agents-can-communicate 0.2.0 → 0.3.1

package/docs/CONFIGURATION.md

@@ -1,18 +1,21 @@
 # Configuration
 
-ACC works with no configuration at all. A workspace is identified by its Git common
-directory when there is one and by the directory itself otherwise. Independently opened
-sessions can communicate without adding runtime state to the project.
-
-`acc.workspace.json` is only for stable workspace identity, roots, and shared claim/context
-policy. It never defines agents, messages, execution state, or delivery endpoints. Project
-map: [README](index.md). Terms used below: [Glossary](GLOSSARY.md).
-
-## When you need a config
-
-- **Identity that survives a move.** Without a config, the same project checked out at two
-  paths is two workspaces, and two people whose clones sit in different directories do not
-  see each other. `workspaceId` fixes that, and it is the usual reason this file exists.
+Start without configuration. ACC identifies a workspace from its Git common directory, or
+from the directory itself when Git is absent. Sessions can communicate only when they run
+as the same operating-system user on the same machine and resolve that same local
+workspace.
+
+Create `acc.workspace.json` only for stable workspace identity, roots, or shared
+claim/context policy. It is optional project configuration that `acc config init` may write
+at your request; runtime state remains in platform app data outside the repository. The
+file never defines agents, messages, execution state, or delivery endpoints. Project map:
+[README](index.md). Terms used below: [Glossary](GLOSSARY.md).
+
+## Decide whether you need a config
+
+- **Identity that survives a local move.** Without a config, the same non-Git project at two
+  paths is two workspaces. `workspaceId` lets the same OS user move or reopen it locally.
+  Matching ids never connect different machines or OS users.
 - **More than one root.** A monorepo whose apps live in separate directories, or a
   workspace that spans sibling checkouts.
 - **Shared policy.** Claim mode and context budget, agreed once and committed, rather than
@@ -21,7 +24,7 @@ map: [README](index.md). Terms used below: [Glossary](GLOSSARY.md).
   to be installed, so `acc doctor` can say what is missing rather than leaving a session
   silently uncoordinated.
 
-### The file
+### Define the file
 
 `acc.workspace.json`, at the root of the workspace. One name, so discovery is a lookup and
 not a search. It is found by walking up from the working directory, because sessions start
@@ -64,7 +67,7 @@ like nothing at all to a parser that ignores what it does not know, and the resu
 team whose policy quietly stopped applying. `extensions` is the one declared door for
 anything ACC does not define.
 
-### What it must never contain
+### Keep runtime state out
 
 Sessions, participants, messages, claims, receipts, intents, events, tokens, credentials.
 All of it is refused, by name, with the key that caused it, for two reasons. Runtime state
@@ -73,7 +76,7 @@ without carrying presence and locks along. And a config lives in a repository, w
 who can open a pull request can edit it — a file that could declare sessions would be a way
 to hand a peer state it should have had to earn.
 
-### Writing one while sessions are running
+### Change identity safely
 
 The config carries the workspace identity, so writing one moves the project to a new
 workspace. Sessions already attached stay on the old one: they keep heartbeating it, they
@@ -90,7 +93,7 @@ pass --force to write anyway.
 
 Close them, or pass `--force` if you mean it — and restart them afterwards.
 
-### Commands
+### Create or validate it
 
 <!-- test:illustration asks a person to confirm; there is nobody to ask in a test -->
 ```bash
@@ -107,7 +110,7 @@ and replacing it on a mistyped command would split one workspace into two.
 thing it is inspecting. With no config present it reports the defaults rather than failing,
 because not having one is a valid state.
 
-## Delivery policy is not project policy
+## Keep delivery consent user-owned
 
 Live delivery may start a model turn and spend that recipient's tokens, so it is configured
 through the recipient's user-owned client installation:
@@ -118,12 +121,15 @@ acc install --adapter codex --delivery off
 
 The allowed values are `off`, `actionable`, and `all`; the default is `off`. This setting
 does not belong in `acc.workspace.json`, where a pull request could opt someone else into
-spending a turn. It also cannot create a capability: when the detected exact client
-version lacks passing live-push evidence, installation keeps the effective policy `off`
-and reports durable next-turn or inbox fallback. No shipped adapter currently qualifies
-for native live push.
+spending a turn. It also cannot create a capability. Exact-version evidence governs
+ordinary hook features; Claude Code live delivery separately requires macOS arm64, version
+2.1.258 or newer, and a current feature probe before installation applies the requested
+policy. If those install-time checks fail, effective policy remains `off` and the installer
+reports next-turn or inbox fallback. Each later session must also pass its own
+generation-bound handshake. A failed session handshake clears or refuses that binding and
+reports degraded reachability; it does not rewrite the installed consent.
 
-## Environment
+## Override local paths and identity
 
 Nothing in `acc.workspace.json` says where state is stored, and nothing there can — that is
 the job of these variables, or the platform's own locations, and ACC refuses any of them
@@ -141,3 +147,7 @@ that resolves inside a workspace.
 | `ACC_MCP_WORKSPACE` | The project `acc-mcp` joins. Without it the server takes the directory the client launched it in, which is rarely the project |
 | `ACC_NO_UPDATE_CHECK=1` | Never ask npm whether a newer ACC exists. `acc update` then says it is off, which is a different answer from "nothing is newer" |
 | `ACC_PROBE_TIMEOUT_MS` | How long to wait for a client to print its version. Three seconds by default: generous on an idle machine, and not always enough on a busy one, where a client that overruns it is reported as not installed |
+| `ACC_NATIVE_DELIVERY_POLICY` | Set only by an ACC-owned shell shim to the consented live policy (`off`, `actionable`, or `all`) before it `exec`s the real client, so the session's hook knows a native transport was activated. Not for a person to set: an ordinary or `ACC_BYPASS=1` launch leaves it unset, and the hook treats missing or invalid values as `off` |
+| `ACC_BYPASS=1` | Runs the unmodified client through an ACC shim: no launch-time check, no native flags, and the reserved policy variable is unset. The escape hatch when you want the vendor command exactly as it was |
+| `ACC_BOOTSTRAP_DEBUG=1` | Lets the internal `acc-bootstrap` check write one safe diagnostic line to stderr. Off, it is silent, and it never writes to stdout |
+| `CODEX_HOME` | Codex's own home, honoured when locating the Codex App Server daemon's control socket for native delivery. Codex sets it; ACC only reads it |

package/docs/DESIGN_DECISIONS.md

@@ -1,8 +1,10 @@
 # Design decisions
 
-Why ACC is shaped the way it is, and what is deliberately still open.
+Use this log to understand constraints that should survive refactors and proposals that
+remain open. Runtime contracts live in [Protocol](PROTOCOL.md); this page records why the
+boundaries exist.
 
-## Settled
+## Preserve these decisions
 
 | Decision | Reason |
 |---|---|
@@ -24,7 +26,7 @@ Why ACC is shaped the way it is, and what is deliberately still open.
 | Node 24 (current production LTS) | Uses `node:test`, modern `fs` promises, and no transpiler. |
 | MCP session from launch config | Never from `initialize` or `clientInfo` — those are attacker-controllable. See the threat scenarios in [SECURITY_MODEL.md](SECURITY_MODEL.md) (scenario 8). |
 
-## Rejected, and why
+## Avoid these rejected designs
 
 | Rejected | Why |
 |---|---|
@@ -36,6 +38,8 @@ Why ACC is shaped the way it is, and what is deliberately still open.
 | Reporting queued messages as delivered | A delivery state that overstates itself is worse than no state. |
 | Guessing file paths out of shell commands | It would block work at random and still miss real writes. See [CAPABILITIES.md](CAPABILITIES.md). |
 
+### Reversals backed by failures
+
 **Reversed in 0.1.11: removing the client's hook-trust record on uninstall.**
 0.1.9 took Codex's `[hooks.state."<plugin>:…"]` tables out on uninstall,
 reasoning they named a plugin that was gone. The check behind that reasoning
@@ -72,7 +76,7 @@ declared. Coverage is deliberately partial, and
 [CAPABILITIES.md](CAPABILITIES.md) says where it ends: an agent that knows
 where a guard stops behaves better than one that believes it absolute.
 
-## Still open
+## Decide these later
 
 1. **Storage backend.** The hardened filesystem store ships first. A transactional backend
    can go behind the same interface later — but not merely to avoid a dependency.

package/docs/GETTING_STARTED.md

@@ -1,145 +1,121 @@
 # Getting started
 
-ACC begins with two AI sessions that you open yourself. It does not create a team or choose
-which model does what. The first useful run is a question that travels from one session to
-the other, receives a reply in the same thread, and is acknowledged without you copying
-the message between windows.
-
-```mermaid
-sequenceDiagram
-  participant A as First session
-  participant ACC
-  participant B as Second session
-  A->>ACC: durable question
-  ACC-->>B: next-turn offer or inbox fallback
-  B->>ACC: reply in the same thread
-  ACC-->>A: next-turn offer or inbox fallback
-```
+Install ACC, open the AI sessions you already use, and give them related work. Supported
+integrations make peers visible and teach each agent how to communicate. You do not need to
+carry messages between windows or add coordination instructions to your task prompts.
 
-## 1. Install once per machine
+## 1. Install once on this machine
 
-Install the package, then let ACC wire only the clients it detects:
+ACC requires macOS or Linux and Node.js 24 or newer.
 
-<!-- test:command -->
 ```bash
-acc install
+npm install -g agents-can-communicate
 ```
 
-Restart those clients because hooks load at startup. Codex also asks you to trust the
-plugin. `acc doctor` names anything still missing and reports the effective delivery mode
-for each detected version.
-
-## 2. Open two sessions normally
-
-Open Codex, Claude Code, Gemini CLI, Grok, or Kimi Code in the same project exactly as you
-would without ACC. A generic MCP client can participate by running `acc-mcp`. ACC never
-launches or owns either session.
-
-In either window:
-
+<!-- test:command -->
 ```bash
-acc status
+acc install
 ```
 
-The roster gives the participant ids used by `--to`. If it shows only one session, fix the
-second client's installation or workspace path before testing communication.
-
-## 3. Publish intent, then claim narrowly
-
-Intent is cheap awareness and grants no protection:
+The installer connects only the supported clients it finds. Open a new terminal and
+restart any running clients so they load their integrations. Codex asks you to trust its
+plugin once.
 
-```bash
-acc work --summary "updating receipt rendering" --mode edit \
-  --hint 'file:packages/cli/src/main.mjs'
-```
+If you opt into Claude Code's experimental idle delivery, Claude also shows its own
+development-channel warning at every startup. The feature is off by default, can spend
+model tokens, and currently requires Apple Silicon macOS, zsh, and Claude Code 2.1.258 or
+newer. You do not need it for durable messages or supported next-turn delivery.
 
-Reserve only what the session is about to change:
+## 2. Open two sessions and give them ordinary tasks
 
-```bash
-acc claim --resource 'file:packages/cli/src/main.mjs' \
-  --reason "updating receipt rendering"
-```
+Start each client normally in the same project. ACC does not launch, supervise, or assign
+work to either session. For example:
 
-Exit code `5` means an overlapping live claim exists. Ask its owner or narrow the edit;
-do not silently work around it. A claim can be `guarded` only where the client exposes a
-certified write guard. Otherwise it remains useful but `advisory`.
+| Session | Your prompt |
+|---|---|
+| Codex | Add an account-registration endpoint. |
+| Claude Code | Build the account-registration screen. |
 
-## 4. Send a real question
+Those are complete prompts. The integration tells each agent that peers are present and
+provides the coordination instructions. If an agent notices that the screen depends on the
+endpoint contract, it can identify the peer, ask for the request and response shape, and
+continue with the answer.
 
-From the first session, address a participant listed by `acc status`:
+The sessions may use different supported clients or two instances of the same client.
+Same-client addresses can be ambiguous when several instances are live; agents use the
+exact participant ids in the roster when needed. See [Concepts](CONCEPTS.md) for participant
+and session identity.
 
-```bash
-acc message --to models --type question --subject "receipt wording" \
-  --body "Should the UI say offered or delivered after the transport accepts bytes?" \
-  --client-message-id client_receipt_wording_1
-```
+## 3. Watch for useful coordination
 
-The output starts with `recorded message_x`. That is the durable guarantee. Any following
-delivery diagnostic is acceleration, not the source of truth. Reuse the explicit
-`client_receipt_wording_1` key when retrying after an uncertain result; it returns the same
-logical message instead of creating a duplicate.
+Look for an agent discovering a peer, publishing the files it expects to change, noticing a
+shared dependency, asking a focused question, or answering one in the same thread. These
+events appear in the agent's normal activity; the exact presentation depends on the client.
 
-## 5. Read and reply from the second session
+ACC provides awareness and communication tools. It cannot guarantee that a model will
+notice every dependency or coordinate on every task. Each agent decides whether a peer is
+relevant under its own instructions, context, and permissions.
 
-A certified hook may offer the question on the recipient's next normal turn. Grok, MCP,
-unknown versions, and any missed projection use the same durable recovery path:
+The commands behind that activity belong to the agents' installed skill. They can publish
+intent, make an advisory or guarded claim, send and reply to messages, acknowledge a thread,
+and leave a handoff. If you want to inspect that interface, use the [CLI reference](CLI.md)
+or follow the interaction through [How ACC works](HOW_IT_WORKS.md).
 
-```bash
-acc inbox
-acc inbox --message message_x
-acc reply --message message_x \
-  --body "Use offered. It proves transport acceptance, not that the model read it."
-```
+## 4. Know when messages arrive
 
-`reply` creates an `answer` in the original thread and acknowledges the recipient's
-receipt for the question atomically. It does not mark the requested work complete. The
-first session receives the answer through its own next-turn or inbox path; you do not copy
-the peer body between sessions.
+Every message is recorded before ACC attempts faster delivery. Every participant has a
+durable inbox, which is the universal recovery path.
 
-Use `acc ack --message message_x` only when the message asks for acknowledgement and no
-written reply is needed.
+On exact client versions and platforms with captured support, Codex, Claude Code, Gemini
+CLI, and Kimi Code can receive a message at the next normal turn. That does not wake an idle
+session. Grok, generic MCP clients, unknown versions, and unsupported platforms use the
+durable inbox instead.
 
-## 6. Hand off while context still exists
+Claude Code's optional native channel is the only shipped idle-delivery path. It is
+experimental, never interrupts a turn already in progress, and remains subject to current
+reachability and recipient policy. Codex native live delivery is withdrawn; Codex uses its
+certified next-turn path or inbox. Read [Capabilities](CAPABILITIES.md) for exact versions,
+platforms, and limitations.
 
-```bash
-acc finish --goal "update receipt rendering" --status partial \
-  --completed "CLI wording changed" --remaining "MCP docs" \
-  --blocker "waiting for fixture"
-```
+Delivery evidence is deliberately narrow: `queued -> offered -> retrieved -> acknowledged`.
+An offer is not proof that the model read anything, retrieval is not proof of attention, and
+a reply settles the communication obligation rather than proving that work is complete.
 
-`finish` records a structured handoff, releases that ACC session's claims, and ends its ACC
-presence. It does not close the external client.
+## 5. Keep the workspace boundary clear
 
-## Delivery expectations
+ACC is local to the same machine and operating-system user. Git worktrees of one repository
+share an ACC workspace while keeping their separate checkout facts. Git is optional, but
+two unrelated plain folders do not share a workspace merely because people consider them
+the same project.
 
-Durable inbox delivery works for every participant. Certified next-turn delivery currently
-exists only for exact captured versions of Codex, Claude Code, Gemini CLI, and Kimi Code.
-Grok and generic MCP poll. No current adapter has certified native live push. Although
-`acc install --delivery off|actionable|all` defines recipient policy, unsupported or
-uncertified clients keep effective policy `off` and report their fallback beside the
-adapter result.
+Messages and runtime state live in platform app data outside the repository. ACC never
+collects or shares raw transcripts. An optional `acc.workspace.json` can provide a stable
+workspace id, multiple roots, or project policy; it is user-requested configuration, not
+runtime state. See [Configuration](CONFIGURATION.md) and the
+[non-Git example](https://github.com/automatis-tools/agents-can-communicate/blob/main/examples/non-git-research.md).
 
-## Optional workspace configuration
+## Diagnose or remove it
 
-No file is required. Use one only for a stable shared workspace id, multiple roots, or
-project policy:
+If a peer does not appear or delivery differs from what you expected, run this from the
+project directory:
 
 <!-- test:command -->
 ```bash
-acc config validate
+acc doctor
 ```
 
-See [Configuration](CONFIGURATION.md) before writing it. Runtime messages and sessions
-never belong in that committed file.
+The report names detected clients, installed integrations, exact capability downgrades,
+and the next action. Continue with [Troubleshooting](TROUBLESHOOTING.md).
 
-## Uninstall
+To remove ACC's integrations:
 
+<!-- test:command -->
 ```bash
 acc uninstall
 ```
 
-ACC removes only installation bytes that still match what it wrote. User-modified client
-settings remain in place.
+Uninstall removes only bytes ACC wrote that still match its install record. User edits are
+reported and preserved.
 
 Next: [Why ACC](WHY_ACC.md) · [Capabilities](CAPABILITIES.md) · [CLI](CLI.md) ·
 [Troubleshooting](TROUBLESHOOTING.md)

package/docs/GLOSSARY.md

@@ -1,8 +1,8 @@
 # Glossary
 
-- **Workspace** — one local coordination room; all worktrees of a Git repository share it.
-- **Participant** — the stable address that sends and receives messages.
-- **Session** — one independently opened client conversation participating in a workspace.
+- **Workspace** — one same-machine, same-OS-user coordination room; all worktrees of a Git repository share it.
+- **Participant** — the address that sends and receives messages; it survives unrelated conversations only when explicitly configured.
+- **Session** — one independently opened client conversation participating in a workspace; its id supplies the default participant address.
 - **Generation** — the token proving a mutation belongs to the current opening of a session.
 - **Presence** — `online`, `stale`, or `offline`, based only on observed heartbeat and pid facts.
 - **Intent** — a session's current summary and resource hints; awareness, not permission.
@@ -16,7 +16,7 @@
 - **Retrieved** — the participant received the body; not proof of model attention.
 - **Acknowledged** — that participant explicitly acknowledged or replied; a reply is not proof requested work finished.
 - **Next-turn delivery** — certified projection at the client's next normal turn; it never interrupts an active turn.
-- **Live push** — optional delivery to an already-running session through an official certified client API. No shipped adapter currently qualifies.
+- **Live push** — optional delivery to an already-running session through an official certified client API. Claude Code 2.1.258+ on macOS arm64 qualifies, behind an opt-in; it waits for a turn in progress rather than interrupting it.
 - **Recipient policy** — `off`, `actionable`, or `all`; opt-in permission to spend a turn, not a capability.
 - **Delivery binding** — ephemeral, generation-bound reachability data owned by an adapter.
 - **Fallback** — durable inbox or exact-certified next-turn recovery when live delivery is unavailable.

package/docs/HOW_IT_WORKS.md

@@ -0,0 +1,163 @@
+# How ACC works
+
+Suppose Codex is adding an account-registration endpoint while Claude Code builds the
+registration screen. You gave each session an ordinary task. ACC supplies the awareness
+and communication layer around their work; the agents decide whether and how to use it.
+
+This page follows the dependency from discovery to an acknowledged answer. For exact record
+shapes and state rules, use [Protocol](PROTOCOL.md). For package boundaries, storage, and
+recovery, use [Architecture](ARCHITECTURE.md).
+
+```mermaid
+sequenceDiagram
+  participant U as User
+  participant C as Codex
+  participant ACC
+  participant A as Claude Code
+  U->>C: Add the registration endpoint
+  U->>A: Build the registration screen
+  ACC-->>C: Claude Code is a peer
+  ACC-->>A: Codex is a peer
+  A->>ACC: Ask Codex for the endpoint contract
+  ACC-->>C: Offer the question or keep it in inbox
+  C->>ACC: Reply with the contract
+  ACC-->>A: Offer the answer or keep it in inbox
+```
+
+## 1. The integrations introduce the peers
+
+`acc install` adds supported hooks, plugins, or extensions to native clients it finds. At
+session startup, such a client calls `acc-hook`, which registers the session in the local
+ACC workspace. The native integration also gives the agent a small skill describing peer
+discovery, messages, replies, claims, and handoffs.
+
+A generic MCP client instead joins through `acc-mcp`, which resolves its configured
+participant and workspace when tools or resources are called. It exposes the coordination
+tools but does not install the native clients' skill. See its
+[manual MCP boundary](MCP.md#account-for-the-manual-boundary).
+
+ACC does not add instructions to the user's task prompt, create a team, or choose work. The
+agent still operates under its own conversation, permissions, and client policy.
+
+Sessions meet only when they resolve to the same local workspace. Git worktrees of one
+repository share a workspace through the Git common directory, while retaining separate
+checkout and branch facts. A plain directory uses its canonical path unless optional
+workspace configuration supplies a stable id or additional roots. Git is not required.
+
+A workspace is local to one machine and operating-system user. ACC is not a remote sync
+service, even if project files are synchronized elsewhere.
+
+## 2. Each agent shares a small amount of work context
+
+The Codex session may publish “adding the registration endpoint” with a hint for its API
+files. Claude may publish “building the registration screen” with a UI hint. This intent is
+short, explicit coordination data, not a copy of either conversation.
+
+When peers are available, the integration can project their identity, intent, relevant
+claims, and pending messages into a supported normal turn. The agent can then notice that
+its work depends on a peer. ACC does not run a hidden classifier and does not guarantee the
+model will coordinate; relevance remains the agent's decision.
+
+Presence and intent can stay ephemeral while a session is alone. Durable workspace history
+materializes when a second session appears or an agent creates the first durable message,
+claim, or handoff. Runtime state lives in platform app data outside the repository.
+
+## 3. A dependency becomes a direct question
+
+Claude needs the endpoint contract, so it looks up the peer and sends an addressed
+`question`. A client name such as `codex` resolves when exactly one peer session of that
+client is eligible. If several Codex sessions are live, the agent uses the exact participant
+id from `acc status --json`.
+
+The sender is not granting itself authority over the recipient. Messages are attributed,
+untrusted peer input. A `request` asks for action and a result, but it is not an order; the
+receiving agent evaluates it under its own instructions and permissions.
+
+## 4. ACC records before it tries delivery
+
+Sending the question commits the message and one `queued` receipt for each recipient in a
+single filesystem transaction. Only then does ACC attempt to make it arrive sooner. If a
+hook, client, or experimental transport is unavailable, the recorded question remains in
+the recipient's durable inbox.
+
+That order is the central reliability guarantee:
+
+```text
+agent sends -> durable message and queued receipt -> optional delivery attempt
+```
+
+The first message is also the root of its thread. Retries can carry a `clientMessageId` so
+equivalent repeats return the original record while conflicting reuse is rejected. Room
+messages resolve their recipients at commit time; later arrivals do not gain retroactive
+receipts. [Protocol](PROTOCOL.md) defines these rules precisely.
+
+## 5. The receiving client chooses the delivery path
+
+All recipients have the same durable record, but adapters expose different acceleration:
+
+- **Durable inbox:** universal recovery. An agent can retrieve the complete addressed
+  message with `acc inbox`, including by exact message id after compaction.
+- **Next normal turn:** exact captured versions of Codex, Claude Code, Gemini CLI, and Kimi
+  Code can receive complete attributed peer context when the user next prompts that client.
+  This does not wake an idle session.
+- **Optional Claude Code channel:** supported Claude Code versions on Apple Silicon macOS
+  may receive an addressed actionable message while idle. This is experimental, off by
+  default, can spend tokens, never interrupts a running turn, and requires the vendor's
+  visible development-channel warning.
+
+Codex native live delivery is withdrawn because the required remote mode hides the
+session's real workspace. Grok, generic MCP, unknown versions, and uncaptured platforms use
+inbox polling. [Capabilities](CAPABILITIES.md) lists the evidence and exact fallbacks.
+
+When a complete projected body cannot fit the configured byte budget, ACC keeps the message
+id and exact inbox recovery command rather than silently truncating the peer's words.
+
+## 6. The reply stays in the same thread
+
+Codex replies with the request and response fields. The reply operation creates an `answer`
+for Claude in the original thread and acknowledges Codex's receipt for the question in one
+transaction. For a message that requires acknowledgement but no answer, the recipient uses
+`ack` instead.
+
+Receipts describe evidence, not assumptions:
+
+```text
+queued -> offered -> retrieved -> acknowledged
+```
+
+- `queued` means the message and receipt are durable;
+- `offered` means bytes crossed ACC's transport boundary or a certified client accepted
+  them, not that the model read them;
+- `retrieved` means the participant explicitly fetched the message, not that a model paid
+  attention; and
+- `acknowledged` means the participant acknowledged or replied, not that requested work is
+  complete.
+
+There is no `seen` receipt and no ACC task state such as accepted, running, or done.
+
+## 7. Claims warn before edits overlap
+
+Before changing files, an agent can publish intent and claim a narrow resource such as
+`file:packages/api/**`. Another live session attempting an overlapping claim receives exit
+code `5` with the holder, giving the peers a chance to narrow or sequence their work.
+
+Claims are not operating-system locks. A claim is `guarded` only when every relevant live
+client exposes a captured pre-write guard for the path ACC can recognize. Otherwise it is
+`advisory`. Even a guarded claim cannot stop an unrelated program or a write path the client
+does not expose. [Concepts](CONCEPTS.md#intent-is-awareness-a-claim-commits) explains the
+user-facing distinction.
+
+## 8. The boundaries remain visible
+
+ACC stores only coordination data an agent explicitly publishes: identity, presence,
+one-line intent, claims, messages, replies, handoffs, receipts, and events. It never collects
+or shares raw prompts, assistant responses, or transcripts. Peer bodies are framed as
+untrusted data and remain subject to the receiving session's permissions.
+
+Hooks have a short time limit and fail open. A coordination failure may remove awareness or
+force inbox fallback, but ACC must not be the reason a client action stops. Unknown versions
+and platforms inherit no capability; `acc doctor` reports the downgrade and next action.
+
+Continue with [Capabilities](CAPABILITIES.md) for client-specific behavior,
+[Security model](SECURITY_MODEL.md) for trust boundaries, or
+[Architecture](ARCHITECTURE.md) to trace these steps through the packages.

package/docs/MCP.md

@@ -1,9 +1,9 @@
 # MCP
 
-`acc-mcp` lets a client with no native ACC adapter participate over stdio. It exposes the
-same durable messages, threads, receipts, intent, claims, and handoffs, but it cannot infer
-the client's lifecycle, intercept writes, inject a normal turn, or push a message. The
-client polls tools under its own control.
+Use `acc-mcp` when a client can call MCP tools but has no native ACC adapter. The server
+exposes durable messages, threads, receipts, intent, claims, and handoffs over stdio. It is
+a manual polling integration: it cannot infer the client's lifecycle, intercept writes,
+inject a normal turn, or push a message.
 
 ```mermaid
 graph LR
@@ -11,7 +11,7 @@ graph LR
   M --> S[("ACC durable store")]
 ```
 
-## Register
+## Configure the server
 
 ```json
 {
@@ -33,7 +33,7 @@ The server implements MCP protocol revision `2026-07-28` over newline-delimited
 stdio. Tool input schemas are closed: unknown fields and invalid conditional shapes are
 rejected before a session is resolved.
 
-## Tools
+## Call the durable tools
 
 | Tool | Required input | Optional input |
 |---|---|---|
@@ -63,7 +63,7 @@ resolves the configured MCP participant and advances only the returned receipts
 `retrieved`, just like the inbox tool. Snapshot and roster reads do not advance receipts.
 A full snapshot is for explicit workspace forensics.
 
-## Capability floor
+## Account for the manual boundary
 
 The generic MCP capability declaration is all false:
 
@@ -79,7 +79,7 @@ An MCP participant therefore reports `advisory` enforcement and `manual` lifecyc
 workspace protection is the weakest live participant's real guarantee, one MCP session
 makes guarded claims advisory for the room.
 
-## Durable polling semantics
+## Poll without overstating delivery
 
 Every outgoing message commits first. `acc_message`, `acc_request`, `acc_reply`, and
 `acc_finish` cannot promise push; delivery results remain queued with a durable diagnostic.