Writing docs

The public docs site renders the root docs/ folder. AI agents read the same pages through /llms.txt, /llms-full.txt, the per-page .md URLs and the docs MCP server, so every page has to be accurate on its own.

Describe shipped behavior from codeCopy Anchor Link

Agents tend to rewrite an old page or copy PRODUCT.md, and both drift from the product. Write each page from the source instead:

1. Read the matching PRODUCT.md section for intent and vocabulary.
2. Read the feature slice in apps/saas/features/<domain>/: the *-actions.ts and *-queries.ts files and the component names.
3. Read the route folder under apps/saas/app/[locale]/(app)/[orgSlug]/ (or admin/) for the real paths and tabs.
4. Read the permission entries in packages/identity/src/rbac/features.ts. That registry is the source of truth, not permissions.ts.
5. Read the API routes under apps/api/app/api/v1/ and the MCP allowlist mcpToolDefinitions in packages/api-client/src/mcp.ts.
6. Confirm labels, tabs and flows in the running app with agent-browser on https://app.localhost and the seeded logins, or read the English strings in apps/saas/translations/en.po.

Describe only what ships. For a roadmap item, write one line that starts with "Not yet available" instead of prose about what the feature is intended to do.

Page templateCopy Anchor Link

Use these H2 sections in this order and leave out the ones that would be empty:

1. Overview: what the feature is and the route where it lives.
2. Key concepts: entities, statuses and lifecycle stages.
3. How-to sections for the main flows, one H2 or H3 per task.
4. Permissions: the organization.* or system.* keys that gate the feature.
5. Automation and AI: workflow triggers, MCP tools and AI actions.
6. API: the REST resources, with links to the generated /openapi/... pages.
7. Related pages.

The frontmatter description is one specific sentence. llms.txt is built from it, so it must say what the page covers.

ConventionsCopy Anchor Link

• Prefer plain Markdown over MDX components. Cards belongs only on index.mdx. Use Markdown tables for reference data.
• Link to other pages with root-relative paths such as /product/quotes. The docs app is mounted at the root, so never prefix /docs.
• Every page must be listed in its folder's meta.json. tests/integration/docs/docs-tree.test.ts fails on orphan pages, missing frontmatter and broken internal links.
• When you remove or rename a page, add a redirect in apps/docs/next.config.ts.
• Follow the repo writing rules: complete sentences, no em dashes or arrow chains in prose, no emojis or exclamation marks, and none of "simply", "seamless", "robust" or "leverage".