@awebai/oats 0.24.12 → 0.25.0

package/docs/rebuild-to-v2.md

@@ -0,0 +1,233 @@
+# Rebuilding a 0.24.x deployment for the workspace model (0.25)
+
+The workspace model ([workspaces.md](workspaces.md)) is a **clean v2**: no
+converter, no dual-schema reader, no `oats migrate`. This guide is what ships
+instead (decision 15 of `workspace-model-v2`). It is short because the new
+surface is small: three shared files, one local file, one command.
+
+## 0. 0.24.x keeps working
+
+A 0.24.x kernel keeps spawning 0.24.x deployments indefinitely. Nothing forces
+the move: install 0.25 when you are ready to rebuild, not before. A 0.25 kernel
+reads only v2 files — a 0.24 `oats-workspace.yaml` (`schemaVersion: 1`), a
+`soul.yaml` with `requires:`/`source:`, an `oats.yaml`, an `oats-config.yaml` or
+a lock v1/v2 is an error **naming the schema** (`E_WORKSPACE_SCHEMA "… reads
+schemaVersion 2 only; found 1"`, `E_LOCK_SCHEMA`), never a silent fallback.
+Keep the 0.24 kernel installed until the last 0.24 deployment you care about is
+rebuilt; the two do not share files.
+
+## 1. Decide the one workspace
+
+One workspace per organisation. Pick the repo that **hosts**
+`oats-workspace.yaml` (a dedicated `agents` repo is common; any member can host
+it). Decide the team labels you want (`global`, `engineering`, …) — labels
+organise and may add defaults; they never gate anything.
+
+**If any member is private, host the workspace file in a private repo that is
+not a public member.** The workspace file names every member, so whoever can
+read it sees the member list: a public host would publish the private repo's
+name; hosting inside the private member hides the workspace from public
+contributors entirely. A dedicated private repo (`<org>/workspace`) is the
+honest shape. Public contributors who can read a public member but not the
+host still get that member's souls through the standalone case (`from: here`
+capabilities plus `oats.core`), so a public soul stays usable.
+
+Two teams that need two different messaging identities (an open-source team
+and a hosted-operations team, say) stay in ONE workspace: `team:` is a label,
+and the provider payload is addressed by label under `messaging.byTeam` (§2).
+
+## 2. Write `oats-workspace.yaml` v2 in the host repo
+
+Start from the 0.24 file and rewrite it:
+
+| 0.24 | v2 |
+|---|---|
+| `schemaVersion: 1` | `schemaVersion: 2` |
+| `members: [{ source: git:… }]` | `members: [git:…]` — plain refs, **no** `@revision` |
+| `imports:` of your **own** repos' souls | delete — member souls are discovered by convention |
+| `imports:` of a **stranger's** soul (with `revision`) | `external: [{ source: git:<repo>@<full OID>, soul: <path> }]` |
+| `teams: { private: per-human }` (the messaging payload) | `messaging: { private: per-human }`; `teams:` now declares **labels** |
+| `defaults.knowledge: { capability, source }` | `defaults.knowledge: { <cap>: { from: package } }` (one entry, or `none`) |
+| per-soul `stores.<x>.inherit` | `stores: { <name>: git:<repo> }` once, here |
+| `catalog:` | delete (bare versions use the official catalog; `OATS_PACKAGE_CATALOG` overrides) |
+| — | `packages: { <id>: <version> \| git:<repo>@<ref> }` — every version your souls used to carry in `source:` lines, **once** |
+| — | `defaults.capabilities: { oats.core: { from: package } }` and whatever every soul should get |
+
+```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.3
+  oats.aweb: v1.11.2
+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
+```
+
+No absolute paths anywhere (they belong in `oats-local.yaml`). `from:` values
+that name a repo are **canonical keys** — `github.com/acme/agents`, not
+`git:github.com/acme/agents` and not `https://…`.
+
+## 3. Add `oats-membership.yaml` to every member (replaces `oats.yaml`)
+
+```yaml
+schemaVersion: 2
+workspace: git:github.com/acme/agents
+team: engineering          # optional default label for this repo's souls/capabilities
+```
+
+Delete `oats.yaml`. Its `exports:` lists are gone: every `souls/*/soul.yaml` and
+`capabilities/*/oats.json` is discoverable; add `private: true` to the ones that
+should stay internal. The host repo backlinks to itself like any member.
+
+## 4. Edit every `soul.yaml` to v2
+
+| 0.24 | v2 |
+|---|---|
+| `schemaVersion: 1` | `schemaVersion: 2` |
+| `requires.knowledge: { capability: oats.okf, source: git:…@v2.1.3#oats-package }` | `capabilities: { oats.okf: { from: package } }` — or nothing, if the workspace default already says so |
+| `requires.capabilities.<cap>: { source: git:… }` | `<cap>: { from: package }` (published) or `<cap>: { from: here }` / `{ from: <repo key> }` (a member capability) |
+| `source: repo:…` / `path:` | `{ from: here }` |
+| `defaults.capabilities` | fold into `capabilities:`; use `off` to remove a workspace default |
+| `stores.inherit` | delete (stores are declared once in the workspace) |
+| `imports` | delete |
+| `kind`, `type`, `repo`, `runtime`, `model`, `launch-config` | delete — model/runtime/launch config are spawn-time choices; `team:` replaces `type:` as the grouping |
+| `knowledge:` / `messaging:` payload | keep as is (opaque provider payload); `none` empties the slot |
+| — | `compatibility: { <cap>: ">=x.y" }` if you want a floor |
+
+```yaml
+schemaVersion: 2
+name: release-manager
+description: Cuts, verifies and announces releases.
+work: worktree
+team: engineering
+capabilities:
+  acme-release-tooling: { from: here }
+knowledge:
+  owns: release-manager
+  reads: [platform-engineer]
+messaging:
+  channels: [acme-eng]
+```
+
+`name` must equal the soul's directory name; `name`, `description` and `work`
+are required. Capabilities the repo exports live at
+`capabilities/<name>/oats.json` — the manifest is unchanged; you may add
+`private: true` / `team:`.
+
+## 5. Write `oats-local.yaml` on each machine
+
+```
+~/acme-workspace/                 # the taught convention: "<name>-workspace"
+├── oats-local.yaml
+├── agents/                       # instance homes
+└── platform/                     # member clones, only where someone works IN them
+```
+
+```yaml
+schemaVersion: 2
+workspace: git:github.com/acme/agents
+settings:                                   # what used to be `settings:` under capabilities.layers.* in oats-config.yaml
+  oats.okf:
+    bindings-file: /Users/ana/.oats/okf-bindings.json
+    state-dir: /Users/ana/.oats/okf
+souls:
+  disabled: [data-analyst]
+```
+
+Move host paths from `oats-config.yaml` `settings:` here; the `souls:` blocks of
+`oats-config.yaml` become `--provider` flags at spawn (step 8). Delete
+`oats-config.yaml`; it is not read. Do not commit `oats-local.yaml`.
+(`oats onboard <dir> --workspace <repo ref>` writes a minimal `oats-local.yaml`
+and runs the first `sync` for you; add `settings:` afterwards.)
+
+## 6. `oats sync`
+
+From the deployment directory:
+
+```
+oats sync
+```
+
+It confirms every member (fix any `no-backlink` / `backlink-elsewhere` /
+`cannot-read` row before going on), resolves `packages:` to commits, writes
+`oats-lock.json` (lockfileVersion 3) and asks for executable approval once per
+package version. The 0.24 lock is not read; delete it (`E_LOCK_SCHEMA` names
+it if you leave it in the way).
+
+## 7. Approve packages
+
+Approval is **per package version, once, in the lock** — no `oats trust`, no
+per-capability approval, no per-operator trust list. `oats sync` on a terminal
+prints every executable (`commands.*` and `hooks.*.command` targets of every
+capability the package provides) and asks `approve <id> <version>? [y/N]`.
+Declined or non-interactive → exit `2`, the lock records the entry
+unapproved, and spawns of souls using it are refused (`E_PACKAGE_UNAPPROVED`)
+until you run `oats sync` in a terminal and say yes. Member capabilities need no
+approval: membership is the trust.
+
+## 8. Re-take a retained messaging seat with `spawn --provider`
+
+In 0.24, an instance-specific messaging identity (a retained seat) was pinned in
+`oats-config.yaml` under `souls:`. That home is gone; the fact belongs to the
+**spawn**:
+
+```bash
+oats spawn release-manager --purpose seat --provider oats.aweb identity.source=retained:release-seat
+```
+
+`--provider <cap> key=value` is repeatable; dotted keys nest. The payload is
+merged after the soul's `messaging:` and the machine's `settings.oats.aweb`, and
+recorded in `instance.json.providers.oats.aweb`, so exactly one instance holds
+the seat while other instances of the soul mint fresh identities. Consult your
+messaging capability's documentation for the exact key it reads. The Desktop's
+confirmed apply carries the same map.
+
+## 9. Spawn, and check drift
+
+```bash
+oats souls                    # every non-private soul of every confirmed member, with origin and team
+oats capabilities             # every capability, member (origin: member <key> @ <commit>) or package (package <id> v<ver>)
+oats spawn <soul> --preview   # modules[] with from/commit/changedSince, team, resolution revision
+oats spawn <soul> --purpose x
+oats status                   # per instance: modules … [member moved since (now @ …)] / [capability no longer present]
+```
+
+## What disappears
+
+| Gone | Replaced by |
+|---|---|
+| `oats-config.yaml` (and the laptop/workspace/repo config chain, `agent-types`, `capabilities.layers`/`additive`, `souls:`, adopted config templates) | `oats-workspace.yaml` defaults + `soul.yaml` `capabilities:`; `oats-local.yaml` for host settings; `spawn --provider` for per-instance facts |
+| `oats.yaml` | `oats-membership.yaml` |
+| `.agents/capabilities/installed/` and `owned/` | nothing is installed; `<instance>/.oats/modules/<cap>/` per instance; member capabilities under `<repo>/capabilities/` |
+| `oats init`, `oats use`, `oats install`, `oats restore`, `oats trust`, `oats list`, `oats catalog`, `oats remove`, `oats migrate`, `oats config` | `oats sync`, `oats package add \| remove`, `oats workspace status`, `oats capabilities`, `oats souls` — each removed verb answers `E_UNKNOWN_COMMAND` naming its replacement |
+| lock v1 / v2 | lock v3 (`packages` only, with `url`, `capabilities`, `approved`) |
+| per-soul `source: git:…@v#…`, `repo:`, `path:` | `from: here \| <repo key> \| package` + `packages:` in the workspace |
+| `imports:` of member souls, `exports:` lists | discovery by convention; `private: true` |
+| `stores.<x>.inherit` | `stores:` in the workspace |
+| `teams:` as the messaging payload | `messaging:`; `teams:` are labels |
+| `@revision` on members | none — members are latest; frozen content is a package |
+| ambient-skill exclusion at launch | the harness starts normally; capability skills are copied to `.agents/skills/<cap>/` |
+
+## What is kept
+
+Kernel-neutral provider payloads and the `binding` contract; per-version
+executable approval (now in the lock); spawn preview / confirmed apply
+(`decision.revision`, now binding the resolution revision) and idempotency;
+retirement and retention; the official catalog; the canonical-plus-alias
+instance construction (`CLAUDE.md → AGENTS.md`, `.claude/skills →
+../.agents/skills`); every published Desktop CLI contract, extended as described
+in [desktop-cli-api.md](desktop-cli-api.md#workspace-model-workspaceapi-2).

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

@@ -0,0 +1,51 @@
+# OATS v0.24.13 — schedule history API 3 and the Desktop schedules table
+
+Kernel/Pi/Desktop **0.24.13**. Tag `v0.24.13` → the commit carrying these
+notes; the version-bump commit lands after the tag. Consumers gate on
+`oats version --json` `features[]` names and API integers — never on the version.
+
+## Kernel — `schedule-read-2` (`scheduleHistoryApi: 3`; `scheduleApi` stays 2)
+
+`oats schedule list|show` history had four defects found by the Desktop
+engineer's exact-source review; each is closed under a new advertised name.
+
+- **A run's identity is when it was scheduled and started, never its outcome.**
+  `runId = sha256(scheduledFor|startedAt|attemptId)[0:24]`; a run's later facts
+  update its one row; `transitions[]` keeps the outcome sequence
+  (`["started","unknown","ended"]` is one run, not three); `settled`,
+  `recordedAt`. Pre-API-3 rows are returned `legacy: true` with `runId: null`
+  and are never merged.
+- **Bounded, descriptor-safe state.** Both scope files are `lstat`ed (regular
+  file only), opened `O_NOFOLLOW|O_NONBLOCK`, `fstat`-verified (dev+ino) and
+  read whole **only within a 1 MiB budget** — over budget is a typed
+  `E_SCHEDULE_STATE_OVERSIZE` refusal, never truncated JSON. `list` carries
+  `integrity.sources[]`; history is capped at 50 rows at read
+  (`history: {status, stored, truncated}`); one job's corrupt history or bad
+  identity is its own row and never fails the others.
+- **Subject truth.** `list`/`show` echo the resolved `scope` and canonical `id`;
+  a definition whose own `id` differs from its key → `E_SCHEDULE_IDENTITY`; ids
+  are validated before any read. Typed refusal details travel through the CLI's
+  JSON failure.
+- **Session provenance, never a transcript.** The `transcript` pointer named a
+  reader that does not exist and is gone. Every run carries
+  `session: {instance|null, home|null, incarnation|null, server|null, delivery}`
+  — what the recorder knew at write time. A read-only transcript verb is a
+  separate seam (K12), not implied by this API.
+
+## Desktop
+
+- **Schedules** view: the compact table (enabled, schedule, target, cadence,
+  next run, last reported outcome, actions) with **Recent runs** for the
+  workspace (≤50), read once on entry and on explicit Refresh — no polling.
+  History enables nothing; `ended` is not success and `delivered` is not
+  consumption; missing time facts are shown as unreported. Session provenance
+  is displayed with a precise unavailable reason — no transcript, terminal or
+  link. Remote history and editing a captured wake are shown as honest
+  limitations. Gated on `scheduleHistoryApi === 3` and `schedule-read-2`.
+- **Security**: the command-running `GET /api/schedules` is removed (405, no
+  command, no default workspace); legacy POST `list|show` aliases run through
+  the same strict admission, budgets and two coalesced read slots.
+
+## Upgrade
+
+`npm i -g @awebai/oats@0.24.13`, then `oats doctor`.

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

@@ -0,0 +1,99 @@
+# OATS v0.25.0 — the workspace model (breaking)
+
+Kernel/Pi **0.25.0**. Tag `v0.25.0` → the commit carrying these notes; the
+version-bump commit lands after the tag. Consumers gate on `oats version --json`
+`features[]` names and API integers — never on the version.
+
+**This is the 0.25 line: a new deployment model, not a patch to the old one.**
+0.24.x keeps spawning 0.24.x deployments; there is no converter. The rebuild
+guide is `docs/rebuild-to-v2.md`. Design: `docs/design/2026-09-23-simplified-workspace-model.md`;
+decision record (26 decisions): `agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md`;
+normative module contracts: `docs/design/2026-09-23-workspace-module-contracts.md`.
+
+## The one idea
+
+An organisation has **one workspace**: a Git repo hosting `oats-workspace.yaml`
+that lists its **member repositories**, pins its **packages**, names its
+**teams** and declares **defaults**. Every member carries an
+`oats-membership.yaml` back-link; the handshake is confirmed over the Git
+remotes in the operator's own access context and **membership is the trust**.
+A member exports **souls** (`souls/<name>/soul.yaml`) and **capabilities**
+(`capabilities/<name>/oats.json`) at its latest commit; a soul says where each
+capability comes from (`from: <member repo> | here | package`). Packages are
+consumed only through `packages:` + `oats-lock.json` v3, with **per-version
+executable approval**. A spawn **resolves** the soul (`lib/resolve.mjs`) and
+**materializes** every capability whole into the instance
+(`<home>/.oats/modules/<cap>/`, skills under `<home>/.agents/skills/<cap>/`);
+the harness starts normally. Nothing is installed anywhere.
+
+## Kernel — `workspace-v2` (`workspaceApi: 2`), `instance-modules`, `spawn-provider-payload`
+
+- **Declarations** (`docs/*.schema.json`, all `schemaVersion: 2`):
+  `oats-workspace.yaml` (members, packages, teams, defaults incl. `byTeam`,
+  stores, `messaging` incl. `byTeam.<label>`, external souls),
+  `oats-membership.yaml` (`workspace`, `team?`), `soul.yaml` v2
+  (`capabilities: { <cap>: { from } | off }`, `team`, `private`,
+  `compatibility`, slot payloads), `oats-local.yaml` (the ONLY per-machine
+  file: `workspace:` or `standalone:` ref, `clones`, `settings.<cap>`,
+  `souls.disabled`).
+- **`oats sync`** — discover → confirm membership → resolve packages → write
+  `oats-lock.json` v3; unapproved executables listed, exit 2 non-TTY / prompt
+  on a TTY. `oats package add|remove`, `oats workspace status`,
+  `oats capabilities`, `oats souls` (origin + team columns).
+- **`oats spawn`** — discovers and resolves over the remotes, fetches the soul
+  from its member repo (refreshed per commit), materializes, launches.
+  `--preview` works before any apply and reports `modules[]` (with
+  `changedSince`), `team`, `resolution`, `workspace`, `soulFetched`; the
+  decision binds the resolution revision (a member that moved between preview
+  and apply → `E_DECISION_STALE`). `--provider <cap> k=v` records a per-spawn
+  provider payload (`instance.json.providers`) — the third payload home after
+  the soul and `oats-local.yaml settings`.
+- **`instance.json`** carries `modules{}` (name → from/commit/digest),
+  `providers{}`, `workspace{ key, commit, resolution, standalone, soul }`,
+  `capabilities[]`.
+- **`oats status`** shows drift per instance (`member moved since …`,
+  `capability no longer present`); `--json` `instances[].modules[]`.
+- **`oats onboard [<dir>] --workspace <ref>`** — writes `oats-local.yaml`,
+  runs the sync path, prints the taught layout and the **hosting rule** for
+  mixed public/private organisations (`onboardApi: 2`). Creates no soul,
+  spawns nothing.
+- **Standalone case** — a member whose workspace cannot be read (access
+  failure only, never network/timeout) still offers its souls with `from: here`
+  capabilities **plus `oats.core`** from the official catalog through the
+  operator's own lock; marked `standalone: true` in sync/status/spawn output.
+- **Teams** are labels; per-team provider payload is `messaging.byTeam.<label>`
+  (merged by the kernel, stripped before the provider). A store names a
+  repository; the root inside it is the provider's binding key.
+- **Scheduled spawns** on a workspace deployment materialize exactly like
+  `oats spawn` (the scheduler delegates to the CLI).
+- **Security** (found by adversarial review, all pinned): remote tree names
+  fsck'd (no traversal), tag naming a blob refused as a commit, symlinks in
+  fetched trees refused except the soul's `CLAUDE.md → AGENTS.md` alias,
+  `__proto__`/`constructor`/`prototype` refused at every payload layer and in
+  `--provider` flags, `byTeam` reserved outside `workspace.messaging`, package
+  executables gated on per-version approval, atomic staging with full
+  rollback (no half homes).
+
+## Removed
+
+`oats init`, `use`, `install`, `trust`, `list`, `remove`, `migrate`, `catalog`,
+`update`, `config`, `inject` → typed `E_UNKNOWN_COMMAND` naming the
+replacement. `oats-config.yaml` is no longer read as configuration (a leftover
+one is harmless); the `installed/` tier, `oats.yaml`, `lockfileVersion` 2,
+per-soul `source: git:…` lines, `stores.inherit`, `imports`. The `catalog`
+feature name is gone from `version --json`. `docs/configuration.md` now
+describes `oats-local.yaml` only.
+
+## Desktop
+
+The Desktop server's `oats catalog` reader now surfaces `E_USAGE` (the verb is
+removed); the Capabilities view's package acquisition flow will follow the new
+DTOs in a later release (Phase F). Everything else in the Desktop is unchanged.
+
+## Known follow-ups
+
+- The classic (no `oats-local.yaml`) spawn path still runs the pre-v2 compose
+  in `lib/core.mjs`; folding it into the one pipeline removes the remaining v1
+  modules (residue table in `docs/design/2026-09-23-workspace-v2-implementation-plan.md`).
+- The OATS framework repositories themselves convert to the model (six expert
+  souls, `oats.core`/`oats.setup` rewritten for the new architecture) in 0.26.

package/docs/soul.schema.json

@@ -1,82 +1,55 @@
 {
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://oats.dev/schemas/soul-v1.json",
-  "title": "Portable soul declaration v1",
-  "description": "Authored shape only. The shared source codec, provider codec and preparation transaction enforce source semantics, containment, requirements and readiness.",
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://oats.dev/schemas/soul-v2.json",
+  "title": "Soul declaration v2 (soul.yaml)",
+  "description": "Authored shape only. A soul names each capability WITH WHERE IT COMES FROM (`from: here | <repo key> | package`) — a location, never a version. Provider payloads (knowledge, messaging, tasks) are opaque to the kernel; `none` empties the slot. Membership, privacy and team semantics are enforced by discovery/resolution, not here.",
   "type": "object",
-  "required": ["schemaVersion", "name"],
+  "required": ["schemaVersion", "name", "description", "work"],
   "additionalProperties": false,
   "properties": {
-    "schemaVersion": { "const": 1 },
-    "name": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "schemaVersion": { "const": 2 },
+    "name": { "$ref": "#/$defs/slug" },
     "description": { "type": "string" },
-    "requires": { "$ref": "#/$defs/requirements" },
-    "defaults": { "$ref": "#/$defs/defaults" },
-    "knowledge": {
+    "work": { "enum": ["worktree", "checkout", "directory", "workspace"] },
+    "team": { "$ref": "#/$defs/label", "description": "Team label; overrides the repo's default from oats-membership.yaml." },
+    "private": { "type": "boolean", "description": "true → not discoverable in the workspace; usable only from its own repo." },
+    "capabilities": {
       "type": "object",
-      "required": ["contract", "version", "payload"],
-      "additionalProperties": false,
-      "properties": {
-        "contract": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" },
-        "version": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
-        "payload": {}
-      }
-    },
-    "teams": {
-      "type": "array", "uniqueItems": true,
-      "items": { "type": "string", "pattern": "^[a-zA-Z0-9][a-zA-Z0-9._-]*$" }
+      "propertyNames": { "$ref": "#/$defs/capabilityName" },
+      "additionalProperties": { "$ref": "#/$defs/capabilityChoice" }
     },
-    "resources": {
-      "type": "array", "uniqueItems": true,
-      "items": { "type": "string", "pattern": "^(?:\\.|(?![A-Za-z]:)(?!.*(?:^|/)\\.{1,2}(?:/|$))[^/\\\\\u0000]+(?:/[^/\\\\\u0000]+)*)$" }
-    },
-    "work": { "enum": ["worktree", "checkout", "attached", "workspace", "directory"] },
-    "runtime": { "enum": ["pi", "claude", "codex"] },
-    "model": { "type": "string", "minLength": 1 },
-    "launch-config": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" },
-    "backend": { "enum": ["tmux", "herdr"] },
-    "yolo": { "type": "boolean" }
+    "knowledge": { "$ref": "#/$defs/slotPayload" },
+    "messaging": { "$ref": "#/$defs/slotPayload" },
+    "tasks": { "$ref": "#/$defs/slotPayload" },
+    "compatibility": {
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/capabilityName" },
+      "additionalProperties": { "type": "string", "minLength": 1 },
+      "description": "Optional FLOORS on package versions (semver ranges) — constraints, not sources."
+    }
   },
   "$defs": {
-    "source": { "type": "string", "pattern": "^(git|repo|path):.+$" },
-    "capability": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
-    "selection": {
-      "type": "object", "required": ["source"], "additionalProperties": false,
-      "properties": { "source": { "$ref": "#/$defs/source" }, "settings": { "type": "object" } }
-    },
-    "provider": {
-      "type": "object", "required": ["capability", "source"], "additionalProperties": false,
-      "properties": {
-        "capability": { "$ref": "#/$defs/capability" },
-        "source": { "$ref": "#/$defs/source" },
-        "settings": { "type": "object" }
-      }
+    "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._-]*$" },
+    "repoKey": { "type": "string", "pattern": "^[^\\s@/][^\\s@]*/[^\\s@]+$" },
+    "fromLocation": {
+      "anyOf": [
+        { "const": "package" },
+        { "const": "here" },
+        { "$ref": "#/$defs/repoKey" }
+      ]
     },
-    "requiredProvider": { "anyOf": [{ "const": "any" }, { "$ref": "#/$defs/provider" }] },
-    "defaultProvider": { "anyOf": [{ "const": "none" }, { "$ref": "#/$defs/provider" }] },
-    "requirements": {
-      "type": "object", "additionalProperties": false,
-      "properties": {
-        "capabilities": {
-          "type": "object", "additionalProperties": false,
-          "patternProperties": { "^[a-z0-9][a-z0-9._-]*$": { "$ref": "#/$defs/selection" } }
-        },
-        "knowledge": { "$ref": "#/$defs/requiredProvider" },
-        "messaging": { "$ref": "#/$defs/requiredProvider" },
-        "tasks": { "$ref": "#/$defs/requiredProvider" }
-      }
+    "capabilityRef": {
+      "type": "object",
+      "required": ["from"],
+      "additionalProperties": false,
+      "properties": { "from": { "$ref": "#/$defs/fromLocation" } }
     },
-    "defaults": {
-      "type": "object", "additionalProperties": false,
-      "properties": {
-        "capabilities": {
-          "type": "object", "additionalProperties": false,
-          "patternProperties": { "^[a-z0-9][a-z0-9._-]*$": { "anyOf": [{ "$ref": "#/$defs/selection" }, { "const": false }] } }
-        },
-        "knowledge": { "$ref": "#/$defs/defaultProvider" },
-        "messaging": { "$ref": "#/$defs/defaultProvider" },
-        "tasks": { "$ref": "#/$defs/defaultProvider" }
-      }
+    "capabilityChoice": { "anyOf": [{ "$ref": "#/$defs/capabilityRef" }, { "const": "off" }] },
+    "slotPayload": {
+      "anyOf": [{ "const": "none" }, { "type": "object" }],
+      "description": "Opaque provider payload, or `none` to leave the slot empty."
     }
   }
 }