@awebai/oats 0.22.0 → 0.22.2

package/docs/execution-targets.md

@@ -0,0 +1,181 @@
+# Execution targets and shared wake delivery
+
+Implementation agreement, 2026-09-05. Lead owns native runtime launch,
+local tmux/Herdr adapters and terminal input; oats owns server registration,
+remote CLI routing and Desktop target selection. Aweb owns the event listener,
+notification state and delivery policy through OATS terminal input. This is the implementation
+contract, not a claim that these features have shipped.
+
+OATS manages composition, worktrees, capability lifecycle and retirement on the execution
+host. A session backend manages the persistent terminal. Desktop is a client;
+closing it must stop neither the agent nor notification delivery.
+
+```mermaid
+flowchart LR
+  UI[Desktop] --> CLI[OATS CLI]
+  CLI --> Local[Local OATS]
+  CLI --> SSH[OpenSSH]
+  SSH --> Remote[Remote OATS]
+  Local --> Sessions[tmux or Herdr]
+  Remote --> RemoteSessions[tmux or Herdr]
+  Events[aweb SSE] --> Wake[aweb wake service on execution host]
+  Wake --> Local
+  RemoteWake[aweb wake service on remote host] --> Remote
+```
+
+Server registrations live in the operator's machine configuration, outside
+repository configuration. Each entry has an id, label, OpenSSH host alias,
+absolute workspace path and OATS/Herdr executable paths. SSH owns key selection,
+host verification and authentication. Registration stores no private keys.
+Remote lifecycle calls invoke the remote installed OATS CLI with argument-safe
+quoting and the same JSON envelope as local calls. Version/envelope compatibility
+is checked before mutation. Repository operations always run on that host.
+
+The local representation of a remote instance snapshots its route:
+
+```json
+{
+  "serverId": "build-server",
+  "target": {
+    "sshHost": "build-server",
+    "workspace": "/srv/team",
+    "oatsPath": "/usr/local/bin/oats",
+    "herdrPath": "/usr/local/bin/herdr"
+  },
+  "instance": "developer-fix",
+  "home": "/srv/team/agents/developer/instances/developer-fix"
+}
+```
+
+`serverId` is for display. Later inspect/retire operations use the snapshot,
+never silently resolve a changed registry entry. A local cache is not authority
+for the remote instance's state. Remote status is pulled from its owning kernel.
+
+The host's instance and independent retirement baseline retain the same local
+session receipt. Existing `tmux: {session, window, socket}` remains readable.
+New Herdr instances use:
+
+```json
+{
+  "backend": "herdr",
+  "binary": "/usr/local/bin/herdr",
+  "socket": "/home/operator/.config/herdr/sessions/oats/herdr.sock",
+  "workspaceId": "w1",
+  "paneId": "w1:p1",
+  "terminalId": "term_65ab9108c6c301",
+  "protocol": 20
+}
+```
+
+The terminal id distinguishes a replacement occupant after a server restart.
+Backend operations allocate, start, inspect, stop and attach a viewer. Retirement
+compares the receipt with its baseline and proves the original session absent.
+An unavailable server or failed inspection is not proof of absence. The same
+rule applies to spawn compensation and detached self-retirement. Lifecycle
+operations run on the target host, so the local backend does not implement SSH.
+
+Herdr 0.8.2 exposes snapshots, socket commands, agent-state inspection and JSONL
+terminal observation/control. Its protocol is versioned. Agent prompts reject
+approval-blocked agents, but prompting a working agent does not prove the new
+message was processed. The adapter must retain this distinction. See the
+[Herdr socket API](https://herdr.dev/docs/socket-api/) and
+[remote connections](https://herdr.dev/docs/persistence-remote/).
+
+An aweb host service owns event streams for managed instances; the GUI displays
+and controls it. Reuse aweb's existing authenticated event/run loop rather than copying credential
+and SSE parsing into OATS or Desktop. OATS exposes backend-neutral session
+inspection and literal terminal input; aweb supplies delivery policy. Current authorization is
+per identity: one long-lived stream per active identity, coalesced per instance,
+with bounded retries. A single team stream requires an explicit server API.
+Reconnect also checks pending state so a lost edge does not strand unread work.
+
+Delivery is a fixed instruction to check `aw` mail/chat from the instance home,
+not arbitrary sender content typed into a shell. The service never acknowledges
+mail or chat on the agent's behalf. Aweb pending hints survive reconnect and service
+restart, coalesce while busy and defer at approval prompts. A stopped harness,
+an unknown occupant or a fallback shell is not a delivery target. Do not call a
+successful terminal write an agent acknowledgement.
+
+Native channels remain selectable during qualification; session delivery must
+be exclusive with them for each instance. Removal follows real tests of Pi,
+Claude and Codex receiving mail/chat, a busy turn, an approval prompt, reconnect,
+service restart, GUI closure and a stopped runtime. The OATS Pi tool extension
+and the aweb Pi channel are separate packages; replacing notification transport
+does not silently remove unrelated tools.
+
+Acceptance includes local CLI/Desktop spawn, reattach, preserved work and
+retirement through both backends; then the same operations on a user-designated
+SSH target. Registering a host without a successful remote agent run does not
+qualify remote support.
+
+## Session CLI contract
+
+Run on the execution host:
+
+```sh
+oats session attach --home /absolute/instance
+oats session inspect --home /absolute/instance --json
+oats session input --home /absolute/instance --text-file /path/to/message --json
+printf '%s' 'Check your pending work.' | oats session input --home /absolute/instance --json
+```
+
+`attach` is interactive and does not accept `--json`. It validates the saved
+endpoint on the execution host, then opens a Herdr terminal viewer or an
+isolated tmux session linked to that agent's window alone. Closing its terminal
+cleans the viewer without stopping the agent; retiring the agent ends the viewer
+instead of switching it to a sibling. This host-local command is also the
+remote Desktop attachment seam over an SSH PTY.
+
+Input accepts UTF-8 text up to 256 KiB, with no NUL bytes. The CLI uses the
+independent lifecycle receipt and refuses metadata disagreement. Tmux uses
+literal bracketed paste followed by Enter. Herdr uses pane input followed by
+Enter. Neither path interprets message text as a shell command. A fallback
+shell or ambiguous split tmux window refuses automatic input.
+
+Success uses the existing envelope:
+
+```json
+{"schemaVersion":1,"ok":true,"result":{"home":"/absolute/instance","backend":"herdr","present":true,"state":"idle","submitted":true}}
+```
+
+Inspect omits `submitted`; optional backend identifiers describe the observed
+terminal. `state` is the Herdr agent state when available, `unknown` for a live
+unclassified harness, `shell` for a fallback shell, `stopped` for an absent/dead
+terminal, or `not-launched`. Errors use `ok:false,error:{code,message}` and a
+nonzero exit. An unavailable backend is an error, never a stopped result.
+Tmux receipts identify socket/session/window; automatic input requires one live
+pane in that exact window. Herdr additionally verifies the original terminal ID.
+The broker owns busy/approval policy and must not interpret `submitted` as
+processing acknowledgement.
+
+Capability spawn hooks register a pending home before runtime allocation;
+inspection becomes available once its receipt is persisted. Retire hooks
+unregister after quiescence. The broker must tolerate this lifecycle order and
+missing homes, and persist pending hints until handled. Kernel session operations
+contain no aweb identity, credentials, stream or notification logic.
+
+The portable integration belongs to the official `oats.aweb` capability.
+The aweb development deployment currently selects its owned `aweb.identity`
+capability; that deployment-specific choice does not change the broker interface
+and needs equivalent registration glue when switched to session delivery.
+
+## Shared permission setting
+
+Set `yolo: true` in an `oats-config.yaml` to apply it to that scope. The closest
+scope wins; an optional `yolo` in soul.yaml overrides it; `oats spawn --yolo` or
+`--no-yolo` overrides both. `oats create` accepts those flags too. Desktop offers
+the same per-launch choice. With no setting, native policy is retained.
+
+Codex receives `--yolo` plus a launch-local trust setting for the generated
+instance home; Claude receives `--dangerously-skip-permissions`. Pi's existing
+project trust behavior is unchanged. `--no-yolo` removes the OATS bypass flags;
+it leaves the operator's native harness settings in force. Instance metadata
+records an explicitly resolved setting. This choice applies when starting an
+agent, not retroactively to running sessions.
+
+Desktop remote terminal requests contain only the server id and instance name.
+The selected installed CLI resolves the saved route and performs remote
+inspection before attaching over SSH. Pending inspections share the terminal
+resource limit and duplicate requests share one inspection. Remote status and
+instance keys must include the server so identical paths on different hosts
+remain distinct.

package/docs/first-team-demo.md

@@ -0,0 +1,87 @@
+# First-team example: OATS working on OATS
+
+On 2026-09-05 we installed the published OATS artifacts and used Pi and
+Claude Code workers to fix issues found during a fresh review. The first
+team's work was release preparation in this repository.
+
+## The setup
+
+| Component | Qualified value |
+| --- | --- |
+| Kernel and Pi adapter | 0.22.0, installed from npm |
+| Workspace config | `oats.dev` 1.0.0 default, adopted at the common workspace root |
+| Knowledge | `oats.okf` 1.4.1 |
+| Messaging | `oats.aweb` 1.8.0, bound to our existing team |
+| Authoring | `oats.authoring` 1.0.0 |
+| Worker scope | The child OATS Git repository, selected explicitly |
+| Harvester runtime/model | Pi, `openai-codex/gpt-5.5`, configured for this machine |
+
+Package acquisition used the published kernel's catalog and exact locks.
+The executable OKF and aweb capabilities were explicitly trusted.
+`oats doctor` passed. A separate published-authoring probe confirmed that
+`integration-authoring`, `skill-craft`, and `soul-craft` materialized for an
+authoring soul.
+
+## Two useful tasks
+
+The **Pi documentation worker**, `docs-expert-readme-claims`, corrected a
+claim that all captured conversations were signed. Native transcript turns
+have content hashes; signed aweb messages preserve their original
+signatures. Its code-review handoff led to the
+[documentation correction](https://github.com/awebai/oats/commit/ef4a1a6599da88e213b2a6a8f3918099aa5ba984).
+
+The **Claude Code worker**, `cli-dev-lock-fix`, fixed a stream-lock race.
+A late contender could classify a live holder's lock as stale and enter the
+same critical section. The fix uses holder liveness and an ownership token;
+review also caught an acquisition loop that could retry filesystem errors
+forever. See the [initial fix](https://github.com/awebai/oats/commit/1036381)
+and [review correction](https://github.com/awebai/oats/commit/81735f6e936d1b6aa0a3ad62d12953d494851cc8).
+
+Both workers used isolated worktrees, committed changes, and reported
+through aw. Review happened before integration. Claude needed its initial
+folder-trust and development-channels confirmations; Pi started directly.
+
+## What carried forward
+
+Each worker invoked OKF harvest. Its temporary harvester promoted a lesson
+into the source soul and committed it on the worker's branch:
+
+- [Content-addressed turn IDs do not authenticate native capture](https://github.com/awebai/oats/commit/91993a0b85db132c59c32d43ee2c90ec5569bd50).
+- [Lock ownership and the limits of comparing timeout thresholds](https://github.com/awebai/oats/commit/120e3474b93efc0d37f94c426327f802e27893ea).
+
+After the documentation promotion landed, the predecessor retired locally:
+its worktree, branch, and home were removed. Its aweb alias remained on the
+server despite the hook reporting success. A new Pi instance of the same
+soul with a different name, `docs-expert-capture-contract-check`, started a real
+follow-up task checking the capture contract documentation.
+
+Its first report named the promoted file:
+`soul/knowledge/lessons/content-addressed-turn-ids-not-authentication.md`.
+The worker said the lesson reinforced the distinction between unsigned
+native turns and preserved source signatures, and explicitly said it did
+not change what it was already about to do.
+
+That verifies useful work, reviewed promotion, local retirement, and a
+successor reading the updated soul. Remote identity retirement remains
+incomplete. The example does not establish a measured productivity
+improvement.
+
+## What the run exposed
+
+The run found first-use problems that unit tests alone had not resolved:
+
+- A fresh scope needed `mkdir -p agents` before `oats create`; the fix is in
+  the 0.22.1 changes.
+- The default harvester model assumed a provider absent on this machine.
+  The workspace now selects an authenticated model explicitly.
+- All four initial worker and harvester retirements reported successful
+  identity deletion but left their aweb aliases on the server. Local
+  cleanup completed; remote cleanup requires a team administrator, and
+  names cannot be reused until it succeeds. Temporary harvesters are now
+  excluded from messaging to avoid adding aliases while this is fixed.
+- A combined workspace roster did not make the workspace a spawn scope for
+  every child repository. Commands select the owning repository explicitly.
+
+The [first-team guide](first-team.md) includes these setup details. The
+package owners are responsible for improving their defaults; the kernel
+continues to resolve capabilities through the same replaceable contracts.

package/docs/first-team.md

@@ -0,0 +1,179 @@
+# Run your first OATS team
+
+Start with one repository and one small, real task. An OATS soul keeps the
+role and knowledge; an instance gets a working session and a Git worktree.
+Review its work, let it promote useful notes, then retire the instance.
+
+This guide follows the published **0.22.0** path exercised on 2026-09-05
+with `oats.dev` 1.0.0, `oats.okf` 1.4.1, `oats.aweb` 1.8.0, and
+`oats.authoring` 1.0.0. The [qualification example](first-team-demo.md)
+records the actual tasks and outcomes. Existing OAS users should follow
+[the migration guide](migration-from-oas.md) first.
+
+## Install and choose a scope
+
+Have Node.js 22+, Git, tmux, and an authenticated agent runtime available.
+Launch Pi or Claude Code once yourself to confirm that your chosen model
+works. The current OKF package runs its harvester in **Pi**, including when
+its working agent uses Claude Code, so this configuration needs Pi too.
+
+```bash
+npm install -g @awebai/oats@latest
+pi install npm:@awebai/oats-pi@latest
+node --version
+tmux -V
+oats version
+```
+
+Install matching kernel and adapter versions from the same release.
+
+Use a repository with an initial Git commit. Keep your normal working
+changes committed or otherwise accounted for before giving an agent work.
+The commands below run from that repository:
+
+```bash
+cd /path/to/project
+oats init --package oats.dev --config default
+oats list
+```
+
+Initialization acquires the package closure and writes an editable
+`oats-config.yaml` plus an exact lock. It does not create a team account or
+approve executable hooks. `oats.dev` is our reference development policy;
+edit its team name and provider choices for your own project.
+
+For several repositories, initialize their common workspace directory
+instead. Run create/spawn/retire with `--dir /path/to/workspace/project` for
+the repository that owns the soul. `oats status --team` at the workspace
+shows the combined roster, but that does not select a repository for spawn.
+
+## Set the model and connect messaging
+
+Edit the existing entries in `oats-config.yaml`; do not append a second
+`capabilities` block. Set `team.name` to your own team. If you already use
+aw, set `team.id` to its exact existing ID so instances join that team.
+
+Under `capabilities.layers`, configure the model your Pi installation can
+actually use. This example was used in our qualification; replace the
+model if you authenticate through another provider:
+
+```yaml
+knowledge:
+  capability: oats.okf
+  from: installed
+  settings:
+    harvest-model: openai-codex/gpt-5.5
+messaging:
+  capability: oats.aweb
+  from: installed
+  global: true
+  souls:
+    memory-harvest: false
+tasks: none
+```
+
+The `oats.okf` 1.4.1 default harvester model is
+`github-copilot/gpt-5.5`; it will not work without that provider. The
+messaging exclusion above keeps temporary harvesters from creating aliases
+while an identity-retirement issue is being corrected. Workers still get
+messaging identities. With a `souls` exclusion, state `global: true`
+explicitly so scope-level commands such as `oats aweb setup` stay active.
+
+Review and approve the executable capabilities, then check onboarding:
+
+```bash
+oats trust oats.okf
+oats trust oats.aweb
+oats aweb setup
+oats doctor
+```
+
+`oats aweb setup` prints the next step: install the `aw` CLI if needed,
+initialize an identity with `aw init`, then create or join your team. Follow
+that output and rerun setup until it confirms membership. For an existing
+team, join it rather than creating another with the same name. Setup's exit
+status alone does not establish that onboarding finished.
+
+Messaging is optional. To work without it, set `messaging: none`, omit the
+aweb trust/setup commands, and keep the knowledge configuration above.
+Packages, souls, Git worktrees, and local knowledge do not require hosted
+messaging. See [configuration](configuration.md) for other providers.
+
+## Give an instance a real task
+
+On 0.22.0, create the roster directory first; a fresh-scope creation fix is
+included in 0.22.1.
+
+```bash
+mkdir -p agents
+oats create backend-expert --type developers --repo . --work worktree --runtime pi
+```
+
+Edit `agents/backend-expert/soul/AGENTS.md` to describe the role, repository
+conventions, and the checks that matter. Review and commit the new soul,
+configuration, lock, generated ignore rules, and adopted template base under
+`.agents/config-templates/adopted/`. A worktree starts from a Git commit;
+uncommitted soul changes are not present on the worker's branch. Keep aw
+credentials out of Git.
+
+Then launch one bounded task:
+
+```bash
+oats spawn backend-expert --purpose first-fix --task "Fix one small issue, run the relevant checks, commit the change, and report what changed. Capture any reusable lesson and harvest it before finishing."
+oats status --team
+```
+
+Choose `--runtime claude` at creation for a Claude Code worker. Today its
+first session can require **two interactive confirmations**: folder trust
+and the development-channels confirmation used by the aweb integration.
+Attach to the tmux session printed by spawn and answer them. A created
+window is not evidence that the agent has started working.
+
+Each instance has a home under `agents/<soul>/instances/<instance>/`; its
+`work/` directory is the repository worktree. Read the instance's report
+and review its commits there. Agents using aw run coordination commands
+from their own home, which holds their identity.
+
+## Harvest, review, and retire
+
+With OKF active, the worker keeps state and notes in its home. After a
+commit it can run `oats okf harvest` there. If it reports pending notes but
+has not harvested, ask it to do so, or run the command from that instance's
+home yourself. Retirement does not initiate knowledge promotion.
+
+The harvester reviews notes, updates the soul's knowledge, and commits the
+promotion into the worker's branch. Let it finish before final review or
+retirement. Review **all** commits, including the promotion, and merge the
+accepted work into the repository's main branch through your normal
+workflow. Then, from the repository scope:
+
+```bash
+oats retire backend-expert-first-fix
+oats status --team
+```
+
+Read the retirement result, including any retained home or recovery path.
+With aweb enabled, also inspect `oats aweb roster`: local retirement alone
+is not proof that a remote alias was removed. During the current hosted
+alias-retirement issue, use a fresh purpose for the next instance and have
+the team administrator clear any stale alias before reusing its name.
+
+Start the same soul on the next useful task after its knowledge commit is
+on main. Check that the new instance can find and use the promoted lesson.
+That completes the first lifecycle: useful work, reviewed learning, clean
+local retirement, and a successor with the updated soul.
+
+## Optional conversation record
+
+Knowledge promotion and conversation capture are separate. To enable the
+local transcript record and query it:
+
+```bash
+oats setup
+oats capture --status
+oats recall "a phrase from your completed task"
+```
+
+Capture reads supported transcripts and aweb logs after setup, subject to
+ignore rules. Native turns are content-addressed; signed aweb messages
+retain their source signatures. See [the turn record](../README.md#the-turn-record).

package/docs/implementation.md

@@ -158,7 +158,20 @@ 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
+Codex is available with `--runtime codex`. It starts in the instance home,
+reads `AGENTS.md` and `.agents/skills` natively, and receives `TASK.md` as its
+initial prompt. User configuration, approval policy, ancestor instructions and
+ambient skill sources remain native. Worktrees are already below the instance
+home; checkout/attached paths outside it use Codex's normal approval handling
+and may require approval for writes, depending on the operator's policy.
+OATS does not pass `--add-dir`, which Codex refuses under some native policies.
+OpenAI-prefixed model preferences are translated to
+Codex ids; other provider preferences fall back to its configured default.
+The Desktop model field accepts a native id without using Pi's model catalog.
+This launch support does not supply an aweb channel for Codex: agents can use
+`aw` from their home, with automatic wake delivery tracked separately.
+
+All 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.

package/docs/integrations.md

@@ -1,39 +1,42 @@
-# Integrations
+# Integrations: binding an implementation to a contract
 
-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.
+An **integration** is a capability package selected to fill one exclusive
+slot: `knowledge`, `messaging` (the communication contract), or `tasks`.
+The contracts themselves are in [the OATS contracts](layers.md); this
+document is about choosing an implementation, and about building one.
 
-Read [Capability packages](capabilities.md) first for manifests, acquisition,
+Read [capability packages](capabilities.md) first for manifests, acquisition,
 targeting, instance-local composition, locks, trust, hooks, and commands.
 
-## Fundamental-layer contract
+## The slots
 
-For each soul, OATS resolves zero or one implementation for each pluggable
-layer:
+For each soul, OATS resolves zero or one implementation per slot:
 
-| 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` |
+| Slot | Contract | Bundled implementations |
+| --- | --- | --- |
+| `knowledge` | [knowledge](layers.md#the-knowledge-contract) | `oats.okf` |
+| `messaging` | [communication](layers.md#the-communication-contract) | `oats.aweb` |
+| `tasks` | [tasks](layers.md#the-tasks-contract) | `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.
+A capability manifest becomes an integration by declaring one `layer`. It
+may not declare several. Two active packages for one slot and one soul are a
+configuration error; capabilities without `layer` compose additively.
 
-This exclusivity matters. For example, task state belongs to the selected task
-integration even if a messaging tool also happens to offer task features.
+Exclusivity is the point. Task state belongs to the selected tasks
+implementation even when a messaging tool also offers task features, and
+conversation belongs to the messaging implementation even when a tracker
+offers comments.
 
 ## Selecting an integration
 
-New config activates the package for the intended target:
+Configuration activates the package for the intended target; the manifest
+already declares the slot, so `oats use` writes the entry under
+`capabilities.layers.<slot>`:
 
 ```yaml
 agent-types:
   product-agents:
-    description: Planner/developer/reviewer souls (they declare `type: product-agents`)
+    description: Planner, developer, and reviewer souls (they declare `type: product-agents`)
 
 capabilities:
   layers:
@@ -59,65 +62,80 @@ capabilities:
             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
+oats use none --layer tasks        # leave an inherited slot deliberately unfilled
 ```
 
-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`).
+Every matching soul gets one implementation per slot. A non-matching soul can
+resolve a different one or leave a slot unfilled. `none` is a layer
+selection, not a policy: a soul with `messaging: none` has no address, which
+is different from a soul whose type restricts its reach.
 
 ## 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.okf`** fills `knowledge`: OKF soul bundles, instance `STATE.md`,
+`log.md`, and `notes/`, the `okf` and `memory-harvest` skills, and
+`oats okf harvest`, which promotes pending notes after a commit through the
+capability-defined `memory-harvest` soul. Its scaffold and spawn hooks own
+memory mechanics; the kernel stays knowledge-format agnostic.
 
-### `oats.jira`
+**`oats.aweb`** fills `messaging`: mints an instance identity at spawn,
+removes it at retire, contributes the aweb messaging and team skills, wires
+the channel plugin so sessions are woken by mail, and exposes
+`oats aweb roster` and `oats aweb setup`. Requires the `aw` CLI.
 
-The Jira tasks integration contributes the `jira-tasks` protocol and an
-advisory spawn hook. It requires `acli`; settings commonly include `site` and
-`project`.
+**`oats.jira`** fills `tasks`: the `jira-tasks` protocol and an advisory
+spawn hook. 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
+**`oats.linear`** fills `tasks`: JSON-first `oats linear` commands, the
+`linear-tasks` skill, and an advisory spawn hook. 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`.
+> zero-dependency loopback server. If an `oats-lock.json` or
+> `oats-config.yaml` still names `oats.web`, remove that entry. Full
+> migration steps: [desktop-succession](desktop-succession.md).
+
+## Building an integration
+
+Building an integration is implementing a contract. The checklist per slot:
+
+**Any slot.** A namespaced capability manifest with exactly one `layer`; an
+`inject` block that tells the instance what this implementation is and which
+skill to load before first use; skills that carry the craft; commands that
+support `--json`; hooks only on the accepted events; `requires` for every
+host command and runtime package; `environment` for every launch variable
+contributed, under the vendor prefix. Package commands and hooks reach the
+kernel only through `OATS_CLI_BIN` and the JSON envelope, never by importing
+kernel files. Never name target souls in the manifest; targeting belongs to
+configuration.
+
+**Knowledge.** Scaffold the soul's store on `soul-scaffold`; create instance
+ephemeral state on `spawn`; teach the read side (index-first, selective,
+binding) in the inject and skill; ship a harvester as a capability-defined
+soul and a command that spawns it attached to the source instance's tree;
+route promotions by custody (commit, pull request, or direct edit); apply the
+promotion doctrine in the contract; and, once the `harvest` event exists,
+declare it instead of relying on the instance to call the command.
+
+**Communication.** Mint an address on `spawn` with a `required` hook and
+remove it on `retire`; supply the roster; teach send, reply, chat, and "read
+the event first" in the inject and skill; contribute launch arguments so the
+session is woken; enforce the soul type's `reach` on both sides; state
+whether the address outlives the instance; and keep task coordination out.
+
+**Tasks.** Teach claim, update, block, hand off, and complete; identify the
+instance to the tracker in a way that survives it; keep conversation out.
+
+The framework's `integrations-expert` soul remains the specialist for
+contract design, and the `integration-authoring` skill routes work to it.
+Test an integration as a capability package: acquire, lock, trust, activate,
+spawn, retire, with the golden fixtures as the behavior oracle for the kernel
+side.