heyspex 0.2.0 → 0.2.2

package/dist/cli-templates/harness-commands/cursor/hs-resolve.md

@@ -7,20 +7,20 @@ description: Pull the top open item from the HeySpex Resolution lane (conflicts,
 
 **Usage:** `/hs-resolve [HS-XXXX-EPIC | <item-key> | --ignore-focus]`
 
-Invoke the `heyspex_next_resolution` MCP tool to fetch the top open resolution item from the HeySpex vault, then paste the returned `prompt_markdown` verbatim so the user can act on the fix brief.
-
-Argument parsing for `$ARGUMENTS` (all optional; if empty, call the tool with no parameters):
-
-- A token containing `:` (e.g. `dangling_ref:hs-epic-x:hs-task-y`) → pass as `item_key` (fetch that specific item's brief; bypasses the focus pin).
-- A bare spec id matching `HS-EPIC-*` / `HS-TASK-*` / `HS-MIL-*` / `HS-*-*` → pass as `scope` (deck-aware: restrict detection to that spec so its gating prerequisite/conflicts surface). This is what the On-Deck `resolve_command: /hs-resolve <epic-id>` passes.
-- `--ignore-focus` → set `ignore_focus: true` (skip the Neon resolution focus pin; lead with the top-ranked open item).
-
-Resolution precedence (built into the tool — do not re-implement): `item_key` → `scope`/`ignore_focus` (top-ranked of the open list) → the Neon focus pin (server-applied) → top-ranked open item. Items are ordered with **gating** and **errors first** (`orderResolutionItems`).
-
-After the tool returns, output the `prompt_markdown` field as-is, then on a final line state the source: `_Source: {source} · {item.kind} · {item.key}_`. Do not summarize, paraphrase, or start executing actions from the brief without the user's go-ahead.
-
-This is the surviving `/hs-resolve` (the legacy conflict-only prompt that errored **"Not an Epic"** on a milestone has been retired — the resolver is item-centric and never type-checks the target). Authority from the brief's resolution menu: **Re-scan / clear** is agent-autonomous; **Switch to this**, **Defer**, **edge removal**, and **override** require explicit user confirmation. `stale_index` items expose **only** re-scan/clear — never an edge-mutating action.
-
-Detection is HTTP-only (the tool reads the console aggregator — the one detection path — it does not re-detect). If the tool errors with `CONSOLE_UNREACHABLE`, tell the user to **start the console dev server (port 3000, or run `hs server status` to see which port it actually bound)** — this only happens on a dev machine; SaaS console is always up. On `CONSOLE_TIMEOUT`, suggest retrying shortly (the server may be cold-compiling). On `ITEM_NOT_FOUND`, the `item_key` is not in the open set — list items with `/hs-resolve` (no args).
-
-This skill does NOT claim or build anything; it presents the fix brief. Sibling skills: `/hs-next` (build pipeline), `/hs-review` (review pipeline), `/hs-resolve` (this — resolution lane). See [[HS-0EJ6-RMCP-EPIC-hs-resolve-mcp-tool-and-skill]] and [[HS-I8FM-RSRF-EPIC-resolution-surface-api-and-pin]].
+Invoke the `heyspex_next_resolution` MCP tool to fetch the top open resolution item from the HeySpex vault, then paste the returned `prompt_markdown` verbatim so the user can act on the fix brief.
+
+Argument parsing for `$ARGUMENTS` (all optional; if empty, call the tool with no parameters):
+
+- A token containing `:` (e.g. `dangling_ref:hs-epic-x:hs-task-y`) → pass as `item_key` (fetch that specific item's brief; bypasses the focus pin).
+- A bare spec id matching `HS-EPIC-*` / `HS-TASK-*` / `HS-MIL-*` / `HS-*-*` → pass as `scope` (deck-aware: restrict detection to that spec so its gating prerequisite/conflicts surface). This is what the On-Deck `resolve_command: /hs-resolve <epic-id>` passes.
+- `--ignore-focus` → set `ignore_focus: true` (skip the Neon resolution focus pin; lead with the top-ranked open item).
+
+Resolution precedence (built into the tool — do not re-implement): `item_key` → `scope`/`ignore_focus` (top-ranked of the open list) → the Neon focus pin (server-applied) → top-ranked open item. Items are ordered with **gating** and **errors first** (`orderResolutionItems`).
+
+After the tool returns, output the `prompt_markdown` field as-is, then on a final line state the source: `_Source: {source} · {item.kind} · {item.key}_`. Do not summarize, paraphrase, or start executing actions from the brief without the user's go-ahead.
+
+This is the surviving `/hs-resolve` (the legacy conflict-only prompt that errored **"Not an Epic"** on a milestone has been retired — the resolver is item-centric and never type-checks the target). Authority from the brief's resolution menu: **Re-scan / clear** is agent-autonomous; **Switch to this**, **Defer**, **edge removal**, and **override** require explicit user confirmation. `stale_index` items expose **only** re-scan/clear — never an edge-mutating action.
+
+Detection is HTTP-only (the tool reads the console aggregator — the one detection path — it does not re-detect). If the tool errors with `CONSOLE_UNREACHABLE`, tell the user to **start the console dev server (port 3000, or run `hs server status` to see which port it actually bound)** — this only happens on a dev machine; SaaS console is always up. On `CONSOLE_TIMEOUT`, suggest retrying shortly (the server may be cold-compiling). On `ITEM_NOT_FOUND`, the `item_key` is not in the open set — list items with `/hs-resolve` (no args).
+
+This skill does NOT claim or build anything; it presents the fix brief. Sibling skills: `/hs-next` (build pipeline), `/hs-review` (review pipeline), `/hs-resolve` (this — resolution lane). See [[HS-0EJ6-RMCP-EPIC-hs-resolve-mcp-tool-and-skill]] and [[HS-I8FM-RSRF-EPIC-resolution-surface-api-and-pin]].

package/dist/cli-templates/harness-commands/cursor/hs-review.md

@@ -7,20 +7,20 @@ description: Pull the next review-ready spec from the HeySpex review queue (revi
 
 **Usage:** `/hs-review [HS-XXXX-TASK | HS-XXXX-EPIC] [--ignore-focus]`
 
-Invoke the `heyspex_next_review` MCP tool to fetch the next review-ready spec from the HeySpex vault, then paste the returned `prompt_markdown` verbatim so the user (reviewer) can walk acceptance against the parent spec + HS-REV companion.
-
-Argument parsing for `$ARGUMENTS` (all optional; if `$ARGUMENTS` is empty, call the tool with no parameters):
-
-- A bare token matching `HS-TASK-*` / `HS-EPIC-*` / `HS-*-*` → pass as `spec_id`.
-- A bare token matching `HS-ROADMAP-*` → pass as `roadmap_id`.
-- `--ignore-focus` → set `ignore_focus: true`.
-
-Resolution precedence (built into the tool, do not re-implement here): `args.spec_id` → `.heyspex/review-focus.yaml` pin → manifest traversal for `status: in_review` specs with an `HS-REV-<suffix>-*.md` companion → folder scan as fallback. Sorted by `updated:` ascending (oldest first).
-
-After the tool returns, output the `prompt_markdown` field as-is, then on a final line state the source: `_Source: {source_kind} · {spec_id} · phase {phase_id} · age {age_in_review_days}d_`. Do not summarize, paraphrase, or start executing the returned prompt.
-
-This skill does NOT claim the spec. Reviewing is a human-in-loop activity by design (CLAUDE.md §Session Completion); the reviewer walks the four sections of the HS-REV companion (`## Acceptance verification`, `## Reviewer notes`, `## Memory candidates`, `## Decision: close or reopen`) and decides pass/reopen. Memory candidates are scored against the four-axis rubric (non-derivability / reusability / surprise-cost / concreteness, 0–3 each, threshold ≥ 7/12) — the prompt body includes the rubric and the conflict-check instruction.
-
-If the tool errors with `NO_REVIEW_READY`, tell the user the review queue is empty (no specs at `status: in_review` with an HS-REV companion) and suggest checking `specs/reviews/` for stale companions or filing the missing review doc. If `SPEC_NOT_IN_REVIEW`, surface the spec's actual status so the user can pick the right `/hs-review HS-XXXX` target. If `NO_REVIEW_DOC`, the parent spec is `in_review` but has no `HS-REV-<suffix>-*.md` companion — point the user at CLAUDE.md §Session Completion §3 for the four-section template.
-
-Cross-reference: [[HS-XRO1-RVDC-TASK-heyspex-review-on-deck-mcp-and-hs-review]] (spec), [[HS-UKD6-CLR4-RES-close-out-review-screen-jtbd-architecture]] §J17 (downstream Review surface that will call this tool from the "Copy `/hs-review`" affordance).
+Invoke the `heyspex_next_review` MCP tool to fetch the next review-ready spec from the HeySpex vault, then paste the returned `prompt_markdown` verbatim so the user (reviewer) can walk acceptance against the parent spec + HS-REV companion.
+
+Argument parsing for `$ARGUMENTS` (all optional; if `$ARGUMENTS` is empty, call the tool with no parameters):
+
+- A bare token matching `HS-TASK-*` / `HS-EPIC-*` / `HS-*-*` → pass as `spec_id`.
+- A bare token matching `HS-ROADMAP-*` → pass as `roadmap_id`.
+- `--ignore-focus` → set `ignore_focus: true`.
+
+Resolution precedence (built into the tool, do not re-implement here): `args.spec_id` → `.heyspex/review-focus.yaml` pin → manifest traversal for `status: in_review` specs with an `HS-REV-<suffix>-*.md` companion → folder scan as fallback. Sorted by `updated:` ascending (oldest first).
+
+After the tool returns, output the `prompt_markdown` field as-is, then on a final line state the source: `_Source: {source_kind} · {spec_id} · phase {phase_id} · age {age_in_review_days}d_`. Do not summarize, paraphrase, or start executing the returned prompt.
+
+This skill does NOT claim the spec. Reviewing is a human-in-loop activity by design (CLAUDE.md §Session Completion); the reviewer walks the four sections of the HS-REV companion (`## Acceptance verification`, `## Reviewer notes`, `## Memory candidates`, `## Decision: close or reopen`) and decides pass/reopen. Memory candidates are scored against the four-axis rubric (non-derivability / reusability / surprise-cost / concreteness, 0–3 each, threshold ≥ 7/12) — the prompt body includes the rubric and the conflict-check instruction.
+
+If the tool errors with `NO_REVIEW_READY`, tell the user the review queue is empty (no specs at `status: in_review` with an HS-REV companion) and suggest checking `specs/reviews/` for stale companions or filing the missing review doc. If `SPEC_NOT_IN_REVIEW`, surface the spec's actual status so the user can pick the right `/hs-review HS-XXXX` target. If `NO_REVIEW_DOC`, the parent spec is `in_review` but has no `HS-REV-<suffix>-*.md` companion — point the user at CLAUDE.md §Session Completion §3 for the four-section template.
+
+Cross-reference: [[HS-XRO1-RVDC-TASK-heyspex-review-on-deck-mcp-and-hs-review]] (spec), [[HS-UKD6-CLR4-RES-close-out-review-screen-jtbd-architecture]] §J17 (downstream Review surface that will call this tool from the "Copy `/hs-review`" affordance).

package/dist/cli-templates/harness-commands/cursor/hs-view.md

@@ -1,30 +1,32 @@
 ---
 name: hs-view
-description: Open one console surface in a chromeless app-mode browser window (solo console gauge) — pipeline funnel first; follows the focus pin when no doc id is given. Thin wrapper over `hs view`.
+description: Open one console surface in a chromeless app-mode browser window (solo console gauge) — the inspector's Pipeline tab first; follows the focus pin when no doc id is given. Thin wrapper over `hs view`.
 ---
 
 <!-- Generated by scripts/sync-skills.mjs from .claude/commands/hs-view.md — do not edit by hand. Run `npm run skills:sync`. -->
 
 **Usage:** `/hs-view [surface] [doc id] [--width N] [--height N] [--browser edge|chrome]`
 
-# HeySpex solo-surface viewer (`/hs-view`)
-
-> Parity: `.commandcode/skills/hs-view/SKILL.md` · `.cursor/skills/hs-view/SKILL.md` · `.agents/skills/hs-view/SKILL.md`
-
-Optional macro over the one core ([[capability-three-faces-no-per-capability-slash]]): shell to `hs view`, never reimplement it. Design: [[HS-RU2R-I87U-RES-solo-surface-cli-launcher-single]].
-
-## What to do
-
-1. **Resolve `$ARGUMENTS` by smart first-token detection** — grammar is positional, token-identical with the CLI:
-   - First token looks like a spec id (`HS-…`) → doc id; surface defaults to `pipeline`.
-   - First token is a surface slug (`pipeline`, `docs`, `whats-next`, `captures`, `session-log`, `settings`) → second token, if present, is the doc id (anchors `pipeline` and `docs` only).
-   - No arguments → `pipeline`, anchored on the focus pin (live-follow).
-   - Pass `--width` / `--height` / `--browser edge|chrome` through unchanged.
-2. **Run it yourself** from the repo root:
-   ```bash
-   node bin/hs.mjs view <surface> [<doc-id>] [flags]
-   ```
-3. The verb probes ground-truth dev-server status first — if the console is down, relay its message and offer `npm run dev` (don't start the server unprompted).
-4. Relay the one-line result (URL + window size); closing the window closes it, re-running reopens it.
-
-Never hand-build `msedge --app=…` invocations — the CLI verb owns server probing, URL resolution, and browser mechanics.
+# HeySpex solo-surface viewer (`/hs-view`)
+
+> Parity: `.commandcode/skills/hs-view/SKILL.md` · `.cursor/skills/hs-view/SKILL.md` · `.agents/skills/hs-view/SKILL.md`
+
+Optional macro over the one core ([[capability-three-faces-no-per-capability-slash]]): shell to `hs view`, never reimplement it. Design: [[HS-RU2R-I87U-RES-solo-surface-cli-launcher-single]].
+
+## What to do
+
+1. **Resolve `$ARGUMENTS` by smart first-token detection** — grammar is positional, token-identical with the CLI:
+   - First token is not a surface slug → it is the doc id, in any form (`hlfj`, `hs-hlfj`, `HS-HLFJ`, a full basename); opens the inspector on its Pipeline tab. Pass it through as typed — the CLI normalises it.
+   - First token is a surface slug (`inspector`, `docs`, `whats-next`, `captures`, `session-log`, `settings`) → second token, if present, is the doc id (anchors `inspector` and `docs` only).
+   - `pipeline` is accepted but is not its own window: it is the inspector on its Pipeline tab.
+   - `docs` opens two panes: the doc beside the inspector on its Pipeline tab.
+   - No arguments → the inspector on its Pipeline tab, anchored on the focus pin (live-follow).
+   - Pass `--width` / `--height` / `--browser edge|chrome` through unchanged.
+2. **Run it yourself** from the repo root:
+   ```bash
+   node bin/hs.mjs view [<surface>] [<doc-id>] [flags]
+   ```
+3. The verb probes ground-truth dev-server status first — if the console is down, relay its message and offer `npm run dev` (don't start the server unprompted).
+4. Relay the one-line result (URL + window size); closing the window closes it, re-running reopens it.
+
+Never hand-build `msedge --app=…` invocations — the CLI verb owns server probing, URL resolution, and browser mechanics.

package/dist/cli-templates/harness-commands/cursor/kill-ports.md

@@ -7,29 +7,29 @@ description: Kill every process listening on a TCP port in the range 3000–5999
 
 **Usage:** `/kill-ports (no arguments)`
 
-**Always use the PowerShell tool for this command — never the Bash tool.** Bash routes to a POSIX shell in this environment and the PowerShell syntax below will fail there.
-
-Kill all processes that are **listening** on TCP ports in the range **3000–5999** inclusive. This clears orphaned dev servers (Next.js, console, companion bridges, etc.) that are holding ports.
-
-Run this single command via the **PowerShell** tool. It discovers the listening connections in range, reports each `port → pid (process name)` it is about to kill, then force-kills the unique owning PIDs and confirms:
-
-```powershell
-$conns = Get-NetTCPConnection -State Listen -ErrorAction SilentlyContinue |
-  Where-Object { $_.LocalPort -ge 3000 -and $_.LocalPort -le 5999 }
-if (-not $conns) { Write-Output 'No listeners on ports 3000-5999. Nothing to kill.'; return }
-$pids = $conns | Select-Object -ExpandProperty OwningProcess -Unique
-foreach ($c in $conns) {
-  $p = Get-Process -Id $c.OwningProcess -ErrorAction SilentlyContinue
-  $name = if ($p) { $p.ProcessName } else { '?' }
-  Write-Output ("port {0,-5} -> pid {1} ({2})" -f $c.LocalPort, $c.OwningProcess, $name)
-}
-foreach ($procId in $pids) {
-  try { Stop-Process -Id $procId -Force -ErrorAction Stop; Write-Output ("killed pid {0}" -f $procId) }
-  catch { Write-Output ("could not kill pid {0}: {1}" -f $procId, $_.Exception.Message) }
-}
-```
-
-Notes:
-- Only TCP **listeners** are targeted, so client/outbound connections in that range are left alone.
-- If `Stop-Process` fails on a PID (e.g. a Windows system process like `svchost`, which needs admin and shouldn't be killed anyway, or a process that already exited), report the `Access is denied` / error and continue with the rest — do not abort the whole run.
-- After running, briefly summarize how many ports were freed.
+**Always use the PowerShell tool for this command — never the Bash tool.** Bash routes to a POSIX shell in this environment and the PowerShell syntax below will fail there.
+
+Kill all processes that are **listening** on TCP ports in the range **3000–5999** inclusive. This clears orphaned dev servers (Next.js, console, companion bridges, etc.) that are holding ports.
+
+Run this single command via the **PowerShell** tool. It discovers the listening connections in range, reports each `port → pid (process name)` it is about to kill, then force-kills the unique owning PIDs and confirms:
+
+```powershell
+$conns = Get-NetTCPConnection -State Listen -ErrorAction SilentlyContinue |
+  Where-Object { $_.LocalPort -ge 3000 -and $_.LocalPort -le 5999 }
+if (-not $conns) { Write-Output 'No listeners on ports 3000-5999. Nothing to kill.'; return }
+$pids = $conns | Select-Object -ExpandProperty OwningProcess -Unique
+foreach ($c in $conns) {
+  $p = Get-Process -Id $c.OwningProcess -ErrorAction SilentlyContinue
+  $name = if ($p) { $p.ProcessName } else { '?' }
+  Write-Output ("port {0,-5} -> pid {1} ({2})" -f $c.LocalPort, $c.OwningProcess, $name)
+}
+foreach ($procId in $pids) {
+  try { Stop-Process -Id $procId -Force -ErrorAction Stop; Write-Output ("killed pid {0}" -f $procId) }
+  catch { Write-Output ("could not kill pid {0}: {1}" -f $procId, $_.Exception.Message) }
+}
+```
+
+Notes:
+- Only TCP **listeners** are targeted, so client/outbound connections in that range are left alone.
+- If `Stop-Process` fails on a PID (e.g. a Windows system process like `svchost`, which needs admin and shouldn't be killed anyway, or a process that already exited), report the `Access is denied` / error and continue with the rest — do not abort the whole run.
+- After running, briefly summarize how many ports were freed.

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

@@ -0,0 +1,177 @@
+# Installing the HeySpex (SpexCode) plugin in GitHub Copilot CLI
+
+Instructions written to be handed verbatim to a GitHub Copilot CLI agent. Follow the steps in
+order and stop at any step that fails, reporting the exact output.
+
+This guide is for a team that installs only the `heyspex` npm package. The heyspex-app repository
+is not needed and is not available to customers.
+
+Source of truth for the Copilot commands and file layout:
+<https://docs.github.com/en/copilot/reference/copilot-cli-reference/cli-plugin-reference>.
+Hook behaviour under Copilot: <https://docs.github.com/en/copilot/reference/hooks-configuration>.
+Both pages were read on 2026-10-16. The plugin itself is documented in `node_modules/heyspex/plugins/heyspex/README.md`.
+
+## 0. The short version
+
+From the root of your repo, after `npm install heyspex`:
+
+```bash
+npx heyspex setup copilot            # plugin route (Copilot CLI): registers the marketplace and installs the plugin
+npx heyspex setup copilot --hooks    # hooks route (Copilot cloud agent / no plugin): writes .github/hooks/heyspex.json
+npx heyspex setup copilot --check    # which route is active; warns if both are
+npx heyspex setup copilot --uninstall
+```
+
+To have an agent do it, paste it the output of `npx heyspex setup copilot --print` (this document,
+preceded by the exact next command). If `copilot` is not on PATH, the plugin route prints the two
+commands to run instead. Pick ONE route, never both. The manual commands below remain the fallback.
+
+## 1. Prerequisites
+
+The heyspex-app repository is not required and is not available to customers. Everything below
+works from the published npm package `heyspex` (or a tarball your HeySpex contact hands you), which
+carries the plugin, the marketplace manifest, the hooks and the MCP server.
+
+- Node.js 20 or newer on PATH (`node --version`).
+- GitHub Copilot CLI installed and signed in (`copilot --version`).
+- A git repo of your own (the one you want governed). From its root, install the package:
+
+```bash
+npm install heyspex
+# or, from a tarball you were given:
+npm install ./heyspex-0.2.0.tgz
+```
+
+- Sign the machine in to the HeySpex console so hooks and MCP tools can reach the vault:
+
+```bash
+npx hs login
+```
+
+## 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,
+every hook runs twice. Choose one.
+
+**Option A: the plugin (recommended).** One command registers the marketplace shipped inside the
+package and installs the plugin:
+
+```bash
+npx heyspex setup copilot
+```
+
+(`npx hs install --target . --copilot-plugin-apply` does the same.) By hand, the equivalent Copilot commands are:
+
+```bash
+copilot plugin marketplace add ./node_modules/heyspex
+copilot plugin install heyspex@heyspex-marketplace
+copilot plugin list
+```
+
+`./node_modules/heyspex/.claude-plugin/marketplace.json` is a Claude-format marketplace named
+`heyspex-marketplace`; its plugin `source` (`./plugins/heyspex`) resolves inside the package.
+`npx hs install --target . --copilot-plugin` (no `-apply`) only prints these commands.
+
+**Option B: repo hooks, for teammates and the Copilot cloud agent.** Writes
+`.github/hooks/heyspex.json` into your repo; commit it. Each command runs
+`node_modules/heyspex/scripts/claude-hooks/_run.mjs` and exits 0 if the package is not installed,
+so a checkout without `npm install` is never blocked.
+
+```bash
+npx heyspex setup copilot --hooks
+```
+
+(`npx hs install --target . --copilot-hooks` does the same.) `setup copilot --hooks` refuses when the plugin is already installed. If you pass `--copilot-hooks` together with `--copilot-plugin[-apply]`, the installer warns and
+skips the hooks file.
+
+Then restart the Copilot session (`/restart`) so hooks load, and verify:
+
+```bash
+copilot plugin list      # Option A: heyspex is enabled
+npx hs doctor            # MCP, hooks and account surfaces healthy
+```
+
+## 3. What the plugin loads
+
+| Component | Source | Behaviour under Copilot |
+| --- | --- | --- |
+| Hooks | `node_modules/heyspex/plugins/heyspex/hooks/hooks.json` | PreToolUse, PostToolUse, Stop, UserPromptSubmit and SessionStart gates. Every command locates the runtime itself and exits 0 if it cannot, so a missing variable never denies a tool call. A real deny arrives as a top-level `permissionDecision` with a reason. |
+| MCP server | `node_modules/heyspex/plugins/heyspex/.mcp.json` | The `heyspex_*` vault tools and `hs-*` prompts. |
+| Slash commands | not loaded | Claude Code commands are not a Copilot component. Use MCP prompts or the `hs` CLI. |
+
+## 4. Verify the install
+
+1. In a Copilot session inside any repo, run a harmless tool call, for example read a file. It
+   must succeed. A message containing "Denied by preToolUse hook" means a hook failed; go to
+   section 7.
+2. Confirm the MCP server is up by listing MCP servers in Copilot (`/mcp`) and calling
+   `heyspex_recall_memories` with `{ "limit": 3 }`. If the server is missing, go to section 7.
+3. Confirm the gates work: send a prompt that contains a new product idea of more than 60
+   characters, then try to edit a source file without capturing. The edit should be refused with a
+   reason that names `directive-obligation-gate`. Call `heyspex_update_capture` with the prompt
+   text, then retry the edit. It should pass.
+
+## 5. Turning HeySpex off and on
+
+Run from the repo you are working in:
+
+```bash
+hs mode status     # on | off, and why
+hs mode off        # every hook exits 0 immediately, no restart needed
+hs mode on
+hs mode toggle
+```
+
+Use `npx hs mode off` when `hs` is not on PATH. The switch writes
+`.heyspex/mode.json` in the project and is git-ignored.
+
+Per-shell variants that touch no files:
+
+| Variable | Effect |
+| --- | --- |
+| `HEYSPEX_MODE=off` | Silences hooks for every harness in that shell |
+| `HEYSPEX_COPILOT_HOOKS_OFF=1` | Silences hooks only when the caller is Copilot; Claude Code and Cursor keep theirs |
+
+The config twin of the Copilot switch is `agent_behaviors.harness_hooks.copilot.enabled: false` in
+the vault's `.heyspex/config.yaml`.
+
+Four security gates ignore all of these by design: `env-vault-guard`, `research-method-guard`,
+`research-protocol-gate` and `git-identity-guard`. They only act on secret writes, built-in
+deep-research skills, unprotocolled web research and git identity changes.
+
+## 6. Everyday loop
+
+With MCP available: `heyspex_next_on_deck`, `heyspex_claim_spec`, `heyspex_report_progress`,
+`heyspex_submit_for_review`. Without MCP, the `hs` CLI (`npx hs`) covers the same loop; see
+`docs/driving-heyspex-from-copilot.md`.
+
+## 7. Troubleshooting
+
+- **Every tool call is denied.** Run `hs mode off` to unblock immediately, then capture the exact
+  deny text and the hook command it names. If the command still starts with
+  `node "$CLAUDE_PROJECT_DIR/...`, the package is old; run `npm install heyspex@latest` and reinstall the plugin.
+- **MCP server does not start.** Copilot documents `${PLUGIN_ROOT}` for its own plugin format, and
+  whether it expands `${CLAUDE_PLUGIN_ROOT}` in a Claude-format plugin is unverified. Register the
+  server explicitly:
+
+```bash
+copilot mcp add heyspex -- node ./node_modules/heyspex/plugins/heyspex/bin/launch-mcp.mjs
+```
+
+- **A hook denies with no reason shown.** That is a hook exiting 2 the old way. Report the hook
+  name; it should be answering in Copilot's JSON format.
+- **Hooks run twice.** The repo you are in also carries HeySpex rows in its own
+  `.claude/settings.json` from `hs install`. Use either the plugin or the install kit (or `.github/hooks`) in one repo,
+  not both.
+
+## 8. Report back
+
+State the Copilot CLI version, the output of `copilot plugin list`, the result of the three checks
+in section 4, and the exact text of any deny or MCP error.
+
+## Status of this document
+
+The install commands come from GitHub's plugin reference, and the hook behaviour was verified by
+replaying Copilot-shaped payloads through the registered commands, not by a live Copilot session.
+The first agent that completes section 4 is the real test. Fix history: diagnose HS-20SW and
+capture HS-HNO1 (2026-10-16).