The docs site

make docs                       # serve on :8001 (DOCS_PORT=8002 if it is taken)
make docs-build                 # --strict; CI runs this, a dead link fails the build

docs/ is both the published site and the repository's own engineering notes — one copy, on purpose. A second copy of "how a capability works" written for outsiders is a copy that disagrees with the one contributors read. So: do not write a page that restates another page. mkdocs.yml's nav decides what an outside reader meets first; nothing is duplicated for them.

The same principle governs these skills. A skill routes to the doc and adds the operational layer; it does not paraphrase the doc.

Where to write when behaviour changes

The table in AGENTS.md under ## Documentation maps topic → page. Keep it current when you add a page.

Three things that silently render wrong

These have all shipped broken. Check the rendered page, not the Markdown.

Mermaid needs the custom fence. Without custom_fences on pymdownx.superfences, a ```mermaid block goes to the syntax highlighter and the reader gets the graph's source in a code box. Configured now — do not remove it.

Verifying is harder than it looks: Material renders into a closed shadow root, so the div.mermaid in the DOM is empty and querySelector('.mermaid svg') finds nothing. That is indistinguishable from a broken render. A screenshot is the only honest check. Mermaid itself loads from unpkg.com at page-view time, so diagrams do not render offline or behind a strict CSP.

Icons need pymdownx.emoji. Without the twemoji index, :material-download:{ .lg .middle } reaches the page as that literal string — the home page's grid cards rendered their own source for a while.

--strict does not validate anchors. A #fragment that matches no heading passes the build. Check fragments by hand, or with a script over the headings.

Search and link previews

scripts/mkdocs_hooks.py writes what a search result or a shared link reads from a page's head; Material writes only the title, description, canonical and hreflang.

• seo_title in front matter replaces the <title> - at most 60 characters, starting with the page's own name. title stays short because the nav uses it.
• description is the meta description and the card text - at most 160 characters. A page without one falls back to site_description.
• Every page gets Open Graph and Twitter tags, with docs/assets/social-preview.png as the image from the site root in every locale.
• A ## Frequently asked questions section becomes FAQPage structured data: each ### inside it is a question, the text up to the next one its answer. A translation must pin { #frequently-asked-questions }, which is how the hook finds the section in every language. Answers are published as plain text, so keep each one self-contained. backend/tests/test_mkdocs_seo.py covers the extraction.

Translate seo_title and description with the page; they are read by people searching in that language.

mkdocstrings

The API reference is generated from docstrings rather than written twice — this codebase puts its reasoning in docstrings, so a hand-written reference would be a worse copy of something already there.

The collector is static, and app/services/, app/api/ and app/worker/ have no __init__.py, so it cannot traverse into them: ::: app.services.foo fails the build. Reference those from prose with a source link until those packages are made explicit.

Because the reference is generated: when behaviour changes, fix the docstring. A prose page that repeats it will drift.

The seven tabs

AgenticOS · Features · Learn · Reference · Resources · About · Release Notes — FastAPI's arrangement, organised by what the reader is doing rather than by what a page is.

Learn is a sequence, not a bag: Get started → Build the agent → Put it in front of people → Keep it under control → the recipes. A page added there belongs at a position.

Files stay flat in docs/. The nav does the grouping. Those paths are named in AGENTS.md, in these skills, in scripts/docs_drift.py and in backend docstrings, so moving a file to get a prettier URL invalidates all of them.

release-notes.md is CHANGELOG.md, substituted at build time by scripts/mkdocs_hooks.py. That is a hook rather than a snippets include because snippets expand after every hook, so nothing could reach the included text to rewrite its docs/-prefixed links — and --strict fails on the docs/docs/… they resolve to.

Two pages are in the repository and not on the site

docs/ROADMAP.md and docs/about/design.md sit in exclude_docs beside design/, plans/ and audits/. Delivery state written in board shorthand and the six decisions a contributor needs before their first change are read by somebody who has already chosen to work on this; published, they put an internal status report in a tab a prospective user meets first.

A published page that links to either one fails --strict, because an excluded file is not built and the link resolves to nothing. Link them by GitHub blob URL instead - docs/about/index.md and docs/reference/capabilities.md are the two that do.

Adding a page

1. Write it in docs/ (or docs/howto/, docs/reference/).
2. Add it to nav in mkdocs.yml, at the position it belongs at — a page outside the nav is a build warning under --strict.
3. Cross-link it from the pages a reader arrives from, and from AGENTS.md's table.
4. make docs-build and check the anchors.

Voice

Use second person and present tense for user instructions. Explain behaviour and relevant reasons; distinguish verified facts from uncertainty. Choose prose, lists or tables according to what helps the reader.

• Use sentence case headings, preserving product names and acronyms.
• Keep paragraphs within the limit enforced by scripts/check_docs_paragraphs.py. Split by idea; use an admonition when a reader needs a warning before acting.
• Add a recap only when it helps a reader retain the decisions from a long page. Do not repeat short pages or force a fixed number of bullets.

Icons

app/core/catalog/icons/<name>.svg is served by GET /catalog/icons and drawn for a catalog entry or provider whose id matches and which no compiled-in icon set carries. The file's own colours are ignored — it renders as a currentColor silhouette, unlike the compiled-in marks, which carry their brand's colour where it reads on both themes. See icons/README.md.