@open-agent-toolkit/cli 0.1.26 → 0.1.28

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

@@ -104,14 +104,15 @@ Key behavior:
 - Same pack selection and install flow as `oat init tools`
 - Pack-oriented install subcommands: `core`, `docs`, `ideas`, `workflows`, `utility`, `project-management`, `research`, `brainstorm`
 - Interactive installs show each pack's current install location in the picker so already-installed packs are visible before you submit
-- User-scope follow-up choices are prepopulated from the current install state for user-eligible packs (`ideas`, `docs`, `utility`, `research`, `brainstorm`)
-- The `brainstorm` pack defaults to user scope on fresh installs (driven by `PACK_METADATA[brainstorm].defaultScope = 'user'`); existing project-scope installs still take precedence on re-install so users do not get unexpected scope migrations
-- If a user-eligible pack is already installed in both project and user scope, the installer asks whether to keep both installs or normalize the pack to user scope before it makes any cleanup changes
-- Changing a user-eligible pack from project scope to user scope, or back again, is treated as a migration: the old canonical copy is removed so the pack ends in the selected scope instead of accumulating duplicate installs
+- Installing is **additive**: choosing a scope for a pack never removes it from another scope. A user-eligible pack installed at user scope plus a project install ends up at `project + user`, not moved
+- For each user-eligible pack (`ideas`, `docs`, `utility`, `research`, `brainstorm`), the interactive flow offers a per-pack end-state selector (`project`, `user`, or `both`) defaulting to the pack's current placement; leaving the default makes no changes for that pack
+- The `brainstorm` pack defaults to user scope on fresh installs (driven by `PACK_METADATA[brainstorm].defaultScope = 'user'`); existing installs keep their current placement on re-install, so a re-install never moves a pack between scopes
+- Removing a pack from a scope happens only when you explicitly choose a narrower end-state in the interactive flow (e.g. a pack at `both` set to `project` only). All staged removals are shown in a single change summary and applied only after one batch confirmation — declining makes no changes
+- Non-interactive installs (including `--scope project`, `--scope user`, and the default pack set) are strictly additive and never remove a pack from a scope. Removal is interactive-only
 - Tracks installed vs bundled skill versions and reports outdated skills
 - Records installed pack state in shared repo config as `tools.<pack>: true` so other OAT workflows can detect installed capabilities without relying on filesystem heuristics
 - Interactive runs can prompt to update selected outdated skills
-- Successful installs report the final scope chosen for each pack, including `project + user` when both installs are preserved, and auto-sync every scope touched by the install or migration
+- Successful installs report the final scope chosen for each pack, including `project + user` when a pack is installed in both, and auto-sync only the scopes actually changed by the install so untouched scopes are never re-synced or pruned
 - Install-triggered auto-sync limits removal planning to the canonical entries from the pack that was just installed, so stale manifest drift in unrelated packs does not delete other provider views
 - Use `--no-sync` to skip auto-sync
 

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.1.26",
-  "docs-config": "0.1.26",
-  "docs-theme": "0.1.26",
-  "docs-transforms": "0.1.26"
+  "cli": "0.1.28",
+  "docs-config": "0.1.28",
+  "docs-theme": "0.1.28",
+  "docs-transforms": "0.1.28"
 }

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

@@ -1,7 +1,7 @@
 ---
 name: oat-docs-bootstrap
-version: 1.1.0
-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 labeled 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).
+version: 1.2.0
+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).
 argument-hint: '<optional-target-dir>'
 disable-model-invocation: true
 user-invocable: true
@@ -10,7 +10,7 @@ allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 
 # 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, labeled 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 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`).
 
 ## Prerequisites
 
@@ -22,7 +22,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 labeled 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. Two framework paths: Fumadocs (full) and MkDocs (lean with defined minimum contract).
 
 **BLOCKED Activities:**
 
@@ -36,7 +36,7 @@ Bootstrap a docs app in this repo and guide the user through understanding how i
 - Inspecting repo state read-only before any mutation
 - Prompting the user for richer inputs than the CLI asks for (notably a site name separate from the package/app name)
 - Invoking `oat docs init` non-interactively with collected flags
-- Applying labeled, idempotent post-patches for open CLI gaps (FP-11/FP-12/FP-13/FP-15/FP-16/FP-17) only when capability detection shows the CLI has not addressed them
+- Applying gated, idempotent post-patches for open CLI gaps (FP-11/FP-12/FP-13/FP-15/FP-16/FP-17) only when capability detection shows the CLI has not addressed them
 - Running install + build and classifying failures against known patterns
 - Reading `.oat/config.json` back to verify paths and prompting for `requireForProjectCompletion`
 - Narrating the scaffolded output as a chunked educational walkthrough
@@ -151,7 +151,7 @@ Conflicts are **recorded**, not **resolved**. Resolution happens in Step 2 (Inpu
 Derive:
 
 - `repoName`: `basename($REPO_ROOT)`
-- `siteName` default: humanized form of `repoName` (e.g., `cyclone-app` → `Cyclone App`, `vox_mobile` → `Vox Mobile`, `docs` → `Docs`). Do not append " Documentation" here — that's a concern of the scaffold, not of the default.
+- `siteName` default: humanized form of `repoName` (e.g., `cyclone-app` → `Cyclone App`, `vox_mobile` → `Vox Mobile`, `docs` → `Docs`). Do not append " Documentation" here; the CLI and skill use the display title verbatim.
 - `appName` default:
   - If shape is `monorepo`: `{repoName}-docs` (e.g., `open-agent-toolkit-docs`)
   - If shape is `single-package` or `nested-standalone`: `docs`
@@ -226,7 +226,7 @@ Before proceeding to scaffold, summarize what the user chose and confirm:
 Here's what I'll scaffold:
 
   Framework:       {framework}
-  Display title:   {siteName} Documentation   ← shown in header / tab / page headings
+  Display title:   {siteName}   ← shown in header / tab / page headings
   Package name:    {appName}                   ← used by pnpm filter / directory name
   Target dir:      {targetDir}                 ← relative to repo root
   Description:     {siteDescription | "(none)"}
@@ -342,7 +342,7 @@ If any mutation fails or any invariant check fails, **stop the flow before scaff
 
 ### Step 3: Scaffold Runner
 
-Invoke `oat docs init` with the collected inputs and then apply labeled post-patches for any CLI gaps the Capability Detection sub-procedure reports as still-open. The Scaffold Runner has four phases: **CLI invocation** (authored here), **Capability Detection** (p03-t02), **site-identity patches** (p03-t03), and **scaffold-integrity patches** (p03-t04).
+Invoke `oat docs init` with the collected inputs and then apply gated post-patches for any CLI gaps the Capability Detection sub-procedure reports as still-open. The Scaffold Runner has four phases: **CLI invocation** (authored here), **Capability Detection** (p03-t02), **site-identity patches** (p03-t03), and **scaffold-integrity patches** (p03-t04).
 
 Print `[3/7] Scaffolding…` at the start of this step.
 
@@ -356,7 +356,7 @@ Base flags (always passed):
 
 - `--yes` — non-interactive
 - `--framework {framework}` — from Input Result
-- `--name {appName}` — from Input Result
+- `--app-name {appName}` — from Input Result
 - `--target-dir {targetDir}` — from Input Result
 - `--description {siteDescription}` — from Input Result (pass empty string if user left blank)
 - `--lint {lint}` — from Input Result
@@ -365,6 +365,7 @@ Base flags (always passed):
 Capability-gated flags (added only when the Capability Probe reports support):
 
 - `--site-name {siteName}` — only if `capabilities.siteNameFlag === true` (FP-12 upstream fix landed). If `false`, **do not pass it**, and queue the FP-12 post-patch instead (applied in p03-t03).
+- `--no-root-patch` — only if `capabilities.noRootPatchFlag === true` and the Preflight / Conflict Resolution result says root package mutation should be skipped. This is recommended for no-root-package repositories or when the user explicitly chose no root mutation; current CLI builds also auto-skip when no root `package.json` exists, so the flag is optional documentation of intent, not a recovery mechanism.
 
 Do not pass flags the CLI doesn't advertise. Never assume a flag exists because the skill wants it — the Capability Probe is the source of truth for what's safe to pass.
 
@@ -377,6 +378,7 @@ Before CLI invocation, probe the installed CLI to discover which FP-11 / FP-12 /
 - `siteNameFlag` — `true` if `--site-name` (or equivalent alias like `--title`) appears in the help output. Implies FP-12 upstream fix has landed.
 - `turbopackRootFlag` — `true` if a flag for forwarding a Turbopack root (or a `--framework-config` passthrough that accepts `turbopack.root`) appears. Implies FP-11 fix has landed in some form.
 - `agentsMdScaffoldFlag` — `true` if the help output mentions `AGENTS.md` scaffolding or the CLI's scaffold template list includes `AGENTS.md`. Implies FP-15 fix has landed.
+- `noRootPatchFlag` — `true` if `--no-root-patch` appears in help output. If supported, pass it when root package mutation should be skipped rather than relying only on auto-skip behavior.
 
 For FP-16, there is no CLI-level help-probe marker; the capability is detected purely by file-shape check on the scaffolded `docs/index.md` (see below). When the CLI scaffold template is fixed upstream, the file-shape check will classify as `patched-shape` and the FP-16 patch will skip automatically.
 
@@ -387,24 +389,24 @@ If the `--help` invocation fails (non-zero exit or empty stdout), treat all capa
 For each patch, the classification rule is:
 
 - **FP-12 targets** — the patch sets display-title references in four files:
-  - `<appRoot>/app/layout.tsx` (Fumadocs only): scaffold shape has `DocsLayout` with `branding: { title: '{appName}' }` (the CLI writes the package name); patched shape has `branding: { title: '{siteName}' }` surrounded by `<!-- FP-12 patch -->` markers.
-  - `<appRoot>/docs/index.md`: scaffold shape has frontmatter `title: '{appName}'` and `# {appName}` H1; patched shape substitutes `{siteName}` in both positions.
-  - `<appRoot>/docs/getting-started.md`: scaffold shape has a body reference to `{appName}`; patched shape uses `{siteName}`.
-  - `<appRoot>/docs/contributing.md`: scaffold shape has `# {appName}` H1; patched shape uses `{siteName}`.
-  - Classification: if the marker string (`appName` where expected in scaffold shape, `siteName` where expected in patched shape) matches exactly, the file is in that shape. If neither pattern matches (e.g., the user already renamed things manually), classify as `drift`.
+  - `<appRoot>/app/layout.tsx` (Fumadocs only): scaffold shape has `DocsLayout` with `branding` pointing at `{appName}` and no `export const metadata`; patched/upstream shape has `branding.title` using `{siteName}` and module-scope Next metadata. Code-file patches may use `/* FP-12 */` markers where syntactically valid.
+  - `<appRoot>/docs/index.md`: scaffold shape has frontmatter `title: '{appName}'` and `# {appName}` H1; patched/upstream shape substitutes `{siteName}` in both positions. Do not add hidden FP comments to rendered Markdown; use content shape for idempotency.
+  - `<appRoot>/docs/getting-started.md`: scaffold shape has a body reference to `{appName}`; patched/upstream shape uses `{siteName}`.
+  - `<appRoot>/docs/contributing.md`: scaffold shape has `# {appName}` H1; patched/upstream shape uses `{siteName}`.
+  - Classification: if the expected literal (`appName` for scaffold shape, `siteName` for patched/upstream shape) matches exactly, the file is in that shape. If neither pattern matches (e.g., the user already renamed things manually), classify as `drift`.
 - **FP-11 target** — `<appRoot>/next.config.js` (Fumadocs, nested-standalone only):
   - Scaffold shape: single-line `export default createDocsConfig()` or near-equivalent with no `turbopack` option.
   - Patched shape (via passthrough): `createDocsConfig({ turbopack: { root: __dirname } })` plus `<!-- FP-11 patch -->` marker comment.
   - Patched shape (via wrapper replacement): explicit `createMDX()` + hand-written config with `turbopack: { root: __dirname }` and the `<!-- FP-11 patch -->` marker.
   - Classification: pattern-match on the wrapper call or the `createMDX()` import; any other shape is `drift`.
-- **FP-13 targets** — the five sub-findings (empty descriptions, bare commands, false lint claim, generated-file warning, Node version mismatch) each target a specific line or section (see design.md). Scaffold shape for each is "unchanged CLI scaffold output"; patched shape has the `<!-- FP-13 patch -->` marker comment adjacent to the rewrite. Sub-finding E (Node version) additionally reads `.nvmrc` / `package.json` `engines.node` at scaffold time to determine the correct version to write.
+- **FP-13 targets** — the five sub-findings (empty descriptions, bare commands, false lint claim, old authored-file generated warning, Node version mismatch) each target a specific line or section. Scaffold shape for each is "unchanged historical CLI scaffold output"; patched/upstream shape is the corrected content. Markdown patches do not add hidden FP comments; they classify by content shape. Sub-finding E (Node version) additionally reads `.nvmrc` / `package.json` `engines.node` at scaffold time to determine the correct version to write.
 - **FP-16 target** — `<appRoot>/docs/index.md` `## Contents` section (Fumadocs only):
   - Scaffold shape: `## Contents` list items have extension-less link targets, e.g. `- [Getting Started](getting-started) - ...`. Detect by regex-matching bulleted list items where the link target is a slug (no file extension, no trailing slash) that corresponds to a real `.md` file in the same directory (or an `index.md` inside a matching subdirectory).
-  - Patched shape: `## Contents` list items have `.md`-suffixed link targets (e.g. `- [Getting Started](getting-started.md) - ...`) with a `<!-- FP-16 patch -->` / `<!-- /FP-16 patch -->` marker wrapping the whole `## Contents` block.
+  - Patched/upstream shape: `## Contents` list items have `.md`-suffixed link targets (e.g. `- [Getting Started](getting-started.md) - ...`). No hidden FP comments are added to rendered Markdown.
   - Drift: neither scaffold nor patched shape — likely user-edited with mixed or inconsistent extensions. Record as `refused` with a suggested manual fix ("normalize all `## Contents` links to `.md`-suffixed form so the `docs-transforms` remark-links plugin handles routing").
 - **FP-17 target** — `<appRoot>/docs/contributing.md` `## Agent guidance` section (Fumadocs only):
   - Scaffold shape: the section contains a short bulleted list of generic agent advice (typically two bullets: treating `index.md` as truth, preferring links to source files). Detect by matching the `## Agent guidance` heading followed by a small bulleted list.
-  - Patched shape: the section contains a one-paragraph pointer to the docs-app `AGENTS.md`, wrapped in `<!-- FP-17 patch: three-surfaces cleanup -->` / `<!-- /FP-17 patch -->` markers.
+  - Patched/upstream shape: the section contains a one-paragraph pointer to the docs-app `AGENTS.md`. No hidden FP comments are added to rendered Markdown.
   - Drift: user-edited with content beyond the scaffold bullets (paragraphs, custom agent rules, links to other files). Classify as `refused` — do not collapse user-authored content; instead suggest the user move custom guidance into `<appRoot>/AGENTS.md` and trim `contributing.md` to the pointer form manually.
 - **FP-15 target** — `<appRoot>/AGENTS.md`:
   - Scaffold shape: file **does not exist** (current CLI doesn't scaffold it).
@@ -451,7 +453,7 @@ Capture both stdout and stderr. **Do not** stream output directly to the user; t
   oat docs init exited with code 2.
 
   Flags passed:
-    --yes --framework fumadocs --name docs --target-dir docs
+    --yes --framework fumadocs --app-name docs --target-dir docs
     --description "" --lint none --format oxfmt
 
   CLI stderr:
@@ -485,7 +487,7 @@ Each patch:
 
 - Reads the relevant capability flag from `Scaffold Result.capabilities` and the file-shape detection from Capability Detection (3b).
 - Runs only if the capability is **absent** (the CLI didn't already address the gap) AND the file-shape check passes.
-- Is **labeled** with a comment marker (e.g., `<!-- FP-12 patch -->`) so it can be found and removed deterministically when the CLI fix lands upstream.
+- Uses a marker comment only in code files where the comment syntax is valid (`/* FP-NN */` in TSX/JS, `// ...` where appropriate). Rendered Markdown patches do **not** add hidden `<!-- FP-NN -->` comments; they rely on content-shape idempotency and drift checks, and they defer to the project's normal comment conventions for user-facing prose.
 - Is **idempotent** — running the patch twice is a no-op.
 - Appends an entry to `Scaffold Result.patchesApplied` with `{ id, status: 'applied' | 'skipped' | 'refused', reason? }`.
 
@@ -506,7 +508,7 @@ Per-file edits (Fumadocs only — MkDocs has no `layout.tsx`; its title handling
   ```tsx
   /* FP-12 patch: site metadata */
   export const metadata = {
-    title: '{siteName} Documentation',
+    title: '{siteName}',
     description: '{siteDescription}',
   };
   /* /FP-12 patch */
@@ -519,24 +521,26 @@ Per-file edits (Fumadocs only — MkDocs has no `layout.tsx`; its title handling
   - Setting `branding.title` alone and calling it done. `branding` populates nav chrome only; browser tab, search previews, and social cards all read `metadata`.
   - Inserting `metadata` into a non-layout file (e.g., `page.tsx` under `[[...slug]]`). For site-wide metadata, `layout.tsx` is the authoritative location.
 
-- **`<appRoot>/app/layout.tsx` — `branding.title`.** Scaffold shape has `branding: { title: '{appName}' }`. Replace the literal string value with `{siteName}` (the user-supplied display title) wrapped in FP-12 markers:
+- **`<appRoot>/app/layout.tsx` — `branding.title`.** Scaffold shape has `branding: { title: '{appName}' }`. Replace the literal string value with `{siteName}` (the user-supplied display title). If adding a marker, put it inside the object literal where TSX accepts JavaScript comments:
 
   ```tsx
-  <!-- FP-12 patch: branding title -->
-  branding={{ title: '{siteName}' }}
-  <!-- /FP-12 patch -->
+  branding={{
+    /* FP-12 patch: branding title */
+    title: '{siteName}',
+    /* /FP-12 patch */
+  }}
   ```
 
-  Idempotency: if the marker `<!-- FP-12 patch: branding title -->` is already present, skip and record `status: 'skipped'`. This is the nav-chrome display title — a separate concern from the metadata export above.
+  Idempotency: if `branding.title` already equals `{siteName}` or the marker is already present, skip and record `status: 'skipped'`. This is the nav-chrome display title — a separate concern from the metadata export above.
 
 - **`<appRoot>/docs/index.md`.** Two edits:
   1. Frontmatter `title: '{appName}'` → `title: '{siteName}'`.
   2. First H1 `# {appName}` → `# {siteName}`.
-     Wrap each edit with HTML-comment markers (`<!-- FP-12 patch: index title -->` / `<!-- /FP-12 patch -->` around the frontmatter line; same pattern around the H1 line). Idempotency: marker absence = scaffold shape, safe to patch; marker present = already patched, skip.
+     Do not add hidden FP comments. Idempotency: `{appName}` in both expected places = scaffold shape, safe to patch; `{siteName}` in both expected places = patched/upstream shape, skip; mixed or unexpected text = drift.
 
-- **`<appRoot>/docs/getting-started.md`.** Body contains references to `{appName}` in the intro paragraph (per the scaffold template). Replace those references with `{siteName}`, wrapped in an HTML-comment marker on the first occurrence. Idempotency: marker absence = patch; marker present = skip.
+- **`<appRoot>/docs/getting-started.md`.** Body contains references to `{appName}` in the intro paragraph (per the historical scaffold template). Replace those references with `{siteName}`. Do not add hidden FP comments; classify by literal content shape.
 
-- **`<appRoot>/docs/contributing.md`.** H1 `# {appName}` → `# {siteName}`, same marker pattern as `index.md`'s H1.
+- **`<appRoot>/docs/contributing.md`.** H1 `# {appName}` → `# {siteName}`. Do not add hidden FP comments; classify by literal content shape.
 
 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.
 
@@ -554,11 +558,10 @@ Procedure when gate passes:
    - `{{SITE_NAME}}` → `{siteName}` (Input Result)
    - `{{APP_DIR}}` → `{targetDir}` (Input Result; the scaffolded app path relative to repo root)
    - `{{REPO_NAME}}` → `{repoName}` (Preflight Result)
-   - `{{GENERATE_INDEX_CMD}}` → rendered per repo shape:
-     - `monorepo`: `pnpm --filter {appName} run docs:generate-index` (if the scaffold exposes that script) or the equivalent `pnpm -w run cli -- docs generate-index --docs-dir {appDir}/docs --output {appDir}/index.md`
-     - `nested-standalone`: `(cd {appDir} && pnpm run docs:generate-index)` or the `-w` equivalent
-     - `single-package`: `pnpm run docs:generate-index`
-     - Fall back to the `pnpm -w run cli -- docs generate-index ...` form if the scaffold did not write a `docs:generate-index` script (determined by grepping `<appRoot>/package.json` after scaffold).
+   - `{{GENERATE_INDEX_CMD}}` → derive from the scaffolded `<appRoot>/package.json`:
+     1. Parse JSON and inspect `scripts.predev` first, then `scripts.prebuild`.
+     2. Find the `fumadocs-mdx &&` segment and use the trimmed command that follows it.
+     3. If neither script contains that segment, fall back by repo shape: monorepo uses `pnpm -w run cli -- docs generate-index --docs-dir {appDir}/docs --output {appDir}/index.md`; nested-standalone and single-package use `oat docs generate-index --docs-dir docs --output index.md` from the app root.
 3. Write the rendered content to `<appRoot>/AGENTS.md`.
 4. Wrap the entire file in an HTML comment banner at the top — not for idempotency (file existence is the idempotency check), but so the user knows this file was written by the skill and can be regenerated: `<!-- Generated by oat-docs-bootstrap (FP-15 bridge). Safe to hand-edit after generation. -->`.
 5. Record `{ id: 'FP-15', status: 'applied', target: '<appRoot>/AGENTS.md' }` in `patchesApplied`.
@@ -611,71 +614,53 @@ Two code paths, selected by the file-shape classification of `<appRoot>/next.con
 
 **FP-13: template-content patches.**
 
-Four sub-findings, each with its own gate, target, and idempotency check. All sub-findings apply to Fumadocs; MkDocs handling lives in the Walkthrough's MkDocs Minimum Contract (Step 6, p05-t02) because the MkDocs scaffold's content layout differs and doesn't share these specific gaps.
+Five sub-findings, each with its own gate, target, and idempotency check. All sub-findings apply to Fumadocs; MkDocs handling lives in the Walkthrough's MkDocs Minimum Contract (Step 6, p05-t02) because the MkDocs scaffold's content layout differs and doesn't share these specific gaps.
 
 - **Sub-finding A: Empty `description:` frontmatter.** Targets: `<appRoot>/docs/getting-started.md:3` and `<appRoot>/docs/contributing.md:3`.
   - Gate: the target line matches `description: ''` (scaffold shape).
   - Patch: replace with static defaults:
     - `getting-started.md`: `description: 'Set up the local environment and preview the docs site.'`
     - `contributing.md`: `description: 'Authoring conventions and navigation rules for this docs site.'`
-  - Wrap each edit with `<!-- FP-13 patch: description-A -->` / `<!-- /FP-13 patch -->` on the line above.
-  - Idempotency: marker present = skip.
+  - Do not add hidden FP comments. Idempotency: non-empty description matching the static default = patched/upstream shape, skip.
   - Rationale: these are per-page descriptions, not site-level — do not template on `{siteDescription}`; use static text that describes the page's own purpose.
 
 - **Sub-finding B: Bare install/build commands lack working-directory context.** Target: `<appRoot>/docs/getting-started.md` (the install/build code block, per scaffold lines 15-33 or nearest equivalent after FP-12 patches).
   - Gate: the block contains a bare `pnpm install` / `pnpm dev` / `pnpm build` sequence with no `--filter` or `cd` prefix (scaffold shape).
-  - Patch: rewrite the block per `repoShape`:
-    - `monorepo`: prefix each command with `pnpm --filter {appName}` (e.g., `pnpm --filter {appName} install`, `... dev`, `... build`).
+  - Patch: rewrite the block using the same command shapes as the CLI command renderer:
+    - `monorepo`: install `pnpm install` at repo root; dev `pnpm --filter {appName} dev`; build `pnpm --filter {appName} build`.
     - `nested-standalone`: prefix each command with `cd {appDir} && ` (e.g., `cd apps/docs && pnpm install`).
-    - `single-package`: leave bare form — it works correctly from repo root.
-  - Wrap the entire rewritten block with `<!-- FP-13 patch: commands-B -->` / `<!-- /FP-13 patch -->`.
-  - Idempotency: marker present = skip. If the block has drifted (not bare, not already patched), classify as `drift` and refuse.
+    - `single-package`: leave bare form when the app is at repo root; if the app lives in a subdirectory, use `cd {appDir} && pnpm <command>`.
+  - Do not add hidden FP comments. Idempotency: command block already matches the renderer output = patched/upstream shape, skip. If the block has drifted (not bare, not renderer-shaped), classify as `drift` and refuse.
 
 - **Sub-finding C: False `docs:lint` claim.** Target: `<appRoot>/docs/contributing.md` line describing the `docs:lint` script (near line 31 per scaffold, may have shifted).
   - Gate: `lint === 'none'` (Input Result) AND the line contains the exact scaffold string "Run Markdown formatting and linting as configured for this docs app."
   - Patch: replace with "Run Markdown formatting as configured for this docs app." (dropping "and linting").
   - If `lint === 'markdownlint-cli2'`, the original claim is accurate — skip with `status: 'skipped', reason: 'linting is configured'`.
-  - Wrap with `<!-- FP-13 patch: lint-claim-C -->` / `<!-- /FP-13 patch -->`.
-  - Idempotency: marker present = skip.
+  - Do not add hidden FP comments. Idempotency: corrected sentence already present = patched/upstream shape, skip.
 
-- **Sub-finding D: Generated `index.md` lacks "do not hand-edit" warning.** Two sub-targets:
+- **Sub-finding D: Generated-file guidance and old authored-header cleanup.** Two sub-targets:
   - **D.1 — `contributing.md` explanatory section.** Append a "Generated files" section to `<appRoot>/docs/contributing.md` (before any closing References section if present). Two sentences:
 
     ```markdown
-    <!-- FP-13 patch: generated-files-D -->
-
     ## Generated files
 
     For Fumadocs apps, the root-level generated manifest at `<appRoot>/index.md` is regenerated from the Markdown file tree under `docs/` on every `predev` / `prebuild`. Do not hand-edit it; edit the authored source under `docs/` instead, and compare the generated manifest against authored `## Contents` when checking freshness. For MkDocs apps, the derived navigation artifact is the `nav:` section of `mkdocs.yml`, not a root manifest.
-
-    <!-- /FP-13 patch -->
-    ```
-
-    Idempotency: marker present = skip.
-
-  - **D.2 — Generated `index.md` header comment.** The header to prepend:
-
-    ```markdown
-    <!-- AUTOGENERATED by `oat docs generate-index`. Do not hand-edit; changes are clobbered on every `predev` / `prebuild`. -->
     ```
 
-    **Two-pass strategy. Both passes MUST run — do not treat the second as optional.**
+    Idempotency: an existing `## Generated files` section with equivalent generated/root-manifest guidance = patched/upstream shape, skip. Do not add hidden FP comments.
 
-    **Pass 1 (best-effort, at scaffold time).** If `<appRoot>/index.md` exists after the CLI's `init` completes, prepend the header directly. Record `{ id: 'FP-13/D.2', status: 'applied', pass: 'scaffold-time' }`. If the file does not yet exist, also add a one-time hook: modify `<appRoot>/package.json` to wrap `prebuild`/`predev` so that the generated `index.md` is prefixed with the header on first run. Hook marker: `<!-- FP-13 patch: generated-header-D2 -->`.
-
-    **Pass 2 (correctness backstop, after Build Verifier).** After the Build Verifier (Step 4) completes install + build, the `prebuild`/`predev` script should have run and `<appRoot>/index.md` should now exist with the header. Verify:
-    - If `<appRoot>/index.md` exists AND starts with the header → no action; record `{ id: 'FP-13/D.2', status: 'already-present', pass: 'post-build-verify' }`.
-    - If `<appRoot>/index.md` exists AND does NOT start with the header → **prepend it directly** (the hook did not fire, or was skipped). Record `{ id: 'FP-13/D.2', status: 'applied-directly', pass: 'post-build-verify' }`.
-    - If `<appRoot>/index.md` still does not exist → the build did not run generate-index. This is a deeper scaffold issue — surface as a refused patch with `reason: 'generated index.md not present after build; check prebuild script'` and let the user investigate.
-
-    The direct-write pass is the correctness backstop. The hook alone is not reliable enough (some users run `pnpm dev` before touching anything else; the hook might be skipped if another prebuild step short-circuits; the hook modification may conflict with user-customized package.json scripts).
+  - **D.2 — Authored `docs/index.md` false generated-header backstop.** Older scaffolds could place a generated-file warning on the authored source file at `<appRoot>/docs/index.md`. That warning is wrong: the authored file is edited by humans and agents; the generated Fumadocs manifest is `<appRoot>/index.md`.
+    - Gate: `<appRoot>/docs/index.md` contains the exact historical `AUTOGENERATED by \`oat docs generate-index\`` warning before the first H1.
+    - Patch: remove only that warning line, preserving frontmatter, the H1, and `## Contents`.
+    - Idempotency: no authored-file warning = patched/upstream shape, skip. If a different top comment is present, treat it as project prose and do not remove it.
+    - The generated root `<appRoot>/index.md` warning is CLI-owned. If it is missing after build, surface that as an Inspector warning; do not inject hooks into `package.json`.
 
   - **E — Node version mismatch.** Target: `<appRoot>/docs/getting-started.md` "Prerequisites" section. The scaffold's `- Node.js 20+` claim (or any hard-coded major version) should reflect the **consuming repo's** actual Node requirement, not a scaffold-time default.
     - Gate: always run when `<appRoot>/docs/getting-started.md` exists and has a `- Node.js` bullet in a "Prerequisites" section.
     - Read (in priority order) `$REPO_ROOT/.nvmrc`, then `$REPO_ROOT/package.json` `engines.node`. If a version is found and it's different from the hard-coded version in the scaffold, rewrite the bullet to reference the detected version.
-    - Wrap the rewritten line with `<!-- FP-13 patch: node-version-E -->` / `<!-- /FP-13 patch -->`.
+    - Do not add hidden FP comments.
     - If neither source is present or parseable, leave the scaffold default and record `{ id: 'FP-13/E', status: 'skipped', reason: 'no .nvmrc or engines.node to detect' }`.
-    - Idempotency: marker present = skip.
+    - Idempotency: the bullet already reflects the detected version = patched/upstream shape, skip.
 
 **FP-16: `## Contents` link-extension patch.**
 
@@ -687,20 +672,16 @@ Target: `<appRoot>/docs/index.md` `## Contents` section. For each list item whos
 - If the target corresponds to a sibling subdirectory with an `index.md` (e.g., `reference` → `reference/`, with `reference/index.md`), rewrite to `reference/index.md`.
 - Leave absolute URLs, anchors (`#section`), and already-suffixed links untouched.
 
-Wrap the rewritten `## Contents` block with markers:
+Rewrite the `## Contents` block in place without hidden FP comments:
 
 ```markdown
-<!-- FP-16 patch: .md-suffixed ## Contents -->
-
 ## Contents
 
 - [Getting Started](getting-started.md) - Set up the local docs toolchain and preview the site.
 - [Contributing](contributing.md) - Authoring conventions and navigation rules.
-
-<!-- /FP-16 patch -->
 ```
 
-Idempotency: if the marker `<!-- FP-16 patch: .md-suffixed ## Contents -->` is already present, skip with `status: 'skipped'`. If the `## Contents` section has drifted (mixed extensions, non-bulleted structure, extra prose between items), classify as `drift` per Capability Detection and record `refused` — do not attempt a partial rewrite.
+Idempotency: if all local file links in `## Contents` are already `.md`-suffixed or `dir/index.md`-suffixed, skip with `status: 'skipped'`. If the `## Contents` section has drifted (mixed extensions, non-bulleted structure, extra prose between items), classify as `drift` per Capability Detection and record `refused` — do not attempt a partial rewrite.
 
 **Rationale.** The `@open-agent-toolkit/docs-transforms` remark-links plugin strips `.md` / `dir/index.md` at build time for Fumadocs routing, so `.md`-suffixed authored links render correctly. `.md`-suffixed form is what `apps/oat-docs` uses in practice and is what agents can follow via direct file open without path inference. Extension-less links are the scaffold's historical form but are agent-hostile; FP-16 normalizes to the correct convention. When the CLI scaffold template is fixed upstream, the file-shape check will skip this patch automatically.
 
@@ -714,19 +695,15 @@ Target: the `## Agent guidance` section in `<appRoot>/docs/contributing.md`. Thi
 - `<appRoot>/AGENTS.md` → agent runtime reference (how to add pages, restructure nav, audit/apply).
 - Root `AGENTS.md` `## Documentation` section → repo-wide pointer.
 
-Patch: replace the section body with a one-line pointer and marker:
+Patch: replace the section body with a one-line pointer:
 
 ```markdown
-<!-- FP-17 patch: three-surfaces cleanup -->
-
 ## Agent guidance
 
 See `AGENTS.md` in this directory for how agents should work inside this docs app. This `contributing.md` covers human authoring conventions; `AGENTS.md` covers agent runtime discipline (adding pages, restructuring nav, audit/apply, three agent-instruction surfaces). Keeping those concerns separate keeps each file useful to its audience.
-
-<!-- /FP-17 patch -->
 ```
 
-Idempotency: if the marker `<!-- FP-17 patch: three-surfaces cleanup -->` is already present, skip with `status: 'skipped'`. If the `## Agent guidance` section has been edited beyond scaffold shape (more than the two or three default bullets; contains content that isn't "docs conventions already in AGENTS.md"), classify as `drift` and refuse — do not collapse user-authored content.
+Idempotency: if the section already contains the one-paragraph pointer to the docs-app `AGENTS.md`, skip with `status: 'skipped'`. If the `## Agent guidance` section has been edited beyond scaffold shape (more than the two or three default bullets; contains content that isn't "docs conventions already in AGENTS.md"), classify as `drift` and refuse — do not collapse user-authored content.
 
 **Rationale.** Without this patch, agents reading `docs/contributing.md` find partial agent guidance that duplicates (and risks diverging from) the docs-app `AGENTS.md`. The three-surfaces model only works if each surface is the single-source-of-truth for its audience.
 
@@ -741,7 +718,7 @@ Inside 3d, patches run in this order:
 
 **Design discipline:**
 
-- **CLI is the source of truth for templates.** The Scaffold Runner never rewrites template content, re-renders frontmatter, or fabricates files the CLI was supposed to create. Post-patches only adjust specific known-gap locations, and every patch is labeled.
+- **CLI is the source of truth for templates.** The Scaffold Runner never rewrites template content, re-renders frontmatter, or fabricates files the CLI was supposed to create. Post-patches only adjust specific known-gap locations and use either syntactically valid code markers or content-shape idempotency, depending on the target file type.
 - **Capability Detection gates every patch.** No patch runs blindly; the file-shape check must pass, and the capability must be absent. This means the skill self-ratchets as CLI fixes land — when `--site-name` is supported upstream, FP-12 patches are skipped automatically.
 - **Failure is loud, not silent.** CLI non-zero exit stops the flow with the verbatim error. Ambiguous file shapes record a `refused` patch status rather than guessing.
 
@@ -953,7 +930,7 @@ Narrate:
 - **The authored source** at `<appRoot>/docs/index.md`. This is the file the user edits. It has frontmatter (`title`, `description`) and a `## Contents` section listing direct children of the docs root. It is the top of a fractal: every directory has its own `index.md`, each with its own `## Contents`.
 - **The Fumadocs generated map** at `<appRoot>/index.md`. Regenerated on every `predev` / `prebuild` by the `oat docs generate-index` command. Machine-shaped: inventories Markdown files with titles and descriptions so tools have a single searchable map. **Hand-edits are silently clobbered.**
 - **The MkDocs derived nav** in `mkdocs.yml` `nav:`. MkDocs does not use a Fumadocs-style generated app-root manifest; its generated/derived navigation boundary is the YAML nav block.
-- **How to tell them apart when opening a file.** If the file sits inside `docs/`, it's authored. If it sits at `<appRoot>/index.md` (outside `docs/`), it's the Fumadocs generated manifest — and when the CLI or Scaffold-integrity FP-13/D.2 wrote the warning correctly, the first line is `<!-- AUTOGENERATED by \`oat docs generate-index\`... -->`.
+- **How to tell them apart when opening a file.** If the file sits inside `docs/`, it's authored. If it sits at `<appRoot>/index.md` (outside `docs/`), it's the Fumadocs generated manifest — and when the CLI wrote the warning correctly, the first line is `<!-- AUTOGENERATED by \`oat docs generate-index\`... -->`.
 
 End with: "Always edit `docs/index.md` and the `## Contents` sections. In Fumadocs, never edit the root-level `index.md` — your edits will disappear next build. In MkDocs, treat `mkdocs.yml` `nav:` as derived from authored Contents unless the local workflow says otherwise."
 
@@ -1156,7 +1133,7 @@ A successful `oat-docs-bootstrap` run satisfies every invariant below. Any failu
 - Conflict Resolution Contract's "Allowed mutations" completed for the chosen resolution; pre-scaffold invariant satisfied before `oat docs init` ran.
 - Scaffold Runner invoked `oat docs init` non-interactively with capability-gated flags; CLI exited zero; `Scaffold Result.appRoot` resolved from `.oat/config.json` (not from input alone).
 - Capability Detection produced a deterministic `capabilities` record before scaffold (for flag gating) and classified each patch target after scaffold (scaffold-shape / patched-shape / drift).
-- Every applied post-patch is labeled with a marker comment (`<!-- FP-NN patch -->` or `/* FP-NN patch */`) and is idempotent; no patch ran without passing both its capability gate and its file-shape check.
+- Every applied post-patch is idempotent and file-type aware: code-file patches use syntactically valid code comments when markers are useful, while rendered Markdown patches rely on content-shape checks instead of hidden FP comments. No patch ran without passing both its capability gate and its file-shape check.
 - Build Verifier ran install + build with commands matching `repoShape`; failures classified against known patterns; unknown errors halted the flow before Inspector/Walkthrough.
 - Post-Scaffold Inspector verified every `documentation.*` path against disk; drift findings recorded with `suggestedFix`; nested-standalone dual-config surfaced without reconciliation.
 - `requireForProjectCompletion` decision collected from user; written to `.oat/config.json` only on opt-in; never silently default-true.

package/assets/templates/docs-app-fuma/app/[[...slug]]/page.tsx

@@ -1,14 +1,28 @@
 import { DocsPage, Mermaid, Tab, Tabs } from '@open-agent-toolkit/docs-theme';
 import defaultComponents from 'fumadocs-ui/mdx';
+import type { Metadata } from 'next';
 import { notFound } from 'next/navigation';
 
 import { source } from '@/lib/source';
 
 const mdxComponents = { ...defaultComponents, Mermaid, Tab, Tabs };
 
-export default async function Page(props: {
+type PageProps = {
   params: Promise<{ slug?: string[] }>;
-}) {
+};
+
+export async function generateMetadata(props: PageProps): Promise<Metadata> {
+  const params = await props.params;
+  const page = source.getPage(params.slug);
+  if (!page) notFound();
+
+  return {
+    title: page.data.title,
+    description: page.data.description,
+  };
+}
+
+export default async function Page(props: PageProps) {
   const params = await props.params;
   const page = source.getPage(params.slug);
   if (!page) notFound();

package/assets/templates/docs-app-fuma/app/layout.tsx

@@ -3,9 +3,13 @@ import { RootProvider } from 'fumadocs-ui/provider/next';
 import type { ReactNode } from 'react';
 
 import './globals.css';
+import StaticSearchDialog from '@/components/search';
 import { source } from '@/lib/source';
 
-const basePath = process.env.NEXT_PUBLIC_BASE_PATH ?? '';
+export const metadata = {
+  title: '{{SITE_NAME}}',
+  description: '{{SITE_DESCRIPTION}}',
+};
 
 export default function Layout({ children }: { children: ReactNode }) {
   return (
@@ -13,10 +17,7 @@ export default function Layout({ children }: { children: ReactNode }) {
       <body>
         <RootProvider
           search={{
-            options: {
-              type: 'static' as const,
-              api: `${basePath}/api/search`,
-            },
+            SearchDialog: StaticSearchDialog,
           }}
         >
           <DocsLayout

package/assets/templates/docs-app-fuma/components/search.tsx

@@ -0,0 +1,46 @@
+'use client';
+
+import { useDocsSearch } from 'fumadocs-core/search/client';
+import {
+  SearchDialog,
+  SearchDialogClose,
+  SearchDialogContent,
+  SearchDialogHeader,
+  SearchDialogIcon,
+  SearchDialogInput,
+  SearchDialogList,
+  SearchDialogOverlay,
+  type SharedProps,
+} from 'fumadocs-ui/components/dialog/search';
+
+// Static export has no search server, so the dialog runs a client-side static
+// index search. fumadocs-ui's DefaultSearchDialog is hardwired to the fetch
+// client, so we provide a custom dialog backed by the static client. `from`
+// mirrors the basePath-aware static index emitted by app/api/search.
+const basePath = process.env.NEXT_PUBLIC_BASE_PATH ?? '';
+
+export default function StaticSearchDialog(props: SharedProps) {
+  const { search, setSearch, query } = useDocsSearch({
+    type: 'static',
+    from: `${basePath}/api/search`,
+  });
+
+  return (
+    <SearchDialog
+      search={search}
+      onSearchChange={setSearch}
+      isLoading={query.isLoading}
+      {...props}
+    >
+      <SearchDialogOverlay />
+      <SearchDialogContent>
+        <SearchDialogHeader>
+          <SearchDialogIcon />
+          <SearchDialogInput />
+          <SearchDialogClose />
+        </SearchDialogHeader>
+        <SearchDialogList items={query.data !== 'empty' ? query.data : null} />
+      </SearchDialogContent>
+    </SearchDialog>
+  );
+}

package/assets/templates/docs-app-fuma/docs/contributing.md

@@ -1,6 +1,6 @@
 ---
 title: Contributing
-description: ''
+description: 'Authoring conventions and navigation rules.'
 ---
 
 # Contributing to {{SITE_NAME}}
@@ -19,16 +19,16 @@ Documentation should ship with the code it explains. This docs app is scaffolded
 1. Install dependencies:
 
    ```bash
-   pnpm install
+   {{INSTALL_CMD}}
    ```
 
 2. Run the live preview:
 
    ```bash
-   pnpm dev
+   {{DEV_CMD}}
    ```
 
-3. Run Markdown formatting and linting as configured for this docs app.
+3. Run Markdown {{LINT_PHRASE}} as configured for this docs app.
 
 ## Supported Markdown features
 

package/assets/templates/docs-app-fuma/docs/getting-started.md

@@ -1,6 +1,6 @@
 ---
 title: Getting Started
-description: ''
+description: 'Set up the local docs toolchain and preview the site.'
 ---
 
 # Getting Started
@@ -15,19 +15,19 @@ Use this guide to set up your local environment and preview {{SITE_NAME}}.
 ## Install dependencies
 
 ```bash
-pnpm install
+{{INSTALL_CMD}}
 ```
 
 ## Run the docs locally
 
 ```bash
-pnpm dev
+{{DEV_CMD}}
 ```
 
 ## Build for production
 
 ```bash
-pnpm build
+{{BUILD_CMD}}
 ```
 
 The static output is generated in the `out/` directory.

package/assets/templates/docs-app-fuma/docs/index.md

@@ -3,8 +3,6 @@ title: '{{SITE_NAME}}'
 description: '{{SITE_DESCRIPTION}}'
 ---
 
-<!-- AUTOGENERATED by `oat docs generate-index`. Do not hand-edit; changes are clobbered on every `predev` / `prebuild`. -->
-
 # {{SITE_NAME}}
 
 Use this file as the map to the repository's central documentation site. The site is organized to support both human readers and AI agents, with every directory exposing an `index.md` entrypoint.

package/assets/templates/docs-app-fuma/next.config.js

@@ -3,7 +3,5 @@ import { createDocsConfig } from '@open-agent-toolkit/docs-config';
 const basePath = process.env.NEXT_PUBLIC_BASE_PATH || undefined;
 
 export default createDocsConfig({
-  title: '{{SITE_NAME}}',
-  description: '{{SITE_DESCRIPTION}}',
   ...(basePath ? { basePath } : {}),
 });