@awebai/oats 0.24.12 → 0.25.0

package/docs/configuration.md

@@ -1,557 +1,92 @@
-# Configuration
+# Configuration — `oats-local.yaml`
 
-OATS configuration lives in `oats-config.yaml` at a laptop, workspace, or
-repository root. It owns deployment policy: agent-type declarations, the three
-fundamental layer slots, additive capability activations, settings,
-exclusions, instruction overrides, and work modes.
+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)).
 
-The CLI is the primary config author: `oats init` scaffolds the full shape,
-`oats use` writes capability entries, `oats create --type` sets a soul's type.
-Hand-editing is valid but never required. Packages never declare their
-targets. See the machine-readable
-[`oats-config.schema.json`](oats-config.schema.json) alongside the examples
-below.
+**`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: [rebuild-to-v2.md](rebuild-to-v2.md).
 
-## Scopes
-
-Resolution walks from the soul's repository upward:
-
-1. repository;
-2. containing workspace(s); and
-3. laptop/home.
-
-A `global` binding applies to all souls governed by the level that declares
-it. It does not escape that scope. This lets a laptop set defaults, a workspace
-add shared team capabilities, and one repository make a narrower choice.
-
-```text
-~/oats-config.yaml
-~/workspace/oats-config.yaml
-~/workspace/service/oats-config.yaml
-```
-
-Use `oats doctor <context> --soul <name>` to inspect the result.
-
-## Schema
+## The file
 
 ```yaml
-name: example-service
-
-# ── Team — the deployment boundary. The closest scope declaring team: wins;
-# every repo under it resolves the same team (identity, discovery, messaging).
-team:
-  name: example-engineering
-  # id: example-engineering:example.com   # explicit provider team id (e.g. aweb <name>:<namespace>)
-
-# ── Agent types (families) ── declared here by name; each soul opts in via
-# `type: <name>` in its soul.yaml. Capability entries can target them.
-agent-types:
-  developers:
-    description: Agents that build and maintain the service
-  reviewers:
-    description: Agents that review changes
-
-capabilities:
-  # Fundamental layers — exclusive slots; a capability entry or an explicit none.
-  layers:
-    knowledge:
-      capability: oats.okf
-      from: installed
-      settings:
-        bindings-file: /absolute/config/okf-bindings.json
-        harvest-runtime: pi
-        # harvest-model: provider/model   # optional; default is runtime-selected
-      # injection-override: .agents/injections/capabilities/oats.okf.md
-    messaging: none
-    tasks:
-      capability: oats.linear
-      from: installed
-      agent-types:
-        developers:
-          enabled: true
-          settings: {team: ENG}
-      # injection-override: .agents/injections/capabilities/oats.linear.md
-
-  # Additive capabilities — non-exclusive; target global, agent-types, or souls.
-  additive:
-    example.review:
-      from: installed
-      agent-types:
-        developers:
-          enabled: true
-          settings:
-            depth: normal
-      souls:
-        security-reviewer:
-          enabled: true
-          settings:
-            depth: exhaustive
-      # injection-override: .agents/injections/capabilities/example.review.md
-
-skill-overrides:
-  review: example.review
-
-# ── Work modes — optional per-mode env bootstrap (briefings are packaged, not overridable).
-work-modes:
-  worktree:
-    # Runs inside each NEW worktree right after `git worktree add` — env setup
-    # scripts (installs, .env copying, direnv/mise). Relative to this config's dir.
-    setup: scripts/setup-worktree.sh
-
-# ── OATS defaults — the framework's baseline instruction block.
-oats:
-  # injection-override: .agents/injections/oats-defaults/oats.md
-
-# Extra unconditional instruction blocks for every instance at this scope.
-agents-md-injection:
-  repository: injects/repository.md
-```
-
-### `team`
-
-`team:` declares the deployment boundary — typically at the workspace scope.
-The closest scope declaring it wins, so every repo under `~/lfx` resolves the
-same team. `name:` is required; `id:` optionally pins the provider team id
-(for aweb, the canonical `<name>:<namespace>` form). Three things hang off
-it:
-
-- **Identity**: instances record their team in `instance.json` and their
-  TASK.md briefing; hooks receive `OATS_TEAM_NAME`/`OATS_TEAM_ID`/`OATS_TEAM_SCOPE`.
-- **Discovery**: `oats status --team` lists agents across every `agents/`
-  root in the team scope (the scope's own plus each member repo's), so an
-  agent in one repo can see teammates defined at the workspace level or in
-  sibling repos. There is no explicit member list — every repo under the
-  team scope is a member by construction.
-- **Cross-repo spawn/retire**: `oats spawn <soul>` and `oats retire <instance>`
-  resolve across the team scope's repos when the name isn't found locally
-  (unique match wins; ambiguity errors with guidance to pass `--dir`). The
-  instance homes with the soul's own repo, works in that repo, and resolves
-  that repo's config chain — spawning from elsewhere changes nothing about
-  the instance itself.
-- **Messaging**: the aweb integration joins spawned instances into the
-  resolved team (id wins over name; a bare name is resolved against the aweb
-  root's memberships), with the instance name as the discoverable alias.
-  Because every instance joins with its own name, the aweb team roster is
-  also the **cross-machine directory**: `oats aweb roster` lists team members
-  wherever they run, complementing the local `oats status --team`.
-
-### `agent-types`
-
-Agent types are agent families. Config declares type names (optionally with a
-description); membership is **not** listed in config — each soul opts in with
-an optional single `type: <name>` in its `soul.yaml` (`oats create --type <t>`
-sets it; `oats type add <name>` declares it in config). A type is identity: what kind of agent a soul is travels with the
-soul, while config decides what each type gets. Tags, dynamic selectors, and
-instance names are not supported.
-
-### `capabilities.layers`
-
-The three fundamental layers — `knowledge`, `messaging`, `tasks` — are
-exclusive slots with an explicit home. Each slot holds either a capability
-entry (`capability: <id>` plus optional `from`, targets, `settings`,
-`injection-override`) or the explicit string `none`, which suppresses an integration
-inherited from an outer scope. A slot absent from a config inherits from
-outer scopes; `oats init` writes all three so the resolution is visible.
+schemaVersion: 2
+workspace: git:github.com/acme/agents        # REQUIRED — the workspace host, observed over the remote
 
-The entry's capability must declare the same layer in its manifest; a
-mismatch is an error, as is a layer-declaring capability placed under
-`additive`. A layer entry with no explicit targets is globally enabled at
-that scope.
+clones:                                      # optional — member clones outside the <name>-workspace/ convention
+  github.com/acme/platform: /Users/ana/src/acme-platform
 
-### `capabilities.additive`
+settings:                                    # optional — 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
 
-Additive capabilities are non-exclusive packages keyed by capability ID. A
-declaration without `global`, `agent-types`, or `souls` is acquired but
-inactive. A target value can be `true`, `false`, or an object containing
-`enabled` and `settings`.
-
-For a soul, matching global, agent-type, and soul bindings compose. Setting
-precedence is:
-
-1. soul;
-2. matching agent-type;
-3. global;
-4. at equal target specificity, closer config scope.
-
-Conflicting values at equal specificity and the same scope are errors. OATS
-never uses YAML order as an implicit winner. `enabled: false` uses the same
-precedence, allowing global enable → type exclusion → soul re-enable.
-
-### `from` (provenance)
-
-`from:` documents where the artifact must come from, and resolution enforces
-it: `installed` (acquired into `.agents/capabilities/installed/`,
-lock-governed — from the official marketplace by id, a git URL, or a local
-path), `owned` (authored at this scope under `.agents/capabilities/owned/`),
-or `path:<dir>` (development declaration pointing at a manifest directory).
-A mismatch between `from:` and the discovered artifact origin is an error.
-`from: bundled` was removed. Official capabilities are acquired like any other
-package, and acquisition never grants executable trust — approve executable
-surfaces explicitly with `oats trust <capability>`.
-
-### `injection-override`
-
-Every injectable item — each capability entry, each work mode, and the `oats:`
-kernel block — accepts an `injection-override:` key: a config-relative path replaces
-the packaged instruction file, `none` suppresses it, and `default` restores
-it. The closest scope declaring the key wins. Scaffolded configs carry these
-as commented-out lines pointing at the conventional locations:
-
-```text
-.agents/injections/capabilities/<capability-id>.md
-.agents/injections/oats-defaults/oats.md
+souls:                                       # optional — souls this machine does not run
+  disabled: [data-analyst]
 ```
 
-The clean path is `oats inject eject <capability|oats>`: it copies
-the packaged default to the conventional path and sets the key — the ejected
-file then deliberately stops tracking package updates. Overrides are not
-allowed on `from: owned`/`path:` entries: the scope owns the package source,
-so its `injects/` file is edited directly.
-
-### `skill-overrides`
-
-Spawn fails when two sources contribute the same skill directory name. An
-explicit override maps that name to the winning source (`soul`, `kernel`, a
-capability ID, or a config source shown by doctor). Overrides are deliberate;
-OATS never keeps whichever filesystem entry happened to be discovered first.
-
-### Instruction sources
-
-`agents-md-injection` adds unconditional config-owned instruction files (it
-adds content; it does not override packaged defaults — that is `injection-override:`).
-Capability packages can ship an `inject`; work modes have their own source.
+Schema: [`oats-local.schema.json`](oats-local.schema.json). Unknown keys are
+refused (`E_WORKSPACE_SCHEMA`).
 
-OATS reads the canonical soul `AGENTS.md`, composes selected blocks in a new
-instance file, and records every source. It never reconciles deployment
-instructions into the committed soul; spawn and doctor are the composition
-boundaries.
+| 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>/<repo-name>/`. Only a soul's **work target** needs a clone. |
+| `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"). |
 
-### Work modes
+## Where it sits and how it is found
 
-Work modes remain soul/instance topology, not capability packages:
+Every `oats` command that needs the workspace (`sync`, `workspace status`,
+`capabilities`, `souls`, `spawn`, `status` drift) walks **up** from the current
+directory (or `--dir`) to the nearest `oats-local.yaml`; its directory is the
+deployment. Not found → `E_LOCAL_MISSING`. Beside it:
 
-- `worktree`: dedicated branch/worktree;
-- `checkout`: shared current checkout;
-- `attached`: another instance's work tree;
-- `workspace`: the whole team scope — cross-repo coordinators that read all
-  member repos but never edit them (their soul's knowledge updates arrive as
-  PRs to the soul's home repo).
-
-Work-mode briefings are packaged with the kernel and are not overridable;
-the only work-mode configuration is `setup:` — an env-bootstrap command that
-runs inside each fresh worktree after creation (a lot of teams prefer a
-script that sets up the environment: installs, .env copying, direnv/mise).
-Its failure warns without hiding the instance.
-
-### `launch-configs`
-
-A named way to start a harness, independent of any soul: which runtime, an
-executable (a wrapper, another binary), literal arguments, environment, a
-model and yolo. Souls keep their own defaults; a launch configuration is
-selected by name at spawn or when an existing instance is started or
-restarted, so the same home can move between configurations without
-being replaced.
-
-```yaml
-launch-configs:
-  personal:
-    runtime: claude
-    executable: ./bin/claude-personal      # relative: against THIS scope's directory
-    args:
-      - "--settings"
-      - "/Users/me/.claude-personal/settings.json"  # a native config file is an ordinary
-                                                     # argument the harness reads from the
-                                                     # INSTANCE HOME it starts in: absolute
-    env:
-      ANTHROPIC_API_KEY:
-        fromEnv: PERSONAL_ANTHROPIC_KEY    # resolved on the execution host at start
-      CLAUDE_CONFIG_DIR: "/Users/me/.claude-personal"
-    model: claude-opus-5
-    yolo: true
-  fast:
-    runtime: codex
-    model: gpt-5.5
 ```
-
-- The closest scope declaring a name provides the **whole** entry; a farther
-  declaration of the same name is shadowed, never merged into.
-- `executable`: a bare name is looked up on `PATH` on the execution host; a
-  path with a slash is resolved against the declaring scope when relative.
-  It must exist and be executable; it is never run just to probe it.
-- `args` and literal `env` values are passed byte-exact: spaces, quotes and
-  shell metacharacters are literal, never interpreted. A path among them is
-  read by the harness from the instance home it starts in, not from the
-  declaring scope: write native configuration paths absolute.
-- `env` values are either literals (non-secret by contract, but no answer ever
-  shows them: `oats launch-config list` and `preview` redact them) or
-  `{fromEnv: NAME}` references, which is the way to hand a secret to a
-  harness. Only the reference is recorded in an instance's launch recipe and
-  receipts; the value is read from the execution host's environment at start
-  time, and a missing reference refuses the start before anything stops.
-- `model` and `yolo` override the soul's defaults when the configuration is
-  selected; explicit `--model`/`--yolo` flags override the configuration.
-
-The CLI authors the block:
-
-```sh
-oats launch-config list [--dir <scope> | --home <abs> | --soul <name>] --json
-oats launch-config set personal --file personal.json [--keep-env] --dir <scope>
-oats launch-config remove personal --dir <scope>
+~/acme-workspace/
+├── oats-local.yaml
+├── oats-lock.json          # written by `oats sync` (lock v3; docs/packages.md)
+├── agents/                 # instance homes + fetched member-soul sources
+└── <member clones>/        # only where someone works IN a repo
 ```
 
-`set` and `remove` rewrite only the `launch-configs` block of that scope's
-`oats-config.yaml`; every other byte stays. `--keep-env` copies the
-environment of the definition effective at that scope for the name (its own,
-or the inherited one being overridden) into the complete new entry, once: an
-editor that saw only redacted values omits `env` from its definition. It is a
-copy at save time, not inheritance; the new entry shadows whole. `list --home`
-reads the home's recorded context; `list --soul` reads the soul's own member
-scope.
-
-## Acquisition and lockfile
-
-External acquisition writes `oats-lock.json` beside the declaring config in
-`lockfileVersion: 2`. It records two levels — a `packages` map (source, exact
-commit, selected path, payload integrity, dependencies) and a `capabilities`
-map (each materialized capability's version, provider package, path, artifact
-integrity, and executable trust):
-
-```json
-{
-  "lockfileVersion": 2,
-  "packages": {
-    "example.engineering": {
-      "source": "git:https://example.invalid/engineering.git@v1.4.2",
-      "version": "1.4.2",
-      "commit": "0123456789abcdef0123456789abcdef01234567",
-      "path": "oats-package",
-      "integrity": "sha256-…",
-      "dependencies": []
-    }
-  },
-  "capabilities": {
-    "example.review": {
-      "version": "1.4.2",
-      "package": "example.engineering",
-      "path": "capabilities/example-review",
-      "integrity": "sha256-…",
-      "trusted": false
-    }
-  }
-}
-```
-
-No command silently updates this record. Changed capability integrity blocks the
-artifact and resets its trust. `oats trust <id>` approves commands, hooks, and
-launch-environment authority only for the exact locked artifact integrity, and
-official identity never grants it.
-Declarative skill/instruction capabilities need a valid lock but no executable
-approval. Capabilities authored under a scope's `.agents/capabilities/owned/`
-follow their reviewed source provenance. Materialized artifacts live in
-`.agents/capabilities/installed/<id>/` beside their lock, stay gitignored, and
-are re-materialized by bare `oats install` with integrity verification.
-
-Legacy `lockfileVersion: 1` locks (per-capability marketplace installs) remain
-readable and usable. `oats migrate` converts a scope to the revised v2 lock
-**all-or-nothing**: if any entry cannot map to a package yet, the whole scope
-stays byte-identical v1 and keeps working, and a successful run converts the
-entire scope at once. There is no residue container — a converted lock never
-carries leftover v1 entries. The earlier transitional v2 shape — capability
-lists on package rows, a persistent `.agents/packages/installed/` store — is
-rejected as an invalid lock and recreated by a fresh acquisition, never
-migrated. See `docs/capabilities.md` (“Distribution packages”), the schemas
-`docs/oats-package.schema.json` / `docs/oats-lock.schema.json`, and
-`docs/design/package-engine-contract.md`.
-
-## CLI
-
-```bash
-oats init [--raw] [--template <name|path|git-url>] [--knowledge <id|none>] [--messaging <id|none>] [--tasks <id|none>]
-oats install [<id|git-url|path>] [--dir <dir>]  # acquire; bare form restores; inactive by default
-oats trust <capability> [--dir <dir>]
-oats use <capability> [--global|--type <t>|--soul <s>] [--disable] [--settings k=v [k2=v2 ...]]
-oats use none --layer <layer>
-oats type add <name> [--description <d>]   # declare an agent type
-oats type list
-oats inject eject <capability|oats>  # materialize an injection override
-oats create <name> --type <agent-type> ...
-oats doctor [context] --soul <name> [--json]
-```
-
-`oats init` writes only explicitly selected defaults, acquiring marketplace
-layer capabilities into this scope's installed/ store as needed; it does not
-activate every acquired package. `oats use`
-places a layer-declaring capability under `capabilities.layers.<layer>` and
-everything else under `capabilities.additive`, regenerating the conventional
-injection comments; custom comments inside the `capabilities:` block are not
-preserved.
-
-`oats use` activates **into a config file**, so it needs one at this scope or an
-outer one. In a scope with no `oats-config.yaml` anywhere in its chain, a
-capability already present in that scope's own `installed/` or `owned/` store
-fails with `E_NO_CONFIG` naming the initialization to run first — exactly
-`oats init --raw --dir <scope>`, which is offline, deterministic and writes only
-the minimal config — and then the same `oats use` command again. It never
-reports the capability as unacquired, and it writes nothing: authoring a
-scope's first config is `oats init`'s job.
-
-### Templates
-
-`oats init --template <name|path|git-url>` seeds the new config from a template
-config file: a local path, a git URL whose default branch carries an
-`oats-config.yaml`, or a name resolved through a `templates:` map declared in an
-outer scope (typically the laptop config):
-
-```yaml
-# ~/oats-config.yaml
-templates:
-  personal: ~/templates/personal-oats-config.yaml
-  team: https://example.invalid/oats-templates.git
-```
-
-A template seed is copied once. `init` copies the content, records provenance in
-a leading `# template:` comment, rewrites `name:`, strips the `templates:` map,
-and runs a restore so declared external capabilities are present. Later template
-edits never propagate silently.
-
-### Package config templates
-
-When the config and its capability providers travel together, prefer
-`oats init --package <source> [--config <name>]`. It validates a reference config
-template shipped by a distribution package and writes it as your local
-`oats-config.yaml`, recording the exact template as a commit-safe adopted base
-with package, template, and commit provenance. `oats config diff` and
-`oats config sync` compare against that base later. Installing the package alone
-adopts no template. See [Distribution packages](packages.md).
-
-## Fundamental-layer disable
-
-An inner scope can suppress an inherited integration without selecting a
-replacement:
-
-```yaml
-capabilities:
-  layers:
-    tasks: none
-```
-
-`oats use none --layer tasks` writes this. Pre-v0.9 spellings (`groups:`,
-top-level `layers:`, flat `capabilities.<id>` maps, `source:`,
-`agents-md-injection` on capability entries) are rejected with pointed
-migration errors. Key names are matched as own properties only, so a key
-spelled `constructor` or `toString` is reported as an unsupported key, never as
-a renamed one. `__proto__` is refused outright by every YAML reader — the
-kernel's and the desktop app's own read-only reader — and by the commands that
-WRITE config keys (`oats use --settings`, `--soul`, `--type`), all with
-`unsafe-config-key`: assigning it rewrites the parsed mapping's prototype
-instead of becoming data, which would hide the entry from every key validator.
-The kernel fails closed and reports the offending file; the desktop reader
-degrades that document to "not visible", per its read-only contract.
-
-Text that cannot be written as ONE YAML scalar on one line is refused. The
-policed inputs are exactly: `oats use --settings` keys and values, `oats use
---soul` and `--type` names, `oats type add --description`, and the scaffolded
-`name:` value that `oats init` (in every form) and the first `oats use` / `oats
-type add` at a fresh scope take from the target directory's basename — a
-basename is filesystem input, so one carrying a newline would otherwise write
-arbitrary top-level blocks into the config.
-
-Refused: a control character (a newline in a `--settings` value used to inject
-whole extra capability entries into the file) or one of the three line breaks
-outside that range (U+0085, U+2028, U+2029 — U+2028/U+2029 made the reader drop
-the written line entirely, so the command reported success for a setting that
-was not there afterwards); leading or trailing whitespace a read would strip; a
-leading YAML structure indicator (`#`, `|`, `>`, `&`, `*`, `!`, `%`, `@`,
-`` ` ``, `,`, a quote, a flow bracket, or `- `/`? `/`: `); for a VALUE, an
-embedded `" #"` (which opens a trailing comment, so the rest would be dropped
-on read) and an empty value (`key:` with nothing after it reads back as an
-empty map, not an empty string); and — for keys and `--soul`/`--type` names —
-the `:` and `#` that end a key token. Those fail with `unsafe-config-value`
-(values, the scaffolded name included) or `unsafe-config-key` (keys and names),
-and nothing is written.
-
-The guarantee is a round trip through the OATS reader, not conformance to an
-external YAML parser: ordinary values are untouched because those characters
-are structural only in first position, so `expr=2 > 1`, `tag=v1.0#build`,
-`list=a,b` and even `mode=a: b` come back exactly as they were written.
-
-## Worked examples
-
-### All souls use OKF; only developers use Linear
-
-For OKF v2, every working soul needs an explicit `okf.json` owner declaration
-and provisioned external nodes. A `bindings-file` alone is not initialization.
-See [knowledge setup](knowledge.md#acquire-bind-and-provision-explicitly) and
-[v1 migration](knowledge-migration.md); target only ready souls if the rest of
-the scope is not yet configured. These examples describe the prepared v2 path.
-
-```yaml
-agent-types:
-  developers:
-    description: Souls with type: developers in their soul.yaml
-capabilities:
-  layers:
-    knowledge:
-      capability: oats.okf
-      from: installed
-      settings:
-        bindings-file: /absolute/config/okf-bindings.json
-    tasks:
-      capability: oats.linear
-      from: installed
-      agent-types:
-        developers:
-          enabled: true
-          settings: {team: ENG, project: Product}
-```
-
-### Laptop default with repository exclusion
-
-Laptop:
-
-```yaml
-capabilities:
-  layers:
-    messaging:
-      capability: oats.aweb
-      from: installed
-```
-
-Solo repository:
-
-```yaml
-capabilities:
-  layers:
-    messaging: none
-```
-
-### One marketplace capability for one soul
-
-```yaml
-capabilities:
-  additive:
-    vendor.security-review:
-      from: installed
-      souls:
-        security-reviewer: true
-```
+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.
 
-Acquire and trust executable surfaces before spawn; target activation alone
-does not download, update, or approve code.
+## What is NOT in it
 
-## Tmux scrolling during init
+- **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
+  `oats-lock.json`.
+- **Trust** — membership for members; per-version approval in the lock for
+  packages. 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.
 
-Interactive `oats init` offers to add `set -g mouse on` to the existing
-`~/.tmux.conf` or XDG tmux config so agent windows scroll normally with a mouse
-or trackpad. It never changes terminal keyboard mappings. Agent-led and
-scripted setup should pass the user's answer explicitly:
+## Inspecting the effective configuration
 
 ```bash
-oats init --tmux-mouse
-oats init --no-tmux-mouse
-oats init --raw --tmux-mouse
+oats workspace status          # membership table, locked packages, approval state, external souls
+oats sync                      # confirm, resolve, approve, 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
 ```
 
-An accepted change is idempotent and reloads a running tmux server when
-possible. This machine preference is separate from capability acquisition and
-activation.
+Environment knobs the kernel honours: `OATS_REMOTE_CACHE` (relocates the
+invisible fetch cache), `OATS_PACKAGE_CATALOG` (an alternative catalog file).