@awebai/oats 0.29.4 → 0.30.1

package/docs/design/2026-09-27-team-model-v2.md

@@ -1,136 +1,116 @@
-# Team model v2: the workspace defines teams and the default; souls declare which they may join
+# Team model v2: shared and local teams, the default team, and membership per deployment
 
-Status: **PROPOSED 2026-09-27** (the lead drafts; the messaging co-lead shapes it; the human confirms the open questions). It supersedes teams-contract §3 amendment K's default-team rule and the "primary" label. The rest of `2026-09-25-teams-contract.md` stands: explicit join, only eligible labels, live reconciliation, and the provider's join/leave verbs.
+**Status:** decided and implemented (kernel 0.30.0, feature `team-model-2`). This record decides where teams, the default team and team membership live, how the kernel resolves them, and what the kernel hands a messaging provider. The reference pages ([workspaces.md](../workspaces.md#teams), [capabilities.md](../capabilities.md#teams-in-the-provider-environment), [desktop-cli-api.md](../desktop-cli-api.md#team-model-v2-feature-team-model-2-oats-0300-replaces-feature-teams)) win on operator-visible behaviour.
 
-## The human's direction (2026-09-27, verbatim)
+## Why
 
-> "El workspace define los equipos que hay, y a que equipo se instancian los souls por default. Y luego en el soul.yaml defines a que equipos se puede unir ese soul, y un default si quieres override el default de el workspace."
->
-> "we do not need aweb primitives for this, we already have teams. we need to be able to add and remove souls to teams."
->
-> "only pepe and i are using this for now, just clean up and do the right thing. no backwards comp required. setup may require creating accounts and teams, we need to support onboarding."
+Team membership is **local to each deployment**, over shared repositories and souls. Two people running the same souls from the same repositories have different sets of teams: some are shared (both map the label to the same provider team), some are personal, and each has their own default. Membership therefore never lives in a committed file, and every soul, member or package, is treated the same.
 
-## Why: today's model has four overlapping ideas
+What is shared is a fact, not a choice: a shared team's provider id is the same for everyone. That fact is committed once; everything personal is local.
 
-1. The workspace's `teams:` labels + `messaging.byTeam.<label>` map labels to provider teams. This part is right.
-2. **The default team is not the workspace's.** After amendment K it's the provider setting `team`, else the provider's own default. For oats.aweb that's the messaging root's active team: host state, invisible in config.
-3. **"Primary"** (the first of a soul's `team:` labels) sets `OATS_TEAM_LABEL` and ordering but isn't the default team.
-4. **`oats-membership.yaml` `team`** is a repository-level default label layered under the soul's.
+## The model (option B)
 
-On top of that, a soul can override the default only by writing a provider team *id* in its messaging slot, not a workspace label. And adding or removing a soul's teams means hand-editing YAML.
+The chosen model is **option B: shared facts committed, personal choices local**. The committed `oats-workspace.yaml` `teams:` declares the shared teams with their provider ids; each deployment's `oats-local.yaml` declares its local teams, its default team and all membership.
 
-## The model
+### Where it lives
+
+Committed `oats-workspace.yaml` (shared teams only; edited by PR):
 
-### The workspace (`oats-workspace.yaml`)
 ```yaml
 teams:
-  dev:      { description: … }
-  platform: { description: … }
-defaultTeam: dev                 # NEW: required when `teams` is non-empty; a declared label
-messaging:
-  oats.aweb: { from: package }
-  byTeam:
-    dev:      { team: <provider team id> }
-    platform: { team: <provider team id> }
+  oats: { team: oats:example.aweb.ai }        # a shared team: the same provider id for everyone
 ```
-- **`teams:`** declares the teams that exist (labels), as today.
-- **`defaultTeam:`** is the team a soul's instances go to by default. It's a label, never a provider id.
-- **`messaging.byTeam.<label>`** maps each label to its provider team, as today. It's the ONLY place a provider team id is written.
-- **Validation:** `defaultTeam` must be a declared label (`E_TEAM_UNKNOWN`). Once messaging is active, the default team's label must be mapped (`E_TEAM_UNMAPPED`, a refusal, not a warning: an instance must have somewhere to live).
 
-### The soul (`soul.yaml`)
+Local `oats-local.yaml` (the deployment's per-machine file, never committed):
+
 ```yaml
-teams: [dev, platform]           # RENAMED from `team`: the teams this soul MAY join
-defaultTeam: platform            # NEW, optional: overrides the workspace's; must be in `teams`
+teams:
+  antares-oats: { team: antares-oats:ana.aweb.ai }   # a local (personal) team: label → provider id
+defaultTeam: antares-oats
+souls:
+  disabled: [...]
+  teams:                        # the extra teams each soul's instances MAY join here
+    "*": [oats]                 # every soul
+    oats-expert: [oats]         # one soul: its bare name, or <package>/<soul> for a package soul
+  default:                      # an optional per-soul override of defaultTeam
+    oats-expert: oats
 ```
-- **`teams:`** is the eligible labels. Each must be declared by the workspace (`E_TEAM_UNKNOWN`), as today. The list is unordered: **"primary" goes away.**
-- **`defaultTeam:`** is optional. It must be one of the soul's `teams`, else `E_TEAM_NOT_ELIGIBLE`. When omitted, the workspace's `defaultTeam` applies, and the soul is eligible for it implicitly.
-- **Removed:**
-  - a soul's messaging-slot provider team id override;
-  - `oats-membership.yaml` `team` (two layers only: the workspace, then the soul);
-  - the old `team:` key.
-
-  No aliases (the human: no backwards compatibility).
-
-### Resolution (the kernel)
-- `effectiveDefault = soul.defaultTeam ?? workspace.defaultTeam`.
-- The provider receives the default team's mapped payload as its default. It gets **no root-active-team fallback.**
-- Plus the eligible set, `{label → payload}` for every label in `soul.teams ∪ {effectiveDefault}` that the workspace maps.
-- **The env names** (renamed, no aliases):
-  - `OATS_DEFAULT_TEAM` (the label) and `OATS_DEFAULT_TEAM_ID` (its mapped provider id);
-  - `OATS_TEAMS` (the JSON of the eligible set).
-  - `OATS_TEAM_LABEL`, `OATS_TEAM_LABELS` and `OATS_TEAM_ID` go.
-- **A standalone deployment** (no workspace) sets `teams` / `defaultTeam` / `messaging.byTeam` in its local config, with the same rules.
+
+- **`teams.<label>`** is `{ team?, description? }` in the committed file and `{ team, description? }` locally. These are the only places a provider team id is written. A shared team without `team` is declared but not yet created: readiness `team-unmapped`, a failure when it is the default, a warning otherwise.
+- **A label in both files** is `team-label-collision`, a readiness warning and never a spawn refusal: the shared definition wins, and the fix is renaming the local label. A teammate's PR adding a shared team never breaks another deployment on sync.
+- **`defaultTeam`** is the team every instance of this deployment lives in: its default-team identity. It names a label from either file. `oats teams add` of the first team sets it.
+- **`souls.teams`** lists the teams a soul's instances are eligible to join here: `"*"` for every soul, and a soul's own entry adds to it. Eligible teams are offered, never auto-joined.
+- **`souls.default`** overrides `defaultTeam` for one soul; it must be one of that soul's teams (`E_TEAM_NOT_ELIGIBLE`).
+- **An undeclared label** anywhere is `E_TEAM_UNKNOWN`: a spawn, preview or `inspect --soul` refusal, and a readiness item.
+- **Messaging active and no default** is `E_TEAM_UNCONFIGURED` (a readiness failure). There is no guessed team and no fallback to a provider's own active team.
+- **A label never gates, restricts, changes trust or partitions the knowledge store.**
+
+### Not part of the model
+
+These keys are refused with `E_WORKSPACE_SCHEMA` (reason `removed-key`), naming the replacement; there are no aliases:
+
+- `oats-workspace.yaml` `messaging.byTeam` (the id is `teams.<label>.team`) and `defaults.byTeam` (capabilities compose from the committed workspace and the soul only, so composition is the same for everyone);
+- `soul.yaml` `team:` and `oats-membership.yaml` `team`;
+- the "primary" label;
+- the messaging provider's own `team` setting, at every layer.
+
+### Resolution
+
+- `defaultOf(soul) = souls.default[soul] ?? defaultTeam`.
+- `teamsOf(soul) = {defaultOf(soul)} ∪ souls.teams["*"] ∪ souls.teams[soul]`, each label resolved through `teams.<label>`. The deployment default is among a soul's teams only when it is that soul's default or the soul lists it.
+- A soul's teams are rows `{label, team, default, from: "shared"|"local"}`, the default first, then by label; its default is `{label, team, from: "deployment"|"soul"}`. The spawn preview, `inspect --soul`, `oats souls` and readiness report them; `instance.json` records them at spawn.
+- **Changing `defaultTeam`** does not move running instances (their default-team identity is fixed): readiness `--home` warns `default-team-changed` until respawn.
 
 ### At spawn, and live
-- An instance is **always in its effective default team** (it can't leave it: `E_TEAM_DEFAULT`).
-- It joins other eligible teams explicitly: the spawn choice `join=…`, or the provider's join/leave on a live instance. This is unchanged from the teams contract.
-- **When a soul loses a label**, or the workspace unmaps it, a joined instance leaves it on the next live read. This is unchanged: teams contract §7 decision 6.
-- **When the effective default changes** (the workspace or soul `defaultTeam` edited), running instances keep their team until respawn. Readiness warns (`default-team-changed`) and names the new default.
 
-### Verbs: add and remove a soul's teams, set its default
-The CLI edits `soul.yaml` for a soul the deployment can edit (a member soul in a clone on this computer, or a local soul):
+- **At spawn an instance joins its default team only.** Every other eligible team is offered: the spawn's `join=<labels>` provider setting (a trigger's `spawn.teams` becomes it), and checkboxes in the Desktop spawn dialog. Each joined team gets its own identity.
+- **Later**, the provider's per-instance join and leave verbs opt one instance in or out of an eligible team. The default team is the instance's identity and is not left.
+- **Live rule:** a joined team that is no longer eligible (removed from the soul's list, or the team removed) is left on the next live read. A newly eligible team is offered, never auto-joined. Nothing else is undone.
+
+### Verbs
+
+The kernel verbs edit `oats-local.yaml` in place; they never call a provider, clone, or open a PR.
+
 ```
-oats soul teams <soul>                                  # eligible, default (and where it comes from)
-oats soul teams <soul> --add <label>[,<label>] | --remove <label>[,<label>]
-oats soul teams <soul> --default <label> | --clear-default
+oats teams [--json]                                   # this deployment's teams, ids, the default, problems
+oats teams add <label> --team <id> [--description d]  # declare a local team
+oats teams remove <label>                             # a local team nothing references
+oats teams default <label>
+oats soul teams <soul>|'*' [--add a,b] [--remove a,b] [--default <label> | --clear-default]
 ```
-- Each edit validates against the workspace (known label; the default ∈ teams) and writes the file.
-- **For a member soul it edits the clone's working tree and says so:** the change travels by commit/PR, as every config change does (oats.setup). It never pushes.
-- **Package souls are read-only:** their teams are the package's. A workspace adds a package soul to a team through the workspace instead, `teams.<label>.souls: [<pkg>/<soul>]`, which extends that soul's eligible set. Proposed; see Open question 3.
-- The Desktop gets the same controls on a soul's page (add/remove/default), and the spawn dialog shows the default + eligible teams.
-
-### Onboarding (setup creates accounts and teams)
-- **`oats aweb setup`** (the provider's setup verb, a setup-time human act):
-  - creates the account (`aw init --new-account --username …`) when none exists;
-  - creates every declared team that the workspace doesn't map yet;
-  - writes the resulting ids into `messaging.byTeam` **as a proposed diff** for the human to commit (oats.setup: config changes by PR).
-  - It never runs at spawn, mint, retire or wake.
-- **What aweb allows today** (the messaging lane, from aweb's lead, 2026-09-27):
-  - **The first account and its default team:** fully automatable (`aw init --new-account --username …`).
-  - **An additional team on a BYOD domain:** automatable headlessly with the namespace controller key:
-    1. `aw id team create --name <t> --namespace <domain>`;
-    2. the team key signs `aw id team invite`;
-    3. the root runs `accept-invite --local`.
-
-    `aw id team register` hosts it on aweb.ai. No human login is needed.
-  - **An additional team on a hosted account (`<u>.aweb.ai`):** NO CLI path. Only a logged-in human creates it, in the dashboard. aweb's lead proposes a generic `aw team create <name>` under the logged-in account.
-- **Update (2026-09-27, the human's decision via aweb's lead): the hosted gap closes headlessly** (aweb `aweb-abkh`, pending a Cloud + CLI release).
-  - A member of an org-owned hosted team creates a sibling team in the same account with `aw id team create --name <t>`, which returns the new `team_id` + a **single-use invite token**. The caller doesn't auto-join.
-  - The home that should hold the new team's member runs `aw --identity-home <root> id team accept-invite <token> --name <alias> --local`.
-  - No TTY, no `aw auth`; bounded by the account plan's team limit.
-- **So setup is designed FULLY HEADLESS:**
-  1. The account + the workspace's default team: `aw init --new-account --username …`.
-  2. Every further declared team (hosted or BYOD): `aw id team create --name <label>` + `accept-invite --local` into the deployment's root.
-  3. Setup writes each new id into `messaging.byTeam` as a proposed diff for the human to commit.
-- **The only gate is the aw/Cloud version floor** that ships `aweb-abkh`. Below it, a hosted extra team is refused with the remedy "upgrade aw" (the provider's readiness names the floor), not a guided dashboard step. The model doesn't change.
-- Setup needs no human login at all on this path.
-- Setup never runs at spawn/mint/retire/wake, and OATS holds no human login (the provider consumes the resulting root).
-- The oats.setup skills (`oats-teams`, `oats-onboarding`, `oats-workspace-config`) teach the model and the verbs.
-
-## Open questions (for the human)
-1. **At spawn:** is an instance in ONLY its default team (others joined explicitly), as proposed? Or does it join every team its soul lists?
-2. **When a soul's team is removed:** do running instances leave on the next live read (proposed, as today), or only when told to?
-3. **Package souls:** is a workspace-side `teams.<label>.souls: [...]` the right way to add a package soul to a team? The alternative is that package souls have only their package's teams.
-
-## Sequencing (proposed)
-1. **Now, small (the messaging lane):** an oats.aweb release with the setup `--new-account` fix + the dead `helperInjection` key.
-2. **This design:** the co-lead shapes it → the human answers 1–3 → **Decided**.
-3. **Kernel 0.30.0 (breaking):**
-   - the schemas;
-   - resolution + env;
-   - the `oats soul teams` verb;
-   - readiness;
-   - the oats.setup skills;
-   - docs.
-4. **oats.aweb 1.17:** the default from the kernel (no root-active fallback); `oats aweb setup` onboarding.
-5. **Desktop:**
-   - the server passes the new fields (the engineer);
-   - the soul-page team controls + the spawn dialog (the ux-designer).
-6. **The KB + migration** of the two existing deployments (one-shot, by the humans with the setup-admin soul).
-
-**Owners (proposed):**
-- the kernel: a cli-dev;
-- oats.aweb + onboarding: the messaging co-lead's developer;
-- the Desktop: the engineer + the ux-designer;
-- this doc, the review and the release: the lead.
+
+- `oats teams add` of a label already declared in either file is `E_TEAM_EXISTS`.
+- `oats teams remove` of a label still referenced (`defaultTeam`, `souls.teams`, `souls.default`) is `E_TEAM_IN_USE`, naming every reference; there is no cascade. A shared label is not removable here (`E_TEAM_SHARED`: it is edited by PR).
+- `oats soul teams` with an unknown label is `E_TEAM_UNKNOWN`; a `--default` outside the soul's teams after the write is `E_TEAM_NOT_ELIGIBLE`; `--default` with `'*'` is `E_BAD_ARGS`.
+- The Desktop offers the same controls, labelled "on this computer": the deployment's teams and default, and a soul's teams here.
+
+### Onboarding
+
+Setup is the messaging provider's act, run by a human at setup time, never at spawn, mint, retire or wake. OATS holds no human login. The provider's setup is expected to:
+
+- create the account and the first team when none exists, and record it locally with `oats teams add` (which makes it the default);
+- create a new **local** team at the provider, then record it with `oats teams add <label> --team <id>`. A local team is never declared without an existing id;
+- for a **shared** team declared without an id, let its owner create it and print the exact line to commit (`teams: { <label>: { team: <id> } }`), by PR; setup never edits the committed file;
+- join an **existing shared** team through its owner's invite;
+- normalize a label to the provider's team-name rules rather than passing it raw; the local mapping, not the name, is the truth.
+
+## The kernel ↔ provider contract
+
+**Environment** (every provider context: lifecycle hooks, home commands, operations and readiness checks). Teams travel beside a provider's settings, never inside them.
+
+- `OATS_DEFAULT_TEAM`: the soul's default label. `OATS_DEFAULT_TEAM_ID`: its provider id. `OATS_DEFAULT_TEAM_FROM`: `deployment` (`defaultTeam`) or `soul` (`souls.default`).
+- No default configured: none of the three is set. An unmapped default: `OATS_DEFAULT_TEAM` and `OATS_DEFAULT_TEAM_FROM` are set, `OATS_DEFAULT_TEAM_ID` is not.
+- `OATS_TEAMS`: JSON `[{label, team, default, from: "shared"|"local"}]`, every **mapped** team the soul may be in here, the default included (`default: true`), default first, then by label. Eligible to join = the rows with `default: false`. Unset when a home's teams are unknown (none recorded and unreadable now).
+- `OATS_TEAMS_SOURCE`: `live` (the workspace and `oats-local.yaml` read now, or a fresh resolution) or `recorded` (the spawn-time record in `instance.json`). **A provider leaves a joined team only on a `live` list**: a recorded list lacks every change since the spawn.
+- Live reads happen where teams are acted on: a home's launch hook (`oats session start|restart`), its messaging module's commands and operations, `oats inspect --home` and `oats readiness --home`. Every other context gets the recorded teams. A scheduled wake's session start uses the recorded teams, so it leaves nothing.
+- The pre-0.30 names `OATS_TEAM_LABEL`, `OATS_TEAM_LABELS` and `OATS_TEAM_ID` are always unset.
+
+**What the messaging provider does with it:**
+
+- mint an instance's default-team identity from `OATS_DEFAULT_TEAM_ID`, and join the other eligible teams only when asked (`join=` at spawn, or its per-instance verbs);
+- refuse the spawn, naming the problem, when no default is configured or the default is unmapped;
+- keep one identity root per team and mint each identity from that team's root, never from whatever team a root happens to have active; report a declared team with no member root as its own readiness problem;
+- make a leave caused by a live read visible: a warning in the hook or command output, a `left: [{label, team, at, reason: "no-longer-eligible"}]` list (the last 20) in its teams document, and the instance's events (`oats instance events`). There is no acknowledge state, and readiness does not nag;
+- report its teams document with `defaultTeam` in exactly the kernel's shape, `{label, team, from}`.
+
+**Kernel verbs are config only.** `oats teams add | remove | default` write `oats-local.yaml` `teams` and `defaultTeam`; `oats soul teams` writes `souls.teams` and `souls.default`. A provider's setup records what it created by calling `oats teams add` and `oats teams default` through `OATS_CLI_BIN`. Joining a shared team's membership is a provider act; there is no kernel `oats teams join`.

package/docs/design/2026-09-28-automations-trust.md

@@ -0,0 +1,38 @@
+# Hosts opt in to workspace automations (`automations.trust`)
+
+Status: **DECIDED 2026-09-28 by Juan** (the automation trust decision, recommended by the leads on
+2026-09-27). Target: OATS 0.30.
+
+## Context
+A workspace trigger or schedule runs on the host whose `host.name` is its `runsOn` and whose `gh`
+account is its `owner` (docs/schedules.md "Who runs it"). Both facts can come from a commit. So
+anyone who can commit to a member repo can make a machine that matches those names run an
+automation. Its operator never said yes to that automation, only to a host name and a login.
+
+## Decision
+**A host runs a workspace automation only when its operator has trusted it**, in the local file:
+```yaml
+# oats-local.yaml (never in oats-workspace.yaml or a member file: the committed schemas refuse it)
+automations:
+  trust:
+    - oats-knowledge/okf-review        # <member>/<id>, as the automations list names it
+    # or: trust: "*"                   # every automation the workspace places on this host
+```
+- **Runs only if** `runsOn` matches, `owner` matches, **and** `trust` admits it. `triggers.disabled` /
+  `schedules.disabled` still opt out on top.
+- **Absent or empty `trust`:** nothing runs.
+- **Matching but untrusted:** it never runs. It's listed with reason `untrusted` (after
+  `assigned-elsewhere`, `owner-mismatch` and `host-unnamed`). A readiness/status item says
+  "declared for this host, not trusted here", and its remedy names the exact `oats-local.yaml`
+  line to add. The automations status row carries the reason, so the Desktop can show it.
+- **A trust entry that matches nothing** is a warning, not an error: a member may not have
+  synced yet.
+- **Personal automations** (`oats trigger add` / `schedule add` in `oats-local.yaml`) are already
+  the operator's own choice and need no trust entry.
+
+## Behaviour change
+Hosts that ran workspace automations before 0.30 must add their `trust` lines. The 0.30 release
+notes say so. No host of ours runs one today, so there's nothing to migrate.
+
+## Unblocks
+The okf review trigger on Juan's host: it runs once his host trusts it.

package/docs/design/2026-09-28-soul-launch-preference.md

@@ -0,0 +1,63 @@
+# Soul launch preferences: a harness and model per soul, overridable per machine
+
+Status: **DECIDED 2026-09-28 by the human (Pepe)**: "per soul preference, but also allow the local
+overrides". Target: OATS 0.30.
+
+## Context
+Workspace-model v2 (0.25.0) removed `runtime`/`model` from `soul.yaml`, and 0.26.0 made a launch
+configuration "a spawn-time host choice, never a soul field", for portability (not every machine has
+every harness or model). The cost: there is no way to say "this role runs on Claude Code with Opus
+5.5" without passing `--launch-config` on every spawn, and the Desktop's soul pages show "No default
+harness" for every soul.
+
+## Decision
+1. **A soul may declare a launch preference** in `soul.yaml`:
+   ```yaml
+   launch: { harness: claude, model: claude-opus-5-5 }   # harness: pi|claude|codex; model optional
+   ```
+   It says only *what the role should run on*: no args, env, yolo or executable (those stay host
+   facts, in launch configurations). A package soul may declare one too (oats.engineering's
+   `code-reviewer`: Codex with Astra).
+2. **A machine may override it** in `oats-local.yaml`:
+   ```yaml
+   souls:
+     launch:
+       "*": <launch-config name>                  # every soul on this machine (optional)
+       oats-expert: opus                          # a launch configuration's name, or
+       oats.engineering/code-reviewer: { harness: codex, model: <model> }   # an inline preference
+   ```
+3. **Precedence for a new selection** (a spawn, or a start/restart given `--launch-config`/`--harness`/`--model`/`--reselect-launch`): explicit flags (`--launch-config`, `--harness`,
+   `--model`) → the machine's `souls.launch.<soul>` → its `souls.launch."*"` → the soul's `launch:` →
+   today's host default. A launch configuration named by an override supplies its full recipe; an
+   inline or soul preference supplies harness and model on top of the host's baseline for that harness.
+   **A home's recorded launch stays frozen:** a plain start/restart runs it as recorded (`from:
+   recorded`). A preference is a default for new instances, not a live setting; a drifted
+   preference shows in `inspect --home` (`launch.current`), and a restart never changes it silently.
+4. **Unavailable harness:** if the chosen harness isn't installed on the machine, the spawn refuses
+   with a clear error naming the source (soul / local / flag) and the fix (install it, or override in
+   `oats-local.yaml`). No silent fallback to another harness.
+5. **Reported everywhere a launch is shown:** `spawn --preview`, `inspect --soul` and `oats souls`
+   carry the soul's declared `launch` and the effective one with its `from` (`flag` | `local` |
+   `local-default` | `soul` | `host` | `recorded`); `instance.json` records the effective one.
+
+## Migration (binding): the same hazard as the team model
+0.29.4's `soul.yaml` schema refuses unknown keys, and members are read at their latest commit.
+- The kernel accepts `launch:` and `souls.launch` in 0.30.
+- **Committed souls gain `launch:` only on the flag day** (every deployment of the workspace runs
+  0.30), and `oats.engineering` ships its reviewer's `launch:` in a release with `compatibility:
+  oats >=0.30.0`.
+- Until then, each machine sets its preferences with the local override (0.30), or with
+  `--launch-config` at spawn.
+
+## Consumers
+- The **Desktop** already renders a soul's default harness and model on the soul page and the side
+  panel, but it reads fields v2 souls no longer have, so it shows "No default harness". It reads the new
+  `launch` (declared + effective + `from`) consumer-first, before the kernel emits it; the spawn dialog
+  shows the effective choice and where it came from.
+- **`oats.developer`'s** `/run-the-review-loop` compares the developer's effective model with the
+  reviewer's effective one (from `spawn --preview`) and picks another model when they're the same.
+
+## The first preferences (at the flag day)
+- All expert souls in the oats repo: Claude Code, Opus 5.5.
+- `oats.engineering/code-reviewer`: Codex, Astra.
+(Model ids are verified against each harness when they're written, not guessed.)

package/docs/design/HISTORY.md

@@ -0,0 +1,65 @@
+# Design history
+
+The design records below were superseded and deleted. Each row keeps the
+decision findable: what the record decided, what replaced it, and a link to its
+full text at the last commit that carried it. The current behaviour is in the
+reference pages; the records still in force are listed in the
+[design index](README.md).
+
+| record | date | decision | superseded by |
+|---|---|---|---|
+| [OATS Desktop — UX plan (phase 1)](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/desktop-ux-plan.md) | 2026-07-22 | Chose the Desktop's design language: a VS Code-style shell with command palette, semantic theme tokens and an agent-centred information architecture. | [Desktop design brief](../../packages/desktop/docs/design-brief.md) |
+| [Architecture reassessment: usable agents with replaceable services](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-07-architecture-reassessment.md) | 2026-09-07 | Kept the package and capability-layer mechanism, fixed places where the CLI and Desktop bypassed it, and assigned separate ownership to kernel, backends, capabilities and Desktop. | [layers](../layers.md) |
+| [Souls and capabilities in Desktop](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-07-desktop-souls-capabilities.md) | 2026-09-07 | Desktop inspects souls, capabilities and provider operations only through kernel JSON and changes them only through CLI verbs, never by editing YAML itself. | [Desktop CLI API](../desktop-cli-api.md) |
+| [Proposal: manage server agents from an iPhone](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-07-mobile-agent-management-proposal.md) | 2026-09-07 | Proposed managing server agents from an iPhone through an installable mobile web app reached over Tailscale, reusing the existing control and session contracts. | none (proposal, never implemented) |
+| [Launch configurations and launch recipes](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/launch-configurations.md) | 2026-09-07 | A launch configuration is a named host choice of harness, executable, args, env, model and yolo; a spawn records a launch recipe that every start renders. | [configuration](../configuration.md#launch-configurations) |
+| [Provider operations and inspection contract](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/operations-contract.md) | 2026-09-07 | A capability declares named operations over its own commands; `oats operation run` resolves the slot's provider and relays one validated JSON answer. | [capabilities](../capabilities.md#operations-a-capability-declares) |
+| [Expert-assisted deployment and an extensible OATS](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-08-expert-assisted-deployment-proposal.md) | 2026-09-08 | Proposed that an OATS expert sets up and verifies agents on other machines through reliable commands and skills, with multi-team membership and explicit knowledge destinations. | [capabilities](../capabilities.md#official-packages) (`oats.setup`), [workspaces](../workspaces.md#teams) |
+| [Knowledge and memory in OATS: the central knowledge base and the expertise doctrine](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-13-knowledge-and-memory-direction.md) | 2026-09-13 | All knowledge leaves the soul for a central per-project base of owned nodes; working agents only read and capture, and a per-instance harvester is the sole writer. | [knowledge theory](../knowledge-theory.md), [knowledge](../knowledge.md) |
+| [Knowledge implementation plan](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-13-knowledge-implementation.md) | 2026-09-13 | Planned the first OKF delivery: Git and directory bases configured by a bindings file, independent per-source harvest, PR-only Git delivery and explicit migration. | [knowledge](../knowledge.md), [OKF knowledge operations](2026-09-26-okf-knowledge-operations.md) |
+| [Knowledge contracts, integrations, and storage](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-13-knowledge-location-contract.md) | 2026-09-13 | Proposed separating the knowledge model, the integration and storage custody, using bases, nodes and bindings with harvest independent of the source instance. | [knowledge](../knowledge.md#bindings-document), [knowledge capability contract](2026-09-16-knowledge-capability-contract.md) |
+| [Finalizing the OKF mirror's source provenance](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/okf-mirror-provenance.md) | 2026-09-13 | The standalone oats-okf repository is authoritative; the mirror here is finalized only from a clean checkout at the published tag, verified against origin. | [release lane](../release-lane.md#mirroring-a-released-oatsokf) |
+| [Retained capability artifacts and captured resolutions](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-14-artifact-retention-contract.md) | 2026-09-14 | Added primitives that retain verified, immutable capability trees addressed by digest, as the base for captured resolutions, separate approval and dispatch. | removed (no successor, 0.26.0) |
+| [Portable souls and Git-backed organizational workspaces](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-14-portable-souls-and-git-workspaces.md) | 2026-09-14 | Souls declare their capability sources, a Git-hosted workspace declares reciprocal membership and defaults, and each local deployment resolves, installs and binds credentials. | [workspaces](../workspaces.md) |
+| [Portable Souls — substantive contract amendment](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-14-portable-souls-contract-amendments.md) | 2026-09-14 | Amended Portable Souls with `requires` versus `defaults`, `repo:` source paths, external soul imports by reference and store-qualified knowledge nodes. | [workspaces](../workspaces.md) |
+| [Portable Souls](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-14-portable-souls-explainer.md) | 2026-09-14 | Explained the Portable Souls model (soul, workspace and deployment responsibilities, reciprocal membership, private-first teams) through an illustrative multi-repository organisation. | [workspaces](../workspaces.md), [Desktop design brief](../../packages/desktop/docs/design-brief.md) |
+| [Captured dispatch integration](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-15-captured-dispatch.md) | 2026-09-15 | Captured each selected manifest's setting defaults with provenance and dispatched commands only from the exact captured resolution, never from current configuration. | removed (no successor, 0.26.0) |
+| [Captured resolution records — implementation boundary](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-15-captured-resolution-records.md) | 2026-09-15 | Defined content-addressed, immutable resolution records stored under the deployment, outside instance homes, with verification of every retained input. | removed (no successor, 0.26.0) |
+| [Package preparation integration](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-15-package-preparation.md) | 2026-09-15 | Reused one shared capability materializer for acquisition, restore and portable package preparation instead of a separate portable installer. | [packages](../packages.md#materialization-from-a-package) |
+| [Portable data and digest contract](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-15-portable-data-contract.md) | 2026-09-15 | Made integrity an explicit `{format, value}` pair with a new executable-aware tree encoding and canonical JSON, so trust never transfers between formats. | [packages](../packages.md#lock-v3); captured formats removed in 0.26.0 |
+| [Portable declaration codecs — implementation contract](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-15-portable-declarations.md) | 2026-09-15 | Added one bounded YAML/JSON reader and parsers for soul v1, workspace, repository exports and external imports, feeding a single choice engine. | [workspaces](../workspaces.md#the-files), [souls and instances](../souls-and-instances.md#soulyaml-v2) |
+| [Portable Souls infrastructure implementation handoff](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-15-portable-souls-handoff.md) | 2026-09-15 | Recorded the fifteen binding Portable Souls decisions and a dependency-ordered delivery plan, with Desktop feature work deferred. | [workspaces](../workspaces.md); captured path removed in 0.26.0 |
+| [Portable Souls infrastructure implementation](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-15-portable-souls-implementation.md) | 2026-09-15 | Recorded a ledger mapping each binding Portable Souls decision to delivery steps and acceptance evidence. | [workspaces](../workspaces.md); captured path removed in 0.26.0 |
+| [Selection lock and approval — implementation boundary](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-15-selection-lock-and-approval.md) | 2026-09-15 | Introduced a selection lock of artifact sets with current and available choices, and exact-artifact executable approval kept separate from the lock. | [lock v3](../packages.md#lock-v3), [package trust](../packages.md#trust) |
+| [Repository observation and source custody](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-15-source-observation.md) | 2026-09-15 | Observed repositories through native Git and `gh` in one transaction, recording exact identity and commit without checking out or executing source. | [workspace module contracts](2026-09-23-workspace-module-contracts.md) |
+| [Captured incarnation and admitted actions](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-16-captured-admission.md) | 2026-09-16 | Minted a stable incarnation ID per fresh home and indexed custody witnesses and admitted provider intents outside the home. | removed (no successor, 0.26.0) |
+| [Retained helper selection — supported subset](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-16-captured-helper-dispatch.md) | 2026-09-16 | Resolved a capability's helper exactly from the source resolution's helper map, with no live soul, configuration or lock lookup. | removed (no successor, 0.26.0) |
+| [Explicit retained launch inputs](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-16-captured-launch-inputs.md) | 2026-09-16 | Required explicit runtime, executable, arguments, environment, model and yolo inputs to compile a captured launch recipe, with no defaulting. | removed (no successor, 0.26.0) |
+| [Command/curriculum preparation](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-16-command-profile-preparation.md) | 2026-09-16 | Added `oats prepare`, combining by-reference soul import, workspace choices and package preparation into captured records without launching. | removed in 0.26.0; replaced by [`oats sync`](../packages.md#oats-sync--the-one-command-for-the-common-path) |
+| [Fresh-install-first Portable Souls rollout](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-16-fresh-install-first-rollout.md) | 2026-09-16 | Prioritised fresh installations over automatic in-place migration and historical reconstruction, keeping the architecture and custody rules unchanged. | none (fresh installs; no migration) |
+| [Fresh operator walkthrough: working preparation versus pending launch](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-16-fresh-operator-walkthrough.md) | 2026-09-16 | Recorded a source-level walkthrough of fresh preparation versus the still-pending captured launch. | [workspace module contracts](2026-09-23-workspace-module-contracts.md), [workspaces](../workspaces.md) |
+| [Messaging capability contract boundary](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-16-messaging-capability-contract.md) | 2026-09-16 | OATS supplies generic messaging selection, lifecycle and outcome contracts; the messaging capability owns identity, teams, transport and access verification. | merged into the [knowledge and messaging capability contract](2026-09-16-knowledge-capability-contract.md) |
+| [Portable migration evidence reader and planner](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-16-portable-migration-evidence.md) | 2026-09-16 | Added a read-only inventory and planner of legacy locks, homes and schedules as evidence for a later explicit migration. | removed (no successor, 0.25.0) |
+| [Portable fresh onboarding and source discovery](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-16-portable-onboarding.md) | 2026-09-16 | Kept source, deployment, work target and membership context as independent facts in a fresh onboarding and discovery facade. | [Desktop CLI API](../desktop-cli-api.md#oats-onboard-onboardapi-2), [workspaces](../workspaces.md) |
+| [Public preparation request-file transport](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-16-prepare-request-transport.md) | 2026-09-16 | Let `oats prepare --request` read the whole preparation input from one bounded JSON file, exclusive with every other input flag. | removed (no successor, 0.26.0) |
+| [Provider-owned binding codecs — implementation boundary](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-16-provider-binding-codecs.md) | 2026-09-16 | A core capability may declare a versioned `binding` naming its own normalize, bind and check commands, so providers own their binding model. | [capabilities](../capabilities.md#readiness-check-bindingcheck) |
+| [Provider binding wire v1](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-16-provider-binding-wire.md) | 2026-09-16 | Defined the bounded JSON stdin/stdout protocol for the normalize, bind and check binding phases. | [capabilities](../capabilities.md#readiness-check-bindingcheck) |
+| [Capability-owned helper injection and lifecycle input contract](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-17-capability-helper-input-contract.md) | 2026-09-17 | Replaced kernel assumptions with an explicit `helperInjection` manifest field and a per-hook opt-in for source receipts. | removed (no successor, 0.26.0; the fields are accepted and ignored) |
+| [Captured native backend parity: tmux and Herdr](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-17-captured-backend-parity.md) | 2026-09-17 | Supported captured start and restart on both tmux and Herdr through explicit backend endpoints recorded in receipts. | removed (no successor, 0.26.0) |
+| [Captured native start through the existing session transaction](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-17-captured-native-start.md) | 2026-09-17 | Started captured instances through the existing native session transaction, from a retained entrypoint or an explicit host executable path. | removed (no successor, 0.26.0) |
+| [Captured boundary resource hookup](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-17-portable-boundary-hookup.md) | 2026-09-17 | Wired the captured-only boundary injections into captured preparation, with unchanged labels and order. | removed (no successor, 0.26.0) |
+| [Captured-only instance and directory boundaries](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-17-portable-boundary-resources.md) | 2026-09-17 | Added captured-only instance-boundary and work-directory injections that take authority from the captured resolution rather than the working directory. | removed (no successor, 0.26.0) |
+| [Public captured start and retained helper dispatch](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-17-public-captured-start.md) | 2026-09-17 | Exposed captured start and restart, including retained helpers, through `oats session start\|restart --deployment --resolution`. | removed (no successor, 0.26.0) |
+| [Public preparation request-file transport](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-17-public-prepare-request.md) | 2026-09-17 | Added a shared helper that reads a preparation request file intact, leaving validation to the one preparation entry point. | removed (no successor, 0.26.0) |
+| [Captured Pi print host — kernel implementation boundary](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-18-captured-pi-host.md) | 2026-09-18 | Added an explicit Pi SDK print-mode host for captured launches, with kernel-controlled arguments, task and history. | removed (no successor, 0.26.0) |
+| [First-cut retained execution: installation and release checklist](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-18-first-cut-release-checklist.md) | 2026-09-18 | Planned the installation, acceptance and publication checklist for the first runnable retained-execution release. | removed (no successor, 0.26.0) |
+| [Explicit Herdr protocol20/22 adapter compatibility](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-18-herdr-protocol-compatibility.md) | 2026-09-18 | The Herdr adapter supports exactly protocols 20 and 22 by explicit selection, with no version negotiation. | [execution targets](../execution-targets.md) |
+| [OATS redesign — program board](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-20-redesign-program-board.md) | 2026-09-20 | Recorded the state, owners and blockers of every redesign work stream. | none (status board) |
+| [OATS adoption plan: workspace first, knowledge and experts second](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-20-workspace-and-portable-adoption-plan.md) | 2026-09-20 | Planned moving OATS development onto a Git workspace, then central knowledge and expert souls, then Desktop parity, with official `oats.core` and `oats.setup` capabilities. | [workspaces](../workspaces.md), [official catalog](../official-catalog.md) |
+| [Public source inspection for same-repository workspace onboarding](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-20-workspace-onboarding-public.md) | 2026-09-20 | Added read-only `oats inspect --request` to inspect onboarding sources and optionally emit a preparation request. | removed in 0.26.0; replaced by [`oats onboard`](../desktop-cli-api.md#oats-onboard-onboardapi-2) |
+| [Desktop parity — slice plan and kernel/provider seams (S8)](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-22-desktop-parity-seams.md) | 2026-09-22 | Planned Desktop parity slices and the kernel and provider JSON seams they need, under shared rules for envelopes and targets. | [Desktop CLI API](../desktop-cli-api.md) |
+| [A simpler multi-repo model for OATS — brainstorm with a worked example](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-23-simplified-workspace-model.md) | 2026-09-23 | Accepted workspace model v2: membership is trust, souls name where each capability comes from, only packages are versioned, capabilities are copied into instances. | [workspaces](../workspaces.md), [workspace module contracts](2026-09-23-workspace-module-contracts.md) |
+| [Phase 4 — implementing workspace model v2: proposal for the human](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-23-workspace-v2-implementation-plan.md) | 2026-09-23 | Planned the workspace model v2 implementation as ordered work packages replacing canonical kernel code, with no migration and no feature flag. | [workspace module contracts](2026-09-23-workspace-module-contracts.md) |
+| [Desktop Phase F — the Desktop is built FOR workspace model v2](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-24-desktop-phase-f-boundary.md) | 2026-09-24 | The Desktop is rebuilt natively for workspace model v2, reading every deployment fact and making every change through kernel JSON verbs. | [Desktop CLI API](../desktop-cli-api.md#workspace-model-workspaceapi-2), [Desktop design brief](../../packages/desktop/docs/design-brief.md) |
+| [Phase D — the OATS project runs on the architecture it offers (plan)](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-24-phase-d-plan.md) | 2026-09-24 | Planned running the OATS project on workspace model v2, centralising its knowledge, and recorded removing per-version package approval. | [packages](../packages.md#trust), [official catalog](../official-catalog.md) |
+| [Teams contract: several team labels per soul, per-team messaging, live reconciliation](https://github.com/awebai/oats/blob/7838d3ca70772f63854b198601fbc45437c2e999/docs/design/2026-09-25-teams-contract.md) | 2026-09-25 | A soul may carry several team labels, each with its own messaging payload, and the provider reconciles team membership live. | [team model v2](2026-09-27-team-model-v2.md) |

package/docs/design/README.md

@@ -1,54 +1,23 @@
-# Design documents — navigation
-
-Dated design documents record how decisions were reached and what each implementation slice was bounded to. They are **history with current pointers**: the current architecture is explained in [workspaces](../workspaces.md), [packages](../packages.md), [configuration](../configuration.md), [souls and instances](../souls-and-instances.md), [contracts](../layers.md) and [knowledge theory](../knowledge-theory.md); readiness is stated in the [release notes](../release-notes/). When a dated document and a current page disagree, the current page wins.
-
-## Current model — workspace v2 (0.25 line)
-
-- **[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: [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` 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)
-
-- [Redesign program board](2026-09-20-redesign-program-board.md) — status of the 0.24 work streams (knowledge contract, workspace adoption, messaging readiness, official capabilities, marketplace, five souls, centralised knowledge, Desktop).
-- [Workspace-first adoption plan (2026-09-20)](2026-09-20-workspace-and-portable-adoption-plan.md) — the 0.24 phase order and distribution work packages (`oats.core`, `oats.setup`, official marketplace).
-
-## Portable Souls and Git workspaces — the 0.24 architecture (superseded)
-
-- [Portable Souls explainer](2026-09-14-portable-souls-explainer.md) — the short version.
-- [Portable souls and Git-backed workspaces](2026-09-14-portable-souls-and-git-workspaces.md) — the accepted architecture.
-- [Contract amendments (14 Sep)](2026-09-14-portable-souls-contract-amendments.md) · [portable declarations](2026-09-15-portable-declarations.md) · [portable data/digest contract](2026-09-15-portable-data-contract.md) · [source observation](2026-09-15-source-observation.md).
-- [Fresh-install-first rollout](2026-09-16-fresh-install-first-rollout.md) · [fresh operator walkthrough](2026-09-16-fresh-operator-walkthrough.md) · [portable onboarding and discovery](2026-09-16-portable-onboarding.md) · [migration evidence](2026-09-16-portable-migration-evidence.md) — the `lib/portable-migration*`, `lib/portable-onboarding-acceptance.mjs` modules and the `portable-onboarding-public` acceptance driver these cite are deleted; each note carries a superseded banner pointing at the [simplified workspace model](2026-09-23-simplified-workspace-model.md).
-
-## Retained execution — artifacts, approval, capture (0.24; artifact/approval parts superseded by lock v3)
-
-- [Artifact retention](2026-09-14-artifact-retention-contract.md) · [selection lock and approval](2026-09-15-selection-lock-and-approval.md) · [captured resolution records](2026-09-15-captured-resolution-records.md).
-- [Package preparation](2026-09-15-package-preparation.md) · [command/curriculum preparation](2026-09-16-command-profile-preparation.md) · [prepare request transport](2026-09-16-prepare-request-transport.md) · [public prepare request](2026-09-17-public-prepare-request.md).
-- [Captured dispatch](2026-09-15-captured-dispatch.md) · [captured admission](2026-09-16-captured-admission.md) · [retained helper dispatch](2026-09-16-captured-helper-dispatch.md) · [retained launch inputs](2026-09-16-captured-launch-inputs.md).
-- [Boundary resources](2026-09-17-portable-boundary-resources.md) · [boundary hookup](2026-09-17-portable-boundary-hookup.md) · [captured native start](2026-09-17-captured-native-start.md) · [public captured start](2026-09-17-public-captured-start.md).
-- [Backend parity: tmux and Herdr](2026-09-17-captured-backend-parity.md) · [Herdr protocol compatibility](2026-09-18-herdr-protocol-compatibility.md) · [captured Pi print host](2026-09-18-captured-pi-host.md).
-- [First-cut release checklist](2026-09-18-first-cut-release-checklist.md).
-- Implementation records: [implementation](2026-09-15-portable-souls-implementation.md) · [handoff](2026-09-15-portable-souls-handoff.md).
-
-## Capabilities and providers
-
-- 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).
-
-## Knowledge and memory
-
-- [Knowledge and memory direction](2026-09-13-knowledge-and-memory-direction.md) · [knowledge location contract](2026-09-13-knowledge-location-contract.md) · [knowledge implementation plan](2026-09-13-knowledge-implementation.md) · [OKF mirror provenance](okf-mirror-provenance.md).
-
-## Product direction and Desktop
-
-- [Architecture reassessment](2026-09-07-architecture-reassessment.md) · [expert-assisted deployment](2026-09-08-expert-assisted-deployment-proposal.md).
-- [Desktop UX plan](desktop-ux-plan.md) · [souls and capabilities in Desktop](2026-09-07-desktop-souls-capabilities.md) · [mobile management proposal](2026-09-07-mobile-agent-management-proposal.md).
-
-Adding a design doc: date-prefix it, state its status in the first lines, and add it here under the right theme.
+# Design records
+
+Dated records of decisions that are still in force: the context, the decision
+and its consequences. The current behaviour is explained in the reference pages
+([workspaces](../workspaces.md), [packages](../packages.md),
+[configuration](../configuration.md), [souls and instances](../souls-and-instances.md),
+[capabilities](../capabilities.md), [knowledge](../knowledge.md)); when a record and
+a reference page disagree, the reference page wins. Superseded records are
+deleted; [HISTORY.md](HISTORY.md) lists each one, its decision and its
+successor, with a link to its full text.
+
+- [Workspace module contracts](2026-09-23-workspace-module-contracts.md): the
+  normative contracts of `lib/remote.mjs`, `lib/workspace.mjs`, `lib/resolve.mjs`,
+  `lib/packages.mjs`, `lib/materialize.mjs` and the CLI verbs built on them.
+- [Knowledge and messaging capability contract](2026-09-16-knowledge-capability-contract.md):
+  the kernel supplies contracts; capabilities own knowledge and messaging behaviour.
+- [OKF knowledge operations](2026-09-26-okf-knowledge-operations.md): package
+  souls, triggers and automations for harvest and maintenance.
+- [Team model v2](2026-09-27-team-model-v2.md): shared teams in the workspace,
+  local teams, the default team and membership in each deployment.
+
+The Desktop's design brief for designers is in
+[packages/desktop/docs](../../packages/desktop/docs/design-brief.md).