Do Presentation

Quick start

The topic comes from $ARGUMENTS. If empty, ask the user what to present on.

Step 1: Scope the topic

Determine what the presentation covers:

• A single feature? A system overview? A concept explanation?
• Who is the audience? Default: general technical audience, high-school reading level
• How long? Default: 10-15 slides (5-8 minute talk)

Ask the user only if the scope is genuinely ambiguous. Otherwise, make a reasonable call.

Step 2: Research

Spawn an Explore agent to deeply research the topic:

• Read relevant source files, docs, READMEs, and config
• Trace how the feature works end-to-end
• Identify the 3-5 key concepts someone must understand
• Find concrete examples, real data, or code snippets
• Note any diagrams that would clarify architecture or flow

Research output should answer:

1. What is this? (one sentence a teenager could understand)
2. Why does it exist? (the problem it solves)
3. How does it work? (the mechanism, simplified)
4. What are the key parts? (components, steps, or layers)
5. What's interesting about it? (the clever bit, the trade-off, the insight)

Step 3: Design the slide structure

Read CONTENT_GUIDE.md for educational best practices. Structure slides following this proven flow:

1. Title slide (hook + subtitle)
2. The Problem (why this exists — relatable scenario)
3. The Big Idea (one-sentence thesis)
4. How It Works — Overview (diagram or visual)
5-8. Key Concepts (one per slide, with examples)
9. Architecture/Flow Diagram
10. Real Example (concrete, from the actual codebase)
11. Trade-offs / Design Decisions
12. Summary (3 bullet takeaway)
13. Questions / Further Reading

Adjust count based on topic complexity. Aim for one idea per slide.

Step 4: Detect and build the theme

Read THEME_DETECTION.md for the full detection process. Quick version:

1. Search for CSS/design tokens in the repo:
   • **/*.css, **/tailwind.config.*, **/theme.*, **/variables.*, **/tokens.*
   • **/styles/**, **/design-system/**, **/ui/**
2. Extract: accent colors, fonts, border radius, spacing
3. If no design system found, use the clean light fallback theme
4. Build the Marp style: block from extracted tokens

IMPORTANT: All presentations use light backgrounds. Even if the repo's design system is dark, adapt it to light mode. Keep the accent colors and fonts, invert backgrounds to white/light gray, use dark text. See the "Light Mode Mandate" section in THEME_DETECTION.md for the full dark→light token mapping.

Step 5: Collect brand logos

When the presentation mentions companies, products, or branded technologies, pull in their logos for visual polish. Logos appear inline next to brand names or as small icons in tables/lists.

Source priority:

1. Simple Icons (GitHub raw) — 3000+ tech/business brands, monochrome SVGs, no auth

   # Download SVG (slug is lowercase brand name, no spaces)
   curl -s "https://raw.githubusercontent.com/simple-icons/simple-icons/develop/icons/{slug}.svg" \
     -o diagrams/logo-{slug}.svg
   

   Common slugs: anthropic, stripe, github, slack, redis, python, docker, linear, sentry, notion, telegram, postgresql

   To find a slug, check: https://raw.githubusercontent.com/simple-icons/simple-icons/develop/slugs.md

2. Google Favicons — universal fallback, any domain, PNG

   curl -sL "https://www.google.com/s2/favicons?domain={domain}&sz=128" \
     -o diagrams/logo-{name}.png
   

Colorizing SVGs for dark backgrounds:

Simple Icons SVGs have no fill color (default black — invisible on dark slides). Inject a fill:

# White (safe default for dark themes)
sed -i '' 's/<path/<path fill="#e6edf3"/' diagrams/logo-{slug}.svg

# Or use the brand's official color (Simple Icons provides these)
sed -i '' 's/<path/<path fill="#FF6600"/' diagrams/logo-{slug}.svg

Converting SVG to PNG (if needed for Marp compatibility):

# macOS built-in, no dependencies, good quality at 512px
qlmanage -t -s 512 -o diagrams/ diagrams/logo-{slug}.svg 2>/dev/null
mv diagrams/logo-{slug}.svg.png diagrams/logo-{slug}.png

Using logos in Marp slides:

<!-- Inline next to text (small, 24-32px) -->
![w:28](diagrams/logo-anthropic.svg) Anthropic ships Managed Agents

<!-- In a table cell -->
| ![w:24](diagrams/logo-stripe.svg) Stripe | Payment processing |

<!-- Larger, standalone -->
![w:80](diagrams/logo-redis.svg)

Rules:

• Only fetch logos for brands that are central to the slide content, not every passing mention
• Keep logos small (24-32px inline, 64-80px standalone) — they accent, not dominate
• SVGs render directly in Marp with --allow-local-files — prefer SVG over PNG for sharpness
• If a brand isn't in Simple Icons, use Google Favicon as fallback
• Don't spend time on logos if the presentation is internal/informal — this is for polished decks

Step 6: Generate diagrams

For any architectural or flow concepts, create diagrams:

1. Prefer ASCII art in code blocks for simple flows (always renders correctly)
2. Use Mermaid for complex diagrams — check if mermaid-render skill is available:
   • Write .mmd file, render to PNG, embed as image
   • Fallback: include as fenced code block (renders in HTML export)
3. Use tables for comparisons, feature matrices, component lists

Diagram guidelines:

• Max 7 nodes/boxes per diagram (cognitive load limit)
• Label every arrow/connection
• Use the repo's accent color for emphasis nodes

Step 7: Write the Marp markdown

Create the presentation file. Location priority:

1. If user specifies a path, use that
2. If a docs/ directory exists, use docs/presentations/<slug>.md
3. Otherwise, use <repo-root>/presentations/<slug>.md

Marp file structure:

---