claudemesh/.artifacts/backlog/2026-04-11-v1-feature-inventory.md

# claudemesh v1 — Feature Inventory

**Status:** backlog reference
**Created:** 2026-04-11
**Purpose:** Exhaustive audit of what v1 ships today. **Every row in this document must still work after v2 lands.** v2 is a refactor + CLI user flows, NOT a functional rewrite; this inventory is the regression checklist.

**Source of truth**:
- `apps/cli/src/` — 22 files, ~12 k LOC (v0.10.5)
- `apps/broker/src/` — 23 files, ~11 k LOC
- `packages/db/src/schema/mesh.ts` — 1,019 lines, 23 tables

---

## 0. Summary counts

| Surface | v1 count |
|---|---|
| CLI commands (subcommands in `index.ts`) | 23 |
| MCP tools (handlers in `mcp/server.ts`) | 79 |
| Broker WS message types (dispatched in `index.ts`) | 85 |
| Broker HTTP endpoints | 18 |
| Postgres tables in `mesh` schema | 23 |
| External backend services the broker manages | 5 (Postgres, Neo4j, Qdrant, MinIO, Docker) |
| Lines of source (CLI + broker, excluding tests) | ~23,450 |

---

## 1. CLI commands

All dispatched from `apps/cli/src/index.ts`. v1 ships 23 public subcommands plus the bare-command welcome wizard.

| Command | File | Purpose | Flags / args |
|---|---|---|---|
| `claudemesh` (bare) | `commands/welcome.ts` | Interactive welcome wizard. Entry point for new users. | (none) |
| `launch` | `commands/launch.ts` (775 lines, biggest) | Spawn a Claude Code session with mesh connectivity + MCP tools | `--name`, `--role`, `--groups`, `--mesh`, `--join`, `--message-mode`, `--system-prompt`, `-y/--yes`, `-r/--resume`, `-c/--continue`, `--quiet`, + passthrough to `claude` after `--` |
| `create` | `commands/create.ts` | Create a new mesh from a template | `--template`, `--list-templates` |
| `install` | `commands/install.ts` (538 lines) | Register MCP server + status hooks with Claude Code (`~/.claude.json`, `~/.claude/settings.json`) | `--no-hooks` |
| `uninstall` | `commands/install.ts` | Remove MCP server + hooks from Claude Code config | (none) |
| `join` | `commands/join.ts` (193 lines) | Join a mesh via invite URL or token | positional `<url>` |
| `list` | `commands/list.ts` | Show joined meshes, slugs, local identities | (none) |
| `leave` | `commands/leave.ts` | Leave a joined mesh + remove its local keypair | positional `<slug>` |
| `peers` | `commands/peers.ts` | List online peers with status, summary, groups | `--mesh`, `--json` |
| `send` | `commands/send.ts` | Send a message to a peer, group, or all peers | positional `<to> <message>`, `--mesh`, `--priority` |
| `inbox` | `commands/inbox.ts` | Drain pending inbound messages | `--mesh`, `--json`, `--wait` |
| `state` | `commands/state.ts` | Get / set / list shared KV state in the mesh | positional `<action> <key> [value]`, `--mesh`, `--json` |
| `info` | `commands/info.ts` | Mesh overview: slug, broker, peer count, state keys | `--mesh`, `--json` |
| `remember` | `commands/memory.ts` | Store a persistent memory visible to all peers | positional `<content>`, `--mesh`, `--tags`, `--json` |
| `recall` | `commands/memory.ts` | Full-text search of mesh memories | positional `<query>`, `--mesh`, `--json` |
| `remind` | `commands/remind.ts` (142 lines) | Schedule a delayed message. Also: `remind list`, `remind cancel <id>` | positional `<message>`, `--in`, `--at`, `--cron`, `--to`, `--mesh`, `--json` |
| `sync` | `commands/sync.ts` | Sync meshes from the user's claudemesh.com dashboard account | `--force` |
| `profile` | `commands/profile.ts` | View or edit member profile (self or another member if admin) | `--mesh`, `--role-tag`, `--groups`, `--message-mode`, `--name`, `--member`, `--json` |
| `status` | `commands/status.ts` | Check broker connectivity for each joined mesh | (none) |
| `doctor` | `commands/doctor.ts` (212 lines) | Diagnose install, config, keypairs, PATH | 7 checks: Node >= 20, claude binary, MCP registered, hooks registered, config parses, file perms, keypairs valid |
| `mcp` | `mcp/server.ts` (2139 lines) | Start MCP server on stdio (internal — invoked by Claude Code) | (none) |
| `seed-test-mesh` | `commands/seed-test-mesh.ts` | Dev-only: inject a mesh into local config without invite flow | `<slug>`, `<broker_url>` |
| `hook` | `commands/hook.ts` | Internal: handle Claude Code hook events (status updates from session lifecycle) | stdin JSON from Claude Code |
| `connect telegram` | `commands/connect-telegram.ts` | Link a Telegram bot to a mesh | inline token prompts, calls broker `/tg/token` |
| `disconnect telegram` | `commands/disconnect-telegram.ts` | Unlink Telegram bot | (none) |

### Flag-first invocation rewrite

`apps/cli/src/index.ts` lines 339–355 implement a **friction reducer**: if the user types `claudemesh --resume xxx` or any flag-first invocation, the argv is rewritten to `claudemesh launch --resume xxx` before citty parses it. This lets users skip typing `launch` for common flag-only forms.

**Must preserve in v2.** Users may depend on this. Applies to `--resume`, `--continue`, `-y`, `--mesh`, `--name`, etc.

---

## 2. MCP tools (79 total)

Defined in `apps/cli/src/mcp/tools.ts` with schemas, implemented in `apps/cli/src/mcp/server.ts` with per-tool case handlers. Each MCP tool is a RPC that the CLI's MCP server handles locally or forwards to the broker via WS.

Grouped by domain family. Every tool listed here has a working handler in v1.

### 2.1 Messaging (4)

| Tool | v1 behavior |
|---|---|
| `send_message` | Send encrypted message to peer, group, or broadcast. Supports priorities: `now` (immediate), `next` (default), `low`. Broker queues if recipient offline. |
| `list_peers` | List connected peers in the mesh with `presenceId`, `displayName`, `status`, `summary`, `groups`, `roleTag`. |
| `message_status` | Query delivery state of a sent message by `messageId`. |
| `check_messages` | Drain pending inbox messages (push mode). |

### 2.2 Profile + identity (4)

| Tool | v1 behavior |
|---|---|
| `set_summary` | Set the current peer's work summary (visible to others). |
| `set_status` | Set status: `idle`, `working`, `dnd`. Priority-ranked by source (`hook` > `manual` > `jsonl`). |
| `set_visible` | Toggle visibility. Hidden peers skip `list_peers` and broadcasts but still receive direct messages. |
| `set_profile` | Update display name, role tag, groups, avatar, title, bio, capabilities. |

### 2.3 Groups (2)

| Tool | v1 behavior |
|---|---|
| `join_group` | Join a `@group` with optional role (`lead`, `member`, or free-form). |
| `leave_group` | Leave a `@group`. |

### 2.4 State KV (3)

| Tool | v1 behavior |
|---|---|
| `set_state` | Set a key-value pair in the mesh's shared state. Broadcasts `state_change` push to all peers. |
| `get_state` | Read a value by key. |
| `list_state` | List all state keys with values, authors, timestamps. |

### 2.5 Memory (3)

| Tool | v1 behavior |
|---|---|
| `remember` | Store a text memory with optional tags. Persists across sessions. |
| `recall` | Full-text search memories by query, ranked results. |
| `forget` | Delete a memory by ID. |

### 2.6 Files (8)

| Tool | v1 behavior |
|---|---|
| `share_file` | Upload a file to MinIO. Supports `to: <peer>` for E2E encryption (symmetric key wrapped with peer pubkey), or mesh-wide sharing. Supports `persistent` vs `ephemeral` storage. |
| `get_file` | Download a file by `fileId`. Returns a presigned MinIO URL. |
| `list_files` | List files in the mesh by `scope`, `tags`, author. |
| `file_status` | Query status of a file: who downloaded, when. |
| `delete_file` | Delete a file (owner only). |
| `grant_file_access` | Add another peer as a recipient of an already-encrypted file (re-wraps symmetric key). |
| `read_peer_file` | Read a file from another peer's working directory (requires peer online + sharing). |
| `list_peer_files` | List files in a peer's shared directory (tree of names, not contents). |

### 2.7 Vectors (Qdrant) (4)

| Tool | v1 behavior |
|---|---|
| `vector_store` | Store embedding with metadata in a named collection. |
| `vector_search` | Nearest-neighbor search in a collection with `limit`. |
| `vector_delete` | Delete a vector by ID. |
| `list_collections` | List collections in the mesh's Qdrant namespace. |

### 2.8 Graph (Neo4j) (2)

| Tool | v1 behavior |
|---|---|
| `graph_query` | Read-only Cypher MATCH query on the per-mesh Neo4j database. |
| `graph_execute` | Write Cypher (CREATE/MERGE/DELETE). |

### 2.9 Shared SQL (Postgres) (3)

| Tool | v1 behavior |
|---|---|
| `mesh_query` | SELECT-only query on the per-mesh Postgres schema. |
| `mesh_execute` | DDL + DML (CREATE TABLE, INSERT, UPDATE, DELETE). |
| `mesh_schema` | List tables + columns in the mesh's schema. |

### 2.10 Streams (4)

| Tool | v1 behavior |
|---|---|
| `create_stream` | Create a named stream for live data pub-sub. |
| `publish` | Push data to a stream. Subscribers receive in real-time. |
| `subscribe` | Subscribe to a stream. Events arrive as channel notifications. |
| `list_streams` | List active streams. |

### 2.11 Contexts (3)

| Tool | v1 behavior |
|---|---|
| `share_context` | Share session understanding with the mesh (summary + files_read + key_findings + tags). |
| `get_context` | Search contexts by query (file path, topic, etc.). |
| `list_contexts` | Show what peers currently know about the codebase. |

### 2.12 Tasks (4)

| Tool | v1 behavior |
|---|---|
| `create_task` | Create a work item (title, assignee, priority, tags). |
| `claim_task` | Claim an unclaimed task. |
| `complete_task` | Mark done with optional result summary. |
| `list_tasks` | Filter by status and/or assignee. |

### 2.13 Scheduling (3)

| Tool | v1 behavior |
|---|---|
| `schedule_reminder` | One-shot (`deliver_at`, `in_seconds`) or recurring (`cron`). Delivered to self or `to`. Persists across broker restarts. |
| `list_scheduled` | List pending scheduled messages. |
| `cancel_scheduled` | Cancel by ID. |

### 2.14 Mesh metadata — read (4)

| Tool | v1 behavior |
|---|---|
| `mesh_info` | Overview: peers, groups, state, memory, files, tasks, streams, tables. |
| `mesh_stats` | Resource usage per peer: messages in/out, tool calls, uptime, errors. |
| `mesh_clock` | Simulation clock status: speed, tick count, simulated time. |
| `ping_mesh` | Test messages through the full pipeline, measure round-trip per priority. Diagnoses push delivery issues. |

### 2.15 Mesh clock — write (3)

| Tool | v1 behavior |
|---|---|
| `mesh_set_clock` | Set simulation clock speed (1–100x). Peers receive heartbeat ticks at the simulated rate. |
| `mesh_pause_clock` | Pause simulation clock. |
| `mesh_resume_clock` | Resume paused clock. |

### 2.16 Skills (5)

| Tool | v1 behavior |
|---|---|
| `share_skill` | Publish a reusable skill (name + description + instructions + tags + when_to_use + allowed_tools + model + context + agent + user_invocable + argument_hint). Exposed as MCP prompts and `skill://` resources. |
| `get_skill` | Load a skill's full instructions by name. |
| `list_skills` | Browse available skills, optionally filter by keyword. |
| `remove_skill` | Remove a shared skill. |
| `mesh_skill_deploy` | Deploy a multi-file skill bundle from zip or git repo. |

### 2.17 MCP registry tier 1 — peer-hosted (4)

| Tool | v1 behavior |
|---|---|
| `mesh_mcp_register` | Register a peer's local MCP server with the mesh (server_name, description, tools schema, persistent flag). Other peers can invoke via `mesh_tool_call`. |
| `mesh_mcp_list` | List MCP servers in the mesh with their tools + hosting peer. |
| `mesh_tool_call` | Call a tool on a mesh-registered MCP server. Routes: caller → broker → hosting peer → execute → result back. 30s timeout. |
| `mesh_mcp_remove` | Unregister a peer-hosted MCP server. |

### 2.18 MCP registry tier 2 — broker-deployed (7)

| Tool | v1 behavior |
|---|---|
| `mesh_mcp_deploy` | Deploy an MCP server from zip (via `file_id`), git URL, or npx package. Runs on broker VPS in Docker sandbox. Scope: `peer` (default), `mesh`, or `{group/groups/role/peers}`. Runtime: node / python / bun. Memory, network_allow, env with `$vault:` references. |
| `mesh_mcp_undeploy` | Stop and remove a managed MCP server. |
| `mesh_mcp_update` | Pull latest + restart a git-sourced server. |
| `mesh_mcp_logs` | Tail recent logs from a managed server. |
| `mesh_mcp_scope` | Get or set visibility scope. |
| `mesh_mcp_schema` | Inspect tool schemas for a deployed server. |
| `mesh_mcp_catalog` | List all deployed services with status, scope, tool count. |

### 2.19 Vault (3)

| Tool | v1 behavior |
|---|---|
| `vault_set` | Store encrypted credential. `type: env` (string, injected as env var via `$vault:<key>`) or `type: file` (file written to `mount_path` in container). |
| `vault_list` | List vault entries (keys + metadata only, no values). |
| `vault_delete` | Remove a credential. |

### 2.20 URL watch (3)

| Tool | v1 behavior |
|---|---|
| `mesh_watch` | Watch a URL for changes. Modes: `hash` (SHA-256 body), `json` (jsonpath extract), `status` (HTTP code). Polling `interval` (min 5s). `notify_on: change \| match:<val> \| not_match:<val>`. Custom headers. |
| `mesh_unwatch` | Stop watching by `watch_id`. |
| `mesh_watches` | List active watches. |

### 2.21 Webhooks (3)

| Tool | v1 behavior |
|---|---|
| `create_webhook` | Create an inbound webhook. Returns a URL external services (GitHub, CI/CD, monitoring) can POST to. Payload becomes a mesh message to all peers. |
| `list_webhooks` | List active webhooks. |
| `delete_webhook` | Deactivate by name. |

---

## 3. Broker WS protocol

`apps/broker/src/index.ts` dispatches 85 message types over a single WebSocket endpoint (`WS_PATH`). Each WS message is a client-initiated RPC; most of the 79 MCP tools above map 1:1 to a WS message. Some additional WS messages exist for connection lifecycle + internal routing.

### 3.1 Connection lifecycle (3)

- `hello` — client authentication. Ed25519 signature over `{meshId, memberId, pubkey, timestamp}`. Broker verifies, creates presence row, replies with `hello_ack`.
- `hello_ack` — server → client, confirms authentication + sends restored peer state.
- `get_clock` — get current simulation clock state.

### 3.2 Messaging (4 WS ops)

- `send` — send a message. Envelope contains sender, recipient (peer/group/*), priority, nonce, ciphertext.
- `peer_dir_request` / `peer_dir_response` — peer-to-peer directory request (read_peer_file under the hood).
- `peer_file_request` / `peer_file_response` — peer-to-peer file read.

### 3.3 Profile + presence (5)

- `set_status`, `set_summary`, `set_visible`, `set_profile`, `set_stats`

### 3.4 Groups (2)

- `join_group`, `leave_group`

### 3.5 State KV (3)

- `set_state`, `get_state`, `list_state`

### 3.6 Memory (3)

- `remember`, `recall`, `forget`

### 3.7 Files (5)

- `get_file`, `list_files`, `file_status`, `grant_file_access`, `delete_file`

### 3.8 Vectors (3)

- `vector_store`, `vector_search`, `vector_delete`, `list_collections`

### 3.9 Graph (2)

- `graph_query`, `graph_execute`

### 3.10 Shared SQL (3)

- `mesh_query`, `mesh_execute`, `mesh_schema`

### 3.11 Streams (4)

- `create_stream`, `publish`, `subscribe`, `unsubscribe`, `list_streams`

### 3.12 Contexts (3)

- `share_context`, `get_context`, `list_contexts`

### 3.13 Tasks (4)

- `create_task`, `claim_task`, `complete_task`, `list_tasks`

### 3.14 Scheduling (3)

- `schedule`, `list_scheduled`, `cancel_scheduled`

### 3.15 Mesh metadata (3)

- `mesh_info`, `peers_list` (from `list_peers`), `message_status`

### 3.16 Simulation clock (4)

- `set_clock`, `pause_clock`, `resume_clock`, `get_clock`

### 3.17 Skills (4)

- `share_skill`, `get_skill`, `list_skills`, `remove_skill`, `skill_deploy`

### 3.18 MCP registry (11)

- `mcp_register`, `mcp_unregister`, `mcp_list`, `mcp_call`, `mcp_call_response` (peer → peer relay)
- `mcp_deploy`, `mcp_undeploy`, `mcp_update`, `mcp_logs`, `mcp_scope`, `mcp_schema`, `mcp_catalog`

### 3.19 Vault (4)

- `vault_set`, `vault_get`, `vault_list`, `vault_delete`

### 3.20 URL watch (3)

- `watch`, `unwatch`, `watch_list`

### 3.21 Webhooks (3)

- `create_webhook`, `list_webhooks`, `delete_webhook`

### 3.22 Audit (2)

- `audit_query`, `audit_verify`

---

## 4. Broker HTTP endpoints

The broker serves both WS (`/ws`) and HTTP on the same port. HTTP endpoints are listed here by (method, path) with purpose.

| Method | Path | Purpose |
|---|---|---|
| `GET` | `/health` | Health check: liveness probe |
| `GET` | `/metrics` | Prometheus metrics endpoint |
| `POST` | `/hook/set-status` | Receive hook status updates from CLI `hook` command (Claude Code session lifecycle) |
| `POST` | `/join` | Accept v1 invite join (legacy) |
| `POST` | `/invites/:code/claim` | v2 invite claim (public, unauthenticated) |
| `POST` | `/upload` | Upload a file (returns fileId, used by `share_file`) |
| `GET` | `/download/:id` | Download a file (returns content or presigned URL) |
| `POST` | `/cli-sync` | CLI sync endpoint — fetches user's meshes from `claudemesh.com` dashboard via JWT, returns mesh list |
| `POST` | `/tg/token` | Register a Telegram bot token for a mesh (connects via `connect telegram` CLI command) |
| `PATCH` | `/mesh/:id/member/:memberId` | Update a member's profile (admin or self) |
| `GET` | `/mesh/:id/members` | List mesh members |
| `PATCH` | `/mesh/:id/settings` | Update mesh-level settings (owner/admin) |
| `POST` | `/hook/:meshId/:webhookId` | Inbound webhook — external systems POST here to publish a mesh message |
| `GET` | `/test/clock` | Dev-only: simulation clock state |
| `GET` | `/test/flip` | Dev-only: test flip endpoint |
| `GET` | `/test/html` | Dev-only: test HTML endpoint |
| `WS` | `/ws` | WebSocket connection for mesh peers (all WS ops above) |

---

## 5. Database schema — `mesh` Postgres schema

23 tables in the `mesh` schema (managed via Drizzle). Defined in `packages/db/src/schema/mesh.ts`.

| Table | Purpose |
|---|---|
| `mesh.mesh` | Mesh identity. slug, name, ownerId, createdAt, settings. |
| `mesh.member` | Per-mesh member record. Stable, durable. pubkey, displayName, role, groups, joinedAt. |
| `mesh.invite` | Invite codes + metadata. |
| `mesh.pending_invite` | v2 invite handshake state (pending claim). |
| `mesh.audit_log` | Audit events per mesh. |
| `mesh.presence` | Ephemeral WS session — one row per active connection. Status, statusSource, statusUpdatedAt. |
| `mesh.message_queue` | Queued messages pending push delivery (priority ordered). |
| `mesh.pending_status` | In-flight status updates (10s TTL). |
| `mesh.state` (meshState) | Shared KV state per mesh. |
| `mesh.memory` (meshMemory) | Shared memories with full-text search. |
| `mesh.file` (meshFile) | File metadata (uploader, size, sha256, persistence, storage location). |
| `mesh.file_access` (meshFileAccess) | Per-recipient ACL on files. |
| `mesh.file_key` (meshFileKey) | Per-recipient wrapped symmetric keys for E2E encryption. |
| `mesh.context` (meshContext) | Shared context entries. |
| `mesh.task` (meshTask) | Tasks with lifecycle (open, claimed, completed, cancelled). |
| `mesh.stream` (meshStream) | Stream metadata. |
| `mesh.skill` (meshSkill) | Skill registrations (name, content, frontmatter, tags). |
| `mesh.webhook` (meshWebhook) | Inbound webhook registrations. |
| `mesh.service` (meshService) | Deployed MCP server state (container ID, scope, env, runtime, memory, logs). |
| `mesh.vault_entry` (meshVaultEntry) | Encrypted vault entries per (mesh, peer, key). |
| `mesh.scheduled_message` | Scheduled / recurring reminders (cron + one-shot). |
| `mesh.peer_state` | Per-peer state (groups, role, profile, message mode preference). |
| `mesh.telegram_bridge` | Telegram bot registration per mesh. |

---

## 6. Broker backend services

Five external services the broker manages at runtime. All currently work in v1 and ship in the default Docker Compose deployment.

| Service | Purpose | File | Per-mesh model |
|---|---|---|---|
| **Postgres** (Drizzle) | Primary data store for mesh schema. Also used for `mesh_execute` / `mesh_query` / `mesh_schema` shared-SQL tools via per-mesh schemas. | `db.ts` | Schema-per-mesh for shared SQL tools |
| **Neo4j** | Graph queries (`graph_query`, `graph_execute`). | `neo4j-client.ts` | Database-per-mesh (Enterprise) or labeled-node fallback (Community) |
| **Qdrant** | Vector embeddings + nearest-neighbor search. | `qdrant.ts` | Collection naming: `mesh_<meshId>_<collection>`, 1536-dim default, cosine distance |
| **MinIO** | File storage for `share_file` / `get_file`. | `minio.ts` | Bucket-per-mesh: `mesh-<meshId>`. Persistent + ephemeral key paths. |
| **Docker** | Runs deployed MCP servers in sandboxed containers. | `index.ts` (deploy handler) | Container-per-deployment. Read-only root, dropped caps, memory limits, network_allow. |

---

## 7. Broker core subsystems

### 7.1 Status engine (`broker.ts`, 2066 lines)

**Battle-tested status model** ported from `claude-intercom`. Rules:

- Status sources are ranked: `hook` (3) > `manual` (2) > `jsonl` (1)
- On status update:
  - If status **changed** → bump everything, record new source
  - If status **unchanged**, incoming source ≥ recorded → upgrade
  - If status **unchanged**, incoming source < recorded:
    - Recorded source still fresh → keep it (bump timestamp only)
    - Recorded source stale → downgrade to honest attribution
- `HOOK_FRESHNESS_MS` window (default 60s) for "fresh" classification
- `WORKING_TTL_MS` after which `working` status reverts to `idle`
- `PENDING_TTL_MS = 10_000` for pending status cleanup
- `TTL_SWEEP_INTERVAL_MS = 15_000` for periodic cleanup

**Must preserve** — this is the correctness engine for `set_status`, `list_peers`, and Claude Code's status line.

### 7.2 Message queue + priority delivery

- Messages are stored in `mesh.message_queue` with priority (`now`, `next`, `low`)
- `now` messages bypass busy-gate and are pushed immediately
- `next` messages wait for idle peer
- `low` messages are pull-only (delivered when peer explicitly drains via `check_messages`)
- Queue is drained via `drainForMember(meshId, memberId)` on WS message arrival or manual `check_messages`
- Duplicate delivery prevention via `messageId` UUID tracking

### 7.3 Scheduled message delivery (`index.ts` in-memory + DB persistence)

- One-shot: `deliver_at` (timestamp) or `in_seconds`
- Recurring: standard 5-field cron expression
- Persists to `mesh.scheduled_message` table — survives broker restart
- On broker start, pending schedules are re-registered
- Delivery is via the normal `send_message` pipeline with `subtype: reminder`

### 7.4 URL watch subsystem (`index.ts`)

- Poller runs in-process (worker per watch)
- Modes: `hash` (SHA-256 of body), `json` (extract jsonpath value), `status` (HTTP status)
- `notify_on: change | match:<val> | not_match:<val>`
- Persists to DB so watches survive broker restart
- Min interval 5s, max 24h

### 7.5 Telegram bridge (`telegram-bridge.ts`, 1711 lines)

**Substantial subsystem.** Provides Telegram Bot API integration:

- Bot token registration per mesh via `POST /tg/token`
- Long-polling or webhook mode
- `tg:<username>` peer identity registration in the mesh's member table
- Inbound Telegram messages → mesh `send_message` events with `subtype: telegram`
- Outbound `send_message(to: "tg:<name>")` → Telegram Bot API call
- Chat-to-mesh mapping (Telegram chat_id ↔ mesh peer)
- User discovery (`connectChat`)
- Bridge row persistence in `mesh.telegram_bridge`

**This is ~18% of the broker's total source**. v2 must either:
1. Port the logic into a standalone MCP connector (`apps/mcp-telegram/`), or
2. Keep this file in the broker and wire it into the v2 architecture unchanged (my recommendation per the previous conversation — bundled into the broker image)

Either way, **every behavior documented here must still work after v2 lands**.

### 7.6 Auth + crypto (`crypto.ts`, `broker-crypto.ts`, `jwt.ts`)

- **Hello signatures**: Ed25519 signed tuple of `(meshId, memberId, pubkey, timestamp)`. Verified on every WS connection. Replay protection via timestamp window.
- **Invite verification**: canonical invite payload (`canonicalInvite`) signed by mesh owner, Ed25519 verified on claim
- **JWT**: for `/cli-sync` endpoint — the CLI obtains a JWT from `claudemesh.com` via browser flow, passes it to the broker, broker verifies and returns the user's mesh list
- **File envelopes**: client-side AES-GCM + per-recipient key wrapping (file_key table)

### 7.7 Rate limiting (`rate-limit.ts`)

- Per-peer rate limits on expensive operations
- Currently in-process (not Redis-backed)
- Enforces limits on `send`, `vector_store`, `mesh_execute`, `mesh_mcp_deploy`, etc.

### 7.8 Metrics (`metrics.ts`)

Prometheus metrics exposed at `/metrics`:
- Request counts by op type
- Latencies p50/p99
- Connection counts per mesh
- Message delivery counts by priority
- Error rates

### 7.9 Audit log (`audit.ts`)

- Every mutation is audited to `mesh.audit_log`
- Tamper-evidence via hash chaining
- Accessible via `audit_query` and `audit_verify` WS ops

### 7.10 Member API (`member-api.ts`, 284 lines)

Exports:
- `updateMemberProfile()` — used by `PATCH /mesh/:id/member/:memberId`
- `listMeshMembers()` — used by `GET /mesh/:id/members`
- `updateMeshSettings()` — used by `PATCH /mesh/:id/settings`

### 7.11 CLI sync (`cli-sync.ts`, 133 lines)

Exports `handleCliSync()` for `POST /cli-sync`. This is **already the "CLI sync meshes from dashboard" feature** — v2 will reuse this endpoint for its mesh-list refresh logic.

### 7.12 Webhook subsystem (`webhooks.ts`, 97 lines)

Handles `POST /hook/:meshId/:webhookId` inbound. Signature verification (HMAC), payload normalization, mesh message emission.

---

## 8. CLI core subsystems

### 8.1 WS client (`ws/client.ts`, 2191 lines)

**The biggest CLI file.** Implements the full WS protocol with:
- Connection management, reconnect with exponential backoff
- Message queue for offline buffering
- Request/response correlation via `_reqId`
- Ed25519 hello signature generation
- Crypto envelope wrapping for `send_message` payloads
- Push notification delivery (messages, state changes, system events)
- Per-mesh connection pooling (one WS per mesh)

### 8.2 MCP server (`mcp/server.ts`, 2139 lines)

Second biggest CLI file. Implements:
- MCP stdio transport (registered with Claude Code via `install.ts`)
- Tool registry from `mcp/tools.ts`
- Dispatch to 79 handlers (one per tool)
- WS client pooling (one connection per mesh)
- Crypto primitives for memory/state encryption
- Inline file-read helpers for `read_peer_file`
- Channel notification forwarding from broker → Claude Code via MCP elicitation

### 8.3 Crypto (`crypto/*.ts`)

- `keypair.ts` — Ed25519 keypair generation + persistence (`~/.claudemesh/keys/<mesh>.key`)
- `envelope.ts` — NaCl `crypto_box` envelope wrapping
- `file-crypto.ts` — AES-GCM file encryption + per-recipient key wrapping
- `hello-sig.ts` — Hello signature generation/verification

### 8.4 Auth + invite (`auth/*.ts`, `invite/*.ts`, `lib/invite-v2.ts`)

- `callback-listener.ts` — local HTTP server that catches browser OAuth callback (for `sync` command)
- `open-browser.ts` — cross-platform browser launcher
- `pairing-code.ts` — pairing code display
- `sync-with-broker.ts` — JWT-based sync from dashboard
- `invite/parse.ts` — parse v1 invite URLs
- `invite/enroll.ts` — enroll into a mesh from an invite
- `lib/invite-v2.ts` — v2 invite format (short-code + signed payload)

### 8.5 State + config (`state/config.ts`)

- `~/.claudemesh/config.json` read/write (mesh list, keypairs, profile defaults)
- 0600 permission enforcement
- Schema validation

### 8.6 TUI primitives (`tui/*.ts`)

- `colors.ts` — hard-coded ANSI colors
- `index.ts` — input helpers
- `screen.ts` — raw-mode screen control
- `spinner.ts` — simple spinner

### 8.7 Templates (`templates/index.ts`)

- `dev-team`, `research`, `ops-incident`, `simulation`, `personal`
- Each template seeds initial state + preset groups

### 8.8 Tests

- `__tests__/crypto-roundtrip.test.ts` — crypto round-trip verification
- `__tests__/invite-parse.test.ts` — invite URL parsing
- No integration tests against a real broker

---

## 9. Infrastructure + deployment

### 9.1 Broker runtime (`env.ts`)

Environment variables the broker expects:
- `DATABASE_URL` — Postgres connection
- `NEO4J_URL`, `NEO4J_USER`, `NEO4J_PASSWORD`
- `QDRANT_URL`
- `MINIO_ENDPOINT`, `MINIO_ACCESS_KEY`, `MINIO_SECRET_KEY`, `MINIO_USE_SSL`
- `STATUS_TTL_SECONDS` — working status timeout
- `HOOK_FRESH_WINDOW_SECONDS` — hook source freshness window
- `TELEGRAM_BOT_TOKEN` — for bridge
- `DASHBOARD_JWT_SECRET` — for `/cli-sync` verification
- `PORT` (default 8787)
- Various feature flags

### 9.2 CLI runtime

- Node >= 20 required (checked in `doctor`)
- `claude` binary must be on PATH
- `~/.claudemesh/` directory with config + keys
- `~/.claude.json` MCP server registration
- `~/.claude/settings.json` status hooks registration

### 9.3 Deployment (Coolify/Docker Compose)

- Broker deployed via Coolify + Gitea CI on OVHcloud VPS (`ic.claudemesh.com`)
- WS endpoint: `wss://ic.claudemesh.com/ws`
- HTTP endpoint: `https://ic.claudemesh.com`
- Postgres, Neo4j, Qdrant, MinIO run as siblings in Docker Compose
- Deployed MCP sandboxes use the host Docker daemon via socket mount

---

## 10. Features not in the tool/WS surface (behavioral)

These are v1 behaviors that exist but aren't enumerated as tools. Each must still work after v2.

| Feature | Location | Notes |
|---|---|---|
| Flag-first `claudemesh --resume xxx` routing | `cli/src/index.ts` §339 | Rewrites argv to `launch --resume xxx` |
| Bare `claudemesh` → welcome wizard | `cli/src/index.ts` §334 | Runs `runWelcome()` |
| Status hook auto-registration | `commands/install.ts` | Writes to `~/.claude/settings.json` |
| Claude Code session hook handling | `commands/hook.ts` | Receives stdin JSON, posts to `/hook/set-status` |
| Per-mesh keypair directory | `crypto/keypair.ts` | `~/.claudemesh/keys/<mesh>.key` with 0600 perms |
| E2E file encryption with re-wrapping | `crypto/file-crypto.ts` + `mesh_file_key` table | `grant_file_access` re-wraps symmetric key for new recipient |
| Priority message delivery | `broker.ts` | `now` bypasses busy-gate, `next` waits for idle, `low` is pull-only |
| Hook > manual > jsonl status priority | `broker.ts` | Documented in §7.1 |
| Simulation clock for test time | `index.ts` (broker) | Peers receive heartbeat ticks at simulated rate |
| Audit log hash chaining | `audit.ts` | Tamper-evident — tools call `audit_verify` to check |
| Dashboard-CLI sync | `auth/sync-with-broker.ts` + `cli-sync.ts` | Browser JWT flow, fetches mesh list from dashboard |
| Telegram chat ↔ mesh peer mapping | `telegram-bridge.ts` | Bidirectional routing via `tg:<username>` |
| Inbound webhook payload normalization | `webhooks.ts` | External systems POST, becomes a mesh message |
| Rate limiting per peer per operation | `rate-limit.ts` | In-memory token buckets |
| Prometheus metrics | `metrics.ts` | `/metrics` endpoint |

---

## 11. Test coverage (v1)

| Test | File | Notes |
|---|---|---|
| Crypto round-trip | `apps/cli/src/__tests__/crypto-roundtrip.test.ts` | Encrypt → decrypt verification |
| Invite URL parsing | `apps/cli/src/__tests__/invite-parse.test.ts` | v1 and v2 formats |
| Broker tests | `apps/broker/tests/*.test.ts` | broker.test.ts, invite-signature.test.ts, invite-v2.test.ts, hello-signature.test.ts, rate-limit.test.ts, encoding.test.ts, dup-delivery.test.ts, metrics.test.ts, logging.test.ts, integration/health.test.ts |

**v1 test coverage is minimal for the CLI side.** 2 unit test files for 12k LOC.

Broker has ~10 test files. They cover crypto primitives, invite flow, hello signatures, rate limiting, metrics — but **not** the 85 WS message handlers comprehensively.

---

## 12. The "must preserve" list (high-priority regression checks)

If v2 breaks any of these, it's a user-facing regression:

### 12.1 First-run experience
- [ ] `claudemesh` bare command → welcome wizard
- [ ] `claudemesh install` registers MCP server + status hooks in Claude Code config
- [ ] `claudemesh join <url>` enrolls into a mesh from a v1 OR v2 invite URL
- [ ] `claudemesh launch` starts Claude Code with mesh connectivity

### 12.2 Session lifecycle
- [ ] Status hooks fire correctly on Claude Code session start/stop/pause
- [ ] `set_status` honors priority (hook > manual > jsonl)
- [ ] `list_peers` shows live status with freshness gating
- [ ] Status TTL sweeper runs every 15s

### 12.3 Messaging
- [ ] `send_message(to: peer, priority: "now")` delivers immediately
- [ ] `send_message(to: peer, priority: "next")` waits for idle
- [ ] `send_message(to: "@group")` broadcasts to group members
- [ ] `send_message(to: "*")` broadcasts to all mesh peers
- [ ] Offline recipients receive queued messages on reconnect
- [ ] Duplicate delivery is prevented by `messageId` tracking

### 12.4 Cryptographic integrity
- [ ] Ed25519 keypair generation + persistence with 0600 perms
- [ ] Hello signature verification rejects replay within timestamp window
- [ ] `send_message` envelopes are E2E encrypted (NaCl crypto_box)
- [ ] File uploads are AES-GCM encrypted with per-recipient key wrapping
- [ ] `grant_file_access` re-wraps symmetric key for a new recipient

### 12.5 All 79 MCP tools
- [ ] Every tool in §2 dispatches correctly through the CLI's MCP server
- [ ] Every tool delegates to the broker WS protocol or local handler as appropriate
- [ ] No tool returns "not implemented" or throws an unexpected error

### 12.6 Broker backends
- [ ] `mesh_query` / `mesh_execute` / `mesh_schema` work against per-mesh Postgres schema
- [ ] `graph_query` / `graph_execute` work against per-mesh Neo4j database
- [ ] `vector_store` / `vector_search` work against per-mesh Qdrant collection
- [ ] `share_file` / `get_file` work through per-mesh MinIO bucket
- [ ] `mesh_mcp_deploy` spawns a Docker container with correct scope + env + network_allow
- [ ] `vault_set` + `$vault:<key>` env injection works end-to-end for deployed MCPs

### 12.7 Scheduled + URL watch
- [ ] `schedule_reminder` with `cron` survives broker restart (persisted in DB)
- [ ] `mesh_watch` polls at the specified interval and notifies on change
- [ ] Watch state persists across broker restart

### 12.8 Telegram bridge
- [ ] `connect telegram` registers bot token via `POST /tg/token`
- [ ] Bot token is stored in `mesh.telegram_bridge`
- [ ] Inbound Telegram messages are routed as mesh messages
- [ ] `send_message(to: "tg:<username>")` routes via Telegram Bot API
- [ ] `disconnect telegram` tears down the bridge cleanly

### 12.9 Dashboard sync
- [ ] `claudemesh sync` browser flow completes and fetches mesh list
- [ ] `POST /cli-sync` with valid JWT returns user's dashboard meshes

### 12.10 Webhooks
- [ ] `create_webhook` returns a POST URL
- [ ] External POST to webhook URL becomes a mesh message
- [ ] HMAC signature validation rejects unsigned requests
- [ ] `list_webhooks` + `delete_webhook` work

### 12.11 Doctor checks
- [ ] Node >= 20 check
- [ ] `claude` binary on PATH
- [ ] MCP server registered in `~/.claude.json`
- [ ] Status hooks registered in `~/.claude/settings.json`
- [ ] `~/.claudemesh/config.json` exists + parses + 0600 perms
- [ ] Mesh keypairs valid

---

## 13. What v2 is adding (net new)

Not part of the regression list, but tracked here so we don't lose sight of the forward-looking scope.

### 13.1 New CLI features (from user's stated v2 intent)

- [ ] `claudemesh login` — device-code OAuth against claudemesh.com's Better Auth backend
- [ ] `claudemesh register` — create a new account from the CLI (via browser handoff)
- [ ] `claudemesh new` — create a mesh from the CLI against `POST /api/my/meshes` (not via templates in the CLI — via dashboard API)
- [ ] `claudemesh invite` — generate an invite from the CLI via `POST /api/my/meshes/:slug/invites`
- [ ] `claudemesh whoami` — show current identity + token source
- [ ] `claudemesh logout` — revoke server-side session + clear local credentials

### 13.2 Architecture improvements (from user's v2 intent)

- [ ] Feature-folder `services/` layer with strict facade boundaries
- [ ] ESLint + dependency-cruiser boundary enforcement
- [ ] `cli/` vs `ui/` separation (non-Ink I/O vs Ink rendering)
- [ ] `entrypoints/` folder with cli + mcp entries
- [ ] Typed error classes per service with `toDomainError` helper
- [ ] Coverage threshold enforcement in CI

### 13.3 Not in v1.0.0 scope (defer to v1.1+)

Everything from the Composer 2 review rounds that isn't Pass 1:

- Local-first SQLite source of truth (Lamport, sync daemon, publish transaction)
- Broker security hardening (role-per-mesh Postgres, Docker egress proxy, SSRF policy)
- ICU MessageFormat + per-locale budgets
- Accessibility token-signal matrix
- Tiered MCP catalog + audit process
- session_kind enum
- NFC peer_id normalization
- Write queue state machine

These stay in the `.artifacts/specs/` as reference documents. They describe a good destination. They are NOT v1.0.0 requirements.

---

## 14. Known v1 technical debt / gaps (worth noting)

These aren't features — they're places where v1 is weaker than it could be. Document here so v2 doesn't blindly port the weaknesses.

- **CLI auth is missing** — v1 has no `login` / `logout` command. All account-level operations require the web dashboard. This is what v2 is adding.
- **Imperative command branching** — `commands/launch.ts` is 775 lines with nested flag handling. Cleaner in v2's flow pipeline.
- **Minimal CLI test coverage** — 2 test files for 12k LOC. v2 should have colocated tests per service.
- **Rate limiting is in-memory only** — doesn't survive broker restart; not Redis-backed.
- **No CLI-side caching** — every `list_peers` / `mesh_info` call hits the broker. v2's local-first layer (Pass 2) addresses this.
- **Telegram bridge is a large monolithic file** (1711 lines) — legitimate complexity, but v2 may want to modularize if it touches it.
- **v1 wizard bleed-through** — `launch` → `claude` handoff leaves ANSI state dirty. v2's `resetTerminal()` choke point fixes this.

None of these are regressions if v2 keeps them as-is. v2 should **not** prioritize fixing them — fix them when they become a problem, not speculatively.

---

## 15. Reading this inventory

**If you're implementing v2 Phase 1** (foundation layers): every tool in §2, every WS op in §3, every HTTP endpoint in §4, every DB table in §5 must have a place in the v2 folder structure. No new semantics, no improved algorithms — just move the working code.

**If you're reviewing a v2 PR**: check it against §12 ("must preserve" list). If the PR changes the behavior of anything in that list, it's a regression and needs explicit sign-off.

**If you're writing v2 docs**: reference this document. Every feature here is user-visible and documented in v1's README / slash-command help / tool descriptions. v2 docs should mention every feature from §2 as preserved.

---

**End of inventory.**