@open-agent-toolkit/cli 0.3.26 → 0.3.28

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.3.26",
+  "version": "0.3.28",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -31,13 +31,22 @@
     "chalk": "^5.6.2",
     "commander": "^12.1.0",
     "entities": "6.0.1",
+    "github-slugger": "2.0.0",
+    "jsdom": "29.1.1",
     "jsonc-parser": "3.2.1",
+    "mermaid": "11.12.3",
     "ora": "^9.0.0",
+    "parse5": "7.3.0",
+    "remark-gfm": "4.0.1",
+    "remark-parse": "11.0.0",
+    "unified": "11.0.5",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.3.26"
+    "@open-agent-toolkit/control-plane": "0.3.28",
+    "@open-agent-toolkit/docs-transforms": "0.3.28"
   },
   "devDependencies": {
+    "@types/jsdom": "28.0.3",
     "@types/node": "^22.10.0",
     "tsc-alias": "^1.8.10",
     "tsx": "^4.21.0",

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

@@ -1,64 +0,0 @@
-<!-- Framework docs-app bridge only: Fumadocs/MkDocs. Never render this template into a plain Markdown content root; use managed root Documentation guidance and the contributing page there. -->
-# 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 Markdown-bearing content directory must have an `index.md`; asset-only directories are exempt. Preserve useful audience/scope context and honor configured excludes and existing local instructions.
-5. Regenerate the derived navigation artifacts for this framework. For Fumadocs, run `oat docs nav sync` (from the app directory, or with `--target-dir <app-dir>`) so the committed `docs/**/meta.json` sidebar files follow authored `## Contents`, and run the generated-index command (`{{GENERATE_INDEX_CMD}}`) so the app-root `index.md` manifest reflects the current Markdown file tree. Fumadocs nav sync is strict: a page no `## Contents` map lists stays out of the sidebar and is reported, so list the new page rather than editing `meta.json`. 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 Fumadocs app-root `index.md` manifest, Fumadocs `meta.json` files, `mkdocs.yml` `nav:` (for MkDocs), and any other derived nav file is rewritten by the local generation workflow.
-3. After editing `## Contents`, run `oat docs nav sync` and 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.
-
-## 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.** 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`.
-- **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}}` — for Fumadocs, regenerates the machine-readable root `index.md` from `docs/`. Runs automatically on `predev` / `prebuild`; don't hand-edit its output.