@open-agent-toolkit/cli 0.3.12 → 0.3.14

package/assets/docs/docs-tooling/commands.md

@@ -1,13 +1,13 @@
 ---
-title: Docs App Commands
-description: 'Docs scaffolding CLI surface for Fumadocs/MkDocs, migration helpers, Fumadocs index generation, and nav sync for both frameworks.'
+title: Documentation Commands
+description: 'Markdown bootstrap/adoption, framework scaffolding, external manifests, and navigation helpers for both frameworks.'
 ---
 
-# Docs App Commands
+# Documentation Commands
 
 OAT includes a dedicated docs command family for bootstrapping and maintaining
-documentation apps. Two frameworks are supported: **Fumadocs** (Next.js-based)
-and **MkDocs Material**.
+plain Markdown documentation and apps using **Fumadocs** (Next.js-based)
+or **MkDocs Material**.
 
 ## Quick Look
 
@@ -17,14 +17,14 @@ and **MkDocs Material**.
 
 ## Command surface
 
-| Command                   | Purpose                                                                       |
-| ------------------------- | ----------------------------------------------------------------------------- |
-| `oat docs init`           | Scaffold a new docs app (Fumadocs or MkDocs).                                 |
-| `oat docs migrate`        | Convert MkDocs admonitions to GFM callouts and inject frontmatter.            |
-| `oat docs generate-index` | Generate a Fumadocs app-root docs index manifest from the Markdown file tree. |
-| `oat docs nav sync`       | Regenerate `mkdocs.yml` nav or Fumadocs `meta.json` from `index.md` maps.     |
-| `oat docs analyze`        | CLI entrypoint that points users to the `oat-docs-analyze` skill.             |
-| `oat docs apply`          | CLI entrypoint that points users to the `oat-docs-apply` skill.               |
+| Command                   | Purpose                                                                   |
+| ------------------------- | ------------------------------------------------------------------------- |
+| `oat docs init`           | Set up Markdown files or a docs app; additively adopt Markdown.           |
+| `oat docs migrate`        | Convert MkDocs admonitions to GFM callouts and inject frontmatter.        |
+| `oat docs generate-index` | Generate a manifest from Markdown files, outside authored content.        |
+| `oat docs nav sync`       | Regenerate `mkdocs.yml` nav or Fumadocs `meta.json` from `index.md` maps. |
+| `oat docs analyze`        | CLI entrypoint that points users to the `oat-docs-analyze` skill.         |
+| `oat docs apply`          | CLI entrypoint that points users to the `oat-docs-apply` skill.           |
 
 ## Which Generation Command To Run
 
@@ -33,24 +33,59 @@ Use the framework-specific generated-artifact command:
 - Fumadocs apps run `fumadocs-mdx` and `oat docs generate-index`. In this repo, `predev` and `prebuild` regenerate `apps/oat-docs/index.md` from `apps/oat-docs/docs`. Run `oat docs nav sync` yourself after structural changes to rewrite the committed `meta.json` sidebar files from authored directory `index.md` `## Contents` sections; the hooks never write them. `prebuild` runs `oat docs nav sync --check`, so a build fails when those files are stale or a page is unlisted.
 - MkDocs apps use `oat docs nav sync` to regenerate the `nav:` block in `mkdocs.yml` from authored directory `index.md` `## Contents` sections.
 
-Both frameworks keep authored `## Contents` sections as the source of local discovery. The generated artifact differs by framework.
+Markdown needs no generation command or site build; optional inventories require
+explicit external output and retain the authored config index. Both frameworks keep authored `## Contents` sections as the source of local discovery. The generated artifact differs by framework.
 
 ## `oat docs init`
 
-Use `oat docs init` to scaffold a docs app that follows the OAT docs contract.
+Use `oat docs init` to bootstrap Markdown documentation or scaffold a framework app.
 
 > **Consider the `oat-docs-bootstrap` skill instead.** The skill wraps `oat docs init` with preflight detection, richer input gathering (site name distinct from package name), capability-gated post-patches that close open CLI gaps (site-title metadata, Turbopack root, template-content fixes, docs-app `AGENTS.md` bridge, `## Contents` link extensions, `contributing.md` three-surfaces cleanup), build verification, config inspection, and a seven-section educational walkthrough. See [Add Docs to a Repo §3a](add-docs-to-a-repo.md#3a-preferred-the-oat-docs-bootstrap-skill-guided) for the full flow. The CLI documented here remains the authoritative surface for flags and is the right choice when you need a deterministic, non-interactive scaffold (CI, automation).
 
 Key behavior:
 
-- prompts for framework choice (Fumadocs or MkDocs) in interactive mode
+- prompts for Markdown, Fumadocs, or MkDocs in interactive mode
 - detects monorepo vs single-package repo shape
-- defaults to `apps/<app-name>` for monorepos
-- defaults to `<app-name>/` at repo root for single-package repos
+- Markdown defaults to literal `docs` in every repo shape; framework apps default
+  to `apps/<app-name>` for monorepos
+- framework apps default to `<app-name>/` at repo root for single-package repos
 - sets `documentation.tooling`, `documentation.root`, and `documentation.index` in `.oat/config.json`
-- when the repo root exposes a compatible Turbo `scripts.build`, patches it to exclude the new docs app from the default root build and adds a root-level `build:docs` script
+- for framework apps, when the repo root exposes a compatible Turbo `scripts.build`, patches it to exclude the new docs app from the default root build and adds a root-level `build:docs` script
 - prints a unified diff before writing the root `package.json` change and returns a manual snippet when the patch is skipped because the build script is missing, non-Turbo, or ambiguous
 
+Markdown setup:
+
+- Creates only authored root `index.md` and `contributing.md` baseline pages,
+  with metadata, context and real relative `.md` Contents links.
+- Records literal root/tooling/authored index and managed root guidance; no
+  docs-root AGENTS, app package, dependencies, package/Turbo patch or site build.
+- Populated targets require `--adopt` even with `--yes`. Adoption only adds missing
+  baseline files; existing malformed indexes and local instructions are preserved
+  with audit advice. It does not claim full OAT conformity.
+- When the root `index.md` is missing, its initial Contents map includes existing
+  sibling pages and usable immediate child indexes. Readable child-index symlinks
+  resolving inside the repository are supported. Unusable child indexes are
+  preserved and omitted from the map with audit advice. An existing root index
+  is preserved rather than rebuilt.
+- During this discovery, directories containing only `AGENTS.md` or `CLAUDE.md`
+  do not trigger missing-index advice. If permissions prevent inspection of a
+  nested directory, bootstrap preserves it, reports that it was not inspected,
+  and continues checking readable siblings. Required root-baseline and target
+  safety checks remain strict; use analyze/apply for approved content repairs.
+- Unsafe roots and incompatible documentation config fail before writes.
+  Explicit framework selection retains its existing replacement behavior over
+  Markdown config, without migrating or deleting old Markdown content.
+- `--dry-run` reports planned changes without writes. Manual-required/blocked
+  guidance yields `partial`/exit `1`; a real partial may already have written
+  files/config. Converged adoption is `ok`/exit `0` with no changes.
+- Lint/format defaults are `none`; selecting existing tools never installs them.
+
+```bash
+oat docs init --framework markdown --site-name "Project Docs" --yes
+oat docs init --framework markdown --target-dir handbook --adopt --dry-run --yes
+oat docs init --framework markdown --target-dir handbook --adopt --yes
+```
+
 Fumadocs scaffold:
 
 - thin Next.js app importing from `@open-agent-toolkit/docs-config`, `@open-agent-toolkit/docs-theme`, `@open-agent-toolkit/docs-transforms`
@@ -67,11 +102,14 @@ Supported flags:
 
 - `--app-name <name>`
 - `--target-dir <path>`
-- `--framework <fumadocs|mkdocs>` (default: `fumadocs` in non-interactive mode)
-- `--description <text>` (site description, optional)
+- `--framework <markdown|fumadocs|mkdocs>` (default: `fumadocs` in non-interactive mode)
+- `--site-name <name>` (site display title or Markdown documentation title)
+- `--description <text>` (documentation description, optional)
 - `--lint <none|markdownlint-cli2>`
 - `--format <oxfmt|none>`
-- `--no-root-patch`
+- `--adopt` (Markdown only; add missing baseline files, preserve existing bytes)
+- `--dry-run` (Markdown only; nonmutating files/config/guidance preview)
+- `--no-root-patch` (inapplicable to Markdown, as is `--app-name`)
 - `--yes`
 
 Examples:
@@ -128,12 +166,12 @@ Key behavior:
 - recursively walks the docs directory
 - extracts page titles from frontmatter (falls back to first `# heading`, then filename title-case)
 - includes descriptions from frontmatter when present
-- resolves omitted paths from `.oat/config.json` rather than the current directory: `--docs-dir` defaults to `<documentation.root>/docs` when that directory exists and to `<documentation.root>` otherwise, and `--output` defaults to the app-root manifest `<documentation.root>/index.md`
+- resolves omitted paths from `.oat/config.json` rather than the current directory: configured Markdown uses the literal `documentation.root` for `--docs-dir` and requires explicit `--output`; other tooling defaults to `<documentation.root>/docs` when present or `<documentation.root>` otherwise, with app-root manifest output `<documentation.root>/index.md`
 - treats explicitly supplied `--docs-dir` / `--output` paths as overrides resolved from the current directory
 - fails with exit code `2` before generating or writing anything when an omitted path has no non-empty `documentation.root` to resolve against, or when the configured root is not a directory
-- refuses unsafe output targets with exit code `1` before generation, for derived and explicit paths alike, comparing symlink-resolved paths: inside the docs directory it indexes, equal to `documentation.config`, or ending in `.yml` / `.yaml` in any case. A derived output whose existing file lacks the `AUTOGENERATED` header is refused too; naming that path with `--output` overwrites it explicitly. A refused target is an actionable flag error (`1`); unusable path configuration is a separate condition and exits `2`, so scripts can branch on the two
+- refuses unsafe output targets with exit code `1` before generation, for derived and explicit paths alike, comparing symlink-resolved paths: inside the docs directory it indexes, equal to `documentation.config`, or ending in `.yml` / `.yaml` in any case. A derived output whose existing file lacks the `AUTOGENERATED` header is refused too; naming that path with `--output` overwrites it explicitly only when no other output guard applies. Configured Markdown additionally protects its full canonical content root and authored `documentation.index`, independently of selected source; narrowed sources and symlink aliases cannot bypass that guard. A refused target is an actionable flag error (`1`); unusable path configuration is a separate condition and exits `2`, so scripts can branch on the two
 - refuses a symlink chain that exceeds its own 32-hop cap, naming the path you supplied or the CLI derived rather than an intermediate link, and addressing the flag that owns it: an unusable **output** chain names `--output` and exits `1`; an unusable **docs directory** chain names `--docs-dir` and, when the directory was derived from `documentation.root` rather than passed explicitly, also names the `oat config set documentation.root <path>` repair and exits `2` as unusable path configuration. That cap governs the dangling links the command walks itself; a chain the operating system refuses first surfaces as its own `ELOOP` error with exit `1`, which is what a too-deep chain reports on a platform whose own limit is 32 or lower
-- writes configuration only for the Fumadocs manifest transition — recording the manifest it just wrote inside `documentation.root` in `documentation.index`, when `documentation.tooling` is `fumadocs` or the config declares neither `tooling` nor `config`. MkDocs configurations are never written, and `documentation.root` and `documentation.config` are never modified
+- writes configuration only for the Fumadocs manifest transition — recording the manifest it just wrote inside `documentation.root` in `documentation.index`, when `documentation.tooling` is `fumadocs` or the config declares neither `tooling` nor `config`. Markdown and MkDocs configurations are never written, and `documentation.root` and `documentation.config` are never modified
 - prepends an `AUTOGENERATED` warning comment to the output and rewrites the file on every run; do not hand-edit the generated `index.md`
 - should be freshness-checked against authored `docs/**/index.md` `## Contents` maps before treating it as navigation evidence
 - sorting: `index.md` first, then directories before files, then lexical
@@ -143,8 +181,8 @@ Key behavior:
 
 Supported flags:
 
-- `--docs-dir <path>` (default: `<documentation.root>/docs`, falling back to `<documentation.root>`)
-- `--output <path>` (default: `<documentation.root>/index.md`)
+- `--docs-dir <path>` (Markdown: literal configured root; others: `<root>/docs`, falling back to `<root>`)
+- `--output <path>` (required external output for configured Markdown; otherwise defaults to `<root>/index.md`)
 - `--exclude <glob>` (repeatable; additive to `documentation.excludes`)
 
 ### Exclusion patterns
@@ -165,10 +203,13 @@ A trailing `/` restricts a pattern to directories and never matches a file; with
 Example:
 
 ```bash
-# Resolve both paths from .oat/config.json
+# Framework defaults from .oat/config.json
 oat docs generate-index
 
-# Portable explicit form, resolved from the current directory
+# Optional Markdown manifest: output outside the entire configured content root
+oat docs generate-index --docs-dir handbook --output .oat/docs-manifest.md
+
+# Portable explicit framework form, resolved from the current directory
 oat docs generate-index --docs-dir apps/oat-docs/docs --output apps/oat-docs/index.md
 
 # Persist the repository's own exclusions, then add a one-off
@@ -176,7 +217,7 @@ oat config set documentation.excludes "**/CLAUDE.md,**/AGENTS.md"
 oat docs generate-index --exclude 'drafts/'
 ```
 
-See [Documentation path resolution](../reference/oat-directory-structure.md#documentation-path-resolution) for the app-root meaning of `documentation.root` and the legacy source-root compatibility rule.
+See [Documentation path resolution](../reference/oat-directory-structure.md#documentation-path-resolution) for Markdown literal roots, framework app roots, and legacy source-root compatibility.
 
 The Fumadocs scaffold runs this automatically via `predev`/`prebuild` npm
 script hooks.
@@ -188,6 +229,9 @@ Use nav sync after adding, removing, renaming, or reordering docs pages.
 The command reads only the reserved `## Contents` section from each directory
 `index.md`. It detects the framework from the app directory:
 
+Plain Markdown needs file/link checks and authored Contents maintenance, without
+site nav generation. Framework apps generate navigation as follows:
+
 - **MkDocs** (`mkdocs.yml`): regenerates the `nav:` block in `mkdocs.yml`.
 - **Fumadocs** (`source.config.ts`): writes one `meta.json` per docs directory
   that has an `index.md`. `pages` follows the `## Contents` order with no

package/assets/docs/docs-tooling/index.md

@@ -1,19 +1,20 @@
 ---
 title: Docs Tooling
-description: Standalone adoption lane for docs app setup, docs commands, and docs maintenance workflows.
+description: Standalone adoption lane for Markdown and docs app setup, docs commands, and docs maintenance workflows.
 ---
 
 # Docs Tooling
 
 Docs Tooling is the OAT lane for setting up, maintaining, and restructuring a documentation surface with OAT.
 
-Use this section when you are adopting the docs app workflow in a repo, maintaining generated navigation, or using the analyze/apply docs workflows. OAT supports both Fumadocs and MkDocs: the site framework changes the surrounding app setup and generated artifacts, but the underlying documentation contract stays centered on `index.md` and `## Contents`.
+Use this section when you are adopting the docs app workflow in a repo, maintaining generated navigation, or using the analyze/apply docs workflows. OAT supports Markdown, Fumadocs, and MkDocs. Plain Markdown keeps authored files without a site build; the site framework changes the surrounding app setup and generated artifacts, but the underlying documentation contract stays centered on `index.md` and `## Contents`.
 
 ## Contents
 
-- [Add Docs to a New Repo](add-docs-to-a-repo.md) - Bootstrap a docs app and adopt the docs workflow in a repo.
-- [Docs App Commands](commands.md) - Docs CLI surface for init, migration, index generation, and nav sync.
+- [Add or Adopt Docs in a Repo](add-docs-to-a-repo.md) - Set up Markdown or a docs app and safely adopt existing Markdown.
+- [Documentation Commands](commands.md) - Docs CLI surface for init, migration, index generation, and nav sync.
 - [Docs Workflows](workflows.md) - How the docs CLI helpers pair with analyze/apply workflows.
+- [Improve Agent Instructions](agent-instructions.md) - Analyze instruction gaps and apply approved evidence-backed changes.
 
 ## What This Section Is
 
@@ -21,7 +22,7 @@ This section explains how OAT supports docs surfaces, how the index contract wor
 
 ## Who It's For
 
-- Repos adding a docs app for the first time
+- Repos setting up or adopting Markdown documentation or a docs app
 - Teams maintaining directory indexes and generated navigation
 - Users who want a controlled analyze/apply flow for docs changes
 
@@ -40,7 +41,7 @@ This section explains how OAT supports docs surfaces, how the index contract wor
 
 ## Go Deeper
 
-- [Add Docs to a Repo](add-docs-to-a-repo.md) - Bootstrap a docs app and adopt the docs workflow in a repo.
+- [Add Docs to a Repo](add-docs-to-a-repo.md) - Set up Markdown or a docs app and safely adopt existing Markdown.
 - [Commands](commands.md) - Docs CLI surface for init, migration, index generation, and nav sync.
 - [Workflows](workflows.md) - How the docs CLI helpers pair with analyze/apply workflows.
 - [Docs Index Contract](../reference/docs-index-contract.md) - Framework-neutral `index.md` rules plus Fumadocs and MkDocs generation notes.

package/assets/docs/docs-tooling/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "Docs Tooling",
-  "pages": ["add-docs-to-a-repo", "commands", "workflows"]
+  "pages": ["add-docs-to-a-repo", "commands", "workflows", "agent-instructions"]
 }