← Về thư mục

---

name: notebooklm-research version: 2.0.0 description: > Use NotebookLM CLI (nlm) as the primary tool for academic/policy research. Summarise sources, query with RAG, cross-query notebooks, and generate reports using Google's NotebookLM AI — no external LLM tokens wasted. Replaces the deprecated notebook-master-sync (absorbed). trigger: - "User says 'sync notebook' / 'notebooklm sync' / 'đồng bộ notebook'" - "User asks to summarise / compare / research sources" - "Need to extract structured info (chapter-by-chapter) from a document" - "Pipeline task involving source ingestion, analysis, or reporting"

---

📞 Telegram Command

• notebooklm sync — Chạy đồng bộ tự động giữa NotebookLM và master file research
• Khi user gõ lệnh này, agent chạy python3 scripts/notebooklm_sync.py

NotebookLM Research Skill

Core Principle

NotebookLM-First. Before calling any external LLM (9router, etc.) for summarisation or extraction, use NotebookLM CLI — it's free, RAG-native, and produces citations.

🔄 Sync Flow (notebooklm sync)

When triggered, the agent runs python3 scripts/notebooklm_sync.py which executes 4 steps:

Step 1 — Source List Discovery

1. Auth check via nlm doctor; auto-refresh if expired
2. Fetch real source list: nlm source list <notebook> --json
3. Fuzzy-match sources against master file entries by normalized title
4. If source listing fails after refresh, retry the source-list call directly before treating the run as blocked

See references/sync-debug-notes.md for a real auth-refresh and ID-drift example. See references/legal-doc-analysis-pattern.md for the correct sequence when analysing legal/regulatory documents (Luật, Thông tư) against an external framework (ILO, OECD, etc.). See references/ilo-lmis-vietnam-domain.md for condensed ILO LMIS framework knowledge and Vietnam-specific labour market context (informal economy stats, ASEAN gap analysis, proxy indicators).

Step 2 — Gap Analysis

• ID drift: if NotebookLM UUID ≠ local master UUID → update local ID
• Missing summaries: if entry has no Tóm tắt (VN) or body < 1200 chars → flag for update
• New sources: if a NotebookLM source has no match in master → flag for addition

Step 3 — RAG Summarisation

For each flagged source: 1. nlm notebook query --source-ids "<id>" "<notebook>" "<prompt>" → 5,000+ char VN summary with citations 2. nlm source describe --json <id> → EN summary + keywords (0 token cost) 3. 3-second delay between calls to avoid rate limiting

Step 4 — Write & Validate

1. Replace old summary block or append new entry at file end
2. Run dash scan: reject if - found in VN prose
3. Report summary via Telegram

🔀 Multi-Task Kanban Orchestration Patterns

When building recurring deep-research loops (e.g. 7-pillar institutional benchmarking), construct multi-task pipelines programmatically: - Task 1 (r-and-d): Scoping & Data Sync (Process batch of 10 sources, run up to 10 nested search/explorations using Vision/OCR if external files are found). - Task 2 (r-and-d): RAG Analysis & Deep Finding (Extract details to policy documents). - Task 3 (grill-qa): Critique (Review findings, check for dashes, enforce logic & 7 pillars). - Task 4 (r-and-d): Synthesis & Reporting. - Task 5 (grill-qa): Master Update & QA Gate. Chain these tasks with --parent dependencies on creation so they execute sequentially. Each cron/orchestrator run must dispatch a dedicated chain per target.

• Phase 2 Policy Coherence Test: Bổ sung bước kiểm định định lượng và định tính về tính tương thích chính sách và agenda overload trong các văn bản chiến lược. • Anti-Dash Enforcement: Trong mọi query prompt tiếng Việt, bắt buộc chèn đoạn: "Tuyệt đối không dùng dấu gạch nối trong văn xuôi tiếng Việt." • Batching Strategy: Thực hiện batch 10 nguồn mỗi loop, lưu trạng thái processed_ids và last_batch vào processed_sources_vn.json. • QA Integration: Tích hợp kiểm tra tính nhất quán dữ liệu (Glossary, citations, APA 7) vào Phase 5. • Handoff Logic: Mỗi phase phải tự chủ động cập nhật trạng thái task và đẩy sang Phase kế tiếp trong Kanban.

Pipeline Advancement Rule (CRITICAL)

• Never block the pipeline. When Phase 3 (Critique) detects issues, it MUST still advance: write findings into the task comment, mark itself done, and push Phase 4 to ready. The CEO reads comments and decides whether to revisit.
• done = signal for the next loop. When all 5 tasks are done (not just archived), the next cron run must detect this and initiate a new 5-task cycle (Loop N+1). Treat done as "pipeline complete" even if not archived.
• Handoff chain: Phase N, on completion, MUST move Phase N+1 from todo → ready and write a transfer comment with findings, file paths, and critique context.

Output File Discipline

• Each phase writes deliverables into its Kanban workspace first (automatic).
• Then MUST copy files to the project master_reports/ directory: bash cp {workspace_path}/{filename} {project_base}/master_reports/{filename}
• Telegram report links MUST use clickable Tailscale Funnel format: ```
• filename ```
• Only one authoritative brief per topic — always overwrite (ghost never conflicted copies).

Cron Agent Discipline

• Every cron run MUST produce visible Telegram output. Never output [SILENT] when a pipeline exists — each run must either create a pipeline or report current status.
• Telegram output = ONLY the formatted message. The cron agent's final response text is the Telegram delivery itself. Do NOT include agent reasoning, debugging output, "I have created the tasks", or any meta-commentary. The CEO only sees the final response; internal steps stay in the Kanban board and logs.
• Execution flow (in order):
• Check board — query Kanban for all non-archived tasks.
• Evaluate — determine state: empty board → create pipeline; all done → create next loop; active pipeline → report progress.
• Act — immediately execute the evaluation finding (create tasks, update statuses).
• Report — compose a concise Vietnamese message with status + clickable Funnel links.

Available CLI Commands

Quality Standard for Government/Policy Sources: - Summaries must be highly detailed, structured chapter-by-chapter or section-by-section as the original document is organized. - If the document explicitly identifies bottlenecks/challenges, faithfully report what it says. If it does NOT mention them, explicitly note their absence in the summary — never fabricate or invent. - Automated background batching (multiple calls via LLM loop) of critical policy documents consistently produces generic, shallow summaries that violate quality standards. Foreground or batch-with-notify supervision is preferred for high-stakes deliverables. - Zero-Token Summarization (NotebookLM-First): Instead of fetching raw content and summarising via external LLM (9router), use NotebookLM's own AI: 1. nlm source describe <source-id> --json for EN summary + keywords (free). 2. nlm notebook query --source-ids <id> <notebook> "VN prompt" for chapter-level VN summary. - NEVER fabricate bottlenecks, targets, or recommendations. If absent from source, say so.

Model Governance Rules

• Model Standard: When 9router is unavoidable, ALWAYS use "model": "default".
• Strict Anti-Switching: Never change model without user approval. Handle 429 with backoff (30s+), not model hopping.
• Streaming: Always set "stream": false in urllib payloads to avoid JSONDecodeError.

CLI Command Reference & Scripting Patterns

Authentication

nlm login                          # Browser-based login
nlm login --check                  # Check auth status
nlm login switch <profile>         # Switch profile
nlm doctor                         # Run diagnostics

Source Management

nlm source list <notebook> --json                 # List all sources with real UUIDs
nlm source describe <source-id>                   # AI summary + keywords (0 token cost)
nlm source describe <source-id> --json            # JSON output
nlm source get <source-id>                        # Raw content

Query (RAG Extraction)

# Single source (targeted)
nlm notebook query --source-ids "<id>" "<notebook>" "Your question"

# Multi-source
nlm notebook query --source-ids "id1,id2" "<notebook>" "Compare..."

# Cross-notebook
nlm cross query "Question" --notebooks "id1,id2"
nlm cross query "Question" --all

Research Automation

nlm research start "query" --notebook-id <id> --mode deep --auto-import
nlm research status <notebook> --max-wait 300
nlm research import <notebook> <task-id> --cited-only

Report & Artifact Generation

nlm report create <notebook> --format "Briefing Doc" --confirm
nlm audio create <notebook> --format deep_dive --confirm
nlm slides create <notebook> --confirm
nlm download report <notebook> <artifact> --output report.md

Batch & Pipeline

nlm batch query "Question" --notebooks "id1,id2"
nlm batch query "Question" --all
nlm pipeline run research-and-report --notebook <id>
nlm tag add <notebook> --tags "tag1,tag2"

Agent Rules (enforce in all subagent tasks)

Rule 1 — NotebookLM-First

• Always use nlm source describe for quick summaries first
• Use nlm notebook query --source-ids for structured extraction
• Only fall back to 9router for formatting/translation of the result

Rule 2 — Real IDs Only

• Source UUIDs MUST come from nlm source list <notebook> --json
• NEVER fabricate or assume UUIDs — verified list is the single source of truth

Rule 3 — No Dash Injection

• Every VN query prompt MUST include: Tuyệt đối không dùng dấu gạch nối trong văn xuôi tiếng Việt

Rule 4 — Auth Recovery

• On Authentication expired or connection refused to Chrome debugger:
• Kill existing Chrome instances: pkill -f chrome
• Start Google Chrome headless on port 9223 using terminal(background=true, notify_on_complete=false) — do NOT use shell & in a foreground call (that syntax is rejected): google-chrome --headless=new --no-sandbox --disable-gpu --disable-dev-shm-usage --disable-extensions --no-first-run --no-default-browser-check --remote-debugging-port=9223 --remote-debugging-address=127.0.0.1 --remote-allow-origins=* --user-data-dir=/root/.notebooklm-mcp-cli/chrome-profiles/default
• In a follow-up foreground terminal call, run the refresh script using its ABSOLUTE path: python3 /opt/ai-os/products/ceo/scripts/notebooklm_refresh.py
• Success signal: ✅ Auth tokens saved to profile 'default'! The subsequent ⚠️ API test failed (may need CSRF refresh): list_notebooks()... from the same script is a FALSE POSITIVE — it does NOT block actual nlm commands.
• Verify auth is live: timeout 60 nlm source list <notebook-id> --json (if it returns JSON, you're good).
• Retry the failed command.

Rule 5 — Background for Batches

• Batches of 5+ sources run as background terminal tasks
• Log to /tmp/nlm_batch_*.log and set notify_on_complete=true

Pipeline Workflow (Research Mastery)

1. INGEST → nlm source add <notebook> --url/file/youtube (--wait)
2. AUTH  → nlm doctor (verify before batch)
3. FETCH UUIDs → nlm source list <notebook> --json
4. SURVEY → nlm source describe <id> --json  (ALL sources, batches of 3)
5. TARGETED QUERY → nlm notebook query --source-ids <1-3 IDs> "VN question"
6. MERGE → write combined EN+VN summary to research file
7. VERIFY → scan for dashes in VN prose
8. REPORT → nlm report create <notebook> --format "Briefing Doc"
9. ARCHIVE → nlm download report <notebook> <artifact> --output report.md

New Notebook / Context Mapping Workflow

When user shares a notebook for the first time and asks to "understand the sources" or build a knowledge base:

1. nlm source list <notebook-id> --json → inventory all sources with IDs
2. nlm source describe <id> --json for EVERY source (3 per terminal call, sleep 3s between)
3. Write a context_map.md in the project folder: source inventory table, each source's role, key themes
4. Run targeted notebook query per analytical cluster (≤3 IDs per call)
5. Write kb_strategy.md: knowledge domain map, tiered source list to acquire, research argument, roadmap
6. Only THEN proceed to gap analysis or pipeline launch

Pitfall: Do NOT skip straight to multi-source cross-query after listing sources. source describe is free and gives enough signal to cluster sources intelligently before spending query budget.

NotebookLM Master Sync Flow

An automated sync script is bundled at scripts/notebooklm_sync.py (resolves to ~/.hermes/skills/research/notebooklm-research/scripts/notebooklm_sync.py). It orchestrates a 4-phase sync: Note: copy is also at /opt/ai-os/products/ceo/scripts/notebooklm_sync.py for direct invocations from the CEO project directory.

Phase 1: Discovery

• Run nlm doctor to verify auth; auto-refresh via notebooklm_refresh.py if expired.
• Fetch all source UUIDs from NotebookLM via nlm source list <notebook> --json.
• Parse master_tourism_vn.md to build a local index of (title, ID, body).

Phase 2: Fuzzy Matching & ID Repair

• Normalise titles on both sides (strip extension, lowercase, remove punctuation).
• Match by src_norm in master_norm or master_norm in src_norm to handle minor name drift.
• For matched pairs with mismatched UUIDs: patch the local file with the correct real ID.
• This catches the common failure of "I guessed a fake UUID for a source" without requiring manual intervention.

Phase 3: RAG Summary Generation

• For sources missing Tóm tắt (VN) or with bodies under 1200 chars:
• nlm notebook query --source-ids <id> with the standard VN prompt (no dashes).
• nlm source describe <id> --json for EN summary + keywords.
• Replace the old summary block in-place, preserving the ### header and metadata lines.

Phase 4: New Source Import

• Sources on NotebookLM that match nothing in the local file are treated as new.
• A new ### entry is appended to the end with autogenerated title, ID, group prefix (GOV_/NEW_/PP_/RP_), and both summaries.
• Intended as a catch-all; manual reordering may be needed after bulk imports.

Caution: The script modifies the master file directly. Always run from a terminal background session with --notify-on-complete for batches over 10 sources, and review the diff before pushing to git.

Pitfalls

• nlm notebook query timeout: Terminal tool mặc định timeout 60s. NLM query có thể mất 120 đến 180s. Luôn truyền timeout=240 vào terminal tool (không phải timeout shell wrapper). Dùng > /tmp/nlm_out.json 2>&1 rồi đọc file sau — không pipe trực tiếp.
• --source-ids format: Nhận comma-separated, KHÔNG phải space-separated. Sai format → query trả về kết quả không lọc.
• Auth timeout: nlm auth hết hạn sau vài giờ idle. Chạy python3 /opt/ai-os/products/ceo/scripts/notebooklm_refresh.py trước mỗi session mới. "API test failed" trong output là false positive — không phải lỗi thật.
• PDF nặng KHÔNG phải nguyên nhân timeout: NLM xử lý PDF phía server. Timeout luôn do shell timeout quá ngắn hoặc auth hết hạn, không bao giờ do kích thước PDF.
• Environment-dependent failures (e.g. nlm: command not found due to missing binary or virtual environment activation): If the nlm tool is missing or fails to execute, do not guess or write off the tool as broken. Ensure you check for the correct python environment/venv or the path where nlm is installed (e.g., look for .venv/bin/nlm in the project integrations folder). If needed, symlink it to /usr/local/bin/nlm or append its directory to PATH.
• Script Dependency Errors: Automated sync scripts (e.g., notebooklm_sync.py) updating the SQLite local Kanban database must import sqlite3 at the top of the file to avoid NameError failures.
• Auth expires after ~1-2 hours. Always nlm doctor before batch work.
• nlm notebook query with no --source-ids mixes all sources — always scope to IDs.
• source describe returns ~500-1000 chars EN — use notebook query for VN deep summaries.
• Never pipe raw JSON through shell | jq — Python json module is safer.
• Delays: allow 3-5 seconds between sequential queries to avoid rate limiting.
• Automated batch processing of research files: When creating multi-file batches (e.g., creating a.txt, b.txt, c.txt), always perform an atomic write (e.g., using write_file) rather than sequential shell commands, and verify existence before proceeding.
• Always specify the Notebook UUID in list or query operations: Calling commands like nlm source list "<name>" with the text title of a notebook will return a NOT_FOUND error. You must first fetch the notebook UUID using nlm notebook list and then use that exact UUID for source lists or target queries (e.g. nlm source list "c73f7763-e6a6-423f-bb64-f751968eab92").
• NEVER fabricate UUIDs. Fake UUIDs cause silent failures (source not found). Real UUIDs come only from nlm source list <notebook> --json. If the master file has an ID that doesn't match NotebookLM's output, run notebooklm_sync.py to auto-repair via fuzzy matching.
• nlm notebook query with --source-ids supports --timeout 300: For multi-source RAG queries spanning 10+ IDs with deep prompt analysis, pass --timeout 600 to avoid premature timeouts.
• Multi-source queries with 5+ IDs reliably timeout at the default 60s shell limit. Split into batches of ≤3 source IDs per notebook query call. Use source describe (free, fast) first to survey all sources, then follow up with targeted notebook query --source-ids <1-3 IDs> for depth. Never attempt all 7–8 sources in one query call.
• Sequential source-reading pattern for new notebooks: When a user shares a fresh notebook and asks to "understand the sources", do NOT fire one large multi-source query. Correct sequence: (1) nlm source list <notebook> --json to get all IDs and titles; (2) nlm source describe <id> --json for every source in parallel batches of 3; (3) only then run targeted notebook query per topic/cluster. This respects rate limits and avoids timeouts.
• timeout 90 wrapper on terminal commands is more reliable than --timeout flag for catching hung queries; pair with 2>&1 | head -200 to capture partial JSON output on timeout.
• nlm doctor "API test failed" is NOT blocking: After an auth refresh cycle, nlm doctor may report "API test failed (may need CSRF refresh): list_notebooks() missing 1 required positional argument: 'client'". This is a false positive in the diagnostic tool that does not affect actual operations. nlm notebook list, nlm source list, and nlm notebook query all still function correctly.
• Do not switch model/provider without user permission. If the configured model (e.g. 9router default) fails or rate-limits, fix the approach (use NotebookLM instead) rather than swapping models. Switching models breaks consistency and wastes tokens.
• NotebookLM summaries are superior to 9router for RAG. 9router summarization of long raw documents often times out or returns 0-length output due to reasoning token starvation. NotebookLM native RAG returns 4K-8K char chapter-by-chapter summaries with citations, zero token cost.
• Parallel subagents sharing Chrome port 9223: When multiple subagents are dispatched concurrently and each executes NotebookLM queries via Chrome headless port 9223, Chrome handles multiple renderer tabs automatically. However, subagents must NOT run pkill -f chrome if port 9223 is already bound (ss -tlnp | grep 9223), as killing Chrome mid-session terminates browser state for all active subagents. Only restart Chrome if auth fails and port 9223 is unresponsive.
• Delegation concurrency limit: delegate_task has a strict concurrency limit (max_concurrent_children, default 3). Attempting to dispatch 4+ tasks in a single call fails immediately. Batch tasks into groups of ≤3 per delegate_task call and dispatch remaining tasks in subsequent calls or wait-for-completion cycles.
• Parallel query throughput pattern: When a notebook has many thematic clusters (e.g. 6+ ILO volumes across 3 topics), dispatch multiple nlm notebook query terminal calls IN PARALLEL — one per topic cluster, each scoped to ≤3 source IDs. This halves wall-clock time versus sequential querying without increasing timeout risk. Combine with parallel web_search calls for supplementary context to fill while NLM queries run.
• notebooklm_refresh.py absolute path: Always use /opt/ai-os/products/ceo/scripts/notebooklm_refresh.py. Do NOT use relative paths (scripts/notebooklm_refresh.py) as the script must be invoked from a shell whose cwd may vary.
• Foreground terminal calls cannot use & backgrounding. Using command1 & sleep 5; command2 in a foreground terminal() call is rejected with an error. To start a long-lived process (like Chrome headless) before running a follow-up script, use two separate calls: terminal(background=true) for the server, then terminal() (foreground) for the script.