Add Docs to a New Repo

Use this path when you want to add an OAT-managed docs app and the docs analyze/apply workflow to a repository.

If you are developing inside the OAT repo itself, replace oat ... with pnpm run cli -- ....

What this gives you

a docs app scaffolded with OAT defaults (Fumadocs or MkDocs)
index.md-driven navigation
docs analysis and apply skills installed via the docs pack
a repeatable workflow for finding gaps, verifying claims, and applying docs changes

1. Initialize OAT in the repo

oat init --scope project

This sets up the base OAT structure used by the CLI and installed tool packs.

2. Install the docs workflow skills

Preferred direct path:

oat tools install docs

Interactive path:

oat tools install

Legacy pack-specific path:

oat init tools docs

The docs pack installs oat-docs-analyze, oat-docs-apply, oat-agent-instructions-analyze, and oat-agent-instructions-apply. For this quickstart, the docs pair is the part you need immediately.

3. Scaffold the docs app

Two paths — pick one:

3a. Preferred: the `oat-docs-bootstrap` skill (guided)

/oat-docs-bootstrap

The docs-bootstrap skill wraps oat docs init with a seven-step guided flow: preflight detection (repo shape + existing-setup conflict surfacing), richer input gathering (including a site name distinct from the package name), the CLI invocation itself, labeled post-patches for open CLI gaps, install + build verification, post-scaffold config inspection, and a chunked educational walkthrough.

What the skill adds over the raw CLI:

Preflight + conflict resolution. Detects existing documentation config / docs app dir / root AGENTS.md section and walks a deliberate resolution choice (replace, abort, repair, or deferred second-app) before any mutation.
Richer inputs. Asks for a site name separate from the package name, so createDocsConfig() / layout branding / page metadata all converge on the same display title.
Post-scaffold patches for open CLI gaps. Applied only when capability detection shows the CLI hasn't closed the gap. Each patch is labeled (e.g., ) so it can be removed deterministically when the upstream fix lands:
- FP-11 — Turbopack root for nested-standalone Fumadocs apps (suppresses the multiple-lockfile warning)
- FP-12 — export const metadata = { title, description } in app/layout.tsx (the only thing that populates page <title>, meta description, and Open Graph — DocsLayout.branding.title only renders nav chrome, and createDocsConfig() ignores title / description entirely)
- FP-13 — four scaffold-content fixes (empty per-page description: frontmatter, bare install/build commands missing --filter or cd-prefix for monorepo/nested shapes, false docs:lint claim when lint=none, Node version line that doesn't match the consuming repo's .nvmrc / engines.node)
- FP-15 — writes a task-framed <appRoot>/AGENTS.md bridge file when the CLI hasn't scaffolded one. The bridge is the docs app's runtime agent reference (separate audience from docs/contributing.md)
- FP-16 — rewrites docs/index.md ## Contents links to the .md-suffixed form that @open-agent-toolkit/docs-transforms normalizes at build time (agent-friendlier than extension-less; routes correctly)
- FP-17 — trims docs/contributing.md's "Agent guidance" section to a one-line pointer at the docs-app AGENTS.md, restoring the three-surfaces separation
Build verification. Runs install + build, classifies failures against known patterns, stops on unknown errors rather than guessing.
Config inspection. Reads .oat/config.json back, verifies paths exist on disk, handles the nested-standalone dual-config case, and collects the requireForProjectCompletion opt-in explicitly.
Root-build explanation. When the CLI safely patches a compatible Turbo root build script, the walkthrough explains why the filter was added, shows the diff shape, and documents how to adjust or revert it. When the CLI skips the patch, the walkthrough relays the recommended manual snippet.
Educational walkthrough. Seven sections covering the documentation config, the two-index.md model, the ## Contents contract (with extension discipline), the three agent-instruction surfaces (root AGENTS.md pointer / docs-app AGENTS.md / docs/contributing.md), Fumadocs internals (or MkDocs Minimum Contract), and the OAT docs ecosystem (oat-project-document, oat-docs-analyze, oat-docs-apply).
Optional content kickoff. Hands off to oat-docs-analyze + oat-docs-apply if you want to populate initial repo-specific content immediately.

Capability-gated: every post-patch self-ratchets off as CLI fixes land upstream. The skill's labeled markers () are how you find them later when the CLI catches up.

3b. Direct CLI (deterministic / non-interactive)

oat docs init --app-name my-docs

In interactive mode, you'll be prompted to choose a framework:

Fumadocs — Next.js-based static site with FlexSearch, Mermaid diagrams, dark/light mode, and code copy buttons
MkDocs — MkDocs Material with the OAT contributor contract

Default placement:

monorepo: apps/my-docs
single-package repo: my-docs/ at repo root

You can override the target and framework explicitly:

# Fumadocs (non-interactive)
oat docs init --app-name my-docs --framework fumadocs --yes

# MkDocs (non-interactive)
oat docs init --app-name my-docs --framework mkdocs --yes

Use 3b when you want a fully headless scaffold (CI, automation) and can accept the raw CLI output without the guided post-patches.

For compatible Turbo monorepos, the CLI also patches the repo-root package.json by default so root pnpm build excludes the new docs app and a root build:docs script is available for docs-only builds. Use --no-root-patch to opt out, or --dry-run to preview the diff without writing it.

3a. Migrating from MkDocs (optional)

If you have an existing MkDocs site and want to switch to Fumadocs, use the migration command after scaffolding:

oat docs migrate --docs-dir docs --config mkdocs.yml --apply

This converts MkDocs admonitions to GFM callouts and injects frontmatter metadata. Run without --apply first to preview changes.

4. Start authoring docs with the OAT contract

Core rules:

every docs directory should have an index.md
every index.md should include a ## Contents section
the ## Contents section should map sibling pages and immediate child directories

For MkDocs apps, regenerate navigation after adding or moving pages:

oat docs nav sync --target-dir apps/my-docs

For Fumadocs apps, the docs index is generated automatically via predev/prebuild hooks. You can also run it manually:

oat docs generate-index --docs-dir docs

The generated app-root index.md is machine-owned and now starts with an AUTOGENERATED warning comment. Edit authored pages under docs/, not the generated root index.

5. Analyze the docs surface

Use the skill, not the CLI stub, for the real analysis workflow.

If your host supports slash-skill invocation:

/oat-docs-analyze

Otherwise invoke the skill by name in your agent host.

What oat-docs-analyze checks:

index contract coverage
nav drift
stale or contradicted repo-checkable claims
missing or thin content coverage based on repo features
contributor/setup guidance gaps

6. Review the artifact and apply approved changes

Run the apply skill after analysis:

/oat-docs-apply

oat-docs-apply consumes the analysis artifact, asks for approval, and applies only the approved, evidence-backed recommendations.

Important:

oat docs analyze and oat docs apply are CLI guidance entrypoints
the actual analysis/apply workflow runs through the skills

Typical loop

oat init --scope project
oat tools install docs
oat docs init --app-name my-docs
(optional) oat docs migrate --docs-dir docs --config mkdocs.yml --apply
Author docs with index.md + ## Contents
oat docs nav sync --target-dir apps/my-docs (MkDocs) or oat docs generate-index (Fumadocs)
/oat-docs-analyze
/oat-docs-apply
Repeat as the codebase changes

On this page