agents-can-communicate 0.3.0 → 0.4.0

package/docs/CONFIGURATION.md

@@ -1,27 +1,27 @@
 # 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
+context budget. 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
-  each person's machine deciding.
-- **Stated expectations.** `requiredAdapters` records which harnesses this project expects
-  to be installed, so `acc doctor` can say what is missing rather than leaving a session
-  silently uncoordinated.
+- **Shared context budget.** Set the ceiling for supported injected turn context once for
+  the workspace.
 
-### 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
@@ -36,10 +36,8 @@ link can point anywhere, including at a file the repository does not control.
   "displayName": "Example",
   "roots": ["."],
   "policy": {
-    "claimMode": "advisory",
     "contextBudgetBytes": 6000
-  },
-  "requiredAdapters": []
+  }
 }
 ```
 
@@ -49,11 +47,16 @@ link can point anywhere, including at a file the repository does not control.
 | `workspaceId` | Stable identity, portable id | required |
 | `displayName` | What peers see in a roster | the directory name |
 | `roots` | Directories in this workspace, relative to the config | `["."]` |
-| `policy.claimMode` | `advisory` or `guarded` | `advisory` |
+| `policy.claimMode` | Validated compatibility metadata (`advisory` or `guarded`); does not select claim enforcement | `advisory` |
 | `policy.contextBudgetBytes` | Ceiling on injected turn context, 1–64000 | `6000` |
-| `requiredAdapters` | Harnesses this project expects | `[]` |
+| `requiredAdapters` | Validated compatibility metadata; does not affect `acc doctor` diagnostics | `[]` |
 | `extensions` | Anything else, namespaced by whoever wrote it | `{}` |
 
+`policy.claimMode` and `requiredAdapters` are stored but have no claim or doctor effect in
+0.4. CLI claims default to advisory; request `--enforcement guarded` on each claim when
+appropriate, subject to every live participant's certified guard. MCP claims remain
+advisory. Do not use these metadata fields to configure protection or missing-client checks.
+
 Roots are refused if they are absolute or escape the workspace. An absolute root is one
 machine's layout committed to a shared repository, and `packages/../../elsewhere` reaches
 outside the boundary the workspace is supposed to be. The check counts path segments, so an
@@ -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,24 +93,32 @@ 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
 acc config init        # preview, then write after you agree
-acc config validate    # read-only; reports what applies
+acc config validate    # read-only; checks acc.workspace.json in the selected directory
 ```
 
+`init` and `validate` operate only on `acc.workspace.json` directly inside the selected
+`--cwd` directory (the current directory when omitted). Unlike ordinary workspace discovery,
+they do not walk upward. Pass `--cwd` with the directory containing the config you intend
+to inspect or create. A nested `init` can create a new config that shadows an ancestor;
+check the ancestor first.
+
 `init` shows the exact file it would write and waits. In a non-interactive run — a pipe, a
 CI job, an agent — there is nobody to ask, so it refuses unless you pass `--yes`. It never
 overwrites an existing config: a committed identity is shared by everyone on the project,
 and replacing it on a mistyped command would split one workspace into two.
 
-`validate` only reads. A command someone runs to find out what is wrong must not change the
-thing it is inspecting. With no config present it reports the defaults rather than failing,
-because not having one is a valid state.
+`validate` only reads. If that selected directory has no config, it reports
+`no acc.workspace.json in selected directory; ancestors not checked`.
+The JSON result returns default config metadata for that missing local file. Ordinary
+commands may still discover an ancestor config; this is not an effective-policy report.
+Run validation with `--cwd` set to that ancestor directory to check its file.
 
-## 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 +129,22 @@ 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.
+
+Codex LocalDaemon delivery separately requires macOS arm64, Codex 0.152.1 or newer, a
+current feature probe, and exact thread, canonical cwd, process, version and protocol
+checks. Its daemon must already be running; ACC never starts or stops it. Codex reads
+consent from the installation record, not a shell-shim variable. Unavailable or ineligible
+sessions retain durable inbox fallback. Use `acc install --adapter codex --delivery off`
+to stop new native offers; bypassing a shim does not disable that recorded opt-in.
+
+## 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
@@ -131,17 +152,17 @@ that resolves inside a workspace.
 
 | Variable | Purpose |
 |---|---|
-| `ACC_DATA_HOME` | Where session, claim, and message state is kept, instead of the platform default (`~/Library/Application Support/acc` on macOS; `~/.local/share/acc` on Linux, or wherever `XDG_DATA_HOME` points) |
-| `ACC_CONFIG_HOME` | The same override, for configuration state the platform would otherwise keep alongside `ACC_DATA_HOME` |
-| `ACC_CACHE_HOME` | The same override, for cache data the platform would otherwise keep under its own cache location |
+| `ACC_DATA_HOME` | Base directory under which ACC creates `acc/` for runtime and coordination state. Defaults: `~/Library/Application Support` on macOS; `~/.local/share` on Linux, or `XDG_DATA_HOME` |
+| `ACC_CONFIG_HOME` | Parsed and validated path override; no current configuration-storage consumer |
+| `ACC_CACHE_HOME` | Parsed and validated path override; no current cache-storage consumer |
 | `ACC_PARTICIPANT` | Which participant a session belongs to, when the client does not say |
 | `ACC_WORKSPACE_ROOT` | The project to work in, instead of discovering one from the working directory. Absolute, or it is refused |
-| `ACC_SESSION` · `ACC_GENERATION` | Which session a command acts as when it is not worked out automatically. A supplied generation proves the exact opening; with only a session id the CLI resolves the current generation and refuses ambiguity |
+| `ACC_SESSION` · `ACC_GENERATION` | Explicit CLI owner credentials, supplied together by the operator for this session. Hooks do not set them. A public session ID alone never resolves a generation; see [CLI ownership](CLI.md#coordinate-from-a-session) |
 | `ACC_MCP_PARTICIPANT` | Who `acc-mcp` takes part as. `mcp` by default |
 | `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_NO_UPDATE_CHECK=1` | Disables update networking and background scheduling; manual recovery of an already downloaded update remains available |
 | `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_NATIVE_DELIVERY_POLICY` | Owned shell-bootstrap consent, currently used by Claude Code. The shim sets `off`, `actionable`, or `all`; missing/invalid values mean off for that route. Codex instead reads recorded installation consent, even when this variable is absent |
+| `ACC_BYPASS=1` | Bypasses owned shell activation, currently Claude Code: no bootstrap check/native flags, and shim policy is unset. It does not disable Codex recorded opt-in; use `acc install --adapter codex --delivery off` for new Codex offers |
 | `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 |
 |---|---|
@@ -16,26 +18,31 @@ Why ACC is shaped the way it is, and what is deliberately still open.
 | Runtime state outside the repository | A checkout can be deleted, cloned, or synced; presence and locks must not travel with it. |
 | Project config optional and runtime-free | A committed file is editable by anyone with a PR, so it may carry policy — never sessions or tokens. |
 | Durable state is authoritative | Next-turn or live delivery may accelerate an interaction; neither becomes the source of truth. |
+| Bounded discovery, explicit history recovery | Automatic context stays small; peers select exact messages or historical records when they need full bodies. |
+| Immutable explicit decision links | Replacements and withdrawals preserve prior records and expose competing branches without choosing by timestamp. |
+| Fence managed runtime activation | Refresh all integrations before switching the active generation; partial refresh stays fenced until forward recovery completes. |
 | No heartbeat helper in v1 | An idle session is honestly reported `stale`. A sidecar process to fake liveness is worse than the truth. |
 | Presence reads the process, never writes the record | A pid answers "gone" at once; an age floor covers what a pid cannot, including its own reuse. Nothing is written back — no session has authority to edit another's record. This checks a process already there, not one beating on a session's behalf like the heartbeat helper above. |
-| No process launching | ACC attaches to sessions you already own. Owning them is a different product. |
+| No AI client or session launching | ACC attaches to sessions you already own; its separate update worker manages ACC packages, not those sessions. |
 | One publishable package | One version and one release rather than twelve coordinated ones. |
 | MIT | Widest reuse, least friction. |
-| Node 24 (current production LTS) | Uses `node:test`, modern `fs` promises, and no transpiler. |
+| Node 24 or newer required | 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 |
 |---|---|
 | A file in each repo that agents poll | No guard, no identity, no atomicity — and it ends up committed. |
 | A permanent global lead session | Turns peers into workers and makes one crash fatal. |
-| Treating MCP as a lifecycle guarantee | MCP is a tool surface. It cannot attach, guard, or wake anything. |
+| Treating MCP as an external-client lifecycle guarantee | Tool calls resolve MCP's own participant, but cannot infer the client's lifecycle, intercept writes, or wake its receiver. |
 | Requiring Git, tmux, PostgreSQL, or a service | Every requirement is a reason the tool is not installed. |
 | Collecting or sharing raw transcripts | Raw transcripts are never collected or shared. Explicit peer messages are bounded records the sender chose to address. |
 | 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
@@ -43,16 +50,18 @@ perturbed the record instead of removing it — a hook whose recorded hash no
 longer matched was still observed running, so absence was never actually
 tested.
 
-Absence is the whole mechanism. With no record, the client runs no hook at
-all, prints `hook: SessionStart Completed` while executing nothing, and ACC's
-write guard goes silently off — while `acc doctor` and `codex plugin list`
-both report it enabled. On a real machine, a shell write walked through a
+Absence was sufficient to disable the hooks in that historical capture. With no
+record, that client ran no hook, printed `hook: SessionStart Completed` while
+executing nothing, and ACC's write guard went silently off — while `acc doctor`
+and `codex plugin list` both reported it enabled. A shell write walked through a
 guarded claim; writing the exact same hashes back (captured before deletion,
 from an ACC three releases older) revived the guard immediately.
 
-That is why removal is never ACC's to do: the record is granted once by a
-person, survives ACC upgrades, and nothing ACC writes can restore it.
-Tidiness is not worth a permission only a human can re-grant.
+That is why removal is never ACC's to do: it preserves the client's trust decision.
+The historical observation above does not establish trust across arbitrary upgrades.
+Codex 0.153.4 compares each current definition's hash and reports changed definitions
+as modified; a trusted hook can also be disabled. ACC preserves the records but leaves
+current readiness unverified, directing the user to `/hooks` in Codex.
 
 **The generalisation, since this cost a release:** to learn whether state is
 load-bearing, take it away. Changing it tests something else.
@@ -72,12 +81,12 @@ 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.
 2. **Remote coordination.** v2, or a separate product.
-3. **Process launching.** Possibly never; possibly an external integration.
+3. **AI client/session launching.** Possibly never; possibly an external integration.
 4. **Multi-root discovery rules** beyond the current `roots` list.
 5. **Default claim lease length** for hook-only adapters. A hook-only session cannot sustain
    a short renewal cadence, so lease policy must not assume one.

package/docs/GETTING_STARTED.md

@@ -1,145 +1,151 @@
 # 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
-```
-
-## 1. Install once per machine
-
-Install the package, then let ACC wire only the clients it detects:
-
-<!-- test:command -->
-```bash
-acc install
-```
-
-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:
-
-```bash
-acc status
-```
-
-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:
-
-```bash
-acc work --summary "updating receipt rendering" --mode edit \
-  --hint 'file:packages/cli/src/main.mjs'
-```
-
-Reserve only what the session is about to change:
-
-```bash
-acc claim --resource 'file:packages/cli/src/main.mjs' \
-  --reason "updating receipt rendering"
-```
+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.
 
-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`.
-
-## 4. Send a real question
-
-From the first session, address a participant listed by `acc status`:
-
-```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
-```
+Active hooks supply each agent's own CLI arguments in coordination context; the installed
+skill tells the agent to use them. This path was observed in Claude Code 2.1.263 and
+Codex 0.153.4. Hooks must be enabled and trusted by the client. Without hook context, owner
+operations require an explicit pair or session-bound ACC MCP tools. See [CLI ownership](CLI.md#coordinate-from-a-session).
 
-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.
+## 1. Install once on this machine
 
-## 5. Read and reply from the second session
+ACC requires macOS or Linux and Node.js 24 or newer.
 
-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:
+Already using 0.3.1? Follow the [upgrade guide](UPGRADING.md) before mixing versions.
 
 ```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."
+npm install -g agents-can-communicate
 ```
 
-`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.
-
-Use `acc ack --message message_x` only when the message asks for acknowledgement and no
-written reply is needed.
-
-## 6. Hand off while context still exists
-
+<!-- test:command -->
 ```bash
-acc finish --goal "update receipt rendering" --status partial \
-  --completed "CLI wording changed" --remaining "MCP docs" \
-  --blocker "waiting for fixture"
+acc install
 ```
 
-`finish` records a structured handoff, releases that ACC session's claims, and ends its ACC
-presence. It does not close the external client.
-
-## Delivery expectations
-
-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.
-
-## Optional workspace configuration
-
-No file is required. Use one only for a stable shared workspace id, multiple roots, or
-project policy:
+Installation also enables automatic updates. ACC downloads releases in the background and
+refreshes its runtime and skills when active clients have left. Use `acc update` for an
+immediate update, or `acc update --auto off` to disable background updates. See
+[update controls](UPGRADING.md#automatic-updates-after-installation).
+
+The installer connects only the supported clients it finds. Open a new terminal and
+restart any running clients so they load their integrations. Follow the activation steps
+printed by the installer. In Codex, use `/plugins` to check ACC is enabled, then `/hooks`
+to review each ACC hook and enable/trust its current definition if needed. Restart the
+session after that review; changed hook definitions may require trust again.
+
+If the installer preserved your existing Codex sandbox settings, verify the named ACC
+state directory is in `sandbox_workspace_write.writable_roots` in the config it identifies.
+ACC keeps those user settings unchanged. Installed files alone do not establish that hooks
+are active; `acc doctor` leaves current readiness unverified and directs you to Codex.
+
+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.
+
+## 2. Open two sessions and give them ordinary tasks
+
+Start each client normally in the same project. ACC does not launch, supervise, or assign
+work to either session. For example:
+
+| Session | Your prompt |
+|---|---|
+| Codex | Add an account-registration endpoint. |
+| Claude Code | Build the account-registration screen. |
+
+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.
+
+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.
+
+A second repeatable pattern is review and handoff. Ask the implementing agent to request
+review of an identified revision (a commit when Git is available, or named files and
+version otherwise) and wait for the verdict. Ask the reviewer to return blocking defects
+or approval. If either session must stop, it can leave a durable handoff naming completed
+work, remaining work, and blockers. A later session can recover it from history. The
+underlying commands are [`acc request`](CLI.md#messages-and-requests), exact
+[`acc inbox --message`](CLI.md#inbox-reply-and-acknowledgement),
+[`acc reply`](CLI.md#inbox-reply-and-acknowledgement), and
+[`acc finish`](CLI.md#handoff).
+
+## 3. Watch for useful coordination
+
+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.
+
+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.
+
+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).
+
+## 4. Know when messages arrive
+
+Every message is recorded before ACC attempts faster delivery. Every participant has a
+durable inbox, which is the universal recovery path.
+
+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.
+
+Codex LocalDaemon and Claude Code Channel offer optional native delivery on
+Apple Silicon macOS. They are experimental, can spend tokens, and queue messages
+until a running turn finishes. Codex requires 0.152.1 or newer, an already-running
+LocalDaemon, recorded opt-in and a verified session; start it with your normal
+command. A loaded daemon thread can receive messages after its terminal exits.
+[Capabilities](CAPABILITIES.md) explains policy, versions and fallback.
+
+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.
+
+## 5. Keep the workspace boundary clear
+
+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.
+
+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).
+
+## Diagnose or remove it
+
+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,13 +1,13 @@
 # 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.
 - **Claim** — a leased reservation for a canonical resource such as `file:src/**`.
-- **Advisory / guarded** — a claim peers must respect versus one ACC can stop on measured client write paths; neither stops unrelated local processes.
+- **Advisory / guarded** — CLI claims default to advisory. Explicit guarded enforcement also requires certified guards from every live participant; neither mode stops unrelated local processes.
 - **Message** — an attributed untrusted `note`, `question`, `request`, `answer`, `decision`, or `handoff`.
 - **Thread** — a root message plus linked answers sharing one immutable `threadId`.
 - **Obligation** — `none`, `reply`, or `acknowledge`; what communication the recipient owes.
@@ -16,11 +16,17 @@
 - **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 through Claude Code Channel or Codex LocalDaemon to an already-running session, behind recipient opt-in. Both wait for an active turn to finish; [Capabilities](CAPABILITIES.md) gives the measured eligibility and limits.
 - **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.
 - **Managed / manual lifecycle** — whether hooks report ACC presence automatically; never ownership of the external client process.
-- **MCP participation** — polling access to durable communication without native lifecycle, context, guards, or push.
+- **MCP participation** — manual incoming polling without native lifecycle, context, guards, or receive wake; outgoing messages can use an eligible recipient's opted-in native route.
+- **Bounded discovery** — inbox/history summary pages with limits and cursors; bodies require selection.
+- **Exact recovery** — read one addressed inbox body, or one history record; history reads do not advance receipts.
+- **Decision change** — an immutable decision explicitly supersedes or withdraws prior decisions; old records remain.
+- **Current decision** — a terminal recorded position or withdrawal, not proven truth; competing branches stay visible.
+- **Managed runtime** — ACC's staged installation generations and automatic-update controls, distinct from managed/manual session presence.
+- **Activation hold** — an ACC process lease or native binding that postpones runtime refresh; observed lifecycle cleanup can release a native hold without stopping a vendor daemon.
 
 See [Concepts](CONCEPTS.md) for relationships and [Protocol](PROTOCOL.md) for exact rules.