@awebai/oats 0.25.8 → 0.26.0

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

@@ -0,0 +1,670 @@
+# 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)).
+
+## 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`.
+
+- **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.
+
+## 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.
+
+## 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.
+
+## 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`.
+
+## 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.
+
+- **`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
+  [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.
+
+## 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".