Documentation contributions
The documentation site lives in apps/docs in the canonical monorepo. Product behavior and documentation now change together in one pull request.
What good documentation does
Every guide should help a reader complete a concrete task or form an accurate mental model. Prefer tested commands, source-backed behavior, small complete examples, explicit role and tenancy assumptions, and links to the next likely task.
Avoid documenting planned behavior as shipped behavior. If a capability is experimental, say so where the reader first encounters it.
Content structure
Documentation pages are Markdown files under content/. Numeric prefixes control order but are removed from public routes.
content/
├── 1.getting-started/
├── 2.architecture/
├── 3.modules/
├── 4.reference/
├── 5.operations/
├── 6.guides/
└── 7.contributing/
Each page needs a clear title and description in frontmatter. Add an icon only when it improves navigation scanning.
Preview locally
pnpm install
pnpm dev
Before opening a pull request, run:
pnpm test:docs
pnpm lint
pnpm typecheck
pnpm test:e2e
test:docs checks required contributor metadata, internal documentation links, repository configuration, and the MCP documentation catalog. test:e2e builds the production site and checks the contributor journeys, accessibility, both color themes, and narrow viewports. Also inspect changed code blocks and task-specific interactions. Review /llms.txt, /llms-full.txt, and the raw Markdown route for the changed page so AI-facing output stays useful.
Every maintained page has an Edit page link to its source and a visible Report a docs issue action. Keep githubPath aligned with the file path so the edit link remains accurate.
Documentation feedback is tracked in the public documentation repository beside the Markdown source and its documentation issue form. The report action prefills the affected page and the exact Customer Portal source revision against which the documentation was verified, giving maintainers reproducible context without mixing writing problems into the product backlog.
Product bugs, feature requests, and module proposals still belong in the Customer Portal repository. The repository URLs, documentation branch, feedback repository, and verified product commit are deployment configuration in nuxt.config.ts. Update the product commit whenever a documentation review moves to a newer Customer Portal revision; do not silently describe behavior from a moving branch while displaying an older verification pin.
Keep docs synchronized
When a product pull request changes a public contract, environment variable, route family, feature action, or contributor workflow, update the relevant documentation in the same release cycle. Cross-repository pull requests should link to one another so reviewers can verify both sides.