@awebai/oats 0.28.0 → 0.29.0

package/docs/knowledge-capability-authoring.md

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

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

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

package/docs/knowledge.md

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

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,6 +64,36 @@
         }
       }
     },
+    "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,

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

@@ -74,8 +74,8 @@ members:
   - git:github.com/acme/agents
   - git:github.com/acme/platform
 packages:
-  oats.framework: v1.1.3
-  oats.okf: v3.0.0
+  oats.framework: v1.3.0
+  oats.okf: v4.0.0
   oats.aweb: v1.14.2
 teams:
   global: { description: Org-wide }
@@ -263,7 +263,13 @@ oats-package/
   `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 `--`,
+  (`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
@@ -338,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.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.