@lincoln504/pi-research 1.3.6 → 1.3.8

package/README.md

@@ -1,9 +1,9 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/Lincoln504/pi-research/main/docs/media/banner.jpg" alt="pi-research" width="100%" />
+  <img src="https://raw.githubusercontent.com/Lincoln504/pi-research/main/docs/media/banner.jpg" alt="pi-research: free unlimited web search and knowledge store for coding agents" width="100%" />
 </p>
 
 <p align="center">
-  <strong>Local web research and knowledge store</strong>
+  <strong>Free unlimited web search &amp; knowledge store for coding agents</strong>
 </p>
 
 <p align="center">
@@ -22,62 +22,64 @@
 
 ---
 
-<a href="https://github.com/Lincoln504/pi-research/actions/workflows/ci.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/Lincoln504/pi-research/ci.yml?style=flat-square&branch=main" /></a> <a href="https://www.npmjs.com/package/@lincoln504/pi-research"><img alt="npm version" src="https://img.shields.io/npm/v/@lincoln504/pi-research.svg?style=flat-square" /></a>
+<a href="https://github.com/Lincoln504/pi-research/actions/workflows/ci.yml"><img alt="Build status" src="https://img.shields.io/github/actions/workflow/status/Lincoln504/pi-research/ci.yml?style=flat-square&branch=main" /></a><br />
+<a href="https://www.npmjs.com/package/@lincoln504/pi-research"><img alt="npm version" src="https://img.shields.io/npm/v/@lincoln504/pi-research.svg?style=flat-square" /></a><br />
+<a href="LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-97ca00?style=flat-square" /></a><br />
+<a href="https://github.com/Lincoln504/pi-research"><img alt="GitHub repository" src="https://img.shields.io/badge/GitHub-Lincoln504%2Fpi--research-181717?style=flat-square&logo=github&logoColor=white" /></a>
 
-**Free, unlimited web search &amp; scraping — no monthly quota, no subscription.** You pay only for the LLM tokens you use, and it can build a searchable knowledge store locally.
+Search and scraping run locally through a stealth browser with no search provider and no monthly cap. You pay only for the LLM tokens you use.
+
+### Install
+
+As a [pi](https://github.com/earendil-works/pi) extension:
+
+```bash
+pi install npm:@lincoln504/pi-research
+```
+
+Standalone, as an [agent skill](docs/AGENT-SKILL.md) for Claude Code, Codex, and OpenClaw:
+
+```bash
+npm install -g @lincoln504/pi-research
+pi-research skill install
+```
+
+In pi it works out of the box on your session's model and pi's configuration. Standalone use (agent skill, CLI, or [SDK](docs/SDK.md)) needs a model configured. See [Configuration](docs/CONFIGURATION.md). The first install pulls the stealth browser engine, which takes a few minutes.
 
 ### How it works
 
-A research run loops through agent teams: a coordinator plans and opens with a search, researcher agents scrape and read in parallel, and an evaluator decides whether to go another round or synthesize — ending in one cited Markdown report, with findings optionally saved to the knowledge store.
+A research run loops through agent teams: a coordinator plans and opens with a search, researcher agents scrape and read in parallel, and an evaluator decides whether to go another round or synthesize. The result is one cited Markdown report with findings optionally saved to the knowledge store.
 
-Three depth levels — normal, deep, ultra — set the team size and number of rounds; ask in natural language and the tool picks the right one:
+Three depth levels (normal, deep, ultra) set the team size and number of rounds. Ask in natural language and the tool picks the right one:
 
 ![Prompt-driven multi-round research in the pi TUI](https://raw.githubusercontent.com/Lincoln504/pi-research/main/docs/media/02-prompt-research.gif)
 
 ### Use cases
 
-- Researching for your [Pi](https://github.com/earendil-works/pi) Coding Agent — plug-and-play, no API key needed.
-- Researching from Claude Code, Codex, or another coding agent, with a cheaper lightweight or local model driving the research so it doesn't spend your main agent's budget.
-- Populating a dataset or index of web sources.
-- Holding research in the knowledge store with a configurable scope — project-specific or globally user-scoped, set per directory from the `/research-config` TUI.
-- Using the pi-research agent skill as OpenClaw's web access.
-- Building agent systems that find and read web content.
+- Researching for your [Pi](https://github.com/earendil-works/pi) Coding Agent. Plug and play with no API key needed.
+- Researching from Claude Code, Codex, OpenClaw, or another coding agent while a cheaper or local model drives the run so it doesn't spend your main agent's budget.
+- Keeping a persistent and searchable knowledge store of findings, scoped globally or per project.
+- Building agent systems that find and read web content or populating a dataset of web sources.
 
 ### Why pi-research
 
-- **Free, unlimited search &amp; scrape — no quota, no monthly fee.** Most AI-search providers cap free searches per month and then charge; results run on *their* index on *their* servers. pi-research's search and scraping layer (DuckDuckGo via a stealth browser) is free and unlimited — you pay only for the LLM tokens you use.
-- **You own your index.** Every finding is written into a local [LanceDB](https://lancedb.com) knowledge store on *your* machine — a persistent, searchable index you control and keep, which also seeds future runs so repeat questions get faster, cheaper answers. Findings can also be kept globally, scoped to a single project, or not kept at all — set per directory, changed whenever you like.
-- **Cited reports, not raw dumps.** It returns one synthesized, sourced Markdown report instead of pasting raw web content into the conversation — context-efficient and easy to verify.
-- **Read-only by design.** Web access runs inside a limited research agent that cannot run shell commands or write, edit, or delete anything. It can read and search files, so treat it as you would any read-only agent with access to your machine.
-- **Search a little or a lot** — three depth levels in the pi tool (four via the SDK and standalone CLI, which add the quick depth-0 path). Levels 1 and 2 are recommended for everyday workflow use; level 3 is for larger-scale investigations.
+- **No quota and no monthly fee.** Most AI search providers cap free searches and then charge, with results served from *their* index on *their* servers. pi-research searches and scrapes locally through DuckDuckGo in a stealth browser.
+- **You own your index.** Every finding is written to a local [LanceDB](https://lancedb.com) knowledge store that seeds future runs, so repeat questions get faster and cheaper answers.
+- **Cited reports rather than raw dumps.** You get one sourced Markdown report instead of raw web content pasted into the conversation. Context efficient and easy to verify.
+- **Read-only by design.** The research agent cannot run shell commands or write, edit, or delete anything. It can read and search files, so treat it as you would any read-only agent with access to your machine.
+- **Search a little or a lot.** Depth levels span a quick pass to a large-scale investigation.
 
 ### Requirements / limitations
 
 - Node.js >= 22.19.0
 - An LLM with a 100k+ context window (bring your own key or use a local model)
-- Internet access
-- A residential IP address — search, scraping, and YouTube transcripts all rely on a residential connection. A datacenter/VPS/cloud IP gets bot-blocked by these providers.
-- The pi runtime the engine builds on — `@earendil-works/pi-ai`, `@earendil-works/pi-coding-agent`, and `@earendil-works/pi-tui`. The pi extension uses the host's copies; the standalone CLI / agent skill install them as dependencies.
-- Cloudflare and similar anti-automation systems block scraping on some sites, so a run will flag pages it can't reach. pi-research compensates with volume: the search tool pulls a large set of results off free DuckDuckGo, giving the model a wide selection of reachable content to cite.
-
-### Install
-
-```bash
-pi install npm:@lincoln504/pi-research
-```
-
-See [Agent skill](docs/AGENT-SKILL.md) or [SDK](docs/SDK.md) to install standalone (no pi extension).
-
-The pi extension works out of the box — it runs on your pi session's model and pi's own configuration. To use it standalone (agent skill / CLI), configure a model: set `PI_RESEARCH_MODEL` (e.g. `openai/gpt-4o`) as an environment variable or in `~/.pi/research/config.env` (the CLI also accepts a per-run `--model`), plus `PI_RESEARCH_API_KEY` if you don't use pi; the SDK takes a `model` option. See [Configuration](docs/CONFIGURATION.md).
-
-The first install pulls the stealth browser engine, which takes a few minutes.
-
-### Stability (v1.x.x)
+- Internet access on a residential IP, since search, scraping, and YouTube transcripts get bot-blocked from datacenter/VPS/cloud IPs
+- The [pi runtime](https://github.com/earendil-works/pi). The pi extension uses the host's copy while the standalone CLI and agent skill install it as a dependency.
+- Cloudflare and similar systems block scraping on some sites. A run flags pages it can't reach and compensates with a wide pool of search results to cite.
 
-v0.1.13 (April 2026) was the last release before a rebuild against current pi APIs and the stealth-browser stack. v1.0.0 is the first stable release since. Channels:
+### Channels
 
-- npm (`npm:@lincoln504/pi-research`) is the stable channel, kept current with breaking pi changes.
-- A git install is the development channel: latest commits, first to break.
+npm (`npm:@lincoln504/pi-research`) is the stable channel and is kept current with breaking pi changes. A git install is the development channel. It has the latest commits and breaks first.
 
 ### License
 

package/docs/ARCHITECTURE.md

@@ -3,8 +3,8 @@
 pi-research is a pi TUI extension for multi-agent web research. It runs inside the pi
 process, registers its tools and commands, and manages its own browser worker pool,
 service registry, and local knowledge store. One engine backs every front-end: besides
-the pi extension it is exposed as a standalone CLI, a portable agent skill — the same
-skill any skills-aware host runs, including OpenClaw — and a programmatic SDK
+the pi extension it is exposed as a standalone CLI, a portable agent skill (the same
+skill any skills-aware host runs, including OpenClaw) and a programmatic SDK
 (`src/sdk.ts`).
 
 ```
@@ -318,7 +318,7 @@ other). This sits above `@lancedb/lancedb` 0.29's declared Arrow peer ceiling
 whenever `@lancedb/lancedb` is upgraded.
 
 Pinned validation library — `typebox` is pinned to the exact version the pi host packages
-depend on (`@earendil-works/pi-ai` / `@earendil-works/pi-coding-agent` 0.83.0 pin `1.3.7`). Every
+depend on (`@earendil-works/pi-ai` / `@earendil-works/pi-coding-agent` 0.84.1 pin `1.3.7`). Every
 tool's parameter schema is built with TypeBox here and handed across the boundary to pi's
 tool system, so the two must agree on `Value.Check`/`Convert` semantics. A floating `^1.1.38`
 range let a fresh consumer install resolve pi-research to a newer TypeBox than pi's, shipping

package/docs/CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.3.8] - 2026-08-13
+
+Presentation and dependency maintenance only. No engine changes.
+
+### Changed
+
+- **README refined.** New tagline ("Free unlimited web search & knowledge store for coding agents"), MIT license and GitHub repository badges added with all four badges stacked vertically, both install paths (pi extension and standalone agent skill) shown up top, and a punctuation pass removing em dashes and surplus commas and semicolons from README and the npm description. The punctuation pass now also covers the intro paragraphs of the docs/ pages.
+- **npm description compacted.** The no-search-API-key and no-quotas clause is covered by "free unlimited" and is gone.
+- **docs/ARCHITECTURE.md** typebox pin rationale updated to cite the current pi host version (0.84.1, which still pins typebox 1.3.7).
+- **In-range dependency refresh.** esbuild 0.28.2, undici 8.10.0, eslint 10.8.1, typescript-eslint 8.67.0. Deliberate exact pins (playwright-core 1.60.0, camoufox-js 0.10.x, lancedb 0.29.0, apache-arrow 21.1.0, transformers 4.2.0) unchanged per their documented rationale.
+
+### Security
+
+- Production audit gate re-verified. The single allowlisted advisory (GHSA-f88m-g3jw-g9cj, sharp via transformers, unreachable image path) still has no upstream fix; no new advisories.
+
+## [1.3.7] - 2026-08-11
+
+Discovery and packaging metadata only — no engine changes.
+
+### Changed
+
+- **README rewritten for concision and effectiveness.** The pitch ("free, unlimited web search & deep research for coding agents — no API key, no quota") now leads the page, install moved up to directly under the badges, each claim is stated once, and detail that only matters after adoption moved to `docs/`. 88 → 78 lines.
+- **npm description and keywords rewritten.** The description is now benefit-led and survives catalog truncation; keywords gained `pi-coding-agent`, `web-research`, `deep-research`, `knowledge-store`, `duckduckgo`, and `skills`, and dropped `security` and `stack-exchange`.
+
 ## [1.3.6] - 2026-08-10
 
 An independent fresh-eyes review of the entire 1.3.4→1.3.5 diff — the previous

package/docs/CONFIGURATION.md

@@ -1,7 +1,7 @@
 ## Configuration
 
-Every front-end (the pi extension, the standalone CLI / agent skill — the surface
-OpenClaw and other skills-aware hosts run — and the SDK) shares one configuration
+Every front-end (the pi extension, the standalone CLI / agent skill that OpenClaw
+and other skills-aware hosts run, and the SDK) shares one configuration
 model. This document covers the
 settings exposed in the `/research-config` TUI first, then the complete
 environment-variable reference, and finally how the configuration layers resolve.

package/docs/KNOWLEDGE-STORE.md

@@ -1,7 +1,7 @@
 ## Knowledge Store
 
-The knowledge store is a local vector database of past research findings. It is used
-in two distinct ways, and it is an optional cache — research works without it:
+The knowledge store is a local vector database of past research findings. It is an
+optional cache (research works without it) and is used in two distinct ways:
 
 - **Knowledge-first answering (advisory).** The `research_knowledge_search` tool
   answers a repeat or overlapping question directly from stored results. The agent is

package/docs/PI-EXTENSION.md

@@ -1,8 +1,8 @@
 ## Pi Extension
 
 pi-research integrates as a [pi](https://github.com/earendil-works/pi)
-extension (`src/index.ts`) — a multi-agent web research engine with a real-time
-TUI, registered directly in the pi process.
+extension (`src/index.ts`), a multi-agent web research engine with a real-time
+TUI registered directly in the pi process.
 
 ### Usage
 

package/docs/SDK.md

@@ -1,7 +1,7 @@
 ## SDK
 
-The programmatic SDK for scripts, CI, and custom tooling. For configuration — the
-layering model, the TUI settings, and every environment variable — see
+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).
 
 ### Install

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@lincoln504/pi-research",
-  "version": "1.3.6",
-  "description": "A set of web research tools (search, scrape, and others) and research agent system that uses them safely and efficiently.",
+  "version": "1.3.8",
+  "description": "Free unlimited web search and deep research for the Pi coding agent. Local knowledge store. Also works from Claude Code, Codex, and OpenClaw.",
   "type": "module",
   "private": false,
   "main": "./src/index.ts",
@@ -52,16 +52,20 @@
     "pi",
     "pi-package",
     "pi-extension",
+    "pi-coding-agent",
     "openclaw",
     "agent-skill",
+    "skills",
     "research",
+    "web-research",
+    "deep-research",
     "agent",
     "web-search",
     "scraping",
+    "knowledge-store",
+    "duckduckgo",
     "stealth-browser",
-    "camoufox",
-    "security",
-    "stack-exchange"
+    "camoufox"
   ],
   "author": "Lincoln Deen",
   "contributors": [

package/skills/pi-research/SKILL.md

@@ -2,7 +2,7 @@
 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.3.6", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
+metadata: { "author": "Lincoln Deen", "version": "1.3.8", "package": "@lincoln504/pi-research", "engine": "pi-research-sdk", "openclaw": { "requires": { "bins": ["node"] } } }
 allowed-tools: Bash(node:*)
 ---