@awebai/oats 0.25.8 → 0.26.0

package/docs/desktop-instance-start.md

@@ -43,7 +43,7 @@ wrapper saves all of its in-flight conversation state. Wrappers should
 **Preview invocation** asks the execution host for the resolved command and
 displays it as text, with environment values redacted. It never launches an
 agent. **Manage launch configurations** in the dialog creates or updates named
-configurations at the displayed scope, including executable/wrapper, a JSON
+configurations in the deployment's `oats-local.yaml`, including executable/wrapper, a JSON
 argument list, environment references, model and permissions. Saving a
 configuration changes its definition; applying it to an existing home requires
 an explicit Start or Restart. When editing redacted environment values, keep

package/docs/desktop.md

@@ -85,20 +85,14 @@ The probe/mutation contract is specified in
 The app starts on the directory it was launched with (its own folder by
 default). To view a deployment, open the workspace switcher in the sidebar
 and choose **Add workspace → Browse**, then point it at an OATS deployment —
-a directory containing `agents/` (under the 0.25 workspace model that is the
-deployment directory (the operator's choice) holding `oats-local.yaml` and `agents/`;
-under 0.24, an `agents/` root, a `local-agents/` root for machine-local souls,
-or a team scope whose `oats-config.yaml` declares `team:`). *The Desktop's own
-multi-repo roster ("team scopes show every member repo's agents under one
-roster") still keys on the 0.24 `oats-config.yaml` `team:` declaration; reading
-the member set from `oats-local.yaml` / `oats workspace status` is the Phase F
-follow-up named in the [0.25.0 notes](release-notes/v0.25.0.md#desktop).*
+the directory (the operator's choice) holding `oats-local.yaml` and `agents/`.
+A picked folder without `oats-local.yaml` is offered onboarding instead. The
+Desktop never parses the deployment: its members, lock state and header come
+from `oats workspace status`, and its instances from the deployment's one
+`agents/` root. There is no team scope and no `oats-config.yaml`.
 Added workspaces are remembered and offered as suggestions next time.
 
-Local souls (uncommitted, machine-local agents under `local-agents/`) are
-first-class: they appear in the roster with a `local` chip, their brains
-and knowledge render, and they spawn like any other soul. Launch flags for
-scripted use: `--dir <workspace>` and `OATS_DESKTOP_PORT`.
+Launch flags for scripted use: `--dir <workspace>` and `OATS_DESKTOP_PORT`.
 
 ## Scheduling agents and wake messages
 
@@ -164,7 +158,7 @@ The full breaking-change list is in the
 | Terminals fail to open ("could not attach") | tmux missing, or no live session for that instance. Install tmux (`tmux -V`); check `tmux ls`. |
 | Can't select/copy text in a terminal tab | The terminal runs with tmux mouse handling, so a plain drag scrolls/passes through. Hold **Option** (macOS) or **Shift** while dragging to make a local selection, then copy (Cmd+C / right-click → Copy). |
 | macOS "app is damaged / can't be opened" | Ad-hoc-signed (not notarized) build + quarantine. Right-click → Open, or clear the quarantine attribute (above). If it persists, verify the bundle: `codesign --verify --deep --strict --verbose=2 "/Applications/OATS Desktop.app"` — a non-zero exit means a broken artifact, report it. |
-| Roster empty | The opened directory isn't an OATS workspace (needs `agents/` or `local-agents/`, or a team scope). Use the workspace switcher → Add workspace to select the right root. |
+| Roster empty | The opened directory isn't an OATS workspace (needs `agents/`, or a team scope). Use the workspace switcher → Add workspace to select the right root. |
 
 For bugs, attach the terminal output of the app (`OATS Desktop` prints
 server and CLI-discovery logs to stdout) and your platform/arch.

package/docs/execution-targets.md

@@ -160,9 +160,7 @@ These pathname checks are not OS-level exclusion against a concurrent hostile
 filesystem mutation between validation and use.
 
 Managed execution also records independent native transcript-location history;
-the recipe remains a template, not provenance. See
-[Native roots](design/package-runtime-api.md)
-for the exact source and standalone-fallback semantics.
+the recipe remains a template, not provenance.
 
 The start opens a new harness conversation on the instance's `TASK.md`; the
 instance resumes its work from its own `STATE.md`, as the knowledge protocol
@@ -231,21 +229,21 @@ and needs equivalent registration glue when switched to session delivery.
 
 ## Shared permission setting
 
-The opt-in is per launch or per soul: `oats spawn --yolo` / `--no-yolo`
-(`oats create` accepts the same flags), an optional `yolo` in `soul.yaml`
-(0.24 schema; the v2 `soul.yaml` schema does not carry it — use the spawn flag
-or a launch configuration), and the Desktop's per-launch choice. With no
-setting, native policy is retained.
-
-*0.24 classic deployments* may also set `yolo: true` in an `oats-config.yaml`
-to apply it to that scope; the closest scope wins, soul overrides scope, the
-spawn flag overrides both. *Under the workspace model* `oats-config.yaml` is
-not configuration ([configuration.md](configuration.md)); the kernel's
-`composeInstance` still consults the classic chain for the machine-level knobs
-`yolo` and `launch-configs` when such a file happens to sit above the
-deployment, but nothing writes one and the rebuild guide tells you to delete
-it — treat a scope-level `yolo` as a 0.24 feature and prefer the explicit
-spawn flag.
+The opt-in is per launch: `oats spawn --yolo` / `--no-yolo`, the `yolo` of a
+named launch configuration (`oats launch-config set <name> --file <json>`),
+or the Desktop's per-launch choice. A soul does not carry it: `soul.yaml` has
+no `yolo`. With no setting, native policy is retained, and the spawn flag
+overrides any configured value.
+
+Launch configurations are host-level: `oats launch-config set` writes them to
+the `launch-configs:` block of the deployment's `oats-local.yaml`, the one
+place the kernel reads them from ([configuration.md](configuration.md)). A
+scope's `oats-config.yaml` declaring `launch-configs:` is refused with a message
+naming the move. The scope-level `yolo:` of `oats-config.yaml` is removed in
+0.26.0 with the config chain (lead decision c3-4): yolo is chosen only by
+`--yolo` / `--no-yolo` on `oats spawn`, `oats session start` and
+`oats session restart`, or by the `yolo` of a named launch configuration. It is
+not a soul field either (lead decision c3-q Q6): `soul.yaml` has no `yolo`.
 
 Autonomous or unattended execution is not permission to synthesize `yolo: true`.
 Explicit user CLI/UI input or a user-selected configuration is the opt-in; explicit

package/docs/first-team.md

@@ -5,17 +5,15 @@
 > `use` / `trust`, the 0.24 `oats onboard --dir` bootstrap that created a local
 > `oats-setup-expert`) no longer exists; those verbs answer `E_UNKNOWN_COMMAND`
 > naming their replacement. Model: [workspaces.md](workspaces.md) ·
-> packages: [packages.md](packages.md) · moving a 0.24 deployment:
-> [rebuild-to-v2.md](rebuild-to-v2.md) (§5 is the deployment layout this page
-> creates). The [qualification example](first-team-demo.md) records real v1
-> tasks on 0.23 and is not v2 acceptance.
+> packages: [packages.md](packages.md) · the deployment layout this page
+> creates: [configuration.md](configuration.md).
 
 Start with one workspace, one member repository and one small, real task. A
 soul keeps the role and its curated skills; an instance gets a working session
 and a repository view; every capability the instance runs is copied whole into
 its home at spawn from a **member** repository (latest state, trusted by
-membership) or from a **package** (a pinned version, executables approved once
-per version in the lock). Nothing is installed.
+membership) or from a **package** (a pinned version, trusted by its
+declaration and locked to a commit and integrity). Nothing is installed.
 
 ## 0. Prerequisites
 
@@ -30,8 +28,7 @@ node --version && tmux -V && oats version --json   # features must list workspac
 
 ## 1. Declare the workspace (shared, in Git)
 
-Three files, all committed ([rebuild-to-v2.md](rebuild-to-v2.md) §§2–4 show
-each field):
+Three files, all committed ([workspaces.md](workspaces.md) shows each field):
 
 - `oats-workspace.yaml` (`schemaVersion: 2`) in **one** host repository: `name`,
   `members: [<repo ref>, …]`, `teams:`, `packages: { oats.framework: v<x>, … }`,
@@ -52,7 +49,7 @@ one soul and, optionally, one capability. Every soul gets `oats.core` from the
 ## 2. Realize it on this machine — `oats onboard`
 
 `oats onboard` is the bootstrap: it writes a minimal `oats-local.yaml`, creates
-`agents/` and runs the first `sync` ([rebuild-to-v2.md](rebuild-to-v2.md) §5 is
+`agents/` and runs the first `sync` ([configuration.md](configuration.md) is
 the resulting layout).
 
 ```bash
@@ -62,16 +59,16 @@ oats onboard ~/acme --workspace git:github.com/acme/agents     # any directory
 ```
 ~/acme/                           # the directory you chose; these three entries are what the kernel needs
 ├── oats-local.yaml               # { schemaVersion: 2, workspace: git:github.com/acme/agents }
-├── oats-lock.json                # lockfileVersion 3: commit + integrity + approval per package
+├── oats-lock.json                # lockfileVersion 3: commit + integrity per package
 ├── agents/                       # instance homes
 └── <member>/                     # clones of the members you work IN — here or anywhere named in oats-local.yaml clones:
 ```
 
 Read the report it prints: every member row must be `✓↔` (confirmed) — fix
-`no-backlink` / `backlink-elsewhere` / `cannot-read` before going on. If it
-exits `2`, a package needs executable approval: run `oats sync` in a terminal
-and answer `approve <id> <version>? [y/N]`. Approval is per package version,
-once, recorded in the lock; member capabilities need none. Then clone the
+`no-backlink` / `backlink-elsewhere` / `cannot-read` before going on. Every
+package in `packages:` is resolved, fetched, integrity-checked and locked; a
+package is trusted because the workspace declares it, so review what a package
+runs before adding its pin. Then clone the
 member you will work in beside `oats-local.yaml` (only a soul's work target
 needs a clone — discovery and resolution run over the remotes).
 
@@ -91,13 +88,13 @@ them. Do not commit `oats-local.yaml`.
 ```bash
 oats souls                    # every non-private soul of every confirmed member, with origin and team
 oats capabilities             # member (origin: member <key> @ <commit>) and package (package <id> v<ver>) capabilities
-oats workspace status         # membership table, packages, approval state
+oats workspace status         # membership table, locked packages
 oats spawn backend-expert --preview   # modules[] with from/commit/changedSince, composed skill names, team
 ```
 
 The preview is where a skill-name clash between two composed capabilities
-(`E_SKILL_DUPLICATE`) or an unapproved package (`E_PACKAGE_UNAPPROVED`) shows
-up, before anything is created.
+(`E_SKILL_DUPLICATE`) or a package missing from the lock (`E_PACKAGE_MISSING`)
+shows up, before anything is created.
 
 ## 4. Give an instance a real task
 

package/docs/implementation.md

@@ -3,7 +3,7 @@
 The reference implementation publishes two npm packages:
 
 - **`@awebai/oats`**: runtime-neutral kernel, universal `oats` CLI,
-  bootstrap skills, instruction sources, and the official capability marketplace.
+  bootstrap skills, instruction sources, and the official package catalog.
 - **`@awebai/oats-pi`**: minimal pi adapter for instance-local resource
   exposure and memory session events. It registers no agent tools.
 
@@ -18,7 +18,7 @@ own Claude configuration is deliberately left enabled.
 |---|---|
 | `lib/core.mjs` | Souls, instances, config/target resolver, capability discovery, composition, locks/trust, hooks. |
 | `bin/oats.mjs` | Agent lifecycle, config, acquisition/trust/activation, doctor, and operational command dispatch. |
-| `capabilities/` | Bundled additive packages and layer integrations, each with `oats.json`. |
+| `capabilities/` | Bundled package copies — core capabilities and others — each with `oats.json`. |
 | `skills/` | Kernel/bootstrap and package-authoring skills. |
 | `injects/` | Kernel and work-mode instruction sources. |
 | `packages/pi/` | Thin pi adapter. |
@@ -49,7 +49,6 @@ and the `oats.web` browser panel were retired in its favor.)
     CLAUDE.md -> AGENTS.md
     skills/                   # soul-private skills
   instances/<instance>/
-    soul -> ../../soul
     AGENTS.md                 # generated composition (regular file)
     CLAUDE.md -> AGENTS.md
     .agents/skills/           # exact materialized set
@@ -59,7 +58,7 @@ and the `oats.web` browser panel were retired in its favor.)
     instance.json             # capabilities, skills, instruction sources, lifecycle metadata
 ```
 
-Knowledge integration hooks may add memory files. The kernel does not assume
+The knowledge capability's hooks may add memory files. The kernel does not assume
 their names.
 
 ## Resolution
@@ -77,21 +76,10 @@ the slot). `lib/materialize.mjs` then copies every module whole into the home.
 The normative contract is
 [docs/design/2026-09-23-workspace-module-contracts.md](design/2026-09-23-workspace-module-contracts.md).
 
-**Classic 0.24 (superseded; still carried for homes without `oats-local.yaml`).**
-`configChain(context)` loads `oats-config.yaml` from closest scope outward.
-`resolveCapabilities(context, soulName)`:
-
-1. resolves explicit group definitions;
-2. collects matching global/group/soul bindings;
-3. composes settings by target specificity then config closeness;
-4. applies explicit enable/exclusion;
-5. validates equal-specificity conflicts, IDs, command namespaces, lock
-   integrity, and skill/layer collisions; and
-6. returns deterministic active capability records with provenance.
-
-`resolveOatsConfig` maps active packages declaring `layer` into the exclusive
-knowledge/messaging/tasks slots. `layers.<layer>: none` explicitly suppresses
-an inherited slot and remains distinct from absence.
+**Classic 0.24 (removed in 0.26.0).** The `oats-config.yaml` chain and its
+resolvers are gone. A legacy `oats-config.yaml` between the invocation
+directory and the deployment is refused with `E_CONFIG_BROKEN`
+(`reason: "legacy-config"`), and the message names the files that replace it.
 
 ## Spawn composition
 
@@ -130,9 +118,9 @@ work-mode block it frames: `<instance-home>` (`$OATS_INSTANCE_HOME`) holds the
 brain, task, provenance and working state, and is where OATS operational/lifecycle
 commands are run from — together with the commands of whatever capabilities are
 active, `aw` among them when aweb messaging is — since they resolve scope from
-the working directory (`--dir <path>` reaches another deliberately); the home's
-`soul` link is to be treated as read-only because writes through it bypass the
-branch and review path; and `<instance-home>/work` is the repository or workspace
+the working directory (`--dir <path>` reaches another deliberately); the home
+carries no soul link (the composed AGENTS.md holds the soul's instructions, and
+hooks receive the recorded soul directory as `OATS_SOUL`); and `<instance-home>/work` is the repository or workspace
 view where repository reading, editing, building, testing, git and commits
 happen. It bounds *repository* work rather than forbidding all output elsewhere —
 episodic state lives in the home, and a service agent's own artifacts (a report
@@ -198,11 +186,10 @@ The generated order is:
 
 1. canonical soul content;
 2. kernel OATS block;
-3. local-soul block (local souls only);
-4. **home/work boundary block** — runtime-neutral, every mode and every kind;
-5. actual spawn work-mode block;
-6. active capability blocks in resolver order; and
-7. unconditional config blocks outermost to innermost.
+3. **home/work boundary block** — runtime-neutral, every mode and every kind;
+4. actual spawn work-mode block;
+5. active capability blocks in resolver order; and
+6. unconditional config blocks outermost to innermost.
 
 Every generated block carries its source path. `oats doctor --soul <name>` uses
 the same composer and prints/returns the final text. Config-dependent prose is
@@ -214,40 +201,26 @@ never reconciled into committed souls.
 (`lib/packages.mjs#resolvePackages`) resolves every `packages:` entry of
 `oats-workspace.yaml` to a commit, computes the package tree's integrity and
 writes `oats-lock.json` **lockfileVersion 3** (`packages.<id>: { source, url,
-path, version, commit, integrity, capabilities[], approved }`). Executable
-approval is **per package version**, recorded in the lock as
-`approved: { executables: sha256-…, at }` after `oats sync` shows the
-executables and the operator says yes; a spawn of a soul using an unapproved
-package is `E_PACKAGE_UNAPPROVED`, and 0.25.1 re-verifies the approved digest
-against the package tree at the locked commit at every spawn. Member-tier
-capabilities need no approval: membership is the trust (decision 2). The
+path, version, commit, integrity, capabilities[] }`). A package is trusted by
+its declaration in `packages:` (human decision, 2026-09-24); member-tier
+capabilities are trusted by membership (decision 2). The lock is
+reproducibility: a moved tag or drifted content is `E_PACKAGE_INTEGRITY`, at
+spawn the lock's capability list must match what the package declares at the
+locked commit, and a spawn uses only packages the workspace still declares. The
 verbs `oats install|trust|list|restore|use|migrate` are removed
 (`E_UNKNOWN_COMMAND` naming the replacement).
 
-**Classic 0.24 (superseded).** External installation copies/clones one exact
-artifact and writes `oats-lock.json` with source, version/commit, and SHA-256
-tree integrity. An existing destination is never pulled silently. Resolution
-rejects changed locked artifacts and unlocked installed/path packages.
-
-Executable package hooks, commands, and launch-environment authority are omitted
-until `oats trust <id>` (0.24) marks the exact locked integrity approved.
-Bundled packages are framework-trusted.
-Packages under a scope's `owned/` subtree are config-owned. Anything under
-`installed/` requires a matching lock entry, so an acquired artifact cannot
-bypass executable trust by its directory location.
-
-Distribution packages generalize this: a package materializes each capability it
-exports into `.agents/capabilities/installed/<id>/`, each independently
-addressable and independently trusted at its own artifact integrity. There is no
-persistent package store. The 0.24 `lockfileVersion: 2` lock records package
-provenance (`packages`) and materialized capability identity (`capabilities`)
-separately. See `docs/design/package-engine-contract.md` for the resolver/lock
-API and error taxonomy.
+**Classic 0.24 (removed in 0.26).** The installed tier
+(`.agents/capabilities/installed/`, the `lockfileVersion: 2` lock, per-artifact
+approval) and its last writer went with the captured path; the
+[0.24 release notes](release-notes/v0.24.0.md) describe what it was.
 
 ## Hooks and scaffold ownership
 
-Only `soul-scaffold`, `spawn`, and `retire` manifest hooks are accepted.
-Spawn/scaffold use outer-scope then capability-ID order; retire reverses it.
+Only `soul-scaffold`, `spawn`, and `retire` manifest hooks are accepted. The
+kernel no longer runs `soul-scaffold`: it ran when `oats create` wrote a soul,
+and souls are now authored in member repositories.
+Spawn uses outer-scope then capability-ID order; retire reverses it.
 Each hook receives package identity/layer plus structured OATS environment and
 may emit a final JSON object containing `meta`, `brief`, `warning`, or `launch`.
 Only a spawn hook may add `env`; other lifecycle events reject it rather than
@@ -269,10 +242,6 @@ removes and verifies rollback-owned Git topology, and removes the home only
 when cleanup completed. Failed compensation or reported state with no retire
 hook uses the same retryable quarantine as every other incomplete spawn.
 
-Soul scaffolding snapshots files around each package hook and records new-file
-ownership in `.oats-scaffold-owners.json`. Overwriting canonical or another
-package's file restores the prior bytes and raises a conflict.
-
 ## Commands
 
 Kernel/package-management commands are always available. Operational

package/docs/integrations.md

@@ -83,7 +83,7 @@ directory delivery is recoverable and needs no Git/gh. Explicit bindings,
 `soul/okf.json` and accepted base metadata are required before a working source
 can spawn. `owns`/`reads` are responsibility/context, not ACLs. See
 [knowledge](knowledge.md) for the **prepared** version scope, provisioning and
-commands, and [migration](knowledge-migration.md) before updating v1.
+commands.
 
 **`oats.aweb`** fills `messaging`: mints an instance identity at spawn (local
 mode) or grants an instance an expiring session as a resident global identity
@@ -103,12 +103,14 @@ secrets never belong in OATS config. See
 > favor of the OATS Desktop app (`packages/desktop/`), which bundles the same
 > zero-dependency loopback server. If an `oats-workspace.yaml` (`packages:`,
 > `defaults.capabilities`) or a `soul.yaml` still names `oats.web`, remove that
-> entry and `oats sync`; on a 0.24 classic deployment, remove it from
-> `oats-lock.json` / `oats-config.yaml`. Full migration steps:
-> [desktop-succession](desktop-succession.md).
+> entry and `oats sync`.
 
 ## Building an integration
 
+A slot provider that declares `binding` answers `oats readiness` through its
+`binding.check` command; the request, environment and answer are specified in
+[capabilities.md](capabilities.md#readiness-check-bindingcheck).
+
 Building an integration is implementing a contract. The checklist per slot:
 
 **Any slot.** A namespaced capability manifest with exactly one `layer`; an
@@ -143,7 +145,7 @@ implementation. **This is a messaging-layer contract, not an oats.aweb
 detail** (decision 27): from kernel 0.25.6 the kernel copies it through as
 the principal the instance *acts as* — `oats status --json
 instances[].identity`, the roster's `identity:` line, `oats inspect --home …
-selected.identity` — preferring the capability whose captured layer is
+selected.identity` — preferring the capability whose recorded layer is
 `messaging`, adding `provider: <capability id>`, and never interpreting
 `grant`. The kernel offers no `--identity` flag: the choice travels as
 `--provider <cap> identity.mode=… identity.resident=…` and is bound by the
@@ -218,27 +220,64 @@ warning naming the fresh-purpose remedy. On an older `aw` the pre-1.36.1
 report stands (`aliasReusable: false`, warning naming aweb-abim), because
 that CLI cannot revoke the certificate.
 
-## oats.aweb settings (1.12.0)
+## oats.aweb settings (1.12.2)
 
-Set in `oats-local.yaml` under `settings.oats.aweb.<key>` (host-owned), in the
-soul's `messaging:` payload (true of every instance), or per spawn with
-`oats spawn … --provider oats.aweb <key>=<value>`. The effective payload is
-merged in order: workspace messaging, `byTeam[team]`, soul messaging,
-`oats-local.yaml` `settings.oats.aweb`, then per-spawn `--provider` values.
-`residents` is host-file-only: put custody paths only in `oats-local.yaml`,
-never in a committed workspace or soul file (current kernels document this rule
-but do not yet enforce provenance in the hook payload).
+Set portable team policy in the workspace/soul `messaging:` payload; set host
+facts in `oats-local.yaml` under `settings.oats.aweb.<key>`. Per-spawn
+`oats spawn … --provider oats.aweb <key>=<value>` is for non-host settings only.
+The effective payload is merged in order: workspace messaging, `byTeam[<primary label>]`,
+soul messaging, `oats-local.yaml` `settings.oats.aweb`, then per-spawn
+`--provider` values. `root`, `roots`, and `residents` are manifest-declared
+`hostOnly: true`: absolute root/custody paths are accepted only from
+`oats-local.yaml`; kernels since 0.25.6 refuse those keys in the workspace file,
+`byTeam`, soul payloads and `--provider` flags with `E_WORKSPACE_SCHEMA` reason
+`host-only-key`.
 
 - `team: <team id>`. The payload team wins over `OATS_TEAM_ID`/
   `OATS_TEAM_NAME`; if both are set and differ, the hook warns and uses the
   payload. Workspace v2 spawns can have an empty `OATS_TEAM_ID`, so set this in
-  the payload for global grants.
+  the workspace file's `messaging:` / `messaging.byTeam.<label>.team`, or in
+  `settings.oats.aweb.team` for a host override.
+- `root: /absolute/dir`. Host-owned absolute directory whose `.aw` is the aweb
+  minting root. A declared root without `.aw` is fatal; run `oats aweb setup`
+  there or set `settings.oats.aweb.root` to the initialized root.
+- `roots: { <team id>: /absolute/dir }`. Host-owned map for deployments that
+  mint into several aweb teams. When a team is known, `roots[team]` wins over
+  `root`.
+- Minting root resolution for spawn and setup is: `roots[team]` when the team is
+  known and present, else `root`. With no declared root, workspace v2 uses
+  `<OATS_WORKSPACE>` (the deployment directory whose `.aw` is used) and never
+  searches above it; classic deployments with `OATS_TEAM_SCOPE` keep the
+  historical bounded candidate search order exactly (team scope, home, home git
+  root, context, context git root, then workspace).
+- `binding-check` answers `needs-configuration` before spawn with one problem
+  per missing item: `no messaging root at <dir>: run oats aweb setup there or
+  set settings.oats.aweb.root`; `no team: set messaging.byTeam.<label>.team in
+  the workspace file or settings.oats.aweb.team`. With both present it answers
+  `ready`.
+  In classic deployments this readiness check approximates the full bounded
+  spawn search by checking `OATS_TEAM_SCOPE` before `OATS_WORKSPACE`; the spawn
+  hook itself still keeps the exact 1.12.0 bounded candidate order. With no
+  explicit team and no workspace team label, readiness follows spawn: an active
+  aweb team at the root is enough to answer ready; an unmapped workspace team
+  label still reports the team-setting remedy above.
+- `oats aweb setup` is idempotent and uses existing aw primitives. With
+  `--username <u>` it runs `aw init --username <u>` at the messaging root and
+  tells the operator to map the workspace team to `default:<u>.aweb.ai` when
+  that team is not already the configured target. With `AWEB_API_KEY` in the
+  environment it runs `aw init` at the root for the hosted team behind the key.
+  With `--invite <token>` it runs `aw team join <token>`. It never prints the
+  API key or invite token, re-reads `aw team list --json` after the action, and
+  prints the same ready/needs-configuration verdict as binding-check.
 - `identity.mode: local | global` (default `local`). Any other value is fatal.
   Local mode is the historical behavior: a spawned team identity is minted for
   the instance, or `identity.source` uses the existing retained-seat flow below.
   Its spawn meta includes `identity: { mode: "local", alias, team, address:
   null, resident: null }` beside the existing top-level `alias`, `team`, and
-  `delivery` keys.
+  `delivery` keys. Local-mode spawn output contributes
+  `env.AWEB_IDENTITY_HOME=<home>/.aw` (and retained-seat local mode contributes
+  the same path) so `aw mail`, `aw chat`, `aw whoami`, `aw wake`, and
+  `aw workspace status` work from the instance's `work/` or any other cwd.
 - `identity.mode: global` makes the instance act as a resident global identity
   through an aweb session grant; it never mints a new global identity and never
   copies root keys into the instance home. `identity.resident` is required and
@@ -247,24 +286,41 @@ but do not yet enforce provenance in the hook payload).
   the `oats-local.yaml settings.oats.aweb.residents.<name>` key to set. Optional
   `identity.scopes` defaults to exactly `[mail.read, mail.send, chat.read,
   chat.send]`; optional `identity.ttl` defaults to `8h` (aw accepts `60s` to
-  `720h`). Spawn runs `aw id grant mint --scope <comma-list> --ttl <ttl>
-  --label oats:<instance> --out <home>/.aweb-identity --json` from the custody
-  directory with `AWEB_IDENTITY_HOME` removed from the child environment: in aw
-  1.36.1, grant commands are not identity-home-aware and intentionally refuse
-  both `--identity-home` and external `AWEB_IDENTITY_HOME`, so cwd selects the
-  custody identity. The hook parses the whole JSON document because aw `--json`
-  output is indented across lines, with a fallback to the first brace-prefixed
-  block when progress lines precede it; it then verifies the minted grant's
-  `team_id` and returns
-  `env.AWEB_IDENTITY_HOME=<home>/.aweb-identity`. If the minted team differs,
-  the hook revokes the grant and keeps nothing. As of aw 1.36.1, receiving,
-  wake registration and `aw whoami` work through a grant, but sending mail or
-  chat through a grant is rejected by the server with 422 (`from_did must match
-  the authenticated sender`) because the aw client signs with the grant-key DID
-  where the server expects the resident's. Retire revokes
+  `720h`). Spawn first runs `aw custody status --json` in the resident custody
+  directory and uses exactly the reported `socket_path`; a status without a
+  socket is refused. It then runs `aw id grant mint --team <team-id> --scope
+  <comma-list> --ttl <ttl> --label oats:<instance> --out
+  <home>/.aweb-identity --custody-socket <preflight-socket> --json` from the
+  custody directory when aw is 1.36.2 or later for `--team`; grants need aw >=
+  1.36.3 (`CUSTODY_ATTACH_MIN`) with aweb server >= 1.27.5 for
+  `--custody-socket`. `AWEB_IDENTITY_HOME`
+  is removed from mint/revoke child environments: grant commands are not
+  identity-home-aware and intentionally refuse both `--identity-home` and
+  external `AWEB_IDENTITY_HOME`, so cwd selects the custody identity. The hook
+  parses the whole JSON document because aw `--json` output is indented across
+  lines, with a fallback to the first brace-prefixed block when progress lines
+  precede it; it then verifies the minted grant's `team_id`, reads back
+  `<grantHome>/grant.yaml` (not `encryption.yaml`) and requires
+  `custody.socket_path` to equal the preflight socket, and runs
+  `aw custody status --json` with `AWEB_IDENTITY_HOME=<grantHome>` from the grant
+  home to verify the resident alias and ready team row. Missing or mismatched
+  custody attachment revokes the grant, removes the grant home and fails the
+  spawn. It returns `env.AWEB_IDENTITY_HOME=<home>/.aweb-identity`. If the minted
+  team differs, the hook revokes the grant and keeps nothing. Receiving, wake registration,
+  and `aw whoami` work through a grant. On aw 1.36.1 the server rejected mail
+  or chat sent through a grant with 422 (`from_did must match the authenticated
+  sender`) because the client signed with the grant-key DID. aw 1.36.2 with
+  aweb server 1.27.5, the floor, fixes this; grant mail and chat sends passed
+  real-server acceptance there. A hosted team whose server has not yet adopted
+  1.27.5 still refuses grant sends; the custody preflight reports that as
+  needs-configuration before spawn through `grant_status_endpoint_ready`.
+  Retire revokes
   `meta.identity.grant.id` through the custody directory; with no grant id it
   reports `nothing-to-revoke`. A failed revoke exits nonzero and reports the TTL
-  expiry.
+  expiry. A binding-less home readiness check for global mode never reports ready
+  for a grant home whose `grant.yaml` lacks `custody.socket_path`; it reports
+  `needs-configuration` / code `custody` and tells the operator to retire and
+  respawn on an aw new enough to attach custody.
 - `residents: { <name>: /abs/custody/dir }` is the host-owned map for global
   mode. Each custody directory's `.aw` holds the resident identity root keys and
   team certificate. Do not put this map in committed source; the hook cannot

package/docs/knowledge-capability-authoring.md

@@ -58,7 +58,7 @@ v0.23.1 is published, an explicit initial Git acquisition at that tag selects
 the patch instead. It does not silently change the catalog's 1.0.0 selection
 or an existing lock. For local development, use an explicit complete source
 package path instead. Activation exposes the expert and targets
-the authoring skill, without selecting or replacing a knowledge integration.
+the authoring skill, without selecting or replacing a knowledge capability.
 There are no executable surfaces to trust in this package. Installed experts
 use their materialized local curriculum, not this repository at runtime.
 

package/docs/knowledge-reference/package-craft.md

@@ -19,7 +19,7 @@ A minimal distribution shape (replace example identities/descriptions):
 {
   "package": "example.knowledge",
   "version": "1.0.0",
-  "description": "Example knowledge integration.",
+  "description": "Example knowledge capability.",
   "compatibility": { "oats": ">=0.22.19" },
   "capabilities": ["capabilities/knowledge"]
 }
@@ -31,7 +31,7 @@ A knowledge implementation's capability manifest might begin:
 {
   "capability": "example.knowledge",
   "version": "1.0.0",
-  "description": "Native knowledge integration.",
+  "description": "Native knowledge capability.",
   "compatibility": { "oats": ">=0.22.19" },
   "layer": "knowledge",
   "skills": ["skills/native-reader", "skills/native-harvest"],
@@ -115,16 +115,18 @@ defaults:
 ```
 
 ```bash
-oats sync --dir /path/to/test-workspace      # resolve, lock, approve once
+oats sync --dir /path/to/test-workspace      # resolve, fetch, verify integrity, lock
 oats spawn <soul> --preview --json           # the module as it would be materialized
 ```
 
 These are illustrative user operations, not instructions to change a live
-deployment. The `oats`, `oats-config` and `oats-packages` kernel skills describe
-the installed kernel's operational commands. Installation exact-locks the
-package closure and activates nothing. Capabilities with executable commands or
-hooks require per-artifact trust before execution. A skills-only package needs
-lock integrity, not executable approval. Official catalog identity is not trust.
+deployment. The `oats.setup` capability's **oats-package-pins** skill describes
+the operational commands. Declaring the package in `packages:` is the trust
+decision: its commands and hooks run at spawn, so whoever adds the pin reviews
+them first. Syncing exact-locks the package (commit and integrity) and activates
+nothing; a soul receives a capability only when it or a workspace default
+selects it. Official catalog identity is a reviewed listing, not trust on the
+operator's behalf.
 Targets belong in config, not manifests. A manifest with `layer: knowledge`
 occupies that exclusive slot; an additive authoring aid must not replace it.
 

package/docs/knowledge-theory.md

@@ -279,7 +279,7 @@ The kernel supplies the common boundary; it must not contain one mandatory knowl
 |---|---|
 | Source, soul and instance identity | Knowledge organisation and destination semantics |
 | Configuration resolution and declared requirements | Storage, retrieval and reading context |
-| Selected resources and exact executable approval | Capture conventions and evidence selection |
+| Selected resources, exactly locked | Capture conventions and evidence selection |
 | Lifecycle/invocation context and provenance | Judgment, harvesting and maintenance where used |
 | Safe helper/job execution when required | Proposals, delivery, acceptance and recovery policies |
 | Retained-artifact integrity and truthful outcomes | Its complete runtime instructions, skills and tools |