blog-notebooklm v2.2.0A

Immutable. This exact content never changes and is served at /api/v1/blob/213f0ec466320599.

---
name: blog-notebooklm
description: >
  Query Google NotebookLM notebooks for source-grounded, citation-backed
  answers from user-uploaded documents. Manages notebook library, handles
  Google authentication, and supports smart discovery. Works standalone
  via /blog notebooklm or internally from blog-write and blog-researcher
  for source-grounded research context. Falls back gracefully when not configured.
  Use when user says "notebooklm", "notebook", "query notebook",
  "ask notebook", "notebook research", "source grounded research",
  "document query", "notebook library".
user-invocable: true
argument-hint: "[ask|discover|library|setup|status|cleanup] [question-or-url]"
license: MIT
metadata:
  author: AgriciDaniel
  version: "2.2.0"
  source: "https://github.com/PleasePrompto/notebooklm-skill"
---

# Blog NotebookLM: Source-Grounded Research from Your Documents

Bundled paths below use host Markdown substitution of `${CLAUDE_SKILL_DIR}`;
it is not an exported shell variable. Resolve them before execution, quote
paths, and refuse nonabsolute overrides. Pass `blog_reference_root` resolved
from `${CLAUDE_SKILL_DIR}/../blog/references`, `blog_template_root` from
`${CLAUDE_SKILL_DIR}/../blog/templates`, and needed sibling roots to agents.
Read the main reference `orchestration-details.md` before loading project
context; pass only its helper-fenced output to downstream agents.

Query Google NotebookLM notebooks directly from Claude Code for citation-backed
answers from Gemini. Each question opens a headless browser session, retrieves
the answer from your uploaded documents, and closes. Responses are
source-grounded model answers, not proof of truth: uploaded documents may be
primary or secondary, and the answer can still omit context.

Answers provide usable provenance only when the returned citation identifies a
verifiable underlying source. Record a stable source URL and a publication,
study-period, or retrieval date when that detail affects verification or
interpretation. Use the underlying source title as the inline citation. Do not
cite the private NotebookLM URL as the bibliography entry for public content.

## Quick Reference

| Command | What it does |
|---------|-------------|
| `/blog notebooklm ask <question>` | Query a notebook for source-grounded answers |
| `/blog notebooklm discover <url>` | Smart-discover notebook content before cataloging |
| `/blog notebooklm library list` | List all notebooks in library |
| `/blog notebooklm library add <url>` | Add a notebook to library |
| `/blog notebooklm library search <query>` | Search notebooks by keyword |
| `/blog notebooklm library remove <id>` | Remove a notebook from library |
| `/blog notebooklm setup` | One-time Google authentication (browser visible) |
| `/blog notebooklm status` | Check authentication status |
| `/blog notebooklm cleanup` | Clean browser state (preserves library) |

## Persistent runtime directory

`CLAUDE_BLOG_RUNTIME_DIR` optionally selects one trusted absolute persistent
root. This integration uses `<root>/blog-notebooklm/.venv`; NotebookLM also
uses `<root>/blog-notebooklm/data` for its library, authentication and browser
state. Without this override, the existing skill-local defaults stay in use.
Google's shared credential config/token paths stay unchanged. No state is
copied or migrated automatically, and ordinary runs never perform setup.

Preserve an existing validated operator override. For a plugin without one,
explicitly pass the host-substituted `${CLAUDE_PLUGIN_DATA}/claude-blog-runtime`
path on both setup and every later runner call. This is Markdown substitution,
not an exported shell variable. Execute only once it is an absolute resolved
path. Single quotes keep an unresolved placeholder literal so validation
rejects it instead of expanding it to a different shell path:

```bash
CLAUDE_BLOG_RUNTIME_DIR='${CLAUDE_PLUGIN_DATA}/claude-blog-runtime' python3 "${CLAUDE_SKILL_DIR}/scripts/setup_environment.py" --check --json
CLAUDE_BLOG_RUNTIME_DIR='${CLAUDE_PLUGIN_DATA}/claude-blog-runtime' python3 "${CLAUDE_SKILL_DIR}/scripts/run.py" notebook_manager.py list --json
```

Only explicit setup without `--check` installs dependencies. Standalone users
keep the default unless they explicitly choose an absolute runtime root.
Relative, unresolved, or linked managed subdirectories fail closed. Changing
the root selects separate state; it never authorizes a migration or cleanup of
the old root. Plugin persistent data follows the host's uninstall retention
rules; preserve it explicitly when uninstalling if it is still needed.

## Prerequisites

- Google account with NotebookLM access
- Python 3.11+; the explicit setup action owns the managed venv
- Google Chrome installed by the explicit setup action when needed by Patchright
- One-time authentication setup (interactive Google login in visible browser)

## Use the run.py Wrapper

Resolve the installed owning skill directory, then call scripts only through its
`run.py` wrapper:

```bash
BLOG_SKILLS_DIR="${CLAUDE_BLOG_SKILLS_DIR:-${CLAUDE_SKILL_DIR}/..}"
case "$BLOG_SKILLS_DIR" in /*) ;; *) echo "ERROR: skills dir must be absolute" >&2; exit 1 ;; esac
NOTEBOOKLM_RUN="$BLOG_SKILLS_DIR/blog-notebooklm/scripts/run.py"
python3 "$NOTEBOOKLM_RUN" auth_manager.py status
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..."

# Do not resolve files beneath the current project's scripts/ directory.
```

Ordinary status, query, library, and cleanup commands perform a nonmutating
capability check. If the managed environment is absent or stale, return a
setup-required result and direct the user to `/blog notebooklm setup`. Only the
explicit setup action may create `.venv`, install dependencies, or install a
browser.

## Auth Check (Gate Pattern)

Before any query operation, check authentication:

```bash
python3 "$NOTEBOOKLM_RUN" auth_manager.py status
```

- If authenticated: proceed with the query
- If not authenticated: inform user and guide to setup:
  "NotebookLM requires Google login. Run `/blog notebooklm setup` to authenticate."
- **When called internally** (from blog-write or blog-researcher): return silently
  with no error if not authenticated. Never block the writing workflow.

## Setup Workflow

For `/blog notebooklm setup`:

```bash
# Opens a visible browser for manual Google login (one-time)
python3 "$NOTEBOOKLM_RUN" auth_manager.py setup
```

Tell the user: "A browser window will open. Please log in to your Google account."
Authentication persists via browser profile + cookie injection (hybrid approach).

Other auth commands:
```bash
python3 "$NOTEBOOKLM_RUN" auth_manager.py status   # Check auth
python3 "$NOTEBOOKLM_RUN" auth_manager.py reauth   # Re-authenticate
python3 "$NOTEBOOKLM_RUN" auth_manager.py clear     # Clear all auth data
```

## Query Workflow

For `/blog notebooklm ask <question>`:

### Step 1: Check Auth
Run auth check (see gate pattern above). If not authenticated, guide to setup.

### Step 2: Resolve Notebook
Determine which notebook to query:
- If `--notebook-url` provided: validate it is a NotebookLM notebook URL, then use it
- If `--notebook-id` provided: look up in library
- If neither: use active notebook from library
- If no active notebook: show library and ask user to select

### Step 3: Ask the Question
```bash
# Basic query (uses active notebook)
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "Your question here"

# Query specific notebook by ID
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..." --notebook-id notebook-id

# Query by URL directly
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..." --notebook-url "https://..."

# JSON output (for internal/programmatic use)
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..." --json

# Show browser for debugging
python3 "$NOTEBOOKLM_RUN" ask_question.py --question "..." --show-browser
```

### Step 4: Analyze and Follow Up
Every response ends with a follow-up prompt. **Required behavior:**
1. **STOP**: do not immediately respond to the user
2. **ANALYZE**: compare the answer to the user's original request
3. **IDENTIFY GAPS**: determine if more information is needed
4. **ASK FOLLOW-UP**: if gaps exist, immediately ask a follow-up question
5. **REPEAT**: continue until information is complete
6. **SYNTHESIZE**: combine all answers before responding to the user

## Smart Discovery Workflow

For `/blog notebooklm discover <url>`:

When adding a notebook without knowing its content, query it first:

```bash
# Step 1: Discover content
python3 "$NOTEBOOKLM_RUN" ask_question.py \
  --question "What is the content of this notebook? What topics are covered? Provide a complete overview briefly and concisely" \
  --notebook-url "<URL>"

# Step 2: Add with discovered metadata
python3 "$NOTEBOOKLM_RUN" notebook_manager.py add \
  --url "<URL>" \
  --name "<Based on content>" \
  --description "<Based on content>" \
  --topics "<Extracted topics>"
```

Do not guess descriptions; discover or ask the user.

## Library Management

```bash
# List all notebooks
python3 "$NOTEBOOKLM_RUN" notebook_manager.py list

# Add notebook (all params required -- discover or ask user!)
python3 "$NOTEBOOKLM_RUN" notebook_manager.py add \
  --url "https://notebooklm.google.com/notebook/..." \
  --name "Descriptive Name" \
  --description "What this notebook contains" \
  --topics "topic1,topic2,topic3"

# Search by keyword
python3 "$NOTEBOOKLM_RUN" notebook_manager.py search --query "keyword"

# Set active notebook
python3 "$NOTEBOOKLM_RUN" notebook_manager.py activate --id notebook-id

# Remove notebook
python3 "$NOTEBOOKLM_RUN" notebook_manager.py remove --id notebook-id

# Library statistics
python3 "$NOTEBOOKLM_RUN" notebook_manager.py stats
```

## Internal integration boundary (for blog-write / blog-researcher)

This skill's `ask_question.py` interface is a local browser-automation
adapter, not an official NotebookLM developer API. As of the 2026-10-07 review,
the official NotebookLM Help documentation supports the product workflow, but
this review did not establish an official public developer API for this
integration. Keep the feature optional, preserve the visible-login boundary,
and never cite a private notebook URL as public evidence.

When invoked as a Task subagent from blog-write or blog-researcher:

**Input** (provided by calling skill):
- `question`: Research question relevant to the blog topic
- `notebook_id` or `notebook_url`: Which notebook to query
- `context`: "internal" (signals graceful fallback mode)

**Process:**
1. Check auth status: if not authenticated, return empty result silently
2. Query the notebook with the research question
3. Parse and return structured response

**Output** (returned to calling skill):
```markdown
### NotebookLM Research
- **Source:** [Notebook name]
- **Question:** [What was asked]
- **Answer:** [Source-grounded response from user's documents]
- **Underlying Source:** [Public source URL or document identifier]
- **Underlying Source Date:** [Publication date or retrieval date]
- **Source Quality:** [Tier 1-3 after classifying the underlying document]
```

**Graceful fallback:** If auth is missing or query fails, return immediately
with no error. The calling workflow continues with WebSearch-based research.
Never block blog-write or blog-rewrite because NotebookLM is unavailable.

## Data Storage

All data stored inside the skill directory:
- `data/library.json`: Notebook metadata and library
- `data/auth_info.json`: Authentication status
- `data/browser_state/`: Chrome profile with cookies

**Security:** All data directories are gitignored. Never commit auth or browser state.

Browser lifecycle and authenticated-context isolation are centralized in
`scripts/browser_session.py`. Command scripts must use that helper instead of
opening an additional persistent profile or copying cookies into another file.

## Error Handling

| Error | Resolution |
|-------|-----------|
| Not authenticated | Run `/blog notebooklm setup` |
| ModuleNotFoundError | Always use `run.py` wrapper |
| Browser crash | `cleanup_manager.py --confirm --preserve-library`, then re-auth |
| Rate limit (50/day) | Wait until midnight PST or switch Google account |
| Notebook not found | Check with `notebook_manager.py list` |
| Query timeout (120s) | Retry with simpler question or `--show-browser` to debug |
| MCP unavailable (internal) | Return silently: writing workflow uses WebSearch |

## Limitations

- No session persistence (each question = new browser session)
- Rate limits on free Google accounts (50 queries/day)
- Manual upload required (user must add docs to NotebookLM web UI)
- Browser overhead (few seconds per question for launch + teardown)
- Local Claude Code only (not available in web UI)

## Reference Documentation

Load on-demand: do NOT load all at startup:
- `${CLAUDE_SKILL_DIR}/references/commands.md`: Full CLI commands, parameters, and workflow patterns
- `${CLAUDE_SKILL_DIR}/references/troubleshooting.md`: Error solutions, recovery procedures, debugging