docs(readme): refresh for v0.6→v0.8, add MCP tool map

CHANGELOG.md

@@ -12,6 +12,12 @@ beeperbox follows [Semantic Versioning 2.0.0](https://semver.org/) with one conc
 
 Published tags on GHCR: `:X.Y.Z` (exact, immutable), `:X.Y` (rolling within a minor), `:X` (rolling within a major — always `:0` today), `:latest` (newest release tag, rebuilt weekly to pick up upstream Beeper AppImage drift), `:edge` (every push to `master`, may break).
 
+## [Unreleased]
+
+### 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`).
+
 ## [0.8.0] — 2026-06-16 `[MINOR]`
 
 **Lite mode** — a first-class, supported way to run beeperbox's MCP verb server standalone against a Beeper Desktop the user already runs locally (no Docker, no Electron, no Xvfb). Driven by [multis](https://github.com/hamr0/multis), beeperbox's first consumer: laptop users with Beeper already open get the verbs without the whole container, while the container stays the answer for always-on/VPS. Same single `mcp/server.js` either way, so the tool surface and `serverInfo.version` are identical by construction — lite mode is the *packaging*, not a fork. MINOR per the versioning policy (new runtime behavior — a boot preflight + new distribution mode), and it carries one bug fix that also mattered to the container. Validated live: the full send → restart → poll round-trip echo-guard persistence was proven against a real Beeper account running on the host.

README.md

@@ -14,11 +14,25 @@
   <img src="https://img.shields.io/badge/license-Apache%202.0-2a4f8c" alt="license: Apache 2.0">
 </p>
 
-**One Docker container that plugs your AI agent into 50+ messengers through a single MCP endpoint.**
+**Plug your AI agent into 50+ messengers through a single MCP endpoint — in Docker, or as a one-line `npx`.**
 
 WhatsApp, iMessage, Signal, Telegram, Discord, Slack, Messenger, Instagram, LinkedIn, Google Messages, Matrix — everything [Beeper](https://www.beeper.com/) bridges, reachable from one HTTP or MCP endpoint instead of 50 per-platform SDKs, OAuth dances, and rate-limit quirks. If you only need Telegram, this is overkill — use [openclaw](https://github.com/openclaw/openclaw) or any BotFather library. If you need reach across many networks from one agent, keep reading.
 
-## Quick start
+## Two ways to run
+
+Same MCP server, same 12 tools, same `serverInfo.version` — by construction, because both modes run the [same single file](mcp/server.js). Pick by where Beeper lives:
+
+| | **Container** | **Lite** (`npx`) |
+|---|---|---|
+| Beeper Desktop | bundled, headless, in Docker | **you** supply it (already open on your machine) |
+| Needs | Docker + compose | just Node 18+ |
+| Start | `docker compose up -d` | `npx beeperbox` |
+| Best for | always-on, VPS, headless | laptop users with Beeper already running |
+| First-run login | noVNC at `:6080` | already done in your local Beeper |
+
+The container is the full appliance (headless Beeper + raw API + MCP). Lite mode is **just the MCP verb layer** pointed at a Beeper you already run — no Docker, no Electron, no Xvfb. New in [v0.8.0](CHANGELOG.md).
+
+## Quick start (container)
 
 Prereqs: Docker + compose plugin, ~1 GB disk, ~600 MB RAM, a Beeper account.
 
@@ -29,7 +43,7 @@ curl -LO https://raw.githubusercontent.com/hamr0/beeperbox/master/docker-compose
 docker compose up -d
 ```
 
-Pulls the pre-built multi-arch image (`ghcr.io/hamr0/beeperbox:latest`, `linux/amd64` + `linux/arm64`). No clone, no build. Pin a version with `BEEPERBOX_IMAGE_TAG=0.7.0 docker compose up -d`, or track master with `:edge` (may break).
+Pulls the pre-built multi-arch image (`ghcr.io/hamr0/beeperbox:latest`, `linux/amd64` + `linux/arm64`). No clone, no build. Pin a version with `BEEPERBOX_IMAGE_TAG=0.8.0 docker compose up -d`, or track master with `:edge` (may break).
 
 **2. Log in once**
 
@@ -68,15 +82,7 @@ Done.
 
 All three are env-overridable (`BEEPERBOX_NOVNC_PORT`, `BEEPERBOX_HOST_PORT`, `BEEPERBOX_MCP_PORT`) so you can run multiple instances on one VPS. For remote access use SSH tunnel, Tailscale, or a TLS reverse proxy — never drop the `127.0.0.1` prefix.
 
-## Lite mode
-
-Two ways to run beeperbox, same verb layer:
-
-| | **Container** (above) | **Lite mode** |
-|---|---|---|
-| Beeper Desktop | bundled, headless, in Docker | **you** supply it (already open on your machine) |
-| Needs | Docker | just Node 18+ |
-| Best for | always-on, VPS, headless | laptop users with Beeper already running |
+## Lite mode (`npx`)
 
 Lite mode runs only the MCP verb server against a Beeper Desktop you already run locally — no Docker, no Electron, no Xvfb. It's the same single file the container runs, so the tool surface and `serverInfo.version` are identical by construction.
 
@@ -117,6 +123,39 @@ BEEPER_TOKEN=your-token-here npx beeperbox --stdio
 
 **What lite mode is *not*:** it does not bundle or headless-run Beeper (that's the container's job). No new verbs, no transport changes — it's the same server, packaged and safe to run standalone.
 
+## The MCP
+
+Not a thin proxy over Beeper's raw API — an **opinionated 12-tool verb layer** built for an LLM to drive. Every tool returns one normalized `Chat` / `Message` schema (so the agent never learns a second shape), propagates `chat_id` + `network` onto every message (no second lookup to know where a hit came from), and is documented in-schema for the model. Reach across all 50+ networks; the agent never knows which bridge it's talking to.
+
+**Read / triage**
+
+| Tool | What it does |
+|---|---|
+| `list_accounts` | Which networks are connected (WhatsApp, Telegram, Discord …) — slug + label + display name |
+| `list_inbox` | Most recently active chats, with unread counts and last-activity time |
+| `list_unread` | The "what needs me right now?" view — only chats with `unread_count > 0` |
+| `get_chat` | One chat's current metadata by ID |
+| `read_chat` | Recent messages of a chat, chronological, normalized |
+| `search_messages` | Full-text search across every chat |
+
+**Write / act**
+
+| Tool | What it does |
+|---|---|
+| `send_message` | The headline write — reply or initiate; markdown, `reply_to_message_id`, returns the new message ID |
+| `note_to_self` | The agent's private command/control channel — recorded, excluded from every inbox view |
+| `react_to_message` | Lightest "I saw it" — a unicode emoji, visible to the sender on every network |
+| `archive_chat` | The "done with this conversation" primitive (Beeper exposes no mark-as-read) |
+
+**Watch / reach** — the last two releases
+
+| Tool | What it does |
+|---|---|
+| `poll_messages` | Read-only **watch primitive**: "what arrived since this cursor?" Seed once, persist the opaque cursor, poll with zero side effects. The cursor is **restart-safe** — survives a container/process restart with no missed or duplicated messages. Each message carries a `source` field (`"api"` for beeperbox's own sends, `"external"` otherwise) so a poll loop never answers itself. *(v0.6.0)* |
+| `download_asset` | The MCP-only way to reach attachment **bytes** (base64). Every `Message` now carries `attachments[]` (`{type, file_name, mime_type, src_url, size, is_voice_note}`); fetch by `src_url` or by `chat_id`+`message_id`. Byte-capped and timeout-bounded; a defense-in-depth guard refuses `file://` paths outside Beeper's media cache. *(v0.7.0)* |
+
+Reliable echo-suppression (`source` + the optional `client_tag` idempotency tag) means an agent on a poll loop can send *and* watch the same chat without mistaking its own messages for inbound — the wiring that lets [multis](https://github.com/hamr0/multis) drop its text-prefix hacks.
+
 ## Build from source
 
 Only if you're hacking on the image itself or running air-gapped:

mcp/README.md

@@ -4,7 +4,7 @@
 
 This is the *lite* half of [beeperbox](https://github.com/hamr0/beeperbox). The full project ships a Docker image with a headless Beeper Desktop inside; lite mode is the same single-file, zero-dependency MCP server pointed at a Beeper Desktop **you** run on your laptop. Identical verb surface, identical version — you just supply Beeper.
 
-- **Always-on / VPS / no local Beeper?** Use the [Docker image](https://github.com/hamr0/beeperbox#quick-start).
+- **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
@@ -45,6 +45,6 @@ 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) 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#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.
 
 [Apache-2.0](https://github.com/hamr0/beeperbox/blob/master/LICENSE)