@awebai/oats 0.24.13 → 0.25.1

package/docs/first-team.md

@@ -1,263 +1,146 @@
 # Run your first OATS team
 
-Start with one repository and one small, real task. A soul keeps the role and
-curated skills; an instance gets a working session and repository view. With OKF
-v2, expertise lives in external owned nodes, not the soul or task branch.
-
-> This guide targets the **v0.23.1 integration of published OKF 2.0.0**, whose
-> published kernel prerequisite is OATS >=0.23.0. Check the matching framework
-> release availability before installation; see [release notes](release-notes/v0.23.1.md).
-> The [qualification example](first-team-demo.md) records real **v1** tasks on
-> earlier versions, not v2 acceptance. Existing knowledge needs
-> [v1 preservation and cutover](knowledge-migration.md), not fresh initialization.
-
-## Install and choose a scope
-
-Install matching published kernel and Pi adapter releases. Have Node.js 22+, Git, tmux and an authenticated working runtime
-available. OKF's independent worker can use Pi, Claude or Codex; authenticate
-that selected runtime too. Plain-directory knowledge needs no Git/gh, although
-this guide's coding worktree does need Git.
+> **Workspace model (0.25).** This page is the v2 first-team guide. The 0.24
+> surface it used to describe (`oats-config.yaml`, `oats init` / `install` /
+> `use` / `trust`, the 0.24 `oats onboard --dir` bootstrap that created a local
+> `oats-setup-expert`) no longer exists; those verbs answer `E_UNKNOWN_COMMAND`
+> naming their replacement. Model: [workspaces.md](workspaces.md) ·
+> packages: [packages.md](packages.md) · 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.
+
+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.
+
+## 0. Prerequisites
+
+Node.js 22+, Git with read access to the repositories below (your own
+credential helpers; the kernel never prompts), tmux, and an authenticated
+harness (Pi, Claude or Codex).
 
 ```bash
 npm install -g @awebai/oats@latest
-pi install npm:@awebai/oats-pi@latest
-node --version
-tmux -V
-oats version
-cd /path/to/project
-oats init --raw
-oats install git:github.com/awebai/oats-okf@v2.0.0
-oats list
+node --version && tmux -V && oats version --json   # features must list workspace-v2
 ```
 
-Use a repository with an initial commit for this coding-worktree example.
-Raw initialization writes editable configuration with integrations disabled;
-installation separately acquires the published OKF 2.0.0 closure and exact lock.
-Neither step approves hooks, authenticates a runtime or joins a team. Inspect
-the acquired version before continuing. An existing development template or
-lock may still select v1: follow explicit preservation/update/cutover instead
-of applying fresh initialization or carrying v1 knowledge settings into v2.
-
-For several repositories initialize their common workspace, then select the
-repository owning the soul with `--dir /path/to/workspace/project` for
-create/spawn/retire. A team roster does not select a work repository for spawn.
-
-## Onboarding with the setup expert
-
-On **OATS 0.24.2 or later**, start in an explicit empty deployment:
-
-```bash
-oats onboard --dir /absolute/new-deployment --json
-```
-
-`oats onboard` ships from 0.24.2 (earlier kernels refuse it). It is a
-classic local bootstrap, not captured preparation or workspace enrollment. It
-acquires `oats.framework` from the official catalog, exact-locks its artifacts,
-selects only `oats.core` and `oats.setup` for the new local `oats-setup-expert`,
-and prints the exact next spawn command. Review and run the returned
-`result.next.command` when ready; it addresses this same kernel and deployment.
-Onboarding itself never launches a model, changes native authentication or
-installs capture hooks/services. **`oats setup` remains the separate record
-capture-setup command**, not an alias for onboarding.
-
-The expert receives `oats-operate`, `oats-souls`, `oats-config`, `oats-packages`
-and `oats-workspace-setup`, without duplicate legacy kernel skill copies. It has
-no hard knowledge/messaging dependency, so it can help select and configure those
-providers afterward. Catalog identity grants no executable trust: the bootstrap
-uses resource-only core/setup capabilities and refuses unexpected executable
-surfaces instead of auto-approving them.
+## 1. Declare the workspace (shared, in Git)
 
-An existing roster is refused unless `--force-existing` is explicit. That flag
-permits adding the new soul, not overwriting an existing setup expert or disabling
-providers for other souls. Failures report partial acquisition/creation rather
-than claiming atomic captured preparation. Preserve that evidence before retrying.
+Three files, all committed ([rebuild-to-v2.md](rebuild-to-v2.md) §§2–4 show
+each field):
 
-Optional `--workspace git:host/org/repository[@revision]` reads the selected
-repository through ordinary discovery: use its pinned `oats-setup-expert` import
-when present, otherwise its own advertised `souls/oats-setup-expert` edition at
-the observed revision. Missing or incompatible explicit sources refuse; they do
-not fall back to the packaged default. The copied edition's package must match
-the official acquisition; workspace policy, teams and provider adoption values
-are not silently adopted. Without this option, only the packaged definition and
-instruction text are used—no knowledge corpus is bundled. From 0.24.5, a
-`--workspace` onboarding also reads `package-catalog.json` **from the workspace
-repository at its observed revision** and acquires the `oats.framework` that
-catalog names; the kernel's bundled catalog is only the fallback (it is a
-snapshot at the kernel's own release and lags every framework release cut
-afterwards). `OATS_PACKAGE_CATALOG` still overrides both. The result reports
-`catalog.origin` (`workspace` | `bundled` | `override`), and an integrity
-refusal names the lag when the bundled entry caused it.
+- `oats-workspace.yaml` (`schemaVersion: 2`) in **one** host repository: `name`,
+  `members: [<repo ref>, …]`, `teams:`, `packages: { oats.framework: v<x>, … }`,
+  `defaults:`. A member is a repo ref, never a revision.
+- `oats-membership.yaml` (`{ schemaVersion: 2, workspace: <host ref>, team? }`)
+  in **every** member — the backlink half of the handshake. A repo listed
+  without a backlink is `no-backlink` and contributes nothing.
+- `souls/<name>/soul.yaml` (`schemaVersion: 2`) in the member that owns the
+  soul: `name`, `description`, `work: worktree|checkout|directory|workspace`,
+  and `capabilities: { <cap>: { from: here | <repo key> | package } | off }`.
+  A capability is a directory `capabilities/<cap>/oats.json` in a member.
 
-The manual path below retains its stated older integration/version scope.
+The smallest real setup is one repository that is host **and** member: it
+carries the workspace file, its own `oats-membership.yaml` pointing at itself,
+one soul and, optionally, one capability. Every soul gets `oats.core` from the
+`oats.framework` package by default.
 
-## Configure explicit knowledge and optional messaging
+## 2. Realize it on this machine — `oats onboard`
 
-Edit the existing entries in `oats-config.yaml`; do not append a second
-`capabilities` map. This example targets only the source soul for knowledge:
-
-```yaml
-agent-types:
-  developers:
-    description: Coding experts
-capabilities:
-  layers:
-    knowledge:
-      capability: oats.okf
-      from: installed
-      souls:
-        backend-expert:
-          enabled: true
-          settings:
-            bindings-file: /absolute/config/okf-bindings.json
-            harvest-runtime: pi
-    messaging: none
-    tasks: none
-```
-
-There is no hardcoded required harvester model in v2: omitted `harvest-model`
-uses the selected runtime's configured default. Choose a model explicitly if
-needed. Source and worker runtimes are independent.
-
-Review the acquired Git payload and approve executable surfaces:
+`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
+the resulting layout).
 
 ```bash
-oats trust oats.okf
+oats onboard ~/acme-workspace --workspace git:github.com/acme/agents
 ```
 
-Use the catalog Git package, not the bundled npm mirror: npm omits the source
-worker's `CLAUDE.md` symlink, so the mirror is not a self-contained distribution.
-Acquisition alone is not activation or trust.
-
-Messaging is optional. If desired, retain/configure the template's `oats.aweb`
-layer, set `team.name` and any existing `team.id`, then review/trust it and run
-`oats aweb setup`. Follow its install, initialization and create/join instructions
-until it confirms membership. Join an existing team rather than duplicating it;
-setup's exit status alone does not establish onboarding completion. A source-only
-knowledge target does not require the service worker to have a messaging identity.
-
-## Create the soul and provision an external base
-
-```bash
-oats create backend-expert --type developers --repo . --work worktree --runtime pi
 ```
-
-Edit `agents/backend-expert/soul/AGENTS.md` for the role and required checks.
-V2 does not scaffold knowledge in the soul. For a small local first base, create
-`/absolute/config/okf-bindings.json`:
-
-```json
-{"version":1,"stateDir":"../durable-okf-state","bases":{"team":{"id":"team-knowledge","kind":"directory","path":"../team-knowledge"}}}
+~/acme-workspace/                 # the taught "<name>-workspace" convention
+├── oats-local.yaml               # { schemaVersion: 2, workspace: git:github.com/acme/agents }
+├── oats-lock.json                # lockfileVersion 3: commit + integrity + approval per package
+├── agents/                       # instance homes
+└── <member>/                     # clones of the members you work IN (printed as next steps)
 ```
 
-Those paths resolve from `/absolute/config`, not the project. Choose durable,
-physical paths outside the source home/worktree and **outside every Git working
-tree**, including ignored directories. State, accepted bases and bindings must
-not overlap. Review [full placement rules](knowledge.md#bindings-document).
+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
+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).
 
-Create `/absolute/config/team-nodes.json`:
+`--json` returns `onboardApi: 2` (`local`, `dir`, `agents`, `lock`, the full
+`sync` report, `hosting`, `next.clone[]`, `next.spawn`); running it twice is
+`E_ALREADY_ONBOARDED` (use `oats sync`); a mistyped ref is `E_REPO_REF`, an
+unreadable one `E_REMOTE_UNREADABLE` with `details.rolledBack: true` — nothing
+half-written is left behind. Exact shapes:
+[desktop-cli-api.md](desktop-cli-api.md#oats-onboard-onboardapi-2).
 
-```json
-{"backend":{"path":"backend","owner":"backend-expert-stable-id"}}
-```
+Host-owned provider values (absolute paths, state roots) go under `settings:` in
+`oats-local.yaml` afterwards — never in the workspace file, whose schema refuses
+them. Do not commit `oats-local.yaml`.
 
-Explicitly provision the new base, refusing any existing destination:
+## 3. Look before you spawn
 
 ```bash
-oats okf init --base team --nodes /absolute/config/team-nodes.json --confirm --soul backend-expert --json
+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 spawn backend-expert --preview   # modules[] with from/commit/changedSince, composed skill names, team
 ```
 
-Write `agents/backend-expert/soul/okf.json`:
+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.
 
-```json
-{"version":1,"owner":"backend-expert-stable-id","owns":["team/backend"],"reads":[]}
-```
-
-For team-shared Git knowledge instead, follow [Git provisioning](knowledge.md#owner-and-base-descriptors)
-and review/merge its initialization PR before spawning. Git knowledge always
-uses PR delivery, not commits on the coding instance's branch.
-
-Review and commit soul/configuration/lock changes, generated ignore rules and
-the adopted template base under `.agents/config-templates/adopted/`. Keep
-credentials and private durable evidence out of Git. Check `oats doctor --soul
-backend-expert --json`. Configuration and a successful doctor do not substitute
-for accepted-base validation by the required spawn hook.
-
-## Give an instance a real task
+## 4. Give an instance a real task
 
 ```bash
-oats spawn backend-expert --purpose first-fix --task "Fix one small issue, run the relevant checks, commit the code change, and report what changed. Read the relevant accepted knowledge indexes and capture non-obvious lessons in notes."
-oats status --team
+oats spawn backend-expert --purpose first-fix --task "Fix one small issue, run the relevant checks, commit the code change, and report what changed."
+oats status
 ```
 
-Choose `--runtime claude` or `codex` if preferred. Complete any native folder
-trust, authentication or messaging-plugin confirmations in the printed session.
-A created window is not proof the agent is working.
+`--runtime pi|claude|codex` picks the harness; complete any native folder
+trust or authentication prompt in the printed session. The instance home is
+`agents/<soul>/instances/<instance>/`; `work/` is its repository view;
+`.oats/modules/<cap>/` and `.agents/skills/<cap>/` are the copied capabilities;
+`instance.json` records `modules` (from, commit, digest), `providers` and
+`workspace`. A running instance never changes under itself — a member that
+moves affects only new spawns, and `oats status` shows the drift
+(`member moved since (now @ …)` / `capability no longer present`).
 
-The instance home is under `agents/<soul>/instances/<instance>/`; `work/` is its
-Git worktree. `knowledge/view.json` identifies immutable accepted snapshots.
-The worker reads indexes selectively, maintains state/log/notes, and never edits
-accepted knowledge. This is instructional, not an OS filesystem sandbox.
-Review its code commits through the repository's ordinary PR workflow.
+Instance-specific provider values belong to the spawn:
+`oats spawn <soul> --provider <cap> key=value` (repeatable; dotted keys nest),
+recorded under `instance.json.providers.<cap>`.
 
-## Inspect, judge and retire
+## 5. Judge and retire
 
-From the source home, read-only inspection shows identity-matching state/log/notes
-plus durable processing receipts:
-
-```bash
-oats okf inspect --json
-```
-
-Spawn registered one per-source command job, but **did not install a host timer**.
-For this first task an operator may request one manual harvest from the source
-home; without `--no-launch` this starts the configured model worker:
-
-```bash
-oats okf harvest --json
-```
-
-The worker judges durable notes **and captured record**, in its own directory
-execution space. It leaves live notes and soul skills untouched. Directory
-delivery is recoverable publication with validation and receipts. Git delivery
-requires a real reviewed PR and merge-visible acceptance. Inspect receipts rather
-than equating a worker spawn with learning. See [operator commands](knowledge.md#inspection-and-operator-commands)
-for scaffold-only requests, completion and retry.
-
-Source retirement need not wait for a worker to finish: it must first certify
-final notes/record custody. From the repository scope:
+Review the instance's code through the repository's ordinary PR workflow. Then:
 
 ```bash
 oats retire backend-expert-first-fix
-oats status --team
-```
-
-Read the retirement result. An uncertified capture retains the home for retry;
-never delete it to bypass recovery. Durable descriptors, evidence and runs survive
-successful retirement. Use `oats okf inspect --source <absolute-source.json>
---soul backend-expert --json` from deployment context afterward. If messaging is
-active, also verify its retirement receipt and roster rather than assuming local
-cleanup proves identity release.
-
-For automatic future judgment, review [source jobs](schedules.md#okf-v2-source-jobs)
-and explicitly opt into host-timer installation. No-launch tests should never
-install it or enable live model launches.
-
-After provider acceptance, start a fresh instance of the same soul on a useful
-task. Check that it finds **and uses** the promoted lesson without the original
-source. That is the learning acceptance step; a no-launch reader only verifies
-scaffolding and references.
-
-## Optional host-wide conversation capture
-
-Knowledge judgment and the native conversation record are separate. OKF uses
-source-targeted native capture through the CLI; host-wide watcher/hook setup is
-an additional deliberate operator action:
-
-```bash
-oats setup
-oats capture --status
-oats recall "a phrase from your completed task"
+oats status
 ```
 
-Capture respects privacy exclusions. Native turns are content-addressed; signed
-aweb messages retain their source signatures. See [where the turn record fits](2026-09-03-architecture-proposal.md#where-the-turn-record-fits).
+Read the retirement result rather than assuming local cleanup proves release;
+knowledge and messaging capabilities (packages such as `oats.okf`, `oats.aweb`)
+add their own retire hooks and receipts — see [knowledge.md](knowledge.md) and
+[capabilities.md](capabilities.md) once you add them to `packages:` and to the
+soul's `capabilities:`.
+
+## The standalone case
+
+If you can read a member repository but not its workspace host (a public member
+of a privately hosted workspace — decision 26), point `oats-local.yaml` at the
+member: `oats sync` and `oats spawn` then give the **standalone view** — the
+repo's own souls with their `from: here` capabilities plus `oats.core`, marked
+`standalone: true` in `sync --json` and `instance.json.workspace.standalone`.
+A repository with no `oats-membership.yaml` is not a member and gets no such
+view (`E_WORKSPACE_SCHEMA`); a network failure reading the host is
+`E_REMOTE_UNREADABLE`, never a silent standalone.

package/docs/implementation.md

@@ -26,10 +26,12 @@ own Claude configuration is deliberately left enabled.
 | `test/` | Capability resolver/composition/security lifecycle tests. |
 | `agents/` | The framework's own portable expert souls. |
 
-Capability discovery has one layout: each config scope's `.agents/capabilities/` split into
-`installed/` (acquired, locked, gitignored, restorable via bare `oats install`)
-and `owned/` (authored at that scope, config-owned trusted; committed where
-the scope is a git repo, plain scope-durable files elsewhere).
+Capabilities have two sources and one destination: a member repo's
+`capabilities/<name>/` (latest state, trusted by membership) or a package pinned
+in the workspace's `packages:` and locked in `oats-lock.json` (v3); at spawn each
+is copied whole into the instance's `.oats/modules/<name>/`. Nothing is
+installed at a deployment (`lib/remote.mjs`, `lib/workspace.mjs`,
+`lib/resolve.mjs`, `lib/packages.mjs`, `lib/materialize.mjs`).
 
 The live control panel is the OATS Desktop app (`packages/desktop/`): an
 Electron shell over a bundled zero-dependency localhost server that uses
@@ -62,6 +64,20 @@ their names.
 
 ## Resolution
 
+**Workspace model (0.25, current).** `lib/instance-resolution.mjs#prepareInstance(dir, soul)`
+loads `oats-local.yaml`, discovers the workspace over its Git remotes
+(`lib/workspace.mjs#discoverWorkspace`, or the standalone view), finds the
+soul among the confirmed members / external souls, and calls
+`lib/resolve.mjs#resolveSoul` → an immutable Resolution: `modules[]` (each
+`from: member|package` with commit and digest), `slots`, merged provider
+`payloads`, `skills`, `injects`, `revision`. Capability order is
+`defaults.<slot>` ⊕ `defaults.capabilities` ⊕ `defaults.byTeam[team]` ⊕
+`soul.capabilities` (soul wins; `off` removes; a soul's `<slot>: none` empties
+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)`:
 
@@ -194,14 +210,28 @@ never reconciled into committed souls.
 
 ## Acquisition and trust
 
-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.
+**Workspace model (0.25, current).** Nothing is installed. `oats sync`
+(`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
+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>` marks the exact locked integrity approved. Bundled
-packages are framework-trusted.
+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.
@@ -209,7 +239,7 @@ 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 `lockfileVersion: 2` lock records package
+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.

package/docs/integrations.md

@@ -29,54 +29,50 @@ offers comments.
 
 ## Selecting an integration
 
-Configuration activates the package for the intended target; the manifest
-already declares the slot, so `oats use` writes the entry under
-`capabilities.layers.<slot>`:
+The workspace supplies a default per slot; a soul may name another, or `none`.
+The manifest already declares the slot, so a soul's `capabilities:` entry does
+not repeat it — a capability with `layer: knowledge` fills the knowledge slot
+wherever it arrives from:
 
 ```yaml
-agent-types:
-  product-agents:
-    description: Planner, developer, and reviewer souls (they declare `type: product-agents`)
-
+# oats-workspace.yaml — one default per slot, for every soul
+defaults:
+  knowledge: { oats.okf: { from: package } }
+  messaging: { oats.aweb: { from: package } }
+  tasks: { oats.linear: { from: package } }
+
+# souls/planner/soul.yaml — keep the defaults, supply the soul's payloads
+knowledge:
+  owns: planner
+  reads: [developer]
+messaging:
+  channels: [product]
+tasks:
+  team: ENG
+  project: Agent Platform
+
+# souls/support-triager/soul.yaml — opt out of one slot, replace another
+knowledge: none                            # empties the slot
 capabilities:
-  layers:
-    knowledge:
-      capability: oats.okf
-      from: installed
-      settings:
-        bindings-file: /absolute/config/okf-bindings.json
-    messaging:
-      capability: oats.aweb
-      from: installed
-      agent-types:
-        product-agents:
-          enabled: true
-          settings:
-            team: example-team
-    tasks:
-      capability: oats.linear
-      from: installed
-      agent-types:
-        product-agents:
-          enabled: true
-          settings:
-            team: ENG
-            project: Agent Platform
+  oats.jira: { from: package }             # its manifest says layer: tasks → replaces the default
 ```
 
-CLI equivalents:
+Packages are pinned once in the workspace's `packages:`
+(`oats.okf: v2.1.3`, …) and synced ([packages.md](packages.md)). Host-owned
+values (absolute paths) go in `oats-local.yaml`:
 
-```bash
-oats use oats.okf --global --settings bindings-file=/absolute/config/okf-bindings.json
-oats use oats.aweb --type product-agents
-oats use oats.linear --type product-agents
-oats use none --layer tasks        # leave an inherited slot deliberately unfilled
+```yaml
+settings:
+  oats.okf:
+    bindings-file: /absolute/config/okf-bindings.json
+  oats.aweb:
+    delivery: channel
 ```
 
-Every matching soul gets one implementation per slot. A non-matching soul can
-resolve a different one or leave a slot unfilled. `none` is a layer
-selection, not a policy: a soul with `messaging: none` has no address, which
-is different from a soul whose type restricts its reach.
+Every soul gets one implementation per slot. Two layered capabilities arriving
+for one slot (a default plus a soul entry, or two soul entries) is
+`E_SLOT_CONFLICT`; spell `<cap>: off` to remove the one you do not want. `none`
+is a slot selection, not a policy: a soul with `messaging: none` has no address.
 
 ## Bundled integrations
 
@@ -104,9 +100,11 @@ secrets never belong in OATS config. See
 
 > **Removed: `oats.web`.** The browser web-panel capability was retired in
 > favor of the OATS Desktop app (`packages/desktop/`), which bundles the same
-> zero-dependency loopback server. If an `oats-lock.json` or
-> `oats-config.yaml` still names `oats.web`, remove that entry. Full
-> migration steps: [desktop-succession](desktop-succession.md).
+> 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).
 
 ## Building an integration
 
@@ -156,8 +154,12 @@ exist and match its owner. Acquisition/activation never bootstraps a knowledge
 base. If activating globally, provision each working soul first or target only
 ready sources.
 
-```bash
-oats use oats.okf --soul domain-expert --settings bindings-file=/absolute/config/okf-bindings.json harvest-runtime=claude
+```yaml
+# oats-local.yaml
+settings:
+  oats.okf:
+    bindings-file: /absolute/config/okf-bindings.json
+    harvest-runtime: claude
 ```
 
 - `harvest-runtime: pi | claude | codex` defaults to `pi`, independently of the
@@ -197,8 +199,9 @@ that CLI cannot revoke the certificate.
 
 ## oats.aweb settings (1.10.0)
 
-Set with `oats use oats.aweb --settings <key>=<value>` at a scope, or per
-soul through the binding's `settings:` map.
+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>`.
 
 - `delivery: channel | session` (default `channel`). `session` hands
   notification delivery to the host wake broker: `AWEB_DELIVERY=session` in

package/docs/knowledge-capability-authoring.md

@@ -40,12 +40,18 @@ aliases or relax installed-artifact integrity checks.
 Select a deployment scope explicitly and acquire the published source, then
 opt in for an author soul:
 
-```bash
-oats install git:github.com/awebai/oats@v0.23.0 --dir /path/to/scope
-oats use oats.knowledge-theory --soul <author-soul> --dir /path/to/scope
+```yaml
+# oats-workspace.yaml
+packages:
+  oats.framework: v1.1.3            # provides oats.core, oats.setup, oats.knowledge-theory
+
+# souls/<author-soul>/soul.yaml
+capabilities:
+  oats.knowledge-theory: { from: package }
 ```
 
-Git sources select `oats-package/` by default and lock the resolved commit.
+`oats sync` resolves the version to a commit and locks it; the package is read
+at `oats-package/` of its repository.
 The `oats.knowledge-theory` catalog shortcut uses that same published v0.23.0
 source. The current authoring-reference patch is package 1.0.1: once framework
 v0.23.1 is published, an explicit initial Git acquisition at that tag selects