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 by this repository's authoring convention. title supplies the page title and default navigation label; metadata may override navigation labels. description supplies page metadata and searchable text. Contents summaries are authored separately. No empty descriptions.

Navigation contract

• Is every new page listed in the nearest index.md's ## Contents? A page without a local-map link is harder to discover in source, even if its route or sidebar entry still exists. Add the link in the same commit, and check sidebar metadata separately. Cross-directory sidebar references are allowed; they do not remove the physical directory's mapping responsibility.

• 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 --dir documentation dev or pnpm --dir documentation build regenerate the manifest.

Build

• Does cd documentation && NEXT_PUBLIC_BASE_PATH=/skills 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, not proof that browser-only diagrams, images, or search work. Inspect the exported site at the production base path as well as the preview.

• Does cd documentation && pnpm exec oat docs check --target-dir . report no errors? It checks frontmatter, ## Contents maps against sidebar metadata, links, inline commands, Mermaid accessibility and page size. Review its warnings as well.

• Does pnpm --dir documentation run docs:format:check pass? Format only the changed authored files with the repository formatter; do not turn a docs edit into a repository-wide formatting change.

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 & Visuals for the supported set. Check diagrams against implementing source and inspect both themes at the actual display size.