@awebai/oats 0.29.4 → 0.30.1

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

@@ -1,50 +1,43 @@
 # OATS v0.24.13 — schedule history API 3 and the Desktop schedules table
 
-Kernel/Pi/Desktop **0.24.13**. Tag `v0.24.13` → the commit carrying these
-notes; the version-bump commit lands after the tag. Consumers gate on
-`oats version --json` `features[]` names and API integers — never on the version.
-
-## Kernel — `schedule-read-2` (`scheduleHistoryApi: 3`; `scheduleApi` stays 2)
-
-`oats schedule list|show` history had four defects found by the Desktop
-engineer's exact-source review; each is closed under a new advertised name.
-
-- **A run's identity is when it was scheduled and started, never its outcome.**
-  `runId = sha256(scheduledFor|startedAt|attemptId)[0:24]`; a run's later facts
-  update its one row; `transitions[]` keeps the outcome sequence
-  (`["started","unknown","ended"]` is one run, not three); `settled`,
-  `recordedAt`. Pre-API-3 rows are returned `legacy: true` with `runId: null`
-  and are never merged.
-- **Bounded, descriptor-safe state.** Both scope files are `lstat`ed (regular
-  file only), opened `O_NOFOLLOW|O_NONBLOCK`, `fstat`-verified (dev+ino) and
-  read whole **only within a 1 MiB budget** — over budget is a typed
-  `E_SCHEDULE_STATE_OVERSIZE` refusal, never truncated JSON. `list` carries
-  `integrity.sources[]`; history is capped at 50 rows at read
-  (`history: {status, stored, truncated}`); one job's corrupt history or bad
-  identity is its own row and never fails the others.
-- **Subject truth.** `list`/`show` echo the resolved `scope` and canonical `id`;
-  a definition whose own `id` differs from its key → `E_SCHEDULE_IDENTITY`; ids
-  are validated before any read. Typed refusal details travel through the CLI's
-  JSON failure.
-- **Session provenance, never a transcript.** The `transcript` pointer named a
-  reader that does not exist and is gone. Every run carries
-  `session: {instance|null, home|null, incarnation|null, server|null, delivery}`
-  — what the recorder knew at write time. A read-only transcript verb is a
-  separate seam (K12), not implied by this API.
+Kernel/Pi/Desktop **0.24.13**. Consumers gate on `oats version --json`
+`features[]` names and API integers, never on the version. Shapes are in the
+[Desktop CLI API](../desktop-cli-api.md).
+
+## Kernel: `schedule-read-2` (`scheduleHistoryApi: 3`; `scheduleApi` stays 2)
+
+`oats schedule list|show` history had four defects; each is closed under a new
+advertised name.
+
+- **A run's identity is when it was scheduled and started, not its outcome.**
+  Each run has a stable `runId`; later facts update its one row and
+  `transitions[]` keeps the outcome sequence (`["started","unknown","ended"]`
+  is one run). Rows from before API 3 are returned with `legacy: true` and
+  `runId: null` and are never merged.
+- **Bounded, descriptor-safe state.** Both scope files must be regular files,
+  are opened without following symlinks, and are read only within a 1 MiB
+  budget; over budget is a typed `E_SCHEDULE_STATE_OVERSIZE` refusal. History
+  is capped at 50 rows (`history: {status, stored, truncated}`); one job's
+  corrupt history never fails the others.
+- **Subject truth.** `list` and `show` echo the resolved `scope` and canonical
+  `id`; a definition whose own `id` differs from its key refuses
+  `E_SCHEDULE_IDENTITY`.
+- **Session provenance, not a transcript.** The `transcript` pointer, which
+  named a reader that did not exist, is removed. Every run carries
+  `session: {instance, home, incarnation, server, delivery}` as known when it
+  was recorded.
 
 ## Desktop
 
-- **Schedules** view: the compact table (enabled, schedule, target, cadence,
+- **Schedules** view: a compact table (enabled, schedule, target, cadence,
   next run, last reported outcome, actions) with **Recent runs** for the
-  workspace (≤50), read once on entry and on explicit Refresh — no polling.
-  History enables nothing; `ended` is not success and `delivered` is not
-  consumption; missing time facts are shown as unreported. Session provenance
-  is displayed with a precise unavailable reason — no transcript, terminal or
-  link. Remote history and editing a captured wake are shown as honest
-  limitations. Gated on `scheduleHistoryApi === 3` and `schedule-read-2`.
-- **Security**: the command-running `GET /api/schedules` is removed (405, no
-  command, no default workspace); legacy POST `list|show` aliases run through
-  the same strict admission, budgets and two coalesced read slots.
+  workspace, read on entry and on Refresh, without polling. `ended` is not
+  shown as success and `delivered` not as consumption. Remote history and
+  editing a captured wake are not available. Requires `scheduleHistoryApi: 3`
+  and `schedule-read-2`.
+- **Security**: the command-running `GET /api/schedules` is removed (405);
+  legacy POST `list|show` aliases go through the same strict admission and
+  budgets.
 
 ## Upgrade
 

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

@@ -4,18 +4,14 @@ Kernel/Pi/Desktop **0.24.2**. Publication is not deployment: every operator stil
 
 ## What changed
 
-- **`oats onboard [--dir <deployment>] [--workspace <git:source[@rev]>] [--force-existing] [--json]`** — bootstrap a deployment with an **`oats-setup-expert`** soul that holds `oats.core` and `oats.setup`. Acquires the official `oats.framework` package through the existing engine (resources-only guard before commit, no catalog auto-trust), activates exactly those two capabilities for that soul, writes its definition with both pinned at the acquired immutable commit, and **prints** the spawn command — it never launches a model. Classic local bootstrap, not captured preparation. `oats setup` (record capture setup) is unchanged.
-- **Soul creation declares `oats.core` explicitly.** `oats create` and new local souls write `requires.capabilities.oats.core` resolved from the official catalog; `--no-oats-core` opts out; nothing is invented when the catalog has no entry. When a soul declares `oats.core` or `oats.setup`, the kernel composes **neither** the legacy kernel skills (`oats`, `oats-config`, `oats-packages`) nor the `kernel:oats` injection — the capability's skills are the operational curriculum. Souls without it keep legacy behavior; `oats doctor` prints an informational line.
-- **Official capabilities.** `oats.framework` **1.1.1** (tag `oats-framework/v1.1.1`) exports `oats.core` (`oats-operate`, `oats-souls`, "you run on OATS" briefing), `oats.setup` (`oats-config`, `oats-packages`, `oats-workspace-setup` — now documenting the operator request shape) and `oats.knowledge-theory`. Listed in the official catalog with capability aliases.
-- **Retained inspection projects `launchSelection`** (`{runtime, model}` or `null`) for the primary from the verified retained record; provider binding codecs receive the same-kernel `OATS_CLI_BIN` after the environment scrub. These are what a provider `check` needs to be truthful about the primary's profile.
-- **aweb 1.11.0 pairing.** The catalog and all framework soul editions pin `oats.aweb@v1.11.0`, which adds the portable binding interface (floor `>=0.24.2`). Its `check` qualifies HOME-route operational custody only: explicit private team, `delivery: session`, an input-capable Claude/Codex primary. A strict-Pi print primary reports `needs-configuration`; the requirement is never dropped.
-- **Six framework soul editions** exported and imported by `oats-workspace.yaml`: the five knowledge-owning experts (`oats-expert`, `oats-kernel-expert`, `oats-desktop-expert`, `market-research-expert`, `oats-assistant`) at `caa341f3` and `oats-setup-expert` at `0aad753c`. All six declare `oats.core` from the repository's own payload.
-- Baseline hygiene: golden fixtures use a genuinely empty catalog; the package check lazy-loads dev validators so syntax-only lanes work without `node_modules`.
+- **`oats onboard [--dir <deployment>] [--workspace <git:source[@rev]>] [--force-existing] [--json]`** bootstraps a deployment with an **`oats-setup-expert`** soul that holds `oats.core` and `oats.setup`. It acquires the official `oats.framework` package (no catalog auto-trust), activates exactly those two capabilities for that soul, pins both at the acquired commit, and **prints** the spawn command; it never launches a model. `oats setup` (record capture setup) is unchanged.
+- **Soul creation declares `oats.core` explicitly.** `oats create` writes `requires.capabilities.oats.core` resolved from the official catalog; `--no-oats-core` opts out. A soul that declares `oats.core` or `oats.setup` no longer receives the legacy kernel skills (`oats`, `oats-config`, `oats-packages`) or the `kernel:oats` injection; the capability's skills replace them. Other souls keep the legacy behavior, and `oats doctor` prints an informational line.
+- **Official capabilities.** `oats.framework` **1.1.1** (tag `oats-framework/v1.1.1`) exports `oats.core` (`oats-operate`, `oats-souls`, the "you run on OATS" briefing), `oats.setup` (`oats-config`, `oats-packages`, `oats-workspace-setup`) and `oats.knowledge-theory`, listed in the official catalog with capability aliases.
+- **Retained inspection reports `launchSelection`** (`{runtime, model}` or `null`) for the primary, and provider binding codecs receive `OATS_CLI_BIN`.
+- **aweb 1.11.0 pairing.** The catalog and the framework soul editions pin `oats.aweb@v1.11.0`, which adds the portable binding interface (floor `>=0.24.2`). Its `check` qualifies only an explicit private team with `delivery: session` and an input-capable Claude or Codex primary; a strict-Pi print primary reports `needs-configuration`.
+- **Six framework soul editions** are exported and imported by `oats-workspace.yaml`: `oats-expert`, `oats-kernel-expert`, `oats-desktop-expert`, `market-research-expert`, `oats-assistant` and `oats-setup-expert`, all declaring `oats.core`.
 
-## Second-operator gate
+## Known limits
 
-An independent operator on a fresh machine adopted the shared definition from public sources through `inspect` → `prepare` → approvals with 0.24.1: the whole graph (including `oats.core`/`oats.setup`) resolved and materialized; preparation stopped at aweb 1.10.3 as declared. Five usability seams were recorded (request-file mismatch between `inspect`/`prepare`, raw ENOENT on an absent deployment, `trust --dir` rejecting lock v3, `--artifact-set` missing from help, unattributed provider problems). **They are not fixed in this cut**; see the [program board](../design/2026-09-20-redesign-program-board.md).
-
-## Not in this cut
-
-Desktop marketplace view / soul creation UI, legacy `agents/` roster and in-soul knowledge decommission (after the fresh-reader proof against the public `oats-knowledge`), Pi session-input support.
+- The first-contact seams in `inspect` and `prepare` (request-file mismatch, raw `ENOENT` on an absent deployment, `oats trust --dir` rejecting lock v3, `--artifact-set` missing from help, unattributed provider problems) are fixed in [v0.24.3](v0.24.3.md).
+- Pi primaries do not support session input.

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

@@ -1,13 +1,9 @@
-# OATS v0.24.3 — second-operator `prepare` seams
+# OATS v0.24.3 — `prepare` usability fixes
 
-Kernel/Pi/Desktop **0.24.3**. Fixes the five usability seams an independent second operator hit adopting the shared workspace definition on 0.24.1/0.24.2 (see the [program board](../design/2026-09-20-redesign-program-board.md)). No contract, schema or authority change.
+Kernel/Pi/Desktop **0.24.3**. Fixes five usability problems met when adopting a shared workspace definition on 0.24.1 and 0.24.2. No contract, schema or authority change.
 
-- **Attributed provider problems.** Every preparation problem now carries `slot`, `capability` and its `origins`, with kernel-fixed text (for example `oats.okf knowledge normalize binding could not be prepared` / `oats.aweb@1.10.3 declares no binding interface; messaging cannot be prepared`). The kernel names the missing item where it knows it (a missing binding interface); for a provider's own `needs-configuration` it attributes the slot/capability/phase but cannot name the missing setting unless the provider sends it — OKF 2.1.1 sends code only, so `bindings-file`/`state-dir` are named by the setup guidance and by OKF 2.1.2. One unqualified slot no longer masks another slot's diagnostics: every slot that has a binding interface is normalized, and the single resolver reports each invalid choice under its slot. Provider free text still never crosses the wire.
-- **`oats trust <capability> --dir <deployment>` on a lock v3 deployment** returns a typed problem with the exact working command (`oats trust <cap> --deployment <abs> --artifact-set <sha256-…>`) instead of `unsupported lockfileVersion 3`. No auto-approval.
-- **Help** documents `--artifact-set` and how `prepare`'s `selections[].artifactSet` / `approvalRequired[]` pair with it.
-- **`prepare` on an absent deployment path** returns a typed explicit-provisioning hold, not a raw `ENOENT` with a host path.
-- **One request file for both commands.** `prepare --request` accepts the explicit `workTarget` that `inspect --request` requires (explicit beats cwd; it never implies captured placement or current config), and `oats inspect --request <f> --emit-prepare-request <out>` writes the converted preparation request through the existing builder.
-
-The second operator's recorded requests and results are preserved verbatim as regression fixtures (`test/fixtures/second-operator/`). Their valid-vs-bogus `stores.oats` pair remains identical by design: both refused on missing OKF runtime settings (`bindings-file`, `state-dir`), which the messages now say.
-
-Setup guidance for those settings lands in the next `oats.framework` payload.
+- **Attributed provider problems.** Every preparation problem carries `slot`, `capability` and its `origins`, with kernel-fixed text (for example `oats.aweb@1.10.3 declares no binding interface; messaging cannot be prepared`). For a provider's own `needs-configuration` the kernel names the slot, capability and phase but not the missing setting unless the provider sends it (OKF 2.1.1 sends only a code). One unqualified slot no longer hides another slot's diagnostics. Provider free text still never crosses the wire.
+- **`oats trust <capability> --dir <deployment>` on a lock v3 deployment** returns a typed problem with the working command (`oats trust <cap> --deployment <abs> --artifact-set <sha256-…>`) instead of `unsupported lockfileVersion 3`. Nothing is approved automatically.
+- **Help** documents `--artifact-set` and how it pairs with `prepare`'s `selections[].artifactSet` and `approvalRequired[]`.
+- **`prepare` on an absent deployment path** returns a typed explicit-provisioning hold instead of a raw `ENOENT`.
+- **One request file for both commands.** `prepare --request` accepts the explicit `workTarget` that `inspect --request` requires, and `oats inspect --request <f> --emit-prepare-request <out>` writes the converted preparation request.

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

@@ -1,10 +1,10 @@
 # OATS v0.24.4 — provider reasons cross the wire; one request file for both commands
 
-Kernel/Pi/Desktop **0.24.4**. Two findings from the independent second operator's repeat on 0.24.3 (see the [program board](../design/2026-09-20-redesign-program-board.md)), plus the first half of the binding-ownership rule. Kernel-first release: the provider releases that declare the new manifest fields (OKF 2.1.2, aweb 1.11.1) require this version.
+Kernel/Pi/Desktop **0.24.4**. Provider releases that declare the new manifest fields (OKF 2.1.2, aweb 1.11.1) require this version.
 
-- **The kernel no longer discards the provider's reason.** A provider's `error.message` (and a non-ready `check`'s `result.problems[].message`) now crosses the binding wire when it is byte-equal to a fixed reason the provider declares — manifest `binding.reasons`, or the kernel's reviewed compatibility list for aweb 1.11.0 and OKF 2.1.2 — and is surfaced as the problem's `message` beside `slot`, `capability` and `origins`. Anything else is dropped as before and the kernel template is used. No interpolation, no operator values, no paths, ever: the second operator sees `messaging workspace must declare private: per-human` or `setting bindings-file is required (absolute host path)` in one run instead of six. Decision: `agents/oats-expert/soul/knowledge/decisions/provider-problem-reasons-cross-the-wire.md`.
-- **`binding.reasons` and `binding.keys` manifest fields** (optional). `reasons`: 1–64 unique printable-ASCII strings ≤200 chars, no braces; an invalid declaration refuses, it never falls back. `keys`: a provider's owned operator-binding keys, exact names or trailing-dot namespaces (`stores.`) — **shape-validated only in 0.24.4**; forwarding, overlap refusal and stray-key attribution land in 0.25. Providers must still ignore keys they do not own (decision `operator-bindings-ownership.md`). Every earlier kernel rejects manifests carrying these fields, so declaring providers floor on `>=0.24.4`.
-- **`inspect --request` accepts `prepare`'s fields.** `operator`, `launch`, `helperLaunches`, `mode`, `allowLocalPaths` are accepted, not evaluated, and listed under `ignored`; `--emit-prepare-request` carries them through unchanged. The same complete request file is now valid for both commands — the 0.24.3 fix had converged only one way.
-- **CLI renders the problem `key`** (for example `/bindings/messaging/responsibleHuman`) beside its message.
+- **The kernel no longer discards the provider's reason.** A provider's `error.message` (and a non-ready `check`'s `result.problems[].message`) crosses the binding wire when it is byte-equal to a fixed reason the provider declares in manifest `binding.reasons`, or to the kernel's compatibility list for aweb 1.11.0 and OKF 2.1.2. It is surfaced as the problem's `message` beside `slot`, `capability` and `origins`; anything else is dropped and the kernel template is used. No interpolation, operator values or paths ever cross.
+- **`binding.reasons` and `binding.keys` manifest fields** (optional). `reasons`: 1–64 unique printable-ASCII strings of at most 200 characters, no braces; an invalid declaration refuses. `keys`: a provider's owned operator-binding keys, exact names or trailing-dot namespaces (`stores.`), shape-validated only in this release. Providers must still ignore keys they do not own. Earlier kernels reject manifests carrying these fields, so declaring providers require `>=0.24.4`.
+- **`inspect --request` accepts `prepare`'s fields.** `operator`, `launch`, `helperLaunches`, `mode` and `allowLocalPaths` are accepted, not evaluated, and listed under `ignored`; `--emit-prepare-request` carries them through. The same request file is now valid for both commands.
+- **The CLI renders the problem `key`** (for example `/bindings/messaging/responsibleHuman`) beside its message.
 
-Not in this release: the operator-bindings deadlock between OKF 2.1.1 and aweb 1.11.0 (OKF validated messaging's `wider` as a store locator) is fixed provider-side in OKF 2.1.2, released next with `binding.reasons`/`binding.keys` declared and floor 0.24.4; then aweb 1.11.1 (manifest-only), the `oats.framework` 1.1.2 payload, and the workspace editions re-pinned.
+Known limit: OKF 2.1.1 and aweb 1.11.0 cannot be prepared together (OKF validated messaging's `wider` as a store locator); OKF 2.1.2 fixes it.

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

@@ -1,12 +1,8 @@
-# OATS v0.24.5 — four small fixes from the second-operator wave
+# OATS v0.24.5 — four small fixes
 
-Kernel/Pi/Desktop **0.24.5**. No contract, schema or authority change. Every item was found while an independent operator (and then the lead) drove the published 0.24.4 wave to its first end-to-end resolution.
+Kernel/Pi/Desktop **0.24.5**. No contract, schema or authority change.
 
-- **Retirement recovers a worktree on the branch it actually has.** `oats retire` derived the recovery clone's branch from `instance.json` (the spawn-time branch); a worktree that had legitimately switched branches during its task could never pass recovery verification and became unretirable by the normal path, even with nothing unpreserved. Recovery now derives the branch from the worktree while it exists (detached HEADs recover at their exact commit), falls back to the recorded branch only when the worktree is gone, and records the drift in `recovery.json` (`branchDrift`). Fail-closed behaviour is unchanged; the source of truth moved to the object.
-- **Captured launch: `ifInstalled` runtime rows are not hard blocks, and refusals are attributed.** A provider's `requires` row marked `ifInstalled: true` (a version floor for an ambient package, if present) was treated as a hard requirement, so a Pi launch with aweb `delivery: session` could never publish a resolution — the same request without a `launch` block published fine. Such rows are now satisfied by absence in captured preparation. Remaining hard rows refuse through the ordinary preparation problem shape (`slot`, `capability`, `runtime`, `package`, the manifest's own `install` text) instead of one bare `needs-configuration`.
-- **Helper-injection refusal is attributed.** A capability that ships an `inject` without a `helperInjection` policy now yields a preparation problem naming that capability (with `origins`), so the operator learns *which* sibling has not adopted the contract rather than only that one has.
-- **`oats onboard --workspace` acquires the framework the workspace's catalog names.** The kernel tarball ships `package-catalog.json` as a snapshot at the kernel's tag, so it lags every `oats.framework` release cut afterwards; onboarding a current workspace edition against it refused as `integrity-drift` — correct, but a fresh machine has no reviewed list to point `OATS_PACKAGE_CATALOG` at. Onboarding now reads the workspace repository's `package-catalog.json` at the observed revision and uses its `oats.framework` entry; the bundled entry is the fallback, `OATS_PACKAGE_CATALOG` still overrides. The result reports `catalog.origin`, and a drift refusal names the lag and both integrities.
-
-Rule going forward (recorded in the maintainer's knowledge): **`prepare` never ends in a bare `needs-configuration` after selection** — every refusal is a problem with a slot/capability, or it is a kernel defect. Remaining bare sites are pre-selection input errors, record-shape guards and the skill-name collision, none reachable from a published edition.
-
-Not in this release: `binding.keys` enforcement and the dotted-exact-key grammar (0.25); OKF `check` per-cause reasons (OKF 2.1.3, deferred with harvest).
+- **Retirement recovers a worktree on the branch it actually has.** Recovery used the spawn-time branch from `instance.json`, so a worktree that had switched branches could not be retired by the normal path. Recovery now reads the branch from the worktree while it exists (a detached HEAD recovers at its exact commit), falls back to the recorded branch only when the worktree is gone, and records the difference in `recovery.json` (`branchDrift`). Fail-closed behavior is unchanged.
+- **Captured launch: `ifInstalled` runtime rows are not hard blocks, and refusals are attributed.** A `requires` row marked `ifInstalled: true` (a version floor for an optional package) was treated as mandatory, so a Pi launch with aweb `delivery: session` could never publish a resolution. Such rows are now satisfied by absence. Remaining hard rows refuse with an ordinary preparation problem (`slot`, `capability`, `runtime`, `package`, and the manifest's `install` text).
+- **Helper-injection refusal is attributed.** A capability that ships an `inject` without a `helperInjection` policy yields a preparation problem naming that capability, with `origins`.
+- **`oats onboard --workspace` uses the workspace's catalog.** The bundled `package-catalog.json` is a snapshot at the kernel's tag and lags later `oats.framework` releases, so onboarding a current workspace edition refused as `integrity-drift`. Onboarding now reads the workspace repository's `package-catalog.json` at the observed revision; the bundled entry is the fallback and `OATS_PACKAGE_CATALOG` still overrides. The result reports `catalog.origin`, and a drift refusal names both integrities.

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

@@ -2,8 +2,5 @@
 
 Kernel/Pi/Desktop **0.24.6**. No contract, schema or authority change.
 
-- **`oats catalog [--json]`** — read-only description of the *effective* official package catalog: where it came from (`bundled` snapshot or `OATS_PACKAGE_CATALOG` override), every package with url/ref/payload root and the exact `oats install` argv, and the capability→package alias map with each alias's resolution. Identity and discovery only: nothing is acquired, trusted or fetched (the contract test asserts no filesystem writes). Built for the Desktop's Capabilities view, which cannot import the kernel; the notes in the payload state that catalog identity grants no executable trust and that a bundled catalog may lag later package releases. Aliases are mappings, not an export inventory.
-- **Desktop parity slice 1a** (`feat/desktop-sidebar-keyboard-parity`): compact relation guides in the roster (nesting 14→8px, elbows 7→4px, gutters 8→6px — the human's request for more horizontal room; rows stay 56px, three themes keep computed AA), engine-owned **⌘F** reveal-and-focus filter (un-hides the sidebar first) and **⌘N** explicit soul chooser (never auto-spawns), visible shortcut hints that follow user rebinds/unbinds. Renderer-only; terminal key passthrough and focus ownership unchanged.
-- **CI**: the pull-request workflow now checks out full history — the workspace-layout guard reads pinned import revisions with `git cat-file`, and a shallow clone made main red from `f34207e9` to `475ea9bf`.
-
-Direction for the rest of S8 is recorded in `docs/design/2026-09-22-desktop-parity-seams.md` (slices 1b–8; kernel seams K1–K8; provider seam P1) and the lifecycle/enrollment/permission/auto-PR decisions in the maintainer's knowledge base. Frames 05 Knowledge and 06 Tasks are excluded by direction.
+- **`oats catalog [--json]`**: a read-only description of the effective official package catalog: its origin (`bundled` snapshot or `OATS_PACKAGE_CATALOG` override), every package with URL, ref, payload root and the exact `oats install` argv, and the capability-to-package alias map. Nothing is acquired, trusted or fetched. Catalog identity grants no executable trust, a bundled catalog may lag later package releases, and aliases are mappings, not an export inventory. See [the official catalog](../official-catalog.md).
+- **Desktop sidebar**: more compact relation guides in the roster, **⌘F** reveals and focuses the filter, **⌘N** opens an explicit soul chooser (never auto-spawns), and shortcut hints follow user rebinds.

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

@@ -1,81 +1,52 @@
 # OATS v0.24.7 — instance Git observation, soul declarations, and no hollow agents
 
-Kernel/Pi/Desktop **0.24.7**. Tag `v0.24.7` → commit `c923d81b` (this notes commit; the last code change is `912aaee0`, PR #57). The npm tarball's `gitHead` is `c923d81b`; the version-bump commit lands after the tag (PR #58). A from-the-tag verifier should expect `gitHead == c923d81b`. Two additive read-only contracts for the Desktop
-(`instanceGitApi: 1`, `soulsApi: 1`), one spawn refusal that closes a
-first-team-path defect, and four Desktop parity slices.
+Kernel/Pi/Desktop **0.24.7** (PR #57). Two additive read-only contracts for the
+Desktop (`instanceGitApi: 1`, `soulsApi: 1`), a spawn refusal that closes a
+first-team defect, and Desktop views built on them. The contracts are
+described in the [Desktop CLI API](../desktop-cli-api.md).
 
 ## Kernel
 
 - **`oats instance git <instance> [--home] [--dir] [--json]`** and
-  **`oats instance diff <instance> --file <id> --revision <rev> [--index-revision <idx>] [--json]`** (K1) —
-  read-only Git observation of one instance's work tree. Truth from the tree:
-  the branch the tree is on (the spawn-recorded branch is reported as
-  `recorded` with a `drift` flag). Porcelain v2 NUL status with renames keeping
-  both paths; **upstream and default-branch merge-base as two separate
-  comparisons** — no upstream is `null`, never 0/0. Opaque file ids minted
-  under (HEAD, index); a diff is taken against the *captured* revision oid and
-  refuses `E_STALE_OBSERVATION` (fresh observation attached) if HEAD, index or
-  the file's content moved, before **or during** the read. Bounded (256 KiB,
-  binary flagged). Qualified addressing: several homes with one name refuse
-  `E_AMBIGUOUS_INSTANCE` with candidates; retired/unmaterialized tree is
-  `E_NO_WORKTREE`.
-  **Hardened after a consumer-side adversarial probe**: the observed tree is
-  worked in by an agent, so its repo config is input — external diff, textconv,
-  fsmonitor and hooks are disabled, the caller's Git environment and global/
-  system config are not inherited, optional locks are off (no index refresh),
-  and the index revision is a hash of `ls-files --stage` (no `write-tree`, no
-  object written). The response states it: `readOnly: {helpers, optionalLocks, objectsWritten}`.
-- **`oats inspect --json` souls carry their declarations** (K4, `soulsApi: 1`):
-  `declarations` (requires/defaults/knowledge/teams/resources, parsed
-  kernel-side, `null` when absent), `provenance` (recorded by `oats onboard`
-  from now on; `null` = *unrecorded*, never inferred), `readiness` (declared
-  sources joined against the same payload's capability inventory — separate
-  from launchability and adoption; never a green "Ready"), and
-  `result.sources` — the scope's portable source context, with an honest
-  `none-recorded` state.
-- **No hollow agents.** `oats create` declares `oats.core` by default; composition
-  honours the declaration by suppressing the kernel's legacy skills — but nothing
-  on that path activates the replacement, so a `spawn` produced an agent with
-  **no operational curriculum and no warning** (second-operator finding on 0.24.6).
-  Now `spawn` refuses `E_REQUIREMENT_INACTIVE` before creating anything, with
-  the remedy (`oats install oats.framework` if needed, then
-  `oats use oats.core --soul <name>`) and the opt-out (remove the declaration).
-  `create` states the activation step up front (`next-step` note,
-  `declaredCapabilities` in `--json`). `create` stays declaration, not acquisition.
-
-## Desktop (parity slices 1b, 2a, 3, 4, 6a, 7a)
-
-- **1b** shared contextual right panel (Instance · Git & GitHub · Soul), collapsed
-  rail, per-workspace preferences, temporary focus mode.
-- **2a** Git & GitHub panel on K1: worktree/branch/drift, upstream and base named
-  separately, real file counts and rename paths, bounded read-only diff; stale
-  → re-observe, never rendered. The legacy background `gitState` collector —
-  which ran Git against every instance tree on every roster poll without helper
-  controls and substituted healthy zeros on failure — is **removed**. Desktop
-  Git reads are the K1 route only. GitHub/PR card is *unavailable* pending the
-  P1 decision: forge connections are an ADE/workstation integration, not a capability (working names `oats.git`/`oats.forge` retired).
-- **3** Souls + Sources on K4: declarations, recorded provenance (`null` renders
-  *Unrecorded*, never *Local*), "Not declared" vs "Not reported" distinguished,
-  sources-installed ≠ Ready.
-- **4** Capabilities: official catalog via `oats catalog` (0.24.6+) plus the
-  deployment's classic inventory; aliases are mappings not exports, refs are refs,
-  override catalogs conspicuously labelled; "Add capability" copies the schema's
-  exact `oats install <package>` argv and never executes it.
-- **6a** Spawn modal to the redesign on existing seams: two-column layout,
-  grouped soul chooser, provider/model with reported-vs-assumed provenance,
-  launch configuration restored (an already-supported property the renderer had
-  regressed out of), fields that need K6 rendered disabled with their seam named.
-- **7a** Active overview (frame 07) on the roster: anonymous count-labelled
-  relation groups (the roster reports no group names), activity `unknown` until K7.
-
-Desktop CLI floor for the new views is **0.24.7** (`instanceGitApi`/`soulsApi`
-gates); an older CLI renders those views as *unavailable*, never as empty-healthy.
-
-## Also
-
-- Board and seams doc dates corrected (2026-09-21, not 09-22 — lead clock error
-  caught by the second operator). Pinned SHAs unaffected.
-- Second-operator `launch` re-run on 0.24.6 passed both halves (publish with an
-  executable launch selection; hard runtime row refuses attributed).
-- OKF 2.1.3 bug list (deferred with harvest): `check` per-cause reasons; retire
-  leaves the per-source `okf-<id>` schedule definition enabled.
+  **`oats instance diff <instance> --file <id> --revision <rev> [--index-revision <idx>] [--json]`**:
+  read-only Git observation of one instance's work tree. It reports the branch
+  the tree is actually on (the spawn-recorded branch as `recorded`, with a
+  `drift` flag), status with renames, and upstream and default-branch
+  comparisons separately (no upstream is `null`). A diff refuses
+  `E_STALE_OBSERVATION` if HEAD, the index or the file moved; reads are bounded
+  at 256 KiB. Several homes with one name refuse `E_AMBIGUOUS_INSTANCE`; a
+  retired tree is `E_NO_WORKTREE`. The observed tree's repository config is
+  treated as untrusted input: external diff, textconv, fsmonitor and hooks are
+  disabled, the caller's Git environment and global config are not inherited,
+  and no object or index refresh is written (`readOnly` in the response).
+- **`oats inspect --json` souls carry their declarations** (`soulsApi: 1`):
+  `declarations`, `provenance` (recorded by `oats onboard` from now on; `null`
+  means unrecorded), `readiness` (declared sources joined against the payload's
+  capability inventory, separate from launchability), and `result.sources`.
+- **No hollow agents.** `oats create` declares `oats.core` by default, which
+  suppresses the kernel's legacy skills, but nothing activated the replacement,
+  so `spawn` produced an agent with no operational curriculum. `spawn` now
+  refuses `E_REQUIREMENT_INACTIVE` before creating anything, with the remedy
+  (`oats install oats.framework` if needed, then `oats use oats.core --soul
+  <name>`) and the opt-out (remove the declaration). `create` states the
+  activation step (`next-step` note, `declaredCapabilities` in `--json`).
+
+## Desktop
+
+- A shared contextual right panel (Instance, Git & GitHub, Soul) with a
+  collapsed rail, per-workspace preferences and a temporary focus mode.
+- **Git & GitHub panel** on `oats instance git|diff`: worktree, branch and
+  drift, upstream and base named separately, file counts and rename paths, and
+  a bounded read-only diff; stale observations are re-read, never rendered. The
+  old background Git collector, which ran Git on every roster poll, is removed.
+  The GitHub/PR card is unavailable in this release.
+- **Souls and Sources** on the new declarations: recorded provenance
+  (`null` renders *Unrecorded*), "Not declared" distinct from "Not reported".
+- **Capabilities**: the official catalog via `oats catalog` plus the
+  deployment's inventory; override catalogs are labelled; "Add capability"
+  copies the exact `oats install <package>` argv and never executes it.
+- **Spawn modal** redesigned: two-column layout, grouped soul chooser,
+  provider and model with their provenance, and launch configuration restored.
+- **Active overview** of the roster, with activity shown as unknown.
+
+The new views need CLI **0.24.7**; an older CLI renders them as unavailable.

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

@@ -1,107 +1,69 @@
 # OATS v0.24.8 — lifecycle plans, readiness, spawn preview, instance events, and guarded Stop/Remove in the Desktop
 
-Kernel/Pi/Desktop **0.24.8**. Tag `v0.24.8` → the commit carrying these notes
-(the last code change is `508fda04`, PR #69). The npm tarball's `gitHead` is
-the tagged commit; the version-bump commit lands after the tag. All new
-contracts are **advertised**: consumers gate on `oats version --json`
-`features[]` names and the API integers below — never on the version number,
-never by optimistic invocation.
+Kernel/Pi/Desktop **0.24.8** (PR #69). Every new contract is advertised:
+consumers gate on `oats version --json` `features[]` names and API integers,
+never on the version number. Full shapes are in the
+[Desktop CLI API](../desktop-cli-api.md).
 
-## Kernel — the remaining Desktop-parity seams (K3, K5, K6, K7, K8)
+## Kernel
 
-- **Lifecycle plans** (K3, `lifecycleApi: 1`, feature `lifecycle-plans`):
-  `oats instance stop <i> --plan|--apply` and `oats retire <i> --plan`, then the
-  **guarded apply** `oats retire <i> --plan-revision <rev> --idempotency-key <key>
-  [--discard-worktree] [--delete-branch]`. A plan states producer facts (ordered
-  targets deepest-first, session/work facts, recorded children, `midTask:
-  "unknown"` never inferred) under a 24-hex `planRevision`; apply re-reads and
-  refuses `E_PLAN_STALE` (fresh plan attached) when facts moved. Keys replay
-  their own receipt instead of acting twice — stop receipts are stored **per
-  key**, retire receipts survive the home's removal.
-  - **Retention by default** (feature `retire-retention`): a plain retire
-    re-homes the worktree to `<workspace>/.agents/worktrees/<repo>/<branch>`
-    instead of deleting it; `--discard-worktree` removes; `--delete-branch`
-    deletes the branch the tree is **verified** to be on and implies discard.
-    Receipt `retention {worktree: retained|removed|absent, movedTo, branch,
-    recordedBranch, branchDeleted?, branchDeletionSkipped?}`; a failed move is
+- **Lifecycle plans** (`lifecycleApi: 1`, feature `lifecycle-plans`):
+  `oats instance stop <i> --plan|--apply` and `oats retire <i> --plan`, then
+  the guarded apply `oats retire <i> --plan-revision <rev> --idempotency-key
+  <key> [--discard-worktree] [--delete-branch]`. A plan states the facts
+  (ordered targets, session and work facts, recorded children) under a
+  `planRevision`; apply refuses `E_PLAN_STALE` when they moved. A repeated key
+  replays its receipt instead of acting twice.
+  - **Retention by default** (feature `retire-retention`): a plain retire moves
+    the worktree to `<workspace>/.agents/worktrees/<repo>/<branch>` instead of
+    deleting it; `--discard-worktree` removes it; `--delete-branch` deletes the
+    branch the tree is verified to be on and implies discard. A failed move is
     `E_WORK_PRESERVATION_FAILED` with the home kept.
-  - **Children first, kernel-owned.** A guarded retire stops the plan's recorded
-    children (bounded SIGTERM, never escalated) and retains them; a child still
-    running refuses the whole retirement — `E_CHILDREN_RUNNING`, nothing retired.
-  - **Branch deletion is bound to the confirmed branch**: re-verified at deletion,
-    after hooks (which may mutate the tree); a mismatch deletes nothing and
-    reports `branchDeletionSkipped {expected, actual, reason}`.
-  - **Ambiguous parentage is reported, never acted on**: parent edges are bare
-    names; one that resolves to several homes appears under `ambiguous[]`
-    (`plan.ambiguous` on stop, `plan.facts.ambiguous` on retire).
-  - A pre-plan CLI does not understand `--plan` and would retire on it; that is
-    exactly why the feature is advertised — consumers must gate.
-- **Readiness** (K5, `readinessApi: 1`): `oats readiness [--soul] [--home]
-  [--verify-signatures] [--policy] --json` — the quartet
-  installed · trusted · configured · enrolled, each `pass|fail|unknown|not-applicable`
-  with items `{subject, required, reason, producer, evidence, remedy}`;
-  `summary.ready` is never vacuous. Signatures are `unknown` unless
-  `--verify-signatures` (an explicit one-commit fetch; `verified|unsigned|invalid`
-  with the signer named). Enrolled = workspace-member admission.
-- **Enforced child policy** (K5): soul `children: {spawn: bool}`, spawn
-  `--allow-child-spawns|--no-child-spawns`, recorded as `instance.json`
-  `policy.childSpawns {allowed, origin}`; a spawn with `--parent` under an off
-  policy refuses `E_CHILD_SPAWNS_DISABLED`. `inspect --json` souls carry
-  `declarations.children`; capability rows carry `commit`.
-- **Spawn preview** (K6, `spawnPreviewApi: 1`): `oats spawn … --preview --json`
-  states the decision — instance name, home, worktree, branch, base `{ref, oid}`,
-  runtime/model/launch config, work mode, composition sources, policy — without
-  creating anything. `--base <ref>` picks the base; `@native-default` names the
-  runtime's own default explicitly.
-- **Instance events** (K7, `eventsApi: 1`, feature `instance-events`):
-  `oats instance events <i> [--limit] [--since] --json` — typed, producer-
-  attributed lifecycle events (spawned, launched, restarted, stopped,
-  stop-refused, retire-planned, retired, worktree-retained, branch-deleted,
-  child-spawn-refused, recomposed) from the home's log and the workspace's
-  retained copy; truncation and unreadable lines are visible, never smoothed.
-- **Schedule run history** (K8, `scheduleApi: 2`, feature `schedule-history`):
-  schedules report `recentRuns` — settled runs only, producer order, ≤ 50.
+  - **Children first.** A guarded retire stops the plan's recorded children
+    (bounded SIGTERM, never escalated); a child still running refuses the whole
+    retirement with `E_CHILDREN_RUNNING`.
+  - Branch deletion is re-verified after hooks; a mismatch deletes nothing and
+    reports `branchDeletionSkipped`. Ambiguous parentage is reported, never
+    acted on.
+  - An older CLI does not understand `--plan` and would retire on it, so
+    consumers must gate on the feature.
+- **Readiness** (`readinessApi: 1`): `oats readiness [--soul] [--home]
+  [--verify-signatures] [--policy] --json` reports installed, trusted,
+  configured and enrolled, each `pass|fail|unknown|not-applicable`, with items
+  and remedies. Signatures are `unknown` unless `--verify-signatures` is given.
+- **Child spawn policy**: soul `children: {spawn: bool}` and spawn
+  `--allow-child-spawns|--no-child-spawns`, recorded in `instance.json`; a spawn
+  with `--parent` under a disabled policy refuses `E_CHILD_SPAWNS_DISABLED`.
+- **Spawn preview** (`spawnPreviewApi: 1`): `oats spawn … --preview --json`
+  states the instance name, home, worktree, branch, base, runtime, model, launch
+  configuration, work mode and policy without creating anything. `--base <ref>`
+  picks the base; `@native-default` names the runtime's default.
+- **Instance events** (`eventsApi: 1`, feature `instance-events`):
+  `oats instance events <i> [--limit] [--since] --json` returns typed lifecycle
+  events (spawned, launched, restarted, stopped, retired, worktree-retained,
+  branch-deleted, recomposed and others); truncation and unreadable lines are
+  visible.
+- **Schedule run history** (`scheduleApi: 2`, feature `schedule-history`):
+  schedules report up to 50 settled `recentRuns`.
 - **Instruction refresh** (feature `session-recompose`): `oats session recompose
-  --home <abs> [--dry-run] --json` recomposes a **live** home's `AGENTS.md`
-  from its current soul with the same composer spawn used; previous text is
-  retained beside it, `instance.json` and a `recomposed` event record it,
-  nothing is restarted. An operator action for when a role changes and a
-  respawn is not possible or wanted.
-- Remote workspaces: `oats instance git|diff` reach a remote instance through
-  the negotiated route (K1 remote), refusing rather than guessing where no
-  route exists.
+  --home <abs> [--dry-run] --json` recomposes a live home's `AGENTS.md` from its
+  current soul, keeps the previous text beside it, and restarts nothing.
+- `oats instance git|diff` reach remote instances through the saved route.
 
-## Desktop (parity slices 2b and 2c)
+## Desktop
 
-- **2b — Connections.** Settings → Connections with an inline "Connect
-  GitHub" (device flow through `gh`, credential custody stays with `gh`; the
-  auth pane is a closed key set with redaction). The Git & GitHub panel gains an
-  observation-bound PR card: informational, correlated to the exact K1
-  revision/branch/remote, never authority. Forge connections are an **ADE
-  integration**, not a capability.
-- **2c — Stop and Remove.** The instance menu offers *Stop…* and *Remove
-  instance…*; both open a plan-backed confirmation showing the kernel's exact
-  targets, skipped/ambiguous children, session and work facts, the real branch
-  (recorded-branch drift noted separately) and retained-by-default choices.
-  One guarded local route; the plan is read from the CLI, each confirmation
-  gets an opaque reference, the idempotency key is minted on the first
-  confirmation and kept for that intent's retries, one apply at a time; lost
-  responses are shown as **unknown outcome**, never "no effect". Stale plans
-  require a new confirmation; a refused child stop names the child. The old
-  unguarded retire route now answers `E_PLAN_REQUIRED`.
-- Everything above is **unavailable** (not hidden, not guessed) when the
-  installed CLI does not advertise the corresponding feature.
-
-## Also
-
-- Lessons recorded: consumers gate on advertised features, never on
-  optimistic invocation; a declaration that suppresses a default must be
-  enforced; read-only Git observation is a security boundary.
-- Verification budget: one full gate per change is PR CI; locally only the
-  affected suites. Desktop-only changes run the Desktop suites plus the
-  focused suite.
+- **Connections**: Settings → Connections with "Connect GitHub" (device flow
+  through `gh`, which keeps the credential). The Git & GitHub panel gains an
+  informational PR card tied to the observed revision and branch.
+- **Stop and Remove**: the instance menu offers *Stop…* and *Remove
+  instance…*, each with a plan-backed confirmation showing the kernel's targets,
+  children, session and work facts, the real branch and the retention choices.
+  Lost responses show an unknown outcome; stale plans need a new confirmation.
+  The old unguarded retire route answers `E_PLAN_REQUIRED`.
+- Each control is unavailable when the installed CLI does not advertise its
+  feature.
 
 ## Upgrade
 
-`npm i -g @awebai/oats@0.24.8`, then `oats doctor`. Desktops pinned to an
-older CLI keep working; new controls appear as the CLI's advertised features do.
+`npm i -g @awebai/oats@0.24.8`, then `oats doctor`. Desktops on an older CLI
+keep working; new controls appear as the CLI advertises their features.