Run autonomous multi-step research with cited sources

Runs autonomous Gemini Deep Research tasks that plan, search, read, and synthesize information into comprehensive, cited reports - covering how to start a run, poll its progress, and collect the final report.

Use it when a question needs autonomous multi-step research with cited sources (market analysis, literature reviews, competitive scans), when a quick web search isn't enough and a structured, source-grounded report is required, or specifically to start a Gemini Deep Research run, poll it, and collect the result. Named best-use cases: market analysis and competitive landscaping, technical literature reviews, due diligence research, historical research and timelines, and comparative analysis of frameworks, products, or technologies. Before starting a job, show the user the exact query, the fact it will be sent to Google's Gemini service, the expected cost range, and the output destination, and start only after explicit approval - never include private workspace material, credentials, personal data, or confidential customer information in a query, and redact proprietary or personal material before requesting approval.

Requires Python 3.8+, the httpx dependency (pip install -r requirements.txt), and a GEMINI_API_KEY environment variable from a Gemini API key obtained at Google AI Studio, set either as an exported variable or a .env file in the skill directory:

export GEMINI_API_KEY=your-api-key-here

Core usage runs through scripts/research.py with a --query flag, and supports a structured --format string, --stream for real-time progress, --no-wait to start without blocking, --status <interaction_id> to check a running job, --wait <interaction_id> to wait for completion, --continue <interaction_id> to elaborate on a previous research run, and --list to see recent research. Output defaults to a human-readable markdown report, with --json for structured programmatic data or --raw for the unprocessed API response. Exit codes are 0 for success, 1 for an error (API error, config issue, timeout), and 130 for user cancellation (Ctrl+C).

Wraps the Gemini Deep Research API directly: each task takes 2-10 minutes and costs $2-5 depending on complexity, consuming roughly 250k-900k input tokens and 60k-80k output tokens - each job is a paid, third-party API request, and the listed cost estimate is not a spending authorization since pricing and availability can change. Reports may contain incomplete, stale, or incorrect citations, so consequential claims should be verified against primary sources. The typical workflow is: run the query, tell the user the estimated 2-10 minute wait, monitor with --stream or poll with --status, return the formatted result, and use --continue for any follow-up questions. The API key must stay local and must never be committed, printed, or sent in a query.

Anyone who needs a structured, source-grounded research report - market analysts, technical reviewers, due-diligence teams - rather than a quick web search, and who is comfortable with a paid third-party API call after explicit cost and query approval.