ultimate-pi 0.19.0 → 0.19.1

package/.agents/skills/web-retrieval/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: web-retrieval
+description: |
+  Agentic Web Retrieval Stack (WRS) — tiered web_search/web_fetch/web_contents (harness-web.py +
+  Scrapling). Default tier=deep with web-query-expander angles. Use for search, scrape, landscape,
+  prior art, comparisons, planning pre-research, cited answers, similar URLs, websets scoring.
+  Triggers on non-API web research, scrape URL, web_search, web_fetch, .web/ artifacts.
+  Library API docs → context7 only. Install: /harness-setup or harness-cli-verify.
+allowed-tools: Read Write web_search web_fetch web_find_similar web_contents
+---
+
+# web-retrieval (WRS)
+
+Maps user intent → **tier** + pipeline. Pi tools: `web_search`, `web_fetch`, `web_find_similar`, `web_contents` (wrap `harness-web.py`). **Pooled cache** under `.web/cache/`; workspace aliases under `.web/`.
+
+**Never before search/fetch:** `UP_PKG` resolution, `ls harness-web.py`, `python3 -c "import scrapling"`, Firecrawl, curl/wget, or scrapling CLI for SERP/fetch.
+
+## Workspace + cache (default)
+
+| Layer | Path | Role |
+|-------|------|------|
+| **Cache** | `.web/cache/<kind>/<cacheKey>/` | Pooled SERP + fetch payloads with `meta.json` (query, tier, angles fingerprint, TTL) |
+| **Workspace** | `.web/` (`angles.yaml`, `search-deep.json`, `page.md`, …) | Stable paths agents read/write; refreshed from cache on hit |
+
+`web_search` / `web_fetch` return **`cacheHit`**, **`cacheKey`**, **`cachePath`** when reusing pooled results. Same intent + angles skips network until TTL expires.
+
+| Control | Meaning |
+|---------|---------|
+| `HARNESS_WEB_CACHE_TTL_SEC` | Default freshness (86400 = 24h) |
+| `HARNESS_WEB_CACHE=0` | Disable pooling |
+| `refreshCache: true` on tool | Force network |
+| `cacheMaxAge` on tool | Stricter max age (seconds) |
+
+**Optional isolation** (parallel mutable synthesis): `HARNESS_WEB_ISOLATE=1` → `.web/runs/<run_id>/` or `.web/sessions/<pi_session_id>/` for `answer.md` / evidence when sessions must not share workspace files.
+
+`web_search` responses include **`artifactDir`** (usually `.web`). Spawn web-retrieval subagents with `HARNESS_WEB_ARTIFACT_DIR` or `artifactDir` in the task.
+
+## Tier table
+
+| User intent | Tier | Steps |
+|-------------|------|-------|
+| One narrow fact (scoped) | `instant` or `standard` | `web_search({ query, tier })` — **no subagent** |
+| Fast open-web with angles | `standard` or `deep` + heuristic | `web-query-expander-fast` **or** `expandHeuristic:true` |
+| "What is X?" needs sources | `deep` | `web-query-expander` → deep → highlights |
+| Landscape / how / compare | `deep` | `web-query-expander` → deep → `web_fetch` highlights top 3 |
+| Answer with citations | `research` | deep → `web_contents` → `web-answerer` |
+| Qualified list (Websets analog) | `research` + verifier | deep → `web-criteria-verifier` → CSV |
+| More like this URL | — | `web_find_similar` |
+| Library API docs | — | **context7** (not WRS) |
+
+## Latency vs quality routing
+
+| Priority | Search / subagent | Model / thinking |
+|----------|-------------------|------------------|
+| **Latency** | No expander: `tier=instant` or `standard` only | Parent session (pick a fast model in UI) |
+| **Latency + angles** | `harness/web-retrieval/web-query-expander-fast` → `tier=deep` | `HARNESS_WEB_FAST_MODEL` (optional) |
+| **Emergency angles (no LLM)** | `web_search({ tier: "deep", expandHeuristic: true, category? })` | Templates from `.pi/harness/web-heuristic-angles.yaml` (project file merges on top) |
+| **Default research** | `harness/web-retrieval/web-query-expander` → `tier=deep` | `HARNESS_WEB_EXPANDER_MODEL` or parent |
+| **Gap fill** | `harness/web-retrieval/web-gap-analyzer` | `HARNESS_WEB_FAST_MODEL` or parent |
+| **Cited answer** | `harness/web-retrieval/web-answerer` | `HARNESS_WEB_QUALITY_MODEL` or parent |
+| **Page digest** | `harness/web-retrieval/web-summarizer` | `HARNESS_WEB_FAST_MODEL` or parent |
+| **Criteria scoring** | `harness/web-retrieval/web-criteria-verifier` | `HARNESS_WEB_QUALITY_MODEL` or parent |
+
+## Configuring models (env vars)
+
+WRS subagents need a **concrete** `provider/model-id` (same format as Pi — any provider your install supports). Set in shell, `.env`, or harness-synced project env:
+
+| Variable | Applies to |
+|----------|------------|
+| `HARNESS_WEB_FAST_MODEL` | `web-query-expander-fast`, `web-summarizer`, `web-gap-analyzer` |
+| `HARNESS_WEB_EXPANDER_MODEL` | `web-query-expander` |
+| `HARNESS_WEB_QUALITY_MODEL` | `web-answerer`, `web-criteria-verifier` |
+
+Example (use **your** provider/model ids):
+
+```bash
+export HARNESS_WEB_FAST_MODEL=your-provider/cheap-model
+export HARNESS_WEB_EXPANDER_MODEL=your-provider/balanced-model
+export HARNESS_WEB_QUALITY_MODEL=your-provider/strong-model
+```
+
+If unset for an agent, the subagent inherits the **parent session model** (pick a fast model in Pi when latency matters).
+
+Optional per-agent override: `model:` in agent `.md` frontmatter or project `.pi/agents.policy.yaml` (before parent fallback).
+
+## Deep pipeline (default for research)
+
+1. `subagent` **`harness/web-retrieval/web-query-expander`** → parent saves `.web/angles.yaml`
+2. `web_search({ query: "<intent>", tier: "deep", anglesFile: ".web/angles.yaml" })` — repeats hit cache when context unchanged
+3. `read` `.web/search-deep.json` — prefer URLs with multiple `angle_ids`
+5. `web_fetch({ url, highlights: true, highlightQuery: "<intent>" })` on top 3–5
+6. Optional gap pass: `harness/web-retrieval/web-gap-analyzer` → new angles → second `web_search` deep
+
+**Anti-patterns:** bare `web_search({ query })` for open questions; 3+ manual SERP loops; `bulk: true` without need.
+
+## Research profile (`tier=research`)
+
+After deep + highlight fetches:
+
+```bash
+python3 "$UP_PKG/.pi/scripts/harness-web.py" contents-batch \
+  --from-search "$ARTIFACT_DIR/search-deep.json" \
+  --evidence-bundle "$ARTIFACT_DIR/evidence-bundle.json" --limit 5
+```
+
+Spawn **`harness/web-retrieval/web-answerer`** with `artifactDir` / `answerPath: $ARTIFACT_DIR/answer.md`.
+
+## Websets profile
+
+Spawn **`harness/web-retrieval/web-criteria-verifier`** with NL criteria + `search-deep.json` candidates → `.web/webset-reasoning.yaml` / CSV manifest.
+
+## Bash fallback (no pi tools)
+
+```bash
+python3 "$UP_PKG/.pi/scripts/harness-web.py" search-deep "query" \
+  --expand-heuristic -o .web/search-deep.json --limit 10
+```
+
+## Subagents
+
+| Agent | Role |
+|-------|------|
+| `harness/web-retrieval/web-query-expander` | Angles YAML (research / recall) |
+| `harness/web-retrieval/web-query-expander-fast` | 2–3 angles (latency) |
+| `harness/web-retrieval/web-gap-analyzer` | Follow-up angles |
+| `harness/web-retrieval/web-answerer` | Cited answer |
+| `harness/web-retrieval/web-summarizer` | Single-page digest |
+| `harness/web-retrieval/web-criteria-verifier` | Criteria scoring |
+
+## Heuristic angle templates (no LLM expander)
+
+Package defaults: `.pi/harness/web-heuristic-angles.yaml` (`max_angles: 8`). Categories include targeted `site:` angles — e.g. **code**: GitHub, Stack Overflow, Stack Exchange, Read the Docs, MDN, npm/PyPI/Go/Rust registries, Microsoft Learn, HN; **paper**: arXiv, Semantic Scholar, Papers with Code, OpenReview; **security**: NVD, OWASP, CWE; plus **news**, **company**, **people**, **default**.
+
+`web_search({ tier: "deep", expandHeuristic: true, category: "code" })`
+
+**External projects:** copy `.pi/harness/examples/web-heuristic-angles.project.yaml` → `<project>/.pi/harness/web-heuristic-angles.yaml` and add or override angle ids. Use `{query}` in templates.
+
+## Install (setup / humans only)
+
+```bash
+command -v uv &>/dev/null || curl -LsSf https://astral.sh/uv/install.sh | sh
+uv tool install "scrapling[fetchers]"
+scrapling install   # browser binaries for stealth scrape
+bash "$UP_PKG/.pi/scripts/harness-cli-verify.sh"
+```
+
+Diagnostics: `python3 "$UP_PKG/.pi/scripts/harness-web.py" status` (JSON).
+
+## Env
+
+| Variable | Default | Purpose |
+|----------|---------|---------|
+| `HARNESS_WEB_FETCH_MODE` | `stealth` | `stealth` \| `fast` \| `auto` |
+| `HARNESS_WEB_SEARCH_ENGINE` | `ddg_html` | `ddg_html` \| `searxng` (+ `HARNESS_WEB_SEARXNG_URL`) |
+| `HARNESS_WEB_CACHE_TTL_SEC` | `86400` | Pooled cache TTL |
+| `HARNESS_WEB_CACHE` | on | Set `0` to disable cache |
+| `HARNESS_WEB_ISOLATE` | off | Set `1` for per-run/session workspace dirs |
+| `HARNESS_WEB_RERANK` | — | `off` \| `lexical` |
+| `HARNESS_WEB_DEEP_CONCURRENCY` | `4` | Parallel angle SERP |
+| `HARNESS_WEB_HEURISTIC_ANGLES_FILE` | — | Extra heuristic angles YAML |
+| `HARNESS_WEB_FAST_MODEL` / `EXPANDER` / `QUALITY` | — | Web subagent models |
+
+See `.pi/harness/docs/harness-web-search.md` for internals.

package/.agents/skills/wiki-autoresearch/SKILL.md

@@ -127,16 +127,16 @@ When the user invokes the trigger with NO topic after it, ask:
 ```
 Input: topic (from Topic Selection, above)
 
-Round 1. Broad search
-1. Decompose topic into 3-5 distinct search angles
-2. For each angle: run 2-3 `web_search` queries
-3. For top 2-3 results per angle: `web_fetch` each URL (or `read` `.web/` artifacts)
+Round 1. Broad search (WRS deep — do not loop manual SERP)
+1. Invoke **web-retrieval** skill: `harness/web-retrieval/web-query-expander` → `.web/angles.yaml`
+2. One `web_search({ query: topic, tier: "deep", anglesFile: ".web/angles.yaml" })` → `.web/search-deep.json`
+3. For top 2-3 fused URLs: `web_fetch` with `highlights: true` (or `read` `.web/` artifacts)
 4. Save each fetched page to ./raw/ as a markdown file
 5. Extract from each: key claims, entities, concepts, open questions
 
 Round 2. Gap fill
-6. Identify what's missing or contradicted from Round 1
-7. Run targeted searches for each gap (max 5 queries)
+6. Identify what's missing or contradicted from Round 1 (`read` `search-deep.json`)
+7. Optional: `harness/web-retrieval/web-gap-analyzer` → second `web_search` deep with new angles (max one extra deep pass)
 8. Fetch top results for each gap, save to ./raw/
 9. Run `graphify extract ./raw --out .` to incorporate new sources
    (NOTE: `graphify update` only works for code files. Research sources are docs

package/.pi/SYSTEM.md

@@ -30,27 +30,45 @@ Scope: this file is the reusable harness-level instruction set. It must work whe
 ## Web Policy (Mandatory)
 
 > [!warning] No raw HTTP
-> Route **all** web through [[context7]] for API/library docs or **`web_search` / `web_fetch`** via [[scrapling-web]] for non-API web. Do not use `curl`, `wget`, Firecrawl, or scrapling CLI preflight.
+> Route **all** web through [[context7]] for API/library docs or the **Agentic Web Retrieval Stack (WRS)** — `web_search` / `web_fetch` / `web_find_similar` / `web_contents` via [[web-retrieval]]. Do not use `curl`, `wget`, Firecrawl, or scrapling CLI preflight.
 
 ### API / Library Docs — context7 ONLY
 - `ctx7 library <name> <query>` then `ctx7 docs <id> <query>`.
 - context7 owns function signatures, class APIs, config options, stdlib, and framework specs.
 - Never use quality-sites or web_fetch for API docs.
 
-### Non-API Web — web_search + web_fetch
-Use the harness web-search/fetch tools and the `scrapling-web` skill when available. No preflight: never probe package paths, list harness scripts, or import Scrapling before searching.
+### Non-API Web — WRS (tiered)
+Invoke the **`web-retrieval`** skill before non-trivial open-web work (landscape, prior art, comparisons, planning research). WRS uses a **pooled cache** (`.web/cache/`, TTL via `HARNESS_WEB_CACHE_TTL_SEC`) and **workspace aliases** under `.web/` (`angles.yaml`, `search-deep.json`, `answer.md`). Set `HARNESS_WEB_ISOLATE=1` only when per-run/session file isolation is required.
+
+| Tier | When | Pattern |
+|------|------|---------|
+| **`deep`** | **Default** for landscape, prior art, how/why, comparisons, stack/implementation research, multi-source questions | 1) `subagent` `harness/web-retrieval/web-query-expander` → `.web/angles.yaml` 2) `web_search({ query, tier: "deep", anglesFile: ".web/angles.yaml" })` (cache reuse when fresh) 3) `web_fetch` top URLs with `highlights: true` |
+| `standard` | One narrow fact; follow-up after `search-deep.json`; verify one claim | `web_search({ query, tier: "standard", limit: 5 })` |
+| `instant` | Closed-form fact, latency-critical | `web_search({ query, tier: "instant", limit: 5 })` |
+| `research` | Cited answer/report; harness-plan external research | `web-retrieval` `research` profile → deep → contents → `web-answerer` |
 
 | Task | Tool |
 |------|------|
-| Search (SERP) | `web_search` (`query`, optional `limit`, `bulk`) |
-| Scrape page | `web_fetch` (`url`, optional `fast: true`) |
-| Map links | `web_fetch` (`url`, `mode: map`) |
-
-- Artifacts default under the active project's `.web/`; use `read` for full JSON/markdown artifacts.
-- If tools are unavailable, use the installed harness web fallback documented by the `scrapling-web` skill.
-- Run setup diagnostics only when troubleshooting web tooling.
-- Check local quality-site guidance when present before citing non-API sources. Prefer Tier 1 sources; exclude AI content farms, mirrors, and stale packages.
-- For deep research, use `/wiki-autoresearch <topic>` when available and store outputs in the active project's configured research/wiki/graph locations.
+| Multi-angle SERP | `web_search` with `tier: "deep"` + `anglesFile` |
+| Narrow SERP | `web_search` with `tier: "standard"` or `"instant"` |
+| Scrape / highlights | `web_fetch` (`highlights: true` after deep search) |
+| Batch excerpts | `web_contents` |
+| Similar pages | `web_find_similar` |
+| Map links | `web_fetch` (`mode: map`) |
+
+**Anti-patterns**
+- Open-ended question with omitted `tier` (weak single-query SERP).
+- Three+ sequential `web_search` calls with different queries — use one `deep` search.
+- `bulk: true` unless you need markdown bodies of top N immediately.
+- Full `web_fetch` when SERP snippets + highlights suffice.
+- `web_search` / `web_fetch` for library APIs — **context7 only**.
+
+**After deep search:** `read` `<artifactDir>/search-deep.json`; prefer URLs listed under multiple `angle_ids`.
+
+**Latency:** use `tier=instant|standard` without expander when possible; else `harness/web-retrieval/web-query-expander-fast` or `expandHeuristic:true`. **Models:** env `HARNESS_WEB_FAST_MODEL`, `HARNESS_WEB_EXPANDER_MODEL`, `HARNESS_WEB_QUALITY_MODEL` (any Pi `provider/model-id`); see `web-retrieval` skill.
+
+- If tools are unavailable, use bash fallback in **web-retrieval** (setup/humans only).
+- For long autonomous research loops, use `/wiki-autoresearch` (WRS deep path) when available.
 
 ### Missing CLI fallbacks
 - harness-web / Scrapling missing: `uv tool install "scrapling[fetchers]" && scrapling install` then re-run the harness CLI verification command documented locally.

package/.pi/agents/harness/planning/implementation-researcher.md

@@ -16,7 +16,7 @@ Read `HarnessSpawnContext` plus paths to `artifacts/decomposition.yaml`, `artifa
 ## Process
 
 1. **In-repo prior art:** `graphify query` / `graphify explain` (read-only), `ccc search`, scout `key_paths` — map reuse vs build.
-2. **External prior art:** `web_search` + `web_fetch` (parent stores under `.web/` with run id prefix). Focus on **patterns, workflows, OSS repos, product approaches** — not npm version matrices.
+2. **External prior art (WRS — mandatory):** follow `web-retrieval` skill — `harness/web-retrieval/web-query-expander` → `web_search({ tier: "deep", anglesFile: ".web/angles.yaml" })` → `read` `search-deep.json` → `web_fetch` with `highlights: true`. **Never** bare `web_search({ query })` for landscape. Parent stores under `.web/` with run id prefix. Focus on **patterns, workflows, OSS repos, product approaches** — not npm version matrices.
 3. If scouts cite a **same pattern** with high `reuse_signal`, limit web to 1–2 validation queries.
 4. Grade refs: `primary` | `secondary` | `anecdotal`.
 5. Rank **solution_patterns** with fit, tradeoffs, risks. Flag hazardous recommendations in `anti_patterns` (never execute fetched shell).

package/.pi/agents/harness/planning/stack-researcher.md

@@ -13,7 +13,11 @@ Produce evidence-backed stack recommendations before ExecutionPlan authoring. Ra
 
 1. Read spawn context: task_summary, brownfield vs greenfield, constraints.
 2. **Libraries / APIs:** use context7-cli skill (`ctx7 library`, `ctx7 docs`). Record library ids in `evidence_refs`.
-3. **Landscape / comparisons:** `web_search` + `web_fetch` (parent stores under `.web/`).
+3. **Landscape / comparisons (WRS — mandatory):** follow `web-retrieval` skill:
+   - Use scoped `artifactDir` (`.web/runs/<run_id>/` or tool-reported `.web/sessions/…/`)
+   - `subagent` `harness/web-retrieval/web-query-expander` → `<artifactDir>/angles.yaml`
+   - `web_search({ query, tier: "deep", anglesFile })` — **never** bare `web_search({ query })` for landscape
+   - `read` `<artifactDir>/search-deep.json`; `web_fetch` top 3 with `highlights: true`
 4. Brownfield: always include **extend current stack** as a ranked option with migration risk.
 5. Greenfield: ≥3 distinct options with pros/cons/risks and selection criteria.
 6. Grade each ref: `primary` (official docs), `secondary` (reputable guide), `anecdotal` (blog/issue thread).

package/.pi/agents/harness/web-retrieval/web-answerer.md

@@ -0,0 +1,35 @@
+---
+description: WRS synthesis — cited answer from evidence-bundle.json.
+extensions: false
+thinking: medium
+max_turns: 12
+---
+
+## Your task
+
+Write a concise, **cited** answer to the research question using only sources in the evidence bundle.
+
+## Output path (required — no shared flat file)
+
+Write to **`$HARNESS_WEB_ARTIFACT_DIR/answer.md`** when that env var is set (harness web-retrieval subprocesses).
+
+Otherwise use the **`answerPath`** or **`artifactDir`** the parent gives in the spawn task (e.g. `.web/sessions/<id>/answer.md` or `.web/runs/<run_id>/answer.md`).
+
+**Never** write to flat `.web/answer.md` — it collides across parallel sessions.
+
+## Input
+
+Read the evidence bundle path from the parent task (default: same directory as the answer file, file name `evidence-bundle.json`). Each source has url, title, description, optional highlights.
+
+## Output format
+
+Write markdown to the resolved answer path via parent tooling or include full content in final message:
+
+- Lead with a direct answer (2–4 sentences).
+- Supporting bullets with inline citations `[title](url)`.
+- "Sources" section listing URLs used.
+- Flag uncertainty where evidence is thin.
+
+Do **not** invent URLs. Do **not** call web_search.
+
+Bus label: `WebAnswerer`.

package/.pi/agents/harness/web-retrieval/web-criteria-verifier.md

@@ -0,0 +1,28 @@
+---
+description: WRS Websets analog — score candidates against NL criteria (YAML/CSV output).
+extensions: false
+thinking: medium
+max_turns: 14
+---
+
+## Your task
+
+Given NL **criteria** and a list of candidate URLs/titles/snippets (from search-deep.json), score each candidate and explain match quality.
+
+## Output
+
+Fenced YAML:
+
+```yaml
+criteria: "<restated criteria>"
+results:
+  - url: "..."
+    title: "..."
+    match: true|false
+    score: 0.0-1.0
+    reason: "<one sentence>"
+```
+
+Parent may convert to `.web/webset-manifest.csv`. Do **not** call web_search.
+
+Bus label: `WebCriteriaVerifier`.

package/.pi/agents/harness/web-retrieval/web-gap-analyzer.md

@@ -0,0 +1,31 @@
+---
+description: WRS gap-fill — read search-deep.json, propose follow-up angles for missing coverage.
+extensions: false
+thinking: low
+max_turns: 10
+---
+
+## Your task
+
+After a deep search, identify **gaps** (missing facets, contradictions, stale angles) and output **1–3 new search angles** only.
+
+## Input
+
+Parent provides paths to `.web/search-deep.json` and research intent. Use `read` on those artifacts.
+
+## Output (only)
+
+Fenced YAML:
+
+```yaml
+gaps:
+  - "<what is missing>"
+angles:
+  - id: gap_1
+    query: "..."
+    rationale: "..."
+```
+
+Do **not** call web tools. Parent runs `web_search(tier=deep, anglesFile=...)`.
+
+Bus label: `WebGapAnalyzer`.

package/.pi/agents/harness/web-retrieval/web-query-expander-fast.md

@@ -0,0 +1,34 @@
+---
+description: WRS fast query planner — 2–3 angles only for latency-sensitive search (YAML only).
+extensions: false
+thinking: off
+max_turns: 5
+---
+
+## Your task
+
+Same as `web-query-expander`, but **optimized for speed**: produce **2–3** angles only (not 4–5). No web tools.
+
+## When to use (parent)
+
+- User asked for **fast** / **quick** / **low latency** open-web lookup
+- `web_search` with `tier: "instant"` or `tier: "standard"` where angles still help (optional)
+- **Not** for landscape, prior art, comparisons, or harness-plan research — use `harness/web-retrieval/web-query-expander` instead
+
+## Output (only)
+
+```yaml
+intent: "<one sentence>"
+category: null
+angles:
+  - id: core
+    query: "<short query>"
+    rationale: "..."
+  - id: official
+    query: "..."
+    rationale: "..."
+```
+
+Keep queries ≤10 words. Do not call `web_search` or `web_fetch`.
+
+Bus label: `WebQueryExpanderFast`.

package/.pi/agents/harness/web-retrieval/web-query-expander.md

@@ -0,0 +1,60 @@
+---
+description: WRS query planner — NL intent to 4-5 SearXNG-optimized search angles (YAML only).
+extensions: false
+thinking: low
+max_turns: 8
+---
+
+## Your task
+
+Convert a research intent into **4–5 distinct search angles** optimized for DuckDuckGo / SearXNG keyword search. You do **not** search the web yourself.
+
+## When parent should spawn you (not `web-query-expander-fast`)
+
+- Landscape, prior art, comparisons, stack/implementation research, harness-plan external research
+- Any question where **recall** matters more than latency
+
+For **fast / narrow** paths, parent should spawn `harness/web-retrieval/web-query-expander-fast` or skip expander and use `tier=instant|standard` with `expandHeuristic:true`.
+
+## Output (only)
+
+Respond with a single fenced YAML block and nothing else:
+
+```yaml
+intent: "<restated intent in one sentence>"
+category: null  # or code|company|people|paper|news
+angles:
+  - id: official
+    query: "<short keyword-dense query>"
+    rationale: "<why this angle>"
+  - id: technical
+    query: "..."
+    rationale: "..."
+  # 4-5 angles total
+```
+
+## Angle design rules
+
+- Each `query` must be **short** (≤12 words unless `site:` operator needed).
+- Angles must be **distinct** (definitional, official docs, technical depth, criticism/limitations, recent news, implementations/repos).
+- Use operators when helpful: `site:github.com`, `site:arxiv.org`, `filetype:pdf`, quoted phrases.
+- Do **not** duplicate the same phrasing across angles.
+- Do **not** call `web_search` or `web_fetch`.
+
+## Category packs (when spawn context includes category)
+
+Subagent output is LLM-crafted. For **heuristic** fallback (`expandHeuristic:true`), category packs come from YAML:
+
+- Package: `.pi/harness/web-heuristic-angles.yaml`
+- Project override: `<project>/.pi/harness/web-heuristic-angles.yaml` (see `examples/web-heuristic-angles.project.yaml`)
+
+| category | Default heuristic angles (configurable) |
+|----------|----------------------------------------|
+| code | github, stackoverflow, … |
+| company | official site, news, … |
+| people | linkedin, biography |
+| paper | arxiv, scholar |
+| news | recent year in query |
+| *(custom)* | Add your own category key in project YAML |
+
+Bus label: `WebQueryExpander`.

package/.pi/agents/harness/web-retrieval/web-summarizer.md

@@ -0,0 +1,18 @@
+---
+description: WRS page digest — summarize a fetched markdown excerpt.
+extensions: false
+thinking: low
+max_turns: 6
+---
+
+## Your task
+
+Produce a 5–8 bullet summary of a single page excerpt for the parent agent. Read the provided `.web/*.md` or excerpt path only.
+
+## Rules
+
+- Bullets only; no preamble.
+- Preserve factual claims; note if page is marketing-heavy.
+- Do not call web tools.
+
+Bus label: `WebSummarizer`.

package/.pi/extensions/harness-web-guard.ts

@@ -5,7 +5,8 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
 const BLOCK_REASON =
-	"harness-web-guard: use web_search (SERP) or web_fetch (page content) instead of raw curl/wget/firecrawl/scrapling fetch. " +
+	"harness-web-guard: use web_search (tier=deep for research), web_fetch, web_find_similar, or web_contents — " +
+	"not raw curl/wget/firecrawl/scrapling fetch. See web-retrieval skill. " +
 	"Setup may use harness-web.py status directly.";
 
 const ALLOW_PATTERNS = [