@awebai/oats 0.25.9 → 0.27.0

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

@@ -0,0 +1,100 @@
+# OATS 0.27.0
+
+What starts an instance (pi, claude or codex) is now called its **harness**
+everywhere the kernel used to say `runtime`: in flags, configuration, records,
+JSON and error codes. Nothing already written stops working. The rule is read
+either, write new: every spelling from before 0.27.0 is still read, and the
+next write records the new one. A command that reads an old spelling answers
+one `deprecated-runtime-name` warning, and a later release drops the old
+spellings. See [Upgrading from 0.26](#upgrading-from-026).
+
+## Changed
+
+- **runtime → harness.** [The Desktop CLI API](../desktop-cli-api.md#the-harness-rename-feature-harness-oats-0270)
+  has the complete table. In short:
+  - Flags: `--harness` replaces `--runtime` on `spawn` (and `--preview`),
+    `session start|restart` and `launch-config preview`, including their
+    `--server` forms. `--runtime` is still accepted, with the warning. The
+    two given with different values are refused (`E_BAD_ARGS`).
+  - `oats-local.yaml`: a launch configuration names `harness:`. `runtime:` is
+    still read, with the warning. Both, disagreeing, is a schema error
+    (`E_WORKSPACE_SCHEMA`). `oats launch-config set` writes `harness`.
+  - Schedules: a spawn job names `harness`. A job stored with `runtime` is
+    read as `harness`, with the warning, and saved in the new name next time.
+    Both, disagreeing, makes that job invalid (`E_SCHEDULE_INVALID`).
+    `lastRun`/`recentRuns` record `startedHarness` (was `startedRuntime`).
+  - Homes: `instance.json` records `harness`, and the launch recipe is version
+    **2** (`harness`; version 1 said `runtime`). A home spawned by 0.26.0 is
+    read in the new names, with the warning naming the home. It inspects,
+    starts, restarts and retires as before, and its next start or restart
+    records the new names.
+  - `soul.yaml` names `harness:`. `runtime:` is still read, **without** a
+    warning, because released capabilities ship it (oats.aweb 1.13.1's agents)
+    and an operator cannot fix a provider's file. Both, disagreeing:
+    `E_BAD_MANIFEST`. The same holds for a capability manifest's
+    `requires[]` harness package (`harness`, or `runtime`, never both).
+  - Hooks get `OATS_HARNESS` and `OATS_PREVIOUS_HARNESS` beside
+    `OATS_RUNTIME` and `OATS_PREVIOUS_RUNTIME`, with the same values.
+  - JSON outputs speak only the new names:
+    - `oats version --json` lists `harnesses` (no `runtimes`) and the feature
+      `harness`;
+    - `harness` replaces `runtime` in the status, inspect, spawn, preview,
+      session, launch-config, schedule and event documents;
+    - `harnessPackages` and `harnessPosture` replace `runtimePackages` and
+      `runtimePosture` in `composition.materialized`;
+    - the launch plan's package check (`launch-config preview` `problems[]`)
+      is `harness-packages`, and package verification's `loadedBy` is
+      `harness-discovery`.
+  - Error codes: `E_UNSUPPORTED_HARNESS`, `E_HARNESS_PACKAGE` and
+    `E_HARNESS_RESOURCE_MISSING` replace `E_UNSUPPORTED_RUNTIME`,
+    `E_RUNTIME_PACKAGE` and `E_RUNTIME_RESOURCE_MISSING`.
+  - JSON envelopes may carry `warnings: [...]`, only when there is something
+    to say. `oats status --json` carries it beside `problems`. In text mode,
+    a warning is one `oats: warning: …` line on stderr.
+  - Routed commands (`--server`) speak each host's own vocabulary. A host
+    without the `harness` feature (0.26.x and older) is sent `--runtime` and
+    `runtime` keys, and its `runtimes` list and `runtime` roster rows are read
+    as harnesses.
+  - A spawn decision previewed by a 0.26 kernel is `E_DECISION_STALE` at a
+    0.27 apply (the revision covers the key names), with the fresh decision
+    attached.
+  - Unchanged, because they do not name the harness: the session endpoint's
+    `runtimeAuthority`, `runtimeState` and `runtimeError`, the
+    `E_RUNTIME_ENDPOINT_*`, `E_RUNTIME_AUTHORITY_MISMATCH` and
+    `E_RUNTIME_QUIESCE_FAILED` codes, `capabilityRuntime`, the retirement
+    baseline, and oats.okf's `harvest-runtime` setting.
+
+## Desktop
+
+- **The Desktop speaks the harness names** on a kernel that declares feature
+  `harness` (`--harness`, `harness`/`harnesses`), and the old names on released
+  0.25.8–0.26.x kernels. It reads either spelling everywhere, shows only the
+  harness the kernel reports (no `pi` default for an instance that doesn't say),
+  and accepts kernels `>=0.25.8 <0.28.0`.
+- **Core capabilities name their origin** (soul, workspace or team) on the soul
+  page and the instance sidebar, on a kernel with feature `layers-from`.
+- The unused "the workspace's team settings" origin label is gone (0.26.0's
+  teams amendment K stopped emitting it).
+
+## Fixed
+
+- **0.26.0's notes said per-workspace personal teams need undeployed aweb
+  server support.** The aweb service (0.8.13 and later) and CLI (1.36.8 and
+  later) already carry personal enrollment; what remains is oats.aweb 1.15
+  adopting it. The bundled oats.aweb is still 1.13.1 (the personal team only);
+  the team verbs come with oats.aweb 1.14.1 in a 0.27.x patch.
+
+## Upgrading from 0.26
+
+Nothing to do. Old spellings keep working with a `deprecated-runtime-name`
+warning, and a later release drops them. To stop the warning:
+
+- write `harness:` for `runtime:` in `oats-local.yaml` launch configurations
+  (or re-save them with `oats launch-config set`);
+- pass `--harness` for `--runtime` in scripts;
+- re-save any schedule the warning names (`oats schedule update`). A stored
+  job is also rewritten on its next save.
+
+A 0.26.0 home stops warning after its next start or restart. A Desktop that
+gates on the `harness` feature reads the new names; an older Desktop reads
+`runtimes` and `runtime` and needs its update.

package/docs/schedules.md

@@ -3,16 +3,12 @@
 A schedule launches an agent, runs an oats command, or wakes an existing
 instance on a cron. Definitions belong to a scope and are committable; every
 `oats schedule` command run anywhere inside that scope, including from an
-instance home, reads and writes the same file. On a **workspace deployment**
-(0.25, [workspaces.md](workspaces.md)) the scope is the deployment directory
-— the one holding `oats-local.yaml` and the `agents/` root (the kernel derives
-it as the directory above the agents root; a leftover `oats-config.yaml` that
-declares `team:` would still win, so remove it); scheduled spawns there
-materialize exactly like `oats spawn`. On a classic 0.24 deployment the scope
-is the team workspace (the config level that declares the team, else the
-outermost `oats-config.yaml` level). Execution belongs to the host that holds
-the scope, so a schedule on a registered server keeps running while your laptop
-sleeps.
+instance home, reads and writes the same file. The scope is the deployment
+directory ([workspaces.md](workspaces.md)) — the one holding `oats-local.yaml`
+and the `agents/` root, found walking up; with none in reach, `oats schedule`
+is `E_LOCAL_MISSING`. Scheduled spawns materialize exactly like `oats spawn`.
+Execution belongs to the host that holds the scope, so a schedule on a
+registered server keeps running while your laptop sleeps.
 
 There is no daemon. One host timer (a launchd user agent on macOS, a systemd
 user timer on Linux) runs `oats schedule tick --host` once a minute; the tick
@@ -25,15 +21,9 @@ and no queue.
 ## Files
 
 - `<workspace>/oats-schedules.json` — the definitions (`{version: 1|2, jobs:
-  {<id>: ...}}`). Version 1 is the legacy format. Adding the first explicit
-  version-2 execution upgrades the whole document to version 2 so an older
-  scheduler refuses it instead of ignoring capture policy. Existing legacy
-  entries may remain visibly unmigrated; new entries in a v2 file must declare
-  their policy. Commit the file if you want the schedule shared with the team.
-  Automatic wake creation uses this same document-version gate. Remote captured
-  mutations require advertised numeric schedule API 2 before forwarding; the old
-  feature-only gate is insufficient. Unclassifiable remote spec files also require
-  API 2. Legacy inline specs/read operations remain compatible with older hosts.
+  {<id>: ...}}`). A new file is version 1. A version-2 file (written by 0.24–0.25
+  for captured definitions) is still read; it is never rewritten to version 1.
+  Commit the file if you want the schedule shared with the team.
 - `<workspace>/.agents/schedules/state.json` — last attempted minute and
   last run per job (gitignored), plus one lock directory per running job.
 - `~/.oats/schedules/registry.json` — the host registry: which scopes the
@@ -43,19 +33,21 @@ and no queue.
   with the directory to remove, and the holder removes its own lock on exit
   and on SIGINT/SIGTERM. Definition edits take a short per-scope lock.
 
-The existing Desktop adapter can inspect/manage supported API-2 schedules, but its
-legacy editor refuses captured policy fields rather than dropping them. Full captured
-editing UI remains later Desktop work; use the explicit CLI for those definitions.
+Captured (versioned) definitions are refused (the captured/portable path was removed in 0.26):
+see [Captured definitions](#captured-definitions-removed-in-026).
 
 ## Kinds
 
 - **spawn** `{id, enabled, cron, tz, kind: "spawn", agent, agentsRoot?,
-  repo?, backend?, purpose?, task, runtime?, model?, yolo?, wake?}` — every
+  repo?, backend?, purpose?, task, harness?, model?, yolo?, wake?}` — every
   due minute launches one disposable instance of `agent` with the same
   options `oats spawn` takes. `agentsRoot` names the exact agents root that
   holds the soul (it must lie inside the workspace and defaults to the
   workspace's own root); it is what tells same-named souls in different
-  member repositories apart. `repo` is the work repository, as `--repo`. The task gets a trailing schedule block naming the job and the
+  member repositories apart. `repo` is the work repository, as `--repo`.
+  Each run is named `<agent>-<purpose or id>-<YYYYMMDDHHMM>`. Instance names
+  are at most 64 characters, so a definition whose run names would be longer
+  is refused when it is saved (`E_SCHEDULE_INVALID`, field `purpose` or `id`). The task gets a trailing schedule block naming the job and the
   minute and ending with `oats retire --self`. An optional `wake` object
   (`{cron, tz, message}`) attaches a wake schedule to each launched instance;
   nothing is attached unless you ask.
@@ -66,8 +58,8 @@ editing UI remains later Desktop work; use the explicit CLI for those definition
   from durable context; the job follows that worker until its home is gone.
   Command return is not task completion. Avoid binding durable work to a
   disposable source-home cwd; see [OKF v2 source jobs](#okf-v2-source-jobs).
-  New exact-record command definitions use the fields described in
-  [Captured execution and recurrence](#captured-execution-and-recurrence).
+  An argv carrying a captured selector (`--deployment`, `--resolution`,
+  `--artifact-set`) is refused when saved (`E_SCHEDULE_INVALID`, field `argv`).
 - **wake** `{id, enabled, cron, tz, kind: "wake", home, message}` — every
   due minute inspects the instance at `home` through its session receipts.
   Running: `message` is delivered once with `session input`. Not running
@@ -97,87 +89,28 @@ required IANA zone; both are evaluated by the croner library. `--wake-every
 N` at spawn time means `*/N * * * *`: every 7 fires at :00, :07, ... :56 and
 then :00 again, so 1, 5, 10, 15 and 30 give an even cadence.
 
-## Captured execution and recurrence
-
-A new captured command definition is explicitly versioned and chooses its
-recurrence policy. Its containing schedule document is version 2:
-
-```json
-{
-  "id": "retained-job",
-  "definitionVersion": 2,
-  "recurrencePolicy": "capture",
-  "kind": "command",
-  "cwd": "/absolute/workspace",
-  "argv": [
-    "oats", "example-action", "run",
-    "--deployment", "/absolute/deployment",
-    "--resolution", "sha256-...",
-    "--", "--provider-argument", "--json"
-  ],
-  "responsibleHuman": null,
-  "cron": "0 * * * *",
-  "tz": "UTC"
-}
-```
-
-The admitted-attempt wire is published as
-[`execution-capsule.schema.json`](execution-capsule.schema.json). Runtime
-validation checks selector/target agreement. A canonical `oats.json.v1` digest
-of all fields except `executionId` is the separate content witness;
-`executionId` itself is opaque admission identity.
-
-`capture` requires the explicit deployment/resolution selector pair and
-`--json` in the **saved argv**. The scheduler never appends an unrecorded
-protocol argument to a captured target. Adding or updating the definition
-derives an immutable `execution` template containing that exact target,
-resolution, input references and explicitly supplied responsible-human value.
-It contains no execution ID; `executionStatus.contentIntegrity` exposes its
-canonical content witness. At each due tick the
-scheduler verifies the retained action first, then mints a fresh opaque
-`executionId`, writes the resulting capsule into the attempt before reserving a
-slot, and only then invokes the CLI. Thus two attempts with identical content
-have the same capsule digest but remain different intents. Definition edits
-affect later admissions only; an unknown attempt, `run`, or reconciliation never
-replaces its capsule with the edited definition or today's config/lock. Captured
-attempts carry their own `schemaVersion:1`; their launch-slot lock names the same
-`executionId`. A mismatching lock or malformed/unknown attempt version stays
-unresolved and cannot dispatch. Scheduler launch also scrubs ambient
-`OATS_DEPLOYMENT` and `OATS_RESOLUTION`; only the saved argv is authority.
-
-`prepare-on-tick` is a distinct explicit policy for a genuinely new command
-tick. Its `preparation` object maps directly to the generic
-`prepareCapturedComposition({deployment,source,workspace?,member?,operator?,mode?})`
-input; scheduler code does not parse source/workspace policy itself. Production
-uses the core adapter and tests may inject the same contract. Direct-source and
-workspace-alias requests are supported; `mode` is a work-mode string, not a nested
-launch object. A complete result must preserve the requested deployment and
-returned resolution, and contain `executionBinding` and an explicit
-`responsibleHuman` (`null` means messaging was actually disabled). The scheduler
-then inserts the exact selector pair before `--`, verifies the captured action,
-mints and persists the attempt, and dispatches. Missing adapters and incomplete
-results return typed `migration-required`/`needs-configuration` with no attempt.
-A dry run never invokes preparation or mints intent. There is no current-context
-fallback. Captured spawn and
-operation definitions remain unavailable until their public captured consumer
-adapters exist. A captured wake definition is accepted only when its target
-`instance.json` has an exact `executionBinding`; the binding is copied into the
-execution template and checked again at admission without consulting source or
-configuration. Actual captured wake delivery/start remains blocked with
-`migration-required` until the parent-owned lifecycle consumer lands. Legacy
-wakes continue through the old lifecycle boundary in this release.
-
-Definitions without `definitionVersion`/`recurrencePolicy` are legacy v1
-definitions. They retain the old release behavior during migration and are not
-reported as captured execution. `list`/`show` report their `executionStatus` as
-`{kind:"legacy",capture:"unknown",migrationRequired:true}`. A captured definition
-reports only `capture:"recorded"` until action admission verifies the retained
-record and current exact approval; it does not claim launch readiness. While an
-attempt is unresolved or its confirmed launched work still holds a slot,
-`executionStatus.intent` separately reports captured, legacy-unknown or invalid
-authority, so editing a future definition cannot hide an older admitted capsule.
-Partial, malformed or unsupported versioned
-definitions/attempts are invalid or blocked, never reinterpreted as legacy.
+## Captured definitions (removed in 0.26)
+
+0.24–0.25 could save captured command definitions: `definitionVersion`,
+`recurrencePolicy` (`capture` or `prepare-on-tick`), an `execution` template and a
+`preparation` request, run against a captured deployment/resolution. That path
+was removed in 0.26:
+
+- `add` and `update` refuse any of those four keys (`E_SCHEDULE_INVALID`, the
+  key as `field`), locally and, with `--server`, before anything is forwarded.
+- A stored captured definition is invalid on its own job: every tick reports it
+  (`invalid`, "captured schedules are refused (the captured/portable path was removed in 0.26) …") and never runs it;
+  the rest of the scope's jobs continue. `list`/`show` report its
+  `executionStatus` as `{kind:"invalid", …, reason}`.
+- A captured attempt or job lock left mid-run by 0.25 is reported on that job
+  (`executionStatus.intent`, `reconcile` refuses with `E_SCHEDULE_INVALID`) and is
+  never run, adopted or released. A held captured lock keeps its launch slot
+  until the job is gone: remove it with `oats schedule remove --force <id>`, or
+  re-add it without the captured keys.
+
+Every other definition is a plain one; `list`/`show` report its `executionStatus`
+as `{kind:"legacy",capture:"unknown",migrationRequired:true}` (a released wire,
+kept as it was).
 
 ## Commands
 
@@ -202,27 +135,23 @@ running}], scheduler: {installed, active, lastTick, maxConcurrent, ...}}`.
 
 ## What a run reports
 
-`launched` (spawn or command returned), `blocked` (versioned execution
-admission refused before a launch slot or child process), `active` (the instance is running;
-a home whose retirement is pending still counts, its runtime may be alive),
+`launched` (spawn or command returned), `active` (the instance is running;
+a home whose retirement is pending still counts, its harness may be alive),
 `ended` (its home is gone), `stopped` (home present, nothing running: needs
 attention, never removed for you), `launch-failed`, `unknown`, and for wake
 jobs `delivered`, `started` or `skipped`. The kernel never claims a task
 succeeded.
 
-`blocked` includes an unavailable exact record/approval or incomplete new-work
-preparation, including not-yet-qualified provider bindings. The result preserves the typed
-`errorCode`; no attempt capsule or launch lock is created.
+A run recorded by 0.24–0.25 may also read `blocked` (a captured admission that
+refused before a launch slot); 0.26 never produces it.
 
 `unknown` means the launch's side effects are unconfirmed: a command timed
 out or answered no envelope, an envelope named an instance the roster
 cannot place, or an attempt was never recorded. The job keeps its slot and
 is skipped until `oats schedule reconcile <id>`. Reconcile adopts only an
-attributable receipt: a legacy spawn job's instance is named deterministically
-for its minute. A captured command requires the SAME admitted execution ID and
-content witness, plus its explicitly recorded home and matching instance metadata;
-current-config roster lookup or a previous attempt's name cannot establish it.
-Nothing is inferred from file times. Observation validates custody before releasing
+attributable receipt: a spawn job's instance is named deterministically for its
+minute; a command job's, only the instance its answer named. Nothing is inferred
+from file times. Observation validates custody before releasing
 slots, and unresolved attempts remain held even in the crash gap before a lock
 exists. Ordinary removal refuses those attempts; force-forget remains explicit. A command whose answer named nothing stays
 unknown; check the roster and the host by hand, then
@@ -230,13 +159,13 @@ unknown; check the roster and the host by hand, then
 slot (or `remove --force` forgets the job).
 
 A wake job that starts a stopped home holds a launch slot while that
-runtime is starting, active, retiring or unobservable, and releases it when
-the runtime is proven stopped (the session start receipt's exit marker for
+harness is starting, active, retiring or unobservable, and releases it when
+the harness is proven stopped (the session start receipt's exit marker for
 that launch, or a home that no longer has a session) or the home is gone.
 A persistent home that outlives its process does not keep a slot. Delivering
 a message to a home that is already running takes no slot. The host tick
 observes every registered scope first, then admits due jobs in one
-host-wide order, least recently launched first (only an actual runtime
+host-wide order, least recently launched first (only an actual harness
 launch counts; a skipped or pending job keeps its place at the front), so
 one frequent job in one scope cannot keep the only slot forever. An invalid
 or malformed definition is reported on that job and the rest of the tick
@@ -244,12 +173,11 @@ continues.
 
 `disable` never stops anything. `update` never touches a running instance,
 and while a job holds a slot or has an unresolved attempt its complete
-execution identity (including a versioned capsule), kind and target cannot
-change; cron, tz and enabled can. Legacy definitions retain their narrower
-compatibility behavior until migrated. A cold wake persists its slot before
+execution identity, kind and target cannot
+change; cron, tz and enabled can. A cold wake persists its slot before
 the session start runs and keeps it on any start exception, whatever its code
 (the kernel can refuse while recording, after the session exists); the next
-observation releases it once the runtime is proven stopped or absent, one tick
+observation releases it once the harness is proven stopped or absent, one tick
 at worst.
 `remove` refuses while the job's instance is still tracked (`--force`
 forgets the job without stopping anything). Retiring an instance removes the
@@ -262,13 +190,7 @@ listed with its skipped reason.
 saves a wake job `wake-<instance>` bound to the new home after the spawn
 succeeded. If the spawn succeeds but the save fails, the spawn result still
 carries the full instance receipt, plus `wakeScheduleError` and a warning;
-the instance is neither hidden nor spawned again. When the spawning consumer
-supplies both the returned `executionBinding` and `responsibleHuman`,
-`saveWakeForHome` creates a version-2 captured wake from the matching binding in
-the new home. Supplying only one, or a result binding that differs from the
-home, refuses. The current parent-owned spawn caller still needs to pass these
-fields when its captured lifecycle path lands; omission retains explicit legacy
-behavior rather than inventing a binding.
+the instance is neither hidden nor spawned again.
 
 ## OKF v2 source jobs
 

package/docs/servers.md

@@ -25,8 +25,8 @@ oats server list
 - `--path` names directories to prepend to the remote PATH for every routed
   command (`~/.local/bin:/opt/pi/bin`). A non-interactive ssh command runs in
   the login shell's minimal PATH, and the remote kernel's spawn preflight looks
-  for the runtime binary (`claude`, `pi`, `codex`) there; without this, a
-  runtime installed under the user's home is "not found" even though it runs
+  for the harness binary (`claude`, `pi`, `codex`) there; without this, a
+  harness installed under the user's home is "not found" even though it runs
   fine in an interactive shell on that host.
 - Registrations live in `~/.oats/servers.json` on this machine, never in a
   repository scope.
@@ -44,13 +44,13 @@ worktree, identity, launch, retirement. The local side only routes: a local
 `--task-file` travels as text, every argument is quoted for the remote login
 shell, and the remote's version and envelope are checked before either
 mutation (spawn and retire). A spawn is also held to what the remote
-advertises: a runtime it does not list (including the soul's own default as
+advertises: a harness it does not list (including the soul's own default as
 the remote roster reports it), a session backend it lacks, or a launch option
 such as `--yolo` it does not know is refused with `E_REMOTE_INCOMPATIBLE`
 saying what was established. A remote that advertises nothing (any kernel
 before 0.22.2) is assumed to run pi and claude on tmux with no options, and
 the refusal says so rather than claiming the remote lacks the feature; a soul
-the remote roster does not list with a runtime is validated by the remote
+the remote roster does not list with a harness is validated by the remote
 kernel itself at spawn. `--dir` and `--server` do not combine; the remote
 workspace comes from the registration.
 

package/docs/soul.schema.json

@@ -2,7 +2,7 @@
   "$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.",
+  "description": "Authored shape only. A soul names each capability WITH WHERE IT COMES FROM (`from: here | <repo key> | package`) — a location, never a version. Core-capability 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", "description", "work"],
   "additionalProperties": false,
@@ -11,8 +11,9 @@
     "name": { "$ref": "#/$defs/slug" },
     "description": { "type": "string" },
     "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." },
+    "team": { "$ref": "#/$defs/teamLabels", "description": "Team label, or a non-empty list of distinct labels (the first is the primary); overrides the repo's default from oats-membership.yaml. Each label's messaging payload reaches the provider as an eligible team (OATS_TEAMS); joining is the provider's explicit act." },
+    "private": { "type": "boolean", "deprecated": true,
+      "description": "Ignored since 0.26.0: souls have no private mode. Every soul of a confirmed member is listed and spawnable; discovery warns soul-private-ignored. Accepted so existing files still validate; remove it." },
     "capabilities": {
       "type": "object",
       "propertyNames": { "$ref": "#/$defs/capabilityName" },
@@ -31,6 +32,12 @@
   "$defs": {
     "slug": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
     "label": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
+    "teamLabels": {
+      "anyOf": [
+        { "$ref": "#/$defs/label" },
+        { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/label" } }
+      ]
+    },
     "capabilityName": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" },
     "repoKey": { "type": "string", "pattern": "^[^\\s@/][^\\s@]*/[^\\s@]+$" },
     "fromLocation": {
@@ -49,7 +56,7 @@
     "capabilityChoice": { "anyOf": [{ "$ref": "#/$defs/capabilityRef" }, { "const": "off" }] },
     "slotPayload": {
       "anyOf": [{ "const": "none" }, { "type": "object" }],
-      "description": "Opaque provider payload, or `none` to leave the slot empty."
+      "description": "Opaque payload for the slot's core capability, or `none` to leave the slot empty."
     }
   }
 }