Deep Research
In Pi with the web_research tool active, use that tool, passing outputPath when creating a report. In every other harness, run scripts/deep-research with EXA_API_KEY set.
Rules
- Exa is the research source. Substitute a general web search only when Exa is unavailable and the user approves the fallback.
- Write
findings.mdto the path the caller requested, exactly. - Cite sources for material claims. Provider payloads go in the sidecar JSON (
findings.raw.jsonbeside the report by default), never inline. Sanitize evidence excerpts: source-page headings must not render as headings. - Once the report and its sidecar exist, run
validateand stop. No local reproduction, benchmarks, tests, code inspection, or implementation unless the caller asked for it. - A missing
EXA_API_KEYfails with setup instructions. Set it on this package's Customize tab in the kendex app, or by hand in the project's private env file —.env.localunlessKENDEX_ENV_FILEnames another. The value may be a key or a 1Passwordop://vault/item/fieldreference when theopCLI is installed and signed in. - Every mode uses the same findings sections. Record mode and source counts in
## Research Metadata.
Running
bash.agents/skills/deep-research/scripts/deep-research report "question" --mode standard --output path/to/findings.md .agents/skills/deep-research/scripts/deep-research report --query-file prompt.txt --context-glob 'context-*.md' --mode full --output findings.md .agents/skills/deep-research/scripts/deep-research json "question" --output raw.json .agents/skills/deep-research/scripts/deep-research validate findings.md findings.raw.json .agents/skills/deep-research/scripts/deep-research doctor
deep-research help lists every flag. Exa /search caps the settings behind them: numResults 1-100, text.maxCharacters 1-10000, additionalQueries at most 10.
| Mode | Exa type | Results | Text cap | Timeout | Synthesis |
|---|---|---|---|---|---|
lite | deep-lite | 15 | 10k chars/result | 5 min | Not requested, evidence brief only |
standard | deep-reasoning | 50 | 10k chars/result | 10 min | Requested via outputSchema |
full | deep-reasoning | 100 | 10k chars/result | 30 min | Requested, per query |
standard is the default; lite for fast spikes, full for strategic or high-risk decisions. --type, --num-results, and --text-max-characters override a mode's defaults.
--additional-query (repeatable) reaches Exa as additionalQueries within the single request under lite and standard, and as one request per query with URLs deduped across responses under full.
--include-domain is a hard host filter, not a quality filter: --include-domain github.com admits every repo on it and excludes everything else. Name authoritative projects and organizations in the query text for quality; audit the returned source list either way.
Validation
bash.agents/skills/deep-research/scripts/deep-research validate path/to/findings.md path/to/findings.raw.json
Prints {ok, errors, warnings, mode, synthesis, queryCount}; exits 0 when there are no errors. Checks structure only: required sections present, sidecar parses, query-expansion metadata self-consistent, synthesized answer present for modes that requested one.
Read for these yourself:
- Claims the cited sources contradict. Spot-check material numbers against the sidecar source text.
- Off-topic sources that share an acronym or name with the subject.
- Recommendations with no claim-level support in Evidence and Sources.
- Results generalized past what the source established.
Findings format
templates/findings.md carries exactly the sections validate requires, in order. Key Findings holds distinct claims, not a restatement of the summary.
