claudemesh-cli 1.17.0 → 1.19.0

package/dist/entrypoints/cli.js

@@ -88,7 +88,7 @@ __export(exports_urls, {
   VERSION: () => VERSION,
   URLS: () => URLS
 });
-var URLS, VERSION = "1.17.0", env;
+var URLS, VERSION = "1.19.0", env;
 var init_urls = __esm(() => {
   URLS = {
     BROKER: process.env.CLAUDEMESH_BROKER_URL ?? "wss://ic.claudemesh.com/ws",
@@ -5135,6 +5135,14 @@ __export(exports_rename, {
   rename: () => rename
 });
 async function rename(slug, newName) {
+  const auth = getStoredToken();
+  if (!auth) {
+    console.error(`  ${icons.cross} Renaming a mesh requires a claudemesh.com account session.`);
+    console.error(`  ${dim("Joining via invite signs you in to the mesh, not to a web account.")}`);
+    console.error(`  ${dim("Run")} ${bold("claudemesh login")} ${dim("first, then retry, or rename from the dashboard:")}`);
+    console.error(`    https://claudemesh.com/dashboard`);
+    return EXIT.AUTH_FAILED;
+  }
   try {
     await renameMesh2(slug, newName);
     console.log(`  ${green(icons.check)} Renamed "${slug}" to "${newName}"`);
@@ -5146,6 +5154,7 @@ async function rename(slug, newName) {
 }
 var init_rename2 = __esm(() => {
   init_facade10();
+  init_facade6();
   init_styles();
   init_exit_codes();
 });
@@ -11124,6 +11133,752 @@ var init_platform_actions = __esm(() => {
   init_exit_codes();
 });
 
+// skills/claudemesh/SKILL.md
+var SKILL_default = `---
+name: claudemesh
+description: Use when the user asks to send a message to a peer Claude session, list mesh peers, share state across meshes, schedule cross-session reminders, or otherwise interact with claudemesh — a peer mesh runtime for Claude Code sessions. Provides the canonical reference for every \`claudemesh\` CLI verb, its flags, JSON output shape, and common patterns.
+---
+
+# claudemesh skill
+
+\`claudemesh\` is the peer mesh runtime for Claude Code sessions. Each session in a mesh has a name, identity (ed25519 keypair), and shared resources: peers, messages, state, memory, files, vectors, scheduled jobs, skills.
+
+**You invoke claudemesh exclusively through the \`claudemesh\` CLI via Bash.** There are no MCP tools to call — \`tools/list\` returns empty for the claudemesh MCP server. The MCP server exists only to deliver inbound peer messages as \`<channel source="claudemesh">\` interrupts mid-turn. Everything else is CLI.
+
+## When you receive a \`<channel source="claudemesh">\` message
+
+Respond IMMEDIATELY. Pause your current task, reply via \`claudemesh send\`, then resume. Read \`from_name\`, \`mesh_slug\`, and \`priority\` from the channel attributes. Reply by setting \`<to>\` to the sender's \`from_name\`. Do not ignore low-priority messages — acknowledge them briefly even if you defer action. If the channel meta contains \`subtype: reminder\`, this is a scheduled reminder you set yourself — act on it.
+
+### Channel attributes (everything you need to reply is in the push)
+
+The \`<channel>\` interrupt carries these attributes — no lookup needed:
+
+| Attribute | What it is |
+|---|---|
+| \`from_name\` | Sender's display name. **Use as \`to\` in your reply** for DMs. |
+| \`from_pubkey\` | Sender's session pubkey (hex). Stable per-session. |
+| \`from_member_id\` | Sender's stable mesh.member id. Survives display-name changes — the canonical id. |
+| \`mesh_slug\` | Mesh the message arrived on. Pass via \`--mesh <slug>\` if the parent isn't on the same mesh. |
+| \`priority\` | \`now\` / \`next\` / \`low\`. |
+| \`message_id\` | Server-side id of THIS message. **Pass to \`--reply-to <id>\` to thread your reply** in topic posts. |
+| \`topic\` | Set when the source is a topic post. Reply via \`topic post <topic> --reply-to <message_id>\`. |
+| \`reply_to_id\` | Set when the message itself is a reply to a previous one — render thread context. |
+
+**Reply patterns:**
+
+\`\`\`bash
+# DM → use from_name as the target
+claudemesh send "<from_name>" "ack — looking now"
+
+# Topic reply → thread it onto the message you got
+claudemesh topic post "<topic>" "yep, looks good" --reply-to <message_id>
+
+# When the sender is on a different mesh you've joined
+claudemesh send "<from_name>" "..." --mesh "<mesh_slug>"
+\`\`\`
+
+## Performance model (warm vs cold path)
+
+If the parent Claude session was launched via \`claudemesh launch\`, an MCP push-pipe is running and holds the per-mesh WS connection. CLI invocations dial \`~/.claudemesh/sockets/<mesh-slug>.sock\` and reuse that warm connection (~200ms total round-trip including Node.js startup). If no push-pipe is running (cron, scripts, hooks fired outside a session), the CLI opens its own WS, which takes ~500-700ms cold. **You don't manage this** — every verb auto-detects and falls through.
+
+## Spawning new sessions (no wizard)
+
+\`claudemesh launch\` is the canonical way to start a new Claude Code session connected to claudemesh. Pass every required flag up front so no interactive prompt fires — that's what makes the verb scriptable from tmux send-keys, AppleScript/iTerm spawn helpers, hooks, cron, and the \`claudemesh launch\` you call from inside another session. **Always use this verb, never \`claude\` directly with hand-rolled flags** — it sets up the per-session ed25519 keypair, exports \`CLAUDEMESH_DISPLAY_NAME\`, isolates the mesh config in a tmpdir, and passes the \`--dangerously-load-development-channels server:claudemesh\` plumbing that the MCP push-pipe needs.
+
+### Full flag surface
+
+| Flag | What it skips | Notes |
+|---|---|---|
+| \`--name <display-name>\` | the "What's your name?" prompt | required when spawning unattended; persists as the session's display name and \`from_name\` in inbound channels |
+| \`--mesh <slug>\` | the multi-mesh picker | required when the user has joined >1 mesh; otherwise the single mesh is auto-selected |
+| \`--join <invite-url>\` | the "join a mesh first" branch | run join + launch in one step; pair with \`-y\` for fully non-interactive |
+| \`--groups "name:role,name2:role2,all"\` | the group selection prompt | comma-separated \`<groupname>:<role>\` entries; the literal \`all\` joins \`@all\` |
+| \`--role <lead\\|member\\|observer>\` | the role prompt | applied to all groups in \`--groups\` that didn't specify their own |
+| \`--message-mode <push\\|inbox>\` | the message-mode prompt | \`push\` (default) emits \`<channel>\` notifications mid-turn; \`inbox\` only buffers — quieter for headless agents |
+| \`--system-prompt <path>\` | nothing — pure pass-through | forwarded to \`claude --append-system-prompt\` |
+| \`--resume <session-id>\` | nothing — pure pass-through | forwarded to \`claude --resume\` to continue a prior Claude Code session |
+| \`--continue\` | nothing — pure pass-through | forwarded to \`claude --continue\` |
+| \`-y\` / \`--yes\` | every confirmation prompt | including the "you'll skip ALL permission prompts" gate. **Use for autonomous agents; omit for shared/multi-person meshes.** |
+| \`-q\` / \`--quiet\` | the welcome banner | useful when the spawning script wants clean stdout |
+| \`--\` | (separator) | everything after \`--\` is forwarded verbatim to \`claude\`. Example: \`claudemesh launch --name X -y -- --resume abc123 --model opus\` |
+
+### Wizard-free spawn templates
+
+\`\`\`bash
+# Minimal — single joined mesh, fresh agent, autonomous:
+claudemesh launch --name "Lug Nut" -y
+
+# Multi-mesh user — pick mesh explicitly:
+claudemesh launch --name "Mou" --mesh openclaw -y
+
+# Cold-start a peer who hasn't joined the mesh yet:
+claudemesh launch \\
+  --name "Lug Nut" \\
+  --join "https://claudemesh.com/i/abc123" \\
+  --groups "frontend:member,reviewers:observer,all" \\
+  --message-mode push \\
+  -y
+
+# Resume a specific Claude session inside claudemesh:
+claudemesh launch --name "Mou" --mesh openclaw -y -- --resume abc123-...
+
+# Quiet, headless, system-prompt loaded — for cron / hooks:
+claudemesh launch --name "ci-bot" --mesh openclaw \\
+  --system-prompt /path/to/ci-bot.md \\
+  --message-mode inbox \\
+  -q -y
+\`\`\`
+
+If any required flag is missing AND stdin is a TTY, \`launch\` falls back to its prompt for that single field. **In a non-TTY context (Bash tool, cron, AppleScript pipe), missing flags cause the verb to fail-closed — never silently use a default that affects identity.**
+
+### Spawning into new terminal panes/windows
+
+The launch verb itself is just a shell command — wrap it in whatever pane-creation primitive the host platform uses. The patterns that work today:
+
+\`\`\`bash
+# tmux — send into a pane you control. NEVER send-keys into a pane
+# you didn't create; you risk typing into another live TUI.
+tmux new-window -t "$SESSION" -n claudemesh-lugnut
+tmux send-keys -t "$SESSION:claudemesh-lugnut" \\
+  'claudemesh launch --name "Lug Nut" --mesh openclaw -y' Enter
+
+# macOS iTerm2 (split current window into a vertical pane):
+osascript <<'OSA'
+tell application "iTerm2"
+  tell current window
+    create tab with default profile
+    tell current session of current tab
+      write text "claudemesh launch --name \\"Lug Nut\\" --mesh openclaw -y"
+    end tell
+  end tell
+end tell
+OSA
+
+# macOS Terminal.app (new window):
+osascript -e 'tell application "Terminal" to do script "claudemesh launch --name \\"Lug Nut\\" --mesh openclaw -y"'
+
+# GNOME Terminal / generic Linux:
+gnome-terminal -- bash -lc 'claudemesh launch --name "Lug Nut" --mesh openclaw -y'
+
+# screen detached:
+screen -dmS lugnut bash -lc 'claudemesh launch --name "Lug Nut" --mesh openclaw -y'
+
+# Windows Terminal (wt.exe) — open a new tab:
+wt.exe new-tab --title claudemesh-lugnut powershell -NoExit -Command "claudemesh launch --name 'Lug Nut' --mesh openclaw -y"
+
+# Windows Terminal — split the current pane vertically instead:
+wt.exe split-pane -V powershell -NoExit -Command "claudemesh launch --name 'Lug Nut' --mesh openclaw -y"
+
+# PowerShell — spawn a detached window of the user's default shell:
+Start-Process powershell -ArgumentList '-NoExit','-Command','claudemesh launch --name "Lug Nut" --mesh openclaw -y'
+
+# cmd.exe — start a new console window:
+start "claudemesh-lugnut" cmd /k "claudemesh launch --name ""Lug Nut"" --mesh openclaw -y"
+
+# WSL from a Windows host — same launch verb, just route through wsl.exe:
+wsl.exe -- bash -lc 'claudemesh launch --name "Lug Nut" --mesh openclaw -y'
+\`\`\`
+
+Windows-specific gotchas:
+- **Single quotes don't nest in cmd.exe.** Use \`""\` to escape inner double quotes (see the \`cmd /k\` example) or move to PowerShell where single quotes work normally.
+- **\`-NoExit\`** is the PowerShell equivalent of bash's \`exec\` + interactive shell — keeps the window open after \`claudemesh launch\` returns control to its child \`claude\` process. Without it, the window closes when the launch script exits.
+- **WSL paths.** If you spawn from a Windows-side script into WSL, the \`claudemesh\` CLI in WSL writes to \`~/.claudemesh/\` on the Linux side, *not* \`%USERPROFILE%\\.claudemesh\\\`. The two installs are independent — match the spawn host to the install host.
+- **Windows Terminal profile names.** Replace \`powershell\` with \`pwsh\` for PowerShell 7+, or use \`--profile "<name>"\` to target a configured profile (e.g. one preconfigured with WSL Ubuntu + a starting directory).
+
+The user's environment may also have these pre-built helpers (CLAUDE.md will tell you):
+
+- \`~/tools/scripts/spawn-iterm-panes.sh\` and \`spawn-iterm-window.sh\` — safer iTerm spawners that only write into sessions they themselves created.
+- \`~/tools/scripts/claude-peers.sh\` — tmux wrapper that opens a split running \`claudemesh launch\` with sensible defaults.
+
+Prefer those when available — they handle pane ownership / cleanup correctly.
+
+### Sanity rules for unattended spawns
+
+1. **Always pass \`--name\`.** A nameless session falls back to \`<hostname>-<pid>\`, which makes peer attribution opaque in \`peer list\` and inbound channels.
+2. **Always pass \`--mesh\` when the user has multiple meshes joined.** Otherwise the picker fires and the spawn hangs waiting for stdin.
+3. **Pass \`-y\` only when you understand the consent it grants.** It skips every permission gate — fine for an autonomous agent on a private mesh, dangerous on a shared mesh where peers can drive your file system.
+4. **For long-running daemonised peers, use \`--message-mode inbox\`** so they don't fire \`<channel>\` interrupts on every received DM. They poll \`claudemesh inbox\` on their own cadence.
+5. **Confirm the spawn worked** by waiting a few seconds and running \`claudemesh peer list\` — the new peer's \`displayName\` should appear with \`status: "idle"\`.
+
+## Universal flags
+
+| Flag | Behavior |
+|---|---|
+| \`--mesh <slug>\` | Target a specific mesh. Required when the user has multiple meshes joined. Default: first/only joined mesh, or interactive picker. |
+| \`--json\` | Emit JSON instead of human-readable text. Use this when you need to parse the output. |
+| \`--json field1,field2\` | Project specific fields (modeled on \`gh --json\`). Friendly aliases like \`name\` → \`displayName\` are resolved automatically. |
+| \`--approval-mode <mode>\` | \`plan\` / \`read-only\` deny all writes; \`write\` (default) prompts on destructive verbs from the policy file; \`yolo\` bypasses every prompt. |
+| \`--policy <path>\` | Override the policy file (default \`~/.claudemesh/policy.yaml\`, auto-created on first run). |
+| \`-y\` / \`--yes\` | Auto-approve any policy prompt. Equivalent to \`--approval-mode yolo\` for the current invocation. |
+
+## Policy & confirmation
+
+Every broker-touching verb runs through a policy gate before dispatch. The default policy allows reads and prompts on destructive writes (\`peer kick/ban/disconnect\`, \`file delete\`, \`vector/vault delete\`, \`memory forget\`, \`skill remove\`, \`webhook delete\`, \`watch remove\`, \`sql/graph execute\`, \`mesh delete\`). When you call \`claudemesh\` from a non-interactive context (cron, scripts, Claude's Bash tool), prompts auto-deny — pass \`-y\` or \`--approval-mode yolo\` for verbs you've vetted, or edit \`~/.claudemesh/policy.yaml\` to mark them \`decision: allow\`. Every gate decision is appended to \`~/.claudemesh/audit.log\` (newline-JSON).
+
+## Resources and verbs
+
+**Convention:** every operation is \`claudemesh <resource> <verb>\`. Legacy short forms (\`send\`, \`peers\`, \`kick\`, \`remember\`, ...) are aliases that keep working forever; prefer the resource form for new code.
+
+### \`topic\` — conversation scope within a mesh (v0.2.0)
+
+A topic is a named conversation inside a mesh. Mesh = trust boundary. Group = identity tag. **Topic = what you're talking about.** Subscribers receive topic-tagged messages; non-subscribers don't. Topics also persist message history so humans (and opting-in agents) can fetch back-scroll on reconnect.
+
+\`\`\`bash
+claudemesh topic create deploys --description "deploy + on-call"
+claudemesh topic create incident-2026-05-02 --visibility private
+claudemesh topic list                                    # all topics in mesh
+claudemesh topic join deploys                            # subscribe (by name or id)
+claudemesh topic join deploys --role lead                # join as lead
+claudemesh topic leave deploys
+claudemesh topic members deploys                         # list subscribers
+claudemesh topic history deploys --limit 50              # fetch back-scroll
+claudemesh topic history deploys --before <msg-id>       # paginate older
+claudemesh topic read deploys                            # mark all as read
+
+# Send to a topic — same \`send\` verb, target starts with # (WS, v1 plaintext)
+claudemesh send "#deploys" "rolling out 1.5.1 to staging"
+
+# v1.7.0+: live tail in the terminal — backfill last N + then SSE forward.
+# Decrypts v2 messages on render. Runs a 30s re-seal loop while held.
+claudemesh topic tail deploys --limit 50
+
+# v1.8.0+: encrypted REST send (body_version 2). Falls back to v1
+# automatically for legacy unencrypted topics. --plaintext forces v1.
+claudemesh topic post deploys "rolling out, cc @Alexis stay around"
+
+# v1.9.0+: thread a reply onto a previous topic message. Accepts the
+# full id or an 8+ char prefix; resolved against recent history.
+claudemesh topic post deploys "yes — same here" --reply-to 7XtIeF7o
+\`\`\`
+
+In \`topic tail\` output, replies render with a \`↳ in reply to <name>: "<snippet>"\` line above the message and every row shows a short id tag (\`#xxxxxxxx\`) so you can copy-paste into \`--reply-to\`.
+
+When to use topics vs groups vs DM:
+- **DM** (\`send <peer>\`) — 1:1, ephemeral.
+- **Group** (\`send "@frontend"\`) — addresses everyone in a group; ephemeral; for coordinating teams.
+- **Topic** (\`send "#deploys"\`) — durable conversation room; for ongoing work threads, incident channels, build-status feeds.
+
+### \`member\` — mesh roster + online state (v1.7.0)
+
+Distinct from \`peer list\`: members shows the static roster (every joined member of a mesh, online or not), peers shows the live WS-connected sessions plus REST-active humans.
+
+\`\`\`bash
+claudemesh member list                                   # everyone, with status dots
+claudemesh member list --online                          # only online
+claudemesh member list --mesh deploys --json
+\`\`\`
+
+Status glyphs: \`●\` emerald = idle, \`●\` clay = working, \`●\` red = dnd, \`○\` dim = offline. \`bot\` tag appears on non-human members.
+
+### \`notification\` — recent @-mentions (v1.7.0)
+
+Server-side write-time fan-out from \`mesh.notification\` — one row per recipient per matching \`@-mention\`. Works for both v1 plaintext and v2 ciphertext (clients send the mention list explicitly on v2).
+
+\`\`\`bash
+claudemesh notification list                             # last 24h, all mentions of you
+claudemesh notification list --since 2026-05-01T00:00Z   # incremental for polling
+claudemesh notification list --json                      # parseable
+\`\`\`
+
+### Per-topic encryption (v0.3.0 / CLI 1.8.0)
+
+Topics created on or after CLI 1.8.0 generate a 32-byte XSalsa20-Poly1305 symmetric key sealed for each member via \`crypto_box\`. The broker holds ciphertext only. \`topic post\` encrypts; \`topic tail\` decrypts. The \`🔒 v2\` glyph in tail output marks ciphertext rounds. v1 plaintext topics keep working unchanged.
+
+When a new member joins an encrypted topic, they get a 404 from \`GET /v1/topics/:name/key\` until any holder re-seals for them. \`topic tail\` runs a 30s background loop that does the re-seal automatically while the tail is open. Otherwise the joiner waits for someone with the key to log in.
+
+### \`peer\` — read connected peers + admin (kick / ban / verify)
+
+\`\`\`bash
+claudemesh peer list                              # human-readable (alias: peers)
+claudemesh peer list --json                       # full record
+claudemesh peer list --json name,status           # field projection
+claudemesh peer list --mesh openclaw --json       # specific mesh
+
+claudemesh peer kick <peer>                       # end session, manual rejoin
+claudemesh peer disconnect <peer>                 # soft, peer auto-reconnects
+claudemesh peer ban <peer>                        # kick + revoke membership
+claudemesh peer unban <peer>
+claudemesh peer bans                              # list banned members
+claudemesh peer verify [peer]                     # 6×5-digit safety numbers
+\`\`\`
+
+JSON shape (per peer):
+\`\`\`json
+{
+  "displayName": "Mou",
+  "pubkey": "abc123...",
+  "status": "idle | working | dnd",
+  "summary": "string or null",
+  "groups": [{ "name": "reviewers", "role": "lead" }],
+  "peerType": "claude | telegram | ...",
+  "channel": "claude-code | api | ...",
+  "model": "claude-opus-4-7 | ...",
+  "cwd": "/path/to/working/dir or null",
+  "stats": { "messagesIn": 0, "messagesOut": 0, "toolCalls": 0, "errors": 0, "uptime": 1200 }
+}
+\`\`\`
+
+### \`message\` — send and inspect messages
+
+\`\`\`bash
+# send (alias: claudemesh send <to> <msg>)
+claudemesh message send <peer-name|@group|*|pubkey> "message text"
+claudemesh message send Mou "hi"                       # by display name
+claudemesh message send "@reviewers" "ready for review"
+claudemesh message send "*" "broadcast"
+claudemesh message send <p> "..." --priority now       # bypass busy gates
+claudemesh message send <p> "..." --priority next      # default
+claudemesh message send <p> "..." --priority low       # pull-only
+
+# inbox (alias: claudemesh inbox)
+claudemesh message inbox
+claudemesh message inbox --json
+
+# delivery status (alias: claudemesh msg-status <id>)
+claudemesh message status <message-id>
+claudemesh message status <message-id> --json
+\`\`\`
+
+\`send\` JSON output: \`{"ok": true, "messageId": "...", "target": "..."}\`. Errors: \`{"ok": false, "error": "..."}\`.
+
+### \`state\` — shared per-mesh key-value store
+
+\`\`\`bash
+claudemesh state set <key> <value>        # value can be JSON or string
+claudemesh state get <key>
+claudemesh state get <key> --json         # includes updatedBy, updatedAt
+claudemesh state list
+claudemesh state list --json
+\`\`\`
+
+State is broadcast to all peers when changed. Use it for shared scratch space: status flags, current focus, agreed-on values.
+
+### \`memory\` — recall-able knowledge per mesh
+
+\`\`\`bash
+claudemesh memory remember "fact text" --tags tag1,tag2     # alias: remember
+claudemesh memory recall "search query"                     # alias: recall
+claudemesh memory recall "search query" --json
+claudemesh memory forget <memory-id>                        # alias: forget
+\`\`\`
+
+Memories are searchable across the mesh. Use for shared documentation, decisions, lessons learned.
+
+### \`task\` — typed work-units claim/complete
+
+\`\`\`bash
+claudemesh task create "<title>" --assignee <peer> --priority <p> --tags a,b
+claudemesh task list [--status open|claimed|done] [--assignee <peer>] [--json]
+claudemesh task claim <task-id>
+claudemesh task complete <task-id> [result text]
+\`\`\`
+
+Tasks are exact-once: claiming is atomic at broker. Use for work coordination across peers.
+
+### \`schedule\` — time-based delivery
+
+\`\`\`bash
+# one-shot or recurring (alias: claudemesh remind ...)
+claudemesh schedule msg "ping" --in 30m              # fires in 30 min
+claudemesh schedule msg "ping" --at 15:00            # next 15:00
+claudemesh schedule msg "ping" --cron "0 9 * * *"    # 9am daily
+claudemesh schedule msg "to peer" --to <peer-name>
+claudemesh schedule list --json
+claudemesh schedule cancel <reminder-id>
+
+# webhook + tool schedules arrive in a later release (broker work pending).
+\`\`\`
+
+### \`profile / group\` — peer presence
+
+\`\`\`bash
+claudemesh profile                              # view/edit your profile
+claudemesh profile summary "what you're working on"   # broadcast (alias: summary)
+claudemesh profile status set idle|working|dnd        # alias: status set
+claudemesh profile visible true|false                 # alias: visible
+claudemesh group join @reviewers --role lead
+claudemesh group leave @reviewers
+\`\`\`
+
+### \`vector\` — embedding store + similarity search
+
+\`\`\`bash
+claudemesh vector store <collection> "<text>" [--metadata '<json>']
+claudemesh vector search <collection> "<query>" [--limit N] [--json]
+claudemesh vector delete <collection> <id>
+claudemesh vector collections          # list collection names
+\`\`\`
+
+Search returns \`[{id, text, score, metadata}]\` ranked by cosine similarity.
+
+### \`graph\` — Cypher queries against per-mesh graph
+
+\`\`\`bash
+claudemesh graph query "MATCH (n) RETURN n LIMIT 10"   # read
+claudemesh graph execute "CREATE (n:Foo {x: 1})"      # write
+\`\`\`
+
+Returns rows as \`[{...}, ...]\`. Queries that return no rows render "(no rows)".
+
+### \`context\` — share work-context summaries between peers
+
+\`\`\`bash
+claudemesh context share "summary text" --files a.ts,b.ts --findings "x,y" --tags spec,review
+claudemesh context get "search query"
+claudemesh context list
+\`\`\`
+
+Use to broadcast "what I just did and what I learned" so peers don't duplicate effort.
+
+### \`stream\` — pub/sub event bus
+
+\`\`\`bash
+claudemesh stream create <name>
+claudemesh stream publish <name> '<json-or-text>'
+claudemesh stream list
+\`\`\`
+
+For event broadcasting (build-events, deploy-notifications, sensor data). Subscribers receive via push.
+
+### \`sql\` — typed SQL against per-mesh tables
+
+\`\`\`bash
+claudemesh sql query "SELECT * FROM <table>"     # SELECT only
+claudemesh sql execute "INSERT INTO ..."         # writes
+claudemesh sql schema                            # list tables + columns
+\`\`\`
+
+Returns \`{columns, rows, rowCount}\` for queries. Each mesh has its own SQL namespace.
+
+### \`skill\` — discover + manage mesh-published Claude skills
+
+\`\`\`bash
+claudemesh skill list [search-query]
+claudemesh skill get <skill-name>
+claudemesh skill remove <skill-name>
+\`\`\`
+
+Published skills appear as \`/claudemesh:<name>\` slash commands across all connected sessions.
+
+### \`vault\` — encrypted per-mesh secrets
+
+\`\`\`bash
+claudemesh vault list                # list keys (values stay encrypted on disk)
+claudemesh vault delete <key>
+# claudemesh vault set/get currently goes through MCP — needs E2E crypto round-trip
+\`\`\`
+
+### \`watch\` — URL change watchers
+
+\`\`\`bash
+claudemesh watch list                # list active watches
+claudemesh watch remove <watch-id>
+# Watch creation currently via MCP \`mesh_watch\` — config-heavy
+\`\`\`
+
+### \`webhook\` — outbound HTTP triggers
+
+\`\`\`bash
+claudemesh webhook list              # list configured webhooks
+claudemesh webhook delete <name>
+# Webhook creation currently via MCP \`create_webhook\`
+\`\`\`
+
+### \`file\` — shared mesh files
+
+\`\`\`bash
+claudemesh file share <path>                       # upload to mesh (visible to all members)
+claudemesh file share <path> --to <peer>           # share with one peer (same-host fast path if co-located)
+claudemesh file share <path> --to <peer> --message "see line 42"
+claudemesh file share <path> --upload              # force network upload, skip same-host fast path
+claudemesh file get <file-id>                      # download by id (saves to ./<name>)
+claudemesh file get <file-id> --out /tmp/foo.bin   # download to explicit path
+claudemesh file list [search-query]                # browse mesh files
+claudemesh file status <file-id>                   # who has accessed
+claudemesh file delete <file-id>
+\`\`\`
+
+**Same-host fast path** (v0.6.0+): when \`--to <peer>\` resolves to a session
+running on the same hostname as you, \`claudemesh file share\` skips MinIO
+entirely and sends a DM with the absolute filepath. The receiver reads it
+directly off disk. No 50 MB cap, no upload latency, nothing in the bucket.
+Falls back to encrypted upload when the peer is remote, or always when
+\`--upload\` is set. Routes by session pubkey, so sibling sessions of the
+same member work without tripping the self-DM guard.
+
+**Network upload cap**: 50 MB. Same-host fast path has no cap.
+
+**\`--to\` accepts**: display name, member pubkey, session pubkey, or any
+≥8-char prefix of a pubkey. Prefer pubkey when multiple peers share a name.
+
+### \`mesh-mcp\` — call MCP servers other peers deployed to the mesh
+
+\`\`\`bash
+claudemesh mesh-mcp list             # which servers are deployed
+claudemesh mesh-mcp call <server> <tool> '<json-args>'
+claudemesh mesh-mcp catalog          # full catalog with schemas
+\`\`\`
+
+Mesh-deployed MCPs let peer X call a tool that peer Y maintains, without local install.
+
+### \`clock\` — mesh logical clock
+
+\`\`\`bash
+claudemesh clock                     # current state
+claudemesh clock set <speed>         # speed: 0=paused, 1=realtime, 60=60× faster
+claudemesh clock pause
+claudemesh clock resume
+\`\`\`
+
+Used for simulations / tests that need a controlled time axis shared across peers.
+
+### \`mesh\` — mesh-level introspection
+
+\`\`\`bash
+claudemesh info --json          # mesh overview: peers, groups, state keys, ...
+claudemesh stats --json         # per-peer activity counters
+claudemesh clock --json         # mesh logical clock (speed/tick/sim_time)
+claudemesh ping --json          # diagnostic — ws status, peer count, push buffer
+claudemesh peers --mesh X       # peers on a specific mesh
+\`\`\`
+
+### \`mesh management\` — admin ops
+
+\`\`\`bash
+claudemesh list                     # all your meshes
+claudemesh create <name>            # create a new mesh
+claudemesh share [email]            # generate invite link
+claudemesh disconnect <peer>        # soft disconnect (auto-reconnects)
+claudemesh kick <peer>              # kick (must rejoin manually)
+claudemesh ban <peer>               # ban (revoked, can't rejoin)
+claudemesh unban <peer>
+claudemesh bans                     # list banned members
+claudemesh delete <slug>            # delete a mesh
+claudemesh rename <slug> <name>
+\`\`\`
+
+### \`verify\` — safety numbers (Signal-style MITM detection)
+
+\`\`\`bash
+claudemesh verify <peer>            # show 6×5-digit fingerprint
+claudemesh verify <peer> --json
+\`\`\`
+
+Compare digits with the peer out-of-band (call, in person — not chat). If they match, the channel is not being intercepted.
+
+### \`auth\` — sign-in
+
+\`\`\`bash
+claudemesh login            # browser or paste-token
+claudemesh whoami           # current identity
+claudemesh logout
+\`\`\`
+
+## Common workflows
+
+### "Send a message to peer X with a confirmation"
+\`\`\`bash
+result=$(claudemesh send "X" "ping" --json)
+echo "$result" | jq -r '.messageId'
+\`\`\`
+
+### "List peers who are currently working"
+\`\`\`bash
+claudemesh peers --json name,status | jq '[.[] | select(.status == "working")]'
+\`\`\`
+
+### "Send to all reviewers"
+\`\`\`bash
+claudemesh send "@reviewers" "PR ready: <url>"
+\`\`\`
+
+### "Set my summary so peers know what I'm doing"
+\`\`\`bash
+claudemesh summary "drafting the auth migration spec"
+\`\`\`
+
+### "Schedule a daily ping at 9am"
+\`\`\`bash
+claudemesh remind "morning standup time" --cron "0 9 * * *"
+\`\`\`
+
+### "Check who I'm verified with"
+\`\`\`bash
+claudemesh verify <peer-name>
+# Compare the 6×5-digit number with peer over voice or in person.
+\`\`\`
+
+## Gotchas
+
+- **\`<peer-name>\` resolution is case-insensitive but exact-match only.** Don't fuzzy-match. If a peer is named "Mou-2", use that exact string. Use \`claudemesh peers --json name\` to confirm.
+- **\`@group\` requires the leading \`@\`.** Without it, claudemesh treats the string as a peer name lookup.
+- **\`*\` means broadcast.** Use carefully — it goes to every peer on the mesh.
+- **\`--priority now\` bypasses busy gates** (peers in DND still receive). Use only for genuine interruptions.
+- **\`claudemesh launch\` writes a per-session config to a tmpdir.** Don't edit \`~/.claudemesh/config.json\` while a session is running — changes won't take effect until the next launch.
+- **The \`claudemesh mcp\` server registers ZERO tools.** Never search ToolSearch for \`mcp__claudemesh__*\` — there are none. All operations go through Bash + CLI.
+- **Soft-deprecated MCP tools (1.1.x).** If you previously called \`mcp__claudemesh__send_message\`, use \`claudemesh send\` via Bash instead. The deprecated tools still work in 1.x but print a stderr warning. They're removed in 2.0.
+- **Field aliases in \`--json\`.** \`name\` resolves to \`displayName\`. Other aliases may be added in future versions; check \`--json\` output to confirm field names.
+- **\`claudemesh send\` to a name that's not online** errors with the list of online peers. Use \`claudemesh peers --json\` first if uncertain.
+- **The \`--mesh <slug>\` flag is required when the user has multiple meshes joined.** Without it, the CLI either picks the first mesh deterministically or shows an interactive picker (depending on context).
+
+## Behavioral conventions
+
+- **Confirm before destructive ops** (\`kick\`, \`ban\`, \`delete\`, \`forget\`). Show the user what you're about to do.
+- **Preview peer-name matches before sending** when the name is ambiguous. \`claudemesh peers --json name,pubkey | jq\` is the right tool for disambiguation.
+- **Don't broadcast (\`*\`) for trivial messages.** It pings every peer mid-task. Prefer DM or \`@group\`.
+- **Don't poll \`inbox\`.** Messages are pushed via \`<channel source="claudemesh">\` automatically. Only call \`inbox --json\` if you suspect a buffered message is stuck.
+- **Echo the messageId in JSON contexts** so the caller can \`msg-status\` it later.
+
+## Related
+
+- Spec: \`.artifacts/specs/2026-05-02-architecture-north-star.md\` (architecture rationale)
+- Source: \`~/Desktop/claudemesh/apps/cli/\`
+- Broker: \`wss://ic.claudemesh.com/ws\`
+- Dashboard: \`https://claudemesh.com/dashboard\`
+`;
+var init_SKILL = () => {};
+
+// src/commands/skill.ts
+var exports_skill = {};
+__export(exports_skill, {
+  runSkill: () => runSkill
+});
+async function runSkill() {
+  process.stdout.write(SKILL_default);
+  if (!SKILL_default.endsWith(`
+`))
+    process.stdout.write(`
+`);
+  return EXIT.SUCCESS;
+}
+var init_skill = __esm(() => {
+  init_SKILL();
+  init_exit_codes();
+});
+
+// src/commands/file.ts
+var exports_file = {};
+__export(exports_file, {
+  runFileShare: () => runFileShare,
+  runFileGet: () => runFileGet
+});
+import { hostname as osHostname } from "node:os";
+import { resolve as resolvePath, basename, dirname as dirname6 } from "node:path";
+import { statSync as statSync6, existsSync as existsSync20, writeFileSync as writeFileSync11, mkdirSync as mkdirSync7 } from "node:fs";
+function emitJson2(data) {
+  console.log(JSON.stringify(data, null, 2));
+}
+function formatSize(bytes) {
+  if (bytes < 1024)
+    return `${bytes} B`;
+  if (bytes < 1024 * 1024)
+    return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+async function runFileShare(filePath, opts) {
+  if (!filePath) {
+    render.err('Usage: claudemesh file share <path> [--to <peer>] [--tags a,b] [--message "..."] [--upload]');
+    return EXIT.INVALID_ARGS;
+  }
+  const absPath = resolvePath(filePath);
+  if (!existsSync20(absPath)) {
+    render.err(`File not found: ${absPath}`);
+    return EXIT.INVALID_ARGS;
+  }
+  const stat = statSync6(absPath);
+  if (!stat.isFile()) {
+    render.err(`Not a regular file: ${absPath}`);
+    return EXIT.INVALID_ARGS;
+  }
+  const tags = opts.tags ? opts.tags.split(",").map((t) => t.trim()).filter(Boolean) : [];
+  return await withMesh({ meshSlug: opts.mesh ?? null }, async (client, mesh) => {
+    if (opts.to && !opts.upload) {
+      const peers = await client.listPeers();
+      const myHost = osHostname();
+      const target = peers.find((p) => {
+        if (!p.hostname || p.hostname !== myHost)
+          return false;
+        return p.displayName === opts.to || p.memberPubkey === opts.to || p.pubkey === opts.to || typeof opts.to === "string" && opts.to.length >= 8 && p.pubkey.startsWith(opts.to);
+      });
+      if (target) {
+        const note = opts.message ? `
+${opts.message}` : "";
+        const body = `\uD83D\uDCCE file://${absPath} (${formatSize(stat.size)} · same host, no upload)${note}`;
+        const result = await client.send(target.pubkey, body, "next");
+        if (!result.ok) {
+          render.err(`Send failed: ${result.error ?? "unknown"}`);
+          return EXIT.NETWORK_ERROR;
+        }
+        if (opts.json) {
+          emitJson2({ mode: "local", path: absPath, to: target.displayName, hostname: myHost, sizeBytes: stat.size });
+        } else {
+          render.ok(`shared ${bold(basename(absPath))} ${dim(`(${formatSize(stat.size)})`)} → ${green(target.displayName)} ${dim("[same host, no upload]")}`);
+        }
+        return EXIT.SUCCESS;
+      }
+    }
+    const fileId = await client.uploadFile(absPath, mesh.meshId, mesh.memberId, {
+      name: basename(absPath),
+      tags,
+      persistent: true,
+      targetSpec: opts.to
+    });
+    if (opts.to) {
+      const note = opts.message ? `
+${opts.message}` : "";
+      const body = `\uD83D\uDCCE ${basename(absPath)} (${formatSize(stat.size)})
+claudemesh file get ${fileId}${note}`;
+      await client.send(opts.to, body, "next");
+    }
+    if (opts.json) {
+      emitJson2({ mode: "upload", fileId, name: basename(absPath), sizeBytes: stat.size, to: opts.to ?? null });
+    } else {
+      render.ok(`uploaded ${bold(basename(absPath))} ${dim(`(${formatSize(stat.size)})`)} ${dim("· id=" + fileId.slice(0, 12))}`);
+      if (opts.to)
+        render.info(dim(`  notified ${opts.to}`));
+      else
+        render.info(dim(`  retrieve: claudemesh file get ${fileId}`));
+    }
+    return EXIT.SUCCESS;
+  });
+}
+async function runFileGet(fileId, opts) {
+  if (!fileId) {
+    render.err("Usage: claudemesh file get <file-id> [--out <path>]");
+    return EXIT.INVALID_ARGS;
+  }
+  return await withMesh({ meshSlug: opts.mesh ?? null }, async (client) => {
+    const meta = await client.getFile(fileId);
+    if (!meta) {
+      render.err(`File not found or not accessible: ${fileId}`);
+      return EXIT.NOT_FOUND;
+    }
+    const res = await fetch(meta.url, { signal: AbortSignal.timeout(60000) });
+    if (!res.ok) {
+      render.err(`Download failed: HTTP ${res.status}`);
+      return EXIT.NETWORK_ERROR;
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    const outPath = opts.out ? resolvePath(opts.out) : resolvePath(process.cwd(), meta.name);
+    mkdirSync7(dirname6(outPath), { recursive: true });
+    writeFileSync11(outPath, buf);
+    if (opts.json) {
+      emitJson2({ fileId, name: meta.name, savedTo: outPath, sizeBytes: buf.length });
+    } else {
+      render.ok(`saved ${bold(meta.name)} ${dim(`(${formatSize(buf.length)})`)} → ${dim(outPath)}`);
+    }
+    return EXIT.SUCCESS;
+  });
+}
+var MAX_FILE_BYTES;
+var init_file = __esm(() => {
+  init_connect();
+  init_render();
+  init_styles();
+  init_exit_codes();
+  MAX_FILE_BYTES = 50 * 1024 * 1024;
+});
+
 // ../../packages/sdk/dist/crypto.js
 var require_crypto = __commonJS((exports) => {
   var __importDefault = exports && exports.__importDefault || function(mod) {
@@ -11716,7 +12471,7 @@ __export(exports_bridge, {
   runBridge: () => runBridge,
   bridgeConfigTemplate: () => bridgeConfigTemplate
 });
-import { readFileSync as readFileSync14, existsSync as existsSync20 } from "node:fs";
+import { readFileSync as readFileSync14, existsSync as existsSync21 } from "node:fs";
 function parseConfig(text) {
   const trimmed = text.trim();
   if (trimmed.startsWith("{"))
@@ -11760,7 +12515,7 @@ async function runBridge(configPath) {
     render.err("Usage: claudemesh bridge run <config.yaml>");
     return EXIT.INVALID_ARGS;
   }
-  if (!existsSync20(configPath)) {
+  if (!existsSync21(configPath)) {
     render.err(`config file not found: ${configPath}`);
     return EXIT.NOT_FOUND;
   }
@@ -12737,7 +13492,7 @@ var init_definitions = __esm(() => {
 
 // src/services/bridge/server.ts
 import { createServer as createServer2 } from "node:net";
-import { mkdirSync as mkdirSync7, unlinkSync as unlinkSync2, existsSync as existsSync21, chmodSync as chmodSync5 } from "node:fs";
+import { mkdirSync as mkdirSync8, unlinkSync as unlinkSync2, existsSync as existsSync22, chmodSync as chmodSync5 } from "node:fs";
 async function resolveTarget2(client, to) {
   if (to.startsWith("@") || to === "*" || /^[0-9a-f]{64}$/i.test(to)) {
     return { ok: true, spec: to };
@@ -12851,10 +13606,10 @@ function handleConnection(socket, client) {
 function startBridgeServer(client) {
   const path = socketPath(client.meshSlug);
   const dir = socketDir();
-  if (!existsSync21(dir)) {
-    mkdirSync7(dir, { recursive: true, mode: 448 });
+  if (!existsSync22(dir)) {
+    mkdirSync8(dir, { recursive: true, mode: 448 });
   }
-  if (existsSync21(path)) {
+  if (existsSync22(path)) {
     try {
       unlinkSync2(path);
     } catch {}
@@ -13005,11 +13760,11 @@ If the channel meta contains \`subtype: reminder\`, this is a scheduled reminder
 | remember(content, tags?) | Store persistent knowledge with optional tags. |
 | recall(query) | Full-text search over mesh memory. |
 | forget(id) | Soft-delete a memory entry. |
-| share_file(path, name?, tags?) | Share a persistent file with the mesh. |
-| get_file(id, save_to) | Download a shared file to a local path. |
-| list_files(query?, from?) | Find files shared in the mesh. |
-| file_status(id) | Check who has accessed a file. |
-| delete_file(id) | Remove a shared file from the mesh. |
+| claudemesh file share <path> [--to peer] [--tags a,b] | Share a file with the mesh, or DM it to a specific peer. Same-host fast path: when --to matches a peer on this machine, sends an absolute filepath instead of uploading (no MinIO round-trip). |
+| claudemesh file get <id> [--out path] | Download a shared file by id. |
+| claudemesh file list [query] | Find files shared in the mesh. |
+| claudemesh file status <id> | Check who has accessed a file. |
+| claudemesh file delete <id> | Remove a shared file from the mesh. |
 | vector_store(collection, text, metadata?) | Store embedding in per-mesh Qdrant collection. |
 | vector_search(collection, query, limit?) | Semantic search over stored embeddings. |
 | vector_delete(collection, id) | Remove an embedding. |
@@ -14320,6 +15075,7 @@ Topic  (conversation scope, v0.2.0)
   claudemesh topic tail <topic>    live SSE tail [--limit --forward-only]
   claudemesh topic post <t> <msg>  encrypted REST post (v0.3.0 v2) [--reply-to <id>]
   claudemesh send "#topic" "msg"   send to a topic (WS path, v1 plaintext)
+  claudemesh skill                 print the bundled SKILL.md to stdout
   claudemesh me                    cross-mesh workspace overview (v0.4.0)
   claudemesh me topics             cross-mesh topic list [--unread]
   claudemesh me notifications      cross-mesh @-mentions [--all] [--since=ISO]
@@ -14355,6 +15111,8 @@ Platform
   claudemesh vault list|delete                         encrypted secrets
   claudemesh watch list|remove                         URL change watchers
   claudemesh webhook list|delete                       outbound HTTP triggers
+  claudemesh file share <path> [--to peer]             upload (or local-host fast path if --to matches)
+  claudemesh file get <id> [--out path]                download by id
   claudemesh file list|status|delete                   shared mesh files
   claudemesh mesh-mcp list|call|catalog                deployed mesh-MCP servers
   claudemesh clock set|pause|resume                    mesh logical clock
@@ -14960,7 +15718,10 @@ async function main() {
     case "skill": {
       const sub = positionals[0];
       const f = { mesh: flags.mesh, json: !!flags.json };
-      if (sub === "list") {
+      if (!sub) {
+        const { runSkill: runSkill2 } = await Promise.resolve().then(() => (init_skill(), exports_skill));
+        process.exit(await runSkill2());
+      } else if (sub === "list") {
         const { runSkillList: runSkillList2 } = await Promise.resolve().then(() => (init_platform_actions(), exports_platform_actions));
         process.exit(await runSkillList2({ ...f, query: positionals[1] }));
       } else if (sub === "get") {
@@ -14970,7 +15731,8 @@ async function main() {
         const { runSkillRemove: runSkillRemove2 } = await Promise.resolve().then(() => (init_platform_actions(), exports_platform_actions));
         process.exit(await runSkillRemove2(positionals[1] ?? "", f));
       } else {
-        console.error("Usage: claudemesh skill <list|get|remove>");
+        console.error(`Usage: claudemesh skill              (print bundled SKILL.md)
+       claudemesh skill <list|get|remove>`);
         process.exit(EXIT.INVALID_ARGS);
       }
       break;
@@ -15023,7 +15785,19 @@ async function main() {
     case "file": {
       const sub = positionals[0];
       const f = { mesh: flags.mesh, json: !!flags.json };
-      if (sub === "list") {
+      if (sub === "share") {
+        const { runFileShare: runFileShare2 } = await Promise.resolve().then(() => (init_file(), exports_file));
+        process.exit(await runFileShare2(positionals[1] ?? "", {
+          ...f,
+          to: flags.to,
+          tags: flags.tags,
+          message: flags.message,
+          upload: !!flags.upload
+        }));
+      } else if (sub === "get") {
+        const { runFileGet: runFileGet2 } = await Promise.resolve().then(() => (init_file(), exports_file));
+        process.exit(await runFileGet2(positionals[1] ?? "", { ...f, out: flags.out }));
+      } else if (sub === "list") {
         const { runFileList: runFileList2 } = await Promise.resolve().then(() => (init_platform_actions(), exports_platform_actions));
         process.exit(await runFileList2({ ...f, query: positionals[1] }));
       } else if (sub === "status") {
@@ -15033,7 +15807,7 @@ async function main() {
         const { runFileDelete: runFileDelete2 } = await Promise.resolve().then(() => (init_platform_actions(), exports_platform_actions));
         process.exit(await runFileDelete2(positionals[1] ?? "", f));
       } else {
-        console.error("Usage: claudemesh file <list|status|delete>");
+        console.error("Usage: claudemesh file <share|get|list|status|delete>");
         process.exit(EXIT.INVALID_ARGS);
       }
       break;
@@ -15315,4 +16089,4 @@ main().catch((err) => {
   process.exit(EXIT.INTERNAL_ERROR);
 });
 
-//# debugId=E54B2ED5C4F2639E64756E2164756E21
+//# debugId=4702C484C802D1AB64756E2164756E21