commandmate 0.42.2 → 0.44.0

package/README.md

@@ -11,662 +11,97 @@
 
 **[commandmate website →](https://kewton.github.io/CommandMate/)**
 
+> **No long blocks of time? Run an AI team from your phone.**
+
+- 10+ PRs a day, solo
+- $110–$210 a month: Claude Max + Command Code Goat
+- ~80% of my instructions sent from a phone (my estimate)
+- 689 PRs merged in September 2026, across my repositories
+
 <p align="center">
   <img src="./docs/images/demo-hero.en.gif" width="560" alt="A list of four open issues, one message typed into the lead session, four worktree sessions in the sidebar, a worker writing a test file, and a final report with a phase-by-phase table" />
 </p>
 
-> **One agent leads. Gates decide what's done.**
-
-CommandMate gives your lead agent the machinery to run the others: one Git worktree and one contract per task, gates that decide what is done, and a record of every run. Claude Code, Codex, Antigravity, Command Code, OpenCode, Gemini CLI, Copilot and local models. You approve; you don't relay.
-
 Open source (MIT) · runs on your machine · macOS / Linux / Windows (WSL2) · no app to install
 
-```bash
-npx commandmate@latest
-```
-
-**From install to your first session in 60 seconds.** macOS / Linux / Windows (WSL2) · Node.js v22+ · npm · git · tmux
-
 ---
 
-## More agents, same you
+## The problem
 
-- The agents are parallel. You are still single-threaded.
+- The agents can work for hours. You can't sit at the desk for hours to answer them.
 - From the outside, an idle agent and one waiting on you look the same.
 - The agent's summary of what it did is not evidence of what it did.
-- Nobody can safely merge a PR that nobody understands.
-
-CommandMate puts the machinery around the CLIs you already run: a lead that hands out contracts, session state read from the agents' own hooks, gates after the work, and the record in between.
-
----
-
-## One agent leads
-
-One message to your lead session. It plans the issues — dependencies, file conflicts, waves — and hands each one to a worker in its own worktree under a contract. Gates decide which work comes back. Only what passed becomes a PR, gets merged, and goes through acceptance. Nothing mutates without an explicit approve, and a failed gate stops the run.
-
-```yaml
-# .commandmate/tasks/issue-21.yaml
-version: 1
-title: "Issue #21: pick(obj, keys)"
-goal: |
-  Implement pick(obj, keys) in src/util/pick.js with node:test cases in tests/pick.test.mjs.
-  Run npm test, then commit.
-scope:
-  allow:
-    - "src/util/pick.js"
-    - "tests/pick.test.mjs"
-verify:
-  gates: [unit]
-```
-
-> The scope gate and the work-evidence gate are built in and run on every contract; you declare only the gates that need your project's commands.
-
-### Measured
-
-| Run | Lead | Workers | Result |
-|---|---|---|---|
-| 4 issues, one message | Claude Code | 4 × Claude Code | 4/4 gates passed, 2 waves, PRs merged, UAT go, 8 min 39 s |
-| 4 issues, one message | Command Code | 4 × Command Code | 4/4 gates passed, 7 min 46 s; then a human pulled develop: 47/47 tests |
-| 1 issue, with a review step | Command Code | Codex builds, Claude Code tests, Antigravity reviews | Review REJECT → fix → APPROVE, RESULT passed |
-
-as observed
-
-The lead is a session like any other: today it has been measured with Claude Code and Command Code. Any of the eight agents can take the work. It is a run, not a resident agent: it starts on your message and ends with a report.
-
----
-
-## Verified, not vibe-checked
-
-Gates you declared decide whether the work is done, and the exit code is the verdict: `0` passed, `20` failed, `21` no evidence of work. The agent's summary of what it did is not the evidence. The run is, and `verify history` keeps it.
-
-<p align="center">
-  <img src="./docs/images/demo-contract-verify.gif" width="600" alt="A task contract is sent, the verification gates run, and the exit code returns RESULT passed" />
-</p>
-
-If this is the kind of AI development workflow you want, [give the repo a star](https://github.com/Kewton/CommandMate).
-
----
-
-## Review by another agent
-
-A session can hand its work to another session for review — `commandmate ask`, or the `cmate-delegate` Skill — and the answer comes back to the lead. In the measured run, Command Code led, Codex built, Claude Code wrote the tests, and Antigravity rejected the first version before approving the fix. This is a step you add; the orchestrate runner does not run a cross-model review for you.
-
----
-
-## Know which one needs you
-
-Waiting is a state read from the agent's hooks, not a guess from the screen. The waiting session shows up as a badge, a toast, the tab title, a PWA badge and a push notification, and you answer from your phone — no app to install.
-
-<p align="center">
-  <img src="./docs/images/demo-sessions.gif" width="560" alt="A sidebar of four sessions with one amber row marked Approve / Reject and a RESULT Passed chip in the header; the waiting session's Create File confirmation is answered with 1. Yes and the list comes back all green" />
-</p>
-
-Works on desktop and mobile — monitor and steer sessions from any browser, including your phone.
-
-<p align="center">
-  <img src="./docs/images/demo-ux.en.gif" width="600" alt="Switch repos from the tab bar, delegate to another agent from the chat, open the file it names, and do the same from a phone" />
-</p>
-
----
-
-## What it gives you
-
-### One agent leads
-
-| Feature | What it does | Why it matters |
-|---------|-------------|----------------|
-| **cmate-orchestrate Skill** | Plans several issues at once and hands each one out with its own contract: `plan` → `dispatch` → `merge` → `uat` | Nothing mutates without `--approve`, and a failed gate stops the run |
-| **Delegation between sessions** | `commandmate ask` puts a question to another session and brings the answer back; `ask --async` with `commandmate relays` when you would rather not wait, `commandmate peers` to see who is reachable, and the `cmate-delegate` Skill for the pattern | One session can hand work to another, and it works across agent CLIs |
-| **Git Worktree Sessions** | One session per worktree, parallel execution | Multiple issues progress simultaneously without interference |
-| **Multi-Agent Support** | Choose Claude Code, Codex, Gemini CLI, Copilot, OpenCode, Antigravity, Command Code or local models per worktree | Pick the right agent for each task |
-| **Auto Yes Mode** | Agent runs without stopping for confirmations | Optional unattended mode for trusted workflows — review the Security section before enabling |
-
-### Verified, not vibe-checked
-
-| Feature | What it does | Why it matters |
-|---------|-------------|----------------|
-| **Task Contract** | Declare the goal, the changeable scope and the gates before the work starts, then `send --contract` hands them to the agent | The agent works to a written definition of done instead of guessing at one |
-| **Verification Gates** | Gates declared in `.commandmate/verify.yaml` run through `verify` / `wait --verify` and return exit `0` / `20` / `21` | "Done" is what a verification run returned, not what the agent said |
-| **Evidence & Metrics** | The built-in work-evidence and scope gates, plus `verify history`, `task show` and `report metrics` | Commits, gate logs and numbers are left behind for the next decision |
-
-### Know which one needs you
-
-| Feature | What it does | Why it matters |
-|---------|-------------|----------------|
-| **Never miss a waiting agent** | A waiting agent shows up as a badge, a toast, the tab title, the PWA app badge and a push notification | You find out the moment an agent needs you, even away from the desk |
-| **Web UI (Desktop & Mobile)** | Full session control from any browser | Monitor and steer from your desk or your phone |
-| **Conversation view** | Switch a session's output between the raw terminal and a chat transcript — replies render in full, tool runs and approvals fold into chips, and a TUI dialog is answerable from the chat surface | Follow the run and answer it — from your desk or your phone — without reading the TUI |
-
-### Method as a system
-
-| Feature | What it does | Why it matters |
-|---------|-------------|----------------|
-| **Skills Catalog** | Install and update official Skills per worktree, from the web UI or `commandmate skill` | The method is installed for the agent to read, not kept in someone's head |
-| **Scheduled Execution** | Cron-based auto-run via CMATE.md | Daily reviews, nightly tests — agents work on a schedule |
-
-### Also
-
-| Feature | What it does | Why it matters |
-|---------|-------------|----------------|
-| **File Viewer & Markdown Editor** | Browse and edit worktree files in the browser | Review changes and update AI instructions without opening an IDE |
-| **Screenshot Instructions** | Attach images to your prompts | Snap a bug → "Fix this" — the agent sees the screenshot |
-| **Token Authentication** | SHA-256 hashed token + HTTPS + rate limiting | Secure remote access — no credentials leaked, brute-force protected |
-
----
-
-## Supported agents
-
-All eight are first-class. Each one gets the same treatment inside CommandMate — its own launch path, its own hook source and its own status detection — so the worktree session, the task contract, the verification gates and the evidence trail behave the same way whichever agent you pick.
-
-- **Claude Code**, **Codex**, **Gemini CLI**, **Copilot**, **Antigravity** — choose per worktree, per task.
-- **OpenCode** — the open-source terminal agent, driven through the same contract-and-gate path as the rest.
-- **Command Code** — driven the same way, its hooks and its transcript included.
-- **Local models** (`vibe-local`) — the same worktree session, contract and gates, against a model you host yourself.
-
----
-
-## What it does not do
-
-- It is a run, not a resident agent. Nothing loops forever, and nothing mutates without an explicit approve.
-- It does not read the code for you. Gates catch what your tests and checks catch.
-- Review by another agent is a step you add, not something the runner does for you.
-- Approvals still come to a person. Auto Yes is opt-in, time-boxed, and stops on the patterns you set.
-- It does not replace tmux, Git worktrees, your terminal, or your agent CLI. An OS reboot ends the processes; what survives is the record.
-
----
-
-## Use cases
-
-| Scenario | How CommandMate helps |
-|----------|----------------------|
-| **Several issues, one message** | The lead plans waves, hands out contracts, and merges only what the gates passed. You read one report. |
-| **Too many sessions to watch** | One list, one state per session, read from hooks. The waiting one floats up. |
-| **Away from the desk** | The waiting agent reaches your phone. Approve or reject there. |
-| **Review by a different agent** | Hand the diff to another session and get the verdict back in the lead's chat. |
-| **Overnight execution** | Scheduled runs with contracts and gates; read the record in the morning. |
-
----
-
-## From vibe coding to Vibe Engineering.
-
-Vibe Engineering — the AI does the building; the system, not your expertise, guarantees the engineering.
-
-We do not make the AI smarter. We make the software-engineering ability its user needed into a system.
-The contract says what done means before the work starts, the gates decide it afterwards, and the
-method that produced both is installed as Skills rather than remembered by whoever happened to run it.
-
-[Concept](./docs/en/concept.md) is the canonical text: the Vision, the Mission, and how each
-implementation item maps to a feature.
-
-> The term "vibe engineering" was coined by Simon Willison (2025) —
-> <https://simonwillison.net/2025/Oct/7/vibe-engineering/>.
 
 ---
 
-## Security
+## Three levels
 
-CommandMate runs on your machine. It sends no telemetry, needs no account, and needs no external server to run. What goes over the network depends on what you use: your agent CLI's own API calls; a check for a newer release on GitHub, from the web UI; the official Skills Catalog on GitHub, when you list or install Skills; your browser's push service, once you turn on Web Push; and Tailscale or cloudflared, while `commandmate remote` is running.
+### Level 1 — Many agents, one place, in your pocket
 
-- Fully open-source ([MIT License](./LICENSE))
-- Local database, local sessions
-- For remote access, use a tunneling service ([Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/), [ngrok](https://ngrok.com/), [Pinggy](https://pinggy.io/)), a VPN, or an authenticated reverse proxy
+Every task gets its own Git worktree and session, on whichever agent fits: Claude Code, Codex, Gemini CLI, Copilot, OpenCode (1.x and V2), Antigravity, Command Code or local models. Waiting is read from the agents' own hooks, not guessed from the screen, and reaches your phone as a badge or a push notification. You answer from the browser.
 
-See the [Security Guide](./docs/security-guide.md) and [Trust & Safety](./docs/en/TRUST_AND_SAFETY.md) for details.
-
----
+### Level 2 — Work like a team, not a chat
 
-## Install as an App (PWA)
+A task goes out with a contract — the goal, the files it may change, the gates — and comes back with a verdict: the gates' exit code (`0` passed, `20` failed, `21` no evidence of work), not the agent's summary. A session can also hand its work to another agent for review.
 
-CommandMate is a Progressive Web App. On a mobile browser, use **Add to Home Screen** to launch it full-screen (standalone), which is ideal for monitoring agents on the go. A Service Worker precaches static assets and shows an offline fallback screen; API responses, the login page, and WebSocket traffic are never cached.
+### Level 3 — An AI team that builds and maintains
 
-> **HTTPS is required for installation.** Browsers only register a Service Worker (and offer install) on `https://` or `http://localhost`. When accessing a self-hosted instance over plain HTTP on the LAN (e.g. `http://192.168.x.x:3000`), install and offline support are disabled by the browser — use a tunnel or an HTTPS reverse proxy (see Security above) to enable them. The app itself remains fully usable without the PWA layer.
+One message to a lead session: it plans several issues, hands each one to a worker under a contract, and only what passed the gates becomes a PR. Schedules keep work running while you are away. The author's daily auto-fix loop is the author's own operation built from these parts, not a switch in the product.
 
-### Phone notifications (Web Push)
-
-Once installed, CommandMate can push a notification to your phone **while the app is closed** — an agent waiting for you, a verification gate that failed, a session that could not start.
-
-**It is off until you generate a VAPID key pair.** `commandmate init` generates one and writes `CM_VAPID_PUBLIC_KEY` / `CM_VAPID_PRIVATE_KEY` / `CM_VAPID_SUBJECT` into `.env`; when they are missing, the startup log and `commandmate status` say so in one line. iOS/iPadOS additionally require the Home Screen install above — a Safari tab cannot subscribe. Full setup, including the HTTPS requirement and what to do when nothing arrives: [Web App Guide -> Phone Notifications](docs/user-guide/webapp-guide.md#phone-notifications-web-push).
+More on each level on the [website](https://kewton.github.io/CommandMate/), and the long form in [How CommandMate works](./docs/en/user-guide/how-it-works.md).
 
 ---
 
-## Browser Support
-
-The web UI is built with Tailwind CSS 4, which targets modern browsers and relies on
-`@property` and `color-mix()` for its color and theming layer. The minimum supported
-versions are:
+## Set up with your agent
 
-| Browser | Minimum version |
-|---------|-----------------|
-| Safari (macOS / iOS) | 16.4+ |
-| Chrome / Edge | 111+ |
-| Firefox | 128+ |
+Paste this into the agent CLI you already use (Claude Code, Codex, …):
 
-Older browsers will load the app but render it with degraded colors and spacing.
-CommandMate is a local developer tool, so this matches the browsers a current
-development machine or phone will already have.
-
----
-
-## How it works
-
-```mermaid
-flowchart LR
-    A["Browser / Phone"] -->|HTTP| B["CommandMate Server"]
-    L["Lead session\n(any agent)"] -->|"send --contract / ask / wait --verify"| B
-    B --> C["Session Manager"]
-    G["Task Contract\n.commandmate/tasks/*.yaml"] --> C
-    C -->|"spawn / attach"| D["tmux sessions\n(per worktree)"]
-    D --> E["Agent CLI"]
-    C <-->|"read / write"| F[("Local DB\n& State")]
-    E --> H["Verification Gates\n.commandmate/verify.yaml"]
-    H -->|"exit 0 / 20 / 21"| B
+```text
+Read https://kewton.github.io/CommandMate/setup.md and help me set up CommandMate on this machine. Explain each step before you run it, and ask me before you install anything or open access from the internet.
 ```
 
-Each Git worktree gets its own tmux session, so multiple tasks run in parallel without interference.
-The contract goes in before the session starts; the gates run after it stops, and their exit code is the verdict.
+### Or by hand
 
----
-
-<details>
-<summary><strong>Quick Start (detailed)</strong></summary>
+Requires macOS / Linux / Windows (WSL2), Node.js v22+, npm, git and tmux.
 
 ```bash
-# Try it in one command (guided setup)
-npx commandmate@latest
-
-# Or install globally — recommended if you plan to keep the server running
 npm install -g commandmate
 commandmate init
 commandmate start --daemon
 ```
 
-Always write `npx commandmate@latest`, not bare `npx commandmate`. If CommandMate is already
-installed globally, bare `npx commandmate` runs that existing binary without ever checking the
-registry, so you silently keep running an old version. `@latest` forces npx to resolve the newest
-release. This only affects `npx` — `npm install -g commandmate` always resolves from the registry.
-
-For anything beyond a first look, prefer the global install. `npx` unpacks CommandMate into the npm
-cache, and `commandmate start --daemon` runs the background server out of that cache directory — a
-later `npx` run or a cache clean can delete it out from under the running server.
-
-Running `commandmate` with no arguments walks you through the whole first run: it checks
-your dependencies, asks a few setup questions on first use, starts the server in the
-background, waits for it to come up, and opens the UI in your browser.
-
-Run it again later and it skips straight to opening the UI (or tells you the server is
-already running). Requires Node.js 22 or later.
-
-- Already have a `.env`? The setup questions are skipped.
-- Don't want the browser to open? Use `commandmate --no-open` (also skipped automatically
-  on CI and headless sessions).
-- Otherwise, open http://127.0.0.1:3000 in your browser. CommandMate binds `127.0.0.1`
-  by default, and `localhost` can resolve to `::1` (IPv6) first — an address CommandMate
-  does not listen on, and another process may.
-
-See the [CLI Setup Guide](./docs/en/user-guide/cli-setup-guide.md) for details.
-For Windows users, see the [WSL2 Setup Guide](./docs/en/user-guide/wsl2-setup.md) — CommandMate depends on tmux, so it runs on Windows via WSL2 (native Windows is not supported).
-
-</details>
-
-<details>
-<summary><strong>CLI Commands</strong></summary>
-
-### Basic
-
-| Command | Description |
-|---------|-------------|
-| `commandmate init` | Initial setup (interactive) |
-| `commandmate init --defaults` | Initial setup (default values) |
-| `commandmate init --force` | Overwrite existing configuration |
-| `commandmate start` | Start the server (foreground) |
-| `commandmate start --daemon` | Start in background |
-| `commandmate start --dev` | Start in development mode |
-| `commandmate start -p 3001` | Start on a specific port |
-| `commandmate stop` | Stop the server |
-| `commandmate stop --force` | Force stop (SIGKILL) |
-| `commandmate status` | Check status |
-| `commandmate update` | Update to the latest version |
-
-### Worktree Parallel Development
-
-Run separate servers per Issue/worktree with automatic port allocation.
-
-| Command | Description |
-|---------|-------------|
-| `commandmate start --issue 123` | Start server for Issue #123 worktree |
-| `commandmate start --issue 123 --auto-port` | Start with automatic port allocation |
-| `commandmate start --issue 123 -p 3123` | Start on a specific port |
-| `commandmate stop --issue 123` | Stop server for Issue #123 |
-| `commandmate status --issue 123` | Check status for Issue #123 |
-| `commandmate status --all` | Check status for all servers |
-
-### Agent Operations
-
-Operate agent sessions from the CLI. See the [CLI Operations Guide](./docs/en/user-guide/cli-operations-guide.md) for details.
-
-| Command | Description |
-|---------|-------------|
-| `commandmate ls` | List worktrees with status (idle/ready/running/waiting) |
-| `commandmate ls --json` | JSON output (for agent consumption) |
-| `commandmate ls --quiet` | IDs only, one per line (for piping) |
-| `commandmate ls --branch feature/` | Filter by branch name prefix |
-| `commandmate ls --id <prefix>` | Filter by worktree ID prefix |
-| `commandmate send <id> "message"` | Send a message to an agent |
-| `commandmate send <id> "msg" --auto-yes` | Send with auto-yes enabled |
-| `commandmate send <id> "msg" --instance codex` | Send to a specific agent instance |
-| `commandmate wait <id> --timeout 300` | Wait for agent completion (exit 0) or prompt (exit 10) |
-| `commandmate wait <id> --instance codex` | Wait on a specific agent instance |
-| `commandmate wait <id> --on-prompt human` | Wait, let human respond to prompts via browser UI |
-| `commandmate respond <id> "yes"` | Respond to an agent's prompt |
-| `commandmate capture <id>` | Get current terminal output |
-| `commandmate capture <id> --json` | Get output with status info as JSON |
-| `commandmate auto-yes <id> --enable` | Enable auto-yes (default 1h) |
-| `commandmate auto-yes <id> --disable` | Disable auto-yes |
-
-> **Name the target with `--instance`, on every command.** It is the only target
-> flag `wait` accepts — `wait --agent` fails with `unknown option`. Naming the
-> agent only on `send` leaves `wait` watching the worktree's *default* agent, so
-> a worktree cut for Codex silently waits for Claude Code. `--agent` still works
-> on `send`/`respond`/`capture`/`auto-yes` as the supplement for instances the
-> roster does not know (it is what `--register` needs). See the
-> [CLI Operations Guide](./docs/en/user-guide/cli-operations-guide.md).
-
-**Typical workflow:**
-
-```bash
-WT=$(commandmate ls --branch feature/101 --quiet)
-commandmate send "$WT" "Implement Issue #101" --auto-yes
-commandmate wait "$WT" --timeout 600
-commandmate capture "$WT"
-```
-
-**For coding agents (Claude Code, Codex, etc.):** Have your agent run these commands to get the full guide and workflow samples:
-
-```bash
-commandmate docs --section agent-operations          # Full guide
-commandmate docs --section agent-operations-samples  # Workflow samples
-```
-
-### GitHub Issue Management
-
-Requires [gh CLI](https://cli.github.com/) to be installed.
-
-| Command | Description |
-|---------|-------------|
-| `commandmate issue create` | Create a new issue |
-| `commandmate issue create --bug` | Create with bug report template |
-| `commandmate issue create --feature` | Create with feature request template |
-| `commandmate issue create --question` | Create with question template |
-| `commandmate issue create --title <title>` | Specify issue title |
-| `commandmate issue create --body <body>` | Specify issue body |
-| `commandmate issue create --labels <labels>` | Add labels (comma-separated) |
-| `commandmate issue search <query>` | Search issues |
-| `commandmate issue list` | List issues |
-
-### Documentation
-
-| Command | Description |
-|---------|-------------|
-| `commandmate docs` | Show documentation |
-| `commandmate docs -s <section>` | Show a specific section |
-| `commandmate docs -q <query>` | Search documentation |
-| `commandmate docs --all` | List all available sections |
-
-See `commandmate --help` for all options.
-
-</details>
-
-<details>
-<summary><strong>Update</strong></summary>
-
-If you installed globally (`npm install -g commandmate`), one command does everything —
-it stops the server, installs the latest version, restarts it, and checks that it came back up.
-
-```bash
-# See whether an update is available (changes nothing)
-commandmate update --check
-
-# Update (asks for confirmation)
-commandmate update
-
-# Non-interactive environments (CI, scripts) require --yes
-commandmate update --yes
-```
-
-**Your data is safe.** Database migrations run automatically the next time the server starts,
-so your worktrees, sessions, and settings carry over. There is no manual migration step.
-
-**Manual update (fallback)** — if `commandmate update` is unavailable:
-
-```bash
-commandmate stop
-npm install -g commandmate@latest
-commandmate start --daemon
-```
-
-Notes:
-
-- After updating, the server restarts using only your `.env`. If you had started it with flags
-  such as `--auth` / `--cert` / `--key` / `--allowed-ips` / `--trust-proxy` / `--port`, start it
-  again manually with those flags (`--auth` generates a new token on each start).
-- Worktree servers (`--issue`) are not stopped automatically. Stop them with
-  `commandmate stop --issue <number>` **before** updating.
-- On permission errors (EACCES), don't re-run with `sudo` — fix your npm global directory
-  permissions using the [CLI Setup Guide](./docs/en/user-guide/cli-setup-guide.md).
-
-See the [Deployment Guide](./docs/en/DEPLOYMENT.md) for exit codes and details.
-
-</details>
-
-<details>
-<summary><strong>Troubleshooting & FAQ</strong></summary>
-
-### Claude CLI not found / path changed?
-
-If you switch between npm and standalone versions of Claude CLI, the path may change. CommandMate auto-detects the new path on the next session start. To set a custom path, add `CLAUDE_PATH=/path/to/claude` to `.env`.
-
-### Port conflict?
-
-```bash
-commandmate start -p 3001
-```
-
-### Session stuck or not responding?
-
-Look at the session with CommandMate's own commands — they resolve the tmux session name for you:
-
-```bash
-# What every worktree's agent is doing, and the tmux session it runs in
-commandmate ls
-commandmate ls --json | jq -r '.[] | "\(.id)\t\(.tmuxSession)"'
-
-# Read the transcript WITHOUT attaching
-commandmate capture <worktree-id> --pane --tail 60
-commandmate capture <worktree-id> --pane --follow    # follow a reply as it is generated
-
-# Attach this terminal (detach with Ctrl+b then d)
-commandmate attach <worktree-id>
-commandmate attach <worktree-id> --live              # re-lay out to your terminal (claude only)
-```
-
-**Why a bare `tmux attach` looks empty.** A CommandMate session is pinned to a 200x1000 canvas so
-`capture-pane` keeps enough history for status detection. Alternate-screen agents (claude / opencode /
-copilot) draw their transcript at the top of that canvas and their composer at the bottom, and tmux
-follows the cursor — so a normal-sized terminal sees the composer, blank rows, and not one line of the
-conversation. Nothing is broken. Read it with `capture --pane` above, with `prefix + g` while
-attached, or hand the window to your terminal with `attach --live`.
-
-From tmux itself, without attaching at all:
-
-```bash
-tmux ls -F '#{session_name} #{@cm_status} #{@cm_tool}/#{@cm_instance}'
-
-# Kill a broken session (`=name:` is an exact match; quote it — zsh eats a bare `=`)
-tmux kill-session -t '=mcbd-claude-feature-123:'
-```
-
-> **Note:** When attached, avoid typing directly into the session — this can interfere with CommandMate's session management. Use `Ctrl+b` then `d` to detach and operate through the CommandMate UI instead.
-
-### Sessions fail when launching from within Claude Code?
-
-Claude Code sets `CLAUDECODE=1` to prevent nesting. CommandMate removes this automatically, but if it persists, run: `tmux set-environment -g -u CLAUDECODE`
-
-### FAQ
-
-**Q: How do I use CommandMate from my phone?**
-A: Run `commandmate remote`. One command starts the server with authentication enabled, opens a tunnel, and prints a QR code in your terminal — scan it with your phone's camera and you are signed in. The pairing code inside that QR works **once** and expires after 10 minutes by default.
-
-```bash
-commandmate remote          # start + publish + pair (QR)
-commandmate remote status   # provider, URL, expiry, pairing state
-commandmate remote stop     # close the outside door (the server keeps running)
-```
-
-It needs [`cloudflared`](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/) installed. Because a Cloudflare Quick Tunnel puts a `https://<random>.trycloudflare.com` address on the public internet, `commandmate remote` warns you and asks before creating it; in a non-interactive shell it refuses instead of assuming yes, so pass `--yes` when you mean it. If no provider is usable it stops with a dependency error rather than falling back to something more exposed. Your `CM_BIND` setting is left alone — the server stays bound to `127.0.0.1`, and `remote` only adds a door in front of it.
-
-**If you would rather not install `cloudflared`**, you can stay inside your LAN: run `commandmate init` and enable external access — this sets `CM_BIND=0.0.0.0` — then open `http://<your-PC-IP>:3000` from a phone on the same Wi-Fi. **Be aware of what that does: it serves CommandMate with no authentication and no encryption.** Anyone on that network can open the URL and drive your repositories, terminals and agents without being asked for anything. Use it only on a network you trust, never on shared or guest Wi-Fi, and set `CM_BIND` back to `127.0.0.1` when you are done.
-
-**Q: Can I access it from outside my home network?**
-A: Yes — `commandmate remote` (above) is the built-in way: the tunnel it creates is reachable from anywhere, and CommandMate answers it with token authentication on. The URL itself is public, so treat the pairing code, not the URL, as the thing that keeps other people out.
-
-If you would rather run the tunnel yourself, any of these work:
-
-- [Cloudflare Tunnel](https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/) — free, requires Cloudflare account
-- [ngrok](https://ngrok.com/) — free tier available, easy setup
-- [Pinggy](https://pinggy.io/) — no sign-up required, simple SSH-based tunnel
-
-Alternatively, a VPN or an authenticated reverse proxy (Basic Auth, OIDC, etc.) also works. **Do not** expose the server directly to the internet without authentication. See the [Security Guide](./docs/security-guide.md) for details.
-
-**Q: Does it work on iPhone / Android?**
-A: Yes. CommandMate's Web UI is responsive and works on any modern mobile browser (Safari, Chrome, etc.). No app install required.
-
-**Q: Is tmux required?**
-A: CommandMate uses tmux internally to manage CLI sessions. You don't need to operate tmux directly — CommandMate handles it for you.
-
-**Q: What about Claude Code's permissions?**
-A: Claude Code's own permission settings apply as-is. CommandMate does not expand permissions. See [Trust & Safety](./docs/en/TRUST_AND_SAFETY.md) for details.
-
-**Q: Can multiple people use it?**
-A: Currently designed for individual use. Simultaneous multi-user access is not supported.
-
-</details>
-
-<details>
-<summary><strong>Developer Setup</strong></summary>
-
-For contributors or those building a development environment:
-
-```bash
-git clone https://github.com/Kewton/CommandMate.git
-cd CommandMate
-./scripts/setup.sh  # Auto-runs dependency check, env setup, build, and launch
-```
-
-### Manual Setup (for customization)
-
-```bash
-git clone https://github.com/Kewton/CommandMate.git
-cd CommandMate
-./scripts/preflight-check.sh          # Dependency check
-npm install
-./scripts/setup-env.sh                # Interactive .env generation
-npm run db:init
-npm run build
-npm start
-```
-
-> **Note**: `./scripts/*` scripts are only available in the development environment. For global installs (`npm install -g`), use the `commandmate` CLI.
+- Open http://127.0.0.1:3000. CommandMate binds `127.0.0.1` by default, and `localhost` can resolve to `::1` (IPv6) first — an address CommandMate does not listen on, and another process may.
+- To try it without installing, run `npx commandmate@latest` (always with `@latest`). The [CLI Setup Guide](./docs/en/user-guide/cli-setup-guide.md) covers why, plus WSL2, updating and building from source.
+- Phone notifications stay off until `commandmate init` has written `CM_VAPID_PUBLIC_KEY` / `CM_VAPID_PRIVATE_KEY` / `CM_VAPID_SUBJECT` into `.env`. See [Web App Guide → Phone Notifications](./docs/en/user-guide/webapp-guide.md#phone-notifications-web-push).
+- To reach it from your phone, run `commandmate remote`: it publishes the server through Tailscale or Cloudflare (asking before anything goes on the public internet) and prints a QR code to pair with.
 
-</details>
-
----
+First commands, for you or for your agent:
 
-<details>
-<summary><strong>With / Without CommandMate</strong></summary>
+| Command | What it does |
+|---------|--------------|
+| `commandmate status` | Is the server up, and is push configured |
+| `commandmate remote` | Pair your phone with a QR code |
+| `commandmate ls` | Every worktree and the state of its session |
+| `commandmate send <id> "Implement Issue #101" --instance codex` | Send a message to one agent's session |
+| `commandmate send <id> --contract .commandmate/tasks/issue-101.yaml --instance codex` | Hand over a task contract |
+| `commandmate wait <id> --instance codex --verify` | Wait for the agent, then run the gates: exit `0` / `20` / `21` |
+| `commandmate capture <id>` | Read the session's current output |
+| `commandmate respond <id> "yes"` | Answer the prompt the agent is waiting on |
+| `commandmate skill list` | The official Catalog Skills you can install per worktree |
+| `commandmate update` | Update a global install and restart the server |
+| `commandmate docs --section agent-operations` | The full command guide, for your agent to read |
 
-The comparison that matters is not against other products; it is against the way of working.
-
-| Dimension | Vibe coding | Vibe Engineering with CommandMate |
-|---|---|---|
-| What "done" means | The agent says it's done | A verification run says so — exit 0 / 20 / 21 |
-| Scope of change | Whatever the agent touched | Declared in the contract, enforced by the scope gate |
-| Method | In someone's head | Installed as Skills from the Catalog (`cmate-task-contract`, `cmate-verify`, …) |
-| Evidence | A chat transcript | Commits, gate logs, `verify history`, `report metrics` |
-| Parallel work | Terminal tabs | One worktree and one contract per task |
-| When it stops | You notice, eventually | Waiting is surfaced: badge, toast, tab title, push |
-| Which agent | Locked to one | Claude Code, Codex, Gemini CLI, Copilot, OpenCode, Antigravity, Command Code, local models |
-
-</details>
+Every command and flag is in the [CLI Operations Guide](./docs/en/user-guide/cli-operations-guide.md); `commandmate --help` lists the options.
 
 ---
 
-## Vibe Engineering workflow
-
-<a id="issue-driven-development"></a>
-
-The system is three things you can hand to any agent: the method, as installed Skills; the contract,
-declared before the work; the gates, which decide afterwards whether the work is done.
-
-```
-Requirement → Contract → Agent runs (any CLI, per worktree) → Verified result
-```
-
-### 1. Install the method as Skills
-
-Skills come from the official Catalog
-([Kewton/commandmate-skills](https://github.com/Kewton/commandmate-skills)) and install into the
-worktree you choose — from the web UI (`/skills`, or the Skills pane of a worktree) or from the CLI.
-
-```bash
-commandmate skill list
-commandmate skill install cmate-task-contract --worktree <worktree-id> --version <version> --yes
-```
-
-| Skill | What it covers |
-|-------|----------------|
-| `cmate-issue-authoring` | Turns a feature description into a set of implementable issues |
-| `cmate-issue-refinement` | Refines a vague issue into an implementable specification, read-only |
-| `cmate-task-contract` | Drafts `.commandmate/tasks/<name>.yaml` from an issue: goal, scope, gates |
-| `cmate-verify` | Declares the gates in `.commandmate/verify.yaml` and runs them for a real exit code |
-| `cmate-verify-advisor` | Proposes gate improvements from the verification history |
-| `cmate-worker-development` | The six steps a worker follows: read, investigate, plan, implement, verify, evidence |
-| `cmate-acceptance-test` | Checks the issue's acceptance criteria and returns Go / Conditional Go / No-Go |
-| `cmate-orchestrate` | Plans several issues in parallel, dispatches them with contracts, judges by exit code |
-
-The Catalog also publishes `cmate-repository-analysis`, `cmate-orchestrate-monitor`,
-`cmate-worktree-setup` and `cmate-worktree-cleanup`. See the
-[Skills guide](./docs/user-guide/skills.md) for the support matrix, the install roots, and the
-rollback story.
-
-### 2. Declare the contract, then let the gates judge
-
-```bash
-# .commandmate/tasks/issue-123.yaml declares goal, scope.allow / scope.deny and the gates to run
-commandmate send <worktree-id> --contract .commandmate/tasks/issue-123.yaml
-commandmate wait <worktree-id> --verify
-```
-
-`--contract` supplies the message, so you do not pass one yourself. `wait --verify` runs the gates
-once the agent stops and returns the verdict as its exit code: **0** everything passed, **20** a gate
-failed, **21** the work-evidence gate found neither a commit nor an uncommitted change.
-
-The contract format is specified in [Task Contract](./docs/design/task-contract.md), the gate format
-in [Verification gates](./docs/design/verification-config.md) — both specifications are written in
-Japanese, but the YAML they specify is the same on either side.
-
-### Read next
-
-| Document | What it gives you |
-|----------|-------------------|
-| [Concept](./docs/en/concept.md) | The Vision, the Mission, and how each implementation item maps to a feature |
-| [Tutorial](./docs/en/user-guide/tutorial.md) | Fork a sample repository and run one task through contract and verification in about fifteen minutes |
-| [Product Highlights](./docs/en/features/product-highlights.md) | A feature-by-feature tour of the product |
-| [CLI Operations Guide](./docs/en/user-guide/cli-operations-guide.md) | Every agent-facing command, in depth |
+## What it does not do
 
-> **Developing CommandMate itself?** The `/work-plan`, `/pm-auto-dev` and other slash commands under
-> `.claude/commands` belong to **this repository only** — they are not installed into yours, and the
-> portable equivalents are the Catalog Skills above. See the
-> [Commands guide](./docs/en/user-guide/commands-guide.md).
+- It is a run, not a resident agent. Nothing loops forever, and nothing mutates without an explicit approve.
+- It does not read the code for you. Gates catch what your tests and checks catch.
+- Review by another agent is a step you add, not something the runner does for you.
+- Approvals still come to a person. Auto Yes is opt-in, time-boxed, and stops on the patterns you set.
+- It does not replace tmux, Git worktrees, your terminal, or your agent CLI. An OS reboot ends the processes; what survives is the record.
 
 ---
 
@@ -674,19 +109,22 @@ Japanese, but the YAML they specify is the same on either side.
 
 | Document | Description |
 |----------|-------------|
-| [CLI Setup Guide](./docs/en/user-guide/cli-setup-guide.md) | Installation and initial setup |
+| [How CommandMate works](./docs/en/user-guide/how-it-works.md) | The long form: measured runs, feature tables, use cases, supported agents, security, the Vibe Engineering workflow |
 | [Tutorial](./docs/en/user-guide/tutorial.md) | Fork a sample repository and go from contract to verified result in about fifteen minutes |
-| [Web App Guide](./docs/en/user-guide/webapp-guide.md) | Basic web app operations |
-| [Quick Start](./docs/en/user-guide/quick-start.md) | Using Claude Code commands |
+| [Quick Start](./docs/en/user-guide/quick-start.md) | The minimum contract-and-verify loop on any agent, then a five-minute development flow |
+| [CLI Setup Guide](./docs/en/user-guide/cli-setup-guide.md) | Installation, `npx`, initial setup, updating, building from source |
 | [CLI Operations Guide](./docs/en/user-guide/cli-operations-guide.md) | Driving sessions from the CLI: execution contracts, verification gates, Skills, agent instances |
-| [Concept](./docs/en/concept.md) | The canonical Vision, Mission and core principle, and how each implementation item maps to a feature |
-| [Product Highlights](./docs/en/features/product-highlights.md) | A feature-by-feature tour of the product |
+| [Web App Guide](./docs/en/user-guide/webapp-guide.md) | The web UI, phone access, app install (PWA), push notifications, supported browsers |
+| [Troubleshooting & FAQ](./docs/en/user-guide/troubleshooting.md) | Stuck sessions, an empty-looking `tmux attach`, port conflicts, phone and remote access |
 | [Skills Guide](./docs/en/user-guide/skills.md) | Installing official Catalog Skills into a worktree |
+| [OpenCode V2 guide](./docs/en/user-guide/opencode-v2.md) | Running OpenCode V2 next to OpenCode 1.x |
 | [Agent Event Hooks](./docs/en/user-guide/agent-event-hooks.md) | Structured agent events instead of terminal scraping |
+| [Concept](./docs/en/concept.md) | The canonical Vision, Mission and core principle, and how each implementation item maps to a feature |
+| [Product Highlights](./docs/en/features/product-highlights.md) | A feature-by-feature tour of the product |
+| [Security Guide](./docs/en/security-guide.md) | No telemetry, no account; authentication and remote access |
+| [Trust & Safety](./docs/en/TRUST_AND_SAFETY.md) | Security and permissions |
 | [Architecture](./docs/en/architecture.md) | System design |
 | [Deployment Guide](./docs/en/DEPLOYMENT.md) | Production environment setup |
-| [UI/UX Guide](./docs/en/UI_UX_GUIDE.md) | UI implementation details |
-| [Trust & Safety](./docs/en/TRUST_AND_SAFETY.md) | Security and permissions |
 
 ## Contributing