@awebai/oats 0.22.0

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

@@ -0,0 +1,63 @@
+# OATS v0.18.3
+
+One public release, built from one tag: `@awebai/oats@0.18.3`,
+`@awebai/oats-pi@0.18.3`, and **OATS Desktop 0.18.3** (attached to this
+GitHub Release).
+
+This is a patch release: corrected macOS installers. There are no CLI or
+kernel behavior changes; CLI compatibility is unchanged
+(Desktop API v1, `>=0.18.0 <0.19.0`).
+
+## Fixed: macOS installers (arm64 and x64)
+
+The v0.18.2 macOS artifacts were defective: the arm64 app carried an
+incomplete linker-generated ad-hoc signature that failed strict bundle
+verification (`code has no resources but signature indicates they must be
+present`), which made macOS falsely report the app as **"damaged"**; the
+x64 app was unsigned.
+
+Both macOS `.app` bundles now receive **complete, valid ad-hoc signatures**,
+covering nested Electron helpers and frameworks, and pass strict deep
+verification:
+
+```bash
+codesign --verify --deep --strict --verbose=2 "OATS Desktop.app"
+```
+
+CI gates this exact strict deep codesign / sealed-resource verification on
+both mac architectures before any artifact is uploaded or published — a
+regression of this signature class cannot ship again.
+
+### What this is (and is not)
+
+The installers are **ad-hoc signed — not Developer ID signed and not
+notarized**. Ad-hoc signatures carry no identified-developer identity, so
+Gatekeeper may still require the first launch via right-click → **Open**
+(or **Open Anyway** in System Settings → Privacy & Security). The false
+"damaged" error is fixed; normal identified-developer behavior is not
+claimed.
+
+Existing v0.18.2 release assets, checksums, and provenance are unchanged.
+
+## Downloads
+
+| Platform | Artifacts |
+| --- | --- |
+| macOS arm64 (Apple Silicon) | DMG + ZIP |
+| macOS x64 (Intel) | DMG + ZIP |
+| Linux x64 | AppImage + DEB |
+
+Verify with `SHA256SUMS.txt`; GitHub build-provenance attestations are
+published for all assets.
+
+**Windows and Linux arm64 are not supported in 0.18.x.**
+
+## Install / update
+
+```bash
+npm install -g @awebai/oats@0.18.3
+```
+
+The pi bridge `@awebai/oats-pi` publishes in lockstep. Desktop downloads
+are the assets on this release; the full install/support guide is
+[docs/desktop.md](https://github.com/awebai/oats/blob/main/docs/desktop.md).

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

@@ -0,0 +1,65 @@
+# OATS v0.18.4
+
+One public release, built from one tag: `@awebai/oats@0.18.4`,
+`@awebai/oats-pi@0.18.4`, and **OATS Desktop 0.18.4** (attached to this
+GitHub Release).
+
+This patch release improves the Desktop experience. There are no CLI or
+kernel behavior changes; CLI compatibility remains Desktop API v1
+(`>=0.18.0 <0.19.0`).
+
+## Desktop UX fixes
+
+### Spawn status is responsive and truthful
+
+The Spawn view now retries the CLI capability probe when startup catches the
+backend before that probe has settled. While capability is still unknown, the
+button reports a pending check instead of appearing silently dead; an actual
+missing or incompatible CLI still produces actionable guidance.
+
+### Better chat editing and copying
+
+- **Shift+Enter** inserts a newline in chat input.
+- Chat transcripts remain selectable and copyable across renderer updates.
+- The application Edit menu is installed only on macOS, preserving expected
+  terminal Ctrl chords on Linux and Windows.
+
+### Instances is a first-class workspace view
+
+Instances now appears directly in the navigation and command palette. The
+roster groups instances by repository and agent family, supports collapsible
+group headers, and provides ordering controls. The selected ordering is stored
+per canonical workspace, so switching workspaces does not leak one workspace's
+preference into another.
+
+### Terminal tabs restore per workspace
+
+The active terminal tab is remembered independently for each workspace and is
+restored when switching back.
+
+## Downloads
+
+| Platform | Artifacts |
+| --- | --- |
+| macOS arm64 (Apple Silicon) | DMG + ZIP |
+| macOS x64 (Intel) | DMG + ZIP |
+| Linux x64 | AppImage + DEB |
+
+The macOS artifacts are ad-hoc signed — not Developer ID signed and not
+notarized. First launch may still require right-click → **Open** (or **Open
+Anyway** in System Settings → Privacy & Security).
+
+Verify downloads with `SHA256SUMS.txt`; GitHub build-provenance attestations
+are published for all assets.
+
+**Windows and Linux arm64 are not supported in 0.18.x.**
+
+## Install / update
+
+```bash
+npm install -g @awebai/oats@0.18.4
+```
+
+The pi bridge `@awebai/oats-pi` publishes in lockstep. Desktop downloads are
+the assets on this release; the full install/support guide is
+[docs/desktop.md](https://github.com/awebai/oats/blob/main/docs/desktop.md).

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

@@ -0,0 +1,66 @@
+# OATS v0.18.5
+
+One public release, built from one tag: `@awebai/oats@0.18.5`,
+`@awebai/oats-pi@0.18.5`, and **OATS Desktop 0.18.5** (attached to this
+GitHub Release).
+
+This corrective patch removes an out-of-scope navigation surface introduced
+in v0.18.4 and fixes two terminal interaction failures. There are no CLI or
+kernel behavior changes; CLI compatibility remains Desktop API v1
+(`>=0.18.0 <0.19.0`).
+
+## Corrected: no separate Instances stage
+
+v0.18.4 incorrectly added an **Instances** navigation-rail destination with a
+second roster sidebar. That surface was not part of the requested Desktop UX.
+It has been removed: Active overview and Soul roster are again the only main
+stages, while the existing permanent sidebar remains the place for instance
+navigation.
+
+The v0.18.4 spawn-status improvements and per-workspace terminal-tab restore
+remain. The repo/family grouping helpers remain available for the separately
+owned existing-sidebar work, but this release does not move the removed
+stage's grouping/sort UI into another surface.
+
+## Fixed: Shift+Enter in terminal input
+
+A physical Shift+Enter press can produce keydown, keypress, and keyup events in
+xterm.js. v0.18.4 handled only keydown, so the later keypress could still emit
+Return and immediately submit after inserting a newline. Desktop now suppresses
+the entire chord and writes exactly one newline on keydown.
+
+## Fixed: copying from terminal tabs
+
+With tmux mouse mode enabled, a plain drag belongs to tmux rather than xterm's
+local selection. Desktop now enables the platform modifier that forces local
+selection:
+
+- macOS: **Option+drag**, then Cmd+C or right-click → Copy
+- Linux/Windows: **Shift+drag**, then the platform copy command
+
+## Downloads
+
+| Platform | Artifacts |
+| --- | --- |
+| macOS arm64 (Apple Silicon) | DMG + ZIP |
+| macOS x64 (Intel) | DMG + ZIP |
+| Linux x64 | AppImage + DEB |
+
+The macOS artifacts are ad-hoc signed — not Developer ID signed and not
+notarized. First launch may still require right-click → **Open** (or **Open
+Anyway** in System Settings → Privacy & Security).
+
+Verify downloads with `SHA256SUMS.txt`; GitHub build-provenance attestations
+are published for all assets.
+
+**Windows and Linux arm64 are not supported in 0.18.x.**
+
+## Install / update
+
+```bash
+npm install -g @awebai/oats@0.18.5
+```
+
+The pi bridge `@awebai/oats-pi` publishes in lockstep. Desktop downloads are
+the assets on this release; the full install/support guide is
+[docs/desktop.md](https://github.com/awebai/oats/blob/main/docs/desktop.md).

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

@@ -0,0 +1,87 @@
+# OATS v0.18.6
+
+One public release, built from one tag: `@awebai/oats@0.18.6`,
+`@awebai/oats-pi@0.18.6`, and **OATS Desktop 0.18.6** (attached to this
+GitHub Release).
+
+This release adds explicit spawn-time agent relations, cluster-first Desktop
+navigation, and user-editable Desktop keyboard shortcuts. Desktop CLI API v1
+remains the compatibility boundary (`>=0.18.0 <0.19.0`), but related spawns
+require the new 0.18.6 CLI.
+
+## New: explicit agent relations
+
+A new instance can declare what it is to an existing instance:
+
+```bash
+oats spawn <agent> --relation child|sibling|parent --relative-to <instance>
+```
+
+- **child** works for and nests under the anchor;
+- **sibling** joins the anchor as a peer;
+- **parent** oversees the anchor and takes its previous lineage position;
+- no relation flags means **unrelated** and top-level.
+
+`--parent <instance>` remains supported as child-relation shorthand.
+Same-named instances can exist in different agent roots, so
+`--relative-root <agents-root>` can qualify an anchor. Ambiguous or shadowed
+lineage fails closed with `E_RELATIVE_AMBIGUOUS` rather than linking or acting
+on the wrong instance. Attached agents remain children of the verified owner
+of their shared work tree.
+
+Retiring an instance repairs ordinary parent and sibling links that point to
+it. OATS intentionally keeps this as sparse current-state metadata rather than
+a lineage database: concurrent parent spawns against one anchor are
+last-writer-wins, and a multi-instance retirement repair is sequential rather
+than a crash-atomic transaction.
+
+## Desktop: cluster-first agent surfaces
+
+The Active overview and permanent instance sidebar now group related agents as
+clusters built from parent and sibling links. Independent instances remain in
+a quieter separate strip. Duplicate instance names across repositories remain
+distinct throughout grouping, filtering, collapse state, terminal routing,
+Brain actions, and privileged instance-addressed API calls.
+
+The Spawn surface now uses one accessible modal with purpose, task, relation,
+anchor, runtime, and model controls. Relation controls stay visible but fail
+closed when the installed CLI predates 0.18.6; unrelated spawning remains
+available across the existing Desktop API v1 compatibility range.
+
+## Desktop: editable keyboard shortcuts
+
+Desktop actions now use a central keybinding engine with persisted user
+overrides and explicit unbinding. Open the shortcuts editor with **Mod+,**.
+The editor covers app, stage, tab, sidebar, terminal typography, and
+view-local actions, with live shortcut labels and conflict warnings.
+
+Terminal shortcut interception happens before PTY writes for an explicit
+action allowlist. View-local shortcuts remain confined to their focused
+surface, and spawn-modal controls keep ownership of their keys.
+
+## Downloads
+
+| Platform | Artifacts |
+| --- | --- |
+| macOS arm64 (Apple Silicon) | DMG + ZIP |
+| macOS x64 (Intel) | DMG + ZIP |
+| Linux x64 | AppImage + DEB |
+
+The macOS artifacts are ad-hoc signed — not Developer ID signed and not
+notarized. First launch may still require right-click → **Open** (or **Open
+Anyway** in System Settings → Privacy & Security).
+
+Verify downloads with `SHA256SUMS.txt`; GitHub build-provenance attestations
+are published for all assets.
+
+**Windows and Linux arm64 are not supported in 0.18.x.**
+
+## Install / update
+
+```bash
+npm install -g @awebai/oats@0.18.6
+```
+
+The pi bridge `@awebai/oats-pi` publishes in lockstep. Desktop downloads are
+the assets on this release; the full install/support guide is
+[docs/desktop.md](https://github.com/awebai/oats/blob/main/docs/desktop.md).

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

@@ -0,0 +1,186 @@
+# OATS v0.19.0
+
+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.
+
+## 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
+```
+
+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>
+```
+
+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 and workspace setup
+
+Packages may ship complete reference `oats-config.yaml` profiles. Adoption is
+explicit and produces 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
+
+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.
+
+Every runtime and lifecycle hook receives the absolute `OATS_INSTANCE_HOME`.
+Generated instructions distinguish the two operational surfaces:
+
+- 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.
+
+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, runtime requirements, and safe rollback
+
+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.
+
+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.
+
+## 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 |
+
+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.
+
+## Install or update
+
+```bash
+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.

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

@@ -0,0 +1,24 @@
+# OATS v0.19.1
+
+Corrective patch for the v0.19.0 marketplace compatibility bridge.
+
+- Restores npm-hoisted aweb skills for existing v1 `oats.aweb` installations.
+  Marketplace declarations still anchor at their declaring capability first;
+  when npm hoists a declared dependency, OATS resolves the equivalent path under
+  the installed kernel root with the same realpath containment checks.
+- Keeps valid older installed+locked marketplace capabilities usable across a
+  kernel upgrade while still failing closed when the installed copy and lock
+  disagree.
+- 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.
+
+Install matching kernel and Pi adapter versions:
+
+```bash
+npm install -g @awebai/oats@0.19.1
+pi install npm:@awebai/oats-pi@0.19.1
+```

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

@@ -0,0 +1,32 @@
+# OATS v0.19.2
+
+Official package catalog and migration activation patch.
+
+The kernel now bundles immutable catalog entries for:
+
+- `oats.okf@v1.4.1`
+- `oats.aweb@v1.8.0`
+- `oats.authoring@v1.0.0`
+- `oats.jira@v1.0.0`
+- `oats.linear@v1.0.0`
+- `oats.dev@v1.0.0`, which exports `oats.review@1.2.0`
+
+Each catalog entry selects the repository's contained `oats-package/` payload.
+Short-id installs now prefer these distribution packages over the legacy bundled
+capability marketplace. Existing v1 locks and installed artifacts remain
+supported until the user explicitly runs the guided migration:
+
+```bash
+oats migrate --official --recursive --dry-run --dir <team-root>
+oats migrate --official --recursive --dir <team-root>
+```
+
+This patch also preserves the v0.19.1 marketplace compatibility bridge for
+npm-hoisted aweb skills.
+
+Install matching versions:
+
+```bash
+npm install -g @awebai/oats@0.19.2
+pi install npm:@awebai/oats-pi@0.19.2
+```

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

@@ -0,0 +1,16 @@
+# OATS v0.19.3 (unpublished)
+
+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.

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

@@ -0,0 +1,12 @@
+# OATS v0.19.4
+
+Release-pipeline follow-up for the documentation refresh.
+
+- Makes Desktop server tests independent of a repository-owned deployment lock
+  by constructing their capability-agent deployment explicitly.
+- Allocates ephemeral loopback ports instead of choosing a collision-prone
+  pseudo-random development port.
+- Keeps live-checkout parity diagnostics tolerant of deployment-local package
+  skew while retaining the unconditional isolated parity proof.
+
+No runtime contract changes from v0.19.2.

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

@@ -0,0 +1,89 @@
+# OATS v0.20.0
+
+OATS v0.20.0 is a breaking pre-1.0 release. The framework release includes
+`@awebai/oats@0.20.0`, `@awebai/oats-pi@0.20.0`, and OATS Desktop
+0.20.0.
+
+This release finalizes capability materialization and config templates. It
+replaces the earlier, unadopted transitional v2 package shape without changing
+`lockfileVersion: 2`.
+
+## Revised lockfile v2
+
+The final v2 lock separates package provenance from installed capability
+identity.
+
+- `packages` records the source, exact commit, selected package root, payload
+  integrity, and package dependencies.
+- `capabilities` records each materialized artifact, its provider package,
+  source path, artifact integrity, and executable trust.
+
+A package is now a transport and update unit. Each exported capability is an
+installed, activatable, and trustable unit. OATS materializes it under
+`.agents/capabilities/installed/<capability-id>/`.
+
+Every newly authored package must give each capability a dedicated,
+self-contained root. Declared resources and symlinks must stay inside that
+root. The package root is not kept as an installed package store.
+
+## Config templates remain local policy
+
+Canonical package manifests use `configTemplates`. Their template files live
+under `config-templates/`.
+
+`oats install` does not apply a template. Adoption is explicit through
+`oats init --package` or `oats config adopt`. The adopted file is an ordinary,
+editable `oats-config.yaml`.
+
+Each scope has at most one active config and one adopted base. OATS records the
+base under `.agents/config-templates/adopted/`. The `oats config diff`, `sync`,
+`sync --reset`, and `adopt` commands use that base for three-way plans. Package
+updates do not overwrite local config edits.
+
+## Migration and trust
+
+Existing valid v1 locks from 0.18 remain supported. Migration is explicit and
+converts a scope directly to the final revised v2 shape.
+
+Migration is atomic for each scope. If a mixed scope contains entries that must
+be retained, OATS holds the whole scope unchanged. It does not partly rewrite
+the lock. Executable trust never transfers silently to a materialized
+capability.
+
+The earlier transitional `lockfileVersion: 2` shape is unsupported. It was not
+adopted as a release contract, so this release provides no migration for it.
+Back up the scope and reacquire its package state through supported CLI paths.
+Do not hand-edit the lock.
+
+See [Distribution packages](../packages.md) for the lock, adoption, and
+migration details.
+
+## Desktop compatibility
+
+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
+npm install -g @awebai/oats@0.20.0
+pi install npm:@awebai/oats-pi@0.20.0
+```
+
+Keep the kernel, Pi adapter, and Desktop on matching release versions.