Canonical Docs Workflow
Canonical docs under docs/features/ are the source of truth for product behavior, repository initiatives, and cross-cutting workstreams that need durable requirements. Support-dev summarizes them for readability.
Before Changing Behavior
Section titled “Before Changing Behavior”- Open the relevant
docs/features/<initiative>/spec.md. - Read related ADRs in
docs/features/<initiative>/decisions/. - Check stories and Gherkin tests under the same initiative directory.
- If the feature has a support-dev page, update the support-dev mirror only after the canonical source is clear.
- If docs and code disagree on product, privacy, security, retention, customer-cluster behavior, or external contracts, stop and get alignment before extending the implementation.
Where Things Belong
Section titled “Where Things Belong”| Content | Location |
|---|---|
| End-state requirements | docs/features/<initiative>/spec.md |
| User-facing acceptance criteria | docs/features/<initiative>/stories/*.stories.md |
| Gherkin scenarios | docs/features/<initiative>/tests/*.feature |
| Architecture decisions | docs/features/<initiative>/decisions/ADR-*.md |
| Contributor support summary | apps/support-dev/src/content/docs/ |
Support-Dev Mirror Rules
Section titled “Support-Dev Mirror Rules”- Keep pages concise.
- Say what is implemented versus planned.
- Link to canonical sources instead of copying long spec prose.
- Use screenshot placeholders when visuals are useful but final design screenshots are not ready.
Canonical Sources
Section titled “Canonical Sources”docs/AGENTS.mddocs/features/README.mdapps/support-dev/AGENTS.md