Agent notes
How to write and update pages in the public docs so they match the shipped product.
The public docs site renders the root docs/ folder. The site lives under /docs on each brand's app host. AI agents read the same pages through /llms.txt, /llms-full.txt, the per-page .md URLs and the docs MCP server at /docs/mcp, so every page has to be accurate on its own.
Agents tend to rewrite an old page or copy PRODUCT.md, and both drift from the product. Write each page from the source instead:
PRODUCT.md section for intent and vocabulary.apps/saas/features/<domain>/: the *-actions.ts and *-queries.ts files and the component names.apps/saas/app/[locale]/[brand]/(app)/[orgSlug]/ (or admin/) for the real paths and tabs.packages/identity/src/permdock/permissions.ts and the role grants in policy.ts. The PermDock policy is the source of truth.apps/api/app/api/v1/ and the MCP allowlist mcpToolDefinitions in packages/api-client/src/mcp.ts.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.
Use these H2 sections in this order and leave out the ones that would be empty:
quote.send or platform.user.manage./openapi/... pages.The frontmatter description is one specific sentence. llms.txt is built from it, so it must say what the page covers.
Cards belongs only on index.mdx. Use Markdown tables for reference data./product/quotes, without a /docs prefix. The docs app is served under basePath: "/docs" and Next adds the prefix to rendered links. Code that builds absolute URLs, fetches or Markdown output uses docsPath() from apps/docs/lib/base-path.ts instead.https://app.centrakit.com/api/v1/..., https://app.centrakit.com/mcp and https://app.centrakit.com/docs/.... The api. and docs. subdomains no longer exist, so do not write them outside historical notes.meta.json. tests/integration/docs/docs-tree.test.ts fails on orphan pages, missing frontmatter and broken internal links.apps/docs/next.config.ts.Last updated on