@jaggerxtrm/specialists 3.3.3 → 3.4.0

package/dist/index.js

@@ -17410,7 +17410,98 @@ var init_dist = __esm(() => {
 });
 
 // src/specialist/schema.ts
+function formatPath(path) {
+  return path.map((p) => typeof p === "number" ? `[${p}]` : p).join(".");
+}
+function getFriendlyMessage(issue2) {
+  const path = formatPath(issue2.path);
+  if (issue2.code === "invalid_string" && issue2.validation === "regex") {
+    if (path.includes("name")) {
+      return `Invalid specialist name: must be kebab-case (lowercase letters, numbers, hyphens). Got: "${issue2.path.at(-1) === "name" ? "invalid value" : "see schema"}"`;
+    }
+    if (path.includes("version")) {
+      return `Invalid version: must be semver format (e.g., "1.0.0"). Got value that doesn't match pattern.`;
+    }
+  }
+  if (issue2.code === "invalid_enum_value") {
+    const allowed = issue2.options.map((o) => `"${o}"`).join(", ");
+    if (path.includes("permission_required")) {
+      return `Invalid permission_required: must be one of ${allowed}. This controls which pi tools are available.`;
+    }
+    if (path.includes("mode")) {
+      return `Invalid execution.mode: must be one of ${allowed}.`;
+    }
+    if (path.includes("beads_integration")) {
+      return `Invalid beads_integration: must be one of ${allowed}.`;
+    }
+    return `Invalid value at "${path}": expected one of ${allowed}, got "${issue2.received}"`;
+  }
+  if (issue2.code === "invalid_type") {
+    return `Invalid type at "${path}": expected ${issue2.expected}, got ${issue2.received}`;
+  }
+  if (issue2.code === "invalid_literal") {
+    return `Invalid value at "${path}": expected "${issue2.expected}"`;
+  }
+  if (issue2.code === "missing_key") {
+    return `Missing required field: "${formatPath(issue2.path)}"`;
+  }
+  return issue2.message;
+}
+async function validateSpecialist(yamlContent) {
+  const errors5 = [];
+  const warnings = [];
+  let raw;
+  try {
+    raw = $parse(yamlContent);
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    errors5.push({
+      path: "yaml",
+      message: `YAML parse error: ${msg}`,
+      code: "yaml_parse_error"
+    });
+    return { valid: false, errors: errors5, warnings };
+  }
+  const result = SpecialistSchema.safeParse(raw);
+  if (!result.success) {
+    for (const issue2 of result.error.issues) {
+      errors5.push({
+        path: formatPath(issue2.path),
+        message: getFriendlyMessage(issue2),
+        code: issue2.code
+      });
+    }
+  } else {
+    const spec = result.data;
+    if (spec.specialist.prompt.normalize_template) {
+      warnings.push("prompt.normalize_template is deprecated (Mercury compat) and will be ignored");
+    }
+    if (spec.specialist.execution.preferred_profile) {
+      warnings.push("execution.preferred_profile is deprecated (Agent Forge compat) and will be ignored");
+    }
+    if (spec.specialist.execution.approval_mode) {
+      warnings.push("execution.approval_mode is deprecated (Agent Forge compat) and will be ignored");
+    }
+    if (!spec.specialist.execution.model.includes("/")) {
+      warnings.push(`Model "${spec.specialist.execution.model}" doesn't include a provider prefix. Expected format: "provider/model-id" (e.g., "anthropic/claude-sonnet-4-5")`);
+    }
+  }
+  return { valid: errors5.length === 0, errors: errors5, warnings };
+}
 async function parseSpecialist(yamlContent) {
+  const result = await validateSpecialist(yamlContent);
+  if (!result.valid) {
+    const errorList = result.errors.map((e) => `  • ${e.message}`).join(`
+`);
+    throw new Error(`Schema validation failed:
+${errorList}`);
+  }
+  if (result.warnings.length > 0) {
+    process.stderr.write(`[specialists] warnings:
+${result.warnings.map((w) => `  ⚠ ${w}`).join(`
+`)}
+`);
+  }
   const raw = $parse(yamlContent);
   return SpecialistSchema.parseAsync(raw);
 }
@@ -17767,13 +17858,36 @@ class PiAgentSession {
       handler?.(event);
       return;
     }
-    if (type === "message_start" && event.message?.role === "assistant") {
-      const { provider, model } = event.message ?? {};
-      if (provider || model) {
-        this.options.onMeta?.({ backend: provider ?? "", model: model ?? "" });
+    if (type === "message_start") {
+      const role = event.message?.role;
+      if (role === "assistant") {
+        this.options.onEvent?.("message_start_assistant");
+        const { provider, model } = event.message ?? {};
+        if (provider || model) {
+          this.options.onMeta?.({ backend: provider ?? "", model: model ?? "" });
+        }
+      } else if (role === "toolResult") {
+        this.options.onEvent?.("message_start_tool_result");
+      }
+      return;
+    }
+    if (type === "message_end") {
+      const role = event.message?.role;
+      if (role === "assistant") {
+        this.options.onEvent?.("message_end_assistant");
+      } else if (role === "toolResult") {
+        this.options.onEvent?.("message_end_tool_result");
       }
       return;
     }
+    if (type === "turn_start") {
+      this.options.onEvent?.("turn_start");
+      return;
+    }
+    if (type === "turn_end") {
+      this.options.onEvent?.("turn_end");
+      return;
+    }
     if (type === "agent_end") {
       const messages = event.messages ?? [];
       const last = [...messages].reverse().find((m) => m.role === "assistant");
@@ -17786,11 +17900,11 @@ class PiAgentSession {
       return;
     }
     if (type === "tool_execution_start") {
-      this.options.onEvent?.("tool_execution");
+      this.options.onEvent?.("tool_execution_start");
       return;
     }
     if (type === "tool_execution_update") {
-      this.options.onEvent?.("tool_execution");
+      this.options.onEvent?.("tool_execution_update");
       return;
     }
     if (type === "tool_execution_end") {
@@ -17888,7 +18002,17 @@ class PiAgentSession {
     if (this._killed)
       return;
     this.proc?.stdin?.end();
-    await this._donePromise?.catch(() => {});
+    if (this.proc) {
+      await new Promise((resolve) => {
+        this.proc.on("close", () => resolve());
+        setTimeout(() => {
+          if (this.proc && !this._killed) {
+            this.proc.kill();
+          }
+          resolve();
+        }, 2000);
+      });
+    }
   }
   kill() {
     if (this._killed)
@@ -18267,6 +18391,7 @@ ${preScripts.map((s) => `    • ${s.run}${s.inject_output ? " → $pre_script_o
     let sessionBackend = model;
     let session;
     let keepAliveActive = false;
+    let sessionClosed = false;
     try {
       session = await this.sessionFactory({
         model,
@@ -18305,6 +18430,7 @@ ${preScripts.map((s) => `    • ${s.run}${s.inject_output ? " → $pre_script_o
         onResumeReady(resumeFn, closeFn);
       } else {
         await session.close();
+        sessionClosed = true;
       }
       const postScripts = spec.specialist.skills?.scripts?.filter((s) => s.phase === "post") ?? [];
       for (const script of postScripts)
@@ -18329,7 +18455,7 @@ ${preScripts.map((s) => `    • ${s.run}${s.inject_output ? " → $pre_script_o
       });
       throw err;
     } finally {
-      if (!keepAliveActive) {
+      if (!keepAliveActive && !sessionClosed) {
         session?.kill();
       }
     }
@@ -18463,6 +18589,23 @@ function mapCallbackEventToTimelineEvent(callbackEvent, context) {
         phase: "start",
         tool_call_id: context.toolCallId
       };
+    case "tool_execution_start":
+      return {
+        t,
+        type: TIMELINE_EVENT_TYPES.TOOL,
+        tool: context.tool ?? "unknown",
+        phase: "start",
+        tool_call_id: context.toolCallId
+      };
+    case "tool_execution_update":
+    case "tool_execution":
+      return {
+        t,
+        type: TIMELINE_EVENT_TYPES.TOOL,
+        tool: context.tool ?? "unknown",
+        phase: "update",
+        tool_call_id: context.toolCallId
+      };
     case "tool_execution_end":
       return {
         t,
@@ -18472,6 +18615,18 @@ function mapCallbackEventToTimelineEvent(callbackEvent, context) {
         tool_call_id: context.toolCallId,
         is_error: context.isError
       };
+    case "message_start_assistant":
+      return { t, type: TIMELINE_EVENT_TYPES.MESSAGE, phase: "start", role: "assistant" };
+    case "message_end_assistant":
+      return { t, type: TIMELINE_EVENT_TYPES.MESSAGE, phase: "end", role: "assistant" };
+    case "message_start_tool_result":
+      return { t, type: TIMELINE_EVENT_TYPES.MESSAGE, phase: "start", role: "toolResult" };
+    case "message_end_tool_result":
+      return { t, type: TIMELINE_EVENT_TYPES.MESSAGE, phase: "end", role: "toolResult" };
+    case "turn_start":
+      return { t, type: TIMELINE_EVENT_TYPES.TURN, phase: "start" };
+    case "turn_end":
+      return { t, type: TIMELINE_EVENT_TYPES.TURN, phase: "end" };
     case "text":
       return { t, type: TIMELINE_EVENT_TYPES.TEXT };
     case "agent_end":
@@ -18552,6 +18707,8 @@ var init_timeline_events = __esm(() => {
     THINKING: "thinking",
     TOOL: "tool",
     TEXT: "text",
+    MESSAGE: "message",
+    TURN: "turn",
     RUN_COMPLETE: "run_complete",
     DONE: "done",
     AGENT_END: "agent_end"
@@ -18647,6 +18804,7 @@ class Supervisor {
     return jobs.sort((a, b) => b.started_at_ms - a.started_at_ms);
   }
   writeStatusFile(id, data) {
+    mkdirSync(this.jobDir(id), { recursive: true });
     const path = this.statusPath(id);
     const tmp = path + ".tmp";
     writeFileSync(tmp, JSON.stringify(data, null, 2), "utf-8");
@@ -18714,6 +18872,14 @@ class Supervisor {
       pid: process.pid
     };
     this.writeStatusFile(id, initialStatus);
+    writeFileSync(join3(this.opts.jobsDir, "latest"), `${id}
+`, "utf-8");
+    this.opts.onJobStarted?.({ id });
+    let statusSnapshot = initialStatus;
+    const setStatus = (updates) => {
+      statusSnapshot = { ...statusSnapshot, ...updates };
+      this.writeStatusFile(id, statusSnapshot);
+    };
     const eventsFd = openSync(this.eventsPath(id), "a");
     const appendTimelineEvent = (event) => {
       try {
@@ -18725,10 +18891,13 @@ class Supervisor {
     };
     appendTimelineEvent(createRunStartEvent(runOptions.name));
     const fifoPath = join3(dir, "steer.pipe");
-    try {
-      execFileSync("mkfifo", [fifoPath]);
-      this.updateStatus(id, { fifo_path: fifoPath });
-    } catch {}
+    const needsFifo = runOptions.keepAlive;
+    if (needsFifo) {
+      try {
+        execFileSync("mkfifo", [fifoPath]);
+        setStatus({ fifo_path: fifoPath });
+      } catch {}
+    }
     let textLogged = false;
     let currentTool = "";
     let currentToolCallId = "";
@@ -18736,6 +18905,8 @@ class Supervisor {
     let steerFn;
     let resumeFn;
     let closeFn;
+    let fifoReadStream;
+    let fifoReadline;
     const sigtermHandler = () => killFn?.();
     process.once("SIGTERM", sigtermHandler);
     try {
@@ -18743,11 +18914,12 @@ class Supervisor {
         const toolMatch = delta.match(/⚙ (.+?)…/);
         if (toolMatch) {
           currentTool = toolMatch[1];
-          this.updateStatus(id, { current_tool: currentTool });
+          setStatus({ current_tool: currentTool });
         }
+        this.opts.onProgress?.(delta);
       }, (eventType) => {
         const now = Date.now();
-        this.updateStatus(id, {
+        setStatus({
           status: "running",
           current_event: eventType,
           last_event_at_ms: now,
@@ -18764,54 +18936,58 @@ class Supervisor {
           appendTimelineEvent({ t: Date.now(), type: TIMELINE_EVENT_TYPES.TEXT });
         }
       }, (meta) => {
-        this.updateStatus(id, { model: meta.model, backend: meta.backend });
+        setStatus({ model: meta.model, backend: meta.backend });
         appendTimelineEvent(createMetaEvent(meta.model, meta.backend));
+        this.opts.onMeta?.(meta);
       }, (fn) => {
         killFn = fn;
       }, (beadId) => {
-        this.updateStatus(id, { bead_id: beadId });
+        setStatus({ bead_id: beadId });
       }, (fn) => {
         steerFn = fn;
-        if (existsSync4(fifoPath)) {
-          const rl = createInterface({ input: createReadStream(fifoPath, { flags: "r+" }) });
-          rl.on("line", (line) => {
-            try {
-              const parsed = JSON.parse(line);
-              if (parsed?.type === "steer" && typeof parsed.message === "string") {
-                steerFn?.(parsed.message).catch(() => {});
-              } else if (parsed?.type === "prompt" && typeof parsed.message === "string") {
-                if (resumeFn) {
-                  this.updateStatus(id, { status: "running", current_event: "starting" });
-                  resumeFn(parsed.message).then((output) => {
-                    writeFileSync(this.resultPath(id), output, "utf-8");
-                    this.updateStatus(id, {
-                      status: "waiting",
-                      current_event: "waiting",
-                      elapsed_s: Math.round((Date.now() - startedAtMs) / 1000),
-                      last_event_at_ms: Date.now()
-                    });
-                  }).catch((err) => {
-                    this.updateStatus(id, { status: "error", error: err?.message ?? String(err) });
+        if (!needsFifo || !existsSync4(fifoPath))
+          return;
+        fifoReadStream = createReadStream(fifoPath, { flags: "r+" });
+        fifoReadline = createInterface({ input: fifoReadStream });
+        fifoReadline.on("line", (line) => {
+          try {
+            const parsed = JSON.parse(line);
+            if (parsed?.type === "steer" && typeof parsed.message === "string") {
+              steerFn?.(parsed.message).catch(() => {});
+            } else if (parsed?.type === "prompt" && typeof parsed.message === "string") {
+              if (resumeFn) {
+                setStatus({ status: "running", current_event: "starting" });
+                resumeFn(parsed.message).then((output) => {
+                  mkdirSync(this.jobDir(id), { recursive: true });
+                  writeFileSync(this.resultPath(id), output, "utf-8");
+                  setStatus({
+                    status: "waiting",
+                    current_event: "waiting",
+                    elapsed_s: Math.round((Date.now() - startedAtMs) / 1000),
+                    last_event_at_ms: Date.now()
                   });
-                }
-              } else if (parsed?.type === "close") {
-                closeFn?.().catch(() => {});
+                }).catch((err) => {
+                  setStatus({ status: "error", error: err?.message ?? String(err) });
+                });
               }
-            } catch {}
-          });
-          rl.on("error", () => {});
-        }
+            } else if (parsed?.type === "close") {
+              closeFn?.().catch(() => {});
+            }
+          } catch {}
+        });
+        fifoReadline.on("error", () => {});
       }, (rFn, cFn) => {
         resumeFn = rFn;
         closeFn = cFn;
-        this.updateStatus(id, { status: "waiting", current_event: "waiting" });
+        setStatus({ status: "waiting", current_event: "waiting" });
       });
       const elapsed = Math.round((Date.now() - startedAtMs) / 1000);
+      mkdirSync(this.jobDir(id), { recursive: true });
       writeFileSync(this.resultPath(id), result.output, "utf-8");
       if (result.beadId) {
         this.opts.beadsClient?.updateBeadNotes(result.beadId, formatBeadNotes(result));
       }
-      this.updateStatus(id, {
+      setStatus({
         status: "done",
         elapsed_s: elapsed,
         last_event_at_ms: Date.now(),
@@ -18824,12 +19000,13 @@ class Supervisor {
         backend: result.backend,
         bead_id: result.beadId
       }));
+      mkdirSync(this.readyDir(), { recursive: true });
       writeFileSync(join3(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, {
+      setStatus({
         status: "error",
         elapsed_s: elapsed,
         error: errorMsg
@@ -18840,6 +19017,12 @@ class Supervisor {
       throw err;
     } finally {
       process.removeListener("SIGTERM", sigtermHandler);
+      try {
+        fifoReadline?.close();
+      } catch {}
+      try {
+        fifoReadStream?.destroy();
+      } catch {}
       try {
         fsyncSync(eventsFd);
       } catch {}
@@ -18862,14 +19045,21 @@ var exports_install = {};
 __export(exports_install, {
   run: () => run
 });
-import { execFileSync as execFileSync2 } from "node:child_process";
-import { fileURLToPath } from "node:url";
-import { dirname as dirname2, join as join8 } from "node:path";
 async function run() {
-  const installerPath = join8(dirname2(fileURLToPath(import.meta.url)), "..", "bin", "install.js");
-  execFileSync2(process.execPath, [installerPath], { stdio: "inherit" });
+  console.log("");
+  console.log(yellow("⚠ DEPRECATED: `specialists install` is deprecated"));
+  console.log("");
+  console.log(`  Use ${bold("specialists init")} instead.`);
+  console.log("");
+  console.log("  The init command:");
+  console.log("    • creates specialists/ and .specialists/ directories");
+  console.log("    • registers the MCP server in .mcp.json");
+  console.log("    • injects workflow context into AGENTS.md/CLAUDE.md");
+  console.log("");
+  console.log(`  ${dim("Run: specialists init --help for full details")}`);
+  console.log("");
 }
-var init_install = () => {};
+var bold = (s) => `\x1B[1m${s}\x1B[0m`, yellow = (s) => `\x1B[33m${s}\x1B[0m`, dim = (s) => `\x1B[2m${s}\x1B[0m`;
 
 // src/cli/version.ts
 var exports_version = {};
@@ -18877,9 +19067,23 @@ __export(exports_version, {
   run: () => run2
 });
 import { createRequire as createRequire2 } from "node:module";
+import { fileURLToPath } from "node:url";
+import { dirname as dirname2, join as join8 } from "node:path";
+import { existsSync as existsSync6 } from "node:fs";
 async function run2() {
   const req = createRequire2(import.meta.url);
-  const pkg = req("../package.json");
+  const here = dirname2(fileURLToPath(import.meta.url));
+  const bundlePkgPath = join8(here, "..", "package.json");
+  const sourcePkgPath = join8(here, "..", "..", "package.json");
+  let pkg;
+  if (existsSync6(bundlePkgPath)) {
+    pkg = req("../package.json");
+  } else if (existsSync6(sourcePkgPath)) {
+    pkg = req("../../package.json");
+  } else {
+    console.error("Cannot find package.json");
+    process.exit(1);
+  }
   console.log(`${pkg.name} v${pkg.version}`);
 }
 var init_version = () => {};
@@ -18944,19 +19148,19 @@ async function run3() {
   }
   const nameWidth = Math.max(...specialists.map((s) => s.name.length), 4);
   console.log(`
-${bold(`Specialists (${specialists.length})`)}
+${bold2(`Specialists (${specialists.length})`)}
 `);
   for (const s of specialists) {
     const name = cyan(s.name.padEnd(nameWidth));
-    const scopeTag = s.scope === "default" ? green("[default]") : yellow("[user]");
-    const model = dim(s.model);
+    const scopeTag = s.scope === "default" ? green("[default]") : yellow2("[user]");
+    const model = dim2(s.model);
     const desc = s.description.length > 80 ? s.description.slice(0, 79) + "…" : s.description;
     console.log(`  ${name}  ${scopeTag}  ${model}`);
-    console.log(`  ${" ".repeat(nameWidth)}  ${dim(desc)}`);
+    console.log(`  ${" ".repeat(nameWidth)}  ${dim2(desc)}`);
     console.log();
   }
 }
-var dim = (s) => `\x1B[2m${s}\x1B[0m`, bold = (s) => `\x1B[1m${s}\x1B[0m`, cyan = (s) => `\x1B[36m${s}\x1B[0m`, green = (s) => `\x1B[32m${s}\x1B[0m`, yellow = (s) => `\x1B[33m${s}\x1B[0m`, ArgParseError;
+var dim2 = (s) => `\x1B[2m${s}\x1B[0m`, bold2 = (s) => `\x1B[1m${s}\x1B[0m`, cyan = (s) => `\x1B[36m${s}\x1B[0m`, green = (s) => `\x1B[32m${s}\x1B[0m`, yellow2 = (s) => `\x1B[33m${s}\x1B[0m`, ArgParseError;
 var init_list = __esm(() => {
   init_loader();
   ArgParseError = class ArgParseError extends Error {
@@ -19043,31 +19247,31 @@ async function run4() {
   }
   const total = models.length;
   console.log(`
-${bold2(`Models on pi`)}  ${dim2(`(${total} total)`)}
+${bold3(`Models on pi`)}  ${dim3(`(${total} total)`)}
 `);
   for (const [provider, pModels] of byProvider) {
-    console.log(`  ${cyan2(provider)}  ${dim2(`${pModels.length} model${pModels.length !== 1 ? "s" : ""}`)}`);
+    console.log(`  ${cyan2(provider)}  ${dim3(`${pModels.length} model${pModels.length !== 1 ? "s" : ""}`)}`);
     const modelWidth = Math.max(...pModels.map((m) => m.model.length));
     for (const m of pModels) {
       const key = `${m.provider}/${m.model}`;
       const inUse = usedBy.get(key);
       const flags = [
-        m.thinking ? green2("thinking") : dim2("·"),
-        m.images ? dim2("images") : ""
+        m.thinking ? green2("thinking") : dim3("·"),
+        m.images ? dim3("images") : ""
       ].filter(Boolean).join("  ");
-      const ctx = dim2(`ctx ${m.context}`);
-      const usedLabel = inUse ? `  ${yellow2("←")} ${dim2(inUse.join(", "))}` : "";
+      const ctx = dim3(`ctx ${m.context}`);
+      const usedLabel = inUse ? `  ${yellow3("←")} ${dim3(inUse.join(", "))}` : "";
       console.log(`    ${m.model.padEnd(modelWidth)}  ${ctx.padEnd(18)}  ${flags}${usedLabel}`);
     }
     console.log();
   }
   if (!args.used) {
-    console.log(dim2(`  --provider <name>  filter by provider`));
-    console.log(dim2(`  --used             only show models used by your specialists`));
+    console.log(dim3(`  --provider <name>  filter by provider`));
+    console.log(dim3(`  --used             only show models used by your specialists`));
     console.log();
   }
 }
-var bold2 = (s) => `\x1B[1m${s}\x1B[0m`, dim2 = (s) => `\x1B[2m${s}\x1B[0m`, cyan2 = (s) => `\x1B[36m${s}\x1B[0m`, yellow2 = (s) => `\x1B[33m${s}\x1B[0m`, green2 = (s) => `\x1B[32m${s}\x1B[0m`;
+var bold3 = (s) => `\x1B[1m${s}\x1B[0m`, dim3 = (s) => `\x1B[2m${s}\x1B[0m`, cyan2 = (s) => `\x1B[36m${s}\x1B[0m`, yellow3 = (s) => `\x1B[33m${s}\x1B[0m`, green2 = (s) => `\x1B[32m${s}\x1B[0m`;
 var init_models = __esm(() => {
   init_loader();
 });
@@ -19077,17 +19281,17 @@ var exports_init = {};
 __export(exports_init, {
   run: () => run5
 });
-import { copyFileSync, cpSync, existsSync as existsSync6, mkdirSync as mkdirSync2, readdirSync as readdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "node:fs";
+import { copyFileSync, cpSync, existsSync as existsSync7, mkdirSync as mkdirSync2, readdirSync as readdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync4 } from "node:fs";
 import { join as join9 } from "node:path";
 import { fileURLToPath as fileURLToPath2 } from "node:url";
 function ok(msg) {
   console.log(`  ${green3("✓")} ${msg}`);
 }
 function skip(msg) {
-  console.log(`  ${yellow3("○")} ${msg}`);
+  console.log(`  ${yellow4("○")} ${msg}`);
 }
 function loadJson(path, fallback) {
-  if (!existsSync6(path))
+  if (!existsSync7(path))
     return structuredClone(fallback);
   try {
     return JSON.parse(readFileSync3(path, "utf-8"));
@@ -19102,10 +19306,10 @@ function saveJson(path, value) {
 function resolvePackagePath(relativePath) {
   const configPath = `config/${relativePath}`;
   let resolved = fileURLToPath2(new URL(`../${configPath}`, import.meta.url));
-  if (existsSync6(resolved))
+  if (existsSync7(resolved))
     return resolved;
   resolved = fileURLToPath2(new URL(`../../${configPath}`, import.meta.url));
-  if (existsSync6(resolved))
+  if (existsSync7(resolved))
     return resolved;
   return null;
 }
@@ -19121,7 +19325,7 @@ function copyCanonicalSpecialists(cwd) {
     skip("no specialist files found in package");
     return;
   }
-  if (!existsSync6(targetDir)) {
+  if (!existsSync7(targetDir)) {
     mkdirSync2(targetDir, { recursive: true });
   }
   let copied = 0;
@@ -19129,7 +19333,7 @@ function copyCanonicalSpecialists(cwd) {
   for (const file of files) {
     const src = join9(sourceDir, file);
     const dest = join9(targetDir, file);
-    if (existsSync6(dest)) {
+    if (existsSync7(dest)) {
       skipped++;
     } else {
       copyFileSync(src, dest);
@@ -19143,19 +19347,19 @@ function copyCanonicalSpecialists(cwd) {
     skip(`${skipped} specialist${skipped === 1 ? "" : "s"} already exist (not overwritten)`);
   }
 }
-function copyCanonicalHooks(cwd) {
+function installProjectHooks(cwd) {
   const sourceDir = resolvePackagePath("hooks");
   if (!sourceDir) {
     skip("no canonical hooks found in package");
     return;
   }
-  const targetDir = join9(cwd, ".specialists", "default", "hooks");
+  const targetDir = join9(cwd, ".claude", "hooks");
   const hooks = readdirSync2(sourceDir).filter((f) => f.endsWith(".mjs"));
   if (hooks.length === 0) {
     skip("no hook files found in package");
     return;
   }
-  if (!existsSync6(targetDir)) {
+  if (!existsSync7(targetDir)) {
     mkdirSync2(targetDir, { recursive: true });
   }
   let copied = 0;
@@ -19163,7 +19367,7 @@ function copyCanonicalHooks(cwd) {
   for (const file of hooks) {
     const src = join9(sourceDir, file);
     const dest = join9(targetDir, file);
-    if (existsSync6(dest)) {
+    if (existsSync7(dest)) {
       skipped++;
     } else {
       copyFileSync(src, dest);
@@ -19171,16 +19375,16 @@ function copyCanonicalHooks(cwd) {
     }
   }
   if (copied > 0) {
-    ok(`copied ${copied} hook${copied === 1 ? "" : "s"} to .specialists/default/hooks/`);
+    ok(`installed ${copied} hook${copied === 1 ? "" : "s"} to .claude/hooks/`);
   }
   if (skipped > 0) {
     skip(`${skipped} hook${skipped === 1 ? "" : "s"} already exist (not overwritten)`);
   }
 }
-function ensureProjectHooks(cwd) {
+function ensureProjectHookWiring(cwd) {
   const settingsPath = join9(cwd, ".claude", "settings.json");
   const settingsDir = join9(cwd, ".claude");
-  if (!existsSync6(settingsDir)) {
+  if (!existsSync7(settingsDir)) {
     mkdirSync2(settingsDir, { recursive: true });
   }
   const settings = loadJson(settingsPath, {});
@@ -19194,8 +19398,8 @@ function ensureProjectHooks(cwd) {
       changed = true;
     }
   }
-  addHook("UserPromptSubmit", "node .specialists/default/hooks/specialists-complete.mjs");
-  addHook("SessionStart", "node .specialists/default/hooks/specialists-session-start.mjs");
+  addHook("UserPromptSubmit", "node .claude/hooks/specialists-complete.mjs");
+  addHook("SessionStart", "node .claude/hooks/specialists-session-start.mjs");
   if (changed) {
     saveJson(settingsPath, settings);
     ok("wired specialists hooks in .claude/settings.json");
@@ -19203,7 +19407,7 @@ function ensureProjectHooks(cwd) {
     skip(".claude/settings.json already has specialists hooks");
   }
 }
-function copyCanonicalSkills(cwd) {
+function installProjectSkills(cwd) {
   const sourceDir = resolvePackagePath("skills");
   if (!sourceDir) {
     skip("no canonical skills found in package");
@@ -19214,44 +19418,39 @@ function copyCanonicalSkills(cwd) {
     skip("no skill directories found in package");
     return;
   }
-  const targetDir = join9(cwd, ".specialists", "default", "skills");
-  if (!existsSync6(targetDir)) {
-    mkdirSync2(targetDir, { recursive: true });
-  }
-  let copied = 0;
-  let skipped = 0;
-  for (const skill of skills) {
-    const src = join9(sourceDir, skill);
-    const dest = join9(targetDir, skill);
-    if (existsSync6(dest)) {
-      skipped++;
-    } else {
-      cpSync(src, dest, { recursive: true });
-      copied++;
+  const targetDirs = [
+    join9(cwd, ".claude", "skills"),
+    join9(cwd, ".pi", "skills")
+  ];
+  let totalCopied = 0;
+  let totalSkipped = 0;
+  for (const targetDir of targetDirs) {
+    if (!existsSync7(targetDir)) {
+      mkdirSync2(targetDir, { recursive: true });
+    }
+    for (const skill of skills) {
+      const src = join9(sourceDir, skill);
+      const dest = join9(targetDir, skill);
+      if (existsSync7(dest)) {
+        totalSkipped++;
+      } else {
+        cpSync(src, dest, { recursive: true });
+        totalCopied++;
+      }
     }
   }
-  if (copied > 0) {
-    ok(`copied ${copied} skill${copied === 1 ? "" : "s"} to .specialists/default/skills/`);
+  if (totalCopied > 0) {
+    ok(`installed ${skills.length} skill${skills.length === 1 ? "" : "s"} to .claude/skills/ and .pi/skills/`);
   }
-  if (skipped > 0) {
-    skip(`${skipped} skill${skipped === 1 ? "" : "s"} already exist (not overwritten)`);
+  if (totalSkipped > 0) {
+    skip(`${totalSkipped} skill location${totalSkipped === 1 ? "" : "s"} already exist (not overwritten)`);
   }
 }
 function createUserDirs(cwd) {
-  const userDirs = [
-    join9(cwd, ".specialists", "user", "specialists"),
-    join9(cwd, ".specialists", "user", "hooks"),
-    join9(cwd, ".specialists", "user", "skills")
-  ];
-  let created = 0;
-  for (const dir of userDirs) {
-    if (!existsSync6(dir)) {
-      mkdirSync2(dir, { recursive: true });
-      created++;
-    }
-  }
-  if (created > 0) {
-    ok("created .specialists/user/ directories for custom assets");
+  const userDir = join9(cwd, ".specialists", "user", "specialists");
+  if (!existsSync7(userDir)) {
+    mkdirSync2(userDir, { recursive: true });
+    ok("created .specialists/user/specialists/ for custom specialists");
   }
 }
 function createRuntimeDirs(cwd) {
@@ -19261,7 +19460,7 @@ function createRuntimeDirs(cwd) {
   ];
   let created = 0;
   for (const dir of runtimeDirs) {
-    if (!existsSync6(dir)) {
+    if (!existsSync7(dir)) {
       mkdirSync2(dir, { recursive: true });
       created++;
     }
@@ -19285,7 +19484,7 @@ function ensureProjectMcp(cwd) {
 }
 function ensureGitignore(cwd) {
   const gitignorePath = join9(cwd, ".gitignore");
-  const existing = existsSync6(gitignorePath) ? readFileSync3(gitignorePath, "utf-8") : "";
+  const existing = existsSync7(gitignorePath) ? readFileSync3(gitignorePath, "utf-8") : "";
   let added = 0;
   const lines = existing.split(`
 `);
@@ -19306,7 +19505,7 @@ function ensureGitignore(cwd) {
 }
 function ensureAgentsMd(cwd) {
   const agentsPath = join9(cwd, "AGENTS.md");
-  if (existsSync6(agentsPath)) {
+  if (existsSync7(agentsPath)) {
     const existing = readFileSync3(agentsPath, "utf-8");
     if (existing.includes(AGENTS_MARKER)) {
       skip("AGENTS.md already has Specialists section");
@@ -19324,40 +19523,42 @@ function ensureAgentsMd(cwd) {
 async function run5() {
   const cwd = process.cwd();
   console.log(`
-${bold3("specialists init")}
+${bold4("specialists init")}
 `);
   copyCanonicalSpecialists(cwd);
-  copyCanonicalHooks(cwd);
-  copyCanonicalSkills(cwd);
   createUserDirs(cwd);
   createRuntimeDirs(cwd);
   ensureGitignore(cwd);
   ensureAgentsMd(cwd);
   ensureProjectMcp(cwd);
-  ensureProjectHooks(cwd);
+  installProjectHooks(cwd);
+  ensureProjectHookWiring(cwd);
+  installProjectSkills(cwd);
   console.log(`
-${bold3("Done!")}
+${bold4("Done!")}
 `);
-  console.log(`  ${dim3("Directory structure:")}`);
+  console.log(`  ${dim4("Project-local installation:")}`);
+  console.log(`  .claude/hooks/         ${dim4("# hooks (Claude Code)")}`);
+  console.log(`  .claude/settings.json  ${dim4("# hook wiring")}`);
+  console.log(`  .claude/skills/        ${dim4("# skills (Claude Code)")}`);
+  console.log(`  .pi/skills/            ${dim4("# skills (pi)")}`);
+  console.log("");
+  console.log(`  ${dim4(".specialists/ structure:")}`);
   console.log(`  .specialists/`);
-  console.log(`  ├── default/      ${dim3("# canonical assets (from init)")}`);
-  console.log(`  │   ├── specialists/`);
-  console.log(`  │   ├── hooks/`);
-  console.log(`  │   └── skills/`);
-  console.log(`  ├── user/         ${dim3("# your custom additions")}`);
-  console.log(`  │   ├── specialists/`);
-  console.log(`  │   ├── hooks/`);
-  console.log(`  │   └── skills/`);
-  console.log(`  ├── jobs/         ${dim3("# runtime (gitignored)")}`);
-  console.log(`  └── ready/        ${dim3("# runtime (gitignored)")}`);
+  console.log(`  ├── default/           ${dim4("# canonical specialists (from init)")}`);
+  console.log(`  │   └── specialists/`);
+  console.log(`  ├── user/              ${dim4("# your custom specialists")}`);
+  console.log(`  │   └── specialists/`);
+  console.log(`  ├── jobs/              ${dim4("# runtime (gitignored)")}`);
+  console.log(`  └── ready/             ${dim4("# runtime (gitignored)")}`);
   console.log(`
-  ${dim3("Next steps:")}`);
-  console.log(`  1. Run ${yellow3("specialists list")} to see available specialists`);
-  console.log(`  2. Add custom specialists to ${yellow3(".specialists/user/specialists/")}`);
-  console.log(`  3. Restart Claude Code to pick up changes
+  ${dim4("Next steps:")}`);
+  console.log(`  1. Run ${yellow4("specialists list")} to see available specialists`);
+  console.log(`  2. Add custom specialists to ${yellow4(".specialists/user/specialists/")}`);
+  console.log(`  3. Restart Claude Code or pi to pick up changes
 `);
 }
-var bold3 = (s) => `\x1B[1m${s}\x1B[0m`, green3 = (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_ENTRIES, MCP_FILE = ".mcp.json", MCP_SERVER_NAME = "specialists", MCP_SERVER_CONFIG;
+var bold4 = (s) => `\x1B[1m${s}\x1B[0m`, green3 = (s) => `\x1B[32m${s}\x1B[0m`, yellow4 = (s) => `\x1B[33m${s}\x1B[0m`, dim4 = (s) => `\x1B[2m${s}\x1B[0m`, AGENTS_BLOCK, AGENTS_MARKER = "## Specialists", GITIGNORE_ENTRIES, MCP_FILE = ".mcp.json", MCP_SERVER_NAME = "specialists", MCP_SERVER_CONFIG;
 var init_init = __esm(() => {
   AGENTS_BLOCK = `
 ## Specialists
@@ -19373,13 +19574,126 @@ Add custom specialists to \`.specialists/user/specialists/\` to extend the defau
   MCP_SERVER_CONFIG = { command: "specialists", args: [] };
 });
 
+// src/cli/validate.ts
+var exports_validate = {};
+__export(exports_validate, {
+  run: () => run6,
+  parseArgs: () => parseArgs3,
+  ArgParseError: () => ArgParseError2
+});
+import { readFile as readFile2 } from "node:fs/promises";
+import { existsSync as existsSync8 } from "node:fs";
+import { join as join10 } from "node:path";
+function parseArgs3(argv) {
+  const name = argv[0];
+  if (!name || name.startsWith("--")) {
+    throw new ArgParseError2("Usage: specialists validate <name> [--json]");
+  }
+  const json = argv.includes("--json");
+  return { name, json };
+}
+function findSpecialistFile(name) {
+  const scanDirs = [
+    join10(process.cwd(), ".specialists", "user", "specialists"),
+    join10(process.cwd(), ".specialists", "default", "specialists"),
+    join10(process.cwd(), "specialists")
+  ];
+  for (const dir of scanDirs) {
+    const candidate = join10(dir, `${name}.specialist.yaml`);
+    if (existsSync8(candidate)) {
+      return candidate;
+    }
+  }
+  return;
+}
+async function run6() {
+  let args;
+  try {
+    args = parseArgs3(process.argv.slice(3));
+  } catch (err) {
+    if (err instanceof ArgParseError2) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+    throw err;
+  }
+  const { name, json } = args;
+  const filePath = findSpecialistFile(name);
+  if (!filePath) {
+    if (json) {
+      console.log(JSON.stringify({ valid: false, errors: [{ path: "name", message: `Specialist not found: ${name}`, code: "not_found" }] }));
+    } else {
+      console.error(`${red("✗")} Specialist not found: ${cyan3(name)}`);
+    }
+    process.exit(1);
+  }
+  let content;
+  try {
+    content = await readFile2(filePath, "utf-8");
+  } catch (e) {
+    const msg = e instanceof Error ? e.message : String(e);
+    if (json) {
+      console.log(JSON.stringify({ valid: false, errors: [{ path: "file", message: `Failed to read file: ${msg}`, code: "read_error" }] }));
+    } else {
+      console.error(`${red("✗")} Failed to read file: ${msg}`);
+    }
+    process.exit(1);
+  }
+  const result = await validateSpecialist(content);
+  if (json) {
+    console.log(JSON.stringify({
+      valid: result.valid,
+      errors: result.errors,
+      warnings: result.warnings,
+      file: filePath
+    }, null, 2));
+    process.exit(result.valid ? 0 : 1);
+  }
+  console.log(`
+${bold5("Validating")} ${cyan3(name)} ${dim5(`(${filePath})`)}
+`);
+  if (result.valid) {
+    console.log(`${green4("✓")} Schema validation passed
+`);
+  } else {
+    console.log(`${red("✗")} Schema validation failed:
+`);
+    for (const error2 of result.errors) {
+      console.log(`  ${red("•")} ${error2.message}`);
+      if (error2.path && error2.path !== "yaml") {
+        console.log(`    ${dim5(`path: ${error2.path}`)}`);
+      }
+    }
+    console.log();
+  }
+  if (result.warnings.length > 0) {
+    console.log(`${yellow5("Warnings")}:
+`);
+    for (const warning of result.warnings) {
+      console.log(`  ${yellow5("⚠")} ${warning}`);
+    }
+    console.log();
+  }
+  process.exit(result.valid ? 0 : 1);
+}
+var bold5 = (s) => `\x1B[1m${s}\x1B[0m`, dim5 = (s) => `\x1B[2m${s}\x1B[0m`, green4 = (s) => `\x1B[32m${s}\x1B[0m`, red = (s) => `\x1B[31m${s}\x1B[0m`, yellow5 = (s) => `\x1B[33m${s}\x1B[0m`, cyan3 = (s) => `\x1B[36m${s}\x1B[0m`, ArgParseError2;
+var init_validate = __esm(() => {
+  init_schema();
+  ArgParseError2 = class ArgParseError2 extends Error {
+    constructor(message) {
+      super(message);
+      this.name = "ArgParseError";
+    }
+  };
+});
+
 // src/cli/edit.ts
 var exports_edit = {};
 __export(exports_edit, {
-  run: () => run6
+  run: () => run7
 });
 import { readFileSync as readFileSync4, writeFileSync as writeFileSync5 } from "node:fs";
-function parseArgs3(argv) {
+function parseArgs4(argv) {
   const name = argv[0];
   if (!name || name.startsWith("--")) {
     console.error("Usage: specialists|sp edit <name> --<field> <value> [--dry-run]");
@@ -19398,8 +19712,8 @@ function parseArgs3(argv) {
     }
     if (token === "--scope") {
       const v = argv[++i];
-      if (v !== "project" && v !== "user") {
-        console.error(`Error: --scope must be "project" or "user", got: "${v ?? ""}"`);
+      if (v !== "default" && v !== "user") {
+        console.error(`Error: --scope must be "default" or "user", got: "${v ?? ""}"`);
         process.exit(1);
       }
       scope = v;
@@ -19441,8 +19755,8 @@ function setIn(doc2, path, value) {
     node.set(leaf, value);
   }
 }
-async function run6() {
-  const args = parseArgs3(process.argv.slice(3));
+async function run7() {
+  const args = parseArgs4(process.argv.slice(3));
   const { name, field, value, dryRun, scope } = args;
   const loader = new SpecialistLoader;
   const all = await loader.list();
@@ -19450,7 +19764,7 @@ async function run6() {
   if (!match) {
     const hint = scope ? ` (scope: ${scope})` : "";
     console.error(`Error: specialist "${name}" not found${hint}`);
-    console.error(`  Run ${yellow4("specialists list")} to see available specialists`);
+    console.error(`  Run ${yellow6("specialists list")} to see available specialists`);
     process.exit(1);
   }
   const raw = readFileSync4(match.filePath, "utf-8");
@@ -19466,10 +19780,10 @@ async function run6() {
   const updated = doc2.toString();
   if (dryRun) {
     console.log(`
-${bold4(`[dry-run] ${match.filePath}`)}
+${bold6(`[dry-run] ${match.filePath}`)}
 `);
-    console.log(dim4("--- current"));
-    console.log(dim4(`+++ updated`));
+    console.log(dim6("--- current"));
+    console.log(dim6(`+++ updated`));
     const oldLines = raw.split(`
 `);
     const newLines = updated.split(`
@@ -19477,8 +19791,8 @@ ${bold4(`[dry-run] ${match.filePath}`)}
     newLines.forEach((line, i) => {
       if (line !== oldLines[i]) {
         if (oldLines[i] !== undefined)
-          console.log(dim4(`- ${oldLines[i]}`));
-        console.log(green4(`+ ${line}`));
+          console.log(dim6(`- ${oldLines[i]}`));
+        console.log(green5(`+ ${line}`));
       }
     });
     console.log();
@@ -19486,9 +19800,9 @@ ${bold4(`[dry-run] ${match.filePath}`)}
   }
   writeFileSync5(match.filePath, updated, "utf-8");
   const displayValue = field === "tags" ? `[${typedValue.join(", ")}]` : String(typedValue);
-  console.log(`${green4("✓")} ${bold4(name)}: ${yellow4(field)} = ${displayValue}` + dim4(` (${match.filePath})`));
+  console.log(`${green5("✓")} ${bold6(name)}: ${yellow6(field)} = ${displayValue}` + dim6(` (${match.filePath})`));
 }
-var bold4 = (s) => `\x1B[1m${s}\x1B[0m`, green4 = (s) => `\x1B[32m${s}\x1B[0m`, yellow4 = (s) => `\x1B[33m${s}\x1B[0m`, dim4 = (s) => `\x1B[2m${s}\x1B[0m`, FIELD_MAP, VALID_PERMISSIONS;
+var bold6 = (s) => `\x1B[1m${s}\x1B[0m`, green5 = (s) => `\x1B[32m${s}\x1B[0m`, yellow6 = (s) => `\x1B[33m${s}\x1B[0m`, dim6 = (s) => `\x1B[2m${s}\x1B[0m`, FIELD_MAP, VALID_PERMISSIONS;
 var init_edit = __esm(() => {
   init_dist();
   init_loader();
@@ -19506,10 +19820,10 @@ var init_edit = __esm(() => {
 // src/cli/run.ts
 var exports_run = {};
 __export(exports_run, {
-  run: () => run7
+  run: () => run8
 });
-import { join as join10 } from "node:path";
-async function parseArgs4(argv) {
+import { join as join11 } from "node:path";
+async function parseArgs5(argv) {
   const name = argv[0];
   if (!name || name.startsWith("--")) {
     console.error('Usage: specialists|sp run <name> [--prompt "..."] [--bead <id>] [--context-depth <n>] [--model <model>] [--no-beads] [--keep-alive]');
@@ -19568,11 +19882,11 @@ async function parseArgs4(argv) {
   }
   return { name, prompt, beadId, model, noBeads, keepAlive, contextDepth };
 }
-async function run7() {
-  const args = await parseArgs4(process.argv.slice(3));
+async function run8() {
+  const args = await parseArgs5(process.argv.slice(3));
   const loader = new SpecialistLoader;
   const circuitBreaker = new CircuitBreaker;
-  const hooks = new HookEmitter({ tracePath: join10(process.cwd(), ".specialists", "trace.jsonl") });
+  const hooks = new HookEmitter({ tracePath: join11(process.cwd(), ".specialists", "trace.jsonl") });
   const beadsClient = args.noBeads ? undefined : new BeadsClient;
   const beadReader = beadsClient ?? new BeadsClient;
   let prompt = args.prompt;
@@ -19584,7 +19898,7 @@ async function run7() {
     }
     const blockers = args.contextDepth > 0 ? beadReader.getCompletedBlockers(args.beadId, args.contextDepth) : [];
     if (blockers.length > 0) {
-      process.stderr.write(dim5(`
+      process.stderr.write(dim7(`
 [context: ${blockers.length} completed dep${blockers.length > 1 ? "s" : ""} injected]
 `));
     }
@@ -19601,57 +19915,70 @@ async function run7() {
     circuitBreaker,
     beadsClient
   });
-  process.stderr.write(`
-${bold5(`Running ${cyan3(args.name)}`)}
-
-`);
-  let trackingBeadId;
-  const result = await runner.run({
-    name: args.name,
-    prompt,
-    variables,
-    backendOverride: args.model,
-    inputBeadId: args.beadId
-  }, (delta) => process.stdout.write(delta), undefined, (meta) => process.stderr.write(dim5(`
+  const jobsDir = join11(process.cwd(), ".specialists", "jobs");
+  const supervisor = new Supervisor({
+    runner,
+    runOptions: {
+      name: args.name,
+      prompt,
+      variables,
+      backendOverride: args.model,
+      inputBeadId: args.beadId,
+      keepAlive: args.keepAlive
+    },
+    jobsDir,
+    beadsClient,
+    onProgress: (delta) => process.stdout.write(delta),
+    onMeta: (meta) => process.stderr.write(dim7(`
 [${meta.backend} / ${meta.model}]
 
-`)), (killFn) => {
-    process.on("SIGINT", () => {
-      process.stderr.write(`
+`)),
+    onJobStarted: ({ id }) => process.stderr.write(dim7(`[job started: ${id}]
+`))
+  });
+  try {
+    await loader.get(args.name);
+  } catch (err) {
+    process.stderr.write(`Error: ${err?.message ?? err}
+`);
+    process.exit(1);
+  }
+  process.stderr.write(`
+${bold7(`Running ${cyan4(args.name)}`)}
 
-Interrupted.
 `);
-      killFn();
-      process.exit(130);
-    });
-  }, (beadId) => {
-    trackingBeadId = beadId;
-    process.stderr.write(dim5(`
-[bead: ${beadId}]
-`));
-  });
-  if (result.output && !result.output.endsWith(`
-`))
-    process.stdout.write(`
+  let jobId;
+  try {
+    jobId = await supervisor.run();
+  } catch (err) {
+    process.stderr.write(`Error: ${err?.message ?? err}
 `);
-  const secs = (result.durationMs / 1000).toFixed(1);
-  const effectiveBeadId = args.beadId ?? trackingBeadId;
+    process.exit(1);
+  }
+  const status = supervisor.readStatus(jobId);
+  const secs = ((status?.last_event_at_ms ?? Date.now()) - (status?.started_at_ms ?? Date.now())) / 1000;
   const footer = [
-    effectiveBeadId ? `bead ${effectiveBeadId}` : "",
-    `${secs}s`,
-    dim5(result.model)
+    `job ${jobId}`,
+    status?.bead_id ? `bead ${status.bead_id}` : "",
+    `${secs.toFixed(1)}s`,
+    status?.model ? dim7(`${status.backend}/${status.model}`) : ""
   ].filter(Boolean).join("  ");
   process.stderr.write(`
-${green5("✓")} ${footer}
+${green6("✓")} ${footer}
 
 `);
+  process.stderr.write(dim7(`Poll: specialists poll ${jobId} --json
+
+`));
+  process.exit(0);
 }
-var bold5 = (s) => `\x1B[1m${s}\x1B[0m`, dim5 = (s) => `\x1B[2m${s}\x1B[0m`, green5 = (s) => `\x1B[32m${s}\x1B[0m`, cyan3 = (s) => `\x1B[36m${s}\x1B[0m`;
+var bold7 = (s) => `\x1B[1m${s}\x1B[0m`, dim7 = (s) => `\x1B[2m${s}\x1B[0m`, green6 = (s) => `\x1B[32m${s}\x1B[0m`, cyan4 = (s) => `\x1B[36m${s}\x1B[0m`;
 var init_run = __esm(() => {
   init_loader();
   init_runner();
   init_hooks();
   init_beads();
+  init_supervisor();
 });
 
 // src/cli/format-helpers.ts
@@ -19692,9 +20019,9 @@ class JobColorMap {
   }
 }
 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 ts = dim8(formatTime(event.t));
+  const label = options.colorize(bold8(getEventLabel(event.type).padEnd(5)));
+  const prefix = `${options.colorize(`[${options.jobId}]`)} ${options.specialist}${options.beadId ? ` ${dim8(`[${options.beadId}]`)}` : ""}`;
   const detailParts = [];
   if (event.type === "meta") {
     detailParts.push(`model=${event.model}`);
@@ -19723,19 +20050,26 @@ function formatEventLine(event, options) {
     detailParts.push("kind=assistant");
   } else if (event.type === "thinking") {
     detailParts.push("kind=model");
+  } else if (event.type === "message") {
+    detailParts.push(`phase=${event.phase}`);
+    detailParts.push(`role=${event.role}`);
+  } else if (event.type === "turn") {
+    detailParts.push(`phase=${event.phase}`);
   }
-  const detail = detailParts.length > 0 ? dim6(detailParts.join(" ")) : "";
+  const detail = detailParts.length > 0 ? dim8(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`, green6 = (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 dim8 = (s) => `\x1B[2m${s}\x1B[0m`, bold8 = (s) => `\x1B[1m${s}\x1B[0m`, cyan5 = (s) => `\x1B[36m${s}\x1B[0m`, yellow7 = (s) => `\x1B[33m${s}\x1B[0m`, red2 = (s) => `\x1B[31m${s}\x1B[0m`, green7 = (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, green6, blue, red];
+  JOB_COLORS = [cyan5, yellow7, magenta, green7, blue, red2];
   EVENT_LABELS = {
     run_start: "START",
     meta: "META",
     thinking: "THINK",
     tool: "TOOL",
     text: "TEXT",
+    message: "MSG",
+    turn: "TURN",
     run_complete: "DONE",
     done: "DONE",
     agent_end: "DONE",
@@ -19746,27 +20080,27 @@ var init_format_helpers = __esm(() => {
 // src/cli/status.ts
 var exports_status = {};
 __export(exports_status, {
-  run: () => run8
+  run: () => run9
 });
 import { spawnSync as spawnSync6 } from "node:child_process";
-import { existsSync as existsSync7 } from "node:fs";
-import { join as join11 } from "node:path";
+import { existsSync as existsSync9 } from "node:fs";
+import { join as join12 } from "node:path";
 function ok2(msg) {
-  console.log(`  ${green6("✓")} ${msg}`);
+  console.log(`  ${green7("✓")} ${msg}`);
 }
 function warn(msg) {
-  console.log(`  ${yellow5("○")} ${msg}`);
+  console.log(`  ${yellow7("○")} ${msg}`);
 }
 function fail(msg) {
-  console.log(`  ${red("✗")} ${msg}`);
+  console.log(`  ${red2("✗")} ${msg}`);
 }
 function info(msg) {
-  console.log(`  ${dim6(msg)}`);
+  console.log(`  ${dim8(msg)}`);
 }
 function section(label) {
   const line = "─".repeat(Math.max(0, 38 - label.length));
   console.log(`
-${bold6(`── ${label} ${line}`)}`);
+${bold8(`── ${label} ${line}`)}`);
 }
 function cmd(bin, args) {
   const r = spawnSync6(bin, args, {
@@ -19789,18 +20123,18 @@ function formatElapsed2(s) {
 function statusColor(status) {
   switch (status) {
     case "running":
-      return cyan4(status);
+      return cyan5(status);
     case "done":
-      return green6(status);
+      return green7(status);
     case "error":
-      return red(status);
+      return red2(status);
     case "starting":
-      return yellow5(status);
+      return yellow7(status);
     default:
       return status;
   }
 }
-async function run8() {
+async function run9() {
   const argv = process.argv.slice(3);
   const jsonMode = argv.includes("--json");
   const loader = new SpecialistLoader;
@@ -19812,11 +20146,11 @@ async function run8() {
 `).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 = existsSync7(join11(process.cwd(), ".beads"));
+  const beadsPresent = existsSync9(join12(process.cwd(), ".beads"));
   const specialistsBin = cmd("which", ["specialists"]);
-  const jobsDir = join11(process.cwd(), ".specialists", "jobs");
+  const jobsDir = join12(process.cwd(), ".specialists", "jobs");
   let jobs = [];
-  if (existsSync7(jobsDir)) {
+  if (existsSync9(jobsDir)) {
     const supervisor = new Supervisor({
       runner: null,
       runOptions: null,
@@ -19867,60 +20201,62 @@ async function run8() {
     return;
   }
   console.log(`
-${bold6("specialists status")}
+${bold8("specialists status")}
 `);
   section("Specialists");
   if (allSpecialists.length === 0) {
-    warn(`no specialists found — run ${yellow5("specialists init")} to scaffold`);
+    warn(`no specialists found — run ${yellow7("specialists init")} to scaffold`);
   } else {
     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(`${allSpecialists.length} found  ${dim6(`(${scopeSummary})`)}`);
+    ok2(`${allSpecialists.length} found  ${dim8(`(${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")}  ${dim8(s.scope)}`);
       } else if (staleness === "STALE") {
-        warn(`${s.name}  ${yellow5("STALE")}  ${dim6(s.scope)}`);
+        warn(`${s.name}  ${yellow7("STALE")}  ${dim8(s.scope)}`);
       }
     }
   }
   section("pi  (coding agent runtime)");
   if (!piInstalled) {
-    fail(`pi not installed — install ${yellow5("pi")} first`);
+    fail(`pi not installed — install ${yellow7("pi")} first`);
   } else {
     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");
+    const pStr = piProviders.size > 0 ? `${piProviders.size} provider${piProviders.size > 1 ? "s" : ""} active  ${dim8(`(${[...piProviders].join(", ")})`)} ` : yellow7("no providers configured — run pi config");
     ok2(`${vStr}  —  ${pStr}`);
   }
   section("beads  (issue tracker)");
   if (!bdInstalled) {
-    fail(`bd not installed — install ${yellow5("bd")} first`);
+    fail(`bd not installed — install ${yellow7("bd")} first`);
   } else {
-    ok2(`bd installed${bdVersion?.ok ? `  ${dim6(bdVersion.stdout)}` : ""}`);
+    ok2(`bd installed${bdVersion?.ok ? `  ${dim8(bdVersion.stdout)}` : ""}`);
     if (beadsPresent) {
       ok2(".beads/ present in project");
     } else {
-      warn(`.beads/ not found — run ${yellow5("bd init")} to enable issue tracking`);
+      warn(`.beads/ not found — run ${yellow7("bd init")} to enable issue tracking`);
     }
   }
   section("MCP");
   if (!specialistsBin.ok) {
-    fail(`specialists not installed globally — run ${yellow5("npm install -g @jaggerxtrm/specialists")}`);
+    fail(`specialists not installed globally — run ${yellow7("npm install -g @jaggerxtrm/specialists")}`);
   } else {
-    ok2(`specialists binary installed  ${dim6(specialistsBin.stdout)}`);
+    ok2(`specialists binary installed  ${dim8(specialistsBin.stdout)}`);
     info(`verify registration: claude mcp get specialists`);
     info(`re-register:         specialists install`);
   }
-  if (jobs.length > 0) {
-    section("Active Jobs");
+  section("Active Jobs");
+  if (jobs.length === 0) {
+    info("  (none)");
+  } else {
     for (const job of jobs) {
       const elapsed = formatElapsed2(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}`);
+      const detail = job.status === "error" ? red2(job.error?.slice(0, 40) ?? "error") : job.current_tool ? dim8(`tool: ${job.current_tool}`) : dim8(job.current_event ?? "");
+      console.log(`  ${dim8(job.id)}  ${job.specialist.padEnd(20)}  ${statusColor(job.status).padEnd(7)}  ${elapsed.padStart(6)}  ${detail}`);
     }
   }
   console.log();
@@ -19934,51 +20270,57 @@ var init_status = __esm(() => {
 // src/cli/result.ts
 var exports_result = {};
 __export(exports_result, {
-  run: () => run9
+  run: () => run10
 });
-import { existsSync as existsSync8, readFileSync as readFileSync5 } from "node:fs";
-import { join as join12 } from "node:path";
-async function run9() {
+import { existsSync as existsSync10, readFileSync as readFileSync5 } from "node:fs";
+import { join as join13 } from "node:path";
+async function run10() {
   const jobId = process.argv[3];
   if (!jobId) {
     console.error("Usage: specialists|sp result <job-id>");
     process.exit(1);
   }
-  const jobsDir = join12(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) {
     console.error(`No job found: ${jobId}`);
     process.exit(1);
   }
+  const resultPath = join13(jobsDir, jobId, "result.txt");
   if (status.status === "running" || status.status === "starting") {
-    process.stderr.write(`${dim7(`Job ${jobId} is still ${status.status}. Use 'specialists feed --job ${jobId}' to follow.`)}
+    if (!existsSync10(resultPath)) {
+      process.stderr.write(`${dim9(`Job ${jobId} is still ${status.status}. Use 'specialists feed --job ${jobId}' to follow.`)}
 `);
-    process.exit(1);
+      process.exit(1);
+    }
+    process.stderr.write(`${dim9(`Job ${jobId} is currently ${status.status}. Showing last completed output while it continues.`)}
+`);
+    process.stdout.write(readFileSync5(resultPath, "utf-8"));
+    return;
   }
   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 = join12(jobsDir, jobId, "result.txt");
-  if (!existsSync8(resultPath)) {
+  if (!existsSync10(resultPath)) {
     console.error(`Result file not found for job ${jobId}`);
     process.exit(1);
   }
   process.stdout.write(readFileSync5(resultPath, "utf-8"));
 }
-var dim7 = (s) => `\x1B[2m${s}\x1B[0m`, red2 = (s) => `\x1B[31m${s}\x1B[0m`;
+var dim9 = (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 existsSync9, readdirSync as readdirSync3, readFileSync as readFileSync6 } from "node:fs";
-import { join as join13 } from "node:path";
+import { existsSync as existsSync11, readdirSync as readdirSync3, readFileSync as readFileSync6 } from "node:fs";
+import { join as join14 } from "node:path";
 function readJobEvents(jobDir) {
-  const eventsPath = join13(jobDir, "events.jsonl");
-  if (!existsSync9(eventsPath))
+  const eventsPath = join14(jobDir, "events.jsonl");
+  if (!existsSync11(eventsPath))
     return [];
   const content = readFileSync6(eventsPath, "utf-8");
   const lines = content.split(`
@@ -19993,15 +20335,15 @@ function readJobEvents(jobDir) {
   return events;
 }
 function readJobEventsById(jobsDir, jobId) {
-  return readJobEvents(join13(jobsDir, jobId));
+  return readJobEvents(join14(jobsDir, jobId));
 }
 function readAllJobEvents(jobsDir) {
-  if (!existsSync9(jobsDir))
+  if (!existsSync11(jobsDir))
     return [];
   const batches = [];
   const entries = readdirSync3(jobsDir);
   for (const entry of entries) {
-    const jobDir = join13(jobsDir, entry);
+    const jobDir = join14(jobsDir, entry);
     try {
       const stat2 = __require("node:fs").statSync(jobDir);
       if (!stat2.isDirectory())
@@ -20010,10 +20352,10 @@ function readAllJobEvents(jobsDir) {
       continue;
     }
     const jobId = entry;
-    const statusPath = join13(jobDir, "status.json");
+    const statusPath = join14(jobDir, "status.json");
     let specialist = "unknown";
     let beadId;
-    if (existsSync9(statusPath)) {
+    if (existsSync11(statusPath)) {
       try {
         const status = JSON.parse(readFileSync6(statusPath, "utf-8"));
         specialist = status.specialist ?? "unknown";
@@ -20076,10 +20418,10 @@ var init_timeline_query = __esm(() => {
 // src/cli/feed.ts
 var exports_feed = {};
 __export(exports_feed, {
-  run: () => run10
+  run: () => run11
 });
-import { existsSync as existsSync10 } from "node:fs";
-import { join as join14 } from "node:path";
+import { existsSync as existsSync12 } from "node:fs";
+import { join as join15 } from "node:path";
 function getHumanEventKey(event) {
   switch (event.type) {
     case "meta":
@@ -20090,6 +20432,10 @@ function getHumanEventKey(event) {
       return "text";
     case "thinking":
       return "thinking";
+    case "message":
+      return `message:${event.role}:${event.phase}`;
+    case "turn":
+      return `turn:${event.phase}`;
     case "run_start":
       return `run_start:${event.specialist}:${event.bead_id ?? ""}`;
     case "run_complete":
@@ -20127,7 +20473,7 @@ function parseSince(value) {
   }
   return;
 }
-function parseArgs5(argv) {
+function parseArgs6(argv) {
   let jobId;
   let specialist;
   let since;
@@ -20172,7 +20518,7 @@ function parseArgs5(argv) {
 function printSnapshot(merged, options) {
   if (merged.length === 0) {
     if (!options.json)
-      console.log(dim6("No events found."));
+      console.log(dim8("No events found."));
     return;
   }
   const colorMap = new JobColorMap;
@@ -20218,13 +20564,13 @@ async function followMerged(jobsDir, options) {
   const initialBatchCount = filteredBatches().length;
   if (!options.forever && initialBatchCount > 0 && completedJobs.size === initialBatchCount) {
     if (!options.json) {
-      process.stderr.write(dim6(`All jobs complete.
+      process.stderr.write(dim8(`All jobs complete.
 `));
     }
     return;
   }
   if (!options.json) {
-    process.stderr.write(dim6(`Following... (Ctrl+C to stop)
+    process.stderr.write(dim8(`Following... (Ctrl+C to stop)
 `));
   }
   const lastPrintedEventKey = new Map;
@@ -20271,11 +20617,37 @@ async function followMerged(jobsDir, options) {
     }, 500);
   });
 }
-async function run10() {
-  const options = parseArgs5(process.argv.slice(3));
-  const jobsDir = join14(process.cwd(), ".specialists", "jobs");
-  if (!existsSync10(jobsDir)) {
-    console.log(dim6("No jobs directory found."));
+function showUsage() {
+  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
+`);
+}
+async function run11() {
+  const options = parseArgs6(process.argv.slice(3));
+  if (!options.jobId && !options.follow) {
+    showUsage();
+    process.exit(1);
+  }
+  const jobsDir = join15(process.cwd(), ".specialists", "jobs");
+  if (!existsSync12(jobsDir)) {
+    console.log(dim8("No jobs directory found."));
     return;
   }
   if (options.follow) {
@@ -20299,11 +20671,11 @@ var init_feed = __esm(() => {
 // src/cli/poll.ts
 var exports_poll = {};
 __export(exports_poll, {
-  run: () => run11
+  run: () => run12
 });
-import { existsSync as existsSync11, readFileSync as readFileSync7 } from "node:fs";
-import { join as join15 } from "node:path";
-function parseArgs6(argv) {
+import { existsSync as existsSync13, readFileSync as readFileSync7 } from "node:fs";
+import { join as join16 } from "node:path";
+function parseArgs7(argv) {
   let jobId;
   let cursor = 0;
   let json = false;
@@ -20328,11 +20700,11 @@ function parseArgs6(argv) {
   }
   return { jobId, cursor, json };
 }
-async function run11() {
-  const { jobId, cursor, json } = parseArgs6(process.argv.slice(3));
-  const jobsDir = join15(process.cwd(), ".specialists", "jobs");
-  const jobDir = join15(jobsDir, jobId);
-  if (!existsSync11(jobDir)) {
+async function run12() {
+  const { jobId, cursor, json } = parseArgs7(process.argv.slice(3));
+  const jobsDir = join16(process.cwd(), ".specialists", "jobs");
+  const jobDir = join16(jobsDir, jobId);
+  if (!existsSync13(jobDir)) {
     const result2 = {
       job_id: jobId,
       status: "error",
@@ -20346,16 +20718,16 @@ async function run11() {
     console.log(JSON.stringify(result2));
     process.exit(1);
   }
-  const statusPath = join15(jobDir, "status.json");
+  const statusPath = join16(jobDir, "status.json");
   let status = null;
-  if (existsSync11(statusPath)) {
+  if (existsSync13(statusPath)) {
     try {
       status = JSON.parse(readFileSync7(statusPath, "utf-8"));
     } catch {}
   }
-  const resultPath = join15(jobDir, "result.txt");
+  const resultPath = join16(jobDir, "result.txt");
   let output = "";
-  if (existsSync11(resultPath)) {
+  if (existsSync13(resultPath)) {
     try {
       output = readFileSync7(resultPath, "utf-8");
     } catch {}
@@ -20410,18 +20782,18 @@ var init_poll = __esm(() => {
 // src/cli/steer.ts
 var exports_steer = {};
 __export(exports_steer, {
-  run: () => run12
+  run: () => run13
 });
-import { join as join16 } from "node:path";
+import { join as join17 } from "node:path";
 import { writeFileSync as writeFileSync6 } from "node:fs";
-async function run12() {
+async function run13() {
   const jobId = process.argv[3];
   const message = process.argv[4];
   if (!jobId || !message) {
     console.error('Usage: specialists|sp steer <job-id> "<message>"');
     process.exit(1);
   }
-  const jobsDir = join16(process.cwd(), ".specialists", "jobs");
+  const jobsDir = join17(process.cwd(), ".specialists", "jobs");
   const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
   const status = supervisor.readStatus(jobId);
   if (!status) {
@@ -20434,7 +20806,7 @@ async function run12() {
     process.exit(1);
   }
   if (!status.fifo_path) {
-    process.stderr.write(`${red3("Error:")} Job ${jobId} has no steer pipe.
+    process.stderr.write(`${red4("Error:")} Job ${jobId} has no steer pipe.
 `);
     process.stderr.write(`Only jobs started with --background support mid-run steering.
 `);
@@ -20444,15 +20816,15 @@ async function run12() {
     const payload = JSON.stringify({ type: "steer", message }) + `
 `;
     writeFileSync6(status.fifo_path, payload, { flag: "a" });
-    process.stdout.write(`${green7("✓")} Steer message sent to job ${jobId}
+    process.stdout.write(`${green8("✓")} Steer message sent to job ${jobId}
 `);
   } catch (err) {
-    process.stderr.write(`${red3("Error:")} Failed to write to steer pipe: ${err?.message}
+    process.stderr.write(`${red4("Error:")} Failed to write to steer pipe: ${err?.message}
 `);
     process.exit(1);
   }
 }
-var green7 = (s) => `\x1B[32m${s}\x1B[0m`, red3 = (s) => `\x1B[31m${s}\x1B[0m`;
+var green8 = (s) => `\x1B[32m${s}\x1B[0m`, red4 = (s) => `\x1B[31m${s}\x1B[0m`;
 var init_steer = __esm(() => {
   init_supervisor();
 });
@@ -20460,18 +20832,18 @@ var init_steer = __esm(() => {
 // src/cli/follow-up.ts
 var exports_follow_up = {};
 __export(exports_follow_up, {
-  run: () => run13
+  run: () => run14
 });
-import { join as join17 } from "node:path";
+import { join as join18 } from "node:path";
 import { writeFileSync as writeFileSync7 } from "node:fs";
-async function run13() {
+async function run14() {
   const jobId = process.argv[3];
   const message = process.argv[4];
   if (!jobId || !message) {
     console.error('Usage: specialists|sp follow-up <job-id> "<message>"');
     process.exit(1);
   }
-  const jobsDir = join17(process.cwd(), ".specialists", "jobs");
+  const jobsDir = join18(process.cwd(), ".specialists", "jobs");
   const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
   const status = supervisor.readStatus(jobId);
   if (!status) {
@@ -20479,14 +20851,14 @@ async function run13() {
     process.exit(1);
   }
   if (status.status !== "waiting") {
-    process.stderr.write(`${red4("Error:")} Job ${jobId} is not in waiting state (status: ${status.status}).
+    process.stderr.write(`${red5("Error:")} Job ${jobId} is not in waiting state (status: ${status.status}).
 `);
     process.stderr.write(`Only jobs started with --keep-alive and --background support follow-up prompts.
 `);
     process.exit(1);
   }
   if (!status.fifo_path) {
-    process.stderr.write(`${red4("Error:")} Job ${jobId} has no steer pipe.
+    process.stderr.write(`${red5("Error:")} Job ${jobId} has no steer pipe.
 `);
     process.exit(1);
   }
@@ -20494,17 +20866,17 @@ async function run13() {
     const payload = JSON.stringify({ type: "prompt", message }) + `
 `;
     writeFileSync7(status.fifo_path, payload, { flag: "a" });
-    process.stdout.write(`${green8("✓")} Follow-up sent to job ${jobId}
+    process.stdout.write(`${green9("✓")} Follow-up sent to job ${jobId}
 `);
     process.stdout.write(`  Use 'specialists feed ${jobId} --follow' to watch the response.
 `);
   } catch (err) {
-    process.stderr.write(`${red4("Error:")} Failed to write to steer pipe: ${err?.message}
+    process.stderr.write(`${red5("Error:")} Failed to write to steer pipe: ${err?.message}
 `);
     process.exit(1);
   }
 }
-var green8 = (s) => `\x1B[32m${s}\x1B[0m`, red4 = (s) => `\x1B[31m${s}\x1B[0m`;
+var green9 = (s) => `\x1B[32m${s}\x1B[0m`, red5 = (s) => `\x1B[31m${s}\x1B[0m`;
 var init_follow_up = __esm(() => {
   init_supervisor();
 });
@@ -20512,16 +20884,16 @@ var init_follow_up = __esm(() => {
 // src/cli/stop.ts
 var exports_stop = {};
 __export(exports_stop, {
-  run: () => run14
+  run: () => run15
 });
-import { join as join18 } from "node:path";
-async function run14() {
+import { join as join19 } from "node:path";
+async function run15() {
   const jobId = process.argv[3];
   if (!jobId) {
     console.error("Usage: specialists|sp stop <job-id>");
     process.exit(1);
   }
-  const jobsDir = join18(process.cwd(), ".specialists", "jobs");
+  const jobsDir = join19(process.cwd(), ".specialists", "jobs");
   const supervisor = new Supervisor({ runner: null, runOptions: null, jobsDir });
   const status = supervisor.readStatus(jobId);
   if (!status) {
@@ -20529,31 +20901,31 @@ async function run14() {
     process.exit(1);
   }
   if (status.status === "done" || status.status === "error") {
-    process.stderr.write(`${dim8(`Job ${jobId} is already ${status.status}.`)}
+    process.stderr.write(`${dim10(`Job ${jobId} is already ${status.status}.`)}
 `);
     return;
   }
   if (!status.pid) {
-    process.stderr.write(`${red5(`No PID recorded for job ${jobId}.`)}
+    process.stderr.write(`${red6(`No PID recorded for job ${jobId}.`)}
 `);
     process.exit(1);
   }
   try {
     process.kill(status.pid, "SIGTERM");
-    process.stdout.write(`${green9("✓")} Sent SIGTERM to PID ${status.pid} (job ${jobId})
+    process.stdout.write(`${green10("✓")} Sent SIGTERM to PID ${status.pid} (job ${jobId})
 `);
   } catch (err) {
     if (err.code === "ESRCH") {
-      process.stderr.write(`${red5(`Process ${status.pid} not found.`)} Job may have already completed.
+      process.stderr.write(`${red6(`Process ${status.pid} not found.`)} Job may have already completed.
 `);
     } else {
-      process.stderr.write(`${red5("Error:")} ${err.message}
+      process.stderr.write(`${red6("Error:")} ${err.message}
 `);
       process.exit(1);
     }
   }
 }
-var green9 = (s) => `\x1B[32m${s}\x1B[0m`, red5 = (s) => `\x1B[31m${s}\x1B[0m`, dim8 = (s) => `\x1B[2m${s}\x1B[0m`;
+var green10 = (s) => `\x1B[32m${s}\x1B[0m`, red6 = (s) => `\x1B[31m${s}\x1B[0m`, dim10 = (s) => `\x1B[2m${s}\x1B[0m`;
 var init_stop = __esm(() => {
   init_supervisor();
 });
@@ -20561,33 +20933,33 @@ var init_stop = __esm(() => {
 // src/cli/quickstart.ts
 var exports_quickstart = {};
 __export(exports_quickstart, {
-  run: () => run15
+  run: () => run16
 });
 function section2(title) {
   const bar = "─".repeat(60);
   return `
-${bold7(cyan5(title))}
-${dim9(bar)}`;
+${bold9(cyan6(title))}
+${dim11(bar)}`;
 }
 function cmd2(s) {
-  return yellow6(s);
+  return yellow8(s);
 }
 function flag(s) {
-  return green10(s);
+  return green11(s);
 }
-async function run15() {
+async function run16() {
   const lines = [
     "",
-    bold7("specialists  ·  Quick Start Guide"),
-    dim9("One MCP server. Multiple AI backends. Intelligent orchestration."),
-    dim9("Tip: sp is a shorter alias — sp run, sp list, sp feed etc. work identically."),
+    bold9("specialists  ·  Quick Start Guide"),
+    dim11("One MCP server. Multiple AI backends. Intelligent orchestration."),
+    dim11("Tip: sp is a shorter alias — sp run, sp list, sp feed etc. work identically."),
     ""
   ];
   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(`  ${cmd2("specialists init")}                         # project setup:`);
+  lines.push(`  ${dim11("                                            #   creates dirs, wires MCP + hooks, injects context")}`);
   lines.push("");
   lines.push(`  Verify everything is healthy:`);
   lines.push(`  ${cmd2("specialists status")}                        # shows pi, beads, MCP, active jobs`);
@@ -20598,9 +20970,9 @@ async function run15() {
   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(`  ${dim11("specialists/")}       — put your .specialist.yaml files here`);
+  lines.push(`  ${dim11(".specialists/")}      — runtime data (jobs/, ready/) — gitignored`);
+  lines.push(`  ${dim11("AGENTS.md")}          — context block injected into Claude sessions`);
   lines.push("");
   lines.push(section2("3. Discover Specialists"));
   lines.push("");
@@ -20616,66 +20988,64 @@ async function run15() {
   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(`  ${bold9("Foreground")} (streams output to stdout):`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--prompt")} ${dim11('"Review src/api.ts for security issues"')}`);
   lines.push("");
-  lines.push(`  ${bold7("Follow")} (background + stream live output in one command):`);
-  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--prompt")} ${dim9('"..."')} ${flag("--follow")}`);
-  lines.push(`  ${dim9("  # starts in background, streams output live, exits when complete")}`);
+  lines.push(`  ${bold9("Tracked run")} (linked to a beads issue for workflow integration):`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--bead")} ${dim11("unitAI-abc")}`);
+  lines.push(`  ${dim11("  # uses bead description as prompt, tracks result in issue")}`);
   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(`  ${cmd2("specialists run code-review")} ${flag("--model")} ${dim11("anthropic/claude-opus-4-6")} ${flag("--prompt")} ${dim11('"..."')}`);
   lines.push("");
   lines.push(`  Run without beads issue tracking:`);
-  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--no-beads")} ${flag("--prompt")} ${dim9('"..."')}`);
+  lines.push(`  ${cmd2("specialists run code-review")} ${flag("--no-beads")} ${flag("--prompt")} ${dim11('"..."')}`);
   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(`  Use Claude Code's native backgrounding or run in a separate terminal.`);
+  lines.push("");
+  lines.push(`  ${bold9("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(`  ${bold9("Read results")} — print the final output:`);
   lines.push(`  ${cmd2("specialists result job_a1b2c3d4")}          # exits 1 if still running`);
   lines.push("");
-  lines.push(`  ${bold7("Steer a running job")} — redirect the agent mid-run without cancelling:`);
+  lines.push(`  ${bold9("Steer a running job")} — redirect the agent mid-run without cancelling:`);
   lines.push(`  ${cmd2("specialists steer job_a1b2c3d4")} ${flag('"focus only on supervisor.ts"')}`);
-  lines.push(`  ${dim9("  # delivered after current tool calls finish, before the next LLM call")}`);
+  lines.push(`  ${dim11("  # delivered after current tool calls finish, before the next LLM call")}`);
   lines.push("");
-  lines.push(`  ${bold7("Keep-alive multi-turn")} — start with ${flag("--keep-alive")}, then follow up:`);
-  lines.push(`  ${cmd2("specialists run bug-hunt")} ${flag("--bead unitAI-abc --keep-alive --background")}`);
-  lines.push(`  ${dim9("  # → Job started: a1b2c3  (status: waiting after first turn)")}`);
+  lines.push(`  ${bold9("Keep-alive multi-turn")} — start with ${flag("--keep-alive")}, then follow up:`);
+  lines.push(`  ${cmd2("specialists run debugger")} ${flag("--bead unitAI-abc --keep-alive")}`);
+  lines.push(`  ${dim11("  # → status: waiting after first turn")}`);
   lines.push(`  ${cmd2("specialists result a1b2c3")}                   # read first turn`);
   lines.push(`  ${cmd2("specialists follow-up a1b2c3")} ${flag('"now write the fix"')}    # next turn, same Pi context`);
   lines.push(`  ${cmd2("specialists feed a1b2c3")} ${flag("--follow")}               # watch response`);
   lines.push("");
-  lines.push(`  ${bold7("Cancel a job")}:`);
+  lines.push(`  ${bold9("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(`  ${dim9("steer.pipe")}    — named FIFO for mid-run steering (removed on job completion)`);
+  lines.push(`  ${bold9("Job files")} in ${dim11(".specialists/jobs/<job-id>/")}:`);
+  lines.push(`  ${dim11("status.json")}   — id, specialist, status, pid, started_at, elapsed_s, current_tool`);
+  lines.push(`  ${dim11("events.jsonl")} — one JSON event per line (tool_use, text, agent_end, error …)`);
+  lines.push(`  ${dim11("result.txt")}    — final output (written when status=done)`);
+  lines.push(`  ${dim11("steer.pipe")}    — named FIFO for mid-run steering (removed on job completion)`);
   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(`  ${cmd2("specialists edit code-review")} ${flag("--model")} ${dim11("anthropic/claude-sonnet-4-6")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--description")} ${dim11('"Updated description"')}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--timeout")} ${dim11("120000")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--permission")} ${dim11("HIGH")}`);
+  lines.push(`  ${cmd2("specialists edit code-review")} ${flag("--tags")} ${dim11("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(`  ${cmd2("specialists edit code-review")} ${flag("--model")} ${dim11("...")} ${flag("--dry-run")}`);
   lines.push("");
   lines.push(section2("7. .specialist.yaml Schema"));
   lines.push("");
@@ -20722,100 +21092,98 @@ async function run15() {
     "    priority: 2                  # 0=critical … 4=backlog"
   ];
   for (const l of schemaLines) {
-    lines.push(`  ${dim9(l)}`);
+    lines.push(`  ${dim11(l)}`);
   }
   lines.push("");
   lines.push(section2("8. Hook System"));
   lines.push("");
-  lines.push(`  Specialists emits lifecycle events to ${dim9(".specialists/trace.jsonl")}:`);
+  lines.push(`  Specialists emits lifecycle events to ${dim11(".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(`  ${bold9("Hook point")}              ${bold9("When fired")}`);
+  lines.push(`  ${yellow8("specialist:start")}       before the agent session begins`);
+  lines.push(`  ${yellow8("specialist:token")}       on each streamed token (delta)`);
+  lines.push(`  ${yellow8("specialist:done")}        after successful completion`);
+  lines.push(`  ${yellow8("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(`  ${dim11('{"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(`  After ${cmd2("specialists init")}, 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("steer_specialist")}      — send a mid-run message to a running job`);
-  lines.push(`  ${bold7("follow_up_specialist")} — send a next-turn prompt to a keep-alive session`);
-  lines.push(`  ${bold7("stop_specialist")}      — cancel a running job by ID`);
-  lines.push(`  ${bold7("specialist_status")}  — circuit breaker health + staleness`);
+  lines.push(`  ${bold9("specialist_init")}    — bootstrap: bd init + list specialists`);
+  lines.push(`  ${bold9("list_specialists")}   — discover specialists (project/user/system)`);
+  lines.push(`  ${bold9("use_specialist")}     — full lifecycle: load → agents.md → run → output`);
+  lines.push(`  ${bold9("run_parallel")}       — concurrent or pipeline execution`);
+  lines.push(`  ${bold9("start_specialist")}   — async job start, returns job ID`);
+  lines.push(`  ${bold9("poll_specialist")}    — poll job status/output by ID`);
+  lines.push(`  ${bold9("steer_specialist")}      — send a mid-run message to a running job`);
+  lines.push(`  ${bold9("follow_up_specialist")} — send a next-turn prompt to a keep-alive session`);
+  lines.push(`  ${bold9("stop_specialist")}      — cancel a running job by ID`);
+  lines.push(`  ${bold9("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(`  ${bold9("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(`  ${bold9("Tracked run with beads integration:")}`);
+  lines.push(`  ${cmd2("specialists run deep-analysis --bead unitAI-abc")}`);
+  lines.push(`  ${dim11("  # prompt from bead, result tracked in bead")}`);
   lines.push("");
-  lines.push(`  ${bold7("Steer a job mid-run:")}`);
-  lines.push(`  ${cmd2('specialists run deep-analysis --prompt "..." --background')}`);
+  lines.push(`  ${bold9("Steer a job mid-run:")}`);
   lines.push(`  ${cmd2('specialists steer <job-id> "focus only on the auth module"')}`);
   lines.push(`  ${cmd2("specialists result <job-id>")}`);
   lines.push("");
-  lines.push(`  ${bold7("Multi-turn keep-alive (iterative work):")}`);
-  lines.push(`  ${cmd2("specialists run bug-hunt --bead unitAI-abc --keep-alive --background")}`);
+  lines.push(`  ${bold9("Multi-turn keep-alive (iterative work):")}`);
+  lines.push(`  ${cmd2("specialists run debugger --bead unitAI-abc --keep-alive")}`);
   lines.push(`  ${cmd2("specialists result <job-id>")}`);
   lines.push(`  ${cmd2('specialists follow-up <job-id> "now write the fix for the root cause"')}`);
   lines.push(`  ${cmd2("specialists feed <job-id> --follow")}`);
   lines.push("");
-  lines.push(`  ${bold7("Override model for a single run:")}`);
+  lines.push(`  ${bold9("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(dim11("─".repeat(62)));
+  lines.push(`  ${dim11("specialists help")}     command list         ${dim11("specialists <cmd> --help")}   per-command flags`);
+  lines.push(`  ${dim11("specialists status")}   health check         ${dim11("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`, cyan5 = (s) => `\x1B[36m${s}\x1B[0m`, blue2 = (s) => `\x1B[34m${s}\x1B[0m`, green10 = (s) => `\x1B[32m${s}\x1B[0m`;
+var bold9 = (s) => `\x1B[1m${s}\x1B[0m`, dim11 = (s) => `\x1B[2m${s}\x1B[0m`, yellow8 = (s) => `\x1B[33m${s}\x1B[0m`, cyan6 = (s) => `\x1B[36m${s}\x1B[0m`, blue2 = (s) => `\x1B[34m${s}\x1B[0m`, green11 = (s) => `\x1B[32m${s}\x1B[0m`;
 
 // src/cli/doctor.ts
 var exports_doctor = {};
 __export(exports_doctor, {
-  run: () => run16
+  run: () => run17
 });
 import { spawnSync as spawnSync7 } from "node:child_process";
-import { existsSync as existsSync12, mkdirSync as mkdirSync3, readFileSync as readFileSync8, readdirSync as readdirSync4 } from "node:fs";
-import { join as join19 } from "node:path";
+import { existsSync as existsSync14, mkdirSync as mkdirSync3, readFileSync as readFileSync8, readdirSync as readdirSync4 } from "node:fs";
+import { join as join20 } from "node:path";
 function ok3(msg) {
-  console.log(`  ${green11("✓")} ${msg}`);
+  console.log(`  ${green12("✓")} ${msg}`);
 }
 function warn2(msg) {
-  console.log(`  ${yellow7("○")} ${msg}`);
+  console.log(`  ${yellow9("○")} ${msg}`);
 }
 function fail2(msg) {
-  console.log(`  ${red6("✗")} ${msg}`);
+  console.log(`  ${red7("✗")} ${msg}`);
 }
 function fix(msg) {
-  console.log(`    ${dim10("→ fix:")} ${yellow7(msg)}`);
+  console.log(`    ${dim12("→ fix:")} ${yellow9(msg)}`);
 }
 function hint(msg) {
-  console.log(`    ${dim10(msg)}`);
+  console.log(`    ${dim12(msg)}`);
 }
 function section3(label) {
   const line = "─".repeat(Math.max(0, 38 - label.length));
   console.log(`
-${bold8(`── ${label} ${line}`)}`);
+${bold10(`── ${label} ${line}`)}`);
 }
 function sp(bin, args) {
   const r = spawnSync7(bin, args, { encoding: "utf8", stdio: "pipe", timeout: 5000 });
@@ -20825,7 +21193,7 @@ function isInstalled2(bin) {
   return spawnSync7("which", [bin], { encoding: "utf8", timeout: 2000 }).status === 0;
 }
 function loadJson2(path) {
-  if (!existsSync12(path))
+  if (!existsSync14(path))
     return null;
   try {
     return JSON.parse(readFileSync8(path, "utf8"));
@@ -20850,9 +21218,19 @@ function checkPi() {
     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(", ")})`)}`);
+  ok3(`pi ${vStr}  —  ${providers.size} provider${providers.size > 1 ? "s" : ""} active  ${dim12(`(${[...providers].join(", ")})`)}`);
   return true;
 }
+function checkSpAlias() {
+  section3("sp alias  (specialists shortcut)");
+  if (isInstalled2("sp")) {
+    ok3("sp alias installed");
+    return true;
+  }
+  fail2("sp alias not found in PATH");
+  fix("npm install -g @jaggerxtrm/specialists@latest   (reinstall to create symlink)");
+  return false;
+}
 function checkBd() {
   section3("beads  (issue tracker)");
   if (!isInstalled2("bd")) {
@@ -20860,8 +21238,8 @@ function checkBd() {
     fix("install beads (bd) first");
     return false;
   }
-  ok3(`bd installed  ${dim10(sp("bd", ["--version"]).stdout || "")}`);
-  if (existsSync12(join19(CWD, ".beads")))
+  ok3(`bd installed  ${dim12(sp("bd", ["--version"]).stdout || "")}`);
+  if (existsSync14(join20(CWD, ".beads")))
     ok3(".beads/ present in project");
   else
     warn2(".beads/ not found in project");
@@ -20874,16 +21252,16 @@ function checkXt() {
     fix("install xtrm-tools first");
     return false;
   }
-  ok3(`xt installed  ${dim10(sp("xt", ["--version"]).stdout || "")}`);
+  ok3(`xt installed  ${dim12(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 = join19(HOOKS_DIR, name);
-    if (!existsSync12(dest)) {
-      fail2(`${name}  ${red6("missing")}`);
+    const dest = join20(HOOKS_DIR, name);
+    if (!existsSync14(dest)) {
+      fail2(`${name}  ${red7("missing")}`);
       fix("specialists install");
       allPresent = false;
     } else {
@@ -20926,18 +21304,18 @@ function checkMCP() {
 }
 function checkRuntimeDirs() {
   section3(".specialists/ runtime directories");
-  const rootDir = join19(CWD, ".specialists");
-  const jobsDir = join19(rootDir, "jobs");
-  const readyDir = join19(rootDir, "ready");
+  const rootDir = join20(CWD, ".specialists");
+  const jobsDir = join20(rootDir, "jobs");
+  const readyDir = join20(rootDir, "ready");
   let allOk = true;
-  if (!existsSync12(rootDir)) {
+  if (!existsSync14(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 (!existsSync12(subDir)) {
+      if (!existsSync14(subDir)) {
         warn2(`.specialists/${label}/ missing — auto-creating`);
         mkdirSync3(subDir, { recursive: true });
         ok3(`.specialists/${label}/ created`);
@@ -20950,8 +21328,8 @@ function checkRuntimeDirs() {
 }
 function checkZombieJobs() {
   section3("Background jobs");
-  const jobsDir = join19(CWD, ".specialists", "jobs");
-  if (!existsSync12(jobsDir)) {
+  const jobsDir = join20(CWD, ".specialists", "jobs");
+  if (!existsSync14(jobsDir)) {
     hint("No .specialists/jobs/ — skipping");
     return true;
   }
@@ -20969,8 +21347,8 @@ function checkZombieJobs() {
   let total = 0;
   let running = 0;
   for (const jobId of entries) {
-    const statusPath = join19(jobsDir, jobId, "status.json");
-    if (!existsSync12(statusPath))
+    const statusPath = join20(jobsDir, jobId, "status.json");
+    if (!existsSync14(statusPath))
       continue;
     try {
       const status = JSON.parse(readFileSync8(statusPath, "utf8"));
@@ -20987,7 +21365,7 @@ function checkZombieJobs() {
             running++;
           else {
             zombies++;
-            warn2(`${jobId}  ${yellow7("ZOMBIE")}  ${dim10(`pid ${pid} not found, status=${status.status}`)}`);
+            warn2(`${jobId}  ${yellow9("ZOMBIE")}  ${dim12(`pid ${pid} not found, status=${status.status}`)}`);
             fix(`Edit .specialists/jobs/${jobId}/status.json  →  set "status": "error"`);
           }
         }
@@ -21000,11 +21378,12 @@ function checkZombieJobs() {
   }
   return zombies === 0;
 }
-async function run16() {
+async function run17() {
   console.log(`
-${bold8("specialists doctor")}
+${bold10("specialists doctor")}
 `);
   const piOk = checkPi();
+  const spOk = checkSpAlias();
   const bdOk = checkBd();
   const xtOk = checkXt();
   const hooksOk = checkHooks();
@@ -21014,21 +21393,21 @@ ${bold8("specialists doctor")}
   const allOk = piOk && bdOk && xtOk && hooksOk && mcpOk && dirsOk && jobsOk;
   console.log("");
   if (allOk) {
-    console.log(`  ${green11("✓")} ${bold8("All checks passed")}  — specialists is healthy`);
+    console.log(`  ${green12("✓")} ${bold10("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(`  ${yellow9("○")} ${bold10("Some checks failed")}  — follow the fix hints above`);
+    console.log(`  ${dim12("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`, green11 = (s) => `\x1B[32m${s}\x1B[0m`, yellow7 = (s) => `\x1B[33m${s}\x1B[0m`, red6 = (s) => `\x1B[31m${s}\x1B[0m`, CWD, CLAUDE_DIR, SPECIALISTS_DIR, HOOKS_DIR, SETTINGS_FILE, MCP_FILE2, HOOK_NAMES;
+var bold10 = (s) => `\x1B[1m${s}\x1B[0m`, dim12 = (s) => `\x1B[2m${s}\x1B[0m`, green12 = (s) => `\x1B[32m${s}\x1B[0m`, yellow9 = (s) => `\x1B[33m${s}\x1B[0m`, red7 = (s) => `\x1B[31m${s}\x1B[0m`, CWD, CLAUDE_DIR, SPECIALISTS_DIR, HOOKS_DIR, SETTINGS_FILE, MCP_FILE2, HOOK_NAMES;
 var init_doctor = __esm(() => {
   CWD = process.cwd();
-  CLAUDE_DIR = join19(CWD, ".claude");
-  SPECIALISTS_DIR = join19(CWD, ".specialists");
-  HOOKS_DIR = join19(SPECIALISTS_DIR, "default", "hooks");
-  SETTINGS_FILE = join19(CLAUDE_DIR, "settings.json");
-  MCP_FILE2 = join19(CWD, ".mcp.json");
+  CLAUDE_DIR = join20(CWD, ".claude");
+  SPECIALISTS_DIR = join20(CWD, ".specialists");
+  HOOKS_DIR = join20(SPECIALISTS_DIR, "default", "hooks");
+  SETTINGS_FILE = join20(CLAUDE_DIR, "settings.json");
+  MCP_FILE2 = join20(CWD, ".mcp.json");
   HOOK_NAMES = [
     "specialists-complete.mjs",
     "specialists-session-start.mjs"
@@ -21038,191 +21417,49 @@ var init_doctor = __esm(() => {
 // src/cli/setup.ts
 var exports_setup = {};
 __export(exports_setup, {
-  run: () => run17
+  run: () => run18
 });
-import { existsSync as existsSync13, readFileSync as readFileSync9, writeFileSync as writeFileSync8 } from "node:fs";
-import { homedir as homedir3 } from "node:os";
-import { join as join20, resolve as resolve2 } from "node:path";
-function ok4(msg) {
-  console.log(`  ${green12("✓")} ${msg}`);
-}
-function skip2(msg) {
-  console.log(`  ${yellow8("○")} ${msg}`);
-}
-function resolveTarget(target) {
-  switch (target) {
-    case "global":
-      return join20(homedir3(), ".claude", "CLAUDE.md");
-    case "agents":
-      return join20(process.cwd(), "AGENTS.md");
-    case "project":
-    default:
-      return join20(process.cwd(), "CLAUDE.md");
-  }
-}
-function parseArgs7() {
-  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 run17() {
-  const { target, dryRun } = parseArgs7();
-  const filePath = resolve2(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 (existsSync13(filePath)) {
-    const existing = readFileSync9(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(`
-`) ? `
-` : `
-
-`;
-    writeFileSync8(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;
-    }
-    writeFileSync8(filePath, WORKFLOW_BLOCK, "utf8");
-    ok4(`Created ${label} with Specialists Workflow section`);
-  }
+async function run18() {
+  console.log("");
+  console.log(yellow10("⚠ DEPRECATED: `specialists setup` is deprecated"));
+  console.log("");
+  console.log(`  Use ${bold11("specialists init")} instead.`);
   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("  The init command handles all setup tasks:");
+  console.log("    • creates specialists/ and .specialists/ directories");
+  console.log("    • adds .specialists/ to .gitignore");
+  console.log("    • registers the MCP server in .mcp.json");
+  console.log("    • injects workflow context into AGENTS.md/CLAUDE.md");
+  console.log("");
+  console.log("  Options:");
+  console.log("    --force-workflow   Overwrite existing workflow blocks");
+  console.log("");
+  console.log(`  ${dim13("Run: specialists init --help for full details")}`);
   console.log("");
 }
-var bold9 = (s) => `\x1B[1m${s}\x1B[0m`, dim11 = (s) => `\x1B[2m${s}\x1B[0m`, green12 = (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 = () => {};
+var bold11 = (s) => `\x1B[1m${s}\x1B[0m`, yellow10 = (s) => `\x1B[33m${s}\x1B[0m`, dim13 = (s) => `\x1B[2m${s}\x1B[0m`;
 
 // src/cli/help.ts
 var exports_help = {};
 __export(exports_help, {
-  run: () => run18
+  run: () => run19
 });
 function formatCommands(entries) {
   const width = Math.max(...entries.map(([cmd3]) => cmd3.length));
   return entries.map(([cmd3, desc]) => `  ${cmd3.padEnd(width)}   ${desc}`);
 }
-async function run18() {
+async function run19() {
   const lines = [
     "",
     "Specialists lets you run project-scoped specialist agents with a bead-first workflow.",
     "",
-    bold10("Usage:"),
+    bold12("Usage:"),
     "  specialists|sp [command]",
     "  specialists|sp [command] --help",
     "",
-    dim12("  sp is a shorter alias — sp run, sp list, sp feed etc. all work identically."),
+    dim14("  sp is a shorter alias — sp run, sp list, sp feed etc. all work identically."),
     "",
-    bold10("Common flows:"),
+    bold12("Common flows:"),
     "",
     "  Tracked work (primary)",
     '    bd create "Task title" -t task -p 1 --json',
@@ -21244,19 +21481,19 @@ async function run18() {
     "    or run in a separate terminal and poll with:",
     "      specialists poll <job-id> --json",
     "",
-    bold10("Core commands:"),
+    bold12("Core commands:"),
     ...formatCommands(CORE_COMMANDS),
     "",
-    bold10("Extended commands:"),
+    bold12("Extended commands:"),
     ...formatCommands(EXTENDED_COMMANDS),
     "",
-    bold10("xtrm worktree commands:"),
+    bold12("xtrm worktree commands:"),
     ...formatCommands(WORKTREE_COMMANDS),
     "",
-    bold10("Examples:"),
+    bold12("Examples:"),
     "  specialists init",
     "  specialists list",
-    "  specialists run bug-hunt --bead unitAI-123",
+    "  specialists run debugger --bead unitAI-123",
     '  specialists run codebase-explorer --prompt "Map the CLI architecture"',
     "  specialists poll abc123 --json                  # check job status",
     "  specialists feed -f                             # stream all job events",
@@ -21264,7 +21501,7 @@ async function run18() {
     '  specialists follow-up <job-id> "now write the fix"',
     "  specialists result <job-id>",
     "",
-    bold10("More help:"),
+    bold12("More help:"),
     "  specialists quickstart         Full guide and workflow reference",
     "  specialists run --help         Run command details and flags",
     "  specialists poll --help        Job status polling details",
@@ -21273,17 +21510,18 @@ async function run18() {
     "  specialists init --help        Bootstrap behavior and workflow injection",
     "  specialists feed --help        Job event streaming details",
     "",
-    dim12("Project model: specialists are project-only; user-scope discovery is deprecated."),
+    dim14("Project model: specialists are project-only; user-scope discovery is deprecated."),
     ""
   ];
   console.log(lines.join(`
 `));
 }
-var bold10 = (s) => `\x1B[1m${s}\x1B[0m`, dim12 = (s) => `\x1B[2m${s}\x1B[0m`, CORE_COMMANDS, EXTENDED_COMMANDS, WORKTREE_COMMANDS;
+var bold12 = (s) => `\x1B[1m${s}\x1B[0m`, dim14 = (s) => `\x1B[2m${s}\x1B[0m`, CORE_COMMANDS, EXTENDED_COMMANDS, WORKTREE_COMMANDS;
 var init_help = __esm(() => {
   CORE_COMMANDS = [
     ["init", "Bootstrap a project: dirs, workflow injection, project MCP registration"],
     ["list", "List specialists in this project"],
+    ["validate", "Validate a specialist YAML against the schema"],
     ["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"],
     ["poll", "Machine-readable job status polling (for scripts/Claude Code)"],
@@ -29279,23 +29517,20 @@ var next = process.argv[3];
 function wantsHelp() {
   return next === "--help" || next === "-h";
 }
-async function run19() {
+async function run20() {
   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.",
+        "⚠ DEPRECATED: Use `specialists init` instead.",
         "",
-        "No flags — just run it.",
+        "The install command is deprecated. Run `specialists init` for project setup.",
         ""
       ].join(`
 `));
       return;
     }
-    const { run: handler } = await Promise.resolve().then(() => (init_install(), exports_install));
+    const { run: handler } = await Promise.resolve().then(() => exports_install);
     return handler();
   }
   if (sub === "version" || sub === "--version" || sub === "-v") {
@@ -29384,6 +29619,38 @@ async function run19() {
     const { run: handler } = await Promise.resolve().then(() => (init_init(), exports_init));
     return handler();
   }
+  if (sub === "validate") {
+    if (wantsHelp()) {
+      console.log([
+        "",
+        "Usage: specialists validate <name> [--json]",
+        "",
+        "Validate a specialist YAML file against the schema.",
+        "",
+        "What it checks:",
+        "  - YAML syntax is valid",
+        "  - Required fields are present (name, version, description, category, model)",
+        "  - Field values match expected formats (kebab-case names, semver versions)",
+        "  - Enum values are valid (permission_required, mode, beads_integration)",
+        "",
+        "Options:",
+        "  --json   Output validation result as JSON",
+        "",
+        "Examples:",
+        "  specialists validate my-specialist",
+        "  specialists validate my-specialist --json",
+        "",
+        "Exit codes:",
+        "  0 — validation passed",
+        "  1 — validation failed (errors) or specialist not found",
+        ""
+      ].join(`
+`));
+      return;
+    }
+    const { run: handler } = await Promise.resolve().then(() => (init_validate(), exports_validate));
+    return handler();
+  }
   if (sub === "edit") {
     if (wantsHelp()) {
       console.log([
@@ -29402,7 +29669,7 @@ async function run19() {
         "",
         "Options:",
         "  --dry-run                Preview the change without writing",
-        "  --scope <project|user>   Disambiguate if same name exists in multiple scopes",
+        "  --scope <default|user>   Disambiguate if same name exists in multiple scopes",
         "",
         "Examples:",
         "  specialists edit code-review --model anthropic/claude-opus-4-6",
@@ -29437,8 +29704,8 @@ async function run19() {
         "  --keep-alive         Keep session alive for follow-up prompts",
         "",
         "Examples:",
-        "  specialists run bug-hunt --bead unitAI-55d",
-        "  specialists run bug-hunt --bead unitAI-55d --context-depth 2",
+        "  specialists run debugger --bead unitAI-55d",
+        "  specialists run debugger --bead unitAI-55d --context-depth 2",
         '  specialists run code-review --prompt "Audit src/api.ts"',
         "  cat brief.md | specialists run report-generator",
         "",
@@ -29603,7 +29870,7 @@ async function run19() {
         '  specialists steer a1b2c3 "skip tests, just fix the bug"',
         "",
         "Notes:",
-        "  - Only works for jobs started with --background.",
+        "  - Only works for running jobs.",
         "  - Delivery is best-effort: the agent processes it on its next turn.",
         ""
       ].join(`
@@ -29622,14 +29889,14 @@ async function run19() {
         "Send a follow-up prompt to a waiting keep-alive specialist session.",
         "The Pi session retains full conversation history between turns.",
         "",
-        "Requires: job started with --keep-alive --background.",
+        "Requires: job started with --keep-alive.",
         "",
         "Examples:",
         '  specialists follow-up a1b2c3 "Now write the fix for the bug you found"',
         '  specialists follow-up a1b2c3 "Focus only on the auth module"',
         "",
         "Workflow:",
-        "  specialists run bug-hunt --bead <id> --keep-alive --background",
+        "  specialists run debugger --bead <id> --keep-alive",
         "  # → Job started: a1b2c3  (status: waiting after first turn)",
         "  specialists result a1b2c3            # read first turn output",
         '  specialists follow-up a1b2c3 "..."   # send next prompt',
@@ -29702,28 +29969,15 @@ async function run19() {
     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.",
+        "⚠ DEPRECATED: Use `specialists init` instead.",
         "",
-        "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",
+        "The setup command is deprecated. Run `specialists init` for project setup.",
         ""
       ].join(`
 `));
       return;
     }
-    const { run: handler } = await Promise.resolve().then(() => (init_setup(), exports_setup));
+    const { run: handler } = await Promise.resolve().then(() => exports_setup);
     return handler();
   }
   if (sub === "help" || sub === "--help" || sub === "-h") {
@@ -29739,7 +29993,7 @@ Run 'specialists help' to see available commands.`);
   const server = new SpecialistsServer;
   await server.start();
 }
-run19().catch((error2) => {
+run20().catch((error2) => {
   logger.error(`Fatal error: ${error2}`);
   process.exit(1);
 });