@awebai/oats 0.29.4 → 0.30.0

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

@@ -4,174 +4,78 @@ One release built from one tag: `@awebai/oats@0.19.0`,
 `@awebai/oats-pi@0.19.0`, and **OATS Desktop 0.19.0** in this GitHub Release.
 
 This release introduces distribution packages, exact OATS-managed instance
-curricula, canonical primary-checkout instance homes, and the package/profile
-setup flow needed for independently published official capabilities.
+curricula, canonical instance homes, and package config profiles.
 
 ## Distribution packages
 
-An OATS package is now the acquisition, integrity, update, and review unit above
-independently targetable capabilities. A Git repository may contain ordinary
-development content and one or more package payloads; the selected payload path
-is part of the source and lock contract.
-
-```bash
-# Git/catalog sources default to the contained oats-package/ directory.
-oats install https://github.com/example/project.git@v1.0.0
-
-# Select another contained directory, or the repository root explicitly.
-oats install 'https://github.com/example/project.git@v1.0.0#dist/oats'
-oats install 'https://github.com/example/root-package.git@v1.0.0#.'
-
-# A local path always names the exact package root.
-oats install ../project/oats-package
-```
+An OATS package is the acquisition, integrity, update, and review unit above
+independently targetable capabilities. Git and catalog sources default to the
+contained `oats-package/` directory; `#<path>` selects another directory (`#.`
+for the repository root), and a local path names the exact package root.
 
 Lock v2 records source, exact commit, selected path, integrity, dependency
 closure, exported capabilities, and per-capability executable approvals. Bare
-`oats install` restores the exact locked graph; it never advances a branch,
-catalog selector, package path, or dependency closure. Updating remains
-explicit:
-
-```bash
-oats update <package-id>
-```
+`oats install` restores the exact locked graph; updating is explicit
+(`oats update <package-id>`). Acquisition installs and hashes only the selected
+payload subtree; root `.git` metadata appearing later inside a managed artifact
+is treated as source drift and invalidates trust. See
+[Distribution packages](../packages.md).
 
-Acquisition installs and hashes only the selected payload subtree. Repository
-CI, documentation, owner souls, sibling packages, and source-control metadata
-are not installed. If root `.git` metadata later appears inside a managed
-artifact, it is treated as source drift and invalidates trust rather than being
-an approval-invisible exclusion.
+## Package config profiles
 
-## Package config profiles and workspace setup
-
-Packages may ship complete reference `oats-config.yaml` profiles. Adoption is
-explicit and produces an editable local snapshot:
+Packages may ship reference `oats-config.yaml` profiles. Adoption is explicit
+and writes an editable local snapshot:
 
 ```bash
 oats init --package <package-source> [--config <profile>] --dir <workspace>
 oats install --dir <workspace>
 ```
 
-The first command acquires and exact-locks the full package closure, validates
-the selected profile against its capability providers, and writes the snapshot.
-The second command reconciles the team boundary and nested repository locks.
-Package updates never rewrite an adopted config; normal targeting, exclusions,
-settings, and closer repository overrides remain authoritative.
-
-Missing host commands and runtime packages remain a separate consent decision.
-Human and JSON plans show every ordered argv step before anything executes.
-Spawn verifies required runtime packages but never installs them.
-
-## Exact OATS-managed instance curriculum
-
-For each soul, the scoped config cascade now determines the complete
-OATS-managed skill and instruction set. Active capability resources are
-enumerated before scaffolding, copied into the canonical instance tree, and
-asserted against the expected composition. Missing, untrusted, duplicate, or
-uncontained active resources fail closed instead of producing a half-configured
-agent.
-
-Canonical instance resources are:
-
-```text
-<instance-home>/.agents/skills/
-<instance-home>/.claude/skills -> ../.agents/skills
-<instance-home>/AGENTS.md
-<instance-home>/CLAUDE.md -> AGENTS.md
-```
-
-Runtime posture is deliberately provider-specific and recorded in
-`instance.json`:
-
-- **Pi** suppresses ambient skills, context files, and prompt templates while
-  preserving operator-configured extensions.
-- **Claude Code** preserves the operator's native user/repository settings,
-  skills, plugins, MCP, hooks, and memory; OATS adds its canonical composed
-  resources without exclusion flags.
-
-The guarantee is exact OATS-managed composition, not identical ambient behavior
-across providers.
-
-## Canonical instance homes and the home/work boundary
+Package updates never rewrite an adopted config. Missing host commands and
+runtime packages remain a separate consent decision; plans show every ordered
+step before anything executes, and spawn verifies required runtime packages but
+never installs them.
 
-Instance homes now live under the soul-owning repository's primary checkout,
-even when spawn is invoked from a linked worktree or from an agent's `work/`.
-Unresolvable placement fails closed before creating anything.
+## Exact instance curriculum and canonical homes
 
-Every runtime and lifecycle hook receives the absolute `OATS_INSTANCE_HOME`.
-Generated instructions distinguish the two operational surfaces:
+The scoped config cascade determines each soul's complete OATS-managed skill and
+instruction set. Missing, untrusted, duplicate, or uncontained active resources
+fail closed. Resources are composed into `<instance-home>/.agents/skills/`
+(linked from `.claude/skills`) and `AGENTS.md` (linked from `CLAUDE.md`). Pi
+suppresses ambient skills, context files, and prompt templates; Claude Code
+keeps the operator's native settings, skills, plugins, MCP, hooks, and memory.
 
-- instance home contains instructions, task, soul reference, provenance,
-  selected skills, and episodic state; OATS lifecycle and active-capability
-  commands run there;
-- `<instance-home>/work` is the repository or workspace view where permitted
-  reading, editing, Git, builds, tests, and commits happen.
+Instance homes live under the soul-owning repository's primary checkout, even
+when spawn runs from a linked worktree. Every runtime and hook receives the
+absolute `OATS_INSTANCE_HOME`; lifecycle commands run in the home, repository
+work happens in `<instance-home>/work`.
 
-OATS performs resolved-path containment checks and rechecks the created home
-before writing credentials or running hooks. The deployment agents directory
-must still be operator-owned and not writable by untrusted local processes.
+## Required hooks and runtime requirements
 
-## Required hooks, runtime requirements, and safe rollback
+Capability spawn hooks may declare `required: true`; a failing required hook
+fails the spawn. If compensation cannot finish, OATS keeps a quarantine that
+`oats retire` retries before deleting the home (`--force` remains available).
+Requirement consent supports runtime-scoped Pi packages and Claude plugins.
 
-Capability spawn hooks may declare `required: true`. A required hook that cannot
-establish its contract fails the spawn. If compensation cannot finish, OATS
-retains a versioned quarantine containing the credential and original cleanup
-metadata; `oats retire` retries and verifies outstanding cleanup before deleting
-the home. `--force` remains the explicit operator escape hatch.
+## Compatibility with 0.18 installations
 
-Requirement consent now supports runtime-scoped Pi packages and Claude plugins,
-including multi-step marketplace registration plans. JSON and human output show
-the same exact ordered steps.
-
-## Existing 0.18 capability installations
-
-Upgrading the kernel does **not** force a capability migration. Existing valid
-v1 locks, installed official capability artifacts, config activation, and trust
-continue to work in 0.19.0.
-
-The guided command is included:
-
-```bash
-oats migrate --official --recursive --dry-run --dir <team-root>
-oats migrate --official --recursive --dir <team-root>
-```
-
-It remains held until the official package catalog and immutable package tags
-are published. That catalog/default redirect ships in the planned 0.19.1
-follow-up. Until then, `oats doctor` explains that the legacy capabilities remain
-supported. Migration preserves config files and capability IDs, leaves custom,
-owned, and path capabilities untouched, and never transfers executable trust
-silently.
-
-Legacy kernel-marketplace capabilities may still reference framework-hoisted
-resources. Those paths now anchor at the declaring capability's canonical
-marketplace directory and remain contained by the installed kernel. Valid older
-installed+locked capabilities continue working across a kernel upgrade.
+Existing v1 locks, installed official capabilities, activation, and trust keep
+working; no migration is forced. `oats migrate --official --recursive
+[--dry-run] --dir <team-root>` is included but held in this release because the
+official package catalog was not yet published; `oats doctor` explains that the
+legacy capabilities remain supported.
 
 ## OATS Desktop
 
-Desktop accepts the matching 0.19 CLI through Desktop CLI API v1
-(`>=0.18.0 <0.20.0`) instead of rejecting its own release and degrading to
-observation-only mode. Compatibility and recovery copy are derived from one
-runtime contract rather than repeated literals.
-
-Desktop also includes the accumulated 0.18.x post-release work: cluster-aware
-agent navigation, persistent editor-style terminal groups, Quick Open for souls,
-runtime-scoped model suggestions, improved spawn readiness handoff, and the
-existing editable shortcut system.
-
-## Downloads
-
-| Platform | Artifacts |
-| --- | --- |
-| macOS arm64 (Apple Silicon) | DMG + ZIP |
-| macOS x64 (Intel) | DMG + ZIP |
-| Linux x64 | AppImage + DEB |
+Desktop accepts CLI versions `>=0.18.0 <0.20.0` (Desktop CLI API v1). It also
+includes cluster-aware agent navigation, persistent terminal groups, Quick Open
+for souls, runtime-scoped model suggestions, and improved spawn readiness
+handoff.
 
-macOS artifacts are ad-hoc signed, not Developer ID signed or notarized. First
-launch may require right-click → **Open**, or **Open Anyway** in System Settings.
-Verify assets with `SHA256SUMS.txt` and the GitHub build-provenance attestations.
-Windows and Linux arm64 are not supported in this release.
+Installers: macOS arm64 and x64 (DMG + ZIP), Linux x64 (AppImage + DEB). macOS
+builds are ad-hoc signed, not notarized; first launch may need right-click →
+**Open**. Verify assets with `SHA256SUMS.txt` and the build-provenance
+attestations. Windows and Linux arm64 are not supported.
 
 ## Install or update
 
@@ -180,7 +84,4 @@ npm install -g @awebai/oats@0.19.0
 pi install npm:@awebai/oats-pi@0.19.0
 ```
 
-The kernel, Pi adapter, and Desktop publish from the same tag and should stay on
-matching versions. Official OATS capability packages are published separately
-after released-kernel consumer probes; this release does not claim that their
-catalog entries are live yet.
+Keep the kernel, Pi adapter, and Desktop on matching versions.

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

@@ -12,9 +12,8 @@ Corrective patch for the v0.19.0 marketplace compatibility bridge.
 - Preserves framework-author `oats.authoring` skill composition from the
   published kernel layout.
 
-The official package catalog and default migration redirects are not included
-in this corrective patch; they follow after the independently tagged official
-packages complete their published-kernel probes.
+This patch does not include the official package catalog or migration
+redirects.
 
 Install matching kernel and Pi adapter versions:
 

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

@@ -1,16 +1,3 @@
-# OATS v0.19.3 (unpublished)
+# OATS v0.19.3
 
-The v0.19.3 pre-publish tag failed its test gate, produced no npm package or
-GitHub Release, and was removed. Its documentation refresh shipped in v0.19.4.
-
-Documentation refresh after the official package and workspace rollout.
-
-- Rewrites the README around OATS's central value: durable, provider-agnostic
-  specialist agents with exact OATS-managed curricula, compounding expertise,
-  mixed-provider teamwork, package/config sovereignty, and Desktop situational
-  awareness.
-- Documents the now-published official package repositories, `oats-package/`
-  payload convention, `oats.dev` non-Git workspace setup, and guided migration
-  from 0.18 capability locks.
-
-No runtime contract changes from v0.19.2.
+Tagged, not published; its changes shipped in v0.19.4.

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

@@ -64,21 +64,6 @@ Desktop API remains version 1. Desktop 0.20 accepts released CLI versions in
 `>=0.18.0 <0.21.0`. This range includes the matching 0.20 kernel.
 Prerelease versions are not accepted.
 
-## Required release order
-
-The framework and package releases have a strict dependency order.
-
-1. Release the v0.20.0 kernel, Pi adapter, and Desktop first.
-2. After that consumer contract is available, revise and test all six official
-   package repositories. They are `oats-okf`, `oats-aweb`, `oats-jira`,
-   `oats-linear`, `oats-authoring`, and `oats-dev`. Tag immutable package revisions
-   in dependency order. Release leaf packages first and `oats.dev` last.
-3. Only after all six immutable package tags exist, update the kernel catalog.
-   Cut a framework patch if the catalog change requires one.
-
-Do not retag an existing package release. The revised package versions do not
-become catalog defaults until the catalog follow-up ships.
-
 ## Install or update
 
 ```bash

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

@@ -4,170 +4,104 @@ OATS v0.22.0 is the first release under the OATS name. The framework release
 includes `@awebai/oats@0.22.0`, `@awebai/oats-pi@0.22.0`, and OATS Desktop
 0.22.0.
 
-The version number sits above every release of the OAS line (`@oas-framework/oas`
-0.21.2 is the latest as of this release) so that "OATS is at least OAS" holds
-numerically. This release includes the OAS 0.20.1, 0.21.1, and 0.21.2
-corrections, ported with their original authorship preserved; it does not
-include the OAS 0.21.0 remote catalog fetch (see "Not included" below).
+The version sits above every release of the OAS line (`@oas-framework/oas`
+0.21.2 was the latest). This release includes the OAS 0.20.1, 0.21.1, and
+0.21.2 corrections; it does not include the OAS 0.21.0 remote catalog fetch.
 
 ## The rename: OAS is now OATS
 
 Everything previously published as **OAS** (`@oas-framework/oas`,
-`@oas-framework/pi`, the OAS Desktop) continues as **OATS** (`@awebai/oats`,
-`@awebai/oats-pi`, OATS Desktop). The rename is a clean break: this kernel
+`@oas-framework/pi`, OAS Desktop) continues as **OATS** (`@awebai/oats`,
+`@awebai/oats-pi`, OATS Desktop). The rename is a clean break: the kernel
 recognizes no `oas-*` file name, no `oas:` config key, and no `oas.*`
 capability id.
 
-Deployments created by OAS must migrate, and now can:
+Deployments created by OAS must migrate:
 
 ```bash
 oats migrate --from-oas --dry-run --dir <scope>   # full plan, touches nothing
 oats migrate --from-oas --dir <scope>             # convert this scope
 ```
 
-One transaction per scope: file renames (`oas-config.yaml`,
-`oas-lock.json`, capability `oas.json` manifests, soul scaffold-owner
-files), the `oas:` config key, and capability ids, then the guided package
-conversion, so the scope ends on `lockfileVersion: 2` official packages.
-Any failure restores the original OAS bytes; a second run is a no-op.
-Executable trust is re-earned after conversion. See
-[docs/migration-from-oas.md](https://github.com/awebai/oats/blob/v0.22.0/docs/migration-from-oas.md).
-
-Un-migrated OAS scopes are also **loud** now: `oats doctor` names them with
-the remedy, and every `oats migrate` form exits nonzero instead of
-reporting "nothing to migrate" on a scope that is actually a pre-rename
-deployment.
-
-The migration was verified against OAS 0.20.x deployments. OAS 0.21.x scopes
-use the same file names, config keys, and capability ids, but the official
-packages they lock may be the OAS v2.0.0 line, which the OATS catalog does not
-yet carry; run the dry run first and read its plan.
-
-## Scope of the 0.18 upgrade guarantee, corrected
-
-Earlier notes said existing valid v1 locks and installed capabilities
-continue to work after a kernel upgrade. That claim holds for **OATS-named
-scopes only** (`oats-config.yaml` / `oats-lock.json`). It was never true
-for OAS-named deployments, whose files this kernel does not read; that is
-exactly what `oats migrate --from-oas` is for.
-
-## Corrections ported from OAS 0.20.1, 0.21.1, and 0.21.2
-
-These land here with the same behavior as in the OAS line, renamed.
-
-- **Own-property config handling and `__proto__` rejection.** Config
-  parsing and diagnostics no longer consult inherited `Object.prototype`
-  properties anywhere: key dispatch, capability binding, command-owner lookup,
-  skill overrides, and shape validation are own-property. YAML keys named
-  `__proto__` are refused with the typed failure `unsafe-config-key`, and
-  the offending file is named.
-- **Internal annotations cannot arrive from disk.** Underscore-prefixed
-  engine annotations (`_capabilityLock`, `_soulDir`, `_origin`, ...) are
-  stripped from every manifest and soul reader before the kernel annotates
-  them, so an on-disk document cannot assert its own provenance or silence
-  doctor's orphan warning.
-- **Config writes fail closed.** Text that would change the shape of a
-  written config is refused with `unsafe-config-value` or
-  `unsafe-config-key` instead of being written: line breaks (including
-  U+0085, U+2028, U+2029), embedded `" #"`, empty values, leading YAML
-  structure indicators, and `:` or `#` in keys. This includes the scaffolded
-  `name:` line: `oats init`, and the first `oats use` or `oats type add` in a
-  fresh scope, refuse to run in a directory whose basename cannot be stored
-  as one YAML scalar. Home directories containing `$&`-style sequences are
-  expanded literally on every write path.
-- **Typed CLI failure boundary.** `unsafe-config-key`, `unsafe-config-value`,
-  and `E_NO_CONFIG` render as one `oats:` line or one `--json` envelope
-  instead of a raw stack. Configless `oats use` reports `E_NO_CONFIG` with
-  the `oats init --raw` remedy instead of a misleading `acquired: none`.
-  Spawn no longer re-badges these as `E_SPAWN_FAILED`.
-- **Scope-exact doctor and trust.** `oats doctor` judges each installed
-  artifact against the lock of the scope that installed it, reading revised-v2
-  `capabilities` rows directly instead of the merged chain, so a chain that
-  holds one package id at two scopes with different source spellings is no
-  longer reported as `invalid-lock`, and v2-locked capabilities are no longer
-  reported as orphans. Trust evaluation reads the row from the artifact's own
-  scope.
-- **Desktop parity.** The Desktop deployment reader reads revised-v2
-  capability locks, refuses every lock shape the kernel refuses, and its
-  legacy-v1 artifact digest counts `.git` and nested lock files exactly as the
-  kernel does.
-- **Package payload is never a deployment scope.** Bare `oats install` at a
-  team scope no longer reconciles config templates that live under a package
-  manifest (`oats-package.json`) as if they were live deployments, so a
-  workspace that develops packages stops failing reconciliation for
-  directories no operator could act on. The same walk backs
-  `oats migrate --official --recursive`.
+Each scope converts in one transaction (file names, the `oas:` key, capability
+ids, then the guided package conversion to `lockfileVersion: 2`). Any failure
+restores the original bytes; a second run is a no-op. Executable trust is
+re-earned after conversion. See
+[migration from OAS](https://github.com/awebai/oats/blob/v0.22.0/docs/migration-from-oas.md).
+
+`oats doctor` names un-migrated OAS scopes with the remedy, and every
+`oats migrate` form exits nonzero on them. Migration was verified against OAS
+0.20.x; OAS 0.21.x scopes may lock the OAS v2.0.0 package line, which the OATS
+catalog does not carry, so run the dry run first.
+
+The 0.18 upgrade guarantee (existing v1 locks keep working) applies to
+OATS-named scopes only, never to OAS-named deployments.
+
+## Corrections ported from OAS
+
+- **Own-property config handling.** Config parsing and diagnostics ignore
+  inherited `Object.prototype` properties; YAML keys named `__proto__` are
+  refused with `unsafe-config-key`.
+- **Internal annotations cannot arrive from disk.** Underscore-prefixed engine
+  annotations are stripped from every manifest and soul read.
+- **Config writes fail closed.** Values or keys that would change the shape of
+  a written config are refused with `unsafe-config-value` or
+  `unsafe-config-key`. `oats init` and the first `oats use` or `oats type add`
+  in a fresh scope refuse a directory basename that cannot be stored as one
+  YAML scalar.
+- **Typed CLI failures.** `unsafe-config-key`, `unsafe-config-value`, and
+  `E_NO_CONFIG` render as one `oats:` line or one `--json` envelope.
+  Configless `oats use` reports `E_NO_CONFIG` with the `oats init --raw` remedy.
+- **Scope-exact doctor and trust.** `oats doctor` and trust judge each artifact
+  against the lock of the scope that installed it, ending false `invalid-lock`
+  and orphan reports.
+- **Desktop parity.** The Desktop deployment reader accepts and refuses the
+  same lock shapes as the kernel.
+- **Package payloads are not deployment scopes.** Bare `oats install` and
+  `oats migrate --official --recursive` skip config templates under a package
+  manifest.
 
 ## The turn record: `oats capture | recall | setup`
 
-The kernel now carries the turn record (`packages/record`): every
-conversation an agent has, Claude Code, pi, and Codex sessions plus aw
-mail and chat logs, captured as content-addressed turns in append-only,
-owner-write journals, searchable with exact provenance.
+The kernel carries the turn record: Claude Code, Pi, and Codex sessions plus
+aw mail and chat logs, captured as content-addressed turns in append-only
+journals and searchable with provenance.
 
 ```bash
-oats setup            # install capture hooks + a background watcher, idempotent
+oats setup            # install capture hooks and a background watcher
 oats capture          # one reconciliation pass (--watch, --status, --install-hint)
-oats recall <query>   # full-text search over everything captured, with provenance
+oats recall <query>   # full-text search with provenance
 ```
 
-The normative v1 format specification and its cross-language conformance
-vectors ship inside the package (`packages/record/docs/`,
-`packages/record/test/vectors/`).
-
-`oats experimental <dress|spawn|segments|mind>` exists in the repo checkout
-only, and deliberately never in this published package: the synthesis layer
-above the record is unproven by design, and its absence from the tarball is
-exactly its status.
+The v1 format specification and conformance vectors ship in the package
+(`packages/record/docs/`, `packages/record/test/vectors/`).
 
 ## Contract changes
 
-- `oats migrate --dry-run --json` on a scope where `oas-config.yaml` /
-  `oas-lock.json` are visible now returns `ok: false` with code
-  `oas-scope-unmigrated` instead of `ok: true` with an empty plan. OATS-named
-  scopes see no change.
+- `oats migrate --dry-run --json` on a scope with visible OAS files returns
+  `ok: false` with code `oas-scope-unmigrated`.
 - `oats doctor --json` gains `oasScopes`, `oasRemedy`, and per-package
-  scope-exact rows. The exit code stays 0; automation gating on deployment
-  health should key on the fields, not the exit code.
-- Guided migration plan rows gain `migratesTo`, and applied rows gain
-  `migratedTo`: the package catalog's capability aliases may carry a rename
-  (`"oas.okf": { "package": "oats.okf", "capability": "oats.okf" }`). All
-  seven ids published by OAS 0.20 are mapped.
-- New typed failures: `unsafe-config-key`, `unsafe-config-value`, and
-  `E_NO_CONFIG` from configless `oats use`. Scripts matching error text
-  should match the typed codes.
-- `oats init` and first-write commands refuse directory basenames that
-  cannot be stored as one YAML scalar (see above). Earlier releases wrote
-  such names verbatim.
+  scope-exact rows; the exit code stays 0.
+- Guided migration plan rows gain `migratesTo`, applied rows `migratedTo`;
+  all seven ids published by OAS 0.20 are mapped.
+- New typed failures `unsafe-config-key`, `unsafe-config-value`, and
+  `E_NO_CONFIG`.
+- `oats init` and first-write commands refuse unstorable directory basenames.
 
 ## Desktop
 
-OATS Desktop 0.22.0 accepts a kernel with `desktopApi: 1` in the semver
-range `>=0.22.0 <0.23.0`, probing `@awebai/oats`. The old OAS Desktop
-probes for `@oas-framework/oas`; the old app and this CLI are mutually
-invisible, so upgrade the CLI and the Desktop together. macOS arm64/x64
-and Linux x64 installers are published on the GitHub Release with
-checksums and provenance; macOS builds are ad-hoc signed (not notarized).
-See [docs/desktop.md](../desktop.md) for the Gatekeeper steps.
-
-## Repository
-
-- A `LICENSE` file (MIT) now ships with the kernel; `package.json` had
-  declared MIT without one.
-- Root `npm test` is correct on a checkout without the Desktop's own
-  dependencies: it runs the Desktop suites when they are installed and
-  otherwise prints an unmissable notice with the install command.
-- A runnerless release lane (`scripts/release-lane.mjs`) mirrors the release
-  workflow off GitHub Actions, so registry publish and hosted assets never
-  depend permanently on a runner.
-
-## Not included
-
-- The OAS 0.21.0 **remote official catalog** (the kernel fetching
-  `package-catalog.json` from GitHub at resolution time). OATS resolves the
-  bundled catalog only. Held for a separate decision.
-- The `@oas-framework/*` packages are **not deprecated** by this release;
-  that action belongs to their maintainer.
+OATS Desktop 0.22.0 accepts a kernel with `desktopApi: 1` in
+`>=0.22.0 <0.23.0`, probing `@awebai/oats`. The old OAS Desktop and this CLI
+cannot see each other, so upgrade both together. macOS builds are ad-hoc
+signed, not notarized; see [the Desktop guide](../desktop.md).
+
+## Also
+
+- The kernel ships a `LICENSE` file (MIT).
+- Root `npm test` runs the Desktop suites when their dependencies are
+  installed and otherwise prints the install command.
+- The OAS 0.21.0 remote official catalog is not included; OATS resolves the
+  bundled catalog only.
 
 ## Install
 
@@ -176,5 +110,4 @@ npm install -g @awebai/oats@latest
 pi install npm:@awebai/oats-pi@latest
 ```
 
-Install matching kernel/adapter versions; they publish in lockstep from
-one tag.
+Install matching kernel and adapter versions.