@awebai/oats 0.25.8 → 0.26.0

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

@@ -25,7 +25,7 @@ Legend: ✅ on main/published · 🔄 in flight (PR/branch) · 🟡 preserved, n
 - Open: strict-Pi "enriched profile" remains unqualified (documented, not hidden).
 
 ## S2 — Workspace adoption of the OATS repos
-- ✅ **PR23 merged f6d5a89b**: `oats-workspace.yaml` (7 members, `imports: []`), `oats.yaml` (exports souls/oats-expert, oats-package, capabilities/oats-authoring), transitional `souls/oats-expert/` edition, `docs/workspace-adoption.md`, layout tests.
+- ✅ **PR23 merged f6d5a89b**: `oats-workspace.yaml` (7 members, `imports: []`), `oats.yaml` (exports souls/oats-expert, oats-package, capabilities/oats-authoring), transitional `souls/oats-expert/` edition, the workspace adoption guide (removed in 0.26.0), layout tests.
 - ✅ **PR24 merged da38e5a9**: deletion of `skills/oats-portable-setup` + `oats inspect --request` read-only seam (ACCEPTED as the public inspection route); full gate 1621/0.
 - ✅ Member `oats.yaml` merged to main: oats-okf #3 (fec78a20), oats-aweb #1 (069ea2f6), oats-authoring #1 (54183a6a), oats-jira #1 (2f855daf).
 - ✅ oats-dev#1 (main 6e164ee3) and oats-linear#1 (main a2121e48) merged after Juan granted write access — M's exact commits 0434f4ef / 8c183c37.
@@ -117,7 +117,7 @@ Fresh directory and deployment, `@awebai/oats@0.24.4`, policy sources v2.1.2 / v
 
 ## S5 — Official marketplace
 - ✅ Mechanism exists (`package-catalog.json`, `officialPackageCatalog()`); decision names it the official list.
-- ✅ **D4 merged PR26 (786490ae)**: `docs/official-marketplace.md`, `package-catalog.json` policy pointer (inert to the reader), README/packages/capabilities links, D3 sketch in adoption guide. ⬜ entries for `oats.core`/`oats.setup` at D1 release. Desktop view → S8.
+- ✅ **D4 merged PR26 (786490ae)**: the official list policy (now `docs/official-catalog.md`), `package-catalog.json` policy pointer (inert to the reader), README/packages/capabilities links, D3 sketch in adoption guide. ⬜ entries for `oats.core`/`oats.setup` at D1 release. Desktop view → S8.
 
 ## S6 — Five expert souls in the oats repo
 - ✅ **PR30 merged (40a579dc)** + maintainer follow-up **caa341f3**: all five declare `oats.core: {source: repo:oats-package}`, oats.okf@v2.1.1; `oats.yaml` exports all five; `oats-workspace.yaml` imports all five at caa341f3 (375b9f42). Live inspection against published main resolves them.

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

@@ -462,7 +462,7 @@ stays advertised because the verb still serves classic homes
 ### 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
+following the 0.25 rebuild guide literally (removed in 0.26.0). **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`).

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

@@ -29,7 +29,7 @@ Each is one PR (or two small ones), reviewed by me, on `main`, as canonical code
 | **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 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 |
+| **W10** | **Docs** | **the rebuild guide (removed in 0.26.0; 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 |
 

package/docs/design/2026-09-24-desktop-phase-f-boundary.md

@@ -87,15 +87,26 @@ the purpose field becomes a name field that shows `<soul>-<purpose>` live and
 then the kernel's final name from the preview. A no-prefix toggle maps to
 `spawn --name <slug>`, gated on the `spawn-name` feature; `--purpose` stays the
 default. **Runtime and model** are always visible, with their resolved value and
-its source. **Work** comes from the soul's `work:` mode, and a `checkout` soul is
-offered "Use a worktree instead?" (`--work worktree`). There is **no**
-modules/capabilities list and no attach-knowledge / child-spawn / open-PR
-toggles, because those behaviours come from capabilities. There is **no**
-preview button either. The preview runs in the background to fill the real
-defaults, and apply still binds with `--expect-decision` (`E_DECISION_STALE`
-re-previews). A collapsed **Advanced** section holds harness permissions, launch
-config, relation, messaging identity (`--provider <cap> identity.mode=…`,
-decision 27), branch/base overrides and the execution server. Every modal gets a darker backdrop.
+its source. **Relationship** sits in the main form, shown by default: None /
+Child of / Sibling of / Parent of. There is **no** modules/capabilities list and
+no attach-knowledge / child-spawn / open-PR toggles, because those behaviours
+come from capabilities. There is **no** preview button either. The preview runs
+in the background to fill the real defaults, and apply still binds with
+`--expect-decision` (`E_DECISION_STALE` re-previews). A collapsed section named
+**Developer settings** holds:
+- **work**: base | branch and the worktree path. A `checkout` soul is offered
+  "Use a worktree instead?" (`--work worktree`); the work mode itself comes
+  from the soul's `work:`.
+- harness permissions
+- launch config
+- session backend
+- Run on (the execution server)
+- wake-up
+- messaging identity (`--provider <cap> identity.mode=…`, decision 27)
+
+(Second human redirect, same day: relationship moved into the main form, work
+moved into the collapsed section, and the section was renamed from "Advanced".)
+Every modal gets a darker backdrop.
 
 **F4 — Instance card and roster on v2 facts.** The served-identity line (`acts
 as <address> via grant, expires <t>` / `alias <a> on <team>`); module rows with
@@ -108,6 +119,38 @@ action (`oats retire`) and `--force` behind a confirm.
 **F5 — Redesign frames** (the original Phase 3 deliverable, excl. 05/06),
 implemented on top of F1–F4 rather than on the 0.24 model.
 
+**F7 — Side panels redesigned, teams everywhere (human, 2026-09-25). This
+supersedes the frames and the text above wherever they differ.** One Desktop PR:
+- **Side panels** in the spawn modal's design language (frame 01a):
+  - an identity header and compact cards;
+  - only useful facts (no "Not reported" rows), and empty sections hidden;
+  - relative dates, and shortened paths with Copy;
+  - errors as one plain sentence, with the code behind Details;
+  - discoverable cross-links between an instance and its soul.
+- **Terminal-side context panel tabs, in order:** Instance · Soul · Git & GitHub.
+- **Teams, per surface** (teams contract `docs/design/2026-09-25-teams-contract.md`):
+  - **Soul** (Workspace inspector): the soul's labels, primary marked, each
+    joinable or "not mapped by this workspace". Read-only, from
+    `inspect --soul` `teams`.
+  - **Instance** (Workspace inspector and the terminal-side Instance tab): the
+    live panel (#178). Personal is always on; joined teams have Leave, and
+    joinable ones have Join.
+  - **Spawn modal, main form** (not Developer settings), a Teams row:
+    - "Personal team — always", fixed;
+    - each joinable label as an unchecked checkbox, sent as
+      `--provider <messaging> join=<a,b>`;
+    - unmapped labels greyed with the reason;
+    - the line "By default it's only in your personal team. Tick the teams it
+      should also join."
+
+    The row is shown iff the preview carries `teams` AND the messaging
+    module's preview row lists `join` in `declares` (feature
+    `settings-declared`; the Desktop gates on declared facts, never on
+    versions).
+  - **Second human redirect (QA, same day):** unmapped labels are not shown
+    anywhere (no greyed rows, no "not mapped" text), and Teams in the spawn
+    modal is one row styled like Relationship.
+
 **F6 — Version and doctor surface.** `oats version --json` and `oats doctor
 --json` in an About/Health pane; `ACCEPT_RANGE` and the three pins move to
 `>=0.25.6`; a kernel below the floor is refused with the upgrade command shown.
@@ -120,7 +163,8 @@ spawns children (its call; the lead reviews each PR).
 Read, in this order, in the checked-out main:
 1. `docs/workspaces.md` — the v2 model end to end (deployment vs workspace,
    members, packages, payloads, `byTeam`, hosting).
-2. `docs/rebuild-to-v2.md` — how an operator builds a deployment (this is the
+2. the 0.25 rebuild guide (removed in 0.26.0; `docs/configuration.md` and
+   `oats onboard` now) — how an operator builds a deployment (this is the
    flow F2 wraps).
 3. `docs/desktop-cli-api.md` — every JSON surface, with examples; note
    `features[]`, `decision.effective.providers`, `instances[].identity`.

package/docs/design/2026-09-24-phase-d-plan.md

@@ -42,6 +42,26 @@ pushes. Agreed by both on 2026-09-24:
 - `main` on these repositories carries no branch or tag protection: the parity
   gate and the cross-review are the only things between a merge and `main`.
 
+## Human decision (2026-09-24): no package approval
+
+**Package approval is removed from the kernel and from the Desktop.** People
+install a package only when they trust it. Declaring it in the workspace's
+`packages:` IS the trust decision, so there's no second, per-version approval
+step. This supersedes the "executables approved once per version" rule in
+`docs/workspaces.md` (§ Packages, lock, approval, catalog) and everything built
+on it:
+- `oats sync` exit 2 for pending approvals and `approvalNeeded`
+- `--approve <id>@<version>` and the interactive prompt
+- the lock's `approved` record
+- `E_PACKAGE_UNAPPROVED` at spawn and dispatch
+- the Desktop F2 approval flow (`E_APPROVAL_STALE`)
+- the planned pinned `--approve …=<digest>`
+
+What stays: the lock still pins each package to the exact commit and integrity,
+and restore still refuses drift (`E_PACKAGE_INTEGRITY`). Reproducibility is not
+approval. It's a breaking contract change, so it ships in a minor release, and
+the Desktop requires that kernel.
+
 ## Slices, in order
 
 ### D1 — Knowledge centralisation (IN PROGRESS)
@@ -147,6 +167,51 @@ Kernel (lead): pass the soul's team label and the workspace identity so the
 provider derives the personal team deterministically; an unmapped team means
 "personal". The onboarding skill's manual invite-then-join step is the 1.12.0
 path and is rewritten when the provider ships R1/R2.
+**Teams, re-stated as THE priority (human, 2026-09-25; amends R1/R2):**
+"As long as we don't have this working seamlessly, people won't understand
+things." The two most important messaging behaviours, above every other
+messaging item:
+- **(R1) A personal team by default.** A user's agents in a workspace get
+  that person's personal team for the workspace with no setup step. This is
+  the default whenever the workspace maps nothing else.
+- **Defaults and joining (human, later the same day; refines R1/R2′):**
+  - By default an instance is in the person's personal team ONLY, even when
+    its soul names teams.
+  - Joining a wider team is explicit: a spawn choice, or at any point of the
+    instance's life one simple command, run by the human, another agent, or
+    the instance when told to. It covers only the soul's labels the workspace
+    maps.
+  - The Desktop offers these controls.
+  - Personal teams are per WORKSPACE: one personal team spanning several
+    workspaces is wrong, and aweb's per-workspace get-or-create (abjj) is
+    urgent. Nobody uses OATS in production yet, which is what keeps this a
+    fix and not a migration.
+  - Contract: `docs/design/2026-09-25-teams-contract.md`.
+- **(R2′) Wider teams, at spawn AND during an instance's life.** When a soul
+  belongs to one or more wider teams, its instance is also included in each
+  team the soul specifies, both at spawn and at any later point of its life,
+  not only at spawn. The teams are exactly those the workspace defines
+  (`messaging.byTeam` / the workspace's team labels); no team outside the
+  workspace's definition, and none silently missing. R2′ supersedes R2's
+  "is spawned … joins": joining is a lifetime operation, and a soul may name
+  several teams.
+Both are oats.aweb's (Antares) with aweb primitives. **The kernel's share is
+the lead's:**
+- today `soul.team` is ONE label (docs/soul.schema.json), and the messaging
+  payload merges `byTeam[soul.team]` for that one label. "Team/teams" needs a
+  soul to name several team labels, and the payload to carry each mapped
+  team's entry (not one merged view), so the provider can join all of them;
+- the workspace identity and the person's identity reach the provider, so
+  the personal team derives deterministically;
+- a lifecycle entry point for "join now" during an instance's life (for
+  example, a provider operation or hook run against a live home when the
+  workspace's teams or the soul's team labels change at a new commit).
+The contract shape is decided with Antares and recorded as a Decision before
+code. **Human, same day:** the primitives must be seamlessly integrated into
+the aweb messaging capability (acceptance is the oats.aweb experience: no
+manual `aw team …` anywhere we ship, and live instances follow the
+workspace's teams), and kernel changes are in scope, so the provider is not
+bent around today's kernel.
 **Naming (lead, 2026-09-24):** the `oats-` prefix on all six —
 it matches the repository names and the roster's `oats-kernel-`/`oats-desktop-`/
 `oats-operator-expert`, and it keeps instance aliases from colliding with the
@@ -191,6 +256,18 @@ the harvester delivers to that node as a PR the owning expert reviews.
 - **Legacy souls** (`agents/*` and their knowledge bundles) are NOT part of D4:
   they go when the live instances linking them retire (human rule).
 
+**Human direction 2026-09-25: runtime → harness** ("throughout the app and cli and everywhere"). It ships in 0.26.0 as one kernel PR after (e):
+- every kernel-owned name is renamed with no alias (`--harness`, `launch-configs.<n>.harness`, `instance.json.harness`, JSON fields, feature `harness`);
+- two released-contract aliases stay: the provider env sets both `OATS_HARNESS` and `OATS_RUNTIME`, and manifests may say `requires[].runtime` or `requires[].harness`;
+- the Desktop switches on the `harness` feature.
+
+**Human direction 2026-09-25 (~17:20Z), amending the above: release 0.26.0 WITHOUT the harness rename; harness ships as a separate, later release.**
+- 0.26.0 ships main as it stands once the in-flight PRs land: (e), K, the teamsOf check, `layers.<layer>.from`, and Desktop F7. It keeps the `runtime` names everywhere.
+- The harness rename (the kernel PR, with the alias addendum: env `OATS_RUNTIME`, stdin `launch.runtime`, manifest `agents[].runtime`/`requires[].runtime`, `spawn --runtime`) ships in the **next minor, 0.27.0**. It is a breaking CLI/JSON change (`--runtime` refused on session/launch-config, `version.runtimes` dropped, launch-configs field renamed), so it isn't a patch. It ships together with the Desktop's switch on feature `harness`, and the Desktop's accepted kernel range widens to include 0.27.
+- Neither the kernel harness PR nor the Desktop switch merges to main before the v0.26.0 tag.
+
+Also: "core capabilities" is the human vocabulary for the knowledge/messaging/tasks capabilities in prose; wire names are unchanged.
+
 ### D5 — Catalog update and 0.26.0
 
 Catalog pins for the new package versions; **widen Desktop `ACCEPT_RANGE` and

package/docs/design/2026-09-25-teams-contract.md

@@ -0,0 +1,226 @@
+# Teams contract: several team labels per soul, per-team messaging, live reconciliation
+
+Status: AGREED 2026-09-25 by both co-leads (provider verbs confirmed in e205c93a). First drafted by the lead (kernel lane), with the messaging
+co-lead's provider plan. It serves the human priority of 2026-09-25, recorded
+in `2026-09-24-phase-d-plan.md` under "Teams, re-stated as THE priority".
+This document is the kernel half; the provider half (oats.aweb) is the
+messaging lane's. Co-lead review (9a18a381): agreed, with three additions,
+folded in below.
+
+## The model (human, 2026-09-25)
+
+- **Default: the personal team only.** Every instance is in its person's
+  personal team for THIS workspace. A soul's `team` labels do NOT put it
+  in those teams by default.
+- **Joining is explicit.** A wider team is joined by an explicit action:
+  - at spawn, a spawn choice;
+  - or at any point of the instance's life, one simple command, run by the
+    human, by another agent, or by the instance itself when told to.
+- **Only what the soul and workspace allow.** The teams an instance MAY join
+  are exactly its soul's labels that the workspace maps. Nothing else is
+  offered or accepted.
+- **Leaving** is the same kind of command. When the workspace removes a
+  mapping or the soul drops a label, the joined membership for it is left.
+- **The Desktop has controls for it:** at spawn (which eligible teams to
+  join) and on a live instance (join/leave, and the joined vs eligible
+  teams).
+- **Personal teams are per WORKSPACE.** One personal team spanning several
+  workspaces is wrong. Until aweb ships the per-workspace get-or-create, the
+  person's single default team is an explicitly temporary stand-in.
+
+## Problem
+
+- A v2 soul names ONE team label (`soul.yaml` `team`, else the repository's
+  default from `oats-membership.yaml`).
+- The resolver merges `workspace.messaging ⊕ byTeam[<that label>]` into one
+  messaging payload, and applies `defaults.byTeam[<that label>].capabilities`
+  to the soul's composition.
+- An instance can therefore be placed in one team only, and only at spawn.
+- The human's bar: a person's agents are in their personal team by default,
+  AND in every wider team their soul belongs to, at spawn and during the
+  instance's life, and those teams are exactly the ones the workspace defines.
+
+## Decision
+
+1. **Several labels.**
+   - `soul.yaml` `team` accepts a label or a non-empty list of distinct
+     labels: `team: dev` or `team: [dev, reviewers]`.
+   - `oats-membership.yaml`'s repository default takes the same shape.
+   - The FIRST label is the **primary**. A single string is a one-element
+     list, so existing souls don't change.
+2. **Composition (`defaults.byTeam[*].capabilities`).**
+   - Applied for every label, in soul order, after `defaults.capabilities`
+     and before the soul's own `capabilities`. The soul's own entries still
+     win.
+   - Two labels that give the same capability different entries is
+     `E_TEAM_CONFLICT`, naming both labels. There's no silent
+     last-writer-wins. Identical entries from two labels are not a
+     conflict.
+3. **Messaging payload.**
+   - **Amended (K, co-lead ruling on the 1.14.0 review):** the messaging
+     provider's merged settings are `base ⊕ soul ⊕ host ⊕ spawn`, and **no
+     `byTeam[<label>]` is merged into them**, the primary's included. Each
+     label's `base ⊕ byTeam[label]` lives only in its `teams` entry (below).
+     So `settings.team` / `OATS_TEAM_ID` mean "the personal team, if the
+     host, soul or spawn set one"; empty means the provider's own default
+     (for oats.aweb, the root's active team). Reason: the instance is
+     personal-by-default (the human's model), and the primary label is just
+     the first eligible team. Merging its payload made the provider mint the
+     primary identity into the mapped team, and it couldn't tell a host-set
+     personal team from the workspace's mapped one.
+   - New and kernel-owned: `teams`, an ordered list of
+     `{ label, mapped: boolean, payload }`.
+     - `payload` is `base ⊕ byTeam[label]` when the workspace maps the label.
+     - It's `base` alone, with `mapped: false`, when the label isn't mapped.
+   - Each entry also carries the resolved team id as `team` (null when the
+     label isn't mapped), so a provider never digs it out of `payload`.
+     "Personal" is the provider's to resolve; the kernel says nothing about
+     it.
+   - These are the **eligible** teams. Joining them is explicit (see "The
+     model"), not automatic.
+   - It's delivered beside the settings, in the environment (`OATS_TEAMS` JSON),
+     never inside the provider's own settings object, so it can't collide
+     with a provider key or its manifest's settings validation.
+   - `teams` is present when the soul has a label; a soul with no label gets
+     `[]`, meaning "personal only".
+4. **Environment.**
+   - `OATS_TEAM_LABEL` / `OATS_TEAM_ID` stay the primary's.
+   - New: `OATS_TEAM_LABELS` (all labels, comma-joined, in order) and
+     `OATS_TEAMS` (the JSON above).
+   - New: `OATS_TEAMS_SOURCE`, which is `live` or `recorded` (decision 6). It's empty
+     when `OATS_TEAMS` is empty (unknown).
+   - **The environment is the only channel.** No stdin wire gains keys: the
+     binding check's request stays exactly the released wire, because released
+     providers (oats.aweb 1.13.1) key it strictly and refuse unknown keys with
+     `invalid-binding`. A provider check reads the teams from the same env
+     variables its hooks get. (Correction after #179, co-lead finding.)
+   - Workspace identity is unchanged: `OATS_WORKSPACE_KEY` / `OATS_WORKSPACE_NAME`.
+   - The person's identity stays the provider's (its messaging root from host
+     settings); the kernel passes the deployment, as today.
+5. **Discovery.**
+   - A label the workspace doesn't map is a discovery **warning**
+     (`unmapped-team-label`), not an error, so the provider can fall back to
+     the personal team and say so.
+   - There's one warning per unmapped label, naming its souls
+     (`{ code, label, souls, paths, message }`), not one per soul and label.
+     A workspace with no `messaging.byTeam` must not print a line per soul.
+   - A label that isn't in the workspace's `teams:` list at all stays the
+     error it is today.
+6. **Live resolution for a home.**
+   - A home's teams are **live messaging state, not frozen composition**. The
+     modules and skills an instance got at spawn don't change under it; which
+     teams it belongs to follows the workspace.
+   - For home-context provider operations and the launch hook, the kernel
+     computes `teams` from the soul's labels at the soul commit the
+     deployment currently resolves (the lock), and the workspace's current
+     `messaging`.
+   - That lets the provider offer a team the workspace added as eligible,
+     and leave one it removed, without a respawn.
+   - The recorded spawn-time `teams` stays in `instance.json.teams` as
+     evidence: beside `providers`, never inside that capability-keyed map.
+   - **Live or recorded.** When the workspace can't be read now (the host is
+     offline, or the soul is no longer listed), the kernel falls back to the
+     recorded set and says so: `OATS_TEAMS_SOURCE=recorded`, or
+     `teamsSource: "recorded"` in inspect.
+     - **A provider leaves a joined team only on a `live` answer.** On
+       `recorded` or unknown it keeps every membership and may warn
+       (`teams-unverified`).
+     - Reason: a team mapped after spawn and joined live is absent from the
+       record, and an offline host must never cost an instance a membership.
+   - **Cost.** Live teams are computed only where they're consumed:
+     - session start/restart;
+     - the messaging module's own home-context commands and operations;
+     - `inspect` / `readiness --home`.
+
+     The live read covers the workspace host and the soul's repo, not a full
+     workspace discovery. Every other in-home capability command uses the
+     record and costs what it did before.
+   - **0.26.0 limitation:** a scheduled wake's start uses the spawn-time teams.
+     The scheduler is synchronous; only operator starts are live.
+   - **Retire** works from the provider's own recorded membership list,
+     never from the live eligible set. A mapping removed after the spawn
+     still has its membership revoked at retire.
+7. **Explicit join, spawn choice, Desktop.**
+   - The join/leave/list verbs are the provider's (oats.aweb 1.14.0), run
+     inside a home or with `--home <abs>`, all idempotent, all with `--json`:
+     - `oats aweb teams` answers
+       `{ personal: {team}, primary, eligible: [{label, team, joined}], joined: [{label, team, since, identityHome, receive}], unmapped: [label], at }`, where `receive` is `native` or `poll`;
+     - `oats aweb join <label>[,<label>]` and
+       `oats aweb leave <label>[,<label>]` answer the same document. The
+       personal team can't be left (`E_TEAM_PERSONAL`).
+     - The same verbs are declared as home-context operations
+       `messaging:teams|join|leave`, so the Desktop uses `oats operation run`
+       and needs no new kernel surface.
+       All three are `kind: action` (the default): a `view` must answer
+       `{documents:[…]}` (markdown/text for reading), and the teams document
+       is structured JSON. `messaging:teams` is read-only by its own
+       contract, which its description says. Join and leave declare one
+       required arg, `labels` (flag `--labels`, comma-separated).
+     - Identity model: one local identity per joined team, under the home as
+       `.aweb-identity-<label>`. The personal-team identity is the primary one,
+       wired to the harness. There are no global identities by default.
+     - **Sending and receiving as a joined team (oats.aweb 1.14.0):**
+       - Sending is complete: `aw --identity-home <identityHome> mail|chat …`,
+         the one form the aweb inject teaches.
+       - Receiving is by POLL: the channel plugin, the pi extension and a wake
+         registration each listen on one identity home. The inject says to
+         check a joined team's inbox at task boundaries, and readiness and
+         `receive: poll` say so.
+       - Native receive for joined teams needs one of two aweb primitives:
+         wake/channel on several identity homes per instance home, or global
+         instance identities with address release (one identity, many teams,
+         one channel). This is a named gap against the "seamless" bar,
+         tracked as an aweb ask.
+   - Each is idempotent, and refuses a label the instance isn't eligible for
+     (`E_TEAM_NOT_ELIGIBLE`, naming the eligible labels).
+   - **Declared setting keys (added after #179):** the spawn preview's
+     `modules[]` rows and `inspect`'s `capabilities[]` rows carry
+     `declares: [<setting key>…]` (names only; feature `settings-declared`).
+     That's how a Desktop sees that the messaging manifest declares
+     `settings.join` without reading manifests.
+   - `inspect --soul` on a soul whose labels conflict (`E_TEAM_CONFLICT`)
+     refuses. The error details name the capability and both labels; no
+     `teams` is answered, because the soul can't be spawned until the
+     workspace resolves it.
+   - At spawn, the kernel carries the operator's choice to the provider as a
+     spawn provider setting (`--provider <messaging> join=<label>[,<label>]`).
+     That needs no new kernel flag, and the spawn preview shows it.
+   - The launch hook re-checks joined memberships against the live eligible
+     set: it leaves what's no longer eligible (only when
+     `OATS_TEAMS_SOURCE=live`, decision 6) and never joins on its own.
+   - **The kernel puts `teams` (eligible, the OATS_TEAMS entries) in the
+     spawn preview and in `inspect --home`**, so a Desktop can offer the
+     choice before anything is minted. The Desktop reads that, plus joined memberships from the provider's inspect or
+     operation, and drives the same verbs.
+   - Later kernel item: `oats sync` reports the souls whose labels or
+     mappings changed since the previous lock.
+
+## Compatibility
+
+- A single-label soul sees byte-identical **composition** (modules, skills,
+  injects). Its messaging **payload** changes: the mapped label's `byTeam`
+  entry is no longer merged into the provider's settings; it's only in
+  `OATS_TEAMS` (amendment K). With 0.26.0 + oats.aweb 1.13.1, the primary
+  identity therefore mints into the personal (root-active) team, as the
+  human's model wants.
+- oats.aweb 1.13.1 ignores `OATS_TEAMS` and keeps working, because no stdin
+  wire changes (its binding decoder refuses unknown request keys).
+- oats.aweb 1.14.0 reads them.
+- The schema change goes into 0.26.0, the release that already breaks the
+  file formats.
+
+## Tests
+
+- Several labels compose in order; a conflict → `E_TEAM_CONFLICT`. A
+  capability the soul names itself is exempt, since the soul's entry wins over
+  every label.
+- A mapped primary's `byTeam` payload is absent from the provider's merged
+  settings and present in `OATS_TEAMS[0].payload` (amendment K).
+- `OATS_TEAMS` shape: mapped and unmapped labels, and no label → `[]`.
+- Home-context `teams` follows a new workspace commit (a mapping added and
+  removed) while the home's modules stay frozen.
+- Discovery warns once per unmapped label.
+- A home whose workspace can't be read gets the record with
+  `OATS_TEAMS_SOURCE=recorded`; a non-messaging in-home command runs no live
+  team read.
+- `teams` entries carry `team`; identical cross-label entries don't conflict.

package/docs/design/README.md

@@ -7,12 +7,12 @@ Dated design documents record how decisions were reached and what each implement
 - **[Workspace module contracts (2026-09-23)](2026-09-23-workspace-module-contracts.md) — NORMATIVE for implementation**: `lib/remote.mjs`, `lib/workspace.mjs`, `lib/resolve.mjs`, `lib/packages.mjs` (lock v3), `lib/materialize.mjs`, the CLI verbs and DTOs, the error codes, the Northwind fixture.
 - [Simplified workspace model — worked example (2026-09-23)](2026-09-23-simplified-workspace-model.md) — ACCEPTED: one workspace per org, membership = trust, `from:` as location, nothing installed, full per-instance copy, teams as labels, harnesses start normally. The Decision concept is `agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md`.
 - [Implementation plan (2026-09-23)](2026-09-23-workspace-v2-implementation-plan.md) — phases A/B/C, what each deletes.
-- Operator-facing: [rebuild guide](../rebuild-to-v2.md) (0.24.x → v2; no converter), [Desktop CLI API — workspace model](../desktop-cli-api.md#workspace-model-workspaceapi-2).
+- Operator-facing: [workspace model](../workspaces.md), [Desktop CLI API — workspace model](../desktop-cli-api.md#workspace-model-workspaceapi-2).
 - Open threads (tracked here until closed): the `workspace` work mode still derives its `./work` boundary from the classic `team:` scope; the readiness `enrolled` producer still reads the 0.24 `oats.yaml` backlink; launch configurations / yolo / work-mode setup are still read from a classic config chain.
 
 ## Superseded by the workspace model
 
-Everything below this line that describes per-soul `source:` provenance, `oats.yaml` exports/imports, the installed-capability tier (`.agents/capabilities/installed/`), `oats-config.yaml` scopes, `oats init`/`use`/`install`/`restore`/`trust`/`migrate`, lock v1/v2 or ambient-skill exclusion at launch is **history**. In particular [package-engine-contract.md](package-engine-contract.md) and [package-runtime-api.md](package-runtime-api.md) describe the removed acquisition/materialization engine; the package tier is now [packages.md](../packages.md) + module contract §4. Capability **manifests**, hooks, the operations contract, provider binding wire/codecs and the knowledge/messaging capability contracts are unchanged.
+Everything below this line that describes per-soul `source:` provenance, `oats.yaml` exports/imports, the installed-capability tier (`.agents/capabilities/installed/`), `oats-config.yaml` scopes, `oats init`/`use`/`install`/`restore`/`trust`/`migrate`, lock v1/v2 or ambient-skill exclusion at launch is **history**. In particular `package-engine-contract.md` and `package-runtime-api.md` (both deleted in 0.26) described the removed acquisition/materialization engine; the package tier is now [packages.md](../packages.md) + module contract §4. Capability **manifests**, hooks, the operations contract, provider binding wire/codecs and the knowledge/messaging capability contracts are unchanged.
 
 ## Earlier plan (0.24)
 
@@ -38,7 +38,7 @@ Everything below this line that describes per-soul `source:` provenance, `oats.y
 
 ## Capabilities and providers
 
-- [Package engine contract](package-engine-contract.md) · [package-runtime API](package-runtime-api.md) — **superseded** (installed tier removed; see [packages](../packages.md)) · [operations contract](operations-contract.md) · [launch configurations](launch-configurations.md).
+- Package engine contract (`package-engine-contract.md`, removed in 0.26) · package-runtime API (`package-runtime-api.md`, removed in 0.26) — **superseded** (installed tier removed; see [packages](../packages.md)) · [operations contract](operations-contract.md) · [launch configurations](launch-configurations.md).
 - [Provider binding wire v1](2026-09-16-provider-binding-wire.md) · [provider binding codecs](2026-09-16-provider-binding-codecs.md) · [capability helper/input contract](2026-09-17-capability-helper-input-contract.md).
 - [Knowledge capability contract](2026-09-16-knowledge-capability-contract.md) · [messaging capability contract](2026-09-16-messaging-capability-contract.md).
 

package/docs/design/launch-configurations.md

@@ -1,12 +1,16 @@
 # Launch configurations and launch recipes
 
-A **launch configuration** is a named way to start a harness, declared per
-scope under `launch-configs:` in `oats-config.yaml` (see
-docs/configuration.md): runtime, an executable, literal arguments,
-environment (literals or `{fromEnv}` references), model, yolo. It is
-independent of any soul; a soul may name one as its default
-(`launch-config:` in soul.yaml, `oats soul set --launch-config`), and a
-spawn, start or restart selects one by name.
+A **launch configuration** is a named way to start a harness, declared by
+the host under `launch-configs:` in the deployment's `oats-local.yaml` (see
+docs/configuration.md; 0.26.0, lead decision 2 — earlier kernels read it
+from a scope's `oats-config.yaml`): runtime, an executable, literal
+arguments, environment (literals or `{fromEnv}` references), model, yolo.
+It is independent of any soul, and a spawn, start or restart selects one by
+name (`--launch-config`, or the Desktop's per-launch choice). A launch
+configuration is a spawn-time host choice, never a soul field: `launch-config:`
+is not a field of a workspace-model soul.yaml (docs/soul.schema.json; discovery
+refuses it), so a v2 soul cannot name one, not even as a default. (A classic
+0.25 soul.yaml could name a preferred entry; 0.26.0 reads no such field.)
 
 A **launch recipe** is what a start is made of, recorded in the instance's
 `instance.json` under `launch` beside the rendered `command`:
@@ -15,9 +19,9 @@ A **launch recipe** is what a start is made of, recorded in the instance's
 {
   "version": 1,
   "runtime": "claude",
-  "launchConfig": "personal", "launchConfigSource": "/scope",
-  "executable": "/scope/tools/claude-wrapper.sh",
-  "executableDeclared": "./tools/claude-wrapper.sh", "executableResolvedFrom": "relative to /scope",
+  "launchConfig": "personal", "launchConfigSource": "/deployment",
+  "executable": "/deployment/tools/claude-wrapper.sh",
+  "executableDeclared": "./tools/claude-wrapper.sh", "executableResolvedFrom": "relative to /deployment",
   "args": ["--settings", "/abs/settings.json"],
   "env": { "KEY": { "fromEnv": "SRC" }, "LIT": "plain" },
   "model": "claude-opus-5", "yolo": true,
@@ -55,16 +59,16 @@ shows them: `list` and `preview` redact every environment value.
   that disagrees with the configuration's runtime is refused
   (`E_LAUNCH_CONFIG_MISMATCH`) before anything happens; the same runtime may
   be repeated; `--model` and `--yolo` override the configuration's fields.
-- Without `--launch-config`: a spawn takes the soul's `launch-config` default
-  or none; an existing home keeps its recorded configuration, except that
+- Without `--launch-config`: a spawn uses no configuration (the runtime's
+  defaults; a soul names none); an existing home keeps its recorded configuration, except that
   `--runtime` alone deliberately leaves it behind and renders the new
   runtime's defaults (no old executable or args are carried).
 - Model: explicit, else the configuration's, else on an existing home the
   recorded model when the runtime is unchanged, else the runtime's native
-  default; a spawn without either resolves the soul's preference for the
-  runtime. A model never crosses runtimes.
+  default; a spawn without either uses the runtime's native default (a
+  workspace-model soul declares no model). A model never crosses runtimes.
 - Executable: the configuration's (bare name on PATH; a path resolved against
-  the declaring scope when relative) or the runtime's default (claude through
+  the deployment directory when relative) or the runtime's default (claude through
   `oats-claude-config`). It must be a regular executable file; it is never
   run to probe it. Capability runtime-package requirements are checked with
   the runtime's default binary, as at spawn.
@@ -87,7 +91,7 @@ re-run by a start or restart.
 Read-only; nothing is locked or started. `--home ABS` describes an existing
 home under a selection (`selection.source`: `frozen` when nothing was
 selected, `config` when re-resolved, `frozen-command` for a home that
-predates recipes, whose selection needs the restart conversion);
+predates recipes, where a selection answers `E_LAUNCH_LEGACY`: re-spawn it);
 `--soul NAME [--dir SCOPE] [--agents-root ABS]` describes a new instance.
 Answer: `{context, selected, selection:{source, launchConfig, runtime,
 model, yolo}, runtime, model, modelSource, yolo, launchConfig,

package/docs/design/operations-contract.md

@@ -97,15 +97,16 @@ are listed. `use none --layer l` is a level statement and takes no soul or
 type. A layer bound to another capability at a level is never overwritten
 (`E_LAYER_BOUND` with the exact remedy).
 
+*(0.24/0.25 only — `oats soul set` was removed in 0.26.0: a soul is edited in its member repository, then `oats sync`. Kept for history.)*
 `oats soul set <name> [--dir] [--agents-root] [--runtime] [--model |
 --no-model] [--yolo | --no-yolo] [--backend] [--description |
---no-description] [--instructions-file <path>] --json` edits only the given
-`soul.yaml` lines and replaces `AGENTS.md`; packaged souls are refused
-(`E_SOUL_READONLY`). The receipt carries before/after and sha256s.
+--no-description] [--instructions-file <path>] --json` edited only the given
+`soul.yaml` lines and replaced `AGENTS.md`; packaged souls were refused
+(`E_SOUL_READONLY`). The receipt carried before/after and sha256s.
 
 ## Remote
 
-`inspect`, `operation`, `use` and `soul` route with `--server <id>` through
+`inspect` and `operation` route with `--server <id>` through
 the saved route. The gate is the destination's `features` list containing
 `operations` and its `operationsApi: 1` (`E_REMOTE_INCOMPATIBLE` before
 anything is sent): `features` describes what a kernel can do locally, which
@@ -113,12 +114,28 @@ is what runs on the host. The probe's `remote` list describes what a CLI
 can ROUTE to a server and is what a GUI checks on the local CLI before
 offering remote actions; it is not a gate on the destination. An explicit `--dir` is the exact member context and
 travels as is; `--home` is its own context; otherwise the registered
-workspace is the scope. Soul instructions travel as bytes on the ssh stdin
-(`--instructions-stdin` on the host), never as a local path.
+workspace is the scope.
 
 ## Replaceability
 
-`test/inspect.test.mjs`, `test/operation.test.mjs` and
-`test/operations-routing.test.mjs` use an owned alternative knowledge
-provider (namespace `notes`, one `MEMORY.md`, operations `harvest` and
-`inspect`) and never mention the official provider.
+`test/operation.test.mjs` runs the real CLI on the Northwind fixture and
+replaces the provider in a spawned home's module copy (what `operation run
+--home` executes) with a recording provider of its own: the runner is generic
+and assumes nothing about the official provider's operations.
+
+## Workspace model (0.26.0)
+
+On a workspace deployment, and for a home whose `instance.json` records
+`modules`, `oats inspect`, `oats readiness` and `oats operation run` read the
+workspace model's own records instead of the config chain:
+- the subject is `--home` (instance.json plus its module copies) or `--soul`
+  (the soul resolved as its spawn would be), never a scope;
+- `operationsApi` is 2 (also on the run result), and each soul row carries
+  `soulsApi: 2`;
+- there is no trust gate (`E_CAPABILITY_BLOCKED` is gone);
+- no `scope`, `chain`, `activation`, `snapshot` or `currentConfig` block.
+
+The payloads are specified in
+[desktop-cli-api.md](../desktop-cli-api.md#inspect-readiness-and-operation-run-on-the-workspace-model-operationsapi-2-soulsapi-2-readinessapi-2-oats-0260).
+The sections above describe the classic path, which is removed with the classic
+config chain.