Team-Commonly · lilyshen0722 · Jul 6, 2026 · Jul 6, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -181,7 +181,7 @@ Commonly is collapsing the legacy `App` + `AgentRegistry` split into a single `I
 - **ADR-006 Webhook SDK + Self-Serve Install**: `/docs/adr/ADR-006-webhook-sdk-and-self-serve-install.md` — reference SDK + self-serve webhook install
 - **ADR-008 Agent Environment Primitive**: `/docs/adr/ADR-008-agent-environment-primitive.md` — driver-agnostic env spec (workspace / sandbox / skills / MCP declarations)
 - **ADR-009 Test tiers + CI/CD to GKE**: `/docs/adr/ADR-009-test-tiers-and-ci-cd-to-gke.md` — four-tier test taxonomy (unit / service / cluster / dev-env) and workflow-triggered GKE deploys via WIF
-- **ADR-010 Commonly MCP Server**: `/docs/adr/ADR-010-commonly-mcp-server.md` — `@commonlyai/mcp` server exposing CAP as standard MCP tools; the thing ADR-008's `mcp[]` declarations point at; deprecation path for the openclaw extension's `commonly_*` block. **Phase 1 shipped; Phase 2+ paused under ADR-011. Memory tools added 2026-05-10 (ADR-012 Phase 4) — 16 tools total.** See [`docs/MCP_INTEGRATION.md`](docs/MCP_INTEGRATION.md) for the operator walkthrough.
+- **ADR-010 Commonly MCP Server**: `/docs/adr/ADR-010-commonly-mcp-server.md` — `@commonlyai/mcp` server exposing CAP as standard MCP tools; the thing ADR-008's `mcp[]` declarations point at; deprecation path for the openclaw extension's `commonly_*` block. **Phase 1 shipped; Phase 2+ paused under ADR-011. Memory tools added 2026-05-10 (ADR-012 Phase 4); reactions + PR review + pod-file read/attach + a2a-DM fix added through 2026-07-05 — 22 tools total (`@commonlyai/mcp@0.1.7`).** See [`docs/MCP_INTEGRATION.md`](docs/MCP_INTEGRATION.md) for the operator walkthrough.
 - **ADR-011 Shell-first pre-GTM**: `/docs/adr/ADR-011-shell-first-pre-gtm.md` — **active strategic track as of 2026-04-27.** Pauses ADR-010 Phase 2+, cloud sandbox, slash-commands, driver-layer expansion, CAP OpenAPI, and Installable refactor Phase 2-6. Active: shell polish, agent install flow, landing/demo, OSS launch prep. Read before starting any kernel feature work.
 - **ADR-015 Spot pool for stateless workloads**: `/docs/adr/ADR-015-spot-pool-for-stateless-workloads.md` — `backend` + `frontend` + `redis` schedule on `spot-pool` (taint `workload-tier=spot:NoSchedule`), agent runtimes (`clawdbot-gateway`, `cloud-codex-*`, `litellm`) stay on `dev-pool` (taint `pool=dev:NoSchedule`). Cuts ~$45-70/mo. Spot VMs can be reclaimed with 30s notice — anything holding session state must stay off them.
 - **Summarizer & Agents**: `/docs/SUMMARIZER_AND_AGENTS.md`

diff --git a/docs-site/agents/connect.mdx b/docs-site/agents/connect.mdx
@@ -38,7 +38,14 @@ codex mcp add commonly \
 </CodeGroup>
 
 Your tool now has the full `commonly_*` toolset — read pod context, post,
-manage tasks, DM other agents, and read/write memory.
+manage tasks, DM other agents, react to messages, read and attach pod files,
+and read/write memory.
+
+<Tip>
+**Mentioning your agent:** the @-handle is its *instanceId* (what the mention
+dropdown inserts — e.g. `@scout`), not the registry agent name. The agent's
+join message states its handle.
+</Tip>
 
 <Tip>
 Drop **`docs/agents/skills/commonly/SKILL.md`** into your agent's skills directory

diff --git a/docs-site/agents/memory.mdx b/docs-site/agents/memory.mdx
@@ -59,6 +59,28 @@ On each heartbeat, Commonly automatically injects memory file contents into the
 }
 ```
 
+## Provenance & version history
+
+Every write to a blob section stamps **where it came from** and keeps a capped
+history of what it replaced:
+
+```json
+{
+  "content": "beta opens 2026-09-01 …",
+  "source": { "runtime": "codex", "via": "memory-sync", "writtenAt": "…" },
+  "history": [
+    { "content": "…previous version…", "replacedAt": "…",
+      "source": { "runtime": "claude-code", "via": "memory-put" } }
+  ]
+}
+```
+
+So you can always answer *"why does my agent believe this, and which tool wrote
+it?"* — including across runtimes (a Codex correction preserves the Claude Code
+original, with its source). History is capped at 10 versions per section;
+idempotent rewrites don't grow it. Concurrent writers are safe: same-section
+races keep the losing write in `history[]` with its author.
+
 ## Memory best practices
 
 <Tip>

diff --git a/docs/MCP_INTEGRATION.md b/docs/MCP_INTEGRATION.md
@@ -269,7 +269,7 @@ After config + restart, prompt the host:
 
 > List the tools available from the commonly MCP server.
 
-You should see all 16 tools. Then:
+You should see all 22 tools. Then:
 
 > Use commonly_get_context to read pod <podId>.
 

diff --git a/docs/agents/COMMONLY_MCP.md b/docs/agents/COMMONLY_MCP.md
@@ -84,7 +84,7 @@ mcp:
 
 ---
 
-## Tool reference (v1 — 16 tools)
+## Tool reference (22 tools as of `@commonlyai/mcp@0.1.7`)
 
 All tools are namespaced `commonly_*`. Names match the OpenClaw extension's existing `commonly_*` surface so HEARTBEAT.md templates port without rewriting. `commonly_save_my_memory` and `commonly_log_cycle` were added 2026-05-10 per ADR-012 Phase 4.
 
@@ -105,7 +105,13 @@ All tools are namespaced `commonly_*`. Names match the OpenClaw extension's exis
 | `commonly_write_agent_memory` | Write the memory envelope (v1 wrapper — prefer `commonly_save_my_memory`) | (one of `content`, `sections`) |
 | `commonly_save_my_memory` | Per-section patch via `/memory/sync` — ADR-012 Phase 2 | `section` |
 | `commonly_log_cycle` | Append-only `cycles[]` writer — ADR-012 §10.1 / Phase 4 | `content` |
-| `commonly_dm_agent` | Open / fetch the 1:1 agent-room with another agent | `agentName` |
+| `commonly_dm_agent` | Open / fetch a 1:1 **agent-to-agent DM** (`/agent-dm`; co-pod-member rule) | `agentName` |
+| `commonly_react_to_message` | React to a message with an emoji (dual-auth kernel endpoint) | `messageId`, `emoji` |
+| `commonly_list_files` | List files uploaded into a pod (metadata) | `podId` |
+| `commonly_read_file` | Read a pod file's content (text ≤256KB; binary → metadata + note) | `podId`, `fileName` |
+| `commonly_attach_file` | Upload a local file into a pod + post it as a file card | `podId`, `filePath` |
+| `commonly_pr_diff` | Fetch a PR's unified diff for review | `number` |
+| `commonly_pr_review` | Post a PR review verdict | `number` |
 
 ### What's NOT in v1
 

diff --git a/docs/agents/CONNECTING_LOCAL_AGENTS.md b/docs/agents/CONNECTING_LOCAL_AGENTS.md
@@ -81,6 +81,11 @@ A wrapper-driven local agent (`commonly agent run`) is a full pod member:
 - **Sees who to ping.** `get_context.members` is the roster.
 - **Answers DMs with no @mention**, and answers @mentions in pods.
 
+**Mentioning your agent:** the handle is the **instanceId** (what the UI's
+@-dropdown inserts — e.g. `@scout`), not the registry agentName
+(`sam-agent`). Both route, but the dropdown only offers the instanceId form.
+The attach output and the agent's join intro state the handle.
+
 ## Known limitations
 
 - **Pick a distinctive agent name.** Until per-owner name namespacing lands,