@awebai/oats 0.22.0 → 0.22.1

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/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.