@awebai/oats 0.29.4 → 0.30.0

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

@@ -1,67 +1,51 @@
 # OATS v0.24.9 — readiness pins, side-effect-free spawn preview (API 2), process-group safety, Desktop Readiness view
 
-Kernel/Pi/Desktop **0.24.9**. Tag `v0.24.9` → the commit carrying these notes;
-the version-bump commit lands after the tag. Consumers gate on `oats version
---json` `features[]` names and API integers — never on the version.
+Kernel/Pi/Desktop **0.24.9**. Consumers gate on `oats version --json`
+`features[]` names and API integers, never on the version. Shapes are in the
+[Desktop CLI API](../desktop-cli-api.md).
 
 ## Kernel
 
 - **Spawn preview API 2** (feature `spawn-preview-2`, `spawnPreviewApi: 2`).
-  API 1 previews **wrote before they returned** — a refused child spawn appended
-  an event to the parent, a Herdr backend could be started, an unknown soul
-  could be imported from an importable def — and nothing bound a later spawn to
-  the previewed decision. API 2: a preview touches nothing, success or refusal
-  (proven by a byte-identical deployment tree); `spawn --agents-root <abs>`
-  binds the exact root with no fallback and the preview echoes `subject` as
-  given; `decision {instance, home, branch, base, revision}` + `spawn
-  --expect-decision <rev>` refuses **`E_DECISION_STALE`** with the fresh
-  decision on any drift (no auto-suffix, no silent re-base, nothing created);
-  every native probe shares one bounded preflight budget and is process-group
-  killed on timeout (`preflight {status, budgetMs, elapsedMs}`). **Gate on API
-  2 — API 1 is the pre-fix marker.**
-- **Readiness pins** (`oats readiness`): `configured` is *effective* activation
-  (a capability declared for the soul but disabled is a fail that says so);
-  data-only capabilities (skills/inject, no commands/hooks/env) report trust
-  **not-applicable** — the inspect row carries `health.executableSurface`;
-  every item is typed (`capability {id, level, scope}`, `origin {kind,
-  target}`) and `summary.byCapability[]` regroups the same items with
-  `ownReady` vs `ready` (never ready under a `summary.subjectBlockers[]` item
-  such as unknown membership); `subject.selector` echoes the arguments as given,
-  byte-exact; an unreadable member document is `unknown`, not not-applicable;
-  `readiness --home <captured>` refuses `E_UNSUPPORTED_MODE`; `--agents-root`
-  documented. **Signature verification** (feature `readiness-verify`) is
-  bounded custody: one budget per read, process-group kill, cleanup on
-  SIGINT/SIGTERM/SIGHUP, `GIT_CONFIG_GLOBAL=/dev/null`, https/ssh only, a closed
-  `signature.failure.code` — never stderr.
-- **Process-group safety (high).** Bounded-custody code killed a child's
-  process group on timeout with `process.kill(-child.pid)`; a **failed** spawn
-  (binary missing → `ENOENT`) reports `pid: 0`, and `kill(-0)` signals the
-  caller's own process group — `oats readiness --verify-signatures` without
-  `git` would have SIGKILLed the operator's shell/tmux/Desktop backend. One
-  guarded helper now refuses non-positive PIDs at every kill site.
-- **OKF 2.1.3** mirrored and pinned in the official catalog: per-cause `check`
-  reasons, a named remedy when a soul has no `okf.json` (was a raw ENOENT from
-  the required spawn hook), retired drained sources switch their `okf-<id>` job
-  off.
+  An API 1 preview could write (an event on the parent, a started Herdr
+  backend, an imported soul) and nothing bound a later spawn to it. An API 2
+  preview touches nothing, success or refusal. `spawn --agents-root <abs>`
+  binds the exact root. The preview returns a `decision {instance, home,
+  branch, base, revision}`, and `spawn --expect-decision <rev>` refuses
+  `E_DECISION_STALE` with the fresh decision on any drift, creating nothing.
+  Native probes share one bounded preflight budget. **Gate on API 2.**
+- **Readiness**: `configured` reflects effective activation (a declared but
+  disabled capability fails and says so); data-only capabilities report trust
+  `not-applicable`; items are typed, and `summary.byCapability[]` regroups them
+  with `ownReady` and `ready`; `subject.selector` echoes the arguments; an
+  unreadable member document is `unknown`; `readiness --home <captured>`
+  refuses `E_UNSUPPORTED_MODE`. Signature verification (feature
+  `readiness-verify`) is bounded, ignores global Git config, allows https and
+  ssh only, and reports a closed `signature.failure.code`.
+- **Process-group safety.** A timed-out child's process group was killed with
+  `process.kill(-child.pid)`; when the spawn itself failed (for example, a
+  missing binary) the pid was 0 and the signal hit the caller's own process
+  group, so `oats readiness --verify-signatures` without `git` could kill the
+  operator's shell, tmux or Desktop backend. Every kill site now refuses
+  non-positive pids.
+- **OKF 2.1.3** is mirrored and pinned in the official catalog: per-cause
+  `check` reasons, a named remedy when a soul has no `okf.json`, and retired
+  drained sources switch their `okf-<id>` job off.
 
 ## Desktop
 
-- **Readiness** (frame 09/04): Workspace header entry and first-run
-  invitation; the quartet from `oats readiness` with items, remedies (display
-  only), *View policy*, *Skip for now* (presentation only). Verify signatures
-  and Enrol are shown unavailable with the exact reason until their contracts
-  land. Effective-readiness section per scope on the Capabilities view.
-- **Normalized route classification**: one classifier decides every specialized
-  IPC route from the normalized pathname — dot-segment, percent-encoded,
-  backslash, tab and CRLF aliases can no longer skip a route's frame/epoch
-  guard.
-- Spawn modal: kernel **preview** (API 2) for the instance name, home, worktree,
-  branch and resolved base — *Suggest* asks the kernel for its default
-  candidate; preview-only choices block legacy submission rather than being
-  dropped. Apply companion, attach-knowledge, auto-PR and branch enumeration are
-  named follow-ups, not parity-done.
+- **Readiness** view: a Workspace header entry and first-run invitation
+  showing the readiness quartet with items and remedies (display only). Verify
+  signatures and Enrol are shown unavailable with the reason. The Capabilities
+  view shows effective readiness per scope.
+- **Route classification** is decided once from the normalized pathname, so
+  dot-segment, percent-encoded, backslash, tab and CRLF aliases cannot skip a
+  route's guard.
+- **Spawn modal** uses the preview (API 2) for the instance name, home,
+  worktree, branch and resolved base; *Suggest* asks the kernel for its default.
+  Preview-only choices block legacy submission instead of being dropped.
 
 ## Upgrade
 
 `npm i -g @awebai/oats@0.24.9`, then `oats doctor`. Desktops on an older CLI
-show the new controls as unavailable until the CLI advertises them.
+show the new controls as unavailable.

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

@@ -1,99 +1,82 @@
 # OATS v0.25.0 — the workspace model (breaking)
 
-Kernel/Pi **0.25.0**. Tag `v0.25.0` → the commit carrying these notes; the
-version-bump commit lands after the tag. Consumers gate on `oats version --json`
-`features[]` names and API integers — never on the version.
+Kernel/Pi **0.25.0**. Consumers gate on `oats version --json` `features[]`
+names and API integers, never on the version.
 
-**This is the 0.25 line: a new deployment model, not a patch to the old one.**
-0.24.x keeps spawning 0.24.x deployments; there is no converter. The rebuild
-guide is `docs/rebuild-to-v2.md`. Design: `docs/design/2026-09-23-simplified-workspace-model.md`;
-decision record (26 decisions): `agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md`;
-normative module contracts: `docs/design/2026-09-23-workspace-module-contracts.md`.
+**This is a new deployment model, not a patch to the old one.** 0.24.x keeps
+spawning 0.24.x deployments; there is no converter, and a 0.24 deployment is
+rebuilt on the new model. Design:
+[simplified workspace model](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-23-simplified-workspace-model.md);
+module contracts:
+[workspace module contracts](../design/2026-09-23-workspace-module-contracts.md).
 
 ## The one idea
 
 An organisation has **one workspace**: a Git repo hosting `oats-workspace.yaml`
 that lists its **member repositories**, pins its **packages**, names its
 **teams** and declares **defaults**. Every member carries an
-`oats-membership.yaml` back-link; the handshake is confirmed over the Git
-remotes in the operator's own access context and **membership is the trust**.
-A member exports **souls** (`souls/<name>/soul.yaml`) and **capabilities**
-(`capabilities/<name>/oats.json`) at its latest commit; a soul says where each
-capability comes from (`from: <member repo> | here | package`). Packages are
-consumed only through `packages:` + `oats-lock.json` v3, with **per-version
-executable approval**. A spawn **resolves** the soul (`lib/resolve.mjs`) and
-**materializes** every capability whole into the instance
-(`<home>/.oats/modules/<cap>/`, skills under `<home>/.agents/skills/<cap>/`);
-the harness starts normally. Nothing is installed anywhere.
+`oats-membership.yaml` back-link, confirmed over the Git remotes in the
+operator's own access context: **membership is the trust**. A member exports
+**souls** (`souls/<name>/soul.yaml`) and **capabilities**
+(`capabilities/<name>/oats.json`); a soul says where each capability comes
+from (`from: <member repo> | here | package`). Packages are consumed only
+through `packages:` + `oats-lock.json` v3, with per-version executable
+approval. A spawn resolves the soul and materializes every capability whole
+into the instance (`<home>/.oats/modules/<cap>/`, skills under
+`<home>/.agents/skills/<cap>/`). Nothing is installed anywhere.
 
 ## Kernel — `workspace-v2` (`workspaceApi: 2`), `instance-modules`, `spawn-provider-payload`
 
-- **Declarations** (`docs/*.schema.json`, all `schemaVersion: 2`):
-  `oats-workspace.yaml` (members, packages, teams, defaults incl. `byTeam`,
-  stores, `messaging` incl. `byTeam.<label>`, external souls),
-  `oats-membership.yaml` (`workspace`, `team?`), `soul.yaml` v2
-  (`capabilities: { <cap>: { from } | off }`, `team`, `private`,
-  `compatibility`, slot payloads), `oats-local.yaml` (the ONLY per-machine
-  file: `workspace:` or `standalone:` ref, `clones`, `settings.<cap>`,
-  `souls.disabled`).
-- **`oats sync`** — discover → confirm membership → resolve packages → write
-  `oats-lock.json` v3; unapproved executables listed, exit 2 non-TTY / prompt
-  on a TTY. `oats package add|remove`, `oats workspace status`,
-  `oats capabilities`, `oats souls` (origin + team columns).
-- **`oats spawn`** — discovers and resolves over the remotes, fetches the soul
-  from its member repo (refreshed per commit), materializes, launches.
-  `--preview` works before any apply and reports `modules[]` (with
-  `changedSince`), `team`, `resolution`, `workspace`, `soulFetched`; the
-  decision binds the resolution revision (a member that moved between preview
-  and apply → `E_DECISION_STALE`). `--provider <cap> k=v` records a per-spawn
-  provider payload (`instance.json.providers`) — the third payload home after
-  the soul and `oats-local.yaml settings`.
-- **`instance.json`** carries `modules{}` (name → from/commit/digest),
-  `providers{}`, `workspace{ key, commit, resolution, standalone, soul }`,
-  `capabilities[]`.
-- **`oats status`** shows drift per instance (`member moved since …`,
-  `capability no longer present`); `--json` `instances[].modules[]`.
-- **`oats onboard [<dir>] --workspace <ref>`** — writes `oats-local.yaml`,
-  runs the sync path, prints the taught layout and the **hosting rule** for
-  mixed public/private organisations (`onboardApi: 2`). Creates no soul,
+- **Declarations** (`docs/*.schema.json`, `schemaVersion: 2`):
+  `oats-workspace.yaml`, `oats-membership.yaml`, `soul.yaml` v2 and
+  `oats-local.yaml`, the only per-machine file (`workspace:` or `standalone:`
+  ref, `clones`, `settings.<cap>`, `souls.disabled`). See
+  [workspaces.md](../workspaces.md#the-files).
+- **`oats sync`** discovers members, confirms membership, resolves packages
+  and writes `oats-lock.json` v3; unapproved executables exit `2` non-TTY or
+  prompt on a TTY. New: `oats package add|remove`, `oats workspace status`,
+  `oats capabilities`, `oats souls`.
+- **`oats spawn`** resolves over the remotes, fetches the soul from its member
+  repo, materializes and launches. `--preview` reports `modules[]`, `team`,
+  `resolution`, `workspace` and `soulFetched`; the decision binds the
+  resolution revision (`E_DECISION_STALE` if a member moved). `--provider <cap>
+  k=v` records a per-spawn provider payload, the third payload home after the
+  soul and `oats-local.yaml` `settings`.
+- **`instance.json`** carries `modules{}`, `providers{}`, `workspace{}` and
+  `capabilities[]`; **`oats status`** shows per-instance drift.
+- **`oats onboard [<dir>] --workspace <ref>`** writes `oats-local.yaml`, runs
+  the sync path and prints the layout and the hosting rule for mixed
+  public/private organisations (`onboardApi: 2`). It creates no soul and
   spawns nothing.
-- **Standalone case** — a member whose workspace cannot be read (access
-  failure only, never network/timeout) still offers its souls with `from: here`
-  capabilities **plus `oats.core`** from the official catalog through the
-  operator's own lock; marked `standalone: true` in sync/status/spawn output.
-- **Teams** are labels; per-team provider payload is `messaging.byTeam.<label>`
-  (merged by the kernel, stripped before the provider). A store names a
-  repository; the root inside it is the provider's binding key.
+- **Standalone case:** a member whose workspace cannot be read (access
+  failure only) still offers its souls with `from: here` capabilities plus
+  `oats.core` from the official catalog, marked `standalone: true`.
+- **Teams** are labels; per-team provider payload is
+  `messaging.byTeam.<label>`. A store names a repository.
 - **Scheduled spawns** on a workspace deployment materialize exactly like
-  `oats spawn` (the scheduler delegates to the CLI).
-- **Security** (found by adversarial review, all pinned): remote tree names
-  fsck'd (no traversal), tag naming a blob refused as a commit, symlinks in
-  fetched trees refused except the soul's `CLAUDE.md → AGENTS.md` alias,
-  `__proto__`/`constructor`/`prototype` refused at every payload layer and in
-  `--provider` flags, `byTeam` reserved outside `workspace.messaging`, package
-  executables gated on per-version approval, atomic staging with full
-  rollback (no half homes).
+  `oats spawn`.
+- **Security:** remote tree names are checked (no traversal), a tag naming a
+  blob is refused as a commit, symlinks in fetched trees are refused except
+  the soul's `CLAUDE.md → AGENTS.md` alias, `__proto__` / `constructor` /
+  `prototype` are refused in every payload layer, `byTeam` is reserved outside
+  `workspace.messaging`, and staging is atomic with full rollback.
 
 ## Removed
 
-`oats init`, `use`, `install`, `trust`, `list`, `remove`, `migrate`, `catalog`,
-`update`, `config`, `inject` → typed `E_UNKNOWN_COMMAND` naming the
-replacement. `oats-config.yaml` is no longer read as configuration (a leftover
-one is harmless); the `installed/` tier, `oats.yaml`, `lockfileVersion` 2,
-per-soul `source: git:…` lines, `stores.inherit`, `imports`. The `catalog`
-feature name is gone from `version --json`. `docs/configuration.md` now
+`oats init`, `use`, `install`, `trust`, `list`, `remove`, `migrate`,
+`catalog`, `update`, `config` and `inject` answer `E_UNKNOWN_COMMAND` naming
+the replacement. `oats-config.yaml` is no longer read as configuration (a
+leftover one is harmless). Also gone: the `installed/` tier, `oats.yaml`,
+`lockfileVersion` 2, per-soul `source: git:…` lines, `stores.inherit`,
+`imports`, and the `catalog` feature name. `docs/configuration.md` now
 describes `oats-local.yaml` only.
 
 ## Desktop
 
-The Desktop server's `oats catalog` reader now surfaces `E_USAGE` (the verb is
-removed); the Capabilities view's package acquisition flow will follow the new
-DTOs in a later release (Phase F). Everything else in the Desktop is unchanged.
+The Desktop server's `oats catalog` reader surfaces `E_USAGE` (the verb is
+removed). Everything else in the Desktop is unchanged.
 
-## Known follow-ups
+## Known limitations
 
-- The classic (no `oats-local.yaml`) spawn path still runs the pre-v2 compose
-  in `lib/core.mjs`; folding it into the one pipeline removes the remaining v1
-  modules (residue table in `docs/design/2026-09-23-workspace-v2-implementation-plan.md`).
-- The OATS framework repositories themselves convert to the model (six expert
-  souls, `oats.core`/`oats.setup` rewritten for the new architecture) in 0.26.
+- A deployment without `oats-local.yaml` still spawns through the classic
+  (pre-workspace) compose path.

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

@@ -1,94 +1,70 @@
 # OATS v0.25.1 — workspace-model fix round
 
-Kernel/Pi **0.25.1**. Tag `v0.25.1` → the commit carrying these notes; the
-version-bump commit lands after the tag. Consumers gate on `oats version --json`
-`features[]` names and API integers — never on the version.
+Kernel/Pi **0.25.1**. Consumers gate on `oats version --json` `features[]`
+names and API integers, never on the version.
 
 **No API change.** `workspaceApi: 2`, every other API integer and the
-`features[]` list are exactly those of [0.25.0](v0.25.0.md). Every item below
-is a correctness, security or documentation fix found by the team review of
-the 0.25.0 workspace model; the normative record is the "0.25.1 fix round"
-section of `docs/design/2026-09-23-workspace-module-contracts.md` and the
-matching clarifications in
-`agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md`.
+`features[]` list are those of [0.25.0](v0.25.0.md). Every item below is a
+correctness, security or documentation fix to the 0.25.0 workspace model.
 
 ## Kernel
 
-- **M1 (high) — a running instance's soul no longer changes under it.** Souls
-  are fetched into a per-commit cache `agents/<name>/souls/<commit12>/`
-  (immutable); `agents/<name>/soul` is an atomically swapped pointer to the
-  current commit; each home links its own commit's directory. A 0.25.0 layout
-  is migrated in place on first use. OKF's path-pinned owner stays valid per
-  instance.
-- **M2 — SSH remotes are fetched over SSH.** The canonical repo key is
-  unchanged; the fetch url honours the ref as written (`git@…`/`ssh://` → SSH,
-  `https://` → HTTPS, bare `git:` → HTTPS unless `remoteOptions.transport:
-  ssh`). A private repo is no longer probed over HTTPS and silently degraded to
-  the standalone view; the standalone fallback now reports the host failure
-  that triggered it.
-- **M3 (high) — package approval is re-verified at spawn.** `resolveSoul`
-  recomputes the executables digest over the package tree at the locked commit
-  and refuses `E_PACKAGE_UNAPPROVED { reason: "digest-mismatch" }` when it
-  differs from the approved one; one shared `executablesDigestAt` serves
-  `sync` and `resolve`.
-- **M4 — annotated tag OIDs are peeled.** `observeRemote` records the peeled
-  commit, never a tag object, in results, locks and `instance.json`.
-- **B2 — `work: workspace` spawns on a v2 deployment.** `./work` is the
-  deployment directory (the one holding `oats-local.yaml`); no branch recorded;
-  the remedy names `oats-local.yaml`.
-- **B3 — operator-level capability commands from the deployment.**
-  `oats <ns> <cmd> … --soul <name>` outside a home resolves exactly as a spawn
-  of that soul, fetches the module into `<deployment>/.oats/modules/<cap>@<commit12>/`
-  and dispatches there with the soul's merged payload (`oats okf init` before
-  any instance exists). `--soul` absent → `E_BAD_ARGS`; unknown namespace →
+- **A running instance's soul no longer changes under it.** Souls are fetched
+  into an immutable per-commit cache `agents/<name>/souls/<commit12>/`;
+  `agents/<name>/soul` is an atomically swapped pointer to the current commit,
+  and each home links its own commit's directory. A 0.25.0 layout is migrated
+  in place on first use.
+- **SSH remotes are fetched over SSH.** The fetch URL honours the ref as
+  written (`git@…` / `ssh://` → SSH, `https://` → HTTPS, bare `git:` → HTTPS
+  unless `remoteOptions.transport: ssh`). A private repo is no longer probed
+  over HTTPS and silently degraded to the standalone view, and the standalone
+  fallback reports the host failure that triggered it.
+- **Package approval is re-verified at spawn.** The executables digest is
+  recomputed at the locked commit; a mismatch is `E_PACKAGE_UNAPPROVED {
+  reason: "digest-mismatch" }`.
+- **Annotated tags are peeled**: results, locks and `instance.json` record
+  the commit, never a tag object.
+- **`work: workspace` spawns on a v2 deployment**, with `./work` as the
+  deployment directory.
+- **Operator-level capability commands from the deployment.** `oats <ns>
+  <cmd> … --soul <name>` outside a home resolves as a spawn of that soul,
+  fetches the module into `<deployment>/.oats/modules/<cap>@<commit12>/` and
+  dispatches there (for example `oats okf init` before any instance exists).
+  Without `--soul` it is `E_BAD_ARGS`; an unknown namespace is
   `E_UNKNOWN_COMMAND`.
-- **L1 — slot `none` empties the slot.** A soul's `knowledge|messaging|tasks:
-  none` drops any layer-bearing capability the workspace defaults contributed
-  for that layer; only a layer-bearing capability the soul itself declares next
-  to `none` is `E_SLOT_CONFLICT`.
-- **L2 — absolute-path refusal is scoped to ref/path fields.** Team
-  descriptions and the opaque messaging payload may contain `/`-rooted text.
-- **L3 — one unsafe deep entry no longer blanks a member's souls.** Depth
-  filtering precedes the entry-name safety check.
-- **L4 — listing failures are classified.** `maxBuffer` overflow is not
-  reported as `timeout`; an unclassified git listing failure becomes a
-  discovery problem row (`E_REMOTE_UNREADABLE { reason: "unknown" }`) instead
-  of an abort.
-- **L6 — revision splits declarations from payload.** `revision =
-  hash(declRevision, payloadRevision)`; decision binding unchanged; preview can
-  report `changed since: declarations | payload | both`.
+- **Slot `none` empties the slot**, dropping any capability the workspace
+  defaults contributed for that layer; only a capability the soul itself
+  declares beside `none` is `E_SLOT_CONFLICT`.
+- **Absolute-path refusal applies only to ref and path fields**; team
+  descriptions and the messaging payload may contain `/`-rooted text.
+- **One unsafe deep entry no longer blanks a member's souls.**
+- **Listing failures are classified**: a `maxBuffer` overflow is not reported
+  as `timeout`, and an unclassified listing failure is a discovery problem row
+  (`E_REMOTE_UNREADABLE { reason: "unknown" }`) instead of an abort.
+- **The revision splits declarations from payload**: `revision =
+  hash(declRevision, payloadRevision)`, and a preview can report `changed
+  since: declarations | payload | both`.
 
 ## Documentation
 
-- **M5 — rebuild guide gaps closed** (`docs/rebuild-to-v2.md`): the tracked
-  `git mv agents/<name>/soul souls/<name>` step and the tests that enumerate
-  soul paths; OKF 2 owner re-registration (fresh `state-dir` for a rebuilt
-  deployment, the old one frozen custody); `oats-local.yaml` example with
-  `settings.oats.aweb.delivery` and `settings.oats.okf` `state-dir` +
-  `bindings-file`; unlabelled souls receive the messaging base payload only;
-  per-soul memory-harvest opt-out is not available in OKF 2.1.3 (an OKF 2.1.4
-  item).
-- **L7 — decision 13 reach.** Every `pi` launch a 0.25 kernel performs starts
-  the harness normally, classic 0.24 homes included (rebuild guide §0,
-  `conventions.md`). `oats session recompose` is `E_UNSUPPORTED_MODE` for
-  module homes; `session-recompose` stays advertised for classic homes
-  (`desktop-cli-api.md`).
-- **L8 — v1 no longer presented as live** in `schedules.md`, `conventions.md`,
-  `implementation.md`, `execution-targets.md`, `desktop.md`,
-  `desktop-succession.md`, `integrations.md`, `migration-from-oas.md`
-  (a 0.24.x procedure), `desktop-cli-api.md` (readiness producers are the 0.24
-  tier), `knowledge-migration.md` (`state-dir` is required; four settings) and
-  `knowledge.md` (operator-level `oats okf … --soul <x>` from the deployment).
+- The [rebuild guide](https://github.com/awebai/oats/blob/bdd7e55e1b798a97b8b5486001d7c17e522792a7/docs/rebuild-to-v2.md) covers moving `agents/<name>/soul` to `souls/<name>`, OKF
+  2 owner re-registration (a fresh `state-dir`), and an `oats-local.yaml`
+  example with `settings.oats.aweb.delivery` and `settings.oats.okf`;
+  unlabelled souls receive the messaging base payload only.
+- Every `pi` launch a 0.25 kernel performs starts the harness normally,
+  classic 0.24 homes included. `oats session recompose` is
+  `E_UNSUPPORTED_MODE` for module homes; `session-recompose` stays advertised
+  for classic homes.
+- The reference docs no longer present the 0.24 model as live, and
+  [knowledge.md](../knowledge.md) documents operator-level `oats okf … --soul
+  <x>` from the deployment.
 
-## Known follow-ups (unchanged from 0.25.0 unless noted)
+## Known limitations
 
-- The classic (no `oats-local.yaml`) spawn path still runs the pre-v2 compose;
-  `composeInstance` still reads `yolo` / `launch-configs` from an
-  `oats-config.yaml` chain when one sits above a deployment.
-- The readiness quartet (`readinessApi: 1`) is still produced by the 0.24 tier
-  observers; re-basing it on `spawn --preview` / `sync` / `workspace status` is
-  a named follow-up.
-- OKF 2's owner pin is per soul path (hence per commit under M1); re-basing it
-  on the owner identity is an OKF 2.1.4 item, as is a per-soul harvest opt-out.
-- `oats-local.yaml` `transport:` (M2's per-machine SSH default) needs a schema
-  addition before it can be written.
+- A deployment without `oats-local.yaml` still spawns through the classic
+  compose path, which reads `yolo` and `launch-configs` from an
+  `oats-config.yaml` chain above a deployment.
+- Readiness (`readinessApi: 1`) is still produced by the 0.24 tier.
+- OKF 2.1.3 pins a soul's owner per soul path, so per commit; a per-soul
+  harvest opt-out is not available.
+- `oats-local.yaml` has no `transport:` key.

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

@@ -1,80 +1,61 @@
 # OATS v0.25.2 — operator-rebuild round
 
-Kernel/Pi **0.25.2**. Tag `v0.25.2` → the commit carrying these notes; the
-version-bump commit lands after the tag. Consumers gate on `oats version --json`
-`features[]` names and API integers — never on the version.
+Kernel/Pi **0.25.2**. Consumers gate on `oats version --json` `features[]`
+names and API integers, never on the version.
 
 **No API change.** `workspaceApi: 2`, every other API integer and the
-`features[]` list are exactly those of [0.25.1](v0.25.1.md). The only surface
-additions are **additive fields**: `oats spawn --preview` gains `providers` and
-`settings`, `oats status --json` gains `instances[].soul`; `oats sync` gains
-the `--approve` flag. Every item below comes from an operator's first rebuild
-of a real two-team deployment on 0.25.0, following `docs/rebuild-to-v2.md`
-literally — the guide is a contract the kernel honours. Normative record:
-"0.25.2 operator-rebuild round" in
-`docs/design/2026-09-23-workspace-module-contracts.md` and the matching
-clarifications in
-`agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md`.
+`features[]` list are those of [0.25.1](v0.25.1.md). The surface additions
+are additive: `oats spawn --preview` gains `providers` and `settings`, `oats
+status --json` gains `instances[].soul`, and `oats sync` gains `--approve`.
+Every item comes from an operator's first rebuild of a real two-team
+deployment on 0.25.0, following the [rebuild guide](https://github.com/awebai/oats/blob/bdd7e55e1b798a97b8b5486001d7c17e522792a7/docs/rebuild-to-v2.md) literally.
 
 ## Kernel
 
-- **R1 — member clones are found as the guide says.** For a `work: worktree |
-  checkout` soul: `--repo`, then `oats-local.yaml` `clones:` (keys normalised
-  through `parseRepoRef`), then `<deployment>/<member name>` (a member named
-  `agents` → `agents-repo`); none → `E_CLONE_MISSING` naming the three
-  remedies; a directory whose remotes name another repo → `E_CLONE_MISMATCH`.
-- **R2 — `oats sync` creates `<deployment>/agents/` when absent.**
-- **R3 — one "You run on OATS" block.** With `oats.core` resolved as a module
-  the kernel's legacy block is suppressed; the module's inject is the briefing.
-- **R4 — `oats status` shows soul-source drift.** `soul: <name> from <member>
-  @ <c7>  [member moved since …]` beside the module rows; `--json`
-  `instances[].soul { repoKey, commit, current, status }`.
-- **R5 — `spawn --preview` shows the payload.** `providers` (the `--provider`
-  map as given) and `settings.<cap>` (the merged payload each provider
-  receives).
-- **R9 — non-interactive approval.** `oats sync --approve <id>@<version>`
-  (repeatable) approves exactly the locked entry at that version; the digest is
-  always computed, never typed; an id/version not in the resolution is
-  `E_BAD_ARGS`. Ctrl+D at the interactive prompt is a decline (exit `2`).
-- **R10 — `oats onboard` lists the host** among the clones to make, like any
-  member; an explicit `standalone:` header is named as such in the next steps.
+- **Member clones are found as the guide says.** For a `work: worktree |
+  checkout` soul: `--repo`, then `oats-local.yaml` `clones:`, then
+  `<deployment>/<member name>` (a member named `agents` → `agents-repo`). None
+  is `E_CLONE_MISSING` naming the three remedies; a directory whose remotes
+  name another repo is `E_CLONE_MISMATCH`.
+- **`oats sync` creates `<deployment>/agents/` when absent.**
+- **One "You run on OATS" block.** With `oats.core` resolved as a module, the
+  kernel's own block is suppressed.
+- **`oats status` shows soul-source drift**: `soul: <name> from <member> @
+  <c7>  [member moved since …]`; `--json` `instances[].soul { repoKey, commit,
+  current, status }`.
+- **`spawn --preview` shows the payload**: `providers` (the `--provider` map
+  as given) and `settings.<cap>` (the merged payload each provider receives).
+- **Non-interactive approval.** `oats sync --approve <id>@<version>`
+  (repeatable) approves exactly that locked entry; the digest is always
+  computed. An id or version not in the resolution is `E_BAD_ARGS`. Ctrl+D at
+  the interactive prompt is a decline (exit `2`).
+- **`oats onboard` lists the host** among the clones to make; an explicit
+  `standalone:` header is named as such in the next steps.
 
 ## Documentation
 
-- **R6** — the rebuild guide's work-mode section states that a coordination
-  soul's (`work: workspace`) `./work` is the deployment directory (0.25.1 B2).
-- **R7 — where the team `.aw` lives now.** Rebuild guide §8b: oats.aweb 1.11.2
-  finds `.aw` among the home, the home's git repo, the soul's work repo and the
-  deployment directory — never the 0.24 team root; place it inside the member
-  clone (gitignored) or at the deployment directory. **`messaging.byTeam` is
-  kernel-merged but a no-op for oats.aweb 1.11.2**, which does not read `team`
-  from its payload; per-repo `.aw` placement is the working alternative
-  (`workspaces.md` byTeam paragraph updated accordingly).
-- **R8 — OKF 2.1.3 reads `okf.json`, not a soul payload.** The guide, `workspaces.md`,
-  `souls-and-instances.md` and `knowledge.md` no longer show `knowledge: { owns,
-  reads }` / `{ store, root }` on `soul.yaml`: the soul's declaration is
-  `souls/<name>/okf.json` (`version`, `owner`, `owns`, `reads`); the `knowledge:`
-  payload may carry only the binding's settings (`bindings-file`, `state-dir`,
-  `harvest-runtime`, `harvest-model`); a base's `root` is the bindings file's.
-  Decision 24's example is corrected. §7b (fresh `state-dir`) confirmed.
-- `configuration.md` `clones` row states the R1 order; `workspaces.md` and
-  `souls-and-instances.md` describe the R4/R5 fields and the per-commit soul
-  cache paths.
-
-## Provider follow-ups (not kernel)
-
-- **oats.aweb follow-up:** read `team` from the spawn payload (so
-  `messaging.byTeam` yields per-label identities) and accept the deployment
-  directory as a first-class aweb root. Until that release, 1.11.2 behaves as
-  §8b describes.
-- **oats.okf follow-up:** a soul-payload grammar (`owns`/`reads` on
-  `soul.yaml`), declared in the binding when it lands; owner pin re-based on
-  identity rather than path, and per-soul harvest opt-out (2.1.4 items, unchanged).
-
-## Known follow-ups (unchanged from 0.25.1)
-
-- The classic (no `oats-local.yaml`) spawn path still runs the pre-v2 compose.
-- The readiness quartet (`readinessApi: 1`) is still produced by the 0.24 tier
-  observers.
-- `oats-local.yaml` `transport:` needs a schema addition before it can be
-  written.
+- A coordination soul's (`work: workspace`) `./work` is the deployment
+  directory.
+- **Where the team `.aw` lives.** oats.aweb 1.11.2 finds `.aw` in the home,
+  the home's git repo, the soul's work repo or the deployment directory, never
+  the 0.24 team root: place it in the member clone (gitignored) or the
+  deployment directory. **`messaging.byTeam` is a no-op for oats.aweb
+  1.11.2**, which does not read `team` from its payload; per-repo `.aw`
+  placement is the working alternative.
+- **OKF 2.1.3 reads `okf.json`, not a soul payload.** A soul's knowledge
+  declaration is `souls/<name>/okf.json` (`version`, `owner`, `owns`,
+  `reads`); the `knowledge:` payload carries only the binding's settings
+  (`bindings-file`, `state-dir`, `harvest-runtime`, `harvest-model`).
+- [configuration.md](../configuration.md), [workspaces.md](../workspaces.md)
+  and [souls-and-instances.md](../souls-and-instances.md) describe the clone
+  order, the new status and preview fields, and the per-commit soul cache.
+
+## Known limitations
+
+- oats.aweb 1.11.2 does not read `team` from the spawn payload and does not
+  treat the deployment directory as an aweb root.
+- OKF 2.1.3 has no soul-payload grammar (`owns` / `reads` on `soul.yaml`),
+  pins owners by path, and has no per-soul harvest opt-out.
+- A deployment without `oats-local.yaml` still spawns through the classic
+  compose path; readiness (`readinessApi: 1`) is still produced by the 0.24
+  tier; `oats-local.yaml` has no `transport:` key.