@open-agent-toolkit/cli 0.3.11 → 0.3.13

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

@@ -1,17 +1,17 @@
 ---
 name: oat-docs-bootstrap
-description: Use when bootstrapping a new OAT docs app in a repo. Guides the user through preflight detection, richer input gathering than the raw CLI, `oat docs init` invocation with gated post-patches for open CLI gaps, build verification, post-scaffold config inspection, and an educational walkthrough. Supports Fumadocs (full path) and MkDocs (lean path with defined minimum contract).
+description: Use when bootstrapping or adopting an OAT documentation surface in a repo. Guides the user through preflight detection, richer input gathering than the raw CLI, `oat docs init` invocation with gated post-patches for open CLI gaps, build verification, post-scaffold config inspection, and an educational walkthrough. Supports plain Markdown (file-level path), Fumadocs (full path), and MkDocs (lean path with defined minimum contract).
 argument-hint: '<optional-target-dir>'
 disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.2.2
+  version: 1.3.1
 ---
 
 # Docs Bootstrap
 
-Bootstrap a docs app in this repo and guide the user through understanding how it works. Wraps `oat docs init` with preflight detection, richer input gathering, gated post-patches for open CLI gaps (FP-11 Turbopack root, FP-12 site-title coherence, FP-13 template content, FP-15 docs-app AGENTS.md, FP-16 `## Contents` link extensions, FP-17 `contributing.md` three-surfaces cleanup), build verification, post-scaffold config inspection, and an educational walkthrough covering the `index.md` + `## Contents` navigation contract, scaffolded agent-instruction surfaces, and the OAT docs ecosystem (`oat-project-document`, `oat-docs-analyze`, `oat-docs-apply`).
+Bootstrap or adopt documentation in this repo and guide the user through understanding how it works. Wraps `oat docs init` with preflight detection, richer input gathering, gated post-patches for open CLI gaps (FP-11 Turbopack root, FP-12 site-title coherence, FP-13 template content, FP-15 docs-app AGENTS.md, FP-16 `## Contents` link extensions, FP-17 `contributing.md` three-surfaces cleanup), build verification, post-scaffold config inspection, and an educational walkthrough covering the `index.md` + `## Contents` navigation contract, scaffolded agent-instruction surfaces, and the OAT docs ecosystem (`oat-project-document`, `oat-docs-analyze`, `oat-docs-apply`).
 
 ## Prerequisites
 
@@ -23,7 +23,7 @@ Bootstrap a docs app in this repo and guide the user through understanding how i
 
 **OAT MODE: Docs Bootstrap**
 
-**Purpose:** Turn `oat docs init` scaffolding into a support-rich onboarding experience — preflight, inputs, CLI invocation with gated post-patches, build verification, config inspection, educational walkthrough, and optional content kickoff. Two framework paths: Fumadocs (full) and MkDocs (lean with defined minimum contract).
+**Purpose:** Turn `oat docs init` scaffolding into a support-rich onboarding experience — preflight, inputs, CLI invocation with gated post-patches, build verification, config inspection, educational walkthrough, and optional content kickoff. Three paths: Markdown (authored content without an app), Fumadocs (full), and MkDocs (lean with defined minimum contract).
 
 **BLOCKED Activities:**
 
@@ -110,6 +110,18 @@ OAT ▸ DOCS BOOTSTRAP
 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 ```
 
+### Markdown path through the seven steps
+
+The detailed framework procedures below apply to Fumadocs/MkDocs. When the selected tooling is `markdown`, use this path for Steps 2–7 instead; never run framework post-patches, the FP-15 AGENTS bridge, dependency discovery/install, package/Turbo patches, or a site build. Step 1 remains the shared read-only detector.
+
+1. **Preflight and routing:** Read `documentation.tooling` as either its string form or its legacy object `framework` field. Declared tooling is authoritative: configured Markdown uses `documentation.root` literally, including when it contains a child named `docs`; declared frameworks or unknown stacks are not plain-doc adoption candidates. With no declared tooling, check framework evidence first (`mkdocs.yml`, Fumadocs/Next config and docs-app package scripts/dependencies), then inspect the chosen dedicated content directory for authored `.md`/`.mdx` pages. A repository-root README alone is insufficient; an empty selected directory is fresh setup. For a populated plain tree, lead with **adopt and audit**, **audit only**, or **abort**. Audit only delegates read-only to `oat-docs-analyze` and exits. Adoption requires the explicit user choice and CLI `--adopt`; `--yes` alone never authorizes it. An incompatible declared root/index/tooling requires a user decision, with no silent clearing or retagging. Keep the existing explicitly authorized framework replacement path when a framework is selected.
+2. **Gather inputs:** Offer “Markdown (plain files), Fumadocs, or MkDocs?” Collect documentation title (`--site-name`), dedicated relative target directory (default `docs` in every repo shape), and optional description. Reuse an existing compatible configured Markdown root. Ask no app/package name, package-manager, site-runtime, or dependency questions. Lint and format default to `none`; describe selected existing repository tools only, without installing them. Validate a nonempty title and a dedicated in-repository target, excluding the repository root and escaping symlinks. Confirm fresh setup or additive adoption, title, root, and audit handoff. `appName` is absent and `conflictResolution` is `adopt`, `audit`, `abort`, or null for this path.
+3. **Invoke CLI:** Probe `$CLI_CMD docs init --help` and require advertised Markdown/`--adopt` support before invocation; if missing, report the needed CLI update rather than fabricating scaffold files. Run `$CLI_CMD docs init --framework markdown --target-dir <root> --site-name <title> --description <description> --lint none --format none --yes`, adding `--adopt` only for explicit adoption. Pass the selected lint/format values when using existing tools. Never pass app-only flags. An optional `--dry-run` previews file/config/guidance changes without writes; it does not count as a completed bootstrap. Capture terminal/JSON results, exact exit, created/preserved files, config changes, guidance action, and audit advice. `partial`/exit 1 with manual-required or blocked guidance means unresolved guidance; real runs may have created files, whereas dry-runs have only planned files. Report actual state and stop before claiming completion. Other refusals also stop without post-patches. For success, read config back to resolve the actual content root and authored index.
+4. **Verify files:** Print `[4/7] Verifying files…`. Check config root/index, baseline file existence, nonempty `title`/`description`, useful audience/scope context and populated `## Contents` links resolving to actual sibling pages or child `index.md`s. Honor excludes and asset-only exceptions; preserve local AGENTS instructions. Fresh setup creates only authored `index.md` and `contributing.md` in the target; verify no docs-root AGENTS, app package, framework config, dependencies, or root build changes. Run already documented lint/link/format checks when applicable; otherwise inspect files/links directly. Adoption preserves existing bytes and may leave missing child indexes, metadata, context, or links: record these as audit gaps for analyze/apply rather than repairing them or calling the tree fully conformant. Distinguish successful setup verification from content-conformance findings.
+5. **Inspect config:** `documentation.tooling` is the string `markdown`; `root` is the literal content directory; `index` is its authored entrypoint, normally `<root>/index.md`. Markdown introduces no `documentation.config`. Preserve unrelated config/excludes/completion settings. Verify deterministic managed root Documentation guidance names that root, Markdown tooling, authored index, and `<root>/contributing.md`; preserve manual/local guidance and surface unresolved disposition. The Step 5e completion opt-in remains available using the docs root rather than an app name, without silently changing an existing value. No nested app-config reconciliation or framework patch inspection applies.
+6. **Walkthrough:** In short chunks, show actual config and `<root>/index.md`: useful context plus the Contents map, title/description metadata, sibling `page.md` and child `section/index.md` links, exclusions and asset-only exceptions. Explain adding a page/section and updating the nearest authored map without overwriting existing context. Root AGENTS Documentation guidance and `<root>/contributing.md` establish agent/human conventions; a preexisting local AGENTS file remains authoritative, but bootstrap creates none. Authored indexes are edited directly. Optional generated inventories require explicit external output, e.g. `$CLI_CMD docs generate-index --docs-dir <root> --output .oat/docs-manifest.md`; output must stay outside the full configured content root and cannot overwrite the configured authored index even with a narrowed `--docs-dir`. Generation does not repoint `documentation.index`. Markdown bootstrap never generates a manifest automatically. Skip framework deep dives and preview-server/build commands.
+7. **Audit handoff and summary:** Offer `oat-docs-analyze` against the literal configured root, followed by `oat-docs-apply` only for approved repairs. An adopted incomplete tree needs that audit; config/guidance alone prove no full conformance. Explain `oat-project-document` for source-backed project deltas. Summarize tooling, actual root/authored index, created/preserved files, guidance/config disposition, file-check outcomes, unresolved audit gaps, optional manifest ownership, and exact skill handoff. For dry-run/partial/refusal, label the outcome accordingly rather than printing BOOTSTRAP COMPLETE. No app, install, build, patch, or dev-command fields apply.
+
 ### Step 1: Preflight Detector
 
 Inspect the working tree before any mutation. Determine the repo shape, detect existing docs setup, and surface conflicts that require user decisions later. This step is strictly read-only; any fix or prompt flows through the Input Gatherer (Step 2).
@@ -131,6 +143,8 @@ In practice: for Fumadocs, any single-package repo with a target subdirectory is
 
 **1b. Detect existing docs setup.**
 
+Apply the Markdown-path evidence and precedence rules above before classifying a directory. Record selected tooling and whether the chosen target is absent/empty, authored Markdown, or a framework app. An existing empty target is not an existing-app conflict. The same shared detector supports the Markdown route; it does not change general `oat init` detection.
+
 Read (do not modify):
 
 - `$REPO_ROOT/.oat/config.json`, extract the `documentation` section if present. Record `configDocumentation` (the parsed object) or `null`.
@@ -202,7 +216,7 @@ If `conflicts[]` is empty, skip conflict handling and go to 2b.
 
 Each question includes plain-language context explaining what the value affects. Defaults come from the Preflight Result. Ask sequentially — each answer can inform the next default.
 
-- **Framework.** `"Which docs framework? Fumadocs (Next.js, primary path) or MkDocs (Python, lean path)?"` Default: `fumadocs`.
+- **Framework.** `"Which documentation tooling? Markdown (plain files), Fumadocs (Next.js), or MkDocs (Python)?"` Default: `fumadocs`. Selecting Markdown switches to the Markdown path above before app/site questions.
 - **Site name.** `"What's the name of the product or project these docs are for?"` Default: `defaults.siteName` (humanized repo name). Explain: "This becomes the display title — what shows up in the site header, browser tab, and page headings. It is **not** the package name." This is the FP-12 workaround — distinct from `appName`.
 - **Package / app name.** `"What should the docs package be called?"` Default: `defaults.appName`. Explain: "This becomes the `package.json` `name`, the directory name, and the pnpm filter (e.g., `pnpm --filter {appName} dev`). It does **not** show up in the UI."
 - **Target directory.** `"Where should the docs app live?"` Default: `defaults.targetDir`. Explain: "Relative to repo root. Monorepos typically use `apps/{appName}`; single-package repos use `{appName}` as a subdirectory."
@@ -245,7 +259,7 @@ Record internally for the Scaffold Runner:
 
 ```
 Input Result:
-  framework: 'fumadocs' | 'mkdocs'
+  framework: 'markdown' | 'fumadocs' | 'mkdocs'
   siteName: string            // FP-12 workaround: display title distinct from appName
   appName: string
   targetDir: string
@@ -545,7 +559,9 @@ Per-file edits (Fumadocs only — MkDocs has no `layout.tsx`; its title handling
 
 Failure handling: if Capability Detection (3b) classified any of these files as `drift`, the patch is already recorded as `refused` in `Scaffold Result.patchesApplied` — skip and move on. Do not re-check drift here.
 
-**FP-15: AGENTS.md write-if-missing.**
+**FP-15: AGENTS.md write-if-missing (Fumadocs/MkDocs only).**
+
+Never apply this bridge to Markdown: its root is the content directory and bootstrap must not create a docs-root AGENTS file.
 
 Gate: run **only if** `capabilities.agentsMdScaffoldFlag === false` AND `<appRoot>/AGENTS.md` does not exist on disk.
 
@@ -1128,7 +1144,14 @@ End the skill with the summary. Do not prompt for more input — the user knows
 
 A successful `oat-docs-bootstrap` run satisfies every invariant below. Any failure of an invariant either blocks progression (critical) or is surfaced to the user in the Exit summary with a `suggestedFix` (warning) so the user knows what to address.
 
-**Pipeline invariants:**
+**Markdown invariants:**
+
+- Configured tooling controls routing; framework evidence precedes unconfigured plain-tree evidence; README-only and empty directories do not imply adoption.
+- Fresh/adopt operations use the CLI with literal roots; populated targets require explicit `--adopt`, preserved content remains authoritative, and audit gaps are handed to analyze/apply.
+- No app questions, installs, site builds, framework patches, automatic manifest, or docs-root AGENTS creation. Authored index/context/Contents/metadata/links and local instructions remain applicable.
+- Dry-run/partial outcomes report planned or actual state accurately; successful adoption is not a claim of full content conformity.
+
+**Framework pipeline invariants (Fumadocs/MkDocs):**
 
 - Preflight ran read-only — no files mutated, no config written, no scaffold invoked.
 - Input Gatherer collected the full Input Result (framework, siteName, appName, targetDir, siteDescription, lint, format) plus any `conflictResolution` required by Preflight conflicts; all inputs validated before scaffold.

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

@@ -1,3 +1,4 @@
+<!-- Framework docs-app bridge only: Fumadocs/MkDocs. Never render this template into a plain Markdown content root; use managed root Documentation guidance and the contributing page there. -->
 # AGENTS — {{SITE_NAME}}
 
 This file tells agents how to work inside `{{APP_DIR}}`, the documentation app for `{{REPO_NAME}}`. It is not bootstrap documentation. If you're looking for how this app was scaffolded, see `docs/getting-started.md` or the root-level `AGENTS.md` section on documentation.
@@ -11,7 +12,7 @@ This file tells agents how to work inside `{{APP_DIR}}`, the documentation app f
 1. Create the Markdown file under `docs/` at the directory that best matches the page's topic. Every content directory is an `index.md` map — find the right one before picking a path. **Prefer `.md`** for plain content pages; reach for `.mdx` only when the page actually needs embedded JSX (a custom component, an interactive widget, a specialized layout). Plain `.md` is the default because agents, linters, and grep rules all handle it more reliably than `.mdx`.
 2. Add frontmatter with at minimum `title:` and `description:`. The title drives nav display and page `<title>`; the description drives search previews, social cards, and sibling summaries. Empty descriptions hurt all three.
 3. Update the nearest `index.md`'s `## Contents` section to include a link to the new page. Use `.md`-suffixed relative links: `[Title](page.md)` for leaf pages, `[Section](subdir/index.md)` for subdirectories. The `@open-agent-toolkit/docs-transforms` remark-links plugin normalizes these for Fumadocs routing at build time (strips `.md`, collapses `dir/index.md` → `dir`), so the suffixed form renders correctly **and** lets agents follow links to the target file without path inference. The `## Contents` section is the machine-readable local map — anything not listed there is effectively invisible to the navigation tooling.
-4. If the new page introduces a new subdirectory, create an `index.md` in that subdirectory with its own `## Contents` section. Every content directory must have an `index.md`.
+4. If the new page introduces a new subdirectory, create an `index.md` in that subdirectory with its own `## Contents` section. Every Markdown-bearing content directory must have an `index.md`; asset-only directories are exempt. Preserve useful audience/scope context and honor configured excludes and existing local instructions.
 5. Regenerate the derived navigation artifacts for this framework. For Fumadocs, run `oat docs nav sync` (from the app directory, or with `--target-dir <app-dir>`) so the committed `docs/**/meta.json` sidebar files follow authored `## Contents`, and run the generated-index command (`{{GENERATE_INDEX_CMD}}`) so the app-root `index.md` manifest reflects the current Markdown file tree. Fumadocs nav sync is strict: a page no `## Contents` map lists stays out of the sidebar and is reported, so list the new page rather than editing `meta.json`. For MkDocs, run `oat docs nav sync` or the local equivalent so `mkdocs.yml` `nav:` reflects authored `## Contents`. Derived artifacts never replace the authored `## Contents`; keep authored maps current and compare generated output against them when checking freshness.
 
 ## When you need to restructure navigation

package/assets/skills/oat-project-document/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash(git:*), Bash(jq:*), Bash(oat pjm:*), Bash(oat project push:*), Bash(oat project scope:*), Bash(oat tools:*), Glob, Grep, AskUserQuestion, Skill
 metadata:
-  version: 1.8.5
+  version: 1.8.6
 ---
 
 # Project Documentation Sync
@@ -141,6 +141,14 @@ DOCS_TOOLING=$(oat config get documentation.tooling 2>/dev/null || true)
 DOCS_CONFIG=$(oat config get documentation.config 2>/dev/null || true)
 ```
 
+For `DOCS_TOOLING=markdown`, `$DOCS_ROOT` is the literal configured authored
+content root, even when a child directory is named `docs`; `documentation.index`
+is authored. Preserve context, metadata, Contents, relative `.md` links, excludes
+and existing local instructions. No app package, framework config, nav generation
+or site build is required. Optional external manifests never replace the authored
+index. For framework tooling, resolve the authored source root from config/scripts
+and local guidance before scanning; the configured root can be an app root.
+
 If `$DOCS_ROOT` is empty, attempt auto-detection:
 
 1. Look for `mkdocs.yml` — if found, set `DOCS_TOOLING=mkdocs` and infer `DOCS_ROOT` from the `docs_dir` field (or default to `docs/` relative to the mkdocs.yml location), set `DOCS_CONFIG` to the mkdocs.yml path
@@ -503,7 +511,18 @@ Execute the approved documentation updates.
    - Add a cross-reference in the original file pointing to the new location
    - If the original had sections that logically separate, use section headings as split boundaries
 
-**Nav structure updates:**
+**Authored maps and derived navigation:**
+
+Update the nearest authored `index.md` Contents for added/moved pages and preserve
+useful context. Validate actual relative `.md` destinations and title/description
+metadata, honoring excludes and local guidance. Markdown uses file/link checks
+and existing documented lint/format tools; it does not require site nav/build.
+Regenerate optional external manifests only when locally declared, with explicit
+output outside the full configured Markdown content tree; leave the configured
+authored index intact. For framework apps, regenerate declared navigation/index
+artifacts through local tooling rather than hand-editing generated output.
+
+**Framework config updates:**
 
 If `$DOCS_CONFIG` exists and new files were created in the docs directory:
 

package/assets/skills/recon/SKILL.md

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Glob, Grep, Bash, AskUserQuestion, Agent, mcp__*
 metadata:
-  version: 1.1.6
+  version: 1.1.7
 ---
 
 # Recon

package/assets/skills/recon/scripts/render-packet.mjs

@@ -9,9 +9,9 @@ import { isDirectExecution } from './lib/cli-entry.mjs';
 import {
   affirmingDispositionByReviewKind,
   classifyUnresolvedIssue,
-  requiredReviewKinds,
   unresolvedIssuesBlockClaim,
 } from './lib/contracts.mjs';
+import { reviewBriefEntries } from './lib/review-binding.mjs';
 import {
   assertSafeExistingPath,
   assertSafeOutputPath,
@@ -121,17 +121,34 @@ function intendedRoutingSection(manifest, routing) {
   ];
 }
 
-// The required reviews that gave `claimId` no disposition at all. Such a
-// claim stays below `verified`, like an uncertain one, and is listed as not
-// reviewed.
+const assuranceReviewKinds = Object.keys(affirmingDispositionByReviewKind);
+
+// The claim IDs a review was briefed on: the entries of the immutable brief
+// its exact reference resolves to, read the way the validator reads them.
+function briefedClaimIds(review, artifacts) {
+  const brief = artifacts.find(
+    ({ reference, value }) =>
+      value.kind === 'recon.review-brief' &&
+      reference.path === review.brief?.path &&
+      reference.digest === review.brief?.digest,
+  )?.value;
+  return new Set(
+    reviewBriefEntries(brief, review.reviewKind).map((entry) => entry.id),
+  );
+}
+
+// Every incorporated assurance review, core or thorough, whose brief listed
+// `claimId` but which gave it no disposition. Such a claim is listed as not
+// reviewed. A claim outside a review's brief was never that review's to
+// dispose of, so it is not an omission.
 function omittedReviews(claimId, reviews) {
-  return requiredReviewKinds
-    .map((kind) => reviews.find((review) => review.reviewKind === kind))
+  return reviews
     .filter(
-      (review) =>
-        review &&
-        !(review.dispositions ?? []).some((item) => item.claimId === claimId),
-    );
+      ({ value, briefed }) =>
+        briefed.has(claimId) &&
+        !(value.dispositions ?? []).some((item) => item.claimId === claimId),
+    )
+    .map(({ value }) => value);
 }
 
 function issueText(entry) {
@@ -140,8 +157,8 @@ function issueText(entry) {
 
 // Every claim an incorporated review kept below `verified` (an unresolved
 // issue that applies to it, a coverage finding that names it, a
-// non-affirming disposition, or a required review that left it without a
-// disposition), with the review's own words. Key-claim status
+// non-affirming disposition, or an assurance review that left a briefed claim
+// without a disposition), with the review's own words. Key-claim status
 // alone would let a `complete` packet hide a downgraded non-key claim.
 function reviewDowngradeLines(validatedRun) {
   const { ledger, artifacts, assuranceReviewIds } = validatedRun;
@@ -152,6 +169,16 @@ function reviewDowngradeLines(validatedRun) {
       (value) =>
         value.kind === 'recon.review-result' && assurance.has(value.id),
     );
+  // Claim-bearing assurance reviews in table order, each with its brief
+  // membership.
+  const briefedReviews = reviews
+    .filter((review) => assuranceReviewKinds.includes(review.reviewKind))
+    .map((value) => ({ value, briefed: briefedClaimIds(value, artifacts) }))
+    .sort(
+      (left, right) =>
+        assuranceReviewKinds.indexOf(left.value.reviewKind) -
+        assuranceReviewKinds.indexOf(right.value.reviewKind),
+    );
   const lines = [];
   for (const claim of ledger.claims) {
     if (claim.status === 'verified') continue;
@@ -182,7 +209,7 @@ function reviewDowngradeLines(validatedRun) {
         }
       }
     }
-    for (const review of omittedReviews(claim.id, reviews)) {
+    for (const review of omittedReviews(claim.id, briefedReviews)) {
       reasons.push(
         `${review.reviewKind} review: not reviewed (no disposition)`,
       );

package/assets/templates/docs-markdown/contributing.md

@@ -0,0 +1,35 @@
+---
+title: Contributing to documentation
+description: Authoring conventions, context, and Markdown navigation rules.
+---
+
+# Contributing to documentation
+
+Maintain documentation for **{{REPO_NAME}}** as authored Markdown pages. Start
+from the [documentation index](index.md) to understand the intended audience and
+where each topic belongs.
+
+## Structure and context
+
+- Give every Markdown-bearing directory an authored `index.md` with useful
+  context: purpose, audience, ownership, and how its pages relate.
+- Maintain a populated `## Contents` map. Link sibling pages as `page.md` and
+  immediate child directories as `section/index.md`. Link only existing files.
+- Asset-only directories do not need an index.
+- Add `title` and `description` metadata to authored pages. Use relative `.md`
+  links so navigation works when reading the repository directly.
+- Preserve existing local instructions and repository-specific guidance.
+
+## Review and verification
+
+Use `oat-docs-analyze` to identify content, metadata, and navigation gaps, then
+`oat-docs-apply` for approved repairs. Adoption establishes entrypoints and
+configuration; review the existing tree before treating it as complete.
+
+Check relative links, Contents maps, metadata, and context after edits. Selected
+existing tools: lint `{{LINT_MODE}}`, format `{{FORMAT_MODE}}`. Use repository
+checks when available; this setup does not install tools or require a site build.
+
+The authored index is not a generated manifest. If an optional inventory is
+needed, run `oat docs generate-index` with an explicit output outside the
+configured content tree and keep the authored entrypoint unchanged.

package/assets/templates/docs-markdown/index.md

@@ -0,0 +1,18 @@
+---
+title: '{{TITLE_METADATA}}'
+description: '{{DESCRIPTION_METADATA}}'
+---
+
+# {{SITE_NAME}}
+
+This is the documentation entrypoint for **{{REPO_NAME}}**. Start with this
+Contents map to find guidance and keep this page's context current as the
+repository evolves. Add the repository's purpose, audience, and key workflows
+when authoring its documentation.
+
+These pages are authored Markdown. The index belongs to contributors; optional
+generated inventories must live outside this content tree.
+
+## Contents
+
+{{CONTENTS}}

package/dist/commands/docs/index-generate/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,eAAO,MAAM,uBAAuB,iIAC4F,CAAC;AAuBjI,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,aAAa,EAAE,oBAAoB,KAChD,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5D,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC7D;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAomBD,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAgCT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAWA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAE9B,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAI5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,eAAO,MAAM,uBAAuB,iIAC4F,CAAC;AAuBjI,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,OAAO,aAAa,EAAE,oBAAoB,KAChD,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,cAAc,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvE,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAClD,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5D,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IAC5C,iBAAiB,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;CAC7D;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAspBD,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAgCT"}

package/dist/commands/docs/index-generate/index.js

@@ -197,7 +197,8 @@ function missingRootError(flag) {
  * options stay CWD-relative for backward compatibility. `documentation.root`
  * canonically names the docs **app root** written by `oat docs init`. The
  * `<root>/docs` preference is compatibility behavior for legacy configs whose
- * `root` names a docs *source* directory; `--docs-dir` overrides it.
+ * `root` names a docs *source* directory. Explicit Markdown uses the literal
+ * configured content root; `--docs-dir` overrides source selection in all modes.
  */
 async function resolveIndexGeneratePaths(context, options, deps) {
     const repoRoot = await deps.resolveRepoRoot(context.cwd);
@@ -206,6 +207,10 @@ async function resolveIndexGeneratePaths(context, options, deps) {
     const configuredRoot = configuredRootValue
         ? resolve(repoRoot, configuredRootValue)
         : null;
+    const isMarkdown = trimmed(config.documentation?.tooling)?.toLowerCase() === 'markdown';
+    if (isMarkdown && options.output === undefined) {
+        throw new CliError('Markdown documentation uses an authored index. Pass --output with a path outside the full configured Markdown content root to generate a separate manifest.', REFUSAL_EXIT_CODE);
+    }
     // Either omitted option needs a usable configured root, so validate it once
     // up front rather than only on the path that happens to be derived first.
     if (options.docsDir === undefined || options.output === undefined) {
@@ -226,7 +231,8 @@ async function resolveIndexGeneratePaths(context, options, deps) {
         docsDir = resolve(context.cwd, options.docsDir);
         docsDirSource = 'flag';
     }
-    else if (await deps.dirExists(join(configuredRoot, 'docs'))) {
+    else if (!isMarkdown &&
+        (await deps.dirExists(join(configuredRoot, 'docs')))) {
         docsDir = join(configuredRoot, 'docs');
         docsDirSource = 'config-docs-subdirectory';
     }
@@ -263,6 +269,10 @@ async function canonicalizeIndexGeneratePaths(resolved, deps) {
     const lexicalDocumentationConfig = documentationConfigValue
         ? resolve(resolved.repoRoot, documentationConfigValue)
         : null;
+    const isMarkdown = trimmed(resolved.config.documentation?.tooling)?.toLowerCase() ===
+        'markdown';
+    const indexValue = trimmed(resolved.config.documentation?.index);
+    const lexicalAuthoredIndex = isMarkdown && indexValue ? resolve(resolved.repoRoot, indexValue) : null;
     // Resolution order is load-bearing: the docs directory is canonicalized
     // first, and the safety checks below compare against its canonical form.
     return {
@@ -277,11 +287,24 @@ async function canonicalizeIndexGeneratePaths(resolved, deps) {
             role: { kind: 'output' },
             origin: resolved.outputPath,
         }),
-        // An unusable configured root only makes the config write ineligible; it
-        // must not fail a run whose paths were both supplied explicitly.
+        // Markdown's configured tree is protected independently of --docs-dir.
+        // Its canonicalization must fail closed; other modes retain the existing
+        // tolerance for unusable config when both paths are explicit.
         configuredRoot: resolved.configuredRoot
-            ? await canonicalizeOrNull(resolved.configuredRoot, deps, {
-                kind: 'other',
+            ? isMarkdown
+                ? await canonicalize(resolved.configuredRoot, deps, {
+                    role: { kind: 'docs-dir', derived: true },
+                    origin: resolved.configuredRoot,
+                })
+                : await canonicalizeOrNull(resolved.configuredRoot, deps, {
+                    kind: 'other',
+                })
+            : null,
+        lexicalAuthoredIndex,
+        authoredIndex: lexicalAuthoredIndex
+            ? await canonicalize(lexicalAuthoredIndex, deps, {
+                role: { kind: 'other' },
+                origin: lexicalAuthoredIndex,
             })
             : null,
         lexicalDocumentationConfig,
@@ -301,6 +324,16 @@ async function canonicalizeIndexGeneratePaths(resolved, deps) {
  */
 async function assertOutputIsSafe(resolved, canonical, deps) {
     const { docsDir, outputPath, outputIsExplicit } = resolved;
+    if (trimmed(resolved.config.documentation?.tooling)?.toLowerCase() ===
+        'markdown' &&
+        ((canonical.configuredRoot !== null &&
+            isAtOrInside(canonical.configuredRoot, canonical.outputPath)) ||
+            (resolved.configuredRoot !== null &&
+                isAtOrInside(resolved.configuredRoot, outputPath)) ||
+            canonical.outputPath === canonical.authoredIndex ||
+            outputPath === canonical.lexicalAuthoredIndex)) {
+        throw new CliError(`Refusing to write the generated index to protected Markdown documentation at ${outputPath}: the full configured content root and authored documentation.index must be preserved. Pass --output with a different path outside the Markdown content root.`, REFUSAL_EXIT_CODE);
+    }
     if (isAtOrInside(canonical.docsDir, canonical.outputPath)) {
         throw new CliError(`Refusing to write the generated index inside the docs directory it indexes: ` +
             `${outputPath} is inside ${docsDir}. Pass --output with a path outside the docs directory.`, REFUSAL_EXIT_CODE);
@@ -449,8 +482,8 @@ export function createDocsGenerateIndexCommand(overrides = {}) {
     };
     return new Command('generate-index')
         .description('Generate a docs index from markdown files')
-        .addOption(new Option('--docs-dir <path>', 'Documentation source directory, resolved from the CWD (default: `<documentation.root>/docs` when that directory exists, otherwise `<documentation.root>`)'))
-        .addOption(new Option('--output <path>', 'Output file path, resolved from the CWD (default: `<documentation.root>/index.md`)'))
+        .addOption(new Option('--docs-dir <path>', 'Documentation source directory, resolved from the CWD (default: literal `<documentation.root>` for Markdown; otherwise `<documentation.root>/docs` when that directory exists, or `<documentation.root>`)'))
+        .addOption(new Option('--output <path>', 'Output file path, resolved from the CWD (required outside the content root for Markdown; otherwise default: `<documentation.root>/index.md`)'))
         .addOption(new Option('--exclude <glob>', 'Exclude matching paths, relative to the docs directory (`*` within a segment, `**` across segments, trailing `/` for directories only). Repeatable, and additive to `documentation.excludes`').argParser(collectExclude))
         .action(async (options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));

package/dist/commands/docs/init/index.d.ts

@@ -1,5 +1,5 @@
 import { type CommandContext, type GlobalOptions } from '../../../app/command-context.js';
-import { type UpsertSectionResult } from '../../shared/agents-md.js';
+import { type UpsertSectionResult, previewAgentsMdSection } from '../../shared/agents-md.js';
 import { type PromptContext, type SelectChoice } from '../../shared/shared.prompts.js';
 import { type OatConfig } from '../../../config/oat-config.js';
 import { Command } from 'commander';
@@ -8,7 +8,21 @@ import { type RootPackagePatchResult } from './root-package.js';
 interface DocsInitExecutionResult {
     createdFiles: string[];
     appRoot: string;
-    rootPackagePatch: RootPackagePatchResult;
+    rootPackagePatch?: RootPackagePatchResult;
+    dryRun?: boolean;
+    plannedFiles?: string[];
+    preservedFiles?: string[];
+    incompleteFiles?: string[];
+    auditAdvice?: string[];
+    changes?: {
+        files: string[];
+        config: boolean;
+    };
+    configStatus?: 'planned' | 'updated' | 'no-change' | 'failed' | 'not-attempted';
+    failure?: {
+        stage: 'scaffold' | 'config';
+        message: string;
+    };
 }
 interface DocsInitDependencies {
     buildCommandContext: (options: GlobalOptions) => CommandContext;
@@ -18,6 +32,7 @@ interface DocsInitDependencies {
     selectWithAbort: <T extends string>(message: string, choices: SelectChoice<T>[], ctx: PromptContext) => Promise<T | null>;
     runDocsInit: (context: CommandContext, options: DocsInitResolvedOptions, assetsRoot: string) => Promise<DocsInitExecutionResult | void>;
     upsertAgentsMdSection: (repoRoot: string, key: string, body: string) => Promise<UpsertSectionResult>;
+    previewAgentsMdSection: typeof previewAgentsMdSection;
     readOatConfig: (repoRoot: string) => Promise<OatConfig>;
     confirmAction: (message: string, ctx: PromptContext) => Promise<boolean>;
 }

package/dist/commands/docs/init/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,mBAAmB,EAIzB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAG5C,OAAO,EAIL,KAAK,uBAAuB,EAK7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,gBAAgB,CAAC;AAexB,UAAU,uBAAuB;IAC/B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,EAAE,sBAAsB,CAAC;CAC1C;AAED,UAAU,oBAAoB;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,gBAAgB,CAAC,CAAC;IAC9E,gBAAgB,EAAE,CAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,SAAS,MAAM,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,EAC1B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvB,WAAW,EAAE,CACX,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,uBAAuB,EAChC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAC;IAC7C,qBAAqB,EAAE,CACrB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClC,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AAqGD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAuB7E;AA6JD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CA6CT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"AAEA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,mBAAmB,EAGxB,sBAAsB,EAEvB,MAAM,4BAA4B,CAAC;AACpC,OAAO,EAGL,KAAK,aAAa,EAClB,KAAK,YAAY,EAElB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,EACL,KAAK,SAAS,EAGf,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAU5C,OAAO,EAIL,KAAK,uBAAuB,EAK7B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,gBAAgB,CAAC;AAgBxB,UAAU,uBAAuB;IAC/B,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,gBAAgB,CAAC,EAAE,sBAAsB,CAAC;IAC1C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,cAAc,CAAC,EAAE,MAAM,EAAE,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,OAAO,CAAA;KAAE,CAAC;IAC/C,YAAY,CAAC,EACT,SAAS,GACT,SAAS,GACT,WAAW,GACX,QAAQ,GACR,eAAe,CAAC;IACpB,OAAO,CAAC,EAAE;QAAE,KAAK,EAAE,UAAU,GAAG,QAAQ,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC7D;AAED,UAAU,oBAAoB;IAC5B,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,iBAAiB,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;IACzC,eAAe,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,UAAU,GAAG,gBAAgB,CAAC,CAAC;IAC9E,gBAAgB,EAAE,CAChB,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC5B,eAAe,EAAE,CAAC,CAAC,SAAS,MAAM,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,EAC1B,GAAG,EAAE,aAAa,KACf,OAAO,CAAC,CAAC,GAAG,IAAI,CAAC,CAAC;IACvB,WAAW,EAAE,CACX,OAAO,EAAE,cAAc,EACvB,OAAO,EAAE,uBAAuB,EAChC,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAAC;IAC7C,qBAAqB,EAAE,CACrB,QAAQ,EAAE,MAAM,EAChB,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClC,sBAAsB,EAAE,OAAO,sBAAsB,CAAC;IACtD,aAAa,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,SAAS,CAAC,CAAC;IACxD,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,aAAa,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CAC1E;AAuLD;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAoC7E;AA0QD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CAiET"}