notebooklm-research-orchestrator

name	notebooklm-research-orchestrator
description	Operate the logged-in NotebookLM UI through a visible Chromium/CDP browser session, preferring Comet and falling back to Chrome, Brave, Edge, Vivaldi, Opera, or Arc for source collection, Fast/Deep Research, YouTube/web URL import, chat synthesis, and Studio artifacts.

NotebookLM Research Orchestrator

Use this skill when the user wants a NotebookLM-centered research workflow in an already logged-in Chromium-based browser session: collect relevant sources, import them into NotebookLM, ask source-grounded questions, and create Studio artifacts.

Operate only through visible UI and Chrome DevTools Protocol. Do not read cookies, localStorage, browser profile databases, keychain items, session tokens, hidden credentials, or private browser storage.

Inputs

• Research question or exact source-discovery query.
• Requested source modes: fast-research, deep-research, youtube, human-experience-youtube, websites, files, or all.
• Optional source budget: target source count, max query attempts, max wait minutes, relevance threshold.
• Optional browser route: auto, comet, chrome, brave, edge, vivaldi, opera, arc, or an explicit CDP --port.
• Optional output mode: collect-only, research-answer, or artifact-generation.
• Optional artifact targets: mind-map, data-table, report, slides, infographic, audio-overview, video-overview, or flashcards.

Non-Goals

• Do not bypass NotebookLM limits, subscription gates, CAPTCHA, Google account gates, or copyright restrictions.
• Do not treat search results, discovered URLs, or pasted URLs as used context until NotebookLM imports them.
• Do not silently replace Deep Research with Fast Research. Report fallback only when the user allows it or a timeout occurs.
• Do not continue collecting sources after context_exhausted; smaller relevant context is better than noisy volume.

Required References

Read these before acting:

1. references/operation.md for the workflow.
2. references/ui-operating-guide.md for NotebookLM UI controls, states, success criteria, and recovery.
3. references/evidence-contract.md for required proof.
4. references/failure-modes.md for closed failure modes and retry limits.
5. references/production-skill-architecture.md before claiming production-candidate or release readiness.

Required Tool Check

Before UI automation, verify the local browser route:

node scripts/notebooklm-cdp.mjs verify --browser auto

auto scans supported Chromium/CDP routes in this order: Comet, Chrome, Brave, Edge, Vivaldi, Opera, Arc. Prefer a reachable endpoint that already has a visible notebooklm.google.com target. If Comet CDP is unavailable but Chrome/Brave/Edge/Vivaldi/Opera/Arc CDP is reachable, record the fallback and continue.

If no CDP endpoint is reachable, return tool_unavailable. Relaunching or restarting any browser, closing user windows, using a temporary profile, or spending quota on Deep Research requires explicit user approval in the current task.

Workflow Routing

Use the smallest workflow that satisfies the user:

• collect-only: create/open notebook, import Fast/Deep Research and/or URL sources, then stop with a source report.
• research-answer: import sources, ask the research question in NotebookLM chat, wait for completion, copy the answer through NotebookLM's answer copy button, and record citation status.
• artifact-generation: import sources, optionally ask chat, then generate requested Studio artifacts and record completion.

Deep Research is long-running. When requested, submit it once, record submitted -> running, poll visible UI for the configured wait budget, and click Import only when importable results appear.

Human Experience YouTube Requirement

For practical, comparative, product-selection, implementation, UI/UX, operational, software, business-tool, or workflow research, web/Fast/Deep Research alone is not enough. The skill must separately scout YouTube for relevant human-experience videos: walkthroughs, tutorials, reviews, postmortems, migration stories, conference talks, demos, comparisons, and practitioner discussions.

Run YouTube scouting unless one of these is true:

• the user explicitly opts out of YouTube/video sources;
• the topic is clearly not experience-based, such as a narrow legal definition, math proof, or purely private-file analysis;
• two consecutive YouTube query variants produce fewer than two relevant non-duplicate videos, in which case stop as context_exhausted/youtube.

Accepted videos must be imported into NotebookLM through Add sources -> Websites before they count as context. If no videos are imported, the final report must say why.

Source Acceptance Rule

A source is accepted only when all are true:

1. Import or Insert was enabled and clicked.
2. The source count increased or a specific source title appeared in the left source list.
3. The action log records the before/after state.

YouTube import is accepted only when all are true:

1. URL text was physically present in the Website and YouTube URLs textarea.
2. Insert became enabled.
3. Insert was clicked.
4. The video title appeared in NotebookLM's source list or the failure was logged as unsupported_source.

Evidence Rule

Every run must write an NDJSON action log and a final JSON report. Required fields are defined in references/evidence-contract.md.

Minimum evidence:

• CDP browser version and sanitized NotebookLM target id.
• Exact query variants and selected mode.
• Accepted and rejected sources with reasons.
• source_count_before and source_count_after for every import batch.
• URL textarea state for website/YouTube import.
• YouTube human-experience query variants, accepted/rejected video cards, and imported video titles when the topic is experience-based.
• Deep Research state transitions and wait duration when used.
• Chat answer copy-button extraction status or artifact completion status when requested.
• Final stop reason.

Scripts

• scripts/notebooklm-cdp.mjs verify --browser auto: discover a reachable Chromium/CDP browser and list visible NotebookLM/YouTube targets.
• scripts/notebooklm-cdp.mjs create-notebook: create a new NotebookLM notebook from the visible homepage.
• scripts/notebooklm-cdp.mjs inspect: inspect a NotebookLM target without reading browser storage.
• scripts/notebooklm-cdp.mjs fast-research: submit NotebookLM Fast Research, wait for importable results, click Import, and verify source count.
• scripts/notebooklm-cdp.mjs youtube-scout: search YouTube in a separate visible target and save accepted/rejected video URLs for later NotebookLM import.
• scripts/notebooklm-cdp.mjs insert-urls: paste website/YouTube URLs into Add sources -> Websites and verify Insert.
• scripts/notebooklm-cdp.mjs monitor-deep: poll a submitted Deep Research run and import when possible.
• scripts/notebooklm-cdp.mjs ask-chat: ask NotebookLM chat after imported-source evidence exists, then prefer NotebookLM's answer copy button for clean extraction. DOM answer text is dirty fallback only and does not satisfy completion unless explicitly allowed.
• scripts/notebooklm-cdp.mjs artifact-status: inspect Studio artifact readiness.

The scripts are helpers, not a bypass. If visible UI changes, report regression_detected and stop after one selector rescan.

Completion Gate

Do not call a run complete unless the requested output mode has matching evidence:

• collect-only: imported source inventory and stop reason.
• research-answer: NotebookLM chat answer completed and extracted through the answer copy button, or partial_output recorded with dirty DOM fallback quarantined.
• artifact-generation: each requested artifact is completed, timeout, permission_blocked, quota_blocked, or partial_output.

Do not call the skill production-ready unless lint, dependency verification, evals, package sanitation, and final review artifacts exist under reviews/ or the release workspace.