@awebai/oats 0.29.4 → 0.30.0

package/docs/execution-targets.md

@@ -1,303 +1,157 @@
-# Execution targets and shared wake delivery
-
-Implementation agreement, 2026-09-05. Lead owns native runtime launch,
-local tmux/Herdr adapters and terminal input; oats owns server registration,
-remote CLI routing and Desktop target selection. Aweb owns the event listener,
-notification state and delivery policy through OATS terminal input. This is the implementation
-contract, not a claim that these features have shipped.
-
-OATS manages composition, worktrees, capability lifecycle and retirement on the execution
-host. A session backend manages the persistent terminal. Desktop is a client;
-closing it must stop neither the agent nor notification delivery.
-
-```mermaid
-flowchart LR
-  UI[Desktop] --> CLI[OATS CLI]
-  CLI --> Local[Local OATS]
-  CLI --> SSH[OpenSSH]
-  SSH --> Remote[Remote OATS]
-  Local --> Sessions[tmux or Herdr]
-  Remote --> RemoteSessions[tmux or Herdr]
-  Events[aweb SSE] --> Wake[aweb wake service on execution host]
-  Wake --> Local
-  RemoteWake[aweb wake service on remote host] --> Remote
-```
-
-Server registrations live in the operator's machine configuration, outside
-repository configuration. Each entry has an id, label, OpenSSH host alias,
-absolute workspace path and OATS/Herdr executable paths. SSH owns key selection,
-host verification and authentication. Registration stores no private keys.
-Remote lifecycle calls invoke the remote installed OATS CLI with argument-safe
-quoting and the same JSON envelope as local calls. Version/envelope compatibility
-is checked before mutation. Repository operations always run on that host.
-
-The local representation of a remote instance snapshots its route:
-
-```json
-{
-  "serverId": "build-server",
-  "target": {
-    "sshHost": "build-server",
-    "workspace": "/srv/team",
-    "oatsPath": "/usr/local/bin/oats",
-    "herdrPath": "/usr/local/bin/herdr"
-  },
-  "instance": "developer-fix",
-  "home": "/srv/team/agents/developer/instances/developer-fix"
-}
-```
-
-`serverId` is for display. Later inspect/retire operations use the snapshot,
-never silently resolve a changed registry entry. A local cache is not authority
-for the remote instance's state. Remote status is pulled from its owning kernel.
-
-The host's instance and independent retirement baseline retain the same local
-session receipt. Existing `tmux: {session, window, socket}` remains readable.
-New Herdr instances use:
-
-```json
-{
-  "backend": "herdr",
-  "binary": "/usr/local/bin/herdr",
-  "socket": "/home/operator/.config/herdr/sessions/oats/herdr.sock",
-  "workspaceId": "w1",
-  "paneId": "w1:p1",
-  "terminalId": "term_65ab9108c6c301",
-  "protocol": 20
-}
-```
-
-The terminal id distinguishes a replacement occupant after a server restart.
-Backend operations allocate, start, inspect, stop and attach a viewer. Retirement
-compares the receipt with its baseline and proves the original session absent.
-An unavailable server or failed inspection is not proof of absence. The same
-rule applies to spawn compensation and detached self-retirement. Lifecycle
-operations run on the target host, so the local backend does not implement SSH.
-
-Herdr 0.8.2 exposes snapshots, socket commands, agent-state inspection and JSONL
-terminal observation/control. Its protocol is versioned. Agent prompts reject
-approval-blocked agents, but prompting a working agent does not prove the new
-message was processed. The adapter must retain this distinction. See the
-[Herdr socket API](https://herdr.dev/docs/socket-api/) and
-[remote connections](https://herdr.dev/docs/persistence-remote/).
-
-An aweb host service owns event streams for managed instances; the GUI displays
-and controls it. Reuse aweb's existing authenticated event/run loop rather than copying credential
-and SSE parsing into OATS or Desktop. OATS exposes backend-neutral session
-inspection and literal terminal input; aweb supplies delivery policy. Current authorization is
-per identity: one long-lived stream per active identity, coalesced per instance,
-with bounded retries. A single team stream requires an explicit server API.
-Reconnect also checks pending state so a lost edge does not strand unread work.
-
-Delivery is a fixed instruction to check `aw` mail/chat from the instance home,
-not arbitrary sender content typed into a shell. The service never acknowledges
-mail or chat on the agent's behalf. Aweb pending hints survive reconnect and service
-restart, coalesce while busy and defer at approval prompts. A stopped harness,
-an unknown occupant or a fallback shell is not a delivery target. Do not call a
-successful terminal write an agent acknowledgement.
-
-Native channels remain selectable during qualification; session delivery must
-be exclusive with them for each instance. Removal follows real tests of Pi,
-Claude and Codex receiving mail/chat, a busy turn, an approval prompt, reconnect,
-service restart, GUI closure and a stopped runtime. The OATS Pi tool extension
-and the aweb Pi channel are separate packages; replacing notification transport
-does not silently remove unrelated tools.
-
-Acceptance includes local CLI/Desktop spawn, reattach, preserved work and
-retirement through both backends; then the same operations on a user-designated
-SSH target. Registering a host without a successful remote agent run does not
-qualify remote support.
-
-## Session CLI contract
-
-Run on the execution host:
+# Sessions
+
+A **session** is the terminal in which an instance's harness runs. OATS
+composes the instance home ([souls-and-instances.md](souls-and-instances.md)),
+then launches the harness in a persistent terminal owned by a session backend.
+Closing a viewer, or the Desktop, stops neither the agent nor its session.
+
+All session commands run on the execution host, the machine that holds the
+home. To run them on another machine, see [servers.md](servers.md).
+
+## Harnesses
+
+| Harness | `--harness` | Launched as |
+|---|---|---|
+| pi | `pi` (the default) | `pi --append-system-prompt <home>/AGENTS.md --approve --name <instance> [--model m] @TASK.md` |
+| Claude Code | `claude` | `claude [--model m] -- "$(cat TASK.md)"` |
+| Codex | `codex` | `codex --cd <home> [--model m] -- "$(cat TASK.md)"` |
+
+Each harness starts in the instance home with its own native settings,
+authentication and skill discovery. The command line also carries the
+launch configuration's arguments and each capability's launch contribution.
+`--runtime` is still read as `--harness`, with a deprecation warning; giving
+both with different values is refused.
+
+The harness, model, yolo choice and executable come from the spawn flags or a
+named launch configuration (`--launch-config <name>`); see
+[configuration.md](configuration.md#launch-configurations).
+`--model @native-default` uses the harness's own default model.
+
+The launch command sets `OATS_INSTANCE`, `OATS_INSTANCE_HOME`,
+`PI_AGENT_INSTANCE` and `PI_AGENT_HOME`, plus the environment that the launch
+configuration and capabilities contribute. The home's layout and what those
+variables point at are described in
+[souls-and-instances.md](souls-and-instances.md#instance-anatomy).
+
+## Backends
+
+`oats spawn --backend tmux|herdr` chooses the backend (default `tmux`). The
+backend binary must be installed on the execution host. The chosen session
+target is recorded twice: in `instance.json` and in an independent lifecycle
+receipt. Every session command checks that the two agree
+(`E_RUNTIME_AUTHORITY_MISMATCH` otherwise).
+
+### tmux
+
+Each instance is a window named after the instance in the tmux session
+`pi-agents` (override with `PI_AGENTS_TMUX_SESSION`). The receipt records the
+session, window and socket. The spawn result prints the attach command.
+
+### Herdr
+
+Each instance is a Herdr workspace with one pane. The receipt records the
+binary, socket, workspace id, pane id, terminal id and protocol. The terminal
+id distinguishes a replacement occupant of the same pane.
+
+- `--herdr-socket <path>` uses an operator-managed Herdr server. OATS never
+  starts a different server when that socket cannot be inspected.
+- Without it, OATS uses `$XDG_CONFIG_HOME/herdr/sessions/oats/herdr.sock`
+  (default `~/.config/...`) and starts `herdr --session oats server` if no
+  server is running there.
+- The adapter speaks the Herdr socket API at an explicit protocol version,
+  with no negotiation. New sessions use protocol 20. A recorded session target
+  may carry protocol 20 or 22, and each call checks that the server's snapshot
+  reports the recorded protocol.
+
+## Lifecycle
+
+| Command | Effect |
+|---|---|
+| `oats spawn <soul> [--no-launch]` | Creates the home and launches the harness. `--no-launch` creates the home only. |
+| `oats session start --home <abs>` | Starts a stopped or never-launched instance again in its existing home. |
+| `oats session restart --home <abs>` | Stops the running harness and starts it again in place. |
+| `oats instance stop <instance> --plan` / `--apply` | Stops the harness and keeps home, work and launch recipe. |
+| `oats retire <instance>` | Ends the session and retires the instance ([souls-and-instances.md](souls-and-instances.md#retire)). |
+
+### Start and restart
+
+`session start` keeps the instance's identity, work tree and notes. It runs no
+spawn hooks and creates no new home. It runs the recorded launch recipe on the
+recorded tmux session or Herdr server; a `--no-launch` home starts on the
+default tmux server.
+
+- `--model`, `--launch-config <name>|none`, `--harness` and `--yolo` /
+  `--no-yolo` re-resolve the recipe against the home's recorded context and
+  run every check before anything starts. `--model` replaces the recorded model
+  for this and later starts.
+- A live harness is refused (`E_SESSION_RUNNING`). A fallback shell or a dead
+  pane is reused in place; a missing window or a lost tmux server is recreated.
+- A state that cannot be established is refused (`E_SESSION_UNKNOWN`). Two
+  starts of one home serialize (`E_SESSION_START_BUSY`). A home being retired
+  is refused (`E_INSTANCE_RETIRING`).
+
+`session restart` takes the same flags. It sends SIGTERM to the harness and
+its children, waits `--stop-grace <seconds>` (default 20, at most 300), then
+starts in place. It never escalates: a harness still running is reported
+(`E_SESSION_STOP_FAILED`) and nothing is launched.
+
+### Stop
+
+`oats instance stop <instance> --plan` reports the session state, recorded
+children and uncommitted work, with a `planRevision`. `--apply --plan-revision
+<rev> --idempotency-key <key>` stops the instance and its recorded children
+first (`--no-recursive` stops only the instance), with the same bounded
+SIGTERM. Restart the instance later with `oats session start` or
+`oats session restart`.
+
+### Inspect, input and attach
 
 ```sh
-oats session attach --home /absolute/instance
-oats session inspect --home /absolute/instance --json
-oats session input --home /absolute/instance --text-file /path/to/message --json
-printf '%s' 'Check your pending work.' | oats session input --home /absolute/instance --json
-oats session start --home /absolute/instance [--model <id>] --json
+oats session inspect --home /abs/home --json
+oats session input --home /abs/home --text-file message.txt --json
+oats session attach --home /abs/home
 ```
 
-`start` runs a STOPPED instance again in its existing home: same identity,
-worktree, notes and launch environment, no spawn hooks, no new home. It reuses
-the persisted launch command, on the recorded tmux session and socket or the
-recorded Herdr server, and records the new session target in the instance
-metadata and the independent lifecycle receipt (whose home and work
-fingerprints are untouched, so a later retire still preserves everything
-changed since the original spawn). `--model` replaces the recorded model for
-this and later starts by re-rendering the persisted command; a command shape
-OATS did not generate is refused rather than rewritten. A quarantined home or one whose self-retirement is in progress is refused (`E_INSTANCE_RETIRING`). A live harness is
-refused (`E_SESSION_RUNNING`); a fallback shell with no harness descendant
-and a dead pane restart in that exact pane, a missing window opens again, and
-a lost tmux server after a reboot is recreated on the recorded socket. A state
-that cannot be established refuses (`E_SESSION_UNKNOWN`). Every observation
-happens under a per-home guard, so two starts of one home serialize
-(`E_SESSION_START_BUSY`). Each launch retains `.oats-start-pending.json`
-with its target and unique id. The wrapper writes that id to
-`.oats-start-exited` only when the saved command returns. A shell without
-the matching exit marker is still starting and cannot be respawned by a
-second caller. This also covers shell-only harness initialization; it needs
-no background monitor. The next start reconciles the complete receipt before
-the ordinary metadata check: a
-target that is present is recorded and adopted; an exited target is reconciled
-before restarting, and an unobservable target or malformed receipt refuses
-and keeps the receipt. Recovery is idempotent for an already-recorded launch
-and never silently applies a new model to an
-already-running harness. A never-launched legacy Herdr home without a saved
-server endpoint requires that endpoint to be configured before it can start;
-it does not fall back to tmux.
-Directory-mode starts and restarts also authenticate the home and owned work
-root against the independent spawn receipt (mode, canonical home, device/inode
-identities). Checks run before resolving mutable home contents, after **each**
-launch hook/preparation and immediately before backend observations, stops,
-allocations and launch-state writes. A missing/file/symlink/exchanged root or
-mode disagreement fails with `E_WORK_INSPECTION_FAILED`; substituted targets
-are neither followed for launch nor removed for lock cleanup. Restore the
-original owned roots before retrying; pending receipts remain with them.
-These pathname checks are not OS-level exclusion against a concurrent hostile
-filesystem mutation between validation and use.
-
-Managed execution also records independent native transcript-location history;
-the recipe remains a template, not provenance.
-
-The start opens a new harness conversation on the instance's `TASK.md`; the
-instance resumes its work from its own `STATE.md`, as the knowledge protocol
-prescribes.
+- **inspect** reports `backend`, `present` and `state`: the Herdr agent state
+  when available, `unknown` for a live harness, `shell` for a fallback shell,
+  `stopped` for an absent or dead terminal, or `not-launched`. An unavailable
+  backend is an error (`E_SESSION_UNAVAILABLE`), never a stopped result.
+- **input** submits UTF-8 text (stdin or `--text-file`, at most 256 KiB, no
+  NUL) followed by Enter: bracketed paste in tmux, `pane run` in Herdr. The
+  text is never run by a shell. A fallback shell, a stopped session or a split
+  tmux window is refused. `submitted: true` means the terminal accepted the
+  text, not that the agent processed it. Wake schedules and messaging
+  capabilities use this command ([schedules.md](schedules.md)).
+- **attach** is interactive and takes no `--json`. It opens a Herdr terminal
+  viewer, or a temporary tmux session linked to the agent's window alone.
+  Closing the viewer leaves the agent running.
 
-`attach` is interactive and does not accept `--json`. It validates the saved
-endpoint on the execution host, then opens a Herdr terminal viewer or an
-isolated tmux session linked to that agent's window alone. Closing its terminal
-cleans the viewer without stopping the agent; retiring the agent ends the viewer
-instead of switching it to a sibling. This host-local command is also the
-remote Desktop attachment seam over an SSH PTY.
+### Attachments
 
-Input accepts UTF-8 text up to 256 KiB, with no NUL bytes. The CLI uses the
-independent lifecycle receipt and refuses metadata disagreement. Tmux uses
-literal bracketed paste followed by Enter. Herdr uses pane input followed by
-Enter. Neither path interprets message text as a shell command. A fallback
-shell or ambiguous split tmux window refuses automatic input.
+`oats session upload --file <local> --home <abs>` copies a file into
+`<home>/.oats-attachments/` (directory mode 0700, file mode 0600, `name-2` on
+collision, at most 64 MiB) and answers `{path, bytes, sha256}`. The caller
+gives `path` to the agent; nothing is typed into the session. Attachments are
+removed with the home.
 
-Success uses the existing envelope:
+## The task prompt
 
-```json
-{"schemaVersion":1,"ok":true,"result":{"home":"/absolute/instance","backend":"herdr","present":true,"state":"idle","submitted":true}}
-```
+Spawn writes `TASK.md` in the home: the instance's name, soul, home and work
+tree, followed by the `--task` or `--task-file` text, or a note to await
+instructions when no task is given. Every launch, including `session start`
+and `restart`, opens a new harness conversation on `TASK.md`. The instance
+resumes its work from its own state files, as its knowledge capability
+prescribes.
 
-Inspect omits `submitted`; optional backend identifiers describe the observed
-terminal. `state` is the Herdr agent state when available, `unknown` for a live
-unclassified harness, `shell` for a fallback shell, `stopped` for an absent/dead
-terminal, or `not-launched`. Errors use `ok:false,error:{code,message}` and a
-nonzero exit. An unavailable backend is an error, never a stopped result.
-Tmux receipts identify socket/session/window; automatic input requires one live
-pane in that exact window. Herdr additionally verifies the original terminal ID.
-The broker owns busy/approval policy and must not interpret `submitted` as
-processing acknowledgement.
+## Permissions (yolo)
 
-### Attachments
+Yolo is chosen per launch: `--yolo` / `--no-yolo` on `oats spawn`,
+`oats session start` and `oats session restart`, or the `yolo` field of a
+named launch configuration. The flag overrides the configuration. A soul never
+carries it. With no choice, a spawn keeps the harness's native policy, and a
+start keeps what the home recorded.
 
-A viewer that drops a file or pastes an image gives the agent a path, never
-terminal input. `oats session upload --file <local> --home <abs>` stores a
-copy as a private file under `<home>/.oats-attachments/` (directory 0700,
-file 0600, `name-2` on collision) and answers `{path, bytes, sha256}`; the
-caller pastes `path` into the still-live session itself. With `--server <id>`
-and `--instance <name>` (or `--home`), the same saved route as attach is
-resolved, the remote must list `session-upload` in both its `remote` and
-`features` probe arrays, and the bytes travel on ssh stdin into `oats session
-receive --home <abs> --name <file>` on the execution host. Each side holds
-the whole file in memory up to the 64 MiB kernel bound (this is a bounded
-transfer, not end-to-end streaming); the receiver reads stdin event-driven,
-refuses above the bound before writing, and allocates the destination
-exclusively (`name-2`, `name-3` when taken), so simultaneous uploads of one
-name never overwrite each other and a planted symlink is never followed. The
-attachments directory must be a real directory inside the home. The local
-side refuses the result unless the remote's size and sha256 equal the local
-file's. A remote file is never a local path over SSH. Attachments live and
-die with the home.
-
-Capability spawn hooks register a pending home before runtime allocation;
-inspection becomes available once its receipt is persisted. Retire hooks
-unregister after quiescence. The broker must tolerate this lifecycle order and
-missing homes, and persist pending hints until handled. Kernel session operations
-contain no aweb identity, credentials, stream or notification logic.
-
-The portable integration belongs to the official `oats.aweb` capability.
-The aweb development deployment currently selects its owned `aweb.identity`
-capability; that deployment-specific choice does not change the broker interface
-and needs equivalent registration glue when switched to session delivery.
-
-## Shared permission setting
-
-The opt-in is per launch: `oats spawn --yolo` / `--no-yolo`, the `yolo` of a
-named launch configuration (`oats launch-config set <name> --file <json>`),
-or the Desktop's per-launch choice. A soul does not carry it: `soul.yaml` has
-no `yolo`. With no setting, native policy is retained, and the spawn flag
-overrides any configured value.
-
-Launch configurations are host-level: `oats launch-config set` writes them to
-the `launch-configs:` block of the deployment's `oats-local.yaml`, the one
-place the kernel reads them from ([configuration.md](configuration.md)). A
-scope's `oats-config.yaml` declaring `launch-configs:` is refused with a message
-naming the move. The scope-level `yolo:` of `oats-config.yaml` is removed in
-0.26.0 with the config chain (lead decision c3-4): yolo is chosen only by
-`--yolo` / `--no-yolo` on `oats spawn`, `oats session start` and
-`oats session restart`, or by the `yolo` of a named launch configuration. It is
-not a soul field either (lead decision c3-q Q6): `soul.yaml` has no `yolo`.
-
-Autonomous or unattended execution is not permission to synthesize `yolo: true`.
-Explicit user CLI/UI input or a user-selected configuration is the opt-in; explicit
-`false` remains false.
-
-Only for an explicitly resolved true setting does OATS add Codex `--yolo` plus
-launch-local project trust, or Claude `--dangerously-skip-permissions`. `--no-yolo` removes the
-OATS-added bypass flags while native settings stay in force. Instance metadata
-records the resolved choice; this policy does not rewrite frozen recipes, live
-configuration or already-running sessions.
-
-Claude Code and Codex use their ordinary native context, skills, settings, plugins,
-profile and authentication. OATS still builds the complete ordinary instance home:
-resolved skills, capabilities and resources, canonical AGENTS plus its CLAUDE alias,
-task, metadata and normal work placement. Resolution, approvals and lifecycle hooks
-are not skipped; normal native launch is not an empty/no-capability mode. Only outside
-native context/skill coexistence is relaxed: OATS does not impose an OATS-only ambient
-view or route these runtimes through the Pi SDK. Pi's selected strict SDK profile is unchanged. OATS
-composition integrity/provenance, source/helper authority, record attribution and
-guards, and admission/retry obligations remain separate and required; normal native
-context alone is not a Claude/Codex qualification failure.
-
-Desktop remote terminal requests contain only the server id and instance name.
-The selected installed CLI resolves the saved route and performs remote
-inspection before attaching over SSH. Pending inspections share the terminal
-resource limit and duplicate requests share one inspection. Remote status and
-instance keys must include the server so identical paths on different hosts
-remain distinct.
-
-## Desktop remote roster and lifecycle
-
-Desktop uses the installed CLI's `server roster --json` feature when advertised.
-It refreshes one aggregate roster at a time, independently of terminal traffic;
-the CLI owns SSH deadlines, server registration and saved routes. Each target
-appears in the workspace selector with its souls and instances. An unreachable
-target stays visible with unknown runtime state and an error. A saved route
-remains visible after its registration is removed or changed.
-
-Choose the server workspace to spawn one of its souls. A successful launch
-switches to that workspace and opens the instance terminal once it appears in
-the roster. The instance action menu offers harvest and retirement, including
-for stopped agents. Remote harvest runs in the saved home on the execution host;
-retirement uses the same saved route and work-preservation rules as the CLI.
-Closing a viewer leaves the agent running.
-
-Desktop retirement requires the CLI's `retire-home` feature and always sends
-the exact selected home. The remote kernel must support that feature too;
-older kernels require an upgrade before the GUI can retire an instance.
-This keeps same-named instances distinct. Retirement feedback reports every
-preserved recovery path and its classes, including an incomplete cleanup.
-
-This first projection enables terminal and lifecycle actions only for remote
-instances with a route saved on this machine. Other observed instances are
-listed, but require the execution host's CLI to manage them. Remote brain files
-are accessed through the terminal. The roster and remote harvest require CLI
-feature tokens `roster` and `harvest`; the published 0.22.2 kernel has remote
-spawn, status, retirement and terminals, but not these two additions.
+When yolo is true, OATS adds `--dangerously-skip-permissions` for Claude Code,
+and `--yolo` plus trust for the instance home for Codex. pi takes no flag.
+`--no-yolo` removes only those added flags; native settings stay in force.
+Unattended execution never implies yolo.

package/docs/first-team.md

@@ -1,12 +1,8 @@
 # Run your first OATS team
 
-> **Workspace model (0.25).** This page is the v2 first-team guide. The 0.24
-> surface it used to describe (`oats-config.yaml`, `oats init` / `install` /
-> `use` / `trust`, the 0.24 `oats onboard --dir` bootstrap that created a local
-> `oats-setup-expert`) no longer exists; those verbs answer `E_UNKNOWN_COMMAND`
-> naming their replacement. Model: [workspaces.md](workspaces.md) ·
-> packages: [packages.md](packages.md) · the deployment layout this page
-> creates: [configuration.md](configuration.md).
+The model is in [workspaces.md](workspaces.md), packages in
+[packages.md](packages.md), and the deployment layout this page creates in
+[configuration.md](configuration.md).
 
 Start with one workspace, one member repository and one small, real task. A
 soul keeps the role and its curated skills; an instance gets a working session
@@ -31,9 +27,9 @@ node --version && tmux -V && oats version --json   # features must list workspac
 Three files, all committed ([workspaces.md](workspaces.md) shows each field):
 
 - `oats-workspace.yaml` (`schemaVersion: 2`) in **one** host repository: `name`,
-  `members: [<repo ref>, …]`, `teams:`, `packages: { oats.framework: v<x>, … }`,
+  `members: [<repo ref>, …]`, `teams:` (the shared teams), `packages: { oats.framework: v<x>, … }`,
   `defaults:`. A member is a repo ref, never a revision.
-- `oats-membership.yaml` (`{ schemaVersion: 2, workspace: <host ref>, team? }`)
+- `oats-membership.yaml` (`{ schemaVersion: 2, workspace: <host ref> }`)
   in **every** member — the backlink half of the handshake. A repo listed
   without a backlink is `no-backlink` and contributes nothing.
 - `souls/<name>/soul.yaml` (`schemaVersion: 2`) in the member that owns the
@@ -43,8 +39,9 @@ Three files, all committed ([workspaces.md](workspaces.md) shows each field):
 
 The smallest real setup is one repository that is host **and** member: it
 carries the workspace file, its own `oats-membership.yaml` pointing at itself,
-one soul and, optionally, one capability. Every soul gets `oats.core` from the
-`oats.framework` package by default.
+one soul and, optionally, one capability. Give every soul `oats.core` with
+`defaults: { capabilities: { oats.core: { from: package } } }` and an
+`oats.framework` pin.
 
 ## 2. Realize it on this machine — `oats onboard`
 
@@ -83,20 +80,37 @@ Host-owned provider values (absolute paths, state roots) go under `settings:` in
 `oats-local.yaml` afterwards — never in the workspace file, whose schema refuses
 them. Do not commit `oats-local.yaml`.
 
-## 3. Look before you spawn
+## 3. Give the deployment a team
+
+With a messaging capability in the soul's composition, every instance lives in
+a team, and readiness fails with `E_TEAM_UNCONFIGURED` until there is a
+default. Create the team with your messaging provider (its own docs say how;
+for `oats.aweb`, see its skills), then record it here:
+
+```bash
+oats teams add research --team <provider team id>   # a local team; the first one becomes the default
+oats teams                                           # shared and local teams, and the default
+```
+
+A team the whole workspace uses is committed as a **shared** team in
+`oats-workspace.yaml`; which souls join which team on this machine is
+`oats soul teams` ([workspaces.md](workspaces.md#teams)). Without messaging,
+skip this step.
+
+## 4. Look before you spawn
 
 ```bash
-oats souls                    # every non-private soul of every confirmed member, with origin and team
+oats souls                    # every soul of every confirmed member, with origin and its teams here
 oats capabilities             # member (origin: member <key> @ <commit>) and package (package <id> v<ver>) capabilities
 oats workspace status         # membership table, locked packages
-oats spawn backend-expert --preview   # modules[] with from/commit/changedSince, composed skill names, team
+oats spawn backend-expert --preview   # modules[] with from/commit/changedSince, composed skill names, teams + default
 ```
 
 The preview is where a skill-name clash between two composed capabilities
 (`E_SKILL_DUPLICATE`) or a package missing from the lock (`E_PACKAGE_MISSING`)
 shows up, before anything is created.
 
-## 4. Give an instance a real task
+## 5. Give an instance a real task
 
 ```bash
 oats spawn backend-expert --purpose first-fix --task "Fix one small issue, run the relevant checks, commit the code change, and report what changed."
@@ -116,7 +130,7 @@ Instance-specific provider values belong to the spawn:
 `oats spawn <soul> --provider <cap> key=value` (repeatable; dotted keys nest),
 recorded under `instance.json.providers.<cap>`.
 
-## 5. Judge and retire
+## 6. Judge and retire
 
 Review the instance's code through the repository's ordinary PR workflow. Then:
 
@@ -134,7 +148,7 @@ soul's `capabilities:`.
 ## The standalone case
 
 If you can read a member repository but not its workspace host (a public member
-of a privately hosted workspace — decision 26), point `oats-local.yaml` at the
+of a privately hosted workspace), point `oats-local.yaml` at the
 member: `oats sync` and `oats spawn` then give the **standalone view** — the
 repo's own souls with their `from: here` capabilities plus `oats.core`, marked
 `standalone: true` in `sync --json` and `instance.json.workspace.standalone`.