Merge branch 'podcast'

Author: ofriw

.gitignore

@@ -31,3 +31,11 @@ node_modules/
 # AI Tools
 .chunkhound/
 .chunkhound.json
+
+# Generated content
+scripts/output/
+
+# Screenshots
+*.png
+*.jpg
+*.jpeg

scripts/generate-presentation.js

@@ -106,7 +106,7 @@ PRESENTATION STRUCTURE REQUIREMENTS:
   - Discussion prompts or questions to ask students
   - Real-world examples to reference
 ✓ DO: Preserve important code examples as slide content
-✓ DO: Identify which visual components to use (CapabilityMatrix, UShapeAttentionCurve, etc.)
+✓ DO: Identify which visual components to use (CapabilityMatrix, UShapeAttentionCurve, WorkflowCircle, GroundingComparison, ContextWindowMeter, AbstractShapesVisualization, etc.)
 
 ✗ AVOID: Long paragraphs on slides (slides are visual anchors, not reading material)
 ✗ AVOID: More than 5 bullet points per slide
@@ -119,9 +119,10 @@ SLIDE TYPES:
 1. **Title Slide**: Lesson title, learning objectives
 2. **Concept Slide**: Key idea with 3-5 bullet points
 3. **Code Example Slide**: Code snippet with context
-4. **Comparison Slide**: Effective vs ineffective patterns
-5. **Visual Slide**: Custom component (CapabilityMatrix, etc.)
-6. **Key Takeaway Slide**: Summary of section or lesson
+4. **Code Execution Slide**: Step-by-step visualization of execution flows (agent loops, algorithms, workflows)
+5. **Comparison Slide**: Effective vs ineffective patterns
+6. **Visual Slide**: Custom component (CapabilityMatrix, etc.)
+7. **Key Takeaway Slide**: Summary of section or lesson
 
 HANDLING CODE BLOCKS:
 
@@ -136,9 +137,106 @@ For presentation slides:
 ✓ Add context in speaker notes about what the code demonstrates
 ✓ For comparison slides, show ineffective and effective side-by-side
 ✓ Keep code snippets under 15 lines for readability
+✓ EXCEPTION: Textual context flow examples showing agent conversation flows should use "codeExecution" slide type regardless of length (see section below)
 ✗ Don't include every code example from the lesson
 ✗ Don't show code without explaining its purpose
 
+COMPONENT DETECTION (CRITICAL):
+
+The source content contains markers for visual React components in the format:
+[VISUAL_COMPONENT: ComponentName]
+
+Examples you will see:
+- [VISUAL_COMPONENT: AbstractShapesVisualization]
+- [VISUAL_COMPONENT: CapabilityMatrix]
+- [VISUAL_COMPONENT: UShapeAttentionCurve]
+- [VISUAL_COMPONENT: ContextWindowMeter]
+
+**MANDATORY RULE:** When you encounter a [VISUAL_COMPONENT: X] marker, you MUST:
+1. Generate a "visual" slide type (NOT a "concept" slide)
+2. Set "component" field to the exact component name from the marker
+3. Use the surrounding context to write a descriptive caption
+
+Example:
+{
+  "type": "visual",
+  "component": "AbstractShapesVisualization",
+  "caption": "Visual comparison showing cluttered vs clean context"
+}
+
+**DO NOT:**
+- Convert component markers into text bullet points
+- Skip component markers
+- Change the component name
+- Generate a "concept" slide when you see a component marker
+
+If you see [VISUAL_COMPONENT: X] anywhere in the content, it MUST become a visual slide.
+
+CODE EXECUTION SLIDES:
+
+Use the "codeExecution" slide type to visualize step-by-step processes like:
+- Agent execution loops (human input → LLM prediction → agent execution → feedback)
+- Algorithm execution flows
+- Request/response cycles
+- Multi-step workflows
+
+Structure with highlightType for semantic color-coding (uses design system colors):
+- **"human"** (white/neutral): Engineer/operator input, commands, task specifications, explicit constraints
+- **"prediction"** (purple): LLM predictions, reasoning, decisions, "I will..." or "I should..." statements
+- **"execution"** (green): Agent/software tool calls, deterministic actions (Read, Edit, Bash commands)
+- **"feedback"** (purple light): Data/results returned from operations, outputs that LLM receives
+- **"summary"** (white/neutral): Loop conditions, conclusions, final outcomes
+
+SEMANTIC RULES (critical for correct color coding):
+✓ "Engineer specifies task:" → human (operator input)
+✓ "LLM predicts:" or "LLM decides:" → prediction (thinking/planning)
+✓ "Agent executes: Read(...)" → execution (tool call)
+✓ "File content returned:" → feedback (operation result)
+✓ "LLM receives and predicts:" → prediction (NOT feedback - it's the prediction after receiving)
+✓ "Loop continues until..." → summary (loop condition)
+
+✓ Use for "how it works" explanations (3-8 steps typical)
+✓ Include annotations to explain WHY each step happens
+✓ Show the complete cycle from start to finish
+✓ Maintain semantic consistency: what's DOING the action determines the type
+✗ Don't use for static code examples (use "code" type instead)
+✗ Don't create more than 10 steps (split into multiple slides if needed)
+✗ Don't confuse "LLM receives data and predicts" (prediction) with "data returned" (feedback)
+
+RECOGNIZING TEXTUAL CONTEXT FLOW PATTERNS (CRITICAL):
+
+When you see code blocks showing conversation/execution flows with patterns like:
+- "SYSTEM: ... USER: ... ASSISTANT: ... TOOL_RESULT: ..."
+- Sequential back-and-forth between human, LLM, and tools
+- Full execution traces showing how text flows through agent context
+- Examples demonstrating the actual content of the context window
+
+→ These are PEDAGOGICALLY CRITICAL and must be included as "codeExecution" slides
+
+Why these matter MORE than config examples:
+- They show the fundamental mental model of how agents operate
+- They demystify what "context" actually contains
+- They're the core learning insight, not just implementation details
+
+How to handle them:
+1. Break the flow into 8-12 logical steps (not necessarily every line)
+2. Map conversation elements to highlightTypes:
+   - "SYSTEM:" or system instructions → human
+   - "USER:" or task specification → human
+   - "ASSISTANT:" thinking/reasoning → prediction
+   - "<tool_use>" or tool calls → execution
+   - "TOOL_RESULT:" or outputs → feedback
+3. Add annotations explaining the significance of each step
+4. Focus on the FLOW of text through the context, not just the code
+
+Example transformation:
+- Source: 67-line conversation showing full agent execution
+- Slide: 10 steps highlighting key moments in the conversation flow
+- Annotations: "Notice how the tool result becomes input to the next prediction"
+
+PRIORITIZATION: Textual flow examples showing context mechanics trump configuration
+examples like MCP setup. Configuration is implementation; textual flow is understanding.
+
 SPEAKER NOTES GUIDELINES:
 
 For each slide, provide speaker notes with:
@@ -204,23 +302,97 @@ You must generate a valid JSON file with this structure:
       "caption": "Brief explanation",
       "speakerNotes": { ... }
     },
+    {
+      "type": "codeExecution",
+      "title": "Agent Execution Loop Example",
+      "steps": [
+        {
+          "line": "Engineer specifies: 'Add authentication middleware'",
+          "highlightType": "human",
+          "annotation": "Human provides explicit task and constraints"
+        },
+        {
+          "line": "LLM predicts: 'I should read existing auth patterns'",
+          "highlightType": "prediction",
+          "annotation": "Token prediction drives next action"
+        },
+        {
+          "line": "Agent executes: Read(src/middleware/auth.ts)",
+          "highlightType": "execution",
+          "annotation": "Deterministic tool execution"
+        },
+        {
+          "line": "File content returned to context",
+          "highlightType": "feedback",
+          "annotation": "Operation result available to LLM"
+        },
+        {
+          "line": "LLM analyzes patterns and predicts: 'I'll use JWT approach'",
+          "highlightType": "prediction",
+          "annotation": "Prediction incorporates new context"
+        },
+        {
+          "line": "Agent executes: Edit(src/app.ts, old, new)",
+          "highlightType": "execution",
+          "annotation": "Code modification"
+        },
+        {
+          "line": "Loop continues until tests pass",
+          "highlightType": "summary",
+          "annotation": "Iteration condition"
+        }
+      ],
+      "speakerNotes": { ... }
+    },
+
+COMPARISON SLIDE CONVENTION (CRITICAL - HARDCODED IN UI):
+
+The comparison slide type has HARDCODED styling in the presentation component:
+- LEFT side → RED background, RED heading, ✗ icons (ineffective/worse/limited)
+- RIGHT side → GREEN background, GREEN heading, ✓ icons (effective/better/superior)
+
+YOU MUST ALWAYS follow this convention:
+- LEFT: The worse/ineffective/traditional/limited approach
+- RIGHT: The better/effective/modern/superior approach
+
+Correct examples:
+- "Chat Interface" (left) vs "Agent Workflow" (right)
+- "Heavy Mocking" (left) vs "Sociable Tests" (right)
+- "Chat/IDE Agents" (left) vs "CLI Agents" (right)
+- "Traditional RAG" (left) vs "Agentic RAG" (right)
+
+INCORRECT: Putting the better option on the left will show it with RED ✗ styling!
+
     {
       "type": "comparison",
       "title": "Ineffective vs Effective",
       "left": {
-        "label": "Ineffective",
+        "label": "Ineffective",        // MANDATORY: LEFT = worse/ineffective/limited (RED ✗)
         "content": ["Point 1", "Point 2"]
       },
       "right": {
-        "label": "Effective",
+        "label": "Effective",          // MANDATORY: RIGHT = better/effective/superior (GREEN ✓)
         "content": ["Point 1", "Point 2"]
       },
       "speakerNotes": { ... }
     },
+    {
+      "type": "marketingReality",
+      "title": "Marketing vs Reality: What Actually Happens",
+      "metaphor": {
+        "label": "Marketing Speak",
+        "content": ["Metaphorical statement 1", "Metaphorical statement 2"]
+      },
+      "reality": {
+        "label": "Technical Reality",
+        "content": ["Technical explanation 1", "Technical explanation 2"]
+      },
+      "speakerNotes": { ... }
+    },
     {
       "type": "visual",
       "title": "Visual Component",
-      "component": "CapabilityMatrix",
+      "component": "CapabilityMatrix | UShapeAttentionCurve | WorkflowCircle | GroundingComparison | ContextWindowMeter | AbstractShapesVisualization",
       "caption": "Description of what the visual shows",
       "speakerNotes": { ... }
     },
@@ -420,6 +592,90 @@ async function promptSelectFile(files, baseDir) {
 // PROCESSING
 // ============================================================================
 
+/**
+ * Extract visual component names from parsed content
+ * @param {string} content - Parsed markdown content
+ * @returns {string[]} Array of component names
+ */
+function extractExpectedComponents(content) {
+  const componentRegex = /\[VISUAL_COMPONENT: ([A-Za-z]+)\]/g;
+  const components = [];
+  let match;
+
+  while ((match = componentRegex.exec(content)) !== null) {
+    components.push(match[1]);
+  }
+
+  return components;
+}
+
+/**
+ * Validate that all expected visual components appear in the presentation
+ * @param {string} content - Parsed markdown content
+ * @param {object} presentation - Generated presentation object
+ * @returns {object} Validation result with missing components
+ */
+function validateComponents(content, presentation) {
+  const expectedComponents = extractExpectedComponents(content);
+  const visualSlides = presentation.slides.filter(s => s.type === 'visual');
+  const renderedComponents = visualSlides.map(s => s.component);
+
+  const missing = expectedComponents.filter(c => !renderedComponents.includes(c));
+
+  return {
+    expected: expectedComponents,
+    rendered: renderedComponents,
+    missing,
+    allPresent: missing.length === 0
+  };
+}
+
+/**
+ * Validate semantic correctness of comparison slides
+ * Checks that better/effective options are on the RIGHT (green ✓)
+ * and worse/ineffective options are on the LEFT (red ✗)
+ * @param {object} presentation - Generated presentation object
+ * @returns {object} Validation result with potential ordering issues
+ */
+function validateComparisonSemantics(presentation) {
+  const comparisonSlides = presentation.slides.filter(s => s.type === 'comparison');
+  const issues = [];
+
+  // Keywords that indicate a "positive/better" option
+  const positiveKeywords = ['cli', 'effective', 'better', 'modern', 'agentic', 'sociable', 'agent workflow'];
+  // Keywords that indicate a "negative/worse" option
+  const negativeKeywords = ['chat', 'ide', 'ineffective', 'worse', 'traditional', 'mocked', 'chat interface'];
+
+  for (const slide of comparisonSlides) {
+    if (!slide.left || !slide.right) continue;
+
+    const leftLabel = slide.left.label?.toLowerCase() || '';
+    const rightLabel = slide.right.label?.toLowerCase() || '';
+
+    // Check if left side has positive keywords (should be on right instead)
+    const leftIsPositive = positiveKeywords.some(k => leftLabel.includes(k));
+    // Check if right side has negative keywords (should be on left instead)
+    const rightIsNegative = negativeKeywords.some(k => rightLabel.includes(k));
+
+    if (leftIsPositive || rightIsNegative) {
+      issues.push({
+        slide: slide.title,
+        left: slide.left.label,
+        right: slide.right.label,
+        reason: leftIsPositive
+          ? `"${slide.left.label}" appears positive/better but is on LEFT (will show RED ✗)`
+          : `"${slide.right.label}" appears negative/worse but is on RIGHT (will show GREEN ✓)`
+      });
+    }
+  }
+
+  return {
+    valid: issues.length === 0,
+    issues,
+    totalComparisons: comparisonSlides.length
+  };
+}
+
 /**
  * Generate presentation for a file
  */
@@ -462,6 +718,31 @@ async function generatePresentation(filePath, manifest, config) {
     // Generate presentation using Claude
     const presentation = await generatePresentationWithClaude(prompt, outputPath);
 
+    // Validate that all visual components were included
+    const validation = validateComponents(content, presentation);
+    if (!validation.allPresent) {
+      console.log(`  ⚠️  WARNING: ${validation.missing.length} visual component(s) not rendered:`);
+      validation.missing.forEach(c => console.log(`      - ${c}`));
+      console.log(`  ℹ️  Expected: [${validation.expected.join(', ')}]`);
+      console.log(`  ℹ️  Rendered: [${validation.rendered.join(', ')}]`);
+    } else if (validation.expected.length > 0) {
+      console.log(`  ✅ All ${validation.expected.length} visual component(s) rendered correctly`);
+    }
+
+    // Validate comparison slide semantics
+    const semanticValidation = validateComparisonSemantics(presentation);
+    if (!semanticValidation.valid) {
+      console.log(`  ⚠️  WARNING: ${semanticValidation.issues.length} comparison slide(s) may have reversed order:`);
+      semanticValidation.issues.forEach(issue => {
+        console.log(`      - "${issue.slide}"`);
+        console.log(`        LEFT: "${issue.left}" | RIGHT: "${issue.right}"`);
+        console.log(`        ${issue.reason}`);
+      });
+      console.log(`  ℹ️  Remember: LEFT = ineffective/worse (RED ✗), RIGHT = effective/better (GREEN ✓)`);
+    } else if (semanticValidation.totalComparisons > 0) {
+      console.log(`  ✅ All ${semanticValidation.totalComparisons} comparison slide(s) follow correct convention`);
+    }
+
     // Copy to static directory for deployment
     const staticPath = join(STATIC_OUTPUT_DIR, dirname(relativePath), outputFileName);
     mkdirSync(dirname(staticPath), { recursive: true });

scripts/lib/markdown-parser.js

@@ -128,7 +128,11 @@ export function parseMarkdownContent(filePath) {
   // Remove frontmatter
   let cleaned = content.replace(/^---[\s\S]*?---\n/, '');
 
-  // Remove JSX components
+  // Extract and preserve React components (capital letter start = React components)
+  // Replace with clear markers so LLM can detect them
+  cleaned = cleaned.replace(/<([A-Z][a-zA-Z]*)\s*\/>/g, '[VISUAL_COMPONENT: $1]');
+
+  // Remove remaining HTML tags (lowercase = HTML elements)
   cleaned = cleaned.replace(/<[^>]+>/g, '');
 
   // First pass: Find all code blocks and their contexts