@open-agent-toolkit/cli 0.1.26 → 0.1.27

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.27",
+  "docs-config": "0.1.27",
+  "docs-theme": "0.1.27",
+  "docs-transforms": "0.1.27"
 }

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 } : {}),
 });

package/assets/templates/docs-app-fuma/package.json.template

@@ -2,7 +2,7 @@
   "name": "{{PACKAGE_NAME}}",
   "type": "module",
   "private": true,
-  "version": "0.1.0",
+  "version": "0.1.0"{{PACKAGE_MANAGER_FIELD}},
   "description": "{{SITE_DESCRIPTION}}",
   "scripts": {
     "predev": "fumadocs-mdx && {{GENERATE_INDEX_CMD}}",

package/assets/templates/docs-app-mkdocs/package.json.template

@@ -2,7 +2,7 @@
   "name": "{{PACKAGE_NAME}}",
   "type": "module",
   "private": true,
-  "version": "0.1.0",
+  "version": "0.1.0"{{PACKAGE_MANAGER_FIELD}},
   "description": "MkDocs Material documentation for {{SITE_NAME}}.",
   "scripts": {
     "docs:dev": "mkdocs serve",

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

@@ -0,0 +1,8 @@
+import type { DocsRepoShape } from './resolve-options.js';
+export interface DocsCommands {
+    install: string;
+    dev: string;
+    build: string;
+}
+export declare function buildDocsCommands(repoShape: DocsRepoShape, targetDir: string, appName: string): DocsCommands;
+//# sourceMappingURL=docs-commands.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"docs-commands.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/docs-commands.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,KAAK,EAAE,MAAM,CAAC;CACf;AAMD,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,GACd,YAAY,CAsBd"}

package/dist/commands/docs/init/docs-commands.js

@@ -0,0 +1,25 @@
+import { normalize } from 'node:path';
+function isRootTarget(targetDir) {
+    return targetDir.trim() === '' || normalize(targetDir) === '.';
+}
+export function buildDocsCommands(repoShape, targetDir, appName) {
+    if (repoShape === 'monorepo') {
+        return {
+            install: 'pnpm install',
+            dev: `pnpm --filter ${appName} dev`,
+            build: `pnpm --filter ${appName} build`,
+        };
+    }
+    if (isRootTarget(targetDir)) {
+        return {
+            install: 'pnpm install',
+            dev: 'pnpm dev',
+            build: 'pnpm build',
+        };
+    }
+    return {
+        install: `cd ${targetDir} && pnpm install`,
+        dev: `cd ${targetDir} && pnpm dev`,
+        build: `cd ${targetDir} && pnpm build`,
+    };
+}

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":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,mBAAmB,EAEzB,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;AAE5C,OAAO,EAIL,KAAK,uBAAuB,EAK7B,MAAM,mBAAmB,CAAC;AAkB3B,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,IAAI,CAAC,CAAC;IACnB,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;AAyGD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAc7E;AA+GD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CAuCT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,KAAK,mBAAmB,EAEzB,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;AAmB3B,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,IAAI,CAAC,CAAC;IACnB,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;AAyGD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAc7E;AAoHD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CA6CT"}

package/dist/commands/docs/init/index.js

@@ -5,6 +5,7 @@ import { readGlobalOptions } from '../../shared/shared.utils.js';
 import { readOatConfig, writeOatConfig, } from '../../../config/oat-config.js';
 import { resolveAssetsRoot } from '../../../fs/assets.js';
 import { Command, Option } from 'commander';
+import { buildDocsCommands } from './docs-commands.js';
 import { DEFAULT_DOCS_REPO_SHAPE_DEPENDENCIES, detectDocsRepoShape, getDefaultDocsAppName, resolveDocsInitOptions, } from './resolve-options.js';
 import { patchRootPackageJson, } from './root-package.js';
 import { scaffoldDocsApp } from './scaffold.js';
@@ -115,6 +116,7 @@ async function runDocsInitCommand(context, options, dependencies) {
             acceptDefaults: options.yes ?? false,
             providedFramework: options.framework,
             providedAppName: options.appName,
+            providedSiteName: options.siteName,
             providedTargetDir: options.targetDir,
             providedSiteDescription: options.description,
             providedLint: options.lint,
@@ -166,13 +168,11 @@ async function runDocsInitCommand(context, options, dependencies) {
         if (!context.json) {
             context.logger.info('');
             context.logger.info('Next steps:');
-            if (resolved.repoShape === 'single-package') {
-                context.logger.info(`  cd ${resolved.targetDir} && pnpm install`);
-                context.logger.info('  pnpm build');
-            }
-            else {
-                context.logger.info('  pnpm install');
-                context.logger.info(`  pnpm --filter ${resolved.appName} build`);
+            const commands = buildDocsCommands(resolved.repoShape, resolved.targetDir, resolved.appName);
+            context.logger.info(`  ${commands.install}`);
+            context.logger.info(`  ${commands.dev}`);
+            context.logger.info(`  ${commands.build}`);
+            if (resolved.repoShape === 'monorepo') {
                 const defaultName = getDefaultDocsAppName(context.cwd, resolved.repoShape);
                 if (resolved.appName !== defaultName) {
                     context.logger.info('');
@@ -205,6 +205,7 @@ export function createDocsInitCommand(overrides = {}) {
         'mkdocs',
     ]))
         .addOption(new Option('--app-name <name>', 'Docs app name'))
+        .addOption(new Option('--site-name <name>', 'Display title (distinct from --app-name)'))
         .addOption(new Option('--target-dir <path>', 'Target directory for the docs app'))
         .addOption(new Option('--description <text>', 'Site description'))
         .addOption(new Option('--lint <mode>', 'Markdown lint mode').choices([

package/dist/commands/docs/init/resolve-options.d.ts

@@ -1,5 +1,6 @@
 import type { PromptContext, SelectChoice } from '../../shared/shared.prompts.js';
-export type DocsRepoShape = 'monorepo' | 'single-package';
+export type DocsRepoShape = 'monorepo' | 'single-package' | 'nested-standalone';
+export type DocsDetectedRepoShape = Exclude<DocsRepoShape, 'nested-standalone'>;
 export type DocsFramework = 'fumadocs' | 'mkdocs';
 export type DocsLintMode = 'none' | 'markdownlint-cli2';
 export type DocsFormatMode = 'oxfmt' | 'none';
@@ -8,6 +9,7 @@ export interface DocsInitResolvedOptions {
     repoShape: DocsRepoShape;
     framework: DocsFramework;
     appName: string;
+    siteName: string;
     targetDir: string;
     siteDescription: string;
     lint: DocsLintMode;
@@ -21,6 +23,7 @@ export interface ResolveDocsInitOptionsInput {
     acceptDefaults: boolean;
     providedFramework?: DocsFramework;
     providedAppName?: string;
+    providedSiteName?: string;
     providedTargetDir?: string;
     providedSiteDescription?: string;
     providedLint?: DocsLintMode;
@@ -36,8 +39,10 @@ export interface DocsRepoShapeDependencies {
 }
 export declare function getDefaultDocsAppName(repoRoot: string, repoShape: DocsRepoShape): string;
 export declare function getDefaultDocsTargetDir(repoShape: DocsRepoShape, appName: string): string;
-export declare function detectDocsRepoShape(repoRoot: string, dependencies: DocsRepoShapeDependencies): Promise<DocsRepoShape>;
+export declare function humanizeAppName(appName: string): string;
+export declare function detectDocsRepoShape(repoRoot: string, dependencies: DocsRepoShapeDependencies): Promise<DocsDetectedRepoShape>;
 export declare function getTemplateDir(framework: DocsFramework): string;
+export declare function resolveEffectiveDocsShape(repoShape: DocsRepoShape, framework: DocsFramework, repoRoot: string, targetDir: string): DocsRepoShape;
 export declare function resolveDocsInitOptions(input: ResolveDocsInitOptionsInput): Promise<DocsInitResolvedOptions | null>;
 export declare const DEFAULT_DOCS_REPO_SHAPE_DEPENDENCIES: DocsRepoShapeDependencies;
 //# sourceMappingURL=resolve-options.d.ts.map

package/dist/commands/docs/init/resolve-options.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"resolve-options.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/resolve-options.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACb,MAAM,iCAAiC,CAAC;AAGzC,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,gBAAgB,CAAC;AAC1D,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,QAAQ,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,mBAAmB,CAAC;AACxD,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9C,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;IACzB,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,iBAAiB,CAAC,EAAE,aAAa,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,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;CACxB;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACvE;AAiBD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,aAAa,GACvB,MAAM,CAMR;AAED,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,MAAM,GACd,MAAM,CAMR;AAoBD,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,yBAAyB,GACtC,OAAO,CAAC,aAAa,CAAC,CAqBxB;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,aAAa,GAAG,MAAM,CAE/D;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,2BAA2B,GACjC,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAgFzC;AAED,eAAO,MAAM,oCAAoC,EAAE,yBAOlD,CAAC"}
+{"version":3,"file":"resolve-options.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/resolve-options.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACb,MAAM,iCAAiC,CAAC;AAGzC,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,gBAAgB,GAAG,mBAAmB,CAAC;AAChF,MAAM,MAAM,qBAAqB,GAAG,OAAO,CAAC,aAAa,EAAE,mBAAmB,CAAC,CAAC;AAChF,MAAM,MAAM,aAAa,GAAG,UAAU,GAAG,QAAQ,CAAC;AAClD,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,mBAAmB,CAAC;AACxD,MAAM,MAAM,cAAc,GAAG,OAAO,GAAG,MAAM,CAAC;AAE9C,MAAM,WAAW,uBAAuB;IACtC,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;IACzB,SAAS,EAAE,aAAa,CAAC;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,EAAE,YAAY,CAAC;IACnB,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,aAAa,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,cAAc,EAAE,OAAO,CAAC;IACxB,iBAAiB,CAAC,EAAE,aAAa,CAAC;IAClC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,YAAY,CAAC,EAAE,YAAY,CAAC;IAC5B,cAAc,CAAC,EAAE,cAAc,CAAC;IAChC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,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;CACxB;AAED,MAAM,WAAW,yBAAyB;IACxC,UAAU,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC/C,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC9C,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACvE;AAiBD,wBAAgB,qBAAqB,CACnC,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,aAAa,GACvB,MAAM,CAMR;AAED,wBAAgB,uBAAuB,CACrC,SAAS,EAAE,aAAa,EACxB,OAAO,EAAE,MAAM,GACd,MAAM,CAMR;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAMvD;AAoBD,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,yBAAyB,GACtC,OAAO,CAAC,qBAAqB,CAAC,CAqBhC;AAED,wBAAgB,cAAc,CAAC,SAAS,EAAE,aAAa,GAAG,MAAM,CAE/D;AAED,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,aAAa,EACxB,SAAS,EAAE,aAAa,EACxB,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,aAAa,CAkBf;AAED,wBAAsB,sBAAsB,CAC1C,KAAK,EAAE,2BAA2B,GACjC,OAAO,CAAC,uBAAuB,GAAG,IAAI,CAAC,CAmGzC;AAED,eAAO,MAAM,oCAAoC,EAAE,yBAOlD,CAAC"}

package/dist/commands/docs/init/resolve-options.js

@@ -1,4 +1,4 @@
-import { basename, join } from 'node:path';
+import { basename, isAbsolute, join, relative, resolve } from 'node:path';
 import { dirExists, fileExists } from '../../../fs/io.js';
 const FRAMEWORK_CHOICES = [
     { label: 'Fumadocs (Next.js + MDX, static export)', value: 'fumadocs' },
@@ -24,6 +24,13 @@ export function getDefaultDocsTargetDir(repoShape, appName) {
     }
     return appName;
 }
+export function humanizeAppName(appName) {
+    return appName
+        .split(/[-_]/g)
+        .filter(Boolean)
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .join(' ');
+}
 function hasWorkspaceConfig(rawPackageJson) {
     try {
         const parsed = JSON.parse(rawPackageJson);
@@ -57,6 +64,21 @@ export async function detectDocsRepoShape(repoRoot, dependencies) {
 export function getTemplateDir(framework) {
     return framework === 'fumadocs' ? 'docs-app-fuma' : 'docs-app-mkdocs';
 }
+export function resolveEffectiveDocsShape(repoShape, framework, repoRoot, targetDir) {
+    if (repoShape !== 'single-package' || framework !== 'fumadocs') {
+        return repoShape;
+    }
+    if (!targetDir.trim()) {
+        return repoShape;
+    }
+    const targetPath = resolve(repoRoot, targetDir);
+    const relativeTarget = relative(resolve(repoRoot), targetPath);
+    const isRepoSubdirectory = relativeTarget !== '' &&
+        relativeTarget !== '.' &&
+        !relativeTarget.startsWith('..') &&
+        !isAbsolute(relativeTarget);
+    return isRepoSubdirectory ? 'nested-standalone' : repoShape;
+}
 export async function resolveDocsInitOptions(input) {
     const ctx = { interactive: input.interactive };
     const framework = input.providedFramework ||
@@ -74,6 +96,14 @@ export async function resolveDocsInitOptions(input) {
     if (!appName) {
         return null;
     }
+    const defaultSiteName = humanizeAppName(appName);
+    const siteName = input.providedSiteName ??
+        (input.interactive && !input.acceptDefaults
+            ? await input.inputWithDefault('Site name', defaultSiteName, ctx)
+            : defaultSiteName);
+    if (siteName === null) {
+        return null;
+    }
     const defaultTargetDir = getDefaultDocsTargetDir(input.repoShape, appName);
     const targetDir = input.providedTargetDir?.trim() ||
         (input.interactive && !input.acceptDefaults
@@ -100,11 +130,13 @@ export async function resolveDocsInitOptions(input) {
     if (!format) {
         return null;
     }
+    const repoShape = resolveEffectiveDocsShape(input.repoShape, framework, input.repoRoot, targetDir);
     return {
         repoRoot: input.repoRoot,
-        repoShape: input.repoShape,
+        repoShape,
         framework,
         appName,
+        siteName,
         targetDir,
         siteDescription,
         lint,

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

@@ -13,7 +13,14 @@ export interface OatDepContext {
     localPackages: Set<string>;
     oatPackageVersions: Record<string, string>;
 }
+type MaybePromise<T> = T | Promise<T>;
+export interface ScaffoldDocsAppDependencies {
+    detectPnpmVersion: () => MaybePromise<string | null | undefined>;
+    hasInheritedPackageManager: (repoRoot: string, appRoot: string) => MaybePromise<boolean>;
+}
+export declare const PNPM_FALLBACK = "10.13.1";
 export declare function detectIsOatRepo(repoRoot: string): Promise<boolean>;
 export declare function resolveOatDepContext(repoRoot: string, assetsRoot: string): Promise<OatDepContext>;
-export declare function scaffoldDocsApp(options: ScaffoldDocsAppOptions): Promise<ScaffoldDocsAppResult>;
+export declare function scaffoldDocsApp(options: ScaffoldDocsAppOptions, overrides?: Partial<ScaffoldDocsAppDependencies>): Promise<ScaffoldDocsAppResult>;
+export {};
 //# sourceMappingURL=scaffold.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/scaffold.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAIjE,OAAO,KAAK,EAGV,uBAAuB,EAExB,MAAM,mBAAmB,CAAC;AA+E3B,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,EAAE,sBAAsB,CAAC;CAC7C;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAWD,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOxE;AAgDD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAaxB;AA4ID,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,GAC9B,OAAO,CAAC,qBAAqB,CAAC,CAoChC"}
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/scaffold.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,oBAAoB,CAAC;AAKjE,OAAO,KAAK,EAGV,uBAAuB,EAExB,MAAM,mBAAmB,CAAC;AAmF3B,MAAM,WAAW,sBAAuB,SAAQ,uBAAuB;IACrE,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,mBAAmB,EAAE,sBAAsB,CAAC;CAC7C;AAED,MAAM,WAAW,aAAa;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB,aAAa,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC3B,kBAAkB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED,KAAK,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAEtC,MAAM,WAAW,2BAA2B;IAC1C,iBAAiB,EAAE,MAAM,YAAY,CAAC,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC;IACjE,0BAA0B,EAAE,CAC1B,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,KACZ,YAAY,CAAC,OAAO,CAAC,CAAC;CAC5B;AAUD,eAAO,MAAM,aAAa,YAAY,CAAC;AAEvC,wBAAsB,eAAe,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAOxE;AAgDD,wBAAsB,oBAAoB,CACxC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,aAAa,CAAC,CAaxB;AAgOD,wBAAsB,eAAe,CACnC,OAAO,EAAE,sBAAsB,EAC/B,SAAS,GAAE,OAAO,CAAC,2BAA2B,CAAM,GACnD,OAAO,CAAC,qBAAqB,CAAC,CAkDhC"}

package/dist/commands/docs/init/scaffold.js

@@ -1,7 +1,8 @@
 import { readdir, readFile, writeFile } from 'node:fs/promises';
-import { basename, dirname, join } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve, } from 'node:path';
 import { dirExists, ensureDir, fileExists } from '../../../fs/io.js';
 import { OAT_VERSION } from '../../../shared/oat-version.js';
+import { buildDocsCommands } from './docs-commands.js';
 import { getTemplateDir } from './resolve-options.js';
 const MKDOCS_TEMPLATE_FILES = [
     { source: '.gitignore', destination: '.gitignore' },
@@ -38,6 +39,10 @@ const FUMA_TEMPLATE_FILES = [
         source: join('app', 'layout.tsx'),
         destination: join('app', 'layout.tsx'),
     },
+    {
+        source: join('components', 'search.tsx'),
+        destination: join('components', 'search.tsx'),
+    },
     {
         source: join('app', '[[...slug]]', 'page.tsx'),
         destination: join('app', '[[...slug]]', 'page.tsx'),
@@ -74,6 +79,7 @@ const OAT_DEP_PACKAGES = [
 ];
 const DEFAULT_OAT_PUBLISHED_VERSION = OAT_VERSION;
 const PUBLIC_PACKAGE_VERSIONS_FILE = 'public-package-versions.json';
+export const PNPM_FALLBACK = '10.13.1';
 export async function detectIsOatRepo(repoRoot) {
     for (const pkg of OAT_DEP_PACKAGES) {
         if (!(await fileExists(join(repoRoot, 'packages', pkg, 'package.json')))) {
@@ -128,13 +134,6 @@ export async function resolveOatDepContext(repoRoot, assetsRoot) {
     };
     return { isOatRepo, localPackages, oatPackageVersions };
 }
-function humanizeAppName(appName) {
-    return appName
-        .split(/[-_]/g)
-        .filter(Boolean)
-        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
-        .join(' ');
-}
 function buildDevDependencies(lint, format) {
     const entries = [];
     if (lint === 'markdownlint-cli2') {
@@ -170,17 +169,75 @@ function oatDepVersion(depContext, packageName) {
     }
     return `^${depContext.oatPackageVersions[packageName] ?? DEFAULT_OAT_PUBLISHED_VERSION}`;
 }
-function renderTemplate(template, options, depContext) {
+function detectPnpmVersionFromUserAgent() {
+    const userAgent = process.env.npm_config_user_agent ?? '';
+    return userAgent.match(/\bpnpm\/([^\s]+)/)?.[1] ?? null;
+}
+function isDescendantOrSame(root, candidate) {
+    const relativePath = relative(root, candidate);
+    return (relativePath === '' ||
+        (!relativePath.startsWith('..') && !isAbsolute(relativePath)));
+}
+async function packageJsonHasPackageManager(packageJsonPath) {
+    if (!(await fileExists(packageJsonPath))) {
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(await readFile(packageJsonPath, 'utf8'));
+        return (typeof parsed.packageManager === 'string' &&
+            parsed.packageManager.trim().length > 0);
+    }
+    catch {
+        return false;
+    }
+}
+async function hasInheritedPackageManager(repoRoot, appRoot) {
+    const root = resolve(repoRoot);
+    let current = resolve(dirname(appRoot));
+    while (isDescendantOrSame(root, current)) {
+        if (await packageJsonHasPackageManager(join(current, 'package.json'))) {
+            return true;
+        }
+        if (current === root) {
+            break;
+        }
+        current = dirname(current);
+    }
+    return false;
+}
+const DEFAULT_SCAFFOLD_DEPENDENCIES = {
+    detectPnpmVersion: detectPnpmVersionFromUserAgent,
+    hasInheritedPackageManager,
+};
+function normalizePnpmVersion(version) {
+    const trimmed = version?.trim();
+    return trimmed && trimmed.length > 0 ? trimmed : PNPM_FALLBACK;
+}
+async function buildPackageManagerField(options, appRoot, dependencies) {
+    if (await dependencies.hasInheritedPackageManager(options.repoRoot, appRoot)) {
+        return '';
+    }
+    const version = normalizePnpmVersion(await dependencies.detectPnpmVersion());
+    return `,\n  "packageManager": ${JSON.stringify(`pnpm@${version}`)}`;
+}
+function renderTemplate(template, options, depContext, packageManagerField) {
     const repoName = basename(options.repoRoot);
-    const siteName = `${humanizeAppName(options.appName)} Documentation`;
+    const commands = buildDocsCommands(options.repoShape, options.targetDir, options.appName);
     const replacements = {
         '{{APP_NAME}}': options.appName,
         '{{PACKAGE_NAME}}': options.appName,
-        '{{SITE_NAME}}': siteName,
+        '{{SITE_NAME}}': options.siteName,
         '{{SITE_DESCRIPTION}}': options.siteDescription,
+        '{{INSTALL_CMD}}': commands.install,
+        '{{DEV_CMD}}': commands.dev,
+        '{{BUILD_CMD}}': commands.build,
+        '{{PACKAGE_MANAGER_FIELD}}': packageManagerField,
         '{{DOCS_LINT_SCRIPT}}': options.lint === 'markdownlint-cli2'
             ? "markdownlint-cli2 'docs/**/*.md'"
             : "echo 'docs lint disabled'",
+        '{{LINT_PHRASE}}': options.lint === 'markdownlint-cli2'
+            ? 'formatting and linting'
+            : 'formatting',
         '{{DOCS_FORMAT_SCRIPT}}': options.format === 'oxfmt'
             ? "oxfmt 'docs/**/*.md'"
             : "echo 'docs formatting disabled'",
@@ -223,23 +280,28 @@ async function ensureTargetWritable(appRoot) {
         throw new Error(`Docs app target directory is not empty: ${appRoot}`);
     }
 }
-export async function scaffoldDocsApp(options) {
+export async function scaffoldDocsApp(options, overrides = {}) {
     const appRoot = join(options.repoRoot, options.targetDir);
     const templateDir = getTemplateDir(options.framework);
     const templateRoot = join(options.assetsRoot, 'templates', templateDir);
     const frameworkConfig = FRAMEWORK_CONFIGS[options.framework];
     const createdFiles = [];
     const depContext = await resolveOatDepContext(options.repoRoot, options.assetsRoot);
+    const dependencies = {
+        ...DEFAULT_SCAFFOLD_DEPENDENCIES,
+        ...overrides,
+    };
     if (!(await fileExists(join(templateRoot, frameworkConfig.sentinelFile)))) {
         throw new Error(`Docs app templates not found under ${templateRoot}`);
     }
     await ensureTargetWritable(appRoot);
     await ensureDir(appRoot);
+    const packageManagerField = await buildPackageManagerField(options, appRoot, dependencies);
     for (const templateFile of frameworkConfig.templateFiles) {
         const source = join(templateRoot, templateFile.source);
         const destination = join(appRoot, templateFile.destination);
         const template = await readFile(source, 'utf8');
-        const rendered = renderTemplate(template, options, depContext);
+        const rendered = renderTemplate(template, options, depContext, packageManagerField);
         await ensureDir(dirname(destination));
         await writeFile(destination, rendered, 'utf8');
         createdFiles.push(templateFile.destination);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-agent-toolkit/cli",
-  "version": "0.1.26",
+  "version": "0.1.27",
   "private": false,
   "description": "Open Agent Toolkit CLI",
   "homepage": "https://github.com/voxmedia/open-agent-toolkit/tree/main/packages/cli",
@@ -34,7 +34,7 @@
     "ora": "^9.0.0",
     "yaml": "2.8.2",
     "zod": "^3.25.76",
-    "@open-agent-toolkit/control-plane": "0.1.26"
+    "@open-agent-toolkit/control-plane": "0.1.27"
   },
   "devDependencies": {
     "@types/node": "^22.10.0",