# Domain Presets

Curated domain lists for Exa `includeDomains` filter, organized by intent.

## Code & Development

### General code
```
github.com, stackoverflow.com, dev.to, medium.com
```

### JavaScript/TypeScript
```
github.com, stackoverflow.com, developer.mozilla.org, nodejs.org, typescriptlang.org, npmjs.com
```

### Python
```
github.com, stackoverflow.com, docs.python.org, pypi.org, realpython.com
```

### Rust
```
github.com, stackoverflow.com, doc.rust-lang.org, crates.io, docs.rs
```

### Go
```
github.com, stackoverflow.com, go.dev, pkg.go.dev
```

### React ecosystem
```
github.com, stackoverflow.com, react.dev, nextjs.org, vercel.com
```

### DevOps / Infrastructure
```
github.com, stackoverflow.com, docs.docker.com, kubernetes.io, terraform.io, aws.amazon.com
```

## Documentation

### Official docs (general pattern)
Use Exa search to find: `"{library} official documentation site"`
Then crawl with `crawling_exa` + subpages.

### Common doc sites
```
docs.python.org, developer.mozilla.org, react.dev, nextjs.org, 
docs.docker.com, kubernetes.io, docs.aws.amazon.com, cloud.google.com/docs,
learn.microsoft.com, docs.github.com, vercel.com/docs
```

## Debug / Troubleshooting

```
stackoverflow.com, github.com/issues, github.com/discussions,
serverfault.com, superuser.com, askubuntu.com
```

## News / Tech

```
techcrunch.com, theverge.com, arstechnica.com, hackernews.com,
wired.com, reuters.com, bloomberg.com
```

## Research / Academic

Use `category: "research paper"` in `web_search_advanced_exa` instead of domain filter.
Fallback domains:
```
arxiv.org, scholar.google.com, semanticscholar.org, 
acm.org, ieee.org, nature.com, science.org
```

## Business / Companies

Use `category: "company"` in `web_search_advanced_exa`.
Fallback:
```
linkedin.com, crunchbase.com, pitchbook.com, 
glassdoor.com, builtin.com
```

## People

Use `category: "people"` in `web_search_advanced_exa`.
Fallback:
```
linkedin.com, twitter.com, github.com
```

## Usage

When {mode} matches an ecosystem detected in the query:
1. Look up matching preset above
2. Pass as `includeDomains` in Exa call
3. Only if no `--domain` flag was explicitly set by user (user flags override presets)

# /websearch - Full guide

## Quick usage

```
/websearch <query>                    Quick search
/websearch --deep <query>             Deep multi-pass research
/websearch --code <query>             Code examples, API, libs
/websearch --docs <lib>               Official documentation for a lib
/websearch --debug <error>            Paste an error, find the fix
/websearch --news <topic>             Recent news
/websearch --compare <A> vs <B>       Side-by-side comparison
/websearch --research <topic>         Academic papers
/websearch --similar <url>            Pages similar to a URL
/websearch --info                     This guide
```

## Modes in detail

### Quick search (default)
```
/websearch how does gRPC work
```
Single pass, 5 results, answer in bullet points with sources.
Best for fast factual questions.

### Deep research (`--deep`)
```
/websearch --deep state management React 2026
```
Breaks the query into 3-5 sub-queries by angle:
- Definitional, practical, comparative, recent, expert.
- Evaluates results, identifies gaps.
- Iterates up to 3 passes max.
- Produces a structured report with thematic sections.
Usage: technical decisions, deep monitoring, topic exploration.

### Code (`--code`)
```
/websearch --code FastAPI middleware authentication
/websearch --code Python asyncio gather timeout
```
Uses `get_code_context_exa`, optimized to:
- Extract real code snippets (GitHub, SO, official docs).
- Code-first results, explanation second.
Usage: find an API example, an implementation pattern.

### Documentation (`--docs`)
```
/websearch --docs prisma
/websearch --docs next.js app router
```
Two-step workflow:
1. Find the official docs site.
2. Crawl the relevant page + linked sub-pages.
Usage: understand a specific API, read the docs without leaving the terminal.

### Debug (`--debug`)
```
/websearch --debug "TypeError: Cannot read properties of undefined (reading 'map')"
/websearch --debug CORS error preflight blocked
```
Smart workflow:
1. Clean the error (strip paths, timestamps, user data).
2. Search the exact error first.
3. Broaden to semantic if not enough results.
4. Target Stack Overflow, GitHub Issues.
Format: solution first, explanation second.

### News (`--news`)
```
/websearch --news AI agents
/websearch --news --after 2026-05-01 Claude Code
```
Filters by Exa "news" category.
Default: last 7 days.
Format: timeline, most recent first.

### Compare (`--compare`)
```
/websearch --compare React vs Vue vs Svelte
/websearch --compare Prisma vs Drizzle
```
Runs one parallel query per option.
Produces a comparison table + verdict.

### Research (`--research`)
```
/websearch --research transformer architecture scaling laws
```
Filters by Exa "research paper" category.
Results from arxiv, ACM, IEEE, Nature.
Format: summary + key findings + methodology.

### Similar (`--similar`)
```
/websearch --similar https://blog.example.com/great-article
```
Finds pages semantically similar to a given URL.

## Filters

Combinable with all modes:

```
--after <date>        Results after this date
                      Formats: 2026-05-01, "last week", "3 days ago"

--before <date>       Results before this date

--domain <d>          Restrict to domains (comma-separated)
                      Ex: --domain github.com,stackoverflow.com

--exclude <d>         Exclude domains
                      Ex: --exclude reddit.com,medium.com

--fresh               Force live crawl (real-time content)
                      Exa recrawls pages instead of using the cache

--locale <CC>         Localized results (ISO country code)
                      Ex: --locale FR, --locale US

-n <num>              Number of results (default: 5, max: 20)
```

## Output

```
--save <file>         Save the report as markdown
                      Ex: --save ./report-react.md

--json                Structured JSON output (for piping)

--full                Full text instead of highlights
                      More tokens but more context
```

## Daily usage examples

```bash
# Quick question
/websearch what is the default port of PostgreSQL

# Find a snippet
/websearch --code React useOptimistic example

# Debug an error
/websearch --debug "ECONNREFUSED 127.0.0.1:5432"

# Read a lib's docs
/websearch --docs zod validation

# Tech monitoring
/websearch --news --after "last week" Anthropic Claude

# Technical choice
/websearch --compare Bun vs Deno vs Node.js 2026

# Deep research for an article
/websearch --deep --save report.md AI impact on software development

# Recent papers
/websearch --research --after 2026-01-01 LLM code generation evaluation

# Find similar content
/websearch --similar https://exa.ai/blog/search-for-ai
```

## How it works

The skill uses 4 Exa MCP tools:

| Tool | Usage |
|-------|-------|
| `web_search_exa` | General semantic search |
| `get_code_context_exa` | Code, API, technical docs |
| `web_search_advanced_exa` | Category filters (news, research, company) |
| `crawling_exa` | Full read of a URL + sub-pages |

The workflow adapts automatically:
- The Exa tool used per mode.
- The targeted domains per detected ecosystem.
- The query phrasing (semantic, not keywords).
- The output format per search type.

`--deep` mode: iterates up to 3 passes with gap analysis between each pass.
All results are cited inline with `[source](url)`.

# Query Formulation Patterns

Exa uses semantic search - describe the ideal page, not keywords.

## Core principle

NOT: `"React vs Vue"`
YES: `"blog post comparing React and Vue performance and developer experience"`

NOT: `"python async"`
YES: `"Python asyncio tutorial with practical examples for web scraping"`

## Patterns by mode

### quick
- Keep user's query mostly intact
- Add context if too short: "how to {query} with examples"
- Remove noise words but keep semantic meaning

### deep (decomposition)
From a single query, generate 3-5 sub-queries:

| Angle | Pattern |
|-------|---------|
| Definitional | "comprehensive guide to {topic} fundamentals" |
| Practical | "how to implement {topic} real world examples production" |
| Comparison | "{topic} compared to alternatives tradeoffs" |
| Recent | "{topic} latest developments news 2025 2026" |
| Expert | "{topic} best practices lessons learned from production" |

### code
- Prefix with language/framework when known
- "Python FastAPI middleware authentication example code"
- "{language} {library} {specific API} usage example"
- For errors: quote the exact error string

### docs
- "{library} official documentation {specific feature}"
- "{library} API reference {class or method name}"
- "{library} migration guide from {version} to {version}"

### debug
1. Clean the error first:
   - Remove file paths, line numbers, timestamps
   - Keep: error type, message, key identifiers
2. Search exact: `"{ErrorType}: {message}"`
3. If no results, generalize: "how to fix {ErrorType} in {framework}"

### news
- "{topic} news latest announcements"
- Add time context: "released", "announced", "launched"

### compare
- Split into per-target queries:
  - "{target A} features pros cons benchmarks {year}"
  - "{target B} features pros cons benchmarks {year}"
- Then: "{A} vs {B} comparison developer experience"

### research
- Use academic language: "study", "analysis", "framework", "evaluation"
- "{topic} research paper empirical study analysis"
- Include field: "machine learning {topic} benchmark evaluation"

## Anti-patterns

- No boolean operators (AND/OR) - Exa ignores them
- No site: operators - use includeDomains filter instead
- Don't use keywords like a search engine - write natural descriptions
- Don't be too short (< 3 words) - add context
- Don't be too long (> 30 words) - keep focused

## Query enhancement

If user query is very short (< 5 words), enhance:
1. Detect topic domain (code, business, news, academic)
2. Add context words per domain
3. Keep user's original intent

Example:
- User: "redis caching" → "Redis caching patterns best practices with code examples"
- User: "CORS error" → "how to fix CORS error in web application browser console"
- User: "transformer architecture" → "transformer architecture explained with diagrams neural network deep learning"

# step 00 triage

Parse the requested mode, filters and output. Default to a focused quick search. No separate classification ceremony. Use the schema of the actual available Exa tool.

The current SKILL.md owns the workflow policy. User consent is required
before any agent, reviewer or advisor. No automatic validation sessions
for prose; no continuation after a user stop or completed result.

# step 01 search

Search the relevant official or primary sources. Use code context for API/debug questions. Prefer useful excerpts; crawl a decisive passage when needed. Do not invent category values or send unsupported parameters.

The current SKILL.md owns the workflow policy. User consent is required
before any agent, reviewer or advisor. No automatic validation sessions
for prose; no continuation after a user stop or completed result.

# step 02 deep

Only --deep needs iterative gap filling. Stop when answered, saturated, or after three passes. Do not search every perspective by habit or spawn research agents without consent.

The current SKILL.md owns the workflow policy. User consent is required
before any agent, reviewer or advisor. No automatic validation sessions
for prose; no continuation after a user stop or completed result.

# step 03 report

Answer the question with supporting citations, dates and uncertainty. Do not dump raw response metadata. Save a document only if requested. No additional research after adequate evidence is obtained.

The current SKILL.md owns the workflow policy. User consent is required
before any agent, reviewer or advisor. No automatic validation sessions
for prose; no continuation after a user stop or completed result.