@awebai/oats 0.25.0 → 0.25.2

package/docs/conventions.md

@@ -31,43 +31,70 @@ instance/.claude/skills -> ../.agents/skills
 
 Spawn copies kernel + soul-private + active capability skills into real
 instance-local directories there. Directory symlinks are not used because
-harness recursive discovery may not descend through them. Packages retain
-skills in their own artifact; activation selects them for materialization. Config-level `.agents/skills` is not an OATS capability source
+harness recursive discovery may not descend through them. Under the workspace
+model (0.25) every capability is copied whole into
+`instance/.oats/modules/<capability>/` and its skills into
+`instance/.agents/skills/<capability>/<skill>/`; nothing is installed at a
+config level. Config-level `.agents/skills` is not an OATS capability source
 or an ambient runtime discovery root.
 
-Pi starts spawned sessions with ambient skill and context discovery disabled
-and the one instance path explicit; its globally configured extensions remain
-enabled. Claude runs provider-native: it reads the instance's `.claude/skills`
-and `CLAUDE.md` symlinks, and the operator's own user and project
-configuration — skills, plugins, settings — stays in effect. Neither runtime
-gets a redirected config home. `composition.materialized.runtimePosture` in
-`instance.json` records what each instance actually exposes.
-`oats-getting-started` is the sole pre-workspace ambient bootstrap.
-
-Duplicate skill directory names are errors unless config's `skill-overrides`
-selects a source.
+Harnesses start normally (workspace-model decision 13, and the behaviour of
+every launch a 0.25 kernel performs, classic homes included): Pi starts with
+cwd = the instance home, the composed `AGENTS.md` appended to its system
+prompt, and its own skill, context and extension discovery intact — the
+instance's copied skills are found because they sit under cwd; machine-level
+and repo-level skills resolve exactly as without OATS. *(0.24 kernels started
+Pi with ambient skill and context discovery disabled and the one instance path
+explicit; that exclusion is gone.)* Claude runs provider-native: it reads the
+instance's `.claude/skills` and `CLAUDE.md` symlinks, and the operator's own
+user and project configuration — skills, plugins, settings — stays in effect.
+Neither runtime gets a redirected config home.
+`composition.materialized.runtimePosture` in `instance.json` records what each
+instance actually exposes. `oats-getting-started` is the sole pre-workspace
+ambient bootstrap.
+
+Duplicate skill directory names within the OATS-composed set are errors
+(`E_SKILL_DUPLICATE`, naming both capabilities) unless the classic config's
+`skill-overrides` selects a source; between a composed skill and an ambient
+repo/machine skill the harness's own precedence decides (decision 16).
 
 ## Package locations
 
+**Workspace model (0.25, current):** nothing is installed. A capability lives
+where its owner keeps it and is copied whole into each instance at spawn:
+
+```text
+<member repo>/capabilities/<name>/oats.json           # member-tier capability, latest state (membership is the trust)
+<package repo>/oats-package/oats-package.json         # package-tier: versioned via oats-workspace.yaml packages:
+<deployment>/oats-lock.json                           # lockfileVersion 3: package commit, integrity, per-version approval
+<instance>/.oats/modules/<capability>/                # the copy this instance runs
+```
+
+**Classic 0.24 layout** (still launched by the 0.24 kernel; a 0.25 kernel
+reads none of it as configuration — see [rebuild-to-v2.md](rebuild-to-v2.md)):
+
 ```text
 <package>/capabilities/<name>/oats.json                 # the official marketplace (install source, not ambient)
 <level>/.agents/capabilities/installed/<name>/oats.json # acquired (gitignored, restorable)
 <level>/.agents/capabilities/owned/<name>/oats.json     # authored at this scope (source; committed where the scope is a repo)
-<level>/oats-lock.json                                  # external source/integrity/trust
+<level>/oats-lock.json                                  # lockfileVersion 2: external source/integrity/trust
 ```
 
 ## Quick map
 
-| Thing | Canonical location |
-|---|---|
-| Config | `<level>/oats-config.yaml` |
-| Acquisition lock | `<level>/oats-lock.json` |
-| Soul operating doc | `soul/AGENTS.md` |
-| Soul Claude view | `soul/CLAUDE.md -> AGENTS.md` |
-| Soul-private skills | `soul/skills/` |
-| Instance operating doc | `instance/AGENTS.md` (generated) |
-| Instance skill set | `instance/.agents/skills/` |
-| Instance metadata | `instance/instance.json` |
+| Thing | Canonical location (0.25 workspace model) | 0.24 classic |
+|---|---|---|
+| Shared declaration | `oats-workspace.yaml` in the host repo; `oats-membership.yaml` in every member | `oats-config.yaml` chain, `oats.yaml` |
+| Per-machine config | `<deployment>/oats-local.yaml` (uncommitted) | `oats-config.yaml` `settings:` |
+| Acquisition lock | `<deployment>/oats-lock.json` (v3) | `<level>/oats-lock.json` (v2) |
+| Soul source | `<member repo>/souls/<name>/` | `agents/<name>/soul/` |
+| Soul operating doc | `souls/<name>/AGENTS.md` | `soul/AGENTS.md` |
+| Soul Claude view | `souls/<name>/CLAUDE.md -> AGENTS.md` | `soul/CLAUDE.md -> AGENTS.md` |
+| Soul-private skills | `souls/<name>/skills/` | `soul/skills/` |
+| Instance operating doc | `instance/AGENTS.md` (generated) | same |
+| Instance skill set | `instance/.agents/skills/` | same |
+| Instance modules | `instance/.oats/modules/<capability>/` | `.agents/capabilities/installed/` (shared) |
+| Instance metadata | `instance/instance.json` (`modules{}`, `providers{}`, `workspace{}`) | `instance/instance.json` |
 
 Symlinks prevent compatibility paths from drifting. Generated regular files
 separate canonical portable identity from scope-dependent runtime policy.

package/docs/design/2026-09-20-redesign-program-board.md

@@ -2,7 +2,7 @@
 
 **Purpose:** the one accurate view of every work stream in the redesign, what is on main, what is in flight, who owns it, and what blocks it. Lead: `oats-expert` (redesign lead). Updated whenever anything merges, is returned, or reality changes. Older per-lane boards are superseded by this file.
 
-**Last update:** 2026-09-23 17:40Z · **Workspace model v2 phases A–C ON MAIN (`59ae22df`, PR99) → `v0.25.0` tagged (release run in flight)** · Phase D next (framework repos as the first workspace; six expert souls; `oats.core`/`oats.setup` rewrite) · ⏸ parity pipeline still paused except 10B-0 (→ 0.24.14 when the engineer hands off; note: 0.24.14 must be cut from the 0.24 line, not main).
+**Last update:** 2026-09-23 20:00Z · **0.25.0 + 0.25.1 PUBLISHED** (workspace model A–C + team-review fixes) · Phase D plan next · **Desktop engineer paused by the human** (10B-0 uncommitted foundation preserved; resume is the human's call; 0.24.14 to be cut from a maintenance branch off `e5cdaf95` when its PR lands) · parity pipeline ⏸.
 
 Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, not adopted · ⬜ not started · ⛔ blocked
 

package/docs/design/2026-09-20-workspace-and-portable-adoption-plan.md

@@ -4,7 +4,7 @@
 
 **Status:** Phase1 implementation authorised by the human, using the existing developers under lead supervision/review. The workspace home is confirmed as `oats`; `oats-dev` remains development capabilities. This does not claim completed conversion or authorise unspecified new contracts, credential operations or live deployment mutations.
 
-> **2026-09-23 — direction change, read first.** Phases 1–3 delivered as written (workspace on Git, five souls + central knowledge, all contract-bearing Desktop parity slices, releases 0.24.7–0.24.13). Reviewing the result, the human judged the *declaration model* itself too heavy and, in one sitting, accepted a simplified **workspace model v2**: one workspace per org; reciprocal membership as the only gate and as the trust decision; a soul says `from:` (member repo | `here` | `package`) — a location, never a version; packages are the only versioned thing; **nothing is installed** — every capability is copied whole into the instance at spawn; discovery over Git remotes; teams as labels; harnesses start normally. Record: `agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md`; worked example: [2026-09-23-simplified-workspace-model.md](2026-09-23-simplified-workspace-model.md). **Consequences for this plan:** P1.3's `oats.yaml` export indexes and P1.4's `oats-config.yaml` activation are superseded (→ `oats-membership.yaml`, derived activation); D1/D4 stand (`oats.core` becomes `from: package` by default; the catalog stays as discovery); D2's "explicit `oats.core` on every soul" is met by the workspace default; D3 gains the `<name>-workspace/` convention and clone-then-spawn. **No migration** — clean v2, the framework's own repos are the first workspace. A Phase 4 implementation plan is proposed to the human before any `lib/`/`bin/` change; the Desktop parity pipeline is paused meanwhile except for the in-flight 10B-0 security fix.
+> **2026-09-23 — direction change, read first.** Phases 1–3 delivered as written (workspace on Git, five souls + central knowledge, all contract-bearing Desktop parity slices, releases 0.24.7–0.24.13). Reviewing the result, the human judged the *declaration model* itself too heavy and, in one sitting, accepted a simplified **workspace model v2**: one workspace per org; reciprocal membership as the only gate and as the trust decision; a soul says `from:` (member repo | `here` | `package`) — a location, never a version; packages are the only versioned thing; **nothing is installed** — every capability is copied whole into the instance at spawn; discovery over Git remotes; teams as labels; harnesses start normally. Record: `agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md`; worked example: [2026-09-23-simplified-workspace-model.md](2026-09-23-simplified-workspace-model.md). **Consequences for this plan:** P1.3's `oats.yaml` export indexes and P1.4's `oats-config.yaml` activation are superseded (→ `oats-membership.yaml`, derived activation); D1/D4 stand (`oats.core` becomes `from: package` by default; the catalog stays as discovery); D2's "explicit `oats.core` on every soul" is met by the workspace default; D3 gains the `the operator's deployment directory` convention and clone-then-spawn. **No migration** — clean v2, the framework's own repos are the first workspace. A Phase 4 implementation plan is proposed to the human before any `lib/`/`bin/` change; the Desktop parity pipeline is paused meanwhile except for the in-flight 10B-0 security fix.
 
 ## Goal and order
 

package/docs/design/2026-09-23-simplified-workspace-model.md

@@ -1,6 +1,6 @@
 # A simpler multi-repo model for OATS — brainstorm with a worked example
 
-**Status:** **ACCEPTED DIRECTION** — every question closed with the human on 2026-09-23; nothing implemented yet. This document is the worked example; the normative record is the Decision concept `agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md` and the adoption plan. Implementation is a clean v2 (no migration), planned separately. **Decided so far (human, 2026-09-23):** (1) reciprocal membership stays a hard gate; (2) workspace-tier trust = membership, nothing more; (3) everything in a member is discoverable by default — a soul or capability that wants to stay internal says `private: true` in its own definition; (4) the repo's half of the handshake is a one-line **`oats-membership.yaml`** (replaces `oats.yaml`); (5) **no migration path** — a clean break to v2; (6) a soul names each capability **with where it comes from** (`from: <member repo>` or `from: package`) — a location, never a version; resolution is a handshake check + lookup, not a search; (7) **full per-instance materialization** — every capability (skills, injects, scripts, hooks) is copied into the instance at spawn; a running instance never changes under itself; (8) **nothing is "installed"** — a package is just a second kind of source, fetched at the pinned version and copied in like a member's capability; the lock records exact commit/integrity and the one-time executable approval per version; (9) **discovery and resolution work against Git remotes, never local clones** — the only thing that needs a clone is a soul's work target; the local layout is the operator's, with a taught convention (`<name>-workspace/`); (10) the handshake is *observed* with the operator's own read access to both halves — no access to the workspace repo means no membership from that seat, by design; (11) **members carry no revision** — a member is always its latest state; a team that wants frozen capabilities publishes them as a package and pins that; (12) **one workspace per org, teams are labels** — `team:` on a soul/capability (or a repo default in `oats-membership.yaml`) organises and can supply additive defaults, but never gates, restricts or partitions anything; (13) **harnesses start normally and resolve skills from their own default places** — OATS contributes materialized capability skills into the instance's `.agents/skills/` and stops excluding machine-level or repo-level skills. **All questions closed; ready to be written up as a Decision.**
+**Status:** **ACCEPTED DIRECTION** — every question closed with the human on 2026-09-23; nothing implemented yet. This document is the worked example; the normative record is the Decision concept `agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md` and the adoption plan. Implementation is a clean v2 (no migration), planned separately. **Decided so far (human, 2026-09-23):** (1) reciprocal membership stays a hard gate; (2) workspace-tier trust = membership, nothing more; (3) everything in a member is discoverable by default — a soul or capability that wants to stay internal says `private: true` in its own definition; (4) the repo's half of the handshake is a one-line **`oats-membership.yaml`** (replaces `oats.yaml`); (5) **no migration path** — a clean break to v2; (6) a soul names each capability **with where it comes from** (`from: <member repo>` or `from: package`) — a location, never a version; resolution is a handshake check + lookup, not a search; (7) **full per-instance materialization** — every capability (skills, injects, scripts, hooks) is copied into the instance at spawn; a running instance never changes under itself; (8) **nothing is "installed"** — a package is just a second kind of source, fetched at the pinned version and copied in like a member's capability; the lock records exact commit/integrity and the one-time executable approval per version; (9) **discovery and resolution work against Git remotes, never local clones** — the only thing that needs a clone is a soul's work target; the local layout is the operator's — onboarding asks for the directory, no named convention; (10) the handshake is *observed* with the operator's own read access to both halves — no access to the workspace repo means no membership from that seat, by design; (11) **members carry no revision** — a member is always its latest state; a team that wants frozen capabilities publishes them as a package and pins that; (12) **one workspace per org, teams are labels** — `team:` on a soul/capability (or a repo default in `oats-membership.yaml`) organises and can supply additive defaults, but never gates, restricts or partitions anything; (13) **harnesses start normally and resolve skills from their own default places** — OATS contributes materialized capability skills into the instance's `.agents/skills/` and stops excluding machine-level or repo-level skills. **All questions closed; ready to be written up as a Decision.**
 **Date:** 2026-09-23
 **Author:** oats-expert, from a conversation with the human about the weight of the current declaration files.
 
@@ -419,10 +419,10 @@ Northwind adopts it through `external:` with a pinned revision. There is deliber
 
 **The only thing that needs a local clone is a soul's work target** — a soul with `work: worktree | checkout | directory` works *in* a repo, so that repo must be on disk. Spawning a soul whose repo is not yet cloned is therefore a *guided clone into the conventional place, then spawn*: a job for the onboarding skill (`oats-setup-expert`), not the kernel.
 
-The **taught default** — what onboarding sets up and what the docs show — is one folder named after the workspace with the member clones inside it:
+**The deployment directory is the operator's choice** (decision 9): an existing folder that already holds the member clones is the usual case; onboarding asks for it (`oats onboard <dir>`) and adds the three entries the kernel needs. Shown here as Ana's `~/northwind/`, with the member clones inside it:
 
 ```
-~/northwind-workspace/            ← "<name>-workspace"
+~/northwind/                      ← the directory Ana chose (any name, any place)
 ├── oats-local.yaml               ← which workspace this machine realizes + host paths + disabled souls
 ├── oats-lock.json                ← exact commit + integrity + per-version approval per package
 ├── agents/                       ← instance homes, each self-contained
@@ -510,7 +510,7 @@ Today's `capabilities.layers.messaging.{capability, from, global, souls, setting
 |---|---|---|
 | True of every instance of the soul | `soul.yaml` → `messaging:` / `knowledge:` | `messaging: { channels: [northwind-eng] }`, `knowledge: { owns: release-manager }` |
 | A fact about this machine | `oats-local.yaml` → `settings.<capability>.<key>` (absolute paths 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` → `instance.json` `providers.<cap>` (the Desktop's confirmed apply carries the same map) | `--provider oats.aweb identity.source=retained:release-seat` — one instance takes the retained seat; other instances of the soul mint fresh |
+| A fact about **this spawn** | `oats spawn … --provider <cap> key=value` → `instance.json` `providers.<cap>` (the Desktop's confirmed apply carries the same map) | `--provider oats.aweb identity.source=/abs/path/to/retained/.aw` — one instance takes the retained seat; other instances of the soul mint fresh |
 
 The provider's `binding` contract (`normalize → bind → check`) runs over the merged payload exactly as today; the provider still enforces its own rules (e.g. a state root outside the work tree).
 
@@ -565,7 +565,7 @@ OATS is a **skill contributor, not a skill sandbox**. Today the harness is launc
 - **Duplicate names** (team review): two *composed* capability skills with the same name are still a spawn error naming both (`skill-overrides` picks one). A composed skill and an ambient repo/machine skill with the same name is **not** an error — the harness's precedence decides; the preview lists composed names so a clash is visible.
 
 ```
-~/northwind-workspace/agents/release-manager/instances/release-manager-v3/
+~/northwind/agents/release-manager/instances/release-manager-v3/
 ├── AGENTS.md                             ← canonical, composed: soul AGENTS.md + capability injects
 ├── CLAUDE.md → AGENTS.md                 ← relative symlink (unchanged from today)
 ├── .agents/skills/                       ← canonical; where Pi (and Codex) look

package/docs/design/2026-09-23-workspace-module-contracts.md

@@ -307,3 +307,260 @@ Appended, not edited in place; each item names the section it refines. Decision
 **§6 `oats package remove <id>` (M15).** BOTH branches — the file tracked by the checkout (edited) and untracked/absent (not edited) — answer `E_PACKAGE_MISSING { id, path? }` when `<id>` is not declared in `packages:`. The tracked receipt is `{ action: "remove", id, value: null, previous: <old value>, edited: true, file }`; the untracked receipt is `{ action: "remove", id, value: null, edited: false, file: null, line: null, hint }` — `previous` is absent and `line` is `null` (a removal has no line to add).
 
 **§6 features.** `catalog` is no longer advertised in `oats version --json` `features` (the verb is removed; the official catalog is reached through `packages:` + `sync`, not a command).
+
+## Post-0.25.0 clarifications (team review, 2026-09-23)
+
+**Capability commands outside an instance home (`oats <ns> <cmd>` from the
+deployment).** Inside an instance home the dispatcher resolves the namespace from
+the home's materialized modules (`instance.json.modules` → `<home>/.oats/modules`);
+that shipped in 0.25.0. Outside a home — the operator acts a knowledge layer needs
+before any instance exists (`oats okf init`, base migration) — the intended rule
+is: **resolve exactly as a spawn of `--soul <name>` would** (`prepareInstance` →
+the soul's Resolution), fetch the namespace's capability into the deployment's
+module store `<deployment>/.oats/modules/<cap>@<commit>/` (the same per-commit
+store capability-defined agents use), and dispatch to that copy with the soul's
+merged payload as `OATS_SETTINGS`. Never "the newest instance's copy" (an
+instance is not an authority for the deployment) and never an unlocked cache
+read (the lock's approval is the gate, as for spawn). `--soul` is required when
+the namespace's capability is not a workspace default. **Status: 0.25.x
+follow-up** — 0.25.0 still answers `E_CAPABILITY_INACTIVE` there (the pre-v2
+chain); the interim is to run the module binary directly with `OATS_SETTINGS`
+and `OATS_CLI_BIN`, as the tarball smoke does.
+
+**`work: workspace` is kept.** A coordination soul's `./work` is the deployment
+boundary — the directory holding `oats-local.yaml` (whatever the operator
+named it, member clones beside it or named in `clones:`) — read-only across member
+clones, no branch recorded. The clone map in `oats-local.yaml` (`clones:`) is
+how such a soul finds a member whose clone is elsewhere. **Status: the
+directory link is the intent; 0.25.0's kernel still derives the boundary from
+the classic `team:` scope (`docs/souls-and-instances.md` open thread) — 0.25.x
+follow-up binds it to the `oats-local.yaml` directory.**
+
+**`identity.source` (oats.aweb) is the absolute path of the `.aw` directory to
+retain**, given per spawn (`--provider oats.aweb identity.source=/abs/.aw`) or
+per machine (`oats-local.yaml settings.oats.aweb.identity.source`); the kernel
+resolves no symbolic seat names. Absolute paths never enter the workspace file
+(decision 14).
+
+**Member capabilities are a code-execution boundary** (decision 2: membership is
+the trust; hooks and scripts of every member's default branch run on every
+operator's machine at spawn). For a mixed public/private organisation the
+recommendation is: **souls only in public members; executable capabilities come
+from packages (approved per version) or from private members.** The onboarding
+skill (Phase E) states this beside the hosting rule (decision 26).
+
+
+### 0.25.1 fix round (team review, 2026-09-23) — appended, not edited in place
+
+Each item names the section it refines and the review finding it closes. The
+implementation lands in kernel 0.25.1 (`docs/release-notes/v0.25.1.md`); no
+API integer or feature name changes.
+
+**§3 slot `none` (L1).** A soul's `none` for a slot **empties the slot and drops
+any layer-bearing capability the WORKSPACE DEFAULTS contributed for that
+layer** — whether it arrived through `defaults.<slot>`, `defaults.capabilities`
+or `defaults.byTeam[team].capabilities`. A layer-bearing capability **the soul
+itself declares** in its own `capabilities:` alongside `none` for that layer is
+`E_SLOT_CONFLICT { reason: "none" }` (spell `<cap>: off` to remove it). This
+replaces the Phase B reading under which a layered default arriving via
+`defaults.capabilities` was itself a conflict: the workspace's choice is a
+default and `none` is the soul's answer to it; only the soul contradicting
+itself is loud.
+
+**§2/§5 per-commit soul cache (M1).** `ensureWorkspaceSoul` fetches a soul's
+source at `(repoKey, commit)` into `<deployment>/agents/<name>/souls/<commit12>/`
+— **immutable once written** (staged, then renamed in; never removed by the
+kernel) — and maintains `<deployment>/agents/<name>/soul` as a **symlink to the
+current commit's directory**, swapped atomically (symlink to a temp name +
+rename over) so classic readers (`findAgent`, `doctor`, the classic spawn path)
+keep seeing "current". A spawned home's `<home>/soul` links **its own commit's
+directory** (the realpath of `souls/<commit12>/`), never the swapped pointer:
+a running instance's soul never changes under it (decision 7), a `--preview`
+may fetch a new commit and swap the pointer without touching any directory an
+instance links, and OKF 2's owner pin (`owners.json` = `realpath(<home>/soul)`)
+stays valid for the instance that registered it. `.oats-soul-source.json`
+remains the stamp of "current". A 0.25.0 layout (`agents/<name>/soul` a real
+directory, no `souls/`) is migrated in place on first use: the directory moves
+to `souls/<commit from the stamp, else unknown>/` and the pointer replaces it.
+A soul symlink whose target lies inside the same `agents/<name>/souls/` is the
+one kernel-owned symlink soul readers accept.
+
+**§1 transport (M2).** `parseRepoRef(ref).key` is unchanged — `<host>/<path>`
+is the identity everywhere and every comparison is by key. The **fetch url
+honours the form written**: `git@host:org/repo(.git)` and `ssh://…` fetch over
+SSH as written; `https://…` fetches over HTTPS; the bare scheme
+`git:host/org/repo` fetches over HTTPS by default **unless
+`remoteOptions.transport === "ssh"`** (a per-machine choice; `oats-local.yaml`
+may carry it once the schema admits it — reported by lane 3, not landed here).
+The operator's SSH access is therefore used when the operator wrote an SSH ref,
+and a private repo no longer degrades to `not-found` → standalone through an
+unintended HTTPS probe. When the standalone fallback engages the discovery
+carries `standaloneReason`/`hostFailure { code, reason, url }` so the CLI can
+print *why*.
+
+**§3/§4 approval re-verified at spawn (M3).** For a `from: package` module
+`resolveSoul` recomputes `executablesDigest` over the package tree **at the
+locked `entry.commit`** and requires equality with `entry.approved.executables`
+→ else `E_PACKAGE_UNAPPROVED { reason: "digest-mismatch", approved, actual }`.
+The one digest definition is `lib/packages.mjs#executablesDigestAt(remote, ref,
+commit, path, capabilities)`, shared by `sync` and `resolve`; a hand-edited lock
+(same id/version, different commit, copied approval) can no longer materialize
+and run unapproved hooks. Cached per `(id, commit)` within a process.
+
+**§1 peeled commit OIDs (M4).** `observeRemote(ref, { at })` accepts an
+annotated tag's OID (or name) but **records the peeled commit** (`<oid>^{commit}`)
+as `commit` — in its result, in the lock, in `fetchRemoteTree`'s errors and in
+every `instance.json` record. A tag OID is never stored where a commit is
+expected.
+
+**§1 listing hygiene (L3, L4).** `listRemoteTree` filters by depth **before**
+asserting entry-name safety, so one unsafe deep name does not blank a member's
+souls (unsafe names at the kept depth are still `E_REMOTE_TREE_UNSAFE`). A git
+child killed for `maxBuffer` (`ENOBUFS`) is not reported as `timeout`; an
+unclassified listing failure is wrapped as `E_REMOTE_UNREADABLE { reason:
+"unknown" }` so discovery records a problem row instead of aborting.
+
+**§2 `validateWorkspace` absolute paths (L2).** The absolute-path refusal
+applies to **ref/path fields only** — `members[]`, `packages` values, `stores`
+values, `external[].source` / `external[].soul`, `defaults.*.from` — never to
+`teams.<label>.description` or to the opaque `messaging` payload.
+
+**§3 revision (L6).** `Resolution.revision = hash(declRevision, payloadRevision)`
+where `declRevision` covers the declarations (member/package commits, the
+composed capability set, skills, injects) and `payloadRevision` covers the
+payload layers (soul slot payloads ⊕ `oats-local.yaml settings` ⊕
+`--provider`). Both are exposed on the Resolution; decision binding keeps using
+`revision`, so a settings-only difference still refuses a stale apply, while
+`spawn --preview` can say **`changed since: declarations | payload | both`**
+instead of a bare `changedSince`.
+
+**§6 operator-level dispatch (B3, implements the rule stated above).** Outside a
+home, with `oats-local.yaml` present, `oats <ns> <cmd> … --soul <name>` runs
+`prepareInstance(dir, name)`, picks the module whose `manifest.command === <ns>`,
+ensures its tree in `<deployment>/.oats/modules/<cap>@<commit12>/` (member: the
+member repo at `module.from.commit`, `module.dir`; package: the lock entry) and
+dispatches to that copy with `OATS_SETTINGS = resolution.payloads[cap]` and
+`OATS_CLI_BIN`. `--soul` absent → `E_BAD_ARGS` naming it; a namespace no module
+provides → `E_UNKNOWN_COMMAND`. Trust is the resolution's (membership;
+`E_PACKAGE_UNAPPROVED` for an unapproved package).
+
+**§5/§6 `work: workspace` under v2 (B2, implements the rule stated above).**
+With `prepared` present, a `work: workspace` soul's `./work` links the
+deployment directory (`prepared.deployment`, the one holding `oats-local.yaml`);
+no branch is recorded; the "needs a declared boundary" remedy names
+`oats-local.yaml`, not `oats-config.yaml`. The classic root is unchanged.
+
+**Decision 13 reach (L7).** "Harnesses start normally" is a property of the
+0.25 **launcher**: every `pi` launch a 0.25 kernel performs — module homes and
+classic 0.24 homes alike — starts pi with cwd = home, the composed `AGENTS.md`
+appended, and pi's own skill/context discovery intact. Consequently `oats
+session recompose` refuses a **module home** (`instance.json.modules` present)
+with `E_UNSUPPORTED_MODE` ("re-spawn"); the `session-recompose` feature name
+stays advertised because the verb still serves classic homes
+(`docs/desktop-cli-api.md`).
+
+### 0.25.2 operator-rebuild round (2026-09-24) — appended, not edited in place
+
+Source: 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 must honour**: where the guide claimed behaviour the kernel lacked, the
+kernel changes; where the guide described keys no provider consumes, the guide
+changes. Findings R1–R10; kernel side in 0.25.2 (`docs/release-notes/v0.25.2.md`).
+No API integer or feature name changes; the only surface additions are
+additive fields (`spawn --preview` `providers` / `settings`, `oats status
+--json instances[].soul`) and the `sync --approve` flag.
+
+**§2/§5 member clone lookup (R1).** For a `work: worktree | checkout` soul the
+kernel finds the member clone in this order, first hit wins: (1) `oats spawn
+--repo <abs path>`; (2) `oats-local.yaml` `clones: { <repo key>: <abs path> }`,
+keys normalised through `parseRepoRef(...).key` so any spelling of the same
+repo addresses one entry; (3) the convention `<deployment>/<member name>` where
+`<member name>` is the last segment of the repo key — **a member named `agents`
+is looked for at `<deployment>/agents-repo`** (`<deployment>/agents/` is the
+instance root); (4) none → `E_CLONE_MISSING { repoKey, tried: [...], remedies }`
+naming the three remedies. A directory found by (2) or (3) whose `origin` remote
+resolves to a different repo key → `E_CLONE_MISMATCH { repoKey, path, origin }`
+— the kernel never spawns into a clone that is not the member. This order was
+stated by the guide and `docs/workspaces.md` before 0.25.2 and not implemented;
+it is now normative.
+
+**§6 `oats sync` creates `agents/` (R2).** `sync` (and therefore `onboard`,
+which runs the sync body) creates `<deployment>/agents/` when absent. A
+hand-written `oats-local.yaml` needs no `mkdir`.
+
+**§5 one "You run on OATS" block (R3).** When `oats.core` resolves as a module
+the composer suppresses the kernel's legacy `oats:kernel:oats` block; the
+module's inject is the one such block. Without `oats.core` (a soul saying `off`)
+the legacy block is composed as before, so no instance is left without the
+briefing.
+
+**§5/§6 soul-source drift (R4).** `driftOf` covers `instance.json.workspace.soul`
+as well as `modules`: `oats status` prints `soul: <name> from <member> @ <c7>`
+with `[member moved since …]` when the member's default branch is past the
+recorded commit (`[member unconfirmed]` / `[soul no longer present]` for the
+missing cases); `--json` adds `instances[].soul = { repoKey, commit, current:
+<commit>|null, status: "current"|"moved"|"missing" }`. A moved soul is
+information (decision 17): the instance keeps its own commit directory (M1).
+
+**§6 preview payload visibility (R5).** `oats spawn --preview` (text and
+`--json`) reports `providers` — the `--provider <cap> k=v` map exactly as given,
+nested — and `settings.<cap>` — `resolution.payloads[cap]`, the merged payload
+the provider's binding receives (`workspace.messaging` base ⊕ `byTeam[team]` ⊕
+soul slot payload ⊕ `local.settings[cap]` ⊕ `providers[cap]`). Additive fields;
+both empty objects when nothing applies.
+
+**§5/§6 `work: workspace` (R6, closed in 0.25.1 as B2).** Documented in the
+guide's §9: a coordination soul's `./work` is the deployment directory.
+
+**Provider payload delivery vs provider consumption (R7 — oats.aweb 1.11.2).**
+Decision 23 (`messaging.byTeam`) is **kernel semantics**: the kernel merges and
+delivers; the provider consumes what its binding declares. oats.aweb 1.11.2's
+spawn hook (a) locates the aweb root among `OATS_TEAM_SCOPE`, the home, the
+home's git root, `OATS_CONTEXT` and its git root, and `OATS_WORKSPACE` (under
+v2: the deployment directory) — none of which is a 0.24 team root; and (b)
+resolves the target team from `OATS_TEAM_ID`/`OATS_TEAM_NAME` (the removed
+`oats-config.yaml` `team:` block; empty under v2), else the **active team at
+the root it found** — it does **not** read `team` from `OATS_SETTINGS`. So for
+1.11.2 `byTeam` is delivered and recorded but a no-op; per-label minting is
+obtained only by placing a per-team `.aw` inside each team's member clone
+(gitignored) so it is found through the work repo, or one `.aw` at the
+deployment directory for a single team. The guide states this (§8b) and
+`docs/workspaces.md` states the general rule ("kernel-merged; whether a
+provider honours it is the provider's"). **oats.aweb follow-up**: read `team`
+(and honour `byTeam`'s result) from the payload; accept the deployment
+directory as a first-class root. The kernel does not paper over this with a
+`team:` env shim — the env block is removed with `oats-config.yaml`, and a
+provider contract is the provider's to grow.
+
+**OKF 2.1.3 reads `okf.json`, not a soul payload (R8 — corrects §2's `stores`
+comment and decision 24's `root` example).** `oats.okf` 2.1.3's spawn hook
+reads the soul's knowledge declaration from `<soul>/okf.json` (`{ version: 1,
+owner, owns: ["<base>/<node>"], reads: [...] }`, `lib/config.mjs#validateDeclaration`)
+and its settings from `OATS_SETTINGS`, admitting **only** `bindings-file`,
+`state-dir`, `harvest-runtime`, `harvest-model` (`oats.json#settings`) — any
+other key is `E_CONFIG unknown OATS_SETTINGS property`. Where a base lives
+inside a store repository is the **bindings file's** `bases.<alias>.repository`
++ `root`, not a soul payload key. Therefore: a soul.yaml `knowledge:` payload for
+OKF carries binding settings only (usually nothing — the workspace default
+fills the slot; `none` opts out); `owns`/`reads`/`store`/`root` examples on
+`soul.yaml` are removed from the guide, `workspaces.md`, `souls-and-instances.md`
+and `knowledge.md`; `okf.json` stays in `souls/<name>/` and travels with the
+soul into the per-commit cache (M1). A soul-payload grammar for OKF is an OKF
+follow-up that lands with an `oats.okf` release declaring it in its binding.
+The kernel's part — opaque forwarding of the merged payload — is unchanged and
+correct. §7b's fresh `state-dir` rule is confirmed by the operator's run.
+
+**§6 non-interactive approval (R9).** `oats sync --approve <id>@<version>`
+(repeatable) approves exactly the entry the current resolution contains for
+that id and version: the executables digest is always computed by `sync` over
+the fetched tree (`executablesDigestAt`) and recorded — never typed. An
+`--approve` naming an id/version the resolution does not contain → `E_BAD_ARGS`
+(nothing approved); entries not covered stay unapproved (exit `2`). At the
+interactive prompt **Ctrl+D (EOF) is a decline**: exit `2`, entry unapproved —
+never treated as "yes", never a hang.
+
+**§6 onboard next steps (R10).** `oats onboard` lists the workspace **host**
+in `next.clone` like any member that lacks a clone at the convention (the host
+is a member; a soul that lives in it may need a work clone). Under an explicit
+`oats-local.yaml` `standalone:` header the next steps say the view is standalone
+and list only that repo.

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

@@ -15,7 +15,7 @@ A clean v2 of the kernel's declaration, resolution and launch path: read `oats-w
 
 ## Work packages
 
-Each is one PR (or two small ones), reviewed by me, on `main`, behind the v2 seam until W7. Order is dependency order; W1–W3 can proceed in parallel lanes.
+Each is one PR (or two small ones), reviewed by me, on `main`, as canonical code from the first phase (no seam — see the approach above). Order is dependency order; W1–W3 can proceed in parallel lanes. **Status (2026-09-23): W1–W8 and W10 shipped in OATS 0.25.0 (PR99 `59ae22df`); W8's last part — folding the classic no-`oats-local.yaml` spawn path into the one pipeline and deleting the v1 residue — is a follow-up; W9/W9b/W11/W12 are Phases D–F.**
 
 | # | Package | Delivers | Owner | Size |
 |---|---|---|---|---|
@@ -28,9 +28,9 @@ Each is one PR (or two small ones), reviewed by me, on `main`, behind the v2 sea
 | **W7** | **CLI switch-over** | `oats sync`, `oats spawn` (preview/apply unchanged in shape, now fed by W4/W6), `oats capabilities` / `oats souls` with origin + team, `oats workspace status`; `oats status` shows `modules … @ commit` + `member moved since`; `oats version --json` advertises `workspaceApi: 2` + feature `workspace-v2`; **remove the v1 readers** (`oats.yaml`, per-soul `source:`, `oats-config.yaml` activation) — a v1 file at a v2 path errors naming the schema | lead | M |
 | **W8** | **Delete v1** | Remove `portable-*`, `source-spec`, `capability-provenance` (v1 parts), `prepared-resources`, migration stores/evidence, the installed tier in `packages.mjs`, classic config activation, their tests and docs; `core.mjs` loses everything that only served v1 | lead | L (mostly deletion) |
 | **W9** | **Framework repos as the first workspace (decisions 18–21)** | `oats-workspace.yaml` v2 in `oats` (drop the six imports; `packages:` pins oats.framework/okf/aweb/jira/linear/authoring/dev **as packages**; `teams:` global/engineering; `defaults`); `oats-membership.yaml` in ALL seven repos; the six soul editions rewritten (`oats.okf: {from: package}` etc. even though the repos are members); **a new expert soul in every package repo** — `okf-expert`, `aweb-expert`, `jira-expert`, `linear-expert`, `authoring-expert`, `dev-expert` (v2 `souls/<name>/`, team global, knows and evolves that capability); `package-catalog.json` kept as the official marketplace (bare-version `packages:` entries resolve through it) | lead (member-repo PRs to their owners; the expert souls' AGENTS.md drafted by me, reviewed by the package owner) | L |
-| **W9b** | **`oats.core` and `oats.setup` rewritten for the new architecture (human, 2026-09-23)** | The two official capabilities' skills and injects are rewritten to teach the *new* model, not patched: **`oats.core`** (`oats-operate`, `oats-souls`, the "you run on OATS" inject) — how an agent works inside an instance under this architecture: its home layout (`.oats/modules/`, `.agents/skills/`, `instance.json` modules/providers), the verbs it will actually use (`status`, `spawn --preview/--provider`, `retire`, `session`, `instance events`, `capabilities`, `souls`, `workspace status`), what a workspace/member/package/team is *from the agent's seat*, drift ("member moved since"), how to find and read other souls. **`oats.setup`** (`oats-config`/`oats-packages` → renamed to what they now are: `oats-workspace`, `oats-packages`, `oats-onboarding`) — the whole architecture and its best practices: workspace ↔ repo handshake and why, `oats-workspace.yaml` / `oats-membership.yaml` / `soul.yaml` v2 / `oats-local.yaml` field by field, teams as labels, member-tier vs package-tier and the non-collapse rule, `packages:` + lock v3 + per-version approval, the official catalog vs `git:` refs, `sync`/`package add`, the `<name>-workspace/` convention and clone-then-spawn, private items, external souls, the standalone case, provider payload homes (soul/machine/spawn), what is deliberately NOT versioned and why. Every skill is validated against the shipped CLI (`oats <verb> --help` snapshot test) so they cannot drift from the commands. | lead (swarm + review) | M |
-| **W10** | **Docs** | **`docs/rebuild-to-v2.md` — the rebuild guide (ships with the schemas; states that 0.24.x keeps spawning 0.24.x deployments)**; `docs/workspaces.md` rewritten around v2; `souls-and-instances.md`, `packages.md`, `configuration.md` (mostly deleted), `first-team.md` → the `<name>-workspace/` convention; DTO doc § Workspace v2; release notes | lead | M |
-| **W11** | **Onboarding skill** | `oats-setup-expert` / `oats.setup`: teach `<name>-workspace/`, `oats sync`, clone-then-spawn; **the hosting rule for mixed public/private organisations (decision 26): ask up front whether any member is private; if so the workspace file is hosted in a private repo that is NOT a public member (a dedicated private `workspace` repo is the honest shape), public contributors get the standalone case with `oats.core` by default (decision 25); `oats onboard` prints the same rule in its next-steps**; the `oats-operate` skill updated for the new verbs | lead | S |
+| **W9b** | **`oats.core` and `oats.setup` rewritten for the new architecture (human, 2026-09-23)** | The two official capabilities' skills and injects are rewritten to teach the *new* model, not patched: **`oats.core`** (`oats-operate`, `oats-souls`, the "you run on OATS" inject) — how an agent works inside an instance under this architecture: its home layout (`.oats/modules/`, `.agents/skills/`, `instance.json` modules/providers), the verbs it will actually use (`status`, `spawn --preview/--provider`, `retire`, `session`, `instance events`, `capabilities`, `souls`, `workspace status`), what a workspace/member/package/team is *from the agent's seat*, drift ("member moved since"), how to find and read other souls. **`oats.setup`** (`oats-config`/`oats-packages` → renamed to what they now are: `oats-workspace`, `oats-packages`, `oats-onboarding`) — the whole architecture and its best practices: workspace ↔ repo handshake and why, `oats-workspace.yaml` / `oats-membership.yaml` / `soul.yaml` v2 / `oats-local.yaml` field by field, teams as labels, member-tier vs package-tier and the non-collapse rule, `packages:` + lock v3 + per-version approval, the official catalog vs `git:` refs, `sync`/`package add`, the deployment directory (the operator's; no naming convention) and clone-then-spawn, private items, external souls, the standalone case, provider payload homes (soul/machine/spawn), what is deliberately NOT versioned and why. Every skill is validated against the shipped CLI (`oats <verb> --help` snapshot test) so they cannot drift from the commands. | lead (swarm + review) | M |
+| **W10** | **Docs** | **`docs/rebuild-to-v2.md` — the rebuild guide (ships with the schemas; states that 0.24.x keeps spawning 0.24.x deployments)**; `docs/workspaces.md` rewritten around v2; `souls-and-instances.md`, `packages.md`, `configuration.md` (mostly deleted), `first-team.md` → the operator's deployment directory; DTO doc § Workspace v2; release notes | lead | M |
+| **W11** | **Onboarding skill** | `oats-setup-expert` / `oats.setup`: ASK for the deployment directory (an existing folder with the operator's clones is the usual case — no named convention, decision 9), `oats sync`, clone-then-spawn; **the hosting rule for mixed public/private organisations (decision 26): ask up front whether any member is private; if so the workspace file is hosted in a private repo that is NOT a public member (a dedicated private `workspace` repo is the honest shape), public contributors get the standalone case with `oats.core` by default (decision 25); `oats onboard` prints the same rule in its next-steps**; the `oats-operate` skill updated for the new verbs | lead | S |
 | **W12** | **Desktop follow-through** | New kernel DTOs (from W7) consumed the usual way — engineer reads the merged head, files pins, wires: Capabilities/Souls origin + team columns; "installed" removed as a state; spawn preview shows modules (from/commit/hash) + team; Workspaces surface shows membership status | Desktop engineer, after W7 | M |
 
 **Team review (Antares, 2026-09-23) folded in:** rebuild guide (W10), **second review (two aweb teams, stores, soul layout, standalone, public/private hosting → decisions 23–26: `messaging.byTeam`, stores = repo + provider `root`, `souls/` only, `oats.core` standalone default, private host rule taught by onboarding),** `--provider` instance payload (W6/W7), drift display (W7), duplicate-name rule (W6), 0.24.x-keeps-working stated everywhere.
@@ -52,7 +52,7 @@ Each phase = one developer-swarm workflow (parallel agents, disjoint files, agai
 | Risk | Mitigation |
 |---|---|
 | Remote access context is subtle (SSH vs HTTPS vs `gh` token; private repos) | W2 uses git itself (`git ls-remote`, `git archive`/shallow fetch) with the operator's configured credential helpers — no new credential store; typed `cannot read` never guesses |
-| `core.mjs` entanglement makes W8 risky | W8 is deletion behind a green W7; the seam guarantees nothing live depends on what is deleted; CI + the Northwind fixture + Desktop suites are the gate |
+| `core.mjs` entanglement makes W8 risky | W8 is deletion behind a green W7; `rg` proof of zero importers per module before each deletion (the v1-residue table from the Phase C review); CI + the Northwind fixture + Desktop suites are the gate |
 | Package approval UX ("asks once") in non-interactive spawns | `oats sync` is where approval is asked; `spawn` refuses `E_PACKAGE_UNAPPROVED` pointing at `sync` — never prompts mid-spawn |
 | Latest-state members drift between preview and apply | The resolution records the member commit; apply re-observes and refuses `E_DECISION_STALE` if it moved — same mechanism as today's decision revision |
 | Desktop relying on "installed" | Removed as a state in W12; until then the Capabilities view keeps working on 0.24.x DTOs (contracts unchanged) |

package/docs/desktop-cli-api.md

@@ -450,6 +450,26 @@ the pre-fix marker and is never accepted for dispatch.
 
 ## Readiness quartet, signatures, enforced policy (`oats readiness`, `readinessApi: 1`, OATS 0.24.8+)
 
+> **0.25 status — the producers below are the 0.24 tier.** The readiness DTO
+> (`readinessApi: 1`) still ships unchanged, but its four checks are *produced*
+> by the classic observers: `installed` by `oats list` over the
+> `.agents/capabilities/installed/` tier, `trusted` by the per-artifact approval
+> that `oats trust` wrote, `configured` by `oats-config.yaml` activation, and
+> `enrolled` by the `oats.yaml` backlink. On a **workspace deployment**
+> (`oats-local.yaml` present) none of those sources exists: nothing is installed,
+> approval is per package version in `oats-lock.json` v3 (`oats sync`), activation
+> is derived (workspace defaults ⊕ soul `capabilities:`), and membership is
+> `oats-membership.yaml` observed over the remotes. `oats list` and `oats trust`
+> are removed verbs (`E_UNKNOWN_COMMAND`), so a `remedy` naming them cannot be
+> run. Treat the field names and producer strings as the stable wire shape they
+> are; for the workspace-model facts read `oats spawn <soul> --preview --json`
+> (`modules[]` with from/commit/digest — the "installed" and "configured"
+> truth), `oats sync --json` `approvalNeeded[]` (the "trusted" truth) and
+> `oats workspace status --json` (the "enrolled" truth). Re-basing the quartet on
+> those producers is an open thread of [the workspace model](#workspace-model-workspaceapi-2);
+> when it lands it will be announced as a new feature name, not a silent change of
+> `readinessApi: 1`.
+
 `oats readiness [--soul <name>] [--home <abs>] [--verify-signatures] [--policy] [--dir <d>] --json`
 is the first-run readiness view (frame 09) and the Capabilities readiness rows
 (frame 04). Every fact is derived from the **same** data `oats inspect` reports
@@ -728,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
@@ -1026,6 +1046,18 @@ refreshes the home in place:
   schedule; the receipt's `note` says so. Refuses a retiring home
   (`E_INSTANCE_RETIRING`), captured incarnations and capability-defined souls
   (`E_UNSUPPORTED_MODE`: those are refreshed by a new resolution / package).
+- **Module homes (0.25+) are `E_UNSUPPORTED_MODE` too.** A home whose
+  `instance.json` carries `modules{}` (spawned on a workspace deployment,
+  `instance-modules`) answers `E_UNSUPPORTED_MODE` ("recompose from
+  materialized modules is not supported yet; re-spawn"): its `AGENTS.md` was
+  composed from the soul at a recorded member commit plus the materialized
+  modules' injects, and the instance never changes under itself (decision 7).
+  The refresh path for such a home is a new spawn (the soul is re-fetched at
+  the member's current commit). `session-recompose` **stays advertised** in
+  `features[]` because the verb still works for classic homes; gate the UI
+  action on the feature AND on the absence of `instance.json.modules`
+  (`oats status --json` `instances[].modules` is non-empty for a module home),
+  and render the typed refusal otherwise.
 - Gate on `features.includes("session-recompose")`. It is an **operator
   action** (the human or the instance's parent), never something a Desktop
   poll or an agent runs on itself.

package/docs/desktop-succession.md

@@ -12,10 +12,17 @@ the OATS Desktop app (`packages/desktop/` in the framework repo):
 
 ## Migrating a deployment that used `oats.web`
 
+Under the **0.25 workspace model** there is nothing to uninstall: remove
+`oats.web` from `oats-workspace.yaml` `packages:` / `defaults.capabilities`
+and from any `soul.yaml` `capabilities:`, run `oats sync` (the lock v3 entry
+disappears with the declaration), and use the Desktop app (step 3 below).
+
+For a **0.24 classic** deployment:
+
 1. Remove the `oats.web` entry from `capabilities.additive` in every
    `oats-config.yaml` in your config chain.
-2. Remove the `oats.web` entry from `oats-lock.json` at the same scope(s), and
-   delete any stale installed copy under `.agents/capabilities/installed/`.
+2. Remove the `oats.web` entry from `oats-lock.json` (v2) at the same scope(s),
+   and delete any stale installed copy under `.agents/capabilities/installed/`.
 3. Use the OATS Desktop app instead: `cd packages/desktop && npm install &&
    npm run rebuild && npm start` (see `packages/desktop/README.md`).
 

package/docs/desktop.md

@@ -84,10 +84,15 @@ The probe/mutation contract is specified in
 
 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 workspace —
-a directory containing `agents/`, or `local-agents/` for machine-local
-souls, or a team scope whose `oats-config.yaml` declares `team:`. Team scopes
-show every member repo's agents under one roster with a workspace switcher.
+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
+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
+roster") still keys on the 0.24 `oats-config.yaml` `team:` declaration; reading
+the member set from `oats-local.yaml` / `oats workspace status` is the Phase F
+follow-up named in the [0.25.0 notes](release-notes/v0.25.0.md#desktop).*
 Added workspaces are remembered and offered as suggestions next time.
 
 Local souls (uncommitted, machine-local agents under `local-agents/`) are

package/docs/execution-targets.md

@@ -231,10 +231,22 @@ and needs equivalent registration glue when switched to session delivery.
 
 ## Shared permission setting
 
-Set `yolo: true` in an `oats-config.yaml` to apply it to that scope. The closest
-scope wins; an optional `yolo` in soul.yaml overrides it; `oats spawn --yolo` or
-`--no-yolo` overrides both. `oats create` accepts those flags too. Desktop offers
-the same per-launch choice. With no setting, native policy is retained.
+The opt-in is per launch or per soul: `oats spawn --yolo` / `--no-yolo`
+(`oats create` accepts the same flags), an optional `yolo` in `soul.yaml`
+(0.24 schema; the v2 `soul.yaml` schema does not carry it — use the spawn flag
+or a launch configuration), and the Desktop's per-launch choice. With no
+setting, native policy is retained.
+
+*0.24 classic deployments* may also set `yolo: true` in an `oats-config.yaml`
+to apply it to that scope; the closest scope wins, soul overrides scope, the
+spawn flag overrides both. *Under the workspace model* `oats-config.yaml` is
+not configuration ([configuration.md](configuration.md)); the kernel's
+`composeInstance` still consults the classic chain for the machine-level knobs
+`yolo` and `launch-configs` when such a file happens to sit above the
+deployment, but nothing writes one and the rebuild guide tells you to delete
+it — treat a scope-level `yolo` as a 0.24 feature and prefer the explicit
+spawn flag.
+
 Autonomous or unattended execution is not permission to synthesize `yolo: true`.
 Explicit user CLI/UI input or a user-selected configuration is the opt-in; explicit
 `false` remains false.