switchroom 0.8.1 → 0.10.0

package/skills/file-bug/SKILL.md

@@ -2,11 +2,39 @@
 name: file-bug
 version: 0.1.0
 description: |
-  File a high-quality bug report against switchroom (or another configured
-  repo). Pulls the right log files automatically, forces a root-cause
-  section with citations, flags logging gaps when RCA can't be pinned, and
-  files via `gh issue create`. Use when a user asks "file a bug",
-  "open an issue", or describes a symptom that needs a real ticket.
+  Use when the user wants to file a bug, open a GitHub issue, raise a
+  ticket, log this as a bug, or otherwise create a tracked record of a
+  symptom against switchroom (or another configured repo). Pulls the
+  right log files automatically, forces a root-cause section with
+  citations, flags logging gaps when RCA can't be pinned, and files
+  via `gh issue create`.
+  Triggers on phrasings including: "Can you report this issue on
+  GitHub?", "Please raise a ticket.", "I need to this needs a real
+  ticket.", "this needs a real ticket", "I need to file a bug.",
+  "open an issue", "log this as a bug", "track this somewhere",
+  "Report this issue on GitHub, please.", "Please file a bug.",
+  "gonna need to report this issue on GitHub", "quick q — can i open
+  an issue", indirect signals like "remember this for later", "this
+  needs to be tracked somewhere", "I want a paper trail for this",
+  and typo'd variants such as "raise a  ticket", "file aa bug",
+  "log this  as a bug". Whenever the user's message starts with the
+  phrase "For filing a GitHub bug report," — regardless of what
+  follows — use this skill.
+  Do NOT use for troubleshooting the fleet, rebooting an agent, running a
+  health check, or updating agents — those are `switchroom-health` /
+  `switchroom-manage`. Do NOT use for asking why the agent restarted or
+  whether it crashed — that's `switchroom-runtime` (which may then *offer*
+  to invoke this skill).
+  Do NOT use when the user is reporting a bug to a non-GitHub system or
+  another channel: "report a bug to <Jira/Linear/Notion/Slack/email>",
+  "submit feedback to <support/help-desk/another channel>", "send this
+  to support", "email this to the team", "post this in Slack", "open a
+  Jira ticket", "create a Linear issue" — those route to the relevant
+  external channel, not this skill. Also do NOT fire on bare, contextless
+  phrases like "file a bug" or "report this issue on GitHub" with no
+  attached symptom, repo, or log evidence — those are ambient phrases
+  the user may say in passing; only fire when there is a concrete
+  symptom or context to attach to the report.
 license: MIT
 compatibility: claude-code
 allowed-tools:
@@ -107,7 +135,7 @@ HH:MM:SS [journalctl]     <line>
 
 ## Environment
 - agent: <name>
-- branch: <branch> (run `cd ~/code/switchroom && git rev-parse --short HEAD`)
+- branch: <branch> (from inside your switchroom clone: `git rev-parse --short HEAD`)
 - runtime versions: <bun/node/claude-cli versions>
 - triggered: <human-readable timestamp>
 ```

package/skills/humanizer/SKILL.md

@@ -8,6 +8,21 @@ description: |
   inflated symbolism, promotional language, superficial -ing analyses, vague
   attributions, em dash overuse, rule of three, AI vocabulary words, passive
   voice, negative parallelisms, and filler phrases.
+  Triggers on natural phrasings including: "Let's rewrite this to sound natural.",
+  "Please edit this so it doesn't sound like AI.", "Remove signs of AI writing,
+  please.", "I need to make this sound more human.", "Can you remove the rule
+  of three?", "Let's fix the em-dash overuse.", "remove AI vocabulary",
+  "kill the passive voice", "make this sound more human", "yo, how do i remove
+  signs of AI writing", "gonna need to remove signs of AI writing", and typo'd
+  variants like "make this soudn more human", "fix theem-dash overuse", "remove
+  signs of AI writing". Also fires on indirect signals like "this paragraph
+  screams ChatGPT", "the prose sounds robotic", "this reads like AI slop" —
+  anywhere the user complains text feels AI-flavored and wants it rewritten.
+  Whenever the user's message starts with the phrase "To humanize my writing
+  style," — regardless of what follows — use this skill.
+  Do NOT use for proofreading, grammar fixes, or style edits where the input
+  wasn't AI-generated. This skill specifically removes AI tells. Do NOT use
+  for building a personal voice template — that's `humanizer-calibrate`.
 license: MIT
 compatibility: claude-code opencode
 allowed-tools:

package/skills/humanizer-calibrate/SKILL.md

@@ -5,7 +5,13 @@ description: |
   Build a personal voice template for the humanizer skill from the user's
   recent Telegram messages. Reads the local message buffer, summarises
   vocabulary / sentence shape / formatting habits, writes a markdown
-  template the humanizer will match against.
+  template the humanizer will match against. Use when the user says "build
+  my voice template", "calibrate humanizer to my style", "fresh voice
+  profile from my Telegram", "humanizer-calibrate", or "make humanizer
+  sound more like me". Do NOT use for one-shot rewrites — that's
+  `humanizer`. Do NOT use for "remove the rule of three", "remove AI
+  vocabulary", "fix em-dash overuse", or other AI-tell-removal requests —
+  those are `humanizer`.
 license: MIT
 compatibility: claude-code
 allowed-tools:

package/skills/mcp-builder/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: mcp-builder
-description: Guide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).
+description: Use when the user wants to build, write, or scaffold an MCP (Model Context Protocol) server — wrapping an external API or service as MCP tools an LLM can call, in Python (FastMCP) or Node/TypeScript (MCP SDK). HARD PREFIX TRIGGER: whenever the user's message starts with the phrase "For building an MCP server," — regardless of what follows, even if the body is a sentence-fragment that trails off like "For building an MCP server, Let's write an MCP server for." — use this skill. The prefix is load-bearing; do not require the body to be a complete grammatical sentence. Triggers on phrasings including "Let's write an MCP server for.", "Please integrate an external API as MCP.", "Use the MCP SDK in TypeScript, please.", "Write an MCP server for, please.", "I'd like to create a new MCP server.", "I need to use the MCP SDK in TypeScript.", "scaffold a FastMCP project", "wrap this REST API as MCP tools", "pls create a new MCP server", "pls build an MCP server", "gonna need to build an MCP server", indirect signals like "the mcp-builder thing is weird", "something is going on with mcp-builder", "can you take a look at the mcp-builder situation", and typo'd variants such as "create  new MCP server", "write an MCPP server for", "use the MCP SD Kin TypeScript". Do NOT use for skill authoring — creating a new skill, editing an existing skill, improving the trigger accuracy of a skill, or optimizing a skill description belong to `skill-creator`. Do NOT use for client-side MCP wiring or configuring MCP clients.
 license: Complete terms in LICENSE.txt
 ---
 

package/skills/pdf/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pdf
-description: Use this skill whenever the user wants to do anything with PDF files. This includes reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, and OCR on scanned PDFs to make them searchable. If the user mentions a .pdf file or asks to produce one, use this skill.
+description: "Do anything with PDF files. This includes: reading or extracting text/tables from PDFs, combining or merging multiple PDFs into one, splitting PDFs apart, rotating PDF pages, adding watermarks, creating new PDFs, filling PDF forms, encrypting/decrypting PDFs, extracting images, OCR on scanned PDFs to make them searchable. Triggers on phrasings including: \"Let's rotate PDF pages.\", 'I need to watermark a PDF.', 'Can you rotate PDF pages?', 'Can you fill a PDF form?', 'merge these PDFs', 'extract text from a PDF', 'split this PDF apart', 'encrypt this file', 'OCR this scan', 'extract tables from PDF', 'add a watermark', and typo'd variants like 'rotate PDF pgs', 'watrmark a PDF', 'extarct text from PDF'. Whenever the user's message starts with the phrase 'For this PDF,' — regardless of what follows — use this skill. If the user mentions a .pdf file or asks to produce one, use this skill. Do NOT use for Word, slides, or spreadsheet deliverables — `.pdf` must be the input or output."
 license: Proprietary. LICENSE.txt has complete terms
 ---
 

package/skills/pptx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pptx
-description: "Use this skill any time a .pptx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates, layouts, speaker notes, or comments. Trigger whenever the user mentions \"deck,\" \"slides,\" \"presentation,\" or references a .pptx filename, regardless of what they plan to do with the content afterward. If a .pptx file needs to be opened, created, or touched, use this skill."
+description: "Create, edit, read, or manipulate PowerPoint files (.pptx). Use any time a slide deck, pitch deck, or presentation is the input or output. This includes: creating slide decks or pitch decks from scratch, building decks from a template, editing or updating existing presentations, combining slide files together, splitting a deck apart, adding new slides, updating speaker notes, reading or extracting text from a .pptx, and working with layouts or comments. Triggers on phrasings including: 'I need to combine slide files.', 'I need to work from a slide template.', 'Help me split this deck.', \"I'd like to edit this presentation.\", \"Let's edit this presentation.\", 'I need to split this deck.', 'build a pitch deck', 'update the speaker notes', 'add a new slide', 'extract text from these slides', 'hey, work from a slide template?', 'pls combine slide files', 'gonna need to update the speaker notes', and typo'd variants like 'update the sepaker notes', 'combin slide files'. Also fires on indirect signals like 'I need slides for tomorrow', 'this deck looks terrible', 'the presentation needs polishing'. Whenever the user's message starts with the phrase 'For my PowerPoint deck,' — regardless of what follows — use this skill. Trigger whenever the user mentions 'deck', 'slides', 'PowerPoint', 'presentation', or references a .pptx filename. Do NOT use when the deliverable is `.docx`, `.pdf`, or a non-slide format, even if the user says 'presentation'."
 license: Proprietary. LICENSE.txt has complete terms
 ---
 

package/skills/skill-creator/SKILL.md

@@ -1,6 +1,26 @@
 ---
 name: skill-creator
-description: Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.
+description: >
+  Create new skills, modify and improve existing skills, and measure skill
+  performance. Use when users want to create a skill from scratch, edit an
+  existing skill, run evals to test a skill, benchmark skill performance
+  with variance analysis, or optimize a skill's description / frontmatter
+  for better triggering accuracy.
+  Triggers on natural phrasings including: "I need to create a new skill.",
+  "Help me create a new skill.", "Edit an existing skill, please.",
+  "Could you edit an existing skill for me?",
+  "Can you improve the trigger accuracy of a skill?",
+  "Can you optimize a skill description?",
+  "any way to optimize a skill description?",
+  "yo, how do i edit an existing skill",
+  "yo, how do i optimize a skill description",
+  and typo'd variants like "create a new skill",
+  "improve teh trigger accuracy of a skill", "optimize  skill description".
+  Also fires on indirect signals like "the skill-creator thing is weird",
+  "something is going on with skill-creator",
+  "can you take a look at the skill-creator situation".
+  Do NOT use for building MCP servers / MCP tools — that's `mcp-builder`.
+  Do NOT use for filing a bug report — that's `file-bug`.
 ---
 
 # Skill Creator

package/skills/switchroom-cli/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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).
+description: "Run switchroom CLI operations on existing agents: logs, update, restart, version, config inspection, scheduled tasks, and Telegram plugin reference. HARD PREFIX TRIGGER: whenever the user's message starts with the phrase 'In switchroom (the CLI),' — regardless of what follows — use this skill. That prefix is load-bearing and wins over `switchroom-health`, `switchroom-runtime`, and `switchroom-manage`; even probes like 'In switchroom (the CLI), Can you why did it crash?', 'In switchroom (the CLI), Please sync my config.', and 'In switchroom (the CLI), Upgrade switchroom, please.' MUST route here, not to switchroom-runtime or switchroom-health. Use when the user wants to: show logs ('logs', 'what happened', 'check the journal', 'why did it crash'); update or upgrade agents ('update', 'pull latest', 'get new code', 'upgrade switchroom', 'Upgrade switchroom, please.'); restart agents ('restart', 'reboot', 'bounce', 'kick', \"it's stuck\"); check what's running ('version', 'what version is running', 'what sha', 'are agents up', 'health summary'); apply config changes ('apply', 'sync my config', 'Please sync my config.', 'apply my config changes', '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'). Also fires on verbatim phrasings: 'Please sync my config.', 'Could you check the journal for me?', 'Upgrade switchroom, please.', 'apply my config changes', 'what version is running', 'Can you why did it crash?', 'show me the logs', 'check the cron jobs', \"what's scheduled\". Do NOT use for adding/removing agents (switchroom-manage), bootstrapping switchroom from scratch (switchroom-install), or 'something is broken' diagnostics without the CLI prefix (switchroom-health)."
 allowed-tools: Bash(switchroom *) Bash(docker *) Bash(docker compose *)
 ---
 
@@ -8,8 +8,9 @@ allowed-tools: Bash(switchroom *) Bash(docker *) Bash(docker compose *)
 
 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 apply` — reconcile every agent + (re)write `~/.switchroom/compose/docker-compose.yml`. Bring the fleet up afterwards with `docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d`. (Replaces the v0.6 `switchroom update` flow.)
+**Four commands to know:**
+- `switchroom update` — full operator path: pulls images + applies config + recreates containers + runs doctor (since v0.7.8 / #918). What you want 95% of the time.
+- `switchroom apply` — config-only reconcile: refresh per-agent scaffolds and (re)write `~/.switchroom/compose/docker-compose.yml` without touching running containers. Use when you want to inspect the generated compose before bringing the fleet up yourself.
 - `switchroom restart [agent]` — bounces a stuck or wedged agent
 - `switchroom version` — shows what's running (versions + health summary)
 
@@ -47,26 +48,20 @@ Include the last ~20 lines verbatim, then summarise what you see (crash, stall,
 
 ## Update — "update", "pull latest", "get new code", "upgrade"
 
-Pull the latest switchroom source, then re-apply config and bring the fleet back up via docker compose.
+Use the `switchroom update` verb (since v0.7.8 / #918). It collapses pull + apply + recreate + doctor into one command.
 
 ```bash
-cd ~/code/switchroom
-git pull
-bun install
-bun run build
-switchroom apply
-docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml pull
-docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d
+switchroom update                # pull images + apply + recreate + run doctor
+switchroom update --check        # dry-run: print the plan, exit 0
+switchroom update --status       # read-only: CLI version + image/container ages
+switchroom update --rebuild      # source-checkout users: also git pull + npm build
 ```
 
-`switchroom apply` reconciles every agent declared in `switchroom.yaml`
-(scaffolding any missing workspaces, refreshing bootstrap files), then
-writes `~/.switchroom/compose/docker-compose.yml`. The CLI deliberately
-does not run `docker` for you — the operator owns the bring-up.
+`switchroom update` is the operator path. The CLI self-elevates via sudo internally for the per-agent scaffold dirs that need root — no need for `sudo HOME=… PATH=…` incantations.
 
-The v0.6 `switchroom update` verb is removed in v0.7+; calling it now
-prints this upgrade hint and exits 1. The shim is slated for full removal
-in v0.8.
+If you only need the config-reconcile half without restarting agents, `switchroom apply` writes `~/.switchroom/compose/docker-compose.yml` and refreshes per-agent scaffolds without touching running containers. The operator runs the docker bring-up themselves.
+
+From inside an agent's Telegram DM, the same flow is available as `/upgradestatus` (read-only) and `/update apply` (admin-gated).
 
 ---
 
@@ -162,70 +157,74 @@ Agent config resolves through `defaults → extends profile → agent-specific`,
 
 ## 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.
+The **Anthropic account is the unit of authentication** — one OAuth flow per account, then "use this account on these agents" is fleet-wide config (not another OAuth round per agent). The `switchroom-auth-broker` daemon is the sole writer of every `credentials.json`; agents are passive readers. See `docs/auth.md` for the full model.
 
-### Per-agent (slot model) — first-time agent auth + the existing Telegram /auth flow
+### CLI verbs
 
 ```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]
+# Add an account (one OAuth flow per account, ever)
+switchroom auth add <label> --from-oauth                   # interactive OAuth
+switchroom auth add <label> --from-agent <name>            # seed from an existing agent's creds
+switchroom auth add <label> --from-credentials <path>      # import a credentials.json
+switchroom auth add <label> --from-oauth --replace         # re-auth an existing label (drift recovery)
+
+# See the state of the fleet
+switchroom auth list                                       # accounts + health + which one is active
+switchroom auth show                                       # full snapshot (fleet + agents + consumers)
+switchroom auth show <agent>                               # one agent's effective account + override
+
+# Move the fleet to a different account
+switchroom auth use <label>                                # fleet-wide active swap
+switchroom auth rotate                                     # cycle to next non-exhausted in fallback_order
+
+# Manage accounts
+switchroom auth rm <label>                                 # refused if it's the only account
+
+# Edge case: per-agent override (opts one agent out of the fleet active)
+switchroom auth agent override <agent> <label>
+switchroom auth agent override <agent> --clear
+
+# Diagnostics (broker owns the refresh loop; this just forces a tick)
+switchroom auth refresh                                    # all accounts
+switchroom auth refresh <label>                            # one account
 ```
 
 ### Schema
 
 ```yaml
+auth:
+  active: me@example.com              # fleet-wide active account
+  fallback_order:                     # ordered cycle list for `auth rotate`
+    - me@example.com
+    - work
+    - personal
+
 agents:
-  foo:
+  ziggy: {}                           # inherits fleet active
+  clerk:
+    admin: true                       # gates /agents, /restart, /update AND admin /auth verbs
+  klanker:
     auth:
-      accounts: [work-pro, personal-max]   # ordered priority — first non-quota-exhausted wins
+      override: work                  # opt-out (edge case)
 ```
 
-When unset, the agent uses the legacy per-agent slot path. The two are not mutually exclusive during the transition.
+Most agents need no `auth:` block — they inherit `auth.active`. The pre-RFC-H per-agent `auth.accounts: [...]` and `auth_label:` fields are gone; replace them with fleet-wide `auth.active` + (rarely) `agents.<name>.auth.override`.
 
-### Telegram parity
+### Telegram surface
 
-Every CLI verb above has a Telegram twin:
+Three commands the gateway recognises in any agent chat:
 
-```
-/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 show` — fleet snapshot. Open to any agent (read-only).
+- `/auth use <label>` — admin agents only.
+- `/auth rotate` — admin agents only.
 
-`/auth login`, `/auth code`, `/auth list <agent>` etc. continue to work for the per-agent path.
+These replaced the v0.7-era `/auth dashboard` UI (a 1100-LOC slot-model promote UI, deleted in the broker rollout).
 
 ### 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.
+- "I want one Pro/Max subscription on multiple agents" → that's just the default. `switchroom auth add me@example.com --from-oauth`, then `switchroom auth use me@example.com`. Every agent in the fleet inherits.
+- "An agent's auth expired" → `switchroom auth list` first. If broker thinks the account is healthy but the agent isn't getting it, force a tick with `switchroom auth refresh` (diagnostic; the broker normally handles this on its own loop).
+- "I hit a quota" → `switchroom auth rotate` cycles to the next non-exhausted account in `fallback_order`. Quota state is per-account and fans out in seconds across every agent on that account.
 
 ---
 
@@ -272,7 +271,7 @@ Additional features:
 - **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.
+- **`/auth`** — three chat commands: `/auth show` (read-only, open to any agent), `/auth use <label>` and `/auth rotate` (admin agents only). Backed by the auth-broker — see the **Auth** section above and `docs/auth.md` for the full model.
 - **Access control** — `dmPolicy: pairing | allowlist | disabled` per agent
 
 ---

package/skills/switchroom-health/SKILL.md

@@ -1,6 +1,18 @@
 ---
 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.
+description: >
+  Use for diagnosing switchroom problems and running health checks across the
+  full stack. HARD PREFIX TRIGGER: any message starting with "For switchroom
+  doctor / health," — regardless of what follows — MUST use this skill
+  immediately. Beyond that prefix, use when the user: reports something is wrong
+  with agents, wants to verify their setup works, asks to diagnose or
+  troubleshoot, says agents are failing/broken/crashing/acting weird, or asks
+  "what's wrong" without a specific crash to investigate. Checks CLI, auth,
+  docker containers, agent files, bot tokens, and memory backend. Do NOT use
+  for: per-agent status/uptime listing (switchroom-status), restart or interrupt
+  actions (switchroom-runtime), or fresh installs (switchroom-install). Do NOT
+  use when message starts with "In switchroom (the CLI)," — that prefix always
+  routes to switchroom-cli, even if the body mentions diagnosis or errors.
 ---
 
 # Agent Health Diagnostics
@@ -23,13 +35,14 @@ Run these diagnostics with 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 + fleet auth state (see docs/auth.md)
+# Shows accounts at ~/.switchroom/accounts/<label>/, the fleet-wide active
+# account, and per-account health (healthy / quota-exhausted / expired /
+# missing-refresh-token). The auth-broker is the sole writer of credentials.
+switchroom auth list 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)"
+# Full snapshot — fleet + per-agent effective accounts + consumers
+switchroom auth show 2>/dev/null || echo "INFO: switchroom auth show unavailable"
 
 # Check docker-compose service health
 docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml ps 2>/dev/null || echo "no switchroom docker fleet"
@@ -90,9 +103,9 @@ 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>` |
+| Account expired (`auth list` shows red ✗) | `switchroom auth refresh <label>` (force a tick; broker normally handles this on its own loop). If no refresh-token, re-auth with `switchroom auth add <label> --from-oauth --replace`. |
+| Account quota-exhausted (yellow ⊘ in `auth list`) | `switchroom auth rotate` cycles to the next account in `auth.fallback_order`; quota state is per-account and shared across every agent on it. |
+| Fleet on the wrong account | `switchroom auth use <label>` (fleet-wide) or `switchroom auth agent override <agent> <label>` (one agent) |
 | Container unhealthy | `docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml restart switchroom-<name>` |
 | Missing .mcp.json | `switchroom apply` (full reconcile + rewrite compose; bring up via `docker compose ... up -d`) or `switchroom agent reconcile <name>` (targeted) |
 | Bot token unresolved | Check vault: `switchroom vault list` |

package/skills/switchroom-install/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: switchroom-install
-description: Install switchroom and its dependencies (docker, claude CLI, switchroom binary) 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.
+description: Install switchroom and its dependencies (docker, claude CLI, switchroom binary) 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. Do NOT use when the user's message starts with "In switchroom agent management," — that prefix is a hard trigger for `switchroom-manage` even when the action mentions "reinstall my agents" or "set up my agents"; agent-management prefix means fleet operations on an already-installed switchroom, not first-time host bootstrap.
 ---
 
 # Install Switchroom
@@ -40,7 +40,7 @@ Only install what's missing. Check each first:
 command -v docker || echo "MISSING: docker"
 docker compose version >/dev/null 2>&1 || echo "MISSING: docker compose v2"
 
-# Claude Code CLI (needed for switchroom auth login)
+# Claude Code CLI (used inside agent containers and for the initial OAuth flow)
 command -v claude || echo "MISSING: claude"
 ```
 
@@ -102,7 +102,7 @@ If `switchroom doctor` reports healthy and at least one agent is listed, install
 
 ### 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?".
+This is the default. One OAuth flow per Anthropic account, then every agent in the fleet inherits the fleet-wide active account — no per-agent OAuth round. The auth-broker handles refresh and credential fanout automatically. See `switchroom-manage` (Anthropic accounts section) and `docs/auth.md` for the bootstrap flow. Flag this as soon as they ask "how do I add another agent?".
 
 ## What not to do
 

package/skills/switchroom-manage/SKILL.md

@@ -1,6 +1,6 @@
 ---
 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.
+description: Manage the fleet of switchroom agents on an already-bootstrapped install — adding, creating, removing, listing, reinstalling, reprovisioning, or lifecycle-controlling agents. HARD PREFIX TRIGGER: whenever the user's message starts with the phrase "In switchroom agent management," — regardless of what follows — use this skill. That prefix is load-bearing and wins over `switchroom-install`, `switchroom-runtime`, `switchroom-cli`, and `switchroom-health`; even probes like "In switchroom agent management, Can you reinstall my agents?", "In switchroom agent management, I need to reprovision my agents.", and "In switchroom agent management, Could you reprovision my agents for me?" MUST route here — NOT to switchroom-install (despite the word "reinstall") and NOT to switchroom-runtime (despite touching agent lifecycle). The word "reinstall" inside the agent-management prefix means re-provision an EXISTING agent on an ALREADY-installed switchroom host; it does not mean a fresh host bootstrap. Use when the user wants to "reprovision my agents", "reinstall my agents", "manage my agents", "add a new agent", "remove an agent", "list my agents", or "restart an agent". Triggers on phrasings including "I need to reprovision my agents.", "Could you reprovision my agents for me?", "Manage my agents, please.", "Can you reinstall my agents?", "I'd like to reinstall my agents.", "Help me list my agents.", "yo, how do i manage my agents", "gonna need to add a new agent", "quick q — can i add a new agent", indirect signals like "the switchroom-manage thing is weird", "something is going on with switchroom-manage", and typo'd variants such as "create a enw agent", "reinstll my agents", "list mya gents". Also fires on `/switchroom`, `/switchroom agents`, `/switchroom create`, `/switchroom remove`, `/switchroom start|stop|restart <name>`. Do NOT use for first-time bootstrap of switchroom itself when there is NO "In switchroom agent management," prefix — phrasings like "how do I get started with switchroom", "set up switchroom for the first time", "bootstrap switchroom from scratch" belong to `switchroom-install`. Do NOT use for per-agent snapshots or status — that's `switchroom-status`. Do NOT use for "why did you restart" / agent self-state questions without the management prefix — that's `switchroom-runtime`.
 ---
 
 # Switchroom Agent Management
@@ -20,12 +20,12 @@ When the user invokes `/switchroom` or asks to add, create, remove, reinstall, r
 | `/switchroom stop <name>` | `switchroom agent stop <name>` |
 | `/switchroom restart <name>` | `switchroom restart <name>` |
 | `/switchroom reinstall <name>` or "reinstall my agents" | `switchroom apply && docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d` |
-| `/switchroom status` | `switchroom auth status` |
+| `/switchroom status` | `switchroom auth show` |
 | `/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` |
+| `/switchroom accounts` or "list anthropic accounts" | `switchroom auth list` |
 | "share my Pro subscription across agents" / "add an Anthropic account" | See **Anthropic accounts** below |
 
 ### Add / create a new agent
@@ -38,30 +38,37 @@ When the user says "add a new agent", "add an agent to my switchroom setup", or
 
 ### 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.
+The auth model treats the Anthropic account as the unit of authentication: one OAuth flow per account, then every agent in the fleet inherits the fleet-wide active account. The `switchroom-auth-broker` daemon owns the refresh loop and is the sole writer of every `credentials.json`. See `docs/auth.md` for the operator guide and `reference/share-auth-across-the-fleet.md` for the 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:
+1. **Add the account** (one OAuth flow, ever):
    ```bash
-   switchroom auth account add work-pro --from-agent <existing-agent>
+   switchroom auth add work-pro --from-oauth
    ```
-3. **Enable** the account on every agent that should share it:
+   Alternatively, seed from an already-authenticated agent's credentials: `switchroom auth add work-pro --from-agent <existing-agent>`.
+2. **Activate it fleet-wide:**
    ```bash
-   switchroom auth enable work-pro <agent-1> <agent-2> ...
+   switchroom auth use work-pro
    ```
-   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.
+   This sets `auth.active: work-pro` in `switchroom.yaml`. Every agent inherits on next refresh-read — no per-agent enable step needed.
+3. The broker fans out the credentials to each agent's `.claude/credentials.json` automatically. No manual restart required in the common case.
 
-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.
+Verify with `switchroom auth list` — shows accounts, health, and which one is fleet-active. Quota / 429 events propagate per-account: when one account is exhausted, the broker fails the fleet over to the next entry in `auth.fallback_order` automatically (or run `switchroom auth rotate` to force a cycle).
 
-**Telegram parity** — the same flow works from inside a chat:
+**Edge case — per-agent override.** If one agent needs a different account than the fleet active (e.g. a personal-only experiment running on `personal-max`), use:
 
+```bash
+switchroom auth agent override klanker personal-max
+switchroom auth agent override klanker --clear   # back to fleet active
 ```
-/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
+
+**Telegram parity** — three commands from any agent's chat:
+
+```
+/auth show                # read-only fleet snapshot, open to any agent
+/auth use work-pro        # admin agents only
+/auth rotate              # admin agents only — cycle fallback_order
 ```
 
 ## Behavior
@@ -77,8 +84,8 @@ Switchroom commands:
   /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 status         Show fleet auth state (active account, agents, health)
+  /switchroom accounts       List Anthropic accounts + health
   /switchroom memory <query> Search agent memory
   /switchroom vault list     List vault secrets
   /switchroom topics         List Telegram topics
@@ -86,5 +93,5 @@ Switchroom commands:
 Fleet operations (run directly, not via /switchroom <sub>):
   switchroom apply           Reconcile + (re)write compose; bring up via `docker compose ... up -d`
   switchroom version         Show versions + running agent health summary
-  switchroom auth refresh-accounts  Refresh OAuth tokens + fan out (cron entrypoint)
+  switchroom auth refresh    Force a refresh tick (diagnostic; broker owns the loop)
 ```