@awebai/oats 0.25.9 → 0.26.0

package/docs/desktop-cli-api.md

@@ -18,9 +18,11 @@ prints exactly one JSON object on stdout:
 ```
 
 `version` is the installed package's exact semver (e.g. `0.20.0`).
-Desktop 0.25 accepts `desktopApi === 1` and semver `>=0.22.0 <0.26.0`
-(the earlier Desktop 0.23 band was `>=0.22.0 <0.24.0`). This admits the paired
-0.24 CLI without changing Desktop API v1. It does not establish complete captured
+The Desktop accepts `desktopApi === 1` and gates on the kernel feature
+`packages-no-approval` (semver range `>=0.25.8 <0.27.0`: the floor admits the
+main-branch kernel before 0.26.0 is tagged; the feature fence is the real gate).
+Earlier bands were `>=0.22.0 <0.26.0` (Desktop 0.25) and `>=0.22.0 <0.24.0`
+(Desktop 0.23). It does not establish complete
 UI, backend, plugin, retirement or recovery parity; capability checks and explicit
 refusals below remain authoritative.
 
@@ -46,49 +48,348 @@ no progress prose (progress goes to stderr):
 - success (exit 0): `{"schemaVersion":1,"ok":true,"result":{...}}`
 - failure (nonzero exit): `{"schemaVersion":1,"ok":false,"error":{"code":"...","message":"..."}}`
 
-## Souls and sources (`oats inspect --json`, `soulsApi: 1`, OATS 0.24.7+)
-
-Every entry in `result.souls[]` carries what the soul's **own `soul.yaml`
-declares**, parsed by the kernel — a consumer never parses YAML and never
-infers a field that is not there:
-
-- `soulsApi: 1`
-- `declarations: { requires, defaults, knowledge, teams, resources, children }` — each
-  the declared object, or `null` when the section is absent (`children`
-  since 0.24.8: `{spawn: boolean}`, see readiness policy).
-- `provenance: { kind, source, revision, path, workspaceRevision } | null` —
-  where this soul copy came from, as recorded by the kernel when it created
-  it (the 0.24 bootstrap recorded `packaged-definition` or
-  `exported-edition-copy`; the 0.25 `oats onboard` creates no soul and records
-  nothing here — see [`oats onboard`](#oats-onboard-onboardapi-2)).
-  Souls created before 0.24.7 or authored by hand
-  read `null`; render that as *unrecorded*, not as local or as anything else.
-- `readiness` — the soul's **declared sources**, joined against
-  `result.capabilities[]` from the same payload. Distinct from launchability
-  (`oats spawn`) and adoption (`oats prepare`); never a green "Ready".
-  - `source: "recorded" | "unrecorded"`
-  - `requirements: [{ capability, source, installed, approved, active, version }] | null`
-    (`null` = nothing declared). `installed: false` = not in the inventory;
-    `approved`/`active`/`version` are `null` when there is no inventory row.
-  - `status: "undeclared" | "sources-installed" | "sources-missing" | "unknown"`
-- `declarationProblems: [{ code, message }]` — an unreadable file reports why;
-  the soul is still listed.
-
-`result.sources` is the scope's **portable source context**: the distinct
-provenance sources its souls record.
+## Inspect, readiness and operation run on the workspace model (`operationsApi: 2`, `soulsApi: 2`, `readinessApi: 2`, OATS 0.26.0)
+
+On a workspace deployment (an `oats-local.yaml` in reach of `--dir`), and for
+any home whose `instance.json` records `modules`, these three commands read the
+workspace model's own records and **never the classic config chain**. The probe
+integers are the gate; there is no feature string. The probe's integer says
+this kernel CAN answer the v2 shape. **Dispatch on the payload's own integer**.
+There is no v1 shape any more (0.26.0 removed the classic chain's answers):
+with no `oats-local.yaml` in reach and no `--home`, the three commands answer
+`E_LOCAL_MISSING`; a `--home` whose `instance.json` records no `modules`
+(spawned by an earlier kernel) answers `E_UNSUPPORTED_MODE` (re-spawn it from
+the deployment); an unreadable `--home` answers `E_SESSION_UNKNOWN`.
+
+**The captured/portable path was removed in 0.26.** A *captured home* (its `instance.json`
+records `executionBinding`, `incarnationId` or `captured`: spawned through
+0.24–0.25's `prepare` / `--deployment --resolution`) answers `E_UNSUPPORTED_MODE`
+(`details: {home, captured: true}`) to these three commands, to `session
+start|restart` and to its in-home commands; `oats retire` still works on it, and
+its result's `warnings[]` names each capability whose retire hook did NOT run
+(what it created is not revoked). `oats status --json` / `oats doctor --json`
+name captured homes once, in `problems[]`, as `legacy-captured-home` `{instances,
+homes, message}`. The captured selectors `--deployment`, `--resolution` and
+`--artifact-set`, and an inherited `OATS_DEPLOYMENT`/`OATS_RESOLUTION`, are refused
+by every command except `version` (`E_UNSUPPORTED_MODE`, `details.selector` or
+`details.inherited`); `oats prepare` and `oats inspect --request` are removed
+verbs (`E_UNKNOWN_COMMAND`, `details: {removed, replacement}`). The version
+document no longer carries `capturedDispatchApi` / `capturedDispatchActions`.
+
+| Command | Integer (probe and payload) | 0.25.x value |
+|---|---|---|
+| `oats inspect --json` | `operationsApi: 2` (top level); each `souls[]` row `soulsApi: 2` | 1 / 1 |
+| `oats readiness --json` | `readinessApi: 2` | 1 |
+| `oats operation run --json` | `operationsApi: 2` on the result | absent |
+
+The probe's `soulsApi` follows the inspect soul rows. The `oats souls --json`
+document keeps its own `soulsApi: 1`, because its shape did not change (see
+[`oats souls`](#oats-capabilities---dir---json-capabilitiesapi-1-oats-souls---dir---json-soulsapi-1)).
+
+**The subject is an instance or a soul, never a scope.** Pass `--home <abs>`
+or `--soul <name>`. A workspace deployment with neither is `E_BAD_ARGS`. An
+`oats-local.yaml` that exists but cannot be read is reported with its own
+error code, never answered from the classic chain. For
+inspect, the message points to `oats souls` and `oats capabilities`, the
+scope-wide lists.
+- `--home` selects the instance, from its `instance.json` and the module copies
+  under `<home>/.oats/modules/`. Everything is as spawned.
+- `--soul` selects the soul, resolved exactly as a spawn of it would be:
+  discovery, then soul `capabilities:` plus workspace defaults, then the lock.
+- A v2 home lives at `<deployment>/agents/<soul>/instances/<name>`, and its
+  deployment is derived from that path. `<deployment>/oats-local.yaml` must
+  exist exactly there (never found by walking up), otherwise
+  `E_HOME_MISMATCH`. A v2 spawn ignores an ambient `PI_AGENTS_ROOT` /
+  `OATS_ROOT`, so its homes always have this layout.
+- `--dir`, if given with `--home`, must be that home's deployment
+  (`E_HOME_MISMATCH`). `--agents-root`, if given, must be
+  `<deployment>/agents` (`E_HOME_MISMATCH` with `--home`, `E_SOUL_UNKNOWN`
+  with `--soul`).
+
+**Gone from every payload:** `scope` (`context`, `chain`, `team`,
+`agentsRoots`), config `levels`, `activation {declaredAt, target, level,
+source}`, `currentConfig`, `snapshot.drift`, `health {trusted, approved,
+locked, installedIntegrity}`, soul `provenance`/`readiness`, and the scope's
+portable `sources`. A capability's origin is its module's `from` (member
+commit, or package version + commit + integrity). Its settings are the merged
+payload the spawn recorded for a home, or the resolution computes for a soul.
+
+### `oats inspect (--home <abs> | --soul <name> [--dir <d>]) --json` → `operationsApi: 2`
 
 ```json
-{"soulsApi":1,"kind":"recorded-provenance","note":null,
- "items":[{"kind":"exported-edition-copy","source":"git:https://…/oats.git","revision":"<sha>","path":"souls/oats-setup-expert","workspaceRevision":"<sha>","souls":["oats-setup-expert"]}]}
+{"operationsApi":2,"kernel":"0.26.0",
+ "subject":{"kind":"instance","instance":"release-manager-x","home":"/w/agents/release-manager/instances/release-manager-x","soul":"release-manager"},
+ "workspace":{"key":"github.com/northwind/agents","name":null,"deployment":"/w","commit":"461b9c24…","standalone":false},
+ "souls":[{"soulsApi":2,"name":"release-manager","repoKey":"github.com/northwind/agents","commit":"461b9c24…","team":"engineering",
+   "kind":null,"path":null,"description":"Cuts, verifies and announces platform releases.","work":"worktree","runtime":null,"model":null,
+   "declarations":{"requires":null,"defaults":null,"knowledge":{"owns":"release-manager","reads":["platform-engineer"]},"teams":null,"resources":null,"children":null,
+                   "capabilities":{"nw-release-tooling":{"from":"here"},"nw-deploy":{"from":"package"}}},
+   "declarationProblems":[],
+   "instructions":{"file":"/w/agents/release-manager/souls/461b9c24929c/AGENTS.md","text":"# release-manager\n…","truncated":false}}],
+ "layers":{"knowledge":{"id":"oats.okf","from":"workspace"},"messaging":{"id":null,"from":null},"tasks":{"id":null,"from":null}},
+ "capabilities":[
+   {"id":"nw-house-style","version":"0.0.0-workspace","layer":null,"command":null,
+    "from":{"kind":"member","repoKey":"github.com/northwind/agents","commit":"461b9c24…"},
+    "dir":"/w/agents/release-manager/instances/release-manager-x/.oats/modules/nw-house-style","settings":{},"declares":[],"compatibility":{"ok":true,"range":">=0.25.0","kernel":"0.26.0"},"missingRequires":[],"operations":[]},
+   {"id":"oats.okf","version":"2.1.3","layer":"knowledge","command":"okf",
+    "from":{"kind":"package","package":"oats.okf","version":"2.1.3","commit":"71f53649…","integrity":"sha256-5019…","repoKey":"github.com/awebai/oats-okf"},
+    "dir":"/w/agents/release-manager/instances/release-manager-x/.oats/modules/oats.okf",
+    "settings":{"owns":"release-manager","reads":["platform-engineer"],"state-dir":"/srv/okf"},"declares":["bindings-file","git-timeout","harvest-model","harvest-runtime","state-dir"],"compatibility":{"ok":true,"range":">=0.24.4","kernel":"0.26.0"},"missingRequires":[],
+    "operations":[{"name":"inspect","kind":"view","command":"inspect","context":"home","description":"…","args":[],"argv":["okf","inspect"],"available":true,"reason":null}]}],
+ "knowledge":{"provider":"oats.okf","version":"2.1.3","operations":[{"name":"inspect","kind":"view","available":true,"reason":null}]},
+ "instance":{"home":"/w/agents/release-manager/instances/release-manager-x","instance":"release-manager-x","agent":"release-manager",
+   "runtime":"pi","model":null,"yolo":null,"launched":false,"createdAt":"<iso>","resolution":"7217670b…",
+   "soulDir":"/w/agents/release-manager/souls/461b9c24929c",
+   "instructions":{"file":"/w/agents/release-manager/instances/release-manager-x/AGENTS.md","text":"…","truncated":false,
+                   "sources":[{"source":"kernel:instance-boundary","file":"…"},{"source":"capability:oats.okf","file":"…/.oats/modules/oats.okf/injects/okf.md"}]}},
+ "identity":null,"problems":[]}
+```
+
+- `subject` is `{kind:"instance", instance, home, soul}` for `--home` (the
+  `home` as you passed it) or `{kind:"soul", soul, repoKey, commit, team}` for
+  `--soul`.
+- `workspace.deployment` is canonical (realpath). `workspace.name` is
+  observed, so it is `null` on `inspect --home`: that command never contacts
+  the remotes, and `instance.json` records the workspace `key`, not its name.
+  Identify the workspace by `key`.
+- `souls` holds exactly the subject's soul. For a home, it is read from the
+  recorded `soulDir` (the per-commit copy the instance incarnates), with
+  `path: null`. For a soul, it is the member's current definition, with
+  `path` inside the member repository. `kind` is `member` or `external`.
+  It is observed from discovery, so it is `null` on `inspect --home`
+  (readiness `--home` observes it).
+  `declarations` gains `capabilities` (the soul's own `capabilities:`).
+- `layers.<layer>` is `{ id, from }`: the capability filling the slot
+  (`null` when empty) and where it came from (feature `layers-from`):
+  `"soul"` (the soul's own `capabilities:`), `"workspace"`
+  (`defaults.<slot>` or `defaults.capabilities`) or `"team:<label>"`
+  (`defaults.byTeam.<label>.capabilities`). `from` is `null` for an empty
+  slot. A soul answers from its resolution now. A home answers what its spawn
+  recorded, even after the workspace changes. A home spawned before
+  `layers-from` recorded nothing, so its `from` is `null`.
+- `capabilities[]` lists the subject's resolved modules, sorted by id:
+  - `dir` is the home's module copy, or `null` for a soul (nothing is
+    materialized to answer inspect).
+  - `settings` is the merged provider payload.
+  - `compatibility` is `{ ok, range, kernel }`: the manifest's
+    `compatibility.oats` (`null` when none) against the running kernel. A
+    soul's resolution refuses an incompatible module (`E_CAPABILITY_INCOMPATIBLE`),
+    so `ok: false` appears only for a home, together with a
+    `capability-incompatible` entry in `problems`.
+  - `declares` lists the setting keys the manifest declares (`settings.<key>`),
+    sorted; names only, never descriptions or defaults; `[]` when it declares
+    none. Gate on feature `settings-declared` (e.g. offer a Teams choice only
+    when the messaging module declares `join`).
+  - `missingRequires` lists the manifest `requires` commands absent from PATH.
+  - `operations[].available` is `false` with a `reason` when it cannot run
+    here: a `context: "home"` operation for a soul subject says `needs a
+    running home (--home)`.
+- `instance` is `null` for a soul. For a home, `instructions.sources` names
+  each composed inject in order.
+- A soul whose resolution is refused (for example, a package the lock does
+  not provide) is an error for inspect (`E_PACKAGE_MISSING`,
+  `E_PACKAGE_INTEGRITY`, `E_CAPABILITY_MISSING`, `E_LOCK_SCHEMA`). Readiness
+  reports the same condition as a failing item.
+
+### `oats readiness (--home <abs> | --soul <name> [--dir <d>]) [--policy] --json` → `readinessApi: 2`
+
+```json
+{"readinessApi":2,
+ "subject":{"kind":"soul","soul":"release-manager","repoKey":"github.com/northwind/agents","commit":"461b9c24…","team":"engineering"},
+ "selector":{"kind":"soul","soul":"release-manager","agentsRoot":null,"dir":"/w"},"at":"<iso>",
+ "checks":{
+  "installed":{"status":"pass","items":[
+    {"subject":"oats.okf","status":"pass","required":true,"reason":null,"producer":"workspace resolution",
+     "evidence":{"from":{"kind":"package","package":"oats.okf","version":"2.1.3","commit":"71f53649…","integrity":"sha256-5019…"}},"remedy":null,"capability":{"id":"oats.okf"}}]},
+  "configured":{"status":"not-applicable","items":[]},
+  "member":{"status":"pass","items":[
+    {"subject":"member github.com/northwind/agents","status":"pass","required":true,"reason":null,"producer":"workspace discovery",
+     "evidence":{"repoKey":"github.com/northwind/agents","workspace":"github.com/northwind/agents","commit":"461b9c24…"},"remedy":null}]},
+  "providers":{"status":"fail","items":[
+    {"subject":"oats.okf","status":"fail","required":true,"reason":"setting state-dir is required (absolute host path)","producer":"provider binding check",
+     "evidence":null,"remedy":null,"capability":{"id":"oats.okf"},
+     "result":{"status":"needs-configuration","problems":[{"code":"needs-configuration","message":"setting state-dir is required (absolute host path)"}],"warnings":[]}}]}},
+ "summary":{"ready":false,"required":3,"pass":2,"fail":1,"unknown":0,
+   "byCapability":[{"capability":{"id":"oats.okf"},"checks":{"installed":"pass","configured":"not-applicable","member":"not-applicable","providers":"fail"},"ownReady":false,"ready":false}],
+   "subjectBlockers":[]},
+ "notes":["…"]}
+```
+
+For `--home`, `subject` is `{kind:"instance", instance, home, soul}`, and
+`selector` is `{kind:"home", home, soul, agentsRoot}`. The selector echoes
+your arguments byte-exact, as before. It is now a top-level field, not
+`subject.selector`.
+
+The four checks are `installed | configured | member | providers`, each
+`{status, items}` with the item fields as before (`subject, status, required,
+reason, producer, evidence, remedy`, plus `capability {id}` on
+per-capability items). Item and check statuses are `pass | fail | unknown |
+not-applicable`. **`summary.ready`** means every required item passes or is
+not-applicable, and at least one required item exists. `byCapability` and
+`subjectBlockers` keep their 0.24.9 meaning over the four new checks.
+
+- **`installed`**:
+  - For `--home` (producer `instance modules`): each recorded module, `pass`
+    when its copy under `<home>/.oats/modules/<id>/` holds its `oats.json`.
+    A missing copy fails, with remedy "spawn a new instance".
+  - For `--soul` (producer `workspace resolution`): each resolved module, with
+    its `from` as evidence.
+  - A resolution refusal is one failing item carrying `code` (`E_PACKAGE_MISSING`,
+    `E_PACKAGE_INTEGRITY`, `E_CAPABILITY_MISSING`, `E_LOCK_SCHEMA` or
+    `E_REQUIREMENT_INACTIVE`), the kernel's message as `reason`, its details as
+    `evidence`, and `remedy: "oats sync (…)"`. That covers a soul whose
+    packages are not locked, or whose lock no longer matches. The item's
+    `subject` is the soul; it lands in `summary.subjectBlockers`.
+- **`configured`** (producer `capability manifest`): each module's manifest
+  `requires` command (`evidence.command`), `pass` on PATH and `fail`
+  otherwise, with the manifest's `install` hint as the remedy. It is `not-applicable` when nothing declares a
+  requirement. Settings problems are the provider's to say, in `providers`.
+- **`member`** (producer `workspace discovery`): the soul's member
+  repository is confirmed in the workspace. It is the host's `members:` with
+  the member's `oats-membership.yaml` backlink, as `oats workspace status`
+  reports it. The kernel never reads `oats.yaml` here.
+  - `fail` when the backlink is not confirmed; the remedy names
+    `oats-membership.yaml`.
+  - `unknown` when discovery could not be read.
+  - `not-applicable` (`required: false`) for an external soul (it has no
+    member backlink) and on a standalone view (decision 10, an allowed mode:
+    membership is declared there, never confirmed). The reason starts with
+    `standalone view (explicit | unreadable-host)`, and
+    `evidence.standaloneReason` carries the reason code. A standalone soul can
+    therefore read Ready.
+  - Never login, never team registration.
+- **`providers`** (producer `provider binding check`): for each module whose
+  manifest declares `binding`, the kernel runs the provider's own check
+  (`binding.check`). It relays **the provider's answer verbatim** as
+  `item.result: {status, problems: [{code, message}], warnings: [{code,
+  message}]}`. The status maps to the item:
+
+  | `result.status` | item `status` |
+  |---|---|
+  | `ready` | `pass` |
+  | `needs-configuration` | `fail` |
+  | `authorization-required` | `fail` |
+  | `unavailable` | `unknown` |
+
+  The reason is the first problem's message (`null` on pass).
+  `authorization-required` and `unavailable` were added in 0.26.0 (additive):
+  treat an unrecognized status as `unknown` and show `result` as sent.
+  - `warnings` is always present (`[]` when the provider sends none). It
+    **never changes the status** and is not counted in `summary`. A ready
+    binding can still say, for example, that end-to-end encryption is off:
+    show it next to the pass. A `warnings` that is not an array of `{code,
+    message}` strings makes the whole answer `unknown`, the same as a
+    malformed `problems`.
+  - A provider that cannot answer is `unknown`, with `item.problems` carrying
+    its error `{code, message}` and `result: null`. That covers:
+    - a refusal (`ok:false`, whose code is relayed);
+    - an invalid answer (`provider-unavailable`, see the wire below);
+    - a timeout;
+    - a module tree that cannot be made available.
+  - **One time budget per readiness read**: 60 s for all provider checks
+    together, and at most 30 s for each. Checks the budget does not reach are
+    not run; they are `unknown` with code `time-budget-exhausted`.
+  - For `--home` the check runs from the home's module copy, as the home's
+    hooks do. For `--soul` it runs from the module in the deployment's module
+    store (the tree `oats <ns> …` dispatch uses). A store tree is used only
+    while its content digest matches the digest verified when it was fetched
+    at the locked commit. A drifted tree is fetched again, and a fetch that
+    does not verify is `E_PACKAGE_INTEGRITY` (the item is `unknown` with that
+    code).
+  - A module without `binding` has no item; the check is `not-applicable`
+    when there are none.
+  - This check reads the provider; it does not bind. A spawn's fail-closed
+    hooks are unchanged.
+- **Removed:** `trusted` and its `signature` block (declaring a package in
+  `packages:` is the trust decision). `--verify-signatures` answers
+  `E_BAD_ARGS`. `enrolled` is now `member`.
+
+`--policy` is **kept**: it means the same without the chain. With `--home` it
+is the instance's recorded, enforced policy (`instance.json` `policy`, plus
+the recorded work mode). With `--soul` it is the soul's declaration
+(`children.spawn`, `work`), `enforced: false`. The shape is unchanged:
+
+```json
+"policy":{"childSpawns":{"allowed":true,"enforced":true,"origin":{"kind":"default","detail":"no declaration: children allowed"}},
+          "worktrees":{"allowed":false,"mode":"directory","enforced":true,"origin":{"kind":"work-mode","detail":"work: directory"}}}
+```
+
+**The provider check wire (the request `binding.check` receives).** The
+request is one JSON line on stdin, and the provider answers one envelope line
+on stdout:
+
+```json
+{"schemaVersion":1,"phase":"check","slot":"knowledge","capability":"oats.okf","settings":{"…":"the merged payload"},
+ "input":{"context":{"kind":"workspace","workspace":"<workspace key>","deployment":"/w","soul":"release-manager","team":"engineering",
+                     "instance":"release-manager-x","home":"/w/agents/…/release-manager-x"},
+          "action":{"kind":"readiness"}}}
+```
+
+```json
+{"schemaVersion":1,"phase":"check","slot":"knowledge","capability":"oats.okf","ok":true,
+ "result":{"status":"ready","problems":[],"warnings":[]}}
 ```
 
-`kind: "none-recorded"` (empty `items`, explanatory `note`) means no soul in the
-scope records a portable **source address** — a soul may still carry a
-`provenance` of kind `packaged-definition` with `source: null`. Say "no portable
-source recorded"; do not infer "local" or "authored" from this state.
-Workspace imports adopted onto a deployment will appear here at their pinned
-revisions when that adoption is recorded on the deployment; nothing is
-enumerated from a source repository that the deployment does not record.
+The environment is the provider's module environment:
+- `OATS_CAPABILITY`, `OATS_SETTINGS`, `OATS_CLI_BIN` and `OATS_WORKSPACE`;
+- the team variables (`OATS_TEAM_*`, `OATS_WORKSPACE_NAME`/`_KEY`);
+- `OATS_AGENT` (the soul), and `OATS_SOUL` when the soul directory is known;
+- for a home, `OATS_INSTANCE` and `OATS_INSTANCE_HOME`.
+
+For a home, `OATS_WORKSPACE_NAME` is `""` until spawn records the workspace
+name (planned).
+
+Ambient `OATS_*`/`PI_*` is removed. For a soul, `instance` and `home` are
+`null`. The answer is decoded by the binding wire's response rules:
+- the process exits 0;
+- stdout is exactly one JSON document within the wire limits;
+- the envelope has exactly `schemaVersion`, `phase`, `slot`, `capability`,
+  `ok` and `result` (or `error`), echoing the request's first four;
+- `result` has `status`, `problems` and optionally `warnings`, and nothing else;
+- `ready` carries no problems;
+- problems and warnings are `{code, message}` strings. Their codes are the
+  provider's own and are not checked against `binding.reasons`.
+
+Anything else is `unknown` (`provider-unavailable`). The check executable must
+resolve (realpath) inside its module directory and be a regular file; otherwise
+the item is `unknown` (`resource-not-found`). The request carries no
+`binding`. A provider whose check
+still requires one answers `invalid-binding`, and readiness reports it as
+`unknown`.
+
+### `oats operation run <layer>:<name> (--home <abs> | --soul <name> [--dir <d>]) [--arg k=v …] --json` → `operationsApi: 2`
+
+```json
+{"operationsApi":2,"operation":"knowledge:inspect","capability":"oats.okf","version":"2.1.3","argv":["okf","inspect"],
+ "cwd":"/w/agents/release-manager/instances/release-manager-x",
+ "target":{"home":"/w/agents/release-manager/instances/release-manager-x","instance":"release-manager-x"},
+ "result":{"documents":[{"label":"Working state (STATE.md)","kind":"markdown","text":"…"}]}}
+```
+
+The provider is the module that fills `<layer>`:
+- for `--home`, the home's module copy, with its recorded settings;
+- for `--soul`, the resolved module, materialized into the deployment's module
+  store if needed.
+
+The rest of the contract is unchanged ([operations contract](design/operations-contract.md)):
+- errors: `E_OPERATION_UNKNOWN`, `E_OPERATION_UNAVAILABLE` (also a
+  `context: "home"` operation without `--home`), `E_CAPABILITY_REQUIRES`;
+- the receipt rules and the `E_OPERATION_TIMEOUT` / `E_OPERATION_RESULT`
+  unconfirmed outcomes.
+
+There is no `E_CAPABILITY_BLOCKED` (no trust gate). `cwd` is the home for a
+`context: "home"` operation, and the deployment otherwise.
+
+**Remote.** `--server` routes as before. The destination must advertise
+`operations` with `operationsApi` 1 or 2; a 0.26 CLI routes to either.
+Payload shapes are the destination kernel's.
+
+## Souls and sources (`oats inspect --json`, `soulsApi: 1`) — removed in 0.26.0
+
+The classic scope document (`souls[].provenance`, `souls[].readiness`, the
+scope's portable `sources`) was removed with the classic config chain.
+`oats inspect` answers only [`soulsApi: 2`](#oats-inspect---home---soul---dir---json-operationsapi-2)
+rows; the soul's declarations are in `oats souls --json`.
 
 ## Instance Git state (`oats instance git|diff`, `instanceGitApi: 1`, OATS 0.24.7+)
 
@@ -258,8 +559,8 @@ deduplicated per run. Where the run launched or targeted an instance, a
 session to open (the existing `oats session` surface); the kernel does not
 copy transcripts. `nextRun`/`lastRun`/`executionStatus` are unchanged. The
 Schedules view (frame 08) renders `recentRuns` as the recent-runs list and the
-transcript pointer as the handoff; captured-policy definitions are preserved
-as they are (definition fields are untouched by this addition).
+transcript pointer as the handoff (definition fields are untouched by this
+addition). A stored captured definition (removed in 0.26) lists as `invalid`.
 
 ### History API 3 (`scheduleHistoryApi: 3`, feature `schedule-read-2`, OATS 0.24.13+) — K8b
 
@@ -332,15 +633,16 @@ executable, runtime packages, child-spawn policy) and returns what the spawn
 
 ```json
 {"spawnPreviewApi":1,"preview":true,"agent":"dev","kind":"persistent","instance":"dev-fix-login","home":"/abs/agents/dev/instances/dev-fix-login",
- "repo":"/abs/repo","work":"worktree","runtime":"claude","model":"opus","modelSource":"soul","launchConfig":null,"yolo":false,"backend":"tmux",
+ "repo":"/abs/repo","work":"worktree","runtime":"claude","model":"opus","modelSource":"explicit","launchConfig":null,"yolo":false,"backend":"tmux",
  "branch":"agents/dev-fix-login","base":{"ref":"HEAD","oid":"<oid>"},"worktree":"/abs/agents/dev/instances/dev-fix-login/work",
  "relation":null,"parentInstance":null,"policy":{"childSpawns":{"allowed":true,"origin":{"kind":"default","detail":"…"}}},
  "executable":"/abs/bin/claude","capabilities":["oats.core"],"skills":["oats-operate","oats-souls"],"task":"…"}
 ```
 
-- **Name / work area**: `instance` is the canonical name (`<agent>-<purpose>`,
-  de-duplicated with `-2`, `-3`…); `home` and `worktree` are the canonical
-  paths. The renderer never derives paths.
+- **Name / work area**: `instance` is the name: by default the derived shape
+  `<agent>-<purpose>` (de-duplicated with `-2`, `-3`…), or exactly the
+  `--name <slug>` the caller gave (see *Instance names* below); `home` and
+  `worktree` are the canonical paths. The renderer never derives paths.
 - **Branch / base** (worktree mode): `branch` defaults to `agents/<instance>`
   (`--branch <name>` overrides; validated); `base` is `--base <ref>` resolved
   to its commit oid (default `HEAD`). `E_BRANCH_EXISTS` and `E_BASE_UNKNOWN`
@@ -376,15 +678,13 @@ the pre-fix marker and is never accepted for dispatch.
   import; `--instructions-file`/`--def-file` refused with `E_BAD_ARGS`). Test:
   the deployment tree is byte-identical after a success, a refusal and an
   unknown-soul preview.
-  **Workspace deployments (0.25.1+) — one stated exception**: the first preview
-  of a workspace soul may populate the deployment's per-commit soul cache
-  (`agents/<soul>/souls/<commit>/`, the swappable `agents/<soul>/soul` pointer,
-  `soulFetched: true` in the result). That cache is derived, content-addressed
-  and idempotent — the same member commit yields the same bytes, a later
-  preview of the same commit writes nothing — and nothing else moves: no lock,
-  no event, no home, no instance. A Desktop treats a preview as
-  side-effect-free for everything it shows; it must not assume the deployment
-  directory's byte-identity across the FIRST preview of a soul or commit.
+  **Workspace deployments (0.26.0+)**: this holds for the FIRST preview of a
+  soul or commit too. A preview reads the soul from the deployment's per-commit
+  cache (`agents/<soul>/souls/<commit>/`) when a spawn already filled it, else
+  fetches it to a temporary copy outside the deployment and removes it
+  (`soulFetched: true` in the result). Only a spawn fills the cache or moves the
+  `agents/<soul>/soul` pointer. (0.25.x previews populated the cache: that stated
+  exception is gone.)
 - **Exact root**: `spawn <soul> --agents-root <abs>` binds the soul to that root
   (as inspect/readiness take it) — no team-soul / capability-agent / importable-
   def fallback; mismatch → `E_SOUL_UNKNOWN`. The preview echoes
@@ -395,7 +695,19 @@ the pre-fix marker and is never accepted for dispatch.
   per-module payload each provider will receive (`{ "<cap>": {…} }`, exactly
   `settings.<cap>` of the preview) — so a confirmed apply binds every
   provider fact (an identity choice, a delivery mode) **by value**; a Desktop
-  that changes a provider field re-previews. `instances[].identity` (status)
+  that changes a provider field re-previews. From 0.26.0 the merged payload
+  includes the manifest's declared setting defaults (`settings.<key>.default`,
+  the lowest layer), and the preview's **`settingsOrigins.<cap>`** maps each
+  leaf of `settings.<cap>` (a JSON pointer, e.g. `/identity/mode`) to
+  `{ kind, at }`: `kind` is `manifest-default` | `workspace` | `soul` |
+  `host` | `spawn` — the last layer that set it. (`workspace-team` no longer
+  appears since teams amendment K: a label's `byTeam` entry is not merged into
+  the settings; it is in `teams[].payload`.) —
+  and `at` names where (`oats.json#/settings/identity/default`,
+  `soul.yaml#/messaging`, `oats-local.yaml#/settings/<cap>`,
+  `--provider <cap>`, …). A Desktop labels `manifest-default` values
+  "Default" from this, instead of hardcoding them (feature
+  **`settings-origins`**). `instances[].identity` (status)
   and `selected.identity` (inspect) carry the served principal a messaging
   provider reported: `{ mode: "local"|"global", alias, team, address|null,
   resident|null, grant?: { id, expiresAt, scopes }, provider }`; absent when
@@ -429,7 +741,12 @@ the pre-fix marker and is never accepted for dispatch.
     immediately after the decision check; a concurrent spawn that lost refuses
     **`E_PLACEMENT_TAKEN`** having touched nothing. Two concurrent applies of
     one decision yield exactly one home. There is no wider lock; this
-    reservation is the guarantee.
+    reservation is the guarantee. Instance names are deployment-wide
+    (0.26.0), so right after its reservation a spawn re-checks the whole agents
+    root: when another soul's concurrent spawn reserved the same name, it
+    removes its own empty reservation and refuses (`E_INSTANCE_NAME_TAKEN` for a
+    `--name`, `E_PLACEMENT_TAKEN` for a derived name). At most one wins, and
+    possibly neither.
   - Gate confirmation AND the exec owner on `spawn-preview-2` +
     `spawn-apply-2` + `spawn-idempotency`; a legacy local request on such a CLI
     is refused by the Desktop (`E_PLAN_REQUIRED`), not routed around the fence.
@@ -468,75 +785,15 @@ the pre-fix marker and is never accepted for dispatch.
   (provider contract), auto-PR (P1/ADE write approval), branch enumeration
   (producer seam).
 
-## Readiness quartet, signatures, enforced policy (`oats readiness`, `readinessApi: 1`, OATS 0.24.8+)
-
-> **0.25 status — the producers below are the 0.24 tier.** The readiness DTO
-> (`readinessApi: 1`) still ships unchanged, but its four checks are *produced*
-> by the classic observers: `installed` by `oats list` over the
-> `.agents/capabilities/installed/` tier, `trusted` by the per-artifact approval
-> that `oats trust` wrote, `configured` by `oats-config.yaml` activation, and
-> `enrolled` by the `oats.yaml` backlink. On a **workspace deployment**
-> (`oats-local.yaml` present) none of those sources exists: nothing is installed,
-> approval is per package version in `oats-lock.json` v3 (`oats sync`), activation
-> is derived (workspace defaults ⊕ soul `capabilities:`), and membership is
-> `oats-membership.yaml` observed over the remotes. `oats list` and `oats trust`
-> are removed verbs (`E_UNKNOWN_COMMAND`), so a `remedy` naming them cannot be
-> run. Treat the field names and producer strings as the stable wire shape they
-> are; for the workspace-model facts read `oats spawn <soul> --preview --json`
-> (`modules[]` with from/commit/digest — the "installed" and "configured"
-> truth), `oats sync --json` `approvalNeeded[]` (the "trusted" truth) and
-> `oats workspace status --json` (the "enrolled" truth). Re-basing the quartet on
-> those producers is an open thread of [the workspace model](#workspace-model-workspaceapi-2);
-> when it lands it will be announced as a new feature name, not a silent change of
-> `readinessApi: 1`.
-
-`oats readiness [--soul <name>] [--home <abs>] [--verify-signatures] [--policy] [--dir <d>] --json`
-is the first-run readiness view (frame 09) and the Capabilities readiness rows
-(frame 04). Every fact is derived from the **same** data `oats inspect` reports
-— never a second opinion — and rolled into four checks:
-
-```json
-{"readinessApi":1,"subject":{"kind":"soul","name":"dev"},"at":"<iso>",
- "checks":{
-  "installed": {"status":"pass","items":[{"subject":"oats.core","status":"pass","required":true,"reason":null,"producer":"oats list","evidence":{"version":"1.1.3","integrity":"sha256-…","origin":"installed"},"remedy":null}]},
-  "trusted":   {"status":"fail","items":[{"subject":"oats.core","status":"fail","required":true,"reason":"executable surface not approved","producer":"artifact approval","evidence":{"integrity":"sha256-…"},"remedy":"oats trust oats.core",
-                                          "signature":{"status":"unknown","signer":null,"reason":"signature verification needs a network fetch; pass --verify-signatures"}}]},
-  "configured":{"status":"pass","items":[{"subject":"oats.core activation","status":"pass","required":true,"producer":"oats-config.yaml","evidence":{"target":"declared","level":"/abs"},"remedy":null}]},
-  "enrolled":  {"status":"not-applicable","items":[{"subject":"workspace membership","status":"not-applicable","required":false,"producer":"oats.yaml","reason":"standalone deployment: no workspace declared in oats.yaml"}]}},
- "summary":{"ready":false,"required":3,"pass":2,"fail":1,"unknown":0},
- "notes":["…"]}
-```
+## Readiness quartet (`readinessApi: 1`) — removed in 0.26.0
 
-- Each check is `pass | fail | unknown | not-applicable`; items carry
-  `subject, status, required, reason, producer, evidence, remedy`. **"Ready" is
-  `summary.ready`**: every *required* item passes (or is not-applicable) and
-  there is at least one required item — never inferred from an empty set.
-- **`installed`**: artifact present, locked, integrity matches. **`trusted`**:
-  executable approval of the exact artifact (`oats trust`). Separately,
-  `signature {status: verified | unsigned | unknown | invalid | not-applicable,
-  signer: {id, label} | null, reason}` — the source commit's **verified Git
-  signature**, named signer or nothing. It is `unknown` unless
-  `--verify-signatures` (a network fetch of that one commit; `git log %G?`);
-  a catalog URL, repository owner or byte hash is never a signer. Render
-  "Trusted · signed by <label>" only for `verified`.
-- **`configured`**: activation for the subject, runtime-package requirements
-  (`missingRequires`), runtime-settings problems. **`enrolled`**: workspace
-  **member admission** (decision §3) — `not-applicable` for a standalone
-  deployment (no `workspace:` in `oats.yaml`), `unknown` until admission is
-  verified against the workspace observation, `pass`/`fail` when it is. Never
-  login, never team registration; "Skip" leaves it not-applicable, never pass.
-  *(The readiness producer still reads the 0.24 `oats.yaml` backlink; under the
-  workspace model membership is `oats-membership.yaml` observed by
-  `oats workspace status` — re-basing this item is an open thread.)*
-- Subject: `--soul <name>` scopes required items to the soul's declared
-  requirements; without it, to the scope's active capabilities.
-
-`--policy` adds the **enforced** policy view with origins:
+The quartet (`installed | trusted | configured | enrolled`), its signature
+verification (`--verify-signatures`, feature `readiness-verify`) and the
+scope subject were removed with the classic config chain. `oats readiness`
+answers only [`readinessApi: 2`](#oats-readiness---home---soul---dir---policy---json-readinessapi-2);
+`--verify-signatures` is `E_BAD_ARGS`.
 
-```json
-"policy":{"childSpawns":{"allowed":false,"enforced":true,"origin":{"kind":"soul","detail":"children.spawn: false in soul.yaml"}},
-          "worktrees":{"allowed":true,"mode":"worktree","enforced":true,"origin":{"kind":"work-mode","detail":"work: worktree"}}}
-```
+### Enforced child-spawn policy (`--policy`)
 
 `childSpawns` is **enforced by the spawn route**: `soul.yaml` may declare
 `children: {spawn: false}`; `oats spawn --allow-child-spawns | --no-child-spawns`
@@ -550,58 +807,6 @@ instance's recorded (enforced) one; with only `--soul` it is the declaration
 (`enforced: false`). It is a lifecycle-authority claim, not an OS sandbox —
 the UI says so.
 
-### Slice-5 producer pins (0.24.9+; all additive — gate items on field presence)
-
-- **`configured` is EFFECTIVE activation.** `activation.enabled` is the resolved
-  verdict for the subject; a capability *declared* for the soul but disabled is
-  `fail` with reason `declared for soul <n> but disabled (…)`. Declaration is
-  never activation.
-- **Trust is not-applicable for data-only capabilities.** The inspect row now
-  carries `health.executableSurface` (manifest commands/hooks/launch env — what
-  `oats trust` approves). No surface → `trusted` item `not-applicable`, reason
-  `no executable surface`, whatever the lock records. This is why a fresh
-  `oats trust <package> --all-capabilities` "skipped" `oats.core` and readiness
-  still said fail before 0.24.9.
-- **Typed linkage on every item**: `capability {id, level, scope}` and
-  `origin {kind: requires|declares|default|inventory, target}`; plus
-  `summary.byCapability[] {capability, origin, required, checks{installed,
-  trusted, configured, enrolled}, ownReady, ready}` — the SAME items regrouped,
-  no second observation. `ownReady` is the capability's own four verdicts;
-  `ready` is `ownReady` AND no **subject-level blocker** — items that belong to
-  no capability (workspace membership, soul declarations) are listed in
-  `summary.subjectBlockers[] {check, subject, status}` and block every row.
-  A per-capability row never says ready while the subject is blocked, and a
-  row's verdict is never promoted to the subject's `summary.ready`. Render
-  per-capability rows from this; never parse subjects.
-- **Selector echo**: `subject.selector` = the arguments **as given, byte-exact,
-  no realpath** — `{kind:"scope", dir|null}` · `{kind:"soul", soul,
-  agentsRoot|null, dir|null}` · `{kind:"home", home, soul, agentsRoot|null}`.
-  Compare with what you sent, byte for byte; never filesystem-normalize a
-  response path. The canonical scope is `subject.context` (may differ from
-  `dir`, e.g. `/var` vs `/private/var` on macOS).
-- **Unreadable member document** (`oats.yaml` unreadable, or `workspace:`
-  present but not a mapping) → `enrolled` item `unknown` with
-  `evidence.file`, never `not-applicable`. A declared backlink stays `unknown`
-  with reason `reciprocal admission not observed …` until the CLI fetches the
-  workspace's members (K11).
-- **Captured homes refuse**: `readiness --home <captured>` →
-  `E_UNSUPPORTED_MODE` (`details.captured: true`) before any current-config
-  interpretation.
-- **`--agents-root <abs>`** is accepted with `--soul` (and with `--home`), as
-  inspect takes it — pin the exact root you admitted.
-- **Signature verification (feature `readiness-verify`)**: `--verify-signatures`
-  is bounded custody — **one total budget per readiness read** (120 s default)
-  shared by every capability's fetch and verify (an exhausted budget refuses the
-  remaining capabilities with `budget-exhausted`, no fetch), each Git child in
-  its own process group and the **whole group** SIGKILLed on timeout or failure,
-  scratch repositories removed on normal exit and on SIGINT/SIGTERM/SIGHUP, `GIT_CONFIG_GLOBAL
-  =/dev/null` + no system config + no prompts/askpass, **only https/ssh**
-  transports. `signature.failure` is `null` or `{code}` from the closed set
-  `transport-not-allowed | fetch-failed | fetch-timeout | budget-exhausted |
-  verifier-failed | verifier-timeout | cannot-check`; `signature.reason` is a
-  fixed sentence, **never stderr**. Gate the *Verify signatures…* action on the
-  feature name; keep it an explicit user action.
-
 ## Lifecycle plans — Stop and Remove (`lifecycleApi: 1`, OATS 0.24.8+)
 
 The Desktop's Stop and Remove confirmations render **plans**: a read-only
@@ -693,6 +898,12 @@ location. The receipt says so:
   nothing is lost; retry or pass `--discard-worktree`.
 - Non-worktree modes report `retention: null`. Quarantine/rollback paths keep
   their removal semantics.
+- A recovery (`workRecovery`, `workRecoveries[]`) is `{path, classes, bytes,
+  outputs?, repoCopy?}` (0.26.0: `bytes`, `outputs`): `bytes` is the recovery's
+  own size; `outputs: {paths: [{path, bytes}], bytes}` names what it copied
+  beyond tracked state — a worktree's untracked and ignored paths, or a
+  directory's work entries — grouped by top-level entry, largest first. Absent
+  when only home bytes were copied.
 - The Remove dialog's "also delete worktree / branch" checkboxes map to these
   two flags; the kernel never touches a PR.
 - **Guarded apply** (what a GUI sends): `oats retire <i> --plan-revision <rev>
@@ -730,7 +941,8 @@ location. The receipt says so:
 `retire-retention`, `readiness`, `spawn-preview`, `instance-events`,
 `schedule-history`, and carries the API integers (`instanceGitApi`, `soulsApi`,
 `lifecycleApi`, `readinessApi`, `spawnPreviewApi`, `eventsApi`,
-`scheduleHistoryApi`). **Gate on these, never on a version string and never by
+`scheduleHistoryApi`, `operationsApi`). In 0.26.0, `soulsApi`, `readinessApi`
+and `operationsApi` are **2** ([the workspace-model inspect](#inspect-readiness-and-operation-run-on-the-workspace-model-operationsapi-2-soulsapi-2-readinessapi-2-oats-0260)). **Gate on these, never on a version string and never by
 optimistic invocation**: an older CLI ignores an unknown `--plan` on `retire`
 and *retires*. Absent feature → the view is unavailable. (`catalog` was the
 0.24 `oats catalog` verb's flag; the verb is removed under the workspace model
@@ -772,13 +984,12 @@ machine in the directory the operator chooses (any existing folder). It writes
 `<dir>/oats-local.yaml` (`{ schemaVersion: 2, workspace: <ref> }`), creates
 `<dir>/agents/` (the instance homes), then runs exactly the `oats sync` body
 over the directory just written — discover over the remotes, confirm
-membership, resolve `packages:`, approve (TTY) or list what needs approval,
-write `oats-lock.json`. It installs nothing, creates no soul, spawns nothing
+membership, resolve `packages:`, write `oats-lock.json`. It installs nothing, creates no soul, spawns nothing
 and writes no `oats-config.yaml`; the member clones and the setup-expert spawn
 are printed as next steps. `<dir>` defaults to cwd; `--dir <d>` is the same
 argument (give it once). `--workspace` is required and must be a ref
 `lib/remote.mjs` parses (`E_REPO_REF`) — checked **before** anything is
-written. Captured selectors are refused (`E_BAD_ARGS`).
+written. Captured selectors are refused (`E_UNSUPPORTED_MODE`: the captured/portable path was removed in 0.26).
 
 ```json
 {"onboardApi":2,
@@ -793,13 +1004,9 @@ written. Captured selectors are refused (`E_BAD_ARGS`).
 ```
 
 - `sync` is the `syncApi: 1` report of the first sync (members, packages,
-  changes, `approvalNeeded`, `problems`); `lock` is the lock it wrote.
-- **Exit `2` with `ok: true`** when `sync.approvalNeeded` is non-empty. Approve
-  non-interactively with `oats sync --dir <dir> --approve <id>@<version> …`
-  (0.25.2+; `<version>` is `approvalNeeded[].version` verbatim — a catalog
-  version, or the full commit OID for a git-pinned package); a Desktop renders
-  `approvalNeeded[].executables` (the digest of the executable set it is
-  approving) and `targets`, then runs that command. Exit `0` otherwise.
+  changes, `problems`); `lock` is the lock it wrote. Exit `0` on success —
+  there is no approval-pending outcome (0.26.0, feature
+  `packages-no-approval`; earlier kernels exited `2` with `approvalNeeded`).
 - `hosting` states decision 26 (the kernel cannot see forge visibility, so it
   reports `hostIsMember` and the rule rather than judging).
 - `next.clone[]` is one row per **confirmed** member (`url` = what the
@@ -822,12 +1029,18 @@ written. Captured selectors are refused (`E_BAD_ARGS`).
 
 ### `oats sync [--dir <d>] --json` → `syncApi: 1`
 
-Discovers, confirms membership, resolves `packages:` to commits, writes
-`oats-lock.json` (lockfileVersion 3), reports. **Exit `2` with `ok: true`** when
-the lock was written but approvals are pending (`approvalNeeded` non-empty).
-Approve with repeatable `--approve <id>@<version>` (0.25.2+, non-interactive;
-`<version>` = `approvalNeeded[].version` verbatim); the interactive prompt is
-the TTY fallback, not the contract. Exit `0` otherwise.
+Discovers, confirms membership, resolves `packages:` to commits + integrity,
+writes `oats-lock.json` (lockfileVersion 3), reports; exit `0` on success.
+**No package approval** (0.26.0, human decision 2026-09-24; feature
+`packages-no-approval`): declaring a package in `packages:` is the trust
+decision. The report has no `approvalNeeded`, package rows no `approved`,
+`changes[]` rows no `approvalNeeded`; there is no prompt and no exit `2`, and
+`--approve` is `E_BAD_ARGS`. A lock written by an earlier kernel keeps working
+(its `approved` records are ignored and dropped on the next write). The fields
+went away without an API-number bump — `syncApi`, `workspaceStatusApi` and
+`capabilitiesApi` stay `1`; the removal is signalled by the feature string
+alone — so a consumer reading `approvalNeeded`, `approval` or `approved` must
+gate that on the absence of `packages-no-approval`.
 
 ```json
 {"syncApi":1,
@@ -839,12 +1052,9 @@ the TTY fallback, not the contract. Exit `0` otherwise.
              "souls":["tools-expert"],"capabilities":["acme-tools-dev"],"publishes":{"package":"acme.tools","version":"0.4.0"}},
             {"key":"github.com/acme/billing","name":"billing","commit":"<oid>","confirmed":false,"status":"no-backlink","detail":"github.com/acme/billing@… has no oats-membership.yaml","team":null,
              "souls":[],"capabilities":[],"publishes":null}],
- "packages":[{"id":"oats.okf","version":"2.1.3","source":"catalog:oats.okf","commit":"<oid>","integrity":"sha256-…","capabilities":["oats.okf"],
-              "approved":{"executables":"sha256-…","at":"<iso>"}},
-             {"id":"acme.tools","version":"0.4.0","source":"git:github.com/acme/tools@v0.4.0","commit":"<oid>","integrity":"sha256-…","capabilities":["acme-deploy","acme-lint"],"approved":null}],
- "changes":[{"id":"acme.tools","from":null,"to":"0.4.0","commit":"<oid>","approvalNeeded":true}],
- "approvalNeeded":[{"id":"acme.tools","version":"0.4.0","commit":"<oid>","executables":"sha256-…",
-                    "targets":["acme-deploy: command apply → bin/acme-deploy.mjs","acme-deploy: hook spawn → bin/acme-deploy.mjs"]}],
+ "packages":[{"id":"oats.okf","version":"2.1.3","source":"catalog:oats.okf","commit":"<oid>","integrity":"sha256-…","capabilities":["oats.okf"]},
+             {"id":"acme.tools","version":"0.4.0","source":"git:github.com/acme/tools@v0.4.0","commit":"<oid>","integrity":"sha256-…","capabilities":["acme-deploy","acme-lint"]}],
+ "changes":[{"id":"acme.tools","from":null,"to":"0.4.0","commit":"<oid>"}],
  "problems":[]}
 ```
 
@@ -854,17 +1064,14 @@ the TTY fallback, not the contract. Exit `0` otherwise.
   capabilities are **not** in `capabilities[]`; the non-collapse rule).
 - `changes[]`: `from` = previously locked version or `null`; `to` = `null` when
   the package was dropped from `packages:` and from the lock.
-- `approvalNeeded[].targets` are human-readable lines
-  (`<cap>: command|hook <name> → <relpath>`); `executables` is the digest an
-  approval would record.
 - `problems[]`: `{ code, path, message, repoKey? }` — per-item discovery
   problems (`E_WORKSPACE_SCHEMA`, `E_TEAM_UNKNOWN`, `E_REMOTE_*`, …). Never an
   abort: an unreadable member directory is a problem of that member.
 - Errors: `E_LOCAL_MISSING`, `E_WORKSPACE_SCHEMA { path, problems[] }`,
   `E_REMOTE_UNREADABLE`, `E_LOCK_SCHEMA`, `E_PACKAGE_MISSING` (catalog has no
   such id), `E_PACKAGE_INTEGRITY { why: "branch" | locked/observed }`,
-  `E_PACKAGE_UNAPPROVED` (approval digest no longer matches),
-  `E_PACKAGE_MANIFEST`, `E_REPO_REF`.
+  `E_PACKAGE_MANIFEST`, `E_REPO_REF`, `E_BAD_ARGS` (`--approve`: package
+  approval was removed).
 
 ### `oats package add <id> <version|git:<repo>@<ref>> | remove <id> [--dir] --json`
 
@@ -896,18 +1103,28 @@ found to check the declaration even though it does not edit it. `E_USAGE`,
  "declaredPackages":["acme.tools","oats.okf"],
  "unsynced":[],
  "stale":[],
- "approval":{"approved":["oats.okf"],"needed":["acme.tools"]},
  "external":[{"source":"git:github.com/oss-collective/experts@<oid>","soul":"security-reviewer","team":"unassigned"}],
- "problems":[]}
+ "problems":[],
+ "warnings":[]}
 ```
 
+`warnings[]` (feature `teams`, also in the `sync` report): `{ code, label,
+souls, paths, message }` — one `unmapped-team-label` per label that is in
+`teams:` but not in `messaging.byTeam`, naming its souls (sorted) and each
+soul's `<repoKey>:<path>#/team`; sorted by label. Never a problem.
+
 `unsynced` = declared in `packages:` but not in the lock (run `sync`);
 `stale` = locked but no longer declared. Read-only: does not write the lock.
+(0.26.0: the `approval` object is gone with package approval.)
 
 ### `oats capabilities [--dir] --json` → `capabilitiesApi: 1` · `oats souls [--dir] --json` → `soulsApi: 1`
 
-Every **non-private** item of every confirmed member, external souls, and
-locked package capabilities, sorted by name then origin. `origin` is the
+Every item of every confirmed member, external souls, and locked package
+capabilities, sorted by name then origin. Souls have no private mode (their
+`private` is always `false`); a repo-owned capability is listed with
+`private: true` — usable only by its own repo's souls. The Desktop shows its
+"Repo owned" section when `version --json` lists the `capabilities-private`
+feature. `origin` is the
 human string (`member <key> @ <8-char commit>` | `package <id> v<version>` |
 `external <key> @ <commit>`); `kind` is the machine field. `team` is the label
 or `"unassigned"`.
@@ -918,7 +1135,7 @@ or `"unassigned"`.
    {"name":"acme-house-style","origin":"member github.com/acme/agents @ 3f2a9c1e","kind":"member","repoKey":"github.com/acme/agents","commit":"<oid>",
     "team":"global","private":false,"path":"capabilities/acme-house-style","layer":null,"version":"0.0.0-workspace"},
    {"name":"oats.okf","origin":"package oats.okf v2.1.3","kind":"package","package":"oats.okf","version":"2.1.3","commit":"<oid>",
-    "team":"unassigned","private":false,"approved":true}],
+    "team":"unassigned","private":false}],
  "problems":[]}
 ```
 
@@ -932,8 +1149,9 @@ or `"unassigned"`.
 ```
 
 Package capabilities of declared-but-unsynced packages are absent until `sync`.
-(`soulsApi: 1` is also the integer of the existing `oats inspect --json`
-declarations block; the two payloads are distinguished by their command.)
+(`oats souls --json` keeps `soulsApi: 1` in 0.26.0: its shape is unchanged.
+The probe's `soulsApi` is **2** because it tracks the `oats inspect --json`
+soul rows. The two payloads are distinguished by their command.)
 
 ### `oats spawn <soul> … --preview --json` — additions (Preview API 2 unchanged)
 
@@ -943,10 +1161,10 @@ between preview and apply is `E_DECISION_STALE`):
 
 ```json
 {"modules":[
-   {"name":"acme-release-tooling","from":{"kind":"member","repoKey":"github.com/acme/agents","commit":"<oid>"},"layer":null,"private":false,
+   {"name":"acme-release-tooling","from":{"kind":"member","repoKey":"github.com/acme/agents","commit":"<oid>"},"layer":null,"private":false,"declares":[],
     "changedSince":{"instance":"release-manager-v2","was":"<old oid>"}},
    {"name":"oats.okf","from":{"kind":"package","package":"oats.okf","version":"2.1.3","commit":"<oid>","integrity":"sha256-…","repoKey":"github.com/awebai/oats-okf"},
-    "layer":"knowledge","private":false,"changedSince":false}],
+    "layer":"knowledge","private":false,"declares":["bindings-file","git-timeout","harvest-model","harvest-runtime","state-dir"],"changedSince":false}],
  "team":"engineering",
  "resolution":"6e3050c0d005879441ab017d",
  "workspace":"github.com/acme/agents",
@@ -956,6 +1174,8 @@ between preview and apply is `E_DECISION_STALE`):
 ```
 
 - `modules[].from` is exactly the `from` recorded in `instance.json` on apply.
+- `modules[].declares`: the manifest's declared setting keys, as in `inspect`
+  (feature `settings-declared`).
 - `changedSince`: `null` (no previous instance of this soul), `false`
   (unchanged since the newest previous instance), or
   `{ instance, was }` (`was` = the previous commit, or `null` when the previous
@@ -982,7 +1202,7 @@ between preview and apply is `E_DECISION_STALE`):
   members or externals), `E_SOUL_AMBIGUOUS { name, repos[] }` (name it
   `<repo>/<soul>`). Resolution errors keep their codes (`E_NOT_A_MEMBER`,
   `E_MEMBERSHIP_UNCONFIRMED { repoKey, reason }`, `E_CAPABILITY_MISSING { hint? }`,
-  `E_CAPABILITY_PRIVATE`, `E_PACKAGE_MISSING`, `E_PACKAGE_UNAPPROVED { id, version, commit }`,
+  `E_CAPABILITY_PRIVATE`, `E_PACKAGE_MISSING`, `E_PACKAGE_INTEGRITY { why: "capabilities", listed, locked }`,
   `E_SLOT_CONFLICT { slot, modules[], reason? }`, `E_SKILL_DUPLICATE { name, modules[] }`,
   `E_COMPATIBILITY { capability, package, version, range, why? }`).
 
@@ -1001,11 +1221,18 @@ Written by materialization inside the spawn transaction; read back by
    "oats.okf":{"from":{"kind":"package","package":"oats.okf","version":"2.1.3","commit":"<oid>","integrity":"sha256-…","repoKey":"github.com/awebai/oats-okf"},
                "commit":"<oid>","digest":"sha256-…","materializedAt":"<iso>"}},
  "providers":{"acme-release-tooling":{},"oats.okf":{"owns":"release-manager","reads":["platform-engineer"],"state-dir":"/Users/ana/.oats/okf"}},
- "workspace":{"key":"github.com/acme/agents","commit":"<oid>","resolution":"<24 hex>","standalone":false,
+ "workspace":{"key":"github.com/acme/agents","name":"acme","deployment":"/Users/ana/acme-workspace","commit":"<oid>","resolution":"<24 hex>","standalone":false,
               "soul":{"repoKey":"github.com/acme/agents","commit":"<oid>","team":"engineering"}},
  "capabilities":[{"id":"oats.okf","capability":"oats.okf","origin":"package:oats.okf@2.1.3","…":"one row per module"}]}
 ```
 
+`workspace.name` (the workspace file's `name`) and `workspace.deployment` (the
+directory holding the deployment's `oats-local.yaml`) are recorded from 0.26.0,
+so a home answers them without discovery: `oats inspect --home` reports the
+recorded name, and `oats operation run --home` hands it to the provider as
+`OATS_WORKSPACE_NAME`. Homes spawned
+before 0.26.0 lack both; the name is then discovered, or `null`.
+
 `workspace.standalone` is `true` when the instance was spawned from the
 **standalone view** (decisions 10/25: a *member* whose workspace could not be
 read — `workspace.key` is then the member repo's key, and `modules` holds the
@@ -1014,9 +1241,14 @@ spawn. The same view is marked `standalone: true` in `oats sync --json` (with
 `workspace.name` = `standalone:<repo>`) and in the roster. `capabilities[]` is
 the per-module row set (`toCapabilityRows`) that `oats inspect`/`status` read.
 
+`soulDir` (0.26.0) is the absolute soul directory the instance incarnates — a
+workspace soul's per-commit copy `<deployment>/agents/<soul>/souls/<commit12>`, or
+the read-only soul inside a capability package — and is what every classic
+lifecycle hook and dispatched command receives as `OATS_SOUL`. Instance homes carry no `soul` link.
+
 `digest` is the sha256 of the copied module tree (`<home>/.oats/modules/<cap>/`);
-`providers.<cap>` is the merged payload (soul ⊕ `oats-local.yaml`
-`settings.<cap>` ⊕ `--provider`), `{}` for a capability with none. Copies live at
+`providers.<cap>` is the merged payload (manifest defaults ⊕ soul ⊕
+`oats-local.yaml` `settings.<cap>` ⊕ `--provider`), `{}` for a capability with none. Copies live at
 `<home>/.oats/modules/<cap>/` and `<home>/.agents/skills/<cap>/<skill>/`.
 
 ### `oats status [--dir] --json` — module drift
@@ -1047,54 +1279,59 @@ top-level `workspace` reachability field:
 - Text mode prints `modules: <cap> from <member|package …> @ <7-char>` lines
   for non-current modules (`--verbose` for all).
 
+### Eligible teams (feature `teams`, OATS 0.26.0)
+
+A soul's `team` may be a list of labels; the first is the primary
+([teams contract](design/2026-09-25-teams-contract.md)). Every label is an
+**eligible** team — which the messaging provider may join on an explicit
+request (a spawn provider setting, or its own join/leave verbs); the kernel
+joins nothing. One entry per label, in soul order:
+
+```json
+{"label":"engineering","team":"aweb:acme.eng","mapped":true,"payload":{"private":"per-human","team":"aweb:acme.eng"}}
+{"label":"reviewers","team":null,"mapped":false,"payload":{"private":"per-human"}}
+```
+
+`payload` = `workspace.messaging` ⊕ `byTeam[label]` (base alone when unmapped);
+`team` = the mapped payload's team id, else `null`. No label → `[]`.
+
+Where it appears:
+- `oats spawn … --preview --json`: top-level `teams` (next to `team`, which
+  stays the primary label). `settings.<messaging>` stays the primary's merged
+  payload and never carries `teams`.
+- `oats inspect --soul|--home --json`: top-level `teams` and `teamsSource`.
+  For `--home` the teams are **live** (the soul's labels and the workspace's
+  `messaging` as the deployment resolves them now, in two repository reads;
+  the home's modules are unchanged): `teamsSource: "live"`, or `"recorded"`
+  with the spawn-time list when the workspace cannot be read now. Providers
+  get the same marker as `OATS_TEAMS_SOURCE`.
+- `instance.json`: `teams` (the spawn-time list, kept as evidence; never
+  rewritten) and `workspace.soul.labels`.
+- `oats souls --json`: each row carries `labels` (`team` stays the primary).
+- A spawn, preview or `inspect --soul` whose labels give one capability
+  different `defaults.byTeam` entries answers `E_TEAM_CONFLICT { capability,
+  labels: [a, b], entries, paths }`.
+
 ### Probe
 
 ```json
-{"…":"…","features":["…","workspace-v2","instance-modules","spawn-provider-payload"],"workspaceApi":2}
+{"…":"…","features":["…","workspace-v2","instance-modules","spawn-provider-payload","packages-no-approval","spawn-name","settings-origins","teams"],"workspaceApi":2}
 ```
 
 A feature is listed only once the binary implements it. Gate `sync`/`package`/
 `workspace status`/`capabilities`/`souls` on `workspace-v2`; gate reading
 `instance.json.modules` and preview `modules[]` on `instance-modules`; gate
-`--provider` on `spawn-provider-payload`.
-
-## Instruction refresh (`oats session recompose`, feature `session-recompose`, OATS 0.24.8+)
-
-A live instance's composed `AGENTS.md` is generated at spawn and outranks any
-mail or tracked file *in the running context*. When a soul changes (a role or
-budget amendment) and a respawn is not possible or wanted, an operator
-refreshes the home in place:
-
-- `oats session recompose --home <abs> [--dry-run] --json` → `{home, instance,
-  agent, soulDir, contextDir, changed, dryRun, blocks[{source,file}], previous,
-  note}`. Same composer spawn used, the home's own `soul` link and recorded
-  context/work mode. `changed:false` is a no-op (no receipt). On change the
-  prior text is retained as `previous` (`<home>/.oats-agents-md.<stamp>.previous`),
-  `instance.json` gains `instructions[]`/`recomposedAt`, and a `recomposed`
-  event is appended.
-- **Nothing is signalled or restarted** — the harness re-reads on its own
-  schedule; the receipt's `note` says so. Refuses a retiring home
-  (`E_INSTANCE_RETIRING`), captured incarnations and capability-defined souls
-  (`E_UNSUPPORTED_MODE`: those are refreshed by a new resolution / package).
-- **Module homes (0.25+) are `E_UNSUPPORTED_MODE` too.** A home whose
-  `instance.json` carries `modules{}` (spawned on a workspace deployment,
-  `instance-modules`) answers `E_UNSUPPORTED_MODE` ("recompose from
-  materialized modules is not supported yet; re-spawn"): its `AGENTS.md` was
-  composed from the soul at a recorded member commit plus the materialized
-  modules' injects, and the instance never changes under itself (decision 7).
-  **Desktop contract (Phase F, F4)**: for a module home, show the drift rows
-  and offer *re-spawn* (preview → apply of the same soul/purpose, then retire
-  the old instance); do not offer "recompose". A kernel recompose for module
-  homes is not planned — an instance never changes under itself.
-  The refresh path for such a home is a new spawn (the soul is re-fetched at
-  the member's current commit). `session-recompose` **stays advertised** in
-  `features[]` because the verb still works for classic homes; gate the UI
-  action on the feature AND on the absence of `instance.json.modules`
-  (`oats status --json` `instances[].modules` is non-empty for a module home),
-  and render the typed refusal otherwise.
-- Gate on `features.includes("session-recompose")`. It is an **operator
-  action** (the human or the instance's parent), never something a Desktop
-  poll or an agent runs on itself.
+`--provider` on `spawn-provider-payload`; gate reading `teams`, `teamsSource`,
+`labels` and `warnings[]` on `teams`; gate reading `declares` on
+`settings-declared`.
+
+## Instruction refresh (`oats session recompose`) — removed in 0.26.0
+
+`oats session recompose` answers `E_UNKNOWN_COMMAND`, and the
+`session-recompose` feature is no longer advertised. An instance never changes
+under itself: the refresh path is a re-spawn (preview → apply of the same
+soul/purpose, then retire the old instance), which fetches the soul at the
+member's current commit.
 
 ## Mutations exposed to Desktop v1
 
@@ -1178,13 +1415,52 @@ Additional informative fields: `repo`, `runtime`, `model`, `parent`,
 was declared, else null), `relation` (`child`/`sibling`/`parent` when a
 relation was declared at spawn, else null), `spawnOrigin`, `attach`.
 
-Stable error codes: `E_USAGE`, `E_NO_DEPLOYMENT`, `E_UNKNOWN_AGENT`,
+Stable error codes: `E_USAGE`, `E_LOCAL_MISSING` (no `oats-local.yaml` in reach:
+a spawn needs a workspace deployment), `E_NO_DEPLOYMENT` (the deployment's
+`agents/` root is missing), `E_SOUL_UNKNOWN`, `E_UNKNOWN_AGENT`,
 `E_AMBIGUOUS_SOUL`, `E_PARENT_NOT_FOUND`, `E_RELATIVE_NOT_FOUND`,
 `E_RELATIVE_AMBIGUOUS` (a `--relative-to`/`--parent` anchor name matches
 multiple team instances — disambiguate with `--relative-root <agents-root>`
 — or the chosen anchor is shadowed by a same-named instance so the lineage
 edge would resolve wrongly), `E_BAD_ARGS`,
-`E_SPAWN_FAILED`.
+`E_INSTANCE_NAME_INVALID`, `E_INSTANCE_NAME_TAKEN`, `E_SPAWN_FAILED`.
+
+**Instance names** (0.26.0, feature `spawn-name`). By default the name is
+derived: `<agent>-<purpose>` with `--purpose <slug>`, else `<agent>-<n>`.
+`--name <slug>` (human decision 2026-09-24) is the explicit opt-in: the
+instance name is **exactly** `<slug>`, with no `<agent>-` prefix.
+
+- `--name` and `--purpose` are mutually exclusive (`E_BAD_ARGS`), and
+  `--name` needs a value (`E_BAD_ARGS`).
+- The name is never rewritten. Input that is not already a slug (lowercase
+  letters and digits, single dashes between them) is
+  `E_INSTANCE_NAME_INVALID`, and so is a name equal to any soul name of the
+  deployment (souls on the agents root, and every soul the workspace
+  declares, fetched or not). Soul and instance references stay unambiguous.
+- **Instance names are at most 64 characters** (0.26.0; the tightest
+  consumer is the messaging alias, which allows 1–64). This covers every
+  name, explicit and derived. A longer name is `E_INSTANCE_NAME_INVALID`
+  ("instance names are at most 64 characters"), in preview and apply alike,
+  and is never truncated. For a derived name the refusal names the purpose
+  to shorten, and the de-duplication suffix counts: when `<agent>-<purpose>`
+  is taken and `<agent>-<purpose>-2` would exceed 64, the spawn is refused.
+- **Names are unique across the deployment.** An explicit name that any
+  `<agents-root>/<soul>/instances/` already holds (including homes whose soul
+  was since removed), or that a live window in the target tmux session carries
+  (tmux backend, launched or `--no-launch`), is `E_INSTANCE_NAME_TAKEN`
+  (`details.instance`, `details.home` or `details.session`). There is never a
+  silent `-2` for a name the operator typed. These checks run after
+  idempotency-key recovery (a keyed retry replays its receipt), and a
+  concurrent spawn of another soul under the same name is caught after
+  placement (see *Exclusive placement*). The invariant covers spawns through
+  the CLI. Homes from earlier kernels may already share a name.
+- Derived names de-duplicate deployment-wide too (`-2`, `-3`, …), against
+  every soul's instances and every soul name. Two souls never derive the same
+  name (soul `a` with `--purpose b-c` against soul `a-b` with `--purpose c`).
+- `--preview` reports the final name (`instance`, `decision.instance`) and
+  refuses with the same codes. The name is part of the decision revision, so
+  `--expect-decision` binds it: another name under a confirmed decision is
+  `E_DECISION_STALE`.
 
 Dispatch-level failures (any `--json` command): `E_UNKNOWN_COMMAND` (no
 kernel subcommand or capability namespace matches, or unknown capability