@awebai/oats 0.25.0 → 0.25.2

package/docs/first-team.md

@@ -56,15 +56,15 @@ one soul and, optionally, one capability. Every soul gets `oats.core` from the
 the resulting layout).
 
 ```bash
-oats onboard ~/acme-workspace --workspace git:github.com/acme/agents
+oats onboard ~/acme --workspace git:github.com/acme/agents     # any directory — an existing one with your clones is fine
 ```
 
 ```
-~/acme-workspace/                 # the taught "<name>-workspace" convention
+~/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
 ├── agents/                       # instance homes
-└── <member>/                     # clones of the members you work IN (printed as next steps)
+└── <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

package/docs/implementation.md

@@ -64,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)`:
 
@@ -196,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.
@@ -211,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

@@ -100,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
 

package/docs/knowledge-migration.md

@@ -39,17 +39,25 @@ Choose stable base IDs, stable owner IDs, nonoverlapping node paths and durable
 permissions. Confirm aliases and owners explicitly, rather than deriving them
 from an instance branch or name.
 
-Configure the absolute `bindings-file` for each source soul. Remove obsolete v1
-settings such as `record-window-turns` and `record-window-bytes`; v2 accepts only
-`bindings-file`, `harvest-runtime` and `harvest-model`. Provision **empty owned
-nodes** using `oats okf init`. Accept Git initialization through a reviewed PR
-before migration delivery; directory provisioning requires explicit confirmation
-and a genuinely non-Git location.
+Configure the absolute `bindings-file` **and** `state-dir` for each source soul
+— the oats.okf 2.1.x binding requires both as normalized absolute host paths
+(`setting state-dir is required (absolute host path)` is a refusal, not a
+default). Remove obsolete v1 settings such as `record-window-turns` and
+`record-window-bytes`; v2 accepts exactly `bindings-file`, `state-dir`,
+`harvest-runtime` and `harvest-model`. Under the 0.25 workspace model these live
+in `oats-local.yaml` `settings.oats.okf` ([configuration.md](configuration.md));
+a rebuilt deployment gets a **fresh** `state-dir`
+([rebuild-to-v2.md §7b](rebuild-to-v2.md#7b-okf-2-start-a-fresh-state-dir-do-not-re-point-the-old-one)).
+Provision **empty owned nodes** using `oats okf init`. Accept Git initialization
+through a reviewed PR before migration delivery; directory provisioning requires
+explicit confirmation and a genuinely non-Git location.
 
 ## 3. Stage and deliver each legacy bundle
 
-From the durable deployment configuration context in an operator shell without
-inherited instance identity, selecting the source soul:
+From the deployment directory (the one holding `oats-local.yaml`) in an operator
+shell without inherited instance identity, selecting the source soul with
+`--soul` — the kernel resolves the command exactly as `oats spawn --soul <x>`
+would ([knowledge.md](knowledge.md#inspection-and-operator-commands)):
 
 ```bash
 oats okf migrate --legacy /absolute/soul/knowledge --base project --node expert --output /absolute/empty-migration-stage --soul domain-expert --json

package/docs/knowledge.md

@@ -51,11 +51,13 @@ artifact**: npm drops the source worker's `CLAUDE.md -> AGENTS.md` symlink.
 Acquire the catalog Git payload; do not install a copied npm mirror as a local
 package or repair missing aliases in installed artifacts.
 
-With a released OATS >=0.23.0 kernel, acquire published OKF 2.0.0 from the
-intended deployment configuration context in an operator shell without inherited
-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:
+Under the 0.25 workspace model OKF is a **package**: pin it once in the
+workspace file, let `oats sync` lock and approve it, and let every soul that
+fills the knowledge slot say (or inherit) `oats.okf: { from: package }`.
+Operator-level `oats okf` commands run from the deployment directory with
+`--soul <name>` (an explicit `--soul` does not override an invoking instance's
+saved settings — use a clean shell). The pinned version resolves through the
+official catalog:
 
 ```yaml
 # oats-workspace.yaml
@@ -64,23 +66,29 @@ packages:
 defaults:
   knowledge: { oats.okf: { from: package } }
 
-# souls/domain-expert/soul.yaml
+# souls/domain-expert/soul.yaml — nothing under knowledge: for oats.okf; the default fills the slot.
+# What the soul owns/reads is souls/domain-expert/okf.json (below), not a soul.yaml payload.
+# A soul-true binding setting is the one thing the payload may carry, e.g.:
 knowledge:
-  owns: domain-expert
+  harvest-runtime: claude
 
 # oats-local.yaml (this machine)
 settings:
   oats.okf:
     bindings-file: /absolute/config/okf-bindings.json
+    state-dir: /absolute/state/okf
 ```
 
 ```bash
 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)
+oats spawn domain-expert --preview --json  # the exact oats.okf module (package, version, commit) + settings.oats.okf (the merged payload)
 ```
 
-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
+Pinning activates nothing by itself: the soul's `okf.json` must exist and the
+merged payload (soul `knowledge:` ⊕ `settings.oats.okf` ⊕ `--provider`) must be
+bindable — it may carry **only** the four settings below (`bindings-file`,
+`state-dir`, `harvest-runtime`, `harvest-model`); `owns`/`reads`/`root` on the
+soul payload are refused by 2.1.3, not read. 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`).
@@ -126,8 +134,10 @@ directory, not the current working directory:
   source homes/worktrees; keep the bindings file outside state and bases. Local
   Git locators must not be disposable linked worktrees. Directory lock/journal
   artifacts also must not overlap state, sources or another base.
-- Settings are `bindings-file`, `harvest-runtime` (`pi`, `claude`, `codex`,
-  default `pi`), and optional `harvest-model`. Choose an installed, authenticated
+- Settings are `bindings-file`, `state-dir` (both required, absolute host
+  paths), `harvest-runtime` (`pi`, `claude`, `codex`, default `pi`), and
+  optional `harvest-model` — the complete list a 2.1.3 payload may carry.
+  Choose an installed, authenticated
   worker runtime independently of the source; omitted models use that runtime's
   configured default. V1 record-window settings are not v2 settings.
 
@@ -157,7 +167,9 @@ bindings, owner declarations, base metadata or indexes fail required spawn rathe
 than silently bootstrapping empty knowledge.
 
 Provisioning is an explicit operator action. Prepare node-map files (the
-`nodes` object above, without its wrapper), then:
+`nodes` object above, without its wrapper), then run from the **deployment
+directory** (the one holding `oats-local.yaml`), naming the soul whose
+`knowledge:` payload and `settings.oats.okf` the command should run with:
 
 ```bash
 # New directory base: refuses an existing destination.
@@ -166,6 +178,19 @@ oats okf init --base team --nodes /absolute/config/team-nodes.json --confirm --s
 oats okf init --base project --nodes /absolute/config/project-nodes.json --output /absolute/new-bundle-stage --soul domain-expert --json
 ```
 
+These run **before any instance exists**. Outside an instance home the kernel
+resolves `oats okf … --soul <name>` exactly as `oats spawn <name>` would
+(discover → resolve → the soul's `oats.okf` module at its locked, approved
+commit), fetches that module into the deployment's module store
+(`<deployment>/.oats/modules/oats.okf@<commit12>/`) and dispatches to that copy
+with the soul's merged payload as `OATS_SETTINGS`; `--soul` is required
+(`E_BAD_ARGS` names it) unless the namespace's capability is a workspace
+default. It never runs "the newest instance's copy" and never an unapproved
+cache read (`E_PACKAGE_UNAPPROVED` until `oats sync` approves the version).
+*0.25.0 still answers `E_CAPABILITY_INACTIVE` here (the operator-level dispatch
+lands in 0.25.1); the interim is to run the module binary directly with
+`OATS_SETTINGS` and `OATS_CLI_BIN` set, as the tarball smoke does.*
+
 Put the Git proposal at the configured root in an operator-owned checkout and
 review/merge it through a PR before spawning working sources. Existing ownership
 changes require an explicit reviewed operator change, not harvest. The standalone
@@ -189,7 +214,7 @@ Snapshots are immutable by protocol, not live mounts. For current accepted text:
 # From the source home:
 oats okf read --base project --path expert/index.md --json
 oats okf refresh --json
-# From the deployment context, even after source retirement:
+# From the deployment directory (oats-local.yaml), even after source retirement — --soul selects the resolution:
 oats okf read --source /absolute/state/sources/UUID/source.json --base project --path expert/index.md --soul domain-expert --json
 oats okf refresh --source /absolute/state/sources/UUID/source.json --soul domain-expert --json
 ```
@@ -289,9 +314,17 @@ spawn and command exit alone are not successful learning.
 
 ## Inspection and operator commands
 
-Run home-local commands from that source home. For cross-source or retired-source
-commands, use the durable deployment context in a clean operator shell without
-another instance's `OATS_*`/`PI_*` identity; select the configured source soul.
+Run home-local commands from that source home: inside an instance the
+dispatcher resolves `okf` from the home's materialized module
+(`instance.json.modules` → `<home>/.oats/modules/oats.okf/`). For cross-source
+or retired-source commands, run from the **deployment directory** (the one
+holding `oats-local.yaml`) in a clean operator shell without another instance's
+`OATS_*`/`PI_*` identity, and select the source soul with `--soul <name>`: the
+kernel resolves that soul as a spawn would and dispatches to the deployment's
+copy of its `oats.okf` module with the soul's merged payload (see
+[Acquire, bind and provision explicitly](#acquire-bind-and-provision-explicitly)).
+No `oats-config.yaml` chain is consulted; a namespace no module of the soul
+provides is `E_UNKNOWN_COMMAND`.
 
 ```bash
 # Read-only; no capture, refresh, scheduling or worker launch:

package/docs/migration-from-oas.md

@@ -1,5 +1,15 @@
 # Migrating from OAS to OATS
 
+> **0.25 status — this is a 0.22–0.24 procedure.** `oats migrate` and
+> `oats trust` are **removed verbs** in the 0.25 kernel (`E_UNKNOWN_COMMAND`
+> naming the replacement), and 0.25 reads none of the files this page
+> converts to (`oats-config.yaml`, `oats-lock.json` v2, the `installed/` tier).
+> An OAS deployment reaches 0.25 in two steps: run this page's commands with a
+> **0.24.x** kernel (`npm install -g @awebai/oats@0.24`), then rebuild for the
+> workspace model with [rebuild-to-v2.md](rebuild-to-v2.md) — which is a rewrite
+> of three shared files, not a conversion, so an operator comfortable with the
+> v2 declarations may skip straight to it and let the old files go.
+
 OATS is the successor to OAS. **OATS 0.22.0 was published on 2026-09-03**:
 the kernel, Pi adapter, and Desktop assets are available. The published
 kernel acquired the official OKF, aweb, authoring, and development packages
@@ -17,15 +27,15 @@ while its knowledge and messaging configuration remains unmigrated.
 > before activation/spawn. The v2 integration is [prepared](release-notes/v0.23.1.md),
 > not a claim that those dependencies or any deployment have already changed.
 
-## Upgrade one scope
+## Upgrade one scope (0.24.x kernel)
 
 Finish or preserve active work before changing a daily-use deployment.
-Install OATS alongside the old CLI, then inspect the plan for the exact
-scope you intend to convert:
+Install OATS **0.24.x** alongside the old CLI (the 0.25 line has no `oats
+migrate`), then inspect the plan for the exact scope you intend to convert:
 
 ```bash
-npm install -g @awebai/oats@latest
-pi install npm:@awebai/oats-pi@latest
+npm install -g @awebai/oats@0.24
+pi install npm:@awebai/oats-pi@0.24
 oats migrate --from-oas --dry-run --dir /path/to/scope
 ```
 
@@ -39,10 +49,11 @@ oats doctor /path/to/scope
 ```
 
 Run the exact `oats trust <capability> --dir <scope>` commands printed by
-migration for the executable capabilities you approve. Trust does not
-transfer automatically. Verify the team ID and messaging membership with
-`oats aweb setup --dir /path/to/scope`, then exercise a real task, harvest,
-and retirement as described in [Run your first team](first-team.md).
+migration for the executable capabilities you approve (0.24: per-artifact
+trust; under 0.25 approval is per package version through `oats sync`). Trust
+does not transfer automatically. Verify the team ID and messaging membership
+with `oats aweb setup --dir /path/to/scope`, then exercise a real task,
+harvest, and retirement as described in [Run your first team](first-team.md).
 
 For a multi-repository deployment, start with one scope. The explicit
 `--recursive --dir /path/to/workspace` form converts every discovered OAS