@doriandev/devcc 0.1.2 → 0.3.0

package/README.md

@@ -1,50 +1,76 @@
 # Dev Command Center
 
-A single keyboard-driven screen that replaces the pile of terminal tabs you keep
-open while working on a project. Built with [OpenTUI](https://opentui.com).
+[![npm](https://img.shields.io/npm/v/@doriandev/devcc)](https://www.npmjs.com/package/@doriandev/devcc)
+[![license](https://img.shields.io/npm/l/@doriandev/devcc)](LICENSE)
 
-## What it is for
+A single keyboard-driven screen that replaces the pile of terminal tabs you keep open while working on a
+project. Built with [OpenTUI](https://opentui.com).
 
-Working on a real project normally means one tab running `next dev`, another for
-`git status`, another for `pnpm test`, another where you `docker ps` or check
-whether Postgres is up, and a fifth for actually typing commands. State ends up
-scattered: you cannot see at a glance whether the dev server is up, whether your
-tree is dirty, or which of those tabs has the error in it.
+## Quick start
 
-Dev Command Center puts that in one place.
-
-- **Watches** - git branch and changes, which services are actually listening
-  (Docker, Postgres, Redis, Ollama, a framework dev server), host CPU / memory /
-  disk, and outdated dependencies.
-- **Controls** - starts, stops and restarts the dev processes you declare in
-  `.devcc.ts`; runs your `package.json` scripts; stages, commits, pulls and
-  pushes.
-- **Collects** - everything it launches streams into one log viewer, per source
-  or merged and searchable, so the error you are chasing is not in a tab you
-  have scrolled away from.
-
-### More than a launcher
-
-Three things it does that running the commands by hand does not:
-
-- **Brings a stack up in order.** `dependsOn` plus a readiness check means `web`
-  waits until `api` is genuinely accepting connections, not merely spawned.
-- **Recovers from crashes.** Opt-in automatic restarts with exponential backoff,
-  and it gives up rather than thrashing.
-- **Holds several projects open at once.** Each keeps its processes alive in the
-  background while you flip between them with `ctrl+o`.
-
-### Where the line is
-
-It is not a terminal replacement - there is no shell in it, and it will not run
-interactive commands. It is not a deploy tool or a container manager; it observes
-Docker rather than replacing compose. And it deliberately will not touch
-processes it did not start: anything you launched in another tab shows up as
-detected and read-only.
+```bash
+npm i -g @doriandev/devcc     # or: pnpm add -g @doriandev/devcc
+cd ~/code/example.com
+devcc init --agent claude     # optional: let an agent write .devcc.ts (or: devcc init)
+devcc
+```
 
-It earns its place on projects with more than one long-running process, or when
-you bounce between repositories. For a single `next dev` you would barely notice
-the difference - the payoff scales with how many moving parts your setup has.
+You need [Bun](https://bun.sh) 1.3+ installed (or Node 26.4+, see [Requirements](#requirements)). No
+configuration is needed to get a useful screen. Press `?` inside the app for the manual.
+
+In scripts, CI and AI coding agents, `devcc verify` is the project's quality gate: it runs your checks and
+exits 0 only when all of them pass (see [Verification](#verification)).
+
+## Contents
+
+- [Why devcc](#why-devcc)
+- [At a glance](#at-a-glance)
+- [Requirements](#requirements)
+- [Usage](#usage)
+- [Worktrees and AI agents](#worktrees-and-ai-agents)
+- [Verification](#verification)
+- [Environment](#environment)
+- [Remote machines](#remote-machines)
+- [Configuration](#configuration)
+- [Keyboard shortcuts](#keyboard-shortcuts)
+- [Known limitations](#known-limitations)
+- [Contributing](#contributing)
+
+## Why devcc
+
+Working on a real project normally means one tab running `next dev`, another for `git status`, another
+for `pnpm test`, another where you `docker ps` or check whether Postgres is up, and a fifth for actually
+typing commands. You cannot see at a glance whether the dev server is up, whether your tree is dirty, or
+which tab has the error in it.
+
+devcc puts that in one place:
+
+- **Watches** git branch and changes, which services are actually listening (Docker, Postgres, Redis,
+  Ollama, a framework dev server), host CPU / memory / disk, and outdated dependencies.
+- **Controls** the dev processes you declare in `.devcc.ts` (start, stop, restart), runs your
+  `package.json` scripts, and stages, commits, pulls and pushes.
+- **Collects** everything it launches into one log viewer, per source or merged and searchable.
+
+It also does things that running the commands by hand does not:
+
+- **Brings a stack up in order.** `dependsOn` plus a readiness check means `web` waits until `api` is
+  genuinely accepting connections, not merely spawned.
+- **Recovers from crashes.** Opt-in automatic restarts with exponential backoff, and it gives up rather
+  than thrashing.
+- **Holds several projects open at once.** Each keeps its processes alive in the background while you flip
+  between them with `ctrl+o`.
+- **Runs AI agents side by side.** Claude Code and Codex, each in its own git worktree, with their output
+  in the log viewer.
+- **Gates the work.** `devcc verify` runs the same checks for you, for CI and for an agent, with an exit
+  code that means something.
+
+**What it is not.** It is not a terminal replacement: there is no shell in it and it will not run
+interactive commands. It is not a deploy tool or a container manager; it observes Docker rather than
+replacing compose. It orchestrates git, mise, direnv, Claude Code, Codex, Tailscale, SSH and Ollama; it
+replaces none of them. It will never touch a process it did not start.
+
+It pays off on projects with more than one long-running process, or when you bounce between repositories.
+For a single `next dev` you would barely notice the difference.
 
 ## At a glance
 
@@ -71,263 +97,273 @@ the difference - the payoff scales with how many moving parts your setup has.
 
 ## Requirements
 
-OpenTUI renders through a native Zig core over FFI, so the dashboard needs one
-of:
+OpenTUI renders through a native Zig core over FFI, so the dashboard needs one of:
 
 - **Bun 1.3.0 or newer** (recommended), or
 - **Node.js 26.4.0 or newer**, started with `--experimental-ffi`
 
-The `devcc` launcher detects this for you: run it with any Node ≥ 20 and it will
-re-exec into Bun (or into Node with the right flag) automatically. Dependency
-installation, linting, type checking and the unit tests all run on plain Node.
+You do not have to pick. The `devcc` launcher runs on any Node ≥ 20 and re-execs into Bun, or into Node
+with the right flag, automatically. If neither is available it says so and stops.
 
-## Install and run
-
-```bash
-npm i -g @doriandev/devcc     # or: pnpm add -g @doriandev/devcc
-cd ~/code/example.com
-devcc
-```
+## Usage
 
-`devcc` runs against the project you are standing in. To point it somewhere else
-without changing directory:
+`devcc` runs against the project you are standing in. To point it somewhere else:
 
 ```bash
 devcc -C ~/code/example.com
 ```
 
-### CLI options
-
-| Option              | Description                                       |
-| ------------------- | ------------------------------------------------- |
-| `-C`, `--cwd <dir>` | Project directory (default: nearest project root) |
-| `-h`, `--help`      | Show usage                                        |
-| `-v`, `--version`   | Show the version                                  |
-
-`DEVCC_LOG_LEVEL` (`debug` \| `info` \| `warn` \| `error` \| `silent`) controls
-the internal diagnostics log written to `.devcc/devcc.log`.
-
-### Running from source
+| Command                        | What it does                                                  |
+| ------------------------------ | ------------------------------------------------------------- |
+| `devcc`                        | Open the dashboard                                            |
+| `devcc verify [--json]`        | Run the project's verification steps; exit 0 only if all pass |
+| `devcc worktree list [--json]` | List git worktrees                                            |
+| `devcc env [--json]`           | Report installed tools, mise runtimes and direnv status       |
+| `devcc init`                   | Write a starter `.devcc.ts` from what devcc detects           |
+| `devcc init --agent <id>`      | Let Claude Code or Codex inspect the project and set it up    |
+| `devcc init --prompt`          | Print that setup prompt for any other agent                   |
+| `devcc config check [--json]`  | Validate the config; exit 0 only when it has no issues        |
+
+| Option              | Description                                              |
+| ------------------- | -------------------------------------------------------- |
+| `-C`, `--cwd <dir>` | Project directory (default: nearest project root)        |
+| `--json`            | One JSON document on stdout, no colour or escape codes   |
+| `--force`           | `init`: replace an existing `.devcc.ts` with the starter |
+| `-h`, `--help`      | Show usage                                               |
+| `-v`, `--version`   | Show the version                                         |
+
+`verify`, `worktree list`, `env`, `init` and `config check` do not load the dashboard, so they run on any Node ≥ 20 without Bun,
+which is what you want in CI or inside an agent's sandbox.
 
 ```bash
-git clone https://github.com/dordevgit/devcc.git
-cd devcc
-pnpm install
-pnpm dev:center                          # launch against this repo
-node bin/devcc.mjs -C ~/code/example.com # or against another project
-pnpm build                               # compile to dist/
+devcc verify                         # human-readable, failing output shown inline
+devcc verify --json | jq .summary    # "4/5 passed, 1 failed (Tests)"
+devcc worktree list --json | jq -r '.worktrees[].path'
+devcc env                            # what is installed on this machine
 ```
 
-## How much setup is needed
-
-Two prerequisites, then nothing else is required to get a useful screen:
+Set `DEVCC_LOG_LEVEL` (`debug` \| `info` \| `warn` \| `error` \| `silent`) to control the internal
+diagnostics log written to `.devcc/devcc.log`.
 
-1. **Install it** - `npm i -g @doriandev/devcc`.
-2. **A runtime with FFI** - Bun ≥ 1.3, or Node ≥ 26.4 run with
-   `--experimental-ffi` (see [Requirements](#requirements)). The launcher
-   handles this for you if Bun is installed; if neither is available it says so
-   and stops.
+## Worktrees and AI agents
 
-### What works with no configuration
+Press `w` (or `0`) for the Worktrees view: every git worktree of the repository, and below them the AI
+agents devcc has started. The worktree devcc is running in is marked `●`.
 
-Run `devcc` in `~/code/example.com` having written nothing, and it works these
-out for itself:
-
-| It figures out  | How                                                                                                                                                                                      |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Project root    | Walks up from the working directory looking for `package.json` or `.git`                                                                                                                 |
-| Package manager | `packageManager` field → lockfile → the manager that launched it → npm                                                                                                                   |
-| Your scripts    | Reads `scripts` from `package.json`                                                                                                                                                      |
-| Git state       | Runs `git status --porcelain=v2` directly - branch, staged/modified/untracked, ahead/behind, recent commits                                                                              |
-| Local services  | TCP-probes Postgres, Redis and Ollama; queries the Docker daemon and any compose file; infers dev-server ports from your dependencies (`next` → 3000, `vite` → 5173, `typesense` → 8108) |
-| Host metrics    | Node's `os` and `fs` APIs - CPU, memory, disk, load, uptime                                                                                                                              |
-| Tool versions   | `git`, `docker` and your package manager, read once in the background                                                                                                                    |
+```
+WORKTREES
+● main                     ~/code/devcc                          main
+○ feature/ai-agents        ~/code/devcc-feature-ai-agents   1 agent ▸
+○ fix/process-restart      ~/code/devcc-fix-process-restart
+
+AI AGENTS
+● running  Claude Code  feature/ai-agents      Add retry to the process manager   2m 10s
+○ stopped  Codex        fix/process-restart    Find why restart loses the pid     exit 0
+```
 
-That is real detection rather than defaults, so Overview, Scripts, Git, Services
-and System are all populated on first launch.
+**Worktrees.** `n` asks for a branch (created if it does not exist), a base (default: your current branch)
+and a directory (default: `../<repo>-<branch>`), then runs `git worktree add`. `d` removes the selected
+worktree after a confirmation, with plain `git worktree remove`: devcc never passes `--force`, so git
+refuses when there are uncommitted or untracked changes, and devcc shows that refusal. It also refuses
+to remove the main worktree, the one it is running in, or one where an agent is still working. `o` opens a
+worktree as another project in devcc, `t` opens a terminal there, `e` opens your editor.
 
-### What does require configuration
+**AI agents** (optional: needs the `claude` or `codex` CLI). With a worktree selected, `c` launches Claude
+Code and `x` launches Codex. devcc asks for the task and starts the agent with that worktree as its working
+directory. Agents run non-interactively (`claude -p <task>`, `codex exec <task>`) as managed processes:
+their output streams into the Logs view (`enter` on a session), `s` stops one, and quitting devcc stops
+them all. For an interactive session, open a terminal in the worktree with `t` and run the agent there.
 
-**Managed processes.** devcc cannot guess that `pnpm dev` is the thing you want
-it to own, that it should wait for port 3000 before calling it ready, or that it
-is safe to restart. Nothing is launched or controlled until you declare it in
-`.devcc.ts`:
+devcc passes no permission flags of its own, so each agent runs with its own defaults, and headless Claude
+Code cannot edit files by default. Grant what you are comfortable with in config:
 
 ```ts
-// ~/code/example.com/.devcc.ts
-export default {
-  processes: [
-    {
-      id: "web",
-      name: "Next.js",
-      command: "pnpm",
-      args: ["dev"],
-      url: "localhost:3000",
-      readiness: { port: 3000 }, // "running" means actually serving
-      restartOnCrash: true, // comes back after a crash, with backoff
-    },
-  ],
-  commands: [
-    {
-      id: "migrate",
-      title: "Run migrations",
-      category: "Database",
-      command: "pnpm",
-      args: ["db:migrate"],
-      confirm: true, // asks first: it mutates the database
-    },
-  ],
+agents: {
+  claude: { args: ["--permission-mode", "acceptEdits"] },
+  codex: { args: ["--sandbox", "workspace-write"] },
 }
 ```
 
-Restart devcc and the Processes pane is live: `s` starts or stops, `r` restarts,
-`enter` jumps to that process's logs, and quitting stops everything devcc
-started. The declared command appears in the palette (`/`) and asks before it
-runs.
+## Verification
 
-This is deliberate. The alternative is a tool that spawns processes you did not
-ask for, and devcc will never touch a process it did not start - see
-[Configuration](#configuration) for every available field.
+Declare the checks that decide whether the project can ship:
 
-## Keyboard shortcuts
+```ts
+// command ids from `commands`, package.json script names, or inline steps
+verify: ["format:check", "lint", "typecheck", "test", "build"],
+```
 
-Press `?`, `F1` or `ctrl+k` in the app for the manual, which also explains what each section is for and the main config fields.
+A name is looked up in `commands` first, then in `package.json` scripts, so you rarely need to repeat
+anything. An inline step is `{ id, name?, command, args?, cwd? }`.
 
-### Global
+```
+$ devcc verify
+devcc verify · ~/code/shop · 3 step(s)
+
+→ lint: pnpm run lint
+✓ lint (2.7s)
+→ test: pnpm run test
+✗ test (1.7s · exit 1)
+    FAIL  tests/cart.test.ts > applies the discount
+    AssertionError: expected 90 to be 81
+→ build: pnpm run build
+✓ build (6.0s)
+
+✗ 2/3 passed, 1 failed (test) in 10.4s
+```
 
-| Key                   | Action                                                    |
-| --------------------- | --------------------------------------------------------- |
-| `↑` / `k`, `↓` / `j`  | Previous / next item                                      |
-| `←` / `h`, `→`        | Previous / next section                                   |
-| `tab`, `shift+tab`    | Cycle sections                                            |
-| `1`…`9`               | Jump straight to a section                                |
-| `p`, `g`, `l`, `d`    | Processes, Git, Logs, Dependencies                        |
-| `enter`               | Open / activate the selection                             |
-| `esc`                 | Close an overlay                                          |
-| `/`                   | Command palette                                           |
-| `ctrl+p`              | Open another project (others keep running)                |
-| `ctrl+o`              | Cycle through open projects                               |
-| `?` / `F1` / `ctrl+k` | The in-app manual (also "Open the manual" in the palette) |
-| `shift+R`             | Refresh everything                                        |
-| `q` or `ctrl+c`       | Quit (stops the processes devcc started)                  |
+Steps run one at a time, in order, and a failure does not stop the run, so one pass shows every problem.
+Colour is switched off for the steps and escape codes are stripped from captured output.
 
-### Processes and Services
+| Exit code | Meaning                                                                   |
+| --------- | ------------------------------------------------------------------------- |
+| `0`       | Every step passed                                                         |
+| `1`       | At least one step failed (or was cancelled)                               |
+| `2`       | Nothing was verified: no steps configured, or a step name matches nothing |
 
-| Key     | Action                            |
-| ------- | --------------------------------- |
-| `s`     | Start or stop the selection       |
-| `r`     | Restart the selection             |
-| `i`     | Inspect the selection             |
-| `enter` | Jump to that process's logs       |
-| `d`     | `docker compose down` (confirmed) |
+A missing configuration is an error on purpose: a gate that passes because it checked nothing is worse
+than no gate. That makes a line like this safe to put in an agent's instructions:
 
-### Scripts
+```text
+Do not finish until `devcc verify` succeeds.
+```
 
-| Key       | Action                             |
-| --------- | ---------------------------------- |
-| `enter`   | Run the selected script            |
-| `x`       | Stop a running script              |
-| `f` / `c` | Filter the list / clear the filter |
+In the dashboard, `shift+V` (or "Project: verify" in the palette) runs the same steps as managed tasks:
+progress shows on the Overview, and each step's output has its own log source.
 
-### Git
+## Environment
 
-| Key             | Action                            |
-| --------------- | --------------------------------- |
-| `s` / `u`       | Stage / unstage the selected file |
-| `d`             | Discard file changes (confirmed)  |
-| `c`             | Commit staged changes             |
-| `p` / `shift+P` | Pull / push (push is confirmed)   |
-| `f`             | Fetch                             |
-| `r`             | Refresh status                    |
+The System view (`8`) starts with the environment, detected in the background when a project opens and
+re-checked with `r`. `devcc env` prints the same report.
 
-### Dependencies
+- **Tools**: Node, pnpm, npm, Bun, Git, mise, direnv, Docker, Rust/Cargo, Claude Code, Codex, Tailscale and
+  Ollama, each with its version, or "not installed". Missing tools are normal. Every probe has a 3-second
+  timeout, so a hung executable shows as a warning instead of freezing anything.
+- **mise** (optional). When mise is installed, the runtimes pinned for this project, read from
+  `mise ls --current --json`. An untrusted `mise.toml` is reported, never trusted automatically.
+- **direnv** (optional). Whether the project has an `.envrc`, whether it is allowed, and whether devcc
+  itself was started with it loaded. "Environment: direnv allow" in the palette runs `direnv allow` after
+  a confirmation; devcc never approves an `.envrc` on its own.
 
-| Key | Action                                  |
-| --- | --------------------------------------- |
-| `r` | Check the registry for updates          |
-| `u` | Update the selected package (confirmed) |
+Anything that needs attention is summarised in one line on the Overview.
 
-### Logs
+## Remote machines
 
-| Key              | Action                                             |
-| ---------------- | -------------------------------------------------- |
-| `j` / `k`        | Scroll                                             |
-| `PgUp` / `PgDn`  | Page                                               |
-| `home` / `end`   | Jump to start / end                                |
-| `f`              | Toggle follow                                      |
-| `s`              | Search - plain text, or a regex if it parses       |
-| `x`              | Clear the search                                   |
-| `e`              | Toggle errors only (stderr)                        |
-| `a`              | Merged stream of every source, colour-keyed        |
-| `tab`, `←` / `→` | Change log source                                  |
-| `c`              | Clear the current buffer (all, in the merged view) |
+Declare the machines you develop on. `host` can be an alias from `~/.ssh/config`: devcc resolves it with
+`ssh -G`, so your existing SSH settings apply, and it never stores users, keys or addresses of its own.
 
-## Configuration
+```ts
+remoteMachines: [
+  { id: "gpu", name: "GPU Server", host: "gpu-server", transport: "ssh", services: ["gpu-ollama"] },
+],
+```
 
-Configuration is **optional** - without it the dashboard still detects your
-package manager, reads `package.json` scripts, shows git status, probes for
-local services, and monitors the host. A config file adds processes devcc can
-control and project-specific commands.
+Each machine appears under REMOTE in the Services view: whether its SSH port answers and how quickly,
+whether it is online in your tailnet, and the status of its associated services. `o` on a machine opens an
+SSH session in a terminal. Reachability is a TCP connection to the SSH port, made at most once a minute
+while the project is open, plus whenever you refresh.
 
-devcc looks for the first of `.devcc.ts`, `devcc.config.ts`, `.devcc.mts`,
-`devcc.config.mts`, `.devcc.js`, `devcc.config.js`, `.devcc.mjs`,
-`devcc.config.mjs`, `.devcc.json` in the project root. TypeScript config files
-are transpiled on the fly, so no build step is needed.
+**Tailscale** (optional). When the `tailscale` CLI is available (including the macOS app's bundled one),
+devcc reads `tailscale status --json` every 30 seconds: connected or not, this node's name, and which of
+your remote machines are online.
 
-A real example (this repository's own `.devcc.ts`):
+**Remote Ollama** (optional). Point a service entry at any Ollama server, whether on localhost, a LAN
+hostname or a Tailscale name:
 
 ```ts
-import { defineConfig } from "./src/devcc/index.js"
+services: [{ id: "gpu-ollama", type: "ollama", baseUrl: "http://gpu-server:11434" }],
+```
 
-export default defineConfig({
-  name: "dev command center",
+The entry lists the server's models with parameter size, quantisation and disk size, marks the ones
+currently loaded (with VRAM use) from `/api/ps`, and says "unreachable" when the server is down. Remote
+endpoints are checked at most once a minute. The local Ollama on port 11434 (or `OLLAMA_HOST`) is still
+detected automatically.
 
+## Configuration
+
+### Setting up a project
+
+devcc works without a config file, but a good `.devcc.ts` is what makes processes, verification and the
+palette useful. There are three ways to get one:
+
+- **`devcc init`** writes a starter from what it can read without running anything: the package manager,
+  a `dev` script and its framework's port, and verify steps from existing scripts (format check, lint,
+  typecheck, tests, build). Scripts that watch, write files or are npm's placeholder are left out. Rust
+  and Go projects get their toolchain's standard checks.
+- **`devcc init --agent claude`** (or `codex`) opens that agent in your terminal with a setup prompt
+  built for this project: what devcc detected, the starter as a draft, the full config reference, and
+  firm rules (never invent commands or ports, never add secrets or hostnames, keep verify
+  non-interactive, confirm anything destructive). The agent reads the README, CI workflows and framework
+  configs, writes `.devcc.ts`, and runs `devcc config check` until it is clean. You watch and approve its
+  edits as usual. `devcc init --prompt` prints the same prompt for any other agent.
+- **In the dashboard**, a project without config shows a hint. The palette offers "Project: set up
+  .devcc.ts from detected scripts", and "Project: set up .devcc.ts with Claude Code / Codex" (also for
+  improving an existing config). The dashboard's agent runs headless and cannot edit files, so it prints
+  its proposal; devcc validates it, saves it to `.devcc/proposed.devcc.ts` for review, and writes it
+  only after you confirm. The project then reloads with the new config.
+
+Nothing is set up automatically, and an existing config is never replaced without `--force` or a
+confirmation.
+
+### Without a config file
+
+Run `devcc` in a project with no configuration and it detects all of this, so Overview, Scripts, Git,
+Services and System are populated on first launch:
+
+| Detects         | How                                                                                          |
+| --------------- | -------------------------------------------------------------------------------------------- |
+| Project root    | Walks up from the working directory looking for `package.json` or `.git`                     |
+| Package manager | `packageManager` field → lockfile → the manager that launched it → npm                       |
+| Scripts         | `scripts` in `package.json`                                                                  |
+| Git state       | `git status --porcelain=v2`: branch, staged/modified/untracked, ahead/behind, recent commits |
+| Local services  | TCP probes for Postgres, Redis and Ollama; the Docker daemon and any compose file            |
+| Dev servers     | Ports inferred from your dependencies (`next` → 3000, `vite` → 5173, `typesense` → 8108)     |
+| Host metrics    | Node's `os` and `fs` APIs: CPU, memory, disk, load, uptime                                   |
+| Tool versions   | `git`, `docker` and your package manager, read once in the background                        |
+
+### Adding processes and commands
+
+devcc cannot guess that `pnpm dev` is the thing you want it to own, that it should wait for port 3000
+before calling it ready, or that it is safe to restart. Nothing is launched or controlled until you declare
+it in `.devcc.ts` in the project root:
+
+```ts
+// ~/code/example.com/.devcc.ts
+export default {
   processes: [
     {
-      id: "typecheck",
-      name: "tsc --watch",
-      command: "pnpm",
-      args: ["exec", "tsc", "-p", "tsconfig.json", "--noEmit", "--watch", "--pretty", "false"],
-      kind: "service",
-    },
-    {
-      id: "vitest",
-      name: "vitest --watch",
+      id: "web",
+      name: "Next.js",
       command: "pnpm",
-      args: ["exec", "vitest", "--watch"],
-      kind: "service",
+      args: ["dev"],
+      url: "localhost:3000",
+      readiness: { port: 3000 }, // "running" means actually serving
+      restartOnCrash: true, // comes back after a crash, with backoff
     },
   ],
-
   commands: [
     {
-      id: "verify",
-      title: "Verify (lint, typecheck, test, build)",
-      category: "Project",
+      id: "migrate",
+      title: "Run migrations",
+      category: "Database",
       command: "pnpm",
-      args: ["run", "verify"],
-      keywords: ["ci", "check", "all"],
-    },
-    {
-      id: "clean",
-      title: "Remove dist/",
-      category: "Project",
-      command: "rm",
-      args: ["-rf", "dist"],
-      confirm: true,
+      args: ["db:migrate"],
+      confirm: true, // asks first: it mutates the database
     },
   ],
-
-  refresh: { system: 1_500, services: 5_000, git: 8_000 },
-})
+}
 ```
 
-A monorepo example. In a project that has devcc installed, import `defineConfig`
-from the package name (`command-center`); in a project that does not, export a
-plain object instead - the shape is identical and it is validated either way:
+Restart devcc and the Processes pane is live: `s` starts or stops, `r` restarts, `enter` jumps to that
+process's logs, and quitting stops everything devcc started. The declared command appears in the palette
+(`/`) and asks before it runs.
+
+**Type-checked config.** If the project has `@doriandev/devcc` installed as a dependency, wrap the config
+in `defineConfig` for editor autocompletion. The shape is the same and it is validated either way. A
+monorepo example:
 
 ```ts
-import { defineConfig } from "command-center"
+import { defineConfig } from "@doriandev/devcc"
 
 export default defineConfig({
   processes: [
@@ -362,44 +398,43 @@ export default defineConfig({
 })
 ```
 
-Without the package installed, the same config works as a plain object:
+**File names.** devcc uses the first of `.devcc.ts`, `devcc.config.ts`, `.devcc.mts`, `devcc.config.mts`,
+`.devcc.js`, `devcc.config.js`, `.devcc.mjs`, `devcc.config.mjs` or `.devcc.json` in the project root.
+TypeScript is transpiled on the fly, so no build step is needed.
 
-```ts
-// .devcc.ts in any project - no import, no dependency
-export default {
-  processes: [{ id: "web", name: "Web", command: "pnpm", args: ["dev"], port: 3000 }],
-}
-```
+**Mistakes are safe.** Invalid entries are reported in **Settings → Config issues** and skipped; a typo
+never stops the dashboard from starting.
 
-### Process definitions
+### Process fields
 
 | Field               | Type                    | Description                                                         |
 | ------------------- | ----------------------- | ------------------------------------------------------------------- |
-| `id`                | `string`                | Unique id. Also the log source id. **Required**                     |
-| `name`              | `string`                | Display name (defaults to `id`)                                     |
-| `command`           | `string`                | Executable. **Required** - never a shell string                     |
+| `id`                | `string`                | **Required.** Unique id, also used as the log source id             |
+| `command`           | `string`                | **Required.** Executable, never a shell string                      |
 | `args`              | `string[]`              | Arguments passed as an array, so quoting is never an issue          |
+| `name`              | `string`                | Display name (defaults to `id`)                                     |
 | `cwd`               | `string`                | Absolute, or relative to the project root                           |
 | `env`               | `Record<string,string>` | Extra environment variables                                         |
 | `kind`              | `"service" \| "task"`   | Long-running vs. expected to exit (default `service`)               |
 | `autoStart`         | `boolean`               | Start with the dashboard (default `false`)                          |
 | `url`               | `string`                | Informational address shown next to the process                     |
 | `port`              | `number`                | Port to associate with the process                                  |
+| `dependsOn`         | `string[]`              | Ids that must be _ready_ before this one starts                     |
+| `readiness`         | `object`                | How devcc decides the process is usable, see below                  |
 | `killGraceMs`       | `number`                | SIGTERM → SIGKILL grace period (default 5000)                       |
 | `restartOnCrash`    | `boolean`               | Bring it back automatically after a non-zero exit (default `false`) |
 | `maxCrashRestarts`  | `number`                | Give up after this many consecutive crashes (default 5)             |
 | `crashBackoffMs`    | `number`                | First backoff delay, doubling per crash (default 1000)              |
 | `maxCrashBackoffMs` | `number`                | Backoff ceiling (default 30000)                                     |
 | `healthyAfterMs`    | `number`                | A run lasting this long resets the crash budget (default 30000)     |
-| `dependsOn`         | `string[]`              | Ids that must be _ready_ before this one starts                     |
-| `readiness`         | `object`                | How devcc decides the process is usable - see below                 |
+
+A manual stop cancels any pending crash restart and resets the budget.
 
 ### Readiness checks
 
-Without a readiness block a process is `running` the moment it has spawned.
-With one, it stays `starting` until the check passes, and `dependsOn` waits for
-that - so "start all" brings a stack up in the right order and only once each
-layer is actually usable.
+Without a readiness block a process is `running` the moment it has spawned. With one, it stays `starting`
+until the check passes, and `dependsOn` waits for that. So "start all" brings a stack up in the right
+order, and only once each layer is actually usable.
 
 ```ts
 {
@@ -423,25 +458,86 @@ layer is actually usable.
 | `timeoutMs`    | Give up waiting and report `running` anyway, with a warning (default 30000)  |
 | `intervalMs`   | Port probe interval (default 250)                                            |
 
-Either `port` or `logPattern` is required; both may be given. A dependency
-cycle is reported and those processes are left alone rather than started in an
-arbitrary order.
+Either `port` or `logPattern` is required; both may be given. A dependency cycle is reported and those
+processes are left alone rather than started in an arbitrary order.
+
+### Command fields
+
+| Field                    | Type                            | Description                                 |
+| ------------------------ | ------------------------------- | ------------------------------------------- |
+| `id`                     | `string`                        | **Required.** Unique id                     |
+| `command`, `args`, `cwd` |                                 | As for processes. **`command` is required** |
+| `title`                  | `string`                        | Palette entry text                          |
+| `category`               | `string`                        | Palette grouping (default `Project`)        |
+| `keywords`               | `string[]`                      | Extra fuzzy-search terms                    |
+| `confirm`                | `boolean \| { title, message }` | Ask before running                          |
+
+### Service fields
+
+Extra ports to watch: `{ id, name, port, host?, healthPath?, category? }`. `healthPath` upgrades the check
+from a TCP probe to an HTTP request. An Ollama server is `{ id, name?, type: "ollama", baseUrl }`; see
+[Remote machines](#remote-machines).
 
-### Command definitions
+### Control-plane fields
 
-| Field                    | Type                            | Description                              |
-| ------------------------ | ------------------------------- | ---------------------------------------- |
-| `id`                     | `string`                        | Unique id. **Required**                  |
-| `title`                  | `string`                        | Palette entry text                       |
-| `category`               | `string`                        | Palette grouping (default `Project`)     |
-| `command`, `args`, `cwd` |                                 | As for processes. **`command` required** |
-| `keywords`               | `string[]`                      | Extra fuzzy-search terms                 |
-| `confirm`                | `boolean \| { title, message }` | Ask before running                       |
+All optional. Nothing here is required for devcc to work.
 
-### Service definitions
+| Field                 | Description                                                                                                                                                                          |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `verify`              | Steps for `devcc verify`: command ids, script names, or `{ id, name?, command, args?, cwd? }`                                                                                        |
+| `agents`              | Per agent id: `{ command?, args?, name?, enabled? }`. `claude` and `codex` are built in; any other key adds an agent whose task is the last argument                                 |
+| `worktrees.directory` | Where new worktrees go, relative to the main worktree (default `..`)                                                                                                                 |
+| `editor`              | `{ command: "zed" }` (also `code`, `cursor`, `webstorm`, with optional `args`) or, on macOS, `{ application: "WebStorm" }`                                                           |
+| `terminal`            | macOS default: Terminal. `{ application: "iTerm" }`, or `{ command, args, execArgs }` where `{path}` in `args` is the directory and `execArgs` makes it run a program (used for SSH) |
+| `remoteMachines`      | `{ id, name?, host, transport: "ssh", port?, user?, services? }`                                                                                                                     |
+
+### A full example
+
+A Next.js app on pnpm, with Claude Code and Codex working in worktrees, models served from a GPU box, and a
+verification gate:
+
+```ts
+// ~/code/shop/.devcc.ts
+import { defineConfig } from "@doriandev/devcc"
+
+export default defineConfig({
+  name: "shop",
+  editor: { command: "zed" },
+
+  processes: [
+    {
+      id: "web",
+      name: "Next.js",
+      command: "pnpm",
+      args: ["dev"],
+      url: "localhost:3000",
+      readiness: { port: 3000 },
+      restartOnCrash: true,
+    },
+  ],
+
+  agents: {
+    claude: { args: ["--permission-mode", "acceptEdits"] },
+    codex: { args: ["--sandbox", "workspace-write"] },
+  },
+  worktrees: { directory: "../shop-worktrees" },
+
+  verify: [
+    "lint",
+    "typecheck",
+    "test",
+    { id: "build", name: "Next.js build", command: "pnpm", args: ["build"] },
+  ],
+
+  services: [{ id: "gpu-ollama", type: "ollama", baseUrl: "http://gpu-server:11434" }],
+  remoteMachines: [
+    { id: "gpu", name: "RTX 3090 Server", host: "gpu-server", transport: "ssh", services: ["gpu-ollama"] },
+  ],
+})
+```
 
-Extra ports to watch: `{ id, name, port, host?, healthPath?, category? }`.
-`healthPath` upgrades the check from a TCP probe to an HTTP request.
+Open it with `devcc`, press `w`, then `n` to create `feature/checkout` and `c` to give Claude a task in it.
+Press `shift+V` before you merge; the agent can run `devcc verify` itself.
 
 ### Other options
 
@@ -454,19 +550,167 @@ Extra ports to watch: `{ id, name, port, host?, healthPath?, category? }`.
 | `projects`          | Extra project paths offered in the switcher (absolute or relative) |
 | `projectSearchDirs` | Extra directories to scan for sibling projects                     |
 
-Invalid entries are reported in **Settings → Config issues** and skipped; a typo
-never stops the dashboard from starting.
+## Keyboard shortcuts
+
+You do not need to memorise these: press `?`, `F1` or `ctrl+k` in the app for the manual, or `/` to search
+every action in the command palette. The footer shows key hints for the current view.
+
+### Global
+
+| Key                     | Action                                        |
+| ----------------------- | --------------------------------------------- |
+| `↑` / `k`, `↓` / `j`    | Previous / next item                          |
+| `←` / `h`, `→`          | Previous / next section                       |
+| `tab`, `shift+tab`      | Cycle sections                                |
+| `1`…`9`, `0`            | Jump straight to a section (`0` is Worktrees) |
+| `p`, `g`, `w`, `l`, `d` | Processes, Git, Worktrees, Logs, Dependencies |
+| `enter`                 | Open / activate the selection                 |
+| `esc`                   | Close an overlay                              |
+| `/`                     | Command palette                               |
+| `ctrl+p`                | Open another project (others keep running)    |
+| `ctrl+o`                | Cycle through open projects                   |
+| `?` / `F1` / `ctrl+k`   | The in-app manual                             |
+| `shift+R`               | Refresh everything                            |
+| `shift+V`               | Verify the project                            |
+| `q` or `ctrl+c`         | Quit (stops the processes devcc started)      |
+
+### Processes and Services
+
+| Key     | Action                             |
+| ------- | ---------------------------------- |
+| `s`     | Start or stop the selection        |
+| `r`     | Restart the selection              |
+| `i`     | Inspect the selection              |
+| `enter` | Jump to that process's logs        |
+| `d`     | `docker compose down` (confirmed)  |
+| `o`     | SSH to the selected remote machine |
+
+### Worktrees
+
+| Key         | Action                                                 |
+| ----------- | ------------------------------------------------------ |
+| `n`         | New worktree (branch, base, directory)                 |
+| `d`         | Remove the worktree (confirmed, never forced)          |
+| `o` / enter | Open the worktree in devcc; on an agent, its logs      |
+| `t` / `e`   | Open a terminal / your editor in the worktree          |
+| `c` / `x`   | Launch Claude Code / Codex with a task in the worktree |
+| `s`         | Stop the selected agent                                |
+| `r`         | Refresh the list                                       |
+
+### Scripts
+
+| Key       | Action                             |
+| --------- | ---------------------------------- |
+| `enter`   | Run the selected script            |
+| `x`       | Stop a running script              |
+| `f` / `c` | Filter the list / clear the filter |
+
+### Git
+
+| Key             | Action                            |
+| --------------- | --------------------------------- |
+| `s` / `u`       | Stage / unstage the selected file |
+| `c`             | Commit staged changes             |
+| `f`             | Fetch                             |
+| `p` / `shift+P` | Pull / push (push is confirmed)   |
+| `d`             | Discard file changes (confirmed)  |
+| `r`             | Refresh status                    |
+
+### Logs
+
+| Key              | Action                                             |
+| ---------------- | -------------------------------------------------- |
+| `j` / `k`        | Scroll                                             |
+| `PgUp` / `PgDn`  | Page                                               |
+| `home` / `end`   | Jump to start / end                                |
+| `f`              | Toggle follow                                      |
+| `s`              | Search: plain text, or a regex if it parses        |
+| `x`              | Clear the search                                   |
+| `e`              | Toggle errors only (stderr)                        |
+| `a`              | Merged stream of every source, colour-keyed        |
+| `tab`, `←` / `→` | Change log source                                  |
+| `c`              | Clear the current buffer (all, in the merged view) |
+
+### Dependencies
 
-## Architecture
+| Key | Action                                  |
+| --- | --------------------------------------- |
+| `r` | Check the registry for updates          |
+| `u` | Update the selected package (confirmed) |
+
+## Known limitations
+
+- **Runtime.** The dashboard needs Bun, or Node ≥ 26.4 with `--experimental-ffi`. This is an OpenTUI/FFI
+  constraint, not a design choice.
+- **Services.** Adapters ship for Docker Compose, PostgreSQL, Redis, Ollama (local or remote), Tailscale,
+  SSH machines and HTTP/port services. Others (Kubernetes, Vercel, Azure, …) are designed for but not
+  implemented.
+- **Agents run headless.** Claude Code and Codex are started in their non-interactive modes with a task;
+  devcc cannot host their interactive interfaces. Use `t` for a terminal in the worktree instead.
+- **Opening things outside devcc.** On macOS, terminals, editors and SSH use `open`. Elsewhere, set
+  `editor.command` and `terminal.command` (with `execArgs` for SSH).
+- **direnv "loaded"** describes devcc's own environment (whether you started it from a direnv-enabled
+  shell), not your other terminals.
+- **Remote reachability** is a TCP connection to the SSH port. It does not log in, so a machine that
+  accepts connections but rejects your key still shows as reachable.
+- **Git.** The panel covers status, staging, discard, commit, fetch, pull and push. Branch switching,
+  rebasing, merge-conflict resolution and diff viewing are not implemented.
+- **Detected services are read-only.** devcc will not start or stop something it did not launch, apart
+  from Docker Compose. `docker compose down --volumes` is deliberately not bound to a key.
+- **Mouse.** Whatever OpenTUI provides by default; the interface is designed and tested for the keyboard.
+- **Small terminals.** Below roughly 60 columns the sidebar hides and columns are trimmed. The layout
+  degrades rather than breaking, but it is cramped.
+
+## Contributing
+
+### Running from source
+
+```bash
+git clone https://github.com/dordevgit/devcc.git
+cd devcc
+pnpm install
+pnpm dev:center                          # launch against this repo
+node bin/devcc.mjs -C ~/code/example.com # or against another project
+```
+
+This repository's own [`.devcc.ts`](.devcc.ts) is a working config example.
+
+### Scripts
+
+```bash
+pnpm lint          # eslint (flat config, type-checked rules)
+pnpm typecheck     # tsc --noEmit, strict
+pnpm test          # vitest: core logic, no terminal required
+pnpm test:tui      # end-to-end smoke test against OpenTUI's headless renderer (Bun only)
+pnpm build         # tsc -> dist/
+pnpm verify        # lint + typecheck + test + build
+pnpm format        # prettier
+```
+
+`pnpm test` covers the non-UI core: package-manager detection, config parsing and validation, the command
+registry, the log ring buffer, process state transitions and real process lifecycles, service detection
+and adapter failure handling, git porcelain and worktree parsing (plus create/remove against a real
+repository), agent launching, tool/mise/direnv detection, verification and its CLI exit codes, Tailscale
+and remote Ollama parsing, the observable store, and the formatting helpers. No optional tool (Claude,
+Codex, Ollama, Tailscale, mise, direnv) needs to be installed.
+
+`pnpm test:tui` boots the real application against OpenTUI's test renderer and drives it with synthetic
+keystrokes: navigation, palette, help, starting/restarting/stopping a managed process, running a package
+script, log capture, creating and removing worktrees, launching an agent in a worktree, verification, and
+clean shutdown. It asserts on behaviour rather than on frame snapshots.
+
+### Architecture
 
 ```
 src/devcc/
-  cli.ts                  argv parsing, TTY check, process exit code
+  cli.ts                  argv parsing, subcommands, TTY check, exit code
+  automation.ts           devcc verify / worktree list / env (no TUI, JSON output)
   index.ts                public API (defineConfig, App, all reusable pieces)
 
   app/
     App.ts                composition root: renderer, services, state, input
     builtinCommands.ts    the built-in command set
+    controlPlaneCommands.ts  worktree, agent, verify, environment and remote commands
     keymap.ts             global bindings + the help cheat sheet
     theme.ts              palette and status glyphs
 
@@ -478,25 +722,26 @@ src/devcc/
 
   components/             Header, Footer, Sidebar, RowList, StatusBadge, Overlay,
                           ConfirmDialog, CommandPalette, ProjectPicker, HelpOverlay
-  views/                  Overview, Processes, Services, Scripts, Git, Logs,
-                          Dependencies, System, Settings (all extend View.ts)
+  views/                  Overview, Processes, Services, Scripts, Git, Worktrees,
+                          Logs, Dependencies, System, Settings (all extend View.ts)
 
-  processes/              ManagedProcess types + ProcessManager (incl. crash policy)
+  processes/              ManagedProcess types, ProcessManager (incl. crash policy),
+                          graph.ts: dependsOn planner (waves + cycle detection)
   services/               ServiceAdapter interface, ServiceManager, and the
-                          docker / node / postgres / redis / ollama adapters
+                          docker / node / postgres / redis / ollama adapters,
+                          remote.ts: SSH machines + Tailscale
+  git/                    GitService, pure porcelain-v2 parsers, worktrees.ts
+  agents/                 AgentAdapter (Claude Code, Codex, custom) + AgentManager
+  environment/            tool detection, mise/direnv parsers, EnvironmentService
+  verify/                 step resolution, the runner loop, the spawn executor
+  platform/               editor / terminal / SSH launch commands
+  logs/                   LogBuffer ring buffer, LogStore, merge.ts (merged stream, search)
   deps/                   DependencyService + per-manager `outdated` parsers
   projects/               ProjectRegistry: discovery, recents, switcher list
-  processes/graph.ts      dependsOn planner (waves + cycle detection)
-  logs/merge.ts           merged stream, search filter
-  git/                    GitService + pure porcelain-v2 parsers
   system/                 SystemMonitor (Node APIs only)
-  logs/                   LogBuffer ring buffer + LogStore
-  utils/                  exec, packageManager, paths, format, fuzzy, logger,
-                          errors
+  utils/                  exec, packageManager, paths, format, fuzzy, logger, errors
 ```
 
-### How data flows
-
 ```
 ProcessManager ─┐
 ServiceManager ─┤   typed events    ┌─────────┐   watched slices   ┌───────┐
@@ -505,65 +750,61 @@ SystemMonitor  ─┤                   └─────────┘
 LogStore       ─┘
 ```
 
-Backends never touch renderables. They emit typed events; `App` folds those into
-a single `AppState`; views subscribe to the slices they care about via
-`store.watch(selector, listener)`, so a 1 Hz CPU sample does not repaint the git
-panel. List rendering recycles `TextRenderable`s and only materialises the rows
+Backends never touch renderables. They emit typed events; `App` folds those into a single `AppState`;
+views subscribe to the slices they care about via `store.watch(selector, listener)`, so a 1 Hz CPU sample
+does not repaint the git panel. List rendering recycles `TextRenderable`s and only materialises the rows
 that fit the viewport.
 
-### Design decisions worth knowing
-
-- **Nothing runs through a shell.** Every child process is
-  `spawn(executable, args[])`, so arguments containing spaces or quotes cannot
-  become injection.
-- **Process trees die properly.** Children are spawned detached (their own
-  process group) and stopped with `kill(-pgid, SIGTERM)`, escalating to
-  `SIGKILL` after the grace period, so dev servers do not leave orphaned
-  workers behind.
-- **Detected ≠ owned.** A process devcc launched is `ownership: "managed"`.
-  Anything merely observed on the host is `"detected"` and can never be
-  signalled by devcc.
-- **Destructive actions are always confirmed**: `git restore`, `git push`,
-  `docker compose down`, stop-all, clear-all-logs, and any config command marked
-  `confirm`. Discarding untracked files is refused outright.
-- **Memory is bounded by construction.** Each log source is a fixed-capacity
-  ring buffer (5000 lines by default); nothing else retains log lines.
-- **Startup never blocks.** The first frame renders before git, Docker, service
-  detection or tool versions have answered; each populates asynchronously with
-  its own timeout.
-- **Several projects can be open at once.** `ctrl+p` opens another project
-  without closing the current one; each keeps its processes and log capture
-  alive in the background, only the visible project polls git/services/system,
-  and the sidebar grows a PROJECTS block with per-project running counts.
-  Closing a project (or quitting) stops what devcc started there, with a
-  confirmation.
-- **Starts are ordered.** `dependsOn` and `readiness` turn "start all" into a
-  wave-by-wave bring-up: each wave waits for the previous one to be ready. The
+### Design decisions
+
+How the worktree, agent, environment, verification and remote features fit onto the existing abstractions
+is written up in [docs/control-plane.md](docs/control-plane.md).
+
+**Safety**
+
+- **Nothing runs through a shell.** Every child process is `spawn(executable, args[])`, so arguments
+  containing spaces or quotes cannot become injection.
+- **Detected ≠ owned.** A process devcc launched is `ownership: "managed"`. Anything merely observed on the
+  host is `"detected"` and can never be signalled by devcc.
+- **Destructive actions are always confirmed:** `git restore`, `git push`, `docker compose down`, stop-all,
+  clear-all-logs, and any config command marked `confirm`. Discarding untracked files is refused outright.
+- **Process trees die properly.** Children are spawned detached (their own process group) and stopped with
+  `kill(-pgid, SIGTERM)`, escalating to `SIGKILL` after the grace period, so dev servers do not leave
+  orphaned workers behind.
+
+**Performance**
+
+- **Startup never blocks.** The first frame renders before git, Docker, service detection or tool versions
+  have answered; each populates asynchronously with its own timeout.
+- **Memory is bounded.** Each log source is a fixed-capacity ring buffer (5000 lines by default). The
+  merged view materialises at most 2,000 recent lines on demand. Search is plain substring, or a regex when
+  the query parses as one, so typing `(` never breaks the view.
+- **Dependency checks never poll.** They reach the network, so they run only when you ask, and updating a
+  package is confirmed because it rewrites the lockfile.
+- **Remote checks are rate-limited.** An adapter can set `refreshIntervalMs`; the poller skips it until that
+  has passed, so an open dashboard does not keep hitting a remote machine. Explicit refresh ignores it.
+- **Agents are processes.** An agent adapter only describes a command line; the session is a managed task
+  in the same `ProcessManager`, so status, logs, stop and shutdown work exactly as for anything else.
+
+**Structure**
+
+- **Starts are ordered.** `dependsOn` and `readiness` turn "start all" into a wave-by-wave bring-up. The
   ordering is a pure function (`planStartOrder`) with its own tests.
-- **The merged log stream is bounded.** Per-source views window straight into
-  that source's ring buffer; the merged view materialises at most 2,000 recent
-  lines on demand. Searching is plain substring, or a regex when the query
-  parses as one, so typing `(` never breaks the view.
-- **Crash recovery is opt-in.** A process only comes back automatically if its
-  definition says `restartOnCrash`, with exponential backoff and a hard attempt
-  limit; a manual stop cancels any pending restart and clears the budget.
-- **Switching project rebuilds the session, not the UI.** The renderer, views and
-  store survive; the process manager, service adapters, git service, logger and
-  command registry are torn down and rebuilt for the new directory, and anything
-  devcc had started is stopped first (with a confirmation).
-- **Dependency checks never poll.** They reach the network, so they run only when
-  you ask, and updating a package is confirmed because it rewrites the lockfile.
-- **Errors are never swallowed.** They are normalised into `DevccError`, written
-  to `.devcc/devcc.log`, shown in the footer, and kept for inspection in
-  **Settings → Diagnostics**.
-
-## Extension points
-
-**Add a command** - register it once and it appears in the palette, with an
-optional confirmation gate:
+- **Several projects stay open.** Each open project keeps its processes and log capture alive in the
+  background; only the visible one polls git, services and system. Closing a project (or quitting) stops
+  what devcc started there, with a confirmation.
+- **Switching project rebuilds the session, not the UI.** The renderer, views and store survive; the
+  process manager, service adapters, git service, logger and command registry are rebuilt for the new
+  directory.
+- **Errors are never swallowed.** They are normalised into `DevccError`, written to `.devcc/devcc.log`,
+  shown in the footer, and kept for inspection in **Settings → Diagnostics**.
+
+### Extending devcc
+
+**Add a command.** Register it once and it appears in the palette, with an optional confirmation gate:
 
 ```ts
-import { type CommandDefinition } from "command-center"
+import { type CommandDefinition } from "@doriandev/devcc"
 
 const command: CommandDefinition = {
   id: "deploy.preview",
@@ -578,15 +819,15 @@ const command: CommandDefinition = {
 }
 ```
 
-`CommandContext` exposes the store, the process/service/git/log/system services,
-and `navigate`, `notify`, `confirm`, `prompt`, `runScript` and `quit`.
+`CommandContext` exposes the store, the process/service/git/log/system services, and `navigate`,
+`notify`, `confirm`, `prompt`, `runScript` and `quit`.
 
-**Add a service adapter** - implement `ServiceAdapter` and register it with the
-`ServiceManager`. `detect()` decides whether the service is relevant at all, so
-adapters cost nothing in projects that do not use them:
+**Add a service adapter.** Implement `ServiceAdapter` and register it with the `ServiceManager`.
+`detect()` decides whether the service is relevant at all, so adapters cost nothing in projects that do not
+use them:
 
 ```ts
-import { type ServiceAdapter } from "command-center"
+import { type ServiceAdapter } from "@doriandev/devcc"
 
 export class TailscaleService implements ServiceAdapter {
   readonly id = "tailscale"
@@ -608,52 +849,11 @@ export class TailscaleService implements ServiceAdapter {
 }
 ```
 
-The same shape is how Azure, Vercel, GitHub, Kubernetes, remote SSH hosts or CI
-pipelines would be added later - each is a `detect()` plus a `getStatus()`, with
-optional `start`/`stop`/`restart`.
-
-**Add a view** - extend `views/View.ts`, register it in `App`, and add an entry
-to `SIDEBAR_ITEMS`.
-
-## Development
-
-```bash
-pnpm lint          # eslint (flat config, type-checked rules)
-pnpm typecheck     # tsc --noEmit, strict
-pnpm test          # vitest - core logic, no terminal required
-pnpm test:tui      # end-to-end smoke test against OpenTUI's headless renderer
-pnpm build         # tsc -> dist/
-pnpm verify        # lint + typecheck + test + build
-pnpm format        # prettier
-```
-
-`pnpm test` covers the non-UI core: package-manager detection, config parsing
-and validation, the command registry, the log ring buffer, process state
-transitions and real process lifecycles, service detection and adapter failure
-handling, git porcelain parsing, the observable store, and the formatting
-helpers.
+Azure, Vercel, GitHub, Kubernetes, remote SSH hosts or CI pipelines would be added the same way: a
+`detect()` plus a `getStatus()`, with optional `start`/`stop`/`restart`.
 
-`pnpm test:tui` boots the actual application against OpenTUI's supported test
-renderer (Bun only) and drives it with synthetic keystrokes: navigation,
-palette, help, starting/restarting/stopping a managed process, running a
-package script, log capture, and clean shutdown. It asserts on behaviour rather
-than on frame snapshots.
+**Add a view.** Extend `views/View.ts`, register it in `App`, and add an entry to `SIDEBAR_ITEMS`.
 
-## Known limitations
+## License
 
-- The dashboard itself requires Bun (or Node ≥ 26.4 with `--experimental-ffi`);
-  this is an OpenTUI/FFI constraint, not a design choice.
-- Service adapters ship for Docker Compose, PostgreSQL, Redis, Ollama and
-  HTTP/port services. Others (Kubernetes, Vercel, Azure, Tailscale, …) are
-  designed for but not implemented.
-- The Git panel covers status, staging, discard, commit, fetch, pull and push.
-  Branch switching, rebasing, merge-conflict resolution and diff viewing in the
-  UI are not implemented (`GitService.diff()` exists but has no view yet).
-- Detected services are read-only: devcc will not start or stop something it did
-  not launch, apart from Docker Compose.
-- `docker compose down --volumes` is available through `DockerService.down()`
-  but is deliberately not bound to a key.
-- Mouse support is whatever OpenTUI provides by default; the interface is
-  designed and tested for the keyboard.
-- Below roughly 60 columns the sidebar hides and columns are trimmed; the layout
-  degrades rather than breaking, but very small terminals are cramped.
+[ISC](LICENSE)