dev-cockpit 0.1.0 → 0.2.2

package/docs/getting-started.md

@@ -1,20 +1,23 @@
 # Getting started
 
-Run `dev-cockpit dev` from a directory that contains a `cockpit.yaml`. The TUI boots into the **Repos** tab and starts any watchers + health checks declared in your config.
+Run `dev-cockpit dev` from a directory that contains a `cockpit.yaml`. The TUI boots into the **Targets** tab (or whatever `config.defaultPane` points at) and starts any processes + health checks declared in your config.
+
+Don't have a `cockpit.yaml` yet? `dev-cockpit init-config -i` walks you through it in eight steps with auto-detection from `package.json` / `compose.yaml`.
 
 ## At a glance
 
-- **Cycle tabs** — `←` / `→` (or `Tab` / `Shift-Tab`)
+- **Cycle tabs** — `←` / `→` (or `Tab` / `Shift-Tab`). Empty tabs (Targets with no rows, Health with no checks) auto-hide.
 - **Quit** — `q`
 - **Toggle notifications for this session** — `n`
+- **Open the `:` command palette** — `:` (any tab). Type to filter actions, ↑↓ to navigate, Enter to fire.
 
-Every tab fills the full terminal. Modals (filter, search) render in place of the active pane.
+Every tab fills the full terminal. Modals (filter, search, `:` palette) render in place of the active pane.
 
 ## What the panes do
 
-- **Repos** — list of repos and (optionally) Docker services with watcher / lint status; per-row actions live here.
-- **Output** — streaming logs from watchers and Docker services, with filter and search modals.
-- **Health** — workspace health checks; each check has a one-keystroke remediation.
+- **Targets** — repos, docker services, and processes as "runnable units". Split layout (≥200 cols) shows the row list on the left and the actions registered for the selected row on the right; under narrow terminals the panels stack vertically. Built-in `[r]` restarts docker containers and processes; declare more via `config.actions[]` (or a profile's `actions`).
+- **Output** — streaming logs from processes and Docker services. Filter + search modals (`f` / `/`); open the most recent error in `$EDITOR` with `e`. Severity glyphs (`⚠`, `✗`) keep lines scannable without color.
+- **Health** — workspace health checks; each row has a one-keystroke remediation.
 - **Help** — this guide. `j` / `k` to flip pages, `↑` / `↓` to scroll.
 
 ## Try it on a fixture

package/docs/index.md

@@ -4,10 +4,14 @@ This is the in-cockpit Help tab. The pages below explain what each pane does, ho
 
 - [Getting started](./getting-started.md) — first run and what to expect
 - [Panes](./panes.md) — Repos, Output, Health, Help
-- [Watchers](./watchers.md) — long-running commands streamed into Output
+- [Processes](./processes.md) — long-running commands streamed into Output
 - [Health](./health.md) — checks and one-keystroke remediations
 - [Commands](./commands.md) — the four core CLI commands + profile `setupCli`
 - [init-config](./init-config.md) — scaffold a starter `cockpit.yaml`
 - [Mount](./mount.md) — host ↔ container bind-mount overlay
 - [Notifications](./notifications.md) — transition-only OS notifications
 - [Config reference](./config-reference.md) — `cockpit.yaml` schema
+
+## Accessibility
+
+The cockpit honours the [`NO_COLOR`](https://no-color.org) environment variable — set `NO_COLOR=1` (or any non-empty value) and all ANSI colour escapes are stripped. Semantic glyphs (`✓` `⚠` `✗` `●` `○` `▸`) carry the same information in the absence of colour, so panes remain scannable without a terminal palette or for screen-reader users.

package/docs/init-config.md

@@ -17,29 +17,55 @@ dev-cockpit init-config -i [-f|--force]                    # interactive wizard
 
 ## Static template
 
-`version: 1` and `appName` are required and uncommented. Everything else (watchers, repos, docker, highlights, health, help, notifications, mounts) ships as a commented example. You uncomment what you need. Best when you already know what you want — fastest path from scratch to "edit me".
+`version: 2` and `appName` are required and uncommented. Everything else (processes, repos, docker, highlights, health, actions, help, notifications, mounts) ships as a commented example. Best when you already know what you want — fastest path from scratch to "edit me".
 
 ## Interactive wizard
 
-The recommended path the first time you set the cockpit up on a project. It walks through seven steps, with project sniffing pre-populating sensible defaults so you usually just press enter:
+The recommended path the first time you set the cockpit up on a project. Eight steps, with project sniffing pre-populating sensible defaults so you usually just press enter:
 
 | Step | Section | What it asks + auto-detects |
 |------|---------|------------------------------|
 | 1 | **App name** | Defaults to `package.json` `name`, then the cwd basename. |
 | 2 | **Docker** | Detects `compose.yaml` / `docker-compose.yml` and parses its services. Offers them as a multi-select. Skip entirely for non-compose projects. |
-| 3 | **Watchers** | Surfaces `package.json` scripts (`dev`, `watch`, `start`, `serve`) as pre-checked candidates. Anything that runs forever and writes to stdout — `vite`, `tsc --watch`, `php artisan serve`, `tail -f storage/logs/laravel.log` — fits here. |
-| 4 | **Repos** | Detects npm/yarn/pnpm workspaces; falls back to a single `.` entry. Each entry becomes a row in the Repos pane (with `r/w/l` keystroke actions when a profile bundle wires them). |
-| 5 | **Highlights** | Regex patterns that re-colour matching Output lines. `error`-severity matches additionally feed the Recent Errors strip + OS notifications. |
-| 6 | **Health** | Reframed as test-and-fix pairs. Pick one of the five built-in types (`container-running`, `port-open`, `http-ok`, `file-exists`, `exec-zero`), supply the type-specific arg(s), then bind a single-keystroke remediation. Add as many checks as you like — same type repeats freely (e.g. `port-open` for 5432, 6379, 8108). `container-running` is hidden when no docker block was declared. |
-| 7 | **Notifications** | Toggle native OS notifications on state transitions. |
+| 3 | **Processes** | Surfaces `package.json` scripts (`dev`, `watch`, `start`, `serve`) as pre-checked candidates. Anything that runs forever and writes to stdout — `vite`, `tsc --watch`, `php artisan serve`, `tail -f storage/logs/laravel.log` — fits here. |
+| 4 | **Targets** | Detects npm/yarn/pnpm workspaces; falls back to a single `.` entry. Each becomes a row in the Targets pane. The way to attach keystrokes to a repo is the Actions step (step 7), with `scope: repos:<id>` + `key:`. |
+| 5 | **Highlights** | Regex patterns that re-colour matching Output lines. `error`-severity matches additionally feed the Recent Errors strip + OS notifications. Patterns now apply to process stdout/stderr too — not just docker logs. |
+| 6 | **Health** | Test-and-fix pairs. Pick one of the five built-in types (`container-running`, `port-open`, `http-ok`, `file-exists`, `exec-zero`), supply the type-specific arg(s), then bind a single-keystroke remediation. Add as many checks as you like — same type repeats freely. `container-running` is hidden when no docker block was declared. |
+| 7 | **Actions** | One-shot shell commands surfaced through the `:` palette and/or bound to a single keypress. Auto-seeds from `package.json` scripts (`test`, `build`, `lint`, `format`, `typecheck`) with sensible default keys (`t`, `b`, `l`, `f`). Custom actions can be added inline. Distinct from processes (long-running) and health (state-checked). |
+| 8 | **Notifications** | Toggle native OS notifications on state transitions. |
 
 After writing the file, the wizard offers to run `dev-cockpit doctor` immediately so you get instant feedback that the config parses + each declared health check has a baseline state.
 
 The wizard scaffolds a *working* config. Anything more advanced (custom triggers, `expectStatus`, exec args, mounts, profile namespaces) is a hand-edit on the generated file.
 
+## Profile-contributed steps
+
+Profiles can append their own wizard steps via `Profile.wizardSteps?: WizardStep[]`. Each step runs after step 8 (Notifications) and before the final summary. Step output (YAML lines, returned from `run(ctx)`) lands under `profile.<appName>:` in the generated cockpit.yaml — the namespace defined by [ADR 0005](../adr/0005-strict-profile-namespace.md).
+
+```ts
+import type { Profile, WizardStep } from 'dev-cockpit';
+
+const gitlabStep: WizardStep = {
+  id: 'gitlab-config',
+  title: 'GitLab integration',
+  description: 'Where does this project live in your gitlab?',
+  async run(ctx) {
+    const host = await ctx.prompts.input({ message: 'GitLab host', default: 'gitlab.com' });
+    return ['gitlab:', `  host: ${host}`];
+  },
+};
+
+export const myProfile: Profile = {
+  appName: 'myapp',
+  wizardSteps: [gitlabStep],
+};
+```
+
+Step context (`ctx`) exposes the lazy-loaded `prompts` (inquirer subset), `hints` (sniffed project metadata), `workspaceRoot`, and a read-only snapshot of the core-step answers via `result`.
+
 ## Profile-driven defaults
 
-When a profile is active (e.g. `<profile-bin> init-config -i`), the wizard defaults `appName` to the profile's. Profile bundles can also register their own `init-config` via `setupCli(program)` if they want a domain-specific template — the generic command is skipped when the profile claims the slot.
+When a profile is active (e.g. `<profile-bin> init-config -i`), the wizard defaults `appName` to the profile's `appName`. Profile bundles can also register their own `init-config` via `setupCli(program)` if they want a domain-specific template — the generic command is skipped when the profile claims the slot.
 
 ## Schema reference
 

package/docs/mount.md

@@ -1,55 +1,228 @@
 # Mount
 
-`dev-cockpit mount` generates a Docker compose overlay describing host ↔ container bind mounts so you can swap a containerised dependency for a local checkout.
+`dev-cockpit mount` generates a Docker compose overlay that bind-mounts host directories into container paths, so changes in a local checkout flow live into the running container without rebuilds.
 
-## When to use it
+The subsystem is fully generic — it works for any docker-compose project — but profiles can plug in domain logic (package discovery, post-apply restart hooks, IDE-facing symlinks, custom status enrichment) without touching dev-cockpit core.
 
-When you're developing a containerised app and want changes in a local checkout to flow live into the running container — e.g. mount your local `./packages/api` into `/srv/api` inside the `web` service.
+## Quick start
+
+```yaml
+# cockpit.yaml
+version: 2
+appName: my-app
+docker:
+  composeFile: docker-compose.yml
+  services:
+    - name: web
+
+mounts:
+  - hostPath: ./packages/api
+    containerPath: /srv/api
+```
+
+```sh
+dev-cockpit mount                # interactive picker (or all when --quiet)
+dev-cockpit mount status         # active mounts with branch / dirty / broken-symlink
+dev-cockpit mount clear          # remove overlay + manifest + symlinks
+```
+
+Apply the generated overlay alongside your existing compose file:
+
+```sh
+docker compose -f docker-compose.yml -f docker-compose.dev-cockpit.yml up -d
+```
+
+## What gets written
+
+| File | Default path | Configurable via |
+|---|---|---|
+| Compose overlay | `<workspace>/docker-compose.dev-cockpit.yml` | `config.mount.overlayPath` |
+| Manifest | `<stateDir>/mount.manifest.json` | `config.mount.manifestFile` |
+
+`<stateDir>` lives under `$XDG_STATE_HOME/<appName>/<workspace-hash>/`. The manifest tracks what was applied and when, and is the source of truth for `status` and `clear`.
+
+Override the paths when the wrapper has its own conventions:
+
+```yaml
+mount:
+  overlayPath: docker/compose/web/docker-compose.dev-link.yml
+  manifestFile: dev-link.manifest.json
+```
 
 ## Mount sources
 
 Mounts come from two places, merged on `containerPath` (config wins on collision):
 
-1. **`config.mounts[]`** — explicit, declared in `cockpit.yaml`:
+1. **`config.mounts[]`** — explicit, declared in cockpit.yaml:
    ```yaml
    mounts:
      - hostPath: ./packages/api
        containerPath: /srv/api
+       meta:                  # optional opaque metadata (read by profile hooks + status)
+         name: api
+         type: package
    ```
-2. **`profile.mountCandidatesProvider?.()`** — discovered programmatically by the active profile (e.g. walking a manifest file to find local checkouts of declared dependencies).
+2. **`profile.mountCandidatesProvider?.()`** — discovered programmatically (walk a manifest file, scan a parent directory, etc.).
 
-## Output
+The `meta` field is opaque to dev-cockpit; profile hooks (status enricher, symlink strategy) read it.
 
-- `<workspace>/docker-compose.dev-cockpit.yml` — the overlay file. Apply it alongside your existing compose file:
-  ```
-  docker compose -f docker-compose.yml -f docker-compose.dev-cockpit.yml up -d
-  ```
-- `<state-dir>/mount.manifest.json` — records what was applied + when. Used by `mount status` and `mount clear`.
+## Subcommands
 
-The state dir lives under `XDG_STATE_HOME/<appName>/<workspace-hash>/`.
+```
+dev-cockpit mount [options]            # write overlay + manifest
+  -c, --config <path>                  # default: ./cockpit.yaml
+  -s, --service <name>                 # default: first in docker.services
+  -q, --quiet                          # skip interactive picker; apply all candidates
+  -e, --exclude <name>                 # exclude a candidate by meta.name (repeatable)
 
-## Subcommands
+dev-cockpit mount status [options]     # branch + dirty + broken-symlink table
+dev-cockpit mount clear  [options]     # remove overlay + manifest + managed symlinks
+```
+
+### Interactive picker
+
+When `mount` runs with discoverable candidates (from `profile.mountCandidatesProvider`) and no `--quiet`, it opens a checkbox picker. Bare-config consumers (only `config.mounts[]`, no provider) bypass the picker — config entries are taken as-is.
+
+### Status
+
+`mount status` prints a table per active mount with auto-enriched columns:
 
 ```
-dev-cockpit mount [-s|--service <name>]   # write/refresh the overlay
-dev-cockpit mount status                  # print active overlay manifest
-dev-cockpit mount clear                   # delete overlay + manifest
+NAME             BRANCH                  DIRTY
+----             ------                  -----
+api              feat/redis-cache        yes
+worker           main                    no   [BROKEN SYMLINK]
 ```
 
-If `--service` is omitted, the first entry in `config.docker.services` is used. Pass `--service` explicitly when your compose file has multiple services and you want mounts attached to a non-default one.
+- **branch / dirty**: auto-detected via `git -C <hostPath> rev-parse --abbrev-ref HEAD` + `git status --porcelain`. Non-git host paths show `?`.
+- **broken-symlink**: only when the profile supplies a `mountSymlinks` strategy (see below). Otherwise the column is omitted.
+- Extra columns: profile-supplied `mountStatusEnricher` can return arbitrary `extra: { columnName: value }` per row.
 
-## Profile-side discovery
+### Clear
 
-A profile that scans a manifest (e.g. `composer.json`, `package.json` workspaces) for local checkouts implements `mountCandidatesProvider` and returns `Mount[]`. Discovered candidates blend with `config.mounts[]` automatically:
+`mount clear` removes the overlay file, the manifest, and any managed symlinks (if a `mountSymlinks` strategy is defined). Then it calls `profile.onMountClear(ctx)` with the previous mount set — that's where consumers run things like `composer install` or `npm install` to restore whatever the mounts had shadowed.
+
+## Profile hooks
+
+Profiles plug in via five optional fields on the `Profile` interface:
 
 ```ts
+import type { Profile } from 'dev-cockpit';
+
 export const myProfile: Profile = {
   appName: 'my-app',
-  mountCandidatesProvider(): Mount[] {
-    return findLocalCheckouts().map((c) => ({
-      hostPath: c.hostPath,
-      containerPath: c.containerPath,
-    }));
-  },
+
+  /** Discover mount candidates programmatically. */
+  mountCandidatesProvider() { ... },
+
+  /** Run after overlay + manifest are written. Typical: `docker compose restart <svc>`. */
+  async onMountApply(ctx) { ... },
+
+  /** Run after overlay + manifest + symlinks are removed. Typical: restore deps. */
+  async onMountClear(ctx) { ... },
+
+  /** Optional IDE-facing symlinks applied + removed alongside the overlay. */
+  mountSymlinks: { linkPath: (mount, workspaceRoot) => '...' },
+
+  /** Per-row column enrichment for `mount status`. */
+  async mountStatusEnricher(mount, ctx) { ... },
 };
 ```
+
+### `mountCandidatesProvider() → Mount[] | Promise<Mount[]>`
+
+Discover candidates from whatever convention the consumer uses (composer.json, package.json workspaces, etc.). Return `Mount[]` with `hostPath` + `containerPath` set; populate `meta` for downstream hooks:
+
+```ts
+mountCandidatesProvider() {
+  return findLocalCheckouts().map((c) => ({
+    hostPath: c.hostPath,
+    containerPath: `/srv/${c.name}`,
+    meta: { name: c.name, type: c.type },
+  }));
+}
+```
+
+### `onMountApply(ctx) → Promise<void>`
+
+Called after the overlay and manifest are written. Common move: restart the docker service so the new mounts take effect.
+
+```ts
+async onMountApply(ctx) {
+  await execa('docker', ['compose', 'restart', 'web'], { cwd: ctx.workspaceRoot });
+}
+```
+
+`ctx` carries `workspaceRoot`, the freshly-applied `mounts[]`, and `log` / `errLog` callbacks that route to the cockpit's Output pane.
+
+### `onMountClear(ctx) → Promise<void>`
+
+Called after the overlay + manifest + symlinks are removed. `ctx.previous` holds the mount set that was just cleared. Typical: re-install whatever the mounts had shadowed.
+
+```ts
+async onMountClear(ctx) {
+  if (ctx.previous.length === 0) return;
+  await execa('npm', ['install'], { cwd: ctx.workspaceRoot });
+}
+```
+
+### `mountSymlinks: MountSymlinkStrategy`
+
+Some package managers expect the on-disk path to exist even when a bind-mount shadows it (composer installer-paths, npm install-from-disk, etc.). The symlink strategy creates host-side symlinks alongside the overlay so IDE tooling (LSPs, file watchers, debuggers) can follow into the live clone:
+
+```ts
+mountSymlinks: {
+  linkPath(mount, workspaceRoot) {
+    const name = mount.meta?.name;
+    if (typeof name !== 'string') return null; // skip mounts without metadata
+    return path.join(workspaceRoot, 'vendor', name);
+  },
+}
+```
+
+Return `null` for mounts that shouldn't get a symlink. Symlinks are removed by `mount clear`; `mount status` detects broken ones (target moved or deleted) and surfaces them in the table.
+
+### `mountStatusEnricher(mount, ctx) → MountStatusInfo`
+
+Add custom columns or override the auto-detected `branch` / `dirty` / `brokenSymlink` flags:
+
+```ts
+async mountStatusEnricher(mount, { workspaceRoot }) {
+  return {
+    extra: {
+      tests: await runTestsForMount(mount) ? 'pass' : 'fail',
+    },
+  };
+}
+```
+
+## Manifest schema
+
+```json
+{
+  "version": 1,
+  "appName": "my-app",
+  "workspaceRoot": "/abs/path",
+  "service": "web",
+  "overlayPath": "/abs/path/docker-compose.dev-cockpit.yml",
+  "mounts": [
+    {
+      "hostPath": "/abs/host/api",
+      "containerPath": "/srv/api",
+      "meta": { "name": "api", "type": "package" }
+    }
+  ],
+  "appliedAt": "2026-05-11T00:00:00.000Z"
+}
+```
+
+Re-running `mount` overwrites the manifest with the new applied set. `mount clear` deletes it.
+
+## Notes for wrappers upgrading from older manifest filenames
+
+If your wrapper previously used a different manifest filename (e.g. a profile that pre-dates the mount lift into dev-cockpit core wrote `dev-link.manifest.json`), the new default is `mount.manifest.json`. Two options:
+
+1. **Adopt the new default**: run `mount` once. The new file replaces the legacy one (which is left orphaned in the state dir — safe to delete).
+2. **Keep the legacy filename**: set `config.mount.manifestFile: dev-link.manifest.json` in cockpit.yaml.
+
+Same applies to the overlay path — set `config.mount.overlayPath` if your wrapper expects a specific location for its compose stack.

package/docs/notifications.md

@@ -14,26 +14,27 @@ OS notifications fire on **state transitions only** — never on every check, ne
        - recovered
    ```
 
-2. **Per-item override** — a `notify:` field on any watcher or health check:
+2. **Per-item override** — a `notify:` field on any process or health check:
 
    ```yaml
-   - id: lint
-     command: npx eslint . --watch
-     notify: false                       # mute this item
-
-   - id: api-up
-     type: http-ok
-     url: http://localhost:3000/health
-     notify:
-       onTransitionTo: [error]           # only on going-down, not on recovery
+   processes:
+     - id: lint
+       command: npx eslint . --watch
+       notify: false                     # mute this item
+
+   health:
+     - id: api-up
+       type: http-ok
+       url: http://localhost:3000/health
+       notify:
+         onTransitionTo: [error]         # only on going-down, not on recovery
    ```
 
 3. **Session toggle** — press `n` in the cockpit to mute *all* notifications for the current session (overrides config). The Health pane shows the current session state at the bottom.
 
 ## Events
 
-- `health-failed` / `health-recovered` — emitted by the health framework
-- `build-failed` / `build-recovered` — emitted by watchers
-- Profiles can emit their own event names; they flow through the same pipeline.
+- `health-failed` / `health-recovered` — emitted by the health framework on state transitions.
+- Profiles can emit their own event names (`build-failed`, `db-disconnect`, anything domain-specific) via the exported `emitEvent` helper; they flow through the same `enabled` + `onTransitionTo` + `exclude` policy.
 
 The `appName` configured in `cockpit.yaml` is used as the title prefix on every notification (e.g. `my-app — API responds`).

package/docs/panes.md

@@ -1,28 +1,47 @@
 # Panes
 
-## Repos
+Four panes cycle via `←` / `→` or `Tab` / `Shift-Tab`. Empty panes hide automatically — Targets hides when no rows are seeded, Health hides when no checks are registered.
 
-Glyphs:
+## Targets
+
+Two-column layout when the terminal is at least 200 cols wide: row list on the left, actions for the selected row on the right. Narrower terminals stack vertically (list on top, actions below).
+
+```
+┌── Targets ──────────────────┬── Actions for `ticker` (process) ────┐
+│  ▸ ○  web      [docker]   │   [r] Restart ticker      (default)  │
+│    ○  db       [docker]   │   [t] Run tests                       │
+│    ○  ticker   [process]  │                                       │
+│    ●  api                 │                                       │
+└───────────────────────────┴───────────────────────────────────────┘
+```
+
+### Row kinds
+
+| Kind | Source | Built-in `r` |
+|---|---|---|
+| `repo`     | `config.repos[]` or `profile.reposProvider()` | none — declare an action |
+| `docker`   | `config.docker.services[]` | `docker compose restart <service>` |
+| `process`  | `config.processes[]` | kill + respawn (tagged spawn lookup) |
+
+### Status glyphs
 
 - ● running (green)
-- ○ idle (gray/dim)
+- ○ idle (gray)
 - ✗ failing (red)
 
-Lint sub-glyph (after the name): ✓ pass · ! fail · (none) unknown.
-
-Selected row is marked with a leading `>` and the pane border is highlighted when this pane has focus.
+Lint sub-glyph (after the name): ✓ pass · ! fail · (none) unknown. The leading `▸` marks the selected row; the pane border highlights when this pane has focus.
 
-Actions (when a row is selected):
+### Keystrokes
 
-- `r` — primary action (rebuild for repo entries, restart for Docker entries)
-- `w` — toggle watcher (repo entries only)
-- `l` — run lint (repo entries only)
+- `↑` / `↓` — move selection
+- `<key>` (any single character) — fire the first matching action for the selected row from the action registry. Match rule: action whose `scope` is `repos:<rowId>` or `repos` AND whose `key` equals the keystroke. Declared actions win over built-ins on (scope, key) collision so you can shadow the default `r`.
+- `:` — open the `:` command palette (any tab; not Targets-specific)
 
-In-flight actions show a banner at the top of the pane plus an inline `(running…)` next to the active row.
+If no action matches, the keystroke is a silent no-op — the right-side panel lists exactly what's bound, including built-ins tagged `(default)`.
 
 ## Output
 
-Streaming source-tagged logs.
+Streaming source-tagged logs. Severity is shown by a leading glyph (`⚠` warn, `✗` error; info has none) so lines remain scannable without color.
 
 - `↑` / `↓` — scroll one line
 - `PgUp` / `PgDn` — scroll one page
@@ -36,10 +55,12 @@ A "Recent errors" strip appears at the top when one or more error lines have bee
 
 ## Health
 
-Each row shows: severity glyph, label, remediation key (if any). `Enter` toggles the diagnostic detail for the selected row. Press the remediation letter to fix.
+Each row shows: severity glyph (`✓` ok, `⚠` warn, `✗` error), label, remediation key (if any). `Enter` toggles the diagnostic detail for the selected row. Press the remediation letter (case-insensitive — declared `R` matches both `r` and `R`) to fire the fix.
 
-While a remediation runs, a banner appears at the top and the running row shows `…  (running…)`.
+While a remediation runs, a banner appears at the top and the running row shows `(running…)`.
 
 ## Help
 
-This pane. `j` / `k` (or `Shift-Tab` / `Tab`) cycle pages. `↑` / `↓` scroll. `g` / `G` jump to top / bottom. `←` / `→` always exit Help to the next tab.
+Live-rendered markdown. `j` / `k` (or `Shift-Tab` / `Tab`) cycle pages. `↑` / `↓` scroll. `g` / `G` jump to top / bottom. `←` / `→` always exit Help to the next tab.
+
+Under narrow terminals (< 200 cols), the page-title strip hides and the legend collapses to `[j/k] page i/N` to save space.

package/docs/processes.md

@@ -0,0 +1,42 @@
+# Processes
+
+A process is a long-running command — `tsc --watch`, `vitest --watch`, `npm run dev`, `php artisan serve`, `tail -f some.log` — declared in `cockpit.yaml` under `processes:`. The cockpit spawns each process once at boot and streams its stdout / stderr into the Output pane, tagged by source.
+
+Distinct from:
+- **Actions** (one-shot shell commands surfaced via the `:` palette and per-row keys)
+- **Health checks** (state predicates with one-keystroke remediation)
+- **Docker tailing** (`config.docker` — already managed by docker compose)
+
+## Config shape
+
+```yaml
+processes:
+  - id: typecheck                       # required, unique; used as the Output source tag and Targets row id
+    label: tsc --watch                  # optional; shown in Repos + Output
+    command: npx tsc --watch --noEmit   # shell command; runs via sh -c (cmd /c on Windows)
+    cwd: ./apps/web                     # optional; relative to workspaceRoot
+    env:                                # optional; merged on top of process.env
+      DEBUG: '1'
+```
+
+`command` runs through the shell so pipes, redirects, env-prefixes, and properly-quoted arguments all work as expected.
+
+## Built-in restart
+
+Every process gets a Targets row of `kind: process` with a built-in action `[r] Restart <id>` (key: `r`, scope: `repos:<id>`). The implementation: SIGTERM the tagged child (via `killSpawnedByTag`), wait for it to exit, then re-spawn it with the same command + cwd + env.
+
+You can shadow `r` with a custom action of the same scope + key — declared actions outrank built-ins in the dispatch precedence.
+
+## Output + highlights
+
+Each line from a process's stdout / stderr gets:
+- The source label (or `id`) as a tag.
+- Default severity: `info` for stdout, `warn` for stderr.
+- Highlight matching against `config.highlights[]`. A matched pattern's `severity:` wins over the default — so a `pattern: 'boom', severity: error` highlight upgrades any line containing "boom" to `error`, which shows as `✗`-prefixed in Output and feeds the Recent Errors strip.
+
+## Lifecycle
+
+- Spawned on `dev-cockpit dev` boot.
+- Tagged with the process's `id` so the per-row restart action can find the right child.
+- Reaped on cockpit shutdown (`q` or SIGTERM) via `killAllSpawned` — SIGTERM with a 1.5s SIGKILL fallback.
+- No fsevent-driven respawn — the process command itself (`tsc --watch`, etc.) is expected to handle re-runs internally.