@jaggerxtrm/specialists 3.0.2 → 3.2.1

package/dist/index.js

@@ -8531,6 +8531,7 @@ var require_limitLength = __commonJS((exports) => {
 var require_pattern = __commonJS((exports) => {
   Object.defineProperty(exports, "__esModule", { value: true });
   var code_1 = require_code2();
+  var util_1 = require_util();
   var codegen_1 = require_codegen();
   var error2 = {
     message: ({ schemaCode }) => (0, codegen_1.str)`must match pattern "${schemaCode}"`,
@@ -8543,10 +8544,18 @@ var require_pattern = __commonJS((exports) => {
     $data: true,
     error: error2,
     code(cxt) {
-      const { data, $data, schema, schemaCode, it } = cxt;
+      const { gen, data, $data, schema, schemaCode, it } = cxt;
       const u = it.opts.unicodeRegExp ? "u" : "";
-      const regExp = $data ? (0, codegen_1._)`(new RegExp(${schemaCode}, ${u}))` : (0, code_1.usePattern)(cxt, schema);
-      cxt.fail$data((0, codegen_1._)`!${regExp}.test(${data})`);
+      if ($data) {
+        const { regExp } = it.opts.code;
+        const regExpCode = regExp.code === "new RegExp" ? (0, codegen_1._)`new RegExp` : (0, util_1.useFunc)(gen, regExp);
+        const valid = gen.let("valid");
+        gen.try(() => gen.assign(valid, (0, codegen_1._)`${regExpCode}(${schemaCode}, ${u}).test(${data})`), () => gen.assign(valid, false));
+        cxt.fail$data((0, codegen_1._)`!${valid}`);
+      } else {
+        const regExp = (0, code_1.usePattern)(cxt, schema);
+        cxt.fail$data((0, codegen_1._)`!${regExp}.test(${data})`);
+      }
     }
   };
   exports.default = def;
@@ -17524,12 +17533,13 @@ class SpecialistLoader {
     this.userDir = options.userDir ?? join(homedir(), ".agents", "specialists");
   }
   getScanDirs() {
-    return [
+    const dirs = [
       { path: join(this.projectDir, "specialists"), scope: "project" },
       { path: join(this.projectDir, ".claude", "specialists"), scope: "project" },
       { path: join(this.projectDir, ".agent-forge", "specialists"), scope: "project" },
       { path: this.userDir, scope: "user" }
-    ].filter((d) => existsSync(d.path));
+    ];
+    return dirs.filter((d) => existsSync(d.path));
   }
   async list(category) {
     const results = [];
@@ -17640,6 +17650,9 @@ var init_backendMap = __esm(() => {
 
 // src/pi/session.ts
 import { spawn } from "node:child_process";
+import { existsSync as existsSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join2 } from "node:path";
 function mapPermissionToTools(level) {
   switch (level?.toUpperCase()) {
     case "READ_ONLY":
@@ -17659,6 +17672,7 @@ class PiAgentSession {
   options;
   proc;
   _lastOutput = "";
+  _donePromise;
   _doneResolve;
   _doneReject;
   _agentEndReceived = false;
@@ -17686,6 +17700,7 @@ class PiAgentSession {
     const args = [
       "--mode",
       "rpc",
+      "--no-extensions",
       ...providerArgs,
       "--no-session",
       ...extraArgs
@@ -17693,11 +17708,22 @@ class PiAgentSession {
     const toolsFlag = mapPermissionToTools(this.options.permissionLevel);
     if (toolsFlag)
       args.push("--tools", toolsFlag);
+    const piExtDir = join2(homedir2(), ".pi", "agent", "extensions");
+    const permLevel = (this.options.permissionLevel ?? "").toUpperCase();
+    if (permLevel !== "READ_ONLY") {
+      const qgPath = join2(piExtDir, "quality-gates");
+      if (existsSync2(qgPath))
+        args.push("-e", qgPath);
+    }
+    const ssPath = join2(piExtDir, "service-skills");
+    if (existsSync2(ssPath))
+      args.push("-e", ssPath);
     if (this.options.systemPrompt) {
       args.push("--append-system-prompt", this.options.systemPrompt);
     }
     this.proc = spawn("pi", args, {
-      stdio: ["pipe", "pipe", "inherit"]
+      stdio: ["pipe", "pipe", "inherit"],
+      cwd: this.options.cwd
     });
     const donePromise = new Promise((resolve, reject) => {
       this._doneResolve = resolve;
@@ -17759,34 +17785,11 @@ class PiAgentSession {
         this._lastOutput = last.content.filter((c) => c.type === "text").map((c) => c.text).join("");
       }
       this._agentEndReceived = true;
-      this.options.onEvent?.("done");
+      this.options.onEvent?.("agent_end");
       this._doneResolve?.();
       return;
     }
-    if (type === "thinking_start") {
-      this.options.onEvent?.("thinking");
-      return;
-    }
-    if (type === "thinking_delta") {
-      if (event.delta)
-        this.options.onThinking?.(event.delta);
-      this.options.onEvent?.("thinking");
-      return;
-    }
-    if (type === "thinking_end") {
-      return;
-    }
-    if (type === "toolcall_start") {
-      this.options.onToolStart?.(event.name ?? event.toolName ?? "tool");
-      this.options.onEvent?.("toolcall");
-      return;
-    }
-    if (type === "toolcall_end") {
-      this.options.onEvent?.("toolcall");
-      return;
-    }
     if (type === "tool_execution_start") {
-      this.options.onToolStart?.(event.name ?? event.toolName ?? "tool");
       this.options.onEvent?.("tool_execution");
       return;
     }
@@ -17795,7 +17798,7 @@ class PiAgentSession {
       return;
     }
     if (type === "tool_execution_end") {
-      this.options.onToolEnd?.(event.name ?? event.toolName ?? "tool");
+      this.options.onToolEnd?.(event.toolName ?? event.name ?? "tool");
       this.options.onEvent?.("tool_execution_end");
       return;
     }
@@ -17803,9 +17806,30 @@ class PiAgentSession {
       const ae = event.assistantMessageEvent;
       if (!ae)
         return;
-      if (ae.type === "text_delta" && ae.delta) {
-        this.options.onToken?.(ae.delta);
-        this.options.onEvent?.("text");
+      switch (ae.type) {
+        case "text_delta":
+          if (ae.delta)
+            this.options.onToken?.(ae.delta);
+          this.options.onEvent?.("text");
+          break;
+        case "thinking_start":
+          this.options.onEvent?.("thinking");
+          break;
+        case "thinking_delta":
+          if (ae.delta)
+            this.options.onThinking?.(ae.delta);
+          this.options.onEvent?.("thinking");
+          break;
+        case "toolcall_start":
+          this.options.onToolStart?.(ae.name ?? ae.toolName ?? "tool");
+          this.options.onEvent?.("toolcall");
+          break;
+        case "toolcall_end":
+          this.options.onEvent?.("toolcall");
+          break;
+        case "done":
+          this.options.onEvent?.("message_done");
+          break;
       }
     }
   }
@@ -17831,7 +17855,7 @@ class PiAgentSession {
     this.proc?.stdin?.write(msg);
   }
   async waitForDone(timeout) {
-    const donePromise = this._donePromise;
+    const donePromise = this._donePromise ?? Promise.resolve();
     if (!timeout)
       return donePromise;
     return Promise.race([
@@ -17868,7 +17892,7 @@ class PiAgentSession {
     if (this._killed)
       return;
     this.proc?.stdin?.end();
-    await this._donePromise.catch(() => {});
+    await this._donePromise?.catch(() => {});
   }
   kill() {
     if (this._killed)
@@ -17892,6 +17916,29 @@ var init_session = __esm(() => {
 
 // src/specialist/beads.ts
 import { spawnSync } from "node:child_process";
+function buildBeadContext(bead, completedBlockers = []) {
+  const lines = [`# Task: ${bead.title}`];
+  if (bead.description?.trim()) {
+    lines.push(bead.description.trim());
+  }
+  if (bead.notes?.trim()) {
+    lines.push("", "## Notes", bead.notes.trim());
+  }
+  if (completedBlockers.length > 0) {
+    lines.push("", "## Context from completed dependencies:");
+    for (const blocker of completedBlockers) {
+      lines.push("", `### ${blocker.title} (${blocker.id})`);
+      if (blocker.description?.trim()) {
+        lines.push(blocker.description.trim());
+      }
+      if (blocker.notes?.trim()) {
+        lines.push("", blocker.notes.trim());
+      }
+    }
+  }
+  return lines.join(`
+`).trim();
+}
 
 class BeadsClient {
   available;
@@ -17917,12 +17964,66 @@ class BeadsClient {
     const id = result.stdout?.trim();
     return id || null;
   }
+  readBead(id) {
+    if (!this.available || !id)
+      return null;
+    const result = spawnSync("bd", ["show", id, "--json"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 });
+    if (result.error || result.status !== 0 || !result.stdout?.trim())
+      return null;
+    try {
+      const parsed = JSON.parse(result.stdout);
+      const bead = Array.isArray(parsed) ? parsed[0] : parsed;
+      if (!bead || typeof bead !== "object" || typeof bead.id !== "string" || typeof bead.title !== "string")
+        return null;
+      return bead;
+    } catch (err) {
+      console.warn(`[specialists] readBead: JSON parse failed for id=${id}: ${err}`);
+      return null;
+    }
+  }
+  getCompletedBlockers(id, depth = 1) {
+    if (!this.available || !id || depth < 1)
+      return [];
+    const result = spawnSync("bd", ["dep", "list", id, "--json"], { encoding: "utf-8", stdio: ["ignore", "pipe", "ignore"], timeout: 5000 });
+    if (result.error || result.status !== 0 || !result.stdout?.trim())
+      return [];
+    let deps;
+    try {
+      deps = JSON.parse(result.stdout);
+      if (!Array.isArray(deps))
+        return [];
+    } catch {
+      return [];
+    }
+    const blockers = deps.filter((d) => d.dependency_type === "blocks" && d.status === "closed");
+    const records = [];
+    for (const dep of blockers) {
+      const record3 = this.readBead(dep.id);
+      if (record3) {
+        records.push(record3);
+        if (depth > 1) {
+          records.push(...this.getCompletedBlockers(dep.id, depth - 1));
+        }
+      }
+    }
+    return records;
+  }
+  addDependency(trackingBeadId, inputBeadId) {
+    if (!this.available || !trackingBeadId || !inputBeadId)
+      return;
+    spawnSync("bd", ["dep", "add", trackingBeadId, inputBeadId], { stdio: "ignore" });
+  }
   closeBead(id, status, durationMs, model) {
     if (!this.available || !id)
       return;
     const reason = `${status}, ${Math.round(durationMs)}ms, ${model}`;
     spawnSync("bd", ["close", id, "-r", reason], { stdio: "ignore" });
   }
+  updateBeadNotes(id, notes) {
+    if (!this.available || !id || !notes)
+      return;
+    spawnSync("bd", ["update", id, "--notes", notes], { stdio: "ignore" });
+  }
   auditBead(id, toolName, model, exitCode) {
     if (!this.available || !id)
       return;
@@ -18006,7 +18107,14 @@ class SpecialistRunner {
     const preScripts = spec.specialist.skills?.scripts?.filter((s) => s.phase === "pre") ?? [];
     const preResults = preScripts.map((s) => runScript(s.path)).filter((_, i) => preScripts[i].inject_output);
     const preScriptOutput = formatScriptOutput(preResults);
-    const variables = { prompt: options.prompt, pre_script_output: preScriptOutput, ...options.variables };
+    const beadVariables = options.inputBeadId ? { bead_context: options.prompt, bead_id: options.inputBeadId } : {};
+    const variables = {
+      prompt: options.prompt,
+      cwd: process.cwd(),
+      pre_script_output: preScriptOutput,
+      ...options.variables ?? {},
+      ...beadVariables
+    };
     const renderedTask = renderTemplate(prompt.task_template, variables);
     const promptHash = createHash("sha256").update(renderedTask).digest("hex").slice(0, 16);
     await hooks.emit("post_render", invocationId, metadata.name, metadata.version, {
@@ -18059,10 +18167,15 @@ You have access via Bash:
     });
     const beadsIntegration = spec.specialist.beads_integration ?? "auto";
     let beadId;
-    if (beadsClient && shouldCreateBead(beadsIntegration, execution.permission_required)) {
+    let ownsBead = false;
+    if (options.inputBeadId) {
+      beadId = options.inputBeadId;
+    } else if (beadsClient && shouldCreateBead(beadsIntegration, execution.permission_required)) {
       beadId = beadsClient.createBead(metadata.name) ?? undefined;
-      if (beadId)
+      if (beadId) {
+        ownsBead = true;
         onBeadCreated?.(beadId);
+      }
     }
     let output;
     let sessionBackend = model;
@@ -18072,6 +18185,7 @@ You have access via Bash:
         model,
         systemPrompt: agentsMd || undefined,
         permissionLevel,
+        cwd: process.cwd(),
         onToken: (delta) => onProgress?.(delta),
         onThinking: (delta) => onProgress?.(`\uD83D\uDCAD ${delta}`),
         onToolStart: (tool) => onProgress?.(`
@@ -18100,7 +18214,8 @@ You have access via Bash:
       }
       const beadStatus = isCancelled ? "CANCELLED" : "ERROR";
       if (beadId) {
-        beadsClient?.closeBead(beadId, beadStatus, Date.now() - start, model);
+        if (ownsBead)
+          beadsClient?.closeBead(beadId, beadStatus, Date.now() - start, model);
         beadsClient?.auditBead(beadId, metadata.name, model, 1);
       }
       await hooks.emit("post_execute", invocationId, metadata.name, metadata.version, {
@@ -18123,7 +18238,8 @@ You have access via Bash:
       output_valid: true
     });
     if (beadId) {
-      beadsClient?.closeBead(beadId, "COMPLETE", durationMs, model);
+      if (ownsBead)
+        beadsClient?.closeBead(beadId, "COMPLETE", durationMs, model);
       beadsClient?.auditBead(beadId, metadata.name, model, 0);
     }
     return {
@@ -18132,6 +18248,7 @@ You have access via Bash:
       model,
       durationMs,
       specialistVersion: metadata.version,
+      promptHash,
       beadId
     };
   }
@@ -18234,9 +18351,9 @@ __export(exports_install, {
 });
 import { execFileSync } from "node:child_process";
 import { fileURLToPath } from "node:url";
-import { dirname as dirname2, join as join4 } from "node:path";
+import { dirname as dirname2, join as join5 } from "node:path";
 async function run() {
-  const installerPath = join4(dirname2(fileURLToPath(import.meta.url)), "..", "bin", "install.js");
+  const installerPath = join5(dirname2(fileURLToPath(import.meta.url)), "..", "bin", "install.js");
   execFileSync(process.execPath, [installerPath], { stdio: "inherit" });
 }
 var init_install = () => {};
@@ -18281,6 +18398,10 @@ function parseArgs(argv) {
       result.scope = value;
       continue;
     }
+    if (token === "--json") {
+      result.json = true;
+      continue;
+    }
   }
   return result;
 }
@@ -18300,6 +18421,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;
@@ -18383,7 +18508,7 @@ async function run4() {
   }
   const allModels = parsePiModels();
   if (!allModels) {
-    console.error("pi not found or failed — run specialists install");
+    console.error("pi not found or failed — install and configure pi first");
     process.exit(1);
   }
   let models = allModels;
@@ -18439,36 +18564,62 @@ var exports_init = {};
 __export(exports_init, {
   run: () => run5
 });
-import { existsSync as existsSync3, mkdirSync, readFileSync, writeFileSync } from "node:fs";
-import { join as join5 } from "node:path";
+import { existsSync as existsSync4, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join as join6 } from "node:path";
 function ok(msg) {
   console.log(`  ${green2("✓")} ${msg}`);
 }
 function skip(msg) {
   console.log(`  ${yellow3("○")} ${msg}`);
 }
+function loadJson(path, fallback) {
+  if (!existsSync4(path))
+    return structuredClone(fallback);
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return structuredClone(fallback);
+  }
+}
+function saveJson(path, value) {
+  writeFileSync(path, JSON.stringify(value, null, 2) + `
+`, "utf-8");
+}
+function ensureProjectMcp(cwd) {
+  const mcpPath = join6(cwd, MCP_FILE);
+  const mcp = loadJson(mcpPath, { mcpServers: {} });
+  mcp.mcpServers ??= {};
+  const existing = mcp.mcpServers[MCP_SERVER_NAME];
+  if (existing && existing.command === MCP_SERVER_CONFIG.command && Array.isArray(existing.args) && existing.args.length === MCP_SERVER_CONFIG.args.length) {
+    skip(".mcp.json already registers specialists");
+    return;
+  }
+  mcp.mcpServers[MCP_SERVER_NAME] = MCP_SERVER_CONFIG;
+  saveJson(mcpPath, mcp);
+  ok("registered specialists in project .mcp.json");
+}
 async function run5() {
   const cwd = process.cwd();
   console.log(`
 ${bold3("specialists init")}
 `);
-  const specialistsDir = join5(cwd, "specialists");
-  if (existsSync3(specialistsDir)) {
+  const specialistsDir = join6(cwd, "specialists");
+  if (existsSync4(specialistsDir)) {
     skip("specialists/ already exists");
   } else {
     mkdirSync(specialistsDir, { recursive: true });
     ok("created specialists/");
   }
-  const runtimeDir = join5(cwd, ".specialists");
-  if (existsSync3(runtimeDir)) {
+  const runtimeDir = join6(cwd, ".specialists");
+  if (existsSync4(runtimeDir)) {
     skip(".specialists/ already exists");
   } else {
-    mkdirSync(join5(runtimeDir, "jobs"), { recursive: true });
-    mkdirSync(join5(runtimeDir, "ready"), { recursive: true });
+    mkdirSync(join6(runtimeDir, "jobs"), { recursive: true });
+    mkdirSync(join6(runtimeDir, "ready"), { recursive: true });
     ok("created .specialists/ (jobs/, ready/)");
   }
-  const gitignorePath = join5(cwd, ".gitignore");
-  if (existsSync3(gitignorePath)) {
+  const gitignorePath = join6(cwd, ".gitignore");
+  if (existsSync4(gitignorePath)) {
     const existing = readFileSync(gitignorePath, "utf-8");
     if (existing.includes(GITIGNORE_ENTRY)) {
       skip(".gitignore already has .specialists/ entry");
@@ -18485,8 +18636,8 @@ ${bold3("specialists init")}
 `, "utf-8");
     ok("created .gitignore with .specialists/ entry");
   }
-  const agentsPath = join5(cwd, "AGENTS.md");
-  if (existsSync3(agentsPath)) {
+  const agentsPath = join6(cwd, "AGENTS.md");
+  if (existsSync4(agentsPath)) {
     const existing = readFileSync(agentsPath, "utf-8");
     if (existing.includes(AGENTS_MARKER)) {
       skip("AGENTS.md already has Specialists section");
@@ -18500,16 +18651,17 @@ ${bold3("specialists init")}
     writeFileSync(agentsPath, AGENTS_BLOCK, "utf-8");
     ok("created AGENTS.md with Specialists section");
   }
+  ensureProjectMcp(cwd);
   console.log(`
 ${bold3("Done!")}
 `);
   console.log(`  ${dim3("Next steps:")}`);
   console.log(`  1. Add your specialists to ${yellow3("specialists/")}`);
   console.log(`  2. Run ${yellow3("specialists list")} to verify they are discovered`);
-  console.log(`  3. Restart Claude Code to pick up AGENTS.md changes
+  console.log(`  3. Restart Claude Code to pick up AGENTS.md / .mcp.json changes
 `);
 }
-var bold3 = (s) => `\x1B[1m${s}\x1B[0m`, green2 = (s) => `\x1B[32m${s}\x1B[0m`, yellow3 = (s) => `\x1B[33m${s}\x1B[0m`, dim3 = (s) => `\x1B[2m${s}\x1B[0m`, AGENTS_BLOCK, AGENTS_MARKER = "## Specialists", GITIGNORE_ENTRY = ".specialists/";
+var bold3 = (s) => `\x1B[1m${s}\x1B[0m`, green2 = (s) => `\x1B[32m${s}\x1B[0m`, yellow3 = (s) => `\x1B[33m${s}\x1B[0m`, dim3 = (s) => `\x1B[2m${s}\x1B[0m`, AGENTS_BLOCK, AGENTS_MARKER = "## Specialists", GITIGNORE_ENTRY = ".specialists/", MCP_FILE = ".mcp.json", MCP_SERVER_NAME = "specialists", MCP_SERVER_CONFIG;
 var init_init = __esm(() => {
   AGENTS_BLOCK = `
 ## Specialists
@@ -18519,6 +18671,7 @@ see available specialists. Use \`use_specialist\` or \`start_specialist\` to
 delegate heavy tasks (code review, bug hunting, deep reasoning) to the right
 specialist without user intervention.
 `.trimStart();
+  MCP_SERVER_CONFIG = { command: "specialists", args: [] };
 });
 
 // src/cli/edit.ts
@@ -18651,10 +18804,119 @@ var init_edit = __esm(() => {
   VALID_PERMISSIONS = ["READ_ONLY", "LOW", "MEDIUM", "HIGH"];
 });
 
+// src/specialist/timeline-events.ts
+function mapCallbackEventToTimelineEvent(callbackEvent, context) {
+  const t = Date.now();
+  switch (callbackEvent) {
+    case "thinking":
+      return { t, type: TIMELINE_EVENT_TYPES.THINKING };
+    case "toolcall":
+      return {
+        t,
+        type: TIMELINE_EVENT_TYPES.TOOL,
+        tool: context.tool ?? "unknown",
+        phase: "start",
+        tool_call_id: context.toolCallId
+      };
+    case "tool_execution_end":
+      return {
+        t,
+        type: TIMELINE_EVENT_TYPES.TOOL,
+        tool: context.tool ?? "unknown",
+        phase: "end",
+        tool_call_id: context.toolCallId,
+        is_error: context.isError
+      };
+    case "text":
+      return { t, type: TIMELINE_EVENT_TYPES.TEXT };
+    case "agent_end":
+    case "message_done":
+    case "done":
+      return null;
+    default:
+      return null;
+  }
+}
+function createRunStartEvent(specialist, beadId) {
+  return {
+    t: Date.now(),
+    type: TIMELINE_EVENT_TYPES.RUN_START,
+    specialist,
+    bead_id: beadId
+  };
+}
+function createMetaEvent(model, backend) {
+  return {
+    t: Date.now(),
+    type: TIMELINE_EVENT_TYPES.META,
+    model,
+    backend
+  };
+}
+function createRunCompleteEvent(status, elapsed_s, options) {
+  return {
+    t: Date.now(),
+    type: TIMELINE_EVENT_TYPES.RUN_COMPLETE,
+    status,
+    elapsed_s,
+    ...options
+  };
+}
+function parseTimelineEvent(line) {
+  try {
+    const parsed = JSON.parse(line);
+    if (!parsed || typeof parsed !== "object")
+      return null;
+    if (typeof parsed.t !== "number")
+      return null;
+    if (typeof parsed.type !== "string")
+      return null;
+    if (parsed.type === TIMELINE_EVENT_TYPES.DONE) {
+      return {
+        t: parsed.t,
+        type: TIMELINE_EVENT_TYPES.DONE,
+        elapsed_s: typeof parsed.elapsed_s === "number" ? parsed.elapsed_s : undefined
+      };
+    }
+    if (parsed.type === TIMELINE_EVENT_TYPES.AGENT_END) {
+      return {
+        t: parsed.t,
+        type: TIMELINE_EVENT_TYPES.AGENT_END,
+        elapsed_s: typeof parsed.elapsed_s === "number" ? parsed.elapsed_s : undefined
+      };
+    }
+    const knownTypes = Object.values(TIMELINE_EVENT_TYPES).filter((type) => type !== TIMELINE_EVENT_TYPES.DONE && type !== TIMELINE_EVENT_TYPES.AGENT_END);
+    if (!knownTypes.includes(parsed.type))
+      return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+function isRunCompleteEvent(event) {
+  return event.type === TIMELINE_EVENT_TYPES.RUN_COMPLETE;
+}
+function compareTimelineEvents(a, b) {
+  return a.t - b.t;
+}
+var TIMELINE_EVENT_TYPES;
+var init_timeline_events = __esm(() => {
+  TIMELINE_EVENT_TYPES = {
+    RUN_START: "run_start",
+    META: "meta",
+    THINKING: "thinking",
+    TOOL: "tool",
+    TEXT: "text",
+    RUN_COMPLETE: "run_complete",
+    DONE: "done",
+    AGENT_END: "agent_end"
+  };
+});
+
 // src/specialist/supervisor.ts
 import {
   closeSync,
-  existsSync as existsSync4,
+  existsSync as existsSync5,
   mkdirSync as mkdirSync2,
   openSync,
   readdirSync,
@@ -18665,7 +18927,32 @@ import {
   writeFileSync as writeFileSync3,
   writeSync
 } from "node:fs";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
+import { spawnSync as spawnSync4 } from "node:child_process";
+function getCurrentGitSha() {
+  const result = spawnSync4("git", ["rev-parse", "HEAD"], {
+    encoding: "utf-8",
+    stdio: ["ignore", "pipe", "ignore"]
+  });
+  if (result.status !== 0)
+    return;
+  const sha = result.stdout?.trim();
+  return sha || undefined;
+}
+function formatBeadNotes(result) {
+  const metadata = [
+    `prompt_hash=${result.promptHash}`,
+    `git_sha=${getCurrentGitSha() ?? "unknown"}`,
+    `elapsed_ms=${Math.round(result.durationMs)}`,
+    `model=${result.model}`,
+    `backend=${result.backend}`
+  ].join(`
+`);
+  return `${result.output}
+
+---
+${metadata}`;
+}
 
 class Supervisor {
   opts;
@@ -18673,23 +18960,23 @@ class Supervisor {
     this.opts = opts;
   }
   jobDir(id) {
-    return join6(this.opts.jobsDir, id);
+    return join7(this.opts.jobsDir, id);
   }
   statusPath(id) {
-    return join6(this.jobDir(id), "status.json");
+    return join7(this.jobDir(id), "status.json");
   }
   resultPath(id) {
-    return join6(this.jobDir(id), "result.txt");
+    return join7(this.jobDir(id), "result.txt");
   }
   eventsPath(id) {
-    return join6(this.jobDir(id), "events.jsonl");
+    return join7(this.jobDir(id), "events.jsonl");
   }
   readyDir() {
-    return join6(this.opts.jobsDir, "..", "ready");
+    return join7(this.opts.jobsDir, "..", "ready");
   }
   readStatus(id) {
     const path = this.statusPath(id);
-    if (!existsSync4(path))
+    if (!existsSync5(path))
       return null;
     try {
       return JSON.parse(readFileSync3(path, "utf-8"));
@@ -18698,12 +18985,12 @@ class Supervisor {
     }
   }
   listJobs() {
-    if (!existsSync4(this.opts.jobsDir))
+    if (!existsSync5(this.opts.jobsDir))
       return [];
     const jobs = [];
     for (const entry of readdirSync(this.opts.jobsDir)) {
-      const path = join6(this.opts.jobsDir, entry, "status.json");
-      if (!existsSync4(path))
+      const path = join7(this.opts.jobsDir, entry, "status.json");
+      if (!existsSync5(path))
         continue;
       try {
         jobs.push(JSON.parse(readFileSync3(path, "utf-8")));
@@ -18724,11 +19011,11 @@ class Supervisor {
     this.writeStatusFile(id, { ...current, ...updates });
   }
   gc() {
-    if (!existsSync4(this.opts.jobsDir))
+    if (!existsSync5(this.opts.jobsDir))
       return;
     const cutoff = Date.now() - JOB_TTL_DAYS * 86400000;
     for (const entry of readdirSync(this.opts.jobsDir)) {
-      const dir = join6(this.opts.jobsDir, entry);
+      const dir = join7(this.opts.jobsDir, entry);
       try {
         const stat2 = statSync(dir);
         if (!stat2.isDirectory())
@@ -18739,11 +19026,11 @@ class Supervisor {
     }
   }
   crashRecovery() {
-    if (!existsSync4(this.opts.jobsDir))
+    if (!existsSync5(this.opts.jobsDir))
       return;
     for (const entry of readdirSync(this.opts.jobsDir)) {
-      const statusPath = join6(this.opts.jobsDir, entry, "status.json");
-      if (!existsSync4(statusPath))
+      const statusPath = join7(this.opts.jobsDir, entry, "status.json");
+      if (!existsSync5(statusPath))
         continue;
       try {
         const s = JSON.parse(readFileSync3(statusPath, "utf-8"));
@@ -18780,14 +19067,19 @@ class Supervisor {
     };
     this.writeStatusFile(id, initialStatus);
     const eventsFd = openSync(this.eventsPath(id), "a");
-    const appendEvent = (obj) => {
+    const appendTimelineEvent = (event) => {
       try {
-        writeSync(eventsFd, JSON.stringify({ t: Date.now(), ...obj }) + `
+        writeSync(eventsFd, JSON.stringify(event) + `
 `);
       } catch {}
     };
+    appendTimelineEvent(createRunStartEvent(runOptions.name));
     let textLogged = false;
     let currentTool = "";
+    let currentToolCallId = "";
+    let killFn;
+    const sigtermHandler = () => killFn?.();
+    process.once("SIGTERM", sigtermHandler);
     try {
       const result = await runner.run(runOptions, (delta) => {
         const toolMatch = delta.match(/⚙ (.+?)…/);
@@ -18803,21 +19095,29 @@ class Supervisor {
           last_event_at_ms: now,
           elapsed_s: Math.round((now - startedAtMs) / 1000)
         });
-        if (LOGGED_EVENTS.has(eventType)) {
-          const tool = eventType === "toolcall" || eventType === "tool_execution_end" ? currentTool : undefined;
-          appendEvent({ type: eventType, ...tool ? { tool } : {} });
+        const timelineEvent = mapCallbackEventToTimelineEvent(eventType, {
+          tool: currentTool,
+          toolCallId: currentToolCallId || undefined
+        });
+        if (timelineEvent) {
+          appendTimelineEvent(timelineEvent);
         } else if (eventType === "text" && !textLogged) {
           textLogged = true;
-          appendEvent({ type: "text" });
+          appendTimelineEvent({ t: Date.now(), type: TIMELINE_EVENT_TYPES.TEXT });
         }
       }, (meta) => {
         this.updateStatus(id, { model: meta.model, backend: meta.backend });
-        appendEvent({ type: "meta", model: meta.model, backend: meta.backend });
-      }, (_killFn) => {}, (beadId) => {
+        appendTimelineEvent(createMetaEvent(meta.model, meta.backend));
+      }, (fn) => {
+        killFn = fn;
+      }, (beadId) => {
         this.updateStatus(id, { bead_id: beadId });
       });
       const elapsed = Math.round((Date.now() - startedAtMs) / 1000);
       writeFileSync3(this.resultPath(id), result.output, "utf-8");
+      if (result.beadId) {
+        this.opts.beadsClient?.updateBeadNotes(result.beadId, formatBeadNotes(result));
+      }
       this.updateStatus(id, {
         status: "done",
         elapsed_s: elapsed,
@@ -18826,27 +19126,35 @@ class Supervisor {
         backend: result.backend,
         bead_id: result.beadId
       });
-      appendEvent({ type: "agent_end", elapsed_s: elapsed });
-      writeFileSync3(join6(this.readyDir(), id), "", "utf-8");
+      appendTimelineEvent(createRunCompleteEvent("COMPLETE", elapsed, {
+        model: result.model,
+        backend: result.backend,
+        bead_id: result.beadId
+      }));
+      writeFileSync3(join7(this.readyDir(), id), "", "utf-8");
       return id;
     } catch (err) {
       const elapsed = Math.round((Date.now() - startedAtMs) / 1000);
+      const errorMsg = err?.message ?? String(err);
       this.updateStatus(id, {
         status: "error",
         elapsed_s: elapsed,
-        error: err?.message ?? String(err)
+        error: errorMsg
       });
-      appendEvent({ type: "error", message: err?.message ?? String(err) });
+      appendTimelineEvent(createRunCompleteEvent("ERROR", elapsed, {
+        error: errorMsg
+      }));
       throw err;
     } finally {
+      process.removeListener("SIGTERM", sigtermHandler);
       closeSync(eventsFd);
     }
   }
 }
-var JOB_TTL_DAYS, LOGGED_EVENTS;
+var JOB_TTL_DAYS;
 var init_supervisor = __esm(() => {
+  init_timeline_events();
   JOB_TTL_DAYS = Number(process.env.SPECIALISTS_JOB_TTL_DAYS ?? 7);
-  LOGGED_EVENTS = new Set(["thinking", "toolcall", "tool_execution_end", "done"]);
 });
 
 // src/cli/run.ts
@@ -18854,27 +19162,37 @@ var exports_run = {};
 __export(exports_run, {
   run: () => run7
 });
-import { join as join7 } from "node:path";
+import { join as join8 } from "node:path";
 async function parseArgs4(argv) {
   const name = argv[0];
   if (!name || name.startsWith("--")) {
-    console.error('Usage: specialists run <name> [--prompt "..."] [--model <model>] [--no-beads] [--background]');
+    console.error('Usage: specialists run <name> [--prompt "..."] [--bead <id>] [--context-depth <n>] [--model <model>] [--no-beads] [--background]');
     process.exit(1);
   }
   let prompt = "";
+  let beadId;
   let model;
   let noBeads = false;
   let background = false;
+  let contextDepth = 1;
   for (let i = 1;i < argv.length; i++) {
     const token = argv[i];
     if (token === "--prompt" && argv[i + 1]) {
       prompt = argv[++i];
       continue;
     }
+    if (token === "--bead" && argv[i + 1]) {
+      beadId = argv[++i];
+      continue;
+    }
     if (token === "--model" && argv[i + 1]) {
       model = argv[++i];
       continue;
     }
+    if (token === "--context-depth" && argv[i + 1]) {
+      contextDepth = parseInt(argv[++i], 10) || 0;
+      continue;
+    }
     if (token === "--no-beads") {
       noBeads = true;
       continue;
@@ -18884,10 +19202,11 @@ async function parseArgs4(argv) {
       continue;
     }
   }
-  if (!prompt) {
-    if (process.stdin.isTTY) {
-      process.stderr.write(dim5("Prompt (Ctrl+D when done): "));
-    }
+  if (prompt && beadId) {
+    console.error("Error: use either --prompt or --bead, not both.");
+    process.exit(1);
+  }
+  if (!prompt && !beadId && !process.stdin.isTTY) {
     prompt = await new Promise((resolve) => {
       let buf = "";
       process.stdin.setEncoding("utf-8");
@@ -18897,26 +19216,58 @@ async function parseArgs4(argv) {
       process.stdin.on("end", () => resolve(buf.trim()));
     });
   }
-  return { name, prompt, model, noBeads, background };
+  if (!prompt && !beadId) {
+    console.error("Error: provide --prompt, pipe stdin, or use --bead <id>.");
+    process.exit(1);
+  }
+  return { name, prompt, beadId, model, noBeads, background, contextDepth };
 }
 async function run7() {
   const args = await parseArgs4(process.argv.slice(3));
   const loader = new SpecialistLoader;
   const circuitBreaker = new CircuitBreaker;
-  const hooks = new HookEmitter({ tracePath: join7(process.cwd(), ".specialists", "trace.jsonl") });
-  const beadsClient = args.noBeads ? null : new BeadsClient;
+  const hooks = new HookEmitter({ tracePath: join8(process.cwd(), ".specialists", "trace.jsonl") });
+  const beadsClient = args.noBeads ? undefined : new BeadsClient;
+  const beadReader = beadsClient ?? new BeadsClient;
+  let prompt = args.prompt;
+  let variables;
+  if (args.beadId) {
+    const bead = beadReader.readBead(args.beadId);
+    if (!bead) {
+      throw new Error(`Unable to read bead '${args.beadId}' via bd show --json`);
+    }
+    const blockers = args.contextDepth > 0 ? beadReader.getCompletedBlockers(args.beadId, args.contextDepth) : [];
+    if (blockers.length > 0) {
+      process.stderr.write(dim5(`
+[context: ${blockers.length} completed dep${blockers.length > 1 ? "s" : ""} injected]
+`));
+    }
+    const beadContext = buildBeadContext(bead, blockers);
+    prompt = beadContext;
+    variables = {
+      bead_context: beadContext,
+      bead_id: args.beadId
+    };
+  }
   const runner = new SpecialistRunner({
     loader,
     hooks,
     circuitBreaker,
-    beadsClient: beadsClient ?? undefined
+    beadsClient
   });
   if (args.background) {
-    const jobsDir = join7(process.cwd(), ".specialists", "jobs");
+    const jobsDir = join8(process.cwd(), ".specialists", "jobs");
     const supervisor = new Supervisor({
       runner,
-      runOptions: { name: args.name, prompt: args.prompt, backendOverride: args.model },
-      jobsDir
+      runOptions: {
+        name: args.name,
+        prompt,
+        variables,
+        backendOverride: args.model,
+        inputBeadId: args.beadId
+      },
+      jobsDir,
+      beadsClient
     });
     try {
       const jobId = await supervisor.run();
@@ -18933,11 +19284,13 @@ async function run7() {
 ${bold5(`Running ${cyan3(args.name)}`)}
 
 `);
-  let beadId;
+  let trackingBeadId;
   const result = await runner.run({
     name: args.name,
-    prompt: args.prompt,
-    backendOverride: args.model
+    prompt,
+    variables,
+    backendOverride: args.model,
+    inputBeadId: args.beadId
   }, (delta) => process.stdout.write(delta), undefined, (meta) => process.stderr.write(dim5(`
 [${meta.backend} / ${meta.model}]
 
@@ -18950,10 +19303,10 @@ Interrupted.
       killFn();
       process.exit(130);
     });
-  }, (id) => {
-    beadId = id;
+  }, (beadId) => {
+    trackingBeadId = beadId;
     process.stderr.write(dim5(`
-[bead: ${id}]
+[bead: ${beadId}]
 `));
   });
   if (result.output && !result.output.endsWith(`
@@ -18961,8 +19314,9 @@ Interrupted.
     process.stdout.write(`
 `);
   const secs = (result.durationMs / 1000).toFixed(1);
+  const effectiveBeadId = args.beadId ?? trackingBeadId;
   const footer = [
-    beadId ? `bead ${beadId}` : "",
+    effectiveBeadId ? `bead ${effectiveBeadId}` : "",
     `${secs}s`,
     dim5(result.model)
   ].filter(Boolean).join("  ");
@@ -18980,14 +19334,103 @@ var init_run = __esm(() => {
   init_supervisor();
 });
 
+// src/cli/format-helpers.ts
+function formatTime(t) {
+  return new Date(t).toISOString().slice(11, 19);
+}
+function formatElapsed(seconds) {
+  if (seconds < 60)
+    return `${seconds}s`;
+  const m = Math.floor(seconds / 60);
+  const s = seconds % 60;
+  return s > 0 ? `${m}m ${s}s` : `${m}m`;
+}
+function getEventLabel(type) {
+  return EVENT_LABELS[type] ?? type.slice(0, 5).toUpperCase();
+}
+
+class JobColorMap {
+  colors = new Map;
+  nextIdx = 0;
+  getColor(jobId) {
+    let color = this.colors.get(jobId);
+    if (!color) {
+      color = JOB_COLORS[this.nextIdx % JOB_COLORS.length];
+      this.colors.set(jobId, color);
+      this.nextIdx++;
+    }
+    return color;
+  }
+  get(jobId) {
+    return this.getColor(jobId);
+  }
+  has(jobId) {
+    return this.colors.has(jobId);
+  }
+  get size() {
+    return this.colors.size;
+  }
+}
+function formatEventLine(event, options) {
+  const ts = dim6(formatTime(event.t));
+  const label = options.colorize(bold6(getEventLabel(event.type).padEnd(5)));
+  const prefix = `${options.colorize(`[${options.jobId}]`)} ${options.specialist}${options.beadId ? ` ${dim6(`[${options.beadId}]`)}` : ""}`;
+  const detailParts = [];
+  if (event.type === "meta") {
+    detailParts.push(`model=${event.model}`);
+    detailParts.push(`backend=${event.backend}`);
+  } else if (event.type === "tool") {
+    detailParts.push(`tool=${event.tool}`);
+    detailParts.push(`phase=${event.phase}`);
+    if (event.phase === "end") {
+      detailParts.push(`ok=${event.is_error ? "false" : "true"}`);
+    }
+  } else if (event.type === "run_complete") {
+    detailParts.push(`status=${event.status}`);
+    detailParts.push(`elapsed=${formatElapsed(event.elapsed_s)}`);
+    if (event.error) {
+      detailParts.push(`error=${event.error}`);
+    }
+  } else if (event.type === "done" || event.type === "agent_end") {
+    detailParts.push("status=COMPLETE");
+    detailParts.push(`elapsed=${formatElapsed(event.elapsed_s ?? 0)}`);
+  } else if (event.type === "run_start") {
+    detailParts.push(`specialist=${event.specialist}`);
+    if (event.bead_id) {
+      detailParts.push(`bead=${event.bead_id}`);
+    }
+  } else if (event.type === "text") {
+    detailParts.push("kind=assistant");
+  } else if (event.type === "thinking") {
+    detailParts.push("kind=model");
+  }
+  const detail = detailParts.length > 0 ? dim6(detailParts.join(" ")) : "";
+  return `${ts} ${prefix}  ${label}${detail ? ` ${detail}` : ""}`.trimEnd();
+}
+var dim6 = (s) => `\x1B[2m${s}\x1B[0m`, bold6 = (s) => `\x1B[1m${s}\x1B[0m`, cyan4 = (s) => `\x1B[36m${s}\x1B[0m`, yellow5 = (s) => `\x1B[33m${s}\x1B[0m`, red = (s) => `\x1B[31m${s}\x1B[0m`, green5 = (s) => `\x1B[32m${s}\x1B[0m`, blue = (s) => `\x1B[34m${s}\x1B[0m`, magenta = (s) => `\x1B[35m${s}\x1B[0m`, JOB_COLORS, EVENT_LABELS;
+var init_format_helpers = __esm(() => {
+  JOB_COLORS = [cyan4, yellow5, magenta, green5, blue, red];
+  EVENT_LABELS = {
+    run_start: "START",
+    meta: "META",
+    thinking: "THINK",
+    tool: "TOOL",
+    text: "TEXT",
+    run_complete: "DONE",
+    done: "DONE",
+    agent_end: "DONE",
+    error: "ERR"
+  };
+});
+
 // src/cli/status.ts
 var exports_status = {};
 __export(exports_status, {
   run: () => run8
 });
-import { spawnSync as spawnSync4 } from "node:child_process";
-import { existsSync as existsSync5 } from "node:fs";
-import { join as join8 } from "node:path";
+import { spawnSync as spawnSync5 } from "node:child_process";
+import { existsSync as existsSync6 } from "node:fs";
+import { join as join9 } from "node:path";
 function ok2(msg) {
   console.log(`  ${green5("✓")} ${msg}`);
 }
@@ -18995,7 +19438,7 @@ function warn(msg) {
   console.log(`  ${yellow5("○")} ${msg}`);
 }
 function fail(msg) {
-  console.log(`  ${red("✗")} ${msg}`);
+  console.log(`  ${red2("✗")} ${msg}`);
 }
 function info(msg) {
   console.log(`  ${dim6(msg)}`);
@@ -19006,7 +19449,7 @@ function section(label) {
 ${bold6(`── ${label} ${line}`)}`);
 }
 function cmd(bin, args) {
-  const r = spawnSync4(bin, args, {
+  const r = spawnSync5(bin, args, {
     encoding: "utf8",
     stdio: "pipe",
     timeout: 5000
@@ -19014,9 +19457,9 @@ function cmd(bin, args) {
   return { ok: r.status === 0 && !r.error, stdout: (r.stdout ?? "").trim() };
 }
 function isInstalled(bin) {
-  return spawnSync4("which", [bin], { encoding: "utf8", timeout: 2000 }).status === 0;
+  return spawnSync5("which", [bin], { encoding: "utf8", timeout: 2000 }).status === 0;
 }
-function formatElapsed(s) {
+function formatElapsed2(s) {
   if (s.elapsed_s === undefined)
     return "...";
   const m = Math.floor(s.elapsed_s / 60);
@@ -19026,11 +19469,11 @@ function formatElapsed(s) {
 function statusColor(status) {
   switch (status) {
     case "running":
-      return cyan4(status);
+      return cyan5(status);
     case "done":
       return green5(status);
     case "error":
-      return red(status);
+      return red2(status);
     case "starting":
       return yellow5(status);
     default:
@@ -19038,56 +19481,113 @@ 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 = existsSync6(join9(process.cwd(), ".beads"));
+  const specialistsBin = cmd("which", ["specialists"]);
+  const jobsDir = join9(process.cwd(), ".specialists", "jobs");
+  let jobs = [];
+  if (existsSync6(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)}`);
+        warn(`${s.name}  ${red2("AGED")}  ${dim6(s.scope)}`);
       } else if (staleness === "STALE") {
         warn(`${s.name}  ${yellow5("STALE")}  ${dim6(s.scope)}`);
       }
     }
   }
   section("pi  (coding agent runtime)");
-  if (!isInstalled("pi")) {
-    fail(`pi not installed — run ${yellow5("specialists install")}`);
+  if (!piInstalled) {
+    fail(`pi not installed — install ${yellow5("pi")} first`);
   } 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")) {
-    fail(`bd not installed — run ${yellow5("specialists install")}`);
+  if (!bdInstalled) {
+    fail(`bd not installed — install ${yellow5("bd")} first`);
   } 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,29 +19595,21 @@ ${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 = formatElapsed2(job);
+      const detail = job.status === "error" ? red2(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();
 }
-var bold6 = (s) => `\x1B[1m${s}\x1B[0m`, dim6 = (s) => `\x1B[2m${s}\x1B[0m`, green5 = (s) => `\x1B[32m${s}\x1B[0m`, yellow5 = (s) => `\x1B[33m${s}\x1B[0m`, red = (s) => `\x1B[31m${s}\x1B[0m`, cyan4 = (s) => `\x1B[36m${s}\x1B[0m`;
+var red2 = (s) => `\x1B[31m${s}\x1B[0m`, cyan5 = (s) => `\x1B[36m${s}\x1B[0m`;
 var init_status = __esm(() => {
   init_loader();
   init_supervisor();
+  init_format_helpers();
 });
 
 // src/cli/result.ts
@@ -19125,15 +19617,15 @@ var exports_result = {};
 __export(exports_result, {
   run: () => run9
 });
-import { existsSync as existsSync6, readFileSync as readFileSync4 } from "node:fs";
-import { join as join9 } from "node:path";
+import { existsSync as existsSync7, readFileSync as readFileSync4 } from "node:fs";
+import { join as join10 } from "node:path";
 async function run9() {
   const jobId = process.argv[3];
   if (!jobId) {
     console.error("Usage: specialists result <job-id>");
     process.exit(1);
   }
-  const jobsDir = join9(process.cwd(), ".specialists", "jobs");
+  const jobsDir = join10(process.cwd(), ".specialists", "jobs");
   const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
   const status = supervisor.readStatus(jobId);
   if (!status) {
@@ -19146,107 +19638,340 @@ async function run9() {
     process.exit(1);
   }
   if (status.status === "error") {
-    process.stderr.write(`${red2(`Job ${jobId} failed:`)} ${status.error ?? "unknown error"}
+    process.stderr.write(`${red3(`Job ${jobId} failed:`)} ${status.error ?? "unknown error"}
 `);
     process.exit(1);
   }
-  const resultPath = join9(jobsDir, jobId, "result.txt");
-  if (!existsSync6(resultPath)) {
+  const resultPath = join10(jobsDir, jobId, "result.txt");
+  if (!existsSync7(resultPath)) {
     console.error(`Result file not found for job ${jobId}`);
     process.exit(1);
   }
   process.stdout.write(readFileSync4(resultPath, "utf-8"));
 }
-var dim7 = (s) => `\x1B[2m${s}\x1B[0m`, red2 = (s) => `\x1B[31m${s}\x1B[0m`;
+var dim7 = (s) => `\x1B[2m${s}\x1B[0m`, red3 = (s) => `\x1B[31m${s}\x1B[0m`;
 var init_result = __esm(() => {
   init_supervisor();
 });
 
+// src/specialist/timeline-query.ts
+import { existsSync as existsSync8, readdirSync as readdirSync2, readFileSync as readFileSync5 } from "node:fs";
+import { join as join11 } from "node:path";
+function readJobEvents(jobDir) {
+  const eventsPath = join11(jobDir, "events.jsonl");
+  if (!existsSync8(eventsPath))
+    return [];
+  const content = readFileSync5(eventsPath, "utf-8");
+  const lines = content.split(`
+`).filter(Boolean);
+  const events = [];
+  for (const line of lines) {
+    const event = parseTimelineEvent(line);
+    if (event)
+      events.push(event);
+  }
+  events.sort(compareTimelineEvents);
+  return events;
+}
+function readAllJobEvents(jobsDir) {
+  if (!existsSync8(jobsDir))
+    return [];
+  const batches = [];
+  const entries = readdirSync2(jobsDir);
+  for (const entry of entries) {
+    const jobDir = join11(jobsDir, entry);
+    try {
+      const stat2 = __require("node:fs").statSync(jobDir);
+      if (!stat2.isDirectory())
+        continue;
+    } catch {
+      continue;
+    }
+    const jobId = entry;
+    const statusPath = join11(jobDir, "status.json");
+    let specialist = "unknown";
+    let beadId;
+    if (existsSync8(statusPath)) {
+      try {
+        const status = JSON.parse(readFileSync5(statusPath, "utf-8"));
+        specialist = status.specialist ?? "unknown";
+        beadId = status.bead_id;
+      } catch {}
+    }
+    const events = readJobEvents(jobDir);
+    if (events.length > 0) {
+      batches.push({ jobId, specialist, beadId, events });
+    }
+  }
+  return batches;
+}
+function mergeTimelineEvents(batches) {
+  const merged = [];
+  for (const batch of batches) {
+    for (const event of batch.events) {
+      merged.push({
+        jobId: batch.jobId,
+        specialist: batch.specialist,
+        beadId: batch.beadId,
+        event
+      });
+    }
+  }
+  merged.sort((a, b) => compareTimelineEvents(a.event, b.event));
+  return merged;
+}
+function filterTimelineEvents(merged, filter) {
+  let result = merged;
+  if (filter.since !== undefined) {
+    result = result.filter(({ event }) => event.t >= filter.since);
+  }
+  if (filter.jobId !== undefined) {
+    result = result.filter(({ jobId }) => jobId === filter.jobId);
+  }
+  if (filter.specialist !== undefined) {
+    result = result.filter(({ specialist }) => specialist === filter.specialist);
+  }
+  if (filter.limit !== undefined && filter.limit > 0) {
+    result = result.slice(0, filter.limit);
+  }
+  return result;
+}
+function queryTimeline(jobsDir, filter = {}) {
+  let batches = readAllJobEvents(jobsDir);
+  if (filter.jobId !== undefined) {
+    batches = batches.filter((b) => b.jobId === filter.jobId);
+  }
+  if (filter.specialist !== undefined) {
+    batches = batches.filter((b) => b.specialist === filter.specialist);
+  }
+  const merged = mergeTimelineEvents(batches);
+  return filterTimelineEvents(merged, filter);
+}
+var init_timeline_query = __esm(() => {
+  init_timeline_events();
+});
+
 // src/cli/feed.ts
 var exports_feed = {};
 __export(exports_feed, {
   run: () => run10
 });
-import { existsSync as existsSync7, readFileSync as readFileSync5, watchFile } from "node:fs";
-import { join as join10 } from "node:path";
-function formatEvent(line) {
-  try {
-    const e = JSON.parse(line);
-    const ts = new Date(e.t).toISOString().slice(11, 19);
-    const type = e.type ?? "?";
-    const extra = e.tool ? ` ${cyan5(e.tool)}` : e.model ? ` ${dim8(e.model)}` : e.message ? ` ${red3(e.message)}` : "";
-    return `${dim8(ts)}  ${type}${extra}`;
-  } catch {
-    return line;
+import { existsSync as existsSync9 } from "node:fs";
+import { join as join12 } from "node:path";
+function getHumanEventKey(event) {
+  switch (event.type) {
+    case "meta":
+      return `meta:${event.backend}:${event.model}`;
+    case "tool":
+      return `tool:${event.tool}:${event.phase}:${event.is_error ? "error" : "ok"}`;
+    case "text":
+      return "text";
+    case "thinking":
+      return "thinking";
+    case "run_start":
+      return `run_start:${event.specialist}:${event.bead_id ?? ""}`;
+    case "run_complete":
+      return `run_complete:${event.status}:${event.error ?? ""}`;
+    case "done":
+    case "agent_end":
+      return `complete:${event.type}`;
+    default:
+      return event.type;
   }
 }
-function printLines(content, from) {
-  const lines = content.split(`
-`).filter(Boolean);
-  for (let i = from;i < lines.length; i++) {
-    console.log(formatEvent(lines[i]));
+function shouldSkipHumanEvent(event, jobId, lastPrintedEventKey, seenMetaKey) {
+  if (event.type === "meta") {
+    const metaKey = `${event.backend}:${event.model}`;
+    if (seenMetaKey.get(jobId) === metaKey)
+      return true;
+    seenMetaKey.set(jobId, metaKey);
   }
-  return lines.length;
+  const key = getHumanEventKey(event);
+  if (lastPrintedEventKey.get(jobId) === key)
+    return true;
+  lastPrintedEventKey.set(jobId, key);
+  return false;
 }
-async function run10() {
-  const argv = process.argv.slice(3);
+function parseSince(value) {
+  if (value.includes("T") || value.includes("-")) {
+    return new Date(value).getTime();
+  }
+  const match = value.match(/^(\d+)([smhd])$/);
+  if (match) {
+    const num = parseInt(match[1], 10);
+    const unit = match[2];
+    const multipliers = { s: 1000, m: 60000, h: 3600000, d: 86400000 };
+    return Date.now() - num * multipliers[unit];
+  }
+  return;
+}
+function parseArgs5(argv) {
   let jobId;
+  let specialist;
+  let since;
+  let limit = 100;
   let follow = false;
+  let forever = false;
+  let json = false;
   for (let i = 0;i < argv.length; i++) {
     if (argv[i] === "--job" && argv[i + 1]) {
       jobId = argv[++i];
       continue;
     }
+    if (argv[i] === "--specialist" && argv[i + 1]) {
+      specialist = argv[++i];
+      continue;
+    }
+    if (argv[i] === "--since" && argv[i + 1]) {
+      since = parseSince(argv[++i]);
+      continue;
+    }
+    if (argv[i] === "--limit" && argv[i + 1]) {
+      limit = parseInt(argv[++i], 10);
+      continue;
+    }
     if (argv[i] === "--follow" || argv[i] === "-f") {
       follow = true;
       continue;
     }
+    if (argv[i] === "--forever") {
+      forever = true;
+      continue;
+    }
+    if (argv[i] === "--json") {
+      json = true;
+      continue;
+    }
     if (!jobId && !argv[i].startsWith("--"))
       jobId = argv[i];
   }
-  if (!jobId) {
-    console.error("Usage: specialists feed --job <job-id> [--follow]");
-    process.exit(1);
+  return { jobId, specialist, since, limit, follow, forever, json };
+}
+function printSnapshot(merged, options) {
+  if (merged.length === 0) {
+    if (!options.json)
+      console.log(dim6("No events found."));
+    return;
   }
-  const jobsDir = join10(process.cwd(), ".specialists", "jobs");
-  const eventsPath = join10(jobsDir, jobId, "events.jsonl");
-  if (!existsSync7(eventsPath)) {
-    const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
-    if (!supervisor.readStatus(jobId)) {
-      console.error(`No job found: ${jobId}`);
-      process.exit(1);
+  const colorMap = new JobColorMap;
+  if (options.json) {
+    for (const { jobId, specialist, beadId, event } of merged) {
+      console.log(JSON.stringify({ jobId, specialist, beadId, ...event }));
     }
-    console.log(dim8("No events yet."));
     return;
   }
-  const content = readFileSync5(eventsPath, "utf-8");
-  let linesRead = printLines(content, 0);
-  if (!follow)
-    return;
-  process.stderr.write(dim8(`Following ${jobId}... (Ctrl+C to stop)
-`));
+  const lastPrintedEventKey = new Map;
+  const seenMetaKey = new Map;
+  for (const { jobId, specialist, beadId, event } of merged) {
+    if (shouldSkipHumanEvent(event, jobId, lastPrintedEventKey, seenMetaKey))
+      continue;
+    const colorize = colorMap.get(jobId);
+    console.log(formatEventLine(event, { jobId, specialist, beadId, colorize }));
+  }
+}
+function isCompletionEvent(event) {
+  return isRunCompleteEvent(event) || event.type === "done" || event.type === "agent_end";
+}
+async function followMerged(jobsDir, options) {
+  const colorMap = new JobColorMap;
+  const lastSeenT = new Map;
+  const completedJobs = new Set;
+  const filteredBatches = () => readAllJobEvents(jobsDir).filter((batch) => !options.jobId || batch.jobId === options.jobId).filter((batch) => !options.specialist || batch.specialist === options.specialist);
+  const initial = queryTimeline(jobsDir, {
+    jobId: options.jobId,
+    specialist: options.specialist,
+    since: options.since,
+    limit: options.limit
+  });
+  printSnapshot(initial, { ...options, json: options.json });
+  for (const batch of filteredBatches()) {
+    if (batch.events.length > 0) {
+      const maxT = Math.max(...batch.events.map((event) => event.t));
+      lastSeenT.set(batch.jobId, maxT);
+    }
+    if (batch.events.some(isCompletionEvent)) {
+      completedJobs.add(batch.jobId);
+    }
+  }
+  const initialBatchCount = filteredBatches().length;
+  if (!options.forever && initialBatchCount > 0 && completedJobs.size === initialBatchCount) {
+    if (!options.json) {
+      process.stderr.write(dim6(`All jobs complete.
+`));
+    }
+    return;
+  }
+  if (!options.json) {
+    process.stderr.write(dim6(`Following... (Ctrl+C to stop)
+`));
+  }
+  const lastPrintedEventKey = new Map;
+  const seenMetaKey = new Map;
   await new Promise((resolve) => {
-    watchFile(eventsPath, { interval: 500 }, () => {
-      try {
-        const updated = readFileSync5(eventsPath, "utf-8");
-        linesRead = printLines(updated, linesRead);
-        const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
-        const status = supervisor.readStatus(jobId);
-        if (status && status.status !== "running" && status.status !== "starting") {
-          const finalMsg = status.status === "done" ? `
-${yellow6("Job complete.")} Run: specialists result ${jobId}` : `
-${red3(`Job ${status.status}.`)} ${status.error ?? ""}`;
-          process.stderr.write(finalMsg + `
-`);
-          resolve();
+    const interval = setInterval(() => {
+      const batches = filteredBatches();
+      const newEvents = [];
+      for (const batch of batches) {
+        const lastT = lastSeenT.get(batch.jobId) ?? 0;
+        for (const event of batch.events) {
+          if (event.t > lastT) {
+            newEvents.push({
+              jobId: batch.jobId,
+              specialist: batch.specialist,
+              beadId: batch.beadId,
+              event
+            });
+          }
         }
-      } catch {}
-    });
+        if (batch.events.length > 0) {
+          const maxT = Math.max(...batch.events.map((e) => e.t));
+          lastSeenT.set(batch.jobId, maxT);
+        }
+        if (batch.events.some(isCompletionEvent)) {
+          completedJobs.add(batch.jobId);
+        }
+      }
+      newEvents.sort((a, b) => a.event.t - b.event.t);
+      for (const { jobId, specialist, beadId, event } of newEvents) {
+        if (options.json) {
+          console.log(JSON.stringify({ jobId, specialist, beadId, ...event }));
+        } else {
+          if (shouldSkipHumanEvent(event, jobId, lastPrintedEventKey, seenMetaKey))
+            continue;
+          const colorize = colorMap.get(jobId);
+          console.log(formatEventLine(event, { jobId, specialist, beadId, colorize }));
+        }
+      }
+      if (!options.forever && batches.length > 0 && completedJobs.size === batches.length) {
+        clearInterval(interval);
+        resolve();
+      }
+    }, 500);
   });
 }
-var dim8 = (s) => `\x1B[2m${s}\x1B[0m`, cyan5 = (s) => `\x1B[36m${s}\x1B[0m`, yellow6 = (s) => `\x1B[33m${s}\x1B[0m`, red3 = (s) => `\x1B[31m${s}\x1B[0m`;
+async function run10() {
+  const options = parseArgs5(process.argv.slice(3));
+  const jobsDir = join12(process.cwd(), ".specialists", "jobs");
+  if (!existsSync9(jobsDir)) {
+    console.log(dim6("No jobs directory found."));
+    return;
+  }
+  if (options.follow) {
+    await followMerged(jobsDir, options);
+    return;
+  }
+  const merged = queryTimeline(jobsDir, {
+    jobId: options.jobId,
+    specialist: options.specialist,
+    since: options.since,
+    limit: options.limit
+  });
+  printSnapshot(merged, options);
+}
 var init_feed = __esm(() => {
-  init_supervisor();
+  init_timeline_events();
+  init_timeline_query();
+  init_format_helpers();
 });
 
 // src/cli/stop.ts
@@ -19254,14 +19979,14 @@ var exports_stop = {};
 __export(exports_stop, {
   run: () => run11
 });
-import { join as join11 } from "node:path";
+import { join as join13 } from "node:path";
 async function run11() {
   const jobId = process.argv[3];
   if (!jobId) {
     console.error("Usage: specialists stop <job-id>");
     process.exit(1);
   }
-  const jobsDir = join11(process.cwd(), ".specialists", "jobs");
+  const jobsDir = join13(process.cwd(), ".specialists", "jobs");
   const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
   const status = supervisor.readStatus(jobId);
   if (!status) {
@@ -19269,71 +19994,742 @@ async function run11() {
     process.exit(1);
   }
   if (status.status === "done" || status.status === "error") {
-    process.stderr.write(`${dim9(`Job ${jobId} is already ${status.status}.`)}
+    process.stderr.write(`${dim8(`Job ${jobId} is already ${status.status}.`)}
 `);
     return;
   }
   if (!status.pid) {
-    process.stderr.write(`${red4(`No PID recorded for job ${jobId}.`)}
+    process.stderr.write(`${red5(`No PID recorded for job ${jobId}.`)}
 `);
     process.exit(1);
   }
   try {
     process.kill(status.pid, "SIGTERM");
-    process.stdout.write(`${green6("✓")} Sent SIGTERM to PID ${status.pid} (job ${jobId})
+    process.stdout.write(`${green7("✓")} Sent SIGTERM to PID ${status.pid} (job ${jobId})
 `);
   } catch (err) {
     if (err.code === "ESRCH") {
-      process.stderr.write(`${red4(`Process ${status.pid} not found.`)} Job may have already completed.
+      process.stderr.write(`${red5(`Process ${status.pid} not found.`)} Job may have already completed.
 `);
     } else {
-      process.stderr.write(`${red4("Error:")} ${err.message}
+      process.stderr.write(`${red5("Error:")} ${err.message}
 `);
       process.exit(1);
     }
   }
 }
-var green6 = (s) => `\x1B[32m${s}\x1B[0m`, red4 = (s) => `\x1B[31m${s}\x1B[0m`, dim9 = (s) => `\x1B[2m${s}\x1B[0m`;
+var green7 = (s) => `\x1B[32m${s}\x1B[0m`, red5 = (s) => `\x1B[31m${s}\x1B[0m`, dim8 = (s) => `\x1B[2m${s}\x1B[0m`;
 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(cyan7(title))}
+${dim9(bar)}`;
+}
+function cmd2(s) {
+  return yellow6(s);
+}
+function flag(s) {
+  return green8(s);
+}
+async function run12() {
+  const lines = [
+    "",
+    bold7("specialists  ·  Quick Start Guide"),
+    dim9("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")}                       # project setup:`);
+  lines.push(`  ${dim9("                                            #   checks pi · bd · xt, then wires 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(`  ${dim9("specialists/")}       — put your .specialist.yaml files here`);
+  lines.push(`  ${dim9(".specialists/")}      — runtime data (jobs/, ready/) — gitignored`);
+  lines.push(`  ${dim9("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(`  ${blue2("project")}   ./specialists/*.specialist.yaml`);
+  lines.push(`  ${blue2("user")}      ~/.specialists/*.specialist.yaml`);
+  lines.push(`  ${blue2("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")} ${dim9('"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")} ${dim9('"..."')} ${flag("--background")}`);
+  lines.push(`  ${dim9("  # → Job started: job_a1b2c3d4")}`);
+  lines.push("");
+  lines.push(`  Override model for one run:`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--model")} ${dim9("anthropic/claude-opus-4-6")} ${flag("--prompt")} ${dim9('"..."')}`);
+  lines.push("");
+  lines.push(`  Run without beads issue tracking:`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--no-beads")} ${flag("--prompt")} ${dim9('"..."')}`);
+  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 ${dim9(".specialists/jobs/<job-id>/")}:`);
+  lines.push(`  ${dim9("status.json")}   — id, specialist, status, pid, started_at, elapsed_s, current_tool`);
+  lines.push(`  ${dim9("events.jsonl")} — one JSON event per line (tool_use, text, agent_end, error …)`);
+  lines.push(`  ${dim9("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")} ${dim9("anthropic/claude-sonnet-4-6")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--description")} ${dim9('"Updated description"')}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--timeout")} ${dim9("120000")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--permission")} ${dim9("HIGH")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--tags")} ${dim9("analysis,security,review")}`);
+  lines.push("");
+  lines.push(`  Preview without writing:`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--model")} ${dim9("...")} ${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(`  ${dim9(l)}`);
+  }
+  lines.push("");
+  lines.push(section2("8. Hook System"));
+  lines.push("");
+  lines.push(`  Specialists emits lifecycle events to ${dim9(".specialists/trace.jsonl")}:`);
+  lines.push("");
+  lines.push(`  ${bold7("Hook point")}              ${bold7("When fired")}`);
+  lines.push(`  ${yellow6("specialist:start")}       before the agent session begins`);
+  lines.push(`  ${yellow6("specialist:token")}       on each streamed token (delta)`);
+  lines.push(`  ${yellow6("specialist:done")}        after successful completion`);
+  lines.push(`  ${yellow6("specialist:error")}       on failure or timeout`);
+  lines.push("");
+  lines.push(`  Each event line in trace.jsonl:`);
+  lines.push(`  ${dim9('{"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(dim9("─".repeat(62)));
+  lines.push(`  ${dim9("specialists help")}     command list         ${dim9("specialists <cmd> --help")}   per-command flags`);
+  lines.push(`  ${dim9("specialists status")}   health check         ${dim9("specialists models")}         available models`);
+  lines.push("");
+  console.log(lines.join(`
+`));
+}
+var bold7 = (s) => `\x1B[1m${s}\x1B[0m`, dim9 = (s) => `\x1B[2m${s}\x1B[0m`, yellow6 = (s) => `\x1B[33m${s}\x1B[0m`, cyan7 = (s) => `\x1B[36m${s}\x1B[0m`, blue2 = (s) => `\x1B[34m${s}\x1B[0m`, green8 = (s) => `\x1B[32m${s}\x1B[0m`;
+
+// src/cli/doctor.ts
+var exports_doctor = {};
+__export(exports_doctor, {
+  run: () => run13
+});
+import { spawnSync as spawnSync6 } from "node:child_process";
+import { existsSync as existsSync10, mkdirSync as mkdirSync3, readFileSync as readFileSync6, readdirSync as readdirSync3 } from "node:fs";
+import { join as join14 } from "node:path";
+function ok3(msg) {
+  console.log(`  ${green9("✓")} ${msg}`);
+}
+function warn2(msg) {
+  console.log(`  ${yellow7("○")} ${msg}`);
+}
+function fail2(msg) {
+  console.log(`  ${red6("✗")} ${msg}`);
+}
+function fix(msg) {
+  console.log(`    ${dim10("→ fix:")} ${yellow7(msg)}`);
+}
+function hint(msg) {
+  console.log(`    ${dim10(msg)}`);
+}
+function section3(label) {
+  const line = "─".repeat(Math.max(0, 38 - label.length));
+  console.log(`
+${bold8(`── ${label} ${line}`)}`);
+}
+function sp(bin, args) {
+  const r = spawnSync6(bin, args, { encoding: "utf8", stdio: "pipe", timeout: 5000 });
+  return { ok: r.status === 0 && !r.error, stdout: (r.stdout ?? "").trim() };
+}
+function isInstalled2(bin) {
+  return spawnSync6("which", [bin], { encoding: "utf8", timeout: 2000 }).status === 0;
+}
+function loadJson2(path) {
+  if (!existsSync10(path))
+    return null;
+  try {
+    return JSON.parse(readFileSync6(path, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function checkPi() {
+  section3("pi  (coding agent runtime)");
+  if (!isInstalled2("pi")) {
+    fail2("pi not installed");
+    fix("install pi first");
+    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  ${dim10(`(${[...providers].join(", ")})`)}`);
+  return true;
+}
+function checkBd() {
+  section3("beads  (issue tracker)");
+  if (!isInstalled2("bd")) {
+    fail2("bd not installed");
+    fix("install beads (bd) first");
+    return false;
+  }
+  ok3(`bd installed  ${dim10(sp("bd", ["--version"]).stdout || "")}`);
+  if (existsSync10(join14(CWD, ".beads")))
+    ok3(".beads/ present in project");
+  else
+    warn2(".beads/ not found in project");
+  return true;
+}
+function checkXt() {
+  section3("xtrm-tools");
+  if (!isInstalled2("xt")) {
+    fail2("xt not installed");
+    fix("install xtrm-tools first");
+    return false;
+  }
+  ok3(`xt installed  ${dim10(sp("xt", ["--version"]).stdout || "")}`);
+  return true;
+}
+function checkHooks() {
+  section3("Claude Code hooks  (2 expected)");
+  let allPresent = true;
+  for (const name of HOOK_NAMES) {
+    const dest = join14(HOOKS_DIR, name);
+    if (!existsSync10(dest)) {
+      fail2(`${name}  ${red6("missing")}`);
+      fix("specialists install");
+      allPresent = false;
+    } else {
+      ok3(name);
+    }
+  }
+  const settings = loadJson2(SETTINGS_FILE);
+  if (!settings) {
+    warn2(`Could not read ${SETTINGS_FILE}`);
+    fix("specialists install");
+    return false;
+  }
+  const hooks = settings.hooks ?? {};
+  const wiredCommands = new Set([
+    ...hooks.UserPromptSubmit ?? [],
+    ...hooks.SessionStart ?? []
+  ].flatMap((entry) => (entry.hooks ?? []).map((h) => h.command ?? "")));
+  for (const name of HOOK_NAMES) {
+    const expected = join14(HOOKS_DIR, name);
+    if (!wiredCommands.has(expected)) {
+      warn2(`${name} not wired in settings.json`);
+      fix("specialists install");
+      allPresent = false;
+    }
+  }
+  if (allPresent)
+    hint(`Hooks wired in ${SETTINGS_FILE}`);
+  return allPresent;
+}
+function checkMCP() {
+  section3("MCP registration");
+  const mcp = loadJson2(MCP_FILE2);
+  const spec = mcp?.mcpServers?.specialists;
+  if (!spec || spec.command !== "specialists") {
+    fail2(`MCP server 'specialists' not registered in .mcp.json`);
+    fix("specialists install");
+    return false;
+  }
+  ok3(`MCP server 'specialists' registered in ${MCP_FILE2}`);
+  return true;
+}
+function checkRuntimeDirs() {
+  section3(".specialists/ runtime directories");
+  const rootDir = join14(CWD, ".specialists");
+  const jobsDir = join14(rootDir, "jobs");
+  const readyDir = join14(rootDir, "ready");
+  let allOk = true;
+  if (!existsSync10(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 (!existsSync10(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 = join14(CWD, ".specialists", "jobs");
+  if (!existsSync10(jobsDir)) {
+    hint("No .specialists/jobs/ — skipping");
+    return true;
+  }
+  let entries;
+  try {
+    entries = readdirSync3(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 = join14(jobsDir, jobId, "status.json");
+    if (!existsSync10(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}  ${yellow7("ZOMBIE")}  ${dim10(`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 bdOk = checkBd();
+  const xtOk = checkXt();
+  const hooksOk = checkHooks();
+  const mcpOk = checkMCP();
+  const dirsOk = checkRuntimeDirs();
+  const jobsOk = checkZombieJobs();
+  const allOk = piOk && bdOk && xtOk && hooksOk && mcpOk && dirsOk && jobsOk;
+  console.log("");
+  if (allOk) {
+    console.log(`  ${green9("✓")} ${bold8("All checks passed")}  — specialists is healthy`);
+  } else {
+    console.log(`  ${yellow7("○")} ${bold8("Some checks failed")}  — follow the fix hints above`);
+    console.log(`  ${dim10("specialists install fixes hook + MCP registration; pi, bd, and xt must be installed separately.")}`);
+  }
+  console.log("");
+}
+var bold8 = (s) => `\x1B[1m${s}\x1B[0m`, dim10 = (s) => `\x1B[2m${s}\x1B[0m`, green9 = (s) => `\x1B[32m${s}\x1B[0m`, yellow7 = (s) => `\x1B[33m${s}\x1B[0m`, red6 = (s) => `\x1B[31m${s}\x1B[0m`, CWD, CLAUDE_DIR, HOOKS_DIR, SETTINGS_FILE, MCP_FILE2, HOOK_NAMES;
+var init_doctor = __esm(() => {
+  CWD = process.cwd();
+  CLAUDE_DIR = join14(CWD, ".claude");
+  HOOKS_DIR = join14(CLAUDE_DIR, "hooks");
+  SETTINGS_FILE = join14(CLAUDE_DIR, "settings.json");
+  MCP_FILE2 = join14(CWD, ".mcp.json");
+  HOOK_NAMES = [
+    "specialists-complete.mjs",
+    "specialists-session-start.mjs"
+  ];
+});
+
+// src/cli/setup.ts
+var exports_setup = {};
+__export(exports_setup, {
+  run: () => run14
+});
+import { existsSync as existsSync11, readFileSync as readFileSync7, writeFileSync as writeFileSync4 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { join as join15, resolve } from "node:path";
+function ok4(msg) {
+  console.log(`  ${green10("✓")} ${msg}`);
+}
+function skip2(msg) {
+  console.log(`  ${yellow8("○")} ${msg}`);
+}
+function resolveTarget(target) {
+  switch (target) {
+    case "global":
+      return join15(homedir3(), ".claude", "CLAUDE.md");
+    case "agents":
+      return join15(process.cwd(), "AGENTS.md");
+    case "project":
+    default:
+      return join15(process.cwd(), "CLAUDE.md");
+  }
+}
+function parseArgs6() {
+  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 } = parseArgs6();
+  const filePath = resolve(resolveTarget(target));
+  const label = target === "global" ? "~/.claude/CLAUDE.md" : filePath.replace(process.cwd() + "/", "");
+  console.log(`
+${bold9("specialists setup")}
+`);
+  console.log(`  Target: ${yellow8(label)}${dryRun ? dim11("  (dry-run)") : ""}
+`);
+  if (existsSync11(filePath)) {
+    const existing = readFileSync7(filePath, "utf8");
+    if (existing.includes(MARKER)) {
+      skip2(`${label} already contains Specialists Workflow section`);
+      console.log(`
+  ${dim11("To force-update, remove the ## Specialists Workflow section and re-run.")}
+`);
+      return;
+    }
+    if (dryRun) {
+      console.log(dim11("─".repeat(60)));
+      console.log(dim11("Would append to existing file:"));
+      console.log("");
+      console.log(WORKFLOW_BLOCK);
+      console.log(dim11("─".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(dim11("─".repeat(60)));
+      console.log(dim11(`Would create ${label}:`));
+      console.log("");
+      console.log(WORKFLOW_BLOCK);
+      console.log(dim11("─".repeat(60)));
+      return;
+    }
+    writeFileSync4(filePath, WORKFLOW_BLOCK, "utf8");
+    ok4(`Created ${label} with Specialists Workflow section`);
+  }
+  console.log("");
+  console.log(`  ${dim11("Next steps:")}`);
+  console.log(`  • Restart Claude Code to pick up the new context`);
+  console.log(`  • Run ${yellow8("specialists list")} to see available specialists`);
+  console.log(`  • Run ${yellow8("specialist_init")} in a new session to bootstrap context`);
+  console.log("");
+}
+var bold9 = (s) => `\x1B[1m${s}\x1B[0m`, dim11 = (s) => `\x1B[2m${s}\x1B[0m`, green10 = (s) => `\x1B[32m${s}\x1B[0m`, yellow8 = (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 formatCommands(entries) {
+  const width = Math.max(...entries.map(([cmd3]) => cmd3.length));
+  return entries.map(([cmd3, desc]) => `  ${cmd3.padEnd(width)}   ${desc}`);
+}
+async function run15() {
   const lines = [
     "",
-    bold7("specialists <command>"),
+    "Specialists lets you run project-scoped specialist agents with a bead-first workflow.",
+    "",
+    bold10("Usage:"),
+    "  specialists [command]",
+    "  specialists [command] --help",
+    "",
+    bold10("Common flows:"),
+    "",
+    "  Tracked work (primary)",
+    '    bd create "Task title" -t task -p 1 --json',
+    "    specialists run <name> --bead <id> [--context-depth N] [--background]",
+    "    specialists feed -f",
+    '    bd close <id> --reason "Done"',
+    "",
+    "  Ad-hoc work",
+    '    specialists run <name> --prompt "..."',
+    "",
+    "  Rules",
+    "    --bead is for tracked work",
+    "    --prompt is for quick untracked work",
+    "    --context-depth defaults to 1 with --bead",
+    "    --no-beads does not disable bead reading",
+    "",
+    bold10("Core commands:"),
+    ...formatCommands(CORE_COMMANDS),
+    "",
+    bold10("Extended commands:"),
+    ...formatCommands(EXTENDED_COMMANDS),
+    "",
+    bold10("xtrm worktree commands:"),
+    ...formatCommands(WORKTREE_COMMANDS),
     "",
-    "Commands:",
-    ...COMMANDS.map(([cmd2, desc]) => `  ${cmd2.padEnd(COL_WIDTH)}    ${dim10(desc)}`),
+    bold10("Examples:"),
+    "  specialists init",
+    "  specialists list",
+    "  specialists run bug-hunt --bead unitAI-123 --background",
+    '  specialists run codebase-explorer --prompt "Map the CLI architecture"',
+    "  specialists feed -f",
+    "  specialists result <job-id>",
     "",
-    dim10("Run 'specialists <command> --help' for command-specific options."),
+    bold10("More help:"),
+    "  specialists quickstart      Full guide and workflow reference",
+    "  specialists run --help      Run command details and flags",
+    "  specialists init --help     Bootstrap behavior and workflow injection",
+    "  specialists feed --help     Background job monitoring details",
+    "",
+    dim12("Project model: specialists are project-only; user-scope discovery is deprecated."),
     ""
   ];
   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`, dim12 = (s) => `\x1B[2m${s}\x1B[0m`, CORE_COMMANDS, EXTENDED_COMMANDS, WORKTREE_COMMANDS;
 var init_help = __esm(() => {
-  COMMANDS = [
-    ["install", "Full-stack installer: pi, beads, dolt, MCP registration, hooks"],
-    ["list", "List available specialists with model and description"],
-    ["models", "List models available on pi, flagged with thinking/images support"],
+  CORE_COMMANDS = [
+    ["init", "Bootstrap a project: dirs, workflow injection, project MCP registration"],
+    ["list", "List specialists in this project"],
+    ["run", "Run a specialist with --bead for tracked work or --prompt for ad-hoc work"],
+    ["feed", "Tail job events; use -f to follow all jobs"],
+    ["result", "Print final output of a completed background job"],
+    ["stop", "Stop a running background job"],
+    ["status", "Show health, MCP state, and active jobs"],
+    ["doctor", "Diagnose installation/runtime problems"],
+    ["quickstart", "Full getting-started guide"],
+    ["help", "Show this help"]
+  ];
+  EXTENDED_COMMANDS = [
+    ["edit", "Edit a specialist field such as model or description"],
+    ["models", "List models available on pi"],
     ["version", "Print installed version"],
-    ["init", "Initialize specialists in the current project"],
-    ["edit", "Edit a specialist field  (e.g. --model, --description)"],
-    ["run", "Run a specialist with a prompt (--background for async)"],
-    ["result", "Print result of a background job"],
-    ["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)"],
-    ["help", "Show this help message"]
+    ["setup", "[deprecated] Use specialists init instead"],
+    ["install", "[deprecated] Use specialists init instead"]
+  ];
+  WORKTREE_COMMANDS = [
+    ["xt pi [name]", "Start a Pi session in a sandboxed xt worktree"],
+    ["xt claude [name]", "Start a Claude session in a sandboxed xt worktree"],
+    ["xt attach [slug]", "Resume an existing xt worktree session"],
+    ["xt worktree list", "List worktrees with runtime and activity"],
+    ["xt end", "Close session, push, PR, cleanup"]
   ];
-  COL_WIDTH = Math.max(...COMMANDS.map(([cmd2]) => cmd2.length));
 });
 
 // node_modules/zod/v4/core/core.js
@@ -25362,6 +26758,9 @@ class Protocol {
     }
   }
   async connect(transport) {
+    if (this._transport) {
+      throw new Error("Already connected to a transport. Call close() before connecting to a new transport, or use a separate Protocol instance per connection.");
+    }
     this._transport = transport;
     const _onclose = this.transport?.onclose;
     this._transport.onclose = () => {
@@ -25394,6 +26793,10 @@ class Protocol {
     this._progressHandlers.clear();
     this._taskProgressTokens.clear();
     this._pendingDebouncedNotifications.clear();
+    for (const controller of this._requestHandlerAbortControllers.values()) {
+      controller.abort();
+    }
+    this._requestHandlerAbortControllers.clear();
     const error2 = McpError.fromError(ErrorCode.ConnectionClosed, "Connection closed");
     this._transport = undefined;
     this.onclose?.();
@@ -25444,6 +26847,8 @@ class Protocol {
       sessionId: capturedTransport?.sessionId,
       _meta: request.params?._meta,
       sendNotification: async (notification) => {
+        if (abortController.signal.aborted)
+          return;
         const notificationOptions = { relatedRequestId: request.id };
         if (relatedTaskId) {
           notificationOptions.relatedTask = { taskId: relatedTaskId };
@@ -25451,6 +26856,9 @@ class Protocol {
         await this.notification(notification, notificationOptions);
       },
       sendRequest: async (r, resultSchema, options) => {
+        if (abortController.signal.aborted) {
+          throw new McpError(ErrorCode.ConnectionClosed, "Request was cancelled");
+        }
         const requestOptions = { ...options, relatedRequestId: request.id };
         if (relatedTaskId && !requestOptions.relatedTask) {
           requestOptions.relatedTask = { taskId: relatedTaskId };
@@ -26064,6 +27472,62 @@ class ExperimentalServerTasks {
   requestStream(request, resultSchema, options) {
     return this._server.requestStream(request, resultSchema, options);
   }
+  createMessageStream(params, options) {
+    const clientCapabilities = this._server.getClientCapabilities();
+    if ((params.tools || params.toolChoice) && !clientCapabilities?.sampling?.tools) {
+      throw new Error("Client does not support sampling tools capability.");
+    }
+    if (params.messages.length > 0) {
+      const lastMessage = params.messages[params.messages.length - 1];
+      const lastContent = Array.isArray(lastMessage.content) ? lastMessage.content : [lastMessage.content];
+      const hasToolResults = lastContent.some((c) => c.type === "tool_result");
+      const previousMessage = params.messages.length > 1 ? params.messages[params.messages.length - 2] : undefined;
+      const previousContent = previousMessage ? Array.isArray(previousMessage.content) ? previousMessage.content : [previousMessage.content] : [];
+      const hasPreviousToolUse = previousContent.some((c) => c.type === "tool_use");
+      if (hasToolResults) {
+        if (lastContent.some((c) => c.type !== "tool_result")) {
+          throw new Error("The last message must contain only tool_result content if any is present");
+        }
+        if (!hasPreviousToolUse) {
+          throw new Error("tool_result blocks are not matching any tool_use from the previous message");
+        }
+      }
+      if (hasPreviousToolUse) {
+        const toolUseIds = new Set(previousContent.filter((c) => c.type === "tool_use").map((c) => c.id));
+        const toolResultIds = new Set(lastContent.filter((c) => c.type === "tool_result").map((c) => c.toolUseId));
+        if (toolUseIds.size !== toolResultIds.size || ![...toolUseIds].every((id) => toolResultIds.has(id))) {
+          throw new Error("ids of tool_result blocks and tool_use blocks from previous message do not match");
+        }
+      }
+    }
+    return this.requestStream({
+      method: "sampling/createMessage",
+      params
+    }, CreateMessageResultSchema, options);
+  }
+  elicitInputStream(params, options) {
+    const clientCapabilities = this._server.getClientCapabilities();
+    const mode = params.mode ?? "form";
+    switch (mode) {
+      case "url": {
+        if (!clientCapabilities?.elicitation?.url) {
+          throw new Error("Client does not support url elicitation.");
+        }
+        break;
+      }
+      case "form": {
+        if (!clientCapabilities?.elicitation?.form) {
+          throw new Error("Client does not support form elicitation.");
+        }
+        break;
+      }
+    }
+    const normalizedParams = mode === "form" && params.mode === undefined ? { ...params, mode: "form" } : params;
+    return this.requestStream({
+      method: "elicitation/create",
+      params: normalizedParams
+    }, ElicitResultSchema, options);
+  }
   async getTask(taskId, options) {
     return this._server.getTask({ taskId }, options);
   }
@@ -26538,7 +28002,7 @@ class StdioServerTransport {
 }
 
 // src/server.ts
-import { join as join3 } from "node:path";
+import { join as join4 } from "node:path";
 
 // src/constants.ts
 var LOG_PREFIX = "[specialists]";
@@ -26627,25 +28091,49 @@ function createListSpecialistsTool(loader) {
 
 // src/tools/specialist/use_specialist.tool.ts
 init_zod();
+init_beads();
 var useSpecialistSchema = exports_external.object({
   name: exports_external.string().describe("Specialist identifier (e.g. codebase-explorer)"),
-  prompt: exports_external.string().describe("The task or question for the specialist"),
+  prompt: exports_external.string().optional().describe("The task or question for the specialist"),
+  bead_id: exports_external.string().optional().describe("Use an existing bead as the specialist prompt"),
   variables: exports_external.record(exports_external.string()).optional().describe("Additional $variable substitutions"),
   backend_override: exports_external.string().optional().describe("Force a specific backend (gemini, qwen, anthropic)"),
-  autonomy_level: exports_external.string().optional().describe("Override permission level for this invocation")
+  autonomy_level: exports_external.string().optional().describe("Override permission level for this invocation"),
+  context_depth: exports_external.number().optional().describe("Depth of blocker context injection (0 = none, 1 = immediate blockers, etc.)")
+}).refine((input) => Boolean(input.prompt?.trim() || input.bead_id), {
+  message: "Either prompt or bead_id is required",
+  path: ["prompt"]
 });
 function createUseSpecialistTool(runner) {
   return {
     name: "use_specialist",
-    description: "Run a specialist synchronously and wait for the result. " + "Full lifecycle: load → agents.md → pi session → output. " + "Response includes output, model, durationMs, and beadId (string | undefined). " + "beadId is set when the specialist's beads_integration policy triggered bead creation " + "(default: auto — creates for LOW/MEDIUM/HIGH permission, skips for READ_ONLY). " + "If beadId is present, use `bd update <beadId> --notes` to attach findings or " + "`bd remember` to persist key discoveries for future sessions.",
+    description: "Run a specialist synchronously and wait for the result. " + "Full lifecycle: load → agents.md → pi session → output. " + "Response includes output, model, durationMs, and beadId (string | undefined). " + "beadId is set when the specialist's beads_integration policy triggered bead creation " + "(default: auto — creates for LOW/MEDIUM/HIGH permission, skips for READ_ONLY). " + "If beadId is present, use `bd update <beadId> --notes` to attach findings or " + "`bd remember` to persist key discoveries for future sessions. " + "When bead_id is provided, the source bead becomes the specialist prompt and the tracking bead links back to it. " + "Use context_depth to inject outputs from completed blocking dependencies (depth 1 = immediate blockers, 2 = include their blockers too).",
     inputSchema: useSpecialistSchema,
     async execute(input, onProgress) {
+      let prompt = input.prompt?.trim() ?? "";
+      let variables = input.variables;
+      if (input.bead_id) {
+        const beadsClient = new BeadsClient;
+        const bead = beadsClient.readBead(input.bead_id);
+        if (!bead) {
+          throw new Error(`Unable to read bead '${input.bead_id}' via bd show --json`);
+        }
+        const blockers = input.context_depth && input.context_depth > 0 ? beadsClient.getBlockers(input.bead_id, input.context_depth) : [];
+        const beadContext = buildBeadContext(bead, { blockers, depth: input.context_depth ?? 0 });
+        prompt = beadContext;
+        variables = {
+          ...input.variables ?? {},
+          bead_context: beadContext,
+          bead_id: input.bead_id
+        };
+      }
       return runner.run({
         name: input.name,
-        prompt: input.prompt,
-        variables: input.variables,
+        prompt,
+        variables,
         backendOverride: input.backend_override,
-        autonomyLevel: input.autonomy_level
+        autonomyLevel: input.autonomy_level,
+        inputBeadId: input.bead_id
       }, onProgress);
     }
   };
@@ -26751,14 +28239,14 @@ function createSpecialistStatusTool(loader, circuitBreaker) {
     async execute(_) {
       const list = await loader.list();
       const stalenessResults = await Promise.all(list.map((s) => checkStaleness(s)));
-      const { existsSync: existsSync2, readdirSync, readFileSync } = await import("node:fs");
-      const { join: join2 } = await import("node:path");
-      const jobsDir = join2(process.cwd(), ".specialists", "jobs");
+      const { existsSync: existsSync3, readdirSync, readFileSync } = await import("node:fs");
+      const { join: join3 } = await import("node:path");
+      const jobsDir = join3(process.cwd(), ".specialists", "jobs");
       const jobs = [];
-      if (existsSync2(jobsDir)) {
+      if (existsSync3(jobsDir)) {
         for (const entry of readdirSync(jobsDir)) {
-          const statusPath = join2(jobsDir, entry, "status.json");
-          if (!existsSync2(statusPath))
+          const statusPath = join3(jobsDir, entry, "status.json");
+          if (!existsSync3(statusPath))
             continue;
           try {
             jobs.push(JSON.parse(readFileSync(statusPath, "utf-8")));
@@ -26970,13 +28458,13 @@ init_zod();
 // src/tools/specialist/specialist_init.tool.ts
 init_zod();
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync2 } from "node:fs";
-import { join as join2 } from "node:path";
+import { existsSync as existsSync3 } from "node:fs";
+import { join as join3 } from "node:path";
 var specialistInitSchema = objectType({});
 function createSpecialistInitTool(loader, deps) {
   const resolved = deps ?? {
     bdAvailable: () => spawnSync2("bd", ["--version"], { stdio: "ignore" }).status === 0,
-    beadsExists: () => existsSync2(join2(process.cwd(), ".beads")),
+    beadsExists: () => existsSync3(join3(process.cwd(), ".beads")),
     bdInit: () => spawnSync2("bd", ["init"], { stdio: "ignore" })
   };
   return {
@@ -27011,7 +28499,7 @@ class SpecialistsServer {
     const circuitBreaker = new CircuitBreaker;
     const loader = new SpecialistLoader;
     const hooks = new HookEmitter({
-      tracePath: join3(process.cwd(), ".specialists", "trace.jsonl")
+      tracePath: join4(process.cwd(), ".specialists", "trace.jsonl")
     });
     const beadsClient = new BeadsClient;
     const runner = new SpecialistRunner({ loader, hooks, circuitBreaker, beadsClient });
@@ -27107,8 +28595,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",
+        "",
+        "Project setup: checks pi/bd/xt prerequisites, registers the MCP server,",
+        "and installs specialists-specific project hooks.",
+        "",
+        "No flags — just run it.",
+        ""
+      ].join(`
+`));
+      return;
+    }
     const { run: handler } = await Promise.resolve().then(() => (init_install(), exports_install));
     return handler();
   }
@@ -27117,41 +28623,322 @@ async function run13() {
     return handler();
   }
   if (sub === "list") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists list [options]",
+        "",
+        "List specialists in the current project.",
+        "",
+        "What it shows:",
+        "  - specialist name",
+        "  - model",
+        "  - short description",
+        "",
+        "Options:",
+        "  --category <name>   Filter by category tag",
+        "  --json              Output as JSON array",
+        "",
+        "Examples:",
+        "  specialists list",
+        "  specialists list --category analysis",
+        "  specialists list --json",
+        "",
+        "Project model:",
+        "  Specialists are project-only. User-scope discovery is deprecated.",
+        ""
+      ].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 [--force-workflow]",
+        "",
+        "Bootstrap a project for specialists. This is the sole onboarding command.",
+        "",
+        "What it does:",
+        "  • creates specialists/ for project .specialist.yaml files",
+        "  • creates .specialists/ runtime dirs (jobs/, ready/)",
+        "  • adds .specialists/ to .gitignore",
+        "  • injects the managed workflow block into AGENTS.md and CLAUDE.md",
+        "  • registers the Specialists MCP server at project scope",
+        "",
+        "Options:",
+        "  --force-workflow   Overwrite existing managed workflow blocks",
+        "",
+        "Examples:",
+        "  specialists init",
+        "  specialists init --force-workflow",
+        "",
+        "Notes:",
+        "  setup and install are deprecated; use specialists init.",
+        "  Safe to run again; existing project state is preserved where possible.",
+        ""
+      ].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 in foreground or background.",
+        "",
+        "Primary modes:",
+        "  tracked:  specialists run <name> --bead <id>",
+        '  ad-hoc:   specialists run <name> --prompt "..."',
+        "",
+        "Options:",
+        "  --bead <id>          Use an existing bead as the prompt source",
+        "  --prompt <text>      Ad-hoc prompt for untracked work",
+        "  --context-depth <n>  Dependency context depth when using --bead (default: 1)",
+        "  --no-beads           Do not create a new tracking bead (does not disable bead reading)",
+        "  --background         Start async and return a job id",
+        "  --model <model>      Override the configured model for this run",
+        "",
+        "Examples:",
+        "  specialists run bug-hunt --bead unitAI-55d",
+        "  specialists run bug-hunt --bead unitAI-55d --context-depth 2 --background",
+        '  specialists run code-review --prompt "Audit src/api.ts"',
+        "  cat brief.md | specialists run report-generator",
+        "",
+        "Rules:",
+        "  Use --bead for tracked work.",
+        "  Use --prompt for quick ad-hoc work.",
+        ""
+      ].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 current runtime state.",
+        "",
+        "Sections include:",
+        "  - discovered specialists",
+        "  - pi provider/runtime health",
+        "  - beads availability",
+        "  - MCP registration hints",
+        "  - active background jobs",
+        "",
+        "Options:",
+        "  --json   Output machine-readable 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 -f [--forever]",
+        "",
+        "Read background job events.",
+        "",
+        "Modes:",
+        "  specialists feed <job-id>        Replay events for one job",
+        "  specialists feed <job-id> -f     Follow one job until completion",
+        "  specialists feed -f              Follow all jobs globally",
+        "",
+        "Options:",
+        "  -f, --follow   Follow live updates",
+        "  --forever      Keep following in global mode even when all jobs complete",
+        "",
+        "Examples:",
+        "  specialists feed 49adda",
+        "  specialists feed 49adda --follow",
+        "  specialists feed -f",
+        "  specialists feed -f --forever",
+        ""
+      ].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",
+        "",
+        "Diagnose bootstrap and runtime problems.",
+        "",
+        "Checks:",
+        "  1. pi installed and has active providers",
+        "  2. beads installed and .beads/ present",
+        "  3. xtrm-tools availability",
+        "  4. Specialists MCP registration in .mcp.json",
+        "  5. .specialists/ runtime directories",
+        "  6. hook wiring expectations",
+        "  7. zombie job detection",
+        "",
+        "Behavior:",
+        "  - prints fix hints for failing checks",
+        "  - auto-creates missing runtime directories when possible",
+        "",
+        "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 +28952,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);
 });