About these docs
For: Contributors changing documentation.
Documentation lives beside the product code in docs-site/, so behaviour and its explanation can change in the same pull request. Read the shared writing standard and documentation skill before drafting or restructuring a page. The site is built with Docus and published as static files.
Change a page
Changing the docs requires access to the private repository; public source downloads are coming soon.
In your checkout, read the shared writing voice in brand/writing.md
and the documentation skill in .agents/skills/oz0-docs/SKILL.md.
Codex and Claude load the same standard through their repository skill entries.
Choose a reader and one purpose: tutorial, how-to, explanation or reference. Record the reader in audience,
the purpose in doc_type, and put a short For: line before the first paragraph. Put prerequisites and
warnings before the action they affect, and show how to verify the result.
Give a long explanation a named companion page. Keep technical limits, permissions and failure behaviour exact when shortening paragraphs. Preserve the topic's URL as a useful index and link old section fragments to the new detail. Keep executable examples with the context needed to run them.
Pages are Markdown in docs-site/content/, one folder per section, in the order of the sidebar: Get started, Concepts, Run, Build (with Plugins, Parts and Apps on OZ), Improve, Govern, Fleet, Spend, Admin, Reference and About. Each folder's .navigation.yml holds its title.
Numbered prefixes set the order and are removed from the address: 07.fleet/02.cluster/00.index.md is /fleet/cluster. Use at least two digits, because names sort as text and 10. would come before 2.. A folder's index page uses the folder's address; the site's index.md is the home page.
cd docs-site
npm ci
npm run dev # http://localhost:3001
Move or rename a page
A page's address normally comes from its folder and its name, so moving a page or renaming it changes its address. Generated CLI pages set an explicit path because commands can use names that the site reserves, such as index. Change those paths through the generator.
Every address a page ever had keeps answering: add a row to docs-site/redirects.yaml with the old address and the new one,
moves:
- from: /monitor/cost-and-usage
to: /spend/cost-and-usage
and the build writes a permanent redirect (301) for the page, for its Markdown copy (/monitor/cost-and-usage.md) and for its /raw/ copy into the site's _redirects, which Cloudflare Pages applies. A page split in two keeps one row, to the page its first heading is on now, and names the headings that went to the other page under anchors:. Then rewrite the links to the old address, in the pages and in the rest of the repository:
scripts/check-docs-redirects.py --fix # every link to a moved address, in pages, code and repository docs
make e2e-docs-redirects # build the site and follow every redirect, as Cloudflare Pages does
make lint runs scripts/check-docs-redirects.py: it fails when a page moved without a row, a row points at no page, an old address is a page again, a page links a moved address, a file of the repository names a page file that is not there, or a page sits in a folder that is no section.
Generated pages
The CLI reference is generated from the binaries' own help text. Never edit it by hand; change the command's help in Go and regenerate:
make build
cd docs-site && npm run reference
CI regenerates it and fails if it is out of date.
Build the site
cd docs-site && npm run generate # the static site in .output/public
The build renders every page, and fails when one does not render or links to a page that does not exist, so a broken page never ships as an error page. The error names the page and the page that links to it.
Check pages against the code
Two checks keep the pages true to the binaries:
make build
scripts/check-docs.py # every page's commands and flags, links and anchors, and make targets
make e2e-docs # the check above, then the getting-started pages run as written
check-docs.py reads every command line of orchestrator-zero and orchestrator-zero-node in a page's code blocks and code spans, and fails on a subcommand or a flag the binary does not have, a link to a page or a heading that does not exist, and a make target the Makefile lacks.
make e2e-docs then runs the code blocks of the quickstart, the first plugin and joining nodes, in order and in the terminals the pages name, against a dev server whose gateway talks to a stand-in for the model provider. A block runs only when an HTML comment marks it, on the line before it; readers do not see the comment:
<!-- e2e terminal=2 expect="COST" -->
```bash [Terminal 2]
oz0 run hello-agent "Say hello to Ada"
```
The marker's options are in scripts/docs-runner.py: terminal, background (start it and wait for a text), expect, wait-for, file (write the block to the file its title names), capture and sub (replace an example value, such as a token, with a real one). When you change a marked page, run make e2e-docs; when you add a getting-started page, mark its blocks and add it to scripts/e2e-docs.sh.
Every page as Markdown
Every page is also published as Markdown at its own address plus .md: this page is at /about/contributing-docs.md, and the landing page at /index.md. The same text is under /raw/ (which llms.txt and sitemap.md link to), and llms-full.txt is every page's text in one file. The Copy as Markdown button beside a page's title copies it; its menu opens it (View as Markdown) or copies its address (Copy Markdown link). The docs are static files, so the server cannot pick Markdown from a request's Accept header: ask for the .md address.
The copies are made when the site is built, by the renderer that writes llms-full.txt, so a page, its copy and its part of llms-full.txt never disagree. After prerendering, docs-site/modules/markdown-twins.ts copies each /raw/ file beside its page's HTML, and docs-site/public/_headers serves .md files as text/markdown on hosts that read it, such as Cloudflare Pages. Before the renderer writes a page, docs-site/server/utils/markdownTree.ts escapes text that would read as an HTML tag, such as \<name\> in a sentence or team:<name> in a table's code, and keeps the backticks of code inside bold text.
make e2e-docs-twins
builds the site and fails when a page has no copy, a copy differs from its /raw/ file or from its part of llms-full.txt, or a copy holds an HTML tag the page does not (only the page's own components, the HTML it writes itself and tables are allowed). With Playwright installed (npm ci in web/), it then uses the button in a browser, by keyboard alone, in both themes.
When it names a tag such as <name>, the page's source has text MDC reads as markup: write it in a code span, or escape it as \<name\>.
Rules
- Every page answers one task. Commands can be copied and run as written, and on the getting-started pages a test does just that.
- Pages about planned features start with a notice saying so.
- Plain words, active voice, sentence-case headings.
The project's internal documents (the plan, ADRs and the build journal) are in docs/ and are not published here.