@awebai/oats 0.25.9 → 0.27.0

package/docs/souls-and-instances.md

@@ -40,7 +40,6 @@ name: release-manager                     # must equal the directory name
 description: Cuts, verifies and announces releases.
 work: worktree                            # worktree | checkout | directory | workspace
 team: engineering                         # optional label; else the repo's default (oats-membership.yaml); else unassigned
-private: true                             # optional: not discoverable; spawnable only from this repo
 
 capabilities:                             # WHERE each capability comes from — a location, never a version
   acme-release-tooling: { from: here }    # here = this soul's own repo
@@ -62,16 +61,19 @@ compatibility:                            # optional floors on PACKAGE versions
 | Key | Meaning |
 |---|---|
 | `name`, `description`, `work` | Required. `work` is the work mode below. |
-| `team` | A label declared in the workspace's `teams:`; may add `defaults.byTeam` capabilities. Never gates or restricts. |
-| `private` | `true` keeps the soul out of workspace discovery; its own repo can still spawn it. |
+| `team` | A label, or a list of labels (the first the primary), declared in the workspace's `teams:`; each may add `defaults.byTeam` capabilities and is an eligible messaging team. Never gates or restricts. |
+| `private` | **Ignored since 0.26.0:** souls have no private mode. Every soul of a confirmed member is listed and spawnable; a soul that still carries the field gets a `soul-private-ignored` warning. Remove it. |
 | `capabilities` | `<cap>: { from: here \| <repo key> \| package }` or `<cap>: off`. Composed over `defaults.<slot>` ⊕ `defaults.capabilities` ⊕ `defaults.byTeam[team]`; the soul wins. |
 | `knowledge` / `messaging` / `tasks` | The slot's provider payload (true of every instance of the soul), or `none`. Merged with `oats-local.yaml` `settings.<cap>` and `spawn --provider <cap>`; the provider's `binding` contract validates the result — and refuses keys it does not declare. For `oats.okf` 2.1.3 the admitted keys are its settings (`bindings-file`, `state-dir`, `harvest-runtime`, `harvest-model`); the soul's `owns`/`reads` live in `souls/<name>/okf.json`, which OKF reads from the soul directory. |
 | `compatibility` | `<cap>: <semver range>` checked against the locked package version (`E_COMPATIBILITY`). |
 
 Schema: [`soul.schema.json`](soul.schema.json). Not in v2: `kind`, `type`,
-`repo`, `runtime`, `model`, `requires`, `source:`, `stores.inherit`. Model and
-runtime are spawn-time / launch-configuration choices (`--runtime`, `--model`,
-`--launch-config`), not soul identity: a soul is model-agnostic as an artifact.
+`repo`, `harness`, `model`, `backend`, `yolo`, `launch-config`, `children`,
+`requires`, `source:`, `stores.inherit`. Runtime, model, backend, yolo and the
+launch configuration are spawn-time host choices (`--harness`, `--model`,
+`--backend`, `--yolo`, `--launch-config`, or a launch configuration in
+`oats-local.yaml`), not soul identity: a soul is model-agnostic as an artifact.
+A child-spawn policy is a spawn flag too (`--no-child-spawns`).
 
 A soul never runs by itself. It is incarnated as an instance. Editing a soul
 is a code change, reviewed in its repo.
@@ -84,9 +86,10 @@ souls — is ordinary capability content: **`oats.core`** (package
 `defaults.capabilities: { oats.core: { from: package } }`; a soul may say
 `oats.core: off`. **`oats.setup`** (same package) carries the whole-architecture
 knowledge an onboarding expert needs. Neither is kernel magic; the kernel still
-composes its own instance-boundary and work-mode briefings — and, when
-`oats.core` resolves as a module, leaves the "You run on OATS" briefing to the
-module's inject (one block, not two; 0.25.2).
+composes its own instance-boundary and work-mode briefings, and the "You run
+on OATS" briefing is `oats.core`'s inject (the kernel ships no copy since 0.26:
+a soul without `oats.core` gets no OATS operating instructions, and
+`oats doctor --soul` says so).
 
 ## Instance anatomy
 
@@ -102,7 +105,6 @@ full copy** of every capability the soul resolved to:
 
 ```text
 <agents-root>/<soul>/instances/<instance>/
-  soul → ../../soul                # the soul, for reference (read-only)
   AGENTS.md                        # generated: soul AGENTS.md + kernel/work-mode blocks + each module's inject
   CLAUDE.md → AGENTS.md
   .agents/skills/                  # canonical skill tree — soul skills + <capability>/<skill>/ full copies
@@ -111,7 +113,7 @@ full copy** of every capability the soul resolved to:
   .oats/modules/<capability>/      # the whole capability: oats.json, bin/, injects/, skills/ (hooks run from here)
   work/                            # worktree, checkout symlink, attached tree, or private directory
   TASK.md                          # briefing and task
-  instance.json                    # provenance (below)
+  instance.json                    # provenance (below); `soulDir` = the soul directory hooks get as OATS_SOUL
   STATE.md, log.md, notes/         # optional, from the knowledge capability
 ```
 
@@ -187,6 +189,11 @@ oats spawn release-manager --preview --json                        # decide ever
 oats spawn release-manager --provider oats.aweb identity.source=/abs/path/to/retained/.aw   # instance-level payload
 ```
 
+An instance is named `<soul>-<purpose>` by default, or exactly `--name <slug>`.
+Names are unique per deployment (a workspace-model deployment has one agents
+root): a derived name in use gets `-2`, `-3`…; an explicit `--name` in use is
+refused (`E_INSTANCE_NAME_TAKEN`).
+
 From a deployment (where `oats-local.yaml` is), a spawn: reads the local file →
 discovers the workspace over its remotes and confirms membership → finds the
 soul among the confirmed members (or `external:`; an ambiguous bare name is
@@ -194,7 +201,7 @@ soul among the confirmed members (or `external:`; an ambiguous bare name is
 `<agents-root>/<soul>/souls/<commit12>/` at its commit (the home links that
 directory; `<agents-root>/<soul>/soul` points at the current one) → resolves
 every capability by
-`from:` (member = latest, package = locked + approved) → creates the home →
+`from:` (member = latest, package = locked) → creates the home →
 **materializes each module whole** into `.oats/modules/` and copies its skills
 into `.agents/skills/` (a transaction: any failure leaves nothing behind) →
 composes `AGENTS.md` → records `modules`/`providers`/`workspace` in
@@ -282,9 +289,9 @@ an agent's environment variables — is operator-origin and appears top-level.
 Agents spawning sub-agents should pass `--parent "$OATS_INSTANCE"` (or the
 relation that fits).
 
-If the workspace has a messaging integration such as aweb, spawned instances
+If the workspace has a messaging capability such as aweb, spawned instances
 can also receive identities and coordinate with each other automatically. The
-task layer can provide shared work state while messaging provides conversation.
+tasks capability can provide shared work state while messaging provides conversation.
 
 ### Retire
 
@@ -296,13 +303,13 @@ evidence but never waits for a model or GitHub: independent processing and
 source-targeted inspection continue after the home disappears.
 
 `oats retire <instance> --self` lets an instance retire itself when the human
-or briefing says it is done. A live runtime cannot give a stable final
+or briefing says it is done. A live harness cannot give a stable final
 inspection of its own work, so the calling process inspects, runs, and removes
 nothing: it records the intent beside its home as
 `.oats-retire-pending-<instance>.json` and starts a detached completion, then returns so the instance can report final
 status before its tmux window dies a few seconds later. The completion then
 retires the instance exactly as an external `oats retire` would: quiesce the
-runtime, preserve uncommitted work, run retire hooks, repair lineage, remove
+harness, preserve uncommitted work, run retire hooks, repair lineage, remove
 the worktree and the home. Success leaves nothing behind: the home and the
 marker are gone. A failure writes `.oats-retired-<instance>.json` beside the
 retained home (plus the usual quarantine marker when hooks reported incomplete
@@ -316,7 +323,7 @@ follow. Every mode sits inside the same home/work boundary, which the generated
 instructions state first (`injects/instance-boundary.md`):
 
 - `<instance-home>` — the gitignored instance directory, `$OATS_INSTANCE_HOME` —
-  holds the brain (`AGENTS.md`, `soul/`), the task, the provenance
+  holds the brain (the composed `AGENTS.md`; there is no soul link), the task, the provenance
   (`instance.json`) and the episodic state (`STATE.md`, `log.md`, `notes/`), and
   is where OATS operational/lifecycle commands — and the commands of whatever
   capabilities are active, `aw` among them when aweb messaging is — are run,
@@ -325,9 +332,11 @@ instructions state first (`injects/instance-boundary.md`):
 - `<instance-home>/work` — the repository or workspace view — is where
   repository reading, editing, building, testing, git and commits happen, to the
   extent the mode below permits.
-- The home's `soul` link is to be treated as read-only: writes through it bypass
-  the branch and review path. Durable soul edits go through tracked paths under
-  `work/` under the applicable review rules. OKF v2 harvest edits external
+- The home has no soul link: the composed `AGENTS.md` already carries the
+  soul's instructions, and `instance.json` `soulDir` records the (read-only,
+  per-commit) soul directory every hook and dispatched command receives as
+  `OATS_SOUL`. Durable soul edits go through tracked paths under `work/` under
+  the applicable review rules. OKF v2 harvest edits external
   owned knowledge, not canonical soul files or skills.
 
 Agents move between the two as the task needs; the boundary is what each
@@ -390,7 +399,7 @@ directory; without it, the deployment directory (where `oats-local.yaml` is) is
 used. No implicit fallback changes the other modes.
 
 `--work-dir` and `--branch` are rejected. Canonical instructions, skill
-composition, provider trust and runtime preflight still apply. No worktree setup
+composition, provider trust and harness preflight still apply. No worktree setup
 runs. Retirement preserves nonempty work in verified recovery storage beside the
 home (`workRecovery.path/work`) before deleting it, including files created by
 hooks; directory work has no disposable-root exemptions. The work-root cannot be
@@ -460,7 +469,7 @@ they are stated separately:
   compatibility aliases for the separately published pi extension.
 - **Lifecycle hooks**: `OATS_INSTANCE_HOME` and `OATS_HOME`, alongside the rest of
   the hook contract. `OATS_HOME` predates `OATS_INSTANCE_HOME` and is kept because
-  shipped capability hooks read it; it is **not** exported to runtime sessions.
+  shipped capability hooks read it; it is **not** exported to harness sessions.
 
 Neither is `OATS_HOME_DIR`, which is the package store root — do not conflate
 them.
@@ -472,8 +481,7 @@ with **`E_NO_CANONICAL_ROOT`** and creates nothing.
 
 ### Deployment prerequisite: the agents directory must be operator-owned
 
-The canonical deployment (the agents root, `local-agents/`, and the instance
-homes under them) **must be owned by the operator and not writable by untrusted
+The canonical deployment (the agents root and the instance homes under it) **must be owned by the operator and not writable by untrusted
 users or processes.** OATS validates resolved destinations and re-checks the home
 immediately before creating anything in it, but it cannot defeat a concurrent
 local attacker who already has write access there: Node offers no
@@ -486,33 +494,38 @@ something the kernel can close from inside.
 Default layout:
 
 ```text
-<scope>/
-  agents/              # committed souls
-    docs-expert/
-      soul/
+<deployment>/
+  oats-local.yaml
+  agents/
+    docs-expert/         # a workspace soul, defined in a member repository's
+      souls/<commit12>/  #   souls/docs-expert/ and copied here per commit
       instances/
-  local-agents/        # local souls — same shape, never committed
-    scratch-agent/
-      soul/
+    memory-harvest/      # a capability-defined agent: only instances/, no soul
       instances/
 ```
 
-`local-agents/` sits BESIDE `agents/` at the scope level and holds **full local
-souls**: complete definitions with instructions, skills, capability declarations
-and instances, not committed to the repo. `oats create <name> --local` creates one — the directory
-is created on first use, and when the scope is a git repo the kernel adds
-`local-agents/` to its `.gitignore` automatically. A scope with only
-`local-agents/` is fully operable: people can use OATS with local agents alone.
-Ad hoc agents from `oats spawn --instructions-file`/`--def-file` land here too.
-Legacy nested `agents/local-agents/` and `agents/tmp-agents/` are still read
-for compatibility.
-
-Instances of a local soul receive a `local-soul` briefing: work and commits
-are normal, but soul updates are plain file edits (nothing to commit), and
-durability is the machine's — promote the soul to `agents/` when it starts to
-matter beyond one machine. That concerns soul artifacts, not a knowledge
-provider's custody: a local soul using OKF v2 still reads external bases and
-uses PR-only delivery for any Git base.
+A capability-defined agent (declared by a package or member module, such as
+the OKF harvester) homes under the agents root exactly like a soul; its
+directory holds only `instances/`. A name that is both a workspace soul and a
+capability agent is ambiguous (`E_SOUL_AMBIGUOUS`).
+
+There are no local souls. A soul is a member repository's `souls/<name>`
+(`soul.yaml` + `AGENTS.md`); author it there and run `oats sync`. OATS 0.25
+and earlier kept local souls and capability-agent homes under
+`<scope>/local-agents/`: this kernel never reads, spawns into or retires from
+that directory; it only detects it. Onboarding refuses into a directory that
+holds one, and `oats status` and `oats doctor` report it once, as the
+`legacy-local-agents` problem naming the instances found there; retire them
+with the 0.25 kernel, or delete the directory once they are stopped.
+
+A *captured home* (spawned through 0.24–0.25's captured path, removed in 0.26:
+its `instance.json` records `executionBinding`, `incarnationId` or `captured`) is
+reported by `oats status` and `oats doctor` as the `legacy-captured-home`
+problem. It has no 0.26 runtime: start, restart, inspect/readiness/operation
+`--home` and its in-home commands refuse it (`E_UNSUPPORTED_MODE`). `oats retire`
+still works; it warns once per capability whose retire hook did NOT run, since
+identities and memberships those capabilities created are not revoked — remove
+them with the provider's own tooling. Re-spawn the soul from the deployment.
 
 Alternative agents-root layouts are planned but not built. Today the default
 layout is the only implemented layout.

package/docs/workspaces.md

@@ -8,7 +8,6 @@ contracts the kernel is built against are in
 [design/2026-09-23-workspace-module-contracts.md](design/2026-09-23-workspace-module-contracts.md);
 a full worked example (an imaginary company with three teams) is in
 [design/2026-09-23-simplified-workspace-model.md](design/2026-09-23-simplified-workspace-model.md).
-Moving an existing 0.24.x deployment: [rebuild-to-v2.md](rebuild-to-v2.md).
 
 ## The rule
 
@@ -19,7 +18,7 @@ versioned.**
 | Source kind | `from:` | Versioned | Trust |
 |---|---|---|---|
 | Member repo | `<repo key>` or `here` | no — always the member's **latest** default-branch state | membership (the reciprocal handshake) |
-| Package | `package` | yes — the version pinned in the workspace's `packages:`; `oats-lock.json` records the exact commit + integrity | executables approved **once per version**, recorded in the lock |
+| Package | `package` | yes — the version pinned in the workspace's `packages:`; `oats-lock.json` records the exact commit + integrity | the declaration in `packages:` (no separate approval) |
 
 A soul names each capability **with where it comes from — a location, never a
 version**. The workspace's `packages:` says which version; materialization
@@ -39,8 +38,8 @@ machine (`oats-local.yaml`); the lock (`oats-lock.json`) sits beside
 `oats-local.yaml` and is identical on every machine that synced the same
 workspace commit. Schemas: [`oats-workspace.schema.json`](oats-workspace.schema.json),
 [`oats-membership.schema.json`](oats-membership.schema.json),
-[`soul.schema.json`](soul.schema.json), [`oats-local.schema.json`](oats-local.schema.json),
-[`oats-lock-v3.schema.json`](oats-lock-v3.schema.json). The JSON schemas encode
+[`soul.schema.json`](soul.schema.json), [`oats-local.schema.json`](oats-local.schema.json);
+the lock's format is in [packages](packages.md#lock-v3). The JSON schemas encode
 shapes; domain rules (declared teams, duplicate members, canonical `from:` keys,
 the two `packages:` value forms) live in the kernel's `validateWorkspace` /
 `validateSoul`, which are the authority.
@@ -61,7 +60,7 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
 
 packages:                                  # the ONLY versioned things
   oats.framework: v1.1.3                   # bare version → resolves through the official catalog
-  oats.okf: v2.1.4
+  oats.okf: v2.1.5
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 
 teams:                                     # labels, declared once so they cannot drift
@@ -141,8 +140,9 @@ declaration; it travels with the soul into the per-commit soul cache. The
 carry only the binding's settings keys (`bindings-file`, `state-dir`,
 `harvest-runtime`, `harvest-model`); `owns`/`reads`/`root` there are refused by
 the provider, not read (a soul payload grammar is an OKF follow-up). Every
-`souls/*/soul.yaml` in a member is discoverable; one that wants to stay
-internal says `private: true` (spawnable only from its own repo). A soul's
+`souls/*/soul.yaml` in a member is listed and spawnable — souls have no
+private mode (`private:` in a soul.yaml is ignored since 0.26.0, with a
+`soul-private-ignored` warning). A soul's
 `name` must equal its directory name; the first of two souls declaring one
 name (by path) is listed, the second is a problem.
 
@@ -151,7 +151,8 @@ name (by path) is listed, the second is a problem.
 The capability manifest is the one file that did not change (see
 [capabilities.md](capabilities.md)). Discovery relies on `capability` (the same
 `^[a-z0-9][a-z0-9._-]*$` grammar every `capabilities:` key uses), `version`,
-`layer`, and may read `private: true` and `team: <label>`. `version` is
+`layer`, and may read `private: true` (a **repo-owned** capability) and
+`team: <label>`. `version` is
 informational for member capabilities — a materialized copy is identified by
 its content digest.
 
@@ -188,7 +189,14 @@ with the right name, is not admission.
 model as a repo's committed `.agents/skills/`: whoever can push to the repo
 decides what runs, and the branch's latest state is what runs. No per-operator
 trust lists, no per-capability approval for members. Packages come from
-*outside* that boundary and keep a one-time executable approval per version.
+*outside* that boundary, and **declaring one in the workspace's `packages:` is
+the trust decision** (human decision, 2026-09-24): people install a package only
+when they trust it, so there is no second, per-version approval step. The lock
+is reproducibility, not approval — it pins the exact commit and content
+integrity, and `oats sync` refuses drift (a moved tag, changed content, an
+edited capability list). A spawn admits only a locked package the workspace
+**still declares**: one removed from `packages:` but left in a stale lock is
+`E_PACKAGE_MISSING { reason: "undeclared" }` until `oats sync` drops it.
 
 **The handshake is observed with the operator's own Git read access, in one
 access context.** The kernel reads both halves over the remotes
@@ -210,10 +218,11 @@ its capabilities unresolvable (`E_NOT_A_MEMBER` / `E_MEMBERSHIP_UNCONFIRMED`).
 Reading the workspace repo *is* being in the workspace — a workspace's access
 control is Git's.
 
-**Private items.** `private: true` on a soul or a capability keeps it out of the
-workspace listing; a private capability is usable only by souls of the same
-repo (`E_CAPABILITY_PRIVATE` otherwise). Owners still see their own private
-items.
+**Repo-owned capabilities.** `private: true` in a capability's `oats.json`
+makes it **repo-owned**: it is listed like any other capability (with
+`private: true`; the human table marks it "(repo-owned)"), and it is usable
+only by souls of the same repo (`E_CAPABILITY_PRIVATE` otherwise). Souls have
+no private mode: every soul of a confirmed member is listed and spawnable.
 
 **External souls.** `external:` adopts a soul by reference from a repo that is
 **not** a member, pinned to a full commit. No handshake is asked for and none is
@@ -226,7 +235,7 @@ its slots. An `external[].team` overrides the soul's own `team`.
 A repository may be a **member** (it completed the handshake; its `souls/*` and
 `capabilities/*` are member-tier: latest state, trusted by membership) **and** a
 **package publisher** (its `oats-package/` is consumed only through
-`packages:`: versioned, locked, approved). The two never collapse:
+`packages:`: versioned and locked). The two never collapse:
 
 - `from: <repo key>` looks **only** under `<repo>/capabilities/<name>/oats.json`
   at the member's latest state. It never looks inside `oats-package/`. A name
@@ -244,31 +253,32 @@ So the framework's own souls say `oats.okf: { from: package }` even though
 member soul that is the expert in that capability (`okf-expert`, `aweb-expert`,
 …), discoverable at latest state like any member soul.
 
-## Packages, lock, approval, catalog
+## Packages, lock, catalog
 
 `packages:` values have exactly two forms:
 
 - a **bare version** (`v2.1.3`, `2.1.3`, `v1.0.0-rc.1`) — resolved through the
   official catalog (`package-catalog.json` in the `oats` repo; the reviewed
-  marketplace, see [official-marketplace.md](official-marketplace.md)). This is
+  list, see [official-catalog.md](official-catalog.md)). This is
   the only way a package becomes *pinnable by id*.
 - **`git:<repo>@<ref>`** — a direct package ref: `<repo>` is any ref the kernel
   understands (`github.com/org/repo`, `https://…`, `git@host:…`, `/abs/bare.git`,
   `file:///…`), `<ref>` a tag name or a full commit OID. The package is read at
   `oats-package/` inside that repo.
 
-Both are packages: versioned, locked, approved. A ref that resolves to a
-**branch** is refused (`E_PACKAGE_INTEGRITY { why: "branch" }`) — versions are
-immutable. A tag that moved (same version string, different commit) fails
-integrity on the next `oats sync` and asks again.
-
-`oats sync` confirms membership, resolves every `packages:` entry to a commit +
-content digest, asks (on a terminal) for any missing per-version executable
-approval — or takes it from repeatable `--approve <id>@<version>` flags for
-unattended runs (each approves exactly the entry the resolution contains; the
-digest is always computed, never typed; Ctrl+D at the prompt is a decline,
-exit `2`) — writes `oats-lock.json` (lockfileVersion 3), creates `agents/` if
-absent and reports what changed. `oats package add <id> <version|git:…@…>` / `oats package remove <id>` edit
+Both are packages: versioned and locked. A ref that resolves to a **branch** is
+refused (`E_PACKAGE_INTEGRITY { why: "branch" }`) — versions are immutable. A
+tag that moved (same version string, different commit), or content that no
+longer matches the locked integrity, fails with `E_PACKAGE_INTEGRITY` on the
+next `oats sync`.
+
+**There is no package approval** (human decision, 2026-09-24). Declaring a
+package in `packages:` is the trust decision; `oats sync` asks nothing and
+`--approve` is `E_BAD_ARGS`. `oats sync` confirms membership, resolves every
+`packages:` entry to a commit + content digest, writes `oats-lock.json`
+(lockfileVersion 3), creates `agents/` if absent, reports what changed and
+exits `0`. A lock written by an earlier kernel may still carry an `approved`
+record per entry: it is ignored, and the next write drops it. `oats package add <id> <version|git:…@…>` / `oats package remove <id>` edit
 `packages:` in the workspace file when it is tracked by the current checkout,
 else print the line to add — the workspace file is shared through Git. Details:
 [packages.md](packages.md).
@@ -282,8 +292,8 @@ the workspace's slot default):
 
 ```
 from: package → some locked package provides `name`            else E_PACKAGE_MISSING (run `oats sync`)
-              → that package version is approved                 else E_PACKAGE_UNAPPROVED
-              → read its capability manifest at the locked commit; copy; record package/version/commit/digest
+              → read its manifests at the locked commit; the lock's capability list must match   else E_PACKAGE_INTEGRITY
+              → copy; record package/version/commit/digest
 from: <repo>  → <repo> is a CONFIRMED member                     else E_NOT_A_MEMBER / E_MEMBERSHIP_UNCONFIRMED
  (or `here`)  → it has capabilities/<name>/oats.json             else E_CAPABILITY_MISSING
               → not private, unless <repo> is the soul's own    else E_CAPABILITY_PRIVATE
@@ -308,13 +318,12 @@ Nothing is symlinked, nothing is shared between instances.
 ```
 <agents-root>/<soul>/instances/<instance>/
 ├── AGENTS.md                          # composed: soul AGENTS.md + kernel/work-mode blocks + each module's inject
-│                                      #   (with oats.core resolved, the module's "You run on OATS" block is the only one — the kernel's legacy copy is suppressed)
+│                                      #   (the "You run on OATS" block is oats.core's inject; the kernel ships no copy)
 ├── CLAUDE.md → AGENTS.md
 ├── .agents/skills/<capability>/<skill>/SKILL.md    # full copies; where pi/codex look
 ├── .claude/skills → ../.agents/skills
 ├── .oats/modules/<capability>/        # the full capability copy: oats.json, bin/, injects/, skills/
 ├── instance.json                      # modules{}, providers{}, workspace{} recorded here
-├── soul → <agents-root>/<soul>/soul   # read-only reference
 ├── TASK.md
 └── work/
 ```
@@ -347,10 +356,16 @@ not exclude anything.
 ## Teams
 
 `teams:` declares labels once (`global`, `engineering`, …) so they cannot drift
-into typos. A soul or capability carries `team:`, else its repo's default from
-`oats-membership.yaml`, else `unassigned`. A label not declared in `teams:` is
-`E_TEAM_UNKNOWN` (the item is still listed). `defaults.byTeam.<team>.capabilities`
-adds capabilities additively for souls with that label (`off` removes). **A
+into typos. A soul carries `team:` — one label or a list (`team: [engineering,
+reviewers]`, the first the primary) — else its repo's default from
+`oats-membership.yaml` (same shape), else `unassigned`; a capability carries one
+label. A label not declared in `teams:` is `E_TEAM_UNKNOWN` (the item is still
+listed); a declared label without a `messaging.byTeam` entry is the
+`unmapped-team-label` warning. `defaults.byTeam.<team>.capabilities` adds
+capabilities additively for souls with that label, for each label in order
+(`off` removes; two labels that disagree are `E_TEAM_CONFLICT`). Each label is
+an *eligible* messaging team the provider may join on request — see
+[capabilities.md](capabilities.md#several-team-labels). **A
 label never gates, restricts, changes trust or partitions the knowledge
 store** — it organises and can supply defaults. The messaging provider's payload
 (private teams, channels) lives under `messaging:`, so "team" means one thing.
@@ -364,9 +379,13 @@ store** — it organises and can supply defaults. The messaging provider's paylo
 | A fact about **this spawn** | `oats spawn … --provider <cap> key=value` (repeatable; dotted keys nest) → `instance.json.providers.<cap>` | `--provider oats.aweb identity.source=/abs/path/to/retained/.aw` |
 
 The merged payload is `workspace.messaging` (messaging slot only; its base
-keys ⊕ `byTeam[<soul's team>]`, with `byTeam` itself stripped) ⊕ soul slot
-payload ⊕ `local.settings[cap]` ⊕ `spawn.providers[cap]` — objects deep-merge,
-later wins on scalars and arrays. The provider's own `binding` contract
+keys, with `byTeam` stripped) ⊕ soul slot payload ⊕ `local.settings[cap]` ⊕
+`spawn.providers[cap]` — objects deep-merge, later wins on scalars and arrays.
+**No `byTeam[<label>]` is merged into it, the primary's included** (teams
+amendment K): each label's `base ⊕ byTeam[label]` reaches the provider only as
+that label's entry in `OATS_TEAMS` (the preview's `teams`). So `settings.team`
+(and `OATS_TEAM_ID`) is the personal team if the host, the soul or the spawn
+set one; empty means the provider's own default. The provider's own `binding` contract
 (`normalize → bind → check`) runs over the merged payload exactly as before.
 Two teams, two messaging identities, one workspace:
 
@@ -378,18 +397,21 @@ messaging:
     cloud: { team: aweb:example.cloud }
 ```
 
-A soul with `team: cloud` hands its messaging provider `{ team: aweb:example.cloud, … }`;
-a label under `byTeam` that is not declared in `teams:` is `E_WORKSPACE_SCHEMA`.
-**`byTeam` is kernel-merged; whether a provider honours what arrives is the
-provider's.** `spawn --preview` shows the merged `settings.<cap>` so the
-delivery is verifiable, and `instance.json.providers.<cap>` records it — but
-**oats.aweb 1.12.0 reads `team` from its payload** and mints into exactly that
-team (`--team-id`), warning when the payload disagrees with an `OATS_TEAM_*`
-value — so `byTeam.<label>.team` IS the per-label identity. What the payload
-does not change is **where the `.aw` root is found**: the hook still searches
-the bounded candidates in
-[rebuild-to-v2.md §8b](rebuild-to-v2.md#8b-where-the-team-aw-lives-now-and-what-byteam-does-today)
-and that root must hold a membership of the named team (the deployment's `.aw`
+A soul with `team: cloud` hands its messaging provider the eligible team
+`{ label: cloud, team: aweb:example.cloud, mapped: true, payload: { team: aweb:example.cloud, … } }`
+in `OATS_TEAMS`; its settings carry no `team` unless the host, soul or spawn set
+one. A label under `byTeam` that is not declared in `teams:` is
+`E_WORKSPACE_SCHEMA`. **Joining an eligible team is the provider's explicit
+act.** `spawn --preview` shows the merged `settings.<cap>` and the `teams`, so
+the delivery is verifiable, and `instance.json` records both. With oats.aweb
+1.13.1 (which reads `team` from its settings and ignores `OATS_TEAMS`) the
+primary identity therefore mints into the personal team: the `.aw` root's
+active team, or the one the host set. What the payload does not change is
+**where the `.aw` root is found**: the hook still searches
+bounded candidates, first hit wins — the instance home, the Git repository
+containing it, the soul's work repository and the Git repository containing
+it, then the deployment directory (`OATS_WORKSPACE`); never the user home or
+above the deployment — and that root must hold a membership of the named team (the deployment's `.aw`
 joined to every team its labels name is the simple layout). On oats.aweb
 1.11.2 `team` was ignored (the root's active team won), so `byTeam` there is
 a recorded intent only.
@@ -428,7 +450,7 @@ The deployment directory is **yours to choose** (decision 9) — an existing fol
 ```
 ~/acme/                           ← the directory you chose
 ├── oats-local.yaml               ← which workspace this machine realizes + host paths + disabled souls
-├── oats-lock.json                ← exact commit + integrity + per-version approval per package
+├── oats-lock.json                ← exact commit + integrity per package
 ├── agents/                       ← instance homes (each self-contained) + fetched soul sources
 ├── platform/                     ← clone of github.com/acme/platform (only if someone works IN it; may live elsewhere — see clones:)
 └── tools/
@@ -454,8 +476,8 @@ the host repo readable (it holds declarations, no secrets) or grant access.
 
 Two things keep the standalone spawn useful rather than hollow: `oats.core`
 (the framework's own operational package) is the kernel's default here as
-well, resolved from the official catalog through the operator's own lock and
-approved like any package (a soul may say `oats.core: off`); and the
+well, resolved from the official catalog through the operator's own lock like any
+package (a soul may say `oats.core: off`); and the
 operator's `oats-local.yaml` may name the repo directly (`workspace: <member
 ref>` — the kernel notices it is a member whose workspace it cannot read and
 falls back to the standalone view — or `standalone: <repo ref>` to ask for
@@ -467,8 +489,8 @@ an explicit `standalone:` header its next steps say so and name that one repo.
 member capability's hooks and command scripts run on every operator's machine at
 spawn, gated by nothing but the handshake. In a mixed public/private
 organisation keep **souls only** in public members and let executable
-capabilities come from packages (approved per version in the lock) or from
-private members.
+capabilities come from packages (declared in `packages:`, pinned by the lock)
+or from private members.
 
 **Hosting the workspace file when some members are private.** Everyone who
 can read the workspace file sees the member list. So: a public member never
@@ -502,12 +524,12 @@ installed-capability tier (`.agents/capabilities/installed/`) and
 `E_UNKNOWN_COMMAND` naming its replacement); per-soul `stores.<x>.inherit`;
 ambient-skill exclusion at launch. Lock v1/v2 files are `E_LOCK_SCHEMA`.
 There is no converter and no dual-schema reader: a 0.24.x kernel keeps
-spawning 0.24.x deployments; see [rebuild-to-v2.md](rebuild-to-v2.md).
+spawning 0.24.x deployments.
 
 ## Related
 
 - [Souls and instances](souls-and-instances.md) · [Packages](packages.md) ·
-  [Configuration (`oats-local.yaml`)](configuration.md) · [Rebuild guide](rebuild-to-v2.md)
+  [Configuration (`oats-local.yaml`)](configuration.md)
 - [Capability manifests](capabilities.md) · [Contracts](layers.md) ·
   [Desktop CLI API — workspace model](desktop-cli-api.md#workspace-model-workspaceapi-2)
 - [Design navigation](design/README.md)

package/injects/instance-boundary.md

@@ -1,7 +1,7 @@
 ## Your two directories
 
 **`<instance-home>` is where this session starts** — the specific gitignored OATS
-instance directory you woke up in, given to your runtime and to every lifecycle
+instance directory you woke up in, given to your harness and to every lifecycle
 hook as `$OATS_INSTANCE_HOME`. It is not your user home (`~`), not the repository
 root, and not the work tree. Anything that says "your home" means this directory.
 
@@ -20,7 +20,7 @@ root, and not the work tree. Anything that says "your home" means this directory
 - **Soul work is repository work.** If your TASK is to change soul content that
   lives in this repository, that is ordinary code work — do it on tracked paths
   under `work/`, reviewed like the rest. How your own learnings reach your soul
-  is your knowledge layer's business, and its instructions below say so if you
+  is your knowledge capability's business, and its instructions below say so if you
   have one.
 
 **`<instance-home>/work` is your repository or workspace view** — whatever your

package/injects/work-attached.md

@@ -8,7 +8,7 @@ their branch and their uncommitted state. You are a guest in their workspace.
 - Keep your changes and commits **small and clearly attributable** (your
   instance name in commit messages where ambiguity is possible).
 - Do not touch files the owner is mid-editing unless your task says so; when
-  in doubt, coordinate through your messaging layer or your spawner.
+  in doubt, coordinate through your messaging capability or your spawner.
 - Retiring you never removes the shared tree — cleanup of the tree is the
   owner's concern, not yours.
 

package/injects/work-workspace.md

@@ -6,8 +6,8 @@ cross-repo coordinator: your product is routing, analysis, and coordination —
 not code changes.
 
 - **Read freely across all member repos; never edit or commit inside them.**
-  Repo changes are routed to that repo's own agents (see `oats status --team`,
-  your task layer, or messaging) or to the human.
+  Repo changes are routed to that repo's own agents (see `oats status` in the
+  deployment, your tasks capability, or messaging) or to the human.
 - No git state operations in any member repo: no branch switching, no
   commits, no worktrees, no resets.
 - Your own working state lives in your instance home, not in any member repo,

package/lib/{portable-files.mjs → bounded-read.mjs}

@@ -1,4 +1,4 @@
-/** Bounded descriptor-backed reads shared by private portable metadata stores. */
+/** Bounded descriptor-backed reads of kernel-owned files (manifests, instance records). */
 import { constants, closeSync, fstatSync, lstatSync, openSync, readSync } from "node:fs";
 import { oatsError } from "./errors.mjs";
 
@@ -8,19 +8,19 @@ export function readPortableBytes(path, { missingCode = "resource-not-found", in
   catch (error) {
     if (error.code !== "ENOENT") throw error;
     if (allowMissing) return null;
-    throw oatsError(missingCode, "portable metadata is absent");
+    throw oatsError(missingCode, "metadata file is absent");
   }
-  if (!stat.isFile()) throw oatsError(invalidCode, "portable metadata must be a regular file");
-  if (stat.size > 8 * 1024 * 1024) throw oatsError("resource-limit", "portable metadata byte limit exceeded");
+  if (!stat.isFile()) throw oatsError(invalidCode, "metadata file must be a regular file");
+  if (stat.size > 8 * 1024 * 1024) throw oatsError("resource-limit", "metadata file byte limit exceeded");
   const fd = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
   try {
     const before = fstatSync(fd);
-    if (!before.isFile() || before.dev !== stat.dev || before.ino !== stat.ino || before.size !== stat.size) throw oatsError("integrity-drift", "portable metadata changed during opening");
+    if (!before.isFile() || before.dev !== stat.dev || before.ino !== stat.ino || before.size !== stat.size) throw oatsError("integrity-drift", "metadata file changed during opening");
     const buffer = Buffer.alloc(stat.size + 1);
     let count = 0, size;
     while (count < buffer.length && (size = readSync(fd, buffer, count, buffer.length - count, null)) > 0) count += size;
     const after = fstatSync(fd);
-    if (count !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) throw oatsError("integrity-drift", "portable metadata changed during reading");
+    if (count !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs) throw oatsError("integrity-drift", "metadata file changed during reading");
     return buffer.subarray(0, count);
   } finally { closeSync(fd); }
 }

package/lib/{portable-values.mjs → canonical-json.mjs}

@@ -1,5 +1,6 @@
-/** Bounded data codecs shared by portable declarations and retained records.
- * No source resolution, filesystem access, getters, or caller serialization hooks. */
+/** Bounded data codecs: strict JSON decoding and canonical JSON (config documents,
+ * instance records, provider answers). No source resolution, filesystem access,
+ * getters, or caller serialization hooks. */
 import { oatsError } from "./errors.mjs";
 
 const DEFAULTS = Object.freeze({ maxBytes: 8 * 1024 * 1024, maxDepth: 64, maxEntries: 100_000 });
@@ -39,16 +40,6 @@ export function decodeUtf8(input, where = "input") {
 }
 export const compareUtf8 = (a, b) => Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
 
-/** Freeze a bounded JSON observation, never caller accessors or cyclic objects. */
-export function freezeJson(value) {
-  canonicalJson(value);
-  const seen = new WeakSet();
-  const freeze = (item) => {
-    if (!item || typeof item !== "object" || seen.has(item)) return;
-    seen.add(item); for (const child of Object.values(item)) freeze(child); Object.freeze(item);
-  };
-  freeze(value); return value;
-}
 
 /** Canonical JSON includes exactly one final LF. Emit sorted keys directly:
  * JSON.stringify on a rebuilt object would reorder integer-looking keys. */