hamr0 · hamr0 · Jun 16, 2026 · Jun 16, 2026
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -16,7 +16,7 @@ Published tags on GHCR: `:X.Y.Z` (exact, immutable), `:X.Y` (rolling within a mi
 
 ### Documentation
 
-- **README rewrite to reflect v0.6 → v0.8.** The root README was restructured onto the shared `bare`-ecosystem skeleton and brought current with the last three releases. The lead now names both run modes (Docker *and* `npx`), a **Two ways to run** table up top contrasts Container vs Lite (where Beeper lives, deps, start command, first-run login) and states the same-single-file version-parity guarantee, and `Quick start` / `Lite mode` are retitled **Quick start (container)** / **Lite mode (`npx`)** with the now-redundant inline comparison table dropped. New **The MCP** section — the "what's inside" map — documents all 12 verbs grouped Read/triage · Write/act · Watch/reach, surfacing the previously undocumented `poll_messages` watch primitive + restart-safe cursor + `source` echo-guard (0.6.0) and `attachments[]` + `download_asset` byte reach (0.7.0). Stale `BEEPERBOX_IMAGE_TAG=0.7.0` pin example bumped to `0.8.0`. The npm-page `mcp/README.md` is deliberately kept as a focused lite-mode landing page (not a copy of the full README); its two cross-links were repointed to the renamed anchors (`#quick-start-container`, `#lite-mode-npx`).
+- **README rewrite to reflect v0.6 → v0.8.** The root README was restructured onto the shared `bare`-ecosystem skeleton and brought current with the last three releases. The lead now names both run modes (Docker *and* `npx`), a **Two ways to run** table up top contrasts Container vs Lite (where Beeper lives, deps, start command, first-run login) and states the same-single-file version-parity guarantee, and `Quick start` / `Lite mode` are retitled **Quick start (container)** / **Lite mode (`npx`)** with the now-redundant inline comparison table dropped. New **The MCP** section — the "what's inside" map — documents all 12 verbs grouped Read/triage · Write/act · Watch/reach, surfacing the previously undocumented `poll_messages` watch primitive + restart-safe cursor + `source` echo-guard (0.6.0) and `attachments[]` + `download_asset` byte reach (0.7.0). Stale `BEEPERBOX_IMAGE_TAG=0.7.0` pin example bumped to `0.8.0`. The npm-page `mcp/README.md` was reshaped onto the same `bare`-ecosystem skeleton (banner, badges, quick start, a compact 12-verb map, the bare-ecosystem footer) but kept lighter than the full README — still a focused lite-mode landing page, not a copy; cross-links repointed to the renamed/added anchors (`#quick-start-container`, `#the-mcp`).
 
 ## [0.8.0] — 2026-06-16 `[MINOR]`
 

diff --git a/mcp/README.md b/mcp/README.md
@@ -1,4 +1,17 @@
-# beeperbox (lite mode)
+```
+                ╭──────────────────────────────────╮
+                │  ╔╗ ╔═╗╔═╗╔═╗╔═╗╦═╗╔╗ ╔═╗ ╦ ╦    │
+                │  ╠╩╗╠╣ ╠╣ ╠═╝╠╣ ╠╦╝╠╩╗║ ║ ╚╦╝    │
+                │  ╚═╝╚═╝╚═╝╩  ╚═╝╩╚═╚═╝╚═╝ ╩ ╩    │
+                │   one agent ──→ 50+ messengers   │
+                ╰──────────────────────────────────╯
+```
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/beeperbox"><img src="https://img.shields.io/npm/v/beeperbox?label=npm&color=2a4f8c" alt="npm version"></a>
+  <a href="https://github.com/hamr0/beeperbox"><img src="https://img.shields.io/badge/source-github-2a4f8c" alt="source on GitHub"></a>
+  <img src="https://img.shields.io/badge/license-Apache%202.0-2a4f8c" alt="license: Apache 2.0">
+</p>
 
 **Run beeperbox's MCP verb server against a Beeper Desktop you already have open — no Docker, no Electron, no Xvfb.**
 
@@ -7,25 +20,32 @@ This is the *lite* half of [beeperbox](https://github.com/hamr0/beeperbox). The
 - **Always-on / VPS / no local Beeper?** Use the [Docker image](https://github.com/hamr0/beeperbox#quick-start-container).
 - **Beeper already open on your machine?** Use this.
 
-## Prerequisites
+## Quick start
 
-1. **Beeper Desktop** running locally.
-2. **Developer API enabled:** Beeper → **Settings → Developers** → enable the API and create an access token (the same token the container uses).
-
-## Run
+**Prereqs:** Beeper Desktop running locally, with the Developer API enabled — Beeper → **Settings → Developers** → enable the API and create an access token (the same token the container uses).
 
 ```sh
 BEEPER_TOKEN=your-token-here npx beeperbox
 ```
 
 That starts the MCP HTTP server on `http://127.0.0.1:23375`, pointed at the local Beeper Desktop API on `http://127.0.0.1:23373`. On boot it logs a one-line reachability verdict (`preflight OK: … N account(s)` or `preflight FAIL: …`) so a misconfigured token or API is obvious immediately.
 
-For stdio transport (Claude Code, Cursor, Cline, Continue, bareagent):
+For stdio transport (Claude Code, Cursor, Cline, Continue, [bareagent](https://npmjs.com/package/bare-agent)):
 
 ```sh
 BEEPER_TOKEN=your-token-here npx beeperbox --stdio
 ```
 
+## The 12 tools
+
+One opinionated MCP verb layer over Beeper — every tool returns a normalized `Chat` / `Message` schema, propagates `chat_id` + `network` onto every message, and is documented in-schema for the model. Reach across all 50+ networks without knowing which bridge you're talking to.
+
+- **Read / triage** — `list_accounts` · `list_inbox` · `list_unread` · `get_chat` · `read_chat` · `search_messages`
+- **Write / act** — `send_message` · `note_to_self` · `react_to_message` · `archive_chat`
+- **Watch / reach** — `poll_messages` (read-only watch primitive, restart-safe cursor, `source` echo-guard) · `download_asset` (attachment bytes; every message carries `attachments[]`)
+
+Full schemas and usage in the [main README](https://github.com/hamr0/beeperbox#the-mcp).
+
 ## Config
 
 | Env | Meaning | Default |
@@ -45,6 +65,19 @@ The server binds **loopback only** (`127.0.0.1`) by default, so it's safe with n
 
 There's no Docker restart policy in lite mode. For an always-on setup, run it under `systemd` or `pm2`.
 
-See the [full README](https://github.com/hamr0/beeperbox#lite-mode-npx) and [docs/GUIDE.md](https://github.com/hamr0/beeperbox/blob/master/docs/GUIDE.md) for the complete tool reference and the container build.
+See the [full README](https://github.com/hamr0/beeperbox#the-mcp) and [docs/GUIDE.md](https://github.com/hamr0/beeperbox/blob/master/docs/GUIDE.md) for the complete tool reference and the container build.
+
+## The bare ecosystem
+
+Local-first, composable agent infrastructure. Same API patterns throughout — mix and match, each module works standalone.
+
+- **[bareagent](https://npmjs.com/package/bare-agent)** — the think→act→observe loop. *Goal in → coordinated actions out.*
+- **[bareguard](https://npmjs.com/package/bareguard)** — the single gate every action passes through. *Action in → allow / deny / ask-a-human out.*
+- **[litectx](https://npmjs.com/package/litectx)** — code + memory graph with activation decay. *Query in → ranked context out.*
+- **[barebrowse](https://npmjs.com/package/barebrowse)** — a real browser for agents. *URL in → pruned snapshot out.*
+- **[baremobile](https://npmjs.com/package/baremobile)** — Android + iOS device control. *Screen in → pruned snapshot out.*
+- **beeperbox** *(this)* — 50+ messaging networks via one MCP server. *Chat in → unified message stream out.*
+
+## License
 
-[Apache-2.0](https://github.com/hamr0/beeperbox/blob/master/LICENSE)
+[Apache-2.0](https://github.com/hamr0/beeperbox/blob/master/LICENSE). Independent wrapper around Beeper Desktop, no affiliation with Beeper / Automattic.