@awebai/oats 0.25.1 → 0.25.3

package/docs/design/2026-09-23-workspace-v2-implementation-plan.md

@@ -28,9 +28,9 @@ Each is one PR (or two small ones), reviewed by me, on `main`, as canonical code
 | **W7** | **CLI switch-over** | `oats sync`, `oats spawn` (preview/apply unchanged in shape, now fed by W4/W6), `oats capabilities` / `oats souls` with origin + team, `oats workspace status`; `oats status` shows `modules … @ commit` + `member moved since`; `oats version --json` advertises `workspaceApi: 2` + feature `workspace-v2`; **remove the v1 readers** (`oats.yaml`, per-soul `source:`, `oats-config.yaml` activation) — a v1 file at a v2 path errors naming the schema | lead | M |
 | **W8** | **Delete v1** | Remove `portable-*`, `source-spec`, `capability-provenance` (v1 parts), `prepared-resources`, migration stores/evidence, the installed tier in `packages.mjs`, classic config activation, their tests and docs; `core.mjs` loses everything that only served v1 | lead | L (mostly deletion) |
 | **W9** | **Framework repos as the first workspace (decisions 18–21)** | `oats-workspace.yaml` v2 in `oats` (drop the six imports; `packages:` pins oats.framework/okf/aweb/jira/linear/authoring/dev **as packages**; `teams:` global/engineering; `defaults`); `oats-membership.yaml` in ALL seven repos; the six soul editions rewritten (`oats.okf: {from: package}` etc. even though the repos are members); **a new expert soul in every package repo** — `okf-expert`, `aweb-expert`, `jira-expert`, `linear-expert`, `authoring-expert`, `dev-expert` (v2 `souls/<name>/`, team global, knows and evolves that capability); `package-catalog.json` kept as the official marketplace (bare-version `packages:` entries resolve through it) | lead (member-repo PRs to their owners; the expert souls' AGENTS.md drafted by me, reviewed by the package owner) | L |
-| **W9b** | **`oats.core` and `oats.setup` rewritten for the new architecture (human, 2026-09-23)** | The two official capabilities' skills and injects are rewritten to teach the *new* model, not patched: **`oats.core`** (`oats-operate`, `oats-souls`, the "you run on OATS" inject) — how an agent works inside an instance under this architecture: its home layout (`.oats/modules/`, `.agents/skills/`, `instance.json` modules/providers), the verbs it will actually use (`status`, `spawn --preview/--provider`, `retire`, `session`, `instance events`, `capabilities`, `souls`, `workspace status`), what a workspace/member/package/team is *from the agent's seat*, drift ("member moved since"), how to find and read other souls. **`oats.setup`** (`oats-config`/`oats-packages` → renamed to what they now are: `oats-workspace`, `oats-packages`, `oats-onboarding`) — the whole architecture and its best practices: workspace ↔ repo handshake and why, `oats-workspace.yaml` / `oats-membership.yaml` / `soul.yaml` v2 / `oats-local.yaml` field by field, teams as labels, member-tier vs package-tier and the non-collapse rule, `packages:` + lock v3 + per-version approval, the official catalog vs `git:` refs, `sync`/`package add`, the `<name>-workspace/` convention and clone-then-spawn, private items, external souls, the standalone case, provider payload homes (soul/machine/spawn), what is deliberately NOT versioned and why. Every skill is validated against the shipped CLI (`oats <verb> --help` snapshot test) so they cannot drift from the commands. | lead (swarm + review) | M |
-| **W10** | **Docs** | **`docs/rebuild-to-v2.md` — the rebuild guide (ships with the schemas; states that 0.24.x keeps spawning 0.24.x deployments)**; `docs/workspaces.md` rewritten around v2; `souls-and-instances.md`, `packages.md`, `configuration.md` (mostly deleted), `first-team.md` → the `<name>-workspace/` convention; DTO doc § Workspace v2; release notes | lead | M |
-| **W11** | **Onboarding skill** | `oats-setup-expert` / `oats.setup`: teach `<name>-workspace/`, `oats sync`, clone-then-spawn; **the hosting rule for mixed public/private organisations (decision 26): ask up front whether any member is private; if so the workspace file is hosted in a private repo that is NOT a public member (a dedicated private `workspace` repo is the honest shape), public contributors get the standalone case with `oats.core` by default (decision 25); `oats onboard` prints the same rule in its next-steps**; the `oats-operate` skill updated for the new verbs | lead | S |
+| **W9b** | **`oats.core` and `oats.setup` rewritten for the new architecture (human, 2026-09-23)** | The two official capabilities' skills and injects are rewritten to teach the *new* model, not patched: **`oats.core`** (`oats-operate`, `oats-souls`, the "you run on OATS" inject) — how an agent works inside an instance under this architecture: its home layout (`.oats/modules/`, `.agents/skills/`, `instance.json` modules/providers), the verbs it will actually use (`status`, `spawn --preview/--provider`, `retire`, `session`, `instance events`, `capabilities`, `souls`, `workspace status`), what a workspace/member/package/team is *from the agent's seat*, drift ("member moved since"), how to find and read other souls. **`oats.setup`** (`oats-config`/`oats-packages` → renamed to what they now are: `oats-workspace`, `oats-packages`, `oats-onboarding`) — the whole architecture and its best practices: workspace ↔ repo handshake and why, `oats-workspace.yaml` / `oats-membership.yaml` / `soul.yaml` v2 / `oats-local.yaml` field by field, teams as labels, member-tier vs package-tier and the non-collapse rule, `packages:` + lock v3 + per-version approval, the official catalog vs `git:` refs, `sync`/`package add`, the deployment directory (the operator's; no naming convention) and clone-then-spawn, private items, external souls, the standalone case, provider payload homes (soul/machine/spawn), what is deliberately NOT versioned and why. Every skill is validated against the shipped CLI (`oats <verb> --help` snapshot test) so they cannot drift from the commands. | lead (swarm + review) | M |
+| **W10** | **Docs** | **`docs/rebuild-to-v2.md` — the rebuild guide (ships with the schemas; states that 0.24.x keeps spawning 0.24.x deployments)**; `docs/workspaces.md` rewritten around v2; `souls-and-instances.md`, `packages.md`, `configuration.md` (mostly deleted), `first-team.md` → the operator's deployment directory; DTO doc § Workspace v2; release notes | lead | M |
+| **W11** | **Onboarding skill** | `oats-setup-expert` / `oats.setup`: ASK for the deployment directory (an existing folder with the operator's clones is the usual case — no named convention, decision 9), `oats sync`, clone-then-spawn; **the hosting rule for mixed public/private organisations (decision 26): ask up front whether any member is private; if so the workspace file is hosted in a private repo that is NOT a public member (a dedicated private `workspace` repo is the honest shape), public contributors get the standalone case with `oats.core` by default (decision 25); `oats onboard` prints the same rule in its next-steps**; the `oats-operate` skill updated for the new verbs | lead | S |
 | **W12** | **Desktop follow-through** | New kernel DTOs (from W7) consumed the usual way — engineer reads the merged head, files pins, wires: Capabilities/Souls origin + team columns; "installed" removed as a state; spawn preview shows modules (from/commit/hash) + team; Workspaces surface shows membership status | Desktop engineer, after W7 | M |
 
 **Team review (Antares, 2026-09-23) folded in:** rebuild guide (W10), **second review (two aweb teams, stores, soul layout, standalone, public/private hosting → decisions 23–26: `messaging.byTeam`, stores = repo + provider `root`, `souls/` only, `oats.core` standalone default, private host rule taught by onboarding),** `--provider` instance payload (W6/W7), drift display (W7), duplicate-name rule (W6), 0.24.x-keeps-working stated everywhere.

package/docs/desktop-cli-api.md

@@ -748,7 +748,7 @@ Every `commit` is a full 40-hex OID; every digest is `sha256-<hex>`; every
 `oats onboard [<dir>] --workspace <repo ref> [--json]`
 
 The **bootstrap** of a deployment (decision 9): realizes a workspace on this
-machine in the taught `<name>-workspace/` layout. It writes
+machine in the directory the operator chooses (any existing folder). It writes
 `<dir>/oats-local.yaml` (`{ schemaVersion: 2, workspace: <ref> }`), creates
 `<dir>/agents/` (the instance homes), then runs exactly the `oats sync` body
 over the directory just written — discover over the remotes, confirm

package/docs/desktop.md

@@ -86,7 +86,7 @@ The app starts on the directory it was launched with (its own folder by
 default). To view a deployment, open the workspace switcher in the sidebar
 and choose **Add workspace → Browse**, then point it at an OATS deployment —
 a directory containing `agents/` (under the 0.25 workspace model that is the
-`<name>-workspace/` directory holding `oats-local.yaml` and `agents/`;
+deployment directory (the operator's choice) holding `oats-local.yaml` and `agents/`;
 under 0.24, an `agents/` root, a `local-agents/` root for machine-local souls,
 or a team scope whose `oats-config.yaml` declares `team:`). *The Desktop's own
 multi-repo roster ("team scopes show every member repo's agents under one

package/docs/first-team.md

@@ -56,15 +56,15 @@ one soul and, optionally, one capability. Every soul gets `oats.core` from the
 the resulting layout).
 
 ```bash
-oats onboard ~/acme-workspace --workspace git:github.com/acme/agents
+oats onboard ~/acme --workspace git:github.com/acme/agents     # any directory — an existing one with your clones is fine
 ```
 
 ```
-~/acme-workspace/                 # the taught "<name>-workspace" convention
+~/acme/                           # the directory you chose; these three entries are what the kernel needs
 ├── oats-local.yaml               # { schemaVersion: 2, workspace: git:github.com/acme/agents }
 ├── oats-lock.json                # lockfileVersion 3: commit + integrity + approval per package
 ├── agents/                       # instance homes
-└── <member>/                     # clones of the members you work IN (printed as next steps)
+└── <member>/                     # clones of the members you work IN — here or anywhere named in oats-local.yaml clones:
 ```
 
 Read the report it prints: every member row must be `✓↔` (confirmed) — fix

package/docs/knowledge.md

@@ -66,9 +66,11 @@ packages:
 defaults:
   knowledge: { oats.okf: { from: package } }
 
-# souls/domain-expert/soul.yaml
+# souls/domain-expert/soul.yaml — nothing under knowledge: for oats.okf; the default fills the slot.
+# What the soul owns/reads is souls/domain-expert/okf.json (below), not a soul.yaml payload.
+# A soul-true binding setting is the one thing the payload may carry, e.g.:
 knowledge:
-  owns: domain-expert
+  harvest-runtime: claude
 
 # oats-local.yaml (this machine)
 settings:
@@ -79,11 +81,14 @@ settings:
 
 ```bash
 oats sync                                  # resolves v2.1.3 to a commit, asks executable approval once
-oats spawn domain-expert --preview --json  # the exact oats.okf module (package, version, commit)
+oats spawn domain-expert --preview --json  # the exact oats.okf module (package, version, commit) + settings.oats.okf (the merged payload)
 ```
 
-Pinning activates nothing by itself: the soul's `knowledge:` payload and the
-machine's `settings.oats.okf` must be bindable. The lock stays exact until the
+Pinning activates nothing by itself: the soul's `okf.json` must exist and the
+merged payload (soul `knowledge:` ⊕ `settings.oats.okf` ⊕ `--provider`) must be
+bindable — it may carry **only** the four settings below (`bindings-file`,
+`state-dir`, `harvest-runtime`, `harvest-model`); `owns`/`reads`/`root` on the
+soul payload are refused by 2.1.3, not read. The lock stays exact until the
 workspace bumps `packages.oats.okf`; v1 operators must plan migration before
 that bump. Executable changes come with a new version and a new approval. A
 service worker need not itself fill the knowledge slot (`knowledge: none`).
@@ -129,8 +134,10 @@ directory, not the current working directory:
   source homes/worktrees; keep the bindings file outside state and bases. Local
   Git locators must not be disposable linked worktrees. Directory lock/journal
   artifacts also must not overlap state, sources or another base.
-- Settings are `bindings-file`, `harvest-runtime` (`pi`, `claude`, `codex`,
-  default `pi`), and optional `harvest-model`. Choose an installed, authenticated
+- Settings are `bindings-file`, `state-dir` (both required, absolute host
+  paths), `harvest-runtime` (`pi`, `claude`, `codex`, default `pi`), and
+  optional `harvest-model` — the complete list a 2.1.3 payload may carry.
+  Choose an installed, authenticated
   worker runtime independently of the source; omitted models use that runtime's
   configured default. V1 record-window settings are not v2 settings.
 

package/docs/rebuild-to-v2.md

@@ -48,6 +48,8 @@ capabilities plus `oats.core`), so a public soul stays usable.
 Two teams that need two different messaging identities (an open-source team
 and a hosted-operations team, say) stay in ONE workspace: `team:` is a label,
 and the provider payload is addressed by label under `messaging.byTeam` (§2).
+Read §8b before relying on it: the kernel merges `byTeam`, but oats.aweb 1.11.2
+does not yet read the `team` it delivers.
 
 ## 2. Write `oats-workspace.yaml` v2 in the host repo
 
@@ -141,7 +143,7 @@ they enumerate `souls/*/soul.yaml`. A soul left under `agents/` is invisible to
 | `stores.inherit` | delete (stores are declared once in the workspace) |
 | `imports` | delete |
 | `kind`, `type`, `repo`, `runtime`, `model`, `launch-config` | delete — model/runtime/launch config are spawn-time choices; `team:` replaces `type:` as the grouping |
-| `knowledge:` / `messaging:` payload | keep as is (opaque provider payload); `none` empties the slot |
+| `knowledge:` / `messaging:` payload | keep as is (opaque provider payload); `none` empties the slot. **For `oats.okf` see the box below: the payload is the binding's SETTINGS keys only; what the soul owns/reads stays in `okf.json`** |
 | — | `compatibility: { <cap>: ">=x.y" }` if you want a floor |
 
 ```yaml
@@ -152,9 +154,8 @@ work: worktree
 team: engineering
 capabilities:
   acme-release-tooling: { from: here }
-knowledge:
-  owns: release-manager
-  reads: [platform-engineer]
+# knowledge: — nothing here for oats.okf: the workspace default fills the slot and
+#   souls/release-manager/okf.json (below) says what this soul owns and reads.
 messaging:
   channels: [acme-eng]
 ```
@@ -164,6 +165,48 @@ are required. Capabilities the repo exports live at
 `capabilities/<name>/oats.json` — the manifest is unchanged; you may add
 `private: true` / `team:`.
 
+**`oats.okf` 2.1.3 reads `souls/<name>/okf.json`, not a `knowledge:` payload.**
+Earlier drafts of this guide showed `knowledge: { owns: …, reads: … }` or
+`knowledge: { store, root }` on the soul; **no shipped provider consumes those
+keys**. What OKF 2.1.3 actually reads at spawn is two things:
+
+1. **`<soul>/okf.json`** (travels with the soul, fetched into the per-commit
+   soul cache like `AGENTS.md`) — the soul's knowledge declaration, exactly
+   these keys and no others:
+
+   ```json
+   { "version": 1,
+     "owner": "release-manager",
+     "owns":  ["org/release-manager"],
+     "reads": ["org/platform-engineer"] }
+   ```
+
+   `owner` is the stable owner id (what `owners.json` pins, §7b); `owns` /
+   `reads` are `<base alias>/<node>` references into the bases the machine's
+   bindings file declares (`oats okf init` / `oats okf migrate` write it;
+   `capabilities/oats-okf/lib/config.mjs#validateDeclaration` is the
+   authority). Keep the file where 0.24 had it — it moves with the soul in
+   §3b. A soul without `okf.json` whose slot resolves to `oats.okf` fails the
+   required spawn hook (`soul has no okf.json`), by design.
+2. **The merged payload, as `OATS_SETTINGS`** — the binding's **settings
+   keys only**, the list in `capabilities/oats-okf/oats.json#settings`:
+   `bindings-file`, `state-dir` (both required, absolute host paths →
+   `oats-local.yaml`, §5), `harvest-runtime`, `harvest-model` (optional). Any
+   other key — `owns`, `reads`, `store`, `root`, `stores` — is refused
+   (`unknown OATS_SETTINGS property`). So for `oats.okf` the soul's
+   `knowledge:` payload is normally **absent** (the workspace default
+   `defaults.knowledge: { oats.okf: { from: package } }` fills the slot) or
+   carries a soul-true binding setting such as `harvest-runtime: claude`;
+   `knowledge: none` opts the soul out.
+
+`stores:` in the workspace file names repositories for the **workspace**; where
+OKF's bases live inside them is a **bindings-file** concern today (`bases.<alias>`
+with `repository` + `root`), not a soul payload key. A soul payload grammar for
+OKF (`owns`/`reads`/`root` on `soul.yaml`) is an OKF follow-up (it lands with an
+`oats.okf` release that declares it in its binding, and this guide will say so);
+until then the kernel forwards the payload opaquely and OKF refuses what it does
+not know.
+
 **Carry `team:` on every soul, or on its repo's membership.** A soul's team is
 `soul.yaml#team`, else `oats-membership.yaml#team`, else *unassigned*
 (`null`). Labels never gate anything, but the kernel addresses provider payload
@@ -175,25 +218,27 @@ outside every team-addressed payload; nothing refuses it. Label the membership
 when a whole repo belongs to one team, and the soul when it does not.
 
 **Per-soul memory-harvest opt-out:** not available in OKF 2.1.3 — an OKF 2.1.4
-item. The 2.1.3 `knowledge:` payload admits `owner`, `owns`, `reads` and
-`stores` (plus the kernel-rendered `runtime`/`execution`); there is no key that
-keeps a soul registered for reads while excluding it from harvest. A soul that
-must not be harvested today says `knowledge: none` (no OKF at all for that
-soul) or `oats.okf: off`; do not invent a key — the binding refuses unknown
-payload keys.
+item. Neither `okf.json` (`version`, `owner`, `owns`, `reads`) nor the settings
+payload (`bindings-file`, `state-dir`, `harvest-runtime`, `harvest-model`) has a
+key that keeps a soul registered for reads while excluding it from harvest. A
+soul that must not be harvested today says `knowledge: none` (no OKF at all for
+that soul) or `oats.okf: off`; do not invent a key — both readers refuse unknown
+keys.
 
 ## 5. Write `oats-local.yaml` on each machine
 
 ```
-~/acme-workspace/                 # the taught convention: "<name>-workspace"
+~/acme/                           # the directory YOU choose — an existing folder with your clones is the usual case
 ├── oats-local.yaml
-├── agents/                       # instance homes
-└── platform/                     # member clones, only where someone works IN them
+├── agents/                       # instance homes — created by `oats sync` if absent (0.25.2)
+└── platform/                     # member clones, wherever you keep them (here, or named in clones:)
 ```
 
 ```yaml
 schemaVersion: 2
 workspace: git:github.com/acme/agents
+clones:                                     # optional: member clones that are NOT at <deployment>/<member name>
+  github.com/acme/platform: /Users/ana/src/acme-platform
 settings:                                   # what used to be `settings:` under capabilities.layers.* in oats-config.yaml
   oats.okf:
     bindings-file: /Users/ana/.oats/okf-bindings.json   # required by the OKF binding: absolute host path
@@ -205,6 +250,27 @@ souls:
   disabled: [data-analyst]
 ```
 
+**Where the kernel looks for a member clone** (a `work: worktree | checkout`
+soul needs one; nothing else does). In this order, first hit wins:
+
+1. `oats spawn … --repo <abs path>` — this spawn only.
+2. `oats-local.yaml` `clones: { <repo key>: <abs path> }` — the key is the
+   member's **canonical key** (`github.com/acme/platform`; any ref spelling you
+   write is normalised through `parseRepoRef`, so `git:github.com/acme/platform`
+   and `https://github.com/acme/platform.git` address the same entry).
+3. The convention: `<deployment>/<member name>` — the last path segment of the
+   repo key (`platform` for `github.com/acme/platform`). One exception: a member
+   whose name is `agents` is looked for at `<deployment>/agents-repo`, because
+   `<deployment>/agents/` is the instance root (above).
+4. None found → `E_CLONE_MISSING`, naming the three remedies. A directory that
+   *is* found but whose `origin` remote is a **different repo** →
+   `E_CLONE_MISMATCH` (the clone is not the member; nothing is spawned into it).
+
+This order was documented before 0.25.2 but the kernel did not honour it (a
+clone had to be `--repo`'d or sit at the convention); 0.25.2 implements it as
+written here. If your host repo is named `agents`, clone it as
+`<deployment>/agents-repo` or name it in `clones:`.
+
 `settings.<cap>` is merged into that capability's payload after the soul's
 slot payload and before `spawn --provider` (decision 14); the keys are the
 capability's own (`oats.json#settings`). For **`oats.okf` 2.1.3** the binding
@@ -220,8 +286,12 @@ here but see §8 for why it belongs at spawn.
 Move host paths from `oats-config.yaml` `settings:` here; the `souls:` blocks of
 `oats-config.yaml` become `--provider` flags at spawn (step 8). Delete
 `oats-config.yaml`; it is not read. Do not commit `oats-local.yaml`.
-(`oats onboard <dir> --workspace <repo ref>` writes a minimal `oats-local.yaml`
-and runs the first `sync` for you; add `settings:` afterwards.)
+(`oats onboard <dir> --workspace <repo ref>` writes a minimal `oats-local.yaml`,
+creates `agents/` and runs the first `sync` for you; add `settings:` afterwards.
+Its `next.clone` list names **every** member that lacks a clone at the
+convention — the host included: the host is a member like any other, and a
+soul that lives in it and says `work: worktree` needs its clone too. Under an
+explicit `standalone:` header the list says so and names only that repo.)
 
 ## 6. `oats sync`
 
@@ -231,11 +301,17 @@ From the deployment directory:
 oats sync
 ```
 
-It confirms every member (fix any `no-backlink` / `backlink-elsewhere` /
-`cannot-read` row before going on), resolves `packages:` to commits, writes
-`oats-lock.json` (lockfileVersion 3) and asks for executable approval once per
-package version. The 0.24 lock is not read; delete it (`E_LOCK_SCHEMA` names
-it if you leave it in the way).
+It creates `agents/` if it is absent (0.25.2; a hand-written `oats-local.yaml`
+no longer needs a `mkdir`), confirms every member (fix any `no-backlink` /
+`backlink-elsewhere` / `cannot-read` row before going on), resolves `packages:`
+to commits, writes `oats-lock.json` (lockfileVersion 3) and asks for executable
+approval once per package version. The 0.24 lock is not read; delete it
+(`E_LOCK_SCHEMA` names it if you leave it in the way).
+
+The legacy "You run on OATS" block is no longer composed into `AGENTS.md` when
+`oats.core` resolves as a module (0.25.2): an instance gets **one** such block,
+the one `oats.core`'s inject carries. If you see two, the soul resolved without
+`oats.core` (check `oats spawn <soul> --preview`).
 
 ## 7. Approve packages
 
@@ -243,10 +319,23 @@ Approval is **per package version, once, in the lock** — no `oats trust`, no
 per-capability approval, no per-operator trust list. `oats sync` on a terminal
 prints every executable (`commands.*` and `hooks.*.command` targets of every
 capability the package provides) and asks `approve <id> <version>? [y/N]`.
-Declined or non-interactive → exit `2`, the lock records the entry
-unapproved, and spawns of souls using it are refused (`E_PACKAGE_UNAPPROVED`)
-until you run `oats sync` in a terminal and say yes. Member capabilities need no
-approval: membership is the trust.
+Declined, **Ctrl+D at the prompt**, or non-interactive → exit `2`, the lock
+records the entry unapproved, and spawns of souls using it are refused
+(`E_PACKAGE_UNAPPROVED`) until you run `oats sync` in a terminal and say yes.
+Member capabilities need no approval: membership is the trust.
+
+**Non-interactive approval (CI, scripted rebuilds):**
+
+```bash
+oats sync --approve oats.okf@v2.1.3 --approve oats.aweb@v1.11.2
+```
+
+`--approve <id>@<version>` is repeatable and approves **exactly** the entry the
+resolution contains for that id and version — the executables digest is always
+computed by `sync` over the fetched tree and recorded in the lock; you never
+type a digest. An `--approve` that names an id or version the resolution does
+not contain is an error, not a silent skip; an entry the flags do not cover
+stays unapproved (exit `2`, as above).
 
 ## 7b. OKF 2: start a FRESH `state-dir` — do not re-point the old one
 
@@ -309,16 +398,83 @@ machine-level setting would give the seat to EVERY instance of every messaging
 soul on that machine, and a seat can be held once. The Desktop's
 confirmed apply carries the same map.
 
+## 8b. Where the team `.aw` lives now (oats.aweb 1.11.2), and what `byTeam` does today
+
+A freshly minted identity (every spawn without `identity.source`) needs an
+**initialised aweb root**: a directory holding `.aw` with a team membership to
+mint into. oats.aweb 1.11.2's spawn hook looks for `.aw` among these, first hit
+wins: the declared team scope (`OATS_TEAM_SCOPE`, from the removed
+`oats-config.yaml` `team:` block — **empty under v2**), the instance home, the
+git repo containing the home, the resolution context (the soul's work repo) and
+the git repo containing it, and the workspace root (`OATS_WORKSPACE`, which
+under v2 is the **deployment directory** — the one holding `oats-local.yaml`).
+None of these is the 0.24 team root you initialised with `oats aweb setup`, so
+a rebuilt deployment mints nothing until you put `.aw` where the hook looks:
+
+- **at the deployment directory** — `<deployment>/.aw`: one team for every
+  messaging soul spawned here; or
+- **inside a member clone** (gitignored — add `.aw/` to the clone's
+  `.gitignore`; never commit `signing.key`): `<clone>/.aw` is found through the
+  soul's work repo, so souls whose `work:` targets *that* member mint into
+  *that* team.
+
+`cp -R <old team root>/.aw <deployment>/.aw` (or into the clone) carries the
+existing memberships over; `aw team list` from that directory shows the active
+team. A `.aw` at your user home or above the deployment is **not** found on
+purpose (a `.aw` there would be a different team; minting into it would be a
+silent cross-team leak).
+
+**Two teams, two identities — what actually decides the team in 1.11.2.** The
+hook resolves the target team as: `OATS_TEAM_ID` / `OATS_TEAM_NAME` from the
+removed `oats-config.yaml` `team:` block (empty under v2), else **the active
+team at the `.aw` root it found**. It **does not read a `team` key from its
+payload** (`OATS_SETTINGS`): the only payload keys 1.11.2 acts on are
+`delivery` and `identity.source`/`identity.takeOver`. Consequently
+`messaging.byTeam.<label>: { team: aweb:… }` is **kernel-merged and
+delivered, but a NO-OP for oats.aweb 1.11.2** — the kernel does its part
+(`spawn --preview` shows the merged `settings.oats.aweb` with the label's
+`team`, and `instance.json.providers.oats.aweb` records it); the provider
+ignores it until an oats.aweb release reads `team` from the payload. Until then
+the only way to get per-label minting is **per-repo placement**: give each
+team's member clone its own `.aw` whose active team is that team’s, and make
+sure the souls of that team say `work: worktree | checkout` **on that repo**.
+A soul with `work: directory | workspace` has no member clone as context and
+falls through to `<deployment>/.aw` — one team only. Keep `byTeam` in the
+workspace file anyway: it is the declared intent, the kernel honours it, and
+the next oats.aweb picks it up without a workspace edit.
+
 ## 9. Spawn, and check drift
 
 ```bash
 oats souls                    # every non-private soul of every confirmed member, with origin and team
 oats capabilities             # every capability, member (origin: member <key> @ <commit>) or package (package <id> v<ver>)
-oats spawn <soul> --preview   # modules[] with from/commit/changedSince, team, resolution revision
+oats spawn <soul> --preview   # modules[] with from/commit/changedSince, team, resolution revision,
+                              #   providers (the --provider map as given) and settings.<cap> (the merged payload each provider receives)
 oats spawn <soul> --purpose x
-oats status                   # per instance: modules … [member moved since (now @ …)] / [capability no longer present]
+oats status                   # per instance: soul: <name> from <member> @ <c7>  [member moved since …]
+                              #               modules … [member moved since (now @ …)] / [capability no longer present]
 ```
 
+`--preview` (0.25.2) prints `providers` — exactly the `--provider <cap> k=v`
+map you gave — and `settings.<cap>` — the **merged** payload the provider's
+binding will receive (`workspace.messaging` base ⊕ `byTeam[team]` ⊕ soul slot
+payload ⊕ `oats-local.yaml settings.<cap>` ⊕ `--provider`), so you can see
+before creating anything that `state-dir` is the fresh one (§7b) and that the
+team block reached the payload (§8b). `oats status` (0.25.2) shows drift for
+the **soul source** as well as for modules: `soul: <name> from <member> @ <c7>`
+with `[member moved since …]` when the member's default branch has moved past
+the commit the instance was spawned from; `--json` carries it as
+`instances[].soul { repoKey, commit, current, status }`. A moved soul is
+information, not a fault — the running instance keeps its own commit (§7b);
+re-spawn when you want the new one.
+
+**Work modes and clones.** `work: worktree | checkout` needs the member clone
+(§5 order); `work: directory` needs nothing; `work: workspace` (a coordination
+soul) links `./work` to the **deployment directory** — the one holding
+`oats-local.yaml`, with `agents/` and whatever clones sit beside it — read-only
+across members, no branch (0.25.1). Such a soul finds a member whose clone is
+elsewhere through `oats-local.yaml` `clones:`.
+
 ## What disappears
 
 | Gone | Replaced by |

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

@@ -0,0 +1,80 @@
+# 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.
+
+**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`.
+
+## 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.
+
+## 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.

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

@@ -0,0 +1,19 @@
+# OATS v0.25.3 — `OATS_SOUL_ID`
+
+Kernel/Pi **0.25.3**. Tag `v0.25.3` → the commit carrying these notes. No API change;
+`features[]` unchanged; one additive hook environment variable and one additive
+`instance.json` field.
+
+## Kernel
+
+- **`OATS_SOUL_ID`** — a soul's stable identity for capability hooks (`spawn`,
+  `retire`, `launch`): `<repo key>#<soul name>` for a workspace soul, the realpath of
+  `agents/<name>/soul` for a classic soul. Recorded as `instance.json.workspace.soul.id`.
+  Fixes the consequence of 0.25.1's per-commit soul cache found by the first outsider
+  rebuild: OKF 2.1.3 pins a soul's owner to `realpath(home/soul)`, which now changes with
+  every member commit → the next spawn of the same soul was refused `E_OWNER`. The provider
+  half (owners keyed by `OATS_SOUL_ID`, one-time migration of path pins) ships in OKF 2.1.4.
+- **`OATS_SOUL` is the content the home links** — for a workspace soul the per-commit
+  directory, never the swappable `agents/<name>/soul` pointer (spawn and retire hooks agree).
+
+Contract: `docs/design/2026-09-23-workspace-module-contracts.md` § "0.25.3 — OATS_SOUL_ID".