@lincoln504/pi-research 0.1.13 → 1.0.1

package/scripts/prepare.cjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+
+/**
+ * Build all distribution artifacts.
+ *
+ * esbuild is a regular dependency, so it is always available on any install
+ * (including git installs and --omit=dev). dist/ is not tracked in git;
+ * this script always builds the artifacts from source.
+ *
+ * Artifacts built:
+ *   - dist/thread-worker.mjs       (browser worker, via build:worker)
+ *   - dist/cli.mjs (+ dist/prompts, dist/webgpu-probe.mjs)  (pi-research CLI binary, via build:cli)
+ *   - skills/pi-research/scripts/run.mjs  (skill launcher, via build:skill)
+ */
+
+'use strict';
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+
+try {
+  execSync('node scripts/build.cjs all', { stdio: 'inherit', cwd: ROOT });
+} catch (err) {
+  console.error('[prepare] Build failed:', err.message);
+  process.exit(1);
+}

package/scripts/setup.cjs

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+/**
+ * pi-research postinstall setup.
+ * Installs Camoufox browser binaries.
+ * Never exits with code 1 — that would break npm install.
+ *
+ * Environment:
+ *   PLAYWRIGHT_BROWSERS_PATH            - override browser install location
+ *   PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1  - skip download entirely
+ *   PLAYWRIGHT_INSTALL_DEPS=true        - also install Linux system deps (or pass --system-deps)
+ */
+
+const { execSync } = require('child_process');
+const { existsSync, readdirSync, statSync } = require('fs');
+const { homedir } = require('os');
+const path = require('path');
+
+// __dirname / __filename are built-in globals in CommonJS (.cjs) modules
+const projectRoot = path.join(__dirname, '..');
+
+const isLinux = process.platform === 'linux';
+const isDarwin = process.platform === 'darwin';
+const isWindows = process.platform === 'win32';
+
+const [nodeMajor, nodeMinor] = process.version.replace('v', '').split('.').map((n) => parseInt(n, 10));
+if (nodeMajor < 22 || (nodeMajor === 22 && nodeMinor < 19)) {
+  console.warn(`WARNING: Node.js ${process.version} is below the minimum (>=22.19.0). Upgrade to 22.19.0+.`);
+}
+
+/**
+ * Resolve the camoufox-js binary path.
+ *
+ * In a typical npm install, dependencies are hoisted to the root node_modules,
+ * so the package's own node_modules/ may be empty. We use require.resolve to
+ * find the real location of camoufox-js and derive the bin from there.
+ */
+function resolveCamoufoxBin() {
+  try {
+    const pkgDir = path.dirname(require.resolve('camoufox-js/package.json', { paths: [projectRoot] }));
+    const binDir = path.join(pkgDir, '..', '.bin');
+    // On Windows the executable is the .cmd shim; the extensionless file is a sh
+    // script that only runs via PATHEXT luck. Mirror src ensure-browser.ts.
+    const bin = path.join(binDir, isWindows ? 'camoufox-js.cmd' : 'camoufox-js');
+    if (existsSync(bin)) return bin;
+  } catch (_) { /* fall through */ }
+  return null;
+}
+
+function camoufoxCachePath() {
+  const customPath = process.env.PLAYWRIGHT_BROWSERS_PATH;
+  if (customPath) return customPath;
+
+  if (isWindows) {
+    // Mirror camoufox-js userCacheDir("camoufox") exactly: homedir-based with a
+    // DOUBLED "camoufox" segment. Must match src getWindowsCamoufoxDir().
+    return path.join(homedir(), 'AppData', 'Local', 'camoufox', 'camoufox', 'Cache');
+  }
+  if (isDarwin) return path.join(homedir(), 'Library', 'Caches', 'camoufox');
+  
+  const cacheHome = process.env.XDG_CACHE_HOME || path.join(homedir(), '.cache');
+  return path.join(cacheHome, 'camoufox');
+}
+
+let browsersInstalled = false;
+
+if (process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD === '1') {
+  console.log('pi-research: skipping browser download (PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1)');
+} else {
+  const env = { ...process.env };
+
+  const installDeps = process.argv.includes('--system-deps') || process.env.PLAYWRIGHT_INSTALL_DEPS === 'true';
+  if (installDeps && isLinux) {
+    try {
+      execSync('npx playwright install-deps', { stdio: 'inherit', env: { ...env, PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD: '0' } });
+    } catch (e) {
+      console.warn(`WARNING: could not install system dependencies. Run: sudo apt-get install -y libgbm1 libnss3 libatk1.0-0 libatk-bridge2.0-0 libcups2 libxkbcommon0 libxcomposite1\nReason: ${e instanceof Error ? e.message : String(e)}\n(These are the libraries headless camoufox needs. Xvfb is NOT required for the default headless mode — only add it if you opt into virtual-display mode with PI_RESEARCH_USE_XVFB=true.)`);
+    }
+  }
+
+  const cachePath = camoufoxCachePath();
+  let alreadyInstalled = false;
+  if (existsSync(cachePath)) {
+    try {
+      const versions = readdirSync(cachePath).filter(f => statSync(path.join(cachePath, f)).isDirectory());
+      if (versions.length > 0) {
+        alreadyInstalled = true;
+        console.log(`pi-research: Camoufox already installed at ${cachePath}. Skipping fetch.`);
+      }
+    } catch (e) {
+      console.warn(`pi-research: error checking camoufox path ${cachePath}: ${e instanceof Error ? e.message : String(e)}`);
+    }
+  }
+
+  if (!alreadyInstalled) {
+    try {
+      const bin = resolveCamoufoxBin();
+      const cmd = bin ? `"${bin}" fetch` : 'npx camoufox-js fetch';
+      // Bound the ~100MB download so a stalled/interrupted network fails fast
+      // instead of hanging `npm install` forever (the catch below exits 0, and the
+      // browser is re-fetchable manually). 15 min is ample even on slow links.
+      execSync(cmd, { stdio: 'inherit', env, timeout: 15 * 60 * 1000 });
+      browsersInstalled = true;
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : String(error);
+      console.error('ERROR: Camoufox browser install failed — pi-research will not work.');
+      console.error('Run manually to fix: npx camoufox-js fetch');
+      console.error(`Reason: ${msg}`);
+      process.exit(0);
+    }
+  } else {
+    browsersInstalled = true;
+  }
+}
+
+// Verify
+const cachePath = camoufoxCachePath();
+if (existsSync(cachePath)) {
+  try {
+    const versions = readdirSync(cachePath).filter(f => statSync(path.join(cachePath, f)).isDirectory());
+    console.log(`pi-research: camoufox ready (${versions.join(', ') || 'installed'})`);
+  } catch (e) {
+    console.log(`pi-research: camoufox ready (path check error: ${e instanceof Error ? e.message : String(e)})`);
+  }
+} else if (browsersInstalled) {
+  console.warn(`pi-research: camoufox binary not found at expected path ${cachePath}`);
+}
+
+// On Linux without a display server the browser runs true-headless (renders
+// offscreen, no Xvfb required) — nothing to install. Xvfb is only needed if you
+// opt into the virtual-framebuffer mode with PI_RESEARCH_USE_XVFB=true.
+if (isLinux && !process.env.DISPLAY && !process.env.WAYLAND_DISPLAY) {
+  console.log('pi-research: No display server detected — the browser will run headless (no Xvfb needed). To opt into Xvfb virtual-display mode, set PI_RESEARCH_USE_XVFB=true and install it: sudo apt install xvfb');
+}

package/skills/pi-research/README.md

@@ -0,0 +1,90 @@
+## research — an Agent Skill for pi-research
+
+A portable [Agent Skill](https://agentskills.io/specification) that gives any
+coding agent multi-agent web research by driving the
+[pi-research](https://github.com/Lincoln504/pi-research) engine. It is the same
+engine the `pi` extension uses, packaged as a skill so Claude, Cursor,
+Codex, OpenClaw, and other Agent-Skills-compatible tools can use it.
+
+### What it exposes
+
+Two capabilities, invoked as shell subcommands:
+
+- `research "<query>"` — live multi-agent web research (search + stealth
+  scraping + security databases + Stack Exchange). Returns a cited Markdown report.
+- `knowledge "<query>"` — search the local knowledge store of previously researched
+  findings before doing live research (instant, free; the store is on by
+  default in `global` mode and can be scoped or disabled via `knowledge-config`).
+
+Plus `knowledge-config [set <none|project|global>]` to show or set the per-directory
+knowledge-store mode, and `status` to inspect detection/config without running research.
+
+### How it works
+
+```
+agent  ──Bash──▶  scripts/run.mjs  ──spawns──▶  pi-research engine (dist/cli.mjs)
+                 (finds the engine,                (uses the SDK: init → run → shutdown)
+                  clean errors if missing)              │
+                                                        ▼
+                                              Markdown report → stdout
+```
+
+The launcher (`scripts/run.mjs`) is zero-dependency and locates the engine
+wherever it's installed (`PI_RESEARCH_BIN` / `PI_RESEARCH_PATH` / PATH /
+`node_modules` / `~/.pi/bin`).
+The engine wraps the [pi-research SDK](https://www.npmjs.com/package/@lincoln504/pi-research)
+and fails fast with actionable messages + config locations when the package or a
+model/key is missing.
+
+### Prerequisites
+
+- Node.js >= 22.19.0
+- `pi-research` installed somewhere the launcher can find it, and a model +
+  API key configured. See [`references/configuration.md`](references/configuration.md).
+
+```bash
+npm install -g @lincoln504/pi-research
+node "<skill_dir>/scripts/run.mjs" status  # verify detection
+```
+
+### Install the skill
+
+Recommended. From the pi extension, run `/research-config` and choose
+Install in External Agents. It detects Claude, Codex, and OpenClaw and
+symlinks this skill into each one that is installed. Remove from External Agents
+removes those symlinks (cleanup also runs automatically on `npm uninstall`).
+
+Cursor is not auto-installed — it has no global skills directory and only reads
+project-level `.cursor/skills/`. Symlink it per-project instead (see the table).
+
+Manual. Or symlink this `pi-research/` directory into your agent's skills folder:
+
+| Agent | Location |
+|-------|----------|
+| Claude (personal) | `~/.claude/skills/pi-research/` |
+| Claude (project)   | `<project>/.claude/skills/pi-research/` |
+| Codex CLI (personal) | `~/.codex/skills/pi-research/` |
+| Codex CLI (project)  | `<project>/.codex/skills/pi-research/` |
+| Cursor (project-only) | `<project>/.cursor/skills/pi-research/` |
+| OpenClaw (personal) | `~/.openclaw/skills/pi-research/` |
+
+Then ask your agent to pi-research something — its skill system matches the
+`description` in `SKILL.md` and activates this skill automatically.
+
+### Usage from an agent
+
+```bash
+node "<skill_dir>/scripts/run.mjs" research "solid-state battery progress 2026" --depth 2
+node "<skill_dir>/scripts/run.mjs" knowledge "openai gpt-5 release date"
+node "<skill_dir>/scripts/run.mjs" status
+```
+
+### Files
+
+- `SKILL.md` — the skill definition + system prompt (what agents read).
+- `scripts/run.mjs` — the launcher (compiled from `run.ts`).
+- `references/configuration.md` — model/key setup and the full variable reference.
+
+### License
+
+MIT.

package/skills/pi-research/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: pi-research
+description: "Multi-agent web research for any coding agent. Use for anything requiring current information from the internet — news, trends, product/service/company facts, statistics, people, places, events, APIs, library behavior, or 'what is X / how does X work' questions. Also use to search a local knowledge store of previously researched findings before doing live research. Powered by the pi-research engine (search, stealth scraping, security databases, Stack Exchange). Not for reading local files, running project commands, or analyzing this repository's own source."
+license: MIT
+metadata: { "author": "Lincoln Deen", "version": "1.0.1", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+allowed-tools: Bash(node:*)
+---
+
+# pi-research skill
+
+Run via your shell tool — the **Bash** tool in Claude Code, the **`exec`** tool in
+OpenClaw. `<SKILL_DIR>` is this skill's own directory: substitute the absolute path
+your harness reports for this skill (in OpenClaw, `{baseDir}` resolves to it).
+
+```
+node "<SKILL_DIR>/scripts/run.mjs" research  "<query>" --depth 1
+node "<SKILL_DIR>/scripts/run.mjs" knowledge "<query>" ["<q2>" ...]
+node "<SKILL_DIR>/scripts/run.mjs" status    [--json]
+```
+
+- **stdout** = Markdown report — read and cite it.
+- **stderr** = progress + errors — relay errors, suppress routine progress.
+- **Always set a generous command timeout** so a stalled run can't block forever, but
+  leave plenty of headroom — a real run should finish well inside it:
+  `knowledge` 600000ms · `research --depth 1` 900000ms · `--depth 2` 1200000ms · `--depth 3` 1800000ms.
+- **Background**: append `&` and keep the PID to work while a run completes; otherwise it runs foreground (blocks). Timeouts apply either way.
+
+## Workflow
+
+1. **Knowledge store first (always).** Run one `knowledge` check with the same
+   intent before any live research — it's instant and free.
+   - Complete answer → use it, skip live research.
+   - Partial → note it, fill gaps with `research`.
+   - Exit 78 → store is off in this directory; proceed with `research`. Don't mention it
+     unless the user asks — then see *Knowledge store scope* below to turn it on.
+2. **Live research — always depth `1`.** It's the default and correct for
+   effectively every request; depth 1 already decomposes and parallelises
+   internally, so it covers big/broad/complex/important topics too. Do NOT raise
+   depth on your own judgment.
+   - **Depth `2` — super rare:** only a genuinely ultra-broad or unusually detailed
+     topic where the user signalled they want deeper/thorough work. Unsure → depth 1.
+   - **Depth `3` — never** unless the user explicitly asks for ludicrously deep /
+     exhaustive research ("ultra", "exhaustive", "comprehensive deep-dive", "maximum").
+
+## Reporting back to the user (always)
+
+- **Cite the report's sources.** Carry its URLs/`[n]` references into your answer;
+  attribute each non-trivial claim. Never present researched facts as unsourced;
+  never invent or substitute sources.
+- **Surface the saved file.** If stderr/stdout ends with `Research report saved to: <path>`,
+  give the user that exact path. If absent, no file was written — say nothing about one.
+
+## Exit codes
+
+| Exit | Meaning | Action |
+|------|---------|--------|
+| `0` | Success | Read stdout; cite sources; relay any "saved to: <path>" line. |
+| `78` on `knowledge` | Store disabled/unconfigured | Silent; proceed to `research`. |
+| `78` on `research` | Engine missing or no model/key | **Stop. Relay full stderr** (it shows where to configure). Don't retry until fixed. |
+| `70` | Runtime error | Relay stderr; suggest one retry for transient failures (network, rate limit). |
+| `64` | Bad arguments | Fix args; don't surface unless the query itself is malformed. |
+
+## Knowledge store scope (act on the user's request)
+
+The knowledge store — what `knowledge` searches — is **on by default** (mode `global`) and
+scoped per directory: `global` (one shared store), `project` (this directory only), or `none`
+(off here). The user manages it by **asking you in chat** — they don't have to run anything themselves.
+
+When the user asks you to turn the store off, make it global, or scope it to this project for
+the current directory (or clearly implies a preference), do it on their behalf and tell them
+the new setting. Check the current one first if useful:
+
+```
+node "<SKILL_DIR>/scripts/run.mjs" knowledge-config                    # current mode + where it's set
+node "<SKILL_DIR>/scripts/run.mjs" knowledge-config set none|project|global
+```
+
+The change applies to the current directory on the next run. Never change it unprompted.
+
+## When NOT to use this
+
+WEB / internet research ONLY. Never use it to investigate *this* project (source,
+config, architecture, tests, logs, anything on this machine) — use your own
+Read/Grep/Bash for that. Reach for `pi-research` only when the answer lives on the
+public internet or in the knowledge store.
+
+## Configuration (relay only on exit 78 from `research`)
+
+On exit 78 the engine prints exact configure locations to stderr — relay verbatim:
+
+```
+config file:  ~/.pi/research/config.env
+env vars:     PI_RESEARCH_API_KEY  PI_RESEARCH_PROVIDER  PI_RESEARCH_MODEL
+pi auth:      ~/.pi/agent/auth.json
+pi models:    ~/.pi/agent/models.json
+```
+
+Run `status` for the resolved paths on this machine. Full reference:
+[`references/configuration.md`](references/configuration.md).
+
+The engine shuts down cleanly on every exit (browser pool, LanceDB, embedding
+model all released) — nothing is left behind between runs.

package/skills/pi-research/references/configuration.md

@@ -0,0 +1,77 @@
+## Configuration
+
+The skill drives the **pi-research** engine, which needs a model + API key.
+Run `node "<SKILL_DIR>/scripts/run.mjs" status` to print what's detected and where
+to configure (no research runs).
+
+### Credentials — resolution order
+
+1. **Env vars** (most portable):
+   ```sh
+   export PI_RESEARCH_API_KEY=sk-...
+   export PI_RESEARCH_PROVIDER=openai        # openai, anthropic, google, openrouter, …
+   export PI_RESEARCH_MODEL=openai/gpt-4o    # provider/model-id
+   ```
+2. **Global config** `~/.pi/research/config.env` (same KEY=VALUE keys; read at startup).
+3. **pi auth** (if you use `pi`): `~/.pi/agent/auth.json` + `~/.pi/agent/models.json`.
+
+Real env vars always win. Optional CLI-only overlay `~/.pi/research/cli.env` layers
+over `config.env` for the CLI only. Precedence:
+`defaults < config.env < cli.env < project registry < real env`.
+
+### Common settings (optional; env or `config.env`)
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PI_RESEARCH_MODEL` | session model | Model override for all research sub-tasks. |
+| `PI_RESEARCH_DEFAULT_RESEARCH_DEPTH` | `1` | Default depth (1–3) when `--depth` omitted. |
+| `PI_RESEARCH_MAX_RESEARCHERS` | `3` | Parallel researchers (1–5). |
+| `PI_RESEARCH_TIMEOUT_MS` | `300000` | Per-researcher timeout (180000–1800000). |
+| `PI_RESEARCH_MAX_SCRAPE_BATCHES` | `2` | Scrape batches per researcher (0 = unlimited). |
+| `PI_RESEARCH_YOUTUBE_TRANSCRIPT_MAX_VIDEOS` | `3` | Videos per `youtube_transcript` call (1–5). |
+| `PI_RESEARCH_YOUTUBE_QUERY_EVERY_N` | `5` | Append `youtube` to ~one-in-N queries (1 = every). |
+| `PI_RESEARCH_KNOWLEDGE_STORE_MODE` | `global` | Knowledge DB: `none`, `project`, `global`. |
+| `PI_RESEARCH_EMBEDDING_DEVICE` | `auto` | Embedding backend: `auto`, `webgpu`, or `cpu` (`auto` probes the GPU and falls back to CPU; raw `webgpu` is forced and can hard-crash on a software GPU). |
+| `PI_RESEARCH_REPORT_EXPORT_ENABLED` | `false` | Write report to `.md` and print its path. |
+| `STACKEXCHANGE_API_KEY` | — | Raises Stack Exchange rate limits (optional). |
+| `GITHUB_TOKEN` | — | Raises GitHub Advisory limit (optional). |
+| `NVD_API_KEY` | — | Raises NVD limit (optional). |
+
+`knowledge` needs a store mode other than `none`. With
+`PI_RESEARCH_REPORT_EXPORT_ENABLED=true`, the report ends with
+`Research report saved to: <path>` — surface that path.
+
+### Knowledge-store scope (per-directory)
+
+`PI_RESEARCH_KNOWLEDGE_STORE_MODE` is **per-directory** (project-scoped): `global` (one
+shared store — the default), `project` (scoped to the current directory), or `none`
+(disabled here). The user changes it by asking you in chat; when they do, run it for them:
+
+```sh
+node "<SKILL_DIR>/scripts/run.mjs" knowledge-config                     # current mode + its source
+node "<SKILL_DIR>/scripts/run.mjs" knowledge-config set none|project|global
+```
+
+`set` persists to the per-directory project registry (`~/.pi/research/state/
+project-settings.json`, keyed by the directory) and applies on the next run. It overrides a
+machine-wide `config.env` default; a real `PI_RESEARCH_KNOWLEDGE_STORE_MODE` env var still
+outranks both (the command says so when that happens).
+
+### Exit codes
+
+`0` success · `64` bad arguments · `78` not configured (engine missing or no
+model/key; message lists the fix) · `70` runtime error (network/provider/internal).
+
+### Troubleshooting
+
+- **"engine not found" (78 from launcher):** not installed —
+  `npm i -g @lincoln504/pi-research`, or `pi install npm:@lincoln504/pi-research`,
+  or `export PI_RESEARCH_PATH=/path/to/pi-research` (package dir), or
+  `export PI_RESEARCH_BIN=/path/to/pi-research/dist/cli.mjs` (exact CLI entry;
+  checked first — also the escape hatch for unusual Windows shim layouts).
+- **"No model or API key" (78 from engine):** set the three env vars (or config /
+  pi auth), then re-run `status`.
+- **Rate limit (70):** provider returned 429 — wait and retry.
+- **GPU/embedding errors:** set `PI_RESEARCH_EMBEDDING_DEVICE=cpu` (headless/no-GPU).
+
+Full variable list + precedence model: `docs/CONFIGURATION.md` in the pi-research repo.

package/skills/pi-research/scripts/run.mjs

@@ -0,0 +1,237 @@
+#!/usr/bin/env node
+
+// skills/pi-research/scripts/run.ts
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { createRequire } from "node:module";
+import { fileURLToPath } from "node:url";
+var PKG = "@lincoln504/pi-research";
+var REQUIRED_DEP = "@earendil-works/pi-coding-agent";
+var EXIT = { OK: 0, USAGE: 64, CONFIG: 78, SOFTWARE: 70 };
+var argv = process.argv.slice(2);
+var subcommand = argv[0];
+if (!subcommand || subcommand === "-h" || subcommand === "--help" || subcommand === "help") {
+  printUsage();
+  process.exit(EXIT.OK);
+}
+var require2 = createRequire(import.meta.url);
+function resolvePackageDir(specifier, roots) {
+  const candidates = [
+    ...process.cwd() !== roots[0] ? [process.cwd()] : [],
+    ...roots
+  ];
+  for (const root of candidates) {
+    try {
+      const pkgJson = require2.resolve(`${specifier}/package.json`, { paths: [root] });
+      return dirname(pkgJson);
+    } catch {
+    }
+  }
+  try {
+    const pkgJson = require2.resolve(`${specifier}/package.json`);
+    return dirname(pkgJson);
+  } catch {
+    return null;
+  }
+}
+function findOnPath(bin) {
+  const pathVar = process.env["PATH"] ?? "";
+  const exts = process.platform === "win32" ? (process.env["PATHEXT"] ?? ".EXE;.CMD").split(";") : [""];
+  for (const dir of pathVar.split(process.platform === "win32" ? ";" : ":")) {
+    if (!dir) continue;
+    for (const ext of exts) {
+      const candidate = join(dir, bin + ext);
+      try {
+        if (existsSync(candidate)) return candidate;
+      } catch {
+      }
+    }
+  }
+  return null;
+}
+function resolveEngine(skillDir) {
+  const home = homedir();
+  if (process.env["PI_RESEARCH_BIN"] && existsSync(process.env["PI_RESEARCH_BIN"])) {
+    return { argv: [process.env["PI_RESEARCH_BIN"]], label: process.env["PI_RESEARCH_BIN"] };
+  }
+  const explicitPath = process.env["PI_RESEARCH_PATH"];
+  if (explicitPath) {
+    const fromDir = engineFromPackageDir(explicitPath);
+    if (fromDir) {
+      if (!depResolvableFrom(explicitPath)) depMissing(explicitPath);
+      return fromDir;
+    }
+  }
+  const onPath = findOnPath("pi-research");
+  if (onPath) return { argv: [onPath], label: onPath };
+  const pkgDir = resolvePackageDir(PKG, [skillDir, process.cwd(), home, join(home, ".pi")]);
+  if (pkgDir) {
+    const fromPkg = engineFromPackageDir(pkgDir);
+    if (fromPkg) {
+      if (!depResolvableFrom(pkgDir)) depMissing(pkgDir);
+      return fromPkg;
+    }
+  }
+  const piBin = join(home, ".pi", "bin", "pi-research");
+  if (existsSync(piBin)) return { argv: [piBin], label: piBin };
+  return null;
+}
+function engineFromPackageDir(pkgDir) {
+  try {
+    const pkg = JSON.parse(readFileSync(join(pkgDir, "package.json"), "utf-8"));
+    const binField = typeof pkg?.bin === "string" ? pkg.bin : pkg?.bin?.["pi-research"];
+    if (binField) {
+      const binPath = join(pkgDir, binField);
+      if (existsSync(binPath)) {
+        const isJsModule = /\.(m|c)?js$/i.test(binField);
+        return isJsModule ? { argv: [process.execPath, binPath], label: binPath } : { argv: [binPath], label: binPath };
+      }
+    }
+  } catch {
+  }
+  const cliPath = join(pkgDir, "dist", "cli.mjs");
+  if (existsSync(cliPath)) {
+    return { argv: [process.execPath, cliPath], label: cliPath };
+  }
+  return null;
+}
+function depResolvableFrom(anchorDir) {
+  const depSegs = REQUIRED_DEP.split("/");
+  let dir = resolve(anchorDir);
+  for (; ; ) {
+    if (existsSync(join(dir, "node_modules", ...depSegs, "package.json"))) return true;
+    const parent = dirname(dir);
+    if (parent === dir) return false;
+    dir = parent;
+  }
+}
+function depMissing(pkgDir) {
+  const lines = [
+    "",
+    `Error: pi-research engine found, but its required runtime dependency`,
+    `'${REQUIRED_DEP}' is not installed alongside it.`,
+    "",
+    "The standalone engine imports this package at startup, so it cannot run",
+    "without it. Reinstall so all dependencies are included:",
+    "",
+    "    npm install -g @lincoln504/pi-research     # global \u2014 reinstalls the full dependency tree",
+    `    # or, in the package dir:  cd "${pkgDir}" && npm install ${REQUIRED_DEP}`,
+    "",
+    `(engine located at: ${pkgDir})`,
+    ""
+  ];
+  process.stderr.write(lines.join("\n"));
+  process.exit(EXIT.CONFIG);
+}
+function notInstalled() {
+  const home = homedir();
+  const lines = [
+    "",
+    "Error: pi-research engine not found.",
+    "",
+    "This research skill drives the pi-research engine, but it is not installed in",
+    "any of the locations this launcher checks (PATH, node_modules, ~/.pi/bin,",
+    "PI_RESEARCH_PATH). Install it, then re-run:",
+    "",
+    "    npm install -g @lincoln504/pi-research     # global (exposes the `pi-research` bin)",
+    "    # or, with pi:   pi install npm:@lincoln504/pi-research",
+    "    # or point at a copy: export PI_RESEARCH_PATH=/path/to/pi-research",
+    "",
+    "After installing, configure a model + API key. Locations:",
+    `  \u2022 env vars:           PI_RESEARCH_API_KEY / PI_RESEARCH_PROVIDER / PI_RESEARCH_MODEL`,
+    `  \u2022 global config file: ${join(home, ".pi", "research", "config.env")}`,
+    `  \u2022 pi auth storage:    ${join(home, ".pi", "agent", "auth.json")}`,
+    "",
+    "Run `status` once installed to verify detection.",
+    ""
+  ];
+  process.stderr.write(lines.join("\n"));
+  process.exit(EXIT.CONFIG);
+}
+function hasCmdMetachar(s) {
+  return /[&|<>^"%()!\r\n]/.test(s);
+}
+function resolveWinShimToNode(shimPath) {
+  const fromLayout = engineFromPackageDir(join(dirname(shimPath), "node_modules", ...PKG.split("/")));
+  if (fromLayout && fromLayout.argv[0] === process.execPath) return fromLayout;
+  try {
+    const content = readFileSync(shimPath, "utf-8");
+    const m = content.match(/node_modules[\\/][^"\r\n]*?\.(?:mjs|cjs|js)\b/i);
+    if (m) {
+      const abs = resolve(dirname(shimPath), m[0]);
+      if (existsSync(abs)) return { argv: [process.execPath, abs], label: abs };
+    }
+  } catch {
+  }
+  return null;
+}
+function launch(engine2) {
+  let target = engine2.argv[0];
+  let runArgv = engine2.argv.slice(1).concat(argv);
+  let useShell = false;
+  if (process.platform === "win32" && /\.(cmd|bat)$/i.test(target)) {
+    const direct = resolveWinShimToNode(target);
+    if (direct) {
+      target = direct.argv[0];
+      runArgv = direct.argv.slice(1).concat(argv);
+    } else if (argv.some(hasCmdMetachar)) {
+      process.stderr.write(
+        `
+Error: cannot safely pass this query to the Windows pi-research.cmd shim \u2014 it contains shell metacharacters (& | < > ^ " % ( ) !).
+Set PI_RESEARCH_BIN to the engine's node CLI (\u2026\\dist\\cli.mjs) or PI_RESEARCH_PATH to its package dir, then re-run.
+`
+      );
+      process.exit(EXIT.CONFIG);
+    } else {
+      useShell = true;
+    }
+  }
+  const child = spawn(
+    useShell ? `"${target}"` : target,
+    useShell ? runArgv.map((a) => `"${a}"`) : runArgv,
+    {
+      stdio: "inherit",
+      env: process.env,
+      windowsHide: true,
+      ...useShell ? { shell: true } : {}
+    }
+  );
+  child.on("error", (err) => {
+    process.stderr.write(`
+Error: failed to launch pi-research (${engine2.label}): ${err.message}
+`);
+    process.exit(EXIT.SOFTWARE);
+  });
+  child.on("exit", (code, signal) => {
+    if (signal) {
+      process.stderr.write(`
+Error: pi-research killed by ${signal}
+`);
+      process.exit(EXIT.SOFTWARE);
+    }
+    process.exit(code ?? EXIT.SOFTWARE);
+  });
+}
+function printUsage() {
+  process.stdout.write(
+    [
+      "research skill \u2014 pi-research launcher",
+      "",
+      "USAGE",
+      '  node run.mjs research  "<query>" [--depth <0|1|2|3>] [--model provider/id]',
+      '  node run.mjs knowledge "<query>" ["<q2>" ...]',
+      "  node run.mjs knowledge-config [set <none|project|global>]",
+      "  node run.mjs status [--json]",
+      "",
+      "This locates the installed pi-research engine and forwards the subcommand to it.",
+      "If the engine is missing, it prints install/config instructions and exits 78.",
+      ""
+    ].join("\n")
+  );
+}
+var here = dirname(fileURLToPath(import.meta.url));
+var engine = resolveEngine(here);
+if (!engine) notInstalled();
+launch(engine);