@open-agent-toolkit/cli 0.3.12 → 0.3.13

package/assets/docs/reference/docs-index-contract.md

@@ -1,6 +1,6 @@
 ---
 title: Docs Index Contract
-description: 'Docs source contract: authored index.md maps, generated Fumadocs manifests and meta.json navigation, and MkDocs nav sync.'
+description: 'Docs source contract: authored Markdown context/maps, optional external inventories, Fumadocs manifests and meta.json navigation, and MkDocs nav sync.'
 ---
 
 # Docs Index Contract
@@ -9,7 +9,8 @@ OAT docs navigation starts from authored `docs/**/index.md` files. Each `## Cont
 
 ## Rules
 
-- Every documentation directory must contain an `index.md`.
+- Every non-excluded Markdown-bearing content directory must contain an authored `index.md`; asset-only directories are exempt.
+- Preserve useful audience/scope context, ownership guidance, and existing local instructions. Authored pages need nonempty title/description metadata.
 - Every `index.md` must include a `## Contents` section.
 - The `## Contents` section is the machine-readable local map for sibling pages and child directories.
 - Every `## Contents` link should use a `.md`-suffixed relative target, including child directory links such as `subdir/index.md`.
@@ -35,6 +36,20 @@ Notes:
 - Leaf pages should link to their `.md` filename.
 - Prose outside `## Contents` is ignored by nav generation and remains freeform; it can explain scope, reader paths, or migration status.
 
+## Plain Markdown Ownership
+
+Configured Markdown uses `documentation.root` literally, even with a child named
+`docs`. The configured `<root>/index.md` is authored context plus a Contents map;
+edit it directly. Bootstrap/adoption creates missing baseline files and root
+guidance, but content gaps remain analyze/apply work. No app package, site build,
+nav sync, default manifest, or docs-root AGENTS creation is required.
+
+Optional inventories need explicit output outside the full configured content
+tree, for example `oat docs generate-index --docs-dir docs --output .oat/docs-manifest.md`.
+Default generation is refused, as is output to the authored index or any part of
+the full root, even with narrowed source flags or symlink aliases. Generation
+never repoints the configured authored index.
+
 ## Fumadocs Generation
 
 For this Fumadocs app, rendered page routing comes from the Fumadocs file/source pipeline over `apps/oat-docs/docs`, and the sidebar order comes from the committed `meta.json` files that `oat docs nav sync` writes (see [Fumadocs Nav Sync](#fumadocs-nav-sync)). The generated root manifest, `apps/oat-docs/index.md`, is an inventory for agents and tooling; it is not the rendered sidebar/page-tree source.
@@ -84,7 +99,7 @@ MkDocs generated behavior:
 
 ## Generated-file boundaries
 
-- Edit authored files under `docs/`, especially the nearest `index.md` and `## Contents`.
+- Edit authored files under the resolved content root (`docs/` inside framework apps, or the literal configured Markdown root), especially the nearest `index.md` and `## Contents`.
 - Do not hand-edit a Fumadocs app-root generated `index.md`; regenerate it from the docs source tree.
 - Do not hand-maintain MkDocs `nav:` entries or Fumadocs `meta.json` `pages` lists when the local workflow uses `oat docs nav sync`.
 - If a Fumadocs generated manifest lists pages that are missing from authored `## Contents`, treat that as authored-source drift or intentional generator-inventory behavior to verify before relying on the generated file as navigation evidence.
@@ -94,7 +109,7 @@ MkDocs generated behavior:
 - Use `index.md` as the local discovery surface for humans and agents.
 - Add a short topic description next to each link so agents can choose the right file without opening every page.
 - Update `## Contents` whenever you add, remove, rename, or reorder docs files in a directory.
-- Regenerate the framework-specific artifacts after structural changes: `nav sync` for MkDocs `mkdocs.yml` and Fumadocs `meta.json` navigation, plus `generate-index` for Fumadocs root manifests.
+- Markdown checks authored files/links, regenerating optional external manifests only when declared. Frameworks regenerate their artifacts after structural changes: `nav sync` for MkDocs `mkdocs.yml` and Fumadocs `meta.json` navigation, plus `generate-index` for Fumadocs root manifests.
 - Refresh or freshness-check the generated artifact before committing structural docs changes.
 
 ## If You Are Trying To...

package/assets/docs/reference/file-locations.md

@@ -174,7 +174,7 @@ Archive sync surfaces:
 - `packages/cli/src/commands/cleanup/project/`
 - `packages/cli/src/commands/cleanup/artifacts/`
 - `packages/cli/src/commands/docs/` — `oat docs` command family
-- `packages/cli/src/commands/docs/init/` — scaffold a docs app (Fumadocs or MkDocs)
+- `packages/cli/src/commands/docs/init/` — bootstrap/adopt authored Markdown or scaffold a docs app (Fumadocs or MkDocs)
 - `packages/cli/src/commands/docs/migrate/` — convert MkDocs admonitions to GFM callouts
 - `packages/cli/src/commands/docs/index-generate/` — generate a docs index from markdown files
 - `packages/cli/src/commands/docs/nav/` — regenerate mkdocs.yml nav or Fumadocs meta.json from index.md sections
@@ -196,3 +196,5 @@ Archive sync surfaces:
 
 - `.oat/templates/docs-app-fuma/` — Fumadocs (Next.js) scaffold template
 - `.oat/templates/docs-app-mkdocs/` — MkDocs Material scaffold template
+
+- `.oat/templates/docs-markdown/` — authored `index.md` and `contributing.md` baseline templates; installed by the docs pack, with no app or docs-root AGENTS template

package/assets/docs/reference/oat-directory-structure.md

@@ -48,16 +48,16 @@ Project scope is used for project workflows and repo-local sync state. User scop
 
 ## Top-level entries
 
-| Path                     | Purpose                                             | Notes                                                                                                                                 |
-| ------------------------ | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
-| `.oat/config.json`       | Shared repo runtime config for non-sync settings    | Includes `worktrees.root`, `projects.root`, `git.defaultBranch`, `archive.*`, `documentation.*`, `instructions.*`, and `pjm.remote.*` |
-| `.oat/config.local.json` | Local per-developer runtime state                   | Gitignored; includes `activeProject`, `lastPausedProject`, `activeIdea`                                                               |
-| `.oat/state.md`          | Generated repo state dashboard                      | Gitignored; rebuilt with `oat state refresh` from config, project artifacts, and knowledge metadata                                   |
-| `.oat/projects/`         | OAT project artifacts                               | `shared`, `synced`, `local`, and lifecycle `archived` locations                                                                       |
-| `.oat/ideas/`            | Project-level ideas store                           | Often gitignored                                                                                                                      |
-| `.oat/sync/`             | Interop sync state/config                           | See details below                                                                                                                     |
-| `.oat/templates/`        | Artifact templates used by OAT skills               | Source for scaffolding. Includes `docs-app-fuma/` (Fumadocs) and `docs-app-mkdocs/` (MkDocs) templates.                               |
-| `.oat/repo/`             | Repo-level PJM/knowledge/reference/review artifacts | Active PJM state under `pjm/`; durable references (including decisions) under `reference/`                                            |
+| Path                     | Purpose                                             | Notes                                                                                                                                                    |
+| ------------------------ | --------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `.oat/config.json`       | Shared repo runtime config for non-sync settings    | Includes `worktrees.root`, `projects.root`, `git.defaultBranch`, `archive.*`, `documentation.*`, `instructions.*`, and `pjm.remote.*`                    |
+| `.oat/config.local.json` | Local per-developer runtime state                   | Gitignored; includes `activeProject`, `lastPausedProject`, `activeIdea`                                                                                  |
+| `.oat/state.md`          | Generated repo state dashboard                      | Gitignored; rebuilt with `oat state refresh` from config, project artifacts, and knowledge metadata                                                      |
+| `.oat/projects/`         | OAT project artifacts                               | `shared`, `synced`, `local`, and lifecycle `archived` locations                                                                                          |
+| `.oat/ideas/`            | Project-level ideas store                           | Often gitignored                                                                                                                                         |
+| `.oat/sync/`             | Interop sync state/config                           | See details below                                                                                                                                        |
+| `.oat/templates/`        | Artifact templates used by OAT skills               | Source for scaffolding. Includes `docs-markdown/` (authored index/contributing), `docs-app-fuma/` (Fumadocs), and `docs-app-mkdocs/` (MkDocs) templates. |
+| `.oat/repo/`             | Repo-level PJM/knowledge/reference/review artifacts | Active PJM state under `pjm/`; durable references (including decisions) under `reference/`                                                               |
 
 ## `.oat/sync/` details
 
@@ -120,10 +120,10 @@ Current schema keys:
 | `projects.root`                                            | `string`                   | `".oat/projects/shared"` | Default root directory for OAT projects                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `projects.defaultScope`                                    | `string`                   | `"synced"`               | Scope used by project creation when `--scope` is omitted: `shared`, `local`, or `synced`. Environment override: `OAT_PROJECTS_DEFAULT_SCOPE`.                                                                                                                                                                                                                                                                                                                                                       |
 | `localPaths`                                               | `string[]`                 | -                        | Gitignored directories to sync between main repo and worktrees. Supports glob patterns. Managed via `oat local add/remove`.                                                                                                                                                                                                                                                                                                                                                                         |
-| `documentation.root`                                       | `string`                   | -                        | Docs **app root** — the directory `oat docs init` scaffolds (e.g., `apps/docs`). Authored pages live under `<root>/docs`. See [Documentation path resolution](#documentation-path-resolution).                                                                                                                                                                                                                                                                                                      |
-| `documentation.tooling`                                    | `string`                   | -                        | Documentation framework identifier (`mkdocs` or `fumadocs`)                                                                                                                                                                                                                                                                                                                                                                                                                                         |
+| `documentation.root`                                       | `string`                   | -                        | Literal authored content root for tooling `markdown` (default `docs`); otherwise docs **app root** (e.g., `apps/docs`) with authored pages normally under `<root>/docs`. See [Documentation path resolution](#documentation-path-resolution).                                                                                                                                                                                                                                                       |
+| `documentation.tooling`                                    | `string`                   | -                        | Documentation tooling identifier (`markdown`, `mkdocs`, or `fumadocs`); parsing remains permissive                                                                                                                                                                                                                                                                                                                                                                                                  |
 | `documentation.config`                                     | `string`                   | -                        | Path to the documentation framework config file (e.g., `mkdocs.yml`, `next.config.js`)                                                                                                                                                                                                                                                                                                                                                                                                              |
-| `documentation.index`                                      | `string`                   | -                        | Path to the docs surface entry point: the generated app-root manifest `<root>/index.md` for Fumadocs, `mkdocs.yml` for MkDocs. Set by `oat docs init`. `oat docs generate-index` writes it only for the Fumadocs manifest transition and never for MkDocs.                                                                                                                                                                                                                                          |
+| `documentation.index`                                      | `string`                   | -                        | Path to the docs surface entry point: authored `<root>/index.md` for Markdown, the generated app-root manifest `<root>/index.md` for Fumadocs, `mkdocs.yml` for MkDocs. Set by `oat docs init`. `oat docs generate-index` writes it only for the Fumadocs manifest transition and never for Markdown or MkDocs.                                                                                                                                                                                     |
 | `documentation.excludes`                                   | `string[]`                 | -                        | Globs, relative to the docs directory, that `oat docs generate-index` leaves out of the generated index. See [Excluding pages from the generated index](#excluding-pages-from-the-generated-index).                                                                                                                                                                                                                                                                                                 |
 | `documentation.requireForProjectCompletion`                | `boolean`                  | `false`                  | When `true`, OAT project completion gates require documentation to be updated                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `git.defaultBranch`                                        | `string`                   | `"main"`                 | Default branch for PR creation. Auto-detected during `oat init` via `gh repo view` or `origin/HEAD`. Used by `oat-project-pr-final` and `oat-project-pr-progress`.                                                                                                                                                                                                                                                                                                                                  |
@@ -174,24 +174,26 @@ Example:
 
 ### Documentation path resolution
 
-`documentation.root` canonically names the docs **app root** — exactly the directory `oat docs init` scaffolds. Authored Markdown lives under `<root>/docs`, and the generated Fumadocs manifest is written to `<root>/index.md`, outside the tree it indexes.
+With `documentation.tooling: "markdown"`, `documentation.root` is the dedicated literal content directory and `documentation.index` is authored `<root>/index.md`. A child named `docs` does not narrow it. Fresh setup/adoption creates missing baseline pages and managed root guidance, without app files, dependencies, site builds, or a docs-root AGENTS file; existing local instructions are preserved.
+
+Framework roots retain their app-root meaning. Authored content commonly lives under `<root>/docs`; the generated Fumadocs manifest lives at `<root>/index.md`, outside its source tree.
 
 `oat docs generate-index` resolves omitted options from this configuration:
 
-| Option       | Omitted                                                                                  | Supplied                            |
-| ------------ | ---------------------------------------------------------------------------------------- | ----------------------------------- |
-| `--docs-dir` | `<documentation.root>/docs` when that directory exists, otherwise `<documentation.root>` | Resolved from the current directory |
-| `--output`   | `<documentation.root>/index.md`                                                          | Resolved from the current directory |
+| Option       | Omitted                                                                                                 | Supplied                            |
+| ------------ | ------------------------------------------------------------------------------------------------------- | ----------------------------------- |
+| `--docs-dir` | Markdown: literal `<documentation.root>`; other tooling: `<root>/docs` when present, otherwise `<root>` | Resolved from the current directory |
+| `--output`   | Markdown: explicit external output required; otherwise `<root>/index.md`                                | Resolved from the current directory |
 
 If an omitted option has no non-empty `documentation.root` to resolve against, or the configured root is not a directory, the command fails with exit code `2` before generating or writing anything.
 
-**Compatibility behavior.** Preferring `<root>/docs` exists for legacy configs whose `root` names a docs _source_ directory rather than an app root; it is not a second meaning of the key. Because the rule is a plain directory-existence test, a source root that happens to contain its own `docs` subdirectory is narrowed to it. The command prints the directory it derived in both human and JSON output (`docsDir`, `docsDirSource`), and `--docs-dir` is the escape hatch when the derivation is wrong.
+**Compatibility behavior.** Preferring `<root>/docs` exists for legacy configs whose `root` names a docs _source_ directory rather than an app root; it is not a second meaning of the key. For non-Markdown tooling the rule is a plain directory-existence test, so a source root that happens to contain its own `docs` subdirectory is narrowed to it. The command prints the directory it derived in both human and JSON output (`docsDir`, `docsDirSource`), and `--docs-dir` is the escape hatch when the derivation is wrong.
 
 A legacy source root with no `docs` child resolves `--docs-dir` and `--output` to the same tree, so a bare run is refused rather than allowed to overwrite an authored page. Pass an explicit `--output` outside the source tree, or repoint `documentation.root` at the app root.
 
-**Refused output targets.** Checked before generation for derived and explicit paths alike, the command refuses to write an output that is inside the docs directory it indexes, equals `documentation.config`, or ends in `.yml` / `.yaml`. A derived output whose existing file lacks the `AUTOGENERATED by oat docs generate-index` header is also refused; naming that same path with `--output` overwrites it explicitly.
+**Refused output targets.** Checked before generation for derived and explicit paths alike, the command refuses to write an output that is inside the docs directory it indexes, equals `documentation.config`, or ends in `.yml` / `.yaml`. A derived output whose existing file lacks the `AUTOGENERATED by oat docs generate-index` header is also refused; naming that same path with `--output` overwrites it explicitly only when no other guard applies. Configured Markdown additionally protects the full canonical configured content root and authored `documentation.index`, even with narrowed `--docs-dir` or symlink aliases. Default Markdown generation is refused; use explicit output outside the full content tree. The authored index remains configured.
 
-**Configuration writes.** The only configuration write generation performs is the Fumadocs manifest transition: when the written manifest lies inside `documentation.root` and `documentation.tooling` is `fumadocs`, the repo-relative output path is recorded in `documentation.index`. A config that declares neither `documentation.tooling` nor `documentation.config` is treated as the same Fumadocs-shaped case. Any other declared tooling — `mkdocs` included — is never written, and neither are `documentation.root` and `documentation.config`. The value is always repo-relative: when `documentation.root` points outside the repository, the manifest is still generated but the key is left untouched rather than recording a machine-specific path.
+**Configuration writes.** The only configuration write generation performs is the Fumadocs manifest transition: when the written manifest lies inside `documentation.root` and `documentation.tooling` is `fumadocs`, the repo-relative output path is recorded in `documentation.index`. A config that declares neither `documentation.tooling` nor `documentation.config` is treated as the same Fumadocs-shaped case. Any other declared tooling — `markdown` and `mkdocs` included — is never written, and neither are `documentation.root` and `documentation.config`. The value is always repo-relative: when `documentation.root` points outside the repository, the manifest is still generated but the key is left untouched rather than recording a machine-specific path.
 
 ### Excluding pages from the generated index
 

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.12",
-  "docs-config": "0.3.12",
-  "docs-theme": "0.3.12",
-  "docs-transforms": "0.3.12"
+  "cli": "0.3.13",
+  "docs-config": "0.3.13",
+  "docs-theme": "0.3.13",
+  "docs-transforms": "0.3.13"
 }

package/assets/skills/oat-docs-analyze/SKILL.md

@@ -1,11 +1,11 @@
 ---
 name: oat-docs-analyze
-description: Run when you need to evaluate documentation structure, navigation, and coverage against the OAT docs app contract. Produces a severity-rated analysis artifact for oat-docs-apply.
+description: Run when you need to evaluate documentation structure, navigation, and coverage against the OAT documentation contract. Produces a severity-rated analysis artifact for oat-docs-apply.
 disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Bash(git:*), Bash(oat docs nav sync --check:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.6.0
+  version: 1.6.1
 ---
 
 # Docs Analysis
@@ -93,7 +93,11 @@ repo fallbacks:
 1. `.oat/config.json` `documentation.root` / `documentation.tooling`.
    - When `documentation.tooling` is `fumadocs`, record the surface type as
      `oat-fumadocs-app`.
-   - Treat `documentation.root` as the docs app root. Resolve the authored docs
+   - When tooling is `markdown`, record `docs-tree`; `documentation.root` is
+     the literal authored content root, even with a child named `docs`. The
+     configured `documentation.index` is authored, not a generated manifest.
+     Honor configured excludes and existing local instructions.
+   - For framework tooling, treat `documentation.root` as the docs app root. Resolve the authored docs
      source root and generated index path from `documentation.index`, app config,
      package scripts, generator scripts, or local guidance.
 2. OAT/Fumadocs app candidates under `apps/*`, before root `docs/` fallback:
@@ -121,6 +125,12 @@ TRACKING=$(bash "$TRACKING_SCRIPT" read docs 2>/dev/null || true)
 - If the stored commit exists, run in `delta` mode and scope drift checks to changed docs directories.
 - Otherwise run in `full` mode.
 
+Configured tooling/root take precedence over discovery. Markdown needs no app
+package, site config, docs-root AGENTS, site build, or generated manifest. Read
+managed root guidance, contributing pages, and any existing local AGENTS files;
+do not mark their absence as a missing app shell. A successful adoption only
+establishes config/baseline/guidance; audit incomplete authored content normally.
+
 ### Step 1: Inventory the Docs Surface
 
 Build a complete inventory of:
@@ -155,7 +165,7 @@ Capture the evidence sources that will justify later findings and recommendation
 Do **not** infer docs structure conventions from a tiny sample of pages when the broader
 tree or config disagrees.
 
-For OAT/Fumadocs docs apps, check whether local guidance covers:
+For configured Markdown and OAT/Fumadocs docs apps, check whether local guidance covers:
 
 - authored docs source location
 - generated root indexes or manifests and their no-hand-edit boundary
@@ -174,7 +184,7 @@ the current analyze/apply flow.
 
 Use `references/quality-checklist.md` and `references/directory-assessment-criteria.md`.
 
-For every documentation directory:
+For every non-excluded Markdown-bearing documentation directory:
 
 1. Verify `index.md` exists.
 2. Verify `index.md` includes a `## Contents` section.
@@ -190,6 +200,13 @@ For every documentation directory:
 9. Exempt asset-only directories that contain no Markdown content and are not
    linked as navigable docs sections.
 
+For Markdown, assess useful audience/scope context, nonempty title/description
+metadata, populated Contents, and relative `.md` links. Do not overwrite or
+recommend replacing existing context just to satisfy structure. Optional external
+manifests are separate derived artifacts: assess them only when local guidance
+actually declares one. Never require default generation or repoint an authored
+`documentation.index` to a manifest.
+
 For OAT/Fumadocs docs apps, also distinguish authored source maps from generated
 root indexes:
 
@@ -240,7 +257,7 @@ For each evaluated page or directory:
 
 1. Read the docs file plus the local evidence needed to validate its claims.
 2. Resolve every local relative Markdown link from the page where it appears.
-   Flag broken targets. In OAT/Fumadocs docs apps, flag extensionless local
+   Flag broken targets. In configured Markdown and OAT/Fumadocs docs apps, flag extensionless local
    Markdown links and prefer `.md`-suffixed targets, including
    `subdir/index.md`.
 3. Accept anchors on `.md` links, such as `page.md#section`, and do not flag
@@ -419,7 +436,10 @@ If `mkdocs.yml` exists:
 4. Flag directories whose `index.md` `## Contents` section appears inconsistent with nav structure.
 5. Flag docs guidance that claims structure, plugin support, or workflow rules not backed by current repo evidence.
 
-If neither `mkdocs.yml` nor a Fumadocs app exists, record whether the repo should be migrated to an OAT docs app.
+For Markdown, verify the authored Contents graph and file/link contract without
+site nav generation or builds. Lack of `mkdocs.yml`, a generated manifest, or an
+app package is expected, not a migration finding. For other unconfigured surfaces,
+record whether app migration is relevant only when evidence or user intent supports it.
 
 ### Step 7: Severity-Rate Findings
 

package/assets/skills/oat-docs-analyze/references/quality-checklist.md

@@ -4,7 +4,10 @@ Use this checklist when evaluating a docs surface.
 
 ## Structure
 
-- Every docs directory has an `index.md`.
+- Every non-excluded Markdown-bearing docs directory has an authored `index.md`.
+- Authored entrypoints preserve useful audience, scope, ownership, and context.
+- Authored pages have nonempty `title` and `description` metadata.
+- Configured excludes and existing local instructions are respected.
 - Every `index.md` includes a `## Contents` section.
 - `## Contents` is useful content, not a placeholder comment, empty list, or
   generic "add links here" scaffold.
@@ -22,7 +25,7 @@ Use this checklist when evaluating a docs surface.
 ## Links
 
 - Local relative Markdown links resolve from the page where they appear.
-- OAT/Fumadocs docs apps use `.md`-suffixed local links for docs pages,
+- Configured Markdown and OAT/Fumadocs docs apps use `.md`-suffixed local links for docs pages,
   including `subdir/index.md` for child directory maps.
 - Anchors on `.md` links are allowed, such as `page.md#section`.
 - Extensionless local docs links are flagged when local guidance follows the
@@ -58,7 +61,17 @@ Use this checklist when evaluating a docs surface.
 - Topic names are specific enough for agents to select the right page quickly.
 - Large sections summarize what each child page covers.
 
-## Docs App Contract
+## Documentation Surface Contract
+
+- For configured Markdown, `documentation.root` is the literal content root,
+  including when it contains a nested `docs` directory.
+- For Markdown, `documentation.index` is authored; optional generated manifests
+  live outside the full configured content tree and do not replace its entrypoint.
+- Markdown needs no app package, framework config, docs-root AGENTS, default
+  manifest, nav generation, installation, or site build. Use applicable existing
+  file/link/lint checks. Adoption alone is not proof of complete content conformity.
+- Managed root guidance, contributing guidance, and preserved local instructions
+  identify the root and authoring/audit/apply workflow.
 
 - For `mkdocs-app`, `mkdocs.yml` exists.
 - For `mkdocs-app`, navigation is consistent with the docs tree.

package/assets/skills/oat-docs-apply/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.3.2
+  version: 1.4.1
 ---
 
 # Docs Apply
@@ -106,6 +106,12 @@ Validate that each recommendation in the artifact includes:
 
 If the artifact is missing that detail, stop and tell the user to re-run `oat-docs-analyze`.
 
+Resolve the artifact target against `.oat/config.json` and cited local guidance.
+With `documentation.tooling: markdown`, the configured root is the literal
+content tree even when it contains a child `docs`; the configured index is
+authored. Preserve excludes, useful audience/context/ownership prose and existing
+local AGENTS files. A changed or incompatible target requires fresh analysis.
+
 ### Step 1: Build the Recommendation Plan
 
 Read the analysis artifact and build the plan from its recommendations.
@@ -117,7 +123,8 @@ Common docs actions:
 - Add or repair `## Contents`
 - Convert `overview.md` usage to the `index.md` contract
 - Add or update `docs/contributing.md` plugin guidance
-- Scaffold an OAT docs app when no docs app exists
+- Route approved setup/adoption to `oat-docs-bootstrap`; a Markdown tree does
+  not require app scaffolding
 - Run `oat docs nav sync` after approved structural changes
 
 Carry forward the artifact's evidence refs, confidence, disclosure mode, and link targets into the apply plan.
@@ -214,7 +221,17 @@ Negative rules:
 
 ### Step 5: Verify and Sync Navigation
 
-Run the smallest relevant verification set based on what changed:
+For configured Markdown, check touched authored indexes/context, nonempty
+title/description metadata, Contents reachability, sibling `.md` and child
+`section/index.md` destinations, configured excludes and local instructions.
+Keep existing context while applying only approved repairs. Run documented
+existing file/link/lint/format checks; no install or site build is required.
+Do not invoke default `generate-index` or site `nav sync`. Regenerate an optional
+external manifest only when locally declared, with explicit output outside the
+full configured content tree; keep the authored config index unchanged.
+
+For framework apps, discover actual scripts and run the smallest relevant
+verification set based on what changed; these examples apply only when present:
 
 - `oat docs nav sync`
 - `pnpm --dir <docs-app> docs:lint` (no-op when no linter is configured)

package/assets/skills/oat-docs-authoring/SKILL.md

@@ -1,28 +1,28 @@
 ---
 name: oat-docs-authoring
-description: Use when authoring or restructuring targeted content inside an existing OAT/Fumadocs docs app. Preserves OAT docs navigation, generated indexes, and validation boundaries.
+description: Use when authoring or restructuring targeted content inside an existing OAT Markdown surface or OAT/Fumadocs docs app. Preserves OAT docs navigation, generated indexes, and validation boundaries.
 argument-hint: '[docs task or target path]'
 disable-model-invocation: false
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 metadata:
-  version: 1.0.2
+  version: 1.1.1
 ---
 
 # OAT Docs Authoring
 
 Use this skill for targeted documentation authoring and small structural edits
-inside an existing OAT/Fumadocs docs app.
+inside an existing OAT Markdown surface or OAT/Fumadocs docs app.
 
 This is a thin wrapper over `authoring-docs`. Load `authoring-docs` for
 universal evidence gathering, page-type selection, writing style, templates,
-and review standards. Keep this wrapper focused on OAT/Fumadocs placement,
+and review standards. Keep this wrapper focused on OAT Markdown/Fumadocs placement,
 navigation, generated artifacts, validation, and lifecycle boundaries.
 
 ## Prerequisites
 
-- The repository already has an OAT/Fumadocs docs app or a clearly identified
-  target docs app that follows OAT conventions.
+- The repository already has an OAT Markdown surface, OAT/Fumadocs docs app,
+  or clearly identified documentation target that follows OAT conventions.
 - The task is a targeted authoring, restructuring, repair, or review task, not
   a new docs-app bootstrap, broad audit, or approved bulk-apply workflow.
 
@@ -31,7 +31,7 @@ navigation, generated artifacts, validation, and lifecycle boundaries.
 **OAT MODE: Docs Authoring Wrapper**
 
 **Purpose:** Author or restructure focused docs content while preserving the
-OAT/Fumadocs source-of-truth contract.
+OAT authored-source contract.
 
 **BLOCKED Activities:**
 
@@ -135,6 +135,10 @@ defaults, and asset-only exceptions.
 Prefer plain Markdown for content pages. Use MDX only when local guidance and
 the task require JSX or custom components.
 
+Markdown uses its literal configured root and authored index; preserve context,
+excludes, and local instructions even with a nested `docs` directory. No app
+package or docs-root AGENTS creation is needed.
+
 ### Step 4: Check Generated Artifacts and Validation
 
 Regenerate or freshness-check derived docs artifacts using local scripts when

package/assets/skills/oat-docs-authoring/references/docs-root-resolution.md

@@ -1,6 +1,6 @@
 ---
 title: OAT docs root resolution
-description: How to resolve OAT/Fumadocs app roots, authored docs roots, generated index outputs, and local instruction surfaces before editing.
+description: How to resolve Markdown content roots and OAT/Fumadocs app roots, authored docs roots, generated index outputs, and local instruction surfaces before editing.
 ---
 
 # OAT Docs Root Resolution
@@ -15,9 +15,15 @@ roots before editing.
      index file.
    - A docs-app `AGENTS.md` may override or narrow the repo-level guidance.
 2. Inspect `.oat/config.json`.
-   - Prefer documented `documentation.root` values for the docs app root.
-   - Treat `documentation.index` as the generated root index when present; it
-     may not be the same as the authored docs root.
+   - Declared tooling is authoritative. For `markdown`, `documentation.root`
+     is the literal authored content root, even with a child named `docs`, and
+     `documentation.index` is authored (normally `<root>/index.md`). Honor excludes.
+   - For framework tooling, prefer `documentation.root` as the docs app root.
+     Resolve authored source and generated ownership from app/local evidence;
+     a configured index alone is not proof that it is generated.
+   - Markdown requires no app package, framework config, site build, or manifest;
+     skip app-only discovery. An optional manifest must be external to the full
+     configured content tree and never replace the authored config index.
    - If config is incomplete, keep resolving from local files instead of
      guessing.
 3. Inspect package scripts in likely docs app directories.
@@ -34,7 +40,8 @@ roots before editing.
      paths can be wired separately. Preserve local customizations unless the
      user explicitly asked for app-shell work.
 5. Resolve the authored docs root.
-   - The common root is `<docs-app>/docs`, but local guidance is authoritative.
+   - Markdown uses the configured root itself. Framework apps commonly use
+     `<docs-app>/docs`, but local guidance is authoritative.
    - Find the top-level authored `index.md`, then follow `## Contents` maps to
      the target area.
 

package/assets/skills/oat-docs-authoring/references/lifecycle-boundaries.md

@@ -10,13 +10,13 @@ Route larger lifecycle work to its owner.
 
 ## Routing Rules
 
-| Request shape                                                           | Owner                      | Why                                                                                                                        |
-| ----------------------------------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| New docs app setup, scaffold repair, package/app shell bootstrap        | `oat-docs-bootstrap`       | Bootstrap owns preflight, inputs, `oat docs init`, post-scaffold checks, config inspection, and walkthrough.               |
-| Read-only docs audit, structure analysis, coverage review, drift report | `oat-docs-analyze`         | Analyze owns inventory, evidence gathering, severity-rated findings, and analysis artifacts.                               |
-| Applying approved analysis recommendations or batch docs changes        | `oat-docs-apply`           | Apply owns branch creation, approved changes, deterministic nav sync, verification, commit, and optional PR.               |
-| Docs updates derived from an active OAT project                         | `oat-project-document`     | Project-document owns artifact/code scanning, docs delta planning, approval, and project provenance.                       |
-| Existing MkDocs app to OAT/Fumadocs migration                           | Standalone migration guide | Migration needs inventory, syntax conversion, app-shell work, render checks, config/CI changes, and owner-review handling. |
+| Request shape                                                                             | Owner                      | Why                                                                                                                        |
+| ----------------------------------------------------------------------------------------- | -------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| New Markdown setup/adoption, docs app setup, scaffold repair, package/app shell bootstrap | `oat-docs-bootstrap`       | Bootstrap owns preflight, inputs, `oat docs init`, post-scaffold checks, config inspection, and walkthrough.               |
+| Read-only docs audit, structure analysis, coverage review, drift report                   | `oat-docs-analyze`         | Analyze owns inventory, evidence gathering, severity-rated findings, and analysis artifacts.                               |
+| Applying approved analysis recommendations or batch docs changes                          | `oat-docs-apply`           | Apply owns branch creation, approved changes, deterministic nav sync, verification, commit, and optional PR.               |
+| Docs updates derived from an active OAT project                                           | `oat-project-document`     | Project-document owns artifact/code scanning, docs delta planning, approval, and project provenance.                       |
+| Existing MkDocs app to OAT/Fumadocs migration                                             | Standalone migration guide | Migration needs inventory, syntax conversion, app-shell work, render checks, config/CI changes, and owner-review handling. |
 
 If a request mixes targeted authoring with lifecycle work, split it:
 

package/assets/skills/oat-docs-authoring/references/oat-fumadocs-contract.md

@@ -5,13 +5,15 @@ description: Authored source, navigation, link, file-type, generated-index, and
 
 # OAT Fumadocs Authoring Contract
 
-The OAT/Fumadocs contract is tooling-critical. It is not just style.
+The authored-source rules below also apply to configured plain Markdown.
+Framework-specific generated output and metadata controls remain conditional.
 
 ## Authored Source of Truth
 
 - Author content under the authored docs root, usually `docs/` inside the docs
-  app.
-- Every Markdown-bearing content directory has an authored `index.md`.
+  app; configured Markdown uses `documentation.root` literally.
+- Every non-excluded Markdown-bearing content directory has an authored `index.md`.
+- Preserve useful audience/scope context, ownership notes, and local instructions.
 - Every authored `index.md` that represents a content directory has a
   `## Contents` section.
 - `## Contents` lists sibling pages and immediate child directories for that
@@ -42,6 +44,14 @@ the task scope or an approved recommendation covers that change.
 - Add or preserve at least `title` and `description` frontmatter on touched
   pages unless local guidance defines a stricter schema.
 
+## Markdown Authored Index Ownership
+
+With `documentation.tooling: markdown`, `documentation.index` is authored.
+Edit its context and Contents directly within approved scope. No manifest is
+required. Optional generation needs explicit output outside the full configured
+content tree and cannot overwrite the authored index, even with narrowed source
+flags. Never repoint the config index to generated output.
+
 ## Generated Root Indexes
 
 Many OAT/Fumadocs apps have an app-root generated `index.md` that rolls up the

package/assets/skills/oat-docs-authoring/references/targeted-authoring-workflow.md

@@ -6,7 +6,7 @@ description: Focused edit loop for small OAT/Fumadocs documentation authoring an
 # Targeted OAT Docs Authoring Workflow
 
 Use this workflow when the user asks for a focused docs addition, repair, move,
-or review inside an existing OAT/Fumadocs docs app.
+or review inside an existing OAT Markdown surface or OAT/Fumadocs docs app.
 
 ## 1. Bound the Change
 
@@ -38,14 +38,15 @@ For page moves and renames:
 - update both the old parent and new parent `## Contents` sections;
 - search for links to the old path before finishing;
 - preserve optional local sidebar metadata, such as `meta.json`, when present;
-- regenerate or freshness-check the generated root index after authored maps
-  change;
+- regenerate or freshness-check declared derived output after authored maps
+  change; Markdown manifests are optional and external to the full content tree;
 - do not treat a generated-root entry as proof that the nearest parent map is
   correct.
 
 ## 4. Validate Locally
 
-- Read package scripts before choosing validation commands.
+- Read existing local scripts/instructions before choosing validation commands;
+  Markdown needs file/link checks, not an app package or site build.
 - Run generation or validation scripts that are relevant to the touched files.
 - For render-sensitive Markdown, inspect the rendered result when practical.
 

package/assets/skills/oat-docs-authoring/references/validation.md

@@ -8,7 +8,17 @@ description: Local validation, generated-index checks, and render spot-check gui
 Validation is local to the docs app. Read scripts and instructions before
 choosing commands.
 
-## Script Discovery
+## Markdown File Checks
+
+For configured Markdown, use the literal content root, honor excludes and local
+instructions, and verify context, title/description metadata, Contents and actual
+relative `.md` destinations. Discover existing repository lint/link/format checks;
+no package creation, install, site build, or site nav generation is required.
+An external generated manifest is optional; regenerate only when local guidance
+declares one, with explicit output outside the full content tree. Keep authored
+indexes and `documentation.index` intact.
+
+## Script Discovery (Framework Apps)
 
 Inspect the docs app `package.json` and local instructions for: