@roomi-fields/notebooklm-mcp 1.5.9 → 1.6.0

package/README.md

@@ -1,10 +1,10 @@
 <div align="center">
 
-# NotebookLM MCP + HTTP REST API
+# NotebookLM REST API + MCP server
 
-**Google NotebookLM over MCP + a local HTTP REST API — Q&A with citations, audio podcasts, video generation, multi-account rotation. Works with Claude Code, Codex, Cursor, n8n, Zapier, Make.**
+**Automate Google NotebookLM at scale. 33-endpoint HTTP REST API for n8n / Zapier / Make / curl, plus an MCP server for Claude Code / Cursor / Codex. Citation-backed Q&A, full Studio generation (audio · video · infographic · report · presentation · data table), multi-account rotation with auto-reauth.**
 
-> 🟢 **Actively maintained fork** of [PleasePrompto/notebooklm-mcp](https://github.com/PleasePrompto/notebooklm-mcp) (upstream last push: 2025-12-27). This fork ships v1.5.8 (2026-04-19) with 2026 NotebookLM UI selectors, HTTP REST API for n8n / Zapier / Make, multi-account rotation, and documented install on Windows / WSL / Docker.
+> v1.6.0 — production-grade, batch-tested on overnight runs of 1 000+ questions. New: `/batch-to-vault` endpoint and [RTFM integration](./deployment/docs/14-RTFM-INTEGRATION.md) for offline retrieval at scale. [Compare with `PleasePrompto/notebooklm-mcp` v2.0.0](https://roomi-fields.github.io/notebooklm-mcp/compare) to see when this project is the right pick (REST API, full Studio, auto-reauth) and when the MCP-only upstream is.
 
 <!-- Badges -->
 
@@ -66,15 +66,35 @@ Generate multiple content types from your notebook sources:
 - **MCP Protocol** — Claude Code, Cursor, Codex, any MCP client
 - **HTTP REST API** — n8n, Zapier, Make.com, custom integrations
 - **Docker** — Isolated deployment with Docker or Docker Compose
+- **[RTFM](https://github.com/roomi-fields/rtfm) retrieval layer** — `/batch-to-vault` writes citation-backed answers as markdown + JSON sidecars (`nblm-answer-v1` schema), indexable by [RTFM](https://github.com/roomi-fields/rtfm) (FTS5 + semantic) for unlimited offline queries. Ideal for academic / SOTA workflows. [Guide](./deployment/docs/14-RTFM-INTEGRATION.md).
 
 ---
 
 ## Quick Start
 
-### Option 1: MCP Mode (Claude Code, Cursor, Codex)
+### Option 1 — HTTP REST API (n8n, Zapier, Make, curl, any HTTP client)
 
 ```bash
-# Clone and build locally
+git clone https://github.com/roomi-fields/notebooklm-mcp.git
+cd notebooklm-mcp
+npm install && npm run build
+npm run setup-auth   # One-time Google login
+npm run start:http   # Start REST API on port 3000
+```
+
+```bash
+# Citation-backed Q&A, single curl, JSON response
+curl -X POST http://localhost:3000/ask \
+  -H 'Content-Type: application/json' \
+  -d '{"question": "Summarize chapter 3", "notebook_id": "your-id", "source_format": "json"}'
+```
+
+The full surface is **33 documented endpoints** — see the [REST API reference](https://roomi-fields.github.io/notebooklm-mcp/notebooklm-rest-api). For overnight batches of 1 000+ questions, see the [batch pattern](https://roomi-fields.github.io/notebooklm-mcp/batch-1000-questions).
+
+### Option 2 — MCP Mode (Claude Code, Cursor, Codex)
+
+```bash
+# Build (same package, MCP transport)
 git clone https://github.com/roomi-fields/notebooklm-mcp.git
 cd notebooklm-mcp
 npm install && npm run build
@@ -82,7 +102,7 @@ npm install && npm run build
 # Claude Code
 claude mcp add notebooklm node /path/to/notebooklm-mcp/dist/index.js
 
-# Cursor - add to ~/.cursor/mcp.json
+# Cursor — add to ~/.cursor/mcp.json
 {
   "mcpServers": {
     "notebooklm": {
@@ -95,24 +115,7 @@ claude mcp add notebooklm node /path/to/notebooklm-mcp/dist/index.js
 
 Then say: _"Log me in to NotebookLM"_ → Chrome opens → log in with Google.
 
-### Option 2: HTTP REST API (n8n, Zapier, Make.com)
-
-```bash
-git clone https://github.com/roomi-fields/notebooklm-mcp.git
-cd notebooklm-mcp
-npm install && npm run build
-npm run setup-auth   # One-time Google login
-npm run start:http   # Start server on port 3000
-```
-
-```bash
-# Query the API
-curl -X POST http://localhost:3000/ask \
-  -H "Content-Type: application/json" \
-  -d '{"question": "Explain X", "notebook_id": "my-notebook"}'
-```
-
-### Option 3: Docker (NAS, Server)
+### Option 3 — Docker (NAS, server, headless)
 
 ```bash
 # Build and run
@@ -131,19 +134,26 @@ See [Docker Guide](./deployment/docs/08-DOCKER.md) for NAS deployment (Synology,
 
 ## Documentation
 
-| Guide                                                        | Description                               |
-| ------------------------------------------------------------ | ----------------------------------------- |
-| [Installation](./deployment/docs/01-INSTALL.md)              | Step-by-step setup for HTTP and MCP modes |
-| [Configuration](./deployment/docs/02-CONFIGURATION.md)       | Environment variables and security        |
-| [API Reference](./deployment/docs/03-API.md)                 | Complete HTTP endpoint documentation      |
-| [n8n Integration](./deployment/docs/04-N8N-INTEGRATION.md)   | Workflow automation setup                 |
-| [Troubleshooting](./deployment/docs/05-TROUBLESHOOTING.md)   | Common issues and solutions               |
-| [Notebook Library](./deployment/docs/06-NOTEBOOK-LIBRARY.md) | Multi-notebook management                 |
-| [Auto-Discovery](./deployment/docs/07-AUTO-DISCOVERY.md)     | Autonomous metadata generation            |
-| [Docker](./deployment/docs/08-DOCKER.md)                     | Docker and Docker Compose deployment      |
-| [Multi-Interface](./deployment/docs/09-MULTI-INTERFACE.md)   | Run Claude Desktop + HTTP simultaneously  |
-| [Chrome Limitation](./docs/CHROME_PROFILE_LIMITATION.md)     | Profile locking (solved in v1.3.6+)       |
-| [Adding a Language](./docs/ADDING_A_LANGUAGE.md)             | i18n system for multilingual UI support   |
+Full docs site: **<https://roomi-fields.github.io/notebooklm-mcp/>** · [OpenAPI 3.1 spec](./deployment/docs/openapi.yaml)
+
+| Guide                                                                                        | Description                                                                                                                       |
+| -------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
+| [Installation](./deployment/docs/01-INSTALL.md)                                              | Step-by-step setup for HTTP and MCP modes                                                                                         |
+| [Configuration](./deployment/docs/02-CONFIGURATION.md)                                       | Environment variables and security                                                                                                |
+| [REST API reference](./deployment/docs/03-API.md)                                            | Complete HTTP endpoint documentation (33 endpoints)                                                                               |
+| [Run 1 000 questions overnight](./deployment/docs/12-BATCH-1000.md)                          | Production batch pattern with auto-reauth and rotation                                                                            |
+| [**RTFM integration — cache as searchable vault**](./deployment/docs/14-RTFM-INTEGRATION.md) | Pipeline pattern: NotebookLM as one-shot ingestion, RTFM as retrieval layer. `/batch-to-vault` endpoint, `nblm-answer-v1` schema. |
+| [n8n integration](./deployment/docs/04-N8N-INTEGRATION.md)                                   | Workflow automation setup                                                                                                         |
+| [Troubleshooting](./deployment/docs/05-TROUBLESHOOTING.md)                                   | Common issues and solutions                                                                                                       |
+| [Notebook library](./deployment/docs/06-NOTEBOOK-LIBRARY.md)                                 | Multi-notebook management                                                                                                         |
+| [Auto-discovery](./deployment/docs/07-AUTO-DISCOVERY.md)                                     | Autonomous metadata generation                                                                                                    |
+| [Content management](./deployment/docs/10-CONTENT-MANAGEMENT.md)                             | Audio, video, infographic, report, presentation                                                                                   |
+| [Multi-account rotation](./deployment/docs/11-MULTI-ACCOUNT.md)                              | Multiple accounts with TOTP auto-reauth                                                                                           |
+| [Docker](./deployment/docs/08-DOCKER.md)                                                     | Docker and Docker Compose deployment                                                                                              |
+| [Multi-interface](./deployment/docs/09-MULTI-INTERFACE.md)                                   | Run Claude Desktop + HTTP simultaneously                                                                                          |
+| [**Compare with PleasePrompto v2.0.0**](./deployment/docs/13-COMPARE.md)                     | Feature matrix vs the upstream MCP-only server                                                                                    |
+| [Chrome profile limitation](./docs/CHROME_PROFILE_LIMITATION.md)                             | Profile locking (solved in v1.3.6+)                                                                                               |
+| [Adding a language](./docs/ADDING_A_LANGUAGE.md)                                             | i18n system for multilingual UI support                                                                                           |
 
 ---
 
@@ -153,6 +163,13 @@ See [ROADMAP.md](./ROADMAP.md) for planned features and version history.
 
 **Latest releases:**
 
+- **v1.6.0** — `/batch-to-vault` endpoint + RTFM integration (`nblm-answer-v1` JSON Schema published at <https://schemas.roomi-fields.com/nblm-answer-v1.json>) for caching NotebookLM answers as a searchable markdown vault
+- **v1.5.9** — Restore `mcpName` field for MCP Registry npm-package ownership verification
+- **v1.5.8** — NotebookLM 2026 UI adaptations (icon-label sanitization, Discussion-panel recovery, count-based source detection) — PR #5 by @KhizarJamshaidIqbal
+- **v1.5.7** — Citation extraction selector fix (`.highlighted`) and Docker multi-stage build — PR #1 by @JulienCANTONI
+- **v1.5.6** — Citation extraction major rewrite (97% success rate), browser-verified auth at startup, profile auto-sync
+- **v1.5.5** — Multi-account state-path bug fix, Windows startup scripts, hidden-window MCP proxy
+- **v1.5.4** — Mid-session auto-reauth with stored credentials, TOTP support
 - **v1.5.3** — Docker deployment with noVNC for visual authentication + NAS support (Synology, QNAP)
 - **v1.5.2** — Notebook scraping from NotebookLM + Bulk delete + Bug fixes
 - **v1.5.1** — Multilingual UI support (FR/EN) with i18n selector system + E2E tests (76 tests)

package/deployment/docs/03-API.md

@@ -1,6 +1,15 @@
-# API Documentation - NotebookLM MCP HTTP Server
-
-> Complete reference for all REST endpoints
+# NotebookLM REST API reference — 33 HTTP endpoints
+
+> Complete reference for the NotebookLM HTTP REST API. Citation-backed Q&A,
+> Studio content generation, notebook library, multi-account, sessions.
+>
+> **OpenAPI 3.1 spec:** [openapi.yaml](pathname:///openapi.yaml) (importable in
+> Postman, Insomnia, Bruno, Swagger UI). Source in the repo at
+> [`deployment/docs/openapi.yaml`](https://github.com/roomi-fields/notebooklm-mcp/blob/main/deployment/docs/openapi.yaml).
+>
+> **Companion guides:** [REST batch pattern (1 000 questions overnight)](/batch-1000-questions) ·
+> [n8n integration](/notebooklm-n8n) · [Multi-account rotation](/notebooklm-multi-account) ·
+> [Compare with PleasePrompto/notebooklm-mcp v2.0.0](/compare)
 
 ---
 

package/deployment/docs/12-BATCH-1000.md

@@ -0,0 +1,165 @@
+# Run 1 000 NotebookLM questions overnight
+
+This is the pattern we use to run very long batches of citation-backed Q&A against Google NotebookLM — from PhD literature reviews to market intelligence pipelines. Single laptop, single account, eight hours, one thousand structured answers in a JSONL file.
+
+The whole thing fits in **one shell loop**, because the project exposes a plain REST API on `http://localhost:3000`. There is no SDK to learn, no agent harness to configure, no MCP client to wire.
+
+## What you need
+
+- This project running locally: `npm run setup-auth` (one-time Google login), then `npm run start:http`. [Install guide](/install).
+- A list of questions in a text file, one per line.
+- A notebook id. Either pick one from `GET /notebooks/scrape` or set a default with `PUT /notebooks/:id/activate`.
+- Optionally: a second Google account for rotation. [Multi-account guide](/notebooklm-multi-account).
+
+## The minimum viable batch (10 lines of bash)
+
+```bash
+NOTEBOOK_ID="paste-your-id-here"
+INPUT="questions.txt"
+OUTPUT="answers.jsonl"
+
+while IFS= read -r question; do
+  curl -sS -X POST http://localhost:3000/ask \
+    -H 'Content-Type: application/json' \
+    -d "$(jq -n --arg q "$question" --arg n "$NOTEBOOK_ID" \
+        '{question: $q, notebook_id: $n, source_format: "json"}')" \
+    >> "$OUTPUT"
+  echo >> "$OUTPUT"
+done < "$INPUT"
+```
+
+That works. It does not survive a session expiry at hour 4, it does not throttle, it does not resume after a network blip, and it makes 1 000 sequential blocking calls. So for real batches we wrap it.
+
+## The production pattern
+
+```python
+#!/usr/bin/env python3
+"""Run a batch of NotebookLM questions through the local REST API.
+
+Resumes safely on restart, handles re-auth, rotates accounts, throttles to
+respect rate limits, and writes one JSON line per answer with citations.
+"""
+
+import json, time, sys
+from pathlib import Path
+import httpx
+
+API = "http://localhost:3000"
+NOTEBOOK_ID = "paste-your-id-here"
+INPUT = Path("questions.txt")
+OUTPUT = Path("answers.jsonl")
+THROTTLE_SECONDS = 8           # average pace; tune to your account's quota
+MAX_RETRIES = 3
+ACCOUNTS = ["primary", "backup"]  # registered via `npm run accounts add`
+
+def already_done() -> set[str]:
+    """Resume support: skip questions already answered."""
+    if not OUTPUT.exists():
+        return set()
+    done = set()
+    for line in OUTPUT.read_text().splitlines():
+        try:
+            done.add(json.loads(line)["question"])
+        except (json.JSONDecodeError, KeyError):
+            continue
+    return done
+
+def switch_account(name: str) -> None:
+    httpx.post(f"{API}/re-auth", json={"account": name}, timeout=120).raise_for_status()
+
+def ask(question: str, account_idx: int = 0) -> dict:
+    payload = {
+        "question": question,
+        "notebook_id": NOTEBOOK_ID,
+        "source_format": "json",
+    }
+    for attempt in range(1, MAX_RETRIES + 1):
+        try:
+            r = httpx.post(f"{API}/ask", json=payload, timeout=180)
+            r.raise_for_status()
+            data = r.json()
+            if data.get("success"):
+                return data
+            # rate-limited or quota — try the next account
+            if "rate" in str(data.get("error", "")).lower():
+                account_idx = (account_idx + 1) % len(ACCOUNTS)
+                switch_account(ACCOUNTS[account_idx])
+                continue
+        except httpx.HTTPError as e:
+            print(f"  attempt {attempt}: {e}", file=sys.stderr)
+            time.sleep(2 ** attempt)
+    raise RuntimeError(f"failed after {MAX_RETRIES} retries: {question}")
+
+def main() -> None:
+    done = already_done()
+    questions = [q.strip() for q in INPUT.read_text().splitlines() if q.strip()]
+    todo = [q for q in questions if q not in done]
+    print(f"{len(done)} already answered · {len(todo)} to go")
+
+    with OUTPUT.open("a") as f:
+        for i, question in enumerate(todo, 1):
+            t0 = time.time()
+            answer = ask(question)
+            row = {
+                "question": question,
+                "answer": answer["answer"],
+                "citations": answer.get("citations", []),
+                "session_id": answer.get("session_id"),
+                "elapsed_s": round(time.time() - t0, 1),
+            }
+            f.write(json.dumps(row, ensure_ascii=False) + "\n")
+            f.flush()
+            print(f"[{i}/{len(todo)}] {row['elapsed_s']}s · {len(row['citations'])} cites")
+            time.sleep(THROTTLE_SECONDS)
+
+if __name__ == "__main__":
+    main()
+```
+
+Save it as `batch.py`, drop your questions in `questions.txt`, run `python batch.py`. Kill it any time, re-run, it picks up where it left off.
+
+## Why this pattern works
+
+### One file in, one file out
+
+Both ends are plain text. Your input is a `questions.txt` you can edit in any tool. Your output is `answers.jsonl` — JSON Lines, one answer per line, trivially loadable into pandas, jq, BigQuery, or another LLM for further processing:
+
+```bash
+jq '.answer' answers.jsonl | wc -l
+jq -c '{q: .question, n: (.citations | length)}' answers.jsonl
+```
+
+### Resume on restart
+
+Network drops, OS updates, batch scripts that get killed at 3am — they all happen. The first thing the script does is re-read the output file and skip questions whose text is already there. You lose the in-flight question and nothing else.
+
+### Auto-reauth across multi-hour runs
+
+Google sessions don't survive the night. The REST API checks the URL ground truth on every call and re-logins automatically using credentials stored in the AES-256-GCM vault (`npm run setup-auth` puts them there). TOTP codes are computed on the fly, so 2FA-protected accounts work transparently. [Multi-account configuration](/notebooklm-multi-account).
+
+### Account rotation when one quota saturates
+
+Free Google accounts hit a daily NotebookLM Q&A quota. The script flips to the next registered account on rate-limit errors via `POST /re-auth`. With two accounts you can typically push 1 500–2 000 questions in a 24-hour window without manual intervention.
+
+### Citations come back structured
+
+`source_format: "json"` returns a `citations` array of `{id, source, excerpt}` objects directly attached to the answer. You can join citations back to your sources for downstream processing — fact-checking, page-number resolution, LaTeX `\cite{}` generation for a thesis bibliography.
+
+## Sizing your throttle
+
+NotebookLM does not document a public rate limit, so we picked **8 seconds between calls** based on hundreds of overnight runs. That gives you ~450 questions in an hour and ~3 600 in eight hours per account. If you see `rate limit` errors before that, raise the throttle to 12-15 seconds or add a third account. If you can sustain 5 seconds without hitting limits, go for it.
+
+## When to switch to MCP mode instead
+
+If your driver is a coding agent (Claude Code, Cursor, Codex) rather than a script, the same operations are exposed as MCP tools. Use that surface when you want the agent to reason about which question to ask next; use the REST API when you have a flat list to grind through. [Both modes ship from the same package](/install).
+
+## What this gives you in practice
+
+For one of our PhD use cases we run 100-200 questions per chapter across a thirty-chapter thesis library. That's 5 000+ structured answers with citations, computed overnight on a laptop, indexed back into the thesis as `\cite{}`-ready snippets. Total cost: zero (uses the user's own NotebookLM account), total infrastructure: one Node process and one Python script.
+
+## Next steps
+
+- [HTTP API reference](/notebooklm-rest-api) — every endpoint, every parameter.
+- [n8n integration guide](/notebooklm-n8n) — same pattern but as a visual workflow.
+- [Multi-account guide](/notebooklm-multi-account) — register a second Google account for rotation.
+- [Compare with PleasePrompto](/compare) — when this project is the right pick over the upstream MCP-only server.

package/deployment/docs/13-COMPARE.md

@@ -0,0 +1,12 @@
+# Comparing NotebookLM MCP servers
+
+There are a handful of community projects that automate Google NotebookLM. The two most active TypeScript implementations are **`PleasePrompto/notebooklm-mcp`** (the original, MCP-only) and **`@roomi-fields/notebooklm-mcp`** (this project — REST API + MCP, Studio-complete, batch-oriented).
+
+This page is an honest, side-by-side comparison so you can pick the right one for your workflow. Both are MIT-licensed and actively maintained.
+
+> **TL;DR**
+>
+> - You want a quick **MCP server** for Claude Code / Cursor / Codex with citations and audio overviews → either works; PleasePrompto v2 is a clean, MCP-spec-first build.
+> - You need a **REST API** to call from n8n / Zapier / Make / curl / any non-MCP client → use this project. PleasePrompto v2 ships MCP-over-HTTP (Streamable HTTP transport) which is **not** a REST API.
+> - You generate **video / infographic / presentation / data table** from NotebookLM Studio → use this project. PleasePrompto v2 ships audio only; the rest is deferred to a follow-up.
+> - You run **long batches** (PhD research, market reports, content pipelines) and need **auto-reauth with TOTP** → use this project. PleasePrompto v2 explicitly does not store credentials.

package/deployment/docs/14-RTFM-INTEGRATION.md

@@ -0,0 +1,288 @@
+# NotebookLM + RTFM — cache batch outputs as a searchable markdown vault
+
+NotebookLM is brilliant at producing citation-backed answers, but it's slow (~10–30s per query) and rate-limited (50 queries per day per Google account on the free tier). For any workflow that re-asks similar questions over time — academic literature reviews, competitive intelligence pipelines, internal knowledge bases — querying NotebookLM live every time is the wrong architecture.
+
+The pattern that scales: **NotebookLM as a one-shot ingestion layer, [RTFM](https://github.com/roomi-fields/rtfm) as the retrieval layer.** Run an exhaustive question set once, persist every answer (with citations, source titles, and excerpts) as markdown, then point your CLI agent at the vault for unlimited offline queries.
+
+```
+[Once per notebook, periodic]
+  CLI agent generates an exhaustive question set
+    → POST /batch-to-vault   (titles + excerpts, citations preserved)
+      → vault/*.md + vault/*.json   (RTFM-ingestable)
+
+[At will, unlimited, ~ms, offline]
+  Agent → rtfm_search → rtfm_expand → answer
+```
+
+This page shows how to wire the two together.
+
+## Why this beats querying NotebookLM live
+
+| Concern           | Live NotebookLM             | NotebookLM → vault → RTFM      |
+| ----------------- | --------------------------- | ------------------------------ |
+| Latency per query | 10–30s                      | ~milliseconds                  |
+| Quota             | 50/day per Google account   | Unlimited after one-shot batch |
+| Repeat queries    | Cost a quota slot each time | Free                           |
+| Offline           | No                          | Yes                            |
+| Source citations  | Yes (titles + excerpts)     | Yes (preserved in markdown)    |
+| Best for          | Fresh interpretation        | Re-querying ingested knowledge |
+
+## What you need
+
+- This project running locally: `npm run start:http` after `npm run setup-auth`. [Install guide](/install).
+- [RTFM](https://github.com/roomi-fields/rtfm) installed and configured to point at your vault directory.
+- A notebook with sources already attached. List them with `GET /notebooks/scrape`.
+- A list of questions you want answered against that notebook.
+
+## The endpoint
+
+`POST /batch-to-vault` runs a list of questions and writes each answer as two artifacts in a vault directory:
+
+- `{slug}.md` — markdown with YAML frontmatter, the answer body, and a "Sources" section with quoted excerpts. Indexable by any markdown vault tool (RTFM, Obsidian, Foam, Dendron…).
+- `{slug}.json` — a structured payload conforming to the `nblm-answer-v1` schema (see [schema below](#nblm-answer-v1-json-schema)) for richer ingestion.
+
+### Request
+
+```bash
+curl -X POST http://localhost:3000/batch-to-vault \
+  -H 'Content-Type: application/json' \
+  -d '{
+    "questions": [
+      "What is the OSBD process?",
+      "How does NVC differentiate a need from a strategy?",
+      "What is empathic listening in NVC?"
+    ],
+    "notebook_id": "notebook-1",
+    "vault_dir": "/path/to/your/vault/cnv",
+    "slug_prefix": "sota",
+    "source_format": "json",
+    "sleep_between_ms": 2000
+  }'
+```
+
+### Parameters
+
+| Field              | Required | Default  | Description                                                                                   |
+| ------------------ | -------- | -------- | --------------------------------------------------------------------------------------------- |
+| `questions`        | yes      | —        | Non-empty array of strings. Each question becomes one `.md` + one `.json` file.               |
+| `vault_dir`        | yes      | —        | Destination directory. Created with `mkdir -p` if missing.                                    |
+| `notebook_id`      | no       | active   | Library notebook id to query.                                                                 |
+| `notebook_url`     | no       | —        | Direct NotebookLM URL (alternative to `notebook_id`).                                         |
+| `slug_prefix`      | no       | `""`     | Prepended to each filename. Use to namespace per topic, e.g. `"sota"`, `"market-2026q2"`.     |
+| `source_format`    | no       | `"json"` | Citation extraction mode. `"json"` is recommended for vault output (keeps titles + excerpts). |
+| `sleep_between_ms` | no       | `0`      | Pause between questions to avoid hammering NotebookLM. 1500–3000ms is sane for batches > 20.  |
+| `session_id`       | no       | new      | Reuse an existing session for context continuity across the batch.                            |
+
+### Response
+
+```json
+{
+  "success": true,
+  "data": {
+    "vault_dir": "/path/to/your/vault/cnv",
+    "total": 3,
+    "succeeded": 3,
+    "failed": 0,
+    "session_id": "5f1d8731",
+    "notebook": {
+      "id": "notebook-1",
+      "url": "https://notebooklm.google.com/notebook/74912e55-..."
+    },
+    "files": [
+      {
+        "question": "What is the OSBD process?",
+        "md_path": "/path/to/your/vault/cnv/sota-001-what-is-the-osbd-process.md",
+        "json_path": "/path/to/your/vault/cnv/sota-001-what-is-the-osbd-process.json",
+        "success": true,
+        "citations_count": 16
+      }
+    ]
+  }
+}
+```
+
+## What gets written
+
+### `{slug}.md`
+
+```markdown
+---
+title: 'What is the OSBD process?'
+type: nblm-answer
+asked_at: 2026-05-04T13:30:00.000Z
+notebook_id: 'notebook-1'
+notebook_url: 'https://notebooklm.google.com/notebook/74912e55-...'
+session_id: '5f1d8731'
+citations_count: 16
+sources:
+  - 'Pratiquer la Communication NonViolente_F.Keller.pdf'
+  - 'CNV et OSBD : outils pour pratiquer la communication bienveillante'
+  - "Rapport d'analyse systémique sur les cursus de formation en CNV"
+---
+
+# What is the OSBD process?
+
+> Asked on 2026-05-04T13:30:00.000Z against [CNV - Communication NonViolente](https://notebooklm.google.com/notebook/...)
+
+## Answer
+
+OSBD is the four-step acronym at the core of Nonviolent Communication...
+
+## Sources
+
+### [1] CNV et OSBD : outils pour pratiquer la communication bienveillante
+
+> Ce mode de communication est un choix conscient...
+
+### [2] Pratiquer la Communication NonViolente_F.Keller.pdf
+
+> Observation Je décris, de manière neutre, la situation...
+```
+
+The frontmatter is standard YAML — every markdown indexer (RTFM, Obsidian, Foam) reads it natively. The body has stable section headings (`## Answer`, `## Sources`) so a parser can lift the answer text and citation excerpts independently.
+
+### `{slug}.json`
+
+A structured sidecar conforming to [`nblm-answer-v1`](#nblm-answer-v1-json-schema). Use it when your indexer wants typed access to citations, source positions, or session metadata without re-parsing the markdown.
+
+## Pointing RTFM at the vault
+
+[RTFM](https://github.com/roomi-fields/rtfm) is an MCP-native retrieval layer with FTS5 + semantic search over markdown vaults, wikilink resolution, and progressive disclosure for AI agents. It speaks the same markdown convention `/batch-to-vault` writes, so wiring is essentially "point and index":
+
+```bash
+# 1. Generate the vault from NotebookLM
+curl -X POST http://localhost:3000/batch-to-vault -d '{...}'
+
+# 2. Index it with RTFM
+rtfm index /path/to/your/vault/cnv
+
+# 3. Search from your CLI agent (or any MCP client)
+rtfm search "OSBD process" --top 5
+rtfm expand sota-001-what-is-the-osbd-process
+```
+
+Inside an MCP client (Claude Code, Cursor, Codex), the same flow becomes a two-tool pattern: `rtfm_search` to surface the relevant cached answer, `rtfm_expand` to read the full markdown with citations preserved. No NotebookLM call needed for repeat queries.
+
+When new sources land in the notebook, re-run `/batch-to-vault` to refresh the cache.
+
+## Recommended layout for academic / SOTA workflows
+
+```
+~/research-vault/
+├── cnv/                          # one notebook → one folder
+│   ├── sota-001-...md
+│   ├── sota-001-...json
+│   ├── sota-002-...md
+│   └── sota-002-...json
+├── ifs-therapy/
+│   ├── sota-001-...md
+│   └── ...
+└── attachment-theory/
+    └── ...
+```
+
+Each folder maps to one NotebookLM notebook. `slug_prefix` per topic keeps filenames sortable and unique. RTFM indexes the whole tree and resolves cross-folder wikilinks if you add them.
+
+## Question generation
+
+The matching pattern on the input side: ask Claude (or any LLM) to generate an exhaustive question set for a topic before you batch them.
+
+```
+You are preparing a SOTA (state of the art) document on {topic} from a NotebookLM
+notebook containing {N sources}. Generate {K} questions that, taken together,
+extract everything a domain expert would want to know:
+
+- Foundational definitions and key concepts
+- Historical context and lineage
+- Core mechanisms / processes
+- Distinctions vs adjacent fields
+- Empirical evidence and limitations
+- Practical applications
+- Open debates and research gaps
+
+Output as a JSON array of strings, no commentary.
+```
+
+Save the output as `questions.json`, then:
+
+```bash
+curl -X POST http://localhost:3000/batch-to-vault \
+  -H 'Content-Type: application/json' \
+  -d "$(jq -n --slurpfile q questions.json --arg dir ~/research-vault/cnv \
+        '{questions: $q[0], notebook_id: "notebook-1", vault_dir: $dir, slug_prefix: "sota", sleep_between_ms: 2000}')"
+```
+
+For batches above ~50 questions, multi-account rotation kicks in automatically when a quota is hit. See [Multi-account rotation](/notebooklm-multi-account).
+
+## `nblm-answer-v1` JSON schema
+
+Sidecar `{slug}.json` files conform to this schema. Stable across releases under SemVer; breaking changes will bump the major version.
+
+> **Canonical URL** (resolvable, served as `application/schema+json` with CORS): <https://schemas.roomi-fields.com/nblm-answer-v1.json> — fetch from any JSON Schema validator. The version below mirrors the canonical document.
+
+```json
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.roomi-fields.com/nblm-answer-v1.json",
+  "title": "NotebookLM Answer (nblm-answer-v1)",
+  "description": "Structured sidecar payload produced by notebooklm-mcp /batch-to-vault. Encodes a single NotebookLM answer with citations, source positions, and session metadata for typed ingestion by retrieval systems (e.g. RTFM).",
+  "type": "object",
+  "required": ["type", "version", "asked_at", "question", "answer", "citations", "metadata"],
+  "properties": {
+    "$schema": { "type": "string", "format": "uri" },
+    "type": { "const": "nblm-answer" },
+    "version": { "const": "1.0" },
+    "asked_at": { "type": "string", "format": "date-time" },
+    "session_id": { "type": ["string", "null"] },
+    "notebook": {
+      "type": "object",
+      "properties": {
+        "id": { "type": ["string", "null"] },
+        "name": { "type": ["string", "null"] },
+        "url": { "type": ["string", "null"] }
+      }
+    },
+    "question": { "type": "string" },
+    "answer": {
+      "type": "object",
+      "required": ["text", "format"],
+      "properties": {
+        "text": { "type": "string" },
+        "format": { "const": "markdown" }
+      }
+    },
+    "citations": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["marker", "number"],
+        "properties": {
+          "marker": { "type": "string", "description": "Display marker, e.g. \"[1]\"" },
+          "number": { "type": "integer", "minimum": 1 },
+          "source_name": { "type": ["string", "null"] },
+          "source_text": {
+            "type": ["string", "null"],
+            "description": "Highlighted excerpt from the cited source"
+          }
+        }
+      }
+    },
+    "metadata": {
+      "type": "object",
+      "properties": {
+        "tags": { "type": "array", "items": { "type": "string" } },
+        "extraction_success": { "type": ["boolean", "null"] },
+        "citations_count": { "type": "integer", "minimum": 0 },
+        "source_names": { "type": "array", "items": { "type": "string" } }
+      }
+    }
+  }
+}
+```
+
+## See also
+
+- [Run 1 000 questions overnight](/batch-1000-questions) — the larger batch pattern with auto-reauth and rotation
+- [Multi-account rotation](/notebooklm-multi-account) — how quotas and TOTP auto-reauth work
+- [REST API reference](/notebooklm-rest-api) — full endpoint surface (33 endpoints + `/batch-to-vault`)
+- [RTFM on GitHub](https://github.com/roomi-fields/rtfm) — the retrieval layer