@open-agent-toolkit/cli 0.0.42 → 0.0.43

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

@@ -69,12 +69,13 @@ What the skill adds over the raw CLI:
 - **Post-scaffold patches for open CLI gaps.** Applied only when capability detection shows the CLI hasn't closed the gap. Each patch is labeled (e.g., `<!-- FP-12 patch -->`) so it can be removed deterministically when the upstream fix lands:
   - **FP-11** — Turbopack `root` for nested-standalone Fumadocs apps (suppresses the multiple-lockfile warning)
   - **FP-12** — `export const metadata = { title, description }` in `app/layout.tsx` (the only thing that populates page `<title>`, meta description, and Open Graph — `DocsLayout.branding.title` only renders nav chrome, and `createDocsConfig()` ignores `title` / `description` entirely)
-  - **FP-13** — five scaffold-content fixes (empty per-page `description:` frontmatter, bare install/build commands missing `--filter` or `cd`-prefix for monorepo/nested shapes, false `docs:lint` claim when `lint=none`, missing "do not hand-edit" header on generated `index.md`, Node version line that doesn't match the consuming repo's `.nvmrc` / `engines.node`)
+  - **FP-13** — four scaffold-content fixes (empty per-page `description:` frontmatter, bare install/build commands missing `--filter` or `cd`-prefix for monorepo/nested shapes, false `docs:lint` claim when `lint=none`, Node version line that doesn't match the consuming repo's `.nvmrc` / `engines.node`)
   - **FP-15** — writes a task-framed `<appRoot>/AGENTS.md` bridge file when the CLI hasn't scaffolded one. The bridge is the docs app's runtime agent reference (separate audience from `docs/contributing.md`)
   - **FP-16** — rewrites `docs/index.md` `## Contents` links to the `.md`-suffixed form that `@open-agent-toolkit/docs-transforms` normalizes at build time (agent-friendlier than extension-less; routes correctly)
   - **FP-17** — trims `docs/contributing.md`'s "Agent guidance" section to a one-line pointer at the docs-app `AGENTS.md`, restoring the three-surfaces separation
 - **Build verification.** Runs install + build, classifies failures against known patterns, stops on unknown errors rather than guessing.
 - **Config inspection.** Reads `.oat/config.json` back, verifies paths exist on disk, handles the nested-standalone dual-config case, and collects the `requireForProjectCompletion` opt-in explicitly.
+- **Root-build explanation.** When the CLI safely patches a compatible Turbo root `build` script, the walkthrough explains why the filter was added, shows the diff shape, and documents how to adjust or revert it. When the CLI skips the patch, the walkthrough relays the recommended manual snippet.
 - **Educational walkthrough.** Seven sections covering the `documentation` config, the two-`index.md` model, the `## Contents` contract (with extension discipline), the three agent-instruction surfaces (root `AGENTS.md` pointer / docs-app `AGENTS.md` / `docs/contributing.md`), Fumadocs internals (or MkDocs Minimum Contract), and the OAT docs ecosystem (`oat-project-document`, `oat-docs-analyze`, `oat-docs-apply`).
 - **Optional content kickoff.** Hands off to `oat-docs-analyze` + `oat-docs-apply` if you want to populate initial repo-specific content immediately.
 
@@ -108,6 +109,12 @@ oat docs init --app-name my-docs --framework mkdocs --yes
 
 Use 3b when you want a fully headless scaffold (CI, automation) and can accept the raw CLI output without the guided post-patches.
 
+For compatible Turbo monorepos, the CLI also patches the repo-root
+`package.json` by default so root `pnpm build` excludes the new docs app and a
+root `build:docs` script is available for docs-only builds. Use
+`--no-root-patch` to opt out, or `--dry-run` to preview the diff without
+writing it.
+
 ## 3a. Migrating from MkDocs (optional)
 
 If you have an existing MkDocs site and want to switch to Fumadocs, use the
@@ -141,6 +148,10 @@ For **Fumadocs** apps, the docs index is generated automatically via
 oat docs generate-index --docs-dir docs
 ```
 
+The generated app-root `index.md` is machine-owned and now starts with an
+`AUTOGENERATED` warning comment. Edit authored pages under `docs/`, not the
+generated root index.
+
 ## 5. Analyze the docs surface
 
 Use the skill, not the CLI stub, for the real analysis workflow.

package/assets/docs/docs-tooling/commands.md

@@ -39,6 +39,8 @@ Key behavior:
 - defaults to `apps/<app-name>` for monorepos
 - defaults to `<app-name>/` at repo root for single-package repos
 - sets `documentation.tooling`, `documentation.root`, and `documentation.index` in `.oat/config.json`
+- when the repo root exposes a compatible Turbo `scripts.build`, patches it to exclude the new docs app from the default root build and adds a root-level `build:docs` script
+- prints a unified diff before writing the root `package.json` change and returns a manual snippet when the patch is skipped because the build script is missing, non-Turbo, or ambiguous
 
 Fumadocs scaffold:
 
@@ -60,6 +62,7 @@ Supported flags:
 - `--description <text>` (site description, optional)
 - `--lint <none|markdownlint-cli2>`
 - `--format <oxfmt|none>`
+- `--no-root-patch`
 - `--yes`
 
 Examples:
@@ -117,6 +120,7 @@ Key behavior:
 - includes descriptions from frontmatter when present
 - outputs to app root (`index.md`) by default, not inside the docs directory
 - updates `documentation.index` in `.oat/config.json`
+- prepends an `AUTOGENERATED` warning comment to the output and rewrites the file on every run; do not hand-edit the generated `index.md`
 - sorting: `index.md` first, then directories before files, then lexical
 
 Supported flags:

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.0.42",
-  "docs-config": "0.0.42",
-  "docs-theme": "0.0.42",
-  "docs-transforms": "0.0.42"
+  "cli": "0.0.43",
+  "docs-config": "0.0.43",
+  "docs-theme": "0.0.43",
+  "docs-transforms": "0.0.43"
 }

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

@@ -1,6 +1,6 @@
 ---
 name: oat-docs-bootstrap
-version: 1.0.0
+version: 1.0.1
 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).
 argument-hint: '<optional-target-dir>'
 disable-model-invocation: true
@@ -473,6 +473,7 @@ Capture both stdout and stderr. **Do not** stream output directly to the user; t
     createdFiles: string[]           // paths relative to appRoot
     capabilities: { siteNameFlag: boolean, ... } // from Capability Detection (3b)
     cliLogs: { stdout: string, stderr: string }  // retained for Walkthrough
+    rootBuildPatch: { status, reason?, diff?, manualSnippet? } | null // parsed from CLI output when available
     patchesApplied: []               // populated by 3c/3d site-identity + scaffold-integrity sub-procedures
   ```
 
@@ -655,7 +656,7 @@ Four sub-findings, each with its own gate, target, and idempotency check. All su
   - **D.2 — Generated `index.md` header comment.** The header to prepend:
 
     ```markdown
-    <!-- generated by oat docs generate-index; do not hand-edit. Source: docs/index.md -->
+    <!-- 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.**
@@ -931,6 +932,13 @@ Narrate each field actually present in their config (skip fields that are absent
 - **`documentation.config`** (MkDocs only) — path to `mkdocs.yml`. Present for MkDocs because its chrome/nav is YAML-configured; absent for Fumadocs because chrome is code.
 - **`documentation.requireForProjectCompletion`** — the opt-in collected in Step 5e. If `true`, `oat-project-complete` will block project completion until `oat-docs-analyze` reports no open recommendations. Explain whichever value is set on this project.
 
+If `Scaffold Result.rootBuildPatch` is present, narrate it here before moving on:
+
+- **When `status` is `applied`, `dry-run`, or `already-configured`:** explain why the root `package.json` changed. The point is not cosmetics; it's to keep repo-root `pnpm build` from pulling the new docs app into the consumer's default Turbo build, where React / Next type collisions can break CI. Show the exact script diff from `rootBuildPatch.diff` when available; if the diff was not retained, at minimum quote the before/after values for `scripts.build` and `scripts["build:docs"]`.
+- Make the behavior concrete: `build` now excludes `{appName}` from the default Turbo build graph, and `build:docs` is the explicit root-level command that builds only the docs app.
+- Document the adjustment/revert path explicitly: "If you want different scope behavior, edit the root `package.json` `scripts.build` and `scripts["build:docs"]` entries together. Removing the extra `--filter='!{appName}'` restores the old all-packages build; changing `build:docs` changes the docs-only target."
+- **When `status` is `skipped`:** surface the skip reason in plain language, then print `rootBuildPatch.manualSnippet` verbatim as the recommended manual Turbo snippet to add. Explain that OAT intentionally left the root scripts alone because it could not prove the existing root build was a Turbo build it was safe to rewrite.
+
 End with: "This config is how every OAT docs tool finds your docs. Editing it by hand is supported — but changes to `root` or `config` paths need to match reality on disk."
 
 #### Section B (both frameworks) — The two `index.md` files
@@ -941,7 +949,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 generated map** at `<appRoot>/index.md` (when Fumadocs — the path differs for MkDocs; use the `documentation.index` path resolved by the Inspector if it differs). Regenerated on every `predev` / `prebuild` by the `oat docs generate-index` command. Machine-shaped: rolls up every `## Contents` section in the tree into a single searchable map that tools consume. **Hand-edits are silently clobbered.**
-- **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 generated — and if Scaffold-integrity FP-13/D.2 patched it, the first line is a `<!-- generated … -->` banner confirming so.
+- **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 generated — 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\`... -->`.
 
 End with: "Always edit `docs/index.md` and the `## Contents` sections. Never edit the root-level `index.md` — your edits will disappear next build."
 

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

@@ -1,6 +1,6 @@
 ---
 name: oat-project-implement
-version: 1.3.0
+version: 1.3.1
 description: Use when plan.md is ready for execution. Implements plan tasks sequentially with TDD discipline and state tracking.
 disable-model-invocation: true
 user-invocable: true
@@ -24,6 +24,9 @@ Execute the implementation plan task-by-task with full state tracking.
 **CRITICAL — Bookkeeping commits are mandatory, not optional.**
 After every code commit and after every phase/review-fix completion, you MUST commit the OAT tracking files (`implementation.md`, `state.md`, `plan.md`) as a separate bookkeeping commit. Do not defer, batch, or skip these commits under the reasoning that they "aren't related to the implementation." Skipping a bookkeeping commit is the primary cause of cross-session state drift and will cause the next implementation run to fail bookkeeping cross-checks. If bookkeeping commits feel frequent, that is the intended design — they are cheap and they prevent drift.
 
+**CRITICAL — Review boundaries require a committed artifact baseline.**
+Do not enter checkpoint review, final review, revise, or PR-final handoff with dirty core project artifacts (`discovery.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`, `state.md`, plus `.oat/state.md` when refreshed). If one of those boundaries is next and artifact bookkeeping is still uncommitted, stop and create the bookkeeping commit first.
+
 ## Progress Indicators (User-Facing)
 
 When executing this skill, provide lightweight progress feedback so the user can tell what’s happening after they confirm.
@@ -641,6 +644,8 @@ All must pass before proceeding.
 
 **At the final plan phase boundary, a code review is required before PR.**
 
+Before requesting final review, ensure the latest project-artifact bookkeeping is already committed. Review should evaluate the implementation state as it actually stands on the branch, not a half-tracked working tree.
+
 Check if final review already completed (preferred source of truth: plan.md Reviews table):
 
 ```bash

package/assets/skills/oat-project-quick-start/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-quick-start
-version: 1.3.3
+version: 1.3.4
 description: Use when a task is small enough for quick mode or rapid iteration is preferred. Scaffolds a lightweight OAT project from discovery directly to a runnable plan, with optional brainstorming and lightweight design.
 argument-hint: '<project-name> ["project description"]'
 disable-model-invocation: true
@@ -70,6 +70,7 @@ When executing this skill, provide lightweight progress feedback so the user can
 - After any write to `discovery.md`, `design.md`, `plan.md`, `implementation.md`, or project `state.md`, ensure the artifact is saved immediately and remains tracked in git.
 - If the skill is about to pause for user input or stop after mutating artifacts, commit the changed artifacts before waiting. Do not leave discovery/design updates only in the working tree.
 - Quick-start handoff is not complete until the changed project artifacts and regenerated `.oat/state.md` dashboard have been committed.
+- This applies to downstream lifecycle boundaries too: implementation, review, revise, and PR skills must inherit a committed artifact baseline, not an untracked project tree.
 
 ## Process
 

package/assets/skills/oat-project-review-provide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-provide
-version: 1.3.0
+version: 1.3.1
 description: Use when completed work in an active OAT project needs a quality gate before merge. Performs a lifecycle-scoped review after a task, phase, or full implementation, unlike oat-review-provide.
 disable-model-invocation: true
 user-invocable: true
@@ -19,6 +19,8 @@ Produce an independent review artifact that verifies requirements/design alignme
 
 **Required:** Active project with at least one completed task.
 
+**Required:** Core project artifacts are already committed before the review begins. Review should not be the first step that notices an untracked project tree or pending bookkeeping-only artifact edits.
+
 ## Mode Assertion
 
 **OAT MODE: Review Request**
@@ -218,7 +220,27 @@ TARGET_BRANCH="${TARGET_BRANCH:-$CURRENT_BRANCH}"  # from user scope, worktree c
 
    - If user chooses option 1: run `git checkout {TARGET_BRANCH}`, then proceed.
    - If user chooses option 2: set `INLINE_ONLY=true` — skip artifact write (Step 7/8) and output review findings directly in the session. The user can manually save the output.
-   - If user chooses option 3: stop and suggest `oat-worktree-bootstrap-auto`.
+
+### Step 1.6: Enforce Committed Artifact Baseline
+
+Before gathering review context, inspect the core project artifacts:
+
+- `"$PROJECT_PATH/discovery.md"`
+- `"$PROJECT_PATH/spec.md"`
+- `"$PROJECT_PATH/design.md"`
+- `"$PROJECT_PATH/plan.md"`
+- `"$PROJECT_PATH/implementation.md"`
+- `"$PROJECT_PATH/state.md"`
+- `.oat/state.md` (when it exists and was refreshed as part of the project workflow)
+
+If any of those files are untracked or modified only because the previous workflow step did not finish its bookkeeping commit:
+
+- Stop and tell the user to commit the pending artifact bookkeeping first, or resume the originating workflow skill so it can do that commit.
+- Do not write a review artifact against that half-tracked state.
+
+If the review is intentionally inline-only and the user explicitly wants to inspect an uncommitted artifact state, say so clearly in the output and skip writing the review artifact to disk.
+
+- If user chooses option 3: stop and suggest `oat-worktree-bootstrap-auto`.
 
 ### Step 2: Validate Artifacts Exist (Mode-Aware)
 

package/assets/skills/oat-project-review-receive/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: oat-project-review-receive
-version: 1.4.0
+version: 1.4.1
 description: Use when review findings from oat-project-review-provide need closure. Converts review artifacts into actionable plan tasks.
 disable-model-invocation: true
 user-invocable: true
@@ -19,6 +19,8 @@ Turn review output into plan changes and a clear next action. This closes the fe
 
 **Required:** An active review artifact exists in the top level of `{PROJECT_PATH}/reviews/` (not in `reviews/archived/`).
 
+This skill assumes the reviewed project artifacts were already committed before the review ran. If you discover untracked core project artifacts here, treat that as earlier workflow drift and include them in the bookkeeping fix instead of leaving the project partially tracked.
+
 ## Mode Assertion
 
 **OAT MODE: Receive Review**
@@ -435,6 +437,8 @@ git diff --cached --quiet || git commit -m "chore(oat): record review findings a
 
 Do not use `git add -A` or glob patterns that reach outside `"$PROJECT_PATH/reviews/"`. Do not include unrelated implementation or code files in this commit. Do not defer this commit without explicit user approval — if deferred, clearly state in the summary that bookkeeping is uncommitted so the original agent knows to commit on return.
 
+If the project itself is still untracked because earlier lifecycle steps never committed the initial artifact set, widen this bookkeeping commit to include the untracked core project artifacts (`discovery.md`, `spec.md`, `design.md`, `plan.md`, `implementation.md`, `state.md`, plus `.oat/state.md` when relevant). Do not leave the project tree partially tracked after receive-review finishes.
+
 **Note on archived review paths:** When `reviews/archived/` matches a `localPaths` pattern (the default setup), the archived file is gitignored and `git add "$PROJECT_PATH/reviews/"` will only stage the deletion of the original (now-moved) top-level review file. When `reviews/archived/` is tracked, both the deletion and the new archived location are staged. Both cases are safe — the command handles them uniformly.
 
 **Worktree handling:** If the project was resolved via a worktree in Step 0, run the git commands scoped to the worktree (`git -C "$WORKTREE_PATH" ...`) so the commit lands on the worktree branch.

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

@@ -3,6 +3,8 @@ 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/dist/commands/docs/index-generate/index.d.ts

@@ -1,5 +1,6 @@
 import { type CommandContext, type GlobalOptions } from '../../../app/command-context.js';
 import { Command } from 'commander';
+export declare const GENERATED_INDEX_WARNING = "<!-- AUTOGENERATED by `oat docs generate-index`. Do not hand-edit; changes are clobbered on every `predev` / `prebuild`. -->";
 interface IndexGenerateFileDependencies {
     generateIndex: (docsDir: string) => Promise<import('./generator.js').IndexEntry[]>;
     renderIndex: (entries: import('./generator.js').IndexEntry[]) => string;

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAS5C,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CACb,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,OAAO,oBAAoB,EAAE,SAAS,CAAC,CAAC;IACrD,cAAc,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,oBAAoB,EAAE,SAAS,KAC3C,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACnD;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAwED,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAsBT"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/index-generate/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,aAAa,EACnB,MAAM,sBAAsB,CAAC;AAI9B,OAAO,EAAE,OAAO,EAAU,MAAM,WAAW,CAAC;AAI5C,eAAO,MAAM,uBAAuB,iIAC4F,CAAC;AAOjI,UAAU,6BAA6B;IACrC,aAAa,EAAE,CACb,OAAO,EAAE,MAAM,KACZ,OAAO,CAAC,OAAO,aAAa,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,WAAW,EAAE,CAAC,OAAO,EAAE,OAAO,aAAa,EAAE,UAAU,EAAE,KAAK,MAAM,CAAC;IACrE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,aAAa,EAAE,CACb,QAAQ,EAAE,MAAM,KACb,OAAO,CAAC,OAAO,oBAAoB,EAAE,SAAS,CAAC,CAAC;IACrD,cAAc,EAAE,CACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,OAAO,oBAAoB,EAAE,SAAS,KAC3C,OAAO,CAAC,IAAI,CAAC,CAAC;IACnB,eAAe,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACnD;AAED,UAAU,yBAAyB;IACjC,mBAAmB,EAAE,CAAC,OAAO,EAAE,aAAa,KAAK,cAAc,CAAC;IAChE,QAAQ,EAAE,6BAA6B,CAAC;CACzC;AAgFD,wBAAgB,8BAA8B,CAC5C,SAAS,GAAE,OAAO,CAAC,yBAAyB,CAAM,GACjD,OAAO,CAsBT"}

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

@@ -6,6 +6,7 @@ import { readOatConfig, writeOatConfig } from '../../../config/oat-config.js';
 import { resolveProjectRoot } from '../../../fs/paths.js';
 import { Command, Option } from 'commander';
 import { generateIndex, renderIndex } from './generator.js';
+export const GENERATED_INDEX_WARNING = '<!-- AUTOGENERATED by `oat docs generate-index`. Do not hand-edit; changes are clobbered on every `predev` / `prebuild`. -->';
 const DEFAULT_FILE_DEPS = {
     generateIndex,
     renderIndex,
@@ -18,13 +19,19 @@ const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
     fileDeps: DEFAULT_FILE_DEPS,
 };
+function buildGeneratedIndexOutput(content) {
+    if (!content) {
+        return GENERATED_INDEX_WARNING;
+    }
+    return `${GENERATED_INDEX_WARNING}\n\n${content}`;
+}
 async function runIndexGenerate(context, options, deps) {
     const docsDir = join(context.cwd, options.docsDir);
     const outputPath = options.output
         ? join(context.cwd, options.output)
         : join(context.cwd, 'index.md');
     const entries = await deps.generateIndex(docsDir);
-    const content = deps.renderIndex(entries);
+    const content = buildGeneratedIndexOutput(deps.renderIndex(entries));
     await deps.writeFile(outputPath, content, 'utf8');
     const repoRoot = await deps.resolveRepoRoot(context.cwd);
     const config = await deps.readOatConfig(repoRoot);

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;AAa3B,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;AAiDD,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,CAc7E;AA8GD,wBAAgB,qBAAqB,CACnC,SAAS,GAAE,OAAO,CAAC,oBAAoB,CAAM,GAC5C,OAAO,CAsCT"}
+{"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"}

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

@@ -6,7 +6,43 @@ import { readOatConfig, writeOatConfig, } from '../../../config/oat-config.js';
 import { resolveAssetsRoot } from '../../../fs/assets.js';
 import { Command, Option } from 'commander';
 import { DEFAULT_DOCS_REPO_SHAPE_DEPENDENCIES, detectDocsRepoShape, getDefaultDocsAppName, resolveDocsInitOptions, } from './resolve-options.js';
+import { patchRootPackageJson, } from './root-package.js';
 import { scaffoldDocsApp } from './scaffold.js';
+function logRootPackagePatch(context, result) {
+    if (result.status === 'disabled') {
+        context.logger.info('Skipped root package.json patch (--no-root-patch).');
+        return;
+    }
+    if (result.diff) {
+        context.logger.info('');
+        context.logger.info('Root package.json diff:');
+        context.logger.info(result.diff);
+    }
+    if (result.status === 'applied') {
+        context.logger.info('Updated the root Turbo build scripts to exclude the docs app from the default build and added `build:docs`.');
+    }
+    else if (result.status === 'dry-run') {
+        context.logger.info('Dry run: the root Turbo build script patch was previewed but not written.');
+        context.logger.info('Run without --dry-run to apply these changes.');
+    }
+    else if (result.status === 'already-configured') {
+        context.logger.info('Root package.json already excludes the docs app from the default Turbo build and exposes `build:docs`.');
+    }
+    else if (result.status === 'skipped') {
+        for (const warning of result.warnings) {
+            context.logger.warn(warning);
+        }
+        if (result.manualSnippet) {
+            context.logger.info('');
+            context.logger.info('Recommended manual Turbo script snippet for the repo root:');
+            context.logger.info(result.manualSnippet);
+        }
+        return;
+    }
+    for (const warning of result.warnings) {
+        context.logger.warn(warning);
+    }
+}
 const DEFAULT_DEPENDENCIES = {
     buildCommandContext,
     resolveAssetsRoot,
@@ -18,6 +54,12 @@ const DEFAULT_DEPENDENCIES = {
             assetsRoot,
             ...options,
         });
+        const rootPackagePatch = await patchRootPackageJson({
+            repoRoot: context.cwd,
+            appName: options.appName,
+            dryRun: context.dryRun,
+            enabled: options.rootPatch,
+        });
         const config = await readOatConfig(context.cwd);
         config.documentation = {
             ...config.documentation,
@@ -30,6 +72,7 @@ const DEFAULT_DEPENDENCIES = {
                 ...options,
                 createdFiles: result.createdFiles,
                 appRoot: result.appRoot,
+                rootPackagePatch,
             });
             return;
         }
@@ -39,6 +82,7 @@ const DEFAULT_DEPENDENCIES = {
         context.logger.info(`  App name: ${options.appName}`);
         context.logger.info(`  Lint: ${options.lint}`);
         context.logger.info(`  Format: ${options.format}`);
+        logRootPackagePatch(context, rootPackagePatch);
     },
     upsertAgentsMdSection,
     readOatConfig,
@@ -75,6 +119,7 @@ async function runDocsInitCommand(context, options, dependencies) {
             providedSiteDescription: options.description,
             providedLint: options.lint,
             providedFormat: options.format,
+            providedRootPatch: options.rootPatch,
             inputWithDefault: dependencies.inputWithDefault,
             selectWithAbort: dependencies.selectWithAbort,
         });
@@ -170,6 +215,7 @@ export function createDocsInitCommand(overrides = {}) {
         'oxfmt',
         'none',
     ]))
+        .option('--no-root-patch', 'Skip patching the consumer root package.json')
         .option('--yes', 'Accept defaults without prompting')
         .action(async (options, command) => {
         const context = dependencies.buildCommandContext(readGlobalOptions(command));

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

@@ -12,6 +12,7 @@ export interface DocsInitResolvedOptions {
     siteDescription: string;
     lint: DocsLintMode;
     format: DocsFormatMode;
+    rootPatch: boolean;
 }
 export interface ResolveDocsInitOptionsInput {
     repoRoot: string;
@@ -24,6 +25,7 @@ export interface ResolveDocsInitOptionsInput {
     providedSiteDescription?: string;
     providedLint?: DocsLintMode;
     providedFormat?: DocsFormatMode;
+    providedRootPatch?: boolean;
     inputWithDefault: (message: string, defaultValue: string, ctx: PromptContext) => Promise<string | null>;
     selectWithAbort: <T extends string>(message: string, choices: SelectChoice<T>[], ctx: PromptContext) => Promise<T | null>;
 }

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;CACxB;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,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,CA+EzC;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,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"}

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

@@ -109,6 +109,7 @@ export async function resolveDocsInitOptions(input) {
         siteDescription,
         lint,
         format,
+        rootPatch: input.providedRootPatch ?? true,
     };
 }
 export const DEFAULT_DOCS_REPO_SHAPE_DEPENDENCIES = {

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

@@ -0,0 +1,23 @@
+type RootPackagePatchReason = 'missing-package-json' | 'no-build-script' | 'non-turbo-build-script' | 'ambiguous-shell-build-script' | 'existing-filter-flags' | 'existing-build-docs-script' | 'disabled';
+type RootPackagePatchStatus = 'applied' | 'dry-run' | 'skipped' | 'disabled' | 'already-configured';
+export interface RootPackagePatchResult {
+    status: RootPackagePatchStatus;
+    reason?: RootPackagePatchReason;
+    packageJsonPath: string;
+    diff?: string;
+    manualSnippet?: string;
+    warnings: string[];
+}
+interface RootPackagePatchDependencies {
+    readFile: (path: string, encoding: BufferEncoding) => Promise<string>;
+    writeFile: (path: string, content: string, encoding: BufferEncoding) => Promise<void>;
+}
+interface RootPackagePatchOptions {
+    repoRoot: string;
+    appName: string;
+    dryRun: boolean;
+    enabled: boolean;
+}
+export declare function patchRootPackageJson(options: RootPackagePatchOptions, dependencies?: RootPackagePatchDependencies): Promise<RootPackagePatchResult>;
+export {};
+//# sourceMappingURL=root-package.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"root-package.d.ts","sourceRoot":"","sources":["../../../../src/commands/docs/init/root-package.ts"],"names":[],"mappings":"AAMA,KAAK,sBAAsB,GACvB,sBAAsB,GACtB,iBAAiB,GACjB,wBAAwB,GACxB,8BAA8B,GAC9B,uBAAuB,GACvB,4BAA4B,GAC5B,UAAU,CAAC;AAEf,KAAK,sBAAsB,GACvB,SAAS,GACT,SAAS,GACT,SAAS,GACT,UAAU,GACV,oBAAoB,CAAC;AAMzB,MAAM,WAAW,sBAAsB;IACrC,MAAM,EAAE,sBAAsB,CAAC;IAC/B,MAAM,CAAC,EAAE,sBAAsB,CAAC;IAChC,eAAe,EAAE,MAAM,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,UAAU,4BAA4B;IACpC,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACtE,SAAS,EAAE,CACT,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,cAAc,KACrB,OAAO,CAAC,IAAI,CAAC,CAAC;CACpB;AAED,UAAU,uBAAuB;IAC/B,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;CAClB;AAsKD,wBAAsB,oBAAoB,CACxC,OAAO,EAAE,uBAAuB,EAChC,YAAY,GAAE,4BAAmD,GAChE,OAAO,CAAC,sBAAsB,CAAC,CA8IjC"}

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

@@ -0,0 +1,226 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+const DEFAULT_BUILD_SCRIPT = 'turbo run build';
+const ROOT_PACKAGE_PATH = 'package.json';
+const DEFAULT_DEPENDENCIES = {
+    readFile,
+    writeFile,
+};
+function runsTurboBuild(script) {
+    return /^turbo\s+(?:run\s+)?build(?:\s+.*)?$/.test(script.trim());
+}
+function hasShellComposition(script) {
+    return /&&|\|\||[;|`]|[$][(]/.test(script);
+}
+function removeFilterFlags(script) {
+    return script
+        .replace(/\s+--filter(?:=|\s+)(?:"[^"]*"|'[^']*'|\S+)/g, '')
+        .trim();
+}
+function getFilterFlags(script) {
+    return Array.from(script.matchAll(/\s+(--filter(?:=|\s+)(?:"[^"]*"|'[^']*'|\S+))/g), (match) => match[1]);
+}
+function buildExcludeFilter(appName) {
+    return `--filter='!${appName}'`;
+}
+function buildIncludeFilter(appName) {
+    return `--filter=${appName}...`;
+}
+function buildManualSnippet(appName, baseBuildScript) {
+    const buildScript = baseBuildScript?.trim() || DEFAULT_BUILD_SCRIPT;
+    return [
+        '"scripts": {',
+        `  "build": "${buildScript} ${buildExcludeFilter(appName)}",`,
+        `  "build:docs": "${buildScript} ${buildIncludeFilter(appName)}"`,
+        '}',
+    ].join('\n');
+}
+function inferIndentation(content) {
+    const match = /\n([ \t]+)"/.exec(content);
+    return match?.[1] ?? '  ';
+}
+function formatJsonWithOriginalStyle(original, value) {
+    const indentation = inferIndentation(original);
+    const trailingNewline = original.endsWith('\n') ? '\n' : '';
+    return `${JSON.stringify(value, null, indentation)}${trailingNewline}`;
+}
+function splitLines(content) {
+    const trimmed = content.endsWith('\n') ? content.slice(0, -1) : content;
+    return trimmed.length > 0 ? trimmed.split('\n') : [];
+}
+function buildDiffOperations(beforeLines, afterLines) {
+    const lengths = Array.from({ length: beforeLines.length + 1 }, () => Array(afterLines.length + 1).fill(0));
+    for (let beforeIndex = beforeLines.length - 1; beforeIndex >= 0; beforeIndex -= 1) {
+        for (let afterIndex = afterLines.length - 1; afterIndex >= 0; afterIndex -= 1) {
+            lengths[beforeIndex][afterIndex] =
+                beforeLines[beforeIndex] === afterLines[afterIndex]
+                    ? lengths[beforeIndex + 1][afterIndex + 1] + 1
+                    : Math.max(lengths[beforeIndex + 1][afterIndex], lengths[beforeIndex][afterIndex + 1]);
+        }
+    }
+    const operations = [];
+    let beforeIndex = 0;
+    let afterIndex = 0;
+    while (beforeIndex < beforeLines.length && afterIndex < afterLines.length) {
+        if (beforeLines[beforeIndex] === afterLines[afterIndex]) {
+            operations.push({ type: 'context', line: beforeLines[beforeIndex] });
+            beforeIndex += 1;
+            afterIndex += 1;
+            continue;
+        }
+        if (lengths[beforeIndex + 1][afterIndex] >=
+            lengths[beforeIndex][afterIndex + 1]) {
+            operations.push({ type: 'remove', line: beforeLines[beforeIndex] });
+            beforeIndex += 1;
+            continue;
+        }
+        operations.push({ type: 'add', line: afterLines[afterIndex] });
+        afterIndex += 1;
+    }
+    while (beforeIndex < beforeLines.length) {
+        operations.push({ type: 'remove', line: beforeLines[beforeIndex] });
+        beforeIndex += 1;
+    }
+    while (afterIndex < afterLines.length) {
+        operations.push({ type: 'add', line: afterLines[afterIndex] });
+        afterIndex += 1;
+    }
+    return operations;
+}
+function createUnifiedDiff(filePath, before, after) {
+    if (before === after) {
+        return '';
+    }
+    const beforeLines = splitLines(before);
+    const afterLines = splitLines(after);
+    const operations = buildDiffOperations(beforeLines, afterLines);
+    return [
+        `--- ${filePath}`,
+        `+++ ${filePath}`,
+        `@@ -1,${beforeLines.length} +1,${afterLines.length} @@`,
+        ...operations.map((operation) => {
+            const prefix = operation.type === 'context'
+                ? ' '
+                : operation.type === 'remove'
+                    ? '-'
+                    : '+';
+            return `${prefix}${operation.line}`;
+        }),
+    ].join('\n');
+}
+export async function patchRootPackageJson(options, dependencies = DEFAULT_DEPENDENCIES) {
+    const packageJsonPath = join(options.repoRoot, ROOT_PACKAGE_PATH);
+    if (!options.enabled) {
+        return {
+            status: 'disabled',
+            reason: 'disabled',
+            packageJsonPath,
+            warnings: [],
+        };
+    }
+    let originalContent;
+    try {
+        originalContent = await dependencies.readFile(packageJsonPath, 'utf8');
+    }
+    catch {
+        return {
+            status: 'skipped',
+            reason: 'missing-package-json',
+            packageJsonPath,
+            manualSnippet: buildManualSnippet(options.appName),
+            warnings: [
+                'Skipped root package.json patch: root package.json was not found.',
+            ],
+        };
+    }
+    const parsed = JSON.parse(originalContent);
+    const currentScripts = parsed.scripts ?? {};
+    const currentBuildScript = currentScripts.build;
+    if (!currentBuildScript) {
+        return {
+            status: 'skipped',
+            reason: 'no-build-script',
+            packageJsonPath,
+            manualSnippet: buildManualSnippet(options.appName),
+            warnings: [
+                'Skipped root package.json patch: scripts.build is missing, so there was no Turbo build command to update.',
+            ],
+        };
+    }
+    if (!runsTurboBuild(currentBuildScript)) {
+        return {
+            status: 'skipped',
+            reason: 'non-turbo-build-script',
+            packageJsonPath,
+            manualSnippet: buildManualSnippet(options.appName),
+            warnings: [
+                'Skipped root package.json patch: scripts.build does not run a Turbo build command, so OAT left it unchanged.',
+            ],
+        };
+    }
+    if (hasShellComposition(currentBuildScript)) {
+        return {
+            status: 'skipped',
+            reason: 'ambiguous-shell-build-script',
+            packageJsonPath,
+            manualSnippet: buildManualSnippet(options.appName),
+            warnings: [
+                'Skipped root package.json patch: scripts.build wraps the Turbo build in a larger shell expression, so OAT left it unchanged rather than rewriting the full command.',
+            ],
+        };
+    }
+    const excludeFilter = buildExcludeFilter(options.appName);
+    const filterFlags = getFilterFlags(currentBuildScript);
+    const hasUserAuthoredFilters = filterFlags.some((flag) => flag !== excludeFilter);
+    if (hasUserAuthoredFilters) {
+        return {
+            status: 'skipped',
+            reason: 'existing-filter-flags',
+            packageJsonPath,
+            manualSnippet: buildManualSnippet(options.appName, removeFilterFlags(currentBuildScript)),
+            warnings: [
+                'Skipped root package.json patch: scripts.build already uses `--filter`, so OAT left it unchanged rather than guessing how to merge filter semantics.',
+            ],
+        };
+    }
+    const nextScripts = { ...currentScripts };
+    const nextBuildScript = currentBuildScript.includes(excludeFilter)
+        ? currentBuildScript
+        : `${currentBuildScript.trim()} ${excludeFilter}`;
+    nextScripts.build = nextBuildScript;
+    const baseBuildScript = removeFilterFlags(currentBuildScript);
+    const desiredBuildDocsScript = `${baseBuildScript} ${buildIncludeFilter(options.appName)}`;
+    const warnings = [];
+    if (nextScripts['build:docs'] &&
+        nextScripts['build:docs'] !== desiredBuildDocsScript) {
+        warnings.push('Left scripts["build:docs"] unchanged because the root package already defines a different value.');
+    }
+    else {
+        nextScripts['build:docs'] = desiredBuildDocsScript;
+    }
+    const nextContent = formatJsonWithOriginalStyle(originalContent, {
+        ...parsed,
+        scripts: nextScripts,
+    });
+    const diff = createUnifiedDiff(ROOT_PACKAGE_PATH, originalContent, nextContent);
+    if (!diff) {
+        return {
+            status: 'already-configured',
+            packageJsonPath,
+            warnings,
+        };
+    }
+    if (!options.dryRun) {
+        await dependencies.writeFile(packageJsonPath, nextContent, 'utf8');
+    }
+    return {
+        status: options.dryRun ? 'dry-run' : 'applied',
+        reason: warnings.length > 0 ? 'existing-build-docs-script' : undefined,
+        packageJsonPath,
+        diff,
+        manualSnippet: warnings.length > 0
+            ? buildManualSnippet(options.appName, baseBuildScript)
+            : undefined,
+        warnings,
+    };
+}

package/package.json

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