@open-agent-toolkit/cli 0.3.24 → 0.3.26

package/assets/skills/oat-docs-analyze/scripts/package-drift.mjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+// Read-only, offline comparison used by oat-docs-analyze. No package resolution or install.
+import { readFile, realpath } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { parseArgs } from 'node:util';
+
+const shellQuote = (value) =>
+  `'${value.replaceAll("'", String.fromCharCode(39, 92, 39, 39))}'`;
+
+async function versionsForCli(executable) {
+  if (!executable)
+    throw new Error(
+      'Provide --cli with the installed oat executable or --versions with its bundled public-package-versions.json.',
+    );
+  let directory = dirname(await realpath(executable));
+  for (;;) {
+    try {
+      const pkg = JSON.parse(
+        await readFile(join(directory, 'package.json'), 'utf8'),
+      );
+      if (pkg.name === '@open-agent-toolkit/cli')
+        return join(directory, 'assets/public-package-versions.json');
+    } catch (error) {
+      if (error.code !== 'ENOENT') throw error;
+    }
+    const parent = dirname(directory);
+    if (parent === directory)
+      throw new Error(
+        'Cannot locate the running CLI bundle through this wrapper; supply --versions from that installed CLI.',
+      );
+    directory = parent;
+  }
+}
+
+try {
+  const { values } = parseArgs({
+    options: {
+      app: { type: 'string' },
+      versions: { type: 'string' },
+      cli: { type: 'string' },
+    },
+  });
+  if (!values.app) throw new Error('Required: --app <docs-app-directory>.');
+  const versionsPath = resolve(
+    values.versions ?? (await versionsForCli(values.cli)),
+  );
+  const versions = JSON.parse(await readFile(versionsPath, 'utf8'));
+  const appPath = resolve(values.app);
+  const manifest = JSON.parse(
+    await readFile(join(appPath, 'package.json'), 'utf8'),
+  );
+  const packages = [];
+  for (const section of [
+    'dependencies',
+    'devDependencies',
+    'optionalDependencies',
+  ]) {
+    for (const [name, declared] of Object.entries(manifest[section] ?? {})) {
+      if (
+        ![
+          '@open-agent-toolkit/docs-config',
+          '@open-agent-toolkit/docs-theme',
+          '@open-agent-toolkit/docs-transforms',
+        ].includes(name)
+      )
+        continue;
+      const bundled = versions[name.slice('@open-agent-toolkit/'.length)];
+      if (
+        typeof bundled !== 'string' ||
+        !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/.test(bundled)
+      )
+        throw new Error(`Missing/invalid bundled version for ${name}.`);
+      // Report installed package bytes when available, not just a declared range.
+      let installed = null;
+      try {
+        const installedManifest = JSON.parse(
+          await readFile(
+            join(appPath, 'node_modules', name, 'package.json'),
+            'utf8',
+          ),
+        );
+        if (typeof installedManifest.version !== 'string')
+          throw new Error(`Invalid installed version for ${name}.`);
+        installed = installedManifest.version;
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+      }
+      // Only stable numeric releases are orderable here; prereleases and other
+      // package-manager version forms need manual verification, never an upgrade.
+      const stable = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/;
+      let status = 'unverified';
+      if (
+        installed !== null &&
+        stable.test(installed) &&
+        stable.test(bundled)
+      ) {
+        const left = installed.split('.').map(BigInt);
+        const right = bundled.split('.').map(BigInt);
+        const differing = left.findIndex(
+          (part, index) => part !== right[index],
+        );
+        status =
+          differing === -1
+            ? 'current'
+            : left[differing] < right[differing]
+              ? 'drift'
+              : 'ahead';
+      }
+      packages.push({
+        name,
+        section,
+        declared,
+        installed,
+        bundled,
+        status,
+        upgradeCommand:
+          status === 'drift' || status === 'current'
+            ? `pnpm --dir ${shellQuote(appPath)} add${section === 'devDependencies' ? ' --save-dev' : section === 'optionalDependencies' ? ' --save-optional' : ''} ${name}@${bundled}`
+            : null,
+      });
+    }
+  }
+  process.stdout.write(
+    `${JSON.stringify({ versionsPath, appPath, packages }, null, 2)}\n`,
+  );
+} catch (error) {
+  process.stderr.write(`${error.message}\n`);
+  process.exitCode = 1;
+}

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

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash(git:*), Bash(gh:*), Bash(oat:*), Bash(pnpm:*), Bash(bash:*), Bash(jq:*), Bash(mkdir:*), Bash(date:*), Bash(echo:*), Bash(cd:*), Bash(pwd:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: '1.4.5'
+  version: '1.4.6'
 ---
 
 # Docs Apply
@@ -33,12 +33,12 @@ Before a parent-branch commit, verify `oat internal commit-paths --help` succeed
 
 - No unapproved documentation changes.
 - No branch creation before the recommendation plan is reviewed.
-- No changes outside the documentation scope except deterministic nav sync and tracking updates.
+- No changes outside the documentation scope except the approved IA record/config mirrors, owner-authorized nav sync, tracking updates, and the individually approved tooling-update carve-out below.
 
 **ALLOWED Activities:**
 
 - Reading analysis artifacts and the current docs surface.
-- Creating or updating docs files and `mkdocs.yml` when approved. Fumadocs `meta.json` files change only through `oat docs nav sync`.
+- Creating or updating docs files and hand-authored navigation when approved. Nav-sync-owned navigation changes only through `oat docs nav sync`; undeclared ownership blocks regeneration.
 - Running `oat docs nav sync` after approved structural changes.
 - Creating branches, commits, and optional PRs.
 
@@ -93,7 +93,13 @@ When executing this skill, provide lightweight progress feedback so the user can
 
 ### Step 0: Intake - Find Analysis Artifact
 
-Locate the most recent docs analysis artifact:
+The one input is an **analysis artifact path plus approved recommendation IDs**.
+Accept an explicitly supplied artifact; when none is supplied, offer the newest
+artifact below and confirm that it is the reviewed input. Never silently switch
+to a newer artifact after approval. IDs identify recommendations within that
+artifact, remain stable through artifact review, and are never reassigned.
+
+Locate a candidate when no artifact path was supplied:
 
 ```bash
 ls -t .oat/repo/analysis/docs-*.md 2>/dev/null | head -1
@@ -103,6 +109,8 @@ If none exists, stop and instruct the user to run `oat-docs-analyze`.
 
 Validate that each recommendation in the artifact includes:
 
+- a unique stable ID (for example `R-001`)
+- `approval: explicit | default`
 - evidence
 - confidence
 - disclosure
@@ -158,9 +166,19 @@ For review-mode and follow-up decisions, use host-aware prompting:
 
 If the user chooses `apply all`:
 
-- confirm the full plan
-- capture any global notes that apply across the whole plan
-- treat all non-blocked recommendations as approved unless the user names exceptions
+- confirm the full plan and capture global notes
+- approve only non-blocked `approval: default` recommendations, excluding named exceptions
+- Blanket approval never approves an `approval: explicit` recommendation.
+- Ask for individual approval by recommendation ID for each explicit item. A
+  restructure block always needs its own approval, including its full map and
+  old-URL plan; approving a different block does not approve it.
+
+In unattended mode, skip every explicit recommendation even when an input list
+names its ID; report `explicit_requires_interactive_approval` in the structured
+result. Never interpret automation configuration or `apply all` as individual
+approval. Missing/unknown approval classes or duplicate/unknown IDs block intake.
+The approved-ID list is captured at this approval step, not inferred from prose.
+An input list alone does not prove individual approval for an explicit item.
 
 If the user chooses `apply interactively`, ask for each recommendation:
 
@@ -174,11 +192,12 @@ If the user chooses `discuss`, answer questions, revise the plan if needed, and
 - `apply interactively`
 - `discuss`
 
-If all recommendations are skipped, stop without changing files.
+If all recommendations are skipped, emit the structured result with reasons and stop without changing files.
 
 Build an `APPLIED_PLAN_DETAILS` block from approved or modified recommendations with:
 
 - recommendation id
+- approval class and individual approval evidence when required
 - action
 - target path
 - disclosure
@@ -216,7 +235,7 @@ locators/provenance into the apply plan; do not silently re-resolve different
 sources. Verify cited inputs still exist and remain read-only outside the repo.
 Local AGENTS/contributing rules stay authoritative; a conflict is `ask_user`
 and blocks that recommendation pending a fresh analysis/user decision. Cite
-sources without copying private contents. This hook adds no restructure action.
+sources without copying private contents.
 
 Before the first approved write, initialize `OWNED_OUTPUT_FILES=()`. Append
 each exact successfully created, modified or removed path at that write,
@@ -235,10 +254,87 @@ For each approved recommendation:
    - `omit` -> do not encode the item in the docs change
    - `ask_user` -> require explicit user confirmation before writing
 
+#### Record an accepted IA
+
+Only an approved `record-ia` recommendation authorizes persistence. Before any
+PJM/decision write run `oat pjm doctor --json` in the target repo and inspect
+`adoption.state`; absent/partial adoption routes to `oat pjm init` before the
+record, never silently writes an unmanaged decision. Read the target's
+`.oat/repo/AGENTS.md`, decision conventions and existing decision index; update
+an existing matching record rather than duplicate it. Create a new record with
+`oat decision new "Documentation information architecture" --status accepted
+--context "<approved evidence>"` and its supported `--decision`/`--consequences` options
+(check `--help`). The command owns index generation; never hand-edit the index.
+
+Write a short `## Information architecture` section with tracks, organizing
+principle per track, placement rules and verification overlay. For Fumadocs and
+MkDocs put it in the docs-app `AGENTS.md`, preserving existing guidance. For
+Markdown put it in the contributing page; create no docs-root `AGENTS.md`.
+Link the decision and authored section reciprocally. They remain authoritative;
+a conflict with config becomes `ask_user`, never a config-driven rewrite.
+
+Mirror the accepted record using shared repo config only:
+`oat config set documentation.ia '<JSON>'`, with exactly `{preset, decision,
+tracks?: [{path, principle}], verification?: 'triad'|'agent-only'|'none'}`.
+`decision` is repo-relative; preserve guidance and unrelated config. For a
+framework surface, separately record the operator's approved sidebar owner via
+`oat config set documentation.navOwner nav-sync` or `hand-authored`. Missing
+ownership stays undeclared and blocks automatic regeneration. Markdown ignores
+navOwner and never runs nav sync. New-scaffold default ownership and preset
+materialization are not implemented by this persistence step.
+
+#### Restructure one approved block
+
+`restructure` requires `approval: explicit` and one individual approval per
+block before any move. Use the apply-plan block: source→destination map, source
+and destination parent Contents edits, grep-derived inbound references (including
+relative links, anchors and assets), exact rewrite list, and old-URL recovery.
+Search the whole repo for each old path/basename with `rg`; resolve relative
+references from their original file and check them again from their new location.
+Keep links to moved headings working. Do not treat search hits in examples or
+unrelated same-name files as automatic rewrites.
+
+Choose recovery supported by the actual deployment: Next static export does
+not support Next config redirects (see [Next static-export unsupported features](https://nextjs.org/docs/app/guides/static-exports#unsupported-features)).
+Use an authored stub at the old route with a relative pointer, or an approved
+archive pointer; a redirect requires verified framework/host support and stays
+manual when it needs app/host config. Never edit `not-found.tsx` through this
+carve-out. Retired pages retain a stub/archive pointer and a parent Contents
+update, never a silent delete. Preserve stub routes in the approved reader map
+where the framework needs them to build.
+
+Apply one block as one exact-path implementation commit; do not combine it with
+another block. Validate all rewritten inbound links and old URLs under the
+actual base path. With `navOwner: nav-sync`, run nav sync then nav sync --check
+with the explicit app target. With `hand-authored`, update approved hand-authored
+navigation and compare membership/order against Contents read-only; never run a
+writing nav sync. With undeclared ownership, report `ask_user` before navigation
+writes. Markdown checks files/Contents/links only. Re-run `oat-docs-analyze`
+after each block, preserving residual findings instead of claiming a clean run.
+
+#### Individually approved tooling update
+
+A `tooling-update` recommendation has `approval: explicit`. Even with individual
+approval, its out-of-Markdown allowance is only these three operations:
+
+1. Bump the docs app's existing `@open-agent-toolkit/docs-*` dependencies to the
+   bundled versions using the artifact's exact upgrade command (preserve dependency
+   section and package manager; include its resulting lockfile only). Never downgrade
+   an installed version: `ahead` or `unverified` requires CLI selection/update or
+   manual verification before re-analysis, not a docs-package tooling update.
+2. Run `oat docs migrate --docs-dir <authored-root> --apply` only for its currently
+   supported admonition conversions and injected frontmatter; inspect the diff.
+3. Run the docs build verifier from the app's existing scripts.
+
+Scaffold changes the CLI cannot make (app config, routes, package scripts) are
+`manual`: report the required change and ID without editing those files. This
+allowance does not permit application dependencies, host settings, arbitrary
+migrations or an app-shell rebuild. Other out-of-scope prohibitions remain.
+
 When approved actions involve docs app creation or nav updates:
 
 - Use `oat docs init` for scaffolding when appropriate.
-- Use `oat docs nav sync` instead of manually editing nav when the CLI helper can generate it. In Fumadocs apps it writes strict `meta.json` files and reports pages no `## Contents` map lists (`unlisted` in `--json`); resolve a reported page through an approved `## Contents` change, never by hand-editing `meta.json`.
+- Use `oat docs nav sync` instead of manually editing nav only when recorded `navOwner: nav-sync` authorizes it. In Fumadocs apps it writes strict `meta.json` files and reports pages no `## Contents` map lists (`unlisted` in `--json`); resolve a reported page through an approved `## Contents` change, never by hand-editing `meta.json`.
 
 Negative rules:
 
@@ -261,7 +357,7 @@ full configured content tree; keep the authored config index unchanged.
 For framework apps, discover actual scripts and run the smallest relevant
 verification set based on what changed; these examples apply only when present:
 
-- `oat docs nav sync`
+- `oat docs nav sync --target-dir <docs-app>` then `--check` only for `nav-sync` ownership; hand-authored/undeclared navigation gets read-only Contents membership/order comparison
 - `pnpm --dir <docs-app> docs:lint` (no-op when no linter is configured)
 - `pnpm --dir <docs-app> docs:format:check`
 - `pnpm --dir <docs-app> docs:build`
@@ -270,7 +366,7 @@ If no docs app exists yet, use file-level verification and confirm the structura
 
 ### Step 6: Commit and PR
 
-Commit the approved changes:
+Commit the approved changes (for restructure, repeat with one retained identity and exact path list per approved block; exclude already committed blocks from any final aggregate commit and skip an empty aggregate):
 
 ```bash
 OWNED_COMMIT_PATHS=("${OWNED_OUTPUT_FILES[@]}")
@@ -344,6 +440,29 @@ PR creation failed. To create manually:
 
 ### Step 7: Update Tracking and Output Summary
 
+Always emit this structured result, including no-op/unattended runs. Each input
+recommendation ID appears in exactly one outcome; failed verification is a
+failure, never an applied success. Unsupported scaffold work is skipped with
+reason `manual` and its required change. Include individual approval evidence
+in the plan, not invented in this result.
+
+```json
+{
+  "analysisArtifact": ".oat/repo/analysis/docs-example.md",
+  "approvedRecommendationIds": ["R-001"],
+  "applied": ["R-001"],
+  "skipped": [
+    { "id": "R-002", "reason": "explicit_requires_interactive_approval" }
+  ],
+  "failed": []
+}
+```
+
+Failed entries use `{ "id": "R-003", "reason": "<verification/error>" }`.
+Report partial writes and stop on a failure; never continue by widening scope.
+
+### Tracking and summary
+
 Update shared tracking:
 
 ```bash

package/assets/skills/oat-docs-apply/references/apply-plan-template.md

@@ -25,7 +25,7 @@ Keep the analysis selection; do not copy private contents or invent missing evid
 
 Review the full recommendation set first, then choose a review mode:
 
-- **apply all** — approve the full set as presented
+- **apply all** — approve non-blocked default items; explicit items require individual approval by ID
 - **apply interactively** — review recommendation by recommendation
 - **discuss** — pause to talk through the plan before approving
 
@@ -41,19 +41,21 @@ blocked pending a fresh analysis rather than guessed.
 
 ## Recommendations
 
-### {N}. {Action}: `{target-path}`
-
-| Field        | Value                                                             |
-| ------------ | ----------------------------------------------------------------- |
-| Action       | {create / update / move / scaffold / sync-nav}                    |
-| Target       | `{target-path}`                                                   |
-| Rationale    | {why this recommendation exists}                                  |
-| Source       | {finding # / contract gap / nav issue}                            |
-| Evidence     | {exact file refs / config / docs that justify the recommendation} |
-| Confidence   | {high / medium / low}                                             |
-| Disclosure   | {inline / link_only / omit / ask_user}                            |
-| Link Targets | {path or URL when link_only; otherwise N/A}                       |
-| Helper       | `oat docs nav sync` / `oat docs init` / `manual edit`             |
+### {R-NNN}. {Action}: `{target-path}`
+
+| Field        | Value                                                                                              |
+| ------------ | -------------------------------------------------------------------------------------------------- |
+| ID           | {R-NNN; stable within the source artifact}                                                         |
+| approval     | {explicit / default; never inferred from blanket consent}                                          |
+| Action       | {create / update / move / scaffold / sync-nav / record-ia / restructure / tooling-update / manual} |
+| Target       | `{target-path}`                                                                                    |
+| Rationale    | {why this recommendation exists}                                                                   |
+| Source       | {finding # / contract gap / nav issue}                                                             |
+| Evidence     | {exact file refs / config / docs that justify the recommendation}                                  |
+| Confidence   | {high / medium / low}                                                                              |
+| Disclosure   | {inline / link_only / omit / ask_user}                                                             |
+| Link Targets | {path or URL when link_only; otherwise N/A}                                                        |
+| Helper       | `oat docs nav sync` / `oat docs init` / `manual edit`                                              |
 
 **Context:** {1-2 sentences}
 
@@ -64,6 +66,29 @@ blocked pending a fresh analysis rather than guessed.
 
 {Repeat for each recommendation}
 
+## Restructure block (one individually approved ID, one exact-path commit)
+
+- ID / individual approval evidence: {R-NNN / operator choice, or pending}
+- Source → destination map: {every moved/retired page}
+- Parent Contents edits: {source and destination indexes}
+- Grep-derived inbound rewrites: {command + referring file:line + old/new link,
+  including anchors/assets and rewritten links inside moved pages}
+- Old-URL strategy: {verified host redirect, authored stub, or archive pointer;
+  static export: no assumed Next redirects}
+- Retired-page recovery: {retained stub/archive pointer + parent Contents entry}
+- Sidebar owner: {nav-sync / hand-authored / undeclared; Markdown: ignored}
+- Verification: {nav-sync write then --check, or read-only membership/order
+  comparison; file/link checks; actual base-path old URL; analyze rerun}
+- Exact owned files and commit identity: {list including both rename sides}
+
+## IA recording / tooling limits
+
+- Record IA: {adoption.state from target pjm doctor; decision command/path;
+  framework AGENTS or Markdown contributing section; shared mirror JSON}
+- Tooling update: {individually approved ID; exact docs-app docs-\* upgrade
+  command; supported migrate conversions; existing build verifier}
+- Unsupported app config/routes/scripts: {manual required changes; no edits}
+
 ## Summary of Actions
 
 | #   | Action                                 | Target   | Disclosure                       | Decision                                                 |
@@ -73,6 +98,25 @@ blocked pending a fresh analysis rather than guessed.
 
 **Total:** {N} approved, {N} modified, {N} skipped
 
+## Structured result
+
+```json
+{
+  "analysisArtifact": "{path}",
+  "approvedRecommendationIds": ["R-001"],
+  "applied": ["R-001"],
+  "skipped": [
+    { "id": "R-002", "reason": "explicit_requires_interactive_approval" }
+  ],
+  "failed": []
+}
+```
+
+Every input ID has exactly one outcome. Unattended explicit items are skipped
+regardless of the supplied ID list. Missing/unknown class or ID blocks intake.
+Use reason `manual` with the required change for unsupported scaffold work;
+failed entries carry an ID and error/verification reason.
+
 ## Proceed?
 
 Confirm to begin applying the approved documentation changes.

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

@@ -6,7 +6,7 @@ disable-model-invocation: true
 user-invocable: true
 allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
 metadata:
-  version: '1.4.0'
+  version: '1.4.2'
 ---
 
 # Docs Bootstrap
@@ -321,7 +321,7 @@ Resolution options:
     ```
 
 - **`repair`** — Fix the existing setup in place rather than replacing it. Delegate to the docs-analysis pack.
-  - **Allowed mutations (by this sub-procedure):** None directly. The bootstrap skill does not modify existing docs app files. It hands off to `oat-docs-analyze` (read-only audit) and, with user approval, to `oat-docs-apply` (applies approved recommendations).
+  - **Allowed mutations (by this sub-procedure):** None directly. The bootstrap skill does not modify existing docs app files. It hands off to `oat-docs-analyze` (read-only audit), then passes the analysis artifact plus approved recommendation IDs to `oat-docs-apply`; explicit items require individual approval.
   - **Preserved state:** Existing docs app directory, the `documentation` config section, the root `AGENTS.md` `## Documentation` section — all preserved unless analyze surfaces a recommendation and the user approves it via apply.
   - **Stop conditions:**
     - Invoke `oat-docs-analyze` and surface its report to the user. If analyze cannot produce meaningful recommendations (e.g., `documentation.index` points at a missing file, or the app directory is empty), **stop the flow before Scaffold Runner**, report what analyze found, and ask the user whether to escalate to `replace`.
@@ -390,9 +390,19 @@ through `oat-docs-analyze --ia`; it does not return to scaffold afterward.
    `ask_user` with local/external source citations. Non-repo guidance stays read-only
    and private exemplars are never copied. Cite ordered sources in the proposal
    and final summary, including the built-in path when it wins.
-6. Carry the proposal to analyze/apply content kickoff. This stage proposes only:
-   it does not persist an accepted IA, restructure pages or scaffold preset trees.
-   CLI scaffold output remains the existing starter; those capabilities ship later.
+6. Obtain explicit approval of the selected IA before persistence. After setup,
+   use apply's `record-ia` procedure: target-repo `oat pjm doctor --json` and
+   adoption check before `oat decision new`, an Information architecture section
+   in the framework docs-app AGENTS.md or Markdown contributing page, and shared
+   `documentation.ia` mirror. Preserve existing guidance; the authored record is
+   authoritative. If approval/adoption is pending, retain the proposal and report
+   it unrecorded. Do not silently initialize PJM. For an existing surface, hand
+   off an analysis artifact plus approved recommendation IDs to apply, with
+   individual approval for explicit record/restructure/tooling items.
+   This IA selection stage does not materialize preset trees or change ownership for an existing app.
+   Sidebar ownership is separately chosen for existing framework apps; absent
+   remains undeclared, Markdown ignores it, and no automatic nav generation is
+   authorized by IA approval alone.
 
 ### Step 3: Scaffold Runner
 
@@ -402,6 +412,10 @@ Print `[3/7] Scaffolding…` at the start of this step.
 
 **Precondition:** The Conflict Resolution Contract's "Allowed mutations" have completed and the working-tree state matches what the CLI expects (Step 2's pre-scaffold invariant). If any resolution-triggered mutation is still pending, **do not invoke the CLI** — stop the flow and surface the missing state.
 
+For an explicitly fresh Fumadocs/MkDocs app, current CLI init writes `documentation.navOwner: nav-sync` and generates navigation after successful scaffold/config. An explicitly selected new app in a repository with prior docs config is fresh creation; preserve the old app's authored files. This does not authorize regeneration of an existing app: keep undeclared/hand-authored ownership untouched and use the existing analyze/apply handoff. IA approval alone never authorizes navigation writes. Markdown and dry runs run no nav sync.
+
+Inspect the generated package scripts rather than adding a duplicate patch: Fumadocs `prebuild` and MkDocs `docs:build` run `nav sync --check`, using external `oat` from the app directory with `--target-dir .`, or source-workspace CLI with the explicit quoted repo-relative app. A stale navigation check requires fixing authored Contents and explicitly syncing owned navigation before retrying, not deleting the check or silently regenerating an undeclared owner.
+
 **3a. Assemble CLI flags.**
 
 Build the flag list deterministically from the Input Result (Step 2e) and the Capability Detection result (Step 3b). Non-interactive mode is mandatory — the skill owns the interactive flow; the CLI runs headless.
@@ -702,6 +716,8 @@ Narrate each field actually present in their config (skip fields that are absent
   - **Fumadocs:** this should be the generated app-root manifest, usually `<appRoot>/index.md`, after the successful build ran `oat docs generate-index`. Explain that this machine-shaped file is how tools inspect the full Markdown file tree, and that the authored source map the user edits is a separate file at `<appRoot>/docs/index.md` with its own `## Contents`.
   - **Fumadocs stale path warning:** if the inspected path still points inside `<appRoot>/docs/` after build verification, do not teach that as normal. Surface it as a warning that `oat docs generate-index` did not update `documentation.index` as expected, then point the user to Section B for the generated/authored split.
   - **MkDocs:** this should point at the configured MkDocs nav/config surface, usually `<appRoot>/mkdocs.yml` and matching `documentation.config`. Explain that the YAML file contains the generated/derived `nav:` block when `oat docs nav sync` is used, while authored `docs/index.md` and nested `## Contents` sections remain the source maps the user edits.
+- **`documentation.navOwner`** — fresh framework init explicitly sets `nav-sync`; existing absent means undeclared and `hand-authored` stays authored. Never infer write permission from missing ownership. Markdown ignores it.
+- **`documentation.nonReaderPaths`** — if present, content-root-relative bounded globs omit drafts/templates from nav inventory, explicit Contents links, nav checks and manifests; excluded metadata is not rewritten. OAT Fumadocs collections also omit rendering when wired through source config. Pinned MkDocs 1.4.2 still renders these routes; explain the limitation and do not add a plugin or upgrade as a bootstrap repair. `documentation.excludes` stays manifest-only. Do not add exclusions or mutate this setting without an approved content/config change through the existing workflow.
 - **`documentation.config`** — optional path to the framework configuration, such as `mkdocs.yml` or `next.config.js`. Inspect whichever path is actually configured.
 - **`documentation.requireForProjectCompletion`** — the opt-in collected in Step 5e. If `true`, `oat-project-complete` will block project completion until the project records `oat_docs_updated: complete` or an explicit `skipped` after the `oat-project-document` prompt. Explain whichever value is set on this project.
 
@@ -734,11 +750,12 @@ This section explains why tooling works at all — the contract every OAT docs t
 
 Narrate:
 
-- **Every directory under `docs/` has an `index.md`.** No exceptions, no `overview.md`, no README-as-index. Missing `index.md`s are the first thing `oat-docs-analyze` flags.
+- **Every non-excluded Markdown-bearing directory under `docs/` has an `index.md`.** Asset-only and non-reader trees are exempt; use no `overview.md` or README-as-index. Missing reader indexes are an analyze finding.
 - **Every `index.md` has a `## Contents` section.** The section is a plain Markdown bulleted list of links to the direct children of that directory — both subdirectory `index.md`s and leaf pages.
 - **Link targets use `.md` extensions.** Leaf pages link as `[Title](page.md)`; subdirectories link as `[Section](subdir/index.md)`. The `@open-agent-toolkit/docs-transforms` remark-links plugin normalizes these at build time for Fumadocs routing (`.md` stripped; `dir/index.md` collapsed to `dir`). `.md`-suffixed authored links render correctly **and** let agents follow each link to the target file without path inference — the best of both worlds.
 - **The `## Contents` section is the machine-readable local map.** For Fumadocs, `oat docs nav sync` reads it to write the committed `meta.json` sidebar files, and agents compare it against the generated app-root manifest. For MkDocs, `oat docs nav sync` reads it to update `mkdocs.yml` `nav:`. `oat-docs-analyze` reads the same authored source to find orphaned pages and stale generated artifacts.
-- **Anything not listed in `## Contents` is invisible to the tooling.** Adding a Markdown file is not enough — it must also appear under the parent `index.md`'s `## Contents`.
+- **Contents uses dash links and optional `### <Label>` groups.** Groups become Fumadocs separators or MkDocs nested nav. Empty authored groups and `*`/`+` link bullets are file/line errors; add a dash link/remove the empty heading, or replace the bullet with `-`.
+- **Reader pages must appear in the local Contents map for navigation.** The manifest retains deterministic unlisted fallback entries and flags them; adding a file alone does not put it in the sidebar. Non-reader exclusions take precedence over explicit Contents links.
 
 Show the user their own `docs/index.md` `## Contents` as a concrete example (read the file and paste the relevant 5–15 lines). Then note: "That's the pattern. Every directory you create from now on follows the same shape — `.md`-suffixed links, bulleted list, dash-separated summary per entry."
 
@@ -836,7 +853,13 @@ Delegate — do not re-implement analyze/apply logic here.
 
 1. Invoke the `oat-docs-analyze` skill against the scaffolded app. Pass the Inspection Result's `documentation.root` path so analyze targets the right surface. Wait for analyze to complete.
 2. Surface analyze's report to the user in its native form — do not re-summarize. The user reads it, decides which recommendations to approve.
-3. If the user approves any recommendations, invoke the `oat-docs-apply` skill with the approved subset. Wait for apply to complete.
+3. Capture the analysis artifact path and approved recommendation IDs, then
+   invoke `oat-docs-apply` with exactly that input. Preserve every approval class:
+   blanket approval covers only default items; explicit items need individual
+   approval by ID, and unattended runs skip/report them. Wait for apply's
+   structured applied/skipped-with-reason/failed IDs; report partial/manual work.
+   Never pass an unexplained "approved subset" or treat kickoff consent as
+   approval of every recommendation.
 4. Report the outcome back briefly: branch name, PR URL if opened, files changed count.
 
 If analyze produces no recommendations (the scaffold is complete and nothing's missing — unlikely on a fresh scaffold but possible), tell the user and skip apply.
@@ -867,6 +890,8 @@ Location:    {appRoot}
 Framework:   {framework}
 IA guidance: {ordered selected locators + explicit/conversation/shared/user/builtin provenance}
 IA proposal: {candidate recommendation, nearest preset, conflicts or none}
+IA record: {decision + authored section + shared mirror, or pending reason}
+Apply handoff: {artifact path, approved IDs, applied/skipped/failed result or not run}
 Config:      {configPath} (documentation section)
 
 Created:

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

@@ -7,7 +7,7 @@
   "scripts": {
     "predev": "fumadocs-mdx && {{GENERATE_INDEX_CMD}}",
     "dev": "next dev",
-    "prebuild": "fumadocs-mdx && {{GENERATE_INDEX_CMD}}",
+    "prebuild": "{{NAV_SYNC_CHECK_CMD}} && fumadocs-mdx && {{GENERATE_INDEX_CMD}}",
     "build": "next build",
     "start": "next start",
     "docs:lint": "{{DOCS_LINT_SCRIPT}}",

package/assets/templates/docs-app-fuma/source.config.ts

@@ -1,10 +1,15 @@
 import { createSourceConfig } from '@open-agent-toolkit/docs-config';
 import { defineConfig, defineDocs } from 'fumadocs-mdx/config';
 
-const sourceConfig = createSourceConfig();
+const sourceConfig = createSourceConfig({
+  oatConfigFile: '{{OAT_CONFIG_RELATIVE_PATH}}',
+  appRoot: '.',
+});
 
 export const docs = defineDocs({
   dir: sourceConfig.contentDir,
+  docs: sourceConfig.docs,
+  meta: sourceConfig.meta,
 });
 
 export default defineConfig({

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

@@ -6,7 +6,7 @@
   "description": "MkDocs Material documentation for {{SITE_NAME}}.",
   "scripts": {
     "docs:dev": "mkdocs serve",
-    "docs:build": "mkdocs build",
+    "docs:build": "{{NAV_SYNC_CHECK_CMD}} && mkdocs build",
     "docs:setup": "sh ./setup-docs.sh",
     "docs:lint": "{{DOCS_LINT_SCRIPT}}",
     "docs:format": "{{DOCS_FORMAT_SCRIPT}}",
@@ -14,6 +14,6 @@
     "test": "echo 'Documentation tests complete'"
   },
   "devDependencies": {
-{{DEV_DEPENDENCIES}}
+    "@open-agent-toolkit/cli": "{{OAT_CLI_DEP}}"{{DEV_DEPENDENCIES}}
   }
 }

package/dist/commands/config/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/commands/config/index.ts"],"names":[],"mappings":"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"}