@awebai/oats 0.25.9 → 0.27.0

package/docs/conventions.md

@@ -6,8 +6,8 @@ instance-local views for deployment composition.
 ## Operating documents
 
 ```text
-soul/AGENTS.md                  # canonical role instructions
-soul/CLAUDE.md -> AGENTS.md
+souls/<name>/AGENTS.md          # canonical role instructions (in the member repo)
+souls/<name>/CLAUDE.md -> AGENTS.md
 instance/AGENTS.md              # generated regular file
 instance/CLAUDE.md -> AGENTS.md
 ```
@@ -48,8 +48,8 @@ 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
+Neither harness gets a redirected config home.
+`composition.materialized.harnessPosture` in `instance.json` records what each
 instance actually exposes. `oats-getting-started` is the sole pre-workspace
 ambient bootstrap.
 
@@ -66,35 +66,25 @@ 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
+<deployment>/oats-lock.json                           # lockfileVersion 3: package commit and integrity
 <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                                  # lockfileVersion 2: external source/integrity/trust
-```
-
 ## Quick map
 
-| 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` |
+| Thing | Canonical location |
+|---|---|
+| Shared declaration | `oats-workspace.yaml` in the host repo; `oats-membership.yaml` in every member |
+| Per-machine config | `<deployment>/oats-local.yaml` (uncommitted) |
+| Acquisition lock | `<deployment>/oats-lock.json` (v3) |
+| Soul source | `<member repo>/souls/<name>/` |
+| Soul operating doc | `souls/<name>/AGENTS.md` |
+| Soul Claude view | `souls/<name>/CLAUDE.md -> AGENTS.md` |
+| Soul-private skills | `souls/<name>/skills/` |
+| Instance operating doc | `instance/AGENTS.md` (generated) |
+| Instance skill set | `instance/.agents/skills/` |
+| Instance modules | `instance/.oats/modules/<capability>/` |
+| Instance metadata | `instance/instance.json` (`modules{}`, `providers{}`, `workspace{}`) |
 
 Symlinks prevent compatibility paths from drifting. Generated regular files
 separate canonical portable identity from scope-dependent runtime policy.

package/docs/design/2026-09-08-expert-assisted-deployment-proposal.md

@@ -32,7 +32,7 @@ how to choose and combine them. A working installation must remain operable
 without the expert running or the original setup conversation being available.
 
 The architecture principle is already in the
-[September 3 proposal](../2026-09-03-architecture-proposal.md):
+September 3 architecture proposal (removed in 0.26.0; it is in the v0.25.x tags):
 
 > Contracts and bootstrap skills in OATS; implementations in packages.
 

package/docs/design/2026-09-13-knowledge-and-memory-direction.md

@@ -85,8 +85,8 @@ code already says**.
 ## 2. Vocabulary
 
 These terms are used precisely throughout. Most are already OATS vocabulary
-(`docs/knowledge.md`, `docs/knowledge-theory.md`,
-`docs/2026-09-03-architecture-proposal.md`); the new ones are marked.
+(`docs/knowledge.md`, `docs/knowledge-theory.md`, the September 3
+architecture proposal); the new ones are marked.
 
 | Term | Meaning |
 |---|---|
@@ -721,7 +721,7 @@ repository is named.
 | 2026-07-26 | Provider-agnostic specialization: compounding expertise across sessions, models, and runtimes; memory outside any one harness. | `decisions/provider-agnostic-specialization-and-curated-context.md`. |
 | 2026-08-27 | Investigation of the public auto-memory audit: governed memory must survive that audit; developer souls must not mirror code; harness-agnostic knowledge enables mixed-runtime teams. | `lessons/governed-memory-survives-auto-memory-audit.md`, `lessons/developer-souls-should-not-mirror-code.md`, `lessons/harness-agnostic-knowledge-enables-mixed-runtime-teams.md`; the video "Turn off Claude Code's Memory" (Theo, t3.gg, YouTube id Jf54k7tFeEc). |
 | 2026-08-27 | Founder correction: developer and UX souls hold decisions, rejected alternatives, inspiration genealogy, and typed slow state; the bias is against descriptions, not decisions. Decision-vs-description; one home per decision; freshness discipline. | Steward note `decision-vs-description-and-knowledge-homing.md` (instance notes, pending harvest); relayed to the OATS coordinator on 2026-09-04. |
-| 2026-09-03/04 | OATS architecture proposal: knowledge is a contract with a read side and a write side; a harvester is a soul type permitted to write knowledge; the write side's doctrine is decision versus description; non-coding specialists are almost pure knowledge; custody scoping belongs to the contract. | `docs/2026-09-03-architecture-proposal.md` (this repository), sections "Soul type", "The slot contracts", "Three simplifications". |
+| 2026-09-03/04 | OATS architecture proposal: knowledge is a contract with a read side and a write side; a harvester is a soul type permitted to write knowledge; the write side's doctrine is decision versus description; non-coding specialists are almost pure knowledge; custody scoping belongs to the contract. | the September 3 architecture proposal (this repository until 0.26.0; in the v0.25.x tags), sections "Soul type", "The slot contracts", "Three simplifications". |
 | 2026-09-05 to 09-08 | Record-fed harvest shipped: `oats.okf` 1.5.0 to 1.6.1 (record windows, watermark, replan detection, exclusions, harvest runtime and model settings, non-zero exit on failure, inspect view and harvest action). | `capabilities/oats-okf/` at 1.6.1 (this repository); `docs/design/operations-contract.md`. |
 | 2026-09-07 | Founder: the OATS team holds the agreed architecture vision; OAS-side review is advisory. | Steward note `oats-vision-delegated-to-juan.md`. |
 | 2026-09-08 | Expert-assisted deployment proposal: shared knowledge collections with explicit promotion destinations; pending-for-owner for ambiguous material; the expert must not become the deployment's database; acceptance is knowledge output, not harvester activity. | `docs/design/2026-09-08-expert-assisted-deployment-proposal.md` (this repository), "Shared knowledge and promotion destinations"; steward note `deployment-as-capability-not-a-layer.md`. |

package/docs/design/2026-09-14-portable-souls-and-git-workspaces.md

@@ -700,8 +700,8 @@ feature work forward.
 ## Current implementation references
 
 These provide baseline context, not proof that this proposal is implemented:
-- [Package engine](package-engine-contract.md)
-- [Package runtime API](package-runtime-api.md)
+- Package engine (`package-engine-contract.md`, removed in 0.26)
+- Package runtime API (`package-runtime-api.md`, removed in 0.26)
 - [Configuration](../configuration.md)
 - [Souls and instances](../souls-and-instances.md)
 - [Multi-team/deployment proposal](2026-09-08-expert-assisted-deployment-proposal.md)

package/docs/design/2026-09-15-portable-souls-handoff.md

@@ -33,8 +33,8 @@ instance review file or original conversation is an acceptance dependency.
 | 4 | [Retention contract](2026-09-14-artifact-retention-contract.md) | Landed and binding: store semantics, captured resolution and consumer migration. |
 | 5 | [Implementation checklist/ledger](2026-09-15-portable-souls-implementation.md) | Clause-by-clause mapping, dependency order, evidence and pending gates. |
 | 6 | [Knowledge direction](2026-09-13-knowledge-and-memory-direction.md) and [current knowledge runtime](../knowledge.md) | Doctrine/context; the older brief's §4.9 automatic skill-delivery account is superseded by OKF v2 (no automatic soul-skill edits). Its older location/type mechanisms are not a second Portable Souls authority. |
-| 7 | [Package engine](package-engine-contract.md) and [runtime API](package-runtime-api.md) | Existing acquisition/trust/runtime invariants; explicit Portable Souls migration changes store/resolution semantics, not silently these contracts. |
-| 8 | [Retention source](../../lib/capability-artifacts.mjs) and [tests](../../test/capability-artifacts.test.mjs) | Storage prerequisite; not complete instance/job dispatch. |
+| 7 | Package engine (`package-engine-contract.md`, removed in 0.26) and runtime API (`package-runtime-api.md`, removed in 0.26) | Existing acquisition/trust/runtime invariants; explicit Portable Souls migration changes store/resolution semantics, not silently these contracts. |
+| 8 | Retention source `lib/capability-artifacts.mjs` and its tests (removed in 0.26 with the captured path) | Storage prerequisite; not complete instance/job dispatch. |
 
 Implementation baseline: `428cd9af615652c4a93d754c1106674abd18545b` on the isolated
 `feat/portable-souls-infrastructure` worktree. There is no instruction to merge,

package/docs/design/2026-09-15-portable-souls-implementation.md

@@ -29,7 +29,7 @@ Binding inputs, all portable repository paths:
   integration requirements are binding despite the historical heading.
 - [Reconciled explainer](2026-09-14-portable-souls-explainer.md); LFX examples are
   hypothetical illustrations, not actual repositories, team setups or credentials.
-- [Package engine](package-engine-contract.md), [runtime API](package-runtime-api.md)
+- Package engine (`package-engine-contract.md`, removed in 0.26), runtime API (`package-runtime-api.md`, removed in 0.26)
   and [current knowledge runtime](../knowledge.md) for preserved contracts.
   The [older knowledge brief](2026-09-13-knowledge-and-memory-direction.md) provides
   doctrine, not a competing source/default schema or permission to auto-edit skills.

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

@@ -119,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.
@@ -131,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

@@ -167,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
@@ -211,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).