heyspex 0.2.6 → 0.2.7

package/dist/cli-templates/harness-commands/cursor/prototype.md

@@ -7,89 +7,89 @@ description: Build an HTML/frontend prototype for the HeySpex Console. Files MUS
 
 **Usage:** `/prototype <slug> [--from-spec HS-XXXX] [--bump] [--variant <name>]`
 
-This skill is the **implementation** of `specs/protocols/prototype-lifecycle-protocol.md`. The protocol is the SSOT — when they conflict, the protocol wins and this skill is the bug. Fetch it with `heyspex_get_procedure({ name: "prototype-lifecycle-protocol" })` when you need the full rules.
-
-It applies to:
-
-- explicit `/prototype` invocation
-- any natural-language "build me an HTML prototype / mock / preview / canvas" ask
-- `/frontend-design` invocations in this repo (the plugin builds the artifact; this skill governs placement)
-
-## The contract — no exceptions
-
-**Required output paths** (both files, same commit):
-
-1. `spex-console/public/design-previews/<slug>-v<N>[-<variant>].html` — the self-contained prototype.
-2. `spex-console/public/design-previews/<slug>-v<N>[-<variant>].meta.json` — the sidecar.
-
-Anything outside this folder — including a stray top-level `prototypes/` directory — is **invisible** to the console. The route at `spex-console/src/app/api/ui-design/prototypes/route.ts` reads this folder flat (no recursion, no nested folders). A prototype that doesn't show up in the Prototypes surface does not exist for the user.
-
-## Naming
-
-- **`<slug>`** (lineage slug) — kebab-case, describes the surface (`capture-canvas`, `shipped-surface`, `review-inbox`). May contain hyphens. **Match an existing lineage if you're iterating on a known surface** — grep `spex-console/public/design-previews/` before inventing a new slug.
-- **`-v<N>`** — version, starts at `-v1`. **Bump rather than overwrite.** The console groups versions into a lineage with full history. If `--bump`, increment from the highest existing `-v<N>` for that slug.
-- **`-<variant>`** (optional) — sibling variant within a version (e.g. `-v2-alt`, `-v2-minimal`, `-v2-terminal`). May contain hyphens. The console nests variants under their parent version and shows a `+N variants at vK` chip on the lineage card. Variants are for "A/B explorations of the same version", not new lineages.
-- **No `index.html`, no nested folders, no dated filenames.** Just `<slug>-v<N>[-<variant>].html`.
-
-## meta.json schema
-
-Validate against `specs/schemas/prototype-meta.schema.json`. Required: `title` + `status`. Always set `surface_area` and 1–4 `tags` on new sidecars (the console's filter rail depends on them — leaving them empty makes the prototype harder to find).
-
-```json
-{
-  "title": "Human-readable name (e.g. 'Capture canvas v2')",
-  "description": "One-paragraph summary: what it demonstrates, key interactions, aesthetic direction, technical notes. The console hides this on the card and shows it in the drawer Notes tab — write for that context.",
-  "status": "draft",
-  "surface_area": "capture | on-deck | preloader | shell | review | roadmap | other",
-  "tags": ["kebab-case", "1-to-4"],
-  "updated_at": "2026-06-03T18:17:00.000Z",
-  "design_doc": "specs/ui/<slug>-design.md  (optional but required for promotion to accepted)",
-  "linked_specs": [
-    "HS-XXXX-CAP-...",
-    "HS-XXXX-EPIC-..."
-  ],
-  "parent": "<slug>-v<N-1>.html  (optional, when this iterates on a prior version)",
-  "embeds": ["other-prototype-slug  (optional)"]
-}
-```
-
-- **`status` MUST be `"draft"` at create time.** Promotion to `"accepted"` runs through the console's `/api/ui-design/prototypes/<slug>/promote` route and requires both a linked `design_doc` AND a review entry under `specs/reviews/`. The skill does not write `accepted` — refuse if the user asks. (`"archived"` is for superseded versions; usually set later, not at create time.)
-- **Compute `updated_at` as `new Date().toISOString()`** at write time.
-- **`linked_specs`** accepts vault basenames (no `.md` extension) and `HS-*` IDs. Always include the capture/epic/task the prototype embodies. Pull from `--from-spec` if provided. Never invent IDs.
-- Reference siblings in this folder for examples — `shipped-surface-v1.meta.json` (thorough) or `on-deck-v2.meta.json` (minimal).
-
-## Workflow
-
-When this skill is invoked or matched:
-
-1. **Resolve lineage slug.** Match an existing slug if iterating on a known surface; otherwise pick a new kebab-case slug.
-2. **Resolve version.** Default `-v1`. If a file with the same slug already exists, default to bumping to the next integer; honour explicit `--bump`. **Never silently overwrite** — if the target file exists and `--bump` was not passed, surface the conflict and ask.
-3. **Resolve variant.** `--variant <name>` produces `<slug>-v<N>-<name>.html`. Without it, you produce the base variant.
-4. **Pull source spec context.** If `--from-spec HS-XXXX` is passed or the user references a spec, Read it first so the prototype reflects real content, not invented filler.
-5. **Aesthetic.** Defer to the user's brief (e.g. "Claude-in-PowerShell terminal aesthetic" overrides defaults). Otherwise honour console design-system tokens — fetch via `heyspex_design_*` MCP tools, do not grep `spex-console/DESIGN.md`. Recall UI memories first: `heyspex_recall_memories({ tags: ["ui", "console", "design-system"] })`.
-6. **Decide `surface_area` and `tags`.** Pick `surface_area` from the enum based on what the prototype shows. Pick 1–4 lowercase kebab-case `tags` covering the dominant patterns (e.g. `empty-state`, `dark-mode`, `keyboard-nav`).
-7. **Write both files in the same commit.** HTML at `spex-console/public/design-previews/<slug>-v<N>[-<variant>].html`, sidecar at the matching `.meta.json` path. Single self-contained HTML file (inline CSS/JS).
-8. **Validate the sidecar shape** against the schema before saving. Required: `title` + `status`. `status` MUST be `"draft"`. `tags` MUST match `^[a-z0-9-]+$`. `surface_area` MUST be in the enum. `linked_specs[]` items MUST match `^HS-[A-Z0-9]+-` (family keys contain digits, e.g. `HS-9HVY-CAP`). Fix and re-write if any fail.
-9. **Confirm.** After writing, report the gallery URL (`/design-previews/<slug>-v<N>[-<variant>].html`). The console's UI-Design → Prototypes surface picks it up via `/api/ui-design/prototypes` and groups it into the matching lineage automatically.
-
-## Anti-patterns — do not do these
-
-- Do **not** create a new `prototypes/` folder at the repo root.
-- Do **not** nest as `<slug>/index.html`.
-- Do **not** overwrite an existing `<slug>-v<N>[-<variant>].html` — bump or use a new variant.
-- Do **not** ship without a sibling sidecar.
-- Do **not** write `status: "accepted"` from this skill — promotion runs through the console's `/promote` route only.
-- Do **not** invent linked specs. Only reference `HS-*` IDs that exist in the vault.
-- Do **not** leave `surface_area` and `tags` empty on new sidecars — the console's filter rail depends on them.
-- Do **not** Read `spex-console/DESIGN.md` for token lookups; use `heyspex_design_get_token` / `heyspex_design_get_pattern` MCP tools.
-
-## Reference
-
-- **Protocol (SSOT):** `specs/protocols/prototype-lifecycle-protocol.md` — fetch with `heyspex_get_procedure({ name: "prototype-lifecycle-protocol" })`
-- **Schema (SSOT):** `specs/schemas/prototype-meta.schema.json`
-- **Discovery route:** `spex-console/src/app/api/ui-design/prototypes/route.ts`
-- **Surface component:** `spex-console/src/components/surfaces/ui-design-surface.tsx`
-- **Lineage parser:** `spex-console/src/lib/prototype-lineage.ts`
-- **Folder:** `spex-console/public/design-previews/`
-- **Thorough sidecar example:** `shipped-surface-v1.meta.json`
-- **Minimal sidecar example:** `on-deck-v2.meta.json`
+This skill is the **implementation** of `specs/protocols/prototype-lifecycle-protocol.md`. The protocol is the SSOT — when they conflict, the protocol wins and this skill is the bug. Fetch it with `heyspex_get_procedure({ name: "prototype-lifecycle-protocol" })` when you need the full rules.
+
+It applies to:
+
+- explicit `/prototype` invocation
+- any natural-language "build me an HTML prototype / mock / preview / canvas" ask
+- `/frontend-design` invocations in this repo (the plugin builds the artifact; this skill governs placement)
+
+## The contract — no exceptions
+
+**Required output paths** (both files, same commit):
+
+1. `spex-console/public/design-previews/<slug>-v<N>[-<variant>].html` — the self-contained prototype.
+2. `spex-console/public/design-previews/<slug>-v<N>[-<variant>].meta.json` — the sidecar.
+
+Anything outside this folder — including a stray top-level `prototypes/` directory — is **invisible** to the console. The route at `spex-console/src/app/api/ui-design/prototypes/route.ts` reads this folder flat (no recursion, no nested folders). A prototype that doesn't show up in the Prototypes surface does not exist for the user.
+
+## Naming
+
+- **`<slug>`** (lineage slug) — kebab-case, describes the surface (`capture-canvas`, `shipped-surface`, `review-inbox`). May contain hyphens. **Match an existing lineage if you're iterating on a known surface** — grep `spex-console/public/design-previews/` before inventing a new slug.
+- **`-v<N>`** — version, starts at `-v1`. **Bump rather than overwrite.** The console groups versions into a lineage with full history. If `--bump`, increment from the highest existing `-v<N>` for that slug.
+- **`-<variant>`** (optional) — sibling variant within a version (e.g. `-v2-alt`, `-v2-minimal`, `-v2-terminal`). May contain hyphens. The console nests variants under their parent version and shows a `+N variants at vK` chip on the lineage card. Variants are for "A/B explorations of the same version", not new lineages.
+- **No `index.html`, no nested folders, no dated filenames.** Just `<slug>-v<N>[-<variant>].html`.
+
+## meta.json schema
+
+Validate against `specs/schemas/prototype-meta.schema.json`. Required: `title` + `status`. Always set `surface_area` and 1–4 `tags` on new sidecars (the console's filter rail depends on them — leaving them empty makes the prototype harder to find).
+
+```json
+{
+  "title": "Human-readable name (e.g. 'Capture canvas v2')",
+  "description": "One-paragraph summary: what it demonstrates, key interactions, aesthetic direction, technical notes. The console hides this on the card and shows it in the drawer Notes tab — write for that context.",
+  "status": "draft",
+  "surface_area": "capture | on-deck | preloader | shell | review | roadmap | other",
+  "tags": ["kebab-case", "1-to-4"],
+  "updated_at": "2026-06-03T18:17:00.000Z",
+  "design_doc": "specs/ui/<slug>-design.md  (optional but required for promotion to accepted)",
+  "linked_specs": [
+    "HS-XXXX-CAP-...",
+    "HS-XXXX-EPIC-..."
+  ],
+  "parent": "<slug>-v<N-1>.html  (optional, when this iterates on a prior version)",
+  "embeds": ["other-prototype-slug  (optional)"]
+}
+```
+
+- **`status` MUST be `"draft"` at create time.** Promotion to `"accepted"` runs through the console's `/api/ui-design/prototypes/<slug>/promote` route and requires both a linked `design_doc` AND a review entry under `specs/reviews/`. The skill does not write `accepted` — refuse if the user asks. (`"archived"` is for superseded versions; usually set later, not at create time.)
+- **Compute `updated_at` as `new Date().toISOString()`** at write time.
+- **`linked_specs`** accepts vault basenames (no `.md` extension) and `HS-*` IDs. Always include the capture/epic/task the prototype embodies. Pull from `--from-spec` if provided. Never invent IDs.
+- Reference siblings in this folder for examples — `shipped-surface-v1.meta.json` (thorough) or `on-deck-v2.meta.json` (minimal).
+
+## Workflow
+
+When this skill is invoked or matched:
+
+1. **Resolve lineage slug.** Match an existing slug if iterating on a known surface; otherwise pick a new kebab-case slug.
+2. **Resolve version.** Default `-v1`. If a file with the same slug already exists, default to bumping to the next integer; honour explicit `--bump`. **Never silently overwrite** — if the target file exists and `--bump` was not passed, surface the conflict and ask.
+3. **Resolve variant.** `--variant <name>` produces `<slug>-v<N>-<name>.html`. Without it, you produce the base variant.
+4. **Pull source spec context.** If `--from-spec HS-XXXX` is passed or the user references a spec, Read it first so the prototype reflects real content, not invented filler.
+5. **Aesthetic.** Defer to the user's brief (e.g. "Claude-in-PowerShell terminal aesthetic" overrides defaults). Otherwise honour console design-system tokens — fetch via `heyspex_design_*` MCP tools, do not grep `spex-console/DESIGN.md`. Recall UI memories first: `heyspex_recall_memories({ tags: ["ui", "console", "design-system"] })`.
+6. **Decide `surface_area` and `tags`.** Pick `surface_area` from the enum based on what the prototype shows. Pick 1–4 lowercase kebab-case `tags` covering the dominant patterns (e.g. `empty-state`, `dark-mode`, `keyboard-nav`).
+7. **Write both files in the same commit.** HTML at `spex-console/public/design-previews/<slug>-v<N>[-<variant>].html`, sidecar at the matching `.meta.json` path. Single self-contained HTML file (inline CSS/JS).
+8. **Validate the sidecar shape** against the schema before saving. Required: `title` + `status`. `status` MUST be `"draft"`. `tags` MUST match `^[a-z0-9-]+$`. `surface_area` MUST be in the enum. `linked_specs[]` items MUST match `^HS-[A-Z0-9]+-` (family keys contain digits, e.g. `HS-9HVY-CAP`). Fix and re-write if any fail.
+9. **Confirm.** After writing, report the gallery URL (`/design-previews/<slug>-v<N>[-<variant>].html`). The console's UI-Design → Prototypes surface picks it up via `/api/ui-design/prototypes` and groups it into the matching lineage automatically.
+
+## Anti-patterns — do not do these
+
+- Do **not** create a new `prototypes/` folder at the repo root.
+- Do **not** nest as `<slug>/index.html`.
+- Do **not** overwrite an existing `<slug>-v<N>[-<variant>].html` — bump or use a new variant.
+- Do **not** ship without a sibling sidecar.
+- Do **not** write `status: "accepted"` from this skill — promotion runs through the console's `/promote` route only.
+- Do **not** invent linked specs. Only reference `HS-*` IDs that exist in the vault.
+- Do **not** leave `surface_area` and `tags` empty on new sidecars — the console's filter rail depends on them.
+- Do **not** Read `spex-console/DESIGN.md` for token lookups; use `heyspex_design_get_token` / `heyspex_design_get_pattern` MCP tools.
+
+## Reference
+
+- **Protocol (SSOT):** `specs/protocols/prototype-lifecycle-protocol.md` — fetch with `heyspex_get_procedure({ name: "prototype-lifecycle-protocol" })`
+- **Schema (SSOT):** `specs/schemas/prototype-meta.schema.json`
+- **Discovery route:** `spex-console/src/app/api/ui-design/prototypes/route.ts`
+- **Surface component:** `spex-console/src/components/surfaces/ui-design-surface.tsx`
+- **Lineage parser:** `spex-console/src/lib/prototype-lineage.ts`
+- **Folder:** `spex-console/public/design-previews/`
+- **Thorough sidecar example:** `shipped-surface-v1.meta.json`
+- **Minimal sidecar example:** `on-deck-v2.meta.json`

package/docs/copilot-plugin-install.md

@@ -52,6 +52,13 @@ npm install ./heyspex-<version>.tgz
 npx hs login
 ```
 
+- For research (`/hs-res`) only: Docker Desktop running a self-hosted Firecrawl stack on this
+  machine (official steps: `SELF_HOST.md` in github.com/firecrawl/firecrawl: clone it, add a
+  `.env` with `PORT=3002` and `USE_DB_AUTHENTICATION=false`, then
+  `docker compose build && docker compose up -d`). No env var or API key: the packaged Firecrawl
+  CLI finds it through `docker ps` / localhost:3002. Check it with
+  `node node_modules/heyspex/dev-factory/spexcrawl/firecrawl-cli.mjs search "test" --json`.
+
 ## 2. Pick ONE: the plugin or the repo hooks (never both)
 
 Copilot reads hooks from an installed plugin and from `.github/hooks/` in the repo. With both,

package/docs/mcp-client-config.md

@@ -42,6 +42,12 @@ name, which is unambiguous:
 npx --yes --package heyspex heyspex-mcp
 ```
 
+**Research prerequisite (`/hs-res` only).** Docker Desktop running a self-hosted Firecrawl stack
+on this machine (official steps: `SELF_HOST.md` in github.com/firecrawl/firecrawl: clone it, add a
+`.env` with `PORT=3002` and `USE_DB_AUTHENTICATION=false`, then
+`docker compose build && docker compose up -d`). No env var or API key: the packaged Firecrawl CLI
+finds it through `docker ps` / localhost:3002.
+
 **What the agent kit injects at session start.** With the kit hooks installed (`hs install` /
 `hs connect`, or the plugin), the `inject-doctrine` SessionStart hook adds the **baseline
 edition of SpexCode Doctrine** to each session: a short list of general working principles

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "heyspex",
-  "version": "0.2.6",
+  "version": "0.2.7",
   "description": "HeySpex CLI + MCP server — connect Claude Code, Cursor, and any MCP client to your HeySpex spec vault",
   "keywords": [
     "heyspex",
@@ -66,6 +66,8 @@
     "dev-factory/lib/model-catalog.mjs",
     "dev-factory/model-catalog.json",
     "dev-factory/spexcrawl/spexcrawl-cli.mjs",
+    "dev-factory/spexcrawl/firecrawl-cli.mjs",
+    "dev-factory/lib/local-firecrawl.mjs",
     "docs/mcp-client-config.md",
     "docs/copilot-plugin-install.md",
     "docs/driving-heyspex-from-copilot.md",
@@ -97,6 +99,7 @@
     "scripts/lib/heyspex-home.mjs",
     "scripts/hs-companion.mjs",
     "scripts/lib/hs-companion-settings.mjs",
+    "scripts/lib/companion-install.mjs",
     "scripts/hs-next.mjs",
     "scripts/hs-mode.mjs",
     "scripts/heyspex-mode.mjs",
@@ -189,6 +192,7 @@
   "scripts": {
     "prepack": "node scripts/sync-skills.mjs && node scripts/build-cli-bundle.mjs && node scripts/prepack-closure-gate.mjs && node scripts/pack-manifest.mjs strip",
     "postpack": "node scripts/pack-manifest.mjs restore",
+    "prepublishOnly": "node scripts/install-qc.mjs",
     "build:cli": "node scripts/build-cli-bundle.mjs",
     "setup": "node scripts/heyspex-doctor.mjs --fix",
     "doctor": "node scripts/heyspex-doctor.mjs",
@@ -254,8 +258,9 @@
     "test:harness": "node --test spexharness/**/*.test.mjs",
     "verify:package": "node scripts/verify-mcp-package.mjs",
     "smoke:packed-install": "node scripts/packed-install.smoke.mjs",
+    "install:qc": "node scripts/install-qc.mjs",
     "verify:onboarding": "node scripts/verify-onboarding-scenario.mjs --fake",
     "sweep": "node scripts/sweep.mjs"
   },
-  "//files": "PUBLISHED SURFACE - every entry is verified by `node scripts/verify-mcp-package.mjs`. It must cover the STATIC import closure of vendor/heyspex-mcp/cli.mjs, plus (since [[HS-LGG2-WW9R-TASK-ship-the-hook-runtime-in-the-npm]]) the customer hook kit: scripts/claude-hooks/_run.mjs, every HOOK_SCOPES customer hook (scripts/lib/customer-kit.mjs) and their static closure under spexharness/src, dev-factory/lib and scripts/ - the hookTargets check names any file that falls out - plus the run-time data files in customer-kit.mjs CUSTOMER_HOOK_DATA (only the baseline edition of SpexCode Doctrine, never the learned spexharness/doctrine/SPEXCODE-DOCTRINE.json; [[HS-A2PO-WW9R-TASK-owner-ruling-does-inject-doctrine-ship]]) - and nothing else. SpexFleet internals (dev-factory/router.mjs, cloud-clients.mjs, cost-tracker.mjs, spexcrawl/) are deliberately absent - research-tools.mjs reaches them through the lazy dev-factory-bridge.mjs. Do not add a path here without re-running the verifier; npm publish is a one-way door ([[HS-ZJSP-0JNK-TASK-ship-the-heyspex-mcp-server-as-an]] / [[HS-8DET-0JNK-TASK-confirm-the-open-core-boundary-and]]). `dist/cli/*.mjs` + `dist/cli-templates/**` are a SEPARATE published surface (`hs-init`, `hs-install`, `hs-claim`, `hs-check`, `hs-env`, `hs-connect`, `hs-join`, `hs-vault`, `hs-workspace`, `hs-defer`, `hs-vault-pull`, `hs-vault-push`, `hs-dev`, `hs-index-rebuild`, `hs-index-reconcile`, `hs-handoff`, `hs-pin`, `hs-events`, `hs-export-events`, `hs-prereq`, `hs-trash`, `hs-trust`, `hs-next-launch`, `hs-revalidate`, `hs-test`, `hs-spawn` bundled by `scripts/build-cli-bundle.mjs`'s `ENTRIES` array, regenerated fresh every `prepack` - `dist/` itself stays git-ignored) - see that script's doc comment for the entry scope decision and [[HS-JOQX-0JNK-TASK-published-package-runs-hs-init-and-hs]]."
+  "//files": "PUBLISHED SURFACE - every entry is verified by `node scripts/verify-mcp-package.mjs`. It must cover the STATIC import closure of vendor/heyspex-mcp/cli.mjs, plus (since [[HS-LGG2-WW9R-TASK-ship-the-hook-runtime-in-the-npm]]) the customer hook kit: scripts/claude-hooks/_run.mjs, every HOOK_SCOPES customer hook (scripts/lib/customer-kit.mjs) and their static closure under spexharness/src, dev-factory/lib and scripts/ - the hookTargets check names any file that falls out - plus the run-time data files in customer-kit.mjs CUSTOMER_HOOK_DATA (only the baseline edition of SpexCode Doctrine, never the learned spexharness/doctrine/SPEXCODE-DOCTRINE.json; [[HS-A2PO-WW9R-TASK-owner-ruling-does-inject-doctrine-ship]]) - and nothing else. SpexFleet internals (dev-factory/router.mjs, cloud-clients.mjs, cost-tracker.mjs, spexcrawl/ except the named research clients spexcrawl-cli.mjs and firecrawl-cli.mjs) are deliberately absent - research-tools.mjs reaches them through the lazy dev-factory-bridge.mjs. Do not add a path here without re-running the verifier; npm publish is a one-way door ([[HS-ZJSP-0JNK-TASK-ship-the-heyspex-mcp-server-as-an]] / [[HS-8DET-0JNK-TASK-confirm-the-open-core-boundary-and]]). `dist/cli/*.mjs` + `dist/cli-templates/**` are a SEPARATE published surface (`hs-init`, `hs-install`, `hs-claim`, `hs-check`, `hs-env`, `hs-connect`, `hs-join`, `hs-vault`, `hs-workspace`, `hs-defer`, `hs-vault-pull`, `hs-vault-push`, `hs-dev`, `hs-index-rebuild`, `hs-index-reconcile`, `hs-handoff`, `hs-pin`, `hs-events`, `hs-export-events`, `hs-prereq`, `hs-trash`, `hs-trust`, `hs-next-launch`, `hs-revalidate`, `hs-test`, `hs-spawn` bundled by `scripts/build-cli-bundle.mjs`'s `ENTRIES` array, regenerated fresh every `prepack` - `dist/` itself stays git-ignored) - see that script's doc comment for the entry scope decision and [[HS-JOQX-0JNK-TASK-published-package-runs-hs-init-and-hs]]."
 }

package/plugins/heyspex/README.md

@@ -45,6 +45,12 @@ npx hs install --target . --plugin-apply # Claude Code
 
 `setup copilot --check` shows which route is active; `--uninstall` removes the hooks file and prints `copilot plugin uninstall heyspex`.
 
+Research prerequisite (`/hs-res` only): Docker Desktop running a self-hosted Firecrawl stack on this machine
+(official steps: `SELF_HOST.md` in github.com/firecrawl/firecrawl: clone it, add a `.env` with `PORT=3002` and
+`USE_DB_AUTHENTICATION=false`, then `docker compose build && docker compose up -d`). No env var or API key: the
+packaged Firecrawl CLI finds it through `docker ps` / localhost:3002. Check it with
+`node node_modules/heyspex/dev-factory/spexcrawl/firecrawl-cli.mjs search "test" --json`.
+
 Fallback, by hand: `claude plugin marketplace add ./node_modules/heyspex` /
 `copilot plugin marketplace add ./node_modules/heyspex`, then `... plugin install heyspex@heyspex-marketplace`.
 Restart the session (`/restart` in Copilot), then check `copilot plugin list` and `npx hs doctor`.

package/plugins/heyspex/bin/launch-mcp.mjs

@@ -106,4 +106,21 @@ try {
   // Older server tree without the helper: its own resolver is the only line of defence.
 }
 
+// HS-2K22 (epic HS-C65J): stamp HEYSPEX_HARNESS for the server so seat defaults follow the harness
+// this plugin was loaded by (Claude Code → Claude models, Copilot → `auto`). Claude Code and
+// Copilot CLI both load this plugin's ONE .mcp.json, so the manifest cannot carry a static value;
+// the stamp comes from positive env markers only (CLAUDE_PLUGIN_ROOT is ambiguous: Copilot expands
+// it too). An explicit HEYSPEX_HARNESS is never overwritten; no marker → nothing is stamped.
+try {
+  if (!process.env.HEYSPEX_HARNESS) {
+    const { harnessStampFor } = await import(
+      pathToFileURL(resolve(dirname(entry), "..", "..", "spexharness", "src", "adapters", "harness-detect.mjs")).href
+    );
+    const stamp = harnessStampFor(process.env);
+    if (stamp) process.env.HEYSPEX_HARNESS = stamp;
+  }
+} catch {
+  // Older package without the detector: the server detects on its own.
+}
+
 await import(pathToFileURL(entry).href);