@titan-design/active-work 0.1.0

package/scripts/gen-cli-reference.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+/**
+ * Generate `docs/cli-reference.md` by walking `active-work --help` and capturing
+ * `--help` output for every leaf sub-command.
+ *
+ * Usage:
+ *   node scripts/gen-cli-reference.mjs            # writes docs/cli-reference.md
+ *   node scripts/gen-cli-reference.mjs --stdout   # prints to stdout
+ *
+ * Requires `pnpm build` to have run so `dist/cli.js` exists.
+ */
+import { spawnSync } from 'node:child_process';
+import { writeFileSync, existsSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(__dirname, '..');
+const CLI = resolve(REPO_ROOT, 'dist/cli.js');
+const OUT = resolve(REPO_ROOT, 'docs/cli-reference.md');
+
+if (!existsSync(CLI)) {
+  console.error(`error: ${CLI} not found. Run \`pnpm build\` first.`);
+  process.exit(1);
+}
+
+/** Run the built CLI and return its stdout (help is written to stdout by commander). */
+function runHelp(args) {
+  const result = spawnSync(process.execPath, [CLI, ...args, '--help'], {
+    encoding: 'utf8',
+    env: { ...process.env, NO_COLOR: '1', FORCE_COLOR: '0' },
+  });
+  if (result.status !== 0 && result.status !== null) {
+    // commander exits 0 for help; treat anything else as a soft warning.
+    process.stderr.write(
+      `warn: \`active-work ${args.join(' ')} --help\` exited ${result.status}\n${result.stderr}\n`,
+    );
+  }
+  return (result.stdout || '').trimEnd();
+}
+
+/**
+ * Parse a `Commands:` block out of a help blob. Each entry is one or more
+ * lines: the first starts with two-space indent, then the command name,
+ * then a description that may wrap to subsequent indented lines.
+ *
+ * Returns an array of `{ name, description }`. Sub-command groups (their
+ * description is exactly `<name> commands`) are flagged via `isGroup`.
+ */
+function parseCommands(helpText) {
+  const lines = helpText.split('\n');
+  const startIdx = lines.findIndex((l) => l.trim() === 'Commands:');
+  if (startIdx === -1) return [];
+
+  const entries = [];
+  let current = null;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.trim() === '') {
+      if (current) {
+        entries.push(current);
+        current = null;
+      }
+      continue;
+    }
+    // Lines starting with two spaces and a letter begin a new command;
+    // subsequent indented continuation lines extend the description.
+    const match = line.match(/^ {2}([a-z][a-z0-9-]*)(?:\s+\[options])?(?:\s+[^ ].*?)?\s{2,}(.*)$/);
+    if (match) {
+      if (current) entries.push(current);
+      current = { name: match[1], description: match[2].trim() };
+    } else if (current && /^\s{4,}/.test(line)) {
+      current.description += ' ' + line.trim();
+    }
+  }
+  if (current) entries.push(current);
+
+  return entries
+    .filter((e) => e.name !== 'help')
+    .map((e) => ({
+      ...e,
+      isGroup: /^[a-z]+ commands$/.test(e.description),
+    }));
+}
+
+/**
+ * Walk help recursively to enumerate every leaf command path.
+ * A leaf is any command whose own help has no `Commands:` section
+ * (or only `help` as a sub-command).
+ */
+function enumerateLeaves(prefix = []) {
+  const help = runHelp(prefix);
+  const cmds = parseCommands(help);
+  if (cmds.length === 0) {
+    // Leaf — return the prefix itself (or empty for root with no children).
+    return prefix.length === 0 ? [] : [prefix];
+  }
+  const leaves = [];
+  for (const cmd of cmds) {
+    leaves.push(...enumerateLeaves([...prefix, cmd.name]));
+  }
+  return leaves;
+}
+
+function renderReference() {
+  const header = `# CLI reference
+
+Generated from \`active-work --help\` and individual command \`--help\` outputs.
+Re-run \`node scripts/gen-cli-reference.mjs\` to refresh after the CLI
+surface changes.
+
+`;
+
+  const rootHelp = runHelp([]);
+  const sections = [
+    `## active-work\n\nTop-level help. Run \`active-work <command> --help\` for command-specific options.\n\n\`\`\`\n${rootHelp}\n\`\`\`\n`,
+  ];
+
+  const leaves = enumerateLeaves();
+  // Sort alphabetically by joined path.
+  leaves.sort((a, b) => a.join(' ').localeCompare(b.join(' ')));
+
+  for (const leaf of leaves) {
+    const path = leaf.join(' ');
+    const help = runHelp(leaf);
+    sections.push(`## active-work ${path}\n\n\`\`\`\n${help}\n\`\`\`\n`);
+  }
+
+  return header + sections.join('\n');
+}
+
+const out = renderReference();
+
+if (process.argv.includes('--stdout')) {
+  process.stdout.write(out);
+} else {
+  writeFileSync(OUT, out, 'utf8');
+  process.stderr.write(`wrote ${OUT}\n`);
+}

package/scripts/postinstall.js

@@ -0,0 +1,48 @@
+// Copy the bundled Claude Code skill into ~/.claude/skills/active-work/ and the
+// /aw-prompt slash command into ~/.claude/commands/ when ~/.claude exists. Skip
+// silently otherwise. Fail-soft: never abort an npm install if a copy fails.
+import { existsSync, mkdirSync, cpSync, copyFileSync, rmSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const skillSource = join(__dirname, '..', 'skill');
+const commandSource = join(__dirname, '..', 'claude-commands', 'aw-prompt.md');
+const claudeDir = join(homedir(), '.claude');
+const claudeSkillsDir = join(claudeDir, 'skills', 'active-work');
+const claudeCommandsDir = join(claudeDir, 'commands');
+
+if (!existsSync(claudeDir)) {
+  // User doesn't have Claude Code installed — skip silently.
+  process.exit(0);
+}
+
+// Skill and command installs are independent — a missing source for one must
+// not skip the other.
+if (existsSync(skillSource)) {
+  try {
+    // Remove existing install to ensure a clean copy.
+    if (existsSync(claudeSkillsDir)) {
+      rmSync(claudeSkillsDir, { recursive: true, force: true });
+    }
+    mkdirSync(claudeSkillsDir, { recursive: true });
+    cpSync(skillSource, claudeSkillsDir, { recursive: true });
+    console.log(`active-work: installed Claude Code skill to ${claudeSkillsDir}`);
+  } catch (err) {
+    // Don't fail npm install if skill copy fails.
+    console.error(`active-work: skill install skipped (${err.message})`);
+  }
+}
+
+try {
+  if (existsSync(commandSource)) {
+    mkdirSync(claudeCommandsDir, { recursive: true });
+    copyFileSync(commandSource, join(claudeCommandsDir, 'aw-prompt.md'));
+    console.log(`active-work: installed /aw-prompt command to ${claudeCommandsDir}`);
+  }
+} catch (err) {
+  // Don't fail npm install if the command copy fails.
+  console.error(`active-work: command install skipped (${err.message})`);
+}

package/scripts/preuninstall.js

@@ -0,0 +1,15 @@
+// Remove ~/.claude/skills/active-work/ on package removal. Fail-soft.
+import { existsSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+
+const claudeSkillsDir = join(homedir(), '.claude', 'skills', 'active-work');
+
+try {
+  if (existsSync(claudeSkillsDir)) {
+    rmSync(claudeSkillsDir, { recursive: true, force: true });
+    console.log(`active-work: removed Claude Code skill from ${claudeSkillsDir}`);
+  }
+} catch (err) {
+  console.error(`active-work: skill removal skipped (${err.message})`);
+}

package/skill/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: active-work
+description: |
+  Maintain durable per-initiative workspace state (brief, handoff, tasks, sessions, artifacts) so engineering work picks up cleanly across Claude Code sessions. Use when the user mentions: "active work", "what am I working on", "bootstrap session", "new initiative", "record this session", "update handoff", "archive initiative", "check active", "audit my workstreams", "find untracked work", "set up active-work", "add a task", "mark X done", "what's blocking me", "wrap up", "I'm done", or types /active-work.
+---
+
+# active-work — durable workspace state across Claude sessions
+
+`active-work` keeps a small filesystem-backed record for every engineering initiative the user has in flight. Files live under `$XDG_DATA_HOME/active-work/<slug>/` and include `brief.md` (frontmatter + prose), `handoff.md` (free prose), `tasks/*.yml`, `sessions/*.md`, `artifacts.yml`, and `sources/`. The CLI is `active-work`; `aw <slug>` is a thin launcher that bootstraps a Claude session for an initiative. A long-running daemon, `active-work mcp serve`, exposes MCP tools to Claude Code over HTTP and serves a read-only dashboard at `http://127.0.0.1:7400/ui`.
+
+## When to engage
+
+Engage whenever the user signals they want to inspect, mutate, or hand off persistent workspace state. Trigger phrases:
+
+- "active work" / "what am I working on" — list initiatives, surface current focus
+- "bootstrap session" / `/active-work` — load the bootstrap prompt for an initiative
+- "new initiative" — scaffold a slug with `active-work new`
+- "add a task" / "mark X done" / "what's blocking me" — task ops via `active-work task`
+- "record this session" / "update handoff" / "wrap up" / "I'm done" — session capture + handoff
+- "archive initiative" — move a slug to the archived state
+- "check active" / "audit my workstreams" — `active-work audit` health check
+- "find untracked work" — `active-work discover` across configured sources
+- "set up active-work" — first-time install / `active-work setup`
+
+## Core rules
+
+1. **Edits route through the CLI.** Use `active-work new`, `active-work set`, `active-work task add`, `active-work task done`, `active-work artifact add`, etc. Direct `Edit`/`Write` on `tasks/*.yml`, `artifacts.yml`, or the frontmatter of `brief.md` bypasses validation and corrupts the schema. Prose bodies (`brief.md` body, `handoff.md`, session summaries) can be edited directly, but prefer `active-work edit` for `brief.md` because it re-validates frontmatter on save.
+2. **LLM writes prose; CLI handles structure.** Task ordering, session filenames, frontmatter dates, slug normalization, and rank reflow are CLI primitives. Don't compute them yourself.
+3. **`active-work --help` is the canonical command reference.** This skill intentionally doesn't duplicate the surface; run `active-work --help` or `active-work <command> --help` when you need flags.
+4. **Session capture at end.** When wrapping up, run `active-work session record <slug>` with a 3-5 bullet summary of what happened, what changed, and what's next. Auto-prompt this when you detect the user winding down ("I'm done", "let's stop", "wrap up", inactivity after a chunk of work).
+5. **`active-work mcp status` first.** If MCP tools aren't responding, the daemon may not be running. Start it with `active-work mcp serve --detach` before retrying.
+
+## Bootstrap flow (`aw <slug>` / `active-work open <slug>`)
+
+`aw <slug>` is the operator-facing launcher: it assembles the bootstrap prompt and execs `claude` with the initiative's worktree as cwd. Omit the slug and it resolves the initiative from the caller's cwd (matching against each brief's registered worktrees), falling back to the interactive picker when nothing matches uniquely; `aw --pick` forces the picker. (Register a worktree so this resolution works with `active-work worktree set <slug> <path>`, or at creation via `new --worktree` / `track --worktree`.) `active-work open <slug>` is the same assembly logic, but prints the prompt to stdout instead of spawning Claude — use it from MCP / scripts / any caller that wants to handle the spawn itself (pass `--cwd <dir>` when the caller's process cwd isn't the user's shell cwd, e.g. the daemon). The bootstrap prompt inlines:
+
+- The full `handoff.md` text
+- A brief excerpt (frontmatter summary + first prose paragraph)
+- The most recent session summary
+- The top N open tasks (rank-sorted)
+- Open artifacts with status
+- Time since the last session
+
+To re-seed context **mid-session** (a session that wasn't started via `aw`, or one that has drifted), run `active-work prompt` — it prints the same bootstrap prompt to stdout, cwd-resolved and side-effect-free (no auto-archive). The bundled `/aw-prompt` slash command wraps it and injects the output straight into the session.
+
+Because handoff and brief excerpt are already in your context, **do not re-read `brief.md` or `handoff.md`** at the top of the session. Jump straight to the highest-rank open task unless the user redirects you. If the user opens a slug without further instruction, ask "continue with `<top task title>`?" and proceed on confirmation.
+
+**Ad-hoc sessions** (`aw <slug> --adhoc`, also `open`/`prompt --adhoc`): the opening and closing directives change to say the session is scoped to ad-hoc work on the workstream — the context is background, *not* a directive. Do **not** offer to continue the top task; wait for the user to describe the specific ad-hoc task, then work it with the workstream context in mind. The bootstrap prompt itself carries this instruction, so follow whichever framing it renders.
+
+## Reference docs
+
+- [onboarding.md](references/onboarding.md) — first-time setup walkthrough
+- [auditing-existing-work.md](references/auditing-existing-work.md) — discover + triage flow for catching up on untracked work
+- [cli-dev.md](references/cli-dev.md) — internal architecture for skill maintainers and CLI contributors

package/skill/references/auditing-existing-work.md

@@ -0,0 +1,125 @@
+# Auditing existing work — discover + triage
+
+If the user has a pile of in-flight work but nothing tracked in `active-work` (or only partially tracked), this walkthrough drives them through discovery and triage in three categories: **Track**, **Fold**, **Drop**.
+
+## When to use
+
+- "I have a bunch of stuff in flight and I want to get it all into active-work"
+- "audit my workstreams"
+- "find untracked work"
+- "what am I forgetting"
+- After a long break — sync state with reality before continuing
+
+## 1. Discover
+
+`active-work discover` walks the configured discovery sources and returns candidate references (PRs, branches, local repos, recent Claude sessions, project directories). Sources are configured in the user's `$XDG_CONFIG_HOME/active-work/config.json` under `discovery`:
+
+```json
+{
+  "discovery": {
+    "githubRepos": ["hjewkes/active-work", "hjewkes/brain"],
+    "localRepos": ["~/Documents/projects/active-work", "~/Documents/projects/brain"],
+    "projectsRoot": "~/Documents/projects"
+  }
+}
+```
+
+Run:
+
+```bash
+active-work discover
+```
+
+Output lists each hit with a stable `ref` (e.g. `gh:hjewkes/active-work#42`, `git:active-work@feat/dashboard`, `dir:/Users/h/projects/foo`, `claude:session/abc123`), a short title, and a guess at the freshest activity date.
+
+## 2. Triage each hit
+
+For every reference, decide one of three actions:
+
+### Track — it's a real initiative
+
+If the work is meaningful and ongoing, give it a slug and a title:
+
+```bash
+active-work track gh:hjewkes/active-work#42 \
+  --slug dashboard-perf \
+  --title "Dashboard load is sluggish on cold open"
+```
+
+`active-work track` scaffolds the initiative (`brief.md` with frontmatter, empty `handoff.md`, empty `tasks/`, an `artifacts.yml` seeded with the source ref), then prints the new slug. Open it next:
+
+```bash
+active-work open dashboard-perf
+```
+
+### Fold — it belongs under something you already track
+
+If the ref is part of an initiative you already have (e.g. one of three PRs against the same effort), fold it in as an artifact:
+
+```bash
+active-work fold gh:hjewkes/active-work#43 \
+  --into dashboard-perf \
+  --note "follow-up PR for the WS reconnection fix"
+```
+
+This appends to `artifacts.yml` and writes a row in `sources/discovery.yml` so the same ref won't reappear on the next `active-work discover`.
+
+### Drop — not real / not yours / abandoned
+
+Mark it dismissed so future `active-work discover` runs ignore it:
+
+```bash
+active-work drop gh:upstream/repo#99 --reason "upstream issue, not actionable"
+```
+
+The ref is recorded in `sources/discovery.yml` with `dismissed: true` and the reason. You can resurrect it with `active-work track <ref>` later if you change your mind.
+
+## 3. Verify state
+
+After triage, run the audit to catch issues:
+
+```bash
+active-work audit
+```
+
+Audit checks:
+
+- Every active slug has a non-empty `handoff.md`
+- Every active slug has at least one open task (otherwise: should it be archived?)
+- `artifacts.yml` references resolve (PRs exist, branches exist locally, etc.)
+- Last session timestamp isn't stale beyond the configured threshold
+- No frontmatter validation errors
+
+Warnings are non-fatal. Fix them iteratively with `active-work set <slug> ...`, `active-work task add`, or `active-work archive`.
+
+## Worked example
+
+```text
+$ active-work discover
+gh:hjewkes/active-work#42       Dashboard cold-load perf            2d ago
+gh:hjewkes/active-work#43       Fix WS reconnect after sleep        2d ago
+git:brain@feat/inbox-rewrite    feat/inbox-rewrite (4 commits)      5d ago
+dir:~/projects/scratch-jq       scratch-jq                          11d ago
+claude:session/0192abc          "look at this gnarly stack trace"   23d ago
+
+$ active-work track gh:hjewkes/active-work#42 --slug dashboard-perf --title "Dashboard cold-load perf"
+created: dashboard-perf
+
+$ active-work fold gh:hjewkes/active-work#43 --into dashboard-perf --note "WS reconnect follow-up"
+folded into dashboard-perf
+
+$ active-work track git:brain@feat/inbox-rewrite --slug brain-inbox-rewrite --title "Brain inbox rewrite"
+created: brain-inbox-rewrite
+
+$ active-work drop dir:~/projects/scratch-jq --reason "scratch repo, not real work"
+dropped
+
+$ active-work drop claude:session/0192abc --reason "one-off debugging, no follow-up"
+dropped
+
+$ active-work audit
+brain-inbox-rewrite: handoff.md is empty — add a one-paragraph status
+ok: 1 warning across 2 initiatives
+```
+
+The user is now caught up. Continue with `active-work open dashboard-perf` (or whichever slug they want to push on first).

package/skill/references/cli-dev.md

@@ -0,0 +1,63 @@
+# CLI dev — internal architecture for skill maintainers
+
+If you are modifying the `active-work` skill, adding a CLI command, extending the daemon, or wiring a new MCP tool, this is the orientation doc. The CLI source lives in `hjewkes/active-work`.
+
+## Directory map
+
+| Path | What's here |
+|---|---|
+| `src/cli.ts` | Entrypoint. Wires commander to the command registry. |
+| `src/registry/` | Command registry types, JSON envelope, dispatcher contract. The single source of truth for both CLI and MCP. |
+| `src/commands/` | One file per CLI command; each exports a `defineCommand({...})` entry. |
+| `src/commands/index.ts` | The aggregate export — register a new command here. |
+| `src/schemas/` | Zod schemas for `brief.md` frontmatter, tasks, sessions, artifacts, state. Every write goes through a validator. |
+| `src/utils/` | `fs-atomic` (atomic writes + flock), `paths`, `slug`, `gray-matter-io`, `yaml-io`, `today`, `color`. |
+| `src/server/` | hono HTTP + WS + MCP-over-HTTP daemon. |
+| `src/dashboard/` | React (react-native-web) read-only dashboard; built via vite. |
+| `src/migrations/` | Schema migrations keyed by `from` version. |
+| `src/lint/` | Per-artifact lint rules (warn-only). |
+| `src/templates/` | Mustache templates for scaffolding new initiatives. |
+| `src/bootstrap/` | Bootstrap prompt assembly used by `active-work open`. |
+| `src/discover/` | Discovery sources (gh, git, projects, Claude sessions). |
+| `skill/` | This skill. Copied into `~/.claude/skills/active-work/` by `scripts/postinstall.js`. |
+| `scripts/` | npm lifecycle hooks: `postinstall.js`, `preuninstall.js`. |
+| `__tests__/` | Vitest tests; fixtures under `__tests__/fixtures/`. |
+
+## Adding a new command
+
+1. Create `src/commands/<name>.ts` exporting a `defineCommand({...})` entry. Define:
+   - `name` (e.g. `"task add"`)
+   - `description`
+   - `input` zod schema
+   - `output` zod schema
+   - `handler(input, ctx)` returning the validated output
+2. Add the import + registration in `src/commands/index.ts`.
+3. The CLI dispatcher and MCP server both pick it up automatically — do not hand-maintain MCP tool definitions.
+4. Add a test under `__tests__/commands/<name>.test.ts`. Use `withTempActiveRoot` / `withEmptyActiveRoot` helpers from `__tests__/setup/test-helpers.ts` for filesystem isolation.
+
+## Schema + write discipline
+
+- Every write to `brief.md` frontmatter, `tasks/*.yml`, `sessions/*.md` (frontmatter), or `artifacts.yml` must go through a validator in `src/schemas/`.
+- Read-modify-write must use `withFileLock` from `src/utils/fs-atomic.ts` to take a per-initiative POSIX flock.
+- Paths are computed via `env-paths` through `src/utils/paths.ts`. Never hardcode `~/.local/share/...`.
+
+## Daemon
+
+`src/server/` runs hono on `127.0.0.1:7400` by default (override with `AW_PORT`). It serves:
+
+- `/rpc/<command>` — REST for every registry entry
+- `/ws` — WebSocket live feed (chokidar-backed filesystem events)
+- `/mcp` — MCP-over-HTTP transport
+- `/ui` — bundled dashboard SPA
+
+The same daemon process can also speak MCP-over-stdio when invoked as `active-work mcp serve --stdio`.
+
+## Skill content
+
+This skill is just three files: `SKILL.md` and three references. Keep `SKILL.md` skim-able (target ~150 lines, hard cap ~200). Push depth into references and link from `SKILL.md`. The frontmatter `description` is what Claude Code uses to decide whether to load the skill, so keep trigger phrases there fresh and aligned with the CLI command surface.
+
+When you add a trigger phrase to `SKILL.md`, ask: is there an existing CLI command that handles it? If not, add the command first, then the trigger.
+
+## Release flow
+
+Changes to skill content ship in the next `@titan-design/active-work` release. The `postinstall.js` hook reinstalls the skill on every update; users do not need to do anything beyond `npm install -g @titan-design/active-work@latest` (or the pnpm equivalent).

package/skill/references/onboarding.md

@@ -0,0 +1,72 @@
+# Onboarding — first-time `active-work` setup
+
+This walkthrough takes a brand-new machine to a working `active-work` install with the Claude Code skill available.
+
+## 1. Verify prerequisites
+
+`active-work` requires Node 22 or newer. `pnpm` is recommended for global installs because it manages multiple Node versions cleanly, but `npm` works too.
+
+```bash
+node --version   # expect v22.x or newer
+pnpm --version   # any recent version, e.g. 9.x or 10.x
+```
+
+If Node is older than 22, install a current LTS via `nvm`, `fnm`, or `volta` before continuing.
+
+## 2. Install the package globally
+
+```bash
+npm install -g @titan-design/active-work
+# or
+pnpm add -g @titan-design/active-work
+```
+
+The package ships the CLI binary (`active-work`), a thin Claude-session launcher (`aw <slug>`), the MCP server, the dashboard bundle, and the Claude skill content.
+
+## 3. Postinstall hook copies the skill
+
+On install, `scripts/postinstall.js` runs automatically. It looks for `~/.claude/` and, if present, copies the bundled `skill/` directory into `~/.claude/skills/active-work/`. If `~/.claude/` does not exist (Claude Code not installed), the hook exits silently so the npm install never fails.
+
+You can verify the skill landed:
+
+```bash
+ls ~/.claude/skills/active-work/
+# expect: SKILL.md  references/
+```
+
+## 4. Run `active-work setup`
+
+`active-work setup` (Wave 6) is the interactive wizard that initializes data roots, registers the MCP server with Claude Code, and offers to install the daemon launchd plist. **It is not yet implemented.** Until it lands, you can prepare the data root manually:
+
+```bash
+mkdir -p "${XDG_DATA_HOME:-$HOME/Library/Application Support}/active-work"
+```
+
+(On Linux this resolves to `~/.local/share/active-work/`; on macOS to `~/Library/Application Support/active-work/`.)
+
+Register the MCP server with Claude Code manually for now:
+
+```bash
+claude mcp add --user @hjewkes/active-work -- active-work mcp serve --stdio
+```
+
+## 5. Verify the install
+
+```bash
+active-work --help          # prints the command surface
+active-work mcp status      # reports daemon state
+```
+
+`active-work mcp status` will report "not running" until you start the daemon (next step).
+
+## 6. Optional — start the daemon
+
+The daemon hosts MCP-over-HTTP, the REST API, the WebSocket live feed, and the dashboard.
+
+```bash
+active-work mcp serve --detach
+```
+
+Then visit `http://127.0.0.1:7400/ui` to see the dashboard. Stop it with `active-work mcp stop`.
+
+You're done. Open Claude Code in any directory and ask "what am I working on?" — the `active-work` skill should engage and surface your initiatives.