Slideshow

"The camera is the pickaxe. The slideshow is the museum."

"Every image tells a story. The slideshow tells THE story."

The Slideshow skill presents generated images as linear visual narratives. While the Visualizer creates images, the Slideshow presents them — synthesizing metadata from prompts and mining sidecars into scrollable stories.

---

Philosophy

Images live in directories. Directories accumulate chaos.

A SLIDESHOW.md transforms that chaos into narrative:

• Time-ordered entries create journeys
• Metadata synthesis extracts meaning
• Death-scrollable layout works everywhere
• Encapsulation keeps related files together

Think of it as the museum for your visual mining operation.

---

Stereo Slideshows: YML + MD

"The left eye sees truth. The right eye sees story. Together: depth perception."

A stereo slideshow maintains two complementary files:

File	Role	Purpose
SLIDESHOW.yml	Left Eye	Machine-readable source of truth
SLIDESHOW.md	Right Eye	Human-readable narrative for GitHub

Why Two Files?

SLIDESHOW.yml (Source of Truth):

• Structured data the compiler can read
• Photo metadata, locations, room references
• No prose, just semantic facts
• Stable structure for tooling

SLIDESHOW.md (Narrative View):

• Rich markdown for GitHub display
• Images inline, captions, stories
• Death-scrollable presentation
• Generated FROM the YML

The SYNC Protocol

┌─────────────────────────────────────────────────────────────────┐
│                    STEREO SLIDESHOW SYNC                        │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  SLIDESHOW.yml (left eye)        SLIDESHOW.md (right eye)       │
│  ┌─────────────────────┐         ┌─────────────────────────┐    │
│  │ id: slideshow/pub   │         │ # 📸 Pub Photo Gallery  │    │
│  │ name: Pub Gallery   │  ───▶   │ > *"Opening quote..."*  │    │
│  │ location: room/pub  │  SYNC   │                         │    │
│  │ contents:           │         │ ## Shot 1: The Bar      │    │
│  │   - dir: bar-shot   │         │ ![Alt](bar-shot.png)    │    │
│  │     subject: ...    │         │ **Location:** The Bar   │    │
│  └─────────────────────┘         └─────────────────────────┘    │
│                                                                 │
│  EDIT the YML → SYNC generates MD                               │
│  The YML is the single source of truth                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

SLIDESHOW.yml Format

# SLIDESHOW.yml — Machine-readable slideshow definition
id: slideshow/pub/photos
name: "Pub Photo Gallery"
type: slideshow
location: room/pub              # Links to compiled room
tagline: "Memories from the Gezelligheid Grotto"

# Photo metadata
contents:
  - dir: bar-shot-2026-01-19
    subject: "Marieke at the bar"
    mood: warm
    role: ESTABLISHING
    image: bar-marieke.png

  - dir: palm-cats-2026-01-19
    subject: "Palm with the cats"
    mood: cozy
    role: DETAIL
    image: palm-cats.png

# Optional: narrative hints for MD generation
narrative:
  opening_quote: "The best nights are the ones you almost remember..."
  style_notes: "First-person phone camera, golden hour lighting"

# Compiler uses this to link slideshow to room
compiled:
  room_ref: room/pub
  photo_count: 2

Photo Directory Structure (Stereo)

Each photo can also be stereo:

photo-directory/
  PHOTO.yml          # Left eye: metadata, generation settings
  PHOTO.md           # Right eye: narrative description
  main-image.png     # The actual image
  MINING-*.yml       # Mining layer files

PHOTO.yml (metadata):

subject:
  primary: "Marieke serving drinks"
  secondary: ["Palm", "cats"]
mood: warm
camera:
  type: "iPhone 15 Pro"
  settings: { aperture: 1.8, iso: 800 }
generation:
  provider: dalle3
  prompt: "..."

PHOTO.md (narrative):

# Marieke at the Bar

The warm glow of Edison bulbs catches the brass
fixtures as Marieke pours a perfect pint...

Commands

SYNC SLIDESHOW [directory]

Regenerates SLIDESHOW.md from SLIDESHOW.yml.

CREATE STEREO SLIDESHOW FOR [directory]

Creates both YML (from scanning directory) and MD (from YML).

UPDATE SLIDESHOW YML [directory]

Scans for new photos and updates the YML source of truth.

---

The CREATE Method

Generate a SLIDESHOW.md for a directory of images:

CREATE SLIDESHOW for pub/dons-photos-2026-01-19/

What happens:

1. Discover images in directory (.png, .jpg, .webp)
2. Find sidecars for each image (.yml prompt, -mined.yml resources)
3. Order by timestamp in filename or file creation time
4. Synthesize narrative descriptions from metadata
5. Write SLIDESHOW.md with gallery structure

---

The LANDING Method

Create a README.md landing page for GitHub display:

LANDING for pub/dons-pub-photos-2026-01-19/

Why README.md?

GitHub renders README.md automatically when you browse a directory, but not SLIDESHOW.md. The landing page is the front door — motivating visitors to read the story.

┌─────────────────────────────────────────────────────────────────┐
│  README.md (Landing Page)          SLIDESHOW.md (Story)        │
├─────────────────────────────────────────────────────────────────┤
│  ✓ Shown on GitHub automatically   ✗ Must click to view        │
│  ✓ Metadata table                  Pure narrative flow          │
│  ✓ Character links                 No links — just story        │
│  ✓ Location links                  No context jumps             │
│  ✓ Story summary (fresh!)          Full detailed story          │
│  → "View the slideshow"            The actual experience        │
└─────────────────────────────────────────────────────────────────┘

What goes in README.md:

Section	Content
Title + Tagline	Hook the reader
Gallery Info	Slide count, date, style, location
Featuring	Characters with links to their directories
Locations	Rooms with links to their directories
Story Summary	Fresh synthesis — "why should I look at these?"
Preview	Optional image grid
Technical	Mining layers, generator

Key insight: The story summary is freshly synthesized, not copy-pasted from SLIDESHOW.md. It answers: "What will I experience if I click through?"

Workflow:

1. CREATE SLIDESHOW       # Generate the story
2. ORGANIZE INTO dirname  # Encapsulate files
3. LANDING                # Create GitHub front door

---

The ORGANIZE Method

Encapsulate a SLIDESHOW.md and its images into a named subdirectory:

ORGANIZE pub/SLIDESHOW.md INTO dons-pub-photos-2026-01-19

Before:

pub/
  SLIDESHOW.md
  dons-photos-2026-01-19-16-30-00-bar-marieke-palm-cats.png
  dons-photos-2026-01-19-16-30-00-bar-marieke-palm-cats.yml
  dons-photos-2026-01-19-16-30-00-bar-marieke-palm-cats-mined.yml
  ...20 more files...

After:

pub/
  dons-pub-photos-2026-01-19/
    SLIDESHOW.md          # Inherits from slideshow skill
    bar-marieke-palm-cats.png
    bar-marieke-palm-cats.yml
    bar-marieke-palm-cats-mined.yml
    ...all files moved and renamed...

Naming convention: lowercase-dashes, descriptive, date-suffixed if temporal.

---

SLIDESHOW.md Format

Every SLIDESHOW.md should declare inheritance:

---
inherits: slideshow
title: "Don's Pub Photos — January 19, 2026"
created: 2026-01-19
images: 8
style: first-person-phone-camera
---

Structure

# 📸 Title

> *"Opening quote capturing the vibe"*

Brief description of what this gallery contains.

---

## 📍 Shot 1: Location (Time)

### *"Caption quote"*

![Alt text](image-file.png)

**Location:** Where this was taken

**Who's Here:**
- 👩🌷 Character 1 doing something
- 🐒🌴 Character 2 doing something else

📎 **Files:** [Prompt](image-file.yml) | [Resources](image-file-mined.yml)

---

## 📍 Shot 2: Next Location (Time)

...

---

## 📊 Stats Table

| Time | Location | Highlights |
|------|----------|------------|
| 4:30 PM | Bar | Marieke, Palm, cats |
| ... | ... | ... |

---

## 🎨 Style Notes

Notes on artistic direction, visual consistency, mood.

---

*"Closing quote"*

---

Metadata Synthesis

The SUMMARIZE method transforms raw sidecar data into narrative:

From prompt.yml:

• Scene description → Location
• Characters present → Who's Here
• Time of day → Shot timing
• Artistic style → Style notes

From prompt-mined.yml:

• Dominant colors → Visual palette
• Mood/atmosphere → Emotional tone
• Implied sounds/smells → Sensory details
• Symbolism → Deeper meaning

Output: Human-readable narrative that tells the story.

---

Integration with Visualizer

The Visualizer creates. The Slideshow presents.

┌─────────────────────────────────────────────────────────────────┐
│                      VISUAL PIPELINE                            │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Context YAML     →    Visualizer    →    Image + Sidecars     │
│  (rooms, chars)        (generate)         (.png, .yml)          │
│                                                                 │
│  Image + Sidecars →    Image Miner   →    Resources             │
│                        (extract)          (-mined.yml)          │
│                                                                 │
│  All Files        →    Slideshow     →    SLIDESHOW.md          │
│                        (present)          (narrative)           │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

Visualizer advertises to Slideshow:

# In visualizer/CARD.yml
advertisements:
  SLIDESHOW:
    delegates_to: slideshow
    score: 85
    condition: "After generating images, create/update gallery"

---

Gallery Discovery

Slideshows can be discovered and linked:

# Find all slideshows in adventure-4
find examples/adventure-4 -name "SLIDESHOW.md"

Cross-slideshow navigation:

**Related Galleries:**
- [Palm's Study](../stage/palm-nook/study/palm-study-images/SLIDESHOW.md)
- [Attic Adventures](../attic/dusty-attic-images/SLIDESHOW.md)

---

Why Encapsulate?

Without encapsulation:

pub/
  ROOM.yml
  SLIDESHOW.md
  guestbook.yml
  fireplace.yml
  20 image files...
  20 prompt files...
  20 mining files...
  # Chaos. What belongs together?

With encapsulation:

pub/
  ROOM.yml
  guestbook.yml
  fireplace.yml
  dons-pub-photos-2026-01-19/
    SLIDESHOW.md
    all-related-files...
  rooftop-telescope-images/
    SLIDESHOW.md
    all-related-files...

Benefits:

• Files that belong together STAY together
• Directory name is descriptive
• Easy to move, share, archive
• No pollution of parent directory
• SLIDESHOW.md becomes the index

---

Example Workflow

# 1. Generate images with visualizer
visualize.py character.yml room.yml -p openai

# 2. Mine resources from images
mine.py *.png --depth full

# 3. Create slideshow gallery
CREATE SLIDESHOW for current directory

# 4. Organize into encapsulated directory
ORGANIZE SLIDESHOW.md INTO palm-portrait-session-2026-01-19

# 5. Result: clean, self-contained gallery

---

Death-Scrollable Design

SLIDESHOW.md targets GitHub rendering:

• Mobile-first: Images scale, text wraps
• Death-scrollable: Just keep scrolling
• Inline images: No external links needed
• Collapsible sections: For detailed metadata
• Emoji headers: Visual navigation
• Tables: Stats and comparisons

---

James Burke Connections

Every good slideshow tells a story through connections:

How do these images connect?

• Shot 1 introduces the setting
• Shot 3 shows the characters in that setting
• Shot 5 captures the climax
• Shot 8 is the aftermath, full circle

The metadata enables this synthesis — prompts describe intent, mining reveals what emerged.

---

Commands Reference

Method	Purpose
CREATE	Generate SLIDESHOW.md for directory
UPDATE	Add new images to existing gallery
SUMMARIZE	Synthesize metadata into narrative
ORGANIZE	Encapsulate into subdirectory
COMPARE	Cross-image comparison section

---

🔧 UPGRADE: Legacy Slideshow Migration

Future feature — not yet implemented

UPGRADE is super flexible. Start with ANYTHING:

• Single file with list of prompts (YML or MD)
• Dir full of loose images (reverse-engineer prompts via mining)
• Just prompts (generate images later!)
• Mixed chaos
• Even empty dirs with just ideas

Input option A — Single prompt list file:

my-ideas.yml (or my-ideas.md)

→ Breaks into individual prompts, removes original, creates full structure

Input option B — Dir of images:

messy-folder/
├── 2026-01-19-dusk-scene-v3.png
├── morning-light-final.png
└── random-sketch.jpg

→ Mines images for prompts (mine prompt mode), structures everything

Input option C — Mixed chaos (images + prompts + whatever):

messy-folder/
├── 2026-01-19-dusk-scene-v3.png    # Image → mine for prompt
├── morning-light-final.png          # Image → mine for prompt
├── cool-idea.txt                    # Prompt → generate image later
├── more-prompts.yml                 # Prompt list → break apart
├── frame-03-arrival.png             # Image
├── random-sketch.jpg                # Image
└── notes.md                         # Prompts inline → extract

→ UPGRADE figures it out: images get mined, prompts get structured, everything organized

Output (full structure from any input):

slideshow/
├── README.md              # Front cover / title page
├── SLIDESHOW.yml          # Machine-readable skeleton
├── SLIDESHOW.md           # Formatted narrative view
├── 001-dusk-scene/
│   ├── PHOTO.yml
│   ├── PHOTO.md
│   ├── image.png          # Main — NO timestamp, NO index
│   ├── original.png       # Secondary (preserved original name)
│   └── PROMPT.yml         # Generation prompt (or mined from image)
├── 002-morning-light/
│   ├── image.png          # Main
│   ├── PROMPT.yml         # Mined via image mining if no prompt existed
│   └── ...
├── 003-future-idea/
│   ├── PHOTO.yml          # Metadata ready
│   ├── PROMPT.yml         # Prompt waiting
│   └── (no image.png yet) # Generate later!

Naming rules:

• Main image: image.png — clean, no timestamp, no index prefix
• Secondary images: anything NOT matching image.png pattern
  • Brought along, not shown by default
  • Original filenames preserved as secondary
• All paths: repo-root relative in compiled output

What UPGRADE does:

Handles any mix — figures out what each file is:

• .png/.jpg → image → mine for prompt
• .txt/.md with prose → prompt → generate image later
• .yml with list → prompt list → break apart
• Unknown → bring along as secondary

Then structures everything:

1. Cluster related files by name similarity
2. Create 001-descriptive-name/ directories
3. Images → image.png (main), originals as secondary
4. Mine images for prompts OR use existing prompts
5. Generate PHOTO.yml, PHOTO.md skeletons
6. Remove consumed prompt list files
7. Generate README.md, SLIDESHOW.yml, SLIDESHOW.md

Invoke: UPGRADE path/to/anything (when implemented)

---

Dovetails With

• Visualizer — Creates the images
• Image Mining — Extracts resources
• Storytelling Tools — Narrative structure
• YAML Jazz — Metadata as fuel
• Room — Spatial context
• Character — Who appears

---

See CARD.yml for full specification.