[YoofiTT96]

Description

A pattern may declare nodes and relationships under items as well as prefixItems. The documentation did not say so. The agent authoring guide described prefixItems in sixteen places and never mentioned items. The user pages taught the positional model only, and no page showed an options relationship in JSON.

Part of #2859. This PR does not document an empty answer to a decision. On main, calm validate crashes on that architecture, and #3270 is still settling which rule applies. That text follows #3270.

What the user documentation gains

• core-concepts/patterns.md. The pattern template offers an optional cache and message queue in items, and explains prefixItems, minItems, items and maxItems one by one. A new section compares the three ways a pattern can say "optional", and explains the options relationship: it is the fifth relationship type, it connects nothing, and the architecture keeps the decision.
• Tutorial 17. A new step validates an architecture without a candidate, with a candidate, and with a node that the pattern does not list.
• working-with-calm/cli.md. A new subsection says what a choice can name.

What the authoring guide gains

A worked catalogue example, a table that chooses between prefixItems and items by obligation, and five rules for items. A decision stays in relationships.prefixItems, and calm generate builds an items member only when a selected choice names it.

How the examples were checked

Every result the pages state was run with the real CLI. For the core-concepts page, I extracted the JSON blocks from the page and ran them: the template generates and validates with no errors or warnings, and the template with the decision added as the text says generates and validates for no choice, one choice and both choices.

That check found one gotcha. Without "type": "object" on relationship-type, calm generate omits the decision from the architecture. The page says to keep it.

Type of Change

• 🐛 Bug fix (non-breaking change which fixes an issue)
• ✨ New feature (non-breaking change which adds functionality)
• 💥 Breaking change (fix or feature that would cause existing functionality to not work as expected)
• 📚 Documentation update
• 🎨 Code style/formatting changes
• ♻️ Refactoring (no functional changes)
• ⚡ Performance improvements
• ✅ Test additions or updates
• 🔧 Chore (maintenance, dependencies, CI, etc.)

No code changes.

Affected Components

• CLI (cli/)
• Schema (calm/)
• CALM AI (calm-ai/)
• CALM Hub (calm-hub/)
• CALM Hub UI (calm-hub-ui/)
• CALM Server (calm-server/)
• CALM Widgets (calm-widgets/)
• Documentation (docs/)
• Shared (shared/)
• VS Code Extension (calm-plugins/vscode/)
• Dependencies
• CI/CD

Commit Message Format ✅

docs: document items catalogues in pattern authoring and user guides
docs: address PR #3114 review feedback
docs(docs): remove the empty-answer text that depends on #3270

Testing

• I have tested my changes locally
• I have added/updated unit tests
• All existing tests pass

The examples were validated and generated with the CLI, as above. The Docusaurus site builds with onBrokenLinks: 'throw'.

Checklist

• My commits follow the conventional commit format
• I have updated documentation if necessary
• I have added tests for my changes (if applicable)
• My changes follow the project's coding standards

🤖 Generated with Claude Code

[markscott-ms]

Review of the docs. Two items are critical:

🔴 Critical — merge order with #3270. cli.md documents an empty anyOf answer as valid. #3270 makes this work, and it is still open. If this PR merges first, a user who passes --option-choices '{"optional-components":[]}' gets a calm validate crash on the generated architecture. Only the PR body states the merge order. Please merge #3270 first, or remove the empty-array text until it lands.

🔴 Critical — unwanted CLI release. Commit 5be24e6 uses docs(calm-ai). cli/.releaserc.json has a {type: docs, scope: calm-ai, release: patch} rule. If the branch merges without a squash, this commit publishes a CLI patch release with no code change. Squash-merge with the PR title, or reword the commit to docs: or docs(docs).

The inline comments are smaller accuracy issues in the instructions.