agents-can-communicate 0.3.0 → 0.3.1

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)

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.
-
-## Environment
+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.
+
+## 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

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)