NotebookLM Integration Workflow (Local + Team Baseline)

Operational reference only. Human entrypoint: docs/Shared/Operations/NOTEBOOKLM_STEP_BY_STEP.md

Nếu bạn chỉ cần dùng repo docs hoặc sửa docs canonical bình thường, không cần đọc file này.

Ở file này:

• artifact = output AI như report, slide deck, infographic, video
• doctor = lệnh preflight để kiểm tra môi trường/config trước khi chạy thật
• dry-run = chạy thử để kiểm tra config/steps mà chưa làm full run
• promote = chỉ lấy phần đã review để đưa vào docs canonical

Mục tiêu

Tích hợp notebooklm-py vào repo theo cách ít coupling, để team có thể:

• đọc tài liệu đã được đưa vào NotebookLM
• tạo report, slide-deck, infographic, video
• tải artifact về docs/tmp/notebooklm/ để review nội bộ

NotebookLM là lane bổ sung cho Knowledge Base, không thay thế kb:ingest.

Khi nào dùng NotebookLM, khi nào dùng kb:ingest

• Dùng kb:ingest khi cần mirror Google Docs/Sheets private thành markdown có traceability trong docs/Shared/Knowledge Base/Imported/.
• Dùng NotebookLM khi cần tạo artifact AI từ một notebook đã có source sẵn.
• Không trộn hai lane: ingest là pipeline đồng bộ tài liệu, NotebookLM là pipeline generate artifact.

Repo contract

• Script npm:
  • npm run kb:nb:init
  • npm run kb:nb:doctor
  • npm run kb:nb:login
  • npm run kb:nb:status
  • npm run kb:nb:batch:dry
  • npm run kb:nb:batch
• Script implementation:
  • scripts/notebooklm-cli.mjs
  • scripts/notebooklm-batch.mjs
  • scripts/notebooklm-doctor.mjs
  • scripts/notebooklm-doctor-lib.mjs
• Config:
  • config/notebooklm/jobs.example.json
  • config/notebooklm/jobs.local.json (gitignored)
• Review output:
  • docs/tmp/notebooklm/
• Run reports:
  • .cache/notebooklm/runs/

Version policy

• Pinned team baseline: notebooklm-py==0.3.3
• Khong dung latest trong huong dan team.
• Khi can nang version, cap nhat:
  • install command
  • kb:nb:doctor
  • runbook nay
  • smoke test kb:nb:batch:dry

Setup chuan

1. Cài CLI đúng version

Chọn 1 trong 2 cách:

pip install "notebooklm-py[browser]==0.3.3"
playwright install chromium

hoặc:

uv tool install "notebooklm-py[browser]==0.3.3"

2. Khởi tạo local config và output folder

npm run kb:nb:init

Lệnh này tạo:

• config/notebooklm/jobs.local.json nếu chưa có
• docs/tmp/notebooklm/

Nếu cần refresh template local theo bản mới nhất:

node scripts/notebooklm-init.mjs --force

3. Đăng nhập NotebookLM

npm run kb:nb:login

4. Điền notebook id vào local config

Sua config/notebooklm/jobs.local.json:

• thay toàn bộ <NOTEBOOK_ID> bằng notebook id thật sự
• chỉ sửa file local, không sửa file example track trong repo

5. Chạy preflight doctor

npm run kb:nb:doctor

Doctor kiểm tra 4 nhóm:

• notebooklm binary tồn tại
• version khớp 0.3.3
• NOTEBOOKLM_HOME ghi được
• auth sẵn sàng
• jobs.local.json không còn <NOTEBOOK_ID>

Nếu cần machine-readable output:

npm run kb:nb:doctor -- --json

6. Dry run batch

npm run kb:nb:batch:dry

Chỉ khi doctor + dry-run đều ổn mới chạy batch thật.

Verification checklist trước lần chạy đầu tiên

• npm run kb:nb:doctor
• npm run kb:nb:status
• npm run kb:nb:batch:dry

Pass criteria:

• doctor không còn FAIL
• kb:nb:status dung .cache/notebooklm/home
• dry-run liệt kê đúng các step sẽ chạy

Bảo mật

• Không commit:
  • config/notebooklm/*.local.json
  • .cache/notebooklm/**
• Không paste token/cookie vào file track trong repo
• Không đưa artifact AI vào docs canonical nếu chưa review

Quy trình vận hành đề xuất

1. Thêm/refresh source trong NotebookLM bằng UI hoặc CLI riêng của NotebookLM.
2. Chạy artifact qua kb:nb:batch hoặc --only.
3. Review artifact trong docs/tmp/notebooklm/.
4. Chỉ promote nội dung đã được review sang docs canonical.

Tài liệu tiếp theo

• Human guide: docs/Shared/Operations/NOTEBOOKLM_STEP_BY_STEP.md
• Artifact recipe va troubleshooting: docs/Shared/Operations/Knowledge/NB_Ops_NotebookLM_Artifact_Runbook.md
• Mirror ingest lane: docs/Shared/Operations/Knowledge/NB_Ops_Knowledge_Ingestion_Workflow.md