heyspex 0.2.1 → 0.2.3

package/dist/cli/hs-install.mjs

@@ -154,9 +154,9 @@ function resolveBearer({ envToken, credentialsText, accountId, legacyAccountId }
   if (entry?.mcp_token) return { token: entry.mcp_token, source: "credentials-file" };
   return { token: null, source: null };
 }
-function readTextOrNull(read, path5) {
+function readTextOrNull(read, path7) {
   try {
-    const raw = read(path5);
+    const raw = read(path7);
     return typeof raw === "string" ? raw : null;
   } catch {
     return null;
@@ -260,6 +260,11 @@ function readLocalDevModeRecord({ homeDir = heyspexHome(), readFile = defaultRea
     return { record: null, parseError: `unparseable dev-mode.json: ${String(err?.message ?? err)}` };
   }
 }
+function overrideCloudCheck(source, cloudKnown, staleAgainstCloud) {
+  if (source !== "local-override") return "not-applicable";
+  if (!cloudKnown) return "unverified";
+  return staleAgainstCloud ? "stale" : "in-sync";
+}
 function resolveDevMode({
   env = process.env,
   homeDir = heyspexHome(),
@@ -299,6 +304,7 @@ function resolveDevMode({
   const semantics = deriveSemantics(mode, reliance);
   const consoleUrl = source === "local-override" && local.record?.console_url ? local.record.console_url.replace(/\/+$/, "") : semantics.consoleUrl;
   const staleAgainstCloud = source === "local-override" && cloudValue !== null && (cloudValue.mode !== mode || mode === "dev" && cloudValue.reliance !== semantics.reliance);
+  const cloudCheck = overrideCloudCheck(source, cloudKnown, staleAgainstCloud);
   return {
     mode,
     reliance: semantics.reliance,
@@ -316,7 +322,8 @@ function resolveDevMode({
       present: local.record !== null,
       record: local.record,
       parseError: local.parseError,
-      staleAgainstCloud
+      staleAgainstCloud,
+      cloudCheck
     },
     cloudSetting: { known: cloudKnown, value: cloudValue }
   };
@@ -996,17 +1003,17 @@ var require_gray_matter = __commonJS({
 });
 
 // spex-console/bin/hs-install.ts
-import { spawnSync as spawnSync3 } from "node:child_process";
+import { spawnSync as spawnSync4 } from "node:child_process";
 import {
-  copyFileSync,
-  existsSync as existsSync6,
-  mkdirSync as mkdirSync6,
+  copyFileSync as copyFileSync2,
+  existsSync as existsSync9,
+  mkdirSync as mkdirSync7,
   readdirSync as readdirSync2,
-  readFileSync as readFileSync11,
-  statSync,
-  writeFileSync as writeFileSync6
+  readFileSync as readFileSync14,
+  statSync as statSync5,
+  writeFileSync as writeFileSync7
 } from "node:fs";
-import { join as join12, resolve as resolve5 } from "node:path";
+import { join as join12, resolve as resolve6 } from "node:path";
 import process4 from "node:process";
 
 // scripts/lib/console-url-resolver.mjs
@@ -1115,7 +1122,9 @@ function resolveConsoleUrl({
 }
 
 // scripts/lib/shared-path-helpers.mjs
+import { realpathSync } from "node:fs";
 import { isAbsolute, resolve as resolve2, sep } from "node:path";
+import { fileURLToPath } from "node:url";
 function resolveCodeRoot({
   explicit,
   packageRoot,
@@ -1133,16 +1142,16 @@ function resolveCodeRoot({
 }
 
 // spex-console/src/lib/cli/control-shared.ts
-import path from "node:path";
+import path2 from "node:path";
 
 // scripts/lib/hs-command.mjs
 import { existsSync } from "node:fs";
 import { delimiter, dirname as dirname2, join as join4 } from "node:path";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
 var HS_BIN_NAME = "hs";
 var HS_DISPATCHER_PATH = (() => {
   try {
-    const here = dirname2(fileURLToPath(import.meta.url));
+    const here = dirname2(fileURLToPath2(import.meta.url));
     return join4(dirname2(dirname2(here)), "bin", "hs.mjs");
   } catch {
     return null;
@@ -1156,8 +1165,8 @@ var HS_DISPATCHER_PREFIX = HS_DISPATCHER_PATH ? `node ${shellQuote(HS_DISPATCHER
 // vendor/heyspex-mcp/console-fetch.mjs
 init_heyspex_home();
 init_credentials();
-import { readFileSync as readFileSync7 } from "node:fs";
-import { homedir as homedir7 } from "node:os";
+import { readFileSync as readFileSync8 } from "node:fs";
+import { homedir as homedir8 } from "node:os";
 import { join as join8 } from "node:path";
 
 // vendor/heyspex-mcp/session-owner.mjs
@@ -1182,14 +1191,14 @@ var VAULT_LESS_ENDPOINTS = Object.freeze([
   "GET /api/workspaces",
   "* /api/admin/dev-mode"
 ]);
-function pathnameOf(path5) {
-  const raw = String(path5 ?? "").split("?")[0].split("#")[0];
+function pathnameOf(path7) {
+  const raw = String(path7 ?? "").split("?")[0].split("#")[0];
   const noTrailing = raw.length > 1 ? raw.replace(/\/+$/, "") : raw;
   return noTrailing || "/";
 }
-function isVaultLessEndpoint(method, path5) {
+function isVaultLessEndpoint(method, path7) {
   const m = String(method || "GET").toUpperCase();
-  const pathname = pathnameOf(path5);
+  const pathname = pathnameOf(path7);
   return VAULT_LESS_ENDPOINTS.some((row) => {
     const [rowMethod, rowPath] = row.split(" ");
     return rowPath === pathname && (rowMethod === "*" || rowMethod === m);
@@ -1210,9 +1219,30 @@ import { basename, join as join6, isAbsolute as isAbsolute2 } from "node:path";
 
 // vendor/heyspex-mcp/vault-resolve.mjs
 init_heyspex_home();
-import { existsSync as existsSync3, readFileSync as readFileSync6 } from "node:fs";
-import { homedir as homedir6, tmpdir } from "node:os";
-import { dirname as dirname3, join as join7, resolve as resolve3 } from "node:path";
+import { existsSync as existsSync4, readFileSync as readFileSync7, realpathSync as realpathSync3, statSync as statSync3 } from "node:fs";
+import { homedir as homedir7, tmpdir } from "node:os";
+
+// vendor/heyspex-mcp/usable-dir-env.mjs
+import { statSync } from "node:fs";
+import { isAbsolute as isAbsolute3 } from "node:path";
+
+// vendor/heyspex-mcp/vault-resolve.mjs
+import { basename as basename2, dirname as dirname3, join as join7, resolve as resolve3 } from "node:path";
+
+// vendor/heyspex-mcp/vault-binding.mjs
+import {
+  copyFileSync,
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync4,
+  readFileSync as readFileSync6,
+  realpathSync as realpathSync2,
+  renameSync as renameSync3,
+  statSync as statSync2,
+  unlinkSync,
+  writeFileSync as writeFileSync4
+} from "node:fs";
+import { homedir as homedir6 } from "node:os";
+import path from "node:path";
 
 // vendor/heyspex-mcp/console-fetch.mjs
 var SCOPE_REFUSAL_CODES = Object.freeze(["VAULT_SCOPE_MISMATCH", "ACCOUNT_MISMATCH", "VAULT_NOT_REGISTERED"]);
@@ -1221,17 +1251,17 @@ var SCOPE_REFUSAL_CODES = Object.freeze(["VAULT_SCOPE_MISMATCH", "ACCOUNT_MISMAT
 init_credentials();
 
 // spex-console/src/lib/vault-registry/registry-file.ts
-import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync8, renameSync as renameSync3, writeFileSync as writeFileSync4 } from "node:fs";
+import { existsSync as existsSync5, mkdirSync as mkdirSync5, readFileSync as readFileSync9, renameSync as renameSync4, writeFileSync as writeFileSync5 } from "node:fs";
 import { dirname as dirname4, join as join9, resolve as resolve4 } from "node:path";
 
 // spex-console/src/lib/heyspex-home.ts
-import { homedir as homedir8 } from "node:os";
+import { homedir as homedir9 } from "node:os";
 function heyspexHome2(env = process.env) {
   const override = env?.HEYSPEX_HOME;
   if (typeof override === "string" && override.trim().length > 0) {
     return override.trim();
   }
-  return homedir8();
+  return homedir9();
 }
 
 // spex-console/src/lib/vault-registry/types.ts
@@ -1353,9 +1383,9 @@ function parseVaultRegistryFile(json) {
 }
 function readRegistryJson(opts) {
   const filePath = vaultRegistryFilePath(opts);
-  if (!existsSync4(filePath)) return { kind: "missing" };
+  if (!existsSync5(filePath)) return { kind: "missing" };
   try {
-    const raw = readFileSync8(filePath, "utf8");
+    const raw = readFileSync9(filePath, "utf8");
     const json = JSON.parse(raw);
     if (registryFileSchemaOf(json) === null) return { kind: "unreadable" };
     return { kind: "ok", raw, json };
@@ -1425,10 +1455,10 @@ function assertNotRealHomeRegistryUnderTest(filePath) {
 function writeVaultRegistry(registry, opts = {}) {
   const filePath = vaultRegistryFilePath(opts);
   assertNotRealHomeRegistryUnderTest(filePath);
-  mkdirSync4(dirname4(filePath), { recursive: true });
+  mkdirSync5(dirname4(filePath), { recursive: true });
   const tmpPath = `${filePath}.tmp`;
-  writeFileSync4(tmpPath, serializeVaultRegistry(registry), "utf8");
-  renameSync3(tmpPath, filePath);
+  writeFileSync5(tmpPath, serializeVaultRegistry(registry), "utf8");
+  renameSync4(tmpPath, filePath);
 }
 function isValidId(id) {
   if (!isNonEmptyString(id)) return false;
@@ -1603,11 +1633,11 @@ function readPairedBearer(opts = {}) {
 function readPairedToken(opts = {}) {
   return readPairedBearer(opts).token ?? void 0;
 }
-function scopeHeadersFor(scope, method, path5) {
+function scopeHeadersFor(scope, method, path7) {
   if (scope === "none") {
-    if (!isVaultLessEndpoint(method, path5)) {
+    if (!isVaultLessEndpoint(method, path7)) {
       throw new Error(
-        `controlRequest: scope "none" is only allowed for the vault-less endpoints (${VAULT_LESS_ENDPOINTS.join(", ")}); ${method.toUpperCase()} ${path5} is vault-scoped and must name { accountId, vaultId }.`
+        `controlRequest: scope "none" is only allowed for the vault-less endpoints (${VAULT_LESS_ENDPOINTS.join(", ")}); ${method.toUpperCase()} ${path7} is vault-scoped and must name { accountId, vaultId }.`
       );
     }
     return {};
@@ -1618,7 +1648,7 @@ function cloudRequestScope(scope) {
   const named = { accountId: scope.accountId, vaultId: scope.vaultId };
   return {
     ...named,
-    headersFor: (method, path5) => isVaultLessEndpoint(method, path5) ? {} : scopeHeadersFor(named, method, path5)
+    headersFor: (method, path7) => isVaultLessEndpoint(method, path7) ? {} : scopeHeadersFor(named, method, path7)
   };
 }
 function withCloudScope(deps, accountId, vaultId) {
@@ -1626,13 +1656,297 @@ function withCloudScope(deps, accountId, vaultId) {
   return { ...deps, http: { ...deps.http, scope: cloudRequestScope({ accountId, vaultId }) } };
 }
 
+// spex-console/src/lib/cli/generated-file-eol.ts
+import { spawnSync } from "node:child_process";
+import { existsSync as existsSync6, readFileSync as readFileSync10 } from "node:fs";
+import { dirname as dirname5, relative, resolve as resolve5 } from "node:path";
+function dominantEol(text) {
+  const crlf = (text.match(/\r\n/g) ?? []).length;
+  const lf = (text.match(/\n/g) ?? []).length - crlf;
+  if (crlf === 0 && lf === 0) return null;
+  return crlf > lf ? "\r\n" : "\n";
+}
+function applyEol(text, eol) {
+  const lf = text.replace(/\r\n/g, "\n");
+  return eol === "\n" ? lf : lf.replace(/\n/g, "\r\n");
+}
+function defaultRunGit(args, cwd) {
+  try {
+    const res = spawnSync("git", args, {
+      cwd,
+      encoding: "utf8",
+      windowsHide: true,
+      timeout: 1e4
+    });
+    if (res.status !== 0) return null;
+    return String(res.stdout ?? "").trim();
+  } catch {
+    return null;
+  }
+}
+function defaultReadFile3(path7) {
+  try {
+    return readFileSync10(path7, "utf8");
+  } catch {
+    return null;
+  }
+}
+function existingAncestor(path7) {
+  let dir = dirname5(resolve5(path7));
+  for (; ; ) {
+    if (existsSync6(dir)) return dir;
+    const parent = dirname5(dir);
+    if (parent === dir) return dir;
+    dir = parent;
+  }
+}
+function createGeneratedFileEol(opts) {
+  const readFile = opts.readFile ?? defaultReadFile3;
+  const runGit = opts.runGit ?? defaultRunGit;
+  const platform = opts.platform ?? process.platform;
+  const attrCache = /* @__PURE__ */ new Map();
+  let configEol;
+  const configDefault = () => {
+    if (configEol !== void 0) return configEol;
+    if (runGit(["rev-parse", "--is-inside-work-tree"], opts.repoRoot) !== "true") {
+      configEol = null;
+      return configEol;
+    }
+    const get = (key) => runGit(["config", "--get", key], opts.repoRoot);
+    const coreEol = (get("core.eol") ?? "").toLowerCase();
+    if (coreEol === "crlf") configEol = "\r\n";
+    else if (coreEol === "lf") configEol = "\n";
+    else if (platform === "win32" && (get("core.autocrlf") ?? "").toLowerCase() === "true")
+      configEol = "\r\n";
+    else configEol = null;
+    return configEol;
+  };
+  const attrEol = (path7) => {
+    const abs = resolve5(path7);
+    const cwd = existingAncestor(abs);
+    const rel = relative(cwd, abs).replace(/\\/g, "/") || ".";
+    const key = `${cwd}\0${rel}`;
+    let out = attrCache.get(key);
+    if (out === void 0) {
+      out = runGit(["check-attr", "eol", "--", rel], cwd) ?? "";
+      attrCache.set(key, out);
+    }
+    const m = out.match(/:\s*eol:\s*(\S+)\s*$/);
+    const value = (m?.[1] ?? "").toLowerCase();
+    if (value === "crlf") return "\r\n";
+    if (value === "lf") return "\n";
+    return null;
+  };
+  const eolFor = (path7, existing) => {
+    const current = existing === void 0 ? readFile(path7) : existing;
+    if (current !== null) {
+      const have = dominantEol(current);
+      if (have) return have;
+    }
+    return attrEol(path7) ?? configDefault() ?? "\n";
+  };
+  return {
+    eolFor,
+    convert: (path7, content, existing) => {
+      if (!content.includes("\n")) return content;
+      return applyEol(content, eolFor(path7, existing));
+    }
+  };
+}
+
 // spex-console/src/lib/cli/install.ts
-import { isAbsolute as isAbsolute3, resolve as resolveNodePath2 } from "node:path";
+import { isAbsolute as isAbsolute4, resolve as resolveNodePath2 } from "node:path";
+
+// spex-console/src/lib/vault-resolve/index.ts
+import { existsSync as existsSync7, readFileSync as readFileSync11, realpathSync as realpathSync4, statSync as statSync4 } from "node:fs";
+import { tmpdir as tmpdir2 } from "node:os";
+import path3 from "node:path";
+
+// spex-console/src/lib/cli/satellite.ts
+import { resolve as resolveNodePath } from "node:path";
+import process2 from "node:process";
+var SATELLITE_VAULT_ENV = "HEYSPEX_VAULT_ROOT";
+var SATELLITE_MANIFEST_RELS = [
+  [".mcp.json"],
+  [".cursor", "mcp.json"]
+];
+function normalizePathForCompare(p) {
+  return p.trim().replace(/[\\/]+/g, "/").replace(/\/+$/, "").toLowerCase();
+}
+function samePath(a, b) {
+  return normalizePathForCompare(a) === normalizePathForCompare(b);
+}
+function isAtOrUnder(child, parent) {
+  const c = normalizePathForCompare(child);
+  const p = normalizePathForCompare(parent);
+  return c === p || c.startsWith(`${p}/`);
+}
+function isAbsolutePathForCompare(p) {
+  const s = p.trim();
+  return /^[\\/]/.test(s) || /^[a-zA-Z]:[\\/]/.test(s);
+}
+function defaultResolveCliPath(p) {
+  const base = process2.env.HS_INVOKED_CWD?.trim() || process2.cwd();
+  return resolveNodePath(base, p);
+}
+function expandPinPlaceholders(value, repoRoot) {
+  return value.replace(/\$\{(?:CLAUDE_PROJECT_DIR|workspaceFolder)(?::-[^}]*)?\}/g, repoRoot);
+}
+function lexicalJoin(base, rel) {
+  const parts = `${base}/${rel}`.replace(/\\/g, "/").split("/");
+  const out = [];
+  for (const seg of parts) {
+    if (seg === "" && out.length > 0) continue;
+    if (seg === ".") continue;
+    if (seg === ".." && out.length > 1) {
+      out.pop();
+      continue;
+    }
+    out.push(seg);
+  }
+  return out.join("/");
+}
+function parseMarkerVaultPath(content) {
+  const m = content.match(/^vault_path:[ \t]*(.+?)[ \t]*$/m);
+  if (!m) return null;
+  const v = m[1].trim().replace(/\s+#.*$/, "").replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1").trim();
+  if (!v || v.includes("${") || /^[\\/]/.test(v) || /^[a-zA-Z]:[\\/]/.test(v)) return null;
+  return v;
+}
+function markerVaultIdOf(content) {
+  const m = content.match(/^vault_id:\s*(.+?)\s*$/m);
+  if (!m) return null;
+  const v = m[1].trim().replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1");
+  return v.length > 0 ? v : null;
+}
+function detectMarkerAttachment(repoRoot, deps) {
+  const markerPath = deps.joinPath(repoRoot, "heyspex.yaml");
+  if (!deps.fileExists(markerPath)) return null;
+  const raw = deps.readFile(markerPath);
+  const vaultPath = raw ? parseMarkerVaultPath(raw) : null;
+  if (!raw || !vaultPath) return null;
+  const vaultRootAbs = lexicalJoin(repoRoot, vaultPath);
+  const markerId = markerVaultIdOf(raw);
+  let cloned = deps.fileExists(deps.joinPath(vaultRootAbs, "specs"));
+  if (cloned && markerId) {
+    const theirs = deps.readFile(deps.joinPath(vaultRootAbs, "heyspex.yaml"));
+    const theirId = theirs ? markerVaultIdOf(theirs) : null;
+    if (theirId && theirId !== markerId) cloned = false;
+  }
+  const registry = loadVaultRegistry(deps.registryOpts);
+  const record = registry.vaults.find((v) => samePath(v.repo_root_abs, vaultRootAbs));
+  return {
+    vaultRootAbs,
+    vaultId: markerId ?? record?.id ?? null,
+    pins: [{ source: "heyspex.yaml", value: vaultRootAbs }],
+    conflicting: false,
+    viaMarker: true,
+    cloned,
+    vaultPath
+  };
+}
+function readPinnedVaultRoot(repoRoot, deps) {
+  const pins = [];
+  for (const rel of SATELLITE_MANIFEST_RELS) {
+    const path7 = deps.joinPath(repoRoot, ...rel);
+    if (!deps.fileExists(path7)) continue;
+    const raw = deps.readFile(path7);
+    if (!raw) continue;
+    let value;
+    try {
+      const parsed = JSON.parse(raw);
+      value = parsed?.mcpServers?.heyspex?.env?.[SATELLITE_VAULT_ENV];
+    } catch {
+      continue;
+    }
+    if (typeof value !== "string") continue;
+    const trimmed = value.trim();
+    if (!trimmed) continue;
+    const expanded = expandPinPlaceholders(trimmed, repoRoot);
+    if (expanded.includes("${")) continue;
+    if (/^[a-zA-Z]:(?![\\/])/.test(expanded)) continue;
+    const abs = isAbsolutePathForCompare(expanded) ? expanded.includes("..") ? lexicalJoin(expanded, ".") : expanded : lexicalJoin(repoRoot, expanded);
+    if (expanded !== trimmed && isAtOrUnder(abs, repoRoot)) continue;
+    pins.push({ source: rel.join("/"), value: abs });
+  }
+  return pins;
+}
+function isVaultRootOnDisk(dir, deps) {
+  return deps.fileExists(deps.joinPath(dir, "heyspex.yaml")) || deps.fileExists(deps.joinPath(dir, "specs"));
+}
+function resolveAttachTarget(idOrPath, deps) {
+  const raw = idOrPath.trim();
+  if (!raw) return { ok: false, message: "--attach-vault requires a vault id or path" };
+  const registry = loadVaultRegistry(deps.registryOpts);
+  const looksLikePath = /[\\/]/.test(raw) || /^[a-zA-Z]:$/.test(raw.slice(0, 2)) || raw === "." || raw === "..";
+  const asPath = looksLikePath && !isAbsolutePathForCompare(raw) ? (deps.resolvePath ?? defaultResolveCliPath)(raw) : raw;
+  const shownPath = asPath === raw ? raw : `${raw} (${asPath})`;
+  const record = registry.vaults.find((v) => v.id === raw) ?? (looksLikePath ? registry.vaults.find((v) => samePath(v.repo_root_abs, asPath)) : void 0);
+  if (!record) {
+    const known = registry.vaults.map((v) => v.id);
+    const knownList = known.length ? `known vault ids: ${known.join(", ")}` : "no vaults are registered on this machine";
+    return {
+      ok: false,
+      message: looksLikePath ? `--attach-vault: no registered vault at ${shownPath} \u2014 register it first with \`hs vault register --path <dir>\`, then attach by id (${knownList}).` : `--attach-vault: unknown vault id "${raw}" \u2014 run \`hs vault list\` to see registered vaults (${knownList}).`
+    };
+  }
+  if (!deps.fileExists(record.repo_root_abs)) {
+    return {
+      ok: false,
+      message: `--attach-vault: vault "${record.id}" is registered at ${record.repo_root_abs}, which does not exist on this machine \u2014 clone it there, or fix the row with \`hs vault move\`.`
+    };
+  }
+  if (!isVaultRootOnDisk(record.repo_root_abs, deps)) {
+    return {
+      ok: false,
+      message: `--attach-vault: ${record.repo_root_abs} (vault "${record.id}") has neither heyspex.yaml nor specs/ \u2014 it is not a vault root.`
+    };
+  }
+  return {
+    ok: true,
+    target: {
+      vaultId: record.id,
+      vaultRootAbs: record.repo_root_abs,
+      workspaceId: record.workspace_id,
+      displayName: record.display_name
+    }
+  };
+}
+
+// spex-console/src/lib/vault-resolve/index.ts
+function parseRepoBinding(content) {
+  const src = String(content ?? "");
+  if (/^(vault_id|vault_root):/m.test(src)) return null;
+  const kind = src.match(/^kind:\s*(.+?)\s*$/m)?.[1]?.replace(/^["']|["']$/g, "").trim();
+  if (kind && kind !== "repo-binding") return null;
+  const lines = src.split(/\r?\n/);
+  const start = lines.findIndex((l) => /^vault:(\s|$)/.test(l));
+  if (start === -1) return null;
+  const unq = (v) => v.trim().replace(/\s+#.*$/, "").replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1").trim();
+  const scalar = lines[start].slice("vault:".length).trim();
+  if (scalar && !scalar.startsWith("#")) {
+    const id = unq(scalar);
+    return id ? { id, name: null, remote: null } : null;
+  }
+  const out = {
+    id: null,
+    name: null,
+    remote: null
+  };
+  for (let i = start + 1; i < lines.length; i += 1) {
+    const l = lines[i];
+    if (!l.trim() || /^\s*#/.test(l)) continue;
+    if (!/^\s+/.test(l)) break;
+    const m = l.match(/^\s+([a-z_]+):\s*(.*)$/);
+    if (m && (m[1] === "id" || m[1] === "name" || m[1] === "remote")) out[m[1]] = unq(m[2]) || null;
+  }
+  return out.id ? { id: out.id, name: out.name, remote: out.remote } : null;
+}
 
 // scripts/install-cursor-hooks.mjs
 import fs2 from "node:fs";
-import path3 from "node:path";
-import { fileURLToPath as fileURLToPath3 } from "node:url";
+import path5 from "node:path";
+import { fileURLToPath as fileURLToPath4 } from "node:url";
 
 // scripts/cursor-hooks/manifest.mjs
 var SHIM = "scripts/cursor-hooks/_run.mjs";
@@ -1778,9 +2092,9 @@ function timeoutFor(entry) {
 // scripts/lib/customer-kit.mjs
 import { createHash } from "node:crypto";
 import fs from "node:fs";
-import path2 from "node:path";
+import path4 from "node:path";
 import os2 from "node:os";
-import { fileURLToPath as fileURLToPath2, pathToFileURL } from "node:url";
+import { fileURLToPath as fileURLToPath3, pathToFileURL } from "node:url";
 
 // scripts/lib/hook-dispositions.mjs
 var HOSTS = Object.freeze(["claude-code", "cursor", "copilot"]);
@@ -2050,7 +2364,7 @@ function toPosixPath(p) {
 function samePlatformPath(a, b) {
   if (!a || !b) return false;
   const norm = (p) => {
-    const s = toPosixPath(path2.resolve(p));
+    const s = toPosixPath(path4.resolve(p));
     return process.platform === "win32" ? s.toLowerCase() : s;
   };
   return norm(a) === norm(b);
@@ -2128,8 +2442,16 @@ var LAUNCHER_TEMPLATE = [
   "//   4. node_modules/heyspex up from $__ENV__, $CLAUDE_PROJECT_DIR, $CURSOR_PROJECT_DIR, cwd",
   "//   5. <npm root -g>/heyspex                    a global install, last resort",
   "// Nothing found -> one stderr line and exit 0 (fail-open, like the shim itself).",
+  "//",
+  "// The same resolution starts the package's other entrypoints, so no committed",
+  "// file names node_modules/heyspex directly and a repo with no node_modules of",
+  "// its own still works off a global install:",
+  "//   --mcp         the stdio MCP server          (.mcp.json, .cursor/mcp.json)",
+  "//   --statusline  the Claude Code status line   (statusLine.command)",
+  "//   --resolve     print the package root, exit 0; exit 1 when none (hs doctor)",
   "import { spawnSync } from 'node:child_process';",
-  "import { existsSync } from 'node:fs';",
+  "import { existsSync, readdirSync, readFileSync, realpathSync } from 'node:fs';",
+  "import { homedir } from 'node:os';",
   "import { dirname, resolve } from 'node:path';",
   "import { fileURLToPath, pathToFileURL } from 'node:url';",
   "",
@@ -2139,6 +2461,7 @@ var LAUNCHER_TEMPLATE = [
   "const text = (v) => (typeof v === 'string' && v.trim() ? v.trim() : null);",
   "const hasShim = (root) => Boolean(root) && existsSync(resolve(root, ...SHIM));",
   "",
+  "__YIELD__",
   "function packageUpFrom(start) {",
   "  let dir = resolve(start);",
   "  for (;;) {",
@@ -2173,31 +2496,109 @@ var LAUNCHER_TEMPLATE = [
   "  if (hasShim(global)) root = global;",
   "}",
   "",
+  "const ENTRYPOINTS = {",
+  "  '--mcp': 'vendor/heyspex-mcp/cli.mjs',",
+  "  '--statusline': 'scripts/claude-statusline/statusline-command.mjs',",
+  "};",
+  "const mode = process.argv[2];",
+  "const entry = Object.hasOwn(ENTRYPOINTS, mode) ? ENTRYPOINTS[mode] : null;",
+  "",
   "if (!root) {",
+  "  const what = entry || mode === '--resolve' ? mode : 'hook ' + (mode ?? '?');",
   "  process.stderr.write(",
-  "    '[heyspex] hook ' + (process.argv[2] ?? '?') + ' skipped: no heyspex package found ' +",
-  `      '(run "npm install heyspex" in this repo, or set HEYSPEX_PLATFORM_ROOT). Looked for __SHIM__ under ' +`,
-  "      'HEYSPEX_PLATFORM_ROOT, HEYSPEX_MCP_ENTRY, node_modules/heyspex up from ' + starts.join(', ') + ', and npm root -g.\\n',",
+  "    '[heyspex] ' + what + ' skipped: no heyspex package found ' +",
+  `      '(run "npm install heyspex" or "npm link heyspex" in this repo, install it globally, or set HEYSPEX_PLATFORM_ROOT). ' +`,
+  "      'Looked for __SHIM__ under HEYSPEX_PLATFORM_ROOT, HEYSPEX_MCP_ENTRY, node_modules/heyspex up from ' + starts.join(', ') + ', and npm root -g.\\n',",
   "  );",
+  "  // Hooks and the status line fail open; the MCP server and --resolve fail",
+  "  // loudly, so the client and hs doctor both see it.",
+  "  process.exit(mode === '--mcp' || mode === '--resolve' ? 1 : 0);",
+  "}",
+  "if (mode === '--resolve') {",
+  "  process.stdout.write(root + '\\n');",
   "  process.exit(0);",
   "}",
   "",
   "// argv is already [node, <this file>, <hook>, ...args] -- the shape the shim",
-  '// reads; the shim path replaces this file so a shim guarded by "am I main?"',
-  "// (the Cursor one) runs exactly as if Cursor had invoked it directly.",
-  "const shim = resolve(root, ...SHIM);",
-  "process.argv[1] = shim;",
+  '// reads; the target replaces this file so a script guarded by "am I main?"',
+  "// runs exactly as if it had been invoked directly. Real path, so that guard",
+  "// still matches when node_modules/heyspex is an npm link or a junction (node",
+  "// realpaths import.meta.url but leaves argv[1] alone).",
+  "let target = resolve(root, ...(entry ? entry.split('/') : SHIM));",
   "try {",
-  "  await import(pathToFileURL(shim).href);",
+  "  target = realpathSync(target);",
+  "} catch {",
+  "  // keep the resolved path",
+  "}",
+  "if (entry) process.argv.splice(2, 1);",
+  "process.argv[1] = target;",
+  "try {",
+  "  await import(pathToFileURL(target).href);",
   "} catch (err) {",
-  "  process.stderr.write('[heyspex] hook ' + (process.argv[2] ?? '?') + ' skipped: ' + (err && err.message ? err.message : err) + '\\n');",
+  "  process.stderr.write('[heyspex] ' + (entry ? mode : 'hook ' + (process.argv[2] ?? '?')) + ' skipped: ' + (err && err.message ? err.message : err) + '\\n');",
+  "  // Hooks and the status line fail open; the MCP server fails loudly.",
+  "  if (mode === '--mcp') process.exit(1);",
   "  process.exit(0);",
   "}",
   ""
 ].join("\n");
+var LAUNCHER_YIELD_MARKER = "// yields-to-plugin: v1";
+var LAUNCHER_YIELD_BLOCK = [
+  LAUNCHER_YIELD_MARKER + " -- one source of hooks: when the heyspex plugin is enabled on this machine",
+  "// its own launcher (plugins/heyspex/bin/run-hook.mjs, which never calls this file) already runs every",
+  "// hook, so this committed row exits 0 silently before resolving anything and each hook fires ONCE.",
+  "//   HEYSPEX_REPO_HOOKS=1                      never yield (the repo rows are the chosen source);",
+  `//   enabledPlugins["heyspex@..."] === false    in ~/.claude/settings.json or this repo's .claude/`,
+  "//                                             settings[.local].json: plugin off here, the row runs;",
+  "//   plugin evidence (what `hs doctor` hook-double-fire reads): a heyspex@... key in",
+  "//     ~/.claude/plugins/installed_plugins.json, enabledPlugins naming heyspex with a non-false",
+  "//     value, or a heyspex directory under ~/.copilot/installed-plugins | ~/.copilot/plugins.",
+  "function readJson(file) {",
+  "  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return undefined; }",
+  "}",
+  "function listDir(dir) {",
+  "  try { return readdirSync(dir); } catch { return []; }",
+  "}",
+  "function pluginTakesThisHook() {",
+  "  const flag = text(env.HEYSPEX_REPO_HOOKS);",
+  "  if (flag && flag !== '0' && flag.toLowerCase() !== 'false') return false;",
+  "  const home = homedir();",
+  "  const repo = resolve(here, '..', '..');",
+  "  const isHeyspex = (k) => /^heyspex(@|$)/i.test(k);",
+  "  let enabled = false;",
+  "  for (const f of [resolve(home, '.claude', 'settings.json'), resolve(repo, '.claude', 'settings.json'), resolve(repo, '.claude', 'settings.local.json')]) {",
+  "    const settings = readJson(f);",
+  "    const ep = settings && typeof settings === 'object' ? settings.enabledPlugins : null;",
+  "    if (!ep || typeof ep !== 'object') continue;",
+  "    for (const [k, v] of Object.entries(ep)) {",
+  "      if (!isHeyspex(k)) continue;",
+  "      if (v === false) return false;",
+  "      enabled = true;",
+  "    }",
+  "  }",
+  "  if (enabled) return true;",
+  "  const installed = readJson(resolve(home, '.claude', 'plugins', 'installed_plugins.json'));",
+  "  if (installed && typeof installed === 'object' && Object.keys(installed.plugins && typeof installed.plugins === 'object' ? installed.plugins : installed).some(isHeyspex)) return true;",
+  "  for (const sub of ['installed-plugins', 'plugins']) {",
+  "    const dir = resolve(home, '.copilot', sub);",
+  "    const names = listDir(dir);",
+  "    if (names.some((n) => /heyspex/i.test(n))) return true;",
+  "    if (names.some((n) => listDir(resolve(dir, n)).some((m) => /heyspex/i.test(m)))) return true;",
+  "  }",
+  "  return false;",
+  "}",
+  "// Only a HOOK EVENT yields: --mcp / --statusline / --resolve and an agent-run",
+  "// `<script> --directive <key>` fetch are not hook events the plugin could run in",
+  "// our place, so they always go on to the package below.",
+  "const yieldMode = process.argv[2];",
+  "const notAHookEvent = ['--mcp', '--statusline', '--resolve'].includes(yieldMode) || process.argv.includes('--directive');",
+  "if (!notAHookEvent && pluginTakesThisHook()) process.exit(0);",
+  "",
+  ""
+].join("\n");
 function renderCustomerLauncher(surface = "claude") {
   const l = CUSTOMER_LAUNCHERS[surface];
-  return LAUNCHER_TEMPLATE.replace(
+  return LAUNCHER_TEMPLATE.replace("__YIELD__\n", surface === "claude" ? LAUNCHER_YIELD_BLOCK : "").replace(
     /__(REGISTRY|ENV|LAUNCHER|SHIM)__/g,
     (_m, token) => token === "REGISTRY" ? l.registry : token === "ENV" ? l.projectDirEnv : token === "LAUNCHER" ? l.rel.join("/") : l.shim
   );
@@ -2423,25 +2824,33 @@ var MARKER_RE = /\n<!-- heyspex-kit: managed by hs install \(sha256:([0-9a-f]{16
 function shortHash(text) {
   return createHash("sha256").update(text, "utf8").digest("hex").slice(0, 16);
 }
+function normalizeEol(text) {
+  return text === null || text === void 0 ? text : String(text).replace(/\r\n/g, "\n");
+}
 function renderKitCommand(content, platformRoot) {
-  const body = `${rewritePlatformPaths(content, platformRoot).replace(/\s+$/, "")}
+  const body = `${rewritePlatformPaths(normalizeEol(content), platformRoot).replace(/\s+$/, "")}
 `;
   return `${body}
 <!-- heyspex-kit: managed by hs install (sha256:${shortHash(body)}). Edit freely: once edited, hs install leaves this file alone. -->
 `;
 }
 function kitFileState(content) {
-  const m = String(content).match(MARKER_RE);
+  const text = normalizeEol(String(content));
+  const m = text.match(MARKER_RE);
   if (!m) return "unmanaged";
-  const body = String(content).slice(0, m.index).replace(/\n$/, "");
-  return shortHash(`${body}
-`) === m[1] ? "managed" : "customized";
+  const body = `${text.slice(0, m.index).replace(/\n$/, "")}
+`;
+  if (shortHash(body) === m[1]) return "managed";
+  if (shortHash(`${body.slice(0, -1).replace(/\n/g, "\r\n")}
+`) === m[1]) return "managed";
+  return "customized";
 }
 function planKitFileWrite({ existing, rendered, raw, force }) {
   if (existing === null || existing === void 0) return { write: true, reason: "missing" };
-  if (existing === rendered) return { write: false, reason: "unchanged" };
-  if (kitFileState(existing) === "managed") return { write: true, reason: "update" };
-  if (existing === raw) return { write: true, reason: "legacy-copy" };
+  const have = normalizeEol(existing);
+  if (have === normalizeEol(rendered)) return { write: false, reason: "unchanged" };
+  if (kitFileState(have) === "managed") return { write: true, reason: "update" };
+  if (have === normalizeEol(raw)) return { write: true, reason: "legacy-copy" };
   return force ? { write: true, reason: "forced" } : { write: false, reason: "customized" };
 }
 function listKitCommandFiles(platformRoot, deps, opts = {}) {
@@ -2466,7 +2875,7 @@ function listKitCommandFiles(platformRoot, deps, opts = {}) {
   return out;
 }
 var fsDeps = {
-  joinPath: (...s) => path2.join(...s),
+  joinPath: (...s) => path4.join(...s),
   readFile: (p) => {
     try {
       return fs.readFileSync(p, "utf8");
@@ -2485,22 +2894,22 @@ var fsDeps = {
 function invokedDirectly(importMetaUrl, selfBasename, argv1 = process.argv[1]) {
   try {
     if (!argv1) return false;
-    const self = fileURLToPath2(importMetaUrl);
-    if (path2.basename(self) !== selfBasename) return false;
-    return pathToFileURL(path2.resolve(argv1)).href === pathToFileURL(self).href;
+    const self = fileURLToPath3(importMetaUrl);
+    if (path4.basename(self) !== selfBasename) return false;
+    return pathToFileURL(path4.resolve(argv1)).href === pathToFileURL(self).href;
   } catch {
     return false;
   }
 }
-var SELF = fileURLToPath2(import.meta.url);
+var SELF = fileURLToPath3(import.meta.url);
 if (invokedDirectly(import.meta.url, "customer-kit.mjs")) {
-  const platformRoot = path2.resolve(path2.dirname(SELF), "..", "..");
-  const target = path2.join(platformRoot, "plugins", "heyspex", "hooks", "hooks.json");
+  const platformRoot = path4.resolve(path4.dirname(SELF), "..", "..");
+  const target = path4.join(platformRoot, "plugins", "heyspex", "hooks", "hooks.json");
   const want = renderPluginHooksText();
   const same = (fsDeps.readFile(target) ?? "").replace(/\r\n/g, "\n") === want;
   if (process.argv.includes("--write-plugin-hooks")) {
     if (!same) fs.writeFileSync(target, want, "utf8");
-    console.log(`customer-kit: ${same ? "unchanged" : "wrote"} ${path2.relative(platformRoot, target)}`);
+    console.log(`customer-kit: ${same ? "unchanged" : "wrote"} ${path4.relative(platformRoot, target)}`);
   } else if (process.argv.includes("--check-plugin-hooks")) {
     if (!same) {
       console.error("customer-kit: plugins/heyspex/hooks/hooks.json is stale \u2014 run `node scripts/lib/customer-kit.mjs --write-plugin-hooks`");
@@ -2508,15 +2917,15 @@ if (invokedDirectly(import.meta.url, "customer-kit.mjs")) {
     }
     console.log("customer-kit: plugins/heyspex/hooks/hooks.json up to date");
   } else if (process.argv.includes("--write-github-hooks") || process.argv.includes("--check-github-hooks")) {
-    const ghTarget = path2.join(platformRoot, ".github", "hooks", "heyspex.json");
+    const ghTarget = path4.join(platformRoot, ".github", "hooks", "heyspex.json");
     const ghWant = renderGithubHooksText();
     const ghSame = (fsDeps.readFile(ghTarget) ?? "").replace(/\r\n/g, "\n") === ghWant;
     if (process.argv.includes("--write-github-hooks")) {
       if (!ghSame) {
-        fs.mkdirSync(path2.dirname(ghTarget), { recursive: true });
+        fs.mkdirSync(path4.dirname(ghTarget), { recursive: true });
         fs.writeFileSync(ghTarget, ghWant, "utf8");
       }
-      console.log(`customer-kit: ${ghSame ? "unchanged" : "wrote"} ${path2.relative(platformRoot, ghTarget).replace(/\\/g, "/")}`);
+      console.log(`customer-kit: ${ghSame ? "unchanged" : "wrote"} ${path4.relative(platformRoot, ghTarget).replace(/\\/g, "/")}`);
     } else if (!ghSame) {
       console.error("customer-kit: .github/hooks/heyspex.json is stale - run `node scripts/lib/customer-kit.mjs --write-github-hooks`");
       process.exit(1);
@@ -2529,9 +2938,9 @@ if (invokedDirectly(import.meta.url, "customer-kit.mjs")) {
 }
 
 // scripts/install-cursor-hooks.mjs
-var PLATFORM_ROOT = path3.resolve(path3.dirname(fileURLToPath3(import.meta.url)), "..");
-var REPO_ROOT = process.env.HS_SETUP_TARGET?.trim() ? path3.resolve(process.env.HS_SETUP_TARGET.trim()) : PLATFORM_ROOT;
-var SETTINGS_PATH = path3.join(REPO_ROOT, ".cursor", "hooks.json");
+var PLATFORM_ROOT = path5.resolve(path5.dirname(fileURLToPath4(import.meta.url)), "..");
+var REPO_ROOT = process.env.HS_SETUP_TARGET?.trim() ? path5.resolve(process.env.HS_SETUP_TARGET.trim()) : PLATFORM_ROOT;
+var SETTINGS_PATH = path5.join(REPO_ROOT, ".cursor", "hooks.json");
 function cursorKitFor(targetRoot, platformRoot = PLATFORM_ROOT) {
   const customer = !samePlatformPath(targetRoot, platformRoot);
   return {
@@ -2543,7 +2952,7 @@ function cursorKitFor(targetRoot, platformRoot = PLATFORM_ROOT) {
 }
 var KIT = cursorKitFor(REPO_ROOT);
 var ACTIVE_HOOKS = KIT.hooks;
-var LAUNCHER_PATH = path3.join(REPO_ROOT, ...CUSTOMER_LAUNCHERS.cursor.rel);
+var LAUNCHER_PATH = path5.join(REPO_ROOT, ...CUSTOMER_LAUNCHERS.cursor.rel);
 var LEGACY_MARKER = "scripts/claude-hooks/";
 function readSettings() {
   try {
@@ -2562,7 +2971,7 @@ function readSettings() {
   return { version: 1, hooks: {} };
 }
 function writeSettings(settings) {
-  fs2.mkdirSync(path3.dirname(SETTINGS_PATH), { recursive: true });
+  fs2.mkdirSync(path5.dirname(SETTINGS_PATH), { recursive: true });
   fs2.writeFileSync(SETTINGS_PATH, `${JSON.stringify(settings, null, 2)}
 `, "utf8");
 }
@@ -2597,7 +3006,7 @@ function sameEntry(raw, entry, render = KIT.commandFor) {
   const want = desiredEntry(entry, render);
   return commandOf(raw) === want.command && raw.timeout === want.timeout && (raw.matcher ?? void 0) === (want.matcher ?? void 0);
 }
-var PLUGIN_HOOKS_PATH = path3.join(REPO_ROOT, "plugins", "heyspex", "hooks", "cursor-hooks.json");
+var PLUGIN_HOOKS_PATH = path5.join(REPO_ROOT, "plugins", "heyspex", "hooks", "cursor-hooks.json");
 function pluginHooksDocument() {
   const hooks = {};
   for (const entry of HOOKS) {
@@ -2627,7 +3036,7 @@ function syncPluginHooks() {
     have = null;
   }
   if (have === want) return false;
-  fs2.mkdirSync(path3.dirname(PLUGIN_HOOKS_PATH), { recursive: true });
+  fs2.mkdirSync(path5.dirname(PLUGIN_HOOKS_PATH), { recursive: true });
   fs2.writeFileSync(PLUGIN_HOOKS_PATH, want, "utf8");
   return true;
 }
@@ -2700,7 +3109,7 @@ function install({ json = false } = {}) {
   if (KIT.customer) {
     const plan = launcherPlan();
     if (plan.write) {
-      fs2.mkdirSync(path3.dirname(LAUNCHER_PATH), { recursive: true });
+      fs2.mkdirSync(path5.dirname(LAUNCHER_PATH), { recursive: true });
       fs2.writeFileSync(LAUNCHER_PATH, plan.text, "utf8");
       launcherWritten = true;
     }
@@ -2727,10 +3136,10 @@ function install({ json = false } = {}) {
     return;
   }
   if (pluginChanged) {
-    console.log(`install-cursor-hooks: regenerated ${path3.relative(REPO_ROOT, PLUGIN_HOOKS_PATH)}`);
+    console.log(`install-cursor-hooks: regenerated ${path5.relative(REPO_ROOT, PLUGIN_HOOKS_PATH)}`);
   }
   if (launcherWritten) {
-    console.log(`install-cursor-hooks: wrote ${path3.relative(REPO_ROOT, LAUNCHER_PATH)} (resolves node_modules/heyspex)`);
+    console.log(`install-cursor-hooks: wrote ${path5.relative(REPO_ROOT, LAUNCHER_PATH)} (resolves node_modules/heyspex)`);
   }
   if (!settingsChanged) {
     console.log(`install-cursor-hooks: already installed (${ACTIVE_HOOKS.length} hooks, no changes).`);
@@ -2741,7 +3150,7 @@ function install({ json = false } = {}) {
   if (repaired.length) parts.push(`repaired ${repaired.length}`);
   if (removed.length) parts.push(`removed ${removed.length}`);
   console.log(
-    `install-cursor-hooks: ${parts.join("; ")} \u2192 ${path3.relative(REPO_ROOT, SETTINGS_PATH)} (${ACTIVE_HOOKS.length} hooks registered)`
+    `install-cursor-hooks: ${parts.join("; ")} \u2192 ${path5.relative(REPO_ROOT, SETTINGS_PATH)} (${ACTIVE_HOOKS.length} hooks registered)`
   );
   for (const line of removed) console.log(`  - ${line}`);
   console.log(
@@ -2843,11 +3252,11 @@ if (invokedDirectly(import.meta.url, "install-cursor-hooks.mjs")) {
 init_credentials();
 
 // spex-console/src/lib/cli/connect-checks.ts
-import { dirname as dirname5 } from "node:path";
+import { dirname as dirname6 } from "node:path";
 import { pathToFileURL as pathToFileURL2 } from "node:url";
 
 // spex-console/src/lib/dev-mode.ts
-import { mkdirSync as mkdirSync5, readFileSync as readFileSync9, writeFileSync as writeFileSync5 } from "node:fs";
+import { mkdirSync as mkdirSync6, readFileSync as readFileSync12, writeFileSync as writeFileSync6 } from "node:fs";
 import { join as join10 } from "node:path";
 init_credentials();
 
@@ -3094,12 +3503,15 @@ var HELP = [
   "(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 the template_version",
-  "pin; with --git, one initial `git init` + commit. Rerunnable: a <dir> that already",
-  "holds heyspex.yaml and an empty/placeholder-only specs/ is accepted, existing",
-  "files are never overwritten (an existing CLAUDE.md gets a CLAUDE.md.template",
-  "beside it), and the result lists each manifest row as created or kept. Refuses a",
-  "non-empty <dir> without heyspex.yaml, or a specs/ holding managed specs.",
-  "See init.customer-vault.ts.",
+  "pin; with --git, one initial `git init` + commit. On an EXISTING vault (<dir>",
+  "holds heyspex.yaml with a vault_id) it is a REFRESH \u2014 the repair `hs doctor`'s",
+  "vault-template row names: only missing shipped files are added, template_version",
+  "is written/updated in heyspex.yaml (every other byte and the vault_id kept),",
+  "nothing existing is ever overwritten (an existing CLAUDE.md gets a",
+  "CLAUDE.md.template beside it), the result lists each manifest row as created or",
+  "kept, and a second run writes nothing. <dir> may be any path (a satellite repo",
+  "names its vault, e.g. `hs init --customer-vault ../my-specs`). Refuses only a",
+  "non-empty <dir> that has no heyspex.yaml. See init.customer-vault.ts.",
   "",
   "Flags:",
   "  --console-url <url>  console_url value (default: the mode-aware console --",
@@ -3121,157 +3533,6 @@ var HELP = [
   "Exit codes: 0 ok \xB7 1 usage \xB7 11 bad-arg \xB7 13 write-failed"
 ].join("\n");
 
-// spex-console/src/lib/cli/satellite.ts
-import { resolve as resolveNodePath } from "node:path";
-import process2 from "node:process";
-var SATELLITE_VAULT_ENV = "HEYSPEX_VAULT_ROOT";
-var SATELLITE_MANIFEST_RELS = [
-  [".mcp.json"],
-  [".cursor", "mcp.json"]
-];
-function normalizePathForCompare(p) {
-  return p.trim().replace(/[\\/]+/g, "/").replace(/\/+$/, "").toLowerCase();
-}
-function samePath(a, b) {
-  return normalizePathForCompare(a) === normalizePathForCompare(b);
-}
-function isAtOrUnder(child, parent) {
-  const c = normalizePathForCompare(child);
-  const p = normalizePathForCompare(parent);
-  return c === p || c.startsWith(`${p}/`);
-}
-function isAbsolutePathForCompare(p) {
-  const s = p.trim();
-  return /^[\\/]/.test(s) || /^[a-zA-Z]:[\\/]/.test(s);
-}
-function defaultResolveCliPath(p) {
-  const base = process2.env.HS_INVOKED_CWD?.trim() || process2.cwd();
-  return resolveNodePath(base, p);
-}
-function expandPinPlaceholders(value, repoRoot) {
-  return value.replace(/\$\{(?:CLAUDE_PROJECT_DIR|workspaceFolder)(?::-[^}]*)?\}/g, repoRoot);
-}
-function lexicalJoin(base, rel) {
-  const parts = `${base}/${rel}`.replace(/\\/g, "/").split("/");
-  const out = [];
-  for (const seg of parts) {
-    if (seg === "" && out.length > 0) continue;
-    if (seg === ".") continue;
-    if (seg === ".." && out.length > 1) {
-      out.pop();
-      continue;
-    }
-    out.push(seg);
-  }
-  return out.join("/");
-}
-function parseMarkerVaultPath(content) {
-  const m = content.match(/^vault_path:[ \t]*(.+?)[ \t]*$/m);
-  if (!m) return null;
-  const v = m[1].trim().replace(/\s+#.*$/, "").replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1").trim();
-  if (!v || v.includes("${") || /^[\\/]/.test(v) || /^[a-zA-Z]:[\\/]/.test(v)) return null;
-  return v;
-}
-function markerVaultIdOf(content) {
-  const m = content.match(/^vault_id:\s*(.+?)\s*$/m);
-  if (!m) return null;
-  const v = m[1].trim().replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1");
-  return v.length > 0 ? v : null;
-}
-function detectMarkerAttachment(repoRoot, deps) {
-  const markerPath = deps.joinPath(repoRoot, "heyspex.yaml");
-  if (!deps.fileExists(markerPath)) return null;
-  const raw = deps.readFile(markerPath);
-  const vaultPath = raw ? parseMarkerVaultPath(raw) : null;
-  if (!raw || !vaultPath) return null;
-  const vaultRootAbs = lexicalJoin(repoRoot, vaultPath);
-  const markerId = markerVaultIdOf(raw);
-  let cloned = deps.fileExists(deps.joinPath(vaultRootAbs, "specs"));
-  if (cloned && markerId) {
-    const theirs = deps.readFile(deps.joinPath(vaultRootAbs, "heyspex.yaml"));
-    const theirId = theirs ? markerVaultIdOf(theirs) : null;
-    if (theirId && theirId !== markerId) cloned = false;
-  }
-  const registry = loadVaultRegistry(deps.registryOpts);
-  const record = registry.vaults.find((v) => samePath(v.repo_root_abs, vaultRootAbs));
-  return {
-    vaultRootAbs,
-    vaultId: markerId ?? record?.id ?? null,
-    pins: [{ source: "heyspex.yaml", value: vaultRootAbs }],
-    conflicting: false,
-    viaMarker: true,
-    cloned,
-    vaultPath
-  };
-}
-function readPinnedVaultRoot(repoRoot, deps) {
-  const pins = [];
-  for (const rel of SATELLITE_MANIFEST_RELS) {
-    const path5 = deps.joinPath(repoRoot, ...rel);
-    if (!deps.fileExists(path5)) continue;
-    const raw = deps.readFile(path5);
-    if (!raw) continue;
-    let value;
-    try {
-      const parsed = JSON.parse(raw);
-      value = parsed?.mcpServers?.heyspex?.env?.[SATELLITE_VAULT_ENV];
-    } catch {
-      continue;
-    }
-    if (typeof value !== "string") continue;
-    const trimmed = value.trim();
-    if (!trimmed) continue;
-    const expanded = expandPinPlaceholders(trimmed, repoRoot);
-    if (expanded.includes("${")) continue;
-    if (/^[a-zA-Z]:(?![\\/])/.test(expanded)) continue;
-    const abs = isAbsolutePathForCompare(expanded) ? expanded.includes("..") ? lexicalJoin(expanded, ".") : expanded : lexicalJoin(repoRoot, expanded);
-    if (expanded !== trimmed && isAtOrUnder(abs, repoRoot)) continue;
-    pins.push({ source: rel.join("/"), value: abs });
-  }
-  return pins;
-}
-function isVaultRootOnDisk(dir, deps) {
-  return deps.fileExists(deps.joinPath(dir, "heyspex.yaml")) || deps.fileExists(deps.joinPath(dir, "specs"));
-}
-function resolveAttachTarget(idOrPath, deps) {
-  const raw = idOrPath.trim();
-  if (!raw) return { ok: false, message: "--attach-vault requires a vault id or path" };
-  const registry = loadVaultRegistry(deps.registryOpts);
-  const looksLikePath = /[\\/]/.test(raw) || /^[a-zA-Z]:$/.test(raw.slice(0, 2)) || raw === "." || raw === "..";
-  const asPath = looksLikePath && !isAbsolutePathForCompare(raw) ? (deps.resolvePath ?? defaultResolveCliPath)(raw) : raw;
-  const shownPath = asPath === raw ? raw : `${raw} (${asPath})`;
-  const record = registry.vaults.find((v) => v.id === raw) ?? (looksLikePath ? registry.vaults.find((v) => samePath(v.repo_root_abs, asPath)) : void 0);
-  if (!record) {
-    const known = registry.vaults.map((v) => v.id);
-    const knownList = known.length ? `known vault ids: ${known.join(", ")}` : "no vaults are registered on this machine";
-    return {
-      ok: false,
-      message: looksLikePath ? `--attach-vault: no registered vault at ${shownPath} \u2014 register it first with \`hs vault register --path <dir>\`, then attach by id (${knownList}).` : `--attach-vault: unknown vault id "${raw}" \u2014 run \`hs vault list\` to see registered vaults (${knownList}).`
-    };
-  }
-  if (!deps.fileExists(record.repo_root_abs)) {
-    return {
-      ok: false,
-      message: `--attach-vault: vault "${record.id}" is registered at ${record.repo_root_abs}, which does not exist on this machine \u2014 clone it there, or fix the row with \`hs vault move\`.`
-    };
-  }
-  if (!isVaultRootOnDisk(record.repo_root_abs, deps)) {
-    return {
-      ok: false,
-      message: `--attach-vault: ${record.repo_root_abs} (vault "${record.id}") has neither heyspex.yaml nor specs/ \u2014 it is not a vault root.`
-    };
-  }
-  return {
-    ok: true,
-    target: {
-      vaultId: record.id,
-      vaultRootAbs: record.repo_root_abs,
-      workspaceId: record.workspace_id,
-      displayName: record.display_name
-    }
-  };
-}
-
 // spex-console/src/lib/cli/connect-checks.ts
 function listCanonicalHarnessCommandFiles(platformRoot, deps, opts = {}) {
   return listKitCommandFiles(
@@ -3405,7 +3666,7 @@ function writeProjectContract(ctx, options2 = {}) {
 }
 
 // spex-console/src/lib/cli/init.customer-vault.ts
-import { basename as basename2 } from "node:path";
+import { basename as basename3 } from "node:path";
 
 // spex-console/src/lib/cli/template-manifest.sources.mjs
 var UNIVERSAL_TEMPLATE_ROWS = [
@@ -3890,41 +4151,42 @@ var SCAFFOLD_FOLDERS = [
   "checks",
   "events"
 ];
-var PLACEHOLDER_FILES = /* @__PURE__ */ new Set([".gitkeep"]);
-function isDir(deps, path5, name) {
-  if (deps.isDirectory) return deps.isDirectory(path5);
-  try {
-    const kids = deps.readdir(path5);
-    return kids.length > 0 || !name.includes(".");
-  } catch {
-    return false;
-  }
+function defaultVaultName(targetDir) {
+  return basename3(targetDir) || targetDir;
 }
-function findManagedSpecs(deps, targetDir, manifestDests) {
-  const out = [];
-  const walk = (abs, rel) => {
-    for (const name of deps.readdir(abs)) {
-      const childAbs = deps.joinPath(abs, name);
-      const childRel = `${rel}/${name}`;
-      if (isDir(deps, childAbs, name)) walk(childAbs, childRel);
-      else if (!PLACEHOLDER_FILES.has(name) && name.endsWith(".md") && !manifestDests.has(childRel))
-        out.push(childRel);
-    }
-  };
-  const specsRoot = deps.joinPath(targetDir, "specs");
-  if (deps.exists(specsRoot)) walk(specsRoot, "specs");
-  return out;
+function readTemplateVersionPin(yamlText) {
+  const m = yamlText.match(/^template_version:[ \t]*(.*?)[ \t]*$/m);
+  if (!m) return null;
+  const raw = m[1].trim();
+  const unquoted = raw.replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1");
+  return unquoted.length > 0 ? unquoted : null;
 }
-function defaultVaultName(targetDir) {
-  return basename2(targetDir) || targetDir;
+function stampTemplateVersion(content, version) {
+  if (readTemplateVersionPin(content) === version) return content;
+  const eol = content.includes("\r\n") ? "\r\n" : "\n";
+  const line = `template_version: ${version}`;
+  if (/^template_version:[^\r\n]*$/m.test(content)) {
+    return content.replace(/^template_version:[^\r\n]*$/m, line);
+  }
+  const body = content.replace(/(?:\r?\n)+$/, "");
+  return body.length === 0 ? `${line}${eol}` : `${body}${eol}${line}${eol}`;
+}
+function parentDirOf(deps, targetDir, dest) {
+  const segments = dest.split("/");
+  if (segments.length < 2) return null;
+  return deps.joinPath(targetDir, ...segments.slice(0, -1));
 }
 function runCustomerVaultInit(args, deps, options2 = {}) {
   const { targetDir } = args;
   const written = [];
   const filter = options2.manifestFilter ?? (() => true);
   const rows = TEMPLATE_MANIFEST.filter(filter);
+  const heyspexYamlPath = deps.joinPath(targetDir, "heyspex.yaml");
+  const markerPresent = deps.exists(targetDir) && deps.exists(heyspexYamlPath);
+  const existingYaml = markerPresent ? deps.readFile?.(heyspexYamlPath) ?? null : null;
+  const existingVaultId = existingYaml ? parseVaultId(existingYaml) : null;
+  const mode = markerPresent && existingVaultId ? "refresh" : "scaffold";
   if (deps.exists(targetDir)) {
-    const markerPresent = deps.exists(deps.joinPath(targetDir, "heyspex.yaml"));
     if (!markerPresent && deps.readdir(targetDir).length > 0) {
       return {
         code: EXIT.INVALID_ARG,
@@ -3934,43 +4196,43 @@ function runCustomerVaultInit(args, deps, options2 = {}) {
         written: []
       };
     }
-    if (markerPresent) {
-      const manifestDests = new Set(TEMPLATE_MANIFEST.map((r) => r.dest));
-      const managed = findManagedSpecs(deps, targetDir, manifestDests);
-      if (managed.length > 0) {
-        return {
-          code: EXIT.INVALID_ARG,
-          message: `${targetDir}/specs already holds managed spec(s) (${managed.slice(0, 3).join(", ")}${managed.length > 3 ? ", ..." : ""}) \u2014 customer-vault init refuses to write over an existing vault.`,
-          payload: { ok: false, error: "specs_not_empty", path: targetDir, specs: managed },
-          isError: true,
-          written: []
-        };
-      }
-    }
   } else {
     deps.mkdirRecursive(targetDir);
   }
-  const specsRoot = deps.joinPath(targetDir, "specs");
-  deps.mkdirRecursive(specsRoot);
-  for (const folder of SCAFFOLD_FOLDERS) {
-    deps.mkdirRecursive(deps.joinPath(specsRoot, folder));
+  if (mode === "scaffold") {
+    const specsRoot = deps.joinPath(targetDir, "specs");
+    deps.mkdirRecursive(specsRoot);
+    for (const folder of SCAFFOLD_FOLDERS) {
+      deps.mkdirRecursive(deps.joinPath(specsRoot, folder));
+    }
   }
-  const heyspexYamlPath = deps.joinPath(targetDir, "heyspex.yaml");
   let vaultId;
-  if (deps.exists(heyspexYamlPath)) {
-    const existingYaml = deps.readFile?.(heyspexYamlPath) ?? null;
-    vaultId = (existingYaml ? parseVaultId(existingYaml) : null) ?? "";
+  let pin;
+  if (markerPresent) {
+    vaultId = existingVaultId ?? "";
+    const stamped = existingYaml === null ? null : stampTemplateVersion(existingYaml, TEMPLATE_VERSION);
+    if (stamped !== null && stamped !== existingYaml) {
+      deps.writeFile(heyspexYamlPath, stamped);
+      written.push(heyspexYamlPath);
+      pin = "written";
+    } else {
+      pin = "kept";
+    }
   } else {
     vaultId = mintVaultId();
     deps.writeFile(
       heyspexYamlPath,
-      renderHeyspexYaml({
-        consoleUrl: options2.consoleUrl ?? DEFAULT_CONSOLE_URL2,
-        vaultRoot: "specs/",
-        vaultId
-      })
+      stampTemplateVersion(
+        renderHeyspexYaml({
+          consoleUrl: options2.consoleUrl ?? DEFAULT_CONSOLE_URL2,
+          vaultRoot: "specs/",
+          vaultId
+        }),
+        TEMPLATE_VERSION
+      )
     );
     written.push(heyspexYamlPath);
+    pin = "written";
   }
   const readConfigSeed = deps.readConfigSeed;
   const configSeed = seedConfigYaml(
@@ -3986,6 +4248,10 @@ function runCustomerVaultInit(args, deps, options2 = {}) {
       rowResults.push({ dest: row.dest, action: "kept" });
       continue;
     }
+    if (mode === "refresh") {
+      const parent = parentDirOf(deps, targetDir, row.dest);
+      if (parent && !deps.exists(parent)) deps.mkdirRecursive(parent);
+    }
     if (row.classification === "universal-template") {
       const srcAbs = deps.joinPath(deps.platformRoot, ...row.source.split("/"));
       deps.copyFile(srcAbs, destAbs);
@@ -4005,24 +4271,41 @@ function runCustomerVaultInit(args, deps, options2 = {}) {
       targetDir,
       vaultName: options2.vaultName ?? defaultVaultName(targetDir),
       templateVersion: TEMPLATE_VERSION,
+      mode,
       manifestRows: rows,
       rows: rowResults,
       deps,
-      recordWrite: (path5) => {
-        written.push(path5);
+      recordWrite: (path7) => {
+        written.push(path7);
       }
     };
     for (const hook of options2.afterScaffold) hook(ctx);
   }
   const createdCount = rowResults.filter((r) => r.action === "created").length;
   const keptCount = rowResults.length - createdCount;
+  const added = rowResults.filter((r) => r.action === "created").map((r) => r.dest);
+  let message2;
+  if (mode === "refresh") {
+    const parts = [];
+    if (added.length > 0)
+      parts.push(`added ${added.length} missing template file(s): ${added.join(", ")}`);
+    if (pin === "written")
+      parts.push(`pinned template_version: ${TEMPLATE_VERSION} in heyspex.yaml`);
+    const hookWrites = written.length - added.length - (pin === "written" ? 1 : 0);
+    if (hookWrites > 0) parts.push(`${hookWrites} other file(s) written`);
+    message2 = parts.length > 0 ? `Refreshed customer vault at ${targetDir}: ${parts.join("; ")} (${keptCount} existing file(s) kept untouched).` : `Customer vault at ${targetDir} is already current (template v${TEMPLATE_VERSION}, ${keptCount} file(s) kept) \u2014 nothing written.`;
+  } else {
+    message2 = `Initialized customer vault at ${targetDir} (${written.length} files written, ${createdCount} manifest rows created, ${keptCount} kept, template v${TEMPLATE_VERSION}).`;
+  }
   return {
     code: EXIT.OK,
-    message: `Initialized customer vault at ${targetDir} (${written.length} files written, ${createdCount} manifest rows created, ${keptCount} kept, template v${TEMPLATE_VERSION}).`,
+    message: message2,
     payload: {
       ok: true,
+      mode,
       targetDir,
       templateVersion: TEMPLATE_VERSION,
+      templatePin: pin,
       vaultId,
       written,
       rows: rowResults,
@@ -4035,7 +4318,7 @@ function runCustomerVaultInit(args, deps, options2 = {}) {
 }
 
 // spex-console/src/lib/cli/init-git-finalize.ts
-import { spawnSync } from "node:child_process";
+import { spawnSync as spawnSync2 } from "node:child_process";
 function readTemplateVersion(yamlText) {
   const m = yamlText.match(/^template_version:\s*(.+?)\s*$/m);
   if (!m) return null;
@@ -4064,14 +4347,14 @@ function templatePinHook() {
 }
 
 // spex-console/src/lib/cli/principle-selection.ts
-import { basename as basename3 } from "node:path";
+import { basename as basename4 } from "node:path";
 var PRINCIPLES_INDEX_DEST = "specs/principles-index.md";
 function principleKey(row) {
-  const base = basename3(row.dest, ".md");
+  const base = basename4(row.dest, ".md");
   return base.startsWith("principle-") ? base.slice("principle-".length) : base;
 }
 function principleWikilink(row) {
-  return basename3(row.dest, ".md");
+  return basename4(row.dest, ".md");
 }
 function parsePrinciplesFlag(value, rows) {
   const principleRows = rows.filter((row) => row.group === "principle");
@@ -4137,13 +4420,13 @@ function applyCustomerTemplate(args) {
       templateVersion: ctx.templateVersion
     });
     for (const file of contractFiles) {
-      const path5 = ctx.deps.joinPath(ctx.targetDir, file);
-      if (force && ctx.deps.exists(path5)) {
-        if (ctx.deps.readFile?.(path5) === content) {
+      const path7 = ctx.deps.joinPath(ctx.targetDir, file);
+      if (force && ctx.deps.exists(path7)) {
+        if (ctx.deps.readFile?.(path7) === content) {
           contracts.push({ file, action: "unchanged" });
         } else {
-          ctx.deps.writeFile(path5, content);
-          ctx.recordWrite(path5);
+          ctx.deps.writeFile(path7, content);
+          ctx.recordWrite(path7);
           contracts.push({ file, action: "overwritten" });
         }
         continue;
@@ -4466,7 +4749,7 @@ function formatReceipt(receipt) {
 }
 
 // spex-console/src/lib/cli/vault-workspace-shared.ts
-import { readFileSync as readFileSync10 } from "node:fs";
+import { readFileSync as readFileSync13 } from "node:fs";
 var VAULT_OWNED_BY_OTHER_ACCOUNT = "vault_owned_by_other_account";
 var WORKSPACE_OWNED_BY_OTHER_ACCOUNT = "workspace_owned_by_other_account";
 function vaultOwnedByOtherAccountMessage(id) {
@@ -4480,10 +4763,10 @@ function classifyHttpFailureReason(res) {
   if (res.status === 401) return "unauthorized";
   return "server-error";
 }
-async function cloudHttpRequest(http, method, path5, body) {
-  const scopeHeaders = http.scope ? http.scope.headersFor(method, path5) : {};
+async function cloudHttpRequest(http, method, path7, body) {
+  const scopeHeaders = http.scope ? http.scope.headersFor(method, path7) : {};
   try {
-    const res = await http.fetchImpl(`${http.consoleUrl}${path5}`, {
+    const res = await http.fetchImpl(`${http.consoleUrl}${path7}`, {
       method,
       headers: {
         "content-type": "application/json",
@@ -4542,8 +4825,8 @@ async function classifyWorkspaceConflictHttp(id, conflictJson, http) {
 // spex-console/src/lib/cli/receipt-readback.ts
 var RECEIPT_CLOUD_READS = 3;
 var RECEIPT_REREAD_DELAY_MS = 1e3;
-var realSleep = (ms) => new Promise((resolve6) => {
-  setTimeout(resolve6, ms);
+var realSleep = (ms) => new Promise((resolve7) => {
+  setTimeout(resolve7, ms);
 });
 function message(err) {
   return err instanceof Error ? err.message : String(err);
@@ -4581,11 +4864,11 @@ function readLocalReceiptSide(subject, registryOpts = {}) {
     return unreadSide(`registry.json could not be read: ${message(err)}`);
   }
 }
-async function readList(http, path5, key) {
-  const res = await cloudHttpRequest(http, "GET", path5);
+async function readList(http, path7, key) {
+  const res = await cloudHttpRequest(http, "GET", path7);
   const rows = res.json?.[key];
   if (!res.ok || !Array.isArray(rows)) {
-    return { reason: `GET ${path5.split("?")[0]} answered HTTP ${res.status}` };
+    return { reason: `GET ${path7.split("?")[0]} answered HTTP ${res.status}` };
   }
   return { rows: rows.filter((r) => Boolean(r) && typeof r === "object") };
 }
@@ -4690,7 +4973,7 @@ async function readReceiptSides(subject, deps) {
 var import_gray_matter = __toESM(require_gray_matter(), 1);
 import { createHash as createHash2 } from "node:crypto";
 import { promises as fs3 } from "node:fs";
-import path4 from "node:path";
+import path6 from "node:path";
 
 // spex-console/src/lib/vault-id.ts
 var FILE_KEY_RE = /^(?=[0-9]*[A-Z])[A-Z0-9]{4,}$/;
@@ -5272,8 +5555,8 @@ async function indexTemplateToCloud(args) {
         const res = await cloudHttpRequest(args.http, "GET", REINDEX_PATH);
         return { status: res.status, json: res.json };
       },
-      post: async (path5, body) => {
-        const res = await cloudHttpRequest(args.http, "POST", path5, body);
+      post: async (path7, body) => {
+        const res = await cloudHttpRequest(args.http, "POST", path7, body);
         return { status: res.status, json: res.json };
       }
     });
@@ -5319,9 +5602,17 @@ async function indexTemplateToCloud(args) {
 // spex-console/src/lib/cli/install.ts
 var MCP_REL = ["vendor", "heyspex-mcp", "cli.mjs"];
 var PORTABLE_MCP_CLI = Object.freeze({
+  claude: `\${CLAUDE_PROJECT_DIR:-.}/${CUSTOMER_LAUNCHERS.claude.rel.join("/")}`,
+  cursor: `\${workspaceFolder}/${CUSTOMER_LAUNCHERS.cursor.rel.join("/")}`
+});
+var LEGACY_PORTABLE_MCP_CLI = Object.freeze({
   claude: `\${CLAUDE_PROJECT_DIR:-.}/${PORTABLE_PACKAGE_DIR}/${MCP_REL.join("/")}`,
   cursor: `\${workspaceFolder}/${PORTABLE_PACKAGE_DIR}/${MCP_REL.join("/")}`
 });
+var LAUNCHER_MCP_FLAG = "--mcp";
+function mcpServerArgs(cliPath) {
+  return /[\\/]heyspex[\\/]run-hook\.mjs$/.test(cliPath) ? [cliPath, LAUNCHER_MCP_FLAG] : [cliPath];
+}
 function mcpCliArgFor(surface, platformRoot, targetDir, joinPath) {
   return samePlatformPath(targetDir, platformRoot) ? mcpCliPath(platformRoot, joinPath) : PORTABLE_MCP_CLI[surface];
 }
@@ -5482,7 +5773,7 @@ function mcpCliPath(platformRoot, joinPath) {
 function resolveCallerPath(p, env, fallbackCwd) {
   const trimmed = p?.trim() ?? "";
   if (!trimmed) return "";
-  if (isAbsolute3(trimmed)) return trimmed;
+  if (isAbsolute4(trimmed)) return trimmed;
   const base = env.HS_INVOKED_CWD?.trim() || fallbackCwd;
   return resolveNodePath2(base, trimmed);
 }
@@ -5493,30 +5784,37 @@ function resolveInstallTargetDir(argsTargetDir, env, fallbackCwd, opts) {
   }
   return explicit || env.HS_VAULT_ROOT?.trim() || env.HS_INVOKED_CWD?.trim() || fallbackCwd;
 }
-function renderCursorMcpJson(cliAbsPath, attachedVaultRoot) {
+function renderCursorMcpJson(cliAbsPath, attachedVaultRoot, opts = {}) {
+  const pin = vaultRootPin(attachedVaultRoot, "${workspaceFolder}", opts);
   return {
     mcpServers: {
       heyspex: {
         type: "stdio",
         command: "node",
-        args: [cliAbsPath],
-        env: {
-          HEYSPEX_VAULT_ROOT: attachedVaultRoot ?? "${workspaceFolder}"
-        }
+        args: mcpServerArgs(cliAbsPath),
+        ...pin ? { env: { HEYSPEX_VAULT_ROOT: pin } } : {}
       }
     }
   };
 }
-function renderClaudeMcpJson(cliAbsPath, attachedVaultRoot) {
+function vaultRootPin(attachedVaultRoot, placeholder, opts = {}) {
+  if (attachedVaultRoot) return attachedVaultRoot;
+  return opts.targetIsVault === false ? null : placeholder;
+}
+function isVaultTarget(targetDir, deps) {
+  if (deps.fileExists(deps.joinPath(targetDir, "specs"))) return true;
+  const marker = deps.readFile(deps.joinPath(targetDir, "heyspex.yaml"));
+  return !(marker && parseRepoBinding(marker));
+}
+function renderClaudeMcpJson(cliAbsPath, attachedVaultRoot, opts = {}) {
+  const pin = vaultRootPin(attachedVaultRoot, "${CLAUDE_PROJECT_DIR:-.}", opts);
   return {
     mcpServers: {
       heyspex: {
         type: "stdio",
         command: "node",
-        args: [cliAbsPath],
-        env: {
-          HEYSPEX_VAULT_ROOT: attachedVaultRoot ?? "${CLAUDE_PROJECT_DIR:-.}"
-        }
+        args: mcpServerArgs(cliAbsPath),
+        ...pin ? { env: { HEYSPEX_VAULT_ROOT: pin } } : {}
       }
     }
   };
@@ -5587,20 +5885,34 @@ var SATELLITE_PIN_TARGETS = [
 function satellitePinnableManifests(args) {
   return SATELLITE_PIN_TARGETS.filter((t) => t.enabled(args)).map((t) => t.rel);
 }
-function planSatelliteManifests(targetDir, attachedRoot, args, deps, satelliteDeps) {
+function manifestHasHeyspexEntry(raw) {
+  if (!raw) return false;
+  try {
+    const parsed = JSON.parse(raw);
+    return Boolean(parsed?.mcpServers && Object.hasOwn(parsed.mcpServers, "heyspex"));
+  } catch {
+    return false;
+  }
+}
+function planSatelliteManifests(targetDir, attachedRoot, args, deps, satelliteDeps, markerBound = false) {
   const onDisk = new Map(readPinnedVaultRoot(targetDir, satelliteDeps).map((p) => [p.source, p]));
   const pinnable = [];
   const stale = [];
   for (const target of SATELLITE_PIN_TARGETS) {
-    const path5 = deps.joinPath(targetDir, ...target.segments);
+    const path7 = deps.joinPath(targetDir, ...target.segments);
     const currentPin = onDisk.get(target.rel)?.value ?? null;
-    const exists = deps.fileExists(path5);
-    const matches = currentPin !== null && samePath(currentPin, attachedRoot);
+    const exists = deps.fileExists(path7);
+    const hasHeyspexEntry = exists && manifestHasHeyspexEntry(deps.readFile(path7));
+    const matches = currentPin !== null ? samePath(currentPin, attachedRoot) : (
+      // Pin-free + a heyspex entry is the portable shape a marker-bound repo commits.
+      markerBound && hasHeyspexEntry
+    );
     const plan = {
       rel: target.rel,
-      path: path5,
+      path: path7,
       exists,
       currentPin,
+      hasHeyspexEntry,
       matches,
       willWrite: !exists || Boolean(args.force)
     };
@@ -5623,13 +5935,15 @@ function buildClaudeMcpAddRemoteCommandPowerShell(targetDir, url = DEFAULT_REMOT
     `claude mcp add --transport http --scope project heyspex '${escapedUrl}' --header 'Authorization: Bearer \${${REMOTE_MCP_TOKEN_ENV}}'`
   ].join("\n");
 }
-function buildClaudeMcpAddCommandPowerShell(targetDir, cliAbsPath, attachedVaultRoot) {
-  const escapedCli = cliAbsPath.replace(/'/g, "''");
+function buildClaudeMcpAddCommandPowerShell(targetDir, cliPath, attachedVaultRoot, opts = {}) {
+  const escapedCli = cliPath.replace(/'/g, "''");
   const escapedTarget = targetDir.replace(/'/g, "''");
-  const vaultRootArg = attachedVaultRoot ? `HEYSPEX_VAULT_ROOT="${attachedVaultRoot}"` : 'HEYSPEX_VAULT_ROOT="$PWD"';
+  const serverArgs = mcpServerArgs(cliPath).map((a, i) => i === 0 ? `'${escapedCli}'` : a).join(" ");
+  const pin = attachedVaultRoot === null ? null : vaultRootPin(attachedVaultRoot, "$PWD", opts);
+  const envArg = pin ? ` --env HEYSPEX_VAULT_ROOT="${pin}"` : "";
   return [
     `Set-Location -LiteralPath '${escapedTarget}'`,
-    `claude mcp add --transport stdio --scope project --env ${vaultRootArg} heyspex -- node '${escapedCli}'`
+    `claude mcp add --transport stdio --scope project${envArg} heyspex -- node ${serverArgs}`
   ].join("\n");
 }
 var PLUGIN_MARKETPLACE_NAME = "heyspex-marketplace";
@@ -5675,21 +5989,17 @@ function buildCopilotPluginInstallCommand(targetDir, platformRoot, spec = PLUGIN
     `copilot plugin install ${spec}`
   ].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() {
+function renderStatusLineEntry(customer = false) {
   return {
     type: "command",
-    command: 'node "$CLAUDE_PROJECT_DIR/scripts/claude-statusline/statusline-command.mjs"',
+    command: customer ? `node "$CLAUDE_PROJECT_DIR/${CUSTOMER_LAUNCHERS.claude.rel.join("/")}" --statusline` : 'node "$CLAUDE_PROJECT_DIR/scripts/claude-statusline/statusline-command.mjs"',
     padding: 2,
     refreshInterval: 5
   };
 }
+function isHeyspexStatusLineCommand(command) {
+  return typeof command === "string" && (command.includes("statusline-command.") || /heyspex\/run-hook\.mjs"?\s+--statusline/.test(command));
+}
 var MCP_ENTRY_ENV = "HEYSPEX_MCP_ENTRY";
 function isAbsoluteFsPath(value) {
   return typeof value === "string" && /^(?:[A-Za-z]:)?[\\/]/.test(value.trim());
@@ -5931,11 +6241,12 @@ function writeCustomerAgentKit(opts, deps) {
   }
   return { steps, settingsText };
 }
-function buildCommandCodeMcpAddCommand(cliAbsPath) {
+function buildCommandCodeMcpAddCommand(cliAbsPath, opts = {}) {
   const escapedCli = cliAbsPath.replace(/'/g, "''");
+  const pin = vaultRootPin(void 0, "$PWD", opts);
   return [
     `cmdc mcp add --transport stdio heyspex -- node '${escapedCli}'`,
-    `cmdc mcp env heyspex HEYSPEX_VAULT_ROOT "$PWD"`
+    ...pin ? [`cmdc mcp env heyspex HEYSPEX_VAULT_ROOT "${pin}"`] : []
   ].join("\n");
 }
 function shouldWrite(exists, force) {
@@ -5948,7 +6259,6 @@ var WRITE_TARGET_KIND = {
   claudeMcp: "claude_mcp",
   claudeMd: "claude_md",
   agentsMd: "agents_md",
-  statuslineVendor: "statusline_vendor",
   gitignore: "gitignore",
   claudeMdTemplate: "claude_md_template",
   agentsMdTemplate: "agents_md_template"
@@ -6009,12 +6319,6 @@ var INSTALL_WRITE_TARGETS = [
     path: (targetDir, joinPath) => joinPath(targetDir, "AGENTS.md.template"),
     appliesTo: (args, opts) => Boolean(args.registerVault) && !opts.attached && opts.installContract
   },
-  {
-    kind: WRITE_TARGET_KIND.statuslineVendor,
-    rel: "scripts/claude-statusline",
-    path: (targetDir, joinPath) => joinPath(targetDir, "scripts", "claude-statusline"),
-    appliesTo: (args) => (args.statusline ?? true) && args.claude
-  },
   {
     kind: WRITE_TARGET_KIND.gitignore,
     rel: ".gitignore",
@@ -6039,7 +6343,7 @@ 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: basename4 } = ctx;
+  const { targetDir, readFile, joinPath, registryOpts, now, basename: basename5 } = ctx;
   let vaultId;
   let schemaVersion = HEYSPEX_YAML_SCHEMA_VERSION;
   const yamlContent = readFile(joinPath(targetDir, "heyspex.yaml"));
@@ -6051,7 +6355,7 @@ function registerInstalledVault(args, ctx) {
     if (versionMatch) schemaVersion = Number(versionMatch[1]);
   }
   if (!vaultId) vaultId = slugFromPath(targetDir);
-  const displayName = basename4(targetDir);
+  const displayName = basename5(targetDir);
   const before = loadVaultRegistry(registryOpts);
   const existingVault = before.vaults.find(
     (v) => v.id === vaultId || v.repo_root_abs === targetDir
@@ -6129,13 +6433,13 @@ function settingsInvalidResult(settingsPath, message2) {
 function guardWritesAgainstLiteralBearer(writeFile, bearerToken) {
   const token = typeof bearerToken === "string" ? bearerToken.trim() : "";
   if (!token) return writeFile;
-  return (path5, content) => {
+  return (path7, content) => {
     if (content.includes(token)) {
       throw new Error(
-        `hs install: refusing to write ${path5} -- its content contains the literal bearer token (only the \${${REMOTE_MCP_TOKEN_ENV}} env reference may be written).`
+        `hs install: refusing to write ${path7} -- its content contains the literal bearer token (only the \${${REMOTE_MCP_TOKEN_ENV}} env reference may be written).`
       );
     }
-    writeFile(path5, content);
+    writeFile(path7, content);
   };
 }
 function runInstall(args, inputDeps) {
@@ -6221,16 +6525,20 @@ function runInstall(args, inputDeps) {
         isError: true
       };
     }
+    const markerBound2 = portableVaultPath !== null;
     const planned = planSatelliteManifests(
       targetDir,
       attached.vaultRootAbs,
       args,
       deps,
-      satelliteDeps
+      satelliteDeps,
+      markerBound2
     );
     satellitePins = planned.pinnable;
     satelliteStalePins = planned.stale;
-    const blocked = satellitePins.filter((p) => p.exists && !p.matches && !args.force);
+    const blocked = satellitePins.filter(
+      (p) => p.exists && !p.matches && !args.force && (!markerBound2 || p.currentPin !== null)
+    );
     if (blocked.length > 0) {
       const detail = blocked.map(
         (p) => `  ${p.rel} \u2014 ${p.currentPin ? `currently pins ${p.currentPin}` : "carries no vault pin"}`
@@ -6368,15 +6676,17 @@ ${detail}
     return !args.dryRun;
   };
   const pinsToWrite = satellitePins.filter((p) => p.willWrite);
-  const pinsUnchanged = satellitePins.filter((p) => !p.willWrite);
+  const pinsUnchanged = satellitePins.filter((p) => !p.willWrite && p.matches);
   const satellitePinWritten = pinsToWrite.length > 0;
   const relList = (plans) => plans.map((p) => p.rel).join(", ");
+  const markerBound = portableVaultPath !== null;
   if (attached) {
+    const binding = markerBound ? `bound to vault "${attached.vaultId}" by the committed heyspex.yaml (vault_path ${portableVaultPath})` : `attached to vault "${attached.vaultId}" (workspace "${attached.workspaceId}")`;
     steps.push({
       kind: "satellite_attach",
       path: attached.vaultRootAbs,
       action: satellitePinWritten ? args.dryRun ? "would_create" : "created" : "skipped",
-      detail: satellitePinWritten ? `attached to vault "${attached.vaultId}" (workspace "${attached.workspaceId}") -- ${SATELLITE_VAULT_ENV} pin ${args.dryRun ? "would be written to" : "written to"} ` + relList(pinsToWrite) + (pinsUnchanged.length ? `; ${relList(pinsUnchanged)} already pinned here` : "") : `already attached to vault "${attached.vaultId}" (workspace "${attached.workspaceId}") -- ${relList(pinsUnchanged)} already pin this root, nothing to write`
+      detail: satellitePinWritten ? `${binding} -- ${markerBound ? "portable manifest" : `${SATELLITE_VAULT_ENV} pin`} ${args.dryRun ? "would be written to" : "written to"} ` + relList(pinsToWrite) + (pinsUnchanged.length ? `; ${relList(pinsUnchanged)} already ${markerBound ? "current" : "pinned here"}` : "") : markerBound ? `already ${binding} -- ${relList(pinsUnchanged)} portable and current, nothing to write` : `already ${binding} -- ${relList(pinsUnchanged)} already pin this root, nothing to write`
     });
     for (const plan of satelliteStalePins) {
       steps.push({
@@ -6483,7 +6793,9 @@ ${detail}
   const claudePin = portableVaultPath ? "${CLAUDE_PROJECT_DIR:-.}/" + portableVaultPath : attachedRoot;
   const cursorPin = portableVaultPath ? "${workspaceFolder}/" + portableVaultPath : attachedRoot;
   const satelliteUnchanged = (rel) => pinsUnchanged.find((p) => p.rel === rel) ?? null;
-  const cursorJson = `${JSON.stringify(renderCursorMcpJson(cursorCliArg, cursorPin), null, 2)}
+  const unchangedDetail = (plan) => plan.currentPin === null ? `portable manifest, bound by heyspex.yaml (vault "${attached?.vaultId}") -- unchanged` : `already pins vault "${attached?.vaultId}" (${attachedRoot}) -- unchanged`;
+  const pinOpts = { targetIsVault: isVaultTarget(targetDir, deps) };
+  const cursorJson = `${JSON.stringify(renderCursorMcpJson(cursorCliArg, cursorPin, pinOpts), null, 2)}
 `;
   if (args.cursor) {
     const cursorUnchanged = satelliteUnchanged(".cursor/mcp.json");
@@ -6492,7 +6804,7 @@ ${detail}
         kind: WRITE_TARGET_KIND.cursorMcp,
         path: cursorPath,
         action: "skipped",
-        detail: `already pins vault "${attached?.vaultId}" (${attachedRoot}) -- unchanged`
+        detail: unchangedDetail(cursorUnchanged)
       });
     } else if (planWrite(WRITE_TARGET_KIND.cursorMcp, cursorPath, deps.fileExists(cursorPath))) {
       deps.mkdir(deps.joinPath(targetDir, ".cursor"));
@@ -6504,9 +6816,9 @@ ${detail}
   }
   const remoteUrl = args.remote ? resolveRemoteMcpUrl(args.remoteUrl) : null;
   const claudeJson = remoteUrl ? `${JSON.stringify(renderRemoteClaudeMcpJson(remoteUrl), null, 2)}
-` : `${JSON.stringify(renderClaudeMcpJson(claudeCliArg, claudePin), null, 2)}
+` : `${JSON.stringify(renderClaudeMcpJson(claudeCliArg, claudePin, pinOpts), null, 2)}
 `;
-  const claudePs = remoteUrl ? buildClaudeMcpAddRemoteCommandPowerShell(targetDir, remoteUrl) : buildClaudeMcpAddCommandPowerShell(targetDir, cliPath, attachedRoot);
+  let claudeManifestRegisters = false;
   if (args.claude) {
     const claudeUnchanged = satelliteUnchanged(".mcp.json");
     if (attached && remoteUrl) {
@@ -6521,7 +6833,7 @@ ${detail}
           existingJson = null;
         }
       }
-      const pinEntry = renderClaudeMcpJson(claudeCliArg, claudePin).mcpServers.heyspex;
+      const pinEntry = renderClaudeMcpJson(claudeCliArg, claudePin, pinOpts).mcpServers.heyspex;
       const cloudEntry = renderRemoteClaudeMcpJson(remoteUrl).mcpServers.heyspex;
       const merged = mergeAttachedRemoteMcpJson(
         existingJson,
@@ -6559,12 +6871,42 @@ ${detail}
         kind: WRITE_TARGET_KIND.claudeMcp,
         path: claudePath,
         action: "skipped",
-        detail: `already pins vault "${attached?.vaultId}" (${attachedRoot}) -- unchanged`
+        detail: unchangedDetail(claudeUnchanged)
       });
+      claudeManifestRegisters = true;
     } else if (planWrite(WRITE_TARGET_KIND.claudeMcp, claudePath, deps.fileExists(claudePath))) {
       deps.writeFile(claudePath, claudeJson);
+      claudeManifestRegisters = true;
     }
-    if (args.claudeApply) {
+    if (!claudeManifestRegisters) {
+      claudeManifestRegisters = manifestHasHeyspexEntry(deps.readFile(claudePath));
+    }
+  }
+  const claudePs = remoteUrl ? buildClaudeMcpAddRemoteCommandPowerShell(targetDir, remoteUrl) : !customerTarget ? buildClaudeMcpAddCommandPowerShell(targetDir, cliPath, attachedRoot, pinOpts) : claudeManifestRegisters ? void 0 : (
+    // Marker-bound: the committed heyspex.yaml binds the vault, so no
+    // HEYSPEX_VAULT_ROOT pin is registered (`null`), matching the manifest.
+    buildClaudeMcpAddCommandPowerShell(
+      targetDir,
+      claudeCliArg,
+      markerBound ? null : attachedRoot,
+      pinOpts
+    )
+  );
+  const claudeMcpRegisteredByManifest = args.claude && !remoteUrl && claudePs === void 0;
+  if (args.claude) {
+    if (claudeMcpRegisteredByManifest) {
+      if (args.claudeApply) {
+        steps.push({
+          kind: "claude_mcp_apply",
+          path: "claude mcp add",
+          action: "skipped",
+          detail: ".mcp.json already registers the heyspex MCP server for Claude Code"
+        });
+      }
+      nextSteps.push(
+        "Claude Code: .mcp.json already registers the heyspex MCP server -- no `claude mcp add` needed; restart Claude Code (or `/mcp` reconnect) in this repo to load it."
+      );
+    } else if (args.claudeApply) {
       steps.push({
         kind: "claude_mcp_apply",
         path: "claude mcp add",
@@ -6699,7 +7041,7 @@ ${detail}
   if ((args.statusline ?? true) && args.claude) {
     const statuslineShipsInPlatform = deps.fileExists(
       deps.joinPath(platformRoot, "scripts", "claude-statusline", "statusline-command.mjs")
-    );
+    ) && (!customerTarget || deps.fileExists(deps.joinPath(platformRoot, "scripts", "claude-hooks", "_run.mjs")));
     if (!statuslineShipsInPlatform) {
       steps.push({
         kind: "claude_statusline",
@@ -6708,41 +7050,8 @@ ${detail}
         detail: "not shipped in this package"
       });
     } else {
-      if (targetDir !== platformRoot) {
-        if (!deps.copyFile) {
-          steps.push({
-            kind: WRITE_TARGET_KIND.statuslineVendor,
-            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: WRITE_TARGET_KIND.statuslineVendor,
-            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 entry = renderStatusLineEntry(customerTarget);
       const raw = deps.readFile(settingsPath);
       let settings = raw === null ? {} : null;
       if (raw !== null) {
@@ -6753,7 +7062,7 @@ ${detail}
         }
       }
       const existing = settings?.statusLine;
-      const ours = typeof existing?.command === "string" && existing.command.includes("statusline-command.");
+      const ours = isHeyspexStatusLineCommand(existing?.command);
       if (settings === null) {
         steps.push({
           kind: "claude_statusline",
@@ -6780,7 +7089,7 @@ ${detail}
           kind: "claude_statusline",
           path: settingsPath,
           action: args.dryRun ? "would_create" : "created",
-          detail: existing ? "repaired to canonical entry" : "branded statusline (vendored renderer)"
+          detail: existing ? "repaired to canonical entry" : customerTarget ? "branded statusline (via .claude/heyspex/run-hook.mjs)" : "branded statusline"
         });
         if (!args.dryRun) {
           settings.statusLine = entry;
@@ -6839,7 +7148,10 @@ ${detail}
       "The plugin's hooks and the kit hooks hs install wrote into .claude/settings.json are the same set -- enable one or the other, or every hook runs twice."
     );
   }
-  const commandCodePs = buildCommandCodeMcpAddCommand(cliPath);
+  const commandCodePs = buildCommandCodeMcpAddCommand(
+    customerTarget ? deps.joinPath(targetDir, PORTABLE_PACKAGE_DIR, ...MCP_REL) : cliPath,
+    pinOpts
+  );
   if (args.commandCode) {
     steps.push({
       kind: "commandcode_mcp",
@@ -6927,6 +7239,7 @@ ${detail}
     steps,
     conflicts,
     claude_powershell: args.claude ? claudePs : void 0,
+    ...claudeMcpRegisteredByManifest ? { claude_mcp_registered_by_manifest: true } : {},
     remote_mcp_url: remoteUrl ?? void 0,
     claude_plugin_powershell: args.plugin && pluginAvailable ? pluginPs : void 0,
     claude_plugin_spec: args.plugin && pluginAvailable ? pluginSpec.spec : void 0,
@@ -6952,6 +7265,7 @@ ${detail}
         repo_root_abs: attached.vaultRootAbs,
         workspace_id: attached.workspaceId,
         display_name: attached.displayName,
+        ...markerBound ? { via_marker: true } : {},
         pinned_manifests: satellitePins.map((p) => p.rel),
         pin_written: satellitePinWritten
       }
@@ -6962,7 +7276,9 @@ ${detail}
     "",
     `Target:   ${targetDir}`,
     `Platform: ${platformRoot}`,
-    `MCP:      ${cliPath}`,
+    // A customer repo's manifests name the portable node_modules form, so
+    // the receipt names that too -- never a path into the platform checkout.
+    `MCP:      ${customerTarget ? claudeCliArg : cliPath}`,
     ...attached ? [`Vault:    ${attached.vaultRootAbs} (attached, id: ${attached.vaultId})`] : [],
     ""
   ];
@@ -7322,8 +7638,8 @@ var INSTALL_HELP = [
 ].join("\n");
 
 // spex-console/src/lib/cli/install-identity.ts
-import { spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync5 } from "node:fs";
+import { spawnSync as spawnSync3 } from "node:child_process";
+import { existsSync as existsSync8 } from "node:fs";
 import { join as join11 } from "node:path";
 import { createInterface } from "node:readline/promises";
 init_credentials();
@@ -7331,7 +7647,7 @@ init_credentials();
 // vendor/heyspex-mcp/whoami.mjs
 init_heyspex_home();
 init_credentials();
-import { homedir as homedir9 } from "node:os";
+import { homedir as homedir10 } from "node:os";
 var SESSION_PATH = "/api/mcp/session";
 async function probeCredentialIdentity({ consoleUrl, token, fetchImpl = fetch } = {}) {
   if (!token) return { kind: "no_credential" };
@@ -7685,7 +8001,7 @@ function isInteractiveTerminal() {
 }
 function defaultIdentityGateIo(opts) {
   const consoleUrl = opts.consoleUrl.trim().replace(/\/+$/, "");
-  const loginCli = [opts.platformRoot, resolveCodeRoot({})].filter((r) => Boolean(r && r.trim())).map((r) => join11(r, "vendor", "heyspex-mcp", "cli.mjs")).find((p) => existsSync5(p));
+  const loginCli = [opts.platformRoot, resolveCodeRoot({})].filter((r) => Boolean(r && r.trim())).map((r) => join11(r, "vendor", "heyspex-mcp", "cli.mjs")).find((p) => existsSync8(p));
   return {
     consoleUrl,
     interactive: opts.interactive ?? isInteractiveTerminal(),
@@ -7714,7 +8030,7 @@ function defaultIdentityGateIo(opts) {
         }
         return 0;
       }
-      const res = spawnSync2(
+      const res = spawnSync3(
         process.execPath,
         [loginCli, "login", flag, "--console-url", consoleUrl],
         {
@@ -7787,35 +8103,36 @@ async function main() {
     return;
   }
   const args = parsed.args;
-  const targetDir = resolve5(
+  const targetDir = resolve6(
     resolveInstallTargetDir(args.targetDir, process4.env, process4.cwd(), {
       satellite: args.attachVault !== void 0
     })
   );
-  const platformRoot = resolve5(
+  const platformRoot = resolve6(
     resolveCallerPath(args.platformRoot, process4.env, process4.cwd()) || platformDefault || process4.cwd()
   );
+  const eol = createGeneratedFileEol({ repoRoot: targetDir });
   const deps = {
     repoRoot: targetDir,
     resolvedTarget: targetDir,
     resolvedPlatform: platformRoot,
-    fileExists: (p) => existsSync6(p),
+    fileExists: (p) => existsSync9(p),
     readFile: (p) => {
       try {
-        return readFileSync11(p, "utf8");
+        return readFileSync14(p, "utf8");
       } catch {
         return null;
       }
     },
-    writeFile: (p, c) => writeFileSync6(p, c, "utf8"),
-    mkdir: (p) => mkdirSync6(p, { recursive: true }),
-    copyFile: (src, dest) => copyFileSync(src, dest),
+    writeFile: (p, c) => writeFileSync7(p, eol.convert(p, c), "utf8"),
+    mkdir: (p) => mkdirSync7(p, { recursive: true }),
+    copyFile: (src, dest) => copyFileSync2(src, dest),
     joinPath: (...s) => join12(...s),
     // Customer-template step (--register-vault) walks specs/ before applying.
     readdir: (p) => readdirSync2(p),
     isDirectory: (p) => {
       try {
-        return statSync(p).isDirectory();
+        return statSync5(p).isDirectory();
       } catch {
         return false;
       }
@@ -7874,11 +8191,17 @@ async function main() {
   const payload = remoteReceipt && !result.isError ? { ...result.payload, ...remoteReceipt } : result.payload;
   sink.write(`${args.json ? JSON.stringify(payload, null, 2) : result.message}
 `);
-  if (!result.isError && args.claudeApply && !args.dryRun && args.claude) {
-    const cliPath = mcpCliPath(platformRoot, join12);
-    const attachedRoot = result.payload?.attached_vault?.repo_root_abs;
+  const applyPayload = result.payload;
+  if (!result.isError && args.claudeApply && !args.dryRun && args.claude && applyPayload.claude_mcp_registered_by_manifest) {
+    process4.stdout.write(
+      "Claude Code: .mcp.json already registers the heyspex MCP server (nothing to apply).\n"
+    );
+  } else if (!result.isError && args.claudeApply && !args.dryRun && args.claude) {
+    const cliPath = mcpCliArgFor("claude", platformRoot, targetDir, join12);
+    const attachedRoot = applyPayload.attached_vault?.repo_root_abs;
+    const viaMarker = applyPayload.attached_vault?.via_marker === true;
     const mcpVaultRoot = attachedRoot ?? targetDir;
-    const claude = spawnSync3(
+    const claude = spawnSync4(
       "claude",
       [
         "mcp",
@@ -7887,8 +8210,7 @@ async function main() {
         "stdio",
         "--scope",
         "project",
-        "--env",
-        `HEYSPEX_VAULT_ROOT=${mcpVaultRoot}`,
+        ...viaMarker ? [] : ["--env", `HEYSPEX_VAULT_ROOT=${mcpVaultRoot}`],
         "heyspex",
         "--",
         process4.execPath,
@@ -7901,19 +8223,19 @@ async function main() {
         `hs install: claude mcp add failed (exit ${claude.status ?? "?"}).
 ${claude.stderr || claude.stdout || ""}
 Run manually:
-${buildClaudeMcpAddCommandPowerShell(targetDir, cliPath, attachedRoot)}
+${buildClaudeMcpAddCommandPowerShell(targetDir, cliPath, viaMarker ? null : attachedRoot)}
 `
       );
     } else {
       process4.stdout.write("Claude Code: registered heyspex MCP (--scope project).\n");
     }
   }
-  if (!result.isError && args.pluginApply && !args.dryRun && existsSync6(pluginMarketplaceManifestPath(platformRoot, join12))) {
+  if (!result.isError && args.pluginApply && !args.dryRun && existsSync9(pluginMarketplaceManifestPath(platformRoot, join12))) {
     const shell = process4.platform === "win32";
     const spec = resolvePluginSpec(platformRoot, {
       readFile: (p) => {
         try {
-          return readFileSync11(p, "utf8");
+          return readFileSync14(p, "utf8");
         } catch {
           return null;
         }
@@ -7927,7 +8249,7 @@ ${buildClaudeMcpAddCommandPowerShell(targetDir, cliPath, attachedRoot)}
       spec.spec,
       scope
     );
-    const claudeRun = (cliArgs) => spawnSync3("claude", cliArgs, { cwd: targetDir, encoding: "utf8", shell });
+    const claudeRun = (cliArgs) => spawnSync4("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]);
@@ -7962,7 +8284,7 @@ ${manualBlock}
   if (!result.isError && args.copilotPluginApply && !args.dryRun && copilotCommands) {
     const shell = process4.platform === "win32";
     const spec = result.payload.copilot_plugin_spec ?? "";
-    const copilotRun = (cliArgs) => spawnSync3("copilot", cliArgs, { cwd: targetDir, encoding: "utf8", shell });
+    const copilotRun = (cliArgs) => spawnSync4("copilot", cliArgs, { cwd: targetDir, encoding: "utf8", shell });
     const failed = (what, r) => process4.stderr.write(
       `hs install: copilot plugin ${what} failed (${r.error ? r.error.message : `exit ${r.status ?? "?"}`}).
 ${r.stderr || r.stdout || ""}
@@ -7989,8 +8311,8 @@ ${copilotCommands}
     const glyphScript = [
       join12(targetDir, "scripts", "install-statusline.mjs"),
       join12(platformRoot, "scripts", "install-statusline.mjs")
-    ].find((p) => existsSync6(p));
-    const glyph = glyphScript ? spawnSync3(process4.execPath, [glyphScript, "--glyph-only"], {
+    ].find((p) => existsSync9(p));
+    const glyph = glyphScript ? spawnSync4(process4.execPath, [glyphScript, "--glyph-only"], {
       cwd: targetDir,
       encoding: "utf8"
     }) : { status: 1, stdout: "", stderr: "install-statusline.mjs not found" };