heyspex 0.2.5 → 0.2.6

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

@@ -7,61 +7,69 @@ description: Confidence-ladder research method's entrypoint — SpexCrawl via th
 
 **Usage:** `/hs-res [research question/topic]`
 
-# Research (`/hs-res`)
-
-> Parity: `.commandcode/skills/hs-res/SKILL.md` · `.cursor/skills/hs-res/SKILL.md` · `.agents/skills/hs-res/SKILL.md`
-
-## What to do
-
-1. **Take the question.** `$ARGUMENTS` is the research question/topic. If empty, load the
-   console doc-toolbar Promote pin via `heyspex_active_research`
-   (`.heyspex/research-focus.yaml` → `source_idea_id`, `scope`, `spec_path`) and read the source
-   capture body as the question. Either way, restate the scope and confirm with the user.
-
-2. **Gather via SpexCrawl (the Companion) — the PRIMARY method** (owner ruling 2026-08-14,
-   [[spexcrawl-through-the-companion-is-the]]: "Companion > SpexCrawl is now default method
-   for research"). Decompose into a few independent search angles, then per angle:
-   `node dev-factory/spexcrawl/spexcrawl-cli.mjs search "<query>" --json` — one call
-   searches AND returns the cleaned pages of the top results. Specific extra URLs:
-   `node dev-factory/spexcrawl/spexcrawl-cli.mjs scrape "<url>" --json`.
-   Prerequisites: the Companion running and paired to the console. LAN mode
-   (`npm run console:log:lan`) is needed ONLY when the Companion runs on a DIFFERENT
-   machine than the console — since HS-V9WH the Companion polls loopback consoles too
-   ([[a-queue-is-dead-if-its-only-consumer]]: the LAN line was a bug workaround
-   misdocumented as a requirement). When missing, the CLI exits 3 with
-   `SPEXCRAWL_UNAVAILABLE` naming the fix; a silent hang means the Companion is not
-   running or not polling this console.
-
-   **Fallback — self-hosted Firecrawl, AUTOMATIC, no permission needed (owner ruling
-   2026-08-22).** When the SpexCrawl path malfunctions, times out, hits a gate, or is otherwise
-   unavailable, fall back immediately: `node dev-factory/spexcrawl/firecrawl-cli.mjs
-   search "<query>" --json` and `node dev-factory/spexcrawl/firecrawl-cli.mjs scrape
-   "<url>" --json`. May run on any fleet machine (coffee-geek, basement-geek, spec-ops) —
-   prefer other reachable machines over the one the orchestrating session runs on; check
-   `docker info`, start Docker/the stack if needed, poll the real endpoint for readiness before
-   use. If this task's changed/claimed files are SpexCrawl-related, skip SpexCrawl entirely and
-   go straight to Firecrawl. Hosted `api.firecrawl.dev` credits are unchanged — still
-   ask-before-spend every time. Full contract: `.commandcode/skills/hs-res/SKILL.md`.
-
-3. **Assemble a numbered sources block** (`[S1]`, `[S2]`, …) from the gathered
-   `{title, url, snippet, markdown}` results, write it plus the question and cite-only
-   instructions to a temp prompt file.
-
-4. **Synthesize via DeepSeek** —
-   `node dev-factory/spexcrawl/synthesize-cli.mjs --prompt-file <path> --json`
-   (defaults `--max-tokens` to 32000 and auto-escalates ×3 up to a 96000 ceiling if DeepSeek's
-   default-on "thinking" mode burns the whole budget on reasoning — never pass a lower
-   `--max-tokens` yourself; the CLI self-heals this failure mode. Exhausted escalation exits 3
-   with `SYNTHESIZE_UNAVAILABLE`).
-
-5. **Save** via `heyspex_save_research` (or `heyspex_complete_research` under the console pin
-   pipeline), with `sources` populated from the gathered URLs.
-
-**Never fall back** to `deep-research`/`deep-research-quick|medium|thorough`, the
-`Workflow({ scriptPath: '.claude/workflows/deep-research-*.js' })` launch, or native
-`WebSearch`/`WebFetch` for this method. Self-hosted Firecrawl fallback is automatic (no
-permission needed, 2026-08-22 ruling); hosted `api.firecrawl.dev` credits still need the
-user's explicit per-run permission, every time. If a CLI reports unavailable
-(`SPEXCRAWL_UNAVAILABLE` / `FIRECRAWL_UNAVAILABLE` / `SYNTHESIZE_UNAVAILABLE`, exit 3),
-**stop** and tell the user — never silently substitute another backend. Full method,
-escalation rule, and hard prohibitions: `.commandcode/skills/hs-res/SKILL.md`.
+# Research (`/hs-res`)
+
+> Parity: `.commandcode/skills/hs-res/SKILL.md` · `.cursor/skills/hs-res/SKILL.md` · `.agents/skills/hs-res/SKILL.md`
+
+## What to do
+
+1. **Take the question.** `$ARGUMENTS` is the research question/topic. If empty, load the
+   console doc-toolbar Promote pin via `heyspex_active_research`
+   (`.heyspex/research-focus.yaml` → `source_idea_id`, `scope`, `spec_path`) and read the source
+   capture body as the question. Either way, restate the scope and confirm with the user.
+
+2. **Gather via SpexCrawl (the Companion) — the PRIMARY method** (owner ruling 2026-08-14,
+   [[spexcrawl-through-the-companion-is-the]]: "Companion > SpexCrawl is now default method
+   for research"). Decompose into a few independent search angles, then per angle:
+   `node dev-factory/spexcrawl/spexcrawl-cli.mjs search "<query>" --json` — one call
+   searches AND returns the cleaned pages of the top results. Specific extra URLs:
+   `node dev-factory/spexcrawl/spexcrawl-cli.mjs scrape "<url>" --json`.
+   Prerequisites: the Companion running and paired to the console. LAN mode
+   (`npm run console:log:lan`) is needed ONLY when the Companion runs on a DIFFERENT
+   machine than the console — since HS-V9WH the Companion polls loopback consoles too
+   ([[a-queue-is-dead-if-its-only-consumer]]: the LAN line was a bug workaround
+   misdocumented as a requirement). When missing, the CLI exits 3 with
+   `SPEXCRAWL_UNAVAILABLE` naming the fix; a silent hang means the Companion is not
+   running or not polling this console.
+
+   **Fallback — self-hosted Firecrawl, AUTOMATIC, no permission needed (owner ruling
+   2026-08-22).** When the SpexCrawl path malfunctions, times out, hits a gate, or is otherwise
+   unavailable, fall back immediately: `node dev-factory/spexcrawl/firecrawl-cli.mjs
+   search "<query>" --json` and `node dev-factory/spexcrawl/firecrawl-cli.mjs scrape
+   "<url>" --json`. May run on any fleet machine (coffee-geek, basement-geek, spec-ops) —
+   prefer other reachable machines over the one the orchestrating session runs on; check
+   `docker info`, start Docker/the stack if needed, poll the real endpoint for readiness before
+   use. If this task's changed/claimed files are SpexCrawl-related, skip SpexCrawl entirely and
+   go straight to Firecrawl. Hosted `api.firecrawl.dev` credits are unchanged — still
+   ask-before-spend every time. Full contract: `.commandcode/skills/hs-res/SKILL.md`.
+
+   **In a repo that uses the `heyspex` npm package** (not a HeySpex platform checkout): the
+   package ships only the SpexCrawl client (`dev-factory/spexcrawl/spexcrawl-cli.mjs` under
+   `node_modules/heyspex/`). It needs the HeySpex Companion, which the npm package does not
+   distribute yet, so it usually exits 3 `SPEXCRAWL_UNAVAILABLE`. The Firecrawl fallback and
+   the DeepSeek synthesis CLI (`firecrawl-cli.mjs`, `synthesize-cli.mjs`) are HeySpex-platform
+   only and are not in the package. When a CLI named in steps 2 or 4 is missing or reports
+   unavailable, stop and tell the user this research method is not available in their install.
+
+3. **Assemble a numbered sources block** (`[S1]`, `[S2]`, …) from the gathered
+   `{title, url, snippet, markdown}` results, write it plus the question and cite-only
+   instructions to a temp prompt file.
+
+4. **Synthesize via DeepSeek** —
+   `node dev-factory/spexcrawl/synthesize-cli.mjs --prompt-file <path> --json`
+   (defaults `--max-tokens` to 32000 and auto-escalates ×3 up to a 96000 ceiling if DeepSeek's
+   default-on "thinking" mode burns the whole budget on reasoning — never pass a lower
+   `--max-tokens` yourself; the CLI self-heals this failure mode. Exhausted escalation exits 3
+   with `SYNTHESIZE_UNAVAILABLE`).
+
+5. **Save** via `heyspex_save_research` (or `heyspex_complete_research` under the console pin
+   pipeline), with `sources` populated from the gathered URLs.
+
+**Never fall back** to `deep-research`/`deep-research-quick|medium|thorough`, the
+`Workflow({ scriptPath: '.claude/workflows/deep-research-*.js' })` launch, or native
+`WebSearch`/`WebFetch` for this method. Self-hosted Firecrawl fallback is automatic (no
+permission needed, 2026-08-22 ruling); hosted `api.firecrawl.dev` credits still need the
+user's explicit per-run permission, every time. If a CLI reports unavailable
+(`SPEXCRAWL_UNAVAILABLE` / `FIRECRAWL_UNAVAILABLE` / `SYNTHESIZE_UNAVAILABLE`, exit 3),
+**stop** and tell the user — never silently substitute another backend. Full method,
+escalation rule, and hard prohibitions: `.commandcode/skills/hs-res/SKILL.md`.

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: