@open-agent-toolkit/cli 0.1.72 → 0.1.74

package/README.md

@@ -35,6 +35,7 @@ Additional useful entry points:
 - `oat config dump --json`
 - `oat project status --json`
 - `oat project list --json`
+- `oat project log --help`
 - `oat project complete-state /path/to/project`
 - `oat project archive /path/to/project`
 - `oat repo archive sync`

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

@@ -1,5 +1,5 @@
 {
-  "version": "2026-07-10.2",
+  "version": "2026-07-11.1",
   "providers": {
     "codex": {
       "economy": {
@@ -101,29 +101,25 @@
     "cursor": {
       "economy": {
         "candidates": [
-          "gpt-5.6-luna-low",
-          "gpt-5.6-luna-medium",
-          "gpt-5.6-luna-high"
+          "composer-2.5",
+          "claude-sonnet-5-high",
+          "gpt-5.6-luna-high",
+          "gpt-5.6-luna-xhigh"
         ]
       },
       "balanced": {
-        "candidates": [
-          "gpt-5.6-luna-xhigh",
-          "gpt-5.6-terra-low",
-          "gpt-5.6-terra-medium",
-          "gpt-5.6-terra-high",
-          "gpt-5.6-terra-xhigh"
-        ]
+        "candidates": ["cursor-grok-4.5-high", "gpt-5.6-terra-high"]
       },
       "high": {
-        "candidates": [
-          "gpt-5.6-sol-low",
-          "gpt-5.6-sol-medium",
-          "gpt-5.6-sol-high"
-        ]
+        "candidates": ["gpt-5.6-sol-medium", "gpt-5.6-sol-high"]
       },
       "frontier": {
-        "candidates": ["gpt-5.6-sol-xhigh", "gpt-5.6-sol-max"]
+        "candidates": [
+          "claude-fable-5-thinking-high",
+          "claude-fable-5-thinking-xhigh",
+          "gpt-5.6-sol-xhigh",
+          "gpt-5.6-sol-max"
+        ]
       }
     }
   }

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

@@ -232,14 +232,15 @@ 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.
 
-Scope determines ownership and Codex materialization:
+Scope determines ownership and Codex/Cursor materialization:
 
 - `--shared` and `--local` are project configuration sources. Their configured
-  Codex candidates materialize into the tracked project `.codex` view.
+  Codex and Cursor candidates materialize into the tracked project `.codex`
+  and `.cursor` views.
 - `--user` writes reusable personal defaults to `~/.oat/config.json`; those
-  Codex candidates materialize under `~/.codex`.
-- Active-project sparse candidates also materialize into the tracked project
-  view.
+  candidates materialize under `~/.codex` and `~/.cursor`.
+- Active-project sparse candidates also materialize into the applicable tracked
+  project view.
 
 Project-generated provider views remain visible to version control. OAT does
 not auto-ignore them. A project-specific active policy or ceiling must not be
@@ -274,7 +275,7 @@ even when the reusable ladder is user-owned.
         },
         "cursor": {
           "balanced": {
-            "candidates": ["opaque:model/lower [v1]", "opaque:model/high [v2]"]
+            "candidates": ["cursor-grok-4.5-high", "gpt-5.6-terra-high"]
           }
         }
       }
@@ -285,9 +286,11 @@ even when the reusable ladder is user-owned.
 
 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 13
-opaque configured strings. Cursor spelling never supplies capability metadata;
-the configured candidate position owns the tier meaning.
+`max`. Claude covers `haiku`, `sonnet`, `opus`, and `fable`. Cursor covers 12
+verified multi-family flat IDs across Composer, Claude, GPT, and Grok. 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
@@ -360,7 +363,7 @@ oat project dispatch-ceiling resolve \
   --provider cursor \
   --role implementer \
   --ceiling-tier high \
-  --candidate-model 'opaque:model/lower [v1]' \
+  --candidate-model gpt-5.6-sol-high \
   --json
 ```
 
@@ -381,11 +384,12 @@ remains compatibility behavior for legacy scalar ceilings and managed
 | -------- | ---------------------------------------------------------------------------------------------------- |
 | Codex    | `providers.codex.dispatchArgs.variant` as `agent_type`, or a fresh child pinned to model plus effort |
 | Claude   | `providers.claude.dispatchArgs.model` as the actual Agent `model`                                    |
-| Cursor   | `providers.cursor.dispatchArgs.model` byte-for-byte as the actual opaque invocation model            |
+| Cursor   | `providers.cursor.dispatchArgs.variant` as the exact native agent type first                         |
 
-Project sync materializes the supported Codex catalogue and every configured
-project-owned candidate for both `oat-phase-implementer` and `oat-reviewer`.
-User sync materializes user-owned candidates under `~/.codex`:
+Project sync materializes the supported Codex and Cursor catalogues and every
+configured project-owned candidate for both `oat-phase-implementer` and
+`oat-reviewer`. User sync materializes user-owned candidates under `~/.codex`
+and `~/.cursor/agents`:
 
 ```bash
 oat sync --scope project
@@ -394,60 +398,31 @@ oat sync --scope all
 ```
 
 Generated roles carry `supported-catalogue`, `project-config`, or `user-config`
-ownership. Cleanup reconciles only the current owner. Materialization is best
-effort at sync boundaries; the exact fresh-child route means workflow
-correctness does not require provider restart or hot reload.
+ownership. Cleanup reconciles only the current owner. Cursor's mapping registry
+rejects unknown flat IDs instead of writing unverified frontmatter.
 
 Reviewer resolution uses the final candidate at the configured review ceiling.
-Codex selects the exact reviewer variant; Claude and Cursor pass the resolver's
-exact model argument. Timeout retries preserve the same complete payload. A
-lower reviewer candidate requires a separate reviewed contract.
+Codex and Cursor select exact native reviewer variants; Claude passes the
+resolver's exact model argument. Timeout retries preserve the same complete
+payload. A lower reviewer candidate requires a separate reviewed contract.
 
 Tier 2 remains target-preserving. Inline review is permitted only when the host
 has verified equivalent current-host controls for explicit inherit,
 managed-uncapped, or base-role behavior. Capped managed reviews still require
 the exact registered role, pinned child, or resolver-returned model argument.
 
-### Cursor validation pass and live evidence
-
-Config adoption and doctor validate Cursor candidates with one command-scoped
-pass context. Duplicate references to the same byte-for-byte candidate share
-one Task/subagent probe. If a decisive probe is unavailable, the pass resolves
-the broad catalog once, with at most one `--list-models` fallback. The cache
-ends with that adopt or doctor command; it is not process-global and has no
-TTL.
-
-A correlated Task start/completion pair that preserves the exact model argument
-and returns the sentinel establishes that the argument is eligible for that
-account and client. A structured rejection or exact allow-list exclusion can
-establish `unknown-value`. Neither result identifies the backend runtime model:
-`runtimeIdentity` remains `not-reported` unless trusted Cursor telemetry or
-Cursor support confirms it. Parent prose and broad catalog presence are
-diagnostic-only, so OAT preserves `unvalidated` when launcher evidence is
-absent instead of inferring capability from candidate spelling.
-
-The [dated GPT-5.6 Cursor verification evidence](https://github.com/voxmedia/open-agent-toolkit/blob/main/.oat/repo/reference/project-summaries/20260711-cursor-gpt-5-6-subagent-verification.md)
-preserves the original text-mode pass and a versioned stream-JSON second pass.
-The second pass ran a dynamic positive control and deliberate invalid control
-before candidates. Both parent runs completed without a Task event, making the
-controls inconclusive; the stop rule therefore executed zero of the 13
-recommended candidates and did not execute exploratory
-`gpt-5.6-sol-high-fast`. The recommendation remains unchanged and candidate
-eligibility remains unresolved.
-
-The tracked artifact's structured second-pass block contains only allowlisted
-event structure, derived outcomes, sanitized auth-presence context, and
-non-reversible identifier hashes. Exact request/session/tool-call IDs and
-credential-redacted unprojected streams from that pass stay under gitignored
-`.oat/projects/local/` storage for possible Cursor support diagnosis.
-
-The same public artifact intentionally retains the sanitized historical v1
-text-mode record for provenance. That older section includes command arguments
-and prompts, stdout and stderr, exit and duration data, and capture-environment
-details such as user-specific binary paths; it is not limited to the structured
-second-pass allowlist. Re-run after a Cursor client rollout exposes Task in
-headless mode or Cursor support confirms the private requests; review the open
-verification item by 2026-08-08.
+### Cursor availability and evidence
+
+`oat doctor` compares configured Cursor flat IDs with the current Cursor
+catalogue and reports availability drift. This check is diagnostic: catalogue
+presence does not prove that a bracket-form definition pin was honored.
+
+Each shipped mapping has mapping-specific native-launch evidence, but Cursor
+can silently fallback when account, plan, or administration constraints prevent
+the requested pin. OAT therefore records the selected variant and mapped model
+with launcher-owned `configured` provenance. Runtime identity remains
+`not-reported` unless independently observed; self-report and catalogue
+availability do not upgrade that evidence.
 
 ### Legacy compatibility
 
@@ -486,6 +461,8 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `workflow.autoNarrowReReviewScope` — boolean. Auto-narrow re-review scope to fix-task commits only in `oat-project-review-provide`. When unset, the skill prompts.
 - `workflow.autoArtifactReview.plan` — boolean, default `true`. Automatically run the bounded artifact-review loop for generated `plan.md` files before implementation handoff. Set to `false` only when you intentionally want to skip the plan artifact review.
 - `workflow.autoArtifactReview.analysis` — boolean, default `true`. Automatically run the bounded accuracy-review loop for generated docs and agent-instructions analysis artifacts before the matching apply workflow consumes them.
+- `workflow.projectLog` — `auto`, `true`, or `false`; default `auto`. `auto` creates the append-only `project-log.md` on the first lifecycle append, `true` also enables scaffold-time creation, and `false` skips appends when no log exists. An existing artifact remains enabled regardless of the current setting.
+- `workflow.projectLogLedgerPath` — repository-relative string; default `.oat/repo/reference/project-observations.md`. Sets the durable ledger target for `general` judgments written by `oat project log rollup`.
 - `workflow.dispatchPolicy.mode` — `managed` or `inherit`. `managed` means OAT selects model/effort controls from `workflow.dispatchPolicy.policy`; `inherit` means OAT leaves controls to host/provider defaults.
 - `workflow.dispatchPolicy.policy` — `economy`, `balanced`, `high`, `frontier`, or `uncapped`. `economy` through `frontier` are capped managed policies; `uncapped` keeps OAT-managed preferred selection without provider caps. It is distinct from `workflow.dispatchPolicy.mode=inherit`, which leaves controls to the host/provider.
 - `workflow.dispatchCeiling.preset` — legacy compatibility alias (`balanced`, `maximum`, or `cost-conscious`) for capped managed policy setup.
@@ -495,6 +472,9 @@ Workflow preference keys live under the `workflow.*` namespace:
 - `workflow.gates.skills` / `workflow.gates.execTargets` — structured per-skill final gate commands and exec-target registry. Use `oat gate set`, `oat gate target set`, `oat gate review`, and `oat gate cross-provider-exec`; do not use `oat config set` for these objects.
 - `workflow.gateTimeouts.code` / `workflow.gateTimeouts.artifact` — validated default gate-review budgets in milliseconds. Both resolve through `local > shared > user`.
 
+The two project-log keys use the standard workflow precedence:
+`local > shared > user > default`.
+
 ### HiLL plan-field semantics
 
 `workflow.hillCheckpointDefault` controls the first implementation run's
@@ -568,6 +548,8 @@ oat config set workflow.designMode collaborative --shared
 oat config set workflow.dispatchCeiling.preset balanced --shared
 oat config set workflow.dispatchCeiling.providers.cursor.high composer-2.5 --shared
 oat config set workflow.autoArtifactReview.plan false --shared
+oat config set workflow.projectLog auto --shared
+oat config set workflow.projectLogLedgerPath .oat/repo/reference/project-observations.md --shared
 
 # Repo-local: personal override for this repo (default when no flag)
 oat config set workflow.hillCheckpointDefault every

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

@@ -15,6 +15,7 @@ Use this section when you want bootstrap guidance, tool-pack lifecycle details,
 - [Tool Packs and Installed Assets](tool-packs.md) - Bundled packs and `oat tools` lifecycle commands.
 - [Configuration](configuration.md) - OAT configuration guidance across shared, local, user, and provider-sync surfaces.
 - [Config and Local State](config-and-local-state.md) - Utility command groups for config, local state, diagnostics, and related inspection flows.
+- [Project Log](project-log.md) - Append-only project observations, synthesis, inspection, and durable roll-up.
 - [Backlog Lifecycle](backlog-lifecycle.md) - Backlog item states, atomic close-out with `oat backlog archive`, and lifecycle drift detection in `oat pjm doctor`.
 - [Workflow Gates](workflow-gates.md) - Completion-safe headless reviews, budgets, liveness evidence, and cross-runtime dispatch with `oat gate`.
 

package/assets/docs/cli-utilities/project-log.md

@@ -0,0 +1,183 @@
+---
+title: Project Log
+description: Capture append-only project observations and roll them into durable summary and ledger surfaces.
+---
+
+# Project Log
+
+`oat project log` manages an optional, append-only `project-log.md` artifact for
+workflow observations and lifecycle events. Use it to preserve evidence that
+would otherwise remain in agent transcripts, then roll that evidence into
+tracked project and repository references before archiving the project.
+
+The command group is the only supported writer for the artifact. Do not edit
+entries or the synthesis section by hand.
+
+## Configure project logs
+
+Two workflow keys control the feature:
+
+| Key                             | Values                   | Default                                       |
+| ------------------------------- | ------------------------ | --------------------------------------------- |
+| `workflow.projectLog`           | `auto`, `true`, `false`  | `auto`                                        |
+| `workflow.projectLogLedgerPath` | repository-relative path | `.oat/repo/reference/project-observations.md` |
+
+```bash
+oat config set workflow.projectLog auto --shared
+oat config set workflow.projectLogLedgerPath .oat/repo/reference/project-observations.md --shared
+```
+
+`auto` creates the log on the first append. `true` also lets
+`oat project new` scaffold the log up front. `false` skips an append when no log
+exists. An existing `project-log.md` always accepts appends, regardless of the
+current config value.
+
+For one scaffold operation, `oat project new --with-project-log` forces
+creation and `--no-project-log` suppresses it.
+
+## Append entries
+
+Judgment entries capture evidence about the project or reusable workflow:
+
+```bash
+oat project log append \
+  --project .oat/projects/shared/example \
+  --type friction \
+  --scope project \
+  --area "gate review handoff" \
+  --body "The gate passed but the handoff was missing, so review receipt stopped."
+```
+
+Judgment flags:
+
+- `--type <bug|friction|worked-well|feedback>`
+- `--scope <project|general>`
+- `--area <text>` — one line, at most 120 characters
+- `--body <text>` — use `--body -` to read from stdin
+- `--version-note <text>` — adds an `observed on` clause
+- `--project <path>` — optional when an active project resolves
+
+Structural entries record lifecycle events without duplicating larger
+artifacts:
+
+```bash
+oat project log append \
+  --structural \
+  --producer oat-project-implement \
+  --ref p03 \
+  --body "Phase passed; details: .oat/projects/shared/example/implementation.md#run-3"
+```
+
+Structural entries require `--structural`, `--producer`, `--ref`, and `--body`.
+Do not combine structural flags with judgment flags.
+
+The helper produces these heading grammars in UTC:
+
+```text
+### YYYY-MM-DD · <project|general> · <bug|friction|worked-well|feedback> · <area>
+### YYYY-MM-DD · structural · <producer> · <ref>
+```
+
+Prior entries are never edited or struck through. Append corrections as new
+judgments that reference the original heading. Never record secret values such
+as tokens, credentials, keys, or signed URLs; reference their name or source
+instead.
+
+Run `oat project log append --help` for the complete entry contract.
+
+## Automatic workflow integration
+
+When project logging is enabled, OAT lifecycle surfaces append structural
+entries without asking agents to edit `project-log.md`:
+
+- `oat-project-implement` records accepted subagent dispatches, STOP or park
+  events, phase outcomes, and parallel-group merge results. These entries point
+  to the corresponding `implementation.md` record instead of copying it.
+- `oat gate review` records exactly one entry for every terminal outcome,
+  including successful and blocking verdicts, child failure, timeout,
+  targeting-correlation failure, and artifact-validation failure. A log append
+  failure produces a warning but never changes the gate result.
+- `oat-project-summary` checks for entries, offers append-only promotion of
+  reusable project judgments, and invokes `rollup` after authoring
+  `summary.md`.
+- `oat-project-complete` warns when synthesis is pending, requires a successful
+  roll-up for a populated log, and appends the final seal entry before archive.
+  No project-log entry may follow the seal.
+
+With the default `auto` setting, the first of these append points creates the
+log. With `false` and no existing artifact, automatic appends are no-ops.
+
+## Inspect status
+
+```bash
+oat project log check --project .oat/projects/shared/example --json
+```
+
+`check` reports whether the log is absent, ready, or still awaiting synthesis;
+entry counts by class, type, and scope; the last entry date; and invalid
+hand-written headings. It reads only `project-log.md`.
+
+Use `--require-synthesis` to exit with status 1 while synthesis is pending:
+
+```bash
+oat project log check --require-synthesis
+```
+
+Without that flag, normal `absent`, `ok`, and `synthesis_pending` results exit
+successfully so lifecycle skills can decide whether to warn or enforce.
+
+## Complete the synthesis
+
+Write the end-of-run synthesis through the command:
+
+```bash
+oat project log synthesize \
+  --project .oat/projects/shared/example \
+  --body "The workflow was effective; preserve the gate handoff checks."
+```
+
+Use `--body -` for stdin. `synthesize` replaces the pending synthesis section
+without changing entries. It fails when the log is absent or the synthesis is
+already complete; append a correction judgment instead of replacing a completed
+synthesis.
+
+## Promote and roll up observations
+
+Before roll-up, promote a reusable `project` judgment by appending a new
+`general` judgment. Its body must reference the original heading. Never mutate
+or annotate the original entry.
+
+```bash
+oat project log append \
+  --type friction \
+  --scope general \
+  --area "gate review handoff" \
+  --body "Promotes '### 2026-07-18 · project · friction · gate review handoff': this applies to all gate-driven reviews."
+```
+
+After `summary.md` exists, roll up the log:
+
+```bash
+oat project log rollup \
+  --project .oat/projects/shared/example \
+  --json
+```
+
+`rollup` writes or updates `## Workflow Observations` in `summary.md` and
+appends `general` judgments to `workflow.projectLogLedgerPath`. Ledger entries
+deduplicate by date and area. The command is idempotent.
+
+The structured result contains:
+
+- `status`: `ok` or `failed`
+- `summarySection`: `written` or `updated`
+- `ledgerOutcome`: `appended`, `deduplicated`, `skipped_permitted`, or `failed`
+- `entriesRolledUp`: number of log entries written to the summary section
+
+`skipped_permitted` means the default repository reference layer is absent and
+no ledger path was explicitly configured; `status` remains `ok`. An explicitly
+configured ledger write failure returns `status: "failed"`. Completion must not
+seal or archive a project with entries until roll-up reports `status: "ok"`.
+
+`rollup` requires an existing `summary.md`; summary authoring remains the
+responsibility of the project summary workflow.

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

@@ -94,6 +94,37 @@ model that ran, and the reviewer must not replace them with self-identification.
 The CLI compares the copied values with its gate-owned record before it applies
 the severity threshold.
 
+### Review producer identity
+
+Dynamic planning workflows can declare their current parent model to a review
+gate without writing a provider or model into shared/user config:
+
+```bash
+OAT_GATE_PRODUCER_IDENTITY='<model>:declared' oat gate review ...
+```
+
+This is a review-command-only bridge. `oat gate review` accepts it only when
+the value is non-empty and its provenance suffix is exactly `declared`. The
+gate removes the variable from the child reviewer's environment, and non-review
+commands such as `oat gate cross-provider-exec` ignore it.
+
+Producer evidence precedence is explicit `--producer-identity`, then a
+qualifying implementation dispatch stamp, then the review-only environment
+declaration, and finally unknown producer behavior. The environment bridge does
+not replace stronger explicit or stamped evidence and does not establish
+observed runtime identity.
+
+For final and contiguous-range reviews, each in-scope implementer/fix stamp
+contributes its claimable producer family. If that producer is not claimable or
+has an unknown family, the gate may infer only a family exclusion from the
+stamp's launcher-owned configured target. The target does not become producer
+runtime identity, and generic or unclassifiable targets contribute no family.
+
+Keep reusable gate commands producer-neutral in shared and user config.
+Planning skills attach the ephemeral declaration only while executing a
+resolved configured command that invokes `oat gate review`; they leave it
+absent for every other gate command.
+
 ### Headless completion safety
 
 Every `oat gate review` child receives the same headless contract through two
@@ -492,7 +523,9 @@ By default the dispatcher:
 4. Resolves producer identity from `--producer-identity` or dispatch stamps when
    available. Exact phase/task scopes use the matching stamp. `final` and
    contiguous ranges such as `p02-p03` aggregate every in-range implementer/fix
-   stamp.
+   stamp. A stamp whose producer is not claimable or has an unknown family may
+   contribute its classifiable configured target family to aggregate avoidance
+   at lower confidence.
 5. Applies `--avoid same-family`.
 6. Checks candidate availability in descending priority order, with target id as
    the tie-breaker.
@@ -537,7 +570,10 @@ single stamp or when no stamp has a claimable family. Their producer record uses
 an unknown representative instead of presenting the latest stamp as aggregate
 truth:
 
-- `avoidFamilies` is the stable deduplicated union of claimable known families.
+- `avoidFamilies` is the stable deduplicated union of claimable known producer
+  families plus classifiable configured target families from stamps whose
+  producer is not claimable or has an unknown family. A known, claimable
+  producer remains authoritative over a conflicting target.
 - `contributingScopes` is the stable document-order list of distinct scopes from
   every relevant stamp.
 - `contributingStampCount` counts every relevant stamp, including unknown or

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

@@ -18,14 +18,11 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
 
     - Project: `.agents/skills` -> `.cursor/skills`, `.agents/agents` -> `.cursor/agents`, `.agents/rules` -> `.cursor/rules`
     - User: `~/.agents/skills` -> `~/.cursor/skills`, `~/.agents/agents` -> `~/.cursor/agents`
-    - Subagent invocation in Cursor is prompt-driven (`/name` or natural mention), not `subagent_type`
-    - OAT-controlled Cursor dispatch uses the generic `.cursor/agents/<name>.md` file plus the exact `providers.cursor.dispatchArgs.model` value selected from the candidate ladder. OAT passes it byte-for-byte as the actual Task-level `model`; a `model` frontmatter value is only a default/fallback mechanism.
-    - Cursor model strings are opaque. OAT does not infer family, effort, cost, or capability from their spelling; the configured candidate position owns the named tier meaning.
-    - Cursor model validation checks whether the selected model is eligible for subagent Task dispatch. Each adopt/doctor command probes each distinct exact candidate once and shares one lazy broad-catalog lookup across that pass; the cache ends with the command.
-    - A correlated accepted Task carrying the exact model argument plus the child sentinel proves argument eligibility for that account/client. It does not prove backend runtime identity; that remains `not-reported` without trusted Cursor telemetry or support confirmation. Structured rejection can establish `unknown-value`, while parent prose and broad `cursor-agent models` catalog presence remain diagnostic-only.
-    - The [dated GPT-5.6 verification artifact](https://github.com/voxmedia/open-agent-toolkit/blob/main/.oat/repo/reference/project-summaries/20260711-cursor-gpt-5-6-subagent-verification.md) preserves the original probe and a stream-JSON control pass. The controls observed no Task events, so the stop rule ran zero recommendation or exploratory candidates and retained the recommendation unchanged.
-    - The artifact's structured second-pass block contains only allowlisted event fields, derived outcomes, sanitized auth presence, and identifier hashes. Exact request/session/tool-call IDs and credential-redacted unprojected streams from that pass remain in gitignored local project storage for support escalation.
-    - The same public artifact retains the sanitized historical v1 text-mode record for provenance. That older section includes command arguments and prompts, stdout and stderr, exit and duration data, and capture-environment details such as user-specific binary paths; it is not limited to the structured second-pass allowlist.
+    - Sync materializes pinned Markdown definitions for both `oat-phase-implementer` and `oat-reviewer`. Each generated name keeps the configured flat ladder ID, while an explicit verified mapping writes the separate bracket-form frontmatter model. OAT never derives one form from the other.
+    - Generated definitions carry `supported-catalogue`, `project-config`, or `user-config` ownership. Project and supported output lives in the tracked `.cursor/agents` view; user-owned output lives under `~/.cursor/agents`. Cleanup reconciles only the applicable owner.
+    - Managed dispatch requires `providers.cursor.dispatchArgs.variant` and launches that exact resolver-selected native agent type first. Skills do not pass a Task-level model argument or normalize Cursor model strings.
+    - Cursor may silently fallback when a definition pin cannot be honored. Variant acceptance therefore establishes launcher-owned `configured` provenance only; runtime identity remains `not-reported` unless independently observed.
+    - `oat doctor` checks whether each flat ID is still present in the current Cursor catalogue and reports availability drift. Catalogue availability is diagnostic and does not prove that a definition-level bracket pin ran as configured.
     - Rule files render as `.cursor/rules/*.mdc`
 
 === "Copilot"
@@ -81,9 +78,9 @@ oat config adopt dispatch-matrix --user
 ```
 
 Project-config candidates materialize into the tracked, version-controlled
-project `.codex` view. User-config candidates materialize under `~/.codex`.
-OAT does not auto-ignore project output or create its Git commit; the team owns
-that repository change.
+project `.codex` and `.cursor` views. User-config candidates materialize under
+`~/.codex` and `~/.cursor`. OAT does not auto-ignore project output or create
+its Git commit; the team owns that repository change.
 
 At implementation time, the root passes the recorded named maximum through
 invocation-only `--ceiling-tier`, resolves one exact candidate per phase, and
@@ -91,19 +88,20 @@ dispatches one phase implementer. Codex first attempts the resolver-returned
 materialized role as the native `agent_type`. The launcher records the target,
 model axis, and effort axis from that resolved payload; child self-report is not
 provenance and cannot replace those values.
-Only an explicit pre-start native role-selection rejection permits a fresh
-pinned-child fallback. An accepted child, including one that later returns
+Only an explicit pre-start native role-selection rejection permits another
+target-preserving route. An accepted child, including one that later returns
 `BLOCKED` or lacks telemetry, is a task outcome rather than a fallback signal.
-Claude and Cursor bind the exact model arguments described above. A missing or
-unselectable managed target blocks rather than falling back to the root target
-or a base role.
+Claude binds the exact model argument described above. Cursor launches the
+exact native variant. A missing or unselectable managed target blocks rather
+than falling back to the root target or a base role.
 
 ## Scope rules
 
 - Project scope: skills + agents + rules
-- User scope: skills, plus the two bundled managed Codex role definitions used only for user-owned target expansion (provider mappings vary by adapter)
+- User scope: skills, plus the two bundled managed Codex and Cursor role definitions used only for user-owned target expansion (provider mappings vary by adapter)
 - Rules are project-scoped only in this release
 - Codex user-scope sync materializes user-config custom roles under `~/.codex`; project-config and supported-catalogue output remains project-scoped and version controlled
+- Cursor user-scope sync materializes user-config variants under `~/.cursor/agents`; project-config and supported-catalogue output remains project-scoped and version controlled
 
 ## Adoption model
 

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

@@ -67,6 +67,7 @@ Notable commands introduced in the current CLI surface:
 - `oat project archive [project-path]` - archive a tracked project through the same local move, summary export, and optional S3 upload path used by completion. When omitted, the project path falls back to the active project.
 - `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 validate-plan --project-path <path>` - validates `oat_plan_parallel_groups` metadata in `plan.md`; exits non-zero on invalid. See [Implementation Execution](../workflows/projects/implementation-execution.md#plan-declared-parallelism).
+- `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 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_validation_failed` | `targeting_correlation_failed`, alongside `runId`, `generatedAt`, and `artifactPath` when available. For `targeting_correlation_failed`, 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`. 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 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.

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

@@ -127,7 +127,7 @@ Each inner array is a group of phases that execute concurrently in their own wor
 - Each group must contain **2 or more** phases — singleton groups are rejected.
 - Every phase ID must exist in the plan body.
 - No phase may appear in more than one group.
-- Parallelism is only honored at Tier 1 (native subagents). Tier 2 degrades parallel groups to sequential target-preserving execution, not unconditional inline review. Concrete managed Claude and Cursor reviewers retain the exact resolver-returned `dispatchArgs.model` in the actual invocation and every retry; Codex retains its exact role or pinned child. Inline review requires verified equivalent host controls or an explicit inherit/default or managed-uncapped base-role exception, and otherwise blocks.
+- Parallelism is only honored at Tier 1 (native subagents). Tier 2 degrades parallel groups to sequential target-preserving execution, not unconditional inline review. Concrete managed Claude reviewers retain the exact resolver-returned `dispatchArgs.model`; Cursor reviewers retain the exact `providers.cursor.dispatchArgs.variant` native agent type; Codex retains its exact role or pinned child. Every retry preserves the complete target. Inline review requires verified equivalent host controls or an explicit inherit/default or managed-uncapped base-role exception, and otherwise blocks.
 
 **Authoring responsibility:**