deep-research-cc 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 desland01
+
+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,299 @@
+<div align="center">
+
+# Deep Research
+
+**Academic-grade multi-agent research pipeline for Claude Code.**
+
+[![Version](https://img.shields.io/badge/version-1.0.0-green?style=for-the-badge)](VERSION)
+[![License](https://img.shields.io/badge/license-MIT-blue?style=for-the-badge)](LICENSE)
+
+<br>
+
+```bash
+npx deep-research-cc
+```
+
+**3-stage pipeline: Research Agents -> Synthesis Agents -> Report Builder**
+
+<br>
+
+*"Point it at a question, walk away, come back to an academic-grade research report with citations."*
+
+<br>
+
+[How It Works](#how-it-works) · [Prerequisites](#prerequisites) · [Installation](#installation) · [Usage](#usage) · [Architecture](#architecture)
+
+</div>
+
+---
+
+## The Problem
+
+Manual research with AI tools is shallow. You search, read, forget context, search again. Sources get lost. Analysis stays surface-level. And if your context window fills up, everything collapses.
+
+**Deep Research fixes that.** It decomposes your question into independent research domains, dispatches parallel agents to investigate each one, synthesizes findings through dedicated analysis agents, and produces a comprehensive report with full citations. All three stages write to disk, so nothing is lost to context limits.
+
+---
+
+## How It Works
+
+### Stage 1: Research Agents (parallel)
+
+You provide a topic. The pipeline decomposes it into 3-6 independent research domains and launches parallel agents, each investigating one domain using Firecrawl MCP for web search and scraping.
+
+Each agent writes a raw research document to `docs/plans/YYYY-MM-DD-{domain}-research.md`.
+
+### Stage 2: Synthesis Agents (parallel)
+
+After all research agents complete, synthesis agents launch in parallel. Each synthesis agent reads exactly ONE research file (strict 1:1 mapping) and produces a distilled domain summary with evidence quality assessment, gap analysis, and organized findings.
+
+Each agent writes to `docs/plans/YYYY-MM-DD-{domain}-synthesis.md`.
+
+### Stage 3: Report Builder (single agent)
+
+A single report builder agent reads ALL synthesis files and produces a comprehensive, externally-shareable research report following an academic template.
+
+Final report: `docs/plans/YYYY-MM-DD-{topic}-report.md`
+
+---
+
+## What You Get
+
+A structured research report with:
+
+- **Executive Summary** with confidence assessment
+- **Methodology** documenting search strategy and source evaluation
+- **Domain Findings** with citations and evidence quality ratings
+- **Cross-Cutting Analysis** identifying themes, contradictions, and risks
+- **Synthesis and Recommendations** with alternatives table
+- **Limitations** and suggested follow-up research
+- **Full References** organized by domain with source type and relevance ratings
+
+Every factual claim traces back to a cited source. The report stands alone: someone with no prior context can read and learn from it.
+
+---
+
+## Prerequisites
+
+| Requirement | Details |
+|-------------|---------|
+| **Claude Code** | Anthropic's CLI for Claude |
+| **Node.js** | v18+ (for npx installer) |
+| **Firecrawl MCP** | Paid API key from [firecrawl.dev](https://firecrawl.dev) |
+
+> **Note:** Firecrawl is a paid service that provides web search and scraping capabilities. Deep Research requires it for all web-based research. Visit [firecrawl.dev/pricing](https://firecrawl.dev/pricing) for current plans.
+
+---
+
+## Installation
+
+### Quick Install (recommended)
+
+```bash
+npx deep-research-cc
+```
+
+The installer copies the skill files into `~/.claude/` and backs up any existing files.
+
+<details>
+<summary><strong>Non-interactive install (Docker, CI, Scripts)</strong></summary>
+
+```bash
+npx deep-research-cc --global   # Install to ~/.claude/
+npx deep-research-cc --local    # Install to ./.claude/
+```
+
+Use `--global` (`-g`) or `--local` (`-l`) to skip the interactive prompt.
+
+</details>
+
+<details>
+<summary><strong>Development installation</strong></summary>
+
+Clone the repository and use symlinks for live editing:
+
+```bash
+git clone https://github.com/desland01/deep-research.git ~/deep-research
+cd ~/deep-research
+chmod +x install.sh
+./install.sh
+```
+
+Changes in `~/deep-research/` are live immediately via symlinks.
+
+</details>
+
+---
+
+## Firecrawl MCP Setup
+
+Deep Research uses Firecrawl MCP for all web search and scraping. You must configure it before using the skill.
+
+### Step 1: Get an API Key
+
+Sign up at [firecrawl.dev](https://firecrawl.dev) and get your API key from the dashboard.
+
+### Step 2: Add Firecrawl MCP to Claude Code
+
+```bash
+claude mcp add firecrawl-mcp -e FIRECRAWL_API_KEY=your-key-here -- npx -y firecrawl-mcp
+```
+
+### Step 3: Restart Claude Code
+
+Restart Claude Code to load both the new skill and the Firecrawl MCP server.
+
+### Verify Setup
+
+Start Claude Code and type `/deep-research`. If the skill loads, you're ready.
+
+---
+
+## Usage
+
+In any Claude Code session:
+
+```
+/deep-research What are the best approaches to real-time voice AI for mobile apps?
+```
+
+The pipeline will:
+
+1. Decompose your question into 3-6 research domains
+2. Launch parallel research agents (each writes to disk)
+3. Launch parallel synthesis agents (each reads one research file, writes synthesis)
+4. Launch a report builder (reads all syntheses, writes final report)
+5. Report the file location and top-level findings
+
+### Example Output Files
+
+For a research topic "voice AI providers for React Native":
+
+```
+docs/plans/
+  2026-02-16-voice-ai-landscape-research.md
+  2026-02-16-voice-ai-pricing-research.md
+  2026-02-16-voice-ai-react-native-research.md
+  2026-02-16-voice-ai-latency-research.md
+  2026-02-16-voice-ai-privacy-research.md
+  2026-02-16-voice-ai-landscape-synthesis.md
+  2026-02-16-voice-ai-pricing-synthesis.md
+  2026-02-16-voice-ai-react-native-synthesis.md
+  2026-02-16-voice-ai-latency-synthesis.md
+  2026-02-16-voice-ai-privacy-synthesis.md
+  2026-02-16-voice-ai-providers-report.md      <- Final report
+```
+
+---
+
+## Architecture
+
+```
+/deep-research [topic]
+       |
+       v
+   Decompose into 3-6 domains
+       |
+       v
+  ┌────┬────┬────┬────┬────┐
+  R1   R2   R3   R4   R5   R6    <- Research agents (parallel, background)
+  |    |    |    |    |    |         Each writes *-research.md to disk
+  └────┴────┴────┴────┴────┘
+       |
+       v  (wait for ALL to complete)
+       |
+  ┌────┬────┬────┬────┬────┐
+  S1   S2   S3   S4   S5   S6    <- Synthesis agents (parallel, background)
+  |    |    |    |    |    |         1:1 with research agents
+  └────┴────┴────┴────┴────┘         Each reads one *-research.md, writes *-synthesis.md
+       |
+       v  (wait for ALL to complete)
+       |
+      [RB]                        <- Report builder (single agent, background)
+       |                             Reads ALL *-synthesis.md files
+       v                             Writes final *-report.md
+   Final Report
+```
+
+### Agent Limits
+
+| Constraint | Value |
+|-----------|-------|
+| Max parallel research agents | 6 |
+| Max parallel synthesis agents | 6 (1:1 with research) |
+| Report builder agents | 1 (always single) |
+| Parent reads raw output | Never |
+| Parent reads final report | Yes (after verification) |
+
+### Why Disk-Based Handoff?
+
+Raw research agent output can exceed 600K tokens. If the parent agent reads it via TaskOutput, context gets crushed and downstream agents never launch. Writing to disk files keeps each stage isolated and the parent context clean.
+
+### Anti-Patterns
+
+| Don't | Do Instead |
+|-------|-----------|
+| Read TaskOutput from research/synthesis agents | Wait for completion, check files on disk |
+| Assign 2+ research files to one synthesis agent | Strict 1:1 mapping |
+| Skip the report builder for "simple" research | Always run all 3 stages |
+| Omit Firecrawl instructions from research agents | Agents don't inherit MCP context |
+| Omit source URLs | Every claim must trace to a URL |
+
+---
+
+## Troubleshooting
+
+**Skill not found after install?**
+- Restart Claude Code to reload skills
+- Verify files exist: `ls ~/.claude/skills/deep-research/`
+
+**Research agents failing?**
+- Check Firecrawl MCP is configured: look for `firecrawl-mcp` in your MCP server list
+- Verify your API key is valid at [firecrawl.dev/dashboard](https://firecrawl.dev)
+
+**Report missing sections?**
+- Check that all research and synthesis files were created in `docs/plans/`
+- The report builder only runs after ALL synthesis agents complete
+
+**Context getting crushed?**
+- This usually means the parent is reading raw agent output. The skill prevents this by design, but if you've modified the protocol, ensure the parent never reads research or synthesis files directly.
+
+---
+
+## Directory Structure
+
+```
+deep-research/
+├── README.md
+├── VERSION
+├── LICENSE
+├── .gitignore
+├── package.json
+├── install.sh                         # Dev install (symlinks)
+├── bin/
+│   └── install.js                     # npx entry point (copy-based)
+└── skills/
+    └── deep-research/
+        ├── SKILL.md                   # 3-stage protocol
+        ├── academic-report-template.md # Report format template
+        └── firecrawl-reference.md     # Firecrawl MCP tool reference
+```
+
+---
+
+## Contributing
+
+1. Clone the repo and run `./install.sh`
+2. Edit files in `~/deep-research/` (changes are live via symlinks)
+3. Test with `/deep-research` in Claude Code
+4. For protocol changes, verify all 3 stages produce expected output files
+
+---
+
+<div align="center">
+
+**Claude Code is powerful. Deep Research makes it thorough.**
+
+*Academic-grade research pipelines, so you can decide with confidence.*
+
+</div>

package/VERSION

@@ -0,0 +1 @@
+1.0.0

package/bin/install.js

@@ -0,0 +1,119 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+const path = require("path");
+const os = require("os");
+const readline = require("readline");
+
+const VERSION = fs
+  .readFileSync(path.join(__dirname, "..", "VERSION"), "utf8")
+  .trim();
+const PKG_ROOT = path.join(__dirname, "..");
+const HOME = os.homedir();
+
+const TARGETS = {
+  global: path.join(HOME, ".claude"),
+  local: path.join(process.cwd(), ".claude"),
+};
+
+const DIRS_TO_COPY = ["skills/deep-research"];
+
+// -- Helpers ----------------------------------------------------------------
+
+function copyDirSync(src, dest) {
+  fs.mkdirSync(dest, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const destPath = path.join(dest, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+function backupIfExists(target) {
+  if (fs.existsSync(target)) {
+    const timestamp = new Date()
+      .toISOString()
+      .replace(/[-:T]/g, "")
+      .slice(0, 14);
+    const backup = `${target}.backup.${timestamp}`;
+    console.log(`  Backing up existing -> ${path.basename(backup)}`);
+    fs.renameSync(target, backup);
+  }
+}
+
+function install(claudeDir) {
+  console.log(`\nInstalling to ${claudeDir}/\n`);
+
+  for (const rel of DIRS_TO_COPY) {
+    const src = path.join(PKG_ROOT, rel);
+    const dest = path.join(claudeDir, rel);
+
+    // Ensure parent dir exists
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+
+    backupIfExists(dest);
+    copyDirSync(src, dest);
+    console.log(`  Copied: ${rel}`);
+  }
+
+  console.log(`
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Install complete.
+
+Skill installed:
+  /deep-research [topic]    Run 3-stage academic research pipeline
+
+Firecrawl MCP Setup (required):
+  Deep Research uses Firecrawl for web search and scraping.
+  You need a Firecrawl API key from https://firecrawl.dev
+
+  Add Firecrawl MCP to your project:
+    claude mcp add firecrawl-mcp -e FIRECRAWL_API_KEY=your-key -- npx -y firecrawl-mcp
+
+  Then restart Claude Code to load the new skill and MCP server.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+}
+
+// -- Main -------------------------------------------------------------------
+
+console.log(`
+Deep Research Installer v${VERSION}
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`);
+
+const args = process.argv.slice(2);
+
+if (args.includes("--global") || args.includes("-g")) {
+  install(TARGETS.global);
+} else if (args.includes("--local") || args.includes("-l")) {
+  install(TARGETS.local);
+} else {
+  // Interactive prompt
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+
+  console.log(`
+Where would you like to install?
+
+  1) Global  (~/.claude/)      Available in all projects
+  2) Local   (./.claude/)      This project only
+`);
+
+  rl.question("Choose [1/2]: ", (answer) => {
+    rl.close();
+    const choice = answer.trim();
+    if (choice === "1" || choice.toLowerCase() === "global") {
+      install(TARGETS.global);
+    } else if (choice === "2" || choice.toLowerCase() === "local") {
+      install(TARGETS.local);
+    } else {
+      console.log("Invalid choice. Use --global or --local flag, or enter 1 or 2.");
+      process.exit(1);
+    }
+  });
+}

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "deep-research-cc",
+  "version": "1.0.0",
+  "description": "Academic-grade multi-agent research pipeline for Claude Code — 3-stage deep research that writes itself.",
+  "bin": {
+    "deep-research-cc": "bin/install.js"
+  },
+  "files": [
+    "bin/",
+    "skills/",
+    "VERSION"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "research",
+    "deep-research",
+    "firecrawl",
+    "academic",
+    "multi-agent"
+  ],
+  "author": "desland01",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/desland01/deep-research.git"
+  }
+}

package/skills/deep-research/SKILL.md

@@ -0,0 +1,229 @@
+---
+name: deep-research
+description: "Use when evaluating technologies, making architectural decisions, comparing options across multiple dimensions, or any research task requiring 5+ web searches across multiple domains. Triggers on phrases like 'research this', 'figure out the best way', 'compare options for', or 'what are our choices'. NOT for simple factual lookups, codebase exploration, or tasks where you already have enough context."
+argument-hint: [topic or question]
+---
+
+# Deep Research Protocol (3-Stage Pipeline)
+
+Autonomous multi-agent research workflow producing academic-level reports. Three stages: Research, Synthesis, Report. Each stage writes to disk. Parent never touches raw output from any stage.
+
+## Why This Exists
+
+Raw research agent output can exceed 600K tokens. If the parent reads it (via TaskOutput or inline), context gets crushed and downstream agents never launch. This protocol keeps the parent context clean by using disk files as the handoff layer between all three stages.
+
+## The Rule
+
+**Parent (you) must NEVER:**
+- Read TaskOutput from research agents or synthesis agents
+- Paste findings from any agent into another agent's prompt
+- Read raw JSONL output files
+- Read research or synthesis markdown files directly
+
+**Parent (you) CAN:**
+- Check completion status via task notifications (automatic)
+- Read the final report on disk after Stage 3 completes
+- Verify files exist using Glob
+- Grep for structural markers (headers, citations) without reading full content
+
+## Protocol
+
+### Step 1: Decompose
+
+Split the research question into 3-6 independent domains. Each domain becomes one research agent. Domains should be non-overlapping but collectively exhaustive.
+
+Example decomposition for "Best voice AI provider for our app":
+- Domain 1: Provider landscape and feature comparison
+- Domain 2: Pricing models and cost projections
+- Domain 3: React Native integration complexity
+- Domain 4: Latency, reliability, and production readiness
+- Domain 5: Privacy, compliance, and data handling
+
+### Step 2: Dispatch Research Agents (parallel, background)
+
+Launch all research agents in parallel with `run_in_background: true`.
+
+Each research agent writes to: `docs/plans/YYYY-MM-DD-{domain-slug}-research.md`
+
+Use the Research Agent Prompt Template below. Every prompt MUST include:
+- Numbered questions to answer (3-5 per agent)
+- Firecrawl MCP tool instructions (agents do not inherit MCP context)
+- Suggested search queries (3-5 per agent)
+- The exact output file path
+- Instructions to include source URLs for every claim
+
+### Step 3: Wait for Research Completion
+
+Do nothing. Task notifications arrive automatically when agents complete. Do NOT poll, do NOT read output files. Wait until all research agents report completion.
+
+### Step 4: Dispatch Synthesis Agents (parallel, background)
+
+After ALL research agents complete, launch synthesis agents with `run_in_background: true`.
+
+**One synthesis agent per research agent.** This is a strict 1:1 mapping. Each synthesis agent reads exactly ONE research file and produces ONE synthesis file. Never assign multiple research files to a single synthesis agent.
+
+Each synthesis agent reads from: `docs/plans/YYYY-MM-DD-{domain-slug}-research.md`
+Each synthesis agent writes to: `docs/plans/YYYY-MM-DD-{domain-slug}-synthesis.md`
+
+Use the Synthesis Agent Prompt Template below. Every prompt MUST include:
+- The exact research file path to READ
+- The exact synthesis file path to WRITE
+- Instructions to distill, organize, cite, and assess source quality
+- Instructions to flag gaps and contradictions
+
+**Why 1:1?** Each domain deserves dedicated attention. Combining domains in synthesis loses nuance and produces shallow analysis.
+
+### Step 5: Dispatch Report Builder (single agent, background)
+
+After ALL synthesis agents complete, launch ONE report builder agent with `run_in_background: true`.
+
+The report builder reads ALL synthesis files and produces a single comprehensive report.
+
+Report builder reads from: All `docs/plans/YYYY-MM-DD-*-synthesis.md` files
+Report builder writes to: `docs/plans/YYYY-MM-DD-{overall-topic}-report.md`
+Report builder references: `~/.claude/skills/deep-research/academic-report-template.md`
+
+Use the Report Builder Prompt Template below. The report builder focuses on cross-cutting analysis, theme identification, and actionable recommendations. It does NOT re-analyze raw research. It works exclusively from the synthesized domain summaries.
+
+### Step 6: Verify and Report
+
+After the report builder completes:
+
+1. Verify deliverables exist on disk (Glob for the report file)
+2. Grep for structural markers: `## Executive Summary`, `## References`, `## 2. Methodology`
+3. Grep for citation presence (source URLs in References section)
+4. Report to user: what was researched, where the report lives, key top-level findings (2-3 sentences max)
+
+The user reads the report on disk. Do NOT paste report content into the chat.
+
+## Agent Limits
+
+| Constraint | Value |
+|-----------|-------|
+| Max parallel research agents | 6 |
+| Max parallel synthesis agents | 6 (1:1 with research agents) |
+| Report builder agents | 1 (always single) |
+| Research agent output | `docs/plans/YYYY-MM-DD-{domain}-research.md` |
+| Synthesis agent output | `docs/plans/YYYY-MM-DD-{domain}-synthesis.md` |
+| Report builder output | `docs/plans/YYYY-MM-DD-{topic}-report.md` |
+| Parent reads raw output | NEVER (research or synthesis) |
+| Parent reads final report | YES (after Step 6 verification) |
+
+## Key Principles
+
+| Principle | Rationale |
+|-----------|-----------|
+| Disk files as handoff layer | Prevents context flooding between stages |
+| 1:1 synthesis mapping | Each domain gets dedicated analytical attention |
+| Report builder works from syntheses only | Cross-cutting analysis, not domain re-reading |
+| Academic rigor | Every claim needs a citation, methodology documented, limitations acknowledged |
+| Background execution for all agents | Parent stays responsive, agents run in parallel |
+| Firecrawl MCP for web research | Consistent tool usage, agents don't inherit MCP context |
+| All findings include source URLs | Traceability and verifiability of claims |
+| Report should be externally shareable | Quality bar: someone outside the team can read and learn from it |
+
+## Template: Research Agent Prompt
+
+```
+You are a technical researcher. Your job is to thoroughly investigate [DOMAIN].
+
+Questions to answer:
+1. [Question 1]
+2. [Question 2]
+3. [Question 3]
+4. [Question 4 - optional]
+5. [Question 5 - optional]
+
+Research method:
+- Use Firecrawl MCP tools for all web search and URL scraping
+- `mcp__firecrawl-mcp__firecrawl_search` for web search (use `query` param)
+- `mcp__firecrawl-mcp__firecrawl_scrape` for reading specific URLs (use `url` param)
+- Reference `~/.claude/skills/deep-research/firecrawl-reference.md` for tool patterns and params
+- Suggested searches: "[query 1]", "[query 2]", "[query 3]"
+
+Output requirements:
+- Write ALL findings to `docs/plans/YYYY-MM-DD-{domain-slug}-research.md` using the Write tool
+- Structure with clear H2/H3 headers and tables where data is comparable
+- Include source URLs for EVERY factual claim (inline or footnote style)
+- Include direct quotes from official documentation where relevant
+- Note contradictions between sources
+- Never use em dashes (use commas, periods, or restructure sentences)
+- End with a "Sources" section listing all URLs consulted with brief descriptions
+```
+
+## Template: Synthesis Agent Prompt
+
+```
+You are an analytical synthesizer. Your job is to distill raw research into a focused, well-organized domain summary.
+
+Input: Read the research document at `docs/plans/YYYY-MM-DD-{domain-slug}-research.md` using the Read tool.
+
+Output: Write your synthesis to `docs/plans/YYYY-MM-DD-{domain-slug}-synthesis.md` using the Write tool.
+
+Synthesis requirements:
+1. **Key Findings** (bulleted, 5-10 items): The most important facts and conclusions from the research
+2. **Thematic Organization**: Group findings by theme, not by source. Use H2 headers for each theme.
+3. **Evidence Quality Assessment**: For each major claim, note:
+   - Number of independent sources confirming it
+   - Source credibility (official docs, peer-reviewed, blog post, forum, marketing material)
+   - Recency (when was this information published or last updated?)
+4. **Gaps and Contradictions**: What questions remain unanswered? Where do sources disagree?
+5. **Citations**: Preserve all source URLs from the research document. Every claim must trace back to a source.
+6. **Domain-Specific Recommendations**: Based on the evidence, what are the clear takeaways for this domain?
+
+Style rules:
+- Never use em dashes (use commas, periods, or restructure sentences)
+- Tables for comparisons and structured data
+- Concise paragraphs (3-4 sentences max)
+- No filler, no hedging language, no sycophancy
+- Write for a technical audience that wants actionable information
+```
+
+## Template: Report Builder Prompt
+
+```
+You are an academic research report writer. Your job is to produce a comprehensive, externally-shareable research report from multiple domain syntheses.
+
+Input: Read ALL synthesis files matching `docs/plans/YYYY-MM-DD-*-synthesis.md` using the Read tool.
+Template: Read the report template at `~/.claude/skills/deep-research/academic-report-template.md` using the Read tool.
+
+Output: Write the final report to `docs/plans/YYYY-MM-DD-{overall-topic}-report.md` using the Write tool.
+
+Report structure (follow the academic report template):
+1. **Executive Summary** (200-300 words): Core question, key findings, primary recommendation, confidence level
+2. **Introduction**: Problem statement, scope and boundaries, numbered research questions
+3. **Methodology**: Search strategy, source evaluation criteria, source distribution by type, limitations
+4. **Domain Findings**: One major section per synthesis file. Key findings with citations, evidence quality, notable gaps.
+5. **Cross-Cutting Analysis**: Common themes across domains, contradictions, dependencies, risk assessment matrix
+6. **Synthesis and Recommendations**: Primary recommendation with rationale, alternatives table, implementation considerations, decision criteria for when to revisit
+7. **Limitations and Future Research**: Exclusions, thin evidence areas, suggested follow-up research
+8. **References**: All source URLs organized by domain, with title, access date, type, and relevance rating
+
+Quality standards:
+- Every factual claim must have a citation (URL or source reference)
+- Distinguish between established facts, expert opinions, and emerging trends
+- Quantify where possible (costs, latency numbers, adoption percentages)
+- Acknowledge uncertainty explicitly rather than presenting speculation as fact
+- The report should stand alone: a reader with no prior context should understand it fully
+
+Style rules:
+- Never use em dashes (use commas, periods, or restructure sentences)
+- Professional, direct tone. No filler or hedging.
+- Tables for all comparative data
+- Use H2 for major sections, H3 for subsections
+- Target length: 2,000-5,000 words depending on complexity
+```
+
+## Anti-Patterns
+
+| Do NOT do this | Do this instead |
+|---------------|-----------------|
+| Read TaskOutput from any agent | Wait for task notifications, then check disk |
+| Paste research into synthesis prompt | Tell synthesis agent which file to Read from disk |
+| Assign 2+ research files to one synthesis agent | Maintain strict 1:1 mapping |
+| Skip the report builder for "simple" research | Always run all 3 stages. The report builder adds cross-cutting analysis. |
+| Read the research or synthesis files yourself | Only read the final report after Step 6 |
+| Launch synthesis before ALL research completes | Wait for every research agent to finish |
+| Launch report builder before ALL synthesis completes | Wait for every synthesis agent to finish |
+| Omit Firecrawl instructions from research agents | Agents do not inherit MCP context. Always spell it out. |
+| Omit source URLs | Every claim must trace to a URL |

package/skills/deep-research/academic-report-template.md

@@ -0,0 +1,435 @@
+# [TOPIC]
+
+**Research Date:** [DATE]
+**Domains Covered:** [DOMAIN_1], [DOMAIN_2], [DOMAIN_3], ... [DOMAIN_N]
+**Total Sources Consulted:** [SOURCE_COUNT]
+**Report Version:** 1.0
+
+---
+
+## Executive Summary
+
+<!--
+Write 200-300 words. State the core question, the key findings, the primary recommendation,
+and an honest confidence assessment. This section should stand alone: a reader who only reads
+this section should understand what was researched, what was found, and what to do next.
+-->
+
+**Core Question:** [STATE_THE_CENTRAL_RESEARCH_QUESTION]
+
+**Key Findings:**
+
+- [FINDING_1: One sentence summarizing the most important discovery]
+- [FINDING_2: One sentence on the second most important finding]
+- [FINDING_3: One sentence on the third finding]
+- [FINDING_4: Optional fourth finding]
+- [FINDING_5: Optional fifth finding]
+
+**Primary Recommendation:** [ONE_PARAGRAPH_RECOMMENDATION]
+
+**Confidence Level:** [HIGH / MODERATE / LOW]
+
+<!--
+Confidence criteria:
+- HIGH: Multiple independent sources agree, official documentation confirms, tested/verified examples exist
+- MODERATE: Several sources agree but some gaps remain, limited independent verification
+- LOW: Few sources available, conflicting information, rapidly changing landscape, or heavy reliance on unofficial sources
+-->
+
+**Confidence Rationale:** [ONE_SENTENCE_EXPLAINING_WHY_THIS_CONFIDENCE_LEVEL]
+
+---
+
+## 1. Introduction
+
+### 1.1 Problem Statement and Motivation
+
+<!--
+Why does this research matter? What decision, project, or initiative prompted it?
+Be specific about the practical context driving this investigation.
+-->
+
+[PROBLEM_STATEMENT]
+
+### 1.2 Scope and Boundaries
+
+**In scope:**
+
+- [INCLUDED_TOPIC_1]
+- [INCLUDED_TOPIC_2]
+- [INCLUDED_TOPIC_3]
+
+**Explicitly excluded:**
+
+- [EXCLUDED_TOPIC_1: brief reason for exclusion]
+- [EXCLUDED_TOPIC_2: brief reason for exclusion]
+
+### 1.3 Research Questions
+
+<!--
+Number each question. These should be specific and answerable, not vague.
+Good: "What is the p95 latency of Provider X's streaming API under concurrent load?"
+Bad: "Is Provider X fast?"
+-->
+
+1. [RESEARCH_QUESTION_1]
+2. [RESEARCH_QUESTION_2]
+3. [RESEARCH_QUESTION_3]
+4. [RESEARCH_QUESTION_N]
+
+---
+
+## 2. Methodology
+
+### 2.1 Search Strategy
+
+<!--
+Document how the research was conducted so the reader can assess rigor and reproduce it.
+-->
+
+| Parameter | Details |
+|-----------|---------|
+| Search tools | [e.g., Firecrawl MCP search, Firecrawl scrape, GitHub API] |
+| Date range | [e.g., Sources published after January 2025] |
+| Query terms | [List primary search queries used] |
+| Languages | [e.g., English only] |
+| Geographic scope | [e.g., Global, US-focused, etc.] |
+
+### 2.2 Source Evaluation Criteria
+
+Sources were evaluated on the following dimensions:
+
+| Criterion | Weight | Description |
+|-----------|--------|-------------|
+| Authority | High | Official docs, peer-reviewed papers, recognized experts |
+| Recency | High | Published within [TIME_WINDOW], reflecting current state |
+| Specificity | Medium | Addresses the exact question, not tangential topics |
+| Independence | Medium | Not authored by a vendor about their own product |
+| Reproducibility | Medium | Claims backed by code samples, benchmarks, or verifiable data |
+
+### 2.3 Source Distribution
+
+| Source Type | Count | Notes |
+|-------------|-------|-------|
+| Official documentation | [N] | |
+| Academic/research papers | [N] | |
+| Technical blog posts | [N] | |
+| GitHub repositories | [N] | |
+| Conference talks/videos | [N] | |
+| Community discussions | [N] | [e.g., Stack Overflow, Discord, forums] |
+| Vendor/marketing materials | [N] | [treated with appropriate skepticism] |
+| **Total** | **[SOURCE_COUNT]** | |
+
+### 2.4 Limitations of This Research
+
+<!--
+Be honest. Every research method has blind spots. Acknowledging them increases credibility.
+-->
+
+- [LIMITATION_1: e.g., "No hands-on benchmarking was performed; latency figures are from third-party reports"]
+- [LIMITATION_2: e.g., "Pricing information may be outdated; last verified on [DATE]"]
+- [LIMITATION_3: e.g., "Limited non-English sources consulted"]
+
+---
+
+## 3. Domain Findings
+
+<!--
+Create one subsection (3.1, 3.2, etc.) per research domain.
+Each domain was investigated by a separate research agent with a focused scope.
+-->
+
+### 3.1 [DOMAIN_1_TITLE]
+
+#### Key Findings
+
+<!--
+Each finding should include a citation. Use the format [Source Title](URL) inline,
+or use numbered references like [1] that map to the References section.
+Prefer inline links for readability when the report will be consumed as markdown.
+-->
+
+- [FINDING]: [CITATION]
+- [FINDING]: [CITATION]
+- [FINDING]: [CITATION]
+
+#### Evidence Quality
+
+<!--
+Rate the overall evidence quality for this domain and explain why.
+-->
+
+| Rating | Justification |
+|--------|--------------|
+| **[STRONG / MODERATE / WEAK]** | [Brief explanation, e.g., "Multiple official sources and independent benchmarks confirm these findings"] |
+
+#### Notable Gaps
+
+<!--
+What questions in this domain could not be fully answered? What data was missing?
+-->
+
+- [GAP_1]
+- [GAP_2]
+
+#### Comparison Table
+
+<!--
+Include when the domain involves evaluating multiple options, tools, or approaches.
+Omit this subsection if not applicable.
+-->
+
+| Criterion | Option A | Option B | Option C |
+|-----------|----------|----------|----------|
+| [CRITERION_1] | [VALUE] | [VALUE] | [VALUE] |
+| [CRITERION_2] | [VALUE] | [VALUE] | [VALUE] |
+| [CRITERION_3] | [VALUE] | [VALUE] | [VALUE] |
+| **Overall** | [RATING] | [RATING] | [RATING] |
+
+---
+
+### 3.2 [DOMAIN_2_TITLE]
+
+#### Key Findings
+
+- [FINDING]: [CITATION]
+- [FINDING]: [CITATION]
+
+#### Evidence Quality
+
+| Rating | Justification |
+|--------|--------------|
+| **[STRONG / MODERATE / WEAK]** | [Explanation] |
+
+#### Notable Gaps
+
+- [GAP_1]
+
+---
+
+### 3.N [DOMAIN_N_TITLE]
+
+<!--
+Repeat the domain section structure for each research domain.
+Typical reports have 3-6 domain sections.
+-->
+
+#### Key Findings
+
+- [FINDING]: [CITATION]
+
+#### Evidence Quality
+
+| Rating | Justification |
+|--------|--------------|
+| **[STRONG / MODERATE / WEAK]** | [Explanation] |
+
+#### Notable Gaps
+
+- [GAP_1]
+
+---
+
+## 4. Cross-Cutting Analysis
+
+<!--
+This is where the report goes beyond summarizing individual domains and performs synthesis.
+Look for patterns, contradictions, and interactions across domains.
+-->
+
+### 4.1 Common Themes
+
+<!--
+Identify findings or patterns that appeared independently in multiple domains.
+These carry higher confidence because they were corroborated from different angles.
+-->
+
+| Theme | Domains Where Observed | Confidence |
+|-------|----------------------|------------|
+| [THEME_1] | [DOMAIN_A], [DOMAIN_B] | [HIGH/MODERATE/LOW] |
+| [THEME_2] | [DOMAIN_A], [DOMAIN_C] | [HIGH/MODERATE/LOW] |
+
+### 4.2 Contradictions and Tensions
+
+<!--
+Where did different domains or sources disagree? Do not paper over disagreements.
+Present both sides and, if possible, explain why they diverge.
+-->
+
+- **[TENSION_1]:** [Domain X suggests A, while Domain Y suggests B. This may be because...]
+- **[TENSION_2]:** [Description of the contradiction and possible explanations]
+
+### 4.3 Dependencies and Interactions
+
+<!--
+How do decisions in one domain constrain or enable decisions in another?
+Example: "Choosing Provider X for the API layer constrains the authentication options to OAuth 2.0 only."
+-->
+
+- [DEPENDENCY_1]
+- [DEPENDENCY_2]
+
+### 4.4 Risk Assessment
+
+<!--
+Identify the key risks surfaced by the research. Rate each on likelihood and impact.
+-->
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| [RISK_1] | [HIGH/MED/LOW] | [HIGH/MED/LOW] | [Brief mitigation strategy] |
+| [RISK_2] | [HIGH/MED/LOW] | [HIGH/MED/LOW] | [Brief mitigation strategy] |
+| [RISK_3] | [HIGH/MED/LOW] | [HIGH/MED/LOW] | [Brief mitigation strategy] |
+
+---
+
+## 5. Synthesis and Recommendations
+
+### 5.1 Primary Recommendation
+
+<!--
+State the recommendation clearly and then explain why.
+The rationale should reference specific findings from the domain sections.
+A reader should be able to trace the recommendation back to evidence.
+-->
+
+**Recommendation:** [CLEAR_STATEMENT_OF_WHAT_TO_DO]
+
+**Rationale:** [2-3 paragraphs explaining why, referencing specific findings from Sections 3 and 4]
+
+### 5.2 Alternative Approaches
+
+<!--
+Present the alternatives that were considered. Be fair to each.
+The reader may have different constraints than those assumed in the primary recommendation.
+-->
+
+| Approach | Strengths | Weaknesses | Best When |
+|----------|-----------|------------|-----------|
+| [PRIMARY: recommended] | [STRENGTHS] | [WEAKNESSES] | [CONDITIONS] |
+| [ALTERNATIVE_1] | [STRENGTHS] | [WEAKNESSES] | [CONDITIONS] |
+| [ALTERNATIVE_2] | [STRENGTHS] | [WEAKNESSES] | [CONDITIONS] |
+
+### 5.3 Implementation Considerations
+
+<!--
+Practical notes for acting on the recommendation. Not a full implementation plan,
+but enough to understand the effort, prerequisites, and sequencing.
+-->
+
+- **Prerequisites:** [What must be in place before starting]
+- **Estimated effort:** [Rough sizing, e.g., "2-3 sprint cycles for a team of 2"]
+- **Key decisions to make first:** [Decisions that block implementation]
+- **Suggested sequencing:** [What to do first, second, third]
+
+### 5.4 Decision Criteria
+
+<!--
+Under what circumstances would the recommendation change? This is critical for making
+the report durable. If conditions shift, the reader knows when to re-evaluate.
+-->
+
+The primary recommendation should be revisited if any of the following occur:
+
+- [CONDITION_1: e.g., "Provider X raises pricing above $Y/month"]
+- [CONDITION_2: e.g., "A competing solution achieves feature parity with lower latency"]
+- [CONDITION_3: e.g., "Requirements change to include [SPECIFIC_CAPABILITY]"]
+
+---
+
+## 6. Limitations and Future Research
+
+### 6.1 What This Report Does Not Cover
+
+<!--
+Restate scope exclusions and add any areas that turned out to be relevant
+but could not be adequately researched within the current scope.
+-->
+
+- [EXCLUSION_1]
+- [EXCLUSION_2]
+
+### 6.2 Areas of Thin or Conflicting Evidence
+
+<!--
+Where was the evidence insufficient to draw strong conclusions?
+Be specific about what data would resolve the uncertainty.
+-->
+
+- **[AREA_1]:** [What is uncertain and what evidence would help]
+- **[AREA_2]:** [What is uncertain and what evidence would help]
+
+### 6.3 Suggested Follow-Up Research
+
+<!--
+Concrete next steps for research, not vague suggestions.
+Include specific questions and, where possible, suggested approaches.
+-->
+
+1. **[FOLLOW_UP_1]:** [Specific question to answer, suggested method]
+2. **[FOLLOW_UP_2]:** [Specific question to answer, suggested method]
+3. **[FOLLOW_UP_3]:** [Specific question to answer, suggested method]
+
+---
+
+## 7. References
+
+<!--
+Organize references by domain for easy navigation.
+Every claim in the report should trace back to a reference here.
+
+Reference format:
+- [N] **Title** — URL — Accessed [DATE] — Type: [official docs / paper / blog / repo / discussion / vendor] — Relevance: [HIGH/MEDIUM/LOW]
+-->
+
+### [DOMAIN_1_TITLE]
+
+- [1] **[Source Title]** | [URL] | Accessed [DATE] | Type: [SOURCE_TYPE] | Relevance: [HIGH/MEDIUM/LOW]
+- [2] **[Source Title]** | [URL] | Accessed [DATE] | Type: [SOURCE_TYPE] | Relevance: [HIGH/MEDIUM/LOW]
+
+### [DOMAIN_2_TITLE]
+
+- [3] **[Source Title]** | [URL] | Accessed [DATE] | Type: [SOURCE_TYPE] | Relevance: [HIGH/MEDIUM/LOW]
+- [4] **[Source Title]** | [URL] | Accessed [DATE] | Type: [SOURCE_TYPE] | Relevance: [HIGH/MEDIUM/LOW]
+
+### [DOMAIN_N_TITLE]
+
+- [N] **[Source Title]** | [URL] | Accessed [DATE] | Type: [SOURCE_TYPE] | Relevance: [HIGH/MEDIUM/LOW]
+
+---
+
+## Appendices
+
+<!--
+Include appendices only when there is substantial supplementary data that would
+disrupt the flow of the main report. Each appendix should be self-contained.
+Omit this entire section if no appendices are needed.
+-->
+
+### Appendix A: [TITLE]
+
+<!-- Example: Detailed Feature Comparison Matrix -->
+
+| Feature | Option A | Option B | Option C | Option D |
+|---------|----------|----------|----------|----------|
+| [FEATURE_1] | [DETAIL] | [DETAIL] | [DETAIL] | [DETAIL] |
+| [FEATURE_2] | [DETAIL] | [DETAIL] | [DETAIL] | [DETAIL] |
+
+### Appendix B: [TITLE]
+
+<!-- Example: Pricing and Cost Analysis -->
+
+| Tier | Monthly Cost | Included Usage | Overage Rate | Notes |
+|------|-------------|---------------|-------------|-------|
+| [TIER_1] | [COST] | [USAGE] | [RATE] | [NOTES] |
+| [TIER_2] | [COST] | [USAGE] | [RATE] | [NOTES] |
+
+### Appendix C: [TITLE]
+
+<!-- Example: Technical Specifications or Configuration Details -->
+
+[SUPPLEMENTARY_CONTENT]
+
+---
+
+*Report generated via Deep Research Protocol. [AGENT_COUNT] research agents across [DOMAIN_COUNT] domains, synthesized into a unified analysis.*

package/skills/deep-research/firecrawl-reference.md

@@ -0,0 +1,220 @@
+# Firecrawl MCP Reference
+
+## Layer 1: Quick Decision Table
+
+Use this to pick the right Firecrawl tool instantly.
+
+| I need to... | Tool | Key params | Credits |
+|---|---|---|---|
+| Search the web for info | `mcp__firecrawl-mcp__firecrawl_search` | `query`, `limit` | 2 per 10 results |
+| Get content from a known URL | `mcp__firecrawl-mcp__firecrawl_scrape` | `url`, `formats: ["markdown"]` | 1 per page |
+| Scrape multiple known URLs | `mcp__firecrawl-mcp__firecrawl_batch_scrape` | `urls`, `options` | 1 per page |
+| Discover all URLs on a site | `mcp__firecrawl-mcp__firecrawl_map` | `url`, `search` | 1 |
+| Crawl a site section | `mcp__firecrawl-mcp__firecrawl_crawl` | `url`, `limit`, `maxDiscoveryDepth` | 1 per page |
+| Extract structured JSON from pages | `mcp__firecrawl-mcp__firecrawl_extract` | `urls`, `prompt`, `schema` | varies |
+
+**Default for web search**: Always use `firecrawl_search` instead of `WebSearch`.
+**Default for reading a URL**: Always use `firecrawl_scrape` instead of `WebFetch`.
+
+---
+
+## Layer 2: Common Patterns
+
+### Web Search (most common)
+```json
+{
+  "query": "your search terms",
+  "limit": 5,
+  "sources": [{"type": "web"}]
+}
+```
+
+To also scrape the result pages:
+```json
+{
+  "query": "your search terms",
+  "limit": 3,
+  "scrapeOptions": {
+    "formats": ["markdown"],
+    "onlyMainContent": true
+  }
+}
+```
+
+**Search sources**: `web` (default), `news`, `images`. Limit applies per source type.
+
+**Search categories** (filter by site type):
+- `github`: GitHub repos, code, issues
+- `research`: arXiv, Nature, IEEE, PubMed
+- `pdf`: PDF documents
+
+**Time filters** (via `tbs` param):
+- `qdr:h` past hour, `qdr:d` past 24h, `qdr:w` past week, `qdr:m` past month, `qdr:y` past year
+
+### Single Page Scrape
+```json
+{
+  "url": "https://example.com",
+  "formats": ["markdown"],
+  "onlyMainContent": true,
+  "maxAge": 172800000
+}
+```
+
+**Performance tip**: `maxAge: 172800000` (2-day cache) makes scrapes up to 5x faster. Use `maxAge: 0` for fresh content.
+
+### Site Discovery (Map then Scrape)
+```json
+{
+  "url": "https://docs.example.com",
+  "search": "api reference",
+  "limit": 50
+}
+```
+Use `map` to find URLs, then `scrape` or `batch_scrape` to get content.
+
+### Structured Data Extraction
+```json
+{
+  "urls": ["https://example.com/pricing"],
+  "prompt": "Extract all pricing plans with name, price, and features",
+  "schema": {
+    "type": "object",
+    "properties": {
+      "plans": {
+        "type": "array",
+        "items": {
+          "type": "object",
+          "properties": {
+            "name": {"type": "string"},
+            "price": {"type": "number"},
+            "features": {"type": "array", "items": {"type": "string"}}
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+---
+
+## Layer 3: Full API Details
+
+### Scrape Formats
+| Format | Description |
+|--------|-------------|
+| `markdown` | Clean markdown, ideal for LLM consumption |
+| `html` | Parsed HTML |
+| `rawHtml` | Unmodified HTML |
+| `screenshot` | Page screenshot (supports `fullPage`, `quality`, `viewport`) |
+| `links` | All links on the page |
+| `summary` | AI-generated summary |
+| `json` | Structured extraction with schema/prompt |
+| `branding` | Brand identity extraction (colors, fonts, typography) |
+| `changeTracking` | Diff against previous scrape |
+
+### Scrape Actions (interact before scraping)
+Available action types: `wait`, `click`, `screenshot`, `write`, `press`, `scroll`, `scrape`, `executeJavascript`, `generatePDF`
+
+Example: Login then scrape
+```json
+{
+  "url": "https://example.com/login",
+  "formats": ["markdown"],
+  "actions": [
+    {"type": "write", "text": "user@example.com"},
+    {"type": "press", "key": "Tab"},
+    {"type": "write", "text": "password"},
+    {"type": "click", "selector": "button[type='submit']"},
+    {"type": "wait", "milliseconds": 1500}
+  ]
+}
+```
+
+### Location and Language
+```json
+{
+  "url": "https://example.com",
+  "location": {
+    "country": "US",
+    "languages": ["en"]
+  }
+}
+```
+
+### Crawl Options
+| Param | Description | Default |
+|-------|-------------|---------|
+| `maxDiscoveryDepth` | How deep to follow links | - |
+| `limit` | Max pages to crawl | - |
+| `allowExternalLinks` | Follow links to other domains | false |
+| `deduplicateSimilarURLs` | Skip near-duplicate URLs | false |
+| `includePaths` | Only crawl URLs matching these patterns | - |
+| `excludePaths` | Skip URLs matching these patterns | - |
+
+**Warning**: Crawl responses can be very large. Use `map` + `batch_scrape` for better control.
+
+### Map Options
+| Param | Description |
+|-------|-------------|
+| `search` | Filter URLs by search term |
+| `sitemap` | `include`, `skip`, or `only` |
+| `includeSubdomains` | Include subdomains |
+| `limit` | Max URLs to return (up to 100k) |
+| `ignoreQueryParameters` | Deduplicate by path |
+
+### Cost Reference
+| Operation | Credits |
+|-----------|---------|
+| Search (10 results) | 2 |
+| Basic scrape | 1 per page |
+| PDF parsing | 1 per PDF page |
+| Enhanced proxy | +4 per page |
+| JSON mode (structured extraction) | +4 per page |
+| Map | 1 |
+
+### Caching
+- Default `maxAge`: 172800000ms (2 days)
+- Set `maxAge: 0` for always-fresh
+- Set `storeInCache: false` to skip caching
+- `changeTracking` format bypasses cache
+
+### Rate Limits and Retries
+- Built-in exponential backoff on rate limits
+- Configurable via env vars:
+  - `FIRECRAWL_RETRY_MAX_ATTEMPTS` (default: 3)
+  - `FIRECRAWL_RETRY_INITIAL_DELAY` (default: 1000ms)
+  - `FIRECRAWL_RETRY_MAX_DELAY` (default: 10000ms)
+  - `FIRECRAWL_RETRY_BACKOFF_FACTOR` (default: 2)
+
+### Agent Feature (New)
+Autonomous web data gathering. Describe what you need, it searches, navigates, and extracts.
+```json
+{
+  "prompt": "Find the pricing plans for Notion"
+}
+```
+Not available via MCP tools yet, API-only at `POST /v2/agent`.
+
+### Async Operations
+- `crawl` and `batch_scrape` are async. They return an operation ID.
+- Check status with `firecrawl_check_crawl_status` or `firecrawl_check_batch_status`.
+- Results expire after 24 hours.
+
+---
+
+## When NOT to Use Firecrawl
+
+| Situation | Use Instead |
+|-----------|-------------|
+| Searching local files | `Grep`, `Glob` |
+| Reading a file on disk | `Read` |
+| GitHub-specific operations (PRs, issues) | `gh` CLI or GitHub MCP tools |
+| Authenticated service (Google Docs, Jira) | Service-specific MCP tool |
+
+## Setup
+- Package: `firecrawl-mcp` (npm, stdio transport)
+- Config: `~/.claude.json` under mcpServers
+- API key: `FIRECRAWL_API_KEY` env var
+- Docs: https://docs.firecrawl.dev