@open-agent-toolkit/cli 0.3.9 → 0.3.11

package/README.md

@@ -62,7 +62,8 @@ Use these commands when you want structured runtime/project state out of the CLI
 - `oat config dump --json` - emit merged OAT config with per-key source attribution
 - `oat project status --json` - emit the active project's full parsed control-plane state
 - `oat project list --json` - emit summary state for tracked projects under the configured projects root
-- `oat project complete-state <project-path>` - emit the canonical completed lifecycle shape into a tracked project's `state.md`
+- `oat project closeout-check <project-path> --json` - report whether a configured, autonomous, or lite closeout's `oat_post_implement_sequence` snapshot permits terminal completion, and which step or approval owns it next (read-only)
+- `oat project complete-state <project-path>` - emit the canonical completed lifecycle shape into a tracked project's `state.md`; refuses the same incomplete closeout `closeout-check` reports
 
 ## Requirements
 

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.3.9"
+  "oatVersion": "0.3.11"
 }

package/assets/config/dispatch-matrix-recommendation.json

@@ -1,5 +1,5 @@
 {
-  "version": "2026-09-25.1",
+  "version": "2026-10-01.1",
   "providers": {
     "codex": {
       "economy": {
@@ -39,17 +39,17 @@
         "candidates": [
           {
             "harness": "codex",
-            "model": "gpt-6-sol",
+            "model": "gpt-6.1-sol",
             "effort": "low"
           },
           {
             "harness": "codex",
-            "model": "gpt-6-sol",
+            "model": "gpt-6.1-sol",
             "effort": "medium"
           },
           {
             "harness": "codex",
-            "model": "gpt-6-sol",
+            "model": "gpt-6.1-sol",
             "effort": "high"
           }
         ]
@@ -58,7 +58,7 @@
         "candidates": [
           {
             "harness": "codex",
-            "model": "gpt-6-sol",
+            "model": "gpt-6.1-sol",
             "effort": "xhigh"
           },
           {
@@ -80,7 +80,7 @@
           "haiku",
           {
             "harness": "claude",
-            "model": "claude-sonnet-5",
+            "model": "claude-sonnet-5-5",
             "effort": "medium"
           }
         ]

package/assets/docs/cli-utilities/configuration.md

@@ -497,11 +497,11 @@ The example above is illustrative rather than a copy of the bundled ladder; its
 tiers are trimmed for readability.
 
 The bundled recommendation covers 11 Codex model/effort combinations: GPT-6
-Luna at `low` through `max`, GPT-6 Sol at `low` through `high` plus `xhigh`,
+Luna at `low` through `max`, GPT-6.1 Sol at `low` through `high` plus `xhigh`,
 and GPT-6 Astra at `high` and `xhigh`.
 Claude covers `haiku`, plus explicit Sonnet, Opus, and Fable
 model/effort pairs. Effort-pinned Claude cells require a recognized versioned
-model ID (`fable-5-1`, `fable-5`, `opus-5-5`, `sonnet-5`,
+model ID (`fable-5-1`, `fable-5`, `opus-5-5`, `sonnet-5-5`, `sonnet-5`,
 `opus-4-7`, `opus-4-6`, or `sonnet-4-6`) or a matching
 `ANTHROPIC_DEFAULT_<FAMILY>_MODEL` pin. A custom provider pin must declare
 matching capability through `<PIN>_SUPPORTED_CAPABILITIES`: `effort` enables
@@ -513,14 +513,17 @@ Model-only Claude aliases remain compatible through the per-call model argument
 and report `effortAxis: not-applicable` because the Agent API exposes no
 per-call effort argument. The recommendation carries 16 Cursor candidates
 across four tiers, drawn from a materialization
-catalogue with 26 catalogued multi-family flat IDs spanning Composer, Claude
-(Sonnet, Opus 5.5, Fable 5, and Fable 5.1), GPT, and Grok 4.5 and 4.6; the two figures differ because some
+catalogue with 31 catalogued multi-family flat IDs spanning Composer, Claude
+(Sonnet 5, Sonnet 5.5, Opus 5.5, Fable 5, and Fable 5.1), GPT, and Grok 4.5 and 4.6; the two figures differ because some
 approved mappings stay materializable without being recommended. An explicit
-mapping connects each flat ladder ID to a separate bracket-form frontmatter
-model; configuration and skills never derive or normalize either form.
+mapping connects each flat ladder ID to its verified frontmatter model.
+Existing mappings keep their bracket selectors; Sonnet 5.5 uses per-pin
+verified exact IDs. The 31 mappings produce 62 pinned role variants.
+Configuration and skills never derive selectors or admit arbitrary flat IDs.
 
 The corresponding pinned Codex variant catalogue includes
-`gpt-5.6-luna-high`, `gpt-5.6-terra-xhigh`, `gpt-5.6-sol-high`, and
+`gpt-6-1-sol-high` and `gpt-6-1-sol-max`, alongside compatible older targets
+such as `gpt-5.6-luna-high`, `gpt-5.6-terra-xhigh`, `gpt-5.6-sol-high`, and
 `gpt-5.6-sol-max`. Configuration selects from that materialized catalogue; it
 does not construct an unregistered role during dispatch.
 
@@ -664,7 +667,8 @@ the exact registered role, pinned child, or resolver-returned model argument.
 
 `oat doctor` compares configured Cursor flat IDs with the current Cursor
 catalogue and reports availability drift. This check is diagnostic: catalogue
-presence does not prove that a bracket-form definition pin was honored.
+presence does not prove that a definition pin was honored, whether its
+selector is bracket-form or an approved exact ID.
 
 Each shipped mapping has mapping-specific native-launch evidence, but Cursor
 can silently fallback when account, plan, or administration constraints prevent

package/assets/docs/cli-utilities/meta.json

@@ -0,0 +1,13 @@
+{
+  "title": "CLI Utilities",
+  "pages": [
+    "bootstrap",
+    "tool-packs",
+    "configuration",
+    "remote-project-management",
+    "config-and-local-state",
+    "project-log",
+    "backlog-lifecycle",
+    "workflow-gates"
+  ]
+}

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

@@ -528,14 +528,20 @@ repository that adopted PJM with a user-scope pack is diagnosed correctly.
 
 ### Template precedence
 
-PJM templates resolve through three tiers, first match wins:
+Project lifecycle and PJM templates resolve through three tiers, first match
+wins (idea templates instead follow the ideas scope the ideas skills select):
 
 1. **Repository** — `.oat/templates/<name>` in this repo. An existing repository
    template is an owner override and is never rewritten by pack updates.
 2. **User** — `~/.oat/templates/<name>`, the managed default that
-   `oat tools update --pack project-management --scope user` keeps current.
+   `oat tools update --pack <pack> --scope user` keeps current (`workflows`
+   for project lifecycle templates, `project-management` for PJM templates).
 3. **Bundle** — the templates shipped inside the installed CLI.
 
+`oat template resolve <name>` reports which tier wins, and lifecycle skills
+copy their templates with `oat template resolve <name> --output <path>`, so a
+user-scope-only install needs no repository `.oat/templates/` directory.
+
 Delete a repository template to fall back to the managed user default. If a
 template is missing from all three tiers, the command errors rather than
 inventing content.

package/assets/docs/cli-utilities/workflow-gates.md

@@ -194,6 +194,19 @@ bookkeeping. Implementation, test, skill, template, workflow configuration, or
 unknown changed paths make the result stale and require a current final review
 and a new gate generation.
 
+An operator can waive specific stale-making descendants, such as a test-only
+fix, instead of rerunning the gate. The waiver is an append-only entry in
+`oat_implement_exit_gate.waivers` recording who waived, the reason, the covered
+commit range, the effective-delta fingerprint at the range end, and a UTC
+timestamp; it never rewrites earlier provenance. Waivers are operator-only:
+agents never infer or self-issue one, and an `OAT_AUTONOMOUS=1` run refuses to
+write one. A later substantive change after the covered range makes the
+generation stale again, and a malformed waiver fails closed. An interactive
+implement run offers the waiver before it persists `stale`; an operator can
+also give it when resuming implementation after `oat-project-next` reports
+stale state. See
+[Implementation Execution](../workflows/projects/implementation-execution.md).
+
 Only an artifact with `oat_review_invocation: gate` and the matching
 `oat_gate_run_id` can satisfy configured-gate provenance. A normal final
 review, phase review, or manually produced independent review cannot substitute
@@ -241,7 +254,7 @@ line. The reviewer's resolver stamp describes the project reviewer policy, so
 gate-originated artifacts label it as the policy view:
 
 ```markdown
-**Dispatch audit (policy view):** `Dispatch: scope=p01 action=review role=reviewer ... target=oat-reviewer-gpt-6-sol-high`
+**Dispatch audit (policy view):** `Dispatch: scope=p01 action=review role=reviewer ... target=oat-reviewer-gpt-6-1-sol-high`
 ```
 
 The gate reads reviewer stamps (`action=review role=reviewer`) from audit lines

package/assets/docs/contributing/code.md

@@ -70,8 +70,14 @@ local `origin/main` tracking ref (falling back to a local `main` branch when no
 release fails locally the same way it fails in CI. Fetch first (`git fetch
 origin`) so that ref is current; a
 checkout with neither `origin/main` nor `main` skips the whole gate (CI uses
-`fetch-depth: 0`). Test files under `packages/cli/src/` count as publishable
-changes for this gate.
+`fetch-depth: 0`). Test-only changes do not require the bump
+(`DR-260927-test-only-paths-skip`): each public package's
+`versionPolicyIgnorePatterns` in
+`packages/cli/src/release/public-package-contract.ts` lists exactly the test
+paths its `tsconfig.json` leaves out of `dist` (for `packages/cli`,
+`src/**/*.test.ts` and `src/**/__tests__/**`), and a contract test fails if
+the two diverge. A test helper or fixture that compiles into `dist` still
+counts as a publishable change.
 
 CI runs neither `pnpm lint` nor `pnpm format`. `pnpm check` covers the
 formatting of `.agents/skills/**`, `apps/oat-docs/docs`, and `tools/smoke`

package/assets/docs/contributing/documentation.md

@@ -62,7 +62,13 @@ Documentation should ship with the code it explains. This page covers the core d
   pnpm -w run cli:source -- docs generate-index --docs-dir apps/oat-docs/docs --output apps/oat-docs/index.md
   ```
 
-- In MkDocs apps, use `oat docs nav sync` to refresh `mkdocs.yml` instead. Do not use MkDocs nav sync as the Fumadocs regeneration step.
+- Then refresh the sidebar navigation. `oat docs nav sync` rewrites the committed `meta.json` files from the `## Contents` maps and reports any page no map lists; list the page in its directory's `## Contents` rather than editing `meta.json`. The build runs the read-only `--check` form and fails while the navigation is stale or a page is unlisted:
+
+  ```bash
+  pnpm -w run cli:source -- docs nav sync --target-dir apps/oat-docs
+  ```
+
+- In MkDocs apps, the same `oat docs nav sync` command refreshes the `nav:` block in `mkdocs.yml` instead.
 - Use [Markdown Features](markdown-features.md) for supported syntax and examples.
 
 ## Agent guidance

package/assets/docs/contributing/meta.json

@@ -0,0 +1,15 @@
+{
+  "title": "Contributing",
+  "pages": [
+    "code",
+    "documentation",
+    "markdown-features",
+    "skills",
+    "design-principles",
+    "commit-conventions",
+    "hooks-and-safety",
+    "smoke-testing",
+    "updating-model-guidance",
+    "verifying-cursor-pins"
+  ]
+}

package/assets/docs/contributing/updating-model-guidance.md

@@ -26,7 +26,9 @@ they choose to adopt a newer recommendation.
 
 A model can remain supported for a user's explicit configuration without being
 recommended by the new ladder. For example, this refresh keeps GPT-5.6 Codex
-and Cursor targets available while preferring GPT-6 in Codex. Claude Opus 4.8
+and Cursor targets available while preferring GPT-6.1 Sol and GPT-6 Luna in
+Codex. GPT-6 Sol remains supported for explicit compatibility configurations.
+Claude Opus 4.8
 and 5.0 have left current supported generations and recommendations; historical
 probe records can still describe past behavior, clearly labeled as historical.
 
@@ -34,7 +36,11 @@ probe records can still describe past behavior, clearly labeled as historical.
 
 Check the provider's official model documentation and the local runtime before
 editing an ID or effort range. The [OpenAI model catalog](https://developers.openai.com/api/docs/models)
-lists GPT-6 Astra, Sol, and Luna. The
+lists GPT-6.1 Sol and GPT-6 Astra, Sol, and Luna. The
+[GPT-6.1 Sol model page](https://developers.openai.com/api/docs/models/gpt-6.1-sol)
+identifies `gpt-6.1-sol` and supports `low`, `medium`, `high`, `xhigh`, and
+`max`; `none` and `minimal` are not supported efforts for this family. Direct
+API tool calls require the Responses API. The
 [Astra model page](https://developers.openai.com/api/docs/models/gpt-6-astra)
 names `gpt-6-astra` and documents `low`, `medium`, `high`, `xhigh`, and `max`;
 compare it with the installed Codex runtime model cache for the exact names and
@@ -42,7 +48,11 @@ local effort set. Catalog presence establishes support, not relative task
 quality. The
 [Anthropic Opus 5.5 documentation](https://www.anthropic.com/claude-opus-5-5)
 names `claude-opus-5-5`; confirm a Claude Code invocation reports that exact
-assistant model before admitting it to the Claude catalog. Claude subagent
+assistant model before admitting it to the Claude catalog. The
+[Sonnet 5.5 overview](https://platform.claude.com/docs/en/models/sonnet-5-5/overview)
+and [effort reference](https://platform.claude.com/docs/en/build-with-claude/effort)
+identify `claude-sonnet-5-5` and its five low-through-max efforts. Verify
+Claude Code identity separately. Claude subagent
 `model` and `effort` frontmatter select a per-agent route; see the
 [Claude Code subagent fields](https://code.claude.com/docs/en/sub-agents).
 An API model announcement alone does not prove a third-party harness supports
@@ -66,14 +76,32 @@ The positive Sonnet control resolved, while invalid family and effort controls
 fell back to defaults. Five Opus 5.5 mappings are now approved for desktop
 subagents; the CLI result alone does not establish that the same bracket syntax
 works as a CLI top-level `--model` argument. Likewise, do not add GPT-6
-Cursor targets until that runtime lists and verifies them.
+or GPT-6.1 Cursor targets until that runtime lists and verifies them.
 
 A 2026-09-25 desktop 3.21.18 probe added Grok 4.6 and Fable 5.1 mappings
 and moved the bundled Cursor ladder to them. The same probe showed Grok 4.7
-resolves only bare flat IDs, never bracket selectors, so it stays out of the
-catalogue; see [Verifying Cursor Pins](verifying-cursor-pins.md). See [Dispatch Policy](../workflows/projects/dispatch-ceiling.md#cursor-evidence-authority)
+resolves only bare flat IDs, never bracket selectors. It still needs its own
+approved registry entry and complete per-pin evidence before admission; see [Verifying Cursor Pins](verifying-cursor-pins.md). See [Dispatch Policy](../workflows/projects/dispatch-ceiling.md#cursor-evidence-authority)
 for the distinction between catalog, configured mapping, and runtime identity.
 
+The October 1 refresh migrates Codex Sol defaults and examples to
+`gpt-6.1-sol` while preserving existing effort choices, including medium for
+intelligent recon. Claude Economy moves to `claude-sonnet-5-5` medium by user
+direction. GPT-6 Sol and Sonnet 5 remain explicitly supported. Cursor lists
+Sonnet 5.5 flat IDs at low through max. Cursor 3.22.12 native probes matched
+those exact IDs at start, Shell execution, and stop while every Sonnet 5.5
+bracket pin fell back to the account default. The existing Opus low control
+matched; unknown-family and Sonnet `ultra` exact-ID controls fell back. The
+fixture summary and event records at
+`packages/cli/src/providers/cursor/codec/__fixtures__/cursor-pin-probe-2026-10-01{,-events}.jsonl`
+retain both rounds. Ship explicit, evidence-backed exact-ID mappings for that family;
+keep existing bracket mappings. An exact-ID mapping requires the same per-pin
+native evidence and controls as a bracket mapping. Do not enable generic
+pass-through of CLI IDs. Cursor does not list GPT-6 Sol or
+GPT-6.1 Sol in the observed catalog. Do not carry Codex model IDs into Cursor
+configurations. These selector changes do not import a separate vault policy
+refresh or claim newly measured task-performance gains.
+
 ## Change and Validate
 
 1. Update the supported catalog for each verified runtime and its tests. Preserve

package/assets/docs/contributing/verifying-cursor-pins.md

@@ -7,7 +7,8 @@ description: 'Runbook for probe-verifying a Cursor model pin before shipping it:
 
 A Cursor model pin maps an OAT ladder model ID to the frontmatter selector that
 materialized role files carry, for example `gpt-5.6-sol-medium` to
-`gpt-5.6-sol[reasoning=medium]`. Adding one to
+`gpt-5.6-sol[reasoning=medium]`, or the verified exact ID
+`claude-sonnet-5-5-medium`. Adding one to
 `packages/cli/src/providers/cursor/codec/catalog.ts` requires evidence that
 Cursor actually resolves that selector to the intended model.
 
@@ -81,10 +82,22 @@ flat IDs such as `grok-4.7-medium` resolved exactly. Two lessons follow:
   control and probe non-default rungs. Here even `effort=low,fast=false`
   landed on the high-fast default.
 
-Approved mappings are bracket-form only
-(`DR-260718-explicit-cursor-pin-mapping`), so Grok 4.7 has no mapping until
-that decision is revisited. The redacted evidence is in the same fixtures
-directory.
+The 2026-10-01 revision of `DR-260718-explicit-cursor-pin-mapping` permits
+verified exact-ID entries as well as bracket selectors. Grok 4.7 remains
+outside the shipped catalog until its own entry is added and approved. The
+redacted evidence is in the same fixtures directory.
+
+The 2026-10-01 Sonnet 5.5 probe on Cursor 3.22.12 confirmed the same syntax
+distinction: every `claude-sonnet-5-5[effort=...]` selector fell back to
+`grok-4.7-high-fast`, but all five exact IDs
+`claude-sonnet-5-5-low|medium|high|xhigh|max` resolved correctly. Both rounds
+included a working Opus 5.5 low control and unknown-family and unsupported-effort
+controls that fell back. The summary and 64 correlated native events are
+retained beside the earlier fixtures.
+
+[Cursor documents specific model IDs and bracket parameters](https://cursor.com/docs/subagents#model-configuration).
+Choose a candidate from the live catalog, then probe its exact frontmatter
+spelling. Documentation and catalog presence do not replace native evidence.
 
 ## Prerequisites
 
@@ -272,10 +285,19 @@ approved it:
 
 ```ts
 approvedMapping(
-  'gpt-5.6-sol-medium',
-  'gpt-5.6-sol[reasoning=medium]',
-  'gpt-reasoning',
-  { probeName: 'zz-pin-probe-sol56-medium', verifiedAt: '2026-07-25', evidencePath: '...' },
+  'claude-sonnet-5-5-medium',
+  'claude-sonnet-5-5-medium',
+  'explicit-model-id',
+  {
+    probeName: 'zz-pin-probe-sonnet55-flat-medium',
+    probeRecord: {
+      submittedSelector: 'claude-sonnet-5-5-medium',
+      resolvedModel: 'claude-sonnet-5-5-medium',
+      verifiedAt: '2026-10-01',
+      evidencePath:
+        'packages/cli/src/providers/cursor/codec/__fixtures__/cursor-pin-probe-2026-10-01.jsonl',
+    },
+  },
 ),
 ```
 
@@ -287,6 +309,13 @@ than inheriting an approval that never covered the new selector.
 Retain the raw payloads alongside the summary. They are the primary evidence;
 the summary is an interpretation of them.
 
+For an exact-ID mapping, use the `explicit-model-id` syntax family and a
+mapping-specific probe record. The frontmatter selector must equal the ladder
+ID, and the independently captured submitted selector and resolved model must
+agree with both. Missing or mismatched evidence must fail materialization;
+there is no generic model-ID pass-through. Preserve rejected selector results
+and control observations alongside the successful rungs.
+
 ## Cleanup
 
 Delete every temporary artifact:

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

@@ -143,15 +143,24 @@ Core rules:
 - the `## Contents` section should map sibling pages and immediate child directories
 - `## Contents` links should use `.md`-suffixed relative targets, including `subdir/index.md` for child directories
 
-For **MkDocs** apps, regenerate navigation after adding or moving pages:
+Regenerate navigation after adding or moving pages. In **MkDocs** apps this
+rewrites the `nav:` block in `mkdocs.yml`; in **Fumadocs** apps it writes the
+committed `meta.json` files and reports any page no `## Contents` map lists:
 
 ```bash
 oat docs nav sync --target-dir apps/my-docs
 ```
 
-For **Fumadocs** apps, the app-root docs index manifest is generated from the
-Markdown file tree automatically via `predev`/`prebuild` hooks. You can also
-run it manually:
+Generated Fumadocs `meta.json` is strict: a page no `## Contents` map lists
+stays out of the sidebar. The `prebuild` script that `oat docs init` scaffolds
+for Fumadocs does not run the read-only check. To make builds fail on stale
+navigation or an unlisted page, as `apps/oat-docs` does, append
+`&& oat docs nav sync --check` to it; the script runs from the app directory,
+which `--target-dir` defaults to.
+
+**Fumadocs** apps also have an app-root docs index manifest, generated from
+the Markdown file tree automatically via `predev`/`prebuild` hooks. You can
+also run it manually:
 
 ```bash
 oat docs generate-index --docs-dir docs
@@ -205,7 +214,7 @@ Important:
 3. `oat docs init --app-name my-docs`
 4. (optional) handle MkDocs migration as a separate workstream; use `oat docs migrate --docs-dir docs --config mkdocs.yml --apply` only for the syntax/frontmatter helper
 5. Author docs with `index.md` + `## Contents`
-6. `oat docs nav sync --target-dir apps/my-docs` (MkDocs) or `oat docs generate-index` (Fumadocs)
+6. `oat docs nav sync --target-dir apps/my-docs` (both frameworks), plus `oat docs generate-index` (Fumadocs)
 7. `/oat-docs-analyze`
 8. `/oat-docs-apply`
 9. Repeat as the codebase changes

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

@@ -1,6 +1,6 @@
 ---
 title: Docs App Commands
-description: 'Docs scaffolding CLI surface for Fumadocs/MkDocs, migration helpers, Fumadocs index generation, and MkDocs nav sync.'
+description: 'Docs scaffolding CLI surface for Fumadocs/MkDocs, migration helpers, Fumadocs index generation, and nav sync for both frameworks.'
 ---
 
 # Docs App Commands
@@ -11,7 +11,7 @@ and **MkDocs Material**.
 
 ## Quick Look
 
-- What it does: documents the docs-specific CLI surface for scaffolding apps, migrating markdown, generating Fumadocs app-root index manifests, and syncing MkDocs navigation.
+- What it does: documents the docs-specific CLI surface for scaffolding apps, migrating markdown, generating Fumadocs app-root index manifests, and syncing MkDocs or Fumadocs navigation.
 - When to use it: when you already know you are working on a docs surface and need the exact command-level behavior.
 - Primary commands: `oat docs init`, `oat docs migrate`, `oat docs generate-index`, `oat docs nav sync`
 
@@ -22,7 +22,7 @@ and **MkDocs Material**.
 | `oat docs init`           | Scaffold a new docs app (Fumadocs or MkDocs).                                 |
 | `oat docs migrate`        | Convert MkDocs admonitions to GFM callouts and inject frontmatter.            |
 | `oat docs generate-index` | Generate a Fumadocs app-root docs index manifest from the Markdown file tree. |
-| `oat docs nav sync`       | Regenerate MkDocs `mkdocs.yml` navigation from directory `index.md` maps.     |
+| `oat docs nav sync`       | Regenerate `mkdocs.yml` nav or Fumadocs `meta.json` from `index.md` maps.     |
 | `oat docs analyze`        | CLI entrypoint that points users to the `oat-docs-analyze` skill.             |
 | `oat docs apply`          | CLI entrypoint that points users to the `oat-docs-apply` skill.               |
 
@@ -30,7 +30,7 @@ and **MkDocs Material**.
 
 Use the framework-specific generated-artifact command:
 
-- Fumadocs apps run `fumadocs-mdx` and `oat docs generate-index`. In this repo, `predev` and `prebuild` regenerate `apps/oat-docs/index.md` from `apps/oat-docs/docs`.
+- Fumadocs apps run `fumadocs-mdx` and `oat docs generate-index`. In this repo, `predev` and `prebuild` regenerate `apps/oat-docs/index.md` from `apps/oat-docs/docs`. Run `oat docs nav sync` yourself after structural changes to rewrite the committed `meta.json` sidebar files from authored directory `index.md` `## Contents` sections; the hooks never write them. `prebuild` runs `oat docs nav sync --check`, so a build fails when those files are stale or a page is unlisted.
 - MkDocs apps use `oat docs nav sync` to regenerate the `nav:` block in `mkdocs.yml` from authored directory `index.md` `## Contents` sections.
 
 Both frameworks keep authored `## Contents` sections as the source of local discovery. The generated artifact differs by framework.
@@ -183,17 +183,35 @@ script hooks.
 
 ## `oat docs nav sync`
 
-Use nav sync in MkDocs apps after adding, removing, or renaming docs pages.
+Use nav sync after adding, removing, renaming, or reordering docs pages.
 
 The command reads only the reserved `## Contents` section from each directory
-`index.md` and regenerates the `nav:` block in `mkdocs.yml`.
-
-For Fumadocs apps, regenerate the root markdown manifest with `oat docs generate-index` instead.
+`index.md`. It detects the framework from the app directory:
+
+- **MkDocs** (`mkdocs.yml`): regenerates the `nav:` block in `mkdocs.yml`.
+- **Fumadocs** (`source.config.ts`): writes one `meta.json` per docs directory
+  that has an `index.md`. `pages` follows the `## Contents` order with no
+  `"..."` rest entry, so a page no map lists stays out of the sidebar and is
+  reported by path (`unlisted` in `--json`). A link to a page in another
+  directory becomes a Fumadocs link entry, and the folder `title` comes from
+  the `index.md` frontmatter `title` or first heading. Files are compared by
+  meaning, so a rerun with no docs changes writes nothing. Commit the
+  generated `meta.json` files.
+
+Use `--check` in builds and CI. It computes the same navigation, writes
+nothing, and exits 1 when any generated file would change or, for Fumadocs,
+any page or folder is unlisted, naming each one (`stale` and `unlisted` in
+`--json`). This repository's `apps/oat-docs` `prebuild` runs it, so
+`pnpm build:docs` fails on stale navigation.
+
+Fumadocs apps also regenerate the root markdown manifest with
+`oat docs generate-index`; the two commands write different artifacts.
 
 Example:
 
 ```bash
 oat docs nav sync --target-dir apps/oat-docs
+oat docs nav sync --target-dir apps/oat-docs --check
 ```
 
 Related reference:

package/assets/docs/docs-tooling/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Docs Tooling",
+  "pages": ["add-docs-to-a-repo", "commands", "workflows"]
+}

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

@@ -18,7 +18,7 @@ Install the workflow skills with `oat tools install docs` (preferred) or
 - `oat docs init` scaffolds a docs app (Fumadocs or MkDocs)
 - `oat docs migrate` converts MkDocs admonitions to GFM callouts and injects frontmatter
 - `oat docs generate-index` generates a Fumadocs app-root docs index manifest from the Markdown file tree
-- `oat docs nav sync` regenerates MkDocs `mkdocs.yml` nav from `index.md` `## Contents` sections
+- `oat docs nav sync` regenerates MkDocs `mkdocs.yml` nav, or strict Fumadocs `meta.json` files, from `index.md` `## Contents` sections
 - `oat docs analyze` and `oat docs apply` expose the workflow surface in CLI help
 
 ### Skills
@@ -67,7 +67,7 @@ skills.
 5. Keep local `## Contents` sections current
 6. Refresh generated artifacts:
    - **MkDocs:** `oat docs nav sync`
-   - **Fumadocs:** `oat docs generate-index` (runs automatically via `predev`/`prebuild` hooks)
+   - **Fumadocs:** `oat docs nav sync` for the committed `meta.json` sidebar files (it reports pages no `## Contents` map lists), and `oat docs generate-index` for the root manifest (runs automatically via `predev`/`prebuild` hooks)
 7. Run `oat-docs-analyze`; by default it verifies the generated analysis artifact
    through `workflow.autoArtifactReview.analysis`
 8. Review the artifact and run `oat-docs-apply`

package/assets/docs/guide/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "User Guide",
+  "pages": ["concepts"]
+}

package/assets/docs/meta.json

@@ -0,0 +1,14 @@
+{
+  "title": "OAT Documentation",
+  "pages": [
+    "index",
+    "quickstart",
+    "guide",
+    "provider-sync",
+    "workflows",
+    "docs-tooling",
+    "cli-utilities",
+    "contributing",
+    "reference"
+  ]
+}

package/assets/docs/provider-sync/instruction-sync.md

@@ -401,6 +401,14 @@ oat instructions validate --strategy symlink
 
 This keeps validation, preview, and repair aligned to the same expected file shape.
 
+`--force` never overwrites a `CLAUDE.md` that an `AGENTS.md` resolves to,
+whether through a symlink, a symlink chain, or a hard link, because that
+`CLAUDE.md` holds the only copy of the instructions behind the link. Sync plans
+a `skip` for it instead, with a reason such as
+`AGENTS.md resolves to this CLAUDE.md, so it holds the instructions; kept`, and
+leaves the file unchanged under every shim strategy, including in
+`--dry-run` previews. Resolve that link by hand before repairing the pair.
+
 ## Manual-Repair Cases
 
 Some states are intentionally surfaced as drift but not auto-repaired.

package/assets/docs/provider-sync/meta.json

@@ -0,0 +1,11 @@
+{
+  "title": "Provider Sync",
+  "pages": [
+    "commands",
+    "config",
+    "instruction-sync",
+    "manifest-and-drift",
+    "providers",
+    "scope-and-surface"
+  ]
+}

package/assets/docs/provider-sync/providers.md

@@ -26,11 +26,11 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - Interactive `oat init` and `oat status` ask for an individual disposition for each unresolved Cursor-local skill: adopt it into `.agents/skills` or keep it Cursor-only and remember the exact path in sync config
     - Keep-local is blocked when a canonical skill has the same name because Cursor does not document a safe duplicate-resolution order
     - During upgrades, OAT removes only verified clean legacy managed skill views. Changed or replaced views are preserved, detached from manifest ownership, and offered for migration.
-    - Sync materializes pinned Markdown definitions for both `oat-phase-implementer` and `oat-reviewer` in addition to the base roles, which sync like any other canonical agent at both scopes. Each generated name keeps the configured flat ladder ID, while an explicit verified mapping writes the separate bracket-form frontmatter model. OAT never derives one form from the other.
+    - Sync materializes pinned Markdown definitions for both `oat-phase-implementer` and `oat-reviewer` in addition to the base roles, which sync like any other canonical agent at both scopes. Each generated name keeps the configured flat ladder ID, while an explicit verified mapping writes its frontmatter model: a bracket-form selector for existing families or an exact ID for Sonnet 5.5. The supported catalogue contains 31 pins and 62 pinned role variants. OAT never derives a selector from the ladder ID or passes through an unregistered ID.
     - Generated definitions carry `supported-catalogue`, `project-config`, or `user-config` ownership. Project and supported output lives in the tracked `.cursor/agents` view; user-owned output lives under `~/.cursor/agents`. Cleanup reconciles only the applicable owner.
     - Managed dispatch requires `providers.cursor.dispatchArgs.variant` and launches that exact resolver-selected native agent type first. Skills do not pass a Task-level model argument or normalize Cursor model strings.
     - Cursor may silently fallback when a definition pin cannot be honored. Variant acceptance therefore establishes launcher-owned `configured` provenance only; runtime identity remains `not-reported` unless independently observed.
-    - `oat doctor` checks whether each flat ID is still present in the current Cursor catalogue and reports availability drift. Catalogue availability is diagnostic and does not prove that a definition-level bracket pin ran as configured.
+    - `oat doctor` checks whether each flat ID is still present in the current Cursor catalogue and reports availability drift. Catalogue availability is diagnostic and does not prove that a definition-level pin ran as configured.
     - Rule files render as `.cursor/rules/*.mdc`
 
 === "Copilot"
@@ -59,7 +59,7 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
       - `.codex/agents/<role>.toml`
       - `.codex/config.toml` (`[features] multi_agent = true`, `[agents.<role>]` upserts)
     - Codex role files include OAT managed provenance headers and are regenerated by `oat sync --scope project|user|all`
-    - Project sync writes and maintains the version-controlled supported catalogue: GPT-6 Luna, Sol, and Astra at `low`, `medium`, `high`, `xhigh`, and `max`; GPT-5.6 Luna and Terra through `xhigh`; and GPT-5.6 Sol through `max`. Both `oat-phase-implementer` and `oat-reviewer` receive each supported pair (56 pinned variants). Sync writes files; it does not create a Git commit.
+    - Project sync writes and maintains the version-controlled supported catalogue: GPT-6.1 Sol and GPT-6 Luna, Sol, and Astra at `low`, `medium`, `high`, `xhigh`, and `max`; GPT-5.6 Luna and Terra through `xhigh`; and GPT-5.6 Sol through `max`. Both `oat-phase-implementer` and `oat-reviewer` receive each supported pair (66 pinned variants). Sync writes files; it does not create a Git commit.
     - Custom targets follow configuration provenance: user-config targets write only under `~/.codex`; shared, repo-local, and active-project targets write under the project's tracked `.codex` view.
     - User sync loads only the bundled canonical `oat-phase-implementer` and `oat-reviewer` definitions needed to expand user-config targets. It does not enable general user-agent mirroring, and it refuses stale user-role cleanup if either managed definition is unavailable.
     - Generated variants carry `supported-catalogue`, `user-config`, or `project-config` ownership. Cleanup removes stale entries only for the owner being reconciled and preserves other scopes plus unrelated Codex entries.
@@ -67,7 +67,7 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - A single role can be materialized directly with `oat providers codex materialize <agent-name> --model <model-id> --effort <reasoning-effort>`; `--agent-path` selects a specific canonical markdown agent, `--role-name` overrides the generated role name, and `--scope user` writes a user-config-owned role.
     - Aggregate Codex config drift metadata (`aggregateConfigHash`) is emitted in sync/status codex extension output and intentionally not stored as a separate manifest row
     - Sync-time materialization is best effort; managed workflow correctness uses exact registered roles or a fresh child pinned to the resolved model plus reasoning effort with canonical role instructions. After a successful provider-visible file change, OAT conservatively advises starting a new Codex session so it has an opportunity to load the role. This repository policy is not a Codex hot-reload contract, an application-process restart requirement, or proof that the new session exposed the role.
-    - Codex `max` is a first-class dispatch effort. It is supported for GPT-6 Luna, Sol, and Astra, plus GPT-5.6 Sol, for both implementer and reviewer roles.
+    - Codex `max` is a first-class dispatch effort. It is supported for GPT-6.1 Sol, GPT-6 Luna, Sol, and Astra, plus GPT-5.6 Sol, for both implementer and reviewer roles.
     - Codex multi-agent dispatch uses config-defined roles (`[agents.<name>]`) and `agent_type`
     - Codex subagent workflows require `[features] multi_agent = true` in active Codex config layers
     - Default managed Codex execution requires root (depth 0) → phase implementer (depth 1). `agents.max_depth >= 2` enables optional nested phase-agent work; sync and direct materialization still merge that capability floor without lowering a higher target value.

package/assets/docs/provider-sync/scope-and-surface.md

@@ -43,8 +43,8 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - `oat providers inspect`
 - `oat providers set`
 - `oat providers codex materialize`
-- `oat project dispatch record` (project-aware dispatch evidence only; never a
-  provider launcher)
+- `oat project dispatch record` (validates project-aware dispatch evidence and
+  writes nothing; never a provider launcher)
 - `oat project dispatch canonical-role` (read-only; prints the
   canonical-role-resolution event that `oat project dispatch record` accepts)
 
@@ -112,8 +112,7 @@ role-selection rejection and do not permit fallback.
 
 Project workflows construct and redact the complete dispatch payload before
 the native call, then record its accepted or `blocked-before-start` result in
-the project's run record; persisting it under the project's `dispatch/`
-directory is optional and off by default. The generic
+the project's run record, which is the only launch record. The generic
 record remains provider-neutral. OAT-specific canonical role, rejection,
 fallback, and runtime facts live only under its `oat` namespace. A qualifying
 fallback is a fresh request that preserves exact target and controls and is