@stage-labs/metro 0.1.0-beta.4 → 0.1.0-beta.6

package/docs/agents.md

@@ -0,0 +1,168 @@
+# Metro: a guide for coding agents
+
+You are running inside a session that has **launched `metro`** in the background. Metro emits a live stream of JSON events from Discord, Telegram, and other agents on its stdout. Your job is to consume that stream and post replies back via subcommands.
+
+## Starting the bridge
+
+The launch mechanics differ by runtime — pick the one that matches yours.
+
+### Claude Code
+
+```
+Bash(command: "metro", run_in_background: true)
+```
+
+Then attach `Monitor` to its stdout. Each line is one JSON event you act on.
+
+### Codex
+
+```
+shell(command: "METRO_CODEX_RC=ws://127.0.0.1:8421 metro", run_in_background: true)
+```
+
+Don't watch its stdout — Codex has no Monitor equivalent. Metro pushes each event into your thread via JSON-RPC `turn/start`, so events arrive as user input on your next turn. The user must have a daemon and TUI running for this to work:
+
+```
+codex app-server --listen ws://127.0.0.1:8421       # daemon (terminal 1)
+codex --remote ws://127.0.0.1:8421                  # TUI (this session — terminal 2)
+```
+
+Run `metro doctor` if anything seems off.
+
+## Event shape
+
+Every event carries `id` (`msg_…`), `ts`, `from` (a universal participant URI), `fromName` (display name), `line` (conversation = `to`), and `messageId` (the platform-side id).
+
+```json
+{"type":"inbound","id":"msg_aB3xY7zP","ts":"2026-05-14T12:00:00Z","station":"telegram","line":"metro://telegram/-100…/247","from":"metro://telegram/user/12345","fromName":"@alice","messageId":"4567","text":"hello","attachmentNames":["[image]"],"mentionsBot":true,"meta":{"isPrivate":false,"inForum":true,"isForumTopic":true},"lineName":"infra"}
+```
+
+```json
+{"type":"notification","id":"msg_pQ4r5sT0","ts":"…","line":"metro://claude/deploys","from":"metro://codex/ci","text":"deploy succeeded"}
+```
+
+Both `from` and `to` are **participant URIs** (the conversation lives in `line`): `metro://<station>/user/<id>` for a person, `metro://claude/<topic>` / `metro://codex/<topic>` for an agent, `metro://<station>/<channelId>` as a fallback `to` when sending to a group with no single recipient.
+
+When **you** call `metro send`/`reply`/`edit`/`react`, metro auto-stamps `from` to your runtime — `metro://claude/agent` (from `$CLAUDECODE`) or `metro://codex/agent` (from `$METRO_CODEX_RC`/`$CODEX_HOME`). Override with `--from=<uri>` or `$METRO_FROM`. When replying/reacting, `to` is auto-set to the original sender (history lookup).
+
+- `type: "inbound"` — a human (or another bot) posted on a chat platform.
+- `type: "notification"` — another agent called `metro notify`/`metro send` against your agent line. This is how Codex pings Claude Code and vice versa.
+
+`text` may include `[image]` / `[voice]` / `[audio]` / `[file: <name>]` placeholders alongside the real text — non-image attachments are opaque markers, images can be materialized via `metro download`.
+
+## Required flow on every event
+
+1. **Echo the event** to your visible output: `[<line>#<messageId>] <text>`. Both Monitor and Codex collapse tool output, so this echo is the only thing the user sees without expanding cards.
+2. **Decide and act** using the subcommands below.
+
+## Subcommands
+
+| Action | Command |
+|---|---|
+| Quote-reply (threads under original) | `metro reply <line> <messageId> <text>` |
+| Send a fresh message (no reply context) | `metro send <line> <text>` |
+| Edit a message you previously sent | `metro edit <line> <messageId> <text>` |
+| Reaction (empty emoji clears it) | `metro react <line> <messageId> <emoji>` |
+| Download `[image]` attachments | `metro download <line> <messageId> [--out=<dir>]` |
+| Recent-message lookback (Discord only) | `metro fetch <line> [--limit=20]` |
+| Cross-agent ping | `metro notify <line> <text> [--from=<line>]` |
+
+`reply` / `send` / `edit` accept multi-line text via stdin (heredoc).
+
+### Rich content flags
+
+`send` and `reply` accept these flags; `edit` accepts `--buttons` only.
+
+- `--image=<path>` — local image. **Repeatable** for albums: `--image=a.png --image=b.png` (or comma-separated). Up to 10 / message. Text becomes the caption (on the first image for albums).
+- `--document=<path>` — local file (PDF, log, csv, …). Same repeat/comma syntax.
+- `--voice=<path>` — single voice message (`.ogg` Opus or `.mp3`). On Telegram renders as a voice bubble; on Discord uploaded as audio attachment.
+- `--buttons='[[{"text":"…","url":"…"}]]'` — inline URL-button keyboard (2D rows × buttons). Pass `'[]'` to `edit` to clear.
+
+```bash
+metro send <line> "screenshot" --image=/tmp/build.png
+metro send <line> "before/after" --image=/tmp/before.png --image=/tmp/after.png
+metro reply <line> <id> "voice note" --voice=/tmp/note.ogg
+metro send <line> "approve?" --buttons='[[{"text":"Open PR","url":"https://github.com/x/y/pull/1"}]]'
+```
+
+Limits: 20 MB / file. Telegram albums are single-type (photos OR documents per album); mixing kinds still works — metro splits into two messages. Buttons are dropped on multi-attachment Telegram sends. URL buttons only for now.
+
+Append `--json` to any command for a single JSON line you can parse.
+
+## When to use `reply` vs `send`
+
+- **`reply`** — responding to a specific inbound message. Threads under it. Default when handling an `inbound` event.
+- **`send`** — initiating without a triggering message: a long task you kicked off finished, a follow-up the user asked you to deliver later, or posting to an agent line (`metro://claude/...`, `metro://codex/...`) to notify a peer.
+
+## Universal message IDs
+
+The `id` field on every event and `metro history` row is metro's **universal ID** (`msg_<8 chars>`). It works anywhere a `<message_id>` is expected — `metro reply`, `edit`, `react`, `download` — and resolves to the platform's own id via the history file. Use it for chaining commands or referring back across stations.
+
+## `metro history` — read the universal message log
+
+Every inbound, outbound, edit, react, and notification is appended to `$METRO_STATE_DIR/history.jsonl` automatically.
+
+```bash
+metro history --limit=20                              # recent 20, newest first
+metro history --line=metro://discord/123              # only this conversation
+metro history --kind=inbound --since=2026-05-14       # inbounds since that day
+metro history --station=telegram --text=deploy        # all Telegram entries containing "deploy"
+metro history --from='@alice' --json                  # everything from alice, JSON
+```
+
+Filters: `--limit` (default 50), `--line`, `--station`, `--kind` (`inbound`/`outbound`/`edit`/`react`/`notification`), `--from`, `--text`, `--since` (ISO), `--json`.
+
+## Discovery
+
+### `metro lines`
+
+```
+$ metro lines
+2m ago    metro://discord/1234567890           infra
+5m ago    metro://telegram/-100123/42          design-review
+```
+
+Lines sorted by recency. Use when the user says "the Telegram channel" or "that PR thread."
+
+### `metro stations`
+
+```
+$ metro stations
+  ✓ discord    chat   in: text+image · out: text · features: reply, send, edit, react, download, fetch
+  ✓ telegram   chat   in: text+image · out: text · features: reply, send, edit, react, download, fetch
+  · claude     agent  in: text · out: – · features: notify
+  ✓ codex      agent  in: text · out: – · features: notify
+```
+
+`✓` = ready, `✗` = configured-but-broken, `·` = informational (agent stations have no setup).
+
+## Image attachments
+
+When an inbound has an `[image]` tag in `text`:
+
+1. `metro download <line> <messageId>` → prints absolute paths.
+2. `Read` each path with your `Read` tool — the image enters your context as a vision input.
+3. Reply normally via `metro reply`.
+
+## Cross-agent notification
+
+Both agents can post to each other's "agent line" — a logical channel under `metro://claude/<topic>` or `metro://codex/<topic>`. The daemon re-emits the post on its stdout stream (and pushes via codex-rc if configured), so the peer agent sees it as a notification:
+
+```bash
+metro send metro://claude/deploys "build green, ready to ship"
+# or equivalently:
+metro notify metro://claude/deploys "build green, ready to ship" --from=metro://codex/ci
+```
+
+This requires the metro daemon to be running on the machine. Without a daemon, agent-line sends error with a clear message.
+
+## Don'ts
+
+- ❌ Spawning a second metro daemon — there's one per machine (lockfile-enforced).
+- ❌ `metro send` to a line that isn't in `metro lines` unless the user gave it to you explicitly.
+- ❌ Narrating the tool ("I'll now use metro reply to…"). The tool call is already visible.
+
+## Further reading
+
+- URI scheme: [`uri-scheme.md`](uri-scheme.md)
+- Source: https://github.com/bonustrack/metro

package/docs/uri-scheme.md

@@ -0,0 +1,71 @@
+# Metro URI scheme
+
+Universal identifier for every conversational scope and notification sink in metro. Lines pass around as opaque strings; only the owning station parses its own paths.
+
+## Grammar
+
+```
+line       = "metro://" station "/" path
+station    = lowercase identifier (claude | codex | discord | telegram | …)
+path       = station-specific, "/"-separated segments
+```
+
+The URI parses cleanly with the WHATWG `URL` parser: `new URL(line)` gives `protocol="metro:"`, `host=<station>`, `pathname="/<path>"`.
+
+## Registered stations
+
+| Station    | Kind  | Pattern                                   | Example                               |
+|------------|-------|-------------------------------------------|---------------------------------------|
+| `discord`  | chat  | `metro://discord/<channel-id>`            | `metro://discord/1234567890123456789` |
+| `telegram` | chat  | `metro://telegram/<chat-id>[/<topic-id>]` | `metro://telegram/-1001234567890/42`  |
+| `claude`   | agent | `metro://claude/<topic>`                  | `metro://claude/deploys`              |
+| `codex`    | agent | `metro://codex/<topic>`                   | `metro://codex/ci`                    |
+
+## Participants
+
+Every chat station also exposes participant URIs — used as `from` on inbound/outbound events and history rows.
+
+| Kind  | Pattern                                  | Example                          |
+|-------|------------------------------------------|----------------------------------|
+| user  | `metro://<station>/user/<id>`            | `metro://discord/user/87654321`  |
+| agent | `metro://{claude,codex}/<topic>`         | `metro://claude/agent`           |
+
+`from` and `to` on history entries are always participant URIs. Discord/Telegram inbounds set `from` to the user URI; the daemon sets `to` to the agent identity (`metro://claude/agent` if `$CLAUDECODE` is detected, `metro://codex/agent` if `$METRO_CODEX_RC`/`$CODEX_HOME` is set, else `metro://agent`). On outbound, `from` = the same agent identity; `to` = the original sender for replies/reacts (looked up from history), or the channel `line` for fresh group sends. A `fromName` field carries the display name (`@alice`, `bonustrack_`).
+
+Override with `--from=<uri>` on any write command, or set `$METRO_FROM` to pin a custom identity for the whole session.
+
+Chat lines identify a Discord channel / Telegram chat (with optional forum topic). Agent lines are notification sinks — posting to one re-emits the message on the daemon's stdout stream and (if configured) pushes it to the Codex app-server. They have no inherent "messages"; only events.
+
+## Message addressing
+
+Messages on chat lines are referenced by **line + message id** (two args), not as part of the URI. So:
+
+```bash
+metro reply  metro://discord/123…  4567  "ack"
+metro edit   metro://discord/123…  9876  "fixed typo"
+metro react  metro://telegram/-100…/42  4567  👍
+```
+
+## Properties
+
+- **Stable**: a Line is valid for the lifetime of the scope.
+- **Self-describing**: the station name is encoded; the dispatcher routes by station prefix.
+- **Persistable**: safe as a JSON key on disk (used by `lines.json`).
+- **Branded**: TypeScript type `Line` prevents mixing with arbitrary strings.
+
+## API
+
+```ts
+import { Line } from './stations/index.js';            // value namespace + type
+
+const l: Line = Line.discord('1234567890');     // typed Line
+Line.parse(l);                                   // { station: 'discord', path: ['1234567890'] } | null
+Line.station(l);                                 // 'discord'
+Line.isAgent(Line.claude('deploys'));            // true
+```
+
+## Adding a new station
+
+1. Pick a lowercase station name (`slack`, `matrix`, …).
+2. Add a `Line.<station>(...)` formatter and a parser that returns your typed payload.
+3. Document the path grammar in the table above.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@stage-labs/metro",
-  "version": "0.1.0-beta.4",
-  "description": "Orchestrator daemon that bridges Codex / Claude Code agent sessions with Telegram and Discord. Each chat thread gets its own agent session, with streaming responses and tool-call visibility.",
+  "version": "0.1.0-beta.6",
+  "description": "Live JSON stream of Telegram + Discord messages for your local Claude Code / Codex session. The agent launches metro; metro emits inbounds on stdout and accepts replies via CLI subcommands.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -14,10 +14,12 @@
     "node": ">=22"
   },
   "bin": {
-    "metro": "./dist/cli.js"
+    "metro": "./dist/cli/index.js"
   },
   "files": [
     "dist",
+    "docs",
+    "skills",
     "README.md",
     "LICENSE"
   ],
@@ -34,6 +36,7 @@
   "dependencies": {
     "discord.js": "^14.14.0",
     "pino": "^9.5.0",
+    "pino-pretty": "^13.1.3",
     "ws": "^8.20.0"
   },
   "devDependencies": {

package/skills/metro/SKILL.md

@@ -0,0 +1,220 @@
+---
+name: metro
+description: Run the metro Telegram/Discord bridge in this session — launch `metro` in the background, watch its stdout for inbound JSON events, and act on each. Use when the user asks to start/run/launch metro, when you see JSON lines on stdout shaped `{"type":"inbound","station":...,"line":"metro://...","messageId":...,"text":...}`, or when handling a chat reply/edit/react/send/download/fetch/notify.
+---
+
+# Metro — running the Telegram & Discord bridge
+
+Metro is a CLI bridge between this agent session and Telegram/Discord. You launch `metro` once when the user asks, then act on each inbound JSON line via `metro <subcommand>`.
+
+## Starting the bridge
+
+When the user asks to run/start/launch metro:
+
+### Claude Code
+
+```
+Bash(command: "metro", run_in_background: true)
+```
+
+Then attach `Monitor` to its stdout. Each line is one JSON event. Stderr is pino logs — don't act on it.
+
+### Codex
+
+```
+shell(command: "METRO_CODEX_RC=ws://127.0.0.1:8421 metro", run_in_background: true)
+```
+
+Codex has no Monitor equivalent. Instead, metro pushes each event into your thread via JSON-RPC `turn/start`, so events arrive as user input on your next turn. The user must have a daemon + TUI running on the **same WebSocket URL**:
+
+```
+codex app-server --listen ws://127.0.0.1:8421     # daemon (terminal 1)
+codex --remote ws://127.0.0.1:8421                # TUI (terminal 2) — type "hi" once to create a live thread
+```
+
+Then metro starts third. If metro exits immediately or you see `thread not found` retries on its stderr, the TUI didn't create a thread yet — tell the user to type something in the TUI.
+
+### Diagnostics
+
+If something seems off, run `metro doctor`. Common causes: missing tokens (`metro setup telegram <token>` / `metro setup discord <token>`), Discord Message Content Intent not toggled, stale lockfile, or (Codex) no live thread on the daemon.
+
+## Event shape
+
+Every line on stdout is one JSON object. Each event carries:
+- `id` (`msg_…`) — universal message ID minted by metro
+- `ts` — ISO timestamp
+- `from` — universal **participant URI** of the sender (a Line)
+- `fromName` — optional human-readable display name (`@alice`, `bonustrack_`)
+- `line` — the conversation URI (also the implicit `to`)
+- `messageId` — the platform-side id (Discord snowflake, Telegram int, …)
+
+```json
+{"type":"inbound","id":"msg_aB3xY7zP","ts":"2026-05-14T12:00:00Z","station":"telegram","line":"metro://telegram/-100…/247","from":"metro://telegram/user/12345","fromName":"@alice","messageId":"4567","text":"hi","attachmentNames":["[image]"],"mentionsBot":true,"meta":{"isPrivate":false,"inForum":true,"isForumTopic":true},"lineName":"infra"}
+```
+
+```json
+{"type":"notification","id":"msg_pQ4r5sT0","ts":"…","line":"metro://claude/deploys","from":"metro://codex/ci","text":"deploy green"}
+```
+
+Both `from` and `to` are **participant URIs** (the conversation context lives in `line`):
+- `metro://<station>/user/<id>` — a person on a chat platform
+- `metro://claude/<topic>` / `metro://codex/<topic>` — an agent
+- `metro://<station>/<channelId>` — a channel (used as `to` for fresh sends to a group, where no single recipient)
+
+When **you** send via `metro send`/`reply`/`edit`/`react`, metro auto-stamps `from = metro://claude/agent` (from `$CLAUDECODE`) or `metro://codex/agent` (from `$METRO_CODEX_RC` / `$CODEX_HOME`). Override with `--from=<uri>` or `$METRO_FROM`. When replying/reacting, `to` is automatically the original sender (looked up via the universal id).
+
+The `id` is the **canonical handle** for that message across all stations — store it if you want to refer back to it later.
+
+- `type: "inbound"` — a human (or another bot) posted on a chat platform.
+- `type: "notification"` — another agent called `metro notify` / `metro send` against your agent line. This is how Codex pings Claude Code and vice versa.
+
+`text` may contain `[image]`, `[voice]`, `[audio]`, or `[file: <name>]` placeholders alongside the real text — non-image attachments are opaque markers; images can be materialized via `metro download`.
+
+## Required flow on every event
+
+1. **Echo to your visible output**: `[<line>#<messageId>] <text>` on its own line. Both Claude Code's Monitor and Codex collapse tool output, so this echo is the only way the user sees what arrived without expanding cards.
+2. **Decide and act** using the subcommands below.
+
+No server-side auto-reaction — don't expect 👀 to be on the user's message; add one yourself with `metro react` if you want to ack quickly.
+
+## Subcommands
+
+All take positional args (no `--to=`/`--text=` flags). Append `--json` to any for a parseable single-line result.
+
+| Action | Command |
+|---|---|
+| Quote-reply (threads under original) | `metro reply <line> <messageId> <text>` |
+| Send a fresh message (no reply context) | `metro send <line> <text>` |
+| Edit a message you previously sent | `metro edit <line> <messageId> <text>` |
+| Reaction (empty emoji clears) | `metro react <line> <messageId> <emoji>` |
+| Download `[image]` attachments → paths | `metro download <line> <messageId> [--out=<dir>]` |
+| Recent channel history (Discord only) | `metro fetch <line> [--limit=20]` |
+| Ping another agent (cross-agent line) | `metro send metro://claude/<topic> <text>` or `metro notify <line> <text> [--from=<line>]` |
+
+`reply` / `send` / `edit` accept multi-line text via stdin (heredoc).
+
+### Rich content flags
+
+`send` and `reply` accept these extra flags; `edit` accepts `--buttons` only.
+
+- `--image=<path>` — upload a local image. **Repeatable** for albums: `--image=a.png --image=b.png`. Comma-separated also works: `--image='a.png,b.png'`. Up to 10 / message. Text becomes the caption (on the first image for albums).
+- `--document=<path>` — upload any local file (PDF, log, csv, …). Same repeat/comma syntax.
+- `--voice=<path>` — single voice message (`.ogg` Opus or `.mp3`). On Telegram renders as a voice bubble via `sendVoice`; on Discord uploaded as an audio attachment.
+- `--buttons='[[{"text":"…","url":"https://…"}]]'` — attach an inline URL-button keyboard. 2D array: outer = rows, inner = buttons on that row.
+
+```bash
+metro send <line> "screenshot"                     --image=/tmp/build.png
+metro send <line> "before/after"                   --image=/tmp/before.png --image=/tmp/after.png
+metro reply <line> <id> "log + transcript"          --document=/tmp/run.log --document=/tmp/transcript.txt
+metro send <line> "have a listen"                  --voice=/tmp/note.ogg
+metro send <line> "approve?" --buttons='[[{"text":"Open PR","url":"https://github.com/x/y/pull/1"}]]'
+metro edit <line> <id> "still working…" --buttons='[]'    # clears buttons
+```
+
+Limits / quirks:
+- 20 MB per file (both platforms).
+- Telegram albums are single-type (all photos OR all documents in one album). Mixing kinds in one send still works — metro splits into two album messages and returns the first id.
+- Telegram drops `--buttons` when multiple attachments are sent (the bot API doesn't allow `reply_markup` on media groups).
+- URL buttons only (no callback / interactive components yet).
+
+## When to use `reply` vs `send`
+
+- **`reply`** — responding to a specific inbound message. Threads under it. Default for handling an `inbound` event.
+- **`send`** — initiating without a triggering message: a long task finished, a follow-up the user asked you to deliver later, or posting to an agent line (`metro://claude/...`, `metro://codex/...`) to notify a peer.
+
+## Line URI scheme
+
+`metro://<station>/<path>` — see [docs/uri-scheme.md](https://github.com/bonustrack/metro/blob/main/docs/uri-scheme.md) for the full grammar.
+
+| Station    | Pattern                                   | Example                              |
+|------------|-------------------------------------------|--------------------------------------|
+| `discord`  | `metro://discord/<channel-id>`            | `metro://discord/1234567890`         |
+| `telegram` | `metro://telegram/<chat-id>[/<topic-id>]` | `metro://telegram/-1001234567890/42` |
+| `claude`   | `metro://claude/<topic>`                  | `metro://claude/deploys`             |
+| `codex`    | `metro://codex/<topic>`                   | `metro://codex/ci`                   |
+
+The `messageId` is **not** part of the URI — it's a separate positional arg for `reply` / `edit` / `react` / `download`.
+
+## Image attachments
+
+When an event's `text` contains `[image]`:
+
+1. `metro download <line> <messageId>` — writes images to disk and prints absolute paths.
+2. `Read` each path with your Read tool — the image enters your context as a vision input.
+3. Reply normally with `metro reply`.
+
+## Opaque attachment markers
+
+`[voice]`, `[audio]`, and `[file: <name>]` are opaque — `metro download` only handles images. Acknowledge in text or ask the user to resend as a regular file.
+
+## Cross-agent notification
+
+Both agents can post to each other's "agent line":
+
+```bash
+metro send metro://claude/deploys "build green, ready to ship"
+# or
+metro notify metro://codex/ci "build green" --from=metro://claude/deploys
+```
+
+The daemon re-emits the post on its stdout stream (and pushes via codex-rc if configured), so the peer agent sees a `{"type":"notification",...}` event. Requires the metro daemon to be running on the machine — agent-line sends error with `metro daemon is not running` otherwise.
+
+## Discoverability
+
+- `metro lines` — list recently-seen conversations (sorted by recency).
+- `metro stations` — list stations + capability matrix.
+- `metro history` — universal message log (every inbound + outbound + notification across all stations). Newest first. Filters:
+  - `--limit=N` (default 50)
+  - `--line=<metro://…>` — only this conversation
+  - `--station=<discord|telegram|claude|codex>`
+  - `--kind=<inbound|outbound|edit|react|notification>`
+  - `--from=<sender>`
+  - `--text=<substring>`
+  - `--since=<iso>` — e.g. `--since=2026-05-14T00:00:00Z`
+  - `--json` — machine-parseable
+
+Every action you take is logged automatically — `metro send`/`reply`/`edit`/`react` append outbound entries, daemon-side inbounds + notifications append on arrival. Stored at `$METRO_STATE_DIR/history.jsonl`.
+
+## Universal message IDs
+
+The `id` from `metro history` or an event JSON works **anywhere a `<message_id>` argument is expected**:
+
+```bash
+# Either form works for reply/edit/react/download:
+metro reply <line> 4567                "ack"     # platform messageId (Telegram int)
+metro reply <line> msg_aB3xY7zP        "ack"     # universal — resolves via history
+```
+
+Use universal IDs when chaining commands or referring back to a specific message across stations.
+
+## Exit codes
+
+- `0` success
+- `1` usage error (bad args, unknown subcommand)
+- `2` configuration error (no tokens — tell the user to run `metro setup`)
+- `3` upstream error (rate limit, auth, network) — retry once after a few seconds before surfacing
+
+`metro doctor` diagnoses tokens, gateways, dispatcher liveness, and codex-rc target.
+
+## --json output
+
+Every command supports `--json` for stable parseable output:
+
+```bash
+metro reply <line> <messageId> "ack" --json
+# {"ok":true,"line":"metro://discord/...","replyTo":"...","messageId":"..."}
+
+metro fetch metro://discord/1234 --limit=10 --json
+# {"ok":true,"line":"...","messages":[{"messageId":"...","author":"...","text":"...","timestamp":"..."},...]}
+
+metro download <line> <messageId> --json
+# {"ok":true,"line":"...","files":[{"path":"/abs/...png","mediaType":"image/png"}]}
+```
+
+Use `--json` when you need to chain calls or capture the new `messageId` for a later edit.
+
+## Don'ts
+
+- ❌ Spawning a second metro daemon — there's one per machine (lockfile-enforced).
+- ❌ Posting to a line that isn't in `metro lines` unless the user gave it to you explicitly.
+- ❌ Narrating the tool ("I'll now use metro reply to…"). The tool call is already visible to the user.