Authoring

How to add, move, and restructure pages without breaking navigation. The rules below are the same ones documentation/AGENTS.md enforces for agents; this page states them for anyone editing the docs by hand.

The navigation contract

Three surfaces serve different readers and must stay aligned:

• Every content directory has an index.md. It is the directory's map page.
• Every index.md has a ## Contents section — a bulleted list linking to that directory's leaf pages and child directories. This is the machine-readable local map.
• Leaf pages do not need a ## Contents. Only directory index.md files carry one.
• meta.json controls the rendered sidebar's ordering and grouping. It is hand-authored alongside the local map, not generated from ## Contents (documentation.navOwner is hand-authored); do not run a writing oat docs nav sync.
• Sidebar groups may borrow canonical pages from elsewhere. Use native relative folder references or link entries rather than copying a guide or moving it only to match the sidebar. Local maps still cover their immediate physical children and may include additional cross-directory destinations.
• Capability headings inside ## Contents are allowed. They organize the authored map; meta.json separators define the rendered sidebar groups. oat docs check compares each meta.json with its local map, so keep their membership, order and groups coherent.
• documentation/index.md is a generated file-tree inventory. It is not the source of sidebar order and must not be edited by hand.

A page omitted from ## Contents is missing from the authored local map even if Fumadocs still resolves its route. Add its link to the nearest index.md and reconcile the directory's sidebar metadata in the same change. See Sidebar order for the supported metadata format; do not add a parallel navigation configuration.

overview.md files are deprecated; use index.md with a ## Contents section.

The .md-link convention

Write ## Contents links with their .md suffix and as relative paths:

• [Page Title](page.md) for a leaf page in the same directory.
• [Section Title](subdir/index.md) for a child directory.

The @open-agent-toolkit/docs-transforms remark-links plugin normalizes these at build time — it strips the .md for Fumadocs routing and collapses dir/index.md to dir. So the suffixed form both renders correctly and lets an agent (or a grep-based tool) follow the link straight to the source file without inferring the extension. Extension-less links ([Page](page)) break that file-following and diverge from the convention used throughout the site; do not author them.

The generated-index discipline

The root manifest at documentation/index.md is a generated file-tree of the whole docs surface. It is produced by:

cd documentation && pnpm exec oat docs generate-index --docs-dir docs --output index.md

This runs automatically on the predev and prebuild npm scripts, so a normal pnpm --dir documentation dev or pnpm --dir documentation build regenerates it for you. Do not hand-edit documentation/index.md — it carries an autogenerated banner and any manual change is clobbered on the next dev/build. It is a derived artifact, not an authored map.

The local maps express content relationships; meta.json expresses sidebar placement. The generated root manifest reflects the file tree. When structure changes, update the maps and affected metadata, then regenerate the inventory. Regeneration does not repair missing authored links or sidebar entries.

Adding a page

1. Create the Markdown file under docs/ in the directory that best matches the topic. Prefer .md. Reach for .mdx only when the page genuinely needs embedded JSX — a custom component, an interactive widget, a non-default layout. Plain .md is friendlier to agents, linters, and grep.
2. Add frontmatter with at least title and description (see Markdown Features).
3. Add a .md-suffixed link to the page in the nearest index.md's ## Contents.
4. If the page introduces a new subdirectory, give that subdirectory its own index.md with a ## Contents section.
5. Update the directory's meta.json to place the page in the intended sidebar position (see Sidebar order).
6. Regenerate the inventory, check the links, and preview the affected navigation.

Restructuring navigation

1. Make the change in each affected index.md's ## Contents and reconcile its meta.json sidebar order/grouping.
2. When moving a page between directories, update both the source and destination ## Contents and sidebar metadata in the same commit.
3. When reparenting a whole subtree, revisit the moved directory's index.md intro paragraph so its stated scope still matches its new home.
4. Let the generator refresh documentation/index.md; do not edit it by hand.

Sidebar order

Each directory's sidebar ordering is controlled by a meta.json next to its index.md. It lists page slugs in display order, and string entries wrapped in dashes act as section separators:

{
  "title": "Documentation",
  "pagesIndex": "[Overview](/engineering/contributing/documentation)",
  "pages": ["authoring", "markdown-features", "review-checklist"]
}

With an explicit pages list, unlisted pages may still resolve without appearing in that sidebar group. Add each intended entry explicitly. pagesIndex makes the folder label link to its landing page; it does not add a second visible Overview row.

For cross-directory grouping, "../consensus" borrows a sibling folder and "[Collaborative Observer](/user-guide/skills/session-observer-collab)" links to an existing page with a navigation-specific label. These are sidebar references, not redirects or duplicate documents. Use relative .md links in the authored Contents map even when the sidebar uses route-based links.

Local workflow

Work from inside the docs app:

cd documentation
pnpm install      # first time only
pnpm dev          # live preview; runs generate-index via predev

pnpm --dir documentation dev starts the Next.js dev server with hot reload. The predev script refreshes the generated inventory first. The sidebar still follows the authored metadata, so inspect it as well as the file-tree inventory.

Before you push, build the site the way CI does:

cd documentation && NEXT_PUBLIC_BASE_PATH=/skills pnpm build

pnpm --dir documentation build runs prebuild (regenerating the manifest) and then the production Next.js build, which surfaces MDX and rendering errors that the dev server tolerates. A clean pnpm --dir documentation build is the bar for a docs change; inspect changed diagrams and sidebar layout separately. Run pnpm --dir documentation run docs:format:check for the docs-wide formatting check. For a bounded change, use the repository's formatter on only the changed authored pages; do not reformat unrelated docs, generated inventories, or AGENTS.md files.

Run the documentation checker with the docs app's own OAT CLI:

cd documentation && pnpm exec oat docs check --target-dir .

It checks frontmatter, ## Contents maps against sidebar metadata, links, inline commands, Mermaid accessibility and page size. Fix errors before you push and review its warnings.

Agent-instruction surfaces

Agent entry points and detailed contributor references have distinct roles:

• documentation/AGENTS.md — the docs-app agent runtime contract. The concise routing and safety contract for agents. It links here for the detailed authoring workflow rather than duplicating this guide.
• Documentation contribution guides — the shared human/agent reference for authoring, supported Markdown features, and review.
• Root AGENTS.md ## Documentation section — the repo-wide pointer that tells any agent working anywhere in the repo that docs live at documentation/. It routes to the docs-app AGENTS.md.

When a convention changes, reconcile its concise instruction and detailed reference in the same change. Verify factual claims against the app's source and configuration; neither prose surface proves that stale guidance is correct.