switchroom 0.5.0

package/skills/switchroom-architecture/telegram.md

@@ -0,0 +1,94 @@
+# Telegram Plugin
+
+Switchroom ships an enhanced `switchroom-telegram` MCP plugin that replaces the official marketplace plugin. It is the default — no configuration needed.
+
+## 10 MCP tools
+
+| Tool | What it does |
+|------|-------------|
+| `reply` | Send text, photos, or documents. Supports threading, topic routing, file attachments. |
+| `stream_reply` | Edit a single message in place as work progresses (~1/sec throttle). Use for long tasks to avoid chat spam. |
+| `react` | Add emoji reactions to messages (Telegram whitelist: 👍 👎 ❤️ 🔥 👀 🎉 etc). |
+| `edit_message` | Update a previously sent message. Edits are silent (no push notification). |
+| `delete_message` | Remove a bot-sent message (48h Telegram API limit). |
+| `forward_message` | Quote/resurface earlier messages with thread support. |
+| `pin_message` | Pin important outputs (requires bot admin). |
+| `send_typing` | Show typing indicator (5s auto-expire). Use during long operations. |
+| `download_attachment` | Fetch files attached to inbound messages. |
+| `get_recent_messages` | Query SQLite history buffer with pagination and thread filtering. |
+
+## Emoji status lifecycle
+
+The plugin automatically reacts to inbound messages with a lifecycle progression:
+
+```
+👀 queued → 🤔 thinking → 👨‍💻 tool use → 🔥 streaming → 👍 done
+```
+
+Stall watchdogs: `🥱` at 30s idle, `😨` at 90s — so the user always knows the agent is alive.
+
+Tool-specific reactions:
+- `👨‍💻` for Bash/Edit/Write
+- `⚡` for web search/fetch
+
+## Message history
+
+A local SQLite database (`telegram/history.db`) records every message. After a Claude Code restart, the agent calls `get_recent_messages` to recover context instead of asking "what were we doing?"
+
+History survives process restarts and session resets.
+
+## stream_reply pattern
+
+For tasks taking more than ~5 seconds:
+
+```
+1. stream_reply(chat_id, "Reading the file...", done=false)  ← creates message
+2. stream_reply(chat_id, "Reading the file...\nParsing...", done=false)  ← edits in place
+3. stream_reply(chat_id, "Done! Here's the result: ...", done=true)  ← locks
+```
+
+Pass the **full current text** on each call (not a delta). The plugin throttles to ~1/sec.
+
+After `done=true`, send a separate `reply` if you want a push notification to the user's device (edits are silent).
+
+## Formatting
+
+Markdown is auto-converted to Telegram HTML:
+- `**bold**` → `<b>bold</b>`
+- `` `code` `` → `<code>code</code>`
+- ` ```blocks``` ` → `<pre><code>...</code></pre>`
+- Smart chunking preserves tag balance across Telegram's 4096-char limit
+
+Formats: `html` (default), `markdownv2`, `text`
+
+## Access control
+
+`telegram/access.json` per agent:
+- **DM policy**: allowlist of user IDs
+- **Group policy**: per-group settings (requireMention, allowFrom)
+- **Topic filtering**: scope agent to specific forum topics
+
+## Forum topics
+
+Messages from forum topics carry `message_thread_id`. The plugin routes replies back to the originating topic automatically. The agent doesn't need to pass `message_thread_id` explicitly.
+
+## Opting out
+
+To use the official upstream plugin for a specific agent:
+```yaml
+agents:
+  basic:
+    channels:
+      telegram:
+        plugin: official
+```
+
+## Env vars
+
+| Var | Source | Purpose |
+|-----|--------|---------|
+| `SWITCHROOM_TG_FORMAT` | `channels.telegram.format` | Default reply format |
+| `SWITCHROOM_TG_RATE_LIMIT_MS` | `channels.telegram.rate_limit_ms` | Min delay between outgoing messages |
+| `TELEGRAM_STATE_DIR` | Auto-set by scaffold | Path to `telegram/` dir |
+| `SWITCHROOM_AGENT_NAME` | Auto-set by scaffold | Agent name (used for self-restart detection) |
+| `SWITCHROOM_CONFIG` | Auto-set by scaffold | Path to switchroom.yaml |

package/skills/switchroom-cli/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: switchroom-cli
+description: "Run switchroom CLI operations on existing agents: logs, update, restart, version, config inspection, scheduled tasks, and Telegram plugin reference. Use when the user wants to: show logs (\"logs\", \"what happened\", \"check the journal\", \"why did it crash\"); update agents (\"update\", \"pull latest\", \"get new code\", \"upgrade\"); restart agents (\"restart\", \"reboot\", \"bounce\", \"kick\", \"it's stuck\"); check what's running (\"version\", \"what sha\", \"are agents up\", \"health summary\"); apply config changes (\"apply\", \"sync my config\", \"I just edited switchroom.yaml\"); inspect an agent's effective config (\"what model is X using\", \"how is <agent> configured\", \"show the cascade\"); list scheduled tasks (\"cron\", \"timers\", \"what runs automatically\", \"scheduled tasks\"); or ask about Telegram-plugin features (\"what MCP tools does the bot have\", \"how does reply work\"). Do NOT use for adding/removing agents (switchroom-manage), bootstrapping switchroom from scratch (switchroom-install), or \"something is broken\" diagnostics (switchroom-health).
+allowed-tools: Bash(switchroom *) Bash(systemctl --user *) Bash(journalctl *)
+---
+
+# Switchroom CLI operations
+
+This skill is the reference for running `switchroom` CLI commands against existing agents. Each section below is triggered by a distinct user intent — jump to the relevant one rather than walking top-to-bottom.
+
+**Three commands to know:**
+- `switchroom update` — picks up new code (pull, rebuild, reconcile, restart)
+- `switchroom restart [agent]` — bounces a stuck or wedged agent
+- `switchroom version` — shows what's running (versions + health summary)
+
+**Prerequisite:** the `switchroom` CLI must be on `PATH`. If it isn't, direct the user to the `switchroom-install` skill.
+
+---
+
+## Logs — "show me the logs", "what happened", "why did it crash"
+
+Fetch recent journal output when the user wants to see what an agent did or is debugging a specific crash.
+
+### Step 1 — Identify the agent
+
+If the user didn't name one, ask: *"Which agent do you want logs for?"* Then list available agents:
+
+```bash
+switchroom agent list
+```
+
+### Step 2 — Tail the logs
+
+Default is the last 20 lines. User can specify a number. Use the CLI if available; fall back to `journalctl` when it's not:
+
+```bash
+switchroom agent logs <name> [--lines 50]
+# or, when switchroom CLI isn't reachable:
+journalctl --user -u switchroom-<name>.service -n 50 --no-pager
+```
+
+### Step 3 — Present output
+
+Include the last ~20 lines verbatim, then summarise what you see (crash, stall, normal chatter). If the user asked "why did it crash" and you don't see a clear cause, say so and offer `/doctor` as the next step.
+
+---
+
+## Update — "update", "pull latest", "get new code", "upgrade"
+
+Pull the latest switchroom source, rebuild the CLI binary, reconcile all agents, and restart everything.
+
+```bash
+switchroom update
+```
+
+This is the single command for "running the latest code". It:
+1. `git pull` the switchroom repo
+2. Reinstalls deps if package.json changed
+3. Regenerates systemd units
+4. Reconciles all agent config from switchroom.yaml
+5. Restarts all agents that need it
+6. Prints a one-line health summary when done
+
+**Idempotent**: running twice = first does work, second is a fast no-op.
+
+---
+
+## Restart — "restart", "reboot", "bounce", "it's stuck"
+
+Restart one agent or all. Also covers "refresh", "kick", "kill and restart", "stop and start".
+
+### Step 1 — Identify the agent
+
+If the user didn't name one, ask which. Accept `all` or no argument as "all agents".
+
+### Step 2 — Run the restart
+
+```bash
+# Restart a specific agent (drains in-flight turn by default):
+switchroom restart <name>
+
+# Restart all agents:
+switchroom restart
+
+# Skip drain — SIGTERM immediately:
+switchroom restart <name> --force
+```
+
+The `switchroom restart` top-level command reconciles + restarts and prints the health summary. It uses drain semantics by default (waits up to 60s for an in-flight turn to complete before cycling).
+
+For the lower-level per-agent restart without reconcile, `switchroom agent restart <name>` is also available.
+
+### Step 3 — Confirm
+
+Report the outcome. If the agent is being restarted via Telegram (`/restart` handler), the user will see a `🔄 Restarting <name>…` ack followed by a `🎛️ Switchroom restarted — ready` message. Don't double-post.
+
+---
+
+## Version / health summary — "version", "what sha", "are agents up", "health check"
+
+Show switchroom version, claude-code version, and the running status of all agents.
+
+```bash
+switchroom version
+```
+
+Output format:
+```
+✓ claude-code 2.1.119
+✓ switchroom 0.3.0 / 7278044 (clean)
+✓ klanker → up 5m, on 7278044
+✓ gymbro → up 4h, on 7278044
+✓ foreman → up 2d, on 7278044
+```
+
+No side effects. Safe to run at any time.
+
+---
+
+## Config inspection — "what model is X using", "show config for <agent>"
+
+Surface the resolved effective config for a specific agent. Use for "how is X configured", "what tools does X have", or cascade-resolution questions.
+
+### Step 1 — Pick the right inspector
+
+For a high-level view (model, profile, topic, status, uptime):
+
+```bash
+switchroom agent list --json
+```
+
+For the full merged settings file (tools, hooks, MCP servers):
+
+```bash
+cat ~/.switchroom/agents/<name>/.claude/settings.json
+```
+
+For the **exact prompt + system message** an agent sends Claude on its next turn:
+
+```bash
+switchroom debug turn <name>
+```
+
+For the rendered workspace bootstrap block (CLAUDE.md, SOUL.md, skills wiring):
+
+```bash
+switchroom workspace render <name>
+```
+
+`debug turn` and `workspace render` are the authoritative answers when the user asks "why is X behaving this way" or "what is X actually being told".
+
+### Step 2 — Explain the cascade
+
+Agent config resolves through `defaults → extends profile → agent-specific`, with later keys winning. If the user asks *why* a value is set the way it is, walk them through which layer contributed it.
+
+---
+
+## Auth — "share my Pro account across agents", "auth verbs", "who's logged into what"
+
+Two layers coexist. **Use the new account model when an operator wants one OAuth flow to drive multiple agents.** The legacy per-agent slot model still works for first-time agent auth.
+
+### Per-agent (slot model) — first-time agent auth + the existing Telegram /auth flow
+
+```bash
+switchroom auth login <agent>          # interactive OAuth, writes to <agent>/.claude/.credentials.json
+switchroom auth status                 # one row per agent
+switchroom auth list <agent>           # show the agent's slot pool
+switchroom auth use <agent> <slot>     # switch the agent's active slot
+switchroom auth refresh-tick           # cron entrypoint for the legacy refresh loop
+```
+
+### Anthropic accounts (new model — see `reference/share-auth-across-the-fleet.md`)
+
+The Anthropic account is the unit of authentication. One account → many agents. Storage at `~/.switchroom/accounts/<label>/`. Per-agent `.credentials.json` becomes a passive mirror that the broker keeps in sync.
+
+```bash
+# Lift an already-authenticated agent's credentials into a global account
+switchroom auth account add <label> --from-agent <agent>
+
+# Or import from a credentials.json file you already have
+switchroom auth account add <label> --from-credentials <path>
+
+switchroom auth account list           # accounts + which agents use each + health
+switchroom auth account rm <label>     # refused while any agent is enabled
+
+# Wire an account to one or more agents (writes agents.<name>.auth.accounts in switchroom.yaml + immediate fanout)
+switchroom auth enable <label> <agent...>
+switchroom auth disable <label> <agent...>
+
+# Single account-refresh tick: refresh expiring tokens, fan out to enabled agents
+switchroom auth refresh-accounts [--json]
+```
+
+### Schema
+
+```yaml
+agents:
+  foo:
+    auth:
+      accounts: [work-pro, personal-max]   # ordered priority — first non-quota-exhausted wins
+```
+
+When unset, the agent uses the legacy per-agent slot path. The two are not mutually exclusive during the transition.
+
+### Telegram parity
+
+Every CLI verb above has a Telegram twin:
+
+```
+/auth account add <label> [--from-agent <name>]
+/auth account list
+/auth account rm <label>
+/auth enable <label> [agents...]    — defaults to the current agent
+/auth disable <label> [agents...]   — defaults to the current agent
+```
+
+`/auth login`, `/auth code`, `/auth list <agent>` etc. continue to work for the per-agent path.
+
+### When auth-related questions come in
+
+- "I want one Pro/Max subscription on multiple agents" → account model. Walk them through the bootstrap (`auth login` first agent → `auth account add --from-agent` → `auth enable` others).
+- "An agent's auth expired" → check `switchroom auth account list` first. If the account is healthy but the agent isn't getting it, the broker fanout may be stale — `switchroom auth refresh-accounts` forces a tick.
+- "I hit a quota" → `switchroom auth account list` shows quota-exhausted accounts; auto-fallback handles it if the agent has multiple accounts in priority order.
+
+---
+
+## Scheduled tasks — "what cron runs", "show me the timers"
+
+List cron jobs and scheduled tasks.
+
+### Step 1 — Show live timers
+
+```bash
+systemctl --user list-timers --all | grep switchroom
+```
+
+### Step 2 — Show declared schedule entries
+
+From `switchroom.yaml`, the `schedule:` array under each agent specifies `cron` + `prompt` + optional `model`. Read the relevant agent block and enumerate the entries with their next-fire times.
+
+---
+
+## Telegram plugin reference — "what MCP tools", "how does reply work"
+
+The `switchroom-telegram` plugin is an enhanced fork of the official Telegram MCP plugin and is the default for all switchroom agents. It exposes **10 MCP tools** (all prefixed `mcp__switchroom-telegram__`):
+
+| Tool | Purpose |
+|---|---|
+| `reply` | Send a text/photo message, with optional `reply_to` for threaded quotes |
+| `stream_reply` | Incrementally stream a long reply (edits the same message as tokens arrive) |
+| `react` | Emoji reaction on an inbound or outbound message |
+| `edit_message` | Modify an earlier bot message's text |
+| `delete_message` | Remove an earlier bot message |
+| `forward_message` | Forward a message from another chat |
+| `pin_message` | Pin a message in the current chat |
+| `send_typing` | Show the "typing…" indicator |
+| `download_attachment` | Save a Telegram file attachment to the agent's inbox |
+| `get_recent_messages` | Fetch recent history for context |
+
+Additional features:
+- **Status reactions** — 👀 queued → 🤔 thinking → 👨‍💻 tool → 🔥 streaming → 👍 done
+- **Progress cards** — pinned, live-updating tool-step summary
+- **SQLite history** — enables quote-reply defaults
+- **PI-safe envelope** — inbound text wrapped in `<channel source="telegram">` for prompt-injection safety
+- **Inline approvals** — tool permissions surface as ✅/❌ buttons or via `/approve` `/deny` `/pending`
+- **Slash commands** — `/new`, `/reset`, `/approve`, `/deny`, `/pending`, `/restart`, `/update`, `/version`, `/logs`, `/doctor`, `/auth`, `/switchroomhelp` (see `TELEGRAM_MENU_COMMANDS` in `telegram-plugin/welcome-text.ts`)
+- **`/auth`** — full auth surface inside Telegram: per-agent slot verbs (`login`/`reauth`/`code`/`add`/`use`/`list`/`rm`) AND account-shaped verbs (`account add`/`account list`/`account rm`/`enable`/`disable`). The account verbs implement the new "one Pro account, many agents" model — see the **Auth** section above.
+- **Access control** — `dmPolicy: pairing | allowlist | disabled` per agent
+
+---
+
+## Rule of thumb
+
+If the user is asking **"do X"**, this is your skill. If they're asking **"why is X broken"**, switch to `switchroom-health`. If they're asking **"how do I add/remove an agent"**, switch to `switchroom-manage`. If they're new and don't have switchroom yet, switch to `switchroom-install`.

package/skills/switchroom-health/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: switchroom-health
+description: Runs a health check and diagnostics on the switchroom setup. Use when the user says 'my agent keeps failing', 'my agents are broken', "what's wrong with my agents", 'agent keeps crashing', 'health check', 'diagnose', 'troubleshoot', "something's wrong", 'can you check my setup', or wants to verify everything is working correctly. Prefer this over logs when the user is reporting a generic failure and wants to know *what* is wrong, not *why* a specific crash happened.
+---
+
+# Agent Health Diagnostics
+
+When the user reports an agent failing, says their agents are broken, asks "what's wrong with my agent(s)", mentions errors, asks to diagnose, or asks to troubleshoot the setup, run this skill to perform a full health check. This skill answers the *what's wrong* question by checking the whole stack (CLI, auth, units, files, memory); defer to `switchroom-cli` (logs section) only when the user specifically asks for logs of a particular crash.
+
+## Step 1 — Run switchroom doctor
+
+```bash
+switchroom doctor --json 2>/dev/null || switchroom doctor 2>/dev/null || echo "switchroom doctor unavailable"
+```
+
+If `switchroom doctor` doesn't exist, fall back to manual checks (Step 2).
+
+## Step 2 — Manual checks (if doctor unavailable)
+
+Run these diagnostics with Bash:
+
+```bash
+# Check switchroom CLI version
+switchroom --version 2>/dev/null || echo "FAIL: switchroom not found"
+
+# Check auth status (per-agent legacy view)
+switchroom auth status 2>/dev/null || echo "FAIL: auth check failed"
+
+# Check Anthropic accounts (new model — see reference/share-auth-across-the-fleet.md)
+# Shows accounts at ~/.switchroom/accounts/<label>/, which agents use each,
+# and per-account health (healthy / quota-exhausted / expired / missing-refresh-token).
+switchroom auth account list 2>/dev/null || echo "INFO: no Anthropic accounts configured (legacy per-agent slot model in use)"
+
+# Check systemd units
+systemctl --user list-units "switchroom-*" --no-pager 2>/dev/null || echo "no switchroom systemd units"
+
+# Check for failed units
+systemctl --user list-units "switchroom-*" --state=failed --no-pager 2>/dev/null
+
+# Check MCP config exists for each agent
+for dir in ~/.switchroom/agents/*/; do
+  name=$(basename "$dir")
+  if [ -f "$dir/.mcp.json" ]; then
+    echo "OK: $name .mcp.json present"
+  else
+    echo "WARN: $name missing .mcp.json"
+  fi
+  if [ -f "$dir/start.sh" ]; then
+    echo "OK: $name start.sh present"
+  else
+    echo "FAIL: $name missing start.sh"
+  fi
+done
+
+# Check bot tokens are set (not empty)
+for dir in ~/.switchroom/agents/*/; do
+  name=$(basename "$dir")
+  if grep -q "TELEGRAM_BOT_TOKEN=" "$dir/start.sh" 2>/dev/null; then
+    token=$(grep "TELEGRAM_BOT_TOKEN=" "$dir/start.sh" | head -1 | cut -d= -f2- | tr -d '"')
+    if [ -z "$token" ] || [ "$token" = "vault:telegram-bot-token" ]; then
+      echo "WARN: $name bot token may not be resolved"
+    else
+      echo "OK: $name bot token set"
+    fi
+  fi
+done
+
+# Check Hindsight MCP reachable
+switchroom memory search "test" --agent assistant 2>/dev/null && echo "OK: memory search works" || echo "WARN: memory search failed"
+```
+
+## Step 3 — Interpret and report
+
+For each check, report:
+- **PASS** — green light, all good
+- **WARN** — something unusual but not necessarily broken
+- **FAIL** — action required
+
+Group findings by category:
+1. **CLI & Auth** — switchroom installed, authenticated
+2. **Systemd units** — services running, no failed units
+3. **Agent files** — start.sh, .mcp.json, settings.json present
+4. **Bot tokens** — Telegram credentials resolved
+5. **Memory backend** — Hindsight reachable
+
+## Step 4 — Suggest fixes
+
+For common failures, give the exact fix:
+
+| Problem | Fix |
+|---------|-----|
+| `switchroom: command not found` | `npm install -g switchroom` |
+| Per-agent auth expired (slot model) | `switchroom auth login <agent>` |
+| Account expired (new model — `auth account list` shows red ✗) | `switchroom auth refresh-accounts` (one tick); if no refresh-token, the account needs re-adding |
+| Account quota-exhausted (yellow ⊘ in `auth account list`) | Auto-fallback handles it if the agent has multiple accounts; otherwise wait for the reset window or `switchroom auth enable <other-account> <agent>` |
+| Unit failed | `systemctl --user reset-failed switchroom-<name>`, then restart |
+| Missing .mcp.json | `switchroom update` (full reconcile + restart) or `switchroom agent reconcile <name>` (targeted) |
+| Bot token unresolved | Check vault: `switchroom vault list` |
+| Memory unreachable | Check Hindsight MCP server is running |
+
+End with a tl;dr: "X issues found — Y critical, Z warnings." If all green: "All health checks passed."

package/skills/switchroom-install/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: switchroom-install
+description: Install switchroom and its dependencies (bun, node, docker, tmux, claude CLI) on a fresh machine. Use for onboarding and first-time setup — when the user says 'install switchroom on this machine', 'set up switchroom for the first time', 'bootstrap switchroom from scratch', 'get switchroom running', 'how do I get started with switchroom', "I'm new to switchroom, where do I begin", or asks about switchroom dependencies or prerequisites. This is the onboarding entry point, not for managing existing agents.
+---
+
+# Install Switchroom
+
+When the user asks to install, set up, bootstrap, or get started with switchroom — or when they're new to switchroom and want to know where to begin — walk them through this flow. Switchroom turns a Linux server + their Claude Pro/Max subscription into always-on Claude Code agents reachable from Telegram.
+
+Switchroom's dependencies are: **bun** (TypeScript runtime), **node** 22+ (via nvm), **docker** (for plugins), **tmux** (for agent sessions), and the **claude** Code CLI (authenticates against Claude Pro/Max). Always enumerate these explicitly when the user asks about dependencies or prerequisites.
+
+## Step 0 — Detect existing install
+
+Before doing anything, check whether switchroom is already installed:
+
+```bash
+command -v switchroom && switchroom --version 2>/dev/null
+```
+
+If switchroom is present, tell the user it's already installed and then — regardless — run the dependency audit in Step 2 so they see the state of **bun**, **node**, **docker**, **tmux**, and **claude**. Users who ask "install switchroom and its dependencies" want to see the dependency inventory even when switchroom itself is already installed. After the audit, offer `switchroom setup` (re-run the wizard), `switchroom doctor` (diagnose), or `switchroom agent list` (see what's running). Do not reinstall switchroom itself without explicit confirmation.
+
+## Step 1 — Verify prerequisites
+
+Switchroom requires Ubuntu 24.04 LTS (or compatible Debian-based Linux) with ≥4GB RAM. Check:
+
+```bash
+. /etc/os-release && echo "$PRETTY_NAME"
+free -h | awk '/^Mem:/ {print $2}'
+uname -m
+```
+
+If the user is on macOS or Windows, stop and explain: switchroom runs on Linux servers (typically a $6/mo VPS). Point them at the README's "Quick Start" — they'll want to provision a Linux box first.
+
+## Step 2 — Install system dependencies
+
+Only install what's missing. Check each first:
+
+```bash
+# System packages
+for pkg in tmux expect docker.io; do
+  dpkg -s "$pkg" >/dev/null 2>&1 || echo "MISSING: $pkg"
+done
+
+# Bun
+command -v bun || echo "MISSING: bun"
+
+# Node 22+ (via nvm)
+node -v 2>/dev/null || echo "MISSING: node"
+
+# Claude Code CLI
+command -v claude || echo "MISSING: claude"
+```
+
+For anything missing, run the corresponding install step:
+
+```bash
+# apt packages
+sudo apt update && sudo apt install -y tmux expect docker.io
+
+# bun
+curl -fsSL https://bun.sh/install | bash
+
+# nvm + node 22
+curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
+source ~/.bashrc
+nvm install 22
+
+# claude code
+npm install -g @anthropic-ai/claude-code
+
+# docker group (user needs to log out/in or newgrp)
+sudo usermod -aG docker "$USER"
+```
+
+**Important:** After `usermod -aG docker`, the user needs a new shell for group membership to apply. Mention this explicitly.
+
+## Step 3 — Clone and build switchroom
+
+```bash
+git clone https://github.com/mekenthompson/switchroom.git ~/code/switchroom
+cd ~/code/switchroom && bun install && bun link
+```
+
+Verify:
+
+```bash
+switchroom --version
+```
+
+## Step 4 — Run setup wizard
+
+`switchroom setup` is an interactive wizard that configures the Telegram bot token, forum chat, and first agent. **It requires a terminal the user controls** — if you're running inside an agent session, you cannot drive it yourself. Tell the user:
+
+> Run `switchroom setup` in your own terminal. It'll ask for your Telegram bot token and walk you through creating your first agent. Come back when it finishes and I can verify with `switchroom doctor`.
+
+## Step 5 — Verify
+
+After `switchroom setup` completes:
+
+```bash
+switchroom doctor
+switchroom agent list
+```
+
+If `switchroom doctor` reports healthy and at least one agent is listed, installation is complete. Offer to invoke the `switchroom-status` or `switchroom-health` skill for a deeper look.
+
+### Optional follow-up: share one Anthropic account across multiple agents
+
+Once the first agent is up and authenticated, the user can promote that agent's auth to a global Anthropic account so additional agents share the same Pro/Max subscription without each running its own OAuth flow. See `switchroom-manage` (Anthropic accounts section) for the bootstrap flow. This is the path most users want when they add a second agent — flag it as soon as they ask "how do I add another agent?".
+
+## What not to do
+
+- **Do not** run `switchroom setup` non-interactively or pipe input to it — it's designed for a human.
+- **Do not** edit `~/.switchroom/vault.enc` or any file under `~/.switchroom/` directly. Use the CLI.
+- **Do not** install switchroom system-wide (no `sudo npm install -g switchroom`). Switchroom is a bun-linked binary from a user-owned checkout.
+- **Do not** reinstall over an existing install without asking. If the user wants a clean slate, have them run `switchroom uninstall` first (or confirm they want to blow away `~/.switchroom/`).

package/skills/switchroom-manage/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: switchroom-manage
+description: Manage the fleet of switchroom agents from a Claude Code session — add, create, remove, reinstall, reprovision, or lifecycle-control agents. Use when the user says 'add a new agent', 'add an agent to my setup', 'create a new agent', 'remove an agent', 'reinstall my agents', 'reprovision my agents', 'list my agents', 'manage my agents', or invokes `/switchroom`. This is the right skill for fleet-level changes (adding/removing agents) even when the phrasing includes 'install' or 'reinstall' — use switchroom-install only for bootstrapping switchroom itself on a fresh machine.
+---
+
+# Switchroom Agent Management
+
+When the user invokes `/switchroom` or asks to add, create, remove, reinstall, reprovision, or otherwise manage their switchroom agents, use the Bash tool to run the appropriate `switchroom` CLI command from the table below.
+
+**Prerequisite:** The `switchroom` CLI must be installed and available on PATH. If it isn't, direct the user to the `switchroom-install` skill to bootstrap switchroom itself first.
+
+## Available Commands
+
+| User says | Run |
+|---|---|
+| `/switchroom agents` or `/switchroom list` | `switchroom agent list` |
+| `/switchroom create <name>` or "add a new agent" | `switchroom agent create <name>` |
+| `/switchroom remove <name>` | `switchroom agent remove <name>` |
+| `/switchroom start <name>` | `switchroom agent start <name>` |
+| `/switchroom stop <name>` | `switchroom agent stop <name>` |
+| `/switchroom restart <name>` | `switchroom restart <name>` |
+| `/switchroom reinstall <name>` or "reinstall my agents" | `switchroom update` |
+| `/switchroom status` | `switchroom auth status` |
+| `/switchroom memory <query>` | `switchroom memory search "<query>"` |
+| `/switchroom memory <query> --agent <name>` | `switchroom memory search "<query>" --agent <name>` |
+| `/switchroom vault list` | `switchroom vault list` |
+| `/switchroom topics` | `switchroom topics list` |
+| `/switchroom accounts` or "list anthropic accounts" | `switchroom auth account list` |
+| "share my Pro subscription across agents" / "add an Anthropic account" | See **Anthropic accounts** below |
+
+### Add / create a new agent
+
+When the user says "add a new agent", "add an agent to my switchroom setup", or "create a new agent", ask for a name (if not provided) and run `switchroom agent create <name>`. This scaffolds the agent directory, installs systemd timers, and wires it into the config cascade.
+
+### Reinstall / reprovision agents
+
+"Reinstall my agents" is a fleet-level reprovisioning operation, **not** a fresh switchroom install. It means: pull the latest code, re-apply `switchroom.yaml`, and restart the agents. Run `switchroom update` for the full fleet. Ask the user to confirm before running if the scope is ambiguous.
+
+### Anthropic accounts (one OAuth, many agents)
+
+The new auth model treats the Anthropic account as the unit of authentication: one `claude setup-token` per account, then enable the account on however many agents you want. See `reference/share-auth-across-the-fleet.md` for the full design.
+
+**Bootstrap flow when the user wants to share one Pro/Max subscription across agents:**
+
+1. Make sure at least one agent is already authenticated the per-agent way (existing `switchroom auth login <agent>` flow). This gives you a valid `.credentials.json` to lift from.
+2. **Create the global account** by lifting the agent's credentials:
+   ```bash
+   switchroom auth account add work-pro --from-agent <existing-agent>
+   ```
+3. **Enable** the account on every agent that should share it:
+   ```bash
+   switchroom auth enable work-pro <agent-1> <agent-2> ...
+   ```
+   This appends to `agents.<name>.auth.accounts` in `switchroom.yaml` and immediately fans out the credentials to each agent's `.claude/credentials.json`.
+4. **Restart** the affected agents so claude picks up the new credentials.
+
+Verify with `switchroom auth account list` — shows accounts, which agents use each, health, and expiry. Account-level quota and refresh state replaces the per-agent view: when one account hits its 5-hour cap, every agent on it is failed over together.
+
+**Telegram parity** — the same flow works from inside a chat:
+
+```
+/auth login                          # current agent, existing slot flow
+/auth account add work-pro           # lifts current agent → global account
+/auth enable work-pro <other-agent>  # wires another agent to the same account
+```
+
+## Behavior
+
+1. Run the matching `switchroom` command using the Bash tool.
+2. If the command fails with "command not found", tell the user that `switchroom` is not installed or not on PATH and suggest running `npm install -g switchroom` or checking their installation.
+3. Format the output cleanly for the user. For list commands, present results as a table or bulleted list. For start/stop/restart, confirm the action taken.
+4. If the user just types `/switchroom` with no subcommand, show this help summary:
+
+```
+Switchroom commands:
+  /switchroom agents         List all configured agents
+  /switchroom start <name>   Start an agent
+  /switchroom stop <name>    Stop an agent
+  /switchroom restart <name> Restart an agent (drain by default)
+  /switchroom status         Show per-agent auth status
+  /switchroom accounts       List Anthropic accounts + which agents use each
+  /switchroom memory <query> Search agent memory
+  /switchroom vault list     List vault secrets
+  /switchroom topics         List Telegram topics
+
+Fleet operations (run directly, not via /switchroom <sub>):
+  switchroom update          Pull latest + reconcile + restart everything
+  switchroom version         Show versions + running agent health summary
+  switchroom auth refresh-accounts  Refresh OAuth tokens + fan out (cron entrypoint)
+```