@awebai/oats 0.24.12 → 0.25.0

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

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
 
@@ -156,8 +152,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 +197,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

package/docs/knowledge-migration.md

@@ -25,10 +25,11 @@ knowledge layer. V2 uses external accepted bases and independent workers, not
   The required v2 spawn hook refuses a legacy `soul/knowledge/`; it never silently
   substitutes an empty bundle.
 
-After publication, explicitly acquire/update the catalog **Git** package and
-review/re-trust its executable surfaces. An existing exact lock does not advance
-on bare `oats install`. Do not install the npm bundled mirror as a self-contained
-package: npm drops the source worker's canonical `CLAUDE.md` symlink.
+After publication, bump `packages.oats.okf` in the workspace file and run
+`oats sync`: the new version resolves to a commit and its executables are
+approved once. An existing lock never advances by itself. Package content is
+read from the catalog **Git** repository, never from an npm mirror (npm drops
+the source worker's canonical `CLAUDE.md` symlink).
 
 ## 2. Bind and provision external destinations
 

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

@@ -104,11 +104,19 @@ not satisfy a skill's missing reference if it is outside the capability root.
 
 ## Acquisition, activation and trust
 
-At an explicitly chosen *test* scope, acquisition and activation are separate:
+In a *test* workspace, pin the package by a direct ref and give it to a soul:
+
+```yaml
+# test workspace's oats-workspace.yaml
+packages:
+  example.knowledge-pkg: git:/abs/path/to/source-repo.git@v0.1.0   # a tag; branches are refused
+defaults:
+  knowledge: { example.knowledge: { from: package } }
+```
 
 ```bash
-oats install /path/to/source/oats-package --dir /path/to/test-scope
-oats use example.knowledge --global --dir /path/to/test-scope
+oats sync --dir /path/to/test-workspace      # resolve, lock, approve once
+oats spawn <soul> --preview --json           # the module as it would be materialized
 ```
 
 These are illustrative user operations, not instructions to change a live

package/docs/knowledge.md

@@ -57,17 +57,33 @@ instance identity (an explicit `--soul` does not override an invoking instance's
 saved settings). The explicit Git source works before and after the v0.23.1
 framework catalog integration:
 
+```yaml
+# oats-workspace.yaml
+packages:
+  oats.okf: v2.1.3
+defaults:
+  knowledge: { oats.okf: { from: package } }
+
+# souls/domain-expert/soul.yaml
+knowledge:
+  owns: domain-expert
+
+# oats-local.yaml (this machine)
+settings:
+  oats.okf:
+    bindings-file: /absolute/config/okf-bindings.json
+```
+
 ```bash
-oats install git:github.com/awebai/oats-okf@v2.0.0
-oats trust oats.okf
-oats use oats.okf --soul domain-expert --settings bindings-file=/absolute/config/okf-bindings.json
-oats doctor --soul domain-expert --json
+oats sync                                  # resolves v2.1.3 to a commit, asks executable approval once
+oats spawn domain-expert --preview --json  # the exact oats.okf module (package, version, commit)
 ```
 
-Acquisition activates nothing. An existing lock remains exact until an explicit
-`oats update oats.okf`; v1 operators must plan migration before that update.
-Executable changes need review and renewed trust. Target only configured source
-souls; the service worker need not itself receive the knowledge layer.
+Pinning activates nothing by itself: the soul's `knowledge:` payload and the
+machine's `settings.oats.okf` must be bindable. The lock stays exact until the
+workspace bumps `packages.oats.okf`; v1 operators must plan migration before
+that bump. Executable changes come with a new version and a new approval. A
+service worker need not itself fill the knowledge slot (`knowledge: none`).
 
 ### Bindings document