@awebai/oats 0.28.0 → 0.29.0

package/capabilities/oats-okf-maintenance/skills/okf-trigger-setup/SKILL.md

@@ -0,0 +1,146 @@
+---
+name: okf-trigger-setup
+description: >-
+  Set up and verify the OKF harvest-review trigger, which spawns a knowledge
+  maintainer for each harvest PR: declare it as a workspace automation
+  (`oats-triggers/okf-harvest-review.yaml` in a member repo, `from:
+  oats.okf:harvest-review`, with `runsOn` naming the one host and `owner` the
+  GitHub account that can merge on the knowledge-base repo), or locally with
+  `oats trigger add` for a machine-private setup. Covers the okf team, the
+  self-approval limit and `oats trigger test`. Use when setting up knowledge
+  operations, when harvest PRs are not being reviewed, when moving the
+  reviewer to another host, or when asked whether a host may run the
+  maintainer.
+---
+
+# Setting up the harvest-review trigger
+
+The trigger makes a harvest PR get reviewed: when a PR labelled `okf-harvest`
+opens on the knowledge-base (KB) repository, the host tick spawns a new
+`oats.okf/knowledge-maintainer` in the `okf` team to review it. It runs on one
+machine, acting as one GitHub account, and that account must be able to
+**merge** on the KB repository.
+
+## 1. Choose the host and the account
+
+- **The account (`owner`)** must be able to merge on the KB repository (push,
+  maintain or admin). Check from the host:
+  `gh api repos/<owner>/<repo> --jq .permissions`.
+- **The host (`runsOn`)** is the one machine that runs the trigger, named by
+  its `oats-local.yaml` `host: { name: <slug> }`, and logged in with `gh` as
+  that account.
+- **The harvest switch is independent**: a review host need not harvest (its
+  `harvest` setting can stay `off`), and a harvesting host need not review.
+
+## 2. The self-approval limit
+
+GitHub forbids approving your own account's PR. If the harvester's host and
+the reviewer's account are the same GitHub account, then either:
+- the KB repository's `main` must not require approving reviews (merge
+  permission is enough; the maintainer records its verdict as a PR comment,
+  not an approval), or
+- the trigger's `owner` is a separate reviewer account or machine user.
+
+Say which one applies when you report the setup.
+
+## 3. The okf team
+
+The package souls carry `team: okf`. The workspace must declare it, with its
+messaging mapping. Messaging is aweb (`oats.aweb`, the workspace default);
+it needs oats.aweb 1.15.0 or later, which honours the `join=okf` the
+harvester spawn and the trigger's `teams: [okf]` pass:
+
+```yaml
+# oats-workspace.yaml
+teams:
+  okf: { description: Knowledge operations }
+defaults:
+  messaging: { oats.aweb: { from: package } }
+messaging:
+  byTeam:
+    okf: { team: aweb:<your-org>.okf }
+```
+
+Another messaging provider works the same way if it honours `join`.
+
+Without it, the souls list with `E_TEAM_UNKNOWN`, and the harvester and the
+maintainer cannot message each other.
+
+## 4. Declare it in the workspace (the default)
+
+A team relies on the review, so declare it in Git, in a member repository (the
+workspace's host repo), in its `oats-triggers/` folder:
+
+```yaml
+# <member>/oats-triggers/okf-harvest-review.yaml
+kind: oats-trigger
+schemaVersion: 1
+description: Review every OKF harvest PR on the knowledge base
+from: oats.okf:harvest-review
+set: { repo: github.com/<owner>/<kb-repo> }     # optional: base, harness, model
+runsOn: <host.name of the one machine>
+owner: github.com/<the merge-capable account>
+```
+
+- `kind: oats-trigger` and `schemaVersion: 1` make the file self-describing; a
+  wrong kind is `E_AUTOMATION_SCHEMA`.
+- The id is `id:` if present, else the filename stem (`okf-harvest-review`).
+  Two files with the same id in one member are `E_AUTOMATION_DUPLICATE`.
+- A file named `*.oats-trigger.yaml` anywhere in the member works too (never
+  under `oats-package/`, `.git/` or `node_modules/`); `oats-triggers/` is the
+  canonical place.
+
+Or let the CLI write it: `oats trigger add --from oats.okf:harvest-review
+--set repo=github.com/<owner>/<kb-repo> --workspace <member>` (it prints the
+file when that repository is not the current checkout). Commit and merge it
+like any other change.
+
+A host runs it only when **both** its `host.name` equals `runsOn` **and** its
+`gh` account equals `owner`. Everywhere else it is listed with the reason:
+`assigned-elsewhere`, `owner-mismatch` or `host-unnamed`. That keeps exactly
+one machine on it, and the operator's consent explicit. A host can opt out
+without a commit: `automations.disabled: [<member>/okf-harvest-review]` in its
+`oats-local.yaml`. Changes reach the host within about ten minutes (after
+`oats sync`, or the tick's refresh).
+
+## 5. Or add it locally (machine-private)
+
+For a personal or experimental setup, add it to this deployment only. It runs
+on this host with this host's `gh`, with no `runsOn` or `owner`:
+
+```sh
+oats trigger add --from oats.okf:harvest-review --set repo=github.com/<owner>/<kb-repo>
+#   optional: --set base=main --set harness=claude --set model=opus --id okf-harvest-review
+```
+
+Never run the same review from two places: one workspace declaration, or one
+local trigger on one host.
+
+## 6. Test it on the host that runs it
+
+```sh
+oats trigger test <member>/okf-harvest-review   # or: oats trigger test okf-harvest-review (local)
+oats schedule host install                      # the host timer, if the test says it is missing
+oats trigger status
+```
+
+- `oats trigger test` checks gh auth and where its credential comes from, the
+  repository and your merge permissions, the soul, its messaging capability,
+  the okf team, the host/owner match, and what would fire now. It spawns
+  nothing. It must pass before you report the setup done; fix what it names.
+- **Credentials reach the tick through the host timer, not your shell.** A
+  `GH_TOKEN` exported in your shell does not reach it; `gh auth login` with the
+  keyring or config file does.
+- Pause with `oats trigger disable <id>`; `remove` leaves running maintainers
+  alone.
+
+## 7. Labels
+
+Harvest PRs carry `okf-harvest` (the harvester's completion creates the label
+if the repository lacks it). The maintainer adds `okf-needs-human` when a PR
+would supersede a human-accepted decision. To pre-create both:
+
+```sh
+gh label create okf-harvest --repo <owner>/<repo> --force --color 0E8A16 --description "OKF harvest PR (oats.okf)"
+gh label create okf-needs-human --repo <owner>/<repo> --force --color D93F0B --description "OKF: needs a human decision"
+```

package/capabilities/oats-review/injects/review.md

@@ -11,8 +11,9 @@ oats spawn reviewer --work attached --work-dir "$PWD/work" \
   --task "Review commit <sha> on branch <branch>. Report to <your-instance> per your operating loop."
 ```
 
-- `--purpose "<short-sha>"` gives the reviewer a unique, commit-relevant
-  instance name (`reviewer-<short-sha>`); attached mode shares your work tree
+- `reviewer` is the oats.dev package's soul (`oats.dev/reviewer`).
+  `--purpose "<short-sha>"` gives it a unique, commit-relevant instance name
+  (`oats-dev-reviewer-<short-sha>`); attached mode shares your work tree
   and automatically makes the reviewer your child (attached agents are always
   children of the work-tree owner — no relation flags needed or allowed).
 - The reviewer reviews **that commit's diff only** and reports its verdict

package/capabilities/oats-review/oats.json

@@ -1,11 +1,10 @@
 {
   "capability": "oats.review",
   "private": true,
-  "version": "1.2.1",
-  "compatibility": { "oats": ">=0.26.0" },
-  "description": "Post-commit review discipline: a fresh reviewer agent (defined by this capability) reviews each new commit's diff, reports its verdict to its spawner over the deployment's messaging layer (or in its transcript when there is none), and retires — plus the shared developer delivery discipline.",
+  "version": "1.3.0",
+  "compatibility": { "oats": ">=0.28.0" },
+  "description": "Post-commit review discipline: a fresh reviewer (this package's soul `reviewer`) reviews each new commit's diff, reports its verdict to its spawner over the deployment's messaging layer (or in its transcript when there is none), and retires — plus the shared developer delivery discipline and the reviewer's code-review and security-review skills.",
   "requires": [],
-  "agents": ["agents/reviewer"],
   "skills": ["skills/code-review", "skills/security-review"],
   "inject": "injects/review.md"
 }

package/docs/capabilities.md

@@ -72,7 +72,7 @@ A self-contained package has an `oats.json`:
 - `compatibility.oats` is the kernel range the capability runs on. The kernel
   refuses to compose a capability whose range does not admit it
   (`E_CAPABILITY_INCOMPATIBLE`, naming capability, range and kernel) wherever a
-  soul or capability agent resolves (spawn, `spawn --preview`, `inspect
+  soul resolves (spawn, `spawn --preview`, `inspect
   --soul`, operator commands). `oats inspect` shows each module's
   `compatibility: { ok, range, kernel }`; a home whose spawned module no longer
   admits the running kernel reports a `capability-incompatible` problem.
@@ -302,6 +302,19 @@ workspace's decision to trust it. A soul names a package capability with
 packages is in [packages.md](packages.md). There is no installed
 copy at a deployment and no `oats install`/`trust`/`update`/`remove`.
 
+One package can carry capabilities meant for **different souls**. oats.okf
+4.0.0 ships three:
+
+- `oats.okf` fills every working soul's knowledge slot;
+- `oats.okf-harvest` is composed only into its harvester soul;
+- `oats.okf-maintenance` is composed only into its maintainer soul.
+
+Each is its own manifest with its own skills, inject and commands. One pin
+versions all three, together with the package's souls
+([knowledge.md](knowledge.md#who-gets-which-okf-skills)). Split a package this
+way when roles need different instructions: a soul composes only the
+capability it names, so no role carries another's procedure.
+
 ## Member capabilities
 
 A capability at `<member repo>/capabilities/<name>/oats.json` is discoverable
@@ -314,13 +327,24 @@ listed (`private: true`, marked "(repo-owned)"), but usable only from its own
 repo (`E_CAPABILITY_PRIVATE` elsewhere). A member's `oats-package/` is **not** a member capability: it is
 reported as `publishes` and consumed only as a package.
 
-## Capability-defined agents
+## Agents a capability needs
+
+A capability declares no agents: `agents:` in a manifest was **removed in
+0.29.0**. Resolution refuses a module that still declares it with
+`E_CAPABILITY_AGENTS_REMOVED { capability, agents }` (spawn, `spawn --preview`,
+`inspect --soul`, operator commands). Ship the agent as a soul instead:
+
+- a **package soul**: `souls/<name>/` beside the package's capabilities, listed
+  in `oats-package.json` `souls:`, spawned as `oats spawn <package>/<name>`
+  (or the bare name when unique), reading the package's capabilities with
+  `from: here` ([packages.md](packages.md#package-souls)). The post-commit
+  `reviewer` is one: oats.dev 1.1.0's `oats.dev/reviewer`, beside `oats.review`;
+- or a **member soul**: `souls/<name>/` in a member repository, using a
+  member capability `from: here`.
 
-A manifest may declare `agents: ["agents/<name>"]` — package-relative soul
-directories (`soul.yaml` + `AGENTS.md` directly inside). *(Open thread: under
-the workspace model these are re-based on member souls — a package repo's
-expert soul is an ordinary `souls/<name>-expert/` in the member; the classic
-lookup still exists for 0.24 layouts.)*
+A home an earlier kernel spawned from a manifest `agents:` soul (its agent
+directory holds only `instances/`) is still listed by `oats status`, may anchor
+a `--parent`, and retires; nothing creates one any more.
 
 ## Commands and hooks
 
@@ -335,7 +359,14 @@ existing manifests load, and change nothing.
 
 Hooks receive `OATS_EVENT`, `OATS_CAPABILITY`, `OATS_LAYER`, `OATS_INSTANCE`,
 `OATS_HOME`, `OATS_AGENT`, `OATS_SOUL`, `OATS_CONTEXT`, `OATS_WORKSPACE`,
-`OATS_ROOT`, `OATS_LEVEL`, `OATS_SETTINGS`, and `OATS_META`. A final JSON line may
+`OATS_ROOT`, `OATS_LEVEL`, `OATS_SETTINGS`, `OATS_SETTINGS_ORIGINS`, and
+`OATS_META`. `OATS_SETTINGS_ORIGINS` (0.29.0) says where each leaf of
+`OATS_SETTINGS` came from: a JSON object from a JSON pointer to `{ kind, at }`,
+`kind` being `manifest-default`, `workspace`, `soul`, `host`, `spawn` or
+`anchor` (the last layer that set it), e.g.
+`{"/harvest":{"kind":"soul","at":"soul.yaml#/knowledge"}}`. A provider tells a
+soul-set value from a host-set one there, and never reads `soul.yaml` for it.
+A home spawned before 0.29.0 recorded none: `{}`. A final JSON line may
 return `meta`, `brief`, `warning`, or harness-specific `launch` arguments. A
 **spawn hook only** may also return an `env` object for the launched process;
 returning `env` from retire or soul-scaffold is an explicit contract error.
@@ -482,7 +513,8 @@ passed as arguments; no shell is involved.
 - Every ambient `OATS_*`, `OAS_*` and `PI_*` variable is removed. Other
   variables pass through.
 - The kernel sets:
-  - `OATS_CAPABILITY` and `OATS_SETTINGS` (the payload as JSON);
+  - `OATS_CAPABILITY`, `OATS_SETTINGS` (the payload as JSON) and
+    `OATS_SETTINGS_ORIGINS` (where each leaf came from, as hooks get it);
   - `OATS_CLI_BIN`;
   - `OATS_WORKSPACE` (the deployment);
   - the team variables `OATS_TEAM_ID` (the messaging payload's `team`: the

package/docs/capability-manifest.schema.json

@@ -262,13 +262,6 @@
       },
       "additionalProperties": false
     },
-    "agents": {
-      "type": "array",
-      "items": {
-        "type": "string"
-      },
-      "description": "Package-relative soul directories (soul.yaml + AGENTS.md) \u2014 capability-defined agents; they resolve where the capability is active, souls stay read-only in the package, instances home under <deployment>/agents/<agent>/instances/."
-    },
     "settings": {
       "type": "object",
       "description": "Declared capability settings: name to { default, values?, description }. Documentation for the values a soul, oats-local.yaml or `oats spawn --provider` supplies; undeclared settings are still accepted.",

package/docs/desktop-cli-api.md

@@ -96,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 |
@@ -253,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
@@ -400,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`.
@@ -755,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},
@@ -1190,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.)
@@ -1238,6 +1244,10 @@ becomes `-`), and that directory is the agent `name` in `oats status --json`
 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`
@@ -1385,13 +1395,15 @@ top-level `workspace` reachability field:
 
 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.
+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"],"harness":"claude","model":"opus"},
+   "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>"}]}
 ```
@@ -1399,18 +1411,24 @@ does not show them.
 - `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: [{ id, enabled, repo, soul,
-  lastPoll: { at, ok, prs, matching } | { at, ok: false, error } | null,
-  nextPollAt, pending: [{ key, event, number, url, observedAt }], fired: [{ key,
-  at, instance, home, event, number }] (newest 50), firedTotal, live: [{
-  instance, home, repo, number, event }], lastError: { at, code, message, key? } | null }] }`.
+- `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, event, number, url, held? }], pollError?, problems:
+  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.
@@ -1428,6 +1446,234 @@ does not show them.
   `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)
 
 A soul's `team` may be a list of labels; the first is the primary

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