@lincoln504/pi-research 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lincoln504
+
+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,131 @@
+![pi-research banner](docs/assets/README-banner.jpg)
+
+<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>
+
+Multi-agent web research extension for [pi](https://github.com/badlogic/pi-mono). Runs parallel AI researchers against a self-hosted SearXNG search container, scrapes pages, queries security databases, and tracks everything in a real-time terminal UI.
+
+---
+
+## Contents
+
+- [Capabilities](#capabilities)
+- [Requirements](#requirements)
+- [Install](#install)
+- [Platform Setup](#platform-setup)
+- [Usage](#usage)
+- [Research Depth](#research-depth)
+- [Configuration](#configuration)
+- [Development & Release](#development--release)
+- [Architecture & Design](docs/ARCHITECTURE.md)
+
+---
+
+## Capabilities
+
+- **Multi-agent deep research** — AI coordinator decomposes a query into parallel research tracks; an AI lead evaluator synthesizes or delegates further rounds
+- **Quick mode** — single researcher for fast, focused queries with no coordinator overhead
+- **Web search** — SearXNG running in Docker, aggregating Bing, Brave, Yahoo, Qwant, DuckDuckGo, Wikipedia, GitHub, arXiv, and Semantic Scholar (engines can be enabled or disabled via [config](docs/ARCHITECTURE.md#searxng-lifecycle-management))
+- **URL scraping** — fetch-first with Playwright/Chromium fallback for JavaScript-heavy pages
+- **Security databases** — NVD, CISA KEV, GitHub Advisories, OSV
+- **Stack Exchange** — full network search and filtering
+- **Real-time TUI** — per-researcher token and cost tracking
+
+```
+── Research: 70% ─────────────────────────────────────
+┌───────┬────┐ 1 ┌─────┬────┐ 2 ┌────┬────┐ 3 ┌────┐
+│SearXNG│     18k      │     36k     │     50k     │
+│:55732 │   $0.0056    │   $0.0055   │   $0.0071   │
+└───────┴──────────────┴─────────────┴─────────────┘
+```
+
+
+---
+
+## Requirements
+
+- Node.js `22.13.0` or any `24.x+` release
+- The `pi` CLI installed and configured
+- Docker daemon running (required for SearXNG)
+- Internet access
+
+---
+
+## Install
+
+```bash
+pi install npm:@lincoln504/pi-research
+```
+
+**From a checkout**
+
+```bash
+npm install
+pi install .
+```
+
+---
+
+## Platform Setup
+
+**macOS/Linux** — Install and start Docker. Ensure your user is in the `docker` group on Linux.
+**Windows** — Install Docker Desktop (Linux containers). Detecting named pipes is automatic.
+
+---
+
+## Usage
+
+Ask pi for web research. The extension registers a `research` tool.
+
+```text
+Research "What is a binary search tree?"
+Do a deep dive on CVE-2024-3094 at depth 2
+```
+
+| Depth | Mode | Researchers | Target rounds |
+|-------|------|-------------|---------------|
+| 0 (default) | Quick | 1 | 1 |
+| 1 | Normal | 2 | 2 |
+| 2 | Deep | 3 | 3 |
+| 3 | Ultra | 5 | 5 |
+
+---
+
+## Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `BRAVE_SEARCH_API_KEY` | — | Enables `braveapi` engine (official REST API) |
+| `PI_RESEARCH_VERBOSE` | — | Set to `1` to write diagnostic JSONL logs to a temp file (see below) |
+| `PI_RESEARCH_SKIP_HEALTHCHECK` | — | Skip startup health check (set to `1` if engines are blocked) |
+| `PROXY_URL` | — | Proxy for SearXNG outgoing requests (e.g. `socks5://127.0.0.1:9050`) |
+| `STACKEXCHANGE_API_KEY` | — | Stack Exchange API key (increases limit from 300 to 10,000/day) |
+| `PI_RESEARCH_SEARCH_LANGUAGE` | `en-US` | BCP 47 language tag for search result filtering |
+| `PI_RESEARCH_RESEARCHER_TIMEOUT_MS` | `240000` | Per-researcher timeout (30s to 10m) |
+| `PI_RESEARCH_MAX_CONCURRENT_RESEARCHERS` | `3` | Maximum researchers running simultaneously (1 to 10) |
+| `PI_RESEARCH_CONSOLE_RESTORE_DELAY_MS` | `15000` | Delay before TUI clears after research ends |
+| `SEARXNG_IMAGE_TAG` | `latest` | SearXNG Docker image tag — pin to a specific release for reproducibility (e.g. `2024.12.23`) |
+
+**Verbose logging**
+
+Set `PI_RESEARCH_VERBOSE=1` (or pass `--verbose`) to enable diagnostic output. Logs are written as JSONL to `{os.tmpdir()}/pi-research-debug-{hash}.log` — one file per session, never written to stdout. Each log line includes a session correlation ID so multiple concurrent sessions are distinguishable. The log path is printed to stderr on startup when verbose mode is active.
+
+---
+
+## Development & Release
+
+**Commands**
+- `npm run lint` / `npm run lint:fix`: Code quality
+- `npm run type-check`: TypeScript verification
+- `npm run test:unit`: Unit tests — no dependencies
+- `npm run test:integration`: Integration tests — requires Docker; uses Testcontainers to spin up a real SearXNG instance (runs locally and in CI)
+
+**Release**
+1. `npm version patch` (or minor/major)
+2. `git push origin main --tags`
+The GitHub Action will automatically publish to npm and create a release.
+
+---
+
+## Architecture
+
+See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed design information.

package/config/searxng/default-settings.yml

@@ -0,0 +1,189 @@
+# SearXNG Default Configuration for pi-search-scrape Extension
+# IMPROVED: Better timeouts, removed problematic engines, added real user agent
+
+general:
+  instance_name: "pi SearXNG"
+  debug: false
+  privacypolicy_url: false
+  contact_url: false
+  enable_metrics: true  # ENABLED for debugging engine issues
+  open_metrics: ''
+
+brand:
+  new_issue_url: https://github.com/searxng/searxng/issues/new
+  docs_url: https://docs.searxng.org/
+  public_instances: https://searx.space
+  wiki_url: https://github.com/searxng/searxng/wiki
+  issue_url: https://github.com/searxng/searxng/issues
+
+server:
+  port: 8080
+  bind_address: "0.0.0.0"
+  secret_key: ""
+  base_url: false
+  limiter: false
+  public_instance: false
+  image_proxy: false
+  http_protocol_version: "1.1"
+  method: "GET"
+  default_http_headers:
+    # REAL BROWSER USER AGENT - prevents bot detection
+    User-Agent: "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36"
+    Accept: "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,*/*;q=0.8"
+    Accept-Language: "en-US,en;q=0.9"
+    Accept-Encoding: "gzip, deflate, br"
+    X-Content-Type-Options: nosniff
+    X-Download-Options: noopen
+    X-Robots-Tag: noindex, nofollow
+    Referrer-Policy: no-referrer
+
+search:
+  safe_search: 1
+  autocomplete: ""
+  autocomplete_min: 4
+  favicon_resolver: ""
+  default_lang: "en-US"
+  ban_time_on_fail: 5
+  max_ban_time_on_fail: 120
+  formats:
+    - html
+    - json
+    - csv
+    - rss
+  suspended_times:
+    # Long backoff prevents hammering blocked engines — re-check after 24h
+    SearxEngineAccessDenied: 86400
+    SearxEngineCaptcha: 86400
+    SearxEngineTooManyRequests: 3600
+    cf_SearxEngineCaptcha: 1296000
+    cf_SearxEngineAccessDenied: 86400
+    recaptcha_SearxEngineCaptcha: 604800
+
+ui:
+  static_path: ""
+  templates_path: ""
+  query_in_title: false
+  default_theme: simple
+  center_alignment: false
+  default_locale: ""
+  results_on_new_tab: false
+  theme_args:
+    simple_style: auto
+  search_on_category_select: true
+  hotkeys: default
+  url_formatting: pretty
+
+outgoing:
+  request_timeout: 20.0        # INCREASED from 10.0
+  max_request_timeout: 60.0      # INCREASED from 30.0
+  useragent_suffix: ""
+  pool_connections: 200            # INCREASED from 150
+  pool_maxsize: 30                # INCREASED from 20
+  enable_http2: true              # ENABLED (was false)
+  retries: 3                      # INCREASED from 2
+  using_tor_proxy: false
+  extra_proxy_timeout: 15
+
+doi_resolvers:
+  oadoi.org: 'https://oadoi.org/'
+  doi.org: 'https://doi.org/'
+default_doi_resolver: 'oadoi.org'
+
+# Search engines configuration
+#
+# Engine reliability for a private low-volume self-hosted instance (2026):
+#   Bing       — most consistently available; scrapes bing.com directly; weak on ambiguous queries
+#   Brave      — independent index; moderate bot detection; occasional suspension at burst rates
+#   Yahoo      — different backend from Bing; low blocking rate; lower result quality
+#   Qwant      — EU-based independent index; low-volume private use is generally fine
+#   DuckDuckGo — ddg-lite endpoint (no vqd); intermittent IP blocks (issue #4824, open)
+#   StartPage  — DISABLED: broken in current SearXNG due to missing sgt param (issue #4549, open)
+#   Google     — DISABLED: IP-blocks any nontrivial automated use
+#
+# If BRAVE_SEARCH_API_KEY is set, searxng-lifecycle.ts injects a braveapi engine at weight 1.2
+# which uses the official REST API and is not subject to bot detection.
+
+engines:
+  # Bing: most reliable free general-web engine for private instances at low volume
+  - name: bing
+    engine: bing
+    shortcut: bi
+    weight: 1.5
+
+  # Brave (scraping): independent index, different coverage from Bing
+  # Can enter suspension after bursts; max_page 10 respected by SearXNG
+  - name: brave
+    engine: brave
+    shortcut: bv
+    weight: 0.8
+
+  # Yahoo: distinct backend, low blocking rate, fills gaps when others are suspended
+  - name: yahoo
+    engine: yahoo
+    shortcut: yh
+    weight: 0.8
+
+  # Qwant: EU-based independent index, low-volume private use stable
+  - name: qwant
+    engine: qwant
+    shortcut: qw
+    weight: 0.7
+
+  # DuckDuckGo: ddg-lite endpoint (no vqd); intermittent IP blocks (issue #4824 open)
+  - name: duckduckgo
+    engine: duckduckgo
+    shortcut: ddg
+    weight: 0.6
+
+  # DISABLED: startpage — sgt parameter missing in SearXNG parser (issue #4549, open)
+  # DISABLED: google — IP-blocks automated access within minutes
+
+  # Wikipedia: Encyclopedic reference
+  # - Reliability: HIGH (uses REST API)
+  # - Note: Keep weight low to prioritize search engines
+  - name: wikipedia
+    engine: wikipedia
+    shortcut: wp
+    categories: [general]
+    weight: 0.3  # LOWER - reference only, not primary search
+
+  # Images (only when category=images is requested)
+  - name: bing images
+    engine: bing_images
+    categories: [images]
+    shortcut: bii
+
+  # News (only when category=news is requested)
+  - name: bing news
+    engine: bing_news
+    categories: [news]
+    shortcut: bin
+
+  # REMOVED: brave_news (engine not available in SearXNG container)
+
+  # Videos (only when category=videos is requested)
+  - name: bing videos
+    engine: bing_videos
+    categories: [videos]
+    shortcut: biv
+
+  # Technical/IT (only when category=it is requested)
+  # REMOVED: stackoverflow (engine not available in SearXNG container)
+  - name: github
+    engine: github
+    categories: [it]
+    shortcut: gh
+    weight: 1.0
+
+  # Science/Academic (only when category=science is requested)
+  - name: arxiv
+    engine: arxiv
+    categories: [science]
+    weight: 1.5  # INCREASED
+    shortcut: arx
+
+  - name: semantic scholar
+    engine: semantic_scholar
+    categories: [science]
+    weight: 1.5  # INCREASED
+    shortcut: sem

package/config/searxng/limiter.toml

@@ -0,0 +1,34 @@
+# SearXNG Limiter Configuration for pi-search-scrape
+# This configuration disables all bot detection and rate limiting for local use
+
+[botdetection]
+# The prefix defines number of leading bits in an address that are compared
+# to determine whether or not an address is part of a (client) network.
+ipv4_prefix = 32
+ipv6_prefix = 48
+
+# Trust localhost requests completely (no bot detection for local connections)
+trusted_proxies = [
+  '127.0.0.0/8',
+  '::1',
+]
+
+[botdetection.ip_limit]
+# Disable rate limiting for link-local addresses (localhost)
+filter_link_local = false
+# Disable link token method (no captcha required)
+link_token = false
+
+[botdetection.ip_lists]
+# No IP blocking for local use
+block_ip = []
+
+# Allow all localhost requests without restrictions
+pass_ip = [
+  '127.0.0.0/8',      # IPv4 localhost
+  'fe80::/10',         # IPv6 link-local
+  '0.0.0.0/0',        # Allow all IPv4 (for local container use)
+]
+
+# Allow SearXNG org IPs for checks
+pass_searxng_org = true

package/config/tooling/eslint.config.js

@@ -0,0 +1,73 @@
+import js from '@eslint/js';
+import tseslint from '@typescript-eslint/eslint-plugin';
+import tsparser from '@typescript-eslint/parser';
+
+export default [
+  // Global ignores
+  {
+    ignores: [
+      'node_modules/**',
+      'dist/**',
+      '*.d.ts',
+      'examples/**',
+    ],
+  },
+  // JavaScript recommended rules
+  js.configs.recommended,
+  // TypeScript recommended rules
+  {
+    files: ['**/*.ts'],
+    languageOptions: {
+      parser: tsparser,
+      parserOptions: {
+        ecmaVersion: 2022,
+        sourceType: 'module',
+        project: './tsconfig.json',
+      },
+      globals: {
+        process: 'readonly',
+        console: 'readonly',
+        Buffer: 'readonly',
+        __dirname: 'readonly',
+        __filename: 'readonly',
+        require: 'readonly',
+        module: 'readonly',
+        exports: 'readonly',
+        NodeJS: 'readonly',
+        setTimeout: 'readonly',
+        setInterval: 'readonly',
+        clearTimeout: 'readonly',
+        clearInterval: 'readonly',
+        crypto: 'readonly',
+        AbortSignal: 'readonly',
+        AbortController: 'readonly',
+        Request: 'readonly',
+        RequestInit: 'readonly',
+        Response: 'readonly',
+        FormData: 'readonly',
+        fetch: 'readonly',
+        URL: 'readonly',
+        URLSearchParams: 'readonly',
+        ArrayBuffer: 'readonly',
+        ReadableStream: 'readonly',
+        Blob: 'readonly',
+      },
+    },
+    plugins: {
+      '@typescript-eslint': tseslint,
+    },
+    rules: {
+      // Override specific rules
+      'no-console': 'off', // Allow console.log for debugging
+      'no-unused-vars': 'off', // Disable in favor of TypeScript version
+      '@typescript-eslint/no-unused-vars': [
+        'error',
+        {
+          argsIgnorePattern: '^_',
+          varsIgnorePattern: '^_',
+          caughtErrorsIgnorePattern: '^_',
+        },
+      ],
+    },
+  },
+];

package/config/tooling/vitest.config.integration.ts

@@ -0,0 +1,17 @@
+import { defineConfig } from 'vitest/config';
+import baseConfig from './vitest.config';
+
+export default defineConfig({
+  ...baseConfig,
+  test: {
+    ...baseConfig.test,
+    // Integration tests using testcontainers
+    include: ['test/integration/**/*.test.ts'],
+    setupFiles: [],
+    testTimeout: 180000, // 180 second timeout for integration tests
+    maxConcurrency: 1, // Only one integration test at a time due to containers
+    fileParallelism: false,
+    pool: 'forks',
+    hookTimeout: 60000,
+  },
+});

package/config/tooling/vitest.config.ts

@@ -0,0 +1,40 @@
+import { defineConfig } from 'vitest/config';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+export default defineConfig({
+  test: {
+    globals: true,
+    environment: 'node',
+    include: ['**/*.test.ts', '**/*.spec.ts'],
+    exclude: ['node_modules', 'dist', '.tmp'],
+    coverage: {
+      provider: 'v8',
+      reporter: ['text', 'json', 'html', 'lcov'],
+      exclude: [
+        'node_modules/',
+        'dist/',
+        '**/*.test.ts',
+        '**/*.spec.ts',
+        '**/types.ts',
+        '**/index.ts',
+        'test/',
+      ],
+      reportOnFailure: true,
+    },
+    testTimeout: 60000,
+    hookTimeout: 30000,
+    teardownTimeout: 10000,
+    pool: 'threads',
+    includeSource: ['src/**/*.ts'],
+    setupFiles: ['./test/setup/unit.ts'],
+  },
+  resolve: {
+    alias: {
+      '@': path.resolve(__dirname, './src'),
+      '@test': path.resolve(__dirname, './test'),
+    },
+  },
+});

package/config/tooling/vitest.config.unit.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'vitest/config';
+import baseConfig from './vitest.config';
+
+export default defineConfig({
+  ...baseConfig,
+  test: {
+    ...baseConfig.test,
+    include: ['test/unit/**/*.test.ts'],
+    setupFiles: ['./test/setup/unit.ts'],
+    testTimeout: 10000,
+  },
+});

package/docs/ARCHITECTURE.md

@@ -0,0 +1,109 @@
+# Architecture
+
+## Orchestration Modes
+
+Two primary modes: **Quick Mode** and **Deep Mode**.
+
+### Quick Mode
+Routes research tasks to a single **Agent Researcher** session. No coordination or evaluation overhead — suitable for focused queries.
+
+### Deep Mode
+Uses a state machine to manage a three-status research lifecycle:
+
+1.  **Planning Status**: The AI coordinator analyzes the conversation context and generates a JSON-formatted research agenda—a list of high-level research tasks.
+2.  **Researching Status**: 
+    - **Parallel Execution**: **Agent Researchers** run in parallel (up to 3 concurrent). Each researcher handles one agenda task per round.
+    - **Report Injection**: Collective knowledge is managed by the orchestrator. When a researcher completes its task, its full report (up to 50k chars) is **injected** into the context of siblings starting later, or **steered** into already running ones. This ensures researchers don't just know *what* was scraped, but also *what was found*.
+    - **Lead Evaluation**: When a round is complete, a **Lead Evaluator** agent call is triggered. It reviews all accumulated findings against the original agenda.
+    - **Decision Outcome**: The evaluator makes a binary choice:
+        - **Synthesize**: Generate a final, exhaustive Markdown report (transition to **Completed**).
+        - **Delegate**: Formulate new, targeted queries for a subsequent round (remain in **Researching**).
+3.  **Completed Status**: The final synthesis is returned as the tool result.
+
+State transitions are managed by a pure reducer (`src/orchestration/deep-research-reducer.ts`), ensuring predictable behavior.
+
+---
+
+## The Agent Researcher
+
+An **Agent Researcher** is the fundamental building block of `pi-research`. Regardless of the orchestration mode, every researcher follows a structured three-phase internal lifecycle:
+
+### Phase 1: Gathering
+The researcher uses broad tools to discover relevant information and identify high-quality URLs for further investigation.
+- **Budget**: 4 Gathering calls (shared across `search`, `security_search`, `stackexchange`, and `grep`).
+- **Goal**: Breadth-first exploration and URL discovery.
+
+### Phase 2: Scraping
+The researcher deep-dives into the URLs identified during the Gathering phase to extract detailed content.
+- **Budget**: 4 Scrape calls (1 handshake + 3 execution batches).
+- **Goal**: Depth-first extraction of specific data and evidence.
+- **Deduplication**: Researchers check a shared URL pool to avoid re-scraping links already handled by siblings in the same operation.
+
+### Phase 3: Reporting
+The researcher synthesizes its individual findings into a structured Markdown report.
+- **Structure**: Includes an executive summary, key findings, and a list of cited links.
+- **Signaling**: Once finished, the report is submitted to the orchestrator for injection into siblings (Deep Mode) or final return (Quick Mode).
+
+---
+
+## Component Details
+
+### Research Tools & Limits
+Each researcher session is constrained by a `ToolUsageTracker` to prevent infinite loops and manage token consumption:
+- **search**: Interfaces with the local SearXNG instance. Supports multiple queries per call.
+- **scrape**: Multi-batch protocol for page extraction.
+- **security_search**: Queries NVD, CISA KEV, GitHub Advisories, and OSV.
+- **stackexchange**: Queries the Stack Exchange network (Stack Overflow, etc.).
+- **grep**: Local codebase search using `ripgrep` (fallback to `grep`).
+
+### Context-Aware Scraping Protocol
+To avoid exceeding LLM context windows, the `scrape` tool follows a four-step handshake. **Each batch step is gated by a 55% context check** — if the session token count already exceeds 55% of the model's context window, that batch is skipped entirely and the tool returns early.
+
+1. **Handshake**: The researcher identifies target URLs. The tool returns a list of URLs already scraped by siblings. No network activity; no context check.
+2. **Batch 1**: Up to 3 URLs — primary broad scraping.
+3. **Batch 2**: Up to 2 URLs — targeted follow-up, deduplicated against Batch 1.
+4. **Batch 3**: Up to 3 URLs — deep-dive scraping.
+
+### Shared Link Deduplication
+Researchers share a URL pool per research operation, used by the `scrape` handshake to avoid redundant network requests. The pool tracks URLs only — findings are shared separately via Report Injection. It resets for each new query.
+
+### SearXNG Lifecycle Management
+SearXNG runs as a Docker container (`searxng/searxng`, tag controlled by `SEARXNG_IMAGE_TAG`, default `latest`).
+- **Lazy Initialization**: The container starts only upon the first research request.
+- **Singleton Pattern**: A single container is shared across all pi processes on the machine. State is persisted to `~/.pi/state/searxng-singleton.json`; each pi process registers a session by PID and the container stays alive until all registered processes have exited.
+- **Configuration**: Runtime settings (proxies, API keys) are generated dynamically and volume-mounted into the container.
+- **Engine configuration**: Active search engines are defined in `config/searxng/default-settings.yml`. Engines can be enabled or disabled by editing that file before starting the container.
+- **Cross-Session Persistence**: Container state and locking are managed via `~/.pi/state/searxng-singleton.json` to handle multiple concurrent pi processes.
+
+### Output File Location
+
+When research completes, the report is written to a `.md` file named `pi-research-{sanitized-query}-{hash}.md` (e.g. `pi-research-rust-async-runtimes-a3.md`). The destination directory is resolved from the pi session's working directory (`cwd`) using a three-tier priority:
+
+1. **cwd is home or a system directory** → `os.tmpdir()`. Prevents cluttering `~`, drive roots, or system paths like `/usr`.
+2. **cwd contains a recognised subdirectory** → that subdirectory. Probed in priority order: `research`, `docs`, `doc`, `ref`, `references`, `notes`. Matching is case-insensitive so it works on macOS APFS and Windows NTFS.
+3. **Otherwise** → cwd itself.
+
+The two-character hash suffix (`{letter}{digit}`, e.g. `b7`) is a collision guard — the file is opened with an exclusive-create flag and the hash is regenerated on `EEXIST`. The full saved path is appended as a footer in the report and returned to the pi UI.
+
+### TUI Progress Percentage
+
+The header percentage (`Research: 70%`) tracks tool-call units completed against a budget established after planning. The budget is set from the number of agenda items the coordinator produces — which scales with query complexity (complexity 1 → 2 initial researchers, 2 → 3, 3 → 5), each researcher allocated 10 units. The budget expands dynamically when the evaluator delegates additional rounds. If research goes beyond the planned rounds the display switches to `exploring` instead of a percentage.
+
+### Evaluator Decision Framework
+The Lead Evaluator follows a strict priority list:
+1.  **Error Check**: If all researchers in a round failed, it reports a critical failure and stops.
+2.  **Coverage Check**: It compares cumulative findings against the initial agenda items.
+3.  **Round Budget**: It checks the round budget (`targetRounds + MAX_EXTRA_ROUNDS`). The hard limit is `targetRounds + 2` bonus rounds.
+4.  **Action Selection**: Produces either a Markdown synthesis (final result) or a JSON delegation object (`{"action": "delegate", "queries": [...]}`). Any non-JSON response is treated as a final synthesis to prevent the research from getting stuck.
+
+---
+
+## Project Structure
+
+- `src/orchestration/`: Core state machine, coordinator, and evaluator logic.
+- `src/infrastructure/`: Docker container management and SearXNG lifecycle.
+- `src/tools/`: Implementations for search, scraping, and specialized database queries.
+- `src/tui/`: Real-time terminal UI components using `pi`'s display capabilities.
+- `src/utils/`: Shared utilities for token tracking, JSON extraction, and link deduplication.
+- `src/prompts/`: Markdown-based system instructions for the Coordinator, Researcher, and Evaluator.
+- `config/`: Default SearXNG engine and rate-limiter configurations.