@awebai/oats 0.29.3 → 0.30.0

package/docs/workspaces.md

@@ -1,13 +1,8 @@
-# Workspaces — one workspace per organisation, members are trust, nothing is installed
+# Workspaces: one workspace per organisation, members are trust, nothing is installed
 
-This is the OATS workspace model (v2, the 0.25 line). It replaces the per-soul
-`source:` grammar, the installed-capability tier and `oats-config.yaml`. The
-normative record is the Decision concept
-`agents/oats-expert/soul/knowledge/decisions/workspace-model-v2.md`; the module
-contracts the kernel is built against are in
-[design/2026-09-23-workspace-module-contracts.md](design/2026-09-23-workspace-module-contracts.md);
-a full worked example (an imaginary company with three teams) is in
-[design/2026-09-23-simplified-workspace-model.md](design/2026-09-23-simplified-workspace-model.md).
+This is the OATS workspace model. The module contracts the kernel is built
+against are in
+[design/2026-09-23-workspace-module-contracts.md](design/2026-09-23-workspace-module-contracts.md).
 
 ## The rule
 
@@ -44,7 +39,7 @@ shapes; domain rules (declared teams, duplicate members, canonical `from:` keys,
 the two `packages:` value forms) live in the kernel's `validateWorkspace` /
 `validateSoul`, which are the authority.
 
-### `oats-workspace.yaml` — the one shared declaration
+### `oats-workspace.yaml`: the one shared declaration
 
 Lives in the repository that **hosts** the workspace (often a dedicated
 `agents` repo, but any member can host it). One per organisation.
@@ -59,13 +54,13 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
   - git:github.com/acme/tools              # a member that ALSO publishes a package (see below)
 
 packages:                                  # the ONLY versioned things
-  oats.framework: v1.3.1                   # bare version → resolves through the official catalog
-  oats.okf: v4.0.0
+  oats.framework: v1.4.0                   # bare version → resolves through the official catalog
+  oats.okf: v4.0.4
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 
-teams:                                     # labels, declared once so they cannot drift
-  global:      { description: Org-wide souls and house capabilities }
-  engineering: { description: Platform and release automation }
+teams:                                     # SHARED teams: the same provider team for everyone
+  engineering: { description: Platform and release automation, team: "engineering:acme.aweb.ai" }
+  reviewers:   { description: Code review }   # declared, not created yet (no `team` id): readiness team-unmapped
 
 defaults:
   capabilities:
@@ -74,9 +69,6 @@ defaults:
   knowledge: { oats.okf: { from: package } }             # one slot default at most; a soul may say `none`
   messaging: none
   tasks: none
-  byTeam:
-    engineering:
-      capabilities: { acme-release-tooling: { from: github.com/acme/agents } }
 
 stores:                                    # knowledge stores, declared once
   org: git:github.com/acme/knowledge
@@ -97,92 +89,68 @@ exactly as the kernel spells it (`parseRepoRef(ref).key`: lowercase host,
 file/bare-directory remote). Any other spelling is a schema error at
 validation, not a late membership error.
 
-### `oats-membership.yaml` — the backlink, in every member
+### `oats-membership.yaml`: the backlink, in every member
 
 ```yaml
 schemaVersion: 2
 workspace: git:github.com/acme/agents      # "I am a member of acme"
-team: engineering                          # optional: default team label for this repo's items
 ```
 
-Nothing else. It replaces `oats.yaml`; there are no export lists.
+Nothing else: there are no export lists, and team membership is local to each
+deployment ([Teams](#teams)).
 
-### `souls/<name>/soul.yaml` — where each capability comes from
+### `souls/<name>/soul.yaml`: where each capability comes from
 
 ```yaml
 schemaVersion: 2
 name: release-manager
 description: Cuts, verifies and announces releases.
 work: worktree                             # worktree | checkout | directory | workspace
-team: engineering                          # optional; else the repo's default; else "unassigned"
 
 capabilities:
   acme-release-tooling: { from: here }     # `here` = the repo this soul.yaml lives in
   acme-deploy: { from: package }           # provided by acme.tools, pinned in packages:
   acme-house-style: off                    # removes a workspace default
 
-knowledge:                                 # provider payload, opaque to the kernel — the slot capability's BINDING keys
-  harvest-runtime: claude                  # (oats.okf 2.1.3: what this soul owns/reads is in souls/<name>/okf.json, not here — see below)
+knowledge:                                 # provider payload, opaque to the kernel: the slot capability's settings
+  harvest: off                             # (what this soul owns and reads is in souls/<name>/okf.json, not here)
 messaging:
   channels: [acme-eng]
 tasks: none                                # empties the slot
 
-compatibility:                             # optional FLOORS on package versions — constraints, not sources
-  oats.okf: ">=2.1"
+compatibility:                             # optional FLOORS on package versions: constraints, not sources
+  oats.okf: ">=4.0"
 ```
 
 Beside it: `AGENTS.md` (canonical), `CLAUDE.md → AGENTS.md`, `skills/`, and
-whatever the slot providers read from the soul directory — for `oats.okf`
-2.1.3 that is **`okf.json`** (`{ version: 1, owner, owns: ["<base>/<node>"],
-reads: […] }`, written by `oats okf init|migrate`), the soul's knowledge
-declaration; it travels with the soul into the per-commit soul cache. The
-`knowledge:` payload on `soul.yaml` reaches OKF as `OATS_SETTINGS` and may
-carry only the binding's settings keys (`bindings-file`, `state-dir`,
-`harvest-runtime`, `harvest-model`); `owns`/`reads`/`root` there are refused by
-the provider, not read (a soul payload grammar is an OKF follow-up). Every
-`souls/*/soul.yaml` in a member is listed and spawnable — souls have no
-private mode (`private:` in a soul.yaml is ignored since 0.26.0, with a
-`soul-private-ignored` warning). A soul's
-`name` must equal its directory name; the first of two souls declaring one
-name (by path) is listed, the second is a problem.
-
-### `capabilities/<name>/oats.json` — the manifest, unchanged shape
-
-The capability manifest is the one file that did not change (see
-[capabilities.md](capabilities.md)). Discovery relies on `capability` (the same
+whatever the slot providers read from the soul directory. For `oats.okf` that
+is **`okf.json`** (`{ version: 1, owner, owns: ["<base>/<node>"], reads: […] }`),
+the soul's knowledge declaration; it travels with the soul into the per-commit
+soul cache ([knowledge.md](knowledge.md)). A slot payload on `soul.yaml` reaches
+the provider as `OATS_SETTINGS` and may carry only the settings the provider's
+manifest declares; the provider refuses any other key.
+
+Every `souls/*/soul.yaml` in a member is listed and spawnable; souls have no
+private mode. A soul's `name` must equal its directory name; the first of two
+souls declaring one name (by path) is listed, the second is a problem.
+
+### `capabilities/<name>/oats.json`: the manifest
+
+The capability manifest is described in [capabilities.md](capabilities.md).
+Discovery relies on `capability` (the same
 `^[a-z0-9][a-z0-9._-]*$` grammar every `capabilities:` key uses), `version`,
-`layer`, and may read `private: true` (a **repo-owned** capability) and
-`team: <label>`. `version` is
+`layer`, and may read `private: true` (a **repo-owned** capability). `version` is
 informational for member capabilities — a materialized copy is identified by
 its content digest.
 
-### `oats-local.yaml` — the only per-machine file
+### `oats-local.yaml`: the only per-machine file
 
-```yaml
-schemaVersion: 2
-workspace: git:github.com/acme/agents      # observed over the remote; need not be cloned
-clones:                                    # optional: where member clones live, if not the convention
-  github.com/acme/platform: /Users/ana/src/acme-platform
-settings:                                  # host-owned values the manifests ask for
-  oats.okf:
-    bindings-file: /Users/ana/.oats/okf-bindings.json
-    state-dir: /Users/ana/.oats/okf
-souls:
-  disabled: [data-analyst]                 # not run on this machine (E_SOUL_DISABLED); oats.okf/knowledge-harvester names a package soul
-host:
-  name: ana-laptop                         # this machine's name: runs the workspace triggers/schedules whose runsOn names it
-triggers:
-  disabled: [knowledge/okf-harvest-review] # workspace triggers this host does not run (oats trigger disable)
-schedules:
-  disabled: [platform/nightly-digest]      # workspace schedules this host does not run (oats schedule disable)
-```
+Which workspace this machine realizes, where member clones live, host-owned
+provider settings, this deployment's local teams and team membership, host
+facts for automations, and launch configurations. The full reference is
+[configuration.md](configuration.md).
 
-`host`, `triggers.disabled` and `schedules.disabled` (0.29.0) are machine facts:
-see [schedules.md#workspace-triggers-and-schedules](schedules.md#workspace-triggers-and-schedules).
-
-See [configuration.md](configuration.md). `oats-config.yaml` no longer exists.
-
-### `oats-lock.json` — lock v3
+### `oats-lock.json`: lock v3
 
 Written by `oats sync`; the only persisted state at the deployment besides
 `oats-local.yaml`. See [packages.md](packages.md).
@@ -194,16 +162,11 @@ Written by `oats sync`; the only persisted state at the deployment besides
 the workspace back. One file per side; a copied backlink in a fork, or a folder
 with the right name, is not admission.
 
-**Membership is the whole trust decision for member capabilities** — the same
+**Membership is the whole trust decision for member capabilities**, the same
 model as a repo's committed `.agents/skills/`: whoever can push to the repo
-decides what runs, and the branch's latest state is what runs. No per-operator
-trust lists, no per-capability approval for members. Packages come from
-*outside* that boundary, and **declaring one in the workspace's `packages:` is
-the trust decision** (human decision, 2026-09-24): people install a package only
-when they trust it, so there is no second, per-version approval step. The lock
-is reproducibility, not approval — it pins the exact commit and content
-integrity, and `oats sync` refuses drift (a moved tag, changed content, an
-edited capability list). A spawn admits only a locked package the workspace
+decides what runs, and the branch's latest state is what runs. Packages come
+from *outside* that boundary, and **declaring one in the workspace's
+`packages:` is the trust decision** ([packages.md](packages.md#trust)). A spawn admits only a locked package the workspace
 **still declares**: one removed from `packages:` but left in a stale lock is
 `E_PACKAGE_MISSING { reason: "undeclared" }` until `oats sync` drops it.
 
@@ -237,15 +200,15 @@ no private mode: every soul of a confirmed member is listed and spawnable.
 **not** a member, pinned to a full commit. No handshake is asked for and none is
 read; the soul gets no member-tier capabilities of its own repo; it is
 "source-complete" (its skills travel with it) and the workspace's defaults fill
-its slots. An `external[].team` overrides the soul's own `team`.
+its slots.
 
-**Package souls.** A package may ship souls (`souls:` in `oats-package.json`,
-0.28.0): they are listed from the lock for each package the workspace declares,
+**Package souls.** A package may ship souls (`souls:` in `oats-package.json`):
+they are listed from the lock for each package the workspace declares,
 named `<package>/<soul>` (a bare name when unique), resolved like any soul
 (`from: here` = their own package at the locked commit) and trusted as the
 package is. See [packages](packages.md#package-souls).
 
-## Member tier vs package tier — the non-collapse rule
+## Member tier vs package tier: the non-collapse rule
 
 A repository may be a **member** (it completed the handshake; its `souls/*` and
 `capabilities/*` are member-tier: latest state, trusted by membership) **and** a
@@ -264,44 +227,24 @@ A repository may be a **member** (it completed the handshake; its `souls/*` and
   package's capabilities as member capabilities.
 
 So the framework's own souls say `oats.okf: { from: package }` even though
-`oats-okf` is a member of the OATS workspace — and every package repo carries a
-member soul that is the expert in that capability (`okf-expert`, `aweb-expert`,
-…), discoverable at latest state like any member soul.
+`oats-okf` is a member of the OATS workspace, and every package repo carries a
+member soul that is the expert in that capability (`oats-okf-expert`,
+`oats-aweb-expert`, …), discoverable at latest state like any member soul.
 
 ## Packages, lock, catalog
 
-`packages:` values have exactly two forms:
-
-- a **bare version** (`v2.1.3`, `2.1.3`, `v1.0.0-rc.1`) — resolved through the
-  official catalog (`package-catalog.json` in the `oats` repo; the reviewed
-  list, see [official-catalog.md](official-catalog.md)). This is
-  the only way a package becomes *pinnable by id*.
-- **`git:<repo>@<ref>`** — a direct package ref: `<repo>` is any ref the kernel
-  understands (`github.com/org/repo`, `https://…`, `git@host:…`, `/abs/bare.git`,
-  `file:///…`), `<ref>` a tag name or a full commit OID. The package is read at
-  `oats-package/` inside that repo.
-
-Both are packages: versioned and locked. A ref that resolves to a **branch** is
-refused (`E_PACKAGE_INTEGRITY { why: "branch" }`) — versions are immutable. A
-tag that moved (same version string, different commit), or content that no
-longer matches the locked integrity, fails with `E_PACKAGE_INTEGRITY` on the
-next `oats sync`.
-
-**There is no package approval** (human decision, 2026-09-24). Declaring a
-package in `packages:` is the trust decision; `oats sync` asks nothing and
-`--approve` is `E_BAD_ARGS`. `oats sync` confirms membership, resolves every
-`packages:` entry to a commit + content digest, writes `oats-lock.json`
-(lockfileVersion 3), creates `agents/` if absent, reports what changed and
-exits `0`. A lock written by an earlier kernel may still carry an `approved`
-record per entry: it is ignored, and the next write drops it. `oats package add <id> <version|git:…@…>` / `oats package remove <id>` edit
-`packages:` in the workspace file when it is tracked by the current checkout,
-else print the line to add — the workspace file is shared through Git. Details:
-[packages.md](packages.md).
+`packages:` values have two forms, a **bare version** resolved through the
+official catalog and a **`git:<repo>@<ref>`** direct ref; both are versioned
+and locked, and a ref that resolves to a branch is refused. `oats sync`
+confirms membership, resolves every entry to a commit and content digest,
+writes `oats-lock.json`, creates `agents/` if absent and reports what changed.
+`oats package add | remove` edit `packages:`. The grammar, the lock, trust and
+the catalog are in [packages.md](packages.md).
 
 ## Resolution, spelled out
 
 For each `(name, from)` in
-`defaults.<slot>` ⊕ `defaults.capabilities` ⊕ `defaults.byTeam[<soul team>]` ⊕
+`defaults.<slot>` ⊕ `defaults.capabilities` ⊕
 `soul.capabilities` (later wins; `off` removes; a soul `<slot>: none` drops
 the workspace's slot default):
 
@@ -326,30 +269,13 @@ preview and apply is `E_DECISION_STALE`, not a silent drift.
 
 ## Materialization and the instance home
 
-At spawn every resolved capability is **copied whole** into the instance home —
-skills, injects, scripts, hooks — from the remote at the recorded commit.
-Nothing is symlinked, nothing is shared between instances.
-
-```
-<agents-root>/<soul>/instances/<instance>/
-├── AGENTS.md                          # composed: soul AGENTS.md + kernel/work-mode blocks + each module's inject
-│                                      #   (the "You run on OATS" block is oats.core's inject; the kernel ships no copy)
-├── CLAUDE.md → AGENTS.md
-├── .agents/skills/<capability>/<skill>/SKILL.md    # full copies; where pi/codex look
-├── .claude/skills → ../.agents/skills
-├── .oats/modules/<capability>/        # the full capability copy: oats.json, bin/, injects/, skills/
-├── instance.json                      # modules{}, providers{}, workspace{} recorded here
-├── TASK.md
-└── work/
-```
-
-`instance.json.modules.<cap>` records `from` (`{ kind: "member", repoKey,
-commit }` or `{ kind: "package", package, version, commit, integrity, repoKey }`),
-`commit`, `digest` (sha256 of the copied tree) and `materializedAt`;
-`instance.json.providers.<cap>` records the merged provider payload. A running
-instance never changes under itself: a member moving or `packages:` being
-bumped affects only new spawns. Details and DTOs:
-[souls-and-instances.md](souls-and-instances.md), [desktop-cli-api.md](desktop-cli-api.md).
+At spawn every resolved capability is **copied whole** into the instance home
+(skills, injects, scripts, hooks) from the remote at the recorded commit, and
+`instance.json` records each module's source, commit and digest. Nothing is
+symlinked or shared between instances, and a running instance never changes
+under itself: a member moving or `packages:` being bumped affects only new
+spawns. The home's layout and records are in
+[souls-and-instances.md](souls-and-instances.md).
 
 **Drift is shown, not prevented.** `oats status` compares each instance's
 recorded modules — and its recorded **soul source** (`instance.json.workspace.soul`)
@@ -361,29 +287,61 @@ carries `instances[].soul`. `oats spawn --preview` lists `changedSince` the
 newest previous instance of the same soul, plus `providers` (the `--provider`
 map as given) and `settings.<cap>` (the merged payload each provider receives).
 
-**Harnesses start normally.** OATS is a skill contributor, not a skill sandbox:
-cwd = the instance home, the harness's own skill discovery intact
-(`~/.pi/agent/skills`, `.agents/skills` up the tree, `.claude/`, …); machine-
-and repo-level skills resolve exactly as they would without OATS. OATS
-composes instructions (`AGENTS.md`) and pins model/provider settings; it does
-not exclude anything.
+Harnesses start normally, with their own skill discovery intact
+([souls-and-instances.md](souls-and-instances.md)).
 
 ## Teams
 
-`teams:` declares labels once (`global`, `engineering`, …) so they cannot drift
-into typos. A soul carries `team:` — one label or a list (`team: [engineering,
-reviewers]`, the first the primary) — else its repo's default from
-`oats-membership.yaml` (same shape), else `unassigned`; a capability carries one
-label. A label not declared in `teams:` is `E_TEAM_UNKNOWN` (the item is still
-listed); a declared label without a `messaging.byTeam` entry is the
-`unmapped-team-label` warning. `defaults.byTeam.<team>.capabilities` adds
-capabilities additively for souls with that label, for each label in order
-(`off` removes; two labels that disagree are `E_TEAM_CONFLICT`). Each label is
-an *eligible* messaging team the provider may join on request — see
-[capabilities.md](capabilities.md#several-team-labels). **A
-label never gates, restricts, changes trust or partitions the knowledge
-store** — it organises and can supply defaults. The messaging provider's payload
-(private teams, channels) lives under `messaging:`, so "team" means one thing.
+A team is a messaging-provider team (for oats.aweb, an
+aweb team id `<team>:<namespace>`) under a **label**. Two files declare them:
+
+- **Shared teams**: the committed `oats-workspace.yaml` `teams.<label> =
+  { description?, team? }`: the same provider team for everyone, edited by a PR.
+  A shared team without `team` is declared but not created yet (readiness
+  `team-unmapped`): its owner creates it with the messaging provider, then
+  commits the id.
+- **Local teams**: the deployment's `oats-local.yaml` `teams.<label> = { team,
+  description? }`: a team only this deployment uses (a personal team). A label in
+  both files is `team-label-collision` (a warning); the **shared** definition
+  wins, and the fix is renaming the local label.
+
+`oats-local.yaml` also says which teams each soul belongs to **here**:
+
+- `defaultTeam: <label>`: the team every instance of this deployment lives in
+  (its default-team identity);
+- `souls.teams`: `"*"` for every soul, and a soul's own entry (its bare name, or
+  `<package>/<soul>` for a package soul) adds to it;
+- `souls.default`: a per-soul override of `defaultTeam`; it must be one of that
+  soul's teams (`E_TEAM_NOT_ELIGIBLE`).
+
+A soul's default is `souls.default[soul] ?? defaultTeam`; its teams are that
+default ∪ `souls.teams["*"]` ∪ `souls.teams[soul]`. A label no file declares is
+`E_TEAM_UNKNOWN` (a spawn, preview or `inspect --soul` of that soul is
+refused). At spawn an instance joins its **default** only; the others are
+eligible: offered, and joined on request through the provider (`join=` at
+spawn, or its own verbs later). Nothing committed besides the shared `teams:`
+says anything about teams, and capabilities compose from the workspace defaults
+and the soul only, the same for everyone. **A label never gates, restricts,
+changes trust or partitions the knowledge store.**
+
+The verbs edit `oats-local.yaml` in place; they never call a provider:
+
+```
+oats teams [--json]                                  # this deployment's teams, ids, the default, problems
+oats teams add <label> --team <id> [--description d] # declare a local team (the first one becomes the default)
+oats teams remove <label>                            # refused while referenced (E_TEAM_IN_USE) or shared (E_TEAM_SHARED)
+oats teams default <label>
+oats soul teams <soul>|'*' [--add a,b] [--remove a,b] [--default <label> | --clear-default] [--json]
+```
+
+The messaging provider's own setup creates provider teams and records them with
+`oats teams add` (see the provider's documentation). The spawn preview, `inspect` and `oats souls` report a soul's
+`teams` and `defaultTeam`; readiness reports the team problems in
+`checks.configured` (`E_TEAM_UNCONFIGURED` when a messaging layer is active and
+there is no default; `team-unmapped`, blocking when it is the default;
+`default-team-changed` for a running instance). The provider receives them in
+its environment — see [capabilities.md](capabilities.md#teams-in-the-provider-environment).
+Exact shapes: [desktop-cli-api.md](desktop-cli-api.md#team-model-v2-feature-team-model-2-oats-0300-replaces-feature-teams).
 
 ## Provider payloads have three homes
 
@@ -393,46 +351,17 @@ store** — it organises and can supply defaults. The messaging provider's paylo
 | A fact about this machine | `oats-local.yaml` → `settings.<cap>.<key>` (absolute paths are refused in the workspace file) | `settings.oats.okf.state-dir: /Users/ana/.oats/okf` |
 | A fact about **this spawn** | `oats spawn … --provider <cap> key=value` (repeatable; dotted keys nest) → `instance.json.providers.<cap>` | `--provider oats.aweb identity.source=/abs/path/to/retained/.aw` |
 
-The merged payload is `workspace.messaging` (messaging slot only; its base
-keys, with `byTeam` stripped) ⊕ soul slot payload ⊕ `local.settings[cap]` ⊕
-`spawn.providers[cap]` — objects deep-merge, later wins on scalars and arrays.
-**No `byTeam[<label>]` is merged into it, the primary's included** (teams
-amendment K): each label's `base ⊕ byTeam[label]` reaches the provider only as
-that label's entry in `OATS_TEAMS` (the preview's `teams`). So `settings.team`
-(and `OATS_TEAM_ID`) is the workspace's default team if the host, the soul or the spawn
-set one; empty means the provider's own default. The provider's own `binding` contract
-(`normalize → bind → check`) runs over the merged payload exactly as before.
-Two teams, two messaging identities, one workspace:
+The merged payload is `workspace.messaging` (messaging slot only) ⊕ soul slot
+payload ⊕ `local.settings[cap]` ⊕ `spawn.providers[cap]` — objects deep-merge,
+later wins on scalars and arrays. The provider's own `binding` contract
+(its readiness check) runs over the merged payload. Teams are **not** settings:
+they reach the provider beside them, in its environment ([Teams](#teams)).
+Where a provider keeps its own state (for oats.aweb, its identity roots) is the
+provider's concern; see its documentation.
 
-```yaml
-teams: { oss: { description: Open protocol }, cloud: { description: Hosted application } }
-messaging:
-  byTeam:
-    oss:   { team: aweb:example.oss }
-    cloud: { team: aweb:example.cloud }
-```
-
-A soul with `team: cloud` hands its messaging provider the eligible team
-`{ label: cloud, team: aweb:example.cloud, mapped: true, payload: { team: aweb:example.cloud, … } }`
-in `OATS_TEAMS`; its settings carry no `team` unless the host, soul or spawn set
-one. A label under `byTeam` that is not declared in `teams:` is
-`E_WORKSPACE_SCHEMA`. **Joining an eligible team is the provider's explicit
-act.** `spawn --preview` shows the merged `settings.<cap>` and the `teams`, so
-the delivery is verifiable, and `instance.json` records both. With oats.aweb
-1.13.1 (which reads `team` from its settings and ignores `OATS_TEAMS`) the
-primary identity therefore mints into the workspace's default team: the `.aw` root's
-active team, or the one the host set. What the payload does not change is
-**where the `.aw` root is found**: the hook still searches
-bounded candidates, first hit wins — the instance home, the Git repository
-containing it, the soul's work repository and the Git repository containing
-it, then the deployment directory (`OATS_WORKSPACE`); never the user home or
-above the deployment — and that root must hold a membership of the named team (the deployment's `.aw`
-joined to every team its labels name is the simple layout). On oats.aweb
-1.11.2 `team` was ignored (the root's active team won), so `byTeam` there is
-a recorded intent only.
 A store (`stores: { <name>: <repo ref> }`) names a repository; where a
-knowledge base lives inside it is the knowledge provider's own concern — for
-OKF 2.1.3 that is the **bindings file** (`bases.<alias>.repository` + `root`,
+knowledge base lives inside it is the knowledge provider's own concern. For
+oats.okf that is the **bindings file** (`bases.<alias>.repository` + `root`,
 `oats-local.yaml settings.oats.okf.bindings-file`), not a soul payload key; a
 repo ref never carries a `#path`.
 
@@ -460,11 +389,11 @@ different repo → `E_CLONE_MISMATCH`. Spawning a soul whose repo is not yet
 cloned is a guided clone-then-spawn, a job for the onboarding skill, not the
 kernel.
 
-The deployment directory is **yours to choose** (decision 9) — an existing folder that already holds your member clones is the usual case; `oats onboard <dir>` adds what the kernel needs and nothing else:
+The deployment directory is **yours to choose**: an existing folder that already holds your member clones is the usual case, and `oats onboard <dir>` adds what the kernel needs and nothing else ([configuration.md](configuration.md#the-deployment-directory)):
 
 ```
 ~/acme/                           ← the directory you chose
-├── oats-local.yaml               ← which workspace this machine realizes + host paths + disabled souls
+├── oats-local.yaml               ← which workspace this machine realizes, and host facts
 ├── oats-lock.json                ← exact commit + integrity per package
 ├── agents/                       ← instance homes (each self-contained) + fetched soul sources
 ├── platform/                     ← clone of github.com/acme/platform (only if someone works IN it; may live elsewhere — see clones:)
@@ -500,7 +429,7 @@ that view explicitly). `oats onboard` lists the host among the clones to make
 like any member (the host is a member; its souls may need a work clone); under
 an explicit `standalone:` header its next steps say so and name that one repo.
 
-**Executables from public members.** Membership is the trust (decision 2): a
+**Executables from public members.** Membership is the trust: a
 member capability's hooks and command scripts run on every operator's machine at
 spawn, gated by nothing but the handshake. In a mixed public/private
 organisation keep **souls only** in public members and let executable
@@ -520,27 +449,15 @@ onboarding skill asks this question first.
 - **Members.** A member is always its latest state; there is no `@revision`
   on `members:`. A team that wants frozen capabilities publishes them as a
   package and pins that.
-- **Member capabilities' `version` field** — informational; the content digest
+- **Member capabilities' `version` field**: informational; the content digest
   recorded at spawn identifies a copy.
 - **Souls in members.** A soul is spawned from its repo's current state; the
   commit is recorded in `instance.json.workspace.soul`.
-- **The deployment layout** — the operator's; only the convention is taught.
+- **The deployment layout**: the operator's; only the convention is taught.
 
 What **is** versioned: `packages:` (the workspace's one list), the lock's exact
 commits and digests, and `external:` pins (a stranger's repo is never "latest").
 
-## Removed
-
-Per-soul `source: git:…@v#…` lines and the `git:`/`repo:`/`path:` grammar;
-`imports:` of member souls; `exports:` lists; `oats.yaml`; the
-installed-capability tier (`.agents/capabilities/installed/`) and
-`oats-config.yaml` entirely; `oats init` / `use` / `install` / `restore` /
-`trust` / `list` / `catalog` / `remove` / `migrate` / `config` (each answers
-`E_UNKNOWN_COMMAND` naming its replacement); per-soul `stores.<x>.inherit`;
-ambient-skill exclusion at launch. Lock v1/v2 files are `E_LOCK_SCHEMA`.
-There is no converter and no dual-schema reader: a 0.24.x kernel keeps
-spawning 0.24.x deployments.
-
 ## Related
 
 - [Souls and instances](souls-and-instances.md) · [Packages](packages.md) ·

package/lib/automations.mjs

@@ -21,9 +21,10 @@
  *    E_AUTOMATION_SCHEMA), `id:` or the filename stem, `runsOn` (a host name), `owner` (a GitHub
  *    account, `<host>/<login>`), `description?`, `enabled?`. A duplicate id within one member and
  *    one kind is E_AUTOMATION_DUPLICATE.
- *  - PLACEMENT: a host runs one ONLY when `runsOn` is its `host.name` (oats-local.yaml) AND its
- *    authenticated `gh` account is `owner`; otherwise it is listed with the reason
- *    (`host-unnamed`, `assigned-elsewhere`, `owner-mismatch`). Each kind's own list in
+ *  - PLACEMENT: a host runs one ONLY when `runsOn` is its `host.name` (oats-local.yaml), its
+ *    authenticated `gh` account is `owner` AND its `automations.trust` admits it (0.30: both
+ *    names come from a commit; trust is the operator's own yes); otherwise it is listed with the
+ *    reason (`host-unnamed`, `assigned-elsewhere`, `owner-mismatch`, `untrusted`). Each kind's own list in
  *    oats-local.yaml (`triggers.disabled`, `schedules.disabled`) stops a named host from running
  *    one.
  *  - THE SNAPSHOT: discovery reads the remotes (async), the host tick is synchronous; so
@@ -38,11 +39,15 @@ import { parseConfigData } from "./config-data.mjs";
 
 export const AUTOMATIONS_API = 1;
 export const SNAPSHOT_MAX_AGE_MS = 10 * 60_000;
-export const PLACEMENT_REASONS = Object.freeze(["host-unnamed", "assigned-elsewhere", "owner-mismatch"]);
+export const PLACEMENT_REASONS = Object.freeze(["host-unnamed", "assigned-elsewhere", "owner-mismatch", "untrusted"]);
 /** The kinds, in the order the snapshot keeps them (`triggers`, `schedules`). */
 export const KIND_NAMES = Object.freeze(["trigger", "schedule"]);
 const NEVER_SCANNED = new Set(["oats-package", ".git", "node_modules"]);
 export const AUTOMATION_ID_RE = /^[a-z0-9-]{1,40}$/;
+/** A model id an automation may pass to `oats spawn --model`: a provider/model id, never an option.
+ *  The first character is alphanumeric (or the spawn CLI's own `@native-default`), so no value can
+ *  be read as a flag (re-review B #1). `[` `]` admit a harness's context-size alias (`opus[1m]`). */
+export const MODEL_RE = /^(?:@native-default|[A-Za-z0-9][A-Za-z0-9._:/@+\[\]-]{0,127})$/;
 export const HOST_NAME_RE = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 const OWNER_RE = /^([a-z0-9-]+(?:\.[a-z0-9-]+)+)\/([A-Za-z0-9](?:[A-Za-z0-9-]{0,38}))$/;
 const HEADER_KEYS = ["kind", "schemaVersion", "id", "description", "runsOn", "owner", "enabled"];
@@ -123,6 +128,9 @@ export async function discoverAutomations(discovery, { remote, memberName, kinds
   const names = new Map();
   for (const m of (discovery?.members || []).filter((x) => x.confirmed && x.commit)) {
     const name = memberName(m.key);
+    // `local/<id>` names this host's own automations (and their state, live counts and CLI edits):
+    // a member labelled `local` would collide with them (re-review B #3).
+    if (name === LOCAL) { problems.push({ code: "E_AUTOMATION_DUPLICATE", repoKey: m.key, path: "", message: `member name ${JSON.stringify(name)} is reserved for this host's own triggers and schedules (local/<id>), so ${m.key}'s are not listed — rename the repository to list them` }); continue; }
     if (names.has(name)) { problems.push({ code: "E_AUTOMATION_DUPLICATE", repoKey: m.key, path: "", message: `member name ${JSON.stringify(name)} is also ${names.get(name)}'s: triggers and schedules are named <member>/<id>, so ${m.key}'s are not listed` }); continue; }
     names.set(name, m.key);
     let candidates;
@@ -218,7 +226,20 @@ const snapshotAge = (snap, now) => (snap?.takenAt ? now.getTime() - Date.parse(s
 export function hostOf(local) {
   const name = isObject(local?.host) && typeof local.host.name === "string" ? local.host.name : null;
   const disabled = Object.fromEntries(KIND_NAMES.map((k) => [k, new Set(Array.isArray(local?.[`${k}s`]?.disabled) ? local[`${k}s`].disabled : [])]));
-  return { name, disabled };
+  const t = isObject(local?.automations) ? local.automations.trust : undefined;
+  const trust = t === "*" ? "*" : new Set(Array.isArray(t) ? t : []);
+  return { name, disabled, trust };
+}
+/** Whether this host's `automations.trust` admits a workspace automation (`<member>/<id>`). */
+export const trusted = (host, id) => host.trust === "*" || !!host.trust?.has(id);
+/** What an operator adds to trust `id`: the exact list line under `automations:` `trust:`. */
+export const trustRemedy = (id) => `add the line "- ${id}" under automations: trust: in oats-local.yaml`;
+/** `automations.trust` entries that name no workspace trigger or schedule in `automations`
+ *  (the snapshot's): stale, or a member not synced yet. A warning, never an error. */
+export function staleTrust(host, automations) {
+  if (host.trust === "*") return [];
+  const known = new Set(automations.map((a) => a.id));
+  return [...host.trust].filter((id) => !known.has(id));
 }
 /** The account the host's `gh` is logged in as on one GitHub host (`gh api user`), memoized in
  *  `cache` (one per tick). `io.gh(args)` is the seam. → { ok, login } | { ok: false, error } */
@@ -237,7 +258,7 @@ export function ghLogin(ghHost, { io, cache } = {}) {
   return out;
 }
 /** Where a workspace trigger or schedule runs, from this host's point of view.
- *  → { runsHere, reason: null | host-unnamed | assigned-elsewhere | owner-mismatch, detail?, enabledHere } */
+ *  → { runsHere, reason: null | host-unnamed | assigned-elsewhere | owner-mismatch | untrusted, detail?, enabledHere } */
 export function placementOf(a, { host, io, cache }) {
   const enabledHere = a.enabled !== false && !host.disabled[a.kind]?.has(a.id);
   let reason = null, detail;
@@ -248,6 +269,7 @@ export function placementOf(a, { host, io, cache }) {
     const who = owner ? ghLogin(owner.host, { io, cache }) : { ok: false, error: "owner is not <host>/<login>" };
     if (!who.ok) { reason = "owner-mismatch"; detail = `acts as ${a.owner}, but this host's gh is not logged in on ${owner?.host ?? "?"}: ${who.error}`; }
     else if (who.login.toLowerCase() !== owner.login.toLowerCase()) { reason = "owner-mismatch"; detail = `acts as ${a.owner}; this host's gh is logged in as ${owner.host}/${who.login}`; }
+    else if (!trusted(host, a.id)) { reason = "untrusted"; detail = `declared for this host, not trusted here; to run it, ${trustRemedy(a.id)}`; }
   }
   return { runsHere: reason === null && enabledHere && !a.invalid && !!a.definition, reason, ...(detail ? { detail } : {}), enabledHere };
 }