@jaggerxtrm/specialists 3.0.1 → 3.2.0

package/dist/index.js

@@ -18281,6 +18281,10 @@ function parseArgs(argv) {
       result.scope = value;
       continue;
     }
+    if (token === "--json") {
+      result.json = true;
+      continue;
+    }
   }
   return result;
 }
@@ -18300,6 +18304,10 @@ async function run3() {
   if (args.scope) {
     specialists = specialists.filter((s) => s.scope === args.scope);
   }
+  if (args.json) {
+    console.log(JSON.stringify(specialists, null, 2));
+    return;
+  }
   if (specialists.length === 0) {
     console.log("No specialists found.");
     return;
@@ -19038,23 +19046,86 @@ function statusColor(status) {
   }
 }
 async function run8() {
+  const argv = process.argv.slice(3);
+  const jsonMode = argv.includes("--json");
+  const loader = new SpecialistLoader;
+  const allSpecialists = await loader.list();
+  const piInstalled = isInstalled("pi");
+  const piVersion = piInstalled ? cmd("pi", ["--version"]) : null;
+  const piModels = piInstalled ? cmd("pi", ["--list-models"]) : null;
+  const piProviders = piModels ? new Set(piModels.stdout.split(`
+`).slice(1).map((line) => line.split(/\s+/)[0]).filter(Boolean)) : new Set;
+  const bdInstalled = isInstalled("bd");
+  const bdVersion = bdInstalled ? cmd("bd", ["--version"]) : null;
+  const beadsPresent = existsSync5(join8(process.cwd(), ".beads"));
+  const specialistsBin = cmd("which", ["specialists"]);
+  const jobsDir = join8(process.cwd(), ".specialists", "jobs");
+  let jobs = [];
+  if (existsSync5(jobsDir)) {
+    const supervisor = new Supervisor({
+      runner: null,
+      runOptions: null,
+      jobsDir
+    });
+    jobs = supervisor.listJobs();
+  }
+  const stalenessMap = {};
+  for (const s of allSpecialists) {
+    stalenessMap[s.name] = await checkStaleness(s);
+  }
+  if (jsonMode) {
+    const output = {
+      specialists: {
+        count: allSpecialists.length,
+        items: allSpecialists.map((s) => ({
+          name: s.name,
+          scope: s.scope,
+          model: s.model,
+          description: s.description,
+          staleness: stalenessMap[s.name]
+        }))
+      },
+      pi: {
+        installed: piInstalled,
+        version: piVersion?.stdout ?? null,
+        providers: [...piProviders]
+      },
+      beads: {
+        installed: bdInstalled,
+        version: bdVersion?.stdout ?? null,
+        initialized: beadsPresent
+      },
+      mcp: {
+        specialists_installed: specialistsBin.ok,
+        binary_path: specialistsBin.ok ? specialistsBin.stdout : null
+      },
+      jobs: jobs.map((j) => ({
+        id: j.id,
+        specialist: j.specialist,
+        status: j.status,
+        elapsed_s: j.elapsed_s,
+        current_tool: j.current_tool ?? null,
+        error: j.error ?? null
+      }))
+    };
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
   console.log(`
 ${bold6("specialists status")}
 `);
   section("Specialists");
-  const loader = new SpecialistLoader;
-  const all = await loader.list();
-  if (all.length === 0) {
+  if (allSpecialists.length === 0) {
     warn(`no specialists found — run ${yellow5("specialists init")} to scaffold`);
   } else {
-    const byScope = all.reduce((acc, s) => {
+    const byScope = allSpecialists.reduce((acc, s) => {
       acc[s.scope] = (acc[s.scope] ?? 0) + 1;
       return acc;
     }, {});
     const scopeSummary = Object.entries(byScope).map(([scope, n]) => `${n} ${scope}`).join(", ");
-    ok2(`${all.length} found  ${dim6(`(${scopeSummary})`)}`);
-    for (const s of all) {
-      const staleness = await checkStaleness(s);
+    ok2(`${allSpecialists.length} found  ${dim6(`(${scopeSummary})`)}`);
+    for (const s of allSpecialists) {
+      const staleness = stalenessMap[s.name];
       if (staleness === "AGED") {
         warn(`${s.name}  ${red("AGED")}  ${dim6(s.scope)}`);
       } else if (staleness === "STALE") {
@@ -19063,31 +19134,25 @@ ${bold6("specialists status")}
     }
   }
   section("pi  (coding agent runtime)");
-  if (!isInstalled("pi")) {
+  if (!piInstalled) {
     fail(`pi not installed — run ${yellow5("specialists install")}`);
   } else {
-    const version2 = cmd("pi", ["--version"]);
-    const models = cmd("pi", ["--list-models"]);
-    const providers = new Set(models.stdout.split(`
-`).slice(1).map((line) => line.split(/\s+/)[0]).filter(Boolean));
-    const vStr = version2.ok ? `v${version2.stdout}` : "unknown version";
-    const pStr = providers.size > 0 ? `${providers.size} provider${providers.size > 1 ? "s" : ""} active  ${dim6(`(${[...providers].join(", ")})`)} ` : yellow5("no providers configured — run pi config");
+    const vStr = piVersion?.ok ? `v${piVersion.stdout}` : "unknown version";
+    const pStr = piProviders.size > 0 ? `${piProviders.size} provider${piProviders.size > 1 ? "s" : ""} active  ${dim6(`(${[...piProviders].join(", ")})`)} ` : yellow5("no providers configured — run pi config");
     ok2(`${vStr}  —  ${pStr}`);
   }
   section("beads  (issue tracker)");
-  if (!isInstalled("bd")) {
+  if (!bdInstalled) {
     fail(`bd not installed — run ${yellow5("specialists install")}`);
   } else {
-    const bdVersion = cmd("bd", ["--version"]);
-    ok2(`bd installed${bdVersion.ok ? `  ${dim6(bdVersion.stdout)}` : ""}`);
-    if (existsSync5(join8(process.cwd(), ".beads"))) {
+    ok2(`bd installed${bdVersion?.ok ? `  ${dim6(bdVersion.stdout)}` : ""}`);
+    if (beadsPresent) {
       ok2(".beads/ present in project");
     } else {
       warn(`.beads/ not found — run ${yellow5("bd init")} to enable issue tracking`);
     }
   }
   section("MCP");
-  const specialistsBin = cmd("which", ["specialists"]);
   if (!specialistsBin.ok) {
     fail(`specialists not installed globally — run ${yellow5("npm install -g @jaggerxtrm/specialists")}`);
   } else {
@@ -19095,21 +19160,12 @@ ${bold6("specialists status")}
     info(`verify registration: claude mcp get specialists`);
     info(`re-register:         specialists install`);
   }
-  const jobsDir = join8(process.cwd(), ".specialists", "jobs");
-  if (existsSync5(jobsDir)) {
-    const supervisor = new Supervisor({
-      runner: null,
-      runOptions: null,
-      jobsDir
-    });
-    const jobs = supervisor.listJobs();
-    if (jobs.length > 0) {
-      section("Active Jobs");
-      for (const job of jobs) {
-        const elapsed = formatElapsed(job);
-        const detail = job.status === "error" ? red(job.error?.slice(0, 40) ?? "error") : job.current_tool ? dim6(`tool: ${job.current_tool}`) : dim6(job.current_event ?? "");
-        console.log(`  ${dim6(job.id)}  ${job.specialist.padEnd(20)}  ${statusColor(job.status).padEnd(7)}  ${elapsed.padStart(6)}  ${detail}`);
-      }
+  if (jobs.length > 0) {
+    section("Active Jobs");
+    for (const job of jobs) {
+      const elapsed = formatElapsed(job);
+      const detail = job.status === "error" ? red(job.error?.slice(0, 40) ?? "error") : job.current_tool ? dim6(`tool: ${job.current_tool}`) : dim6(job.current_event ?? "");
+      console.log(`  ${dim6(job.id)}  ${job.specialist.padEnd(20)}  ${statusColor(job.status).padEnd(7)}  ${elapsed.padStart(6)}  ${detail}`);
     }
   }
   console.log();
@@ -19298,42 +19354,654 @@ var init_stop = __esm(() => {
   init_supervisor();
 });
 
+// src/cli/quickstart.ts
+var exports_quickstart = {};
+__export(exports_quickstart, {
+  run: () => run12
+});
+function section2(title) {
+  const bar = "─".repeat(60);
+  return `
+${bold7(cyan6(title))}
+${dim10(bar)}`;
+}
+function cmd2(s) {
+  return yellow7(s);
+}
+function flag(s) {
+  return green7(s);
+}
+async function run12() {
+  const lines = [
+    "",
+    bold7("specialists  ·  Quick Start Guide"),
+    dim10("One MCP server. Multiple AI backends. Intelligent orchestration."),
+    ""
+  ];
+  lines.push(section2("1. Installation"));
+  lines.push("");
+  lines.push(`  ${cmd2("npm install -g @jaggerxtrm/specialists")}    # install globally`);
+  lines.push(`  ${cmd2("specialists install")}                       # full-stack setup:`);
+  lines.push(`  ${dim10("                                            #   pi · beads · dolt · MCP · hooks")}`);
+  lines.push("");
+  lines.push(`  Verify everything is healthy:`);
+  lines.push(`  ${cmd2("specialists status")}                        # shows pi, beads, MCP, active jobs`);
+  lines.push("");
+  lines.push(section2("2. Initialize a Project"));
+  lines.push("");
+  lines.push(`  Run once per project root:`);
+  lines.push(`  ${cmd2("specialists init")}                          # creates specialists/, .specialists/, AGENTS.md`);
+  lines.push("");
+  lines.push(`  What this creates:`);
+  lines.push(`  ${dim10("specialists/")}       — put your .specialist.yaml files here`);
+  lines.push(`  ${dim10(".specialists/")}      — runtime data (jobs/, ready/) — gitignored`);
+  lines.push(`  ${dim10("AGENTS.md")}          — context block injected into Claude sessions`);
+  lines.push("");
+  lines.push(section2("3. Discover Specialists"));
+  lines.push("");
+  lines.push(`  ${cmd2("specialists list")}                          # all specialists (project + user)`);
+  lines.push(`  ${cmd2("specialists list")} ${flag("--scope project")}            # project-scoped only`);
+  lines.push(`  ${cmd2("specialists list")} ${flag("--scope user")}               # user-scoped (~/.specialists/)`);
+  lines.push(`  ${cmd2("specialists list")} ${flag("--category analysis")}        # filter by category`);
+  lines.push(`  ${cmd2("specialists list")} ${flag("--json")}                     # machine-readable JSON`);
+  lines.push("");
+  lines.push(`  Scopes (searched in order):`);
+  lines.push(`  ${blue("project")}   ./specialists/*.specialist.yaml`);
+  lines.push(`  ${blue("user")}      ~/.specialists/*.specialist.yaml`);
+  lines.push(`  ${blue("system")}    bundled specialists (shipped with the package)`);
+  lines.push("");
+  lines.push(section2("4. Running a Specialist"));
+  lines.push("");
+  lines.push(`  ${bold7("Foreground")} (streams output to stdout):`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--prompt")} ${dim10('"Review src/api.ts for security issues"')}`);
+  lines.push("");
+  lines.push(`  ${bold7("Background")} (returns a job ID immediately):`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--prompt")} ${dim10('"..."')} ${flag("--background")}`);
+  lines.push(`  ${dim10("  # → Job started: job_a1b2c3d4")}`);
+  lines.push("");
+  lines.push(`  Override model for one run:`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--model")} ${dim10("anthropic/claude-opus-4-6")} ${flag("--prompt")} ${dim10('"..."')}`);
+  lines.push("");
+  lines.push(`  Run without beads issue tracking:`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--no-beads")} ${flag("--prompt")} ${dim10('"..."')}`);
+  lines.push("");
+  lines.push(`  Pipe a prompt from stdin:`);
+  lines.push(`  ${cmd2("cat my-brief.md | specialists run code-review")}`);
+  lines.push("");
+  lines.push(section2("5. Background Job Lifecycle"));
+  lines.push("");
+  lines.push(`  ${bold7("Watch progress")} — stream events as they arrive:`);
+  lines.push(`  ${cmd2("specialists feed job_a1b2c3d4")}            # print events so far`);
+  lines.push(`  ${cmd2("specialists feed job_a1b2c3d4")} ${flag("--follow")}      # tail and stream live updates`);
+  lines.push("");
+  lines.push(`  ${bold7("Read results")} — print the final output:`);
+  lines.push(`  ${cmd2("specialists result job_a1b2c3d4")}          # exits 1 if still running`);
+  lines.push("");
+  lines.push(`  ${bold7("Cancel a job")}:`);
+  lines.push(`  ${cmd2("specialists stop job_a1b2c3d4")}            # sends SIGTERM to the agent process`);
+  lines.push("");
+  lines.push(`  ${bold7("Job files")} in ${dim10(".specialists/jobs/<job-id>/")}:`);
+  lines.push(`  ${dim10("status.json")}   — id, specialist, status, pid, started_at, elapsed_s, current_tool`);
+  lines.push(`  ${dim10("events.jsonl")} — one JSON event per line (tool_use, text, agent_end, error …)`);
+  lines.push(`  ${dim10("result.txt")}    — final output (written when status=done)`);
+  lines.push("");
+  lines.push(section2("6. Editing Specialists"));
+  lines.push("");
+  lines.push(`  Change a field without opening the YAML manually:`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--model")} ${dim10("anthropic/claude-sonnet-4-6")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--description")} ${dim10('"Updated description"')}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--timeout")} ${dim10("120000")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--permission")} ${dim10("HIGH")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--tags")} ${dim10("analysis,security,review")}`);
+  lines.push("");
+  lines.push(`  Preview without writing:`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--model")} ${dim10("...")} ${flag("--dry-run")}`);
+  lines.push("");
+  lines.push(section2("7. .specialist.yaml Schema"));
+  lines.push("");
+  lines.push(`  Full annotated example:`);
+  lines.push("");
+  const schemaLines = [
+    "specialist:",
+    "  metadata:",
+    '    name: my-specialist          # required · used in "specialists run <name>"',
+    "    version: 1.0.0               # semver, for staleness detection",
+    '    description: "What it does"  # shown in specialists list',
+    "    category: analysis           # free-form tag for --category filter",
+    "    tags: [review, security]     # array of labels",
+    '    updated: "2026-03-11"        # ISO date — used for staleness check',
+    "",
+    "  execution:",
+    "    mode: tool                   # tool (default) | chat",
+    "    model: anthropic/claude-sonnet-4-6   # primary model",
+    "    fallback_model: qwen-cli/qwen3-coder  # if primary circuit-breaks",
+    "    timeout_ms: 120000           # ms before job is killed (default: 120000)",
+    "    stall_timeout_ms: 30000      # ms of silence before stall-detection fires",
+    "    response_format: markdown    # markdown | json | text",
+    "    permission_required: MEDIUM  # READ_ONLY | LOW | MEDIUM | HIGH",
+    "",
+    "  prompt:",
+    "    system: |                    # system prompt (multiline YAML literal block)",
+    "      You are …",
+    "    user_template: |             # optional; $prompt and $context are substituted",
+    "      Task: $prompt",
+    "      Context: $context",
+    "",
+    "  skills:",
+    "    paths:                       # extra skill dirs searched at runtime",
+    "      - ./specialists/skills",
+    "      - ~/.specialists/skills",
+    "",
+    "  capabilities:",
+    "    web_search: false            # allow web search tool",
+    "    file_write: true             # allow file writes",
+    "",
+    "  beads_integration:",
+    "    auto_create: true            # create a beads issue per run",
+    "    issue_type: task             # task | bug | feature",
+    "    priority: 2                  # 0=critical … 4=backlog"
+  ];
+  for (const l of schemaLines) {
+    lines.push(`  ${dim10(l)}`);
+  }
+  lines.push("");
+  lines.push(section2("8. Hook System"));
+  lines.push("");
+  lines.push(`  Specialists emits lifecycle events to ${dim10(".specialists/trace.jsonl")}:`);
+  lines.push("");
+  lines.push(`  ${bold7("Hook point")}              ${bold7("When fired")}`);
+  lines.push(`  ${yellow7("specialist:start")}       before the agent session begins`);
+  lines.push(`  ${yellow7("specialist:token")}       on each streamed token (delta)`);
+  lines.push(`  ${yellow7("specialist:done")}        after successful completion`);
+  lines.push(`  ${yellow7("specialist:error")}       on failure or timeout`);
+  lines.push("");
+  lines.push(`  Each event line in trace.jsonl:`);
+  lines.push(`  ${dim10('{"t":"<ISO>","hook":"specialist:done","specialist":"code-review","durationMs":4120}')}`);
+  lines.push("");
+  lines.push(`  Tail the trace file to observe all activity:`);
+  lines.push(`  ${cmd2("tail -f .specialists/trace.jsonl | jq .")}`);
+  lines.push("");
+  lines.push(section2("9. MCP Integration (Claude Code)"));
+  lines.push("");
+  lines.push(`  After ${cmd2("specialists install")}, these MCP tools are available to Claude:`);
+  lines.push("");
+  lines.push(`  ${bold7("specialist_init")}    — bootstrap: bd init + list specialists`);
+  lines.push(`  ${bold7("list_specialists")}   — discover specialists (project/user/system)`);
+  lines.push(`  ${bold7("use_specialist")}     — full lifecycle: load → agents.md → run → output`);
+  lines.push(`  ${bold7("run_parallel")}       — concurrent or pipeline execution`);
+  lines.push(`  ${bold7("start_specialist")}   — async job start, returns job ID`);
+  lines.push(`  ${bold7("poll_specialist")}    — poll job status/output by ID`);
+  lines.push(`  ${bold7("stop_specialist")}    — cancel a running job by ID`);
+  lines.push(`  ${bold7("specialist_status")}  — circuit breaker health + staleness`);
+  lines.push("");
+  lines.push(section2("10. Common Workflows"));
+  lines.push("");
+  lines.push(`  ${bold7("Foreground review, save to file:")}`);
+  lines.push(`  ${cmd2('specialists run code-review --prompt "Audit src/" > review.md')}`);
+  lines.push("");
+  lines.push(`  ${bold7("Fire-and-forget, check later:")}`);
+  lines.push(`  ${cmd2('specialists run deep-analysis --prompt "..." --background')}`);
+  lines.push(`  ${cmd2("specialists feed <job-id> --follow")}`);
+  lines.push(`  ${cmd2("specialists result <job-id> > analysis.md")}`);
+  lines.push("");
+  lines.push(`  ${bold7("Override model for a single run:")}`);
+  lines.push(`  ${cmd2('specialists run code-review --model anthropic/claude-opus-4-6 --prompt "..."')}`);
+  lines.push("");
+  lines.push(dim10("─".repeat(62)));
+  lines.push(`  ${dim10("specialists help")}     command list         ${dim10("specialists <cmd> --help")}   per-command flags`);
+  lines.push(`  ${dim10("specialists status")}   health check         ${dim10("specialists models")}         available models`);
+  lines.push("");
+  console.log(lines.join(`
+`));
+}
+var bold7 = (s) => `\x1B[1m${s}\x1B[0m`, dim10 = (s) => `\x1B[2m${s}\x1B[0m`, yellow7 = (s) => `\x1B[33m${s}\x1B[0m`, cyan6 = (s) => `\x1B[36m${s}\x1B[0m`, blue = (s) => `\x1B[34m${s}\x1B[0m`, green7 = (s) => `\x1B[32m${s}\x1B[0m`;
+
+// src/cli/doctor.ts
+var exports_doctor = {};
+__export(exports_doctor, {
+  run: () => run13
+});
+import { spawnSync as spawnSync5 } from "node:child_process";
+import { existsSync as existsSync8, mkdirSync as mkdirSync3, readFileSync as readFileSync6, readdirSync as readdirSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join12 } from "node:path";
+function ok3(msg) {
+  console.log(`  ${green8("✓")} ${msg}`);
+}
+function warn2(msg) {
+  console.log(`  ${yellow8("○")} ${msg}`);
+}
+function fail2(msg) {
+  console.log(`  ${red5("✗")} ${msg}`);
+}
+function fix(msg) {
+  console.log(`    ${dim11("→ fix:")} ${yellow8(msg)}`);
+}
+function hint(msg) {
+  console.log(`    ${dim11(msg)}`);
+}
+function section3(label) {
+  const line = "─".repeat(Math.max(0, 38 - label.length));
+  console.log(`
+${bold8(`── ${label} ${line}`)}`);
+}
+function sp(bin, args) {
+  const r = spawnSync5(bin, args, { encoding: "utf8", stdio: "pipe", timeout: 5000 });
+  return { ok: r.status === 0 && !r.error, stdout: (r.stdout ?? "").trim() };
+}
+function isInstalled2(bin) {
+  return spawnSync5("which", [bin], { encoding: "utf8", timeout: 2000 }).status === 0;
+}
+function checkPi() {
+  section3("pi  (coding agent runtime)");
+  if (!isInstalled2("pi")) {
+    fail2("pi not installed");
+    fix("specialists install");
+    return false;
+  }
+  const version2 = sp("pi", ["--version"]);
+  const models = sp("pi", ["--list-models"]);
+  const providers = models.ok ? new Set(models.stdout.split(`
+`).slice(1).map((line) => line.split(/\s+/)[0]).filter(Boolean)) : new Set;
+  const vStr = version2.ok ? `v${version2.stdout}` : "unknown version";
+  if (providers.size === 0) {
+    warn2(`pi ${vStr} installed but no active providers`);
+    fix("pi config   (add at least one API key)");
+    return false;
+  }
+  ok3(`pi ${vStr}  —  ${providers.size} provider${providers.size > 1 ? "s" : ""} active  ${dim11(`(${[...providers].join(", ")})`)} `);
+  return true;
+}
+function checkHooks() {
+  section3("Claude Code hooks  (7 expected)");
+  let allPresent = true;
+  for (const name of HOOK_NAMES) {
+    const dest = join12(HOOKS_DIR, name);
+    if (!existsSync8(dest)) {
+      fail2(`${name}  ${red5("missing")}`);
+      fix("specialists install   (reinstalls all hooks)");
+      allPresent = false;
+    } else {
+      ok3(name);
+    }
+  }
+  if (allPresent && existsSync8(SETTINGS_FILE)) {
+    try {
+      const settings = JSON.parse(readFileSync6(SETTINGS_FILE, "utf8"));
+      const hooks = settings.hooks ?? {};
+      const allEntries = [
+        ...hooks.PreToolUse ?? [],
+        ...hooks.PostToolUse ?? [],
+        ...hooks.Stop ?? [],
+        ...hooks.UserPromptSubmit ?? [],
+        ...hooks.SessionStart ?? []
+      ];
+      const wiredCommands = new Set(allEntries.flatMap((e) => (e.hooks ?? []).map((h) => h.command ?? "")));
+      const guardWired = [...wiredCommands].some((c) => c.includes("specialists-main-guard"));
+      if (!guardWired) {
+        warn2("specialists-main-guard not wired in settings.json");
+        fix("specialists install   (rewires hooks in settings.json)");
+        allPresent = false;
+      } else {
+        hint(`Hooks wired in ${SETTINGS_FILE}`);
+      }
+    } catch {
+      warn2(`Could not parse ${SETTINGS_FILE}`);
+      allPresent = false;
+    }
+  }
+  return allPresent;
+}
+function checkMCP() {
+  section3("MCP registration");
+  const check2 = sp("claude", ["mcp", "get", MCP_NAME]);
+  if (!check2.ok) {
+    fail2(`MCP server '${MCP_NAME}' not registered`);
+    fix(`specialists install   (or: claude mcp add --scope user ${MCP_NAME} -- specialists)`);
+    return false;
+  }
+  ok3(`MCP server '${MCP_NAME}' registered`);
+  return true;
+}
+function checkRuntimeDirs() {
+  section3(".specialists/ runtime directories");
+  const cwd = process.cwd();
+  const rootDir = join12(cwd, ".specialists");
+  const jobsDir = join12(rootDir, "jobs");
+  const readyDir = join12(rootDir, "ready");
+  let allOk = true;
+  if (!existsSync8(rootDir)) {
+    warn2(".specialists/ not found in current project");
+    fix("specialists init");
+    allOk = false;
+  } else {
+    ok3(".specialists/ present");
+    for (const [subDir, label] of [[jobsDir, "jobs"], [readyDir, "ready"]]) {
+      if (!existsSync8(subDir)) {
+        warn2(`.specialists/${label}/ missing — auto-creating`);
+        mkdirSync3(subDir, { recursive: true });
+        ok3(`.specialists/${label}/ created`);
+      } else {
+        ok3(`.specialists/${label}/ present`);
+      }
+    }
+  }
+  return allOk;
+}
+function checkZombieJobs() {
+  section3("Background jobs");
+  const jobsDir = join12(process.cwd(), ".specialists", "jobs");
+  if (!existsSync8(jobsDir)) {
+    hint("No .specialists/jobs/ — skipping");
+    return true;
+  }
+  let entries;
+  try {
+    entries = readdirSync2(jobsDir);
+  } catch {
+    entries = [];
+  }
+  if (entries.length === 0) {
+    ok3("No jobs found");
+    return true;
+  }
+  let zombies = 0;
+  let total = 0;
+  let running = 0;
+  for (const jobId of entries) {
+    const statusPath = join12(jobsDir, jobId, "status.json");
+    if (!existsSync8(statusPath))
+      continue;
+    try {
+      const status = JSON.parse(readFileSync6(statusPath, "utf8"));
+      total++;
+      if (status.status === "running" || status.status === "starting") {
+        const pid = status.pid;
+        if (pid) {
+          let alive = false;
+          try {
+            process.kill(pid, 0);
+            alive = true;
+          } catch {}
+          if (alive) {
+            running++;
+          } else {
+            zombies++;
+            warn2(`${jobId}  ${yellow8("ZOMBIE")}  ${dim11(`pid ${pid} not found, status=${status.status}`)}`);
+            fix(`Edit .specialists/jobs/${jobId}/status.json  →  set "status": "error"`);
+          }
+        }
+      }
+    } catch {}
+  }
+  if (zombies === 0) {
+    const detail = running > 0 ? `, ${running} currently running` : ", none currently running";
+    ok3(`${total} job${total !== 1 ? "s" : ""} checked${detail}`);
+  }
+  return zombies === 0;
+}
+async function run13() {
+  console.log(`
+${bold8("specialists doctor")}
+`);
+  const piOk = checkPi();
+  const hooksOk = checkHooks();
+  const mcpOk = checkMCP();
+  const dirsOk = checkRuntimeDirs();
+  const jobsOk = checkZombieJobs();
+  const allOk = piOk && hooksOk && mcpOk && dirsOk && jobsOk;
+  console.log("");
+  if (allOk) {
+    console.log(`  ${green8("✓")} ${bold8("All checks passed")}  — specialists is healthy`);
+  } else {
+    console.log(`  ${yellow8("○")} ${bold8("Some checks failed")}  — follow the fix hints above`);
+    console.log(`  ${dim11("specialists install  fixes most issues automatically.")}`);
+  }
+  console.log("");
+}
+var bold8 = (s) => `\x1B[1m${s}\x1B[0m`, dim11 = (s) => `\x1B[2m${s}\x1B[0m`, green8 = (s) => `\x1B[32m${s}\x1B[0m`, yellow8 = (s) => `\x1B[33m${s}\x1B[0m`, red5 = (s) => `\x1B[31m${s}\x1B[0m`, HOME, CLAUDE_DIR, HOOKS_DIR, SETTINGS_FILE, MCP_NAME = "specialists", HOOK_NAMES;
+var init_doctor = __esm(() => {
+  HOME = homedir2();
+  CLAUDE_DIR = join12(HOME, ".claude");
+  HOOKS_DIR = join12(CLAUDE_DIR, "hooks");
+  SETTINGS_FILE = join12(CLAUDE_DIR, "settings.json");
+  HOOK_NAMES = [
+    "specialists-main-guard.mjs",
+    "beads-edit-gate.mjs",
+    "beads-commit-gate.mjs",
+    "beads-stop-gate.mjs",
+    "beads-close-memory-prompt.mjs",
+    "specialists-complete.mjs",
+    "specialists-session-start.mjs"
+  ];
+});
+
+// src/cli/setup.ts
+var exports_setup = {};
+__export(exports_setup, {
+  run: () => run14
+});
+import { existsSync as existsSync9, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { join as join13, resolve } from "node:path";
+function ok4(msg) {
+  console.log(`  ${green9("✓")} ${msg}`);
+}
+function skip2(msg) {
+  console.log(`  ${yellow9("○")} ${msg}`);
+}
+function resolveTarget(target) {
+  switch (target) {
+    case "global":
+      return join13(homedir3(), ".claude", "CLAUDE.md");
+    case "agents":
+      return join13(process.cwd(), "AGENTS.md");
+    case "project":
+    default:
+      return join13(process.cwd(), "CLAUDE.md");
+  }
+}
+function parseArgs5() {
+  const argv = process.argv.slice(3);
+  let target = "project";
+  let dryRun = false;
+  for (let i = 0;i < argv.length; i++) {
+    const token = argv[i];
+    if (token === "--global" || token === "-g") {
+      target = "global";
+      continue;
+    }
+    if (token === "--agents" || token === "-a") {
+      target = "agents";
+      continue;
+    }
+    if (token === "--project" || token === "-p") {
+      target = "project";
+      continue;
+    }
+    if (token === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
+  }
+  return { target, dryRun };
+}
+async function run14() {
+  const { target, dryRun } = parseArgs5();
+  const filePath = resolve(resolveTarget(target));
+  const label = target === "global" ? "~/.claude/CLAUDE.md" : filePath.replace(process.cwd() + "/", "");
+  console.log(`
+${bold9("specialists setup")}
+`);
+  console.log(`  Target: ${yellow9(label)}${dryRun ? dim12("  (dry-run)") : ""}
+`);
+  if (existsSync9(filePath)) {
+    const existing = readFileSync7(filePath, "utf8");
+    if (existing.includes(MARKER)) {
+      skip2(`${label} already contains Specialists Workflow section`);
+      console.log(`
+  ${dim12("To force-update, remove the ## Specialists Workflow section and re-run.")}
+`);
+      return;
+    }
+    if (dryRun) {
+      console.log(dim12("─".repeat(60)));
+      console.log(dim12("Would append to existing file:"));
+      console.log("");
+      console.log(WORKFLOW_BLOCK);
+      console.log(dim12("─".repeat(60)));
+      return;
+    }
+    const separator = existing.trimEnd().endsWith(`
+`) ? `
+` : `
+
+`;
+    writeFileSync4(filePath, existing.trimEnd() + separator + WORKFLOW_BLOCK, "utf8");
+    ok4(`Appended Specialists Workflow section to ${label}`);
+  } else {
+    if (dryRun) {
+      console.log(dim12("─".repeat(60)));
+      console.log(dim12(`Would create ${label}:`));
+      console.log("");
+      console.log(WORKFLOW_BLOCK);
+      console.log(dim12("─".repeat(60)));
+      return;
+    }
+    writeFileSync4(filePath, WORKFLOW_BLOCK, "utf8");
+    ok4(`Created ${label} with Specialists Workflow section`);
+  }
+  console.log("");
+  console.log(`  ${dim12("Next steps:")}`);
+  console.log(`  • Restart Claude Code to pick up the new context`);
+  console.log(`  • Run ${yellow9("specialists list")} to see available specialists`);
+  console.log(`  • Run ${yellow9("specialist_init")} in a new session to bootstrap context`);
+  console.log("");
+}
+var bold9 = (s) => `\x1B[1m${s}\x1B[0m`, dim12 = (s) => `\x1B[2m${s}\x1B[0m`, green9 = (s) => `\x1B[32m${s}\x1B[0m`, yellow9 = (s) => `\x1B[33m${s}\x1B[0m`, MARKER = "## Specialists Workflow", WORKFLOW_BLOCK = `## Specialists Workflow
+
+> Injected by \`specialists setup\`. Keep this section — agents use it for context.
+
+### When to use specialists
+
+Specialists are autonomous AI agents (running via the \`specialists\` MCP server)
+optimised for heavy tasks: code review, deep bug analysis, test generation,
+architecture design. Use them instead of doing the work yourself when the task
+would benefit from a fresh perspective, a second opinion, or a different model.
+
+### Quick reference
+
+\`\`\`
+# List available specialists
+specialists list                                    # all scopes
+specialists list --scope project                    # this project only
+
+# Run a specialist (foreground — streams output)
+specialists run <name> --prompt "..."
+
+# Run async (background — immediate job ID)
+specialists run <name> --prompt "..." --background
+  → Job started: job_a1b2c3d4
+
+# Watch / get results
+specialists feed job_a1b2c3d4 --follow             # tail live events
+specialists result job_a1b2c3d4                    # read final output
+specialists stop job_a1b2c3d4                      # cancel if needed
+\`\`\`
+
+### MCP tools (available in this session)
+
+| Tool | Purpose |
+|------|---------|
+| \`specialist_init\` | Bootstrap: bd init + list specialists |
+| \`list_specialists\` | Discover specialists across scopes |
+| \`use_specialist\` | Run foreground: load → inject context → execute → output |
+| \`start_specialist\` | Start async: returns job ID immediately |
+| \`poll_specialist\` | Poll job status + delta output by ID |
+| \`stop_specialist\` | Cancel a running job |
+| \`run_parallel\` | Run multiple specialists concurrently or as a pipeline |
+| \`specialist_status\` | Circuit breaker health + staleness |
+
+### Completion banner format
+
+When a specialist finishes, you may see:
+
+\`\`\`
+✓ bead unitAI-xxx  4.1s  anthropic/claude-sonnet-4-6
+\`\`\`
+
+This means:
+- The specialist completed successfully
+- A beads issue (\`unitAI-xxx\`) was created to track the run
+- The result can be fetched with \`specialists result <job-id>\`
+
+### When NOT to use specialists
+
+- Simple single-file edits — just do it directly
+- Tasks that need interactive back-and-forth — use foreground mode or work yourself
+- Short read-only queries — faster to answer directly
+`;
+var init_setup = () => {};
+
 // src/cli/help.ts
 var exports_help = {};
 __export(exports_help, {
-  run: () => run12
+  run: () => run15
 });
-async function run12() {
+function formatGroup(label, entries) {
+  const colWidth = Math.max(...entries.map(([cmd3]) => cmd3.length));
+  return [
+    "",
+    bold10(cyan7(label)),
+    ...entries.map(([cmd3, desc]) => `  ${cmd3.padEnd(colWidth)}    ${dim13(desc)}`)
+  ];
+}
+async function run15() {
   const lines = [
     "",
-    bold7("specialists <command>"),
+    bold10("specialists <command> [options]"),
     "",
-    "Commands:",
-    ...COMMANDS.map(([cmd2, desc]) => `  ${cmd2.padEnd(COL_WIDTH)}    ${dim10(desc)}`),
+    dim13("One MCP server. Multiple AI backends. Intelligent orchestration."),
+    ...formatGroup("Setup", SETUP),
+    ...formatGroup("Discovery", DISCOVERY),
+    ...formatGroup("Running", RUNNING),
+    ...formatGroup("Jobs", JOBS),
+    ...formatGroup("Other", OTHER),
     "",
-    dim10("Run 'specialists <command> --help' for command-specific options."),
+    dim13("Run 'specialists <command> --help' for command-specific options."),
+    dim13("Run 'specialists quickstart' for a full getting-started guide."),
     ""
   ];
   console.log(lines.join(`
 `));
 }
-var bold7 = (s) => `\x1B[1m${s}\x1B[0m`, dim10 = (s) => `\x1B[2m${s}\x1B[0m`, COMMANDS, COL_WIDTH;
+var bold10 = (s) => `\x1B[1m${s}\x1B[0m`, dim13 = (s) => `\x1B[2m${s}\x1B[0m`, cyan7 = (s) => `\x1B[36m${s}\x1B[0m`, SETUP, DISCOVERY, RUNNING, JOBS, OTHER;
 var init_help = __esm(() => {
-  COMMANDS = [
+  SETUP = [
     ["install", "Full-stack installer: pi, beads, dolt, MCP registration, hooks"],
+    ["init", "Scaffold specialists/, .specialists/, AGENTS.md in current project"],
+    ["setup", "Inject workflow context block into CLAUDE.md or AGENTS.md"],
+    ["quickstart", "Rich getting-started guide with examples and YAML schema reference"],
+    ["doctor", "Health check: pi, hooks, MCP registration, dirs, zombie jobs"]
+  ];
+  DISCOVERY = [
     ["list", "List available specialists with model and description"],
     ["models", "List models available on pi, flagged with thinking/images support"],
-    ["version", "Print installed version"],
-    ["init", "Initialize specialists in the current project"],
-    ["edit", "Edit a specialist field  (e.g. --model, --description)"],
+    ["status", "Show system health (pi, beads, MCP, jobs)"]
+  ];
+  RUNNING = [
     ["run", "Run a specialist with a prompt (--background for async)"],
-    ["result", "Print result of a background job"],
+    ["edit", "Edit a specialist field  (e.g. --model, --description)"]
+  ];
+  JOBS = [
     ["feed", "Tail events for a background job (--follow to stream)"],
-    ["stop", "Send SIGTERM to a running background job"],
-    ["status", "Show system health (pi, beads, MCP, jobs)"],
+    ["result", "Print result of a background job"],
+    ["stop", "Send SIGTERM to a running background job"]
+  ];
+  OTHER = [
+    ["version", "Print installed version"],
     ["help", "Show this help message"]
   ];
-  COL_WIDTH = Math.max(...COMMANDS.map(([cmd2]) => cmd2.length));
 });
 
 // node_modules/zod/v4/core/core.js
@@ -27107,8 +27775,26 @@ class SpecialistsServer {
 
 // src/index.ts
 var sub = process.argv[2];
-async function run13() {
+var next = process.argv[3];
+function wantsHelp() {
+  return next === "--help" || next === "-h";
+}
+async function run16() {
   if (sub === "install") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists install",
+        "",
+        "Full-stack setup: installs pi, beads, dolt, registers the MCP server,",
+        "and installs session hooks and skills for Claude Code.",
+        "",
+        "No flags — just run it.",
+        ""
+      ].join(`
+`));
+      return;
+    }
     const { run: handler } = await Promise.resolve().then(() => (init_install(), exports_install));
     return handler();
   }
@@ -27117,41 +27803,284 @@ async function run13() {
     return handler();
   }
   if (sub === "list") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists list [options]",
+        "",
+        "List available specialists across all scopes.",
+        "",
+        "Options:",
+        "  --scope <project|user>   Filter by scope",
+        "  --category <name>        Filter by category tag",
+        "  --json                   Output as JSON array",
+        "",
+        "Examples:",
+        "  specialists list",
+        "  specialists list --scope project",
+        "  specialists list --category analysis",
+        "  specialists list --json",
+        ""
+      ].join(`
+`));
+      return;
+    }
     const { run: handler } = await Promise.resolve().then(() => (init_list(), exports_list));
     return handler();
   }
   if (sub === "models") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists models",
+        "",
+        "List all models available on pi, with thinking and image support flags.",
+        "",
+        "No flags.",
+        ""
+      ].join(`
+`));
+      return;
+    }
     const { run: handler } = await Promise.resolve().then(() => (init_models(), exports_models));
     return handler();
   }
   if (sub === "init") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists init",
+        "",
+        "Initialize specialists in the current project:",
+        "  • Creates specialists/           — put .specialist.yaml files here",
+        "  • Creates .specialists/          — runtime data (gitignored)",
+        "  • Adds .specialists/ to .gitignore",
+        "  • Scaffolds AGENTS.md            — context injected into Claude sessions",
+        "",
+        "Safe to run on an existing project (skips already-present items).",
+        ""
+      ].join(`
+`));
+      return;
+    }
     const { run: handler } = await Promise.resolve().then(() => (init_init(), exports_init));
     return handler();
   }
   if (sub === "edit") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists edit <name> --<field> <value> [options]",
+        "",
+        "Edit a field in a .specialist.yaml without opening the file.",
+        "",
+        "Editable fields:",
+        "  --model <value>          Primary execution model",
+        "  --fallback-model <value> Fallback model (used on circuit-break)",
+        "  --description <value>    One-line description",
+        "  --permission <value>     READ_ONLY | LOW | MEDIUM | HIGH",
+        "  --timeout <ms>           Timeout in milliseconds",
+        "  --tags <a,b,c>           Comma-separated list of tags",
+        "",
+        "Options:",
+        "  --dry-run                Preview the change without writing",
+        "  --scope <project|user>   Disambiguate if same name exists in multiple scopes",
+        "",
+        "Examples:",
+        "  specialists edit code-review --model anthropic/claude-opus-4-6",
+        "  specialists edit code-review --permission HIGH --dry-run",
+        "  specialists edit code-review --tags analysis,security",
+        ""
+      ].join(`
+`));
+      return;
+    }
     const { run: handler } = await Promise.resolve().then(() => (init_edit(), exports_edit));
     return handler();
   }
   if (sub === "run") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists run <name> [options]",
+        "",
+        "Run a specialist. Streams output to stdout by default.",
+        "Reads prompt from stdin if --prompt is not provided.",
+        "",
+        "Options:",
+        "  --prompt <text>    Prompt to send to the specialist (required unless piped)",
+        "  --model <model>    Override the model for this run only",
+        "  --background       Run async; prints job ID and exits immediately",
+        "  --no-beads         Skip creating a beads issue for this run",
+        "",
+        "Examples:",
+        '  specialists run code-review --prompt "Audit src/api.ts"',
+        '  specialists run code-review --prompt "..." --background',
+        "  cat brief.md | specialists run deep-analysis",
+        '  specialists run code-review --model anthropic/claude-opus-4-6 --prompt "..."',
+        "",
+        "See also:",
+        "  specialists feed --help   (tail events for a background job)",
+        "  specialists result --help (read background job output)",
+        ""
+      ].join(`
+`));
+      return;
+    }
     const { run: handler } = await Promise.resolve().then(() => (init_run(), exports_run));
     return handler();
   }
   if (sub === "status") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists status [options]",
+        "",
+        "Show system health: pi runtime, beads installation, MCP registration,",
+        "and all active background jobs.",
+        "",
+        "Options:",
+        "  --json    Output as JSON",
+        "",
+        "Examples:",
+        "  specialists status",
+        "  specialists status --json",
+        ""
+      ].join(`
+`));
+      return;
+    }
     const { run: handler } = await Promise.resolve().then(() => (init_status(), exports_status));
     return handler();
   }
   if (sub === "result") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists result <job-id>",
+        "",
+        "Print the final output of a completed background job.",
+        "Exits with code 1 if the job is still running or failed.",
+        "",
+        "Examples:",
+        "  specialists result job_a1b2c3d4",
+        "  specialists result job_a1b2c3d4 > output.md",
+        "",
+        "See also:",
+        "  specialists feed <job-id> --follow   (stream live events)",
+        "  specialists status                   (list all active jobs)",
+        ""
+      ].join(`
+`));
+      return;
+    }
     const { run: handler } = await Promise.resolve().then(() => (init_result(), exports_result));
     return handler();
   }
   if (sub === "feed") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists feed <job-id> [options]",
+        "       specialists feed --job <job-id> [options]",
+        "",
+        "Print events emitted by a background job.",
+        "",
+        "Options:",
+        "  --follow, -f    Stay open and stream new events as they arrive",
+        "                  (exits automatically when job completes)",
+        "",
+        "Examples:",
+        "  specialists feed job_a1b2c3d4",
+        "  specialists feed job_a1b2c3d4 --follow",
+        "  specialists feed --job job_a1b2c3d4 -f",
+        "",
+        "Event types: tool_use · tool_result · text · agent_end · error",
+        ""
+      ].join(`
+`));
+      return;
+    }
     const { run: handler } = await Promise.resolve().then(() => (init_feed(), exports_feed));
     return handler();
   }
   if (sub === "stop") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists stop <job-id>",
+        "",
+        "Send SIGTERM to the agent process for a running background job.",
+        "Has no effect if the job is already done or errored.",
+        "",
+        "Examples:",
+        "  specialists stop job_a1b2c3d4",
+        ""
+      ].join(`
+`));
+      return;
+    }
     const { run: handler } = await Promise.resolve().then(() => (init_stop(), exports_stop));
     return handler();
   }
+  if (sub === "quickstart") {
+    const { run: handler } = await Promise.resolve().then(() => exports_quickstart);
+    return handler();
+  }
+  if (sub === "doctor") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists doctor",
+        "",
+        "Health check for your specialists installation:",
+        "  1. pi installed and has at least one active provider",
+        "  2. All 7 Claude Code hooks present and wired in settings.json",
+        "  3. MCP server registered (claude mcp get specialists)",
+        "  4. .specialists/jobs/ and .specialists/ready/ dirs exist",
+        "  5. No zombie jobs (running status but dead PID)",
+        "",
+        "Prints fix hints for each failure.",
+        "Auto-creates missing runtime directories.",
+        "",
+        "Examples:",
+        "  specialists doctor",
+        ""
+      ].join(`
+`));
+      return;
+    }
+    const { run: handler } = await Promise.resolve().then(() => (init_doctor(), exports_doctor));
+    return handler();
+  }
+  if (sub === "setup") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists setup [options]",
+        "",
+        "Inject the Specialists Workflow context block into AGENTS.md or CLAUDE.md.",
+        "This teaches agents in that project how to use specialists.",
+        "",
+        "Options:",
+        "  --project, -p   Write to ./CLAUDE.md (default)",
+        "  --agents,  -a   Write to ./AGENTS.md",
+        "  --global,  -g   Write to ~/.claude/CLAUDE.md",
+        "  --dry-run       Preview the block without writing",
+        "",
+        "Examples:",
+        "  specialists setup                  # → ./CLAUDE.md",
+        "  specialists setup --agents         # → ./AGENTS.md",
+        "  specialists setup --global         # → ~/.claude/CLAUDE.md",
+        "  specialists setup --dry-run        # preview only",
+        ""
+      ].join(`
+`));
+      return;
+    }
+    const { run: handler } = await Promise.resolve().then(() => (init_setup(), exports_setup));
+    return handler();
+  }
   if (sub === "help" || sub === "--help" || sub === "-h") {
     const { run: handler } = await Promise.resolve().then(() => (init_help(), exports_help));
     return handler();
@@ -27165,7 +28094,7 @@ Run 'specialists help' to see available commands.`);
   const server = new SpecialistsServer;
   await server.start();
 }
-run13().catch((error2) => {
+run16().catch((error2) => {
   logger.error(`Fatal error: ${error2}`);
   process.exit(1);
 });