@lincoln504/pi-research 0.1.12 → 1.0.0

package/docs/SDK.md

@@ -0,0 +1,113 @@
+## SDK
+
+The programmatic SDK for scripts, CI, and custom tooling. For configuration — the
+layering model, the TUI settings, and every environment variable — see
+[CONFIGURATION.md](CONFIGURATION.md).
+
+`src/sdk.ts` is a library for scripts, CI, and custom tooling. It is configured
+from code, not from a global overlay file — there is no `sdk.env`. It reads the
+base `~/.pi/research/config.env` as a baseline, and everything is
+overridable via `options.config`. Pass `ignoreGlobalConfig: true` to ignore the
+global file entirely and run purely from defaults + `process.env` + `options.config`
+— self-contained and reproducible from code.
+
+> Runtime requirement. The package exports (`.` and `/sdk`) resolve to
+> TypeScript source — there is no transpiled `dist/sdk.js`. It must run on a
+> runtime that *transforms* TypeScript, not merely strips types: the source uses
+> `enum` and constructor parameter properties, which Node's strip-only mode
+> (`--experimental-strip-types`, the default since Node 23.6) rejects with
+> `ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX`. Use one of:
+> - the pi host, which loads it natively;
+> - **`node --experimental-transform-types your-script.ts`** — must be passed
+>   explicitly; full transform is not the default on any current Node release;
+> - a loader such as `tsx` or `ts-node`.
+>
+> Plain `node script.js` doing `require('@lincoln504/pi-research/sdk')`, or
+> `--experimental-strip-types`, will not work. (`engines.node` is `>=22.19.0`.)
+
+```typescript
+import {
+  initResearchSDK,
+  runDeepResearch,
+  runQuickResearch,
+  getResearchReports,
+  shutdownResearchSDK,
+} from '@lincoln504/pi-research';
+
+// 1. Initialize (configured entirely in code; no global config needed)
+await initResearchSDK({
+  model: 'openrouter/deepseek/deepseek-v4-flash', // string "provider/id" or a Model object
+  ignoreGlobalConfig: true,                       // hermetic: ignore ~/.pi/research/config.env
+  config: { MAX_SCRAPE_BATCHES: 4 },              // typed Config overrides
+});
+
+// 2. Deep research (depth 1–3)
+const markdown = await runDeepResearch('solid-state battery technology', { depth: 2 });
+
+// 3. Quick research (depth 0)
+const quick = await runQuickResearch('what is the capital of France');
+
+// 4. Retrieve per-researcher reports from the last run
+const reports = await getResearchReports();
+
+// 5. Cleanup — REQUIRED: drains the writer queue, closes LanceDB, kills workers
+await shutdownResearchSDK();
+```
+
+`initResearchSDK` must run before any research call. Auth resolves from
+`options.apiKey` + `options.provider`, else `process.env.PI_RESEARCH_API_KEY` /
+`PI_RESEARCH_PROVIDER`, else pi's `~/.pi/agent/auth.json`. Other exports include
+`runResearchDetailed`, `searchKnowledge`, `scrapeUrl`, `getResearchHealth`,
+`getLastRunStats`, and `getSessionMetrics`, plus `exportKnowledge` (write the
+knowledge store to a web-consumable JSON file) and the post-run telemetry accessors
+`getLastRunMetrics`, `getLastRunSummary`, and `getLastErrorReport`. Both
+`@lincoln504/pi-research` and `@lincoln504/pi-research/sdk` export these symbols.
+
+> Concurrency: a single initialized SDK instance runs one research call at a time.
+> Overlapping `runDeepResearch`/`runQuickResearch` calls on the same instance throw
+> — run them sequentially, or use a separate process per concurrent run.
+
+The SDK does not write report files. Report export is a front-end concern — the pi
+extension and the CLI / agent skill do it when `PI_RESEARCH_REPORT_EXPORT_ENABLED=true`.
+
+### Init options
+
+| Option | Description |
+|--------|-------------|
+| `model` | `"provider/id"` string or a `Model` object. Omit to use the first available pi model. |
+| `apiKey` / `provider` | Explicit credentials (provider required with apiKey). |
+| `config` | `Partial<Config>` overrides, applied over the base/defaults. |
+| `ignoreGlobalConfig` | Skip `config.env` entirely — defaults + `process.env` + `config` only. |
+| `cwd` | Working directory for logs and the knowledge store. |
+| `verbose` | Mirror logs to the console. |
+
+For configuration precedence, the per-front-end overlays, and the full
+environment-variable reference, see [CONFIGURATION.md](CONFIGURATION.md).
+
+### Health & knowledge-store APIs
+
+The `health` tool (and the SDK's `getResearchHealth()`) runs every registered
+health check — browser capability, browser runtime, knowledge store, and state
+manager — and returns a structured report:
+
+```typescript
+import { initResearchSDK, getResearchHealth } from '@lincoln504/pi-research/sdk';
+
+await initResearchSDK();                 // required first — throws if not initialized
+const result = await getResearchHealth();
+// { success: boolean, status: 'healthy' | 'degraded' | 'unhealthy', components: [...] }
+```
+
+The knowledge store is an internal service, not a public export. It is populated
+automatically during research runs; query stored findings with the SDK's
+`searchKnowledge()` or the `research_knowledge_search` tool. The vector dimension
+is model-dependent (auto-detected); stored fields are `text`, `content`,
+`vector`, `url`, `metadata`, `timestamp`, `workspace`, `is_global`, and
+`ingestion_type`.
+
+### Example Use
+
+The [Wall of Shame](https://wallofshame.io) project ([repo](https://github.com/Lincoln504/wall-of-shame))
+uses this SDK in its agent pipeline: it calls `initResearchSDK` and the research
+entry points (`runQuickResearch` / `runDeepResearch`) per investigation, and uses
+the `scrapeUrl`, `verifyUrl`, and `repairJson` exports directly.

package/docs/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,64 @@
+## Third-Party Notices
+
+`@lincoln504/pi-research` is licensed under the MIT License (see `LICENSE`). That
+license covers this project's own source code only.
+
+This package depends on third-party software distributed under its own license
+terms. Dependencies are resolved and installed by npm at install time (by
+reference); they are **not** bundled into this package's published artifacts
+(`dist/*` is built with esbuild `--packages=external`, so no third-party code is
+inlined).
+
+### Notable dependency licensing
+
+camoufox-js / Camoufox browser
+
+The `camoufox-js` npm package itself is licensed under **MPL-2.0** (file-level
+copyleft). It is resolved at install time and **not bundled** into this package's
+artifacts (`dist/*` is built `--packages=external`), so no MPL-covered source is
+combined into or redistributed by this MIT package. It is used in-process only to
+configure and launch the Camoufox (Firefox-fork) browser **binary as a separate
+operating-system process**, which this package then drives over the Playwright/CDP
+protocol. The Camoufox binary is downloaded and run separately and is subject to its
+own license.
+
+ua-parser-js
+
+`ua-parser-js` 2.x is licensed under AGPL-3.0-or-later. To keep this MIT-licensed
+package free of AGPL-licensed code in its dependency tree, `package.json`
+`overrides` pins `ua-parser-js` to the `1.x` line, which is MIT-licensed. The
+1.x and 2.x APIs are compatible for the only surface our transitive dependency
+(`camoufox-js`) uses, and the pin is behavior-neutral for this package's usage
+(no custom `navigator.userAgent`/`fingerprint` is passed to Camoufox).
+
+youtubei.js / bgutils-js / jsdom (YouTube transcripts)
+
+The `youtube_transcript` tool depends on `youtubei.js` (MIT), `bgutils-js` (MIT),
+and `jsdom` (MIT). All three are standard MIT and are resolved at install time,
+not bundled. `youtubei.js` and `bgutils-js` interact with YouTube's **unofficial**
+InnerTube API and BotGuard attestation to fetch publicly available captions
+without an API key; no credentials are used and only caption text is read.
+Operators are responsible for ensuring their use complies with YouTube's Terms of
+Service. `jsdom` provides the DOM environment the BotGuard VM requires; it is
+loaded lazily (only when the tool runs) and never at startup.
+
+sharp / @img/sharp-libvips (via @huggingface/transformers)
+
+`@huggingface/transformers` pulls in `sharp` (Apache-2.0) for image decoding, which
+in turn installs prebuilt `@img/sharp-libvips-*` native packages licensed under
+**LGPL-3.0-or-later**. These are platform-specific shared libraries linked
+**dynamically** at runtime and resolved at install time; no LGPL code is statically
+linked into or bundled with this package (`dist/*` is built `--packages=external`).
+Dynamic linkage of an unmodified LGPL library from an MIT-licensed program is
+permitted by the LGPL. The image path is only exercised by the embedding/knowledge
+stack; text-only research does not load it.
+
+### Verifying the dependency tree
+
+```
+npm ls ua-parser-js   # expect ua-parser-js@1.x (overridden, MIT)
+```
+
+For a full license inventory of installed dependencies, run a license scanner of
+your choice (e.g. `npx license-checker --summary`) against your installed
+`node_modules`.

package/package.json

@@ -1,18 +1,43 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "0.1.12",
+  "version": "1.0.0",
   "description": "A set of web research tools (search, scrape, and others) and research agent system that uses them safely and efficiently.",
   "type": "module",
   "private": false,
   "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "bin": {
+    "pi-research": "./dist/cli.mjs"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./sdk": "./src/sdk.ts",
+    "./package.json": "./package.json"
+  },
   "files": [
     "src/",
-    "config/",
-    "docs/",
-    "scripts/",
+    "dist/cli.mjs",
+    "dist/thread-worker.mjs",
+    "dist/webgpu-probe.mjs",
+    "dist/prompts/",
+    "skills/",
+    "!skills/pi-research/scripts/run.ts",
+    "!src/.env",
+    "!src/.env.local",
+    "!src/.env.*.local",
+    "docs/PI-EXTENSION.md",
+    "docs/SDK.md",
+    "docs/CONFIGURATION.md",
+    "docs/KNOWLEDGE-STORE.md",
+    "docs/AGENT-SKILL.md",
+    "docs/ARCHITECTURE.md",
+    "scripts/setup.cjs",
+    "scripts/cleanup.cjs",
+    "scripts/build.cjs",
+    "scripts/prepare.cjs",
     "LICENSE",
-    "README.md",
-    "tsconfig.json"
+    "docs/THIRD-PARTY-NOTICES.md",
+    "README.md"
   ],
   "repository": {
     "type": "git",
@@ -26,67 +51,108 @@
     "pi",
     "pi-package",
     "pi-extension",
+    "openclaw",
+    "agent-skill",
     "research",
     "agent",
     "web-search",
     "scraping",
+    "stealth-browser",
+    "camoufox",
     "security",
     "stack-exchange"
   ],
-  "author": "Lincolndeen",
+  "author": "Lincoln Deen",
   "contributors": [
     "MuratAitov"
   ],
   "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
   "engines": {
-    "node": "^22.13.0 || >=24.0.0"
+    "node": ">=22.19.0"
   },
   "scripts": {
     "lint": "npx eslint --config config/tooling/eslint.config.js src/",
     "lint:fix": "npx eslint --config config/tooling/eslint.config.js src/ --fix",
     "type-check": "tsc --noEmit",
-    "test": "vitest run --config config/tooling/vitest.config.unit.ts",
+    "type-check:tests": "tsc --noEmit --project config/tooling/tsconfig.test.json",
+    "build:worker": "node scripts/build.cjs worker",
+    "test": "npm run test:unit",
     "test:unit": "vitest run --config config/tooling/vitest.config.unit.ts",
-    "test:integration": "vitest run --config config/tooling/vitest.config.integration.ts",
+    "test:integration": "npm run test:integration:parallel && npm run test:integration:serial",
+    "test:integration:parallel": "vitest run --config config/tooling/vitest.config.integration.parallel.ts",
+    "test:integration:serial": "vitest run --config config/tooling/vitest.config.integration.serial.ts",
+    "test:all": "npm run test:unit && npm run test:integration",
     "test:watch": "vitest --config config/tooling/vitest.config.unit.ts",
-    "test:coverage": "vitest run --config config/tooling/vitest.config.ts --coverage",
-    "postinstall": "node scripts/setup.js",
-    "install:browsers": "npx playwright install chromium",
-    "install:deps": "npx playwright install-deps",
-    "setup": "npm install && npm run install:browsers"
+    "test:coverage": "vitest run --config config/tooling/vitest.config.unit.ts --coverage",
+    "build:cli": "node scripts/build.cjs cli",
+    "build:skill": "node scripts/build.cjs skill",
+    "build": "node scripts/build.cjs all",
+    "prepublishOnly": "node scripts/build.cjs all && node scripts/verify-package.cjs manifest",
+    "prepare": "node scripts/prepare.cjs",
+    "version": "node -e \"const fs=require('fs');const p=require('./package.json');const sp='./skills/pi-research/SKILL.md';let s=fs.readFileSync(sp,'utf8');s=s.replace(/\\\"version\\\": \\\"[^\\\"]*\\\"/,'\\\"version\\\": \\\"'+p.version+'\\\"');fs.writeFileSync(sp,s);console.log('✔ synced SKILL.md to v'+p.version)\" && git add skills/pi-research/SKILL.md",
+    "postinstall": "node scripts/setup.cjs",
+    "preuninstall": "node scripts/cleanup.cjs",
+    "setup": "node scripts/setup.cjs",
+    "install:system-deps": "node scripts/setup.cjs --system-deps",
+    "deps:check": "depcruise --config config/tooling/dependency-cruiser.cjs --output-type err-long src",
+    "deps:generate": "npx --yes madge --image docs/deps.svg src/index.ts",
+    "analyze:dependencies": "ncu",
+    "analyze:compatibility": "depngn"
   },
   "pi": {
     "extensions": [
       "./src/index.ts"
-    ]
+    ],
+    "image": "https://raw.githubusercontent.com/Lincoln504/pi-research/main/docs/media/hero.png"
   },
   "dependencies": {
-    "@kreuzberg/html-to-markdown-node": "^2.30.0",
-    "dockerode": "^4.0.10",
-    "js-yaml": "^4.1.1",
+    "@earendil-works/pi-ai": ">=0.80.2 <1",
+    "@earendil-works/pi-coding-agent": ">=0.80.2 <1",
+    "@earendil-works/pi-tui": ">=0.80.2 <1",
+    "@huggingface/transformers": "4.2.0",
+    "@kreuzberg/html-to-markdown-node": "^3.5.5",
+    "@lancedb/lancedb": "0.29.0",
+    "apache-arrow": "21.1.0",
+    "bgutils-js": "^3.2.0",
+    "camoufox-js": "^0.10.2",
+    "esbuild": "^0.28.1",
+    "impit": "0.13.0",
+    "jsdom": "^29.1.1",
     "node-html-markdown": "^2.0.0",
-    "playwright": "^1.52.0"
+    "pdf-oxide-wasm": "^0.3.70",
+    "playwright-core": "1.60.0",
+    "poolifier": "^5.3.2",
+    "typebox": "1.1.38",
+    "undici": "^8.6.0",
+    "youtubei.js": "^17.2.0"
   },
   "optionalDependencies": {
-    "@kreuzberg/html-to-markdown-node-darwin-arm64": "^2.30.0",
-    "@kreuzberg/html-to-markdown-node-darwin-x64": "^2.30.0",
-    "@kreuzberg/html-to-markdown-node-win32-x64-msvc": "^2.30.0"
+    "webgpu": "^0.4.0"
   },
-  "peerDependencies": {
-    "@mariozechner/pi-coding-agent": ">=0.65.0",
-    "@sinclair/typebox": ">=0.34.0"
+  "overrides": {
+    "lodash.isequal": "npm:fast-deep-equal@^3.1.3",
+    "ip-address": "^10.2.0",
+    "apache-arrow": "21.1.0",
+    "onnxruntime-web": "1.24.3",
+    "node-domexception": "npm:@nolyfill/domexception@^1.0.28",
+    "ua-parser-js": "^1.0.41",
+    "protobufjs": "7.6.4",
+    "vite": "^8.0.16"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@types/dockerode": "^4.0.1",
-    "@types/js-yaml": "^4.0.9",
-    "@typescript-eslint/eslint-plugin": "^8.58.0",
-    "@typescript-eslint/parser": "^8.58.0",
-    "@vitest/coverage-v8": "^4.1.2",
-    "eslint": "^10.1.0",
-    "eslint-config-prettier": "^10.1.0",
-    "testcontainers": "^11.13.0",
-    "typescript": "^6.0.2",
-    "vitest": "^4.1.2"
+    "@types/jsdom": "^28.0.3",
+    "@typescript-eslint/eslint-plugin": "^8.60.0",
+    "@typescript-eslint/parser": "^8.60.0",
+    "@vitest/coverage-v8": "^4.1.7",
+    "dependency-cruiser": "^17.4.2",
+    "depngn": "^0.6.0",
+    "eslint": "^10.4.0",
+    "npm-check-updates": "^22.2.1",
+    "typescript": ">=6.0.3 <6.1.0",
+    "vitest": "^4.1.7"
   }
 }

package/scripts/build.cjs

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+
+/**
+ * Cross-platform build of all distribution artifacts via the esbuild JS API.
+ *
+ * Using the JS API (not shell `esbuild ...` invocations) removes every
+ * shell-quoting hazard between POSIX `sh` and Windows `cmd.exe` — most notably
+ * the `--banner:js='#!/usr/bin/env node'` shebang, whose single quotes are not
+ * grouping characters in cmd.exe and so split the build on the space. The
+ * banner is just a JS string here, identical on every platform.
+ *
+ * Targets (dispatch by argv, or build all when no/`all` arg):
+ *   worker   -> src/infrastructure/browser/thread-worker.mjs  (browser worker)
+ *   cli      -> dist/cli.mjs (+ dist/prompts, dist/thread-worker.mjs, dist/webgpu-probe.mjs)
+ *   skill    -> skills/pi-research/scripts/run.mjs  (skill launcher, shebang)
+ *
+ * Note: `packages: 'external'` already externalizes every bare/`node:` import,
+ * so the old `--external:node:*` flag was redundant — output is identical.
+ */
+
+'use strict';
+
+const esbuild = require('esbuild');
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '..');
+const SHEBANG = '#!/usr/bin/env node';
+
+const COMMON = {
+  bundle: true,
+  platform: 'node',
+  format: 'esm',
+  packages: 'external',
+  logLevel: 'warning',
+};
+
+const p = (...segs) => path.join(ROOT, ...segs);
+
+// The out-of-process WebGPU viability probe is plain .mjs (not bundled). It must
+// sit next to the bundled entry points so the embedder can resolve it relative to
+// import.meta.url, and so it resolves @huggingface/transformers from the installed
+// package's node_modules. The bundled dist/cli.mjs depends on it.
+function copyWebGpuProbe() {
+  fs.mkdirSync(p('dist'), { recursive: true });
+  fs.copyFileSync(
+    p('src', 'knowledge', 'webgpu-probe.mjs'),
+    p('dist', 'webgpu-probe.mjs'),
+  );
+}
+
+// Build the browser worker bundle. Factored out so the cli target can guarantee
+// it exists when built in isolation (`build:cli`), not only via `build all`.
+function buildWorker() {
+  return esbuild.build({
+    ...COMMON,
+    entryPoints: [p('src', 'infrastructure', 'browser', 'thread-worker.ts')],
+    outfile: p('src', 'infrastructure', 'browser', 'thread-worker.mjs'),
+  });
+}
+
+async function ensureWorkerBuilt() {
+  const src = p('src', 'infrastructure', 'browser', 'thread-worker.ts');
+  const out = p('src', 'infrastructure', 'browser', 'thread-worker.mjs');
+  // Rebuild if the bundle is missing OR older than its source, so an isolated
+  // `build:cli` after editing thread-worker.ts never ships a stale worker.
+  const stale =
+    !fs.existsSync(out) || fs.statSync(out).mtimeMs < fs.statSync(src).mtimeMs;
+  if (stale) {
+    await buildWorker();
+  }
+}
+
+// Copy the built worker bundle into dist/. dist/thread-worker.mjs is resolved by
+// worker-pool-manager.ts at runtime, so the bundled cli — which spins up the
+// browser pool — needs it next to its bundle.
+function copyThreadWorker() {
+  fs.mkdirSync(p('dist'), { recursive: true });
+  fs.copyFileSync(
+    p('src', 'infrastructure', 'browser', 'thread-worker.mjs'),
+    p('dist', 'thread-worker.mjs'),
+  );
+}
+
+// Copy the prompt templates into dist/prompts/. The bundled dist/cli.mjs resolves
+// prompts relative to its own location (loadPrompt → join(dirname(cli.mjs),
+// 'prompts')), so the templates must sit next to the bundle.
+function copyPrompts() {
+  fs.mkdirSync(p('dist', 'prompts'), { recursive: true });
+  for (const f of fs.readdirSync(p('src', 'prompts'))) {
+    fs.copyFileSync(p('src', 'prompts', f), p('dist', 'prompts', f));
+  }
+}
+
+const TARGETS = {
+  worker: () => buildWorker(),
+  cli: async () => {
+    await ensureWorkerBuilt();
+    await esbuild.build({
+      ...COMMON,
+      entryPoints: [p('src', 'cli.ts')],
+      outfile: p('dist', 'cli.mjs'),
+      banner: { js: SHEBANG },
+    });
+    copyThreadWorker();
+    copyWebGpuProbe();
+    copyPrompts();
+  },
+  skill: () =>
+    esbuild.build({
+      ...COMMON,
+      entryPoints: [p('skills', 'pi-research', 'scripts', 'run.ts')],
+      outfile: p('skills', 'pi-research', 'scripts', 'run.mjs'),
+      banner: { js: SHEBANG },
+    }),
+};
+
+// The cli target's copyThreadWorker step depends on the worker output existing,
+// so the full build runs worker before cli; skill is independent.
+const ALL_ORDER = ['worker', 'cli', 'skill'];
+
+async function main() {
+  const arg = process.argv[2];
+  const targets = !arg || arg === 'all' ? ALL_ORDER : [arg];
+
+  for (const name of targets) {
+    const build = TARGETS[name];
+    if (!build) {
+      console.error(`[build] Unknown target: ${name}`);
+      console.error(`[build] Valid targets: ${Object.keys(TARGETS).join(', ')}, all`);
+      process.exit(1);
+    }
+    await build();
+  }
+}
+
+main().catch((err) => {
+  console.error('[build] Build failed:', err && err.message ? err.message : err);
+  process.exit(1);
+});

package/scripts/cleanup.cjs

@@ -0,0 +1,149 @@
+#!/usr/bin/env node
+
+const { execSync } = require('child_process');
+const { rmSync, existsSync, lstatSync, readlinkSync, readFileSync, writeFileSync, unlinkSync } = require('fs');
+const os = require('os');
+const path = require('path');
+
+// __dirname is a built-in global in CommonJS (.cjs) modules
+const projectRoot = path.join(__dirname, '..');
+
+/**
+ * Remove research-skill installs (symlinks/copies) this package created in the
+ * coding-agent harnesses, so `npm uninstall` is symmetric with the in-app
+ * installer (the /research-config "Install Skill in Coding Agents" action).
+ * Reads the manifest written by the installer and removes ONLY entries we still
+ * own (a symlink pointing into a pi-research skills dir, or a copy carrying our
+ * package marker). Foreign directories are never touched. Best-effort; never
+ * throws (preuninstall must not fail the uninstall).
+ */
+function removeInstalledSkills() {
+  const manifestPath = path.join(os.homedir(), '.pi', 'research', 'installed-skills.json');
+  // Read directly and let the catch handle a missing/unreadable manifest. Avoiding
+  // a separate existsSync() check removes a check-then-use (TOCTOU) on the file that
+  // is later rewritten below — the read itself is the only gate we need.
+  let manifest;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, 'utf-8'));
+  } catch {
+    return;
+  }
+  const entries = Array.isArray(manifest && manifest.entries) ? manifest.entries : [];
+  const kept = [];
+  for (const e of entries) {
+    const p = e && e.path;
+    if (!p) continue;
+    // Use lstat, not existsSync: existsSync follows symlinks, so a DANGLING
+    // symlink (our target already removed) reports absent and we'd drop the
+    // manifest entry while leaving the broken symlink on disk. lstat sees the
+    // link itself.
+    let lst;
+    try { lst = lstatSync(p); } catch { continue; } // truly gone → drop entry
+    let owned = false;
+    try {
+      if (lst.isSymbolicLink()) {
+        const dest = path.resolve(path.dirname(p), readlinkSync(p));
+        owned = /[/\\]pi-research[/\\]skills[/\\]pi-research$/.test(dest);
+      } else {
+        const md = readFileSync(path.join(p, 'SKILL.md'), 'utf-8');
+        owned = md.includes('@lincoln504/pi-research');
+      }
+    } catch { /* treat as not-owned */ }
+    if (!owned) { kept.push(e); continue; }
+    try {
+      if (lstatSync(p).isSymbolicLink()) unlinkSync(p);
+      else rmSync(p, { recursive: true, force: true });
+      console.log(`pi-research: removed skill install at ${p}`);
+    } catch (err) {
+      kept.push(e);
+      console.warn(`pi-research: could not remove skill install ${p}: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+  try {
+    if (kept.length > 0) {
+      writeFileSync(manifestPath, JSON.stringify({ version: 1, package: '@lincoln504/pi-research', entries: kept }, null, 2) + '\n', 'utf-8');
+    } else {
+      unlinkSync(manifestPath);
+    }
+  } catch { /* best effort */ }
+}
+
+removeInstalledSkills();
+
+/**
+ * Resolve the camoufox-js binary path.
+ *
+ * See setup.cjs for rationale — dependencies are hoisted to root node_modules.
+ */
+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; see setup.cjs.
+    const bin = path.join(binDir, process.platform === 'win32' ? 'camoufox-js.cmd' : 'camoufox-js');
+    if (existsSync(bin)) return bin;
+  } catch (_) { /* fall through */ }
+  return null;
+}
+
+// Remove camoufox browser binaries — only when explicitly requested.
+// The shared cache (~/.cache/camoufox) may be used by other tools, so we do NOT
+// purge it by default. Set PI_RESEARCH_PURGE_BROWSERS=1 to opt in.
+if (process.env.PI_RESEARCH_PURGE_BROWSERS === '1') {
+  if (process.env.PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD !== '1') {
+    try {
+      const bin = resolveCamoufoxBin();
+      const cmd = bin ? `"${bin}" remove` : 'npx camoufox-js remove';
+      execSync(cmd, { stdio: 'inherit' });
+      console.log('pi-research: camoufox browser binaries removed.');
+    } catch (error) {
+      console.warn(`pi-research: could not remove camoufox binaries: ${error instanceof Error ? error.message : String(error)}`);
+      console.warn('pi-research: to remove manually, run: npx camoufox-js remove');
+    }
+  }
+} else {
+  console.log('pi-research: leaving shared camoufox binaries in place (set PI_RESEARCH_PURGE_BROWSERS=1 to remove).');
+}
+
+// Remove legacy project-local browser cache if present
+const legacyCacheDir = path.join(projectRoot, '.browser');
+if (existsSync(legacyCacheDir)) {
+  try {
+    rmSync(legacyCacheDir, { recursive: true, force: true });
+  } catch (error) {
+    console.warn(`pi-research: could not remove ${legacyCacheDir}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+/**
+ * Purge pi-research's OWN scratch dirs on uninstall — there is no next startup to
+ * reclaim them, so they would otherwise persist forever. Both are exclusively ours
+ * (named `pi-research`), so removal is safe. User config (~/.pi/research/config.env)
+ * and the knowledge_db are deliberately preserved. Best-effort; never throws.
+ * Paths mirror the runtime resolution (config.ts / state-path-configuration.ts) and
+ * honor the same overrides, so this stays correct cross-platform.
+ */
+function removeOwnedScratchDir(label, dir) {
+  if (!dir || !existsSync(dir)) return;
+  try {
+    rmSync(dir, { recursive: true, force: true });
+    console.log(`pi-research: removed ${label} ${dir}`);
+  } catch (error) {
+    console.warn(`pi-research: could not remove ${label} ${dir}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+// Cache tree: browser profiles, webgpu-viability probe, downloaded embedding models.
+// Same resolution as config.ts (XDG_CACHE_HOME || ~/.cache, then pi-research) on
+// every platform. Shared camoufox binaries live in ~/.cache/camoufox (handled above).
+const cacheHome = process.env.XDG_CACHE_HOME || path.join(os.homedir(), '.cache');
+removeOwnedScratchDir('cache dir', path.join(cacheHome, 'pi-research'));
+
+// State tree: transient run state, locks, backups, project-settings. Now lives in
+// pi-research's own namespace (~/.pi/research/state), honoring the same overrides
+// as getGlobalConfigDir()/PI_RESEARCH_STATE_DIR.
+const stateDir = process.env.PI_RESEARCH_STATE_DIR
+  || path.join(os.homedir(), process.env.PI_RESEARCH_CONFIG_DIR_NAME || '.pi', 'research', 'state');
+removeOwnedScratchDir('state dir', stateDir);
+
+process.exit(0);