zelari-code 1.0.2 → 1.0.3

package/dist/cli/main.bundled.js

@@ -1,7 +1,9 @@
 #!/usr/bin/env node
 import { createRequire as __crq } from 'node:module'; const require = __crq(import.meta.url);
 var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
 var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
 var __esm = (fn, res) => function __init() {
   return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
 };
@@ -9,6 +11,15 @@ var __export = (target, all) => {
   for (var name in all)
     __defProp(target, name, { get: all[name], enumerable: true });
 };
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
 
 // src/cli/grokOAuth.ts
 var grokOAuth_exports = {};
@@ -1522,10 +1533,10 @@ function mergeDefs(...defs) {
 function cloneDef(schema) {
   return mergeDefs(schema._zod.def);
 }
-function getElementAtPath(obj, path24) {
-  if (!path24)
+function getElementAtPath(obj, path25) {
+  if (!path25)
     return obj;
-  return path24.reduce((acc, key) => acc?.[key], obj);
+  return path25.reduce((acc, key) => acc?.[key], obj);
 }
 function promiseAllObject(promisesObj) {
   const keys = Object.keys(promisesObj);
@@ -1853,11 +1864,11 @@ function explicitlyAborted(x, startIndex = 0) {
   }
   return false;
 }
-function prefixIssues(path24, issues) {
+function prefixIssues(path25, issues) {
   return issues.map((iss) => {
     var _a3;
     (_a3 = iss).path ?? (_a3.path = []);
-    iss.path.unshift(path24);
+    iss.path.unshift(path25);
     return iss;
   });
 }
@@ -2075,16 +2086,16 @@ function flattenError(error51, mapper = (issue2) => issue2.message) {
 }
 function formatError(error51, mapper = (issue2) => issue2.message) {
   const fieldErrors = { _errors: [] };
-  const processError = (error52, path24 = []) => {
+  const processError = (error52, path25 = []) => {
     for (const issue2 of error52.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path24, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path25, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path24, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path25, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path24, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path25, ...issue2.path]);
       } else {
-        const fullpath = [...path24, ...issue2.path];
+        const fullpath = [...path25, ...issue2.path];
         if (fullpath.length === 0) {
           fieldErrors._errors.push(mapper(issue2));
         } else {
@@ -2111,17 +2122,17 @@ function formatError(error51, mapper = (issue2) => issue2.message) {
 }
 function treeifyError(error51, mapper = (issue2) => issue2.message) {
   const result = { errors: [] };
-  const processError = (error52, path24 = []) => {
+  const processError = (error52, path25 = []) => {
     var _a3, _b;
     for (const issue2 of error52.issues) {
       if (issue2.code === "invalid_union" && issue2.errors.length) {
-        issue2.errors.map((issues) => processError({ issues }, [...path24, ...issue2.path]));
+        issue2.errors.map((issues) => processError({ issues }, [...path25, ...issue2.path]));
       } else if (issue2.code === "invalid_key") {
-        processError({ issues: issue2.issues }, [...path24, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path25, ...issue2.path]);
       } else if (issue2.code === "invalid_element") {
-        processError({ issues: issue2.issues }, [...path24, ...issue2.path]);
+        processError({ issues: issue2.issues }, [...path25, ...issue2.path]);
       } else {
-        const fullpath = [...path24, ...issue2.path];
+        const fullpath = [...path25, ...issue2.path];
         if (fullpath.length === 0) {
           result.errors.push(mapper(issue2));
           continue;
@@ -2153,8 +2164,8 @@ function treeifyError(error51, mapper = (issue2) => issue2.message) {
 }
 function toDotPath(_path) {
   const segs = [];
-  const path24 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
-  for (const seg of path24) {
+  const path25 = _path.map((seg) => typeof seg === "object" ? seg.key : seg);
+  for (const seg of path25) {
     if (typeof seg === "number")
       segs.push(`[${seg}]`);
     else if (typeof seg === "symbol")
@@ -15657,13 +15668,13 @@ function resolveRef(ref, ctx) {
   if (!ref.startsWith("#")) {
     throw new Error("External $ref is not supported, only local refs (#/...) are allowed");
   }
-  const path24 = ref.slice(1).split("/").filter(Boolean);
-  if (path24.length === 0) {
+  const path25 = ref.slice(1).split("/").filter(Boolean);
+  if (path25.length === 0) {
     return ctx.rootSchema;
   }
   const defsKey = ctx.version === "draft-2020-12" ? "$defs" : "definitions";
-  if (path24[0] === defsKey) {
-    const key = path24[1];
+  if (path25[0] === defsKey) {
+    const key = path25[1];
     if (!key || !ctx.defs[key]) {
       throw new Error(`Reference not found: ${ref}`);
     }
@@ -17693,11 +17704,11 @@ var init_tools = __esm({
           if (!ctx.addDocument)
             return "Knowledge vault tool not available.";
           const title = args["title"] || "New Document";
-          const path24 = args["path"] || `notes/${title.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
+          const path25 = args["path"] || `notes/${title.toLowerCase().replace(/[^a-z0-9]+/g, "-")}`;
           const content = args["content"] || "";
           const tags = args["tags"] || [];
           ctx.addDocument({
-            path: path24,
+            path: path25,
             title,
             content,
             format: "markdown",
@@ -17706,7 +17717,7 @@ var init_tools = __esm({
             workspaceId: ctx.workspaceId
           });
           ctx.addActivity("vault", "created document", title);
-          return `Document "${title}" created at "${path24}".`;
+          return `Document "${title}" created at "${path25}".`;
         }
       }
     ];
@@ -20212,11 +20223,11 @@ var init_synthesisAudit = __esm({
 import { existsSync as existsSync8, readFileSync as readFileSync6, writeFileSync as writeFileSync5 } from "node:fs";
 import { join as join2 } from "node:path";
 function loadNfrSpec(zelariRoot) {
-  const path24 = join2(zelariRoot, "nfr-spec.json");
-  if (!existsSync8(path24))
+  const path25 = join2(zelariRoot, "nfr-spec.json");
+  if (!existsSync8(path25))
     return null;
   try {
-    const raw = JSON.parse(readFileSync6(path24, "utf8"));
+    const raw = JSON.parse(readFileSync6(path25, "utf8"));
     if (raw.version !== 1 || !Array.isArray(raw.targets))
       return null;
     return raw;
@@ -22405,9 +22416,9 @@ var init_types2 = __esm({
 import { readFileSync as readFileSync11 } from "node:fs";
 import { join as join8 } from "node:path";
 function readLessonsDeduped(zelariRoot) {
-  const path24 = join8(zelariRoot, LESSONS_FILE);
+  const path25 = join8(zelariRoot, LESSONS_FILE);
   try {
-    const raw = readFileSync11(path24, "utf8");
+    const raw = readFileSync11(path25, "utf8");
     const byId = /* @__PURE__ */ new Map();
     for (const line of raw.split(/\r?\n/)) {
       if (!line.trim())
@@ -22508,8 +22519,8 @@ function keywordsFrom(check2, signature) {
   return [.../* @__PURE__ */ new Set([...fromId, ...words])].slice(0, 12);
 }
 function writeLesson(zelariRoot, lesson) {
-  const path24 = join9(zelariRoot, LESSONS_FILE);
-  appendFileSync2(path24, `${JSON.stringify(lesson)}
+  const path25 = join9(zelariRoot, LESSONS_FILE);
+  appendFileSync2(path25, `${JSON.stringify(lesson)}
 `, "utf8");
 }
 function findSimilar(lessons, signature) {
@@ -23649,28 +23660,28 @@ var init_storage = __esm({
     VALID_SCALARS = /^(true|false|null|~)$/i;
     Storage = class {
       /** Read a Markdown file with frontmatter. Throws if not found. */
-      read(path24) {
-        if (!existsSync13(path24)) {
-          throw new Error(`File not found: ${path24}`);
+      read(path25) {
+        if (!existsSync13(path25)) {
+          throw new Error(`File not found: ${path25}`);
         }
-        const md = readFileSync13(path24, "utf8");
+        const md = readFileSync13(path25, "utf8");
         return parseFrontmatter(md);
       }
       /** Read a Markdown file; returns null if not found. */
-      readIfExists(path24) {
-        if (!existsSync13(path24)) return null;
-        return this.read(path24);
+      readIfExists(path25) {
+        if (!existsSync13(path25)) return null;
+        return this.read(path25);
       }
       /**
        * Write a Markdown file atomically (tmp + rename). Creates parent dirs.
        * The meta object is serialized as YAML frontmatter; body as Markdown.
        */
-      write(path24, meta3, body) {
-        mkdirSync7(dirname(path24), { recursive: true });
-        const tmp = path24 + ".tmp-" + process.pid;
+      write(path25, meta3, body) {
+        mkdirSync7(dirname(path25), { recursive: true });
+        const tmp = path25 + ".tmp-" + process.pid;
         const md = serializeFrontmatter(meta3, body);
         writeFileSync11(tmp, md, "utf8");
-        renameSync2(tmp, path24);
+        renameSync2(tmp, path25);
       }
       /** List all .md files in a directory (non-recursive). */
       listMarkdown(dir) {
@@ -23748,8 +23759,8 @@ function readPlan(ctx) {
     } catch {
     }
   }
-  const path24 = workspaceFile(ctx.rootDir, "plan");
-  const doc = ctx.storage.readIfExists(path24);
+  const path25 = workspaceFile(ctx.rootDir, "plan");
+  const doc = ctx.storage.readIfExists(path25);
   if (!doc) return { phases: [], tasks: [], milestones: [] };
   const meta3 = doc.meta;
   return {
@@ -23914,7 +23925,7 @@ function addMilestoneRecord(ctx, summary, input) {
     dueDate: input.dueDate,
     targetVersion: version2
   });
-  const path24 = join14(ctx.rootDir, "milestones", `${id}.md`);
+  const path25 = join14(ctx.rootDir, "milestones", `${id}.md`);
   const meta3 = {
     kind: "milestone",
     id,
@@ -23931,7 +23942,7 @@ function addMilestoneRecord(ctx, summary, input) {
     `Target version: ${version2}`,
     ""
   ].join("\n");
-  ctx.storage.write(path24, meta3, body);
+  ctx.storage.write(path25, meta3, body);
   return { id, created: true };
 }
 function readPlanSummary(ctx) {
@@ -24135,7 +24146,7 @@ function addIdeaStub(ctx) {
         const tags = args["tags"] ?? [];
         const category = args["category"] ?? "General";
         const id = `${nextAdrId(ctx)}-${slugify3(title)}`;
-        const path24 = workspaceArtifact(ctx.rootDir, "decisions", id);
+        const path25 = workspaceArtifact(ctx.rootDir, "decisions", id);
         const meta3 = {
           kind: "adr",
           status: "proposed",
@@ -24161,7 +24172,7 @@ function addIdeaStub(ctx) {
           ...consequences.map((c) => `- ${c}`),
           ""
         ].join("\n");
-        ctx.storage.write(path24, meta3, body);
+        ctx.storage.write(path25, meta3, body);
         return `ADR ${id} created: "${title}". Status: proposed. Promote to accepted via /update ADR or manual edit.`;
       });
     }
@@ -24243,14 +24254,14 @@ function createDocumentStub(ctx) {
           ctx.storage.write(risksPath, riskMeta, content);
           return `Document "${title}" created at risks.md (workspace root).`;
         }
-        const path24 = workspaceArtifact(ctx.rootDir, "docs", slug);
+        const path25 = workspaceArtifact(ctx.rootDir, "docs", slug);
         const meta3 = {
           kind: "doc",
           id: slug,
           date: (/* @__PURE__ */ new Date()).toISOString().slice(0, 10),
           tags
         };
-        ctx.storage.write(path24, meta3, content);
+        ctx.storage.write(path25, meta3, content);
         return `Document "${title}" created at docs/${slug}.md.`;
       });
     }
@@ -25017,10 +25028,10 @@ import { createHash as createHash2 } from "node:crypto";
 import { join as join17 } from "node:path";
 import { readFile } from "node:fs/promises";
 async function readPackageJson2(projectRoot) {
-  const path24 = join17(projectRoot, "package.json");
-  if (!existsSync17(path24)) return null;
+  const path25 = join17(projectRoot, "package.json");
+  if (!existsSync17(path25)) return null;
   try {
-    return JSON.parse(await readFile(path24, "utf8"));
+    return JSON.parse(await readFile(path25, "utf8"));
   } catch {
     return null;
   }
@@ -25102,9 +25113,9 @@ async function genBuild(ctx) {
   ].join("\n");
 }
 async function genOpenQuestions(ctx) {
-  const path24 = join17(ctx.rootDir, "risks.md");
-  if (!existsSync17(path24)) return "_No open questions._";
-  const content = readFileSync17(path24, "utf8");
+  const path25 = join17(ctx.rootDir, "risks.md");
+  if (!existsSync17(path25)) return "_No open questions._";
+  const content = readFileSync17(path25, "utf8");
   const lines = content.split("\n");
   const questions = [];
   let currentTitle = "";
@@ -25667,8 +25678,8 @@ async function runPostCouncilHook(ctx, options) {
           sources: scope.sources
         } : void 0
       });
-      const path24 = writeCouncilCompletion(ctx.rootDir, completion);
-      completionHook = { ran: true, path: path24, completion };
+      const path25 = writeCouncilCompletion(ctx.rootDir, completion);
+      completionHook = { ran: true, path: path25, completion };
     } catch (err) {
       completionHook = {
         ran: true,
@@ -26156,6 +26167,252 @@ var init_zelariMission = __esm({
   }
 });
 
+// src/cli/utils/doctor.ts
+var doctor_exports = {};
+__export(doctor_exports, {
+  runDoctor: () => runDoctor
+});
+import { execSync } from "node:child_process";
+import { existsSync as existsSync26, readFileSync as readFileSync23, readlinkSync, statSync as statSync6 } from "node:fs";
+import { createRequire as createRequire2 } from "node:module";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+import path24 from "node:path";
+function findPackageRoot(start) {
+  let dir = start;
+  for (let i = 0; i < 6; i += 1) {
+    const candidate = path24.join(dir, "package.json");
+    if (existsSync26(candidate)) {
+      try {
+        const pkg = JSON.parse(readFileSync23(candidate, "utf8"));
+        if (pkg.name === "zelari-code") return dir;
+      } catch {
+      }
+    }
+    const parent = path24.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return path24.resolve(__dirname3, "..", "..", "..");
+}
+function tryExec(cmd) {
+  try {
+    return execSync(cmd, {
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"]
+    }).trim();
+  } catch {
+    return "";
+  }
+}
+function readPackageJson3() {
+  try {
+    const pkgPath = path24.join(packageRoot, "package.json");
+    return JSON.parse(readFileSync23(pkgPath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function getGlobalPrefix() {
+  return (process.env.npm_config_prefix || process.env.NPM_CONFIG_PREFIX || "").trim() || tryExec("npm prefix -g");
+}
+function checkShim(pkgName) {
+  const prefix = getGlobalPrefix();
+  if (!prefix) {
+    return WARN("npm global prefix not detectable (run inside an npm context)");
+  }
+  const isWin = process.platform === "win32";
+  const shimName = isWin ? "zelari-code.cmd" : "zelari-code";
+  const shimPath = path24.join(prefix, shimName);
+  if (!existsSync26(shimPath)) {
+    return FAIL(
+      `shim not found at ${shimPath}
+         fix:  npm install -g ${pkgName}@latest --force`
+    );
+  }
+  try {
+    const st = statSync6(shimPath);
+    if (isWin) {
+      const content = readFileSync23(shimPath, "utf8");
+      if (content.includes(`${pkgName}\\bin\\`) || content.includes(`${pkgName}/bin/`)) {
+        return OK(`shim OK at ${shimPath} (${st.size} bytes)`);
+      }
+      return FAIL(
+        `shim at ${shimPath} does not reference ${pkgName}/bin/
+         fix:  npm install -g ${pkgName}@latest --force`
+      );
+    }
+    let target;
+    try {
+      target = readlinkSync(shimPath);
+    } catch {
+      return FAIL(
+        `shim at ${shimPath} is not a symlink (POSIX global installs should be symlinks)
+         fix:  npm install -g ${pkgName}@latest --force`
+      );
+    }
+    const resolved = path24.resolve(path24.dirname(shimPath), target);
+    const expected = path24.join(
+      prefix,
+      "node_modules",
+      pkgName,
+      "bin",
+      "zelari-code.js"
+    );
+    if (resolved === expected) {
+      return OK(`shim OK at ${shimPath} \u2192 ${resolved}`);
+    }
+    return FAIL(
+      `shim at ${shimPath} points to ${resolved}
+         expected ${expected}
+         fix:  npm install -g ${pkgName}@latest --force`
+    );
+  } catch (err) {
+    return FAIL(
+      `could not inspect shim: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function checkNode(pkg) {
+  const raw = tryExec("node --version");
+  if (!raw) {
+    return FAIL("`node` not found on PATH");
+  }
+  const m = raw.match(/^v?(\d+)\.(\d+)\.(\d+)/);
+  if (!m) {
+    return WARN(`could not parse node version: ${raw}`);
+  }
+  const major = Number(m[1]);
+  if (major < 20) {
+    return FAIL(
+      `node ${raw} is older than the required engines.node (>= 20.0.0)`
+    );
+  }
+  return OK(`node ${raw}`);
+}
+function checkBundle() {
+  const bundle = path24.join(packageRoot, "dist", "cli", "main.bundled.js");
+  if (!existsSync26(bundle)) {
+    return FAIL(
+      `dist/cli/main.bundled.js missing at ${bundle}
+         fix:  npm run build:cli   (then reinstall or run via tsx)`
+    );
+  }
+  try {
+    const st = statSync6(bundle);
+    return OK(`bundle OK (${(st.size / 1024 / 1024).toFixed(2)} MB)`);
+  } catch (err) {
+    return FAIL(
+      `could not stat bundle: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+}
+function checkRuntimeDeps() {
+  const required2 = ["react", "react-dom", "ink", "ink-text-input", "zod"];
+  const missing = [];
+  for (const dep of required2) {
+    try {
+      const localReq = createRequire2(path24.join(packageRoot, "package.json"));
+      localReq.resolve(dep);
+    } catch {
+      missing.push(dep);
+    }
+  }
+  if (missing.length === 0) {
+    return OK(
+      "runtime deps resolvable (react, react-dom, ink, ink-text-input, zod)"
+    );
+  }
+  return FAIL(
+    `missing runtime deps: ${missing.join(", ")}
+         fix:  npm install -g ${"<pkg>"} --force    (then reopen the terminal)`
+  );
+}
+function checkPath() {
+  const prefix = getGlobalPrefix();
+  if (!prefix) return WARN("npm global prefix not detectable");
+  const pathSep = process.platform === "win32" ? ";" : ":";
+  const pathDirs = (process.env.PATH || "").split(pathSep);
+  if (pathDirs.includes(prefix)) {
+    return OK(`PATH includes npm prefix (${prefix})`);
+  }
+  return WARN(
+    `PATH does not include npm prefix (${prefix})
+         symptom: "zelari-code: command not found" after install
+         fix (POSIX):   export PATH="$(npm prefix -g)/bin:$PATH"
+         fix (Windows): $env:Path = "$(npm prefix -g);$env:Path"`
+  );
+}
+function runDoctor() {
+  const pkg = readPackageJson3();
+  const pkgName = pkg?.name ?? "zelari-code";
+  const checks = [
+    { name: "node", run: () => checkNode(pkg) },
+    { name: "bin shim", run: () => checkShim(pkgName) },
+    { name: "cli bundle", run: () => checkBundle() },
+    { name: "runtime deps", run: () => checkRuntimeDeps() },
+    { name: "PATH", run: () => checkPath() }
+  ];
+  console.log(`zelari-code doctor (v${pkg?.version ?? "unknown"})`);
+  console.log("platform:", process.platform, process.arch);
+  console.log("node:    ", process.version);
+  console.log("prefix:  ", getGlobalPrefix() || "(unknown)");
+  console.log("root:    ", packageRoot);
+  console.log("");
+  let criticalFails = 0;
+  let warns = 0;
+  for (const c of checks) {
+    let result;
+    try {
+      result = c.run();
+    } catch (err) {
+      result = FAIL(
+        `unexpected error: ${err instanceof Error ? err.message : String(err)}`
+      );
+    }
+    const tag = result.ok ? "OK  " : result.severity === "critical" ? "FAIL" : "WARN";
+    const color = result.ok ? "\x1B[32m" : result.severity === "critical" ? "\x1B[31m" : "\x1B[33m";
+    const reset = "\x1B[0m";
+    console.log(
+      `  ${color}${tag}${reset}  ${c.name.padEnd(14)}${result.message.replace(/\n/g, "\n              ")}`
+    );
+    if (!result.ok) {
+      if (result.severity === "critical") criticalFails += 1;
+      else warns += 1;
+    }
+  }
+  console.log("");
+  if (criticalFails === 0 && warns === 0) {
+    console.log("\x1B[32m\u2714 all checks passed\x1B[0m");
+    return true;
+  }
+  console.log(`\u2717 ${criticalFails} critical failure(s), ${warns} warning(s)`);
+  return criticalFails === 0;
+}
+var require3, __dirname3, packageRoot, OK, FAIL, WARN;
+var init_doctor = __esm({
+  "src/cli/utils/doctor.ts"() {
+    "use strict";
+    require3 = createRequire2(import.meta.url);
+    __dirname3 = path24.dirname(fileURLToPath2(import.meta.url));
+    packageRoot = findPackageRoot(__dirname3);
+    OK = (message) => ({
+      ok: true,
+      message,
+      severity: "critical"
+    });
+    FAIL = (message, severity = "critical") => ({
+      ok: false,
+      message,
+      severity
+    });
+    WARN = (message) => ({
+      ok: false,
+      message,
+      severity: "warn"
+    });
+  }
+});
+
 // src/cli/main.ts
 import React13 from "react";
 import { render } from "ink";
@@ -31629,14 +31886,23 @@ async function handleUpdateCheck(ctx) {
        Run \`/update --yes\` to install. You'll need to restart manually after.`
       );
     } else {
-      appendSystem(ctx.setMessages, `[update] up to date (${info.currentVersion})`);
+      appendSystem(
+        ctx.setMessages,
+        `[update] up to date (${info.currentVersion})`
+      );
     }
   } catch (err) {
-    appendSystem(ctx.setMessages, `[update error] ${err instanceof Error ? err.message : String(err)}`);
+    appendSystem(
+      ctx.setMessages,
+      `[update error] ${err instanceof Error ? err.message : String(err)}`
+    );
   }
 }
 async function handleUpdatePerform(ctx) {
-  appendSystem(ctx.setMessages, "[update] running `npm install -g zelari-code@latest`...");
+  appendSystem(
+    ctx.setMessages,
+    "[update] running `npm install -g zelari-code@latest`..."
+  );
   try {
     const { performUpdate: performUpdate2 } = await Promise.resolve().then(() => (init_updater(), updater_exports));
     const res = await performUpdate2();
@@ -31649,18 +31915,48 @@ Please restart zelari-code manually to use the new version.
 (exit with /exit or Ctrl+C, then run \`zelari-code\` again)`
       );
     } else {
+      const output = res.output?.trim() || "(empty)";
+      const hint = buildUpdateFailureHint(
+        res.error ?? "",
+        output,
+        res.exitCode
+      );
       appendSystem(
         ctx.setMessages,
         `[update] \u274C failed: ${res.error ?? "unknown error"}
+exit code: ${res.exitCode ?? "n/a"}
 
 npm output:
-${res.output || "(empty)"}`
+${output}
+
+` + hint
       );
     }
   } catch (err) {
-    appendSystem(ctx.setMessages, `[update error] ${err instanceof Error ? err.message : String(err)}`);
+    appendSystem(
+      ctx.setMessages,
+      `[update error] ${err instanceof Error ? err.message : String(err)}`
+    );
   }
 }
+function buildUpdateFailureHint(error51, output, exitCode) {
+  const haystack = `${error51}
+${output}`.toLowerCase();
+  const isWin = process.platform === "win32";
+  if (haystack.includes("eresolve") || haystack.includes("epeerinvalid") || haystack.includes("peer dep")) {
+    return "\u{1F4A1} hint: peer-dependency conflict. Try:\n         npm install -g zelari-code@latest --legacy-peer-deps\n   or:  npm install -g zelari-code@latest --force";
+  }
+  if (haystack.includes("eacces") || haystack.includes("eperm")) {
+    return "\u{1F4A1} hint: permission denied. On macOS/Linux, avoid sudo with npm:\n         https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally\n   On Windows, re-run the terminal as Administrator.";
+  }
+  if (haystack.includes("enoent") && haystack.includes("npm")) {
+    return '\u{1F4A1} hint: `npm` was not found on PATH for the spawned shell.\n   Re-open the terminal so it picks up your current PATH, or set:\n         export PATH="$(npm prefix -g)/bin:$PATH"   (POSIX)\n         $env:Path = "$(npm prefix -g);$env:Path"   (PowerShell)';
+  }
+  if (haystack.includes("zelari-code") && (haystack.includes("not found") || haystack.includes("eexist") || haystack.includes("ebusy") || haystack.includes("shim") || exitCode === 0)) {
+    return "\u{1F4A1} hint: the install may have completed but the global bin shim\n   is missing or stale (common on Windows + npm 10/11 after major\n   upgrades). To repair:\n         npm install -g zelari-code@latest --force\n   Then re-open the terminal. If `zelari-code` is still not found,\n   run the doctor: `zelari-code doctor`";
+  }
+  return "\u{1F4A1} hint: the install did not succeed. To retry with more detail:\n         npm install -g zelari-code@latest --verbose 2>&1 | tail -40\n   On Windows, also try: `npm install -g zelari-code@latest --force`\n" + (isWin ? "   Run `zelari-code doctor` from a new terminal to diagnose shim / PATH issues.\n" : "");
+}
 
 // src/cli/slashHandlers/promoteMember.ts
 import { promises as fs15 } from "node:fs";
@@ -33891,9 +34187,14 @@ function pickRootComponent() {
     console.log(`zelari-code v${VERSION}`);
     process.exit(0);
   }
+  if (argv.includes("--doctor") || argv.includes("doctor")) {
+    const { runDoctor: runDoctor2 } = (init_doctor(), __toCommonJS(doctor_exports));
+    const healthy = runDoctor2();
+    process.exit(healthy ? 0 : 1);
+  }
   if (argv.includes("--help") || argv.includes("-h")) {
     console.log(
-      "zelari-code \u2014 AI Council coding agent CLI.\n\nUsage: zelari-code [options]\n\nOptions:\n  --version, -v       Print version and exit\n  --help, -h          Print this help and exit\n  --no-wizard         Skip the first-run wizard\n  --reset-config      Re-run the wizard (clears provider.json on commit)\n  --headless          Run a single task without mounting the TUI\n    --task <text>       Task prompt (required in headless mode)\n    --output json|plain Output format (default: json)\n    --council          Use the 6-member council pipeline\n    --provider <id>    Provider override (default: active)\n    --model <id>       Model override (default: provider default)\n\nEnvironment:\n  ZELARI_NO_WIZARD=1  Skip the first-run wizard\n  ANATHEMA_DEV=1      Disable background update check\n"
+      "zelari-code \u2014 AI Council coding agent CLI.\n\nUsage: zelari-code [options]\n\nOptions:\n  --version, -v       Print version and exit\n  --help, -h          Print this help and exit\n  --doctor            Diagnose install health (shim, bundle, PATH, deps)\n  --no-wizard         Skip the first-run wizard\n  --reset-config      Re-run the wizard (clears provider.json on commit)\n  --headless          Run a single task without mounting the TUI\n    --task <text>       Task prompt (required in headless mode)\n    --output json|plain Output format (default: json)\n    --council          Use the 6-member council pipeline\n    --provider <id>    Provider override (default: active)\n    --model <id>       Model override (default: provider default)\n\nEnvironment:\n  ZELARI_NO_WIZARD=1  Skip the first-run wizard\n  ANATHEMA_DEV=1      Disable background update check\n"
     );
     process.exit(0);
   }