@open-agent-toolkit/cli 0.3.10 → 0.3.12

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.10"
+  "oatVersion": "0.3.12"
 }

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

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/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/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

package/assets/docs/reference/cli-reference.md

@@ -53,6 +53,7 @@ The first practical expansion path is to keep improving the existing owners: [Do
 | `oat docs ...`                                  | Docs app bootstrap, migration, index generation, nav sync, and docs workflow entrypoints.                                                                                                                                  | [Docs Tooling Commands](../docs-tooling/commands.md)                               |
 | `oat status` / `oat sync` / `oat providers ...` | Provider sync, drift inspection, provider configuration, and adoption behavior.                                                                                                                                            | [Provider Sync](../provider-sync/index.md)                                         |
 | `oat project ...` / `oat cleanup ...`           | Project scaffolding, active-project status inspection, tracked-project listing, plan validation, archive creation, and project/artifact cleanup commands.                                                                  | [Workflow & Projects](../workflows/projects/index.md)                              |
+| `oat template resolve`                          | Resolve a lifecycle template in repository, user, then bundle order and optionally copy it into place.                                                                                                                     | [File Locations](file-locations.md)                                                |
 | `oat review ...`                                | Review artifact discovery helpers, including latest-review resolution for project and ad-hoc review flows.                                                                                                                 | [Reviews](../workflows/projects/reviews.md)                                        |
 | `oat repo ...`                                  | Repository-level workflows such as archive sync and PR-comment analysis.                                                                                                                                                   | [Repository Analysis](../workflows/projects/repo-analysis.md)                      |
 
@@ -149,12 +150,14 @@ Notable commands introduced in the current CLI surface:
 - `oat project status --project-path <path>` - read from a repo-relative or absolute project path instead of `.oat/config.local.json`'s active project pointer. Combine it with `--field` or `--shell` when a skill has already resolved the target project path.
 - `oat project status --shell NAME=path ...` - print shell-safe assignments for one or more fields from one status read, e.g. `WORKFLOW_MODE='quick'`. This is the preferred multi-field read API for skills. See [Writing Skills → Reading project state](../contributing/skills.md#reading-project-state) for examples and the `npx`-backed `oat` shim contract.
 - `oat project promote <project-path> --to quick [--json]` - promote an authored lite project to quick mode. The command derives `discovery.md` from the lite plan's Summary, Decisions, Assumptions, Out of Scope, and Validation Criteria; carries Product Behavior into Success Criteria and Technical Design into a carried-forward discovery section when those adaptive sections are present; preserves the original as `references/lite-plan.md`; and scaffolds a fresh quick `plan.md`. It refuses unsupported targets, non-lite or unreadable projects, an existing lite-plan reference, invalid authored sections, unresolved scope, unavailable templates, failed writes, or failed persistence. JSON output is `{ status: "promoted" | "refused", reason, files }`; `reason` is the stable categorical contract and refused results exit non-zero.
+- `oat template resolve <name> [--output <path>] [--json]` - resolve a template in repository (`<repo>/.oat/templates/`), user (`~/.oat/templates/`), then bundled order and report `name`, `found`, `tier` (`repository` | `user` | `bundle`), and `path`. `path` is set only for the repository and user tiers; it is `null` for the bundled tier, so callers never depend on a package-manager path. `<name>` accepts `plan` or `plan.md` and rejects path separators and `..`. `--output <path>` copies the resolved content to that file, replacing an existing file, and does not create missing parent directories; JSON output adds the absolute `output` path. A template missing from every tier exits 1 with `found: false`. Lifecycle skills use `--output` to copy their artifact templates, so a user-scope-only install works without a repository `.oat/templates/` directory.
 - `oat review latest --json` - find the newest review artifact by `oat_generated_at`, scanning the active or specified project's `reviews/` and `reviews/archived/` directories plus ad-hoc review locations. Same-time candidates use target priority, then lifecycle recency (`final` > higher phase/task > lower phase/task). The JSON contract returns `path`, `scope`, `generatedAt`, `kind` (`project` or `adhoc`), `archived`, and `actionable`, with `null` values when no review exists. Archived project reviews remain discoverable as history but return `actionable: false`.
 - `oat project list --json` - summary state for tracked projects under the configured projects root
-- `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
+- `oat project closeout-check <project-path> [--autonomous] [--json]` - read-only check of the closeout invariant: a closeout that must snapshot its post-implementation sequence cannot reach terminal completion until its `oat_post_implement_sequence` snapshot exists, every stored step is recorded complete, approval is recorded, and the snapshot reached `status: complete`. A snapshot is required when the effective layered `workflow.postImplementSequence` is configured, when the closeout is autonomous (`--autonomous`, or `OAT_AUTONOMOUS=1` in the environment even without the flag), or when `oat_workflow_mode` is `lite`. Once a snapshot exists its recorded state is authoritative and current configuration is not consulted. JSON output reports `status` (`complete`, `not_required`, or `incomplete`), the missing `invariant` (`snapshot_missing`, `snapshot_malformed`, `sequence_failed`, `pre_approval_step_pending`, `approval_pending`, `post_approval_step_pending`, or `sequence_not_complete`), `route` (`oat-project-implement` when incomplete), `nextOwner` (the next stored step and its skill, or the approval), and the evaluated `inputs`. An incomplete or malformed result exits 1.
+- `oat project complete-state <project-path> [--archived] [--autonomous]` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout. It first evaluates the same closeout invariant as `oat project closeout-check` and refuses, with the same message and without writing, a configured, autonomous, or lite closeout whose snapshot is absent, malformed, or incomplete. A project whose implementation finished before closeout snapshots existed recovers by running `oat-project-implement`, which persists the snapshot (`completion-and-closeout.md` Step 15) and completes its stored steps; there is no override flag. An unconfigured, interactive, non-lite closeout without a snapshot completes as before.
 - `oat project archive [project-path] [--project-recap-run <project-relative-path>] [--no-commit]` - archive a tracked project through the same local move, summary export, and configured S3 upload path used by completion. When omitted, the project path falls back to the active project. The optional recap path must identify a `project-recap` run inside the project's `explainers/` directory. Archive stages the selected complete package into `.oat/repo/reference/project-recaps/<YYYYMMDD-project-slug>/`, verifies every manifest-declared file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete inventory coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project. For synced projects, a configured S3 upload must succeed before terminal cleanup. Successful closeout makes `refs/oat/completed/<project>` authoritative, deletes the tracked JSON record and nested checkout, and leaves archive metadata sufficient for an idempotent recordless retry. With `--json`, the terminal receipt reports `completedRef`, `verifiedSourceSha`, whether `activeAliasDisposition` was `retained` or `removed`, whether `recordRetired` completed, and the parent `lifecycleCommit`. `--no-commit` is a manual/library-only option: for a synced project it still removes the checkout but deliberately leaves `lifecycleCommit` null. Never pass it through `oat-project-complete`, which requires that receipt.
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
-- `oat project dispatch record --event-file <json-file-or-dash> [--project <project-path>]` - validate one generic dispatch record plus its namespaced OAT evidence event, and persist it into the project's append-only `dispatch/` journal (optional; no lifecycle skill requires persistence). Omit `--project` to validate without persisting. Managed, effort-pinned Claude launches use the validation-only form before launch: the input carries `claudeLaunch` with the real resolver result, generated definition, and proposed payload, plus `recordBase` and `event`. The command validates their agreement and derives the configured invocation fields; callers cannot copy those fields into `recordBase`. One validation run reports every violation across `claudeLaunch`, `recordBase`, and `event` in a single error message, one `stage path: message` line each; the `recordBase` cross-field rules run even when a required field is missing, checks that need a value that failed to parse are skipped and named on a final line, secret-shaped values and absolute paths are scrubbed from the message, and the exit code stays 1. A validated input per role is published at `.agents/skills/oat-dispatch-subagents/references/managed-claude-example.json`. Revision 1 is `dispatch/<request-id>.json` and every later revision is `dispatch/<request-id>@<NNNN>.json`; superseded revisions are never replaced or removed. The command validates and records evidence only — it never launches a provider. A `runtime-observation` event may carry either a finished `observation` or the provider `metadata` envelope (`provider`, `observedAt`, `entries`) to normalize, but not both. `entries` may be raw provider output: they are projected through the owning parser's allowlist, are never persisted, and both forms have their `match` derived from the record's configured invocation rather than trusted from the caller, with the observation's `provider` bound to the record's. With `--json`, the result adds `runtimeIdentity` with separate `configured` and `observed` objects plus a `match` of `matching`, `mismatching`, `not-comparable`, or `null`; observation is corroboration only and never overrides configured invocation. Error output is redacted on a best-effort basis; absolute paths in identity fields are rejected outright, while some prose forms (colon-prefixed, URL routes) can survive. See [Evidence Layers](../workflows/projects/evidence-layers.md).
+- `oat project dispatch record --event-file <json-file-or-dash>` - validate one generic dispatch record plus its namespaced OAT evidence event and print the result with `status: validated-only`. The command writes nothing; launches are recorded in the calling workflow's run record. Managed, effort-pinned Claude launches run it before launch: the input carries `claudeLaunch` with the real resolver result, generated definition, and proposed payload, plus `recordBase` and `event`. The command validates their agreement and derives the configured invocation fields; callers cannot copy those fields into `recordBase`. One validation run reports every violation across `claudeLaunch`, `recordBase`, and `event` in a single error message, one `stage path: message` line each; the `recordBase` cross-field rules run even when a required field is missing, checks that need a value that failed to parse are skipped and named on a final line, secret-shaped values and absolute paths are scrubbed from the message, and the exit code stays 1. A validated input per role is published at `.agents/skills/oat-dispatch-subagents/references/managed-claude-example.json`. The command validates evidence only — it never launches a provider. A `runtime-observation` event may carry either a finished `observation` or the provider `metadata` envelope (`provider`, `observedAt`, `entries`) to normalize, but not both. `entries` may be raw provider output: they are projected through the owning parser's allowlist, are never echoed in the output, and both forms have their `match` derived from the record's configured invocation rather than trusted from the caller, with the observation's `provider` bound to the record's. With `--json`, the result adds `runtimeIdentity` with separate `configured` and `observed` objects plus a `match` of `matching`, `mismatching`, `not-comparable`, or `null`; observation is corroboration only and never overrides configured invocation. Error output is redacted on a best-effort basis; absolute paths in identity fields are rejected outright, while some prose forms (colon-prefixed, URL routes) can survive. See [Evidence Layers](../workflows/projects/evidence-layers.md).
 - `oat project dispatch canonical-role --role <name> --request-id <id> --skill-dir <dir> [--json]` - resolve a canonical role through the loaded, user (`$HOME/.agents`), and project (`<repo>/.agents`) tiers and print the `canonical-role-resolution` event that `oat project dispatch record` accepts unchanged: redacted `canonicalPath` and `selectedPath` in the form `<loaded|user|project>/agents/<name>.md`, the role's `contentDigest`, and `candidateMisses`. `--skill-dir` is required because the loaded tier is derived from the loaded skill's directory; a missing or invalid directory exits 1 with a redacted error. An unknown role prints `missing` evidence with its recovery commands. Read-only; the dependency is the `workflows` pack.
 - `oat project validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. Lite plans must contain exactly one phase, declare no parallel groups, and give every Validation Criteria bullet either a backticked command or a `manual:` instruction. See [Implementation Execution](../workflows/projects/implementation-execution.md#parallel-phase-groups).
 - `oat project log append|check|synthesize|rollup` - manage the optional append-only project observation log: append validated judgment or structural entries, inspect grammar and synthesis status, complete end-of-run synthesis, and roll observations into `summary.md` plus the configured repository ledger. See [Project Log](../cli-utilities/project-log.md).

package/assets/docs/reference/docs-index-contract.md

@@ -1,6 +1,6 @@
 ---
 title: Docs Index Contract
-description: 'Docs source contract: authored index.md maps, generated Fumadocs manifests, and MkDocs nav sync.'
+description: 'Docs source contract: authored index.md maps, generated Fumadocs manifests and meta.json navigation, and MkDocs nav sync.'
 ---
 
 # Docs Index Contract
@@ -15,7 +15,7 @@ OAT docs navigation starts from authored `docs/**/index.md` files. Each `## Cont
 - Every `## Contents` link should use a `.md`-suffixed relative target, including child directory links such as `subdir/index.md`.
 - Do not hand-edit generated navigation or generated root-index artifacts.
 - For Fumadocs, refresh or freshness-check the generated app-root manifest after adding, removing, or renaming Markdown files. Compare that manifest against authored `## Contents` maps for drift; reordering `## Contents` does not reorder the generated manifest's file-tree sort.
-- For MkDocs, run `oat docs nav sync` after adding, removing, renaming, or reordering pages. It regenerates `mkdocs.yml` from authored `## Contents` maps and preserves the order declared in each local map.
+- Run `oat docs nav sync` after adding, removing, renaming, or reordering pages. It regenerates the framework's navigation from authored `## Contents` maps and preserves the order declared in each local map: the `nav:` block in `mkdocs.yml` for MkDocs, and one `meta.json` per docs directory for Fumadocs.
 
 ## `## Contents` format
 
@@ -37,7 +37,7 @@ Notes:
 
 ## Fumadocs Generation
 
-For this Fumadocs app, rendered page routing and sidebar data come from the Fumadocs file/source pipeline over `apps/oat-docs/docs`. The generated root manifest, `apps/oat-docs/index.md`, is an inventory for agents and tooling; it is not the rendered sidebar/page-tree source.
+For this Fumadocs app, rendered page routing comes from the Fumadocs file/source pipeline over `apps/oat-docs/docs`, and the sidebar order comes from the committed `meta.json` files that `oat docs nav sync` writes (see [Fumadocs Nav Sync](#fumadocs-nav-sync)). The generated root manifest, `apps/oat-docs/index.md`, is an inventory for agents and tooling; it is not the rendered sidebar/page-tree source.
 
 `oat docs generate-index` walks the Markdown file tree under `docs/` and writes the app-root generated manifest. The app scripts run:
 
@@ -46,7 +46,7 @@ fumadocs-mdx
 pnpm -w run cli:source -- docs generate-index --docs-dir apps/oat-docs/docs --output apps/oat-docs/index.md
 ```
 
-`oat docs generate-index` rewrites the generated root manifest from the docs source tree. It is the command to use after adding, removing, or retiring pages in this Fumadocs app. Do not use `oat docs nav sync` as the Fumadocs regeneration step.
+`oat docs generate-index` rewrites the generated root manifest from the docs source tree. Run it after adding, removing, or retiring pages in this Fumadocs app, and run `oat docs nav sync` as well so the sidebar's `meta.json` files follow the same change. The two commands produce different artifacts: `generate-index` writes the agent-facing inventory and `nav sync` writes the sidebar navigation.
 
 Fumadocs generated behavior:
 
@@ -54,6 +54,23 @@ Fumadocs generated behavior:
 - Reordering a `## Contents` block does not reorder the generated manifest's file-tree sort.
 - Generated manifests should carry an autogen warning and are rewritten by `predev` / `prebuild`.
 
+## Fumadocs Nav Sync
+
+In a Fumadocs app (detected by its `source.config.ts`), `oat docs nav sync --target-dir <docs-app-dir>` writes one `meta.json` beside every docs directory `index.md`. The files are generated and committed; edit the `## Contents` map, not the `meta.json`.
+
+Fumadocs generated behavior:
+
+- `pages` follows the order of the directory's `## Contents` links. The root list starts with `index`; a child directory appears by its folder name, and its own `index.md` becomes that folder's landing page. A folder whose `meta.json` keeps `root: true` also lists `index` first, because Fumadocs gives a root folder no implicit landing page.
+- Navigation is strict: there is no `"..."` rest entry. A page or folder that no `## Contents` map lists stays out of the sidebar, and the command reports it by path in its human output and in `--json` (`unlisted`). Add the page to its directory's `## Contents` map to show it.
+- A `## Contents` link to a page in another directory is written as a Fumadocs link entry such as `[Writing Skills](/contributing/skills)`, so each page belongs to exactly one folder.
+- A page or folder whose name Fumadocs would read as a `pages` directive, such as `!hidden`, `z...a`, `...name`, or `---`, is written in the local-path form `./!hidden` so it stays a page entry.
+- The folder `title` comes from the `index.md` frontmatter `title`, falling back to its first `#` heading.
+- Keys nav sync does not own, such as `icon` or `defaultOpen`, are kept.
+- Existing files are compared by meaning, not bytes, so a second run with no docs changes writes nothing, even after a formatter rewrites the files.
+- `.md` and `.mdx` pages can both be listed; each appears in `pages` by its file name without the extension.
+
+`oat docs nav sync --check` computes the same result and writes nothing. It exits 1 when a `meta.json` file would change or a page or folder is unlisted, and names each one. In this app, `prebuild` runs it, so `pnpm build:docs` fails until the `## Contents` maps and the committed `meta.json` files agree.
+
 ## MkDocs Nav Sync
 
 MkDocs apps use `oat docs nav sync --target-dir <docs-app-dir>` to walk the docs tree from `docs/index.md` downward and regenerate the `nav:` block in `mkdocs.yml` from discovered directory `index.md` files.
@@ -69,7 +86,7 @@ MkDocs generated behavior:
 
 - Edit authored files under `docs/`, especially the nearest `index.md` and `## Contents`.
 - Do not hand-edit a Fumadocs app-root generated `index.md`; regenerate it from the docs source tree.
-- Do not hand-maintain MkDocs `nav:` entries when the local workflow uses `oat docs nav sync`.
+- Do not hand-maintain MkDocs `nav:` entries or Fumadocs `meta.json` `pages` lists when the local workflow uses `oat docs nav sync`.
 - If a Fumadocs generated manifest lists pages that are missing from authored `## Contents`, treat that as authored-source drift or intentional generator-inventory behavior to verify before relying on the generated file as navigation evidence.
 
 ## Authoring guidance
@@ -77,7 +94,7 @@ MkDocs generated behavior:
 - Use `index.md` as the local discovery surface for humans and agents.
 - Add a short topic description next to each link so agents can choose the right file without opening every page.
 - Update `## Contents` whenever you add, remove, rename, or reorder docs files in a directory.
-- Regenerate the framework-specific artifact after structural changes: `generate-index` for Fumadocs root manifests, `nav sync` for MkDocs `mkdocs.yml`.
+- Regenerate the framework-specific artifacts after structural changes: `nav sync` for MkDocs `mkdocs.yml` and Fumadocs `meta.json` navigation, plus `generate-index` for Fumadocs root manifests.
 - Refresh or freshness-check the generated artifact before committing structural docs changes.
 
 ## If You Are Trying To...

package/assets/docs/reference/file-locations.md

@@ -38,7 +38,12 @@ columns are ordinary states.
 
 Project-scope templates under `.oat/templates/` are owner overrides that OAT
 seeds once and never rewrites; the managed default lives at user scope and in
-the bundle. PJM templates resolve repository → user → bundle.
+the bundle. Project lifecycle and PJM templates resolve repository → user →
+bundle. Run `oat template resolve <name>` to see which tier supplies one, or
+add `--output <path>` to copy it. Idea templates under `ideas/` are different:
+the ideas skills select `.oat/templates/ideas/` or `~/.oat/templates/ideas/` by
+the ideas scope, and `oat template resolve` does not search nested
+directories.
 
 Pack intent is stored per scope:
 
@@ -172,7 +177,7 @@ Archive sync surfaces:
 - `packages/cli/src/commands/docs/init/` — scaffold a docs app (Fumadocs or MkDocs)
 - `packages/cli/src/commands/docs/migrate/` — convert MkDocs admonitions to GFM callouts
 - `packages/cli/src/commands/docs/index-generate/` — generate a docs index from markdown files
-- `packages/cli/src/commands/docs/nav/` — regenerate mkdocs.yml nav from index.md sections
+- `packages/cli/src/commands/docs/nav/` — regenerate mkdocs.yml nav or Fumadocs meta.json from index.md sections
 - `packages/cli/src/commands/instructions/`
 - `packages/cli/src/commands/project/`
 - `packages/cli/src/commands/internal/`

package/assets/docs/reference/index.md

@@ -13,7 +13,7 @@ Contributor how-to material now lives under `contributing/`, and user-facing rou
 
 - [CLI Reference](cli-reference.md) - Shallow map of the OAT command surface with links to owning sections.
 - [File Locations](file-locations.md) - Where core OAT files, assets, and artifacts live.
-- [Docs Index Contract](docs-index-contract.md) - Authored `index.md` maps, `.md` links, generated Fumadocs manifests, and MkDocs nav sync boundaries.
+- [Docs Index Contract](docs-index-contract.md) - Authored `index.md` maps, `.md` links, generated Fumadocs manifests, and MkDocs and Fumadocs nav sync boundaries.
 - [OAT Directory Structure](oat-directory-structure.md) - Canonical `.oat/` tree map and the role of each major directory.
 - [Troubleshooting](troubleshooting.md) - Common issues, diagnostics, and remediation guidance.
 

package/assets/docs/reference/meta.json

@@ -0,0 +1,10 @@
+{
+  "title": "Reference",
+  "pages": [
+    "cli-reference",
+    "file-locations",
+    "docs-index-contract",
+    "oat-directory-structure",
+    "troubleshooting"
+  ]
+}

package/assets/docs/reference/troubleshooting.md

@@ -97,6 +97,27 @@ Use [Instruction Sync](../provider-sync/instruction-sync.md) for the full strate
 - Per-pack install commands no longer accept the previously inert `--force`
   option.
 
+## A skill fails with `unknown command 'template'` or `'closeout-check'`
+
+Lifecycle skills from OAT 0.3.11 copy their templates with
+`oat template resolve` and check closeout with `oat project closeout-check`.
+An older `oat` on `PATH` rejects both:
+
+```text
+error: unknown command 'template'
+error: unknown command 'closeout-check'
+```
+
+`oat-project-complete` treats a failed closeout check as an incomplete
+closeout, so with an older CLI it stops and routes back to
+`oat-project-implement` even when every closeout step is done. This happens
+when the skills a host loads are newer than the CLI, for example repository
+skills from a newer checkout run against an older global CLI.
+
+Check `oat --version`. Install `@open-agent-toolkit/cli` 0.3.11 or later, then
+refresh the installed skills to that CLI's bundle with
+`oat tools update --all`.
+
 ## `sync` reports an unsafe provider parent
 
 Errors containing `Unsafe provider parent`, `symbolic links are not allowed in
@@ -200,7 +221,13 @@ OAT could not read the canonical managed-pack inventory. `oat status` keeps the
 rest of the report available and returns `packs.availability.status` as
 `unavailable` in JSON, with an empty `packs.states` array and a structured
 diagnostic. `oat doctor` emits the same condition as a warning instead of
-stopping its other checks. Reported project and home paths remain redacted.
+stopping its other checks.
+
+The diagnostic message redacts only the roots that are part of the run: the
+project root becomes a relative path (or `.`) when project scope is checked,
+and the home root becomes `~` when user scope is checked. Redaction is a literal
+replacement of those exact root paths, so a path outside them, such as a global
+bundle path in an assets error, stays absolute in the message.
 
 Rebuild the CLI workspace, then rerun the command named in the diagnostic:
 
@@ -269,16 +296,24 @@ oat pjm init
 scaffold — rerun `oat pjm init`), or `none`. `oat pjm init` records
 `pjm.initialized` in `.oat/config.json` after verifying the canonical scaffold.
 
-## A PJM template change is not taking effect
+## A template change is not taking effect
+
+Project lifecycle and PJM templates resolve repository → user → bundle, first
+match wins (idea templates follow the ideas scope instead). A repository
+template under `.oat/templates/` is an owner override that pack updates never
+rewrite, so it shadows the managed user default. Check which tier supplies a
+template:
 
-PJM templates resolve repository → user → bundle, first match wins. A
-repository template under `.oat/templates/` is an owner override that pack
-updates never rewrite, so it shadows the managed user default.
+```bash
+oat template resolve plan
+```
 
 Delete the repository copy to fall back to the managed default, or update the
-managed default itself:
+managed default itself (`workflows` owns the project lifecycle templates,
+`project-management` the PJM templates):
 
 ```bash
+oat tools update --pack workflows --scope user
 oat tools update --pack project-management --scope user
 ```
 

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

@@ -0,0 +1,4 @@
+{
+  "title": "Ideas Workflow",
+  "pages": ["lifecycle"]
+}

package/assets/docs/workflows/meta.json

@@ -0,0 +1,4 @@
+{
+  "title": "Agentic Workflows",
+  "pages": ["ideas", "projects", "wave-workflows", "skills"]
+}

package/assets/docs/workflows/projects/cursor-cloud.md

@@ -95,9 +95,14 @@ dispatch records, prompts, logs, or the VM image.
 ## User-scope asset precedence
 
 In provisioned cloud environments, the user-scope installation is the execution
-source for every OAT asset class: skills, templates, and scripts. The user tier
-is refreshed from the published package during environment setup; repository
-copies are compatibility context, not an override.
+source for skills and scripts. The user tier is refreshed from the published
+package during environment setup; repository copies of skills and scripts are
+compatibility context, not an override.
+
+Templates are the exception. They resolve repository, then user, then bundled,
+the same order as everywhere else, because a repository template is an owner
+override. Agents resolve and copy them with `oat template resolve <name>
+--output <destination>` rather than reading `~/.oat/templates/` directly.
 
 For skills, compare frontmatter versions as a freshness check: