@awebai/oats 0.29.4 → 0.30.0

package/docs/release-notes/v0.26.0.md

@@ -1,670 +1,199 @@
 # OATS 0.26.0
 
-The workspace model is the only model the kernel knows ("v2 becomes the
-classic"). The 0.24-era classic path is removed, not flagged: a 0.24.x kernel
-keeps running 0.24.x deployments, and a 0.25.x deployment is already v2
-(the 0.24 → 0.25 rebuild guide is removed in this release; see
-[Upgrading from 0.25](#upgrading-from-025)).
+The workspace model is the only model the kernel knows. The 0.24-era classic
+path is removed, not flagged: a 0.24.x kernel keeps running 0.24.x
+deployments, and a 0.25.x deployment is already on the workspace model. See
+[Upgrading from 0.25](#upgrading-from-025).
 
 ## Removed
 
-- **The captured/portable path** (0.24–0.25's `oats prepare`, captured
-  resolutions, `--deployment --resolution` dispatch, the pi SDK host and
-  versioned schedules; lead decisions on (e)). Nothing on the workspace path
-  used it, as coverage of the v2 flows showed. What is left of it is typed
-  refusals, none falling back to the workspace path:
-  - The 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`). That includes the captured `oats trust
-    --deployment|--artifact-set`.
-  - `oats prepare` and `oats inspect --request` are removed verbs
-    (`E_UNKNOWN_COMMAND`, `details: {removed, replacement}`): `oats onboard` /
-    `oats sync` set a workspace up, and `oats spawn <soul> --preview` shows
-    what a spawn would resolve.
-  - `oats version --json` no longer carries `capturedDispatchApi` or
-    `capturedDispatchActions`.
-  - **Captured homes** (an `instance.json` recording `executionBinding`,
-    `incarnationId` or `captured`) have no 0.26 runtime. `oats status` and
-    `oats doctor` report them once as the problem **`legacy-captured-home`**
-    (JSON `problems[]`: `{instances, homes, message}`). Session start/restart,
-    `inspect|readiness|operation --home` and in-home commands refuse them
-    (`E_UNSUPPORTED_MODE`, `details: {home, captured: true}`). **`oats retire`
-    works, but their captured retire hooks do not run:** the result's
-    `warnings[]` (also printed by the human output) names each capability whose
-    spawn hook ran, since identities/memberships it created are not revoked —
-    remove them with the provider's own tooling.
-  - **Captured schedule definitions** (`definitionVersion`, `recurrencePolicy`,
-    `execution`, `preparation`) are refused by `schedule add|update`
-    (`E_SCHEDULE_INVALID`, the key as `field`), locally and before any
-    `--server` forwarding. A command argv carrying a captured selector is
-    refused too. A stored one is `invalid` on its own job and never runs, and a
-    captured attempt or job lock left by 0.25 is reported on its job and never
-    run or adopted: `oats schedule remove --force <id>` clears it (a held lock
-    keeps its launch slot until then). The run outcome `blocked` is no longer
-    produced.
-  - **Manifest keys:** `helperInjection` and hook `inputs` are accepted and
-    ignored (existing manifests still load).
-  - **Public core exports removed with it** (no in-repo consumer):
-    `capabilityArtifactIntegrity`, `OATS_LOCK_FILE`, `CAPABILITIES_DIRNAME`,
-    `INSTALLED_SUBDIR`, `CAPABILITY_ID_RE`, `isMaterializedCapabilityId`,
-    `capabilityIdViolation`, `CAPABILITY_INSTALLATION_FILE`,
-    `normalizePackagePath`, `validateLockEntry`, `validateCapabilityLockEntry`,
-    `verifyCapabilityInstallation`, `loadPackageManifestAt`,
-    `assertCapabilitySelfContained`, `materializeCapabilityDeps`,
-    `platformVariantLockPackages`, `isCanonicalTemplatePath`, and every
-    captured/portable export (`startCapturedInstanceSession`,
-    `prepareCapturedComposition`, `loadCapturedDispatch`, …).
-  - **Schemas removed:** `portable`, `captured-resolution`,
-    `captured-invocation-context`, `execution-capsule`, `artifact-approvals`,
-    `oats-lock-v3` (the captured *selection* lock, never the workspace lock) and
-    `oats-lock` (lockfileVersion 2), plus `provider-check-input` (the captured
-    check request; the workspace readiness request is documented in
-    [capabilities](../capabilities.md#readiness-check-bindingcheck)). The design
-    notes `package-engine-contract.md` and `package-runtime-api.md` are deleted.
-  - Errors from kernel metadata reads say "metadata file", not "portable
-    metadata".
-  - **Kernel skills and injects** (human decision on D7): `oats-portable`,
-    `oats-portable-artifacts` and the injects `oats-portable`,
-    `portable-instance-boundary` and `portable-work-directory` are deleted, and so
-    are the kernel's own **`oats` skill** and **`injects/oats.md`** ("You run on
-    OATS"): the `oats.core` capability (`oats.framework` package, the workspace
-    default) ships the operating skills (`oats-operate`, `oats-souls`) and that
-    briefing, and the workspace path already composed only its copy. A soul
-    without `oats.core` gets no OATS operating instructions; `oats doctor --soul`
-    says so. The kernel keeps `instance-boundary`, the `work-*` briefings and the
-    ambient `oats-getting-started`.
-
-- **Package approval** (human decision, 2026-09-24). People install a package
-  only when they trust it: declaring it in the workspace's `packages:` IS the
-  trust decision, so there is no second, per-version approval step.
-  - `oats sync` resolves, fetches, verifies integrity, writes the lock and exits
-    `0` on success. No exit `2` for pending approvals, no interactive prompt, no
-    `approvalNeeded` in the report and none on `changes[]` rows.
-    `oats sync --approve …` is `E_BAD_ARGS` naming the decision.
-  - `oats onboard` has no approval-pending outcome and no "approve first" hint.
-  - The lock (v3) drops the per-entry `approved` record. A lock that still
-    carries it is read with the field ignored, and the next write drops it.
-    **A kernel before 0.26.0 cannot read a lock 0.26.0 wrote** (`E_LOCK_SCHEMA`
-    on the missing `approved`): keep every kernel that reads one deployment on
-    0.26.0 or later.
-  - The lock still pins each package to its exact commit and content integrity.
-    `oats sync` refuses a moved tag, drifted content and a lock whose capability
-    list no longer matches the package (`E_PACKAGE_INTEGRITY`) —
-    reproducibility, not approval.
-    **Where integrity is checked:** `oats sync` recomputes each package's
-    content digest and refuses drift. At spawn, the kernel checks the lock's
-    capability list against the package and trusts the locked commit plus
-    materialize's fetch-versus-copy self-check. The lock's integrity is
-    recorded in each module's `from`, not recomputed per spawn. (The removed
-    per-spawn executables-digest check was an approval binding, not an
-    integrity guarantee.)
-  - Spawn, `--preview` and operator dispatch never raise `E_PACKAGE_UNAPPROVED`;
-    the executables-digest gate is gone. At spawn a package capability must come
-    from a package the workspace **still declares** (a stale lock entry for a
-    package removed from `packages:` is `E_PACKAGE_MISSING { reason:
-    "undeclared" }` until `oats sync`), and the lock's capability list must match
-    what the package declares at the locked commit (`E_PACKAGE_INTEGRITY { why:
-    "capabilities" }`). A package capability agent is found only in a declared
-    package.
-  - `oats workspace status` loses its `approval` object and column; `oats
-    capabilities` package rows lose `approved`; `oats doctor` prints each locked
-    package's integrity instead of its approval.
-  - `oats version --json` advertises `packages-no-approval`. `syncApi`,
-    `workspaceStatusApi` and `capabilitiesApi` are NOT bumped: a consumer that
-    reads the removed fields gates on this feature string.
-- **The `soul` link in instance homes.** A home no longer carries
-  `<home>/soul`: its composed `AGENTS.md` already holds the soul's
-  instructions. The soul directory an instance incarnates is recorded as
-  `instance.json` `soulDir` (a workspace soul's per-commit copy
-  `<deployment>/agents/<soul>/souls/<commit12>`, or the read-only soul inside a
-  capability package) and is handed to every classic lifecycle hook — spawn,
-  launch, retire — and to every capability command dispatched inside a home as
-  `OATS_SOUL`. Launch
-  and retire hooks, and in-home commands such as `oats okf harvest`, previously
-  received no `OATS_SOUL`; `oats operation run`
-  previously handed the swappable `agents/<soul>/soul` pointer. `oats session
-  recompose` reads the recorded `soulDir`. A spawn that is rolled back into
-  quarantine records the soul in its cleanup descriptor, so a retried retire
-  hook sees the spawn's soul. A capability command dispatched with no recorded
-  soul gets no `OATS_SOUL`, never one inherited from the invoking process.
-  - **Homes spawned before 0.26.0** record no `soulDir`. They keep their
-    existing `soul` link (0.26.0 neither reads nor removes it). Their retire
-    hooks get the soul pointer `agents/<soul>/soul` (today's soul, not
-    necessarily the spawn's commit). They are degraded: their launch hooks and
-    in-home commands get no `OATS_SOUL` (a provider that requires it, such as
-    oats.okf 2.1.5, refuses with `E_OATS_SOUL_MISSING`), and `oats session
-    recompose` refuses them (`E_SOUL_UNKNOWN`). Re-spawn to get a recorded
-    `soulDir`.
-
+- **The captured/portable path** (`oats prepare`, captured resolutions,
+  `--deployment --resolution` dispatch, the pi SDK host, versioned schedules).
+  What is left are typed refusals:
+  - The selectors `--deployment`, `--resolution`, `--artifact-set` and an
+    inherited `OATS_DEPLOYMENT` / `OATS_RESOLUTION` are `E_UNSUPPORTED_MODE`
+    for every command but `version`. `oats prepare` and `oats inspect
+    --request` are `E_UNKNOWN_COMMAND`, naming `oats onboard` / `oats sync` and
+    `oats spawn <soul> --preview`.
+  - **Captured homes** are reported as the problem `legacy-captured-home` and
+    refused by start, restart, `--home` reads and in-home commands. `oats
+    retire` works but runs no captured retire hook; its `warnings[]` name the
+    capabilities whose identities to revoke with the provider's tooling.
+  - **Captured schedule keys** are refused by `schedule add|update`
+    (`E_SCHEDULE_INVALID`); a stored captured job or lock never runs until
+    `oats schedule remove --force <id>` clears it.
+  - Manifest keys `helperInjection` and hook `inputs` are accepted and
+    ignored. `oats version --json` drops `capturedDispatchApi` and
+    `capturedDispatchActions`. The captured/portable core exports, the
+    installed-tier and lock v2 helpers, and their schemas (including
+    `oats-lock` lockfileVersion 2 and `provider-check-input`) are removed.
+- **Kernel skills, injects and the operational block.** The kernel's `oats`,
+  `oats-config`, `oats-packages` and portable skills, and its "You run on
+  OATS" and portable injects, are deleted. `oats.core` (the `oats.framework`
+  package, the workspace default) ships the operating skills and briefing,
+  `oats.setup` the setup skills. A soul without them gets no OATS operating
+  instructions (`oats doctor --soul` says so). The kernel keeps
+  `instance-boundary`, the `work-*` briefings and `oats-getting-started`.
+- **Package approval.** Declaring a package in `packages:` is the trust
+  decision. `oats sync` exits `0` on success (no exit `2`, prompt or
+  `approvalNeeded`; `--approve` is `E_BAD_ARGS`), and `oats onboard` has no
+  approval step. `E_PACKAGE_UNAPPROVED` is gone. Lock v3 drops `approved`
+  (ignored on read, dropped on write). **A kernel before 0.26.0 cannot read a
+  lock 0.26.0 wrote** (`E_LOCK_SCHEMA`): keep every kernel of a deployment on
+  0.26.0 or later. The lock still pins commit and content integrity
+  (`E_PACKAGE_INTEGRITY`); a package no longer declared is `E_PACKAGE_MISSING`
+  at spawn until `oats sync`. The `approval`/`approved` fields leave `oats
+  workspace status` and `oats capabilities`. Gate on the feature
+  `packages-no-approval`; the API integers are not bumped.
+- **The `soul` link in instance homes.** `instance.json` records `soulDir`,
+  handed as `OATS_SOUL` to every spawn, launch and retire hook and to in-home
+  capability commands (launch and retire hooks and in-home commands had none
+  before). A command with no recorded soul gets no `OATS_SOUL`. Homes spawned
+  before 0.26.0 keep their link; their launch hooks and in-home commands get no
+  `OATS_SOUL` (oats.okf 2.1.5 refuses with `E_OATS_SOUL_MISSING`): re-spawn
+  them.
 - **Local souls and `local-agents/`.** A soul is a member repository's
-  `souls/<name>` (`soul.yaml` + `AGENTS.md`); there are no machine-local souls.
-  - **`oats create` is removed**: `E_UNKNOWN_COMMAND` naming the replacement
-    (author `souls/<name>/soul.yaml` + `AGENTS.md` in a member repository, then
-    `oats sync`). `--local`, `--type` and the `.gitignore` injection went with it.
-  - **`oats spawn --instructions-file` and `--def-file`** (which wrote a local
-    soul, including from a `.claude/agents` definition) are refused with
-    `E_BAD_ARGS` naming the same replacement. `oats status` no longer lists
-    importable definitions.
-  - The kernel no longer composes the local-soul instruction block.
-  - **`soul-scaffold` hooks are no longer run** (souls are authored in member
-    repositories); manifests may still declare it until providers drop it.
-  - **Capability-defined agents** (a package's or member module's `agents/`,
-    such as the OKF harvester) now home at
-    `<deployment>/agents/<agent>/instances/<name>`, like souls. That directory
-    holds only `instances/`. A name that is both a workspace soul and a
-    capability agent stays `E_SOUL_AMBIGUOUS`.
-  - The agents root is found only as the closest `agents/` (or
-    `PI_AGENTS_ROOT`); a `local-agents/` beside it no longer locates one.
-- **OAS scope probes.** `oats doctor` no longer looks for un-migrated OAS
-  scope files, and the dead `docs/migration-from-oas.md` links went with the
-  probe.
-- **The installed tier.** `oats doctor` loses its installed-packages section.
-  The restore, remove, lock-migration and installed config-template readers
-  are deleted with it.
-- **Classic verbs** (lead decision 3). Each answers a typed refusal naming
-  its replacement:
-  - `oats type` and `oats soul set` are removed verbs (`E_UNKNOWN_COMMAND`).
-    A soul is edited in its member repository (`soul.yaml` + `AGENTS.md`),
-    then `oats sync`; per-spawn choices are spawn flags or a launch
-    configuration. `soul` no longer routes with `--server`.
-  - `oats session recompose` is `E_UNKNOWN_COMMAND`, and the
-    `session-recompose` feature is no longer advertised. The refresh path is
-    a re-spawn: an instance never changes under itself.
-  - `oats status --team` is `E_BAD_ARGS`: `oats status` in the deployment
-    lists every instance, and `oats workspace status` shows the members.
-- **The classic answers of `oats inspect`, `oats readiness` and `oats
-  operation run`** (lead decision 4). There is no v1 shape any more. With no
-  `oats-local.yaml` in reach and no `--home` they 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`. `--verify-signatures` is
-  always `E_BAD_ARGS`, and the signature verifier is deleted.
-
-- **`oats-config.yaml` and the scope configuration chain** (lead decisions
-  c3 1–7, 9). The kernel reads no `oats-config.yaml`. One found between a
-  command's directory and its deployment (the directory holding
-  `oats-local.yaml`) is refused, `E_CONFIG_BROKEN` (`reason:
-  "legacy-config"`), naming where each key went; with no `oats-local.yaml` in
-  reach, `E_LOCAL_MISSING` names the file as a 0.25 deployment's.
-  `docs/oats-config.schema.json` is deleted (below). Each key:
-  - **`capabilities:`** (`layers:`, `additive:`, targets, `from:`,
-    `injection-override:`) and **`agent-types:`**: a soul's capabilities are
-    the workspace's resolution — `oats-workspace.yaml` `defaults:` and each
-    soul's `soul.yaml` `capabilities:` / slot keys, then `oats sync`.
-  - **`team:`**: teams are `oats-workspace.yaml` `teams:` and a soul's
-    `team:`. Hooks get the workspace facts only: `OATS_TEAM_SCOPE` (the
-    deployment), `OATS_TEAM_ID` (the messaging payload's `team`),
-    `OATS_TEAM_LABEL`, `OATS_WORKSPACE_NAME`, `OATS_WORKSPACE_KEY`;
-    `OATS_TEAM_NAME` is always empty. Operator-level capability commands get
-    the same five.
-  - **`work-modes:`**: a soul's `work:` and the spawn flags decide the mode. A
-    worktree `setup:` script no longer runs (run it yourself, or from a
-    capability's spawn hook); `retirement-disposable:` is gone with it (a
-    capability's manifest `retirement.disposable` still applies).
-  - **`agents-md-injection:`**: removed. Instructions come from the soul and
-    its modules' injects.
-  - **`skill-overrides:`**: removed. A duplicate skill name is
-    `E_SKILL_DUPLICATE`; there is no override.
-  - **Scope `yolo:`**: removed. Yolo is `--yolo` on `oats spawn`, `session
-    start` and `session restart`, or a launch configuration's `yolo`.
-  - **`launch-configs:`**: moved to `oats-local.yaml` (see Changed).
-  - **`oats:` `injection-override:`**: removed with the kernel's operational
-    block (below).
-- **Scheduling a capability agent by name.** A `kind: "spawn"` schedule's
-  `agent` is a soul under the deployment's `agents/` root only; the fallback
-  to a capability-defined agent (a harvester, a reviewer) is gone with the
-  config chain (`E_SCHEDULE_INVALID`, `agent: no soul named …`). Schedule what
-  spawns it instead: a `kind: "command"` job running the capability's own
-  command (for example `oats okf harvest --soul <soul>`), or a
-  `kind: "operation"` job running the provider operation on the anchor home.
-- **Spawning without a workspace deployment.** `oats spawn` with no
-  `oats-local.yaml` in reach is `E_LOCAL_MISSING` naming `oats onboard`
-  (0.25 answered `E_NO_DEPLOYMENT`, which now means only a deployment whose
-  `agents/` root is missing); the kernel's `spawnInstance` without a prepared resolution refuses the same
-  way (`spawnInstanceAsync` with `prepared` is the one spawn).
-- **v1 soul fields.** A soul's `runtime`, `model`, `backend`, `repo`, `yolo`,
-  `launch-config`, `children` and `requires:` are not read (the v2 soul schema
-  already refuses them at discovery; lead decision c3 Q6). They are spawn and
-  host choices: `--runtime`, `--model`, `--backend`, `--repo`, `--yolo`,
-  `--launch-config` / `oats-local.yaml` `launch-configs:`, and
-  `--allow-child-spawns` / `--no-child-spawns` (a recorded child-spawn policy's
-  origin is `spawn-option` or `default`, never `soul`). An attached instance
-  works in its work tree owner's recorded repository. A capability agent's own
-  `soul.yaml` (for example `oats.review`'s reviewer) still names its default
-  `runtime`, `model` and `work`.
-- **The kernel's operational block and bundled skills** (lead decision c3 9).
-  A soul whose resolution has no `oats.core` or `oats.setup` module no longer
-  gets the kernel's "You run on OATS" block or the `oats`, `oats-config` and
-  `oats-packages` skills copied into its home; operational knowledge is the
-  `oats.core` / `oats.setup` capabilities'. The `skills/oats-config` and
-  `skills/oats-packages` directories are deleted.
-- **Session start, restart and capability commands on homes from an earlier
-  kernel** (lead decision c3 Q2). A home whose `instance.json` records no
-  `modules` answers `E_UNSUPPORTED_MODE` ("re-spawn it from the deployment").
-  **`oats retire` still works on it**: no retire hook runs (the home records
-  none), and the result's `warnings` says so.
-- **The conversion of a home that predates launch recipes** (lead decision
-  c3c). `oats launch-config preview --home` still describes such a home as
-  recorded (`selection.source: "frozen-command"`). Under a selection
-  (`--runtime`, `--launch-config`, `--model`, `--yolo`/`--no-yolo`) it answers
-  `E_LAUNCH_LEGACY` ("re-spawn it from the deployment; nothing was changed")
-  instead of converting the recorded command.
-- **Classic `oats doctor`, schedule scope and team roots.** `oats doctor` is
-  the workspace-model doctor only (`E_LOCAL_MISSING` with no deployment in
-  reach; `--dir` is honoured). A schedule belongs to the deployment directory:
-  with none in reach, `oats schedule` is `E_LOCAL_MISSING`, never an ambient
-  `OATS_ROOT` / `PI_AGENTS_ROOT` scope. A deployment has one agents root; the
-  cross-repository team roots (and `--parent` across them) are gone.
-- **The framework repository's root `oats-config.yaml`** and its only reader,
-  `injects/framework-workspace.md`. The kernel refuses an `oats-config.yaml`
-  between a command's directory and its deployment, so every instance whose
-  work tree is a checkout of this repository failed every `oats` command; the
-  root `oats-workspace.yaml` and `oats-membership.yaml` are the repository's
-  config, and `scripts/validate-project.mjs` refuses a root `oats-config.yaml`.
-  **Consequence:** a classic deployment rooted at a checkout of this repository
-  (its root holds `agents/` and a 0.24/0.25 kernel reads the root
-  `oats-config.yaml`) can spawn no new instance from that root once it pulls
-  this change. Existing homes keep running and retire normally; the rebuild is
-  `oats-local.yaml` + `oats onboard` on 0.26.0.
-- **The classic-era guides:** `docs/rebuild-to-v2.md` (the 0.24 → 0.25 rebuild
-  guide) and its skill form, `oats.setup`'s `oats-rebuild`;
-  `docs/operating-team-migration.md`; `docs/knowledge-migration.md` (OKF v1 →
-  v2 for 0.23); `docs/workspace-adoption.md`; `docs/first-team-demo.md`;
-  `docs/2026-09-03-architecture-proposal.md`. The catalog-pinned workspace
-  example moved to [packages.md](../packages.md#declaring-packages-two-forms-in-one-place),
-  where a test keeps its pins equal to `package-catalog.json`.
-- **`docs/oats-config.schema.json`**, the record of what 0.25 read.
-- **Kernel helpers of the v1 catalog migration:** `describeOfficialCatalog`
-  (with its `oats install` acquire argv and approval notes) and
-  `officialCapabilityPackage` (the `marketplace:` → package mapping);
-  `officialCatalogFile` names the effective catalog file. `findRoot` no longer
-  treats an `oats-config.yaml` without `agents/` as a package-only deployment
-  root; a deployment without `agents/` gets `ensureRoot`'s `oats-local.yaml`
-  remedy.
-- **The repository's root `log.md`** (the stale 0.24.2 working log).
-- **The "marketplace" name** for the official list: `docs/official-marketplace.md`
-  is [official-catalog.md](../official-catalog.md), and the catalog's `policy`
-  field points there.
+  `souls/<name>`. `oats create` is `E_UNKNOWN_COMMAND`, and `oats spawn
+  --instructions-file` / `--def-file` are `E_BAD_ARGS`, naming the
+  replacement (author the soul in a member repository, then `oats sync`).
+  `soul-scaffold` hooks no longer run. Capability-defined agents home at
+  `<deployment>/agents/<agent>/instances/<name>`; the agents root is the
+  closest `agents/` (or `PI_AGENTS_ROOT`).
+- **Classic verbs.** `oats type`, `oats soul set` and `oats session recompose`
+  are `E_UNKNOWN_COMMAND` (edit the soul in its repository; re-spawn to
+  refresh). `oats status --team` is `E_BAD_ARGS`.
+- **`oats-config.yaml` and the scope configuration chain.** One found between
+  a command's directory and its deployment is `E_CONFIG_BROKEN` (`reason:
+  "legacy-config"`); with no `oats-local.yaml` in reach, `E_LOCAL_MISSING`
+  names it. Where each key went:
+
+  | 0.25 key | 0.26.0 |
+  | --- | --- |
+  | `capabilities:`, `agent-types:` | `oats-workspace.yaml` `defaults:` and `soul.yaml`, then `oats sync` |
+  | `team:` | `oats-workspace.yaml` `teams:` and a soul's `team:` |
+  | `work-modes:` | a soul's `work:` and spawn flags; a worktree `setup:` script no longer runs |
+  | `yolo:` | `--yolo`, or a launch configuration's `yolo` |
+  | `launch-configs:` | `oats-local.yaml` (see Changed) |
+  | `agents-md-injection:`, `skill-overrides:`, `injection-override:` | removed; a duplicate skill is `E_SKILL_DUPLICATE` |
+
+  Hooks get the team facts `OATS_TEAM_SCOPE`, `OATS_TEAM_ID`,
+  `OATS_TEAM_LABEL`, `OATS_WORKSPACE_NAME` and `OATS_WORKSPACE_KEY`
+  (`OATS_TEAM_NAME` is always empty). A classic deployment rooted at a checkout
+  of the OATS repository can spawn nothing from that root once it pulls this
+  release (its root `oats-config.yaml` is gone); rebuild it with `oats
+  onboard`.
+- **v1 soul fields** (`runtime`, `model`, `backend`, `repo`, `yolo`,
+  `launch-config`, `children`, `requires:`) are not read; use spawn flags,
+  launch configurations and `--allow-child-spawns` / `--no-child-spawns`.
+- **Classic answers and scopes.** With no `oats-local.yaml` and no `--home`,
+  `oats inspect`, `readiness`, `operation run`, `doctor`, `spawn` and
+  `schedule` answer `E_LOCAL_MISSING` (`E_NO_DEPLOYMENT` now means only a
+  missing `agents/` root); an unreadable `--home` is `E_SESSION_UNKNOWN`.
+  `--verify-signatures` is always `E_BAD_ARGS`. A
+  deployment has one agents root; cross-repository team roots are gone.
+- **Homes from an earlier kernel** (no `modules` in `instance.json`) answer
+  `E_UNSUPPORTED_MODE` to start, restart, `--home` reads and capability
+  commands; `oats retire` still works, runs no retire hook and says so. `oats
+  launch-config preview --home` under a selection answers `E_LAUNCH_LEGACY`.
+- **Scheduling a capability agent by name.** A `kind: "spawn"` schedule names
+  a soul; schedule the capability's command (`kind: "command"`, for example
+  `oats okf harvest --soul <soul>`) or operation instead.
+- **Leftovers:** the OAS scope probes, the installed tier, the v1 catalog
+  migration helpers, and the classic-era guides (including the 0.24 → 0.25
+  rebuild guide). The catalog-pinned workspace example is in
+  [packages.md](../packages.md#declaring-packages); the official list is the
+  [official catalog](../official-catalog.md), no longer "marketplace".
 
 ## Known limitations
 
 - **A scheduled wake's session start uses the spawn-time teams**
-  (`OATS_TEAMS_SOURCE=recorded`), because the scheduler reads no remote. Its
-  launch hook therefore leaves no team. The next operator
-  `oats session start|restart`, or messaging command, is live.
-
-- **Joining teams beyond the personal one needs a later oats.aweb.** 0.26.0
-  bundles and pins **oats.aweb 1.13.1**: every instance gets its primary aweb
-  identity in the personal team (the aweb root's active team, or
-  `settings.oats.aweb.team`; see teams amendment K under Changed), and the
-  kernel hands the provider `OATS_TEAMS`, but 1.13.1 joins no further team.
-  The team verbs (`messaging:teams|join|leave`, and `join=` at spawn) arrive
-  with oats.aweb 1.14.x, pinned in a 0.26.x patch. There, joined teams **poll**
-  (their mail is read between tasks); live receive for joined teams is planned
-  for oats.aweb 1.15.
-- **A per-workspace personal team** (one personal team per person per
-  workspace) needs aweb server support that is not yet deployed. Until then,
-  "personal" is the person's active aweb team, shared across that person's
-  workspaces.
+  (`OATS_TEAMS_SOURCE=recorded`), so its launch hook leaves no team. The next
+  operator start, restart or messaging command is live.
+- **The bundled oats.aweb 1.13.1 joins no team beyond the personal one** (the
+  aweb root's active team, or `settings.oats.aweb.team`), though the kernel
+  hands it `OATS_TEAMS`.
+- **"Personal" is the person's active aweb team,** shared across that
+  person's workspaces.
 
 ## Upgrading from 0.25
 
-- **Retire classic instances with 0.25, then onboard the deployment with
-  0.26.** A 0.25 deployment configured by `oats-config.yaml` is refused by
-  0.26.0 (`E_CONFIG_BROKEN` / `E_LOCAL_MISSING`, above). With the 0.25 kernel,
-  retire its instances; then, with 0.26.0, write the deployment's
-  `oats-local.yaml` (`oats onboard`), move what the old file declared into
-  `oats-workspace.yaml` and each soul's `soul.yaml`, delete `oats-config.yaml`,
-  and run `oats sync`. Homes left behind still retire under 0.26.0, but
-  **no retire hook runs for them** (a pre-workspace home records no capability
-  hooks): a messaging identity the 0.25 retire hook would have revoked stays
-  live. Retire classic instances with the 0.25 kernel first, or revoke their
-  identities by hand after retiring them with 0.26.0.
-- **Retire capability-agent instances before upgrading.** Instances homed
-  under `<deployment>/local-agents/` (running knowledge harvesters, for
-  example) are not managed by 0.26.0: it never reads, spawns into or retires
-  from that directory, and only detects it (onboarding refuses into a
-  directory that holds one). Retire them with the 0.25 kernel first, or accept that
-  they are orphaned. While the directory exists, `oats status` and
-  `oats doctor` report it once as the problem **`legacy-local-agents`** (JSON
-  `problems[]`), naming the instances found there. Delete the directory once
-  they are stopped.
-
-- **Wake needs aw 1.36.5 or later, and a daemon restart.** Scheduled and
-  mail-driven wakes were verified end to end on aw 1.36.8 for session-delivery
-  homes. After upgrading aw, restart the host's wake daemon so it re-registers.
-
-- **Captured homes and captured schedules** (from 0.24–0.25's captured path):
-  retire each captured home — 0.26.0 retires it, but none of its captured
-  retire hooks runs, so revoke the messaging identities and memberships named
-  in the retire warnings with the provider's own tooling — and re-spawn the soul
-  from the deployment. Remove each captured schedule job
-  (`oats schedule remove --force <id>`) and re-add it without the captured keys.
+- **Retire classic instances with 0.25, then onboard with 0.26.** With 0.26.0,
+  write `oats-local.yaml` (`oats onboard`), move what `oats-config.yaml`
+  declared into `oats-workspace.yaml` and each `soul.yaml`, delete it, and run
+  `oats sync`. Homes left behind retire under 0.26.0 with no retire hook, so
+  revoke their messaging identities by hand.
+- **Retire instances under `local-agents/` first.** 0.26.0 does not manage
+  them; `oats status` and `oats doctor` report the problem
+  `legacy-local-agents` until the directory is deleted.
+- **Wake needs aw 1.36.5 or later** (verified on 1.36.8), and a restart of the
+  host's wake daemon.
+- **Captured homes and schedules:** retire each home, revoke the identities
+  its retire warnings name, and re-spawn the soul. Remove each captured
+  schedule (`oats schedule remove --force <id>`) and re-add it without the
+  captured keys.
 
 ## Added
 
-- **Private capabilities are listed as repo-owned** (human decision,
-  2026-09-25). `oats capabilities` (and `--json`) now lists a member
-  capability whose manifest says `private: true`, with `private: true` on its
-  row; the human table marks it "(repo-owned)". Enforcement is unchanged: only
-  souls of its own repository can use it (`E_CAPABILITY_PRIVATE`). `oats sync`'s
-  "· N private" count is of these capabilities. Feature
-  `capabilities-private` in `oats version --json`; the Desktop shows its "Repo
-  owned" section only when it is present.
-- **`oats spawn <soul> --name <slug>`** (human decision, 2026-09-24): an
-  explicit, unprefixed instance name. The name is exactly `<slug>`, with no
-  `<soul>-` prefix. Derived naming (`--purpose`, `<soul>-<n>`) stays the
-  default.
-  - `--name` and `--purpose` are mutually exclusive (`E_BAD_ARGS`).
-  - The name is never rewritten: a non-slug, or a soul name of the deployment,
-    is `E_INSTANCE_NAME_INVALID`.
-  - A name that any soul of the deployment already holds, or that a live tmux
-    window carries, is `E_INSTANCE_NAME_TAKEN`; never a silent `-2`.
-  - `--preview` reports the final name and the same refusals, and
-    `--expect-decision` binds the name.
-  - Feature `spawn-name`.
-- **Instance names are at most 64 characters**, explicit and derived (the
-  messaging alias allows 1–64). A longer name is `E_INSTANCE_NAME_INVALID` in
-  preview and apply, and is never truncated. A derived name that would exceed
-  64 (a long purpose, or the `-2` suffix on a long one) is refused, naming the
-  purpose to shorten. A spawn schedule whose run names
-  (`<agent>-<purpose|id>-<YYYYMMDDHHMM>`) would exceed 64 is refused when it is
-  saved (`E_SCHEDULE_INVALID`). Previously such a name passed the kernel and
-  failed only at the messaging join.
-- **The retire summary names what a recovery copied and what it cost.** A
-  workspace-model worktree has no disposable declaration, so its ignored build
-  outputs (`node_modules/`, `build/` …) are copied to recovery with the
-  uncommitted work: safe, not clean. A recovery (`workRecovery` /
-  `workRecoveries[]` under `--json`, and its `recovery.json`) now carries
-  `outputs: { paths: [{ path, bytes }], bytes }` (the untracked and ignored
-  paths, or a directory's work entries, grouped by top-level entry, largest
-  first) and its own `bytes`; the text summary prints the recovery's size and
-  `copied outputs: node_modules/ (412.0 MiB), … — <total> in total`.
-- **`oats inspect --json` says where each layer's capability came from.**
-  Each `layers.<layer>` row gains `from`: `"soul"`, `"workspace"` (a slot
-  default or `defaults.capabilities`) or `"team:<label>"`
-  (`defaults.byTeam.<label>`). It is `null` for an empty slot. A spawn records
-  the rows in `instance.json` (`workspace.layers`), so `inspect --home`
-  reports the spawn-time origin. A home spawned earlier reports `null`.
-  Neither revision changes. Feature `layers-from`.
+- **Private capabilities are listed as repo-owned** (`private: true` rows,
+  still usable only by their own repository's souls). Feature
+  `capabilities-private`.
+- **`oats spawn <soul> --name <slug>`**: an explicit, unprefixed instance
+  name, never rewritten; exclusive with `--purpose`. Refusals:
+  `E_INSTANCE_NAME_INVALID`, `E_INSTANCE_NAME_TAKEN`. Feature `spawn-name`.
+- **Instance names are at most 64 characters**, never truncated; a spawn
+  schedule whose run names would exceed 64 is refused when saved.
+- **The retire summary names what a recovery copied** (`outputs`, `bytes`).
+- **`oats inspect --json` says where each layer's capability came from**
+  (`layers.<layer>.from`: `soul`, `workspace` or `team:<label>`). Feature
+  `layers-from`.
 
 ## Changed
 
-- **Souls have no private mode** (human decision, 2026-09-25). `private:` in a
-  `soul.yaml` is no longer honoured: every soul of a confirmed member, and
-  every external soul, is listed (`oats souls`, `oats sync`) and spawnable, and
-  a soul row's `private` is always `false`. The field is still accepted, so
-  existing files validate (`docs/soul.schema.json` marks it deprecated), and
-  each soul that carries it gets one **`soul-private-ignored`** warning in
-  `oats sync` and `oats workspace status` (`warnings[]`: `{ code, soul,
-  repoKey, path, message }`; "`private` has no effect on a soul since 0.26.0;
-  remove it from souls/<name>/soul.yaml"). It is a warning, never a problem.
-- **Kernel: a capability whose `compatibility.oats` the running kernel doesn't
-  satisfy is refused (`E_CAPABILITY_INCOMPATIBLE`).** This applies to package
-  and member capabilities, and to capability agents, wherever a soul resolves
-  (spawn, `spawn --preview`, `inspect --soul`, operator commands). The details
-  name the capability, the range and the kernel. Before this, the workspace
-  model never checked the range.
-  - `oats inspect` capability rows carry `compatibility: { ok, range, kernel }`.
-  - A home whose spawned module no longer admits the running kernel is not
-    refused: `inspect --home` reports a `capability-incompatible` problem.
-
-- **Catalog: oats.authoring 1.0.3** (the bundled copy matches the tag byte for byte; the framework's `skills/integration-authoring` matches the package): the "core capabilities" wording.
-- **Catalog: oats.jira, oats.linear and oats.dev 1.0.1** (the bundled
-  `capabilities/oats-{jira,linear,review}` copies match the tags byte for byte;
-  the framework's copy of oats.review adds only `private: true`, a member-only
-  key). Each now requires OATS >=0.26.0 and names only the workspace-model
-  homes for its settings:
-  - the soul's `tasks:` payload;
-  - `settings.<cap>` in the deployment's `oats-local.yaml`;
-  - `--provider` at spawn.
-
-  oats.dev drops its `oats-config.yaml` config template and its package
-  dependencies; oats.review is 1.2.1.
-
-- **A soul may name several team labels** (teams contract,
-  [docs/design/2026-09-25-teams-contract.md](../design/2026-09-25-teams-contract.md)).
-  The kernel passes each label's messaging payload to the provider as
-  `OATS_TEAMS` (the eligible teams). Joining them is the messaging provider's
-  job: oats.aweb 1.14.0 joins the default personal team only, and any other
-  team on an explicit join.
-  - `soul.yaml` `team` and `oats-membership.yaml`'s `team` take a label or a
-    non-empty list of distinct labels; the first is the **primary**. A
-    one-label soul composes exactly as before (same modules, skills, injects
-    and `declRevision`); its messaging payload changes only by amendment K
-    (below).
-  - `defaults.byTeam[<label>].capabilities` applies for every label, in order.
-    Two labels that give one capability different entries are
-    `E_TEAM_CONFLICT` (naming both), unless the soul names that capability
-    itself.
-  - **The messaging provider no longer receives `byTeam[<label>]` merged into
-    its settings** (teams amendment K, co-lead ruling), the primary's included:
-    the settings are `base ⊕ soul ⊕ host ⊕ spawn`, and the per-label payloads
-    are in `OATS_TEAMS`. `OATS_TEAM_ID` (the settings' `team`) is therefore the
-    personal team a host, soul or spawn set; empty means the provider's
-    default. With oats.aweb 1.13.1 the primary identity mints into the
-    personal (root-active) team. The preview's `settingsOrigins` no longer
-    shows a `workspace-team` origin.
-  - **Revision change:** a soul whose primary label is mapped in
-    `messaging.byTeam` gets a new `payloadRevision` and `revision` (its
-    `declRevision` is unchanged), so a preview reports a payload change
-    against instances spawned before this.
-  - `OATS_TEAM_LABEL` stays the primary label. New: `OATS_TEAM_LABELS` (comma-joined), `OATS_TEAMS`
-    (`[{ label, team, mapped, payload }]`, `[]` with no label) and
-    `OATS_TEAMS_SOURCE` (`live` | `recorded`). All three are set in the
-    environment of every hook, home command and provider check, and only
-    there: a check's stdin request is unchanged, so providers that decode it
-    strictly (oats.aweb 1.13.1) keep working. They are empty when a home's
-    teams are unknown. A provider leaves a joined team only when the source is
-    `live`.
-  - A home's teams are **live** where they are acted on: the launch hook, the
-    messaging module's commands and `messaging:` operations, and `inspect
-    --home` read the workspace's current mappings in two repository reads (no
-    discovery); `readiness --home` uses the discovery it already runs. Other
-    capability commands and operations get the spawn-time list
-    (`instance.json` `teams`, `recorded`) at no remote cost. The home's modules
-    are unchanged.
-  - `oats spawn --preview` and `oats inspect` show `teams`. A label with no
-    `messaging.byTeam` entry is one `unmapped-team-label` warning, naming its
-    souls, in `oats workspace status` / `oats sync`. Feature `teams`.
-  - oats.aweb 1.13.1 ignores the new variables and keeps working.
-
-- **Declared setting keys.** The spawn preview's `modules[]` and `oats inspect`'s
-  `capabilities[]` carry `declares`: the setting keys each manifest declares,
-  sorted, names only (`[]` when none). Feature `settings-declared`.
-
-- **A home records its module skills.** `instance.json` `skills` lists each
-  module skill as `{ name, source: "module:<capability>" }` beside the soul's
-  own (`source: "soul"`), and `composition.materialized.skills` adds `from`:
-  the home's module copy (`.oats/modules/<capability>/…`) the skill was copied
-  from. Module skills sit under `.agents/skills/<capability>/<skill>/`.
-- **`oats launch-config list` with only a 0.25 `oats-config.yaml` in reach**
-  answers `E_LOCAL_MISSING` naming the file instead of an empty list; inside a
-  deployment the file is `E_CONFIG_BROKEN` with `details.reason:
-  "legacy-config"`, as for every command.
-- **Launch configurations move to `oats-local.yaml`** (lead decision 2: a
-  spawn-time host choice). The deployment's `oats-local.yaml` gains a
-  `launch-configs:` key with the same entries (`runtime`, `executable`, `args`,
-  `env`, `model`, `yolo`); `oats launch-config set | remove` rewrite only that
-  block, and `list` / `preview`, `--launch-config` on `oats spawn` and on
-  `oats session start | restart`, and the `launch-config` feature are unchanged.
-  There is one host file and no scope chain: `list` rows keep `source` (the
-  deployment directory) and an always-empty `shadows`. A relative `executable`
-  resolves against the deployment directory. A home's launch configurations
-  are its deployment's, found walking up from the home.
-  - **Upgrading:** a scope's `oats-config.yaml` that still declares
-    `launch-configs:` is refused (its readers, and the `launch-config`
-    commands, name the move). Move the block into `oats-local.yaml`, or
-    re-declare each entry with `oats launch-config set <name> --file <json>`
-    from the deployment. `set` with no `oats-local.yaml` in reach is
-    `E_LOCAL_MISSING`.
-- **The capability manifest contract is checked where a workspace reads the
-  manifest.** The rules the kernel enforced only on classic capabilities now
-  apply to member and package capabilities too, before anything runs:
-  - a launch `environment` name inside the capability's vendor namespace (or an
-    `environmentNamespaces` prefix that is not reserved), never a core or
-    process bootstrap variable;
-  - hooks: an approved event, a command string or `{ command, required,
-    inputs }`, `required: true` only on the spawn hook, and a script path inside
-    the capability directory;
-  - hooks and launch environment only on a dotted id (`acme.tool`): an
-    undotted id has no vendor namespace to claim.
-
-  A member capability that breaks one is a discovery problem
-  (`E_WORKSPACE_SCHEMA` at `capabilities/<dir>/oats.json#<pointer>`, shown by
-  `oats workspace status`) and is not listed; a soul that declares it is
-  refused with that problem (`reason: "manifest-contract"`), not "missing". A
-  package capability that breaks one is `E_PACKAGE_MANIFEST` at `oats sync`.
-  - **A provider payload value outside the manifest's `settings.<key>.values`
-    is refused** (`E_WORKSPACE_SCHEMA`, `reason: "setting-value"`, naming where
-    it was set: a `--provider` flag, `oats-local.yaml` settings, the soul or the
-    workspace). A misspelled value used to be recorded and skip every
-    conditional `requires` row that reads it.
-- **A capability agent is a workspace-model spawn of its providing module
-  only** (lead decision c3 Q1). `oats spawn <agent>` for a capability's
-  `agents:` soul (OKF's `memory-harvest`, `oats.review`'s `reviewer`) records
-  `modules`/`providers`/`workspace` like any v2 home, and composes exactly one
-  module: the capability that declares the agent. The module comes from the
-  `--parent`/`--relative-to` instance's verified copy (pinned to its recorded
-  digest, with its recorded payload), else from a home that carries it, else
-  from a confirmed member capability or a locked package that declares the
-  agent (the source instance may be gone). A capability agent gets no
-  knowledge, messaging or tasks module and runs no provider hook, its providing
-  module's included: a harvester never registers as a knowledge source or gets
-  a messaging identity. A knowledge-layer provider's inject is left out.
-- **`instance.json` records `workspace.name` and `workspace.deployment`**
-  (M5/3a). `oats inspect --home` reports the recorded workspace name without
-  discovery, and `oats operation run --home` hands it to the provider as
-  `OATS_WORKSPACE_NAME`. Homes spawned before 0.26.0 have neither.
-
+- **Souls have no private mode.** `private:` in `soul.yaml` is accepted but
+  ignored, with a `soul-private-ignored` warning.
+- **A capability whose `compatibility.oats` the kernel does not satisfy is
+  refused** (`E_CAPABILITY_INCOMPATIBLE`); an existing home reports
+  `capability-incompatible` instead.
+- **Catalog:** oats.authoring 1.0.3; oats.jira, oats.linear and oats.dev
+  1.0.1 (require OATS >=0.26.0, settings only from the workspace model);
+  oats.review 1.2.1.
+- **A soul may name several team labels**; the first is the primary. Each
+  label's `defaults.byTeam` applies (`E_TEAM_CONFLICT` on a clash). The
+  messaging provider's settings no longer merge `byTeam[<label>]`; the
+  per-label payloads travel in `OATS_TEAMS`, beside `OATS_TEAM_LABELS` and
+  `OATS_TEAMS_SOURCE`, and a soul whose primary label is mapped gets a new
+  `payloadRevision`. Feature `teams`. See the
+  [teams contract](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-25-teams-contract.md).
+- **Launch configurations move to `oats-local.yaml`** (`launch-configs:`).
+  Move the block, or re-declare each entry with `oats launch-config set`. See
+  [configuration.md](../configuration.md#launch-configurations).
+- **The capability manifest contract applies to member and package
+  capabilities** (`E_WORKSPACE_SCHEMA` / `E_PACKAGE_MANIFEST`), and a payload
+  value outside `settings.<key>.values` is refused.
+- **A capability agent composes only its providing module**, with no
+  knowledge, messaging or tasks module.
 - **`oats inspect`, `oats readiness` and `oats operation run` read the
-  workspace model** on a workspace deployment and for every home whose
-  `instance.json` records `modules`. They never read the classic config chain.
-  The probe integers are the gate: `operationsApi: 2`, `soulsApi: 2` (the
-  inspect soul rows) and `readinessApi: 2`. `oats souls --json` keeps
-  `soulsApi: 1`, since its shape is unchanged. Shapes and examples are in
+  workspace model** (`operationsApi: 2`, `soulsApi: 2`, `readinessApi: 2`).
+  Readiness checks are `installed | configured | member | providers`. See
   [desktop-cli-api.md](../desktop-cli-api.md#inspect-readiness-and-operation-run-on-the-workspace-model-operationsapi-2-soulsapi-2-readinessapi-2-oats-0260).
-  - The subject is an instance (`--home`: `{kind:"instance", instance, home,
-    soul}`) or a soul (`--soul`: `{kind:"soul", soul, repoKey, commit,
-    team}`). A workspace deployment with neither is `E_BAD_ARGS`; the
-    scope-wide lists are `oats souls` and `oats capabilities`.
-  - Payloads lose `scope` (`chain`, `team`, `agentsRoots`), config `levels`,
-    `activation`, `currentConfig`, `snapshot`, `health.trusted` and the
-    portable `sources`. A capability's origin is its module's `from`; its
-    settings are the merged provider payload.
-  - Readiness checks are `installed | configured | member | providers`:
-    - `trusted` is removed, and `--verify-signatures` is `E_BAD_ARGS`.
-    - `enrolled` is now `member`: the soul's member repository confirmed in
-      the workspace (`oats-membership.yaml`), never `oats.yaml`.
-    - `providers` is new: each bound provider's own binding check, relayed
-      verbatim as `{status, problems, warnings}`. The status maps to the item:
-      - `ready` → pass;
-      - `needs-configuration` or `authorization-required` → fail;
-      - `unavailable` → unknown.
-
-      `warnings` is optional in the provider's answer and always present in
-      the relay (`[]` when absent). It never changes the status: a ready
-      binding with a warning still passes. The answer is decoded by the
-      binding wire's rules (exit 0, one strict JSON document, the envelope
-      echo, no problems on `ready`); anything else is `unknown`. All provider
-      checks share one 60 s budget per read. Provider authors: the request,
-      environment and answer are specified in
-      [capabilities.md](../capabilities.md#readiness-check-bindingcheck).
-    - A soul whose packages the lock does not provide fails `installed` with
-      the typed code and an `oats sync` remedy.
-  - The probe's integers say the kernel can answer the v2 shapes. Dispatch
-    on each payload's own integer; the v1 shapes are removed (see Removed).
-  - The `readiness-verify` feature is no longer advertised.
-  - A v2 home's deployment is derived from its path
-    (`<deployment>/agents/<soul>/instances/<name>`), and
-    `<deployment>/oats-local.yaml` must exist exactly there (`E_HOME_MISMATCH`
-    otherwise). A v2 spawn ignores an ambient `PI_AGENTS_ROOT` / `OATS_ROOT`.
-  - A module tree in the deployment's store (used by readiness `--soul`,
-    `operation run --soul` and `oats <ns>` dispatch) runs only while it
-    matches the digest verified when it was fetched at the locked commit. A
-    drifted tree is fetched again; a fetch that does not verify is
-    `E_PACKAGE_INTEGRITY`.
-  - `readiness --policy` is kept, with the same shape. The selector echo moves
-    from `subject.selector` to a top-level `selector`.
-  - `oats operation run` runs the module that fills the layer for the home or
-    the soul. There is no trust gate, and the result carries
-    `operationsApi: 2`. Remote routing accepts a destination advertising
-    `operationsApi` 1 or 2.
-
-- **Manifest setting defaults reach workspace spawns** (addendum 5). A
-  capability's declared `settings.<key>.default` (for example oats.aweb's
-  `identity: { mode: local }`) is now the lowest layer of the merged provider
-  payload on `oats spawn`, `--preview` and `oats inspect --soul`, below the
-  workspace, team, soul, host and `--provider` layers. The provider receives it
-  in `OATS_SETTINGS` and `instance.json` `providers.<cap>` records it. The
-  preview's new `settingsOrigins.<cap>` says where each leaf came from
-  (`manifest-default`, `workspace`, `workspace-team`, `soul`, `host`,
-  `spawn`; feature `settings-origins`), so a Desktop shows "Default" without
-  hardcoding it. The decision
-  binds the payload by value, defaults included. An instance spawned before
-  0.26.0 keeps the payload it recorded, without the defaults.
+- **Manifest setting defaults reach workspace spawns** as the lowest payload
+  layer; the preview's `settingsOrigins` says where each value came from
+  (feature `settings-origins`).
+- Spawn previews and `oats inspect` report each module's declared setting keys
+  (feature `settings-declared`); `instance.json` records module skills and
+  `workspace.name` / `workspace.deployment`.
 
 ## Fixed
 
-- **Every team label's messaging payload is validated.** A soul with several
-  labels had only its primary label's `messaging.byTeam` entry checked, though
-  every label's entry reaches the provider in `OATS_TEAMS`. A secondary
-  label's entry could carry a manifest `hostOnly` key or a nested `byTeam`
-  unchecked. Each label the soul carries is now refused the same way, with
-  `E_WORKSPACE_SCHEMA` (reason `host-only-key` or `reserved-key`) and the
-  path `/messaging/byTeam/<label>/…`.
-- **Team facts in a home's launch and retire hooks.** A home's `launch` and
-  `retire` hooks received an empty `OATS_TEAM_LABEL` and `OATS_TEAM_ID`. The
-  kernel read the recorded workspace in the wrong shape, while spawn hooks and
-  home commands got the right values. They now get the soul's primary label and
-  the recorded messaging payload's team id.
-- **Session start and restart of a workspace-model home.** Every start or
-  restart of a home that records `modules` and a launch recipe refused with
-  `E_LAUNCH_PREPARATION` ("… is no longer installed in the scope"): the
-  launch providers' manifests were looked up from the home's recorded work
-  repository instead of the home's own module copies. A module home now reads
-  them from `<home>/.oats/modules`, and is never re-resolved against the scope;
-  a module copy that is missing is its own refusal naming the directory.
-
-- **A spawn preview writes nothing, the first one included.** The first
-  `oats spawn <soul> --preview` of a workspace soul (or of a new member commit)
-  used to fill the deployment's soul cache (`agents/<soul>/souls/<commit>/`)
-  and move the `agents/<soul>/soul` pointer. A preview now reads the cache when
-  a spawn already filled it, else fetches the soul to a temporary copy outside
-  the deployment and removes it; `soulFetched: true` still says it fetched. The
-  deployment is byte-identical after any preview, as `spawnPreviewApi 2`
-  promises (docs/desktop-cli-api.md).
-
-- **`oats retire <unknown>` is a typed refusal.** An instance name with no home
-  under the agents root used to escape as an untyped error with a stack trace
-  (no `--json` envelope). It is now `E_SESSION_UNKNOWN` (`no instance named
-  "<name>"`), the code every lookup by instance name answers, exit 1, one
-  envelope under `--json`.
-
-- **Instance names are unique across the deployment.** A derived name used to
-  de-duplicate only within its own soul's `instances/`, so soul `a` with
-  `--purpose b-c` and soul `a-b` with `--purpose c` both got `a-b-c`. Derived
-  names now skip every instance and soul name in the deployment (`-2`, `-3`, …).
-
-- **`oats status` shows a workspace soul as it is written.** A soul row read a
-  `schemaVersion: 2` soul.yaml with the classic flat reader: a nested map
-  (`capabilities`, `knowledge` …) came out as `""` and `schemaVersion` as the
-  string `"2"`. Such a soul.yaml is now read with the YAML parser: the row
-  carries the maps as maps, `schemaVersion: 2` and booleans as booleans.
-
-- **`oats doctor --soul <name>` includes module injects.** On a workspace
-  deployment it composed through the classic config chain, so the capability
-  injects a spawned home carries were missing. It now resolves the soul over
-  the workspace remotes as a spawn preview does and composes the full text
-  (module inject blocks are named home-relative, `.oats/modules/<cap>/…`). It
-  writes nothing in the deployment; an unknown soul is `E_SOUL_UNKNOWN`.
-  Without `--soul`, doctor stays offline.
-
-- **Capability commands recognise `OATS_INSTANCE_HOME`.** Dispatch found the
-  instance home only from `PI_AGENT_HOME` / `OATS_HOME`; the canonical
-  `OATS_INSTANCE_HOME` now counts, and wins when several are set.
-
-- **Launch-preparation refusals name no removed verb.** The classic
-  `E_LAUNCH_PREPARATION` remedies said "reinstall it (oats install)" and
-  "re-trust it (oats trust)"; the remedy is now "respawn the instance".
+- Every team label's messaging payload is validated, not only the primary's.
+- Launch and retire hooks get the primary `OATS_TEAM_LABEL` and
+  `OATS_TEAM_ID` (they were empty).
+- Session start and restart of a workspace-model home no longer refuse with
+  `E_LAUNCH_PREPARATION`.
+- A spawn preview writes nothing to the deployment, the first one included.
+- `oats retire <unknown>` is `E_SESSION_UNKNOWN`.
+- Derived instance names are unique across the deployment.
+- `oats status` reads a `schemaVersion: 2` soul.yaml correctly.
+- `oats doctor --soul <name>` includes module injects.
+- Capability commands recognise `OATS_INSTANCE_HOME`.
+- `E_LAUNCH_PREPARATION` remedies no longer name removed verbs.