@open-agent-toolkit/cli 0.3.10 → 0.3.11

package/assets/docs/workflows/projects/evidence-layers.md

@@ -77,14 +77,12 @@ section.
 
 For project-aware work, the calling workflow records each launch in its run
 record in `implementation.md` (request ID, `Dispatch:` stamp, launch status,
-terminal outcome). Persisting one generic record per request under the
-project's `dispatch/` directory with `oat project dispatch record` is optional
-and off by default; no lifecycle skill or command consumes those files. Managed
-effort-pinned Claude launches still pass the real resolver result, generated
-definition, and proposed payload through the command without `--project`
-before launch. That validation-only call derives the configured invocation and
-does not persist a journal file. When a host opts in, the generic snake-case
-fields remain authoritative. A namespaced `oat` block adds
+terminal outcome); that run record is the only launch record.
+`oat project dispatch record` validates a generic record and writes nothing.
+Managed effort-pinned Claude launches pass the real resolver result, generated
+definition, and proposed payload through it before launch, and that
+validation-only call derives the configured invocation. In a validated record
+the generic snake-case fields remain authoritative. A namespaced `oat` block adds
 only canonical-role identity, proven pre-start rejection, fallback linkage,
 and optional runtime observation. `oat project dispatch canonical-role`
 prints the canonical-role-resolution event read-only, so callers do not

package/assets/docs/workflows/projects/implementation-execution.md

@@ -76,10 +76,10 @@ that scope.
 Before a native launch, the root constructs and redacts the complete generic
 dispatch record and OAT role event. When the host returns, it writes the
 request ID, the `Dispatch:` stamp, and the accepted or `blocked-before-start`
-result into the run record in `implementation.md`; persisting a per-dispatch
-file with `oat project dispatch record` is optional and off by default. Before
-an effort-pinned managed Claude launch, the root must still run that command
-without `--project` as a validation-only boundary. It supplies the real
+result into the run record in `implementation.md`, the only launch record.
+Before an effort-pinned managed Claude launch, the root must run
+`oat project dispatch record`, which writes nothing, as a validation-only
+boundary. It supplies the real
 resolver result, generated definition, and proposed launch payload, and launches
 only the payload returned by the accepted envelope. An accepted launch closes
 replacement. Only an explicit rejection proving no child started permits one
@@ -319,6 +319,32 @@ and start a new gate generation. Beyond the version's own exclusion set, no
 implementation or closeout output path is excluded from the comparison. Legacy unqualified fingerprints retain the older
 fail-closed descendant-path behavior and are not migrated in place.
 
+There is no automatic test-only freshness exception. An operator can instead
+waive named stale-making descendants of an `effective-delta-v1` or
+`effective-delta-v2` generation (`DR-260927-operator-waiver-for-test-only`).
+Each waiver is appended to `oat_implement_exit_gate.waivers` with who waived,
+the reason, the covered `from_commit..to_commit` range, the effective-delta
+fingerprint at the range end (in the generation's own version), and a UTC
+timestamp. A waiver never rewrites `reviewed_head`, the implementation
+fingerprint, `freshness_head`, or the freshness fingerprint, and an earlier
+waiver is never edited. Agents write a waiver only on an explicit operator
+instruction. Under `OAT_AUTONOMOUS=1` an attempted waiver write is refused,
+and a run that finds a stale generation persists `stale` and starts a new gate
+run instead of pausing. A waived generation stays fresh only while nothing
+substantive lands after the covered range, under both versions; a malformed or
+unverifiable waiver fails closed as stale. The project summary and the final PR
+description's Verification section list every waiver.
+
+The waiver is offered where staleness is found. Before an interactive
+`oat-project-implement` run persists an allowed generation as `stale` because
+of descendant commits no waiver covers, it lists those commits and asks the
+operator to waive that range or start a new gate run; it persists `stale` only
+when the operator declines. An autonomous run never offers a waiver and starts
+a new gate run. An operator may also record a waiver before resuming
+implementation, for example after `oat-project-next` reports stale state, by
+giving the range, name, and reason in the instruction that resumes
+`oat-project-implement`.
+
 This narrow merge-only exemption relies on fresh repository CI, automated
 review such as Bugbot, and lifecycle self-review to cover integration risk.
 Those checks do not substitute for the semantic gate on the full

package/assets/docs/workflows/projects/lifecycle.md

@@ -65,6 +65,12 @@ allowed and fresh disposition before pre-approval work starts. A
 not inferred from missing state, and a null, missing, or unrecognized resolver
 result fails closed as unresolved instead.
 
+A later substantive change makes an allowed result stale, test-only changes
+included. Only an operator can keep it fresh, by recording an append-only
+exit-gate waiver for the exact commits; agents never issue one. An autonomous
+run that finds a stale result persists `stale` and starts a new gate run; it
+refuses only an attempted waiver write. The summary and PR description list every waiver.
+
 After implementation closeout finishes:
 
 1. **Summary** (`oat-project-summary`) — generates `summary.md` as institutional memory from project artifacts; PR-final and completion will auto-refresh it if you have not already run it or if it is stale
@@ -75,7 +81,7 @@ After implementation closeout finishes:
    - GitHub PR feedback delegates to `oat-project-review-receive-remote`
    - Review artifacts delegate to `oat-project-review-receive`
    - After revision tasks complete, state returns to `pr_open`
-5. **Complete** (`oat-project-complete`) — accepts any phase status (`pr_open`, `complete`, `in_progress`), auto-refreshes `summary.md` before closeout when needed, and archives when selected by the workflow preference or completion prompt
+5. **Complete** (`oat-project-complete`) — accepts any phase status (`pr_open`, `complete`, `in_progress`), auto-refreshes `summary.md` before closeout when needed, and archives when selected by the workflow preference or completion prompt. Before any completion write it runs the read-only `oat project closeout-check`: a configured, autonomous, or lite closeout whose `oat_post_implement_sequence` snapshot is missing, malformed, or incomplete stops and routes back to `oat-project-implement`, and `oat project complete-state` refuses the same state. There is no override; see the [CLI reference](../../reference/cli-reference.md).
 
 ### Project-recap gate (non-lite)
 

package/assets/docs/workflows/projects/meta.json

@@ -0,0 +1,25 @@
+{
+  "title": "Workflow & Projects",
+  "pages": [
+    "lifecycle",
+    "retro",
+    "autonomy",
+    "cursor-cloud",
+    "design-modes",
+    "hill-checkpoints",
+    "dispatch-ceiling",
+    "orchestration-model",
+    "review-flavors",
+    "evidence-layers",
+    "programmatic-execution",
+    "artifacts",
+    "implementation-execution",
+    "reviewing-oat-prs",
+    "picking-up-projects",
+    "splitting",
+    "state-machine",
+    "reviews",
+    "pr-flow",
+    "repo-analysis"
+  ]
+}

package/assets/docs/workflows/projects/orchestration-model.md

@@ -76,14 +76,14 @@ sequenceDiagram
   participant Root as Project root
   participant Adapter as Project adapter
   participant Engine as Dispatch engine
-  participant Journal as Project dispatch journal
+  participant Record as Run record in implementation.md
   participant Phase as Phase implementer
 
   Root->>Adapter: Phase + lifecycle authority
   Adapter->>Engine: Provider-neutral dispatch request
   Engine-->>Root: Exact route + request ID
   Root->>Phase: Phase Scope
-  Root->>Journal: Accepted or blocked-before-start record
+  Root->>Record: Accepted or blocked-before-start result
   Phase-->>Root: Phase report + commits
 ```
 
@@ -125,10 +125,9 @@ launch.
 The launcher constructs and redacts the complete generic record plus the
 namespaced OAT role event before it calls the native host. When the host
 returns, the calling workflow writes the accepted or `blocked-before-start`
-state into its run record in `implementation.md`. Persisting a per-dispatch
-file with `oat project dispatch record` is optional and off by default; the
-command is a recorder only and never launches a provider or changes selection
-authority.
+state into its run record in `implementation.md`, the only launch record.
+`oat project dispatch record` validates a record and writes nothing; it never
+launches a provider or changes selection authority.
 
 An accepted handle owns the scope and closes replacement. One fresh fallback
 record is legal only when the native wrapper proves no child started, links the

package/assets/docs/workflows/skills/meta.json

@@ -0,0 +1,10 @@
+{
+  "title": "Skills",
+  "pages": [
+    "[Writing Skills](/contributing/skills)",
+    "[Docs Workflows](/docs-tooling/workflows)",
+    "explainer-kit",
+    "repo-improve",
+    "recon"
+  ]
+}

package/assets/docs/workflows/skills/recon.md

@@ -275,6 +275,12 @@ them. Adversarial reviewers receive the declared scope, questions, and
 provisional statements. Neither pass receives gatherer reasoning, synthesis
 prose, dossier paths, or earlier review conclusions.
 
+Review briefs come only from the production brief generator. The packet
+validator rebuilds every brief from the prior claim ledger and manifest with
+that same generator and rejects any difference with `REVIEW_BRIEF_MISMATCH`, so
+a brief carrying an injected claim, note, or source fails publication. A
+review's dispositions must also be unique members of its brief's claims.
+
 Each lane receives one explicit authority envelope and one unique output path.
 Its enforcement is recorded as:
 
@@ -293,8 +299,17 @@ operation.
 A structurally valid run can publish an honest `partial` packet. The manifest
 and `packet.md` then identify the requested and achieved profiles, failed or
 omitted passes, material gaps, affected claims, and required assurance
-downgrades. A run may be partial even when it achieved the requested profile if
-a material evidence gap remains. The achieved profile is derived from the
+downgrades. Every claim a review kept below `verified` (an unresolved issue
+scoped to it or global to its review, a coverage finding that names it, or a
+non-affirming disposition) is listed under Review Downgrades with the review's
+own text, even when it is not a key claim, so a `complete` packet cannot hide a
+downgraded claim. A claim that a required review left without a disposition stays
+`unresolved` and is listed there as not reviewed. A review's
+`unresolvedIssues` entry may name the claim IDs it affects or apply to the
+whole review; a legacy plain-string entry is read as review-wide. A material
+coverage gap does not fail publication by itself: the claims it affects stay
+below `verified` and the run publishes as an honest `partial`. A run may be partial even when it achieved the requested
+profile if a material evidence gap remains. The achieved profile is derived from the
 complete typed artifacts in the packet; each required pass without a complete
 result needs a material `PASS_FAILED` or `PASS_OMITTED` gap. Each approved lane
 must likewise have a complete artifact or a material outcome gap carrying its
@@ -310,7 +325,17 @@ honest `partial` packet at that achieved profile.
 
 Status updates and the final handoff label each failure as `worker`,
 `provider/dispatch`, `contract validation`, or `source availability`, and
-say whether every accepted lane reached a terminal result. Workers that
+say whether every accepted lane reached a terminal result.
+
+A launch the provider rejects before any child is accepted, such as a Codex
+agent-limit rejection, is a `provider/dispatch` failure, never a worker
+failure, and every accepted artifact is kept. The approved `retryLimit` counts
+these pre-acceptance admission retries per lane, and the controller makes at
+most one per lane, so the approval preview's worst case is two attempts per
+lane. The default of 0 allows none. If admission still fails, recon uses an
+alternate route only when it was already approved; otherwise it stops with a
+partial run and asks for a continuation amendment. An accepted lane is never
+rerun to free capacity. Workers that
 completed are never reported as failed because the controller could not
 publish.
 

package/assets/public-package-versions.json

@@ -1,6 +1,6 @@
 {
-  "cli": "0.3.10",
-  "docs-config": "0.3.10",
-  "docs-theme": "0.3.10",
-  "docs-transforms": "0.3.10"
+  "cli": "0.3.11",
+  "docs-config": "0.3.11",
+  "docs-theme": "0.3.11",
+  "docs-transforms": "0.3.11"
 }

package/assets/skills/oat-cursor-cloud-projects/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: false
 user-invocable: true
 allowed-tools: Read, Write, Bash, Glob, Grep
 metadata:
-  version: 1.1.2
+  version: 1.1.3
 ---
 
 # OAT in Cursor Cloud
@@ -183,7 +183,7 @@ commands from the target repository or pass their supported project path.
 
 ### Step 3: Resolve Assets with User Scope First
 
-Apply one source order independently to every asset file:
+Apply one source order independently to every skill and script file:
 
 1. user scope;
 2. target-repository scope when the user asset is absent;
@@ -191,18 +191,30 @@ Apply one source order independently to every asset file:
 
 User locations:
 
-| Asset    | User source                 |
-| -------- | --------------------------- |
-| Skill    | `~/.agents/skills/<skill>/` |
-| Template | `~/.oat/templates/<file>`   |
-| Script   | `~/.oat/scripts/<file>`     |
+| Asset  | User source                 |
+| ------ | --------------------------- |
+| Skill  | `~/.agents/skills/<skill>/` |
+| Script | `~/.oat/scripts/<file>`     |
 
-Repository locations are `.agents/skills/`, `.oat/templates/`, and
-`.oat/scripts/` within the target repository.
+Repository locations are `.agents/skills/` and `.oat/scripts/` within the
+target repository.
 
-The user tier is provisioned from `@latest` at environment boot and is the
-canonical execution tier. Repository copies in this fleet are not customized;
-a difference indicates staleness, not a local override.
+For skills and scripts, the user tier is provisioned from `@latest` at
+environment boot and is the canonical execution tier. Repository copies of
+skills and scripts in this fleet are not customized; a difference indicates
+staleness, not a local override.
+
+Templates are the exception. They resolve repository, then user, then bundled,
+the same order every lifecycle skill uses, because a repository template is an
+owner override. Resolve them only through the CLI, run from the target
+repository:
+
+```bash
+oat template resolve <name> --json                      # report the tier
+oat template resolve <name> --output "<destination>"    # copy the template
+```
+
+Do not read `~/.oat/templates/` directly or choose a template tier by hand.
 
 #### Absolute-path loading contract
 
@@ -213,7 +225,6 @@ Therefore, resolve and read the selected user asset by absolute path as the
 
 ```bash
 USER_SKILLS_ROOT="${HOME}/.agents/skills"
-USER_TEMPLATES_ROOT="${HOME}/.oat/templates"
 USER_SCRIPTS_ROOT="${HOME}/.oat/scripts"
 ```
 
@@ -238,8 +249,9 @@ It never chooses the source:
 - if freshness is safety-critical, refresh and re-verify before continuing;
   stop if the user tier cannot be refreshed safely.
 
-Never silently switch to the repo copy. Apply per-file precedence to templates
-and scripts without using skill semver as their arbitration mechanism.
+Never silently switch to the repo copy. Apply per-file precedence to scripts
+without using skill semver as their arbitration mechanism; templates follow
+`oat template resolve`.
 
 ### Step 4: Load Cursor Dispatch Context When Needed
 
@@ -328,7 +340,9 @@ separate dispatch surface and snapshot its current catalog. See
 - ✅ `oat` was verified before project artifact work.
 - ✅ The project home is anchored inside the target repository in both single-
   and multi-repo environments.
-- ✅ Existing user assets won independently for skills, templates, and scripts.
+- ✅ Existing user assets won independently for skills and scripts.
+- ✅ Templates were resolved through `oat template resolve` (repository, user,
+  then bundled).
 - ✅ Skill version comparison verified freshness without changing source.
 - ✅ User assets were read by absolute path as the primary mechanism.
 - ✅ Cursor dispatch mechanics remained delegated to the canonical provider

package/assets/skills/oat-dispatch-subagents/SKILL.md

@@ -5,7 +5,7 @@ disable-model-invocation: true
 user-invocable: false
 allowed-tools: Read
 metadata:
-  version: 1.2.11
+  version: 1.2.12
 ---
 
 # Dispatching OAT Subagents
@@ -176,17 +176,9 @@ terminal outcome, not a pre-start rejection, and must be recorded through
 `provesNoChildStarted: true`, and no fallback is authorized.
 
 The calling workflow records each launch in its own run record (request ID,
-`Dispatch:` stamp, launch status, terminal outcome). Writing a per-dispatch file with `oat project dispatch record` is optional and off by default: no lifecycle skill or command consumes those files, so do not write them unless the host has explicitly opted in. A host that has opted
-in passes the validated record and event on standard input:
-
-```bash
-oat project dispatch record \
-  --project "$PROJECT_PATH" \
-  --event-file - \
-  --json
-```
-
-The command validates and persists evidence only. It never launches a provider.
+`Dispatch:` stamp, launch status, terminal outcome); that run record is the
+only launch record. `oat project dispatch record --event-file - --json`
+validates a record and event and writes nothing. It never launches a provider.
 
 ## Capability and Authorization
 

package/assets/skills/oat-dispatch-subagents/references/managed-claude-example.json

@@ -1,5 +1,5 @@
 {
-  "description": "Managed Claude validation-only inputs for `oat project dispatch record --event-file <file> --json` (no --project). Each role key is one complete input. claudeLaunch.resolution is `oat project dispatch-ceiling resolve --provider claude --role <role> --json` output verbatim; claudeLaunch.definition is the generated Claude agent file content; claudeLaunch.payload is the exact launch payload; event is `oat project dispatch canonical-role --json` output. Built from fixture agents, so the definition body, role version, and content digest are illustrative. See record-schema.md, Managed Claude Validation Input.",
+  "description": "Managed Claude validation-only inputs for `oat project dispatch record --event-file <file> --json`. Each role key is one complete input. claudeLaunch.resolution is `oat project dispatch-ceiling resolve --provider claude --role <role> --json` output verbatim; claudeLaunch.definition is the generated Claude agent file content; claudeLaunch.payload is the exact launch payload; event is `oat project dispatch canonical-role --json` output. Built from fixture agents, so the definition body, role version, and content digest are illustrative. See record-schema.md, Managed Claude Validation Input.",
   "implementer": {
     "claudeLaunch": {
       "resolution": {

package/assets/skills/oat-dispatch-subagents/references/provider-codex.md

@@ -110,3 +110,54 @@ Add a service tier or reasoning mode only through controls shown by the current
 CLI/schema. Honor the caller's authorization boundary. Record every selector
 as configured invocation evidence; do not infer runtime identity from process
 success alone.
+
+## Agent-Limit Rejections and v2 Residency
+
+A native spawn rejected with `agent thread limit reached`
+(`AgentLimitReached`) before any child is accepted is a pre-start
+provider/dispatch outcome, not a worker failure, and not by itself evidence of
+cumulative or lifetime thread exhaustion. The v2 lifecycle facts below are
+cited from the openai/codex `rust-v0.159.2` tag; re-check them when the
+installed Codex version changes.
+
+- Before returning `AgentLimitReached`, v2 admission tries to unload an eligible
+  resident. A resident is eligible only when it is completed, errored, or
+  interrupted, has no active turn, has no pending mailbox items, and holds no
+  residency lock
+  ([`residency.rs` L99-L120](https://github.com/openai/codex/blob/rust-v0.159.2/codex-rs/core/src/agent/control/residency.rs#L99-L120),
+  [eligibility L266-L272](https://github.com/openai/codex/blob/rust-v0.159.2/codex-rs/core/src/agent/control/residency.rs#L266-L272)).
+  A visible completed status does not prove eligibility: status does not
+  expose mailbox state, active-turn cleanup, or residency locks.
+- The v2 toolset exposes `interrupt_agent`, which interrupts work but does not
+  unregister the agent. Older toolsets expose `close_agent`
+  ([`spec_plan.rs`](https://github.com/openai/codex/blob/rust-v0.159.2/codex-rs/core/src/tools/spec_plan.rs)).
+  Never present `interrupt_agent` as a close or release.
+- A queue-only message to a completed v2 agent can pin it by leaving a pending
+  mailbox item
+  ([openai/codex#32353](https://github.com/openai/codex/issues/32353)). Do not
+  message completed agents to clean them up.
+- Reports of completed residents blocking replacement are nondeterministic
+  ([openai/codex#44351](https://github.com/openai/codex/issues/44351)), and
+  older open-thread quota behavior
+  ([openai/codex#22779](https://github.com/openai/codex/issues/22779)) is a
+  different mechanism. Do not conflate either with v2 residency eviction.
+
+On a pre-acceptance agent-limit rejection:
+
+1. Keep every accepted artifact and record the exact rejection as a
+   provider/dispatch outcome.
+2. Inspect the available lifecycle tools and statuses. Release only completed
+   agents whose output is already retained, and only through a close or release
+   tool the live toolset supports; never close the root or an active required
+   lane.
+3. Do not archive or delete sessions to free capacity. Archive availability
+   does not prove that it releases a v2 residency slot.
+4. Make at most one admission retry, only when the caller's approved dispatch
+   envelope allows retries and after the eligibility check above. A wait result
+   or a completed status alone does not justify another attempt.
+5. If admission still fails, use an alternate route only when the caller
+   already approved it; otherwise stop and return the partial result for a
+   concrete continuation amendment.
+
+No retry or route changes model, effort, role behavior, data authority, output
+limits, or reviewer blindness. Never rerun an accepted lane to free capacity.

package/assets/skills/oat-dispatch-subagents/references/record-schema.md

@@ -212,7 +212,7 @@ selection source.
 
 Before every managed, effort-pinned Claude implementer or reviewer launch,
 `oat-project-implement` runs `oat project dispatch record --event-file <file>
---json` without `--project` and requires `status: validated-only`. That input
+--json` and requires `status: validated-only`. That input
 replaces `record` with three top-level keys:
 
 - `claudeLaunch`, an object with three keys of its own:
@@ -361,10 +361,10 @@ be traded against another:
   strings; and
 - at most 16 KiB serialized per field.
 
-The whole record is additionally capped at 64 KiB, measured as the **published**
-bytes — the pretty-printed JSON plus trailing newline that is actually written
-to the journal, not compact `JSON.stringify` output. The two differ by roughly a
-tenth on a nested record, so size against the published form. Per-field
+The whole record is additionally capped at 64 KiB, measured as the **serialized**
+document — the pretty-printed JSON plus trailing newline, not compact
+`JSON.stringify` output. The two differ by roughly a tenth on a nested record,
+so size against the serialized form. Per-field
 projection limits above remain compact measurements, because they bound the
 shape of a field rather than the size of a file. A realistically rich record
 measures a few kilobytes, so these limits bind prompt bodies, transcripts, and
@@ -376,8 +376,9 @@ cannot fully account for is treated as sensitive rather than classified on a
 partial token. Store references, identifiers, and digests; never role content, message bodies,
 or credentials.
 
-Absolute filesystem paths are handled by field class, because the journal is
-committed and a home path in it is permanent:
+Absolute filesystem paths are handled by field class, because the validated
+record is printed verbatim and a caller may copy it into a committed artifact,
+where a home path is permanent:
 
 - **Identity and control fields reject them.** `caller`, `scope`, every
   selector, `selected_route`, the `guidance_*` fields, `authority`,

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

@@ -3,9 +3,9 @@ name: oat-docs-analyze
 description: Run when you need to evaluate documentation structure, navigation, and coverage against the OAT docs app contract. Produces a severity-rated analysis artifact for oat-docs-apply.
 disable-model-invocation: true
 user-invocable: true
-allowed-tools: Read, Write, Bash(git:*), Glob, Grep, AskUserQuestion, Task
+allowed-tools: Read, Write, Bash(git:*), Bash(oat docs nav sync --check:*), Glob, Grep, AskUserQuestion, Task
 metadata:
-  version: 1.5.2
+  version: 1.6.0
 ---
 
 # Docs Analysis
@@ -386,6 +386,31 @@ If a generated root index or manifest exists:
    files, and representative links for each finding.
 5. Prefer source-of-truth fixes over generated-file edits.
 
+If the app is Fumadocs (a `source.config.ts` beside `docs/`), its sidebar comes from
+`docs/**/meta.json` files that `oat docs nav sync` generates from `## Contents`:
+
+1. Flag a docs directory with an `index.md` but no `meta.json` as a missing
+   generated artifact.
+2. Flag a `meta.json` whose `pages` order or entries differ from that directory's
+   `## Contents` (immediate pages and child folders by name, `index` first in the
+   docs root and in any `root: true` folder, other targets as `[Title](url)` link
+   entries) as stale; the fix is to rerun `oat docs nav sync`.
+3. Flag a `"..."` or `"z...a"` rest entry as a hand edit; nav sync output is strict.
+4. Flag pages that no `## Contents` map lists: under strict `meta.json` they are
+   hidden from the sidebar. Recommend listing them, not adding a rest entry.
+5. During analysis, run only the read-only check, with `--check` first and
+   `--target-dir` set to the resolved docs app directory (the directory that
+   holds `source.config.ts` and `docs/`, such as `apps/oat-docs`, not its `docs/`
+   content root):
+
+   ```bash
+   oat docs nav sync --check --target-dir <docs-app-dir>
+   ```
+
+   It writes nothing, names stale `meta.json` files and unlisted pages, and exits
+   1 when either exists. The skill grants only this `--check` form; plain
+   `oat docs nav sync` writes files and is not part of analysis.
+
 If `mkdocs.yml` exists:
 
 1. Compare nav entries with the docs tree.
@@ -394,7 +419,7 @@ If `mkdocs.yml` exists:
 4. Flag directories whose `index.md` `## Contents` section appears inconsistent with nav structure.
 5. Flag docs guidance that claims structure, plugin support, or workflow rules not backed by current repo evidence.
 
-If no `mkdocs.yml` exists, record whether the repo should be migrated to an OAT docs app.
+If neither `mkdocs.yml` nor a Fumadocs app exists, record whether the repo should be migrated to an OAT docs app.
 
 ### Step 7: Severity-Rate Findings
 

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:*), Glob, Grep, AskUserQuestion
 metadata:
-  version: 1.3.1
+  version: 1.3.2
 ---
 
 # Docs Apply
@@ -34,7 +34,7 @@ Generate or update documentation files from a docs analysis artifact, with expli
 **ALLOWED Activities:**
 
 - Reading analysis artifacts and the current docs surface.
-- Creating or updating docs files and `mkdocs.yml` when approved.
+- Creating or updating docs files and `mkdocs.yml` when approved. Fumadocs `meta.json` files change only through `oat docs nav sync`.
 - Running `oat docs nav sync` after approved structural changes.
 - Creating branches, commits, and optional PRs.
 
@@ -203,7 +203,7 @@ For each approved recommendation:
 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.
+- 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`.
 
 Negative rules:
 

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

@@ -6,7 +6,7 @@ disable-model-invocation: false
 allowed-tools: Read, Write, Bash, Glob, Grep, AskUserQuestion
 user-invocable: true
 metadata:
-  version: 1.0.1
+  version: 1.0.2
 ---
 
 # OAT Docs Authoring

package/assets/skills/oat-docs-authoring/references/oat-fumadocs-contract.md

@@ -60,8 +60,11 @@ authored docs tree. Treat it as generated output.
 - Asset-only directories do not need `index.md` unless local guidance says so.
 - Build output, hidden tool directories, and generated artifacts are not content
   directories.
-- Optional Fumadocs metadata files, such as `meta.json`, may refine sidebar
-  presentation when local style uses them. They do not replace `## Contents`.
+- Fumadocs `meta.json` files are generated by `oat docs nav sync` from each
+  directory's `## Contents`, not hand-authored. After structural changes, rerun
+  nav sync and commit the result; it never adds a `"..."` rest entry, so list a
+  page in `## Contents` to show it in the sidebar. Keys nav sync does not own,
+  such as `icon` or `defaultOpen`, may be added by hand and are preserved.
 - Preserve local audience routers, ownership notes, and app-shell
   customizations.
 

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.2.1
+  version: 1.2.2
 ---
 
 # Docs Bootstrap
@@ -930,10 +930,11 @@ 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 Fumadocs sidebar navigation** in `<appRoot>/docs/**/meta.json`. `oat docs nav sync` writes one per docs directory from that directory's `## Contents` order, and the files are committed. Navigation is strict: a page no `## Contents` map lists stays out of the sidebar and the command reports it, so the fix is to list the page, never to edit `meta.json` by hand.
 - **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 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."
+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 — and regenerate `meta.json` with `oat docs nav sync` instead of editing it. In MkDocs, treat `mkdocs.yml` `nav:` as derived from authored Contents unless the local workflow says otherwise."
 
 #### Section C (both frameworks) — The `## Contents` contract
 
@@ -944,7 +945,7 @@ 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 `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, it remains the authored navigation intent that agents maintain and compare 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.
+- **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`.
 
 Show the user their own `docs/index.md` `## Contents` as a concrete example (read the file and paste the relevant 5–15 lines). If `patchesApplied` includes an `FP-16` entry with `status: 'applied'`, mention it — the skill rewrote the scaffold's extension-less links to `.md`-suffixed form so agents can follow them. 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."

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

@@ -12,13 +12,13 @@ This file tells agents how to work inside `{{APP_DIR}}`, the documentation app f
 2. Add frontmatter with at minimum `title:` and `description:`. The title drives nav display and page `<title>`; the description drives search previews, social cards, and sibling summaries. Empty descriptions hurt all three.
 3. Update the nearest `index.md`'s `## Contents` section to include a link to the new page. Use `.md`-suffixed relative links: `[Title](page.md)` for leaf pages, `[Section](subdir/index.md)` for subdirectories. The `@open-agent-toolkit/docs-transforms` remark-links plugin normalizes these for Fumadocs routing at build time (strips `.md`, collapses `dir/index.md` → `dir`), so the suffixed form renders correctly **and** lets agents follow links to the target file without path inference. The `## Contents` section is the machine-readable local map — anything not listed there is effectively invisible to the navigation tooling.
 4. If the new page introduces a new subdirectory, create an `index.md` in that subdirectory with its own `## Contents` section. Every content directory must have an `index.md`.
-5. Regenerate the derived navigation artifact for this framework. For Fumadocs, run the generated-index command (`{{GENERATE_INDEX_CMD}}`) so the app-root `index.md` manifest reflects the current Markdown file tree. For MkDocs, run `oat docs nav sync` or the local equivalent so `mkdocs.yml` `nav:` reflects authored `## Contents`. Derived artifacts never replace the authored `## Contents`; keep authored maps current and compare generated output against them when checking freshness.
+5. Regenerate the derived navigation artifacts for this framework. For Fumadocs, run `oat docs nav sync` (from the app directory, or with `--target-dir <app-dir>`) so the committed `docs/**/meta.json` sidebar files follow authored `## Contents`, and run the generated-index command (`{{GENERATE_INDEX_CMD}}`) so the app-root `index.md` manifest reflects the current Markdown file tree. Fumadocs nav sync is strict: a page no `## Contents` map lists stays out of the sidebar and is reported, so list the new page rather than editing `meta.json`. For MkDocs, run `oat docs nav sync` or the local equivalent so `mkdocs.yml` `nav:` reflects authored `## Contents`. Derived artifacts never replace the authored `## Contents`; keep authored maps current and compare generated output against them when checking freshness.
 
 ## When you need to restructure navigation
 
 1. Make changes in the authored `## Contents` sections of each affected `index.md`. That is the authoritative local map.
-2. Do **not** hand-edit generated navigation artifacts. The Fumadocs app-root `index.md` manifest, `mkdocs.yml` `nav:` (for MkDocs), and any other derived nav file is rewritten by the local generation workflow.
-3. After editing `## Contents`, run the framework's generation command to refresh derived artifacts.
+2. Do **not** hand-edit generated navigation artifacts. The Fumadocs app-root `index.md` manifest, Fumadocs `meta.json` files, `mkdocs.yml` `nav:` (for MkDocs), and any other derived nav file is rewritten by the local generation workflow.
+3. After editing `## Contents`, run `oat docs nav sync` and the framework's generation command to refresh derived artifacts.
 4. If you're moving pages between directories, update both source and destination `index.md` `## Contents` entries in the same commit so the site isn't broken mid-way through history.
 5. If you're reparenting an entire subtree, consider whether the moved directory's own `index.md` needs a revised "scope" paragraph.