@apmantza/greedysearch-pi 2.1.2 → 2.1.4

package/CHANGELOG.md

@@ -1,6 +1,40 @@
 # Changelog
 
-## [Unreleased]
+## [Unreleased]
+
+### Added
+
+### Changed
+
+### Fixed
+
+## [2.1.4] — 2026-07-04
+
+### Added
+
+- **Changelog-driven release notes** (`scripts/changelog-extract.mjs`, `scripts/changelog-release.mjs`, `scripts/backfill-github-releases.mjs`, `.github/workflows/release.yml`) — GitHub releases now use curated CHANGELOG sections as the release body, with helper scripts for promoting `Unreleased`, extracting summary notes, and backfilling historical releases. The parser supports both current `## [x.y.z] — date` headings and legacy `## vx.y.z (date)` headings.
+
+### Changed
+
+- **README simplified like pi-lens and package skill removed** (`README.md`, `docs/*.md`, `package.json`) — The root README is now a concise project overview with installation, quick usage, and links to focused docs for usage, research mode, runtime/Chrome, source fetching, development, and releases. The duplicated Pi skill file was removed so docs live in one place.
+- **Normal all-engine config excludes Semantic Scholar** (`src/search/constants.mjs`, `~/.pi/greedyconfig`) — Default and local all-engine fan-out now use Perplexity, Google, ChatGPT, and Gemini while academic/research engines remain opt-in.
+
+### Fixed
+
+- **Headless ChatGPT and Gemini extraction in all-mode** (`extractors/chatgpt.mjs`, `extractors/gemini.mjs`, `bin/search.mjs`) — ChatGPT now keeps its tab foregrounded during headless streaming, waits for streaming indicators to clear, and rejects repeated-domain citation stubs. Gemini now targets the latest `model-response`, avoids nested code-block copy buttons, and prefers a complete DOM fallback when clipboard copy captures only a snippet.
+- **Research-mode floor and citation handling** (`src/search/research.mjs`, `src/search/simple-research.mjs`) — Explicit `breadth` / `iterations` values now bypass scale-aware overrides, duplicate fetch targets are skipped, cited-source URL checks only evaluate cited sources, and bot-protected HEAD responses are skipped instead of treated as dead links.
+- **Fetcher return style consistency** (`src/fetcher.mjs`) — Multi-line formatting for the protocol-not-allowed return object in `isPrivateUrl` to match the project's code style conventions.
+
+## [2.1.3] — 2026-06-21
+
+### Fixed
+
+- **Stale dependency resolution** — `jsdom` was installed at `24.1.3` despite `package.json` declaring `^29.1.1` (lockfile freeze). Fresh lockfile resolves all deps to latest within semver ranges. Updated `@sinclair/typebox` `^0.34.48` → `^0.34.49`.
+- **Peer dep pin** — `@earendil-works/pi-coding-agent` peer dep changed from wildcard `*` to `^0.79.0` to pin compatible range against Pi `0.79.9`.
+
+### Changed
+
+- **CI security audit** — Added `npm audit --omit=dev --audit-level=high` to GitHub Actions CI (matching pi-lens) to block pushes/PRs that introduce high/critical vulnerabilities in production dependencies.
 
 ## [2.1.2] — 2026-06-18
 

package/README.md

@@ -1,14 +1,19 @@
+<p align="center">
+  <img src="docs/banner.svg" alt="GreedySearch for Pi" width="1100">
+</p>
+
 # GreedySearch for Pi
 
-![GreedySearch](docs/banner.svg)
+GreedySearch registers the `greedy_search` tool for Pi: headless-first,
+no-API-key AI/web search through a dedicated Chrome profile.
 
-Multi-engine AI web search for Pi via browser automation.
+## What It Does
 
-- No API keys
-- Real browser results from configurable engines: Perplexity, Google AI, ChatGPT, Gemini, plus opt-in Semantic Scholar and Logically research engines
-- Research mode as the centerpiece: iterative planning, source fetching, citation audit, and structured bundles
-- Optional configurable synthesis with source grounding (Gemini by default)
-- Chrome runs headless by default — no window, purely background
+- Multi-engine search across Perplexity, Google AI, ChatGPT, and Gemini
+- Source-grounded `engine: "all"` results with fetched source content
+- Optional synthesis over engine answers and fetched sources
+- Iterative `depth: "research"` runs with citation audit and research bundles
+- Visible Chrome fallback for login/captcha/cookie setup when needed
 
 ## Install
 
@@ -22,16 +27,12 @@ Or from git:
 pi install git:github.com/apmantza/GreedySearch-pi
 ```
 
-## Tool
-
-- `greedy_search` — multi-engine AI web search, source-grounded synthesis, and deep research
-
-## Quick usage
+## Quick Usage
 
 ```js
-greedy_search({ query: "React 19 changes" }); // all engines + fetched sources
-greedy_search({ query: "React 19 changes", synthesize: true }); // add configured synthesis
-greedy_search({ query: "Prisma vs Drizzle", engine: "perplexity" }); // individual engine
+greedy_search({ query: "React 19 changes" });
+greedy_search({ query: "React 19 changes", synthesize: true });
+greedy_search({ query: "Prisma vs Drizzle", engine: "perplexity" });
 greedy_search({
   query: "Evaluate browser automation options for AI agents",
   depth: "research",
@@ -39,181 +40,32 @@ greedy_search({
   iterations: 2,
   maxSources: 8,
 });
-// Research mode writes a dataroom-style bundle under .pi/greedysearch-research/ by default.
-// Headless is the default — no window. To force visible Chrome:
-greedy_search({ query: "Visible browser setup", engine: "perplexity", visible: true });
-```
-
-## Parameters (`greedy_search`)
-
-### Common
-
-- `query` (required)
-- `fullAnswer`: return full single-engine output instead of preview
-- `headless`: set to `false` to show Chrome window (default: `true`)
-- `visible` / `alwaysVisible`: set to `true` to always use visible Chrome for this search
-
-### Normal search
-
-- `engine`: `all` (default web/search fan-out), `perplexity`, `google`, `chatgpt`, `gemini`; opt-in research engines: `semantic-scholar`, `logically`; `bing` still works for signed-in users
-- `synthesize`: for `engine: "all"`, synthesize fetched sources with the configured synthesizer (default false)
-- `synthesizer`: override the configured synthesis engine for this call (`gemini` default, `chatgpt` supported)
-- `depth`: legacy `fast`/`standard`/`deep` aliases are still accepted for compatibility; prefer `synthesize` for normal search
-
-### Deep research
-
-- `depth`: set to `"research"` to run the iterative research workflow
-- `breadth`: number of research actions per round, 1-5 (default 3)
-- `iterations`: research rounds, 1-3 (default 2)
-- `maxSources`: fetched source cap for the final report, 3-12
-- `researchOutDir`: optional directory for the research bundle
-- `writeResearchBundle`: write the research bundle to disk (default true for research mode)
-
-Deep research uses the configured `~/.pi/greedyconfig.engines` list for child searches and Gemini for planning/final synthesis.
-
-## Environment variables
-
-| Variable                             | Default       | Description                                                   |
-| ------------------------------------ | ------------- | ------------------------------------------------------------- |
-| `GREEDY_SEARCH_VISIBLE`              | (unset)       | Set to `1` to show Chrome window instead of headless          |
-| `GREEDY_SEARCH_ALWAYS_VISIBLE`       | (unset)       | Set to `1` to force visible Chrome for all GreedySearch runs  |
-| `GREEDY_SEARCH_IDLE_TIMEOUT_MINUTES` | `5`           | Minutes of inactivity before auto-killing GreedySearch Chrome |
-| `GREEDY_SEARCH_LOCALE`               | `en`          | Default result language (en, de, fr, es, ja, etc.)            |
-| `CHROME_PATH`                        | auto-detected | Path to Chrome/Chromium executable                            |
-
-## Search modes
-
-- **Individual engine search/research** — `engine: "perplexity" | "google" | "chatgpt" | "gemini" | "semantic-scholar" | "logically" | "bing"`; returns that engine's answer and sources.
-- **Grounded multi-engine search** — default `engine: "all"`; fans out to configured engines, ranks sources, fetches top source content, and reports confidence metadata.
-- **All + synthesis** — add `synthesize: true` (or CLI `--synthesize`) to ask the configured synthesizer to combine engine answers and fetched source evidence.
-- **Deep research** — `depth: "research"`; iterative action planning, direct URL fetches, fast multi-engine searches, source fetching, learning extraction, deterministic floor checks, citation audit, a final cited report, and a structured on-disk bundle.
-
-Legacy `depth: "fast" | "standard" | "deep"` values remain accepted for compatibility: `fast` skips source fetching; `standard`/`deep` request synthesis.
-
-Configure all-engine fan-out and synthesis in `~/.pi/greedyconfig`:
-
-```json
-{
-  "engines": ["perplexity", "google", "chatgpt", "gemini"],
-  "synthesizer": "gemini"
-}
-```
-
-Gemini is a normal search engine and can participate in `engine: "all"`. `semantic-scholar` and `logically` are opt-in academic/research engines; include them in `~/.pi/greedyconfig` only when you want the all-engine fan-out to include academic paper discovery or research-assistant workflows. Default `engine: "all"` excludes them because their results are noisy for casual web search — they shine in `depth: "research"` mode instead. Deep research child searches reuse the same configured `engines` list and keep query text on stdin; Gemini remains the research planner/final-report synthesizer. If `synthesize: true` and `"synthesizer": "gemini"`, Gemini runs once as a search engine and again as the synthesizer; set `"synthesizer": "chatgpt"` to separate those roles for normal all-search synthesis.
-
-Research bundles are written by default to `.pi/greedysearch-research/<timestamp>_<query>/` and include:
-
-```text
-STATUS.md              # floor status, open/closed question ledger, and gaps
-OUTLINE.md             # bundle table of contents
-reports/SUMMARY.md     # final cited report
-reports/CLAIMS.md      # extracted claims mapped to source IDs
-reports/EVIDENCE.md    # goal-based evidence extracted from fetched sources
-reports/GAPS.md        # caveats and remaining uncertainties
-sources/               # fetched source markdown files
-data/manifest.json     # run metadata, stop reason, floor checks, citation audit
-data/rounds.json       # per-round actions/learnings/gaps
-data/sources.json      # ranked source registry
-data/questions.json    # STATUS-style question ledger with evidence/source IDs
-data/evidence.json     # structured rational/evidence/summary per useful source
-```
-
-CLI controls:
-
-```bash
-node bin/search.mjs all --inline --stdin --depth research --breadth 3 --iterations 2 --max-sources 8 <<'EOF'
-Evaluate browser automation options for AI agents
-EOF
-node bin/search.mjs all "topic" --depth research --research-out-dir ./research-topic
-node bin/search.mjs all "topic" --depth research --no-research-bundle
 ```
 
-## Runtime commands
+Headless is the default. Use `visible: true` only when you need to establish a
+session, solve a challenge, or inspect the browser:
 
-Inside Pi, prefer the extension commands (no package path needed):
-
-```text
-/greedy-visible      # launch visible Chrome for captcha/login/cookie setup
-/greedy-status       # show GreedySearch Chrome status
-/greedy-kill         # stop GreedySearch Chrome
-/set-greedy-locale   # set default result language (de, fr, es, ja, etc.)
-```
-
-Git install path:
-
-```bash
-GS=~/.pi/agent/git/github.com/apmantza/GreedySearch-pi
-node "$GS/bin/launch.mjs" --status
-node "$GS/bin/visible.mjs"          # visible mode
-node "$GS/bin/visible.mjs" --kill   # strong visible/port cleanup
-node "$GS/bin/kill-visible.mjs"     # same as visible.mjs --kill
-node "$GS/bin/cdp-visible.mjs" list # safe CDP: GreedySearch visible Chrome only
-node "$GS/bin/cdp-headless.mjs" list # safe CDP: GreedySearch headless Chrome only
-node "$GS/bin/cdp-greedy.mjs" list  # safe CDP: any GreedySearch Chrome mode
-```
-
-npm global install path:
-
-```bash
-GS="$(npm root -g)/@apmantza/greedysearch-pi"
-node "$GS/bin/launch.mjs" --status
-node "$GS/bin/visible.mjs"
-node "$GS/bin/visible.mjs" --kill
-node "$GS/bin/kill-visible.mjs"
-node "$GS/bin/cdp-visible.mjs" list
-node "$GS/bin/cdp-headless.mjs" list
-node "$GS/bin/cdp-greedy.mjs" list
+```js
+greedy_search({ query: "Visible setup", engine: "perplexity", visible: true });
 ```
 
-Chrome is auto-cleaned after 5 min idle. Override with `GREEDY_SEARCH_IDLE_TIMEOUT_MINUTES=10` or disable with `0`.
+## Documentation
 
-**CDP safety:** use `cdp-visible.mjs`, `cdp-headless.mjs`, or `cdp-greedy.mjs` for debugging. They always set `CDP_PROFILE_DIR` to the dedicated GreedySearch Chrome profile and never fall back to your main Chrome session. Avoid calling raw `bin/cdp.mjs` manually unless you explicitly set `CDP_PROFILE_DIR`.
+- [Usage guide](docs/usage.md) — tool parameters, search modes, and config
+- [Research mode](docs/research.md) — iterative workflow and bundle layout
+- [Runtime and Chrome](docs/runtime.md) — slash commands, env vars, CDP safety
+- [Source fetching](docs/source-fetching.md) — supported source types and metadata
+- [Development](docs/development.md) — project layout, tests, and smoke checks
+- [Release workflow](docs/releases.md) — changelog scripts and GitHub releases
 
 ## Requirements
 
-- Chrome
+- Chrome or Chromium
 - Node.js 20.11.0+
 
-## Source fetching
-
-When using `engine: "all"`, top source content is fetched by default. Add `synthesize: true` to synthesize with the configured synthesizer:
-
-- **PDFs** — Direct PDF links are parsed to markdown text for source-grounded synthesis
-- **Semantic Scholar** — Discovers academic papers and prefers direct PDF/external paper links when available
-- **Reddit** — Uses Reddit's public `.json` API for posts and comments
-- **GitHub** — Uses GitHub REST API for repos, READMEs, and file trees
-- **General web** — Mozilla Readability extraction with browser fallback when needed
-- **Metadata** — title, author/byline, site name, publish date, language, excerpt
-
-## Project layout
-
-- `bin/` — runtime CLIs (`search.mjs`, `launch.mjs`, `launch-visible.mjs`, `visible.mjs`, `kill-visible.mjs`, safe CDP wrappers, `cdp.mjs`)
-- `extractors/` — engine-specific automation + stealth/consent handling
-- `src/` — search pipeline, chrome management, source fetching, formatting
-- `skills/` — Pi skill metadata
-
-## Testing
-
-Cross-platform test runner (Windows + Unix):
-
-```bash
-npm test              # run all tests
-npm run test:quick    # skip slow tests
-npm run test:smoke    # basic health check
-```
-
-Full bash test suite (Unix only):
-
-```bash
-npm run test:bash           # comprehensive tests
-./test.sh parallel          # race condition tests
-./test.sh flags             # flag/option tests
-```
-
-## Changelog
-
-See `CHANGELOG.md`.
+## Contributing
 
-## License
+See [`CONTRIBUTING.md`](CONTRIBUTING.md) and [`AGENTS.md`](AGENTS.md) for the
+extractor, recovery, and release checklists.
 
-MIT
+GreedySearch is released under the [MIT License](LICENSE).

package/bin/search.mjs

@@ -314,6 +314,8 @@ async function main() {
 		const ENGINE_START_URLS = {
 			perplexity: "https://www.perplexity.ai/",
 			google: "https://www.google.com/",
+			chatgpt: "https://chatgpt.com/",
+			gemini: "https://gemini.google.com/app",
 			"semantic-scholar": "https://www.semanticscholar.org/",
 			semanticscholar: "https://www.semanticscholar.org/",
 			s2: "https://www.semanticscholar.org/",

package/docs/banner.svg

@@ -0,0 +1,86 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 1200 480" width="1200" height="480">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#0d1117"/>
+      <stop offset="50%" style="stop-color:#161b22"/>
+      <stop offset="100%" style="stop-color:#0d1117"/>
+    </linearGradient>
+
+    <linearGradient id="title" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#58a6ff"/>
+      <stop offset="50%" style="stop-color:#bc8cff"/>
+      <stop offset="100%" style="stop-color:#3fb950"/>
+    </linearGradient>
+
+    <linearGradient id="piGrad" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#8b5cf6"/>
+      <stop offset="100%" style="stop-color:#a78bfa"/>
+    </linearGradient>
+
+    <filter id="glow" x="-20%" y="-20%" width="140%" height="140%">
+      <feGaussianBlur stdDeviation="6" result="blur"/>
+      <feComposite in="SourceGraphic" in2="blur" operator="over"/>
+    </filter>
+
+    <pattern id="dots" width="20" height="20" patternUnits="userSpaceOnUse">
+      <circle cx="2" cy="2" r="0.8" fill="#30363d" opacity="0.4"/>
+    </pattern>
+  </defs>
+
+  <!-- Background -->
+  <rect width="1200" height="480" fill="url(#bg)"/>
+  <rect width="1200" height="480" fill="url(#dots)"/>
+
+  <circle cx="1050" cy="100" r="300" fill="#bc8cff" opacity="0.03"/>
+  <circle cx="1150" cy="400" r="200" fill="#3fb950" opacity="0.03"/>
+
+  <!-- ===== PI LOGO (left) ===== -->
+  <g transform="translate(60, 140)">
+    <circle cx="60" cy="60" r="72" fill="none" stroke="#8b5cf6" stroke-width="2" opacity="0.3"/>
+    <circle cx="60" cy="60" r="62" fill="none" stroke="#8b5cf6" stroke-width="1" opacity="0.1"/>
+    <g transform="translate(18, 18) scale(2.6)">
+      <path fill="#8b5cf6" fill-rule="evenodd" d="M0 0H15V10H10V15H5V20H0ZM5 5V10H10V5Z"/>
+      <rect x="15" y="10" width="5" height="10" fill="#8b5cf6"/>
+    </g>
+  </g>
+
+  <!-- ===== TITLE ===== -->
+  <text x="240" y="195" font-family="'Segoe UI', -apple-system, system-ui, sans-serif" font-size="72" font-weight="700" letter-spacing="-1.5" fill="url(#title)" filter="url(#glow)">
+    GreedySearch
+  </text>
+
+  <!-- ===== "No API keys" badge ===== -->
+  <g transform="translate(240, 218)">
+    <rect x="0" y="0" width="155" height="28" rx="14" fill="#1f6feb" opacity="0.15"/>
+    <rect x="0" y="0" width="155" height="28" rx="14" fill="none" stroke="#1f6feb" stroke-width="1" opacity="0.3"/>
+    <text x="77" y="19" font-family="'Segoe UI', -apple-system, system-ui, sans-serif" font-size="13" font-weight="600" fill="#58a6ff" text-anchor="middle">🔑 No API keys</text>
+  </g>
+
+  <!-- ===== TAGLINE ===== -->
+  <text x="240" y="280" font-family="'Segoe UI', -apple-system, system-ui, sans-serif" font-size="20" font-weight="400" fill="#8b949e" letter-spacing="0.3">
+    Multi-engine AI search via browser automation.
+  </text>
+
+  <!-- ===== ENGINE PILLS ===== -->
+  <g transform="translate(240, 310)">
+    <!-- Perplexity -->
+    <rect x="0" y="0" width="115" height="30" rx="15" fill="#00c8b4" opacity="0.12"/>
+    <rect x="0" y="0" width="115" height="30" rx="15" fill="none" stroke="#00c8b4" stroke-width="1" opacity="0.3"/>
+    <text x="57" y="20" font-family="'Segoe UI', -apple-system, system-ui, sans-serif" font-size="13" font-weight="600" fill="#00c8b4" text-anchor="middle">Perplexity</text>
+
+    <!-- Bing -->
+    <rect x="130" y="0" width="115" height="30" rx="15" fill="#00a4ef" opacity="0.12"/>
+    <rect x="130" y="0" width="115" height="30" rx="15" fill="none" stroke="#00a4ef" stroke-width="1" opacity="0.3"/>
+    <text x="187" y="20" font-family="'Segoe UI', -apple-system, system-ui, sans-serif" font-size="13" font-weight="600" fill="#00a4ef" text-anchor="middle">Bing Copilot</text>
+
+    <!-- Google AI -->
+    <rect x="260" y="0" width="115" height="30" rx="15" fill="#fbbc04" opacity="0.12"/>
+    <rect x="260" y="0" width="115" height="30" rx="15" fill="none" stroke="#fbbc04" stroke-width="1" opacity="0.3"/>
+    <text x="317" y="20" font-family="'Segoe UI', -apple-system, system-ui, sans-serif" font-size="13" font-weight="600" fill="#fbbc04" text-anchor="middle">Google AI</text>
+
+    <!-- Gemini -->
+    <rect x="390" y="0" width="100" height="30" rx="15" fill="#8b5cf6" opacity="0.12"/>
+    <rect x="390" y="0" width="100" height="30" rx="15" fill="none" stroke="#8b5cf6" stroke-width="1" opacity="0.3"/>
+    <text x="440" y="20" font-family="'Segoe UI', -apple-system, system-ui, sans-serif" font-size="13" font-weight="600" fill="#a78bfa" text-anchor="middle">Gemini</text>
+  </g>
+</svg>

package/docs/development.md

@@ -0,0 +1,63 @@
+# Development
+
+## Project Layout
+
+- `index.ts` — Pi extension entrypoint.
+- `src/tools/greedy-search-handler.ts` — Pi tool registration/handler.
+- `bin/search.mjs` — CLI orchestration.
+- `extractors/` — engine-specific browser automation.
+- `src/search/` — search pipeline, Chrome lifecycle, recovery, synthesis,
+  source ranking, and research orchestration.
+- `test.mjs`, `test-suite/`, `test/` — unit and smoke tests.
+
+Pi loads this extension through `jiti`; TypeScript does not need to be
+precompiled for Pi runtime.
+
+## Checks
+
+```bash
+npm run check:lockfile
+npm run lint
+node test.mjs unit
+npm pack --dry-run --json
+```
+
+Jiti load check:
+
+```bash
+node - <<'NODE'
+import { createJiti } from 'file:///C:/Users/R3LiC/AppData/Roaming/npm/node_modules/@earendil-works/pi-coding-agent/node_modules/jiti/lib/jiti.mjs';
+const jiti = createJiti(import.meta.url, { interopDefault: true });
+const mod = await jiti.import('./index.ts');
+console.log('jiti ok', typeof mod.default);
+NODE
+```
+
+## Useful Headless Smoke Checks
+
+```bash
+node bin/launch.mjs --kill || node bin/kill-visible.mjs
+node bin/search.mjs all --inline --stdin --full <<'EOF'
+TypeScript 5.8 5.9 Node.js ESM module-resolution changes
+EOF
+
+node bin/search.mjs all --inline --stdin --depth research \
+  --breadth 1 --iterations 1 --max-sources 3 <<'EOF'
+Node.js native TypeScript type stripping for CLI authors
+EOF
+```
+
+## Extractor Notes
+
+When adding or changing an extractor:
+
+1. Reuse `extractors/common.mjs` utilities.
+2. Prefer single in-browser polling evals over Node-side CDP polling loops.
+3. Use language-agnostic selectors and data attributes where possible.
+4. Avoid matching English UI strings except as a last resort.
+5. Register new engines in both `src/search/constants.mjs` and `bin/search.mjs`
+   when they need all-mode pre-seeding.
+6. Update `README.md`, `docs/`, `src/tools/greedy-search-handler.ts`, and
+   `CHANGELOG.md`.
+
+See [`AGENTS.md`](../AGENTS.md) for the full extractor and recovery guide.

package/docs/releases.md

@@ -0,0 +1,88 @@
+# Release Workflow
+
+Releases are automated from `package.json` versions and `CHANGELOG.md` sections.
+The curated changelog entry is the source of truth for GitHub release notes.
+
+## Cut a Release
+
+1. Bump `package.json`.
+2. Add entries under `## [Unreleased]`.
+3. Promote the changelog section:
+
+   ```bash
+   npm run changelog:release
+   ```
+
+   Or with explicit values:
+
+   ```bash
+   node scripts/changelog-release.mjs 2.2.0 --date 2026-07-03
+   ```
+
+4. Run checks:
+
+   ```bash
+   npm run check:lockfile
+   npm run lint
+   node test.mjs unit
+   ```
+
+5. Commit and push to `master`.
+
+## Changelog Scripts
+
+- `npm run changelog:check` — verifies `## [Unreleased]` has releaseable
+  entries.
+- `npm run changelog:release` — moves `Unreleased` into the current
+  `package.json` version and opens a fresh empty `Unreleased` section.
+- `npm run changelog:extract -- <version>` — prints release notes for a
+  version.
+- `npm run release:backfill-notes` — dry-run GitHub release-body backfill.
+
+The parser supports both current headings like:
+
+```markdown
+## [2.1.3] — 2026-06-21
+```
+
+and older headings like:
+
+```markdown
+## v1.8.5 (2026-04-29)
+```
+
+so historical releases can be backfilled from the same changelog.
+
+## GitHub Release Notes
+
+`.github/workflows/release.yml` extracts release notes with:
+
+```bash
+node scripts/changelog-extract.mjs "$VERSION" --summary -o RELEASE_NOTES.md
+```
+
+and passes `RELEASE_NOTES.md` to `softprops/action-gh-release`. GitHub release
+bodies therefore match the curated changelog summary instead of generated PR
+or commit-title notes.
+
+## Backfill Existing Releases
+
+Preview the update plan:
+
+```bash
+npm run release:backfill-notes
+```
+
+Apply it with the GitHub CLI authenticated:
+
+```bash
+node scripts/backfill-github-releases.mjs --apply
+```
+
+Limit to specific tags:
+
+```bash
+node scripts/backfill-github-releases.mjs --apply --only v2.1.3,v2.1.2
+```
+
+Use `--full` to write the full changelog prose instead of the summarized body.

package/docs/research.md

@@ -0,0 +1,82 @@
+# Research Mode
+
+Set `depth: "research"` to run GreedySearch's iterative research workflow.
+
+```js
+greedy_search({
+  query: "Evaluate browser automation options for AI agents",
+  depth: "research",
+  breadth: 3,
+  iterations: 2,
+  maxSources: 8,
+});
+```
+
+## Workflow
+
+Research mode performs:
+
+1. Query complexity classification when breadth/iterations are not explicit.
+2. Action planning with Gemini.
+3. Fast all-engine child searches using the configured engine list.
+4. Direct URL fetches when useful.
+5. Source ranking, dedupe, and source-content fetching.
+6. Evidence and learning extraction.
+7. Final cited synthesis.
+8. Citation audit, URL reachability checks, and deterministic floor checks.
+
+Simple questions may take a single-pass path. Explicit `breadth` or
+`iterations` values always override classifier suggestions.
+
+## Bundle Layout
+
+Research bundles are written by default under
+`.pi/greedysearch-research/<timestamp>_<query>/`.
+
+```text
+STATUS.md              # floor status, question ledger, and gaps
+OUTLINE.md             # bundle table of contents
+provenance.md          # run metadata and verification summary
+reports/SUMMARY.md     # final cited report
+reports/CLAIMS.md      # claims mapped to source IDs
+reports/EVIDENCE.md    # extracted source evidence
+reports/GAPS.md        # caveats and remaining uncertainties
+sources/               # fetched source markdown files
+data/manifest.json     # metadata, stop reason, floor checks, citation audit
+data/rounds.json       # per-round actions/learnings/gaps
+data/sources.json      # ranked source registry
+data/questions.json    # open/closed question ledger
+data/evidence.json     # structured evidence per useful source
+```
+
+## CLI
+
+```bash
+node bin/search.mjs all --inline --stdin --depth research \
+  --breadth 3 --iterations 2 --max-sources 8 <<'EOF'
+Evaluate browser automation options for AI agents
+EOF
+
+node bin/search.mjs all --inline --stdin --depth research \
+  --research-out-dir ./research-topic <<'EOF'
+Topic
+EOF
+
+node bin/search.mjs all --inline --stdin --depth research \
+  --no-research-bundle <<'EOF'
+Topic
+EOF
+```
+
+## Verification
+
+The provenance sidecar records:
+
+- sources consulted, fetched, and cited;
+- primary/official source counts;
+- citation audit status;
+- citation URL reachability;
+- floor checks and overall status.
+
+Bot-protected or HEAD-disallowing hosts are skipped in URL reachability rather
+than marked dead when they return common anti-bot statuses such as 403.