@open-agent-toolkit/cli 0.0.36 → 0.0.38

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

@@ -0,0 +1,63 @@
+# AGENTS — {{SITE_NAME}}
+
+This file tells agents how to work inside `{{APP_DIR}}`, the documentation app for `{{REPO_NAME}}`. It is not bootstrap documentation. If you're looking for how this app was scaffolded, see `docs/getting-started.md` or the root-level `AGENTS.md` section on documentation.
+
+## Purpose and scope
+
+`{{APP_DIR}}` is the documentation surface for `{{REPO_NAME}}`. Humans read the rendered site; agents read the Markdown source and the navigation structure. This file tells agents the conventions that keep both audiences served, and points at the tooling that enforces those conventions. Everything here is about ongoing work inside the docs app — adding, restructuring, auditing, and bulk-editing content.
+
+## When you need to add a new page
+
+1. Create the Markdown file under `docs/` at the directory that best matches the page's topic. Every content directory is an `index.md` map — find the right one before picking a path. **Prefer `.md`** for plain content pages; reach for `.mdx` only when the page actually needs embedded JSX (a custom component, an interactive widget, a specialized layout). Plain `.md` is the default because agents, linters, and grep rules all handle it more reliably than `.mdx`.
+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.
+
+## 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.
+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.
+
+## When you need to audit or bulk-edit docs
+
+1. Use `oat-docs-analyze` to audit the docs surface against the `## Contents` contract and surface gaps, drift, and coverage opportunities. This is read-only; it produces a report artifact under `.oat/repo/analysis/`.
+2. Review the report with the user. The analyze output is a set of ordered recommendations — apply them selectively, not wholesale.
+3. Use `oat-docs-apply` to execute approved recommendations. Apply creates a branch, performs the approved changes, runs nav sync, and optionally opens a PR. It will not make unapproved changes or invent new conventions.
+4. Do not bypass analyze/apply for sweeping content changes. The branch-and-review discipline catches mistakes that would otherwise land silently and accumulate over time.
+
+## When you're unsure where content belongs
+
+1. Start at `docs/index.md` and read its `## Contents` section. That's the top-level map. Follow the link that best matches the topic.
+2. Repeat at each directory level — every `index.md` has its own `## Contents`. Descend until you find the right scope.
+3. If none of the existing sections fit, the content probably belongs in a new subdirectory. Create it with an `index.md` (see "When you need to add a new page").
+4. If in doubt, match existing siblings' style and depth rather than inventing a new pattern. Consistency across neighboring pages matters more than exact placement.
+
+## When you need project-level documentation updates
+
+1. Use the `oat-project-document` skill during OAT project workflows. It reads project artifacts (`discovery.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`) and proposes evidence-backed doc updates — no speculation, no content that doesn't trace back to the source artifacts.
+2. The skill generates recommendations; you approve them before they land. Treat it like analyze/apply but scoped to a single project's documentation delta.
+3. Do not hand-write project-derived docs that bypass this flow. Bypassing means future runs of the skill will re-surface the same content as "missing" because the provenance chain is broken.
+
+## 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 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`.
+- **Don't bypass `oat-docs-apply` for bulk content changes.** The analyze/apply flow exists to catch mistakes. Bulk edits done by hand or by a one-off script skip the safety net and often regress something unexpected.
+- **Don't create `overview.md` files.** They're deprecated in favor of `index.md` with a `## Contents` section.
+- **Don't edit the scaffolded `{{SITE_NAME}}` value in isolation.** The site name flows to multiple files (layout branding, metadata, page headings). If you're renaming the docs site, update all locations in the same commit or you'll get inconsistent chrome.
+
+## Reference
+
+- `docs/getting-started.md` — first-run setup instructions for contributors joining this docs app.
+- `docs/contributing.md` — authoring conventions (frontmatter requirements, Markdown features like GFM alerts / mermaid / code blocks, nav contract summary).
+- Root `AGENTS.md` `## Documentation` section in `{{REPO_NAME}}` — repo-wide pointer telling any agent "docs live at `{{APP_DIR}}`."
+- `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.

package/assets/skills/oat-project-document/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-document
-version: 1.2.0
+version: 1.3.0
 description: Run when implementation is complete and documentation needs updating. Analyzes project artifacts to produce documentation update recommendations, then applies approved changes before project completion.
 argument-hint: '[project-path] [--auto]'
 disable-model-invocation: true
@@ -195,9 +195,9 @@ These will be verified against actual code in Step 3.
 - Quick-mode projects may lack spec.md and design.md — extract what's available
 - If only plan.md exists (no implementation.md), the project may not have started implementation yet — still proceed, but note that documentation recommendations will be based on planned work rather than verified implementation
 
-### Step 3: Verify Against Code
+### Step 3: Verify Against Code and Build a Capability Inventory
 
-Read source files referenced in artifacts to confirm what actually shipped.
+Read source files referenced in artifacts to confirm what actually shipped, then do a targeted capability-discovery pass so the skill can catch newly introduced documentation surfaces rather than only updating already-documented ones.
 
 **For each referenced source file:**
 
@@ -211,11 +211,31 @@ Read source files referenced in artifacts to confirm what actually shipped.
 
 - Add code-verified details that artifacts didn't capture
 - Note any discrepancies between artifacts and code (informational — include in delta plan as context, not as blocking issues)
+- Organize the verified implementation into **capability areas** (for example: new app surface, CI/CD pipeline, release automation flow, deployment target, integration surface, CLI/config workflow)
+
+**Targeted capability discovery pass:**
+
+After verifying artifact-referenced files, inspect the strongest adjacent signals for newly shipped capability surfaces even when the exact docs target does not already exist.
+
+Prioritize evidence from:
+
+- new apps/packages/directories called out by the artifacts
+- workflow/config files tied to shipped behavior (`.github/workflows`, release configs, deploy configs, mobile build/release files, etc.)
+- entrypoints, route registration files, service modules, and schemas that define user- or operator-facing behavior
+- package manifests and scripts that expose new setup, release, or operational workflows
+
+For each significant capability area, capture:
+
+- capability name
+- concrete repo evidence proving it shipped
+- likely audience (`developer`, `operator`, `integrator`, `end user`)
+- whether the capability represents a new docs surface versus an addition to an existing surface
 
 **Scope control:**
 
-- Focus on files directly referenced in artifacts — don't scan the entire codebase
-- If artifacts reference many files (>20), prioritize: new files first, then modified files with the most changes
+- Start with files directly referenced in artifacts, then inspect only the highest-signal adjacent files needed to understand the shipped capability areas
+- Do not scan the entire codebase blindly; stay anchored to the implementation areas surfaced by the project artifacts
+- If artifacts reference many files (>20), prioritize: new files first, then modified files with the most changes, then only the adjacent files needed to confirm docs impact
 - Read file contents, not just check existence — the skill needs to understand what the code does to make good documentation recommendations
 
 ### Step 4: Discover Documentation Surfaces
@@ -228,6 +248,8 @@ Scan the repository for all documentation and instruction surfaces.
    - Read the docs tooling config (e.g., `$DOCS_CONFIG`) to understand nav structure
    - List all files in `$DOCS_ROOT` recursively
    - Read existing docs files that could be affected by the project
+   - Identify the parent section or directory where each uncovered capability area would naturally live
+   - Note when no existing page or directory is a good fit — this is a strong signal for a `CREATE` recommendation, not a reason to force the content into an unrelated existing page
 
 2. **Root README.md:**
    - Always check — read current content
@@ -270,7 +292,38 @@ Scan the repository for all documentation and instruction surfaces.
 
 Compare "what was built" (from Steps 2-3) against "what's documented" (from Step 4) to produce recommendations.
 
-**5a. Documentation surface assessment:**
+**5a. Capability coverage assessment (required):**
+
+Before recommending file-level edits, evaluate coverage for each significant capability area in the "what was built" model.
+
+For each capability area, classify the documentation state as:
+
+- **adequately covered** — existing docs already explain the shipped behavior accurately
+- **thin coverage** — the area is mentioned, but important setup, workflow, or usage details are missing
+- **no coverage** — no existing docs surface meaningfully covers the capability
+
+For each capability with **thin coverage** or **no coverage**, determine the best docs home:
+
+- **Expand an existing page** when a clear, discoverable page already owns the topic
+- **Create a new page** when the topic is distinct enough to deserve its own entrypoint
+- **Create a new docs directory** (with `index.md` entrypoint, where that is the local convention) when the shipped work introduces a new top-level capability area with multiple likely subtopics
+
+Bias rules:
+
+- If a docs app exists and the shipped work represents a new major capability area, do **not** default to stuffing the information into `README.md`, `roadmap.md`, or `current-state.md`
+- Examples that often warrant `CREATE` recommendations: new mobile apps, CI/CD and release automation, new deployment targets, new integration surfaces, or new operator workflows
+- If no existing docs section is a natural fit, prefer recommending a new page or directory rather than forcing an `UPDATE` on a loosely related page
+
+Each coverage-gap finding should capture:
+
+- capability area
+- current docs state (`thin coverage` or `no coverage`)
+- evidence proving the capability shipped
+- likely audience
+- suggested docs location (`existing page`, `new page`, or `new directory`)
+- why that location is the right home
+
+**5b. Documentation surface assessment:**
 
 For each documentation surface relevant to the project, determine one of:
 
@@ -283,6 +336,7 @@ For each documentation surface relevant to the project, determine one of:
   - Proposed file path
   - Proposed content outline (section headings, key points)
   - Why this warrants a new file (evidence)
+  - If inside a docs app, note any parent index/nav follow-on work that will be needed
 
 - **SPLIT:** Existing doc would become too large with additions. Specify:
   - Current file path and approximate size
@@ -291,7 +345,13 @@ For each documentation surface relevant to the project, determine one of:
 
 - **No change:** Surface is already accurate — skip from delta plan.
 
-**5b. Instruction surface assessment (strong signals only):**
+When deciding between `UPDATE` and `CREATE`, prefer `CREATE` if:
+
+- the capability currently has **no coverage**
+- the docs app has no discoverable home for that topic
+- the proposed addition would otherwise bury a new major workflow inside an unrelated page
+
+**5c. Instruction surface assessment (strong signals only):**
 
 Only recommend instruction changes when there is a clear trigger:
 
@@ -305,14 +365,17 @@ Only recommend instruction changes when there is a clear trigger:
 
 If no strong signal is present for an instruction surface, skip it.
 
-**5c. Per recommendation, capture:**
+**5d. Per recommendation, capture:**
 
 ```
 - Target: {file path — existing or proposed}
 - Action: {UPDATE | CREATE | SPLIT}
 - Summary: {1-2 sentences on what changes and why}
-- Evidence: {artifact reference — e.g., "spec.md §3", "plan.md p02-t03", "implementation.md p01-t01 outcome"}
+- Evidence: {artifact/code reference — e.g., "spec.md §3", "plan.md p02-t03", "implementation.md p01-t01 outcome", "workflow file X proves release automation shipped"}
+- Audience: {developer | operator | integrator | end user}
 - Content guidance: {specific content to add or outline for new files}
+- Coverage state: {adequately covered | thin coverage | no coverage}
+- Parent docs impact: {parent index/nav updates needed, or "none"}
 ```
 
 ### Step 6: Present Delta Plan
@@ -378,7 +441,8 @@ Execute the approved documentation updates.
 2. **CREATE:**
    - Create parent directories if needed (`mkdir -p`)
    - Write the new file with the content outlined in the recommendation
-   - For docs directory files: follow the existing docs conventions (e.g., index.md structure for MkDocs)
+   - For docs directory files: follow the existing docs conventions for entrypoints and local navigation (for example, `index.md` entrypoints and `## Contents` sections where that is the local pattern)
+   - If the recommendation created a new docs directory, add the required entrypoint file for that directory as part of the same change
 
 3. **SPLIT:**
    - Create the new file with the content being moved
@@ -475,7 +539,9 @@ Next steps:
 ## Success Criteria
 
 - All documentation surfaces relevant to the project are scanned
+- Significant capability areas from the "what was built" model are classified as `adequately covered`, `thin coverage`, or `no coverage` before file-level recommendations are chosen
 - Recommendations are evidence-based (every recommendation cites artifact/code sources)
+- `CREATE` actions are recommended when no existing docs surface is a natural fit, including new docs pages or directories when the shipped work introduces a new capability area
 - Interactive approval flow works correctly (all/individual/skip)
 - `--auto` mode applies all changes without user interaction
 - New files and splits are handled correctly

package/assets/templates/docs-app-fuma/docs/contributing.md

@@ -67,5 +67,4 @@ Theme toggle is included in the layout. Mermaid diagrams re-render on mode switc
 
 ## Agent guidance
 
-- Treat `index.md` plus its `## Contents` section as the local discovery source of truth.
-- Prefer linking to source files and commands explicitly when documenting behavior.
+See `AGENTS.md` in this directory for how agents should work inside this docs app. This `contributing.md` covers human authoring conventions; `AGENTS.md` covers agent runtime discipline (adding pages, restructuring nav, audit/apply, three agent-instruction surfaces). Keeping those concerns separate keeps each file useful to its audience.

package/assets/templates/docs-app-fuma/docs/getting-started.md

@@ -9,7 +9,7 @@ Use this guide to set up your local environment and preview {{SITE_NAME}}.
 
 ## Prerequisites
 
-- Node.js 22+
+- Node.js 20+ (or whatever your repo's `.nvmrc` / `package.json` `engines.node` pins — match that)
 - pnpm 10+ (or npm/yarn)
 
 ## Install dependencies

package/assets/templates/docs-app-fuma/docs/index.md

@@ -9,5 +9,5 @@ Use this file as the map to the repository's central documentation site. The sit
 
 ## Contents
 
-- [Getting Started](getting-started) - Set up the local docs toolchain and preview the site.
-- [Contributing](contributing) - Authoring conventions and navigation rules.
+- [Getting Started](getting-started.md) - Set up the local docs toolchain and preview the site.
+- [Contributing](contributing.md) - Authoring conventions and navigation rules.

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

@@ -11,7 +11,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"];
+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_SCRIPTS: readonly ["resolve-tracking.sh"];
 export declare const UTILITY_SKILLS: readonly ["create-agnostic-skill", "oat-repo-maintainability-review", "oat-review-provide", "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;AAIH,eAAO,MAAM,eAAe,qwBA+BlB,CAAC;AAEX,eAAO,MAAM,eAAe,wDAGlB,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,mHAKd,CAAC;AAEX,eAAO,MAAM,YAAY,kCAAmC,CAAC;AAI7D,eAAO,MAAM,cAAc,gJAMjB,CAAC;AAIX,eAAO,MAAM,yBAAyB,kGAI5B,CAAC;AAEX,eAAO,MAAM,4BAA4B,4CAG/B,CAAC;AAEX,eAAO,MAAM,0BAA0B,aAAc,CAAC;AAItD,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;AAIH,eAAO,MAAM,eAAe,qwBA+BlB,CAAC;AAEX,eAAO,MAAM,eAAe,wDAGlB,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,gJAMjB,CAAC;AAIX,eAAO,MAAM,yBAAyB,kGAI5B,CAAC;AAEX,eAAO,MAAM,4BAA4B,4CAG/B,CAAC;AAEX,eAAO,MAAM,0BAA0B,aAAc,CAAC;AAItD,eAAO,MAAM,eAAe,2EAMlB,CAAC;AAEX,eAAO,MAAM,eAAe,qCAAsC,CAAC"}

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

@@ -71,6 +71,7 @@ export const DOCS_SKILLS = [
     'oat-agent-instructions-apply',
     'oat-docs-analyze',
     'oat-docs-apply',
+    'oat-docs-bootstrap',
 ];
 export const DOCS_SCRIPTS = ['resolve-tracking.sh'];
 // ── Utility pack ───────────────────────────────────────────────────

package/package.json

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