agents-can-communicate 0.1.18 → 0.2.0

package/docs/PROTOCOL.md

@@ -0,0 +1,200 @@
+# Protocol
+
+The protocol is the vendor-neutral contract shared by core, CLI, MCP, storage, and every
+adapter. Version 0.2 uses store schema version `3` and deliberately rejects v0.1 state.
+There is no compatibility reader, conversion, archive path, or automatic deletion.
+
+## Durable records
+
+The store accepts only these durable kinds:
+
+```text
+workspace · participant · session · intent · claim · message · receipt · event
+```
+
+`deliveryBinding` is validated but ephemeral. It is tied to one open session generation
+and never written inside a repository.
+
+## Identity
+
+```text
+Workspace
+└── Participant
+    └── Session generation
+```
+
+- A workspace is one local coordination room.
+- A participant is the stable recipient of a message.
+- A session is one client conversation. Its unguessable generation token proves that a
+  later mutation still belongs to the current opening.
+
+Sessions carry harness, checkout, branch, optional pid, enforcement, and lifecycle facts.
+The `managed` lifecycle value means ACC hooks can report presence changes; it does not mean
+ACC owns or controls the external client.
+
+## Intent and claims
+
+Intent contains `summary`, `mode`, `resourceHints`, `state`, and `updatedAt`. It is
+awareness only.
+
+Claims contain the owner session and generation, canonical resource URI, shared or
+exclusive mode, advisory or guarded enforcement, reason, and lease timestamps. Claim
+acquisition and conflict detection are atomic. Presence becoming stale never releases a
+claim; expiry or an explicit release does.
+
+## Message envelope
+
+Every message contains:
+
+```text
+messageId
+threadId
+clientMessageId
+workspaceId
+fromParticipantId
+fromSessionId
+toParticipantIds
+kind
+obligation
+subject
+body
+inReplyTo
+artifacts
+handoff
+sentAt
+```
+
+`clientMessageId` is an idempotency key scoped to workspace plus sender participant. A
+retry with the same logical content returns the original message. Reusing the key with
+different content is a data error. CLI and MCP generate a key when omitted and return it
+inside the message so an uncertain caller can retry explicitly.
+
+An empty `toParticipantIds` creates a room record. At commit time, core resolves every
+known peer participant with an open session and creates a receipt for each. Participants
+that arrive later can inspect room history through a full sync but do not receive
+retroactive receipts. Those already-present recipients get the normal inbox and certified
+next-turn path; a successful next-turn write advances their room receipt to `offered`.
+Room records are never eligible for native live push.
+
+## Kinds and obligations
+
+| Kind | Valid obligation | Addressing |
+|---|---|---|
+| `note` | `none` | addressed or room |
+| `question` | `reply` | addressed only |
+| `request` | `reply` | addressed only |
+| `answer` | `none` | addressed reply only |
+| `decision` | `none`, or `acknowledge` | addressed or room; room must use `none` |
+| `handoff` | `acknowledge`, or `none` | addressed must acknowledge; room must use `none` |
+
+The generic `message` boundary accepts only `note`, `question`, `request`, and `decision`.
+An `answer` must be made through `reply`, which supplies the thread link. A `handoff` must
+be made through `finish`, which supplies the structured payload.
+
+A request has no accepted, running, or done state. The reply resolves its communication
+obligation; execution evidence belongs in the answer or handoff.
+
+## Threads
+
+The root message uses its own id as the thread id:
+
+```text
+threadId = messageId
+inReplyTo = null
+```
+
+An answer carries the same `threadId` and the original message id in `inReplyTo`. There is
+no mutable thread record or hidden thread status.
+
+## Receipt lifecycle
+
+Every resolved recipient gets an independent receipt:
+
+```text
+queued -> offered -> retrieved -> acknowledged
+```
+
+`recorded` is the send boundary's success result: the message is durable. It is not a
+receipt state. `queued` is the distinct per-recipient fact created in the same transaction,
+so one recorded room or multi-recipient message can have zero or several queued receipts.
+
+- `queued` proves the durable message and receipt committed.
+- `offered` proves bytes crossed ACC's transport boundary or the target client accepted a
+  certified native call.
+- `retrieved` proves the participant explicitly received the body through inbox or an
+  equally strong certified adapter signal.
+- `acknowledged` proves that participant acknowledged or replied.
+
+Offered is not read. Retrieved is not model attention. Reply is not task completion.
+
+Forward skips are allowed when the stronger observation implies the weaker ones. Repeating
+a state is idempotent; moving backward is rejected. There is no `seen` state because ACC
+cannot inspect model attention, and no terminal delivery `failed` state because the
+durable path remains available.
+
+## Offer attempts
+
+Delivery attempts are immutable events, not receipt states:
+
+```text
+message.offer_succeeded
+message.offer_failed
+```
+
+Every attempt identifies `messageId`, `recipientParticipantId`, `targetSessionId`, and
+`targetGeneration`, followed by the transport name, adapter, client version, and timestamp.
+A failed attempt additionally carries a safe closed error code. Core validates the target
+as that recipient's recorded session generation and derives event attribution from it; the
+router cannot substitute the sender or omit the selected binding. Attempts never copy the
+peer body into diagnostics.
+Receipt `offered` is committed only after the transport accepts bytes. A failed attempt
+leaves the receipt queued.
+
+## Inbox, reply, and acknowledgement
+
+`inbox` returns unresolved messages owned by the calling participant and advances only
+that participant's receipt to `retrieved`. An exact message id is the recovery path after
+compaction or an over-budget projection.
+
+`reply` verifies that ownership, records an `answer` in the original thread, and advances
+the original receipt to `acknowledged` in one transaction. Only after that durable commit
+may the answer be offered to the original author. A transport error cannot roll back it.
+
+`ack` advances the caller's receipt without creating a reply. It exposes no state override;
+callers cannot claim that a transport offered or a participant retrieved a message.
+
+## Handoff
+
+`finish` creates a `handoff` with structured `status`, `completed`, `remaining`,
+`blockers`, and `verification`, releases the sender session's claims, and ends its ACC
+presence. An addressed handoff requires acknowledgement. A room handoff does not. Neither
+form closes or otherwise controls the external AI client.
+
+## Delivery binding and recipient policy
+
+A live-capable adapter may publish one ephemeral binding for its exact session generation:
+
+```text
+sessionId · generation · adapterId · clientVersion · availableModes
+livePolicy · opaqueEndpointRef · leaseUntil
+```
+
+The recipient owns `livePolicy` because native push may start a model turn:
+
+- `off`: inbox and normal next-turn paths only;
+- `actionable`: questions, requests, and addressed handoffs may use live push;
+- `all`: every addressed kind may use live push.
+
+Default is `off`. Policy never creates a capability. The router still requires a current
+reachable binding, one unambiguous recipient generation, a passing exact-version
+certification, and adapter acceptance. The current Codex and Claude captures do not meet
+those requirements; all shipped native live routes therefore fall back durably.
+
+## Attention and sync
+
+Bounded sync returns events after a cursor plus explicit attention. Full sync is a
+forensic workspace snapshot, not the normal way to recover one message. Attention is
+limited to six explicit rules: `reply_required`, `acknowledgement_required`,
+`recipient_unavailable`, `claim_conflict`, `claim_contended`, and `claim_expired`.
+
+Next: [CLI](CLI.md) · [MCP](MCP.md) · [Architecture](ARCHITECTURE.md)

package/docs/RELEASING.md

@@ -0,0 +1,109 @@
+# Releasing
+
+```mermaid
+graph LR
+  A[npm ci] --> B[npm run check] --> C[npm test] --> D[clean candidate commit] --> E[npm pack] --> F[verify-package] --> G{approved?}
+  G -->|yes| H[tag · publish · release]
+  G -->|no| I[stop]
+```
+
+## Build the candidate
+
+```bash
+npm ci
+npm run check
+env npm_config_cache=/private/tmp/acc-npm-cache-v02 npm test
+git status --short
+git commit -m "release: prepare ACC v0.2.0"
+candidate_dir="$(mktemp -d /private/tmp/acc-v0.2.XXXXXX)"
+env npm_config_cache=/private/tmp/acc-npm-cache-v02 npm pack --pack-destination "$candidate_dir"
+env npm_config_cache=/private/tmp/acc-npm-cache-v02 node scripts/verify-package.mjs \
+  "$candidate_dir/agents-can-communicate-0.2.0.tgz"
+git diff --check
+```
+
+`verify-package.mjs` is the gate that matters. It installs the tarball into a
+clean directory with **no workspace anywhere** and then drives the product. The
+acceptance suite additionally opens independent Claude/Codex hook sessions from
+the installed artifact, completes both message directions, proves downgrade and
+restart behavior, exercises the installed MCP binary, and removes client wiring twice.
+
+Development cannot catch what this catches. Workspace symlinks are always
+present there, so an unbundled package imports fine right up until somebody
+else installs it.
+
+## What it refuses
+
+| Refused | Why |
+|---|---|
+| `tests/`, `test/` | test suite |
+| unreferenced `fixtures/` | material that is not exact redacted certification evidence |
+| `scripts/spikes/`, `*.sock` | development probes and local endpoints |
+| runtime, transcript, or secret directories | machine state and private material |
+| `.github/`, `.githooks/`, `.agents/` | local configuration |
+| `*.jsonl` | looks like a transcript |
+| Workspaces missing from `node_modules/` | every internal import would fail |
+
+## Record the evidence
+
+Put the tarball name, sha256, **the commit it was built from**, exact platform/client
+facts, fallback result, and known limitations in `docs/release-evidence/v0.2.0.md` and
+the current `CHANGELOG.md` release table. A release without them is a release nobody can
+audit later. Test count is deliberately left out: nothing verifies it, so it only
+decorates or, when it drifts, misleads.
+
+The commit matters because every workspace travels inside the tarball, so any
+change to shipped code changes the digest. A digest recorded alone goes stale
+on the next merge and then reads as a false claim about the current tree
+rather than a true one about an older commit. `verify-package.mjs` prints
+both on one line for exactly this reason, and refuses to imply
+reproducibility when the working tree is dirty:
+
+```text
+PASS  agents-can-communicate-0.0.0.tgz  sha256 a5c8bb1d…  built from 39d0dcf
+```
+
+It went stale four times in a row anyway, each caught by hand and only
+because someone happened to run the script. So `npm test` now checks it:
+`tests/acceptance/recorded-candidate.test.mjs` fails when shipped code has
+changed since the recorded commit, and names the files. A shallow clone that
+does not have the commit reports that instead of failing — the check is of
+the record, not of the checkout depth.
+
+The candidate therefore uses two commits. Commit A contains every packed file and every
+release gate. Pack and verify clean commit A, then commit B records its digest and evidence
+only in files that are not packed. Never record a dirty-tree digest: changing a packed file
+after commit A means making a new candidate commit and packing again.
+
+Native real-client tests run only where the retained capture proved that native boundary.
+For v0.2.0 neither Codex 0.152.0 nor Claude Code 2.1.252 did: the Codex control socket was
+absent and Claude stopped at the development-channel warning. Record those exact failed
+captures and run the packed inbox/next-turn fallback instead of promoting an unobserved
+native path. Windows is an explicit unsupported-platform skip, not a passing capture.
+
+A published version's record is history and is not rewritten; later changes
+get a new `## Unreleased` entry at the top, checked the same way against the
+current tree.
+
+## Then stop
+
+Publishing, tagging, and cutting a GitHub release are **external mutations**.
+They need explicit approval from the maintainer, every time.
+
+With two-factor authentication set to `auth-and-writes` — which is what `npm
+profile get` reports for this account — every publish needs a code, and npm
+does not prompt for one:
+
+```bash
+npm publish --otp=123456
+```
+
+An npm *Automation* token, or a granular token with write access, publishes
+without a code. A granular token scoped to selected packages cannot create a
+package that does not exist yet, which is the case exactly once per package.
+The `Release` workflow builds and verifies a candidate and uploads it as an
+artifact; it does not publish.
+
+---
+
+See also: [README](index.md) for navigation and [Glossary](GLOSSARY.md) for terms.

package/docs/SECURITY_MODEL.md

@@ -0,0 +1,131 @@
+# Security model
+
+ACC connects independently controlled sessions without merging their authority. A peer can
+send useful context, a question, or a request; its text never becomes system policy or a
+human instruction merely because ACC transported it.
+
+The first release coordinates processes under one local OS user. Same-user access protects
+local transport from the network; it does not make model output trustworthy.
+
+## Trust boundaries
+
+1. Human instructions and approved local policy.
+2. ACC protocol and core invariants.
+3. Adapter facts backed by exact real-client evidence.
+4. Peer messages and artifact references, always untrusted input.
+
+```mermaid
+graph LR
+  P["peer session — untrusted text"] --> ACC["ACC runtime"]
+  ACC --> S[("state outside repositories")]
+  ACC --> C["recipient client — own permissions"]
+  H["human authority"] --> C
+```
+
+ACC does not read raw transcripts, relay permission approvals, or start target clients. A
+native delivery path may only offer an attributed peer envelope to an already-running,
+user-owned session.
+
+## Peer-content boundary
+
+Inbound messages are rendered as structured, attributed peer data. The frame includes the
+sender, message id, kind, obligation, and an explicit untrusted marker. The renderer
+escapes fences, nested strings, terminal control sequences, and human output. If a body
+cannot fit the context budget, the projection keeps the id and directs the participant to
+`acc inbox --message <id>` instead of cutting the frame in half.
+
+A model may still choose to follow persuasive peer text. Attribution and the recipient's
+own instruction hierarchy are the mitigation; ACC is not a model sandbox.
+
+## Identity and ownership
+
+- Participant identity is the address; session identity is one current client opening.
+- Mutating calls prove their owner with the session generation.
+- A stale process cannot renew or release records owned by a newer generation.
+- Inbox, reply, and acknowledgement validate the recipient's participant id.
+- One participant cannot advance another participant's receipt.
+- MCP identity derives from user-owned server launch configuration, never from untrusted
+  `initialize` or `clientInfo` fields.
+
+The `managed` lifecycle label means hooks can report ACC presence transitions. It never
+grants ACC process-control authority.
+
+## Durable and delivery integrity
+
+Messages and queued receipts commit before delivery is attempted. Receipt words correspond
+to observations:
+
+- `offered` only after bytes cross ACC's boundary or a certified client accepts the call;
+- `retrieved` only after the participant receives the body through inbox or equally strong
+  evidence;
+- `acknowledged` only after that participant acknowledges or replies.
+
+There is no model-attention claim and no public state override. Failed acceleration leaves
+the message queued and records only a closed safe error code. Diagnostics and offer events
+never copy the peer body.
+
+A future live adapter must match exact passing evidence, one unexpired generation-bound
+binding, and the recipient's opt-in policy. Opaque endpoint references remain inside the
+adapter and outside repositories. Current Codex and Claude native captures failed, so no
+live transport is enabled.
+
+## Claims
+
+Claims are advisory unless every live participant exposes a certified guard for the
+relevant mutation path. Even guarded claims do not stop unrelated processes, runtime-built
+paths, or tool calls the client never presents to the hook. Force release requires explicit
+authority and records actor and reason.
+
+File resources are canonicalized and kept inside workspace roots. Misleading glob forms
+are refused. Hooks fail open on timeout or coordination failure so ACC cannot stop a client
+from operating merely because its own state is unavailable.
+
+## Filesystem and installation
+
+- Runtime state, bindings, sockets, and install ownership records stay outside repositories.
+- Managed paths are checked for containment and symlink escape.
+- Store publication uses atomic no-replace behavior, journaling, and writer locks.
+- Corrupt or incompatible store versions fail closed before mutation.
+- Client installers preserve unrelated settings and record content hashes.
+- Uninstall removes only bytes still matching what ACC wrote.
+- Tokens, credentials, and environment contents are never copied into ACC or project config.
+
+## Data collected
+
+ACC stores participant/session identity, presence, one-line intent, explicit claims,
+explicit messages and structured handoffs, per-recipient receipts, artifact references,
+and coordination events. It excludes complete prompts, assistant responses, raw
+transcripts, secrets, environment variables, and unrelated files.
+
+## Threat scenarios
+
+| Threat | Prevention and detection | Residual |
+|---|---|---|
+| Peer message impersonates system authority | Attributed untrusted frame; fence and terminal escaping; injection tests | A model can still make a poor judgment about untrusted data |
+| Large body buries a claim conflict | Fixed attention priority and bounded whole-frame projection | Very small budgets omit lower-priority roster detail |
+| Stale session mutates new ownership | Exact generation on mutations; conflict error on mismatch | A same-user attacker with runtime access is out of scope |
+| Symlink or traversal escapes a managed root | Per-segment containment, no-follow reads, closed config schema | Host filesystem compromise is out of scope |
+| Claim denial of service | Leases, visible owner, explicit authority release | Deliberate abuse by a trusted local peer is social |
+| Installer removes user configuration | Content-hashed ownership and byte comparison | User must remove modified leftovers manually |
+| False delivery claim | Record-first order, transport-owned `offered`, recipient-owned retrieval/ack, mutation tests | Crash after offer before commit can cause duplicate display |
+| Native endpoint leaks | Ephemeral opaque reference, user-only local endpoint, status redaction | Same-user local processes are outside the trust boundary |
+| MCP client impersonates another session | Identity fixed by launch env, closed tool schemas | A compromised launch config already controls that client |
+| Corrupt or v0.1 store is reinterpreted | Schema version rejection and doctor diagnostics | The maintainer must reset incompatible local state deliberately |
+
+## Verification
+
+The release gate executes attacks rather than trusting this page:
+
+| Boundary | Covering tests |
+|---|---|
+| peer text and budget framing | `tests/security/peer-injection.test.mjs`, `packages/adapter-sdk/test/context-projector.test.mjs` |
+| receipt ownership and truthful transitions | `packages/core/test/inbox-and-reply.test.mjs`, `receipt-offer-idempotency.test.mjs` |
+| path, symlink, and config containment | `tests/security/storage-boundary.test.mjs`, `symlinked-workspace.test.mjs`, `claim-spelling.test.mjs` |
+| installer ownership and restoration | `tests/security/installer.test.mjs`, `restore-every-client.test.mjs` |
+| no hook-path network access | `tests/security/no-network-on-the-hook-path.test.mjs` |
+| capability evidence and version downgrade | `packages/adapter-sdk/test/certification.test.mjs` |
+
+An attacker who can rewrite the user's ACC data home or client configuration already has
+the local rights ACC relies on. Report vulnerabilities through [SECURITY.md](../SECURITY.md).
+
+Next: [Architecture](ARCHITECTURE.md) · [Capabilities](CAPABILITIES.md)

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,102 @@
+# Troubleshooting
+
+Start with:
+
+```bash
+acc doctor
+```
+
+It reports detected clients, exact versions, installation ownership, capability downgrade,
+and the next action. Restart a client after installation because hooks load at startup.
+
+## The second session does not appear
+
+Run `acc status --json` in both windows and compare `workspaceId`. Common causes are an
+already-running client that never loaded the hook, a generic MCP server launched without
+`ACC_MCP_WORKSPACE`, or two plain directories that are not the same workspace. Codex also
+requires plugin trust.
+
+ACC does not launch a missing session. Open it normally after fixing the installation or
+workspace path.
+
+## A message stays queued
+
+Queued means the durable message is safe; it does not mean the recipient model saw it.
+Have the recipient run:
+
+```bash
+acc inbox
+acc inbox --message message_x
+```
+
+Certified next-turn delivery waits for that client's next normal prompt. Grok, generic MCP,
+unknown client versions, and other platforms poll inbox. A reply acknowledges the original
+automatically; `acc ack` is for acknowledgement-only messages.
+
+## I enabled live delivery but got fallback
+
+`--delivery actionable|all` is recipient policy, not a capability switch. No current
+adapter has passing native live-push certification:
+
+- Codex 0.152.0: the existing app-server control socket was absent; ACC did not start one.
+- Claude Code 2.1.252: the capture stopped at the development-channel warning before the
+  ACC child process started.
+
+The installer therefore keeps effective policy off and reports exact-certified next-turn
+or inbox fallback. This is expected, not a partially working live route.
+
+## Codex plugin is listed but inactive
+
+Trust the plugin in Codex, then restart it. Until the client accepts that trust step, hooks
+do not run. `acc doctor` reports the installed cache copy and missing activation separately.
+
+## Gemini does not guard a write
+
+Default and `plan` modes expose no write tool to the model. `auto_edit` exposes edit tools;
+shell availability depends on approval mode. Only Gemini CLI 0.37.0 on `darwin-arm64` has
+package-shipped delivery certification; other versions still use inbox.
+
+## Grok shows no injected message
+
+Grok 1.0.13 discarded UserPromptSubmit context in the real capture. Its next-turn and guard
+capabilities remain false. Use `acc status` and `acc inbox`; do not wait for a banner.
+
+## Kimi sessions remain in history
+
+Kimi 0.36.1 emits a heartbeat but prompt-mode `SessionEnd` was not observed. An exited
+session becomes offline by presence rules rather than a clean end signal. The default
+status hides offline sessions; `acc status --all` intentionally retains attribution and
+checkout history.
+
+## A write was blocked
+
+Exit code `5` names the overlapping claim and owner. Ask the owner or wait for release. If
+an explicit authority has decided to replace it:
+
+```bash
+acc release --claim claim_x --authority "agreed with models" \
+  --reason "handing over the file"
+```
+
+## Protection says advisory
+
+At least one live participant cannot be stopped through a certified hook, or at least one
+claim asked only for advisory enforcement. This includes generic MCP and Grok. Respect the
+claim manually; `guarded` would be a false room-wide promise.
+
+## Store version is incompatible
+
+v0.2 rejects v0.1 state and provides no migration or automatic deletion. `acc doctor`
+identifies the incompatible data path. Back it up or remove it deliberately only after
+confirming no needed coordination state remains.
+
+## Uninstall left files
+
+ACC removes only bytes that still match its install record. Anything edited by the user is
+reported and retained. Remove those leftovers manually if desired.
+
+Runtime state is outside the repository by design. `ACC_DATA_HOME` can relocate it, but ACC
+refuses a path inside any workspace root.
+
+Next: [Getting started](GETTING_STARTED.md) · [Capabilities](CAPABILITIES.md) ·
+[Configuration](CONFIGURATION.md)

package/docs/WHY_ACC.md

@@ -0,0 +1,61 @@
+# Why ACC
+
+ACC exists for a narrow situation: you already have several AI sessions open, each with
+its own client, context, permissions, checkout, and human direction, and they need to
+communicate without becoming workers owned by one controller.
+
+That boundary matters. Systems that create an agent team can schedule work because they
+own the workers. ACC deliberately does not. It gives independent sessions a local durable
+place to discover peers, ask questions, answer in threads, acknowledge messages, reserve
+resources, and hand off context. If every session closes, the durable records still tell
+the truth.
+
+## Does it fit?
+
+```mermaid
+flowchart TD
+  A["Do you independently open several sessions?"] -->|no| N["ACC adds little and stays quiet"]
+  A -->|yes| B["Must they keep separate ownership and permissions?"]
+  B -->|no| M["A managed agent runtime may fit better"]
+  B -->|yes| C["Do they need direct questions, durable replies, or claim awareness?"]
+  C -->|yes| Y["ACC fits this workflow"]
+  C -->|no| N
+```
+
+The strongest adoption signal is not installation or a large roster. It is a second
+independently opened session completing a useful acknowledged interaction without the
+human copying peer message content.
+
+## What is different
+
+| Need | ACC's boundary |
+|---|---|
+| Keep sessions you already opened | Hooks or MCP add participation; ACC never starts replacement workers. |
+| Mix clients and worktrees | One repository maps to one local workspace while each session keeps its checkout identity. Git is optional. |
+| Ask without granting authority | Messages are attributed untrusted data. A request expects a reply but is not an order. |
+| Recover after compaction or restart | Messages and receipts commit before delivery; participant addressing survives when the participant id is stable. |
+| Avoid overlapping edits | Intent warns; narrow claims may advise or guard, depending on every live client's measured capability. |
+| Trust delivery language | Recorded, queued, offered, retrieved, and acknowledged are separate observable facts. |
+| Keep it private and removable | State is local and outside repositories; transcripts are excluded; uninstall preserves user edits. |
+
+Claims support communication; they are not the product's center. The useful loop is ask,
+retrieve, reply, acknowledge, and hand off. A claim merely makes “I am changing this”
+actionable before two sessions collide.
+
+## Choose another layer when
+
+Choose a managed runtime if you want the system to create agents, assign execution state,
+select models, spend token budgets, or control process lifecycle. Choose a tracker when
+you need organizational planning. Choose a hosted service when participants must
+coordinate across machines.
+
+ACC also does not merge model memory, read raw conversations, approve tools, operate CI,
+or make guarded claims immune to unrelated local processes. Current native live push is
+uncertified, so workflows that require immediate interruption of an already-running model
+should not depend on ACC today.
+
+If the sessions should remain yours and simply stop working in isolation, that is the
+product ACC is designed to be.
+
+Next: [Getting started](GETTING_STARTED.md) · [Concepts](CONCEPTS.md) ·
+[Capabilities](CAPABILITIES.md)

package/docs/index.md

@@ -0,0 +1,42 @@
+# ACC documentation
+
+ACC connects independently opened AI sessions so they can discover peers and communicate
+without becoming one managed agent team. This map starts with the useful interaction, then
+separates protocol truth from adapter reach.
+
+## Evaluate
+
+1. [Why ACC](WHY_ACC.md) — the product boundary and when a managed runtime fits better.
+2. [Concepts](CONCEPTS.md) — peers, durable threads, receipts, intent, and claims.
+3. [Capabilities](CAPABILITIES.md) — certified support, current reachability, recipient
+   policy, fallback, and limitations beside each adapter.
+
+## Use it
+
+1. [Getting started](GETTING_STARTED.md) — two user-opened sessions complete one useful
+   acknowledged question-and-answer interaction.
+2. [CLI](CLI.md) — exact commands, flags, result shapes, and exit codes.
+3. [MCP](MCP.md) — durable polling for clients without a native adapter.
+4. [Configuration](CONFIGURATION.md) — optional workspace identity and policy.
+5. [Troubleshooting](TROUBLESHOOTING.md) — symptoms, exact downgrades, and fixes.
+
+## Understand and extend it
+
+- [Protocol](PROTOCOL.md) — message envelope, thread rules, receipt lifecycle, handoffs,
+  bindings, and the clean v0.2 store break.
+- [Architecture](ARCHITECTURE.md) — record-first flow, package boundaries, router, storage,
+  and hooks.
+- [Security model](SECURITY_MODEL.md) — untrusted peer content, delivery integrity,
+  filesystem boundaries, and executable attack tests.
+- [Adapter authoring](ADAPTER_AUTHORING.md) — capability evidence, hook contracts, and
+  installation ownership.
+- [Glossary](GLOSSARY.md) — each public term in one line.
+
+## Project work
+
+- [Contributing](https://github.com/automatis-tools/agents-can-communicate/blob/main/AGENTS.md) — invariants and the mutation-proof gate.
+- [Design decisions](DESIGN_DECISIONS.md) — architectural decisions and reversals.
+- [Releasing](RELEASING.md) — packed-artifact verification.
+
+Runtime state and raw transcripts are not documentation artifacts and never belong in the
+repository.