@open-agent-toolkit/cli 0.3.11 → 0.3.13

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.11"
+  "oatVersion": "0.3.13"
 }

package/assets/docs/cli-utilities/configuration.md

@@ -93,7 +93,7 @@ Common keys in `.oat/config.json`:
   configured value for the current process.
 - `worktrees.root` — where OAT-managed worktrees live
 - `git.defaultBranch` — base branch fallback for PR workflows
-- `documentation.root`, `documentation.tooling`, `documentation.config` — docs-surface ownership
+- `documentation.root`, `documentation.tooling`, `documentation.config` — docs-surface ownership. With tooling `markdown`, root is the literal content directory (including nested `docs`) and `documentation.index` is authored `<root>/index.md`; Markdown adds no framework config. Framework roots retain app/source semantics. Use `oat docs init --framework markdown` or explicit `--adopt` for setup; optional manifests need external output and never change the authored index. See [Documentation path resolution](../reference/oat-directory-structure.md#documentation-path-resolution)
 - `documentation.excludes` — a JSON array of globs, relative to the docs directory, that `oat docs generate-index` leaves out of the generated index. `oat config set` takes the list as one comma-separated value (`"a/**,b.md"`) and stores it as an array; repeated `--exclude` flags extend it, and an empty value clears the key
 - `documentation.requireForProjectCompletion` — whether docs sync is a completion gate
 - `instructions.claude.shims` — how `oat instructions sync` keeps a `CLAUDE.md` beside each `AGENTS.md`: `none` (the default: no shims; sync removes the ones OAT created and warns about any other `CLAUDE.md`, all or nothing: it removes none while any `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` has content of its own; see [All or nothing](../provider-sync/instruction-sync.md#all-or-nothing)), `pointer`, `symlink`, or `copy`. The `--strategy` flag overrides it for one run. Set it with `oat config set instructions.claude.shims pointer` when contributors need `CLAUDE.md` (see [Claude Code and AGENTS.md](../provider-sync/instruction-sync.md#claude-code-and-agentsmd)); `oat config unset` returns to `none`. Any other value is rejected with exit code `2` rather than read as unset, and `oat config set` can still replace it

package/assets/docs/cli-utilities/tool-packs.md

@@ -928,7 +928,7 @@ Key behavior:
 The `docs` pack contains active documentation and instruction-governance
 workflows:
 
-- **oat-docs-bootstrap** — Guide users through bootstrapping a docs app
+- **oat-docs-bootstrap** — Guide users through Markdown setup/adoption or a docs app
   end-to-end: preflight detection, input gathering, scaffold (via `oat docs
 init`) with capability-gated post-patches, build verification, config
   inspection, and an educational walkthrough.
@@ -943,6 +943,9 @@ init`) with capability-gated post-patches, build verification, config
 
 Key behavior:
 
+- The docs pack includes `docs-markdown/index.md` and `docs-markdown/contributing.md`
+  baseline templates alongside framework scaffolds. Repository templates override
+  user templates, which override bundled defaults.
 - Docs pack installs at the selected scope and defaults to user scope on a
   fresh install.
 - It complements the `core` pack: `oat-docs` answers questions from bundled

package/assets/docs/docs-tooling/add-docs-to-a-repo.md

@@ -1,11 +1,11 @@
 ---
-title: Add Docs to a New Repo
-description: 'Step-by-step guide for adding an OAT-managed docs app to a repository.'
+title: Add or Adopt Docs in a Repo
+description: 'Step-by-step guide for adding or adopting OAT-managed documentation to a repository.'
 ---
 
-# Add Docs to a New Repo
+# Add or Adopt Docs in a Repo
 
-Use this path when you want to add an OAT-managed docs app and the docs
+Use this path when you want to add or adopt documentation and the docs
 analyze/apply workflow to a repository.
 
 If you are developing inside the OAT repo itself, replace `oat ...` with
@@ -13,7 +13,7 @@ If you are developing inside the OAT repo itself, replace `oat ...` with
 
 ## What this gives you
 
-- a docs app scaffolded with OAT defaults (Fumadocs or MkDocs)
+- plain Markdown files or a docs app scaffolded with OAT defaults (Fumadocs or MkDocs)
 - `index.md`-driven navigation
 - docs analysis and apply skills installed via the docs pack
 - a repeatable workflow for finding gaps, verifying claims, and applying docs changes
@@ -51,9 +51,9 @@ The docs pack installs `authoring-docs`, `oat-docs-authoring`,
 `oat-agent-instructions-apply`. For this quickstart, the authoring and docs
 analysis/apply skills are the parts you need immediately.
 
-## 3. Scaffold the docs app
+## 3. Set up the documentation surface
 
-Two paths — pick one:
+Choose Markdown files or a framework app, using the guided skill or direct CLI.
 
 ### 3a. Preferred: the `oat-docs-bootstrap` skill (guided)
 
@@ -61,9 +61,11 @@ Two paths — pick one:
 /oat-docs-bootstrap
 ```
 
-The docs-bootstrap skill wraps `oat docs init` with a seven-step guided flow: preflight detection (repo shape + existing-setup conflict surfacing), richer input gathering (including a site name distinct from the package name), the CLI invocation itself, labeled post-patches for open CLI gaps, install + build verification, post-scaffold config inspection, and a chunked educational walkthrough.
+The docs-bootstrap skill offers Markdown, Fumadocs, and MkDocs. Configured tooling is authoritative; framework evidence is checked before plain-directory evidence. A root README alone does not trigger adoption, and an empty selected target stays fresh setup. Markdown uses file checks and an adopt/audit handoff, with no app questions, dependencies, framework patches, docs-root AGENTS, or site build.
 
-What the skill adds over the raw CLI:
+For framework apps, it wraps `oat docs init` with a seven-step guided flow: preflight detection (repo shape + existing-setup conflict surfacing), richer input gathering (including a site name distinct from the package name), the CLI invocation itself, labeled post-patches for open CLI gaps, install + build verification, post-scaffold config inspection, and a chunked educational walkthrough.
+
+What the framework path adds over the raw CLI:
 
 - **Preflight + conflict resolution.** Detects existing `documentation` config / docs app dir / root `AGENTS.md` section and walks a deliberate resolution choice (replace, abort, repair, or deferred second-app) before any mutation.
 - **Richer inputs.** Asks for a **site name** separate from the package name, so `createDocsConfig()` / layout branding / page metadata all converge on the same display title.
@@ -90,10 +92,11 @@ oat docs init --app-name my-docs
 
 In interactive mode, you'll be prompted to choose a framework:
 
+- **Markdown** — authored files, context indexes, and Contents maps without a site framework
 - **Fumadocs** — Next.js-based static site with FlexSearch, Mermaid diagrams, dark/light mode, and code copy buttons
 - **MkDocs** — MkDocs Material with the OAT contributor contract
 
-Default placement:
+Framework default placement:
 
 - monorepo: `apps/my-docs`
 - single-package repo: `my-docs/` at repo root
@@ -113,8 +116,68 @@ Use 3b when you want a fully headless scaffold (CI, automation) and can accept t
 For compatible Turbo monorepos, the CLI also patches the repo-root
 `package.json` by default so root `pnpm build` excludes the new docs app and a
 root `build:docs` script is available for docs-only builds. Use
-`--no-root-patch` to opt out, or `--dry-run` to preview the diff without
-writing it.
+`--no-root-patch` to opt out. `--dry-run` is available only for Markdown
+files/config/guidance; it does not preview framework package patches.
+
+### Plain Markdown: fresh setup or additive adoption
+
+```bash
+# Fresh default root: docs/ in every repository shape
+oat docs init --framework markdown --site-name "Project Docs" --yes
+
+# Existing content: preview, then explicitly adopt without overwriting files
+oat docs init --framework markdown --target-dir handbook --adopt --dry-run --yes
+oat docs init --framework markdown --target-dir handbook --adopt --yes
+```
+
+Markdown creates missing `index.md` and `contributing.md` baseline pages and
+records `documentation.tooling: "markdown"`, the literal root, and its authored
+`<root>/index.md`. A nested `<root>/docs` remains a subsection. Root managed
+Documentation guidance names these paths; bootstrap creates no docs-root
+`AGENTS.md` and preserves one already present. It creates no app package,
+framework config, dependencies, or install/dev/build commands. Lint/format
+choices default to `none` and never install tools.
+
+A default setup records:
+
+```json
+{
+  "documentation": {
+    "tooling": "markdown",
+    "root": "docs",
+    "index": "docs/index.md"
+  }
+}
+```
+
+A populated target is refused without `--adopt`, including with `--yes`.
+Adoption preserves existing page/index/local-instruction bytes and adds only
+missing baseline files. Missing child indexes, metadata, context, or Contents
+remain audit gaps: run `oat-docs-analyze`, then `oat-docs-apply` for approved
+repairs. Successful config/guidance setup does not prove full content conformity.
+See [Markdown setup details](commands.md#oat-docs-init) for initial Contents
+discovery and repair advice for optional child indexes and unreadable directories.
+
+Incompatible declared tooling/root/index or unsafe paths are refused before
+writes. Selecting a framework explicitly retains its existing replacement
+prompt/`--yes` behavior, including over configured Markdown: config may change
+while old Markdown files remain. This is not an automatic content migration.
+
+Dry-run writes nothing. Manual-required or blocked guidance returns `partial`
+and exit `1`; files/config are planned, not completed. A real partial run may
+already have created baseline files and config: follow its reported state and
+preserve those files when retrying. Converged repeated adoption returns `ok`,
+exit `0`, and no changes.
+
+Markdown indexes are authored. Optional inventories require external output:
+
+```bash
+oat docs generate-index --docs-dir handbook --output .oat/docs-manifest.md
+```
+
+Default generation is refused for configured Markdown. External output cannot
+be inside the full configured content root or overwrite its authored index,
+even with a narrowed `--docs-dir`. It never repoints `documentation.index`.
 
 ### 3c. Existing MkDocs content
 
@@ -132,13 +195,15 @@ refactor, use the assigned migration handoff guide or project plan; do not make
 
 ## 4. Start authoring docs with the OAT contract
 
-Use `oat-docs-authoring` for targeted OAT/Fumadocs content edits or local
+Use `oat-docs-authoring` for targeted OAT Markdown/Fumadocs content edits or local
 restructuring. It uses `authoring-docs` for the portable documentation baseline
 and adds the OAT-specific navigation, generated-index, and validation contract.
 
 Core rules:
 
-- every docs directory should have an `index.md`
+- every non-excluded Markdown-bearing docs directory should have an authored `index.md`
+- preserve useful audience/scope context and nonempty title/description metadata
+- honor asset-only exceptions, configured excludes, and existing local instructions
 - every `index.md` should include a `## Contents` section
 - the `## Contents` section should map sibling pages and immediate child directories
 - `## Contents` links should use `.md`-suffixed relative targets, including `subdir/index.md` for child directories
@@ -214,7 +279,7 @@ Important:
 3. `oat docs init --app-name my-docs`
 4. (optional) handle MkDocs migration as a separate workstream; use `oat docs migrate --docs-dir docs --config mkdocs.yml --apply` only for the syntax/frontmatter helper
 5. Author docs with `index.md` + `## Contents`
-6. `oat docs nav sync --target-dir apps/my-docs` (both frameworks), plus `oat docs generate-index` (Fumadocs)
+6. Check Markdown files/links, or refresh declared artifacts with `oat docs nav sync --target-dir apps/my-docs` (both frameworks), plus `oat docs generate-index` (Fumadocs)
 7. `/oat-docs-analyze`
 8. `/oat-docs-apply`
 9. Repeat as the codebase changes

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,18 +1,18 @@
 ---
 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.
 
 ## What This Section Is
@@ -21,7 +21,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 +40,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/workflows.md

@@ -15,7 +15,7 @@ Install the workflow skills with `oat tools install docs` (preferred) or
 
 ### CLI helpers
 
-- `oat docs init` scaffolds a docs app (Fumadocs or MkDocs)
+- `oat docs init` bootstraps/adopts Markdown files or scaffolds a docs app (Fumadocs or MkDocs)
 - `oat docs migrate` converts MkDocs admonitions to GFM callouts and injects frontmatter
 - `oat docs generate-index` generates a Fumadocs app-root docs index manifest from the Markdown file tree
 - `oat docs nav sync` regenerates MkDocs `mkdocs.yml` nav, or strict Fumadocs `meta.json` files, from `index.md` `## Contents` sections
@@ -26,13 +26,14 @@ Install the workflow skills with `oat tools install docs` (preferred) or
 - `authoring-docs` is the provider-agnostic baseline for evidence-first
   technical documentation: page types, information architecture, category
   guidance, templates, and review rubrics
-- `oat-docs-authoring` layers the OAT/Fumadocs docs-app contract on top of
+- `oat-docs-authoring` layers the OAT Markdown/Fumadocs authored-source contract on top of
   `authoring-docs` for targeted authoring, restructuring, link repair, and
-  local navigation maintenance inside an existing OAT docs app
-- `oat-docs-bootstrap` is the guided onramp for adding a docs app to a repo —
+  local navigation maintenance inside an existing OAT documentation surface
+- `oat-docs-bootstrap` is the guided onramp for Markdown setup/adoption or adding a docs app —
   wraps `oat docs init` with preflight detection, richer input gathering (site
   name distinct from package name), labeled post-patches for open CLI gaps,
-  build verification, config inspection, and an educational walkthrough
+  file-level verification for Markdown or framework build verification, config
+  inspection, and an educational walkthrough
 - `oat-docs-analyze` evaluates a docs surface for structure, drift, coverage,
   contributor guidance, and docs-app contract issues, then runs the shared
   auto artifact-review loop to verify the generated analysis artifact's
@@ -60,18 +61,34 @@ skills.
 
 ## Typical flow
 
-1. Bootstrap a docs app with `oat-docs-bootstrap` (preferred — guided, includes post-scaffold patches and walkthrough) or `oat docs init` directly (CLI-only / non-interactive workflows)
+1. Bootstrap or explicitly adopt a documentation surface with `oat-docs-bootstrap` (preferred — guided, includes post-scaffold patches and walkthrough) or `oat docs init` directly (CLI-only / non-interactive workflows)
 2. (Optional) If migrating from MkDocs, handle that as a separate migration workstream; `oat docs migrate --docs-dir docs --config mkdocs.yml --apply` is only the syntax/frontmatter helper
-3. Use `oat-docs-authoring` for targeted OAT/Fumadocs authoring work, with `authoring-docs` as the universal documentation-quality baseline
-4. Author docs so every directory has an `index.md` with a `## Contents` section
+3. Use `oat-docs-authoring` for targeted OAT Markdown/Fumadocs authoring work, with `authoring-docs` as the universal documentation-quality baseline
+4. Keep authored context and title/description metadata, with an `index.md` and useful `## Contents` in each non-excluded Markdown-bearing directory; preserve asset-only exceptions and local instructions
 5. Keep local `## Contents` sections current
-6. Refresh generated artifacts:
+6. Verify files/links and refresh declared derived artifacts:
+   - **Markdown:** use the configured root literally, including nested `docs`; authored indexes are editable. No app install/site build/nav sync is required. Optional manifests need explicit external output and never replace the authored config index.
    - **MkDocs:** `oat docs nav sync`
    - **Fumadocs:** `oat docs nav sync` for the committed `meta.json` sidebar files (it reports pages no `## Contents` map lists), and `oat docs generate-index` for the root manifest (runs automatically via `predev`/`prebuild` hooks)
 7. Run `oat-docs-analyze`; by default it verifies the generated analysis artifact
    through `workflow.autoArtifactReview.analysis`
 8. Review the artifact and run `oat-docs-apply`
 
+## Existing Markdown and partial setup
+
+Bootstrap checks declared config before discovery and framework evidence before
+plain-tree candidates. A populated plain tree is offered adopt/audit; `--yes`
+alone does not authorize adoption. `--adopt` preserves existing bytes and adds
+missing baseline files only. Config/guidance success does not prove complete
+content conformity: analyze recommends missing context, metadata, Contents or
+child indexes, and apply performs only approved repairs without replacing useful
+context or local instructions.
+
+Use `--dry-run` for a nonmutating Markdown preview. Guidance conflicts may yield
+`partial`/exit `1`, with planned files/config; a real partial reports any already
+created files/config separately. Repeated converged adoption returns no changes.
+See [Commands](commands.md#oat-docs-init) for examples and exit behavior.
+
 ## Progressive disclosure
 
 The docs workflow expects local indexes to guide discovery without forcing agents

package/assets/docs/provider-sync/commands.md

@@ -236,7 +236,7 @@ Key behavior:
 - Adopts Claude-only stray files by writing canonical `AGENTS.md` content first, then regenerating `CLAUDE.md` (shim strategies) or removing it (`none`)
 - Under a shim strategy, skips mismatched files unless `--force` is provided
 - Skips unreadable canonical or Claude-only sources and reports manual-repair guidance instead of forcing recovery
-- Skips the documentation content tree (`<documentation.root>/docs` when that is a directory, otherwise `documentation.root`) plus any `instructions.claude.excludes` paths, so authored pages never receive pointers; app-level instruction files such as `apps/oat-docs/AGENTS.md` are still synced
+- Skips the documentation content tree (literal `documentation.root` for tooling `markdown`, including nested `docs`; otherwise `<documentation.root>/docs` when that is a directory, falling back to `documentation.root`) plus any `instructions.claude.excludes` paths, so authored pages never receive pointers; app-level instruction files such as `apps/oat-docs/AGENTS.md` are still synced
 - Never deletes an existing `CLAUDE.md` inside an excluded tree
 - Under `none`, warns about every `CLAUDE.md` that remains after sync, including inside excluded trees, because any one of them makes Claude Code ignore every `AGENTS.md`
 - Uses pointer content `@AGENTS.md\n`, file symlinks, or hard copies depending on the selected strategy

package/assets/docs/provider-sync/instruction-sync.md

@@ -41,22 +41,29 @@ to fix.
 
 The content root is derived from `documentation.root` in `.oat/config.json`:
 
-- `<documentation.root>/docs` when that path is a directory;
-- otherwise `documentation.root` itself.
+- for tooling `markdown`, the literal configured `documentation.root`, even
+  when it contains a child directory named `docs`;
+- for other or undeclared tooling, `<documentation.root>/docs` when that path is
+  a directory, otherwise `documentation.root` itself.
 
 This is the same derivation `oat docs generate-index` uses to pick its default
 docs directory, so the excluded tree and the indexed tree agree by
 construction. (`oat docs generate-index --docs-dir` overrides the index side
 only; it does not change what instruction sync excludes.)
 
-**App-level instruction files are still synced.** `documentation.root`
-canonically names the docs _app_ root, and a file like
+**Framework app-level instruction files are still synced.** For framework tooling, `documentation.root`
+names the docs _app_ root, and a file like
 `apps/oat-docs/AGENTS.md` is instructions for working on the docs app rather
 than a documentation page. When the app root has a `docs` child, only that
 child is skipped, and the app root is still synced (under a shim strategy it
 keeps receiving its `CLAUDE.md` pointer). Opt the app root out explicitly if
 you do not want it synced.
 
+For configured Markdown, the entire content root remains excluded, including
+existing local AGENTS files and parent pages outside a nested `docs` subsection.
+Bootstrap preserves local guidance and creates no docs-root AGENTS. Pointer sync
+never replaces authored content or those local instruction files.
+
 Add further paths with `instructions.claude.excludes`, a list of
 repository-relative directories. Set it with
 `oat config set instructions.claude.excludes "vendor,third_party/docs"`

package/assets/docs/reference/cli-reference.md

@@ -16,7 +16,7 @@ The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oa
 - [Config and Local State](../cli-utilities/config-and-local-state.md) - Config, backlog, local paths, diagnostics, and related utility commands.
 - [Remote Project Management](../cli-utilities/remote-project-management.md) - Explicit remote bindings, policy, host handoffs, and recovery.
 - [Workflow Gates](../cli-utilities/workflow-gates.md) - Per-skill final commands, review gates, and cross-runtime prompt dispatch.
-- [Docs Tooling Commands](../docs-tooling/commands.md) - Docs app scaffolding, migration, index generation, and nav sync.
+- [Docs Tooling Commands](../docs-tooling/commands.md) - Markdown setup/adoption, framework scaffolding, manifests, and nav sync.
 - [Provider Sync](../provider-sync/index.md) - Sync behavior, provider capabilities, config, and drift management.
 - [Agentic Workflows](../workflows/index.md) - Tracked project execution, skills, ideas, and workflow routing.
 - [Workflow & Projects](../workflows/projects/index.md) - Project lifecycle, artifacts, reviews, PR flow, and state-machine docs.
@@ -50,7 +50,7 @@ The first practical expansion path is to keep improving the existing owners: [Do
 | `oat config ...` / `oat instructions ...`       | Config discovery, source-aware config dumps, supported mutations, and instruction-integrity helpers.                                                                                                                       | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
 | `oat gate ...`                                  | Per-skill final gate config, review-specific gate execution, exec-target registry writes, and cross-runtime prompt dispatch.                                                                                               | [Workflow Gates](../cli-utilities/workflow-gates.md)                               |
 | `oat state ...` / `oat index ...` / `internal`  | Repo dashboard refresh, repo indexing, validation helpers, and diagnostics.                                                                                                                                                | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
-| `oat docs ...`                                  | Docs app bootstrap, migration, index generation, nav sync, and docs workflow entrypoints.                                                                                                                                  | [Docs Tooling Commands](../docs-tooling/commands.md)                               |
+| `oat docs ...`                                  | Markdown bootstrap/adoption, framework setup, external manifests, nav sync, and docs workflow entrypoints.                                                                                                                 | [Docs Tooling Commands](../docs-tooling/commands.md)                               |
 | `oat status` / `oat sync` / `oat providers ...` | Provider sync, drift inspection, provider configuration, and adoption behavior.                                                                                                                                            | [Provider Sync](../provider-sync/index.md)                                         |
 | `oat project ...` / `oat cleanup ...`           | Project scaffolding, active-project status inspection, tracked-project listing, plan validation, archive creation, and project/artifact cleanup commands.                                                                  | [Workflow & Projects](../workflows/projects/index.md)                              |
 | `oat template resolve`                          | Resolve a lifecycle template in repository, user, then bundle order and optionally copy it into place.                                                                                                                     | [File Locations](file-locations.md)                                                |