@ztffn/presentation-generator-plugin 1.0.0

package/skills/presentation-generator/narrative/slide-content.md

@@ -0,0 +1,193 @@
+# Slide Content Quality Guide
+
+How to write individual slide content at a high quality level.
+No layout, design, or slide-type references — narrative quality only.
+
+## Density Rules
+
+**One key message per slide.** Supporting points add depth to that message, not new messages.
+
+- If a slide has two competing claims, split it into two slides
+- If removing a bullet doesn't weaken the key message, remove it
+- If the audience can't state what the slide was about in one sentence, it's too dense
+
+## The One Thing
+
+Before writing any slide content, name the one thing the audience should remember from this slide. Every bullet, every data point, every quote must support that one thing — or it gets cut. If you can't state it in a single sentence, the slide has two messages and needs to be two slides.
+
+## Assertion-Evidence Structure
+
+The strongest slides pair an assertion (the headline) with evidence that proves it — not more assertions in bullet form. Evidence is visual: a chart, a comparison, a quote, a number with context. It does not repeat the headline in text.
+
+**Weak — assertion + more assertions:**
+Title: "Our platform is faster and cheaper"
+- Response time improved significantly
+- Infrastructure costs decreased
+- Customer satisfaction increased
+
+**Strong — assertion + evidence:**
+Headline: "Response time dropped 60% — infrastructure cost followed"
+[Chart: response time and monthly cost, both declining over 6 months]
+
+When evidence is visual, your spoken narration explains what it means instead of reading bullets aloud.
+
+## Spoken vs. Shown
+
+| Show on Slide | Speak Aloud |
+|---|---|
+| Headline claim | Why it matters to this specific audience |
+| Visual evidence | Interpretation — what the data means |
+| Specific numbers | The story behind the number |
+| Call to action | The stakes of not acting |
+| Navigation cue (notes) | Anticipated objections and how to handle them |
+
+The most common failure: slides containing everything the presenter plans to say. If the audience can read it, they will — and they'll tune out while the presenter catches up. Slides are visual anchors for a spoken argument, not scripts.
+
+## Titles vs. Headlines
+
+**Titles are labels.** They name the topic.
+**Headlines make claims.** They tell the audience what to think.
+
+| Title (weak) | Headline (strong) |
+|---|---|
+| "Market Overview" | "The market has shifted to outcome-based pricing" |
+| "Our Technology" | "One integration replaces three legacy systems" |
+| "Q3 Results" | "Q3 revenue exceeded forecast by 18%" |
+| "Team" | "12 engineers with 200+ years of combined industrial experience" |
+
+Use headlines on the spine (main flow). Titles are acceptable on drill-down detail slides where the parent headline provides context.
+
+## Speaker Notes
+
+Notes should add context the presenter says aloud, not repeat what's on screen.
+
+**Bad notes (repetition):**
+> "This slide shows our Q3 results. Revenue was $8.2M."
+
+**Good notes (context):**
+> "Pause here if the audience asks about regional breakdown — the drill-down below has that data. Key talking point: the Oslo pilot drove 40% of Q3 growth."
+
+Notes should include:
+- Talking points not on the slide
+- Audience-specific framing ("For technical audiences, emphasize...")
+- Anticipated questions and how to handle them
+- Transition language to the next slide
+- Time guidance ("Spend max 2 minutes here")
+
+## When to Use Comparison
+
+Use comparison (two sides of the same question) when:
+- There is a clear before/after contrast
+- Two approaches are being weighed
+- The audience needs to see a trade-off
+- A competitive positioning argument needs visual clarity
+
+Do not force comparison when there is no natural duality.
+
+## When Content Warrants a Drill-Down
+
+Content belongs on a drill-down (vertical branch) when:
+- It supports the spine message but isn't essential to the main story arc
+- It answers "how?" or "why?" in more detail than the spine needs
+- It is evidence or data that a skeptical audience may want to inspect
+- It addresses a specific objection or concern
+- It is technical detail for a technical sub-audience
+
+Content stays on the spine when:
+- Removing it would break the narrative logic
+- The audience needs to see it to understand the next spine node
+- It is the key message itself, not supporting evidence
+
+## Framing Data as Story
+
+Data on a slide must be framed — the audience should know what the number means, not just what the number is.
+
+**Number without frame:**
+> "40% reduction"
+
+**Number with frame:**
+> "40% reduction — enough to pay back the installation cost in 14 months"
+
+**Framing pattern:** State the metric, then immediately state what it means for the audience. Use "enough to...", "which means...", "equivalent to...", or "compared to..." as connectors.
+
+## Content Ordering Within a Slide
+
+1. **Headline** — the claim this slide makes
+2. **Context** — one sentence of setup if the headline isn't self-evident
+3. **Evidence** — bullets, data, or quotes that support the headline
+4. **Implication** — what this means for the audience (optional — sometimes the headline is the implication)
+
+## Transition Thinking
+
+Each slide should have an implicit connection to the next. The narrative agent should include a brief transition note in the outline indicating how each slide leads to the next.
+
+- "This problem creates an opportunity for..."
+- "Having seen the evidence, the question becomes..."
+- "With this foundation in place, we can now show..."
+
+## What Is vs. What Could Be
+
+The most persuasive presentations alternate between the current reality and the possible future, repeatedly widening the gap between them. Each cycle deepens the audience's investment before the solution arrives.
+
+1. **What is:** The current state — the friction, cost, or missed opportunity the audience recognizes
+2. **What could be:** What changes if the problem is solved — specific, concrete, desirable
+3. **Repeat:** Each spine node can echo this cycle before the solution appears
+4. **Close with new bliss:** The final slides show the world after adoption — not just the product
+
+The audience should feel the gap before they hear the answer. A problem slide without a vivid "what could be" creates intellectual understanding but not urgency. The tension between the two states is what motivates action.
+
+## Principles from Expert Practice
+
+These complement the quality rules above. Apply them when writing any slide content.
+
+**Lead with a named shift, not a pain.** The strongest problem slides don't just describe a pain — they name a change in the world that makes the old approach obsolete. "Managing inventory is difficult" is a pain. "Same-day delivery expectations have made batch inventory management structurally incompatible with customer demands" is a named shift. The shift creates urgency the pain does not.
+
+**The audience is the hero.** Slides should speak to "your situation," "your team," "your outcome" — not "our product" — until evidence has been established. Position the presenter as a guide providing tools, not as the protagonist of the story. (Mike Maples Jr: "Your job is to be Obi-Wan, not Luke.")
+
+**Establish stakes in the first substantive slide.** The audience must know what's at risk within 60 seconds of the opening. If the cost of inaction isn't clear on the problem slide, the rest of the presentation is solving a problem they don't yet believe they have. (Matthew Dicks: "We have to be worried about something.")
+
+**Answer "why now?"** Whatever problem you lead with, state why it is acute *at this moment* — a technology shift, a cost inflection, a regulatory change, a market move. Without it, the audience files the problem as "interesting" rather than "urgent." One sentence is enough.
+
+**Make the key message citable.** Every headline should be repeatable in a hallway conversation after the meeting. If an executive can't paraphrase it in one sentence without looking at the slide, the claim isn't sharp enough. (Yuhki Yamashata: "You know you've done your job when an exec cites your insight in a meeting without prompting.")
+
+## Before/After: Worked Rewrite
+
+Same content, different quality. Study what changed and why.
+
+---
+
+**BEFORE (weak)**
+
+*Title:* The Problem
+
+*Content:*
+- Companies struggle with managing data across multiple systems
+- Current tools are inefficient and time-consuming
+- Teams waste hours on manual processes
+
+*Speaker notes:* "This slide explains the problem we're solving."
+
+---
+
+**AFTER (strong)**
+
+*Headline:* Mid-market finance teams lose 11 hours a week reconciling what three systems can't agree on
+
+*Content:*
+- Finance: 3 hours/week merging exports from ERP, CRM, and billing into one spreadsheet
+- Operations: 4 hours/week chasing approval chains across email and Slack
+- Leadership: 4 hours/week rebuilding reports that were accurate yesterday but not today
+  → Every one of these hours disappears when systems share a single live record
+
+*Speaker notes:* "Pause after the headline. Let the number land — if anyone nods, they're your champion in the room. The '11 hours' anchors the cost before anything about the product has been shown. If someone pushes back ('we solved this with Salesforce'), the drill-down below has the integration story. Spend no more than 2 minutes here; the goal is recognition, not proof."
+
+---
+
+**What changed:**
+
+| Element | Before | After |
+|---|---|---|
+| Title | Topic label ("The Problem") | Specific, quantified claim |
+| Bullets | Generic descriptions | Named roles with concrete hour counts |
+| Implication | Absent | Explicit (→ connector) |
+| Speaker notes | Repetition of screen content | Anticipation, objection routing, time guidance |

package/skills/presentation-generator/system/edge-conventions.md

@@ -0,0 +1,92 @@
+# Edge Conventions
+
+Authoritative reference for wiring navigation edges in the presentation graph.
+Edges define valid navigation paths — without correct edges, arrow keys won't work.
+
+## Handle IDs
+
+Eight handle IDs exist, four source and four target:
+
+| Handle ID | Type | Position | Navigation |
+|---|---|---|---|
+| `s-right` | source | Right side | Pressing **right arrow** follows this edge |
+| `s-left` | source | Left side | Pressing **left arrow** follows this edge |
+| `s-bottom` | source | Bottom | Pressing **down arrow** follows this edge |
+| `s-top` | source | Top | Pressing **up arrow** follows this edge |
+| `t-right` | target | Right side | Arrived via **left arrow** from source |
+| `t-left` | target | Left side | Arrived via **right arrow** from source |
+| `t-bottom` | target | Bottom | Arrived via **up arrow** from source |
+| `t-top` | target | Top | Arrived via **down arrow** from source |
+
+## Bidirectional Pair Rule
+
+**Every navigation edge must have a return edge** with swapped source/target and swapped handles.
+
+If the user can press right to go from A to B, they must be able to press left to go from B back to A.
+
+## Standard Edge Pairs
+
+### Horizontal Forward/Back (Spine Navigation)
+
+```json
+{ "id": "e-a-b", "source": "a", "target": "b", "sourceHandle": "s-right", "targetHandle": "t-left" }
+{ "id": "e-b-a", "source": "b", "target": "a", "sourceHandle": "s-left", "targetHandle": "t-right" }
+```
+
+A → (right) → B and B → (left) → A
+
+### Drill-Down / Return-to-Parent
+
+```json
+{ "id": "e-parent-child", "source": "parent", "target": "child", "sourceHandle": "s-bottom", "targetHandle": "t-top" }
+{ "id": "e-child-parent", "source": "child", "target": "parent", "sourceHandle": "s-top", "targetHandle": "t-bottom" }
+```
+
+Parent → (down) → Child and Child → (up) → Parent
+
+### Horizontal Within a Drill-Down Branch
+
+Siblings within a drill-down branch use the same horizontal pattern:
+
+```json
+{ "id": "e-child1-child2", "source": "child1", "target": "child2", "sourceHandle": "s-right", "targetHandle": "t-left" }
+{ "id": "e-child2-child1", "source": "child2", "target": "child1", "sourceHandle": "s-left", "targetHandle": "t-right" }
+```
+
+## Edge ID Convention
+
+Use descriptive hyphenated strings:
+
+- `e-cover-problem` — cover to problem
+- `e-problem-cover` — problem back to cover
+- `e-problem-detail` — problem drill-down to detail
+- `e-detail-problem` — detail return to problem
+
+Pattern: `e-{source}-{target}` using the node IDs or abbreviated forms.
+
+## Validation Checklist
+
+Run this checklist before writing the final JSON:
+
+1. **Every node has at least one outgoing edge** — no dead ends
+2. **Every forward edge has a paired return edge** — source/target swapped, handles swapped
+3. **All handle IDs are from the valid set** — only the 8 IDs listed above
+4. **Source handles start with `s-`** and target handles start with `t-`
+5. **The first spine node has no incoming `s-right` edge** — it's the leftmost entry point
+6. **The last spine node has no outgoing `s-right` edge** (or loops back to cover)
+7. **Drill-down children always have `s-top`/`t-bottom` return edge to parent**
+8. **No duplicate edge IDs**
+
+## Edge Object Structure
+
+```json
+{
+  "id": "e-cover-problem",
+  "source": "cover",
+  "target": "problem",
+  "sourceHandle": "s-right",
+  "targetHandle": "t-left"
+}
+```
+
+All four fields (`source`, `target`, `sourceHandle`, `targetHandle`) are required. Edges without explicit handles will have direction inferred from node positions, but this is a fallback — always set handles explicitly.

package/skills/presentation-generator/system/layout-templates.md

@@ -0,0 +1,310 @@
+# Layout Templates & Design Decisions
+
+Decision guide for the design agent. Maps content signals from the slide outline
+to the correct visual treatment in the graph JSON.
+
+## 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 `---` when:
+
+- **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
+- **Dual evidence:** two independent supporting points side by side
+
+Do not force two-column when content is naturally sequential.
+
+### When to Center
+
+Set `centered: true` for:
+
+- **Cover slides:** Title + subtitle, branded
+- **Call-to-action slides:** Single message, end of presentation
+- **Single-message impact slides:** One powerful statement or quote
+- **Transition slides:** Brief pause between major sections
+
+Set `centered: false` for:
+
+- **Content-heavy slides:** Bullets, tables, code, multiple paragraphs
+- **Data slides:** Charts with explanatory text
+- **Comparison slides:** Two-column layouts
+
+### When to Use Brand Font
+
+Set `brandFont: true` for:
+
+- Cover slide (first slide)
+- Closing/CTA slide (last slide)
+- High-impact single-message slides
+
+Do not use on content-heavy or data slides — brand fonts are display fonts, not body fonts.
+
+### When to Show Branding
+
+Set `showBranding: true` and `brandingText: "huma.energy"` (or client name) for:
+
+- Cover slide
+- Closing slide
+- Any slide where the audience might screenshot or reference later
+
+Default is `true`, so only set `showBranding: false` for immersive slides (R3F, full-bleed video) where the overlay is distracting.
+
+## Background Treatment
+
+### Background Image
+
+Use `backgroundImage` when the outline indicates:
+- A mood or atmosphere for a section opener
+- Visual evidence (photo of a product, facility, or result)
+- Impact slide where imagery reinforces the message
+
+Set `backgroundImageOverlay: true` and `lightText: true` when text appears over the image.
+
+**Image sourcing:** Use external URLs directly. Unsplash with query params works well:
+```
+https://images.unsplash.com/photo-XXXXX?w=1920&q=80
+```
+
+### Background Video
+
+Use `backgroundVideo` for cinematic section openers or demo context.
+
+**Video sourcing is deferred.** For any slide requiring background video:
+1. Set `backgroundVideo` to a placeholder: `"PLACEHOLDER: [description of needed video]"`
+2. Set `backgroundVideoFit: "cover"` and `backgroundVideoLoop: true`
+3. Add the slide title to the delivery summary for manual upload
+
+### Inline Video
+
+For videos embedded in slide content (via `![alt](url)` in markdown):
+1. Set the URL to a placeholder: `"PLACEHOLDER: [description]"`
+2. Configure `inlineVideoControls`, `inlineVideoAutoplay`, `inlineVideoLoop` as appropriate
+3. Add to delivery summary
+
+### Text Contrast
+
+Set `lightText: true` whenever the background is dark:
+- Dark `style.backgroundColor`
+- `backgroundImage` with `backgroundImageOverlay: true`
+- `backgroundVideo` slides
+- `type: "r3f"` with dark scene background
+
+## Chart Decisions
+
+### Full-Viewport Chart (`type: "chart"`)
+
+Use when the data IS the slide — the chart is the primary message, not supporting evidence.
+
+```json
+{
+  "type": "chart",
+  "chart": {
+    "chartType": "bar",
+    "data": [...],
+    "config": { "xKey": "quarter", "yKeys": ["revenue", "cost"], "showGrid": true, "showLegend": true }
+  },
+  "content": "Optional caption below the chart"
+}
+```
+
+### Inline Chart (`[chart:name]` in content)
+
+Use when data supports a text argument — the chart is evidence, not the headline.
+
+```json
+{
+  "content": "## Why this approach wins\n\n[chart:comparison]\n\nAdapt to the audience. Deliver with confidence.",
+  "charts": {
+    "comparison": {
+      "chartType": "radar",
+      "data": [...],
+      "config": { "xKey": "axis", "yKeys": ["ours", "theirs"], "showLegend": true }
+    }
+  }
+}
+```
+
+### Chart Title Rule
+
+A chart's `label` field states the insight, not the data category. The audience should understand your point before reading the chart.
+
+| Weak (category label) | Strong (insight claim) |
+|---|---|
+| "Revenue Data" | "Revenue grew 40% QoQ after the pricing change" |
+| "Response Time" | "Response time dropped 60% after caching rollout" |
+| "User Growth" | "1M users in 6 months — 2× ahead of plan" |
+
+The label is your assertion. The chart is your evidence.
+
+### Chart Type Selection
+
+| Data Pattern | Chart Type |
+|---|---|
+| Trend over time | `"line"` or `"area"` |
+| Category comparison | `"bar"` |
+| Multi-axis comparison | `"radar"` |
+| Part-of-whole | `"pie"` |
+| Volume trend | `"area"` |
+
+## R3F Scene Decisions
+
+Use `type: "r3f"` when the outline calls for a 3D demo or visual impact.
+
+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 (dark backgrounds). Content renders as an overlay on top of the 3D scene.
+
+## Topic Badge Conventions
+
+Use `topic` to group slides by section. Format: `"NN / Section Name"` for numbered sections:
+
+- `"01 / Problem"`
+- `"02 / Solution"`
+- `"03 / Value"`
+- `"04 / Evidence"`
+
+Or plain text for non-numbered groupings: `"Huma Showcase"`, `"Technical Deep Dive"`.
+
+## Slide Recipes
+
+Complete `data` field patterns for common pitch slide types. Combine with `node-schema.md` for the full field reference.
+
+### Cover / Call to Action
+
+Cover = first spine node. CTA = last. Both: centered, branded, no bullets. The only difference is the label and content.
+
+```json
+{
+  "label": "[Title or Ask]",
+  "topic": "[Company or Meeting Context]",
+  "content": "One sentence: what this is and for whom. (Cover) — or — what happens next and when. (CTA)",
+  "centered": true,
+  "brandFont": true,
+  "showBranding": true,
+  "brandingText": "[company.domain]"
+}
+```
+
+### Standard Bullets — Workhorse
+
+Default for problem, solution, evidence, and detail nodes.
+
+```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. Objection signal: 'If they ask X, navigate to [node-id].' Time: 2 minutes max.",
+  "centered": false
+}
+```
+
+### Impact Statement
+
+Single message, no bullets. Use for named shifts, "why now" openers, or bold claims that stand alone.
+
+```json
+{
+  "label": "The Shift",
+  "topic": "01 / Problem",
+  "content": "The market has permanently changed.\n\n**Batch scheduling is structurally incompatible with same-day delivery expectations.**",
+  "notes": "Pause. Do not advance immediately. If the room agrees, the rest is inevitable.",
+  "centered": true
+}
+```
+
+### Two-Column Comparison
+
+Before/after, us/them, or two parallel arguments. Content splits on `---`; left column renders first.
+
+```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- Reports are always one day stale\n\n---\n\n## With [Product]\n- Single live record across all systems\n- Reports update in real time\n- Finance, ops, and leadership see the same data",
+  "layout": "two-column",
+  "centered": false
+}
+```
+
+### Text + Inline Chart
+
+Text on left makes the claim; chart on right is the evidence. Chart is supporting, not the headline.
+
+```json
+{
+  "label": "The Data Confirms It",
+  "topic": "03 / Evidence",
+  "content": "## Continuous monitoring outperforms batch on every metric\n\nThree field studies. Same result each time.\n\n---\n\n[chart:comparison]",
+  "charts": {
+    "comparison": {
+      "chartType": "bar",
+      "data": [{ "metric": "Uptime %", "ours": 98.2, "baseline": 91.5 }],
+      "config": { "xKey": "metric", "yKeys": ["ours", "baseline"], "showGrid": true, "showLegend": true }
+    }
+  },
+  "layout": "two-column",
+  "centered": false
+}
+```
+
+### Proof Point — Customer Quote
+
+Named case study or customer quote. Blockquote (`>`) renders as a styled pull quote — lead with it before the numbers.
+
+```json
+{
+  "label": "Summit Health: Year One",
+  "topic": "04 / Proof",
+  "content": "## 2.3 hours of admin time eliminated per nurse per shift\n\n> \"The conflicts surfaced automatically — we'd been creating them for years without knowing it.\"\n> — VP Operations, Summit Health (42 facilities)\n\n- 38% reduction in shift coverage failures\n- Full rollout across 6 units in 11 weeks",
+  "notes": "If they ask about rollout timeline, the drill-down below has the full breakdown.",
+  "centered": false
+}
+```
+
+### Section Opener — Background Image
+
+Spine node opening a new chapter. Sets atmosphere. Max 3 bullet points on an image slide.
+
+```json
+{
+  "label": "The Opportunity",
+  "topic": "03 / Opportunity",
+  "content": "## A $40B market with no dominant platform\n\nEvery competitor is solving scheduling.\nNobody is solving the coordination layer.",
+  "backgroundImage": "https://images.unsplash.com/photo-XXXXX?w=1920&q=80",
+  "backgroundImageFit": "cover",
+  "backgroundImageOverlay": true,
+  "lightText": true,
+  "centered": false
+}
+```
+
+## Media Delivery Summary
+
+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
+```