Review Checklist

Walk this checklist before committing any change that adds, moves, renames, or restructures pages in this docs app. Each item is a prompt, not a bureaucratic gate — the goal is to catch the common failure modes where a page is added but never linked, a generated file is hand-edited, or the build is left red.

Frontmatter

• Does every new or changed page have title and description? Both are required. title drives the sidebar label and <title>; description drives search previews, social cards, and ## Contents summaries. No empty descriptions.

Navigation contract

• Is every new page listed in the nearest index.md's ## Contents? A page that isn't in some ## Contents is invisible to the navigation tooling. Add the link in the same commit.

• Did you add an index.md for any new subdirectory? Every content directory needs an index.md with its own ## Contents.

• For moved pages, are both the source and destination ## Contents updated in this commit? History should never contain a broken intermediate state.

Links

• Are ## Contents links .md-suffixed and relative? Use [Page](page.md) for leaf pages and [Section](subdir/index.md) for child directories. The remark-links transform strips .md at build time; extension-less links break grep-based navigation and diverge from the convention.

• Do all links resolve? Click through new and changed links in the local preview, or confirm the targets exist on disk. A .md link that points at a missing file renders as a dead route.

Generated manifest

• Did you leave documentation/index.md untouched by hand? It is generated by oat docs generate-index on predev/prebuild. Any manual edit is clobbered. If structure changed, edit the authored ## Contents sections and let pnpm dev/pnpm build regenerate the manifest.

Build

• Does cd documentation && pnpm build succeed? The production build catches MDX and rendering errors the dev server tolerates, and its prebuild step regenerates the manifest. A green build is the bar for a docs change.

• Does pnpm run docs:format:check pass? If not, run pnpm run docs:format and stage the result.

Sidebar order

• Is the sidebar order sane? If a new page needs a specific slot, add its slug to the directory's meta.json pages array. Confirm the rendered sidebar reads in a logical order — overview/index first, then pages in a sensible progression.

Accuracy

• Does the content match current repo behavior? Documenting a command, path, or feature? Confirm it exists and behaves as written. Prefer linking to source files and real commands over paraphrasing from memory. Do not claim features this app doesn't render — see Markdown Features for the supported set.