@awebai/oats 0.25.0 → 0.25.2

package/docs/rebuild-to-v2.md

@@ -16,6 +16,19 @@ schemaVersion 2 only; found 1"`, `E_LOCK_SCHEMA`), never a silent fallback.
 Keep the 0.24 kernel installed until the last 0.24 deployment you care about is
 rebuilt; the two do not share files.
 
+**One thing a 0.25 kernel changes for a classic home it does launch.** Decision
+13 ("harnesses start normally") is a property of the 0.25 *launcher*, not of the
+v2 files: every `pi` launch a 0.25 kernel performs — `oats spawn`, `oats session
+start|restart`, scheduled runs — starts pi with cwd = the instance home and pi's
+own skill and context discovery intact (`--append-system-prompt <home>/AGENTS.md`,
+no `--no-skills` / `--no-context-files` / `--no-prompt-templates` exclusion).
+That holds for a classic 0.24 home (no `oats-local.yaml`, spawned through the
+pre-v2 compose path that 0.25 still carries) exactly as for a module home. If you
+relied on 0.24's ambient-skill exclusion to hide machine-level or repo-level
+skills from an instance, that isolation is gone the moment a 0.25 kernel
+launches it — keep the 0.24 kernel for those homes, or accept the ambient set
+(the spawn preview lists composed skill names so a clash is visible).
+
 ## 1. Decide the one workspace
 
 One workspace per organisation. Pick the repo that **hosts**
@@ -35,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
 
@@ -93,6 +108,29 @@ Delete `oats.yaml`. Its `exports:` lists are gone: every `souls/*/soul.yaml` and
 `capabilities/*/oats.json` is discoverable; add `private: true` to the ones that
 should stay internal. The host repo backlinks to itself like any member.
 
+## 3b. Move the souls: `agents/<name>/soul/` → `souls/<name>/`
+
+In 0.24 a repo's souls lived at `agents/<name>/soul/` beside that soul's
+instances. Under v2 discovery looks **only** at `souls/<name>/soul.yaml`; the
+`agents/` directory belongs to the *deployment* (instance homes and, under the
+kernel's per-commit soul cache, the fetched soul copies — see §7b) and is not
+read as a soul source. Move every soul as a tracked rename so history follows:
+
+```bash
+mkdir -p souls
+git mv agents/release-manager/soul souls/release-manager
+# … one line per soul; then
+git rm -r --cached agents 2>/dev/null; echo 'agents/' >> .gitignore   # instances were never meant to be tracked
+```
+
+`souls/<name>/` keeps its `AGENTS.md`, `CLAUDE.md → AGENTS.md` alias, `skills/`,
+`knowledge/` and `soul.yaml` (rewritten in §4); the directory name must equal
+`soul.yaml#name`. Then fix whatever enumerates the old path: repo tests, scripts,
+CI checks and any `oats.yaml`-era `exports:` tooling that globbed
+`agents/*/soul/soul.yaml` (`git grep -n 'agents/.*/soul'` finds them) — under v2
+they enumerate `souls/*/soul.yaml`. A soul left under `agents/` is invisible to
+`oats souls` and to `oats spawn`; nothing warns about it.
+
 ## 4. Edit every `soul.yaml` to v2
 
 | 0.24 | v2 |
@@ -105,7 +143,7 @@ should stay internal. The host repo backlinks to itself like any member.
 | `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
@@ -116,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]
 ```
@@ -128,31 +165,133 @@ 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
+by label: an unlabelled soul receives the messaging **base** payload only —
+`workspace.messaging` minus `byTeam`, no `byTeam.<label>` block, and no
+`defaults.byTeam.<label>` capabilities either. If your 0.24 deployment had one
+messaging identity per team (§1), a soul that loses its label silently lands
+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. 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
-    state-dir: /Users/ana/.oats/okf
+    bindings-file: /Users/ana/.oats/okf-bindings.json   # required by the OKF binding: absolute host path
+    state-dir: /Users/ana/.oats/okf-state               # required by the OKF binding: absolute host path; FRESH for a rebuilt deployment (§7b)
+    harvest-runtime: pi                                 # optional: pi | claude | codex (default pi)
+  oats.aweb:
+    delivery: channel                                   # channel (default) | session — see capabilities/oats-aweb/oats.json#settings.delivery
 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
+requires both `bindings-file` and `state-dir` as normalized absolute host
+paths (`setting state-dir is required (absolute host path)` is a refusal, not a
+default) and accepts `harvest-runtime` / `harvest-model`. For **`oats.aweb`**
+the one machine-level key is `delivery`: `channel` (the native aweb channel
+packages wake the instance; default) or `session` (delivery is external —
+`AWEB_DELIVERY=session`, the host wake broker registers the instance once it
+exists; requires an `aw` that ships `aw wake`). `identity.source` is also legal
+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`
 
@@ -162,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
 
@@ -174,10 +319,59 @@ 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
+
+OKF 2 pins each knowledge **owner** to a soul by path: at source registration
+(the `oats.okf` spawn hook) it writes `owners.json` in `state-dir` as
+`{ <owner id>: realpath(<home>/soul) }` and refuses a later registration whose
+owner resolves to a different path (`E_OWNER stable owner ID already identifies
+a different soul in this state namespace`).
+
+Under v2 that path is no longer your checkout. `oats spawn` fetches the soul
+from its member repo at the confirmed commit into the deployment's
+**per-commit soul cache**, `agents/<name>/souls/<commit12>/` (immutable once
+written; `agents/<name>/soul` is a kernel-swapped pointer to the current one),
+and the instance's `<home>/soul` links **its own commit's directory** — so the
+realpath the hook pins is `<deployment>/agents/<name>/souls/<commit12>`, which
+never equals the 0.24 pin (`<repo>/agents/<name>/soul`) and changes whenever the
+member moves. Two consequences:
+
+- **Do not reuse the 0.24 `state-dir`.** Its `owners.json` pins every owner to
+  the old path; the first v2 spawn of each soul would be refused with `E_OWNER`.
+  Give the rebuilt deployment a fresh `state-dir` (§5) and a fresh
+  `bindings-file` if the old one names the old state root. The old `state-dir`
+  is **frozen custody**: read-only history (`oats okf inspect --source
+  <old-state>/sources/<id>/source.json …` still works against it), never edited,
+  never re-pointed at the new soul path. Accepted knowledge is not affected —
+  it lives in the bases, not in `state-dir`.
+- **The owner pin is per commit.** OKF 2.1.3 records the realpath at first
+  registration and the kernel keeps that commit directory for as long as any
+  instance links it, so a running instance's pin stays valid; a *later* spawn of
+  the same soul at a newer member commit links a different directory and
+  registers under the same owner id → `E_OWNER` again. Until OKF re-bases the
+  pin on the owner identity rather than the path (an OKF 2.1.4 item), the
+  practical rule is: one `state-dir` per (deployment, soul commit) is safe;
+  moving a member that owns knowledge means a fresh `state-dir` for the new
+  commit's spawns (the previous one becomes frozen custody, as above). Plan
+  knowledge-owning souls' member commits deliberately.
 
 ## 8. Re-take a retained messaging seat with `spawn --provider`
 
@@ -186,32 +380,108 @@ In 0.24, an instance-specific messaging identity (a retained seat) was pinned in
 **spawn**:
 
 ```bash
-oats spawn release-manager --purpose seat --provider oats.aweb identity.source=retained:release-seat
+oats spawn release-manager --purpose seat --provider oats.aweb identity.source=/abs/path/to/retained/.aw
 ```
 
 `--provider <cap> key=value` is repeatable; dotted keys nest. The payload is
 merged after the soul's `messaging:` and the machine's `settings.oats.aweb`, and
 recorded in `instance.json.providers.oats.aweb`, so exactly one instance holds
-the seat while other instances of the soul mint fresh identities. Consult your
-messaging capability's documentation for the exact key it reads. The Desktop's
+the seat while other instances of the soul mint fresh identities.
+
+**The value is the path itself.** `oats.aweb` reads `identity.source` as the
+absolute path of the `.aw` directory to retain (it must hold `signing.key`); the
+kernel does not resolve symbolic seat names. Because it is an absolute path it is
+a fact about ONE machine, so its other legal home is `oats-local.yaml`
+(`settings.oats.aweb.identity.source: /abs/path`) — never the workspace file
+(absolute paths are refused there, decision 14). Prefer the spawn form: a
+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 |
 |---|---|
 | `oats-config.yaml` (and the laptop/workspace/repo config chain, `agent-types`, `capabilities.layers`/`additive`, `souls:`, adopted config templates) | `oats-workspace.yaml` defaults + `soul.yaml` `capabilities:`; `oats-local.yaml` for host settings; `spawn --provider` for per-instance facts |
 | `oats.yaml` | `oats-membership.yaml` |
+| `agents/<name>/soul/` as the tracked soul source | `souls/<name>/` (tracked); `agents/` is deployment state — instance homes and the kernel's per-commit soul cache `agents/<name>/souls/<commit12>/` |
 | `.agents/capabilities/installed/` and `owned/` | nothing is installed; `<instance>/.oats/modules/<cap>/` per instance; member capabilities under `<repo>/capabilities/` |
 | `oats init`, `oats use`, `oats install`, `oats restore`, `oats trust`, `oats list`, `oats catalog`, `oats remove`, `oats migrate`, `oats config` | `oats sync`, `oats package add \| remove`, `oats workspace status`, `oats capabilities`, `oats souls` — each removed verb answers `E_UNKNOWN_COMMAND` naming its replacement |
 | lock v1 / v2 | lock v3 (`packages` only, with `url`, `capabilities`, `approved`) |

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

@@ -0,0 +1,94 @@
+# 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.
+
+**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`.
+
+## 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 →
+  `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`.
+
+## 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).
+
+## Known follow-ups (unchanged from 0.25.0 unless noted)
+
+- 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.

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/schedules.md

@@ -1,12 +1,18 @@
 # Schedules
 
 A schedule launches an agent, runs an oats command, or wakes an existing
-instance on a cron. Definitions belong to a scope, the team workspace (the
-config level that declares the team, else the outermost `oats-config.yaml`
-level), and are committable; every `oats schedule` command run anywhere
-inside that scope, including from an instance home, reads and writes the
-same file. Execution belongs to the host that holds the scope, so a
-schedule on a registered server keeps running while your laptop sleeps.
+instance on a cron. Definitions belong to a scope and are committable; every
+`oats schedule` command run anywhere inside that scope, including from an
+instance home, reads and writes the same file. On a **workspace deployment**
+(0.25, [workspaces.md](workspaces.md)) the scope is the deployment directory
+— the one holding `oats-local.yaml` and the `agents/` root (the kernel derives
+it as the directory above the agents root; a leftover `oats-config.yaml` that
+declares `team:` would still win, so remove it); scheduled spawns there
+materialize exactly like `oats spawn`. On a classic 0.24 deployment the scope
+is the team workspace (the config level that declares the team, else the
+outermost `oats-config.yaml` level). Execution belongs to the host that holds
+the scope, so a schedule on a registered server keeps running while your laptop
+sleeps.
 
 There is no daemon. One host timer (a launchd user agent on macOS, a systemd
 user timer on Linux) runs `oats schedule tick --host` once a minute; the tick