@awebai/oats 0.25.0 → 0.25.1

package/docs/implementation.md

@@ -64,6 +64,20 @@ their names.
 
 ## Resolution
 
+**Workspace model (0.25, current).** `lib/instance-resolution.mjs#prepareInstance(dir, soul)`
+loads `oats-local.yaml`, discovers the workspace over its Git remotes
+(`lib/workspace.mjs#discoverWorkspace`, or the standalone view), finds the
+soul among the confirmed members / external souls, and calls
+`lib/resolve.mjs#resolveSoul` → an immutable Resolution: `modules[]` (each
+`from: member|package` with commit and digest), `slots`, merged provider
+`payloads`, `skills`, `injects`, `revision`. Capability order is
+`defaults.<slot>` ⊕ `defaults.capabilities` ⊕ `defaults.byTeam[team]` ⊕
+`soul.capabilities` (soul wins; `off` removes; a soul's `<slot>: none` empties
+the slot). `lib/materialize.mjs` then copies every module whole into the home.
+The normative contract is
+[docs/design/2026-09-23-workspace-module-contracts.md](design/2026-09-23-workspace-module-contracts.md).
+
+**Classic 0.24 (superseded; still carried for homes without `oats-local.yaml`).**
 `configChain(context)` loads `oats-config.yaml` from closest scope outward.
 `resolveCapabilities(context, soulName)`:
 
@@ -196,14 +210,28 @@ never reconciled into committed souls.
 
 ## Acquisition and trust
 
-External installation copies/clones one exact artifact and writes
-`oats-lock.json` with source, version/commit, and SHA-256 tree integrity. An
-existing destination is never pulled silently. Resolution rejects changed
-locked artifacts and unlocked installed/path packages.
+**Workspace model (0.25, current).** Nothing is installed. `oats sync`
+(`lib/packages.mjs#resolvePackages`) resolves every `packages:` entry of
+`oats-workspace.yaml` to a commit, computes the package tree's integrity and
+writes `oats-lock.json` **lockfileVersion 3** (`packages.<id>: { source, url,
+path, version, commit, integrity, capabilities[], approved }`). Executable
+approval is **per package version**, recorded in the lock as
+`approved: { executables: sha256-…, at }` after `oats sync` shows the
+executables and the operator says yes; a spawn of a soul using an unapproved
+package is `E_PACKAGE_UNAPPROVED`, and 0.25.1 re-verifies the approved digest
+against the package tree at the locked commit at every spawn. Member-tier
+capabilities need no approval: membership is the trust (decision 2). The
+verbs `oats install|trust|list|restore|use|migrate` are removed
+(`E_UNKNOWN_COMMAND` naming the replacement).
+
+**Classic 0.24 (superseded).** External installation copies/clones one exact
+artifact and writes `oats-lock.json` with source, version/commit, and SHA-256
+tree integrity. An existing destination is never pulled silently. Resolution
+rejects changed locked artifacts and unlocked installed/path packages.
 
 Executable package hooks, commands, and launch-environment authority are omitted
-until `oats trust <id>` marks the exact locked integrity approved. Bundled
-packages are framework-trusted.
+until `oats trust <id>` (0.24) marks the exact locked integrity approved.
+Bundled packages are framework-trusted.
 Packages under a scope's `owned/` subtree are config-owned. Anything under
 `installed/` requires a matching lock entry, so an acquired artifact cannot
 bypass executable trust by its directory location.
@@ -211,7 +239,7 @@ bypass executable trust by its directory location.
 Distribution packages generalize this: a package materializes each capability it
 exports into `.agents/capabilities/installed/<id>/`, each independently
 addressable and independently trusted at its own artifact integrity. There is no
-persistent package store. The `lockfileVersion: 2` lock records package
+persistent package store. The 0.24 `lockfileVersion: 2` lock records package
 provenance (`packages`) and materialized capability identity (`capabilities`)
 separately. See `docs/design/package-engine-contract.md` for the resolver/lock
 API and error taxonomy.

package/docs/integrations.md

@@ -100,9 +100,11 @@ secrets never belong in OATS config. See
 
 > **Removed: `oats.web`.** The browser web-panel capability was retired in
 > favor of the OATS Desktop app (`packages/desktop/`), which bundles the same
-> zero-dependency loopback server. If an `oats-lock.json` or
-> `oats-config.yaml` still names `oats.web`, remove that entry. Full
-> migration steps: [desktop-succession](desktop-succession.md).
+> zero-dependency loopback server. If an `oats-workspace.yaml` (`packages:`,
+> `defaults.capabilities`) or a `soul.yaml` still names `oats.web`, remove that
+> entry and `oats sync`; on a 0.24 classic deployment, remove it from
+> `oats-lock.json` / `oats-config.yaml`. Full migration steps:
+> [desktop-succession](desktop-succession.md).
 
 ## Building an integration
 

package/docs/knowledge-migration.md

@@ -39,17 +39,25 @@ Choose stable base IDs, stable owner IDs, nonoverlapping node paths and durable
 permissions. Confirm aliases and owners explicitly, rather than deriving them
 from an instance branch or name.
 
-Configure the absolute `bindings-file` for each source soul. Remove obsolete v1
-settings such as `record-window-turns` and `record-window-bytes`; v2 accepts only
-`bindings-file`, `harvest-runtime` and `harvest-model`. Provision **empty owned
-nodes** using `oats okf init`. Accept Git initialization through a reviewed PR
-before migration delivery; directory provisioning requires explicit confirmation
-and a genuinely non-Git location.
+Configure the absolute `bindings-file` **and** `state-dir` for each source soul
+— the oats.okf 2.1.x binding requires both as normalized absolute host paths
+(`setting state-dir is required (absolute host path)` is a refusal, not a
+default). Remove obsolete v1 settings such as `record-window-turns` and
+`record-window-bytes`; v2 accepts exactly `bindings-file`, `state-dir`,
+`harvest-runtime` and `harvest-model`. Under the 0.25 workspace model these live
+in `oats-local.yaml` `settings.oats.okf` ([configuration.md](configuration.md));
+a rebuilt deployment gets a **fresh** `state-dir`
+([rebuild-to-v2.md §7b](rebuild-to-v2.md#7b-okf-2-start-a-fresh-state-dir-do-not-re-point-the-old-one)).
+Provision **empty owned nodes** using `oats okf init`. Accept Git initialization
+through a reviewed PR before migration delivery; directory provisioning requires
+explicit confirmation and a genuinely non-Git location.
 
 ## 3. Stage and deliver each legacy bundle
 
-From the durable deployment configuration context in an operator shell without
-inherited instance identity, selecting the source soul:
+From the deployment directory (the one holding `oats-local.yaml`) in an operator
+shell without inherited instance identity, selecting the source soul with
+`--soul` — the kernel resolves the command exactly as `oats spawn --soul <x>`
+would ([knowledge.md](knowledge.md#inspection-and-operator-commands)):
 
 ```bash
 oats okf migrate --legacy /absolute/soul/knowledge --base project --node expert --output /absolute/empty-migration-stage --soul domain-expert --json

package/docs/knowledge.md

@@ -51,11 +51,13 @@ artifact**: npm drops the source worker's `CLAUDE.md -> AGENTS.md` symlink.
 Acquire the catalog Git payload; do not install a copied npm mirror as a local
 package or repair missing aliases in installed artifacts.
 
-With a released OATS >=0.23.0 kernel, acquire published OKF 2.0.0 from the
-intended deployment configuration context in an operator shell without inherited
-instance identity (an explicit `--soul` does not override an invoking instance's
-saved settings). The explicit Git source works before and after the v0.23.1
-framework catalog integration:
+Under the 0.25 workspace model OKF is a **package**: pin it once in the
+workspace file, let `oats sync` lock and approve it, and let every soul that
+fills the knowledge slot say (or inherit) `oats.okf: { from: package }`.
+Operator-level `oats okf` commands run from the deployment directory with
+`--soul <name>` (an explicit `--soul` does not override an invoking instance's
+saved settings — use a clean shell). The pinned version resolves through the
+official catalog:
 
 ```yaml
 # oats-workspace.yaml
@@ -72,6 +74,7 @@ knowledge:
 settings:
   oats.okf:
     bindings-file: /absolute/config/okf-bindings.json
+    state-dir: /absolute/state/okf
 ```
 
 ```bash
@@ -157,7 +160,9 @@ bindings, owner declarations, base metadata or indexes fail required spawn rathe
 than silently bootstrapping empty knowledge.
 
 Provisioning is an explicit operator action. Prepare node-map files (the
-`nodes` object above, without its wrapper), then:
+`nodes` object above, without its wrapper), then run from the **deployment
+directory** (the one holding `oats-local.yaml`), naming the soul whose
+`knowledge:` payload and `settings.oats.okf` the command should run with:
 
 ```bash
 # New directory base: refuses an existing destination.
@@ -166,6 +171,19 @@ oats okf init --base team --nodes /absolute/config/team-nodes.json --confirm --s
 oats okf init --base project --nodes /absolute/config/project-nodes.json --output /absolute/new-bundle-stage --soul domain-expert --json
 ```
 
+These run **before any instance exists**. Outside an instance home the kernel
+resolves `oats okf … --soul <name>` exactly as `oats spawn <name>` would
+(discover → resolve → the soul's `oats.okf` module at its locked, approved
+commit), fetches that module into the deployment's module store
+(`<deployment>/.oats/modules/oats.okf@<commit12>/`) and dispatches to that copy
+with the soul's merged payload as `OATS_SETTINGS`; `--soul` is required
+(`E_BAD_ARGS` names it) unless the namespace's capability is a workspace
+default. It never runs "the newest instance's copy" and never an unapproved
+cache read (`E_PACKAGE_UNAPPROVED` until `oats sync` approves the version).
+*0.25.0 still answers `E_CAPABILITY_INACTIVE` here (the operator-level dispatch
+lands in 0.25.1); the interim is to run the module binary directly with
+`OATS_SETTINGS` and `OATS_CLI_BIN` set, as the tarball smoke does.*
+
 Put the Git proposal at the configured root in an operator-owned checkout and
 review/merge it through a PR before spawning working sources. Existing ownership
 changes require an explicit reviewed operator change, not harvest. The standalone
@@ -189,7 +207,7 @@ Snapshots are immutable by protocol, not live mounts. For current accepted text:
 # From the source home:
 oats okf read --base project --path expert/index.md --json
 oats okf refresh --json
-# From the deployment context, even after source retirement:
+# From the deployment directory (oats-local.yaml), even after source retirement — --soul selects the resolution:
 oats okf read --source /absolute/state/sources/UUID/source.json --base project --path expert/index.md --soul domain-expert --json
 oats okf refresh --source /absolute/state/sources/UUID/source.json --soul domain-expert --json
 ```
@@ -289,9 +307,17 @@ spawn and command exit alone are not successful learning.
 
 ## Inspection and operator commands
 
-Run home-local commands from that source home. For cross-source or retired-source
-commands, use the durable deployment context in a clean operator shell without
-another instance's `OATS_*`/`PI_*` identity; select the configured source soul.
+Run home-local commands from that source home: inside an instance the
+dispatcher resolves `okf` from the home's materialized module
+(`instance.json.modules` → `<home>/.oats/modules/oats.okf/`). For cross-source
+or retired-source commands, run from the **deployment directory** (the one
+holding `oats-local.yaml`) in a clean operator shell without another instance's
+`OATS_*`/`PI_*` identity, and select the source soul with `--soul <name>`: the
+kernel resolves that soul as a spawn would and dispatches to the deployment's
+copy of its `oats.okf` module with the soul's merged payload (see
+[Acquire, bind and provision explicitly](#acquire-bind-and-provision-explicitly)).
+No `oats-config.yaml` chain is consulted; a namespace no module of the soul
+provides is `E_UNKNOWN_COMMAND`.
 
 ```bash
 # Read-only; no capture, refresh, scheduling or worker launch:

package/docs/migration-from-oas.md

@@ -1,5 +1,15 @@
 # Migrating from OAS to OATS
 
+> **0.25 status — this is a 0.22–0.24 procedure.** `oats migrate` and
+> `oats trust` are **removed verbs** in the 0.25 kernel (`E_UNKNOWN_COMMAND`
+> naming the replacement), and 0.25 reads none of the files this page
+> converts to (`oats-config.yaml`, `oats-lock.json` v2, the `installed/` tier).
+> An OAS deployment reaches 0.25 in two steps: run this page's commands with a
+> **0.24.x** kernel (`npm install -g @awebai/oats@0.24`), then rebuild for the
+> workspace model with [rebuild-to-v2.md](rebuild-to-v2.md) — which is a rewrite
+> of three shared files, not a conversion, so an operator comfortable with the
+> v2 declarations may skip straight to it and let the old files go.
+
 OATS is the successor to OAS. **OATS 0.22.0 was published on 2026-09-03**:
 the kernel, Pi adapter, and Desktop assets are available. The published
 kernel acquired the official OKF, aweb, authoring, and development packages
@@ -17,15 +27,15 @@ while its knowledge and messaging configuration remains unmigrated.
 > before activation/spawn. The v2 integration is [prepared](release-notes/v0.23.1.md),
 > not a claim that those dependencies or any deployment have already changed.
 
-## Upgrade one scope
+## Upgrade one scope (0.24.x kernel)
 
 Finish or preserve active work before changing a daily-use deployment.
-Install OATS alongside the old CLI, then inspect the plan for the exact
-scope you intend to convert:
+Install OATS **0.24.x** alongside the old CLI (the 0.25 line has no `oats
+migrate`), then inspect the plan for the exact scope you intend to convert:
 
 ```bash
-npm install -g @awebai/oats@latest
-pi install npm:@awebai/oats-pi@latest
+npm install -g @awebai/oats@0.24
+pi install npm:@awebai/oats-pi@0.24
 oats migrate --from-oas --dry-run --dir /path/to/scope
 ```
 
@@ -39,10 +49,11 @@ oats doctor /path/to/scope
 ```
 
 Run the exact `oats trust <capability> --dir <scope>` commands printed by
-migration for the executable capabilities you approve. Trust does not
-transfer automatically. Verify the team ID and messaging membership with
-`oats aweb setup --dir /path/to/scope`, then exercise a real task, harvest,
-and retirement as described in [Run your first team](first-team.md).
+migration for the executable capabilities you approve (0.24: per-artifact
+trust; under 0.25 approval is per package version through `oats sync`). Trust
+does not transfer automatically. Verify the team ID and messaging membership
+with `oats aweb setup --dir /path/to/scope`, then exercise a real task,
+harvest, and retirement as described in [Run your first team](first-team.md).
 
 For a multi-repository deployment, start with one scope. The explicit
 `--recursive --dir /path/to/workspace` form converts every discovered OAS

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**
@@ -93,6 +106,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 |
@@ -128,6 +164,24 @@ are required. Capabilities the repo exports live at
 `capabilities/<name>/oats.json` — the manifest is unchanged; you may add
 `private: true` / `team:`.
 
+**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. 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.
+
 ## 5. Write `oats-local.yaml` on each machine
 
 ```
@@ -142,12 +196,27 @@ schemaVersion: 2
 workspace: git:github.com/acme/agents
 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]
 ```
 
+`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`.
@@ -179,6 +248,42 @@ 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.
 
+## 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`
 
 In 0.24, an instance-specific messaging identity (a retained seat) was pinned in
@@ -186,14 +291,22 @@ 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.
 
 ## 9. Spawn, and check drift
@@ -212,6 +325,7 @@ oats status                   # per instance: modules … [member moved since (n
 |---|---|
 | `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/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

package/docs/souls-and-instances.md

@@ -176,7 +176,7 @@ instructions and pins model/provider settings; it excludes nothing.
 ```bash
 oats spawn release-manager --purpose cut-3.2 --task "…"            # a soul of a confirmed member
 oats spawn release-manager --preview --json                        # decide everything, create nothing
-oats spawn release-manager --provider oats.aweb identity.source=retained:release-seat   # instance-level payload
+oats spawn release-manager --provider oats.aweb identity.source=/abs/path/to/retained/.aw   # instance-level payload
 ```
 
 From a deployment (where `oats-local.yaml` is), a spawn: reads the local file →
@@ -208,7 +208,7 @@ Examples of spawn hooks:
   registers a durable source plus its per-source schedule definition. Missing
   knowledge is an error, not permission to bootstrap an empty substitute.
 - `oats.aweb` mints a messaging identity — or, with
-  `--provider oats.aweb identity.source=retained:<seat>`, re-takes a retained
+  `--provider oats.aweb identity.source=/abs/path/of/the/.aw/to/retain`, re-takes a retained
   one for exactly this instance.
 
 ### Work

package/docs/workspaces.md

@@ -346,7 +346,7 @@ store** — it organises and can supply defaults. The messaging provider's paylo
 |---|---|---|
 | True of every instance of the soul | `soul.yaml` → `knowledge:` / `messaging:` / `tasks:` | `knowledge: { owns: release-manager }` |
 | A fact about this machine | `oats-local.yaml` → `settings.<cap>.<key>` (absolute paths are refused in the workspace file) | `settings.oats.okf.state-dir: /Users/ana/.oats/okf` |
-| A fact about **this spawn** | `oats spawn … --provider <cap> key=value` (repeatable; dotted keys nest) → `instance.json.providers.<cap>` | `--provider oats.aweb identity.source=retained:release-seat` |
+| A fact about **this spawn** | `oats spawn … --provider <cap> key=value` (repeatable; dotted keys nest) → `instance.json.providers.<cap>` | `--provider oats.aweb identity.source=/abs/path/to/retained/.aw` |
 
 The merged payload is `workspace.messaging` (messaging slot only; its base
 keys ⊕ `byTeam[<soul's team>]`, with `byTeam` itself stripped) ⊕ soul slot
@@ -421,6 +421,13 @@ ref>` — the kernel notices it is a member whose workspace it cannot read and
 falls back to the standalone view — or `standalone: <repo ref>` to ask for
 that view explicitly).
 
+**Executables from public members.** Membership is the trust (decision 2): a
+member capability's hooks and command scripts run on every operator's machine at
+spawn, gated by nothing but the handshake. In a mixed public/private
+organisation keep **souls only** in public members and let executable
+capabilities come from packages (approved per version in the lock) or from
+private members.
+
 **Hosting the workspace file when some members are private.** Everyone who
 can read the workspace file sees the member list. So: a public member never
 hosts it when any member is private (it would publish the private repo's