@open-agent-toolkit/cli 0.3.13 → 0.3.15

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

@@ -11,16 +11,16 @@ The CLI is also a standalone value path. You can use `oat init`, `oat sync`, `oa
 
 ## Contents
 
-- [CLI Bootstrap](../cli-utilities/bootstrap.md) - Bootstrap a repo with `oat init`, guided setup, and initial provider adoption.
-- [Tool Packs](../cli-utilities/tool-packs.md) - Install, update, inspect, migrate, and remove bundled OAT skills and agents at project or user scope.
-- [Config and Local State](../cli-utilities/config-and-local-state.md) - Config, backlog, local paths, diagnostics, and related utility commands.
-- [Remote Project Management](../cli-utilities/remote-project-management.md) - Explicit remote bindings, policy, host handoffs, and recovery.
-- [Workflow Gates](../cli-utilities/workflow-gates.md) - Per-skill final commands, review gates, and cross-runtime prompt dispatch.
+- [CLI Bootstrap](../getting-started/bootstrap.md) - Bootstrap a repo with `oat init`, guided setup, and initial provider adoption.
+- [Tool Packs](../getting-started/tool-packs.md) - Install, update, inspect, migrate, and remove bundled OAT skills and agents at project or user scope.
+- [Config and Local State](config-and-local-state.md) - Config, backlog, local paths, diagnostics, and related utility commands.
+- [Remote Project Management](../workflows/backlog-and-planning/remote-project-management.md) - Explicit remote bindings, policy, host handoffs, and recovery.
+- [Workflow Gates](../workflows/advanced/workflow-gates.md) - Per-skill final commands, review gates, and cross-runtime prompt dispatch.
 - [Docs Tooling Commands](../docs-tooling/commands.md) - Markdown setup/adoption, framework scaffolding, manifests, and nav sync.
 - [Provider Sync](../provider-sync/index.md) - Sync behavior, provider capabilities, config, and drift management.
-- [Agentic Workflows](../workflows/index.md) - Tracked project execution, skills, ideas, and workflow routing.
+- [Agentic Workflows](../workflows/choose-workflow.md) - Tracked project execution, skills, ideas, and workflow routing.
 - [Workflow & Projects](../workflows/projects/index.md) - Project lifecycle, artifacts, reviews, PR flow, and state-machine docs.
-- [Repository PR Comment Analysis](../workflows/projects/repo-analysis.md) - Detailed `oat repo pr-comments ...` behavior.
+- [Repository PR Comment Analysis](repository-pr-comments.md) - Detailed `oat repo pr-comments ...` behavior.
 
 ## Full CLI Reference Expansion Path
 
@@ -35,27 +35,27 @@ Each full command reference should include:
 - non-interactive usage guidance, including required flags and scripting-safe forms
 - source or test references for behavior that is easy to drift, marking unknown exit-code behavior as unknown instead of inventing a contract
 
-The first practical expansion path is to keep improving the existing owners: [Docs App Commands](../docs-tooling/commands.md), [Provider Interop Commands](../provider-sync/commands.md), [Config and Local State](../cli-utilities/config-and-local-state.md), [Tool Packs](../cli-utilities/tool-packs.md), [Workflow & Projects](../workflows/projects/index.md), and [Repository PR Comment Analysis](../workflows/projects/repo-analysis.md).
+The first practical expansion path is to keep improving the existing owners: [Docs App Commands](../docs-tooling/commands.md), [Provider Interop Commands](../provider-sync/commands.md), [Config and Local State](config-and-local-state.md), [Tool Packs](../getting-started/tool-packs.md), [Workflow & Projects](../workflows/projects/index.md), and [Repository PR Comment Analysis](repository-pr-comments.md).
 
 ## Command Groups
 
-| Command group                                   | What it covers                                                                                                                                                                                                             | Go deeper                                                                          |
-| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
-| `oat init`                                      | Bootstrap canonical OAT directories, sync config, optional hooks, and guided setup.                                                                                                                                        | [CLI Bootstrap](../cli-utilities/bootstrap.md)                                     |
-| `oat tools ...`                                 | Install, inspect, update, remove, and migrate bundled OAT tool packs and assets across project and user scope.                                                                                                             | [Tool Packs](../cli-utilities/tool-packs.md)                                       |
-| `oat pjm ...`                                   | Adopt PJM for a repository and record it (`init`), run read-only adoption and reference diagnostics (`doctor`), and migrate legacy layouts to `pjm/` + `reference/` (`migrate`). Adoption is separate from pack placement. | [Install vs. initialize](../cli-utilities/tool-packs.md#install-vs-initialize)     |
-| `oat pjm remote ...`                            | Intake, publish, refresh, reconcile, close out, inspect discussion, resolve anomalies, diagnose, migrate, and continue durable host actions for explicit remote bindings.                                                  | [Remote Project Management](../cli-utilities/remote-project-management.md)         |
-| `oat decision ...`                              | Create, index, and migrate file-per-record repo decisions under `reference/decisions/` (`init`, `new`, `regenerate-index`, `migrate`).                                                                                     | [Config and Local State](../cli-utilities/config-and-local-state.md#oat-decision-) |
-| `oat backlog ...` / `oat local ...`             | File-backed backlog helpers, local path sync, and local-only operational support.                                                                                                                                          | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
-| `oat config ...` / `oat instructions ...`       | Config discovery, source-aware config dumps, supported mutations, and instruction-integrity helpers.                                                                                                                       | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
-| `oat gate ...`                                  | Per-skill final gate config, review-specific gate execution, exec-target registry writes, and cross-runtime prompt dispatch.                                                                                               | [Workflow Gates](../cli-utilities/workflow-gates.md)                               |
-| `oat state ...` / `oat index ...` / `internal`  | Repo dashboard refresh, repo indexing, validation helpers, and diagnostics.                                                                                                                                                | [Config and Local State](../cli-utilities/config-and-local-state.md)               |
-| `oat docs ...`                                  | Markdown bootstrap/adoption, framework setup, external manifests, 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)                      |
+| Command group                                   | What it covers                                                                                                                                                                                                             | Go deeper                                                                                   |
+| ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `oat init`                                      | Bootstrap canonical OAT directories, sync config, optional hooks, and guided setup.                                                                                                                                        | [CLI Bootstrap](../getting-started/bootstrap.md)                                            |
+| `oat tools ...`                                 | Install, inspect, update, remove, and migrate bundled OAT tool packs and assets across project and user scope.                                                                                                             | [Tool Packs](../getting-started/tool-packs.md)                                              |
+| `oat pjm ...`                                   | Adopt PJM for a repository and record it (`init`), run read-only adoption and reference diagnostics (`doctor`), and migrate legacy layouts to `pjm/` + `reference/` (`migrate`). Adoption is separate from pack placement. | [Install vs. initialize](../getting-started/tool-packs.md#install-vs-initialize)            |
+| `oat pjm remote ...`                            | Intake, publish, refresh, reconcile, close out, inspect discussion, resolve anomalies, diagnose, migrate, and continue durable host actions for explicit remote bindings.                                                  | [Remote Project Management](../workflows/backlog-and-planning/remote-project-management.md) |
+| `oat decision ...`                              | Create, index, and migrate file-per-record repo decisions under `reference/decisions/` (`init`, `new`, `regenerate-index`, `migrate`).                                                                                     | [Config and Local State](config-and-local-state.md#oat-decision-)                           |
+| `oat backlog ...` / `oat local ...`             | File-backed backlog helpers, local path sync, and local-only operational support.                                                                                                                                          | [Config and Local State](config-and-local-state.md)                                         |
+| `oat config ...` / `oat instructions ...`       | Config discovery, source-aware config dumps, supported mutations, and instruction-integrity helpers.                                                                                                                       | [Config and Local State](config-and-local-state.md)                                         |
+| `oat gate ...`                                  | Per-skill final gate config, review-specific gate execution, exec-target registry writes, and cross-runtime prompt dispatch.                                                                                               | [Workflow Gates](../workflows/advanced/workflow-gates.md)                                   |
+| `oat state ...` / `oat index ...` / `internal`  | Repo dashboard refresh, repo indexing, validation helpers, and diagnostics.                                                                                                                                                | [Config and Local State](config-and-local-state.md)                                         |
+| `oat docs ...`                                  | Markdown bootstrap/adoption, framework setup, external manifests, 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/index.md)                                           |
+| `oat repo ...`                                  | Repository-level workflows such as archive sync and PR-comment analysis.                                                                                                                                                   | [Repository Analysis](repository-pr-comments.md)                                            |
 
 Notable commands introduced in the current CLI surface:
 
@@ -135,8 +135,8 @@ Notable commands introduced in the current CLI surface:
   `refs/oat/completed/<project>` result counts as absence. Transport,
   authentication, and other lookup failures fail the command closed; they are
   never converted into a `recorded-absent` row or pull guidance.
-- `oat tools guidance` - print the managed `OAT tools` `AGENTS.md` block for the currently installed packs without installing, upgrading, or writing anything; `--json` returns `status`, `sectionKey`, `target`, `packs`, `otherProjectSkills`, and `managedBlock`. See [Tool Packs](../cli-utilities/tool-packs.md#oat-tools-guidance).
-- `oat tools migrate --pack <pack> --from <scope> --to <scope>` - move one installed pack between project and user scope. Always previews first, installs and re-inventories the destination before touching the source, and offers source removal only after the destination is verified complete. Declining or running non-interactively leaves the pack installed at both scopes rather than failing. `--dry-run` stops after the preview; there is no force flag. See [Tool Packs](../cli-utilities/tool-packs.md#oat-tools-migrate).
+- `oat tools guidance` - print the managed `OAT tools` `AGENTS.md` block for the currently installed packs without installing, upgrading, or writing anything; `--json` returns `status`, `sectionKey`, `target`, `packs`, `otherProjectSkills`, and `managedBlock`. See [Tool Packs](../getting-started/tool-packs.md#oat-tools-guidance).
+- `oat tools migrate --pack <pack> --from <scope> --to <scope>` - move one installed pack between project and user scope. Always previews first, installs and re-inventories the destination before touching the source, and offers source removal only after the destination is verified complete. Declining or running non-interactively leaves the pack installed at both scopes rather than failing. `--dry-run` stops after the preview; there is no force flag. See [Tool Packs](../getting-started/tool-packs.md#oat-tools-migrate).
 - `oat pjm doctor --json` - read-only repository PJM diagnostics whose result carries an additive `adoption` object (`state` of `declared` | `inferred-legacy` | `partial-initialization` | `none`, `repoRoot`, and `recovery`). This, not `oat tools has project-management`, is the check that answers whether _this repository_ adopted PJM.
 - `oat pjm remote ... --json` - operate one explicit provider-neutral binding.
   The family includes `intake`, `publish`, `refresh`, `reconcile`, `closeout`,
@@ -145,7 +145,7 @@ Notable commands introduced in the current CLI surface:
   every safely persisted nonterminal or blocked status exits 1. A `pending`
   envelope with `externalAction` is a durable host handoff, not remote success.
 - `oat config dump --json` - merged config with source attribution
-- `oat project status --json` - full parsed state for the active tracked project. **Stable contract for skills:** the JSON output is a typed read interface for OAT skills; the field set consumed by migrated skills is locked by `MIGRATED_FIELDS` in `packages/cli/src/commands/project/status.test.ts`. Removing or renaming any of `project.{name, path, phase, phaseStatus, workflowMode, docsUpdated, lastCommit, prStatus, prUrl}` is a breaking change and will fail the contract test.
+- `oat project status --json` - full parsed state for the active tracked project. **Stable contract for skills:** the JSON output is a typed read interface for OAT skills; the fields that OAT skills read from it are pinned by a contract test in the OAT source repository. Removing or renaming any of `project.{name, path, phase, phaseStatus, workflowMode, docsUpdated, lastCommit, prStatus, prUrl}` is a breaking change and fails that test.
 - `oat project status --field <path>` - print one arbitrary dot-path field from the same status payload, e.g. `project.workflowMode` or `project.timestamps.stateUpdated`. Missing/null fields print `null`; object and array fields print compact JSON.
 - `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.
@@ -157,12 +157,12 @@ Notable commands introduced in the current CLI surface:
 - `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>` - 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 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/advanced/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).
+- `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/execution/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](../workflows/projects/execution/project-log.md).
 - `oat project set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.
-- `oat gate review <prompt...>` - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. `--timeout-ms <milliseconds>` overrides target, `workflow.gateTimeouts`, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews default to 30 minutes, while task code and artifact reviews default to 15 minutes. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_missing` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. `artifact_missing` means an accepted child exited cleanly without an artifact; fix synchronous review/artifact completion and start a new run, without review-receive or same-run remediation. For `targeting_correlation_failed`, correct the project declaration or artifact routing and start a new run; do not run review-receive even if an artifact path is present. For `artifact_validation_failed`, correct the artifact and rerun the gate until it revalidates as `ok` or `blocked`. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. `review_failed` may include structured `refusal`, `noOutputProduced`, and metadata-only `activityEvidence`; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. When post-selection work fails after the reviewer already committed a run-correlated artifact, the gate re-validates that selected snapshot through the same eligibility path rather than re-parsing whatever the path now holds, never re-dispatching, and returns the ordinary `ok` or `blocked` envelope with additive `postSelectionRecovery: true`; the artifact must still be present and unchanged for re-validation to succeed. When nothing recovers, `review_failed` names the failing sub-step in `postSelection.step` and its cause in `postSelection.code`. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Orchestrators should read the structured result rather than poll the filesystem. See [Workflow Gates](../cli-utilities/workflow-gates.md).
+- `oat gate review <prompt...>` - run a stateful, headless OAT review through the target registry, parse the produced review artifact, and exit nonzero for configured blocking findings. `--timeout-ms <milliseconds>` overrides target, `workflow.gateTimeouts`, environment, and scope defaults; accepted values are 1,000–14,400,000. Final/phase/range code reviews default to 30 minutes, while task code and artifact reviews default to 15 minutes. With `--json`, the result envelope on exit is the canonical completion signal: `status` is `ok` | `blocked` | `review_failed` | `artifact_missing` | `artifact_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. `artifact_missing` means an accepted child exited cleanly without an artifact; fix synchronous review/artifact completion and start a new run, without review-receive or same-run remediation. For `targeting_correlation_failed`, correct the project declaration or artifact routing and start a new run; do not run review-receive even if an artifact path is present. For `artifact_validation_failed`, correct the artifact and rerun the gate until it revalidates as `ok` or `blocked`. Invoke `oat-project-review-receive` only when all three conditions hold: `status` is `ok` or `blocked`, `receiveEligible` is `true`, and `handoff` is non-null. `review_failed` may include structured `refusal`, `noOutputProduced`, and metadata-only `activityEvidence`; these diagnostic fields never make a run receive-eligible. After a timeout, a validated run-correlated artifact returns the ordinary `ok` or `blocked` envelope with additive `lateCompletion: true`. When post-selection work fails after the reviewer already committed a run-correlated artifact, the gate re-validates that selected snapshot through the same eligibility path rather than re-parsing whatever the path now holds, never re-dispatching, and returns the ordinary `ok` or `blocked` envelope with additive `postSelectionRecovery: true`; the artifact must still be present and unchanged for re-validation to succeed. When nothing recovers, `review_failed` names the failing sub-step in `postSelection.step` and its cause in `postSelection.code`. Duplicate run-ID matches or a changed artifact with a mismatched run ID retain `targeting_correlation_failed` and `receiveEligible: false`. Orchestrators should read the structured result rather than poll the filesystem. See [Workflow Gates](../workflows/advanced/workflow-gates.md).
 - `oat gate route --expect-runtime <runtime> --expect-model <model> --can-await <true|false> --json` - return the headless child route (`inline`, `delegate-sync`, or `refuse`) from provider-marker and model evidence. Ambiguous or contradictory evidence never routes inline.
 - `oat gate exec <prompt...>` / `oat gate cross-provider-exec <prompt...>` - run a generic target prompt. `--timeout-ms` uses the same validated CLI override; untyped runs otherwise retain the legacy default path.
 - `oat gate target set <id> --invocation-model <model|provider-default> --invocation-reasoning-effort <effort|provider-default>` - persist optional configured invocation metadata alongside an exec target without inferring it from the target command.
@@ -211,4 +211,4 @@ The `workflow.*` namespace holds user-facing workflow preferences that let you a
 - `workflow.autoArtifactReview.analysis` (`boolean`, default `true`) — auto-run the bounded accuracy-review loop for generated analysis artifacts before apply workflows consume them
 - `workflow.gateTimeouts.code` / `workflow.gateTimeouts.artifact` (integer milliseconds from 1,000–14,400,000) — review-type budget defaults below CLI and target overrides
 
-These workflow keys resolve through config files and defaults (`local > shared > user > default`). Some config keys have explicit environment aliases, but `workflow.autoArtifactReview.plan` and `workflow.autoArtifactReview.analysis` do not. See [Workflow preferences in the Configuration guide](../cli-utilities/configuration.md#workflow-preferences-workflow) for full descriptions, surface guidance, and cross-repo foot-gun examples.
+These workflow keys resolve through config files and defaults (`local > shared > user > default`). Some config keys have explicit environment aliases, but `workflow.autoArtifactReview.plan` and `workflow.autoArtifactReview.analysis` do not. See [Workflow preferences in the Configuration guide](configuration.md#workflow-preferences-workflow) for full descriptions, surface guidance, and cross-repo foot-gun examples.

package/assets/docs/{cli-utilities → reference}/config-and-local-state.md

@@ -24,7 +24,7 @@ Backlog IDs are deterministic date+slug identifiers (`BL-YYMMDD-slug`) derived f
 
 Run `oat backlog init` directly when you need to create or repair only the backlog scaffold. `oat backlog new` initializes a missing scaffold automatically after validating its inputs. This command group is primarily used by the `oat-pjm-*` project-management skills, but it is also available directly when you need to inspect or repair backlog metadata by hand.
 
-For the end-to-end states an item moves through — and how `oat backlog archive` and `oat pjm doctor` keep the backlog honest — see [Backlog Lifecycle](backlog-lifecycle.md).
+For the end-to-end states an item moves through — and how `oat backlog archive` and `oat pjm doctor` keep the backlog honest — see [Backlog Lifecycle](../workflows/backlog-and-planning/backlog-lifecycle.md).
 
 ### `oat backlog new`
 
@@ -83,7 +83,7 @@ On success the payload is the archive result object:
 
 `result` is `archived` or `noop` (already archived); `completedEntry` is `written`, `scaffolded`, or `skipped` (e.g. a `wont_do` archive without `--summary`); `movedTo` is the destination path or `null`; `rewrittenReferences` lists the repository-relative Markdown files whose references to the moved item were rewritten (on a no-op this lists anything the retried rewrite changed, and the human output prints each file on both paths). On an actionable failure the payload is `{ "result": "error", "id": "<id>", "message": "<why + fix>" }`.
 
-For full project-management repo-reference setup, use [`oat pjm init`](tool-packs.md#install-vs-initialize). It scaffolds the two-layer PJM surface (`pjm/current-state.md`, `pjm/roadmap.md`, `reference/decisions/`, and AGENTS guides) and delegates the backlog sub-surface to `oat backlog init`.
+For full project-management repo-reference setup, use [`oat pjm init`](../getting-started/tool-packs.md#install-vs-initialize). It scaffolds the two-layer PJM surface (`pjm/current-state.md`, `pjm/roadmap.md`, `reference/decisions/`, and AGENTS guides) and delegates the backlog sub-surface to `oat backlog init`.
 
 ## `oat decision ...`
 
@@ -98,7 +98,7 @@ Pass `--context`, `--decision`, and `--consequences` together when creating a re
 
 The decision index uses managed marker pairs and is deterministic, so an index merge conflict can be resolved by re-running `oat decision regenerate-index` and staging the result. Decision records replace the legacy single `decision-record.md`; repos still on the old layout migrate with `oat decision migrate` (or the broader `oat pjm migrate`).
 
-`oat decision init` is the lightweight standalone setup path. It does not require the `project-management` tool pack and does not create current state, roadmap, or backlog artifacts. It is also not an alternate adoption path for the broader PJM surface: repository PJM mutations still require `oat pjm init`, and `oat decision` mutations fail closed with that recovery when the repository has not adopted PJM. Its AGENTS guidance uses `oat decision` directly while also recognizing `oat-pjm-decision` when that optional skill is installed later.
+`oat decision init` is a lightweight decision-scaffold path after repository PJM adoption. It does not require the `project-management` tool pack and does not itself create current state, roadmap, or backlog artifacts. It is not an alternate adoption path: `oat decision` mutations, including init, fail closed with `oat pjm init` as the recovery when the repository has not adopted PJM. Its AGENTS guidance uses `oat decision` directly while also recognizing `oat-pjm-decision` when that optional skill is installed later.
 
 ## `oat local ...`
 
@@ -123,8 +123,8 @@ Use this when you want archived review history or idea scratchpads to persist lo
 Use `oat config` for repo runtime config inspection and supported key mutation.
 
 - `oat config get <key>` - read one resolved config value
-- `oat config set <key> <value>` - update a supported shared or repo-local key
-- `oat config unset <key>` - remove a supported key from one surface, with the same `--shared`/`--local`/`--user` flags and per-key restrictions as `set`. Pruning removes any parent object the removal empties, and the resolved value falls back to the next surface or the built-in default. A key the surface does not hold reports an already-unset outcome and exits 0; `--json` adds a `removed` boolean that distinguishes that no-op from a real removal. Five classes are refused with exit 1: unknown keys (including the uncatalogued `documentation.index`), lifecycle state (`activeProject`, `lastPausedProject`, cleared with `oat config set <key> ''`), pack intent (`tools.*`, removed with `oat tools remove --pack <pack> --scope project`), the aggregate read views `workflow.dispatchCeiling` and `workflow.dispatchCeiling.providers`, and environment-shadowed keys with nothing stored on the target surface. See [CLI Reference](../reference/cli-reference.md#oat-config-surface-flags) for the full contract
+- `oat config set <key> <value>` - update a supported shared, repo-local, or user key according to per-key restrictions
+- `oat config unset <key>` - remove a supported key from one surface, with the same `--shared`/`--local`/`--user` flags and per-key restrictions as `set`. Pruning removes any parent object the removal empties, and the resolved value falls back to the next surface or the built-in default. A key the surface does not hold reports an already-unset outcome and exits 0; `--json` adds a `removed` boolean that distinguishes that no-op from a real removal. Five classes are refused with exit 1: unknown keys (including the uncatalogued `documentation.index`), lifecycle state (`activeProject`, `lastPausedProject`, cleared with `oat config set <key> ''`), pack intent (`tools.*`, removed with `oat tools remove --pack <pack> --scope project`), the aggregate read views `workflow.dispatchCeiling` and `workflow.dispatchCeiling.providers`, and environment-shadowed keys with nothing stored on the target surface. See [CLI Reference](cli-reference.md#oat-config-surface-flags) for the full contract
 - `oat config list` - show the resolved command-surface values with source information
 - `oat config dump --json` - emit the full merged config payload with per-key source attribution, suitable for automation and debugging
 - `oat config describe` - list supported config surfaces and keys across shared repo, repo-local, user, and sync/provider config
@@ -207,7 +207,7 @@ repository whose PJM capability lives at user scope is still diagnosed
 correctly. A repository that never adopted PJM reports adoption state `none`
 with `oat pjm init` as the recovery instead of treating absent
 `.oat/repo/pjm/` files as drift. See
-[Install vs. initialize](tool-packs.md#install-vs-initialize).
+[Install vs. initialize](../getting-started/tool-packs.md#install-vs-initialize).
 
 Workflow automation preferences are also visible through `oat config` and can be set at local, shared, or user scope. Notable review-loop keys:
 
@@ -250,12 +250,12 @@ target when available, and exits with the child process status. Target commands
 are stored as JSON argv arrays, so configure them with
 `oat gate target set --base-command-json ...` rather than `oat config set`.
 
-For schema, examples, and current V1 limits, see [Workflow Gates](workflow-gates.md).
+For schema, examples, and current V1 limits, see [Workflow Gates](../workflows/advanced/workflow-gates.md).
 
 Use these reference pages for file ownership and schema details:
 
-- [File Locations](../reference/file-locations.md)
-- [`.oat` Directory Structure](../reference/oat-directory-structure.md)
+- [File Locations](file-locations.md)
+- [`.oat` Directory Structure](oat-directory-structure.md)
 - [Sync Config (`.oat/sync/config.json`)](../provider-sync/config.md)
 
 ## `oat instructions ...`
@@ -291,3 +291,19 @@ For the full state model, repair semantics, and examples, see [Instruction Sync]
 `oat doctor` is the quickest way to confirm that your runtime, directory structure, and installed OAT assets are healthy before deeper debugging. At project scope it also scans bounded repository script and documentation surfaces for known-stale CLI grammar, such as `oat --scope all sync` <!-- oat-doctor: allow-stale-invocation -->, and reports file/line evidence plus the current `oat sync --scope all` form. Generated provider views, OAT lifecycle artifacts, archived content, dependencies, build output, and nested worktrees are excluded.
 
 The `/oat-doctor` skill (installed via the core pack) goes further: it sweeps config, project management (PJM), agent instructions, docs, and installed tools read-only, prints one report grouped by area and severity, and then dives into any area you pick, teaching from the bundled documentation and the `oat config describe` entries and offering the exact fix command or the owning skill. It applies nothing except a single fix command you approve. Unattended (`OAT_NON_INTERACTIVE=1`), the report is the whole output; `--summary` keeps the installed-tools dashboard.
+
+## Choose before writing configuration
+
+Before you set a team default or a personal override, decide which config layer
+should hold it: shared (committed for the team), local (this checkout only), or
+user (you, in every repository). [Choosing a config layer](configuration.md#choosing-a-config-layer)
+explains the tradeoffs. Run `oat config describe <key>` to see where a key lives
+and which command sets it, and `oat config dump --json` to see which file the
+current value actually comes from. The value you see may come from a different
+file than the one you would edit.
+
+- If a personal preference seems to be ignored, check where the effective value
+  comes from before changing it again: a shared value overrides your user value.
+- If you are rolling out a team policy, set a key that shared config supports
+  and review the resulting diff, rather than relying on a value that exists only
+  in your own checkout or home directory.