@awebai/oats 0.27.2 → 0.29.0

package/docs/oats-local.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://oats.dev/schemas/local-v2.json",
   "title": "Deployment-local overrides v2 (oats-local.yaml)",
-  "description": "The operator's side of a workspace: which workspace this machine realizes, where member clones live when not at the taught convention, host-owned capability settings (absolute paths belong HERE, never in the workspace file), souls disabled on this machine, and the named launch configurations this host offers. Never shared through Git.",
+  "description": "The operator's side of a workspace: which workspace this machine realizes, where member clones live when not at the taught convention, host-owned capability settings (absolute paths belong HERE, never in the workspace file), souls disabled on this machine, this host's name and the workspace triggers and schedules it does not run, and the named launch configurations this host offers. Never shared through Git.",
   "type": "object",
   "required": ["schemaVersion", "workspace"],
   "additionalProperties": false,
@@ -64,14 +64,45 @@
         }
       }
     },
+    "host": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["name"],
+      "properties": {
+        "name": { "type": "string", "pattern": "^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$", "description": "This machine's name (0.29.0). A workspace trigger or schedule runs on the host whose name is its `runsOn` (and only when this host's gh account is its `owner`). A machine fact, never in Git." }
+      }
+    },
+    "triggers": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "disabled": {
+          "description": "Workspace triggers this host does not run, by qualified id <member>/<id>, without a commit (`oats trigger disable <member>/<id>` writes it). Local triggers are enabled and disabled in oats-schedules.json.",
+          "type": "array", "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[a-z0-9-]{1,40}$" }
+        }
+      }
+    },
+    "schedules": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "disabled": {
+          "description": "Workspace schedules this host does not run, by qualified id <member>/<id>, without a commit (`oats schedule disable <member>/<id>` writes it). Local schedules are enabled and disabled in oats-schedules.json.",
+          "type": "array", "uniqueItems": true,
+          "items": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]*/[a-z0-9-]{1,40}$" }
+        }
+      }
+    },
     "souls": {
       "type": "object",
       "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/official-catalog.md

@@ -65,13 +65,16 @@ this policy does not invent new catalog or manifest fields.
 
 ## Listed first set
 
-- Listed capabilities: `oats.okf`, `oats.aweb`, `oats.authoring`, `oats.jira`,
-  `oats.linear`, `oats.dev`, `oats.knowledge-theory`, `oats.core` and `oats.setup`.
-- **`oats.framework` 1.1.3** is listed at tag `oats-framework/v1.1.3` in
+- Listed capabilities: `oats.okf`, `oats.okf-harvest`, `oats.okf-maintenance`,
+  `oats.aweb`, `oats.authoring`, `oats.jira`, `oats.linear`, `oats.dev`,
+  `oats.knowledge-theory`, `oats.core` and `oats.setup`. `oats.okf-harvest` and
+  `oats.okf-maintenance` select the `oats.okf` package (4.0.0).
+- **`oats.framework` 1.3.0** is listed at tag `oats-framework/v1.3.0` in
   `awebai/oats`, payload root `oats-package`. The `oats.core`, `oats.setup` and
   `oats.knowledge-theory` aliases select that distribution; package identity is
   distinct from capability identity. Core supplies operation/soul guidance;
-  setup supplies OATS Soul Setup, configuration and package guidance.
+  setup supplies OATS Soul Setup, configuration and package guidance. The
+  package also ships the `knowledge-theory-expert` package soul.
 
 These entries are in the current repository catalog. An older installed CLI keeps
 its bundled catalog; publication here does not update that installation or rewrite

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
@@ -72,8 +74,8 @@ members:
   - git:github.com/acme/agents
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.1.3
-  oats.okf: v2.1.5
+  oats.framework: v1.3.0
+  oats.okf: v4.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,72 @@ 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>`). That prefix counts toward the
+  64-character instance-name limit, so a package soul's purposes are short:
+  `oats-okf-knowledge-maintainer-` is 30 characters, which leaves 34 for the
+  purpose (fewer when a `-2` suffix de-duplicates it). A longer one is
+  `E_INSTANCE_NAME_INVALID { prefix, purpose, maxPurpose }`, naming the budget;
+  a trigger's or schedule's purpose template obeys the same limit when it
+  renders. 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:
@@ -274,8 +344,8 @@ A soul that names one of the package's capabilities with
 }
 ```
 
-`ref` carries the tag convention: a workspace's `oats.framework: v1.2.0`
-resolves to tag `oats-framework/v1.2.0`. Resolving through the catalog never
+`ref` carries the tag convention: a workspace's `oats.framework: v1.3.0`
+resolves to tag `oats-framework/v1.3.0`. Resolving through the catalog never
 advances a lock by itself — `oats sync` does, and
 says so.
 

package/docs/release-lane.md

@@ -30,7 +30,7 @@ under `stage/<tag>/logs/`; a failing step exits non-zero with the log path.
 
 | Phase | Mirrors in `release.yml` | Writes |
 | --- | --- | --- |
-| `build --tag vX.Y.Z [--sha <commit>]` | job `build-and-test`: notes gate, three-manifest bump, `node --check`, `npm ci`, `npm run check`, Desktop test deps, `npm test`, `pack:check` and the tarball greps, `smoke:tarball`, the `version --json` probe | `npm/*.tgz`, `MANIFEST.json` |
+| `build --tag vX.Y.Z [--sha <commit>]` | jobs `build-and-test` and `tests` (the lane runs the suite unsharded): notes gate, three-manifest bump, `node --check`, `npm ci`, `npm run check`, Desktop test deps, `npm test`, `pack:check` and the tarball greps, `smoke:tarball`, the `version --json` probe | `npm/*.tgz`, `MANIFEST.json` |
 | `desktop --tag vX.Y.Z --arch arm64\|x64` | one `desktop-build` matrix leg: desktop `npm ci`, `npm test`, `npm run dist -- --<arch>`, strict deep `codesign --verify` (macOS), `dist:smoke` in build-verify mode | `assets/oats-desktop-*` |
 | `stage --tag vX.Y.Z` | publish job, "Checksums" (`shasum -a 256`) | `assets/SHA256SUMS.txt` |
 | `publish-npm --tag vX.Y.Z [--dry-run] --yes` | publish job, the two guarded `npm publish --access public` steps, kernel then adapter | — |

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/release-notes/v0.29.0.md

@@ -0,0 +1,240 @@
+# OATS 0.29.0
+
+## Added
+
+- **Workspace triggers and schedules** (feature `automations`). A trigger or a
+  schedule can now be declared in Git, in any confirmed member, and shared with the
+  team. It is named `<member>/<id>`, and a machine's own ones are named
+  `local/<id>`. See
+  [schedules.md#workspace-triggers-and-schedules](../schedules.md#workspace-triggers-and-schedules).
+  - Triggers and schedules stay separate:
+
+    | | triggers | schedules |
+    | --- | --- | --- |
+    | folder | `oats-triggers/` | `oats-schedules/` |
+    | file name anywhere in the member | `*.oats-trigger.yaml` | `*.oats-schedule.yaml` |
+    | `kind:` | `oats-trigger` | `oats-schedule` |
+    | commands and list | `oats trigger …` | `oats schedule …` |
+    | opt-out | `triggers.disabled` | `schedules.disabled` |
+
+    `oats-package/`, `.git/` and `node_modules/` are never scanned.
+  - Every file carries `kind`, `schemaVersion: 1`, `runsOn` (the host that runs it)
+    and `owner` (the GitHub account it acts as). The wrong kind is
+    `E_AUTOMATION_SCHEMA`, and a duplicate id is `E_AUTOMATION_DUPLICATE`.
+  - A host runs one only when `runsOn` is its new `oats-local.yaml` `host.name`
+    **and** its `gh` is logged in as `owner`. Otherwise the item is listed as
+    `assigned-elsewhere`, `owner-mismatch` or `host-unnamed`.
+  - `oats trigger disable <member>/<id>` and `oats schedule disable <member>/<id>`
+    stop it on this host without a commit, by writing `triggers.disabled` or
+    `schedules.disabled` in `oats-local.yaml`.
+  - `oats sync` takes a snapshot of them. The host tick reads the snapshot and
+    refreshes it every ten minutes (`oats automations refresh`).
+  - `oats trigger add … --workspace <member> --runs-on <host> --owner <host>/<login>`
+    writes the file in a checkout of the member, or prints it. `oats schedule add`
+    takes the same options.
+  - `oats trigger list --json` and `oats schedule list --json` answer the Desktop's
+    rows for both levels: the owner, where it runs and why (not), the soul and
+    where it comes from, the task verbatim, the event or cron, and the last and
+    next run. Local schedule rows keep their bare `id` and add `qualifiedId`. See
+    [desktop-cli-api.md](../desktop-cli-api.md).
+  - Each row's `origin` carries `url` (the file on GitHub at its commit) and
+    `localPath` (the file in this machine's clone of the member), each `null` when
+    there is none. Both lists carry `host.ghUser` (who `gh` is logged in as, per
+    GitHub host) and the host `scheduler`. "When it next runs" is `nextDue`
+    everywhere.
+- **Desktop facts** (feature `desktop-facts`): kernel facts the Desktop's Workspace
+  view shows, so it never derives them. Every field is an addition. See
+  [desktop-cli-api.md](../desktop-cli-api.md#desktop-facts-feature-desktop-facts-oats-0290).
+  - `oats inspect --soul --json`: each capability's `composedFrom` (`workspace`,
+    `team:<label>` or `soul`), and `capabilitiesOff[]`, the defaults the soul
+    turned off (`<id>: off` or `<slot>: none`).
+  - `oats souls --json` rows: the default `harness`/`model` a spawn starts with,
+    and `spawnable` and `problem`, the refusal a spawn would meet (it spawns
+    nothing). Also `file`.
+  - `oats capabilities --json` rows: `layer` on package rows too, `description`,
+    `skills`/`commands`/`hooks` by name, `file`, and a member capability's `tree`
+    (its Git tree id).
+  - `oats workspace status --json`:
+    - the workspace and team `defaults` as rows;
+    - this computer's member `clones` and the rule that found each;
+    - `disabledSouls`;
+    - `lock` (`path`, `lockfileVersion`);
+    - `packages[].latest` when the shipped catalog has a newer version;
+    - file locations (`workspace.file`, `members[].url`,
+      `members[].membershipFile`).
+  - `oats status --json` instance rows: `startedAt` (the last start or restart),
+    `modelFrom` (also recorded in `instance.json`) and `identityAddress`. A member
+    module's drift `current` gains `version`.
+  - URLs are GitHub pages at the row's commit, `null` for any other host.
+  - `oats help` lists `spawn --provider`.
+- **`oats schedule test <id>`**: where a schedule runs, whether its soul resolves
+  (a spawn preview) and when it is next due. It spawns nothing, like
+  `oats trigger test`.
+- **`launchConfig`** on a trigger's `spawn` and on a spawn schedule: the soul starts
+  on that launch configuration of the running host (`oats-local.yaml`
+  `launch-configs`). A package trigger template can expose it as a parameter.
+- `oats trigger status --json` rows add `nextDue`, `concurrency` and `liveCount`;
+  `oats trigger test --json` `wouldFire` items add `repo`.
+- **`OATS_SETTINGS_ORIGINS`** beside `OATS_SETTINGS`, for every hook and
+  capability command (and readiness probes): where each leaf of the payload came
+  from, a JSON pointer → `{ kind, at }` (`manifest-default`, `workspace`, `soul`,
+  `host`, `spawn`). A provider can tell a soul-set value from a host-set one
+  without reading `soul.yaml`. `instance.json` records it with the settings
+  (`capabilities[].settingsOrigins`, `capabilityRuntime[].settingsOrigins`).
+
+## Changed
+
+- **oats.framework 1.3.0 pinned.** The official catalog pins `oats.framework` to
+  `oats-framework/v1.3.0` (this repository's workspace pins it too). 0.28.1 was never
+  released, so this pin covers three framework releases:
+  - **1.2.0:** the setup-admin skills. oats.setup 2.1.0 adds `oats-setup-model`,
+    `oats-workspace-config`, `oats-teams`, `oats-automations` and a setup inject,
+    and oats.core 2.1.0 is current for an instance's view. The `oats-setup-admin`
+    soul uses them.
+  - **1.2.1:** OKF knowledge operations in onboarding (oats.setup 2.1.1,
+    `oats-onboarding`).
+  - **1.3.0:** `knowledge-theory-expert` is a package soul
+    (`oats spawn oats.framework/knowledge-theory-expert`), with
+    oats.knowledge-theory 1.1.0.
+
+  A workspace picks it up by pinning `oats.framework: v1.3.0` and running
+  `oats sync`.
+- **A local trigger's id is `local/<id>`** in `oats trigger` rows, in its dedup keys
+  and state, and in a triggered instance's `instance.json.trigger.id` and event
+  file. It was the bare id in 0.28.0. Every `oats trigger` verb still accepts the
+  bare id.
+
+## Removed
+
+- **BREAKING: capability-defined agents.** A capability manifest's `agents:` is
+  refused at resolution, with
+  `E_CAPABILITY_AGENTS_REMOVED { capability, agents, from }`. The remedy names the
+  replacement: a **package soul** (`souls/<name>/` in the package, spawned as
+  `oats spawn <package>/<name>`) or a **member soul**. `oats spawn <name>` no
+  longer falls back to an agent declared by a materialized or locked module; an
+  unknown name is `E_SOUL_UNKNOWN`. The manifest schema drops `agents`.
+  - A home an earlier kernel spawned for one (its agent directory holds only
+    `instances/`) is still listed by `oats status`, may be a `--parent`, and
+    retires. Nothing creates one any more.
+  - This repository's users moved:
+    - oats.okf 4.0.0's harvester is a package soul;
+    - the post-commit **`reviewer`** is an oats.dev **1.1.0** package soul
+      (`oats.dev/reviewer`, beside oats.review 1.3.0; the pin moves to
+      `v1.1.0`), and oats.review's inject spawns it unchanged, now named
+      `oats-dev-reviewer-<short-sha>`;
+    - **`knowledge-theory-expert`** is an oats.framework **1.3.0** package soul
+      (`oats spawn oats.framework/knowledge-theory-expert`), with
+      oats.knowledge-theory 1.1.0.
+  - A v2 soul.yaml declares no harness or model, so the reviewer's harness and
+    model now come from the **spawner's launch configuration** (its former pin was
+    pi, gpt-5.6-sol).
+
+## Fixed
+
+- A package soul's derived instance name is checked and de-duplicated as the name
+  the home gets (`acme-pkg-keeper-<purpose>`, not `acme-pkg--keeper-…`). A
+  purpose inside the limit is no longer refused, and a second spawn with the same
+  purpose is `…-2` instead of a collision. An over-long purpose is
+  `E_INSTANCE_NAME_INVALID` naming how many characters the purpose may have
+  (`details.maxPurpose`).
+
+- Concurrent spawns of the same instance: a spawn that loses the race now refuses
+  with `E_PLACEMENT_TAKEN` (it created nothing). It used to fail with an uncoded
+  "instance already exists" error, surfaced as `E_SPAWN_FAILED`.
+- Disabled-here messages name the per-kind key (`triggers.disabled`,
+  `schedules.disabled`).
+
+## Desktop
+
+- **Schedules and Triggers tabs** on the automations contract. Rows are grouped by
+  where they run: on this computer, needing attention here, or elsewhere. Workspace
+  and local items are listed together, with an origin chip, a filter and a search.
+  - Each row has an on-here switch, the soul and where it comes from, the cron in
+    words or the trigger's event, and where it runs and as whom. It also shows the
+    last and next run, and a menu (Open, Test, Run now, on/off here, Open file).
+  - A row opens a detail page: the prompt verbatim, the schedule or event, recent
+    runs, the kernel's placement verdict, where it comes from, and the test result.
+  - The old Schedules read path is gone.
+- **Why each capability is there.** The soul page and an instance's soul tab tag
+  each capability `workspace`, `team · <label>` or `soul`, and list the defaults the
+  soul turned off (including a slot it emptied), from the kernel's Desktop facts.
+- **A moved module names its versions**: "moved 2.1.5 → 2.2.0" in the instance
+  panel's module drift.
+- The Desktop accepts OATS CLIs `>=0.25.8 <0.30.0`.
+
+## Internal
+
+- The release workflow runs the test suite in six parallel shards, like PR CI, and
+  publication waits for every shard.
+
+## Upgrading from 0.28
+
+> **0.29.0 and oats.okf 4.0.0 move in lockstep.** On kernel 0.29.0, oats.okf ≤3.x
+> is refused because it declares a capability agent, and oats.okf 4.0.0 requires
+> kernel 0.29.0. A deployment on okf 3.x therefore **stays on kernel 0.28 until it
+> moves its pins**. It then upgrades in one sitting, in this order:
+
+1. **Upgrade the kernel**: the npm package, the pi adapter and the Desktop, all
+   0.29.0.
+2. **Move the pins** to the official catalog's: `oats.okf: v4.0.0`,
+   `oats.dev: v1.1.0`, `oats.framework: v1.3.0`.
+3. **Run `oats sync`.**
+
+Between step 1 and step 3, a package pinned below its 0.29 release still declares
+`agents:`. A spawn, preview or `inspect --soul` of any soul that composes it
+refuses with `E_CAPABILITY_AGENTS_REMOVED`:
+- **oats.okf ≤3.x** (`memory-harvest`): this is **every soul with oats.okf in its
+  knowledge slot**;
+- **oats.dev 1.0.x** (`reviewer`);
+- **oats.framework ≤1.2.x** (`knowledge-theory-expert`).
+
+Harvest is off by default in okf 4.0.0. Switch it on
+(`oats okf setup --harvest on`) where you want it.
+
+Homes spawned earlier keep loading their recorded modules. Homes spawned for a
+capability agent stay listed and retirable.
+
+## oats.okf 4.0.0 (catalog pin and bundled mirror)
+
+The official catalog now pins `oats.okf` to `v4.0.0` (tag object `239f2885`,
+commit `1f0ba12f`). The copy bundled in this package is its byte mirror.
+
+**BREAKING:**
+- The package requires `oats >=0.29.0`; an older kernel refuses it
+  (`E_CAPABILITY_INCOMPATIBLE`).
+- The `okf` and `memory-harvest` skills are gone from `oats.okf`.
+
+- **Three capabilities.** The package now exports:
+  - `oats.okf`: the knowledge slot;
+  - `oats.okf-harvest`: the harvester's completion and status commands;
+  - `oats.okf-maintenance`: the maintainer's review context.
+
+  The catalog maps `oats.okf-harvest` and `oats.okf-maintenance` to the
+  `oats.okf` package.
+- **Working souls get two skills and the inject.** A soul with `oats.okf` in
+  its knowledge slot gets `okf-consultation` and `okf-instance-knowledge`, and
+  the okf inject.
+- **The harvester is a package soul.** `oats okf run-source` (and `oats okf
+  harvest`) spawns `oats.okf/knowledge-harvester`. It is named
+  `okf-harvester-<run>` and homes under
+  `agents/oats-okf--knowledge-harvester/`. It is no longer the `memory-harvest`
+  capability agent. After a successful completion it stays alive in the `okf`
+  team until its PR is merged or closed. `oats.okf/knowledge-maintainer` is the
+  package's second soul.
+- **The harvest-review trigger.** The package ships the trigger template
+  `harvest-review` (`triggers/harvest-review.json`). It watches the labelled
+  harvest PRs.
+- **`harvest: on|off`** (default **off**). Harvest is a host switch in
+  `oats-local.yaml` `settings.oats.okf.harvest` (`oats okf setup --harvest
+  on|off`). Off means no source registration, capture or custody. A soul can
+  only opt out (`knowledge: { harvest: off }`).
+- **`oats okf read` is removed** (`E_REMOVED`). Use `oats okf cat --base
+  <alias> <path>`, which takes the same path and gives the same text and
+  receipt.
+
+The bundled mirror now covers the three capability directories
+(`capabilities/oats-okf`, `capabilities/oats-okf-harvest`,
+`capabilities/oats-okf-maintenance`). The package's souls and trigger are
+checked byte for byte in `scripts/okf-source-inventory.json` (schemaVersion 2).
+The npm package does not ship them, because the kernel reads a package's souls
+and triggers from Git at its locked commit.