opencode-sa-assistant 0.2.4 → 0.2.6

package/README.md

@@ -17,6 +17,9 @@ This plugin activates when you use the `wadd` keyword in your messages, transfor
 - `sa-researcher`: AWS service information via MCP tools
 - `sa-reviewer`: Well-Architected Framework reviews (6 pillars)
 
+**Orchestrator**:
+- `sa-orchestrator`: Master agent that coordinates Gurus and Specialists based on Guru_Mandate rules
+
 ## Features
 
 ✨ **WADD Mode Activation**: Type `wadd` to activate SA mode  
@@ -26,12 +29,43 @@ This plugin activates when you use the `wadd` keyword in your messages, transfor
 📚 **AWS MCP Tools**: Real-time AWS documentation access  
 🇰🇷 **Bilingual**: Korean prose + English technical terms  
 
+## Agents
+
+### Guru Agents (Philosophy & Strategy)
+
+| Agent | Core Principles | Use When | Avoid When |
+|-------|----------------|----------|------------|
+| **sa-bezos** | Customer Obsession, Day 1, Working Backwards | Customer value definition, Long-term vs short-term decisions, PR/FAQ writing | Pure technical implementation, Cost calculations |
+| **sa-vogels** | Everything Fails, Design for Failure, Loose Coupling | Distributed system design, Scalability/resilience patterns, Operational excellence | Business strategy, Cost ROI analysis |
+| **sa-naval** | Leverage, Asymmetric Outcomes, Compounding | Cost analysis, ROI, Leverage points identification, Complexity removal | Technical architecture details, Customer experience |
+| **sa-feynman** | Feynman Technique, First Principles, Simplicity | Complex concept simplification, Non-technical presentations, Learning materials | Detailed technical decisions, Cost analysis |
+
+### Specialist Agents (Execution)
+
+| Agent | Role | Output |
+|-------|------|--------|
+| **sa-explorer** | Architecture analysis | Component discovery, Dependency mapping, As-Is documentation |
+| **sa-researcher** | AWS information gathering | Service info, Pricing, Best practices with evidence |
+| **sa-reviewer** | Well-Architected review | 6 Pillars evaluation, Risk summary, Prioritized recommendations |
+
+### Orchestrator
+
+**sa-orchestrator** is the master agent that:
+- Classifies user intent (Architecture Review, Service Selection, Cost Analysis, etc.)
+- Invokes appropriate Gurus based on Guru_Mandate rules
+- Delegates tasks to Specialists
+- Enforces anti-patterns (no architecture decisions without Guru consultation)
+
 ## Installation
 
-```bash
-# From the repository root
-cd packages/opencode-sa-assistant
-bun install
+Add the plugin to your `opencode.json`:
+
+```json
+{
+  "plugin": [
+    "opencode-sa-assistant"
+  ]
+}
 ```
 
 ## Usage
@@ -73,14 +107,14 @@ wadd bezos에게 고객 경험 관점에서 이 기능을 평가해달라고 해
 
 ## Skills
 
-The plugin includes 4 skill modules:
+The plugin includes 4 skill modules that are automatically installed to `~/.config/opencode/skills/`:
 
 - **guru**: Guru consultation patterns and philosophies
 - **mcp**: AWS MCP tools reference (search_documentation, read_documentation)
 - **docx**: AWS Blog-style document generation guidelines
 - **pptx**: SA presentation templates
 
-Skills are automatically loaded when needed.
+Skills are installed globally to ensure they are available before any plugin caching occurs. Use `/skill guru` or `/skill mcp` to load them.
 
 ## Testing
 
@@ -92,7 +126,7 @@ bun test
 bun test src/__tests__/integration.test.ts
 ```
 
-**Test Coverage**: 65 tests, 212 assertions, 100% pass rate
+**Test Coverage**: 80 tests, 234 assertions, 100% pass rate
 
 ## Development
 
@@ -103,17 +137,18 @@ packages/opencode-sa-assistant/
 ├── src/
 │   ├── index.ts                     # Plugin entry point
 │   ├── hooks/wadd-mode.ts           # WADD keyword detection
-│   ├── prompts/
-│   │   ├── orchestrator.ts          # SA Orchestrator
-│   │   ├── gurus.ts                 # 4 Guru agents
-│   │   └── specialists.ts           # 3 Specialist agents
-│   ├── skills/
-│   │   ├── guru/SKILL.md
-│   │   ├── mcp/SKILL.md
-│   │   ├── docx/SKILL.md
-│   │   └── pptx/SKILL.md
-│   └── __tests__/
-│       └── *.test.ts                # 65 tests
+│   ├── agents/index.ts              # Agent/Skill installation
+│   │   ├── prompts/
+│   │   │   ├── orchestrator.ts          # SA Orchestrator
+│   │   │   ├── gurus.ts                 # 4 Guru agents
+│   │   │   └── specialists.ts           # 3 Specialist agents
+│   │   ├── skills/
+│   │   │   ├── guru/SKILL.md
+│   │   │   ├── mcp/SKILL.md
+│   │   │   ├── docx/SKILL.md
+│   │   │   └── pptx/SKILL.md
+│   │   └── __tests__/
+│   │       └── *.test.ts                # 80 tests
 ├── package.json
 ├── tsconfig.json
 └── bunfig.toml
@@ -147,7 +182,7 @@ The plugin integrates with AWS Documentation MCP for real-time information:
 
 ## License
 
-[Your License Here]
+MIT
 
 ## Author
 
@@ -163,6 +198,23 @@ Contributions are welcome! Please ensure:
 
 ## Changelog
 
+### v0.2.5 (2026-02-05)
+
+- Fix: Skills now installed to global location (`~/.config/opencode/skills/`)
+  - Resolves oh-my-opencode cache timing issue
+  - Skills are now available via `/skill` command immediately
+- Test coverage: 80 tests, 234 assertions
+
+### v0.2.4 (2026-02-05)
+
+- Added skill installation to `.opencode/skills/`
+- Skills: guru, mcp, docx, pptx
+
+### v0.2.3 (2026-02-05)
+
+- Aligned wadd hook with oh-my-opencode pattern
+- Added `removeCodeBlocks()` for keyword detection
+
 ### v0.1.0 (2026-02-05)
 
 - Initial release
@@ -171,4 +223,3 @@ Contributions are welcome! Please ensure:
 - Guru_Mandate consultation system
 - Well-Architected Framework integration
 - AWS MCP tools support
-- 65 tests, 100% pass rate

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-sa-assistant",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "type": "module",
   "main": "src/index.ts",
   "description": "OpenCode plugin for AWS Solutions Architect assistant with multi-agent Guru system",

package/src/agents/index.ts

@@ -172,11 +172,12 @@ export function uninstallSAAgents(): string[] {
 export const SA_SKILL_NAMES = ["docx", "pptx", "mcp", "guru"] as const;
 
 /**
- * Get the skills directory path for project-level installation
- * Uses process.cwd() to find the project root
+ * Get the skills directory path for global installation
+ * Uses ~/.config/opencode/skills/ to ensure skills are available
+ * before any plugin loads (solving the oh-my-opencode cache timing issue)
  */
 function getSkillsDir(): string {
-  return join(process.cwd(), ".opencode", "skills");
+  return join(homedir(), ".config", "opencode", "skills");
 }
 
 /**
@@ -195,9 +196,7 @@ function getSourceSkillsDir(): string {
 }
 
 /**
- * Install SA skills to .opencode/skills/
- * Creates the directory structure if it doesn't exist.
- * Only writes files if they don't exist (preserves user modifications).
+ * Install SA skills to ~/.config/opencode/skills/ (global location)
  */
 export function installSASkills(): { installed: string[]; skipped: string[]; errors: string[] } {
   const skillsDir = getSkillsDir();
@@ -243,7 +242,7 @@ export function installSASkills(): { installed: string[]; skipped: string[]; err
 }
 
 /**
- * Uninstall SA skills (remove SKILL.md files and directories)
+ * Uninstall SA skills from ~/.config/opencode/skills/
  */
 export function uninstallSASkills(): string[] {
   const skillsDir = getSkillsDir();

package/src/skills/docx/SKILL.md

@@ -272,6 +272,218 @@ new Paragraph({
 })
 ```
 
+### 이미지 비율 유지 삽입
+
+이미지 원본 비율을 유지하면서 삽입하려면 `image-size` 패키지를 사용합니다.
+
+```javascript
+const sizeOf = require('image-size');
+
+function createImageWithAspectRatio(imagePath, maxWidth = 500) {
+  const dimensions = sizeOf(imagePath);
+  const ratio = dimensions.height / dimensions.width;
+  const displayWidth = Math.min(maxWidth, dimensions.width);
+  const displayHeight = Math.round(displayWidth * ratio);
+  
+  return new Paragraph({
+    alignment: AlignmentType.CENTER,
+    children: [new ImageRun({
+      type: imagePath.endsWith('.png') ? 'png' : 'jpg',
+      data: fs.readFileSync(imagePath),
+      transformation: { width: displayWidth, height: displayHeight }
+    })]
+  });
+}
+
+// 사용 예시
+createImageWithAspectRatio('diagrams/architecture.png', 500)
+```
+
+## 다이어그램 삽입
+
+### Mermaid 다이어그램을 이미지로 변환
+
+Word 문서에서 Mermaid 다이어그램을 표시하려면 먼저 이미지로 변환해야 합니다.
+
+#### 1. Mermaid CLI 설치
+
+```bash
+npm install @mermaid-js/mermaid-cli
+```
+
+#### 2. .mmd 파일 작성
+
+```mermaid
+graph TB
+    Client[Client] --> ALB[Application Load Balancer]
+    ALB --> Lambda[AWS Lambda]
+    Lambda --> DynamoDB[(DynamoDB)]
+```
+
+#### 3. 이미지로 변환
+
+```bash
+npx mmdc -i diagram.mmd -o diagram.png -w 800 -b white
+```
+
+#### 4. 비율 유지하여 삽입
+
+```javascript
+const sizeOf = require('image-size');
+
+function insertMermaidDiagram(mmdPath, outputPngPath, maxWidth = 500) {
+  // 1. Mermaid → PNG 변환 (사전 실행 필요)
+  // npx mmdc -i ${mmdPath} -o ${outputPngPath} -w 800 -b white
+  
+  // 2. 이미지 크기 확인 및 비율 계산
+  const dimensions = sizeOf(outputPngPath);
+  const ratio = dimensions.height / dimensions.width;
+  const displayHeight = Math.round(maxWidth * ratio);
+  
+  return new Paragraph({
+    alignment: AlignmentType.CENTER,
+    children: [new ImageRun({
+      type: "png",
+      data: fs.readFileSync(outputPngPath),
+      transformation: { width: maxWidth, height: displayHeight }
+    })]
+  });
+}
+```
+
+## 코드 블록 (멀티라인)
+
+**중요**: Word에서는 `\n` 문자가 제대로 렌더링되지 않습니다. 각 줄을 별도 Paragraph로 분리해야 합니다.
+
+### 잘못된 방식 (동작 안함)
+
+```javascript
+// ❌ 이 방식은 줄바꿈이 무시됨
+new Paragraph({
+  children: [new TextRun({ text: "line1\nline2\nline3" })]
+})
+```
+
+### 올바른 방식
+
+```javascript
+// ✅ 각 줄을 별도 Paragraph로 분리
+function createCodeBlock(codeLines) {
+  const lines = Array.isArray(codeLines) ? codeLines : codeLines.split('\n');
+  return lines.map((line, index) => 
+    new Paragraph({
+      shading: { fill: "F5F5F5", type: ShadingType.CLEAR },
+      spacing: { 
+        before: index === 0 ? 120 : 0, 
+        after: index === lines.length - 1 ? 120 : 0 
+      },
+      indent: { left: 360 },
+      children: [new TextRun({ 
+        text: line || " ",  // 빈 줄은 공백으로
+        font: "Courier New", 
+        size: 18 
+      })]
+    })
+  );
+}
+
+// 사용 예시 - 배열로 전달
+...createCodeBlock([
+  "{",
+  "    \"key\": \"value\",",
+  "    \"nested\": {",
+  "        \"item\": 123",
+  "    }",
+  "}"
+])
+
+// 또는 문자열로 전달
+...createCodeBlock(`function hello() {
+    console.log("Hello, World!");
+}`)
+```
+
+## Pretty JSON 표현
+
+JSON 데이터를 가독성 좋게 표현하는 헬퍼 함수:
+
+```javascript
+function jsonToCodeBlock(jsonObject, indent = 4) {
+  const prettyJson = JSON.stringify(jsonObject, null, indent);
+  return createCodeBlock(prettyJson.split('\n'));
+}
+
+// 사용 예시
+const apiResponse = {
+  userId: "user_abc123",
+  metadata: {
+    model: "claude-3-haiku",
+    tokens: 150
+  }
+};
+
+// 문서에 추가
+...jsonToCodeBlock(apiResponse)
+```
+
+## 테이블 열 너비 조정
+
+### 퍼센트 기반 열 너비 지정
+
+```javascript
+function createTableWithWidths(headers, rows, widthPercents) {
+  const totalWidth = 9360; // DXA 단위 (약 6.5인치, 일반적인 본문 너비)
+  const colWidths = widthPercents.map(p => Math.floor(totalWidth * p / 100));
+  
+  const tableBorder = { style: BorderStyle.SINGLE, size: 1, color: "CCCCCC" };
+  const cellBorders = { top: tableBorder, bottom: tableBorder, left: tableBorder, right: tableBorder };
+  
+  // 헤더 행 생성
+  const headerRow = new TableRow({
+    tableHeader: true,
+    children: headers.map((header, i) => 
+      new TableCell({
+        width: { size: colWidths[i], type: WidthType.DXA },
+        borders: cellBorders,
+        shading: { fill: "232F3E", type: ShadingType.CLEAR },
+        children: [new Paragraph({
+          children: [new TextRun({ text: header, bold: true, color: "FFFFFF" })]
+        })]
+      })
+    )
+  });
+  
+  // 데이터 행 생성
+  const dataRows = rows.map(row => 
+    new TableRow({
+      children: row.map((cell, i) => 
+        new TableCell({
+          width: { size: colWidths[i], type: WidthType.DXA },
+          borders: cellBorders,
+          children: [new Paragraph({ children: [new TextRun(cell)] })]
+        })
+      )
+    })
+  );
+  
+  return new Table({
+    columnWidths: colWidths,
+    rows: [headerRow, ...dataRows]
+  });
+}
+
+// 사용 예시: 합이 100%가 되도록 지정
+createTableWithWidths(
+  ["모델", "Input 비용", "Output 비용"],
+  [
+    ["Claude 3 Haiku", "$0.25/1M", "$1.25/1M"],
+    ["Claude 3 Sonnet", "$3.00/1M", "$15.00/1M"],
+    ["Claude 3 Opus", "$15.00/1M", "$75.00/1M"]
+  ],
+  [40, 30, 30]  // 40% + 30% + 30% = 100%
+)
+```
+
 ## AWS Blog 스타일 가이드
 
 ### 작성 원칙
@@ -305,3 +517,5 @@ new Paragraph({
 필수 의존성:
 - **docx**: `npm install docx` (문서 생성)
 - **sharp**: `npm install sharp` (이미지 처리)
+- **image-size**: `npm install image-size` (이미지 크기 확인)
+- **@mermaid-js/mermaid-cli**: `npm install @mermaid-js/mermaid-cli` (다이어그램 렌더링)

package/src/skills/pptx/SKILL.md

@@ -16,7 +16,6 @@ A user may ask you to create, edit, or analyze the contents of a .pptx file. A .
 If you just need to read the text contents of a presentation, you should convert the document to markdown:
 
 ```bash
-# Convert document to markdown
 python -m markitdown path-to-file.pptx
 ```
 
@@ -24,7 +23,9 @@ python -m markitdown path-to-file.pptx
 You need raw XML access for: comments, speaker notes, slide layouts, animations, design elements, and complex formatting. For any of these features, you'll need to unpack a presentation and read its raw XML contents.
 
 #### Unpacking a file
-`python ooxml/scripts/unpack.py <office_file> <output_dir>`
+```bash
+python scripts/ooxml/unpack.py <office_file> <output_dir>
+```
 
 #### Key file structures
 * `ppt/presentation.xml` - Main presentation metadata and slide references
@@ -40,6 +41,36 @@ You need raw XML access for: comments, speaker notes, slide layouts, animations,
 
 When creating a new PowerPoint presentation from scratch, use the **html2pptx** workflow to convert HTML slides to PowerPoint with accurate positioning.
 
+### Layout Initialization (MANDATORY)
+
+**CRITICAL**: Always define layout constants BEFORE creating slides. Different layouts have different dimensions:
+
+| Layout | Width | Height | Use Case |
+|--------|-------|--------|----------|
+| `LAYOUT_16x9` | 10" | 5.625" | Standard widescreen |
+| `LAYOUT_WIDE` | 13.33" | 7.5" | Extra wide presentations |
+| `LAYOUT_4x3` | 10" | 7.5" | Legacy/square displays |
+
+```javascript
+const LAYOUT_NAME = 'LAYOUT_WIDE';
+const SLIDE = { width: 13.33, height: 7.5 };
+const MARGIN = 0.5;
+const CONTENT = {
+  width: SLIDE.width - (2 * MARGIN),
+  height: SLIDE.height - (2 * MARGIN)
+};
+
+let pptx = new PptxGenJS();
+pptx.layout = LAYOUT_NAME;
+
+slide.addText('Title', {
+  x: MARGIN,
+  y: MARGIN,
+  w: CONTENT.width,
+  h: 0.8
+});
+```
+
 ### Design Principles
 
 **CRITICAL**: Before creating any presentation, analyze the content and choose appropriate design elements:
@@ -73,31 +104,62 @@ AWS 브랜드 색상 팔레트, 표준 슬라이드 구성, HTML 템플릿 예
 When editing slides in an existing PowerPoint presentation, you need to work with the raw Office Open XML (OOXML) format.
 
 ### Workflow
-1. Unpack the presentation: `python ooxml/scripts/unpack.py <office_file> <output_dir>`
+1. Unpack the presentation: `python scripts/ooxml/unpack.py <office_file> <output_dir>`
 2. Edit the XML files (primarily `ppt/slides/slide{N}.xml` and related files)
 3. **CRITICAL**: Validate immediately after each edit
-4. Pack the final presentation: `python ooxml/scripts/pack.py <input_directory> <office_file>`
+4. Pack the final presentation: `python scripts/ooxml/pack.py <input_directory> <office_file>`
 
 ## Creating a new PowerPoint presentation **using a template**
 
 When you need to create a presentation that follows an existing template's design:
 
+### Template Workflow Scripts
+
+All scripts are located in the `scripts/` directory of this skill.
+
+| Script | Command | Purpose |
+|--------|---------|---------|
+| `thumbnail.py` | `python scripts/thumbnail.py template.pptx` | Generate slide thumbnails for visual inspection |
+| `inventory.py` | `python scripts/inventory.py template.pptx -o inventory.json` | Extract all text elements with shape IDs |
+| `replace.py` | `python scripts/replace.py template.pptx mapping.json -o output.pptx` | Replace text using JSON mapping |
+| `rearrange.py` | `python scripts/rearrange.py template.pptx operations.json -o output.pptx` | Duplicate/delete/reorder slides |
+
 ### Workflow
+
 1. **Extract template text AND create visual thumbnail grid**:
-   * Extract text: `python -m markitdown template.pptx > template-content.md`
-   * Create thumbnail grids: `python scripts/thumbnail.py template.pptx`
+```bash
+python -m markitdown template.pptx > template-content.md
+python scripts/thumbnail.py template.pptx --output-dir ./thumbs
+```
 
-2. **Analyze template and save inventory to a file**
+2. **Extract text inventory** (get shape IDs and text content):
+```bash
+python scripts/inventory.py template.pptx -o inventory.json
+```
 
 3. **Create presentation outline based on template inventory**
 
-4. **Duplicate, reorder, and delete slides using `rearrange.py`**
-
-5. **Extract ALL text using the `inventory.py` script**
+4. **Duplicate, reorder, and delete slides**:
+```bash
+# Create operations.json:
+# {"operations": [{"action": "duplicate", "slide": 1, "count": 3}, {"action": "delete", "slides": [5, 6]}]}
+python scripts/rearrange.py template.pptx operations.json -o structured.pptx
+```
 
-6. **Generate replacement text and save the data to a JSON file**
+5. **Generate replacement mapping** and save to JSON:
+```json
+{
+  "replacements": [
+    {"from": "Template Title", "to": "My Presentation"},
+    {"from": "Placeholder Text", "to": "Actual Content"}
+  ]
+}
+```
 
-7. **Apply replacements using the `replace.py` script**
+6. **Apply replacements**:
+```bash
+python scripts/replace.py structured.pptx mapping.json -o final.pptx
+```
 
 ## Dependencies
 
@@ -106,5 +168,5 @@ Required dependencies:
 - **pptxgenjs**: `npm install -g pptxgenjs` (for creating presentations)
 - **playwright**: `npm install -g playwright` (for HTML rendering)
 - **sharp**: `npm install -g sharp` (for SVG rasterization)
-- **LibreOffice**: For PDF conversion
-- **Poppler**: For pdftoppm
+- **LibreOffice**: For PDF conversion (thumbnail generation)
+- **Poppler**: For pdftoppm (thumbnail generation)

package/src/skills/pptx/references/html2pptx.md

@@ -0,0 +1,191 @@
+# HTML to PowerPoint Guide
+
+Convert HTML slides to PowerPoint presentations with accurate positioning using the `html2pptx.js` library.
+
+## Table of Contents
+
+1. [Creating HTML Slides](#creating-html-slides)
+2. [Using the html2pptx Library](#using-the-html2pptx-library)
+3. [Using PptxGenJS](#using-pptxgenjs)
+
+---
+
+## Creating HTML Slides
+
+Every HTML slide must include proper body dimensions:
+
+### Layout Dimensions
+
+- **16:9** (default): `width: 720pt; height: 405pt`
+- **4:3**: `width: 720pt; height: 540pt`
+- **16:10**: `width: 720pt; height: 450pt`
+
+### Supported Elements
+
+- `<p>`, `<h1>`-`<h6>` - Text with styling
+- `<ul>`, `<ol>` - Lists (never use manual bullets •, -, *)
+- `<b>`, `<strong>` - Bold text (inline formatting)
+- `<i>`, `<em>` - Italic text (inline formatting)
+- `<u>` - Underlined text (inline formatting)
+- `<span>` - Inline formatting with CSS styles (bold, italic, underline, color)
+- `<br>` - Line breaks
+- `<div>` with bg/border - Becomes shape
+- `<img>` - Images
+- `class="placeholder"` - Reserved space for charts (returns `{ id, x, y, w, h }`)
+
+### Critical Text Rules
+
+**ALL text MUST be inside `<p>`, `<h1>`-`<h6>`, `<ul>`, or `<ol>` tags:**
+- ✅ Correct: `<div><p>Text here</p></div>`
+- ❌ Wrong: `<div>Text here</div>` - **Text will NOT appear in PowerPoint**
+- ❌ Wrong: `<span>Text</span>` - **Text will NOT appear in PowerPoint**
+
+**NEVER use manual bullet symbols (•, -, *, etc.)** - Use `<ul>` or `<ol>` lists instead
+
+**ONLY use web-safe fonts:**
+- ✅ Web-safe: `Arial`, `Helvetica`, `Times New Roman`, `Georgia`, `Courier New`, `Verdana`, `Tahoma`, `Trebuchet MS`, `Impact`
+- ❌ Wrong: `'Segoe UI'`, `'SF Pro'`, `'Roboto'`, custom fonts
+
+### Styling
+
+- Use `display: flex` on body to prevent margin collapse
+- Use `margin` for spacing (padding included in size)
+- Flexbox works - positions calculated from rendered layout
+- Use hex colors with `#` prefix in CSS
+
+### Shape Styling (DIV elements only)
+
+**IMPORTANT: Backgrounds, borders, and shadows only work on `<div>` elements, NOT on text elements**
+
+- **Backgrounds**: CSS `background` or `background-color` on `<div>` elements only
+- **Borders**: CSS `border` on `<div>` elements converts to PowerPoint shape borders
+- **Border radius**: CSS `border-radius` on `<div>` elements for rounded corners
+- **Box shadows**: CSS `box-shadow` on `<div>` elements (outer shadows only)
+
+### Icons & Gradients
+
+- **CRITICAL: Never use CSS gradients** - They don't convert to PowerPoint
+- **ALWAYS create gradient/icon PNGs FIRST using Sharp, then reference in HTML**
+
+**Rasterizing Icons with Sharp:**
+
+```javascript
+const sharp = require('sharp');
+const { FaHome } = require('react-icons/fa');
+
+async function rasterizeIconPng(IconComponent, color, size, filename) {
+  const svgString = ReactDOMServer.renderToStaticMarkup(
+    React.createElement(IconComponent, { color: `#${color}`, size: size })
+  );
+  await sharp(Buffer.from(svgString)).png().toFile(filename);
+  return filename;
+}
+```
+
+### Example HTML Slide
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+<style>
+html { background: #ffffff; }
+body {
+  width: 720pt; height: 405pt; margin: 0; padding: 0;
+  background: #f5f5f5; font-family: Arial, sans-serif;
+  display: flex;
+}
+.content { margin: 30pt; padding: 40pt; background: #ffffff; border-radius: 8pt; }
+h1 { color: #2d3748; font-size: 32pt; }
+</style>
+</head>
+<body>
+<div class="content">
+  <h1>Title</h1>
+  <ul>
+    <li><b>Item:</b> Description</li>
+  </ul>
+  <div id="chart" class="placeholder" style="width: 350pt; height: 200pt;"></div>
+</div>
+</body>
+</html>
+```
+
+## Using the html2pptx Library
+
+### Basic Usage
+
+```javascript
+const pptxgen = require('pptxgenjs');
+const html2pptx = require('./html2pptx');
+
+const pptx = new pptxgen();
+pptx.layout = 'LAYOUT_16x9';
+
+const { slide, placeholders } = await html2pptx('slide1.html', pptx);
+
+if (placeholders.length > 0) {
+    slide.addChart(pptx.charts.LINE, chartData, placeholders[0]);
+}
+
+await pptx.writeFile('output.pptx');
+```
+
+### API Reference
+
+```javascript
+await html2pptx(htmlFile, pres, options)
+// Returns: { slide, placeholders: [{ id, x, y, w, h }] }
+```
+
+## Using PptxGenJS
+
+### ⚠️ Critical Rules
+
+**Colors - NEVER use `#` prefix:**
+- ✅ Correct: `color: "FF0000"`, `fill: { color: "0066CC" }`
+- ❌ Wrong: `color: "#FF0000"` (breaks document)
+
+### Adding Charts
+
+```javascript
+slide.addChart(pptx.charts.BAR, [{
+    name: "Sales 2024",
+    labels: ["Q1", "Q2", "Q3", "Q4"],
+    values: [4500, 5500, 6200, 7100]
+}], {
+    ...placeholders[0],
+    barDir: 'col',
+    showTitle: true,
+    title: 'Quarterly Sales',
+    showCatAxisTitle: true,
+    catAxisTitle: 'Quarter',
+    showValAxisTitle: true,
+    valAxisTitle: 'Sales ($000s)',
+    chartColors: ["4472C4"]
+});
+```
+
+### Adding Tables
+
+```javascript
+slide.addTable([
+    ["Header 1", "Header 2", "Header 3"],
+    ["Row 1, Col 1", "Row 1, Col 2", "Row 1, Col 3"]
+], {
+    x: 0.5, y: 1, w: 9, h: 3,
+    border: { pt: 1, color: "999999" },
+    fill: { color: "F1F1F1" }
+});
+```
+
+### Adding Images
+
+```javascript
+const aspectRatio = imgWidth / imgHeight;
+const h = 3;
+const w = h * aspectRatio;
+const x = (10 - w) / 2;
+
+slide.addImage({ path: "chart.png", x, y: 1.5, w, h });
+```