heyspex 0.1.0

package/dist/cli/hs-install.mjs

@@ -0,0 +1,1390 @@
+import { createRequire as __hsCreateRequire } from 'node:module';
+const require = __hsCreateRequire(import.meta.url);
+
+// spex-console/bin/hs-install.ts
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync as readFileSync4, writeFileSync as writeFileSync2 } from "node:fs";
+import { join as join4, resolve } from "node:path";
+import process2 from "node:process";
+
+// spex-console/src/lib/vault-registry/registry-file.ts
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+// spex-console/src/lib/vault-registry/types.ts
+var VAULT_REGISTRY_SCHEMA_VERSION = 1;
+function emptyVaultRegistry() {
+  return {
+    schema_version: VAULT_REGISTRY_SCHEMA_VERSION,
+    workspaces: [],
+    vaults: [],
+    active_workspace_id: null,
+    active_vault_id: null
+  };
+}
+
+// spex-console/src/lib/vault-registry/registry-file.ts
+function vaultRegistryDir(opts = {}) {
+  return opts.registryDir ?? join(homedir(), ".heyspex");
+}
+function vaultRegistryFilePath(opts = {}) {
+  return join(vaultRegistryDir(opts), "registry.json");
+}
+function isNonEmptyString(v) {
+  return typeof v === "string" && v.trim().length > 0;
+}
+function normalizeWorkspace(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const o = raw;
+  if (!isNonEmptyString(o.id)) return null;
+  if (!isNonEmptyString(o.display_name)) return null;
+  if (!isNonEmptyString(o.created_at)) return null;
+  const record = {
+    id: o.id,
+    display_name: o.display_name,
+    created_at: o.created_at,
+    archived: o.archived === true
+  };
+  if (isNonEmptyString(o.github_org)) record.github_org = o.github_org;
+  return record;
+}
+function normalizeVault(raw) {
+  if (!raw || typeof raw !== "object") return null;
+  const o = raw;
+  if (!isNonEmptyString(o.id)) return null;
+  if (!isNonEmptyString(o.workspace_id)) return null;
+  if (!isNonEmptyString(o.display_name)) return null;
+  if (!isNonEmptyString(o.repo_root_abs)) return null;
+  if (typeof o.schema_version !== "number") return null;
+  if (!isNonEmptyString(o.registered_at)) return null;
+  const record = {
+    id: o.id,
+    workspace_id: o.workspace_id,
+    display_name: o.display_name,
+    repo_root_abs: o.repo_root_abs,
+    schema_version: o.schema_version,
+    registered_at: o.registered_at,
+    archived: o.archived === true
+  };
+  if (isNonEmptyString(o.github_remote)) record.github_remote = o.github_remote;
+  return record;
+}
+function parseVaultRegistryFile(json) {
+  const fallback = emptyVaultRegistry();
+  if (!json || typeof json !== "object") return fallback;
+  const o = json;
+  const workspacesRaw = Array.isArray(o.workspaces) ? o.workspaces : [];
+  const workspaces = workspacesRaw.map(normalizeWorkspace).filter((w) => w !== null);
+  const vaultsRaw = Array.isArray(o.vaults) ? o.vaults : [];
+  const vaults = vaultsRaw.map(normalizeVault).filter((v) => v !== null);
+  const active_workspace_id = isNonEmptyString(o.active_workspace_id) ? o.active_workspace_id : null;
+  const active_vault_id = isNonEmptyString(o.active_vault_id) ? o.active_vault_id : null;
+  return {
+    schema_version: VAULT_REGISTRY_SCHEMA_VERSION,
+    workspaces,
+    vaults,
+    active_workspace_id,
+    active_vault_id
+  };
+}
+function loadVaultRegistry(opts = {}) {
+  const filePath = vaultRegistryFilePath(opts);
+  if (!existsSync(filePath)) return emptyVaultRegistry();
+  try {
+    const raw = readFileSync(filePath, "utf8");
+    return parseVaultRegistryFile(JSON.parse(raw));
+  } catch {
+    return emptyVaultRegistry();
+  }
+}
+function writeVaultRegistry(registry, opts = {}) {
+  const filePath = vaultRegistryFilePath(opts);
+  mkdirSync(dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.tmp`;
+  writeFileSync(tmpPath, `${JSON.stringify(registry, null, 2)}
+`, "utf8");
+  renameSync(tmpPath, filePath);
+}
+function isValidId(id) {
+  if (!isNonEmptyString(id)) return false;
+  if (id.includes("/") || id.includes("\\")) return false;
+  if (id === "." || id === "..") return false;
+  return true;
+}
+function registerWorkspace(record, opts = {}) {
+  if (!isValidId(record.id)) {
+    throw new Error(`registerWorkspace: invalid workspace id "${record.id}"`);
+  }
+  const registry = loadVaultRegistry(opts);
+  const idx = registry.workspaces.findIndex((w) => w.id === record.id);
+  if (idx >= 0) {
+    registry.workspaces[idx] = { ...record };
+  } else {
+    registry.workspaces.push({ ...record });
+  }
+  writeVaultRegistry(registry, opts);
+  return registry;
+}
+function registerVault(record, opts = {}) {
+  if (!isValidId(record.id)) {
+    throw new Error(`registerVault: invalid vault id "${record.id}"`);
+  }
+  if (!isValidId(record.workspace_id)) {
+    throw new Error(`registerVault: invalid workspace_id "${record.workspace_id}"`);
+  }
+  if (!isNonEmptyString(record.repo_root_abs)) {
+    throw new Error("registerVault: repo_root_abs is required");
+  }
+  const registry = loadVaultRegistry(opts);
+  const isSameVault = (v) => v.id === record.id || v.repo_root_abs === record.repo_root_abs;
+  const idx = registry.vaults.findIndex(isSameVault);
+  if (idx >= 0) {
+    registry.vaults[idx] = { ...record };
+    registry.vaults = registry.vaults.filter((v, i) => i === idx || !isSameVault(v));
+  } else {
+    registry.vaults.push({ ...record });
+  }
+  writeVaultRegistry(registry, opts);
+  return registry;
+}
+function setActiveWorkspaceId(workspaceId, opts = {}) {
+  const registry = loadVaultRegistry(opts);
+  registry.active_workspace_id = workspaceId;
+  writeVaultRegistry(registry, opts);
+  return registry;
+}
+
+// spex-console/src/lib/cli/control-shared.ts
+import { readFileSync as readFileSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join2 } from "node:path";
+var EXIT = {
+  /** Success. */
+  OK: 0,
+  /** Usage error — unknown subcommand/flag, or a missing required argument. */
+  USAGE: 1,
+  /** Claim race lost — the spec is already claimed by another agent (409). */
+  CONFLICT: 9,
+  /** Target not found — release of an unheld claim, etc. (404). */
+  NOT_FOUND: 10,
+  /** Invalid argument — bad `--ttl`, unknown `--kind`, unparseable date. */
+  INVALID_ARG: 11,
+  /** SpexConsole unreachable (network error reaching the dev server). */
+  CONSOLE_UNREACHABLE: 12,
+  /** Server failure — a non-OK response that isn't 400/402/404/409. */
+  WRITE_FAILED: 13,
+  /** Neon control plane absent — the endpoint returned 402 (upgrade required). */
+  NEON_REQUIRED: 14,
+  /**
+   * A cross-account `--account <id>` override was refused — the caller is
+   * not a builder/admin (`resolveScopedAccountId`'s `forbidden_account_override`,
+   * [[HS-X3GB-EKLJ-TASK-hs-cli-account-flag-for-cross-account]]). Distinct
+   * from `USAGE`/`INVALID_ARG` — this is an authorization refusal, not a
+   * malformed command.
+   */
+  FORBIDDEN: 15
+};
+
+// spex-console/src/lib/cli/customer-agent-contract.ts
+var CUSTOMER_AGENT_CONTRACT = `# Agent Instructions
+
+This project is managed with **HeySpex** \u2014 a spec vault under \`specs/\` is the system of record (the markdown files *are* the tracker; there is no separate database). The **HeySpex MCP server** is the source of truth for how to work here: procedures, project memory, and design patterns all load **on demand** through its tools, so this file stays small.
+
+## At session start
+
+Recall project memory before doing anything: \`heyspex_recall_memories({ limit: 10 })\`. It surfaces lessons, decisions, and conventions specific to this project.
+
+Project memory lives in the vault and loads on demand \u2014 **do not mirror it into your local auto-memory index** (e.g. Claude Code's \`MEMORY.md\`). Keep that index to your own working notes; durable project knowledge goes to the vault via \`heyspex_file_spec\`. This keeps HeySpex's footprint in your memory window to a single recall call.
+
+## Before any significant action \u2014 ask the procedures
+
+Before filing work, a destructive change, or closing a session, consult the procedures via MCP (do not guess from examples):
+
+- \`heyspex_preflight({ intent })\` \u2014 call first; returns the procedures to consult. Common intents: \`file_epic\`, \`file_task\`, \`destructive_action\`, \`close_session\`, \`claim_spec\`.
+- \`heyspex_get_procedure({ name })\` \u2014 fetch one full procedure when preflight names it.
+- \`heyspex_list_procedures({ query? })\` \u2014 browse what's available.
+
+## Working a task (the handshake)
+
+1. Get the next task: the on-deck prompt comes from HeySpex.
+2. Before starting, confirm with the user, then call \`heyspex_claim_spec({ spec_id })\` \u2014 this marks it in progress.
+3. As you complete each acceptance criterion, call \`heyspex_report_progress({ acProgress, currentStage })\` so progress shows live.
+4. When all criteria are met, call \`heyspex_submit_for_review({ spec_id })\`. **Never hand-edit \`status:\` in a spec's frontmatter** \u2014 the status API owns it.
+5. The agent does **not** commit or push \u2014 a human reviews and commits. A dirty working tree is the expected hand-off.
+
+## Capture knowledge as you go
+
+After research or a notable decision, save it to the vault (\`heyspex_save_research\` for findings; file a memory spec for lessons/decisions) so the next session inherits it. Cross-link specs with \`[[wikilinks]]\`.
+
+## Where things live
+
+\`specs/\` holds the work \u2014 \`specs/epics/\`, \`specs/tasks/\`, \`specs/research/\`, \`specs/memory/\`. Never set a spec \`id\` by hand; file via \`heyspex_file_spec\`.
+
+## Everything else
+
+If you need to know *how* something works in this project, **ask the HeySpex MCP server** (\`heyspex_get_procedure\` / \`heyspex_list_procedures\`) rather than expecting it here. This file is intentionally a thin contract; the detail lives one fetch away.
+`;
+function renderCustomerAgentContract() {
+  return CUSTOMER_AGENT_CONTRACT;
+}
+
+// spex-console/src/lib/cli/init.ts
+import { randomUUID } from "node:crypto";
+
+// scripts/lib/console-url-resolver.mjs
+import { readFileSync as readFileSync3 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { join as join3 } from "node:path";
+var DEFAULT_CONSOLE_URL = "https://app.heyspex.com";
+function trimTrailingSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+function readCredentialsConsoleUrl({ homeDir = homedir3() } = {}) {
+  try {
+    const raw = readFileSync3(join3(homeDir, ".heyspex", "credentials.yaml"), "utf8");
+    const match = raw.match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
+    const value = match?.[1]?.trim();
+    return value && value.length > 0 ? trimTrailingSlash(value) : null;
+  } catch {
+    return null;
+  }
+}
+function readDiscoveryFileConsoleUrl(repoRoot) {
+  if (!repoRoot) return null;
+  for (const name of [
+    "console-url",
+    "cockpit-url"
+    /* legacy-cockpit */
+  ]) {
+    try {
+      const discovery = readFileSync3(join3(repoRoot, ".heyspex", name), "utf8").trim();
+      if (discovery.length > 0) return trimTrailingSlash(discovery);
+    } catch {
+    }
+  }
+  return null;
+}
+var ConsoleUrlUnresolvedError = class extends Error {
+  constructor() {
+    super(
+      `resolveConsoleUrl: no HEYSPEX_CONSOLE_URL/HEYSPEX_COCKPIT_URL env, no console_url: in ~/.heyspex/credentials.yaml, and no .heyspex/console-url discovery file \u2014 refusing to silently fall back to the ${DEFAULT_CONSOLE_URL} default in strict mode.`
+    );
+    this.name = "ConsoleUrlUnresolvedError";
+  }
+};
+function resolveConsoleUrl({
+  repoRoot,
+  env = process.env,
+  homeDir = homedir3(),
+  strict = false
+} = {}) {
+  const envUrl = (env.HEYSPEX_CONSOLE_URL ?? env.HEYSPEX_COCKPIT_URL)?.trim();
+  if (envUrl) return trimTrailingSlash(envUrl);
+  const credentialsUrl = readCredentialsConsoleUrl({ homeDir });
+  if (credentialsUrl) return credentialsUrl;
+  const discoveryUrl = readDiscoveryFileConsoleUrl(repoRoot);
+  if (discoveryUrl) return discoveryUrl;
+  if (strict) throw new ConsoleUrlUnresolvedError();
+  return DEFAULT_CONSOLE_URL;
+}
+
+// spex-console/src/lib/cli/init.ts
+var HEYSPEX_YAML_SCHEMA_VERSION = 2;
+var DEFAULT_CONSOLE_URL2 = resolveConsoleUrl();
+function mintVaultId() {
+  return randomUUID();
+}
+function parseVaultId(content) {
+  const m = content.match(/^vault_id:\s*(.+?)\s*$/m);
+  if (!m) return null;
+  const raw = m[1].trim();
+  const unquoted = raw.replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1");
+  return unquoted.length > 0 ? unquoted : null;
+}
+function appendVaultIdLine(content, vaultId) {
+  const trimmed = content.replace(/\n+$/, "");
+  return `${trimmed}
+vault_id: ${vaultId}
+`;
+}
+function renderHeyspexYaml(args) {
+  return [
+    `schema_version: ${HEYSPEX_YAML_SCHEMA_VERSION}`,
+    `console_url: ${args.consoleUrl}`,
+    `vault_root: ${args.vaultRoot}`,
+    `vault_id: ${args.vaultId}`,
+    ""
+  ].join("\n");
+}
+function readExistingContent(deps, markerPath) {
+  if (!deps.readFile) return null;
+  try {
+    return deps.readFile(markerPath);
+  } catch {
+    return null;
+  }
+}
+function runInit(args, deps) {
+  const markerPath = deps.joinPath(deps.repoRoot, "heyspex.yaml");
+  const exists = deps.fileExists(markerPath);
+  const existingContent = exists ? readExistingContent(deps, markerPath) : null;
+  const existingVaultId = existingContent ? parseVaultId(existingContent) : null;
+  if (exists && !args.force) {
+    if (existingVaultId) {
+      return {
+        code: EXIT.OK,
+        message: `heyspex.yaml already exists at ${markerPath} \u2014 vault already initialized (use --force to overwrite).`,
+        payload: {
+          ok: true,
+          created: false,
+          path: markerPath,
+          reason: "already_initialized",
+          vault_id: existingVaultId
+        },
+        isError: false
+      };
+    }
+    if (existingContent === null) {
+      return {
+        code: EXIT.OK,
+        message: `heyspex.yaml already exists at ${markerPath} \u2014 vault already initialized (use --force to overwrite).`,
+        payload: { ok: true, created: false, path: markerPath, reason: "already_initialized" },
+        isError: false
+      };
+    }
+    const mintedId = args.adoptedVaultId ?? mintVaultId();
+    const updatedContent = appendVaultIdLine(existingContent, mintedId);
+    try {
+      deps.writeFile(markerPath, updatedContent);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        code: EXIT.WRITE_FAILED,
+        message: `failed to write heyspex.yaml: ${message}`,
+        payload: { ok: false, error: "write_failed", path: markerPath, message },
+        isError: true
+      };
+    }
+    return {
+      code: EXIT.OK,
+      message: `Added vault_id to existing heyspex.yaml at ${markerPath} (schema_version unchanged).`,
+      payload: {
+        ok: true,
+        created: false,
+        backfilled: true,
+        path: markerPath,
+        vault_id: mintedId
+      },
+      isError: false
+    };
+  }
+  const vaultId = existingVaultId ?? args.adoptedVaultId ?? mintVaultId();
+  const content = renderHeyspexYaml({ ...args, vaultId });
+  try {
+    deps.writeFile(markerPath, content);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    return {
+      code: EXIT.WRITE_FAILED,
+      message: `failed to write heyspex.yaml: ${message}`,
+      payload: { ok: false, error: "write_failed", path: markerPath, message },
+      isError: true
+    };
+  }
+  return {
+    code: EXIT.OK,
+    message: `${exists ? "Overwrote" : "Wrote"} ${markerPath} (schema_version ${HEYSPEX_YAML_SCHEMA_VERSION}).`,
+    payload: {
+      ok: true,
+      created: true,
+      overwrote: exists,
+      path: markerPath,
+      schema_version: HEYSPEX_YAML_SCHEMA_VERSION,
+      console_url: args.consoleUrl,
+      vault_root: args.vaultRoot,
+      vault_id: vaultId
+    },
+    isError: false
+  };
+}
+var HELP = [
+  "Usage:",
+  "  hs init [--console-url <url>] [--vault-root <path>] [--force] [--json]",
+  "  hs init --customer-vault <dir> [--console-url <url>] [--principles <all|none|a,b>]",
+  "                          [--vault-name <name>] [--no-git] [--json]",
+  "",
+  "Write the top-level heyspex.yaml vault marker (schema_version, console_url,",
+  "vault_root, vault_id) \u2014 the committed file the console / web companion read",
+  "to bootstrap a vault. Idempotent: an existing marker is left untouched unless",
+  "--force, EXCEPT a missing vault_id is backfilled in place either way (backward",
+  "compatible \u2014 no schema_version bump). vault_id is reused exactly when already",
+  "present; a fresh one is minted only when absent.",
+  "Does not modify .heyspex/config.yaml or its templates (ADR-0009).",
+  "",
+  "--customer-vault <dir> scaffolds a REAL customer vault at <dir> instead: the",
+  "specs/ folder tree, heyspex.yaml, and every row of the template shipping",
+  "manifest (spex-console/src/lib/cli/template-manifest.ts) \u2014 universal docs",
+  "copied verbatim, template-shape docs written as author-prompt skeletons \u2014",
+  "plus a generated CLAUDE.md, the kept-principles index, and (unless --no-git)",
+  "one initial `git init` + commit pinning the template version. Refuses a",
+  "non-empty <dir> with a plain error. See init.customer-vault.ts.",
+  "",
+  "Flags:",
+  "  --console-url <url>  console_url value (default: $HEYSPEX_CONSOLE_URL or",
+  "                       https://console.heyspex.local).",
+  "  --vault-root <path>  vault_root value (default: specs/).",
+  "  --customer-vault <dir> Scaffold a new customer vault at <dir> (see above).",
+  "  --principles <all|none|a,b> Which universal principle docs to ship",
+  "                       (--customer-vault only). Omitted + a TTY: interactive",
+  "                       keep/skip prompt per principle. Omitted + no TTY: all.",
+  "  --vault-name <name>  Display name for the scaffolded vault (--customer-vault",
+  "                       only; default: <dir>'s basename).",
+  "  --no-git             Skip git init + the initial commit (--customer-vault only).",
+  "  --force              Overwrite an existing heyspex.yaml.",
+  "  --json               Emit a machine-readable JSON result.",
+  "  --help, -h           Show this help.",
+  "",
+  "Exit codes: 0 ok \xB7 1 usage \xB7 11 bad-arg \xB7 13 write-failed"
+].join("\n");
+
+// spex-console/src/lib/cli/install-conflicts.ts
+var INSTALL_CONFLICT_REGISTRY = [
+  {
+    id: "beads-directory",
+    label: "Beads (`.beads/`)",
+    severity: "blocker",
+    why: "Beads and HeySpex both claim to be the agent queue; dual SSOT causes hook + status drift.",
+    remediation: "Remove `.beads/` and retire bd hooks (`hs install` documents manual steps; future: `hs install --remediate beads`)."
+  },
+  {
+    id: "beads-agents-md",
+    label: "Beads block in AGENTS.md",
+    severity: "warning",
+    why: "Agents still receive `bd prime` / `bd ready` instructions alongside HeySpex.",
+    remediation: "Replace the `<!-- BEGIN BEADS INTEGRATION -->` block with HeySpex agent rules."
+  },
+  {
+    id: "beads-claude-md",
+    label: "Beads block in CLAUDE.md",
+    severity: "warning",
+    why: "Claude Code session hooks and close-out still reference beads.",
+    remediation: "Replace beads integration with the HeySpex vault section."
+  },
+  {
+    id: "beads-claude-hooks",
+    label: "Claude Code `bd prime` hooks",
+    severity: "blocker",
+    why: "SessionStart runs `bd prime` every turn \u2014 fights HeySpex MCP recall/on-deck.",
+    remediation: "Clear `.claude/settings.json` hooks or remove `bd prime` entries."
+  },
+  {
+    id: "workflow-pm",
+    label: "workflow-pm / wfpm (beads PM dashboard)",
+    severity: "warning",
+    why: "PM scripts assume `bd` as queue truth.",
+    remediation: "Remove `workflow-pm` devDependency and `pm:*` npm scripts."
+  },
+  {
+    id: "parallel-issue-tracker",
+    label: "Alternate markdown issue tracker under `issues/` or `.github/ISSUE_TEMPLATE` only",
+    severity: "warning",
+    why: "Agents may file work outside `specs/` if instructions mention GitHub Issues as primary.",
+    remediation: "Point agent docs at `specs/` only; keep GitHub Issues optional for humans."
+  }
+];
+function includesAny(haystack, needles) {
+  return needles.some((n) => haystack.includes(n));
+}
+function scanInstallConflicts(targetDir, deps) {
+  const hits = [];
+  const rule = (id) => INSTALL_CONFLICT_REGISTRY.find((r) => r.id === id);
+  const beadsDir = deps.joinPath(targetDir, ".beads");
+  if (deps.fileExists(beadsDir)) {
+    const r = rule("beads-directory");
+    hits.push({ ...r, signal: beadsDir });
+  }
+  const agentsMd = deps.joinPath(targetDir, "AGENTS.md");
+  const agentsText = deps.readFile(agentsMd);
+  if (agentsText && includesAny(agentsText, [
+    "BEGIN BEADS INTEGRATION",
+    "Use `bd` for ALL task tracking",
+    "Run `bd prime`"
+  ])) {
+    const r = rule("beads-agents-md");
+    hits.push({ ...r, signal: agentsMd });
+  }
+  const claudeMd = deps.joinPath(targetDir, "CLAUDE.md");
+  const claudeText = deps.readFile(claudeMd);
+  if (claudeText && includesAny(claudeText, ["BEGIN BEADS INTEGRATION", "bd prime", "bd dolt push"])) {
+    const r = rule("beads-claude-md");
+    hits.push({ ...r, signal: claudeMd });
+  }
+  const claudeSettings = deps.joinPath(targetDir, ".claude", "settings.json");
+  const settingsText = deps.readFile(claudeSettings);
+  if (settingsText && settingsText.includes("bd prime")) {
+    const r = rule("beads-claude-hooks");
+    hits.push({ ...r, signal: claudeSettings });
+  }
+  const pkgJson = deps.joinPath(targetDir, "package.json");
+  const pkgText = deps.readFile(pkgJson);
+  if (pkgText && includesAny(pkgText, ["workflow-pm", '"wfpm"'])) {
+    const r = rule("workflow-pm");
+    hits.push({ ...r, signal: pkgJson });
+  }
+  return hits;
+}
+function formatConflictReport(hits) {
+  if (hits.length === 0) {
+    return "Conflict scan: no known tooling conflicts detected.";
+  }
+  const lines = [
+    `Conflict scan: ${hits.length} known conflict(s) detected \u2014 resolve before relying on HeySpex as the only queue.`,
+    ""
+  ];
+  for (const hit of hits) {
+    lines.push(
+      `[${hit.severity.toUpperCase()}] ${hit.label} (${hit.id})`,
+      `  Signal: ${hit.signal}`,
+      `  Why: ${hit.why}`,
+      `  Fix: ${hit.remediation}`,
+      ""
+    );
+  }
+  lines.push(
+    "Registry SSOT: specs/protocols/customer-vault-local-install-protocol.md",
+    "Future: `hs install --remediate <id>` for safe auto-fix paths."
+  );
+  return lines.join("\n");
+}
+
+// spex-console/src/lib/cli/install.ts
+var MCP_REL = ["vendor", "heyspex-mcp", "cli.mjs"];
+function parseInstallArgs(argv) {
+  let targetDir;
+  let platformRoot;
+  let cursor = true;
+  let claude = true;
+  let claudeApply = false;
+  let plugin = false;
+  let pluginApply = false;
+  let pluginScope = "project";
+  let statusline = true;
+  let commandCode = false;
+  let force = false;
+  let json = false;
+  let dryRun = false;
+  let skipConflictCheck = false;
+  let registerVaultFlag = false;
+  let workspace;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === "--help" || arg === "-h") return { help: true };
+    else if (arg === "--json") json = true;
+    else if (arg === "--force") force = true;
+    else if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--skip-conflict-check") skipConflictCheck = true;
+    else if (arg === "--register-vault") registerVaultFlag = true;
+    else if (arg === "--workspace" || arg.startsWith("--workspace=")) {
+      const v = arg === "--workspace" ? argv[++i] : arg.slice("--workspace=".length);
+      if (v === void 0 || v.trim() === "") {
+        return { error: { code: EXIT.INVALID_ARG, message: "--workspace requires an id" } };
+      }
+      workspace = v.trim();
+    } else if (arg === "--claude-apply") claudeApply = true;
+    else if (arg === "--plugin") plugin = true;
+    else if (arg === "--plugin-apply") {
+      plugin = true;
+      pluginApply = true;
+    } else if (arg === "--plugin-scope" || arg.startsWith("--plugin-scope=")) {
+      const v = arg === "--plugin-scope" ? argv[++i] : arg.slice("--plugin-scope=".length);
+      if (!v || !PLUGIN_SCOPES.includes(v.trim())) {
+        return {
+          error: {
+            code: EXIT.INVALID_ARG,
+            message: `--plugin-scope requires one of: ${PLUGIN_SCOPES.join(", ")}`
+          }
+        };
+      }
+      pluginScope = v.trim();
+      plugin = true;
+    } else if (arg === "--no-statusline") statusline = false;
+    else if (arg === "--cc" || arg === "--command-code") commandCode = true;
+    else if (arg === "--cursor-only") {
+      cursor = true;
+      claude = false;
+    } else if (arg === "--claude-only") {
+      cursor = false;
+      claude = true;
+    } else if (arg === "--no-cursor") cursor = false;
+    else if (arg === "--no-claude") claude = false;
+    else if (arg === "--target" || arg.startsWith("--target=")) {
+      const v = arg === "--target" ? argv[++i] : arg.slice("--target=".length);
+      if (v === void 0 || v.trim() === "") {
+        return { error: { code: EXIT.INVALID_ARG, message: "--target requires a path" } };
+      }
+      targetDir = v.trim();
+    } else if (arg === "--platform" || arg.startsWith("--platform=")) {
+      const v = arg === "--platform" ? argv[++i] : arg.slice("--platform=".length);
+      if (v === void 0 || v.trim() === "") {
+        return { error: { code: EXIT.INVALID_ARG, message: "--platform requires a path" } };
+      }
+      platformRoot = v.trim();
+    } else if (arg.startsWith("-")) {
+      return { error: { code: EXIT.USAGE, message: `unknown flag: ${arg}` } };
+    } else {
+      return { error: { code: EXIT.USAGE, message: `unexpected argument: ${arg}` } };
+    }
+  }
+  return {
+    args: {
+      targetDir: targetDir ?? "",
+      platformRoot: platformRoot ?? "",
+      cursor,
+      claude,
+      claudeApply,
+      plugin,
+      pluginApply,
+      pluginScope,
+      statusline,
+      commandCode,
+      force,
+      json,
+      dryRun,
+      skipConflictCheck,
+      registerVault: registerVaultFlag,
+      workspace
+    }
+  };
+}
+function mcpCliPath(platformRoot, joinPath) {
+  return joinPath(platformRoot, ...MCP_REL);
+}
+function resolveInstallTargetDir(argsTargetDir, env, fallbackCwd) {
+  return argsTargetDir && argsTargetDir.trim() || env.HS_VAULT_ROOT?.trim() || env.HS_INVOKED_CWD?.trim() || fallbackCwd;
+}
+function renderCursorMcpJson(cliAbsPath) {
+  return {
+    mcpServers: {
+      heyspex: {
+        type: "stdio",
+        command: "node",
+        args: [cliAbsPath],
+        env: {
+          HEYSPEX_VAULT_ROOT: "${workspaceFolder}"
+        }
+      }
+    }
+  };
+}
+function renderClaudeMcpJson(cliAbsPath) {
+  return {
+    mcpServers: {
+      heyspex: {
+        type: "stdio",
+        command: "node",
+        args: [cliAbsPath],
+        env: {
+          HEYSPEX_VAULT_ROOT: "${CLAUDE_PROJECT_DIR:-.}"
+        }
+      }
+    }
+  };
+}
+function buildClaudeMcpAddCommandPowerShell(targetDir, cliAbsPath) {
+  const escapedCli = cliAbsPath.replace(/'/g, "''");
+  const escapedTarget = targetDir.replace(/'/g, "''");
+  return [
+    `Set-Location -LiteralPath '${escapedTarget}'`,
+    `claude mcp add --transport stdio --scope project --env HEYSPEX_VAULT_ROOT="$PWD" heyspex -- node '${escapedCli}'`
+  ].join("\n");
+}
+var PLUGIN_MARKETPLACE_NAME = "heyspex-marketplace";
+var PLUGIN_INSTALL_SPEC = `heyspex@${PLUGIN_MARKETPLACE_NAME}`;
+var PLUGIN_SCOPES = ["user", "project", "local"];
+function resolvePluginSpec(platformRoot, deps) {
+  const fallback = {
+    marketplaceName: PLUGIN_MARKETPLACE_NAME,
+    pluginName: "heyspex",
+    spec: PLUGIN_INSTALL_SPEC
+  };
+  const raw = deps.readFile(pluginMarketplaceManifestPath(platformRoot, deps.joinPath));
+  if (!raw) return fallback;
+  try {
+    const parsed = JSON.parse(raw);
+    const marketplaceName = typeof parsed.name === "string" && parsed.name.trim() ? parsed.name.trim() : fallback.marketplaceName;
+    const firstNamed = Array.isArray(parsed.plugins) ? parsed.plugins.find((p) => typeof p?.name === "string" && p.name.trim()) : void 0;
+    const pluginName = firstNamed ? firstNamed.name.trim() : fallback.pluginName;
+    return { marketplaceName, pluginName, spec: `${pluginName}@${marketplaceName}` };
+  } catch {
+    return fallback;
+  }
+}
+function pluginMarketplaceManifestPath(platformRoot, joinPath) {
+  return joinPath(platformRoot, ".claude-plugin", "marketplace.json");
+}
+function buildClaudePluginInstallCommandPowerShell(targetDir, platformRoot, spec = PLUGIN_INSTALL_SPEC, scope = "project") {
+  const escapedTarget = targetDir.replace(/'/g, "''");
+  const escapedPlatform = platformRoot.replace(/'/g, "''");
+  return [
+    `Set-Location -LiteralPath '${escapedTarget}'`,
+    `claude plugin marketplace add '${escapedPlatform}'`,
+    `claude plugin install ${spec} --scope ${scope}`
+  ].join("\n");
+}
+var STATUSLINE_VENDOR_FILES = [
+  ["scripts", "install-statusline.mjs"],
+  ["scripts", "claude-statusline", "statusline-command.mjs"],
+  ["scripts", "claude-statusline", "statusline-command.ps1"],
+  ["scripts", "claude-statusline", "fonts", "HeySpexIcons.ttf"],
+  ["scripts", "claude-statusline", "fonts", "README.md"]
+];
+function renderStatusLineEntry() {
+  return {
+    type: "command",
+    command: 'node "$CLAUDE_PROJECT_DIR/scripts/claude-statusline/statusline-command.mjs"',
+    padding: 2,
+    refreshInterval: 5
+  };
+}
+function buildCommandCodeMcpAddCommand(cliAbsPath) {
+  const escapedCli = cliAbsPath.replace(/'/g, "''");
+  return [
+    `cmdc mcp add --transport stdio heyspex -- node '${escapedCli}'`,
+    `cmdc mcp env heyspex HEYSPEX_VAULT_ROOT "$PWD"`
+  ].join("\n");
+}
+function shouldWrite(exists, force) {
+  return !exists || force;
+}
+function pathTail(p) {
+  return p.split(/[\\/]/).filter(Boolean).pop() ?? p;
+}
+function slugFromPath(p) {
+  return pathTail(p).toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+}
+function registerInstalledVault(args, ctx) {
+  const { targetDir, readFile, joinPath, registryOpts, now, basename } = ctx;
+  let vaultId;
+  let schemaVersion = HEYSPEX_YAML_SCHEMA_VERSION;
+  const yamlContent = readFile(joinPath(targetDir, "heyspex.yaml"));
+  if (yamlContent) {
+    const existing = parseVaultId(yamlContent);
+    if (existing) vaultId = existing;
+    const versionMatch = yamlContent.match(/^schema_version:\s*(\d+)\s*$/m);
+    if (versionMatch) schemaVersion = Number(versionMatch[1]);
+  }
+  if (!vaultId) vaultId = slugFromPath(targetDir);
+  const workspaceId = args.workspace ?? "default";
+  const displayName = basename(targetDir);
+  const before = loadVaultRegistry(registryOpts);
+  const workspaceExisted = before.workspaces.some((w) => w.id === workspaceId);
+  const result = {
+    registered: !args.dryRun,
+    vault_id: vaultId,
+    workspace_id: workspaceId,
+    workspace_created: !workspaceExisted && args.workspace !== void 0,
+    workspace_activated: false,
+    repo_root_abs: targetDir,
+    schema_version: schemaVersion
+  };
+  if (args.dryRun) return result;
+  if (args.workspace !== void 0) {
+    if (!workspaceExisted) {
+      registerWorkspace(
+        { id: workspaceId, display_name: workspaceId, created_at: now },
+        registryOpts
+      );
+    }
+    setActiveWorkspaceId(workspaceId, registryOpts);
+    result.workspace_activated = true;
+  }
+  registerVault(
+    {
+      id: vaultId,
+      workspace_id: workspaceId,
+      display_name: displayName,
+      repo_root_abs: targetDir,
+      schema_version: schemaVersion,
+      registered_at: now
+    },
+    registryOpts
+  );
+  return result;
+}
+function resolveInstallContract(platformRoot, deps) {
+  try {
+    const raw = deps.readFile(deps.joinPath(platformRoot, "spex-console", "settings.json"));
+    if (!raw) return true;
+    const parsed = JSON.parse(raw);
+    const v = parsed?.agentMemory?.installContract;
+    return typeof v === "boolean" ? v : true;
+  } catch {
+    return true;
+  }
+}
+function runInstall(args, deps) {
+  const targetDir = deps.resolvedTarget;
+  const platformRoot = deps.resolvedPlatform;
+  const cliPath = mcpCliPath(platformRoot, deps.joinPath);
+  if (!deps.fileExists(cliPath)) {
+    return {
+      code: EXIT.INVALID_ARG,
+      message: `HeySpex platform MCP not found at ${cliPath}
+    Pass --platform <path-to-workflow-protocol> or run hs install from the platform repo.`,
+      payload: { ok: false, error: "platform_mcp_missing", path: cliPath },
+      isError: true
+    };
+  }
+  const steps = [];
+  const nextSteps = [];
+  const conflicts = args.skipConflictCheck ? [] : scanInstallConflicts(targetDir, {
+    fileExists: deps.fileExists,
+    readFile: deps.readFile,
+    joinPath: deps.joinPath
+  });
+  const specsDir = deps.joinPath(targetDir, "specs");
+  const cursorPath = deps.joinPath(targetDir, ".cursor", "mcp.json");
+  const claudePath = deps.joinPath(targetDir, ".mcp.json");
+  const gitkeepPath = deps.joinPath(specsDir, ".gitkeep");
+  const planWrite = (kind, filePath, exists, detail) => {
+    if (!shouldWrite(exists, args.force)) {
+      steps.push({
+        kind,
+        path: filePath,
+        action: "skipped",
+        detail: "already exists (use --force)"
+      });
+      return false;
+    }
+    steps.push({
+      kind,
+      path: filePath,
+      action: args.dryRun ? "would_create" : "created",
+      detail
+    });
+    return !args.dryRun;
+  };
+  if (!deps.fileExists(specsDir)) {
+    if (args.dryRun) {
+      steps.push({ kind: "specs_dir", path: specsDir, action: "would_create" });
+    } else {
+      deps.mkdir(specsDir);
+      steps.push({ kind: "specs_dir", path: specsDir, action: "created" });
+    }
+  }
+  if (planWrite("specs_gitkeep", gitkeepPath, deps.fileExists(gitkeepPath))) {
+    deps.writeFile(gitkeepPath, "");
+  }
+  const markerPath = deps.joinPath(targetDir, "heyspex.yaml");
+  const markerExists = deps.fileExists(markerPath);
+  if (!markerExists || args.force) {
+    if (args.dryRun) {
+      steps.push({
+        kind: "heyspex_yaml",
+        path: markerPath,
+        action: "would_create",
+        detail: markerExists ? "overwrite with --force" : void 0
+      });
+    } else {
+      const initResult = runInit(
+        {
+          consoleUrl: process.env.HEYSPEX_CONSOLE_URL?.trim() || "https://console.heyspex.local",
+          vaultRoot: "specs/",
+          force: args.force,
+          json: false
+        },
+        { ...deps, repoRoot: targetDir }
+      );
+      if (initResult.isError) {
+        return initResult;
+      }
+      steps.push({
+        kind: "heyspex_yaml",
+        path: markerPath,
+        action: "created",
+        detail: markerExists ? "overwrote" : "initialized"
+      });
+    }
+  } else {
+    steps.push({
+      kind: "heyspex_yaml",
+      path: markerPath,
+      action: "skipped",
+      detail: "already initialized"
+    });
+  }
+  const cursorJson = `${JSON.stringify(renderCursorMcpJson(cliPath), null, 2)}
+`;
+  if (args.cursor) {
+    if (planWrite("cursor_mcp", cursorPath, deps.fileExists(cursorPath))) {
+      deps.mkdir(deps.joinPath(targetDir, ".cursor"));
+      deps.writeFile(cursorPath, cursorJson);
+    }
+    nextSteps.push(
+      "Cursor: toggle heyspex MCP off/on in Settings \u2192 Tools & MCP (or restart Cursor)."
+    );
+  }
+  const claudeJson = `${JSON.stringify(renderClaudeMcpJson(cliPath), null, 2)}
+`;
+  const claudePs = buildClaudeMcpAddCommandPowerShell(targetDir, cliPath);
+  if (args.claude) {
+    if (planWrite("claude_mcp", claudePath, deps.fileExists(claudePath))) {
+      deps.writeFile(claudePath, claudeJson);
+    }
+    if (args.claudeApply) {
+      steps.push({
+        kind: "claude_mcp_apply",
+        path: "claude mcp add",
+        action: args.dryRun ? "would_create" : "created",
+        detail: "see claude_powershell if apply fails"
+      });
+    } else {
+      nextSteps.push(
+        "Claude Code: run the printed PowerShell block, or re-run with --claude-apply if `claude` is on PATH."
+      );
+    }
+  }
+  const pluginSpec = resolvePluginSpec(platformRoot, deps);
+  const pluginScope = args.pluginScope ?? "project";
+  const pluginPs = buildClaudePluginInstallCommandPowerShell(
+    targetDir,
+    platformRoot,
+    pluginSpec.spec,
+    pluginScope
+  );
+  const marketplaceManifest = pluginMarketplaceManifestPath(platformRoot, deps.joinPath);
+  const pluginAvailable = deps.fileExists(marketplaceManifest);
+  if (args.plugin) {
+    if (!pluginAvailable) {
+      steps.push({
+        kind: "claude_plugin",
+        path: marketplaceManifest,
+        action: "skipped",
+        detail: "platform checkout has no .claude-plugin/marketplace.json"
+      });
+    } else if (args.pluginApply) {
+      steps.push({
+        kind: "claude_plugin_apply",
+        path: "claude plugin install",
+        action: args.dryRun ? "would_create" : "created",
+        detail: "see claude_plugin_powershell if apply fails"
+      });
+    } else {
+      steps.push({
+        kind: "claude_plugin",
+        path: pluginSpec.spec,
+        action: "skipped",
+        detail: "printed below \u2014 run in PowerShell, or re-run with --plugin-apply"
+      });
+      nextSteps.push(
+        "Claude Code plugin: run the printed PowerShell block, or re-run with --plugin-apply if `claude` is on PATH."
+      );
+    }
+    if (pluginAvailable && args.claude) {
+      nextSteps.push(
+        "Plugin AND project .mcp.json both register the heyspex MCP server \u2014 once the plugin validates, re-run with --no-claude for plugin-only wiring (HS-QTBK prototype)."
+      );
+    }
+  }
+  if ((args.statusline ?? true) && args.claude) {
+    const statuslineShipsInPlatform = deps.fileExists(
+      deps.joinPath(platformRoot, "scripts", "claude-statusline", "statusline-command.mjs")
+    );
+    if (!statuslineShipsInPlatform) {
+      steps.push({
+        kind: "claude_statusline",
+        path: deps.joinPath(targetDir, ".claude", "settings.json"),
+        action: "skipped",
+        detail: "not shipped in this package"
+      });
+    } else {
+      if (targetDir !== platformRoot) {
+        if (!deps.copyFile) {
+          steps.push({
+            kind: "statusline_vendor",
+            path: deps.joinPath(targetDir, "scripts", "claude-statusline"),
+            action: "skipped",
+            detail: "no copyFile capability in this caller"
+          });
+        } else {
+          let copied = 0;
+          let missing = 0;
+          for (const rel of STATUSLINE_VENDOR_FILES) {
+            const src = deps.joinPath(platformRoot, ...rel);
+            const dest = deps.joinPath(targetDir, ...rel);
+            if (!deps.fileExists(src)) {
+              missing += 1;
+              continue;
+            }
+            if (deps.fileExists(dest) && !args.force) continue;
+            copied += 1;
+            if (!args.dryRun) {
+              deps.mkdir(deps.joinPath(targetDir, ...rel.slice(0, -1)));
+              deps.copyFile(src, dest);
+            }
+          }
+          steps.push({
+            kind: "statusline_vendor",
+            path: deps.joinPath(targetDir, "scripts", "claude-statusline"),
+            action: copied === 0 ? "skipped" : args.dryRun ? "would_create" : "created",
+            detail: copied === 0 ? "already vendored" : `${copied} file${copied === 1 ? "" : "s"} (renderer + font + installer)` + (missing > 0 ? `; ${missing} missing from platform` : "")
+          });
+        }
+      }
+      const settingsPath = deps.joinPath(targetDir, ".claude", "settings.json");
+      const entry = renderStatusLineEntry();
+      const raw = deps.readFile(settingsPath);
+      let settings = raw === null ? {} : null;
+      if (raw !== null) {
+        try {
+          settings = JSON.parse(raw);
+        } catch {
+          settings = null;
+        }
+      }
+      const existing = settings?.statusLine;
+      const ours = typeof existing?.command === "string" && existing.command.includes("statusline-command.");
+      if (settings === null) {
+        steps.push({
+          kind: "claude_statusline",
+          path: settingsPath,
+          action: "skipped",
+          detail: "settings.json unparseable \u2014 wire the statusline manually"
+        });
+      } else if (existing && !ours) {
+        steps.push({
+          kind: "claude_statusline",
+          path: settingsPath,
+          action: "skipped",
+          detail: "a foreign statusLine entry exists \u2014 left alone"
+        });
+      } else if (existing && JSON.stringify(existing) === JSON.stringify(entry)) {
+        steps.push({
+          kind: "claude_statusline",
+          path: settingsPath,
+          action: "skipped",
+          detail: "already installed"
+        });
+      } else {
+        steps.push({
+          kind: "claude_statusline",
+          path: settingsPath,
+          action: args.dryRun ? "would_create" : "created",
+          detail: existing ? "repaired to canonical entry" : "branded statusline (vendored renderer)"
+        });
+        if (!args.dryRun) {
+          settings.statusLine = entry;
+          deps.mkdir(deps.joinPath(targetDir, ".claude"));
+          deps.writeFile(settingsPath, `${JSON.stringify(settings, null, 2)}
+`);
+        }
+      }
+    }
+  }
+  const commandCodePs = buildCommandCodeMcpAddCommand(cliPath);
+  if (args.commandCode) {
+    steps.push({
+      kind: "commandcode_mcp",
+      path: "cmdc mcp add",
+      action: args.dryRun ? "would_create" : "created",
+      detail: "printed below \u2014 run in PowerShell to register heyspex MCP server"
+    });
+    nextSteps.push(
+      "Command Code: run the printed PowerShell block to register the heyspex MCP server."
+    );
+  }
+  const installContract = resolveInstallContract(platformRoot, deps);
+  if (installContract) {
+    const agentContract = renderCustomerAgentContract();
+    const claudeMdPath = deps.joinPath(targetDir, "CLAUDE.md");
+    const agentsMdPath = deps.joinPath(targetDir, "AGENTS.md");
+    if (args.claude) {
+      if (planWrite("claude_md", claudeMdPath, deps.fileExists(claudeMdPath), "thin agent contract")) {
+        deps.writeFile(claudeMdPath, agentContract);
+      }
+    }
+    if (planWrite(
+      "agents_md",
+      agentsMdPath,
+      deps.fileExists(agentsMdPath),
+      "cross-tool agent contract"
+    )) {
+      deps.writeFile(agentsMdPath, agentContract);
+    }
+  } else {
+    steps.push({
+      kind: "agent_contract",
+      path: "CLAUDE.md / AGENTS.md",
+      action: "skipped",
+      detail: "disabled in Settings \u2192 Config \u2192 Memory"
+    });
+  }
+  let registration;
+  if (args.registerVault) {
+    registration = registerInstalledVault(args, {
+      targetDir,
+      readFile: deps.readFile,
+      joinPath: deps.joinPath,
+      registryOpts: deps.registryOpts,
+      now: deps.now ? deps.now() : (/* @__PURE__ */ new Date()).toISOString(),
+      basename: deps.basename ?? pathTail
+    });
+    steps.push({
+      kind: "vault_register",
+      path: registration.repo_root_abs,
+      action: args.dryRun ? "would_create" : "created",
+      detail: `vault "${registration.vault_id}" \u2192 workspace "${registration.workspace_id}"` + (registration.workspace_activated ? " (active)" : "")
+    });
+  }
+  if (conflicts.length > 0) {
+    nextSteps.unshift(
+      "Resolve conflict scan hits above before treating HeySpex as the only agent queue."
+    );
+  }
+  nextSteps.push(`Open the project in Cursor, Claude Code, or Command Code: ${targetDir}`);
+  nextSteps.push("Start capturing work with /hs-capture or file specs via heyspex MCP.");
+  const payload = {
+    ok: true,
+    target_dir: targetDir,
+    platform_root: platformRoot,
+    mcp_cli: cliPath,
+    steps,
+    conflicts,
+    claude_powershell: args.claude ? claudePs : void 0,
+    claude_plugin_powershell: args.plugin && pluginAvailable ? pluginPs : void 0,
+    claude_plugin_spec: args.plugin && pluginAvailable ? pluginSpec.spec : void 0,
+    claude_plugin_scope: args.plugin && pluginAvailable ? pluginScope : void 0,
+    command_code_powershell: args.commandCode ? commandCodePs : void 0,
+    next_steps: nextSteps,
+    dry_run: args.dryRun,
+    registration
+  };
+  const lines = [
+    args.dryRun ? "hs install (dry run) \u2014 no files written." : "hs install \u2014 vault bootstrap complete.",
+    "",
+    `Target:   ${targetDir}`,
+    `Platform: ${platformRoot}`,
+    `MCP:      ${cliPath}`,
+    ""
+  ];
+  if (!args.skipConflictCheck) {
+    lines.push(formatConflictReport(conflicts), "");
+  }
+  lines.push(
+    "Steps:",
+    ...steps.map(
+      (s) => `  \u2022 ${s.kind}: ${s.action} \u2192 ${s.path}${s.detail ? ` (${s.detail})` : ""}`
+    )
+  );
+  if (args.claude && claudePs) {
+    lines.push("", "Claude Code (PowerShell):", claudePs);
+  }
+  if (args.plugin && pluginAvailable && pluginPs) {
+    lines.push("", "Claude Code plugin (PowerShell):", pluginPs);
+  }
+  if (args.commandCode && commandCodePs) {
+    lines.push("", "Command Code (PowerShell):", commandCodePs);
+  }
+  if (nextSteps.length) {
+    lines.push("", "Next:", ...nextSteps.map((s) => `  \u2022 ${s}`));
+  }
+  return {
+    code: EXIT.OK,
+    message: lines.join("\n"),
+    payload,
+    isError: false
+  };
+}
+var INSTALL_HELP = [
+  "Usage:",
+  "  hs install [--target <dir>] [--platform <dir>] [--force] [--dry-run] [--json]",
+  "             [--no-cursor] [--no-claude] [--claude-apply]",
+  "             [--plugin | --plugin-apply] [--plugin-scope user|project|local]",
+  "             [--no-statusline]",
+  "             [--cc | --command-code] [--register-vault [--workspace <id>]]",
+  "",
+  "Bootstrap a project vault for HeySpex agent tooling:",
+  "  \u2022 specs/ + heyspex.yaml (via hs init)",
+  "  \u2022 .cursor/mcp.json  \u2014 Cursor MCP (gitignored, machine-local path to platform MCP)",
+  "  \u2022 .mcp.json         \u2014 Claude Code project MCP (absolute platform path)",
+  "  \u2022 CLAUDE.md / AGENTS.md \u2014 thin agent contract pointing at the HeySpex MCP server",
+  "",
+  "Conflict scan: every install checks the target repo against the known-conflict",
+  "registry (beads, workflow-pm, bd hooks, \u2026). See:",
+  "  specs/protocols/customer-vault-local-install-protocol.md",
+  "",
+  "Run from the HeySpex platform repo, or pass --platform to its checkout.",
+  "Target defaults to the current directory.",
+  "",
+  "Flags:",
+  "  --target <dir>     Project repo to bootstrap (default: cwd).",
+  "  --platform <dir>   HeySpex platform checkout (default: HS_INSTALL_PLATFORM or dispatcher root).",
+  "  --claude-apply     Run `claude mcp add --scope project` after writing files.",
+  "  --plugin           Print the Claude Code plugin registration block (self-hosted",
+  "                     marketplace at the platform root \u2014 HS-QTBK prototype).",
+  "  --plugin-apply     Run `claude plugin marketplace add` + `claude plugin install`",
+  "                     after writing files. Marketplace + plugin names are read from",
+  `                     the platform's .claude-plugin/marketplace.json (fallback: ${PLUGIN_INSTALL_SPEC}).`,
+  "  --plugin-scope <s> Plugin install scope: user, project (default), or local.",
+  "                     Implies --plugin.",
+  "  --no-statusline    Skip the branded statusline (statusLine entry in the target's",
+  "                     .claude/settings.json + machine-level glyph install).",
+  "  --cc, --command-code  Print `cmdc mcp add` PowerShell one-liner for Command Code.",
+  "  --register-vault   Register this repo's vault into ~/.heyspex/registry.json during install.",
+  "  --workspace <id>   With --register-vault: ensure this workspace exists, make it active,",
+  '                     and associate the vault with it (default workspace: "default").',
+  "  --no-cursor        Skip .cursor/mcp.json.",
+  "  --no-claude        Skip .mcp.json and Claude instructions.",
+  "  --force            Overwrite existing MCP manifests and heyspex.yaml.",
+  "  --dry-run          Print the plan without writing.",
+  "  --skip-conflict-check  Skip the known-conflict registry scan.",
+  "  --json             Machine-readable result.",
+  "  --help, -h         Show this help.",
+  "",
+  "Exit codes: 0 ok \xB7 1 usage \xB7 11 bad-arg \xB7 13 write-failed"
+].join("\n");
+
+// spex-console/bin/hs-install.ts
+function main() {
+  const platformDefault = process2.env.HS_INSTALL_PLATFORM?.trim() || process2.env.HEYSPEX_PLATFORM_ROOT?.trim() || process2.env.HS_PKG_ROOT?.trim() || "";
+  const parsed = parseInstallArgs(process2.argv.slice(3));
+  if (parsed.help) {
+    process2.stdout.write(`${INSTALL_HELP}
+`);
+    process2.exit(EXIT.OK);
+  }
+  if (parsed.error) {
+    process2.stderr.write(`hs install: ${parsed.error.message}
+`);
+    process2.exit(parsed.error.code);
+  }
+  const args = parsed.args;
+  const targetDir = resolve(resolveInstallTargetDir(args.targetDir, process2.env, process2.cwd()));
+  const platformRoot = resolve(args.platformRoot || platformDefault || process2.cwd());
+  const deps = {
+    repoRoot: targetDir,
+    resolvedTarget: targetDir,
+    resolvedPlatform: platformRoot,
+    fileExists: (p) => existsSync2(p),
+    readFile: (p) => {
+      try {
+        return readFileSync4(p, "utf8");
+      } catch {
+        return null;
+      }
+    },
+    writeFile: (p, c) => writeFileSync2(p, c, "utf8"),
+    mkdir: (p) => mkdirSync2(p, { recursive: true }),
+    copyFile: (src, dest) => copyFileSync(src, dest),
+    joinPath: (...s) => join4(...s)
+  };
+  const result = runInstall(args, deps);
+  const sink = result.isError ? process2.stderr : process2.stdout;
+  sink.write(`${args.json ? JSON.stringify(result.payload, null, 2) : result.message}
+`);
+  if (!result.isError && args.claudeApply && !args.dryRun && args.claude) {
+    const cliPath = mcpCliPath(platformRoot, join4);
+    const claude = spawnSync(
+      "claude",
+      [
+        "mcp",
+        "add",
+        "--transport",
+        "stdio",
+        "--scope",
+        "project",
+        "--env",
+        `HEYSPEX_VAULT_ROOT=${targetDir}`,
+        "heyspex",
+        "--",
+        process2.execPath,
+        cliPath
+      ],
+      { cwd: targetDir, encoding: "utf8", shell: process2.platform === "win32" }
+    );
+    if (claude.status !== 0) {
+      process2.stderr.write(
+        `hs install: claude mcp add failed (exit ${claude.status ?? "?"}).
+${claude.stderr || claude.stdout || ""}
+Run manually:
+${buildClaudeMcpAddCommandPowerShell(targetDir, cliPath)}
+`
+      );
+    } else {
+      process2.stdout.write("Claude Code: registered heyspex MCP (--scope project).\n");
+    }
+  }
+  if (!result.isError && args.pluginApply && !args.dryRun && existsSync2(pluginMarketplaceManifestPath(platformRoot, join4))) {
+    const shell = process2.platform === "win32";
+    const spec = resolvePluginSpec(platformRoot, {
+      readFile: (p) => {
+        try {
+          return readFileSync4(p, "utf8");
+        } catch {
+          return null;
+        }
+      },
+      joinPath: join4
+    });
+    const scope = args.pluginScope ?? "project";
+    const manualBlock = buildClaudePluginInstallCommandPowerShell(
+      targetDir,
+      platformRoot,
+      spec.spec,
+      scope
+    );
+    const claudeRun = (cliArgs) => spawnSync("claude", cliArgs, { cwd: targetDir, encoding: "utf8", shell });
+    let marketplace = claudeRun(["plugin", "marketplace", "add", platformRoot]);
+    if (marketplace.status !== 0 && /already/i.test(marketplace.stderr + marketplace.stdout)) {
+      marketplace = claudeRun(["plugin", "marketplace", "update", spec.marketplaceName]);
+    }
+    if (marketplace.status !== 0) {
+      process2.stderr.write(
+        `hs install: claude plugin marketplace add failed (exit ${marketplace.status ?? "?"}).
+${marketplace.stderr || marketplace.stdout || ""}
+Run manually:
+${manualBlock}
+`
+      );
+    } else {
+      const install = claudeRun(["plugin", "install", spec.spec, "--scope", scope]);
+      if (install.status !== 0 && !/already/i.test(install.stderr + install.stdout)) {
+        process2.stderr.write(
+          `hs install: claude plugin install failed (exit ${install.status ?? "?"}).
+${install.stderr || install.stdout || ""}
+Run manually:
+${manualBlock}
+`
+        );
+      } else {
+        process2.stdout.write(
+          `Claude Code: installed plugin ${spec.spec} (--scope ${scope}). Restart the Claude Code session to load it.
+`
+        );
+      }
+    }
+  }
+  if (!result.isError && !args.dryRun && args.claude && (args.statusline ?? true)) {
+    const glyphScript = [
+      join4(targetDir, "scripts", "install-statusline.mjs"),
+      join4(platformRoot, "scripts", "install-statusline.mjs")
+    ].find((p) => existsSync2(p));
+    const glyph = glyphScript ? spawnSync(process2.execPath, [glyphScript, "--glyph-only"], {
+      cwd: targetDir,
+      encoding: "utf8"
+    }) : { status: 1, stdout: "", stderr: "install-statusline.mjs not found" };
+    if (glyph.status === 0) {
+      const out = (glyph.stdout || "").trim();
+      if (out) process2.stdout.write(`${out}
+`);
+    } else {
+      process2.stderr.write(
+        `hs install: glyph install skipped (${(glyph.stderr || glyph.stdout || "unknown error").trim()}) \u2014 see scripts/claude-statusline/fonts/README.md.
+`
+      );
+    }
+  }
+  process2.exit(result.code);
+}
+main();