agents-can-communicate 0.2.0 → 0.3.1

package/docs/ARCHITECTURE.md

@@ -1,8 +1,9 @@
 # Architecture
 
-ACC is a local control plane for communication facts. The execution planes remain the AI
-clients the user opened. Core records the truth before a delivery adapter is asked to make
-it arrive sooner.
+Use this page to trace a communication fact from an independently opened client through
+core, storage, and an optional delivery adapter. ACC is the local control plane; the AI
+clients remain independent execution planes. Core records the truth before an adapter is
+asked to make it arrive sooner.
 
 ```mermaid
 flowchart LR
@@ -41,7 +42,7 @@ The order is part of the public guarantee:
 
 1. validate and commit the message plus one `queued` receipt per resolved recipient;
 2. resolve the recipient's current delivery bindings;
-3. check recipient policy, current reachability, and exact client-version certification;
+3. check recipient policy and the current binding's reachability and offered native mode;
 4. ask one adapter to cross its transport boundary;
 5. only after acceptance, commit `offered` and an immutable success event.
 
@@ -71,16 +72,21 @@ lease without exposing the endpoint.
 
 ## Certified capability versus current reachability
 
-A capability says an exact client version on an exact platform passed a captured behavior.
-It does not say one particular session is reachable now. A binding says what that current
-generation exposes and whether its lease is current. Recipient policy says whether it may
-spend a turn. All three must agree before live delivery is possible.
-
-Codex and Claude Code currently ship failed native-delivery captures, so their
-`delivery.livePush` and `delivery.replyRoute` capabilities resolve false. Gemini CLI and
-Kimi Code have exact-version next-turn evidence only. Grok and generic MCP use inbox
-polling. The architecture includes a live seam without pretending the current clients
-proved it.
+Ordinary hook capabilities say an exact client version on an exact platform passed a
+captured behavior. Native live delivery uses a separate contract: installation checks the
+captured minimum, platform, and current feature probe, then each session publishes a binding
+only after a generation-bound handshake. The router trusts that admission and verifies the
+binding, recipient policy, declared adapter capability, and adapter response; it does not add
+a third exact-version certification check. A binding says what that current generation
+exposes and whether its lease is current, while recipient policy says whether it may spend a
+turn.
+
+Claude Code is the one client that proved the live seam: a Channel capture on 2.1.258,
+confirmed on 2.1.260 through the installed package, admitted by minimum-plus-probe rather
+than an exact version. Codex's queue transport passed its capture and the capability was
+withdrawn, because the mode it needs hides the session's workspace. Gemini CLI and Kimi
+Code have exact-version next-turn evidence only; Grok and generic MCP use inbox polling.
+The seam exists for every adapter; only one has earned it.
 
 ## Storage and workspace identity
 
@@ -90,7 +96,9 @@ lexically, so a cursor is simply the last sequence returned.
 
 Workspace discovery checks an explicit config first, then the Git common directory, then
 the plain directory. Multiple worktrees share a workspace id while each session records
-its checkout and branch. Nothing written by ACC lands inside those roots.
+its checkout and branch. Runtime state never lands inside those roots; the only project
+file ACC writes is an optional `acc.workspace.json` explicitly requested through
+`acc config init`.
 
 A lone session can remain ephemeral. Durable state materialises when a second live session
 appears or the first claim, message, or handoff is committed. This makes “silent when

package/docs/CAPABILITIES.md

@@ -1,5 +1,11 @@
 # Capabilities
 
+Use this page to set expectations after installation. Integration means ACC can introduce
+peer awareness and coordination instructions; it does not guarantee what a model will do
+with them. Delivery also varies independently from awareness. The durable inbox works for
+every participant, supported exact versions may add next-turn delivery, and only the
+experimental Claude Code channel can deliver while a session is idle.
+
 Capability honesty separates four questions that are easy to collapse:
 
 1. **Certified support** — did this exact client version and platform pass a shipped
@@ -13,11 +19,15 @@ Capability honesty separates four questions that are easy to collapse:
 A source method or vendor documentation is not certification. Unknown versions and
 platforms degrade to false. No weaker session inherits a stronger peer's capability.
 
+Run `acc doctor` in the project when observed behavior differs from this page. It reports
+the installed client version, platform, effective capability, and fallback instead of
+assuming that a newer or differently packaged client behaves like a captured one.
+
 ## Certified support
 
 Passing evidence currently ships for these exact versions on `darwin-arm64`:
 
-| Capability | Codex 0.147.0 | Claude Code 2.1.233 | Gemini CLI 0.37.0 | Grok 1.0.13 | Kimi 0.36.1 |
+| Capability | Codex 0.147.0 | Claude Code 2.1.233 | Gemini CLI 0.57.0 | Grok 1.0.13 | Kimi 0.36.1 |
 |---|---:|---:|---:|---:|---:|
 | `lifecycle.sessionStart` | yes | yes | yes | no | yes |
 | `lifecycle.sessionEnd` | yes | yes | yes | no | no |
@@ -32,15 +42,23 @@ Passing evidence currently ships for these exact versions on `darwin-arm64`:
 Every other capability in the closed shape defaults to false, including session resume,
 child sessions, startup or safe-point injection, and before-read guards.
 
+The `delivery.livePush` and `delivery.replyRoute` row is `no` for the exact hook versions
+this matrix is keyed to. Native live delivery is captured on a newer client - Claude Code
+2.1.258, livePush and replyRoute, confirmed again on 2.1.260 through the installed package -
+and is admitted through the native delivery contract rather than exact-version
+certification: it is off until a per-client opt-in, experimental, and never turns on for a
+client below the captured minimum. Codex's queue capture passed and the capability was
+withdrawn; the row below says why.
+
 The limitations belong next to the adapters they affect:
 
 | Adapter | Exact limitation and evidence |
 |---|---|
-| Codex | 0.147.0 next-turn stdout arrives as unwrapped developer-role context and requires plugin trust. The separate 0.152.0 native capture found no daemon control socket; ACC did not start one, so live push and reply routing remain false. |
-| Claude Code | 2.1.233 next-turn delivery waits for the next user prompt. The 2.1.252 channel capture stopped at the development-channel warning before the ACC MCP child started; native delivery branches are unobserved and false. |
-| Gemini CLI | Only 0.37.0 has package-shipped next-turn certification. Write and shell tools depend on approval mode; other versions and platforms retain inbox access but no effective delivery capability. |
-| Grok | Documentation-shaped payloads do not count as real captures. UserPromptSubmit context was observed discarded, and no deny was captured stopping a real write; all capabilities remain false. |
-| Kimi Code | 0.36.1 has next-turn and guard evidence, plus a 60-second heartbeat. Prompt-mode `SessionEnd` never fired, and its next-turn path does not interrupt an active turn. |
+| Codex | 0.147.0 next-turn stdout arrives as unwrapped developer-role context and requires plugin trust. A 0.152.1 capture proved the App Server queue transport, but the release capture then measured that native delivery there requires `codex --remote unix://`, and in that mode the session runs inside the daemon: both the hook payload and the App Server's own thread record report the daemon's directory instead of the session's, so ACC cannot tell which workspace the session is in. Nothing ACC can reach carries the real one, and placing a session in the wrong workspace is worse than not placing it, so `delivery.livePush` is **not** claimed - the probe and the handshake both refuse with `workspace_identity_unavailable`. `replyRoute` stays false. |
+| Claude Code | 2.1.233 next-turn delivery waits for the next user prompt. A 2.1.258 Channel capture proved idle offer, busy queue-after-turn, explicit reply, duplicate suppression, and durable fallback, so `delivery.livePush` and `delivery.replyRoute` are live capabilities behind the native contract (experimental, off until opted in; Claude's development-channel warning is vendor-owned and visible). |
+| Gemini CLI | Only 0.57.0 has package-shipped next-turn certification. Its TUI has no captured external wake or queue interface and `--acp` changes launch ownership, so native delivery is fallback-only; live push and reply routing remain false. |
+| Grok | Documentation-shaped payloads do not count as real captures. The public leader surface exposed no proven addressed injection into an ordinary TUI session, so native delivery is `awaiting_compatibility_capture`; all capabilities remain false. |
+| Kimi Code | 0.36.1 has next-turn and guard evidence, plus a 60-second heartbeat. Its server/queue APIs do not prove a transparent binding to an independently opened session, so native delivery is fallback-only. |
 | Generic MCP | Tool polling is not next-turn injection, live push, or a native reply route. It has no write guard or client-lifecycle evidence. |
 
 `certification.json` beside each adapter is machine-readable. `COMPATIBILITY.md` records the
@@ -54,13 +72,24 @@ would publish a generation-bound binding with `availableModes`, `clientVersion`,
 with a computed `reachable` boolean while keeping the opaque endpoint private.
 
 The router requires exactly one current eligible generation. No binding, an expired lease,
-several live sessions for one participant, a busy target, or a version that does not match
-passing evidence all stay on durable fallback.
-
-Current shipped reality: no adapter publishes a native live binding, and no adapter has
-passing `livePush` certification. Codex and Claude Code are next-turn or inbox only;
-Gemini CLI and Kimi Code are next-turn only at their exact captured versions; Grok and MCP
-poll inbox.
+several live sessions for one participant, and an adapter refusal each keep delivery on the
+durable fallback. Busy behavior belongs to the transport: Claude's Channel can accept a
+message while the target is busy and queue it until the current turn finishes; an adapter
+that instead refuses with `recipient_busy` leaves the message on the durable path.
+
+The lease is extended by whoever serves the endpoint, because only that process knows it is
+still alive. A client that publishes no heartbeat - Claude Code among them - would otherwise
+let the lease run out under an idle session, which is exactly when live delivery is worth
+having. Giving a binding up is a separate, final fact rather than an expired lease, so a
+channel that has not yet noticed cannot extend something the session already retired.
+
+Current shipped reality: Claude Code on darwin-arm64 has a passing experimental `livePush`
+capture behind the native delivery contract, off until a per-client opt-in. Codex is
+next-turn and inbox only: its queue transport works, but the mode that makes a session
+reachable is the mode that hides which workspace it is in. Every other client is next-turn or
+inbox only. Gemini CLI and Kimi Code are next-turn only at their exact captured versions;
+Grok and MCP poll inbox. On Linux, the shipped captures above do not establish next-turn or
+live delivery, so the honest expectation is the durable inbox.
 
 ## Recipient policy
 
@@ -70,13 +99,17 @@ policy:
 | Policy | Meaning |
 |---|---|
 | `off` | normal next-turn and inbox only |
-| `actionable` | questions, requests, and addressed handoffs may use live push |
+| `actionable` | questions, requests, answers, decisions, and addressed handoffs may use live push; notes wait for the next turn |
 | `all` | every addressed message kind may use live push |
 
 The default is `off`. `acc install --delivery actionable|all` is an explicit request, not
-a force switch. The installer applies it only when the detected exact client has certified
-live push; otherwise effective policy remains off and the fallback diagnostic is printed.
-Room messages are never live-push candidates.
+a force switch. Exact-version certification governs ordinary hook capabilities. Native live
+delivery is separate: the installer applies the requested policy only when the client meets
+the captured minimum version, runs on a captured platform, and passes the current feature
+probe; otherwise effective policy remains off and the fallback diagnostic is printed. Each
+enabled session must then pass its generation-bound handshake. A failed handshake clears or
+refuses that session's binding and reports degraded reachability without rewriting the
+installed consent. Room messages are never live-push candidates.
 
 ## Fallback
 
@@ -84,7 +117,7 @@ Room messages are never live-push candidates.
 |---|---|
 | exact-certified Codex 0.147.0 | complete peer body at the next normal turn; `acc inbox` remains recoverable |
 | exact-certified Claude Code 2.1.233 | complete peer body at the next normal prompt; `acc inbox` remains recoverable |
-| exact-certified Gemini CLI 0.37.0 | complete peer body at the next normal turn; `acc inbox` remains recoverable |
+| exact-certified Gemini CLI 0.57.0 | complete peer body at the next normal turn; `acc inbox` remains recoverable |
 | exact-certified Kimi Code 0.36.1 | complete peer body at the next normal turn; `acc inbox` remains recoverable |
 | Grok, generic MCP, unknown version, other platform | explicit `acc inbox` polling |
 

package/docs/CLI.md

@@ -1,9 +1,10 @@
 # CLI
 
-The `acc` command is the universal local boundary. Setup commands are for a person;
-communication commands are the small surface installed skills teach to agents. Every
-command accepts `--json` and `--cwd <path>`. `--workspace <config>` selects an explicit
-workspace config where supported by the common boundary.
+Use `acc` to install and diagnose integrations, or to inspect the same communication
+operations that installed skills use on an agent's behalf. Setup commands are for a
+person; communication commands are the smaller agent-facing vocabulary. Every command
+accepts `--json` and `--cwd <path>`. `--workspace <config>` selects an explicit workspace
+config where supported by the common boundary.
 
 <!-- test:command -->
 ```bash
@@ -11,7 +12,7 @@ acc help
 acc version
 ```
 
-## Communication commands
+## Coordinate from a session
 
 | Command | Required | Optional |
 |---|---|---|
@@ -57,14 +58,24 @@ reason; ordinary sessions release only their own claims.
 ### Messages and requests
 
 ```bash
-acc message --to models --type question --subject "receipt wording" \
+acc message --to codex --type question --subject "receipt wording" \
   --body "Should transport acceptance be called offered?" \
   --client-message-id client_stable_1
 
-acc request --to models --title "review receipt wording" \
+acc request --to codex --title "review receipt wording" \
   --detail "Check CLI and MCP results; reply with defects only."
 ```
 
+`--to` takes a client name - `codex`, `claude_code`, `gemini_cli` - while exactly one
+session of that client is here, and the exact participant id from `acc status --json`
+otherwise. Two sessions of one client are refused by name rather than guessed between, the
+same way `--session` refuses. The recorded message always names the participant, never the
+client it was reached through.
+
+By default a hooked participant id is derived from that client's session id. It remains
+usable for the current conversation but a new unrelated conversation gets a new address.
+Set `ACC_PARTICIPANT` when the recipient must keep one stable address across conversations.
+
 `message` accepts generic kinds `note`, `question`, `request`, and `decision`. Defaults are
 `note` plus obligation `none`; questions and requests require `reply`; an addressed
 decision may explicitly use `--obligation acknowledge`. `answer` is created only by
@@ -109,14 +120,14 @@ no state override.
 ```bash
 acc finish --goal "document receipt semantics" --status partial \
   --completed "protocol updated" --remaining "acceptance proof" \
-  --blocker "packed test not run" --to models
+  --blocker "packed test not run" --to codex
 ```
 
 Status is `complete`, `partial`, or `blocked`. `finish` records a structured handoff,
 releases the caller's claims, and ends ACC presence for that session. It never closes the
 external AI client. An addressed handoff requires acknowledgement; a room handoff does not.
 
-## Setup and maintenance
+## Install, diagnose, and update
 
 | Command | Flags |
 |---|---|
@@ -129,14 +140,21 @@ external AI client. An addressed handoff requires acknowledgement; a room handof
 | `acc help` | — |
 | `acc version` | — |
 
-`--delivery` is a recipient policy request, not a capability switch. The default is
-`off`. If the detected exact client version lacks certified live push, installation keeps
-the effective policy off and prints the adapter's durable fallback.
+`--delivery off|actionable|all` is a per-client recipient policy request, not a capability
+switch, and the default is `off`. `--adapter` is repeatable to name several clients. An
+explicit `--delivery` applies uniformly and never prompts; omitting it on an interactive
+terminal asks one default-No question per eligible client, and on a non-interactive run or a
+`--dry-run` it keeps fresh clients off. A recorded opt-in is kept on upgrade. If the detected
+client cannot receive native delivery - unsupported, below the captured minimum, a
+prerelease, known-bad, a wrong platform, or an unsupported shell - installation keeps the
+effective policy off and prints the reason. A live install writes an owned zsh PATH block and
+a per-command shim that keeps your command name and `exec`s the real client; `ACC_BYPASS=1`
+runs the unmodified client, and ACC is never the parent of the session after that `exec`.
 
 Only `update` touches the network. `ACC_NO_UPDATE_CHECK=1` disables update checks. Hooks
 never perform them.
 
-## Adapter lifecycle commands
+## Integrate a client lifecycle
 
 `acc attach --participant <id>`, `acc heartbeat --session <id> --generation <token>`, and
 `acc detach --session <id> --generation <token>` are public executable boundaries used by

package/docs/CONCEPTS.md

@@ -1,134 +1,131 @@
 # Concepts
 
-ACC connects AI sessions that were independently opened by a user. It adds communication
-around those sessions; it does not turn them into one managed runtime. Each client keeps
-its own context, permissions, lifecycle, checkout, and human authority.
-
-```mermaid
-graph LR
-  A["independent session A"] --- ACC["ACC local room"]
-  B["independent session B"] --- ACC
-  C["independent session C"] --- ACC
-```
+You open the sessions and give each agent its own task. ACC makes those sessions aware of
+one another and gives them a shared communication vocabulary. It does not combine their
+contexts or turn them into workers owned by one controller.
+
+Use this page when a guide or diagnostic names an ACC object. The examples assume Codex is
+building a registration endpoint and Claude Code is building the screen that calls it.
 
 ## Peers, not workers
 
-Sessions in one workspace may use different models, clients, trust settings, or people.
-No participant is automatically in charge of another. A peer may ask, answer, reserve,
-acknowledge, or hand off; the receiver evaluates the message under its own instructions.
+Codex and Claude Code are **peers**. They may use different models, permissions, trust
+settings, clients, and checkouts. Neither is automatically in charge. Claude can ask Codex
+for the endpoint shape; Codex can answer or decline under its own instructions.
 
-This is the middle layer between isolated terminals and a system that owns the agents.
-ACC owns durable coordination facts even when every model process is gone, but it never
-owns the process itself.
+This resembles coordination among subagents, but the sessions were opened independently by
+the user. ACC never launches, assigns, supervises, or closes them.
 
-## Participant and session
+## Workspace, participant, and session
 
-A **participant** is the address used for communication. A stable participant id lets a
-new session recover messages addressed before restart. A **session** is one current client
-conversation with a generation token proving ownership of its mutations. Several sessions
-may belong to one participant; a live offer is ambiguous unless exactly one current
-generation is eligible.
+A **workspace** is the local room where related sessions discover coordination facts. It is
+scoped to one machine and operating-system user. Git worktrees of one repository resolve to
+the same ACC workspace, but their checkout files remain separate. In a plain directory, the
+directory supplies identity unless optional configuration says otherwise. Git is optional.
 
-A **workspace** is the local room. Git worktrees of one repository resolve to the same
-workspace while retaining their checkout and branch in presence. In a non-Git directory,
-the directory itself supplies identity. Git enriches the record but is never required.
+A **participant** is the address for communication. A stable participant id can recover
+messages sent before a restart. A **session** is one current opening of that participant,
+with a generation token preventing an old process from changing its replacement's state.
 
-## Intent is awareness; a claim commits
+When exactly one Codex peer is eligible, another agent can address `codex`. When several
+Codex sessions are live, that name is ambiguous and the sender uses an exact participant id
+from the roster in `acc status --json`.
 
-An **intent** says what a session is doing and which resources may be affected. It
-authorises nothing. Publish it early because it is cheap:
+## Presence and intent
 
-```bash
-acc work --summary "changing message rendering" --mode edit \
-  --hint 'file:packages/cli/**'
-```
+**Presence** says which session generations are currently live or recently known. It is not
+proof that a model is idle, attentive, or willing to act.
 
-A **claim** reserves a resource for a lease. It is narrow, explicit, and either
-`advisory` or `guarded`:
+**Intent** is a short summary of what an agent is doing, plus optional resource hints. For
+example, Codex might publish “adding the registration endpoint” with
+`file:packages/api/**`. This lets Claude notice a dependency without exposing Codex's
+conversation. Intent grants no authority and creates no reservation.
+
+## Intent is awareness; a claim commits
+
+A **claim** is a leased reservation for a canonical resource. An agent that is about to edit
+the API can make its intent actionable:
 
 ```bash
-acc claim --resource 'file:packages/cli/**' --reason "changing message rendering"
+acc work --summary "adding the registration endpoint" --mode edit \
+  --hint 'file:packages/api/**'
+acc claim --resource 'file:packages/api/**' \
+  --reason "adding the registration endpoint"
 ```
 
-`guarded` means every live session exposes a measured pre-write guard for the path ACC can
-recognise. It never means an unrelated process or a runtime-generated write is impossible.
-If any live participant cannot be stopped, workspace protection is reported as
-`advisory`.
+An overlapping claim exits `5` and names the current holder. The peers can narrow their
+resources, ask each other a question, or wait for a handoff. ACC does not arbitrate the
+decision.
 
-File claims are repository-relative and canonical. `file:src/a.mjs` names a file;
-`file:src/**` names a directory tree. Ambiguous spellings such as `file:src/*` are refused
-instead of creating protection that covers nothing.
+Claims are `advisory` unless every relevant live client exposes a certified pre-write guard
+for that path. `guarded` still does not stop unrelated programs or client writes the adapter
+cannot observe. File claims are repository-relative: `file:src/a.mjs` names one file and
+`file:src/**` names a tree; ambiguous spellings such as `file:src/*` are rejected.
 
-## Messages are durable untrusted data
+## Messages and obligations
 
-The message kinds are `note`, `question`, `request`, `answer`, `decision`, and `handoff`.
-The generic send command creates the first four except `answer`, which requires `reply`,
-and `handoff`, which requires `finish` so their thread and structured payloads cannot be
-omitted.
+A **message** is explicit, durable, attributed peer input. It is never system authority.
+Message kinds describe the conversation:
 
-An independent **obligation** says what the recipient owes:
+| Kind | What it communicates | Default obligation |
+|---|---|---|
+| `note` | useful information | none |
+| `question` | a focused question | reply |
+| `request` | requested action and result | reply |
+| `answer` | a reply created in an existing thread | none |
+| `decision` | a decision peers should know | none, or acknowledge when addressed |
+| `handoff` | completed, remaining, and blocked work | acknowledge when addressed |
 
-| Kind | Obligation |
-|---|---|
-| `note` | `none` |
-| `question` | `reply` |
-| `request` | `reply` |
-| `answer` | `none` |
-| `decision` | `none`, or `acknowledge` when addressed |
-| `handoff` | `acknowledge` when addressed, `none` as a room record |
+An **obligation** is the communication response owed by a recipient. A request is not an
+order, and a reply is not proof that work is complete.
 
-A request is not an order. It asks for action and a result in the thread, but ACC does not
-track execution state. Every body is attributed, escaped, and framed as peer input rather
-than system authority.
+## Threads keep the exchange together
 
-## Threads have no hidden status
+The first message is a **thread** root. A reply names the original message and stays in that
+thread, so Claude's interface question and Codex's answer remain connected. There is no
+hidden mutable thread status; pending attention is derived from obligations and each
+recipient's receipt.
 
-The first message is the thread root and uses its own `messageId` as `threadId`. A reply
-keeps that thread id and names the original with `inReplyTo`. There is no mutable thread
-record. What still needs attention is derived from message obligations and per-recipient
-receipts.
-
-`clientMessageId` is the caller's retry key. Repeating equivalent content with the same
-key returns the same logical message; reusing it for different content is rejected.
+`clientMessageId` is an optional retry key. Equivalent retries return the original message;
+the same key with different content is rejected. The exact fields and validation rules are
+in [Protocol](PROTOCOL.md).
 
 ## Delivery words are evidence
 
-Each recipient has an independent monotonic receipt:
+Each recipient has its own monotonic **receipt**:
 
 ```text
 queued -> offered -> retrieved -> acknowledged
 ```
 
-- `queued`: message and receipt committed durably;
-- `offered`: bytes crossed ACC's transport boundary or a certified native client accepted
-  the call;
-- `retrieved`: the participant explicitly read the message through inbox or equivalent
-  certified evidence;
-- `acknowledged`: the participant acknowledged it or replied.
+- `queued`: the durable message and receipt committed;
+- `offered`: ACC or a certified client accepted the delivery bytes, not proof of reading;
+- `retrieved`: the participant fetched the message, not proof of model attention;
+- `acknowledged`: the participant acknowledged it or replied, not proof of task completion.
+
+There is no `seen` receipt. A failed delivery attempt leaves the message queued and
+recoverable rather than creating a terminal failure state.
 
-There is no `seen`: ACC cannot observe model attention. There is no terminal delivery
-failure: a failed acceleration leaves the durable message recoverable. Forward skips are
-legal when a stronger fact implies the weaker ones; backward transitions are rejected.
+## Durable first, faster delivery second
 
-## Durable first, acceleration second
+The durable inbox is universal. Exact-version certified adapters may also offer messages at
+the next normal turn. That does not wake an idle client. Claude Code has the only shipped
+experimental live path, off by default and subject to recipient policy and current
+reachability; Codex live delivery is withdrawn. [Capabilities](CAPABILITIES.md) is the
+current adapter matrix.
 
-Every send records the message before attempting a transport. Inbox is the universal
-recovery path. Exact-version certified adapters may offer complete peer messages at the
-next normal turn. Native live push would additionally require passing certification, the
-recipient's opt-in policy, exactly one current reachable binding, and a safe recipient
-state.
+## Handoffs preserve explicit context
 
-No shipped adapter currently passes live-push certification. Codex 0.152.0 had no daemon
-control socket; Claude Code 2.1.252 stopped at the development-channel warning before its
-ACC child started. Those failures are shipped as evidence and result in visible fallback,
-not a stronger promise.
+A **handoff** records what an agent says it completed, what remains, and any blockers before
+the session ends. It can help a later session resume without copying a transcript. Like
+every peer message, it is attributed data to verify, not an authoritative completion claim.
 
-## Where state lives
+## Where data lives
 
-Presence, intents, claims, messages, receipts, events, and handoffs live in platform app
-data outside every repository. Raw transcripts remain in the client. A single session is
-silent; durable workspace state materialises when a second session or the first durable
-coordination object makes it necessary.
+Presence, intent, claims, messages, receipts, events, and handoffs live in platform app data
+outside every repository. ACC never collects or shares raw prompts, assistant responses, or
+transcripts. Optional `acc.workspace.json` is user-requested workspace configuration, not
+runtime state.
 
-Next: [Getting started](GETTING_STARTED.md) · [Protocol](PROTOCOL.md) ·
-[Capabilities](CAPABILITIES.md)
+Next: [Getting started](GETTING_STARTED.md) · [How ACC works](HOW_IT_WORKS.md) ·
+[Protocol](PROTOCOL.md) · [Capabilities](CAPABILITIES.md)