@ztffn/presentation-generator-plugin 1.3.9 → 1.4.0

package/DEFERRED-FIXES.md

@@ -0,0 +1,11 @@
+# Deferred Fixes
+
+Issues that require architectural changes and should be addressed in targeted, focused fixes rather than prompt-level patches.
+
+---
+
+## Issue 3 — `topic` badge truncation ✓ resolved
+
+**Was:** Badge clips at ~180px wide when `topic` strings are long.
+
+**Resolution:** The root cause was slide titles being written at full descriptive length (10–15 words) rather than as sharp 6–10 word claims. Fixed by adding slide title length rules to `slide-content/SKILL.md` (narrative agent) and reinforcing the hard limit in the style agent's label rewriting rules. Short titles produce short `topic` strings naturally — no schema change or UI change required.

package/agents/presentation-narrative.md

@@ -6,6 +6,7 @@ skills:
   - presentation-generator:frameworks
   - presentation-generator:slide-content
   - presentation-generator:graph-topology
+  - presentation-generator:outline-format
 ---
 
 # Narrative Design Agent
@@ -20,8 +21,9 @@ Read the skill files at the explicit paths provided by the orchestrator in your
 - `{PLUGIN_ROOT}/skills/frameworks/SKILL.md`
 - `{PLUGIN_ROOT}/skills/slide-content/SKILL.md`
 - `{PLUGIN_ROOT}/skills/graph-topology/SKILL.md`
+- `{PLUGIN_ROOT}/skills/outline-format/SKILL.md`
 
-These files define framework selection logic, slide content quality rules, visual intent annotations, and topology patterns. You must follow them exactly.
+These files define framework selection logic, slide content quality rules, visual intent annotations, topology patterns, and the exact markdown format the Phase 5 parser requires. You must follow them exactly — the outline format in particular is a hard contract with the parser.
 
 ### Step 2 — Read the content brief
 
@@ -44,23 +46,36 @@ Return a summary: framework selected, spine node count, drill-down node count, a
 
 ## Output Format
 
-Write a markdown file to `_temp/presentation-outline.md` with these sections:
+Write a markdown file to `_temp/presentation-outline.md`. The format is a hard contract with the Phase 5 parser — follow `outline-format/SKILL.md` exactly. Key rules:
+
+- Title line: `# Presentation Outline: [Deck Title]`
+- SPINE items: `N. **Title**` (number, period, bold)
+- DRILL-DOWNS parent headers: `### Under Spine N` (H3, exact wording)
+- DRILL-DOWNS child entries: `- **N.M** Title: description` (numeric minor index, never letters)
+- CONTENT headers for spine: `### SPINE N: Title`
+- CONTENT headers for drill-downs: `### SPINE N.M: Title`
 
 ```markdown
-# Presentation Outline
+# Presentation Outline: [Deck Title]
 
 ## Framework
 [Which framework was selected and why]
 
 ## SPINE
-[Ordered list of main-flow slides with title and key message]
+
+1. **[Spine 1 Title]**
+2. **[Spine 2 Title]**
+3. **[Spine 3 Title]**
 
 ## DRILL-DOWNS
-[Which spine nodes have drill-downs, with titles and content summaries]
+
+### Under Spine 2
+- **2.1** [Child Title]: [short description]
+- **2.2** [Child Title]: [short description]
 
 ## CONTENT PER SLIDE
 
-### [Slide Title] (spine | drill-down under [parent])
+### SPINE 1: [Spine 1 Title]
 **Key message:** [one sentence]
 **Content:**
 [Detailed bullet points and text for this slide]
@@ -68,6 +83,15 @@ Write a markdown file to `_temp/presentation-outline.md` with these sections:
 [What the presenter should say that isn't on screen]
 **Transition to next:**
 [How this slide connects to the next]
+
+### SPINE 2.1: [Child Title]
+**Key message:** [one sentence]
+**Content:**
+[Detail]
+**Speaker notes:**
+[Notes]
+**Transition to next:**
+[Transition]
 ```
 
 ## Rules

package/agents/presentation-style.md

@@ -44,9 +44,9 @@ Walk through every node and assign a visual intent. Use the outline's `**Slide t
 | Slide after 2+ consecutive bullet-heavy slides | `breathing-room` | Centered, background image, minimal text |
 | Drill-down with detailed specs or numbers | `workhorse` or `evidence` | Depends on whether data is comparative or sequential |
 
-### Step 4 — Rewrite content for slide readability
+### Step 4 — Rewrite content and labels for slide readability
 
-The script extracted outline content verbatim. Outline content is written for reading, not presenting. For each slide, rewrite `data.content` to work on screen:
+The script extracted outline content verbatim. Outline content is written for reading, not presenting. For each slide, rewrite `data.content` and related fields to work on screen.
 
 **Content rules:**
 - Lead with a `## Heading` that states the insight or claim (not a topic label)
@@ -58,14 +58,45 @@ The script extracted outline content verbatim. Outline content is written for re
 - For two-column slides, ensure the content has a `---` delimiter separating left and right columns.
 - For `impact` slides, content should be 1-2 sentences maximum. Let whitespace carry the message.
 - For `bookend` slides, content is a single compelling sentence or tagline.
+- **Closing lines:** A trailing paragraph after a bullet list must be absorbed as the final bullet, formatted as an explicit callout (`→ Closing thought` or `**Takeaway:** ...`), or removed if the bullets already make the point. Never leave a standalone sentence after a list.
+
+**Label rewriting rules — two patterns based on slide type:**
+
+`data.label` is the largest text on the slide. **Target 6–10 words. Hard limit: 12.** A label that wraps to two lines hasn't been edited yet. Cut every word that doesn't change the meaning if removed.
+
+| Slide type | `data.label` | Longer text |
+|---|---|---|
+| Concept slide (problem, argument, CTA) | Short assertive claim, 6–10 words | Goes in `data.subtitle` |
+| Product/brand slide (named technology or system) | Product or brand name only | Goes in `content` as H1/H2 |
+
+For concept slides — `label` states the claim; detail and data go in `subtitle`:
+```
+Weak:   label: "Annual output: 1,680 tonnes wax, 1,365 tonnes biochar, hydrogen, -10,500 CO₂-eq"
+Strong: label:    "Three products. Carbon-negative by design."
+        subtitle: "1,680t wax · 1,365t biochar · hydrogen · −10,500 CO₂-eq/yr"
+```
+
+For product/brand slides — promote the product name to `label`; move the descriptive headline into `content` as `## H1/H2`:
+```
+Weak:   label: "Ceramic Spiralis geometry solves isothermal operation"
+Strong: label:   "Spiralis"
+        content: ## Ceramic Spiralis geometry solves isothermal operation
+                 - **Spiralis geometry:** Dean flow mixing + isothermal control
+                 - **Modular stacking:** Add capacity without redesigning the system
+```
+When to apply product pattern: the slide's central subject is a named product, technology, or system. Not for abstract concepts, problems, or CTAs.
+
+**Speaker notes:**
+For every node, read the corresponding speaker notes from the outline and write them to `data.notes`. Create the field if it does not already exist. Do NOT rely on Phase 5 to have pre-populated this field — always source notes from the outline directly.
 
 **Do NOT change:**
-- `data.label` — the slide title in the graph editor
-- `data.notes` — speaker notes are already correct from the outline
 - `data.transitionToNext` — transition cues are already correct
 
 ### Step 5 — Apply visual fields
 
+**Branding — apply to every node:**
+Set `brandingText` on every node in the deck, not just bookends. Infer the correct value from the deck title or topic (e.g., the company domain or product name). Also set `showBranding: true` on bookend slides; on other slides `showBranding` can be omitted (it defaults to off), but `brandingText` must always be present so the presenter has a correct fallback.
+
 For each slide, set the appropriate data fields based on visual intent:
 
 #### Bookend (cover / CTA)
@@ -185,8 +216,8 @@ Your completion message must include:
 - **NEVER modify** `id`, `type` (on the node wrapper), `position`, `style`, or `measured` on any node
 - **NEVER modify** any edge — edges are structurally fixed
 - **NEVER add or remove** nodes or edges
-- **NEVER change** `data.label` — this is the slide title shown in the graph editor
-- **NEVER change** `data.notes` — speaker notes are set by the outline
+- **Rewrite** `data.label` per the headline rules in Step 4 — short assertive claim or product name only
+- **Write** `data.notes` from the outline for every node — create the field if absent, never leave it empty
 - **NEVER change** `data.transitionToNext` — transition cues are set by the outline
 - Only use field names from the `ALLOWED_DATA_FIELDS` set in the validator
 - For background images, use Unsplash URLs with `?w=1920&q=80`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ztffn/presentation-generator-plugin",
-  "version": "1.3.9",
+  "version": "1.4.0",
   "description": "Claude Code plugin for generating graph-based presentations",
   "bin": {
     "presentation-generator-plugin": "bin/index.js"

package/scripts/outline_to_graph.py

@@ -38,12 +38,28 @@ def parse_spine(text):
 
 
 def parse_drilldowns(text):
-    """Parse DRILL-DOWNS into {parent_spine_num: [(child_num, child_subnum, title), ...]}."""
+    """Parse DRILL-DOWNS into {parent_spine_num: [(child_num, child_subnum, title), ...]}.
+
+    Canonical format:
+      ### Under Spine N
+      - **N.M** Title: description
+
+    Also accepts common LLM format variants as a fallback:
+      **Under Spine Node N (description):**
+      - Drill-down A: Title
+      - **N.A**: Title  (letter suffix)
+    """
     drilldowns = {}
     current_parent = None
+    _letter = {chr(ord('A') + i): i + 1 for i in range(26)}
 
     for line in text.splitlines():
-        parent_match = re.match(r"###\s+Under Spine (\d+)", line)
+        # Parent header — canonical: "### Under Spine N"
+        # Fallback:  "**Under Spine Node N ..." or "**Under Spine N"
+        parent_match = (
+            re.match(r"###\s+Under Spine\s+(\d+)", line) or
+            re.match(r"\*\*Under Spine(?:\s+Node)?\s+(\d+)", line)
+        )
         if parent_match:
             current_parent = int(parent_match.group(1))
             if current_parent not in drilldowns:
@@ -51,22 +67,71 @@ def parse_drilldowns(text):
             continue
 
         if current_parent is not None:
+            # Canonical: "- **N.M** Title: description"
             child_match = re.match(
-                r"-\s+\*\*(\d+)\.(\d+)\*\*\s+(.+?):\s*(.*)", line
+                r"-\s+\*\*(\d+)\.(\d+)\*\*\s+(.+?)(?::\s.*)?$", line
             )
             if child_match:
                 major = int(child_match.group(1))
                 minor = int(child_match.group(2))
-                title = child_match.group(3).strip()
+                title = child_match.group(3).strip().rstrip("*")
+                drilldowns[current_parent].append((major, minor, title))
+                continue
+
+            # Fallback A: "- **N.A** Title:" or "- **N.A**: Title" (letter suffix)
+            bold_letter = re.match(r"-\s+\*\*(\d+)\.([A-Za-z])\*\*:?\s+(.+)", line)
+            if bold_letter:
+                major = int(bold_letter.group(1))
+                minor = _letter.get(bold_letter.group(2).upper(), 1)
+                title = bold_letter.group(3).strip().rstrip("*:")
                 drilldowns[current_parent].append((major, minor, title))
+                continue
+
+            # Fallback B: "- Drill-down A: Title"
+            dd_letter = re.match(r"-\s+Drill-down\s+([A-Za-z]):\s+(.+)", line)
+            if dd_letter:
+                minor = _letter.get(dd_letter.group(1).upper(), 1)
+                title = dd_letter.group(2).strip()
+                drilldowns[current_parent].append((current_parent, minor, title))
 
     return drilldowns
 
 
 def parse_content_blocks(text):
-    """Parse CONTENT PER SLIDE into a dict keyed by slide identifier (e.g. '1', '2.1')."""
+    """Parse CONTENT PER SLIDE into a dict keyed by slide identifier (e.g. '1', '2.1').
+
+    Canonical header:  ### SPINE N: Title
+                       ### SPINE N.M: Title
+
+    Fallback header:   ### Slide N: Title  (letter or number suffix accepted)
+                       ### Slide N.A: Title
+
+    Note: Phase 6 (style agent) re-reads the outline and overwrites all content fields
+    anyway, so content parsing here is best-effort pre-population only.
+    """
+    _letter = {chr(ord('A') + i): i + 1 for i in range(26)}
+
+    def _normalize_slide_header(m):
+        """Map '### Slide N[.X]: Title' → '### SPINE N[.M]: Title'."""
+        major = m.group(1)
+        raw_suffix = m.group(2)
+        title = m.group(3).strip()
+        if raw_suffix:
+            minor = _letter.get(raw_suffix.upper(), raw_suffix) if raw_suffix.isalpha() else raw_suffix
+            slide_key = f"{major}.{minor}"
+        else:
+            slide_key = major
+        return f"### SPINE {slide_key}: {title}"
+
+    # Normalize fallback "### Slide N[.X]: Title (...)" → canonical before splitting
+    text = re.sub(
+        r"^### Slide (\d+)(?:\.([A-Za-z0-9]+))?[:\s]+(.+?)(?:\s*\(.*\))?\s*$",
+        _normalize_slide_header,
+        text,
+        flags=re.MULTILINE,
+    )
+
     blocks = {}
-    # Split on ### SPINE headers
     parts = re.split(r"(?=^### SPINE )", text, flags=re.MULTILINE)
 
     for part in parts:

package/skills/outline-format/SKILL.md

@@ -0,0 +1,267 @@
+---
+name: outline-format
+description: >
+  Exact markdown format specification for _temp/presentation-outline.md.
+  The outline_to_graph.py script parses this file deterministically — any
+  deviation causes nodes to be silently dropped from the output JSON.
+user-invocable: false
+---
+
+# Outline Format Specification
+
+Defines the exact markdown format that `outline_to_graph.py` (Phase 5) expects.
+Follow it character-for-character. Format drift causes nodes to be silently dropped.
+
+---
+
+## File structure
+
+Four sections in this order:
+
+```
+# Presentation Outline: [Deck Title]
+
+## Framework
+
+## SPINE
+
+## DRILL-DOWNS
+
+## CONTENT PER SLIDE
+```
+
+---
+
+## Title line
+
+```
+# Presentation Outline: The Exact Deck Title
+```
+
+The colon and title on the **same line** are required. The script errors and exits if this line is missing.
+
+---
+
+## SPINE section
+
+Numbered list with bold titles:
+
+```markdown
+## SPINE
+
+1. **Cover Slide Title**
+2. **The Problem We Solve**
+3. **Our Solution**
+4. **Evidence**
+5. **Call to Action**
+```
+
+Rules:
+- Format per item: `N. **Title**` — number, period, space, `**`, title, `**`
+- No trailing colon, asterisk, or other punctuation inside the bold markers
+- Order determines left-to-right position in the graph
+
+---
+
+## DRILL-DOWNS section
+
+Group children under their parent spine node using H3 headers:
+
+```markdown
+## DRILL-DOWNS
+
+### Under Spine 3
+- **3.1** Integration Detail: How the system connects to existing infrastructure
+- **3.2** Change Management: What changes for the people using it
+
+### Under Spine 4
+- **4.1** Case Study: Full methodology and 12-month results
+- **4.2** ROI Model: Payback timeline for the audience's context
+```
+
+Rules:
+- Parent header: exactly `### Under Spine N` — H3, `Under Spine`, space, integer. No additional text.
+- Child entry: `- **N.M** Title: description` where N is the parent spine number and M starts at 1
+- Use **numeric** minor indices only (1, 2, 3…). Do NOT use letter suffixes (A, B, C).
+- The colon after the title is required; the description after it is optional but recommended
+
+---
+
+## CONTENT PER SLIDE section
+
+One H3 block per slide for every spine and drill-down node declared above:
+
+```markdown
+## CONTENT PER SLIDE
+
+### SPINE 1: Cover Slide Title
+**Key message:** One sentence stating what the audience should remember.
+**Content:**
+The detailed slide content. Use bullet points and markdown formatting.
+- Point one with a specific number or named entity
+- Point two — consequence or contrast
+**Speaker notes:**
+What the presenter says that is not on screen. Talking points, anticipated questions, timing.
+**Transition to next:**
+One sentence bridging this slide to the next.
+
+### SPINE 2: The Problem We Solve
+**Key message:** ...
+**Content:**
+...
+**Speaker notes:**
+...
+**Transition to next:**
+...
+
+### SPINE 3.1: Integration Detail
+**Key message:** Integration is a one-day process, not a project.
+**Content:**
+...
+**Speaker notes:**
+...
+**Transition to next:**
+...
+```
+
+Rules:
+- Spine header: `### SPINE N: Title`
+- Drill-down header: `### SPINE N.M: Title` — same N.M notation as DRILL-DOWNS section
+- Every node declared in SPINE and DRILL-DOWNS must have a corresponding content block
+- Field markers must be exactly: `**Key message:**`, `**Content:**`, `**Speaker notes:**`, `**Transition to next:**`
+- Do NOT add parenthetical context like `(drill-down under Slide 3)` after the title
+
+---
+
+## Complete minimal example
+
+```markdown
+# Presentation Outline: Acme Platform Pitch
+
+## Framework
+Problem-Solution-Evidence. Chosen because the audience is unfamiliar with the product
+and needs to understand the problem before evaluating the solution.
+
+## SPINE
+
+1. **Introduction**
+2. **The Problem**
+3. **Our Approach**
+4. **Results**
+5. **Next Steps**
+
+## DRILL-DOWNS
+
+### Under Spine 2
+- **2.1** Root Cause: Why existing tools fail at scale
+
+### Under Spine 3
+- **3.1** How It Works: Technical walkthrough for engineering audiences
+- **3.2** Integrations: Connects to Salesforce, SAP, and custom APIs
+
+## CONTENT PER SLIDE
+
+### SPINE 1: Introduction
+**Key message:** Acme eliminates the manual reconciliation layer that costs mid-market finance teams 11 hours a week.
+**Content:**
+## One integration. Every system in sync.
+
+- Finance teams spend 11 hrs/week reconciling three systems that can't agree
+- Acme replaces the reconciliation step with a live shared record
+- Live in one day — no migration, no rip-and-replace
+**Speaker notes:**
+Open with the cost before introducing the product. Let the number land. If anyone nods, they're the champion.
+**Transition to next:**
+Let's look at exactly where those 11 hours go.
+
+### SPINE 2: The Problem
+**Key message:** Three siloed systems mean no single source of truth — ever.
+**Content:**
+## The reconciliation trap
+
+- ERP, CRM, and billing each hold a different version of reality
+- Finance exports all three every Monday morning and manually merges them
+- One bad merge cascades into wrong forecasts, wrong invoices, wrong decisions
+**Speaker notes:**
+Pause after "wrong decisions" — let the audience feel the compounding failure. If someone raises a specific system, note it and offer to address it in the drill-down below.
+**Transition to next:**
+The root cause isn't the systems — it's the gap between them.
+
+### SPINE 2.1: Root Cause
+**Key message:** Integration middleware solves point-to-point connections but not semantic alignment.
+**Content:**
+## Why middleware isn't enough
+
+- Middleware syncs data but doesn't resolve conflicting field definitions
+- "Customer" means different things in ERP vs CRM — no sync resolves that
+- Result: data arrives but still requires human interpretation on the other end
+**Speaker notes:**
+This is a technical drill-down — adjust depth based on audience. For non-technical audiences, focus on the "different definitions" point and skip the middleware detail.
+**Transition to next:**
+Acme solves the semantic layer, not just the transport layer.
+
+### SPINE 3: Our Approach
+**Key message:** A shared semantic layer makes all three systems agree on meaning, not just data.
+**Content:**
+## One record. Three systems. Zero reconciliation.
+
+- Acme sits between your systems and maintains a canonical data model
+- Each system reads and writes to its own view — Acme translates in real time
+- No migration required: connect in one day, live by end of week
+**Speaker notes:**
+The "canonical data model" framing resonates with technical buyers. For business buyers, use "single source of truth." Have the integration diagram ready to show if they ask how it connects.
+**Transition to next:**
+Here's what it looks like in practice for a customer similar to yours.
+
+### SPINE 3.1: How It Works
+**Key message:** Three API calls replace an 11-step manual process.
+**Content:**
+## From 11 steps to 3 API calls
+
+- Step 1: Connect your systems via pre-built connectors (30 minutes)
+- Step 2: Map your field definitions once using the visual schema editor
+- Step 3: Acme maintains alignment in real time — no ongoing maintenance
+**Speaker notes:**
+If the audience is technical, offer a live demo. If not, skip this slide and go straight to Results.
+**Transition to next:**
+Let's look at what changed for a customer who went live six months ago.
+
+### SPINE 3.2: Integrations
+**Key message:** Pre-built connectors for the 12 systems mid-market companies actually use.
+**Content:**
+## Connect what you have — not what you planned to have
+
+- Salesforce, SAP, NetSuite, HubSpot, QuickBooks, and 7 more
+- Custom API connector for any REST endpoint
+- No professional services required for standard connectors
+**Speaker notes:**
+List connectors only if the audience asks. Lead with "we probably already connect to your stack" rather than listing all 12 upfront.
+**Transition to next:**
+These integrations are what made the Oslo deployment possible in one day.
+
+### SPINE 4: Results
+**Key message:** Customers recover the 11-hour weekly loss in the first month.
+**Content:**
+## 11 hours → 0 hours in 30 days
+
+- Oslo Pilot (6-month data): reconciliation time dropped from 11 hrs/week to zero
+- Forecast accuracy improved from 74% to 96% within the first quarter
+- Zero incidents of invoice errors in the post-deployment period (vs. 3/month prior)
+**Speaker notes:**
+These are real numbers from Oslo — use them confidently. If they ask for more detail, the case study drill-down has the full methodology. The ROI model drill-down has the payback math for their specific context.
+**Transition to next:**
+This is what we'd like to replicate for your team in a structured 90-day pilot.
+
+### SPINE 5: Next Steps
+**Key message:** A 90-day pilot delivers a live system and a verified business case.
+**Content:**
+## From this meeting to live in 90 days
+
+- Day 1–5: Connect your systems, map your schema
+- Day 6–30: Run Acme in parallel — verify accuracy before switching
+- Day 31–90: Full cutover, team training, and business case documentation
+**Speaker notes:**
+Make the ask specific: "Can we agree to the 90-day pilot today?" Have the pilot agreement ready. If they want to think about it, offer a follow-up with their IT lead present.
+**Transition to next:**
+No transition — this is the closing slide.
+```

package/skills/presentation-generator/SKILL.md

@@ -85,13 +85,16 @@ Read these skill files first:
 - {PLUGIN_ROOT}/skills/frameworks/SKILL.md
 - {PLUGIN_ROOT}/skills/slide-content/SKILL.md
 - {PLUGIN_ROOT}/skills/graph-topology/SKILL.md
+- {PLUGIN_ROOT}/skills/outline-format/SKILL.md
 
 Read the content brief at _temp/presentation-content-brief.json
 
 Audience: {AUDIENCE}
 Goal: {GOAL}
 
-Write the outline as MARKDOWN to _temp/presentation-outline.md
+Pacing constraint: for any run of 3 or more consecutive workhorse or evidence slides, include at least one breathing-room or chapter-opener beat — even in short decks. Do not compress this out to save slide count.
+
+Write the outline as MARKDOWN to _temp/presentation-outline.md following the format in outline-format/SKILL.md exactly — the Phase 5 parser is strict about header syntax.
 Report back: framework chosen, spine count, drill-down count.
 ```
 
@@ -128,7 +131,41 @@ Run this bash command:
 python3 "{PLUGIN_ROOT}/scripts/outline_to_graph.py" _temp/presentation-outline.md -o "presentations/{SLUG}/{SLUG}.json"
 ```
 
-If exit code is 0, move to Phase 6. If non-zero, show the errors.
+If exit code is non-zero, show the errors and stop.
+
+After a successful run, verify node count against the outline:
+
+```bash
+python3 - <<'EOF'
+import json, re, sys
+
+with open("_temp/presentation-outline.md") as f:
+    outline = f.read()
+
+# Scope counts to their respective sections to avoid false matches
+spine_m = re.search(r"^## SPINE\b", outline, re.MULTILINE)
+dd_m    = re.search(r"^## DRILL-DOWNS\b", outline, re.MULTILINE)
+cont_m  = re.search(r"^## CONTENT PER SLIDE\b", outline, re.MULTILINE)
+
+spine_text = outline[spine_m.end():dd_m.start()]   if spine_m and dd_m   else ""
+dd_text    = outline[dd_m.end():cont_m.start()]     if dd_m and cont_m   else ""
+
+spine_count = len(re.findall(r"^\d+\.\s+\*\*", spine_text, re.MULTILINE))
+drill_count = len(re.findall(r"^-\s+\*\*\d+\.\d+\*\*", dd_text, re.MULTILINE))
+expected    = spine_count + drill_count
+
+with open("presentations/{SLUG}/{SLUG}.json") as f:
+    data = json.load(f)
+actual = len(data["nodes"])
+
+print(f"Outline declares {expected} nodes ({spine_count} spine + {drill_count} drill-down), JSON has {actual}")
+if actual < expected:
+    print(f"MISMATCH: {expected - actual} node(s) missing — inspect DRILL-DOWNS headers and child entry format in the outline")
+    sys.exit(1)
+EOF
+```
+
+If this count check fails: read the DRILL-DOWNS section of `_temp/presentation-outline.md`, identify format mismatches against `outline-format/SKILL.md`, and do NOT proceed to Phase 6 until the outline is corrected and Phase 5 re-run.
 
 ---
 
@@ -153,6 +190,8 @@ Read the outline at _temp/presentation-outline.md for context.
 Apply visual treatments to each slide. Edit only data fields using the Edit tool.
 Never modify node wrappers (id, type, position, style, measured), edges, or positions.
 
+Speaker notes: for every node, read the corresponding speaker notes from the outline and write them to data.notes, creating the field if it does not already exist. Do not rely on Phase 5 to have pre-populated this field — always write notes from the outline directly.
+
 After all edits, run the validator:
 python3 "{PLUGIN_ROOT}/scripts/validate_draft.py" "presentations/{SLUG}/{SLUG}.json"
 

package/skills/slide-content/SKILL.md

@@ -62,6 +62,27 @@ The most common failure: slides containing everything the presenter plans to say
 
 Use headlines on the spine (main flow). Titles are acceptable on drill-down detail slides where the parent headline provides context.
 
+## Slide Title Length
+
+**6–10 words is the target. Never exceed 12.**
+
+The slide title is the largest text on the screen. Long titles wrap, shrink, and lose impact. A title that needs two lines to fit is a title that hasn't been sharpened yet.
+
+Rules:
+- State the claim, not the description of the claim
+- Cut every word that doesn't change the meaning if removed
+- Prefer a verb: "Spiralis enables compact FT operation" over "The Role of Spiralis in Enabling Compact FT Operation"
+- Numbers and specifics are allowed: "Q3 revenue up 18% — cost held flat" is 8 words and stronger than any 15-word version
+
+| Too long (rewrite this) | Sharp (target) |
+|---|---|
+| "The Spiralis Ceramic Reactor Makes Compact, Isothermal FT Operation Physically Achievable" | "Spiralis makes compact, isothermal FT achievable" |
+| "Revenue grew 40% quarter-on-quarter after the pricing change in Q2 of last year" | "Pricing change drove 40% QoQ growth" |
+| "Why Existing Integration Middleware Tools Fail to Solve the Semantic Alignment Problem" | "Middleware moves data — it doesn't resolve meaning" |
+| "Annual Output: 1,680 Tonnes Wax, 1,365 Tonnes Biochar, Hydrogen, and Negative CO₂" | "Three products. Carbon-negative by design." |
+
+If you find yourself writing a title longer than 10 words, stop. Name the single thing the slide proves, then state it in the fewest words that are still specific.
+
 ## Speaker Notes
 
 Notes should add context the presenter says aloud, not repeat what's on screen.
@@ -220,11 +241,11 @@ The narrative agent should annotate each slide in the outline with a `**Visual i
 | `bookend` | Cover or CTA, branded, symmetrical with its pair |
 | `breathing-room` | Minimal text over image or color, resets attention after dense slides |
 
-Example annotation in an outline:
+Example annotation in an outline (use `### SPINE N:` header format — the parser requires it):
 
 ```
-Slide 4: "Response time dropped 60% — infrastructure cost followed"
-Key message: The platform delivers measurable speed and cost gains.
+### SPINE 4: Response time dropped 60% — infrastructure cost followed
+**Key message:** The platform delivers measurable speed and cost gains.
 **Visual intent:** evidence
 ```
 

package/skills/slide-recipes/SKILL.md

@@ -79,6 +79,11 @@ Set `showBranding: false` for immersive slides (R3F, full-bleed video).
 - Set `backgroundImageOverlay: true` and `lightText: true` when text appears over the image
 - Use Unsplash URLs with `?w=1920&q=80`
 
+**Default-image decision rule:** If a slide has `centered: true` and its content is under ~30 words (i.e. a `bookend` or `impact` slide, not a content-heavy workhorse), apply a contextually appropriate background image:
+- Set `backgroundImage`, `backgroundImageFit: "cover"`, `backgroundImageOverlay: true`, `lightText: true`
+- Choose Unsplash keywords from the deck's topic and industry: energy → `solar`, `infrastructure`; finance → `architecture`, `city`; technology → `abstract`, `circuit`; climate → `nature`, `landscape`; health → `light`, `science`
+- Plain white backgrounds on impact and bookend slides are the wrong default — use an image unless the slide explicitly needs a solid colour treatment
+
 **Background video** — cinematic section openers or demo context:
 - Set URL to placeholder: `"PLACEHOLDER: [description of needed video]"`
 - Set `backgroundVideoFit: "cover"`, `backgroundVideoLoop: true`
@@ -95,6 +100,22 @@ Set `showBranding: false` for immersive slides (R3F, full-bleed video).
 **Full-viewport** (`type: "chart"`) — when the data IS the slide.
 **Inline** (`[chart:name]` in content) — when data supports a text argument.
 
+**Chart-trigger signals** — when outline content matches any of these patterns, synthesise a chart rather than leaving data as bullets:
+
+| Content signal | Chart type |
+|---|---|
+| 2+ quantities of the same type being compared | `bar` or grouped bar |
+| Named items scored across two options (us vs. them, A vs. B) | `radar` |
+| Values changing across 3+ time periods | `area` or `line` |
+| Capital vs. revenue with a breakeven point | `bar` with threshold line |
+| A single proportion of a whole | Large number callout — **not** a pie chart |
+
+When a signal is present: synthesise the `charts` dict from the outline figures, embed `[chart:name]` in the content markdown, and remove the raw data from bullet form. The agent must extract values from the outline text — do not leave chart-ready data as bullets.
+
+Chart placement:
+- Data IS the primary message of the slide → `type: "chart"` (full-viewport)
+- Data supports a text argument → `[chart:name]` inline in a `two-column` layout
+
 ### R3F Scene Decisions
 
 Available scenes: