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

Navigation in this site is authored, not configured. There is no hand-rolled sidebar YAML and no separate table of contents to maintain. Instead:

• 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.

If a page is not listed in some ## Contents, it is effectively invisible to the navigation tooling. When you add a page, the same commit must add its link to the nearest index.md.

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 && oat docs generate-index --docs-dir docs --output index.md

This runs automatically on the predev and prebuild npm scripts, so a normal pnpm dev or pnpm 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 authored maps are the per-directory ## Contents sections. The generated root manifest reflects the file tree; the ## Contents sections express intent. When you change structure, edit the ## Contents sections and let the generator refresh the manifest — never the other way around.

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 if the new page should appear in a specific sidebar position (see Sidebar order).

Restructuring navigation

1. Make the change in the authored ## Contents sections of each affected index.md. Those are the source of truth.
2. When moving a page between directories, update both the source and destination ## Contents in the same commit so history never contains a broken intermediate state.
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:

{
  "pages": ["index", "authoring", "markdown-features", "review-checklist"]
}

Pages not listed still resolve, but their sidebar position is left to the default. When you add a page that needs a specific slot, add its slug to the parent meta.json.

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 dev starts the Next.js dev server with hot reload. The predev script regenerates the root manifest first, so the navigation you preview matches the current file tree.

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

cd documentation && pnpm build

pnpm 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 build is the bar for a docs change. Run pnpm run docs:format:check to verify Markdown formatting, and pnpm run docs:format to apply it.

Agent-instruction surfaces

Three distinct files carry agent and contributor instructions; keep them in their lanes:

• documentation/AGENTS.md — the docs-app agent runtime contract. The authoritative source for how agents add pages, restructure nav, run audit/apply, and avoid clobbering generated files. This section of the docs defers to it.
• documentation/docs/contributing.md — the scaffold's human-facing contributing page (navigation contract summary, supported Markdown features, local workflow). It is rendered in the site.
• 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, update the surface that owns it and reconcile the others in the same change rather than letting them drift.