heyspex 0.2.5 → 0.2.7

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "heyspex",
       "source": "./plugins/heyspex",
       "displayName": "HeySpex",
-      "description": "HeySpex plugin for Claude Code and GitHub Copilot CLI: vault integration, MCP server (spec vault tools + hs-* prompts) and lifecycle hooks. Prototype — see plugins/heyspex/README.md before enabling."
+      "description": "SpexCode plugin (for Claude Code), also installable in GitHub Copilot CLI: HeySpex vault integration, MCP server (spec vault tools + hs-* prompts) and lifecycle hooks. Prototype — see plugins/heyspex/README.md before enabling."
     }
   ]
 }

package/bin/hs.mjs

@@ -12,6 +12,8 @@
  * node_modules) executes the .ts entrypoints.
  */
 import { BINDING_VERBS, runVaultBindingCommand } from "./hs-vault-binding.mjs";
+import { findProjectRoot } from "../scripts/lib/customer-kit.mjs";
+import { companionDoctorRow } from "../scripts/lib/companion-install.mjs";
 import { spawn } from "node:child_process";
 import { existsSync, readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
@@ -36,6 +38,77 @@ import {
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(__dirname, "..");
 
+/**
+ * True when this `hs` runs from an installed `heyspex` npm package rather than
+ * a HeySpex source checkout. Same signal `hs doctor` already dispatches on:
+ * scripts/heyspex-doctor.mjs only exists in a source clone (never in `files`).
+ */
+const IS_INSTALLED_PACKAGE = !existsSync(path.join(PKG_ROOT, "scripts", "heyspex-doctor.mjs"));
+
+/**
+ * Help lines for verbs that only work inside a HeySpex source checkout (dev
+ * server, Dev-Factory, seat registry, Companion build, the SpexCrawl dev path).
+ * `hs --help` from an installed package drops them and says so once.
+ */
+const DEV_ONLY_HELP_PREFIXES = [
+  "  hs server ",
+  "  hs factory ",
+  "  hs seat ",
+  // Platform-operator verbs whose implementations are not in the npm package:
+  // test-customer minting (admin), the Neon fleet queue, SpexCode Doctrine
+  // synthesis over this checkout's spexharness/ tree.
+  "  hs admin ",
+  "  hs queue ",
+  "  hs doctrine ",
+  // Verbs listed in the source-checkout help whose implementation the npm
+  // package does not carry (see NOT_IN_PACKAGE_VERBS below for each reason).
+  // Invoking one from an installed package prints a clear "not available in
+  // the npm package" line instead of "install is incomplete".
+  "  hs agent ",
+  "  hs chat ",
+  "  hs code-watcher ",
+  "  hs harness ",
+  "  hs hooks ",
+  "  hs import ",
+  "  hs milestone ",
+  "  hs model ",
+  "  hs registry ",
+  "  hs skills ",
+  "  hs voice ",
+  "  hs check judge ",
+  "  hs bench ",
+  "  node dev-factory/",
+  "                                              search/scrape/crawl CLI",
+  "                                              not an `hs` verb",
+  "                                              Companion)",
+];
+
+function helpForThisInstall(lines) {
+  if (!IS_INSTALLED_PACKAGE) return lines;
+  const out = [];
+  for (const line of lines) {
+    if (line.startsWith("  hs seat set|reset|assignments")) {
+      out.push("  hs seat list|set|reset [--harness <h>]     Your own model per SpexFleet seat in this vault (Claude Code / Copilot)");
+      continue;
+    }
+    if (DEV_ONLY_HELP_PREFIXES.some((p) => line.startsWith(p))) continue;
+    if (line.startsWith("  hs companion start|stop|status|build")) {
+      out.push("  hs companion start|stop|status            Desktop companion tray app (installed by `hs companion install`)");
+      continue;
+    }
+    out.push(line);
+  }
+  out.push(
+    "HeySpex developer-only verbs (hs server, hs factory, hs seat add|update|disable, hs admin, hs queue,",
+    "hs doctrine, hs companion build) need a HeySpex source checkout and are not",
+    "listed here. Neither are verbs whose implementation the npm package does not",
+    "carry (hs agent, hs chat, hs code-watcher, hs harness, hs hooks, hs import,",
+    "hs milestone, hs model, hs registry, hs skills, hs voice, hs check judge).",
+    "",
+  );
+  return out;
+}
+
 /**
  * Every script path `hs` spawns directly by filesystem path (as opposed to
  * `dispatchSpexConsoleEntry`'s own three-case tsx/bundle/missing resolution,
@@ -545,8 +618,23 @@ function extractGlobalVaultFlag(argv) {
 }
 
 function usage() {
-  process.stdout.write(
-    [
+  process.stdout.write(usageLines().join("\n"));
+}
+
+/**
+ * `hs <namespace> --help` for a namespace whose own handler has no help text
+ * (its first token must be a sub-verb): print this install's `hs --help`
+ * lines for that namespace and exit 0, instead of "unknown verb --help".
+ */
+const HELP_FROM_USAGE_NAMESPACES = new Set(["index", "mcp", "wip", "worktree", "skills"]);
+
+/** @param {string} namespace */
+export function namespaceHelpLines(namespace, lines = usageLines()) {
+  return lines.filter((l) => l.startsWith(`  hs ${namespace} `));
+}
+
+function usageLines() {
+  return helpForThisInstall([
       "hs — HeySpex vault CLI",
       "",
       "Usage:",
@@ -573,7 +661,7 @@ function usage() {
       "  hs gateway validate [slug] [--json]        Validate user-authored gateway skills (.heyspex/skills/user/)",
       "  hs mode on|off|status|toggle               Master switch: HeySpex layer on or off (restart Claude Code)",
       "  hs dev [mode:local|mode:cloud|mode:prod]   Dev/prod mode + local/cloud reliance (status when bare)",
-      "  hs setup claude|cursor|copilot [--check|--uninstall]  Install agent lifecycle hooks (copilot also: --print, --hooks)",
+      "  hs setup claude|cursor|copilot [--check|--uninstall]  Install agent lifecycle hooks (claude, copilot also: --print; copilot: --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",
@@ -595,13 +683,12 @@ function usage() {
       "  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 companion start|stop|status|build     Desktop companion tray app",
+      "  hs companion install [--quiet] [--dry-run]  Download, verify and run the signed SpexCompanion setup (Windows x64)",
       "  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",
@@ -619,6 +706,7 @@ function usage() {
       "  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 seat set|reset|assignments [--harness]  Your own model per SpexFleet seat, this vault (customers: hs seat list|set|reset)",
       "  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",
@@ -648,6 +736,9 @@ function usage() {
       "                                              search/scrape/crawl CLI (standalone script,",
       "                                              not an `hs` verb; also reachable from the",
       "                                              Companion)",
+      "  node dev-factory/spexcrawl/firecrawl-cli.mjs search|scrape  Firecrawl — finds the",
+      "                                              self-hosted Firecrawl in this machine's",
+      "                                              Docker (no env var, no API key)",
       "",
       "Control plane (Neon — requires a reachable console):",
       "  hs pin get|set <id>|clear                  Read/set/clear the on-deck pin",
@@ -674,8 +765,7 @@ function usage() {
       "`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"),
-  );
+    ]);
 }
 
 /**
@@ -689,8 +779,11 @@ function usage() {
  *   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
+ *      `hs-defer.ts`, `hs-vault-pull.ts`, `hs-vault-push.ts`, `hs-dev.ts`,
+ *      `hs-index-rebuild.ts`, `hs-index-reconcile.ts`, `hs-handoff.ts`,
+ *      `hs-pin.ts`, `hs-events.ts`, `hs-export-events.ts`, `hs-prereq.ts`,
+ *      `hs-trash.ts`, `hs-trust.ts`, `hs-next-launch.ts`, `hs-revalidate.ts`,
+ *      `hs-test.ts`, `hs-spawn.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
@@ -778,6 +871,10 @@ function dispatchSpexConsoleEntry(entryFile, args, vaultRoot, extraEnv = {}) {
  * version.
  */
 function runStandaloneDoctor(args, vaultRoot) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(`Usage:\n${namespaceHelpLines("doctor").join("\n")}\n`);
+    process.exit(0);
+  }
   const jsonOut = args.includes("--json");
   let version = "0.0.0";
   try {
@@ -827,6 +924,11 @@ function runStandaloneDoctor(args, vaultRoot) {
   if (templateRow.status === "fail") report.ok = false;
   report.checks.push(templateRow);
 
+  // `companion` (HS-056P): is SpexCompanion installed? Optional, so it is never
+  // a failure -- missing on Windows is a warn that offers
+  // `npx heyspex companion install`; other platforms get a skipped note.
+  report.checks.push(companionDoctorRow());
+
   // `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
@@ -891,6 +993,45 @@ function runStandaloneDoctor(args, vaultRoot) {
   printStandaloneDoctorReport(report, jsonOut);
 }
 
+/** Usage for `hs setup`; printed by --help/-h (exit 0) and on a bad target (exit 2). */
+const SETUP_USAGE =
+  "Usage:\n" +
+  "  hs setup claude [--check|--uninstall|--print]   Claude Code lifecycle hooks (--print: setup steps; alias claude-code)\n" +
+  "  hs setup cursor [--check|--uninstall]   Cursor CLI lifecycle hooks\n" +
+  "  hs setup copilot [--check|--uninstall|--print|--hooks|--statusline [--force]]   GitHub Copilot (plugin; --hooks for the cloud agent; --statusline opt-in status line)\n" +
+  "  hs setup <target> --help   This help (never installs anything)\n";
+
+/**
+ * `hs setup claude --print` (alias `claude-code`): the Claude Code steps for a
+ * repo that uses the heyspex npm package — the sibling of `hs setup copilot
+ * --print`. Text only; writes nothing. The one-source-of-hooks note is backed
+ * by the `yields-to-plugin` marker in the committed launcher
+ * (scripts/lib/customer-kit.mjs LAUNCHER_YIELD_MARKER).
+ */
+function claudeCodeSetupSteps() {
+  return [
+    "# Using HeySpex in Claude Code",
+    "",
+    "1. Open this repo in Claude Code (run `claude` from the repo root).",
+    "2. On first open Claude Code asks whether to use the project MCP server `heyspex`",
+    "   (declared in this repo's .mcp.json). Approve it. No .mcp.json yet? Run `npx hs install`.",
+    "   Not signed in on this machine? Run `npx hs login` first.",
+    "3. Check: ask Claude to run `heyspex_preflight`, or run `npx hs doctor`.",
+    "",
+    "Optional: the SpexCode plugin (for Claude Code), from the copy inside node_modules:",
+    "  claude plugin marketplace add ./node_modules/heyspex",
+    "  claude plugin install heyspex@heyspex-marketplace",
+    "  (or in a session: /plugin marketplace add ./node_modules/heyspex, then",
+    "   /plugin install heyspex@heyspex-marketplace)",
+    "",
+    "One source of hooks: the plugin and this repo's .claude/heyspex/run-hook.mjs yield to",
+    "each other. When the plugin is enabled on this machine the committed launcher exits",
+    "silently and the plugin runs every hook, so each hook fires once. Set",
+    "HEYSPEX_REPO_HOOKS=1 to keep the repo hooks as the source instead.",
+    "",
+  ].join("\n");
+}
+
 function printStandaloneDoctorReport(report, jsonOut) {
   if (jsonOut) {
     process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
@@ -913,14 +1054,115 @@ function printStandaloneDoctorReport(report, jsonOut) {
     if (check.human) process.stdout.write(`         ${check.human}\n`);
   }
   process.stdout.write(
-    "\nNote: the full `hs doctor` (git hooks, Cursor wiring, console secrets, and\n" +
-      "dozens of other source-checkout-only checks) only ships inside a clone of\n" +
-      "https://github.com/pwhermanson/workflow-protocol — this is the subset that\n" +
-      "applies to a published install.\n",
+    "\nNote: this is the setup check for a published install. The full platform\n" +
+      "doctor (git hooks, console secrets and other source-checkout checks) is for\n" +
+      "HeySpex developers only and is not part of the npm package.\n",
   );
   process.exit(report.ok ? 0 : 1);
 }
 
+/** The tray-host subcommands of `hs companion` (bare `hs companion` means start). */
+const COMPANION_HOST_COMMANDS = new Set(["start", "stop", "status", "build"]);
+
+/**
+ * The `hs companion` host subcommand to answer with "not distributed through
+ * the npm package yet", or null. Non-null only for start|stop|status|build (or
+ * a bare `hs companion`) when `pkgRoot` has no companion/ source -- an
+ * installed `heyspex` package. Pure apart from the injectable `exists`.
+ * @param {string | undefined} namespace
+ * @param {string | undefined} command
+ * @param {{ pkgRoot?: string, exists?: (p: string) => boolean }} [opts]
+ * @returns {string | null}
+ */
+export function companionHostWithoutSource(namespace, command, { pkgRoot = PKG_ROOT, exists = existsSync } = {}) {
+  if (namespace !== "companion") return null;
+  const sub = command === undefined ? "start" : command;
+  if (!COMPANION_HOST_COMMANDS.has(sub)) return null;
+  return exists(path.join(pkgRoot, "companion")) ? null : sub;
+}
+
+/**
+ * Verbs (`"<namespace>"` or `"<namespace> <sub>"`) a source checkout runs but
+ * the npm package deliberately does not carry, each with the reason a
+ * customer sees. `hs --help` from an installed package hides their lines
+ * (DEV_ONLY_HELP_PREFIXES); invoking one exits 1 with
+ * {@link notInPackageMessage} instead of dispatchSpexConsoleEntry's
+ * "install is incomplete". A verb that IS bundled (scripts/build-cli-bundle.mjs
+ * ENTRIES) never belongs here.
+ */
+export const NOT_IN_PACKAGE_VERBS = Object.freeze({
+  admin: "platform-operator test-customer minting.",
+  queue: "the SpexFleet build queue runs only on the HeySpex platform.",
+  seat: "SpexFleet seat registry, platform build system only.",
+  agent: "the vendored agent collections it imports from are not shipped.",
+  chat: "the SpexCode chat front needs the SpexCode engine, which is not in the npm package.",
+  "code-watcher": "it needs the HeySpex source tree and its TypeScript toolchain.",
+  harness: "SpexCode gate fixtures live in the SpexCode engine, which is not in the npm package.",
+  hooks: "the SpexCode extension seam is read by the SpexCode engine, which is not in the npm package.",
+  import: "it uses the SpexFleet model router, which is not in the npm package.",
+  milestone: "use the console or the heyspex_* MCP tools to read a milestone.",
+  model: "the SpexFleet seat routing table is not in the npm package.",
+  registry: "the launch registry is managed from the console.",
+  skills: "skill sync and the SpexCode skill registry need a HeySpex source checkout.",
+  voice: "voice profiles feed the SpexVoice Companion, which is not in the npm package yet.",
+  "check judge": "the decorrelated judge seat runs on the HeySpex platform.",
+  factory: "SpexFleet/dev-factory internals are platform-only.",
+  doctrine: "SpexCode Doctrine synthesis internals are platform-only.",
+  bench: "SpexCode bench internals are platform-only.",
+  server: "the spex-console dev server is part of the HeySpex source checkout; the hosted console is app.heyspex.com.",
+});
+
+/**
+ * Is this `hs <verb> ... --help|-h` (a help flag after the verb, before any
+ * `--` end-of-options marker)? Bare `hs --help` is handled before dispatch.
+ * @param {string[]} argv the argv after the global --vault flag is removed
+ */
+export function isHelpInvocation(argv) {
+  for (const a of argv.slice(1)) {
+    if (a === "--") return false;
+    if (a === "--help" || a === "-h") return true;
+  }
+  return false;
+}
+
+/**
+ * The NOT_IN_PACKAGE_VERBS key this invocation hits from an installed
+ * package, or null. Pure apart from `installed`.
+ * @param {string | undefined} namespace
+ * @param {string | undefined} command
+ * @param {{ installed?: boolean }} [opts]
+ * @returns {string | null}
+ */
+export function notInPackageVerb(namespace, command, { installed = IS_INSTALLED_PACKAGE } = {}) {
+  if (!installed || !namespace) return null;
+  const two = command ? `${namespace} ${command}` : null;
+  if (two && Object.hasOwn(NOT_IN_PACKAGE_VERBS, two)) return two;
+  return Object.hasOwn(NOT_IN_PACKAGE_VERBS, namespace) ? namespace : null;
+}
+
+/** @param {string} key a NOT_IN_PACKAGE_VERBS key */
+export function notInPackageMessage(key) {
+  return (
+    `hs ${key}: not available in the npm package — ${NOT_IN_PACKAGE_VERBS[key]}\n` +
+    `    It runs only inside a HeySpex source checkout. \`hs --help\` lists every verb this install can run.\n`
+  );
+}
+
+/**
+ * Does `hs seat <command>` go to the customer seat-assignment CLI
+ * (vendor/heyspex-mcp/seat-assign-cli.mjs, epic HS-K9L7)? Installed package:
+ * list|assignments|set|reset|defaults|report-fallback|help (and a bare `hs seat`).
+ * Source checkout: the same minus `list`/bare, which stay the dev-factory
+ * registry (`hs-seat.ts`).
+ */
+export function routesToSeatAssignCli(namespace, command, { installed = IS_INSTALLED_PACKAGE } = {}) {
+  if (namespace !== "seat") return false;
+  if (installed) {
+    return command === undefined || ["list", "assignments", "set", "reset", "defaults", "report-fallback", "help", "--help", "-h"].includes(command);
+  }
+  return ["assignments", "set", "reset", "defaults", "report-fallback"].includes(command);
+}
+
 function main(argv) {
   if (argv.length === 0 || argv[0] === "--help" || argv[0] === "-h") {
     usage();
@@ -952,12 +1194,66 @@ function main(argv) {
   const command = argv[1];
   const rest = argv.slice(2);
 
-  const {
-    vaultRoot,
-    usedRegistryFallback,
-    error: vaultError,
-    brokenPin,
-  } = resolveVaultRootForMain(process.cwd(), process.env);
+  // `hs seat list|set|reset|defaults|report-fallback` — the signed-in user's OWN
+  // seat models (HS-K9L7). Installed package: these subcommands. Source checkout:
+  // set|reset|defaults|assignments|report-fallback (list stays the registry).
+  if (routesToSeatAssignCli(namespace, command)) {
+    import(pathToFileURL(path.join(PKG_ROOT, "vendor", "heyspex-mcp", "seat-assign-cli.mjs")).href)
+      .then((m) => m.runSeatAssignCli(argv.slice(1)))
+      .then((code) => process.exit(code));
+    return;
+  }
+
+  // A source-checkout-only verb from an installed package: say so before vault
+  // resolution can refuse with an unrelated binding error.
+  const missingVerb = notInPackageVerb(namespace, command);
+  if (missingVerb) {
+    process.stderr.write(notInPackageMessage(missingVerb));
+    process.exit(1);
+  }
+  if (
+    HELP_FROM_USAGE_NAMESPACES.has(namespace) &&
+    (command === "--help" || command === "-h")
+  ) {
+    const lines = namespaceHelpLines(namespace);
+    if (lines.length) {
+      process.stdout.write(`Usage:\n${lines.join("\n")}\n`);
+      process.exit(0);
+    }
+  }
+
+  // `hs companion start|stop|status|build` from an installed package (no
+  // companion/ source in the tarball) and `hs companion install` anywhere are
+  // machine-local and need no vault: run them BEFORE vault resolution can
+  // refuse with "not bound to a vault", which sends a customer to fix a binding
+  // that would not help. scripts/hs-companion.mjs drives an installed
+  // SpexCompanion, or offers `npx heyspex companion install` when there is none
+  // (HS-056P; this replaced the "not distributed through the npm package yet" answer).
+  const companionSub = companionHostWithoutSource(namespace, command);
+  if (companionSub || (namespace === "companion" && command === "install")) {
+    const companionArgs = command ? [command, ...rest] : ["start", ...rest];
+    const child = spawn(process.execPath, [spawnTargetPath("companion"), ...companionArgs], {
+      cwd: INVOKED_CWD,
+      stdio: "inherit",
+    });
+    child.on("exit", (code, signal) => process.exit(signal ? 1 : (code ?? 0)));
+    child.on("error", (err) => {
+      process.stderr.write(`hs companion: ${err.message}\n`);
+      process.exit(1);
+    });
+    return;
+  }
+
+  const resolved = resolveVaultRootForMain(process.cwd(), process.env);
+  const { usedRegistryFallback, error: vaultError } = resolved;
+  // `hs <verb> --help` must always print help and exit 0, bound vault or not
+  // (install QC: ~28 verbs refused with VAULT_UNBOUND from an unbound folder).
+  // Help never reads or writes a vault, so an unresolved vault falls back to the
+  // invocation folder and the vault refusals below (broken pin, no vault,
+  // uncloned satellite) are skipped; each verb's own handler prints its help.
+  const helpRequested = isHelpInvocation(argv);
+  const vaultRoot = resolved.vaultRoot || (helpRequested ? INVOKED_CWD : resolved.vaultRoot);
+  const brokenPin = helpRequested ? null : resolved.brokenPin;
   // The registry pointer is never consulted ([[HS-TYJA]]), so the only P1
   // refusal left is a satellite pin that cannot be honoured; onboarding /
   // registry verbs and `hs doctor` still run so the pin can be repaired.
@@ -1066,7 +1362,18 @@ function main(argv) {
 
   // `hs setup claude|cursor` — install agent lifecycle hooks into the vault root.
   if (namespace === "setup") {
-    const agent = command?.toLowerCase();
+    const agent = command?.toLowerCase() === "claude-code" ? "claude" : command?.toLowerCase();
+    // --help/-h anywhere (`hs setup --help`, `hs setup copilot --help`) prints usage and
+    // exits 0 BEFORE any installer is spawned: the installers ignore unknown flags, so a
+    // forwarded --help used to run the real install (Copilot: into ~/.copilot).
+    if ([command, ...rest].some((a) => a === "--help" || a === "-h")) {
+      process.stdout.write(SETUP_USAGE);
+      process.exit(0);
+    }
+    if (agent === "claude" && rest.includes("--print")) {
+      process.stdout.write(claudeCodeSetupSteps());
+      process.exit(0);
+    }
     const SPAWN_KEYS = {
       claude: "setup:claude",
       cursor: "setup:cursor",
@@ -1074,10 +1381,7 @@ function main(argv) {
     };
     if (!agent || !Object.hasOwn(SPAWN_KEYS, agent)) {
       process.stderr.write(
-        `hs setup: expected \`claude\`, \`cursor\` or \`copilot\` (got \`${command ?? ""}\`)\n` +
-          "  hs setup claude [--check|--uninstall]   Claude Code lifecycle hooks\n" +
-          "  hs setup cursor [--check|--uninstall]   Cursor CLI lifecycle hooks\n" +
-          "  hs setup copilot [--check|--uninstall|--print|--hooks|--statusline [--force]]   GitHub Copilot (plugin; --hooks for the cloud agent; --statusline opt-in status line)\n",
+        `hs setup: expected \`claude\`, \`cursor\` or \`copilot\` (got \`${command ?? ""}\`)\n` + SETUP_USAGE,
       );
       process.exit(2);
     }
@@ -1095,8 +1399,10 @@ function main(argv) {
       }
     }
     const script = spawnTargetPath(SPAWN_KEYS[agent]);
-    // Copilot sets up the repo you are standing in, never the (possibly sibling) vault root.
-    const target = agent === "copilot" ? process.cwd() : vaultRoot || process.cwd();
+    // Every agent sets up the PROJECT you are standing in (nearest .git /
+    // heyspex.yaml at or above cwd) -- never the (possibly sibling) vault
+    // root, and never this package's own folder under node_modules/.
+    const target = findProjectRoot(INVOKED_CWD);
     const child = spawn(process.execPath, [script, ...setupFlags], {
       cwd: target,
       stdio: "inherit",
@@ -1315,6 +1621,22 @@ function main(argv) {
     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` below; 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.
+  // Machine-local, never acts on a vault, so it runs ABOVE the hard vault gate
+  // (it is in POINTER_FALLBACK_NAMESPACES): since HS-TYJA (a2bbb0698) dropped the
+  // registry-pointer fallback, `hs trust revoke` from an unbound dir hit
+  // VAULT_UNBOUND here.
+  if (namespace === "trust") {
+    dispatchSpexConsoleEntry("hs-trust.ts", argv, vaultRoot || process.cwd());
+    return;
+  }
+
   if (!vaultRoot) {
     process.stderr.write(noVaultMessage(vaultError));
     process.exit(1);
@@ -1325,6 +1647,7 @@ function main(argv) {
   // vault's files to disk must never scaffold specs/ into a code repo.
   if (
     ["pull", "push", "index"].includes(namespace) &&
+    !helpRequested &&
     readMarkerSatellite(vaultRoot) &&
     !existsSync(path.join(vaultRoot, "specs"))
   ) {
@@ -1936,18 +2259,6 @@ function main(argv) {
     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

package/bin/spexcode.mjs

@@ -33,6 +33,8 @@ import { readFileSync, realpathSync } from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { fileURLToPath } from "node:url";
+import { PRODUCT_SEATS, canonicalSeatId, defaultModelForSeat } from "../vendor/heyspex-mcp/seat-defaults.mjs";
+import { detectHarness } from "../spexharness/src/adapters/harness-detect.mjs";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -200,6 +202,29 @@ export function resolveSeatGuard(argv, seatsRegistry) {
   };
 }
 
+/**
+ * HS-MDZB (epic HS-C65J): a customer install ships no dev-factory/seats.json (that file is the
+ * owner's own fleet). When it is ABSENT, a product seat id is allowed and runs on the harness
+ * default (Claude tiers under Claude Code, `auto` under Copilot); an unknown id is still refused.
+ * Pure: env in, a guard verdict plus a one-line notice out.
+ * @returns {{allowed: boolean, message?: string, notice?: string}}
+ */
+export function resolveSeatGuardWithoutRegistry(seatId, env = {}) {
+  const id = canonicalSeatId(seatId);
+  const known = PRODUCT_SEATS.some((s) => s.id === id);
+  if (!known) {
+    return {
+      allowed: false,
+      message: `spexcode: refusing --seat "${seatId}" — not a HeySpex seat (known: ${PRODUCT_SEATS.map((s) => s.id).join(", ")}).`,
+    };
+  }
+  const d = defaultModelForSeat(id, detectHarness(env).harness);
+  const notice = d.model
+    ? `spexcode: seat "${id}" uses the ${d.harness} default model "${d.model}".`
+    : `spexcode: seat "${id}" has no default model (no harness detected; set HEYSPEX_HARNESS=claude-code or copilot).`;
+  return { allowed: true, notice };
+}
+
 /** Load + JSON.parse `dev-factory/seats.json`. Isolated so tests can stub it. */
 export function loadSeatsRegistry(seatsJsonPath = SEATS_JSON_PATH) {
   return JSON.parse(readFileSync(seatsJsonPath, "utf8"));
@@ -273,6 +298,12 @@ export async function runSpexcode(argv, deps = {}) {
     try {
       registry = loadRegistry();
     } catch (err) {
+      if (err && err.code === "ENOENT") {
+        const guard = resolveSeatGuardWithoutRegistry(seatId, deps.env ?? process.env);
+        stderr.write((guard.allowed ? guard.notice : guard.message) + "\n");
+        if (!guard.allowed) return 2;
+        return runForward(argv, { hsPath, spawnFn });
+      }
       stderr.write(
         `spexcode: could not read dev-factory/seats.json to check --seat "${seatId}": ` +
           `${err && err.message ? err.message : err}\n`,