@awebai/oats 0.29.4 → 0.30.0

package/docs/configuration.md

@@ -1,41 +1,45 @@
-# Configuration — `oats-local.yaml`
-
-A deployment has **one** per-machine file: `oats-local.yaml`. It says which
-workspace this machine realizes and holds the few facts that are true of this
-host only. Everything shared — members, packages and their versions, teams,
-defaults, stores, the messaging policy — lives in the workspace repo's
-`oats-workspace.yaml`; everything about a soul lives in its `soul.yaml`
-([workspaces.md](workspaces.md)).
-
-**`oats-config.yaml` no longer exists.** Its `capabilities.layers` /
-`additive` / `from:` / `global` / `agent-types` blocks are gone — activation is
-derived from workspace defaults plus each soul's `capabilities:` — and its
-`souls:` blocks are gone — per-instance provider content moved to
-`oats spawn … --provider`. There is no `oats init`, no `oats use`, no config
-scope chain, no adopted config templates. A 0.24.x deployment is rebuilt, not
-converted: write `oats-local.yaml` with `oats onboard` and move what the old
-file declared into `oats-workspace.yaml` and each soul's `soul.yaml`.
+# Configuration: `oats-local.yaml`
+
+A deployment has **one** per-machine file, `oats-local.yaml`. It names the
+workspace this machine realizes and holds the facts that are true of this host
+only. Everything shared (members, packages and their versions, shared teams,
+defaults, stores) lives in the workspace repository's `oats-workspace.yaml`,
+and everything about a soul lives in its `soul.yaml` ([workspaces.md](workspaces.md)).
+Write the first version with `oats onboard`; never commit it to a shared
+repository.
 
 ## The file
 
 ```yaml
 schemaVersion: 2
-workspace: git:github.com/acme/agents        # REQUIRED — the workspace host, observed over the remote
+workspace: git:github.com/acme/agents        # REQUIRED: the workspace host, read over the remote
 
-clones:                                      # optional — member clones that are not beside oats-local.yaml under their repo name
+clones:                                      # member clones not beside this file under their repo name
   github.com/acme/platform: /Users/ana/src/acme-platform
 
-settings:                                    # optional — host-owned values per capability
+settings:                                    # host-owned values per capability
   oats.okf:
     bindings-file: /Users/ana/.oats/okf-bindings.json
-    state-dir: /Users/ana/.oats/okf
-  oats.aweb:
-    delivery: channel
 
-souls:                                       # optional — souls this machine does not run
-  disabled: [data-analyst]
+teams:                                       # LOCAL teams: only this deployment uses them
+  ana-research: { team: "ana-research:acme.aweb.ai", description: Ana's research }
+defaultTeam: ana-research                    # the team every instance lives in
+souls:
+  teams:
+    "*": [ana-research]                      # every soul is in these teams here
+    data-analyst: [platform]                 # and this one also joins a shared team
+  default:
+    data-analyst: platform                   # per-soul override of defaultTeam
+  disabled: [legacy-bot]                     # souls not run on this machine
+
+host:
+  name: ana-laptop                           # which workspace triggers and schedules run here
+triggers:
+  disabled: [platform/nightly-review]
+schedules:
+  disabled: [platform/weekly-digest]
 
-launch-configs:                              # optional — named ways this host starts a harness
+launch-configs:                              # named ways this host starts a harness
   personal:
     harness: claude
     executable: "./bin/claude-wrapper.sh"    # relative → against this deployment directory
@@ -51,59 +55,204 @@ refused (`E_WORKSPACE_SCHEMA`).
 
 | key | meaning |
 |---|---|
-| `workspace` | Repo ref of the workspace host (`git:host/org/repo`, `https://…`, `git@host:…`, `file:///…`, `/abs/bare.git`). Read with your own Git credentials; the repo need not be cloned. |
-| `clones` | `<canonical repo key>: <absolute path>` — where a member's clone lives when it is not at `<deployment>/<member name>/`. Only a soul's **work target** (`work: worktree \| checkout`) needs a clone. Lookup order: `spawn --repo`, then this map (keys normalised through `parseRepoRef`, so any ref spelling of the same repo matches), then `<deployment>/<member name>` (a member named `agents` → `<deployment>/agents-repo`, since `agents/` is the instance root); none → `E_CLONE_MISSING`; a directory whose `origin` is another repo → `E_CLONE_MISMATCH`. |
-| `settings.<cap>.<key>` | Host-owned provider values the capability's manifest asks for — absolute paths, state roots, delivery modes. The workspace file **refuses** absolute paths; this is where they go. Merged into the capability's provider payload after the soul's own payload and before any `--provider` flag (see [three homes](workspaces.md#provider-payloads-have-three-homes)). |
-| `souls.disabled` | Soul names not run on this machine; reported by `oats sync` ("disabled here"). |
-| `launch-configs.<name>` | A named way to start a harness on this host (0.26.0; lead decision 2 — a spawn-time host choice, never a soul field): `harness` (`pi` \| `claude` \| `codex`, required; named `runtime` before 0.27.0, which is still read with a `deprecated-runtime-name` warning), `executable` (a bare name looked up on `PATH`, or a path — relative to this deployment directory), `args` (literal, no shell), `env` (a literal string, non-secret by contract and always redacted, or `{ fromEnv: NAME }` resolved on the host at start), `model`, `yolo`. Selected with `--launch-config <name>` on `oats spawn` and `oats session start \| restart`; explicit flags override its fields. Written by `oats launch-config set <name> --file <json>` / `remove <name>`, which rewrite only this block. Earlier kernels read `launch-configs:` from a scope's `oats-config.yaml`; 0.26.0 refuses it there with a message naming this move. |
+| `workspace` | Repo ref of the workspace host (`git:host/org/repo`, `https://…`, `git@host:…`, `file:///…`, `/abs/bare.git`). Read with your own Git credentials; it need not be cloned. |
+| `standalone` | A repo ref to realize on its own: its souls and `from: here` capabilities plus `oats.core`, with no workspace lookup. For a repository whose workspace this machine cannot read ([workspaces.md](workspaces.md#the-standalone-case)). |
+| `clones` | `<repo key>: <absolute path>` for a member clone that is not at `<deployment>/<member name>/`. Only a soul whose work target needs a clone (`work: worktree \| checkout`) uses it. Lookup order: `spawn --repo`, then this map, then `<deployment>/<member name>` (a member named `agents` → `<deployment>/agents-repo`). None → `E_CLONE_MISSING`; a directory whose `origin` is another repository → `E_CLONE_MISMATCH`. |
+| `settings.<cap>.<key>` | Host-owned values a capability's manifest asks for: absolute paths, state roots, delivery modes. The workspace file refuses absolute paths; they go here. Merged into the capability's provider payload after the soul's own and before any `--provider` flag ([three homes](workspaces.md#provider-payloads-have-three-homes)). |
+| `teams.<label>` | A **local** team: `{ team: <provider team id>, description? }`. Shared teams are committed in `oats-workspace.yaml`; a label in both is refused. Written by `oats teams add <label> --team <id>` and `oats teams remove <label>`. |
+| `defaultTeam` | The team every instance of this deployment lives in: a label of a local or shared team. The first `oats teams add` sets it; `oats teams default <label>` changes it. |
+| `souls.teams` | Which teams each soul joins here: `"*"` applies to every soul; a soul's own entry (its name, or `<package>/<soul>`) adds to it. Every soul is also in its default team. Written by `oats soul teams <soul>\|'*' --add … --remove …`. |
+| `souls.default` | A per-soul override of `defaultTeam`; it must be one of that soul's teams here (`E_TEAM_NOT_ELIGIBLE`). Written by `oats soul teams <soul> --default <label>`. |
+| `souls.disabled` | Souls not run on this machine; a spawn is refused with `E_SOUL_DISABLED`. A bare name disables every soul of that name; `<package>/<soul>` or `<member>/<soul>` disables one. |
+| `host.name` | This machine's name. A workspace trigger or schedule runs only on the host named by its `runsOn` ([schedules.md](schedules.md)). |
+| `automations.trust` | The workspace triggers and schedules (`<member>/<id>`) this host agrees to run, or `"*"` for every one the workspace places here (0.30). Absent or empty: none runs. See [Who runs workspace automations](#who-runs-workspace-automations). |
+| `triggers.disabled`, `schedules.disabled` | Workspace triggers and schedules (`<member>/<id>`) this host does not run, without a commit. Written by `oats trigger disable` / `oats schedule disable`. |
+| `launch-configs.<name>` | A named way to start a harness on this host, chosen at spawn or session start, never by the soul. See [Launch configurations](#launch-configurations). |
+| `souls.launch` | This machine's launch preference per soul (0.30): `"*"` for every soul, a soul's own entry (its name, or `<package>/<soul>`) over it. A value is a `launch-configs` name or an inline `{ harness, model? }`. It overrides the soul's own `launch:`; explicit spawn flags win over both. See [Launch preferences](#launch-preferences). |
+
+How teams are resolved, and what a messaging provider does with them, is in
+[workspaces.md](workspaces.md#teams).
+
+## Launch configurations
+
+An entry has `harness` (`pi` \| `claude` \| `codex`, required), `executable`
+(a bare name looked up on `PATH`, or a path relative to this deployment
+directory), `args` (literal, no shell), `env` (a literal string, or
+`{ fromEnv: NAME }` resolved on the host at start), `model` and `yolo`. A
+launch configuration is a host choice: a soul never names one.
+
+- Select one with `--launch-config <name>` on `oats spawn`,
+  `oats session start` and `oats session restart`. A named configuration is
+  a unit: a `--harness` that disagrees with it is refused
+  (`E_LAUNCH_CONFIG_MISMATCH`); `--model` and `--yolo` override its fields.
+- Without `--launch-config` or `--harness`, a spawn follows the soul's
+  [launch preference](#launch-preferences) (else `pi` with its defaults), and
+  an existing home keeps what it recorded. `--harness` alone leaves the recorded
+  configuration behind and uses the new harness's defaults. A model never
+  crosses harnesses.
+- The executable must be a regular executable file; it is never run to probe
+  it.
+- `oats launch-config list` shows the effective entries;
+  `oats launch-config set <name> --file <json>` and
+  `oats launch-config remove <name>` rewrite only this block;
+  `oats launch-config preview (--home <abs> | --soul <name>) --json` shows
+  what a start would run (harness, model, executable, argv, redacted
+  environment, command and preflight checks) and starts nothing.
+- The old key `runtime` is still read as `harness`, with a
+  `deprecated-runtime-name` warning.
+
+### Launch preferences
+
+A soul says what its role should run on, and each machine may override it
+(0.30; the design is
+[soul launch preferences](design/2026-09-28-soul-launch-preference.md)):
+
+```yaml
+# souls/<soul>/soul.yaml — only a harness and a model
+launch: { harness: claude, model: claude-opus-5-5 }
+
+# oats-local.yaml
+souls:
+  launch:
+    "*": personal                                    # a launch configuration, for every soul here
+    oats-expert: { harness: claude, model: claude-opus-5-5 }
+    oats.engineering/code-reviewer: { harness: codex }   # a package soul
+```
+
+- **Precedence for a new launch:** `--launch-config` or `--harness`, then
+  `souls.launch.<soul>`, then `souls.launch."*"`, then the soul's `launch:`,
+  then `pi` with its defaults. `--model` alone keeps the deciding layer's
+  harness and replaces only its model.
+- A **launch configuration** name runs that configuration's full recipe. An
+  **inline or soul preference** runs its harness the way this host starts it
+  without a configuration (the executable on `PATH`, no args, no env), with
+  its `model`. A preference without `model` uses the harness's own model; it
+  never borrows a lower layer's.
+- **A missing harness is refused**, never replaced: `E_HARNESS_UNAVAILABLE`
+  names the layer that chose it and the fix (install the harness, or override
+  it here in `souls.launch`). `oats souls` still lists the soul, with the
+  problem.
+- **Existing homes keep their launch.** A changed preference does not affect
+  a running or stopped home until `oats session restart --reselect-launch`
+  (or `start --reselect-launch`) or a respawn. `session start|restart --model`
+  keeps the recorded harness and replaces only the model. `oats readiness --home` shows
+  the drift as the `launch-changed` warning; `oats inspect --home` shows
+  `launch` (the record) beside `launchCurrent`.
+- `oats souls`, `oats inspect --soul` and `oats spawn … --preview` show each
+  soul's `launch`: its own preference, the effective launch, and which layer
+  decided (`from`) and where (`at`).
+- **Migration.** 0.29 refuses a soul.yaml it does not know, so a committed
+  soul gains `launch:` only once every deployment of the workspace runs 0.30.
+  Until then, set the preference in `souls.launch` on each machine.
+
+**Environment references.** `{ fromEnv: SRC }` is rendered as a reference,
+never a value, in the recorded command and in every answer. At start each
+source variable must be set on the host (`E_LAUNCH_ENV_MISSING`, before
+anything is created or stopped), and only the harness's pane receives it.
+`list` and `preview` redact every environment value, literals included.
+
+**The launch recipe.** A spawn records what a start is made of in
+`instance.json` under `launch`: the harness, the configuration and where it
+came from, the executable, args, env, model, yolo, and each capability's
+launch contribution with its settings and trust. One renderer turns it into
+the `command`. Configuration `args` go after the harness's own options and
+before capability arguments; every argument is single-quoted.
+
+**Starting and restarting a home.** `oats session start --home <abs>` runs
+the recorded recipe. With `--launch-config`, `--harness` or `--yolo`, the
+recipe is resolved again against the home's recorded context and every check
+runs first. With `--reselect-launch`, the launch preferences decide again
+(the home's recorded soul and this deployment's `souls.launch`). A capability that contributed harness-specific arguments must
+declare a `launch` hook to follow a harness change; otherwise the start is
+refused (`E_LAUNCH_PREPARATION`). A launch hook's warnings do not stop
+the start: `session start|restart` print them (and answer them as
+`warnings` under `--json`), as spawn does, and each is kept as a
+`launch-warning` instance event (`oats instance events`).
+`oats session restart` runs the same
+checks, then sends SIGTERM to the harness and what it started, waits
+(`--stop-grace <seconds>`, default 20) for them to exit, and starts again in
+place. It never escalates: a harness still running is reported
+(`E_SESSION_STOP_FAILED`) and nothing is launched. What a harness saves on
+SIGTERM is its own; a wrapper script should `exec` the harness or forward
+signals.
+
+## Who runs workspace automations
+
+A workspace trigger or schedule names the host that runs it (`runsOn`) and
+the GitHub account it acts as (`owner`). Both come from a commit, so a host
+also has to say yes itself (0.30):
+
+```yaml
+automations:
+  trust:
+    - agents/pr-review          # <member>/<id>
+    - agents/nightly-digest
+# or: trust: "*"                # every automation the workspace places on this host
+```
+
+- It runs only if `runsOn` is this host's `host.name`, its `owner` is this
+  host's `gh` account, **and** `trust` admits it. `triggers.disabled` and
+  `schedules.disabled` still opt out on top.
+- A placed but untrusted one never runs. Its row has reason `untrusted`, and
+  `oats workspace status` warns with the line to add.
+- An entry that names nothing is a warning, not an error.
+- `automations` is a host key: the committed `oats-workspace.yaml` refuses
+  it.
+- **Upgrading to 0.30:** a host that ran workspace automations must add its
+  `trust` lines; until then they do not run there.
+- Your own triggers and schedules (`oats trigger add`, `oats schedule add`)
+  need no trust. Details: [schedules.md](schedules.md#workspace-triggers-and-schedules).
 
-## Where it sits and how it is found
+## The deployment directory
 
-Every `oats` command that needs the workspace (`sync`, `workspace status`,
-`capabilities`, `souls`, `spawn`, `status` drift) walks **up** from the current
+Every `oats` command that needs the workspace walks **up** from the current
 directory (or `--dir`) to the nearest `oats-local.yaml`; its directory is the
-deployment. Not found → `E_LOCAL_MISSING`. The deployment is also a
-**configuration boundary**: nothing above the directory holding
-`oats-local.yaml` composes into it (a deployment created inside another
-scope — a scratch deployment under a repository, a fixture under an operator
-workspace — sees only its own files; `oats inspect` reports it, not the outer
-scope, as the workspace). Beside it:
+deployment. Not found → `E_LOCAL_MISSING`. Nothing above that directory
+composes into it: a deployment created inside another one sees only its own
+files.
 
 ```
-~/acme-workspace/
+~/acme/
 ├── oats-local.yaml
-├── oats-lock.json          # written by `oats sync` (lock v3; docs/packages.md)
-├── agents/                 # instance homes + fetched member-soul sources (created by `oats sync` / `oats onboard` if absent)
-└── <member clones>/        # only where someone works IN a repo
+├── oats-lock.json          # written by `oats sync` (packages.md)
+├── oats-schedules.json     # this host's local schedules and triggers (schedules.md)
+├── agents/                 # instance homes and the fetched soul copies
+├── .oats/modules/          # the capability store for operator-level commands
+└── <member clones>/        # only where someone works IN a repository
 ```
 
-Never commit `oats-local.yaml` to a shared repo: it names one machine's paths.
-Two operators of the same workspace share the declarations through Git and
-nothing else.
+**The capability store.** A capability command run from the deployment for a
+soul (`oats <namespace> <command> --soul <soul>`) fetches that capability at
+its locked commit into `.oats/modules/<capability>@<commit12>/`, verifies its
+content digest against the lock (recorded beside it as
+`.<capability>@<commit12>.digest`) and runs that copy. A tree that no longer
+matches its record is fetched again. An instance never uses the store: each
+home has its own copy under `<home>/.oats/modules/<capability>/`
+([souls-and-instances.md](souls-and-instances.md)). The store is a cache; it
+is safe to delete.
 
-## What is NOT in it
+## What is not in it
 
-- **Which capabilities a soul gets** — the soul's `capabilities:` plus the
-  workspace `defaults` (and `defaults.byTeam`). There is no per-deployment
-  activation or targeting.
-- **Versions** — `packages:` in the workspace file; exact commits in
+- **Which capabilities a soul gets:** the soul's `capabilities:` plus the
+  workspace `defaults`.
+- **Versions:** `packages:` in the workspace file; exact commits in
   `oats-lock.json`.
-- **Trust** — membership for members; the declaration in the workspace's
-  `packages:` for packages (no approval step). No per-operator trust list.
-- **Per-instance provider facts** (a retained messaging seat, a one-off state
-  root) — `oats spawn <soul> --provider <cap> key=value`, recorded in
-  `instance.json.providers`.
-- **Team labels, stores, messaging policy** — the workspace file.
+- **Trust:** membership for members, the workspace's `packages:` declaration
+  for packages ([packages.md](packages.md#trust)).
+- **Per-instance provider facts:** `oats spawn <soul> --provider <cap> key=value`,
+  recorded in the instance's `instance.json`.
+- **Shared teams, stores and defaults:** the workspace file.
 
 ## Inspecting the effective configuration
 
 ```bash
-oats workspace status          # membership table, locked packages, external souls
+oats workspace status          # members, locked packages, external souls
 oats sync                      # confirm, resolve, lock, report the diff
-oats capabilities | oats souls # everything a soul may name, with origin and team
-oats spawn <soul> --preview    # the exact modules (from/commit/changedSince), team, resolution revision
-oats doctor                    # this deployment's oats-local.yaml and lock, plus kernel diagnostics
+oats teams                     # shared and local teams, and the default
+oats soul teams <soul>         # the teams one soul joins here
+oats spawn <soul> --preview    # the exact modules, teams and provider payloads
+oats doctor                    # this deployment's files and the lock
 ```
 
-Environment knobs the kernel honours: `OATS_REMOTE_CACHE` (relocates the
-invisible fetch cache), `OATS_PACKAGE_CATALOG` (an alternative catalog file).
+Environment: `OATS_REMOTE_CACHE` relocates the fetch cache;
+`OATS_PACKAGE_CATALOG` names an alternative package catalog file.

package/docs/design/2026-09-16-knowledge-capability-contract.md

@@ -1,61 +1,47 @@
 ---
 type: Decision
 status: accepted-boundary
-title: Knowledge and harvesting capability contract boundary
-description: OATS provides generic context, binding, lifecycle and execution contracts; capabilities implement knowledge and harvesting functionality.
+title: Knowledge and messaging capability contract boundary
+description: OATS provides generic selection, lifecycle and execution contracts; knowledge and messaging capabilities implement their own behaviour.
 timestamp: 2026-09-16
 ---
 
-# Knowledge and harvesting capability contract boundary
+# Knowledge and messaging capability contract boundary
 
-**OATS provides contracts; capabilities provide functionality.** Knowledge and
-harvesting follow the same separation as the
-[messaging capability contract](2026-09-16-messaging-capability-contract.md).
-The reference knowledge theory remains optional authoring guidance, not a mandatory
-runtime model or a kernel-owned harvester.
+**OATS provides contracts; capabilities provide functionality.** The kernel
+has no knowledge model, harvester, messaging backend or identity system of its
+own. The official providers are `oats.okf` (knowledge) and `oats.aweb`
+(messaging); any other capability may fill either slot with a different model.
 
 ## Responsibilities
 
-| Kernel contract/support | Capability functionality |
+| Kernel supplies | The capability owns |
 |---|---|
-| Selection, exact executable approval and the shared resolver | Interpret provider-owned declarations; validate and render its nonsecret bindings |
-| Verified captured source/instance/context and bounded invocation data | Select/read the knowledge relevant to that context through its own model/tools |
-| Generic lifecycle events, hook outcomes and cleanup custody | Initialize its memory protocol, capture/freeze inputs and perform its own retirement handoff |
-| Generic native evidence APIs where applicable | Choose which evidence to collect, how to interpret it and its durable source/cursor format |
-| Source-independent helper/job execution, exact artifact/record references and admission identity | Supply harvester helpers, prompts, runtime conventions, schedules and input/destination receipts |
-| Truthful execution/uncertainty and declared operation result contracts | Judge promotion, validate, retry, publish and establish provider-specific acceptance |
-
-Reuse ProviderBinding, captured invocation/lifecycle, declared operations and
-execution capsules. Any missing generic field is reviewed/versioned once. Do not
-introduce a second config parser, resolver, command registry or harvesting engine.
-Capability-specific data remains opaque to the kernel.
-
-## Default OKF versus alternatives
-
-`oats.okf` owns stores/nodes, reads/owns, immutable views, STATE/log/notes conventions,
-durable source descriptors, harvester judgment and store-specific delivery. Its
-existing promotion bar and PR-only Git knowledge publication remain in force.
-Other capabilities may use different models, stores and harvesting machinery;
-they are not required to imitate OKF's filesystem or workflow.
-
-The knowledge-theory expert is an authoring aid, not a runtime dispatcher,
-universal harvester or required approval service. Capability ownership does not
-waive repository governance, work boundaries, secret exclusions, exact executable
-approval or truthful lifecycle/custody reporting.
-
-## Integration checks
-
-- Audit helper memory/injection suppression and source handoff projection for
-  accidental kernel-owned knowledge policy. Move new behavior behind neutral
-  contracts or capability declarations as appropriate; do not blindly enable
-  recursive harvesting or weaken existing fail-closed guards.
-- A knowledge-specific source receipt may remain a compatibility input for a
-  provider, but must not become the mandatory shape for every alternative.
-- Retirement must honor required capture/handoff outcomes before deleting their
-  source. The capability supplies the evidence and outcome; the kernel does not
-  implement the provider's memory/promotion algorithm.
-- Independent work must retain everything it needs through the existing execution
-  and provider custody contracts, without a live source/config fallback.
-
-This records the boundary and remaining audit, not a claim that every consumer is
-already refactored or that a fresh deployment/live harvester is qualified.
+| Selection: one provider per slot, resolved from the soul and the workspace defaults, copied into the home at its locked commit | Interpreting its own settings and declarations; the kernel treats them as opaque |
+| Lifecycle hooks (`spawn`, `launch`, `retire`) with the hook environment: settings and their origins, the home, the soul, the teams | What happens at each event: registering a source, minting an identity, joining a team, handing off at retirement |
+| A required spawn hook's failure rolls the spawn back; every other hook is advisory | Reporting its own outcome truthfully in the hook answer |
+| Command and operation dispatch from the copied module, and the readiness relay (`binding.check`) | Its commands, operations and readiness answer |
+| The soul's teams, as declarations | Enrolment, membership, transport and wake delivery; a declared team is not proof of enrolment |
+
+The contracts themselves are in [capabilities.md](../capabilities.md): hooks
+and their environment, commands, operations and the readiness check.
+
+## Rules
+
+- **No second engine.** A capability does not get its own resolver, config
+  parser or command registry in the kernel; a missing generic field is added
+  once, to the shared contract, and versioned.
+- **Knowledge.** The provider decides where knowledge lives, who reads and
+  owns what, how evidence is captured and judged, and how accepted knowledge
+  is delivered. `oats.okf`'s model (owned nodes in central bases, independent
+  harvest, PR-only Git delivery) is the reference, not a requirement for
+  alternatives ([knowledge theory](../knowledge-theory.md)).
+- **Messaging.** The provider owns identity, addressing, teams and delivery,
+  using only the authority it is given. Configuration never implies privacy or
+  access: contact, delivery and history are verified through the provider's
+  own mechanisms.
+- **No secrets in the contract.** Hooks contribute locators and endpoints,
+  never credentials, and nothing credential-bearing is recorded in
+  `instance.json` or logs.
+- Capability ownership does not waive repository governance, work
+  boundaries or truthful lifecycle reporting.