heyspex 0.1.0 → 0.2.0

package/dist/cli/hs-init.mjs

@@ -1,19 +1,182 @@
 import { createRequire as __hsCreateRequire } from 'node:module';
 const require = __hsCreateRequire(import.meta.url);
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res) => function __init() {
+  return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+};
+
+// vendor/heyspex-mcp/credentials.mjs
+import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import os, { homedir } from "node:os";
+import { dirname, join, resolve as resolve2 } from "node:path";
+var init_credentials = __esm({
+  "vendor/heyspex-mcp/credentials.mjs"() {
+    "use strict";
+  }
+});
+
+// scripts/lib/dev-mode.mjs
+import { mkdirSync as mkdirSync2, readFileSync as readFileSync2, writeFileSync as writeFileSync2 } from "node:fs";
+import { homedir as homedir2 } from "node:os";
+import { join as join2 } from "node:path";
+function devModeFilePath(homeDir = homedir2()) {
+  return join2(homeDir, ".heyspex", DEV_MODE_FILENAME);
+}
+function normalizeMode(raw) {
+  const v = String(raw ?? "").trim().toLowerCase();
+  if (v === "prod" || v === "production") return { mode: "prod", reliance: "cloud" };
+  if (v === "dev") return { mode: "dev", reliance: null };
+  if (v === "local") return { mode: "dev", reliance: "local" };
+  if (v === "cloud") return { mode: "dev", reliance: "cloud" };
+  return null;
+}
+function normalizeReliance(raw) {
+  const v = String(raw ?? "").trim().toLowerCase();
+  return v === "local" || v === "cloud" ? v : null;
+}
+function deriveSemantics(mode, reliance) {
+  const effectiveReliance = mode === "prod" ? "cloud" : reliance ?? "local";
+  const local = mode === "dev" && effectiveReliance === "local";
+  return {
+    reliance: effectiveReliance,
+    consoleUrl: local ? LOCAL_CONSOLE_URL : CLOUD_CONSOLE_URL,
+    readTier: local ? "disk" : "neon",
+    vaultWriteMode: local ? "local" : "cloud"
+  };
+}
+function readLocalDevModeRecord({ homeDir = homedir2(), readFile = defaultReadFile } = {}) {
+  let raw;
+  try {
+    raw = readFile(devModeFilePath(homeDir));
+  } catch {
+    return { record: null, parseError: null };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    const mode = parsed?.mode === "prod" || parsed?.mode === "dev" ? parsed.mode : null;
+    const reliance = normalizeReliance(parsed?.reliance);
+    if (!mode || mode === "dev" && !reliance) {
+      return { record: null, parseError: `invalid dev-mode record: ${JSON.stringify(parsed)}` };
+    }
+    return {
+      record: {
+        mode,
+        reliance: mode === "prod" ? "cloud" : reliance,
+        console_url: typeof parsed.console_url === "string" ? parsed.console_url : null,
+        updated_at: typeof parsed.updated_at === "string" ? parsed.updated_at : null,
+        source: typeof parsed.source === "string" ? parsed.source : null
+      },
+      parseError: null
+    };
+  } catch (err) {
+    return { record: null, parseError: `unparseable dev-mode.json: ${String(err?.message ?? err)}` };
+  }
+}
+function resolveDevMode({
+  env = process.env,
+  homeDir = homedir2(),
+  readFile = defaultReadFile,
+  cloudSetting = void 0
+} = {}) {
+  const local = readLocalDevModeRecord({ homeDir, readFile });
+  const cloudKnown = cloudSetting !== void 0;
+  const cloudValue = cloudKnown && cloudSetting ? {
+    mode: cloudSetting.mode === "dev" ? "dev" : "prod",
+    reliance: normalizeReliance(cloudSetting.reliance) ?? "cloud"
+  } : null;
+  let mode;
+  let reliance;
+  let source;
+  let relianceSource;
+  const envParsed = normalizeMode(env.HEYSPEX_DEV_MODE);
+  if (envParsed) {
+    mode = envParsed.mode;
+    const envReliance = envParsed.reliance ?? normalizeReliance(env.HEYSPEX_DEV_RELIANCE);
+    reliance = envReliance ?? "local";
+    source = "env";
+    relianceSource = envReliance ? "env" : "assumed-local";
+  } else if (local.record) {
+    mode = local.record.mode;
+    reliance = local.record.reliance;
+    source = "local-override";
+  } else if (cloudValue) {
+    mode = cloudValue.mode;
+    reliance = cloudValue.reliance;
+    source = "cloud-setting";
+  } else {
+    mode = "prod";
+    reliance = "cloud";
+    source = "default";
+  }
+  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);
+  return {
+    mode,
+    reliance: semantics.reliance,
+    consoleUrl,
+    readTier: semantics.readTier,
+    vaultWriteMode: semantics.vaultWriteMode,
+    sources: {
+      mode: source,
+      reliance: relianceSource ?? source,
+      consoleUrl: source === "local-override" && local.record?.console_url ? "local-override" : "derived",
+      readTier: "derived",
+      vaultWriteMode: "derived"
+    },
+    localOverride: {
+      present: local.record !== null,
+      record: local.record,
+      parseError: local.parseError,
+      staleAgainstCloud
+    },
+    cloudSetting: { known: cloudKnown, value: cloudValue }
+  };
+}
+var CLOUD_CONSOLE_URL, LOCAL_CONSOLE_URL, DEV_MODE_FILENAME, defaultReadFile;
+var init_dev_mode = __esm({
+  "scripts/lib/dev-mode.mjs"() {
+    "use strict";
+    init_credentials();
+    CLOUD_CONSOLE_URL = "https://app.heyspex.com";
+    LOCAL_CONSOLE_URL = "http://localhost:3000";
+    DEV_MODE_FILENAME = "dev-mode.json";
+    defaultReadFile = (p) => readFileSync2(p, "utf8");
+  }
+});
 
 // spex-console/bin/hs-init.ts
 import {
   copyFileSync,
-  existsSync,
-  mkdirSync,
+  existsSync as existsSync4,
+  mkdirSync as mkdirSync4,
   readdirSync,
-  readFileSync as readFileSync4,
-  writeFileSync
+  readFileSync as readFileSync8,
+  statSync,
+  writeFileSync as writeFileSync4
 } from "node:fs";
-import { dirname, join as join3, resolve } from "node:path";
-import process2 from "node:process";
+import { dirname as dirname5, join as join9, resolve as resolve5 } from "node:path";
+import process3 from "node:process";
 import { createInterface } from "node:readline/promises";
-import { fileURLToPath } from "node:url";
+import { fileURLToPath as fileURLToPath2 } from "node:url";
+
+// scripts/lib/shared-path-helpers.mjs
+import { isAbsolute, resolve, sep } from "node:path";
+function resolveCodeRoot({
+  explicit,
+  packageRoot,
+  vaultRoot,
+  env = process.env
+} = {}) {
+  const fromExplicit = typeof explicit === "string" ? explicit.trim() : "";
+  if (fromExplicit) return fromExplicit;
+  const fromEnv = typeof env?.HS_PKG_ROOT === "string" ? env.HS_PKG_ROOT.trim() : "";
+  if (fromEnv) return fromEnv;
+  const fromPackage = typeof packageRoot === "string" ? packageRoot.trim() : "";
+  if (fromPackage) return fromPackage;
+  const fromVault = typeof vaultRoot === "string" ? vaultRoot.trim() : "";
+  return fromVault;
+}
 
 // spex-console/src/lib/cli/customer-claude-md.ts
 function renderCustomerClaudeMd({
@@ -65,15 +228,38 @@ The vault under \`specs/\` is the only persistent queue. File new work via \`hey
 This CLAUDE.md was generated for **${vaultName}** from HeySpex template version **${templateVersion}** \u2014 it is yours to edit. Unlike HeySpex's own platform contract (which carries HeySpex's internal build tooling), everything above applies to *your* vault and *your* agents. Edit it freely as your project's conventions evolve; a later template update will not overwrite your changes.
 `;
 }
-function customerClaudeMdHook() {
+function writeProjectContract(ctx, options = {}) {
+  const content = renderCustomerClaudeMd({
+    vaultName: ctx.vaultName,
+    templateVersion: ctx.templateVersion
+  });
+  const results = [];
+  for (const file of options.files ?? ["CLAUDE.md"]) {
+    const destPath = ctx.deps.joinPath(ctx.targetDir, file);
+    if (!ctx.deps.exists(destPath)) {
+      ctx.deps.writeFile(destPath, content);
+      ctx.recordWrite?.(destPath);
+      results.push({ file, action: "created", path: destPath });
+      continue;
+    }
+    if (ctx.deps.readFile?.(destPath) === content) {
+      results.push({ file, action: "unchanged" });
+      continue;
+    }
+    const templatePath = ctx.deps.joinPath(ctx.targetDir, `${file}.template`);
+    if (ctx.deps.readFile?.(templatePath) !== content) {
+      ctx.deps.writeFile(templatePath, content);
+      ctx.recordWrite?.(templatePath);
+    }
+    const hint = `${file} already exists - left untouched. Generated contract written to ${file}.template; compare with: diff ${file} ${file}.template`;
+    options.notify?.(hint);
+    results.push({ file, action: "template", path: templatePath, hint });
+  }
+  return results;
+}
+function customerClaudeMdHook(notify) {
   return (ctx) => {
-    const content = renderCustomerClaudeMd({
-      vaultName: ctx.vaultName,
-      templateVersion: ctx.templateVersion
-    });
-    const destPath = ctx.deps.joinPath(ctx.targetDir, "CLAUDE.md");
-    ctx.deps.writeFile(destPath, content);
-    ctx.recordWrite(destPath);
+    writeProjectContract(ctx, { notify });
   };
 }
 
@@ -81,69 +267,182 @@ function customerClaudeMdHook() {
 import { randomUUID } from "node:crypto";
 
 // scripts/lib/console-url-resolver.mjs
-import { readFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { join } from "node:path";
-var DEFAULT_CONSOLE_URL = "https://app.heyspex.com";
+init_dev_mode();
+import { readFileSync as readFileSync3 } from "node:fs";
+import { homedir as homedir3 } from "node:os";
+import { join as join3 } from "node:path";
+var DEFAULT_CONSOLE_URL = LOCAL_CONSOLE_URL;
 function trimTrailingSlash(url) {
   return url.replace(/\/+$/, "");
 }
-function readCredentialsConsoleUrl({ homeDir = homedir() } = {}) {
+var LOOPBACK_HOSTS = /* @__PURE__ */ new Set(["localhost", "127.0.0.1", "::1", "[::1]", "0.0.0.0"]);
+function isLoopbackConsoleUrl(url) {
+  if (typeof url !== "string" || !url) return false;
+  try {
+    return LOOPBACK_HOSTS.has(new URL(url).hostname.toLowerCase());
+  } catch {
+    return false;
+  }
+}
+var staleLoopbackCredentialsWarned = false;
+function warnStaleLoopbackCredentialsOnce(credentialsUrl, derivedUrl, { log }) {
+  if (staleLoopbackCredentialsWarned) return;
+  staleLoopbackCredentialsWarned = true;
+  try {
+    log(
+      `[heyspex] ignoring console_url ${credentialsUrl} from ~/.heyspex/credentials.yaml: the resolved reliance is cloud, and a loopback console cannot serve it \u2014 using ${derivedUrl} (set HEYSPEX_CONSOLE_URL to override explicitly, or run \`hs dev mode:local\` to go back to a local console).
+`
+    );
+  } catch {
+  }
+}
+function readCredentialsConsoleUrl({ homeDir = homedir3(), readFile = defaultReadFile2 } = {}) {
   try {
-    const raw = readFileSync(join(homeDir, ".heyspex", "credentials.yaml"), "utf8");
-    const match = raw.match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
+    const raw = readFile(join3(homeDir, ".heyspex", "credentials.yaml"));
+    const match = String(raw ?? "").match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
     const value = match?.[1]?.trim();
     return value && value.length > 0 ? trimTrailingSlash(value) : null;
   } catch {
     return null;
   }
 }
-function readDiscoveryFileConsoleUrl(repoRoot) {
+function defaultReadFile2(p) {
+  return readFileSync3(p, "utf8");
+}
+function readDiscoveryFileConsoleUrl(repoRoot, { readDiscovery = defaultReadFile2 } = {}) {
   if (!repoRoot) return null;
-  for (const name of [
-    "console-url",
-    "cockpit-url"
-    /* legacy-cockpit */
-  ]) {
-    try {
-      const discovery = readFileSync(join(repoRoot, ".heyspex", name), "utf8").trim();
-      if (discovery.length > 0) return trimTrailingSlash(discovery);
-    } catch {
-    }
+  try {
+    const discovery = String(readDiscovery(join3(repoRoot, ".heyspex", "console-url")) ?? "").trim();
+    if (discovery.length > 0) return trimTrailingSlash(discovery);
+  } catch {
   }
   return null;
 }
 var ConsoleUrlUnresolvedError = class extends Error {
   constructor() {
     super(
-      `resolveConsoleUrl: no HEYSPEX_CONSOLE_URL/HEYSPEX_COCKPIT_URL env, no console_url: in ~/.heyspex/credentials.yaml, and no .heyspex/console-url discovery file \u2014 refusing to silently fall back to the ${DEFAULT_CONSOLE_URL} default in strict mode.`
+      "resolveConsoleUrl: local reliance with no HEYSPEX_CONSOLE_URL env, no console_url: in ~/.heyspex/credentials.yaml, and no .heyspex/console-url discovery file \u2014 refusing to silently fall back to the localhost:3000 default in strict mode."
     );
     this.name = "ConsoleUrlUnresolvedError";
   }
 };
+function resolveModeEnvelope({ env, homeDir }) {
+  try {
+    const resolved = resolveDevMode({ env, homeDir });
+    return {
+      reliance: resolved.reliance === "cloud" ? "cloud" : "local",
+      consoleUrl: resolved.consoleUrl || DEFAULT_CONSOLE_URL
+    };
+  } catch {
+    return { reliance: "local", consoleUrl: DEFAULT_CONSOLE_URL };
+  }
+}
 function resolveConsoleUrl({
   repoRoot,
   env = process.env,
-  homeDir = homedir(),
-  strict = false
+  homeDir = homedir3(),
+  strict = false,
+  devMode,
+  log = (line) => process.stderr.write(line),
+  readFile = defaultReadFile2,
+  readDiscovery = defaultReadFile2
 } = {}) {
-  const envUrl = (env.HEYSPEX_CONSOLE_URL ?? env.HEYSPEX_COCKPIT_URL)?.trim();
+  const envUrl = env.HEYSPEX_CONSOLE_URL?.trim();
   if (envUrl) return trimTrailingSlash(envUrl);
-  const credentialsUrl = readCredentialsConsoleUrl({ homeDir });
-  if (credentialsUrl) return credentialsUrl;
-  const discoveryUrl = readDiscoveryFileConsoleUrl(repoRoot);
-  if (discoveryUrl) return discoveryUrl;
-  if (strict) throw new ConsoleUrlUnresolvedError();
-  return DEFAULT_CONSOLE_URL;
+  const mode = devMode ?? resolveModeEnvelope({ env, homeDir });
+  const cloud = mode.reliance === "cloud";
+  const derivedUrl = trimTrailingSlash(
+    cloud && isLoopbackConsoleUrl(mode.consoleUrl) ? CLOUD_CONSOLE_URL : mode.consoleUrl || DEFAULT_CONSOLE_URL
+  );
+  const credentialsUrl = readCredentialsConsoleUrl({ homeDir, readFile });
+  if (credentialsUrl) {
+    if (cloud && isLoopbackConsoleUrl(credentialsUrl)) {
+      warnStaleLoopbackCredentialsOnce(credentialsUrl, derivedUrl, { log });
+    } else {
+      return credentialsUrl;
+    }
+  }
+  if (!cloud) {
+    const discoveryUrl = readDiscoveryFileConsoleUrl(repoRoot, { readDiscovery });
+    if (discoveryUrl) return discoveryUrl;
+    if (strict) throw new ConsoleUrlUnresolvedError();
+  }
+  return derivedUrl;
 }
 
 // spex-console/src/lib/cli/control-shared.ts
-import { readFileSync as readFileSync2 } from "node:fs";
-import { homedir as homedir2 } from "node:os";
-import { join as join2 } from "node:path";
+import path 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";
+var HS_BIN_NAME = "hs";
+var HS_DISPATCHER_PATH = (() => {
+  try {
+    const here = dirname2(fileURLToPath(import.meta.url));
+    return join4(dirname2(dirname2(here)), "bin", "hs.mjs");
+  } catch {
+    return null;
+  }
+})();
+function shellQuote(p) {
+  return /[\\\s]/.test(p) ? `"${p}"` : p;
+}
+var HS_DISPATCHER_PREFIX = HS_DISPATCHER_PATH ? `node ${shellQuote(HS_DISPATCHER_PATH)}` : HS_BIN_NAME;
+
+// vendor/heyspex-mcp/console-fetch.mjs
+init_credentials();
+import { readFileSync as readFileSync6 } from "node:fs";
+import { homedir as homedir6 } from "node:os";
+import { join as join7 } from "node:path";
+
+// vendor/heyspex-mcp/session-owner.mjs
+init_credentials();
+import { readFileSync as readFileSync4 } from "node:fs";
+import { homedir as homedir4 } from "node:os";
+import { join as join5 } from "node:path";
+
+// vendor/heyspex-mcp/vault-less-endpoints.mjs
+var VAULT_LESS_ENDPOINTS = Object.freeze([
+  "* /api/mcp/session",
+  "* /api/mcp/pairing-codes",
+  "POST /api/vaults",
+  "GET /api/vaults",
+  "POST /api/workspaces",
+  "GET /api/workspaces",
+  "* /api/admin/dev-mode"
+]);
+
+// vendor/heyspex-mcp/vault-resolve.mjs
+import { existsSync as existsSync2, readFileSync as readFileSync5 } from "node:fs";
+import { homedir as homedir5, tmpdir } from "node:os";
+import { dirname as dirname3, join as join6, resolve as resolve3 } from "node:path";
+
+// vendor/heyspex-mcp/console-fetch.mjs
+var SCOPE_REFUSAL_CODES = Object.freeze(["VAULT_SCOPE_MISMATCH", "ACCOUNT_MISMATCH", "VAULT_NOT_REGISTERED"]);
+
+// spex-console/src/lib/cli/control-shared.ts
+init_credentials();
+
+// spex-console/src/lib/vault-registry/registry-file.ts
+import { existsSync as existsSync3, mkdirSync as mkdirSync3, readFileSync as readFileSync7, renameSync as renameSync2, writeFileSync as writeFileSync3 } from "node:fs";
+import { homedir as homedir7 } from "node:os";
+import { dirname as dirname4, join as join8, resolve as resolve4 } from "node:path";
+
+// spex-console/src/lib/cli/control-shared.ts
 var EXIT = {
   /** Success. */
   OK: 0,
+  /**
+   * A read-only CHECK ran correctly and its answer is "no" — `hs connect
+   * --check` on an unconnected repo. Distinct from {@link EXIT.USAGE} so a
+   * script can tell "you typed the command wrong" from "the command worked,
+   * the repo is not connected". Both were `1` until 2026-09-18, which made
+   * `--check` unusable in a conditional: every caller had to parse stdout to
+   * find out which of the two had happened.
+   */
+  CHECK_FAILED: 2,
   /** Usage error — unknown subcommand/flag, or a missing required argument. */
   USAGE: 1,
   /** Claim race lost — the spec is already claimed by another agent (409). */
@@ -165,12 +464,63 @@ var EXIT = {
    * from `USAGE`/`INVALID_ARG` — this is an authorization refusal, not a
    * malformed command.
    */
-  FORBIDDEN: 15
+  FORBIDDEN: 15,
+  /**
+   * A CLOUD write refused because no account id could be resolved (no
+   * `HS_ACCOUNT_ID` env var, no `account_id:` in `~/.heyspex/config.yaml`) --
+   * `resolveCloudAccountIdOrRefuse` in `vault-workspace-shared.ts`
+   * ([[HS-YU1S-UAGY-TASK-cloud-writes-refuse-without-a]]). Distinct from
+   * `FORBIDDEN` -- this is "not signed in at all", not "signed in but not
+   * authorized for this override".
+   */
+  SIGN_IN_REQUIRED: 16,
+  /**
+   * Signed in, but the account a repo would be attached to was not confirmed:
+   * a non-interactive install/connect with no matching `--account` / `--yes`,
+   * an `account_id` that disagrees with the bearer's user, or the human
+   * aborting the identity prompt (`install-identity.ts`,
+   * [[HS-HAQI-KODY-DIAG-hs-install-and-hs-connect-bind-a-new]]).
+   */
+  IDENTITY_UNCONFIRMED: 17,
+  /**
+   * The repo this verb runs in is not registered on this machine (no
+   * `~/.heyspex/registry.json` row for its root, or a legacy slug row with no
+   * cloud `vault_id` in its heyspex.yaml), so the call was refused LOCALLY —
+   * nothing was sent. Names `hs connect`
+   * ([[HS-MVG4-WW9R-TASK-mcp-and-hs-name-account-vault-on-every]]).
+   */
+  VAULT_NOT_REGISTERED: 18,
+  /**
+   * The local half of a setup verb (`hs connect`, `hs vault *`, `hs workspace
+   * *`) was written but the CLOUD half did not land -- the console refused
+   * it or was never reached. The verb's receipt names the failed half and the
+   * exact command to re-run
+   * ([[HS-STCY-WW9R-TASK-add-a-shared-receipt-that-reads-back]], invariant 6).
+   * Distinct from {@link EXIT.WRITE_FAILED} so a script can tell "re-run to
+   * sync the cloud" from a generic server failure.
+   */
+  CLOUD_WRITE_FAILED: 19,
+  /**
+   * The repo's committed `heyspex.yaml` records `account: <A>` but the machine
+   * is signed in as another account, so `hs connect` refused and wrote
+   * nothing (marker, registry, cloud). Repair: `hs login --switch-account <A>`
+   * ([[HS-VWUD-WW9R-TASK-record-the-connecting-account-in]], invariant 4).
+   */
+  ACCOUNT_MISMATCH: 20,
+  /**
+   * Both sides of a setup verb's receipt were read back and still DISAGREE
+   * after a short bounded re-read of the cloud side (a briefly stale read is
+   * absorbed first). The write may well have landed; what the verb cannot
+   * claim is that this machine and the console now say the same thing. The
+   * receipt prints the diffs and the command to re-run
+   * ([[HS-FKSR-WW9R-TASK-make-one-hs-connect-run-create-a-cloud]], invariant 6).
+   * Distinct from {@link EXIT.CLOUD_WRITE_FAILED} (a write that did not land).
+   */
+  RECEIPT_DISAGREE: 21
 };
 
 // spex-console/src/lib/cli/init.ts
 var HEYSPEX_YAML_SCHEMA_VERSION = 2;
-var DEFAULT_CONSOLE_URL2 = resolveConsoleUrl();
 function mintVaultId() {
   return randomUUID();
 }
@@ -181,6 +531,30 @@ function parseVaultId(content) {
   const unquoted = raw.replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1");
   return unquoted.length > 0 ? unquoted : null;
 }
+function parseAccountId(content) {
+  const m = content.match(/^account:[ \t]*(.+?)\s*$/m);
+  if (!m) return null;
+  const raw = m[1].replace(/\s+#.*$/, "").trim();
+  const unquoted = raw.replace(/^"(.*)"$/, "$1").replace(/^'(.*)'$/, "$1");
+  return unquoted.length > 0 ? unquoted : null;
+}
+var MARKER_ACCOUNT_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_.@+-]*$/;
+function recordMarkerAccount(content, accountId) {
+  if (!MARKER_ACCOUNT_ID_RE.test(accountId)) {
+    throw new Error(`recordMarkerAccount: "${accountId}" is not a valid account id`);
+  }
+  const recorded = parseAccountId(content);
+  if (recorded === accountId) return { action: "unchanged", content };
+  if (recorded !== null) return { action: "conflict", recorded, content };
+  const eol = content.includes("\r\n") ? "\r\n" : "\n";
+  const lines = content.replace(/(\r?\n)+$/, "").split(/\r?\n/);
+  const kept = lines.filter((l) => !/^account:\s*$/.test(l));
+  const vaultIdx = kept.findIndex((l) => /^vault_id:/.test(l));
+  const line = `account: ${accountId}`;
+  if (vaultIdx >= 0) kept.splice(vaultIdx + 1, 0, line);
+  else kept.push(line);
+  return { action: "added", content: `${kept.join(eol)}${eol}` };
+}
 function appendVaultIdLine(content, vaultId) {
   const trimmed = content.replace(/\n+$/, "");
   return `${trimmed}
@@ -188,21 +562,22 @@ vault_id: ${vaultId}
 `;
 }
 function parseInitArgs(argv) {
-  let consoleUrl = (process.env.HEYSPEX_CONSOLE_URL ?? process.env.HEYSPEX_COCKPIT_URL)?.trim() || // legacy-cockpit env
-  DEFAULT_CONSOLE_URL2;
+  let consoleUrl = resolveConsoleUrl();
   let vaultRoot = "specs/";
   let force = false;
   let json = false;
   let customerVaultDir;
   let principles;
   let vaultName;
-  let noGit = false;
+  let git = false;
   for (let i = 0; i < argv.length; i++) {
     const arg = argv[i];
     if (arg === "--help" || arg === "-h") return { help: true };
     else if (arg === "--json") json = true;
     else if (arg === "--force") force = true;
-    else if (arg === "--no-git") noGit = true;
+    else if (arg === "--git") git = true;
+    else if (arg === "--no-git")
+      git = false;
     else if (arg === "--principles" || arg.startsWith("--principles=")) {
       const v = arg === "--principles" ? argv[++i] : arg.slice("--principles=".length);
       if (v === void 0 || v.trim() === "") {
@@ -215,8 +590,7 @@ function parseInitArgs(argv) {
         return { error: { code: EXIT.INVALID_ARG, message: "--vault-name requires a value" } };
       }
       vaultName = v.trim();
-    } else if (arg === "--console-url" || arg.startsWith("--console-url=") || arg === "--cockpit-url" || // legacy-cockpit alias
-    arg.startsWith("--cockpit-url=")) {
+    } else if (arg === "--console-url" || arg.startsWith("--console-url=")) {
       const eq = arg.indexOf("=");
       const v = eq === -1 ? argv[++i] : arg.slice(eq + 1);
       if (v === void 0 || v.trim() === "") {
@@ -247,17 +621,36 @@ function parseInitArgs(argv) {
     }
   }
   return {
-    args: { consoleUrl, vaultRoot, force, json, customerVaultDir, principles, vaultName, noGit }
+    args: { consoleUrl, vaultRoot, force, json, customerVaultDir, principles, vaultName, git }
   };
 }
+var HEYSPEX_CONFIG_DIR = ".heyspex";
+var HEYSPEX_CONFIG_FILE = "config.yaml";
+function seedConfigYaml(root, readSeed, fs) {
+  const configDir = fs.joinPath(root, HEYSPEX_CONFIG_DIR);
+  const configPath = fs.joinPath(configDir, HEYSPEX_CONFIG_FILE);
+  if (fs.exists(configPath)) return { status: "kept", path: configPath };
+  if (!readSeed) return { status: "no_seed", path: configPath };
+  let seed;
+  try {
+    seed = readSeed();
+  } catch {
+    seed = null;
+  }
+  if (seed === null) return { status: "no_seed", path: configPath };
+  fs.mkdirRecursive(configDir);
+  fs.writeFile(configPath, seed);
+  return { status: "seeded", path: configPath };
+}
 function renderHeyspexYaml(args) {
-  return [
+  const body = [
     `schema_version: ${HEYSPEX_YAML_SCHEMA_VERSION}`,
     `console_url: ${args.consoleUrl}`,
     `vault_root: ${args.vaultRoot}`,
     `vault_id: ${args.vaultId}`,
     ""
   ].join("\n");
+  return args.accountId ? recordMarkerAccount(body, args.accountId).content : body;
 }
 function readExistingContent(deps, markerPath) {
   if (!deps.readFile) return null;
@@ -272,17 +665,60 @@ function runInit(args, deps) {
   const exists = deps.fileExists(markerPath);
   const existingContent = exists ? readExistingContent(deps, markerPath) : null;
   const existingVaultId = existingContent ? parseVaultId(existingContent) : null;
+  if (deps.mkdirRecursive) {
+    const specsPath = deps.joinPath(deps.repoRoot, args.vaultRoot);
+    try {
+      deps.mkdirRecursive(specsPath);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        code: EXIT.WRITE_FAILED,
+        message: `failed to create ${specsPath}: ${message}`,
+        payload: { ok: false, error: "write_failed", path: specsPath, message },
+        isError: true
+      };
+    }
+  }
+  let configSeed = null;
+  const mkdirRecursive = deps.mkdirRecursive;
+  if (mkdirRecursive) {
+    const readConfigSeed2 = deps.readConfigSeed;
+    try {
+      configSeed = seedConfigYaml(
+        deps.repoRoot,
+        readConfigSeed2 ? () => readConfigSeed2.call(deps) : void 0,
+        {
+          exists: (p) => deps.fileExists(p),
+          mkdirRecursive: (p) => mkdirRecursive.call(deps, p),
+          writeFile: (p, c) => deps.writeFile(p, c),
+          joinPath: (...s) => deps.joinPath(...s)
+        }
+      );
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      const configPath = deps.joinPath(deps.repoRoot, HEYSPEX_CONFIG_DIR, HEYSPEX_CONFIG_FILE);
+      return {
+        code: EXIT.WRITE_FAILED,
+        message: `failed to seed ${configPath}: ${message}`,
+        payload: { ok: false, error: "write_failed", path: configPath, message },
+        isError: true
+      };
+    }
+  }
+  const configNote = configSeed?.status === "seeded" ? ` Seeded ${configSeed.path}.` : configSeed?.status === "kept" ? ` Kept existing ${configSeed.path}.` : "";
+  const configPayload = configSeed === null || configSeed.status === "no_seed" ? {} : { config_yaml: configSeed.path, config_yaml_seeded: configSeed.status === "seeded" };
   if (exists && !args.force) {
     if (existingVaultId) {
       return {
         code: EXIT.OK,
-        message: `heyspex.yaml already exists at ${markerPath} \u2014 vault already initialized (use --force to overwrite).`,
+        message: `heyspex.yaml already exists at ${markerPath} \u2014 vault already initialized (use --force to overwrite).${configNote}`,
         payload: {
           ok: true,
           created: false,
           path: markerPath,
           reason: "already_initialized",
-          vault_id: existingVaultId
+          vault_id: existingVaultId,
+          ...configPayload
         },
         isError: false
       };
@@ -290,8 +726,14 @@ function runInit(args, deps) {
     if (existingContent === null) {
       return {
         code: EXIT.OK,
-        message: `heyspex.yaml already exists at ${markerPath} \u2014 vault already initialized (use --force to overwrite).`,
-        payload: { ok: true, created: false, path: markerPath, reason: "already_initialized" },
+        message: `heyspex.yaml already exists at ${markerPath} \u2014 vault already initialized (use --force to overwrite).${configNote}`,
+        payload: {
+          ok: true,
+          created: false,
+          path: markerPath,
+          reason: "already_initialized",
+          ...configPayload
+        },
         isError: false
       };
     }
@@ -310,19 +752,21 @@ function runInit(args, deps) {
     }
     return {
       code: EXIT.OK,
-      message: `Added vault_id to existing heyspex.yaml at ${markerPath} (schema_version unchanged).`,
+      message: `Added vault_id to existing heyspex.yaml at ${markerPath} (schema_version unchanged).${configNote}`,
       payload: {
         ok: true,
         created: false,
         backfilled: true,
         path: markerPath,
-        vault_id: mintedId
+        vault_id: mintedId,
+        ...configPayload
       },
       isError: false
     };
   }
   const vaultId = existingVaultId ?? args.adoptedVaultId ?? mintVaultId();
-  const content = renderHeyspexYaml({ ...args, vaultId });
+  const accountId = args.accountId ?? (existingContent ? parseAccountId(existingContent) : null);
+  const content = renderHeyspexYaml({ ...args, vaultId, accountId });
   try {
     deps.writeFile(markerPath, content);
   } catch (err) {
@@ -336,7 +780,7 @@ function runInit(args, deps) {
   }
   return {
     code: EXIT.OK,
-    message: `${exists ? "Overwrote" : "Wrote"} ${markerPath} (schema_version ${HEYSPEX_YAML_SCHEMA_VERSION}).`,
+    message: `${exists ? "Overwrote" : "Wrote"} ${markerPath} (schema_version ${HEYSPEX_YAML_SCHEMA_VERSION}).${configNote}`,
     payload: {
       ok: true,
       created: true,
@@ -345,7 +789,9 @@ function runInit(args, deps) {
       schema_version: HEYSPEX_YAML_SCHEMA_VERSION,
       console_url: args.consoleUrl,
       vault_root: args.vaultRoot,
-      vault_id: vaultId
+      vault_id: vaultId,
+      ...accountId ? { account: accountId } : {},
+      ...configPayload
     },
     isError: false
   };
@@ -354,27 +800,38 @@ var HELP = [
   "Usage:",
   "  hs init [--console-url <url>] [--vault-root <path>] [--force] [--json]",
   "  hs init --customer-vault <dir> [--console-url <url>] [--principles <all|none|a,b>]",
-  "                          [--vault-name <name>] [--no-git] [--json]",
+  "                          [--vault-name <name>] [--git] [--json]",
   "",
   "Write the top-level heyspex.yaml vault marker (schema_version, console_url,",
-  "vault_root, vault_id) \u2014 the committed file the console / web companion read",
+  "vault_root, vault_id; `hs connect` also records `account:`, the account id the",
+  "repo was connected under) \u2014 the committed file the console / web companion read",
   "to bootstrap a vault. Idempotent: an existing marker is left untouched unless",
   "--force, EXCEPT a missing vault_id is backfilled in place either way (backward",
   "compatible \u2014 no schema_version bump). vault_id is reused exactly when already",
   "present; a fresh one is minted only when absent.",
-  "Does not modify .heyspex/config.yaml or its templates (ADR-0009).",
+  "Also scaffolds the vault_root folder and seeds .heyspex/config.yaml (the",
+  "HeySpex workflow settings, ADR-0009) from the shipped template",
+  "(vendor/heyspex-mcp/config-seed.yaml) when that file is absent. An existing",
+  ".heyspex/config.yaml is never rewritten \u2014 not even with --force; change its",
+  "values with `hs settings set <key> <value>`.",
   "",
   "--customer-vault <dir> scaffolds a REAL customer vault at <dir> instead: the",
-  "specs/ folder tree, heyspex.yaml, and every row of the template shipping",
-  "manifest (spex-console/src/lib/cli/template-manifest.ts) \u2014 universal docs",
+  "specs/ folder tree, heyspex.yaml, the seeded .heyspex/config.yaml, and every",
+  "row of the template shipping manifest",
+  "(spex-console/src/lib/cli/template-manifest.ts) \u2014 universal docs",
   "copied verbatim, template-shape docs written as author-prompt skeletons \u2014",
-  "plus a generated CLAUDE.md, the kept-principles index, and (unless --no-git)",
-  "one initial `git init` + commit pinning the template version. Refuses a",
-  "non-empty <dir> with a plain error. See init.customer-vault.ts.",
+  "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.",
   "",
   "Flags:",
-  "  --console-url <url>  console_url value (default: $HEYSPEX_CONSOLE_URL or",
-  "                       https://console.heyspex.local).",
+  "  --console-url <url>  console_url value (default: the mode-aware console --",
+  "                       $HEYSPEX_CONSOLE_URL, else the signed-in console, else",
+  "                       https://app.heyspex.com in prod mode).",
   "  --vault-root <path>  vault_root value (default: specs/).",
   "  --customer-vault <dir> Scaffold a new customer vault at <dir> (see above).",
   "  --principles <all|none|a,b> Which universal principle docs to ship",
@@ -382,8 +839,9 @@ var HELP = [
   "                       keep/skip prompt per principle. Omitted + no TTY: all.",
   "  --vault-name <name>  Display name for the scaffolded vault (--customer-vault",
   "                       only; default: <dir>'s basename).",
-  "  --no-git             Skip git init + the initial commit (--customer-vault only).",
-  "  --force              Overwrite an existing heyspex.yaml.",
+  "  --git                Also run git init + one initial commit (--customer-vault only;",
+  "                       default: no git). --no-git is accepted as a no-op.",
+  "  --force              Overwrite an existing heyspex.yaml (never .heyspex/config.yaml).",
   "  --json               Emit a machine-readable JSON result.",
   "  --help, -h           Show this help.",
   "",
@@ -407,14 +865,69 @@ var UNIVERSAL_TEMPLATE_ROWS = [
   {
     platformSource: "specs/protocols/memory-protocol.md",
     dest: "specs/protocols/memory-protocol.md"
+  },
+  {
+    // ~455 lines of HS-REV / MVP-grain / guardrail detail that cannot be
+    // curated cleanly: ships a template-shape abridgement instead.
+    platformSource: "specs/protocols/session-close-protocol.md",
+    abridgedSource: "spex-console/templates/abridged/specs/protocols/session-close-protocol.md",
+    dest: "specs/protocols/session-close-protocol.md"
+  },
+  {
+    platformSource: "specs/protocols/spec-summary-authoring.md",
+    dest: "specs/protocols/spec-summary-authoring.md",
+    dropSections: ["Keeping the code snapshot in sync", "Change log"],
+    dropLinePatterns: ["vendor/heyspex-mcp/summary-contract\\.mjs"]
+  },
+  {
+    platformSource: "specs/protocols/destructive-action-checklist.md",
+    dest: "specs/protocols/destructive-action-checklist.md",
+    dropSections: ["Change log"],
+    dropLinePatterns: ["spex-console/scripts/validate-destructive-actions\\.mjs"],
+    replacements: [
+      [
+        "The 2026-05-22 idea-discard incident showed that strong UX *principles*\n([[errors-destructive-recovery]], [[reversible-user-actions]]) are not\nenough",
+        "A past idea-discard data-loss incident showed that strong UX *principles*\n(recoverable destructive actions, reversible user actions) are not\nenough"
+      ],
+      [
+        "Today: linked from `CLAUDE.md` Console pre-ship checklist; agents must\nwalk it",
+        "Today: agents must\nwalk it"
+      ],
+      [
+        '- [ ] If a *new* destructive surface is introduced, append it to the\n      "Where this is applied" table in\n      [[destructive-action-needs-explicit-button-and-undo]].',
+        "- [ ] If a *new* destructive surface is introduced, record it in a vault memory."
+      ],
+      [
+        "- [ ] Read [[errors-destructive-recovery]] and\n      [[destructive-action-needs-explicit-button-and-undo]] in full.",
+        "- [ ] Read any vault memories on destructive-action recovery and Undo."
+      ],
+      [
+        " (Not covered here; see existing dirty-editor\n      pattern in `specs-surface.tsx`.)",
+        " (Not covered here.)"
+      ]
+    ]
   }
 ];
 
 // dist/cli/._template-manifest-sources.cli-shim.mjs
 var CURATED_TEMPLATE_ROOT = "dist/cli-templates/customer-vault";
 
+// scripts/lib/template-pin.mjs
+var TEMPLATE_VERSION = "1.1.0";
+var TEMPLATE_CORE_DESTS = Object.freeze([
+  "specs/north-star.md",
+  "specs/principles-index.md",
+  "specs/roadmap.md",
+  "specs/entity-model.md",
+  "specs/protocols/canonical-frontmatter-templates.md",
+  "specs/protocols/spec-hierarchy.md",
+  "specs/protocols/memory-protocol.md",
+  "specs/protocols/session-close-protocol.md",
+  "specs/protocols/spec-summary-authoring.md",
+  "specs/protocols/destructive-action-checklist.md"
+]);
+
 // spex-console/src/lib/cli/template-manifest.ts
-var TEMPLATE_VERSION = "1.0.0";
 var TODO_NORTH_STAR = `---
 id: HS-L1
 name: TODO \u2014 your product name
@@ -804,7 +1317,7 @@ var TEMPLATE_MANIFEST = [
 ];
 
 // spex-console/src/lib/cli/init.customer-vault.ts
-var DEFAULT_CONSOLE_URL3 = "https://console.heyspex.local";
+var DEFAULT_CONSOLE_URL2 = "https://console.heyspex.local";
 var SCAFFOLD_FOLDERS = [
   "tasks",
   "epics",
@@ -821,23 +1334,63 @@ var SCAFFOLD_FOLDERS = [
   "checks",
   "events"
 ];
+var PLACEHOLDER_FILES = /* @__PURE__ */ new Set([".gitkeep"]);
+function isDir(deps, path2, name) {
+  if (deps.isDirectory) return deps.isDirectory(path2);
+  try {
+    const kids = deps.readdir(path2);
+    return kids.length > 0 || !name.includes(".");
+  } catch {
+    return false;
+  }
+}
+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 defaultVaultName(targetDir) {
   return basename(targetDir) || targetDir;
 }
 function runCustomerVaultInit(args, deps, options = {}) {
   const { targetDir } = args;
   const written = [];
+  const filter = options.manifestFilter ?? (() => true);
+  const rows = TEMPLATE_MANIFEST.filter(filter);
   if (deps.exists(targetDir)) {
-    const entries = deps.readdir(targetDir);
-    if (entries.length > 0) {
+    const markerPresent = deps.exists(deps.joinPath(targetDir, "heyspex.yaml"));
+    if (!markerPresent && deps.readdir(targetDir).length > 0) {
       return {
         code: EXIT.INVALID_ARG,
-        message: `${targetDir} is not empty \u2014 customer-vault init refuses to write into an existing, non-empty directory.`,
+        message: `${targetDir} is not empty \u2014 customer-vault init refuses to write into an existing, non-empty directory that has no heyspex.yaml.`,
         payload: { ok: false, error: "target_not_empty", path: targetDir },
         isError: true,
         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);
   }
@@ -846,19 +1399,37 @@ function runCustomerVaultInit(args, deps, options = {}) {
   for (const folder of SCAFFOLD_FOLDERS) {
     deps.mkdirRecursive(deps.joinPath(specsRoot, folder));
   }
-  const vaultId = mintVaultId();
-  const yamlContent = renderHeyspexYaml({
-    consoleUrl: options.consoleUrl ?? DEFAULT_CONSOLE_URL3,
-    vaultRoot: "specs/",
-    vaultId
-  });
   const heyspexYamlPath = deps.joinPath(targetDir, "heyspex.yaml");
-  deps.writeFile(heyspexYamlPath, yamlContent);
-  written.push(heyspexYamlPath);
-  const filter = options.manifestFilter ?? (() => true);
-  const rows = TEMPLATE_MANIFEST.filter(filter);
+  let vaultId;
+  if (deps.exists(heyspexYamlPath)) {
+    const existingYaml = deps.readFile?.(heyspexYamlPath) ?? null;
+    vaultId = (existingYaml ? parseVaultId(existingYaml) : null) ?? "";
+  } else {
+    vaultId = mintVaultId();
+    deps.writeFile(
+      heyspexYamlPath,
+      renderHeyspexYaml({
+        consoleUrl: options.consoleUrl ?? DEFAULT_CONSOLE_URL2,
+        vaultRoot: "specs/",
+        vaultId
+      })
+    );
+    written.push(heyspexYamlPath);
+  }
+  const readConfigSeed2 = deps.readConfigSeed;
+  const configSeed = seedConfigYaml(
+    targetDir,
+    readConfigSeed2 ? () => readConfigSeed2.call(deps) : void 0,
+    deps
+  );
+  if (configSeed.status === "seeded") written.push(configSeed.path);
+  const rowResults = [];
   for (const row of rows) {
     const destAbs = deps.joinPath(targetDir, ...row.dest.split("/"));
+    if (deps.exists(destAbs)) {
+      rowResults.push({ dest: row.dest, action: "kept" });
+      continue;
+    }
     if (row.classification === "universal-template") {
       const srcAbs = deps.joinPath(deps.platformRoot, ...row.source.split("/"));
       deps.copyFile(srcAbs, destAbs);
@@ -871,6 +1442,7 @@ function runCustomerVaultInit(args, deps, options = {}) {
       deps.writeFile(destAbs, row.content);
     }
     written.push(destAbs);
+    rowResults.push({ dest: row.dest, action: "created" });
   }
   if (options.afterScaffold && options.afterScaffold.length > 0) {
     const ctx = {
@@ -878,22 +1450,28 @@ function runCustomerVaultInit(args, deps, options = {}) {
       vaultName: options.vaultName ?? defaultVaultName(targetDir),
       templateVersion: TEMPLATE_VERSION,
       manifestRows: rows,
+      rows: rowResults,
       deps,
-      recordWrite: (path) => {
-        written.push(path);
+      recordWrite: (path2) => {
+        written.push(path2);
       }
     };
     for (const hook of options.afterScaffold) hook(ctx);
   }
+  const createdCount = rowResults.filter((r) => r.action === "created").length;
+  const keptCount = rowResults.length - createdCount;
   return {
     code: EXIT.OK,
-    message: `Initialized customer vault at ${targetDir} (${written.length} files written, template v${TEMPLATE_VERSION}).`,
+    message: `Initialized customer vault at ${targetDir} (${written.length} files written, ${createdCount} manifest rows created, ${keptCount} kept, template v${TEMPLATE_VERSION}).`,
     payload: {
       ok: true,
       targetDir,
       templateVersion: TEMPLATE_VERSION,
       vaultId,
-      written
+      written,
+      rows: rowResults,
+      created: createdCount,
+      kept: keptCount
     },
     isError: false,
     written
@@ -902,7 +1480,6 @@ function runCustomerVaultInit(args, deps, options = {}) {
 
 // spex-console/src/lib/cli/init-git-finalize.ts
 import { spawnSync } from "node:child_process";
-import { readFileSync as readFileSync3 } from "node:fs";
 var nodeGitRunner = {
   run(args, cwd) {
     const result = spawnSync("git", args, { cwd, encoding: "utf8" });
@@ -929,14 +1506,19 @@ function ensureTemplateVersionLine(content, version) {
 template_version: ${version}
 `;
 }
+function templatePinHook() {
+  return (ctx) => {
+    const yamlPath = ctx.deps.joinPath(ctx.targetDir, "heyspex.yaml");
+    const existingYaml = ctx.deps.readFile?.(yamlPath);
+    if (existingYaml === null || existingYaml === void 0) return;
+    if (readTemplateVersion(existingYaml) === ctx.templateVersion) return;
+    ctx.deps.writeFile(yamlPath, ensureTemplateVersionLine(existingYaml, ctx.templateVersion));
+    ctx.recordWrite(yamlPath);
+  };
+}
 function gitFinalizeHook(runner, notify) {
   return (ctx) => {
     const target = ctx.targetDir;
-    const yamlPath = ctx.deps.joinPath(target, "heyspex.yaml");
-    const existingYaml = readFileSync3(yamlPath, "utf8");
-    const updatedYaml = ensureTemplateVersionLine(existingYaml, ctx.templateVersion);
-    ctx.deps.writeFile(yamlPath, updatedYaml);
-    ctx.recordWrite(yamlPath);
     const probe = runner.run(["--version"], target);
     if (!probe.ok) {
       notify("git not found - vault left uninitialized, run git init yourself");
@@ -1015,6 +1597,7 @@ function principleManifestFilter(selected) {
 }
 function principlesIndexHook(selected, rows) {
   return (ctx) => {
+    if (ctx.rows.some((r) => r.dest === PRINCIPLES_INDEX_DEST && r.action === "kept")) return;
     const indexRow = rows.find((row) => row.dest === PRINCIPLES_INDEX_DEST);
     if (!indexRow || indexRow.content === void 0) {
       throw new Error(
@@ -1031,10 +1614,53 @@ function principlesIndexHook(selected, rows) {
   };
 }
 
+// spex-console/bin/run-entry.ts
+import process2 from "node:process";
+var BinExit = class extends Error {
+  code;
+  constructor(code) {
+    super(`exit ${code}`);
+    this.name = "BinExit";
+    this.code = code;
+  }
+};
+function runEntry(name, main2, options = {}) {
+  const { fallbackCode = 1, unhandledLabel = "unhandled" } = options;
+  void (async () => {
+    try {
+      await main2();
+    } catch (err) {
+      if (err instanceof BinExit) {
+        process2.exitCode = err.code;
+        return;
+      }
+      const message = err instanceof Error ? err.message : String(err);
+      process2.stderr.write(`${name}: ${unhandledLabel}: ${message}
+`);
+      process2.exitCode = fallbackCode;
+    }
+  })();
+}
+
 // spex-console/bin/hs-init.ts
-var INTERACTIVE = process2.stdin.isTTY === true;
+var INTERACTIVE = process3.stdin.isTTY === true;
+var PKG_ROOT = resolve5(
+  resolveCodeRoot({ packageRoot: resolve5(dirname5(fileURLToPath2(import.meta.url)), "..", "..") })
+);
+var CONFIG_SEED_PATH = join9(PKG_ROOT, "vendor", "heyspex-mcp", "config-seed.yaml");
+function readConfigSeed() {
+  try {
+    return readFileSync8(CONFIG_SEED_PATH, "utf8");
+  } catch {
+    process3.stderr.write(
+      `hs init: warning \u2014 config seed template not found at ${CONFIG_SEED_PATH}; .heyspex/config.yaml was not seeded (run \`hs settings set <key> <value>\` to create it).
+`
+    );
+    return null;
+  }
+}
 async function askYesNo(question) {
-  const rl = createInterface({ input: process2.stdin, output: process2.stdout });
+  const rl = createInterface({ input: process3.stdin, output: process3.stdout });
   try {
     const answer = (await rl.question(`${question} `)).trim().toLowerCase();
     return answer === "y" || answer === "yes" || answer === "";
@@ -1047,9 +1673,9 @@ async function resolvePrincipleSelection(principlesFlag) {
     return parsePrinciplesFlag(principlesFlag, TEMPLATE_MANIFEST);
   }
   if (INTERACTIVE) {
-    process2.stdout.write("Select which universal principle docs to ship with this vault:\n");
+    process3.stdout.write("Select which universal principle docs to ship with this vault:\n");
     for (const choice of listPrincipleChoices(TEMPLATE_MANIFEST)) {
-      process2.stdout.write(`  - ${choice.key}: ${choice.summary}
+      process3.stdout.write(`  - ${choice.key}: ${choice.summary}
 `);
     }
     const selected = await promptPrincipleSelection(askYesNo, TEMPLATE_MANIFEST);
@@ -1058,47 +1684,60 @@ async function resolvePrincipleSelection(principlesFlag) {
   return parsePrinciplesFlag(void 0, TEMPLATE_MANIFEST);
 }
 async function main() {
-  const repoRoot = process2.env.HS_VAULT_ROOT ? resolve(process2.env.HS_VAULT_ROOT) : process2.cwd();
-  const parsed = parseInitArgs(process2.argv.slice(3));
+  const repoRoot = process3.env.HS_VAULT_ROOT ? resolve5(process3.env.HS_VAULT_ROOT) : process3.cwd();
+  const parsed = parseInitArgs(process3.argv.slice(3));
   if (parsed.help) {
-    process2.stdout.write(`${HELP}
+    process3.stdout.write(`${HELP}
 `);
-    process2.exit(EXIT.OK);
+    process3.exitCode = EXIT.OK;
+    return;
   }
   if (parsed.error) {
-    process2.stderr.write(`hs init: ${parsed.error.message}
+    process3.stderr.write(`hs init: ${parsed.error.message}
 `);
-    process2.exit(parsed.error.code);
+    process3.exitCode = parsed.error.code;
+    return;
   }
   const args = parsed.args;
   if (args.customerVaultDir) {
-    const here = dirname(fileURLToPath(import.meta.url));
-    const platformRoot = resolve(here, "..", "..");
-    const targetDir = resolve(args.customerVaultDir);
+    const here = dirname5(fileURLToPath2(import.meta.url));
+    const platformRoot = resolve5(here, "..", "..");
+    const targetDir = resolve5(args.customerVaultDir);
     const deps = {
       platformRoot,
-      exists: (p) => existsSync(p),
+      exists: (p) => existsSync4(p),
       readdir: (p) => readdirSync(p),
       mkdirRecursive: (p) => {
-        mkdirSync(p, { recursive: true });
+        mkdirSync4(p, { recursive: true });
       },
-      writeFile: (p, c) => writeFileSync(p, c, "utf8"),
+      writeFile: (p, c) => writeFileSync4(p, c, "utf8"),
       copyFile: (src, dest) => copyFileSync(src, dest),
-      joinPath: (...s) => join3(...s)
+      joinPath: (...s) => join9(...s),
+      readConfigSeed,
+      readFile: (p) => {
+        try {
+          return readFileSync8(p, "utf8");
+        } catch {
+          return null;
+        }
+      },
+      isDirectory: (p) => statSync(p).isDirectory()
     };
     const principlesResult = await resolvePrincipleSelection(args.principles);
     if (!principlesResult.ok) {
-      process2.stderr.write(`hs init: ${principlesResult.message}
+      process3.stderr.write(`hs init: ${principlesResult.message}
 `);
-      process2.exit(EXIT.INVALID_ARG);
+      process3.exitCode = EXIT.INVALID_ARG;
+      return;
     }
     const selected = principlesResult.selected;
     const notices = [];
     const afterScaffold = [
-      customerClaudeMdHook(),
-      principlesIndexHook(selected, TEMPLATE_MANIFEST)
+      customerClaudeMdHook((msg) => notices.push(msg)),
+      principlesIndexHook(selected, TEMPLATE_MANIFEST),
+      templatePinHook()
     ];
-    if (!args.noGit) {
+    if (args.git) {
       afterScaffold.push(gitFinalizeHook(nodeGitRunner, (msg) => notices.push(msg)));
     }
     const result2 = runCustomerVaultInit({ targetDir }, deps, {
@@ -1107,7 +1746,7 @@ async function main() {
       manifestFilter: principleManifestFilter(selected),
       afterScaffold
     });
-    const sink2 = result2.isError ? process2.stderr : process2.stdout;
+    const sink2 = result2.isError ? process3.stderr : process3.stdout;
     if (args.json) {
       sink2.write(`${JSON.stringify({ ...result2.payload, notices })}
 `);
@@ -1117,29 +1756,29 @@ async function main() {
       for (const notice of notices) sink2.write(`${notice}
 `);
     }
-    process2.exit(result2.code);
+    process3.exitCode = result2.code;
+    return;
   }
   const result = runInit(args, {
     repoRoot,
-    fileExists: (p) => existsSync(p),
+    fileExists: (p) => existsSync4(p),
     readFile: (p) => {
       try {
-        return readFileSync4(p, "utf8");
+        return readFileSync8(p, "utf8");
       } catch {
         return null;
       }
     },
-    writeFile: (p, c) => writeFileSync(p, c, "utf8"),
-    joinPath: (...s) => join3(...s)
+    writeFile: (p, c) => writeFileSync4(p, c, "utf8"),
+    joinPath: (...s) => join9(...s),
+    mkdirRecursive: (p) => {
+      mkdirSync4(p, { recursive: true });
+    },
+    readConfigSeed
   });
-  const sink = result.isError ? process2.stderr : process2.stdout;
+  const sink = result.isError ? process3.stderr : process3.stdout;
   sink.write(`${args.json ? JSON.stringify(result.payload) : result.message}
 `);
-  process2.exit(result.code);
+  process3.exitCode = result.code;
 }
-main().catch((err) => {
-  const message = err instanceof Error ? err.message : String(err);
-  process2.stderr.write(`hs init: unhandled: ${message}
-`);
-  process2.exit(EXIT.WRITE_FAILED);
-});
+runEntry("hs init", main, { fallbackCode: EXIT.WRITE_FAILED });