switchroom 0.11.1 → 0.12.1

package/README.md

@@ -22,7 +22,7 @@ Every time an agent starts work, a **progress card** pins into its Telegram topi
 
 No silent gaps. No ghosts. No squinting into a black box.
 
-<p align="center"><img src="docs/diagrams/progress-card-anatomy.jpg" width="700" alt="Annotated progress card: pin badge, user quote, last 5 steps, collapsed older, in-flight pulse, elapsed timer, sub-agent indent"></p>
+<p align="center"><img src="docs/diagrams/progress-card-anatomy.svg" width="700" alt="Annotated progress card: pin badge, user quote, last 5 steps, collapsed older, in-flight pulse, elapsed timer, sub-agent indent"></p>
 
 ```
 ⚙️ Working… · ⏱ 12s
@@ -87,9 +87,12 @@ You (Telegram)
            ├─ Progress cards             ├─ Approval kernel ◄─────┤   settings.json (tools, hooks, MCP)
            ├─ Pin / unpin lifecycle      │   (allow/deny broker)  ├─ Hindsight plugin (memory)
            ├─ SQLite history             ├─ Vault broker ◄────────┤   Drive MCP, Playwright MCP, …
-           ├─ Card-events.jsonl audit    │   (cron secrets, IPC)  └─ scheduled tasks across reboots
-           ├─ Emoji reactions            │
-           └─ Format conversion          └─ Docker Compose restart (unless-stopped)
+           ├─ Card-events.jsonl audit    ├─ Auth broker ◄─────────┤   in-agent scheduler sidecar
+           ├─ Emoji reactions            │   (OAuth refresh,       └─ (cron, fires across reboots)
+           └─ Format conversion          │    sole creds writer)
+                                         ├─ hostd (host-control:
+                                         │   /restart, /update apply)
+                                         └─ Docker Compose restart (unless-stopped)
 ```
 
 See [`docs/architecture.md`](docs/architecture.md) for the process model, IPC layout, supervisor choice, and how each layer maps to the `claude` CLI.
@@ -98,7 +101,7 @@ See [`docs/architecture.md`](docs/architecture.md) for the process model, IPC la
 
 Tools that touch the world — Bash, Edit, Write, anything not on an agent's pre-approved allowlist — pause for explicit approval. Switchroom's **approval kernel** (shipped in v0.5.1) routes every gated tool call through an inline Telegram card with the actual diff or command shown. Tap Allow and the tool resumes. Tap Deny and the agent gets a clean refusal it can recover from.
 
-<p align="center"><img src="docs/diagrams/approval-grant-flow.jpg" width="700" alt="Approval grant flow: agent tool call pauses at the kernel, broker writes pending grant to sqlite, user taps Allow on the Telegram card, broker releases the gate, tool resumes"></p>
+<p align="center"><img src="docs/diagrams/approval-grant-flow.svg" width="700" alt="Approval grant flow: agent tool call pauses at the kernel, broker writes pending grant to sqlite, user taps Allow on the Telegram card, broker releases the gate, tool resumes"></p>
 
 - **Inline cards.** Allow / Deny / Allow once / Allow for 1h. No leaving Telegram.
 - **TTL'd grants.** "Allow Bash for 1h" expires automatically. No silent permanent escalation.
@@ -115,7 +118,7 @@ Switchroom never intercepts auth, never proxies inference, never patches the CLI
 
 Each agent is a long-running service. They survive reboots, network drops, and your laptop closing. But "always on" isn't enough on its own. Things still die. The product has to handle that gracefully or the illusion breaks.
 
-<p align="center"><img src="docs/diagrams/wake-audit-lifecycle.jpg" width="700" alt="Wake-audit lifecycle: kill, crash-pane snapshot, auto-restart, agent boots with SWITCHROOM_PENDING_TURN, acks with three options"></p>
+<p align="center"><img src="docs/diagrams/wake-audit-lifecycle.svg" width="700" alt="Wake-audit lifecycle: kill, crash-pane snapshot, auto-restart, agent boots with SWITCHROOM_PENDING_TURN, acks with three options"></p>
 
 - **Auto-restart.** Agent containers come up with `restart: unless-stopped`, and each service has a healthcheck — a crashed or wedged agent is brought back automatically. No silent dropped work.
 - **Resume protocol.** When an agent reboots mid-turn, `start.sh` exports `SWITCHROOM_PENDING_TURN=true` plus the original chat / message ids. The agent's first action on boot is to acknowledge the gap and ask the user how to proceed (start over, summarise and continue, or drop it).
@@ -157,12 +160,13 @@ Then log out and back in so the docker group takes effect, and:
 
 ```bash
 switchroom setup                       # interactive: Telegram + vault + first agent
-switchroom auth add me --from-oauth    # OAuth into your Claude Pro or Max account (one flow, fleet-wide)
-switchroom apply                       # write ~/.switchroom/compose/docker-compose.yml
-docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d
+switchroom apply                       # regenerate ~/.switchroom/compose/docker-compose.yml
+docker compose -p switchroom -f ~/.switchroom/compose/docker-compose.yml up -d   # bring the fleet up
+switchroom auth add default --via-claude   # OAuth your Claude Pro/Max account — run AFTER the fleet is up
+switchroom auth use default                # make it the fleet-wide active account
 ```
 
-After the last command you talk to the agent from Telegram. You don't touch the server again.
+Auth comes *after* the fleet is up on purpose: the `switchroom-auth-broker` is the sole writer of credentials and doesn't exist until the compose stack is running (`switchroom auth …` beforehand just prints a "fleet not up" hint). After this you talk to the agent from Telegram and don't touch the server again. To catch a running host up later — pull images, refresh scaffolds, recreate — use **`switchroom update`**, not a raw `docker compose up` (a bare compose-up on a live fleet skips the operator restart-marker, so the boot cards render as crashes).
 
 ### Already have Docker + Node ≥ 20.11
 
@@ -187,7 +191,7 @@ If you already use Claude Code, this is the shortest path. Inside any session:
 
 ### Static binary (planned, not yet shipped)
 
-Pre-built single-binary releases (no Node or Bun required on the host) are scaffolded in [`install.sh`](install.sh) and referenced from the GitHub Releases page, but **the release workflow that publishes those binaries does not yet exist**. Until v0.9, use the one-script or npm paths above. Tracking work: switching the release pipeline to actually upload `switchroom-linux-{amd64,arm64}` and `switchroom-macos-{amd64,arm64}` on every tag.
+Pre-built single-binary releases (no Node or Bun required on the host) are scaffolded in [`install.sh`](install.sh) and referenced from the GitHub Releases page, but **the release workflow that publishes those binaries still does not exist as of v0.12.0**. Use the one-script or npm paths above. Tracking work: switching the release pipeline to actually upload `switchroom-linux-{amd64,arm64}` and `switchroom-macos-{amd64,arm64}` on every tag.
 
 ### One-shot happy path (no wizard)
 
@@ -292,7 +296,8 @@ Disable with `switchroom vault broker disable-auto-unlock`.
 ```bash
 switchroom setup                              # Interactive wizard
 switchroom doctor                             # Health check
-switchroom apply                              # Reconcile + (re)write docker-compose.yml; bring fleet up via `docker compose ... up -d`
+switchroom apply                              # Reconcile + regenerate docker-compose.yml (self-elevates via sudo for scaffolds). Does NOT run docker — prints the `up` command
+switchroom update [--check|--status|--rebuild] # Operator catch-up: pull images + apply + recreate fleet + doctor
 switchroom restart [agent] [--force]          # Bounce agent(s); drains in-flight turn by default
 switchroom version                            # Show versions + running agent health summary
 
@@ -304,15 +309,23 @@ switchroom agent bootstrap <name> --profile <p> --bot-token <t>  # One-shot scaf
 switchroom agent reconcile <name|all>         # Re-apply switchroom.yaml (without pulling/building)
 switchroom agent start|stop|restart <name>    # Lifecycle (with preflight)
 switchroom agent interrupt <name>             # Cancel in-flight turn without restarting
+switchroom agent unquarantine <name>          # Clear a crash-quarantine and resume supervision
 switchroom agent rename <old> <new>           # Rename an agent slug (#168)
 switchroom agent destroy <name>               # Remove from compose + scaffold dir
 switchroom agent attach <name>                # Interactive tmux session
+switchroom agent send <name> <slash-cmd>      # Inject a slash command into the agent's tmux pane
 switchroom agent logs <name> [-f]             # View logs
 switchroom agent grant <name> <tool>          # Grant a tool permission
 switchroom agent permissions <name>           # Show allow/deny list
 switchroom agent dangerous <name> [off]       # Toggle full tool access
+
+switchroom soul path|show|reset <name>        # Manage the agent's user-owned SOUL.md (persona)
+switchroom hostd install|status|uninstall|audit # Host-control daemon (/restart, /update apply, …)
+switchroom drive connect|disconnect <agent>   # Per-agent Google Drive OAuth
 ```
 
+`switchroom --help` lists every verb (also `deps`, `issues`, `migrate`).
+
 Profiles live in `profiles/` at the repo root. Bundled ones for `--profile`: `coding`, `default`, `executive-assistant`, `health-coach` (the `_base/` dir is framework-internal render templates and is not a user-selectable profile).
 
 `switchroom agent create <name> --profile <profile>` does two things in one step:
@@ -329,10 +342,11 @@ Model aliases: the bare names `opus`, `sonnet`, `haiku` are accepted alongside t
 The **Anthropic account is 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`. Per-account quota state fans out across the fleet in seconds. See [`docs/auth.md`](docs/auth.md) for the full operator guide.
 
 ```bash
-switchroom auth add <label> --from-oauth          # New account via OAuth (one flow per Anthropic account)
+switchroom auth add <label> --via-claude          # New account, broader scope — recommended for first-time
+switchroom auth add <label> --from-oauth          # Narrow scope=user:inference (rejected by agents in server: mode)
 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)
+switchroom auth add <label> --via-claude --replace     # Re-auth an existing label (drift recovery)
 
 switchroom auth list                              # Accounts + health + which one is fleet-active
 switchroom auth show [agent]                      # Full snapshot (fleet + agents + consumers), or one agent
@@ -350,7 +364,9 @@ The same surface is reachable from Telegram in any agent's chat: `/auth show` (r
 
 ### Workspace (agent bootstrap layer)
 
-Each agent has a workspace directory (`~/.switchroom/agents/<name>/workspace/`) with editable stable files (`AGENTS.md`, `SOUL.md`, `USER.md`, `IDENTITY.md`, `TOOLS.md`) and dynamic files (`MEMORY.md`, `memory/YYYY-MM-DD.md`, `HEARTBEAT.md`) that are injected into the model's context at turn time.
+Each agent has a workspace directory (`~/.switchroom/agents/<name>/workspace/`) with editable stable files (`AGENTS.md`, `USER.md`, `IDENTITY.md`, `TOOLS.md`) and dynamic files (`MEMORY.md`, `memory/YYYY-MM-DD.md`, `HEARTBEAT.md`) injected into the model's context at turn time.
+
+`SOUL.md` (the persona) is a special case since v0.12.0: it's **user-owned and seeded once** — switchroom writes it at first scaffold (from the setup wizard's persona prompts or the profile default) and then *never overwrites it*, the deliberate inverse of the switchroom-managed `CLAUDE.md`. Edit it freely; `switchroom update` won't touch it. Use `switchroom soul reset <agent>` to re-seed from the profile (it backs the old one up first). See [docs/configuration.md § Persona & SOUL.md ownership](docs/configuration.md#persona--soulmd-ownership).
 
 ```bash
 switchroom workspace path <agent>                 # Print the workspace dir
@@ -414,7 +430,7 @@ Overlay entries win on collision with built-in defaults. Unknown files that appe
 | **[Vault](docs/vault.md)** | Architecture, per-cron secrets, ACL, audit log, threat model |
 | **[Telegram Plugin](docs/telegram-plugin.md)** | Progress cards, 15 MCP tools, native checklists, sticker aliases, voice-in |
 | **[Sub-Agents](docs/sub-agents.md)** | Model routing, delegation patterns, frontmatter spec |
-| **[Scheduling](docs/scheduling.md)** | Cron tasks (per-agent scheduler container), model selection |
+| **[Scheduling](docs/scheduling.md)** | Cron tasks (in-agent scheduler sidecar), model selection |
 | **[Session Management](docs/session-optimization.md)** | Continuity, compaction, freshness policy |
 | **[OpenClaw alternative](docs/vs-openclaw.md)** | Switchroom vs OpenClaw |
 | **[NanoClaw alternative](docs/vs-nanoclaw.md)** | Switchroom vs NanoClaw |