NotebookLM Artifact Runbook

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
• rerun = chạy lại đúng step lỗi thay vì chạy lại toàn bộ
• completed / in_progress = trạng thái artifact đã xong hay còn đang render
• canonical = bản docs chính thức trong repo, không phải output review tạm

Mục tiêu

Runbook này dùng cho vận hành hằng ngày sau khi setup đã xong. Phạm vi cover:

• report
• slide-deck
• infographic
• video

Trước khi chạy

• npm run kb:nb:doctor
• npm run kb:nb:list
• npm run kb:nb:batch:dry khi vừa đổi config step

Output review mặc định:

• docs/tmp/notebooklm/study-guide.md
• docs/tmp/notebooklm/overview-slide-deck.pdf
• docs/tmp/notebooklm/overview-infographic.png
• docs/tmp/notebooklm/overview-video.mp4

Recipe theo artifact

Tạo report

node scripts/notebooklm-batch.mjs --config config/notebooklm/jobs.local.json --only generate-study-guide,download-study-guide

Dùng khi:

• cần tổng hợp insight cho Product/UX team
• cần preview markdown để tái chế thành docs nội bộ

Tạo slide deck

node scripts/notebooklm-batch.mjs --config config/notebooklm/jobs.local.json --only generate-slide-deck,download-slide-deck

Dùng khi:

• cần deck review nội bộ
• cần artifact để demo/brief stakeholder

Chẩn đoán trạng thái render:

NOTEBOOKLM_HOME="$PWD/.cache/notebooklm/home" notebooklm artifact list --type slide-deck --json -n <NOTEBOOK_ID>
NOTEBOOKLM_HOME="$PWD/.cache/notebooklm/home" notebooklm artifact poll <ARTIFACT_ID> -n <NOTEBOOK_ID>

Tải một slide deck completed theo artifact id:

NOTEBOOKLM_HOME="$PWD/.cache/notebooklm/home" notebooklm download slide-deck docs/tmp/notebooklm/overview-slide-deck.pdf -n <NOTEBOOK_ID> -a <ARTIFACT_ID>

Tạo infographic

node scripts/notebooklm-batch.mjs --config config/notebooklm/jobs.local.json --only generate-infographic,download-infographic

Dùng khi:

• cần hình tổng quan nhanh cho meeting
• cần visual summary từ notebook đã có source rõ ràng

Tạo video

node scripts/notebooklm-batch.mjs --config config/notebooklm/jobs.local.json --only generate-video,download-video

Dùng khi:

• cần overview video nội bộ
• cần artifact tương đối để chốt thông điệp tổng quan

Cách review artifact

• report: kiểm tra claim có bám nguồn và có đúng đối tượng đọc không
• slide-deck: kiểm tra structure có hợp logic và có thiếu cảnh báo/ngoại lệ không
• infographic: kiểm tra thông điệp có bị oversimplify không
• video: kiểm tra tone và tên riêng/term nội bộ có bị sai không

Artifact AI mặc định là draft, không coi là source of truth.

Best practices

• Luôn chạy kb:nb:doctor trước session mới.
• Luôn chạy kb:nb:batch:dry trước khi thay đổi config step.
• Tách generate và download thành step riêng để debug nhanh.
• Nếu chỉ 1 artifact lỗi, rerun bằng --only, không rerun toàn bộ.
• Giữ output review trong docs/tmp/notebooklm/, không promote thẳng vào docs canonical.

Troubleshooting

notebooklm command not found

Nguyên nhân:

• chưa cài CLI
• shell không thấy binary

Xử lý:

pip install "notebooklm-py[browser]==0.3.3"
playwright install chromium
npm run kb:nb:doctor

Doctor fail Version drift

Nguyên nhân:

• máy đang dùng version khác 0.3.3

Xử lý:

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

Doctor fail Auth readiness

Nguyên nhân:

• chưa login
• session hết hạn

Xử lý:

npm run kb:nb:login
npm run kb:nb:doctor

Doctor fail Jobs config

Nguyên nhân:

• chưa thay <NOTEBOOK_ID>
• JSON lỗi syntax

Xử lý:

• sửa config/notebooklm/jobs.local.json
• chạy lại npm run kb:nb:doctor

Batch fail ở 1 step generate/download

Xử lý:

• đọc .cache/notebooklm/runs/<timestamp>-batch-report.json
• rerun đúng step fail bằng --only
• không rerun toàn bộ nếu artifact khác đã xong

Slide deck bị in_progress quá lâu

Nguyên nhân có thể:

• NotebookLM đang queue render phía server
• artifact mới tạo chưa completed nhưng artifact cũ trong cùng notebook vẫn dùng được

Xử lý:

• kiểm tra bằng artifact list --type slide-deck --json
• kiểm tra chi tiết bằng artifact poll <ARTIFACT_ID>
• nếu cần file gấp, tải artifact completed gần nhất bằng download slide-deck -a <ARTIFACT_ID>
• không kết luận login/config lỗi nếu kb:nb:doctor đã pass mà chỉ riêng artifact còn in_progress

Mẫu quy trình review nội bộ

1. Generate artifact từ notebook đã ổn định.
2. Review output trong docs/tmp/notebooklm/.
3. Tách phần nào được dùng cho docs canonical, phần nào chỉ là support material.
4. Rewrite lại nội dung quan trọng trong docs canonical thay vì copy nguyên artifact AI.