@ztffn/presentation-generator-plugin 1.6.0 → 1.6.2

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "presentation-generator",
   "description": "Generate complete graph-based presentations from natural language briefs and project documents. Pipeline: content extraction, narrative design, deterministic graph generation, and visual styling.",
-  "version": "1.6.0",
+  "version": "1.6.2",
   "author": {
     "name": "Huma"
   },

package/agents/presentation-narrative.md

@@ -32,7 +32,7 @@ Read `_temp/presentation-content-brief.json`. Note any weak or missing fields.
 ### Step 3 — Select framework, design structure, write slide content
 
 Based on `goal` and `audience`, select the appropriate narrative framework from your frameworks skill. Then:
-1. Design the spine (main horizontal flow) of 4-7 nodes
+1. Design the spine (main horizontal flow) — use the duration-based spine length table in your frameworks skill to determine node count
 2. Design drill-down branches where content warrants optional depth
 3. Write detailed content for each slide following the quality guidance in your slide-content skill
 
@@ -55,6 +55,10 @@ Write a markdown file to `_temp/presentation-outline.md`. The format is a hard c
 - CONTENT headers for spine: `### SPINE N: Title`
 - CONTENT headers for drill-downs: `### SPINE N.M: Title`
 
+**Two formats that look reasonable but silently break the parser:**
+- `- **Io Thermal Storage: The foundation** — Phase-change iron...` ✗ — title must not be inside the bold markers; the N.M index must be
+- `### Io Thermal Storage: The foundation` / `**(Drill-down under Spine Node 2)**` ✗ — no freeform title headers; must be `### SPINE 2.1: Io Thermal Storage`
+
 ```markdown
 # Presentation Outline: [Deck Title]
 

package/agents/presentation-style.md

@@ -30,7 +30,7 @@ These define the visual intent mapping, slide recipes, allowed data fields, and
 
 ### Step 3 — Classify each slide
 
-Walk through every node and assign a visual intent. Use the outline's `**Slide type:**` annotation if present. Otherwise infer:
+Walk through every node and assign a visual intent. Use the outline's `**Visual intent:**` annotation if present. Otherwise infer:
 
 | Position / Content Signal | Visual Intent | Treatment |
 |---|---|---|
@@ -40,7 +40,7 @@ Walk through every node and assign a visual intent. Use the outline's `**Slide t
 | Spine node with a single bold claim | `impact` | Centered, no bullets, whitespace-forward |
 | Spine or drill-down with 4+ bullet points | `workhorse` | Left-aligned, `centered: false`, single or two-column |
 | Slide with comparison data (before/after, us/them, old/new) | `evidence` | Two-column layout, split on `---` |
-| Slide with numeric data suitable for charting | `evidence` | Inline chart (`[chart:name]` in content) or full-viewport `type: "chart"` |
+| Slide with 2+ numeric values of the same type, or named items scored across options | `evidence` | **Synthesize a chart** — do not leave this as bullets. Add `charts` dict, embed `[chart:name]` in content, remove raw data from bullet form. Use chart-trigger signals in your slide-recipes skill to select chart type. |
 | 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 |
 

package/package.json

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

package/scripts/outline_to_graph.py

@@ -93,6 +93,18 @@ def parse_drilldowns(text):
                 minor = _letter.get(dd_letter.group(1).upper(), 1)
                 title = dd_letter.group(2).strip()
                 drilldowns[current_parent].append((current_parent, minor, title))
+                continue
+
+            # Fallback C: "- **Title**" or "- **Title: desc**" or "- **Title — desc**"
+            # Agent wrote title-first bold instead of "- **N.M** Title:". Extract the
+            # title portion (before any colon, em-dash, or en-dash) and auto-number.
+            bold_title = re.match(r"-\s+\*\*([^*]+?)\*\*", line)
+            if bold_title:
+                raw = bold_title.group(1)
+                title = re.split(r"[:\u2014\u2013]", raw)[0].strip()
+                if title:
+                    minor = len(drilldowns[current_parent]) + 1
+                    drilldowns[current_parent].append((current_parent, minor, title))
 
     return drilldowns
 
@@ -131,6 +143,23 @@ def parse_content_blocks(text):
         flags=re.MULTILINE,
     )
 
+    # Normalize freeform drill-down headers:
+    #   ### Some Title
+    #   **(Drill-down under Spine Node N ...)**
+    # → ### SPINE N.M: Some Title  (M auto-incremented per parent)
+    _dd_minor: dict = {}
+    def _normalize_freeform_dd(m):
+        title = m.group(1).strip()
+        parent = int(m.group(2))
+        _dd_minor[parent] = _dd_minor.get(parent, 0) + 1
+        return f"### SPINE {parent}.{_dd_minor[parent]}: {title}"
+    text = re.sub(
+        r"^### (.+?)\n\*\*\(?Drill-down under Spine(?:\s+Node)?\s+(\d+)[^)]*\)?\*\*",
+        _normalize_freeform_dd,
+        text,
+        flags=re.MULTILINE,
+    )
+
     blocks = {}
     parts = re.split(r"(?=^### SPINE )", text, flags=re.MULTILINE)
 

package/scripts/validate_content_brief.py

@@ -0,0 +1,203 @@
+#!/usr/bin/env python3
+"""
+validate_content_brief.py — Validates the content brief JSON produced by Phase 2.
+Checks required fields, detects placeholder/weak values, and warns on thin content.
+Exit 0 if brief is usable; exit 1 if critically malformed.
+Usage: python3 validate_content_brief.py <path-to-content-brief.json>
+"""
+
+import sys
+import json
+import re
+from pathlib import Path
+
+VALID_GOALS = {"pitch", "demo", "update", "internal", "exploratory"}
+
+# Sentinel strings the content agent writes when data is absent in source material.
+NOT_FOUND_RE = re.compile(r"NOT FOUND IN SOURCE", re.IGNORECASE)
+
+# Generic/weak phrases that should not appear as values — adapted from content-signals SKILL.md.
+WEAK_VALUE_RE = re.compile(
+    r"\b(significant|various|many|some|multiple|considerable|substantial|good|better|great|saves time|easy to use|improves efficiency)\b",
+    re.IGNORECASE,
+)
+
+# A specific number means the string contains at least one digit sequence.
+HAS_NUMBER_RE = re.compile(r"\d")
+
+
+def is_not_found(value):
+    if isinstance(value, str):
+        return bool(NOT_FOUND_RE.search(value))
+    if isinstance(value, list):
+        return all(isinstance(v, str) and NOT_FOUND_RE.search(v) for v in value) and len(value) > 0
+    return False
+
+
+def check_string(field, value, errors, warnings):
+    """Validate a required top-level string field."""
+    if not isinstance(value, str) or not value.strip():
+        errors.append(f"{field}: missing or empty")
+        return
+    if is_not_found(value):
+        warnings.append(f"{field}: contains 'NOT FOUND IN SOURCE' placeholder — brief is incomplete")
+
+
+def validate(path):
+    errors = []
+    warnings = []
+
+    try:
+        raw = Path(path).read_text()
+    except FileNotFoundError:
+        print(f"ERROR  File not found: {path}")
+        return False
+
+    try:
+        brief = json.loads(raw)
+    except json.JSONDecodeError as e:
+        print(f"ERROR  Invalid JSON: {e}")
+        return False
+
+    if not isinstance(brief, dict):
+        print("ERROR  Content brief must be a JSON object")
+        return False
+
+    # --- product ---
+    product = brief.get("product")
+    if not isinstance(product, dict):
+        errors.append("product: missing or not an object")
+    else:
+        if not str(product.get("name", "")).strip():
+            errors.append("product.name: missing or empty")
+        if not str(product.get("description", "")).strip():
+            errors.append("product.description: missing or empty")
+
+    # --- audience ---
+    audience = brief.get("audience")
+    if not isinstance(audience, dict):
+        errors.append("audience: missing or not an object")
+    else:
+        for sub in ("who", "background", "cares_about"):
+            val = audience.get(sub, "")
+            if not isinstance(val, str) or not val.strip():
+                errors.append(f"audience.{sub}: missing or empty")
+            elif is_not_found(val):
+                warnings.append(f"audience.{sub}: 'NOT FOUND IN SOURCE' placeholder — narrative will lack audience specificity")
+
+    # --- goal ---
+    goal = brief.get("goal", "")
+    if not isinstance(goal, str) or not goal.strip():
+        errors.append("goal: missing or empty — must be one of: pitch, demo, update, internal, exploratory")
+    elif goal not in VALID_GOALS:
+        if is_not_found(goal):
+            warnings.append("goal: 'NOT FOUND IN SOURCE' placeholder — framework selection will be generic")
+        else:
+            errors.append(f"goal: '{goal}' is not a valid value — must be one of: {', '.join(sorted(VALID_GOALS))}")
+
+    # --- keyMessages ---
+    key_messages = brief.get("keyMessages")
+    if not isinstance(key_messages, list) or len(key_messages) == 0:
+        errors.append("keyMessages: missing or empty array — at least one declarative sentence required")
+    else:
+        real = [m for m in key_messages if isinstance(m, str) and not NOT_FOUND_RE.search(m) and m.strip()]
+        if len(real) == 0:
+            errors.append("keyMessages: all entries are placeholders — no real key messages extracted")
+        elif len(real) < 3:
+            warnings.append(f"keyMessages: only {len(real)} non-placeholder entry(ies) — schema requires 3–5 declarative sentences")
+        elif len(real) > 5:
+            warnings.append(f"keyMessages: {len(real)} entries — schema recommends 3–5")
+        for i, msg in enumerate(real):
+            if WEAK_VALUE_RE.search(msg):
+                warnings.append(f"keyMessages[{i}]: weak/generic language detected — '{msg[:80]}...' — make it specific")
+
+    # --- valueProps ---
+    value_props = brief.get("valueProps")
+    if not isinstance(value_props, list) or len(value_props) == 0:
+        warnings.append("valueProps: missing or empty — narrative may lack audience-specific benefit framing")
+    elif is_not_found(value_props):
+        warnings.append("valueProps: all entries are placeholders — will produce generic benefit statements")
+
+    # --- dataPoints ---
+    data_points = brief.get("dataPoints")
+    if not isinstance(data_points, list) or len(data_points) == 0:
+        errors.append("dataPoints: missing or empty — at least one specific metric is required")
+    else:
+        has_specific_number = False
+        for i, dp in enumerate(data_points):
+            if not isinstance(dp, dict):
+                errors.append(f"dataPoints[{i}]: must be an object with label, value, source")
+                continue
+            val = str(dp.get("value", ""))
+            if HAS_NUMBER_RE.search(val) and not NOT_FOUND_RE.search(val):
+                has_specific_number = True
+            else:
+                warnings.append(
+                    f"dataPoints[{i}] ('{dp.get('label', '?')}'): value '{val}' has no specific number — "
+                    f"weak metric (schema requires a concrete figure)"
+                )
+            if not dp.get("source", "").strip():
+                warnings.append(f"dataPoints[{i}] ('{dp.get('label', '?')}'): missing source attribution")
+        if not has_specific_number:
+            errors.append("dataPoints: no entry has a specific numeric value — brief cannot support evidence slides")
+
+    # --- proofPoints ---
+    proof_points = brief.get("proofPoints")
+    if not isinstance(proof_points, list) or len(proof_points) == 0:
+        warnings.append("proofPoints: missing or empty — narrative will lack named evidence")
+    elif is_not_found(proof_points):
+        warnings.append("proofPoints: all entries are placeholders")
+
+    # --- objections ---
+    objections = brief.get("objections")
+    if not isinstance(objections, list) or len(objections) == 0:
+        warnings.append("objections: missing or empty — narrative cannot preempt audience concerns")
+    elif is_not_found(objections):
+        warnings.append("objections: all entries are placeholders")
+
+    # --- callToAction ---
+    cta = brief.get("callToAction", "")
+    check_string("callToAction", cta, errors, warnings)
+    if isinstance(cta, str) and cta.strip() and not is_not_found(cta):
+        # Heuristic: a real CTA contains an action verb and a concrete outcome
+        weak_cta_patterns = re.compile(
+            r"^(let'?s|we should|continue|follow up|stay in touch|keep talking)",
+            re.IGNORECASE,
+        )
+        if weak_cta_patterns.match(cta.strip()):
+            warnings.append(f"callToAction: '{cta}' — too vague; should name a specific action and outcome")
+
+    # --- context ---
+    context = brief.get("context", "")
+    if not isinstance(context, str) or not context.strip():
+        warnings.append("context: missing or empty — narrative agent has no competitive or timing signals")
+    elif is_not_found(context):
+        warnings.append("context: 'NOT FOUND IN SOURCE' placeholder")
+
+    # --- Report ---
+    if warnings:
+        print(f"WARN   {len(warnings)} warning(s):")
+        for w in warnings:
+            print(f"  WARN  {w}")
+        print()
+
+    if errors:
+        for e in errors:
+            print(f"ERROR  {e}")
+        print()
+        print(f"FAILED  {len(errors)} critical error(s) — content brief is not usable; re-run Phase 2")
+        return False
+
+    if not warnings:
+        print("OK  Content brief is valid")
+    else:
+        print(f"OK (with warnings)  Content brief is usable — {len(warnings)} weak field(s) noted above")
+    return True
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 2:
+        print("Usage: python3 validate_content_brief.py <path-to-content-brief.json>")
+        sys.exit(1)
+    ok = validate(sys.argv[1])
+    sys.exit(0 if ok else 1)

package/skills/frameworks/SKILL.md

@@ -137,7 +137,8 @@ Frameworks define the spine structure. Drill-downs can use a different pattern:
 |---|---|---|
 | 5-10 minutes | 4-5 | 0-1 |
 | 15-20 minutes | 5-6 | 1-2 |
-| 30+ minutes | 6-7 | 2-3 |
+| 30-45 minutes | 7-9 | 2-4 |
+| 60-90 minutes | 8-10 | 4-7 |
 
 The spine is the minimum viable presentation. Drill-downs are optional depth the presenter can use or skip based on time and audience interest.
 

package/skills/graph-topology/SKILL.md

@@ -35,7 +35,7 @@ No drill-downs. Every slide is on the main horizontal path.
 
 ### 2. Spine with Deep Dives
 
-Main path has 4-7 spine nodes. Each can have 1-3 optional drill-down children below it.
+Main path has spine nodes scaled to presentation duration (see frameworks skill for the duration table). Each spine node can have optional drill-down children below it — longer presentations go deeper rather than wider.
 
 ```
 [Cover] → [Problem] → [Solution] → [Value] → [CTA]

package/skills/presentation-generator/SKILL.md

@@ -69,9 +69,15 @@ Write a JSON content brief to _temp/presentation-content-brief.json
 Report back what you extracted.
 ```
 
-When the agent finishes, move to Phase 3.
+When the agent finishes (or after you write the brief yourself), validate the brief before continuing:
 
-If no documents were provided, write _temp/presentation-content-brief.json yourself from the user's prompt, then move to Phase 3.
+```bash
+python3 "{PLUGIN_ROOT}/scripts/validate_content_brief.py" _temp/presentation-content-brief.json
+```
+
+If exit code is non-zero, stop and show the errors to the user — do not proceed to Phase 3.
+
+If no documents were provided, write _temp/presentation-content-brief.json yourself from the user's prompt, then run the validation above.
 
 ---
 
@@ -192,12 +198,36 @@ cp _temp/presentation-content-brief.json "presentations/{SLUG}/content-brief.jso
 cp _temp/presentation-outline.md "presentations/{SLUG}/outline.md"
 ```
 
-Then tell the user:
+Then upload the presentation automatically. Read the upload skill first:
+
+```
+Read: {PLUGIN_ROOT}/skills/upload-presentation/SKILL.md
+```
+
+The presentation JSON is at `presentations/{SLUG}/{SLUG}.json`. The `name` field must be at the JSON root — use the TOPIC from Phase 1:
+
+```bash
+jq --arg name "{TOPIC}" '. + {"name": $name}' "presentations/{SLUG}/{SLUG}.json" | \
+  curl -s -X POST "https://humagreenfield.netlify.app/api/presentations/upload" \
+    -H "Content-Type: application/json" \
+    -H "X-API-Key: TheSunIsFree" \
+    -d @-
+```
+
+On success, report the returned URLs to the user:
+
+```
+Presentation published:
+- Present: https://humagreenfield.netlify.app{presentUrl}
+- Edit:    https://humagreenfield.netlify.app{editUrl}
+```
+
+If the upload fails, fall back to manual import:
 
 ```
 Your presentation is at: presentations/{SLUG}/{SLUG}.json
 
-To import:
+To import manually:
 1. Open https://humagreenfield.netlify.app/present/plan
 2. New presentation → Import JSON
 3. Select the file above

package/skills/slide-content/SKILL.md

@@ -261,4 +261,6 @@ Example annotation in an outline (use `### SPINE N:` header format — the parse
 
 5. **Breathing room after sustained density.** If the outline has a run of `workhorse` and `evidence` slides (detailed argument, data, comparison), follow it with a `breathing-room` or `impact` slide before continuing. The audience needs a reset.
 
+6. **Chart rhythm.** One `evidence` slide per major section is a signal. Two in a row is a pattern the audience can follow. Three or more consecutive `evidence` slides is a data dump — it exhausts attention and flattens the argument. If the content demands multiple data points, prefer one chart slide with a strong claim followed by a drill-down for the supporting data, rather than stacking chart slides on the spine. Equally, a deck with no `evidence` at any point reads as assertion without proof — aim for at least one per major argument.
+
 These annotations describe intent only. How the design agent translates them into layout, background, and typography is not the narrative agent's concern.

package/skills/slide-recipes/SKILL.md

@@ -112,6 +112,23 @@ Set `showBranding: false` for immersive slides (R3F, full-bleed video).
 
 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.
 
+**Data extraction and creation rules:**
+
+The outline rarely contains a tidy data table. More often, values are embedded in prose or bullets. The agent must parse them out and construct the data array. When exact values are missing or incomplete, synthesise plausible values consistent with the narrative — a chart that conveys the right order of magnitude and relative relationship is more useful than no chart.
+
+| Outline text | What to do |
+|---|---|
+| `- Iron oxide: 3,000 kJ/kg` / `- Lithium-ion: 576 kJ/kg` / `- Molten salt: 360 kJ/kg` | Extract label + value pairs → `[{material, energy_density}]`, `xKey: "material"`, `yKeys: ["energy_density"]`, chart type: `bar` |
+| `Response time down 60%, cost down 40% over 6 months` | Construct time-series or before/after → `[{period: "Before", response_ms: 100, cost: 100}, {period: "After", response_ms: 40, cost: 60}]`, chart type: `bar` |
+| `Outperforms competitors on flexibility, integration speed, and reliability` | Named items across multiple axes → `[{axis: "Flexibility", ours: 90, competitor: 35}, ...]`, chart type: `radar` |
+| `Revenue grew 40% QoQ` — no breakdown given | Create a minimal 2-point bar: `[{quarter: "Q2", revenue: 100}, {quarter: "Q3", revenue: 140}]`. Label it clearly. |
+
+Key principles:
+- Use short, readable axis labels — `"Q3"` not `"Third Quarter of Fiscal Year"`
+- `yKeys` values become legend labels — use the words the audience would say: `"ours"` / `"competitor"`, `"before"` / `"after"`, `"target"` / `"actual"`
+- Normalise to a common base (e.g., index to 100) when absolute values would mislead
+- When data is qualitative (e.g. "best-in-class"), skip the chart — use an impact or workhorse slide instead
+
 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

package/skills/upload-presentation/SKILL.md

@@ -0,0 +1,155 @@
+---
+name: upload-presentation
+description: >
+  Upload a React Flow presentation graph JSON directly to the Huma Showcase platform via HTTP API.
+  Use when an agent has generated a presentation (e.g. from the presentation-generator skill) and
+  wants to publish it without manual browser interaction. Triggers on: "upload the presentation",
+  "publish the deck", "deploy the slides", "push to the showcase", "upload presentation-draft.json".
+---
+
+# Upload Presentation
+
+Publishes a presentation graph (nodes + edges) to the platform via a single HTTP call.
+Returns a live URL — no browser interaction needed.
+
+## Prerequisites
+
+- API key: `TheSunIsFree`
+- The JSON to upload must match the `GraphPayload` shape: `{ name, nodes[], edges[] }`.
+
+Pass the key via the `X-API-Key` header or `?key=TheSunIsFree` query param.
+
+## Upload Command
+
+```bash
+curl -s -X POST "https://humagreenfield.netlify.app/api/presentations/upload" \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: TheSunIsFree" \
+  -d @_temp/presentation-draft.json
+```
+
+Or with the key in the URL:
+
+```bash
+curl -s -X POST "https://humagreenfield.netlify.app/api/presentations/upload?key=TheSunIsFree" \
+  -H "Content-Type: application/json" \
+  -d @_temp/presentation-draft.json
+```
+
+## Request Body
+
+The file at `_temp/presentation-draft.json` must contain:
+
+```json
+{
+  "name": "Human-readable presentation title",
+  "description": "Optional one-line description",
+  "nodes": [ /* GraphNode[] — see node schema below */ ],
+  "edges": [ /* GraphEdge[] */ ]
+}
+```
+
+The API requires `name` at the JSON root. Supply it explicitly using the TOPIC from Phase 1:
+
+```bash
+jq --arg name "{TOPIC}" '. + {"name": $name}' "presentations/{SLUG}/{SLUG}.json" | \
+  curl -s -X POST "https://humagreenfield.netlify.app/api/presentations/upload" \
+    -H "Content-Type: application/json" \
+    -H "X-API-Key: TheSunIsFree" \
+    -d @-
+```
+
+If uploading a manually constructed payload, ensure `nodes` is present and non-empty (`[]` is accepted but produces a blank presentation).
+
+### Minimal node shape
+
+```json
+{
+  "id": "cover",
+  "type": "huma",
+  "position": { "x": 0, "y": 0 },
+  "data": {
+    "label": "Slide Title",
+    "content": "Optional markdown body",
+    "notes": "Optional speaker notes"
+  },
+  "style": { "width": 180, "height": 70 },
+  "measured": { "width": 180, "height": 70 }
+}
+```
+
+Full field reference: `.claude/skills/presentation-generator/system/node-schema.md`
+
+### Minimal edge shape
+
+```json
+{
+  "id": "cover-to-problem",
+  "source": "cover",
+  "target": "problem",
+  "sourceHandle": "s-right",
+  "targetHandle": "t-left"
+}
+```
+
+Handle pairs: `s-right/t-left` (→), `s-left/t-right` (←), `s-bottom/t-top` (↓), `s-top/t-bottom` (↑)
+
+## Response
+
+Success (`200`):
+
+```json
+{
+  "ok": true,
+  "slug": "q1-strategy",
+  "name": "Q1 Strategy",
+  "presentUrl": "/present/q1-strategy",
+  "editUrl": "/present/plan/q1-strategy"
+}
+```
+
+Prepend the site origin to get absolute URLs:
+- Present: `https://humagreenfield.netlify.app/present/q1-strategy`
+- Edit: `https://humagreenfield.netlify.app/present/plan/q1-strategy`
+
+Error responses use standard HTTP status codes with `{ "error": "..." }` body:
+
+| Status | `error` message | Fix |
+|--------|----------------|-----|
+| `400` | `"Invalid JSON body"` | Body is not valid JSON |
+| `400` | `"Body must be a JSON object"` | Wrap payload in `{}` |
+| `400` | `"name is required (string)"` | Add `"name"` field to the JSON root |
+| `400` | `"nodes is required (array)"` | Add `"nodes": [...]` to the JSON root |
+| `401` | `"Unauthorized"` | Check API key — must be `TheSunIsFree` |
+| `500` | `"Server misconfiguration: PRESENTATIONS_API_KEY is not set"` | Env var missing on server |
+| `500` | Storage error message | Blob write failed — retry or check Netlify status |
+
+## Slug Behavior
+
+The slug is derived from `name` via `slugify()` (lowercase, hyphens, max 64 chars).
+If the slug already exists, a numeric suffix is appended automatically (`-2`, `-3`, …).
+Bundled template slugs (`lyse-neo-pitch`, `presentation-demo`, `huma-partner-pitch`) are always protected.
+
+## Integration with Presentation Generator
+
+In Phase 7 of the `presentation-generator` pipeline, the output JSON is at `presentations/{SLUG}/{SLUG}.json`. Upload it with the TOPIC as the name:
+
+```bash
+jq --arg name "{TOPIC}" '. + {"name": $name}' "presentations/{SLUG}/{SLUG}.json" | \
+  curl -s -X POST "https://humagreenfield.netlify.app/api/presentations/upload" \
+    -H "Content-Type: application/json" \
+    -H "X-API-Key: TheSunIsFree" \
+    -d @-
+```
+
+## Local Dev
+
+Replace the Netlify URL with `http://localhost:3000`. The endpoint behaves identically — blobs
+fall back to `_temp/react-flow/presentations/` on the local filesystem.
+
+```bash
+curl -s -X POST "http://localhost:3000/api/presentations/upload" \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: TheSunIsFree" \
+  -d @_temp/presentation-draft.json
+```

package/DEFERRED-FIXES.md

@@ -1,50 +0,0 @@
-# Deferred Fixes
-
-Issues that require architectural changes and should be addressed in targeted, focused fixes rather than prompt-level patches.
-
----
-
-## v1.6.0 fixes ✓ resolved
-
-**UX: Phase 1 bash command visible in permission dialog**
-The Phase 1 `find` one-liner (shipped in v1.5.0) still appeared as a bash
-permission prompt. Added `inject-plugin-root.sh` — a `PostToolUse` hook on the
-`Skill` tool that silently resolves PLUGIN_ROOT and injects it as
-`additionalContext` when the orchestrator skill loads. Phase 1 now reads the
-injected value from context with no bash at all. Cowork fallback uses two
-ordered `Read` probes of known install paths — also no bash.
-
----
-
-## v1.5.0 fixes ✓ resolved
-
-**Bug: Style agent always launched as `undefined`**
-`enforce-style-schema.sh` returned `updatedInput: { prompt: "..." }` which replaced
-the entire tool_input, dropping `subagent_type`. Fixed by merging the modified prompt
-into the original tool_input: `updatedInput: ($orig + {prompt: $prompt})`.
-
-**Bug: Content brief triggered presentation validator**
-Hook patterns `*_temp/presentation*.json` matched `_temp/presentation-content-brief.json`,
-causing the validator to reject it. Removed the broad arm — only `*_temp/presentation-draft.json`
-needs validation now.
-
-**Bug: Bare agent names caused first-attempt failures**
-SKILL.md used `presentation-content` etc; Task tool requires fully-qualified
-`presentation-generator:presentation-content`. Fixed in all three phases (2, 3, 6).
-
-**UX: Visual intent annotations leaking into slide content**
-Narrative agents sometimes write `**Visual intent:** bookend` inside `**Content:**` blocks.
-Added `**Visual intent:**` as a recognized field marker in `extract_fields()` so it acts
-as a boundary, preventing bleed into `data.content`. Documented in `outline-format/SKILL.md`.
-
-**UX: Intimidating inline scripts in permission prompts**
-Phase 1 multi-line if/elif replaced with a single `find` one-liner.
-Phase 5 Python heredoc extracted into `scripts/verify_node_count.py`.
-
----
-
-## 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.