@awebai/oats 0.22.0

package/docs/desktop.md

@@ -0,0 +1,187 @@
+# OATS Desktop
+
+The OATS Desktop app is the control panel for OATS deployments: the agent
+roster and hierarchy, brain/markdown/task/state views, and real terminal
+attach to running agents' tmux sessions. With a compatible `oats` CLI
+installed it can also spawn agents from the Soul roster.
+
+## Install
+
+Download the installer for your platform from the
+[GitHub Release](https://github.com/awebai/oats/releases) assets:
+
+| Platform | Artifacts | Notes |
+| --- | --- | --- |
+| macOS arm64 (Apple Silicon) | DMG + ZIP | ad-hoc signed — see below |
+| macOS x64 (Intel) | DMG + ZIP | ad-hoc signed — see below |
+| Linux x64 | AppImage + DEB | requires `tmux` |
+
+**Windows and Linux arm64 are not supported in 0.19.x.**
+
+Verify downloads against the release's `SHA256SUMS.txt`. GitHub
+build-provenance attestations are published for every asset
+(`gh attestation verify <file> --repo awebai/oats`).
+
+### macOS: ad-hoc signed build
+
+The macOS installers are **ad-hoc signed — not Developer ID signed and not
+notarized** (no Apple signing credentials exist; nothing about this release
+claims identified-developer trust). The app bundle carries a complete,
+valid ad-hoc signature — every nested helper and framework is signed and
+the bundle passes `codesign --verify --deep --strict` — but ad-hoc
+signatures carry no identity Gatekeeper can trust, so it will still block
+the first launch of a downloaded (quarantined) copy:
+
+- Right-click the app → **Open** → **Open** (once; subsequent launches are
+  normal), or
+- `xattr -dr com.apple.quarantine "/Applications/OATS Desktop.app"`.
+
+### Linux: prerequisites
+
+`tmux` is required for the integrated terminal — the app attaches to your
+agents' tmux sessions. Roster, brain, Markdown and CLI features work without
+it, but opening a terminal will fail until tmux is installed. The DEB
+declares the dependency; for the AppImage install it yourself
+(`apt install tmux`, `dnf install tmux`, …) and verify with `tmux -V`.
+
+### The `oats` CLI (for Spawn)
+
+Reads — roster, hierarchy, brain, files, terminals — work with no CLI at
+all. Spawning agents runs through an installed `oats` CLI with Desktop API
+v1:
+
+```bash
+npm install -g @awebai/oats
+```
+
+Desktop and the CLI publish in lockstep from one tag, so the matching CLI is
+the one with **this Desktop's own version** — the app's degradation card
+shows that exact `npm install -g @awebai/oats@<version>` command, and
+copying it from the card is the reliable route.
+
+Each Desktop accepts a band of released CLI versions around its own —
+prereleases are never accepted — and individual features may sit behind a
+higher floor (spawn-time agent relations do; the relation controls fail closed
+naming the version they need). **The app states both**: the degradation card
+shows the accepted range and the exact install command, and the relation note
+names its floor. This guide deliberately does not repeat those numbers — it is
+rolling documentation and would go stale against the app; the versioned
+[release notes](release-notes/) record the band for each release, and
+[docs/desktop-cli-api.md](desktop-cli-api.md) is the contract of record beside
+the code that enforces it. The app discovers the CLI automatically
+(your PATH, the npm global prefix, a login shell) and re-probes on launch,
+app focus, and Retry. Until a compatible CLI is verified, the Soul roster's
+**Spawn** buttons are disabled behind one card showing what was detected,
+what is required, **Choose oats…** (pick the binary yourself — the choice
+persists), **Retry**, a docs link, and the copyable install command. The
+app never installs anything itself. (Memory harvest runs through the same
+CLI boundary in the backend; it has no dedicated button in this release.)
+
+The probe/mutation contract is specified in
+[desktop-cli-api.md](desktop-cli-api.md).
+
+## Opening a workspace
+
+The app starts on the directory it was launched with (its own folder by
+default). To view a deployment, open the workspace switcher in the sidebar
+and choose **Add workspace → Browse**, then point it at an OATS workspace —
+a directory containing `agents/`, or `local-agents/` for machine-local
+souls, or a team scope whose `oats-config.yaml` declares `team:`. Team scopes
+show every member repo's agents under one roster with a workspace switcher.
+Added workspaces are remembered and offered as suggestions next time.
+
+Local souls (uncommitted, machine-local agents under `local-agents/`) are
+first-class: they appear in the roster with a `local` chip, their brains
+and knowledge render, and they spawn like any other soul. Launch flags for
+scripted use: `--dir <workspace>` and `OATS_DESKTOP_PORT`.
+
+## Migrating from the web panel / TUI pane
+
+0.18.2 removes the legacy `oats.web` browser panel, `oats pane`, and the
+`@awebai/oats/control-pane` export. The Desktop app replaces all
+three. Migration:
+
+1. Update the CLI everywhere: `npm install -g @awebai/oats`.
+2. Run `oats doctor` at each workspace scope and follow its guidance to
+   remove stale `oats.web` config entries, locks, and installed artifacts.
+3. Install the Desktop app (above) and open your workspace.
+
+The full breaking-change list is in the
+[v0.18.2 release notes](release-notes/v0.18.2.md).
+
+## Security posture
+
+- The bundled backend binds **127.0.0.1 only** and guards against DNS
+  rebinding (loopback Host on every request, loopback Origin on POSTs).
+  Do not expose it: it can type into your agent terminals.
+- The app never imports framework code from a checkout and accepts no
+  framework-root environment override; deployments are read with an
+  app-owned read-only reader. All lifecycle mutations go through the
+  installed CLI via `execFile` with an absolute binary — never a shell.
+- Task text for spawns travels via an owner-only (0600) tempfile, never
+  argv. Harvest always runs in the server-verified instance home.
+- Workspace content is treated as untrusted: symlinked directories never
+  widen the file API, and capability packages cannot read outside their
+  own tree.
+
+## Troubleshooting
+
+| Symptom | Cause / fix |
+| --- | --- |
+| "Compatible oats CLI required" card | No CLI, or a version outside the range the card itself states. Copy the card's install command, or **Choose oats…** to point at the right binary; **Retry** re-probes. Spawn is disabled until a compatible CLI is verified. |
+| Spawn disabled, no card | The probe hasn't settled yet (transient, resolves in ms). If it persists, the backend is unreachable — restart the app. |
+| Terminals fail to open ("could not attach") | tmux missing, or no live session for that instance. Install tmux (`tmux -V`); check `tmux ls`. |
+| Can't select/copy text in a terminal tab | The terminal runs with tmux mouse handling, so a plain drag scrolls/passes through. Hold **Option** (macOS) or **Shift** while dragging to make a local selection, then copy (Cmd+C / right-click → Copy). |
+| macOS "app is damaged / can't be opened" | Ad-hoc-signed (not notarized) build + quarantine. Right-click → Open, or clear the quarantine attribute (above). If it persists, verify the bundle: `codesign --verify --deep --strict --verbose=2 "/Applications/OATS Desktop.app"` — a non-zero exit means a broken artifact, report it. |
+| Roster empty | The opened directory isn't an OATS workspace (needs `agents/` or `local-agents/`, or a team scope). Use the workspace switcher → Add workspace to select the right root. |
+
+For bugs, attach the terminal output of the app (`OATS Desktop` prints
+server and CLI-discovery logs to stdout) and your platform/arch.
+
+## Release verification ownership
+
+Installer CI gates what headless runners can prove reliably for every
+published platform/architecture: electron-builder completes, the expected
+DMG/ZIP/AppImage/DEB artifacts exist, both packaged macOS `.app` bundles
+pass strict deep codesign verification of their complete ad-hoc signatures
+(`codesign --verify --deep --strict`), node-pty's packaged `spawn-helper` is
+executable, and node-pty loads and spawns under the packaged Electron ABI.
+The macOS x64 leg cross-builds on macos-14 and installs Rosetta 2 so that its
+x64 Electron + node-pty ABI probe really executes; a wrong-architecture
+native module fails that leg.
+
+CI does **not** gate the packaged GUI launch: ad-hoc-signed, non-notarized
+Electron apps do not
+have a reliable interactive windowserver in headless CI. Post-publish launch
+acceptance is therefore owned by the operator/maintainer, using the actual
+released installers (not a source checkout):
+
+1. Verify the asset checksum/attestation, install it outside the source tree,
+   and on macOS use right-click → **Open** for the Gatekeeper step (ad-hoc
+   signatures carry no identified-developer identity).
+2. Launch OATS Desktop and open a real deployment; verify roster, brain and
+   Markdown reads.
+3. Attach an existing tmux terminal, confirm input/output, and close the tab
+   (the durable tmux window must survive).
+4. Verify the released global CLI is detected and Spawn is enabled; hide or
+   mismatch the CLI and confirm reads/terminal still work while Spawn disables
+   with recovery guidance.
+5. Repeat per published architecture where hardware is available. In
+   particular, launch-check macOS x64 on an Intel Mac if one is available;
+   CI's Rosetta ABI probe is the native-module proof, while this is the actual
+   shipped-installer/user-launch proof.
+
+Record the installed version, platform/architecture and outcome in the
+release verification notes. This post-publish check is acceptance — it does
+not weaken the pre-publish build/inventory/ABI gates.
+
+## Building from source
+
+Developer docs live in [`packages/desktop/README.md`](../packages/desktop/README.md)
+(run, architecture, view contract) — packaging is `npm run dist`
+(electron-builder; macOS ad-hoc signed — not Developer ID, not notarized —
+certificate auto-discovery disabled) and
+`npm run dist:smoke` verifies the packed artifact. Build/release CI uses the
+marked build-verify mode (inventory + strict codesign verification +
+node-pty ABI, no GUI launch); a local
+interactive run may also exercise the launch phase.

package/docs/implementation.md

@@ -0,0 +1,282 @@
+# Implementation reference
+
+The reference implementation publishes two npm packages:
+
+- **`@awebai/oats`**: runtime-neutral kernel, universal `oats` CLI,
+  bootstrap skills, instruction sources, and the official capability marketplace.
+- **`@awebai/oats-pi`**: minimal pi adapter for instance-local resource
+  exposure and memory session events. It registers no agent tools.
+
+Claude instances consume the generated standard files directly through the
+instance home's `.claude/` and `CLAUDE.md` symlinks. OATS does **not** redirect
+Claude's config home: an isolated one cannot authenticate, and the operator's
+own Claude configuration is deliberately left enabled.
+
+## Repository layout
+
+| Path | Purpose |
+|---|---|
+| `lib/core.mjs` | Souls, instances, config/target resolver, capability discovery, composition, locks/trust, hooks. |
+| `bin/oats.mjs` | Agent lifecycle, config, acquisition/trust/activation, doctor, and operational command dispatch. |
+| `capabilities/` | Bundled additive packages and layer integrations, each with `oats.json`. |
+| `skills/` | Kernel/bootstrap and package-authoring skills. |
+| `injects/` | Kernel and work-mode instruction sources. |
+| `packages/pi/` | Thin pi adapter. |
+| `packages/desktop/` | OATS Desktop — the Electron control panel and its bundled zero-dependency backend server (private, not published). |
+| `test/` | Capability resolver/composition/security lifecycle tests. |
+| `agents/` | The framework's own portable expert souls. |
+
+Capability discovery has one layout: each config scope's `.agents/capabilities/` split into
+`installed/` (acquired, locked, gitignored, restorable via bare `oats install`)
+and `owned/` (authored at that scope, config-owned trusted; committed where
+the scope is a git repo, plain scope-durable files elsewhere).
+
+The live control panel is the OATS Desktop app (`packages/desktop/`): an
+Electron shell over a bundled zero-dependency localhost server that uses
+plain OATS metadata/files plus git and tmux; no pi APIs cross into the
+feature, so the same surface works for pi and Claude instances. (`oats pane`
+and the `oats.web` browser panel were retired in its favor.)
+
+## Instance layout
+
+```text
+<agents-root>/<agent>/
+  soul/
+    soul.yaml
+    AGENTS.md                 # canonical role instructions
+    CLAUDE.md -> AGENTS.md
+    skills/                   # soul-private skills
+  instances/<instance>/
+    soul -> ../../soul
+    AGENTS.md                 # generated composition (regular file)
+    CLAUDE.md -> AGENTS.md
+    .agents/skills/           # exact materialized set
+    .claude/skills -> ../.agents/skills
+    work/
+    TASK.md
+    instance.json             # capabilities, skills, instruction sources, lifecycle metadata
+```
+
+Knowledge integration hooks may add memory files. The kernel does not assume
+their names.
+
+## Resolution
+
+`configChain(context)` loads `oats-config.yaml` from closest scope outward.
+`resolveCapabilities(context, soulName)`:
+
+1. resolves explicit group definitions;
+2. collects matching global/group/soul bindings;
+3. composes settings by target specificity then config closeness;
+4. applies explicit enable/exclusion;
+5. validates equal-specificity conflicts, IDs, command namespaces, lock
+   integrity, and skill/layer collisions; and
+6. returns deterministic active capability records with provenance.
+
+`resolveOatsConfig` maps active packages declaring `layer` into the exclusive
+knowledge/messaging/tasks slots. `layers.<layer>: none` explicitly suppresses
+an inherited slot and remains distinct from absence.
+
+## Spawn composition
+
+`spawnInstance` resolves against the soul's repository and soul name. It:
+
+0. resolves and validates WHERE the home will be created, before any side
+   effect: the destination must be the agent directory's own `instances/`
+   child, that agent directory must lie inside this deployment, and a linked
+   worktree maps to the primary checkout — otherwise `E_NO_CANONICAL_ROOT` and
+   nothing is created. The check is repeated on the created directory before
+   anything is written into it. See
+   [souls-and-instances.md](souls-and-instances.md#deployment-prerequisite-the-agents-directory-must-be-operator-owned)
+   for the deployment prerequisite this rests on;
+1. calls `composeInstanceAgentsMd` without writing the soul;
+2. writes generated `AGENTS.md` and canonical compatibility symlinks;
+3. copies kernel + soul + active package skill trees into real directories in
+   one instance-local root, failing duplicate names unless `skill-overrides`
+   chooses a source;
+4. creates the selected work topology;
+5. runs active hooks in deterministic order; and
+6. records capabilities, settings, trust, skill names/sources, instruction
+   files, hooks, capability metadata, and forward-only spawn lineage in
+   `instance.json`.
+
+Pi launches with `--no-skills --skill <instance-home>/.agents/skills
+--no-context-files --no-prompt-templates --append-system-prompt
+<instance-home>/AGENTS.md`. The OATS-managed skill set is exactly the composed
+one: no user, project, ancestor or package skill catalogs. It is not a claim
+that nothing else can reach the session — extensions stay ambient (below), and
+what they contribute stays with them.
+
+After the canonical soul and kernel text, every generated `AGENTS.md` states the
+runtime-neutral **home/work boundary** (`injects/instance-boundary.md`) — for
+every work mode and for capability service agents alike — immediately before the
+work-mode block it frames: `<instance-home>` (`$OATS_INSTANCE_HOME`) holds the
+brain, task, provenance and working state, and is where OATS operational/lifecycle
+commands are run from — together with the commands of whatever capabilities are
+active, `aw` among them when aweb messaging is — since they resolve scope from
+the working directory (`--dir <path>` reaches another deliberately); the home's
+`soul` link is to be treated as read-only because writes through it bypass the
+branch and review path; and `<instance-home>/work` is the repository or workspace
+view where repository reading, editing, building, testing, git and commits
+happen. It bounds *repository* work rather than forbidding all output elsewhere —
+episodic state lives in the home, and a service agent's own artifacts (a report
+written to a temp file before mailing it) are its role's business. What each mode
+actually permits is the work-mode block's call, which follows immediately.
+
+`--no-context-files` also suppresses the instance's *own* composed `AGENTS.md`,
+so that is delivered explicitly; the work tree's `AGENTS.md` stays readable by
+the file tools — readable, not auto-injected.
+
+Pi **extensions stay ambient**: operators run cross-agent extensions (web
+search, output formatting) that every instance should keep, so OATS does not
+pass `--no-extensions`. The accepted residue is narrow but real — an
+extension's `resources_discover` hook can contribute skill paths that survive
+`--no-skills`. Today only the OATS bridge does that, and inside an instance it
+contributes that instance's own `.agents/skills`, leaving the composed set
+unchanged.
+
+Runtime packages that active capabilities declare (see
+[capabilities](capabilities.md)) are verified at spawn and recorded in
+`instance.json`; a missing one fails the spawn with the consent command to fix
+it, rather than starting an agent whose instructions promise a capability it
+does not have. OATS does not resolve their extension entry points — pi owns that
+resolution, including globs and conventional directories.
+
+Claude discovers the same set natively through the instance's `.claude/skills`
+symlink, and its composed instructions through `CLAUDE.md -> AGENTS.md`.
+
+Claude Code's **own configuration stays enabled**: user and project skills,
+plugins, settings and `CLAUDE.md` all resolve into an OATS session as they
+normally would. That is a deliberate product choice — those mechanisms are
+powerful and the operator decides whether to use them; a deployment that wants
+only the OATS-composed surface achieves it by configuring everything OATS-side.
+So OATS passes no `--setting-sources`, no exclusions, and no synthetic plugin.
+
+Measured behavior worth knowing when reasoning about an instance: project
+skills resolve from the working directory up to the **repository root**, so an
+instance homed inside a repository with its own `.claude/skills` sees those
+too. Project *settings* — hooks, plugins, permissions, custom agents — resolve
+from the instance home rather than from ancestors.
+
+Both runtimes record what they actually expose in `instance.json` under
+`composition.materialized.runtimePosture`: the OATS-composed set, what is
+curtailed, and what remains ambient. The deviation from strict composition is
+auditable rather than implied.
+
+## Instructions
+
+The generated order is:
+
+1. canonical soul content;
+2. kernel OATS block;
+3. local-soul block (local souls only);
+4. **home/work boundary block** — runtime-neutral, every mode and every kind;
+5. actual spawn work-mode block;
+6. active capability blocks in resolver order; and
+7. unconditional config blocks outermost to innermost.
+
+Every generated block carries its source path. `oats doctor --soul <name>` uses
+the same composer and prints/returns the final text. Config-dependent prose is
+never reconciled into committed souls.
+
+## Acquisition and trust
+
+External installation copies/clones one exact artifact and writes
+`oats-lock.json` with source, version/commit, and SHA-256 tree integrity. An
+existing destination is never pulled silently. Resolution rejects changed
+locked artifacts and unlocked installed/path packages.
+
+Executable package hooks, commands, and launch-environment authority are omitted
+until `oats trust <id>` marks the exact locked integrity approved. Bundled
+packages are framework-trusted.
+Packages under a scope's `owned/` subtree are config-owned. Anything under
+`installed/` requires a matching lock entry, so an acquired artifact cannot
+bypass executable trust by its directory location.
+
+Distribution packages generalize this: a package materializes each capability it
+exports into `.agents/capabilities/installed/<id>/`, each independently
+addressable and independently trusted at its own artifact integrity. There is no
+persistent package store. The `lockfileVersion: 2` lock records package
+provenance (`packages`) and materialized capability identity (`capabilities`)
+separately. See `docs/design/package-engine-contract.md` for the resolver/lock
+API and error taxonomy.
+
+## Hooks and scaffold ownership
+
+Only `soul-scaffold`, `spawn`, and `retire` manifest hooks are accepted.
+Spawn/scaffold use outer-scope then capability-ID order; retire reverses it.
+Each hook receives package identity/layer plus structured OATS environment and
+may emit a final JSON object containing `meta`, `brief`, `warning`, or `launch`.
+Only a spawn hook may add `env`; other lifecycle events reject it rather than
+silently discard it. Launch environment is string-only,
+size/control-character checked, owned by an unambiguous dotted capability
+vendor, and restricted to the manifest's exact trust-visible `environment`
+declaration. Capabilities that request this authority must use the stricter
+dotted ID form even though capabilities without environment authority retain
+the wider namespaced-ID compatibility contract. Explicit and automatic trust
+disclose the declaration before persisting authority. Known process-bootstrap
+names are denied in depth, not treated as an
+exhaustive authority list. Aggregation is deterministic, shell-quoted, and
+collision-fatal. It prefixes only the initial runtime command;
+values are persisted with that command, so the contract is for non-secret
+locators and broker endpoints, never bearer credentials or durable principal
+root keys. No restart/replay contract exists. A fatal environment contract error enters
+the required-spawn rollback transaction. It runs compensation in reverse,
+removes and verifies rollback-owned Git topology, and removes the home only
+when cleanup completed. Failed compensation or reported state with no retire
+hook uses the same retryable quarantine as every other incomplete spawn.
+
+Soul scaffolding snapshots files around each package hook and records new-file
+ownership in `.oats-scaffold-owners.json`. Overwriting canonical or another
+package's file restores the prior bytes and raises a conflict.
+
+## Commands
+
+Kernel/package-management commands are always available. Operational
+namespaces are discovered from manifest `command`, but dispatch verifies that
+`instance.json` or current soul resolution contains the package and that its
+locked executable surface is trusted.
+
+## Verification
+
+```bash
+npm test
+npm run check
+npm run check:pi
+npm run validate
+npm run validate:okf
+npm run pack:check
+npm run smoke:tarball
+```
+
+Pull-request CI runs this matrix on supported Node 22. `validate` compiles both
+public JSON schemas, validates clean-contract manifests, parses documented
+OATS config examples with the production parser, and checks maintainable public
+local links/anchors. `pack:check` dry-runs both npm packages and rejects missing
+runtime surfaces or leaked workspace/test state.
+
+The clean-room smoke test packs both packages, installs their tarballs outside
+the checkout, verifies the adapter resolves that installed kernel, runs
+`init`/`doctor`, and creates/retires a clean-contract scaffold while checking
+exact skills, generated instructions, canonical soul immutability, and
+metadata.
+
+One manual probe is required after every release and before 0.19.0 ships: from
+the **published** kernel (not a checkout), install `oats.authoring` into a fresh
+scope, activate it for a framework-author soul, and spawn that soul. The spawn
+must succeed with `integration-authoring`, `skill-craft`, and `soul-craft`
+materialized in the instance's `.agents/skills/`. Framework-hoisted resources
+are resolved by path arithmetic against the installed kernel's own layout, so a
+source-tree run can pass while every installed deployment fails.
+
+These deterministic checks deliberately do **not** contact real aweb, Jira, or
+Linear services, validate remote git hosting/auth flows, or publish npm
+artifacts. Adapter/discovery changes additionally require a disposable real pi
+session from the packed artifacts; external services remain credentialed,
+out-of-scope probes. Release CI publishes both
+packages from one tag; keep versions synchronized because exact pi isolation
+depends on both kernel launch and adapter discovery behavior.
+
+Runtime-neutral token/cost/model/tool telemetry for Control Pane remains a
+follow-up; it requires an adapter-neutral event contract rather than pi-specific
+inspection in the universal CLI.

package/docs/integrations.md

@@ -0,0 +1,123 @@
+# Integrations
+
+An **integration is a capability package selected to satisfy one exclusive
+fundamental layer**: knowledge, messaging, or tasks. The layer model remains a
+formal part of OATS; capability packages generalize how its implementations and
+other reusable agent features are distributed and targeted.
+
+Read [Capability packages](capabilities.md) first for manifests, acquisition,
+targeting, instance-local composition, locks, trust, hooks, and commands.
+
+## Fundamental-layer contract
+
+For each soul, OATS resolves zero or one implementation for each pluggable
+layer:
+
+| Layer | Contract | Bundled choices |
+|---|---|---|
+| knowledge | capture, durable knowledge form, and promotion lifecycle | `oats.okf` |
+| messaging | reachable instance identity and human/agent communication | `oats.aweb` |
+| tasks | durable work queue, ownership, and status | `oats.jira`, `oats.linear` |
+
+A capability manifest becomes an integration by declaring one `layer`. It may
+not declare several layers. Two active packages for the same layer are a
+configuration error; general capabilities without `layer` remain additive.
+
+This exclusivity matters. For example, task state belongs to the selected task
+integration even if a messaging tool also happens to offer task features.
+
+## Selecting an integration
+
+New config activates the package for the intended target:
+
+```yaml
+agent-types:
+  product-agents:
+    description: Planner/developer/reviewer souls (they declare `type: product-agents`)
+
+capabilities:
+  layers:
+    knowledge:
+      capability: oats.okf
+      from: installed
+    messaging:
+      capability: oats.aweb
+      from: installed
+      agent-types:
+        product-agents:
+          enabled: true
+          settings:
+            team: example-team
+    tasks:
+      capability: oats.linear
+      from: installed
+      agent-types:
+        product-agents:
+          enabled: true
+          settings:
+            team: ENG
+            project: Agent Platform
+```
+
+Every matching soul gets one knowledge, messaging, and tasks implementation.
+A non-matching soul can resolve a different integration or leave a layer
+unresolved.
+
+CLI equivalents:
+
+```bash
+oats use oats.okf --global
+oats use oats.aweb --type product-agents
+oats use oats.linear --type product-agents
+```
+
+The manifest-declared layer makes a separate CLI/config layer selection
+unnecessary — `oats use` writes the entry under `capabilities.layers.<layer>`.
+To leave an inherited layer deliberately unfilled, use
+`oats use none --layer <layer>` (writes `capabilities.layers.<layer>: none`).
+
+## Bundled integrations
+
+### `oats.okf`
+
+The knowledge integration creates OKF soul bundles, instance `STATE.md`,
+`log.md`, and `notes/`, and exposes the `okf` and `memory-harvest` skills. The
+instance-triggered `oats okf harvest` command promotes pending notes after a
+commit. Its scaffold/spawn hooks own memory mechanics; the kernel remains
+knowledge-format agnostic.
+
+### `oats.aweb`
+
+The messaging integration mints an instance identity at spawn, removes it at
+retire, and contributes official aweb messaging/team skills. It requires the
+`aw` CLI. Messaging does not become the task system.
+
+### `oats.jira`
+
+The Jira tasks integration contributes the `jira-tasks` protocol and an
+advisory spawn hook. It requires `acli`; settings commonly include `site` and
+`project`.
+
+### `oats.linear`
+
+The Linear tasks integration contributes JSON-first `oats linear` commands,
+the `linear-tasks` skill, and an advisory spawn hook. It uses
+`LINEAR_API_KEY`; secrets never belong in OATS config. See
+`capabilities/oats-linear/README.md` for its support boundary.
+
+> **Removed: `oats.web`.** The browser web-panel capability was retired in
+> favor of the OATS Desktop app (`packages/desktop/`), which bundles the same
+> zero-dependency loopback server. If an `oats-lock.json` or `oats-config.yaml`
+> still names `oats.web`, remove that entry — the capability no longer exists
+> in the marketplace. Full migration steps: [docs/desktop-succession.md](desktop-succession.md).
+
+## Build an integration
+
+Use a namespaced capability manifest with exactly one `layer`, then test it as
+a capability package. The framework's `integrations-expert` soul remains the
+specialist for layer contract design. The `integration-authoring` skill routes
+work to it, while the package itself lives under `capabilities/` or
+`.agents/capabilities/`.
+
+Do not put target soul names in the manifest. Acquisition, agent types,
+activation, settings, exclusions, and overrides belong to `oats-config.yaml`.