Studyflow

Ask before running:

• notebooklm generate audio/video/slide-deck (long-running)
• notebooklm delete (destructive)

Commands

/studyflow setup

Create the full Notion workspace. Run this once.

Workflow:

1. Use mcp__claude_ai_Notion__notion-search to check if "StudyFlow" root page already exists
2. If not, create the root structure using mcp__claude_ai_Notion__notion-create-pages
3. Create all four databases (Knowledge Base, Flashcard Vault, Quiz Bank, Study Sessions)
4. Create the Courses and Projects sections as child pages
5. Print all created page/database IDs — copy these into the Permanent Notion IDs section below

Notion Page Structure:

📚 StudyFlow                    (root page)
├── 📈 Dashboard                (page with command reference)
├── 🗂️ Courses                  (page — course sub-pages go here)
├── 🔧 Projects & Freelance     (page — project sub-pages go here)
├── 📚 Knowledge Base           (database)
├── 🃏 Flashcard Vault          (database)
├── ❓ Quiz Bank                (database)
└── 📅 Study Sessions           (database)

Database Schemas:

Knowledge Base (Notes database)

• Name (title), Course (select), Type (select: Concept/Algorithm/Technology/Lecture/Pattern)
• Mastery (select: ⬜ New / 🟥 Learning / 🟨 Familiar / 🟩 Mastered)
• NotebookLM ID (rich_text), Source Type (multi_select), Tags (multi_select)
• Last Reviewed (date), Feynman Done (checkbox)

Flashcard Vault

• Front (title), Back (rich_text), Course (select)
• Status (select: 🆕 New / 📖 Learning / 🔄 Review / ✅ Mastered)
• Ease Factor (number, default 2.5), Interval (number, default 1)
• Next Review (date), Repetitions (number, default 0), Last Reviewed (date)
• Card Type (select: Standard / Cloze / Code)

Quiz Bank

• Question (title), Type (select: MCQ / True-False / Short Answer)
• Options (rich_text), Answer (rich_text), Explanation (rich_text)
• Course (select), Times Attempted (number), Times Correct (number), Last Attempted (date)

Study Sessions

• Session (title: "YYYY-MM-DD — [Notebook]"), Date (date), Notebook (rich_text)
• Topics Covered, What I Learned, Confusions, Next Actions (all rich_text)
• Cards Reviewed (number), Notes Created (number)

/studyflow notes <notebook-name-or-id> [--topic <topic>] [--type concept|algo|tech|lecture]

Generate a structured note page in Notion's Knowledge Base.

Workflow:

1. Run PYTHONIOENCODING=utf-8 notebooklm list --json to find the notebook by name
2. Set notebook context: PYTHONIOENCODING=utf-8 notebooklm use <id>
3. Run targeted NotebookLM queries:
   • notebooklm ask "Explain [topic] comprehensively — core concept, definitions, how it works, why it matters"
   • notebooklm ask "What are 3-5 common pitfalls or misconceptions about [topic]?"
   • notebooklm ask "Give me a concrete example or code example of [topic] in action"
   • notebooklm ask "What are 5-8 active recall questions that test deep understanding of [topic]?"
   • notebooklm ask "How does [topic] connect to or differ from related concepts?"
   • notebooklm ask "Describe the key steps, states, or relationships in [topic] that could be drawn as a diagram (e.g. flowchart of an algorithm, state transitions, system components, data structure shape)" — use this to inform diagram generation
4. Synthesize into a structured page using the Note Page Template below
5. Create in Knowledge Base using mcp__claude_ai_Notion__notion-create-pages
6. Log a Study Session entry

Note Page Template:

[TOPIC NAME] — page title

> Course: [course] | Type: [type] | Mastery: ⬜ New

## 🎯 Learning Objectives
- [ ] Understand [core idea]
- [ ] Be able to [apply it]
- [ ] Explain [it simply] without notes

## 📖 Core Explanation
[2-4 paragraphs. Prose, not bullet dump. What → How → Why it matters]

## 💡 Key Definitions
[Table: Term | Definition — 4-8 rows]

## 🔍 Active Recall Questions
> Close this page. Can you answer these from memory?
- ❓ [Question 1–5]

## 🧠 Feynman Explanation
[Plain English analogy. Avoid jargon.]
**Still fuzzy on:** [ ] [gap]

## 💻 Code Example
[Well-annotated example with inline comments explaining WHY]

## 📊 Visual Diagram
[Mermaid code block — include when the topic has a flow, structure, or relationship that benefits
from visualization. See the Mermaid Diagram Guidelines section for which type to use.
Omit this section only if the topic is purely abstract with no meaningful structure to draw.]

```mermaid
[diagram here — e.g. flowchart TD, graph LR, stateDiagram-v2, sequenceDiagram, classDiagram, erDiagram]

⚠️ Common Pitfalls

• ❌ [Mistake] → ✅ [Correct approach]

🔗 Related Concepts

• [Concept A] — [1-line connection]

📝 One-Line Summary

[Single sentence: what + why + when]

**Type-specific additions:**
- **algo**: Add `⏱️ Complexity` section with Time/Space/Best/Worst/Average; diagram = `flowchart TD` of the algorithm steps
- **tech**: Add `🔧 Quick Setup` section; diagram = `graph LR` of component/data flow
- **lecture**: Replace code section with `📋 Lecture Key Points` bullets; diagram = whatever best fits the lecture content
- **concept** (ToC, OS, DB): diagram = `stateDiagram-v2` for automata/process states, `erDiagram` for DB schemas, `graph LR` for concept relationships
- **pattern** (Design Patterns): diagram = `classDiagram` showing class relationships

---

### `/studyflow flashcards <notebook-name-or-id> [--count N] [--cloze] [--topic <topic>]`

Generate flashcards and add them to the Flashcard Vault.

**Default count:** 15. Use `--count N` to override.

**Workflow:**
1. Find and set notebook context
2. Query NotebookLM:
   - Standard: `notebooklm ask "Generate [N] flashcard Q&A pairs. Format: Q: [question]\nA: [answer]\n---"`
   - Cloze: `notebooklm ask "Generate [N] cloze sentences. Format: CLOZE: [sentence with ___]\nANSWER: [fill]\n---"`
3. Parse into individual cards
4. For each card, create entry in Flashcard Vault with:
   - Status: "🆕 New", Ease Factor: 2.5, Interval: 1, Next Review: today, Repetitions: 0

**Quality guidelines:** Atomic cards, test understanding not just recall. Prefer "How does X work?" over "What is X?"

---

### `/studyflow review`

Process today's due flashcards using SM-2 spaced repetition.

**Workflow:**
1. Query Flashcard Vault for cards where Next Review ≤ today
2. Show each card: FRONT → reveal BACK → ask **[E]asy / [H]ard / [A]gain**
3. Apply SM-2:
   - **Again (A):** interval=1, repetitions=0
   - **Hard (H):** interval=max(1, round(interval×1.2)), ease_factor=max(1.3, ef-0.15)
   - **Easy (E):** interval=1 (rep 0), 6 (rep 1), else round(interval×ef); repetitions+=1, ef=min(4.0, ef+0.1)
   - Next Review = today + interval days
4. Status: reps=0→New, 1-2→Learning, 3-5→Review, 6+ and interval>21→Mastered
5. Update Notion card, show summary

---

## SM-2 Algorithm Reference

Again (score=0): interval=1, repetitions=0, ease_factor unchanged Hard (score=3): interval=max(1, round(interval × 1.2)) ease_factor=max(1.3, ease_factor - 0.15) Easy (score=5): if repetitions=0: interval=1 elif repetitions=1: interval=6 else: interval=round(interval × ease_factor) repetitions += 1 ease_factor = min(4.0, ease_factor + 0.1) Next Review = today + interval days

---

## Mermaid Diagram Guidelines

Use Notion's Mermaid code block (Code block → language: `mermaid`) to add diagrams to note pages.
**Always include a diagram when the topic has a flow, hierarchy, state machine, or structural relationship.**
Visual diagrams dramatically improve understanding for complex CSE topics — prioritize them for algorithms, automata, system design, and data structures.

### When to draw a diagram

| Topic type | Draw a diagram when... | Preferred Mermaid type |
|------------|------------------------|------------------------|
| **Algorithm** | The algorithm has steps, branches, or recursion | `flowchart TD` |
| **Data Structure** | There's a visual shape (tree, graph, linked list) | `graph LR` or `graph TD` |
| **Automata / State Machine** (ToC) | DFA, NFA, pushdown automaton | `stateDiagram-v2` |
| **OS Concepts** | Process lifecycle, memory management, scheduling | `stateDiagram-v2` or `flowchart TD` |
| **Database** | Schema relationships, ER model, query plan | `erDiagram` |
| **OOP / Design Patterns** | Class hierarchy, composition, inheritance | `classDiagram` |
| **Network / Protocols** | Request-response, handshake, packet flow | `sequenceDiagram` |
| **System Architecture** | Components, services, data flow | `graph LR` |
| **Compiler Pipeline** | Lexing → parsing → AST → codegen stages | `flowchart LR` |
| **Concept relationships** | How concepts connect or depend on each other | `graph LR` |

### Mermaid syntax quick reference

**Flowchart — algorithm steps, decision trees:**
```mermaid
flowchart TD
    A[Start] --> B{Condition?}
    B -- Yes --> C[Do X]
    B -- No --> D[Do Y]
    C --> E[End]
    D --> E

State diagram — automata, process/OS states:

stateDiagram-v2
    [*] --> New
    New --> Ready : admitted
    Ready --> Running : scheduler dispatch
    Running --> Waiting : I/O request
    Running --> Ready : interrupt
    Waiting --> Ready : I/O complete
    Running --> [*] : exit

Sequence diagram — protocol flows, API calls:

sequenceDiagram
    participant Client
    participant Server
    participant DB
    Client->>Server: POST /login
    Server->>DB: SELECT user WHERE email=?
    DB-->>Server: user record
    Server-->>Client: 200 OK + JWT

Graph — data structures, concept maps, component graphs:

graph LR
    A[Sorting] --> B[Comparison-based]
    A --> C[Non-comparison]
    B --> D[Merge Sort O(n log n)]
    B --> E[Quick Sort O(n log n) avg]
    C --> F[Counting Sort O(n+k)]
    C --> G[Radix Sort O(nk)]

Class diagram — OOP, design patterns:

classDiagram
    class Animal {
        +String name
        +speak() String
    }
    class Dog {
        +fetch()
    }
    class Cat {
        +purr()
    }
    Animal <|-- Dog
    Animal <|-- Cat

ER diagram — database schemas:

erDiagram
    STUDENT ||--o{ ENROLLMENT : has
    COURSE  ||--o{ ENROLLMENT : has
    STUDENT {
        int id PK
        string name
        string email
    }
    ENROLLMENT {
        int student_id FK
        int course_id FK
        date enrolled_on
    }

Decision rule: include vs. skip

Include a diagram if ANY of these are true:

• The topic has 3+ steps that happen in order
• There are states and transitions between them
• There are two or more entities with relationships
• A whiteboard drawing would make this clearer in 30 seconds
• The topic involves a tree, graph, or hierarchical structure

Skip the diagram if ALL of these are true:

• The topic is a definition or theorem with no process or structure
• A diagram would just repeat what the text already says clearly
• There is no meaningful visual representation

How to create in Notion via API

When using mcp__claude_ai_Notion__notion-create-pages, add the diagram as a code block:

{
  "type": "code",
  "code": {
    "language": "mermaid",
    "rich_text": [{ "type": "text", "text": { "content": "flowchart TD\n    A --> B" } }]
  }
}

Notebook Name Resolution

1. PYTHONIOENCODING=utf-8 notebooklm list --json
2. Case-insensitive partial match on title field
3. One match → use it; multiple → ask user; zero → show all and ask

Permanent Notion IDs (do NOT re-create these)

Run /studyflow setup to populate. Then update this section with your IDs.

When creating entries in databases, use data_source_id as the parent type.

/studyflow quiz <notebook-name-or-id>

Import NotebookLM's quiz into the Quiz Bank.

Workflow:

1. Find and set notebook context
2. PYTHONIOENCODING=utf-8 notebooklm generate quiz --json
3. Wait: PYTHONIOENCODING=utf-8 notebooklm artifact wait <artifact_id> --timeout 900
4. Download: PYTHONIOENCODING=utf-8 notebooklm download quiz --format json ./studyflow_quiz_temp.json
5. Parse JSON → create Quiz Bank entries via Notion MCP
6. Delete temp file
7. Also generate 5 short-answer questions via chat: notebooklm ask "Give me 5 short-answer questions with model answers. Format: Q: [question]\nA: [answer]\n---"

/studyflow feynman <notebook-name-or-id> --topic <topic>

Generate or update a Feynman Explanation for a topic.

Workflow:

1. Find the notebook
2. notebooklm ask "Explain [topic] as if you're teaching a curious 12-year-old with no CS background. Use a real-world analogy. Avoid all jargon."
3. notebooklm ask "What are the 3 things that confuse most students about [topic]?"
4. Check if a note for this topic already exists in Knowledge Base (search Notion)
5. If yes: update the Feynman block, set Feynman Done = true
6. If no: create a minimal note page with just the Feynman section + Active Recall

/studyflow study <notebook-name-or-id>

Full study session — runs notes + flashcards + quiz sequentially.

Workflow:

1. Find notebook
2. Ask: "What topic to focus on? (Leave blank for full notebook overview)"
3. Run: notes → flashcards → quiz in sequence
4. Offer: "Review cards now? (10 cards)"
5. Create Study Session log entry
6. Show session summary: notes created, cards created, quiz questions imported

/studyflow brief

Daily study brief — morning overview.

Workflow:

1. Query Flashcard Vault for cards with Next Review ≤ today → count
2. Query Knowledge Base for notes with Last Reviewed > 14 days ago → suggest re-reading
3. Check Study Sessions for streak (consecutive days with sessions)
4. Suggest one notebook to study today

Output:

☀️ StudyFlow Daily Brief — [date]

🃏 Due for review: N cards
📚 Suggested topic: [notebook/topic]
🔁 Study streak: N days
⚠️ Needs revisiting: [topics last reviewed 14+ days ago]

Quick start: /studyflow review
             /studyflow notes "[suggested]"

/studyflow podcast <notebook-name-or-id>

Generate a NotebookLM podcast and extract key insights as a Notion note.

Workflow:

1. Ask confirmation: "Generate a Deep Dive podcast for [notebook]? (~15 min) [Y/n]"
2. PYTHONIOENCODING=utf-8 notebooklm generate audio "Focus on most important concepts and counterintuitive insights" --json
3. While waiting, pre-generate notes via chat:
   • notebooklm ask "What are the 5 most important concepts and the most surprising/counterintuitive thing?"
   • notebooklm ask "What are the key takeaways a student should remember?"
4. Create 🎧 Podcast Notes — [notebook] page in Knowledge Base

/studyflow mindmap <notebook-name-or-id>

Convert a NotebookLM mind map into a Notion page hierarchy.

Workflow:

1. PYTHONIOENCODING=utf-8 notebooklm generate mind-map --json (synchronous/instant)
2. PYTHONIOENCODING=utf-8 notebooklm download mind-map ./studyflow_mindmap_temp.json
3. Parse JSON tree structure
4. Create 🗺️ Concept Map — [notebook] page under course
5. Recursively mirror the hierarchy: top-level → H2, second-level → H3/child pages, leaves → bullets
6. Report: "Created N top-level concepts and M sub-topics"

/studyflow slides <notebook-name-or-id>

Import a NotebookLM slide deck summary into Notion.

Workflow:

1. Ask confirmation (long-running)
2. PYTHONIOENCODING=utf-8 notebooklm generate slide-deck --json
3. While waiting: notebooklm ask "Outline the main sections for a presentation. Format: SLIDE: [title]\nPOINTS: [p1] | [p2] | [p3]\n---"
4. Create 📊 Slide Notes — [notebook] page; each slide → H3 section with key points

/studyflow exam <course-name> --days <N>

Exam preparation mode.

Workflow:

1. Search Knowledge Base + Flashcard Vault for the course
2. Count due cards, mastery distribution
3. Calculate cards_per_day = (total_not_mastered) / days
4. Create 📅 Exam Prep — [course] — [date] page with:
   • Exam date, daily review target, topics not yet covered (⬜ New mastery)
   • Weakest flashcards (lowest Ease Factor), daily schedule template
5. Set all unreviewed cards' Next Review to today (crunch mode)

/studyflow project <project-name>

Create a project page bridging freelance work to curriculum concepts.

Workflow:

1. Ask: "What technologies/concepts are you using in this project?"
2. Create 🔧 [project-name] page under Projects & Freelance with:
   • Tech Stack table (Technology | Purpose | Learning Status)
   • Curriculum Connections: which courses/concepts relate
   • Learning Gaps: technologies used but not in any notebook

/studyflow sync <notebook-name-or-id>

Re-sync an updated notebook — add new content, update existing notes.

Workflow:

1. Find notebook, notebooklm source list --json — note recent additions
2. notebooklm ask "What new concepts does the most recently added content cover?"
3. Search Knowledge Base for existing notes from this notebook
4. New topics not in KB → create note stubs
5. Existing notes → append 📥 Updated Content block
6. Generate N new flashcards for new content only

/studyflow search-youtube <query> [--count N] [--filter lecture|tutorial|short|any] [--add <notebook>]

Search YouTube for videos related to a topic and optionally add selected ones to a notebook.

Workflow:

1. Run yt-dlp in metadata-only mode (no download):

   yt-dlp "ytsearch{count}:{query}" \
     --print "%(title)s\t%(webpage_url)s\t%(duration_string)s\t%(channel)s\t%(view_count)s" \
     --no-playlist --skip-download --no-warnings
   

2. Parse tab-separated output into a ranked list
3. Apply --filter re-ranking (not filtering — avoids zero results):
   • lecture — re-rank by duration desc, prefer >30 min
   • tutorial — re-rank by view count, prefer 5–60 min range
   • short — prefer under 15 minutes
4. Display numbered results with channel, duration, view count
5. If --add <notebook> given, ask which numbers to add → run add workflow for each

Quality guidance for CSE content:

• University lectures: MIT OCW, Stanford, NPTEL, CMU, IIT
• Algorithms/DS: Abdul Bari, William Fiset, NeetCode, Back To Back SWE
• AI/ML: Andrej Karpathy, Lex Fridman, StatQuest
• System design: Gaurav Sen, ByteByteGo

/studyflow add <notebook-name> <source> [--type youtube|web|url]

Add a new source to a NotebookLM notebook — YouTube video, scraped web page, or direct URL.

Source type auto-detection:

• URL contains youtube.com or youtu.be → YouTube
• URL starts with http (non-YouTube) → web
• Local file path → file upload

YouTube workflow:

1. Extract transcript via yt-dlp (VTT → clean text, deduplicate overlapping lines)
2. Try notebooklm source add-url <youtube_url> first (native support)
3. If fails: upload the extracted .txt transcript

Web workflow:

1. Scrape with site-specific selectors (GeeksForGeeks, MDN, Wikipedia, Stack Overflow, generic)
2. Save to temp .txt, upload to NotebookLM

Error handling:

Output Style

• Show progress as you work: "🔍 Querying NotebookLM...", "📝 Creating note page...", "🃏 Adding 15 flashcards..."
• Use tables to summarize results
• End every command with a clear summary: what was created, where to find it in Notion
• Always use PYTHONIOENCODING=utf-8 prefix on all notebooklm commands (Windows Unicode fix)