heyspex 0.2.0 → 0.2.1

package/dist/cli/hs-install.mjs

@@ -35,11 +35,26 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
   mod
 ));
 
+// scripts/lib/heyspex-home.mjs
+import { homedir } from "node:os";
+function heyspexHome(env = process.env) {
+  const override = env?.HEYSPEX_HOME;
+  if (typeof override === "string" && override.trim().length > 0) {
+    return override.trim();
+  }
+  return homedir();
+}
+var init_heyspex_home = __esm({
+  "scripts/lib/heyspex-home.mjs"() {
+    "use strict";
+  }
+});
+
 // vendor/heyspex-mcp/credentials.mjs
 import { mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
-import os, { homedir } from "node:os";
+import os, { homedir as homedir2 } from "node:os";
 import { dirname, join, resolve } from "node:path";
-function credentialsFilePath(homeDir = homedir()) {
+function credentialsFilePath(homeDir = heyspexHome()) {
   return join(homeDir, ".heyspex", "credentials.yaml");
 }
 function parseMcpToken(raw) {
@@ -152,14 +167,14 @@ function readLegacyConfigAccountId(read, homeDir) {
   const value = raw?.match(CONFIG_ACCOUNT_ID_RE)?.[1]?.trim() ?? "";
   return value || null;
 }
-function readBearer({ env = process.env, homeDir = homedir(), readFile, accountId } = {}) {
+function readBearer({ env = process.env, homeDir = heyspexHome(), readFile, accountId } = {}) {
   const read = readFile ?? ((p) => readFileSync(p, "utf8"));
   const credentialsText = readTextOrNull(read, credentialsFilePath(homeDir));
   const named = typeof accountId === "string" && accountId.trim() ? accountId.trim() : null;
   const legacyAccountId = named && parseCredentialsStore(credentialsText).schemaVersion === 1 ? readLegacyConfigAccountId(read, homeDir) : null;
   return resolveBearer({ envToken: env?.[MCP_TOKEN_ENV], credentialsText, accountId: named, legacyAccountId });
 }
-function readCurrentAccountId({ homeDir = homedir(), readFile } = {}) {
+function readCurrentAccountId({ homeDir = heyspexHome(), readFile } = {}) {
   const read = readFile ?? ((p) => readFileSync(p, "utf8"));
   const store = parseCredentialsStore(readTextOrNull(read, credentialsFilePath(homeDir)));
   if (store.schemaVersion === 2 && store.currentAccountId && store.currentAccountId !== LEGACY_ACCOUNT_ID) {
@@ -177,6 +192,7 @@ var MCP_TOKEN_ENV, MCP_TOKEN_LINE_RE, CREDENTIALS_SCHEMA_VERSION, LEGACY_ACCOUNT
 var init_credentials = __esm({
   "vendor/heyspex-mcp/credentials.mjs"() {
     "use strict";
+    init_heyspex_home();
     MCP_TOKEN_ENV = "HEYSPEX_MCP_TOKEN";
     MCP_TOKEN_LINE_RE = /^mcp_token:[ \t]*["']?([^"'\r\n#]+)/m;
     CREDENTIALS_SCHEMA_VERSION = 2;
@@ -189,9 +205,9 @@ var init_credentials = __esm({
 
 // 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 { homedir as homedir3 } from "node:os";
 import { join as join2 } from "node:path";
-function devModeFilePath(homeDir = homedir2()) {
+function devModeFilePath(homeDir = heyspexHome()) {
   return join2(homeDir, ".heyspex", DEV_MODE_FILENAME);
 }
 function normalizeMode(raw) {
@@ -216,7 +232,7 @@ function deriveSemantics(mode, reliance) {
     vaultWriteMode: local ? "local" : "cloud"
   };
 }
-function readLocalDevModeRecord({ homeDir = homedir2(), readFile = defaultReadFile } = {}) {
+function readLocalDevModeRecord({ homeDir = heyspexHome(), readFile = defaultReadFile } = {}) {
   let raw;
   try {
     raw = readFile(devModeFilePath(homeDir));
@@ -246,7 +262,7 @@ function readLocalDevModeRecord({ homeDir = homedir2(), readFile = defaultReadFi
 }
 function resolveDevMode({
   env = process.env,
-  homeDir = homedir2(),
+  homeDir = heyspexHome(),
   readFile = defaultReadFile,
   cloudSetting = void 0
 } = {}) {
@@ -309,6 +325,7 @@ var CLOUD_CONSOLE_URL, LOCAL_CONSOLE_URL, DEV_MODE_FILENAME, defaultReadFile;
 var init_dev_mode = __esm({
   "scripts/lib/dev-mode.mjs"() {
     "use strict";
+    init_heyspex_home();
     init_credentials();
     CLOUD_CONSOLE_URL = "https://app.heyspex.com";
     LOCAL_CONSOLE_URL = "http://localhost:3000";
@@ -982,20 +999,21 @@ var require_gray_matter = __commonJS({
 import { spawnSync as spawnSync3 } from "node:child_process";
 import {
   copyFileSync,
-  existsSync as existsSync5,
-  mkdirSync as mkdirSync5,
-  readdirSync,
-  readFileSync as readFileSync10,
+  existsSync as existsSync6,
+  mkdirSync as mkdirSync6,
+  readdirSync as readdirSync2,
+  readFileSync as readFileSync11,
   statSync,
-  writeFileSync as writeFileSync5
+  writeFileSync as writeFileSync6
 } from "node:fs";
-import { join as join11, resolve as resolve5 } from "node:path";
+import { join as join12, resolve as resolve5 } from "node:path";
 import process4 from "node:process";
 
 // scripts/lib/console-url-resolver.mjs
+init_heyspex_home();
 init_dev_mode();
 import { readFileSync as readFileSync3 } from "node:fs";
-import { homedir as homedir3 } from "node:os";
+import { homedir as homedir4 } from "node:os";
 import { join as join3 } from "node:path";
 var DEFAULT_CONSOLE_URL = LOCAL_CONSOLE_URL;
 function trimTrailingSlash(url) {
@@ -1022,7 +1040,7 @@ function warnStaleLoopbackCredentialsOnce(credentialsUrl, derivedUrl, { log }) {
   } catch {
   }
 }
-function readCredentialsConsoleUrl({ homeDir = homedir3(), readFile = defaultReadFile2 } = {}) {
+function readCredentialsConsoleUrl({ homeDir = heyspexHome(), readFile = defaultReadFile2 } = {}) {
   try {
     const raw = readFile(join3(homeDir, ".heyspex", "credentials.yaml"));
     const match = String(raw ?? "").match(/^console_url:\s*["']?([^"'\r\n#]+)/m);
@@ -1066,7 +1084,7 @@ function resolveModeEnvelope({ env, homeDir }) {
 function resolveConsoleUrl({
   repoRoot,
   env = process.env,
-  homeDir = homedir3(),
+  homeDir = heyspexHome(),
   strict = false,
   devMode,
   log = (line) => process.stderr.write(line),
@@ -1136,17 +1154,19 @@ function shellQuote(p) {
 var HS_DISPATCHER_PREFIX = HS_DISPATCHER_PATH ? `node ${shellQuote(HS_DISPATCHER_PATH)}` : HS_BIN_NAME;
 
 // vendor/heyspex-mcp/console-fetch.mjs
+init_heyspex_home();
 init_credentials();
-import { readFileSync as readFileSync6 } from "node:fs";
-import { homedir as homedir6 } from "node:os";
-import { join as join7 } from "node:path";
+import { readFileSync as readFileSync7 } from "node:fs";
+import { homedir as homedir7 } from "node:os";
+import { join as join8 } from "node:path";
 
 // vendor/heyspex-mcp/session-owner.mjs
+init_heyspex_home();
 init_credentials();
 import { readFileSync as readFileSync4 } from "node:fs";
-import { homedir as homedir4 } from "node:os";
+import { homedir as homedir5 } from "node:os";
 import { join as join5 } from "node:path";
-function resolveSessionOwnerUncached({ env = process.env, homeDir = homedir4(), readFile } = {}) {
+function resolveSessionOwnerUncached({ env = process.env, homeDir = heyspexHome(), readFile } = {}) {
   const fromEnv = typeof env?.HS_ACCOUNT_ID === "string" ? env.HS_ACCOUNT_ID.trim() : "";
   if (fromEnv) return fromEnv;
   return readCurrentAccountId({ homeDir, readFile });
@@ -1176,10 +1196,23 @@ function isVaultLessEndpoint(method, path5) {
   });
 }
 
+// vendor/heyspex-mcp/write-outbox.mjs
+import {
+  readdirSync,
+  readFileSync as readFileSync5,
+  writeFileSync as writeFileSync3,
+  mkdirSync as mkdirSync3,
+  existsSync as existsSync2,
+  renameSync as renameSync2,
+  rmSync
+} from "node:fs";
+import { basename, join as join6, isAbsolute as isAbsolute2 } from "node:path";
+
 // 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";
+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";
 
 // vendor/heyspex-mcp/console-fetch.mjs
 var SCOPE_REFUSAL_CODES = Object.freeze(["VAULT_SCOPE_MISMATCH", "ACCOUNT_MISMATCH", "VAULT_NOT_REGISTERED"]);
@@ -1188,9 +1221,18 @@ 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 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";
+import { existsSync as existsSync4, mkdirSync as mkdirSync4, readFileSync as readFileSync8, renameSync as renameSync3, writeFileSync as writeFileSync4 } 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";
+function heyspexHome2(env = process.env) {
+  const override = env?.HEYSPEX_HOME;
+  if (typeof override === "string" && override.trim().length > 0) {
+    return override.trim();
+  }
+  return homedir8();
+}
 
 // spex-console/src/lib/vault-registry/types.ts
 var LEGACY_REGISTRY_ACCOUNT_ID = "legacy";
@@ -1207,10 +1249,10 @@ function emptyVaultRegistry() {
 
 // spex-console/src/lib/vault-registry/registry-file.ts
 function vaultRegistryDir(opts = {}) {
-  return opts.registryDir ?? join8(homedir7(), ".heyspex");
+  return opts.registryDir ?? join9(heyspexHome2(), ".heyspex");
 }
 function vaultRegistryFilePath(opts = {}) {
-  return join8(vaultRegistryDir(opts), "registry.json");
+  return join9(vaultRegistryDir(opts), "registry.json");
 }
 function isNonEmptyString(v) {
   return typeof v === "string" && v.trim().length > 0;
@@ -1311,9 +1353,9 @@ function parseVaultRegistryFile(json) {
 }
 function readRegistryJson(opts) {
   const filePath = vaultRegistryFilePath(opts);
-  if (!existsSync3(filePath)) return { kind: "missing" };
+  if (!existsSync4(filePath)) return { kind: "missing" };
   try {
-    const raw = readFileSync7(filePath, "utf8");
+    const raw = readFileSync8(filePath, "utf8");
     const json = JSON.parse(raw);
     if (registryFileSchemaOf(json) === null) return { kind: "unreadable" };
     return { kind: "ok", raw, json };
@@ -1374,7 +1416,7 @@ function samePathLoose(a, b) {
 }
 function assertNotRealHomeRegistryUnderTest(filePath) {
   if (!underTestRunner()) return;
-  if (samePathLoose(dirname4(filePath), join8(homedir7(), ".heyspex"))) {
+  if (samePathLoose(dirname4(filePath), join9(heyspexHome2(), ".heyspex"))) {
     throw new Error(
       `registry-file: refusing to write ${filePath} under a test runner \u2014 that is the real ~/.heyspex registry. Pass opts.registryDir (a temp dir).`
     );
@@ -1383,10 +1425,10 @@ function assertNotRealHomeRegistryUnderTest(filePath) {
 function writeVaultRegistry(registry, opts = {}) {
   const filePath = vaultRegistryFilePath(opts);
   assertNotRealHomeRegistryUnderTest(filePath);
-  mkdirSync3(dirname4(filePath), { recursive: true });
+  mkdirSync4(dirname4(filePath), { recursive: true });
   const tmpPath = `${filePath}.tmp`;
-  writeFileSync3(tmpPath, serializeVaultRegistry(registry), "utf8");
-  renameSync2(tmpPath, filePath);
+  writeFileSync4(tmpPath, serializeVaultRegistry(registry), "utf8");
+  renameSync3(tmpPath, filePath);
 }
 function isValidId(id) {
   if (!isNonEmptyString(id)) return false;
@@ -1585,7 +1627,7 @@ function withCloudScope(deps, accountId, vaultId) {
 }
 
 // spex-console/src/lib/cli/install.ts
-import { homedir as homedir10 } from "node:os";
+import { isAbsolute as isAbsolute3, resolve as resolveNodePath2 } from "node:path";
 
 // scripts/install-cursor-hooks.mjs
 import fs2 from "node:fs";
@@ -1602,10 +1644,13 @@ var HOOKS = [
   { event: "sessionStart", hook: "wip-checkpoint", why: "Surface the previous session WIP handoff before work resumes." },
   { event: "sessionStart", hook: "inject-dev-server-awareness", why: "Once-per-session reminder that dev-server status is a tool call, not a guess." },
   { event: "sessionStart", hook: "inject-coo-seat", why: "Inject the dev-factory COO seat mandate when the COO window is open." },
+  { event: "sessionStart", hook: "inject-doctrine", why: "Inject the baseline SpexCode Doctrine edition at session start." },
   { event: "sessionStart", hook: "coo-guard-check", why: "Warn at session start when a breakdown has not been delegated." },
   { event: "sessionStart", hook: "check-auto-memory-budget", why: "Self-heal and budget-check the auto-memory index." },
   { event: "sessionStart", hook: "check-claude-md-budget", why: "Advisory budget check on the always-loaded agent contract." },
   { event: "sessionStart", hook: "check-mcp-freshness-hook", why: "Warn when the running MCP server is stale versus vendor." },
+  { event: "sessionStart", hook: "git-reflog-audit", why: "Session-start git audit (stash/reset/rebase witness)." },
+  { event: "sessionStart", hook: "vault-mirror-catchup", why: "Cloud write mode: detached hs pull --apply closes a stale disk mirror (HS-XJFQ)." },
   // ── Compaction ──────────────────────────────────────────────────────────
   // Claude re-runs SessionStart(source: compact) after compaction; Cursor fires
   // preCompact BEFORE it, so the shim relays this one as SessionStart(compact)
@@ -1619,6 +1664,7 @@ var HOOKS = [
   { event: "beforeSubmitPrompt", hook: "preflight-reminder", why: "Name the required procedure before a filing/destructive/protocol turn." },
   { event: "beforeSubmitPrompt", hook: "intent-classifier-trigger", why: "Route capture / research / settings / defer intents to the right skill." },
   { event: "beforeSubmitPrompt", hook: "inject-communication-style", why: "Re-assert the plain-language communication rules each turn." },
+  { event: "beforeSubmitPrompt", hook: "inject-vault-context", timeout: 10, why: "Lexical vault retrieval for the prompt (surfaced as a user message)." },
   // ── Before every tool call (any tool) ───────────────────────────────────
   { event: "preToolUse", matcher: ".*", hook: "emit-claim-status", args: ["--event=PreToolUse"], why: "Claim liveness heartbeat to the console." },
   { event: "preToolUse", matcher: ".*", hook: "coo-denylist-gate", why: "Hard deny the COO-window deny list." },
@@ -1629,21 +1675,27 @@ var HOOKS = [
   // the vault guard because removing a profile file is the loss it exists to
   // prevent, and Claude had no separate delete tool to list.
   { event: "preToolUse", matcher: "Write|Delete", hook: "env-vault-guard", why: "Block destructive writes to the encrypted env vault (ALWAYS ON)." },
+  { event: "preToolUse", matcher: "Write", hook: "vault-write-tier-guard", why: "Deny disk writes to vault specs in cloud write mode (HS-FCNH)." },
   { event: "preToolUse", matcher: "Write", hook: "settings-write-gate", why: "Require approval before .heyspex/config.yaml changes." },
   { event: "preToolUse", matcher: "Write", hook: "enforce-vault-naming", why: "Block vault filenames that violate the naming registry." },
   { event: "preToolUse", matcher: "Write", hook: "guard-auto-memory-writes", why: "Block new topic files in the auto-memory directory." },
   { event: "preToolUse", matcher: "Write", hook: "preflight-reminder", why: "Preflight reminder on the edit path itself." },
   { event: "preToolUse", matcher: "Write", hook: "claim-before-code-gate", why: "Deny the first code edit after plan exit with no claim." },
+  { event: "preToolUse", matcher: "Write", hook: "directive-obligation-gate", why: "Deny product-code writes while a capture_on_idea obligation is unmet, and (claim-before-build) with no claim/capture (HS-20SW)." },
   // ── Before a shell command ──────────────────────────────────────────────
   // beforeShellExecution, not preToolUse/Shell: it is the only event guaranteed
   // to carry the command string, and Cursor honors allow/deny/ask on it.
   { event: "beforeShellExecution", hook: "env-vault-guard", why: "Block shell writes/exfiltration targeting the env vault (ALWAYS ON)." },
+  { event: "beforeShellExecution", hook: "vault-write-tier-guard", why: "Deny shell writes to vault specs in cloud write mode (HS-FCNH)." },
   { event: "beforeShellExecution", hook: "settings-write-gate", why: "Catch shell writes to .heyspex/config.yaml." },
   { event: "beforeShellExecution", hook: "enforce-vault-naming", why: "Catch vault files created via the shell." },
   { event: "beforeShellExecution", hook: "guard-auto-memory-writes", why: "Catch auto-memory topic files created via the shell." },
   { event: "beforeShellExecution", hook: "preflight-reminder", why: "Preflight reminder on rm -rf / force-push shaped commands." },
   { event: "beforeShellExecution", hook: "dev-server-task-reminder", timeout: 10, why: "Dev-server start/stop hard gate plus DB-safety reminder." },
   { event: "beforeShellExecution", hook: "git-stash-gate", timeout: 10, why: "Always ask before a mutating git stash." },
+  { event: "beforeShellExecution", hook: "git-identity-guard", why: "Agents never write git identity (owner ruling 2026-09-19, ALWAYS ON)." },
+  { event: "beforeShellExecution", hook: "capture-execution-gate", why: "Block dev-factory research/paid-model/routing shell commands past an ungrounded capture (HS-KNJ8, platform)." },
+  { event: "beforeShellExecution", hook: "directive-obligation-gate", why: "Deny build commands and product-code shell writes while a capture obligation is unmet (HS-20SW)." },
   // ── Before specific MCP tools ───────────────────────────────────────────
   // Cursor fires preToolUse for MCP tools too (matcher `MCP:<name>`), so these
   // stay on preToolUse rather than beforeMCPExecution — registering both would
@@ -1653,15 +1705,20 @@ var HOOKS = [
   { event: "preToolUse", matcher: ".*", tool: "heyspex_file_spec$", hook: "capture-workflow-gate", timeout: 8, why: "Deny filing an implementation spec straight out of an open capture." },
   { event: "preToolUse", matcher: ".*", tool: "heyspex_settings_set$", hook: "settings-write-gate", why: "Require approval for settings changes made through MCP." },
   { event: "preToolUse", matcher: ".*", tool: "[Nn]eon__(prepare_database_migration|complete_database_migration|reset_from_parent|delete_branch)$", hook: "dev-server-task-reminder", timeout: 10, why: "DB-safety gate on Neon migration/reset/delete tools." },
+  { event: "preToolUse", matcher: ".*", tool: "heyspex_file_spec$", hook: "diagnose-capture-reminder", why: "Warn when a diagnose is filed with no capture holding the owner words (HS-IK2D)." },
+  { event: "preToolUse", matcher: ".*", tool: "^(Workflow|Skill)$", hook: "research-method-guard", why: "Research method guard on Skill/Workflow launches (HS-EN4F, ALWAYS ON)." },
   { event: "preToolUse", matcher: ".*", tool: "^(Workflow|Skill)$", hook: "deep-research-cost-gate", why: "Cost confirmation before a paid deep-research harness launch." },
   { event: "preToolUse", matcher: ".*", tool: "^(WebSearch|WebFetch|web_search|web_fetch)$|heyspex_save_research$", hook: "research-protocol-gate", why: "WebSearch/WebFetch/save_research refused until the research preflight ran (HS-K0ZP, HS-EN4F)." },
   // ── Before a subagent spawn ─────────────────────────────────────────────
   // subagentStart over preToolUse/Task: it carries subagent_type and the model,
   // which is exactly what the routing gate decides on, and it can deny.
   { event: "subagentStart", hook: "agent-spawn-delegation-gate", why: "Block a build/breakdown/critic subagent on an off-routing model." },
+  { event: "subagentStart", hook: "capture-execution-gate", why: "Block a dev-factory subagent spawn past an ungrounded capture (HS-KNJ8, platform)." },
+  { event: "subagentStart", hook: "directive-obligation-gate", why: "Deny a build subagent while a capture obligation is unmet or the session has no claim/capture (HS-20SW)." },
   // ── After every tool call ───────────────────────────────────────────────
   { event: "postToolUse", matcher: ".*", hook: "emit-claim-status", args: ["--event=PostToolUse"], why: "Claim liveness heartbeat after the call resolves." },
   { event: "postToolUse", matcher: ".*", hook: "log-session-activity", args: ["--event=PostToolUse"], why: "Append the tool result row to the session log." },
+  { event: "postToolUse", matcher: ".*", hook: "directive-obligation-gate", why: "Discharge the capture obligation on a capture write; track claim acquire/release (HS-20SW)." },
   { event: "postToolUse", matcher: ".*", hook: "close-terminal-on-ship", why: "Close the Launch terminal once the spec ships." },
   { event: "postToolUse", matcher: "Write", hook: "notify-status-flip", why: "Sound on an in_review status flip." },
   { event: "postToolUse", matcher: "Write", hook: "scripts/stamp-provenance-on-edit.mjs", why: "Stamp assisted_by provenance on direct spec edits." },
@@ -1674,7 +1731,11 @@ var HOOKS = [
   // hook re-drives the agent — the same effect as Claude's exit-2 block.
   { event: "stop", hook: "emit-claim-status", args: ["--event=Stop"], why: "Mark the claim pending-on-response." },
   { event: "stop", hook: "naughty-list-gate", why: "Re-drive the turn when the final message uses banned jargon." },
+  { event: "stop", hook: "id-display-format-gate", why: "Re-drive the turn when a reply breaks the Naming V3 display-id format." },
+  { event: "stop", hook: "epic-milestone-phrasing-gate", why: "Re-drive the turn when a reply breaks the epic/milestone phrasing rules." },
+  { event: "stop", hook: "git-reflog-audit", why: "Session-close git audit backstop (stash/reset/rebase witness)." },
   { event: "stop", hook: "enforce-session-sequence", why: "Re-drive the turn when work shipped without record_wip." },
+  { event: "stop", hook: "directive-obligation-gate", why: "Re-drive the turn ONCE (followup_message) when a capture obligation is still unmet (HS-20SW)." },
   // ── Session end ─────────────────────────────────────────────────────────
   { event: "sessionEnd", hook: "session-end", why: "Release the claim and notify the console." },
   { event: "sessionEnd", hook: "close-terminal-on-ship", why: "Final terminal cleanup." }
@@ -1718,7 +1779,134 @@ function timeoutFor(entry) {
 import { createHash } from "node:crypto";
 import fs from "node:fs";
 import path2 from "node:path";
+import os2 from "node:os";
 import { fileURLToPath as fileURLToPath2, pathToFileURL } from "node:url";
+
+// scripts/lib/hook-dispositions.mjs
+var HOSTS = Object.freeze(["claude-code", "cursor", "copilot"]);
+var DISPOSITIONS = Object.freeze(["mapped", "advisory-degraded", "unportable", "not-shipped"]);
+var mapped = (note) => Object.freeze({ disposition: "mapped", ...note ? { note } : {} });
+var degraded = (note) => Object.freeze({ disposition: "advisory-degraded", note });
+var unportable = (control) => Object.freeze({ disposition: "unportable", control });
+var notShipped = Object.freeze({ disposition: "not-shipped" });
+var CC = mapped();
+var COPILOT_PROMPT_DROPPED = "Copilot drops command-hook output on userPromptSubmitted (no prompt-time context channel); the text moves to sessionStart / .github/copilot-instructions.md.";
+var CURSOR_PROMPT_USER_MESSAGE = "Cursor beforeSubmitPrompt honors user_message only (no additional_context): the text surfaces in the transcript instead of as invisible context.";
+var COPILOT_NO_PLAN_TOOL = "MCP preflight refusals (heyspex_claim_spec / heyspex_submit_for_review / heyspex_save_research) + .github/copilot-instructions.md plan rule (state the plan in chat, claim the spec before editing) + HS-20SW directive-obligation-gate claim-before-build deny";
+var HOOK_DISPOSITIONS = Object.freeze({
+  // ── customer: session start / compaction ──────────────────────────────────
+  "wip-checkpoint": {
+    "claude-code": CC,
+    cursor: mapped("preCompact is relayed as SessionStart(compact)."),
+    copilot: mapped("sessionStart additionalContext is delivered; the preCompact leg writes WIP only (no output channel), re-injected at the next sessionStart.")
+  },
+  "inject-doctrine": { "claude-code": CC, cursor: mapped(), copilot: mapped("sessionStart additionalContext.") },
+  "check-auto-memory-budget": { "claude-code": CC, cursor: mapped(), copilot: mapped("sessionStart additionalContext.") },
+  "check-claude-md-budget": { "claude-code": CC, cursor: mapped(), copilot: mapped("sessionStart additionalContext.") },
+  "git-reflog-audit": { "claude-code": CC, cursor: mapped(), copilot: mapped("sessionStart additionalContext and agentStop.") },
+  "vault-mirror-catchup": { "claude-code": CC, cursor: mapped(), copilot: mapped("Detached side effect on sessionStart.") },
+  // ── customer: every user turn ─────────────────────────────────────────────
+  "preflight-reminder": {
+    "claude-code": CC,
+    cursor: degraded(CURSOR_PROMPT_USER_MESSAGE),
+    copilot: degraded(`${COPILOT_PROMPT_DROPPED} Real enforcement is the MCP preflight refusal.`)
+  },
+  "intent-classifier-trigger": {
+    "claude-code": CC,
+    cursor: degraded(CURSOR_PROMPT_USER_MESSAGE),
+    copilot: degraded(
+      `${COPILOT_PROMPT_DROPPED} The hook still runs and arms obligation state; the HS-20SW directive-obligation-gate turns that state into a hard deny.`
+    )
+  },
+  "inject-communication-style": {
+    "claude-code": CC,
+    cursor: degraded(CURSOR_PROMPT_USER_MESSAGE),
+    copilot: degraded(COPILOT_PROMPT_DROPPED)
+  },
+  "inject-vault-context": {
+    "claude-code": CC,
+    cursor: degraded(CURSOR_PROMPT_USER_MESSAGE),
+    copilot: degraded(`${COPILOT_PROMPT_DROPPED} Per-prompt vault retrieval has no Copilot channel at all.`)
+  },
+  // ── customer: before a tool call (hard gates) ─────────────────────────────
+  "git-identity-guard": { "claude-code": CC, cursor: mapped("beforeShellExecution. Always on."), copilot: mapped("preToolUse on bash/powershell. Always on.") },
+  "vault-write-tier-guard": { "claude-code": CC, cursor: mapped(), copilot: mapped("preToolUse on create/edit/bash/powershell.") },
+  "settings-write-gate": { "claude-code": CC, cursor: mapped(), copilot: mapped("preToolUse on create/edit/bash/powershell and the MCP settings tool.") },
+  "emit-claim-status": { "claude-code": CC, cursor: mapped(), copilot: mapped("Telemetry on preToolUse/postToolUse/agentStop; the cloud agent needs a network allow rule for the console.") },
+  "enforce-vault-naming": { "claude-code": CC, cursor: mapped(), copilot: mapped("preToolUse on create/bash/powershell.") },
+  "guard-auto-memory-writes": { "claude-code": CC, cursor: mapped(), copilot: mapped("preToolUse on create/bash/powershell.") },
+  "directive-obligation-gate": {
+    "claude-code": CC,
+    cursor: mapped(),
+    copilot: mapped("HS-20SW: hard deny on task/create/edit/write-shaped shell while a capture obligation is unmet; the only hard capture-on-idea guarantee on Copilot.")
+  },
+  "claim-before-code-gate": {
+    "claude-code": CC,
+    cursor: degraded("Armed only by plan-exit-ingest-gate, which has no Cursor trigger, so it stays dormant; covered by the HS-20SW claim-before-build rule."),
+    copilot: degraded("Armed only by plan-exit-ingest-gate, which has no Copilot trigger (no ExitPlanMode tool), so it stays dormant; covered by the HS-20SW claim-before-build rule.")
+  },
+  "capture-workflow-gate": {
+    "claude-code": CC,
+    cursor: mapped(),
+    copilot: mapped("preToolUse on the MCP heyspex_file_spec tool; MCP tool naming in hook payloads is unverified live (matched by suffix).")
+  },
+  "diagnose-capture-reminder": {
+    "claude-code": CC,
+    cursor: mapped("preToolUse agent_message delivers the reminder."),
+    copilot: degraded("Copilot preToolUse has no context channel for an inject, so this advisory is silent (lost).")
+  },
+  "git-stash-gate": {
+    "claude-code": CC,
+    cursor: mapped(),
+    copilot: mapped('The Claude "ask" becomes a deny where no user is present (cloud agent, CLI autopilot).')
+  },
+  "research-protocol-gate": { "claude-code": CC, cursor: mapped("Always on."), copilot: mapped("preToolUse on web_fetch/web_search and the MCP save_research tool. Always on; the MCP refusal duplicates it.") },
+  "research-method-guard": {
+    "claude-code": CC,
+    cursor: mapped("preToolUse with a Skill|Workflow tool filter. Always on."),
+    copilot: unportable("MCP preflight refusal on heyspex_save_research (hard floor, hook-independent) + .github/copilot-instructions.md research rule; Copilot has no Skill or Workflow tool to hook.")
+  },
+  "deep-research-cost-gate": {
+    "claude-code": CC,
+    cursor: mapped("preToolUse with a Workflow|Skill tool filter."),
+    copilot: unportable("MCP preflight refusal on heyspex_save_research + .github/copilot-instructions.md cost-confirmation rule; Copilot has no Skill or Workflow tool to hook.")
+  },
+  "plan-review-gate": {
+    "claude-code": CC,
+    cursor: unportable(".cursor/rules/plan-review-required.mdc (always-on rule)"),
+    copilot: unportable(COPILOT_NO_PLAN_TOOL)
+  },
+  "plan-exit-ingest-gate": {
+    "claude-code": CC,
+    cursor: unportable(".cursor/rules/plan-review-required.mdc + spec-creation-linkage.mdc"),
+    copilot: unportable(COPILOT_NO_PLAN_TOOL)
+  },
+  // ── customer: end of turn / session ───────────────────────────────────────
+  "naughty-list-gate": { "claude-code": CC, cursor: mapped("stop followup_message re-drive."), copilot: mapped('agentStop {decision:"block"} re-drive, capped at 8 consecutive blocks.') },
+  "id-display-format-gate": { "claude-code": CC, cursor: mapped("stop followup_message re-drive."), copilot: mapped("agentStop re-drive; reads the transcript (format is not a stable API).") },
+  "epic-milestone-phrasing-gate": { "claude-code": CC, cursor: mapped("stop followup_message re-drive."), copilot: mapped("agentStop re-drive; reads the transcript (format is not a stable API).") },
+  "enforce-session-sequence": { "claude-code": CC, cursor: mapped("stop followup_message re-drive."), copilot: mapped("agentStop re-drive, capped at 8 consecutive blocks.") },
+  "notify-status-flip": { "claude-code": CC, cursor: mapped(), copilot: mapped("Side effect on postToolUse.") },
+  "close-terminal-on-ship": { "claude-code": CC, cursor: mapped(), copilot: mapped("Side effect on postToolUse / sessionEnd.") },
+  "scripts/stamp-provenance-on-edit.mjs": { "claude-code": CC, cursor: mapped(), copilot: mapped("Side effect on postToolUse.") },
+  "session-end": { "claude-code": CC, cursor: mapped(), copilot: mapped("sessionEnd.") },
+  // ── platform: heyspex-app development machinery (never installed in a customer repo) ──
+  "inject-dev-server-awareness": { "claude-code": CC, cursor: mapped(), copilot: notShipped },
+  "inject-coo-seat": { "claude-code": CC, cursor: mapped(), copilot: notShipped },
+  "coo-guard-check": { "claude-code": CC, cursor: mapped(), copilot: notShipped },
+  "coo-denylist-gate": { "claude-code": CC, cursor: mapped(), copilot: notShipped },
+  "agent-spawn-delegation-gate": { "claude-code": CC, cursor: mapped("subagentStart."), copilot: notShipped },
+  "capture-execution-gate": { "claude-code": CC, cursor: mapped("beforeShellExecution + subagentStart."), copilot: notShipped },
+  "check-mcp-freshness-hook": { "claude-code": CC, cursor: mapped(), copilot: notShipped },
+  "dev-server-task-reminder": { "claude-code": CC, cursor: mapped(), copilot: notShipped },
+  "env-vault-guard": { "claude-code": CC, cursor: mapped("Always on."), copilot: notShipped },
+  "log-session-activity": { "claude-code": CC, cursor: mapped(), copilot: notShipped }
+});
+function dispositionFor(hook, host) {
+  return HOOK_DISPOSITIONS[hook]?.[host] ?? null;
+}
+
+// scripts/lib/customer-kit.mjs
 var HOOK_SCOPES = Object.freeze({
   // ── customer: vault / workflow / safety gates ─────────────────────────────
   "wip-checkpoint": { scope: "customer", why: "Previous-session WIP handoff, read from the active vault." },
@@ -1734,6 +1922,7 @@ var HOOK_SCOPES = Object.freeze({
   "inject-communication-style": { scope: "customer", why: "Plain-language communication rules each turn." },
   "inject-vault-context": { scope: "customer", why: "Lexical vault retrieval for the prompt." },
   "git-identity-guard": { scope: "customer", why: "Agents never write git identity (owner ruling 2026-09-19)." },
+  "vault-write-tier-guard": { scope: "customer", why: "Cloud write mode: disk edits to vault specs are a mirror the console never reads back (HS-FCNH)." },
   "settings-write-gate": { scope: "customer", why: "Approval before the vault's .heyspex/config.yaml changes." },
   "emit-claim-status": { scope: "customer", why: "Claim liveness heartbeat to the console." },
   "enforce-vault-naming": { scope: "customer", why: "Naming V3 filename guard (HS-RY2N)." },
@@ -1741,7 +1930,10 @@ var HOOK_SCOPES = Object.freeze({
   "plan-review-gate": { scope: "customer", why: "Plan review + QC markers before ExitPlanMode." },
   "plan-exit-ingest-gate": { scope: "customer", why: "Plan ingest on ExitPlanMode; arms claim-before-code." },
   "claim-before-code-gate": { scope: "customer", why: "First code edit after plan exit needs a claim." },
+  "directive-obligation-gate": { scope: "customer", why: "A capture_on_idea directive leaves a durable obligation; an unmet one denies sub-agent spawns, product-code writes and builds, and re-drives Stop once. Also claim-before-build (HS-20SW)." },
   "capture-workflow-gate": { scope: "customer", why: "No implementation spec straight out of an open capture." },
+  "vault-mirror-catchup": { scope: "customer", why: "Cloud write mode: a SessionStart detached `hs pull --apply` closes a stale disk mirror before the first tool call (HS-XJFQ)." },
+  "diagnose-capture-reminder": { scope: "customer", why: "Warn when a diagnose is filed with no capture holding the owner's words (HS-IK2D)." },
   "git-stash-gate": { scope: "customer", why: "Always ask before a mutating git stash." },
   "research-method-guard": { scope: "customer", why: "Research method guard (HS-EN4F)." },
   "deep-research-cost-gate": { scope: "customer", why: "Cost confirmation before a paid deep-research launch." },
@@ -1760,6 +1952,7 @@ var HOOK_SCOPES = Object.freeze({
   "coo-guard-check": { scope: "platform", why: "dev-factory breakdown-delegation guard." },
   "coo-denylist-gate": { scope: "platform", why: "dev-factory COO window deny list." },
   "agent-spawn-delegation-gate": { scope: "platform", why: "dev-factory seat routing for subagents." },
+  "capture-execution-gate": { scope: "platform", why: "Blocks dev-factory research/paid-model/routing surfaces past an ungrounded capture (HS-KNJ8)." },
   "check-mcp-freshness-hook": { scope: "platform", why: "Freshness of the vendored MCP build \u2014 a platform-dev concern." },
   "dev-server-task-reminder": { scope: "platform", why: "spex-console dev server + Neon DB safety." },
   "env-vault-guard": { scope: "platform", why: "Guards heyspex-app's encrypted env vault paths." },
@@ -1778,6 +1971,7 @@ var CLAUDE_HOOK_ROWS = Object.freeze([
   { event: "SessionStart", hook: "check-claude-md-budget", timeout: 5 },
   { event: "SessionStart", hook: "check-mcp-freshness-hook", timeout: 5 },
   { event: "SessionStart", hook: "git-reflog-audit", timeout: 5 },
+  { event: "SessionStart", hook: "vault-mirror-catchup", timeout: 5 },
   { event: "PreCompact", hook: "wip-checkpoint", timeout: 5 },
   { event: "UserPromptSubmit", hook: "preflight-reminder", timeout: 5 },
   { event: "UserPromptSubmit", hook: "intent-classifier-trigger", timeout: 5 },
@@ -1785,10 +1979,13 @@ var CLAUDE_HOOK_ROWS = Object.freeze([
   { event: "UserPromptSubmit", hook: "inject-vault-context", timeout: 10 },
   { event: "PreToolUse", matcher: "Write|Edit|MultiEdit|NotebookEdit|Bash|PowerShell", hook: "env-vault-guard", timeout: 5 },
   { event: "PreToolUse", matcher: "Bash|PowerShell", hook: "git-identity-guard", timeout: 5 },
+  { event: "PreToolUse", matcher: "Write|Edit|MultiEdit|NotebookEdit|Bash|PowerShell", hook: "vault-write-tier-guard", timeout: 5 },
   { event: "PreToolUse", matcher: "Write|Edit|NotebookEdit|Bash|PowerShell|mcp__heyspex__heyspex_settings_set", hook: "settings-write-gate", timeout: 5 },
   { event: "PreToolUse", matcher: ".*", hook: "emit-claim-status", args: ["--event=PreToolUse"], timeout: 5 },
   { event: "PreToolUse", matcher: ".*", hook: "coo-denylist-gate", timeout: 5 },
   { event: "PreToolUse", matcher: "Agent|Task", hook: "agent-spawn-delegation-gate", timeout: 5 },
+  { event: "PreToolUse", matcher: "Bash|PowerShell|Agent|Task", hook: "capture-execution-gate", timeout: 5 },
+  { event: "PreToolUse", matcher: "Agent|Task|Edit|Write|MultiEdit|NotebookEdit|Bash|PowerShell", hook: "directive-obligation-gate", timeout: 5 },
   { event: "PreToolUse", matcher: "mcp__heyspex__heyspex_claim_spec", hook: "coo-guard-check", timeout: 5 },
   { event: "PreToolUse", matcher: "Write|NotebookEdit|Bash|PowerShell", hook: "enforce-vault-naming", timeout: 5 },
   { event: "PreToolUse", matcher: "Write|NotebookEdit|Bash|PowerShell", hook: "guard-auto-memory-writes", timeout: 5 },
@@ -1797,6 +1994,7 @@ var CLAUDE_HOOK_ROWS = Object.freeze([
   { event: "PreToolUse", matcher: "ExitPlanMode", hook: "plan-exit-ingest-gate", timeout: 5 },
   { event: "PreToolUse", matcher: "Edit|MultiEdit|Write", hook: "claim-before-code-gate", timeout: 5 },
   { event: "PreToolUse", matcher: "mcp__heyspex__heyspex_file_spec", hook: "capture-workflow-gate", timeout: 8 },
+  { event: "PreToolUse", matcher: "mcp__heyspex__heyspex_file_spec", hook: "diagnose-capture-reminder", timeout: 5 },
   { event: "PreToolUse", matcher: "Bash|PowerShell|mcp__neon__prepare_database_migration|mcp__neon__complete_database_migration|mcp__neon__reset_from_parent|mcp__neon__delete_branch|mcp__Neon__prepare_database_migration|mcp__Neon__complete_database_migration|mcp__Neon__reset_from_parent|mcp__Neon__delete_branch", hook: "dev-server-task-reminder", timeout: 10 },
   { event: "PreToolUse", matcher: "Bash|PowerShell", hook: "git-stash-gate", timeout: 10 },
   { event: "PreToolUse", matcher: "Skill|Workflow", hook: "research-method-guard", timeout: 5 },
@@ -1809,7 +2007,9 @@ var CLAUDE_HOOK_ROWS = Object.freeze([
   { event: "Stop", hook: "epic-milestone-phrasing-gate", timeout: 5 },
   { event: "Stop", hook: "git-reflog-audit", timeout: 5 },
   { event: "Stop", hook: "enforce-session-sequence", timeout: 5 },
+  { event: "Stop", hook: "directive-obligation-gate", timeout: 5 },
   { event: "PostToolUse", matcher: ".*", hook: "emit-claim-status", args: ["--event=PostToolUse"], timeout: 5 },
+  { event: "PostToolUse", matcher: "Skill|mcp__heyspex__heyspex_update_capture|mcp__heyspex__heyspex_promote_capture.*|mcp__heyspex__heyspex_file_spec|mcp__heyspex__heyspex_claim_spec|mcp__heyspex__heyspex_release_spec|mcp__heyspex__heyspex_defer_spec", hook: "directive-obligation-gate", timeout: 5 },
   { event: "PostToolUse", matcher: "Edit|Write|MultiEdit", hook: "notify-status-flip", timeout: 5 },
   { event: "PostToolUse", matcher: "Edit|Write|MultiEdit", hook: "close-terminal-on-ship", timeout: 5 },
   { event: "PostToolUse", matcher: "Edit|Write|MultiEdit", hook: "scripts/stamp-provenance-on-edit.mjs", timeout: 5 },
@@ -1894,9 +2094,22 @@ var CUSTOMER_LAUNCHERS = Object.freeze({
 });
 function customerRunnerPrefix(_platformRoot, surface = "claude") {
   const l = CUSTOMER_LAUNCHERS[surface];
+  if (surface === "claude") return CUSTOMER_RUNNER_PREFIX;
   return `node "$${l.projectDirEnv}/${l.rel.join("/")}"`;
 }
-var PLUGIN_RUNNER_PREFIX = 'node "${CLAUDE_PLUGIN_ROOT}/bin/run-hook.mjs"';
+var BOOTSTRAP_WALK = "var d=process.cwd(),r=e.CLAUDE_PROJECT_DIR;if(!r||!f.existsSync(p.join(r,...n))){r='';for(;;){if(f.existsSync(p.join(d,...n))){r=d;break}var q=p.dirname(d);if(q===d)break;d=q}}";
+function buildBootstrap({ plugin = false } = {}) {
+  const walk = BOOTSTRAP_WALK;
+  const body = plugin ? "var f=require('fs'),p=require('path'),u=require('url'),e=process.env,n=['scripts','claude-hooks','_run.mjs'],s='',m=e.CLAUDE_PLUGIN_ROOT||e.COPILOT_PLUGIN_ROOT||e.PLUGIN_ROOT;if(m&&f.existsSync(p.join(m,'bin','run-hook.mjs')))s=p.join(m,'bin','run-hook.mjs');if(!s){" + walk + "if(r){e.CLAUDE_PROJECT_DIR=r;s=p.join(r,...n)}}" : "var f=require('fs'),p=require('path'),u=require('url'),e=process.env,n=['scripts','claude-hooks','_run.mjs'],s='';" + walk + "if(r){e.CLAUDE_PROJECT_DIR=r;s=p.join(r,...n)}";
+  return body + "if(!s)process.exit(0);process.argv=[process.argv[0],s].concat(process.argv.slice(1));import(u.pathToFileURL(s).href).catch(function(){process.exit(0)});" + (plugin ? "//bin/run-hook.mjs" : "//scripts/claude-hooks/_run.mjs");
+}
+var PLATFORM_RUNNER_PREFIX = 'node -e "' + buildBootstrap() + '"';
+var PLUGIN_RUNNER_PREFIX = 'node -e "' + buildBootstrap({ plugin: true }) + '"';
+function buildCustomerBootstrap() {
+  const rel = CUSTOMER_LAUNCHERS.claude.rel.map((s) => "'" + s + "'").join(",");
+  return "var f=require('fs'),p=require('path'),u=require('url'),e=process.env,n=[" + rel + "],s='';" + BOOTSTRAP_WALK + "if(r){e.CLAUDE_PROJECT_DIR=r;s=p.join(r,...n)}if(!s)process.exit(0);process.argv=[process.argv[0],s].concat(process.argv.slice(1));import(u.pathToFileURL(s).href).catch(function(){process.exit(0)});//" + CUSTOMER_LAUNCHERS.claude.rel.join("/");
+}
+var CUSTOMER_RUNNER_PREFIX = 'node -e "' + buildCustomerBootstrap() + '"';
 var LAUNCHER_TEMPLATE = [
   "#!/usr/bin/env node",
   "// HeySpex hook launcher -- GENERATED by hs install / hs connect. Commit it with this repo.",
@@ -1974,7 +2187,12 @@ var LAUNCHER_TEMPLATE = [
   "// (the Cursor one) runs exactly as if Cursor had invoked it directly.",
   "const shim = resolve(root, ...SHIM);",
   "process.argv[1] = shim;",
-  "await import(pathToFileURL(shim).href);",
+  "try {",
+  "  await import(pathToFileURL(shim).href);",
+  "} catch (err) {",
+  "  process.stderr.write('[heyspex] hook ' + (process.argv[2] ?? '?') + ' skipped: ' + (err && err.message ? err.message : err) + '\\n');",
+  "  process.exit(0);",
+  "}",
   ""
 ].join("\n");
 function renderCustomerLauncher(surface = "claude") {
@@ -2081,7 +2299,6 @@ function renderPluginHooksDocument() {
     });
   }
   return {
-    _comment: "GENERATED from scripts/lib/customer-kit.mjs (customer-scoped rows only) \u2014 do not edit by hand; run `node scripts/lib/customer-kit.mjs --write-plugin-hooks`. Every command goes through bin/run-hook.mjs, which finds the hook runtime (HEYSPEX_PLATFORM_ROOT / HEYSPEX_MCP_ENTRY when set in the machine's own env, then the plugin's own location, node_modules/heyspex, $CLAUDE_PROJECT_DIR) \u2014 never $CLAUDE_PROJECT_DIR/scripts, which only exists in heyspex-app. WARNING: a repo whose .claude/settings.json already carries the hs install kit hooks runs every hook twice if this plugin is also enabled \u2014 use one or the other.",
     hooks
   };
 }
@@ -2089,6 +2306,75 @@ function renderPluginHooksText() {
   return `${JSON.stringify(renderPluginHooksDocument(), null, 2)}
 `;
 }
+var COPILOT_EVENT_NAMES = Object.freeze({
+  SessionStart: "sessionStart",
+  SessionEnd: "sessionEnd",
+  UserPromptSubmit: "userPromptSubmitted",
+  PreToolUse: "preToolUse",
+  PostToolUse: "postToolUse",
+  Stop: "agentStop",
+  PreCompact: "preCompact"
+});
+var GITHUB_HOOKS_STATE_ARMING = Object.freeze(["intent-classifier-trigger"]);
+var COPILOT_TOOL_NAMES = Object.freeze({
+  Write: "create",
+  Edit: "edit",
+  MultiEdit: "edit",
+  NotebookEdit: "edit",
+  Bash: "bash",
+  PowerShell: "powershell",
+  Agent: "task",
+  Task: "task",
+  WebFetch: "web_fetch",
+  WebSearch: "web_search"
+});
+function toCopilotMatcher(matcher) {
+  if (!matcher) return void 0;
+  const out = [];
+  for (const part of matcher.split("|")) {
+    let t = null;
+    if (part === ".*") t = ".*";
+    else if (COPILOT_TOOL_NAMES[part]) t = COPILOT_TOOL_NAMES[part];
+    else if (part.startsWith(MCP_PROJECT_PREFIX)) t = ".*" + part.slice(MCP_PROJECT_PREFIX.length);
+    else if (part.startsWith(MCP_PLUGIN_PREFIX)) t = ".*" + part.slice(MCP_PLUGIN_PREFIX.length);
+    if (t && !out.includes(t)) out.push(t);
+  }
+  if (out.includes(".*")) return ".*";
+  return out.length ? out.join("|") : null;
+}
+function githubHookNames() {
+  const names = /* @__PURE__ */ new Set();
+  for (const r of customerHookRows()) {
+    if (dispositionFor(r.hook, "copilot")?.disposition === "mapped" || GITHUB_HOOKS_STATE_ARMING.includes(r.hook)) names.add(r.hook);
+  }
+  return names;
+}
+function githubHookCommand(row) {
+  const tail = hookTail(row);
+  return `R=node_modules/heyspex/scripts/claude-hooks/_run.mjs; [ -f "$R" ] || R=./scripts/claude-hooks/_run.mjs; [ -f "$R" ] || exit 0; exec node "$R" ${tail}`;
+}
+function renderGithubHooksDocument() {
+  const allowed = githubHookNames();
+  const hooks = {};
+  for (const row of customerHookRows()) {
+    if (!allowed.has(row.hook)) continue;
+    const event = COPILOT_EVENT_NAMES[row.event];
+    if (!event) continue;
+    const matcher = toCopilotMatcher(row.matcher);
+    if (matcher === null) continue;
+    (hooks[event] ??= []).push({
+      type: "command",
+      ...matcher ? { matcher } : {},
+      bash: githubHookCommand(row),
+      timeoutSec: row.timeout
+    });
+  }
+  return { version: 1, hooks };
+}
+function renderGithubHooksText() {
+  return `${JSON.stringify(renderGithubHooksDocument(), null, 2)}
+`;
+}
 var HARNESS_COMMAND_SURFACES = Object.freeze([
   {
     installedDir: Object.freeze([".claude", "commands"]),
@@ -2221,6 +2507,22 @@ if (invokedDirectly(import.meta.url, "customer-kit.mjs")) {
       process.exit(1);
     }
     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 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.writeFileSync(ghTarget, ghWant, "utf8");
+      }
+      console.log(`customer-kit: ${ghSame ? "unchanged" : "wrote"} ${path2.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);
+    } else {
+      console.log("customer-kit: .github/hooks/heyspex.json up to date");
+    }
   } else {
     console.log("usage: node scripts/lib/customer-kit.mjs --write-plugin-hooks | --check-plugin-hooks");
   }
@@ -2541,15 +2843,13 @@ if (invokedDirectly(import.meta.url, "install-cursor-hooks.mjs")) {
 init_credentials();
 
 // spex-console/src/lib/cli/connect-checks.ts
-import { homedir as homedir9 } from "node:os";
 import { dirname as dirname5 } 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 { join as join10 } from "node:path";
 init_credentials();
-import { mkdirSync as mkdirSync4, readFileSync as readFileSync8, writeFileSync as writeFileSync4 } from "node:fs";
-import { homedir as homedir8 } from "node:os";
-import { join as join9 } from "node:path";
 
 // spex-console/src/lib/cli/connect-checks.ts
 init_credentials();
@@ -2738,7 +3038,7 @@ function runInit(args, deps) {
     };
   }
   const vaultId = existingVaultId ?? args.adoptedVaultId ?? mintVaultId();
-  const accountId = args.accountId ?? (existingContent ? parseAccountId(existingContent) : null);
+  const accountId = null;
   const content = renderHeyspexYaml({ ...args, vaultId, accountId });
   try {
     deps.writeFile(markerPath, content);
@@ -2835,6 +3135,11 @@ function normalizePathForCompare(p) {
 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);
@@ -2843,6 +3148,62 @@ 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) {
@@ -2859,9 +3220,13 @@ function readPinnedVaultRoot(repoRoot, deps) {
     }
     if (typeof value !== "string") continue;
     const trimmed = value.trim();
-    if (!trimmed || trimmed.includes("${")) continue;
-    if (!isAbsolutePathForCompare(trimmed)) continue;
-    pins.push({ source: rel.join("/"), value: trimmed });
+    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;
 }
@@ -3040,7 +3405,7 @@ function writeProjectContract(ctx, options2 = {}) {
 }
 
 // spex-console/src/lib/cli/init.customer-vault.ts
-import { basename } from "node:path";
+import { basename as basename2 } from "node:path";
 
 // spex-console/src/lib/cli/template-manifest.sources.mjs
 var UNIVERSAL_TEMPLATE_ROWS = [
@@ -3551,7 +3916,7 @@ function findManagedSpecs(deps, targetDir, manifestDests) {
   return out;
 }
 function defaultVaultName(targetDir) {
-  return basename(targetDir) || targetDir;
+  return basename2(targetDir) || targetDir;
 }
 function runCustomerVaultInit(args, deps, options2 = {}) {
   const { targetDir } = args;
@@ -3699,14 +4064,14 @@ function templatePinHook() {
 }
 
 // spex-console/src/lib/cli/principle-selection.ts
-import { basename as basename2 } from "node:path";
+import { basename as basename3 } from "node:path";
 var PRINCIPLES_INDEX_DEST = "specs/principles-index.md";
 function principleKey(row) {
-  const base = basename2(row.dest, ".md");
+  const base = basename3(row.dest, ".md");
   return base.startsWith("principle-") ? base.slice("principle-".length) : base;
 }
 function principleWikilink(row) {
-  return basename2(row.dest, ".md");
+  return basename3(row.dest, ".md");
 }
 function parsePrinciplesFlag(value, rows) {
   const principleRows = rows.filter((row) => row.group === "principle");
@@ -4101,8 +4466,7 @@ function formatReceipt(receipt) {
 }
 
 // spex-console/src/lib/cli/vault-workspace-shared.ts
-import { readFileSync as readFileSync9 } from "node:fs";
-import os2 from "node:os";
+import { readFileSync as readFileSync10 } 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) {
@@ -4981,6 +5345,9 @@ function parseInstallArgs(argv) {
   let plugin = false;
   let pluginApply = false;
   let pluginScope = "project";
+  let copilotHooks = false;
+  let copilotPlugin = false;
+  let copilotPluginApply = false;
   let statusline = true;
   let commandCode = false;
   let force = false;
@@ -5040,6 +5407,11 @@ function parseInstallArgs(argv) {
       }
       pluginScope = v.trim();
       plugin = true;
+    } else if (arg === "--copilot-hooks") copilotHooks = true;
+    else if (arg === "--copilot-plugin") copilotPlugin = true;
+    else if (arg === "--copilot-plugin-apply") {
+      copilotPlugin = true;
+      copilotPluginApply = true;
     } else if (arg === "--no-statusline") statusline = false;
     else if (arg === "--cc" || arg === "--command-code") commandCode = true;
     else if (arg === "--cursor-only") {
@@ -5087,6 +5459,9 @@ function parseInstallArgs(argv) {
       plugin,
       pluginApply,
       pluginScope,
+      copilotHooks,
+      copilotPlugin,
+      copilotPluginApply,
       statusline,
       commandCode,
       force,
@@ -5104,8 +5479,15 @@ function parseInstallArgs(argv) {
 function mcpCliPath(platformRoot, joinPath) {
   return joinPath(platformRoot, ...MCP_REL);
 }
+function resolveCallerPath(p, env, fallbackCwd) {
+  const trimmed = p?.trim() ?? "";
+  if (!trimmed) return "";
+  if (isAbsolute3(trimmed)) return trimmed;
+  const base = env.HS_INVOKED_CWD?.trim() || fallbackCwd;
+  return resolveNodePath2(base, trimmed);
+}
 function resolveInstallTargetDir(argsTargetDir, env, fallbackCwd, opts) {
-  const explicit = argsTargetDir && argsTargetDir.trim();
+  const explicit = resolveCallerPath(argsTargetDir, env, fallbackCwd);
   if (opts?.satellite) {
     return explicit || env.HS_INVOKED_CWD?.trim() || fallbackCwd;
   }
@@ -5176,7 +5558,7 @@ function mergeAttachedRemoteMcpJson(existingJson, pinEntry, cloudEntry, preserve
 }
 function resolveInstallBearer(deps) {
   const env = deps.env ?? process.env;
-  const homeDir = deps.homeDir ?? homedir10();
+  const homeDir = deps.homeDir ?? heyspexHome2();
   const { source } = resolveBearer({
     envToken: env[REMOTE_MCP_TOKEN_ENV],
     credentialsText: deps.readFile(deps.joinPath(homeDir, ".heyspex", "credentials.yaml"))
@@ -5283,6 +5665,16 @@ function buildClaudePluginInstallCommandPowerShell(targetDir, platformRoot, spec
     `claude plugin install ${spec} --scope ${scope}`
   ].join("\n");
 }
+var COPILOT_HOOKS_REL = [".github", "hooks", "heyspex.json"];
+function buildCopilotPluginInstallCommand(targetDir, platformRoot, spec = PLUGIN_INSTALL_SPEC) {
+  const escapedTarget = targetDir.replace(/'/g, "''");
+  const escapedPlatform = platformRoot.replace(/'/g, "''");
+  return [
+    `Set-Location -LiteralPath '${escapedTarget}'`,
+    `copilot plugin marketplace add '${escapedPlatform}'`,
+    `copilot plugin install ${spec}`
+  ].join("\n");
+}
 var STATUSLINE_VENDOR_FILES = [
   ["scripts", "install-statusline.mjs"],
   ["scripts", "claude-statusline", "statusline-command.mjs"],
@@ -5647,11 +6039,11 @@ 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: basename3 } = ctx;
+  const { targetDir, readFile, joinPath, registryOpts, now, basename: basename4 } = ctx;
   let vaultId;
   let schemaVersion = HEYSPEX_YAML_SCHEMA_VERSION;
   const yamlContent = readFile(joinPath(targetDir, "heyspex.yaml"));
-  const markerAccountId = yamlContent ? parseAccountId(yamlContent) : null;
+  const markerAccountId = null;
   if (yamlContent) {
     const existing = parseVaultId(yamlContent);
     if (existing) vaultId = existing;
@@ -5659,7 +6051,7 @@ function registerInstalledVault(args, ctx) {
     if (versionMatch) schemaVersion = Number(versionMatch[1]);
   }
   if (!vaultId) vaultId = slugFromPath(targetDir);
-  const displayName = basename3(targetDir);
+  const displayName = basename4(targetDir);
   const before = loadVaultRegistry(registryOpts);
   const existingVault = before.vaults.find(
     (v) => v.id === vaultId || v.repo_root_abs === targetDir
@@ -5747,7 +6139,7 @@ function guardWritesAgainstLiteralBearer(writeFile, bearerToken) {
   };
 }
 function runInstall(args, inputDeps) {
-  const guardHome = inputDeps.homeDir ? inputDeps.homeDir() : homedir10();
+  const guardHome = inputDeps.homeDir ? inputDeps.homeDir() : heyspexHome2();
   const guardBearer = resolveBearer({
     envToken: (inputDeps.env ?? process.env)[REMOTE_MCP_TOKEN_ENV],
     credentialsText: inputDeps.readFile(
@@ -5784,16 +6176,27 @@ function runInstall(args, inputDeps) {
     };
   }
   let attached;
+  let portableVaultPath = null;
   let satellitePins = [];
   let satelliteStalePins = [];
-  if (args.attachVault !== void 0) {
-    const satelliteDeps = {
-      fileExists: deps.fileExists,
-      readFile: deps.readFile,
-      joinPath: deps.joinPath,
-      ...deps.registryOpts ? { registryOpts: deps.registryOpts } : {}
-    };
-    const resolved = resolveAttachTarget(args.attachVault, satelliteDeps);
+  const markerSatelliteDeps = {
+    fileExists: deps.fileExists,
+    readFile: deps.readFile,
+    joinPath: deps.joinPath,
+    ...deps.registryOpts ? { registryOpts: deps.registryOpts } : {}
+  };
+  const markerAttachment = args.attachVault === void 0 ? detectMarkerAttachment(targetDir, markerSatelliteDeps) : null;
+  if (args.attachVault !== void 0 || markerAttachment && markerAttachment.vaultId) {
+    const satelliteDeps = markerSatelliteDeps;
+    const resolved = args.attachVault === void 0 && markerAttachment ? {
+      ok: true,
+      target: {
+        vaultId: markerAttachment.vaultId ?? "",
+        vaultRootAbs: markerAttachment.vaultRootAbs,
+        workspaceId: "(from heyspex.yaml)",
+        displayName: markerAttachment.vaultId ?? ""
+      }
+    } : resolveAttachTarget(args.attachVault, satelliteDeps);
     if (!resolved.ok) {
       return {
         code: EXIT.INVALID_ARG,
@@ -5803,6 +6206,12 @@ function runInstall(args, inputDeps) {
       };
     }
     attached = resolved.target;
+    {
+      const markerText = deps.readFile(deps.joinPath(targetDir, "heyspex.yaml"));
+      const vp = markerText ? parseMarkerVaultPath(markerText) : null;
+      const markerId = markerText ? parseVaultId(markerText) : null;
+      if (vp && (!markerId || markerId === attached.vaultId)) portableVaultPath = vp;
+    }
     if (deps.joinPath(attached.vaultRootAbs) === deps.joinPath(targetDir)) {
       const message2 = "--attach-vault: this repo IS that vault -- run a normal `hs install` instead of attaching it to itself.";
       return {
@@ -5993,7 +6402,7 @@ ${detail}
     if (deps.fileExists(gitkeepPath)) {
       staleLocalMarkers.push("specs/.gitkeep");
     }
-    if (deps.fileExists(deps.joinPath(targetDir, "heyspex.yaml"))) {
+    if (deps.fileExists(deps.joinPath(targetDir, "heyspex.yaml")) && !portableVaultPath) {
       staleLocalMarkers.push("heyspex.yaml");
     }
     if (staleLocalMarkers.length > 0) {
@@ -6071,8 +6480,10 @@ ${detail}
     templateOutcome = outcome;
   }
   const attachedRoot = attached?.vaultRootAbs;
+  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, attachedRoot), null, 2)}
+  const cursorJson = `${JSON.stringify(renderCursorMcpJson(cursorCliArg, cursorPin), null, 2)}
 `;
   if (args.cursor) {
     const cursorUnchanged = satelliteUnchanged(".cursor/mcp.json");
@@ -6093,7 +6504,7 @@ ${detail}
   }
   const remoteUrl = args.remote ? resolveRemoteMcpUrl(args.remoteUrl) : null;
   const claudeJson = remoteUrl ? `${JSON.stringify(renderRemoteClaudeMcpJson(remoteUrl), null, 2)}
-` : `${JSON.stringify(renderClaudeMcpJson(claudeCliArg, attachedRoot), null, 2)}
+` : `${JSON.stringify(renderClaudeMcpJson(claudeCliArg, claudePin), null, 2)}
 `;
   const claudePs = remoteUrl ? buildClaudeMcpAddRemoteCommandPowerShell(targetDir, remoteUrl) : buildClaudeMcpAddCommandPowerShell(targetDir, cliPath, attachedRoot);
   if (args.claude) {
@@ -6110,7 +6521,7 @@ ${detail}
           existingJson = null;
         }
       }
-      const pinEntry = renderClaudeMcpJson(claudeCliArg, attachedRoot).mcpServers.heyspex;
+      const pinEntry = renderClaudeMcpJson(claudeCliArg, claudePin).mcpServers.heyspex;
       const cloudEntry = renderRemoteClaudeMcpJson(remoteUrl).mcpServers.heyspex;
       const merged = mergeAttachedRemoteMcpJson(
         existingJson,
@@ -6219,6 +6630,71 @@ ${detail}
       );
     }
   }
+  const copilotPluginWanted = args.copilotPlugin === true || args.copilotPluginApply === true;
+  const copilotPluginAvailable = deps.fileExists(marketplaceManifest);
+  let copilotPluginActive = false;
+  if (copilotPluginWanted) {
+    if (!copilotPluginAvailable) {
+      steps.push({
+        kind: "copilot_plugin",
+        path: marketplaceManifest,
+        action: "skipped",
+        detail: "platform root has no .claude-plugin/marketplace.json"
+      });
+    } else {
+      copilotPluginActive = true;
+      steps.push({
+        kind: args.copilotPluginApply ? "copilot_plugin_apply" : "copilot_plugin",
+        path: args.copilotPluginApply ? "copilot plugin install" : pluginSpec.spec,
+        action: args.copilotPluginApply ? args.dryRun ? "would_create" : "created" : "skipped",
+        detail: args.copilotPluginApply ? "needs `copilot` on PATH; see copilot_plugin_commands if apply fails" : "printed below -- run it, or re-run with --copilot-plugin-apply"
+      });
+      if (!args.copilotPluginApply) {
+        nextSteps.push(
+          "GitHub Copilot plugin: run the printed commands, or re-run with --copilot-plugin-apply if `copilot` is on PATH. Then /restart."
+        );
+      }
+    }
+  }
+  if (args.copilotHooks) {
+    const ghPath = deps.joinPath(targetDir, ...COPILOT_HOOKS_REL);
+    if (copilotPluginWanted) {
+      steps.push({
+        kind: "copilot_hooks",
+        path: ghPath,
+        action: "skipped",
+        detail: "WARNING: --copilot-hooks and the Copilot plugin both requested -- the plugin already carries the hooks, so .github/hooks/heyspex.json is not written (they would fire twice)"
+      });
+      nextSteps.push(
+        "Warning: --copilot-hooks skipped because the Copilot plugin is requested (single source: plugin OR .github/hooks, never both)."
+      );
+    } else {
+      const want = renderGithubHooksText();
+      const existing = deps.fileExists(ghPath) ? deps.readFile(ghPath) : null;
+      if (existing !== null && existing.replace(/\r\n/g, "\n") === want) {
+        steps.push({
+          kind: "copilot_hooks",
+          path: ghPath,
+          action: "skipped",
+          detail: "already current"
+        });
+      } else {
+        steps.push({
+          kind: "copilot_hooks",
+          path: ghPath,
+          action: args.dryRun ? "would_create" : "created",
+          detail: `${existing === null ? "new" : "updated"} -- commands resolve ${PORTABLE_PACKAGE_DIR}/scripts/claude-hooks/_run.mjs first, then ./scripts/claude-hooks/_run.mjs, else exit 0`
+        });
+        if (!args.dryRun) {
+          deps.mkdir(deps.joinPath(targetDir, ...COPILOT_HOOKS_REL.slice(0, -1)));
+          deps.writeFile(ghPath, want);
+        }
+      }
+      nextSteps.push(
+        "GitHub Copilot hooks: commit .github/hooks/heyspex.json so cloud agents and teammates get it."
+      );
+    }
+  }
   let settingsWrittenText = null;
   if ((args.statusline ?? true) && args.claude) {
     const statuslineShipsInPlatform = deps.fileExists(
@@ -6455,6 +6931,8 @@ ${detail}
     claude_plugin_powershell: args.plugin && pluginAvailable ? pluginPs : void 0,
     claude_plugin_spec: args.plugin && pluginAvailable ? pluginSpec.spec : void 0,
     claude_plugin_scope: args.plugin && pluginAvailable ? pluginScope : void 0,
+    copilot_plugin_commands: copilotPluginActive ? buildCopilotPluginInstallCommand(targetDir, platformRoot, pluginSpec.spec) : void 0,
+    copilot_plugin_spec: copilotPluginActive ? pluginSpec.spec : void 0,
     command_code_powershell: args.commandCode ? commandCodePs : void 0,
     next_steps: nextSteps,
     dry_run: args.dryRun,
@@ -6548,7 +7026,7 @@ function formatInstallFiles(facts) {
 }
 function predictInstallVaultId(targetDir, deps) {
   const yaml2 = deps.readFile(deps.joinPath(targetDir, "heyspex.yaml"));
-  const accountId = yaml2 ? parseAccountId(yaml2) : null;
+  const accountId = null;
   const fromMarker = yaml2 ? parseVaultId(yaml2) : null;
   if (fromMarker) return { vaultId: fromMarker, accountId };
   try {
@@ -6729,6 +7207,7 @@ var INSTALL_HELP = [
   "  hs install [--target <dir>] [--platform <dir>] [--force] [--dry-run] [--json]",
   "             [--no-cursor] [--no-claude] [--claude-apply]",
   "             [--plugin | --plugin-apply] [--plugin-scope user|project|local]",
+  "             [--copilot-hooks | --copilot-plugin | --copilot-plugin-apply]",
   "             [--no-statusline]",
   "             [--cc | --command-code] [--register-vault [--workspace <id>]]",
   "             [--remote[=<url>]]",
@@ -6787,6 +7266,15 @@ var INSTALL_HELP = [
   `                     the platform's .claude-plugin/marketplace.json (fallback: ${PLUGIN_INSTALL_SPEC}).`,
   "  --plugin-scope <s> Plugin install scope: user, project (default), or local.",
   "                     Implies --plugin.",
+  "  --copilot-hooks    Write .github/hooks/heyspex.json (GitHub Copilot hooks) into the",
+  "                     target. Commands resolve node_modules/heyspex first, so an npm-only",
+  "                     install (no heyspex repo checkout) works. Pick this OR the plugin.",
+  "  --copilot-plugin   Print `copilot plugin marketplace add '<platform>'` +",
+  "                     `copilot plugin install <plugin>@<marketplace>` (the platform root is",
+  "                     node_modules/heyspex for a published install).",
+  "  --copilot-plugin-apply  Run those two commands when `copilot` is on PATH.",
+  "                     Requesting the Copilot plugin AND --copilot-hooks warns and skips the",
+  "                     hooks file (both would fire every hook twice).",
   "  --remote[=<url>]   Write .mcp.json for the REMOTE (cloud) MCP endpoint instead of",
   `                     the local stdio server \u2014 the Streamable-HTTP form against`,
   `                     ${DEFAULT_REMOTE_MCP_URL} (or <url>), authenticated by the`,
@@ -6835,15 +7323,15 @@ var INSTALL_HELP = [
 
 // spex-console/src/lib/cli/install-identity.ts
 import { spawnSync as spawnSync2 } from "node:child_process";
-import { existsSync as existsSync4 } from "node:fs";
-import { homedir as homedir12 } from "node:os";
-import { join as join10 } from "node:path";
+import { existsSync as existsSync5 } from "node:fs";
+import { join as join11 } from "node:path";
 import { createInterface } from "node:readline/promises";
 init_credentials();
 
 // vendor/heyspex-mcp/whoami.mjs
+init_heyspex_home();
 init_credentials();
-import { homedir as homedir11 } from "node:os";
+import { homedir as homedir9 } from "node:os";
 var SESSION_PATH = "/api/mcp/session";
 async function probeCredentialIdentity({ consoleUrl, token, fetchImpl = fetch } = {}) {
   if (!token) return { kind: "no_credential" };
@@ -7098,21 +7586,26 @@ async function runIdentityGate(io, flags, verb, wording = ATTACH_WORDING) {
     "identity_unconfirmed"
   );
 }
-function readConfiguredAccountId(env = process.env, homeDir = homedir12()) {
+function readConfiguredAccountId(env = process.env, homeDir = heyspexHome2()) {
   return resolveSessionOwnerUncached({ env, homeDir });
 }
-function parseMarkerAccount(raw) {
-  if (typeof raw !== "string" || raw.length === 0) return null;
-  return parseAccountId(raw);
-}
 function accountMismatchRepair(repoAccount) {
   return `hs login --switch-account ${repoAccount}`;
 }
 function readRecordedRepoAccount(opts) {
-  const joinPath = opts.joinPath ?? join10;
-  const fromMarker = parseMarkerAccount(opts.readFile(joinPath(opts.repoRoot, "heyspex.yaml")));
-  if (fromMarker) return { accountId: fromMarker, source: "heyspex.yaml" };
-  const configured = readConfiguredAccountId(opts.env ?? process.env, opts.homeDir ?? homedir12());
+  const homeDir = opts.homeDir ?? heyspexHome2();
+  let fromRegistry = null;
+  try {
+    const row = loadVaultRegistry({ registryDir: join11(homeDir, ".heyspex") }).vaults.find(
+      (v) => samePath(v.repo_root_abs, opts.repoRoot)
+    );
+    const id = row?.account_id;
+    fromRegistry = id && id !== "legacy" ? id : null;
+  } catch {
+    fromRegistry = null;
+  }
+  if (fromRegistry) return { accountId: fromRegistry, source: "registry" };
+  const configured = readConfiguredAccountId(opts.env ?? process.env, homeDir);
   return configured ? { accountId: configured, source: "config.yaml" } : null;
 }
 function decideRemoteAccount(input) {
@@ -7131,7 +7624,7 @@ function decideRemoteAccount(input) {
   const tokenLine = `  token:    ${describeBearerSource(identity.tokenSource ?? null)}`;
   if (recorded && recorded.accountId !== identity.accountId) {
     const message2 = `${verb}: refusing -- this repo is recorded under account ${recorded.accountId} (${recorded.source}), but the token this install would wire belongs to ${formatShownIdentity(identity)}. Sign in as the repo's account with \`hs login --switch-account\`, then re-run with --account ${recorded.accountId}. Nothing was written.`;
-    const fromMarker = recorded.source === "heyspex.yaml";
+    const fromMarker = recorded.source === "registry";
     return {
       ok: false,
       result: {
@@ -7152,7 +7645,7 @@ function decideRemoteAccount(input) {
       }
     };
   }
-  const repoLine = !recorded ? "  repo:     unrecorded (heyspex.yaml has no account:, no account_id in ~/.heyspex/config.yaml) -- using the signed-in account" : recorded.source === "heyspex.yaml" ? `  repo:     ${recorded.accountId} (heyspex.yaml) -- matches the signed-in account` : `  repo:     unrecorded in heyspex.yaml -- compared with this machine's configured account ${recorded.accountId} (~/.heyspex/config.yaml), which matches`;
+  const repoLine = !recorded ? "  repo:     unrecorded (heyspex.yaml has no account:, no account_id in ~/.heyspex/config.yaml) -- using the signed-in account" : recorded.source === "registry" ? `  repo:     ${recorded.accountId} (registry) -- matches the signed-in account` : `  repo:     unrecorded in heyspex.yaml -- compared with this machine's configured account ${recorded.accountId} (~/.heyspex/config.yaml), which matches`;
   return {
     ok: true,
     identity,
@@ -7192,7 +7685,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) => join10(r, "vendor", "heyspex-mcp", "cli.mjs")).find((p) => existsSync4(p));
+  const loginCli = [opts.platformRoot, resolveCodeRoot({})].filter((r) => Boolean(r && r.trim())).map((r) => join11(r, "vendor", "heyspex-mcp", "cli.mjs")).find((p) => existsSync5(p));
   return {
     consoleUrl,
     interactive: opts.interactive ?? isInteractiveTerminal(),
@@ -7299,25 +7792,27 @@ async function main() {
       satellite: args.attachVault !== void 0
     })
   );
-  const platformRoot = resolve5(args.platformRoot || platformDefault || process4.cwd());
+  const platformRoot = resolve5(
+    resolveCallerPath(args.platformRoot, process4.env, process4.cwd()) || platformDefault || process4.cwd()
+  );
   const deps = {
     repoRoot: targetDir,
     resolvedTarget: targetDir,
     resolvedPlatform: platformRoot,
-    fileExists: (p) => existsSync5(p),
+    fileExists: (p) => existsSync6(p),
     readFile: (p) => {
       try {
-        return readFileSync10(p, "utf8");
+        return readFileSync11(p, "utf8");
       } catch {
         return null;
       }
     },
-    writeFile: (p, c) => writeFileSync5(p, c, "utf8"),
-    mkdir: (p) => mkdirSync5(p, { recursive: true }),
+    writeFile: (p, c) => writeFileSync6(p, c, "utf8"),
+    mkdir: (p) => mkdirSync6(p, { recursive: true }),
     copyFile: (src, dest) => copyFileSync(src, dest),
-    joinPath: (...s) => join11(...s),
+    joinPath: (...s) => join12(...s),
     // Customer-template step (--register-vault) walks specs/ before applying.
-    readdir: (p) => readdirSync(p),
+    readdir: (p) => readdirSync2(p),
     isDirectory: (p) => {
       try {
         return statSync(p).isDirectory();
@@ -7328,7 +7823,7 @@ async function main() {
     // The /hs-* harness commands step lists the platform's canonical trees.
     listDir: (p) => {
       try {
-        return readdirSync(p);
+        return readdirSync2(p);
       } catch {
         return [];
       }
@@ -7349,7 +7844,7 @@ async function main() {
       verb: "hs install",
       repoRoot: targetDir,
       readFile: deps.readFile,
-      joinPath: join11
+      joinPath: join12
     }) : await runIdentityGate(io, identityArgv.flags, "hs install");
     if (!gate.ok) {
       process4.stderr.write(
@@ -7380,7 +7875,7 @@ async function main() {
   sink.write(`${args.json ? JSON.stringify(payload, null, 2) : result.message}
 `);
   if (!result.isError && args.claudeApply && !args.dryRun && args.claude) {
-    const cliPath = mcpCliPath(platformRoot, join11);
+    const cliPath = mcpCliPath(platformRoot, join12);
     const attachedRoot = result.payload?.attached_vault?.repo_root_abs;
     const mcpVaultRoot = attachedRoot ?? targetDir;
     const claude = spawnSync3(
@@ -7413,17 +7908,17 @@ ${buildClaudeMcpAddCommandPowerShell(targetDir, cliPath, attachedRoot)}
       process4.stdout.write("Claude Code: registered heyspex MCP (--scope project).\n");
     }
   }
-  if (!result.isError && args.pluginApply && !args.dryRun && existsSync5(pluginMarketplaceManifestPath(platformRoot, join11))) {
+  if (!result.isError && args.pluginApply && !args.dryRun && existsSync6(pluginMarketplaceManifestPath(platformRoot, join12))) {
     const shell = process4.platform === "win32";
     const spec = resolvePluginSpec(platformRoot, {
       readFile: (p) => {
         try {
-          return readFileSync10(p, "utf8");
+          return readFileSync11(p, "utf8");
         } catch {
           return null;
         }
       },
-      joinPath: join11
+      joinPath: join12
     });
     const scope = args.pluginScope ?? "project";
     const manualBlock = buildClaudePluginInstallCommandPowerShell(
@@ -7458,6 +7953,33 @@ ${manualBlock}
       } else {
         process4.stdout.write(
           `Claude Code: installed plugin ${spec.spec} (--scope ${scope}). Restart the Claude Code session to load it.
+`
+        );
+      }
+    }
+  }
+  const copilotCommands = result.payload?.copilot_plugin_commands;
+  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 failed = (what, r) => process4.stderr.write(
+      `hs install: copilot plugin ${what} failed (${r.error ? r.error.message : `exit ${r.status ?? "?"}`}).
+${r.stderr || r.stdout || ""}
+Run manually:
+${copilotCommands}
+`
+    );
+    const marketplace = copilotRun(["plugin", "marketplace", "add", platformRoot]);
+    if (marketplace.status !== 0 && !/already/i.test(marketplace.stderr + marketplace.stdout)) {
+      failed("marketplace add", marketplace);
+    } else {
+      const install2 = copilotRun(["plugin", "install", spec]);
+      if (install2.status !== 0 && !/already/i.test(install2.stderr + install2.stdout)) {
+        failed("install", install2);
+      } else {
+        process4.stdout.write(
+          `GitHub Copilot: installed plugin ${spec}. Run /restart in the Copilot CLI to load it.
 `
         );
       }
@@ -7465,9 +7987,9 @@ ${manualBlock}
   }
   if (!result.isError && !args.dryRun && args.claude && (args.statusline ?? true)) {
     const glyphScript = [
-      join11(targetDir, "scripts", "install-statusline.mjs"),
-      join11(platformRoot, "scripts", "install-statusline.mjs")
-    ].find((p) => existsSync5(p));
+      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"], {
       cwd: targetDir,
       encoding: "utf8"