/gemini-research

Create notebooks, add sources, run research, query content, and generate artifacts using the NotebookLM MCP server (mcp__notebooklm-mcp__*). This is a direct API approach — no browser automation needed.

Triggers on: gemini research, Gemini Deep Research, NotebookLM, notebook research, add sources to notebook, generate podcast, create audio overview, study materials, slides, quizzes, and source-grounded reports.

🔑 DRIVE-WORKSPACE RULE (Etan, standing — never violate): Etan's Gemini has his Google Drive workspace CONNECTED. Every deep-research prompt must REFERENCE the relevant Google Doc(s) by NAME (e.g. "ground this in my 'Context Strategy' doc in my Drive") so Gemini pulls them itself via the Drive connector. NEVER instruct Etan to attach/upload files — he should never have to attach anything. Reference doc names, not attachments.

ROUTING — Three Gemini/NotebookLM UIs (READ FIRST)

This skill owns TWO of three distinct Gemini research UIs. Picking the wrong one silently burns a session — they look similar but have incompatible prompting styles.

Decision tree:

• Content is ALREADY in Drive → Brain Drive side panel (/braindrive)
• Need broad WEB research, one-shot → gemini.google.com Deep Research (see "Gemini Deep Research (Standalone UI)" section below)
• Need persistent notebook + artifacts → NotebookLM MCP (rest of this skill)

Anti-patterns observed (2026-04-11): a 1800-word structured prompt wasted on the side panel (truncated); a 5-line short prompt wasted on gemini.google.com Deep Research (missed context); NotebookLM MCP setup run for a task that only needed a 3-line side-panel query. Match the prompt length and setup cost to the UI.

Gemini Deep Research (Standalone UI at gemini.google.com)

Separate from NotebookLM. Distinct interaction model. Use this when you need broad WEB research with source gathering and a plan-review flow BEFORE the research runs.

When to use gemini.google.com Deep Research vs NotebookLM:

• gemini.google.com → one-shot broad web research, won't revisit, want the plan-review step, want to edit the research plan before it runs
• NotebookLM → persistent notebook, curated sources, repeat queries, generate artifacts (audio overview, slides, quizzes, etc.)

Prompt template for gemini.google.com Deep Research:

# Research goal
<one-sentence what you need to learn>

# Grounding (Drive workspace — CONNECTED; REQUIRED block)
Ground this research in the following docs from my Google Drive — pull them
yourself via the connected Drive workspace; do NOT ask me to attach anything:
- "<Exact Google Doc name 1>"
- "<Exact Google Doc name 2>"
<If no Drive doc applies, write "None — web-only research" so the omission is
deliberate, not an oversight. Never replace this block with an attach/upload ask.>

# Scope
<what TO include — specific domains, timeframes, primary vs secondary sources>

# Anti-scope
<what NOT to include — common tangents, outdated info, marketing content>

# Evaluation criteria
<how I'll judge the findings — what makes a good source, what's disqualifying>

# Prior art I already have
<optional: what BrainLayer / local context already says so the research doesn't re-cover it>

# Desired output
<structure: executive summary, N findings, confidence level, sources, etc.>

🔒 EMIT-GATE — Drive-Workspace compliance (BLOCKING — run before emitting ANY prompt)

A deep-research prompt is not allowed to leave this skill until it passes the Drive-Workspace gate. The rule is mechanically enforced — do not eyeball it:

# Scan the prompt you are about to emit (file or stdin). Exit 1 = FAIL.
bash skills/golem-powers/_shared/research/drive-grounding-gate.sh /path/to/R{NN}-prompt.md
# or:  printf '%s' "$PROMPT_TEXT" | bash skills/golem-powers/_shared/research/drive-grounding-gate.sh -

• FAIL (gate finds attach / upload / drag / "add the file" aimed at Etan) → do NOT emit. Rewrite the offending lines to REFERENCE the doc(s) by NAME inside the # Grounding block, then re-run the gate. Repeat until it PASSes.
• PASS → the prompt grounds itself by doc-name; safe to emit.

This gate also runs over the user-facing dispatch message, not just the prompt body — telling Etan "attach the Drive folder" in the hand-off message is the same violation. Both must pass.

Interaction steps:

1. Paste prompt → get research plan
2. Return the generated plan to the prompt author for an explicit START / EDIT verdict before firing the research. Do not click Start Research on your own plan interpretation.
3. Edit the plan if needed (add angles, remove irrelevant ones, tighten focus)
4. Click Start Research → wait (Fast: ~1 min, Thinking: ~5 min, Pro 3.1: 10–15 min)
5. Read report → export to Google Doc if it needs to land in Drive
6. brain_store conclusions (always) + brain_digest raw report for entity/relation extraction (standards/deep-research-brainlayer.md). brain_digest was fixed in PR #100 (2026-03-22) per ~/.claude/CLAUDE.md BrainLayer Protocol; if you suspect it's returning stubbed success, fall back to brain_store with the full raw report as the content field and skip the automated extraction step.

Harvest gate: If a report claim cites one of YOUR OWN briefs/prompts/plans as evidence, open the actual brief text and cross-check the claim before accepting or relaying it. Two 2026-06-05 catches came from fabricated premises in research artifacts: a hallucinated Drive doc in R01's plan and a nonexistent delta-brief mandate in R02's report.

Dispatch harvest contract (required — see /research-lifecycle): Every research dispatch records at dispatch time:

Includes researches Etan fires himself in gemini.google.com or NotebookLM UI (fire=Etan standing rule) — adapters name who harvests and where results export back to the fleet. Research without a harvest path = parked, not done.

Anti-patterns:

• Telling Etan to attach/upload a doc — his Drive workspace is CONNECTED; the prompt must reference the doc by NAME so Gemini pulls it itself. This is gate-enforced (drive-grounding-gate.sh) — a prompt with attach/upload language does not get emitted.
• Skipping the prompt-author START/EDIT gate → the research runs on the raw plan, often with blind spots you could have caught
• Treating this like NotebookLM — it's NOT a persistent notebook, the research run is ephemeral unless you export
• Using for content already in Drive — that's /braindrive territory, cheaper and faster
• Using gemini.google.com for a task that will need multiple follow-up queries on the same sources — use NotebookLM instead

Quick Reference

Auth

If you get authentication errors, run nlm login via Bash first — this is the automated method. Only use save_auth_tokens as a fallback if the CLI fails. To switch Google accounts: nlm login switch <profile>.

Core Workflows

Default Workflow: Drive-Sync Research

Drive is the source of truth. NotebookLM consumes the same Drive project that /claude-desktop-research uses.

1. Verify account first:
   bash skills/golem-powers/_shared/research/verify-account.sh --expect research-account@example.com

2. Ensure Drive folders exist:
   python3 skills/golem-powers/_shared/research/drive-paths.py ensure-project-folders <project>

3. Resolve notebook state:
   ~/.golems/research-state.json maps <project> -> notebook_id
   - reuse the notebook when it already exists
   - create a new notebook when the project is new

4. Load Drive context into NotebookLM:
   - list context files from Drive/Research/<project>/context/
   - add each file into the notebook
   - for raw markdown/text files, download from Drive then upload as file sources

5. Run Drive-backed research:
   research_start(query=<prompt from Drive/prompts/>, source="drive", notebook_id=<id>)
   - if the tool/UI returns a research PLAN before execution, return that PLAN
     to the prompt author and wait for `START` / `EDIT` before firing
   research_status(notebook_id, task_id=<task>, max_wait=60)
   research_import(notebook_id, task_id=<task>) when sources are found

6. Query the notebook for the synthesized answer

7. Write the result to:
   Drive/Research/<project>/results/R{NN}-gemini-result.md

Wrapper (live mode needs both variables, and stops with an error if either is unset):

export GEMINI_RESEARCH_PROFILE=<nlm profile>   # the name you gave `nlm login --profile`
export RESEARCH_ACCOUNT=<google account>       # Drive/NotebookLM must be signed in as this
bash skills/golem-powers/gemini-research/scripts/drive-sync.sh --project cmux --prompt R36-R38-cmux-mobile-prompts.md

Notebook workflows and patterns

Create a notebook, run Deep Research, generate artifacts, manage sources, keep notes, share, plus the end-to-end pipeline, the proven 96-file local-context pattern and batch source addition: references/notebooklm-workflows.md. Number local context files per the shared scheme in skills/golem-powers/_shared/research/context-numbering.md (never restate it here).

Critical Gotchas (from real session failures, April 4 2026)

Sources ≠ Prompts (NP1 — #1 mistake)

Sources are CONTEXT. Queries are QUESTIONS. Never upload a research prompt as a source.

• A research prompt (e.g., "Investigate BrainLayer search improvements") is a QUERY you send to notebook_query or research_start
• Context files (architecture docs, code samples, prior research) are SOURCES you upload via source_add
• Evidence: orcClaude uploaded R75 research prompts as NotebookLM sources. User: "Why did you upload this file? That's something you send to research on Notebook LM."

Account Verification Before Creation (NP4)

Check which Google account the MCP is connected to BEFORE creating notebooks.

The MCP may be connected to a different Google account than the one with the AI Pro subscription. Evidence: notebook created on maintainer@example.com instead of research-account@example.com, causing sources to silently fail. To check: server_info() or notebook_list() — verify the account matches the intended user. To switch: nlm login switch <profile> (or nlm login --clear --profile <name> for fresh auth).

File Type Restrictions (NP3 — complete list)

Workaround for blocked types: Rename to .txt (e.g., search.py → search.py.txt) or use source_type="text" via MCP to paste file contents directly. Evidence: 52 code files had to be renamed during April 4 session.

Deep Research — shared engine, different UIs (NP5 — updated 2026-04-11)

NotebookLM Deep Research and gemini.google.com Deep Research share the underlying research engine, but they are distinct UIs with different interaction models. The old claim "you never need to go to gemini.google.com separately" was wrong — each UI has real advantages:

• NotebookLM Fast: ~30s, ~10 sources (quick directional checks)
• NotebookLM Deep: ~5 min, ~40 sources (comprehensive, web-crawling)
• gemini.google.com Pro 3.1: 10–15 min (most comprehensive single run)

Long-prompt workaround for NotebookLM: The "Search the web" bar has character limits. Add the prompt as a note() in the notebook, then send a shorter query referencing it. Or use gemini.google.com Deep Research instead (no char limit).

Brain Drive side panel is a THIRD UI — see the "ROUTING" section at the top of this skill. It's NOT Deep Research — it's cross-file summarization against files already in Drive. Owned by /braindrive.

Important Notes

• Source limits: 50 sources per notebook, 500K words total. Plan source selection carefully.
• Confirm required: Destructive operations (delete, share, studio_create) require confirm=True. Always ask the user before confirming.
• Studio polling: After studio_create, the artifact generates asynchronously. Poll studio_status — audio takes 1-3 min, video takes 3-10 min.
• Query vs Research: notebook_query asks about EXISTING sources in the notebook. research_start searches the WEB or DRIVE for NEW sources.
• File types: See "File Type Restrictions" section above for complete list and workarounds.
• Drive doc types: When adding Drive docs, specify doc_type: doc, slides, sheets, or pdf.
• Language: Most tools accept a language parameter (BCP-47 code: en, he, es, fr, de, ja).
• Silent failures: source_add may return success but sources don't persist if the MCP is connected to the wrong Google account. Always verify after upload.

Workflows and references

• references/notebooklm-workflows.md: every notebook workflow (create, Deep Research, artifacts, sources, notes, sharing) and the common patterns.
• Drive sync: scripts/drive-sync.sh / scripts/drive_sync.py (tests in scripts/__tests__/).