@awebai/oats 0.25.9 → 0.27.0

package/docs/capabilities.md

@@ -1,17 +1,19 @@
 # Capability packages
 
 A **capability** is OATS's reusable unit of behaviour. It can contribute
-skills, instance instructions, requirements, namespaced commands, and approved
+skills, instance instructions, requirements, namespaced commands, and declared
 lifecycle hooks. A soul — not the capability — decides which souls receive it,
 by naming it with where it comes from (`from:`; see [workspaces](workspaces.md)).
 
-The [official marketplace policy](official-marketplace.md) defines the reviewed
+The [official catalog policy](official-catalog.md) defines the reviewed
 package list and its acceptance criteria. Finding an official package does not
-pin, approve or give it to any soul; those remain explicit, separate choices.
+declare it or give it to any soul; declaring it in `packages:` is the
+workspace's trust decision, and giving it to a soul is a separate choice.
 
-An **integration** is a capability that implements one exclusive fundamental
-layer: `knowledge`, `messaging`, or `tasks`. General capabilities claim no
-layer and compose additively.
+A **core capability** fills one of the three positions a soul has: knowledge,
+messaging or tasks, at most one of each per soul. The manifest's `layer` field
+names which core capability it is. Other capabilities claim no `layer` and
+compose additively.
 
 ## Mental model
 
@@ -20,8 +22,8 @@ A capability lives in one of two kinds of source:
 1. a **member repo** of the workspace, at `capabilities/<name>/oats.json` —
    unversioned, always the member's latest state, trusted by membership;
 2. a **package** (`oats-package/` in a repo, pinned by version in the
-   workspace's `packages:`, locked and approved once per version —
-   [packages.md](packages.md)).
+   workspace's `packages:` — the declaration is the trust — and locked to a
+   commit and integrity; [packages.md](packages.md)).
 
 A soul says `capabilities: { <name>: { from: here | <repo key> | package } }`
 (or `off`); the workspace supplies defaults. At spawn every resolved
@@ -45,7 +47,7 @@ A self-contained package has an `oats.json`:
   "requires": [
     { "command": "team-chat", "why": "send and receive messages" },
     {
-      "runtime": "pi",
+      "harness": "pi",
       "package": "npm:team-chat-pi",
       "why": "real-time push events in pi sessions"
     }
@@ -67,8 +69,16 @@ A self-contained package has an `oats.json`:
   namespace.
 - `command` is an optional, unique CLI namespace. The example exposes
   `oats team-chat auth`.
-- `layer` is optional and may name exactly one fundamental layer. Two active
-  packages cannot implement the same layer for one soul.
+- `compatibility.oats` is the kernel range the capability runs on. The kernel
+  refuses to compose a capability whose range does not admit it
+  (`E_CAPABILITY_INCOMPATIBLE`, naming capability, range and kernel) wherever a
+  soul or capability agent resolves (spawn, `spawn --preview`, `inspect
+  --soul`, operator commands). `oats inspect` shows each module's
+  `compatibility: { ok, range, kernel }`; a home whose spawned module no longer
+  admits the running kernel reports a `capability-incompatible` problem.
+- `layer` is optional; when present it names which core capability this is
+  (`knowledge`, `messaging` or `tasks`). A soul has at most one capability per
+  slot.
 - `skills` entries can be skill directories or roots containing skills.
 - `inject` is optional instance instruction Markdown.
 - Only `soul-scaffold`, `spawn`, and `retire` hooks are accepted. A hook is a
@@ -79,15 +89,16 @@ A self-contained package has an `oats.json`:
   woken by mail. Every other hook stays best-effort and only warns, so advisory
   work never becomes a spawn blocker. `retire` and `soul-scaffold` cannot be
   required: they run outside a spawn transaction, so there is no moment to
-  enforce them.
+  enforce them. The kernel no longer runs `soul-scaffold` (it ran when
+  `oats create` wrote a soul); a manifest may still declare it.
 - A capability declaring a **required** spawn hook should declare a `retire` hook
   too. Without one, OATS has no way to undo what the spawn hook did and no way to
   know whether it did anything, so a failure quarantines the home rather than
   rolling it back — the operator cleans up by hand and removes it with `--force`.
-- A required hook must also be **able** to run: a package capability whose
-  version is not approved in the lock is refused at resolution
-  (`E_PACKAGE_UNAPPROVED`, remedy `oats sync`), so a required hook never
-  silently fails to configure an instance.
+- A required hook must also be **able** to run: a package capability the lock
+  does not pin is refused at resolution (`E_PACKAGE_MISSING`, remedy `oats
+  sync`), and drifted content is `E_PACKAGE_INTEGRITY`, so a required hook
+  never silently fails to configure an instance.
 - When a required hook fails and its compensation cannot finish, the instance
   home is **retained**, not deleted — it holds the credentials and metadata a
   retry needs, and removing it would turn a transient cleanup failure into
@@ -123,27 +134,29 @@ A self-contained package has an `oats.json`:
   the operator to clean up by hand.
 - `requires` declares what must exist before the capability works. Two kinds:
   - a **host command** (`command`), satisfied by a binary on `PATH`;
-  - a **runtime package** (`runtime` + `package`, optionally `marketplace`),
-    satisfied by that runtime's own package manager — `npm:@scope/name` for pi,
+  - a **harness package** (`harness` + `package`, optionally `marketplace`),
+    satisfied by that harness's own package manager — `npm:@scope/name` for pi,
     `plugin@marketplace` for Claude Code. It is raised only for deployments that use the named
-    runtime — a Claude-only deployment is never asked to install a pi package —
-    and is verified in the runtime's package list, never on `PATH`. A version
+    harness — a Claude-only deployment is never asked to install a pi package —
+    and is verified in the harness's package list, never on `PATH`. A version
     selector is allowed and ignored for identity, so `@latest` and a pinned
     version are one requirement.
-  A runtime package is **verified at spawn, never installed there**: installing
-  would mutate the operator's runtime configuration without asking, in the
+  A harness package is **verified at spawn, never installed there**: installing
+  would mutate the operator's harness configuration without asking, in the
   middle of a spawn. A missing, uninstalled or disabled package fails the spawn
   with the consent command that fixes it.
 - OATS never installs a host requirement silently. A missing host command is
   the operator's to install; `oats doctor` reports it. Consent to install is
-  separate from package approval.
-- `environment` lists the exact launch variables executable trust approves;
+  separate from declaring the package.
+- `environment` lists the exact launch variables the capability may set;
   spawn hook output must be a subset and use the capability vendor prefix.
 - Target names never appear in a package manifest.
 
 `capability` is the only manifest identity field; it may also carry
-`private: true` (usable only by souls of its own repo) and `team: <label>`
-(a workspace team label). The machine-readable contract is
+`private: true` (a **repo-owned** capability: listed, but usable only by souls
+of its own repo) and `team: <label>`
+(the one workspace team label it is listed under; without it, the primary of
+its repository's default). The machine-readable contract is
 [`capability-manifest.schema.json`](capability-manifest.schema.json).
 
 ## Who gets a capability
@@ -171,15 +184,73 @@ knowledge:
 ```
 
 Composition order: `defaults.<slot>` ⊕ `defaults.capabilities` ⊕
-`defaults.byTeam[<soul team>]` ⊕ `soul.capabilities` — later wins, `off`
-removes, a soul `<slot>: none` drops the workspace's slot default. A resolved
+`defaults.byTeam[<label>]` for each of the soul's team labels, in order ⊕
+`soul.capabilities` — later wins, `off` removes, a soul `<slot>: none` drops
+the workspace's slot default. Two labels that give one capability different
+entries are `E_TEAM_CONFLICT`, naming both labels; identical entries are fine,
+and a capability the soul names itself settles it (the soul's entry wins). A resolved
 capability whose manifest says `layer: X` fills slot X; two for one slot are
-`E_SLOT_CONFLICT`. Provider settings come from three homes — the soul's slot
-payload, `oats-local.yaml` `settings.<cap>`, and `oats spawn --provider` — and
-are deep-merged in that order. There are no agent types, no `global`, no
+`E_SLOT_CONFLICT`. Provider settings start from the manifest's own declared
+defaults (`settings.<key>.default`, the lowest layer), then take the workspace's
+`messaging` payload (its base: no `byTeam` entry is merged, per teams
+amendment K) for the messaging slot, the soul's
+slot payload, `oats-local.yaml` `settings.<cap>`, and `oats spawn --provider`,
+deep-merged in that order. There are no agent types, no `global`, no
 per-deployment activation or exclusion maps.
 
-## Exact runtime composition
+### Several team labels
+
+A soul's `team` (or its repository's default in `oats-membership.yaml`) is a
+label or a non-empty list of distinct labels; the first is the **primary**:
+
+```yaml
+# souls/release-manager/soul.yaml
+schemaVersion: 2
+name: release-manager
+description: Cuts and ships releases.
+work: worktree
+team: [engineering, reviewers]
+```
+
+- `OATS_TEAM_LABEL` is the primary label. The merged messaging payload takes
+  **no** label's `byTeam` entry, the primary's included (teams amendment K), so
+  `OATS_TEAM_ID` (the payload's `team`) is the personal team a host, soul or
+  spawn set; empty means the provider's default.
+- Every label is an **eligible team**: the kernel hands the messaging provider
+  `teams`, one `{ label, team, mapped, payload }` per label in order. `payload`
+  is `workspace.messaging` ⊕ `byTeam[<label>]` when the workspace maps the
+  label (`team` is then its team id), else the base alone with `mapped: false`
+  and `team: null`. A soul with no label gets `[]` (personal only).
+- `teams` travels **beside** a provider's settings, never inside them:
+  `OATS_TEAMS` (the JSON), `OATS_TEAM_LABELS` (comma-joined) and
+  `OATS_TEAMS_SOURCE` in the environment of every hook, home command and
+  provider check. The environment is their only channel: a check's stdin
+  request stays the released binding wire, which providers decode strictly.
+  The variables are empty (not `[]`) when a home's teams are unknown.
+- `OATS_TEAMS_SOURCE` is `live` (read from the workspace now, or a fresh
+  resolution) or `recorded` (the spawn-time list). **A provider leaves a joined
+  team only on a `live` list**: a recorded one lacks every team mapped since
+  the spawn, so acting on it could drop a valid membership.
+- Joining an eligible team is the provider's explicit act (a spawn choice or a
+  command at any time); the kernel never joins anything.
+- For an existing home the teams are **live** where they are acted on: its
+  launch hook (`oats session start|restart`), its messaging module's commands
+  and `messaging:` operations (`oats operation run --home`), and `oats inspect
+  --home` read the soul's labels and the workspace's `messaging` as they stand
+  now — two repository reads (the workspace host, the soul's own repo), never a
+  discovery; `oats readiness --home` takes them from the discovery it already
+  runs. The home's modules and skills stay as spawned. Every other capability
+  command and operation gets the teams the spawn recorded in `instance.json`
+  (`teams`), marked `recorded`, at no remote cost; so does any read where the
+  workspace cannot be reached.
+- **Known limitation (0.26.0):** a scheduled wake's session start uses the
+  recorded teams (`OATS_TEAMS_SOURCE=recorded`), so its launch hook leaves
+  nothing; the next operator start or messaging command is live.
+- A label in the workspace's `teams:` but not in `messaging.byTeam` is a
+  discovery warning (`unmapped-team-label`, one per label naming its souls); a
+  label not in `teams:` at all is the `E_TEAM_UNKNOWN` problem.
+
+## Exact harness composition
 
 Every spawned instance receives:
 
@@ -223,10 +294,10 @@ A **package** is the versioned tier: a directory with an `oats-package.json`
 that enumerates one or more capabilities (schema
 [`oats-package.schema.json`](oats-package.schema.json)). It is pinned once in
 the workspace's `packages:`, resolved to an exact commit + integrity by
-`oats sync` into `oats-lock.json` (lockfileVersion 3), and its executables are
-approved once per version. A soul names a package capability with
-`from: package`. Everything about declaring, syncing, locking, approving and
-publishing packages is in [packages.md](packages.md). There is no installed
+`oats sync` into `oats-lock.json` (lockfileVersion 3); declaring it is the
+workspace's decision to trust it. A soul names a package capability with
+`from: package`. Everything about declaring, syncing, locking and publishing
+packages is in [packages.md](packages.md). There is no installed
 copy at a deployment and no `oats install`/`trust`/`update`/`remove`.
 
 ## Member capabilities
@@ -236,8 +307,9 @@ by every soul in the workspace (`oats capabilities` lists it with origin
 `member <repo key> @ <commit>`) and is named with `from: <repo key>` — or
 `from: here` by souls of the same repo. It is trusted by **membership**: the
 repo's access control is the boundary and its latest default-branch state is
-what is copied. `private: true` in the manifest keeps it usable only from its
-own repo. A member's `oats-package/` is **not** a member capability: it is
+what is copied. `private: true` in the manifest makes it **repo-owned**: still
+listed (`private: true`, marked "(repo-owned)"), but usable only from its own
+repo (`E_CAPABILITY_PRIVATE` elsewhere). A member's `oats-package/` is **not** a member capability: it is
 reported as `publishes` and consumed only as a package.
 
 ## Capability-defined agents
@@ -255,15 +327,19 @@ instance's modules (or the soul's resolved set). Workspace commands (`sync`,
 `package`, `workspace status`, `capabilities`, `souls`, `doctor`) are always
 available.
 
+A manifest's `helperInjection` and a hook's `inputs` are **ignored since 0.26**:
+they served the captured path (removed in 0.26), are still accepted so that
+existing manifests load, and change nothing.
+
 Hooks receive `OATS_EVENT`, `OATS_CAPABILITY`, `OATS_LAYER`, `OATS_INSTANCE`,
 `OATS_HOME`, `OATS_AGENT`, `OATS_SOUL`, `OATS_CONTEXT`, `OATS_WORKSPACE`,
 `OATS_ROOT`, `OATS_LEVEL`, `OATS_SETTINGS`, and `OATS_META`. A final JSON line may
-return `meta`, `brief`, `warning`, or runtime-specific `launch` arguments. A
+return `meta`, `brief`, `warning`, or harness-specific `launch` arguments. A
 **spawn hook only** may also return an `env` object for the launched process;
 returning `env` from retire or soul-scaffold is an explicit contract error.
 
 A **launch hook** runs at every start and restart of a home for each provider
-captured at spawn (under its captured settings). Its `launch` arguments and
+recorded at spawn (under its recorded settings). Its `launch` arguments and
 `env` replace that provider's previous contribution whole. Its `meta`, when
 returned, replaces that provider's entry in `instance.json.capabilityMeta`
 after the start succeeds — the same record the spawn hook wrote and the retire
@@ -285,22 +361,24 @@ hyphen to `_` would let `aweb-evil.*` collide with names already inside
 A manifest's `settings.<key>` may carry `hostOnly: true` (decision 27). Such a
 key is a fact about the machine — a custody directory, a state root — and the
 resolver accepts it only from the deployment's own `oats-local.yaml`
-`settings.<capability>`; a committed workspace or soul file or a `--provider`
-flag carrying it is refused (`E_WORKSPACE_SCHEMA`, reason `host-only-key`).
+`settings.<capability>`; a committed workspace or soul file (every
+`messaging.byTeam` entry of a label the soul carries included) or a
+`--provider` flag carrying it is refused (`E_WORKSPACE_SCHEMA`, reason
+`host-only-key`).
 Declare it for any key whose value points at something a committed file must
 never be able to choose.
 
 A hook may return only names in its manifest's exact `environment` declaration.
 For package capabilities that declaration is part of the integrity-locked tree
-and of what the per-version approval showed; for member capabilities it is
-part of what membership trusts. Undeclared output is fatal. This positive
-authority is the contract boundary — adding a new launch variable requires a
-visible manifest change (and, for a package, a new approved version).
+the workspace declared; for member capabilities it is part of what membership
+trusts. Undeclared output is fatal. This positive authority is the contract
+boundary — adding a new launch variable requires a visible manifest change
+(and, for a package, a new version, reviewed as a new pin).
 
 `OATS_*`, `PI_AGENT_*`, kernel launch variables, and known shell/bootstrap/loader
 names are also rejected as defense in depth. The denylist includes current Node,
 JVM, .NET, Python, Perl, Ruby, Lua, PHP, ELF, and dyld surfaces, but is explicitly
-not the authority boundary: runtime bootstrap names are open-ended, so the
+not the authority boundary: harness bootstrap names are open-ended, so the
 manifest declaration and trust review enforce what an artifact may contribute.
 Two capabilities claiming the same name is an error even when their values
 match.
@@ -316,7 +394,7 @@ without a retire hook uses the standard retryable quarantine instead. Ordinary
 advisory hook execution failure itself contributes no environment.
 
 The environment prefix applies to the initial Pi or Claude process. `--no-launch`
-validates command preparation but has no runtime consumer. The fallback shell
+validates command preparation but launches no harness. The fallback shell
 after that process exits does not inherit command-scoped assignments, and OATS
 has no restart command or replay policy yet. The generated command is persisted
 as before; hooks must contribute locators, selectors, or broker endpoints—not
@@ -327,12 +405,9 @@ this mechanism must never copy or expose that global identity's root keys to the
 worker process. Session-scoped execution credentials need a separate lifecycle
 and must not be encoded into this persisted spawn command.
 
-Spawn/scaffold order is by capability name; retirement reverses successful
+Spawn order is by capability name; retirement reverses successful
 spawn order. Hooks run from the instance's own copy
-(`<home>/.oats/modules/<cap>/`). Scaffold hooks cannot modify or delete
-canonical or another capability's files. OATS records ownership, restores the
-pre-hook snapshot, and raises a conflict instead of accepting destructive or
-last-writer-wins behavior.
+(`<home>/.oats/modules/<cap>/`).
 
 ## Official packages
 
@@ -340,14 +415,14 @@ last-writer-wins behavior.
 |---|---|---|---|
 | `oats.core` | additive | day-to-day OATS operation for an instance | `oats.framework` |
 | `oats.setup` | additive | whole-architecture knowledge for an onboarding expert | `oats.framework` |
-| `oats.okf` | knowledge integration | External owned OKF bases, durable notes/record custody, independent judgment and inspection | `oats.okf` |
-| `oats.aweb` | messaging integration | aweb identity lifecycle and messaging skills | `oats.aweb` |
-| `oats.jira` | tasks integration | Jira task protocol via `acli` | `oats.jira` |
-| `oats.linear` | tasks integration | Linear GraphQL task commands and workflow | `oats.linear` |
+| `oats.okf` | knowledge core capability | External owned OKF bases, durable notes/record custody, independent judgment and inspection | `oats.okf` |
+| `oats.aweb` | messaging core capability | aweb identity lifecycle and messaging skills | `oats.aweb` |
+| `oats.jira` | tasks core capability | Jira task protocol via `acli` | `oats.jira` |
+| `oats.linear` | tasks core capability | Linear GraphQL task commands and workflow | `oats.linear` |
 | `oats.authoring` | additive | capability, skill, and soul authoring guidance | `oats.authoring` |
 
 Each is pinned by a bare version in `packages:` and resolved through the
-[official catalog](official-marketplace.md); each package repo is also a member
+[official catalog](official-catalog.md); each package repo is also a member
 of the OATS workspace carrying its expert soul (`okf-expert`, `aweb-expert`, …).
 The framework's own souls say `oats.okf: { from: package }` — membership never
 turns a package into a latest-state capability.
@@ -358,3 +433,99 @@ A manifest may declare `operations` (named actions or views delegating to
 its own commands) that a GUI or a schedule invokes through `oats operation
 run <layer>:<name>`; `oats inspect --json` reports them with availability.
 See [docs/design/operations-contract.md](design/operations-contract.md).
+
+## Readiness check (`binding.check`)
+
+A slot provider (knowledge, messaging, tasks) that declares `binding` in its
+manifest is asked by `oats readiness` whether it is ready for the subject. The
+subject is an instance home (`--home`) or a soul (`--soul`). The command named
+by `binding.check` receives one request and answers once. The kernel relays
+that answer to consumers as it came: readiness `providers` items. For the
+consumer side, see [desktop-cli-api.md](desktop-cli-api.md#oats-readiness---home---soul---dir---policy---json-readinessapi-2).
+This check reads configuration only; it binds nothing and does not change a
+spawn's fail-closed hooks.
+
+```json
+"commands": { "binding-check": "bin/my-provider.mjs binding-check" },
+"binding": { "version": 1, "normalize": "binding-normalize", "bind": "binding-bind", "check": "binding-check" }
+```
+
+**Invocation.** The kernel runs the command's script with `node`, from the
+module directory. That is the home's module copy for `--home`, or the
+deployment's verified module store for `--soul`. The script must resolve inside
+the module and be a regular file. The command's words after the script are
+passed as arguments; no shell is involved.
+
+**Request** — one JSON document on stdin:
+
+```json
+{"schemaVersion":1,"phase":"check","slot":"messaging","capability":"my.provider",
+ "settings":{"team":"acme:eng","root":"/srv/aw"},
+ "input":{"context":{"kind":"workspace","workspace":"github.com/acme/agents","deployment":"/srv/acme",
+                     "soul":"release-manager","team":"engineering","instance":"release-manager-1",
+                     "home":"/srv/acme/agents/release-manager/instances/release-manager-1"},
+          "action":{"kind":"readiness"}}}
+```
+
+- `slot` is the manifest's `layer`.
+- `settings` is the merged provider payload: the one the spawn recorded for a
+  home, or the one the resolution computes for a soul.
+- The request has exactly these keys; a provider may decode it strictly. The
+  soul's eligible teams (see *Several team labels*) are not on stdin: the check
+  reads them from `OATS_TEAMS` / `OATS_TEAMS_SOURCE` / `OATS_TEAM_LABELS`.
+- `context.team` is the soul's primary team label, or `null`.
+- `instance` and `home` are `null` for a soul subject.
+
+**Environment:**
+- Every ambient `OATS_*`, `OAS_*` and `PI_*` variable is removed. Other
+  variables pass through.
+- The kernel sets:
+  - `OATS_CAPABILITY` and `OATS_SETTINGS` (the payload as JSON);
+  - `OATS_CLI_BIN`;
+  - `OATS_WORKSPACE` (the deployment);
+  - the team variables `OATS_TEAM_ID` (the messaging payload's `team`: the
+    personal team if one is set; empty = the provider's default),
+    `OATS_TEAM_SCOPE`, `OATS_TEAM_LABEL`, `OATS_TEAM_NAME`,
+    `OATS_TEAM_LABELS`, `OATS_TEAMS`, `OATS_TEAMS_SOURCE`, `OATS_WORKSPACE_NAME` and
+    `OATS_WORKSPACE_KEY`;
+  - `OATS_AGENT` (the soul);
+  - `OATS_SOUL` when the soul directory is known;
+  - for a home, `OATS_INSTANCE` and `OATS_INSTANCE_HOME`.
+- A home's `OATS_WORKSPACE_NAME` is `""` until spawn records the workspace
+  name.
+
+**Answer** — exit 0, and exactly one JSON document on stdout (whitespace
+around it is fine; progress text is not):
+
+```json
+{"schemaVersion":1,"phase":"check","slot":"messaging","capability":"my.provider","ok":true,
+ "result":{"status":"ready","problems":[],"warnings":[{"code":"e2ee-disabled","message":"end-to-end encryption is off for this team"}]}}
+```
+
+- **The envelope** has exactly these keys. `schemaVersion`, `phase`, `slot`
+  and `capability` echo the request.
+- **A refusal** is `{…, "ok": false, "error": {"code", "message"?}}`.
+  Readiness shows it as `unknown`, with your code.
+- **`status`** is one of four values, and maps to the readiness item as
+  follows:
+
+  | `status` | readiness item | use it when |
+  |---|---|---|
+  | `ready` | `pass` | nothing is missing; `problems` must be `[]` |
+  | `needs-configuration` | `fail` | a setting or host resource is missing |
+  | `authorization-required` | `fail` | the operator must log in or grant access |
+  | `unavailable` | `unknown` | you cannot tell right now (a service is down) |
+
+- **`problems`** is a list of `{code, message}` strings. The codes are yours;
+  they are not matched against `binding.reasons`. The first message becomes
+  the item's reason.
+- **`warnings`** is optional: `{code, message}` strings, relayed as they come.
+  A warning never changes the status or the readiness summary.
+- **Anything else is `unknown`** (`provider-unavailable`): a nonzero exit, two
+  documents, unknown keys, a wrong echo, or `ready` with problems.
+
+**Time.** Each check gets at most 30 s and is killed after that. All provider
+checks in one readiness read share 60 s, and checks the budget does not reach
+are not run (`unknown`, `time-budget-exhausted`). Answer from configuration
+and local state. A provider that must call a remote service should bound that
+call well inside the 30 s.

package/docs/capability-manifest.schema.json

@@ -55,6 +55,15 @@
       "type": "string",
       "minLength": 1
     },
+    "private": {
+      "type": "boolean",
+      "description": "Workspace discovery: true makes this member capability repo-owned — listed (private: true) but usable only by souls of its own repository (E_CAPABILITY_PRIVATE elsewhere)."
+    },
+    "team": {
+      "type": "string",
+      "pattern": "^[a-z0-9][a-z0-9._-]*$",
+      "description": "Workspace discovery: the team label for this capability; else the repository's default from oats-membership.yaml."
+    },
     "layer": {
       "enum": [
         "knowledge",
@@ -108,17 +117,28 @@
             "additionalProperties": false
           },
           {
-            "title": "runtime package requirement",
-            "description": "A package that must be installed into a specific runtime's own package manager. Raised only for deployments using that runtime, satisfied by the runtime's package list rather than by PATH, and installed only with explicit consent.",
+            "title": "harness package requirement",
+            "description": "A package that must be installed into a specific harness's own package manager. Raised only for deployments using that harness, satisfied by the harness's package list rather than by PATH, and installed only with explicit consent. The harness is named by `harness` (0.27.0) or by `runtime`, its pre-0.27 name that released manifests use: exactly one of the two.",
             "type": "object",
             "required": [
-              "runtime",
               "package",
               "why"
             ],
+            "oneOf": [
+              { "required": ["harness"], "not": { "required": ["runtime"] } },
+              { "required": ["runtime"], "not": { "required": ["harness"] } }
+            ],
             "properties": {
+              "harness": {
+                "type": "string",
+                "enum": [
+                  "pi",
+                  "claude"
+                ]
+              },
               "runtime": {
                 "type": "string",
+                "description": "The pre-0.27 name of `harness`, accepted for released manifests.",
                 "enum": [
                   "pi",
                   "claude"
@@ -126,7 +146,7 @@
               },
               "package": {
                 "type": "string",
-                "description": "Source spec in that runtime's own naming: \"npm:@scope/name\" for pi, \"plugin@marketplace\" for Claude."
+                "description": "Source spec in that harness's own naming: \"npm:@scope/name\" for pi, \"plugin@marketplace\" for Claude."
               },
               "why": {
                 "type": "string"
@@ -146,7 +166,7 @@
               },
               "minVersion": {
                 "type": "string",
-                "description": "Lowest acceptable installed version of the package, read from the package.json under the install directory the runtime's listing names; an older or absent manifest fails the requirement with the install remedy.",
+                "description": "Lowest acceptable installed version of the package, read from the package.json under the install directory the harness's listing names; an older or absent manifest fails the requirement with the install remedy.",
                 "pattern": "^[0-9]+\\.[0-9]+\\.[0-9]+"
               },
               "ifInstalled": {
@@ -170,7 +190,7 @@
       }
     },
     "binding": {
-      "description": "Versioned provider-owned normalize/bind/check phases, each naming an existing command in this manifest. Runtime validation enforces fundamental-slot ownership and command references; presence is not approval or provider readiness.",
+      "description": "Versioned provider-owned normalize/bind/check phases, each naming an existing command in this manifest. Runtime validation enforces that the phases belong to a core capability (a manifest with `layer`) and command references; presence is not approval or provider readiness.",
       "type": "object",
       "required": ["version", "normalize", "bind", "check"],
       "additionalProperties": false,
@@ -247,11 +267,11 @@
       "items": {
         "type": "string"
       },
-      "description": "Package-relative soul directories (soul.yaml + AGENTS.md) \u2014 capability-defined agents; they resolve like local souls where the capability is active, souls stay read-only in the package, instances home under the scope's local-agents/."
+      "description": "Package-relative soul directories (soul.yaml + AGENTS.md) \u2014 capability-defined agents; they resolve where the capability is active, souls stay read-only in the package, instances home under <deployment>/agents/<agent>/instances/."
     },
     "settings": {
       "type": "object",
-      "description": "Declared capability settings: name to { default, values?, description }. Documentation for `oats use --settings`; undeclared settings are still accepted.",
+      "description": "Declared capability settings: name to { default, values?, description }. Documentation for the values a soul, oats-local.yaml or `oats spawn --provider` supplies; undeclared settings are still accepted.",
       "additionalProperties": {
         "type": "object",
         "properties": {
@@ -274,7 +294,7 @@
     },
     "environmentNamespaces": {
       "type": "array",
-      "description": "Additional environment-name prefixes this capability may declare besides its vendor's own (e.g. AWEB_ for the official oats.aweb integration). Each is an uppercase prefix ending in an underscore; the reserved core (OATS_, PI_AGENT_) and process bootstrap namespaces cannot be claimed. Disclosed at trust time with the environment list.",
+      "description": "Additional environment-name prefixes this capability may declare besides its vendor's own (e.g. AWEB_ for the official oats.aweb messaging capability). Each is an uppercase prefix ending in an underscore; the reserved core (OATS_, PI_AGENT_) and process bootstrap namespaces cannot be claimed. Disclosed at trust time with the environment list.",
       "items": {
         "type": "string",
         "pattern": "^[A-Z][A-Z0-9]*_$"

package/docs/configuration.md

@@ -13,7 +13,8 @@ derived from workspace defaults plus each soul's `capabilities:` — and its
 `souls:` blocks are gone — per-instance provider content moved to
 `oats spawn … --provider`. There is no `oats init`, no `oats use`, no config
 scope chain, no adopted config templates. A 0.24.x deployment is rebuilt, not
-converted: [rebuild-to-v2.md](rebuild-to-v2.md).
+converted: write `oats-local.yaml` with `oats onboard` and move what the old
+file declared into `oats-workspace.yaml` and each soul's `soul.yaml`.
 
 ## The file
 
@@ -33,6 +34,16 @@ settings:                                    # optional — host-owned values pe
 
 souls:                                       # optional — souls this machine does not run
   disabled: [data-analyst]
+
+launch-configs:                              # optional — named ways this host starts a harness
+  personal:
+    harness: claude
+    executable: "./bin/claude-wrapper.sh"    # relative → against this deployment directory
+    args: ["--verbose"]
+    env:
+      CLAUDE_CONFIG_DIR: { fromEnv: PERSONAL_CLAUDE_DIR }
+    model: opus
+    yolo: false
 ```
 
 Schema: [`oats-local.schema.json`](oats-local.schema.json). Unknown keys are
@@ -44,6 +55,7 @@ refused (`E_WORKSPACE_SCHEMA`).
 | `clones` | `<canonical repo key>: <absolute path>` — where a member's clone lives when it is not at `<deployment>/<member name>/`. Only a soul's **work target** (`work: worktree \| checkout`) needs a clone. Lookup order: `spawn --repo`, then this map (keys normalised through `parseRepoRef`, so any ref spelling of the same repo matches), then `<deployment>/<member name>` (a member named `agents` → `<deployment>/agents-repo`, since `agents/` is the instance root); none → `E_CLONE_MISSING`; a directory whose `origin` is another repo → `E_CLONE_MISMATCH`. |
 | `settings.<cap>.<key>` | Host-owned provider values the capability's manifest asks for — absolute paths, state roots, delivery modes. The workspace file **refuses** absolute paths; this is where they go. Merged into the capability's provider payload after the soul's own payload and before any `--provider` flag (see [three homes](workspaces.md#provider-payloads-have-three-homes)). |
 | `souls.disabled` | Soul names not run on this machine; reported by `oats sync` ("disabled here"). |
+| `launch-configs.<name>` | A named way to start a harness on this host (0.26.0; lead decision 2 — a spawn-time host choice, never a soul field): `harness` (`pi` \| `claude` \| `codex`, required; named `runtime` before 0.27.0, which is still read with a `deprecated-runtime-name` warning), `executable` (a bare name looked up on `PATH`, or a path — relative to this deployment directory), `args` (literal, no shell), `env` (a literal string, non-secret by contract and always redacted, or `{ fromEnv: NAME }` resolved on the host at start), `model`, `yolo`. Selected with `--launch-config <name>` on `oats spawn` and `oats session start \| restart`; explicit flags override its fields. Written by `oats launch-config set <name> --file <json>` / `remove <name>`, which rewrite only this block. Earlier kernels read `launch-configs:` from a scope's `oats-config.yaml`; 0.26.0 refuses it there with a message naming this move. |
 
 ## Where it sits and how it is found
 
@@ -76,8 +88,8 @@ nothing else.
   activation or targeting.
 - **Versions** — `packages:` in the workspace file; exact commits in
   `oats-lock.json`.
-- **Trust** — membership for members; per-version approval in the lock for
-  packages. No per-operator trust list.
+- **Trust** — membership for members; the declaration in the workspace's
+  `packages:` for packages (no approval step). No per-operator trust list.
 - **Per-instance provider facts** (a retained messaging seat, a one-off state
   root) — `oats spawn <soul> --provider <cap> key=value`, recorded in
   `instance.json.providers`.
@@ -86,8 +98,8 @@ nothing else.
 ## Inspecting the effective configuration
 
 ```bash
-oats workspace status          # membership table, locked packages, approval state, external souls
-oats sync                      # confirm, resolve, approve, report the diff
+oats workspace status          # membership table, locked packages, external souls
+oats sync                      # confirm, resolve, lock, report the diff
 oats capabilities | oats souls # everything a soul may name, with origin and team
 oats spawn <soul> --preview    # the exact modules (from/commit/changedSince), team, resolution revision
 oats doctor                    # this deployment's oats-local.yaml and lock, plus kernel diagnostics