@awebai/oats 0.27.2 → 0.28.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
@@ -667,7 +679,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.
@@ -1115,8 +1127,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 +1137,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
@@ -1207,10 +1221,23 @@ 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>`.
+
 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 +1288,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 +1317,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 +1373,60 @@ 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.
+
+```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"},
+   "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: [{ 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 }] }`.
+- `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:
+  [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`.
 
 ### Eligible teams (feature `teams`, OATS 0.26.0)
 

package/docs/oats-local.schema.json

@@ -69,9 +69,10 @@
       "additionalProperties": false,
       "properties": {
         "disabled": {
+          "description": "Souls not run on this machine (a spawn is E_SOUL_DISABLED): a bare soul name disables every soul of that name; a qualified name disables one — <package>/<soul> for a package soul, <member name>/<soul> for a member's.",
           "type": "array",
           "uniqueItems": true,
-          "items": { "type": "string", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$" }
+          "items": { "type": "string", "pattern": "^(?:[a-z0-9][a-z0-9._-]*/)?[a-z0-9]+(?:-[a-z0-9]+)*$" }
         }
       }
     }

package/docs/oats-package.schema.json

@@ -53,6 +53,45 @@
       },
       "uniqueItems": true
     },
+    "souls": {
+      "description": "Package souls (OATS 0.28.0): package-relative soul directories, each an ordinary soul (soul.yaml + AGENTS.md, optional skills/). A soul's name is its directory's. They are versioned and locked with the package (oats-lock.json records each soul's name, path and digest), listed with their package origin, and spawned by the qualified name <package>/<soul> (or the bare name when unique). `from: here` in a package soul is its own package at the locked commit.",
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1,
+        "pattern": "^[^/].*$",
+        "not": {
+          "pattern": "(^|/)\\.\\.(/|$)"
+        }
+      },
+      "uniqueItems": true
+    },
+    "triggers": {
+      "description": "Trigger templates (OATS 0.28.0): `oats trigger add --from <package>:<id> [--set <name>=<value>]…` instantiates one from the locked package. Each file is { parameters: { <name>: { path, required?, default?, description? } }, definition: { …a trigger definition… } }; see docs/schedules.md#triggers.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "file"
+        ],
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z0-9][a-z0-9._-]*$"
+          },
+          "file": {
+            "type": "string",
+            "minLength": 1,
+            "pattern": "^[^/].*$",
+            "not": {
+              "pattern": "(^|/)\\.\\.(/|$)"
+            }
+          }
+        }
+      }
+    },
     "configTemplates": {
       "description": "Named config TEMPLATES: complete reference oats-config.yaml files of the classic line, whose adoption verb is removed under the workspace model. A template is a recommended starting point that becomes ordinary local policy on adoption — adopters may change every copied setting, and package updates never rewrite an adopted config. Templates must stay portable: no secret, credential, account, machine path or provider-local ID. Installation applies none of them. This is the canonical spelling; a manifest may not carry both this and the legacy `configs`.",
       "type": "object",

package/docs/packages.md

@@ -27,7 +27,9 @@ A Git repository **contains** a package at `oats-package/`:
 ```
 
 `oats-package.json` must declare `package` and `capabilities` (a list of
-directories relative to the package root, each holding an `oats.json`). A
+directories relative to the package root, each holding an `oats.json`). It may
+also declare `souls` (0.28.0): soul directories the package ships, see
+[Package souls](#package-souls). A
 directory entry need not equal the capability's name
 (`capabilities/oats-okf` → capability `oats.okf`). A package declaring one
 capability name twice, a listed directory without a manifest, or a manifest
@@ -73,7 +75,7 @@ members:
   - git:github.com/acme/platform
 packages:
   oats.framework: v1.1.3
-  oats.okf: v2.1.5
+  oats.okf: v3.0.0
   oats.aweb: v1.14.2
 teams:
   global: { description: Org-wide }
@@ -172,7 +174,8 @@ same workspace commit hold identical locks.
       "version": "0.4.0",
       "commit": "47f4b81660e4cc9701d373088de52462762585a3",
       "integrity": "sha256-4cd126a7…",
-      "capabilities": ["acme-deploy", "acme-lint"]
+      "capabilities": ["acme-deploy", "acme-lint"],
+      "souls": [{ "name": "release-reviewer", "path": "souls/release-reviewer", "digest": "sha256-9a0f…" }]
     }
   }
 }
@@ -187,6 +190,7 @@ same workspace commit hold identical locks.
 | `commit` | full 40-hex OID the version resolved to |
 | `integrity` | `sha256-<hex>` content digest of the package tree at `path` |
 | `capabilities` | the capability names the package provides (sorted) — what `from: package` looks up |
+| `souls` | the package souls (0.28.0), sorted by name: `name`, `path` (inside the package) and `digest` (`sha256-<hex>` of the soul directory); absent when the package ships none |
 
 A capability provided by **two** locked packages is ambiguous and fails
 closed (`E_PACKAGE_MISSING { ambiguous: [ids] }`): keep one of them in
@@ -220,6 +224,66 @@ against what the fetch reported; skills are copied to
 `packages:` and syncing affects **only new spawns**; `oats status` shows a
 running instance's package module as `moved` once the lock points elsewhere.
 
+## Package souls
+
+A package may ship **souls** as well as capabilities (0.28.0). One pin in
+`packages:` then versions both: nothing drifts, unlike an `external:` soul's
+commit pin.
+
+```
+oats-package/
+├── oats-package.json      # { …, "capabilities": ["capabilities/acme-review"], "souls": ["souls/release-reviewer"] }
+├── capabilities/acme-review/oats.json
+└── souls/release-reviewer/
+    ├── soul.yaml          # an ordinary soul: name = the directory's name
+    ├── AGENTS.md
+    └── skills/…
+```
+
+- **Locked.** `oats sync` records each soul's `name`, `path` and `digest` in
+  the lock entry. A soul without `soul.yaml` or `AGENTS.md`, or whose
+  directory is not a soul name, is `E_PACKAGE_MANIFEST`. On a later sync at
+  the same version the souls must still match (`E_PACKAGE_INTEGRITY { why:
+  "souls" }`); a lock written before 0.28.0 has its `souls` filled in.
+- **Listed.** `oats souls` lists a package soul with `kind: "package"`,
+  `package`, `version`, `qualifiedName` and `origin: "package <id>
+  v<version>"`; `oats sync` / `oats workspace status` list each package's
+  `souls`. Only packages the workspace still declares are listed.
+- **Named.** The qualified name is `<package>/<soul>` (`oats.okf/knowledge-maintainer`).
+  A bare name works when it is unique across member, external and package
+  souls; otherwise `E_SOUL_AMBIGUOUS` names each qualified form
+  (`details.qualified`). A member soul's qualified form is `<member name>/<soul>`.
+- **Resolved** like any soul: the workspace and team defaults apply, `off` and
+  `<slot>: none` work, every `team:` label must be declared (`E_TEAM_UNKNOWN`
+  in discovery), and `from: here` means **this package** at the locked commit
+  (a capability it does not provide is `E_CAPABILITY_MISSING`).
+- **Spawned** at the locked commit: the soul is fetched into the per-commit
+  soul cache and its digest must equal the lock's (`E_PACKAGE_INTEGRITY
+  { why: "soul-digest" }`). A package soul homes in its own agent directory,
+  `agents/<package>--<soul>/` (the package id with `.` as `-`:
+  `agents/oats-okf--knowledge-maintainer/`), which is also its agent name
+  (`OATS_AGENT`, the `oats status` row); its instances are named from it
+  (`oats-okf-knowledge-maintainer-<purpose>`). A soul name never holds `--`,
+  so a member soul of the same bare name keeps its own `agents/<soul>/`.
+  Two packages whose ids sanitise alike (`a.b`, `a-b`) and that ship a
+  same-named soul would share a directory: both are listed with an
+  `E_SOUL_AMBIGUOUS` problem, and spawning either is `E_SOUL_AMBIGUOUS
+  { agentDir, qualified }` — keep one of the packages.
+  `instance.json.workspace.soul` records `name`, `qualifiedName`, `package:
+  { id, version, commit, digest, path }` and the soul id `package:<id>#<soul>`;
+  in `oats status` the soul is `moved` once the package pin moves.
+- **Disabled** by `oats-local.yaml` `souls.disabled` by its qualified or bare
+  name (`E_SOUL_DISABLED` at spawn).
+- **Trusted** as the package's capabilities are: declaring the package is the
+  trust decision.
+
+## Trigger templates
+
+A package may also ship **trigger templates** (0.28.0): `triggers: [{ id,
+file }]` in `oats-package.json`, each file `{ parameters, definition }`.
+`oats trigger add --from <package>:<id> --set <name>=<value>` instantiates one
+at the locked commit; see [schedules.md#triggers](schedules.md#triggers).
+
 ## Compatibility floors
 
 A soul may state floors on package versions — constraints, not sources:

package/docs/release-notes/v0.28.0.md

@@ -0,0 +1,144 @@
+# OATS 0.28.0
+
+Package souls, triggers, okf 3.0.0 remote knowledge consult, and the Workspace v4 Desktop.
+
+## Added
+
+- **Package souls** (feature `package-souls`). A package may ship souls as
+  well as capabilities: `souls: ["souls/<name>", …]` in
+  `oats-package/oats-package.json`, each an ordinary soul directory
+  (`soul.yaml`, `AGENTS.md`, `skills/`). One pin in the workspace's
+  `packages:` versions both, so a package soul never drifts the way an
+  `external:` commit pin can. See [packages.md](../packages.md#package-souls).
+  - `oats sync` locks each soul's `name`, `path` and `digest` in the package's
+    lock entry and checks them again on the next sync
+    (`E_PACKAGE_INTEGRITY { why: "souls" }`). A soul without `soul.yaml` or
+    `AGENTS.md` is `E_PACKAGE_MANIFEST`. A lock written by an earlier kernel
+    has its `souls` filled in on the next sync.
+  - `oats souls` lists them with `kind: "package"`, `package`, `version` and
+    `qualifiedName`; `oats sync` and `oats workspace status` list each
+    package's `souls`.
+  - Spawn one by its qualified name `<package>/<soul>`
+    (`oats spawn oats.okf/knowledge-maintainer`), or by its bare name when that
+    is unique. A bare name shared by several souls is `E_SOUL_AMBIGUOUS`, which
+    now names each qualified form (`details.qualified`); a member soul's is
+    `<member name>/<soul>`.
+  - A package soul resolves like any soul: workspace and team defaults apply,
+    `off` and `<slot>: none` work, its `team:` labels must be declared, and
+    `from: here` means its own package at the locked commit.
+  - The spawn fetches the soul at the locked commit and verifies it against the
+    lock's digest (`E_PACKAGE_INTEGRITY { why: "soul-digest" }`). It homes in
+    its own agent directory `agents/<package>--<soul>/`
+    (`agents/oats-okf--knowledge-maintainer/`), its agent name in `oats status`
+    and `OATS_AGENT`, so a member soul of the same bare name never shares its
+    directory or roster row. `instance.json.workspace.soul` records `name`,
+    `qualifiedName` and `package: { id, version, commit, digest, path }`, and
+    the soul id is `package:<id>#<soul>`. `oats status` shows the soul as
+    `moved` once the package pin moves. Two packages whose ids differ only by
+    `.` and `-` (`a.b`, `a-b`) and that ship a same-named soul would share an
+    agent directory: that is an `E_SOUL_AMBIGUOUS` problem in `oats sync` and
+    `oats souls`, and neither spawns.
+
+- **Triggers** (feature `triggers`): event-driven spawns. A trigger says
+  "when a GitHub pull request event matches, spawn a new instance of this soul
+  with this task, in these teams". It is stored beside the schedules
+  (`kind: "trigger"` in `oats-schedules.json`) and evaluated by the same host
+  tick; there is no daemon or webhook. See
+  [schedules.md#triggers](../schedules.md#triggers).
+  - The source `github.pull_request` is polled with the host's `gh` at the
+    trigger's `poll` interval (at least 1m). Events: `opened`, `reopened`,
+    `ready_for_review`, `labeled`, `synchronize`, filtered by `labels` and
+    `base`.
+  - Each event fires once: its key is recorded only after a successful spawn,
+    so a failed spawn is retried on the next poll. Delivery is at least once: a
+    tick that dies between the spawn and recording its key spawns the event
+    again (held while the first instance is live, under the default `perKey: 1`). `concurrency.max` and
+    `perKey` bound the live instances of the trigger and of one PR.
+  - The purpose and task are templated from `{repo} {number} {url} {event}
+    {headSha} {trigger}` only; a PR's title and body never reach the task.
+    `spawn.teams` becomes the messaging capability's `join=`. The instance gets
+    the event as `OATS_TRIGGER_EVENT_FILE` (`<home>/.oats/trigger-event.json`)
+    and records `instance.json.trigger`.
+  - `oats trigger add (--file | --from <package>:<template> --set …) | list |
+    show | enable | disable | remove | test | status`, all with `--json`.
+    `oats trigger test` checks gh auth and where its credential comes from
+    (warning when the host timer cannot reach it, such as a shell-only
+    `GH_TOKEN`), the repository and your push/maintain/admin permissions on it,
+    the soul, the teams, and what would fire now, and spawns nothing.
+    `oats schedule list` counts the triggers it does not list.
+  - A package may ship trigger templates (`triggers: [{ id, file }]` in
+    `oats-package.json`).
+  - `oats spawn --trigger-event <file>` is how a trigger hands the event to the
+    spawn.
+
+## Fixed
+
+- **`--flag=value` is read.** Every kernel command ignored the inline form
+  silently: `oats spawn dev --harness=claude` spawned the default harness,
+  and `--name=x`, `--runtime=x`, `--dir=x` and `--server=x` were dropped the
+  same way. A kernel command now reads `--flag=value` exactly as
+  `--flag value`, with the same validation. The value is everything after the
+  first `=`. Two inline forms are refused with `E_BAD_ARGS`: an empty
+  `--flag=`, and a value on a switch. `--yolo=false` is refused and never
+  turns yolo on. A capability command's own flags are its provider's: they
+  are forwarded exactly as typed, and the kernel reads only its dispatch flag
+  (`--soul`) in either form. `oats capture`, `recall` and `setup` parse their
+  own arguments, as before. See
+  [desktop-cli-api.md § Flags](../desktop-cli-api.md#flags).
+  **On an older kernel:** use the spaced form.
+
+- **`oats-local.yaml` `souls.disabled` is enforced at spawn.** It was documented
+  as "not run on this machine", but only counted souls in the `oats sync`
+  report. A listed soul is now refused with `E_SOUL_DISABLED { name,
+  qualifiedName, entry }`. An entry is a bare name (every soul of that name) or
+  a qualified name (`oats.okf/knowledge-harvester`, `<member>/<soul>`).
+
+## oats.okf 3.0.0 (catalog pin and bundled mirror)
+
+The official catalog now pins `oats.okf` to `v3.0.0` (tag object `ad2349c7`,
+commit `76f7ccdb`). The copy bundled in this package is its byte mirror. The
+package declares `oats >=0.26.0`.
+
+- **Knowledge is consulted remotely.** An instance reads its soul's knowledge
+  at the accepted state through new commands: `oats okf bases`, `index`,
+  `cat --base <alias> <path>`, `ls`, `links` and `search`. A Git base is served
+  from one host-wide partial clone per base, and a read refetches the accepted
+  branch once the cached commit is older than the `consult-max-age` setting
+  (seconds; default 300; `0` refetches on every read). `--fresh` always
+  refetches. If the fetch fails, the read is served from the cache, with
+  `stale: true` and the reason in its receipt.
+  A directory base is read in place. The new `okf-consultation` skill and the
+  okf injection teach instances to run `oats okf index` at the start of every
+  task.
+- **BREAKING: no `./knowledge/` in homes.** A spawn records the accepted
+  resolution and materializes no `./knowledge/` directory or view. Anything
+  that read `<home>/knowledge/bases/<alias>/…` reads
+  `oats okf cat --base <alias> <path>` instead.
+- **BREAKING: `oats okf refresh` is `E_REMOVED`.** There are no per-instance
+  views to refresh.
+- **`oats okf read --path` still works** in 3.0.0, as an alias of `cat`.
+- **Older homes:** a `./knowledge/` a 2.x spawn left in a home is not touched.
+  3.0.0 ignores it, and `oats okf inspect` reports it as
+  `legacy-local-view`.
+- The memory-harvest worker soul no longer ships a `CLAUDE.md -> AGENTS.md`
+  symlink (npm drops symlinks, and the kernel composes each home's
+  `CLAUDE.md`). The mirror check (`scripts/check-okf-mirror.mjs`) no longer
+  requires one; any symlink a future release ships is mirrored and verified
+  as before.
+
+## Desktop
+
+- **Workspace v4 redesign** (#206): the Workspace area (Setup, Souls, Capabilities, the soul and capability pages) is rebuilt to the Workspace v4 design. Facts the kernel does not report yet are left out rather than guessed; the Setup screen no longer names kernel files.
+- **Soul team labels** reach the Souls grid (#208).
+
+## Tests and CI
+
+- A home's resolved view (`resolvedFromHome`) carrying the slot rows its
+  spawn recorded (`layers`, since 0.26.0 layers-from) is now pinned. Before,
+  no test caught reverting it to `{}`.
+- CI runs the suite in six parallel shards (`node --test --test-shard`), plus a gate job with the old check name. Main runs no longer cancel each other.
+
+## Upgrading
+
+- **okf 3.0.0 is breaking for anything that read `<home>/knowledge/`.** Use `oats okf cat`. Existing homes keep their old view, unused.
+- **Package souls and triggers are additive.** Nothing changes until a package declares `souls:`/`triggers:`, or you add a trigger.

package/docs/schedules.md

@@ -10,7 +10,7 @@ is `E_LOCAL_MISSING`. Scheduled spawns materialize exactly like `oats spawn`.
 Execution belongs to the host that holds the scope, so a schedule on a
 registered server keeps running while your laptop sleeps.
 
-There is no daemon. One host timer (a launchd user agent on macOS, a systemd
+[Triggers](#triggers) are evaluated by the same tick. There is no daemon. One host timer (a launchd user agent on macOS, a systemd
 user timer on Linux) runs `oats schedule tick --host` once a minute; the tick
 is a short-lived process that evaluates only the current minute, launches
 what is due through the same `spawn`, `session start` and `session input`
@@ -89,6 +89,104 @@ required IANA zone; both are evaluated by the croner library. `--wake-every
 N` at spawn time means `*/N * * * *`: every 7 fires at :00, :07, ... :56 and
 then :00 again, so 1, 5, 10, 15 and 30 give an even cadence.
 
+## Triggers
+
+A **trigger** (OATS 0.28.0, feature `triggers`) is an event-driven schedule:
+"when EVENT matches, spawn a NEW instance of SOUL with TASK, in TEAMS". It is
+stored in the same `oats-schedules.json` as a job of `kind: "trigger"`,
+managed with `oats trigger …` (never `oats schedule …`, which neither lists nor
+edits one), and evaluated by the same host tick (`oats schedule tick --host`,
+and `oats schedule tick` for one scope). There is no daemon and no webhook: it
+runs only on the host that holds the scope, with **that host's own
+credentials**; a definition carries none.
+
+**Credentials reach the tick through the host timer, not your shell.** The
+timer (a user LaunchAgent on macOS, a `systemd --user` unit on Linux) runs the
+tick with its own environment, which sets only `PATH` and `OATS_HOME_DIR`. `gh`
+logged in with the keyring or its config file under your HOME works there. A
+`GH_TOKEN` or `GITHUB_TOKEN` exported in your shell does not reach it.
+`oats trigger test` reports where `gh`'s credential comes from (`gh.credentialSource`:
+`keyring`, `config`, `env:<VAR>`) and warns when the timer cannot reach it.
+
+```json
+{ "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": "Review knowledge-base PR {repo}#{number}. Load knowledge-review first.",
+             "teams": ["okf"], "harness": "claude", "model": "opus" },
+  "concurrency": { "max": 2, "perKey": 1 } }
+```
+
+- **Source** `github.pull_request` (the only one in v1): the tick polls the
+  repository's open pull requests with the host's `gh` (`gh api repos/<owner>/<repo>/pulls`,
+  `state=open`, most recently updated first) every `poll` (default `2m`, at
+  least `1m`). `labels` (all must be present) and `base` filter them. A repo is
+  `github.com/<owner>/<repo>`; another host is passed to `gh` as `--hostname`.
+- **Events** are inferred poll over poll: `opened` (a PR first seen, not a
+  draft; the first poll sees every open PR), `reopened` (seen closed, open
+  again), `ready_for_review` (was a draft), `labeled` (now carries the filter
+  labels it lacked; without a filter, any new label), `synchronize` (a new
+  head commit).
+- **Dedup and retry.** Each event has a key
+  `<trigger>:<repo>#<number>:<event>:<stamp>` (`created_at` for `opened`, the
+  head SHA for `synchronize`, `updated_at` otherwise). A key is recorded as
+  fired **only after a successful spawn**; until then the event stays pending
+  and is retried at every poll, and dropped when its PR closes.
+- **At least once, not exactly once.** The fired key is written after the
+  spawn returns. If the tick dies in between (a crash, a kill, the host going
+  down), the spawned instance exists but the key does not, and the next poll
+  spawns the event again. Concurrency still applies to that retry: with the
+  default `perKey: 1` the first instance is live, so the event is `held` rather
+  than spawned twice, and it fires once that instance retires. A trigger's soul
+  should therefore tolerate a second run on the same PR event (a review that
+  finds its own earlier review, for example).
+- **Concurrency.** `max` (default 1) bounds the live instances of the trigger,
+  `perKey` (default 1) those of one PR; both are counted from the homes'
+  `instance.json.trigger` records, so a retired instance frees its slot. An
+  event over the bound stays pending (`held`).
+- **The spawn** is `oats spawn` (the same path as a scheduled spawn). `soul` is
+  bare or qualified (`<package>/<soul>`). `purpose` (default
+  `{trigger}-{number}`, must render to a slug) and `task` are templated from
+  **only** `{repo} {number} {url} {event} {headSha} {trigger}`: a pull
+  request's title and body are untrusted and never reach the task (a template
+  naming any other field is refused). `teams` becomes the messaging
+  capability's `join=` setting (as `--provider <messaging cap> join=<labels>`).
+  `harness`, `model`, `yolo`, `backend` are as for schedules.
+- **The event reaches the instance** as `OATS_TRIGGER_EVENT_FILE`
+  (`<home>/.oats/trigger-event.json`: `{ trigger, source, repo, number, url,
+  event, headSha, labels, observedAt, key }`), given to the spawn hooks and the
+  harness; `instance.json.trigger` records `{ id, key, source, repo, number,
+  url, event, headSha, observedAt, eventFile }`. The task ends with a short
+  block naming the event file.
+- **State** lives in `<scope>/.agents/schedules/triggers.json` (last poll, the
+  PRs seen, pending events, fired keys, the last error).
+
+```sh
+oats trigger add --file trigger.json                 # or:
+oats trigger add --from oats.okf:harvest-review --set repo=github.com/acme/knowledge [--id <id>]
+oats trigger list | show <id> | enable <id> | disable <id> | remove <id>
+oats trigger test <id>      # dry run: gh auth + credential source, repo + permissions (push/maintain/admin), the soul resolves,
+                            # its messaging capability, the teams declared, what WOULD fire now; spawns nothing
+oats trigger status [<id>]  # last poll, pending, fired keys, live instances, last error
+```
+
+All take `--dir` and `--json` (`triggerApi: 1`). `remove` leaves the instances
+it spawned running. `oats schedule list` does not list triggers, but it counts
+them (`triggers: { count, command: "oats trigger list" }`, and a line in text
+mode). Errors: `E_TRIGGER_INVALID { field }`, `E_TRIGGER_EXISTS`,
+`E_TRIGGER_UNKNOWN`, `E_BAD_ARGS`.
+
+**Package trigger templates.** A package may declare `triggers: [{ id, file }]`
+in `oats-package.json`. Each file is `{ parameters: { <name>: { path,
+required?, default?, description? } }, definition: { …a trigger… } }`.
+`oats trigger add --from <package>:<id>` reads it at the locked commit;
+`--set <name>=<value>` fills a parameter at its dotted `path` (a list value is
+comma-separated); a required parameter without a value is `E_BAD_ARGS
+{ missing }` naming it. The trigger records `template: { package, version,
+commit, template }`.
+
 ## Captured definitions (removed in 0.26)
 
 0.24–0.25 could save captured command definitions: `definitionVersion`,

package/docs/souls-and-instances.md

@@ -196,9 +196,13 @@ refused (`E_INSTANCE_NAME_TAKEN`).
 
 From a deployment (where `oats-local.yaml` is), a spawn: reads the local file →
 discovers the workspace over its remotes and confirms membership → finds the
-soul among the confirmed members (or `external:`; an ambiguous bare name is
-`E_SOUL_AMBIGUOUS` — say `<repo>/<soul>`) → fetches the soul's source into
-`<agents-root>/<soul>/souls/<commit12>/` at its commit (the home links that
+soul among the confirmed members, `external:` souls and the locked packages'
+souls (an ambiguous bare name is `E_SOUL_AMBIGUOUS`, naming each qualified
+form: `<member>/<soul>` or `<package>/<soul>`; a soul listed in
+`oats-local.yaml` `souls.disabled` is `E_SOUL_DISABLED`) → fetches the soul's
+source into `<agents-root>/<soul>/souls/<commit12>/` at its commit (a package
+soul at the locked commit, verified against the lock's digest — see
+[package souls](packages.md#package-souls); the home links that
 directory; `<agents-root>/<soul>/soul` points at the current one) → resolves
 every capability by
 `from:` (member = latest, package = locked) → creates the home →

package/docs/workspaces.md

@@ -60,7 +60,7 @@ members:                                   # repo refs, NO @revision (E_WORKSPAC
 
 packages:                                  # the ONLY versioned things
   oats.framework: v1.1.3                   # bare version → resolves through the official catalog
-  oats.okf: v2.1.5
+  oats.okf: v3.0.0
   acme.tools: git:github.com/acme/tools@v0.4.0   # outside the catalog → git:<repo>@<tag|OID>; still a package
 
 teams:                                     # labels, declared once so they cannot drift
@@ -168,7 +168,7 @@ settings:                                  # host-owned values the manifests ask
     bindings-file: /Users/ana/.oats/okf-bindings.json
     state-dir: /Users/ana/.oats/okf
 souls:
-  disabled: [data-analyst]                 # not run on this machine
+  disabled: [data-analyst]                 # not run on this machine (E_SOUL_DISABLED); oats.okf/knowledge-harvester names a package soul
 ```
 
 See [configuration.md](configuration.md). `oats-config.yaml` no longer exists.
@@ -230,6 +230,12 @@ read; the soul gets no member-tier capabilities of its own repo; it is
 "source-complete" (its skills travel with it) and the workspace's defaults fill
 its slots. An `external[].team` overrides the soul's own `team`.
 
+**Package souls.** A package may ship souls (`souls:` in `oats-package.json`,
+0.28.0): they are listed from the lock for each package the workspace declares,
+named `<package>/<soul>` (a bare name when unique), resolved like any soul
+(`from: here` = their own package at the locked commit) and trusted as the
+package is. See [packages](packages.md#package-souls).
+
 ## Member tier vs package tier — the non-collapse rule
 
 A repository may be a **member** (it completed the handshake; its `souls/*` and