@open-agent-toolkit/cli 0.1.21 → 0.1.22

package/assets/skills/oat-docs-bootstrap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-docs-bootstrap
-version: 1.0.1
+version: 1.1.0
 description: Use when bootstrapping a new OAT docs app in a repo. Guides the user through preflight detection, richer input gathering than the raw CLI, `oat docs init` invocation with labeled post-patches for open CLI gaps, build verification, post-scaffold config inspection, and an educational walkthrough. Supports Fumadocs (full path) and MkDocs (lean path with defined minimum contract).
 argument-hint: '<optional-target-dir>'
 disable-model-invocation: true
@@ -646,7 +646,7 @@ Four sub-findings, each with its own gate, target, and idempotency check. All su
 
     ## Generated files
 
-    The root-level `index.md` at `<appRoot>/index.md` is regenerated from `docs/index.md` and its `## Contents` sections on every `predev` / `prebuild`. Do not hand-edit it; edit the authored source under `docs/` instead.
+    For Fumadocs apps, the root-level generated manifest at `<appRoot>/index.md` is regenerated from the Markdown file tree under `docs/` on every `predev` / `prebuild`. Do not hand-edit it; edit the authored source under `docs/` instead, and compare the generated manifest against authored `## Contents` when checking freshness. For MkDocs apps, the derived navigation artifact is the `nav:` section of `mkdocs.yml`, not a root manifest.
 
     <!-- /FP-13 patch -->
     ```
@@ -844,7 +844,7 @@ If the `documentation` section is missing or malformed after a successful CLI in
 For each field in `documentation`, check that the referenced path exists and has the expected type:
 
 - `root`: must be a directory that exists on disk (absolute or resolved-relative to `$REPO_ROOT`).
-- `index`: must be a file that exists on disk (Fumadocs: `<appRoot>/index.md`; MkDocs: `<appRoot>/docs/index.md`). The generated root `index.md` is part of the contract even though it's regenerated every build.
+- `index`: must be a file that exists on disk. For Fumadocs, this is the generated app-root manifest at `<appRoot>/index.md`, regenerated from the Markdown file tree under `docs/`. For MkDocs, this is the authored source root at `<appRoot>/docs/index.md`; generated navigation lives in `mkdocs.yml` `nav:`.
 - `config`: MkDocs only — must be a file that exists on disk (`<appRoot>/mkdocs.yml`). For Fumadocs, this field is absent; no check needed.
 - `tooling.framework`: must match the Input Result `framework`. Mismatch is surprising and indicates drift.
 - `tooling.lint` / `tooling.format`: must match Input Result values.
@@ -928,7 +928,10 @@ Narrate each field actually present in their config (skip fields that are absent
 
 - **`documentation.root`** — the scaffolded app directory. Downstream tools (`oat-project-document`, `oat-docs-analyze`, `oat-docs-apply`) use this to find "the docs" without the user having to tell them.
 - **`documentation.tooling`** — framework + lint + format. `oat-docs-analyze` uses `framework` to pick the right rule set; the tooling values also get echoed into the `## Documentation` section the CLI wrote into root `AGENTS.md`.
-- **`documentation.index`** — the authored `docs/index.md`. This is the content map (not the generated root `index.md` — that's Section B). Tools read this to understand top-level navigation intent.
+- **`documentation.index`** — branch this narration on the inspected `documentation.tooling` and path; do not describe one meaning for every framework:
+  - **Fumadocs:** this should be the generated app-root manifest, usually `<appRoot>/index.md`, after the successful build ran `oat docs generate-index`. Explain that this machine-shaped file is how tools inspect the full Markdown file tree, and that the authored source map the user edits is a separate file at `<appRoot>/docs/index.md` with its own `## Contents`.
+  - **Fumadocs stale path warning:** if the inspected path still points inside `<appRoot>/docs/` after build verification, do not teach that as normal. Surface it as a warning that `oat docs generate-index` did not update `documentation.index` as expected, then point the user to Section B for the generated/authored split.
+  - **MkDocs:** this should point at the configured MkDocs nav/config surface, usually `<appRoot>/mkdocs.yml` and matching `documentation.config`. Explain that the YAML file contains the generated/derived `nav:` block when `oat docs nav sync` is used, while authored `docs/index.md` and nested `## Contents` sections remain the source maps the user edits.
 - **`documentation.config`** (MkDocs only) — path to `mkdocs.yml`. Present for MkDocs because its chrome/nav is YAML-configured; absent for Fumadocs because chrome is code.
 - **`documentation.requireForProjectCompletion`** — the opt-in collected in Step 5e. If `true`, `oat-project-complete` will block project completion until `oat-docs-analyze` reports no open recommendations. Explain whichever value is set on this project.
 
@@ -941,17 +944,18 @@ If `Scaffold Result.rootBuildPatch` is present, narrate it here before moving on
 
 End with: "This config is how every OAT docs tool finds your docs. Editing it by hand is supported — but changes to `root` or `config` paths need to match reality on disk."
 
-#### Section B (both frameworks) — The two `index.md` files
+#### Section B (both frameworks) — Authored source and generated navigation
 
-This section prevents the footgun from FP-13 sub-finding D: users silently hand-edit the generated `index.md` and wonder why their edits vanish on the next build.
+This section prevents the footgun from FP-13 sub-finding D: users silently hand-edit the Fumadocs generated root `index.md` and wonder why their edits vanish on the next build.
 
 Narrate:
 
 - **The authored source** at `<appRoot>/docs/index.md`. This is the file the user edits. It has frontmatter (`title`, `description`) and a `## Contents` section listing direct children of the docs root. It is the top of a fractal: every directory has its own `index.md`, each with its own `## Contents`.
-- **The generated map** at `<appRoot>/index.md` (when Fumadocs — the path differs for MkDocs; use the `documentation.index` path resolved by the Inspector if it differs). Regenerated on every `predev` / `prebuild` by the `oat docs generate-index` command. Machine-shaped: rolls up every `## Contents` section in the tree into a single searchable map that tools consume. **Hand-edits are silently clobbered.**
-- **How to tell them apart when opening a file.** If the file sits inside `docs/`, it's authored. If it sits at `<appRoot>/index.md` (outside `docs/`), it's generated — and when the CLI or Scaffold-integrity FP-13/D.2 wrote the warning correctly, the first line is `<!-- AUTOGENERATED by \`oat docs generate-index\`... -->`.
+- **The Fumadocs generated map** at `<appRoot>/index.md`. Regenerated on every `predev` / `prebuild` by the `oat docs generate-index` command. Machine-shaped: inventories Markdown files with titles and descriptions so tools have a single searchable map. **Hand-edits are silently clobbered.**
+- **The MkDocs derived nav** in `mkdocs.yml` `nav:`. MkDocs does not use a Fumadocs-style generated app-root manifest; its generated/derived navigation boundary is the YAML nav block.
+- **How to tell them apart when opening a file.** If the file sits inside `docs/`, it's authored. If it sits at `<appRoot>/index.md` (outside `docs/`), it's the Fumadocs generated manifest — and when the CLI or Scaffold-integrity FP-13/D.2 wrote the warning correctly, the first line is `<!-- AUTOGENERATED by \`oat docs generate-index\`... -->`.
 
-End with: "Always edit `docs/index.md` and the `## Contents` sections. Never edit the root-level `index.md` — your edits will disappear next build."
+End with: "Always edit `docs/index.md` and the `## Contents` sections. In Fumadocs, never edit the root-level `index.md` — your edits will disappear next build. In MkDocs, treat `mkdocs.yml` `nav:` as derived from authored Contents unless the local workflow says otherwise."
 
 #### Section C (both frameworks) — The `## Contents` contract
 
@@ -962,7 +966,7 @@ Narrate:
 - **Every directory under `docs/` has an `index.md`.** No exceptions, no `overview.md`, no README-as-index. Missing `index.md`s are the first thing `oat-docs-analyze` flags.
 - **Every `index.md` has a `## Contents` section.** The section is a plain Markdown bulleted list of links to the direct children of that directory — both subdirectory `index.md`s and leaf pages.
 - **Link targets use `.md` extensions.** Leaf pages link as `[Title](page.md)`; subdirectories link as `[Section](subdir/index.md)`. The `@open-agent-toolkit/docs-transforms` remark-links plugin normalizes these at build time for Fumadocs routing (`.md` stripped; `dir/index.md` collapsed to `dir`). `.md`-suffixed authored links render correctly **and** let agents follow each link to the target file without path inference — the best of both worlds.
-- **The `## Contents` section is the machine-readable local map.** It's what `oat docs nav sync` reads to regenerate framework nav, what `oat docs generate-index` reads to roll up the tree, and what `oat-docs-analyze` reads to find orphaned pages.
+- **The `## Contents` section is the machine-readable local map.** For Fumadocs, it remains the authored navigation intent that agents maintain and compare against the generated app-root manifest. For MkDocs, `oat docs nav sync` reads it to update `mkdocs.yml` `nav:`. `oat-docs-analyze` reads the same authored source to find orphaned pages and stale generated artifacts.
 - **Anything not listed in `## Contents` is invisible to the tooling.** Adding a Markdown file is not enough — it must also appear under the parent `index.md`'s `## Contents`.
 
 Show the user their own `docs/index.md` `## Contents` as a concrete example (read the file and paste the relevant 5–15 lines). If `patchesApplied` includes an `FP-16` entry with `status: 'applied'`, mention it — the skill rewrote the scaffold's extension-less links to `.md`-suffixed form so agents can follow them. Then note: "That's the pattern. Every directory you create from now on follows the same shape — `.md`-suffixed links, bulleted list, dash-separated summary per entry."
@@ -1007,7 +1011,7 @@ In scope (required — share these):
 - **Material theme provides the default UI.** Light/dark toggle, responsive sidebar, search UI. Config lives under `theme:` in `mkdocs.yml`.
 - **Plugins are pip-installed and named in `mkdocs.yml`.** The scaffold's `requirements.txt` pins the plugins currently wired in. Adding a new plugin = add to both files.
 - **Python environment via `requirements.txt` + `setup-docs.sh`.** The scaffold provides a `setup-docs.sh` that creates a venv, installs `requirements.txt`, and is idempotent on re-run. Use it; the skill assumes you will.
-- **The shared concepts still apply.** The `## Contents` contract (Section C), the two `index.md` model (Section B — note for MkDocs the generated artifact is the `nav:` section of `mkdocs.yml`, not a root `index.md`), and the three agent-instruction surfaces (Section D) all transfer directly.
+- **The shared concepts still apply.** The `## Contents` contract (Section C), the authored-source/generated-navigation model (Section B), and the three agent-instruction surfaces (Section D) all transfer directly.
 
 Deferred (out of scope for this skill — point, don't teach):
 

package/assets/skills/oat-docs-bootstrap/assets/AGENTS.md.template

@@ -12,13 +12,13 @@ This file tells agents how to work inside `{{APP_DIR}}`, the documentation app f
 2. Add frontmatter with at minimum `title:` and `description:`. The title drives nav display and page `<title>`; the description drives search previews, social cards, and sibling summaries. Empty descriptions hurt all three.
 3. Update the nearest `index.md`'s `## Contents` section to include a link to the new page. Use `.md`-suffixed relative links: `[Title](page.md)` for leaf pages, `[Section](subdir/index.md)` for subdirectories. The `@open-agent-toolkit/docs-transforms` remark-links plugin normalizes these for Fumadocs routing at build time (strips `.md`, collapses `dir/index.md` → `dir`), so the suffixed form renders correctly **and** lets agents follow links to the target file without path inference. The `## Contents` section is the machine-readable local map — anything not listed there is effectively invisible to the navigation tooling.
 4. If the new page introduces a new subdirectory, create an `index.md` in that subdirectory with its own `## Contents` section. Every content directory must have an `index.md`.
-5. Run `oat docs nav sync` (or equivalent for this framework) to regenerate any derived navigation artifacts. Derived artifacts never replace the authored `## Contents`; they're generated from it.
+5. Regenerate the derived navigation artifact for this framework. For Fumadocs, run the generated-index command (`{{GENERATE_INDEX_CMD}}`) so the app-root `index.md` manifest reflects the current Markdown file tree. For MkDocs, run `oat docs nav sync` or the local equivalent so `mkdocs.yml` `nav:` reflects authored `## Contents`. Derived artifacts never replace the authored `## Contents`; keep authored maps current and compare generated output against them when checking freshness.
 
 ## When you need to restructure navigation
 
 1. Make changes in the authored `## Contents` sections of each affected `index.md`. That is the authoritative local map.
-2. Do **not** hand-edit generated navigation artifacts. The root-level `index.md` (if present for this framework), `mkdocs.yml` `nav:` (for MkDocs), and any other derived nav file is rewritten on every build.
-3. After editing `## Contents`, run the framework's nav sync command to regenerate derived artifacts.
+2. Do **not** hand-edit generated navigation artifacts. The Fumadocs app-root `index.md` manifest, `mkdocs.yml` `nav:` (for MkDocs), and any other derived nav file is rewritten by the local generation workflow.
+3. After editing `## Contents`, run the framework's generation command to refresh derived artifacts.
 4. If you're moving pages between directories, update both source and destination `index.md` `## Contents` entries in the same commit so the site isn't broken mid-way through history.
 5. If you're reparenting an entire subtree, consider whether the moved directory's own `index.md` needs a revised "scope" paragraph.
 
@@ -44,7 +44,7 @@ This file tells agents how to work inside `{{APP_DIR}}`, the documentation app f
 
 ## What not to do
 
-- **Don't hand-edit generated files.** The root-level `index.md` generated by `{{GENERATE_INDEX_CMD}}` is rewritten on every build. Edits to it are silently clobbered. Edit the authored source (`docs/index.md` and its `## Contents`), not the generated copy.
+- **Don't hand-edit generated files.** For Fumadocs, the root-level `index.md` generated by `{{GENERATE_INDEX_CMD}}` is rewritten on every build. For MkDocs, generated or synchronized navigation lives in `mkdocs.yml` `nav:`. Edits to derived artifacts are silently clobbered. Edit the authored source (`docs/index.md` and its `## Contents`), then regenerate.
 - **Don't default to `.mdx` when `.md` would do.** MDX adds JSX-in-Markdown capability (embedded components), which breaks simple link rewrites, confuses agent tooling, and requires imports that plain `.md` doesn't. Reach for `.mdx` only when a page actually needs a component it can't express in plain Markdown.
 - **Don't author `## Contents` links without `.md` extensions.** Extension-less links (`[Title](page)` instead of `[Title](page.md)`) force agents to infer the target file type, break simple grep-based navigation, and diverge from the convention used throughout `{{REPO_NAME}}`. The build pipeline (`@open-agent-toolkit/docs-transforms` remark-links) strips `.md` for Fumadocs routing — so suffixed authored links render correctly and stay agent-friendly.
 - **Don't invent new navigation conventions outside `## Contents`.** A sidebar config in a framework file, a hand-rolled TOC, a separate nav YAML — all of these diverge from the contract and break the tooling. Extend via `## Contents`.
@@ -60,4 +60,4 @@ This file tells agents how to work inside `{{APP_DIR}}`, the documentation app f
 - `oat-docs-analyze` — read-only audit command.
 - `oat-docs-apply` — apply approved audit recommendations.
 - `oat-project-document` skill — propose evidence-backed doc updates from project artifacts.
-- `{{GENERATE_INDEX_CMD}}` — regenerates the machine-readable root `index.md` from `docs/`. Runs automatically on `predev` / `prebuild`; don't hand-edit its output.
+- `{{GENERATE_INDEX_CMD}}` — for Fumadocs, regenerates the machine-readable root `index.md` from `docs/`. Runs automatically on `predev` / `prebuild`; don't hand-edit its output.

package/dist/commands/init/tools/shared/skill-manifest.d.ts

@@ -17,7 +17,7 @@ export declare const WORKFLOW_TEMPLATES: readonly ["state.md", "discovery.md", "
 export declare const WORKFLOW_SCRIPTS: readonly ["generate-oat-state.sh", "generate-thin-index.sh", "resolve-tracking.sh"];
 export declare const IDEA_SKILLS: readonly ["oat-idea-new", "oat-idea-ideate", "oat-idea-summarize", "oat-idea-scratchpad"];
 export declare const CORE_SKILLS: readonly ["oat-docs", "oat-doctor"];
-export declare const DOCS_SKILLS: readonly ["oat-agent-instructions-analyze", "oat-agent-instructions-apply", "oat-docs-analyze", "oat-docs-apply", "oat-docs-bootstrap"];
+export declare const DOCS_SKILLS: readonly ["authoring-docs", "oat-agent-instructions-analyze", "oat-agent-instructions-apply", "oat-docs-analyze", "oat-docs-apply", "oat-docs-authoring", "oat-docs-bootstrap"];
 export declare const DOCS_SCRIPTS: readonly ["resolve-tracking.sh"];
 export declare const UTILITY_SKILLS: readonly ["create-agnostic-skill", "oat-repo-maintainability-review", "oat-review-provide", "oat-review-provide-remote", "oat-review-receive", "oat-review-receive-remote"];
 export declare const PROJECT_MANAGEMENT_SKILLS: readonly ["oat-pjm-add-backlog-item", "oat-pjm-update-repo-reference", "oat-pjm-review-backlog"];

package/dist/commands/init/tools/shared/skill-manifest.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"skill-manifest.d.ts","sourceRoot":"","sources":["../../../../../src/commands/init/tools/shared/skill-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAKtD,CAAC;AAEF,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE5E;AAID,eAAO,MAAM,eAAe,6xBAgClB,CAAC;AAEX,eAAO,MAAM,eAAe,oFAIlB,CAAC;AAEX,eAAO,MAAM,kBAAkB,6GAQrB,CAAC;AAEX,eAAO,MAAM,gBAAgB,qFAInB,CAAC;AAIX,eAAO,MAAM,WAAW,2FAKd,CAAC;AAIX,eAAO,MAAM,WAAW,qCAAsC,CAAC;AAI/D,eAAO,MAAM,WAAW,yIAMd,CAAC;AAEX,eAAO,MAAM,YAAY,kCAAmC,CAAC;AAI7D,eAAO,MAAM,cAAc,6KAOjB,CAAC;AAIX,eAAO,MAAM,yBAAyB,kGAI5B,CAAC;AAEX,eAAO,MAAM,4BAA4B,sFAK/B,CAAC;AAEX,eAAO,MAAM,0BAA0B,aAAc,CAAC;AAItD,eAAO,MAAM,iBAAiB,6BAA8B,CAAC;AAI7D,eAAO,MAAM,eAAe,2EAMlB,CAAC;AAEX,eAAO,MAAM,eAAe,qCAAsC,CAAC"}
+{"version":3,"file":"skill-manifest.d.ts","sourceRoot":"","sources":["../../../../../src/commands/init/tools/shared/skill-manifest.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,GAAG,SAAS,CAAC;CAClC;AAED,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAKtD,CAAC;AAEF,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAE5E;AAID,eAAO,MAAM,eAAe,6xBAgClB,CAAC;AAEX,eAAO,MAAM,eAAe,oFAIlB,CAAC;AAEX,eAAO,MAAM,kBAAkB,6GAQrB,CAAC;AAEX,eAAO,MAAM,gBAAgB,qFAInB,CAAC;AAIX,eAAO,MAAM,WAAW,2FAKd,CAAC;AAIX,eAAO,MAAM,WAAW,qCAAsC,CAAC;AAI/D,eAAO,MAAM,WAAW,iLAQd,CAAC;AAEX,eAAO,MAAM,YAAY,kCAAmC,CAAC;AAI7D,eAAO,MAAM,cAAc,6KAOjB,CAAC;AAIX,eAAO,MAAM,yBAAyB,kGAI5B,CAAC;AAEX,eAAO,MAAM,4BAA4B,sFAK/B,CAAC;AAEX,eAAO,MAAM,0BAA0B,aAAc,CAAC;AAItD,eAAO,MAAM,iBAAiB,6BAA8B,CAAC;AAI7D,eAAO,MAAM,eAAe,2EAMlB,CAAC;AAEX,eAAO,MAAM,eAAe,qCAAsC,CAAC"}

package/dist/commands/init/tools/shared/skill-manifest.js

@@ -78,10 +78,12 @@ export const IDEA_SKILLS = [
 export const CORE_SKILLS = ['oat-docs', 'oat-doctor'];
 // ── Docs pack ─────────────────────────────────────────────────────
 export const DOCS_SKILLS = [
+    'authoring-docs',
     'oat-agent-instructions-analyze',
     'oat-agent-instructions-apply',
     'oat-docs-analyze',
     'oat-docs-apply',
+    'oat-docs-authoring',
     'oat-docs-bootstrap',
 ];
 export const DOCS_SCRIPTS = ['resolve-tracking.sh'];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.1.21"
+    "@open-agent-toolkit/control-plane": "0.1.22"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",