@awebai/oats 0.29.4 → 0.30.0

package/docs/layers.md

@@ -1,116 +1,61 @@
 # The OATS contracts
 
-OATS supplies common contracts; capabilities supply behavior. The current architecture combines [Git workspaces and portable sources](workspaces.md), retained instance execution and provider-owned knowledge, messaging and tasks.
-
-This page is the current conceptual map, not a replacement for the versioned schemas or a claim that every provider/profile is implemented. Use [release scope](release-notes/v0.24.0.md) and actual readiness results. Earlier contract inventories remain in [Git history](https://github.com/awebai/oats/blob/249899a9a1ae865cc640fbc52b3585765fba473f/docs/layers.md); dated designs are navigated through the [design index](design/README.md).
-
-## How the pieces fit
+OATS supplies common contracts; capabilities supply behaviour. The kernel
+discovers souls and capabilities, resolves what each soul gets, copies it into
+an instance home and runs the lifecycle; it implements no knowledge, messaging
+or task model of its own.
 
 ```text
-Git workspace definition
-  ├── admits repositories with reciprocal backlinks
-  ├── supplies bounded defaults and provider declarations
-  └── imports exported souls by source reference and revision
-        └── soul declares requirements, defaults and software sources
-              └── resolution pins and records an exact composition
-                    └── instance runs against an independent work target
-                          ├── knowledge capability
-                          ├── messaging capability
-                          ├── tasks capability
-                          └── any additional capabilities
+workspace (oats-workspace.yaml)      members, packages, shared teams, defaults, stores
+  └── soul (soul.yaml)               role, work mode, capabilities, slot choices
+        └── resolution               exact commits and digests, recorded at spawn
+              └── instance home      soul + copied capabilities + its own work view
+                    ├── knowledge capability
+                    ├── messaging capability
+                    ├── tasks capability
+                    └── any additional capabilities
 ```
 
-The workspace definition, source repository, local deployment, work target and messaging team are different identities. They may share a repository or machine without becoming interchangeable authority.
-
-## Soul format
-
-Portable `soul.yaml` uses `schemaVersion: 1`, a name, optional role/runtime/work preferences and explicit requirements/defaults. Canonical `AGENTS.md`, its `CLAUDE.md` alias and the declared resources provide the operating curriculum. See the [schema](soul.schema.json).
-
-A soul can require a concrete implementation **and its source**, or require a provider by presence with supported defaults/operator choice. Naming OKF or a tracker does not make a soul malformed: it makes a particular source policy explicit. A source that genuinely promises interchangeable implementations must use compatible requirements and test that claim.
-
-Concrete capability selections carry `source`; software must not be inferred from an ambient installation or the publisher's unshared config. Imports retain source identity and revision rather than creating local forks. Source updates do not silently rewrite an existing instance's retained curriculum.
-
-Classic `kind`/`type`/`repo` declarations and config-targeted agent types are a compatibility model, not mandatory fields or a third policy tier in portable resolution. See [souls and instances](souls-and-instances.md) and [classic configuration](configuration.md).
-
-## Workspace, repository and adoption contracts
-
-- `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, 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, 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. A manifest shape alone does not certify its implementation:
-
-- 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.
-
-Use [capability details](capabilities.md) and the [provider wire](design/2026-09-16-provider-binding-wire.md).
+The forms are in [workspaces.md](workspaces.md) and the schemas beside it;
+capability manifests, hooks and readiness in [capabilities.md](capabilities.md).
 
 ## The three core capabilities
 
-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.
+Knowledge, messaging and tasks are **slots**: a soul has at most one
+capability in each, and `none` empties a slot. Any number of other
+capabilities compose beside them. A slot provider declares `layer:` in its
+manifest and may answer the kernel's [readiness check](capabilities.md#readiness-check-bindingcheck).
 
 ### The knowledge contract
 
-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.
-
-The reference OKF model uses centralised per-soul knowledge, stable ownership/read routing, independent promotion and PR-only Git delivery. `owns` routes harvests; `reads` selects context; neither is an ACL. Directory publication, a proposed PR, an accepted merge and a fresh reader's observation are separate facts.
-
-Alternatives may choose different placement or learning procedures. A supported co-located profile is not implied merely because the architecture allows one. See [knowledge theory](knowledge-theory.md), [version-scoped operations](knowledge.md) and [provider-neutral boundary](design/2026-09-16-knowledge-capability-contract.md).
-
-### The tasks contract
-
-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.
+The kernel supplies selection, the copied modules, the lifecycle hooks and
+their environment. The knowledge capability owns everything else: where
+knowledge lives, who reads and owns what, how evidence is captured and judged,
+and how accepted knowledge is delivered. The official provider is `oats.okf`
+([knowledge.md](knowledge.md), [knowledge theory](knowledge-theory.md)); the
+boundary is the [knowledge and messaging capability contract](design/2026-09-16-knowledge-capability-contract.md).
 
 ### The communication contract
 
-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 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).
-
-Roster membership is not a live process or a responsive session. Retirement may leave provider-side records or incomplete cleanup; inspect the actual outcome rather than promising aliases disappear.
-
-## Runtime and work-target contracts
-
-The selected runtime owns its normal model/authentication/profile mechanisms. OATS supplies complete composed resources, task, work selection and retained execution authority; it does not copy or repair credentials or enable permission bypass merely because a session is unattended.
+The slot is named **`messaging`**. The capability owns identity, addressing,
+team membership, transport and wake delivery. The kernel supplies each soul's
+teams in the hook environment ([capabilities.md](capabilities.md#teams-in-the-provider-environment))
+and never joins a team itself. A team in a workspace file is a declaration,
+not proof that an agent is enrolled. The official provider is `oats.aweb`.
 
-Pi, Claude Code and Codex have version/profile-specific support. Claude Code and Codex retain normal native context and permissions; strict selected Pi execution has its own verified profile limits. Tmux and Herdr are backend choices, not soul identities. A source can support several realizations without every combination being qualified.
-
-The work target is independent of source publication and knowledge placement. Preserve the selected work-mode discipline and ownership. Unsupported required lifecycle, wake, plugin or recovery behavior must remain explicit, not be replaced with an easier hidden profile. See [execution targets](execution-targets.md) and the [release notes](release-notes/v0.24.0.md).
-
-## 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, 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 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.
-
-## Replaceability without invented readiness
+### The tasks contract
 
-A capability boundary is useful when implementations can differ without a new kernel-owned version of their behavior. But:
+The tasks capability owns assignment, claims, status, blockers and handoff.
+`oats.jira` and `oats.linear` are the official providers. Messaging is
+conversation, not task state.
 
-- 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 profile.
-- Workspace membership does not select every capability a member exports.
-- Published primitives and documentation do not constitute a completed deployment.
+## What the kernel does not own
 
-Use the same kernel contracts, preserve declared requirements and verify the specific supported profile. New generic authority or schema semantics require an explicit decision rather than an undocumented bypass.
+- **The harness.** pi, Claude Code and Codex start normally, with their own
+  authentication, models and permissions ([execution-targets.md](execution-targets.md)).
+- **Operating knowledge.** How to operate and configure OATS is capability
+  content: `oats.core` and `oats.setup` from the `oats.framework` package
+  ([souls-and-instances.md](souls-and-instances.md#oats-operational-knowledge-is-a-capability)).
+  The kernel writes only the home-versus-work and work-mode briefings.
+- **Proof of readiness.** A valid manifest or a declared team is not a working
+  provider; `oats readiness` asks the provider.

package/docs/oats-local.schema.json

@@ -18,7 +18,7 @@
       "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."
+      "description": "Repo ref to realize in the STANDALONE view: its own souls and from: here capabilities plus oats.core, 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",
@@ -37,15 +37,15 @@
     },
     "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`.",
+      "description": "Named ways to start a harness on this host, independent of any soul (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,
         "anyOf": [{ "required": ["harness"] }, { "required": ["runtime"] }],
         "properties": {
-          "harness": { "type": "string", "enum": ["pi", "claude", "codex"], "description": "The harness this configuration starts (named `runtime` before 0.27.0); it decides the kernel's own baseline arguments (skills, instructions, task) and how model/yolo are expressed." },
-          "runtime": { "type": "string", "enum": ["pi", "claude", "codex"], "deprecated": true, "description": "The pre-0.27 name of `harness`, still read (a deprecation warning); both, disagreeing, are refused. `oats launch-config set` writes `harness`." },
+          "harness": { "type": "string", "enum": ["pi", "claude", "codex"], "description": "The harness this configuration starts; it decides the kernel's own baseline arguments (skills, instructions, task) and how model/yolo are expressed." },
+          "runtime": { "type": "string", "enum": ["pi", "claude", "codex"], "deprecated": true, "description": "The old name of `harness`, still read (a deprecation warning); both, disagreeing, are refused. `oats launch-config set` writes `harness`." },
           "executable": { "type": "string", "minLength": 1, "description": "The program to run instead of the harness'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": {
@@ -69,7 +69,7 @@
       "additionalProperties": false,
       "required": ["name"],
       "properties": {
-        "name": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$", "description": "This machine's name (0.29.0). A workspace trigger or schedule runs on the host whose name is its `runsOn` (and only when this host's gh account is its `owner`). A machine fact, never in Git." }
+        "name": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$", "description": "This machine's name. A workspace trigger or schedule runs on the host whose name is its `runsOn` (and only when this host's gh account is its `owner`). A machine fact, never in Git." }
       }
     },
     "triggers": {
@@ -94,6 +94,19 @@
         }
       }
     },
+    "automations": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "trust": {
+          "description": "The workspace triggers and schedules this host agrees to run, by qualified id <member>/<id>, or \"*\" for every one the workspace places on this host (0.30). A workspace automation runs only when its runsOn is host.name, its owner is this host's gh account AND trust admits it; absent or empty, none runs. A host fact: the committed workspace file refuses it. Local triggers and schedules need no trust.",
+          "oneOf": [
+            { "const": "*" },
+            { "type": "array", "uniqueItems": true, "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[a-z0-9-]{1,40}$" } }
+          ]
+        }
+      }
+    },
     "souls": {
       "type": "object",
       "additionalProperties": false,
@@ -103,8 +116,48 @@
           "type": "array",
           "uniqueItems": true,
           "items": { "type": "string", "pattern": "^(?:[a-z0-9][a-z0-9._-]*/)?[a-z0-9]+(?:-[a-z0-9]+)*$" }
+        },
+        "teams": {
+          "description": "Which teams each soul belongs to on this deployment (`oats soul teams` writes it): \"*\" applies to every soul; a soul's own entry (its bare name, or <package>/<soul> for a package soul) adds to it. Every soul is also in its default. Eligible, never auto-joined: an instance joins its default at spawn and the others on request.",
+          "type": "object",
+          "propertyNames": { "type": "string", "pattern": "^(?:\\*|(?:[a-z0-9][a-z0-9._-]*/)?[a-z0-9]+(?:-[a-z0-9]+)*)$" },
+          "additionalProperties": { "type": "array", "uniqueItems": true, "items": { "$ref": "#/$defs/label" } }
+        },
+        "launch": {
+          "description": "Launch preferences on this machine (0.30; feature launch-preference), overriding the soul's own launch: \"*\" applies to every soul; a soul's own entry (its bare name, or <package>/<soul>) wins over it. A value is a launch configuration's name (in launch-configs of this file) or an inline { harness, model? }. Explicit spawn flags win over both. A changed preference affects no existing home until --reselect-launch or a respawn.",
+          "type": "object",
+          "propertyNames": { "type": "string", "pattern": "^(?:\\*|(?:[a-z0-9][a-z0-9._-]*/)?[a-z0-9]+(?:-[a-z0-9]+)*)$" },
+          "additionalProperties": { "oneOf": [ { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$" }, { "$ref": "#/$defs/launchPreference" } ] }
+        },
+        "default": {
+          "description": "A per-soul override of defaultTeam (`oats soul teams <soul> --default <label>`); it must be one of that soul's teams here (E_TEAM_NOT_ELIGIBLE).",
+          "type": "object",
+          "propertyNames": { "type": "string", "pattern": "^(?:[a-z0-9][a-z0-9._-]*/)?[a-z0-9]+(?:-[a-z0-9]+)*$" },
+          "additionalProperties": { "$ref": "#/$defs/label" }
         }
       }
+    },
+    "teams": {
+      "description": "LOCAL teams (`oats teams add` writes it): <label>: { team, description? }, the messaging provider's team id for a team only this deployment uses. Shared teams are committed in oats-workspace.yaml teams:; a label in both is team-label-collision (the shared one wins).",
+      "type": "object",
+      "propertyNames": { "$ref": "#/$defs/label" },
+      "additionalProperties": {
+        "type": "object",
+        "required": ["team"],
+        "additionalProperties": false,
+        "properties": {
+          "team": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@/+-]{0,255}$", "description": "The messaging provider's team id (for oats.aweb, <team>:<namespace>). The kernel's safety rule: never '-'-led, no whitespace or control characters, at most 256 characters; the provider validates its own shape." },
+          "description": { "type": "string" }
+        }
+      }
+    },
+    "defaultTeam": {
+      "$ref": "#/$defs/label",
+      "description": "The team every instance of this deployment lives in (its primary identity), unless souls.default overrides it for a soul: a label of teams here or in oats-workspace.yaml (`oats teams default` writes it; the first `oats teams add` sets it)."
     }
+  },
+  "$defs": {
+    "launchPreference": { "type": "object", "additionalProperties": false, "required": ["harness"], "properties": { "harness": { "enum": ["pi", "claude", "codex"], "description": "The harness the role should run on." }, "model": { "type": "string", "minLength": 1, "pattern": "^[^\\s-][^\\s]*$", "description": "A model id for that harness; absent: the harness's own model." } } },
+    "label": { "type": "string", "pattern": "^[a-z0-9][a-z0-9._-]*$" }
   }
 }

package/docs/oats-membership.schema.json

@@ -2,7 +2,7 @@
   "$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.",
+  "description": "The repo's half of the reciprocal handshake: it names the workspace it belongs to. Nothing else. A backlink is consent, not admission — the workspace must list the repo too.",
   "type": "object",
   "required": ["schemaVersion", "workspace"],
   "additionalProperties": false,
@@ -13,13 +13,6 @@
       "minLength": 1,
       "pattern": "^(?:git@[^@\\s]+|[^@\\s]+)$",
       "description": "Repo ref of the workspace host, without revision."
-    },
-    "team": {
-      "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

@@ -54,7 +54,7 @@
       "uniqueItems": true
     },
     "souls": {
-      "description": "Package souls (OATS 0.28.0): package-relative soul directories, each an ordinary soul (soul.yaml + AGENTS.md, optional skills/). A soul's name is its directory's. They are versioned and locked with the package (oats-lock.json records each soul's name, path and digest), listed with their package origin, and spawned by the qualified name <package>/<soul> (or the bare name when unique). `from: here` in a package soul is its own package at the locked commit.",
+      "description": "Package souls: package-relative soul directories, each an ordinary soul (soul.yaml + AGENTS.md, optional skills/). A soul's name is its directory's. They are versioned and locked with the package (oats-lock.json records each soul's name, path and digest), listed with their package origin, and spawned by the qualified name <package>/<soul> (or the bare name when unique). `from: here` in a package soul is its own package at the locked commit.",
       "type": "array",
       "items": {
         "type": "string",
@@ -67,7 +67,7 @@
       "uniqueItems": true
     },
     "triggers": {
-      "description": "Trigger templates (OATS 0.28.0): `oats trigger add --from <package>:<id> [--set <name>=<value>]…` instantiates one from the locked package. Each file is { parameters: { <name>: { path, required?, default?, description? } }, definition: { …a trigger definition… } }; see docs/schedules.md#triggers.",
+      "description": "Trigger templates: `oats trigger add --from <package>:<id> [--set <name>=<value>]…` instantiates one from the locked package. Each file is { parameters: { <name>: { path, required?, default?, description? } }, definition: { …a trigger definition… } }; see docs/schedules.md#triggers.",
       "type": "array",
       "items": {
         "type": "object",
@@ -93,7 +93,7 @@
       }
     },
     "configTemplates": {
-      "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`.",
+      "description": "Tolerated and ignored: named classic config templates, accepted so published packages still validate; the workspace model reads nothing from them.",
       "type": "object",
       "propertyNames": {
         "pattern": "^[a-z0-9][a-z0-9._-]*$"
@@ -125,7 +125,7 @@
       }
     },
     "configs": {
-      "description": "DEPRECATED 0.19 spelling of `configTemplates`, readable only so immutable published 0.19 package tags stay consumable. Both spellings normalize to one descriptor shape; the diagnostic `legacySpelling` flag records which was used. It is NOT the discriminator for a \".\" capability root — published legacy packages exist with neither spelling. New authoring must emit `configTemplates`; carrying both spellings is an invalid manifest.",
+      "description": "Tolerated and ignored: the old spelling of `configTemplates`.",
       "type": "object",
       "propertyNames": {
         "pattern": "^[a-z0-9][a-z0-9._-]*$"
@@ -155,7 +155,7 @@
       }
     },
     "dependencies": {
-      "description": "Package source specifications (NOT capability IDs): official catalog selectors (e.g. \"oats.okf@v1.4.0\"), git:host/org/repo@ref, raw HTTPS/SSH git URLs with @ref, or local paths. No general semver ranges; the resolved closure is exact-locked.",
+      "description": "Tolerated and ignored: package source specifications from the classic line. The workspace model resolves only the workspace's `packages:`; a package's dependencies are not followed.",
       "type": "array",
       "items": {
         "type": "string",

package/docs/oats-workspace.schema.json

@@ -25,7 +25,7 @@
       "type": "object",
       "propertyNames": { "$ref": "#/$defs/label" },
       "additionalProperties": { "$ref": "#/$defs/team" },
-      "description": "Org team labels. A label never gates, restricts or partitions anything."
+      "description": "SHARED teams: <label>: { description?, team? }. `team` is the messaging provider's team id, the same for everyone; without it the team is declared but not yet created (readiness team-unmapped). Local teams, the default and which teams each soul belongs to live in the deployment's oats-local.yaml (`oats teams`, `oats soul teams`). A label never gates, restricts or partitions anything."
     },
     "defaults": { "$ref": "#/$defs/defaults" },
     "stores": {
@@ -36,14 +36,7 @@
     },
     "messaging": {
       "type": "object",
-      "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",
-          "propertyNames": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" },
-          "additionalProperties": { "type": "object" }
-        }
-      }
+      "description": "Opaque provider payload consumed by the messaging core capability. A team's provider id is teams.<label>.team."
     },
     "external": {
       "type": "array",
@@ -113,7 +106,10 @@
     "team": {
       "type": "object",
       "additionalProperties": false,
-      "properties": { "description": { "type": "string" } }
+      "properties": {
+        "description": { "type": "string" },
+        "team": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@/+-]{0,255}$", "description": "The messaging provider's team id (for oats.aweb, <team>:<namespace>). Absent: declared, not yet created. The kernel's safety rule: never '-'-led, no whitespace or control characters, at most 256 characters; the provider validates its own shape." }
+      }
     },
     "defaults": {
       "type": "object",
@@ -122,16 +118,7 @@
         "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" } }
-          }
-        }
+        "tasks": { "$ref": "#/$defs/slotDefault" }
       }
     },
     "external": {
@@ -145,8 +132,7 @@
           "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-catalog.md

@@ -5,19 +5,33 @@ 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.
 
+## The packages
+
+| package | release | capabilities | package souls |
+|---|---|---|---|
+| `oats.framework` | `oats-framework/v1.4.0` (this repository) | `oats.core`, `oats.setup`, `oats.knowledge-theory` | `knowledge-theory-expert` |
+| `oats.okf` | `v4.0.4` | `oats.okf` (knowledge), `oats.okf-harvest`, `oats.okf-maintenance` | `knowledge-harvester`, `knowledge-maintainer` |
+| `oats.aweb` | `v1.17.1` | `oats.aweb` (messaging) | |
+| `oats.engineering` | `v1.1.0` | `oats.engineering-expert`, `oats.developer`, `oats.code-review` | `code-reviewer` |
+| `oats.authoring` | `v1.0.3` | `oats.authoring` | |
+| `oats.jira` | `v1.0.1` | `oats.jira` (tasks) | |
+| `oats.linear` | `v1.0.1` | `oats.linear` (tasks) | |
+
+Each package lives in its own `awebai/oats-*` repository except
+`oats.framework`, whose payload root is `oats-package/` here. A capability id
+names the package that supplies it through the catalog's aliases, so
+`oats.developer: { from: package }` selects `oats.engineering`. This catalog ships with
+the CLI: an older installed CLI keeps its own copy, and a change here rewrites
+no lock and adds nothing to an existing workspace.
+
 ## Find and use packages
 
-- 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.
 - A workspace pins an official package by **bare version** in its
-  `packages:` map (`oats.okf: v2.1.3`); `oats sync` resolves it through the
+  `packages:` map (`oats.okf: v4.0.4`); `oats sync` resolves it through the
   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
+  A package outside the catalog is written `git:<repo>@<ref>`. Pinning does
+  not join a team or adopt the publisher's workspace. See
   [packages](packages.md).
-- 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
@@ -63,27 +77,10 @@ or workspace membership alone does not make a package official.
 Contact and license evidence may live in the package/repository documentation;
 this policy does not invent new catalog or manifest fields.
 
-## Listed first set
-
-- Listed capabilities: `oats.okf`, `oats.okf-harvest`, `oats.okf-maintenance`,
-  `oats.aweb`, `oats.authoring`, `oats.jira`, `oats.linear`, `oats.dev`,
-  `oats.knowledge-theory`, `oats.core` and `oats.setup`. `oats.okf-harvest` and
-  `oats.okf-maintenance` select the `oats.okf` package (4.0.1).
-- **`oats.framework` 1.3.2** is listed at tag `oats-framework/v1.3.2` in
-  `awebai/oats`, payload root `oats-package`. The `oats.core`, `oats.setup` and
-  `oats.knowledge-theory` aliases select that distribution; package identity is
-  distinct from capability identity. Core supplies operation/soul guidance;
-  setup supplies OATS Soul Setup, configuration and package guidance. The
-  package also ships the `knowledge-theory-expert` package soul.
-
-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
-locks or tags. No package is silently added to an existing workspace.
-
 ## Updates, deprecation and removal
 
 Use the same catalog PR and maintainer-review path to update, deprecate or remove
 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,
-change what a workspace declares, uninstall packages or delete retained resources.
+and assess existing locks before changing discovery. Preserve immutable
+release history. A list change is not permission to rewrite a deployment's
+lock or change what a workspace declares.