heyspex 0.1.0 → 0.2.1

package/bin/hs.mjs

@@ -12,16 +12,245 @@
  * node_modules) executes the .ts entrypoints.
  */
 import { spawn } from "node:child_process";
-import { existsSync, readFileSync, statSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-import { runtimeFilesCheckRow } from "../scripts/lib/standalone-doctor.mjs";
+import {
+  foldConnectionReport,
+  runBundledConnectCheck,
+  runtimeFilesCheckRow,
+  templateCheckRow,
+  vaultConfigCheckRow,
+} from "../scripts/lib/standalone-doctor.mjs";
+import {
+  findBrokenSatellitePin,
+  isVaultRoot,
+  readMarkerSatellite,
+  readSatellitePin,
+  resolveActiveVault,
+} from "../vendor/heyspex-mcp/vault-resolve.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(__dirname, "..");
 
+/**
+ * Every script path `hs` spawns directly by filesystem path (as opposed to
+ * `dispatchSpexConsoleEntry`'s own three-case tsx/bundle/missing resolution,
+ * which already carries its own existence handling). Each entry is
+ * PKG_ROOT-relative, posix-separated.
+ *
+ * Why this exists ([[HS-561M]]): `scripts/verify-mcp-package.mjs`'s
+ * `checkClosure` proves the STATIC IMPORT closure of vendor/heyspex-mcp/cli.mjs
+ * is fully packed — it says nothing about the ~15 verbs below that reach a
+ * script by `spawn()`ing a path string, which is invisible to any import-graph
+ * walk. Every dispatch site below resolves its script path THROUGH this
+ * manifest (`path.join(PKG_ROOT, SPAWN_TARGETS[key].path)`) instead of
+ * building the path inline, so `verify-mcp-package.mjs`'s `spawnTargets` check
+ * (which imports this const) can assert every non-`devOnly` entry is actually
+ * in the packed tarball file list, naming whichever one is missing.
+ *
+ * `devOnly: true` entries are scripts this package deliberately does NOT ship
+ * (see each `reason`) — the pack gate skips them, and the dispatch site for
+ * each already guards the missing case at runtime with a clear message
+ * (`doctor` falls back to `runStandaloneDoctor`; `skills` prints a
+ * published-install notice — see their dispatch sites below).
+ */
+export const SPAWN_TARGETS = {
+  "setup:claude": { path: "scripts/install-claude-code-hooks.mjs" },
+  "setup:cursor": { path: "scripts/install-cursor-hooks.mjs" },
+  "skills:sync": {
+    path: "scripts/sync-skills.mjs",
+    devOnly: true,
+    reason:
+      "sync-skills.mjs propagates THIS platform repo's OWN .commandcode/skills " +
+      "source content (Command Code SSOT, resolved from the script's own file " +
+      "location, not the caller's vault) — that content has no meaning outside " +
+      "a clone of the HeySpex platform repo and is not shipped.",
+  },
+  "heyspex-mcp-cli": { path: "vendor/heyspex-mcp/cli.mjs" }, // `hs login` + `hs mcp *`
+  doctor: {
+    path: "scripts/heyspex-doctor.mjs",
+    devOnly: true,
+    reason:
+      "the full doctor audits dozens of source-checkout-only surfaces (git " +
+      "hooks, Cursor wiring, console secrets, ...) a published install never " +
+      "has by design — the dispatch site below already falls back to " +
+      "runStandaloneDoctor() when this file is absent.",
+  },
+  "server:status": { path: "scripts/dev-server-status.mjs" },
+  "server:stop": { path: "scripts/dev-server-stop.mjs" },
+  wip: { path: "scripts/wip-ledger-health.mjs" },
+  worktree: { path: "scripts/hs-worktree.mjs" },
+  "source:status": { path: "scripts/lib/hs-source-preflight.mjs" },
+  "source:preflight": { path: "scripts/lib/hs-source-preflight.mjs" },
+  "source:commit": { path: "scripts/lib/hs-source-commit.mjs" },
+  "source:push": { path: "scripts/lib/hs-source-push.mjs" },
+  "source:branch": { path: "scripts/lib/hs-source-branch.mjs" },
+  "source:log": { path: "scripts/lib/hs-source-log.mjs" },
+  // `hs source identity` — the ONE sanctioned git-identity writer (human-only
+  // set/clear, read-only show). Incident 2026-09-19, vault lesson
+  // `when-git-says-author-identity-unknown`; docs/admin/workflow/git-identity.md.
+  "source:identity": { path: "scripts/lib/hs-source-identity.mjs" },
+  view: { path: "scripts/hs-view.mjs" },
+  capture: { path: "scripts/hs-capture-cli.mjs" },
+  companion: { path: "scripts/hs-companion.mjs" },
+  next: { path: "scripts/hs-next.mjs" },
+  mode: { path: "scripts/hs-mode.mjs" },
+  gateway: { path: "scripts/hs-gateway.mjs" },
+  settings: { path: "scripts/hs-settings.mjs" },
+  classifier: { path: "scripts/hs-classifier.mjs" },
+  auto: { path: "scripts/hs-auto.mjs" },
+  "plugin:launch-mcp": { path: "plugins/heyspex/bin/launch-mcp.mjs" },
+};
+
+/**
+ * Neon control-plane verbs ([[HS-EPIC-CLMW-hs-cli-mcp-wrappers-for-control-plane]]):
+ * each namespace maps to a spex-console TS entry, dispatched via
+ * `dispatchSpexConsoleEntry` in `main()` below. Hoisted to module scope (was
+ * previously declared inline inside `main()`) and exported alongside
+ * `SPAWN_TARGETS` so `BUILTIN_VERBS` below — and anything else that needs the
+ * full verb manifest, e.g. `scripts/verify-verb-sweep.mjs` — can derive these
+ * eight verb names from the dispatcher's own table instead of hand-copying it.
+ */
+export const CONTROL_ENTRYPOINTS = {
+  pin: "hs-pin.ts",
+  claim: "hs-claim.ts",
+  handoff: "hs-handoff.ts",
+  events: "hs-events.ts",
+  "export-events": "hs-export-events.ts",
+  prereq: "hs-prereq.ts",
+  queue: "hs-queue.ts",
+  // `hs model` - one read-only list of every seat that has a model behind it
+  // (launch seats from settings.json, SpexFleet seats from routing-table.json).
+  model: "hs-model.ts",
+  // `hs trash` - the bin every spec delete soft-deletes into. Nothing looked
+  // at it before, so deleted specs accumulated on disk forever.
+  trash: "hs-trash.ts",
+  // `hs admin test-user create` — mint one throwaway test customer against a
+  // stated environment ([[HS-4Z1N-SMXX-EPIC-hs-admin-test-user-create-one-command]]).
+  // Wraps POST /api/admin/users/create, so it belongs with the other verbs
+  // that are thin shells over a console endpoint.
+  admin: "hs-admin.ts",
+  // `hs seat` — read/add/update/disable a SpexFleet seat, matching
+  // /api/seat-registry's operations 1:1 ([[HS-W2H1-NYPR-TASK-create-the-api-endpoint-that-lets-a]]
+  // of epic [[HS-RJVM-NYPR-EPIC-seat-registry-every-role-spexfleet-runs]]).
+  // Reads/writes dev-factory/seats.json directly through `@/lib/seat-registry`
+  // — the same core the API route calls — so it works with the console
+  // stopped, same shape as `hs model` / `hs registry`.
+  seat: "hs-seat.ts",
+  // `hs voice` — add/build/show/set/test/refresh/export a coded voice profile,
+  // matching /api/voice's operations 1:1
+  // ([[HS-PQPJ-DOJY-TASK-build-the-hs-voice-cli-and-matching]] of epic
+  // [[HS-8PG1-DOJY-EPIC-voice-as-a-deterministic-system-a-coded]]). Reads/
+  // writes .heyspex/voice-profiles directly through @/lib/voice-cli — the
+  // same core the API route calls — so it works with the console stopped,
+  // same shape as `hs model` / `hs seat`.
+  voice: "hs-voice.ts",
+};
+
+/**
+ * Every top-level `hs <namespace>` verb `main()` recognizes below, listed in
+ * the same order as their dispatch branches — the single manifest
+ * [[HS-G65Z-TASK-every-hs-verb-sweeps-clean-against-a]]'s
+ * `scripts/verify-verb-sweep.mjs` imports to enumerate what to sweep, instead
+ * of hand-maintaining a second, driftable copy of this list in the sweep
+ * script. Deleting a verb's dispatch branch above and its entry here (both in
+ * this file) is enough to drop it from the sweep with no sweep-script edit.
+ * Does NOT distinguish spawn-backed vs. spex-console-TS-backed vs. bundled —
+ * `SPAWN_TARGETS` above already carries that detail for the verbs it covers;
+ * this list is deliberately just "what does `hs` accept as argv[0]".
+ */
+export const BUILTIN_VERBS = [
+  "init",
+  "install",
+  "join",
+  "invite",
+  "setup",
+  "skills",
+  "vault",
+  "workspace",
+  "login",
+  "logout",
+  "whoami",
+  "connect",
+  "doctor",
+  "index",
+  "pull",
+  "push",
+  "import",
+  "milestone",
+  "factory",
+  "code-watcher",
+  "server",
+  "wip",
+  "worktree",
+  "source",
+  "view",
+  "dev",
+  "defer",
+  "undefer",
+  "spawn",
+  "capture",
+  "companion",
+  "registry",
+  "env",
+  "next",
+  "mode",
+  "gateway",
+  "settings",
+  "classifier",
+  "auto",
+  "mcp",
+  "test",
+  "harness",
+  "hooks",
+  "bench",
+  "check",
+  "revalidate",
+  "agent",
+  "chat",
+  "trust",
+  "doctrine",
+  ...Object.keys(CONTROL_ENTRYPOINTS),
+];
+
+/**
+ * Does this `hs next ...` invocation need the console? Mirror of
+ * `isNextConsoleCommand` in `spex-console/src/lib/cli/next.ts` - that module
+ * owns the rule; this copy exists because the dispatcher must choose a half
+ * BEFORE spawning either one, and cannot import TypeScript. Keep the two in
+ * step: any launch/settings flag added there belongs here too.
+ */
+export function isNextConsoleArgv(args) {
+  if (
+    args[0] === "model" ||
+    args[0] === "permission-mode" ||
+    args[0] === "claim" ||
+    args[0] === "front"
+  )
+    return true;
+  return args.some(
+    (a) =>
+      a === "--launch" ||
+      a === "--force" ||
+      a === "--claim" ||
+      a === "--no-claim" ||
+      a === "--model" ||
+      a.startsWith("--model=") ||
+      a === "--permission-mode" ||
+      a.startsWith("--permission-mode="),
+  );
+}
+
+/** Resolve a SPAWN_TARGETS entry to an absolute path under PKG_ROOT. */
+function spawnTargetPath(key) {
+  const entry = SPAWN_TARGETS[key];
+  if (!entry) throw new Error(`hs: unknown SPAWN_TARGETS key "${key}"`);
+  return path.join(PKG_ROOT, ...entry.path.split("/"));
+}
+
 // Captured before anything in this process could ever chdir (it doesn't
 // today, but every dispatched entry below is spawned with its own `cwd`
 // override — see dispatchSpexConsoleEntry). This is the ONE true record of
@@ -42,20 +271,244 @@ const INVOKED_CWD = process.cwd();
 process.env.HS_INVOKED_CWD = INVOKED_CWD;
 
 /**
- * Walk up from `start` until we find a directory containing `specs/`.
- * That directory is the vault root.
+ * Walk up from `start` until we find a vault root — a directory containing
+ * a `heyspex.yaml` marker file OR a `specs/` dir. Delegates the "is this a
+ * vault root" test to the shared `isVaultRoot` helper (same one the MCP
+ * resolver's cwd walk uses) so the two walks can never disagree about what
+ * counts as a vault ([[HS-GKAI]]).
  */
-function findVaultRoot(start) {
+export function findVaultRoot(start, stopAt) {
   let dir = path.resolve(start);
+  const boundary = stopAt ? path.resolve(stopAt) : null;
   while (true) {
-    const candidate = path.join(dir, "specs");
-    if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+    // A SATELLITE repo (a code repo attached to an existing vault -- see
+    // spex-console/src/lib/cli/satellite.ts) carries no marker of its own and
+    // names its vault in its MCP manifests instead. Checked FIRST at each
+    // level so an explicit attachment beats a vault that merely happens to
+    // sit further up the tree, and so `hs` in a satellite follows THAT vault
+    // rather than whatever the machine-global active pointer last named.
+    const pinned = readSatellitePin(dir);
+    if (pinned) {
+      return pinned;
+    }
+    // A committed, portable satellite marker (heyspex.yaml with a relative
+    // `vault_path`): the attached vault's clone when it is on this machine,
+    // else this repo itself (cloud-only; the marker's vault_id binds it).
+    const marked = readMarkerSatellite(dir);
+    if (marked) {
+      return marked.vaultRootAbs ?? dir;
+    }
+    if (isVaultRoot(dir)) {
       return dir;
     }
+    // `stopAt` is a TEST-ONLY walk boundary (mirrors vault-resolve.mjs's
+    // `cwdWalkRoot`) — checked, then the walk stops, never climbing past it.
+    // Unset in production, so the walk always reaches the real filesystem
+    // root; tests fence it inside a disposable fixture so an unrelated
+    // ancestor higher up the real tree (e.g. a stray `specs/` dir left over
+    // in a temp folder) cannot produce a false match ([[HS-0I1G]]).
+    if (boundary && dir === boundary) return null;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Registry fallback for when the specs/ walk-up finds nothing — since the
+ * repo split (2026-08-31) the vault lives outside the code repo, so `hs`
+ * run from the code repo would otherwise exit "no vault detected".
+ * Delegates to the shared resolver (same one the MCP server trusts) but
+ * only accepts a result that names a real vault: the resolver's last-resort
+ * cwd fallback is rejected so the "no vault detected" error below still
+ * fires when there is genuinely no vault anywhere.
+ *
+ * The test is deliberately "anything but `cwd-heuristic`", so every real
+ * tier passes it: `explicit`, `account-pointer`, `env-vault-root`,
+ * `env-vault-dir`, and `satellite-pin` (an on-disk manifest attachment found
+ * by the resolver's tier-3 walk -- that tier reported the untrue
+ * `env-vault-root` until 2026-09-18; both labels are accepted here, so the
+ * rename changed nothing). `cwd-marker` and `marker-registry-mismatch` (a
+ * heyspex.yaml `vault_id` named the vault, [[HS-VVNQ]]) pass too.
+ */
+export function findRegistryVaultRoot(options = {}) {
+  let resolved;
+  try {
+    resolved = resolveActiveVault(options);
+  } catch {
+    return null;
+  }
+  if (!resolved || resolved.source === "cwd-heuristic") return null;
+  if (!existsSync(resolved.specsDirAbs)) return null;
+  return resolved.repoRootAbs;
+}
+
+/** Env hatch: follow the account-wide active-vault pointer on purpose (same name the MCP transport uses). */
+export function pointerVaultAllowed(env = process.env) {
+  const v = String(env.HEYSPEX_ALLOW_POINTER_VAULT ?? "").trim().toLowerCase();
+  return v === "1" || v === "true" || v === "yes";
+}
+
+/**
+ * Verbs that may legitimately run with only the machine's last-active vault
+ * (or none): they onboard, sign in, or manage the registry itself. EVERY other
+ * verb acts on a vault, and P1 (owner, 2026-10-16) says that vault is the one
+ * bound to the repo the agent runs in -- never the account-wide pointer.
+ */
+const POINTER_FALLBACK_NAMESPACES = new Set([
+  "init", "install", "join", "setup", "skills", "vault", "workspace",
+  "login", "whoami", "logout", "doctor", "registry", "companion", "trust",
+]);
+
+/** True when `hs <namespace> <command>` may run on the pointer-only fallback. */
+export function pointerFallbackAllowedFor(namespace, command) {
+  if (namespace === "mcp") return command === "pair" || command === "login" || command === "install";
+  return POINTER_FALLBACK_NAMESPACES.has(namespace);
+}
+
+/** The refusal printed when a satellite's pin / marker cannot be honoured. */
+export function brokenPinRefusalLine(broken) {
+  return (
+    `hs: this repo's vault pin cannot be honoured, so nothing was run. ${broken.dir}/${broken.source} ` +
+    `names \`${broken.raw}\`, but ${broken.reason}. ` +
+    "Fix the pin (a relative path such as ../<vault-repo> or ${CLAUDE_PROJECT_DIR:-.}/../<vault-repo> is portable), " +
+    "or commit a heyspex.yaml with vault_id and vault_path; hs will NOT fall back to the account-wide active vault.\n"
+  );
+}
+
+/** Nearest directory at/above `start` whose heyspex.yaml is a satellite marker (has vault_path), else null. */
+export function markerSatelliteDirFrom(start) {
+  let dir = path.resolve(start);
+  for (let i = 0; i < 256; i += 1) {
+    if (readMarkerSatellite(dir)) return dir;
     const parent = path.dirname(dir);
     if (parent === dir) return null;
     dir = parent;
   }
+  return null;
+}
+
+/** The refusal for disk-writing verbs in a satellite whose vault clone is missing. */
+export function unclonedVaultRefusalLine(repo) {
+  const m = readMarkerSatellite(repo);
+  return (
+    `hs: ${repo} is bound to vault ${m?.vaultId ?? "(no vault_id)"} by its heyspex.yaml, but the vault ` +
+    `is not cloned at ${m?.vaultPath ?? "its vault_path"} on this machine, so this verb has no local vault to act on. ` +
+    "Clone the vault repo to that relative path (agents and cloud-routed MCP writes work without it).\n"
+  );
+}
+
+/** The refusal printed when only the account-wide pointer answered and the verb acts on a vault. */
+export function pointerOnlyRefusalLine(cwd, vaultRoot) {
+  return (
+    `hs: ${cwd} is not bound to a HeySpex vault (no heyspex.yaml, no specs/, no vault pin in .mcp.json), ` +
+    `so \`hs\` refused to follow the account-wide active vault${vaultRoot ? ` (${vaultRoot})` : ""}. ` +
+    "Bind this repo: run `hs connect` in a vault repo, `hs install --attach-vault <id> --target <repo>` for a code repo, " +
+    "or commit a heyspex.yaml with vault_id and a relative vault_path. " +
+    "To follow the pointer on purpose set HEYSPEX_ALLOW_POINTER_VAULT=1.\n"
+  );
+}
+
+/**
+ * The vault-resolution ladder `main()` runs at the top of every invocation,
+ * factored out so it is unit-testable without spawning a child process
+ * ([[HS-0I1G-B0IT-TASK-track-and-announce-the-registry-active]]).
+ *
+ * Reports `usedRegistryFallback: true` only when NONE of `HS_VAULT_ROOT`, an
+ * explicit `--target`-equivalent, or a marker/satellite pin found walking up
+ * from `cwd` answered, and `findRegistryVaultRoot()` (the machine's
+ * last-active vault, `~/.heyspex/registry.json`) is what resolved the root.
+ * `hs install` uses that flag to warn (always) and — when `--register-vault`
+ * is given without `--dry-run` — refuse, so a customer onboarding an empty
+ * directory doesn't silently write into whatever vault this machine last had
+ * active in some other terminal/console tab.
+ *
+ * `stopAt` is a TEST-ONLY walk-boundary fence, threaded through to both
+ * `findVaultRoot`'s own walk and `resolveActiveVault`'s inner cwd walk (via
+ * its `cwdWalkRoot` option) — production callers (`main()`) omit it.
+ *
+ * @param {string} cwd
+ * @param {NodeJS.ProcessEnv} env
+ * @param {string} [stopAt]
+ * @returns {{ vaultRoot: string|null, usedRegistryFallback: boolean }}
+ */
+export function resolveVaultRootForMain(cwd, env, stopAt) {
+  if (env.HS_VAULT_ROOT) {
+    return { vaultRoot: env.HS_VAULT_ROOT, usedRegistryFallback: false };
+  }
+  // A pin that cannot be honoured is a REFUSAL, never a reason to fall
+  // through to the account-wide pointer (owner principle P1, 2026-10-16).
+  const brokenPin = findBrokenSatellitePin(cwd, stopAt);
+  if (brokenPin) {
+    return { vaultRoot: null, usedRegistryFallback: false, brokenPin };
+  }
+  const walkedRoot = findVaultRoot(cwd, stopAt);
+  if (walkedRoot) {
+    return { vaultRoot: walkedRoot, usedRegistryFallback: false };
+  }
+  // Same ONE order as both resolvers ([[HS-VVNQ]], shared fixture
+  // spex-console/src/lib/vault-resolve/precedence-fixtures.json):
+  // `HS_VAULT_ROOT` (this CLI's explicit tier) → the walk above (satellite
+  // pin, then marker) → `HEYSPEX_VAULT_ROOT`/`HEYSPEX_VAULT_DIR` env → the
+  // registry pointer, the last two via the shared resolver. `cwd` is passed
+  // explicitly so the resolver's own walk starts where ours did — left to
+  // its default it would start from `CLAUDE_PROJECT_DIR`, and a marker found
+  // THERE (a different folder) would be mislabelled a registry fallback.
+  const registryRoot = findRegistryVaultRoot(
+    stopAt ? { cwd, cwdWalkRoot: stopAt } : { cwd },
+  );
+  return {
+    vaultRoot: registryRoot,
+    usedRegistryFallback: Boolean(registryRoot),
+  };
+}
+
+/** True when `argv` carries `--attach-vault` (bare or `=value` form). */
+export function hasAttachVaultFlag(argv) {
+  return argv.some(
+    (a) => a === "--attach-vault" || a.startsWith("--attach-vault="),
+  );
+}
+
+/**
+ * True when `argv` carries an explicit `--target` (bare or `=value` form) —
+ * mirrors `install.ts`'s own `parseInstallArgs` flag test. `hs-install.ts`'s
+ * `resolveInstallTargetDir` already honors `--target` over `HS_VAULT_ROOT`
+ * unconditionally, so a caller who named their target explicitly is never
+ * actually affected by the registry fallback `bin/hs.mjs` computed for
+ * `HS_VAULT_ROOT` — warning or refusing anyway would be a false alarm about a
+ * value the install never consults.
+ */
+export function hasExplicitTargetFlag(argv) {
+  return argv.some((a) => a === "--target" || a.startsWith("--target="));
+}
+
+/**
+ * The warning `hs install` prints (to stderr, in both `--dry-run` and real
+ * output) when the target it is about to use came ONLY from the registry
+ * active-vault fallback — i.e. cwd sits under no vault at all and this
+ * machine's last-active vault pointer answered instead.
+ */
+export function registryFallbackWarningLine(cwd, vaultRoot) {
+  return (
+    `hs install: no vault found in or above ${cwd} — falling back to this ` +
+    `machine's last-active vault (${vaultRoot}, from ~/.heyspex/registry.json). ` +
+    "Pass --target <dir> to install into this directory instead.\n"
+  );
+}
+
+/**
+ * The refusal `hs install --register-vault` (without `--dry-run`) prints and
+ * exits non-zero on instead of registering, when the fallback above is what
+ * answered — registering here would file the machine's last-active vault
+ * under a fresh pointer, not the one the caller meant.
+ */
+export function registryFallbackRefusalLine() {
+  return (
+    "hs install: refusing to run --register-vault from an empty directory that " +
+    "resolved only through the registry active-vault fallback. Pass --target <dir> " +
+    "naming the vault to register, or --dry-run to preview first.\n"
+  );
 }
 
 /**
@@ -93,8 +546,14 @@ function usage() {
       "",
       "Usage:",
       "  hs login [--console-url <url>] [--label <t>] [--json]  Sign in via your browser (no code to type)",
+      "  hs login --switch-account [<id|email>] | --create-account   Switch to a stored account, or choose/create one in the browser",
+      "  hs login --migrate [--dry-run]             Re-key a single-account credentials file under its confirmed account",
+      "  hs whoami [--account <id|email>] [--json]  Which account this machine is signed in as (email, id, source, console)",
+      "  hs logout [--account <id|email>] [--json]  Sign one account out of this machine (default: the current one)",
       "  hs init [--console-url <url>] [--force]     Write the heyspex.yaml vault marker",
       "  hs install [--target <dir>] [--platform <dir>]  Bootstrap vault + Cursor/Claude MCP",
+      "  hs install --attach-vault <id|path>          Wire THIS code repo to an existing vault",
+      "                                               (satellite: no specs/, no heyspex.yaml here)",
       "  hs invite [<name>]                     Mint a short pairing code (other computer: hs join CODE)",
       "  hs join <code>                         Join with a pairing code (LAN auto-find; no IP to type)",
       "  hs join [<repo>] [--dir d] [--code c] [--at url] [--profile p] [--skip steps] [--json] [--yes]  Fresh-machine onboarding (clone → toolchain → deps → doctor → agent layer → secrets → verify)",
@@ -108,20 +567,35 @@ function usage() {
       "  hs dev [mode:local|mode:cloud|mode:prod]   Dev/prod mode + local/cloud reliance (status when bare)",
       "  hs setup claude|cursor [--check|--uninstall]  Install agent lifecycle hooks",
       "  hs skills sync|check                       Propagate skills to Cursor/Codex/Claude (cwd-safe)",
+      "  hs skills add <module-path> --name <n> --trigger </slash> [--export <n>] [--description <t>]  Register a skill (extension seam)",
+      "  hs skills remove <name>                    Remove a customer-registered skill",
+      "  hs skills list [--json]                    List registered skills (built-ins first, locked)",
       "  hs index rebuild [--verbose] [--dry-run]   Full idempotent rebuild of the index",
-      "  hs pull [--apply] [--only <id>] [--overwrite]  Bring cloud-written specs down to the disk vault (reports unless --apply)",
+      "  hs index reconcile [--apply] [--cap-docs keep-out|index]  Per-spec newest-wins between disk and cloud (reports unless --apply)",
+      "  hs pull [--apply] [--only <id>] [--overwrite]  Bring cloud-written specs down to the disk vault (reports unless --apply; --watch --push adds the disk -> cloud leg)",
+      "  hs push [--apply] [--only <id>] [--force]  Send local spec edits up to the cloud vault (reports unless --apply)",
+      "  hs import <source-dir> [--folders a,b] [--plan f] [--dry-run] [--limit N]  Import a doc tree as GROUNDED spec-import captures (never raw, never research)",
+      "  hs source status|preflight|commit|push|branch  Local git: tree status, path-scoped checks, commit, safe push, session branch",
+      "  hs source identity [show|set|clear]        Git author identity: show (read-only) / set, clear (HUMAN-ONLY)",
       "  hs milestone show <id> [--json]            Show a milestone (flags needs-breakdown when epicless)",
       "  hs factory status|fleet|results [--json]   Dev-Factory read-only status (fleet, routing, calibrations, results)",
       "  hs factory run status [--json]             Live assisted/autonomous dispatcher run (pids, queue, stop hints)",
       "  hs code-watcher scan [--json]              Capture build-correctness failures (tsc) → Resolution",
       "  hs server status [--json]                  Ground-truth dev-server status (running? which port[s]?)",
+      "  hs wip status [--json]                     WIP ledger health report (lines vs 600-line budget, age tiers, archive)",
+      "  hs wip restore <id> [--json] [--force]     Restore an archived WIP ledger entry back onto the live ledger",
+      "  hs worktree list|alloc|release|reap [--json] [--dry-run]  Session/build worktree registry (HS-03DO)",
       "  hs view <surface> [spec-id] [--width N --height N --browser edge|chrome]  Open one surface in a chromeless app-mode window",
       "  hs server stop [--json]                    Stop the spex-console dev server (any terminal)",
+      "  hs source status|preflight|commit|push   SpexSource local git operations",
+      "  hs source identity [show|set|clear]      Git author identity (set/clear are human-only; see hs source --help)",
       "  hs defer <id> [--until <when>] [--json]    Time-shift a spec (defer_until)",
       "  hs undefer <id> [--json]                   Clear a spec's defer_until",
       "  hs spawn [<id>] [--dry-run] [--json]       Launch a fresh /hs-next agent in a new terminal",
-      "  hs capture \"<text>\"|--clipboard|--file <p> [--add]  Capture → console drafts (--add chains a group)",
+      '  hs capture "<text>"|--clipboard|--file <p> [--add]  Capture → console drafts (--add chains a group)',
       "  hs companion start|stop|status|build     Desktop companion tray app",
+      "  hs companion settings [list|get <k>|set <k> <v>] [--json]  Every Companion setting (console-backed)",
+      "  hs companion mute|unmute|volume|orb|wake|activation|hotkey [<v>]  Setting shortcuts (omit <v> to read)",
       "  hs registry list [--json]                  List launch registry entries",
       "  hs env init|set|list|run|export|rotate    Encrypted env vault (ADR-0020)",
       "  hs env profiles | key export|import        Named profiles + second-machine key transfer",
@@ -129,23 +603,52 @@ function usage() {
       "  hs settings list|get|set                   Read/change workflow settings (.heyspex/config.yaml)",
       "  hs classifier stats [--json] [--recent N]  Intent Classifier decision stats (read-only)",
       "  hs next [spec_id] [--summary] [--json]     Resolve on-deck brief (MCP fallback)",
+      "  hs next <id> --launch [--dry-run] [--claim] [--backend <anthropic|ollama|deepseek>]  Launch a session on that spec",
+      "  hs next model|permission-mode [<kind>] [<v>]  Per-kind launch defaults",
+      "  hs next backend [<kind>] [<v>]              Per-kind launch backend default (anthropic|ollama|deepseek)",
+      "  hs next claim [on|off]                     Auto-claim vs ask-first default",
+      "  hs next front [handheld|assist|auto]       Default front: one task with you, or a dispatcher run",
+      "  hs next assist|auto <milestone...> --launch  Arm a dispatcher run on one or more milestones",
+      "  hs model [<seat>] [--launch|--fleet]       Every seat and the model set for it",
+      "  hs seat list|add|update|disable [--json]   Read/add/update/disable a seat in the registry (dev-factory/seats.json)",
+      "  hs voice add|build|show|set|test|refresh|export  Build and manage a coded voice profile",
+      "  hs trash [list|restore|empty]              The bin spec deletes go into",
       "  hs auto [filename] [--json]                Resolve /hs-auto dispatch plan",
       "  hs mcp call <tool> [--arg key=value ...] [--args '<json>'] [--args-file <path>] [--json]  One-shot MCP tool",
       "  hs mcp pair <code> [--console-url <url>]   Redeem a console pairing code (cross-machine fallback for hs login)",
+      "  hs mcp install --remote [--write] [--json]  Write/print .mcp.json for the cloud (remote) MCP endpoint",
       "  hs test run <id|manifest> [--format ...]   Run open-format API tests (Hurl/.http) per AC",
       "  hs test gate [dir] [--report <j>] [--threshold n]  Mutation-testing gate — reject suites that kill no mutants",
       "  hs test conform <spec> --url <u> | --report <x>    OpenAPI conformance / docs↔impl drift (Schemathesis)",
+      "  hs chat [--model <name>] [--script <file>] [--seat <seat>]  HeySpex's own chat front (any model); !<cmd> or /shell for CLI passthrough",
+      "  hs trust list                              List spexcode's stored folder-trust decisions",
+      "  hs trust revoke [path]                     Clear one folder's trust decision (default: cwd) so the next launch asks again",
+      "  hs doctrine extract [--since <iso>] [--project <name>] [--dry-run]  Stream every session/taste source into .heyspex/doctrine/observations.jsonl",
+      "  hs doctrine learn [--full] [--max-batches <n>] [--dry-run]  Extract, then synthesize into spexharness/doctrine/SPEXCODE-DOCTRINE.md/json",
+      "  hs doctrine show                            Print the current SPEXCODE-DOCTRINE.md",
+      "  hs harness gates [--json]                  List every SpexHarness gate: id, event, severity, last fixture result",
+      "  hs hooks add <module-path> --event <event> [--id <id>] [--priority <n>]  Register a hook (extension seam)",
+      "  hs hooks remove <id>                       Remove a customer-registered hook",
+      "  hs hooks list [--json]                     List registered hooks (built-ins first, locked)",
       "  hs check run <id|manifest> [--json]        Verify acceptance criteria vs the frozen checks manifest (per-AC pass/fail)",
+      "  hs check judge <id> [--session <id>] [--dry-run]  Decorrelated judge seat: verdicts on method:human criteria, posts to the verification API",
       "  hs revalidate [--json] [--apply]           Re-run the frozen checks of already-stamped work; report what has decayed",
       "  hs agent import <collection> <role>        Import a community agent into a type:agent vault spec",
       "  hs agent list [collection]                 List vendored agent collections / roles",
       "",
+      "  node dev-factory/spexcrawl/spexcrawl-cli.mjs search|scrape|crawl  SpexCrawl — web",
+      "                                              search/scrape/crawl CLI (standalone script,",
+      "                                              not an `hs` verb; also reachable from the",
+      "                                              Companion)",
+      "",
       "Control plane (Neon — requires a reachable console):",
       "  hs pin get|set <id>|clear                  Read/set/clear the on-deck pin",
       "  hs claim acquire|release <id> | list       Atomic spec claims",
       "  hs claim progress <id> --stage <verb>      Report live work-stage",
-      "  hs handoff record|load [--lane <k>]        Resume-context coordination",
+      "  hs handoff record|load [--lane <k>]        Resume-context coordination (never launches)",
+      "  hs handoff <CODE> [--no-launch]             Resolve + LAUNCH the lane's resume by default",
       "  hs events show <id> [--kind --since]       Per-spec audit log",
+      "  hs admin test-user create --env <e>        Mint one throwaway test customer",
       "  hs export-events [--since <date>]          Idempotent audit export → specs/events/",
       "  hs prereq <blocked-id> [<action> <prereq>] Cross-milestone prerequisite resolution",
       "  hs queue submit|next|claim|complete|fail|list  Fleet-queue dispatch (Neon, direct — no console hop)",
@@ -155,7 +658,13 @@ function usage() {
       "  hs --version                               Show CLI version",
       "",
       "Vault root is detected by walking up from the current directory until a",
-      "specs/ folder is found. Override with HS_VAULT_ROOT.",
+      "heyspex.yaml marker or a specs/ folder is found, then falling back to the",
+      "registry's active vault (~/.heyspex/registry.json). Override with HS_VAULT_ROOT.",
+      "When hs install resolves ONLY through that registry fallback (a fully empty",
+      "cwd — no heyspex.yaml/specs/ found walking up, no HS_VAULT_ROOT, no --target),",
+      "it warns, naming the fallback vault, in both --dry-run and real output; and",
+      "`hs install --register-vault` without --dry-run in that case refuses instead of",
+      "registering, asking for --target. --attach-vault (satellite mode) is exempt.",
       "",
     ].join("\n"),
   );
@@ -169,9 +678,13 @@ function usage() {
  * Three cases, in order ([[HS-JOQX-0JNK-TASK-published-package-runs-hs-init-and-hs]]):
  *   1. Monorepo checkout: `.ts` source AND `tsx` both present — run via tsx,
  *      exactly as before this task.
- *   2. Published install of a BUNDLED verb (currently only `hs-init.ts` /
- *      `hs-install.ts` — see `scripts/build-cli-bundle.mjs`'s doc comment
- *      for why only these two): neither the source nor tsx exists, but
+ *   2. Published install of a BUNDLED verb — currently `hs-init.ts`,
+ *      `hs-install.ts`, `hs-claim.ts`, `hs-check.ts`, `hs-env.ts`,
+ *      `hs-connect.ts`, `hs-join.ts`, `hs-vault.ts`, `hs-workspace.ts`,
+ *      `hs-defer.ts`, `hs-vault-pull.ts`, `hs-dev.ts`, `hs-index-rebuild.ts`,
+ *      `hs-index-reconcile.ts` — see `scripts/build-cli-bundle.mjs`'s
+ *      `ENTRIES` array and doc comment for the authoritative list and why
+ *      each qualifies: neither the source nor tsx exists, but
  *      `dist/cli/<name>.mjs` does — run the plain-JS bundle directly with
  *      `node`, no tsx/TypeScript involved.
  *   3. Neither exists: the package install is incomplete (a verb this
@@ -256,7 +769,7 @@ function dispatchSpexConsoleEntry(entryFile, args, vaultRoot, extraEnv = {}) {
  * it), so there is nothing to check about `hs` other than reporting its
  * version.
  */
-function runStandaloneDoctor(args) {
+function runStandaloneDoctor(args, vaultRoot) {
   const jsonOut = args.includes("--json");
   let version = "0.0.0";
   try {
@@ -292,6 +805,46 @@ function runStandaloneDoctor(args) {
   if (runtimeFilesRow.status !== "ok") report.ok = false;
   report.checks.push(runtimeFilesRow);
 
+  // `vault-config` ([[HS-4C76-9W86-DIAG-heyspex-config-yaml-has-no-single-home]]
+  // fix 5): the vault's `.heyspex/config.yaml` (ADR-0009: vault root, git-
+  // tracked) must exist — without it every settings reader runs on defaults.
+  // `vaultRoot` is main()'s resolution (HS_VAULT_ROOT → walk-up → registry);
+  // null means no vault at all, which the row reports as its own failure.
+  const vaultConfigRow = vaultConfigCheckRow(vaultRoot ?? null);
+  if (vaultConfigRow.status !== "ok") report.ok = false;
+  report.checks.push(vaultConfigRow);
+
+  // `vault-template` (HS-KH0Q): shipped core docs + template_version pin present.
+  const templateRow = templateCheckRow(vaultRoot ?? null);
+  if (templateRow.status === "fail") report.ok = false;
+  report.checks.push(templateRow);
+
+  // `connection` ([[HS-W73V-WW9R-TASK-make-both-doctor-shapes-fail-on-cloud]],
+  // invariants 8 and 10): the BUNDLED `hs connect --check --json` from the
+  // invoked cwd, folded by the SAME function the full doctor uses
+  // (`foldConnectionReport`), so a customer machine gets the local-vs-cloud
+  // rows too. A disagreeing row fails the run with its repair command; an
+  // unreadable cloud side (offline, signed out) is a warn and leaves `ok`
+  // alone. The check reads the console with GET only. Its subject is the repo
+  // the caller stands in (the walk-up from the invoked cwd, else the cwd
+  // itself), NOT `vaultRoot`: that can be an inherited HS_VAULT_ROOT or the
+  // registry fallback, i.e. ANOTHER repo (seen when `hs connect`'s acceptance
+  // pass ran this doctor in a fresh repo and it audited the previous one).
+  const connectSubject = findVaultRoot(INVOKED_CWD) ?? INVOKED_CWD;
+  const connection = foldConnectionReport(
+    runBundledConnectCheck(PKG_ROOT, {
+      cwd: INVOKED_CWD,
+      env: {
+        ...process.env,
+        HS_INVOKED_CWD: INVOKED_CWD,
+        HS_VAULT_ROOT: connectSubject,
+      },
+    }),
+  );
+  if (!connection.ok) report.ok = false;
+  report.checks.push(...connection.rows);
+  report.connection = connection.json;
+
   const hsLinkLib = path.join(PKG_ROOT, "scripts", "lib", "hs-link.mjs");
   if (existsSync(hsLinkLib)) {
     // Deliberately synchronous top-level work below via a nested async IIFE
@@ -340,8 +893,15 @@ function printStandaloneDoctorReport(report, jsonOut) {
     "HeySpex setup check — published-package install (not a source clone)\n\n",
   );
   for (const check of report.checks) {
-    const label = check.status === "ok" ? "  ok  " : " FAIL ";
-    process.stdout.write(`[ ${label} ] ${check.detail}\n`);
+    const label =
+      check.status === "ok"
+        ? "  ok  "
+        : check.status === "warn"
+          ? " warn "
+          : " FAIL ";
+    process.stdout.write(
+      `[ ${label} ] ${check.label ? `${check.label}: ` : ""}${check.detail}\n`,
+    );
     if (check.human) process.stdout.write(`         ${check.human}\n`);
   }
   process.stdout.write(
@@ -384,24 +944,88 @@ function main(argv) {
   const command = argv[1];
   const rest = argv.slice(2);
 
-  const vaultRoot = process.env.HS_VAULT_ROOT || findVaultRoot(process.cwd());
+  const resolvedMain = resolveVaultRootForMain(process.cwd(), process.env);
+  const { usedRegistryFallback, brokenPin } = resolvedMain;
+  // P1: the pointer is not a binding. A verb that acts on a vault runs with
+  // NO vault (and is refused at the gate) rather than on whatever vault the
+  // console last selected; onboarding/registry verbs keep the old fallback.
+  const pointerOnly =
+    usedRegistryFallback &&
+    !pointerVaultAllowed(process.env) &&
+    !pointerFallbackAllowedFor(namespace, command);
+  const vaultRoot = pointerOnly ? null : resolvedMain.vaultRoot;
+  if (pointerOnly) {
+    process.stderr.write(pointerOnlyRefusalLine(process.cwd(), resolvedMain.vaultRoot));
+  }
+  if (
+    brokenPin &&
+    namespace !== "doctor" &&
+    !pointerFallbackAllowedFor(namespace, command)
+  ) {
+    process.stderr.write(brokenPinRefusalLine(brokenPin));
+    process.exit(2);
+  }
 
-  // `hs init` writes the top-level heyspex.yaml vault marker
-  // ([[HS-EPIC-AEHR-audit-export-heyspex-yaml-and-heyspex-retirement]] §2). It
-  // may run on a fresh directory that has no specs/ yet, so it bypasses the
-  // hard vault gate below and falls back to the current directory.
+  // `hs init` writes the top-level heyspex.yaml vault marker AND scaffolds
+  // specs/ ([[HS-EPIC-AEHR-audit-export-heyspex-yaml-and-heyspex-retirement]]
+  // §2). It always acts on the caller's invocation directory (`INVOKED_CWD`,
+  // captured before any dispatch below runs) — NEVER on `vaultRoot`'s
+  // walk-up/registry result. `hs init` may legitimately run *inside* a stray
+  // ancestor's `specs/` folder (a half-set-up nested checkout, a doc repo
+  // that happens to have a `specs/` dir, etc.); using `vaultRoot` here would
+  // silently write the marker into that unrelated ancestor instead of where
+  // the user actually typed `hs init` (HS-HISX: first fresh-machine walkthrough
+  // break — the vault marker landed in the wrong folder).
+  // HS_PKG_ROOT is forwarded so the entrypoint can resolve the vendored
+  // `.heyspex/config.yaml` seed template (`vendor/heyspex-mcp/config-seed.yaml`)
+  // from the PACKAGE root, never from the caller's cwd (HS-4C76 fix 4).
   if (namespace === "init") {
-    dispatchSpexConsoleEntry("hs-init.ts", argv, vaultRoot || process.cwd());
+    dispatchSpexConsoleEntry("hs-init.ts", argv, INVOKED_CWD, {
+      HS_PKG_ROOT: PKG_ROOT,
+    });
     return;
   }
 
   // `hs install` bootstraps a customer/project vault + agent MCP wiring. May run
   // on a fresh directory with no specs/ yet (like init).
+  //
+  // [[HS-0I1G-B0IT-TASK-track-and-announce-the-registry-active]]: when the
+  // resolution above bottomed out at the registry active-vault fallback
+  // (nothing set HS_VAULT_ROOT, and no marker/satellite pin was found walking
+  // up from cwd), say so — silently bootstrapping into whatever vault this
+  // machine last had active in some OTHER terminal/console tab is exactly the
+  // wrong-vault failure this task closes. Two flags are exempt because
+  // `hs-install.ts` never actually consults the vaultRoot this fallback
+  // computed for them, so warning/refusing about it would be a false alarm:
+  // `--attach-vault` (satellite mode) — its target resolution
+  // (resolveInstallTargetDir's satellite branch) ignores HS_VAULT_ROOT
+  // entirely and reads HS_INVOKED_CWD instead (and `--register-vault` is
+  // already mutually exclusive with it via assertSatelliteFlagCombination, so
+  // the refusal below can never apply either way) — and an explicit
+  // `--target`, which resolveInstallTargetDir honors over HS_VAULT_ROOT
+  // unconditionally (see hasExplicitTargetFlag's doc comment).
   if (namespace === "install") {
+    if (
+      usedRegistryFallback &&
+      !hasAttachVaultFlag(argv) &&
+      !hasExplicitTargetFlag(argv)
+    ) {
+      process.stderr.write(
+        registryFallbackWarningLine(process.cwd(), vaultRoot),
+      );
+      const isDryRun = argv.includes("--dry-run");
+      const isRegisterVault = argv.includes("--register-vault");
+      if (isRegisterVault && !isDryRun) {
+        process.stderr.write(registryFallbackRefusalLine());
+        process.exit(1);
+      }
+    }
     dispatchSpexConsoleEntry(
       "hs-install.ts",
       argv,
-      vaultRoot || process.cwd(),
+      // In a committed-marker satellite the install target is the CODE repo
+      // (MCP entry, hooks, commands), never the vault clone the marker names.
+      markerSatelliteDirFrom(INVOKED_CWD) ?? (vaultRoot || process.cwd()),
       {
         HS_PKG_ROOT: PKG_ROOT,
       },
@@ -426,24 +1050,28 @@ function main(argv) {
   if (namespace === "invite") {
     if (!vaultRoot) {
       process.stderr.write(
-        "hs: no vault detected — could not find a specs/ folder " +
-          "walking up from the current directory. " +
+        "hs: no vault detected — could not find a heyspex.yaml marker or a " +
+          "specs/ folder walking up from the current directory. " +
           "Set HS_VAULT_ROOT or run from inside a vault.\n",
       );
       process.exit(1);
     }
-    dispatchSpexConsoleEntry("hs-env.ts", ["env", "invite", ...argv.slice(1)], vaultRoot);
+    dispatchSpexConsoleEntry(
+      "hs-env.ts",
+      ["env", "invite", ...argv.slice(1)],
+      vaultRoot,
+    );
     return;
   }
 
   // `hs setup claude|cursor` — install agent lifecycle hooks into the vault root.
   if (namespace === "setup") {
     const agent = command?.toLowerCase();
-    const SCRIPTS = {
-      claude: "install-claude-code-hooks.mjs",
-      cursor: "install-cursor-hooks.mjs",
+    const SPAWN_KEYS = {
+      claude: "setup:claude",
+      cursor: "setup:cursor",
     };
-    if (!agent || !Object.hasOwn(SCRIPTS, agent)) {
+    if (!agent || !Object.hasOwn(SPAWN_KEYS, agent)) {
       process.stderr.write(
         `hs setup: expected \`claude\` or \`cursor\` (got \`${command ?? ""}\`)\n` +
           "  hs setup claude [--check|--uninstall]   Claude Code lifecycle hooks\n" +
@@ -454,7 +1082,7 @@ function main(argv) {
     const setupFlags = rest.filter(
       (a) => a === "--check" || a === "--uninstall",
     );
-    const script = path.join(PKG_ROOT, "scripts", SCRIPTS[agent]);
+    const script = spawnTargetPath(SPAWN_KEYS[agent]);
     const target = vaultRoot || process.cwd();
     const child = spawn(process.execPath, [script, ...setupFlags], {
       cwd: target,
@@ -464,7 +1092,7 @@ function main(argv) {
     child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
     child.on("error", (err) => {
       process.stderr.write(
-        `hs setup: failed to run ${SCRIPTS[agent]}: ${err.message}\n`,
+        `hs setup: failed to run ${SPAWN_TARGETS[SPAWN_KEYS[agent]].path}: ${err.message}\n`,
       );
       process.exit(1);
     });
@@ -472,17 +1100,44 @@ function main(argv) {
   }
 
   // `hs skills sync|check` — propagate .commandcode/skills → Cursor/Codex/Claude shims.
+  // `hs skills add|remove|list` — a DIFFERENT verb: the extension seam's skill
+  // registry ([[HS-8N3K-NYPR-TASK-add-cli-verbs-so-a-developer-can]],
+  // [[HS-8EDJ-NYPR-EPIC-extension-seam-for-other-developers]]), routed to its
+  // own entrypoint below so it never touches the sync/check spawn path.
   if (namespace === "skills") {
     const action = command?.toLowerCase();
+    if (action === "add" || action === "remove" || action === "list") {
+      dispatchSpexConsoleEntry(
+        "hs-skills.ts",
+        argv,
+        vaultRoot || process.cwd(),
+      );
+      return;
+    }
     if (action !== "sync" && action !== "check") {
       process.stderr.write(
-        `hs skills: expected \`sync\` or \`check\` (got \`${command ?? ""}\`)\n` +
-          "  hs skills sync    Copy skills + slash shims to all agent harnesses\n" +
-          "  hs skills check   Exit 1 if any harness copy is stale\n",
+        `hs skills: expected \`sync\`, \`check\`, \`add\`, \`remove\`, or \`list\` (got \`${command ?? ""}\`)\n` +
+          "  hs skills sync                                            Copy skills + slash shims to all agent harnesses\n" +
+          "  hs skills check                                           Exit 1 if any harness copy is stale\n" +
+          "  hs skills add <module-path> --name <n> --trigger </slash> Register a skill (extension seam)\n" +
+          "  hs skills remove <name>                                   Remove a customer-registered skill\n" +
+          "  hs skills list [--json]                                   List registered skills\n",
       );
       process.exit(2);
     }
-    const script = path.join(PKG_ROOT, "scripts", "sync-skills.mjs");
+    const script = spawnTargetPath("skills:sync");
+    if (!existsSync(script)) {
+      // `skills:sync` is a deliberately dev-only SPAWN_TARGETS entry — see its
+      // `reason` above. A published `npm install heyspex` never has
+      // `.commandcode/skills` (the platform's own SSOT content) on disk, so
+      // report that plainly instead of a bare MODULE_NOT_FOUND.
+      process.stderr.write(
+        "hs skills: not available in a published `heyspex` install — this verb " +
+          "propagates the HeySpex platform repo's OWN `.commandcode/skills` " +
+          "source content, which only exists inside a clone of that repo.\n",
+      );
+      process.exit(1);
+    }
     const target = vaultRoot || PKG_ROOT;
     const childArgs = action === "check" ? ["--check"] : [];
     const child = spawn(process.execPath, [script, ...childArgs], {
@@ -532,18 +1187,22 @@ function main(argv) {
   // auth verb, so it bypasses the hard vault gate below like init/install —
   // signing in is exactly what you do BEFORE you have a vault here.
   if (namespace === "login") {
-    const cliPath = path.join(PKG_ROOT, "vendor", "heyspex-mcp", "cli.mjs");
+    const cliPath = spawnTargetPath("heyspex-mcp-cli");
     const loginRoot = vaultRoot || process.cwd();
-    const child = spawn(process.execPath, [cliPath, "login", ...argv.slice(1)], {
-      cwd: PKG_ROOT,
-      stdio: "inherit",
-      env: {
-        ...process.env,
-        HEYSPEX_VAULT_ROOT: loginRoot,
-        HS_VAULT_ROOT: loginRoot,
-        HEYSPEX_DISABLE_STDIO_BOOTSTRAP: "1",
+    const child = spawn(
+      process.execPath,
+      [cliPath, "login", ...argv.slice(1)],
+      {
+        cwd: PKG_ROOT,
+        stdio: "inherit",
+        env: {
+          ...process.env,
+          HEYSPEX_VAULT_ROOT: loginRoot,
+          HS_VAULT_ROOT: loginRoot,
+          HEYSPEX_DISABLE_STDIO_BOOTSTRAP: "1",
+        },
       },
-    });
+    );
     child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
     child.on("error", (err) => {
       process.stderr.write(`hs: failed to run login: ${err.message}\n`);
@@ -552,15 +1211,53 @@ function main(argv) {
     return;
   }
 
+  // `hs whoami` — which account this machine's credential belongs to (email,
+  // account id, console), asked of GET /api/mcp/session. The account a repo
+  // would be attached to by `hs connect` / `hs install`
+  // ([[HS-HAQI-KODY-DIAG-hs-install-and-hs-connect-bind-a-new]]). Auth verb:
+  // bypasses the vault gate like `hs login`.
+  // `hs logout [--account <id|email>]` — remove one stored account's token
+  // ([[HS-UA9S-WW9R-TASK-store-credentials-per-account-login]]). Auth verb:
+  // bypasses the vault gate like `hs login` / `hs whoami`.
+  if (namespace === "whoami" || namespace === "logout") {
+    const cliPath = spawnTargetPath("heyspex-mcp-cli");
+    const whoamiRoot = vaultRoot || process.cwd();
+    const child = spawn(
+      process.execPath,
+      [cliPath, namespace, ...argv.slice(1)],
+      {
+        cwd: PKG_ROOT,
+        stdio: "inherit",
+        env: {
+          ...process.env,
+          HEYSPEX_VAULT_ROOT: whoamiRoot,
+          HS_VAULT_ROOT: whoamiRoot,
+          HEYSPEX_DISABLE_STDIO_BOOTSTRAP: "1",
+        },
+      },
+    );
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(`hs: failed to run ${namespace}: ${err.message}\n`);
+      process.exit(1);
+    });
+    return;
+  }
+
   // `hs connect --check [--json]` — the read-only connect-checks report
   // ([[HS-I2OO-EKLJ-TASK-shared-connect-checks-module-with-a]] on
   // [[HS-QYH8-EKLJ-EPIC-hs-connect-one-command-repo-connect-verb]]). May run
   // in an unconnected repo (no specs/ yet — that is the point), so it
   // bypasses the hard vault gate below like init/install/vault/workspace.
   if (namespace === "connect") {
-    dispatchSpexConsoleEntry("hs-connect.ts", argv, vaultRoot || process.cwd(), {
-      HS_INVOKED_CWD: INVOKED_CWD,
-    });
+    dispatchSpexConsoleEntry(
+      "hs-connect.ts",
+      argv,
+      vaultRoot || process.cwd(),
+      {
+        HS_INVOKED_CWD: INVOKED_CWD,
+      },
+    );
     return;
   }
 
@@ -572,7 +1269,7 @@ function main(argv) {
   // the very first thing a stranger runs after `npm install heyspex` in an
   // empty project is exactly this, from a directory with no `specs/` yet.
   if (namespace === "doctor") {
-    const script = path.join(PKG_ROOT, "scripts", "heyspex-doctor.mjs");
+    const script = spawnTargetPath("doctor");
     if (!existsSync(script)) {
       // Published-package install (per HS-ZJSP-0JNK): the full doctor audits
       // dozens of source-checkout-only surfaces (git hooks, Cursor wiring,
@@ -580,7 +1277,7 @@ function main(argv) {
       // it is deliberately not in the package's `files`. Run the small
       // subset that DOES apply to a published install instead of crashing
       // with MODULE_NOT_FOUND.
-      runStandaloneDoctor(argv.slice(1));
+      runStandaloneDoctor(argv.slice(1), vaultRoot);
       return;
     }
     const child = spawn(process.execPath, [script, ...argv.slice(1)], {
@@ -598,15 +1295,40 @@ function main(argv) {
 
   if (!vaultRoot) {
     process.stderr.write(
-      "hs: no vault detected — could not find a specs/ folder " +
-        "walking up from the current directory. " +
+      "hs: no vault detected — could not find a heyspex.yaml marker or a " +
+        "specs/ folder walking up from the current directory. " +
         "Set HS_VAULT_ROOT or run from inside a vault.\n",
     );
     process.exit(1);
   }
 
+  // A committed satellite marker whose vault clone is NOT on this machine
+  // resolves to the code repo itself (cloud-only binding). Verbs that write the
+  // vault's files to disk must never scaffold specs/ into a code repo.
+  if (
+    ["pull", "push", "index"].includes(namespace) &&
+    readMarkerSatellite(vaultRoot) &&
+    !existsSync(path.join(vaultRoot, "specs"))
+  ) {
+    process.stderr.write(unclonedVaultRefusalLine(vaultRoot));
+    process.exit(2);
+  }
+
   if (namespace === "index" && command === "rebuild") {
-    dispatchSpexConsoleEntry("hs-index-rebuild.ts", rest, vaultRoot);
+    dispatchSpexConsoleEntry("hs-index-rebuild.ts", rest, vaultRoot, {
+      ...(vaultIdOverride ? { HS_VAULT_ID_OVERRIDE: vaultIdOverride } : {}),
+    });
+    return;
+  }
+
+  // `hs index reconcile` — per-spec newest-wins between the disk vault and the
+  // cloud index ([[HS-MS75]]). Read-only unless `--apply`; status moves go
+  // through the status route (refusals are listed), content through the
+  // phased reindex route with preserve_status; never deletes, never finalizes.
+  if (namespace === "index" && command === "reconcile") {
+    dispatchSpexConsoleEntry("hs-index-reconcile.ts", rest, vaultRoot, {
+      ...(vaultIdOverride ? { HS_VAULT_ID_OVERRIDE: vaultIdOverride } : {}),
+    });
     return;
   }
 
@@ -617,7 +1339,34 @@ function main(argv) {
   // pushes, never deletes, and only REPORTS unless `--apply` is given.
   // Forwards the full argv; the entrypoint drops the leading `pull` token.
   if (namespace === "pull") {
-    dispatchSpexConsoleEntry("hs-vault-pull.ts", argv, vaultRoot);
+    dispatchSpexConsoleEntry("hs-vault-pull.ts", argv, vaultRoot, {
+      ...(vaultIdOverride ? { HS_VAULT_ID_OVERRIDE: vaultIdOverride } : {}),
+    });
+    return;
+  }
+
+  // `hs import <source-dir>` — a doc tree becomes GROUNDED spec-import captures
+  // in the cwd's vault (heyspex.yaml marker, never the account pointer): group-
+  // intent pass, foundational-to-specific order, sequential Ground=Expand with
+  // a running batch ledger, one intent-map doc, source links; never promotes
+  // ([[HS-0GOV-43G9-CAP-the-spec-import-function-should-not-stop]]). Forwards
+  // the full argv; the entrypoint drops the leading `import` token and resolves
+  // a relative <source-dir> against HS_INVOKED_CWD.
+  if (namespace === "import") {
+    dispatchSpexConsoleEntry("hs-import.ts", argv, vaultRoot, {
+      HS_INVOKED_CWD: INVOKED_CWD,
+      ...(vaultIdOverride ? { HS_VAULT_ID_OVERRIDE: vaultIdOverride } : {}),
+    });
+    return;
+  }
+
+  // `hs push` — disk -> cloud (SpexRelay local leg, HS-FCNH). Report-only
+  // unless --apply; never creates specs, never pushes status, refuses over a
+  // newer cloud copy. Forwards the full argv; the entrypoint drops `push`.
+  if (namespace === "push") {
+    dispatchSpexConsoleEntry("hs-vault-push.ts", argv, vaultRoot, {
+      ...(vaultIdOverride ? { HS_VAULT_ID_OVERRIDE: vaultIdOverride } : {}),
+    });
     return;
   }
 
@@ -629,6 +1378,14 @@ function main(argv) {
     return;
   }
 
+  // NOTE: `hs source` is handled further down by the plain-Node
+  // scripts/lib/hs-source-*.mjs cores ([[HS-Q0K8-CWPX-EPIC-spexsource-local-git-preflight-commit]]),
+  // which ship inside the published package. An earlier TypeScript build of the
+  // same verb ([[HS-KN93-V4RB-EPIC-local-git-preflight-commit-and-push-for]],
+  // spex-console/bin/hs-source.ts + src/lib/source-local/) used to be dispatched
+  // from this spot; it was superseded when the two branches merged and must not
+  // be re-wired here, or the package-shipping handler below becomes dead code.
+
   if (namespace === "factory" && command === "run") {
     dispatchSpexConsoleEntry("hs-factory-run.ts", argv, vaultRoot);
     return;
@@ -659,9 +1416,8 @@ function main(argv) {
   // server-impacting task; stop from any terminal (not only the one that
   // started it). See [[dev-server-lifecycle-and-db-safety]].
   if (namespace === "server" && (command === "status" || command === "stop")) {
-    const scriptName =
-      command === "stop" ? "dev-server-stop.mjs" : "dev-server-status.mjs";
-    const script = path.join(PKG_ROOT, "scripts", scriptName);
+    const spawnKey = command === "stop" ? "server:stop" : "server:status";
+    const script = spawnTargetPath(spawnKey);
     const child = spawn(process.execPath, [script, ...rest], {
       cwd: PKG_ROOT,
       stdio: "inherit",
@@ -670,7 +1426,55 @@ function main(argv) {
     child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
     child.on("error", (err) => {
       process.stderr.write(
-        `hs: failed to run ${scriptName}: ${err.message}\n`,
+        `hs: failed to run ${SPAWN_TARGETS[spawnKey].path}: ${err.message}\n`,
+      );
+      process.exit(1);
+    });
+    return;
+  }
+
+  // `hs wip status` / `hs wip restore <id>` — health report + restore for the
+  // WIP hand-off ledger (`.heyspex/wip-state.json`) and its archive
+  // (`.heyspex/wip-archive/*.jsonl`). Pure Node core under scripts/ (same
+  // pattern as `hs server status/stop` above). See
+  // [[HS-B8OK-PFMN]] / capture [[HS-817Y-83XQ]] ("the WIP ledger maintains
+  // itself"). Forwards `command` plus the rest of argv; the script itself
+  // decides status vs restore off that first token.
+  if (namespace === "wip" && (command === "status" || command === "restore")) {
+    const script = spawnTargetPath("wip");
+    const child = spawn(process.execPath, [script, command, ...rest], {
+      cwd: PKG_ROOT,
+      stdio: "inherit",
+      env: { ...process.env, HS_VAULT_ROOT: vaultRoot },
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(
+        `hs: failed to run wip-ledger-health.mjs: ${err.message}\n`,
+      );
+      process.exit(1);
+    });
+    return;
+  }
+
+  // `hs worktree list|alloc|release|reap|rebind` — session/build worktree
+  // registry (HS-03DO / HS-V9XH). Pure Node core under scripts/, itself a
+  // thin shell over dev-factory/lib/worktree-allocator.mjs (called in-process,
+  // never shelled out to). Same dispatch shape as `hs server status/stop` and
+  // `hs wip status/restore` above. Forwards the full sub-argv; the entrypoint
+  // drops the leading `worktree` token itself.
+  if (namespace === "worktree") {
+    const script = spawnTargetPath("worktree");
+    const worktreeArgs = command ? [command, ...rest] : rest;
+    const child = spawn(process.execPath, [script, ...worktreeArgs], {
+      cwd: PKG_ROOT,
+      stdio: "inherit",
+      env: { ...process.env, HS_VAULT_ROOT: vaultRoot },
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(
+        `hs: failed to run hs-worktree.mjs: ${err.message}\n`,
       );
       process.exit(1);
     });
@@ -695,27 +1499,41 @@ function main(argv) {
           "  hs source status              Read-only tree status + path-scoped stage plan\n" +
           "  hs source preflight           Alias of status\n" +
           "  hs source commit              Stage + commit per the preflight plan\n" +
-          "  hs source push                Push the committed branch\n" +
+          "  hs source push [branch]       Push the committed branch (no branch: the shared session-branch resolver's target)\n" +
+          "  hs source branch declare [<branch>] | show\n" +
+          "                                Declare the branch this session works on (cloud spec saves then land on it) / show the target\n" +
           "  hs source log <spec-id>       Commit-history lookup for a spec (console settlement,\n" +
-          "                                 falling back to local git log)\n",
+          "                                 falling back to local git log)\n" +
+          "  hs source identity [show] [--json]\n" +
+          "                                Effective git user.name/user.email, where each comes from,\n" +
+          "                                 and whether a repo-local override is authorized (read-only)\n" +
+          "  hs source identity set --email <email> [--name <name>] [--global] [--human]\n" +
+          "                                HUMAN-ONLY: write the identity and record the authorization\n" +
+          "                                 in .heyspex/git-identity.json (agents are refused, exit 3)\n" +
+          "  hs source identity clear [--human]\n" +
+          "                                HUMAN-ONLY: remove the repo-local [user] override + authorization\n" +
+          "                                 Type set/clear yourself — terminal: hs source identity set --email you@example.com\n" +
+          "                                 inside Claude Code: !hs source identity set --email you@example.com --human\n",
       );
       process.exit(0);
     }
-    const SOURCE_ENTRYPOINTS = {
-      status: "hs-source-preflight.mjs",
-      preflight: "hs-source-preflight.mjs",
-      commit: "hs-source-commit.mjs",
-      push: "hs-source-push.mjs",
-      log: "hs-source-log.mjs",
+    const SOURCE_SPAWN_KEYS = {
+      status: "source:status",
+      preflight: "source:preflight",
+      commit: "source:commit",
+      push: "source:push",
+      branch: "source:branch",
+      log: "source:log",
+      identity: "source:identity",
     };
-    const scriptName = SOURCE_ENTRYPOINTS[command];
-    if (!scriptName) {
+    const spawnKey = SOURCE_SPAWN_KEYS[command];
+    if (!spawnKey) {
       process.stderr.write(
-        `hs: unknown \`hs source\` verb \`${command ?? ""}\` — expected one of: ${Object.keys(SOURCE_ENTRYPOINTS).join(", ")}\n`,
+        `hs: unknown \`hs source\` verb \`${command ?? ""}\` — expected one of: ${Object.keys(SOURCE_SPAWN_KEYS).join(", ")}\n`,
       );
       process.exit(2);
     }
-    const script = path.join(PKG_ROOT, "scripts", "lib", scriptName);
+    const script = spawnTargetPath(spawnKey);
     const child = spawn(process.execPath, [script, command, ...rest], {
       cwd: PKG_ROOT,
       stdio: "inherit",
@@ -723,7 +1541,9 @@ function main(argv) {
     });
     child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
     child.on("error", (err) => {
-      process.stderr.write(`hs: failed to run ${scriptName}: ${err.message}\n`);
+      process.stderr.write(
+        `hs: failed to run ${SPAWN_TARGETS[spawnKey].path}: ${err.message}\n`,
+      );
       process.exit(1);
     });
     return;
@@ -734,7 +1554,7 @@ function main(argv) {
   // [[HS-RU2R-I87U-RES-solo-surface-cli-launcher-single]]). Probes ground-truth
   // server status first; a down console prints a clear message, never a blank window.
   if (namespace === "view") {
-    const script = path.join(PKG_ROOT, "scripts", "hs-view.mjs");
+    const script = spawnTargetPath("view");
     const child = spawn(process.execPath, [script, ...argv.slice(1)], {
       cwd: PKG_ROOT,
       stdio: "inherit",
@@ -779,7 +1599,7 @@ function main(argv) {
   // group (the multi-capture "add another?" gesture). Pure Node, posts the
   // same heyspex.capture/0.1 envelope the companion sends to /api/drafts.
   if (namespace === "capture") {
-    const script = path.join(PKG_ROOT, "scripts", "hs-capture-cli.mjs");
+    const script = spawnTargetPath("capture");
     const captureArgs = command ? [command, ...rest] : rest;
     const child = spawn(process.execPath, [script, ...captureArgs], {
       cwd: PKG_ROOT,
@@ -795,12 +1615,17 @@ function main(argv) {
   }
 
   // `hs companion start|stop|status|build` — companion tray host (companion/src/HeySpex.Companion.Host).
+  // `hs companion settings ...` and the shortcuts (mute|volume|orb|wake|...) — every
+  // Companion setting via the console's /api/companion/settings ([[HS-UDH1]]); the
+  // script resolves the console through the shared resolver, which needs the
+  // vault root for the `.heyspex/console-url` discovery file (same as `capture`).
   if (namespace === "companion") {
-    const script = path.join(PKG_ROOT, "scripts", "hs-companion.mjs");
+    const script = spawnTargetPath("companion");
     const companionArgs = command ? [command, ...rest] : ["start", ...rest];
     const child = spawn(process.execPath, [script, ...companionArgs], {
       cwd: PKG_ROOT,
       stdio: "inherit",
+      env: { ...process.env, HS_VAULT_ROOT: vaultRoot },
     });
     child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
     child.on("error", (err) => {
@@ -825,12 +1650,28 @@ function main(argv) {
 
   // `hs next [spec_id] [--summary] [--json]` — resolve the on-deck brief without
   // MCP ([[HS-TASK-ISK7]] / [[tool-agnostic-mcp-first-cli-second]]).
+  // `hs next` has TWO halves and this branch picks one.
+  //
+  //   - `hs next [spec_id] [--summary] [--json]` resolves the on-deck brief
+  //     with no console and no MCP (`scripts/hs-next.mjs`).
+  //   - `hs next <id> --launch`, and the `model` / `permission-mode` / `claim`
+  //     subcommands, need the console (POST /api/agent/start, PUT
+  //     /api/settings) and run through `spex-console/bin/hs-next-launch.ts` -
+  //     the same shape `hs handoff` uses.
   if (namespace === "next") {
-    const script = path.join(PKG_ROOT, "scripts", "hs-next.mjs");
+    if (isNextConsoleArgv(argv.slice(1))) {
+      dispatchSpexConsoleEntry("hs-next-launch.ts", argv, vaultRoot);
+      return;
+    }
+    const script = spawnTargetPath("next");
     const child = spawn(process.execPath, [script, ...argv.slice(1)], {
       cwd: PKG_ROOT,
       stdio: "inherit",
-      env: { ...process.env, HS_VAULT_ROOT: vaultRoot },
+      // hs-next.mjs loads vendor/heyspex-mcp/cli.mjs, which is CODE, not vault
+      // content — since the repo split, HS_VAULT_ROOT can point at a checkout
+      // (e.g. heyspex-specs) with no vendor/ at all
+      // ([[HS-1LCC-4XKS-DIAG-frozen-checks-run-against-the-vault]]).
+      env: { ...process.env, HS_VAULT_ROOT: vaultRoot, HS_PKG_ROOT: PKG_ROOT },
     });
     child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
     child.on("error", (err) => {
@@ -845,7 +1686,7 @@ function main(argv) {
   // Turning it off makes this repo behave like a plain codebase in Claude Code.
   // Core: scripts/heyspex-mode.mjs · docs/claude-code-setup.md.
   if (namespace === "mode") {
-    const script = path.join(PKG_ROOT, "scripts", "hs-mode.mjs");
+    const script = spawnTargetPath("mode");
     const child = spawn(process.execPath, [script, ...argv.slice(1)], {
       cwd: PKG_ROOT,
       stdio: "inherit",
@@ -864,7 +1705,7 @@ function main(argv) {
   // Registration subcommands print a blocked-on-HS-DCCP notice until the
   // connector's server-registration table exists.
   if (namespace === "gateway") {
-    const script = path.join(PKG_ROOT, "scripts", "hs-gateway.mjs");
+    const script = spawnTargetPath("gateway");
     const child = spawn(process.execPath, [script, ...argv.slice(1)], {
       cwd: PKG_ROOT,
       stdio: "inherit",
@@ -882,7 +1723,7 @@ function main(argv) {
   // .heyspex/config.yaml (settings capability; core: vendor/heyspex-mcp/
   // config-settings.mjs; write-permission rules: agent-settings-protocol).
   if (namespace === "settings") {
-    const script = path.join(PKG_ROOT, "scripts", "hs-settings.mjs");
+    const script = spawnTargetPath("settings");
     const child = spawn(process.execPath, [script, ...argv], {
       cwd: PKG_ROOT,
       stdio: "inherit",
@@ -899,7 +1740,7 @@ function main(argv) {
   // `hs classifier stats` — read-only view of HeySpex Intent Classifier decisions
   // (.heyspex/intent-classifier-history.jsonl). Pure local read.
   if (namespace === "classifier") {
-    const script = path.join(PKG_ROOT, "scripts", "hs-classifier.mjs");
+    const script = spawnTargetPath("classifier");
     const child = spawn(process.execPath, [script, ...argv], {
       cwd: PKG_ROOT,
       stdio: "inherit",
@@ -915,7 +1756,7 @@ function main(argv) {
 
   // `hs auto [filename] [--json]` — resolve /hs-auto COO dispatch plan.
   if (namespace === "auto") {
-    const script = path.join(PKG_ROOT, "scripts", "hs-auto.mjs");
+    const script = spawnTargetPath("auto");
     const child = spawn(process.execPath, [script, ...argv.slice(1)], {
       cwd: PKG_ROOT,
       stdio: "inherit",
@@ -936,30 +1777,45 @@ function main(argv) {
   // code for a persistent `hsmcp_` bearer, stored in ~/.heyspex/credentials.yaml
   // ([[HS-GD45-MCPC-TASK-mcp-cloud-auth-shared-console-resolver]]).
   if (namespace === "mcp") {
-    if (command !== "call" && command !== "pair" && command !== "login") {
+    if (
+      command !== "call" &&
+      command !== "pair" &&
+      command !== "login" &&
+      command !== "install"
+    ) {
       process.stderr.write(
-        `hs: unknown mcp subcommand \`${command ?? ""}\` (expected: call | pair | login)\n` +
+        `hs: unknown mcp subcommand \`${command ?? ""}\` (expected: call | pair | login | install)\n` +
           "  hs mcp call <tool> [--arg key=value ...] [--args '<json>'] [--args-file <path>] [--json]\n" +
           "  hs mcp pair <code> [--console-url <url>] [--label <text>] [--json]\n" +
-          "  hs mcp login [--console-url <url>] [--label <text>] [--json]   (alias of `hs login`)\n",
+          "  hs mcp login [--console-url <url>] [--label <text>] [--json]   (alias of `hs login`)\n" +
+          "  hs mcp install --remote [--console-url <url>] [--write] [--json]   Wire a client to the cloud endpoint\n",
       );
       process.exit(2);
     }
-    const cliPath = path.join(PKG_ROOT, "vendor", "heyspex-mcp", "cli.mjs");
+    const cliPath = spawnTargetPath("heyspex-mcp-cli");
+    // The MCP engine resolves its vault by walking UP from ITS cwd. Launching
+    // it with cwd = the HeySpex checkout made every `hs mcp call` read the
+    // HeySpex vault no matter where the agent stood (found 2026-10-16 from
+    // mlc-specs / mlc-app). Run it from the repo the caller is in; an explicit
+    // HS_VAULT_ROOT keeps winning (the engine is started inside that vault).
+    const mcpCwd = process.env.HS_VAULT_ROOT && vaultRoot ? vaultRoot : INVOKED_CWD;
     const child = spawn(process.execPath, [cliPath, command, ...rest], {
-      cwd: PKG_ROOT,
+      cwd: mcpCwd,
       stdio: "inherit",
       env: {
         ...process.env,
-        HEYSPEX_VAULT_ROOT: vaultRoot,
-        HS_VAULT_ROOT: vaultRoot,
+        CLAUDE_PROJECT_DIR: mcpCwd,
+        HEYSPEX_VAULT_ROOT: vaultRoot ?? "",
+        HS_VAULT_ROOT: vaultRoot ?? "",
         // One-shot MCP tool — no stdio loop, no stderr brief-tier noise in PS.
         HEYSPEX_DISABLE_STDIO_BOOTSTRAP: "1",
       },
     });
     child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
     child.on("error", (err) => {
-      process.stderr.write(`hs: failed to run mcp ${command}: ${err.message}\n`);
+      process.stderr.write(
+        `hs: failed to run mcp ${command}: ${err.message}\n`,
+      );
       process.exit(1);
     });
     return;
@@ -974,13 +1830,54 @@ function main(argv) {
     return;
   }
 
+  // `hs harness gates [--json]` — list every registered SpexHarness gate (id,
+  // event, severity, last fixture result), reading the live gate registry +
+  // rule table straight from spexharness/ — no vault/console dependency
+  // ([[HS-XKYY-NYPR-TASK-hs-harness-gates-and-a-console]]).
+  if (namespace === "harness") {
+    dispatchSpexConsoleEntry("hs-harness.ts", argv, vaultRoot || process.cwd());
+    return;
+  }
+
+  // `hs hooks add|remove|list` — the CLI face of the extension seam
+  // ([[HS-8N3K-NYPR-TASK-add-cli-verbs-so-a-developer-can]],
+  // [[HS-8EDJ-NYPR-EPIC-extension-seam-for-other-developers]]). Reads/writes
+  // `.heyspex/harness.json` straight through `spexharness/src/extension/
+  // cli-face.mjs` — the SAME core the API face
+  // (spex-console/src/app/api/harness/extension/route.ts) calls — no
+  // vault/console dependency, same shell shape as `harness gates` above.
+  if (namespace === "hooks") {
+    dispatchSpexConsoleEntry("hs-hooks.ts", argv, vaultRoot || process.cwd());
+    return;
+  }
+
+  // `hs bench <phase1|phase2> --model <name> --harness <on|off>` — run the
+  // harness-on-versus-harness-off benchmark's task set once and write a dated
+  // report under dev-factory/reports/calibrations/bench/
+  // ([[HS-DQ0S-NYPR-TASK-add-a-bench-command-that-runs-the-same]], epic
+  // [[HS-IZCF-NYPR-EPIC-harness-on-versus-harness-off-benchmark]]). Thin CLI
+  // verb only — the real orchestration lives in spexharness/src/bench/*.mjs;
+  // this dispatch branch just reaches the thin shell like `harness` above.
+  if (namespace === "bench") {
+    dispatchSpexConsoleEntry("hs-bench.ts", argv, vaultRoot || process.cwd());
+    return;
+  }
+
   // `hs check run <id|manifest>` — verify a spec's acceptance criteria against its
   // frozen checks manifest, per-criterion pass/fail against the real tree
   // ([[HS-EPIC-DCEP-acceptance-criteria-checks-manifest-dete]], the deterministic
   // kernel of [[HS-MIL-Y5DN-verification-engine-shared-deterministic]]). Forwards
   // the full argv; the entrypoint drops the leading `check` token.
+  //
+  // HS_PKG_ROOT is forwarded so the entrypoint can resolve a check's `cwd`
+  // against the CODE root rather than `vaultRoot` — since the repo split, the
+  // vault and the code can be two different checkouts, and a check almost
+  // always runs code, not vault content
+  // ([[HS-1LCC-4XKS-DIAG-frozen-checks-run-against-the-vault]]).
   if (namespace === "check") {
-    dispatchSpexConsoleEntry("hs-check.ts", argv, vaultRoot);
+    dispatchSpexConsoleEntry("hs-check.ts", argv, vaultRoot, {
+      HS_PKG_ROOT: PKG_ROOT,
+    });
     return;
   }
 
@@ -988,8 +1885,15 @@ function main(argv) {
   // `review_pending`/`in_review` and report what has decayed since the stamp
   // ([[HS-R5LF-36QL-EPIC-stamped-work-is-re-verified-on-a]]). Read-only with
   // respect to the repo; the Resolution plan is a dry run unless `--apply`.
+  //
+  // HS_PKG_ROOT is forwarded for the same reason `check` forwards it: the sweep
+  // re-runs those same frozen manifests, so a check's `cwd` has to resolve
+  // against the CODE root, not the vault
+  // ([[HS-1LCC-4XKS-DIAG-frozen-checks-run-against-the-vault]]).
   if (namespace === "revalidate") {
-    dispatchSpexConsoleEntry("hs-revalidate.ts", argv, vaultRoot);
+    dispatchSpexConsoleEntry("hs-revalidate.ts", argv, vaultRoot, {
+      HS_PKG_ROOT: PKG_ROOT,
+    });
     return;
   }
 
@@ -1003,18 +1907,49 @@ function main(argv) {
     return;
   }
 
+  // `hs chat [--model <name>] [--script <file>] [--seat <seat>]` — HeySpex's own chat
+  // front (step 0 of [[HS-2KYS-NYPR-EPIC-phase-1-end-to-end-on-deepseek-and-on-a]], the
+  // prerequisite that finishes [[HS-F7N3-NYPR-EPIC-the-powershell-front-hs-chat]]). Thin
+  // CLI verb only — every real behavior lives in spexharness/src/chat/*.mjs; this
+  // dispatch branch just reaches the thin shell like every other verb here. Forwards the
+  // full argv; the entrypoint drops the leading `chat` token.
+  if (namespace === "chat") {
+    dispatchSpexConsoleEntry("hs-chat.ts", argv, vaultRoot || process.cwd());
+    return;
+  }
+
+  // `hs trust list` / `hs trust revoke [path]` — standalone management of the machine-local
+  // folder-trust store `hs chat`'s first-run prompt writes to
+  // ([[HS-25AJ-8CMW-TASK-folder-trust-revoke-through-the]], deferred from
+  // [[HS-ZBEB-8CMW-TASK-folder-trust-for-spexcode-first-run]], which shipped only `hs chat
+  // --revoke-trust`). Thin CLI verb — same shell shape as `chat`/`hooks`/`bench` above; the real
+  // logic lives in `spex-console/src/lib/cli/trust-cli.ts` over `folder-trust.ts`'s pure
+  // functions. Forwards the full argv; the entrypoint drops the leading `trust` token.
+  if (namespace === "trust") {
+    dispatchSpexConsoleEntry("hs-trust.ts", argv, vaultRoot || process.cwd());
+    return;
+  }
+
+  // `hs doctrine extract|learn|show` — SpexCode Doctrine corpus reader + synthesis
+  // ([[HS-TWTC-8CMW-TASK-dr1-doctrine-corpus-reader-stream-every]],
+  // [[HS-YMPY-8CMW-TASK-dr2-doctrine-synthesis-a-routed]] of epic
+  // [[HS-KNHZ-8CMW-EPIC-spexcode-doctrine-v0-the-foundational]]). Thin CLI verb —
+  // same shell shape as `chat`/`trust`/`harness` above; the real logic lives in
+  // `spexharness/src/doctrine/*.mjs`. Forwards the full argv; the entrypoint drops
+  // the leading `doctrine` token.
+  if (namespace === "doctrine") {
+    dispatchSpexConsoleEntry(
+      "hs-doctrine.ts",
+      argv,
+      vaultRoot || process.cwd(),
+    );
+    return;
+  }
+
   // Neon control-plane verbs ([[HS-EPIC-CLMW-hs-cli-mcp-wrappers-for-control-plane]]).
   // Each forwards the full argv (namespace/verb + args); the entrypoint drops
-  // the leading namespace token and parses the rest.
-  const CONTROL_ENTRYPOINTS = {
-    pin: "hs-pin.ts",
-    claim: "hs-claim.ts",
-    handoff: "hs-handoff.ts",
-    events: "hs-events.ts",
-    "export-events": "hs-export-events.ts",
-    prereq: "hs-prereq.ts",
-    queue: "hs-queue.ts",
-  };
+  // the leading namespace token and parses the rest. (Table itself now lives
+  // at module scope as CONTROL_ENTRYPOINTS — see its definition above main().)
   if (Object.hasOwn(CONTROL_ENTRYPOINTS, namespace)) {
     dispatchSpexConsoleEntry(CONTROL_ENTRYPOINTS[namespace], argv, vaultRoot);
     return;
@@ -1025,4 +1960,54 @@ function main(argv) {
   process.exit(2);
 }
 
-main(process.argv.slice(2));
+// Only run the CLI when this file is executed directly (`node bin/hs.mjs` /
+// the `hs`/`heyspex` bin shims), not when another script imports it — e.g.
+// `scripts/verify-mcp-package.mjs`'s `spawnTargets` check and
+// `scripts/lib/spawn-target-manifest.test.mjs` import `SPAWN_TARGETS` above
+// without wanting `main()` to run the dispatcher against THEIR argv.
+//
+// A naive `import.meta.url === pathToFileURL(process.argv[1]).href` (the
+// pattern `scripts/verify-mcp-package.mjs`'s own `isMain` guard uses — safe
+// there because that script is never reached through an npm bin shim) is
+// NOT enough here: an `npm link`ed / globally-installed `hs` runs
+// `node "<npm-prefix>/node_modules/heyspex/bin/hs.mjs"`, and when that path
+// is a symlink (npm link's install shape), Node's default module resolution
+// realpaths it for `import.meta.url` but leaves `process.argv[1]` as the
+// ORIGINAL (symlinked) path the shim passed — so the two never matched,
+// `isMain` came out false, and the globally-installed `hs` silently printed
+// nothing and exited 0 for every verb ([[HS-561M]] regression). Fix:
+// realpath BOTH sides before comparing (so the symlink resolves the same way
+// on each side), case-insensitively on Windows (drive-letter casing can
+// differ between how a shim built the path and how realpath reports it).
+function isSameFile(a, b) {
+  const normalize = (p) => {
+    let real;
+    try {
+      real = realpathSync.native(p);
+    } catch {
+      real = path.resolve(p);
+    }
+    return process.platform === "win32" ? real.toLowerCase() : real;
+  };
+  return normalize(a) === normalize(b);
+}
+
+const isMain = (() => {
+  if (!process.argv[1]) return false;
+  try {
+    if (isSameFile(process.argv[1], fileURLToPath(import.meta.url)))
+      return true;
+  } catch {
+    // fall through to the basename fallback below
+  }
+  // Belt-and-suspenders fallback for install shapes realpath can't reconcile
+  // (a shim invoking through an intermediate wrapper, a path realpath can't
+  // stat, etc.): recognize this file by its own known bin names rather than
+  // failing closed into silent no-output.
+  const base = path.basename(process.argv[1]).toLowerCase();
+  return base === "hs.mjs" || base === "hs" || base === "heyspex";
+})();
+
+if (isMain) {
+  main(process.argv.slice(2));
+}