# Claude Presentation Master

<div align="center">

![NPM Version](https://img.shields.io/npm/v/claude-presentation-master)
![Downloads](https://img.shields.io/npm/dm/claude-presentation-master)
![License](https://img.shields.io/badge/license-MIT-brightgreen.svg)
![Zero Cost](https://img.shields.io/badge/cost-FREE-success)

### World-Class Presentations from Any Content — Zero Cost, Zero API Keys

**7 Presentation Types • Expert Methodologies • QA Validation • Auto-Remediation**

[Install Now](#installation) •
[Quick Start](#-30-second-demo) •
[Graphics & Images](#-graphics--images) •
[Knowledge Base](#the-knowledge-base)

</div>

---

## What This Tool Does

Claude Presentation Master transforms your content (Markdown, text, JSON, YAML) into professional presentations using a comprehensive **knowledge base of expert methodologies** from McKinsey, BCG, Nancy Duarte, Edward Tufte, and more.

### The Complete Pipeline

```
Your Content (Markdown, text, etc.)
        ↓
  Content Analysis (auto-detects presentation type)
        ↓
  Pattern Classification → Structural Slide Types
        ↓
  Slide Generation (KB-driven, expert methodology)
        ↓
  Image Assignment (local → Unsplash → placeholder)
        ↓
  Visual Quality Evaluation (Playwright-based)
        ↓
  Auto-Fix Issues (iterates until 95+)
        ↓
  Output: HTML (Reveal.js) + PDF + PowerPoint
```

---

## 🖼️ Graphics & Images

### How Images Work (No API Keys Required)

The tool uses a **3-tier image fallback system** that works completely free:

| Priority | Source | API Key Needed? | How It Works |
|----------|--------|-----------------|--------------|
| 1st | **Your Local Images** | No | Put images in same folder as your content |
| 2nd | **Unsplash Source** | No | Keyword-matched photos from Unsplash |
| 3rd | **Picsum.photos** | No | Professional placeholder images |

### Option 1: Use Your Own Images (Best Quality)

Place images in the same directory as your content file:

```
my-presentation/
├── content.md           # Your presentation content
├── images/              # OR put in 'images' subfolder
│   ├── hero.jpg
│   ├── team.png
│   └── product-demo.gif
├── screenshots/         # OR 'screenshots' subfolder
│   └── app-ui.png
└── assets/              # OR 'assets' subfolder
    └── logo.svg
```

**The CLI auto-detects images** in:
- Same directory as input file
- `images/` subfolder
- `screenshots/` subfolder
- `assets/` subfolder

Supported formats: `.jpg`, `.jpeg`, `.png`, `.gif`, `.webp`, `.svg`

### Option 2: Automatic Free Images (No Work Required)

If you don't provide images, the tool automatically fetches relevant photos:

**Unsplash Source (Free, No API Key)**
```
https://source.unsplash.com/800x600/?technology,business
```
- Matches keywords from your slide content
- High-quality photos
- No registration needed
- No rate limits for basic use

**Picsum.photos (Always Available)**
```
https://picsum.photos/800/600
```
- Professional placeholder images
- Seeded for consistency (same content = same image)
- Zero configuration

### Optional: Enhanced Unsplash (More Control)

If you want more control over images, you can optionally set an Unsplash API key:

```bash
# Optional - get a free key from https://unsplash.com/developers
export UNSPLASH_ACCESS_KEY="your-key-here"

# Then generate as normal
npx claude-presentation-master generate content.md
```

**Without the key, images still work** — they just use Unsplash Source (simpler API).

### What About AI-Generated Images?

This tool does **not** generate AI images because:
1. AI image APIs cost money
2. They require API keys
3. Stock photos are often better for presentations

If you want AI-generated images, create them separately and put them in your `images/` folder.

---

## 🏗️ v8.0.0 Unified Architecture

Version 8.0.0 introduces a **unified type system** that ensures consistent behavior across all presentation types:

### Semantic → Structural Type Mapping

The knowledge base uses **semantic types** (e.g., `problem`, `solution`, `traction`) that the engine automatically maps to **structural types** (e.g., `single-statement`, `metrics-grid`, `three-column`):

```
Content Pattern → Semantic Intent → Structural Slide Type
     ↓                  ↓                   ↓
  "3 bullets"    →   "key points"    →  "three-points"
  "$2.4M ARR"    →   "traction"      →  "metrics-grid"
  "vs competitor"→   "competition"   →  "comparison"
```

This architecture ensures:
- **Any content works** — not just specific test cases
- **Universal 95+/100 scores** — tested across keynotes, investor pitches, consulting decks
- **Consistent output** — same input always produces same quality

---

## 🧠 The Knowledge Base

This isn't a template library. It's a **73,000+ token expert system** containing:

### Presentation Experts Encoded

| Expert | Methodology | Used For |
|--------|-------------|----------|
| **Nancy Duarte** | Sparkline structure, STAR moments | TED-style keynotes |
| **Barbara Minto** | Pyramid Principle, SCQA | Consulting decks |
| **Edward Tufte** | Data-ink ratio, chartjunk elimination | Technical presentations |
| **Garr Reynolds** | Simplicity, restraint | Minimal designs |
| **Carmine Gallo** | Rule of Three, 18-minute rule | TED talks |
| **Robert Cialdini** | Persuasion principles | Sales pitches |
| **Chris Anderson** | TED formula | Keynotes |
| **McKinsey/BCG** | Action titles, one-message-per-slide | Business decks |

### What the KB Controls

**Every decision** comes from the knowledge base:

```yaml
# Word limits per presentation type
ted_keynote:
  words_per_slide: { min: 1, max: 15 }

consulting_deck:
  words_per_slide: { min: 40, max: 80 }

# Slide structure rules
allowed_elements:
  keynote:
    - title
    - big_idea
    - single_stat
    - full_image
    - quote

# Expert-specific rules
experts:
  duarte:
    sparkline_required: true
    star_moment_placement: [3, 7, 11]

  minto:
    action_titles_required: true
    scqa_structure: true
```

### 7 Presentation Types (Auto-Detected)

| Type | Auto-Detection Keywords | Primary Experts |
|------|-------------------------|-----------------|
| `ted_keynote` | "TED", "inspire", "keynote" | Duarte, Reynolds, Anderson |
| `sales_pitch` | "sales", "demo", "prospect" | Cialdini, Heath |
| `consulting_deck` | "strategy", "recommendation" | Minto, McKinsey, BCG |
| `investment_banking` | "M&A", "DCF", "valuation" | Wall Street Prep |
| `investor_pitch` | "Series A", "raise", "investor" | Sequoia, YC |
| `technical_presentation` | "API", "architecture", "system" | Tufte, C4 Model |
| `all_hands` | "company update", "quarterly" | Internal Comms |

---

## 📊 Visual Quality Evaluation (Playwright-Based)

Every presentation is scored using **real browser rendering** via Playwright. The tool evaluates actual visual output, not just metadata:

### 4-Dimension Visual Scoring (25 points each)

| Dimension | What It Measures |
|-----------|------------------|
| **Narrative Flow** | Logical progression, strong opening, clear transitions, memorable close |
| **Visual Consistency** | Typography uniformity, color palette adherence, spacing consistency |
| **Content Quality** | Word limits, readability, key message clarity, bullet structure |
| **Executive Readiness** | Would impress stakeholders, boardroom-ready, compelling, shareworthy |

### 7-Dimension Content Scoring (Backup/Additional)

| Dimension | Weight | What It Measures |
|-----------|--------|------------------|
| **Layout** | 15% | Whitespace (40%+ required), balance, structure |
| **Contrast** | 15% | WCAG 4.5:1 compliance, readability |
| **Graphics** | 10% | Image presence, placement, relevance |
| **Content** | 20% | Word limits, bullet count, structure |
| **Clarity** | 15% | One message per slide, key message focus |
| **Effectiveness** | 15% | Expert methodology compliance |
| **Consistency** | 10% | Style uniformity, title casing |

### Iterative Auto-Fix

```
Generate → Visual Score (85/100) → Auto-Fix Issues → Regenerate → Score (95/100) → ✅ Done
```

The engine will iterate up to 5 times (configurable) to reach your target score.

---

## Installation

### Option 1: npx (No Install — Just Run)

```bash
# Generate a keynote presentation (HTML + PDF auto-generated)
npx claude-presentation-master generate notes.md -m keynote -f html

# Generate a consulting deck as PowerPoint
npx claude-presentation-master generate strategy.md --type consulting_deck -f pptx

# All formats (HTML + PDF + PPTX)
npx claude-presentation-master generate content.md -f html,pptx

# With verbose output
npx claude-presentation-master generate content.md -f html --verbose
```

### Option 2: Global Install (Short Command)

```bash
npm install -g claude-presentation-master

# Now use the short 'cpm' command anywhere
cpm generate notes.md -m keynote
cpm info
```

---

## ⚡ 30-Second Demo

```bash
# Create a test file
echo "# Our Big Opportunity

## The Problem
Enterprise teams waste 40% of time on manual data entry.
$50B market. Growing 23% annually.

## Our Solution
AI-powered automation that learns from your workflow.
Currently serving 150 enterprise customers.

## Traction
- \$2.4M ARR (up from \$800K last year)
- 94% customer retention
- NPS score of 72

## The Ask
Raising \$15M to expand into Europe." > pitch.md

# Generate presentation (auto-detects as investor_pitch)
npx claude-presentation-master generate pitch.md -m keynote -f html -o ./demo

# Open demo/our-big-opportunity.html in your browser
```

---

## CLI Reference

```
USAGE:
  npx claude-presentation-master <command> [options]
  cpm <command> [options]

COMMANDS:
  generate <input>    Generate presentation from input file
  validate <file>     Validate existing HTML presentation
  info                Show package information

OPTIONS:
  -o, --output <dir>      Output directory (default: ./output)
  -m, --mode <mode>       keynote (6-25 words) or business (40-80 words)
  -f, --format <fmt>      html, pptx, or html,pptx (PDF auto-generated with html)
  --type <type>           Presentation type (auto-detected if omitted)
  -t, --theme <name>      Theme: default, consulting-classic, modern-tech, minimal
  --title <title>         Presentation title
  --author <name>         Author name
  --min-score <num>       Minimum QA score (default: 95)
  --max-iterations <num>  Max auto-fix iterations (default: 5)
  --no-iterative          Disable iterative QA (single pass)
  --skip-qa               Skip QA (NOT recommended)
  --verbose               Show detailed progress output

EXAMPLES:
  # TED-style keynote
  cpm generate talk.md -m keynote -f html

  # McKinsey-style consulting deck
  cpm generate strategy.md -m business --type consulting_deck -f pptx

  # Investment banking pitchbook
  cpm generate deal.md --type investment_banking -f pptx

  # High quality bar (98+)
  cpm generate content.md --min-score 98 --max-iterations 10
```

---

## Programmatic API

```typescript
import { PresentationEngine } from 'claude-presentation-master';

const engine = new PresentationEngine();

const result = await engine.generate({
  content: markdownContent,
  contentType: 'markdown',
  title: 'Series A Pitch',
  mode: 'keynote',
  format: ['html', 'pptx'],

  // Optional
  presentationType: 'investor_pitch',  // auto-detected if omitted
  qaThreshold: 95,
  maxIterations: 5,
  author: 'Your Name'
});

// Results
console.log(`Score: ${result.score}/100`);
console.log(`Slides: ${result.metadata.slideCount}`);

// Save outputs
fs.writeFileSync('pitch.html', result.outputs.html);
fs.writeFileSync('pitch.pptx', result.outputs.pptx);
```

---

## Output Formats

### HTML (Reveal.js)

- Modern, web-native slides
- Share via URL
- Works on any device
- Keyboard shortcuts: `S` (speaker notes), `F` (fullscreen)
- Embedded CSS with presentation-type theming

### PDF (Auto-generated from HTML)

- Print-ready format
- Generated automatically with HTML
- High-fidelity rendering via Playwright
- Perfect for email attachments

### PowerPoint (PPTX)

- Opens in Microsoft PowerPoint
- Fully editable
- Send to clients
- Includes IB specialty charts (football field, waterfall, comps)

---

## Investment Banking Features

For IB presentations, the engine generates industry-standard charts:

```typescript
// Football Field Valuation
engine.addFootballFieldChart(slide, {
  title: 'Valuation Summary',
  methodologies: [
    { name: 'DCF', low: 42, mid: 48, high: 55 },
    { name: 'Comps', low: 38, mid: 45, high: 52 }
  ],
  currentPrice: 46
});

// Waterfall Chart
engine.addWaterfallChart(slide, {
  title: 'Enterprise Value Bridge',
  startValue: 850000,
  steps: [
    { label: 'Plus: Debt', value: 250000 },
    { label: 'Less: Cash', value: -150000 }
  ]
});

// Comparable Companies Table
engine.addCompsTable(slide, {
  columns: ['EV/Revenue', 'EV/EBITDA', 'P/E'],
  companies: [
    { name: 'Company A', values: [3.2, 12.5, 18.3] },
    { name: 'Target Co', values: [2.5, 9.8, 14.2], highlight: true }
  ]
});
```

---

## Quality Scores

| Score | Grade | Status |
|-------|-------|--------|
| 97-100 | A+ | Exceptional |
| 93-96 | A | Excellent |
| 90-92 | A- | Very Good |
| 85-89 | B+ | Good |
| 80-84 | B | Acceptable |
| < 80 | C | Auto-remediation applied |

**Default threshold: 95/100**

---

## Themes

| Theme | Look | Best For |
|-------|------|----------|
| `default` | Dark executive | General use |
| `consulting-classic` | Cream + navy | McKinsey/BCG style |
| `modern-tech` | Light + teal | Startups |
| `minimal` | Maximum whitespace | Design-focused |
| `dark-executive` | Dark mode | Screen presentations |
| `investment-banking` | Navy + gold | Finance |

---

## FAQ

**Does this require an API key?**
No. Everything runs 100% locally. Images use free services (Unsplash Source, Picsum.photos).

**What's the difference between mode and type?**
- **Mode** (`keynote`/`business`): Controls word count and visual density
- **Type** (e.g., `consulting_deck`): Selects expert methodology and theming

**How do I add custom images?**
Put them in the same directory as your input file (or in `images/`, `screenshots/`, `assets/` subfolders). The CLI auto-detects them.

**What if Unsplash is slow or down?**
The tool automatically falls back to Picsum.photos placeholders.

**Can I lower the quality threshold?**
Yes, but not recommended: `--min-score 80`

**Does it work with Claude Code?**
Yes — that's exactly what it's designed for.

---

## Slide Types

**Keynote Mode:**
Title • Big Idea • Single Statement • Full Image • Big Number • Quote • CTA • Thank You

**Business Mode:**
Title • Agenda • Bullet Points • Two Column • Three Column • Metrics Grid • Timeline • Process Flow • Comparison • Case Study • Section Divider

**Investment Banking:**
Football Field Chart • Waterfall Chart • Sources & Uses • Comparable Companies Table

---

## Zero Cost Guarantee

| Component | Cost | Notes |
|-----------|------|-------|
| NPM Package | FREE | MIT License |
| Dependencies | FREE | reveal.js, pptxgenjs, etc. |
| Fonts | FREE | Google Fonts CDN |
| Images | FREE | Unsplash Source, Picsum |
| QA Validation | FREE | Built-in |
| API Keys | NONE | Runs 100% locally |

---

## License

MIT — free to use, modify, and distribute.

---

## Author

**Stuart Kerr** — [Isovision.ai](https://isovision.ai)

Questions? [stuart@isovision.ai](mailto:stuart@isovision.ai)

---

<div align="center">

## Stop Fighting With Slides. Start Presenting.

```bash
npx claude-presentation-master generate your-content.md -m keynote -f html
```

**Built on methodologies from:**
McKinsey • BCG • Nancy Duarte • Garr Reynolds • Carmine Gallo
Chris Anderson • Barbara Minto • Edward Tufte • Robert Cialdini

**100% Free • Zero API Keys • Runs Locally • MIT License**

</div>