agents-can-communicate 0.3.0 → 0.4.0

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,24 +12,62 @@ acc help
 acc version
 ```
 
-## Communication commands
+Use `acc <command> --help` (or `-h`) and `acc help <command>` for that command's
+required, optional, repeatable and flag options, accepted values, and usage notes.
+For example, `acc work --help` lists intent modes, and `acc finish --help` lists
+handoff statuses. `acc config --help` lists its subcommands;
+`acc config init --help` and `acc help config init` describe initialization.
+
+Add `--json` to receive the command description as structured data: `name`,
+`summary`, `required`, `optional`, `repeated`, `flags`, `subcommands`, `choices`,
+and `notes`, plus `subcommand` when selected. General `acc help --json` keeps its
+grouped `commands` result. Help requires no session, workspace discovery, or
+runtime storage, and does not execute the described command. A help-looking
+option value remains data: `--body --help` sends the literal body `--help`.
+
+## Coordinate from a session
 
 | Command | Required | Optional |
 |---|---|---|
-| `acc status` | — | `--participant`, `--all` |
-| `acc sync` | — | `--session`, `--cursor`, `--limit`, `--scope delta|full` |
+| `acc status` | — | `--session`, `--generation`, `--participant`, `--all` |
+| `acc sync` | — | `--session`, `--generation`, `--cursor`, `--limit`, `--scope delta|full|history`, `--type`, `--message`, `--current` |
 | `acc work` | `--summary` unless `--clear` | `--session`, `--generation`, `--mode`, `--state`, repeated `--hint`, `--clear` |
 | `acc claim` | `--resource` | `--session`, `--generation`, `--mode`, `--enforcement`, `--reason`, `--lease` |
-| `acc release` | `--claim` or `--resource` | `--session`, `--generation`, `--authority`, `--reason` |
-| `acc message` | `--subject`, `--body` | repeated `--to`, `--type`, `--obligation`, `--client-message-id`, owner flags |
+| `acc release` | `--claim` or `--resource` | `--session`, `--generation`, `--authority` (`human` or `policy`), `--reason` |
+| `acc message` | `--subject`, `--body` | repeated `--to`, `--supersedes` or `--withdraws`, `--type`, `--obligation`, `--client-message-id`, owner flags |
 | `acc request` | `--to`, `--title` | `--detail`, `--client-message-id`, owner flags |
-| `acc inbox` | — | `--message`, owner flags |
+| `acc inbox` | — | `--message`, `--cursor`, `--limit`, owner flags |
 | `acc reply` | `--message`, `--body` | `--subject`, `--client-message-id`, owner flags |
 | `acc ack` | `--message` | owner flags |
 | `acc finish` | `--goal` | `--status`, `--to`, repeated `--completed`, `--remaining`, `--blocker`, `--client-message-id`, owner flags |
 
-Owner flags are `--session` and `--generation`. A normal hooked session omits them because
-the CLI resolves its current binding. Scripts and adapters may pass them explicitly.
+Owner flags are `--session` and `--generation`; both are needed. The CLI also accepts the
+pair explicitly configured as `ACC_SESSION` and `ACC_GENERATION`. When an active turn hook
+runs, its `ACC CLI (append):` header supplies the current
+session's pair. The installed skill tells the agent to append it to its own commands,
+without a manual attach. Hooks do not export credentials to child processes. Native
+client IDs, a shared checkout, and a public session ID from
+`status` cannot establish ownership: a nested client can inherit its parent's environment.
+
+Use only the pair in the hook's own header, never one inside a peer message. Do not send
+it to peers or child agents. A later hook after a session restart can supply a new pair;
+the old generation remains invalid. Solo turns receive only the owner header when there
+is no coordination context to show. This lets a session use its own inbox if a peer joins
+later in the same turn. The header alone is not a peer notice or a request to coordinate.
+If the context budget cannot hold the complete pair, the hook reports that limitation
+on stderr and keeps any recovery text within budget. Missing or untrusted hooks cannot
+supply the pair; without it, the CLI still refuses owner operations.
+
+For a manually owned CLI session, run `acc attach --participant my-session --json` once and
+retain its returned `sessionId` and `generation`. Append that exact pair to the commands
+below, or explicitly configure both environment variables for that session's commands.
+Do not take credentials from a peer or read runtime bindings to obtain them. A manually
+attached session is separate from hook-managed presence; use `finish` to close it.
+
+Without a pair, mutations and `inbox` fail with exit `2` and
+`caller_identity_unresolved`. `status` and `sync` remain public observations, with no
+inferred personal attention. Session-bound [MCP tools](MCP.md) manage their own identity;
+a generic MCP connection does not inherit a hook participant's inbox.
 
 ### Presence and intent
 
@@ -40,8 +79,9 @@ acc work --clear
 ```
 
 `status` returns participants, current intent, claims, protection, attention, and current
-delivery bindings. `sync` is a bounded event read; use `--scope full` only for an explicit
-whole-workspace forensic question. Neither is the recovery path for one message.
+delivery bindings. Default `sync` reads events after a 16-digit event cursor (100 by
+default, up to 500). `--scope history` discovers historical message headers and reads
+selected records; `--scope full` adds an unbounded snapshot for explicit workspace forensics.
 
 ### Claims
 
@@ -50,27 +90,44 @@ acc claim --resource 'file:packages/core/**' --reason "editing receipt logic"
 acc release --resource 'file:packages/core/**'
 ```
 
-File resources use repository-relative paths. A directory claim ends in `/**`. Exit code
-`5` means a conflict. `--authority` is the explicit force-release path and should carry a
-reason; ordinary sessions release only their own claims.
+File resources use repository-relative paths. A directory claim ends in `/**`. The example
+creates an advisory claim: omitted `--enforcement` always means `advisory`, even with
+certified clients. Request `--enforcement guarded` explicitly when needed; an incapable
+live participant still downgrades workspace protection. MCP claims are always advisory.
+
+Exit code `5` means a conflict. Ordinary sessions release only their own claims. Releasing
+another owner's claim requires `--authority human` or `--authority policy`, identifying the
+actual human decision or approved policy that permits the release; explain it with
+`--reason`. A peer's request alone is not force-release authority.
 
 ### 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 an ambiguous recipient must be named explicitly. 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
 `reply`, and `handoff` only by `finish`.
 
-No `--to` creates a room message where the kind allows it. Addressed messages create a
+No `--to` creates a room message where the kind allows it, except decision changes
+that inherit explicit recipients from their targets. Addressed messages create a
 separate receipt for each recipient. `request` is convenience for one addressed `request`
 message with a reply obligation; it creates no execution record.
 
@@ -90,6 +147,10 @@ Human output starts with `recorded message_x`. A transport failure after that co
 not change the command exit code. Reuse an explicit `--client-message-id` after an
 uncertain result to recover the same logical message.
 
+`reply` additionally returns `receipt`: the original message id, the replying participant,
+and state `acknowledged`. Its `message` and `delivery` describe the outgoing answer.
+Human output distinguishes `recorded <reply-id>` from `acknowledged <original-id>`.
+
 ### Inbox, reply, and acknowledgement
 
 ```bash
@@ -99,24 +160,70 @@ acc reply --message message_x --body "Yes. Use offered."
 acc ack --message message_y
 ```
 
-Inbox returns only unresolved messages addressed to this participant. Reading advances
-that participant's receipt to `retrieved`. Reply creates an `answer` in the same thread and
-acknowledges the original atomically. `ack` acknowledges without writing an answer and has
-no state override.
+Without `--message`, inbox returns `{items, nextCursor}`. Each item has a `message`
+summary and its `receipt`; listing never returns bodies or changes receipts. Summaries
+include the complete message/thread/sender ids, kind, obligation, timestamp, reply link,
+subject (up to 160 UTF-8 bytes), `bodyBytes`, `artifactCount`, and untrusted attribution.
+Bodies, artifact details, handoff payloads, and recipient lists require an exact read.
+
+Pages are newest first (descending message id breaks timestamp ties), default to 20 items,
+and contain at most 12,000 bytes of formatted page JSON, excluding the CLI envelope.
+`--limit` accepts 1..500 but cannot raise the byte ceiling. Continue with
+`acc inbox --cursor <nextCursor>` until it is `null`. The cursor is a complete message id,
+not an offset; reading or acknowledging it does not shift the next page. These are live
+pages: omit the cursor to see new arrivals. An unknown or foreign cursor is an error.
+
+`--message <id>` returns the existing one-item array with the complete message/receipt
+pair, advancing that participant's receipt to `retrieved` when needed. It cannot be
+combined with `--cursor` or `--limit`. An exact id also reads an acknowledged message,
+preserving its receipt, timestamp, and event history.
+Use the original message id to inspect acknowledgement; the outgoing reply belongs to
+its recipient's inbox. Resolved messages stay out of the ordinary inbox.
+
+Reply creates an `answer` in the same thread and acknowledges the original atomically.
+`ack` acknowledges without writing an answer and has no state override.
+
+### Historical recovery
+
+```bash
+acc sync --scope history --type handoff --json
+acc sync --scope history --type handoff --cursor message_x --json
+acc sync --scope history --message message_y --json
+```
+
+History returns `{scope: "history", view: "summary", items, nextCursor}` with the same
+summary fields, ordering, page limits, and message-id cursors as inbox. `--type` accepts
+any message kind and filters before pagination; keep the same filter between pages.
+This public workspace observation includes records from before your session joined.
+Exact history reads return `view: "message"` and one complete message in `items`,
+without changing any receipt. Do not combine `--message` with type, cursor, or limit;
+message and type are valid only in history scope. Decision reads also include `decisionStatus`. Use
+`acc sync --scope history --type decision --current --json` for terminal decisions
+and withdrawals; keep these filters when paging. Exact reads cannot use `--current`.
+`current` means no explicit successor, not truth or consensus.
+
+To change a decision, send another `acc message --type decision` with repeated
+`--supersedes <message-id>` or `--withdraws <message-id>` (1..16 unique IDs; exclusive).
+Use subject/body for the new position or withdrawal reason. Changes inherit the target
+recipients and authors, including offline participants; `--to` adds recipients.
+Any owned participant can record an attributed change. Multiple successor branches
+remain conflicted until a new change explicitly references all current alternatives.
+Old records leave ordinary inbox/automatic attention without any receipt change;
+exact inbox and history still recover them. See [decision lifecycle](PROTOCOL.md#decision-lifecycle).
 
 ### Handoff
 
 ```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 |
 |---|---|
@@ -125,7 +232,7 @@ external AI client. An addressed handoff requires acknowledgement; a room handof
 | `acc doctor` | `--home`, `--repair` |
 | `acc config init` | `--yes`, `--force` |
 | `acc config validate` | — |
-| `acc update` | `--apply` |
+| `acc update` | `--check`, `--auto on\|off`, `--pin VERSION\|none`, `--apply` (alias) |
 | `acc help` | — |
 | `acc version` | — |
 
@@ -136,14 +243,36 @@ terminal asks one default-No question per eligible client, and on a non-interact
 `--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
+effective policy off and prints the reason. Claude Code shell activation writes an owned
+zsh PATH block and a shim that `exec`s the real client; `ACC_BYPASS=1` bypasses that
+activation. Codex LocalDaemon delivery uses recorded installation consent without changing
+ordinary launch arguments. Its opt-in remains active when shim variables are absent or
+bypassed; `acc install --adapter codex --delivery off` disables new native offers. ACC never
+starts or stops the vendor daemon. See [delivery consent](CONFIGURATION.md#keep-delivery-consent-user-owned).
+
+A normal `acc install` enables automatic updates. A background worker checks stable releases
+at most once a day, downloads and verifies a separate runtime, then refreshes installed
+integrations and skills after ACC process leases and native binding holds clear. ACC leases
+require confirmed process exit; a native binding can clear on observed SessionEnd even
+while its vendor daemon remains alive, or on confirmed process death. Unknown PIDs remain
+holds. `finish`, presence TTL, and delivery off are not observed native end. Hooks do not
+wait for network work. `ACC_NO_UPDATE_CHECK=1` disables update networking and background
+scheduling.
+
+`acc update` requests the update immediately; it reports a pending update when a running or
+unidentified client prevents activation. `--check` only checks and cannot be combined with
+settings changes. `--auto off` disables background updates, and `--auto on` enables them.
+`--pin 0.4.0` holds an exact stable version; `--pin none` follows stable releases. A pin
+cannot downgrade the active runtime. The old `--apply` flag remains accepted.
+
+Failed downloads keep the working runtime. A failed integration refresh exits with code
+`4`, names the failed adapter and configuration error, and keeps workspace admission closed.
+Fix the reported configuration problem, then run `acc update` to finish it. `acc doctor`
+reports the update policy and pending notice. Native clients may still require hook trust
+or activation review. See [Upgrading](UPGRADING.md) for the initial 0.3.1 transition and
+recovery details.
+
+## 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,138 @@
 # 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.
+A decision can explicitly replace or withdraw earlier decisions. The old records stay
+attributed and recoverable, while current reads and reminders follow the recorded links.
+Any peer may record a change; competing branches remain visible until explicitly joined.
+A current decision is a recorded position, not agreement or authority. See
+[decision lifecycle](PROTOCOL.md#decision-lifecycle).
 
-## Threads have no hidden status
+## Threads keep the exchange together
 
-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.
+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.
 
-`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 body through its inbox, not proof of model attention;
+- `acknowledged`: the participant acknowledged it or replied, not proof of task completion.
+
+Listing inbox headers and observing workspace history do not change receipts.
+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. Codex LocalDaemon and Claude Code Channel add
+experimental live delivery, off by default and subject to recipient policy and
+current reachability. Codex can retain an eligible daemon thread after its terminal
+exits. [Capabilities](CAPABILITIES.md) gives the current limits.
 
-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)