@awebai/oats 0.27.2 → 0.29.0

package/docs/desktop-cli-api.md

@@ -54,6 +54,18 @@ something to say. The one warning so far is `deprecated-runtime-name` (see
 --json`, whose document is not an envelope, carries the same `warnings` beside
 its `problems`. In text mode the warning is one `oats: warning: …` line on stderr.
 
+## Flags
+
+A kernel command reads `--flag=value` exactly as `--flag value`, with the
+same validation (0.27.3+; before, the inline form was silently ignored, so
+`--harness=claude` spawned the default harness). The value is everything after
+the first `=`. An empty `--flag=` is `E_BAD_ARGS` ("`--flag=` needs a value"),
+and so is a value on a switch: `--yolo=false` is refused and never turns
+yolo on. A capability command's own flags belong to its provider. They are
+forwarded exactly as typed; the kernel reads only its dispatch flag (`--soul`)
+in either form. There is no feature string: a caller that must work with
+older kernels uses the spaced form.
+
 ## The harness rename (feature `harness`, OATS 0.27.0)
 
 What starts an instance (pi, claude or codex) is its **harness**. 0.27.0 renames
@@ -84,7 +96,7 @@ routed commands (`--server`) already translate for such a host, sending
 | `oats inspect --json` `souls[]` rows, remote roster rows | `runtime` | `harness` | Output only; a pre-0.27 host's `runtime` rows are read as `harness` |
 | `oats inspect --home --json` `instance` | `runtime` | `harness` | Output only |
 | The launch plan's package check (`launch-config preview` `problems[]`) | `runtime-packages` | `harness-packages` | Output only |
-| Soul `soul.yaml` (member souls and capability-defined agents) | `runtime:` | `harness:` | Yes, **without** a warning: released capabilities (oats.aweb 1.13.1) ship `runtime:`, and the operator cannot fix a provider's file. Both, disagreeing → `E_BAD_MANIFEST` |
+| Soul `soul.yaml` (member and package souls) | `runtime:` | `harness:` | Yes, **without** a warning: released capabilities (oats.aweb 1.13.1) ship `runtime:`, and the operator cannot fix a provider's file. Both, disagreeing → `E_BAD_MANIFEST` |
 | `oats-local.yaml` `launch-configs.<name>` | `runtime:` | `harness:` | Yes, with the warning. Both, disagreeing → `E_WORKSPACE_SCHEMA`. `launch-config set` writes `harness` (a `runtime` in its `--file` definition too) |
 | `launch-config list/preview --json` rows and `selection` | `runtime` | `harness` | Output only |
 | Home `instance.json` | `runtime`; launch recipe `launch` version 1 `{runtime}` | `harness`; recipe version **2** `{harness}` | Yes, with the warning naming the home: a 0.26.0 home inspects, starts, restarts and retires; its next start or restart records the new names |
@@ -241,6 +253,8 @@ payload the spawn recorded for a home, or the resolution computes for a soul.
   - `operations[].available` is `false` with a `reason` when it cannot run
     here: a `context: "home"` operation for a soul subject says `needs a
     running home (--home)`.
+- `capabilities[].composedFrom` and `capabilitiesOff[]` (feature
+  `desktop-facts`): see [Desktop facts](#desktop-facts-feature-desktop-facts-oats-0290).
 - `instance` is `null` for a soul. For a home, `instructions.sources` names
   each composed inject in order.
 - A soul whose resolution is refused (for example, a package the lock does
@@ -388,7 +402,8 @@ on stdout:
 ```
 
 The environment is the provider's module environment:
-- `OATS_CAPABILITY`, `OATS_SETTINGS`, `OATS_CLI_BIN` and `OATS_WORKSPACE`;
+- `OATS_CAPABILITY`, `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS` (0.29.0: JSON
+  pointer → `{ kind, at }`), `OATS_CLI_BIN` and `OATS_WORKSPACE`;
 - the team variables (`OATS_TEAM_*`, `OATS_WORKSPACE_NAME`/`_KEY`);
 - `OATS_AGENT` (the soul), and `OATS_SOUL` when the soul directory is known;
 - for a home, `OATS_INSTANCE` and `OATS_INSTANCE_HOME`.
@@ -667,7 +682,7 @@ unchecked, echoed a stored `definition.id` without checking it, and named a
 ```
 
 **Exact shapes (API 3):**
-- `schedule list --json` → `result = {scope, scheduleApi: 2, scheduleHistoryApi: 3, integrity, schedules: Entry[], scheduler}`.
+- `schedule list --json` → `result = {scope, scheduleApi: 2, scheduleHistoryApi: 3, integrity, schedules: Entry[], triggers: {count, command: "oats trigger list"}, scheduler}` (`triggers`, 0.28.0: the trigger definitions this listing leaves out).
 - `schedule show <id> --json` → `result = {schedule: Entry}` (one level of nesting; `integrity` is NOT on `show` — it is a scope fact reported by `list`).
 - `Entry` (readable) = definition fields (`id, kind, home, message|operation, cron, enabled, …`) + `{scope, scheduleApi: 2, scheduleHistoryApi: 3, executionStatus, nextRun: ISO|null, lastRun: Run|null, history, recentRuns: Run[], running: boolean, attempt?, pendingWake?}`.
 - `Entry` (unreadable, `list` only) = `{id, scope, scheduleApi: 2, scheduleHistoryApi: 3, unreadable: {code, message}, history: {status: "corrupt", stored: null, truncated: false}, recentRuns: []}` — no definition fields.
@@ -743,7 +758,7 @@ the pre-fix marker and is never accepted for dispatch.
   `agents/<soul>/soul` pointer. (0.25.x previews populated the cache: that stated
   exception is gone.)
 - **Exact root**: `spawn <soul> --agents-root <abs>` binds the soul to that root
-  (as inspect/readiness take it) — no team-soul / capability-agent / importable-
+  (as inspect/readiness take it) — no team-soul / importable-
   def fallback; mismatch → `E_SOUL_UNKNOWN`. The preview echoes
   `subject {soul, agentsRoot|null, dir|null}` **as given, byte-exact**.
 - **Decision binding**: `decision {instance, home, branch, base{ref,oid},
@@ -1115,8 +1130,8 @@ gate that on the absence of `packages-no-approval`.
              "souls":["tools-expert"],"capabilities":["acme-tools-dev"],"publishes":{"package":"acme.tools","version":"0.4.0"}},
             {"key":"github.com/acme/billing","name":"billing","commit":"<oid>","confirmed":false,"status":"no-backlink","detail":"github.com/acme/billing@… has no oats-membership.yaml","team":null,
              "souls":[],"capabilities":[],"publishes":null}],
- "packages":[{"id":"oats.okf","version":"2.1.3","source":"catalog:oats.okf","commit":"<oid>","integrity":"sha256-…","capabilities":["oats.okf"]},
-             {"id":"acme.tools","version":"0.4.0","source":"git:github.com/acme/tools@v0.4.0","commit":"<oid>","integrity":"sha256-…","capabilities":["acme-deploy","acme-lint"]}],
+ "packages":[{"id":"oats.okf","version":"2.1.3","source":"catalog:oats.okf","commit":"<oid>","integrity":"sha256-…","capabilities":["oats.okf"],"souls":[]},
+             {"id":"acme.tools","version":"0.4.0","source":"git:github.com/acme/tools@v0.4.0","commit":"<oid>","integrity":"sha256-…","capabilities":["acme-deploy","acme-lint"],"souls":["release-reviewer"]}],
  "changes":[{"id":"acme.tools","from":null,"to":"0.4.0","commit":"<oid>"}],
  "problems":[]}
 ```
@@ -1125,6 +1140,8 @@ gate that on the absence of `packages-no-approval`.
   `backlink-elsewhere` | `cannot-read`; `detail` explains an unconfirmed row.
   `publishes` reports a member's `oats-package/` (informational — its
   capabilities are **not** in `capabilities[]`; the non-collapse rule).
+- `packages[].souls` (feature `package-souls`, 0.28.0): the names of the
+  package souls the lock records for that package (`[]` when none).
 - `changes[]`: `from` = previously locked version or `null`; `to` = `null` when
   the package was dropped from `packages:` and from the lock.
 - `problems[]`: `{ code, path, message, repoKey? }` — per-item discovery
@@ -1176,6 +1193,9 @@ souls, paths, message }` — one `unmapped-team-label` per label that is in
 `teams:` but not in `messaging.byTeam`, naming its souls (sorted) and each
 soul's `<repoKey>:<path>#/team`; sorted by label. Never a problem.
 
+`defaults`, `clones`, `disabledSouls`, `lock`, file locations and
+`packages[].latest` (feature `desktop-facts`): see [Desktop facts](#desktop-facts-feature-desktop-facts-oats-0290).
+
 `unsynced` = declared in `packages:` but not in the lock (run `sync`);
 `stale` = locked but no longer declared. Read-only: does not write the lock.
 (0.26.0: the `approval` object is gone with package approval.)
@@ -1207,10 +1227,27 @@ or `"unassigned"`.
  "souls":[
    {"name":"release-manager","origin":"member github.com/acme/agents @ 3f2a9c1e","kind":"member","repoKey":"github.com/acme/agents","commit":"<oid>",
     "team":"engineering","private":false,"path":"souls/release-manager","work":"worktree","description":"Cuts, verifies and announces releases."},
-   {"name":"security-reviewer","origin":"external github.com/oss-collective/experts @ 9c4e1f2a","kind":"external",…}],
+   {"name":"security-reviewer","origin":"external github.com/oss-collective/experts @ 9c4e1f2a","kind":"external",…},
+   {"name":"release-reviewer","qualifiedName":"acme.tools/release-reviewer","origin":"package acme.tools v0.4.0","kind":"package","package":"acme.tools","version":"0.4.0",
+    "repoKey":"github.com/acme/tools","commit":"<oid>","team":"engineering","labels":["engineering"],"private":false,"path":"oats-package/souls/release-reviewer","work":"directory","description":"…"}],
  "problems":[]}
 ```
 
+**Package souls** (feature `package-souls`, 0.28.0): a row with `kind:
+"package"` is a soul a locked package ships (listed only while the workspace
+declares the package). It carries `package`, `version` and `qualifiedName`
+(`<package>/<soul>`); spawn it by `qualifiedName` (the bare `name` works when
+it is unique). The Souls page shows it as "from package <id> <version>".
+Its instances home under `agents/<package>--<soul>/` (`.` in the package id
+becomes `-`), and that directory is the agent `name` in `oats status --json`
+(`agents[].name`, e.g. `oats-okf--knowledge-maintainer`). A
+problem about a package soul carries `package` (and `repoKey: null`); its
+`path` is `package:<id>:<path in the repo>`.
+
+Souls rows' defaults, spawnability and `file`, and capability rows' `layer`,
+`description`, provides, `file` and `tree` (feature `desktop-facts`): see
+[Desktop facts](#desktop-facts-feature-desktop-facts-oats-0290).
+
 Package capabilities of declared-but-unsynced packages are absent until `sync`.
 (`oats souls --json` keeps `soulsApi: 1` in 0.26.0: its shape is unchanged.
 The probe's `soulsApi` is **2** because it tracks the `oats inspect --json`
@@ -1261,9 +1298,13 @@ between preview and apply is `E_DECISION_STALE`):
   key**: legal only at the top level of the workspace file's `messaging:`;
   anywhere else in any payload layer (soul, `oats-local.yaml` `settings`,
   `--provider`, at any depth) it is `E_WORKSPACE_SCHEMA { reason: "reserved-key", path, key }`.
-- Soul lookup: `E_SOUL_UNKNOWN { name, members[] }` (not among confirmed
-  members or externals), `E_SOUL_AMBIGUOUS { name, repos[] }` (name it
-  `<repo>/<soul>`). Resolution errors keep their codes (`E_NOT_A_MEMBER`,
+- Soul lookup: `E_SOUL_UNKNOWN { name, members[], packages[] }` (not among
+  confirmed members, externals or package souls), `E_SOUL_AMBIGUOUS { name,
+  repos[], qualified[] }` (name one of `qualified`: `<member>/<soul>` or
+  `<package>/<soul>`), `E_SOUL_DISABLED { name, qualifiedName, entry }` (the
+  soul is in `oats-local.yaml` `souls.disabled`). A package soul whose fetched
+  content does not match the lock is `E_PACKAGE_INTEGRITY { why:
+  "soul-digest", package, soul, locked, observed }`. Resolution errors keep their codes (`E_NOT_A_MEMBER`,
   `E_MEMBERSHIP_UNCONFIRMED { repoKey, reason }`, `E_CAPABILITY_MISSING { hint? }`,
   `E_CAPABILITY_PRIVATE`, `E_PACKAGE_MISSING`, `E_PACKAGE_INTEGRITY { why: "capabilities", listed, locked }`,
   `E_SLOT_CONFLICT { slot, modules[], reason? }`, `E_SKILL_DUPLICATE { name, modules[] }`,
@@ -1286,6 +1327,7 @@ Written by materialization inside the spawn transaction; read back by
  "providers":{"acme-release-tooling":{},"oats.okf":{"owns":"release-manager","reads":["platform-engineer"],"state-dir":"/Users/ana/.oats/okf"}},
  "workspace":{"key":"github.com/acme/agents","name":"acme","deployment":"/Users/ana/acme-workspace","commit":"<oid>","resolution":"<24 hex>","standalone":false,
               "soul":{"repoKey":"github.com/acme/agents","commit":"<oid>","team":"engineering"}},
+ "…":"a package soul's workspace.soul also records package: {id, version, commit, digest, path}, and its id is package:<id>#<soul>",
  "capabilities":[{"id":"oats.okf","capability":"oats.okf","origin":"package:oats.okf@2.1.3","…":"one row per module"}]}
 ```
 
@@ -1341,6 +1383,296 @@ top-level `workspace` reachability field:
   `oats-local.yaml` has no `workspace` field and `modules` as recorded.
 - Text mode prints `modules: <cap> from <member|package …> @ <7-char>` lines
   for non-current modules (`--verbose` for all).
+- `instances[].soul` is the soul source's drift: `{ repoKey, commit, current,
+  status, reason? }`. For a **package soul** (feature `package-souls`) it also
+  carries `package`, `version` and `currentVersion`; `moved` means the package
+  pin moved (another version/commit is locked now), `missing` has `reason`
+  `package-absent` (no longer locked or declared) or `soul-absent` (the locked
+  package no longer ships it). Text: `soul: <name> from package <id> v<version>
+  @ <7-char>  [package moved since (now v<version> @ <7-char>)]`.
+
+### Triggers (feature `triggers`, OATS 0.28.0) — `oats trigger … --json` → `triggerApi: 1`
+
+Event-driven spawns of a deployment ([schedules.md#triggers](schedules.md#triggers)).
+Definitions live in `oats-schedules.json` (`kind: "trigger"`); `oats schedule list`
+does not show them. From 0.29.0 a row's `id` is qualified (`local/<id>` here; a
+workspace trigger's is `<member>/<id>`) and the row carries the shared fields of
+[workspace triggers and schedules](#workspace-triggers-and-schedules-feature-automations-oats-0290-automationsapi-1).
+
+```json
+{"triggerApi":1,"scope":"/abs/deployment","triggers":[
+  {"id":"okf-harvest-review","enabled":true,"kind":"trigger",
+   "on":{"source":"github.pull_request","repo":"github.com/acme/knowledge","events":["opened","reopened","ready_for_review"],"labels":["okf-harvest"],"base":"main","poll":"2m"},
+   "spawn":{"soul":"oats.okf/knowledge-maintainer","purpose":"review-pr-{number}","task":"…","teams":["okf"],"launchConfig":"reviewers","harness":"claude","model":"opus"},
+   "concurrency":{"max":2,"perKey":1},"template":{"package":"oats.okf","version":"4.0.0","commit":"<oid>","template":"harvest-review"},
+   "triggerApi":1,"scope":"/abs/deployment","createdAt":"<iso>","updatedAt":"<iso>"}]}
+```
+
+- `list` → the document above; `show <id>`, `add`, `enable`, `disable` →
+  `{ trigger }` (one row); a stored definition that no longer validates carries
+  `invalid: { code, message }`. `remove <id>` → `{ removed, live: [instance] }`.
+- `status [<id>]` → `{ triggerApi, scope, triggers: [Status] }`. It writes
+  nothing. Each `Status`:
+  - `id`, `name`, `enabled`, `runsHere`, `reason`, `enabledHere`, `repo`, `soul` (the soul name);
+  - `concurrency: { max, perKey }` and `liveCount`: live instances against `max`;
+    `live: [{ instance, home, repo, number, event }]`;
+  - `lastPoll: { at, ok: true, prs, matching } | { at, ok: false, error } | null`;
+    `nextPollAt`; `nextDue` (the next poll when it runs here, else `null`);
+  - `pending: [{ key, event, number, url, observedAt }]`: observed, not yet spawned
+    (held, or its spawn failed);
+  - `fired: [{ key, at, instance, home, event, number }]` (newest 50) and `firedTotal`;
+  - `lastError: { at, code, message, key? } | null`.
+- `test <id>` → `{ triggerApi, id, ok, gh: { ok, account, credentialSource:
+  "keyring" | "config" | "env:<VAR>" | "unknown" | null, reachesHostTimer:
+  boolean | null, note, detail }, repo: { key,
+  readable, fullName, permissions: { push, maintain, admin }, canMerge } |
+  { key, readable: false, error }, soul: { resolves, name, agent, messaging } |
+  { resolves: false, name, error }, teams: { requested, undeclared | null,
+  messaging }, wouldFire: [{ key, repo, number, event, url, held? }], pollError?, problems:
+  [string], warnings: [string], spawned: false }`. It writes nothing. `ok`
+  counts `problems` only; a credential the host timer cannot reach
+  (`reachesHostTimer: false`) is a warning.
+- `oats schedule list --json` gains `triggers: { count, command: "oats trigger
+  list" }`: the triggers it does not list.
+- The tick's `considered[]` gains trigger rows `{ workspace, trigger, action,
+  … }` with `action` `not-due`, `poll-failed`, `polled` (`prs`, `matching`;
+  nothing to fire), `held`, `fired` (`key`,
+  `instance`, `home`), `spawn-failed` (`key`, `code`, `error`), `would-fire`
+  (`--dry-run`) or `invalid`.
+- A triggered instance's `instance.json.trigger` is `{ id, key, source, repo,
+  number, url, event, headSha, observedAt, eventFile }`; the event file is
+  `OATS_TRIGGER_EVENT_FILE`.
+- Errors: `E_TRIGGER_INVALID { field }`, `E_TRIGGER_EXISTS`,
+  `E_TRIGGER_UNKNOWN`, `E_BAD_ARGS` (`missing` / `parameters` for a template),
+  `E_PACKAGE_MISSING`, `E_PACKAGE_MANIFEST`, `E_LOCAL_MISSING`.
+
+### Workspace triggers and schedules (feature `automations`, OATS 0.29.0; `automationsApi: 1`)
+
+See [schedules.md#workspace-triggers-and-schedules](schedules.md#workspace-triggers-and-schedules).
+`oats trigger list --json` and `oats schedule list --json` answer this machine's
+local items and every workspace item defined in a member the user can read. The
+Desktop renders these rows and never re-derives them. The two lists stay separate:
+a trigger never appears in `schedule list`, and a schedule never appears in
+`trigger list`.
+
+- Both lists add:
+  - `host: { name | null, ghUser: { <gh host>: <login> | null } }`: this machine's
+    `oats-local.yaml` `host.name`, and who its `gh` is logged in as on every GitHub
+    host the rows name (the owners'; a trigger's repository's) — `null` when `gh`
+    is not authenticated there. The Desktop compares it with a row's `owner`.
+  - `snapshot: { takenAt, problems } | null` (`null` until `oats sync` has found some).
+  - `scheduler: { installed, active, registered, lastTick, maxConcurrent, … }`: the
+    host tick (the same object as `oats schedule host status`). Nothing runs unless
+    it is installed, active and this deployment is registered.
+- **Identity:**
+  - `id`:
+    - a trigger row's is always qualified (`local/<id>`, `<member>/<id>`);
+    - a local schedule row keeps its bare id (the 0.28 contract);
+    - a workspace schedule row's is `<member>/<id>`.
+  - `qualifiedId` is always the qualified form, and `name` is the bare id.
+  - Every verb accepts `local/<id>` or a bare local id.
+- **Shared fields in every row:**
+  - `origin`: where the item is defined, and where to open it:
+    - `{ kind: "local", path: "oats-schedules.json", url: null, localPath }`;
+    - `{ kind: "workspace", repoKey, path, commit, url, localPath }`: `url` is the
+      file's web URL at `commit` (`https://github.com/<owner>/<repo>/blob/<commit>/<path>`
+      for a `github.com` member, else `null`); `localPath` is the file in this
+      machine's clone of the member (`null` when the member is not cloned here).
+  - `description`, `owner`, `runsOn`;
+  - `runsHere`; `reason` (`null` | `host-unnamed` | `assigned-elsewhere` | `owner-mismatch`) with `reasonDetail`;
+  - `enabledHere`;
+  - `soul`: `{ name, origin } | null` (`null` for a command, wake or operation schedule). `origin` is where the name resolves, per the snapshot:
+    - `{ kind: "member", repoKey, member }`: a soul in a workspace member;
+    - `{ kind: "package", package, version }`: a soul of a locked package;
+    - `{ kind: "external", repoKey, source }`: an external soul (`source` is the workspace's `external[].source` ref);
+    - `{ kind: "ambiguous", candidates }`: a bare name several souls answer to (`candidates` is how many); a spawn needs the qualified name;
+    - `null`: not found (or no snapshot yet).
+  - `task`: the template, verbatim;
+  - `teams`, `launchConfig`, `harness`, `model`, `concurrency`;
+  - `lastRun`, `nextDue`;
+  - `invalid?: { code, message, field? }`.
+- **A trigger row** also carries `kind: "trigger"`, `on`, `spawn`, and `template?`:
+  - `on: { source: "github.pull_request", repo: "<host>/<owner>/<repo>", events: [opened | reopened | ready_for_review | labeled | synchronize], labels: [string], base?: string, poll: "<n>s|m|h" }` (`base` absent: any base branch);
+  - `spawn: { soul, purpose, task, teams: [label], launchConfig?, harness?, model?, yolo?, backend? }`
+    (`purpose` and `task` are templates over `{repo}`, `{number}`, `{url}`, `{event}`, `{trigger}`, `{headSha}`;
+    `launchConfig` names a launch configuration in the running host's `oats-local.yaml`);
+  - `template?: { package, version, commit, template }`: the package template it was added from.
+  - `lastRun` is the last fired event: `{ at, instance, home, event, number, key }`.
+  - `nextDue` is the next poll, only when it runs here; `null` before its first poll (it polls at the next tick).
+- **A schedule row** keeps every 0.28 field (`scheduleApi: 2`). Its `kind` is the run (`spawn` | `command` | `wake` | `operation`); it also carries `cron` and `tz`.
+  - `nextDue` is the next minute, only when it runs here.
+  - `teams` is `[]` and `concurrency` is `null`.
+  - A workspace schedule another host runs carries its definition and placement only: `lastRun` and `nextDue` are `null`.
+  - A spawn schedule's `launchConfig` names a launch configuration in the running host's `oats-local.yaml`.
+- **Naming:** `nextDue` is the one name for "when it next runs" in every trigger and
+  schedule row. A schedule row still carries the 0.24 `nextRun` for older readers;
+  they agree whenever it runs here.
+- **Actions:**
+  - `enable` and `disable` on a workspace id edit `oats-local.yaml` `triggers.disabled` or `schedules.disabled`.
+  - `update` and `remove` refuse it with `E_AUTOMATION_WORKSPACE { id, origin }`.
+  - `schedule run` and `schedule reconcile` work when it runs here, else `E_AUTOMATION_NOT_HERE { id, reason, runsOn, owner }`.
+- **`oats trigger test <id>`** adds `placement: { runsOn, owner, host, runsHere, reason, detail?, enabledHere }`. Any reason, or disabled here, is a problem (`ok: false`).
+- **`oats schedule test <id> --json`** (local or workspace) → `{ test: { id, qualifiedId, kind,
+  placement: { runsHere, reason, reasonDetail?, enabledHere, runsOn, owner, host },
+  soul: { name, origin, resolves, error: { code, message } | null } | null, nextDue,
+  spawned: false, problems: [string], ok } }`. `soul` is checked the way the run
+  would start it (`oats spawn <soul> --preview`, which writes nothing); it is `null`
+  for a command, wake or operation. `nextDue` is the next cron match whether or not
+  this host runs it (`placement` says that). Not running here, disabled, invalid or a
+  soul that does not resolve is a problem (`ok: false`). It spawns nothing and records
+  nothing. Errors: `E_SCHEDULE_UNKNOWN`, `E_BAD_ARGS`.
+- **`oats trigger|schedule add … --workspace <member> --runs-on <host> --owner <host>/<login> --json`** answers `{ id, written, file: { member, repoKey, path, content, written? } }`.
+  - Errors: `E_AUTOMATION_MEMBER` (not a confirmed member), `E_TRIGGER_EXISTS` or `E_SCHEDULE_EXISTS` (the file exists), and the kind's validation codes.
+- **`oats automations refresh --json`** answers `{ automationsApi, snapshot, triggers, schedules, problems: [...], takenAt }`.
+- **`oats sync --json`** gains `automations: { triggers, schedules, problems, takenAt }`. Discovery problems join `problems` (`E_AUTOMATION_SCHEMA`, `E_AUTOMATION_DUPLICATE`, each with `kind`, `repoKey` and `path`).
+- **`oats workspace status --json`** gains `automations: { host, snapshot, rows: [{ kind, id, runsOn, owner, runsHere, reason, enabledHere, origin, invalid? }] }`.
+- **The tick's `considered[]`** gains the trigger action `not-here` (`reason: owner-mismatch`, `detail`): a trigger naming this host that this host cannot run. A workspace schedule's row `id` is its state key, `<member>~<id>`. A failed snapshot refresh is `{ action: "error", error: "automations refresh: …" }`.
+
+### Desktop facts (feature `desktop-facts`, OATS 0.29.0)
+
+These are facts the Workspace view shows. The kernel reports them so the
+Desktop never works them out itself. Gate reading every field below on
+`desktop-facts` in `features[]`. No API integer changes, and every field is an
+addition to an existing row.
+
+**`oats inspect --soul <name> --json`: why each capability is there**
+
+- `capabilities[].composedFrom` says which layer put the module in the soul:
+  `"workspace"` (`defaults.<slot>` or `defaults.capabilities`),
+  `"team:<label>"` (`defaults.byTeam.<label>.capabilities`) or `"soul"` (the
+  soul's own `capabilities:`). This is the same vocabulary as
+  `layers.<slot>.from`. It is `null` on `inspect --home`, because a spawn does
+  not record it. `from` stays the module's origin object (`{kind, repoKey,
+  commit}` or the package object), so it is a separate key.
+- `capabilitiesOff[]` lists the capabilities the soul turned off, which a
+  lower layer would otherwise have given it. They are not rows of
+  `capabilities[]`, because those are resolved modules with operations. Each
+  entry is `{ id, off: true, from: "soul", reason, slot?, overrides }`:
+  - `reason: "off"`: the soul wrote `<id>: off` over a workspace or team
+    default.
+  - `reason: "slot-none"`: the soul wrote `<slot>: none` (`slot` names it),
+    which emptied the slot the workspace filled with `<id>`.
+  - `overrides`: the layer whose default was turned off (`"workspace"` or
+    `"team:<label>"`).
+  - Sorted by id. `[]` on `inspect --home`.
+
+**`oats souls --json` rows**
+
+- `harness`, `model`, `harnessFrom`: what a spawn of the soul starts with
+  when no `--harness`/`--model` is given. A v2 `soul.yaml` cannot declare a
+  harness or a model, so today this is always `harness: "pi"`, `model: null`
+  (the harness's native model) and `harnessFrom: "kernel-default"`.
+  `harnessFrom: "soul"` is reserved for a schema that lets a soul declare
+  one.
+- `spawnable`, `problem`: whether a spawn here would refuse.
+  - `problem` is `{ code, message }` when a spawn would refuse, else `null`.
+  - The kernel resolves the soul exactly as a spawn does, but spawns nothing,
+    writes nothing and reads only the sync cache.
+  - Codes: `E_SOUL_DISABLED` (this machine's `souls.disabled`),
+    `E_TEAM_CONFLICT`, `E_CAPABILITY_MISSING`, `E_CAPABILITY_PRIVATE`,
+    `E_CAPABILITY_INCOMPATIBLE`, `E_PACKAGE_MISSING`, `E_PACKAGE_INTEGRITY`,
+    `E_LOCK_SCHEMA`, `E_REMOTE_*`, and any other resolution refusal.
+  - An `E_TEAM_UNKNOWN` problem in `problems[]` is informational. It does not
+    make a soul unspawnable.
+- `file`: `{ path, url }`, the soul's `soul.yaml` in its repository (see
+  **URLs** at the end of this section).
+
+**`oats capabilities --json` rows**
+
+- `layer` on every row. Package rows now carry it too, from the package
+  manifest; `null` for a capability outside the slots.
+- `description`: the manifest's `description`, or `null`.
+- `skills`, `commands`, `hooks`: what the capability provides, by name,
+  sorted.
+  - `skills` is enumerated as a spawn would. It is `null` when the declared
+    skills cannot be listed, which a spawn of it would refuse.
+  - `commands` and `hooks` are the keys of the manifest's `commands` and
+    `hooks`.
+- `file`: `{ path, url }`, the capability's `oats.json`, or `null` when the
+  manifest cannot be read.
+- `tree`: a member capability's fingerprint, the Git tree id of its
+  directory at the member commit. The same bytes give the same id. It is
+  `null` on package rows, whose fingerprint is `integrity` in the lock (see
+  `oats workspace status`).
+- A package whose manifests cannot be read at its locked commit leaves these
+  facts `null` on its rows.
+- Package manifests are read at the locked commit from the sync cache. There
+  is no network beyond what `sync` already fetched.
+
+**`oats workspace status --json`**
+
+```json
+{"workspace":{"…":"…","file":{"path":"oats-workspace.yaml","url":"https://github.com/acme/agents/blob/<oid>/oats-workspace.yaml"}},
+ "members":[{"…":"…","url":"https://github.com/acme/tools/tree/<oid>","membershipFile":{"path":"oats-membership.yaml","url":"https://github.com/acme/tools/blob/<oid>/oats-membership.yaml"}}],
+ "packages":[{"id":"oats.okf","version":"3.0.0","source":"catalog:oats.okf","commit":"<oid>","…":"…","latest":{"version":"4.0.0","ref":"v4.0.0"}}],
+ "defaults":{"slots":{"knowledge":{"name":"oats.okf","from":"package"},"messaging":"none","tasks":null},
+             "capabilities":[{"name":"acme-house-style","from":"github.com/acme/agents","off":false}],
+             "byTeam":{"engineering":{"capabilities":[{"name":"acme-house-style","from":null,"off":true},{"name":"acme-deploy","from":"package","off":false}]}}},
+ "clones":[{"key":"github.com/acme/agents","name":"agents","path":"/abs/acme-workspace/agents","rule":"convention"},
+           {"key":"github.com/acme/tools","name":"tools","path":null,"rule":null}],
+ "disabledSouls":["release-reviewer"],
+ "lock":{"path":"/abs/acme-workspace/oats-lock.json","lockfileVersion":3}}
+```
+
+- `defaults`: the workspace file's defaults, as declared rather than
+  resolved for a soul.
+  - `slots.<slot>` is `{ name, from }` when the workspace fills it, `"none"`
+    when it empties it, and `null` when it says nothing.
+  - `capabilities` and `byTeam.<label>.capabilities` are rows `{ name, from,
+    off }`, sorted by name. `from` is the declared location (`"package"`,
+    `"here"` or a member repo key); an `off` row has `from: null`.
+  - Standalone: slots `null`, `capabilities: []` and `byTeam: {}`.
+- `clones`: this computer's clone of each member.
+  - `path` is the absolute clone, or `null` when this machine has none.
+  - `rule` names what found it: `"clones"` (the `oats-local.yaml` `clones:`
+    entry) or `"convention"` (`<deployment>/<member name>`). It is `null`
+    with no clone.
+  - A path that is not the member's clone gives `path: null, rule: null,
+    problem: { code: "E_CLONE_MISMATCH", message }`, the refusal a spawn
+    would meet.
+  - (`--repo` is a spawn option, so it plays no part here.)
+- `disabledSouls`: `oats-local.yaml` `souls.disabled`, as written.
+- `lock`: `{ path, lockfileVersion }`. The per-package commit is each
+  `packages[]` row's `commit`, and its fingerprint is `integrity`.
+- `packages[].latest`: `{ version, ref }` when the official catalog shipped
+  with this kernel has a newer version of a catalog-sourced package than the
+  lock holds. It is `null` when the pin is current and for `git:` packages.
+  It never reaches the network: the catalog is the kernel's own
+  (`OATS_PACKAGE_CATALOG` overrides it, as for `sync`).
+- `workspace.file` is `{ path, url }` for the workspace file in the
+  workspace repository (at `workspace.key` @ `workspace.commit`). It is
+  `null` for a standalone deployment.
+- `members[].url` is the member repository at its commit.
+  `members[].membershipFile` is `{ path, url }`.
+
+**`oats status --json` instance rows**
+
+- A member module's `modules[].current` gains `version` (the capability's
+  manifest version at the current commit, `null` when it has none) beside
+  `commit`, on `current` and `moved` rows. Package rows already carried it. On a `moved` row, the recorded `commit`/`from` and `current`
+  together say what moved and to what.
+- `startedAt`: the last session start or restart (the session receipt). A
+  home spawned with a launch and never restarted uses `createdAt`. A home
+  never launched is `null`. `createdAt` stays the spawn time.
+- `modelFrom`: where the model the home runs came from.
+  - `"soul"`: the soul's model preference.
+  - `"spawn"` or `"start"`: an explicit `--model` on that command.
+  - `"launch-config"`: a launch configuration's model.
+  - `"harness-default"`: the harness's own model.
+  - A start that reuses the recorded model keeps the recorded answer.
+  - `null` for a home spawned before 0.29.0. `instance.json` records it as
+    `modelFrom`.
+- `identityAddress`: the messaging identity's `address` (else `alias`) that
+  the messaging capability recorded (`capabilityMeta.<messaging>.identity`),
+  passed through unchanged. `null` otherwise.
+
+**URLs.** Every `url` is a browsable page of
+the file (or of the repository, for a member) at the commit the row names.
+Only repositories on `github.com` have one (`https://github.com/<org>/<repo>/blob/<commit>/<path>`,
+or `/tree/<commit>`). Every other host and local repository gives `url:
+null`, with `path` still set. `path` is relative to that repository's root.
+
+**Help.** `oats help` lists `spawn … [--provider <capability> <key>=<value>]`.
 
 ### Eligible teams (feature `teams`, OATS 0.26.0)
 

package/docs/implementation.md

@@ -113,7 +113,7 @@ what they contribute stays with them.
 
 After the canonical soul and kernel text, every generated `AGENTS.md` states the
 runtime-neutral **home/work boundary** (`injects/instance-boundary.md`) — for
-every work mode and for capability service agents alike — immediately before the
+every work mode and for service souls (the post-commit reviewer) alike — immediately before the
 work-mode block it frames: `<instance-home>` (`$OATS_INSTANCE_HOME`) holds the
 brain, task, provenance and working state, and is where OATS operational/lifecycle
 commands are run from — together with the commands of whatever capabilities are

package/docs/knowledge-capability-authoring.md

@@ -57,8 +57,14 @@ source. The current authoring-reference patch is package 1.0.1: once framework
 v0.23.1 is published, an explicit initial Git acquisition at that tag selects
 the patch instead. It does not silently change the catalog's 1.0.0 selection
 or an existing lock. For local development, use an explicit complete source
-package path instead. Activation exposes the expert and targets
-the authoring skill, without selecting or replacing a knowledge capability.
+package path instead. Activation targets the authoring skill, without
+selecting or replacing a knowledge capability.
+
+The expert is an oats.framework **package soul** from framework 1.3.0
+(`oats-package/souls/knowledge-theory-expert/`, reading `oats.knowledge-theory`
+1.1.0 from its own package): spawn it by its qualified name in the author's
+repository, `oats spawn oats.framework/knowledge-theory-expert --repo <repo>`.
+Before 1.3.0 it was a capability-defined agent, which OATS 0.29.0 removed.
 There are no executable surfaces to trust in this package. Installed experts
 use their materialized local curriculum, not this repository at runtime.
 

package/docs/knowledge-reference/package-craft.md

@@ -35,8 +35,7 @@ A knowledge implementation's capability manifest might begin:
   "compatibility": { "oats": ">=0.22.19" },
   "layer": "knowledge",
   "skills": ["skills/native-reader", "skills/native-harvest"],
-  "inject": "injects/knowledge.md",
-  "agents": ["agents/native-harvester"]
+  "inject": "injects/knowledge.md"
 }
 ```
 
@@ -49,14 +48,18 @@ kernel's real manifest validation, not this example as a complete schema.
 
 The optional `oats.knowledge-theory` capability is deliberately **different**:
 it is additive, declares no layer, injection, command or hook, and supplies
-only an expert and its authoring skill. It neither selects knowledge policy nor
+only its authoring skill; the expert that uses it is the oats.framework package
+soul `knowledge-theory-expert`. It neither selects knowledge policy nor
 depends on OKF. A runtime integration should not depend on it just to inherit
 mandatory doctrine. Explicit versioned reuse is a choice, not a requirement.
 
 ## Soul craft
 
-A capability's `agents/<name>/` contains `soul.yaml`, canonical `AGENTS.md` and
-relative `CLAUDE.md -> AGENTS.md`. Keep role instructions to a screen or two:
+An agent a package ships is a **package soul**: `souls/<name>/` beside the
+package's capabilities (listed in `oats-package.json` `souls:`), holding
+`soul.yaml`, canonical `AGENTS.md` and relative `CLAUDE.md -> AGENTS.md`; it
+reads the package's own capabilities with `from: here`. (A capability manifest
+declares no agents: `agents:` was removed in OATS 0.29.0.) Keep role instructions to a screen or two:
 role and boundaries, operating loop, verification, local skill pointer,
 escalation. Do not bury an entire curriculum in always-loaded instructions.
 

package/docs/knowledge.md

@@ -311,6 +311,107 @@ receipts. Inputs are processed only when required destinations resolve. All-drop
 or no-change judgment can be successful without inventing a PR. Enqueue, worker
 spawn and command exit alone are not successful learning.
 
+## Knowledge operations
+
+> **Version scope:** oats.okf **4.0.0** on kernel **0.29.0** (package souls,
+> triggers and workspace automations). Everything above describes the 2.x runtime, which 4.0.0 keeps for
+> capture, custody and delivery. The design and its decisions are in
+> [the knowledge-operations plan](design/2026-09-26-okf-knowledge-operations.md).
+> The setup procedure is the `oats-onboarding` skill ("Knowledge operations with
+> OKF") and okf's `okf-trigger-setup`.
+
+From 4.0.0, harvested knowledge is judged by a harvester, reviewed by a
+maintainer and merged without an operator in the loop, except where a merge
+would supersede a human-accepted decision.
+
+### The flow
+
+1. **Capture.** A working soul whose knowledge slot is `oats.okf`, on a host
+   where harvest is on (below), registers a source at spawn. Capture and
+   custody are as above: notes and bounded transcript windows, copied outside
+   the home.
+2. **Harvest.** The source's `run-source` job spawns the package soul
+   `oats.okf/knowledge-harvester` (team `okf`). It reads the input in full,
+   transcript windows included, and judges it with the OKF promotion
+   doctrine. It stages edits on the owned nodes and opens a PR on the
+   knowledge-base repo, labelled `okf-harvest`, whose body carries a fenced
+   `okf-harvest` provenance block (the run, the source soul and instance, the
+   owned and read nodes, the task references, the harvester's alias). It
+   stays alive, answering questions in `okf`, until the PR is merged or
+   closed, then retires. `harvester-max-age` (default 7d) bounds it; it never
+   closes its own PR.
+3. **Trigger.** The workspace declares the trigger in a member repo,
+   `oats-triggers/okf-harvest-review.yaml` (`kind: oats-trigger`), from the package template
+   `oats.okf:harvest-review`. It names the host that runs it (`runsOn`, that
+   machine's `host.name`) and the GitHub account it acts as (`owner`, which
+   must be able to merge on the knowledge-base repo). Only that host, logged
+   in to `gh` as that account, polls for such PRs. For each one it spawns a
+   NEW `oats.okf/knowledge-maintainer`, joining `okf`. The event reaches it as
+   `OATS_TRIGGER_EVENT_FILE`. A local trigger (`oats trigger add`, this host
+   only) is the machine-private alternative. Triggers are described in
+   [schedules.md, "Triggers"](schedules.md#triggers), and the workspace
+   file in ["Workspace triggers and schedules"](schedules.md#workspace-triggers-and-schedules).
+4. **Review.** The maintainer checks out the PR and situates it: the
+   provenance, the source soul's owned and read nodes, the neighbouring
+   concepts, and the source's tickets when a tasks capability can read them.
+   It records a verdict on the PR (`merge`, `amend+merge`, `request-changes`
+   or `close`), amends what needs amending, and merges with the host's `gh`. A
+   PR that would supersede a concept with human acceptance evidence is not
+   merged: it is labelled `okf-needs-human` for the workspace's human. The
+   maintainer tells the harvester the outcome and retires.
+
+### Who gets which okf skills
+
+| Capability | Composed into | Skills | Inject |
+|---|---|---|---|
+| `oats.okf` | every working soul whose knowledge slot it fills | `okf-consultation` (reading soul knowledge and citing it); `okf-instance-knowledge` (what instance knowledge is worth capturing, and the form of `STATE.md`, `log.md` and `notes/`) | the work mode: consult instance memory and soul knowledge at task start, after compaction and before decisions; capture before compaction |
+| `oats.okf-harvest` | `oats.okf/knowledge-harvester` only | `knowledge-theory` (the OKF promotion doctrine); `knowledge-harvest` (the procedure, through the PR's lifetime); `okf-authoring` | the harvester's: a judge, not a worker; the staged roots are its only write surface |
+| `oats.okf-maintenance` | `oats.okf/knowledge-maintainer` only | `knowledge-theory`; `knowledge-review`; `okf-authoring`; `okf-trigger-setup` | the maintainer's: one PR per instance; supersede explicitly, never silently |
+
+Working souls get no promotion doctrine: the harvester is the only judge of
+what is promoted, and the maintainer the only one who merges. The shared
+skills ship as identical copies in each capability. The harvester and the
+maintainer hold no knowledge slot, so nothing harvests them.
+
+### The harvest switch
+
+Harvest is off unless both the host and the soul allow it:
+
+| Where | Setting | Effect |
+|---|---|---|
+| The host, `oats-local.yaml` | `settings.oats.okf.harvest: on` (default `off`) | This host harvests its working souls. |
+| A soul, `soul.yaml` | `knowledge: { harvest: off }` | This soul is never harvested, whatever the host says. |
+
+Off means **no capture at all**: no source is registered and no transcript or
+notes enter custody, so nothing accumulates for later. Turning it on starts
+with the next session. `oats okf setup --harvest on|off` writes the host
+setting, and `oats okf harvest-status [--soul <soul>]` reports the effective
+value, the row that decided it and the registered sources.
+`oats schedule disable <job>` on a source's `run-source` job is an emergency
+brake for one source, not the switch. The review trigger does not depend on the
+switch: a host can review harvest PRs from other hosts without harvesting.
+Keep harvest off until the end-to-end check in `okf-trigger-setup` passes.
+
+### The `okf` team
+
+The package souls carry `team: okf`. The workspace declares the label and maps
+it to a messaging team:
+
+```yaml
+teams:
+  okf: { description: Knowledge operations }
+messaging:
+  byTeam:
+    okf: { team: <messaging team id> }
+```
+
+Harvesters and maintainers talk there (subjects prefixed `okf:` with the PR's
+URL) without writing into the working teams. Like every label it organises and
+gates nothing. A workspace without it reports `E_TEAM_UNKNOWN` on both package
+souls in discovery. They still spawn, but into no messaging team, so the
+harvester and the maintainer cannot talk, and `oats trigger test` fails its
+team check.
+
 ## Inspection and operator commands
 
 Run home-local commands from that source home: inside an instance the