@open-agent-toolkit/cli 0.0.37 → 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/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.37",
+  "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.37"
+    "@open-agent-toolkit/control-plane": "0.0.38"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",