Themodernsoftware Notebooklm

TheModernSoftware NotebookLM

Overview

Run an agent-first workflow where Codex is the controller. Crawl weekly course materials from themodernsoftware.dev, ingest them into NotebookLM, and produce deep-study outputs without requiring a custom standalone agent service.

The workflow is deterministic through state files and templates:

• Use templates/course.yaml and templates/weeks.json as the single source of run state.
• Use agent-browser for page crawling and link extraction.
• Use notebooklm for source ingestion and output generation.

Workflow

Step 0: Initialize runtime workspace

Create a runtime folder and copy templates:

./themodernsoftware-notebooklm/scripts/init-workspace.sh ./runtime

This creates:

• ./runtime/course.yaml
• ./runtime/weeks.json
• ./runtime/prompts/*.prompt.md

Step 1: Preflight checks

Verify required tools before crawling:

agent-browser --help
notebooklm status --json

If notebooklm status --json fails, run notebooklm login.

Step 2: Crawl weekly materials (Codex-controlled)

Open https://themodernsoftware.dev/ with agent-browser and recursively discover week pages.

For each week, extract and classify links into:

• syllabus
• ppt
• reference

Persist each discovered week entry into weeks.json with status: "discovered".

Use crawl and classification rules from references/crawl-rules.md.

Step 3: Ingest into NotebookLM

For each status: discovered week: 1. Ensure notebook exists (from course.yaml.notebook_id; create once if empty). 2. Add all URLs/files for the week to NotebookLM sources. 3. Wait for source processing. 4. Write source_ids back into weeks.json. 5. Move status to ingested.

Use generation behavior and retries from references/notebooklm-deep-mode.md.

Step 4: Generate deep outputs

For each status: ingested week: 1. Generate bilingual lesson plan using prompts/lesson-plan.prompt.md. 2. Generate bilingual lecture notes using prompts/lecture-notes.prompt.md. 3. Generate video overview task using prompts/video.prompt.md. 4. Wait for video artifact completion. 5. Download video to local output path. 6. Update week status:

• drafted after document outputs
• video_pending while video is generating/downloading
• completed only when all required artifacts exist

Step 5: Failure policy

Apply strict policy from references/failure-handling.md:

• If themodernsoftware.dev is unreachable: fail the current run immediately.
• No automatic fallback source.
• Keep failure reason in weeks.json.error for the affected week/run.

Output Contract

Each completed week must include:

• lesson_plan_path
• lecture_notes_path
• video_artifact_id
• video_local_path
• status: completed

Do not mark completed if video generation is unfinished.

Resources

• references/crawl-rules.md: URL discovery and week classification rules.
• references/notebooklm-deep-mode.md: source ingestion, output generation, language and quality requirements.
• references/failure-handling.md: stop/retry/error recording policy.
• references/execution-checklist.md: runbook checklist.
• templates/course.yaml: runtime config template.
• templates/weeks.json: runtime state template.
• templates/weeks.schema.json: structure contract for state validation.
• templates/prompts/*.prompt.md: prompt templates.
• scripts/init-workspace.sh: initialize runtime workspace.
• scripts/verify-week-state.sh: validate weeks.json structure.

Common mistakes

• Running generation before source processing finishes.
• Marking week as completed before video download succeeds.
• Losing state by not persisting source_ids and artifact IDs.
• Mixing unrelated links into week assets.

Crawl Rules

Scope

Target domain: https://themodernsoftware.dev/

Only keep links likely related to weekly course content and supporting learning materials.

Discovery strategy

1. Start from homepage and course navigation pages. 2. Collect candidate URLs from anchors and visible page text. 3. Normalize URLs:

• Keep https absolute links.
• Remove fragment-only duplicates.
• Deduplicate by normalized URL string.

Week identification

Classify page/link into a week candidate when any of these match:

• URL path includes week, wk, or a numeric week segment.
• Page heading includes Week <N>.
• Neighboring nav text indicates week progression.

Generate week_id as week-XX with zero padding.

Asset classification

Classify assets by URL/text hints:

• syllabus: contains syllabus, outline, schedule
• ppt: contains .ppt, .pptx, slides, deck
• reference: all other supporting external links

If classification is ambiguous:

• Prefer ppt when slide/deck hints exist.
• Prefer syllabus for course-structure pages.
• Otherwise assign reference.

Required minimum for processing

A week is eligible for NotebookLM ingest when:

• at least one syllabus or one ppt exists.

If neither exists, keep week in discovered with error note.

Execution Checklist

1. Run workspace init script. 2. Confirm agent-browser and notebooklm availability. 3. Confirm NotebookLM auth (notebooklm status --json). 4. Crawl and classify weekly assets. 5. Persist discovery state into weeks.json. 6. Ingest week assets into NotebookLM. 7. Generate lesson plan and lecture notes. 8. Generate and download video overview. 9. Validate state file with scripts/verify-week-state.sh. 10. Confirm completed weeks satisfy full quality gate.

Failure Handling

Hard stop conditions

Stop the run immediately when:

• themodernsoftware.dev is unreachable (DNS/network failure)
• NotebookLM authentication is invalid and cannot be refreshed

No automatic fallback source is used.

Week-level failures

Mark only the affected week as failed when:

• one or more sources cannot be ingested
• generation command returns failure
• video download fails after artifact completion

Store failure details in:

• weeks[].error
• weeks[].last_attempt_at

Retry policy

On rerun, prioritize weeks in:

• failed
• video_pending

Never overwrite completed outputs unless user explicitly requests regeneration.

NotebookLM Deep Mode

Language policy

Generate outputs in bilingual mode:

• Primary explanation in Simplified Chinese.
• Keep key terms and section labels with English counterparts.

Ingestion protocol

1. Ensure notebook_id exists in course.yaml. 2. Add each week asset as a source using URL or local file path. 3. Record returned source IDs to weeks.json. 4. Wait until all week sources are ready before generation.

Required outputs per week

1. Lesson plan (lesson-plan.zh-en.md) 2. Lecture notes (lecture-notes.zh-en.md) 3. Video overview artifact and downloaded overview.mp4

Suggested generation order

1. Lesson plan first (provides structure) 2. Lecture notes second (expand structure) 3. Video last (reference the first two outputs)

Quality gate

A week is complete only when all outputs exist and video is downloaded locally.

Create detailed bilingual lecture notes (zh-Hans + English terms) based on this week's syllabus/slides/reference materials.

Requirements: 1. Expand each core concept with examples and counterexamples. 2. Include likely student misconceptions and correction guidance. 3. Add a short Q&A section with model answers. 4. Keep technical terms bilingual.

Output format:

• Markdown
• Structured by teaching segments

Generate a bilingual (zh-Hans + English terms) lesson plan for this week.

Requirements: 1. Include learning objectives, prerequisite knowledge, core concepts, and in-class activities. 2. Use Chinese as the primary explanation language, with English term labels. 3. Include a 90-minute session timeline and assessment checkpoints. 4. Cite source materials when possible.

Output format:

• Markdown
• Sectioned headings
• Actionable instructor notes

Based on this week's materials, generate a bilingual Chinese-first video overview script and structure.

Requirements: 1. Follow the lesson-plan structure. 2. Keep Chinese narrative natural for spoken explanation. 3. Preserve critical English technical terms. 4. Include short intro, concept walkthrough, and recap.

Style:

• Instructor-led, clear pacing, suitable for self-study learners.