1. Analyze the topic -- What is the core insight? What specific value can this deliver?
2. Identify the audience -- What does the target audience NOT already know? What's their current understanding?
3. Auto-detect content vertical and theme -- Use the Content Vertical Detection table below
4. Select the archetype -- Which of the 7 carousel archetypes (see below) fits best? Use the Archetype Selection Guide below. Auto-select unless the user specifies.
5. Design the narrative arc -- Map each archetype role to a renderer slide type using the Role-to-SlideType Mapping below. Ensure each slide creates a curiosity gap that the next slide resolves.
6. Run the Bullshit Test on the outline -- Does every slide pass? (See QUALITY GATE below)

paper_decoder

tool_showdown

breaking_news

tool_tutorial

hot_take

prompt_playbook

industry_map

build_this

founders_money

future_scenario

• Max 4 information chunks per slide (Cognitive Load Theory, Sweller)
• Pattern interrupt every 2-3 slides (diagram, comparison, color shift, or layout change)
• Density wave: H-M-H-M-H-H-M (never 3 high-density slides consecutively)
• Synthesis slide = THE save trigger (Serial Position Effect: last items remembered best)
• Dual-code the hardest concept (Paivio: visual + text = 6.5x retention)
• CTA matches save trigger: utility categories → "Save this", social categories → "Share/Comment"

• paper_decoder

  (9 slides): hook → body → diagram → body → body → diagram → body → synthesis → cta

• tool_showdown

  (8 slides): hook → body → comparison → body → body → comparison → synthesis → cta

• breaking_news

  (8 slides): hook → body → body → body → diagram → body → synthesis → cta

• tool_tutorial

  (8 slides): hook → body → tool → tool → tool → body → synthesis → cta

• hot_take

  (7 slides): hook → body → body → body → body → synthesis → cta (text-driven, no diagrams)

• prompt_playbook

  (9 slides): hook → body → body → body → comparison → body → body → synthesis → cta

• industry_map

  (9 slides): hook → diagram → body → body → body → comparison → diagram → synthesis → cta

• build_this

  (8 slides): hook → body → tool → tool → tool → body → synthesis → cta

• founders_money

  (7 slides): hook → body → body → body → diagram → synthesis → cta

• future_scenario

  (8 slides): hook → body → body → diagram → body → body → synthesis → cta

• Use

  generate-image

  skill (uses

  AI_GATEWAY_API_KEY

  ). Nano-banana-pro requires

  GEMINI_API_KEY

  (often unset) but uses the same underlying model.
• Model:

  google/gemini-3-pro-image-preview

  (primary). Fallback:

  google/gemini-3.1-flash-image-preview

  .
• Output: ~1408x768 landscape. Overlay compensates for portrait stretch on slides.

/api/v1/images/generations

ai_bg

• Photo of person → SUBJECT (preserve face, never modify)
• Screenshot/UI → EVIDENCE (float as holographic panel, stylize frame, preserve content)
• Logo/brand → ANCHOR (small, consistent corner placement)
• Abstract/texture → ATMOSPHERE (background only)

• HYPER-DETAILED (50+ words): materials, lighting, composition, colors, atmosphere. Generic = bad.
• Always end with "absolutely no text, no words, no letters, no watermarks" -- AI models add unwanted text otherwise.
• Declare each input's role explicitly (per A2): "Image 1 is a portrait... Image 2 is a screenshot..."
• Specify depth map (per A4): "subject sharp foreground, screenshots floating midground, atmospheric background"
• Lock light direction (per A3): "single dominant light from upper-left, rim light on subject"
• For editorial portraits: add "ABSOLUTELY NO TEXT NO LOGOS NO MAGAZINE ELEMENTS" or Gemini creates TIME covers.
• Overlay opacity sweet spot: 0.60-0.68 for hooks, 0.55-0.65 for diagrams, 0.65-0.70 for CTA.

• Tool/product visuals: Generate an AI illustration or abstract representation
• Data/charts: Generate AI bar charts or infographics (Gemini 3 Pro handles these well)
• Architecture/flows: Generate AI flowcharts or architecture diagrams
• People: Use text descriptions instead of photos

1. Write the hook (Slide 1) -- Apply the Hook Taxonomy. This slide determines everything.
2. Write each slide -- One idea per slide. No exceptions. Apply the Bullshit Test to each.
3. Map to renderer data format -- For each slide, create the JSON data object matching the slide type's required fields (see Data fields by slide type in RENDERING SCRIPTS).
4. Execute the visual strategy decided in Phase 1.5:
   • Generate AI images per the 2-3 Rule (hook + 1-2 emotional peaks). State each image's telos.
   • Capture browser screenshots for any real tools/products/news referenced.
   • Set

     bg_style

     per the Background Style Selection table.
   • Use

     diagram

     slide type for any process/flow that benefits from a visual.
5. Select Instagram music -- Apply the Music Decision Matrix (see MUSIC SELECTION).
6. Write the caption -- Front-load value in first 2 lines. Include CTA and hashtags.
7. Build the carousel spec JSON -- Assemble all slides into a single spec file for the orchestrator.

• Knuth-Plass optimal line breaking -- no ugly word wraps
• Professional font kerning and ligatures -- Palatino with microtype
• Native vector diagrams -- TikZ flow charts (fallback for simple diagrams)
• AI image integration -- full-bleed Gemini 3 Pro images for hook/CTA/diagram backgrounds
• Gradient backgrounds -- clean TikZ-rendered gradients for text-only slides
• Publication-grade output -- the same engine that typesets academic papers and books

--brand brand.json

{
  "name": "TechStack AI",       // Brand name shown in header
  "logo": "path/to/logo.png",   // Optional: logo image replaces text in header
  "theme": "dark",              // Base theme: warm, clean, dark, earth
  "accent_override": "6366F1",  // Optional: override accent hex (no #)
  "font_serif": "newpxtext",    // LaTeX serif font package (default: Palatino)
  "header_style": "bold",       // Header text: italic, bold, or plain
  "nav_style": "circle",        // Navigation arrow: circle, arrow, none
  "divider_style": "line",      // Dividers: line, ornament (diamond), dots, none
  "corner_radius": "6pt"        // Rounded corner radius for labels/badges
}

tmp/brands/

6366F1

B45309

python3 ~/.claude/skills/world-class-carousel/scripts/render_latex_slide.py \
  --type hook \
  --data hook_data.json \
  --output slide.png \
  --theme dark \
  --brand brands/techstartup.json

• ai_image

  : Accent illustration placed in a card (hook bottom, body bottom)

• ai_bg

  : Full-bleed background with semi-transparent overlay for text readability
• When no AI image is provided, decorative geometric accents fill empty space automatically

**Step 2a: News-editorial style** (matches @therundownai -- single person, big headline):
```bash
python3 scripts/compose_news_hook.py \
  --base tmp/carousel/hook_base.png \
  --output tmp/carousel/slide_01_hook.png \
  --headline "OpenAI just hit $13B ARR making it the fastest-growing software company in history" \
  --category "AI NEWS" \
  --brand "@DailyAINews"

compose_news_hook.py

• Subtle bottom gradient (ease-in, configurable start/strength)
• Small category label above headline
• MASSIVE bold headline (Inter Black, auto-sized 42-72px to fill bottom 35%)
• Optional brand mark top-left
• Clean, minimal -- no slide counter, no CTA, no subhead
• Best for: single-person portrait + news headline

python3 scripts/compose_hook.py \
  --base tmp/carousel/hook_base.png \
  --output tmp/carousel/slide_01_hook.png \
  --headline "THE AI WAR JUST ESCALATED" \
  --subhead "3 moves that changed everything this week" \
  --brand "YOUR BRAND" \
  --category "AI NEWS"

compose_hook.py

• Bottom gradient overlay (0-220 alpha, ease-in curve) for text readability
• Light top gradient for brand area
• Category label (upper-left, e.g., "AI NEWS")
• Brand watermark (centered)
• Word-wrapped bold headline (bottom area, all-caps)
• Optional subheadline
• "SWIPE FOR MORE" CTA with decorative line
• Slide counter (top-right, "1/8")
• Best for: multi-person compositions, face-off style

CRITICAL: Use `/api/v1/images/generations` (NOT `/api/v1/openai/v1/images/generations`). The OpenAI-prefixed endpoint rejects the `images` parameter.

**Alternative: transform_image.py with Flickr URLs (9.5/10)**

When photos are available at Flickr URLs (directly accessible by Vertex AI):

```bash
python3 ~/.claude/skills/generate-image/scripts/transform_image.py \
  "Create a dramatic cinematic photomontage combining these tech leaders. \
  Dark dramatic background with blue and red lighting. Keep faces EXACTLY as they appear." \
  "https://live.staticflickr.com/7832/33377877458_d1a3774615_b.jpg" \
  "https://live.staticflickr.com/5767/30796823531_85932ecaa0_b.jpg" \
  --model "google/gemini-3-pro-image-preview" \
  --output tmp/carousel/hook_base.png

• Use Creative Commons (CC BY 2.0+) photos from Flickr, Wikimedia Commons
• Flickr URLs accessible by Vertex AI; Wikimedia URLs often blocked
• Use

  urllib.request

  with browser User-Agent for Wikimedia downloads to local files
• For local-only files (Wikimedia downloads), use the base64 approach above
• Include CC attribution in carousel caption

pip install rembg  # One-time setup

• 7-10 slide PNG images at 1080x1350
• Caption text with hashtags
• Music recommendation (Instagram track names + artists)
• Posting notes (best time, engagement strategy)

"Claude Code has a memory problem. Here's how to fix it for free."

"Stop using RAG. There's a better way."

"This setup saved me 4 hours per week of prompt debugging."

"Your AI agent's memory works like a messy desk. Here's how to organize it."

"90% of developers use Claude Code wrong. Are you one of them?"

"Obsidian + Claude Code = unlimited AI memory"

• FAIL: "Use the right tools for the job"
• PASS: "Obsidian's graph view lets Claude Code traverse 10x more documents by following wiki-links between markdown files"

• FAIL: "AI is changing the world"
• PASS: "By creating bidirectional links between your docs, you turn Claude Code's context window into a navigation system instead of a storage container"

• FAIL: "There are many benefits to using this approach, including several key advantages that make it worthwhile"
• PASS: "3 benefits: 10x doc navigation, auto-linked memory, zero-config setup"

• Maximum 2 fonts per carousel
• Title font and body font must pair well
• NEVER go below 24px for any text the reader must understand
• Consistent across ALL slides

• Background:

  #0D1117

  (deep dark) or

  #1A1A2E

  (midnight blue)
• Primary text:

  #E6EDF3

  (near-white) or

  #F0F6FC

• Accent:

  #7C3AED

  (electric purple) or

  #3B82F6

  (bright blue)
• Secondary:

  #6B7280

  (muted gray)

• Background: Linear gradient

  #F97316

  to

  #EAB308

  (warm amber) or

  #FFF7ED

  (cream)
• Primary text:

  #1C1917

  (near-black)
• Accent:

  #DC2626

  (confident red) or

  #F59E0B

  (gold)
• Secondary:

  #78716C

  (warm gray)

• Background:

  #FFFFFF

  (clean white) or

  #F8FAFC

  (cool off-white)
• Primary text:

  #0F172A

  (dark slate)
• Accent:

  #2563EB

  (trust blue) or

  #0EA5E9

  (sky blue)
• Secondary:

  #64748B

  (slate gray)

• Background:

  #18181B

  (charcoal) or

  #FAFAFA

  (near-white)
• Primary text: Inverse of background
• Accent: ONE bold color (

  #EC4899

  magenta,

  #10B981

  emerald, or

  #F59E0B

  amber)
• Secondary:

  #71717A

  (zinc)

• Background:

  #F5F0EB

  (warm neutral) or

  #1B3A2D

  (forest dark)
• Primary text:

  #2D2416

  (earth brown) or

  #E8E0D5

  (warm light)
• Accent:

  #16A34A

  (forest green) or

  #B45309

  (amber earth)
• Secondary:

  #8B7355

  (warm mid-tone)

1. Canvas: 1080 x 1350 px (4:5 portrait) -- ALWAYS
2. Margins: 60px minimum on all sides
3. Safe Zone: Center 80% (top/bottom 10% may be occluded by Instagram UI)
4. One idea per slide: If a slide has two ideas, split it into two slides
5. Visual anchor: Every slide needs ONE dominant visual element
6. Breathing room: Content should never feel cramped -- generous whitespace signals quality

1. Text-heavy carousels: ALWAYS instrumental only (vocals compete with reading)
2. Visual-heavy carousels: Vocals acceptable (separate processing channels)
3. Trending audio: Use ONLY if it genuinely fits the content type. Mismatched trending sounds damage authenticity
4. Trending audio lifecycle: Discovery (Day 0-3, max boost) -> Growth (Day 3-14, good) -> Peak (Day 14-30, OK) -> Saturation (Day 30+, skip)
5. Output format: Provide 2-3 track recommendations with artist name, track name, and why it fits

• Save Rate is the #1 signal. Design every carousel to be save-worthy. Include a synthesis/mental-model slide.
• 10-slide carousels outperform shorter ones by ~30% in save rate
• Dwell time: More slides = more time on post = algorithm reward
• Music adds ~15-30% reach boost
• Re-engagement: Instagram re-shows carousels to users who did not swipe all the way through
• First hour: Posts saved within the first hour get exponential distribution
• Hashtags: Put in caption (not first comment). 5-15 total.

hook

body

comparison

diagram

synthesis

cta

warm

clean

dark

earth

python3 ~/.claude/skills/world-class-carousel/scripts/render_latex_slide.py \
  --type body \
  --data body_data.json \
  --output slide.png \
  --theme dark \
  --brand brand_config.json

• hook:

  title

  ,

  title_highlight

  ,

  subtitle

  ,

  callout

  ,

  ai_bg

  ,

  overlay_opacity

  ,

  logos[]

• body:

  title

  ,

  title_highlight

  ,

  body

  ,

  bullets[]

  ,

  bg_style

• comparison:

  title

  ,

  subtitle

  ,

  columns[{name, items[{label, value}]}]

  ,

  bg_style

• diagram:

  title

  ,

  description

  ,

  diagram_nodes[{label, desc}]

  ,

  diagram_type

  (vertical/horizontal),

  ai_bg

  ,

  overlay_opacity

• synthesis:

  title

  ,

  points[]

  ,

  bg_style

• cta:

  title

  ,

  cta_text

  ,

  handle

  ,

  stats[]

  ,

  ai_bg

  ,

  overlay_opacity

• All types:

  slide_num

  ,

  total_slides

  ,

  show_nav

  ,

  ai_bg

  (full-bleed background),

  overlay_opacity

  ,

  bg_style

1. Intellectual Density: One INSIGHT per slide, not just one idea (insight = non-obvious connection between two known things)
2. Visual Craftsmanship: Every pixel intentional. Margins mathematical. Colors from a system.
3. Hook Specificity: "I tested 1,247 prompts across 6 models" not "5 Tips for Better Prompts"
4. Narrative Completeness: Each slide creates a question the next answers. Final slide ties back to hook.
5. Proof Over Claims: Screenshots, before/after comparisons, specific metrics -- not "this is great"
6. Typography as Design: The way words are sized, spaced, and placed tells the story VISUALLY
7. Strategic Restraint: Know what to leave OUT. Negative space is a design choice.
8. Music-Content Resonance: BPM matches reading pace. Genre signals the tribe.
9. Save-Worthy Synthesis: Last content slide is a mental model / framework diagram worth saving
10. Authentic Voice: Written as one expert talking to a colleague. Never "content creator voice."

• First slide passes the 1.3-second scroll-stop test
• Every slide passes the Bullshit Test (Specific, Novel, Dense)
• One idea per slide, no exceptions
• Typography readable at mobile size (24px+ body text)
• Color palette consistent across all slides
• Narrative arc complete (tension -> resolution)
• Each slide creates curiosity for the next
• Last content slide has a save-worthy synthesis (mental model, framework, diagram)
• CTA slide is clear and specific
• Music recommendation matches content type and audience
• Aspect ratio is 1080x1350 (4:5)
• All content within safe zone (not occluded by UI)
• Caption front-loads value in first 2 lines
• 5-15 hashtags with proper distribution (broad + niche + community + branded)
• Alt-text provided for accessibility
• Every rendered slide visually inspected (no half-empty slides)
• Synthesis title < 4 words
• Synthesis points are flat strings, not dicts
• JSON data passed via temp files, not inline in bash
• Hook/CTA slides use

  ai_bg

  for visual topics; body slides stay text-only
• AI images prompted with "no text" to prevent unwanted labels
• Overlay opacity 0.60-0.68 for hooks, 0.65-0.70 for CTA
• All KNOWN_ISSUES.md rules checked before delivery

KNOWN_ISSUES.md

• MAX 60 lines. Contains ONLY compressed, actionable rules.
• Format: one-line rules grouped by category. No narratives, no session history.
• When adding a new rule: check if it supersedes an existing rule. If yes, REPLACE the old rule. Never append duplicates.
• Read this file at the START of every carousel session to avoid known pitfalls.

session-archives/

• Verbose session logs go here as timestamped files:

  session-archives/YYYY-MM-DD-topic.md

• Include: full experiment data, scoring matrices, debug traces, before/after comparisons.
• These files are NEVER loaded into context unless explicitly requested by the user.
• They exist as raw data for future deep-dives, not as operational knowledge.

1. Check KNOWN_ISSUES.md -- Does this session reveal a new rule? Add it (max 1 line). Does it supersede an old rule? Replace it.
2. Archive verbose data -- If the session involved experiments, debugging, or research, write a session archive file.
3. Compress, don't accumulate -- The goal is a fixed-size knowledge base that gets BETTER over time, not BIGGER.

• BAD: "In session on March 10, we discovered that passing synthesis points as dicts causes an AttributeError because the renderer at line 870 does escape_latex(pt) directly on each point" (38 words)
• GOOD: "Synthesis

  points[]

  must be FLAT STRINGS, not dicts. Renderer does

  escape_latex(pt)

  directly." (12 words)