switchroom 0.7.15 → 0.10.0

package/skills/buildkite-pipelines/SKILL.md

@@ -1,15 +1,32 @@
 ---
 name: buildkite-pipelines
 description: >
-  This skill should be used when the user asks to "write a pipeline",
-  "add caching", "make this build faster", "show test failures in the build page",
-  "add annotations", "only run tests when code changes", "set up dynamic pipelines",
-  "add retry", "parallel steps", "matrix build", "add plugins", or
-  "work with artifacts in pipeline YAML".
-  Also use when the user mentions .buildkite/ directory, pipeline.yml,
-  buildkite-agent pipeline upload, step types (command, wait, block, trigger,
-  group, input), if_changed, notify, concurrency, or asks about Buildkite CI
-  configuration.
+  Use when the user is authoring or editing `.buildkite/pipeline.yml` — the
+  declarative CI/CD configuration for Buildkite. Covers step types, caching,
+  parallelism, annotations, retry, dynamic pipelines, matrix builds, plugins,
+  notifications, artifacts, and concurrency in pipeline YAML.
+  Triggers on natural phrasings including: "Help me write a pipeline.",
+  "Can you parallel steps?", "Let's add retry.", "I'd like to add caching.",
+  "Let's add annotations.", "Let's show test failures in the build page.",
+  "yo, how do i matrix build", "pls only run tests when code changes",
+  "yo, how do i only run tests when code changes", and typo'd variants like
+  "write a pipeline", "add annotations", "set up dnamic pipelines".
+  Also fires on indirect signals like "my pipeline.yml is a mess",
+  "the build is slow", "tests run in serial when they shouldn't".
+  Also fires on mentions of the `.buildkite/` directory, `pipeline.yml`,
+  step types (command, wait, block, trigger, group, input), `if_changed`,
+  `notify`, `concurrency`, plugin blocks, matrix steps, or general
+  Buildkite CI configuration.
+  Do NOT use when the user is invoking `buildkite-agent <subcommand>` inside
+  a running step — that's `buildkite-agent-runtime`. In particular, if the
+  user's message begins with "Inside a Buildkite step," that is the
+  hard-trigger prefix for `buildkite-agent-runtime`, NOT this skill — even
+  if the message also mentions annotations, artifacts, step attributes, or
+  pipeline upload. The distinguishing rule is: authoring `pipeline.yml` =
+  this skill; calling the `buildkite-agent` binary from inside a running
+  job = `buildkite-agent-runtime`. Do NOT use for terminal-driven `bk` CLI
+  operations — that's `buildkite-cli`. Do NOT use for direct REST/GraphQL
+  API calls — that's `buildkite-api`.
 ---
 
 # Buildkite Pipelines

package/skills/buildkite-secure-delivery/SKILL.md

@@ -1,15 +1,29 @@
 ---
 name: buildkite-secure-delivery
 description: >
-  This skill should be used when the user asks to "publish to package registry",
-  "push a Docker image", "set up OIDC authentication", "request an OIDC token",
-  "authenticate without static credentials", "set up SLSA provenance",
-  "generate attestation", "sign pipelines", "verify pipeline signatures",
-  or "secure the supply chain".
-  Also use when the user mentions OIDC, SLSA, provenance, attestation, cosign,
-  JWKS, pipeline signing, pipeline verification, packages.buildkite.com,
-  Package Registry, artifact signing, or asks about credential-free publishing,
-  supply chain security, or secure delivery in Buildkite.
+  Set up secure delivery for Buildkite CI: configure OIDC authentication
+  (no static credentials), generate SLSA provenance / build attestations,
+  sign pipelines and verify pipeline signatures with JWKS, publish to a
+  package registry (packages.buildkite.com), push signed Docker images,
+  and harden the supply chain end-to-end. Use when the user says:
+  "Please secure the supply chain.", "I'd like to push a Docker image.",
+  "Can you sign pipelines?", "I need to verify pipeline signatures.",
+  "Could you sign pipelines for me?", "Set up SLSA provenance, please.",
+  "authenticate without static credentials", "generate attestation",
+  "publish to packages.buildkite.com", "gonna need to verify pipeline
+  signatures", "gonna need to sign pipelines", "pls authenticate without
+  static credentials", and typo'd variants like "set up LSA provenance",
+  "verify ppeline signatures". Whenever the user's message starts with
+  the phrase "For Buildkite OIDC/SLSA," — regardless of what follows —
+  use this skill. Anything mentioning OIDC, SLSA, provenance,
+  attestation, cosign, JWKS, pipeline signing, pipeline verification,
+  packages.buildkite.com, Package Registry, artifact signing,
+  credential-free publishing, or supply chain security fires this skill.
+  Do NOT use for in-step `buildkite-agent oidc request-token` — that's
+  `buildkite-agent-runtime`. Do NOT use for writing pipelines, uploading
+  pipelines dynamically, or adding caching/plugins — those are
+  `buildkite-pipelines`. Do NOT use for distributed locks — that's
+  `buildkite-agent-runtime`.
 ---
 
 # Buildkite Secure Delivery

package/skills/buildkite-test-engine/SKILL.md

@@ -1,14 +1,31 @@
 ---
 name: buildkite-test-engine
 description: >
-  This skill should be used when the user asks to "split tests across machines",
-  "set up test splitting", "parallelize test suite", "detect flaky tests",
-  "quarantine flaky tests", "configure test collectors", "speed up tests",
-  "set up bktec", "configure test engine", or "reduce flaky test failures".
-  Also use when the user mentions bktec, Test Engine, test suites,
-  BUILDKITE_TEST_ENGINE_* environment variables, BUILDKITE_ANALYTICS_TOKEN,
-  test-collector plugin, test reliability scores, test timing data,
-  or asks about Buildkite test splitting and flaky test management.
+  ALWAYS use this skill when the user's message begins with "Using
+  Buildkite Test Engine," — that prefix is a hard trigger regardless of
+  what follows. Specifically fires on: "Using Buildkite Test Engine, Help
+  me detect flaky tests.", "Using Buildkite Test Engine, Can you
+  parallelize test suite?", "Using Buildkite Test Engine, Can you
+  configure test collectors?", "Using Buildkite Test Engine, Let's speed
+  up tests.", "Using Buildkite Test Engine, set up test splitting",
+  "Using Buildkite Test Engine, quarantine flaky tests".
+  Use when the user wants to split tests across parallel machines, set up
+  test splitting, parallelize a test suite, detect or quarantine flaky tests,
+  configure test collectors, speed up tests via Buildkite's Test Engine, set
+  up `bktec`, or reduce flaky test failures.
+  Triggers on natural phrasings including: "Help me detect flaky tests.",
+  "Can you parallelize test suite?", "I need to configure test collectors.",
+  "Can you configure test collectors?", "Let's speed up tests.",
+  "Can you speed up tests?", "yo, how do i speed up tests",
+  "gonna need to configure test collectors",
+  "quick q — can i configure test collectors", and typo'd variants like
+  "parallelize  test suite", "set up tes tsplitting", "set up test splitting".
+  Also fires on `bktec`, Buildkite Test Engine, test suites,
+  `BUILDKITE_TEST_ENGINE_*` environment variables, `BUILDKITE_ANALYTICS_TOKEN`,
+  the `test-collector` plugin, test reliability scores, test timing data,
+  or any mention of Buildkite test splitting and flaky-test management.
+  Do NOT use for authoring general pipeline YAML (that's `buildkite-pipelines`)
+  or for `buildkite-agent` in-step subcommands (that's `buildkite-agent-runtime`).
 ---
 
 # Buildkite Test Engine

package/skills/docx/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: docx
-description: "Use this skill whenever the user wants to create, read, edit, or manipulate Word documents (.docx files). Triggers include: any mention of 'Word doc', 'word document', '.docx', or requests to produce professional documents with formatting like tables of contents, headings, page numbers, or letterheads. Also use when extracting or reorganizing content from .docx files, inserting or replacing images in documents, performing find-and-replace in Word files, working with tracked changes or comments, or converting content into a polished Word document. If the user asks for a 'report', 'memo', 'letter', 'template', or similar deliverable as a Word or .docx file, use this skill. Do NOT use for PDFs, spreadsheets, Google Docs, or general coding tasks unrelated to document generation."
+description: "Create, read, edit, or manipulate Word documents (.docx files). Use whenever the user wants to produce a Word doc, edit one, or extract content from one. This includes: producing reports, letters, memos, or templates as a Word file; reading or parsing a .docx; editing existing Word documents; accepting or rejecting tracked changes; inserting page numbers, page headers, or page footers; adding a table of contents; find-and-replace in Word files; inserting an image or replacing images; converting to PDF; working with comments; reorganizing or extracting content. Triggers on phrasings including: 'Help me accept tracked changes.', 'Please insert page numbers.', \"I'd like to read a .docx file.\", 'Can you produce a report as a Word file?', 'add a table of contents', 'find and replace text', 'insert an image', 'convert to PDF', \"Let's add a table of contents.\", 'hey, read a .docx file?', 'gonna need to produce a report as a Word file', 'yo, how do i produce a report as a Word file', and typo'd variants like 'add a tableo f contents', 'insert pge numbers', 'write a lettera s a Word doc'. Whenever the user's message starts with the phrase 'For my Word .docx document,' — regardless of what follows — use this skill. Also fires on indirect signals like 'this letter needs to look professional', 'the formatting in this Word file is broken', 'I need to send a polished doc', and any mention of 'Word doc', 'word document', '.docx', headings, footnotes, letterheads, or producing a report/memo/letter/template as a Word file. Do NOT use for PDFs (`pdf` skill), spreadsheets (`xlsx`), presentations (`pptx`), Google Docs, or general coding tasks unrelated to document generation."
 license: Proprietary. LICENSE.txt has complete terms
 ---
 

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` |