@awebai/oats 0.25.1 → 0.25.2

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/souls-and-instances.md

@@ -25,10 +25,12 @@ A soul is durable and committed. It is the part you review, improve, and keep.
   AGENTS.md            # canonical operating doc
   CLAUDE.md → AGENTS.md
   skills/              # skills specific to this expert
+  okf.json             # if the soul uses oats.okf: { version: 1, owner, owns: ["<base>/<node>"], reads: […] } — the provider's, not the kernel's
 ```
 
-(A deployment's own `agents/<name>/soul/` has the same shape; a member soul is
-fetched there at its discovered commit before its first spawn.)
+(A deployment's `agents/<name>/souls/<commit12>/` has the same shape; a member
+soul is fetched there at its discovered commit before its first spawn, and
+`agents/<name>/soul` points at the current commit.)
 
 ### `soul.yaml` v2
 
@@ -47,8 +49,8 @@ capabilities:                             # WHERE each capability comes from —
   acme-house-style: off                   # removes a workspace/team default
 
 knowledge:                                # provider payloads — opaque to the kernel, consumed by the slot's capability
-  owns: release-manager
-  reads: [platform-engineer]
+  harvest-runtime: claude                 #   (oats.okf 2.1.3 reads only its binding's settings keys here; what the soul
+                                          #    owns/reads is in this directory's okf.json — see "Soul anatomy")
 messaging:
   channels: [acme-eng]
 tasks: none                               # `none` empties the slot (drops the workspace default)
@@ -63,7 +65,7 @@ compatibility:                            # optional floors on PACKAGE versions
 | `team` | A label declared in the workspace's `teams:`; may add `defaults.byTeam` capabilities. Never gates or restricts. |
 | `private` | `true` keeps the soul out of workspace discovery; its own repo can still spawn it. |
 | `capabilities` | `<cap>: { from: here \| <repo key> \| package }` or `<cap>: off`. Composed over `defaults.<slot>` ⊕ `defaults.capabilities` ⊕ `defaults.byTeam[team]`; the soul wins. |
-| `knowledge` / `messaging` / `tasks` | The slot's provider payload (true of every instance of the soul), or `none`. Merged with `oats-local.yaml` `settings.<cap>` and `spawn --provider <cap>`; the provider's `binding` contract validates the result. |
+| `knowledge` / `messaging` / `tasks` | The slot's provider payload (true of every instance of the soul), or `none`. Merged with `oats-local.yaml` `settings.<cap>` and `spawn --provider <cap>`; the provider's `binding` contract validates the result — and refuses keys it does not declare. For `oats.okf` 2.1.3 the admitted keys are its settings (`bindings-file`, `state-dir`, `harvest-runtime`, `harvest-model`); the soul's `owns`/`reads` live in `souls/<name>/okf.json`, which OKF reads from the soul directory. |
 | `compatibility` | `<cap>: <semver range>` checked against the locked package version (`E_COMPATIBILITY`). |
 
 Schema: [`soul.schema.json`](soul.schema.json). Not in v2: `kind`, `type`,
@@ -82,7 +84,9 @@ souls — is ordinary capability content: **`oats.core`** (package
 `defaults.capabilities: { oats.core: { from: package } }`; a soul may say
 `oats.core: off`. **`oats.setup`** (same package) carries the whole-architecture
 knowledge an onboarding expert needs. Neither is kernel magic; the kernel still
-composes its own instance-boundary and work-mode briefings.
+composes its own instance-boundary and work-mode briefings — and, when
+`oats.core` resolves as a module, leaves the "You run on OATS" briefing to the
+module's inject (one block, not two; 0.25.2).
 
 ## Instance anatomy
 
@@ -134,7 +138,7 @@ skills and instructions), a workspace spawn records:
     }
   },
   "providers": {
-    "oats.okf": { "owns": "release-manager", "reads": ["platform-engineer"], "state-dir": "/Users/ana/.oats/okf" },
+    "oats.okf": { "bindings-file": "/Users/ana/.oats/okf-bindings.json", "state-dir": "/Users/ana/.oats/okf", "harvest-runtime": "claude" },
     "acme-release-tooling": {}
   },
   "workspace": {
@@ -149,9 +153,13 @@ skills and instructions), a workspace spawn records:
   shows `moved` / `missing` per module (drift is shown, not prevented).
 - `providers.<cap>` — the merged provider payload the capability was bound with
   (soul ⊕ machine settings ⊕ `--provider`), so a later inspection can tell
-  which instance holds a retained seat or a one-off state root.
+  which instance holds a retained seat or a one-off state root. `spawn
+  --preview` shows the same map before anything exists, as `settings.<cap>`,
+  beside `providers` (the `--provider` flags as given).
 - `workspace` — the workspace commit observed at spawn, the soul's repo/commit/
-  team, and the **resolution revision** the spawn decision bound.
+  team, and the **resolution revision** the spawn decision bound. `oats status`
+  compares `workspace.soul` with the member's current commit too: `soul: <name>
+  from <member> @ <c7>  [member moved since …]` (`--json`: `instances[].soul`).
 
 A running instance never changes under itself: a member moving or a package
 bump affects only new spawns.
@@ -183,7 +191,9 @@ From a deployment (where `oats-local.yaml` is), a spawn: reads the local file
 discovers the workspace over its remotes and confirms membership → finds the
 soul among the confirmed members (or `external:`; an ambiguous bare name is
 `E_SOUL_AMBIGUOUS` — say `<repo>/<soul>`) → fetches the soul's source into
-`<agents-root>/<soul>/soul/` at its commit → resolves every capability by
+`<agents-root>/<soul>/souls/<commit12>/` at its commit (the home links that
+directory; `<agents-root>/<soul>/soul` points at the current one) → resolves
+every capability by
 `from:` (member = latest, package = locked + approved) → creates the home →
 **materializes each module whole** into `.oats/modules/` and copies its skills
 into `.agents/skills/` (a transaction: any failure leaves nothing behind) →
@@ -194,8 +204,10 @@ unchanged. This is a normal agent process with its own home and tools, not a
 subagent call.
 
 `--preview` reports `modules[]` (`from`, `layer`, `changedSince` the newest
-previous instance of the soul), `team`, the `resolution` revision and the
-decision it would bind; the apply refuses with `E_DECISION_STALE` if a member
+previous instance of the soul), `team`, the `resolution` revision, the decision
+it would bind, `providers` (the `--provider` map exactly as given) and
+`settings.<cap>` (the merged payload each provider's binding will receive);
+the apply refuses with `E_DECISION_STALE` if a member
 moved in between. `--provider <cap> key=value` (repeatable; dotted keys nest)
 must name a capability the soul resolves (`E_CAPABILITY_MISSING` otherwise) and
 needs a workspace deployment. The full DTOs are in
@@ -324,7 +336,10 @@ directory is for, not a place to settle in.
 ### `worktree` — isolated branch
 
 `work/` is a git worktree on the instance's own branch, by default
-`agents/<instance>`.
+`agents/<instance>`. The worktree is created from the member's **clone**, found
+as `--repo`, then `oats-local.yaml` `clones:`, then `<deployment>/<member name>`
+(`E_CLONE_MISSING` / `E_CLONE_MISMATCH` otherwise — see
+[configuration.md](configuration.md)).
 
 Use this for agents that will edit code or docs independently.
 
@@ -341,7 +356,8 @@ inside each fresh worktree. Failures warn but do not block spawn.
 
 ### `checkout` — shared current branch
 
-`work/` is a symlink to the repo checkout itself.
+`work/` is a symlink to the repo checkout itself (the member clone, found as for
+`worktree`).
 
 Use this for maintainers, coordinators, auditors, or agents working on the
 repo's current state.
@@ -382,8 +398,10 @@ exchanged for a symlink. Recovery does not replace the worker's delivery protoco
 
 ### `workspace` — cross-repo coordinator
 
-`work/` is a symlink to the **whole deployment** (the `<name>-workspace/`
-directory holding `oats-local.yaml` and the member clones) — not a repo. Every
+`work/` is a symlink to the **whole deployment** — the directory holding
+`oats-local.yaml`, with `agents/` and the member clones that sit beside it —
+not a repo (0.25.1; a member cloned elsewhere is reached through
+`oats-local.yaml` `clones:`). Every
 member repo is read-context; the instance's product is coordination:
 routing, analysis, task-writing, messaging, spawning specialists.