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

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

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

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