@open-agent-toolkit/cli 0.2.50 → 0.2.52

package/assets/bundle-metadata.json

@@ -1,4 +1,4 @@
 {
   "schemaVersion": 1,
-  "oatVersion": "0.2.50"
+  "oatVersion": "0.2.52"
 }

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

@@ -47,7 +47,8 @@ After core initialization completes, `oat init` can enter an interactive guided
    - choose **Yes** to run the per-pack scope selector for every pack that allows both scopes (`ideas`, `docs`, `workflows`, `utility`, `project-management`, `research`, `brainstorm`)
    - choose **No** to apply additive per-pack defaults without extra scope prompts
    - on a fresh install every pack defaults to **user** scope, so capabilities follow you across repositories; an existing install keeps its current placement
-   - installing `project-management` installs the capability only. Adopting it for this repository is a separate, explicit `oat pjm init` step — see [Install vs. initialize](tool-packs.md#install-vs-initialize)
+   - after placement is chosen, repository `AGENTS.md` guidance is a separate opt-in. Accepting creates the managed `OAT tools` section only when the root file is absent. An existing file or symlink is never replaced: OAT prints a repository-relative, copy-pasteable managed-block patch instead. Declining leaves `AGENTS.md` unchanged
+   - installing `project-management` installs the capability only. Adopting it for this repository is a third, separate choice made with `oat pjm init` — see [Install vs. initialize](tool-packs.md#install-vs-initialize)
 2. **Local paths** — multi-select from default gitignored artifact paths (analysis, PR, reviews, ideas). Pre-existing paths are pre-checked; only new paths are added.
 3. **Documentation** — detect or enter docs metadata for the repo when documentation exists.
 4. **Provider sync** — sync provider project views via `oat sync --scope project`.
@@ -58,12 +59,15 @@ Hook install note:
 - The optional OAT pre-commit hook installs into Git's active hook directory.
 - If a repo uses a managed hook folder such as `.githooks/`, that path must already be configured in Git, or OAT must configure it during the prompt flow before hook install.
 
-**Non-interactive mode:** Fresh-init guided setup offers are interactive-only. If `--setup` is passed in non-interactive mode (`--json`, piped input, non-TTY, or `OAT_NON_INTERACTIVE=1`), guided setup does not prompt: tool packs use additive defaults, local-path and documentation prompts are skipped unless already configured, and provider sync is skipped unless separately requested.
+**Non-interactive mode:** Fresh-init guided setup offers are interactive-only. If `--setup` is passed in non-interactive mode (`--json`, piped input, non-TTY, or `OAT_NON_INTERACTIVE=1`), guided setup does not prompt: tool packs use additive defaults, local-path and documentation prompts are skipped unless already configured, and provider sync is skipped unless separately requested. Repository guidance also defaults to no write; pass `--project-guidance` to opt in explicitly or `--no-project-guidance` to record an explicit decline.
 
 ```bash
 # Explicit guided setup on an existing repo
 oat init --setup --scope project
 
+# Install capabilities and create or propose repository guidance
+oat init --setup --project-guidance
+
 # Fresh init — guided setup is offered automatically
 oat init --scope project
 ```

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

@@ -169,16 +169,64 @@ Commands report both. `oat tools list` and `oat tools info` show placement,
 intent source, and completeness. `oat status` and `oat doctor` report drift
 between intent and inventory with a scoped recovery command.
 
+### Requested scope versus realized placement
+
+Intent and inventory are reported as separate, source-qualified facts, so a
+pack you declared but never installed is never rendered as installed. The
+interactive picker labels each pack from **realized** placement — the scopes
+where managed assets actually exist on disk — not from declared `tools.*`
+intent. A pack declared at project scope with nothing materialized shows as
+not installed, which is the honest answer.
+
+Installation outcomes carry `realizedPlacement` alongside the requested scope,
+so JSON consumers can tell the two apart. Selecting `User scope` installs at
+user scope only; it never silently widens to `project + user`.
+
+One caveat worth knowing: `oat tools list` and `oat tools info` human output,
+and `oat status` JSON, still print a `placement` field derived from
+declaration rather than realization. For a declared-but-absent pack that field
+reads `project` even though nothing is installed. Prefer the picker labels and
+`realizedPlacement` when you need the truthful answer. Retiring the
+declaration-derived field is tracked in the repository backlog.
+
 A pack is **complete** at a scope when every managed asset the current release
 declares for that scope is present, **partial** when only some are, and
 **absent** when none are.
 
+### Three independent repository choices
+
+Tool-pack setup separates three decisions that do not imply one another:
+
+1. **Capability placement** chooses whether pack assets live at project scope,
+   user scope, or both. Placement controls where the capability is available;
+   it does not authorize a repository `AGENTS.md` edit.
+2. **Project guidance** is an explicit choice to create an absent root
+   `AGENTS.md` or print a manual patch for its managed `OAT tools` section. Use
+   `--project-guidance` to accept or `--no-project-guidance` to decline on
+   `oat init --setup`, `oat init tools`, and `oat tools install` flows. The
+   interactive prompt defaults to decline. Non-interactive runs perform no
+   guidance write unless `--project-guidance` is present and report the exact
+   opt-in command instead. When `AGENTS.md` already exists or is a contained
+   symlink, accepted guidance performs zero writes and prints the same
+   repository-relative, copy-pasteable managed block on every run. The patch
+   describes the complete realized project-and-user pack inventory and tells
+   the operator to remove a legacy `OAT workflows` block manually when needed.
+3. **PJM adoption** is the repository decision to use project-management state.
+   Make it separately with `oat pjm init`; neither installing the
+   `project-management` pack nor accepting tool guidance adopts PJM.
+
+These choices stay independent for standalone workflows installs too. For
+example, `oat init tools workflows --scope user --project-guidance` installs
+the workflows capability at user scope while updating guidance in the current
+repository. A blocked guidance update is reported separately and does not
+undo or misreport the successful capability install.
+
 ### Where pack assets land
 
 | Asset kind        | Project scope                                                                      | User scope                   | Ownership                                           |
 | ----------------- | ---------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------------- |
 | Skill             | `.agents/skills/<name>/`                                                           | `~/.agents/skills/<name>/`   | Managed — updated and removed by OAT                |
-| Agent             | `.agents/agents/<name>.md`                                                         | `~/.agents/agents/<name>.md` | Managed (see the user-scope agent limitation below) |
+| Agent             | `.agents/agents/<name>.md`                                                         | `~/.agents/agents/<name>.md` | Managed; provider projection is capability-driven   |
 | Template          | `.oat/templates/<name>`                                                            | `~/.oat/templates/<name>`    | Seeded once at project scope; managed at user scope |
 | Script            | `.oat/scripts/<name>`                                                              | `~/.oat/scripts/<name>`      | Managed, executable                                 |
 | Bundled docs tree | not applicable                                                                     | `~/.oat/docs/`               | Managed directory (core pack)                       |
@@ -189,30 +237,33 @@ creates `~/.oat/ideas/backlog.md` and `~/.oat/ideas/scratchpad.md`. Only the
 `workflows` project-scaffold seeds — `.oat/projects-root`, `.oat/config.json`,
 and the project `.gitkeep` files — are pinned to project scope.
 
-#### User-scope agents have limited native materialization
-
-Canonical **agents** are installed at either scope. At user scope, native
-Codex or Cursor role materialization is active only when that adapter is active
-under the resolved sync config: explicit enablement wins without filesystem
-detection, explicit disablement wins despite detection, and an unset adapter
-follows detection. That native materialization supplies the bundled managed
-role files (`oat-phase-implementer.md` and `oat-reviewer.md`); it does not
-materialize other pack-owned user agents. For example, a user-scope workflows
-install leaves `oat-codebase-mapper` without a native provider role, and a
-user-scope research install does the same for `skeptical-evaluator`. When no
-Codex or Cursor adapter is active, even the bundled managed roles lack native
-materialization.
-
-This diagnostic concerns native provider roles only. Providers may read
-canonical agent instructions through a separate loaded, user, and project
-lookup contract; that read availability does not establish native
-materialization and does not suppress this finding.
-
-`oat status` and `oat doctor` name the affected agents with a
-`user-agent-unmaterialized` finding rather than reporting the pack as complete
-without qualification. Install the pack at **project scope** when you need its
-native provider roles; `oat tools update` cannot repair this, because it is a
-scope limitation rather than drift.
+#### User-scope agent projection is provider-capability driven
+
+Canonical **agents** are installed at either scope. User sync scans them when
+an active provider declares user-agent capability. Explicit enablement wins
+without filesystem detection, explicit disablement wins despite detection, and
+an unset adapter follows detection. Provider mappings and registered
+materialization extensions then determine the output: entry sync, native read,
+extension-owned role materialization, or explicit unsupported evidence.
+
+Core sync does not write extension-owned role paths. Codex and Cursor own their
+generated managed-role outputs through provider extensions, while other user
+agents continue through each active adapter's declared mapping. Per-asset sync
+results distinguish changed, current, missing, failed, unsupported, and unknown
+outcomes, so one failed or unsupported asset does not erase evidence for its
+siblings.
+
+Materialization is not runtime visibility. `oat status` and `oat doctor` report
+the registered refresh policy separately and say `not-reported` when they did
+not inspect a running provider catalog. A provider file being current therefore
+does not mean the active session is proven to see it.
+
+After a successful provider-visible file change, OAT conservatively advises
+starting a new provider session so it has an opportunity to load the changed
+asset. This repository policy is not a provider hot-reload guarantee, an
+application-process restart requirement, or proof of visibility. No advice is
+emitted for current/no-op, planned-only, failed, missing, inactive, or
+unsupported materialization.
 
 Repository templates under `.oat/templates/` are **owner-owned seeds**. OAT
 compares a source-backed seed with its bundled default: a byte-equivalent copy
@@ -285,9 +336,12 @@ adoption**, and the two are tracked independently:
   fresh install, so `~/.agents/skills/` and `~/.oat/templates/` receive the
   managed assets and no repository file is touched.
 - **Initialize (adoption)**: `oat pjm init` instantiates the two-layer working
-  repo-reference surface under `.oat/repo/`, upserts the repository `AGENTS.md`
-  project-management guidance, and records explicit adoption in
+  repo-reference surface under `.oat/repo/`, creates repository guidance only
+  when the root `AGENTS.md` is absent, and records explicit adoption in
   `.oat/config.json` as `pjm.initialized: true` with a `pjm.schemaVersion`.
+  When the root file or a contained symlink already exists, adoption completes
+  independently and OAT prints a manual project-management/decision patch
+  without changing that file.
 
 Having the pack installed does **not** mean this repository uses PJM. Adoption
 is a per-repository decision recorded by `oat pjm init`:
@@ -315,7 +369,7 @@ neither recognized legacy input nor a complete current layout is skipped with
 an `oat pjm init` recovery. `--print-prompt` only reads the bundled prompt and
 does not inspect adoption or modify the repository.
 
-Decision records still require repository PJM adoption. Run `oat pjm init` first: like every repository-mutating PJM command, `oat decision init` fails closed in an unadopted repository, writes nothing, and returns `oat pjm init` as the recovery. Once the repository is adopted, `oat decision init` scaffolds only the decision surface — the decision directory, generated index, and decision-specific AGENTS guidance — without touching current state, roadmap, or backlog artifacts. It does not require the `project-management` pack. If the pack is installed later, its root guidance is maintained as a separate managed section so the decision instructions remain independently reusable.
+Decision records still require repository PJM adoption. Run `oat pjm init` first: like every repository-mutating PJM command, `oat decision init` fails closed in an unadopted repository, writes nothing, and returns `oat pjm init` as the recovery. Once the repository is adopted, `oat decision init` scaffolds only the decision surface — the decision directory, generated index, and decision-specific AGENTS guidance — without touching current state, roadmap, or backlog artifacts. It does not require the `project-management` pack. A missing AGENTS file can be created exclusively; an existing file or symlink is left byte-for-byte unchanged and receives a manual decision-guidance patch. If the pack is installed later, project-management guidance remains a separate managed section so the decision instructions stay independently reusable.
 
 `oat pjm init` is idempotent and non-destructive. Existing reference docs are skipped and left unchanged, so curated repo state is not overwritten on repeated runs.
 
@@ -500,9 +554,9 @@ Key behavior:
   output prints `Adopted project tool pack: <pack>` once per adopted pack;
   JSON output adds `adoptedPacks` only when the list is non-empty. This is pack
   intent reconciliation, not repository PJM adoption
-- A user-only install needs no Git repository and performs no repository writes
-- Refreshes the managed `OAT tools` section in the repository-root `AGENTS.md` **only for project-scope runs of the aggregate `oat tools install`**. The per-pack subcommands (`oat tools install workflows`, `oat tools install docs`, and the rest) never write `AGENTS.md`, at either scope
-- Repository `AGENTS.md` guidance for project management is owned by adoption, not by pack placement. Installing the `project-management` pack no longer upserts a managed `OAT project-management` section; `oat pjm init` writes that repository guidance when the repository actually adopts PJM
+- A user-only capability install needs no Git repository and performs no repository writes unless `--project-guidance` explicitly requests the separate repository guidance update
+- Offers repository `AGENTS.md` guidance independently of capability scope. Pass `--project-guidance` to create an absent file or print a manual managed `OAT tools` patch for an existing file/symlink, or `--no-project-guidance` to decline; the interactive prompt defaults to decline and non-interactive runs write nothing without the explicit opt-in
+- Repository `AGENTS.md` guidance for project management is owned by adoption, not by pack placement. Installing the `project-management` pack never writes the section. `oat pjm init` creates guidance only when the root file is absent; otherwise it completes scaffold/adoption and prints a manual patch without changing the existing file or symlink
 - Interactive runs can prompt to update selected outdated skills
 - Successful installs report the final scope chosen for each pack, including `project + user` when a pack is installed in both, and auto-sync only the scopes actually changed by the install so untouched scopes are never re-synced or pruned
 - Install-triggered auto-sync limits removal planning to the canonical entries from the pack that was just installed, so stale manifest drift in unrelated packs does not delete other provider views
@@ -771,11 +825,11 @@ brainstorm`, and `oat tools remove --pack brainstorm` manage the skill plus
 
 ### Auto-sync behavior
 
-All mutation commands (`install`, `update`, `remove`, `migrate`) automatically run `oat sync --scope <scope>` after successful operations. This ensures provider views stay in sync with canonical assets without manual intervention.
+All mutation commands (`install`, `update`, `remove`, `migrate`) automatically run `oat sync --scope <scope>` after successful operations. This reconciles provider files without manual intervention; it does not prove that an already-running provider catalog has loaded them.
 
 Use `--no-sync` on any mutation command to skip this step.
 
-For `oat tools install`, the follow-up sync still refreshes provider views immediately, but its removal pass is scoped to the canonical entries that were just installed. This avoids deleting unrelated provider views when a worktree has stale manifest entries for packs whose canonical content is absent locally.
+For `oat tools install`, the follow-up sync still reconciles provider views immediately, but its removal pass is scoped to the canonical entries that were just installed. New-session advice is shown only when a registered provider/content policy applies to a successful current-run change. It gives the provider an opportunity to load the changed asset; it does not tell you to restart the application process or prove runtime visibility. This avoids deleting unrelated provider views when a worktree has stale manifest entries for packs whose canonical content is absent locally.
 
 Removal and migration use the symmetric contract: the follow-up sync prunes exactly the provider views for the canonical paths that were removed, in that scope only, and only after the canonical source is confirmed absent.
 

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

@@ -55,6 +55,21 @@ Key behavior:
 
 - Mutates by default; use `--dry-run` to preview
 - Strategy-aware operations (`symlink`, `copy`, `auto`)
+- Configured `auto` may adopt an existing exact collection-directory alias.
+  When the destination is absent, the current runtime falls back per entry;
+  OAT does not create or unlink a collection alias without identity-bound
+  guarded primitives. Configuring an explicit per-entry strategy does not
+  release an owned collection: the current runtime fails closed for deferred
+  collection-directory copies and symlinks because it cannot keep every
+  destination ancestor identity-bound.
+  To leave the provider directory externally owned, run
+  `oat providers set --scope <scope> --disabled <provider>` and then
+  `oat sync --scope <scope>` to detach OAT ownership. Then verify and remove
+  the preserved alias before managing that directory manually.
+  Automatic transition requires an identity-bound, non-following publication
+  primitive. Deferred file operations and ordinary non-transition per-entry
+  symlinks retain their existing behavior. Explicit `symlink` and `copy` remain
+  per-entry modes; `oat sync` does not add a `--strategy` option.
 - Provider enable/disable honored via sync config
 - Cursor skills are native-read from canonical `.agents/skills`; sync does not
   create `.cursor/skills` mirrors
@@ -83,27 +98,40 @@ oat sync --scope all --dry-run
 Review every planned `remove` and `detach` operation before running the same
 command without `--dry-run`.
 
+Dry-run and apply output include a `Collection aliases` section with scope,
+provider, content kind, action, ownership, scope-relative canonical/provider
+directories, reason, and planned or applied result. JSON reports the same
+redacted fields under `collectionOperations`; collection proofs are reduced to
+status and a safe reason rather than filesystem identities or absolute scope
+roots. Real-directory fallback is reported as `fallback-per-entry`.
+
 ## `oat providers list`
 
 Purpose:
 
 - Summarize adapters, detection, and mapping-level health summary
+- Summarize managed collection aliases by `oat-created` and `adopted-exact`
+  ownership in both human and JSON output
 
 ## `oat providers inspect <provider>`
 
 Purpose:
 
 - Show adapter mappings and per-scope mapping state details
+- Show each owned collection alias with scope-relative paths, ownership, and
+  last-verification time
 
 ## `oat providers set`
 
 Purpose:
 
-- Enable or disable project providers in sync config
+- Enable or disable providers in the selected scope's sync config; project is
+  the default scope
 
 Key behavior:
 
-- Modifies `.oat/sync/config.json` to toggle provider enablement
+- Updates the selected scope's sync config to toggle provider enablement
+- Scope: `--scope project|user` (defaults to `project`)
 - Options: `--enabled <providers>`, `--disabled <providers>` (comma-separated)
 - Changes take effect on next `oat sync`
 

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

@@ -103,6 +103,25 @@ safe, including after interruption.
   - `false`: provider is inactive even if directory is detected.
   - unset: provider falls back to directory detection.
 - `defaultStrategy` is used when no provider-specific `strategy` is set.
+- `auto` prefers a safe exact collection-directory alias when the canonical
+  collection and provider mapping are eligible. The current runtime can adopt
+  an existing exact alias; an absent destination falls back to per-entry sync
+  because guarded alias creation is unavailable. OAT does not automatically
+  unlink collection aliases. Configuring an explicit per-entry strategy does
+  not release an owned collection. Deferred collection-directory copies and
+  symlinks fail closed with manual recovery guidance on the current runtime.
+  To make the provider directory externally owned, disable the provider with
+  `oat providers set --scope <scope> --disabled <provider>`, run
+  `oat sync --scope <scope>` to detach OAT ownership, and then verify and remove
+  the preserved alias before managing the directory manually. Automatic
+  transition requires an identity-bound,
+  non-following publication primitive. Deferred file operations and ordinary
+  non-transition per-entry symlinks retain their existing behavior. A real
+  provider directory falls back to per-entry sync; broken, foreign, nested,
+  unsafe, or unverifiable collection identity fails closed without replacement.
+- Explicit `symlink` and `copy` always remain per-entry strategies. Strategy is
+  configured here (globally or per provider); `oat sync` intentionally has no
+  `--strategy` flag.
 - At runtime, config is normalized so `providers` is always present in memory.
 - Project scans combine project and user known-stray paths. User scans use the
   user sync config.

package/assets/docs/provider-sync/manifest-and-drift.md

@@ -32,6 +32,38 @@ Autonomous worktree bootstrap also treats sync output as setup state. `oat-workt
 
 For transformed mappings such as project-scoped rules, the manifest stores hashes for the rendered provider output that was actually written, not the canonical source markdown. This keeps drift detection aligned with the on-disk managed file.
 
+### Collection alias ownership
+
+Manifest version 2 can record an exact collection-directory alias plus the
+canonical entries inherited through it. Collection records distinguish links
+created by OAT (`oat-created`) from exact links OAT adopted without rewriting
+(`adopted-exact`). Inherited entries use the `collection` strategy and refer to
+their owning collection record; OAT does not mutate provider child paths under
+that alias.
+
+The current runtime adopts an existing alias only when it exactly resolves to
+the canonical collection and has the same entry set. When the destination is
+absent, `auto` falls back to ordinary per-entry sync: Node does not expose the
+identity-bound parent-relative primitive OAT requires to create a collection
+alias safely. OAT does not use copy fallback for collection aliases.
+
+OAT also does not automatically unlink a collection alias in the current
+runtime because a separate identity check followed by path-based removal has a
+final replacement race. Disabling a provider detaches ownership while
+preserving the alias. Configuring an explicit per-entry strategy does not
+release an owned collection. Deferred collection-directory copies and symlinks
+fail closed because the current runtime cannot publish through replaceable
+ancestors without following them.
+To leave the provider directory externally owned, run
+`oat providers set --scope <scope> --disabled <provider>` and then
+`oat sync --scope <scope>` to detach OAT ownership. Then verify and remove the
+preserved alias before managing the directory manually. Automatic transition
+requires an identity-bound, non-following publication primitive.
+Deferred file operations and ordinary non-transition per-entry symlinks retain
+their existing behavior. Real directories, destination races, broken links,
+foreign targets, and unverifiable identities are preserved and fail closed.
+Canonical targets are never removed.
+
 ## Drift states
 
 - `in_sync`
@@ -47,6 +79,11 @@ For transformed mappings such as project-scoped rules, the manifest stores hashe
 
 Rendered rule files participate in the same drift states as other managed copies. If a provider rule file is edited directly, drift is computed against the expected rendered output for that provider.
 
+Collection-backed entries are checked through the owning collection identity.
+An exact alias is `in_sync`; an absent alias is `missing`; and a broken,
+replaced, foreign, or otherwise unverifiable alias is `drifted`. Provider list
+and inspect output summarize collection ownership separately from copy mode.
+
 ## Stray adoption
 
 `oat init` and `oat status` can offer adoption of unmanaged provider entries into canonical `.agents`.

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

@@ -13,6 +13,7 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - User: `~/.agents/skills` -> `~/.claude/skills`, `~/.agents/agents` -> `~/.claude/agents`
     - Rule files stay `.md` and are rendered with Claude-compatible frontmatter when needed
     - Managed phase implementers and optional nested workers use the exact configured candidate returned as `providers.claude.dispatchArgs.model`; OAT passes that value as the actual Agent `model`
+    - Claude's official subagent contract says existing agent directories are watched and changes load within seconds. It describes a conditional restart for the first agent added to a directory that was absent when the session started, for agents added through `--add-dir`, and when Claude starts with `--disable-slash-commands`. OAT cannot observe those session-start and launch-mode facts. After a successful provider-visible file change, the generic OAT repository policy therefore conservatively advises starting a new provider session; it does not claim that Claude hot-reloaded the file or that the application process must restart. The provider semantics were verified against [Claude Code subagent documentation](https://code.claude.com/docs/en/sub-agents) on 2026-08-31.
 
 === "Cursor"
 
@@ -62,7 +63,7 @@ description: 'Provider-specific path mappings for Claude, Cursor, Copilot, Gemin
     - All project-generated Codex variants and config registrations are repository-owned, version-controlled output and are never auto-ignored by OAT. User-config output remains under `~/.codex`.
     - A single role can be materialized directly with `oat providers codex materialize <agent-name> --model <model-id> --effort <reasoning-effort>`; `--agent-path` selects a specific canonical markdown agent, `--role-name` overrides the generated role name, and `--scope user` writes a user-config-owned role.
     - Aggregate Codex config drift metadata (`aggregateConfigHash`) is emitted in sync/status codex extension output and intentionally not stored as a separate manifest row
-    - Sync-time materialization is best effort; managed workflow correctness uses exact registered roles or a fresh child pinned to the resolved model plus reasoning effort with canonical role instructions, and does not require provider restart/hot reload
+    - Sync-time materialization is best effort; managed workflow correctness uses exact registered roles or a fresh child pinned to the resolved model plus reasoning effort with canonical role instructions. After a successful provider-visible file change, OAT conservatively advises starting a new Codex session so it has an opportunity to load the role. This repository policy is not a Codex hot-reload contract, an application-process restart requirement, or proof that the new session exposed the role.
     - Codex `max` is a first-class dispatch effort. It is present only for the Sol family in the committed supported catalogue, for both implementer and reviewer roles.
     - Codex multi-agent dispatch uses config-defined roles (`[agents.<name>]`) and `agent_type`
     - Codex subagent workflows require `[features] multi_agent = true` in active Codex config layers
@@ -103,10 +104,76 @@ 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.
 
+### Post-launch runtime observation
+
+Runtime observation is a separate, optional layer from the configured
+invocation above. It never changes launch, fallback, policy, ceiling, role,
+authority, or any selector: it only records what a provider said about its own
+child, so a configured selection and an observed identity stay independently
+readable.
+
+Codex reports child lineage, role, model, and effort through its session and
+turn metadata. It reports no service tier: the parser accepts one for forward
+compatibility, but no captured rollout carries the field. Claude reports role, model, effort, and service tier
+from its on-disk transcript metadata, and lineage only as root-or-child: it
+emits no depth field, so a subagent turn is recorded as `depth-unknown` rather
+than given an invented depth. Claude's role comes from the same class of
+bounded role identifier Codex records, and is reported only on the subagent
+turns that carry one. Cursor exposes no metadata channel and stays explicitly
+`not-reported`.
+
+`not-exposed` is reserved for an axis a provider genuinely does not have. It is
+not a stand-in for an axis that simply went unreported on a given run, and it is
+never written in place of a value the provider did report.
+
+Observation is metadata-only. Parsers select entries by type and never read
+conversation content, and raw provider output is projected through the owning
+parser's allowlist before validation, so instruction text, conversation bodies,
+and working directories are dropped rather than merely ignored. A missing,
+unparseable, or uncorrelated
+observation is `not-reported`, never a copy of the requested arguments or the
+materialized pin. An observed mismatch is evidence for a human to read; it is
+not a fallback trigger and cannot authorize replacement or retry.
+
+## Materialization, refresh, and visibility
+
+OAT reports three separate facts rather than collapsing them into “available”:
+
+1. **Materialization** says whether the canonical asset's provider output was
+   changed, current, missing, failed, unsupported, or unknown.
+2. **Catalog refresh policy** is provider- and content-specific. A policy is
+   `live`, `manual-refresh`, `restart-required`, or `unknown`, with its source
+   and verification date.
+3. **Runtime visibility** says whether the active provider catalog was actually
+   observed. `oat sync`, `oat status`, `oat doctor`, and install-triggered sync
+   do not query a running provider session, so they report visibility as
+   `not-reported` or `unknown`, never `visible`.
+
+After a successful provider-visible file change, `oat sync` conservatively
+advises starting a new provider session so the provider has an opportunity to
+load the changed asset. This repository decision was approved on 2026-08-31 and
+is recorded in the active project's implementation record. It is safety
+guidance, not a provider hot-reload guarantee, an instruction to restart the
+application process, or proof that the new session loaded or exposed the asset.
+The compatibility schema reports this session boundary as `restart-required`;
+with `repository-decision` provenance, that state means “start a new provider
+session,” not “restart the application.”
+No advice is emitted for current/no-op, planned-only, failed, missing, inactive,
+or unsupported materialization.
+
+A truthful provider/content-specific policy takes precedence over this generic
+repository decision. Claude's documented behavior remains conditional on
+session-start and launch-mode facts that OAT cannot observe, so OAT does not
+claim those conditions were met; the conservative new-session advice still
+applies after a successful file change. Unsupported capabilities retain an
+`unknown` policy rather than inheriting advice. A current file with no
+current-session catalog probe is still not proof of provider visibility.
+
 ## Scope rules
 
 - Project scope: skills + agents + rules
-- 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)
+- User scope: skills plus capability-supported ordinary agents (provider mappings vary by adapter)
+- The two bundled managed roles separately participate in Codex and Cursor extension expansion for user-owned targets
 - 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

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

@@ -33,6 +33,7 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - Canonical `.agents/rules` is source of truth for rules; provider rule files are derived rendered copies
 - Each scope syncs independently. When the same canonical asset exists at both project and user scope, OAT reports the duplication with both paths and versions and does **not** infer which copy a provider executes; resolve it explicitly with `oat tools migrate`
 - Pack removal and migration drive a symmetric removal sync: the exact canonical paths that were removed are pruned from provider views in that scope only, and only after the canonical source is confirmed absent
+- A successful provider write proves materialization only. Catalog refresh policy and current-session visibility are separate evidence; without a provider catalog observation, OAT does not claim the asset is visible.
 
 ## Implemented command surface
 
@@ -42,6 +43,8 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - `oat providers inspect`
 - `oat providers set`
 - `oat providers codex materialize`
+- `oat project dispatch record` (project-aware dispatch evidence only; never a
+  provider launcher)
 
 ## Adjacent CLI commands (commonly used with provider interop)
 
@@ -52,6 +55,8 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 ## Provider enablement model
 
 - Project provider enablement is stored in `.oat/sync/config.json` (`providers.<name>.enabled`).
+- User provider enablement is stored in `~/.oat/sync/config.json`. `oat providers set --scope user --enabled claude` and `oat providers set --scope user --disabled claude` update this canonical user config while preserving unrelated fields.
+- `oat providers list` and `oat providers inspect` show configuration-owned activation separately from filesystem detection, plus registered scope/content capability, projection modes, native reads, materialization, and visibility evidence.
 - `oat init --scope project` (interactive) prompts for supported providers and persists explicit true/false values.
 - `oat sync --scope project` uses config-aware provider activation and can prompt to remediate detected mismatches.
 - Cursor provider enablement still controls agents, rules, migration discovery, and legacy cleanup even though Cursor reads canonical skills without a generated skill view.
@@ -62,6 +67,36 @@ Rules are currently project-scoped canonical content. Unlike skills and agents,
 - Codex aggregate config drift is reported via sync/status extension metadata (`aggregateConfigHash`); it is not persisted as a separate manifest schema entry.
 - Codex user-config materialization writes user-owned implementer and reviewer roles under the user provider directory, `~/.codex`; it does not write those roles into the repository.
 
+## Provider refresh evidence
+
+Refresh advice is emitted only for a successful, relevant current-run change.
+For every supported provider-visible capability without a stronger sourced
+policy, the registry records the OAT repository decision approved on
+2026-08-31: start a new provider session so it has an opportunity to load the
+changed asset. This is conservative safety guidance, not a provider hot-reload
+guarantee, an application-process restart requirement, or proof that the new
+session loaded or exposed the asset. Current/no-op, planned-only, failed,
+missing, inactive, and unsupported materialization receive no such advice;
+unsupported capabilities keep an `unknown` policy.
+
+The compatibility schema names this session boundary `restart-required`. When
+its provenance is `repository-decision`, the recovery text means “start a new
+provider session,” not “restart the application.”
+
+A truthful provider/content-specific policy takes precedence over the generic
+repository decision. The official Claude Code subagent contract, verified on
+2026-08-31, says existing agent directories are watched and changes load within
+seconds. It describes a conditional restart for the first agent added to a
+directory absent at session start, for agents added through `--add-dir`, and
+when Claude starts with `--disable-slash-commands`. OAT cannot observe those
+runtime conditions and does not claim they occurred; it applies only the
+generic new-session guidance after a successful file change.
+
+`oat status`, `oat doctor`, and `oat init` expose that their running-provider
+catalog observation is `not-reported`. They inspect filesystem/configuration
+state, not the provider's active catalog. Only an actual current-session probe
+can establish `visible`.
+
 ## Codex managed dispatch
 
 For managed Codex work, the resolver-returned materialized role is attempted as
@@ -73,6 +108,15 @@ role-selection rejection. Missing runtime telemetry, missing self-report, or a
 child accepted by the native route that later returns `BLOCKED` are not
 role-selection rejection and do not permit fallback.
 
+Project workflows construct and redact the complete dispatch payload before
+the native call, then persist its accepted or `blocked-before-start` result
+immediately under the active project's `dispatch/` directory. The generic
+record remains provider-neutral. OAT-specific canonical role, rejection,
+fallback, and runtime facts live only under its `oat` namespace. A qualifying
+fallback is a fresh request that preserves exact target and controls and is
+explicitly labeled an approximation; timeout, refusal after acceptance,
+runtime mismatch, malformed output, and missing telemetry never authorize it.
+
 ## Non-interop namespaces in the same CLI
 
 - `oat project new <name>` (workflow/project scaffolding)

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

@@ -80,13 +80,19 @@ Notable commands introduced in the current CLI surface:
   `--no-commit` leaves the new record uncommitted for the caller to persist.
   With `--json`, the receipt includes `status`, `sha`, and `ref`, plus
   `conflicts` when applicable and per-child results when coordination children
-  were requested.
+  were requested. A project whose authoritative ref is
+  `refs/oat/completed/<project>` is terminal and cannot be pulled or opened.
+  A same-SHA `refs/oat/projects/<project>` ref is only an inert alias; differing
+  active and completed SHAs are reported as a terminal mismatch that must be
+  repaired before lifecycle work continues.
 - `oat project links [project] --format markdown|json` - render SHA-pinned
   links for the linkable artifacts on the project ref. On GitHub origins the
   artifacts become full-SHA blob links; other hosts degrade to the retained ref
   and short SHA without guessing a web URL. `--durable-summary <path>` accepts
   only a path contained in the repository, normalizes it repository-relative,
-  and renders it as a code span rather than a guessed remote link.
+  and renders it as a code span rather than a guessed remote link. Completed
+  projects resolve through `refs/oat/completed/<project>` while the rendered
+  artifact URLs remain pinned to the verified full source SHA.
 - `oat project pause [project]` - persist the pause state and clear the active
   project pointer. If synced publication is declined or fails after the pause
   commit is created, that clean commit is retained; address the publication
@@ -99,7 +105,10 @@ Notable commands introduced in the current CLI surface:
   commit. If remote deletion succeeds but local checkout removal fails, the
   local ref, record, and checkouts are retained. Resolve the reported local
   obstruction and retry `prune --force`; do not run `project push`, which would
-  republish the deleted remote ref.
+  republish the deleted remote ref. For a completed project, explicit prune
+  deletes the completed ref and any same-SHA active alias but preserves durable
+  local and S3 archive snapshots. A differing-SHA terminal mismatch blocks
+  prune and retains both refs.
 - `oat project migrate <path> --to synced [--no-commit]` - migrate an existing
   shared project to synced storage while preserving its artifacts and
   retargeting the active project pointer. `--no-commit` leaves the parent
@@ -110,7 +119,13 @@ Notable commands introduced in the current CLI surface:
   parents. A malformed discovery record with no materialized checkout appears
   as a `recorded-invalid` row. When the checkout is materialized, its existing
   row instead carries the restore hint and `recordError` parse diagnostic in
-  `--json` output.
+  `--json` output. Fully retired completed refs and same-SHA active aliases are
+  omitted from active discovery. A differing-SHA active/completed pair appears
+  as a `terminal-invalid` row with a recovery diagnosis. When reconciling a
+  local synced record or checkout, only a verified missing
+  `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 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 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 config dump --json` - merged config with source attribution
@@ -121,8 +136,9 @@ Notable commands introduced in the current CLI surface:
 - `oat review latest --json` - find the newest review artifact by `oat_generated_at`, scanning the active or specified project's `reviews/` and `reviews/archived/` directories plus ad-hoc review locations. Same-time candidates use target priority, then lifecycle recency (`final` > higher phase/task > lower phase/task). The JSON contract returns `path`, `scope`, `generatedAt`, `kind` (`project` or `adhoc`), `archived`, and `actionable`, with `null` values when no review exists. Archived project reviews remain discoverable as history but return `actionable: false`.
 - `oat project list --json` - summary state for tracked projects under the configured projects root
 - `oat project complete-state <project-path>` - apply the canonical completed-state mutation to a project's `state.md`; used by `oat-project-complete` during lifecycle closeout
-- `oat project archive [project-path] [--project-recap-run <project-relative-path>] [--no-commit]` - 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. 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 immutable file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete legacy hash coverage, stale bytes, path escapes, and recipe mismatches fail without removing the active project. `--no-commit` is a manual/library-only option: for a synced project it still removes the checkout but deliberately omits the lifecycle commit receipt. Never pass it through `oat-project-complete`, which requires that receipt.
+- `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 immutable file byte, then atomically installs the export before deleting the active project. Existing destinations, incomplete legacy hash 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. Legacy complete records receive a cleanup diagnosis rather than pull/open guidance. With `--json`, the terminal receipt reports `completedRef`, `verifiedSourceSha`, whether `activeAliasDisposition` was `retained` or `removed`, whether `recordRetired` completed, and the parent `lifecycleCommit`. `--no-commit` is a manual/library-only option: for a synced project it still removes the checkout but deliberately leaves `lifecycleCommit` null. Never pass it through `oat-project-complete`, which requires that receipt.
 - `oat repo archive sync [project-name]` - hydrate archived project snapshots from the configured repo-scoped S3 archive into `.oat/projects/archived/`. The old `oat project archive sync` path remains as a deprecated shim.
+- `oat project dispatch record --event-file <json-file-or-dash> [--project <project-path>]` - validate one generic dispatch record plus its namespaced OAT evidence event, and persist it into the project's append-only `dispatch/` journal. Omit `--project` to validate without persisting. Revision 1 is `dispatch/<request-id>.json` and every later revision is `dispatch/<request-id>@<NNNN>.json`; superseded revisions are never replaced or removed. The command validates and records evidence only — it never launches a provider. A `runtime-observation` event may carry either a finished `observation` or the provider `metadata` envelope (`provider`, `observedAt`, `entries`) to normalize, but not both. `entries` may be raw provider output: they are projected through the owning parser's allowlist, are never persisted, and both forms have their `match` derived from the record's configured invocation rather than trusted from the caller, with the observation's `provider` bound to the record's. With `--json`, the result adds `runtimeIdentity` with separate `configured` and `observed` objects plus a `match` of `matching`, `mismatching`, `not-comparable`, or `null`; observation is corroboration only and never overrides configured invocation. Error output is redacted on a best-effort basis; absolute paths in identity fields are rejected outright, while some prose forms (colon-prefixed, URL routes) can survive. See [Evidence Layers](../workflows/projects/evidence-layers.md).
 - `oat project 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#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 set-mode` — deprecated no-op. Execution mode is no longer user-selectable; emits a deprecation warning and preserves the `--json` contract.