@open-agent-toolkit/cli 0.2.25 → 0.2.27

package/assets/NOTICES.md

@@ -0,0 +1,156 @@
+# NOTICES
+
+This file records attribution for externally-sourced prose incorporated
+into this repository. When you adapt or lift prose from an external
+project into a skill, template, or doc, add an entry here — do not
+add attribution footers to the skill files themselves.
+
+## Obra Superpowers
+
+**Source:** https://github.com/obra/superpowers
+**License:** MIT
+**Version referenced:** 5.0.7
+
+### `brainstorming` skill
+
+Source file: `skills/brainstorming/SKILL.md`
+
+Passages adapted or lifted verbatim into OAT:
+
+- "Exploring approaches" (4 lines) — used in `oat-project-design` Component 3.5 (approach reaffirmation)
+- "Presenting the design" (5 lines) — used in `oat-project-design` Component 4 (section iterator)
+- "Design for isolation and clarity" (4 lines) — used as a principle in `oat-project-design`
+- Self-review four-check template — used in `oat-project-design` Component 6
+- User-review gate phrasing — used in `oat-project-design` Component 7
+
+Consumer OAT skills: `oat-project-design`, `oat-project-quick-start`
+(via lightweight-design mode choice inheriting the same prose).
+
+### Upstream MIT license
+
+```text
+MIT License
+
+Copyright (c) 2025 Jesse Vincent
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+### `brainstorming` skill — visual companion
+
+Source files: `skills/brainstorming/scripts/{server.cjs, start-server.sh,
+  stop-server.sh, frame-template.html, helper.js}` and
+`skills/brainstorming/visual-companion.md`.
+
+Files lifted into OAT (under `.agents/skills/oat-brainstorm/`):
+
+- `scripts/server.cjs`, `scripts/stop-server.sh`, `scripts/frame-template.html`,
+  `scripts/helper.js` — verbatim from upstream.
+- `scripts/start-server.sh` — verbatim except for default persistence-path
+  changes (`.superpowers/brainstorm/` → OAT-managed prefixes:
+  `<project>/.oat/brainstorm/`, `<repo-root>/.oat/brainstorm/`,
+  `~/.oat/brainstorm/`).
+- `references/visual-companion.md` — adapted prose: persistence paths and
+  example invocations updated to OAT conventions.
+
+Consumer OAT skills: `oat-brainstorm`.
+
+## shadcn/improve
+
+**Source:** https://github.com/shadcn/improve/tree/main/skills/improve
+**License:** MIT
+**Version referenced:** `main` (retrieved 2026-07-12)
+
+### `improve` skill
+
+Source files: `skills/improve/SKILL.md` and
+`skills/improve/references/{audit-playbook.md,closing-the-loop.md,plan-template.md}`.
+
+Files copied into `.agents/skills/oat-repo-improve/`; the skill identifier,
+heading, invocation examples, and generated-plan attribution were renamed for
+the OAT repository namespace.
+
+### Upstream MIT license
+
+```text
+MIT License
+
+Copyright (c) 2026 shadcn
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```
+
+## visual-explainer
+
+**Source:** https://github.com/nicobailon/visual-explainer
+**License:** MIT
+**Version referenced:** 0.8.1
+
+### Explainer templates and render QA
+
+Visual presentation and QA patterns were adapted into
+`.agents/skills/explainer-kit/`, including self-contained HTML shells,
+responsive navigation, slide-deck interaction and print behavior, overflow
+containment, reduced-motion handling, and structural/render checks.
+
+The OAT implementation replaces upstream branding, destinations, invocation
+commands, and example content with destination-neutral contracts, themes,
+templates, and fixtures. Consumer OAT skill: `explainer-kit`.
+
+### Upstream MIT license
+
+```text
+MIT License
+
+Copyright (c) 2025 Nico Bailon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+```

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

@@ -308,6 +308,15 @@ Adoption fills missing provider/tier cells and preserves explicit existing
 values. Planning shows the complete bundled recommendation before asking for
 this scope, then rechecks the effective ladder. If explicit cells still leave
 the ladder incomplete, readiness blocks; OAT does not overwrite them.
+`workflow.dispatchCeiling.recommendationVersion` describes only the bundled
+recommendation that was adopted. Dispatch targets, structured notices, and
+runtime disclosure come from the effective ladder after explicit cells have
+been preserved.
+
+A recommended Fable target may require model access from the executing
+provider. The adopting organization is responsible for confirming its
+applicable retention policy. OAT does not determine model access or
+organizational retention eligibility.
 
 Scope determines ownership and Codex/Cursor materialization:
 
@@ -366,13 +375,13 @@ tiers are trimmed for readability.
 
 The bundled recommendation covers 13 Codex model/effort combinations: Luna and
 Terra at `low`, `medium`, `high`, and `xhigh`, plus Sol at those efforts and
-`max`. Claude covers `haiku`, `sonnet`, `opus`, and `fable`. Cursor covers 16
-candidates across four tiers, drawn from a materialization catalogue of 18
-verified multi-family flat IDs spanning Composer, Claude (Sonnet, Opus, and
-Fable), GPT, and Grok; the two figures differ because some approved mappings
-stay materializable without being recommended. An explicit mapping connects
-each flat ladder ID to a separate bracket-form frontmatter model; configuration
-and skills never derive or normalize either form.
+`max`. Claude covers `haiku`, `sonnet`, `opus`, and `fable`. The recommendation
+carries 14 Cursor candidates across four tiers, drawn from a materialization
+catalogue with 18 catalogued multi-family flat IDs spanning Composer, Claude
+(Sonnet, Opus, and Fable), GPT, and Grok; the two figures differ because some
+approved mappings stay materializable without being recommended. An explicit
+mapping connects each flat ladder ID to a separate bracket-form frontmatter
+model; configuration and skills never derive or normalize either form.
 
 The corresponding pinned Codex variant catalogue includes
 `gpt-5.6-luna-high`, `gpt-5.6-terra-xhigh`, `gpt-5.6-sol-high`, and
@@ -432,6 +441,10 @@ oat project dispatch-ceiling resolve \
   --ceiling-tier high \
   --candidate-model gpt-5.6-terra \
   --candidate-effort medium \
+  --task-class default-implementation \
+  --task-effort medium \
+  --report-scope p02 \
+  --report-action implementation \
   --json
 
 oat project dispatch-ceiling resolve \
@@ -439,6 +452,9 @@ oat project dispatch-ceiling resolve \
   --role implementer \
   --ceiling-tier high \
   --candidate-model sonnet \
+  --task-class default-implementation \
+  --report-scope p02 \
+  --report-action implementation \
   --json
 
 oat project dispatch-ceiling resolve \
@@ -446,19 +462,34 @@ oat project dispatch-ceiling resolve \
   --role implementer \
   --ceiling-tier high \
   --candidate-model gpt-5.6-sol-high \
+  --task-class default-implementation \
+  --report-scope p02 \
+  --report-action implementation \
   --json
 ```
 
+Use the same classification flags and `--report-action fix` for bounded fixes.
+Reviewer routes carry neither `--task-class` nor `--task-effort`; the CLI
+rejects classification flags for reviewers. Before any implementation, fix, or
+reviewer launch, display `dispatchReport.notices` and the formatted report. The
+effective resolver target—not the recommendation version—owns runtime
+disclosure.
+
 `--ceiling-tier` is invocation-only. It accepts `economy`, `balanced`, `high`,
 or `frontier`, overrides layered active-policy ceilings for that call, and never
 writes user, shared, local, or project configuration. JSON reports top-level
 `source: invocation`; `providers.<provider>.cellSource` still identifies the
 config layer that owns the selected candidate.
 
-The resolver fails closed when a candidate is missing, above the maximum,
-ambiguous, malformed, or cannot compile exact provider controls. `--preferred`
-remains compatibility behavior for legacy scalar ceilings and managed
-`Uncapped`; it is not the exact managed phase-agent path.
+The resolver fails closed when a requested candidate is above the maximum,
+ambiguous, malformed, or cannot compile exact provider controls. Omitting an
+exact candidate from a managed named-cap implementation or fix currently
+preserves compatibility by resolving successfully at the cap; with report
+context, human and JSON output include the
+`managed-capped-selection-skipped` warning. Callers must surface that warning
+and select an exact candidate before launch. `--preferred` remains
+compatibility behavior for legacy scalar ceilings and managed `Uncapped`; it is
+not the exact managed phase-agent path.
 
 ### Provider enforcement and materialization
 

package/assets/docs/contributing/explainer-kit-verification.md

@@ -0,0 +1,125 @@
+---
+title: Verifying Explainer Kit
+description: 'Maintainer runbook for semantic golden cases, temporary real-Chromium evidence, and release validation.'
+---
+
+# Verifying Explainer Kit
+
+Explainer Kit uses portable behavioral goldens and a real-browser release gate.
+The goal is not pixel identity: output may change markup, spacing, and
+composition when it preserves the same meaning, topology, interactions, and
+evidence quality.
+
+## Golden cases
+
+The suite under
+`.agents/skills/explainer-kit/tests/fixtures/golden/` contains three
+portable semantic cases:
+
+| Case                           | What it proves                                             |
+| ------------------------------ | ---------------------------------------------------------- |
+| `simple`                       | Viewport-sized lead evidence and a cohesive baseline recap |
+| `non-linear`                   | Exact branch, fan-in, and cycle preservation               |
+| `explainer-authoring-redesign` | Archive-only rebuild from a dense completed project record |
+
+Every case retains only its descriptor, source input, and content-addressed
+source record. The three cases share one rubric. Generated artifacts, browser
+evidence, screenshots, manifests, catalogs, and review results stay in a
+temporary test directory and are never committed. Paths are
+repository-relative; machine roots, home-relative paths, `file://` URLs,
+Windows drive paths, and UNC paths are rejected.
+
+## Prerequisites
+
+- Install workspace dependencies.
+- Ensure the repository-supported Chromium runtime is installed and launchable.
+- Run from the repository root.
+
+The end-to-end benchmarks require an actual launched Chromium session. A
+deterministic fixture session is valid only for bounded unit/integration tests
+and cannot satisfy a golden production path.
+
+## Run the golden suite
+
+```bash
+node --test \
+  .agents/skills/explainer-kit/tests/golden-conformance.test.mjs
+```
+
+A passing run proves:
+
+- one planner-owned hub, architecture view, and deck;
+- source and terminology cohesion;
+- exact topology and catalog parity;
+- mobile, tablet, and desktop Chromium evidence;
+- one independent critic invocation; and
+- a passing terminal review without correction.
+
+The focused integration suites below separately exercise the one-correction
+ceiling.
+
+The suite recomputes semantic-input hashes, grounds every claim in retained
+source evidence, and evaluates the shared rubric against live runtime output.
+A prose claim or status label without runtime proof does not pass.
+
+## Inspect generated evidence
+
+The suite materializes each case's runtime package under its temporary working
+directory, validates it, and removes it at test completion. Add a local
+debugger breakpoint or temporarily disable cleanup when diagnosing a failure;
+do not add generated runtime output to the fixture directories.
+
+## Focused integrity suites
+
+Use these when changing browser identity, immutable evidence, resume, or archive
+contracts:
+
+```bash
+node --test \
+  .agents/skills/explainer-kit/tests/records.test.mjs \
+  .agents/skills/explainer-kit/tests/run.integration.test.mjs
+
+node --test \
+  .agents/skills/explainer-kit/tests/browser-runtime.test.mjs \
+  .agents/skills/explainer-kit/tests/qa.test.mjs \
+  .agents/skills/explainer-kit/tests/contracts.test.mjs \
+  .agents/skills/explainer-kit/tests/durability.test.mjs \
+  .agents/skills/explainer-kit/tests/rebuildability.test.mjs
+
+pnpm --filter @open-agent-toolkit/cli exec vitest run \
+  src/commands/project/archive/archive-utils.test.ts \
+  src/release/public-package-contract.test.ts
+
+node --test tools/smoke/explainer-kit/*.test.mjs
+```
+
+## Release gate
+
+The required publishable-package gate is:
+
+```bash
+pnpm release:validate
+```
+
+It validates all five lockstep public package tarballs and then runs the bounded
+curated-style/template matrix in real Chromium. The visual gate retains 65
+machine-readable viewport, clipping, motion, keyboard, no-JavaScript, and print
+measurements. Missing Chromium or untrusted retained evidence fails closed.
+
+For the full repository closeout, also run the standard checks documented in
+the root `AGENTS.md`:
+
+```bash
+pnpm check
+pnpm type-check
+pnpm test
+pnpm build
+pnpm lint
+pnpm format
+pnpm build:docs
+git diff --check
+```
+
+Do not treat an isolated transient timeout as a product pass or failure without
+reproducing the failing test. Preserve the exact-head successful rerun evidence
+used for release closure.

package/assets/docs/contributing/index.md

@@ -17,4 +17,5 @@ Use this section when you are changing OAT itself rather than consuming it as a
 - [Commit Conventions](commit-conventions.md) - Traceable commit patterns for project and docs work.
 - [Hooks and Safety](hooks-and-safety.md) - Safety and mutation contracts for provider-sync behavior.
 - [Smoke Testing](smoke-testing.md) - Runbook for the live workflow smoke runner: prerequisites, scenarios, evidence reports, and recovery.
+- [Verifying Explainer Kit](explainer-kit-verification.md) - Golden recap cases, real-Chromium evidence, fixture regeneration, and release validation.
 - [Verifying Cursor Pins](verifying-cursor-pins.md) - Runbook for probe-verifying a Cursor model pin before shipping it.

package/assets/docs/reference/troubleshooting.md

@@ -113,9 +113,56 @@ oat tools has <pack> --scope user
 - Reconcile `state.md`, `plan.md` review table, and `implementation.md`.
 - Ensure phase/review status has been updated after reviews and fix cycles.
 
+## An Explainer Kit recap ends as `built-needs-review`
+
+`built-needs-review` means the required unattended visual-review chain did not
+reach a valid `pass`. The run retains available output for diagnosis, but OAT
+will not finalize, archive, attest, publish, or push it as a successful recap.
+Do not bypass the review gate by copying the package into a durable location.
+
+Inspect:
+
+1. `build-record.json` and `manifest.json` for the terminal outcome and warning.
+2. `qa/browser/` for all required mobile, tablet, and desktop PNG/metrics pairs.
+3. `qa/visual-review/attempt-*/request.json` and `result.json` for request
+   binding, critic disposition, and findings.
+4. `qa/visual-review/revision.json` when a correction was requested.
+5. Adapter logs for missing or invalid `browserSession`, `visualCritic`, or
+   correction-provider modules.
+
+Common causes include unavailable Chromium, a fixture or unbranded session,
+missing screenshots, invalid decoded PNG dimensions, runtime/capture identity
+drift, critic exceptions, evidence mutation, `fail`, and an unresolved
+correction. Fix the provider or artifact problem and rebuild the recap; partial
+evidence is diagnostic only.
+
+See
+[Explainer Provider Integration](../workflows/skills/explainer-kit-providers.md)
+for the trusted-session and critic contracts.
+
+## Explainer Kit resume fails with `E_APPROVAL_RESUME`
+
+Interactive resume is same-request only. Keep the opaque `ekrt2` token returned
+as `approval.resumeToken` outside the package and provide it as
+`reviewedSource.resumeToken` with the complete original request.
+
+The error is expected when:
+
+- the token is missing, malformed, or not `ekrt2`;
+- the configured output root or retained run root moved;
+- `run-request.json` or a retained set-plan record changed;
+- the current request differs in source binding, recipe, mode, theme, render
+  strategy, privacy, public URL, durability, or publish destination; or
+- the package contains a legacy `ekrt1` token.
+
+Do not edit retained files or weaken the current request to force a match.
+Restore the exact original request and package bytes. Legacy paused runs cannot
+be upgraded in place; restart them to receive an authenticated `ekrt2` token.
+
 ## Reference artifacts
 
 - `.oat/projects/<scope>/<project>/implementation.md`
 - `.oat/projects/<scope>/<project>/reviews/`
+- `.oat/projects/<scope>/<project>/explainers/<slug>/qa/`
 - `packages/cli/src/commands/doctor/index.ts`
 - `packages/cli/src/commands/instructions/`

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

@@ -57,12 +57,30 @@ The archive exports at most one selected recap package. It preserves structured
 failure outcomes and successful intermediates, rejects an existing dated
 destination, and requires the selected path to stay under the project's
 `explainers/` directory with a `project-recap` manifest. Verification covers
-the exact retained bytes for the privacy-safe request, content approval, fact
-base JSON and Markdown, declared author results, authored content, resolved
-theme, and every built artifact. Canonical fact-base and theme hashes remain
-normalized-object identities; `manifest.immutableHashes` independently covers
-serialized file bytes. Missing, stale, or tampered coverage fails before the
-active project is deleted.
+the complete mode-aware package:
+
+- privacy-safe request and content approval;
+- fact-base JSON and Markdown;
+- the five immutable set-plan records and authored drafts;
+- declared author results and authored content;
+- resolved theme and every built artifact;
+- canonical mobile, tablet, and desktop screenshots;
+- paired `browser-evidence/v2` metrics with launched Chromium name, version,
+  and capture identity;
+- cohesion observations and each visual-review request/result; and
+- the bounded revision record when a correction occurred.
+
+Canonical object hashes identify normalized fact-base, theme, runtime, and
+capture objects; `manifest.immutableHashes` independently covers serialized file
+bytes. The archive requires one complete, internally consistent browser and
+review chain for a successful unattended recap. Missing, stale, forged,
+cross-record-mismatched, or tampered coverage fails before the active project is
+deleted.
+
+`built-needs-review` is a terminal review-gate outcome, not a non-durable
+success. Its partial evidence remains available for diagnosis, but it cannot be
+finalized, exported, attested, archived, or pushed. Review and rebuild the recap
+to a passing visual-review outcome first.
 
 Local-scope projects are not archived through this export path. Their explainer
 packages inherit the local project's untracked posture and remain

package/assets/docs/workflows/projects/dispatch-ceiling.md

@@ -63,6 +63,10 @@ Adoption fills missing provider/tier cells and records
 existing cells. Planning shows the complete recommendation before asking which
 scope should own it. If the resulting ladder is still missing or incomplete,
 planning remains blocked rather than replacing the user's explicit values.
+The recommendation version describes only the bundled recommendation. After
+preserving existing cells, OAT resolves the effective ladder and uses that
+effective result—not the recommendation version—for dispatch targets and
+runtime disclosure.
 
 ### Upgrading to a newer recommendation version
 
@@ -91,6 +95,12 @@ does not compare the two rungs. Both models remain in the pin catalog and stay
 available to a hand-edited ladder. An adopter still on the prior version keeps their existing
 Cursor tiers untouched until they take one of the actions above.
 
+The terminal Fable target may require model access from the executing provider.
+The adopting organization is responsible for confirming its applicable
+retention policy. OAT does not determine model access or organizational
+retention eligibility; recommendation membership and catalogue presence are
+configuration data, not an eligibility decision.
+
 The terminal entries in that version are chosen, not incidental. Because the
 final candidate in a tier is the target its implementation-phase self-review
 pins, reordering a tier changes who reviews it even when the membership is
@@ -274,6 +284,10 @@ oat project dispatch-ceiling resolve \
   --ceiling-tier high \
   --candidate-model gpt-5.6-terra \
   --candidate-effort medium \
+  --task-class default-implementation \
+  --task-effort medium \
+  --report-scope p02 \
+  --report-action implementation \
   --json
 
 # Claude: exact model argument
@@ -282,6 +296,9 @@ oat project dispatch-ceiling resolve \
   --role implementer \
   --ceiling-tier high \
   --candidate-model sonnet \
+  --task-class default-implementation \
+  --report-scope p02 \
+  --report-action implementation \
   --json
 
 # Cursor: exact opaque configured string
@@ -290,9 +307,16 @@ oat project dispatch-ceiling resolve \
   --role implementer \
   --ceiling-tier high \
   --candidate-model gpt-5.6-sol-high \
+  --task-class default-implementation \
+  --report-scope p02 \
+  --report-action implementation \
   --json
 ```
 
+Use the same classification flags and `--report-action fix` for a bounded fix.
+Reviewer routes use neither `--task-class` nor `--task-effort`; the CLI rejects
+classification flags for reviewers.
+
 `--ceiling-tier` accepts `economy`, `balanced`, `high`, or `frontier`. It
 overrides a layered active-policy ceiling for that resolver invocation only. It
 does not modify user, shared, local, or project configuration.
@@ -306,10 +330,14 @@ Successful JSON reports:
   `selection.requestedCandidate`
 - the exact provider-specific `dispatchArgs`
 
-The resolver rejects a missing candidate, an above-ceiling candidate, an
-ambiguous route, malformed ordering, a reviewer candidate request, or controls
-that cannot compile exactly. The root blocks instead of reusing its own target,
-a base role, or a provider default.
+The resolver rejects an above-ceiling candidate, an ambiguous route, malformed
+ordering, a reviewer candidate request, or controls that cannot compile
+exactly. For compatibility, omitting an exact candidate from a managed
+named-cap implementation or fix still resolves successfully at the cap. When
+report context is present, that path emits the coded
+`managed-capped-selection-skipped` warning in human and JSON output. The root
+must treat the warning as a dispatch-policy violation and select an exact
+candidate before launch even though the command retains exit code `0`.
 
 Implementer and fix resolution has two mutually exclusive selection branches:
 
@@ -411,20 +439,38 @@ write authority. See
 
 Resolver calls that pass `--report-scope` and `--report-action` include a
 `dispatchReport` object in JSON output. Consumers must require
-`dispatchReport.schemaVersion: 1` before dispatch. The report keeps four
-different decisions separate:
-
-| Report area                                                         | What it means                                                        |
-| ------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `policy`                                                            | The resolved managed/inherit policy, its status, name, and source    |
-| `selection.ceilingTier` / `selection.ceilingTarget`                 | The maximum allowed tier and its boundary target                     |
-| `selection.requestedCandidate` / `candidateTier` / `candidateIndex` | The exact candidate requested for this bounded task and its position |
-| `selection.exactSelectedTarget` / `route.target`                    | The compiled provider target and actual invocation route             |
+`dispatchReport.schemaVersion: 1` before dispatch. The report keeps these
+concerns separate:
+
+| Report area                                                         | What it means                                                                                 |
+| ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `policy`                                                            | The resolved managed/inherit policy, its status, name, and source                             |
+| `selection.ceilingTier` / `selection.ceilingTarget`                 | The maximum allowed tier and its boundary target                                              |
+| `selection.requestedCandidate` / `candidateTier` / `candidateIndex` | The exact candidate requested for this bounded task and its position                          |
+| `selection.preferredValue`                                          | The legacy `--preferred` selection value, or `null` when that compatibility path was not used |
+| `selection.exactSelectedTarget` / `route.target`                    | The compiled provider target and actual invocation route                                      |
+| `classification`                                                    | Caller-reported task class, applicable Codex preferred effort, and provenance source          |
+| `notices`                                                           | Ordered coded warnings and advisories derived from the effective dispatch context             |
 
 A named policy or ceiling is never a substitute for the requested candidate or
-exact selected target. `requestedControls` records what OAT put into the host
-payload. `configuredDefaults` records fallback configuration and is explicitly
-not a runtime observation.
+exact selected target. Classification is provenance only: it records the
+root's judgment but does not participate in candidate normalization or let OAT
+judge whether that classification was correct. `requestedControls` records
+what OAT put into the host payload. `configuredDefaults` records fallback
+configuration and is explicitly not a runtime observation.
+
+Managed named-cap implementation and fix reports can include two warning codes:
+
+- `managed-capped-selection-skipped` means no exact candidate or legacy
+  preferred value was supplied, so compatibility behavior selected the cap.
+- `managed-capped-classification-missing` means an exact candidate was supplied
+  without `--task-class`.
+
+Both warnings preserve resolved status and exit code `0`. They do not apply to
+policy-only preflight, reviewer, inherit, uncapped, unresolved, or
+legacy-preferred routes. `terminal-reviewer-eligibility` is an advisory tied to
+an effective Fable reviewer target, not proof of model access or organizational
+retention eligibility.
 
 `gateInvocation` is an immutable copy of configured gate controls.
 `runtimeIdentity` is separate and stays `not-reported` until independently
@@ -446,6 +492,11 @@ when OAT can establish it; otherwise it is `unknown`. `provenance` is
 `declared`, `observed`, `inferred`, or `unknown`. Selected model and effort axes
 can remain exact even when runtime producer identity is not reported.
 
+Before launching an implementation, fix, or reviewer, surface the structured
+notices in `dispatchReport.notices` and render the report. Structured notices
+and runtime disclosure use the effective target returned by that resolver call,
+never a target inferred from the bundled recommendation version.
+
 ## Legacy Compatibility
 
 The following remain readable during migration: