@awebai/oats 0.24.13 → 0.25.1

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

@@ -51,23 +51,42 @@ 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
+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
+    state-dir: /absolute/state/okf
+```
 
 ```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
 
@@ -141,7 +160,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.
@@ -150,6 +171,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
@@ -173,7 +207,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
 ```
@@ -273,9 +307,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/layers.md

@@ -34,8 +34,8 @@ Classic `kind`/`type`/`repo` declarations and config-targeted agent types are a
 
 ## Workspace, repository and adoption contracts
 
-- `oats-workspace.yaml` declares intended members, defaults, imports and optional provider-owned stores/team/catalog references.
-- `oats.yaml` advertises a repository's actual soul/package/knowledge exports and, for membership, a workspace backlink.
+- `oats-workspace.yaml` (v2) declares members, the pinned `packages:`, team labels, defaults per slot and per team, stores, the messaging payload and pinned `external:` souls.
+- `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.
@@ -96,7 +96,7 @@ 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, trust) is capability content — accepted as the official capabilities `oats.core` (explicit default on every soul, removable) and `oats.setup` (held by the onboarding-created `oats-setup-expert`). At the0.24 baseline those skills are still kernel-shipped; see the [workspace guide](workspaces.md#how-a-soul-knows-oats-accepted-direction-not-yet-shipped) and the adoption plan's distribution packages.
+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).
 
 ## Capture and knowledge are separate
 

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

package/docs/oats-local.schema.json

@@ -0,0 +1,50 @@
+{
+  "$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.",
+  "type": "object",
+  "required": ["schemaVersion", "workspace"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "workspace": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?:git@[^@\\s]+|[^@\\s]+)$",
+      "description": "Repo ref of the workspace host; observed over the remote, need not be cloned."
+    },
+    "standalone": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?:git@[^@\\s]+|[^@\\s]+)$",
+      "description": "Repo ref to realize in the STANDALONE view (decision 10): its own souls and from: here capabilities plus oats.core (decision 25), no workspace lookup. Use when the repo's workspace cannot be read; `workspace:` still names the repo you point the kernel at."
+    },
+    "clones": {
+      "type": "object",
+      "propertyNames": { "type": "string", "pattern": "^[^\\s@/][^\\s@]*/[^\\s@]+$" },
+      "additionalProperties": { "type": "string", "minLength": 1 },
+      "description": "<repo key>: <path on this machine> for member clones outside the convention."
+    },
+    "settings": {
+      "type": "object",
+      "propertyNames": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+      "additionalProperties": {
+        "type": "object",
+        "propertyNames": { "type": "string", "pattern": "^[A-Za-z][A-Za-z0-9_.-]*$" }
+      },
+      "description": "<capability>: { <key>: <value> } host-owned values the manifests ask for."
+    },
+    "souls": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "disabled": {
+          "type": "array",
+          "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }
+        }
+      }
+    }
+  }
+}

package/docs/oats-membership.schema.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oats.dev/schemas/membership-v2.json",
+  "title": "Repository membership backlink v2 (oats-membership.yaml)",
+  "description": "The repo's half of the reciprocal handshake: it names the workspace it belongs to, plus an optional default team label for the repo's items. Nothing else. A backlink is consent, not admission — the workspace must list the repo too.",
+  "type": "object",
+  "required": ["schemaVersion", "workspace"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "workspace": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?:git@[^@\\s]+|[^@\\s]+)$",
+      "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."
+    }
+  }
+}

package/docs/oats-workspace.schema.json

@@ -1,68 +1,153 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://oats.dev/schemas/workspace-v1.json",
-  "title": "Portable workspace definition v1",
-  "description": "Data shape only; hosting identity, reciprocal membership and provider readiness are verified separately.",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oats.dev/schemas/workspace-v2.json",
+  "title": "Workspace declaration v2 (oats-workspace.yaml)",
+  "description": "Data shape only. Members carry NO revision (a member is always its latest state); `external` sources REQUIRE a full 40-hex commit; absolute filesystem paths are refused anywhere in this file (host paths belong in oats-local.yaml). Reciprocal membership is observed over Git remotes, not declared here.",
   "type": "object",
   "required": ["schemaVersion", "name"],
   "additionalProperties": false,
   "properties": {
-    "schemaVersion": { "const": 1 },
-    "name": { "type": "string", "minLength": 1 },
-    "members": { "type": "array", "items": { "$ref": "#/$defs/repository" } },
-    "defaults": { "$ref": "https://oats.dev/schemas/soul-v1.json#/$defs/defaults" },
-    "knowledge": {
-      "type": "object", "required": ["stores"], "additionalProperties": false,
-      "properties": { "stores": { "type": "array", "items": { "$ref": "https://oats.dev/schemas/soul-v1.json#/properties/knowledge" } } }
+    "schemaVersion": { "const": 2 },
+    "name": { "$ref": "#/$defs/slug" },
+    "members": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": { "$ref": "#/$defs/memberRef" },
+      "description": "Repo refs without revision. Each becomes a member only when its oats-membership.yaml names this workspace back."
+    },
+    "packages": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/packageId" },
+      "additionalProperties": { "$ref": "#/$defs/packageVersion" },
+      "description": "The ONLY versioned things: <package-id>: <version | git ref with @revision>."
     },
     "teams": {
-      "type": "object", "propertyNames": { "$ref": "#/$defs/alias" },
-      "properties": { "private": { "const": "per-human" } },
-      "additionalProperties": {
-        "type": "object", "required": ["provider", "id"], "additionalProperties": false,
-        "properties": { "provider": { "$ref": "https://oats.dev/schemas/soul-v1.json#/$defs/capability" }, "id": { "type": "string", "minLength": 1 } }
-      }
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/label" },
+      "additionalProperties": { "$ref": "#/$defs/team" },
+      "description": "Org team labels. A label never gates, restricts or partitions anything."
+    },
+    "defaults": { "$ref": "#/$defs/defaults" },
+    "stores": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/slug" },
+      "additionalProperties": { "$ref": "#/$defs/memberRef" },
+      "description": "Knowledge stores, declared once: <name>: <repo ref>."
     },
-    "catalogs": {
-      "type": "array", "items": {
-        "type": "object", "required": ["source"], "additionalProperties": false,
-        "properties": { "source": { "$ref": "#/$defs/source" }, "revision": { "$ref": "#/$defs/revision" }, "path": { "$ref": "#/$defs/path" } }
+    "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).",
+      "properties": {
+        "byTeam": {
+          "type": "object",
+          "propertyNames": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+          "additionalProperties": { "type": "object" }
+        }
       }
     },
-    "imports": { "type": "array", "items": { "$ref": "#/$defs/import" } }
+    "external": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/external" },
+      "description": "Souls adopted by reference from repos that are NOT members; pinned to a full commit."
+    }
   },
   "$defs": {
-    "source": { "type": "string", "pattern": "^git:.+$" },
-    "revision": { "type": "string", "minLength": 1 },
-    "path": { "type": "string", "minLength": 1, "description": "Canonical contained repository-relative path; the shared source codec enforces semantic path rules." },
-    "alias": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" },
-    "repository": {
-      "type": "object", "required": ["source"], "additionalProperties": false,
-      "properties": { "source": { "$ref": "#/$defs/source" }, "revision": { "$ref": "#/$defs/revision" } }
+    "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "label": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+    "capabilityName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+    "packageId": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+    "packageVersion": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?:v?\\d+(?:\\.\\d+)*(?:[-+][0-9A-Za-z.-]+)?|git:(?:git@[^@\\s/:]+:)?[^@\\s]+@(?:[0-9a-f]{40}|(?!-)(?!.*(?:\\.\\.|@\\{|\\^|~|:|\\?|\\*|\\[|\\\\|\\.lock$|\\.$|/$|^/))[!-?A-~]+))$",
+      "description": "Exactly two forms: a bare version (v2.1.3) resolved through the catalog, or git:<repo>@<ref> (a direct package ref). lib/packages.mjs#classifyPackageValue is the full grammar."
+    },
+    "memberRef": {
+      "type": "string",
+      "minLength": 1,
+      "pattern": "^(?:git@[^@\\s]+|[^@\\s]+)$",
+      "description": "A repo ref (git:<host>/<path>, https://…, git@host:path.git, file:///…) with NO @revision."
+    },
+    "pinnedRef": {
+      "type": "string",
+      "pattern": "^(?:git@[^@\\s]+|[^@\\s]+)@[0-9a-f]{40}$",
+      "description": "<repo ref>@<full 40-hex commit OID>."
+    },
+    "repoKey": {
+      "type": "string",
+      "pattern": "^[^\\s@/][^\\s@]*/[^\\s@]+$",
+      "description": "Canonical repo identity <host>/<path> (or local/<abs-path> for file remotes), as produced by parseRepoRef(...).key."
     },
-    "import": {
-      "type": "object", "required": ["source", "soul", "revision", "alias"], "additionalProperties": false,
+    "fromLocation": {
+      "anyOf": [
+        { "const": "package" },
+        { "const": "here" },
+        { "$ref": "#/$defs/repoKey" }
+      ],
+      "description": "WHERE a capability comes from — a location, never a version."
+    },
+    "capabilityRef": {
+      "type": "object",
+      "required": ["from"],
+      "additionalProperties": false,
+      "properties": { "from": { "$ref": "#/$defs/fromLocation" } }
+    },
+    "capabilityChoice": { "anyOf": [{ "$ref": "#/$defs/capabilityRef" }, { "const": "off" }] },
+    "capabilityMap": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/capabilityName" },
+      "additionalProperties": { "$ref": "#/$defs/capabilityChoice" }
+    },
+    "slotDefault": {
+      "anyOf": [
+        { "const": "none" },
+        {
+          "type": "object",
+          "maxProperties": 1,
+          "propertyNames": { "$ref": "#/$defs/capabilityName" },
+          "additionalProperties": { "$ref": "#/$defs/capabilityRef" }
+        }
+      ],
+      "description": "At most one capability fills a slot; `none` leaves it empty."
+    },
+    "team": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": { "description": { "type": "string" } }
+    },
+    "defaults": {
+      "type": "object",
+      "additionalProperties": false,
       "properties": {
-        "source": { "$ref": "#/$defs/source" },
-        "soul": { "$ref": "#/$defs/path" },
-        "revision": { "$ref": "#/$defs/revision" },
-        "alias": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
-        "adoption": {
-          "type": "object", "additionalProperties": false,
-          "properties": {
-            "teamAliases": { "type": "object", "propertyNames": { "$ref": "#/$defs/alias" }, "additionalProperties": { "$ref": "#/$defs/alias" } },
-            "providers": {
-              "type": "object", "additionalProperties": false,
-              "properties": {
-                "knowledge": { "$ref": "https://oats.dev/schemas/soul-v1.json#/$defs/defaultProvider" },
-                "messaging": { "$ref": "https://oats.dev/schemas/soul-v1.json#/$defs/defaultProvider" },
-                "tasks": { "$ref": "https://oats.dev/schemas/soul-v1.json#/$defs/defaultProvider" }
-              }
-            },
-            "bindings": { "type": "object" }
+        "capabilities": { "$ref": "#/$defs/capabilityMap" },
+        "knowledge": { "$ref": "#/$defs/slotDefault" },
+        "messaging": { "$ref": "#/$defs/slotDefault" },
+        "tasks": { "$ref": "#/$defs/slotDefault" },
+        "byTeam": {
+          "type": "object",
+          "propertyNames": { "$ref": "#/$defs/label" },
+          "additionalProperties": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": { "capabilities": { "$ref": "#/$defs/capabilityMap" } }
           }
         }
       }
+    },
+    "external": {
+      "type": "object",
+      "required": ["source", "soul"],
+      "additionalProperties": false,
+      "properties": {
+        "source": { "$ref": "#/$defs/pinnedRef" },
+        "soul": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^(?![A-Za-z]:)(?!/)(?!.*(?:^|/)\\.{1,2}(?:/|$))[^/\\\\\u0000]+(?:/[^/\\\\\u0000]+)*$",
+          "description": "Repository-relative directory holding the soul's soul.yaml."
+        },
+        "team": { "$ref": "#/$defs/label" }
+      }
     }
   }
 }

package/docs/official-marketplace.md

@@ -10,14 +10,17 @@ or workspace membership alone does not make a package official.
 - Browse the catalog for the kernel/source version you use. Each package entry
   identifies its repository, release ref and payload root; capability aliases
   can point to the package that supplies them.
-- Today, `oats install <capability-or-package-id>` resolves official short names
-  through the CLI's catalog. For example, `oats install oats.okf --dir /absolute/scope`
-  selects the listed package; it does not enroll a team or adopt
-  the publisher's workspace. See [package operations](packages.md).
+- 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>`.
+  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 ≠ installed ≠ approved.** Acquisition and exact locking are
-  separate from capability selection and per-capability executable approval.
+- **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.
   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,