@awebai/oats 0.29.3 → 0.30.0

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

@@ -0,0 +1,116 @@
+# Team model v2: shared and local teams, the default team, and membership per deployment
+
+**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.
+
+## Why
+
+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.
+
+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.
+
+## The model (option B)
+
+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.
+
+### Where it lives
+
+Committed `oats-workspace.yaml` (shared teams only; edited by PR):
+
+```yaml
+teams:
+  oats: { team: oats:example.aweb.ai }        # a shared team: the same provider id for everyone
+```
+
+Local `oats-local.yaml` (the deployment's per-machine file, never committed):
+
+```yaml
+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.<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
+
+- **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 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]
+```
+
+- `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).