@ztffn/presentation-generator-plugin 1.3.3 → 1.3.6

package/skills/presentation-generator/SKILL.md

@@ -9,38 +9,58 @@ description: >
 
 # Presentation Generator
 
-Orchestrates a three-agent pipeline to produce a complete, navigable presentation graph JSON from a user brief and optional source documents.
+Orchestrates a two-agent + script pipeline to produce a complete, navigable presentation graph JSON from a user brief and optional source documents.
 
 ## Pipeline Overview
 
 ```
 User Brief + Documents
         ↓
-  [1] Content Extraction  →  _temp/presentation-content-brief.json
+  [1] Content Extraction   →  _temp/presentation-content-brief.json
         ↓
-  [2] Narrative Design     →  _temp/presentation-outline.md
+  [2] Narrative Design      →  _temp/presentation-outline.md
         ↓
-  [3] User Approval        →  confirm or revise structure
+  [3] User Approval         →  confirm or revise structure
         ↓
-  [4] Design & JSON        →  _temp/presentation-draft.json
+  [4] Graph Generation      →  presentations/{slug}/{slug}.json  (script)
         ↓
-  [5] Delivery             →  import instructions + media checklist
+  [5] Visual Styling        →  styled JSON  (agent)
+        ↓
+  [6] Delivery              →  import instructions + media checklist
 ```
 
+## Phase 0 — Locate Plugin Root
+
+Before any other phase, resolve the plugin root directory. Check the local project path first, then the global path:
+
+```bash
+if [ -f ".claude/plugins/presentation-generator/scripts/outline_to_graph.py" ]; then
+  PLUGIN_ROOT=".claude/plugins/presentation-generator"
+elif [ -f "$HOME/.claude/plugins/presentation-generator/scripts/outline_to_graph.py" ]; then
+  PLUGIN_ROOT="$HOME/.claude/plugins/presentation-generator"
+else
+  echo "ERROR: presentation-generator-plugin not found" && exit 1
+fi
+echo "Plugin root: $PLUGIN_ROOT"
+```
+
+Store `PLUGIN_ROOT` for all subsequent phases. All skill files, scripts, and agent references use this path.
+
 ## Phase 1 — Context Gathering
 
-Parse the user's request to identify:
+Parse the user's request to extract these four fields. Do NOT read or open any files — just note the paths as strings:
 
 1. **What** is being presented (product, project, topic)
 2. **To whom** (audience type, their background, what they care about)
 3. **For what goal** (`pitch`, `demo`, `update`, `internal`, `exploratory`)
-4. **Source documents** — paths to files the user wants to draw from
+4. **Source documents** — file paths mentioned in the request (pass these to the content agent in Phase 2, do not read them yourself)
 
 If no documents are provided, skip Phase 2 and construct a minimal content brief directly from the prompt. Ask the user for any missing critical information:
 - If audience is unclear, ask who the presentation is for
 - If goal is unclear, ask what outcome they want
 
 ## Phase 2 — Content Extraction
+Announce to the user that you are **Executing Phase 2 — Subagent: Content Extraction**
 
 Delegate content extraction to the specialist agent using the Task tool:
 
@@ -49,8 +69,8 @@ Task tool:
   subagent_type: "presentation-content"
   description: "Extract content brief"
   prompt: |
-    Step 1: Load your skill file. Find and read the file matching
-    **/presentation-generator/skills/content-signals/SKILL.md
+    Step 1: Load your skill file. Read this file:
+    {PLUGIN_ROOT}/skills/content-signals/SKILL.md
     — it defines the content brief schema, signal priorities, and validation rules.
 
     Step 2: Read these source documents and extract a structured content brief:
@@ -88,6 +108,7 @@ After the content brief is written, read `_temp/presentation-content-brief.json`
 If any check fails, ask the user ONE targeted question to fill the gap. Do not pass a weak brief to the narrative agent.
 
 ## Phase 3 — Narrative Design
+Announce to the user that you are **Executing Phase 3 — Subagent: Narrative Design**
 
 Delegate narrative design to the specialist agent using the Task tool:
 
@@ -96,10 +117,10 @@ Task tool:
   subagent_type: "presentation-narrative"
   description: "Design narrative outline"
   prompt: |
-    Step 1: Load your skill files. Find and read these three files:
-    - **/presentation-generator/skills/frameworks/SKILL.md
-    - **/presentation-generator/skills/slide-content/SKILL.md
-    - **/presentation-generator/skills/graph-topology/SKILL.md
+    Step 1: Load your skill files. Read these three files:
+    - {PLUGIN_ROOT}/skills/frameworks/SKILL.md
+    - {PLUGIN_ROOT}/skills/slide-content/SKILL.md
+    - {PLUGIN_ROOT}/skills/graph-topology/SKILL.md
 
     Step 2: Read the content brief at _temp/presentation-content-brief.json
 
@@ -116,6 +137,7 @@ Task tool:
 The narrative agent selects a story framework, designs the spine and drill-down structure, and writes a detailed slide outline.
 
 ## Phase 4 — User Approval
+Announce to the user that you are **Executing Phase 4 — Getting User Approval**
 
 Read `_temp/presentation-outline.md` and render it as a folder tree for the user:
 
@@ -145,38 +167,59 @@ Wait for the user to respond:
 
 This loop continues until the user explicitly approves.
 
-## Phase 5 — Design and JSON Generation
+## Phase 5A — Graph Generation (script)
+Announce to the user that you are **Executing Phase 5A — Generating Graph JSON from Outline**
 
-Delegate design and JSON generation to the specialist agent using the Task tool:
+Run the deterministic outline-to-graph converter directly via Bash:
+
+```bash
+python3 "$PLUGIN_ROOT/scripts/outline_to_graph.py" _temp/presentation-outline.md -o presentations/{slug}/{slug}.json
+```
+
+The script:
+- Parses the outline markdown
+- Generates all nodes with correct wrappers, positions, and data fields
+- Wires all edges with bidirectional pairs
+- Runs the validator internally
+- Exits 0 if valid, 1 with errors
+
+If exit non-zero, review the errors and fix the outline. If zero, proceed to Phase 5B.
+
+## Phase 5B — Visual Styling (agent)
+Announce to the user that you are **Executing Phase 5B — Subagent: Visual Styling**
+
+Delegate visual styling to the specialist agent using the Task tool:
 
 ```
 Task tool:
-  subagent_type: "presentation-design"
-  description: "Generate presentation JSON"
+  subagent_type: "presentation-style"
+  description: "Apply visual treatments"
   prompt: |
-    Step 1: Load your skill file. Find and read the file matching
-    **/presentation-generator/skills/graph-json-spec/SKILL.md
-    — it defines the complete JSON schema, allowed fields, banned fields,
-    edge wiring, handle IDs, and positioning grid.
+    Step 1: Load your skill files. Read these two files:
+    - {PLUGIN_ROOT}/skills/slide-recipes/SKILL.md
+    - {PLUGIN_ROOT}/skills/graph-json-spec/SKILL.md
 
-    Step 2: Read the approved outline at _temp/presentation-outline.md
+    Step 2: Read the structurally valid presentation JSON at
+    presentations/{slug}/{slug}.json
 
-    Step 3: Translate the outline into a complete presentation graph JSON.
-    Presentation slug: {slug}
+    Step 3: Read the outline at _temp/presentation-outline.md for context
+    on each slide's purpose and visual intent.
 
-    Step 4: Write the JSON to presentations/{slug}/{slug}.json
+    Step 4: Apply visual treatments to each slide based on the slide-recipes
+    Visual Intent Mapping. Edit only data fields using the Edit tool.
+    Never modify node wrappers, edges, or positions.
 
-    Step 5: Run the validator script and fix any errors until it passes:
-    VALIDATE=$(find -L .claude ~/.claude -path "*/presentation-generator/scripts/validate_draft.py" 2>/dev/null | head -1)
-    python3 "$VALIDATE" presentations/{slug}/{slug}.json
+    Step 5: Run the validator script and fix any errors:
+    python3 "{PLUGIN_ROOT}/scripts/validate_draft.py" presentations/{slug}/{slug}.json
 
     Step 6: Report back with the exact validator terminal output,
-    output path, node count, edge count, and any video placeholders.
+    number of slides styled, and any video/image placeholders.
 ```
 
-The design agent translates each slide into a fully specified graph node, wires all edges with bidirectional pairs, and validates the result.
+The styling agent reads the valid JSON and applies visual treatments (two-column layouts, centered slides, background images, charts) by editing only `data` fields. It cannot break structure.
 
 ## Phase 6 — Delivery
+Announce to the user that you are **Executing Phase 6 — Packaging Presentation**
 
 After `presentations/{slug}/{slug}.json` is written:
 
@@ -189,10 +232,12 @@ After `presentations/{slug}/{slug}.json` is written:
 
 ```
 Import your presentation:
-1. Open the graph editor at /present/plan
+1. Open the graph editor at https://humagreenfield.netlify.app/present/plan
 2. Click "New presentation"
 3. Choose "Import JSON"
 4. Select presentations/{slug}/{slug}.json
+5. Click "Create presentation"
+6. Make final adjustments and manual uploads.
 ```
 
 3. If any slides have video placeholders, list them:
@@ -212,7 +257,9 @@ Replace the PLACEHOLDER string with the returned URL after upload.
 |---|---|---|
 | `presentation-content` | `content-signals` | Extract structured brief from documents |
 | `presentation-narrative` | `frameworks`, `slide-content`, `graph-topology` | Design story structure and slide content |
-| `presentation-design` | `graph-json-spec` | Translate outline to valid graph JSON |
+| `presentation-style` | `graph-json-spec`, `slide-recipes` | Apply visual treatments to valid graph JSON |
+
+Note: Graph structure (nodes, edges, positions) is generated deterministically by `scripts/outline_to_graph.py` in Phase 5A. The `presentation-style` agent in Phase 5B only modifies visual `data` fields.
 
 ## Working Without Documents
 
@@ -241,9 +288,9 @@ All intermediate and output files:
 | File | Created By | Read By |
 |---|---|---|
 | `_temp/presentation-content-brief.json` | Content agent or orchestrator | Narrative agent |
-| `_temp/presentation-outline.md` | Narrative agent | Design agent, orchestrator |
+| `_temp/presentation-outline.md` | Narrative agent | Script + styling agent, orchestrator |
 | `_temp/presentation-plan.md` | Orchestrator | User (approval) |
-| `presentations/{slug}/{slug}.json` | Design agent | User (import) |
+| `presentations/{slug}/{slug}.json` | Script (structure) + styling agent (visuals) | User (import) |
 | `presentations/{slug}/content-brief.json` | Orchestrator (Phase 6) | Reference |
 | `presentations/{slug}/outline.md` | Orchestrator (Phase 6) | Reference |
 | `presentations/{slug}/plan.md` | Orchestrator (Phase 6) | Reference |

package/skills/presentation-generator/presentation-guide.md

@@ -138,7 +138,7 @@ Replace bullet lists with assertion + evidence. The assertion is the headline
 > *Headline:* Mid-market finance teams lose 11 hours a week reconciling what three systems can't agree on
 > [Chart or role-by-role breakdown of where those hours go]
 
-→ Deep dive: *Assertion-Evidence Structure* — Michael Alley; *Presentation Design* — presentation-design skill
+→ Deep dive: *Assertion-Evidence Structure* — Michael Alley; *Slide Recipes* — slide-recipes skill
 
 ### Headlines vs. Titles
 
@@ -301,7 +301,7 @@ For difficult questions: "That's a valid concern. Here's how we thought about it
 | Start in the Middle of Action | Merci Grace — *Giving Presentations* guest insights |
 | Make the Title the Takeaway | Andy Raskin — *Giving Presentations* guest insights |
 | Lead a Movement, Not Just Solve a Problem | Andy Raskin — *Brand Storytelling* guest insights |
-| Assertion-Evidence Structure | Michael Alley — *presentation-design* skill |
+| Assertion-Evidence Structure | Michael Alley — *slide-recipes* skill |
 | State Changes Every 3–5 Slides | Wes Kao — *Giving Presentations* guest insights |
 | Stay in Character | Tristan de Montebello — *Giving Presentations* guest insights |
 | Accordion Method | Tristan de Montebello — *Giving Presentations* guest insights |

package/skills/slide-recipes/SKILL.md

@@ -0,0 +1,326 @@
+---
+name: slide-recipes
+description: >
+  Design decision guide and slide recipes for presentation JSON generation.
+  Maps content signals to slide type, layout, and visual treatment.
+  Includes a reference example with all key patterns.
+user-invocable: false
+---
+
+# Slide Recipes
+
+Design decisions and concrete patterns for presentation JSON. For node schema, edge wiring, and positioning grid, see `graph-json-spec`.
+
+## Visual Intent Mapping
+
+The narrative agent annotates each slide with a `**Visual intent:**` label. Map them to JSON treatments:
+
+| Visual Intent | type | centered | layout | brandFont | Background | lightText | Notes |
+|---|---|---|---|---|---|---|---|
+| `bookend` | content | true | single | true | optional image/color | if dark bg | Cover and CTA slides. showBranding: true |
+| `chapter-opener` | content | false or true | single | false | backgroundImage + overlay | true | Full-bleed image, sets section mood. Max 3 bullet points. |
+| `impact` | content | true | single | false | optional dark color | if dark bg | Single statement, no bullets. Let whitespace do the work. |
+| `workhorse` | content | false | single or two-column | false | none | false | Standard bullets/content. The default treatment. |
+| `evidence` | content or chart | false | single or two-column | false | none | false | Data-forward: chart, table, or comparison. |
+| `breathing-room` | content | true | single | false | backgroundImage + overlay OR style.backgroundColor | true | Minimal text. Visual pause. Resets audience attention. |
+
+When the outline lacks visual intent annotations, infer them:
+- First slide → bookend
+- Last slide → bookend
+- Slide after 2+ consecutive bullet-heavy slides → breathing-room or impact
+- Slide introducing a new topic section → chapter-opener
+- Slide with chart data or comparison → evidence
+- Everything else → workhorse
+
+---
+
+## Design Decisions
+
+### Slide Type Selection
+
+| Content Signal | `type` | Key Fields |
+|---|---|---|
+| Standard text, bullets, headings | `"content"` (default) | `content`, `layout` |
+| Full-viewport data visualization | `"chart"` | `chart` (ChartConfig) |
+| Interactive 3D scene | `"r3f"` | `scene` (R3FSceneConfig) |
+
+Most slides are `"content"`. Use `"chart"` or `"r3f"` only when the content is primarily a visualization.
+
+### Layout Decisions
+
+**When to use `two-column`** — set `layout: "two-column"` and split content on `---`:
+- Comparison: before/after, old/new, us/them
+- Pros/cons: advantages on left, considerations on right
+- Text + chart: explanation on left, `[chart:name]` on right
+- Text + media: bullets on left, `![](image)` on right
+
+Do not force two-column when content is naturally sequential.
+
+**When to center** — set `centered: true` for:
+- Cover and CTA slides
+- Single-message impact slides
+- Transition slides
+
+Set `centered: false` for content-heavy, data, and comparison slides.
+
+**When to use brand font** — set `brandFont: true` for:
+- Cover slide, closing/CTA slide, high-impact single-message slides
+
+Do not use on content-heavy or data slides.
+
+**When to show branding** — set `showBranding: true` and `brandingText` for:
+- Cover, closing, slides likely to be screenshotted
+
+Set `showBranding: false` for immersive slides (R3F, full-bleed video).
+
+### Background Treatment
+
+**Background image** — mood, atmosphere, visual evidence, or impact:
+- Set `backgroundImageOverlay: true` and `lightText: true` when text appears over the image
+- Use Unsplash URLs with `?w=1920&q=80`
+
+**Background video** — cinematic section openers or demo context:
+- Set URL to placeholder: `"PLACEHOLDER: [description of needed video]"`
+- Set `backgroundVideoFit: "cover"`, `backgroundVideoLoop: true`
+- Add to delivery summary
+
+**Text contrast** — set `lightText: true` whenever background is dark:
+- Dark `style.backgroundColor`, `backgroundImage` with overlay, `backgroundVideo`, `type: "r3f"` with dark scene
+
+### Chart Decisions
+
+**Chart title rule** — `label` states the insight, not the data category:
+- Weak: "Revenue Data" → Strong: "Revenue grew 40% QoQ after the pricing change"
+
+**Full-viewport** (`type: "chart"`) — when the data IS the slide.
+**Inline** (`[chart:name]` in content) — when data supports a text argument.
+
+### R3F Scene Decisions
+
+Available scenes:
+- `"rotating-cube"` — interactive cube, good for tech demos. Set `scene.controls: true`.
+- `"particle-field"` — atmospheric particle cloud. Set `scene.controls: false`.
+
+Always set `lightText: true` for R3F slides.
+
+### Topic Badge Conventions
+
+Format: `"NN / Section Name"` for numbered sections (`"01 / Problem"`, `"02 / Solution"`).
+Or plain text: `"Huma Showcase"`, `"Technical Deep Dive"`.
+
+---
+
+## Slide Recipes
+
+Complete `data` field patterns. For field definitions, see `graph-json-spec`.
+
+### Cover / Call to Action
+
+```json
+{
+  "label": "[Title or Ask]",
+  "topic": "[Company or Meeting Context]",
+  "content": "One sentence: what this is and for whom. (Cover) — or — what happens next. (CTA)",
+  "centered": true,
+  "brandFont": true,
+  "showBranding": true,
+  "brandingText": "[company.domain]"
+}
+```
+
+### Standard Bullets
+
+```json
+{
+  "label": "Headline claim that makes the point",
+  "topic": "01 / Problem",
+  "content": "## Headline claim in one sentence\n\n- Specific point with a number or named entity\n- Second point — consequence or contrast\n- Third point — the implication\n\nClosing sentence bridging to the next slide.",
+  "notes": "Talking point not on screen. Time: 2 minutes max.",
+  "centered": false
+}
+```
+
+### Two-Column Comparison
+
+```json
+{
+  "label": "Old Way vs. New Way",
+  "topic": "02 / Solution",
+  "content": "## Today\n- 3 systems, no shared state\n- 11 hours/week reconciling exports\n\n---\n\n## With [Product]\n- Single live record across all systems\n- Reports update in real time",
+  "layout": "two-column",
+  "centered": false
+}
+```
+
+---
+
+## Reference Example
+
+A 7-node presentation demonstrating cover, content, two-column, inline chart, R3F, background image, and closing.
+
+```json
+{
+  "meta": {
+    "name": "Graph-Based Presentations"
+  },
+  "nodes": [
+    {
+      "id": "cover",
+      "type": "huma",
+      "position": { "x": 0, "y": 0 },
+      "data": {
+        "label": "Graph-Based Presentations",
+        "topic": "Huma Showcase",
+        "content": "Non-linear storytelling for technical teams.\n\nNavigate with arrow keys. Press **down** to drill into any topic.",
+        "centered": true,
+        "brandFont": true,
+        "showBranding": true,
+        "brandingText": "huma.energy"
+      },
+      "style": { "width": 180, "height": 70 },
+      "measured": { "width": 180, "height": 70 }
+    },
+    {
+      "id": "problem",
+      "type": "huma",
+      "position": { "x": 240, "y": 0 },
+      "data": {
+        "label": "The Problem",
+        "topic": "01 / Problem",
+        "content": "## Linear tools break complex stories\n\n- Cannot branch based on audience questions\n- Skipping sections breaks the flow\n- No private view for speaker notes during screen share\n\nEvery meeting is different. The presentation should adapt.",
+        "notes": "Pause here and ask: 'Does this match your experience?'",
+        "centered": false
+      },
+      "style": { "width": 180, "height": 70 },
+      "measured": { "width": 180, "height": 70 }
+    },
+    {
+      "id": "problem-detail",
+      "type": "huma",
+      "position": { "x": 240, "y": 150 },
+      "data": {
+        "label": "Value Breakdown",
+        "topic": "03 / Value",
+        "content": "## Flexible narratives\nAdapt flow to audience type and questions in real time\n\n---\n\n## Consistent style\nReuse front-end web styling and components directly\n\n## Professional delivery\nSpeaker notes and timing without the audience seeing them",
+        "layout": "two-column",
+        "centered": false
+      },
+      "style": { "width": 180, "height": 70 },
+      "measured": { "width": 180, "height": 70 }
+    },
+    {
+      "id": "value",
+      "type": "huma",
+      "position": { "x": 480, "y": 0 },
+      "data": {
+        "label": "The Value",
+        "topic": "03 / Value",
+        "content": "## Why this approach wins\n\n[chart:value]\n\nAdapt to the audience. Reuse web components. Deliver with confidence.",
+        "charts": {
+          "value": {
+            "chartType": "radar",
+            "data": [
+              { "axis": "Flexibility", "graph": 95, "traditional": 30 },
+              { "axis": "Visual Quality", "graph": 90, "traditional": 50 },
+              { "axis": "Interactivity", "graph": 85, "traditional": 20 },
+              { "axis": "Ease of Use", "graph": 60, "traditional": 90 },
+              { "axis": "Consistency", "graph": 85, "traditional": 40 }
+            ],
+            "config": {
+              "xKey": "axis",
+              "yKeys": ["graph", "traditional"],
+              "showGrid": true,
+              "showLegend": true
+            }
+          }
+        },
+        "centered": false
+      },
+      "style": { "width": 180, "height": 70 },
+      "measured": { "width": 180, "height": 70 }
+    },
+    {
+      "id": "feat-3d",
+      "type": "huma",
+      "position": { "x": 720, "y": 0 },
+      "data": {
+        "label": "3D Scenes",
+        "topic": "04 / Features",
+        "type": "r3f",
+        "scene": {
+          "component": "rotating-cube",
+          "controls": true,
+          "background": "#1a1a2e"
+        },
+        "content": "Interactive React Three Fiber scene.\n\nDrag to rotate. Scroll to zoom.",
+        "lightText": true
+      },
+      "style": { "width": 180, "height": 70 },
+      "measured": { "width": 180, "height": 70 }
+    },
+    {
+      "id": "feat-bgimage",
+      "type": "huma",
+      "position": { "x": 960, "y": 0 },
+      "data": {
+        "label": "Background Image",
+        "topic": "04 / Features",
+        "content": "## Full-bleed imagery\n\nUpload any image as a slide background. Toggle overlay for text readability.\n\n- Cover/contain fit modes\n- Dark overlay toggle\n- Light text auto-detection",
+        "backgroundImage": "https://images.unsplash.com/photo-1451187580459-43490279c0fa?w=1920&q=80",
+        "backgroundImageFit": "cover",
+        "backgroundImageOverlay": true,
+        "lightText": true,
+        "centered": false
+      },
+      "style": { "width": 180, "height": 70 },
+      "measured": { "width": 180, "height": 70 }
+    },
+    {
+      "id": "end",
+      "type": "huma",
+      "position": { "x": 1200, "y": 0 },
+      "data": {
+        "label": "Get Started",
+        "content": "Fork this template to build your own.\n\nEvery slide, chart, and scene is editable in the graph editor.",
+        "centered": true,
+        "brandFont": true,
+        "showBranding": true,
+        "brandingText": "huma.energy"
+      },
+      "style": { "width": 180, "height": 70 },
+      "measured": { "width": 180, "height": 70 }
+    }
+  ],
+  "edges": [
+    { "id": "e-cover-problem", "source": "cover", "target": "problem", "sourceHandle": "s-right", "targetHandle": "t-left" },
+    { "id": "e-problem-cover", "source": "problem", "target": "cover", "sourceHandle": "s-left", "targetHandle": "t-right" },
+    { "id": "e-problem-value", "source": "problem", "target": "value", "sourceHandle": "s-right", "targetHandle": "t-left" },
+    { "id": "e-value-problem", "source": "value", "target": "problem", "sourceHandle": "s-left", "targetHandle": "t-right" },
+    { "id": "e-problem-detail", "source": "problem", "target": "problem-detail", "sourceHandle": "s-bottom", "targetHandle": "t-top" },
+    { "id": "e-detail-problem", "source": "problem-detail", "target": "problem", "sourceHandle": "s-top", "targetHandle": "t-bottom" },
+    { "id": "e-value-3d", "source": "value", "target": "feat-3d", "sourceHandle": "s-right", "targetHandle": "t-left" },
+    { "id": "e-3d-value", "source": "feat-3d", "target": "value", "sourceHandle": "s-left", "targetHandle": "t-right" },
+    { "id": "e-3d-bgimage", "source": "feat-3d", "target": "feat-bgimage", "sourceHandle": "s-right", "targetHandle": "t-left" },
+    { "id": "e-bgimage-3d", "source": "feat-bgimage", "target": "feat-3d", "sourceHandle": "s-left", "targetHandle": "t-right" },
+    { "id": "e-bgimage-end", "source": "feat-bgimage", "target": "end", "sourceHandle": "s-right", "targetHandle": "t-left" },
+    { "id": "e-end-bgimage", "source": "end", "target": "feat-bgimage", "sourceHandle": "s-left", "targetHandle": "t-right" }
+  ]
+}
+```
+
+---
+
+## Media Delivery Summary Format
+
+After generating the JSON, list any slides with placeholder media:
+
+```
+Slides requiring manual media upload:
+- "Cover" — background video: [description]
+- "Demo" — inline video: [description]
+
+Upload via POST /api/slide-images/upload (multipart/form-data, field: "file")
+Returns { ok: true, key, url } — replace placeholder with returned url
+Accepted: all image/*, video/mp4, video/webm, video/quicktime
+Max size: 50MB
+```