heyspex 0.2.5 → 0.2.7

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

@@ -32,7 +32,7 @@ The heyspex-app repository is not required and is not available to customers. Ev
 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`).
+- Node.js 20–24 on PATH (`node --version`; the package requires `>=20 <25`).
 - GitHub Copilot CLI installed and signed in. Any one of: the GitHub Copilot app (its bundled
   `%LOCALAPPDATA%\github-copilot-sdk\cli\<version>\copilot.exe` is auto-detected, newest version
   wins, no PATH entry needed), `npm install -g @github/copilot`, or `winget install GitHub.Copilot`.
@@ -43,7 +43,7 @@ carries the plugin, the marketplace manifest, the hooks and the MCP server.
 ```bash
 npm install heyspex
 # or, from a tarball you were given:
-npm install ./heyspex-0.2.0.tgz
+npm install ./heyspex-<version>.tgz
 ```
 
 - Sign the machine in to the HeySpex console so hooks and MCP tools can reach the vault:
@@ -52,6 +52,13 @@ npm install ./heyspex-0.2.0.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