@ztffn/presentation-generator-plugin 1.2.0 → 1.3.0

package/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "WebFetch(domain:support.claude.com)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:raw.githubusercontent.com)"
+    ]
+  }
+}

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. Includes a three-agent pipeline: content extraction, narrative design, and graph JSON compilation.",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "author": {
     "name": "Huma"
   },

package/CONTEXT.md

@@ -0,0 +1,110 @@
+# Context: Presentation Generator Plugin
+
+## What this plugin is
+
+A Claude Code plugin (`@ztffn/presentation-generator-plugin`) that generates graph-based presentation JSON for the Huma Showcase renderer. It uses a three-agent pipeline:
+
+1. **presentation-content** — reads source documents, produces `_temp/presentation-content-brief.json`
+2. **presentation-narrative** — reads the brief, produces `_temp/presentation-outline.md` (story structure, slide content)
+3. **presentation-design** — reads the outline, produces `presentations/{slug}/{slug}.json` (graph JSON with nodes, edges, positions)
+
+The orchestrator skill (`skills/presentation-generator/SKILL.md`) spawns each agent via the Task tool.
+
+## Repository layout
+
+```
+presentation-generator-plugin/
+├── .claude-plugin/plugin.json      # Plugin manifest (v1.3.0)
+├── package.json                     # npm package (v1.3.0)
+├── bin/index.js                     # Installer script
+├── agents/
+│   ├── presentation-content.md      # Agent 1: content extraction
+│   ├── presentation-narrative.md    # Agent 2: narrative design
+│   └── presentation-design.md       # Agent 3: JSON generation
+├── skills/
+│   ├── presentation-generator/      # Orchestrator skill
+│   │   ├── SKILL.md
+│   │   └── presentation-guide.md    # Generic presentation craft guide
+│   ├── content-signals/SKILL.md     # Content brief schema + extraction patterns
+│   ├── frameworks/SKILL.md          # 5 narrative frameworks (PSV, BAB, etc.)
+│   ├── slide-content/SKILL.md       # Slide writing quality rules
+│   ├── graph-topology/SKILL.md      # Spine/drill-down structure patterns
+│   └── graph-json-spec/SKILL.md     # Complete graph JSON spec (node schema, edges, positioning, layouts, recipes, reference example)
+└── scripts/
+    └── validate_draft.py            # Validates generated JSON
+```
+
+## How skills reach agents
+
+Each agent file has a `skills:` frontmatter listing plugin-namespaced skill references:
+
+```yaml
+# agents/presentation-design.md
+skills:
+  - presentation-generator:graph-json-spec
+```
+
+Per Claude Code docs, the full content of each listed skill should be injected into the sub-agent's context at startup. The agent's markdown body (below the frontmatter) becomes the system prompt. The `prompt` field from the Task tool call becomes the user message.
+
+## Resilience: self-sufficient agents
+
+Because `skills:` injection has proven unreliable, each agent's markdown body now contains the critical subset of its skill content inlined directly. The design agent body includes: valid enum values, positioning grid, chart config structure, and a reference node example. This means the agent produces correct JSON even when skill injection fails entirely.
+
+## The three agent responsibilities (DO NOT MIX)
+
+### presentation-content
+- **Input:** Source document paths, audience, goal
+- **Output:** `_temp/presentation-content-brief.json`
+- **Knows about:** Content extraction patterns, brief schema, what makes content presentation-worthy
+- **Does NOT know about:** Narrative frameworks, slide design, JSON format, node schema, edges
+
+### presentation-narrative
+- **Input:** Content brief
+- **Output:** `_temp/presentation-outline.md`
+- **Knows about:** Story frameworks (PSV, BAB, etc.), graph topology (spine/drill-down), slide content quality (headlines, assertion-evidence, speaker notes)
+- **Does NOT know about:** JSON format, node schema fields, edge handles, positioning grid, layout/type values
+
+### presentation-design
+- **Input:** Approved outline
+- **Output:** `presentations/{slug}/{slug}.json`
+- **Knows about:** Node schema (SlideNodeData fields), edge conventions (handle IDs), positioning grid, layout templates (type/layout decisions), slide recipes
+- **Does NOT know about:** Story frameworks, content extraction, audience analysis
+
+## The renderer (authoritative, do not modify)
+
+Lives at `/Users/steffen/Projects/huma/humashowcase`. Key types from `src/types/presentation.ts`:
+
+### SlideNodeData allowed fields
+`label`, `topic`, `content`, `notes`, `type`, `centered`, `layout`, `lightText`, `brandFont`, `showBranding`, `brandingText`, `backgroundImage`, `backgroundImageFit`, `backgroundImageOverlay`, `backgroundVideo`, `backgroundVideoFit`, `backgroundVideoLoop`, `inlineVideoControls`, `inlineVideoAutoplay`, `inlineVideoLoop`, `scene`, `chart`, `charts`, `sceneGroup`, `focus`
+
+### Valid enums
+- `data.type`: `"content"` | `"r3f"` | `"chart"` | `"custom"` (default: `"content"`)
+- `data.layout`: `"single"` | `"two-column"` (default: `"single"`)
+
+### Correct node structure
+```json
+{
+  "id": "kebab-case-slug",
+  "type": "huma",
+  "position": { "x": 240, "y": 0 },
+  "data": {
+    "label": "Slide title goes here",
+    "content": "## Markdown body\n\n- Bullet points\n- More content",
+    "notes": "Speaker notes go here",
+    "centered": false
+  },
+  "style": { "width": 180, "height": 70 },
+  "measured": { "width": 180, "height": 70 }
+}
+```
+
+### Correct edge structure
+```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" }
+```
+
+### Positioning grid
+- Horizontal spacing: 240px
+- Vertical spacing: 150px
+- Node size: always 180x70

package/HANDOFF.md

@@ -0,0 +1,49 @@
+# Handoff: Presentation Generator Plugin v1.3.0
+
+## Current state
+
+The plugin generates correct graph JSON. The design agent is resilient to skills injection failure because critical rules (enums, grid, chart config, reference node) are inlined in its body.
+
+## Architecture
+
+Three-agent pipeline orchestrated by `skills/presentation-generator/SKILL.md`:
+
+| Agent | Skills | Purpose |
+|---|---|---|
+| `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 |
+
+## Key files
+
+| File | Purpose |
+|---|---|
+| `skills/graph-json-spec/SKILL.md` | Complete graph JSON specification — node schema, edges, positioning, layouts, recipes, reference example |
+| `agents/presentation-design.md` | Design agent with inlined critical rules as fallback |
+| `scripts/validate_draft.py` | Validates generated JSON against renderer types |
+
+## Known past failures (resolved)
+
+1. **Skills injection failure** — agent invented its own schema (wrong field names, wrong enums, wrong spacing). Fixed by inlining critical rules into the agent body.
+2. **Fragmented skills** — 5 separate skills (`node-schema`, `edge-conventions`, `layout-templates`, `positioning`, `pitch-reference`) all had to inject correctly. Consolidated into single `graph-json-spec` skill.
+3. **Wrong field names** — `title`/`subtitle`/`bullets` instead of `label`/`content`/`notes`. Banned field list is in both the agent body and the consolidated skill.
+4. **Bare edge handles** — `right`/`left` instead of `s-right`/`t-left`. Handle rules are in both the agent body and the consolidated skill.
+5. **Missing `measured` field** — validator now enforces this.
+
+## The renderer (do not modify)
+
+Lives at `/Users/steffen/Projects/huma/humashowcase`. The renderer is authoritative — the plugin must match it. Key source of truth: `src/types/presentation.ts` (`SlideNodeData` interface).
+
+## Validation
+
+Run against any generated JSON:
+
+```bash
+python3 scripts/validate_draft.py presentations/{slug}/{slug}.json
+```
+
+Or against the reference demo:
+
+```bash
+python3 scripts/validate_draft.py "/Users/steffen/Downloads/presentation-demo-2(1).json"
+```

package/PLAN-consolidate-design-skills.md

@@ -0,0 +1,238 @@
+# Plan: Consolidate Design Agent Skills
+
+## Objective
+
+Merge the 5 fragmented design-agent skills (`node-schema`, `edge-conventions`, `layout-templates`, `positioning`, `pitch-reference`) into a single consolidated skill AND inline its critical content into the `agents/presentation-design.md` body. The agent must produce correct JSON even when `skills:` injection fails entirely.
+
+## Problem
+
+The design agent currently references 5 separate skills via frontmatter:
+```yaml
+skills:
+  - presentation-generator:node-schema
+  - presentation-generator:edge-conventions
+  - presentation-generator:layout-templates
+  - presentation-generator:positioning
+  - presentation-generator:pitch-reference
+```
+
+Per Claude Code docs, `skills:` in subagent frontmatter should inject full skill content at startup. In practice, this injection fails — the agent invents its own schema (wrong field names, wrong enums, wrong spacing, bare handles). Five skills must ALL inject correctly; if even one fails, the output breaks.
+
+## What to do
+
+### Step 1: Create consolidated skill
+
+Create `skills/graph-json-spec/SKILL.md` — a single comprehensive skill containing everything the design agent needs. Merge content from all 5 skills into one coherent document, organized in the order the agent needs it during JSON generation.
+
+**Frontmatter:**
+```yaml
+---
+name: graph-json-spec
+description: >
+  Complete specification for generating valid graph-based presentation JSON —
+  node schema, edge wiring, positioning grid, layout decisions, and slide recipes.
+  Used by the presentation-design agent.
+user-invocable: false
+---
+```
+
+**Document structure** (in this order):
+
+1. **Quick Reference** — The essential rules on one screen. Field names, valid enums, grid values, handle IDs. This section alone should prevent the most common errors.
+
+2. **Node Structure** — Merge from `node-schema`. Full node wrapper (`id`, `type: "huma"`, `position`, `data`, `style`, `measured`). All `SlideNodeData` fields with types and defaults. Keep the grouped tables (content fields, layout/display, background media, inline video, R3F scene, charts). Include the banned field names list from the current agent body.
+
+3. **Edge Wiring** — Merge from `edge-conventions`. Handle ID table, bidirectional pair rule, standard edge pair patterns (spine, drill-down, sibling), edge ID convention, validation checklist.
+
+4. **Positioning Grid** — Merge from `positioning`. Grid constants (240px/150px/180×70), spine row layout, drill-down row placement, sibling spacing, quick reference position table.
+
+5. **Design Decisions** — Merge from `layout-templates`. Slide type selection, layout decisions (when two-column, when centered, when brand font, when branding), background treatment, text contrast, chart decisions (full-viewport vs inline, chart type selection), R3F scene decisions, topic badge conventions.
+
+6. **Slide Recipes** — Merge from `layout-templates`. All 7 recipe patterns (cover/CTA, standard bullets, impact statement, two-column comparison, text+inline chart, proof point/customer quote, section opener with background image). These are complete `data` field examples the agent can pattern-match against.
+
+7. **Complete Reference Example** — Merge from `pitch-reference`. The full 7-node JSON with all edges. But UPDATE it to match the validated demo at `/Users/steffen/Downloads/presentation-demo-2(1).json`. Key differences to adopt from the demo:
+   - The demo uses `"meta": { "updatedAt": "..." }` — the plugin should use `"meta": { "name": "..." }` (per the current agent spec). Keep the plugin's `meta.name` convention.
+   - Edge IDs: the demo uses short IDs like `"e1"`, `"e2"` for spine and descriptive IDs like `"e-prob-detail"` for drill-downs. Either convention is fine, but the reference should be consistent — use the descriptive `e-{source}-{target}` pattern throughout.
+   - The demo has 20 nodes and 40 edges — it's a real-world example. Consider including a trimmed version (keep the 7-node pitch reference) but add 2-3 realistic patterns from the demo that the current pitch-reference doesn't cover:
+     - A slide with `style.backgroundColor` set (the `feat-style` node uses `"backgroundColor": "#1a1a2e"`)
+     - A drill-down with a second-level child (the demo has `feat-markdown` → `feat-tables` at y:300)
+     - Sibling drill-downs connected horizontally (the demo has `feat-markdown` → `feat-charts` via `s-right`/`t-left`)
+
+8. **Media Delivery Summary Format** — The template for listing placeholder media at the end of output.
+
+**Important content decisions:**
+- DO NOT include narrative frameworks, content extraction patterns, or audience analysis — those belong to other agents.
+- DO NOT include the presentation guide / playbook content — that's for the narrative agent.
+- DO include the content markdown features list from node-schema (the agent needs to know what markdown syntax works).
+- DO include chart config structure with the `config` wrapper (the demo JSON shows `config: { xKey, yKeys, showGrid, showLegend }` — not top-level `xKey`/`yKey`).
+
+### Step 2: Update the design agent body
+
+Edit `agents/presentation-design.md` to inline the critical subset — the minimum needed for correct output even if skills injection fails completely. The agent body should contain:
+
+**Keep everything currently in the body** (field mapping table, banned fields, edge handle rules, node structure rules, output format, validator invocation).
+
+**Add these sections from the consolidated skill:**
+
+1. **Valid Enums** — Add directly after the field mapping table:
+   ```
+   ## Valid Enum Values
+
+   - `data.type`: `"content"` (default) | `"r3f"` | `"chart"` | `"custom"`
+   - `data.layout`: `"single"` (default) | `"two-column"` (splits content on `---`)
+   - `data.centered`: `true` (default) | `false`
+   - `data.backgroundImageFit`: `"cover"` (default) | `"contain"`
+   - `data.backgroundVideoFit`: `"cover"` (default) | `"contain"`
+   ```
+
+2. **Positioning Grid** — Add a compact version:
+   ```
+   ## Positioning Grid
+
+   - Horizontal spacing: 240px between nodes
+   - Vertical spacing: 150px between levels
+   - Node size: always `{ width: 180, height: 70 }` in both `style` and `measured`
+   - Spine: all at y:0, x increments by 240 (0, 240, 480, 720...)
+   - Drill-down level 1: y:150, same x as parent
+   - Drill-down level 2: y:300
+   - Siblings at same depth: increment x by 240
+   ```
+
+3. **Chart Config Structure** — Add a compact example showing the `config` wrapper:
+   ```
+   ## Chart Config
+
+   Charts use a `config` wrapper for axis and display settings:
+   { "chartType": "bar", "data": [...], "config": { "xKey": "...", "yKeys": [...], "showGrid": true, "showLegend": true } }
+
+   Inline: put in `charts` record, reference with `[chart:name]` in content.
+   Full-viewport: put in `chart` field, set `type: "chart"`.
+   ```
+
+4. **Compact Reference Node** — One complete node example showing all common fields:
+   ```json
+   {
+     "id": "problem",
+     "type": "huma",
+     "position": { "x": 240, "y": 0 },
+     "data": {
+       "label": "The Problem",
+       "topic": "01 / Problem",
+       "content": "## Linear tools break complex stories\n\n- Point one\n- Point two",
+       "notes": "Speaker notes here",
+       "centered": false
+     },
+     "style": { "width": 180, "height": 70 },
+     "measured": { "width": 180, "height": 70 }
+   }
+   ```
+
+**Update the `skills:` frontmatter** to reference the single consolidated skill:
+```yaml
+skills:
+  - presentation-generator:graph-json-spec
+```
+
+### Step 3: Update the orchestrator
+
+Edit `skills/presentation-generator/SKILL.md` — update the Sub-Agent Reference table:
+
+```
+| Agent | Skills Loaded | Purpose |
+|---|---|---|
+| `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 |
+```
+
+### Step 4: Delete the old skill directories
+
+Remove these 5 directories (they're fully superseded):
+- `skills/node-schema/`
+- `skills/edge-conventions/`
+- `skills/layout-templates/`
+- `skills/positioning/`
+- `skills/pitch-reference/`
+
+### Step 5: Update validator awareness
+
+Read `scripts/validate_draft.py` and verify the consolidated skill's field lists match. The validator's `ALLOWED_DATA_FIELDS` set and handle sets must be consistent with what's documented in the skill. Current validator allows 24 data fields:
+
+```python
+ALLOWED_DATA_FIELDS = {
+    "label", "topic", "content", "notes", "type", "centered", "layout",
+    "lightText", "brandFont", "showBranding", "brandingText",
+    "backgroundImage", "backgroundImageFit", "backgroundImageOverlay",
+    "backgroundVideo", "backgroundVideoFit", "backgroundVideoLoop",
+    "inlineVideoControls", "inlineVideoAutoplay", "inlineVideoLoop",
+    "scene", "chart", "charts", "sceneGroup", "focus"
+}
+```
+
+The consolidated skill should list these same 24 fields. Cross-check against the demo JSON — the demo also uses `"selected": false` at the node level (not in `data`), which is fine (it's a React Flow runtime field, not part of `data`).
+
+Note: the demo JSON uses `meta.updatedAt` instead of `meta.name`. The validator checks for `meta.name` as non-empty. The consolidated skill should document that `meta.name` is required (the validator enforces it). The orchestrator can add `updatedAt` if desired but it's not checked.
+
+### Step 6: Update package version
+
+Bump version in `package.json` and `.claude-plugin/plugin.json` from `1.2.0` to `1.3.0`.
+
+### Step 7: Update CONTEXT.md and HANDOFF.md
+
+Update or remove the sections that describe the old fragmented skill structure. The new structure should be documented.
+
+### Step 8: Update README.md
+
+The Plugin structure section at the bottom lists the old nested structure. Update to reflect the actual flat structure with the new consolidated skill.
+
+## Files to create
+
+| File | Description |
+|---|---|
+| `skills/graph-json-spec/SKILL.md` | Consolidated design specification (merge of 5 skills) |
+
+## Files to modify
+
+| File | Changes |
+|---|---|
+| `agents/presentation-design.md` | Inline critical rules (enums, grid, chart config, reference node). Change `skills:` to reference `graph-json-spec` only. |
+| `skills/presentation-generator/SKILL.md` | Update sub-agent reference table |
+| `package.json` | Bump to 1.3.0 |
+| `.claude-plugin/plugin.json` | Bump to 1.3.0 |
+| `README.md` | Update plugin structure diagram |
+| `CONTEXT.md` | Update to reflect new structure |
+| `HANDOFF.md` | Update to reflect new structure |
+
+## Files to delete
+
+| File | Reason |
+|---|---|
+| `skills/node-schema/SKILL.md` | Merged into `graph-json-spec` |
+| `skills/edge-conventions/SKILL.md` | Merged into `graph-json-spec` |
+| `skills/layout-templates/SKILL.md` | Merged into `graph-json-spec` |
+| `skills/positioning/SKILL.md` | Merged into `graph-json-spec` |
+| `skills/pitch-reference/SKILL.md` | Merged into `graph-json-spec` |
+
+## Validation criteria
+
+After implementation, verify:
+
+1. `skills/graph-json-spec/SKILL.md` exists and contains all content from the 5 merged skills
+2. `agents/presentation-design.md` body contains: valid enums, positioning grid values, chart config structure, and a reference node example
+3. `agents/presentation-design.md` frontmatter references only `presentation-generator:graph-json-spec`
+4. The 5 old skill directories are deleted
+5. The validator still passes against the demo JSON:
+   ```bash
+   python3 scripts/validate_draft.py "/Users/steffen/Downloads/presentation-demo-2(1).json"
+   ```
+6. No narrative/content concepts leaked into the design skill (no framework names, no content extraction patterns, no audience analysis)
+7. The chart config in the skill uses the `config` wrapper structure (matching the demo JSON), not bare `xKey`/`yKey`
+
+## Reference files for the implementor
+
+These files contain the authoritative truth. Read them if anything is ambiguous:
+
+- **Valid demo JSON:** `/Users/steffen/Downloads/presentation-demo-2(1).json` — 20 nodes, 40 edges, all patterns
+- **Renderer types:** `/Users/steffen/Projects/huma/humashowcase/src/types/presentation.ts` — `SlideNodeData` interface
+- **Technical docs:** `/Users/steffen/Projects/huma/humashowcase/docs/technical/presentation-system-implementation.md`
+- **Validator:** `/Users/steffen/Projects/huma/presentation-generator-plugin/scripts/validate_draft.py`

package/README.md

@@ -133,27 +133,25 @@ Pushing the tag triggers the publish workflow. Team members get the update with
 ## Plugin structure
 
 ```
-presentation-generator/
+presentation-generator-plugin/
 ├── .claude-plugin/
 │   └── plugin.json
+├── package.json
+├── bin/
+│   └── index.js
 ├── agents/
 │   ├── presentation-content.md
 │   ├── presentation-narrative.md
 │   └── presentation-design.md
-└── skills/
-    └── presentation-generator/
-        ├── SKILL.md
-        ├── narrative/
-        │   ├── content-signals.md
-        │   ├── frameworks.md
-        │   ├── slide-content.md
-        │   └── graph-topology.md
-        ├── system/
-        │   ├── node-schema.md
-        │   ├── edge-conventions.md
-        │   ├── layout-templates.md
-        │   └── positioning.md
-        └── examples/
-            ├── pitch-reference.json
-            └── presentation-guide.md
+├── skills/
+│   ├── presentation-generator/
+│   │   ├── SKILL.md                # Orchestrator skill
+│   │   └── presentation-guide.md
+│   ├── content-signals/SKILL.md    # Content extraction patterns
+│   ├── frameworks/SKILL.md         # Narrative frameworks
+│   ├── slide-content/SKILL.md      # Slide writing quality
+│   ├── graph-topology/SKILL.md     # Spine/drill-down structure
+│   └── graph-json-spec/SKILL.md    # Complete graph JSON spec (design agent)
+└── scripts/
+    └── validate_draft.py
 ```

package/agents/presentation-design.md

@@ -3,11 +3,7 @@ name: presentation-design
 description: Translates approved slide outlines into complete graph JSON with nodes, edges, positions, and visual treatments. Pure translation — never alters content or structure from the outline.
 tools: Read, Write, Bash
 skills:
-  - presentation-generator:node-schema
-  - presentation-generator:edge-conventions
-  - presentation-generator:layout-templates
-  - presentation-generator:positioning
-  - presentation-generator:pitch-reference
+  - presentation-generator:graph-json-spec
 ---
 
 # Design & JSON Generation Agent
@@ -18,11 +14,11 @@ You are a design and JSON generation specialist. Your job is to translate an app
 
 1. Read the approved outline from `_temp/presentation-outline.md`
 2. For each slide in the outline, make three categories of decision:
-   a. **Slide type and layout**: Based on content signals, select `type`, `layout`, `centered`, and related fields using the layout-templates skill
+   a. **Slide type and layout**: Based on content signals, select `type`, `layout`, `centered`, and related fields per the graph-json-spec skill
    b. **Visual treatment**: Set background media, `lightText`, branding flags, and chart configuration
-   c. **Positioning**: Place each node on the grid defined in the positioning skill
+   c. **Positioning**: Place each node on the 240px/150px grid
 3. Build all nodes with complete `data`, `style`, and `measured` objects
-4. Wire all edges with bidirectional pairs following the edge-conventions skill
+4. Wire all edges with bidirectional pairs per the edge wiring rules
 5. Run the edge validation checklist before finalizing
 6. Write the complete JSON to `_temp/presentation-draft.json`
 
@@ -39,6 +35,57 @@ When translating from the outline to `data` fields, use **exactly** these SlideN
 **DO NOT use these field names** — they are not part of the schema and will be silently ignored by the renderer:
 `headline`, `subheadline`, `bullets`, `speakerNote`, `speakerNotes`, `visualHint`, `theme`, `title`, `body`, `text`, `background`, `showLogo`, `keyMessage`, `claim`, `hook`, `description`, `summary`
 
+## Valid Enum Values
+
+- `data.type`: `"content"` (default) | `"r3f"` | `"chart"` | `"custom"`
+- `data.layout`: `"single"` (default) | `"two-column"` (splits content on `---`)
+- `data.centered`: `true` (default) | `false`
+- `data.backgroundImageFit`: `"cover"` (default) | `"contain"`
+- `data.backgroundVideoFit`: `"cover"` (default) | `"contain"`
+
+## Positioning Grid
+
+- Horizontal spacing: 240px between nodes
+- Vertical spacing: 150px between levels
+- Node size: always `{ width: 180, height: 70 }` in both `style` and `measured`
+- Spine: all at y:0, x increments by 240 (0, 240, 480, 720...)
+- Drill-down level 1: y:150, same x as parent
+- Drill-down level 2: y:300
+- Siblings at same depth: increment x by 240
+
+## Chart Config
+
+Charts use a `config` wrapper for axis and display settings:
+
+```json
+{ "chartType": "bar", "data": [...], "config": { "xKey": "quarter", "yKeys": ["revenue", "cost"], "showGrid": true, "showLegend": true } }
+```
+
+- Inline: put in `charts` record, reference with `[chart:name]` in content
+- Full-viewport: put in `chart` field, set `type: "chart"`
+- Chart types: `"bar"` | `"line"` | `"area"` | `"pie"` | `"radar"`
+
+## Reference Node
+
+A complete correct node for pattern-matching:
+
+```json
+{
+  "id": "problem",
+  "type": "huma",
+  "position": { "x": 240, "y": 0 },
+  "data": {
+    "label": "The Problem",
+    "topic": "01 / Problem",
+    "content": "## Linear tools break complex stories\n\n- Point one\n- Point two",
+    "notes": "Speaker notes here",
+    "centered": false
+  },
+  "style": { "width": 180, "height": 70 },
+  "measured": { "width": 180, "height": 70 }
+}
+```
+
 ## Edge Handle Rules
 
 **WRONG** — these handle values will break navigation:

package/package.json

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