feat: add deep-research skill, /deep-research command, fix web-search-researcher

deep-research skill fans out to isolated web-search-researcher subagents (now
using browser_web_search + browser_read_page instead of the non-existent
web_search/web_fetch), coverage-driven loop with a hard ceiling, synthesizes a
cited Markdown report. /deep-research command as explicit entry point. Docs updated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

2 files changed, 74 insertions, 0 deletions

diff --git a/skills/deep-research/SKILL.md b/skills/deep-research/SKILL.md
new file mode 100644
index 0000000..846c522
--- /dev/null
+++ b/skills/deep-research/SKILL.md
@@ -0,0 +1,66 @@
+---
+name: deep-research
+description: Use when the user asks you to research a topic on the web, do deep research, investigate something across multiple sources, or produce a cited report / literature review from the live web. Decomposes the question, fans out isolated web-search-researcher subagents (one per sub-question) that scrape the real browser, then synthesizes a source-cited Markdown report. Trigger phrases include "research", "deep research", "look this up and cite sources", "investigate", "compare X and Y with sources".
+---
+
+# Deep Research
+
+Turn a research question into a **cited Markdown report** by fanning out to isolated `web-search-researcher` subagents that use the real browser, then synthesizing their distilled findings. Every claim in the final report carries a source link.
+
+This runs on two browser tools — `browser_web_search` (ranked SERP, links only) and `browser_read_page` (URL → clean article text) — used *inside the subagents*, not by you directly. Both tools open their own isolated tabs, so **the fan-out never disturbs the user's tabs or current page.** You do not need `/browser-setup` to have been run by you; if the browser isn't connected the subagents' first tool call will report `not_connected` — relay that and ask the user to run `/browser-setup`.
+
+## Workflow
+
+### 1. Decompose
+
+Break the question into **3–6 focused sub-questions**, each independently answerable from the web. Cover the distinct facets — definitions, current state, competing options, trade-offs, recent changes — not slight rewordings of the same thing. Aim for coverage: if you synthesized perfect answers to all sub-questions, the original question should be fully answered.
+
+State the sub-questions to the user before dispatching (a short numbered list) so the plan is visible.
+
+### 2. Fan out
+
+Dispatch **one `web-search-researcher` subagent per sub-question**, in parallel where the runtime allows. Each subagent runs in isolated context and returns a distilled, source-linked finding (claims + urls) — not raw pages. Give each subagent exactly one sub-question plus any constraints (recency, specific ecosystem, authoritative sources to prefer).
+
+Do not do the searching yourself — that is the subagents' job, and their isolation is what keeps your context clean enough to synthesize well.
+
+### 3. Assess coverage — loop with a hard ceiling
+
+After each round of findings, self-assess: **is every sub-question answered, or did findings surface new gaps worth a follow-up search?**
+
+- If gaps remain and you are under the ceiling, dispatch a second round of researchers targeting only the gaps (rephrased or newly discovered sub-questions).
+- **Hard ceiling:** at most **2 rounds** and **8 researcher subagents total**. When you hit either limit, stop searching, synthesize with what you have, and list the unresolved gaps explicitly in the report. Never loop indefinitely chasing completeness.
+
+Handle subagent-reported tool failures:
+- A subagent reporting a `browser_web_search` `invalid_state` with `reason: "captcha"` means a bot wall. **Surface this to the user immediately** and do not spawn a tight retry loop — ask whether to continue, wait, or narrow scope.
+- `reason: "no_results"` is already handled inside the subagent (one rephrase); if it still comes back empty, treat that sub-question as a gap.
+
+### 4. Synthesize a cited report
+
+Merge the distilled findings into a **Markdown report written to a file** (e.g. `research-<topic-slug>.md` in the working directory — tell the user the path). Structure:
+
+```
+# {The research question}
+
+## Summary
+{A few paragraphs answering the question, synthesized across sources.}
+
+## {Sub-topic / sub-question 1}
+{Findings, in prose. Every claim carries a source link inline: … as shown in [Title](url).}
+
+## {Sub-topic 2}
+...
+
+## Open questions / gaps
+{Anything the ceiling left unresolved, or where sources conflicted.}
+
+## Sources
+{Deduplicated list of every URL cited, with titles.}
+```
+
+Rules for the report:
+- **Every factual claim carries a source link** — inline `[title](url)`. No unsourced assertions.
+- **Attribute conflicts.** Where sources disagree, present both and cite each.
+- **Distinguish synthesis from quotation.** Don't fabricate precision the sources didn't provide.
+- **Be honest about gaps.** The gaps section is mandatory when the ceiling cut off coverage — an incomplete-but-honest report beats a complete-looking-but-padded one.
+
+After writing the file, give the user a short chat summary and the file path — don't paste the whole report into the conversation.
diff --git a/skills/pi-browser-harness/SKILL.md b/skills/pi-browser-harness/SKILL.md
index e4221be..60e23e0 100644
--- a/skills/pi-browser-harness/SKILL.md
+++ b/skills/pi-browser-harness/SKILL.md
@@ -21,6 +21,12 @@ What do you need to know?
   ├─ Network behavior on the current page?
   │     → browser_network_requests
   │
+  ├─ Find pages on the web about a topic?
+  │     → browser_web_search    (ranked SERP — links only; follow up with browser_read_page)
+  │
+  ├─ An article's main content as clean text?
+  │     → browser_read_page     (reader mode — a url or an owned targetId → boilerplate stripped)
+  │
   ├─ JS errors / why did nothing happen after an action?
   │     → browser_console     (DIAGNOSTIC — only when something looks broken)
   │
@@ -30,6 +36,8 @@ What do you need to know?
 
 Pass `@(x,y)` from `browser_snapshot` straight to `browser_click`. No screenshot round-trip.
 
+`browser_web_search` and `browser_read_page` each run in their own isolated tab and never touch the user's current tab. For a multi-source question that needs a synthesized, cited report, use the **deep-research** skill (or `/deep-research <question>`): it fans out isolated `web-search-researcher` subagents over both tools and writes a source-cited Markdown report.
+
 ## Connection Setup
 
 Browser control is **on-demand** — the daemon does NOT start automatically.