claudemesh/.artifacts/specs/2026-04-11-cli-v2-pass1.md

claudemesh-cli v2 — Pass 1

Status: spec (active implementation target) Created: 2026-04-11 Scope: immediate v2 work — refactor + CLI user flows + v1 preservation Ships as: claudemesh-cli@1.0.0

Companion documents (read these first):

• 2026-04-11-v1-feature-inventory.md — every v1 feature that must keep working
• 2026-04-11-v2-parity-test-plan.md — how we verify v2 preserves v1
• 2026-04-10-cli-v2-pass2-facade-pattern.md — architectural rules (authoritative for both passes)

Pass 2 references (future work, not implementation targets):

• 2026-04-10-cli-v2-pass2-final-vision.md — longer-term architecture vision
• 2026-04-10-cli-v2-pass2-ux-design.md — interactive UX redesign
• 2026-04-10-cli-v2-pass2-local-first-storage.md — local SQLite + Lamport + sync daemon
• 2026-04-10-cli-v2-pass2-shared-infrastructure.md — broker hardening

---

1. Scope

1.1 What Pass 1 delivers

Three things, exactly:

1. Folder structure refactor. apps/cli/src/ becomes apps/cli-v2/src/ with a cleaner layout: entrypoints/, cli/, commands/, services/ (feature-folders with facades), ui/, mcp/, constants/, types/, utils/, locales/, templates/. ESLint + dependency-cruiser enforce the facade pattern. The scaffold replaces v1's ad-hoc organization.
2. CLI user flows that remove the dependency on the web dashboard for common operations:
   • claudemesh login — device-code OAuth against claudemesh.com
   • claudemesh register — account creation flow (browser handoff for email verification)
   • claudemesh logout — revoke session
   • claudemesh whoami — identity check
   • claudemesh new — create a mesh from the CLI (was dashboard-only in v1)
   • claudemesh invite — generate an invite from the CLI (was dashboard-only in v1)
3. Every v1 feature preserved — the 79 MCP tools, the 85 broker WS message types, the welcome wizard, the launch flow, the status hooks, the crypto primitives, the invite parsing, the doctor checks. See 2026-04-11-v1-feature-inventory.md for the complete list.

1.2 What Pass 1 does NOT deliver

Everything in the Pass 2 specs. Concretely:

• No local SQLite source of truth. v2 Pass 1 still hits the broker for every read/write (same as v1).
• No Lamport clock, no sync daemon, no outbox/inbox, no publish transaction, no NFC normalization, no write queue with state machine.
• No broker changes. The broker runs unchanged. Postgres, Neo4j, Qdrant, MinIO, Docker sandboxes — all stay on their v1 configurations.
• No hardened Postgres role isolation. v1's search_path-based scoping is preserved unchanged. Improving this is Pass 2.
• No MCP catalog tiering, no catalog audit process, no egress proxy for Docker sandboxes, no SSRF policy for URL watch. v1 behavior is preserved.
• No Telegram bridge changes. apps/broker/src/telegram-bridge.ts stays exactly as it is. The v2 CLI preserves claudemesh connect telegram as an interactive wizard (see §5.7) — this was a regression risk in an earlier draft of this spec. The v1 disconnect telegram subcommand is dropped because teardown is handled by the bridge itself (revoke inside Telegram) or by leaving the mesh.
• No new MCP catalog. Deployed MCPs still come from zip upload / git URL / npx package, same as v1. The bundled catalog (apps/broker/src/mcp-catalog.ts) is Pass 2 work.
• No ICU MessageFormat. v2 Pass 1 uses simple string templates. ICU plurals + per-locale length budgets are Pass 2.
• No session_kind enum with six output budgets. v2 Pass 1 keeps v1's imperative output patterns.
• No accessibility token-signal matrix. v2 Pass 1 keeps v1's TUI primitives. Pass 2 introduces the new design system.
• No new visual design system. v1's colors and icons stay. Pass 2 introduces the six-role palette.
• No trust surfaces / delight beats budget. Pass 2 concern.
• No new error structure with one-action recovery. v1's existing error messages stay.
• No 14 inviolable rules from the Pass 2 UX spec. Pass 2 concern.

If it's in a Pass 2 document, it is not part of Pass 1 unless this document explicitly says so.

1.3 The two compatibility contracts

Contract A — the broker's WS protocol. v2's CLI must speak the broker's v1 WS protocol byte-for-byte. Every one of the 85 WS message types in inventory §3 keeps the same envelope shape, the same field names, the same signature format. Production brokers deployed today must continue to serve v2 CLIs without any broker-side changes. This is the only compatibility contract that matters.

Contract B — v1 feature parity (user-facing behavior). Every item in the v1 inventory §12 "must preserve" list must keep working. This includes the 79 MCP tools, the 85 WS messages, the 18 HTTP endpoints, the backend integrations, the status engine, the scheduled message delivery, the URL watch, and the crypto round-trips. The v2 parity test suite is the verification.

What is NOT a compatibility contract:

• v1's CLI command names (launch, connect telegram, etc.) — v2 picks new names where better ones exist.
• v1's config file shape (~/.claudemesh/config.json) — v2 picks a new shape if needed.
• v1's JSON output shape (--json outputs) — v2 locks a new shape via schema_version: "1.0".
• v1's env var names — v2 picks new ones.
• v1's exit codes — v2 uses the cleaner scheme from Pass 2 §11.2.
• v1's stdout text — v2 rewrites for consistency and future localization.

No deprecation windows, no migration runners, no aliases. There are no users to migrate.

---

2. The three Pass 1 intents

These are the decisions v2 Pass 1 is optimizing for. Everything else is either out of scope or inherits from v1.

2.1 Intent A — scalability through folder structure

Problem: v1's apps/cli/src/ has 22 files, with business logic scattered across commands/, mcp/, ws/, auth/, crypto/, invite/, state/, tui/, and lib/. No enforced boundaries. commands/launch.ts is 775 lines. mcp/server.ts is 2,139 lines. ws/client.ts is 2,191 lines. Growing to v1.5 and beyond would compound the tangle.

Pass 1 fix: feature-folder services with facade pattern. Every service (auth, mesh, invite, broker, api, crypto, config, state, device, clipboard, spawn, telemetry, health, update, i18n, lifecycle, logger) lives in services/<name>/ with facade.ts as the single public entry point. ESLint boundaries plugin + dependency-cruiser enforce that ui/, commands/, cli/, and mcp/ import only from services/*/facade.ts.

The facade pattern is described in full in 2026-04-10-cli-v2-pass2-facade-pattern.md (which applies to both passes). Pass 1 implements it completely.

What this buys us:

• Growing a service is local — add files inside its folder, extend its facade
• Cross-service calls are explicit — facades import other facades, never internal files
• Testing is trivial — mock the facade
• Code review is bounded — PRs touch single service folders
• Scaling contributors is possible — ownership can split along service lines

2.2 Intent B — CLI user flows (remove dashboard dependency)

Problem: v1 users must open the claudemesh.com dashboard to:

• Create an account
• Log in to the dashboard (OAuth flow)
• Create a mesh
• Generate an invite link
• Manage their profile

Only after those web steps can they use the CLI to join (claudemesh join <url>). This means a terminal-first developer always has to context-switch to a browser for anything beyond joining.

Pass 1 fix: add CLI commands that drive all these flows end-to-end.

v2 Pass 1 command	Replaces
claudemesh register	Web dashboard signup page
claudemesh login	Web dashboard login + dashboard-to-CLI JWT sync
claudemesh logout	Web dashboard logout
claudemesh whoami	Web dashboard "who am I" profile view
claudemesh new <name>	Web dashboard "create mesh" form
claudemesh invite [email]	Web dashboard "generate invite" button

These are the only net-new CLI commands in Pass 1. Everything else inherits from v1.

The flows use device-code OAuth against claudemesh.com's existing Better Auth backend. No new backend work is required beyond confirming the device-code endpoint exists (it may or may not — the inventory §4 confirms POST /cli-sync exists, which is the existing dashboard-sync flow; v2 extends this to a full login/register flow).

2.3 Intent C — preserve every v1 feature

Problem: the scope creep risk. Every review round has added "while we're refactoring, let's also fix X."

Pass 1 fix: the v1 feature inventory is the regression contract. The parity test suite is the verification. A PR cannot merge if it breaks any item in inventory §12.

Pass 1 is a refactor, not a rewrite. v1's code gets moved into new files, its imports get updated to use facades, its business logic stays intact. Where v1's implementation is long or messy, v2 Pass 1 may split it into multiple files — but the observable behavior stays identical.

---

3. Target source tree

apps/cli-v2/
├── package.json                        # name: claudemesh-cli, version: 0.11.0-alpha.0 → 1.0.0
├── tsconfig.json
├── bunfig.toml
├── build.ts                            # Bun bundler driver, enforces 1.2 MB gzipped ceiling
├── .eslintrc.cjs                       # boundaries plugin + 3 custom rules
├── dependency-cruiser.config.js        # folder-level boundary enforcement
├── biome.json
├── CHANGELOG.md
├── README.md
├── bin/
│   └── claudemesh                      # shebang → dist/entrypoints/cli.js
│
├── src/
│   ├── entrypoints/
│   │   ├── cli.ts                      # interactive CLI entry — parses argv, dispatches
│   │   └── mcp.ts                      # `claudemesh mcp` → MCP stdio server
│   │
│   ├── cli/                            # non-Ink I/O plumbing
│   │   ├── argv.ts                     # parse process.argv, detect positional invite URLs
│   │   ├── print.ts                    # stdout helpers (respects NO_COLOR / FORCE_COLOR)
│   │   ├── structured-io.ts            # --json output with schema_version
│   │   ├── exit.ts                     # exit codes + cleanup hooks
│   │   ├── update-notice.ts            # "new version available" banner (npm registry poll)
│   │   ├── handlers/
│   │   │   ├── signal.ts               # SIGINT/SIGTERM graceful shutdown
│   │   │   └── error.ts                # top-level error → user message
│   │   └── output/                     # plain-text renderers for non-interactive commands
│   │       ├── list.ts
│   │       ├── peers.ts
│   │       ├── whoami.ts
│   │       └── version.ts
│   │
│   ├── commands/                       # one verb per file; no "advanced" prefix
│   │   ├── index.ts                    # command registry
│   │   ├── join.ts                     # join a mesh from invite URL (v1 + v2 formats)
│   │   ├── new.ts                      # NEW — create a mesh via API
│   │   ├── invite.ts                   # NEW — generate invite via API
│   │   ├── list.ts                     # list joined meshes
│   │   ├── rename.ts                   # rename current mesh
│   │   ├── leave.ts                    # leave a mesh
│   │   ├── peers.ts                    # list peers
│   │   ├── send.ts                     # send a message
│   │   ├── inbox.ts                    # drain inbox
│   │   ├── state.ts                    # get / set / list state
│   │   ├── info.ts                     # mesh overview
│   │   ├── remember.ts                 # store memory
│   │   ├── recall.ts                   # search memories
│   │   ├── remind.ts                   # schedule reminder
│   │   ├── profile.ts                  # view / edit profile
│   │   ├── status.ts                   # broker connectivity check
│   │   ├── doctor.ts                   # diagnostic checks (port from v1)
│   │   ├── register.ts                 # NEW — account creation
│   │   ├── login.ts                    # NEW — device-code OAuth
│   │   ├── logout.ts                   # NEW — revoke session
│   │   ├── whoami.ts                   # NEW — identity check
│   │   ├── install.ts                  # register MCP + hooks with Claude Code
│   │   ├── uninstall.ts                # remove MCP + hooks
│   │   ├── sync.ts                     # sync meshes from dashboard (existing /cli-sync)
│   │   ├── welcome.ts                  # welcome wizard (bare command, first-run only)
│   │   ├── hook.ts                     # internal Claude Code hook handler
│   │   ├── mcp.ts                      # internal `claudemesh mcp` dispatcher
│   │   └── seed-test-mesh.ts           # dev-only
│   │
│   ├── services/                       # feature-folders with facades
│   │   ├── auth/                       # NEW CLI user flows + existing JWT sync
│   │   │   ├── client.ts               # HTTP calls to /api/auth/cli/* endpoints
│   │   │   ├── device-code.ts          # device-code flow orchestration
│   │   │   ├── token-store.ts          # ~/.claudemesh/auth.json R/W with 0600
│   │   │   ├── dashboard-sync.ts       # existing /cli-sync flow (port from v1 auth/sync-with-broker.ts)
│   │   │   ├── callback-listener.ts    # local HTTP listener for OAuth callback (port from v1)
│   │   │   ├── open-browser.ts         # cross-platform browser launcher (port from v1)
│   │   │   ├── implementation.ts
│   │   │   ├── schemas.ts
│   │   │   ├── errors.ts
│   │   │   ├── index.ts                # getAuthService() factory
│   │   │   ├── facade.ts               # loginWithDeviceCode, logout, whoAmI, register
│   │   │   └── auth.test.ts
│   │   │
│   │   ├── mesh/                       # mesh CRUD + list + resolve-target
│   │   │   ├── client.ts               # HTTP to /api/my/meshes
│   │   │   ├── list.ts                 # port from v1 commands/list.ts logic
│   │   │   ├── create.ts               # NEW — POST /api/my/meshes
│   │   │   ├── rename.ts               # PATCH /api/my/meshes/:slug
│   │   │   ├── leave.ts                # port from v1 commands/leave.ts
│   │   │   ├── join.ts                 # port from v1 commands/join.ts
│   │   │   ├── resolve-target.ts       # port from v1 launch.ts mesh picker logic
│   │   │   ├── implementation.ts
│   │   │   ├── schemas.ts
│   │   │   ├── errors.ts
│   │   │   ├── index.ts
│   │   │   └── facade.ts
│   │   │
│   │   ├── invite/                     # invite generation + parsing + claiming
│   │   │   ├── generate.ts             # NEW — POST /api/my/meshes/:slug/invites
│   │   │   ├── parse-url.ts            # port from v1 invite/parse.ts + lib/invite-v2.ts
│   │   │   ├── claim.ts                # port from v1 invite/enroll.ts
│   │   │   ├── send-email.ts           # NEW — email delivery (if backend supports)
│   │   │   ├── implementation.ts
│   │   │   ├── schemas.ts
│   │   │   ├── errors.ts
│   │   │   ├── index.ts
│   │   │   └── facade.ts
│   │   │
│   │   ├── broker/                     # WS client + peer crypto (port from v1 ws/)
│   │   │   ├── ws-client.ts            # port from v1 ws/client.ts (2191 lines)
│   │   │   ├── manager.ts              # port from v1 ws/manager.ts
│   │   │   ├── envelope.ts             # port from v1 crypto/envelope.ts
│   │   │   ├── hello-sig.ts            # port from v1 crypto/hello-sig.ts
│   │   │   ├── implementation.ts
│   │   │   ├── schemas.ts              # WS message type definitions (all 85)
│   │   │   ├── errors.ts
│   │   │   ├── index.ts
│   │   │   ├── facade.ts               # typed methods for each WS op
│   │   │   └── broker.test.ts
│   │   │
│   │   ├── api/                        # base HTTP client
│   │   │   ├── client.ts               # typed fetch wrapper
│   │   │   ├── my.ts                   # /api/my/* endpoint helpers
│   │   │   ├── public.ts               # /api/public/* (invite claim)
│   │   │   ├── errors.ts
│   │   │   ├── index.ts
│   │   │   └── facade.ts
│   │   │
│   │   ├── crypto/                     # Ed25519, NaCl, AES-GCM
│   │   │   ├── keypair.ts              # port from v1 crypto/keypair.ts
│   │   │   ├── file-crypto.ts          # port from v1 crypto/file-crypto.ts
│   │   │   ├── box.ts                  # NaCl crypto_box wrappers
│   │   │   ├── random.ts               # secure random helpers
│   │   │   ├── index.ts
│   │   │   ├── facade.ts
│   │   │   └── crypto.test.ts
│   │   │
│   │   ├── config/                     # ~/.claudemesh/config.json
│   │   │   ├── read.ts                 # port from v1 state/config.ts
│   │   │   ├── write.ts
│   │   │   ├── schemas.ts
│   │   │   ├── index.ts
│   │   │   └── facade.ts
│   │   │
│   │   ├── state/                      # last-used cache (not mesh state — that's via broker)
│   │   │   ├── last-used.ts            # remember last mesh, name, role for faster launch
│   │   │   ├── schemas.ts
│   │   │   ├── index.ts
│   │   │   └── facade.ts
│   │   │
│   │   ├── device/                     # hostname, os, arch
│   │   │   ├── info.ts
│   │   │   ├── index.ts
│   │   │   └── facade.ts
│   │   │
│   │   ├── clipboard/                  # pbpaste / xclip / wl-paste (optional)
│   │   │   ├── read.ts
│   │   │   ├── index.ts
│   │   │   └── facade.ts
│   │   │
│   │   ├── spawn/                      # exec choke points
│   │   │   ├── claude.ts               # exec claude binary (port from v1 launch.ts)
│   │   │   ├── browser.ts              # open browser (port from v1 auth/open-browser.ts)
│   │   │   ├── index.ts
│   │   │   └── facade.ts
│   │   │
│   │   ├── telemetry/                  # opt-out usage events
│   │   │   ├── emit.ts
│   │   │   ├── opt-out.ts
│   │   │   ├── index.ts
│   │   │   └── facade.ts
│   │   │
│   │   ├── health/                     # doctor check implementations
│   │   │   ├── check-node-version.ts
│   │   │   ├── check-claude-binary.ts
│   │   │   ├── check-mcp-registered.ts
│   │   │   ├── check-hooks-registered.ts
│   │   │   ├── check-config-perms.ts
│   │   │   ├── check-keypairs-valid.ts
│   │   │   ├── index.ts
│   │   │   └── facade.ts               # runAllChecks, runCheck
│   │   │
│   │   ├── update/                     # npm registry version check
│   │   │   ├── check.ts
│   │   │   ├── index.ts
│   │   │   └── facade.ts
│   │   │
│   │   ├── i18n/                       # simple string templates (no ICU in Pass 1)
│   │   │   ├── resolve.ts              # locale detection
│   │   │   ├── format.ts               # {placeholder} substitution
│   │   │   ├── index.ts
│   │   │   └── facade.ts
│   │   │
│   │   ├── lifecycle/                  # start/stop long-running services
│   │   │   ├── service-manager.ts
│   │   │   ├── index.ts
│   │   │   └── facade.ts
│   │   │
│   │   └── logger/                     # structured logger
│   │       ├── logger.ts
│   │       ├── index.ts
│   │       └── facade.ts
│   │
│   ├── ui/                             # Ink-based TUI (port from v1 tui/)
│   │   ├── styles.ts                   # colors + icons (port from v1 tui/colors.ts — v1 values, not Pass 2 redesign)
│   │   ├── screen.ts                   # port from v1 tui/screen.ts
│   │   ├── spinner.ts                  # port from v1 tui/spinner.ts
│   │   ├── welcome/                    # welcome wizard screens (port from v1 commands/welcome.ts)
│   │   │   ├── WelcomeScreen.tsx
│   │   │   ├── RegisterStep.tsx        # NEW for Pass 1
│   │   │   ├── LoginStep.tsx           # NEW for Pass 1
│   │   │   ├── MeshPickerStep.tsx
│   │   │   └── index.ts
│   │   └── launch/                     # launch flow (port from v1 commands/launch.ts interactive bits)
│   │       ├── LaunchFlow.tsx
│   │       └── index.ts
│   │
│   ├── mcp/                            # stdio MCP server (port from v1 mcp/server.ts)
│   │   ├── server.ts                   # entry from entrypoints/mcp.ts
│   │   ├── router.ts                   # tool dispatch
│   │   ├── tools/                      # one file per tool family (79 tools total)
│   │   │   ├── memory.ts               # remember, recall, forget
│   │   │   ├── state.ts                # set_state, get_state, list_state
│   │   │   ├── messaging.ts            # send_message, list_peers, check_messages, message_status
│   │   │   ├── profile.ts              # set_profile, set_status, set_summary, set_visible
│   │   │   ├── groups.ts               # join_group, leave_group
│   │   │   ├── files.ts                # share_file, get_file, list_files, file_status, delete_file, grant_file_access, read_peer_file, list_peer_files
│   │   │   ├── vectors.ts              # vector_store, vector_search, vector_delete, list_collections
│   │   │   ├── graph.ts                # graph_query, graph_execute
│   │   │   ├── sql.ts                  # mesh_query, mesh_execute, mesh_schema
│   │   │   ├── streams.ts              # create_stream, publish, subscribe, list_streams
│   │   │   ├── contexts.ts             # share_context, get_context, list_contexts
│   │   │   ├── tasks.ts                # create_task, claim_task, complete_task, list_tasks
│   │   │   ├── scheduling.ts           # schedule_reminder, list_scheduled, cancel_scheduled
│   │   │   ├── mesh-meta.ts            # mesh_info, mesh_stats, mesh_clock, ping_mesh
│   │   │   ├── clock-write.ts          # mesh_set_clock, mesh_pause_clock, mesh_resume_clock
│   │   │   ├── skills.ts               # share_skill, get_skill, list_skills, remove_skill, mesh_skill_deploy
│   │   │   ├── mcp-registry-peer.ts    # mesh_mcp_register, mesh_mcp_list, mesh_tool_call, mesh_mcp_remove
│   │   │   ├── mcp-registry-broker.ts  # mesh_mcp_deploy, undeploy, update, logs, scope, schema, catalog
│   │   │   ├── vault.ts                # vault_set, vault_list, vault_delete
│   │   │   ├── url-watch.ts            # mesh_watch, mesh_unwatch, mesh_watches
│   │   │   ├── webhooks.ts             # create_webhook, list_webhooks, delete_webhook
│   │   │   └── index.ts
│   │   ├── middleware/
│   │   │   ├── logging.ts
│   │   │   └── error-handler.ts
│   │   └── handlers/
│   │       ├── stdio.ts
│   │       └── jsonrpc.ts
│   │
│   ├── constants/
│   │   ├── paths.ts                    # XDG paths for ~/.claudemesh/
│   │   ├── urls.ts                     # default API / broker URLs
│   │   ├── timings.ts                  # polling intervals, timeouts
│   │   ├── exit-codes.ts               # numeric exit code constants
│   │   └── index.ts
│   │
│   ├── types/
│   │   ├── api.ts                      # request/response types
│   │   ├── mesh.ts                     # mesh, member, invite types
│   │   ├── peer.ts
│   │   └── index.ts
│   │
│   ├── utils/
│   │   ├── levenshtein.ts              # typo recovery
│   │   ├── slug.ts                     # hostname → slug
│   │   ├── url.ts                      # URL parsing
│   │   ├── format.ts                   # bytes, durations
│   │   ├── semver.ts                   # version comparison
│   │   ├── retry.ts                    # backoff helpers
│   │   └── index.ts
│   │
│   ├── locales/
│   │   ├── en.ts                       # simple string templates (no ICU in Pass 1)
│   │   └── index.ts
│   │
│   └── templates/                      # mesh templates (port from v1 templates/index.ts)
│       ├── dev-team.ts
│       ├── research.ts
│       ├── ops-incident.ts
│       ├── simulation.ts
│       ├── personal.ts
│       └── index.ts
│
└── tests/                              # See parity test plan for full layout
    ├── unit/                           # colocated tests under src/services/*/
    ├── parity/                         # v1/v2 behavioral equivalence (~70 files)
    ├── contract/                       # WS protocol compatibility (~85 files)
    ├── mcp-tools/                      # per-tool handler parity (79 files)
    ├── e2e/                            # full journeys against real broker (~28 files)
    ├── golden/                         # --json output shape (~12 files)
    ├── fixtures/
    └── helpers/

What's NOT in this tree (versus Pass 2):

• No src/services/store/ — no local SQLite source of truth
• No src/services/broker/sync-daemon.ts — no outbox/inbox sync
• No src/services/broker/peer-crypto.ts (beyond hello-sig + envelope that v1 already has)
• No src/migrations/ — no config migrations because there's no v1 user base
• No src/ui/accessibility/ — no announcement shim
• No src/ui/session-kind.ts — no output budget enum
• No src/locales/es.ts — Pass 1 is English-only (Spanish is Pass 2)
• No src/services/broker/mcp-catalog.ts — no CLI-side catalog mirror

The scaffold for Pass 1 creates ~200 files (similar to Pass 2 scaffold but leaner on the services/store/, services/broker/sync-*, ui/accessibility/, and Pass 2-specific areas).

---

4. CLI command surface

4.1 Main --help output

$ claudemesh --help

claudemesh — peer mesh for Claude Code sessions
v1.0.0

USAGE
  claudemesh                 start a session in your mesh (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 (copies to clipboard)
  claudemesh list            see your meshes
  claudemesh rename <name>   rename the current mesh
  claudemesh leave [mesh]    leave a mesh
  claudemesh peers           see who's in the current mesh

  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

When something's wrong
  claudemesh doctor          diagnose install/config/connection issues
  claudemesh whoami          show current identity
  claudemesh status          check broker connectivity

Authentication
  claudemesh register        create a claudemesh.com account from the CLI
  claudemesh login           sign in via browser
  claudemesh logout          sign out and clear credentials

Setup
  claudemesh install           register MCP server + status hooks with Claude Code
  claudemesh uninstall         remove MCP server + hooks
  claudemesh sync              refresh mesh list from your dashboard
  claudemesh connect telegram  link a Telegram bot to a mesh (interactive wizard)

Internal (for Claude Code and scripts)
  claudemesh mcp             stdio MCP server
  claudemesh hook            handle Claude Code hook events
  claudemesh seed-test-mesh  dev-only helper

4.2 Flat command namespace

There is no advanced prefix. There is no launch subcommand. connect telegram is preserved as an interactive wizard (see §5.7); disconnect telegram is dropped. Every command above is callable directly.

The main --help groups commands visually (USAGE block + "When something's wrong" + "Authentication" + "Setup" + "Internal") but this is display formatting, not namespacing. claudemesh register is a direct invocation, not claudemesh advanced register.

4.3 Bare command behavior

$ claudemesh

Depends on machine state:

• First run, no config: runs the welcome wizard (commands/welcome.ts) which detects first-time use and prompts for register/login/join/exit.
• Returning user, config present: launches a session directly. Picks the mesh from (in priority order): --mesh flag → last-used cache (services/state/last-used.ts) → interactive picker if ambiguous → the only joined mesh if there's just one.
• Returning user, flag-first invocation (claudemesh --resume abc, claudemesh --name X, claudemesh -y): same as returning user launch, with the flags passed to the launch handler.
• Returning user, mesh already determined, clipboard has invite URL: offers the invite as an alternative option before launching.

This is the v1 behavior preserved verbatim, minus the launch word.

4.4 Exit codes

0   success
1   user cancelled (Ctrl-C, declined prompt)
2   authentication failed
3   invalid arguments / unknown command
4   network error (broker or API unreachable — only when network was explicitly required)
5   not found (mesh, invite, peer)
6   already exists (slug collision, duplicate command)
7   permission denied (role, scope)
8   internal error (bug)
9   claude binary missing

These are defined in src/constants/exit-codes.ts and imported by every command handler.

4.5 Flag conventions

• -y / --yes — skip interactive confirmations
• -q / --quiet — suppress non-essential output
• -v / --verbose — increase log detail
• --json / --output-format json — machine-readable output with schema_version: "1.0"
• --mesh <slug> — override mesh selection
• --token <value> — override auth token (for scripts)
• --help / -h — per-command help

-y is the key flag. It enables scripted/non-interactive use by skipping every prompt. Commands that require a confirmation in interactive mode just proceed when -y is passed.

---

5. CLI user flows (net new)

All five user flows run against claudemesh.com's existing Better Auth + dashboard infrastructure. The broker already has POST /cli-sync (inventory §4) for JWT-based sync — v2 Pass 1 extends this to a full device-code OAuth flow.

5.1 claudemesh register

Creates a new claudemesh.com account via browser handoff (email verification is a browser-side step).

$ claudemesh register

  Opening browser for account signup…

  [browser opens to claudemesh.com/register?source=cli]
  [user fills in email, password, verifies email]
  [browser redirects to claudemesh.com/cli-auth with success token]

  ✔ Account created: alejandro@example.com
  ✔ Signed in.

Implementation:

1. CLI generates a one-time callback URL with a local port listener (services/auth/callback-listener.ts, ported from v1)
2. Opens browser to claudemesh.com/register?source=cli&callback=http://localhost:<port>
3. User completes signup + email verification on the web
4. claudemesh.com posts a session token back to the callback
5. CLI stores token in ~/.claudemesh/auth.json via services/auth/token-store.ts
6. CLI calls POST /cli-sync to fetch any existing meshes (usually none for a new account)

Backend requirement: claudemesh.com/register?source=cli&callback=<url> must exist. If it doesn't, Pass 1 scope expands to add it to the web app (but this is a single Next.js page, not a backend architectural change).

5.2 claudemesh login

Device-code OAuth against claudemesh.com for existing accounts.

$ claudemesh login

  Opening browser for sign-in…

  If your browser didn't open, visit:
    https://claudemesh.com/cli-auth?code=ABCD-EFGH

  Waiting for confirmation…

  ✔ Signed in as Alejandro.
  ✔ Synced 3 meshes: platform-team, alejandro-mbp, claudefarm

Implementation:

1. CLI POSTs /api/auth/cli/device-code/new with device info (hostname, os, arch)
2. Receives { device_code, user_code, expires_at, verification_url }
3. Opens browser to verification_url?code=<user_code>
4. Prints the user code to terminal as fallback
5. Polls /api/auth/cli/device-code/<device_code> every 1.5 seconds
6. On approval, receives { session_token, user } + stores in ~/.claudemesh/auth.json
7. Calls POST /cli-sync to fetch meshes

Backend requirement: /api/auth/cli/device-code/* endpoints must exist. These are net new. Pass 1 scope includes adding them to apps/web/src/app/api/auth/cli/ as a thin wrapper around Better Auth's session creation. This is ~100 lines of backend TypeScript.

5.3 claudemesh logout

$ claudemesh logout

  ✔ Revoked session on claudemesh.com
  ✔ Removed ~/.claudemesh/auth.json

Implementation:

1. Calls DELETE /api/my/sessions/current (or equivalent Better Auth revoke endpoint)
2. Deletes ~/.claudemesh/auth.json
3. On server revocation failure, still removes local file and warns:

   ✔ Removed local credentials.
   ⚠ Could not revoke session on claudemesh.com. Revoke manually at
     https://claudemesh.com/dashboard/settings/sessions
   

5.4 claudemesh whoami

$ claudemesh whoami

  Signed in as Alejandro (alejandro@example.com)
  Token source: device-code (~/.claudemesh/auth.json)
  Meshes: 3 owned, 1 guest

With --json:

{
  "schema_version": "1.0",
  "signed_in": true,
  "user": {
    "id": "usr_abc123",
    "display_name": "Alejandro",
    "email": "alejandro@example.com"
  },
  "token_source": "device-code",
  "meshes": { "owned": 3, "guest": 1 }
}

Implementation: reads ~/.claudemesh/auth.json, calls GET /api/my/profile to verify + refresh, prints formatted output.

5.5 claudemesh new <name>

Creates a mesh on claudemesh.com from the CLI.

$ claudemesh new "Platform team"

  ✔ Created "platform-team" (id: msh_abc123)
  ✔ You're the owner
  ✔ Joined locally

  Invite teammates with: claudemesh invite

Implementation:

1. Requires authenticated session (if not, triggers login flow first)
2. POSTs /api/my/meshes with { name, slug?: "platform-team" } (slug auto-derived from name if not provided)
3. On slug collision, suggests alternative: "A mesh called 'platform-team' already exists. Try 'platform-team-2'?"
4. On success, stores the mesh in local config via services/config/facade.ts
5. Joins locally (generates Ed25519 keypair, stores in ~/.claudemesh/keys/<slug>.key)

Flags:

• --template <name> — use a mesh template (reuses templates/ directory ported from v1)
• --description <text> — optional description

Backend requirement: POST /api/my/meshes must exist. It may already exist (v1 backend has mesh creation endpoints per member-api.ts). If not, adding it is ~50 lines on top of existing schema patterns.

5.6 claudemesh invite [email]

Generates an invite URL for the current mesh, optionally sending email.

$ claudemesh invite

  ✔ Invite URL copied to clipboard:
    https://claudemesh.com/i/AB12CD34

  Expires in 7 days. Anyone with this link can join "platform-team".

With email:

$ claudemesh invite alice@example.com

  ✔ Sent to alice@example.com
  ✔ Also copied to clipboard

Implementation:

1. Resolves current mesh (via services/mesh/resolve-target.ts)
2. POSTs /api/my/meshes/:slug/invites with { email?, expires_in?: "7d", role?: "member" }
3. Receives { url, code, expires_at }
4. Copies to clipboard via services/clipboard/facade.ts
5. If email provided, backend sends an invitation email (reuses existing transactional email path in the web app)

Flags:

• --mesh <slug> — target mesh (default: current)
• --expires <dur> — expiry (default: 7d)
• --uses <n> — max uses (default: unlimited)
• --role <role> — role for the invitee (default: member)

Backend requirement: POST /api/my/meshes/:slug/invites must exist. v1 has the inverse flow (POST /api/public/invites/:code/claim). Generating an invite is presumably already there since the dashboard has an "Invite" button — this just exposes it over the CLI.

5.7 claudemesh connect telegram

Interactive wizard that picks a mesh, requests a connect token from the broker, and shows a QR code + t.me deep link for the user to scan. Replaces v1's silent auto-pick of config.meshes[0] (which was a multi-mesh footgun).

$ claudemesh connect telegram

  Connect Telegram to a mesh
  ──────────────────────────

  Select mesh:
  ❯ 1) platform-team      (owner, 4 members)
    2) alejandro-mbp      (owner, 1 member)
    3) claudefarm         (guest, 12 members)

  [enter to confirm, ↑↓ to change, q to cancel]

  ✔ Token generated for "platform-team"

  Scan with your phone camera, or tap the link:

    █▀▀▀▀▀█ ▀▀ █▄▄▀ █▀▀▀▀▀█
    █ ███ █ ██▄▄▄▄▀ █ ███ █
    ...

    https://t.me/claudemeshbot?start=abc123…

  Waiting for confirmation from Telegram… (Ctrl-C to skip)

  ✔ Connected as @alejandro_m
    Messages to tg:alejandro_m now route to Telegram.

Implementation:

1. Loads joined meshes from services/config/facade.ts. If zero → error with claudemesh join <url> hint. If one → skip the picker. If multiple → render Ink mesh picker in ui/telegram/ConnectWizard.tsx.
2. Converts the chosen mesh's brokerUrl from wss:// to https://, POSTs {meshId, memberId, pubkey, secretKey} to <broker>/tg/token.
3. Broker returns {token, deepLink}. Wizard renders qrcode-terminal ASCII block + the raw link so users on desktop can copy-paste.
4. Opens a short-lived WS subscription on the chosen mesh and waits for a telegram_bridge_connected push (new broker event — see §5.7.1 below). If received within 5 minutes, prints the success line with the resolved tg:<username>.
5. On Ctrl-C, prints The link stays valid. Run 'claudemesh connect telegram --status' later to check. and exits 0.

Flags:

• --mesh <slug> — skip the picker, target a specific mesh
• --link — print only the deep link, no QR, no wait (for scripting)
• --status — check whether the current mesh already has a Telegram bridge registered, without generating a new token

Broker dependencies to verify before Phase 5:

1. Token TTL — /tg/token currently returns {token, deepLink}. If the broker knows the TTL (it should — generateTelegramConnectToken encodes an expiry), extend the response to {token, deepLink, expiresAt}. This is a 3-line broker change and is the only broker touch permitted in Pass 1. Alternatively, the wizard just prints "link stays valid for a while" without a specific duration.
2. Bridge-connected push event — if the broker doesn't already emit a push when a Telegram bridge claims a token, the wizard falls back to polling GET /mesh/:id/members every 2s for a new tg:* member, with a 5-minute timeout. Polling is acceptable for Pass 1 — no broker change needed.
3. Rate limit — /tg/token is capped at 10 requests/hour/IP. Wizard must catch the 429 and print You've requested too many Telegram tokens in the last hour. Try again in a few minutes. instead of raw HTTP errors.

5.7.1 Optional broker edit (small, allowed)

The rule "broker unchanged in Pass 1" has one permitted exception: extending the /tg/token response with expiresAt. This is additive, unversioned, and costs three lines. If the v2 implementer judges even this too risky, the wizard simply omits the TTL display.

No other broker change is in scope.

---

6. Broker compatibility

6.1 The broker is unchanged

apps/broker/src/ stays exactly as it is in v1. No files are added, modified, or removed. The broker:

• Listens on the same WS endpoint
• Handles the same 85 WS message types
• Serves the same 18 HTTP endpoints
• Uses the same Postgres schema
• Runs the same Neo4j, Qdrant, MinIO, Docker backends
• Executes the same Telegram bridge (telegram-bridge.ts, 1711 lines, unchanged)
• Applies the same rate limits, audit logging, status engine, priority delivery

Why: because there are no broker-side changes in scope, and touching the broker introduces risk without reward for Pass 1. Every Pass 2 improvement to the broker (role-per-mesh isolation, egress proxy, catalog audit, etc.) is deferred until its own decision point.

6.2 The CLI speaks v1's WS protocol

v2's services/broker/ws-client.ts is a port of v1's ws/client.ts. The port preserves:

• Every WS message type's envelope shape
• Every field name and type
• The Ed25519 hello signature format
• NaCl crypto_box envelope wrapping for send_message
• Reconnect logic, message queue, request/response correlation

The parity test layer 2 (WS contract tests) verifies this empirically by capturing v1's envelope for each message type and asserting v2's envelope matches byte-for-byte (modulo nonces and timestamps).

6.3 HTTP API compatibility

v2's services/api/my.ts and services/api/public.ts call the same endpoints v1 uses. POST /cli-sync, POST /invites/:code/claim, POST /hook/set-status, POST /upload, GET /download/:id, etc. — all unchanged.

The new user flow endpoints (/api/auth/cli/device-code/*, POST /api/my/meshes, POST /api/my/meshes/:slug/invites, DELETE /api/my/sessions/current, GET /api/my/profile) are net new but live in the claudemesh.com web app (apps/web/), not the broker. They're ~200 lines of Next.js API routes total.

6.4 Backend services unchanged

Postgres, Neo4j, Qdrant, MinIO, Docker — all on their v1 configurations. No role changes, no schema changes, no hardening, no egress controls. These all stay as Pass 2 work.

---

7. Implementation phases

Phases are organized by what gets built in each step. No time estimates — each phase ships when its acceptance criteria are met.

Phase 0 — Scaffold

• Create apps/cli-v2/ with the full source tree
• All files exist as stubs throwing NotImplementedError with the relevant spec reference in the header
• package.json, tsconfig.json, bunfig.toml, build.ts, .eslintrc.cjs, dependency-cruiser.config.js, biome.json all configured
• Custom ESLint plugin tools/eslint-plugin-claudemesh/ scaffolded (3 rules)
• Test files for every layer of the parity plan scaffolded (~300 files)
• CI runs: lint green, type-check green, zero violations in dependency-cruiser + boundaries
• Done when: scaffold compiles and tests run (even if most tests are NotImplementedError)

Phase 1 — Foundation layers

• types/, constants/, utils/, locales/ fully implemented
• Pure services (services/device/, services/clipboard/, services/spawn/, services/crypto/, services/i18n/, services/logger/, services/lifecycle/)
• Unit tests for each (colocated)
• No user-visible behavior yet
• Done when: pure-layer unit tests all pass, 80%+ branch coverage on foundation services

Phase 2 — Config + state + API client

• services/config/ reads + writes ~/.claudemesh/config.json with 0600 enforcement
• services/state/last-used.ts persists mesh picker cache
• services/api/client.ts typed fetch wrapper with retry
• services/api/my.ts + services/api/public.ts endpoint helpers
• Unit tests for each
• Done when: config round-trips, API client calls a mock server

Phase 3 — Broker client (port from v1 ws/)

• services/broker/ws-client.ts ports v1's ws/client.ts into the facade pattern
• services/broker/envelope.ts and hello-sig.ts port v1's crypto primitives
• All 85 WS message types have typed facade methods
• Contract test layer (parity plan layer 2) goes green
• Done when: every WS contract test passes against captured v1 envelopes

Phase 4 — MCP server (port from v1 mcp/server.ts)

• mcp/server.ts + router.ts + 21 tool family files
• Each tool family ports v1's handler logic unchanged, calling the new broker facade instead of v1's direct WS client
• MCP tool parity test layer (parity plan layer 3) goes green
• Done when: all 79 MCP tool parity tests pass

Phase 5 — Auth + CLI user flows

• services/auth/ full implementation: device-code flow, token store, dashboard sync, callback listener, browser opener
• commands/register.ts, commands/login.ts, commands/logout.ts, commands/whoami.ts
• Backend work (if needed): add /api/auth/cli/device-code/* endpoints to apps/web/
• commands/new.ts, commands/invite.ts — call the new backend endpoints
• End-to-end test of full flow: register → login → new mesh → invite → logout
• Done when: fresh user can register, create a mesh, invite a teammate, all from the CLI

Phase 6 — Mesh + invite + remaining commands

• services/mesh/ — list, rename, leave, join, resolve-target (port from v1)
• services/invite/ — generate, parse-url, claim (port from v1)
• commands/join.ts, commands/list.ts, commands/rename.ts, commands/leave.ts, commands/peers.ts, commands/send.ts, commands/inbox.ts, commands/state.ts, commands/info.ts, commands/remember.ts, commands/recall.ts, commands/remind.ts, commands/profile.ts, commands/status.ts, commands/sync.ts
• commands/install.ts, commands/uninstall.ts — port from v1 (writes to ~/.claude.json + ~/.claude/settings.json)
• commands/doctor.ts — port from v1's 7 checks
• Parity test layer (parity plan layer 1) goes green for all non-launch commands
• Done when: every command in §4.1 main help works identically to v1

Phase 7 — UI flows (welcome wizard + launch)

• ui/welcome/ — welcome wizard screens (port from v1 commands/welcome.ts)
• ui/launch/ — launch flow screens (port from v1 commands/launch.ts interactive bits)
• commands/welcome.ts → renders ui/welcome/WelcomeScreen
• Bare claudemesh dispatches to welcome (first run) or launch (returning)
• Parity test layer for first-run + launch journeys goes green
• Done when: welcome wizard and launch flow work identically to v1

Phase 8 — Golden JSON + E2E tests

• tests/golden/ — lock JSON output shape for every command that supports --json
• tests/e2e/ — full journey tests against a real broker in testcontainers
• E2E tests cover the 28 flows from parity plan §6
• Done when: all e2e tests green on main, all golden tests green on PR

Phase 9 — Docs + ship

• apps/cli-v2/README.md — usage, install, architecture overview
• apps/cli-v2/CHANGELOG.md — v1.0.0 entry listing changes from v0.10.5
• Root README.md updated to reference v2
• docs/quickstart.md rewritten for v2 command surface
• Migration notes: none (no users to migrate)
• Done when: docs complete, all layers green, ready to ship

Phase 10 — Atomic swap + v1.0.0 publish

Single atomic commit:

rm -rf apps/cli && mv apps/cli-v2 apps/cli
git commit -m "v2: replace v1 CLI with the refactored v2 implementation"

Followed by:

cd apps/cli && pnpm publish --access public --no-git-checks
git tag v1.0.0
git push origin main --tags

No legacy preservation, no rollback window, no deprecation period. Clean break. (Feature is at apps/cli/ after the swap, not apps/cli-v2/.)

---

8. Acceptance criteria

v2 Pass 1 ships when all of these are true:

Test gates

• Every test file in 2026-04-11-v2-parity-test-plan.md has a passing assertion (no NotImplementedError remaining)
• Layer 1 parity: ~70 test files covering v1 inventory §12 regression checks — all green
• Layer 2 contract: ~85 test files covering WS message types — all green against captured v1 envelopes
• Layer 3 MCP tool parity: 79 test files covering every MCP tool — all green
• Layer 4 e2e: 28 journey tests — all green against real broker in testcontainers
• Layer 5 golden JSON: 12 test files locking --json output shapes — all green
• Layer 6 facade units: colocated tests + boundary scanner — all green
• Layer 7 port-forwarded v1 tests: crypto round-trip + invite parse — all green

Lint / type / structure gates

• biome check — zero violations
• tsc --noEmit — zero errors, strict mode
• ESLint boundaries plugin — zero violations (facade pattern holds)
• ESLint custom rules (no-index-reexport-internal, type-imports-count-as-edges, no-dynamic-service-imports) — zero violations
• dependency-cruiser — zero circular imports, zero layer violations, zero v1 imports (no-v1-dependencies rule)
• no-restricted-imports — zero violations

Coverage gates

• services/*/*.test.ts — 80%+ branch coverage on non-broker services
• services/broker/* — 70%+ branch coverage via integration tests (WS client is the bulk of this)
• No file below 60% branch coverage without a documented reason in a PR comment

Build / ship gates

• bun build.ts produces dist/entrypoints/cli.js and dist/entrypoints/mcp.js
• Gzipped JS bundle < 1.2 MB (enforced in build.ts)
• bin/claudemesh shebang works on macOS + Linux
• pnpm publish dry-run passes
• Published package installable via npm i -g claudemesh-cli@1.0.0-rc.1
• Cold start < 400 ms on Apple M2 Pro (benchmarked in tests/bench/cold-start.bench.ts)

Behavioral gates (against v1 feature inventory §12)

• First-run install works on a fresh machine
• Welcome wizard shows on bare command with no config
• Launch works on returning machine (bare + flag-first)
• All 79 MCP tools dispatch correctly through the v2 MCP server
• Status priority engine (hook > manual > jsonl) unchanged
• Message queue priority delivery (now / next / low) unchanged
• Cryptographic integrity (Ed25519 signatures, NaCl envelopes, AES-GCM files) unchanged
• Scheduled reminders survive broker restart
• URL watch detects changes + survives broker restart
• Telegram bridge continues to work on the broker side (verified via e2e against broker directly, not via v2 CLI subcommand which is gone)
• Dashboard sync (POST /cli-sync) works
• Webhooks (POST /hook/:meshId/:webhookId) route external requests to mesh messages
• Doctor's 7 checks all pass on a clean install

New behavior gates (net new in Pass 1)

• claudemesh register creates a new claudemesh.com account from the CLI
• claudemesh login completes the device-code flow
• claudemesh logout revokes the session + clears local credentials
• claudemesh whoami prints current identity
• claudemesh new <name> creates a mesh via POST /api/my/meshes
• claudemesh invite generates an invite via POST /api/my/meshes/:slug/invites
• claudemesh invite <email> sends a transactional email (if backend supports)
• Complete first-time user journey: register → new → invite → send → logout works end-to-end without opening the browser except for account signup email verification

Regression gates (nothing should break)

• Zero previously-passing tests become failing
• No --json output shape change for any command that supported --json in v1
• Broker test suite (unchanged in Pass 1) stays green

When all gates are true, Pass 1 ships.

---

9. What gets renamed vs what gets rewritten

Files that are ports (move + update imports, preserve logic)

These files' business logic is preserved verbatim from v1. The only changes are folder location, import paths, and the addition of a facade wrapper.

v1 file	v2 location	Change
cli/src/ws/client.ts	services/broker/ws-client.ts	Import paths, facade wrap
cli/src/ws/manager.ts	services/broker/manager.ts	Import paths
cli/src/crypto/envelope.ts	services/broker/envelope.ts	Folder move only
cli/src/crypto/hello-sig.ts	services/broker/hello-sig.ts	Folder move only
cli/src/crypto/keypair.ts	services/crypto/keypair.ts	Facade wrap
cli/src/crypto/file-crypto.ts	services/crypto/file-crypto.ts	Facade wrap
cli/src/auth/callback-listener.ts	services/auth/callback-listener.ts	Folder move
cli/src/auth/open-browser.ts	services/spawn/browser.ts	Consolidated with launch spawn
cli/src/auth/pairing-code.ts	services/auth/pairing-code.ts	Folder move
cli/src/auth/sync-with-broker.ts	services/auth/dashboard-sync.ts	Folder move + facade wrap
cli/src/invite/parse.ts	services/invite/parse-url.ts	Folder move
cli/src/invite/enroll.ts	services/invite/claim.ts	Folder move
cli/src/lib/invite-v2.ts	services/invite/parse-url.ts (merged)	Consolidated
cli/src/state/config.ts	services/config/ (split into read + write)	Split + facade wrap
cli/src/mcp/server.ts (2139 lines)	mcp/server.ts + mcp/router.ts + 21 tool family files	Split by family
cli/src/mcp/tools.ts	mcp/tools/*.ts — 21 family files	Split by family
cli/src/templates/index.ts	templates/ — 5 individual files	Split by template name
cli/src/commands/launch.ts (775 lines)	commands/welcome.ts + ui/launch/ + launch handler dispatched from bare command	Split
cli/src/commands/welcome.ts	commands/welcome.ts + ui/welcome/	Split
cli/src/commands/install.ts	commands/install.ts	Folder move, port ~538 lines
cli/src/commands/doctor.ts	commands/doctor.ts + services/health/check-*.ts	Split into health checks
cli/src/commands/join.ts	commands/join.ts + services/mesh/join.ts	Split into command + service
cli/src/commands/list.ts	commands/list.ts + services/mesh/list.ts	Split
cli/src/commands/leave.ts	commands/leave.ts + services/mesh/leave.ts	Split
cli/src/commands/peers.ts	commands/peers.ts	Folder move
cli/src/commands/send.ts	commands/send.ts	Folder move
cli/src/commands/inbox.ts	commands/inbox.ts	Folder move
cli/src/commands/state.ts	commands/state.ts	Folder move
cli/src/commands/info.ts	commands/info.ts	Folder move
cli/src/commands/memory.ts	commands/remember.ts + commands/recall.ts	Split into two commands
cli/src/commands/remind.ts	commands/remind.ts	Folder move
cli/src/commands/profile.ts	commands/profile.ts	Folder move
cli/src/commands/status.ts	commands/status.ts	Folder move
cli/src/commands/sync.ts	commands/sync.ts	Folder move
cli/src/commands/hook.ts	commands/hook.ts	Folder move
cli/src/commands/create.ts	commands/new.ts	Renamed (from create to new, matches spec)
cli/src/commands/seed-test-mesh.ts	commands/seed-test-mesh.ts	Folder move
cli/src/commands/connect-telegram.ts	commands/connect-telegram.ts + ui/telegram/ConnectWizard.tsx	Port + split: command stays thin, mesh picker + QR render live in Ink wizard (§5.7)
cli/src/tui/colors.ts	ui/styles.ts	Folder move, keep v1 values (Pass 2 redesigns)
cli/src/tui/index.ts	ui/index.ts	Folder move
cli/src/tui/screen.ts	ui/screen.ts	Folder move
cli/src/tui/spinner.ts	ui/spinner.ts	Folder move
cli/src/env.ts	constants/urls.ts + constants/paths.ts (split)	Consolidated into constants
cli/src/version.ts	constants/version.ts	Folder move
cli/src/logo-spinner.ts	ui/logo-spinner.ts	Folder move
cli/src/index.ts	entrypoints/cli.ts + commands/index.ts	Split entry point from command registry
cli/src/__tests__/crypto-roundtrip.test.ts	tests/unit/crypto-roundtrip.test.ts	Folder move
cli/src/__tests__/invite-parse.test.ts	tests/unit/invite-parse.test.ts	Folder move

Files that are NET NEW in Pass 1

v2 file	Purpose
commands/register.ts	Account creation via browser handoff
commands/login.ts	Device-code OAuth
commands/logout.ts	Revoke session
commands/whoami.ts	Identity check
commands/invite.ts	Generate invite (was dashboard-only in v1)
commands/rename.ts	Rename a mesh (was dashboard-only in v1)
services/auth/device-code.ts	Device-code flow orchestration
services/auth/token-store.ts	~/.claudemesh/auth.json R/W
services/auth/client.ts	HTTP calls to new /api/auth/cli/* endpoints
services/auth/facade.ts	Public auth API
services/mesh/create.ts	POST /api/my/meshes
services/mesh/facade.ts	Public mesh API
services/invite/generate.ts	POST /api/my/meshes/:slug/invites
services/invite/send-email.ts	Email delivery through backend
services/invite/facade.ts	Public invite API
services/api/facade.ts	Public HTTP API
services/config/facade.ts	Public config API
services/state/last-used.ts	Last-used mesh/name/role cache
services/state/facade.ts	Public state API
services/device/facade.ts	Device info for device-code registration
services/clipboard/facade.ts	Clipboard read
services/spawn/facade.ts	Claude + browser spawning
services/telemetry/facade.ts	Usage event emission (opt-out)
services/health/facade.ts	Doctor checks
services/update/facade.ts	npm registry version poll
services/i18n/facade.ts	String templates (no ICU in Pass 1)
services/lifecycle/facade.ts	Service lifecycle manager
services/logger/facade.ts	Structured logger
cli/argv.ts	argv parsing
cli/print.ts	stdout helpers
cli/structured-io.ts	JSON output
cli/exit.ts	Exit code + cleanup hooks
cli/update-notice.ts	Update banner
cli/handlers/signal.ts	SIGINT/SIGTERM
cli/handlers/error.ts	Top-level error handler
cli/output/list.ts	Plain-text list renderer
cli/output/peers.ts	Plain-text peers renderer
cli/output/whoami.ts	Plain-text whoami renderer
cli/output/version.ts	Version output
tools/eslint-plugin-claudemesh/	Custom ESLint plugin (3 rules)
tests/helpers/v1-runner.ts	Spawns v1 CLI for parity comparisons
tests/helpers/v2-runner.ts	Spawns v2 CLI for parity comparisons
tests/helpers/wire-capture.ts	Records WS envelopes
tests/helpers/mock-broker.ts	In-memory broker
tests/helpers/real-broker.ts	Testcontainers broker harness

Files that are DELETED (no v2 replacement)

v1 file	Why deleted
cli/src/commands/disconnect-telegram.ts	Bridge teardown is handled inside Telegram (/revoke in the bot) or by leaving the mesh; a CLI wrapper is purely cosmetic

Files that are NEW in the backend (apps/web/)

File	Purpose
apps/web/src/app/api/auth/cli/device-code/new/route.ts	Issue device code
apps/web/src/app/api/auth/cli/device-code/[code]/route.ts	Poll device code status
apps/web/src/app/api/auth/cli/device-code/[code]/approve/route.ts	Approve from browser
apps/web/src/app/[locale]/cli-auth/page.tsx	Browser-side approval UI
apps/web/src/app/api/my/meshes/route.ts	POST = create mesh (may already exist)
apps/web/src/app/api/my/meshes/[slug]/invites/route.ts	POST = generate invite (may already exist)
apps/web/src/app/api/my/profile/route.ts	GET = whoami (may already exist)
apps/web/src/app/api/my/sessions/current/route.ts	DELETE = logout

These are small Next.js API routes (~50 lines each) that wrap Better Auth's session management. The exact set depends on what already exists in the web app — an audit is part of Phase 5.

---

10. Decisions locked in by this spec

If you want to change any of these, update this spec and run the parity tests again.

1. CLI command surface is flat. No advanced prefix. No launch subcommand. No connect telegram / disconnect telegram. The main --help groups commands visually but the namespace is flat.

2. Pass 1 preserves every v1 feature in the inventory. No feature cuts, no "while we're at it, let's also change X." The only removals are CLI subcommands that don't add value (launch, connect-telegram, disconnect-telegram).

3. The broker is unchanged in Pass 1. No files added, modified, or removed. All broker improvements are deferred to Pass 2.

4. Facade pattern is mandatory. Every service has a facade.ts as the single public entry point. ESLint boundaries enforce this.

5. No Pass 2 features sneak in. No local SQLite, no Lamport, no sync daemon, no hardened Postgres, no MCP catalog tiering, no ICU, no accessibility matrix, no session_kind enum, no six-color palette redesign, no facade bypass path closures beyond what exists in the Pass 2 facade spec.

6. No backwards compatibility hedges. There are no users to migrate. v2 picks the best names, shapes, and conventions without alias support or deprecation windows.

7. The parity test suite is the acceptance criteria. Not vibes, not "looks good to me," not code review alone. A red test means not-done.

8. The broker's WS protocol is the only compatibility contract that matters. Everything above that layer (command names, config shape, JSON output, env vars, exit codes, stdout text) can change freely.

9. Atomic swap, clean break. When Pass 1 is ready, a single commit replaces apps/cli with apps/cli-v2. No legacy preservation.

10. Pass 1 is done when the acceptance criteria in §8 are all green. Nothing more, nothing less.

---

End of Pass 1 spec.