description:Use when writing or restructuring a tabletop RPG convention one-shot scenario document, or when building/deploying GM-facing apps (consoles, handout/print packs, story readers, device editions) derived from those scenarios. Triggers include "make a version of the con app for <device>", scenario/act/handout authoring, and offline GM PWA deploys.
---
# Convention scenario tooling
Authoring convention one-shot **documents** and shipping the **apps** derived from them.
Distilled from Continuum 2026 (six one-shots, a weekend at the table) — including, honestly,
the parts that were done the hard way.
## The one idea that ties it together
**A convention scenario has one source of truth — the scenario document — and everything else
is a render of it.** Print packs, GM consoles, a phone story reader, and per-device editions
are all downstream. Get the document *structured* (not freeform prose) and the apps fall out
cheaply. Fork the content into parallel copies and every app becomes bespoke, drifting
hand-work.
## Two jobs, two references
- **Writing the scenario** → read [scenario-authoring.md]. The proven section order, the
stand-in-can-run-it-cold constraint, the immovable-clock + pre-written-cuts pacing spine, the
antagonist countdown, and the per-act structure. The logline, the GM's Truth, and the
Player-Experience paragraph are load-bearing — every downstream app needs exactly those.
- **Building/deploying the apps** → read [app-editions-and-deploy.md]. The fork-vs-adapt
decision, the verified rsync→container→Caddy deploy pattern, and the gotchas (service-worker
cache staleness, the Caddyfile inode trap, SSH target) that cost real hours.
## The fork-vs-adapt decision (memorise this)
A "make a version for device X" request is one of three things:
# Convention app editions — fork-vs-adapt, deploy, and the gotchas that cost hours
This is the shipping half. It captures what the Continuum 2026 project got *right*, and —
honestly — what it got *wrong*, verified by watching fresh agents solve the same requests
better than the project actually did.
## The core decision: adapt one source, or build a separate artifact?
A new "make me a version for device X" request is one of three things. Classify it before you build:
| The delta is… | Then… | Real example |
|---|---|---|
| **Presentation only** (colour, motion, density, layout, tap size) | **Adapt one source** — media query or a theme flag. Ship its own URL/container if the device needs one, but the *content and build stay single-source.* | laptop vs tablet → one responsive build, `@media (hover:hover)` for the laptop layer |
| **Build-time divergence the runtime can't express** | **Separate build is justified** — but still fed from the *one* content source. | e-paper needed a non-deferred `<head>` script to clamp `setInterval`/`rAF` against ghosting — a runtime theme toggle can't inject that early. |
| **Different content model or machinery** | **Separate artifact.** Don't drag the unwanted machinery in. | phone story reader (no dice/stats/props) vs interactive consoles → its own tiny app |
**The mistake to avoid: forking for a presentation-only delta.** The laptop layer correctly
stayed one build; if every device had become its own `build-X.mjs`, weekly content edits would
fan out to N hand-maintained bundles.
## The anti-pattern the project actually committed (fix it if you touch this again)
**A hand-copied content store that duplicates the scenario docs.** The phone app's
`pwa/phone/data/*.json` was *distilled by hand* from `scenarios/*.md`. It is a second copy of
narrative that already exists upstream — so **it silently goes stale the moment a scenario is
rewritten** (and scenarios changed almost weekly: Draft 14 errata, Day One v2.0, art/budget
fixes). Every other edition reads the shared con content and only goes stale on *presentation*
bugs; the phone reader can go stale on *content*, invisibly, because nothing links the JSON
back to the Markdown.
**The right shape:** name the extractable fields consistently in the scenario docs (logline,
GM's Truth, Player-Experience/through-line, per-act Goal/Summary/start/next — see
[scenario-authoring.md]) and **generate** the reader's data from them in the build step. One
source, many renders. If you add editions again, this is the highest-value refactor.
## Cross-session drift: the reason five editions exist
No single request was wrong. Each "can you also make one for X?" got a locally-reasonable
"yes." The *sum* was five separate builds + containers + Caddy routes + hub tiles, each a
standing staleness liability — and only ~1–2 were likely used at the table.
**Discipline (the one real rule here):** when the **Nth** variant request arrives, stop and
inventory the whole edition set *before* answering. Ask: does this fold into an existing
build as a theme, or is it genuinely a new content model? Answer the set, not the request.
Fresh agents do this correctly when the existing forks are visible to them — so *make them
visible*: the accretion happens when each request is handled in isolation across sessions.
## The deploy pattern (verified, reusable)
Production VPS `tevans@77.68.99.134` (the `ubuntu` SSH alias exists only on some machines —
from the Mac use `tevans@77.68.99.134` directly). Docker as `tevans`, no sudo. Repo mirrored
at `~/continuum-pwa/` (`pwa/`, `deploy*/`, `apps-hub/`). **Continuum2026 is private → the VPS
has no GitHub creds, so `rsync` the built `dist-*` + the `deploy-*` dir over SSH; never
This is the document format that survived a real convention (Continuum 2026, six one-shots
across a weekend). It is battle-tested and, critically, **structured enough that every
downstream artifact — print packs, GM consoles, a phone story reader — could be generated
or distilled from it.** Write the scenario doc this way and the apps fall out of it cheaply.
Write it as freeform prose and every app becomes bespoke hand-work.
## The governing constraint: a stand-in must be able to run it cold
The single most important property. At a convention the GM can fall through — illness, a
double-booking, a delayed train. Every scenario doc must let a competent stranger run the
game with no prep beyond reading it. This forces:
- A **self-contained system crash-course** in the doc itself ("MASTER RULES (this scenario)"),
not a pointer to a 200-page rulebook. Enough to adjudicate the whole session.
- **One immovable clock** with pre-decided cuts, so a nervous stand-in can't run out of time.
- **The GM's Truth stated plainly and early**, so the runner knows the real story before Act One.
## Section order (use these headings)
1.**Title + logline** — one italic line that is the whole game (`The dead king remembers he was beautiful.`). This becomes the app's hero text; make it earn that.
2.**MASTER RULES (this scenario)** — the crash-course. Structure, max runtime, act weighting (%), and the system reduced to what a stand-in needs to rule fairly. End with a doctrine line: **"Rule once, rule the same all session."**
3.**Event Details** — slot, system, player count, runtime, art style. Flat metadata; also the app's card fields.
4.**Session Timing Guide** — a table: Section · Duration · Cumulative · **GM Checkpoint** (the observable state that means "this section is done"). Then two sub-blocks:
- **Hard rules** — the immovable clock triggers ("the whistle blows at 1:00 whatever the players are doing"). The thing that must happen at the table by a wall-clock time, named as the point of the evening.
- **Pre-written cuts if running late** — numbered, *in the order you'd take them*. Decided in advance, never improvised under pressure.
5.**Plot Summary (GM's Truth — do not share with players)** — the real cosmology, the antagonist's true motive, and **each named NPC's private secret**. This is the block that must be walled off from players in every app.
6.**The countdown***(if there's an offstage threat)* — a table mapping session-clock → where the unseen antagonist is. A pacing engine the GM reads against the party's speed. One of the strongest devices in the format.
7.**Player Experience** — one paragraph on what the players should *feel* and the shape of their arc. Not plot — experience. This is the "through-line" the phone reader surfaces.
8.**Pre-Game Handouts** — table: ID · Description · Format · When Given, linked to the print-ready HTML. Handout IDs (`VC-H00-A`) are the join key between doc, print pack, and console.
9.**Introduction** — three parts: the **pitch** (a read-aloud box), the **dice primer** (teach the system safely *inside the fiction* before it can hurt anyone — "these five rolls ARE the arrival"), and **atmosphere notes** (props on the table, music).
10.**Acts** — each act, same sub-structure (below).
## Per-act sub-structure
- **Goal** — one line: what this act is *for* (the social act; the fight that teaches the loop; the hour you can lose).
- **Summary** — the act in a paragraph.
- **Staging** — the physical setup, **with playtest fixes annotated inline** (`Staging (playtest fix): two locations only — the faces come to the party, five players get scenes without a walking tour`). Keep the fixes; they are the scar tissue that makes it run.
- **Location** — Description · Atmosphere · inline mechanic call-outs (`[SYSTEM: Reaction roll …]`) · art asset ID.
- **The Faces / Foes** — NPCs with just enough to voice and stat them.
- **Trail / triggers** — what moves the story forward here.
- **Story hooks & answered moves** — anticipated player actions and how they land.
- **Pacing note** — how to speed up or slow down *this* act.
- **Handouts** — which handouts appear here.
- For a **climax act**, break into **beats**, and give each beat a **spotlight** — one PC/class whose "key turns exactly once." Distributing the spotlight deliberately is how five players each get their moment in a fixed slot.
## Design theses worth stealing
- **Teach the system inside the fiction**, staged so every player hits a safe failure before it matters.
- **Merge seams**: "the Intro's last five minutes and Act One's first five are the same five." Fewer hard transitions = smoother table.
- **Immovable clock + pre-written cuts** beats improvising cuts under time pressure every time.
- **Annotate playtest fixes in place** rather than silently rewriting — the reasoning is the value.
- **The logline, the GM's Truth, and the Player-Experience paragraph are the three things every downstream app needs.** If those three are sharp, distillation is trivial. Treat them as load-bearing, not flavour.
description:Complete API for Google NotebookLM - full programmatic access including features not in the web UI. Create notebooks, add sources, generate all artifact types, download in multiple formats. Activates on explicit /notebooklm or intent like "create a podcast about X"
---
<!-- notebooklm-py v0.7.3 -->
# NotebookLM Automation
Complete programmatic access to Google NotebookLM—including capabilities not exposed in the web UI. Create notebooks, add sources (URLs, YouTube, PDFs, audio, video, images), chat with content, generate all artifact types, and download results in multiple formats.
## Installation
**From PyPI (Recommended for AI agents — Python-version-aware):**
```bash
pip install "notebooklm-py[browser]"# mandatory; errors must propagate
# [cookies] (rookiepy) is optional and known to FAIL TO BUILD on Python 3.13+.
# Skip it deliberately on 3.13+ rather than swallowing the error — that lets
# *real* install failures (typos, network, PyPI outages) surface for the agent.
if python -c "import sys; sys.exit(0 if sys.version_info < (3, 13) else 1)";then
⚠️ **DO NOT install from main branch** (`pip install git+https://github.com/teng-lin/notebooklm-py`). The main branch may contain unreleased/unstable changes. Always use PyPI or a specific release tag, unless you are testing unreleased features.
**Skill install methods:**
-`notebooklm skill install` installs this skill into the supported local agent directories managed by the CLI.
-`npx skills add teng-lin/notebooklm-py` installs this skill from the GitHub repository into compatible agent skill directories.
- If you are already reading this file inside an agent skill directory, the skill is already installed. You only need the Python package and authentication below.
**CLI-managed install:**
```bash
notebooklm skill install
```
## Prerequisites
**IMPORTANT:** Before using any command, you MUST authenticate:
```bash
notebooklm login # Opens browser for Google OAuth
notebooklm list # Verify authentication works
```
If commands fail with authentication errors, re-run `notebooklm login`.
### CI/CD, Multiple Accounts, and Parallel Agents
For automated environments, multiple accounts, or parallel agent workflows:
**CI/CD setup:** Set `NOTEBOOKLM_AUTH_JSON` from a secret containing your `storage_state.json` contents.
**Multiple accounts:** Use named profiles (`notebooklm profile create work`, then `notebooklm -p work login`). Alternatively, use different `NOTEBOOKLM_HOME` directories per account.
**Parallel agents:** The CLI stores notebook context per profile (`~/.notebooklm/profiles/<profile>/context.json`, with a legacy fallback to `~/.notebooklm/context.json` for the implicit default profile). Multiple concurrent agents that share a profile and use `notebooklm use` can overwrite each other's context — use one of the isolation strategies below.
**Solutions for parallel workflows:**
1.**Always use explicit notebook ID** (recommended): Pass `-n <notebook_id>` (for `wait`/`download` commands) or `--notebook <notebook_id>` (for others) instead of relying on `use`
2.**Per-agent isolation via profiles:**`export NOTEBOOKLM_PROFILE=agent-$ID` (each profile gets its own context file)
3.**Per-agent isolation via home:** Set unique `NOTEBOOKLM_HOME` per agent: `export NOTEBOOKLM_HOME=/tmp/agent-$ID`
4.**Use full UUIDs:** Avoid partial IDs in automation (they can become ambiguous)
## Agent Setup Verification
Before starting workflows, verify auth is in place. **Use `--test --json` (not bare `--json`)** — bare `--json` only proves the cookie file parses; `--test` makes a network call and proves the cookies still authenticate against Google.
1.`notebooklm auth check --test --json` → require BOTH `"status": "ok"` AND `"checks.token_fetch": true`. Bare `"status": "ok"` (without `--test`) is a false-positive trap — a stale cookie file passes the parse check.
2.`notebooklm list --json` → expect valid JSON (may be empty for new accounts).
3.**If auth fails or is missing → run `notebooklm login` first.** This is the primary auth path: opens a browser, the user signs in to Google once, and the resulting `storage_state.json` is reused on every subsequent run. Works on any environment with a display.
- For headless contexts where opening a browser is not feasible, use `notebooklm login --browser-cookies <browser>` instead — extracts the user's already-logged-in cookies from Chrome/Firefox/etc. (requires the `[cookies]` extra; rookiepy may not install on Python 3.13+). Use `chrome::<profile-name-or-directory>` to target one Chromium user-profile, or `firefox::<container-name>` / `firefox::none` to target one Firefox container.
- To survey signed-in Google accounts before picking one: `notebooklm auth inspect --browser <browser>` (read-only; pass `-v` to see which Chromium user-profile each account came from, or `--json` for tooling). Scoped forms such as `notebooklm auth inspect --browser 'chrome::Profile 1'` inspect only that browser profile.
- Re-run step 1 after login to confirm.
4.**If auth was working but cookies went stale** (Google rotated SIDTS, or you signed in fresh in the browser) **→ refresh the active profile in place instead of full re-login:**
-`notebooklm auth refresh` — server-side SIDTS refresh against the existing `storage_state.json`. Cheap and silent; safe to run on a schedule (cron / launchd / systemd) at 15–20 min cadence to keep an unattended profile warm.
-`notebooklm auth refresh --browser-cookies <browser>` — re-extract cookies from a running browser and match them back to the profile's recorded email in `context.json`. Use when the on-disk `storage_state.json` is too stale for the server-side refresh path but you've just signed back into Google in the browser. For Chromium-family browsers with multiple user-profiles (Chrome's `Default`, `Profile 1`, …), refresh fans out across all profiles to find the email — same path as `auth inspect` (issue #571). Use `chrome::<profile-name-or-directory>` when you already know the exact browser profile.
- Both forms preserve the same `--profile` (no new profile is created).
> **Note:** `notebooklm status` reports *context state* (selected notebook); do not use it to verify auth.
## When This Skill Activates
**Explicit:** User says "/notebooklm", "use notebooklm", or mentions the tool by name
**Intent detection:** Recognize requests like:
- "Create a podcast about [topic]"
- "Summarize these URLs/documents"
- "Generate a quiz from my research"
- "Turn this into an audio overview"
- "Create flashcards for studying"
- "Generate a video explainer"
- "Make an infographic"
- "Create a mind map of the concepts"
- "Download the quiz as markdown"
- "Add these sources to NotebookLM"
## Autonomy Rules
**Run automatically (no confirmation):**
-`notebooklm status` - check context
-`notebooklm auth check` - diagnose auth issues
-`notebooklm auth inspect` - list Google accounts visible to a browser (read-only)
-`notebooklm auth refresh` - server-side SIDTS refresh of the active profile (no new profile, no destructive writes)
-`notebooklm auth refresh --browser-cookies <browser>` - re-extract cookies from a browser into the active profile (rebuilds `storage_state.json` for the same `--profile`, not a new one)
-`notebooklm list` - list notebooks
-`notebooklm source list` - list sources
-`notebooklm artifact list` - list artifacts
-`notebooklm language list` - list supported languages
-`notebooklm language get` - get current language
-`notebooklm language set` - set language (global setting)
-`notebooklm artifact wait` - wait for artifact completion (in subagent context)
-`notebooklm source wait` - wait for source processing (in subagent context)
-`notebooklm research status` - check research status
-`notebooklm research wait` - wait for research (in subagent context)
-`notebooklm use <id>` - set context (⚠️ SINGLE-AGENT ONLY - use `-n` flag in parallel workflows)
-`notebooklm history` - display conversation history (read-only)
-`notebooklm source add` - add sources
-`notebooklm profile list` - list profiles
-`notebooklm profile create` - create profile
-`notebooklm profile switch` - switch active profile
-`notebooklm doctor` - check environment health
**Ask before running:**
-`notebooklm delete` / `source delete` / `note delete` / `share remove` / `profile delete` - destructive. Once approved, pass `--yes`/`-y` to skip the confirmation prompt (uniform across every destructive command). On the commands that also expose `--json` (e.g. `delete`, `source delete`, `note delete`, `share remove`), `--json` implies `--yes` so non-interactive callers never hang on the prompt; `profile delete` has no `--json`, so pass `--yes` explicitly there.
-`notebooklm generate *` - long-running, may fail
-`notebooklm download *` - writes to filesystem
-`notebooklm artifact wait` - long-running (when in main conversation)
-`notebooklm source wait` - long-running (when in main conversation)
-`notebooklm research wait` - long-running (when in main conversation)
-`notebooklm ask "..." --save-as-note` - writes a note
-`notebooklm history --save` - writes a note
## Quick Reference
| Task | Command |
|------|---------|
| Authenticate | `notebooklm login` |
| Authenticate from browser cookies | `notebooklm login --browser-cookies <browser>` |
| Authenticate from one Chromium profile | `notebooklm login --browser-cookies 'chrome::Profile 1'` |
| Authenticate from one Firefox container | `notebooklm login --browser-cookies 'firefox::Work'` |
| Import every signed-in account into its own profile | `notebooklm login --browser-cookies <browser> --all-accounts` |
| Delete profile | `notebooklm profile delete old --yes` (`-y`; `--confirm` is a deprecated alias) |
| Rename profile | `notebooklm profile rename old new` |
| Use profile (one-off) | `notebooklm -p work list` |
| Health check | `notebooklm doctor` |
| Health check (auto-fix) | `notebooklm doctor --fix` |
**Parallel safety:** Use explicit notebook IDs in parallel workflows. Commands supporting `-n` shorthand: `artifact wait`, `source wait`, `research wait/status`, `download *`. Download commands also support `-a/--artifact`. Other commands use `--notebook`. For chat, use `-c <conversation_id>` to target a specific conversation.
**Partial IDs:** Use first 6+ characters of UUIDs. Must be unique prefix (fails if ambiguous). Works for ID-based commands such as `use`, `source delete`, and `wait`. For exact source-title deletion, use `source delete-by-title "Title"`. For automation, prefer full UUIDs to avoid ambiguity.
## Command Output Formats
Commands with `--json` return structured data for parsing:
**Understanding citations:** The `cited_text` in references is often a snippet or section header, not the full quoted passage. The `start_char`/`end_char` positions reference NotebookLM's internal chunked index, not the raw fulltext. Use `SourceFulltext.find_citation_context()` to locate citations:
or `.task_id` (from `generate *`). The chat `--json` references list uses
`.references[].source_id`.
## Generation Types
All generate commands support:
-`-s, --source` to use specific source(s) instead of all sources
-`--language` to set output language (defaults to configured language or 'en')
-`--json` for machine-readable output (returns `task_id` and `status`)
-`--retry N` to automatically retry on rate limits with exponential backoff (supported on all subcommands **except**`mind-map`)
-`--prompt-file PATH` to read description/query from a file (supported on `ask`, `generate` subcommands except `mind-map`, and `source add-research`; mutually exclusive with positional argument; use for long prompts)
¹ `--append` only customizes the built-in templates. With `--format custom`, pass the prompt as the positional `DESCRIPTION` argument (`notebooklm generate report "PROMPT" --format custom`); `--append` is silently ignored in that mode (the CLI prints a warning).
³ **Two kinds of mind map (issue #1256).**`generate mind-map --kind note-backed` (today's default) creates the **note-backed** kind — a JSON node tree, generated synchronously. `generate mind-map --kind interactive` creates the newer **interactive** studio artifact (what the web app now makes); it is polled to completion. Both emit the same `{mind_map, note_id, kind}` JSON, list under `artifact list --type mind-map`, and export via `download mind-map`. `--instructions` applies only to the note-backed kind. **The default `--kind` switches to `interactive` in v0.8.0**; omitting `--kind` prints a one-time stderr notice (silence with `NOTEBOOKLM_QUIET_DEPRECATIONS=1`).
⁴ **Cinematic video (Veo 3).**`generate video --format cinematic` generates AI documentary footage via Veo 3; it **ignores `--style`**, takes ~30-40 min, and requires a Google AI Ultra subscription. Also exposed as the `generate cinematic-video` alias (which forces `--format cinematic` and a longer default timeout). Download with `download video` or the `download cinematic-video` alias.
² **Portrait / vertical slide decks via prompt.** Slide-deck has no `--orientation` flag (unlike infographic). Treat portrait decks as skill-level prompt guidance, not a typed CLI/API contract: NotebookLM currently honors orientation cues written into the `DESCRIPTION` positional argument. Including phrases like `"9:16 portrait"`, `"vertical layout"`, `"portrait mobile format"`, or `"vertical 9:16 layout"` can make NotebookLM render each slide as a 9:16 portrait image. Empirically:
- The `.pptx` canvas itself may stay 16:9, but each slide's embedded image can be rendered as 9:16 portrait — useful for vertical/mobile video material extracted via `python-pptx`.
- Orientation is steered once at generation time. `generate revise-slide` edits content within an existing slide but does not change its orientation; if a slide falls back to landscape (occasional inconsistency), regenerate the whole deck rather than revising the single page.
- Combine with an explicit page count in the prompt (e.g. `"Create exactly 8 pages, using a vertical 9:16 portrait layout"`) for the most predictable output.
```bash
# Skill prompt hint: ask NotebookLM to render each slide as a 9:16 portrait image
notebooklm generate slide-deck "Create an 8-page deck in 9:16 portrait orientation for mobile viewing" --length default
```
## Features Beyond the Web UI
These capabilities are available via CLI but not in NotebookLM's web interface:
| Feature | Command | Description |
|---------|---------|-------------|
| **Batch downloads** | `download <type> --all` | Download all artifacts of a type at once |
| **Quiz/Flashcard export** | `download quiz --format json` | Export as JSON, Markdown, or HTML (web UI only shows interactive view) |
| **Slide deck as PPTX** | `download slide-deck --format pptx` | Download slide deck as editable .pptx (web UI only offers PDF) |
| **Slide revision** | `generate revise-slide "prompt" --artifact <id> --slide N` | Modify individual slides with a natural-language prompt |
| **Report template append** | `generate report --format study-guide --append "..."` | Append custom instructions to built-in format templates without losing the format type |
| **Source fulltext** | `source fulltext <id>` | Retrieve the indexed text content of any source |
| **Save chat to note** | `ask "..." --save-as-note` / `history --save` | Save Q&A answers or conversation history as notebook notes |
| **Programmatic sharing** | `share` commands | Manage sharing permissions without the UI |
- If download fails: Check if artifact status is COMPLETED first
**Benefits:** Non-blocking, user can do other work, automatic download on completion
### Document Analysis
**Time:** 1-2 minutes
1. `notebooklm create "Analysis: [project]"`
2. `notebooklm source add ./doc.pdf` (or URLs)
3. `notebooklm ask "Summarize the key points"`
4. `notebooklm ask "What are the main arguments?"`
5. Continue chatting as needed
### Bulk Import
**Time:** Varies by source count
1. `notebooklm create "Collection: [name]"`
2. Add multiple sources:
```bash
notebooklm source add "https://url1.com"
notebooklm source add "https://url2.com"
notebooklm source add ./local-file.pdf
```
3. `notebooklm source list` to verify
**Source limits:** Varies by plan—Standard: 50, Plus: 100, Pro: 300, Ultra: 600 sources per notebook. See [NotebookLM plans](https://support.google.com/notebooklm/answer/16213268) for details. The CLI does not enforce these limits; they are applied by your NotebookLM account.
**Supported types:** PDFs, YouTube URLs, web URLs, Google Docs, text files, Markdown, Word docs, EPUB, audio files, video files, images
### Bulk Import with Source Waiting (Subagent Pattern)
**Time:** Varies by source count
When adding multiple sources and needing to wait for processing before chat/generation:
1. Add sources with `--json` to capture IDs (parse with `jq -r .source.id`):
2. **Spawn a background agent** to wait for all sources:
```
Task(
prompt="Wait for sources {source_ids} in notebook {notebook_id} to be ready.
For each: notebooklm source wait {id} -n {notebook_id} --timeout 600
Report when all ready or if any fail.",
subagent_type="general-purpose"
)
```
3. Main conversation continues while agent waits
4. Once sources are ready, proceed with chat or generation
**Why wait for sources?** Sources must be indexed before chat or generation. Takes ~30 seconds to several minutes per source (see the processing-times table below).
### Deep Web Research (Subagent Pattern)
**Time:** 15-30+ minutes, runs in background
Deep research finds and analyzes web sources on a topic:
notebooklm source add-research --prompt-file ./research_query.txt --mode deep
```
`--prompt-file` is mutually exclusive with the positional text argument. The file is read as UTF-8 with trailing whitespace stripped. Supported on: `ask`, all `generate` subcommands (except `mind-map`), and `source add-research`.
> **Note:** `--prompt-file` reads a *prompt/query text file*, not a source document. To upload a file as a notebook source, use `source add ./file.pdf`.
## Known Limitations
**Rate limiting:** Audio, video, quiz, flashcards, infographic, and slide deck generation may fail due to Google's rate limits. This is an API limitation, not a bug.
**Refresh a CLI-managed install:** `notebooklm skill install`
Reference in New Issue
Block a user
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
