@nailuogg/pi-find-packages 0.1.1

package/.github/workflows/publish.yml

@@ -0,0 +1,40 @@
+name: publish
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: write # create the GitHub release
+  id-token: write # reserved for a future Trusted-Publishing (OIDC) switch
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          registry-url: https://registry.npmjs.org/
+          # reads NODE_AUTH_TOKEN from env to write ~/.npmrc
+
+      - name: Verify version matches tag
+        run: |
+          PKG_VERSION="${GITHUB_REF_NAME#v}"
+          TAG_VERSION="$(node -p "require('./package.json').version")"
+          if [ "${PKG_VERSION}" != "${TAG_VERSION}" ]; then
+            echo "::error::tag ${GITHUB_REF_NAME} != package.json version ${TAG_VERSION}"
+            exit 1
+          fi
+
+      - name: Publish
+        run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub release
+        run: gh release create "${GITHUB_REF_NAME}" --verify-tag --generate-notes
+        env:
+          GH_TOKEN: ${{ github.token }}

package/.github/workflows/update-data.yml

@@ -0,0 +1,45 @@
+name: update-data
+
+on:
+  schedule:
+    - cron: "17 3 * * *" # daily, off the hour
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+jobs:
+  refresh:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+
+      - name: Fetch latest catalog
+        run: node scripts/sync-catalog.mjs --out "${RUNNER_TEMP}/catalog"
+
+      - name: Skip if unchanged
+        id: diff
+        run: |
+          NEW="${RUNNER_TEMP}/catalog/catalog.jsonl.gz"
+          OLD="$(curl -fsSL --max-time 30 https://cdn.jsdelivr.net/gh/${GITHUB_REPOSITORY}@data/data/catalog.jsonl.gz 2>/dev/null | sha256sum | cut -d' ' -f1 || true)"
+          CUR="$(sha256sum "${NEW}" | cut -d' ' -f1)"
+          echo "changed=$([[ "${CUR}" != "${OLD}" ]] && echo true || echo false)" >> "$GITHUB_OUTPUT"
+
+      - name: Push to data branch
+        if: steps.diff.outputs.changed == 'true'
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git fetch origin data || true
+          git checkout -B data origin/data 2>/dev/null || git checkout -B data
+          mkdir -p data
+          cp "${RUNNER_TEMP}/catalog/catalog.jsonl"      data/
+          cp "${RUNNER_TEMP}/catalog/catalog.jsonl.gz"   data/
+          cp "${RUNNER_TEMP}/catalog/catalog.jsonl.gz.sha256" data/
+          git add data/
+          git commit -qm "chore(data): refresh catalog ($(date -u +%Y-%m-%d))"
+          git push origin data

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nailuoGG
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,68 @@
+# pi-find-packages
+
+A [pi](https://pi.dev) extension providing a local catalog of the pi package ecosystem plus a `/find-packages` integration-review workflow.
+
+## Features
+
+- **Offline catalog**: syncs the full `keywords:pi-package` corpus (~5k+ packages) from npm to local JSONL; search with jq/grep over descriptions, names, and keywords — no dependence on npm's keyword-matched search
+- **`/find-packages <need>`**: retrieve candidates → read-only source analysis in a sandbox → comparison table and recommendation against criteria (feature overlap / peer compatibility / maintenance activity / supply-chain signals)
+- **Cold start**: the package ships a bundled catalog snapshot (`data/catalog.jsonl.gz`); install and use immediately with zero network requests on first run
+- **Docker isolation by default**: candidate repos are cloned and unpacked inside a credential-free, non-root container; isolation can be disabled explicitly (a risk warning is shown on every use — not recommended)
+
+## Install
+
+```bash
+pi install npm:@nailuogg/pi-find-packages
+pi install git:github.com/nailuoGG/pi-find-packages
+pi install /path/to/pi-find-packages   # local trial
+```
+
+## Data directory
+
+`<PI_CODING_AGENT_DIR>/data/pi-find-packages/` (default `~/.pi/agent/data/pi-find-packages/`)
+
+- `catalog.jsonl` — catalog data (one package per line: name/version/description/date/author/keywords/repo)
+- `config.json` — `{"isolation": "docker" | "off", "semantic": "auto" | "on" | "off"}`
+  - `isolation` defaults to `docker` (sandboxed source analysis)
+  - `semantic` controls semantic search over lazily-cached READMEs (via [qmd](https://github.com/tobi/qmd)); defaults to `auto`: enabled automatically when the `qmd` binary is present, force with `"on"`, disable with `"off"`
+
+## Refreshing the catalog
+
+Preferred, in order:
+
+1. `/find-packages update` — pulls the latest snapshot from the jsDelivr `data` branch
+   (`cdn.jsdelivr.net/gh/nailuoGG/pi-find-packages@data`), falls back to the npmmirror
+   tarball of the latest published version. Checksum-verified, atomic replace.
+2. Full rebuild from the npm registry search API (~40 requests):
+
+   ```bash
+   node <package-dir>/scripts/sync-catalog.mjs            # default data dir
+   node scripts/sync-catalog.mjs --out /tmp/catalog       # custom output dir (used by CI)
+   ```
+
+   Once every ≥30 days is plenty — please avoid hammering the npm registry.
+
+A GitHub Actions workflow (`update-data.yml`) refreshes the `data` branch daily when the
+corpus changes, which is what the jsDelivr channel serves. The npmmirror channel tracks
+the latest npm publish and therefore updates on release cadence.
+
+## Analysis sandbox
+
+```bash
+docker build -t pi-find-packages-analysis -f docker/Dockerfile.analysis docker
+```
+
+The image contains no pi and no credentials: it exists solely to clone/unpack/read third-party source. Never execute a candidate package's install scripts or build artifacts in any environment.
+
+## Releasing
+
+Publishing is automated: push a tag `v<version>` matching `package.json`, and the
+`publish.yml` workflow verifies the version, publishes `@nailuogg/pi-find-packages`
+to npm, and creates a GitHub release. The `NPM_TOKEN` repository secret must hold a
+granular npm access token scoped to the `@nailuogg` packages (npmjs.com → Access Keys).
+
+## Security boundaries
+
+- An analysis report is **not** install authorization — whether to `pi install` is always the user's decision
+- `isolation: off` injects a risk warning on every use; third-party package source may contain malicious logic
+- Planned: update channel via GitHub tag + jsDelivr CDN with checksum verification

package/docker/Dockerfile.analysis

@@ -0,0 +1,13 @@
+FROM node:24-bookworm-slim
+
+RUN apt-get update \
+  && apt-get install -y --no-install-recommends bash ca-certificates git ripgrep curl jq \
+  && rm -rf /var/lib/apt/lists/*
+
+# No pi, no credentials: this image only clones/unpacks and reads third-party source.
+RUN useradd -m -s /bin/bash analyst
+RUN mkdir -p /analysis && chown analyst:analyst /analysis
+WORKDIR /analysis
+USER analyst
+
+ENTRYPOINT ["bash"]

package/extensions/find-packages.ts

@@ -0,0 +1,190 @@
+/**
+ * /find-packages — search the local pi-package catalog and kick off guided analysis.
+ *
+ * Data dir: <agentDir>/data/pi-find-packages/catalog.jsonl
+ * Cold start: extracts the bundled data/catalog.jsonl.gz on first run.
+ * Config (config.json in the data dir):
+ *   isolation: "docker" (default) | "off"  — source-analysis execution environment
+ *   semantic:  "auto" (default) | "on" | "off" — qmd-backed semantic search over cached READMEs
+ * Subcommand: /find-packages update — refresh the catalog from jsDelivr (data branch),
+ *   then the npmmirror tarball of the latest published version; local sync script as last resort.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { gunzipSync } from "node:zlib";
+import { createHash } from "node:crypto";
+import { tmpdir } from "node:os";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+const JSDELIVR_GZ = "https://cdn.jsdelivr.net/gh/nailuoGG/pi-find-packages@data/data/catalog.jsonl.gz";
+const JSDELIVR_SHA = "https://cdn.jsdelivr.net/gh/nailuoGG/pi-find-packages@data/data/catalog.jsonl.gz.sha256";
+const NPMIRROR_TARBALL = "https://registry.npmmirror.com/@nailuogg%2Fpi-find-packages/latest";
+
+export default function activate(pi: ExtensionAPI) {
+  // PI_CODING_AGENT_DIR is the official config-dir override (docs/environment-variables.md).
+  const agentDir = process.env.PI_CODING_AGENT_DIR || join(process.env.HOME ?? "", ".pi/agent");
+  const dataDir = join(agentDir, "data/pi-find-packages");
+  const catalog = join(dataDir, "catalog.jsonl");
+  const configFile = join(dataDir, "config.json");
+
+  // Cold start: extract bundled snapshot if catalog missing.
+  const pkgDir = dirname(dirname(fileURLToPath(import.meta.url))); // extensions/../ = package root
+  const bundled = join(pkgDir, "data/catalog.jsonl.gz");
+  if (!existsSync(catalog)) {
+    mkdirSync(dataDir, { recursive: true });
+    if (existsSync(bundled)) {
+      writeFileSync(catalog, gunzipSync(readFileSync(bundled)));
+      pi.appendEntry("find-packages", { event: "cold-start-extract", from: bundled });
+    }
+  }
+
+  function readConfig(): Record<string, unknown> {
+    try {
+      return JSON.parse(readFileSync(configFile, "utf8"));
+    } catch {
+      return {};
+    }
+  }
+
+  function isolation(): "docker" | "off" {
+    return readConfig().isolation === "off" ? "off" : "docker"; // secure default
+  }
+
+  // Semantic search via qmd: "auto" (default) = enabled iff qmd binary exists; "on" forces; "off" disables.
+  let qmdAvailable: boolean | undefined;
+  function semanticEnabled() {
+    const pref = readConfig().semantic;
+    if (pref === "off") return false;
+    if (qmdAvailable === undefined) {
+      try {
+        qmdAvailable = spawnSync("qmd", ["--version"], { timeout: 5000 }).status === 0;
+      } catch {
+        qmdAvailable = false;
+      }
+    }
+    return qmdAvailable;
+  }
+
+  async function fetchText(url: string, timeoutMs = 15000): Promise<string | undefined> {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+      if (!res.ok) return undefined;
+      return await res.text();
+    } catch {
+      return undefined;
+    }
+  }
+
+  async function fetchBuffer(url: string, timeoutMs = 30000): Promise<Buffer | undefined> {
+    try {
+      const res = await fetch(url, { signal: AbortSignal.timeout(timeoutMs) });
+      if (!res.ok) return undefined;
+      return Buffer.from(await res.arrayBuffer());
+    } catch {
+      return undefined;
+    }
+  }
+
+  function sha256(buf: Buffer): string {
+    return createHash("sha256").update(buf).digest("hex");
+  }
+
+  function installCatalog(buf: Buffer, ctx): boolean {
+    const tmp = join(tmpdir(), `catalog.jsonl.${Date.now()}`);
+    try {
+      const jsonl = gunzipSync(buf);
+      JSON.parse(jsonl.toString("utf8").split("\n")[0]); // sanity: first line parses
+      writeFileSync(tmp, jsonl);
+      renameSync(tmp, catalog);
+      return true;
+    } catch {
+      try { spawnSync("rm", ["-f", tmp]); } catch {}
+      ctx.ui.notify("Downloaded catalog failed validation; keeping the existing file.", "error");
+      return false;
+    }
+  }
+
+  async function updateCatalog(ctx): Promise<void> {
+    // 1) jsDelivr data branch (freshest; updated by CI)
+    const gz = await fetchBuffer(JSDELIVR_GZ);
+    const expected = (await fetchText(JSDELIVR_SHA))?.trim();
+    if (gz && expected && sha256(gz) === expected.split(/\s+/)[0]) {
+      if (installCatalog(gz, ctx)) ctx.ui.notify("Catalog updated from jsDelivr (data branch).", "info");
+      return;
+    }
+    // 2) npmmirror tarball of the latest published version (freshness = publish cadence)
+    try {
+      const meta = await (await fetch(NPMIRROR_TARBALL, { signal: AbortSignal.timeout(15000) })).json();
+      const tarballUrl: string | undefined = meta?.dist?.tarball;
+      if (tarballUrl) {
+        const res = await fetch(tarballUrl, { signal: AbortSignal.timeout(60000) });
+        if (res.ok) {
+          const buf = Buffer.from(await res.arrayBuffer());
+          const proc = spawnSync("tar", ["-xzOf", "-", "package/data/catalog.jsonl.gz"], { input: buf });
+          if (proc.status === 0 && proc.stdout?.length) {
+            if (installCatalog(Buffer.from(proc.stdout), ctx)) {
+              ctx.ui.notify("Catalog updated from npmmirror (latest published version).", "info");
+              return;
+            }
+          }
+        }
+      }
+    } catch {}
+    // 3) fall back to the local sync script
+    ctx.ui.notify(
+      "Both CDNs unavailable or checksum mismatch. Rebuild locally with:\n"
+      + `  node ${join(pkgDir, "scripts/sync-catalog.mjs")}`,
+      "warning",
+    );
+  }
+
+  pi.registerCommand("find-packages", {
+    description: "Search local pi-package catalog for packages matching a need; `update` refreshes the catalog",
+    handler: async (args, ctx) => {
+      const query = (args ?? "").trim();
+      if (query === "update") {
+        await updateCatalog(ctx);
+        return;
+      }
+      if (!query) {
+        ctx.ui.notify("Usage: /find-packages <need> — e.g. /find-packages control sessions remotely; or /find-packages update", "warning");
+        return;
+      }
+      if (!existsSync(catalog)) {
+        ctx.ui.notify(`catalog.jsonl not found. Run: /find-packages update  — or: node ${join(pkgDir, "scripts/sync-catalog.mjs")}`, "error");
+        return;
+      }
+      const iso = isolation();
+      const riskNote =
+        iso === "off"
+          ? [
+              "",
+              "⚠️ **Isolation disabled (isolation: off)**: candidate source will be cloned/unpacked on the host.",
+              "Third-party packages may contain malicious install scripts or build logic; host-side analysis is not sandboxed.",
+              "This mode is not recommended. Delete data/pi-find-packages/config.json or set isolation:\"docker\" to restore the default.",
+            ].join("\n")
+          : "";
+      const prompt = [
+        `Search the local pi-package catalog for packages that satisfy the following need, and complete an integration review:`,
+        `**${query}**`,
+        "",
+        "Steps:",
+        "1. Search: run multiple jq/grep keyword passes over `~/.pi/agent/data/pi-find-packages/catalog.jsonl` against description/keywords/name, trying synonyms as needed; "
+        + (semanticEnabled()
+            ? "also run `qmd query --collection pi-pkg-readmes` for semantic search over cached READMEs (skip if empty); "
+            : "")
+        + "pick the 3-5 most relevant candidates.",
+        "2. Review each candidate (read-only): `npm view <pkg>` for version/deps/peer; clone or download source via the repo link; read entry points, extension points, and the README; judge maintenance activity, dependency surface, and supply-chain signals. "
+        + "After reviewing, save the package README to `~/.pi/agent/data/pi-find-packages/readmes/<name with / replaced by __>.md` (first line `# <name> <version> <date>`)"
+        + (semanticEnabled() ? ", then run `qmd index pi-pkg-readmes` to update the index" : "") + ".",
+        `3. Execution environment: ${iso === "docker" ? "all cloning/unpacking/source analysis must run inside the Docker container (see docker/Dockerfile.analysis); the host only receives analysis text; never run a candidate's install scripts." : "not isolated — analyze read-only on the host (see the risk note above)."}`,
+        "4. Criteria: feature overlap with the current setup / installed packages (Unix philosophy: features must not cross); pi compatibility (peer ranges); maintenance activity; dependency and supply-chain safety.",
+        "5. Output: a candidate comparison table (name/version/activity/fit/risk) + a clear recommendation with reasons. The analysis report is not install authorization — I decide whether to integrate.",
+        riskNote,
+      ].filter(Boolean).join("\n");
+      await pi.sendUserMessage(prompt, { deliverAs: "followUp" });
+    },
+  });
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@nailuogg/pi-find-packages",
+  "version": "0.1.1",
+  "description": "Local catalog of the pi package ecosystem with /find-packages: offline search, cold-start data, and sandboxed source analysis for integration review",
+  "type": "module",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "pi-extension",
+    "packages",
+    "catalog",
+    "discovery"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=22"
+  },
+  "pi": {
+    "extensions": [
+      "./extensions/find-packages.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "author": "nailuoGG",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nailuoGG/pi-find-packages.git"
+  },
+  "bugs": {
+    "url": "https://github.com/nailuoGG/pi-find-packages/issues"
+  },
+  "homepage": "https://github.com/nailuoGG/pi-find-packages#readme",
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/sync-catalog.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// Sync the pi-package catalog from the npm registry search API.
+// Data source: https://registry.npmjs.org/-/v1/search?text=keywords:pi-package
+// Output: JSONL (one package per line) at ~/.pi/agent/data/pi-find-packages/catalog.jsonl
+// Usage: node sync-catalog.mjs [--out <dir>]
+//   --out: output directory (default: ~/.pi/agent/data/pi-find-packages; CI writes to a checkout of the data branch)
+
+import { mkdirSync, writeFileSync, renameSync, statSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { gzipSync } from "node:zlib";
+import { createHash } from "node:crypto";
+
+const PAGE_SIZE = 250;
+const REQUEST_DELAY_MS = 1000; // shared runner IPs get rate-limited fast; stay polite // be polite to the registry
+const outArg = process.argv.indexOf("--out");
+const OUT_DIR = outArg > -1 ? process.argv[outArg + 1] : join(homedir(), ".pi/agent/data/pi-find-packages");
+const OUT_FILE = join(OUT_DIR, "catalog.jsonl");
+const OUT_GZ = join(OUT_DIR, "catalog.jsonl.gz");
+
+const seen = new Map(); // name -> record (dedupe across pages)
+let total = Infinity;
+
+async function fetchPage(from) {
+  const url = `https://registry.npmjs.org/-/v1/search?text=keywords:pi-package&size=${PAGE_SIZE}&from=${from}`;
+  for (let attempt = 0; ; attempt++) {
+    const res = await fetch(url, { headers: { accept: "application/json" } });
+    if (res.ok) return res.json();
+    if (attempt >= 5 || (res.status !== 429 && res.status >= 500)) {
+      throw new Error(`registry ${res.status} at from=${from} after ${attempt + 1} attempts`);
+    }
+    const wait = Math.min(30000, 2000 * 2 ** attempt); // 2s, 4s, 8s, 16s, 30s, 30s
+    process.stderr.write(`registry ${res.status} at from=${from}; retrying in ${wait / 1000}s\n`);
+    await new Promise((r) => setTimeout(r, wait));
+  }
+}
+
+function toRecord(p) {
+  const links = p.links || {};
+  return {
+    name: p.name,
+    version: p.version,
+    description: p.description || "",
+    date: p.date || "",
+    author: typeof p.author === "string" ? p.author : p.author?.name || "",
+    publisher: p.publisher?.username || "",
+    keywords: p.keywords || [],
+    npm: links.npm || `https://www.npmjs.com/package/${p.name}`,
+    repo: links.repository || "",
+    homepage: links.homepage || "",
+  };
+}
+
+for (let from = 0; from < total; from += PAGE_SIZE) {
+  const data = await fetchPage(from);
+  total = Math.min(data.total, 10000); // search API caps total at 10000
+  for (const { package: p } of data.objects) seen.set(p.name, toRecord(p));
+  process.stderr.write(`fetched ${seen.size}/${total}\n`);
+  if (from + PAGE_SIZE < total) await new Promise((r) => setTimeout(r, REQUEST_DELAY_MS));
+}
+
+const lines = [...seen.values()]
+  .sort((a, b) => a.name.localeCompare(b.name))
+  .map((r) => JSON.stringify(r));
+
+mkdirSync(OUT_DIR, { recursive: true });
+const tmp = OUT_FILE + ".tmp";
+writeFileSync(tmp, lines.join("\n") + "\n");
+renameSync(tmp, OUT_FILE);
+writeFileSync(OUT_GZ, gzipSync(Buffer.from(lines.join("\n") + "\n")));
+
+writeFileSync(OUT_GZ + ".sha256", createHash("sha256").update(readFileSync(OUT_GZ)).digest("hex") + "\n");
+
+const bytes = statSync(OUT_FILE).size;
+console.log(`done: ${lines.length} packages, ${(bytes / 1e6).toFixed(1)} MB -> ${OUT_FILE}`);
+console.log(`gz: ${(statSync(OUT_GZ).size / 1e6).toFixed(1)} MB -> ${OUT_GZ}`);

package/skills/find-packages/SKILL.md

@@ -0,0 +1,37 @@
+# find-packages: pi package catalog search & integration review
+
+Maintains a local catalog of the pi package ecosystem (same source as pi.dev/packages: npm `keywords:pi-package`) for offline/semantic package discovery, plus a standard integration-evaluation workflow.
+
+## Data
+
+- Catalog file: `~/.pi/agent/data/pi-find-packages/catalog.jsonl` (one package per line: name/version/description/date/author/keywords/npm/repo)
+- Refresh (pick the first that works):
+  1. `/find-packages update` — pulls the latest snapshot from the jsDelivr `data` branch (falls back to the npmmirror tarball of the latest published version); checksum-verified, atomic replace
+  2. `node <package-dir>/scripts/sync-catalog.mjs` — full rebuild from the npm registry search API (~40 requests). Only run when the file is older than 30 days or the user asks; avoid hammering the registry.
+
+## Search methods
+
+1. Lexical: `jq -r 'select(.description|test("keyword";"i")) | [.name,.version,.description] | @tsv' catalog.jsonl` — try multiple synonym groups (English-first; cover channel words like remote/telegram/discord/web).
+2. Semantic (optional): `qmd query --collection pi-pkg-readmes "need description"` — searches cached READMEs of previously reviewed packages (grows over time; skip when the cache is empty). Only use when the `qmd` binary is available and not disabled via `"semantic":"off"` in `config.json`; otherwise skip this step and rely on lexical search.
+3. When both come up empty, fall back to `npm search` and note the catalog may be stale.
+
+## README cache (written as a side effect of review)
+
+After reviewing a candidate, save its README to `~/.pi/agent/data/pi-find-packages/readmes/<name with / replaced by __>.md`, first line `# <name> <version> <date>`; then run `qmd index pi-pkg-readmes` to update the index. **Never bulk-fetch all READMEs** — the corpus grows with real reviews.
+
+## Integration review (check every candidate)
+
+- **Feature overlap**: does it overlap installed packages (`packages` arrays in `~/.pi/agent/settings.json` and the project `.pi/settings.json`) or pi built-ins? No overlap is a hard rule.
+- **Compatibility**: does `npm view <pkg> peerDependencies` cover the current pi version?
+- **Activity**: latest publish date, latest repo commit.
+- **Supply chain**: author/maintainers, dependency count, install/preinstall scripts in package.json, any data-exfiltration paths.
+
+## Execution environment
+
+- **Source analysis must run inside Docker by default** (clone/unpack candidate code via `docker/Dockerfile.analysis`: node24-slim + git + ripgrep, no credentials). The host only receives analysis text. **Never execute a candidate's install scripts or build artifacts.**
+- `"isolation":"off"` in `data/pi-find-packages/config.json` disables isolation — a risk warning is shown on every use; not recommended.
+- Shallow lookups (`npm view`, registry JSON) do not need the container.
+
+## Output convention
+
+Candidate comparison table (name/version/last publish/activity/fit/risk) + a clear recommendation with reasons. **An analysis report is not install authorization** — the user decides whether to `pi install`.