@awebai/oats 0.25.9 → 0.26.0

package/docs/knowledge.md

@@ -5,8 +5,7 @@ For the canonical design, defaults and alternatives, start with
 an operational guide to the version-scoped OKF implementation below, not a universal
 knowledge layout or learning policy. The default direction is centralised per-soul
 knowledge; other capabilities may provide different procedures and placements,
-including co-location, without writing into immutable captured artifacts. For the
-newer captured path, also read the [0.24 release scope](release-notes/v0.24.0.md).
+including co-location, without writing into a home's read-only module copies.
 
 Specialization is accumulated judgment: decisions and rationale, rejected
 alternatives, discovered limits, and maintained context that changes what a
@@ -22,7 +21,6 @@ are optional author resources, not mandatory runtime policy.
 > the published OATS >=0.23.0 kernel. Framework v0.23.1 integrates its catalog
 > and mirror; publishing packages does not activate or deploy them automatically.
 > See [release notes](release-notes/v0.23.1.md).
-> V1 soul-contained knowledge needs [explicit migration](knowledge-migration.md).
 
 ## What lives where
 
@@ -52,7 +50,7 @@ Acquire the catalog Git payload; do not install a copied npm mirror as a local
 package or repair missing aliases in installed artifacts.
 
 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
+workspace file, let `oats sync` resolve, verify and lock 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
@@ -80,7 +78,7 @@ settings:
 ```
 
 ```bash
-oats sync                                  # resolves v2.1.3 to a commit, asks executable approval once
+oats sync                                  # resolves v2.1.3 to a commit, verifies its integrity, writes the lock
 oats spawn domain-expert --preview --json  # the exact oats.okf module (package, version, commit) + settings.oats.okf (the merged payload)
 ```
 
@@ -90,7 +88,7 @@ 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
+that bump. Executable changes come with a new version, reviewed as a new pin. A
 service worker need not itself fill the knowledge slot (`knowledge: none`).
 
 ### Bindings document
@@ -180,13 +178,14 @@ oats okf init --base project --nodes /absolute/config/project-nodes.json --outpu
 
 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
+(discover → resolve → the soul's `oats.okf` module at its locked commit and
+integrity), 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).
+default. It never runs "the newest instance's copy" and never a cache read the
+lock does not pin (`E_PACKAGE_MISSING` until `oats sync` locks the declared
+version; drifted content is `E_PACKAGE_INTEGRITY`).
 *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.*
@@ -375,7 +374,7 @@ is unknown, inspect the worker session before retrying. See the
 [standalone runtime guide](https://github.com/awebai/oats-okf#independent-worker-and-completion)
 for exact recovery, adoption and lock-release procedures.
 
-## Without a knowledge integration
+## Without a knowledge capability
 
 `capabilities.layers.knowledge: none` is valid. The kernel creates no OKF state,
 notes, bundle or harvest flow. Other capabilities may adopt, adapt or replace

package/docs/layers.md

@@ -12,7 +12,7 @@ Git workspace definition
   ├── supplies bounded defaults and provider declarations
   └── imports exported souls by source reference and revision
         └── soul declares requirements, defaults and software sources
-              └── preparation resolves and retains an approved composition
+              └── resolution pins and records an exact composition
                     └── instance runs against an independent work target
                           ├── knowledge capability
                           ├── messaging capability
@@ -38,31 +38,30 @@ Classic `kind`/`type`/`repo` declarations and config-targeted agent types are a
 - `oats-membership.yaml` is a repository's half of the handshake: the workspace backlink plus an optional default team label. Everything under `souls/` and `capabilities/` is discoverable by convention (`private: true` opts out); there are no export lists.
 - Membership requires compatible observations on both sides; folder adjacency or a copied declaration is not admission.
 - External source import does not adopt the publisher's workspace. A framework repository may host its own development workspace without imposing it on consumers.
-- Operator choices and workspace defaults must respect source requirements. Git read access is not write permission, executable approval or messaging enrollment.
+- Operator choices and workspace defaults must respect source requirements. Git read access is not write permission, a trust declaration or messaging enrollment.
 
 The [workspace guide](workspaces.md) explains these boundaries and the [declaration contract](design/2026-09-15-portable-declarations.md) defines their versioned forms.
 
 ## Capability manifest and lifecycle events
 
-A capability's `oats.json` declares its identity, optional fundamental `layer`, resources, host/runtime prerequisites, commands, operations and supported lifecycle contributions. A distribution package's `oats-package.json` exports one or more capabilities; a package is not itself an active integration or workspace.
+A capability's `oats.json` declares its identity, an optional `layer` field (which names the core capability it is, if any), resources, host/runtime prerequisites, commands, operations and supported lifecycle contributions. A distribution package's `oats-package.json` exports one or more capabilities; a package is not itself an active capability or workspace.
 
-The current [manifest schema](capability-manifest.schema.json) includes the published binding interface and helper/input declarations. A manifest shape alone does not certify its implementation:
+The current [manifest schema](capability-manifest.schema.json) includes the published binding interface. A manifest shape alone does not certify its implementation:
 
-- Captured fundamental providers expose their declared normalize/bind/check phases through the existing broker. The kernel resolves their fields without implementing their domain model.
-- Commands/hooks execute only with the appropriate exact artifact approval and invocation authority.
-- Helper behavior and optional source-receipt inputs are declared by their owner, not guessed from a layer name.
+- A core capability declares normalize/bind/check binding phases; readiness runs its `check` (the kernel relays its answer without implementing its domain model).
+- Commands/hooks execute only from a declared source (a member, or a package the workspace declares, at its locked commit and integrity).
+- `helperInjection` and hook `inputs` are accepted and ignored since 0.26 (they served the removed captured path).
 - Required setup/capture outcomes cannot be silently omitted to make a launch or cleanup appear successful.
-- Legacy hook environment and captured binding/invocation inputs are distinct contracts. A legacy hook is not automatically safe for retained execution.
 
-Use [capability details](capabilities.md), the [provider wire](design/2026-09-16-provider-binding-wire.md), [helper/input contract](design/2026-09-17-capability-helper-input-contract.md) and [package runtime boundary](design/package-runtime-api.md).
+Use [capability details](capabilities.md) and the [provider wire](design/2026-09-16-provider-binding-wire.md).
 
-## The three fundamental slots
+## The three core capabilities
 
-Knowledge, messaging and tasks are exclusive provider slots: zero or one selected implementation of each per composition. `none` is an explicit permitted choice only where requirements allow it. Additional capabilities are unlimited and nonexclusive; the three slots do not limit domain tools or workflows.
+Knowledge, messaging and tasks are the **core capabilities**: at most one of each per soul, each filling its own slot. `none` is an explicit permitted choice only where requirements allow it; it empties that slot. Other capabilities are unlimited and nonexclusive; the three core capabilities do not limit domain tools or workflows.
 
 ### The knowledge contract
 
-The kernel supplies selection, retained identity/resources, approval, invocation/lifecycle context, independent helper execution and truthful outcomes. It does not mandate OKF, memory filenames, a taxonomy, a harvester or external-only mutable placement.
+The kernel supplies selection, retained identity/resources, exact locking, invocation/lifecycle context, independent helper execution and truthful outcomes. It does not mandate OKF, memory filenames, a taxonomy, a harvester or external-only mutable placement.
 
 The knowledge capability supplies organization, stores, readers, evidence capture, judgment, maintenance and delivery/acceptance policy. Mutable knowledge is never permission to alter immutable retained software/source artifacts.
 
@@ -72,7 +71,7 @@ Alternatives may choose different placement or learning procedures. A supported
 
 ### The tasks contract
 
-A task provider owns work assignment, claims, status, blockers, outcomes and handoff procedures. OATS supplies the selected capability/runtime boundary, not one mandatory tracker workflow. Jira and Linear are available integrations; no tasks provider is mandatory when source requirements permit none.
+The tasks core capability owns work assignment, claims, status, blockers, outcomes and handoff procedures. OATS supplies the selected capability/runtime boundary, not one mandatory tracker workflow. Jira and Linear are available tasks capabilities; none is mandatory when source requirements permit `none`.
 
 Messaging is conversation, not automatically task state. Accepted knowledge may explain a decision or important situation without duplicating the tracker.
 
@@ -80,7 +79,7 @@ Messaging is conversation, not automatically task state. Accepted knowledge may
 
 The current slot name is **`messaging`**. The capability owns native identity, addressing, team membership, transport, wake delivery and qualification. A team alias in a workspace is a declaration, not proof that an actor is enrolled or a privacy property is enforced.
 
-aweb 1.10.3 supports its legacy setup/lifecycle path but lacks the captured provider-binding interface. **aweb 1.11.0** (OATS >=0.24.2) adds it (1.11.2, OATS >=0.24.4, is code-identical and declares its fixed reasons and `helperInjection: omit`): `check` qualifies HOME-route operational custody for an input-capable Claude/Codex primary with an explicit private team and `delivery: session`; a strict-Pi print primary reports `needs-configuration` rather than dropping the requirement. Qualification is not account delegation, broker delivery or model consumption.
+aweb 1.10.3 supports its setup/lifecycle path but lacks the provider-binding interface. **aweb 1.11.0** (OATS >=0.24.2) adds it (1.11.2, OATS >=0.24.4, is code-identical and declares its fixed reasons and `helperInjection: omit`): `check` qualifies HOME-route operational custody for an input-capable Claude/Codex primary with an explicit private team and `delivery: session`; a strict-Pi print primary reports `needs-configuration` rather than dropping the requirement. Qualification is not account delegation, broker delivery or model consumption.
 
 The earlier proposed `reach` ladder is **not an enforced universal field**. In particular, aweb's `team_and_contacts` includes verified same-team senders; the compatibility spellings `contacts-only` and `contacts_only` do not establish owner-only admission. A config command succeeding proves neither inbound/outbound restrictions nor knowledge visibility. See the [identity/membership amendment](design/2026-09-08-expert-assisted-deployment-proposal.md#membership-reach-and-visibility-are-separate) and [messaging boundary](design/2026-09-16-messaging-capability-contract.md).
 
@@ -96,11 +95,11 @@ The work target is independent of source publication and knowledge placement. Pr
 
 ## Kernel briefings versus operational capabilities
 
-The kernel owns only what describes the layout it creates: the `instance-boundary` briefing (home versus `work/`), the selected work-mode briefing and config-declared injections. Knowing how to *operate* OATS (status, spawn, retire, soul discovery) and how to *configure* it (workspaces, packages, approval) is capability content — the official capabilities `oats.core` (a workspace default via `defaults.capabilities`, removable per soul with `off`) and `oats.setup` (held by an onboarding expert), both provided by the `oats.framework` package; see [souls and instances](souls-and-instances.md#oats-operational-knowledge-is-a-capability).
+The kernel owns only what describes the layout it creates: the `instance-boundary` briefing (home versus `work/`), the selected work-mode briefing and config-declared injections. Knowing how to *operate* OATS (status, spawn, retire, soul discovery) and how to *configure* it (workspaces, packages, the lock) is capability content — the official capabilities `oats.core` (a workspace default via `defaults.capabilities`, removable per soul with `off`) and `oats.setup` (held by an onboarding expert), both provided by the `oats.framework` package; see [souls and instances](souls-and-instances.md#oats-operational-knowledge-is-a-capability).
 
 ## Capture and knowledge are separate
 
-The native turn record is an evidence substrate, not accepted knowledge or a compulsory fourth fundamental slot. A capability decides which evidence it consumes and how it judges it. Source attribution, before-read custody and incomplete-outcome handling remain necessary wherever those guarantees are promised.
+The native turn record is an evidence substrate, not accepted knowledge or a compulsory fourth core capability. A capability decides which evidence it consumes and how it judges it. Source attribution, before-read custody and incomplete-outcome handling remain necessary wherever those guarantees are promised.
 
 A successful capture is not a completed judgment; completed judgment is not accepted Git knowledge. Source loss or retirement must not erase pending obligations or make an uncertain record complete. See [the record package](../packages/record/README.md) and the relevant versioned lifecycle contracts.
 
@@ -110,7 +109,7 @@ A capability boundary is useful when implementations can differ without a new ke
 
 - Two stores within OKF are not proof of a genuinely different knowledge model.
 - Schema validation is not native authority, provider readiness or learning.
-- A working old configuration does not prove compatibility with a new captured profile.
+- A working old configuration does not prove compatibility with a new profile.
 - Workspace membership does not select every capability a member exports.
 - Published primitives and documentation do not constitute a completed deployment.
 

package/docs/oats-local.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://oats.dev/schemas/local-v2.json",
   "title": "Deployment-local overrides v2 (oats-local.yaml)",
-  "description": "The operator's side of a workspace: which workspace this machine realizes, where member clones live when not at the taught convention, host-owned capability settings (absolute paths belong HERE, never in the workspace file), and souls disabled on this machine. Never shared through Git.",
+  "description": "The operator's side of a workspace: which workspace this machine realizes, where member clones live when not at the taught convention, host-owned capability settings (absolute paths belong HERE, never in the workspace file), souls disabled on this machine, and the named launch configurations this host offers. Never shared through Git.",
   "type": "object",
   "required": ["schemaVersion", "workspace"],
   "additionalProperties": false,
@@ -35,6 +35,34 @@
       },
       "description": "<capability>: { <key>: <value> } host-owned values the manifests ask for."
     },
+    "launch-configs": {
+      "type": "object",
+      "description": "Named ways to start a harness on this host, independent of any soul (lead decision 2: a spawn-time host choice). Selected by name at spawn or session start/restart; explicit flags override its fields. Written by `oats launch-config set|remove`.",
+      "propertyNames": { "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
+      "additionalProperties": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["runtime"],
+        "properties": {
+          "runtime": { "type": "string", "enum": ["pi", "claude", "codex"], "description": "The harness family this configuration starts; it decides the kernel's own baseline arguments (skills, instructions, task) and how model/yolo are expressed." },
+          "executable": { "type": "string", "minLength": 1, "description": "The program to run instead of the runtime's default binary: a bare name is looked up on PATH on the execution host; a path containing a slash is resolved against the deployment directory (where this oats-local.yaml lives) when relative. Checked to exist and be executable before any start; never executed just to probe it." },
+          "args": { "type": "array", "items": { "type": "string" }, "description": "Extra arguments, each passed literally (no shell interpretation): native configuration files or profiles go here as ordinary arguments." },
+          "env": {
+            "type": "object",
+            "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" },
+            "additionalProperties": {
+              "oneOf": [
+                { "type": "string" },
+                { "type": "object", "additionalProperties": false, "required": ["fromEnv"], "properties": { "fromEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" } } }
+              ]
+            },
+            "description": "Environment for the harness. A string is a literal (non-secret by contract; still redacted in every answer). {fromEnv: NAME} is resolved from the execution host's environment at start time; the reference, never the value, is recorded. A missing reference refuses the start before anything stops."
+          },
+          "model": { "type": "string", "minLength": 1, "description": "Model for this configuration's runtime; overrides the soul default when this configuration is selected." },
+          "yolo": { "type": "boolean", "description": "Permission bypass for this configuration; overrides scope and soul defaults when selected." }
+        }
+      }
+    },
     "souls": {
       "type": "object",
       "additionalProperties": false,

package/docs/oats-membership.schema.json

@@ -15,9 +15,11 @@
       "description": "Repo ref of the workspace host, without revision."
     },
     "team": {
-      "type": "string",
-      "pattern": "^[a-z0-9][a-z0-9._-]*$",
-      "description": "Default team label for souls and capabilities in this repo that carry no `team:` of their own."
+      "anyOf": [
+        { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+        { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" } }
+      ],
+      "description": "Default team label, or a non-empty list of distinct labels (the first is the primary), for souls in this repo that carry no `team:` of their own. A capability without its own `team:` is listed under the primary."
     }
   }
 }

package/docs/oats-package.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://oats.dev/schemas/oats-package.schema.json",
   "title": "OATS distribution package manifest (oats-package.json)",
-  "description": "Manifest at a distribution-package root. A package is the source, dependency, integrity, review and atomic-update unit — it is TRANSPORT, not the installed entity. Acquisition stages the package in a temporary transaction directory, validates the whole selected payload, MATERIALIZES each declared capability into .agents/capabilities/installed/<id>/, writes the exact lock, and discards staging; there is no persistent package store. Every package must therefore export at least one capability, and each capability entry must name a DEDICATED capability root whose declared paths and symlinks all resolve inside it, so the materialized artifact is self-contained, independently hashable and independently trustable. Config templates are optional package SOURCE MATERIAL, never installed behavior: `oats install` applies none of them. Install never ambiently loads undeclared files.",
+  "description": "Manifest at a distribution-package root. A package is the source, dependency, integrity, review and atomic-update unit — it is TRANSPORT, not the installed entity. A workspace declares it in `packages:`; `oats sync` resolves it to a commit, verifies its integrity and locks it, and each spawn copies the capabilities a soul selects into that instance's home; there is no persistent package store. Every package must therefore export at least one capability, and each capability entry must name a DEDICATED capability root whose declared paths and symlinks all resolve inside it, so the copied artifact is self-contained and independently hashable. Config templates are optional package SOURCE MATERIAL, never applied behavior; nothing ambiently loads undeclared files.",
   "type": "object",
   "required": [
     "package",
@@ -54,7 +54,7 @@
       "uniqueItems": true
     },
     "configTemplates": {
-      "description": "Named config TEMPLATES: complete reference oats-config.yaml files an adopter may explicitly adopt with `oats init --package`. A template is a recommended starting point that becomes ordinary local policy on adoption — adopters may change every copied setting, and package updates never rewrite an adopted config. Templates must stay portable: no secret, credential, account, machine path or provider-local ID. Installation applies none of them. This is the canonical spelling; a manifest may not carry both this and the legacy `configs`.",
+      "description": "Named config TEMPLATES: complete reference oats-config.yaml files of the classic line, whose adoption verb is removed under the workspace model. A template is a recommended starting point that becomes ordinary local policy on adoption — adopters may change every copied setting, and package updates never rewrite an adopted config. Templates must stay portable: no secret, credential, account, machine path or provider-local ID. Installation applies none of them. This is the canonical spelling; a manifest may not carry both this and the legacy `configs`.",
       "type": "object",
       "propertyNames": {
         "pattern": "^[a-z0-9][a-z0-9._-]*$"

package/docs/oats-workspace.schema.json

@@ -36,7 +36,7 @@
     },
     "messaging": {
       "type": "object",
-      "description": "Opaque provider payload consumed by the messaging-slot capability. May carry byTeam: { <team label>: <payload> } — the kernel merges base ⊕ byTeam[soul.team] and strips byTeam before the provider sees it (decision 23).",
+      "description": "Opaque provider payload consumed by the messaging core capability. May carry byTeam: { <team label>: <payload> } — the kernel merges base ⊕ byTeam[soul.team] and strips byTeam before the provider sees it (decision 23).",
       "properties": {
         "byTeam": {
           "type": "object",

package/docs/{official-marketplace.md → official-catalog.md}

@@ -1,6 +1,6 @@
-# The official OATS marketplace
+# The official OATS catalog
 
-The marketplace is the reviewed [package-catalog.json](../package-catalog.json)
+The official catalog is the reviewed [package-catalog.json](../package-catalog.json)
 list in [awebai/oats](https://github.com/awebai/oats), not a separate registry
 service. **A package listed there is official.** A name, logo, repository owner
 or workspace membership alone does not make a package official.
@@ -12,15 +12,16 @@ or workspace membership alone does not make a package official.
   can point to the package that supplies them.
 - A workspace pins an official package by **bare version** in its
   `packages:` map (`oats.okf: v2.1.3`); `oats sync` resolves it through the
-  catalog to an exact commit, locks it and asks for executable approval once
-  per version. A package outside the catalog is written `git:<repo>@<ref>`.
+  catalog to an exact commit, fetches it, verifies its integrity and locks it.
+  A package outside the catalog is written `git:<repo>@<ref>`.
   Pinning does not enroll a team or adopt the publisher's workspace. See
   [packages](packages.md).
-- The Desktop marketplace view/search is **planned for the parity phase**, not
-  shipped by this policy or by OATS 0.24. There is no new marketplace CLI verb.
-- **Discoverable ≠ pinned ≠ approved.** A catalog listing grants nothing; a
-  `packages:` pin selects a version; the lock's per-version approval is what
-  lets its executables run. Nothing is installed.
+- The Desktop catalog view/search is **planned for the parity phase**, not
+  shipped by this policy. There is no catalog CLI verb.
+- **Discoverable ≠ declared.** A catalog listing grants nothing; a
+  `packages:` pin is the workspace's decision to trust that package at that
+  version, and the lock pins it to an exact commit and integrity. Nothing is
+  installed.
   Official status never grants trust, credentials or permission to run code.
 - Listing also does not prove that every harness, provider combination or
   deployment profile is supported. Check the package's declared compatibility,
@@ -46,8 +47,9 @@ or workspace membership alone does not make a package official.
 - **Valid declarations:** capability manifests validate against the supported
   schema and state truthful identities, compatibility and requirements.
 - **Honest execution surface:** commands, hooks, launch environment and other
-  executable contributions are declared accurately. Review their effects;
-  approval still binds to each capability's exact artifact, not its official name.
+  executable contributions are declared accurately. Review their effects: a
+  workspace that declares the package trusts exactly the locked version, not
+  its official name.
 - **Maintainership:** a documented, reachable maintainer contact or maintained
   issue/security-reporting route.
 - **License:** clear redistribution terms for the package and its dependencies,
@@ -73,10 +75,7 @@ this policy does not invent new catalog or manifest fields.
 
 These entries are in the current repository catalog. An older installed CLI keeps
 its bundled catalog; publication here does not update that installation or rewrite
-old source references, locks or tags. Follow that CLI's supported acquisition path.
-The [workspace adoption guide](workspace-adoption.md) distinguishes the published
-capabilities and five expert imports from the still-pending D3 setup-expert flow.
-No package is silently added to an existing soul.
+locks or tags. No package is silently added to an existing workspace.
 
 ## Updates, deprecation and removal
 
@@ -84,4 +83,4 @@ Use the same catalog PR and maintainer-review path to update, deprecate or remov
 an entry. State the reason, affected releases and supported replacement or hold,
 and assess existing locks/restores before changing discovery. Preserve immutable
 release history. A list change is not permission to rewrite a deployment's locks,
-revoke or grant local approvals, uninstall packages or delete retained resources.
+change what a workspace declares, uninstall packages or delete retained resources.

package/docs/packages.md

@@ -4,12 +4,11 @@ A **package** is a place to fetch capabilities from *with a version attached*.
 It is one of the two kinds of capability source in the
 [workspace model](workspaces.md); the other — a member repo — is never
 versioned. Nothing is installed: a package is resolved to an exact commit by
-`oats sync`, recorded in `oats-lock.json`, approved once per version, and
-**copied whole into each instance at spawn** (`<home>/.oats/modules/<cap>/`).
+`oats sync`, recorded in `oats-lock.json`, and **copied whole into each instance at spawn** (`<home>/.oats/modules/<cap>/`).
 
 Ground truth: [`oats-package.schema.json`](oats-package.schema.json) (the
-package manifest), [`oats-lock-v3.schema.json`](oats-lock-v3.schema.json) (the
-lock), and the module contract
+package manifest), the [lock v3 format](#lock-v3) below (`validateLock` in
+`lib/packages.mjs` is its authority; it has no JSON schema), and the module contract
 [design/2026-09-23-workspace-module-contracts.md §4](design/2026-09-23-workspace-module-contracts.md).
 
 ## What a package is
@@ -24,7 +23,7 @@ A Git repository **contains** a package at `oats-package/`:
         ├── acme-lint/oats.json          # ordinary capability manifests (docs/capabilities.md)
         └── acme-deploy/
             ├── oats.json
-            └── bin/acme-deploy.mjs      # an executable → approved once per version
+            └── bin/acme-deploy.mjs      # an executable — trusted by declaring the package
 ```
 
 `oats-package.json` must declare `package` and `capabilities` (a list of
@@ -52,14 +51,44 @@ packages:
   named by `OATS_PACKAGE_CATALOG` — which supplies the repo url, the tag
   convention (`v2.1.3` or `oats-framework/v1.1.3`) and the payload path. An id
   the catalog does not know is `E_PACKAGE_MISSING` ("use `git:<repo>@<ref>` for
-  a package outside the catalog"). The catalog is the reviewed marketplace
-  ([official-marketplace.md](official-marketplace.md)) and the only way a
+  a package outside the catalog"). The catalog is the reviewed official list
+  ([official-catalog.md](official-catalog.md)) and the only way a
   package becomes pinnable *by id*.
 - **`git:<repo>@<ref>`**: `<repo>` is any repo ref the kernel understands
   (`github.com/org/repo`, `https://…`, `git@host:…`, `/abs/bare.git`,
   `file:///…`); `<ref>` is a tag name or a full 40-hex commit. The package is
   read at `oats-package/`.
 
+A whole workspace file pinning the current official packages — its bare
+versions are kept equal to `package-catalog.json` by
+`test/docs-catalog-pins.test.mjs`, so a catalog pin round updates this example
+in the same change:
+
+<!-- catalog-pins -->
+```yaml
+schemaVersion: 2
+name: acme
+members:
+  - git:github.com/acme/agents
+  - git:github.com/acme/platform
+packages:
+  oats.framework: v1.1.3
+  oats.okf: v2.1.5
+  oats.aweb: v1.13.1
+teams:
+  global: { description: Org-wide }
+  engineering: { description: Platform }
+defaults:
+  capabilities: { oats.core: { from: package } }
+  knowledge: { oats.okf: { from: package } }
+  messaging: { oats.aweb: { from: package } }
+  tasks: none
+stores:
+  org: git:github.com/acme/knowledge
+messaging:
+  private: per-human
+```
+
 There is no third form; `lib/packages.mjs#classifyPackageValue` is the one
 grammar, used by workspace validation and by `sync`. A `<ref>` (or catalog ref)
 that resolves to a **branch** is refused: `E_PACKAGE_INTEGRITY { why: "branch" }`
@@ -75,15 +104,12 @@ decision recorded in the lock.
 $ oats sync
 workspace  acme  (github.com/acme/agents @ 3f2a9c1e)
 members    agents ✓↔ (@ 3f2a9c1e)   platform ✓↔ (@ 77c0a1b2)   tools ✓↔ (@ 47f4b816)   billing ✗ (no-backlink)
-packages   acme.tools 0.4.0 ✓ (approval needed)   oats.framework 1.1.3 ✓ (approved)   oats.okf 2.1.3 ✓ (approved)
+packages   acme.tools 0.4.0 ✓ (@ 47f4b816)   oats.framework 1.1.3 ✓ (@ 9c3e27aa)   oats.okf 2.1.3 ✓ (@ b2e16f2e)
 changed    acme.tools  — → 0.4.0 (@ 47f4b816)
-souls      7 discovered (6 members, 1 external, 0 disabled here) · 1 private (platform-reviewer, platform only)
+souls      7 discovered (6 members, 1 external, 0 disabled here) · 0 private capabilities
 teams      engineering 4 souls, 3 capabilities · global 2 souls, 2 capabilities · unassigned 1 soul
 
-acme.tools 0.4.0 @ 47f4b816 needs executable approval (2 executables, digest sha256-7923…):
-  acme-deploy: command apply → bin/acme-deploy.mjs
-  acme-deploy: command plan → bin/acme-deploy.mjs
-approve acme.tools 0.4.0? [y/N]
+lock       oats-lock.json
 ```
 
 `sync` (run from the deployment — where `oats-local.yaml` is, or `--dir`):
@@ -94,19 +120,15 @@ approve acme.tools 0.4.0? [y/N]
    and records `url`, `path`, `version`, `commit`, `integrity`, `capabilities`;
 3. for an entry already locked at the same version/source/path: the commit must
    be unchanged (else `E_PACKAGE_INTEGRITY` — "the tag moved; a version string
-   must change when its content does"), the integrity must match, and a
-   recorded approval must still describe the package's executables (else
-   `E_PACKAGE_UNAPPROVED` — approve again);
-4. for every unapproved entry, prints the exact executables (every `commands.*`
-   target and every `hooks.*.command` target of every capability manifest —
-   hooks run unattended at spawn/retire) and asks **once** on a terminal;
-5. writes `oats-lock.json` and reports the diff. Entries dropped from
+   must change when its content does") and the integrity must match
+   (`E_PACKAGE_INTEGRITY`);
+4. writes `oats-lock.json` and reports the diff. Entries dropped from
    `packages:` are dropped from the lock.
 
-Exit status `2` means the lock is written but approvals are pending
-(non-interactive, or declined). Spawns of souls using an unapproved package are
-refused (`E_PACKAGE_UNAPPROVED`) until `oats sync` is run in a terminal and the
-approval given. `--json` emits the `syncApi: 1` envelope documented in
+There is **no approval step** (human decision, 2026-09-24): declaring a package
+in the workspace's `packages:` is the trust decision, so `sync` asks nothing,
+exits `0` on success, and `--approve` is `E_BAD_ARGS`. `--json` emits the
+`syncApi: 1` envelope documented in
 [desktop-cli-api.md](desktop-cli-api.md#workspace-model-workspaceapi-2).
 
 ## `oats package add | remove`
@@ -128,7 +150,7 @@ machine. Nothing network-bound happens in `package add`; `sync` resolves.
 ## Lock v3
 
 `oats-lock.json` lives beside `oats-local.yaml`. Two operators who synced the
-same workspace commit and approved the same versions hold identical locks.
+same workspace commit hold identical locks.
 
 ```json
 {
@@ -141,8 +163,7 @@ same workspace commit and approved the same versions hold identical locks.
       "version": "2.1.3",
       "commit": "b2e16f2ea1555be519db76fda30cd0bea06f8609",
       "integrity": "sha256-1c34dbe9c1cc3826dbe6ecbafbd9a1e189ed36a74bfb2ba8fb6f46a382e95c2d",
-      "capabilities": ["oats.okf"],
-      "approved": { "executables": "sha256-0d7615fa…", "at": "2026-09-24T09:02:11.000Z" }
+      "capabilities": ["oats.okf"]
     },
     "acme.tools": {
       "source": "git:github.com/acme/tools@v0.4.0",
@@ -151,8 +172,7 @@ same workspace commit and approved the same versions hold identical locks.
       "version": "0.4.0",
       "commit": "47f4b81660e4cc9701d373088de52462762585a3",
       "integrity": "sha256-4cd126a7…",
-      "capabilities": ["acme-deploy", "acme-lint"],
-      "approved": null
+      "capabilities": ["acme-deploy", "acme-lint"]
     }
   }
 }
@@ -167,28 +187,27 @@ same workspace commit and approved the same versions hold identical locks.
 | `commit` | full 40-hex OID the version resolved to |
 | `integrity` | `sha256-<hex>` content digest of the package tree at `path` |
 | `capabilities` | the capability names the package provides (sorted) — what `from: package` looks up |
-| `approved` | `{ executables: "sha256-<hex>", at }` — the digest of the approved executables — or `null` |
 
 A capability provided by **two** locked packages is ambiguous and fails
 closed (`E_PACKAGE_MISSING { ambiguous: [ids] }`): keep one of them in
 `packages:`. A lock that is not v3 (a 0.24 lock, an unreadable file) is
-`E_LOCK_SCHEMA`; it is never auto-repaired — delete it and `oats sync`. Agents
-never hand-edit the lock.
-
-## Approval
-
-Member capabilities are trusted by membership; **package executables are
-approved once per version**, and every instance that materializes that version
-inherits the approval. What is approved is a digest over the bytes of every
-executable a manifest can make the kernel run — `commands.*` targets and
-`hooks.*.command` targets — in canonical order; a hook object without
-`command` is `E_PACKAGE_MANIFEST`, never an invisible no-op. Skills, injects
-and other files are covered by `integrity`, not by the approval.
-
-The approval lives next to the commit it approved. A new version starts
-unapproved; a moved tag fails integrity and asks again; an approval whose digest
-no longer matches the tree is refused. `oats spawn` re-checks `approved` on the
-way to `from: package`: reaching materialization means approved.
+`E_LOCK_SCHEMA`; it is never auto-repaired — delete it and `oats sync`. A v3
+lock written before 0.26.0 may carry an `approved` record per entry: it is read
+with the field ignored, and the next write drops it. The reverse does not hold:
+a kernel before 0.26.0 refuses a lock 0.26.0 wrote (`E_LOCK_SCHEMA "approved:
+must be null or { executables, at }"`) — keep every kernel that reads one
+deployment on 0.26.0 or later. Agents never hand-edit the lock.
+
+## Trust
+
+Member capabilities are trusted by membership; **a package is trusted by its
+declaration in the workspace's `packages:`** (human decision, 2026-09-24) —
+people install a package only when they trust it, so there is no second,
+per-version approval step. The lock is reproducibility, not approval: it pins
+the exact commit and the content integrity, a moved tag or drifted content is
+`E_PACKAGE_INTEGRITY`, and at spawn the lock's capability list must match what
+the package declares at the locked commit (`E_PACKAGE_INTEGRITY { why:
+"capabilities" }`).
 
 ## Materialization from a package
 
@@ -214,6 +233,10 @@ Checked at resolution against the locked version (`E_COMPATIBILITY`,
 naming capability, package, version and range). A package pinned by OID has no
 version to check (`why: "unversioned"`): pin a tagged version.
 
+Separately, each capability's own `compatibility.oats` (its manifest's kernel
+range) must admit the running kernel, for package and member capabilities
+alike (`E_CAPABILITY_INCOMPATIBLE`); see [capabilities.md](capabilities.md).
+
 ## Publishing a package from a member repo
 
 A repo can be a **member** of the workspace **and** publish a package; the two
@@ -230,10 +253,10 @@ roles never collapse (see [workspaces.md](workspaces.md#member-tier-vs-package-t
    plus `acme-tools-dev: { from: here }`.
 3. Tag a release (`v0.4.0`). Tags are immutable: a new content needs a new tag.
 4. Consumers pin it: `oats package add acme.tools git:github.com/acme/tools@v0.4.0`
-   → commit → `oats sync` → approve once. Discovery shows the member row with
+   → commit → `oats sync`. Discovery shows the member row with
    `publishes: { package: "acme.tools", version: "0.4.0" }`.
 5. To become pinnable by id, open a PR adding the package to
-   `package-catalog.json` in the `oats` repo ([official-marketplace.md](official-marketplace.md)).
+   `package-catalog.json` in the `oats` repo ([official-catalog.md](official-catalog.md)).
 
 A soul that names one of the package's capabilities with
 `from: github.com/acme/tools` fails: `E_CAPABILITY_MISSING` with the hint
@@ -243,7 +266,7 @@ A soul that names one of the package's capabilities with
 
 ```json
 {
-  "policy": "docs/official-marketplace.md",
+  "policy": "docs/official-catalog.md",
   "packages": {
     "oats.okf":       { "url": "https://github.com/awebai/oats-okf.git", "ref": "v2.1.3", "path": "oats-package" },
     "oats.framework": { "url": "https://github.com/awebai/oats.git", "ref": "oats-framework/v1.1.3", "path": "oats-package" }
@@ -253,7 +276,7 @@ A soul that names one of the package's capabilities with
 
 `ref` carries the tag convention: a workspace's `oats.framework: v1.2.0`
 resolves to tag `oats-framework/v1.2.0`. Resolving through the catalog never
-grants approval and never advances a lock by itself — `oats sync` does, and
+advances a lock by itself — `oats sync` does, and
 says so.
 
 ## Removed verbs
@@ -264,4 +287,4 @@ replacement (`details.removed` / `details.replacement` in `--json`). There is
 no installed-capability directory, no config template adoption, no host
 requirement installer. A manifest's `requires` still describes what must exist
 on the host (runtime packages are verified at spawn; host commands are the
-operator's to install). See [rebuild-to-v2.md](rebuild-to-v2.md).
+operator's to install).

package/docs/release-notes/v0.22.0.md

@@ -31,7 +31,7 @@ files), the `oas:` config key, and capability ids, then the guided package
 conversion, so the scope ends on `lockfileVersion: 2` official packages.
 Any failure restores the original OAS bytes; a second run is a no-op.
 Executable trust is re-earned after conversion. See
-[docs/migration-from-oas.md](../migration-from-oas.md).
+[docs/migration-from-oas.md](https://github.com/awebai/oats/blob/v0.22.0/docs/migration-from-oas.md).
 
 Un-migrated OAS scopes are also **loud** now: `oats doctor` names them with
 the remedy, and every `oats migrate` form exits nonzero instead of

package/docs/release-notes/v0.23.1.md

@@ -74,7 +74,7 @@ must stay synchronized. Acquisition alone activates nothing.
 
 ## Migration and verification
 
-Follow [the v1 preservation and cutover guide](../knowledge-migration.md):
+Follow [the v1 preservation and cutover guide](https://github.com/awebai/oats/blob/v0.23.1/docs/knowledge-migration.md):
 inventory active writers, preserve legacy knowledge/state/cursors, provision
 empty owned nodes, stage and deliver through the provider, confirm acceptance,
 then deliberately cut over owner declarations and existing sources. Old