feat(cli): bump to alpha.30 + channel message polish

Channel messages now render as '<sender>: <body>' with priority + broadcast badges in Claude Code's <channel> reminders, so the inbox reads as a chat thread rather than bare lines. [URGENT] alice: deploy is blocking release bob (broadcast): team sync 15min charlie: pr #42 lgtm Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
fix(ci): skip smoke tests for cross-compiled binaries
2026-04-15 02:54:53 +01:00 · 2026-04-15 02:51:25 +01:00 · 2026-04-15 02:47:52 +01:00 · 2026-04-15 02:45:44 +01:00 · 2026-04-15 02:43:50 +01:00 · 2026-04-15 02:42:16 +01:00
459 changed files with 91041 additions and 2667 deletions
--- a/.artifacts/specs/2026-04-10-anthropic-vision-meshes-invites.md
+++ b/.artifacts/specs/2026-04-10-anthropic-vision-meshes-invites.md
@@ -0,0 +1,232 @@
+# Anthropic Vision: Meshes & Invitations
+
+**Status:** in progress · partial implementation 2026-04-10
+**Owner:** agutierrez
+**Scope:** `apps/web`, `packages/api`, `packages/db`, `apps/broker` (future), `apps/cli` (future)
+
+---
+
+## Guiding principles
+
+1. **Identity is opaque, display is free-form.** Humans pick any name; the system uses random IDs.
+2. **Secrets never appear in URLs.** Links are capabilities, not credentials.
+3. **Defaults are obvious; advanced options are discoverable but hidden.**
+4. **Self-service wherever possible; admins don't become gatekeepers.**
+5. **Every visible action is also an auditable event.**
+
+These mirror how Anthropic builds its own org/workspace/project model.
+
+---
+
+## Part 1 — Meshes
+
+### Problem
+Global uniqueness on `mesh.slug` creates name collisions at scale. Two users picking "platform" or "test" fight for the slug. At 50k users this is the default state.
+
+### Decision
+**Drop the slug as an identity concept.** `mesh.id` (opaque, already random) is the canonical identifier everywhere (URLs, invites, broker lookups). `mesh.name` is a free-form display label, non-unique. `mesh.slug` is kept as a non-unique cosmetic string derived from the name at creation time, embedded in invite payloads for debugging.
+
+### What this enables
+- Two users can both name their mesh "platform-team" with zero friction
+- URLs stay stable (`/meshes/{id}`) even if the user renames the mesh
+- No "slug taken" error state exists in the product anymore
+
+### Tradeoff explicitly accepted
+Users lose the ability to type `claudemesh join platform-team` — but they never did, because the CLI takes signed invite tokens, not slugs. This capability was phantom.
+
+### Implementation — DONE in this spec
+- [x] Drop `UNIQUE` constraint on `mesh.slug` (migration `0017_mesh-slug-non-unique.sql`)
+- [x] Remove `slug` field from `createMyMeshInputSchema`
+- [x] Remove slug field from `CreateMeshForm`
+- [x] Server-side `toSlug(name)` derives slug from name automatically
+- [x] Schema comment documents the non-canonical role of `slug`
+
+### Future (optional, not in v0.1.x)
+- **Vanity slugs as a Pro feature:** one globally-unique handle per *account* (not per mesh), exposed as `claudemesh.com/@acme/...`. Sold as part of an org tier. This is where slug uniqueness actually pays for itself — against usernames, not against meshes.
+
+---
+
+## Part 2 — Invitations
+
+### Problems with the current invite system
+
+| # | Problem | Severity |
+|---|---|---|
+| 1 | `mesh_root_key` is embedded in the invite URL as base64url JSON | 🔴 **Security** |
+| 2 | Invite URLs are ~400 chars of opaque base64url | 🟡 UX |
+| 3 | No invite-by-email; only shareable link | 🟡 UX |
+| 4 | Required form fields (role, maxUses, expiresInDays) for every invite | 🟡 UX |
+| 5 | Landing page does not clearly preview role/consent | 🟡 UX |
+| 6 | No audit trail for invites received-but-never-clicked | 🟢 Polish |
+| 7 | `ic://` link scheme is vestigial, nothing registers the handler | 🟢 Polish |
+
+### Severity 🔴 — the root key leak
+
+Current canonical invite bytes:
+```
+v | mesh_id | mesh_slug | broker_url | expires_at | mesh_root_key | role | owner_pubkey
+```
+
+`mesh_root_key` is a 32-byte shared secret used by all channel and broadcast encryption in the mesh. Once it lives in a URL:
+- Slack/Telegram/Discord link previews fetch and cache the URL → root key is in those caches
+- Browser history, sync, analytics pixels, error logs → root key persists anywhere URLs persist
+- A screenshot of the invite link is a compromise
+- Revoking the invite does **not** rotate the key, so exposure is permanent
+
+**Anthropic would never do this.** The fix is a protocol change: the invite grants the *right* to receive the key, it is not the key itself.
+
+### The v2 invite protocol (spec only in this doc — NOT implemented this session)
+
+**Design goals**
+1. No secret material in any user-visible string (URL, QR, paste buffer)
+2. Invite URLs are short (<30 chars): `claudemesh.com/i/abc12345`
+3. Existing v1 invites continue to work during a deprecation window
+4. Revocation is clean and immediate
+5. One recipient = one root-key-delivery capability
+
+**Flow**
+```
+Admin creates invite (v2):
+  server generates short_code (base62, 8 chars, unique)
+  server stores in DB: {id, mesh_id, code, role, max_uses, expires_at, signed_capability}
+  signed_capability = ed25519_sign(canonical_v2_bytes, mesh.owner_secret_key)
+  canonical_v2_bytes = v=2 | mesh_id | invite_id | expires_at | role | owner_pubkey
+  NOTE: no root_key, no broker_url
+  returns: claudemesh.com/i/{code}
+
+Recipient clicks the link:
+  web: GET /api/public/invites/code/{code}
+    returns {mesh_name, inviter_name, role, expires_at, member_count}
+    no secrets, no signature leaked
+  web: shows consent landing: "You are joining ACME as a Member"
+  recipient authenticates (sign up / log in) OR runs CLI
+
+Recipient claims the invite:
+  CLI: generates session ed25519 keypair (ephemeral)
+  CLI: connects to broker ws://ic.claudemesh.com/ws
+  CLI: sends { type: "claim_invite", code, recipient_pubkey }
+  broker: looks up invite by code
+  broker: verifies signed_capability against mesh.owner_pubkey
+  broker: checks expires_at, max_uses vs used_count, revoked_at
+  broker: increments used_count, creates mesh.member row
+  broker: seals mesh.root_key with crypto_box_seal to recipient_pubkey
+  broker: returns { sealed_root_key, mesh_id, member_id }
+  CLI: unseals with its secret key → has root_key
+  CLI: starts normal mesh traffic
+
+Revocation:
+  admin sets invite.revoked_at = now()
+  any future claim fails at broker with invite_revoked
+  root_key is NOT rotated — past members keep access
+  (for "kick a member" semantics, use a separate member revocation, which DOES rotate the key)
+```
+
+**Properties**
+- URL contains only `{code}` (8 chars base62)
+- `signed_capability` lives server-side; leaks of the URL never expose the root key
+- Screenshot of invite URL is harmless
+- Link preview bots see nothing sensitive
+- Broker DB is the source of truth for revocation
+
+**Migration strategy (v1 → v2)**
+- Add `invite.code`, `invite.v2_capability` columns (nullable for existing rows)
+- `createMyInvite` generates BOTH v1 token (legacy) and v2 code
+- Web invite UI displays the short URL by default, long URL as "Legacy format" disclosure
+- Broker accepts both formats until v0.2.0
+- Announce deprecation window; at v0.2.0 the long-format endpoints 410 Gone
+
+**Status update 2026-04-10 — v2 is now being implemented in parallel**
+
+The scope that was deferred at the top of the session is actively landing in a coordinated multi-agent push:
+- Broker: new `/api/public/invites/:code/claim` endpoint, `crypto_box_seal` against recipient x25519 pubkey, signed capability verification, single-use accounting.
+- DB: `mesh.invite.version` int, `mesh.invite.capability_v2` text nullable, `mesh.invite.claimed_by_pubkey` text nullable. New table `mesh.pending_invite` for email invites.
+- CLI / web claim client: generates a fresh x25519 keypair (separate from the ed25519 identity), POSTs the pubkey, unseals the returned `sealed_root_key`, then verifies `canonical_v2` against `owner_pubkey`.
+- Email invites (parallel track): Postmark delivery wired on top of `pending_invite`; the email body carries the same `claudemesh.com/i/{code}` short URL.
+
+v1 invites continue to work throughout v0.1.x. v1 endpoints return `410 Gone` at v0.2.0.
+
+Docs updated in the same session: `SPEC.md` §14b, `docs/protocol.md` (v2 invites subsection), `docs/roadmap.md` (in progress).
+
+---
+
+### Severity 🟡 — implemented this session
+
+#### Short invite codes (URL shortening, backward-compatible)
+
+Additive: invites now get both a long token AND a short opaque code. The web app prefers the short URL.
+
+**DB:** new nullable `invite.code` column, unique. New migration `0018_invite-short-code.sql`.
+
+**API:** `createMyInvite` generates `code` (base62, 8 chars, collision-retry). Returns `shortUrl` alongside `inviteLink` / `joinUrl`.
+
+**Web:** new server route `/i/[code]/page.tsx` that resolves the code server-side and redirects to the canonical `/join/[token]` page. Invite generator UI shows the short URL as the primary "Copy link" target.
+
+**Backward compat:** existing invites without a `code` keep working via their long token. No broker/CLI changes.
+
+**This is NOT the v2 protocol.** It only fixes the URL-length problem. The root key is still embedded in the long token that the short code resolves to. The short code is a URL shortener, not a capability boundary. Document this clearly so nobody confuses the two.
+
+---
+
+#### Collapsed advanced fields
+
+The invite form asks for `role`, `max uses`, `expires in days` upfront. 90% of users only ever create `{ role: member, max_uses: 1, expires_in_days: 7 }`.
+
+Change: defaults are pre-filled; the three fields are hidden behind an "Advanced" disclosure.
+
+---
+
+### Severity 🟡 — deferred
+
+#### Invite by email
+
+- Requires an `invitation_email` table or equivalent pending-invites state
+- Requires wire-up to email delivery (already have Postmark via turbostarter)
+- Out of scope this session; fits naturally on top of v2 invite protocol
+
+#### Consent landing redesign
+
+- The `/join/[token]` page should show: mesh name, inviter, role being granted, member count, expiry, explicit "Join as Member of ACME" button
+- Needs a design pass
+- Deferred
+
+---
+
+### Severity 🟢 — deferred
+
+- Remove `ic://` scheme — it's dead, nothing handles it, safe to delete in v0.1.x cleanup
+- Received-but-not-clicked audit — falls out of email invites for free
+
+---
+
+## Summary table
+
+| Change | Status | File(s) |
+|---|---|---|
+| Drop global slug uniqueness | ✅ done | `packages/db/src/schema/mesh.ts`, migration `0017` |
+| Remove slug from create-mesh form | ✅ done | `apps/web/src/modules/mesh/create-mesh-form.tsx` |
+| Server-derived slug from name | ✅ done | `packages/api/src/modules/mesh/mutations.ts` |
+| Short invite codes (URL shortener) | ✅ done | `packages/db` migration `0018`, api, web `/i/[code]` |
+| Collapse invite advanced fields | ✅ done | `apps/web/src/modules/mesh/invite-generator.tsx` |
+| v2 invite protocol (root key out of URL) | 🚧 in progress | broker `/api/public/invites/:code/claim`, `mesh.invite.version` + `capability_v2` + `claimed_by_pubkey`, CLI/web claim client |
+| Invite by email | 🚧 in progress | `mesh.pending_invite` table, Postmark delivery |
+| Consent landing redesign | 📝 spec only | (future PR) |
+| Remove `ic://` scheme | 📝 spec only | (cleanup PR) |
+
+---
+
+## Non-goals (for clarity)
+
+- Not adding per-user mesh namespaces (`alice/platform`) — opaque IDs are enough
+- Not adding vanity slugs at v0.1.x — can come as a Pro tier later
+- Not changing the broker wire protocol this session
+- Not rewriting the CLI join flow this session
+
+---
+
+## Post-implementation checklist
+
+- [x] Web builds without type errors on changed files
+- [x] Migrations run on production DB (`0017` applied; `0018` after review)
+- [x] No broker protocol change (backward compat verified)
+- [x] Existing long-token invites continue to resolve
+- [x] New invites expose `shortUrl` in the API response
--- a/.artifacts/specs/2026-04-15-cli-distribution-pipeline.md
+++ b/.artifacts/specs/2026-04-15-cli-distribution-pipeline.md
@@ -0,0 +1,58 @@
+# CLI Distribution Pipeline
+
+## Status
+- Shell installer (`/install`): ✅ live, needs polish
+- Single-binary build script (`scripts/build-binaries.ts`): ✅ written, not wired to CI
+- GitHub Releases publish: ❌ not set up
+- Homebrew tap: ❌ not set up
+- winget manifest: ❌ not set up
+
+## Shipped this session (alpha.28)
+- `bun build --compile` script at `apps/cli-v2/scripts/build-binaries.ts` produces
+  `dist/bin/claudemesh-{darwin,linux,windows}-{x64,arm64}` locally.
+- `/install` updated to use the one-command `claudemesh <invite-url>` flow.
+- `claudemesh url-handler install` registers the `claudemesh://` scheme on the three OSes.
+
+## What's missing
+
+### 1. GitHub Actions to build + publish binaries
+```yaml
+# .github/workflows/release-binaries.yml
+on: { push: { tags: ['v*'] } }
+jobs:
+  build:
+    strategy: { matrix: { target: [darwin-x64, darwin-arm64, linux-x64, linux-arm64, windows-x64] } }
+    steps:
+      - uses: oven-sh/setup-bun@v2
+      - run: cd apps/cli-v2 && bun install --frozen-lockfile
+      - run: cd apps/cli-v2 && bun run scripts/build-binaries.ts
+      - uses: softprops/action-gh-release@v2
+        with: { files: apps/cli-v2/dist/bin/* }
+```
+
+### 2. `/install` detects missing Node and downloads a binary
+Current `/install` requires Node 20+. Next iteration: detect absence, curl the
+right binary from GitHub Releases, drop it in `~/.claudemesh/bin/`, add to PATH.
+
+### 3. Homebrew tap (`homebrew-claudemesh`)
+Separate repo with a formula that points at the GitHub Release artifact.
+Users: `brew install alezmad/claudemesh/claudemesh`. Auto-updated by the
+release workflow via `brew bump-formula-pr`.
+
+### 4. winget manifest
+YAML in `microsoft/winget-pkgs` repo pointing at the Windows .exe.
+
+### 5. Auto-update in-CLI
+Already have `showUpdateNotice`. Upgrade to offer `claudemesh upgrade` that
+re-runs `/install` OR downloads a new binary in place.
+
+## Why this matters
+Current state: users need Node, npm, and patience. Goal state:
+```
+curl -fsSL claudemesh.com/install | sh
+```
+…and that's it, on any OS, with or without Node.
+
+## Priority
+After tier-1 usability (done), this is the next biggest lever for adoption.
+Estimate: 1-2 days for full pipeline, mostly CI config + release testing.
--- a/.artifacts/specs/2026-04-15-per-peer-capabilities.md
+++ b/.artifacts/specs/2026-04-15-per-peer-capabilities.md
@@ -0,0 +1,75 @@
+# Per-Peer Capabilities
+
+## Goal
+Give mesh members fine-grained control over what peers can do to their
+session. Today: any mesh peer can send you any message; all messages get
+pushed as `<channel>` reminders. Users can't say "only @alice can send me
+messages," "read-only peers," or "@bob can broadcast but not DM."
+
+## Current state
+- Mesh-level role: `admin` | `member` (only affects invite issuance)
+- No per-peer filter — every peer message is delivered
+- No per-peer read/write split (all peers have the same capabilities)
+
+## Target capability model
+
+| Capability   | Meaning                                                |
+|--------------|--------------------------------------------------------|
+| `read`       | Peer appears in your list_peers, can see your summary  |
+| `dm`         | Peer can send you direct messages                      |
+| `broadcast`  | Peer's group broadcasts reach you                      |
+| `state-read` | Peer can read shared state keys                        |
+| `state-write`| Peer can set shared state keys                         |
+| `file-read`  | Peer can read files you've shared (already exists)     |
+
+## CLI surface
+```
+claudemesh grant @alice dm broadcast   # allow direct + broadcast
+claudemesh grant @bob state-read       # read-only
+claudemesh revoke @alice broadcast
+claudemesh grants                       # list current grants per peer
+claudemesh block @spammer               # shorthand for revoke-all
+```
+
+## Broker schema
+New column on `mesh_member`:
+```sql
+peer_grants jsonb DEFAULT '{}'::jsonb
+  -- shape: { "<peer_pubkey_hex>": ["dm", "broadcast", ...] }
+```
+
+Alternative (cleaner): separate `peer_grant` table keyed on
+`(member_id, target_pubkey)`.
+
+## Enforcement point
+Broker's message router (`apps/broker/src/index.ts` — send flow).
+Before writing the encrypted message to the recipient's queue, check
+`recipient.peer_grants[sender_pubkey]` against message kind. Drop
+silently if disallowed (sender sees delivered, recipient sees nothing —
+matches Signal/iMessage block semantics).
+
+## Defaults
+- Unknown peers: `read + dm` (matches current behavior — additive-safe rollout)
+- Existing members: grandfathered into `read + dm + broadcast + state-read`
+  via a migration
+- `claudemesh profile --default-grants read dm` lets users change their own default
+
+## UI
+- `claudemesh peers` renders a `[grants: dm,broadcast]` tag per peer
+- `claudemesh verify` gains a `--with-grants` flag that shows the grant set
+  alongside the safety number (helps the "did I accidentally block them?" check)
+
+## Crypto implications
+Grants are server-enforced metadata. Not capability tokens. A malicious
+broker could forward messages regardless — this is about UX trust (spam /
+noise control), not protocol security. The spec is clear about this.
+
+## Migration plan
+1. Ship broker schema change (jsonb column, nullable, default `{}`).
+2. Ship `grant/revoke/grants/block` CLI commands against an unused column.
+3. Enable enforcement in broker behind a per-mesh feature flag.
+4. Flip on for all meshes.
+
+## Priority
+Nice-to-have. The killer feature here is `block` — every mesh gets a bad
+actor eventually. Ship `block` first even if the full grant system is deferred.
--- a/.env.example
+++ b/.env.example
@@ -16,3 +16,6 @@ URL="http://localhost:3000"

 # Default locale of the apps, can be overridden separately in each app.
 DEFAULT_LOCALE="en"
+
+# Shared secret for CLI sync JWT signing (HS256) — must match between broker and web app
+CLI_SYNC_SECRET="<your-cli-sync-secret>"
--- a/.github/workflows/release-cli.yml
+++ b/.github/workflows/release-cli.yml
@@ -0,0 +1,113 @@
+name: Release CLI binaries
+
+# Fires on any push of a tag shaped like `cli-v1.2.3` (prerelease `-alpha.N` OK).
+# Builds self-contained `bun build --compile` binaries for darwin/linux/win
+# (x64 + arm64) and attaches them to a GitHub Release. The `install.sh`
+# fallback path curls these when Node isn't available.
+#
+# Publishing to npm is still a manual step (pnpm publish from apps/cli-v2) —
+# this workflow only handles binary distribution.
+
+on:
+  push:
+    tags:
+      - "cli-v*"
+  workflow_dispatch:
+    inputs:
+      tag:
+        description: "Release tag to build (e.g. cli-v1.0.0-alpha.28)"
+        required: true
+
+permissions:
+  contents: write # to upload release assets
+
+jobs:
+  build:
+    name: ${{ matrix.target }}
+    runs-on: ${{ matrix.runner }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { target: darwin-x64,   bun_target: bun-darwin-x64,   runner: macos-latest,   ext: "" }
+          - { target: darwin-arm64, bun_target: bun-darwin-arm64, runner: macos-latest,   ext: "" }
+          - { target: linux-x64,    bun_target: bun-linux-x64,    runner: ubuntu-latest,  ext: "" }
+          - { target: linux-arm64,  bun_target: bun-linux-arm64,  runner: ubuntu-latest,  ext: "" }
+          - { target: windows-x64,  bun_target: bun-windows-x64,  runner: windows-latest, ext: ".exe" }
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: "1.2"
+
+      - uses: pnpm/action-setup@v4
+
+      - name: Install workspace deps
+        run: pnpm install --frozen-lockfile --ignore-scripts
+
+      - name: Compile binary
+        working-directory: apps/cli-v2
+        shell: bash
+        run: |
+          mkdir -p dist/bin
+          bun build --compile --minify \
+            --target=${{ matrix.bun_target }} \
+            src/entrypoints/cli.ts \
+            --outfile dist/bin/claudemesh-${{ matrix.target }}${{ matrix.ext }}
+
+      # Smoke test only on native arch. macos-latest runners are ARM64 (Apple
+      # Silicon); ubuntu-latest is x64. Cross-compiled binaries can't execute
+      # on the build host, so skip them.
+      - name: Smoke test (native only)
+        if: matrix.target == 'darwin-arm64' || matrix.target == 'linux-x64'
+        working-directory: apps/cli-v2
+        run: |
+          ./dist/bin/claudemesh-${{ matrix.target }} --version
+          ./dist/bin/claudemesh-${{ matrix.target }} --help | head -5
+
+      - name: Upload artefact
+        uses: actions/upload-artifact@v4
+        with:
+          name: claudemesh-${{ matrix.target }}
+          path: apps/cli-v2/dist/bin/claudemesh-${{ matrix.target }}${{ matrix.ext }}
+
+  release:
+    needs: build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+
+      - name: Stage binaries
+        run: |
+          mkdir -p release
+          find artifacts -type f -exec cp {} release/ \;
+          cd release && sha256sum claudemesh-* > SHA256SUMS
+
+      - name: Publish release
+        uses: softprops/action-gh-release@v2
+        with:
+          tag_name: ${{ github.ref_name }}
+          files: |
+            release/claudemesh-*
+            release/SHA256SUMS
+          generate_release_notes: true
+          fail_on_unmatched_files: true
+
+  update-homebrew:
+    needs: release
+    runs-on: macos-latest
+    if: github.event_name == 'push' && !contains(github.ref_name, 'alpha')
+    steps:
+      - name: Bump Homebrew tap formula
+        env:
+          HOMEBREW_GITHUB_API_TOKEN: ${{ secrets.HOMEBREW_TAP_TOKEN }}
+        run: |
+          brew tap alezmad/claudemesh || true
+          brew bump-formula-pr --no-browse --no-fork \
+            --tag "${{ github.ref_name }}" \
+            --revision "${{ github.sha }}" \
+            alezmad/claudemesh/claudemesh || echo "formula bump skipped (no tap yet)"
--- a/.gitignore
+++ b/.gitignore
@@ -45,6 +45,9 @@ yarn-error.log*
 # local env files
 .env*.local

+# secrets
+.cli_sync_secret
+
 # vercel
 .vercel

@@ -72,3 +75,4 @@ dist/
 apps/web/payload.db
 apps/web/public/media/*
 !apps/web/public/media/.gitkeep
+.env.local
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,30 @@
+# claudemesh
+
+Peer mesh for Claude Code sessions. Broker + CLI + MCP server.
+
+## Structure
+
+- `apps/broker/` — WebSocket broker (Bun + Drizzle + PostgreSQL), deployed at `wss://ic.claudemesh.com/ws`
+- `apps/cli/` — `claudemesh-cli` npm package (CLI + MCP server)
+- `apps/web/` — Marketing site + dashboard at claudemesh.com
+- `docs/` — Protocol spec, quickstart, FAQ, roadmap
+
+## Key docs
+
+- `SPEC.md` — What claudemesh is, protocol, crypto, wire format
+- `docs/protocol.md` — Wire protocol reference
+- `docs/roadmap.md` — Public roadmap (shipped + planned)
+- `docs/vision-20260407.md` — Internal feature brainstorm with 19 ideas across 3 tiers, effort estimates, and build order
+
+## Deploy
+
+- **Broker:** `git push gitea-vps main` triggers Coolify auto-deploy. Manual: `curl -s -X GET "http://100.122.34.28:8000/api/v1/deploy?uuid=mcn8m74tbxfxbplmyb40b2ia" -H "Authorization: Bearer 3|K2vkSJzdUA69rj22CKZc5z0YB6pkY43GLEonti3UzcnqVJj6WhrqqYTAng6DzMUi"`
+- **CLI:** `cd apps/cli && pnpm publish --access public --no-git-checks`
+- **Web:** Vercel auto-deploy on push to GitHub
+
+## Dev
+
+- Monorepo: pnpm workspaces + Turborepo
+- Broker dev: `cd apps/broker && bun --hot src/index.ts`
+- CLI build: `cd apps/cli && pnpm build` (Bun bundler)
+- CLI link for local testing: `cd apps/cli && npm link`
--- a/SPEC.md
+++ b/SPEC.md
--- a/apps/broker/Dockerfile
+++ b/apps/broker/Dockerfile
@@ -37,7 +37,7 @@ COPY --from=deps --chown=bun:bun /deploy /app

 EXPOSE 7900

-HEALTHCHECK --interval=15s --timeout=5s --start-period=10s --retries=3 \
+HEALTHCHECK --interval=10s --timeout=5s --start-period=30s --retries=5 \
  CMD bun -e "fetch('http://localhost:7900/health').then(r=>{process.exit(r.ok?0:1)}).catch(()=>process.exit(1))"

 # Non-root user (oven/bun image ships with 'bun' uid 1000)
--- a/apps/broker/package.json
+++ b/apps/broker/package.json
@@ -15,10 +15,19 @@
  },
  "prettier": "@turbostarter/prettier-config",
  "dependencies": {
+    "@anthropic-ai/sdk": "0.71.2",
+    "@qdrant/js-client-rest": "1.17.0",
+    "@react-email/components": "0.3.2",
+    "@react-email/render": "1.3.2",
    "@turbostarter/db": "workspace:*",
    "@turbostarter/shared": "workspace:*",
    "drizzle-orm": "0.44.7",
+    "grammy": "^1.35.0",
    "libsodium-wrappers": "0.7.15",
+    "minio": "8.0.7",
+    "neo4j-driver": "6.0.1",
+    "react": "19.2.0",
+    "react-dom": "19.2.0",
    "ws": "8.20.0",
    "zod": "catalog:"
  },
@@ -28,6 +37,8 @@
    "@turbostarter/tsconfig": "workspace:*",
    "@turbostarter/vitest-config": "workspace:*",
    "@types/libsodium-wrappers": "0.7.14",
+    "@types/react": "19.2.0",
+    "@types/react-dom": "19.2.0",
    "@types/ws": "8.5.13",
    "eslint": "catalog:",
    "prettier": "catalog:",
--- a/apps/broker/src/audit.ts
+++ b/apps/broker/src/audit.ts
@@ -0,0 +1,215 @@
+/**
+ * Signed audit log with hash-chain integrity.
+ *
+ * Every significant mesh event is recorded as an append-only entry.
+ * Each entry's SHA-256 hash includes the previous entry's hash,
+ * forming a tamper-evident chain per mesh. If any row is modified
+ * or deleted, all subsequent hashes will fail verification.
+ *
+ * NEVER logs message content (ciphertext or plaintext) — only metadata.
+ */
+
+import { createHash } from "node:crypto";
+import { asc, desc, eq, sql, and } from "drizzle-orm";
+import { db } from "./db";
+import { auditLog } from "@turbostarter/db/schema/mesh";
+import { log } from "./logger";
+
+// ---------------------------------------------------------------------------
+// In-memory last-hash cache (one entry per mesh, loaded from DB on startup)
+// ---------------------------------------------------------------------------
+
+const lastHash = new Map<string, string>();
+
+// ---------------------------------------------------------------------------
+// Core audit logging
+// ---------------------------------------------------------------------------
+
+function computeHash(
+  prevHash: string,
+  meshId: string,
+  eventType: string,
+  actorMemberId: string | null,
+  payload: Record<string, unknown>,
+  createdAt: Date,
+): string {
+  const input = `${prevHash}|${meshId}|${eventType}|${actorMemberId}|${JSON.stringify(payload)}|${createdAt.toISOString()}`;
+  return createHash("sha256").update(input).digest("hex");
+}
+
+/**
+ * Append an audit entry for a mesh event.
+ *
+ * Fire-and-forget safe — callers should `void audit(...)` or
+ * `.catch(log.warn)` to avoid blocking the hot path.
+ */
+export async function audit(
+  meshId: string,
+  eventType: string,
+  actorMemberId: string | null,
+  actorDisplayName: string | null,
+  payload: Record<string, unknown>,
+): Promise<void> {
+  const prevHash = lastHash.get(meshId) ?? "genesis";
+  const createdAt = new Date();
+  const hash = computeHash(prevHash, meshId, eventType, actorMemberId, payload, createdAt);
+
+  try {
+    await db.insert(auditLog).values({
+      meshId,
+      eventType,
+      actorMemberId,
+      actorDisplayName,
+      payload,
+      prevHash,
+      hash,
+      createdAt,
+    });
+    lastHash.set(meshId, hash);
+  } catch (e) {
+    log.warn("audit log insert failed", {
+      mesh_id: meshId,
+      event_type: eventType,
+      error: e instanceof Error ? e.message : String(e),
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Startup: load last hash per mesh from DB
+// ---------------------------------------------------------------------------
+
+export async function loadLastHashes(): Promise<void> {
+  try {
+    // For each mesh, find the most recent audit entry by id (serial).
+    // DISTINCT ON (mesh_id) ORDER BY id DESC gives us one row per mesh.
+    const rows = await db.execute<{ mesh_id: string; hash: string }>(sql`
+      SELECT DISTINCT ON (mesh_id) mesh_id, hash
+      FROM mesh.audit_log
+      ORDER BY mesh_id, id DESC
+    `);
+
+    for (const row of rows) {
+      lastHash.set(row.mesh_id, row.hash);
+    }
+    log.info("audit: loaded last hashes", { meshes: lastHash.size });
+  } catch (e) {
+    // Table may not exist yet on first boot — that's fine.
+    log.warn("audit: loadLastHashes failed (table may not exist yet)", {
+      error: e instanceof Error ? e.message : String(e),
+    });
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Chain verification
+// ---------------------------------------------------------------------------
+
+export async function verifyChain(
+  meshId: string,
+): Promise<{ valid: boolean; entries: number; brokenAt?: number }> {
+  const rows = await db
+    .select()
+    .from(auditLog)
+    .where(eq(auditLog.meshId, meshId))
+    .orderBy(asc(auditLog.id));
+
+  if (rows.length === 0) {
+    return { valid: true, entries: 0 };
+  }
+
+  for (let i = 0; i < rows.length; i++) {
+    const row = rows[i]!;
+    const expectedPrevHash = i === 0 ? "genesis" : rows[i - 1]!.hash;
+
+    // Verify prevHash linkage
+    if (row.prevHash !== expectedPrevHash) {
+      return { valid: false, entries: rows.length, brokenAt: row.id };
+    }
+
+    // Recompute hash and verify
+    const recomputed = computeHash(
+      row.prevHash,
+      row.meshId,
+      row.eventType,
+      row.actorMemberId,
+      row.payload as Record<string, unknown>,
+      row.createdAt,
+    );
+    if (recomputed !== row.hash) {
+      return { valid: false, entries: rows.length, brokenAt: row.id };
+    }
+  }
+
+  return { valid: true, entries: rows.length };
+}
+
+// ---------------------------------------------------------------------------
+// Query: paginated audit entries
+// ---------------------------------------------------------------------------
+
+export async function queryAuditLog(
+  meshId: string,
+  options?: { limit?: number; offset?: number; eventType?: string },
+): Promise<{ entries: Array<{ id: number; eventType: string; actor: string; payload: Record<string, unknown>; hash: string; createdAt: string }>; total: number }> {
+  const limit = options?.limit ?? 50;
+  const offset = options?.offset ?? 0;
+
+  const conditions = [eq(auditLog.meshId, meshId)];
+  if (options?.eventType) {
+    conditions.push(eq(auditLog.eventType, options.eventType));
+  }
+  const where = conditions.length === 1 ? conditions[0]! : and(...conditions);
+
+  const [rows, countResult] = await Promise.all([
+    db
+      .select()
+      .from(auditLog)
+      .where(where)
+      .orderBy(desc(auditLog.id))
+      .limit(limit)
+      .offset(offset),
+    db
+      .select({ count: sql<number>`count(*)` })
+      .from(auditLog)
+      .where(where),
+  ]);
+
+  return {
+    entries: rows.map((r) => ({
+      id: r.id,
+      eventType: r.eventType,
+      actor: r.actorDisplayName ?? r.actorMemberId ?? "system",
+      payload: r.payload as Record<string, unknown>,
+      hash: r.hash,
+      createdAt: r.createdAt.toISOString(),
+    })),
+    total: Number(countResult[0]?.count ?? 0),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Ensure table exists (raw DDL for first-boot before migrations run)
+// ---------------------------------------------------------------------------
+
+export async function ensureAuditLogTable(): Promise<void> {
+  try {
+    await db.execute(sql`
+      CREATE TABLE IF NOT EXISTS mesh.audit_log (
+        id INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
+        mesh_id TEXT NOT NULL REFERENCES mesh.mesh(id) ON DELETE CASCADE ON UPDATE CASCADE,
+        event_type TEXT NOT NULL,
+        actor_member_id TEXT,
+        actor_display_name TEXT,
+        payload JSONB NOT NULL DEFAULT '{}',
+        prev_hash TEXT NOT NULL,
+        hash TEXT NOT NULL,
+        created_at TIMESTAMP NOT NULL DEFAULT now()
+      )
+    `);
+  } catch (e) {
+    log.warn("audit: ensureAuditLogTable failed", {
+      error: e instanceof Error ? e.message : String(e),
+    });
+  }
+}
--- a/apps/broker/src/broker-crypto.ts
+++ b/apps/broker/src/broker-crypto.ts
@@ -0,0 +1,68 @@
+/**
+ * Broker-side symmetric encryption for persisting resolved env vars.
+ *
+ * Uses Node's built-in crypto (AES-256-GCM). The key comes from
+ * BROKER_ENCRYPTION_KEY env var (64 hex chars = 32 bytes). If not set,
+ * a random key is generated and logged on first use — operator should
+ * persist it to survive broker restarts.
+ *
+ * This is NOT the same as peer-side E2E crypto (libsodium). This is
+ * platform-level encryption-at-rest, same model as Heroku/Coolify/AWS.
+ */
+
+import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
+import { env } from "./env";
+import { log } from "./logger";
+
+const ALGO = "aes-256-gcm";
+const IV_LEN = 12;
+const TAG_LEN = 16;
+
+let _key: Buffer | null = null;
+
+function getKey(): Buffer {
+  if (_key) return _key;
+
+  if (env.BROKER_ENCRYPTION_KEY && env.BROKER_ENCRYPTION_KEY.length === 64) {
+    _key = Buffer.from(env.BROKER_ENCRYPTION_KEY, "hex");
+  } else {
+    _key = randomBytes(32);
+    log.warn("BROKER_ENCRYPTION_KEY not set — generated ephemeral key. " +
+      "Set BROKER_ENCRYPTION_KEY=" + _key.toString("hex") + " to persist across restarts.");
+  }
+  return _key;
+}
+
+/**
+ * Encrypt a JSON-serializable value. Returns a base64 string containing
+ * IV + ciphertext + auth tag.
+ */
+export function encryptForStorage(plaintext: string): string {
+  const key = getKey();
+  const iv = randomBytes(IV_LEN);
+  const cipher = createCipheriv(ALGO, key, iv);
+  const encrypted = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+  const tag = cipher.getAuthTag();
+  // Pack: IV (12) + tag (16) + ciphertext
+  return Buffer.concat([iv, tag, encrypted]).toString("base64");
+}
+
+/**
+ * Decrypt a value produced by encryptForStorage. Returns the plaintext
+ * string, or null if decryption fails (wrong key, tampered).
+ */
+export function decryptFromStorage(packed: string): string | null {
+  try {
+    const key = getKey();
+    const buf = Buffer.from(packed, "base64");
+    const iv = buf.subarray(0, IV_LEN);
+    const tag = buf.subarray(IV_LEN, IV_LEN + TAG_LEN);
+    const ciphertext = buf.subarray(IV_LEN + TAG_LEN);
+    const decipher = createDecipheriv(ALGO, key, iv);
+    decipher.setAuthTag(tag);
+    const decrypted = Buffer.concat([decipher.update(ciphertext), decipher.final()]);
+    return decrypted.toString("utf8");
+  } catch {
+    return null;
+  }
+}
--- a/apps/broker/src/broker.ts
+++ b/apps/broker/src/broker.ts
--- a/apps/broker/src/cli-sync.ts
+++ b/apps/broker/src/cli-sync.ts
@@ -0,0 +1,133 @@
+/**
+ * POST /cli-sync handler.
+ *
+ * Accepts a sync JWT from the dashboard, creates or finds member rows
+ * for each mesh in the token, and returns mesh details + member IDs.
+ */
+
+import { and, eq, isNull } from "drizzle-orm";
+import { db } from "./db";
+import { verifySyncToken, type SyncTokenPayload } from "./jwt";
+
+// Import schema tables
+import {
+  mesh as meshTable,
+  meshMember as memberTable,
+} from "@turbostarter/db/schema/mesh";
+import { generateId } from "@turbostarter/shared/utils";
+
+export interface CliSyncRequest {
+  sync_token: string;
+  peer_pubkey: string;   // ed25519 hex (64 chars)
+  display_name: string;
+}
+
+export interface CliSyncResponse {
+  ok: true;
+  account_id: string;
+  meshes: Array<{
+    mesh_id: string;
+    slug: string;
+    broker_url: string;
+    member_id: string;
+    role: "admin" | "member";
+  }>;
+}
+
+export interface CliSyncError {
+  ok: false;
+  error: string;
+}
+
+export async function handleCliSync(
+  body: CliSyncRequest,
+): Promise<CliSyncResponse | CliSyncError> {
+  // 1. Validate inputs
+  if (!body.sync_token || !body.peer_pubkey || !body.display_name) {
+    return { ok: false, error: "sync_token, peer_pubkey, display_name required" };
+  }
+  if (!/^[0-9a-f]{64}$/i.test(body.peer_pubkey)) {
+    return { ok: false, error: "peer_pubkey must be 64 hex chars (32 bytes)" };
+  }
+
+  // 2. Verify JWT
+  const tokenResult = await verifySyncToken(body.sync_token);
+  if (!tokenResult.ok) {
+    return { ok: false, error: `sync token invalid: ${tokenResult.error}` };
+  }
+  const payload = tokenResult.payload;
+
+  // 3. For each mesh in the token, create or find a member row
+  const resultMeshes: CliSyncResponse["meshes"] = [];
+
+  for (const tokenMesh of payload.meshes) {
+    // Verify mesh exists and is not archived
+    const [m] = await db
+      .select({ id: meshTable.id, slug: meshTable.slug })
+      .from(meshTable)
+      .where(and(eq(meshTable.id, tokenMesh.id), isNull(meshTable.archivedAt)));
+
+    if (!m) {
+      // Skip meshes that don't exist (could have been deleted)
+      continue;
+    }
+
+    // Check if this pubkey is already a member of this mesh
+    const [existing] = await db
+      .select({ id: memberTable.id, role: memberTable.role })
+      .from(memberTable)
+      .where(
+        and(
+          eq(memberTable.meshId, tokenMesh.id),
+          eq(memberTable.peerPubkey, body.peer_pubkey),
+          isNull(memberTable.revokedAt),
+        ),
+      );
+
+    let memberId: string;
+    let role: "admin" | "member";
+
+    if (existing) {
+      // Already a member — update dashboard link + display name
+      memberId = existing.id;
+      role = existing.role;
+      await db
+        .update(memberTable)
+        .set({
+          dashboardUserId: payload.sub,
+          displayName: body.display_name,
+        })
+        .where(eq(memberTable.id, existing.id));
+    } else {
+      // Create new member row
+      memberId = generateId();
+      role = tokenMesh.role;
+      await db.insert(memberTable).values({
+        id: memberId,
+        meshId: tokenMesh.id,
+        peerPubkey: body.peer_pubkey,
+        displayName: body.display_name,
+        role: tokenMesh.role,
+        dashboardUserId: payload.sub,
+      });
+    }
+
+    resultMeshes.push({
+      mesh_id: tokenMesh.id,
+      slug: m.slug,
+      broker_url: process.env.BROKER_PUBLIC_URL ?? "wss://ic.claudemesh.com/ws",
+      member_id: memberId,
+      role,
+    });
+  }
+
+  if (resultMeshes.length === 0) {
+    return { ok: false, error: "no valid meshes found in sync token" };
+  }
+
+  return {
+    ok: true,
+    account_id: payload.sub,
+    meshes: resultMeshes,
+  };
+}
--- a/apps/broker/src/crypto.ts
+++ b/apps/broker/src/crypto.ts
@@ -7,7 +7,10 @@
 * current member of the claimed mesh.
 */

+import { and, eq, isNull, lt, sql } from "drizzle-orm";
 import sodium from "libsodium-wrappers";
+import { db } from "./db";
+import { invite as inviteTable, mesh, meshMember } from "@turbostarter/db/schema/mesh";

 let ready = false;
 async function ensureSodium(): Promise<typeof sodium> {
@@ -69,6 +72,70 @@ export async function verifyEd25519(
  }
 }

+/**
+ * Canonical v2 invite bytes — signed by the mesh owner's ed25519 secret key.
+ * NOTE: deliberately does NOT include the root_key or broker_url; the v2
+ * protocol moves the root_key out of the URL entirely. Format is locked:
+ * `v=2|mesh_id|invite_id|expires_at|role|owner_pubkey` (no trailing newline).
+ */
+export function canonicalInviteV2(p: {
+  mesh_id: string;
+  invite_id: string;
+  expires_at: number; // unix seconds
+  role: "admin" | "member";
+  owner_pubkey: string; // hex
+}): string {
+  return `v=2|${p.mesh_id}|${p.invite_id}|${p.expires_at}|${p.role}|${p.owner_pubkey}`;
+}
+
+/**
+ * Verify an ed25519 signature over the v2 canonical invite bytes against
+ * the mesh owner's public key. Returns true on valid signature.
+ */
+export async function verifyInviteV2(params: {
+  canonical: string;
+  signatureHex: string;
+  ownerPubkeyHex: string;
+}): Promise<boolean> {
+  return verifyEd25519(
+    params.canonical,
+    params.signatureHex,
+    params.ownerPubkeyHex,
+  );
+}
+
+/**
+ * Seal the mesh root_key to a recipient-provided x25519 public key using
+ * libsodium's sealed box (crypto_box_seal). Only the holder of the matching
+ * x25519 secret key can unseal.
+ *
+ *   rootKeyBase64url is the mesh.root_key column value (base64url of 32 bytes).
+ *   recipientX25519PubkeyBase64url is the 32-byte x25519 pubkey the recipient
+ *     provided in its claim request. We do NOT convert an ed25519 pubkey here —
+ *     the recipient generates a dedicated x25519 keypair and sends us the pubkey.
+ *
+ * Returns base64url of the sealed ciphertext.
+ */
+export async function sealRootKeyToRecipient(params: {
+  rootKeyBase64url: string;
+  recipientX25519PubkeyBase64url: string;
+}): Promise<string> {
+  const s = await ensureSodium();
+  const rootKeyBytes = s.from_base64(
+    params.rootKeyBase64url,
+    s.base64_variants.URLSAFE_NO_PADDING,
+  );
+  const recipientPk = s.from_base64(
+    params.recipientX25519PubkeyBase64url,
+    s.base64_variants.URLSAFE_NO_PADDING,
+  );
+  if (recipientPk.length !== 32) {
+    throw new Error("recipient_x25519_pubkey must decode to 32 bytes");
+  }
+  const sealed = s.crypto_box_seal(rootKeyBytes, recipientPk);
+  return s.to_base64(sealed, s.base64_variants.URLSAFE_NO_PADDING);
+}
+
 export const HELLO_SKEW_MS = 60_000;

 /**
@@ -118,3 +185,185 @@ export async function verifyHelloSignature(args: {
    return { ok: false, reason: "malformed" };
  }
 }
+
+// ----------------------------------------------------------------------------
+// v2 invite claim core — exported for the HTTP handler in index.ts AND for
+// tests that need to exercise the logic without spinning up the broker server.
+// ----------------------------------------------------------------------------
+//
+// capabilityV2 column is stored as JSON:
+//   { "canonical": "v=2|mesh_id|invite_id|expires_at|role|owner_pubkey",
+//     "signature": "<hex ed25519 detached signature>" }
+// The broker recomputes the canonical bytes from the invite row and verifies
+// the signature against mesh.ownerPubkey. v1 rows (version === 1 OR
+// capabilityV2 === null) skip verification — the legacy path still works
+// during the deprecation window.
+
+export type InviteClaimV2Result =
+  | {
+      ok: true;
+      status: 200;
+      body: {
+        sealed_root_key: string;
+        mesh_id: string;
+        member_id: string;
+        owner_pubkey: string;
+        canonical_v2: string;
+      };
+    }
+  | { ok: false; status: 400 | 404 | 410; body: { error: string } };
+
+export async function claimInviteV2Core(params: {
+  code: string;
+  recipientX25519PubkeyBase64url: string;
+  displayName?: string;
+  now?: number;
+}): Promise<InviteClaimV2Result> {
+  const now = params.now ?? Date.now();
+  const recipientPk = params.recipientX25519PubkeyBase64url;
+
+  if (!recipientPk || typeof recipientPk !== "string" || recipientPk.length < 32) {
+    return { ok: false, status: 400, body: { error: "malformed" } };
+  }
+
+  // 1. Look up the invite by opaque code.
+  const [inv] = await db
+    .select()
+    .from(inviteTable)
+    .where(eq(inviteTable.code, params.code))
+    .limit(1);
+  if (!inv) return { ok: false, status: 404, body: { error: "not_found" } };
+
+  // 2. Lifecycle checks: revoked → expired → exhausted.
+  if (inv.revokedAt) {
+    return { ok: false, status: 410, body: { error: "revoked" } };
+  }
+  if (inv.expiresAt.getTime() < now) {
+    return { ok: false, status: 410, body: { error: "expired" } };
+  }
+  if (inv.usedCount >= inv.maxUses) {
+    return { ok: false, status: 410, body: { error: "exhausted" } };
+  }
+
+  // 3. Load the mesh for owner_pubkey + root_key.
+  const [m] = await db
+    .select({
+      id: mesh.id,
+      ownerPubkey: mesh.ownerPubkey,
+      rootKey: mesh.rootKey,
+    })
+    .from(mesh)
+    .where(and(eq(mesh.id, inv.meshId), isNull(mesh.archivedAt)))
+    .limit(1);
+  if (!m) return { ok: false, status: 404, body: { error: "not_found" } };
+  if (!m.ownerPubkey || !m.rootKey) {
+    return { ok: false, status: 400, body: { error: "malformed" } };
+  }
+
+  // 4. Compute canonical_v2 from the row (used in the response either way).
+  const expiresAtUnix = Math.floor(inv.expiresAt.getTime() / 1000);
+  const canonical = canonicalInviteV2({
+    mesh_id: inv.meshId,
+    invite_id: inv.id,
+    expires_at: expiresAtUnix,
+    role: inv.role as "admin" | "member",
+    owner_pubkey: m.ownerPubkey,
+  });
+
+  if (inv.version === 2 && inv.capabilityV2) {
+    let storedCanonical: string | undefined;
+    let signatureHex: string | undefined;
+    try {
+      const parsed = JSON.parse(inv.capabilityV2) as {
+        canonical?: string;
+        signature?: string;
+      };
+      storedCanonical = parsed.canonical;
+      signatureHex = parsed.signature;
+    } catch {
+      return { ok: false, status: 400, body: { error: "malformed" } };
+    }
+    if (!storedCanonical || !signatureHex) {
+      return { ok: false, status: 400, body: { error: "malformed" } };
+    }
+    // Broker-recomputed canonical must match the signed bytes exactly.
+    if (storedCanonical !== canonical) {
+      return { ok: false, status: 400, body: { error: "bad_signature" } };
+    }
+    const sigOk = await verifyInviteV2({
+      canonical: storedCanonical,
+      signatureHex,
+      ownerPubkeyHex: m.ownerPubkey,
+    });
+    if (!sigOk) {
+      return { ok: false, status: 400, body: { error: "bad_signature" } };
+    }
+  }
+  // v1 rows: skip signature verification (legacy path during migration).
+
+  // 5. Atomic consume: increment used_count iff still under max_uses.
+  const [claimed] = await db
+    .update(inviteTable)
+    .set({
+      usedCount: sql`${inviteTable.usedCount} + 1`,
+      claimedByPubkey: recipientPk,
+    })
+    .where(
+      and(
+        eq(inviteTable.id, inv.id),
+        lt(inviteTable.usedCount, inv.maxUses),
+      ),
+    )
+    .returning({ id: inviteTable.id });
+  if (!claimed) {
+    return { ok: false, status: 410, body: { error: "exhausted" } };
+  }
+
+  // 6. Create a member row for the claimant.
+  const preset = (inv.preset as {
+    displayName?: string;
+    roleTag?: string;
+    groups?: Array<{ name: string; role?: string }>;
+    messageMode?: string;
+  } | null) ?? {};
+  const displayName =
+    preset.displayName ?? params.displayName ?? `member-${recipientPk.slice(0, 8)}`;
+  const [row] = await db
+    .insert(meshMember)
+    .values({
+      meshId: inv.meshId,
+      peerPubkey: recipientPk,
+      displayName,
+      role: inv.role,
+      roleTag: preset.roleTag ?? null,
+      defaultGroups: preset.groups ?? [],
+      messageMode: preset.messageMode ?? "push",
+    })
+    .returning({ id: meshMember.id });
+  if (!row) {
+    return { ok: false, status: 400, body: { error: "malformed" } };
+  }
+
+  // 7. Seal the mesh root_key to the recipient's x25519 pubkey.
+  let sealed: string;
+  try {
+    sealed = await sealRootKeyToRecipient({
+      rootKeyBase64url: m.rootKey,
+      recipientX25519PubkeyBase64url: recipientPk,
+    });
+  } catch {
+    return { ok: false, status: 400, body: { error: "malformed" } };
+  }
+
+  return {
+    ok: true,
+    status: 200,
+    body: {
+      sealed_root_key: sealed,
+      mesh_id: inv.meshId,
+      member_id: row.id,
+      owner_pubkey: m.ownerPubkey,
+      canonical_v2: canonical,
+    },
+  };
+}
--- a/apps/broker/src/emails/mesh-invitation.tsx
+++ b/apps/broker/src/emails/mesh-invitation.tsx
@@ -0,0 +1,320 @@
+import {
+  Body,
+  Button,
+  Container,
+  Head,
+  Heading,
+  Hr,
+  Html,
+  Link,
+  Preview,
+  Section,
+  Text,
+} from "@react-email/components";
+import * as React from "react";
+
+interface MeshInvitationProps {
+  meshName: string;
+  inviteUrl: string;
+  token: string;
+  expiresAt: string;
+  appBaseUrl: string;
+}
+
+// Brand tokens — mirror of apps/web/src/assets/styles/globals.css (--cm-*).
+// Inlined here because email clients don't resolve CSS vars.
+const brand = {
+  bg: "#141413",
+  bgElevated: "#1f1e1d",
+  bgCode: "#0f0e0d",
+  fg: "#faf9f5",
+  fgSecondary: "#c2c0b6",
+  fgTertiary: "#87867f",
+  clay: "#d97757",
+  clayBorder: "rgba(217, 119, 87, 0.35)",
+  border: "rgba(217, 119, 87, 0.2)",
+  serif: 'Georgia, "Times New Roman", serif',
+  mono: '"JetBrains Mono", "SF Mono", Menlo, Consolas, monospace',
+  sans:
+    '-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif',
+} as const;
+
+export const MeshInvitation = ({
+  meshName,
+  inviteUrl,
+  token,
+  expiresAt,
+  appBaseUrl,
+}: MeshInvitationProps) => {
+  const expiresLabel = new Date(expiresAt).toUTCString();
+  const launchCmd = `claudemesh launch --join ${inviteUrl}`;
+  const oneLiner = `npm i -g claudemesh-cli && ${launchCmd}`;
+
+  return (
+    <Html lang="en">
+      <Head>
+        <meta name="color-scheme" content="dark" />
+        <meta name="supported-color-schemes" content="dark" />
+      </Head>
+      <Preview>You've been invited to the {meshName} mesh on claudemesh</Preview>
+      <Body
+        style={{
+          backgroundColor: brand.bg,
+          color: brand.fg,
+          fontFamily: brand.sans,
+          margin: 0,
+          padding: "40px 0",
+        }}
+      >
+        <Container
+          style={{
+            maxWidth: "560px",
+            margin: "0 auto",
+            padding: "0 24px",
+          }}
+        >
+          {/* Header — mesh glyph + wordmark */}
+          <Section style={{ marginBottom: "40px" }}>
+            <table role="presentation" cellPadding={0} cellSpacing={0} border={0}>
+              <tr>
+                <td style={{ verticalAlign: "middle", paddingRight: "10px" }}>
+                  <svg
+                    width="22"
+                    height="22"
+                    viewBox="0 0 24 24"
+                    xmlns="http://www.w3.org/2000/svg"
+                  >
+                    <circle cx="12" cy="4" r="2" fill={brand.clay} />
+                    <circle cx="4" cy="12" r="2" fill={brand.clay} />
+                    <circle cx="20" cy="12" r="2" fill={brand.clay} />
+                    <circle cx="12" cy="20" r="2" fill={brand.clay} />
+                    <path
+                      d="M12 4L4 12M12 4L20 12M4 12L12 20M20 12L12 20M4 12L20 12M12 4L12 20"
+                      stroke={brand.clay}
+                      strokeWidth="1.2"
+                      opacity="0.45"
+                      fill="none"
+                    />
+                  </svg>
+                </td>
+                <td style={{ verticalAlign: "middle" }}>
+                  <Text
+                    style={{
+                      fontFamily: brand.serif,
+                      fontSize: "17px",
+                      fontWeight: 500,
+                      letterSpacing: "-0.01em",
+                      color: brand.fg,
+                      margin: 0,
+                    }}
+                  >
+                    claudemesh
+                  </Text>
+                </td>
+              </tr>
+            </table>
+          </Section>
+
+          {/* Eyebrow */}
+          <Text
+            style={{
+              fontFamily: brand.mono,
+              fontSize: "11px",
+              textTransform: "uppercase",
+              letterSpacing: "0.22em",
+              color: brand.clay,
+              margin: "0 0 16px 0",
+            }}
+          >
+            — you're invited
+          </Text>
+
+          {/* Heading */}
+          <Heading
+            as="h1"
+            style={{
+              fontFamily: brand.serif,
+              fontSize: "32px",
+              fontWeight: 500,
+              lineHeight: "1.15",
+              letterSpacing: "-0.01em",
+              color: brand.fg,
+              margin: "0 0 20px 0",
+            }}
+          >
+            Join{" "}
+            <span style={{ fontFamily: brand.mono, color: brand.clay }}>
+              {meshName}
+            </span>{" "}
+            on claudemesh
+          </Heading>
+
+          {/* Body prose */}
+          <Text
+            style={{
+              fontFamily: brand.serif,
+              fontSize: "16px",
+              lineHeight: "1.65",
+              color: brand.fgSecondary,
+              margin: "0 0 32px 0",
+            }}
+          >
+            claudemesh is a peer mesh for Claude Code sessions — end-to-end
+            encrypted, keys stay on your machine. Open the link below to see
+            the mesh, the inviter, and the command to join.
+          </Text>
+
+          {/* Primary CTA */}
+          <Section style={{ marginBottom: "36px" }}>
+            <Button
+              href={inviteUrl}
+              style={{
+                backgroundColor: brand.clay,
+                color: brand.fg,
+                fontFamily: brand.sans,
+                fontSize: "15px",
+                fontWeight: 500,
+                textDecoration: "none",
+                padding: "14px 28px",
+                borderRadius: "4px",
+                display: "inline-block",
+              }}
+            >
+              Open invite →
+            </Button>
+          </Section>
+
+          {/* Terminal shortcut — for the already-set-up crowd */}
+          <Text
+            style={{
+              fontFamily: brand.mono,
+              fontSize: "11px",
+              textTransform: "uppercase",
+              letterSpacing: "0.22em",
+              color: brand.fgTertiary,
+              margin: "0 0 12px 0",
+            }}
+          >
+            — already have the CLI?
+          </Text>
+          <Section
+            style={{
+              backgroundColor: brand.bgElevated,
+              border: `1px solid ${brand.clayBorder}`,
+              borderRadius: "6px",
+              padding: "16px 18px",
+              marginBottom: "32px",
+            }}
+          >
+            <Text
+              style={{
+                fontFamily: brand.mono,
+                fontSize: "12px",
+                color: brand.fg,
+                margin: 0,
+                wordBreak: "break-all",
+                lineHeight: "1.6",
+              }}
+            >
+              {launchCmd}
+            </Text>
+          </Section>
+
+          {/* First-time one-liner */}
+          <Text
+            style={{
+              fontFamily: brand.mono,
+              fontSize: "11px",
+              textTransform: "uppercase",
+              letterSpacing: "0.22em",
+              color: brand.fgTertiary,
+              margin: "0 0 12px 0",
+            }}
+          >
+            — first time? one command
+          </Text>
+          <Section
+            style={{
+              backgroundColor: brand.bgElevated,
+              border: `1px solid ${brand.border}`,
+              borderRadius: "6px",
+              padding: "16px 18px",
+              marginBottom: "32px",
+            }}
+          >
+            <Text
+              style={{
+                fontFamily: brand.mono,
+                fontSize: "12px",
+                color: brand.fg,
+                margin: 0,
+                lineHeight: "1.6",
+                wordBreak: "break-all",
+              }}
+            >
+              {oneLiner}
+            </Text>
+            <Text
+              style={{
+                fontFamily: brand.serif,
+                fontSize: "12px",
+                color: brand.fgTertiary,
+                margin: "8px 0 0 0",
+              }}
+            >
+              Requires Node.js 20+. Display name defaults to $USER.
+            </Text>
+          </Section>
+
+          <Hr
+            style={{
+              border: "none",
+              borderTop: `1px solid ${brand.border}`,
+              margin: "28px 0 20px 0",
+            }}
+          />
+
+          {/* Footer meta */}
+          <Text
+            style={{
+              fontFamily: brand.serif,
+              fontSize: "13px",
+              lineHeight: "1.6",
+              color: brand.fgTertiary,
+              margin: "0 0 8px 0",
+            }}
+          >
+            Expires{" "}
+            <span style={{ color: brand.fgSecondary }}>{expiresLabel}</span>.
+            If you weren't expecting this, you can ignore it.
+          </Text>
+          <Text
+            style={{
+              fontFamily: brand.mono,
+              fontSize: "11px",
+              color: brand.fgTertiary,
+              margin: 0,
+            }}
+          >
+            <Link
+              href={appBaseUrl}
+              style={{ color: brand.fgTertiary, textDecoration: "underline" }}
+            >
+              claudemesh.com
+            </Link>
+          </Text>
+        </Container>
+      </Body>
+    </Html>
+  );
+};
+
+MeshInvitation.PreviewProps = {
+  meshName: "prueba1",
+  inviteUrl: "https://claudemesh.com/i/RUVMYXZQ",
+  token: "eyJ2IjoxLCJtZXNoX2lkIjoiQUtMYUZxR3FKOGZCajN0U3dvVk1PSFYxQmF3UGlYTE8iLCJtZXNoX3NsdWciOiJwcnVlYmExIn0",
+  expiresAt: "2026-04-22T00:51:26.181Z",
+  appBaseUrl: "https://claudemesh.com",
+} satisfies MeshInvitationProps;
+
+export default MeshInvitation;
--- a/apps/broker/src/env.ts
+++ b/apps/broker/src/env.ts
@@ -20,6 +20,21 @@ const envSchema = z.object({
  MAX_CONNECTIONS_PER_MESH: z.coerce.number().int().positive().default(100),
  MAX_MESSAGE_BYTES: z.coerce.number().int().positive().default(65_536),
  HOOK_RATE_LIMIT_PER_MIN: z.coerce.number().int().positive().default(30),
+  MINIO_ENDPOINT: z.string().default("minio:9000"),
+  MINIO_ACCESS_KEY: z.string().default("claudemesh"),
+  MINIO_SECRET_KEY: z.string().default("changeme"),
+  MINIO_USE_SSL: z.enum(["true", "false", ""]).transform(v => v === "true").default("false"),
+  QDRANT_URL: z.string().default("http://qdrant:6333"),
+  NEO4J_URL: z.string().default("bolt://neo4j:7687"),
+  NEO4J_USER: z.string().default("neo4j"),
+  NEO4J_PASSWORD: z.string().default("changeme"),
+  RUNNER_URL: z.string().default("http://runner:7901"),
+  CLAUDEMESH_SERVICES_DIR: z.string().default("/var/claudemesh/services"),
+  BROKER_ENCRYPTION_KEY: z.string().default(""),  // 64 hex chars (32 bytes). Auto-generated if empty.
+  CLI_SYNC_SECRET: z.string().default(""),  // HS256 shared secret for dashboard→broker sync JWTs. Required for /cli-sync.
+  MAX_SERVICES_PER_MESH: z.coerce.number().int().positive().default(20),
+  MAX_SERVICE_ZIP_BYTES: z.coerce.number().int().positive().default(50 * 1024 * 1024),
+  ANTHROPIC_API_KEY: z.string().default(""),  // Claude API key for Telegram AI bot
  NODE_ENV: z
    .enum(["development", "production", "test"])
    .default("development"),
--- a/apps/broker/src/index.ts
+++ b/apps/broker/src/index.ts
--- a/apps/broker/src/jwt.ts
+++ b/apps/broker/src/jwt.ts
@@ -0,0 +1,146 @@
+/**
+ * JWT verification for CLI sync tokens.
+ *
+ * Sync tokens are HS256 JWTs issued by the dashboard after OAuth,
+ * shared secret between dashboard and broker via env var.
+ *
+ * JTI dedup: tracks used token IDs in a TTL-evicted Set to prevent replay.
+ */
+
+import { env } from "./env";
+
+// --- Types ---
+
+export interface SyncTokenPayload {
+  sub: string;           // dashboard user ID
+  email: string;
+  meshes: Array<{
+    id: string;
+    slug: string;
+    role: "admin" | "member";
+  }>;
+  action: "sync" | "create";
+  newMesh?: {
+    name: string;
+    slug: string;
+  };
+  jti: string;           // unique token ID for replay prevention
+  iat: number;
+  exp: number;
+}
+
+// --- JTI dedup ---
+
+const usedJtis = new Map<string, number>(); // jti → expiry timestamp (ms)
+
+// Sweep expired JTIs every 5 minutes
+setInterval(() => {
+  const now = Date.now();
+  for (const [jti, exp] of usedJtis) {
+    if (exp < now) usedJtis.delete(jti);
+  }
+}, 5 * 60_000);
+
+// --- Verification ---
+
+/**
+ * Verify and decode a sync token JWT.
+ * Returns the decoded payload on success, or an error string on failure.
+ */
+export async function verifySyncToken(
+  token: string,
+): Promise<{ ok: true; payload: SyncTokenPayload } | { ok: false; error: string }> {
+  // Get shared secret from env
+  const secret = env.CLI_SYNC_SECRET;
+  if (!secret) {
+    return { ok: false, error: "CLI_SYNC_SECRET not configured on broker" };
+  }
+
+  try {
+    // Decode JWT manually (HS256)
+    const parts = token.split(".");
+    if (parts.length !== 3) {
+      return { ok: false, error: "malformed JWT" };
+    }
+
+    const headerB64 = parts[0]!;
+    const payloadB64 = parts[1]!;
+    const signatureB64 = parts[2]!;
+
+    // Verify signature (HS256)
+    const encoder = new TextEncoder();
+    const key = await crypto.subtle.importKey(
+      "raw",
+      encoder.encode(secret),
+      { name: "HMAC", hash: "SHA-256" },
+      false,
+      ["sign", "verify"],
+    );
+
+    const signatureInput = encoder.encode(`${headerB64}.${payloadB64}`);
+    const signature = base64UrlDecode(signatureB64);
+
+    const valid = await crypto.subtle.verify("HMAC", key, signature, signatureInput);
+    if (!valid) {
+      return { ok: false, error: "invalid signature" };
+    }
+
+    // Decode header — must be HS256
+    const header = JSON.parse(new TextDecoder().decode(base64UrlDecode(headerB64)));
+    if (header.alg !== "HS256") {
+      return { ok: false, error: `unsupported algorithm: ${header.alg}` };
+    }
+
+    // Decode payload
+    const payload = JSON.parse(
+      new TextDecoder().decode(base64UrlDecode(payloadB64)),
+    ) as SyncTokenPayload;
+
+    // Check expiry
+    const now = Math.floor(Date.now() / 1000);
+    if (payload.exp && payload.exp < now) {
+      return { ok: false, error: "token expired" };
+    }
+
+    // Check iat not in the future (30s tolerance)
+    if (payload.iat && payload.iat > now + 30) {
+      return { ok: false, error: "token issued in the future" };
+    }
+
+    // JTI dedup
+    if (!payload.jti) {
+      return { ok: false, error: "missing jti" };
+    }
+    if (usedJtis.has(payload.jti)) {
+      return { ok: false, error: "token already used" };
+    }
+    // Mark as used with expiry time
+    usedJtis.set(payload.jti, (payload.exp ?? now + 900) * 1000);
+
+    // Basic validation
+    if (!payload.sub || !payload.email) {
+      return { ok: false, error: "missing sub or email" };
+    }
+    if (!Array.isArray(payload.meshes)) {
+      return { ok: false, error: "missing meshes array" };
+    }
+
+    return { ok: true, payload };
+  } catch (e) {
+    return { ok: false, error: e instanceof Error ? e.message : String(e) };
+  }
+}
+
+// --- Helpers ---
+
+function base64UrlDecode(input: string): Uint8Array {
+  // Add padding
+  let base64 = input.replace(/-/g, "+").replace(/_/g, "/");
+  while (base64.length % 4) base64 += "=";
+  const binary = atob(base64);
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.charCodeAt(i);
+  }
+  return bytes;
+}
--- a/apps/broker/src/member-api.ts
+++ b/apps/broker/src/member-api.ts
@@ -0,0 +1,284 @@
+/**
+ * Member profile REST API handlers.
+ *
+ * PATCH /mesh/:meshId/member/:memberId — update member profile
+ * GET   /mesh/:meshId/members          — list all members with online status
+ * PATCH /mesh/:meshId/settings         — update mesh settings (selfEditable)
+ *
+ * These are standalone handler functions. Route wiring happens in index.ts.
+ */
+
+import { and, eq, isNull, sql } from "drizzle-orm";
+import { db } from "./db";
+import {
+  mesh as meshTable,
+  meshMember as memberTable,
+  presence as presenceTable,
+} from "@turbostarter/db/schema/mesh";
+
+// --- Types ---
+
+export interface MemberProfileUpdate {
+  displayName?: string;
+  roleTag?: string;
+  groups?: Array<{ name: string; role?: string }>;
+  messageMode?: "push" | "inbox" | "off";
+}
+
+export interface MemberPermissionUpdate {
+  permission?: "admin" | "member"; // only admins can change this
+}
+
+export type MemberUpdateRequest = MemberProfileUpdate & MemberPermissionUpdate;
+
+interface SelfEditablePolicy {
+  displayName: boolean;
+  roleTag: boolean;
+  groups: boolean;
+  messageMode: boolean;
+}
+
+// --- Handlers ---
+
+/**
+ * Update a member's profile fields.
+ *
+ * Authorization:
+ * - If caller is the target member: check mesh.selfEditable for each field
+ * - If caller is a mesh admin: allow all fields
+ * - permission field: admin-only always
+ *
+ * Returns: { ok: true, member: {...} } or { ok: false, error: string }
+ */
+export async function updateMemberProfile(
+  meshId: string,
+  memberId: string,
+  callerMemberId: string, // from auth header or WS connection
+  updates: MemberUpdateRequest,
+): Promise<
+  | { ok: true; member: Record<string, unknown>; changes: MemberProfileUpdate }
+  | { ok: false; error: string }
+> {
+  // 1. Load mesh for selfEditable policy
+  const [m] = await db
+    .select({ id: meshTable.id, selfEditable: meshTable.selfEditable })
+    .from(meshTable)
+    .where(and(eq(meshTable.id, meshId), isNull(meshTable.archivedAt)));
+
+  if (!m) return { ok: false, error: "mesh not found" };
+
+  // 2. Load caller's member row to check permission
+  const [caller] = await db
+    .select({ id: memberTable.id, role: memberTable.role })
+    .from(memberTable)
+    .where(
+      and(
+        eq(memberTable.id, callerMemberId),
+        eq(memberTable.meshId, meshId),
+        isNull(memberTable.revokedAt),
+      ),
+    );
+
+  if (!caller) return { ok: false, error: "caller not a member of this mesh" };
+
+  const isAdmin = caller.role === "admin";
+  const isSelf = callerMemberId === memberId;
+
+  if (!isAdmin && !isSelf) {
+    return {
+      ok: false,
+      error: "not authorized — only admins or self can edit",
+    };
+  }
+
+  // 3. Check self-edit permissions for non-admin self-edits
+  const policy: SelfEditablePolicy =
+    (m.selfEditable as SelfEditablePolicy) ?? {
+      displayName: true,
+      roleTag: true,
+      groups: true,
+      messageMode: true,
+    };
+
+  const rejected: string[] = [];
+  if (!isAdmin && isSelf) {
+    if (updates.displayName !== undefined && !policy.displayName)
+      rejected.push("displayName");
+    if (updates.roleTag !== undefined && !policy.roleTag)
+      rejected.push("roleTag");
+    if (updates.groups !== undefined && !policy.groups)
+      rejected.push("groups");
+    if (updates.messageMode !== undefined && !policy.messageMode)
+      rejected.push("messageMode");
+    if (updates.permission !== undefined) rejected.push("permission");
+  }
+
+  if (rejected.length > 0) {
+    return {
+      ok: false,
+      error: `admin-managed fields: ${rejected.join(", ")}`,
+    };
+  }
+
+  // 4. Build update set
+  const set: Record<string, unknown> = {};
+  const changes: MemberProfileUpdate = {};
+
+  if (updates.displayName !== undefined) {
+    set.displayName = updates.displayName;
+    changes.displayName = updates.displayName;
+  }
+  if (updates.roleTag !== undefined) {
+    set.roleTag = updates.roleTag;
+    changes.roleTag = updates.roleTag;
+  }
+  if (updates.groups !== undefined) {
+    set.defaultGroups = updates.groups;
+    changes.groups = updates.groups;
+  }
+  if (updates.messageMode !== undefined) {
+    set.messageMode = updates.messageMode;
+    changes.messageMode = updates.messageMode;
+  }
+  if (updates.permission !== undefined && isAdmin) {
+    set.role = updates.permission;
+  }
+
+  if (Object.keys(set).length === 0) {
+    return { ok: false, error: "no fields to update" };
+  }
+
+  // 5. Update member row
+  await db.update(memberTable).set(set).where(eq(memberTable.id, memberId));
+
+  // 6. Read back the updated member
+  const [updated] = await db
+    .select()
+    .from(memberTable)
+    .where(eq(memberTable.id, memberId));
+
+  if (!updated) return { ok: false, error: "member not found after update" };
+
+  return {
+    ok: true,
+    member: {
+      id: updated.id,
+      displayName: updated.displayName,
+      roleTag: updated.roleTag,
+      groups: updated.defaultGroups,
+      messageMode: updated.messageMode,
+      permission: updated.role,
+      dashboardUserId: updated.dashboardUserId,
+      joinedAt: updated.joinedAt,
+      lastSeenAt: updated.lastSeenAt,
+    },
+    changes,
+  };
+}
+
+/**
+ * List all members of a mesh with online status.
+ */
+export async function listMeshMembers(
+  meshId: string,
+): Promise<
+  | { ok: true; members: Array<Record<string, unknown>> }
+  | { ok: false; error: string }
+> {
+  // Verify mesh exists
+  const [m] = await db
+    .select({ id: meshTable.id })
+    .from(meshTable)
+    .where(and(eq(meshTable.id, meshId), isNull(meshTable.archivedAt)));
+
+  if (!m) return { ok: false, error: "mesh not found" };
+
+  // Get all non-revoked members
+  const members = await db
+    .select()
+    .from(memberTable)
+    .where(
+      and(eq(memberTable.meshId, meshId), isNull(memberTable.revokedAt)),
+    );
+
+  // Early return for empty member list (avoids invalid SQL IN clause)
+  if (members.length === 0) {
+    return { ok: true, members: [] };
+  }
+
+  // Get active presences for online status
+  const activePresences = await db
+    .select({
+      memberId: presenceTable.memberId,
+      count: sql<number>`count(*)::int`,
+    })
+    .from(presenceTable)
+    .where(
+      and(
+        isNull(presenceTable.disconnectedAt),
+        sql`${presenceTable.memberId} IN (${sql.join(
+          members.map((m) => sql`${m.id}`),
+          sql`, `,
+        )})`,
+      ),
+    )
+    .groupBy(presenceTable.memberId);
+
+  const onlineMap = new Map(
+    activePresences.map((p) => [p.memberId, p.count]),
+  );
+
+  return {
+    ok: true,
+    members: members.map((member) => ({
+      id: member.id,
+      displayName: member.displayName,
+      roleTag: member.roleTag,
+      groups: member.defaultGroups,
+      messageMode: member.messageMode,
+      permission: member.role,
+      dashboardUserId: member.dashboardUserId,
+      joinedAt: member.joinedAt?.toISOString(),
+      lastSeenAt: member.lastSeenAt?.toISOString(),
+      online: onlineMap.has(member.id),
+      sessionCount: onlineMap.get(member.id) ?? 0,
+    })),
+  };
+}
+
+/**
+ * Update mesh settings (currently: selfEditable policy).
+ * Admin-only.
+ */
+export async function updateMeshSettings(
+  meshId: string,
+  callerMemberId: string,
+  settings: { selfEditable?: SelfEditablePolicy },
+): Promise<{ ok: true } | { ok: false; error: string }> {
+  // Check caller is admin
+  const [caller] = await db
+    .select({ role: memberTable.role })
+    .from(memberTable)
+    .where(
+      and(
+        eq(memberTable.id, callerMemberId),
+        eq(memberTable.meshId, meshId),
+        isNull(memberTable.revokedAt),
+      ),
+    );
+
+  if (!caller || caller.role !== "admin") {
+    return { ok: false, error: "admin access required" };
+  }
+
+  const set: Record<string, unknown> = {};
+  if (settings.selfEditable) set.selfEditable = settings.selfEditable;
+
+  if (Object.keys(set).length === 0) {
+    return { ok: false, error: "no settings to update" };
+  }
+
+  await db.update(meshTable).set(set).where(eq(meshTable.id, meshId));
+
+  return { ok: true };
+}
--- a/apps/broker/src/minio.ts
+++ b/apps/broker/src/minio.ts
@@ -0,0 +1,28 @@
+/**
+ * MinIO client for file storage.
+ *
+ * Each mesh gets its own bucket (mesh-{meshId}). Files are stored under
+ * a key path that encodes persistence and origin:
+ *   - persistent: shared/{fileId}/{originalName}
+ *   - ephemeral:  ephemeral/{YYYY-MM-DD}/{fileId}/{originalName}
+ */
+
+import { Client } from "minio";
+import { env } from "./env";
+
+export const minioClient = new Client({
+  endPoint: env.MINIO_ENDPOINT.split(":")[0]!,
+  port: parseInt(env.MINIO_ENDPOINT.split(":")[1] || "9000"),
+  useSSL: env.MINIO_USE_SSL,
+  accessKey: env.MINIO_ACCESS_KEY,
+  secretKey: env.MINIO_SECRET_KEY,
+});
+
+export async function ensureBucket(name: string): Promise<void> {
+  const exists = await minioClient.bucketExists(name);
+  if (!exists) await minioClient.makeBucket(name);
+}
+
+export function meshBucketName(meshId: string): string {
+  return `mesh-${meshId.toLowerCase().replace(/[^a-z0-9-]/g, "-")}`;
+}
--- a/apps/broker/src/neo4j-client.ts
+++ b/apps/broker/src/neo4j-client.ts
@@ -0,0 +1,22 @@
+import neo4j from "neo4j-driver";
+import { env } from "./env";
+
+export const neo4jDriver = neo4j.driver(
+  env.NEO4J_URL,
+  neo4j.auth.basic(env.NEO4J_USER, env.NEO4J_PASSWORD),
+);
+
+export function meshDbName(meshId: string): string {
+  return `mesh_${meshId.toLowerCase().replace(/[^a-z0-9]/g, "")}`;
+}
+
+export async function ensureDatabase(name: string): Promise<void> {
+  const session = neo4jDriver.session({ database: "system" });
+  try {
+    await session.run(`CREATE DATABASE $name IF NOT EXISTS`, { name });
+  } catch {
+    /* may not support multi-db in community edition — fall back to default */
+  } finally {
+    await session.close();
+  }
+}
--- a/apps/broker/src/permissions.ts
+++ b/apps/broker/src/permissions.ts
@@ -0,0 +1,112 @@
+/**
+ * Granular permission checks for mesh operations.
+ *
+ * If a meshPermission row exists for the member, use it.
+ * Otherwise, derive defaults from the member's role.
+ */
+
+import { and, eq } from "drizzle-orm";
+import { db } from "./db";
+import { meshPermission, meshMember, mesh, DEFAULT_PERMISSIONS } from "@turbostarter/db/schema/mesh";
+import type { PermissionKey } from "@turbostarter/db/schema/mesh";
+
+export interface ResolvedPermissions {
+  canInvite: boolean;
+  canDeployMcp: boolean;
+  canManageFiles: boolean;
+  canManageVault: boolean;
+  canManageWatches: boolean;
+  canManageWebhooks: boolean;
+  canWriteState: boolean;
+  canSend: boolean;
+  canUseTools: boolean;
+  canDeleteMesh: boolean;
+  canManagePermissions: boolean;
+}
+
+/**
+ * Get effective permissions for a member in a mesh.
+ * Checks for explicit permission row, falls back to role defaults.
+ */
+export async function getPermissions(meshId: string, memberId: string): Promise<ResolvedPermissions> {
+  // Get the explicit permission row if it exists
+  const [perm] = await db.select().from(meshPermission)
+    .where(and(eq(meshPermission.meshId, meshId), eq(meshPermission.memberId, memberId)))
+    .limit(1);
+
+  if (perm) {
+    return {
+      canInvite: perm.canInvite,
+      canDeployMcp: perm.canDeployMcp,
+      canManageFiles: perm.canManageFiles,
+      canManageVault: perm.canManageVault,
+      canManageWatches: perm.canManageWatches,
+      canManageWebhooks: perm.canManageWebhooks,
+      canWriteState: perm.canWriteState,
+      canSend: perm.canSend,
+      canUseTools: perm.canUseTools,
+      canDeleteMesh: perm.canDeleteMesh,
+      canManagePermissions: perm.canManagePermissions,
+    };
+  }
+
+  // Fall back to role-based defaults
+  const [member] = await db.select().from(meshMember)
+    .where(eq(meshMember.id, memberId))
+    .limit(1);
+
+  if (!member) return DEFAULT_PERMISSIONS.member;
+
+  // Check if member is mesh owner
+  const [m] = await db.select().from(mesh)
+    .where(eq(mesh.id, meshId))
+    .limit(1);
+
+  if (m && m.ownerUserId && member.userId === m.ownerUserId) {
+    return DEFAULT_PERMISSIONS.owner;
+  }
+
+  return DEFAULT_PERMISSIONS[member.role] ?? DEFAULT_PERMISSIONS.member;
+}
+
+/**
+ * Check a single permission for a member.
+ * Returns true if allowed, false if denied.
+ */
+export async function checkPermission(
+  meshId: string,
+  memberId: string,
+  permission: PermissionKey,
+): Promise<boolean> {
+  const perms = await getPermissions(meshId, memberId);
+  return perms[permission];
+}
+
+/**
+ * Set explicit permissions for a member (partial update).
+ * Creates the row if it doesn't exist.
+ */
+export async function setPermissions(
+  meshId: string,
+  memberId: string,
+  updates: Partial<ResolvedPermissions>,
+): Promise<void> {
+  const [existing] = await db.select().from(meshPermission)
+    .where(and(eq(meshPermission.meshId, meshId), eq(meshPermission.memberId, memberId)))
+    .limit(1);
+
+  if (existing) {
+    await db.update(meshPermission)
+      .set({ ...updates, updatedAt: new Date() })
+      .where(eq(meshPermission.id, existing.id));
+  } else {
+    // Get role defaults first, then overlay updates
+    const defaults = await getPermissions(meshId, memberId);
+    await db.insert(meshPermission).values({
+      meshId,
+      memberId,
+      ...defaults,
+      ...updates,
+    });
+  }
+}
--- a/apps/broker/src/qdrant.ts
+++ b/apps/broker/src/qdrant.ts
@@ -0,0 +1,24 @@
+import { QdrantClient } from "@qdrant/js-client-rest";
+import { env } from "./env";
+
+export const qdrant = new QdrantClient({ url: env.QDRANT_URL });
+
+export function meshCollectionName(
+  meshId: string,
+  collection: string,
+): string {
+  return `mesh_${meshId}_${collection}`.toLowerCase().replace(/[^a-z0-9_]/g, "_");
+}
+
+export async function ensureCollection(
+  name: string,
+  vectorSize = 1536,
+): Promise<void> {
+  try {
+    await qdrant.getCollection(name);
+  } catch {
+    await qdrant.createCollection(name, {
+      vectors: { size: vectorSize, distance: "Cosine" },
+    });
+  }
+}
--- a/apps/broker/src/service-manager.ts
+++ b/apps/broker/src/service-manager.ts
@@ -0,0 +1,788 @@
+/**
+ * Service Manager — lifecycle management for mesh-deployed MCP servers.
+ *
+ * Each deployed MCP server runs as a child process with its own stdio pipe.
+ * The manager spawns, monitors, restarts, and routes tool calls to them.
+ *
+ * In production: child processes run inside a Docker container (one per mesh).
+ * In dev: child processes run directly on the broker host.
+ */
+
+import { spawn, type ChildProcess } from "node:child_process";
+import { createInterface } from "node:readline";
+import { existsSync } from "node:fs";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { log } from "./logger";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/** MCP tool definition returned by tools/list. */
+export interface ToolDef {
+  name: string;
+  description: string;
+  inputSchema: Record<string, unknown>;
+}
+
+/** Per-service deploy-time configuration. */
+export interface ServiceConfig {
+  env?: Record<string, string>;
+  memory_mb?: number;
+  cpus?: number;
+  network_allow?: string[];
+  runtime?: "node" | "python" | "bun";
+}
+
+/** Observable lifecycle states. */
+export type ServiceStatus =
+  | "building"
+  | "installing"
+  | "running"
+  | "stopped"
+  | "failed"
+  | "crashed"
+  | "restarting";
+
+/** Internal bookkeeping for a spawned service. */
+interface ManagedService {
+  name: string;
+  meshId: string;
+  process: ChildProcess | null;
+  tools: ToolDef[];
+  status: ServiceStatus;
+  config: ServiceConfig;
+  sourcePath: string;
+  runtime: "node" | "python" | "bun";
+  restartCount: number;
+  maxRestarts: number;
+  healthFailures: number;
+  logBuffer: string[]; // ring buffer, max LOG_BUFFER_SIZE
+  pendingCalls: Map<
+    string,
+    {
+      resolve: (result: { result?: unknown; error?: string }) => void;
+      timer: NodeJS.Timeout;
+    }
+  >;
+  pid?: number;
+  startedAt?: Date;
+}
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const LOG_BUFFER_SIZE = 1000;
+const HEALTH_INTERVAL_MS = 30_000;
+const HEALTH_TIMEOUT_MS = 5_000;
+const MAX_HEALTH_FAILURES = 3;
+const DEFAULT_MAX_RESTARTS = 5;
+const CALL_TIMEOUT_MS = 25_000;
+const SERVICES_BASE_DIR =
+  process.env.CLAUDEMESH_SERVICES_DIR ?? "/var/claudemesh/services";
+
+// ---------------------------------------------------------------------------
+// Service registry
+// ---------------------------------------------------------------------------
+
+const services = new Map<string, ManagedService>(); // keyed by "meshId:serviceName"
+let healthTimer: NodeJS.Timer | null = null;
+
+function serviceKey(meshId: string, name: string): string {
+  return `${meshId}:${name}`;
+}
+
+/** Validate service name: alphanumeric, hyphens, underscores only. No path traversal. */
+const SAFE_NAME_RE = /^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/;
+
+export function validateServiceName(name: string): string | null {
+  if (!SAFE_NAME_RE.test(name)) {
+    return "service name must be 1-64 chars, alphanumeric/hyphens/underscores, starting with alphanumeric";
+  }
+  if (name.includes("..") || name.includes("/") || name.includes("\\")) {
+    return "service name must not contain path separators";
+  }
+  return null; // valid
+}
+
+// ---------------------------------------------------------------------------
+// Runtime detection
+// ---------------------------------------------------------------------------
+
+/**
+ * Detect the runtime for a service based on its source directory contents.
+ *
+ * Priority: bun (lockfile/config) > node (package.json) > python
+ * (pyproject.toml / requirements.txt). Falls back to node.
+ */
+export function detectRuntime(sourcePath: string): "node" | "python" | "bun" {
+  if (
+    existsSync(join(sourcePath, "bun.lockb")) ||
+    existsSync(join(sourcePath, "bunfig.toml"))
+  ) {
+    return "bun";
+  }
+  if (existsSync(join(sourcePath, "package.json"))) {
+    return "node";
+  }
+  if (
+    existsSync(join(sourcePath, "pyproject.toml")) ||
+    existsSync(join(sourcePath, "requirements.txt"))
+  ) {
+    return "python";
+  }
+  return "node"; // default
+}
+
+// ---------------------------------------------------------------------------
+// Entry point detection
+// ---------------------------------------------------------------------------
+
+function detectEntry(
+  sourcePath: string,
+  runtime: "node" | "python" | "bun",
+): { command: string; args: string[] } {
+  if (runtime === "python") {
+    if (existsSync(join(sourcePath, "requirements.txt"))) {
+      for (const entry of [
+        "server.py",
+        "src/server.py",
+        "main.py",
+        "src/main.py",
+      ]) {
+        if (existsSync(join(sourcePath, entry))) {
+          return { command: "python", args: [entry] };
+        }
+      }
+    }
+    if (existsSync(join(sourcePath, "pyproject.toml"))) {
+      return { command: "python", args: ["-m", "server"] };
+    }
+    return { command: "python", args: ["server.py"] };
+  }
+
+  // Node / Bun
+  const cmd = runtime === "bun" ? "bun" : "node";
+  if (existsSync(join(sourcePath, "package.json"))) {
+    try {
+      const pkg = JSON.parse(
+        readFileSync(join(sourcePath, "package.json"), "utf-8"),
+      );
+      if (pkg.main) return { command: cmd, args: [pkg.main] };
+      if (pkg.bin) {
+        const bin =
+          typeof pkg.bin === "string"
+            ? pkg.bin
+            : (Object.values(pkg.bin)[0] as string);
+        if (bin) return { command: cmd, args: [bin] };
+      }
+    } catch {
+      /* ignore parse errors */
+    }
+  }
+
+  // Common entry points
+  for (const entry of [
+    "dist/index.js",
+    "src/index.js",
+    "src/index.ts",
+    "index.js",
+  ]) {
+    if (existsSync(join(sourcePath, entry))) {
+      return { command: cmd, args: [entry] };
+    }
+  }
+
+  return { command: cmd, args: ["src/index.js"] };
+}
+
+// ---------------------------------------------------------------------------
+// Install dependencies
+// ---------------------------------------------------------------------------
+
+/**
+ * Install dependencies for a service. Resolves on success, rejects with
+ * the tail of stderr on failure.
+ */
+export async function installDeps(
+  sourcePath: string,
+  runtime: "node" | "python" | "bun",
+): Promise<void> {
+  return new Promise((resolve, reject) => {
+    let cmd: string;
+    let args: string[];
+
+    if (runtime === "python") {
+      if (existsSync(join(sourcePath, "requirements.txt"))) {
+        cmd = "pip";
+        args = ["install", "--no-cache-dir", "-r", "requirements.txt"];
+      } else {
+        cmd = "pip";
+        args = ["install", "--no-cache-dir", "."];
+      }
+    } else if (runtime === "bun") {
+      cmd = "bun";
+      args = ["install"];
+    } else {
+      cmd = "npm";
+      args = ["install", "--production", "--legacy-peer-deps"];
+    }
+
+    const child = spawn(cmd, args, {
+      cwd: sourcePath,
+      stdio: ["ignore", "pipe", "pipe"],
+    });
+
+    let stderr = "";
+    child.stderr?.on("data", (d: Buffer) => {
+      stderr += d.toString();
+    });
+    child.on("exit", (code) => {
+      if (code === 0) resolve();
+      else
+        reject(
+          new Error(
+            `${cmd} install failed (exit ${code}): ${stderr.slice(-500)}`,
+          ),
+        );
+    });
+    child.on("error", reject);
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Log ring buffer
+// ---------------------------------------------------------------------------
+
+function appendLog(svc: ManagedService, line: string): void {
+  svc.logBuffer.push(`${new Date().toISOString()} ${line}`);
+  if (svc.logBuffer.length > LOG_BUFFER_SIZE) {
+    svc.logBuffer.shift();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// MCP JSON-RPC helpers
+// ---------------------------------------------------------------------------
+
+let callIdCounter = 0;
+
+function sendMcpRequest(
+  svc: ManagedService,
+  method: string,
+  params?: unknown,
+): Promise<{ result?: unknown; error?: string }> {
+  return new Promise((resolve) => {
+    if (!svc.process || !svc.process.stdin?.writable) {
+      resolve({ error: "service not running" });
+      return;
+    }
+
+    const id = `call_${++callIdCounter}`;
+    const request = {
+      jsonrpc: "2.0",
+      id,
+      method,
+      ...(params ? { params } : {}),
+    };
+
+    const timer = setTimeout(() => {
+      svc.pendingCalls.delete(id);
+      resolve({ error: `tool call timed out after ${CALL_TIMEOUT_MS}ms` });
+    }, CALL_TIMEOUT_MS);
+
+    svc.pendingCalls.set(id, { resolve, timer });
+
+    try {
+      svc.process.stdin!.write(JSON.stringify(request) + "\n");
+    } catch (e) {
+      clearTimeout(timer);
+      svc.pendingCalls.delete(id);
+      resolve({
+        error: `write failed: ${e instanceof Error ? e.message : String(e)}`,
+      });
+    }
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Initialize MCP server (handshake + tool discovery)
+// ---------------------------------------------------------------------------
+
+async function initializeMcp(svc: ManagedService): Promise<ToolDef[]> {
+  // MCP initialize handshake
+  const initResult = await sendMcpRequest(svc, "initialize", {
+    protocolVersion: "2024-11-05",
+    capabilities: {},
+    clientInfo: { name: "claudemesh-runner", version: "0.1.0" },
+  });
+
+  if (initResult.error) {
+    throw new Error(`MCP initialize failed: ${initResult.error}`);
+  }
+
+  // Send initialized notification (no response expected)
+  if (svc.process?.stdin?.writable) {
+    svc.process.stdin.write(
+      JSON.stringify({
+        jsonrpc: "2.0",
+        method: "notifications/initialized",
+      }) + "\n",
+    );
+  }
+
+  // Fetch tool list
+  const toolsResult = await sendMcpRequest(svc, "tools/list", {});
+  if (toolsResult.error) {
+    throw new Error(`tools/list failed: ${toolsResult.error}`);
+  }
+
+  const result = toolsResult.result as { tools?: ToolDef[] } | undefined;
+  return result?.tools ?? [];
+}
+
+// ---------------------------------------------------------------------------
+// Spawn an MCP server child process
+// ---------------------------------------------------------------------------
+
+function spawnService(svc: ManagedService): void {
+  const { command, args } = detectEntry(svc.sourcePath, svc.runtime);
+
+  const env: Record<string, string> = {
+    ...(process.env as Record<string, string>),
+    ...(svc.config.env ?? {}),
+    NODE_ENV: "production",
+  };
+
+  const child = spawn(command, args, {
+    cwd: svc.sourcePath,
+    stdio: ["pipe", "pipe", "pipe"],
+    env,
+  });
+
+  svc.process = child;
+  svc.pid = child.pid;
+  svc.startedAt = new Date();
+  svc.status = "running";
+  svc.healthFailures = 0;
+
+  // Read MCP JSON-RPC responses from stdout
+  const rl = createInterface({ input: child.stdout! });
+  rl.on("line", (line) => {
+    try {
+      const msg = JSON.parse(line);
+      if (msg.id && svc.pendingCalls.has(String(msg.id))) {
+        const pending = svc.pendingCalls.get(String(msg.id))!;
+        clearTimeout(pending.timer);
+        svc.pendingCalls.delete(String(msg.id));
+        if (msg.error) {
+          pending.resolve({
+            error: msg.error.message ?? JSON.stringify(msg.error),
+          });
+        } else {
+          pending.resolve({ result: msg.result });
+        }
+      }
+    } catch {
+      // Not JSON — treat as log output
+      appendLog(svc, `[stdout] ${line}`);
+    }
+  });
+
+  // Capture stderr as logs
+  const stderrRl = createInterface({ input: child.stderr! });
+  stderrRl.on("line", (line) => {
+    appendLog(svc, `[stderr] ${line}`);
+  });
+
+  child.on("exit", (code, signal) => {
+    log.warn("service exited", {
+      service: svc.name,
+      mesh_id: svc.meshId,
+      code,
+      signal,
+      restarts: svc.restartCount,
+    });
+
+    // Reject all pending calls
+    for (const [, pending] of svc.pendingCalls) {
+      clearTimeout(pending.timer);
+      pending.resolve({ error: "service crashed" });
+    }
+    svc.pendingCalls.clear();
+    svc.process = null;
+    svc.pid = undefined;
+
+    // Auto-restart if under limit
+    if (svc.status === "running" && svc.restartCount < svc.maxRestarts) {
+      svc.restartCount++;
+      svc.status = "restarting";
+      log.info("auto-restarting service", {
+        service: svc.name,
+        attempt: svc.restartCount,
+      });
+      setTimeout(() => spawnService(svc), 1000 * svc.restartCount); // backoff
+    } else if (svc.status === "running") {
+      svc.status = "crashed";
+      log.error("service max restarts exceeded", {
+        service: svc.name,
+        restarts: svc.restartCount,
+      });
+    }
+  });
+
+  child.on("error", (err) => {
+    log.error("service spawn error", {
+      service: svc.name,
+      error: err.message,
+    });
+    svc.status = "failed";
+  });
+
+  log.info("service spawned", {
+    service: svc.name,
+    mesh_id: svc.meshId,
+    pid: child.pid,
+    command,
+    args,
+    runtime: svc.runtime,
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Deploy (or redeploy) an MCP server.
+ *
+ * Installs dependencies, spawns the child process, runs the MCP
+ * initialize handshake, and returns the discovered tool list.
+ */
+export async function deploy(opts: {
+  meshId: string;
+  name: string;
+  sourcePath: string;
+  config: ServiceConfig;
+  resolvedEnv?: Record<string, string>;
+}): Promise<{ tools: ToolDef[]; status: ServiceStatus }> {
+  const key = serviceKey(opts.meshId, opts.name);
+
+  // Kill existing if redeploying
+  const existing = services.get(key);
+  if (existing?.process) {
+    existing.process.kill("SIGTERM");
+    await new Promise((r) => setTimeout(r, 1000));
+  }
+
+  const runtime = opts.config.runtime ?? detectRuntime(opts.sourcePath);
+
+  const svc: ManagedService = {
+    name: opts.name,
+    meshId: opts.meshId,
+    process: null,
+    tools: [],
+    status: "installing",
+    config: {
+      ...opts.config,
+      env: { ...(opts.config.env ?? {}), ...(opts.resolvedEnv ?? {}) },
+    },
+    sourcePath: opts.sourcePath,
+    runtime,
+    restartCount: 0,
+    maxRestarts: DEFAULT_MAX_RESTARTS,
+    healthFailures: 0,
+    logBuffer: [],
+    pendingCalls: new Map(),
+  };
+
+  services.set(key, svc);
+
+  // Install dependencies
+  try {
+    await installDeps(opts.sourcePath, runtime);
+  } catch (e) {
+    svc.status = "failed";
+    appendLog(
+      svc,
+      `Install failed: ${e instanceof Error ? e.message : String(e)}`,
+    );
+    throw e;
+  }
+
+  // Spawn and initialize
+  spawnService(svc);
+
+  // Wait a moment for the process to start
+  await new Promise((r) => setTimeout(r, 500));
+
+  // Get tool list via MCP initialize handshake
+  try {
+    svc.tools = await initializeMcp(svc);
+    log.info("service deployed", {
+      service: opts.name,
+      mesh_id: opts.meshId,
+      tools: svc.tools.length,
+      runtime,
+    });
+  } catch (e) {
+    svc.status = "failed";
+    appendLog(
+      svc,
+      `MCP init failed: ${e instanceof Error ? e.message : String(e)}`,
+    );
+    throw e;
+  }
+
+  return { tools: svc.tools, status: svc.status };
+}
+
+/**
+ * Undeploy a running service. Sends SIGTERM, waits for graceful exit
+ * (up to 10 s), then SIGKILL. All pending tool calls are rejected.
+ */
+export async function undeploy(meshId: string, name: string): Promise<void> {
+  const key = serviceKey(meshId, name);
+  const svc = services.get(key);
+  if (!svc) return;
+
+  svc.status = "stopped";
+  if (svc.process) {
+    svc.process.kill("SIGTERM");
+    await new Promise<void>((resolve) => {
+      const timeout = setTimeout(() => {
+        svc.process?.kill("SIGKILL");
+        resolve();
+      }, 10_000);
+      svc.process?.on("exit", () => {
+        clearTimeout(timeout);
+        resolve();
+      });
+    });
+  }
+
+  // Reject pending calls
+  for (const [, pending] of svc.pendingCalls) {
+    clearTimeout(pending.timer);
+    pending.resolve({ error: "service undeployed" });
+  }
+
+  services.delete(key);
+  log.info("service undeployed", { service: name, mesh_id: meshId });
+}
+
+/**
+ * Route a tool call to the named service. Returns the MCP response
+ * payload or an error string.
+ */
+export async function callTool(
+  meshId: string,
+  serverName: string,
+  toolName: string,
+  args: Record<string, unknown>,
+): Promise<{ result?: unknown; error?: string }> {
+  const key = serviceKey(meshId, serverName);
+  const svc = services.get(key);
+  if (!svc) return { error: `service "${serverName}" not found` };
+  if (svc.status !== "running")
+    return { error: `service "${serverName}" is ${svc.status}` };
+  if (!svc.process)
+    return { error: `service "${serverName}" has no running process` };
+
+  return sendMcpRequest(svc, "tools/call", { name: toolName, arguments: args });
+}
+
+/**
+ * Return the last N log lines for a service (from its ring buffer).
+ */
+export function getLogs(meshId: string, name: string, lines = 50): string[] {
+  const key = serviceKey(meshId, name);
+  const svc = services.get(key);
+  if (!svc) return [];
+  return svc.logBuffer.slice(-Math.min(lines, LOG_BUFFER_SIZE));
+}
+
+/**
+ * Return current status, PID, restart count, tool list, and uptime
+ * for a single service. Returns null if the service doesn't exist.
+ */
+export function getStatus(
+  meshId: string,
+  name: string,
+): {
+  status: ServiceStatus;
+  pid?: number;
+  restartCount: number;
+  tools: ToolDef[];
+  startedAt?: string;
+} | null {
+  const key = serviceKey(meshId, name);
+  const svc = services.get(key);
+  if (!svc) return null;
+  return {
+    status: svc.status,
+    pid: svc.pid,
+    restartCount: svc.restartCount,
+    tools: svc.tools,
+    startedAt: svc.startedAt?.toISOString(),
+  };
+}
+
+/**
+ * Return the tool definitions for a service, or an empty array if the
+ * service doesn't exist.
+ */
+export function getTools(meshId: string, name: string): ToolDef[] {
+  const key = serviceKey(meshId, name);
+  const svc = services.get(key);
+  return svc?.tools ?? [];
+}
+
+/**
+ * List all services belonging to a mesh with summary info.
+ */
+export function listServices(
+  meshId: string,
+): Array<{
+  name: string;
+  status: ServiceStatus;
+  toolCount: number;
+  runtime: string;
+  restartCount: number;
+  pid?: number;
+}> {
+  const result: Array<{
+    name: string;
+    status: ServiceStatus;
+    toolCount: number;
+    runtime: string;
+    restartCount: number;
+    pid?: number;
+  }> = [];
+  for (const [key, svc] of services) {
+    if (!key.startsWith(`${meshId}:`)) continue;
+    result.push({
+      name: svc.name,
+      status: svc.status,
+      toolCount: svc.tools.length,
+      runtime: svc.runtime,
+      restartCount: svc.restartCount,
+      pid: svc.pid,
+    });
+  }
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Health check loop
+// ---------------------------------------------------------------------------
+
+async function healthCheckAll(): Promise<void> {
+  for (const [, svc] of services) {
+    if (svc.status !== "running" || !svc.process) continue;
+
+    const result = await sendMcpRequest(svc, "ping", {});
+    if (result.error) {
+      svc.healthFailures++;
+      log.warn("health check failed", {
+        service: svc.name,
+        failures: svc.healthFailures,
+        error: result.error,
+      });
+      if (svc.healthFailures >= MAX_HEALTH_FAILURES) {
+        log.error("health check threshold exceeded, restarting", {
+          service: svc.name,
+        });
+        svc.process.kill("SIGTERM");
+        // exit handler will trigger auto-restart
+      }
+    } else {
+      svc.healthFailures = 0;
+    }
+  }
+}
+
+/** Start the periodic health check loop (30 s interval). No-op if already running. */
+export function startHealthChecks(): void {
+  if (healthTimer) return;
+  healthTimer = setInterval(healthCheckAll, HEALTH_INTERVAL_MS);
+}
+
+/** Stop the periodic health check loop. */
+export function stopHealthChecks(): void {
+  if (healthTimer) {
+    clearInterval(healthTimer);
+    healthTimer = null;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Restore all services on broker boot
+// ---------------------------------------------------------------------------
+
+/**
+ * Re-deploy every persisted service record. Called once at broker startup
+ * to bring services back after a restart. Failures are logged but don't
+ * prevent other services from restoring.
+ */
+export async function restoreAll(
+  getServiceRecords: () => Promise<
+    Array<{
+      meshId: string;
+      name: string;
+      sourcePath: string;
+      config: ServiceConfig;
+      resolvedEnv?: Record<string, string>;
+    }>
+  >,
+): Promise<void> {
+  const records = await getServiceRecords();
+  log.info("restoring services", { count: records.length });
+
+  for (const record of records) {
+    try {
+      await deploy({
+        meshId: record.meshId,
+        name: record.name,
+        sourcePath: record.sourcePath,
+        config: record.config,
+        resolvedEnv: record.resolvedEnv,
+      });
+      log.info("service restored", {
+        service: record.name,
+        mesh_id: record.meshId,
+      });
+    } catch (e) {
+      log.error("service restore failed", {
+        service: record.name,
+        mesh_id: record.meshId,
+        error: e instanceof Error ? e.message : String(e),
+      });
+    }
+  }
+
+  startHealthChecks();
+}
+
+// ---------------------------------------------------------------------------
+// Shutdown
+// ---------------------------------------------------------------------------
+
+/**
+ * Gracefully shut down all running services. Stops health checks, sends
+ * SIGTERM to every child, waits for exit, then clears the registry.
+ */
+export async function shutdownAll(): Promise<void> {
+  stopHealthChecks();
+  const promises: Promise<void>[] = [];
+  for (const [, svc] of services) {
+    if (svc.process) {
+      svc.status = "stopped";
+      promises.push(undeploy(svc.meshId, svc.name));
+    }
+  }
+  await Promise.allSettled(promises);
+  services.clear();
+}
--- a/apps/broker/src/telegram-ai.ts
+++ b/apps/broker/src/telegram-ai.ts
@@ -0,0 +1,424 @@
+/**
+ * Claude-powered natural language processing for Telegram mesh interactions.
+ *
+ * Uses Claude Haiku 4.5 with tool calling to interpret user intent
+ * and map to mesh operations. Destructive/social actions require
+ * confirmation via Telegram inline buttons.
+ */
+
+import Anthropic from "@anthropic-ai/sdk";
+import { env } from "./env";
+import { log } from "./logger";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export interface AiTool {
+  name: string;
+  description: string;
+  input_schema: Record<string, unknown>;
+}
+
+export interface AiToolCall {
+  name: string;
+  input: Record<string, unknown>;
+}
+
+export interface AiResult {
+  type: "text" | "tool_call" | "error";
+  text?: string;
+  toolCall?: AiToolCall;
+  requiresConfirmation?: boolean;
+}
+
+// ---------------------------------------------------------------------------
+// Tools definition
+// ---------------------------------------------------------------------------
+
+const TOOLS: AiTool[] = [
+  {
+    name: "send_message",
+    description: "Send a message to a peer in the mesh. Use when the user wants to tell, ask, or communicate something to a specific person or group.",
+    input_schema: {
+      type: "object",
+      properties: {
+        to: { type: "string", description: "Peer name, @group, or * for broadcast" },
+        message: { type: "string", description: "The message content" },
+        priority: { type: "string", enum: ["now", "next", "low"], description: "Delivery priority (default: next)" },
+      },
+      required: ["to", "message"],
+    },
+  },
+  {
+    name: "list_peers",
+    description: "List all connected peers in the mesh. Use when user asks who's online, who's available, or what everyone is doing.",
+    input_schema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "list_meshes",
+    description: "List all meshes this Telegram chat is connected to. Use when user asks about their meshes, which meshes are available, or wants to see their workspace list.",
+    input_schema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "remember",
+    description: "Store a memory/note in the mesh's shared knowledge. Use when user wants to save information for later.",
+    input_schema: {
+      type: "object",
+      properties: {
+        content: { type: "string", description: "The content to remember" },
+        tags: { type: "array", items: { type: "string" }, description: "Tags for categorization" },
+      },
+      required: ["content"],
+    },
+  },
+  {
+    name: "recall",
+    description: "Search the mesh's shared memory. Use when user asks about something that was previously stored.",
+    input_schema: {
+      type: "object",
+      properties: {
+        query: { type: "string", description: "Search query" },
+      },
+      required: ["query"],
+    },
+  },
+  {
+    name: "get_state",
+    description: "Read a shared state value. Use when user asks about a specific key/variable.",
+    input_schema: {
+      type: "object",
+      properties: {
+        key: { type: "string", description: "State key to read" },
+      },
+      required: ["key"],
+    },
+  },
+  {
+    name: "set_state",
+    description: "Write a shared state value. Use when user wants to set/update a key.",
+    input_schema: {
+      type: "object",
+      properties: {
+        key: { type: "string", description: "State key" },
+        value: { type: "string", description: "Value to set" },
+      },
+      required: ["key", "value"],
+    },
+  },
+  {
+    name: "create_mesh",
+    description: "Create a new mesh. Use when user wants to create a new workspace/mesh.",
+    input_schema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "Mesh name" },
+      },
+      required: ["name"],
+    },
+  },
+  {
+    name: "share_mesh",
+    description: "Generate an invite link or send an invite email. Use when user wants to invite someone to the mesh.",
+    input_schema: {
+      type: "object",
+      properties: {
+        email: { type: "string", description: "Email to invite (optional — if omitted, generates a link)" },
+      },
+    },
+  },
+  {
+    name: "list_services",
+    description: "List all deployed MCP services and skills in the mesh. Use when user asks about available tools, services, MCPs, skills, or capabilities.",
+    input_schema: {
+      type: "object",
+      properties: {},
+    },
+  },
+  {
+    name: "list_commands",
+    description: "Show available Telegram bot commands. Use when user asks what commands are available, what they can do, or asks for help.",
+    input_schema: {
+      type: "object",
+      properties: {},
+    },
+  },
+];
+
+// Actions that need user confirmation before executing
+const CONFIRM_ACTIONS = new Set([
+  "send_message",
+  "create_mesh",
+  "share_mesh",
+  "set_state",
+  "remember",
+]);
+
+const SYSTEM_PROMPT = `You are the claudemesh Telegram assistant. You help users interact with their claudemesh peer network using natural language.
+
+You have access to tools for mesh operations. When the user's intent maps to a tool, use it. When it's a general question or conversation, respond directly.
+
+IMPORTANT: Always respond in the same language the user writes in. If they write in Spanish, respond in Spanish. If English, respond in English.
+
+Key concepts:
+- A MESH is a workspace/group (like "flexicar", "alexis-mou"). This Telegram chat can be connected to multiple meshes.
+- A PEER is a person/agent connected to a mesh (like "Nedas", "Mou").
+- When user says "send to <mesh-name>", they mean BROADCAST to all peers in that mesh. Use send_message with to="*" — the system will route to the correct mesh.
+- When user says "send to <person-name>", they mean a direct message to that peer.
+
+Rules:
+- Be concise — Telegram messages should be short
+- When sending messages to peers, preserve the user's tone and intent
+- If the target looks like a mesh name (matches one from context), broadcast to it
+- Never fabricate peer names — use list_peers to find real names
+- Default to the first connected mesh if not specified`;
+
+// ---------------------------------------------------------------------------
+// AI Engine
+// ---------------------------------------------------------------------------
+
+let client: Anthropic | null = null;
+
+function getClient(): Anthropic {
+  if (!client) {
+    const apiKey = env.ANTHROPIC_API_KEY;
+    if (!apiKey) throw new Error("ANTHROPIC_API_KEY not configured");
+    client = new Anthropic({ apiKey });
+  }
+  return client;
+}
+
+// ---------------------------------------------------------------------------
+// Conversation history (per chat, rolling window)
+// ---------------------------------------------------------------------------
+
+const MAX_HISTORY = 10;
+const HISTORY_TTL_MS = 30 * 60 * 1000; // 30 min
+
+interface HistoryEntry {
+  role: "user" | "assistant";
+  content: string;
+  ts: number;
+}
+
+const chatHistory = new Map<number, HistoryEntry[]>();
+
+// Clean stale histories every 10 min
+setInterval(() => {
+  const now = Date.now();
+  for (const [chatId, entries] of chatHistory) {
+    const fresh = entries.filter(e => now - e.ts < HISTORY_TTL_MS);
+    if (fresh.length === 0) chatHistory.delete(chatId);
+    else chatHistory.set(chatId, fresh);
+  }
+}, 10 * 60 * 1000);
+
+function getHistory(chatId: number): HistoryEntry[] {
+  return chatHistory.get(chatId) ?? [];
+}
+
+function pushHistory(chatId: number, role: "user" | "assistant", content: string): void {
+  const entries = chatHistory.get(chatId) ?? [];
+  entries.push({ role, content, ts: Date.now() });
+  if (entries.length > MAX_HISTORY * 2) entries.splice(0, entries.length - MAX_HISTORY * 2);
+  chatHistory.set(chatId, entries);
+}
+
+/**
+ * Record a tool result in conversation history so the AI knows what happened.
+ */
+export function recordToolResult(chatId: number, toolName: string, resultSummary: string): void {
+  pushHistory(chatId, "assistant", `[Tool ${toolName} result]: ${resultSummary}`);
+}
+
+/**
+ * Process a natural language message through Claude and return the intent.
+ */
+export async function processMessage(
+  chatId: number,
+  userMessage: string,
+  context: { meshSlug?: string; meshSlugs?: string[]; userName?: string; recentPeers?: string[] },
+): Promise<AiResult> {
+  try {
+    const anthropic = getClient();
+
+    // Record user message in history
+    pushHistory(chatId, "user", userMessage);
+
+    const contextInfo = [
+      context.meshSlugs?.length ? `Connected meshes: ${context.meshSlugs.join(", ")}` : context.meshSlug ? `Current mesh: ${context.meshSlug}` : null,
+      context.userName ? `User's name: ${context.userName}` : null,
+      context.recentPeers?.length ? `Known peers: ${context.recentPeers.join(", ")}` : null,
+    ].filter(Boolean).join(". ");
+
+    // Build message history for multi-turn context
+    const history = getHistory(chatId);
+    const messages: Array<{ role: "user" | "assistant"; content: string }> = [];
+    for (const entry of history) {
+      // Alternate roles — Claude API requires user/assistant alternation
+      if (messages.length === 0 || messages[messages.length - 1]!.role !== entry.role) {
+        messages.push({ role: entry.role, content: entry.content });
+      } else {
+        // Same role consecutive — merge into the last message
+        messages[messages.length - 1]!.content += "\n" + entry.content;
+      }
+    }
+
+    // Ensure messages start with user and alternate
+    if (messages.length > 0 && messages[0]!.role !== "user") {
+      messages.shift();
+    }
+
+    const response = await anthropic.messages.create({
+      model: "claude-haiku-4-5-20251001",
+      max_tokens: 500,
+      system: SYSTEM_PROMPT + (contextInfo ? `\n\nContext: ${contextInfo}` : ""),
+      tools: TOOLS as Anthropic.Messages.Tool[],
+      messages,
+    });
+
+    // Check for tool use
+    for (const block of response.content) {
+      if (block.type === "tool_use") {
+        pushHistory(chatId, "assistant", `[Using tool: ${block.name}(${JSON.stringify(block.input).slice(0, 100)})]`);
+        return {
+          type: "tool_call",
+          toolCall: { name: block.name, input: block.input as Record<string, unknown> },
+          requiresConfirmation: CONFIRM_ACTIONS.has(block.name),
+        };
+      }
+      if (block.type === "text") {
+        pushHistory(chatId, "assistant", block.text);
+        return { type: "text", text: block.text };
+      }
+    }
+
+    return { type: "text", text: "I'm not sure how to help with that." };
+  } catch (err) {
+    log.error("telegram-ai", { error: err instanceof Error ? err.message : String(err) });
+    return { type: "error", text: "AI processing failed. Try a /command instead." };
+  }
+}
+
+/**
+ * Format a tool call as a human-readable confirmation message for Telegram.
+ */
+export function formatConfirmation(toolCall: AiToolCall): string {
+  const { name, input } = toolCall;
+
+  switch (name) {
+    case "send_message":
+      return `📤 <b>Send message to ${escHtml(String(input.to))}:</b>\n\n"${escHtml(String(input.message))}"\n\nPriority: ${input.priority ?? "next"}`;
+
+    case "create_mesh":
+      return `🔧 <b>Create mesh:</b>\n\nName: ${escHtml(String(input.name))}`;
+
+    case "share_mesh":
+      return input.email
+        ? `📧 <b>Send invite to:</b>\n\n${escHtml(String(input.email))}`
+        : `🔗 <b>Generate invite link</b>`;
+
+    case "set_state":
+      return `📝 <b>Set state:</b>\n\n<code>${escHtml(String(input.key))}</code> = <code>${escHtml(String(input.value))}</code>`;
+
+    case "remember":
+      return `💾 <b>Remember:</b>\n\n"${escHtml(String(input.content))}"${input.tags ? `\nTags: ${(input.tags as string[]).join(", ")}` : ""}`;
+
+    default:
+      return `⚙️ <b>${escHtml(name)}:</b>\n\n<pre>${escHtml(JSON.stringify(input, null, 2))}</pre>`;
+  }
+}
+
+/**
+ * Format a tool result as a Telegram reply.
+ */
+export function formatResult(toolName: string, result: unknown): string {
+  switch (toolName) {
+    case "send_message":
+      return "✅ Message sent.";
+
+    case "list_peers": {
+      const peers = result as Array<{ displayName: string; status: string; summary?: string }>;
+      if (!peers || peers.length === 0) return "No peers online.";
+      return "👥 <b>Online peers:</b>\n\n" + peers.map(p => {
+        const icon = p.status === "idle" ? "🟢" : p.status === "working" ? "🟡" : p.status === "dnd" ? "🔴" : "⚪";
+        return `${icon} <b>${escHtml(p.displayName)}</b>${p.summary ? ` — ${escHtml(p.summary)}` : ""}`;
+      }).join("\n");
+    }
+
+    case "list_meshes": {
+      const meshes = result as Array<{ slug: string; peers: number }>;
+      if (!meshes || meshes.length === 0) return "No meshes connected. Use /connect to add one.";
+      return "🔗 <b>Connected meshes:</b>\n\n" + meshes.map(m =>
+        `• <b>${escHtml(m.slug)}</b> — ${m.peers} peer${m.peers !== 1 ? "s" : ""} online`
+      ).join("\n");
+    }
+
+    case "recall": {
+      const memories = result as Array<{ content: string; tags: string[] }>;
+      if (!memories || memories.length === 0) return "No memories found.";
+      return "🧠 <b>Memories:</b>\n\n" + memories.map(m =>
+        `• ${escHtml(m.content)}${m.tags.length ? ` <i>[${m.tags.join(", ")}]</i>` : ""}`
+      ).join("\n");
+    }
+
+    case "get_state": {
+      const state = result as { key: string; value: unknown } | null;
+      if (!state) return "Key not found.";
+      return `📊 <code>${escHtml(state.key)}</code> = <code>${escHtml(String(state.value))}</code>`;
+    }
+
+    case "remember":
+      return "💾 Remembered.";
+
+    case "set_state":
+      return "📝 State updated.";
+
+    case "create_mesh":
+      return "✅ Mesh created.";
+
+    case "share_mesh":
+      return typeof result === "string" ? `🔗 Invite: ${result}` : "✅ Invite sent.";
+
+    case "list_services": {
+      const services = result as Array<{ name: string; type: string; tools: number; status: string }>;
+      if (!services || services.length === 0) return "No services deployed in this mesh.";
+      return "⚙️ <b>Mesh services:</b>\n\n" + services.map(s =>
+        `• <b>${escHtml(s.name)}</b> (${s.type}) — ${s.tools} tool${s.tools !== 1 ? "s" : ""} [${s.status}]`
+      ).join("\n");
+    }
+
+    case "list_commands":
+      return `📋 <b>Available commands:</b>
+
+/connect — connect to a mesh
+/disconnect — disconnect from mesh
+/peers — list online peers
+/meshes — list connected meshes
+/dm @Name message — send direct message
+/broadcast message — send to all peers
+/status — connection status
+/help — show help
+
+Or just type naturally:
+• "who's online?"
+• "tell Nedas the API is ready"
+• "list my meshes"
+• "what services are available?"`;
+
+    default:
+      return `✅ Done: ${JSON.stringify(result)}`;
+  }
+}
+
+function escHtml(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+export { CONFIRM_ACTIONS };
--- a/apps/broker/src/telegram-bridge.ts
+++ b/apps/broker/src/telegram-bridge.ts
--- a/apps/broker/src/telegram-token.ts
+++ b/apps/broker/src/telegram-token.ts
@@ -0,0 +1,148 @@
+/**
+ * JWT utilities for Telegram bridge connections.
+ *
+ * When a user connects their Telegram chat to a mesh, the broker generates
+ * a short-lived JWT containing mesh credentials. The Telegram bot decodes
+ * this token to establish the connection.
+ *
+ * Pure-crypto implementation — no external JWT library.
+ * Tokens are URL-safe (base64url) for use as Telegram deep link parameters.
+ *
+ * IMPORTANT: The JWT payload contains the member's secretKey.
+ * Never log the token or its decoded payload.
+ */
+
+import { createHmac } from "node:crypto";
+
+// --- Types ---
+
+export interface TelegramConnectPayload {
+  meshId: string;
+  meshSlug: string;
+  memberId: string;
+  pubkey: string;
+  secretKey: string;   // ed25519 secret key — sensitive
+  createdBy: string;   // Dashboard userId or CLI memberId
+}
+
+interface JwtClaims extends TelegramConnectPayload {
+  iss: string;
+  sub: string;
+  iat: number;
+  exp: number;
+}
+
+// --- Helpers ---
+
+function base64url(data: string): string {
+  return Buffer.from(data).toString("base64url");
+}
+
+function base64urlDecode(str: string): string {
+  return Buffer.from(str, "base64url").toString("utf-8");
+}
+
+function sign(input: string, secret: string): string {
+  return createHmac("sha256", secret).update(input).digest("base64url");
+}
+
+// --- Public API ---
+
+const JWT_HEADER = base64url(JSON.stringify({ alg: "HS256", typ: "JWT" }));
+const TOKEN_TTL_SECONDS = 15 * 60; // 15 minutes
+
+/**
+ * Create a signed JWT containing Telegram connect credentials.
+ * Expires in 15 minutes.
+ */
+export function generateTelegramConnectToken(
+  payload: TelegramConnectPayload,
+  secret: string,
+): string {
+  const now = Math.floor(Date.now() / 1000);
+
+  const claims: JwtClaims = {
+    ...payload,
+    iss: "claudemesh-broker",
+    sub: "telegram-connect",
+    iat: now,
+    exp: now + TOKEN_TTL_SECONDS,
+  };
+
+  const encodedPayload = base64url(JSON.stringify(claims));
+  const signingInput = `${JWT_HEADER}.${encodedPayload}`;
+  const signature = sign(signingInput, secret);
+
+  return `${signingInput}.${signature}`;
+}
+
+/**
+ * Validate and decode a Telegram connect JWT.
+ * Returns the payload on success, or null on any failure
+ * (bad signature, expired, wrong subject).
+ */
+export function validateTelegramConnectToken(
+  token: string,
+  secret: string,
+): TelegramConnectPayload | null {
+  try {
+    const parts = token.split(".");
+    if (parts.length !== 3) return null;
+
+    const [headerB64, payloadB64, signatureB64] = parts as [string, string, string];
+
+    // Verify signature
+    const signingInput = `${headerB64}.${payloadB64}`;
+    const expectedSignature = sign(signingInput, secret);
+    // Constant-time comparison to prevent timing attacks
+    const a = Buffer.from(signatureB64);
+    const b = Buffer.from(expectedSignature);
+    if (a.length !== b.length) return null;
+    const { timingSafeEqual } = require("node:crypto");
+    if (!timingSafeEqual(a, b)) return null;
+
+    // Verify header algorithm
+    const header = JSON.parse(base64urlDecode(headerB64));
+    if (header.alg !== "HS256") return null;
+
+    // Decode and validate claims
+    const claims: JwtClaims = JSON.parse(base64urlDecode(payloadB64));
+
+    // Check subject
+    if (claims.sub !== "telegram-connect") return null;
+
+    // Check expiry
+    const now = Math.floor(Date.now() / 1000);
+    if (claims.exp < now) return null;
+
+    // Check iat not in the future (30s tolerance)
+    if (claims.iat > now + 30) return null;
+
+    // Extract payload fields (strip JWT claims)
+    const {
+      meshId,
+      meshSlug,
+      memberId,
+      pubkey,
+      secretKey,
+      createdBy,
+    } = claims;
+
+    // Basic presence check
+    if (!meshId || !meshSlug || !memberId || !pubkey || !secretKey || !createdBy) {
+      return null;
+    }
+
+    return { meshId, meshSlug, memberId, pubkey, secretKey, createdBy };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Generate a Telegram deep link that passes the JWT as start parameter.
+ * Format: https://t.me/{botUsername}?start={token}
+ */
+export function generateDeepLink(token: string, botUsername: string): string {
+  return `https://t.me/${botUsername}?start=${token}`;
+}
--- a/apps/broker/src/types.ts
+++ b/apps/broker/src/types.ts
--- a/apps/broker/src/webhooks.ts
+++ b/apps/broker/src/webhooks.ts
@@ -0,0 +1,97 @@
+/**
+ * Inbound webhook handler.
+ *
+ * External services POST JSON to `/hook/:meshId/:secret`. The broker
+ * verifies the secret against the mesh.webhook table, then pushes the
+ * payload to all connected peers in that mesh as a "webhook" push.
+ */
+
+import { eq, and } from "drizzle-orm";
+import { db } from "./db";
+import { meshWebhook } from "@turbostarter/db/schema/mesh";
+import type { WSPushMessage } from "./types";
+import { log } from "./logger";
+
+export interface WebhookResult {
+  status: number;
+  body: { ok: boolean; delivered?: number; error?: string };
+}
+
+/**
+ * Look up a webhook by meshId + secret, verify it's active, then return
+ * the webhook name for push routing. Returns null if not found/inactive.
+ */
+async function findActiveWebhook(
+  meshId: string,
+  secret: string,
+): Promise<{ id: string; name: string; meshId: string } | null> {
+  const rows = await db
+    .select({ id: meshWebhook.id, name: meshWebhook.name, meshId: meshWebhook.meshId })
+    .from(meshWebhook)
+    .where(
+      and(
+        eq(meshWebhook.meshId, meshId),
+        eq(meshWebhook.secret, secret),
+        eq(meshWebhook.active, true),
+      ),
+    )
+    .limit(1);
+  return rows[0] ?? null;
+}
+
+/**
+ * Handle an inbound webhook HTTP request.
+ *
+ * @param meshId - mesh ID from the URL path
+ * @param secret - webhook secret from the URL path
+ * @param body - parsed JSON body from the request
+ * @param broadcastToMesh - callback to push a message to all connected peers in a mesh.
+ *   Returns the number of peers the message was delivered to.
+ */
+export async function handleWebhook(
+  meshId: string,
+  secret: string,
+  body: unknown,
+  broadcastToMesh: (meshId: string, msg: WSPushMessage) => number,
+): Promise<WebhookResult> {
+  try {
+    const webhook = await findActiveWebhook(meshId, secret);
+    if (!webhook) {
+      log.warn("webhook auth failed", { mesh_id: meshId });
+      return { status: 401, body: { ok: false, error: "unauthorized" } };
+    }
+
+    if (body === null || body === undefined || typeof body !== "object") {
+      return { status: 400, body: { ok: false, error: "invalid JSON body" } };
+    }
+
+    const pushMsg: WSPushMessage = {
+      type: "push",
+      subtype: "webhook" as any,
+      event: webhook.name,
+      eventData: body as Record<string, unknown>,
+      messageId: crypto.randomUUID(),
+      meshId: webhook.meshId,
+      senderPubkey: `webhook:${webhook.name}`,
+      priority: "next",
+      nonce: "",
+      ciphertext: "",
+      createdAt: new Date().toISOString(),
+    };
+
+    const delivered = broadcastToMesh(webhook.meshId, pushMsg);
+
+    log.info("webhook delivered", {
+      webhook_name: webhook.name,
+      mesh_id: webhook.meshId,
+      delivered,
+    });
+
+    return { status: 200, body: { ok: true, delivered } };
+  } catch (e) {
+    log.error("webhook handler error", {
+      error: e instanceof Error ? e.message : String(e),
+    });
+    return { status: 500, body: { ok: false, error: "internal error" } };
+  }
+}
--- a/apps/broker/tests/invite-v2.test.ts
+++ b/apps/broker/tests/invite-v2.test.ts
@@ -0,0 +1,268 @@
+/**
+ * v2 invite protocol — broker claim endpoint.
+ *
+ * Covers the sealed-root-key delivery flow added in
+ * .artifacts/specs/2026-04-10-anthropic-vision-meshes-invites.md :
+ *
+ *   - happy path: signed v2 invite claim returns a sealed root_key the
+ *     recipient can unseal back to the mesh.rootKey column value
+ *   - tampered signature → 400 bad_signature
+ *   - expired invite → 410 expired
+ *   - revoked invite → 410 revoked
+ *   - exhausted invite (usedCount === maxUses) → 410 exhausted
+ *   - round-trip: recipient-side crypto_box_seal_open recovers the real key
+ *
+ * Tests talk directly to claimInviteV2Core() to avoid spinning up the
+ * full broker HTTP server. The handler delegates to this function with
+ * zero extra logic, so coverage is equivalent.
+ */
+
+import { afterAll, afterEach, beforeAll, describe, expect, test } from "vitest";
+import { eq } from "drizzle-orm";
+import sodium from "libsodium-wrappers";
+import { db } from "../src/db";
+import { invite, mesh } from "@turbostarter/db/schema/mesh";
+import { canonicalInviteV2 } from "../src/crypto";
+import { claimInviteV2Core } from "../src/index";
+import {
+  cleanupAllTestMeshes,
+  setupTestMesh,
+  type TestMesh,
+} from "./helpers";
+
+afterAll(async () => {
+  await cleanupAllTestMeshes();
+});
+
+beforeAll(async () => {
+  await sodium.ready;
+});
+
+/**
+ * Set a random base64url root_key on an existing test mesh. The helpers
+ * don't set one by default, so v2 tests prime it per-mesh here.
+ */
+async function primeRootKey(meshId: string): Promise<Uint8Array> {
+  const key = sodium.randombytes_buf(32);
+  const b64 = sodium.to_base64(key, sodium.base64_variants.URLSAFE_NO_PADDING);
+  await db.update(mesh).set({ rootKey: b64 }).where(eq(mesh.id, meshId));
+  return key;
+}
+
+/**
+ * Insert a signed v2 invite row. Returns the opaque short code + the
+ * recipient x25519 keypair the test will use to unseal.
+ */
+async function insertV2Invite(
+  m: TestMesh,
+  opts: {
+    code: string;
+    expiresInSec?: number;
+    maxUses?: number;
+    role?: "admin" | "member";
+    tamper?: boolean; // corrupt the signature
+    revoked?: boolean;
+    used?: number;
+  },
+): Promise<{ inviteId: string; canonical: string }> {
+  const expiresInSec = opts.expiresInSec ?? 3600;
+  const expiresAt = new Date(Date.now() + expiresInSec * 1000);
+  const maxUses = opts.maxUses ?? 1;
+  const role = opts.role ?? "member";
+
+  // Insert first with a placeholder capability so we have the invite id.
+  const [row] = await db
+    .insert(invite)
+    .values({
+      meshId: m.meshId,
+      token: `v2-test-token-${opts.code}`,
+      code: opts.code,
+      maxUses,
+      usedCount: opts.used ?? 0,
+      role,
+      expiresAt,
+      createdBy: "test-user-integration",
+      version: 2,
+      revokedAt: opts.revoked ? new Date() : null,
+    })
+    .returning({ id: invite.id });
+  if (!row) throw new Error("v2 invite insert failed");
+
+  // Now compute canonical_v2 using the real invite id and sign with the
+  // mesh owner's ed25519 secret key.
+  const expiresAtUnix = Math.floor(expiresAt.getTime() / 1000);
+  const canonical = canonicalInviteV2({
+    mesh_id: m.meshId,
+    invite_id: row.id,
+    expires_at: expiresAtUnix,
+    role,
+    owner_pubkey: m.ownerPubkey,
+  });
+  let signatureHex = sodium.to_hex(
+    sodium.crypto_sign_detached(
+      sodium.from_string(canonical),
+      sodium.from_hex(m.ownerSecretKey),
+    ),
+  );
+  if (opts.tamper) {
+    // Flip a single hex nibble — keeps length valid, invalidates signature.
+    const first = signatureHex[0] === "0" ? "1" : "0";
+    signatureHex = first + signatureHex.slice(1);
+  }
+
+  const capability = JSON.stringify({
+    canonical,
+    signature: signatureHex,
+  });
+  await db
+    .update(invite)
+    .set({ capabilityV2: capability })
+    .where(eq(invite.id, row.id));
+  return { inviteId: row.id, canonical };
+}
+
+function genRecipientX25519(): { pk: string; sk: Uint8Array } {
+  const kp = sodium.crypto_box_keypair();
+  return {
+    pk: sodium.to_base64(kp.publicKey, sodium.base64_variants.URLSAFE_NO_PADDING),
+    sk: kp.privateKey,
+  };
+}
+
+describe("claimInviteV2Core — v2 invite claim", () => {
+  let m: TestMesh;
+  afterEach(async () => m && (await m.cleanup()));
+
+  test("happy path: signed v2 invite returns sealed root_key and member row", async () => {
+    m = await setupTestMesh("v2-ok");
+    const rootKeyBytes = await primeRootKey(m.meshId);
+    const code = `c${Math.random().toString(36).slice(2, 10)}`;
+    const { inviteId, canonical } = await insertV2Invite(m, { code });
+    const recipient = genRecipientX25519();
+
+    const result = await claimInviteV2Core({
+      code,
+      recipientX25519PubkeyBase64url: recipient.pk,
+    });
+
+    expect(result.ok).toBe(true);
+    if (!result.ok) return;
+    expect(result.status).toBe(200);
+    expect(result.body.mesh_id).toBe(m.meshId);
+    expect(result.body.owner_pubkey).toBe(m.ownerPubkey);
+    expect(result.body.canonical_v2).toBe(canonical);
+    expect(result.body.member_id).toBeTruthy();
+
+    // Recipient unseals the sealed_root_key using its x25519 secret key.
+    const sealed = sodium.from_base64(
+      result.body.sealed_root_key,
+      sodium.base64_variants.URLSAFE_NO_PADDING,
+    );
+    const recipientPkBytes = sodium.from_base64(
+      recipient.pk,
+      sodium.base64_variants.URLSAFE_NO_PADDING,
+    );
+    const opened = sodium.crypto_box_seal_open(
+      sealed,
+      recipientPkBytes,
+      recipient.sk,
+    );
+    expect(opened).toBeInstanceOf(Uint8Array);
+    expect(opened.length).toBe(32);
+    expect(Array.from(opened)).toEqual(Array.from(rootKeyBytes));
+
+    // usedCount incremented and claimedByPubkey recorded.
+    const [updated] = await db
+      .select({
+        usedCount: invite.usedCount,
+        claimedByPubkey: invite.claimedByPubkey,
+      })
+      .from(invite)
+      .where(eq(invite.id, inviteId));
+    expect(updated?.usedCount).toBe(1);
+    expect(updated?.claimedByPubkey).toBe(recipient.pk);
+  });
+
+  test("tampered signature → 400 bad_signature", async () => {
+    m = await setupTestMesh("v2-tampered");
+    await primeRootKey(m.meshId);
+    const code = `c${Math.random().toString(36).slice(2, 10)}`;
+    await insertV2Invite(m, { code, tamper: true });
+    const recipient = genRecipientX25519();
+
+    const result = await claimInviteV2Core({
+      code,
+      recipientX25519PubkeyBase64url: recipient.pk,
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.status).toBe(400);
+    expect(result.body.error).toBe("bad_signature");
+  });
+
+  test("expired invite → 410 expired", async () => {
+    m = await setupTestMesh("v2-expired");
+    await primeRootKey(m.meshId);
+    const code = `c${Math.random().toString(36).slice(2, 10)}`;
+    await insertV2Invite(m, { code, expiresInSec: -60 });
+    const recipient = genRecipientX25519();
+
+    const result = await claimInviteV2Core({
+      code,
+      recipientX25519PubkeyBase64url: recipient.pk,
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.status).toBe(410);
+    expect(result.body.error).toBe("expired");
+  });
+
+  test("revoked invite → 410 revoked", async () => {
+    m = await setupTestMesh("v2-revoked");
+    await primeRootKey(m.meshId);
+    const code = `c${Math.random().toString(36).slice(2, 10)}`;
+    await insertV2Invite(m, { code, revoked: true });
+    const recipient = genRecipientX25519();
+
+    const result = await claimInviteV2Core({
+      code,
+      recipientX25519PubkeyBase64url: recipient.pk,
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.status).toBe(410);
+    expect(result.body.error).toBe("revoked");
+  });
+
+  test("exhausted invite (usedCount >= maxUses) → 410 exhausted", async () => {
+    m = await setupTestMesh("v2-exhausted");
+    await primeRootKey(m.meshId);
+    const code = `c${Math.random().toString(36).slice(2, 10)}`;
+    await insertV2Invite(m, { code, maxUses: 1, used: 1 });
+    const recipient = genRecipientX25519();
+
+    const result = await claimInviteV2Core({
+      code,
+      recipientX25519PubkeyBase64url: recipient.pk,
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.status).toBe(410);
+    expect(result.body.error).toBe("exhausted");
+  });
+
+  test("unknown code → 404 not_found", async () => {
+    m = await setupTestMesh("v2-404");
+    await primeRootKey(m.meshId);
+    const recipient = genRecipientX25519();
+
+    const result = await claimInviteV2Core({
+      code: "nonexistent",
+      recipientX25519PubkeyBase64url: recipient.pk,
+    });
+    expect(result.ok).toBe(false);
+    if (result.ok) return;
+    expect(result.status).toBe(404);
+    expect(result.body.error).toBe("not_found");
+  });
+});
--- a/apps/broker/tsconfig.json
+++ b/apps/broker/tsconfig.json
@@ -8,8 +8,9 @@
    "paths": {
      "~/*": ["./src/*"]
    },
-    "types": ["bun-types"]
+    "types": ["bun-types"],
+    "jsx": "react-jsx"
  },
-  "include": ["src/**/*.ts"],
+  "include": ["src/**/*.ts", "src/**/*.tsx"],
  "exclude": ["node_modules", "dist"]
 }
--- a/apps/cli-v2/.gitignore
+++ b/apps/cli-v2/.gitignore
@@ -0,0 +1,5 @@
+node_modules/
+dist/
+.turbo/
+.cache/
+*.log
--- a/apps/cli-v2/CHANGELOG.md
+++ b/apps/cli-v2/CHANGELOG.md
@@ -0,0 +1,44 @@
+# Changelog
+
+## 1.0.0-alpha.0 (2026-04-13)
+
+### Architecture
+- Complete folder restructure: `entrypoints/`, `cli/`, `commands/`, `services/` (17 feature-folders with facade pattern), `ui/`, `mcp/`, `constants/`, `types/`, `utils/`, `locales/`, `templates/`
+- 212 source files, 10,900 lines
+- ESM-only, Bun bundler, TypeScript strict mode
+
+### New CLI commands
+- `claudemesh register` — account creation via browser handoff
+- `claudemesh login` — device-code OAuth
+- `claudemesh logout` — revoke session + clear credentials
+- `claudemesh whoami` — identity check with `--json` support
+- `claudemesh new <name>` — create mesh from CLI (was dashboard-only)
+- `claudemesh invite [email]` — generate invite from CLI (was dashboard-only)
+
+### Ported from v1 (full feature parity)
+- All 79 MCP tools
+- All 85 WS message types (broker protocol unchanged)
+- Welcome wizard, launch flow, install/uninstall
+- Ed25519 + NaCl crypto (keypairs, crypto_box DMs, file encryption)
+- Reconnect with exponential backoff
+- Status priority engine, scheduled messages, URL watch
+- Doctor checks, Telegram bridge connect wizard
+
+### Security hardening (25 bugs fixed across 4 reviews)
+- `execFile` instead of `exec` for browser open (command injection fix)
+- ReDoS-safe pattern matching in peer file sharing
+- Atomic config writes via temp file + rename
+- Auth token stored with `openSync(mode: 0o600)` — no permission race
+- Decryption oracle collapsed to generic error in `get_file`
+- Download size limit (100MB) on file retrieval
+- Path traversal protection with `realpathSync` for symlink escapes
+- Callback listener double-resolve guard
+- Push buffer 1MB per-message truncation
+- `makeReqId` uses `crypto.randomBytes` instead of `Math.random`
+- Connect guard prevents double-connect race
+
+### Breaking changes from v0.10.x
+- Flat command namespace (no `launch` subcommand, no `advanced` prefix)
+- New config shape (same data, cleaner layout)
+- New `--json` output format with `schema_version: "1.0"`
+- New exit codes (see `constants/exit-codes.ts`)
--- a/apps/cli-v2/README.md
+++ b/apps/cli-v2/README.md
@@ -0,0 +1,90 @@
+# claudemesh-cli
+
+Peer mesh for Claude Code sessions. Connect multiple Claude Code instances into a shared mesh with real-time messaging, shared state, memory, file sharing, and 79 MCP tools.
+
+## Install
+
+```bash
+npm i -g claudemesh-cli
+```
+
+## Quick start
+
+```bash
+claudemesh register        # create account
+claudemesh new "my-team"   # create a mesh
+claudemesh invite           # generate invite link
+claudemesh                  # start a session
+```
+
+## Commands
+
+```
+USAGE
+  claudemesh                 start a session (creates one if needed)
+  claudemesh <url>           join a mesh from an invite link
+  claudemesh new             create a new mesh
+  claudemesh invite [email]  generate an invite
+  claudemesh list            see your meshes
+  claudemesh rename <name>   rename the current mesh
+  claudemesh leave [mesh]    leave a mesh
+  claudemesh peers           see who's online
+
+  claudemesh send <to> <msg> send a message
+  claudemesh inbox           drain pending messages
+  claudemesh state ...       get, set, or list shared state
+  claudemesh remember <text> store a memory
+  claudemesh recall <query>  search memories
+  claudemesh remind ...      schedule a reminder
+  claudemesh profile         view or edit your profile
+
+  claudemesh doctor          diagnose issues
+  claudemesh whoami          show current identity
+  claudemesh status          check broker connectivity
+
+  claudemesh register        create account
+  claudemesh login           sign in via browser
+  claudemesh logout          sign out
+
+  claudemesh install         register MCP server + hooks
+  claudemesh uninstall       remove MCP server + hooks
+```
+
+## Architecture
+
+```
+src/
+├── entrypoints/     CLI + MCP stdio entry points
+├── cli/             argv parsing, output formatters, signal handling
+├── commands/        one verb per file (29 commands)
+├── services/        17 feature-folders with facade pattern
+│   ├── auth/        device-code OAuth, token storage
+│   ├── broker/      WebSocket client (2200 lines), reconnect, crypto
+│   ├── crypto/      Ed25519, NaCl crypto_box, AES-GCM file encryption
+│   ├── config/      ~/.claudemesh/config.json with atomic writes
+│   ├── mesh/        CRUD, join, resolve target
+│   ├── invite/      generate, parse, claim (v1 + v2 formats)
+│   ├── api/         typed HTTP client for claudemesh.com
+│   ├── health/      6 diagnostic checks
+│   └── ...          device, clipboard, spawn, telemetry, i18n, logger
+├── mcp/             MCP server with 79 tools across 21 families
+├── ui/              TUI: styles, spinner, welcome wizard, launch flow
+├── constants/       exit codes, paths, URLs, timings
+├── types/           API, mesh, peer interfaces
+├── utils/           levenshtein, slug, URL, format, semver, retry
+├── locales/         English strings (i18n ready)
+└── templates/       5 mesh templates
+```
+
+## Development
+
+```bash
+pnpm install
+bun run dev          # hot-reload
+bun run build        # production build
+bun run typecheck    # tsc --noEmit
+```
+
+## License
+
+MIT
--- a/apps/cli-v2/bin/claudemesh
+++ b/apps/cli-v2/bin/claudemesh
@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "../dist/entrypoints/cli.js";
--- a/apps/cli-v2/biome.json
+++ b/apps/cli-v2/biome.json
@@ -0,0 +1,4 @@
+{
+  "$schema": "https://biomejs.dev/schemas/1.9.4/schema.json",
+  "extends": ["../../biome.json"]
+}
--- a/apps/cli-v2/build.ts
+++ b/apps/cli-v2/build.ts
@@ -0,0 +1,51 @@
+import { statSync } from "node:fs";
+import { gzipSync } from "node:zlib";
+
+const MAX_GZIPPED_BYTES = 1.2 * 1024 * 1024; // 1.2 MB
+
+const result = await Bun.build({
+  entrypoints: [
+    "src/entrypoints/cli.ts",
+    "src/entrypoints/mcp.ts",
+  ],
+  outdir: "dist/entrypoints",
+  target: "node",
+  format: "esm",
+  splitting: false,
+  sourcemap: "external",
+  external: [
+    "libsodium-wrappers",
+    "ws",
+    "@modelcontextprotocol/sdk",
+  ],
+});
+
+if (!result.success) {
+  console.error("Build failed:");
+  for (const log of result.logs) {
+    console.error(log);
+  }
+  process.exit(1);
+}
+
+for (const output of result.outputs) {
+  const raw = statSync(output.path).size;
+  const gz = gzipSync(await Bun.file(output.path).arrayBuffer()).byteLength;
+  const label = output.path.replace(process.cwd() + "/", "");
+  console.log(`  ${label}  ${(raw / 1024).toFixed(0)} KB  (${(gz / 1024).toFixed(0)} KB gzipped)`);
+
+  if (gz > MAX_GZIPPED_BYTES) {
+    console.error(`\n  ERROR: ${label} exceeds 1.2 MB gzipped ceiling (${(gz / 1024).toFixed(0)} KB)`);
+    process.exit(1);
+  }
+}
+
+const { chmodSync, readFileSync, writeFileSync } = await import("node:fs");
+const cliPath = "dist/entrypoints/cli.js";
+const cliContent = readFileSync(cliPath, "utf-8");
+if (!cliContent.startsWith("#!")) {
+  writeFileSync(cliPath, "#!/usr/bin/env node\n" + cliContent);
+}
+chmodSync(cliPath, 0o755);
+
+console.log("\nBuild complete.");
--- a/apps/cli-v2/package.json
+++ b/apps/cli-v2/package.json
@@ -0,0 +1,69 @@
+{
+  "name": "claudemesh-cli-v2",
+  "version": "1.0.0-alpha.30",
+  "description": "Peer mesh for Claude Code sessions — CLI + MCP server.",
+  "keywords": [
+    "claude-code",
+    "mcp",
+    "model-context-protocol",
+    "claudemesh",
+    "peer-messaging",
+    "multi-agent"
+  ],
+  "author": "Alejandro Gutiérrez",
+  "license": "MIT",
+  "homepage": "https://claudemesh.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/alezmad/claudemesh.git",
+    "directory": "apps/cli-v2"
+  },
+  "type": "module",
+  "bin": {
+    "claudemesh": "./dist/entrypoints/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "bun build.ts",
+    "clean": "git clean -xdf .cache .turbo dist node_modules",
+    "dev": "bun --hot src/entrypoints/cli.ts",
+    "start": "bun src/entrypoints/cli.ts",
+    "format": "prettier --check . --ignore-path ../../.gitignore",
+    "lint": "eslint",
+    "prepublishOnly": "bun run build",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "prettier": "@turbostarter/prettier-config",
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.27.1",
+    "citty": "0.2.2",
+    "libsodium-wrappers": "0.7.15",
+    "qrcode-terminal": "0.12.0",
+    "ws": "8.20.0",
+    "zod": "4.1.13"
+  },
+  "devDependencies": {
+    "@turbostarter/eslint-config": "workspace:*",
+    "@turbostarter/prettier-config": "workspace:*",
+    "@turbostarter/tsconfig": "workspace:*",
+    "@turbostarter/vitest-config": "workspace:*",
+    "@types/libsodium-wrappers": "0.7.14",
+    "@types/qrcode-terminal": "0.12.2",
+    "@types/ws": "8.5.13",
+    "eslint": "catalog:",
+    "prettier": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}
--- a/apps/cli-v2/scripts/build-binaries.ts
+++ b/apps/cli-v2/scripts/build-binaries.ts
@@ -0,0 +1,49 @@
+/**
+ * Cross-platform single-binary compile.
+ *
+ * Run:  bun run scripts/build-binaries.ts
+ * Output:  dist/bin/claudemesh-{darwin,linux,windows}-{x64,arm64}{.exe}
+ *
+ * Each binary bundles the CLI + Bun runtime, no Node required.
+ * Current caveat: native deps like libsodium-wrappers ship as JS+wasm
+ * so they work. `ws` falls back to its JS polyfill when uws isn't present.
+ *
+ * Intended for CI — GitHub Releases publish → install.sh / Homebrew
+ * pull the right tarball per platform.
+ */
+
+import { mkdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+
+const TARGETS: Array<{ name: string; target: string; ext: string }> = [
+  { name: "darwin-x64", target: "bun-darwin-x64", ext: "" },
+  { name: "darwin-arm64", target: "bun-darwin-arm64", ext: "" },
+  { name: "linux-x64", target: "bun-linux-x64", ext: "" },
+  { name: "linux-arm64", target: "bun-linux-arm64", ext: "" },
+  { name: "windows-x64", target: "bun-windows-x64", ext: ".exe" },
+];
+
+mkdirSync("dist/bin", { recursive: true });
+
+for (const { name, target, ext } of TARGETS) {
+  const out = `dist/bin/claudemesh-${name}${ext}`;
+  console.log(`→ ${out}`);
+  const res = spawnSync(
+    "bun",
+    [
+      "build",
+      "--compile",
+      "--minify",
+      `--target=${target}`,
+      "src/entrypoints/cli.ts",
+      "--outfile",
+      out,
+    ],
+    { stdio: "inherit" },
+  );
+  if (res.status !== 0) {
+    console.error(`  failed: ${name}`);
+    process.exit(1);
+  }
+}
+console.log("\nBinaries built in dist/bin/");
--- a/apps/cli-v2/src/cli/argv.ts
+++ b/apps/cli-v2/src/cli/argv.ts
@@ -0,0 +1,30 @@
+import { defineCommand, runMain } from "citty";
+
+export interface ParsedArgs { command: string; positionals: string[]; flags: Record<string, string | boolean | undefined>; }
+
+export function parseArgv(argv: string[]): ParsedArgs {
+  const args = argv.slice(2);
+  const flags: Record<string, string | boolean | undefined> = {};
+  const positionals: string[] = [];
+  let command = "";
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!;
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = args[i + 1];
+      if (next && !next.startsWith("-")) { flags[key] = next; i++; } else flags[key] = true;
+    } else if (arg.startsWith("-") && arg.length === 2) {
+      const key = arg.slice(1);
+      const next = args[i + 1];
+      if (next && !next.startsWith("-")) { flags[key] = next; i++; } else flags[key] = true;
+    } else if (!command) {
+      command = arg;
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return { command, positionals, flags };
+}
+
+export { defineCommand, runMain };
--- a/apps/cli-v2/src/cli/exit.ts
+++ b/apps/cli-v2/src/cli/exit.ts
@@ -0,0 +1,7 @@
+import { EXIT } from "~/constants/exit-codes.js";
+const cleanupHooks: Array<() => void> = [];
+export function onExit(fn: () => void): void { cleanupHooks.push(fn); }
+export function exit(code: number = EXIT.SUCCESS): never {
+  for (const fn of cleanupHooks) { try { fn(); } catch {} }
+  process.exit(code);
+}
--- a/apps/cli-v2/src/cli/handlers/error.ts
+++ b/apps/cli-v2/src/cli/handlers/error.ts
@@ -0,0 +1,12 @@
+import { EXIT } from "~/constants/exit-codes.js";
+import { red } from "~/ui/styles.js";
+export function handleUncaughtError(err: unknown): never {
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(red("\n  Fatal: " + msg + "\n"));
+  if (process.env.CLAUDEMESH_DEBUG === "1" && err instanceof Error && err.stack) console.error(err.stack);
+  process.exit(EXIT.INTERNAL_ERROR);
+}
+export function installErrorHandlers(): void {
+  process.on("uncaughtException", handleUncaughtError);
+  process.on("unhandledRejection", (reason) => handleUncaughtError(reason));
+}
--- a/apps/cli-v2/src/cli/handlers/signal.ts
+++ b/apps/cli-v2/src/cli/handlers/signal.ts
@@ -0,0 +1,6 @@
+import { SHOW_CURSOR } from "~/ui/styles.js";
+export function installSignalHandlers(): void {
+  const cleanup = () => { process.stdout.write(SHOW_CURSOR); };
+  process.on("SIGINT", () => { cleanup(); process.exit(1); });
+  process.on("SIGTERM", () => { cleanup(); process.exit(0); });
+}
--- a/apps/cli-v2/src/cli/output/list.ts
+++ b/apps/cli-v2/src/cli/output/list.ts
@@ -0,0 +1,6 @@
+import type { JoinedMesh } from "~/services/config/facade.js";
+import { bold, dim } from "~/ui/styles.js";
+export function renderMeshList(meshes: JoinedMesh[]): string {
+  if (meshes.length === 0) return "  No meshes joined.";
+  return meshes.map((m, i) => "  " + bold((i + 1) + ")") + " " + m.slug + " " + dim("(" + m.meshId.slice(0, 8) + "\u2026)")).join("\n");
+}
--- a/apps/cli-v2/src/cli/output/peers.ts
+++ b/apps/cli-v2/src/cli/output/peers.ts
@@ -0,0 +1,11 @@
+import type { PeerInfo } from "~/services/broker/facade.js";
+import { bold, dim, green, yellow, red } from "~/ui/styles.js";
+const S: Record<string, (s: string) => string> = { idle: green, working: yellow, dnd: red };
+export function renderPeers(peers: PeerInfo[], meshSlug: string): string {
+  if (peers.length === 0) return "  No peers online in " + meshSlug + ".";
+  return peers.map(p => {
+    const icon = (S[p.status] ?? dim)("\u25CF");
+    const summary = p.summary ? dim(" \u2014 " + p.summary) : "";
+    return "  " + icon + " " + bold(p.displayName) + summary;
+  }).join("\n");
+}
--- a/apps/cli-v2/src/cli/output/version.ts
+++ b/apps/cli-v2/src/cli/output/version.ts
@@ -0,0 +1,3 @@
+import { VERSION } from "~/constants/urls.js";
+import { boldOrange } from "~/ui/styles.js";
+export function renderVersion(): string { return "  " + boldOrange("claudemesh") + " v" + VERSION; }
--- a/apps/cli-v2/src/cli/output/whoami.ts
+++ b/apps/cli-v2/src/cli/output/whoami.ts
@@ -0,0 +1,11 @@
+import type { WhoAmIResult } from "~/services/auth/facade.js";
+import { bold, dim } from "~/ui/styles.js";
+export function renderWhoAmI(result: WhoAmIResult): string {
+  if (!result.signed_in) return "  Not signed in.";
+  const lines = [
+    "  Signed in as " + bold(result.user!.display_name) + " (" + result.user!.email + ")",
+    "  Token source: " + result.token_source + " " + dim("(~/.claudemesh/auth.json)"),
+  ];
+  if (result.meshes) lines.push("  Meshes: " + result.meshes.owned + " owned, " + result.meshes.guest + " guest");
+  return lines.join("\n");
+}
--- a/apps/cli-v2/src/cli/print.ts
+++ b/apps/cli-v2/src/cli/print.ts
@@ -0,0 +1,7 @@
+const isTTY = process.stdout.isTTY && !process.env.NO_COLOR;
+export function print(msg: string): void { process.stdout.write(msg + "\n"); }
+export function printErr(msg: string): void { process.stderr.write(msg + "\n"); }
+export function isQuiet(): boolean { return process.argv.includes("-q") || process.argv.includes("--quiet"); }
+export function isVerbose(): boolean { return process.argv.includes("-v") || process.argv.includes("--verbose"); }
+export function isJson(): boolean { return process.argv.includes("--json"); }
+export function isTty(): boolean { return !!isTTY; }
--- a/apps/cli-v2/src/cli/structured-io.ts
+++ b/apps/cli-v2/src/cli/structured-io.ts
@@ -0,0 +1,4 @@
+export function jsonOutput<T>(data: T): string {
+  return JSON.stringify({ schema_version: "1.0", ...data }, null, 2);
+}
+export function writeJson<T>(data: T): void { console.log(jsonOutput(data)); }
--- a/apps/cli-v2/src/cli/update-notice.ts
+++ b/apps/cli-v2/src/cli/update-notice.ts
@@ -0,0 +1,11 @@
+import { checkForUpdate } from "~/services/update/facade.js";
+import { dim, yellow } from "~/ui/styles.js";
+export async function showUpdateNotice(currentVersion: string): Promise<void> {
+  try {
+    const info = await checkForUpdate(currentVersion);
+    if (info.updateAvailable) {
+      console.error(yellow("  Update available: " + info.current + " \u2192 " + info.latest));
+      console.error(dim("  Run: npm i -g claudemesh-cli"));
+    }
+  } catch {}
+}
--- a/apps/cli-v2/src/commands/backup.ts
+++ b/apps/cli-v2/src/commands/backup.ts
@@ -0,0 +1,147 @@
+/**
+ * `claudemesh backup` — encrypt the local config and save a portable
+ * recovery file. Restore later with `claudemesh restore <file>` on any
+ * machine to recover mesh memberships.
+ *
+ * Crypto:
+ *   - Argon2id KDF over a user passphrase → 32-byte key
+ *     (via libsodium's crypto_pwhash, INTERACTIVE limits so a weak
+ *      passphrase is still workable but brute-force remains expensive)
+ *   - XChaCha20-Poly1305 authenticated encryption of the JSON config
+ *   - Format: magic "CMB1" · salt (16B) · nonce (24B) · ciphertext
+ *
+ * Output: a single `.claudemesh-backup` file the user can store in
+ * 1Password, email to themselves, etc. Zero server involvement.
+ *
+ * Passphrase hygiene: read twice from TTY, never echoed. Rejects
+ * passphrases shorter than 12 characters.
+ */
+
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { createInterface } from "node:readline";
+import { getConfigPath } from "~/services/config/facade.js";
+import { ensureSodium } from "~/services/crypto/facade.js";
+import { EXIT } from "~/constants/exit-codes.js";
+
+const MAGIC = Buffer.from("CMB1", "utf-8");
+
+function readHidden(prompt: string): Promise<string> {
+  return new Promise((resolve) => {
+    process.stdout.write(prompt);
+    const rl = createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+    // Node readline doesn't mask by default. Turn off echo manually.
+    const stdin = process.stdin as NodeJS.ReadStream & { isTTY?: boolean };
+    const wasRaw = Boolean(stdin.isRaw);
+    if (stdin.isTTY) {
+      stdin.setRawMode(true);
+    }
+    let buf = "";
+    const onData = (chunk: Buffer): void => {
+      const ch = chunk.toString("utf-8");
+      if (ch === "\n" || ch === "\r" || ch === "\u0004") {
+        stdin.removeListener("data", onData);
+        if (stdin.isTTY) stdin.setRawMode(wasRaw);
+        process.stdout.write("\n");
+        rl.close();
+        resolve(buf);
+        return;
+      }
+      if (ch === "\u0003") { // ctrl-c
+        process.exit(130);
+      }
+      if (ch === "\u007f") { // backspace
+        buf = buf.slice(0, -1);
+        return;
+      }
+      buf += ch;
+    };
+    stdin.on("data", onData);
+  });
+}
+
+async function deriveKey(pass: string, salt: Buffer, s: Awaited<ReturnType<typeof ensureSodium>>): Promise<Uint8Array> {
+  return s.crypto_pwhash(
+    32,
+    pass,
+    salt,
+    s.crypto_pwhash_OPSLIMIT_INTERACTIVE,
+    s.crypto_pwhash_MEMLIMIT_INTERACTIVE,
+    s.crypto_pwhash_ALG_ARGON2ID13,
+  );
+}
+
+export async function runBackup(outPath: string | undefined): Promise<number> {
+  const configPath = getConfigPath();
+  if (!existsSync(configPath)) {
+    console.error("  No config found — nothing to back up. Join a mesh first.");
+    return EXIT.NOT_FOUND;
+  }
+  const plaintext = readFileSync(configPath);
+
+  const pass = await readHidden("  Passphrase (min 12 chars): ");
+  if (pass.length < 12) {
+    console.error("  ✗ Passphrase too short.");
+    return EXIT.INVALID_ARGS;
+  }
+  const confirm = await readHidden("  Confirm passphrase:       ");
+  if (confirm !== pass) {
+    console.error("  ✗ Passphrases did not match.");
+    return EXIT.INVALID_ARGS;
+  }
+
+  const s = await ensureSodium();
+  const salt = Buffer.from(s.randombytes_buf(16));
+  const nonce = Buffer.from(s.randombytes_buf(24));
+  const key = await deriveKey(pass, salt, s);
+  const ciphertext = Buffer.from(
+    s.crypto_aead_xchacha20poly1305_ietf_encrypt(plaintext, null, null, nonce, key),
+  );
+  const blob = Buffer.concat([MAGIC, salt, nonce, ciphertext]);
+
+  const file = outPath ?? `claudemesh-backup-${new Date().toISOString().replace(/[:.]/g, "-")}.cmb`;
+  writeFileSync(file, blob, { mode: 0o600 });
+  console.log(`\n  ✓ Backup saved: ${file}`);
+  console.log(`  Size: ${blob.length} bytes. Guard the passphrase — there is no recovery.\n`);
+  return EXIT.SUCCESS;
+}
+
+export async function runRestore(inPath: string | undefined): Promise<number> {
+  if (!inPath) {
+    console.error("  Usage: claudemesh restore <backup-file>");
+    return EXIT.INVALID_ARGS;
+  }
+  if (!existsSync(inPath)) {
+    console.error(`  ✗ File not found: ${inPath}`);
+    return EXIT.NOT_FOUND;
+  }
+  const blob = readFileSync(inPath);
+  if (blob.length < 4 + 16 + 24 + 17 || !blob.subarray(0, 4).equals(MAGIC)) {
+    console.error("  ✗ Not a claudemesh backup file (bad magic).");
+    return EXIT.INVALID_ARGS;
+  }
+  const salt = blob.subarray(4, 20);
+  const nonce = blob.subarray(20, 44);
+  const ciphertext = blob.subarray(44);
+
+  const pass = await readHidden("  Passphrase: ");
+  const s = await ensureSodium();
+  const key = await deriveKey(pass, Buffer.from(salt), s);
+  let plaintext: Uint8Array;
+  try {
+    plaintext = s.crypto_aead_xchacha20poly1305_ietf_decrypt(null, ciphertext, null, nonce, key);
+  } catch {
+    console.error("  ✗ Decryption failed — wrong passphrase or tampered file.");
+    return EXIT.INTERNAL_ERROR;
+  }
+
+  const configPath = getConfigPath();
+  if (existsSync(configPath)) {
+    const backupOld = `${configPath}.before-restore.${Date.now()}`;
+    writeFileSync(backupOld, readFileSync(configPath), { mode: 0o600 });
+    console.log(`  ↻ Existing config saved to ${backupOld}`);
+  }
+  writeFileSync(configPath, Buffer.from(plaintext), { mode: 0o600 });
+  console.log(`\n  ✓ Config restored to ${configPath}`);
+  console.log("  Run `claudemesh list` to verify your meshes.\n");
+  return EXIT.SUCCESS;
+}
--- a/apps/cli-v2/src/commands/completions.ts
+++ b/apps/cli-v2/src/commands/completions.ts
@@ -0,0 +1,122 @@
+/**
+ * `claudemesh completions <shell>` — emit a completion script for bash / zsh / fish.
+ *
+ * Users pipe it into their shell's completion system:
+ *   bash: claudemesh completions bash > /etc/bash_completion.d/claudemesh
+ *   zsh:  claudemesh completions zsh > ~/.zfunc/_claudemesh  (add $fpath)
+ *   fish: claudemesh completions fish > ~/.config/fish/completions/claudemesh.fish
+ */
+
+import { EXIT } from "~/constants/exit-codes.js";
+
+const COMMANDS = [
+  "create", "new", "join", "add", "launch", "connect", "disconnect",
+  "list", "ls", "delete", "rm", "rename", "share", "invite",
+  "peers", "send", "inbox", "state", "info",
+  "remember", "recall", "remind", "profile", "status",
+  "login", "register", "logout", "whoami",
+  "install", "uninstall", "doctor", "sync",
+  "completions", "verify", "url-handler",
+  "help",
+];
+
+const FLAGS = [
+  "--help", "-h", "--version", "-V", "--json", "--yes", "-y",
+  "--quiet", "-q", "--mesh", "--name", "--join", "--resume",
+];
+
+function bash(): string {
+  return `# claudemesh bash completion
+_claudemesh_complete() {
+  local cur prev words cword
+  _init_completion || return
+
+  local commands="${COMMANDS.join(" ")}"
+  local flags="${FLAGS.join(" ")}"
+
+  if [[ \${cword} -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "\${commands}" -- "\${cur}") )
+    return 0
+  fi
+
+  case "\${cur}" in
+    -*)
+      COMPREPLY=( $(compgen -W "\${flags}" -- "\${cur}") )
+      return 0
+      ;;
+  esac
+}
+complete -F _claudemesh_complete claudemesh
+`;
+}
+
+function zsh(): string {
+  return `#compdef claudemesh
+# claudemesh zsh completion
+
+_claudemesh() {
+  local -a commands flags
+  commands=(
+${COMMANDS.map((c) => `    '${c}'`).join("\n")}
+  )
+  flags=(
+${FLAGS.map((f) => `    '${f}'`).join("\n")}
+  )
+
+  if (( CURRENT == 2 )); then
+    _describe 'command' commands
+    return
+  fi
+
+  case $words[2] in
+    join|add|launch|connect)
+      _arguments '--name[display name]' '--join[invite url]' '-y[non-interactive]' '--mesh[mesh slug]'
+      ;;
+    share|invite)
+      _arguments '--mesh[mesh slug]' '--json[machine-readable]'
+      ;;
+    *)
+      _values 'flag' $flags
+      ;;
+  esac
+}
+compdef _claudemesh claudemesh
+`;
+}
+
+function fish(): string {
+  const cmdLines = COMMANDS.map(
+    (c) => `complete -c claudemesh -n '__fish_use_subcommand' -a '${c}'`,
+  ).join("\n");
+  return `# claudemesh fish completion
+${cmdLines}
+complete -c claudemesh -l help -s h -d 'show help'
+complete -c claudemesh -l version -s V -d 'show version'
+complete -c claudemesh -l json -d 'machine-readable output'
+complete -c claudemesh -l yes -s y -d 'skip confirmations'
+complete -c claudemesh -l mesh -d 'mesh slug'
+complete -c claudemesh -l name -d 'display name'
+complete -c claudemesh -l join -d 'invite url'
+`;
+}
+
+export async function runCompletions(shell: string | undefined): Promise<number> {
+  if (!shell) {
+    console.error("Usage: claudemesh completions <bash|zsh|fish>");
+    return EXIT.INVALID_ARGS;
+  }
+  switch (shell.toLowerCase()) {
+    case "bash":
+      process.stdout.write(bash());
+      return EXIT.SUCCESS;
+    case "zsh":
+      process.stdout.write(zsh());
+      return EXIT.SUCCESS;
+    case "fish":
+      process.stdout.write(fish());
+      return EXIT.SUCCESS;
+    default:
+      console.error(`Unsupported shell: ${shell}. Use bash, zsh, or fish.`);
+      return EXIT.INVALID_ARGS;
+  }
+}
--- a/apps/cli-v2/src/commands/connect-telegram.ts
+++ b/apps/cli-v2/src/commands/connect-telegram.ts
@@ -0,0 +1,65 @@
+import { readConfig } from "~/services/config/facade.js";
+
+export async function connectTelegram(args: string[]): Promise<void> {
+  const config = readConfig();
+  if (config.meshes.length === 0) {
+    console.error("No meshes joined. Run 'claudemesh join' first.");
+    process.exit(1);
+  }
+
+  const mesh = config.meshes[0]!;
+  const linkOnly = args.includes("--link");
+
+  // Convert WS broker URL to HTTP
+  const brokerHttp = mesh.brokerUrl
+    .replace("wss://", "https://")
+    .replace("ws://", "http://")
+    .replace("/ws", "");
+
+  console.log("Requesting Telegram connect token...");
+
+  const res = await fetch(`${brokerHttp}/tg/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      meshId: mesh.meshId,
+      memberId: mesh.memberId,
+      pubkey: mesh.pubkey,
+      secretKey: mesh.secretKey,
+    }),
+    signal: AbortSignal.timeout(10_000),
+  });
+
+  if (!res.ok) {
+    const err = await res.json().catch(() => ({}));
+    console.error(`Failed: ${(err as any).error ?? res.statusText}`);
+    process.exit(1);
+  }
+
+  const { token, deepLink } = (await res.json()) as {
+    token: string;
+    deepLink: string;
+  };
+
+  if (linkOnly) {
+    console.log(deepLink);
+    return;
+  }
+
+  // Print QR code using simple block characters
+  console.log("\n  Connect Telegram to your mesh:\n");
+  console.log(`  ${deepLink}\n`);
+  console.log("  Open this link on your phone, or scan the QR code");
+  console.log("  with your Telegram camera.\n");
+
+  // Try to generate QR with qrcode-terminal if available
+  try {
+    const QRCode = require("qrcode-terminal");
+    QRCode.generate(deepLink, { small: true }, (code: string) => {
+      console.log(code);
+    });
+  } catch {
+    // qrcode-terminal not available, link is enough
+    console.log("  (Install qrcode-terminal for QR code display)");
+  }
+}
--- a/apps/cli-v2/src/commands/connect.ts
+++ b/apps/cli-v2/src/commands/connect.ts
@@ -0,0 +1,81 @@
+/**
+ * Short-lived WS connection helper for CLI commands (peers, send, inbox, state).
+ *
+ * Opens a connection to one mesh, runs a callback, then closes cleanly.
+ * The caller never deals with connect/close lifecycle.
+ */
+
+import { hostname } from "node:os";
+import { createInterface } from "node:readline";
+import { BrokerClient } from "~/services/broker/facade.js";
+import { readConfig } from "~/services/config/facade.js";
+import type { JoinedMesh } from "~/services/config/facade.js";
+
+export interface ConnectOpts {
+  /** Mesh slug to connect to. Auto-selects if only one mesh joined. */
+  meshSlug?: string | null;
+  /** Display name for this session. Defaults to hostname-pid. */
+  displayName?: string;
+  /** Connect to all meshes and run fn for each. */
+  all?: boolean;
+}
+
+async function pickMesh(meshes: JoinedMesh[]): Promise<JoinedMesh> {
+  console.log("\n  Select mesh:");
+  meshes.forEach((m, i) => {
+    console.log(`    ${i + 1}) ${m.slug}`);
+  });
+  console.log("");
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question("  Choice [1]: ", (answer) => {
+      rl.close();
+      const idx = parseInt(answer || "1", 10) - 1;
+      if (idx >= 0 && idx < meshes.length) {
+        resolve(meshes[idx]!);
+      } else {
+        console.error("  Invalid choice, using first mesh.");
+        resolve(meshes[0]!);
+      }
+    });
+  });
+}
+
+export async function withMesh<T>(
+  opts: ConnectOpts,
+  fn: (client: BrokerClient, mesh: JoinedMesh) => Promise<T>,
+): Promise<T> {
+  const config = readConfig();
+  if (config.meshes.length === 0) {
+    console.error("No meshes joined. Run `claudemesh join <url>` first.");
+    process.exit(1);
+  }
+
+  let mesh: JoinedMesh;
+  if (opts.meshSlug) {
+    const found = config.meshes.find((m) => m.slug === opts.meshSlug);
+    if (!found) {
+      console.error(
+        `Mesh "${opts.meshSlug}" not found. Joined: ${config.meshes.map((m) => m.slug).join(", ")}`,
+      );
+      process.exit(1);
+    }
+    mesh = found;
+  } else if (config.meshes.length === 1) {
+    mesh = config.meshes[0]!;
+  } else {
+    mesh = await pickMesh(config.meshes);
+  }
+
+  const displayName = opts.displayName ?? config.displayName ?? `${hostname()}-${process.pid}`;
+  const client = new BrokerClient(mesh, { displayName });
+
+  try {
+    await client.connect();
+    const result = await fn(client, mesh);
+    return result;
+  } finally {
+    client.close();
+  }
+}
--- a/apps/cli-v2/src/commands/delete-mesh.ts
+++ b/apps/cli-v2/src/commands/delete-mesh.ts
@@ -0,0 +1,128 @@
+import { createInterface } from "node:readline";
+import { readConfig } from "~/services/config/facade.js";
+import { leave as leaveMesh } from "~/services/mesh/facade.js";
+import { getStoredToken } from "~/services/auth/facade.js";
+import { request } from "~/services/api/facade.js";
+import { URLS } from "~/constants/urls.js";
+import { green, red, bold, dim, yellow, icons } from "~/ui/styles.js";
+import { EXIT } from "~/constants/exit-codes.js";
+
+const BROKER_HTTP = URLS.BROKER.replace("wss://", "https://").replace("ws://", "http://").replace("/ws", "");
+
+function prompt(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (a) => { rl.close(); resolve(a.trim()); });
+  });
+}
+
+function getUserId(token: string): string {
+  try {
+    const payload = JSON.parse(Buffer.from(token.split(".")[1]!, "base64url").toString()) as { sub?: string };
+    return payload.sub ?? "";
+  } catch { return ""; }
+}
+
+async function isOwner(slug: string, userId: string): Promise<boolean> {
+  try {
+    const res = await request<{ meshes: Array<{ slug: string; is_owner: boolean }> }>({
+      path: `/cli/meshes?user_id=${userId}`,
+      baseUrl: BROKER_HTTP,
+    });
+    return res.meshes?.find(m => m.slug === slug)?.is_owner ?? false;
+  } catch { return false; }
+}
+
+export async function deleteMesh(slug: string, opts: { yes?: boolean } = {}): Promise<number> {
+  const config = readConfig();
+
+  // Mesh picker if no slug given
+  if (!slug) {
+    if (config.meshes.length === 0) {
+      console.error("  No meshes to remove.");
+      return EXIT.NOT_FOUND;
+    }
+    console.log("\n  Select mesh to remove:\n");
+    config.meshes.forEach((m, i) => {
+      console.log(`    ${bold(String(i + 1) + ")")} ${m.slug} ${dim("(" + m.name + ")")}`);
+    });
+    console.log("");
+    const choice = await prompt("  Choice: ");
+    const idx = parseInt(choice, 10) - 1;
+    if (idx < 0 || idx >= config.meshes.length) {
+      console.log("  Cancelled.");
+      return EXIT.USER_CANCELLED;
+    }
+    slug = config.meshes[idx]!.slug;
+  }
+
+  const auth = getStoredToken();
+  const userId = auth ? getUserId(auth.session_token) : "";
+  const ownerCheck = userId ? await isOwner(slug, userId) : false;
+
+  // Ask what to do
+  if (!opts.yes) {
+    console.log(`\n  ${bold(slug)}\n`);
+
+    if (ownerCheck) {
+      console.log(`    ${bold("1)")} Remove from this device only ${dim("(keep on server)")}`);
+      console.log(`    ${bold("2)")} ${red("Delete everywhere")} ${dim("(removes for all members)")}`);
+      console.log(`    ${bold("3)")} Cancel`);
+      console.log("");
+
+      const choice = await prompt("  Choice [1]: ") || "1";
+
+      if (choice === "3") { console.log("  Cancelled."); return EXIT.USER_CANCELLED; }
+
+      if (choice === "2") {
+        // Server-side delete — require confirmation
+        console.log(`\n  ${red("Warning:")} This will delete ${bold(slug)} for all members.`);
+        const confirm = await prompt(`  Type "${slug}" to confirm: `);
+        if (confirm.toLowerCase() !== slug.toLowerCase()) {
+          console.log("  Cancelled.");
+          return EXIT.USER_CANCELLED;
+        }
+
+        try {
+          await request({
+            path: `/cli/mesh/${slug}`,
+            method: "DELETE",
+            body: { user_id: userId },
+            baseUrl: BROKER_HTTP,
+          });
+          console.log(`  ${green(icons.check)} Deleted "${slug}" from server.`);
+        } catch (err) {
+          const msg = err instanceof Error ? err.message : String(err);
+          console.error(`  ${icons.cross} Server delete failed: ${msg}`);
+        }
+
+        leaveMesh(slug);
+        console.log(`  ${green(icons.check)} Removed from local config.`);
+        return EXIT.SUCCESS;
+      }
+
+      // choice === "1" — local only, fall through
+    } else {
+      // Not owner — can only remove locally
+      console.log(`    ${bold("1)")} Remove from this device ${dim("(you can re-add later)")}`);
+      console.log(`    ${bold("2)")} Cancel`);
+      if (!ownerCheck && userId) {
+        console.log(dim(`\n    ${yellow(icons.warn)} Only the mesh owner can delete it from the server.`));
+      }
+      console.log("");
+
+      const choice = await prompt("  Choice [1]: ") || "1";
+      if (choice === "2") { console.log("  Cancelled."); return EXIT.USER_CANCELLED; }
+    }
+  }
+
+  // Local-only removal
+  const removed = leaveMesh(slug);
+  if (removed) {
+    console.log(`  ${green(icons.check)} Removed "${slug}" from this device.`);
+    console.log(dim(`    Re-add anytime with: claudemesh mesh add <invite-url>`));
+  } else {
+    console.error(`  Mesh "${slug}" not found in local config.`);
+  }
+  return EXIT.SUCCESS;
+}
--- a/apps/cli-v2/src/commands/doctor.ts
+++ b/apps/cli-v2/src/commands/doctor.ts
@@ -0,0 +1,281 @@
+/**
+ * `claudemesh doctor` — diagnostic checks.
+ *
+ * Walks through the install + runtime preconditions and prints each
+ * as pass/fail with a fix hint on failure. Exit 0 if everything
+ * passes, 1 otherwise.
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { homedir, platform } from "node:os";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { readConfig, getConfigPath } from "~/services/config/facade.js";
+import { VERSION, URLS } from "~/constants/urls.js";
+
+interface Check {
+  name: string;
+  pass: boolean;
+  detail?: string;
+  fix?: string;
+}
+
+function checkNode(): Check {
+  const major = Number(process.versions.node.split(".")[0]);
+  return {
+    name: "Node.js >= 20",
+    pass: major >= 20,
+    detail: `v${process.versions.node}`,
+    fix: "Install Node 20 or newer (https://nodejs.org)",
+  };
+}
+
+function checkClaudeOnPath(): Check {
+  const res =
+    platform() === "win32"
+      ? spawnSync("where", ["claude"])
+      : spawnSync("sh", ["-c", "command -v claude"]);
+  const onPath = res.status === 0;
+  const location = onPath ? res.stdout.toString().trim().split("\n")[0] : undefined;
+  return {
+    name: "claude binary on PATH",
+    pass: onPath,
+    detail: location,
+    fix: "Install Claude Code (https://claude.com/claude-code)",
+  };
+}
+
+function checkMcpRegistered(): Check {
+  const claudeConfig = join(homedir(), ".claude.json");
+  if (!existsSync(claudeConfig)) {
+    return {
+      name: "claudemesh MCP registered in ~/.claude.json",
+      pass: false,
+      fix: "Run `claudemesh install`",
+    };
+  }
+  try {
+    const cfg = JSON.parse(readFileSync(claudeConfig, "utf-8")) as {
+      mcpServers?: Record<string, unknown>;
+    };
+    const registered = Boolean(cfg.mcpServers?.["claudemesh"]);
+    return {
+      name: "claudemesh MCP registered in ~/.claude.json",
+      pass: registered,
+      fix: registered ? undefined : "Run `claudemesh install`",
+    };
+  } catch (e) {
+    return {
+      name: "claudemesh MCP registered in ~/.claude.json",
+      pass: false,
+      detail: e instanceof Error ? e.message : String(e),
+      fix: "Check ~/.claude.json for JSON parse errors",
+    };
+  }
+}
+
+function checkHooksRegistered(): Check {
+  const settings = join(homedir(), ".claude", "settings.json");
+  if (!existsSync(settings)) {
+    return {
+      name: "Status hooks registered in ~/.claude/settings.json",
+      pass: false,
+      fix: "Run `claudemesh install` (remove --no-hooks)",
+    };
+  }
+  try {
+    const raw = readFileSync(settings, "utf-8");
+    const has = raw.includes("claudemesh hook ");
+    return {
+      name: "Status hooks registered in ~/.claude/settings.json",
+      pass: has,
+      fix: has ? undefined : "Run `claudemesh install` (remove --no-hooks)",
+    };
+  } catch (e) {
+    return {
+      name: "Status hooks registered in ~/.claude/settings.json",
+      pass: false,
+      detail: e instanceof Error ? e.message : String(e),
+    };
+  }
+}
+
+function checkConfigFile(): Check {
+  const path = getConfigPath();
+  if (!existsSync(path)) {
+    return {
+      name: "~/.claudemesh/config.json exists and parses",
+      pass: true,
+      detail: "not created yet (fine — no meshes joined)",
+    };
+  }
+  try {
+    readConfig();
+    const st = statSync(path);
+    const mode = (st.mode & 0o777).toString(8);
+    const secure = platform() === "win32" || mode === "600";
+    return {
+      name: "~/.claudemesh/config.json parses + chmod 0600",
+      pass: secure,
+      detail: platform() === "win32" ? "chmod skipped on Windows" : `0${mode}`,
+      fix: secure ? undefined : `chmod 600 ${path}`,
+    };
+  } catch (e) {
+    return {
+      name: "~/.claudemesh/config.json exists and parses",
+      pass: false,
+      detail: e instanceof Error ? e.message : String(e),
+      fix: "Inspect or delete ~/.claudemesh/config.json and re-join",
+    };
+  }
+}
+
+function checkKeypairs(): Check {
+  try {
+    const cfg = readConfig();
+    if (cfg.meshes.length === 0) {
+      return {
+        name: "Mesh keypairs valid",
+        pass: true,
+        detail: "no meshes joined",
+      };
+    }
+    for (const m of cfg.meshes) {
+      if (m.pubkey.length !== 64 || !/^[0-9a-f]+$/.test(m.pubkey)) {
+        return {
+          name: "Mesh keypairs valid",
+          pass: false,
+          detail: `${m.slug}: pubkey malformed`,
+          fix: `Leave + re-join the mesh: claudemesh leave ${m.slug}`,
+        };
+      }
+      if (m.secretKey.length !== 128 || !/^[0-9a-f]+$/.test(m.secretKey)) {
+        return {
+          name: "Mesh keypairs valid",
+          pass: false,
+          detail: `${m.slug}: secret key malformed`,
+          fix: `Leave + re-join the mesh: claudemesh leave ${m.slug}`,
+        };
+      }
+    }
+    return {
+      name: "Mesh keypairs valid",
+      pass: true,
+      detail: `${cfg.meshes.length} mesh(es)`,
+    };
+  } catch (e) {
+    return {
+      name: "Mesh keypairs valid",
+      pass: false,
+      detail: e instanceof Error ? e.message : String(e),
+    };
+  }
+}
+
+async function checkBrokerWs(): Promise<Check> {
+  const wsUrl = URLS.BROKER;
+  const start = Date.now();
+  try {
+    const WebSocket = (await import("ws")).default;
+    const ws = new WebSocket(wsUrl);
+    const result = await new Promise<Check>((resolve) => {
+      const timer = setTimeout(() => {
+        try { ws.close(); } catch { /* noop */ }
+        resolve({
+          name: "Broker WebSocket reachable",
+          pass: false,
+          detail: `timeout after 5s (${wsUrl})`,
+          fix: "Check firewall/proxy. Broker at ic.claudemesh.com:443 over WSS.",
+        });
+      }, 5000);
+      ws.once("open", () => {
+        clearTimeout(timer);
+        const latency = Date.now() - start;
+        try { ws.close(); } catch { /* noop */ }
+        resolve({
+          name: "Broker WebSocket reachable",
+          pass: true,
+          detail: `${latency}ms to ${wsUrl}`,
+        });
+      });
+      ws.once("error", (e) => {
+        clearTimeout(timer);
+        resolve({
+          name: "Broker WebSocket reachable",
+          pass: false,
+          detail: e.message,
+          fix: "Check network. Broker URL can be overridden via CLAUDEMESH_BROKER_URL.",
+        });
+      });
+    });
+    return result;
+  } catch (e) {
+    return {
+      name: "Broker WebSocket reachable",
+      pass: false,
+      detail: e instanceof Error ? e.message : String(e),
+    };
+  }
+}
+
+async function checkNpmLatest(): Promise<Check> {
+  try {
+    const res = await fetch(URLS.NPM_REGISTRY, { signal: AbortSignal.timeout(5000) });
+    if (!res.ok) {
+      return { name: "CLI up-to-date", pass: true, detail: `npm unreachable (${res.status}) — skipped` };
+    }
+    const body = (await res.json()) as { "dist-tags"?: { alpha?: string; latest?: string } };
+    const latest = body["dist-tags"]?.alpha ?? body["dist-tags"]?.latest;
+    if (!latest) return { name: "CLI up-to-date", pass: true, detail: "no dist-tag — skipped" };
+    const up = latest === VERSION;
+    return {
+      name: "CLI up-to-date",
+      pass: up,
+      detail: up ? `latest ${latest}` : `installed ${VERSION} → latest ${latest}`,
+      fix: up ? undefined : "npm i -g claudemesh-cli@alpha",
+    };
+  } catch {
+    return { name: "CLI up-to-date", pass: true, detail: "npm check skipped" };
+  }
+}
+
+export async function runDoctor(): Promise<void> {
+  const useColor =
+    !process.env.NO_COLOR && process.env.TERM !== "dumb" && process.stdout.isTTY;
+  const dim = (s: string): string => (useColor ? `\x1b[2m${s}\x1b[22m` : s);
+  const green = (s: string): string => (useColor ? `\x1b[32m${s}\x1b[39m` : s);
+  const red = (s: string): string => (useColor ? `\x1b[31m${s}\x1b[39m` : s);
+
+  console.log(`claudemesh doctor  (v${VERSION})`);
+  console.log("─".repeat(60));
+
+  const checks: Check[] = [
+    checkNode(),
+    checkClaudeOnPath(),
+    checkMcpRegistered(),
+    checkHooksRegistered(),
+    checkConfigFile(),
+    checkKeypairs(),
+    await checkBrokerWs(),
+    await checkNpmLatest(),
+  ];
+
+  for (const c of checks) {
+    const mark = c.pass ? green("✓") : red("✗");
+    const detail = c.detail ? dim(` (${c.detail})`) : "";
+    console.log(`${mark} ${c.name}${detail}`);
+    if (!c.pass && c.fix) {
+      console.log(dim(`   → ${c.fix}`));
+    }
+  }
+
+  const failing = checks.filter((c) => !c.pass);
+  console.log("");
+  if (failing.length === 0) {
+    console.log(green("All checks passed."));
+    process.exit(0);
+  } else {
+    console.log(red(`${failing.length} check(s) failed.`));
+    process.exit(1);
+  }
+}
--- a/apps/cli-v2/src/commands/grants.ts
+++ b/apps/cli-v2/src/commands/grants.ts
@@ -0,0 +1,176 @@
+/**
+ * `claudemesh grant / revoke / grants / block` — per-peer capability grants.
+ *
+ * Claudemesh's original threat model treats all mesh members as trusted, so
+ * every peer can send you messages and read your summary. These commands add
+ * a local filter: the broker still forwards messages, but the MCP server
+ * drops disallowed kinds before they reach Claude Code.
+ *
+ * Grants are stored in ~/.claudemesh/grants.json keyed on
+ * (mesh_slug, peer_pubkey). Default = read + dm (backwards-compatible).
+ * The `block` command sets an empty grant set (equivalent to revoke-all).
+ *
+ * Full grant-enforcement on the broker side is out of scope for this pass
+ * — see .artifacts/specs/2026-04-15-per-peer-capabilities.md for the
+ * server-side rollout plan. Client-side enforcement handles the 80% case
+ * (spam / noise) without needing a broker migration.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readConfig } from "~/services/config/facade.js";
+import { withMesh } from "./connect.js";
+import { render } from "~/ui/render.js";
+import { EXIT } from "~/constants/exit-codes.js";
+
+export type Capability =
+  | "read"
+  | "dm"
+  | "broadcast"
+  | "state-read"
+  | "state-write"
+  | "file-read";
+
+const ALL_CAPS: Capability[] = ["read", "dm", "broadcast", "state-read", "state-write", "file-read"];
+const DEFAULT_CAPS: Capability[] = ["read", "dm", "broadcast", "state-read"];
+
+type GrantStore = Record<string, Record<string, Capability[]>>; // mesh → pubkey → caps
+
+const GRANT_FILE = join(homedir(), ".claudemesh", "grants.json");
+
+function readGrants(): GrantStore {
+  if (!existsSync(GRANT_FILE)) return {};
+  try {
+    return JSON.parse(readFileSync(GRANT_FILE, "utf-8")) as GrantStore;
+  } catch {
+    return {};
+  }
+}
+
+function writeGrants(g: GrantStore): void {
+  const dir = join(homedir(), ".claudemesh");
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  writeFileSync(GRANT_FILE, JSON.stringify(g, null, 2), { mode: 0o600 });
+}
+
+function resolveCaps(input: string[]): Capability[] {
+  if (input.includes("all")) return [...ALL_CAPS];
+  return input.filter((c): c is Capability => (ALL_CAPS as string[]).includes(c));
+}
+
+async function resolvePeer(meshSlug: string, name: string): Promise<{ displayName: string; pubkey: string } | null> {
+  return await withMesh({ meshSlug }, async (client) => {
+    const peers = await client.listPeers();
+    const match = peers.find((p) => p.displayName === name || p.pubkey === name || p.pubkey.startsWith(name));
+    return match ? { displayName: match.displayName, pubkey: match.pubkey } : null;
+  });
+}
+
+function pickMesh(slug?: string): string | null {
+  const cfg = readConfig();
+  if (slug) return cfg.meshes.find((m) => m.slug === slug) ? slug : null;
+  return cfg.meshes[0]?.slug ?? null;
+}
+
+export async function runGrant(peer: string | undefined, caps: string[], opts: { mesh?: string } = {}): Promise<number> {
+  if (!peer || caps.length === 0) {
+    render.err("Usage: claudemesh grant <peer> <capability...>");
+    render.hint(`Capabilities: ${ALL_CAPS.join(", ")}, all`);
+    return EXIT.INVALID_ARGS;
+  }
+  const mesh = pickMesh(opts.mesh);
+  if (!mesh) { render.err("No matching mesh — join one first."); return EXIT.NOT_FOUND; }
+  const resolved = await resolvePeer(mesh, peer);
+  if (!resolved) { render.err(`Peer "${peer}" not found on ${mesh}.`); return EXIT.NOT_FOUND; }
+  const wanted = resolveCaps(caps);
+  if (wanted.length === 0) { render.err(`Unknown capabilities: ${caps.join(", ")}`); return EXIT.INVALID_ARGS; }
+
+  const store = readGrants();
+  const meshGrants = store[mesh] ?? {};
+  const existing = meshGrants[resolved.pubkey] ?? DEFAULT_CAPS.slice();
+  const merged = Array.from(new Set([...existing, ...wanted]));
+  meshGrants[resolved.pubkey] = merged;
+  store[mesh] = meshGrants;
+  writeGrants(store);
+
+  render.ok(`Granted ${wanted.join(", ")} to ${resolved.displayName} on ${mesh}.`);
+  render.kv([["now", merged.join(", ")]]);
+  return EXIT.SUCCESS;
+}
+
+export async function runRevoke(peer: string | undefined, caps: string[], opts: { mesh?: string } = {}): Promise<number> {
+  if (!peer || caps.length === 0) {
+    render.err("Usage: claudemesh revoke <peer> <capability...>");
+    return EXIT.INVALID_ARGS;
+  }
+  const mesh = pickMesh(opts.mesh);
+  if (!mesh) { render.err("No matching mesh."); return EXIT.NOT_FOUND; }
+  const resolved = await resolvePeer(mesh, peer);
+  if (!resolved) { render.err(`Peer "${peer}" not found on ${mesh}.`); return EXIT.NOT_FOUND; }
+  const wanted = caps.includes("all") ? ALL_CAPS.slice() : resolveCaps(caps);
+
+  const store = readGrants();
+  const meshGrants = store[mesh] ?? {};
+  const existing = meshGrants[resolved.pubkey] ?? DEFAULT_CAPS.slice();
+  const after = existing.filter((c) => !wanted.includes(c));
+  meshGrants[resolved.pubkey] = after;
+  store[mesh] = meshGrants;
+  writeGrants(store);
+
+  render.ok(`Revoked ${wanted.join(", ")} from ${resolved.displayName} on ${mesh}.`);
+  render.kv([["now", after.length ? after.join(", ") : "(none)"]]);
+  return EXIT.SUCCESS;
+}
+
+export async function runBlock(peer: string | undefined, opts: { mesh?: string } = {}): Promise<number> {
+  if (!peer) { render.err("Usage: claudemesh block <peer>"); return EXIT.INVALID_ARGS; }
+  const mesh = pickMesh(opts.mesh);
+  if (!mesh) { render.err("No matching mesh."); return EXIT.NOT_FOUND; }
+  const resolved = await resolvePeer(mesh, peer);
+  if (!resolved) { render.err(`Peer "${peer}" not found on ${mesh}.`); return EXIT.NOT_FOUND; }
+  const store = readGrants();
+  const meshGrants = store[mesh] ?? {};
+  meshGrants[resolved.pubkey] = [];
+  store[mesh] = meshGrants;
+  writeGrants(store);
+  render.ok(`Blocked ${resolved.displayName} on ${mesh} (all capabilities revoked).`);
+  render.hint(`Undo with: claudemesh grant ${resolved.displayName} all --mesh ${mesh}`);
+  return EXIT.SUCCESS;
+}
+
+export async function runGrants(opts: { mesh?: string; json?: boolean } = {}): Promise<number> {
+  const mesh = pickMesh(opts.mesh);
+  if (!mesh) { render.err("No matching mesh."); return EXIT.NOT_FOUND; }
+  const store = readGrants();
+  const meshGrants = store[mesh] ?? {};
+
+  if (opts.json) {
+    console.log(JSON.stringify({ schema_version: "1.0", mesh, grants: meshGrants }, null, 2));
+    return EXIT.SUCCESS;
+  }
+
+  render.section(`grants on ${mesh}`);
+  const peerPubkeys = Object.keys(meshGrants);
+  if (peerPubkeys.length === 0) {
+    render.info("(no overrides — all peers use default caps: " + DEFAULT_CAPS.join(", ") + ")");
+    return EXIT.SUCCESS;
+  }
+  await withMesh({ meshSlug: mesh }, async (client) => {
+    const peers = await client.listPeers();
+    const byPk = new Map(peers.map((p) => [p.pubkey, p.displayName]));
+    for (const [pk, caps] of Object.entries(meshGrants)) {
+      const name = byPk.get(pk) ?? `${pk.slice(0, 10)}…`;
+      render.kv([[name, caps.length ? caps.join(", ") : "(blocked)"]]);
+    }
+  });
+  return EXIT.SUCCESS;
+}
+
+/** Used by the MCP inbound-message path. Returns true if the capability is allowed. */
+export function isAllowed(meshSlug: string, peerPubkey: string, cap: Capability): boolean {
+  const store = readGrants();
+  const entry = store[meshSlug]?.[peerPubkey];
+  if (entry === undefined) return DEFAULT_CAPS.includes(cap);
+  return entry.includes(cap);
+}
--- a/apps/cli-v2/src/commands/hook.ts
+++ b/apps/cli-v2/src/commands/hook.ts
@@ -0,0 +1,123 @@
+/**
+ * `claudemesh hook <status>` — Claude Code hook handler.
+ *
+ * Registered as a Stop + UserPromptSubmit hook by `claudemesh install`.
+ * On each turn boundary, Claude Code invokes:
+ *
+ *   Stop              → `claudemesh hook idle`
+ *   UserPromptSubmit  → `claudemesh hook working`
+ *
+ * We read the Claude Code hook JSON payload from stdin (contains cwd +
+ * session_id), then POST `/hook/set-status` to EVERY joined mesh's
+ * broker with {cwd, pid, status, session_id}. Each broker looks up
+ * its local presence row by (pid, cwd) and updates status.
+ *
+ * Fire-and-forget, silent. Hooks must NEVER block Claude Code or
+ * surface errors to the user. Debug logging available via
+ * CLAUDEMESH_HOOK_DEBUG=1.
+ *
+ * Why send to every broker? A user joined to multiple meshes has
+ * one presence row per mesh, each on its own broker. A turn boundary
+ * updates the status on every broker where this session is active.
+ * Brokers that don't have a matching presence just queue the signal
+ * in pending_status (harmless, TTL-swept).
+ */
+
+import { readConfig } from "~/services/config/facade.js";
+
+const DEBUG = process.env.CLAUDEMESH_HOOK_DEBUG === "1";
+
+function debug(msg: string): void {
+  if (DEBUG) console.error(`[claudemesh-hook] ${msg}`);
+}
+
+/** WS URL → HTTP URL (same host, swap scheme). */
+function wsToHttp(wsUrl: string): string {
+  try {
+    const u = new URL(wsUrl);
+    const httpScheme = u.protocol === "wss:" ? "https:" : "http:";
+    return `${httpScheme}//${u.host}`;
+  } catch {
+    return wsUrl;
+  }
+}
+
+async function readStdinJson(): Promise<Record<string, unknown>> {
+  if (process.stdin.isTTY) return {};
+  const chunks: Uint8Array[] = [];
+  const reader = process.stdin;
+  try {
+    for await (const chunk of reader) {
+      chunks.push(chunk as Uint8Array);
+      if (chunks.reduce((n, c) => n + c.length, 0) > 256 * 1024) break;
+    }
+    const raw = Buffer.concat(chunks).toString("utf-8").trim();
+    if (!raw) return {};
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return {};
+  }
+}
+
+async function postHook(
+  brokerWsUrl: string,
+  body: Record<string, unknown>,
+): Promise<void> {
+  const base = wsToHttp(brokerWsUrl);
+  try {
+    const controller = new AbortController();
+    const t = setTimeout(() => controller.abort(), 1000);
+    await fetch(`${base}/hook/set-status`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+      signal: controller.signal,
+    }).finally(() => clearTimeout(t));
+  } catch (e) {
+    debug(`post failed ${base}: ${e instanceof Error ? e.message : e}`);
+  }
+}
+
+export async function runHook(args: string[]): Promise<void> {
+  const status = args[0];
+  if (!status || !["idle", "working", "dnd"].includes(status)) {
+    // Silent no-op — we never want a hook to surface an error.
+    process.exit(0);
+  }
+
+  // Read Claude Code's stdin payload for cwd + session_id.
+  const stdinTimeout = new Promise<Record<string, unknown>>((r) =>
+    setTimeout(() => r({}), 500),
+  );
+  const payload = await Promise.race([readStdinJson(), stdinTimeout]);
+  const cwd =
+    (typeof payload.cwd === "string" && payload.cwd) ||
+    process.env.CLAUDE_PROJECT_DIR ||
+    process.cwd();
+  const sessionId =
+    (typeof payload.session_id === "string" && payload.session_id) || "";
+
+  // Fan out to EVERY joined mesh's broker in parallel.
+  let config;
+  try {
+    config = readConfig();
+  } catch (e) {
+    debug(`config load failed: ${e instanceof Error ? e.message : e}`);
+    process.exit(0);
+  }
+  if (config.meshes.length === 0) {
+    debug("no joined meshes, nothing to do");
+    process.exit(0);
+  }
+
+  const body = { cwd, pid: process.ppid, status, session_id: sessionId };
+  debug(
+    `status=${status} cwd=${cwd} meshes=${config.meshes.length} session=${sessionId.slice(0, 8)}`,
+  );
+
+  // Dedupe by brokerUrl — if multiple meshes share a broker, one POST
+  // covers them (broker resolves presence by cwd+pid regardless).
+  const brokerUrls = [...new Set(config.meshes.map((m) => m.brokerUrl))];
+  await Promise.all(brokerUrls.map((url) => postHook(url, body)));
+  process.exit(0);
+}
--- a/apps/cli-v2/src/commands/inbox.ts
+++ b/apps/cli-v2/src/commands/inbox.ts
@@ -0,0 +1,60 @@
+/**
+ * `claudemesh inbox` — read pending peer messages.
+ *
+ * Connects, waits briefly for push delivery, drains the buffer, prints.
+ * Works best when message-mode is "inbox" or "off" (messages held at broker).
+ */
+
+import { withMesh } from "./connect.js";
+import type { InboundPush } from "~/services/broker/facade.js";
+
+export interface InboxFlags {
+  mesh?: string;
+  json?: boolean;
+  wait?: number;
+}
+
+function formatMessage(msg: InboundPush, useColor: boolean): string {
+  const dim = (s: string) => (useColor ? `\x1b[2m${s}\x1b[22m` : s);
+  const bold = (s: string) => (useColor ? `\x1b[1m${s}\x1b[22m` : s);
+
+  const text = msg.plaintext ?? `[encrypted: ${msg.ciphertext.slice(0, 32)}…]`;
+  const from = msg.senderPubkey.slice(0, 8);
+  const time = new Date(msg.createdAt).toLocaleTimeString();
+  const kindTag = msg.kind === "direct" ? "→ direct" : msg.kind;
+
+  return `  ${bold(from)} ${dim(`[${kindTag}] ${time}`)}\n  ${text}`;
+}
+
+export async function runInbox(flags: InboxFlags): Promise<void> {
+  const useColor =
+    !process.env.NO_COLOR && process.env.TERM !== "dumb" && process.stdout.isTTY;
+  const dim = (s: string) => (useColor ? `\x1b[2m${s}\x1b[22m` : s);
+  const bold = (s: string) => (useColor ? `\x1b[1m${s}\x1b[22m` : s);
+
+  const waitMs = (flags.wait ?? 1) * 1000;
+
+  await withMesh({ meshSlug: flags.mesh ?? null }, async (client, mesh) => {
+    // Wait briefly for broker to push any held messages.
+    await new Promise<void>((resolve) => setTimeout(resolve, waitMs));
+
+    const messages = client.drainPushBuffer();
+
+    if (flags.json) {
+      console.log(JSON.stringify(messages, null, 2));
+      return;
+    }
+
+    if (messages.length === 0) {
+      console.log(dim(`No messages on mesh "${mesh.slug}".`));
+      return;
+    }
+
+    console.log(bold(`Inbox — ${mesh.slug}`) + dim(` (${messages.length} message${messages.length === 1 ? "" : "s"})`));
+    console.log("");
+    for (const msg of messages) {
+      console.log(formatMessage(msg, useColor));
+      console.log("");
+    }
+  });
+}
--- a/apps/cli-v2/src/commands/index.ts
+++ b/apps/cli-v2/src/commands/index.ts
@@ -0,0 +1,29 @@
+export { runJoin } from "./join.js";
+export { newMesh } from "./new.js";
+export { invite } from "./invite.js";
+export { runList } from "./list.js";
+export { rename } from "./rename.js";
+export { runLeave } from "./leave.js";
+export { runPeers } from "./peers.js";
+export { runSend } from "./send.js";
+export { runInbox } from "./inbox.js";
+export { runStateGet, runStateSet } from "./state.js";
+export { runInfo } from "./info.js";
+export { remember } from "./remember.js";
+export { recall } from "./recall.js";
+export { runRemind } from "./remind.js";
+export { runProfile } from "./profile.js";
+export { runStatus } from "./status.js";
+export { runDoctor } from "./doctor.js";
+export { register } from "./register.js";
+export { login } from "./login.js";
+export { logout } from "./logout.js";
+export { whoami } from "./whoami.js";
+export { runInstall } from "./install.js";
+export { uninstall } from "./uninstall.js";
+export { runSync } from "./sync.js";
+export { runWelcome } from "./welcome.js";
+export { runHook } from "./hook.js";
+export { runMcp } from "./mcp.js";
+export { runSeedTestMesh } from "./seed-test-mesh.js";
+export { withMesh } from "./connect.js";
--- a/apps/cli-v2/src/commands/info.ts
+++ b/apps/cli-v2/src/commands/info.ts
@@ -0,0 +1,58 @@
+/**
+ * `claudemesh info` — show mesh overview: slug, broker URL, peer count, state count.
+ *
+ * Useful for AI agents to orient themselves in a mesh via bash.
+ */
+
+import { withMesh } from "./connect.js";
+import { readConfig } from "~/services/config/facade.js";
+
+export interface InfoFlags {
+  mesh?: string;
+  json?: boolean;
+}
+
+export async function runInfo(flags: InfoFlags): Promise<void> {
+  const useColor =
+    !process.env.NO_COLOR && process.env.TERM !== "dumb" && process.stdout.isTTY;
+  const dim = (s: string) => (useColor ? `\x1b[2m${s}\x1b[22m` : s);
+  const bold = (s: string) => (useColor ? `\x1b[1m${s}\x1b[22m` : s);
+
+  const config = readConfig();
+
+  await withMesh({ meshSlug: flags.mesh ?? null }, async (client, mesh) => {
+    const [brokerInfo, peers, state] = await Promise.all([
+      client.meshInfo(),
+      client.listPeers(),
+      client.listState(),
+    ]);
+
+    const output = {
+      slug: mesh.slug,
+      meshId: mesh.meshId,
+      memberId: mesh.memberId,
+      brokerUrl: mesh.brokerUrl,
+      displayName: config.displayName ?? null,
+      peerCount: peers.length,
+      stateCount: state.length,
+      ...(brokerInfo ?? {}),
+    };
+
+    if (flags.json) {
+      console.log(JSON.stringify(output, null, 2));
+      return;
+    }
+
+    console.log(bold(mesh.slug) + dim(` · ${mesh.brokerUrl}`));
+    console.log(dim(`  mesh:   ${mesh.meshId}`));
+    console.log(dim(`  member: ${mesh.memberId}`));
+    console.log(`  peers:  ${peers.length} connected`);
+    console.log(`  state:  ${state.length} keys`);
+    if (brokerInfo && typeof brokerInfo === "object") {
+      for (const [k, v] of Object.entries(brokerInfo)) {
+        if (["slug", "meshId", "brokerUrl"].includes(k)) continue;
+        console.log(dim(`  ${k}: ${JSON.stringify(v)}`));
+      }
+    }
+  });
+}
--- a/apps/cli-v2/src/commands/install.ts
+++ b/apps/cli-v2/src/commands/install.ts
@@ -0,0 +1,564 @@
+/**
+ * `claudemesh install` / `uninstall` — manage Claude Code MCP registration.
+ *
+ * install:
+ *   1. Preflight: bun is on PATH, this package's MCP entry is on disk.
+ *   2. Read ~/.claude.json (or empty object if absent).
+ *   3. Add/update `mcpServers.claudemesh` with the resolved entry path.
+ *   4. Write back with 0600 perms.
+ *   5. Verify via read-back, print success.
+ *
+ * uninstall:
+ *   1. Read ~/.claude.json (bail if missing).
+ *   2. Delete `mcpServers.claudemesh` if present.
+ *   3. Write back.
+ *
+ * Both are idempotent — re-running install is a no-op if the entry is
+ * already correct, and uninstall is a no-op if no entry exists.
+ */
+
+import {
+  chmodSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir, platform } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+import { readConfig } from "~/services/config/facade.js";
+
+const MCP_NAME = "claudemesh";
+const CLAUDE_CONFIG = join(homedir(), ".claude.json");
+const CLAUDE_SETTINGS = join(homedir(), ".claude", "settings.json");
+const HOOK_COMMAND_STOP = "claudemesh hook idle";
+const HOOK_COMMAND_USER_PROMPT = "claudemesh hook working";
+const HOOK_MARKER = "claudemesh hook ";
+
+type McpEntry = {
+  command: string;
+  args?: string[];
+  env?: Record<string, string>;
+};
+
+interface HookCommand {
+  type: "command";
+  command: string;
+}
+interface HookMatcher {
+  matcher?: string;
+  hooks: HookCommand[];
+}
+type HooksConfig = Record<string, HookMatcher[]>;
+
+function readClaudeConfig(): Record<string, unknown> {
+  if (!existsSync(CLAUDE_CONFIG)) return {};
+  const text = readFileSync(CLAUDE_CONFIG, "utf-8").trim();
+  if (!text) return {};
+  try {
+    return JSON.parse(text) as Record<string, unknown>;
+  } catch (e) {
+    throw new Error(
+      `failed to parse ${CLAUDE_CONFIG}: ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+}
+
+/**
+ * Create a timestamped backup of ~/.claude.json before any write.
+ */
+function backupClaudeConfig(): void {
+  if (!existsSync(CLAUDE_CONFIG)) return;
+  const backupDir = join(dirname(CLAUDE_CONFIG), ".claude", "backups");
+  mkdirSync(backupDir, { recursive: true });
+  const ts = Date.now();
+  const dest = join(backupDir, `.claude.json.pre-claudemesh.${ts}`);
+  copyFileSync(CLAUDE_CONFIG, dest);
+}
+
+/**
+ * Atomic read-merge-write: re-reads ~/.claude.json at write time and
+ * patches ONLY the `claudemesh` MCP entry. Never touches other keys.
+ * Returns the action taken ("added" | "updated" | "unchanged").
+ */
+function patchMcpServer(entry: McpEntry): "added" | "updated" | "unchanged" {
+  backupClaudeConfig();
+  const cfg = readClaudeConfig();
+  const servers =
+    ((cfg.mcpServers as Record<string, McpEntry>) ?? {});
+  if (!cfg.mcpServers) cfg.mcpServers = servers;
+
+  const existing = servers[MCP_NAME];
+  let action: "added" | "updated" | "unchanged";
+  if (!existing) {
+    servers[MCP_NAME] = entry;
+    action = "added";
+  } else if (entriesEqual(existing, entry)) {
+    return "unchanged";
+  } else {
+    servers[MCP_NAME] = entry;
+    action = "updated";
+  }
+
+  flushClaudeConfig(cfg);
+  return action;
+}
+
+/**
+ * Atomic read-merge-write: re-reads ~/.claude.json at write time and
+ * removes ONLY the `claudemesh` MCP entry. Never touches other keys.
+ * Returns true if an entry was removed.
+ */
+function removeMcpServer(): boolean {
+  if (!existsSync(CLAUDE_CONFIG)) return false;
+  backupClaudeConfig();
+  const cfg = readClaudeConfig();
+  const servers = cfg.mcpServers as Record<string, McpEntry> | undefined;
+  if (!servers || !(MCP_NAME in servers)) return false;
+  delete servers[MCP_NAME];
+  cfg.mcpServers = servers;
+  flushClaudeConfig(cfg);
+  return true;
+}
+
+/** Low-level write — callers must backup + merge first. */
+function flushClaudeConfig(obj: Record<string, unknown>): void {
+  mkdirSync(dirname(CLAUDE_CONFIG), { recursive: true });
+  writeFileSync(
+    CLAUDE_CONFIG,
+    JSON.stringify(obj, null, 2) + "\n",
+    "utf-8",
+  );
+  try {
+    chmodSync(CLAUDE_CONFIG, 0o600);
+  } catch {
+    /* windows has no chmod */
+  }
+}
+
+
+/** Check `bun` is on PATH — OS-agnostic, node:child_process. */
+function bunAvailable(): boolean {
+  const res =
+    platform() === "win32"
+      ? spawnSync("where", ["bun"])
+      : spawnSync("sh", ["-c", "command -v bun"]);
+  return res.status === 0;
+}
+
+/** Absolute path to this CLI's entry file. */
+function resolveEntry(): string {
+  const here = fileURLToPath(import.meta.url);
+  // When bundled (dist/index.js), this file IS the entry → return self.
+  // When running from source (src/index.ts via bun), walk up to the
+  // dir + resolve index.ts.
+  if (here.endsWith("/dist/index.js") || here.endsWith("\\dist\\index.js")) {
+    return here;
+  }
+  return resolve(dirname(here), "..", "index.ts");
+}
+
+/**
+ * Build the MCP server entry for Claude Code's config.
+ *
+ * Two modes:
+ *   - Installed globally (npm i -g claudemesh-cli): use `claudemesh`
+ *     as the command, relies on it being on PATH.
+ *   - Local dev (bun apps/cli/src/index.ts): use `bun <absolute-path>`.
+ */
+function buildMcpEntry(entryPath: string): McpEntry {
+  const isBundled = entryPath.endsWith("/dist/index.js") ||
+    entryPath.endsWith("\\dist\\index.js");
+  if (isBundled) {
+    return {
+      command: "claudemesh",
+      args: ["mcp"],
+    };
+  }
+  return {
+    command: "bun",
+    args: [entryPath, "mcp"],
+  };
+}
+
+function entriesEqual(a: McpEntry, b: McpEntry): boolean {
+  return (
+    a.command === b.command &&
+    JSON.stringify(a.args ?? []) === JSON.stringify(b.args ?? [])
+  );
+}
+
+function readClaudeSettings(): Record<string, unknown> {
+  if (!existsSync(CLAUDE_SETTINGS)) return {};
+  const text = readFileSync(CLAUDE_SETTINGS, "utf-8").trim();
+  if (!text) return {};
+  try {
+    return JSON.parse(text) as Record<string, unknown>;
+  } catch (e) {
+    throw new Error(
+      `failed to parse ${CLAUDE_SETTINGS}: ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+}
+
+function writeClaudeSettings(obj: Record<string, unknown>): void {
+  mkdirSync(dirname(CLAUDE_SETTINGS), { recursive: true });
+  writeFileSync(
+    CLAUDE_SETTINGS,
+    JSON.stringify(obj, null, 2) + "\n",
+    "utf-8",
+  );
+}
+
+/**
+ * All claudemesh MCP tool names, prefixed for allowedTools.
+ * These let Claude Code use claudemesh tools without --dangerously-skip-permissions.
+ */
+const CLAUDEMESH_TOOLS = [
+  "mcp__claudemesh__cancel_scheduled",
+  "mcp__claudemesh__check_messages",
+  "mcp__claudemesh__claim_task",
+  "mcp__claudemesh__complete_task",
+  "mcp__claudemesh__create_stream",
+  "mcp__claudemesh__create_task",
+  "mcp__claudemesh__delete_file",
+  "mcp__claudemesh__file_status",
+  "mcp__claudemesh__forget",
+  "mcp__claudemesh__get_context",
+  "mcp__claudemesh__get_file",
+  "mcp__claudemesh__get_state",
+  "mcp__claudemesh__grant_file_access",
+  "mcp__claudemesh__graph_execute",
+  "mcp__claudemesh__graph_query",
+  "mcp__claudemesh__join_group",
+  "mcp__claudemesh__leave_group",
+  "mcp__claudemesh__list_collections",
+  "mcp__claudemesh__list_contexts",
+  "mcp__claudemesh__list_files",
+  "mcp__claudemesh__list_peers",
+  "mcp__claudemesh__list_scheduled",
+  "mcp__claudemesh__list_state",
+  "mcp__claudemesh__list_streams",
+  "mcp__claudemesh__list_tasks",
+  "mcp__claudemesh__mesh_execute",
+  "mcp__claudemesh__mesh_info",
+  "mcp__claudemesh__mesh_query",
+  "mcp__claudemesh__mesh_schema",
+  "mcp__claudemesh__message_status",
+  "mcp__claudemesh__ping_mesh",
+  "mcp__claudemesh__publish",
+  "mcp__claudemesh__recall",
+  "mcp__claudemesh__remember",
+  "mcp__claudemesh__schedule_reminder",
+  "mcp__claudemesh__send_message",
+  "mcp__claudemesh__set_state",
+  "mcp__claudemesh__set_status",
+  "mcp__claudemesh__set_summary",
+  "mcp__claudemesh__share_context",
+  "mcp__claudemesh__share_file",
+  "mcp__claudemesh__subscribe",
+  "mcp__claudemesh__vector_delete",
+  "mcp__claudemesh__vector_search",
+  "mcp__claudemesh__vector_store",
+];
+
+/**
+ * Pre-approve all claudemesh MCP tools in allowedTools.
+ * Merges into any existing list — never overwrites other entries.
+ * Returns which tools were added vs already present.
+ */
+function installAllowedTools(): { added: string[]; unchanged: number } {
+  const settings = readClaudeSettings();
+  const existing = new Set<string>((settings.allowedTools as string[] | undefined) ?? []);
+  const toAdd = CLAUDEMESH_TOOLS.filter((t) => !existing.has(t));
+  if (toAdd.length > 0) {
+    settings.allowedTools = [...Array.from(existing), ...toAdd];
+    writeClaudeSettings(settings);
+  }
+  return { added: toAdd, unchanged: CLAUDEMESH_TOOLS.length - toAdd.length };
+}
+
+/**
+ * Remove claudemesh tools from allowedTools.
+ * Leaves all other entries intact. Returns count removed.
+ */
+function uninstallAllowedTools(): number {
+  if (!existsSync(CLAUDE_SETTINGS)) return 0;
+  const settings = readClaudeSettings();
+  const existing = (settings.allowedTools as string[] | undefined) ?? [];
+  const toolSet = new Set(CLAUDEMESH_TOOLS);
+  const kept = existing.filter((t) => !toolSet.has(t));
+  const removed = existing.length - kept.length;
+  if (removed > 0) {
+    settings.allowedTools = kept;
+    writeClaudeSettings(settings);
+  }
+  return removed;
+}
+
+/**
+ * Add a Stop + UserPromptSubmit hook entry to ~/.claude/settings.json,
+ * idempotent on the command string. Returns counts for reporting.
+ */
+function installHooks(): { added: number; unchanged: number } {
+  const settings = readClaudeSettings();
+  const hooks = ((settings.hooks ??= {}) as HooksConfig) ?? {};
+  let added = 0;
+  let unchanged = 0;
+
+  const ensure = (event: string, command: string): void => {
+    const list = (hooks[event] ??= []);
+    const alreadyPresent = list.some((entry) =>
+      (entry.hooks ?? []).some((h) => h.command === command),
+    );
+    if (alreadyPresent) {
+      unchanged += 1;
+      return;
+    }
+    list.push({ hooks: [{ type: "command", command }] });
+    added += 1;
+  };
+  ensure("Stop", HOOK_COMMAND_STOP);
+  ensure("UserPromptSubmit", HOOK_COMMAND_USER_PROMPT);
+
+  settings.hooks = hooks;
+  writeClaudeSettings(settings);
+  return { added, unchanged };
+}
+
+/**
+ * Remove every hook entry whose command contains "claudemesh hook "
+ * from ~/.claude/settings.json. Idempotent. Returns removed count.
+ */
+function uninstallHooks(): number {
+  if (!existsSync(CLAUDE_SETTINGS)) return 0;
+  const settings = readClaudeSettings();
+  const hooks = settings.hooks as HooksConfig | undefined;
+  if (!hooks) return 0;
+  let removed = 0;
+  for (const event of Object.keys(hooks)) {
+    const kept: HookMatcher[] = [];
+    for (const entry of hooks[event] ?? []) {
+      const filtered = (entry.hooks ?? []).filter(
+        (h) => !(h.command ?? "").includes(HOOK_MARKER),
+      );
+      removed += (entry.hooks ?? []).length - filtered.length;
+      if (filtered.length > 0) kept.push({ ...entry, hooks: filtered });
+    }
+    if (kept.length === 0) delete hooks[event];
+    else hooks[event] = kept;
+  }
+  settings.hooks = hooks;
+  writeClaudeSettings(settings);
+  return removed;
+}
+
+function installStatusLine(): { installed: boolean } {
+  const settings = readClaudeSettings();
+  const cmd = `claudemesh status-line`;
+  const current = (settings as { statusLine?: { command?: string } }).statusLine;
+  // If the user has their own statusLine command, don't clobber it.
+  if (current?.command && !current.command.includes("claudemesh status-line")) {
+    return { installed: false };
+  }
+  (settings as { statusLine?: { type: string; command: string } }).statusLine = {
+    type: "command",
+    command: cmd,
+  };
+  writeClaudeSettings(settings);
+  return { installed: true };
+}
+
+export function runInstall(args: string[] = []): void {
+  const skipHooks = args.includes("--no-hooks");
+  const wantStatusLine = args.includes("--status-line");
+  console.log("claudemesh install");
+  console.log("------------------");
+
+  const entry = resolveEntry();
+  const isBundled = entry.endsWith("/dist/index.js") ||
+    entry.endsWith("\\dist\\index.js");
+
+  // Dev mode (running from src/) requires bun on PATH; bundled mode
+  // (npm install -g) just uses node + the claudemesh bin shim.
+  if (!isBundled && !bunAvailable()) {
+    console.error(
+      "✗ `bun` is not on PATH. Install Bun first: https://bun.com",
+    );
+    process.exit(1);
+  }
+  if (!existsSync(entry)) {
+    console.error(`✗ MCP entry not found at ${entry}`);
+    process.exit(1);
+  }
+
+  const desired = buildMcpEntry(entry);
+  const action = patchMcpServer(desired);
+
+  // Read-back verification.
+  const verify = readClaudeConfig();
+  const verifyServers = (verify.mcpServers ?? {}) as Record<string, McpEntry>;
+  const stored = verifyServers[MCP_NAME];
+  if (!stored || !entriesEqual(stored, desired)) {
+    console.error(
+      `✗ post-write verification failed — ${CLAUDE_CONFIG} may be corrupt`,
+    );
+    process.exit(1);
+  }
+
+  // ANSI color helpers — stick to 8-color set so terminals without
+  // truecolor still render. Fall back to plain if NO_COLOR or dumb TERM.
+  const useColor =
+    !process.env.NO_COLOR && process.env.TERM !== "dumb" && process.stdout.isTTY;
+  const bold = (s: string) => (useColor ? `\x1b[1m${s}\x1b[22m` : s);
+  const yellow = (s: string) => (useColor ? `\x1b[33m${s}\x1b[39m` : s);
+  const dim = (s: string) => (useColor ? `\x1b[2m${s}\x1b[22m` : s);
+
+  console.log(`✓ MCP server "${MCP_NAME}" ${action}`);
+  console.log(dim(`  config:  ${CLAUDE_CONFIG}`));
+  console.log(
+    dim(
+      `  command: ${desired.command}${desired.args?.length ? " " + desired.args.join(" ") : ""}`,
+    ),
+  );
+
+  // allowedTools — pre-approve claudemesh MCP tools so peers don't need
+  // --dangerously-skip-permissions just to call mesh tools.
+  try {
+    const { added, unchanged } = installAllowedTools();
+    if (added.length > 0) {
+      console.log(
+        `✓ allowedTools: ${added.length} claudemesh tools pre-approved${unchanged > 0 ? `, ${unchanged} already present` : ""}`,
+      );
+      console.log(dim(`  This lets claudemesh tools run without --dangerously-skip-permissions.`));
+      console.log(dim(`  Your existing allowedTools entries were preserved.`));
+    } else {
+      console.log(`✓ allowedTools: all ${unchanged} claudemesh tools already pre-approved`);
+    }
+    console.log(dim(`  config:  ${CLAUDE_SETTINGS}`));
+  } catch (e) {
+    console.error(
+      `⚠  allowedTools update failed: ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+
+  // Hooks — status accuracy (Stop/UserPromptSubmit → POST /hook/set-status).
+  if (!skipHooks) {
+    try {
+      const { added, unchanged } = installHooks();
+      if (added > 0) {
+        console.log(
+          `✓ Hooks registered (Stop + UserPromptSubmit) → ${added} added, ${unchanged} already present`,
+        );
+      } else {
+        console.log(`✓ Hooks already registered (${unchanged} present)`);
+      }
+      console.log(dim(`  config:  ${CLAUDE_SETTINGS}`));
+    } catch (e) {
+      console.error(
+        `⚠  hook registration failed: ${e instanceof Error ? e.message : String(e)}`,
+      );
+      console.error(
+        "   (MCP is still installed — hooks just skip. Retry with --no-hooks to suppress.)",
+      );
+    }
+  } else {
+    console.log(dim("· Hooks skipped (--no-hooks)"));
+  }
+
+  // Opt-in status line (shows mesh + peer count in Claude Code).
+  if (wantStatusLine) {
+    try {
+      const { installed } = installStatusLine();
+      if (installed) {
+        console.log(`✓ Claude Code statusLine → \`claudemesh status-line\``);
+        console.log(dim(`  Shows: ◇ <mesh> · <online>/<total> online · <you>`));
+      } else {
+        console.log(dim("· statusLine already set to a custom command — left alone"));
+      }
+    } catch (e) {
+      console.error(`⚠  statusLine install failed: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+
+  // Check if user has any meshes joined — nudge them if not.
+  let hasMeshes = false;
+  try {
+    const meshConfig = readConfig();
+    hasMeshes = meshConfig.meshes.length > 0;
+  } catch {
+    // Config missing or corrupt — treat as no meshes.
+  }
+
+  console.log("");
+  console.log(yellow(bold("⚠  RESTART CLAUDE CODE")) + yellow(" for MCP tools to appear."));
+
+  if (!hasMeshes) {
+    console.log("");
+    console.log(yellow("No meshes joined.") + " To connect with peers:");
+    console.log(
+      `  ${bold("claudemesh <invite-url>")}` +
+        dim("   — joins + launches in one step"),
+    );
+    console.log(
+      `  ${dim("Create one at")} ${bold("https://claudemesh.com/dashboard")}`,
+    );
+  } else {
+    console.log("");
+    console.log(
+      `Next: ${bold("claudemesh")}` + dim("   — launch with your joined mesh"),
+    );
+  }
+
+  console.log("");
+  console.log(dim("Optional:"));
+  console.log(dim(`  claudemesh url-handler install   # click-to-launch from email`));
+  console.log(dim(`  claudemesh install --status-line # live peer count in Claude Code`));
+  console.log(dim(`  claudemesh completions zsh       # shell completions`));
+}
+
+export function runUninstall(): void {
+  console.log("claudemesh uninstall");
+  console.log("--------------------");
+
+  // MCP entry — only removes claudemesh, never touches other servers.
+  if (removeMcpServer()) {
+    console.log(`✓ MCP server "${MCP_NAME}" removed`);
+  } else {
+    console.log(`· MCP server "${MCP_NAME}" not present`);
+  }
+
+  // allowedTools
+  try {
+    const removed = uninstallAllowedTools();
+    if (removed > 0) {
+      console.log(`✓ allowedTools: ${removed} claudemesh tools removed`);
+    } else {
+      console.log("· No claudemesh allowedTools to remove");
+    }
+  } catch (e) {
+    console.error(
+      `⚠  allowedTools removal failed: ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+
+  // Hooks
+  try {
+    const removed = uninstallHooks();
+    if (removed > 0) {
+      console.log(`✓ Hooks removed (${removed} entries)`);
+    } else {
+      console.log("· No claudemesh hooks to remove");
+    }
+  } catch (e) {
+    console.error(
+      `⚠  hook removal failed: ${e instanceof Error ? e.message : String(e)}`,
+    );
+  }
+
+  console.log("");
+  console.log("Restart Claude Code to drop the MCP connection + hooks.");
+}
--- a/apps/cli-v2/src/commands/invite.ts
+++ b/apps/cli-v2/src/commands/invite.ts
@@ -0,0 +1,96 @@
+import { createInterface } from "node:readline";
+import { getStoredToken } from "~/services/auth/facade.js";
+import { generateInvite } from "~/services/invite/generate.js";
+import { readConfig } from "~/services/config/facade.js";
+import { writeClipboard } from "~/services/clipboard/facade.js";
+import { green, bold, dim, icons } from "~/ui/styles.js";
+import { renderQrAsync } from "~/ui/qr.js";
+import { EXIT } from "~/constants/exit-codes.js";
+
+function prompt(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (a) => { rl.close(); resolve(a.trim()); });
+  });
+}
+
+export async function invite(
+  email?: string,
+  opts: { mesh?: string; expires?: string; uses?: number; role?: string; json?: boolean } = {},
+): Promise<number> {
+  const auth = getStoredToken();
+  if (!auth) {
+    console.error("  Not signed in. Run `claudemesh login` first.");
+    return EXIT.AUTH_FAILED;
+  }
+
+  const config = readConfig();
+  if (config.meshes.length === 0) {
+    console.error("  No meshes. Create one with `claudemesh mesh create <name>`.");
+    return EXIT.NOT_FOUND;
+  }
+
+  // Resolve which mesh to share
+  let meshSlug = opts.mesh;
+  if (!meshSlug) {
+    if (config.meshes.length === 1) {
+      meshSlug = config.meshes[0]!.slug;
+    } else {
+      // Show picker
+      console.log("\n  Select mesh to share:\n");
+      config.meshes.forEach((m, i) => {
+        console.log(`    ${bold(String(i + 1) + ")")} ${m.slug} ${dim("(" + m.name + ")")}`);
+      });
+      console.log("");
+      const choice = await prompt("  Choice [1]: ") || "1";
+      const idx = parseInt(choice, 10) - 1;
+      meshSlug = config.meshes[idx >= 0 && idx < config.meshes.length ? idx : 0]!.slug;
+    }
+  }
+
+  try {
+    const result = await generateInvite(meshSlug, {
+      email,
+      expires_in: opts.expires ?? "7d",
+      max_uses: opts.uses,
+      role: opts.role,
+    });
+
+    const copied = writeClipboard(result.url);
+
+    if (opts.json) {
+      console.log(JSON.stringify({ schema_version: "1.0", ...result, copied }, null, 2));
+    } else {
+      if (email) {
+        if (result.emailed) {
+          console.log(`\n  ${green(icons.check)} Invite sent to ${bold(email)}`);
+          if (copied) console.log(`  ${green(icons.check)} Link also copied to clipboard`);
+        } else {
+          console.log(`\n  ${icons.cross} Email to ${bold(email)} was NOT sent (server did not send).`);
+          console.log(`  ${dim("Share the link manually:")}`);
+          console.log(`    ${result.url}`);
+          if (copied) console.log(`  ${green(icons.check)} Link copied to clipboard`);
+        }
+      } else {
+        console.log(`\n  ${green(icons.check)} Invite link${copied ? " copied to clipboard" : ""}:`);
+        console.log(`    ${result.url}`);
+        // Print QR for phone→laptop pairing. Small variant is ~17 lines tall.
+        const qr = await renderQrAsync(result.url, { small: true });
+        console.log("");
+        for (const line of qr.split("\n")) console.log(`  ${line}`);
+      }
+      console.log(`\n  ${dim("Expires " + result.expires_at + ". Anyone with this link can join \"" + meshSlug + "\".")}\n`);
+    }
+
+    return EXIT.SUCCESS;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("403") || msg.includes("permission")) {
+      console.error(`  ${icons.cross} You don't have permission to invite to "${meshSlug}".`);
+      console.error(`  ${dim("Ask the mesh owner to grant you invite permissions.")}`);
+    } else {
+      console.error(`  ${icons.cross} Failed: ${msg}`);
+    }
+    return EXIT.INTERNAL_ERROR;
+  }
+}
--- a/apps/cli-v2/src/commands/join.ts
+++ b/apps/cli-v2/src/commands/join.ts
@@ -0,0 +1,193 @@
+/**
+ * `claudemesh join <invite-link-or-code>` — full join flow.
+ *
+ * Accepts either:
+ *   - v2 short invite: `claudemesh.com/i/<code>` or bare `<code>`
+ *     → POSTs to /api/public/invites/:code/claim, unseals root_key,
+ *       persists mesh + fresh ed25519 identity.
+ *   - v1 legacy invite: `ic://join/<token>` or `https://.../join/<token>`
+ *     → parses signed payload, calls broker /join, persists.
+ *
+ * v1 continues to work throughout v0.1.x. v1 endpoints 410 Gone at v0.2.0.
+ */
+
+import { parseInviteLink } from "~/services/invite/facade.js";
+import { enrollWithBroker } from "~/services/invite/facade.js";
+import { generateKeypair } from "~/services/crypto/facade.js";
+import { readConfig, writeConfig, getConfigPath } from "~/services/config/facade.js";
+import { claimInviteV2, parseV2InviteInput } from "~/services/invite/facade.js";
+import sodium from "libsodium-wrappers";
+import { writeFileSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { homedir, hostname } from "node:os";
+import { env } from "~/constants/urls.js";
+
+/** Derive the web app base URL from the broker URL, unless explicitly overridden. */
+function deriveAppBaseUrl(): string {
+  const override = process.env.CLAUDEMESH_APP_URL;
+  if (override) return override.replace(/\/$/, "");
+  // Broker is `wss://ic.claudemesh.com/ws` → app is `https://claudemesh.com`.
+  // For self-hosted: honour the broker host's parent domain as best-effort.
+  try {
+    const u = new URL(env.CLAUDEMESH_BROKER_URL);
+    const host = u.host.replace(/^ic\./, "");
+    const scheme = u.protocol === "wss:" ? "https:" : "http:";
+    return `${scheme}//${host}`;
+  } catch {
+    return "https://claudemesh.com";
+  }
+}
+
+async function runJoinV2(code: string): Promise<void> {
+  const appBaseUrl = deriveAppBaseUrl();
+  console.log(`Claiming invite ${code} via ${appBaseUrl}…`);
+
+  let claim;
+  try {
+    claim = await claimInviteV2({ appBaseUrl, code });
+  } catch (e) {
+    console.error(
+      `claudemesh: ${e instanceof Error ? e.message : String(e)}`,
+    );
+    process.exit(1);
+  }
+
+  // Generate a fresh ed25519 identity for this peer. The v2 claim
+  // endpoint creates the member row keyed on the x25519 pubkey we sent;
+  // the ed25519 keypair is what the `hello` handshake and future
+  // envelope signing will use. Stored locally only.
+  const keypair = await generateKeypair();
+  const displayName = `${hostname()}-${process.pid}`;
+
+  // Encode the unsealed 32-byte root key as URL-safe base64url (no pad)
+  // to match the format used everywhere else (broker stores it the
+  // same way in mesh.rootKey).
+  await sodium.ready;
+  const rootKeyB64 = sodium.to_base64(
+    claim.rootKey,
+    sodium.base64_variants.URLSAFE_NO_PADDING,
+  );
+
+  // Persist. We don't have a mesh_slug in the v2 response — the server
+  // derives slug from name and slug is no longer globally unique. Use a
+  // stable short derivative of the mesh id so `list` / `launch --mesh`
+  // still have something to match on.
+  const fallbackSlug = `mesh-${claim.meshId.slice(0, 8)}`;
+  const config = readConfig();
+  config.meshes = config.meshes.filter((m) => m.meshId !== claim.meshId);
+  config.meshes.push({
+    meshId: claim.meshId,
+    memberId: claim.memberId,
+    slug: fallbackSlug,
+    name: fallbackSlug,
+    pubkey: keypair.publicKey,
+    secretKey: keypair.secretKey,
+    brokerUrl: env.CLAUDEMESH_BROKER_URL,
+    joinedAt: new Date().toISOString(),
+    rootKey: rootKeyB64,
+    inviteVersion: 2,
+  });
+  writeConfig(config);
+
+  console.log("");
+  console.log(`✓ Joined mesh ${claim.meshId} via v2 invite`);
+  console.log(`  member id:  ${claim.memberId}`);
+  console.log(`  pubkey:     ${keypair.publicKey.slice(0, 16)}…`);
+  console.log(`  broker:     ${env.CLAUDEMESH_BROKER_URL}`);
+  console.log(`  config:     ${getConfigPath()}`);
+  console.log("");
+  console.log("Restart Claude Code to pick up the new mesh.");
+}
+
+export async function runJoin(args: string[]): Promise<void> {
+  const link = args[0];
+  if (!link) {
+    console.error("Usage: claudemesh join <invite-url-or-code>");
+    console.error("");
+    console.error("Examples:");
+    console.error("  claudemesh join https://claudemesh.com/i/abc12345");
+    console.error("  claudemesh join abc12345");
+    console.error("  claudemesh join ic://join/eyJ2IjoxLC4uLn0   (v1 legacy)");
+    process.exit(1);
+  }
+
+  // Try v2 first — short code / `/i/<code>` URL.
+  const v2Code = parseV2InviteInput(link);
+  if (v2Code) {
+    await runJoinV2(v2Code);
+    return;
+  }
+
+  // 1. Parse + verify signature client-side.
+  let invite;
+  try {
+    invite = await parseInviteLink(link);
+  } catch (e) {
+    console.error(
+      `claudemesh: ${e instanceof Error ? e.message : String(e)}`,
+    );
+    process.exit(1);
+  }
+  const { payload, token } = invite;
+  console.log(`Joining mesh "${payload.mesh_slug}" (${payload.mesh_id})…`);
+
+  // 2. Generate keypair.
+  const keypair = await generateKeypair();
+
+  // 3. Enroll with broker.
+  const displayName = `${hostname()}-${process.pid}`;
+  let enroll;
+  try {
+    enroll = await enrollWithBroker({
+      brokerWsUrl: payload.broker_url,
+      inviteToken: token,
+      invitePayload: payload,
+      peerPubkey: keypair.publicKey,
+      displayName,
+    });
+  } catch (e) {
+    console.error(
+      `claudemesh: broker enrollment failed: ${e instanceof Error ? e.message : String(e)}`,
+    );
+    process.exit(1);
+  }
+
+  // 4. Persist.
+  const config = readConfig();
+  config.meshes = config.meshes.filter(
+    (m) => m.slug !== payload.mesh_slug,
+  );
+  config.meshes.push({
+    meshId: payload.mesh_id,
+    memberId: enroll.memberId,
+    slug: payload.mesh_slug,
+    name: payload.mesh_slug,
+    pubkey: keypair.publicKey,
+    secretKey: keypair.secretKey,
+    brokerUrl: payload.broker_url,
+    joinedAt: new Date().toISOString(),
+  });
+  writeConfig(config);
+
+  // 4b. Store invite token for per-session re-enrollment (launch --name).
+  const configDir = env.CLAUDEMESH_CONFIG_DIR ?? join(homedir(), ".claudemesh");
+  const inviteFile = join(configDir, `invite-${payload.mesh_slug}.txt`);
+  try {
+    mkdirSync(dirname(inviteFile), { recursive: true });
+    writeFileSync(inviteFile, link, "utf-8");
+  } catch {
+    // Non-fatal — launch will fall back to shared identity.
+  }
+
+  // 5. Report.
+  console.log("");
+  console.log(
+    `✓ Joined "${payload.mesh_slug}" as ${displayName}${enroll.alreadyMember ? " (already a member — re-enrolled with same pubkey)" : ""}`,
+  );
+  console.log(`  member id: ${enroll.memberId}`);
+  console.log(`  pubkey:    ${keypair.publicKey.slice(0, 16)}…`);
+  console.log(`  broker:    ${payload.broker_url}`);
+  console.log(`  config:    ${getConfigPath()}`);
+  console.log("");
+  console.log("Restart Claude Code to pick up the new mesh.");
+}
--- a/apps/cli-v2/src/commands/launch.ts
+++ b/apps/cli-v2/src/commands/launch.ts
@@ -0,0 +1,823 @@
+// @ts-nocheck — v1 port, runtime-tested
+/**
+ * `claudemesh launch` — spawn `claude` with peer mesh identity.
+ *
+ * Flags are defined in index.ts (citty command) — that is the source of
+ * truth. This file receives already-parsed flags and rawArgs.
+ *
+ * Flow:
+ *   1. Receive parsed flags from citty + rawArgs for -- passthrough
+ *   2. If --join: run join flow first
+ *   3. Load config → pick mesh (auto if 1, interactive picker if >1)
+ *   4. Write per-session config to tmpdir (isolates mesh selection)
+ *   5. Spawn claude with CLAUDEMESH_CONFIG_DIR + CLAUDEMESH_DISPLAY_NAME
+ *   6. On exit: cleanup tmpdir
+ */
+
+import { spawnSync } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdtempSync, writeFileSync, rmSync, readdirSync, statSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir, hostname, homedir } from "node:os";
+import { join } from "node:path";
+import { createInterface } from "node:readline";
+import { readConfig, getConfigPath } from "~/services/config/facade.js";
+import type { Config, JoinedMesh, GroupEntry } from "~/services/config/facade.js";
+import { startCallbackListener, generatePairingCode } from "~/services/auth/facade.js";
+import { openBrowser } from "~/services/spawn/facade.js";
+import { BrokerClient } from "~/services/broker/facade.js";
+
+// Flags as parsed by citty (index.ts is the source of truth for definitions).
+export interface LaunchFlags {
+  name?: string;
+  role?: string;
+  groups?: string;
+  join?: string;
+  mesh?: string;
+  "message-mode"?: string;
+  "system-prompt"?: string;
+  resume?: string;
+  continue?: boolean;
+  yes?: boolean;
+  quiet?: boolean;
+}
+
+// --- Interactive mesh picker ---
+
+async function pickMesh(meshes: JoinedMesh[]): Promise<JoinedMesh> {
+  if (meshes.length === 1) return meshes[0]!;
+
+  console.log("\n  Select mesh:");
+  meshes.forEach((m, i) => {
+    console.log(`    ${i + 1}) ${m.slug}`);
+  });
+  console.log("");
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question("  Choice [1]: ", (answer) => {
+      rl.close();
+      const idx = parseInt(answer || "1", 10) - 1;
+      if (idx >= 0 && idx < meshes.length) {
+        resolve(meshes[idx]!);
+      } else {
+        console.error("  Invalid choice, using first mesh.");
+        resolve(meshes[0]!);
+      }
+    });
+  });
+}
+
+// --- Group string parser ---
+
+/** Parse "frontend:lead,reviewers:member,all" → GroupEntry[] */
+function parseGroupsString(raw: string): GroupEntry[] {
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((token) => {
+      const idx = token.indexOf(":");
+      if (idx === -1) return { name: token };
+      return { name: token.slice(0, idx), role: token.slice(idx + 1) };
+    });
+}
+
+// --- Interactive role/groups prompts ---
+
+function askLine(prompt: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(prompt, (answer) => {
+      rl.close();
+      resolve(answer.trim());
+    });
+  });
+}
+
+// --- Permission confirmation ---
+
+async function confirmPermissions(): Promise<void> {
+  const useColor =
+    !process.env.NO_COLOR && process.env.TERM !== "dumb" && process.stdout.isTTY;
+  const bold = (s: string): string => (useColor ? `\x1b[1m${s}\x1b[22m` : s);
+  const dim = (s: string): string => (useColor ? `\x1b[2m${s}\x1b[22m` : s);
+  const yellow = (s: string): string => (useColor ? `\x1b[33m${s}\x1b[39m` : s);
+
+  console.log(yellow(bold("  Autonomous mode")));
+  console.log("");
+  console.log("  Claude will run with --dangerously-skip-permissions, bypassing");
+  console.log("  ALL permission prompts — not just claudemesh tools.");
+  console.log("  Peers exchange text only — no file access, no tool calls.");
+  console.log("");
+  console.log(dim("  Without -y: only claudemesh tools are pre-approved (via allowedTools)."));
+  console.log(dim("  Use -y for autonomous agents. Omit it for shared/multi-person meshes."));
+  console.log("");
+
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve, reject) => {
+    rl.question(`  ${bold("Continue?")} [Y/n] `, (answer) => {
+      rl.close();
+      const a = answer.trim().toLowerCase();
+      if (a === "" || a === "y" || a === "yes") {
+        resolve();
+      } else {
+        console.log("\n  Aborted. Run without autonomous mode:");
+        console.log("    claude --dangerously-load-development-channels server:claudemesh\n");
+        process.exit(0);
+      }
+    });
+  });
+}
+
+// --- Banner ---
+
+import {
+  bold as tBold, dim as tDim, green as tGreen, orange as tOrange,
+  boldOrange, HIDE_CURSOR, SHOW_CURSOR,
+} from "~/ui/styles.js";
+import {
+  enterFullScreen, exitFullScreen, writeCentered, termSize,
+  drawTopBar, drawBottomBar, menuSelect, textInput, confirmPrompt,
+} from "~/ui/screen.js";
+import { createSpinner, FRAME_HEIGHT } from "~/ui/spinner.js";
+
+interface LaunchWizardResult {
+  mesh: JoinedMesh;
+  role: string | null;
+  groups: GroupEntry[];
+  messageMode: "push" | "inbox" | "off";
+  skipPermissions: boolean;
+}
+
+/**
+ * Full-screen launch wizard — spinning logo + interactive config.
+ * Mesh selection, role, groups, message mode, permissions — all in one TUI.
+ * Falls back to plain text on non-TTY.
+ */
+async function runLaunchWizard(opts: {
+  displayName: string;
+  meshes: JoinedMesh[];
+  selectedMesh: JoinedMesh | null;
+  existingRole: string | null;
+  existingGroups: GroupEntry[];
+  existingMessageMode: "push" | "inbox" | "off" | null;
+  skipPermConfirm: boolean;
+}): Promise<LaunchWizardResult> {
+  if (!process.stdout.isTTY) {
+    return {
+      mesh: opts.selectedMesh ?? opts.meshes[0]!,
+      role: opts.existingRole,
+      groups: opts.existingGroups,
+      messageMode: opts.existingMessageMode ?? "push",
+      skipPermissions: opts.skipPermConfirm,
+    };
+  }
+
+  const { rows } = termSize();
+  enterFullScreen();
+  drawTopBar();
+
+  // Spinning logo centered in upper portion
+  const logoTop = Math.floor((rows - FRAME_HEIGHT - 16) / 2);
+  const brandRow = logoTop + FRAME_HEIGHT + 1;
+  const subtitleRow = brandRow + 1;
+  const formRow = subtitleRow + 2;
+
+  writeCentered(brandRow, boldOrange("claudemesh"));
+  writeCentered(subtitleRow, tDim("peer mesh for Claude Code"));
+
+  const spinner = createSpinner({
+    render(lines) {
+      for (let i = 0; i < lines.length; i++) {
+        writeCentered(logoTop + i, lines[i]!);
+      }
+    },
+    interval: 70,
+  });
+  spinner.start();
+
+  // Show detected info
+  let row = formRow;
+  writeCentered(row, `Directory ${tGreen("✓")} ${process.cwd()}`);
+  row++;
+  writeCentered(row, `Name      ${tGreen("✓")} ${opts.displayName}`);
+  row += 2;
+
+  // Mesh selection
+  let mesh: JoinedMesh;
+  if (opts.selectedMesh) {
+    mesh = opts.selectedMesh;
+    writeCentered(row, `Mesh      ${tGreen("✓")} ${mesh.slug}`);
+    row++;
+  } else if (opts.meshes.length === 1) {
+    mesh = opts.meshes[0]!;
+    writeCentered(row, `Mesh      ${tGreen("✓")} ${mesh.slug}`);
+    row++;
+  } else {
+    spinner.stop();
+    const choice = await menuSelect({
+      title: "Select mesh",
+      items: opts.meshes.map(m => m.slug),
+      row,
+    });
+    mesh = opts.meshes[choice]!;
+    // Redraw as confirmed
+    for (let i = 0; i < opts.meshes.length + 1; i++) {
+      writeCentered(row + i, " ");
+    }
+    writeCentered(row, `Mesh      ${tGreen("✓")} ${mesh.slug}`);
+    spinner.start();
+    row++;
+  }
+
+  row++;
+
+  // Interactive fields
+  let role = opts.existingRole;
+  let groups = opts.existingGroups;
+  let messageMode = opts.existingMessageMode ?? "push" as "push" | "inbox" | "off";
+
+  // Role input
+  if (role === null) {
+    spinner.stop();
+    const answer = await textInput({ label: "Role", row, placeholder: "optional — press Enter to skip" });
+    if (answer) role = answer;
+    spinner.start();
+    row++;
+  } else {
+    writeCentered(row, `Role      ${tGreen("✓")} ${role}`);
+    row++;
+  }
+
+  // Groups input
+  if (groups.length === 0) {
+    spinner.stop();
+    const answer = await textInput({ label: "Groups", row, placeholder: "comma-separated, optional" });
+    if (answer) groups = parseGroupsString(answer);
+    spinner.start();
+    row++;
+  } else {
+    const tags = groups.map(g => `@${g.name}${g.role ? `:${g.role}` : ""}`).join(", ");
+    writeCentered(row, `Groups    ${tGreen("✓")} ${tags}`);
+    row++;
+  }
+
+  // Message mode selection
+  if (opts.existingMessageMode === null) {
+    row++;
+    spinner.stop();
+    const choice = await menuSelect({
+      title: "Message mode",
+      items: [
+        "Push (real-time, peers can interrupt)",
+        "Inbox (held until you check)",
+        "Off (tools only, no messages)",
+      ],
+      row,
+    });
+    messageMode = (["push", "inbox", "off"] as const)[choice];
+    spinner.start();
+    row += 5;
+  } else {
+    writeCentered(row, `Messages  ${tGreen("✓")} ${messageMode}`);
+    row++;
+  }
+
+  // Permissions confirmation
+  let skipPermissions = opts.skipPermConfirm;
+  if (!skipPermissions) {
+    row++;
+    spinner.stop();
+    writeCentered(row, tDim("Claude will run with --dangerously-skip-permissions,"));
+    writeCentered(row + 1, tDim("bypassing ALL permission prompts — not just claudemesh."));
+    row += 3;
+    const confirmed = await confirmPrompt({
+      message: boldOrange("Autonomous mode?"),
+      row,
+      defaultYes: true,
+    });
+    if (!confirmed) {
+      exitFullScreen();
+      console.log("  Run without autonomous mode:");
+      console.log("    claude --dangerously-load-development-channels server:claudemesh\n");
+      process.exit(0);
+    }
+    skipPermissions = true;
+    spinner.start();
+  }
+
+  // Final animation
+  row += 2;
+  writeCentered(row, tDim("Launching Claude Code..."));
+
+  await new Promise(r => setTimeout(r, 800));
+  spinner.stop();
+  exitFullScreen();
+
+  return { mesh, role, groups, messageMode, skipPermissions };
+}
+
+function printBanner(name: string, meshSlug: string, role: string | null, groups: GroupEntry[], messageMode: "push" | "inbox" | "off"): void {
+  const useColor =
+    !process.env.NO_COLOR && process.env.TERM !== "dumb" && process.stdout.isTTY;
+  const dim = (s: string): string => (useColor ? `\x1b[2m${s}\x1b[22m` : s);
+  const bold = (s: string): string => (useColor ? `\x1b[1m${s}\x1b[22m` : s);
+
+  const roleSuffix = role ? ` (${role})` : "";
+  const groupTags = groups.length
+    ? " [" + groups.map((g) => `@${g.name}${g.role ? `:${g.role}` : ""}`).join(", ") + "]"
+    : "";
+
+  const rule = "─".repeat(60);
+  console.log(bold(`claudemesh launch`) + dim(` — as ${name}${roleSuffix} on ${meshSlug}${groupTags} [${messageMode}]`));
+  console.log(rule);
+  if (messageMode === "push") {
+    console.log("Peer messages arrive as <channel> reminders in real-time.");
+  } else if (messageMode === "inbox") {
+    console.log("Peer messages held in inbox. Use check_messages to read.");
+  } else {
+    console.log("Messages off. Use check_messages to poll manually.");
+  }
+  console.log("Peers send text only — they cannot call tools or read files.");
+  console.log(dim(`Config: ${getConfigPath()}`));
+  console.log(rule);
+  console.log("");
+}
+
+// --- Main ---
+
+export async function runLaunch(flags: LaunchFlags, rawArgs: string[]): Promise<void> {
+  // Extract args that follow "--" — passed straight through to claude.
+  const dashIdx = rawArgs.indexOf("--");
+  const claudePassthrough = dashIdx >= 0 ? rawArgs.slice(dashIdx + 1) : [];
+
+  // Normalise flags into the internal shape used below.
+  const args = {
+    name: flags.name ?? null,
+    role: flags.role ?? null,
+    groups: flags.groups ?? null,
+    joinLink: flags.join ?? null,
+    meshSlug: flags.mesh ?? null,
+    messageMode: (["push", "inbox", "off"].includes(flags["message-mode"] ?? "")
+      ? flags["message-mode"] as "push" | "inbox" | "off"
+      : null),
+    systemPrompt: flags["system-prompt"] ?? null,
+    resume: flags.resume ?? null,
+    continueSession: flags.continue ?? false,
+    quiet: flags.quiet ?? false,
+    skipPermConfirm: flags.yes ?? false,
+    claudeArgs: claudePassthrough,
+  };
+
+  // 1. If --join, run join flow first.
+  if (args.joinLink) {
+    console.log("Joining mesh...");
+    const invite = await parseInviteLink(args.joinLink);
+    const keypair = await generateKeypair();
+    const displayName = (args.name ?? process.env.USER ?? process.env.USERNAME ?? hostname());
+    const enroll = await enrollWithBroker({
+      brokerWsUrl: invite.payload.broker_url,
+      inviteToken: invite.token,
+      invitePayload: invite.payload,
+      peerPubkey: keypair.publicKey,
+      displayName,
+    });
+    const config = readConfig();
+    config.meshes = config.meshes.filter(
+      (m) => m.slug !== invite.payload.mesh_slug,
+    );
+    config.meshes.push({
+      meshId: invite.payload.mesh_id,
+      memberId: enroll.memberId,
+      slug: invite.payload.mesh_slug,
+      name: invite.payload.mesh_slug,
+      pubkey: keypair.publicKey,
+      secretKey: keypair.secretKey,
+      brokerUrl: invite.payload.broker_url,
+      joinedAt: new Date().toISOString(),
+    });
+    const { writeConfig } = await import("~/services/config/facade.js");
+    writeConfig(config);
+    console.log(
+      `✓ Joined "${invite.payload.mesh_slug}"${enroll.alreadyMember ? " (already member)" : ""}`,
+    );
+  }
+
+  // 2. Load config, pick mesh.
+  const config = readConfig();
+  let justSynced = false;
+
+  if (config.meshes.length === 0 && !args.joinLink) {
+    const useColor = !process.env.NO_COLOR && process.env.TERM !== "dumb" && process.stdout.isTTY;
+    const bold = (s: string): string => (useColor ? `\x1b[1m${s}\x1b[22m` : s);
+    const dim = (s: string): string => (useColor ? `\x1b[2m${s}\x1b[22m` : s);
+    const green = (s: string): string => (useColor ? `\x1b[32m${s}\x1b[39m` : s);
+
+    const code = generatePairingCode();
+    const listener = await startCallbackListener();
+    const url = `https://claudemesh.com/cli-auth?port=${listener.port}&code=${code}&action=sync`;
+
+    console.log(`\n  ${bold("Welcome to claudemesh!")} No meshes found.`);
+    console.log(`  Opening browser to sign in...\n`);
+
+    const opened = await openBrowser(url);
+    if (!opened) {
+      console.log(`  Couldn't open browser automatically.`);
+    }
+    console.log(`  ${dim(`Visit: ${url}`)}`);
+    console.log(`  ${dim(`Or join with invite: claudemesh launch --join <url>`)}\n`);
+
+    // Race: localhost callback vs manual paste vs timeout
+    const manualPromise = new Promise<string>((resolve) => {
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      rl.question("  Paste sync token (or wait for browser): ", (answer) => {
+        rl.close();
+        if (answer.trim()) resolve(answer.trim());
+      });
+    });
+
+    const timeoutPromise = new Promise<null>((resolve) => {
+      setTimeout(() => resolve(null), 15 * 60_000);
+    });
+
+    const syncToken = await Promise.race([
+      listener.token,
+      manualPromise,
+      timeoutPromise,
+    ]);
+
+    listener.close();
+
+    if (!syncToken) {
+      console.error("\n  Timed out waiting for sign-in.");
+      process.exit(1);
+    }
+
+    // Generate keypair and sync with broker
+    const { generateKeypair } = await import("~/services/crypto/facade.js");
+    const keypair = await generateKeypair();
+    const displayNameForSync = (args.name ?? process.env.USER ?? process.env.USERNAME ?? hostname());
+
+    const { syncWithBroker } = await import("~/services/auth/facade.js");
+    const result = await syncWithBroker(syncToken, keypair.publicKey, displayNameForSync);
+
+    // Write all meshes to config
+    const { writeConfig } = await import("~/services/config/facade.js");
+    for (const m of result.meshes) {
+      config.meshes.push({
+        meshId: m.mesh_id,
+        memberId: m.member_id,
+        slug: m.slug,
+        name: m.slug,
+        pubkey: keypair.publicKey,
+        secretKey: keypair.secretKey,
+        brokerUrl: m.broker_url,
+        joinedAt: new Date().toISOString(),
+      });
+    }
+    config.accountId = result.account_id;
+    writeConfig(config);
+    justSynced = true;
+
+    console.log(`\n  ${green("✓")} Synced ${result.meshes.length} mesh(es): ${result.meshes.map(m => m.slug).join(", ")}\n`);
+  }
+
+  if (config.meshes.length === 0) {
+    console.error("No meshes joined. Run `claudemesh join <url>` or use --join <url>.");
+    process.exit(1);
+  }
+
+  // Resolve mesh — by flag, auto (if 1), or defer to wizard (if >1)
+  let mesh: JoinedMesh;
+  if (args.meshSlug) {
+    const found = config.meshes.find((m) => m.slug === args.meshSlug);
+    if (!found) {
+      console.error(
+        `Mesh "${args.meshSlug}" not found. Joined: ${config.meshes.map((m) => m.slug).join(", ")}`,
+      );
+      process.exit(1);
+    }
+    mesh = found;
+  } else if (config.meshes.length === 1) {
+    mesh = config.meshes[0]!;
+  } else {
+    // Multiple meshes — wizard will handle selection
+    mesh = null as unknown as JoinedMesh; // set by wizard below
+  }
+
+  // 3. Session identity + role/groups via TUI wizard.
+  const displayName = (args.name ?? process.env.USER ?? process.env.USERNAME ?? hostname());
+
+  let role: string | null = args.role;
+  let parsedGroups: GroupEntry[] = args.groups ? parseGroupsString(args.groups) : [];
+  let messageMode: "push" | "inbox" | "off" = args.messageMode ?? "push";
+
+  // `-y` (skipPermConfirm) implies fully non-interactive — skip the wizard
+  // entirely and use sensible defaults (role=member, no groups, push mode).
+  // Same applies to `--quiet` and the post-sync path where we already picked.
+  const nonInteractive = args.quiet || justSynced || args.skipPermConfirm;
+  if (!nonInteractive) {
+    const wizardResult = await runLaunchWizard({
+      displayName,
+      meshes: config.meshes,
+      selectedMesh: mesh ?? null,
+      existingRole: args.role,
+      existingGroups: parsedGroups,
+      existingMessageMode: args.messageMode ?? null,
+      skipPermConfirm: args.skipPermConfirm,
+    });
+    mesh = wizardResult.mesh;
+    role = wizardResult.role;
+    parsedGroups = wizardResult.groups;
+    messageMode = wizardResult.messageMode;
+    args.skipPermConfirm = wizardResult.skipPermissions;
+  } else if (!mesh) {
+    // No mesh picked yet + non-interactive — pick the first one deterministically.
+    mesh = config.meshes[0]!;
+  }
+
+  // Clean up orphaned tmpdirs from crashed sessions (older than 1 hour)
+  const tmpBase = tmpdir();
+  try {
+    for (const entry of readdirSync(tmpBase)) {
+      if (!entry.startsWith("claudemesh-")) continue;
+      const full = join(tmpBase, entry);
+      const age = Date.now() - statSync(full).mtimeMs;
+      if (age > 3600_000) rmSync(full, { recursive: true, force: true });
+    }
+  } catch { /* best effort */ }
+
+  // Clean up stale mesh MCP entries from crashed sessions
+  try {
+    const claudeConfigPath = join(homedir(), ".claude.json");
+    if (existsSync(claudeConfigPath)) {
+      const claudeConfig = JSON.parse(readFileSync(claudeConfigPath, "utf-8"));
+      const mcpServers = claudeConfig.mcpServers ?? {};
+      let cleaned = 0;
+      for (const key of Object.keys(mcpServers)) {
+        if (!key.startsWith("mesh:")) continue;
+        const meta = mcpServers[key]?._meshSession;
+        if (!meta?.pid) continue;
+        // Check if the PID is still alive
+        try {
+          process.kill(meta.pid, 0); // signal 0 = check existence
+        } catch {
+          // PID is dead — remove stale entry
+          delete mcpServers[key];
+          cleaned++;
+        }
+      }
+      if (cleaned > 0) {
+        claudeConfig.mcpServers = mcpServers;
+        writeFileSync(claudeConfigPath, JSON.stringify(claudeConfig, null, 2) + "\n", "utf-8");
+      }
+    }
+  } catch { /* best effort */ }
+
+  // --- Fetch deployed services for native MCP entries ---
+  let serviceCatalog: Array<{
+    name: string;
+    description: string;
+    status: string;
+    tools: Array<{ name: string; description: string; inputSchema: object }>;
+    deployed_by: string;
+  }> = [];
+
+  try {
+    const tmpClient = new BrokerClient(mesh, { displayName });
+    await tmpClient.connect();
+    // Wait briefly for hello_ack with service catalog
+    await new Promise(r => setTimeout(r, 2000));
+    serviceCatalog = tmpClient.serviceCatalog;
+    tmpClient.close();
+  } catch {
+    // Non-fatal — launch without native service entries
+    if (!args.quiet) {
+      console.log("  (Could not fetch service catalog — mesh services won't be natively available)");
+    }
+  }
+
+  // 4. Write session config to tmpdir (isolates mesh selection).
+  const tmpDir = mkdtempSync(join(tmpdir(), "claudemesh-"));
+  const sessionConfig: Config = {
+    version: 1,
+    meshes: [mesh],
+    displayName,
+    ...(role ? { role } : {}),
+    ...(parsedGroups.length > 0 ? { groups: parsedGroups } : {}),
+    messageMode,
+  };
+  writeFileSync(
+    join(tmpDir, "config.json"),
+    JSON.stringify(sessionConfig, null, 2) + "\n",
+    "utf-8",
+  );
+
+  // 5. Print summary banner (wizard already handled all interactive config).
+  if (!args.quiet) {
+    printBanner(displayName, mesh.slug, role, parsedGroups, messageMode);
+  }
+
+  // --- Install native MCP entries for deployed mesh services ---
+  const meshMcpEntries: Array<{ key: string; entry: unknown }> = [];
+
+  if (serviceCatalog.length > 0) {
+    const claudeConfigPath = join(homedir(), ".claude.json");
+
+    // Read-modify-write: only touch mesh:* entries in mcpServers
+    let claudeConfig: Record<string, unknown> = {};
+    try {
+      claudeConfig = JSON.parse(readFileSync(claudeConfigPath, "utf-8"));
+    } catch {
+      claudeConfig = {};
+    }
+
+    const mcpServers = (claudeConfig.mcpServers ?? {}) as Record<string, unknown>;
+
+    // Session-scoped key: mesh:<service>:<sessionId>
+    const sessionTag = `${process.pid}`;
+
+    for (const svc of serviceCatalog) {
+      if (svc.status !== "running") continue;
+      const entryKey = `mesh:${svc.name}:${sessionTag}`;
+      const entry = {
+        command: "claudemesh",
+        args: ["mcp", "--service", svc.name],
+        env: {
+          CLAUDEMESH_CONFIG_DIR: tmpDir,
+        },
+        _meshSession: {
+          pid: process.pid,
+          meshSlug: mesh.slug,
+          serviceName: svc.name,
+          createdAt: new Date().toISOString(),
+        },
+      };
+      mcpServers[entryKey] = entry;
+      meshMcpEntries.push({ key: entryKey, entry });
+    }
+
+    claudeConfig.mcpServers = mcpServers;
+    writeFileSync(claudeConfigPath, JSON.stringify(claudeConfig, null, 2) + "\n", "utf-8");
+
+    if (!args.quiet && meshMcpEntries.length > 0) {
+      console.log(`  ${meshMcpEntries.length} mesh service(s) registered as native MCPs:`);
+      for (const { key } of meshMcpEntries) {
+        const svcName = key.split(":")[1];
+        const svc = serviceCatalog.find(s => s.name === svcName);
+        console.log(`    ${svcName} (${svc?.tools.length ?? 0} tools)`);
+      }
+      console.log("");
+    }
+  }
+
+  // 6. Spawn claude with ephemeral config + dev channel + auto-permissions.
+  //    Strip any user-supplied --dangerously flags to avoid duplicates.
+  const filtered: string[] = [];
+  for (let i = 0; i < args.claudeArgs.length; i++) {
+    if (args.claudeArgs[i] === "--dangerously-load-development-channels"
+        || args.claudeArgs[i] === "--dangerously-skip-permissions") {
+      if (args.claudeArgs[i] === "--dangerously-load-development-channels") i++;
+      continue;
+    }
+    filtered.push(args.claudeArgs[i]!);
+  }
+  // --dangerously-skip-permissions is only added when the user explicitly
+  // passes -y / --yes. Without it, claudemesh tools still work because
+  // `claudemesh install` pre-approves them via allowedTools in settings.json.
+  // This keeps permissions tight for multi-person meshes.
+  // Session identity: --resume reuses existing session, otherwise generate new.
+  // When resuming, Claude Code reuses the session ID so the mesh peer identity persists.
+  const isResume = args.resume !== null || args.continueSession;
+  const claudeSessionId = isResume ? undefined : randomUUID();
+
+  const claudeArgs = [
+    "--dangerously-load-development-channels",
+    "server:claudemesh",
+    ...(claudeSessionId ? ["--session-id", claudeSessionId] : []),
+    ...(args.resume ? ["--resume", args.resume] : []),
+    ...(args.continueSession ? ["--continue"] : []),
+    ...(args.skipPermConfirm ? ["--dangerously-skip-permissions"] : []),
+    ...(args.systemPrompt ? ["--system-prompt", args.systemPrompt] : []),
+    ...filtered,
+  ];
+
+  // Resolve the full path to `claude` — when launched from a non-interactive
+  // shell (e.g. nvm node shebang), ~/.local/bin may not be in PATH.
+  const isWindows = process.platform === "win32";
+  let claudeBin = "claude";
+  if (!isWindows) {
+    const candidates = [
+      join(homedir(), ".local", "bin", "claude"),
+      "/usr/local/bin/claude",
+      join(homedir(), ".claude", "bin", "claude"),
+    ];
+    for (const c of candidates) {
+      if (existsSync(c)) { claudeBin = c; break; }
+    }
+  }
+
+  // 7. Define cleanup — runs on every exit path via process.on('exit').
+  //    Synchronous-only (rmSync + writeFileSync) so it works inside the
+  //    'exit' event, which does not allow async work.
+  const cleanup = (): void => {
+    // Remove mesh MCP entries from ~/.claude.json
+    if (meshMcpEntries.length > 0) {
+      try {
+        const claudeConfigPath = join(homedir(), ".claude.json");
+        const claudeConfig = JSON.parse(readFileSync(claudeConfigPath, "utf-8"));
+        const mcpServers = claudeConfig.mcpServers ?? {};
+        for (const { key } of meshMcpEntries) {
+          delete mcpServers[key];
+        }
+        claudeConfig.mcpServers = mcpServers;
+        writeFileSync(claudeConfigPath, JSON.stringify(claudeConfig, null, 2) + "\n", "utf-8");
+      } catch { /* best effort */ }
+    }
+    // Ephemeral config dir
+    try {
+      rmSync(tmpDir, { recursive: true, force: true });
+    } catch { /* best effort */ }
+  };
+
+  // Register cleanup on every exit path — including normal exit, uncaught
+  // throws, and fatal signals. process.on('exit') fires synchronously, which
+  // is what the rmSync + writeFileSync above need.
+  process.on("exit", cleanup);
+
+  // 8. Hard-reset the TTY before handing control to claude.
+  //
+  // Every interactive element in the pre-launch flow — the full-screen
+  // wizard (tui/screen.ts), the permission confirmation, the callback-
+  // listener paste prompt, the mesh picker — attaches listeners to
+  // process.stdin, toggles raw mode, hides the cursor, and sometimes
+  // enters the alt-screen. Those helpers do best-effort cleanup in their
+  // own finally blocks, but any leak — an orphaned 'data' listener, a
+  // still-raw TTY, a pending render paint — means the parent node process
+  // keeps competing with claude's Ink TUI for the same keystrokes and
+  // stdout frames. Symptoms: dropped keystrokes at the claude prompt, or
+  // the wizard visibly repainting on top of claude after launch.
+  //
+  // Defensive reset here is cheap and guarantees a clean TTY regardless
+  // of what the wizard helpers did or didn't restore.
+  if (process.stdin.isTTY) {
+    try { process.stdin.setRawMode(false); } catch { /* not a TTY under some parents */ }
+  }
+  process.stdin.removeAllListeners("data");
+  process.stdin.removeAllListeners("keypress");
+  process.stdin.removeAllListeners("readable");
+  process.stdin.pause();
+  if (process.stdout.isTTY) {
+    process.stdout.write("\x1b[?25h");   // show cursor
+    process.stdout.write("\x1b[?1049l"); // exit alt-screen if any wizard step entered it
+  }
+
+  // 9. Block-and-wait on claude with spawnSync.
+  //
+  // Why spawnSync instead of spawn + child.on('exit'):
+  //   - spawn keeps the parent node event loop running alongside claude.
+  //     Any stray listener, setImmediate, or async wizard tail-end can
+  //     still fire during claude's lifetime, stealing input or painting
+  //     over claude's TUI.
+  //   - spawnSync blocks the parent event loop completely until claude
+  //     exits. No listeners fire. Nothing paints. The parent is effectively
+  //     suspended, and claude has exclusive ownership of the TTY.
+  //
+  // Signal forwarding: claude inherits the TTY process group via
+  // stdio: "inherit". When the user hits Ctrl-C, the terminal sends
+  // SIGINT to the whole group. Claude handles it (Ink unmounts, exits
+  // cleanly); spawnSync returns with result.signal='SIGINT'. We re-raise
+  // the same signal on the parent so it dies the same way.
+  const result = spawnSync(claudeBin, claudeArgs, {
+    stdio: "inherit",
+    shell: isWindows,
+    env: {
+      ...process.env,
+      CLAUDEMESH_CONFIG_DIR: tmpDir,
+      CLAUDEMESH_DISPLAY_NAME: displayName,
+      ...(claudeSessionId ? { CLAUDEMESH_SESSION_ID: claudeSessionId } : {}),
+      MCP_TIMEOUT: process.env.MCP_TIMEOUT ?? "30000",
+      MAX_MCP_OUTPUT_TOKENS: process.env.MAX_MCP_OUTPUT_TOKENS ?? "50000",
+      ...(role ? { CLAUDEMESH_ROLE: role } : {}),
+    },
+  });
+
+  // 10. Handle the result. Cleanup runs automatically via process.on('exit').
+  if (result.error) {
+    const err = result.error as NodeJS.ErrnoException;
+    if (err.code === "ENOENT") {
+      console.error("✗ `claude` not found on PATH. Install Claude Code first.");
+    } else {
+      console.error(`✗ failed to launch claude: ${err.message}`);
+    }
+    process.exit(1);
+  }
+
+  if (result.signal) {
+    // Re-raise the same signal so the parent dies the same way the child did.
+    process.kill(process.pid, result.signal);
+    return;
+  }
+
+  process.exit(result.status ?? 0);
+}
--- a/apps/cli-v2/src/commands/leave.ts
+++ b/apps/cli-v2/src/commands/leave.ts
@@ -0,0 +1,25 @@
+/**
+ * `claudemesh leave <slug>` — remove a mesh from local config.
+ *
+ * Does NOT (yet) notify the broker. In 15b+ this will send a
+ * best-effort revoke request before removing the entry.
+ */
+
+import { readConfig, writeConfig } from "~/services/config/facade.js";
+
+export function runLeave(args: string[]): void {
+  const slug = args[0];
+  if (!slug) {
+    console.error("Usage: claudemesh leave <slug>");
+    process.exit(1);
+  }
+  const config = readConfig();
+  const before = config.meshes.length;
+  config.meshes = config.meshes.filter((m) => m.slug !== slug);
+  if (config.meshes.length === before) {
+    console.error(`claudemesh: no joined mesh with slug "${slug}"`);
+    process.exit(1);
+  }
+  writeConfig(config);
+  console.log(`Left mesh "${slug}". Remaining: ${config.meshes.length}`);
+}
--- a/apps/cli-v2/src/commands/list.ts
+++ b/apps/cli-v2/src/commands/list.ts
@@ -0,0 +1,104 @@
+/**
+ * `claudemesh mesh list` — merged view of server + local meshes.
+ */
+
+import { readConfig, getConfigPath } from "~/services/config/facade.js";
+import { getStoredToken } from "~/services/auth/facade.js";
+import { request } from "~/services/api/facade.js";
+import { URLS } from "~/constants/urls.js";
+import { bold, dim, green, yellow, red } from "~/ui/styles.js";
+
+const BROKER_HTTP = URLS.BROKER.replace("wss://", "https://").replace("ws://", "http://").replace("/ws", "");
+
+interface ServerMesh {
+  id: string;
+  slug: string;
+  name: string;
+  role: string;
+  is_owner: boolean;
+  member_count: number;
+  active_peers: number;
+  joined_at: string;
+}
+
+export async function runList(): Promise<void> {
+  const config = readConfig();
+  const auth = getStoredToken();
+
+  // Try to fetch from server
+  let serverMeshes: ServerMesh[] = [];
+  if (auth) {
+    try {
+      let userId = "";
+      try {
+        const payload = JSON.parse(Buffer.from(auth.session_token.split(".")[1]!, "base64url").toString()) as { sub?: string };
+        userId = payload.sub ?? "";
+      } catch {}
+
+      if (userId) {
+        const res = await request<{ meshes: ServerMesh[] }>({
+          path: `/cli/meshes?user_id=${userId}`,
+          baseUrl: BROKER_HTTP,
+        });
+        serverMeshes = res.meshes ?? [];
+      }
+    } catch {}
+  }
+
+  // Merge: server meshes + local-only meshes
+  const localSlugs = new Set(config.meshes.map(m => m.slug));
+  const serverSlugs = new Set(serverMeshes.map(m => m.slug));
+
+  const allSlugs = new Set([...localSlugs, ...serverSlugs]);
+
+  if (allSlugs.size === 0) {
+    console.log("\n  No meshes yet.\n");
+    console.log("  Create one:  claudemesh mesh create <name>");
+    console.log("  Join one:    claudemesh mesh add <invite-url>\n");
+    return;
+  }
+
+  console.log("\n  Your meshes:\n");
+
+  for (const slug of allSlugs) {
+    const local = config.meshes.find(m => m.slug === slug);
+    const server = serverMeshes.find(m => m.slug === slug);
+
+    const name = server?.name ?? local?.name ?? slug;
+    const role = server?.role ?? "member";
+    const isOwner = server?.is_owner ?? false;
+    const roleLabel = isOwner ? "owner" : role;
+    const memberCount = server?.member_count;
+    const activePeers = server?.active_peers ?? 0;
+
+    // Status indicator
+    const inLocal = localSlugs.has(slug);
+    const inServer = serverSlugs.has(slug);
+    let status: string;
+    let icon: string;
+
+    if (inLocal && inServer) {
+      icon = green("●");
+      status = activePeers > 0 ? green(`${activePeers} online`) : dim("synced");
+    } else if (inLocal && !inServer) {
+      icon = yellow("●");
+      status = yellow("local only");
+    } else {
+      icon = dim("○");
+      status = dim("not added locally");
+    }
+
+    const memberInfo = memberCount ? dim(`${memberCount} member${memberCount !== 1 ? "s" : ""}`) : "";
+    const parts = [roleLabel, memberInfo, status].filter(Boolean);
+
+    console.log(`    ${icon} ${bold(name)}  ${dim(slug)}`);
+    console.log(`      ${parts.join("  ·  ")}`);
+  }
+
+  console.log("");
+  if (serverMeshes.some(m => !localSlugs.has(m.slug))) {
+    console.log(dim("    ○ = server only — run `claudemesh mesh add` to use locally"));
+  }
+  console.log(dim(`    Config: ${getConfigPath()}`));
+  console.log("");
+}
--- a/apps/cli-v2/src/commands/login.ts
+++ b/apps/cli-v2/src/commands/login.ts
@@ -0,0 +1,118 @@
+import { createInterface } from "node:readline";
+import { loginWithDeviceCode, getStoredToken, clearToken, storeToken } from "~/services/auth/facade.js";
+import { my } from "~/services/api/facade.js";
+import { green, dim, bold, icons } from "~/ui/styles.js";
+import { EXIT } from "~/constants/exit-codes.js";
+import { URLS } from "~/constants/urls.js";
+
+function prompt(question: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => { rl.close(); resolve(answer.trim()); });
+  });
+}
+
+async function loginWithToken(): Promise<number> {
+  console.log(`\n  Paste a token from ${dim(URLS.API_BASE + "/token")}`);
+  console.log(`  ${dim("Generate one in your browser, then paste it here.")}\n`);
+
+  const token = await prompt("  Token: ");
+  if (!token) {
+    console.error(`  ${icons.cross} No token provided.`);
+    return EXIT.AUTH_FAILED;
+  }
+
+  // Decode JWT to get user info
+  let user = { id: "", display_name: "", email: "" };
+  try {
+    const parts = token.split(".");
+    if (parts[1]) {
+      const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString()) as {
+        sub?: string; email?: string; name?: string; exp?: number;
+      };
+      if (payload.exp && payload.exp < Date.now() / 1000) {
+        console.error(`  ${icons.cross} Token expired. Generate a new one.`);
+        return EXIT.AUTH_FAILED;
+      }
+      user = {
+        id: payload.sub ?? "",
+        display_name: payload.name ?? payload.email ?? "",
+        email: payload.email ?? "",
+      };
+    }
+  } catch {
+    console.error(`  ${icons.cross} Invalid token format.`);
+    return EXIT.AUTH_FAILED;
+  }
+
+  storeToken({ session_token: token, user, token_source: "manual" });
+  console.log(`  ${green(icons.check)} Signed in as ${user.display_name || user.email || "user"}.`);
+  return EXIT.SUCCESS;
+}
+
+async function syncMeshes(token: string): Promise<void> {
+  try {
+    const meshes = await my.getMeshes(token);
+    if (meshes.length > 0) {
+      const names = meshes.map((m) => m.slug).join(", ");
+      console.log(`  ${green(icons.check)} Synced ${meshes.length} mesh${meshes.length === 1 ? "" : "es"}: ${names}`);
+    }
+  } catch {}
+}
+
+export async function login(): Promise<number> {
+  const existing = getStoredToken();
+  if (existing) {
+    const name = existing.user.display_name || existing.user.email || "unknown";
+    console.log(`\n  Already signed in as ${bold(name)}.`);
+    console.log("");
+    console.log(`    ${bold("1)")} Continue as ${name}`);
+    console.log(`    ${bold("2)")} Sign in via browser`);
+    console.log(`    ${bold("3)")} Paste a token from ${dim("claudemesh.com/token")}`);
+    console.log(`    ${bold("4)")} Sign out`);
+    console.log("");
+
+    const choice = await prompt("  Choice [1]: ") || "1";
+
+    if (choice === "1") {
+      console.log(`\n  ${green(icons.check)} Continuing as ${name}.`);
+      return EXIT.SUCCESS;
+    }
+    if (choice === "4") {
+      clearToken();
+      console.log(`  ${green(icons.check)} Signed out.`);
+      return EXIT.SUCCESS;
+    }
+    if (choice === "3") {
+      clearToken();
+      return loginWithToken();
+    }
+    // choice === "2" → fall through to browser login
+    clearToken();
+    console.log(`  ${dim("Signing in…")}`);
+  } else {
+    // Not logged in — show auth options
+    console.log(`\n  ${bold("claudemesh")} — sign in to connect your terminal`);
+    console.log("");
+    console.log(`    ${bold("1)")} Sign in via browser ${dim("(opens automatically)")}`);
+    console.log(`    ${bold("2)")} Paste a token from ${dim("claudemesh.com/token")}`);
+    console.log("");
+
+    const choice = await prompt("  Choice [1]: ") || "1";
+
+    if (choice === "2") {
+      return loginWithToken();
+    }
+    // choice === "1" → fall through to browser login
+  }
+
+  try {
+    const result = await loginWithDeviceCode();
+    console.log(`  ${green(icons.check)} Signed in as ${result.user.display_name}.`);
+    await syncMeshes(result.session_token);
+    return EXIT.SUCCESS;
+  } catch (err) {
+    console.error(`  ${icons.cross} Login failed: ${err instanceof Error ? err.message : err}`);
+    return EXIT.AUTH_FAILED;
+  }
+}
--- a/apps/cli-v2/src/commands/logout.ts
+++ b/apps/cli-v2/src/commands/logout.ts
@@ -0,0 +1,22 @@
+import { logout as doLogout } from "~/services/auth/facade.js";
+import { green, yellow, icons } from "~/ui/styles.js";
+import { EXIT } from "~/constants/exit-codes.js";
+
+export async function logout(): Promise<number> {
+  try {
+    const { revoked } = await doLogout();
+
+    if (revoked) {
+      console.log(`  ${green(icons.check)} Revoked session on claudemesh.com`);
+    } else {
+      console.log(`  ${yellow(icons.warn)} Could not revoke session on claudemesh.com.`);
+      console.log(`    Revoke manually at https://claudemesh.com/dashboard/settings/sessions`);
+    }
+    console.log(`  ${green(icons.check)} Removed local credentials.`);
+
+    return EXIT.SUCCESS;
+  } catch (err) {
+    console.error(`  ${icons.cross} Logout failed: ${err instanceof Error ? err.message : err}`);
+    return EXIT.AUTH_FAILED;
+  }
+}
--- a/apps/cli-v2/src/commands/mcp.ts
+++ b/apps/cli-v2/src/commands/mcp.ts
@@ -0,0 +1,9 @@
+import { startMcpServer } from "~/mcp/server.js";
+
+export async function runMcp(): Promise<never> {
+  await startMcpServer();
+  await new Promise(() => {});
+  process.exit(0);
+}
+
+export { runMcp as _stub };
--- a/apps/cli-v2/src/commands/new.ts
+++ b/apps/cli-v2/src/commands/new.ts
@@ -0,0 +1,48 @@
+import { create as createMesh } from "~/services/mesh/facade.js";
+import { getStoredToken } from "~/services/auth/facade.js";
+import { green, dim, icons } from "~/ui/styles.js";
+import { EXIT } from "~/constants/exit-codes.js";
+
+export async function newMesh(
+  name: string,
+  opts: { template?: string; description?: string; json?: boolean },
+): Promise<number> {
+  if (!name) {
+    console.error("  Usage: claudemesh mesh create <name>");
+    return EXIT.INVALID_ARGS;
+  }
+
+  if (!getStoredToken()) {
+    console.log(dim("  Not signed in — starting login…\n"));
+    const { login } = await import("./login.js");
+    const loginResult = await login();
+    if (loginResult !== EXIT.SUCCESS) return loginResult;
+    console.log("");
+  }
+
+  try {
+    const result = await createMesh(name, {
+      template: opts.template,
+      description: opts.description,
+    });
+
+    if (opts.json) {
+      console.log(JSON.stringify({ schema_version: "1.0", ...result }, null, 2));
+    } else {
+      console.log(`\n  ${green(icons.check)} Created "${result.slug}" (id: ${result.id})`);
+      console.log(`  ${green(icons.check)} You're the owner`);
+      console.log(`  ${green(icons.check)} Joined locally`);
+      console.log(`\n  Share with: claudemesh mesh share\n`);
+    }
+
+    return EXIT.SUCCESS;
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("409") || msg.includes("already exists")) {
+      console.error(`  ${icons.cross} A mesh with this name already exists. Try a different name.`);
+    } else {
+      console.error(`  ${icons.cross} Failed: ${msg}`);
+    }
+    return EXIT.INTERNAL_ERROR;
+  }
+}
--- a/apps/cli-v2/src/commands/peers.ts
+++ b/apps/cli-v2/src/commands/peers.ts
@@ -0,0 +1,82 @@
+/**
+ * `claudemesh peers` — list connected peers in the mesh.
+ *
+ * Shows all meshes by default, or filter with --mesh.
+ */
+
+import { withMesh } from "./connect.js";
+import { readConfig } from "~/services/config/facade.js";
+
+export interface PeersFlags {
+  mesh?: string;
+  json?: boolean;
+}
+
+export async function runPeers(flags: PeersFlags): Promise<void> {
+  const useColor =
+    !process.env.NO_COLOR && process.env.TERM !== "dumb" && process.stdout.isTTY;
+  const dim = (s: string) => (useColor ? `\x1b[2m${s}\x1b[22m` : s);
+  const bold = (s: string) => (useColor ? `\x1b[1m${s}\x1b[22m` : s);
+  const green = (s: string) => (useColor ? `\x1b[32m${s}\x1b[39m` : s);
+  const yellow = (s: string) => (useColor ? `\x1b[33m${s}\x1b[39m` : s);
+
+  const config = readConfig();
+
+  // If --mesh specified, show only that one. Otherwise show all.
+  const slugs = flags.mesh
+    ? [flags.mesh]
+    : config.meshes.map(m => m.slug);
+
+  if (slugs.length === 0) {
+    console.error("No meshes joined. Run `claudemesh join <url>` first.");
+    process.exit(1);
+  }
+
+  const allJson: Array<{ mesh: string; peers: unknown[] }> = [];
+
+  for (const slug of slugs) {
+    try {
+      await withMesh({ meshSlug: slug }, async (client, mesh) => {
+        const peers = await client.listPeers();
+
+        if (flags.json) {
+          allJson.push({ mesh: mesh.slug, peers });
+          return;
+        }
+
+        console.log(bold(`Peers on ${mesh.slug}`) + dim(` (${peers.length})`));
+        console.log("");
+
+        if (peers.length === 0) {
+          console.log(dim("  No peers connected."));
+        } else {
+          for (const p of peers) {
+            const groups = p.groups.length
+              ? " [" + p.groups.map((g: { name: string; role?: string }) =>
+                  `@${g.name}${g.role ? `:${g.role}` : ""}`).join(", ") + "]"
+              : "";
+            const statusIcon = p.status === "working" ? yellow("●") : green("●");
+            const name = bold(p.displayName);
+            const meta: string[] = [];
+            if (p.peerType) meta.push(p.peerType);
+            if (p.channel) meta.push(p.channel);
+            if (p.model) meta.push(p.model);
+            const metaStr = meta.length ? dim(` (${meta.join(", ")})`) : "";
+            const cwdStr = p.cwd ? dim(`  cwd: ${p.cwd}`) : "";
+            const summary = p.summary ? dim(`  ${p.summary}`) : "";
+            console.log(`  ${statusIcon} ${name}${groups}${metaStr}${summary}`);
+            if (cwdStr) console.log(`    ${cwdStr}`);
+          }
+        }
+        console.log("");
+      });
+    } catch (e) {
+      console.error(dim(`  Could not connect to ${slug}: ${e instanceof Error ? e.message : String(e)}`));
+      console.log("");
+    }
+  }
+
+  if (flags.json) {
+    console.log(JSON.stringify(slugs.length === 1 ? allJson[0]?.peers : allJson, null, 2));
+  }
+}
--- a/apps/cli-v2/src/commands/profile.ts
+++ b/apps/cli-v2/src/commands/profile.ts
@@ -0,0 +1,114 @@
+/**
+ * `claudemesh profile` — view or edit your member profile.
+ *
+ * Profile fields (roleTag, groups, messageMode, displayName) are persistent
+ * on the server. Changes are pushed to active sessions in real-time.
+ */
+
+import { readConfig } from "~/services/config/facade.js";
+import { BrokerClient } from "~/services/broker/facade.js";
+
+export interface ProfileFlags {
+  mesh?: string;
+  "role-tag"?: string;
+  groups?: string;
+  "message-mode"?: string;
+  name?: string;
+  member?: string;  // admin only: edit another member
+  json?: boolean;
+}
+
+export async function runProfile(flags: ProfileFlags): Promise<void> {
+  const useColor = !process.env.NO_COLOR && process.env.TERM !== "dumb" && process.stdout.isTTY;
+  const dim = (s: string): string => (useColor ? `\x1b[2m${s}\x1b[22m` : s);
+  const green = (s: string): string => (useColor ? `\x1b[32m${s}\x1b[39m` : s);
+
+  const config = readConfig();
+  if (config.meshes.length === 0) {
+    console.error("No meshes joined. Run `claudemesh join <url>` first.");
+    process.exit(1);
+  }
+
+  // Pick mesh
+  const mesh = flags.mesh
+    ? config.meshes.find(m => m.slug === flags.mesh)
+    : config.meshes[0]!;
+
+  if (!mesh) {
+    console.error(`Mesh "${flags.mesh}" not found. Joined: ${config.meshes.map(m => m.slug).join(", ")}`);
+    process.exit(1);
+  }
+
+  // Derive broker HTTP URL from WSS URL
+  const brokerUrl = mesh.brokerUrl.replace("wss://", "https://").replace("ws://", "http://").replace(/\/ws\/?$/, "");
+
+  const hasEdits = flags["role-tag"] !== undefined || flags.groups !== undefined || flags["message-mode"] !== undefined || flags.name !== undefined;
+
+  if (hasEdits) {
+    // PATCH member profile
+    const targetMemberId = flags.member ?? mesh.memberId; // TODO: resolve --member by name
+    const body: Record<string, unknown> = {};
+    if (flags.name !== undefined) body.displayName = flags.name;
+    if (flags["role-tag"] !== undefined) body.roleTag = flags["role-tag"];
+    if (flags.groups !== undefined) {
+      body.groups = flags.groups.split(",").map(s => {
+        const [name, role] = s.trim().split(":");
+        return role ? { name: name!, role } : { name: name! };
+      });
+    }
+    if (flags["message-mode"] !== undefined) body.messageMode = flags["message-mode"];
+
+    const res = await fetch(`${brokerUrl}/mesh/${mesh.meshId}/member/${targetMemberId}`, {
+      method: "PATCH",
+      headers: {
+        "Content-Type": "application/json",
+        "X-Member-Id": mesh.memberId,
+      },
+      body: JSON.stringify(body),
+    });
+
+    const result = await res.json() as Record<string, unknown>;
+    if (flags.json) {
+      console.log(JSON.stringify(result, null, 2));
+    } else if (result.ok) {
+      console.log(green("✓ Profile updated"));
+      const member = result.member as Record<string, unknown>;
+      printProfile(member, dim);
+    } else {
+      console.error(`Error: ${result.error}`);
+      process.exit(1);
+    }
+  } else {
+    // GET members list, show current user's profile
+    const res = await fetch(`${brokerUrl}/mesh/${mesh.meshId}/members`);
+    const result = await res.json() as { ok: boolean; members?: Array<Record<string, unknown>>; error?: string };
+
+    if (!result.ok) {
+      console.error(`Error: ${result.error}`);
+      process.exit(1);
+    }
+
+    const me = result.members?.find(m => m.id === mesh.memberId);
+    if (flags.json) {
+      console.log(JSON.stringify(me ?? {}, null, 2));
+    } else if (me) {
+      printProfile(me, dim);
+    } else {
+      console.log("Member not found in mesh.");
+    }
+  }
+}
+
+function printProfile(member: Record<string, unknown>, dim: (s: string) => string): void {
+  const groups = member.groups as Array<{ name: string; role?: string }> | undefined;
+  const groupStr = groups?.length
+    ? groups.map(g => g.role ? `${g.name} (${g.role})` : g.name).join(", ")
+    : dim("(none)");
+
+  console.log(`  Name:     ${member.displayName ?? dim("(not set)")}`);
+  console.log(`  Role:     ${member.roleTag ?? dim("(not set)")}`);
+  console.log(`  Groups:   ${groupStr}`);
+  console.log(`  Messages: ${member.messageMode ?? "push"}`);
+  console.log(`  Access:   ${member.permission ?? "member"}`);
+  console.log(`  Mesh:     ${dim(String(member.id ?? ""))}`);
+}
--- a/apps/cli-v2/src/commands/recall.ts
+++ b/apps/cli-v2/src/commands/recall.ts
@@ -0,0 +1,35 @@
+import { allClients } from "~/services/broker/facade.js";
+import { dim, bold } from "~/ui/styles.js";
+import { EXIT } from "~/constants/exit-codes.js";
+
+export async function recall(
+  query: string,
+  opts: { mesh?: string; json?: boolean } = {},
+): Promise<number> {
+  const client = allClients()[0];
+  if (!client) {
+    console.error("Not connected to any mesh.");
+    return EXIT.NETWORK_ERROR;
+  }
+
+  const memories = await client.recall(query);
+
+  if (opts.json) {
+    console.log(JSON.stringify(memories, null, 2));
+    return EXIT.SUCCESS;
+  }
+
+  if (memories.length === 0) {
+    console.log(dim("No memories found."));
+    return EXIT.SUCCESS;
+  }
+
+  for (const m of memories) {
+    const tags = m.tags.length ? dim(` [${m.tags.join(", ")}]`) : "";
+    console.log(`${bold(m.id.slice(0, 8))}${tags}`);
+    console.log(`  ${m.content}`);
+    console.log(dim(`  ${m.rememberedBy} \u00B7 ${new Date(m.rememberedAt).toLocaleString()}`));
+    console.log("");
+  }
+  return EXIT.SUCCESS;
+}
--- a/apps/cli-v2/src/commands/register.ts
+++ b/apps/cli-v2/src/commands/register.ts
@@ -0,0 +1,8 @@
+import { login } from "./login.js";
+
+// Register and login use the same device-code flow.
+// The browser page (/cli-auth) redirects to /auth/login if not authenticated,
+// which has a "Don't have an account? Register" link.
+export async function register(): Promise<number> {
+  return login();
+}
--- a/apps/cli-v2/src/commands/remember.ts
+++ b/apps/cli-v2/src/commands/remember.ts
@@ -0,0 +1,28 @@
+import { allClients } from "~/services/broker/facade.js";
+import { EXIT } from "~/constants/exit-codes.js";
+
+export async function remember(
+  content: string,
+  opts: { mesh?: string; tags?: string; json?: boolean } = {},
+): Promise<number> {
+  const client = allClients()[0];
+  if (!client) {
+    console.error("Not connected to any mesh.");
+    return EXIT.NETWORK_ERROR;
+  }
+
+  const tags = opts.tags?.split(",").map((t) => t.trim()).filter(Boolean);
+  const id = await client.remember(content, tags);
+
+  if (opts.json) {
+    console.log(JSON.stringify({ id, content, tags }));
+    return EXIT.SUCCESS;
+  }
+
+  if (id) {
+    console.log(`\u2713 Remembered (${id.slice(0, 8)})`);
+    return EXIT.SUCCESS;
+  }
+  console.error("\u2717 Failed to store memory");
+  return EXIT.INTERNAL_ERROR;
+}
--- a/apps/cli-v2/src/commands/remind.ts
+++ b/apps/cli-v2/src/commands/remind.ts
@@ -0,0 +1,142 @@
+/**
+ * `claudemesh remind <message> --in <duration> | --at <time>`
+ * `claudemesh remind list`
+ * `claudemesh remind cancel <id>`
+ *
+ * Human-facing interface to the broker's scheduled message delivery.
+ */
+
+import { withMesh } from "./connect.js";
+
+export interface RemindFlags {
+  mesh?: string;
+  in?: string;       // e.g. "2h", "30m", "90s"
+  at?: string;       // ISO or HH:MM
+  cron?: string;     // 5-field cron expression for recurring
+  to?: string;       // default: self
+  json?: boolean;
+}
+
+function parseDuration(raw: string): number | null {
+  const m = raw.trim().match(/^(\d+(?:\.\d+)?)\s*(s|sec|m|min|h|hr|d|day)?$/i);
+  if (!m) return null;
+  const n = parseFloat(m[1]!);
+  const unit = (m[2] ?? "s").toLowerCase();
+  if (unit.startsWith("d")) return n * 86_400_000;
+  if (unit.startsWith("h")) return n * 3_600_000;
+  if (unit.startsWith("m")) return n * 60_000;
+  return n * 1_000;
+}
+
+function parseDeliverAt(flags: RemindFlags): number | null {
+  if (flags.in) {
+    const ms = parseDuration(flags.in);
+    if (ms === null) return null;
+    return Date.now() + ms;
+  }
+  if (flags.at) {
+    // Try HH:MM first
+    const hm = flags.at.match(/^(\d{1,2}):(\d{2})$/);
+    if (hm) {
+      const now = new Date();
+      const target = new Date(now);
+      target.setHours(parseInt(hm[1]!, 10), parseInt(hm[2]!, 10), 0, 0);
+      if (target <= now) target.setDate(target.getDate() + 1); // next occurrence
+      return target.getTime();
+    }
+    const ts = Date.parse(flags.at);
+    return isNaN(ts) ? null : ts;
+  }
+  return null;
+}
+
+export async function runRemind(
+  flags: RemindFlags,
+  positional: string[],
+): Promise<void> {
+  const useColor = !process.env.NO_COLOR && process.env.TERM !== "dumb" && process.stdout.isTTY;
+  const dim = (s: string) => (useColor ? `\x1b[2m${s}\x1b[22m` : s);
+  const bold = (s: string) => (useColor ? `\x1b[1m${s}\x1b[22m` : s);
+
+  const action = positional[0];
+
+  // claudemesh remind list
+  if (action === "list") {
+    await withMesh({ meshSlug: flags.mesh ?? null }, async (client) => {
+      const scheduled = await client.listScheduled();
+      if (flags.json) { console.log(JSON.stringify(scheduled, null, 2)); return; }
+      if (scheduled.length === 0) { console.log(dim("No pending reminders.")); return; }
+      for (const m of scheduled) {
+        const when = new Date(m.deliverAt).toLocaleString();
+        const to = m.to === client.getSessionPubkey() ? dim("(self)") : m.to;
+        console.log(`  ${bold(m.id.slice(0, 8))} → ${to} at ${when}`);
+        console.log(`  ${dim(m.message.slice(0, 80))}`);
+        console.log("");
+      }
+    });
+    return;
+  }
+
+  // claudemesh remind cancel <id>
+  if (action === "cancel") {
+    const id = positional[1];
+    if (!id) { console.error("Usage: claudemesh remind cancel <id>"); process.exit(1); }
+    await withMesh({ meshSlug: flags.mesh ?? null }, async (client) => {
+      const ok = await client.cancelScheduled(id);
+      if (ok) console.log(`✓ Cancelled ${id}`);
+      else { console.error(`✗ Not found or already fired: ${id}`); process.exit(1); }
+    });
+    return;
+  }
+
+  // claudemesh remind <message> --in <duration> | --at <time> | --cron <expr>
+  const message = action ?? positional.join(" ");
+  if (!message) {
+    console.error("Usage: claudemesh remind <message> --in <duration>");
+    console.error("       claudemesh remind <message> --at <time>");
+    console.error('       claudemesh remind <message> --cron "0 */2 * * *"');
+    console.error("       claudemesh remind list");
+    console.error("       claudemesh remind cancel <id>");
+    process.exit(1);
+  }
+
+  const isCron = !!flags.cron;
+  const deliverAt = isCron ? 0 : parseDeliverAt(flags);
+  if (!isCron && deliverAt === null) {
+    console.error('Specify when: --in <duration> (e.g. "2h", "30m"), --at <time> (e.g. "15:00"), or --cron <expression>');
+    process.exit(1);
+  }
+
+  await withMesh({ meshSlug: flags.mesh ?? null }, async (client) => {
+    // Determine target: --to flag or self
+    let targetSpec: string;
+    if (flags.to && flags.to !== "self") {
+      if (flags.to.startsWith("@") || flags.to === "*" || /^[0-9a-f]{64}$/i.test(flags.to)) {
+        targetSpec = flags.to;
+      } else {
+        const peers = await client.listPeers();
+        const match = peers.find((p) => p.displayName.toLowerCase() === flags.to!.toLowerCase());
+        if (!match) {
+          console.error(`Peer "${flags.to}" not found. Online: ${peers.map((p) => p.displayName).join(", ") || "(none)"}`);
+          process.exit(1);
+        }
+        targetSpec = match.pubkey;
+      }
+    } else {
+      targetSpec = client.getSessionPubkey() ?? "*";
+    }
+
+    const result = await client.scheduleMessage(targetSpec, message, deliverAt ?? 0, false, flags.cron);
+    if (!result) { console.error("✗ Broker did not acknowledge — check connection"); process.exit(1); }
+
+    if (flags.json) { console.log(JSON.stringify(result)); return; }
+    const toLabel = !flags.to || flags.to === "self" ? "yourself" : flags.to;
+    if (isCron) {
+      const nextFire = new Date(result.deliverAt).toLocaleString();
+      console.log(`✓ Recurring reminder set (${result.scheduledId.slice(0, 8)}): "${message}" → ${toLabel} — cron: ${flags.cron}, next fire: ${nextFire}`);
+    } else {
+      const when = new Date(result.deliverAt).toLocaleString();
+      console.log(`✓ Reminder set (${result.scheduledId.slice(0, 8)}): "${message}" → ${toLabel} at ${when}`);
+    }
+  });
+}
--- a/apps/cli-v2/src/commands/rename.ts
+++ b/apps/cli-v2/src/commands/rename.ts
@@ -0,0 +1,14 @@
+import { rename as renameMesh } from "~/services/mesh/facade.js";
+import { green, icons } from "~/ui/styles.js";
+import { EXIT } from "~/constants/exit-codes.js";
+
+export async function rename(slug: string, newName: string): Promise<number> {
+  try {
+    await renameMesh(slug, newName);
+    console.log(`  ${green(icons.check)} Renamed "${slug}" to "${newName}"`);
+    return EXIT.SUCCESS;
+  } catch (err) {
+    console.error(`  ${icons.cross} Failed: ${err instanceof Error ? err.message : err}`);
+    return EXIT.INTERNAL_ERROR;
+  }
+}
--- a/apps/cli-v2/src/commands/seed-test-mesh.ts
+++ b/apps/cli-v2/src/commands/seed-test-mesh.ts
@@ -0,0 +1,44 @@
+/**
+ * `claudemesh seed-test-mesh` — dev-only helper for 15b testing.
+ *
+ * Writes a locally-valid JoinedMesh entry to ~/.claudemesh/config.json
+ * so the MCP server can connect to a locally-running broker without
+ * invite-link / crypto plumbing.
+ *
+ * Usage:
+ *   claudemesh seed-test-mesh <broker-url> <mesh-id> <member-id> <pubkey> <slug>
+ */
+
+import { readConfig, writeConfig } from "~/services/config/facade.js";
+
+export function runSeedTestMesh(args: string[]): void {
+  const [brokerUrl, meshId, memberId, pubkey, slug] = args;
+  if (!brokerUrl || !meshId || !memberId || !pubkey || !slug) {
+    console.error(
+      "Usage: claudemesh seed-test-mesh <broker-ws-url> <mesh-id> <member-id> <pubkey> <slug>",
+    );
+    console.error("");
+    console.error(
+      'Example: claudemesh seed-test-mesh "ws://localhost:7900/ws" mesh-123 member-abc aaa..aaa smoke-test',
+    );
+    process.exit(1);
+  }
+  const config = readConfig();
+  // Remove any prior entry with same slug (idempotent).
+  config.meshes = config.meshes.filter((m) => m.slug !== slug);
+  config.meshes.push({
+    meshId,
+    memberId,
+    slug,
+    name: `Test: ${slug}`,
+    pubkey,
+    secretKey: "dev-only-stub", // real keypair generated during join in Step 17
+    brokerUrl,
+    joinedAt: new Date().toISOString(),
+  });
+  writeConfig(config);
+  console.log(`Seeded mesh "${slug}" (${meshId}) into local config.`);
+  console.log(
+    `Run \`claudemesh mcp\` to connect, or register with Claude Code via \`claudemesh install\`.`,
+  );
+}
--- a/apps/cli-v2/src/commands/send.ts
+++ b/apps/cli-v2/src/commands/send.ts
@@ -0,0 +1,51 @@
+/**
+ * `claudemesh send <to> <message>` — send a message to a peer or group.
+ *
+ * <to> can be:
+ *   - a display name  ("Mou")
+ *   - a pubkey hex    ("abc123...")
+ *   - @group          ("@flexicar")
+ *   - *               (broadcast to all)
+ */
+
+import { withMesh } from "./connect.js";
+import type { Priority } from "~/services/broker/facade.js";
+
+export interface SendFlags {
+  mesh?: string;
+  priority?: string;
+}
+
+export async function runSend(flags: SendFlags, to: string, message: string): Promise<void> {
+  const priority: Priority =
+    flags.priority === "now" ? "now"
+    : flags.priority === "low" ? "low"
+    : "next";
+
+  await withMesh({ meshSlug: flags.mesh ?? null }, async (client) => {
+    // Resolve display name → pubkey for direct messages.
+    // If `to` starts with @, *, or looks like a hex pubkey, use as-is.
+    let targetSpec = to;
+    if (!to.startsWith("@") && to !== "*" && !/^[0-9a-f]{64}$/i.test(to)) {
+      // Treat as display name — look up pubkey via list_peers.
+      const peers = await client.listPeers();
+      const match = peers.find(
+        (p) => p.displayName.toLowerCase() === to.toLowerCase(),
+      );
+      if (!match) {
+        const names = peers.map((p) => p.displayName).join(", ");
+        console.error(`Peer "${to}" not found. Online: ${names || "(none)"}`);
+        process.exit(1);
+      }
+      targetSpec = match.pubkey;
+    }
+
+    const result = await client.send(targetSpec, message, priority);
+    if (result.ok) {
+      console.log(`✓ Sent to ${to}${result.messageId ? ` (${result.messageId.slice(0, 8)})` : ""}`);
+    } else {
+      console.error(`✗ Send failed: ${result.error ?? "unknown error"}`);
+      process.exit(1);
+    }
+  });
+}
--- a/apps/cli-v2/src/commands/state.ts
+++ b/apps/cli-v2/src/commands/state.ts
@@ -0,0 +1,75 @@
+/**
+ * `claudemesh state get <key>`    — read a shared state value
+ * `claudemesh state set <key> <value>` — write a shared state value
+ * `claudemesh state list`          — list all state entries
+ */
+
+import { withMesh } from "./connect.js";
+
+export interface StateFlags {
+  mesh?: string;
+  json?: boolean;
+}
+
+export async function runStateGet(flags: StateFlags, key: string): Promise<void> {
+  const useColor =
+    !process.env.NO_COLOR && process.env.TERM !== "dumb" && process.stdout.isTTY;
+  const dim = (s: string) => (useColor ? `\x1b[2m${s}\x1b[22m` : s);
+
+  await withMesh({ meshSlug: flags.mesh ?? null }, async (client) => {
+    const entry = await client.getState(key);
+    if (!entry) {
+      console.log(dim(`(not set)`));
+      return;
+    }
+    if (flags.json) {
+      console.log(JSON.stringify(entry, null, 2));
+      return;
+    }
+    const val = typeof entry.value === "string" ? entry.value : JSON.stringify(entry.value);
+    console.log(val);
+    console.log(dim(`  set by ${entry.updatedBy} at ${new Date(entry.updatedAt).toLocaleString()}`));
+  });
+}
+
+export async function runStateSet(flags: StateFlags, key: string, value: string): Promise<void> {
+  // Try to parse as JSON so numbers/booleans/objects work; fall back to string.
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(value);
+  } catch {
+    parsed = value;
+  }
+
+  await withMesh({ meshSlug: flags.mesh ?? null }, async (client) => {
+    await client.setState(key, parsed);
+    console.log(`✓ ${key} = ${JSON.stringify(parsed)}`);
+  });
+}
+
+export async function runStateList(flags: StateFlags): Promise<void> {
+  const useColor =
+    !process.env.NO_COLOR && process.env.TERM !== "dumb" && process.stdout.isTTY;
+  const dim = (s: string) => (useColor ? `\x1b[2m${s}\x1b[22m` : s);
+  const bold = (s: string) => (useColor ? `\x1b[1m${s}\x1b[22m` : s);
+
+  await withMesh({ meshSlug: flags.mesh ?? null }, async (client, mesh) => {
+    const entries = await client.listState();
+
+    if (flags.json) {
+      console.log(JSON.stringify(entries, null, 2));
+      return;
+    }
+
+    if (entries.length === 0) {
+      console.log(dim(`No state on mesh "${mesh.slug}".`));
+      return;
+    }
+
+    for (const e of entries) {
+      const val = typeof e.value === "string" ? e.value : JSON.stringify(e.value);
+      console.log(`${bold(e.key)}: ${val}`);
+      console.log(dim(`  ${e.updatedBy} · ${new Date(e.updatedAt).toLocaleString()}`));
+    }
+  });
+}
--- a/apps/cli-v2/src/commands/status-line.ts
+++ b/apps/cli-v2/src/commands/status-line.ts
@@ -0,0 +1,69 @@
+/**
+ * `claudemesh status-line` — one-line renderer for Claude Code's
+ * `statusLine` setting.
+ *
+ * Must be FAST (Claude Code polls it between every turn) — zero network
+ * I/O. Reads only local config + a peer-state cache maintained by the
+ * MCP server (~/.claudemesh/peer-cache.json, updated on every
+ * list_peers call).
+ *
+ * Output format:
+ *   ◇ <mesh> · <online>/<total> peers · <you>
+ * or:
+ *   ◇ claudemesh (not joined)
+ */
+
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { readConfig } from "~/services/config/facade.js";
+import { EXIT } from "~/constants/exit-codes.js";
+
+interface PeerCacheEntry {
+  total: number;
+  online: number;
+  updatedAt: string;
+  you?: string;
+}
+
+type PeerCache = Record<string, PeerCacheEntry>;
+
+export async function runStatusLine(): Promise<number> {
+  try {
+    const config = readConfig();
+    if (config.meshes.length === 0) {
+      process.stdout.write("◇ claudemesh (not joined)");
+      return EXIT.SUCCESS;
+    }
+
+    const cachePath = join(homedir(), ".claudemesh", "peer-cache.json");
+    let cache: PeerCache = {};
+    if (existsSync(cachePath)) {
+      try {
+        cache = JSON.parse(readFileSync(cachePath, "utf-8")) as PeerCache;
+      } catch {
+        // corrupt — ignore
+      }
+    }
+
+    // Pick the most-recently-used mesh if multiple.
+    const pick = config.meshes[0]!;
+    const entry = cache[pick.slug];
+
+    const age = entry ? Date.now() - new Date(entry.updatedAt).getTime() : Infinity;
+    const fresh = age < 60_000; // < 1 min = live
+
+    if (entry && fresh) {
+      const you = entry.you ? ` · ${entry.you}` : "";
+      process.stdout.write(`◇ ${pick.slug} · ${entry.online}/${entry.total} online${you}`);
+    } else if (entry) {
+      process.stdout.write(`◇ ${pick.slug} · ${entry.online}/${entry.total} (stale)`);
+    } else {
+      process.stdout.write(`◇ ${pick.slug} · idle`);
+    }
+    return EXIT.SUCCESS;
+  } catch {
+    // Never break the status line — just print nothing.
+    return EXIT.SUCCESS;
+  }
+}
--- a/apps/cli-v2/src/commands/status.ts
+++ b/apps/cli-v2/src/commands/status.ts
@@ -0,0 +1,103 @@
+/**
+ * `claudemesh status` — one-shot health report.
+ *
+ * Reports CLI version, config path + permissions, each joined mesh
+ * with broker reachability (WS handshake probe). Exit 0 if every
+ * mesh's broker is reachable, 1 otherwise.
+ */
+
+import { statSync, existsSync } from "node:fs";
+import WebSocket from "ws";
+import { readConfig, getConfigPath } from "~/services/config/facade.js";
+import { VERSION } from "~/constants/urls.js";
+
+interface MeshStatus {
+  slug: string;
+  brokerUrl: string;
+  pubkey: string;
+  reachable: boolean;
+  error?: string;
+}
+
+async function probeBroker(url: string, timeoutMs = 4000): Promise<{ ok: boolean; error?: string }> {
+  return new Promise((resolve) => {
+    const ws = new WebSocket(url);
+    const timer = setTimeout(() => {
+      try { ws.terminate(); } catch { /* noop */ }
+      resolve({ ok: false, error: "timeout" });
+    }, timeoutMs);
+    ws.on("open", () => {
+      clearTimeout(timer);
+      try { ws.close(); } catch { /* noop */ }
+      resolve({ ok: true });
+    });
+    ws.on("error", (err) => {
+      clearTimeout(timer);
+      resolve({ ok: false, error: err.message });
+    });
+  });
+}
+
+export async function runStatus(): Promise<void> {
+  const useColor =
+    !process.env.NO_COLOR && process.env.TERM !== "dumb" && process.stdout.isTTY;
+  const dim = (s: string): string => (useColor ? `\x1b[2m${s}\x1b[22m` : s);
+  const green = (s: string): string => (useColor ? `\x1b[32m${s}\x1b[39m` : s);
+  const red = (s: string): string => (useColor ? `\x1b[31m${s}\x1b[39m` : s);
+
+  console.log(`claudemesh status  (v${VERSION})`);
+  console.log("─".repeat(60));
+
+  const configPath = getConfigPath();
+  let configPerms = "missing";
+  if (existsSync(configPath)) {
+    const st = statSync(configPath);
+    const mode = (st.mode & 0o777).toString(8).padStart(4, "0");
+    configPerms = mode === "0600" ? `${mode} ✓` : `${mode} ⚠ (expected 0600)`;
+  }
+  console.log(`Config:     ${configPath} (${configPerms})`);
+
+  const config = readConfig();
+  if (config.meshes.length === 0) {
+    console.log("");
+    console.log(dim("No meshes joined. Run `claudemesh join <invite-url>` to get started."));
+    process.exit(0);
+  }
+
+  console.log("");
+  console.log(`Meshes (${config.meshes.length}):`);
+
+  const results: MeshStatus[] = [];
+  for (const m of config.meshes) {
+    process.stdout.write(`  ${m.slug.padEnd(20)} probing ${m.brokerUrl}… `);
+    const probe = await probeBroker(m.brokerUrl);
+    results.push({
+      slug: m.slug,
+      brokerUrl: m.brokerUrl,
+      pubkey: m.pubkey,
+      reachable: probe.ok,
+      error: probe.error,
+    });
+    if (probe.ok) {
+      console.log(green("reachable"));
+    } else {
+      console.log(red(`unreachable (${probe.error})`));
+    }
+  }
+
+  console.log("");
+  for (const r of results) {
+    console.log(dim(`  ${r.slug}: pubkey ${r.pubkey.slice(0, 16)}…`));
+  }
+
+  const allOk = results.every((r) => r.reachable);
+  console.log("");
+  if (allOk) {
+    console.log(green("All meshes reachable."));
+    process.exit(0);
+  } else {
+    const broken = results.filter((r) => !r.reachable).length;
+    console.log(red(`${broken} of ${results.length} mesh(es) unreachable.`));
+    process.exit(1);
+  }
+}
--- a/apps/cli-v2/src/commands/sync.ts
+++ b/apps/cli-v2/src/commands/sync.ts
@@ -0,0 +1,89 @@
+/**
+ * `claudemesh sync` — re-sync meshes from dashboard account.
+ *
+ * Opens browser for OAuth, receives sync token, calls broker /cli-sync,
+ * merges new meshes into local config.
+ */
+
+import { createInterface } from "node:readline";
+import { hostname } from "node:os";
+import { readConfig, writeConfig } from "~/services/config/facade.js";
+import { startCallbackListener, generatePairingCode, syncWithBroker } from "~/services/auth/facade.js";
+import { openBrowser } from "~/services/spawn/facade.js";
+import { generateKeypair } from "~/services/crypto/facade.js";
+
+export async function runSync(args: { force?: boolean }): Promise<void> {
+  const useColor = !process.env.NO_COLOR && process.env.TERM !== "dumb" && process.stdout.isTTY;
+  const dim = (s: string): string => (useColor ? `\x1b[2m${s}\x1b[22m` : s);
+  const green = (s: string): string => (useColor ? `\x1b[32m${s}\x1b[39m` : s);
+
+  const config = readConfig();
+
+  const code = generatePairingCode();
+  const listener = await startCallbackListener();
+  const url = `https://claudemesh.com/cli-auth?port=${listener.port}&code=${code}&action=sync`;
+
+  console.log(`Opening browser to sync meshes...`);
+  console.log(dim(`Visit: ${url}`));
+  await openBrowser(url);
+
+  // Race: localhost callback vs manual paste vs timeout
+  const manualPromise = new Promise<string>((resolve) => {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    rl.question("Paste sync token (or wait for browser): ", (answer) => {
+      rl.close();
+      if (answer.trim()) resolve(answer.trim());
+    });
+  });
+
+  const timeoutPromise = new Promise<null>((resolve) => {
+    setTimeout(() => resolve(null), 15 * 60_000);
+  });
+
+  const syncToken = await Promise.race([
+    listener.token,
+    manualPromise,
+    timeoutPromise,
+  ]);
+
+  listener.close();
+
+  if (!syncToken) {
+    console.error("Timed out waiting for sign-in.");
+    process.exit(1);
+  }
+
+  // Use existing keypair from first mesh, or generate new
+  const keypair = config.meshes.length > 0
+    ? { publicKey: config.meshes[0]!.pubkey, secretKey: config.meshes[0]!.secretKey }
+    : await generateKeypair();
+
+  const displayName = config.displayName ?? `${hostname()}-${process.pid}`;
+
+  const result = await syncWithBroker(syncToken, keypair.publicKey, displayName);
+
+  // Merge: add new meshes, skip duplicates
+  let added = 0;
+  for (const m of result.meshes) {
+    if (config.meshes.some(existing => existing.meshId === m.mesh_id)) continue;
+    config.meshes.push({
+      meshId: m.mesh_id,
+      memberId: m.member_id,
+      slug: m.slug,
+      name: m.slug,
+      pubkey: keypair.publicKey,
+      secretKey: keypair.secretKey,
+      brokerUrl: m.broker_url,
+      joinedAt: new Date().toISOString(),
+    });
+    added++;
+  }
+  config.accountId = result.account_id;
+  writeConfig(config);
+
+  if (added > 0) {
+    console.log(green(`✓ Added ${added} new mesh(es)`));
+  } else {
+    console.log(`Already up to date (${config.meshes.length} meshes)`);
+  }
+}
--- a/apps/cli-v2/src/commands/test.ts
+++ b/apps/cli-v2/src/commands/test.ts
@@ -0,0 +1,228 @@
+/**
+ * `claudemesh test` — integration test battery against live broker.
+ *
+ * Creates a temporary mesh, runs all operations, verifies results,
+ * then cleans up. Safe to run repeatedly.
+ */
+
+import { getStoredToken } from "~/services/auth/facade.js";
+import { create as createMesh, leave as leaveMesh } from "~/services/mesh/facade.js";
+import { readConfig } from "~/services/config/facade.js";
+import { request } from "~/services/api/facade.js";
+import { generateKeypair, sign, verify } from "~/services/crypto/facade.js";
+import { BrokerClient } from "~/services/broker/facade.js";
+import { URLS } from "~/constants/urls.js";
+import { runAllChecks } from "~/services/health/facade.js";
+import { green, red, dim, bold, yellow, icons } from "~/ui/styles.js";
+import { EXIT } from "~/constants/exit-codes.js";
+
+const BROKER_HTTP = URLS.BROKER.replace("wss://", "https://").replace("ws://", "http://").replace("/ws", "");
+
+interface TestResult {
+  name: string;
+  ok: boolean;
+  detail: string;
+  ms: number;
+}
+
+const results: TestResult[] = [];
+
+async function run(name: string, fn: () => Promise<string>): Promise<boolean> {
+  const start = Date.now();
+  try {
+    const detail = await fn();
+    results.push({ name, ok: true, detail, ms: Date.now() - start });
+    console.log(`  ${green(icons.check)} ${name.padEnd(18)} ${dim(detail)}`);
+    return true;
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    results.push({ name, ok: false, detail, ms: Date.now() - start });
+    console.log(`  ${red(icons.cross)} ${name.padEnd(18)} ${red(detail)}`);
+    return false;
+  }
+}
+
+export async function runTest(): Promise<number> {
+  const started = Date.now();
+  const meshSlug = `test-e2e-${Date.now().toString(36)}`;
+
+  console.log("");
+  console.log(`  ${bold("claudemesh integration test")}`);
+  console.log(`  ${dim("─".repeat(40))}`);
+  console.log("");
+
+  // --- Auth ---
+  const auth = getStoredToken();
+  if (!auth) {
+    console.log(`  ${red(icons.cross)} Not signed in. Run ${bold("claudemesh login")} first.\n`);
+    return EXIT.AUTH_FAILED;
+  }
+
+  let userId = "";
+  try {
+    const payload = JSON.parse(Buffer.from(auth.session_token.split(".")[1]!, "base64url").toString()) as { sub?: string };
+    userId = payload.sub ?? "";
+  } catch {}
+
+  await run("auth", async () => {
+    if (!userId) throw new Error("invalid token");
+    return `signed in as ${auth.user.display_name || auth.user.email}`;
+  });
+
+  // --- Doctor checks (non-blocking — warns but doesn't fail) ---
+  {
+    const checks = runAllChecks();
+    const failed = checks.filter(c => !c.ok);
+    if (failed.length > 0) {
+      const warns = failed.map(c => c.name).join(", ");
+      console.log(`  ${yellow(icons.warn)} ${"doctor".padEnd(18)} ${dim(warns + " (non-blocking)")}`);
+    } else {
+      console.log(`  ${green(icons.check)} ${"doctor".padEnd(18)} ${dim(checks.length + " checks passed")}`);
+    }
+  }
+
+  // --- Crypto ---
+  await run("crypto", async () => {
+    const kp = await generateKeypair();
+    const sig = await sign("test-message", kp.secretKey);
+    const valid = await verify("test-message", sig, kp.publicKey);
+    if (!valid) throw new Error("signature verification failed");
+    const tampered = await verify("tampered", sig, kp.publicKey);
+    if (tampered) throw new Error("tampered message should not verify");
+    return "keypair + sign + verify round-trip";
+  });
+
+  // --- Mesh create ---
+  let meshId = "";
+  const createOk = await run("create", async () => {
+    const result = await createMesh(meshSlug);
+    meshId = result.id;
+    return `created "${result.slug}" (${result.id.slice(0, 8)}…)`;
+  });
+
+  if (!createOk) {
+    console.log(`\n  ${red("Aborting — mesh creation failed.")}\n`);
+    return EXIT.INTERNAL_ERROR;
+  }
+
+  // --- List ---
+  await run("list", async () => {
+    const config = readConfig();
+    const found = config.meshes.find(m => m.slug === meshSlug);
+    if (!found) throw new Error("mesh not in local config");
+    return `found ${meshSlug} in local config`;
+  });
+
+  // --- Server list ---
+  await run("server list", async () => {
+    const res = await request<{ meshes: Array<{ slug: string }> }>({
+      path: `/cli/meshes?user_id=${userId}`,
+      baseUrl: BROKER_HTTP,
+    });
+    const found = res.meshes?.find(m => m.slug === meshSlug);
+    if (!found) throw new Error("mesh not on server");
+    return `found ${meshSlug} on server (${res.meshes.length} total)`;
+  });
+
+  // --- Connect (broker WS) ---
+  const config = readConfig();
+  const meshConfig = config.meshes.find(m => m.slug === meshSlug);
+  let client: BrokerClient | null = null;
+
+  if (meshConfig) {
+    await run("connect", async () => {
+      client = new BrokerClient(meshConfig, { displayName: "test-runner" });
+      await client.connect();
+      if (client.status !== "open") throw new Error("status: " + client.status);
+      return "broker connected, hello_ack received";
+    });
+
+    // --- Peers ---
+    if (client) {
+      await run("peers", async () => {
+        const peers = await client!.listPeers();
+        return `${peers.length} peer(s) online`;
+      });
+
+      // --- Send ---
+      await run("send", async () => {
+        const result = await client!.send("*", "test-battery-ping", "low");
+        if (!result.ok) throw new Error(result.error ?? "send failed");
+        return `broadcast sent (${result.messageId?.slice(0, 8)}…)`;
+      });
+
+      // --- Remember ---
+      let memoryId: string | null = null;
+      await run("remember", async () => {
+        memoryId = await client!.remember("integration test battery memory probe", ["test", "e2e"]);
+        if (!memoryId) throw new Error("no memory ID returned");
+        return `stored (${memoryId.slice(0, 8)}…)`;
+      });
+
+      // --- Recall (postgres full-text search) ---
+      await run("recall", async () => {
+        await new Promise(r => setTimeout(r, 500));
+        const memories = await client!.recall("integration test battery");
+        if (memories.length === 0) throw new Error("no memories found");
+        return `${memories.length} result(s)`;
+      });
+
+      // --- State ---
+      const stateVal = "test-value-" + Date.now();
+      await run("state set", async () => {
+        await client!.setState("test-e2e-key", stateVal);
+        return "key written";
+      });
+
+      await run("state get", async () => {
+        await new Promise(r => setTimeout(r, 500));
+        const result = await client!.getState("test-e2e-key");
+        if (!result) throw new Error("key not found");
+        if (String(result.value) !== stateVal) throw new Error(`expected ${stateVal}, got ${result.value}`);
+        return `read back: ${String(result.value).slice(0, 20)}…`;
+      });
+
+      // --- Clean up memory ---
+      if (memoryId) {
+        await run("forget", async () => {
+          await client!.forget(memoryId!);
+          return "memory cleaned up";
+        });
+      }
+
+      // --- Disconnect ---
+      await run("disconnect", async () => {
+        client!.close();
+        return "connection closed";
+      });
+    }
+  }
+
+  // --- Delete mesh ---
+  await run("delete", async () => {
+    // Server-side delete
+    await request({
+      path: `/cli/mesh/${meshSlug}`,
+      method: "DELETE",
+      body: { user_id: userId },
+      baseUrl: BROKER_HTTP,
+    });
+    leaveMesh(meshSlug);
+    return `deleted "${meshSlug}" from server + local`;
+  });
+
+  // --- Summary ---
+  const passed = results.filter(r => r.ok).length;
+  const failed = results.filter(r => !r.ok).length;
+  const totalMs = Date.now() - started;
+
+  console.log("");
+  if (failed === 0) {
+    console.log(`  ${green(bold(`${passed}/${results.length} passed`))}  ${dim(`(${(totalMs / 1000).toFixed(1)}s)`)}`);
+  } else {
+    console.log(`  ${red(bold(`${failed} failed`))}, ${green(`${passed} passed`)}  ${dim(`(${(totalMs / 1000).toFixed(1)}s)`)}`);
+  }
+  console.log("");
+
+  return failed > 0 ? EXIT.INTERNAL_ERROR : EXIT.SUCCESS;
+}
--- a/apps/cli-v2/src/commands/uninstall.ts
+++ b/apps/cli-v2/src/commands/uninstall.ts
@@ -0,0 +1,58 @@
+import { readFileSync, writeFileSync, existsSync } from "node:fs";
+import { PATHS } from "~/constants/paths.js";
+import { green, icons } from "~/ui/styles.js";
+import { EXIT } from "~/constants/exit-codes.js";
+
+export async function uninstall(): Promise<number> {
+  let removed = 0;
+
+  // Remove MCP server from ~/.claude.json
+  if (existsSync(PATHS.CLAUDE_JSON)) {
+    try {
+      const raw = readFileSync(PATHS.CLAUDE_JSON, "utf-8");
+      const config = JSON.parse(raw) as Record<string, unknown>;
+      const servers = config.mcpServers as Record<string, unknown> | undefined;
+      if (servers && "claudemesh" in servers) {
+        delete servers.claudemesh;
+        writeFileSync(PATHS.CLAUDE_JSON, JSON.stringify(config, null, 2) + "\n", "utf-8");
+        console.log(`  ${green(icons.check)} Removed MCP server from ~/.claude.json`);
+        removed++;
+      }
+    } catch {}
+  }
+
+  // Remove only claudemesh hooks from ~/.claude/settings.json
+  if (existsSync(PATHS.CLAUDE_SETTINGS)) {
+    try {
+      const raw = readFileSync(PATHS.CLAUDE_SETTINGS, "utf-8");
+      const config = JSON.parse(raw) as Record<string, unknown>;
+      const hooks = config.hooks as Record<string, unknown[]> | undefined;
+      if (hooks) {
+        let removedHooks = 0;
+        for (const [event, entries] of Object.entries(hooks)) {
+          if (!Array.isArray(entries)) continue;
+          const filtered = entries.filter((h: unknown) => {
+            const cmd = typeof h === "object" && h !== null && "command" in h ? String((h as Record<string, unknown>).command) : "";
+            return !cmd.includes("claudemesh");
+          });
+          if (filtered.length < entries.length) {
+            removedHooks += entries.length - filtered.length;
+            if (filtered.length === 0) delete hooks[event];
+            else hooks[event] = filtered;
+          }
+        }
+        if (removedHooks > 0) {
+          writeFileSync(PATHS.CLAUDE_SETTINGS, JSON.stringify(config, null, 2) + "\n", "utf-8");
+          console.log(`  ${green(icons.check)} Removed ${removedHooks} claudemesh hook(s) from settings.json`);
+          removed++;
+        }
+      }
+    } catch {}
+  }
+
+  if (removed === 0) {
+    console.log("  Nothing to remove — claudemesh was not installed.");
+  }
+
+  return EXIT.SUCCESS;
+}
--- a/apps/cli-v2/src/commands/upgrade.ts
+++ b/apps/cli-v2/src/commands/upgrade.ts
@@ -0,0 +1,99 @@
+/**
+ * `claudemesh upgrade` — self-update the CLI to the latest alpha.
+ *
+ * Strategy:
+ *   1. Query npm for the latest @alpha dist-tag.
+ *   2. If we're behind, run `npm i -g claudemesh-cli@alpha` via the same
+ *      npm that installed us (detected from argv[1] path walk).
+ *   3. Print before/after versions.
+ *
+ * For users who got the CLI via the `/install` shell flow (portable Node
+ * in ~/.claudemesh), we call that npm directly so nothing else on the
+ * system is touched.
+ */
+
+import { spawnSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { URLS, VERSION } from "~/constants/urls.js";
+import { render } from "~/ui/render.js";
+import { EXIT } from "~/constants/exit-codes.js";
+
+async function latestAlpha(): Promise<string | null> {
+  try {
+    const res = await fetch(URLS.NPM_REGISTRY, { signal: AbortSignal.timeout(8000) });
+    if (!res.ok) return null;
+    const body = (await res.json()) as { "dist-tags"?: { alpha?: string; latest?: string } };
+    return body["dist-tags"]?.alpha ?? body["dist-tags"]?.latest ?? null;
+  } catch {
+    return null;
+  }
+}
+
+function findNpm(): { npm: string; prefix?: string } {
+  // Portable install path (`/install.sh` puts npm in ~/.claudemesh/node/bin/npm)
+  const portable = join(process.env.HOME ?? "", ".claudemesh", "node", "bin", "npm");
+  if (existsSync(portable)) {
+    return { npm: portable, prefix: join(process.env.HOME ?? "", ".claudemesh") };
+  }
+  // argv[1] → .../node_modules/claudemesh-cli/dist/entrypoints/cli.js
+  // walk up to find a sibling npm binary.
+  let cur = resolve(process.argv[1] ?? ".");
+  for (let i = 0; i < 6; i++) {
+    cur = dirname(cur);
+    const candidate = join(cur, "bin", "npm");
+    if (existsSync(candidate)) return { npm: candidate };
+  }
+  // Fallback to PATH.
+  return { npm: "npm" };
+}
+
+export async function runUpgrade(opts: { check?: boolean; yes?: boolean } = {}): Promise<number> {
+  render.section("claudemesh upgrade");
+  render.kv([
+    ["installed", VERSION],
+    ["checking", "npm registry…"],
+  ]);
+
+  const latest = await latestAlpha();
+  if (!latest) {
+    render.warn("Could not reach npm registry — skipped.");
+    return EXIT.SUCCESS;
+  }
+
+  render.kv([["latest", latest]]);
+
+  if (latest === VERSION) {
+    render.blank();
+    render.ok(`Already on latest (${latest}).`);
+    return EXIT.SUCCESS;
+  }
+
+  if (opts.check) {
+    render.blank();
+    render.warn(`Update available: ${VERSION} → ${latest}`);
+    render.hint("Run: claudemesh upgrade");
+    return EXIT.SUCCESS;
+  }
+
+  const { npm, prefix } = findNpm();
+  const args = ["install", "-g"];
+  if (prefix) args.push("--prefix", prefix);
+  args.push("claudemesh-cli@alpha");
+
+  render.blank();
+  render.info(`Updating ${VERSION} → ${latest}…`);
+  render.hint(`${npm} ${args.join(" ")}`);
+  render.blank();
+
+  const res = spawnSync(npm, args, { stdio: "inherit" });
+  if (res.status !== 0) {
+    render.err(`npm exited with status ${res.status}`);
+    render.hint("Try: npm i -g claudemesh-cli@alpha");
+    return EXIT.INTERNAL_ERROR;
+  }
+
+  render.blank();
+  render.ok(`Upgraded to ${latest}.`);
+  return EXIT.SUCCESS;
+}
--- a/apps/cli-v2/src/commands/url-handler.ts
+++ b/apps/cli-v2/src/commands/url-handler.ts
@@ -0,0 +1,178 @@
+/**
+ * `claudemesh url-handler <install|uninstall>` — register a `claudemesh://`
+ * URL scheme handler with the OS so click-to-launch from email/web works.
+ *
+ * Scheme: `claudemesh://join/<code-or-token>` or `claudemesh://i/<code>`.
+ * When activated, the OS opens the handler, which runs
+ *   claudemesh https://claudemesh.com/i/<code>
+ * (inline join + launch path via the bare-URL dispatch in cli.ts).
+ *
+ * Platforms:
+ *   - darwin  → LSRegisterURL via a per-user .app bundle in
+ *               ~/Library/Application\ Support/claudemesh/ClaudemeshHandler.app
+ *   - linux   → xdg-mime default + a .desktop file in
+ *               ~/.local/share/applications/claudemesh.desktop
+ *   - win32   → HKCU\Software\Classes\claudemesh (registry write)
+ */
+
+import { platform, homedir } from "node:os";
+import { existsSync, mkdirSync, writeFileSync, rmSync, chmodSync } from "node:fs";
+import { join } from "node:path";
+import { spawnSync } from "node:child_process";
+import { EXIT } from "~/constants/exit-codes.js";
+
+function resolveClaudemeshBin(): string {
+  // argv[1] points to the running binary; prefer that over $PATH so we
+  // register the exact install the user ran.
+  return process.argv[1] ?? "claudemesh";
+}
+
+function installDarwin(): number {
+  const binPath = resolveClaudemeshBin();
+  const appDir = join(homedir(), "Library", "Application Support", "claudemesh", "ClaudemeshHandler.app");
+  const contents = join(appDir, "Contents");
+  const macOS = join(contents, "MacOS");
+  mkdirSync(macOS, { recursive: true });
+
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>CFBundleIdentifier</key><string>com.claudemesh.handler</string>
+  <key>CFBundleName</key><string>Claudemesh</string>
+  <key>CFBundleExecutable</key><string>open-url</string>
+  <key>CFBundleInfoDictionaryVersion</key><string>6.0</string>
+  <key>CFBundlePackageType</key><string>APPL</string>
+  <key>CFBundleSignature</key><string>????</string>
+  <key>CFBundleShortVersionString</key><string>1.0</string>
+  <key>LSUIElement</key><true/>
+  <key>CFBundleURLTypes</key>
+  <array>
+    <dict>
+      <key>CFBundleURLName</key><string>Claudemesh Invite</string>
+      <key>CFBundleURLSchemes</key>
+      <array><string>claudemesh</string></array>
+    </dict>
+  </array>
+</dict>
+</plist>`;
+  writeFileSync(join(contents, "Info.plist"), plist);
+
+  // Tiny shell shim: parse the URL and re-invoke the CLI in a Terminal
+  // window so the user sees launch output.
+  const shim = `#!/bin/sh
+URL="$1"
+CODE=\${URL#claudemesh://}
+CODE=\${CODE#i/}
+CODE=\${CODE#join/}
+# Open a Terminal window so the user can see claude launching
+osascript <<EOF
+tell application "Terminal"
+  activate
+  do script "${binPath.replace(/"/g, '\\"')} https://claudemesh.com/i/$CODE"
+end tell
+EOF
+`;
+  const shimPath = join(macOS, "open-url");
+  writeFileSync(shimPath, shim);
+  chmodSync(shimPath, 0o755);
+
+  // Re-register with Launch Services so the scheme resolves here.
+  const lsreg = spawnSync("/System/Library/Frameworks/CoreServices.framework/Frameworks/LaunchServices.framework/Support/lsregister", ["-f", appDir], { encoding: "utf-8" });
+  if (lsreg.status !== 0) {
+    console.log("  ⚠ lsregister returned non-zero; scheme may not activate until Finder rescans.");
+  }
+  console.log(`  ✓ Registered claudemesh:// scheme on macOS`);
+  console.log(`    app bundle: ${appDir}`);
+  return EXIT.SUCCESS;
+}
+
+function installLinux(): number {
+  const binPath = resolveClaudemeshBin();
+  const appsDir = join(homedir(), ".local", "share", "applications");
+  mkdirSync(appsDir, { recursive: true });
+  const desktop = `[Desktop Entry]
+Type=Application
+Name=Claudemesh
+Comment=Claudemesh invite handler
+Exec=${binPath} %u
+StartupNotify=false
+Terminal=true
+MimeType=x-scheme-handler/claudemesh;
+NoDisplay=true
+`;
+  const desktopPath = join(appsDir, "claudemesh.desktop");
+  writeFileSync(desktopPath, desktop);
+
+  const xdg1 = spawnSync("xdg-mime", ["default", "claudemesh.desktop", "x-scheme-handler/claudemesh"], { encoding: "utf-8" });
+  if (xdg1.status !== 0) {
+    console.log("  ⚠ xdg-mime not available — skipped mime default registration");
+  }
+  const xdg2 = spawnSync("update-desktop-database", [appsDir], { encoding: "utf-8" });
+  xdg2.status ?? 0; // best effort
+  console.log(`  ✓ Registered claudemesh:// scheme on Linux`);
+  console.log(`    desktop entry: ${desktopPath}`);
+  return EXIT.SUCCESS;
+}
+
+function installWindows(): number {
+  const binPath = resolveClaudemeshBin().replace(/\//g, "\\");
+  const lines = [
+    `Windows Registry Editor Version 5.00`,
+    ``,
+    `[HKEY_CURRENT_USER\\Software\\Classes\\claudemesh]`,
+    `@="URL:Claudemesh Invite"`,
+    `"URL Protocol"=""`,
+    ``,
+    `[HKEY_CURRENT_USER\\Software\\Classes\\claudemesh\\shell\\open\\command]`,
+    `@="\\"${binPath.replace(/\\/g, "\\\\")}\\" \\"%1\\""`,
+  ];
+  const regPath = join(homedir(), "claudemesh-handler.reg");
+  writeFileSync(regPath, lines.join("\r\n"));
+  const res = spawnSync("reg.exe", ["import", regPath], { encoding: "utf-8" });
+  if (res.status !== 0) {
+    console.log(`  ⚠ reg.exe import failed. Manual: double-click ${regPath}`);
+    return EXIT.INTERNAL_ERROR;
+  }
+  console.log(`  ✓ Registered claudemesh:// scheme on Windows`);
+  return EXIT.SUCCESS;
+}
+
+function uninstallDarwin(): number {
+  const appDir = join(homedir(), "Library", "Application Support", "claudemesh", "ClaudemeshHandler.app");
+  if (existsSync(appDir)) rmSync(appDir, { recursive: true, force: true });
+  console.log("  ✓ Removed claudemesh:// handler on macOS");
+  return EXIT.SUCCESS;
+}
+
+function uninstallLinux(): number {
+  const desktopPath = join(homedir(), ".local", "share", "applications", "claudemesh.desktop");
+  if (existsSync(desktopPath)) rmSync(desktopPath, { force: true });
+  console.log("  ✓ Removed claudemesh:// handler on Linux");
+  return EXIT.SUCCESS;
+}
+
+function uninstallWindows(): number {
+  spawnSync("reg.exe", ["delete", "HKCU\\Software\\Classes\\claudemesh", "/f"], { encoding: "utf-8" });
+  console.log("  ✓ Removed claudemesh:// handler on Windows");
+  return EXIT.SUCCESS;
+}
+
+export async function runUrlHandler(action: string | undefined): Promise<number> {
+  const act = action ?? "install";
+  const p = platform();
+  if (act === "install") {
+    if (p === "darwin") return installDarwin();
+    if (p === "linux") return installLinux();
+    if (p === "win32") return installWindows();
+  } else if (act === "uninstall" || act === "remove") {
+    if (p === "darwin") return uninstallDarwin();
+    if (p === "linux") return uninstallLinux();
+    if (p === "win32") return uninstallWindows();
+  } else {
+    console.error("Usage: claudemesh url-handler <install|uninstall>");
+    return EXIT.INVALID_ARGS;
+  }
+  console.error(`Unsupported platform: ${p}`);
+  return EXIT.INTERNAL_ERROR;
+}
--- a/apps/cli-v2/src/commands/verify.ts
+++ b/apps/cli-v2/src/commands/verify.ts
@@ -0,0 +1,95 @@
+/**
+ * `claudemesh verify [peer]` — show safety numbers for a peer.
+ *
+ * A safety number is a derived, human-readable fingerprint of the peer's
+ * ed25519 public key plus your own. Both parties see the same digits,
+ * so out-of-band comparison (call, in-person) detects MITM.
+ *
+ * Format: 6 groups of 5 decimal digits. Rendered from the first 15 bytes
+ * of SHA-256(sorted(your_pubkey ++ peer_pubkey)). Matches the Signal /
+ * Whatsapp pattern so users don't have to learn a new mental model.
+ */
+
+import { withMesh } from "./connect.js";
+import { readConfig } from "~/services/config/facade.js";
+import { EXIT } from "~/constants/exit-codes.js";
+import { createHash } from "node:crypto";
+
+function safetyNumber(myPubkey: string, peerPubkey: string): string {
+  const a = Buffer.from(myPubkey, "hex");
+  const b = Buffer.from(peerPubkey, "hex");
+  const [lo, hi] = Buffer.compare(a, b) < 0 ? [a, b] : [b, a];
+  const hash = createHash("sha256").update(lo).update(hi).digest();
+  // Take first 15 bytes, split into 6 groups of 20 bits → 5 decimal digits each.
+  const bits: number[] = [];
+  for (let i = 0; i < 15; i++) {
+    for (let b = 7; b >= 0; b--) {
+      bits.push((hash[i]! >> b) & 1);
+    }
+  }
+  const groups: string[] = [];
+  for (let g = 0; g < 6; g++) {
+    let val = 0;
+    for (let i = 0; i < 20; i++) val = val * 2 + bits[g * 20 + i]!;
+    groups.push(String(val % 100000).padStart(5, "0"));
+  }
+  return groups.join(" ");
+}
+
+export async function runVerify(
+  target: string | undefined,
+  opts: { mesh?: string; json?: boolean } = {},
+): Promise<number> {
+  const useColor = !process.env.NO_COLOR && process.env.TERM !== "dumb" && process.stdout.isTTY;
+  const bold = (s: string) => (useColor ? `\x1b[1m${s}\x1b[22m` : s);
+  const dim = (s: string) => (useColor ? `\x1b[2m${s}\x1b[22m` : s);
+  const clay = (s: string) => (useColor ? `\x1b[38;2;217;119;87m${s}\x1b[39m` : s);
+
+  const config = readConfig();
+  const meshSlug = opts.mesh ?? config.meshes[0]?.slug;
+  if (!meshSlug) {
+    console.error("  No meshes joined. Run `claudemesh join <url>` first.");
+    return EXIT.NOT_FOUND;
+  }
+  const mesh = config.meshes.find((m) => m.slug === meshSlug);
+  if (!mesh) {
+    console.error(`  Mesh "${meshSlug}" not found locally.`);
+    return EXIT.NOT_FOUND;
+  }
+
+  return await withMesh({ meshSlug }, async (client) => {
+    const peers = await client.listPeers();
+    const targets = target
+      ? peers.filter((p) => p.displayName === target || p.pubkey === target || p.pubkey.startsWith(target))
+      : peers;
+    if (targets.length === 0) {
+      console.error(`  No peer matching "${target ?? "(all)"}" on mesh ${meshSlug}.`);
+      return EXIT.NOT_FOUND;
+    }
+
+    if (opts.json) {
+      console.log(JSON.stringify(targets.map((p) => ({
+        mesh: meshSlug,
+        peer: p.displayName,
+        pubkey: p.pubkey,
+        safetyNumber: safetyNumber(mesh.pubkey, p.pubkey),
+      })), null, 2));
+      return EXIT.SUCCESS;
+    }
+
+    console.log("");
+    console.log(`  ${dim("— safety numbers on")} ${bold(meshSlug)}`);
+    console.log("");
+    for (const p of targets) {
+      const sn = safetyNumber(mesh.pubkey, p.pubkey);
+      console.log(`  ${bold(p.displayName)}`);
+      console.log(`  ${clay(sn)}`);
+      console.log(`  ${dim(`pubkey ${p.pubkey.slice(0, 16)}…`)}`);
+      console.log("");
+    }
+    console.log(dim("  Compare these digits with your peer (phone, in person, not chat)."));
+    console.log(dim("  If they match on both sides, the channel is not being intercepted."));
+    console.log("");
+    return EXIT.SUCCESS;
+  });
+}
--- a/apps/cli-v2/src/commands/welcome.ts
+++ b/apps/cli-v2/src/commands/welcome.ts
@@ -0,0 +1,72 @@
+/**
+ * `claudemesh` with no args + no joined meshes → unified onboarding.
+ *
+ * One flow, one keystroke per decision. Collapses the old three-branch
+ * picker (signup / login / join) into a linear path:
+ *
+ *   1. Already have an invite URL? → paste it, run the bare-URL join+launch.
+ *      (no account needed — invites are self-signed capabilities)
+ *   2. Else: open the browser for sign-in + mesh creation at claudemesh.com
+ *      and fall back to paste-sync when the browser hand-off lands.
+ *
+ * The branch that used to be "register" collapses into the browser flow
+ * (the web handles signup + mesh creation as one wizard there).
+ */
+
+import { createInterface } from "node:readline";
+import { readConfig } from "~/services/config/facade.js";
+import { renderWelcome } from "~/ui/welcome/index.js";
+import { login } from "./login.js";
+import { render } from "~/ui/render.js";
+import { isInviteUrl, normaliseInviteUrl } from "~/utils/url.js";
+import { EXIT } from "~/constants/exit-codes.js";
+
+function prompt(q: string): Promise<string> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  return new Promise((resolve) => {
+    rl.question(q, (a) => { rl.close(); resolve(a.trim()); });
+  });
+}
+
+export async function runWelcome(): Promise<number> {
+  const config = readConfig();
+  if (config.meshes.length > 0) return EXIT.SUCCESS;
+
+  renderWelcome();
+
+  render.info("Do you already have an invite link? (y/n) [n]");
+  const hasInvite = (await prompt("  > ")).toLowerCase().startsWith("y");
+
+  if (hasInvite) {
+    render.blank();
+    render.info("Paste your invite link (claudemesh.com/i/... or claudemesh://...)");
+    const raw = await prompt("  > ");
+    if (!raw || !isInviteUrl(raw)) {
+      render.err("That doesn't look like a claudemesh invite URL.");
+      render.hint("Check your email — the link starts with https://claudemesh.com/i/");
+      return EXIT.INVALID_ARGS;
+    }
+    const normalised = normaliseInviteUrl(raw);
+    render.blank();
+    render.ok(`Joining via ${normalised}`);
+    const { runLaunch } = await import("./launch.js");
+    await runLaunch(
+      {
+        join: normalised,
+        name: process.env.USER ?? process.env.USERNAME ?? undefined,
+        yes: false,
+      },
+      [],
+    );
+    return EXIT.SUCCESS;
+  }
+
+  // No invite → browser-first sign-in + mesh creation.
+  render.blank();
+  render.info("Opening claudemesh.com so you can sign in and create your first mesh.");
+  render.hint("After sign-in, paste the sync token back here when prompted.");
+  render.blank();
+  return await login();
+}
+
+export { runWelcome as _stub };
--- a/apps/cli-v2/src/commands/whoami.ts
+++ b/apps/cli-v2/src/commands/whoami.ts
@@ -0,0 +1,26 @@
+import { whoAmI } from "~/services/auth/facade.js";
+import { dim, icons } from "~/ui/styles.js";
+import { EXIT } from "~/constants/exit-codes.js";
+
+export async function whoami(opts: { json?: boolean }): Promise<number> {
+  const result = await whoAmI();
+
+  if (opts.json) {
+    console.log(JSON.stringify({ schema_version: "1.0", ...result }, null, 2));
+    return EXIT.SUCCESS;
+  }
+
+  if (!result.signed_in) {
+    console.log(`  Not signed in. Run \`claudemesh login\` to sign in.`);
+    return EXIT.AUTH_FAILED;
+  }
+
+  console.log(`\n  Signed in as ${result.user!.display_name} (${result.user!.email})`);
+  console.log(`  Token source: ${result.token_source} ${dim("(~/.claudemesh/auth.json)")}`);
+  if (result.meshes) {
+    console.log(`  Meshes: ${result.meshes.owned} owned, ${result.meshes.guest} guest`);
+  }
+  console.log();
+
+  return EXIT.SUCCESS;
+}
--- a/apps/cli-v2/src/constants/exit-codes.ts
+++ b/apps/cli-v2/src/constants/exit-codes.ts
@@ -0,0 +1,14 @@
+export const EXIT = {
+  SUCCESS: 0,
+  USER_CANCELLED: 1,
+  AUTH_FAILED: 2,
+  INVALID_ARGS: 3,
+  NETWORK_ERROR: 4,
+  NOT_FOUND: 5,
+  ALREADY_EXISTS: 6,
+  PERMISSION_DENIED: 7,
+  INTERNAL_ERROR: 8,
+  CLAUDE_MISSING: 9,
+} as const;
+
+export type ExitCode = (typeof EXIT)[keyof typeof EXIT];
--- a/apps/cli-v2/src/constants/index.ts
+++ b/apps/cli-v2/src/constants/index.ts
@@ -0,0 +1,5 @@
+export { EXIT } from "./exit-codes.js";
+export type { ExitCode } from "./exit-codes.js";
+export { PATHS } from "./paths.js";
+export { URLS } from "./urls.js";
+export { TIMINGS } from "./timings.js";
--- a/apps/cli-v2/src/constants/paths.ts
+++ b/apps/cli-v2/src/constants/paths.ts
@@ -0,0 +1,22 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+const home = homedir();
+
+export const PATHS = {
+  CONFIG_DIR: process.env.CLAUDEMESH_CONFIG_DIR || join(home, ".claudemesh"),
+  get CONFIG_FILE() {
+    return join(this.CONFIG_DIR, "config.json");
+  },
+  get AUTH_FILE() {
+    return join(this.CONFIG_DIR, "auth.json");
+  },
+  get KEYS_DIR() {
+    return join(this.CONFIG_DIR, "keys");
+  },
+  get LAST_USED_FILE() {
+    return join(this.CONFIG_DIR, "last-used.json");
+  },
+  CLAUDE_JSON: join(home, ".claude.json"),
+  CLAUDE_SETTINGS: join(home, ".claude", "settings.json"),
+} as const;
--- a/apps/cli-v2/src/constants/timings.ts
+++ b/apps/cli-v2/src/constants/timings.ts
@@ -0,0 +1,11 @@
+export const TIMINGS = {
+  DEVICE_CODE_POLL_MS: 1500,
+  DEVICE_CODE_TIMEOUT_MS: 5 * 60 * 1000,
+  WS_RECONNECT_BASE_MS: 1000,
+  WS_RECONNECT_MAX_MS: 30_000,
+  UPDATE_CHECK_INTERVAL_MS: 24 * 60 * 60 * 1000,
+  TELEGRAM_CONNECT_TIMEOUT_MS: 5 * 60 * 1000,
+  TELEGRAM_POLL_INTERVAL_MS: 2000,
+  API_TIMEOUT_MS: 15_000,
+  API_RETRY_COUNT: 2,
+} as const;
--- a/apps/cli-v2/src/constants/urls.ts
+++ b/apps/cli-v2/src/constants/urls.ts
@@ -0,0 +1,14 @@
+export const URLS = {
+  BROKER: process.env.CLAUDEMESH_BROKER_URL ?? "wss://ic.claudemesh.com/ws",
+  API_BASE: process.env.CLAUDEMESH_API_URL ?? "https://claudemesh.com",
+  DASHBOARD: "https://claudemesh.com/dashboard",
+  NPM_REGISTRY: "https://registry.npmjs.org/claudemesh-cli",
+} as const;
+
+export const VERSION = "1.0.0-alpha.27";
+
+export const env = {
+  CLAUDEMESH_BROKER_URL: URLS.BROKER,
+  CLAUDEMESH_CONFIG_DIR: process.env.CLAUDEMESH_CONFIG_DIR || undefined,
+  CLAUDEMESH_DEBUG: process.env.CLAUDEMESH_DEBUG === "1" || process.env.CLAUDEMESH_DEBUG === "true",
+};
--- a/apps/cli-v2/src/entrypoints/cli.ts
+++ b/apps/cli-v2/src/entrypoints/cli.ts
@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+import { parseArgv } from "~/cli/argv.js";
+import { installSignalHandlers } from "~/cli/handlers/signal.js";
+import { installErrorHandlers } from "~/cli/handlers/error.js";
+import { showUpdateNotice } from "~/cli/update-notice.js";
+import { VERSION } from "~/constants/urls.js";
+import { EXIT } from "~/constants/exit-codes.js";
+import { renderVersion } from "~/cli/output/version.js";
+import { isInviteUrl, normaliseInviteUrl } from "~/utils/url.js";
+
+installSignalHandlers();
+installErrorHandlers();
+
+const { command, positionals, flags } = parseArgv(process.argv);
+
+const HELP = `
+claudemesh — peer mesh for Claude Code sessions
+${VERSION}
+
+USAGE
+  claudemesh                                  auto-connect to your mesh
+  claudemesh <invite-url>                     join a mesh, then launch
+  claudemesh launch --name <n> --join <url>   join + launch in one step
+
+Mesh
+  claudemesh create <name>         create a new mesh
+  claudemesh join <url>            join a mesh (accepts short /i/ or long /join/ link)
+  claudemesh launch [slug]         launch Claude Code on a mesh (alias: connect)
+  claudemesh list                  show your meshes (alias: ls)
+  claudemesh delete [slug]         delete a mesh (alias: rm)
+  claudemesh rename <slug> <name>  rename a mesh
+  claudemesh share [email]         share mesh (invite link / send email)
+
+Messaging
+  claudemesh peers                 see who's online
+  claudemesh send <to> <msg>       send a message
+  claudemesh inbox                 drain pending messages
+  claudemesh state get|set|list    shared state
+  claudemesh remember <text>       store a memory
+  claudemesh recall <query>        search memories
+  claudemesh remind ...            schedule a reminder
+  claudemesh profile               view or edit your profile
+  claudemesh info                  mesh overview
+
+Auth
+  claudemesh login                 sign in (browser or paste token)
+  claudemesh register              create account + sign in
+  claudemesh logout                sign out
+  claudemesh whoami                show current identity
+
+Security
+  claudemesh verify [peer]         show ed25519 safety numbers (SAS)
+  claudemesh grant <peer> <cap>    grant capability (dm, broadcast, state-read, all)
+  claudemesh revoke <peer> <cap>   revoke capability (or 'all')
+  claudemesh block <peer>          revoke all capabilities (silent drop)
+  claudemesh grants                list per-peer overrides for current mesh
+  claudemesh backup [file]         encrypt config → portable recovery file
+  claudemesh restore <file>        restore config from a backup file
+
+Setup
+  claudemesh install               register MCP server + hooks
+  claudemesh uninstall             remove MCP server + hooks
+  claudemesh doctor                diagnose issues (broker, node, claude)
+  claudemesh status                check broker connectivity
+  claudemesh sync                  refresh mesh list from dashboard
+  claudemesh completions <shell>   emit bash / zsh / fish completion script
+  claudemesh url-handler install   register claudemesh:// click-to-launch
+  claudemesh upgrade               self-update to latest alpha (rustup-style)
+
+Flags
+  --version, -V                    show version
+  --help, -h                       show this help
+  --json                           machine-readable output
+  --mesh <slug>                    override mesh selection
+  -y, --yes                        skip confirmations
+  -q, --quiet                      suppress non-essential output
+`;
+
+async function main(): Promise<void> {
+  if (flags.help || flags.h) { console.log(HELP); process.exit(EXIT.SUCCESS); }
+  if (flags.version || flags.V) { console.log(renderVersion()); process.exit(EXIT.SUCCESS); }
+
+  // Bare command or invite URL
+  if (!command || isInviteUrl(command)) {
+    // `claudemesh <invite-url>` → join + launch in one step.
+    // `-y` skips all interactive prompts (role=member, no groups, push mode).
+    if (command && isInviteUrl(command)) {
+      const { runLaunch } = await import("~/commands/launch.js");
+      await runLaunch({
+        mesh: flags.mesh as string | undefined,
+        name: flags.name as string | undefined,
+        join: normaliseInviteUrl(command),
+        yes: !!flags.y || !!flags.yes,
+        resume: flags.resume as string | undefined,
+      }, process.argv.slice(2));
+      return;
+    }
+    const { readConfig } = await import("~/services/config/facade.js");
+    const config = readConfig();
+    if (config.meshes.length === 0) {
+      const { runWelcome } = await import("~/commands/welcome.js");
+      process.exit(await runWelcome());
+    }
+    const { runLaunch } = await import("~/commands/launch.js");
+    await runLaunch({
+      mesh: flags.mesh as string | undefined,
+      name: flags.name as string | undefined,
+      yes: !!flags.y || !!flags.yes,
+      resume: flags.resume as string | undefined,
+    }, process.argv.slice(2));
+    return;
+  }
+
+  switch (command) {
+    case "help": { console.log(HELP); break; }
+
+    // Mesh management
+    case "create": case "new": { const { newMesh } = await import("~/commands/new.js"); process.exit(await newMesh(positionals[0] ?? "", { json: !!flags.json })); break; }
+    case "add": case "join": { const { runJoin } = await import("~/commands/join.js"); await runJoin(positionals); break; }
+    case "connect": case "launch": {
+      const { runLaunch } = await import("~/commands/launch.js");
+      await runLaunch({
+        mesh: positionals[0] ?? flags.mesh as string,
+        name: flags.name as string,
+        join: flags.join as string,
+        yes: !!flags.y || !!flags.yes,
+        resume: flags.resume as string,
+      }, process.argv.slice(2));
+      break;
+    }
+    case "disconnect": { console.log("  Connection closed."); process.exit(EXIT.SUCCESS); break; }
+    case "list": case "ls": { const { runList } = await import("~/commands/list.js"); await runList(); break; }
+    case "delete": case "rm": { const { deleteMesh } = await import("~/commands/delete-mesh.js"); process.exit(await deleteMesh(positionals[0] ?? "", { yes: !!flags.y || !!flags.yes })); break; }
+    case "rename": { const { rename } = await import("~/commands/rename.js"); process.exit(await rename(positionals[0] ?? "", positionals[1] ?? "")); break; }
+    case "share": case "invite": { const { invite } = await import("~/commands/invite.js"); process.exit(await invite(positionals[0], { mesh: flags.mesh as string, json: !!flags.json })); break; }
+
+    // Messaging
+    case "peers": { const { runPeers } = await import("~/commands/peers.js"); await runPeers({ mesh: flags.mesh as string, json: !!flags.json }); break; }
+    case "send": { const { runSend } = await import("~/commands/send.js"); await runSend({}, positionals[0] ?? "", positionals.slice(1).join(" ")); break; }
+    case "inbox": { const { runInbox } = await import("~/commands/inbox.js"); await runInbox({ json: !!flags.json }); break; }
+    case "state": {
+      const sub = positionals[0];
+      if (sub === "set") { const { runStateSet } = await import("~/commands/state.js"); await runStateSet({}, positionals[1] ?? "", positionals[2] ?? ""); }
+      else if (sub === "list") { const { runStateList } = await import("~/commands/state.js"); await runStateList({}); }
+      else { const { runStateGet } = await import("~/commands/state.js"); await runStateGet({}, positionals[0] ?? ""); }
+      break;
+    }
+    case "info": { const { runInfo } = await import("~/commands/info.js"); await runInfo({}); break; }
+    case "remember": { const { remember } = await import("~/commands/remember.js"); process.exit(await remember(positionals.join(" "), { tags: flags.tags as string, json: !!flags.json })); break; }
+    case "recall": { const { recall } = await import("~/commands/recall.js"); process.exit(await recall(positionals.join(" "), { json: !!flags.json })); break; }
+    case "remind": { const { runRemind } = await import("~/commands/remind.js"); await runRemind({ mesh: flags.mesh as string }, positionals); break; }
+    case "profile": { const { runProfile } = await import("~/commands/profile.js"); await runProfile(flags as any); break; }
+
+    // Auth
+    case "login": { const { login } = await import("~/commands/login.js"); process.exit(await login()); break; }
+    case "register": { const { register } = await import("~/commands/register.js"); process.exit(await register()); break; }
+    case "logout": { const { logout } = await import("~/commands/logout.js"); process.exit(await logout()); break; }
+    case "whoami": { const { whoami } = await import("~/commands/whoami.js"); process.exit(await whoami({ json: !!flags.json })); break; }
+
+    // Setup
+    case "install": { const { runInstall } = await import("~/commands/install.js"); runInstall(positionals); break; }
+    case "uninstall": { const { uninstall } = await import("~/commands/uninstall.js"); process.exit(await uninstall()); break; }
+    case "doctor": { const { runDoctor } = await import("~/commands/doctor.js"); await runDoctor(); break; }
+    case "status": { const { runStatus } = await import("~/commands/status.js"); await runStatus(); break; }
+    case "sync": { const { runSync } = await import("~/commands/sync.js"); await runSync({ force: !!flags.force }); break; }
+
+    // Test
+    case "test": { const { runTest } = await import("~/commands/test.js"); process.exit(await runTest()); break; }
+
+    // CLI utilities
+    case "completions": { const { runCompletions } = await import("~/commands/completions.js"); process.exit(await runCompletions(positionals[0])); break; }
+    case "verify": { const { runVerify } = await import("~/commands/verify.js"); process.exit(await runVerify(positionals[0], { mesh: flags.mesh as string | undefined, json: !!flags.json })); break; }
+    case "url-handler": { const { runUrlHandler } = await import("~/commands/url-handler.js"); process.exit(await runUrlHandler(positionals[0])); break; }
+    case "status-line": { const { runStatusLine } = await import("~/commands/status-line.js"); process.exit(await runStatusLine()); break; }
+    case "backup": { const { runBackup } = await import("~/commands/backup.js"); process.exit(await runBackup(positionals[0])); break; }
+    case "restore": { const { runRestore } = await import("~/commands/backup.js"); process.exit(await runRestore(positionals[0])); break; }
+    case "upgrade": case "update": { const { runUpgrade } = await import("~/commands/upgrade.js"); process.exit(await runUpgrade({ check: !!flags.check, yes: !!flags.y || !!flags.yes })); break; }
+    case "grant": { const { runGrant } = await import("~/commands/grants.js"); process.exit(await runGrant(positionals[0], positionals.slice(1), { mesh: flags.mesh as string | undefined })); break; }
+    case "revoke": { const { runRevoke } = await import("~/commands/grants.js"); process.exit(await runRevoke(positionals[0], positionals.slice(1), { mesh: flags.mesh as string | undefined })); break; }
+    case "block": { const { runBlock } = await import("~/commands/grants.js"); process.exit(await runBlock(positionals[0], { mesh: flags.mesh as string | undefined })); break; }
+    case "grants": { const { runGrants } = await import("~/commands/grants.js"); process.exit(await runGrants({ mesh: flags.mesh as string | undefined, json: !!flags.json })); break; }
+
+    // Internal
+    case "mcp": { const { runMcp } = await import("~/commands/mcp.js"); await runMcp(); break; }
+    case "hook": { const { runHook } = await import("~/commands/hook.js"); await runHook(positionals); break; }
+    case "seed-test-mesh": { const { runSeedTestMesh } = await import("~/commands/seed-test-mesh.js"); runSeedTestMesh(positionals); break; }
+
+    default: {
+      console.error(`  Unknown command: ${command}. Run \`claudemesh --help\` for usage.`);
+      process.exit(EXIT.INVALID_ARGS);
+    }
+  }
+
+  showUpdateNotice(VERSION).catch(() => {});
+}
+
+main().catch((err) => {
+  console.error("Fatal: " + (err instanceof Error ? err.message : String(err)));
+  process.exit(EXIT.INTERNAL_ERROR);
+});
--- a/apps/cli-v2/src/entrypoints/mcp.ts
+++ b/apps/cli-v2/src/entrypoints/mcp.ts
@@ -0,0 +1,6 @@
+import { startMcpServer } from "~/mcp/server.js";
+
+startMcpServer().catch((err) => {
+  process.stderr.write(`MCP server error: ${err instanceof Error ? err.message : err}\n`);
+  process.exit(1);
+});
--- a/apps/cli-v2/src/locales/en.ts
+++ b/apps/cli-v2/src/locales/en.ts
@@ -0,0 +1,10 @@
+export const en = {
+  welcome: "Welcome to claudemesh",
+  signed_in_as: "Signed in as {name}",
+  mesh_created: 'Created "{slug}"',
+  invite_copied: "Invite URL copied to clipboard",
+  logout_success: "Signed out",
+  error_network: "Could not reach {url}. Check your connection.",
+  error_auth: "Authentication failed. Run \`claudemesh login\` to sign in.",
+  error_not_found: "{resource} not found",
+} as const;
--- a/Show More
+++ b/Show More