@martintrojer/mu 0.3.2 → 0.4.1

package/AGENTS.md

@@ -13,8 +13,9 @@ write code. Follow the conventions below.
 
 1. **[docs/USAGE_GUIDE.md](docs/USAGE_GUIDE.md)** — what mu does
    from a user's perspective. ~10 minutes.
-2. **[CHANGELOG.md](CHANGELOG.md)** — the v0.1.0 release entry.
-   Single source of truth for the verb list, schema, env vars.
+2. **[CHANGELOG.md](CHANGELOG.md)** — the upcoming version's
+   entry (currently `[0.4.1] — 2026-05-14`). Single source of truth
+   for the verb list, schema, env vars.
 3. **[docs/VISION.md](docs/VISION.md)** — the load-bearing pillars.
    The design principles you must not violate.
 4. **[docs/ROADMAP.md](docs/ROADMAP.md)** — what's next, with
@@ -24,13 +25,22 @@ write code. Follow the conventions below.
    **Source of truth for every word** in code, docs, and error
    messages. If you use a term not defined there, fix the docs first.
 6. **[docs/ARCHITECTURE.md](docs/ARCHITECTURE.md)** — module layout,
-   reconciliation algorithm, key seams.
+   reconciliation algorithm, TUI architecture, key seams.
 
 Design rationale for rejected and unbuilt features (DSL, snapshots,
 task_artifacts, ...) is now folded into
 [docs/ROADMAP.md](docs/ROADMAP.md) per item, alongside its
 promotion criteria.
 
+> **If you are an orchestrator** — a coding agent driving a crew of
+> pi worker agents on this repo via `mu` — read
+> **[docs/HANDOVER.md](docs/HANDOVER.md)** instead of the order
+> above. It is the goto reset doc for orchestrators: onboarding
+> steps, the 8-phase dispatch loop, conflict-resolution playbook,
+> known gotchas, and end-of-session checklist. AGENTS.md is for
+> workers (and humans editing the repo directly); HANDOVER.md is for
+> orchestrators.
+
 ---
 
 ## Repo layout
@@ -41,39 +51,53 @@ mu/
 ├── AGENTS.md              # this file
 ├── CHANGELOG.md           # release notes
 ├── docs/                  # everything else
-│   ├── USAGE_GUIDE.md
-│   ├── ROADMAP.md         # what's next; promotion criteria
-│   ├── VISION.md
-│   ├── VOCABULARY.md
-│   └── ARCHITECTURE.md
+│   ├── USAGE_GUIDE.md     # user-facing tour (§ 5b is the TUI reference)
+│   ├── HANDOVER.md        # orchestrator goto reset doc (8-phase loop + gotchas)
+│   ├── ROADMAP.md         # what's next; promotion criteria; anti-feature pledges
+│   ├── VISION.md          # load-bearing pillars
+│   ├── VOCABULARY.md      # canonical terms (single source of truth)
+│   └── ARCHITECTURE.md    # module layout, TUI architecture, key seams
 ├── src/                   # all source (root files: SDK + shared infra; one
 │                          # level of subdirs OK for cohesive clusters — see
 │                          # `src/cli/`, `src/agents/`, `src/tasks/` below)
-│   ├── db.ts              # SQLite schema + openDb (single CREATE-IF-NOT-EXISTS block)
+│   ├── db.ts              # SQLite schema + openDb (single CREATE-IF-NOT-EXISTS block; v8)
 │   ├── tmux.ts            # tmux wrapper, send protocol, pane validation
-│   ├── detect.ts          # pi-only status detector
+│   ├── detect.ts          # pi status detector + Braille-spinner fallback for other CLIs
 │   ├── reconcile.ts       # ghost prune + status detect + orphan surface
 │   ├── agents.ts          # CRUD + send/read/list/close/free + liveness + reaper hub (re-exports src/agents/*)
 │   ├── agents/            # cohesive cluster of agent-lifecycle internals
 │   │   ├── spawn.ts       # spawnAgent + resolveCliCommand / awaitSpawnLiveness / pane create-or-reuse / prestage / rollback
+│   │   ├── kick.ts        # reaper events + cleanup of dead agent rows
 │   │   ├── adopt.ts       # adoptAgent: register an existing tmux pane as a managed agent
 │   │   └── errors.ts      # typed agent error classes (AgentNotFoundError, AgentDiedOnSpawnError, …)
-│   ├── tasks.ts           # task SDK hub (re-exports src/tasks/* + edit/edges/queries verbs)
+│   ├── tasks.ts           # task SDK hub (re-exports src/tasks/*)
 │   ├── tasks/             # cohesive cluster of task-graph internals
-│   │   ├── status.ts      # TaskStatus enum + helpers (single source of truth for statuses)
-│   │   ├── claim.ts       # claim/release + resolveActorIdentity (atomic CAS)
+│   │   ├── status.ts      # TaskStatus enum + helpers
+│   │   ├── core.ts        # core SDK funcs reused across cluster files
+│   │   ├── id.ts          # tryResolveTaskId / qualified-id helpers
+│   │   ├── queries.ts     # listTasks / nextTasks / owned-by
+│   │   ├── edit.ts        # addTask / setTaskTitle / etc (no edges)
+│   │   ├── edges.ts       # block / unblock / reparent / delete + dedupe
+│   │   ├── claim.ts       # claim / release + resolveActorIdentity (atomic CAS)
 │   │   ├── lifecycle.ts   # setTaskStatus / closeTask / openTask / rejectTask / deferTask + cascade
 │   │   ├── wait.ts        # waitForTasks: block until tasks reach a target status
+│   │   ├── sort.ts        # sortTasks (roi / recency / age / id)
 │   │   └── errors.ts      # typed task error classes (TaskAlreadyOwnedError, CycleError, …)
 │   ├── tracks.ts          # parallel-tracks union-find with diamond merge
 │   ├── workstream.ts      # ensureWorkstream / list / summarize / destroy / export
-│   ├── archives.ts        # cross-workstream archive buckets (create / add / remove / restore)
-│   ├── exporting.ts       # unified bucket renderer (workstream + archive export)
-│   ├── importing.ts       # inverse of exporting.ts: parse a v0.3 bucket dir → live DB rows
+│   ├── archives.ts        # cross-workstream archive bucket SDK hub (re-exports src/archives/*)
+│   ├── exporting.ts       # unified bucket renderer (workstream + archive export; read-only buckets)
+│   ├── db-sync.ts         # whole-DB export/import + drift detection + sidecar park SDK
+│   ├── db-sync-replay.ts  # manual replay of divergence sidecars parked by db import --force-source
 │   ├── logs.ts            # agent_logs SDK (append, list, latestSeq, emitEvent)
-│   ├── vcs.ts             # VcsBackend interface + jj/sl/git/none impls
-│   ├── workspace.ts       # per-agent VCS workspaces (CRUD over vcs_workspaces)
-│   ├── snapshots.ts       # whole-DB snapshots (VACUUM INTO) + auto-capture hook
+│   ├── vcs.ts             # VcsBackend hub (re-exports src/vcs/*: jj/sl/git/none impls)
+│   ├── workspace.ts       # per-agent VCS workspaces hub (re-exports src/workspace/*)
+│   ├── snapshots.ts       # whole-DB snapshots hub (re-exports src/snapshots/*)
+│   ├── dag.ts             # full-DAG forest builder (loadFullDag for `mu task tree` + DAG popup)
+│   ├── state.ts           # SDK seam for `mu state` (fast SQL tier + slow subprocess tier + merge)
+│   ├── staleness.ts       # WORKSPACE_STALE_THRESHOLD + isStaleWorkspace
+│   ├── project-root.ts    # detectProjectRoot for the TUI launch cwd ladder
+│   ├── doctor-summary.ts  # TUI-friendly slice of `mu doctor` checks + remediation helpers
 │   ├── output.ts          # NextStep type + printNextSteps / errorNextSteps
 │   ├── cli.ts             # commander wiring (buildProgram); re-exports format/handle for back-compat
 │   ├── cli/               # one file per verb-namespace; thin wrappers over the SDK
@@ -88,17 +112,52 @@ mu/
 │   │   │   ├── claim.ts      # claim / release / wait
 │   │   │   ├── tree.ts       # tree rendering
 │   │   │   └── wire.ts       # Commander glue
-│   │   ├── workspace.ts   # workspace create / list / free / path / orphans
+│   │   ├── workspace.ts   # workspace create / list / free / path / orphans / refresh / commits
 │   │   ├── log.ts         # log read / write / tail
-│   │   ├── archive.ts     # archive create / list / show / add / remove / delete
-│   │   ├── state.ts       # `mu state` (canonical state card) + bare `mu` (mission control / hud render mode)
+│   │   ├── archive.ts     # archive create / list / show / add / restore / remove / delete
+│   │   ├── state.ts       # `mu state` (canonical state card); --tui dispatches to src/cli/tui/
+│   │   ├── staleness.ts   # shared workspace-staleness CLI helpers + warn formatter
+│   │   ├── tui-launch-focus.ts # initial-tab focus ladder for bare `mu` and `mu state --tui`
+│   │   ├── tui/           # interactive ink-based TUI cluster; ONLY place ink/react are imported
+│   │   │   ├── index.ts            # runTui entrypoint; alt-screen + mouse-mode lifecycle
+│   │   │   ├── escapes.ts          # pure ANSI escape constants (ALT_SCREEN_*, mouse-mode bytes) — no ink imports
+│   │   │   ├── app.tsx             # <App> root (popup state machine + global keymap + footer + tick + tabs)
+│   │   │   ├── state.ts            # poll-loop hook (useDashboardSnapshot; fast/slow tick split)
+│   │   │   ├── keys.ts             # pure dispatchGlobalKey + dispatchPopupKey + shouldSwallowGlobalKey
+│   │   │   ├── keymap-spec.ts      # canonical keymap source-of-truth (drives help overlay + dispatch)
+│   │   │   ├── yank.ts             # clipboard probe + write (pbcopy/wl-copy/xclip/xsel/clip.exe + OSC-52)
+│   │   │   ├── mouse.ts            # vendored SGR mouse layer (parser + double-click + useMouse hook)
+│   │   │   ├── layout.ts           # responsive multi-column dashboard + per-card row budgets
+│   │   │   ├── columns.ts          # column-aligned row layout with protect/clip clipping
+│   │   │   ├── wrap-ansi.ts        # ANSI-aware visual-width line wrapper + SGR close-on-end
+│   │   │   ├── glyphs.ts           # superscript digit + status glyphs
+│   │   │   ├── format-helpers.ts   # shared TUI formatters (relTime, sinceClaim, ROI, etc.)
+│   │   │   ├── titled-box.tsx      # rounded border with section header inset into top border + bottomLabel
+│   │   │   ├── popup-shell.tsx     # popup outer chrome (cyan TitledBox)
+│   │   │   ├── list-row.tsx        # centralised non-selected row primitive (width pin + gutter + truncate)
+│   │   │   ├── padded-rows.tsx     # per-card body padder
+│   │   │   ├── help.tsx            # ?/F1 keymap overlay (scrollable on short panes)
+│   │   │   ├── status-bar.tsx      # bottom status bar (mode + active ws + tick + footer flash)
+│   │   │   ├── tab-strip.tsx       # multi-workstream tab switcher (N≥2)
+│   │   │   ├── tab-strip-layout.ts # pure window-around-active layout helper for the tab strip
+│   │   │   ├── tuicr.ts            # `t` shortcut: alt-screen handoff to tuicr -r <sha>
+│   │   │   ├── use-popup-filter.tsx       # shared '/' substring filter hook + applyFilter + FilterPrompt
+│   │   │   ├── use-status-filter.tsx      # task-status toggles for task-list popups (o/i/c/r/d)
+│   │   │   ├── use-notes-drill.ts         # shared notes-drill memo (5 task popups consume it)
+│   │   │   ├── use-popup-action-queue.ts  # consume mouse PopupAction queue once per render
+│   │   │   ├── cards/{agents,tracks,ready,log,workspaces,inprogress,blocked,recent,commits,doctor}.tsx + _placeholder.tsx
+│   │   │   └── popups/{agents,tracks,ready,log,workspaces,inprogress,blocked,recent,commits,doctor,dag,all-tasks}.tsx
+│   │   │                          # plus drill.tsx (DrillScrollView), task-detail.tsx (TaskDetailDrill),
+│   │   │                          # cursor-row.tsx, scroll.ts (applyCursor/applyScroll), viewport.ts,
+│   │   │                          # show-loader.ts (shared subprocess-preserving loader)
 │   │   ├── snapshot.ts    # undo / snapshot list / snapshot show
+│   │   ├── db.ts          # db export / import / replay
 │   │   ├── sql.ts         # sql escape hatch
 │   │   ├── doctor.ts      # doctor diagnostic
 │   │   ├── format.ts      # pure rendering helpers (table renderers, status colourers, truncate/relTime)
 │   │   └── handle.ts      # typed-error → exit-code map + handle() wrapper
 │   └── index.ts           # SDK entrypoint (re-exports)
-├── test/                  # 60 files / 57 *.test.ts / ~996 it()/test() calls; many use real tmux/git/jj/sl
+├── test/                  # ~165 *.test.ts files / ~2000 it()/test() calls; many use real tmux/git/jj/sl
 ├── skills/mu/SKILL.md     # what the LLM running inside an agent pane sees
 ├── package.json           # bin: { mu: ./dist/cli.js }, type: module
 ├── tsconfig.json          # strict + noUncheckedIndexedAccess + verbatimModuleSyntax
@@ -116,15 +175,20 @@ mu/
 ```bash
 npm install
 npm run build            # tsup → dist/
-npm run typecheck        # tsc --noEmit
+npm run typecheck        # source + test TypeScript checks
 npm run lint             # biome check src test
-npm run test             # vitest run
+npm run test:fast        # fast unit/dev-loop tier (excludes *.integration.test.ts / *.smoke.test.ts)
+npm run test             # full vitest suite, including integration tests
 npm run test:watch       # vitest in watch mode
+npm run test:watch:fast  # fast-tier watch mode
 ```
 
-All four must pass before any commit. Tests include real-tmux
-integration tests that need `$TMUX` set. If you're not in tmux,
-those tests skip themselves; CI runs inside tmux.
+Use `npm run test:fast` for the inner dev loop and concurrent
+worker checks; it is the concurrency-safe tier that avoids real
+tmux/VCS subprocess integration fixtures. All four green gates still
+include `npm run test` (the full suite) before any commit. Full tests
+include real-tmux integration tests that need `$TMUX` set. If you're
+not in tmux, those tests skip themselves; CI runs inside tmux.
 
 ### Commits
 
@@ -170,17 +234,74 @@ those tests skip themselves; CI runs inside tmux.
 
 - Unit tests: real SQLite (in-temp-dir), mocked tmux executor via
   `setTmuxExecutor()`. Fast, deterministic.
-- Integration tests: real tmux server. File suffix
-  `.integration.test.ts` (e.g. `tmux.integration.test.ts`). Skipped
-  when `$TMUX` is unset. These tests typically opt out of the spawn
+- TUI popup/card behaviour tests should follow `test/README.md`:
+  prefer the `test/_ink-render.ts` CaptureStream seam over
+  `readFileSync` source-greps except for narrow structural guards.
+- Fast tier: `npm run test:fast` runs `test/**/*.test.ts` while
+  excluding `*.integration.test.ts` and `*.smoke.test.ts`. Keep this
+  tier pure/in-process: mocked tmux/VCS, real SQLite only in per-test
+  temp DBs, no real tmux/git/jj/sl subprocess fixtures, no
+  filesystem-heavy export/import/snapshot paths, and no fixed sleeps
+  above 50ms.
+- Integration tests: full-only tests use the `.integration.test.ts`
+  suffix (e.g. `tmux.integration.test.ts`). They may touch real tmux
+  servers, git/jj/sl fixture repos, subprocess-backed smoke paths,
+  filesystem-heavy export/import/snapshot flows, or intentionally
+  slower in-process CLI flows. Real-tmux tests are skipped when
+  `$TMUX` is unset. These tests typically opt out of the spawn
   liveness check via `process.env.MU_SPAWN_LIVENESS_MS = "0"` in
   `beforeEach` since the long-running sh subprocesses they spawn are
   intentionally alive.
 - Each test gets its own temp DB and (for integration) a unique
   tmux session like `mu-test-<pid>-<ts>-<rand>` to avoid colliding
   with the user's panes or with parallel test runs.
-- The acceptance test in `test/acceptance.test.ts` is the
+- Dogfood reality: multiple pi worker agents often run `npm run test`
+  concurrently on the same machine from different workspaces. Treat
+  flakes that pass in isolation but fail under load as concurrency
+  bugs first (shared `/tmp` cleanup, tmux socket/session collisions,
+  leaked subprocesses, VCS background file activity). Use
+  `npm run test:stress` for the pre-release/stability gate; it runs
+  the suite repeatedly with a per-run timeout and can simulate
+  parallel full-suite runs via
+  `MU_TEST_STRESS_MODE=parallel MU_TEST_STRESS_PARALLEL=2`.
+- The acceptance test in `test/acceptance.integration.test.ts` is the
   "everything works" gate. Keep it passing.
+- **DB baseline**: `openDb()` refuses to open the user's REAL
+  default DB (`<HOME or XDG_STATE_HOME>/mu/mu.db`) when
+  `process.env.VITEST` is set or `NODE_ENV === "test"`. Tests
+  MUST use a per-test temp DB — either via MU_DB_PATH (which
+  `test/_runCli.ts` sets automatically) or an explicit `{ path }`
+  argument to `openDb`. A regression that forgets either one
+  fails loudly at the offending openDb() call site instead of
+  silently writing to the dev box's live state. Production never
+  sets VITEST, so the guard is a no-op outside the test runner.
+- **Env baseline**: `test/_setup.ts` (vitest `setupFiles`) clears
+  every `MU_*` env var inherited from the parent shell at the start
+  of each fork, so SDK-level overrides (`MU_PI_COMMAND`,
+  `MU_IDLE_THRESHOLD_MS`, `MU_SEND_DELAY_MS`, …) can't silently
+  change behaviour underneath tests. Allowlist: `MU_TMUX_SOCKET`
+  (set by `_global-teardown.ts` at MODULE LOAD time — BEFORE vitest
+  spawns the worker pool — for Layer-3 isolation; see round-3
+  Part A in the file's header comment for why module-load not
+  setup()). Tests that need a specific value opt IN per-test via
+  `process.env.X = "..."` or `withEnv()` from `test/_env.ts`.
+- **Default-socket sweep philosophy**: `_global-teardown.ts` runs
+  an ALLOWLIST sweep of `mu-*` sessions on the user's default tmux
+  socket at suite setup AND teardown. The allowlist is DB-rooted:
+  (1) `mu-<name>` for every workstream in the user's REAL DB
+  (read-only via better-sqlite3, bypassing the `openDb()` test
+  guard) and (2) `mu-$MU_SESSION` if the orchestrator runs the suite
+  inside a tmux pane. Anything else is, by elimination, test residue
+  and is killed. Replaces the old regex-prefix sweep that missed
+  bare-name leftovers like `mu-alpha` / `mu-demo` / `mu-ws`. Round-4
+  removed the previous "pre-existing sessions snapshot" source
+  (`bug_test_flake_round_4_self_heal`): leftover test residue at
+  module-load time was getting grandfathered in as protected forever,
+  defeating the self-healing intent. Cost: an ad-hoc
+  `tmux new-session -t mu-foo` with no DB row gets killed; workaround
+  is `mu workstream init foo` first. New tests can hardcode any
+  workstream name they want — if they accidentally bypass the
+  private socket the sweep catches them by default.
 
 ### When you change behaviour, update VOCABULARY first
 
@@ -208,12 +329,18 @@ meeting these criteria, **stop**. Add an entry to
 The "anti-feature pledges" in ROADMAP.md are firm:
 
 - No config file
-- No daemon
+- No daemon / background process beyond what tmux + SQLite give us
 - No anticipatory abstractions (no traits with zero implementors)
 - No wrappers around wrappers
-- No codegen
-- An agent template/discovery system requires explicit promotion
-- No render layer beyond `cli-table3` + `picocolors`
+- No codegen / embedded JS engine / workflow DSL
+- No template/discovery system for agent roles (spawn flags + first
+  message ARE the definition)
+- No render layer beyond `cli-table3` + `picocolors`, EXCEPT `ink`
+  confined to `src/cli/tui/`. NO second TUI stack alongside `ink`
+  (no `blessed` / `terminal-kit` etc.); if `ink` ever stops paying
+  off, REPLACE it, don't stack stacks.
+- No plugin runtime, web UI, RPC, chat/docs integrations, memory
+  system, workflow engine
 - Don't bundle pi (it's a peer dep)
 
 ### When in doubt: be small
@@ -252,11 +379,27 @@ real friction proves itself.
 
 ### "Update the schema"
 
-1. 0.1.0 has no migration layer. Schema lives in `src/db.ts` as a
-   single CREATE-IF-NOT-EXISTS block. The first non-additive
-   change should land alongside a `schema_version` table.
-2. Update tests that exercise the schema (`test/db.test.ts`).
-3. Update [CHANGELOG.md](CHANGELOG.md) §"Schema" snapshot.
+1. Current schema version is **v8** (see `CURRENT_SCHEMA_VERSION`
+   in `src/db.ts`). The schema lives in `src/db.ts` as the
+   `applySchema(db)` block, which is idempotent CREATE-IF-NOT-EXISTS
+   plus targeted `DROP TABLE IF EXISTS` for retired tables
+   (e.g. v7's `DROP TABLE IF EXISTS approvals`). v8 is additive:
+   `machine_identity` and `workstream_sync` are
+   `CREATE TABLE IF NOT EXISTS`, and `openDb` seeds the single
+   `machine_identity` row on first open. `openDb` rejects pre-current
+   DBs with `SchemaTooOldError` (exit 4) and a migration hint.
+2. Bump `CURRENT_SCHEMA_VERSION` in `src/db.ts` and mirror the new
+   shape in `CURRENT_SCHEMA`. Three of the last four bumps were
+   script-free: v5 → v6 was purely additive (existing
+   CREATE-TABLE-IF-NOT-EXISTS picked up new tables); v6 → v7 was a
+   destructive-but-idempotent `DROP TABLE` block; v7 → v8 is
+   additive plus the `machine_identity` seed. Reach for a one-shot
+   migration script only when the change can't be expressed that way
+   (the v4 → v5 surrogate-PK substrate switch was the canonical
+   example).
+3. Update tests that exercise the schema (`test/db.test.ts`).
+4. Update [CHANGELOG.md](CHANGELOG.md) under the upcoming version's
+   `### Changed` section.
 
 ### "Add a new tmux operation"
 
@@ -322,11 +465,12 @@ processes need time to settle. Use:
 Before opening a PR or marking a task complete:
 
 ```bash
-npm run typecheck && npm run lint && npm run test && npm run build
+npm run typecheck && npm run lint && npm run test:fast && npm run test && npm run build
 ```
 
-All four green. The acceptance test (`test/acceptance.test.ts`)
-must pass — it's the "end-to-end works" gate.
+All four green gates, plus the fast dev-loop tier. The acceptance
+test (`test/acceptance.integration.test.ts`) must pass — it's the
+"end-to-end works" gate.
 
 Checklist for any non-trivial change:
 

package/README.md

@@ -2,28 +2,39 @@
 
 **A small, opinionated control plane for a crew of AI coding agents
 working in parallel.** One tmux session, a typed task DAG, isolated
-VCS workspaces per agent, an audit log — and a hard refusal to
-grow into another bloated agent framework.
+VCS workspaces per agent, an audit log — and a dashboard for seeing
+what the crew is doing right now.
+
+![mu dashboard](docs/img/tui-dashboard.png)
+
+*`mu` (no args) — read-only dashboard: agents, tracks, ready /
+in-progress / blocked tasks, log tail, workspaces, doctor.*
 
 ```bash
 mu workstream init auth-refactor
 mu task add --title "Design auth"  --impact 80 --effort-days 2
-mu task add --title "Build auth"   --impact 80 --effort-days 5 --blocks design_auth
-mu task add --title "Review auth"  --impact 60 --effort-days 1 --blocks build_auth
+mu task add --title "Build auth"   --impact 80 --effort-days 5 --blocked-by design_auth
+mu task add --title "Review auth"  --impact 60 --effort-days 1 --blocked-by build_auth
 
 mu agent spawn worker-1   --workspace
 mu agent spawn reviewer-1 --workspace --role read-only
 mu agent send worker-1 "Pick up the next ready task and design the auth module."
 
 tmux a -t mu-auth-refactor    # watch the whole crew live
-mu                            # mission control: ready tasks, parallel tracks, agent status
+mu                            # human home base: TUI with every workstream loaded
+mu state -w auth-refactor --json  # agent/script API: typed static state for jq
 mu log --tail                 # subscribe to every state change
 ```
 
-The crew is real (tmux panes you can attach to), the work graph is
-real (SQLite + a parallel-tracks algorithm with diamond-merge), the
-workspaces are real (jj workspace / sl share / git worktree), and
-**mu does not get in your model's way.**
+Crew, graph, and workspaces are all real things you can poke at:
+tmux panes (`tmux attach`), a SQLite DAG with parallel-tracks +
+diamond-merge, and jj workspace / sl share / git worktree on disk.
+**mu persists state and coordinates handoffs; the model still
+decides what to do.** Workers reach for the bundled
+[SKILL.md](skills/mu/SKILL.md) when they need in-pane ground truth.
+Bare `mu` on a TTY launches the read-only multi-workstream TUI;
+piped/scripted calls print help, so use typed verbs + `--json` (or
+`MU_NO_TUI=1`) for agent/API flows.
 
 ---
 
@@ -34,17 +45,14 @@ workspaces are real (jj workspace / sl share / git worktree), and
   task DAG with **deterministic parallel-track detection +
   diamond-merge** so two agents are never assigned tasks that share
   a prerequisite.
-- **Get out of the model's way.** Mu coordinates agents; it does
-  not reason about them. No model selection, no thinking-effort
-  knobs, no system-prompt templating, no tool routing. `--cli <key>`
-  uppercases to `$MU_<KEY>_COMMAND` — your shell rc owns the
-  mapping. Swap your whole stack in one line.
-- **A deliberate refusal to over-engineer.** One CLI. One SQLite
-  file. ~60 typed verbs. No daemon, no config file, no plugin
-  runtime, no DSL, no codegen, no web UI, no chat integration, no
-  hosted service. Each missing piece is an
-  **[anti-feature pledge](docs/ROADMAP.md#anti-feature-pledges-still-in-force-reinforced-by-an-internal-critique)**,
-  not an oversight.
+- **Stay out of the model's way.** Mu coordinates handoffs; it does
+  not make choices on behalf of the model. `--cli <key>` uppercases
+  to `$MU_<KEY>_COMMAND`, so your shell rc owns model/provider
+  selection and thinking-effort flags. The orchestrator and workers
+  drive; mu records, scopes, and yanks the next command.
+- **A local typed state surface.** One CLI, one SQLite registry,
+  typed verbs, `--json` everywhere useful, and a read-only dashboard
+  for humans.
 
 ## What mu is NOT
 
@@ -110,7 +118,31 @@ npx skills add ./skills/mu              # local-path source format
 ```
 
 More install patterns (alias-to-dist for fastest dev iteration) in
-[docs/USAGE_GUIDE.md § 1 Setup](docs/USAGE_GUIDE.md#1-setup).
+[docs/USAGE_GUIDE.md § 1 Setup](docs/USAGE_GUIDE.md#1-setup). After
+installing, run bare `mu` (or `mu state --tui`) for the dashboard tour.
+
+---
+
+## TUI dashboard
+
+Bare `mu` in a TTY launches the flagship read-only dashboard across
+all workstreams; `mu state --tui -w <workstream>` is the explicit
+single/multi-workstream form. Non-TTY callers and scripts keep the
+static/help path, and `mu state --json` is the API.
+
+The dashboard has ten cards: Commits, Agents, Tracks, Ready, Activity
+log, Workspaces, In-progress, Blocked, Recent, and Doctor. Drill into
+any numbered card fullscreen with `Shift+0`-`Shift+9`; `g` opens the
+full DAG and `t` opens the all-tasks list. `?` shows the complete
+keymap. Keyboard and mouse both work: navigate with keys, double-click
+cards or rows to drill, and scroll popup bodies with the mouse wheel.
+
+The TUI is read-only by design. `y` yanks the canonical `mu` command
+for the focused row to your clipboard; you run it in a shell, so every
+mutation still goes through a short-lived typed CLI invocation. The
+one exception is user-driven: `t` inside a commit/show drill suspends
+mu's alt-screen and hands off to `tuicr -r <sha>`, then restores the
+dashboard when tuicr exits.
 
 ---
 
@@ -125,16 +157,20 @@ mu workstream init auth-refactor
 
 # Plan the work as a DAG. IDs auto-derive from titles.
 mu task add --title "Design auth module" --impact 80 --effort-days 2
-mu task add --title "Build auth"         --impact 80 --effort-days 5 --blocks design_auth_module
-mu task add --title "Review auth"        --impact 60 --effort-days 1 --blocks build_auth
+mu task add --title "Build auth"         --impact 80 --effort-days 5 --blocked-by design_auth_module
+mu task add --title "Review auth"        --impact 60 --effort-days 1 --blocked-by build_auth
 
 # Spawn a crew with isolated workspaces.
 mu agent spawn worker-1   --workspace
 mu agent spawn reviewer-1 --workspace --role read-only
 
-# Mission control: parallel tracks, ready tasks, agent status.
+# Human home base: interactive read-only TUI across every workstream
+# (same dashboard is explicit with: mu state --tui -w auth-refactor).
 mu
 
+# Agent/script API: static state stays explicit and JSON-friendly.
+mu state -w auth-refactor --json
+
 # Inside an agent's pane, the agent claims and closes tasks
 # without ever knowing its own name (mu reads $TMUX_PANE).
 mu task claim design_auth_module
@@ -148,7 +184,26 @@ mu log --tail
 mu workstream destroy --yes
 ```
 
-Full tour: [docs/USAGE_GUIDE.md](docs/USAGE_GUIDE.md).
+Full tour: [docs/USAGE_GUIDE.md](docs/USAGE_GUIDE.md), including the
+expanded [dashboard/state guide](docs/USAGE_GUIDE.md#5-see-the-graph-dashboard--state-api).
+
+---
+
+## Portability and handoff
+
+State lives in one SQLite DB, so it travels. `mu db export <file>`
+writes a consistent whole-DB copy plus a manifest sidecar; `mu db
+import <file>` ships it back, with per-workstream drift detection
+(dry-run by default; `--apply` commits) and a sharp `--force-source`
+that parks the loser to a sidecar before clobbering. Hard rule: don't
+edit the same workstream on two machines concurrently.
+
+For humans / git / docs, `mu workstream export` and `mu archive
+export` render a workstream (or an archive bucket) as Markdown:
+per-task `.md` files plus an `INDEX.md`, suitable for committing,
+reviewing, or pasting. Bucket exports are read-only artifacts; the
+lossless un-archive path back into a live workstream is `mu archive
+restore <label> --as <new-ws>`.
 
 ---