@pan-sec/notebooklm-mcp 2026.3.3 → 2026.4.1

package/docs/configuration.md

@@ -1,94 +0,0 @@
-## Configuration
-
-**No config files needed!** The server works out of the box with sensible defaults.
-
-### Configuration Priority (highest to lowest):
-1. **Tool Parameters** - Claude passes settings like `browser_options` at runtime
-2. **Environment Variables** - Optional overrides for advanced users
-3. **Hardcoded Defaults** - Sensible defaults that work for most users
-
----
-
-## Tool Parameters (Runtime Configuration)
-
-Claude can control browser behavior via the `browser_options` parameter in tools like `ask_question`, `setup_auth`, and `re_auth`:
-
-```typescript
-browser_options: {
-  show: boolean,              // Show browser window (overrides headless)
-  headless: boolean,          // Run in headless mode (default: true)
-  timeout_ms: number,         // Browser timeout in ms (default: 30000)
-
-  stealth: {
-    enabled: boolean,         // Master switch (default: true)
-    random_delays: boolean,   // Random delays between actions (default: true)
-    human_typing: boolean,    // Human-like typing (default: true)
-    mouse_movements: boolean, // Realistic mouse movements (default: true)
-    typing_wpm_min: number,   // Min typing speed (default: 160)
-    typing_wpm_max: number,   // Max typing speed (default: 240)
-    delay_min_ms: number,     // Min delay between actions (default: 100)
-    delay_max_ms: number,     // Max delay between actions (default: 400)
-  },
-
-  viewport: {
-    width: number,            // Viewport width (default: 1024)
-    height: number,           // Viewport height (default: 768)
-  }
-}
-```
-
-**Example usage:**
-- "Research this and show me the browser" → Sets `show: true`
-- "Use slow typing for this query" → Adjusts typing WPM via stealth settings
-
----
-
-## Environment Variables (Optional)
-
-For advanced users who want to set global defaults:
-- Auth
-  - `AUTO_LOGIN_ENABLED` — `true|false` (default `false`)
-  - `LOGIN_EMAIL`, `LOGIN_PASSWORD` — for auto‑login if enabled
-  - `AUTO_LOGIN_TIMEOUT_MS` (default `120000`)
-- Stealth / Human-like behavior
-  - `STEALTH_ENABLED` — `true|false` (default `true`) — Master switch for all stealth features
-  - `STEALTH_RANDOM_DELAYS` — `true|false` (default `true`)
-  - `STEALTH_HUMAN_TYPING` — `true|false` (default `true`)
-  - `STEALTH_MOUSE_MOVEMENTS` — `true|false` (default `true`)
-- Typing speed (human‑like)
-  - `TYPING_WPM_MIN` (default 160), `TYPING_WPM_MAX` (default 240)
-- Delays (human‑like)
-  - `MIN_DELAY_MS` (default 100), `MAX_DELAY_MS` (default 400)
-- Browser
-  - `HEADLESS` (default `true`), `BROWSER_TIMEOUT` (ms, default `30000`)
-- Sessions
-  - `MAX_SESSIONS` (default 10), `SESSION_TIMEOUT` (s, default 900)
-- Multi‑instance profile strategy
-  - `NOTEBOOK_PROFILE_STRATEGY` — `auto|single|isolated` (default `auto`)
-  - `NOTEBOOK_CLONE_PROFILE` — clone base profile into isolated dir (default `false`)
-- Cleanup (to prevent disk bloat)
-  - `NOTEBOOK_CLEANUP_ON_STARTUP` (default `true`)
-  - `NOTEBOOK_CLEANUP_ON_SHUTDOWN` (default `true`)
-  - `NOTEBOOK_INSTANCE_TTL_HOURS` (default `72`)
-  - `NOTEBOOK_INSTANCE_MAX_COUNT` (default `20`)
-- Library metadata (optional hints)
-  - `NOTEBOOK_DESCRIPTION`, `NOTEBOOK_TOPICS`, `NOTEBOOK_CONTENT_TYPES`, `NOTEBOOK_USE_CASES`
-  - `NOTEBOOK_URL` — optional; leave empty and manage notebooks via the library
-
----
-
-## Storage Paths
-
-The server uses platform-specific paths via [env-paths](https://github.com/sindresorhus/env-paths)
-- **Linux**: `~/.local/share/notebooklm-mcp/`
-- **macOS**: `~/Library/Application Support/notebooklm-mcp/`
-- **Windows**: `%LOCALAPPDATA%\notebooklm-mcp\`
-
-**What's stored:**
-- `chrome_profile/` - Persistent Chrome browser profile with login session
-- `browser_state/` - Browser context state and cookies
-- `library.json` - Your notebook library with metadata
-- `chrome_profile_instances/` - Isolated Chrome profiles for concurrent sessions
-
-**No config.json file** - Configuration is purely via environment variables or tool parameters!
-

package/docs/dependency-risk.md

@@ -1,25 +0,0 @@
-# Dependency Risk Notes
-
-## Patchright
-
-This project uses `patchright` for browser automation because NotebookLM flows
-depend on Playwright-compatible browser control with stealth-oriented behavior.
-Treat it as a higher-risk dependency than ordinary runtime libraries:
-
-- It is a Playwright fork, so upstream security fixes may not land at the same
-  time as Playwright releases.
-- Browser automation packages can run install scripts that fetch browser
-  binaries or drivers.
-- Keep it exact-pinned in `package.json` and review updates manually.
-- CI installs dependencies with `npm ci --ignore-scripts`; browser binaries
-  should be provisioned explicitly in controlled environments.
-- Production deployments should run the MCP server in a least-privilege
-  container or sandbox with a dedicated browser profile directory and no access
-  to unrelated host files.
-
-When upgrading `patchright`, verify:
-
-1. The package tarball integrity in `package-lock.json` changes only as expected.
-2. Notebook creation, source upload, auth setup, and session reuse tests pass.
-3. Any browser installation step is run explicitly, not via automatic package
-   lifecycle scripts in CI.

package/docs/improvement-sprint-2026.2.10.md

@@ -1,210 +0,0 @@
-# NotebookLM MCP Server — Improvement Sprint v2026.2.10
-
-## Overview
-
-A comprehensive 5-phase improvement project covering security hardening, code architecture, reliability, CI/CD, and testing. Informed by a full codebase audit (architecture, security sentinel, code quality review) and validated by a 4-agent review team (Skeptic, Sentinel, Architect, Librarian).
-
-**Result:** 168 tests passing, clean TypeScript build, 2 critical security bugs caught and fixed during review.
-
----
-
-## Phase 1: Quick Wins (CI, Docker, Cleanup)
-
-### 1A. Tests added to CI pipeline
-- **File:** `.github/workflows/ci.yml`
-- Added `npm test` step after the build step
-
-### 1B. `.dockerignore` created
-- **New file:** `.dockerignore`
-- Excludes: `node_modules/`, `dist/`, `.git/`, `*.tar.gz`, `tests/`, `docs/`, `medusa-env/`, `.mcpregistry_*`, `.env*`, IDE files, OS files, Python artifacts
-
-### 1C. Multi-stage Docker build
-- **File:** `Dockerfile`
-- **Stage 1 (builder):** install all deps, build TypeScript
-- **Stage 2 (runtime):** copy only `dist/`, `package.json`, `package-lock.json`, `npm ci --omit=dev`, install patchright
-- Keeps image ~40-60% smaller, dev dependencies never reach production
-
----
-
-## Phase 2: Security Hardening
-
-### 2A. MCP auth secure-by-default
-- **File:** `src/auth/mcp-auth.ts`
-- Auth is now **enabled by default** — no configuration needed for secure operation
-- Explicit opt-out via `NLMCP_AUTH_DISABLED=true` (case-insensitive via `parseBoolean`)
-- Legacy `NLMCP_AUTH_ENABLED=true` still honored for backwards compatibility
-- Clear warning logged when auth is disabled; conflict warning when both env vars set
-
-### 2B. Exponential backoff for auth lockout
-- **File:** `src/auth/mcp-auth.ts`
-- After lockout expires, `lockoutCount` persists to drive escalation
-- Backoff: 5min -> 15min -> 45min -> 4hr (capped at `MAX_LOCKOUT_MS`)
-- Formula: `baseDuration * 3^(lockoutCount - 1)`, capped at 4 hours
-
-### 2C. Credentials wrapped in SecureCredential
-- **File:** `src/config.ts`
-- `LOGIN_PASSWORD` and `GEMINI_API_KEY` wrapped in `SecureCredential` with 30-min TTL
-- Original env vars deleted from `process.env` after reading
-- **CONFIG.loginPassword blanked to `""`** — consumers must use `getSecureLoginPassword()`
-- **CONFIG.geminiApiKey set to `null`** — consumers must use `getSecureGeminiApiKey()`
-- `browser-session.ts` and `gemini-client.ts` updated to use secure accessors
-- Graceful handling when credential expires (clear error message, not unhandled throw)
-
-### 2D. Filesystem tools gated behind auth
-- **Files:** `src/index.ts`, `src/auth/mcp-auth.ts`
-- `add_folder`, `cleanup_data`, `export_library` require auth even when globally disabled
-- `authenticateMCPRequest()` passes `forceAuth` flag through to `validateToken()`
-- **Critical fix:** `validateToken()` accepts `forceValidation` parameter to bypass the `!enabled` short-circuit — prevents any-token-passes bypass
-
-### 2E. Config value range validation
-- **File:** `src/config.ts`
-- Added `clampInteger(value, min, max)` helper
-- Applied to: `maxSessions` (1-50), `sessionTimeout` (60-86400), `browserTimeout` (5000-300000)
-- Exported `parseBoolean`, `parseInteger`, `parseArray` for testability and reuse
-
----
-
-## Phase 3: Code Quality & Architecture
-
-### 3A. Handler split — 3,611 lines -> 9 domain modules
-- **From:** `src/tools/handlers.ts` (deleted after split)
-- **To:** `src/tools/handlers/` directory:
-
-| Module | Handlers | Lines |
-|--------|----------|-------|
-| `types.ts` | `HandlerContext` interface | ~20 |
-| `ask-question.ts` | `handleAskQuestion` | ~260 |
-| `session-management.ts` | list/close/reset/health | ~300 |
-| `auth.ts` | setup_auth, re_auth | ~230 |
-| `notebook-management.ts` | list/get/add/update/remove/select/search/stats | ~220 |
-| `notebook-creation.ts` | create/batch/sync/sources/folder | ~680 |
-| `system.ts` | export/project_info/quota/cleanup | ~370 |
-| `audio-video.ts` | audio/video/data-table tools | ~380 |
-| `webhooks.ts` | configure/list/test/remove | ~160 |
-| `gemini.ts` | deep_research/query/documents/history | ~780 |
-| `index.ts` | `ToolHandlers` facade class | ~280 |
-
-- Each domain function receives `ctx: HandlerContext` (sessionManager, authManager, library, rateLimiter, geminiClient)
-- Facade class delegates all 48 methods to domain functions
-- Type inference via `Parameters<typeof fn>[1]` prevents type drift
-
-### 3B. Tool registry pattern
-- **File:** `src/index.ts`
-- Replaced ~500-line switch/case with `Map<string, ToolHandler>` registry
-- **Built once** as class-level field in `setupHandlers()` (not per-request)
-- ~60 lines for all 48 tools
-
-### 3C. Locale-agnostic selectors
-- **File:** `src/session/browser-session.ts`
-- Replaced German-locale hardcoded `textarea[aria-label="Feld fur Anfragen"]`
-- New fallback chain: `textarea[aria-label]`, `textarea[class*="query"]`, `.chat-input textarea`
-
-### 3D. Gemini SDK type annotations
-- **File:** `src/gemini/gemini-client.ts`
-- Added explicit comment explaining why `as any` is needed (SDK v1.41.0 lacks Interactions API types)
-
-### 3E. Configurable FOLLOW_UP_REMINDER
-- **Files:** `src/config.ts`, `src/tools/handlers/ask-question.ts`
-- `NLMCP_FOLLOW_UP_REMINDER` env var (default: current text)
-- `NLMCP_FOLLOW_UP_ENABLED=true/false` to disable entirely
-- Added `responseTimeout` and `followUpReminder`/`followUpEnabled` to Config interface
-
----
-
-## Phase 4: Robustness & Reliability
-
-### 4A. Gemini API retry with exponential backoff
-- **File:** `src/gemini/gemini-client.ts`
-- Added `retryWithBackoff(fn, { maxRetries: 3, baseDelay: 1000 })` utility
-- Retries on: HTTP 429, 500, 502, 503, network errors
-- Does NOT retry on: 400, 401, 403, 404
-
-### 4B. Configurable NotebookLM response timeout
-- **File:** `src/session/browser-session.ts`, `src/config.ts`
-- Replaced hardcoded `120000` with `CONFIG.responseTimeout`
-- Configurable via `NLMCP_RESPONSE_TIMEOUT_MS` (default: 120000)
-
-### 4C. Better error handling for file permissions
-- **File:** `src/utils/file-permissions.ts`
-- Permission failures now log via `log.warning()` and create audit events
-- Lazy imports to break circular dependency (audit-logger -> config -> file-permissions)
-- Stale "no logger available" comment replaced with actual logging call
-
----
-
-## Phase 5: Testing
-
-### 5A. Security utility tests — `tests/security.test.ts`
-- 25 tests covering:
-  - `validateNotebookUrl` — valid URLs, invalid domains, non-HTTPS, dangerous protocols, empty/null input
-  - `validateQuestion` — empty, max length, trimming, null/undefined
-  - `RateLimiter` — under limit, at limit, independent keys, window expiry, clear
-
-### 5B. Config parsing tests — `tests/config.test.ts`
-- 32 tests covering:
-  - `parseBoolean` — true/false/1/0/undefined/unrecognized/case-insensitive
-  - `parseInteger` — valid/undefined/non-numeric/floats
-  - `parseArray` — comma-separated/trim/filter empty/undefined/single values
-  - Range clamping via CONFIG defaults
-  - `applyBrowserOptions` — show/headless/timeout/stealth/viewport/legacy/precedence
-  - New CONFIG defaults (responseTimeout, followUpEnabled, followUpReminder)
-
----
-
-## Post-Review Fixes (4-Agent Validation)
-
-Issues found and fixed by the Skeptic, Sentinel, Architect, and Librarian agents:
-
-| Fix | Severity | Description |
-|-----|----------|-------------|
-| forceAuth bypass | **CRITICAL** | `validateToken()` returned true when auth disabled, making forceAuth useless. Added `forceValidation` parameter. |
-| Plaintext creds in CONFIG | **CRITICAL** | `CONFIG.loginPassword` held plaintext despite SecureCredential wrapping. Blanked CONFIG fields, updated all consumers. |
-| Dead handlers.ts | **CRITICAL** | 3,611-line file still compiled by tsconfig glob. Deleted. |
-| toolRegistry per-request | **HIGH** | Map with 48 entries rebuilt on every tool call. Promoted to class field. |
-| Misleading auth log | **HIGH** | "Auth disabled" logged even when auth was actually enabled (conflicting env vars). |
-| parseInt inconsistency | **HIGH** | Bare `parseInt` in mcp-auth.ts bypassed NaN guard. Switched to `parseInteger`. |
-| Auth disable case-sensitivity | **MEDIUM** | `=== "true"` strict check. Now uses `parseBoolean()` for consistency. |
-| Stale no-logger comment | **HIGH** | Comment said "no logger" but lazy import mechanism was available. Fixed. |
-| Backoff comment | **LOW** | Said "3rd: 1hr" but actual value is 45min. Corrected. |
-
----
-
-## New Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `NLMCP_AUTH_DISABLED` | `false` | Explicitly disable MCP auth (not recommended) |
-| `NLMCP_RESPONSE_TIMEOUT_MS` | `120000` | NotebookLM response timeout in ms |
-| `NLMCP_FOLLOW_UP_REMINDER` | _(built-in text)_ | Custom follow-up reminder text |
-| `NLMCP_FOLLOW_UP_ENABLED` | `true` | Enable/disable follow-up reminder |
-
----
-
-## Files Modified
-
-| File | Changes |
-|------|---------|
-| `.github/workflows/ci.yml` | Added test step |
-| `.dockerignore` | **New** |
-| `.gitignore` | Added `docs/` |
-| `Dockerfile` | Multi-stage build |
-| `src/auth/mcp-auth.ts` | Secure-by-default, exponential backoff, forceValidation, parseBoolean/parseInteger |
-| `src/config.ts` | SecureCredential wrapping, range clamping, new config fields, exported parsers |
-| `src/index.ts` | Tool registry, forceAuth for filesystem tools |
-| `src/session/browser-session.ts` | Locale-agnostic selectors, configurable timeout, secure password accessor |
-| `src/gemini/gemini-client.ts` | Retry with backoff, secure API key accessor |
-| `src/utils/file-permissions.ts` | Lazy logging, audit events on failure |
-| `src/tools/handlers.ts` | **Deleted** (split into handlers/) |
-| `src/tools/handlers/` | **New** — 11 files (types, index, 9 domain modules) |
-| `src/tools/index.ts` | Re-export from handlers/ |
-| `tests/security.test.ts` | **New** — 25 tests |
-| `tests/config.test.ts` | **New** — 32 tests |
-
----
-
-## Verification
-
-- `npm run build` — TypeScript compiles clean
-- `npm test` — 168 tests pass (6 test files)
-- `node dist/index.js config` — server starts without errors
-- Tool count: 48 tools registered in registry

package/docs/testing-runbook.md

@@ -1,166 +0,0 @@
-# Authenticated Testing Runbook
-
-This runbook is the baseline sequence for future NotebookLM MCP testing in a real authenticated browser session.
-
-## Goal
-
-Use a visible Chrome session to capture valid NotebookLM auth, verify the local repo is healthy, and run a minimal smoke test flow before broader manual or agent-driven testing.
-
-## 1. Local Repo Preflight
-
-Run these from the repo root:
-
-```bash
-npx tsc --noEmit
-npx vitest run
-npx stryker run --dryRunOnly
-npm audit --json
-```
-
-Expected result:
-- TypeScript passes
-- Vitest passes
-- Stryker dry-run passes
-- `npm audit` reports 0 vulnerabilities
-
-## 2. Start Visible Chrome Auth
-
-Use the standalone auth flow from the repo root:
-
-```bash
-node auth-now.mjs
-```
-
-What it does:
-- Opens visible Chrome using the persistent NotebookLM profile
-- Waits for manual Google login
-- Saves encrypted browser state to the local auth store
-
-Expected success signal in the terminal:
-- `NotebookLM detected`
-- `Saved encrypted state.json.pqenc`
-- `Auth complete`
-
-Expected saved file on Linux:
-
-```text
-~/.local/share/notebooklm-mcp/browser_state/state.json.pqenc
-```
-
-## 3. Verify Auth Artifact
-
-Confirm the encrypted state file exists and is freshly updated:
-
-```bash
-stat ~/.local/share/notebooklm-mcp/browser_state/state.json.pqenc
-```
-
-Expected result:
-- File exists
-- Permissions are `0600`
-- Modify time matches the recent auth session
-
-## 4. MCP Health Check
-
-After auth is saved, verify the MCP server can use it.
-
-Important:
-- Browser auth and MCP auth are separate.
-- If you are testing through a direct stdio harness instead of your normal MCP client, you must also provide a valid `NLMCP_AUTH_TOKEN`.
-- For ad hoc local smoke tests, prefer a temporary in-process token over rotating the persisted token.
-
-Recommended prompt:
-
-```text
-Run get_health with deep_check enabled and report auth status, chat_ui_accessible, and any warnings.
-```
-
-Expected result:
-- `authenticated: true`
-- `chat_ui_accessible: true`
-
-If this fails, do not continue to notebook smoke tests until auth is repaired.
-
-## 5. Notebook Smoke Test Sequence
-
-Run this exact sequence in the MCP client:
-
-1. `get_health(deep_check=true)`
-2. `list_notebooks`
-3. `select_notebook` on a known safe test notebook
-4. `ask_question` with a low-risk prompt such as:
-
-```text
-Summarize the main topics covered in this notebook in 3 bullets.
-```
-
-5. `get_quota(sync=true)` if quota behavior matters for the session
-
-Success criteria:
-- Notebook list loads
-- Notebook selection succeeds
-- `ask_question` returns a grounded answer
-- No auth-expired or browser-closed errors occur
-
-For direct test harnesses:
-- Inject a temporary `NLMCP_AUTH_TOKEN` into the server process
-- Pass the same token in MCP request metadata
-- Do not rotate the saved token unless you actually need to replace your client configuration
-
-## 6. Optional Creation Flow Test
-
-Only run this when creation is in scope for the session:
-
-1. `create_notebook` with a disposable test name
-2. `add_source` or `add_folder` with a safe local fixture
-3. `list_sources`
-4. Optional: `generate_audio_overview`, `generate_video_overview`, or `generate_data_table`
-
-Cleanup:
-- Remove disposable test notebooks or clearly label them as temporary
-
-## 7. Recovery Paths
-
-If auth is stale or broken:
-
-1. Close all Chrome/Chromium windows
-2. Re-run visible auth:
-
-```bash
-node auth-now.mjs
-```
-
-If persistent profile/session issues remain:
-
-1. Close all Chrome/Chromium windows
-2. Preview cleanup with library preservation
-3. Confirm cleanup
-4. Re-run auth
-5. Re-run `get_health(deep_check=true)`
-
-Recommended agent prompt:
-
-```text
-Repair NotebookLM auth without deleting my library, then verify with get_health deep_check.
-```
-
-## 8. Session Notes Template
-
-Record these for each authenticated test pass:
-
-- Date:
-- Branch/commit:
-- Auth method: `node auth-now.mjs`
-- Auth artifact updated: yes/no
-- `get_health(deep_check=true)`: pass/fail
-- Notebook smoke test: pass/fail
-- Creation flow test: pass/fail/not run
-- Quota check: pass/fail/not run
-- Issues found:
-
-## Notes
-
-- Prefer visible auth for all interactive login work.
-- Do not use headless auth flows.
-- `cleanup_data` is a recovery tool, not a default auth step.
-- Keep at least one safe disposable notebook available for smoke testing.

package/docs/tools.md

@@ -1,34 +0,0 @@
-## Tools
-
-### Core
-- `ask_question`
-  - Parameters: `question` (string, required), optional `session_id`, `notebook_id`, `notebook_url`, `show_browser`.
-  - Returns NotebookLM's answer plus the follow-up reminder.
-- `list_sessions`, `close_session`, `reset_session`
-  - Inspect or manage active browser sessions.
-- `get_health`
-  - Summaries auth status, active sessions, and configuration.
-- `setup_auth`
-  - Opens the persistent Chrome profile so you can log in manually.
-- `re_auth`
-  - Switch to a different Google account or re-authenticate.
-  - Use when NotebookLM rate limit is reached (50 queries/day for free accounts).
-  - Closes all sessions, clears auth data, and opens browser for fresh login.
-
-### Notebook library
-- `add_notebook` – Safe conversational add; expects confirmation before writing.
-- `list_notebooks` – Returns id, name, topics, URL, metadata for every entry.
-- `get_notebook` – Fetch a single notebook by id.
-- `select_notebook` – Set the active default notebook.
-- `update_notebook` – Modify metadata fields.
-- `remove_notebook` – Removes entries from the library (not the original NotebookLM notebook).
-- `search_notebooks` – Simple query across name/description/topics/tags.
-- `get_library_stats` – Aggregate statistics (total notebooks, usage counts, etc.).
-
-### Resources
-- `notebooklm://library`
-  - JSON representation of the full library: active notebook, stats, individual notebooks.
-- `notebooklm://library/{id}`
-  - Fetch metadata for a specific notebook. The `{id}` completion pulls from the library automatically.
-
-**Remember:** Every `ask_question` response ends with a reminder that nudges your agent to keep asking until the user’s task is fully addressed.

package/docs/troubleshooting.md

@@ -1,59 +0,0 @@
-## Troubleshooting
-
-### Fresh start / Deep cleanup
-If you're experiencing persistent issues, corrupted data, or want to start completely fresh:
-
-**⚠️ CRITICAL: Close ALL Chrome/Chromium instances before cleanup!** Open browsers can prevent cleanup and cause issues.
-
-**Recommended workflow:**
-1. Close all Chrome/Chromium windows and instances
-2. Ask: "Run NotebookLM cleanup and preserve my library"
-3. Review the preview - you'll see exactly what will be deleted
-4. Confirm deletion
-5. Re-authenticate: "Open NotebookLM auth setup"
-
-**What gets cleaned:**
-- Browser data, cache, Chrome profiles
-- Temporary files and logs
-- Old installation data
-- **Preserved:** Your notebook library (when using preserve option)
-
-**Useful for:**
-- Authentication problems
-- Browser session conflicts
-- Corrupted browser profiles
-- Clean reinstalls
-- Switching between accounts
-
-### Browser closed / `newPage` errors
-- Symptom: `browserContext.newPage: Target page/context/browser has been closed`.
-- Fix: The server auto‑recovers (recreates context and page). Re‑run the tool.
-
-### Profile lock / `ProcessSingleton` errors
-- Cause: Another Chrome is using the base profile.
-- Fix: `NOTEBOOK_PROFILE_STRATEGY=auto` (default) falls back to isolated per‑instance profiles; or set `isolated`.
-
-### Authentication issues
-**Quick fix:** Ask the agent to repair authentication; it will run `get_health` → `setup_auth` → `get_health`.
-
-**For persistent auth failures:**
-1. Close ALL Chrome/Chromium instances
-2. Ask: "Run NotebookLM cleanup with library preservation"
-3. After cleanup completes, ask: "Open NotebookLM auth setup"
-4. This creates a completely fresh browser session while keeping your notebooks
-
-**Auto-login (optional):**
-- Set `AUTO_LOGIN_ENABLED=true` with `LOGIN_EMAIL`, `LOGIN_PASSWORD` environment variables
-- For automation workflows only
-
-### Typing speed too slow/fast
-- Adjust `TYPING_WPM_MIN`/`MAX`; or disable stealth typing by setting `STEALTH_ENABLED=false`.
-
-### Rate limit reached
-- Symptom: "NotebookLM rate limit reached (50 queries/day for free accounts)".
-- Fix: Use `re_auth` tool to switch to a different Google account, or wait until tomorrow.
-- Upgrade: Google AI Pro/Ultra gives 5x higher limits.
-
-### No notebooks found
-- Ask to add the NotebookLM link you need.
-- Ask to list the stored notebooks, then choose the one to activate.