@awebai/oats 0.25.9 → 0.26.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
@@ -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
@@ -136,14 +147,16 @@ A self-contained package has an `oats.json`:
   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,14 +184,72 @@ 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.
 
+### 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 runtime 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,6 +327,10 @@ 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
@@ -263,7 +339,7 @@ return `meta`, `brief`, `warning`, or runtime-specific `launch` arguments. A
 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,17 +361,19 @@ 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,
@@ -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",
@@ -170,7 +179,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 +256,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 +283,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:
+    runtime: 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): `runtime` (`pi` \| `claude` \| `codex`, required), `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

package/docs/conventions.md

@@ -6,8 +6,8 @@ instance-local views for deployment composition.
 ## Operating documents
 
 ```text
-soul/AGENTS.md                  # canonical role instructions
-soul/CLAUDE.md -> AGENTS.md
+souls/<name>/AGENTS.md          # canonical role instructions (in the member repo)
+souls/<name>/CLAUDE.md -> AGENTS.md
 instance/AGENTS.md              # generated regular file
 instance/CLAUDE.md -> AGENTS.md
 ```
@@ -66,35 +66,25 @@ where its owner keeps it and is copied whole into each instance at spawn:
 ```text
 <member repo>/capabilities/<name>/oats.json           # member-tier capability, latest state (membership is the trust)
 <package repo>/oats-package/oats-package.json         # package-tier: versioned via oats-workspace.yaml packages:
-<deployment>/oats-lock.json                           # lockfileVersion 3: package commit, integrity, per-version approval
+<deployment>/oats-lock.json                           # lockfileVersion 3: package commit and integrity
 <instance>/.oats/modules/<capability>/                # the copy this instance runs
 ```
 
-**Classic 0.24 layout** (still launched by the 0.24 kernel; a 0.25 kernel
-reads none of it as configuration — see [rebuild-to-v2.md](rebuild-to-v2.md)):
-
-```text
-<package>/capabilities/<name>/oats.json                 # the official marketplace (install source, not ambient)
-<level>/.agents/capabilities/installed/<name>/oats.json # acquired (gitignored, restorable)
-<level>/.agents/capabilities/owned/<name>/oats.json     # authored at this scope (source; committed where the scope is a repo)
-<level>/oats-lock.json                                  # lockfileVersion 2: external source/integrity/trust
-```
-
 ## Quick map
 
-| Thing | Canonical location (0.25 workspace model) | 0.24 classic |
-|---|---|---|
-| Shared declaration | `oats-workspace.yaml` in the host repo; `oats-membership.yaml` in every member | `oats-config.yaml` chain, `oats.yaml` |
-| Per-machine config | `<deployment>/oats-local.yaml` (uncommitted) | `oats-config.yaml` `settings:` |
-| Acquisition lock | `<deployment>/oats-lock.json` (v3) | `<level>/oats-lock.json` (v2) |
-| Soul source | `<member repo>/souls/<name>/` | `agents/<name>/soul/` |
-| Soul operating doc | `souls/<name>/AGENTS.md` | `soul/AGENTS.md` |
-| Soul Claude view | `souls/<name>/CLAUDE.md -> AGENTS.md` | `soul/CLAUDE.md -> AGENTS.md` |
-| Soul-private skills | `souls/<name>/skills/` | `soul/skills/` |
-| Instance operating doc | `instance/AGENTS.md` (generated) | same |
-| Instance skill set | `instance/.agents/skills/` | same |
-| Instance modules | `instance/.oats/modules/<capability>/` | `.agents/capabilities/installed/` (shared) |
-| Instance metadata | `instance/instance.json` (`modules{}`, `providers{}`, `workspace{}`) | `instance/instance.json` |
+| Thing | Canonical location |
+|---|---|
+| Shared declaration | `oats-workspace.yaml` in the host repo; `oats-membership.yaml` in every member |
+| Per-machine config | `<deployment>/oats-local.yaml` (uncommitted) |
+| Acquisition lock | `<deployment>/oats-lock.json` (v3) |
+| Soul source | `<member repo>/souls/<name>/` |
+| Soul operating doc | `souls/<name>/AGENTS.md` |
+| Soul Claude view | `souls/<name>/CLAUDE.md -> AGENTS.md` |
+| Soul-private skills | `souls/<name>/skills/` |
+| Instance operating doc | `instance/AGENTS.md` (generated) |
+| Instance skill set | `instance/.agents/skills/` |
+| Instance modules | `instance/.oats/modules/<capability>/` |
+| Instance metadata | `instance/instance.json` (`modules{}`, `providers{}`, `workspace{}`) |
 
 Symlinks prevent compatibility paths from drifting. Generated regular files
 separate canonical portable identity from scope-dependent runtime policy.

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

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

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

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

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

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

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

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

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

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