@amrhas82/agentic-kit 1.2.0 → 1.5.0

package/packages/ampcode/commands/pptx.md

@@ -0,0 +1,1542 @@
+---
+name: pptx
+description: "Presentation creation, editing, and analysis. When Claude needs to work with presentations (.pptx files) for: (1) Creating new presentations, (2) Modifying or editing content, (3) Working with layouts, (4) Adding comments or speaker notes, or any other presentation tasks"
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# PPTX creation, editing, and analysis
+
+## Overview
+
+A user may ask you to create, edit, or analyze the contents of a .pptx file. A .pptx file is essentially a ZIP archive containing XML files and other resources that you can read or edit. You have different tools and workflows available for different tasks.
+
+## Reading and analyzing content
+
+### Text extraction
+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
+```
+
+### Raw XML access
+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>`
+
+**Note**: The unpack.py script is located at `skills/pptx/ooxml/scripts/unpack.py` relative to the project root. If the script doesn't exist at this path, use `find . -name "unpack.py"` to locate it.
+
+#### Key file structures
+* `ppt/presentation.xml` - Main presentation metadata and slide references
+* `ppt/slides/slide{N}.xml` - Individual slide contents (slide1.xml, slide2.xml, etc.)
+* `ppt/notesSlides/notesSlide{N}.xml` - Speaker notes for each slide
+* `ppt/comments/modernComment_*.xml` - Comments for specific slides
+* `ppt/slideLayouts/` - Layout templates for slides
+* `ppt/slideMasters/` - Master slide templates
+* `ppt/theme/` - Theme and styling information
+* `ppt/media/` - Images and other media files
+
+#### Typography and color extraction
+**When given an example design to emulate**: Always analyze the presentation's typography and colors first using the methods below:
+1. **Read theme file**: Check `ppt/theme/theme1.xml` for colors (`<a:clrScheme>`) and fonts (`<a:fontScheme>`)
+2. **Sample slide content**: Examine `ppt/slides/slide1.xml` for actual font usage (`<a:rPr>`) and colors
+3. **Search for patterns**: Use grep to find color (`<a:solidFill>`, `<a:srgbClr>`) and font references across all XML files
+
+## Creating a new PowerPoint presentation **without a template**
+
+When creating a new PowerPoint presentation from scratch, use the **html2pptx** workflow to convert HTML slides to PowerPoint with accurate positioning.
+
+### Design Principles
+
+**CRITICAL**: Before creating any presentation, analyze the content and choose appropriate design elements:
+1. **Consider the subject matter**: What is this presentation about? What tone, industry, or mood does it suggest?
+2. **Check for branding**: If the user mentions a company/organization, consider their brand colors and identity
+3. **Match palette to content**: Select colors that reflect the subject
+4. **State your approach**: Explain your design choices before writing code
+
+**Requirements**:
+- ✅ State your content-informed design approach BEFORE writing code
+- ✅ Use web-safe fonts only: Arial, Helvetica, Times New Roman, Georgia, Courier New, Verdana, Tahoma, Trebuchet MS, Impact
+- ✅ Create clear visual hierarchy through size, weight, and color
+- ✅ Ensure readability: strong contrast, appropriately sized text, clean alignment
+- ✅ Be consistent: repeat patterns, spacing, and visual language across slides
+
+#### Color Palette Selection
+
+**Choosing colors creatively**:
+- **Think beyond defaults**: What colors genuinely match this specific topic? Avoid autopilot choices.
+- **Consider multiple angles**: Topic, industry, mood, energy level, target audience, brand identity (if mentioned)
+- **Be adventurous**: Try unexpected combinations - a healthcare presentation doesn't have to be green, finance doesn't have to be navy
+- **Build your palette**: Pick 3-5 colors that work together (dominant colors + supporting tones + accent)
+- **Ensure contrast**: Text must be clearly readable on backgrounds
+
+**Example color palettes** (use these to spark creativity - choose one, adapt it, or create your own):
+
+1. **Classic Blue**: Deep navy (#1C2833), slate gray (#2E4053), silver (#AAB7B8), off-white (#F4F6F6)
+2. **Teal & Coral**: Teal (#5EA8A7), deep teal (#277884), coral (#FE4447), white (#FFFFFF)
+3. **Bold Red**: Red (#C0392B), bright red (#E74C3C), orange (#F39C12), yellow (#F1C40F), green (#2ECC71)
+4. **Warm Blush**: Mauve (#A49393), blush (#EED6D3), rose (#E8B4B8), cream (#FAF7F2)
+5. **Burgundy Luxury**: Burgundy (#5D1D2E), crimson (#951233), rust (#C15937), gold (#997929)
+6. **Deep Purple & Emerald**: Purple (#B165FB), dark blue (#181B24), emerald (#40695B), white (#FFFFFF)
+7. **Cream & Forest Green**: Cream (#FFE1C7), forest green (#40695B), white (#FCFCFC)
+8. **Pink & Purple**: Pink (#F8275B), coral (#FF574A), rose (#FF737D), purple (#3D2F68)
+9. **Lime & Plum**: Lime (#C5DE82), plum (#7C3A5F), coral (#FD8C6E), blue-gray (#98ACB5)
+10. **Black & Gold**: Gold (#BF9A4A), black (#000000), cream (#F4F6F6)
+11. **Sage & Terracotta**: Sage (#87A96B), terracotta (#E07A5F), cream (#F4F1DE), charcoal (#2C2C2C)
+12. **Charcoal & Red**: Charcoal (#292929), red (#E33737), light gray (#CCCBCB)
+13. **Vibrant Orange**: Orange (#F96D00), light gray (#F2F2F2), charcoal (#222831)
+14. **Forest Green**: Black (#191A19), green (#4E9F3D), dark green (#1E5128), white (#FFFFFF)
+15. **Retro Rainbow**: Purple (#722880), pink (#D72D51), orange (#EB5C18), amber (#F08800), gold (#DEB600)
+16. **Vintage Earthy**: Mustard (#E3B448), sage (#CBD18F), forest green (#3A6B35), cream (#F4F1DE)
+17. **Coastal Rose**: Old rose (#AD7670), beaver (#B49886), eggshell (#F3ECDC), ash gray (#BFD5BE)
+18. **Orange & Turquoise**: Light orange (#FC993E), grayish turquoise (#667C6F), white (#FCFCFC)
+
+#### Visual Details Options
+
+**Geometric Patterns**:
+- Diagonal section dividers instead of horizontal
+- Asymmetric column widths (30/70, 40/60, 25/75)
+- Rotated text headers at 90° or 270°
+- Circular/hexagonal frames for images
+- Triangular accent shapes in corners
+- Overlapping shapes for depth
+
+**Border & Frame Treatments**:
+- Thick single-color borders (10-20pt) on one side only
+- Double-line borders with contrasting colors
+- Corner brackets instead of full frames
+- L-shaped borders (top+left or bottom+right)
+- Underline accents beneath headers (3-5pt thick)
+
+**Typography Treatments**:
+- Extreme size contrast (72pt headlines vs 11pt body)
+- All-caps headers with wide letter spacing
+- Numbered sections in oversized display type
+- Monospace (Courier New) for data/stats/technical content
+- Condensed fonts (Arial Narrow) for dense information
+- Outlined text for emphasis
+
+**Chart & Data Styling**:
+- Monochrome charts with single accent color for key data
+- Horizontal bar charts instead of vertical
+- Dot plots instead of bar charts
+- Minimal gridlines or none at all
+- Data labels directly on elements (no legends)
+- Oversized numbers for key metrics
+
+**Layout Innovations**:
+- Full-bleed images with text overlays
+- Sidebar column (20-30% width) for navigation/context
+- Modular grid systems (3×3, 4×4 blocks)
+- Z-pattern or F-pattern content flow
+- Floating text boxes over colored shapes
+- Magazine-style multi-column layouts
+
+**Background Treatments**:
+- Solid color blocks occupying 40-60% of slide
+- Gradient fills (vertical or diagonal only)
+- Split backgrounds (two colors, diagonal or vertical)
+- Edge-to-edge color bands
+- Negative space as a design element
+
+### Layout Tips
+**When creating slides with charts or tables:**
+- **Two-column layout (PREFERRED)**: Use a header spanning the full width, then two columns below - text/bullets in one column and the featured content in the other. This provides better balance and makes charts/tables more readable. Use flexbox with unequal column widths (e.g., 40%/60% split) to optimize space for each content type.
+- **Full-slide layout**: Let the featured content (chart/table) take up the entire slide for maximum impact and readability
+- **NEVER vertically stack**: Do not place charts/tables below text in a single column - this causes poor readability and layout issues
+
+### Workflow
+1. **MANDATORY - READ ENTIRE FILE**: Read [`html2pptx.md`](html2pptx.md) completely from start to finish. **NEVER set any range limits when reading this file.** Read the full file content for detailed syntax, critical formatting rules, and best practices before proceeding with presentation creation.
+2. Create an HTML file for each slide with proper dimensions (e.g., 720pt × 405pt for 16:9)
+   - Use `<p>`, `<h1>`-`<h6>`, `<ul>`, `<ol>` for all text content
+   - Use `class="placeholder"` for areas where charts/tables will be added (render with gray background for visibility)
+   - **CRITICAL**: Rasterize gradients and icons as PNG images FIRST using Sharp, then reference in HTML
+   - **LAYOUT**: For slides with charts/tables/images, use either full-slide layout or two-column layout for better readability
+3. Create and run a JavaScript file using the [`html2pptx.js`](scripts/html2pptx.js) library to convert HTML slides to PowerPoint and save the presentation
+   - Use the `html2pptx()` function to process each HTML file
+   - Add charts and tables to placeholder areas using PptxGenJS API
+   - Save the presentation using `pptx.writeFile()`
+4. **Visual validation**: Generate thumbnails and inspect for layout issues
+   - Create thumbnail grid: `python scripts/thumbnail.py output.pptx workspace/thumbnails --cols 4`
+   - Read and carefully examine the thumbnail image for:
+     - **Text cutoff**: Text being cut off by header bars, shapes, or slide edges
+     - **Text overlap**: Text overlapping with other text or shapes
+     - **Positioning issues**: Content too close to slide boundaries or other elements
+     - **Contrast issues**: Insufficient contrast between text and backgrounds
+   - If issues found, adjust HTML margins/spacing/colors and regenerate the presentation
+   - Repeat until all slides are visually correct
+
+## Editing an existing PowerPoint presentation
+
+When edit slides in an existing PowerPoint presentation, you need to work with the raw Office Open XML (OOXML) format. This involves unpacking the .pptx file, editing the XML content, and repacking it.
+
+### Workflow
+1. **MANDATORY - READ ENTIRE FILE**: Read [`ooxml.md`](ooxml.md) (~500 lines) completely from start to finish.  **NEVER set any range limits when reading this file.**  Read the full file content for detailed guidance on OOXML structure and editing workflows before any presentation editing.
+2. Unpack the presentation: `python ooxml/scripts/unpack.py <office_file> <output_dir>`
+3. Edit the XML files (primarily `ppt/slides/slide{N}.xml` and related files)
+4. **CRITICAL**: Validate immediately after each edit and fix any validation errors before proceeding: `python ooxml/scripts/validate.py <dir> --original <file>`
+5. Pack the final presentation: `python ooxml/scripts/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, you'll need to duplicate and re-arrange template slides before then replacing placeholder context.
+
+### Workflow
+1. **Extract template text AND create visual thumbnail grid**:
+   * Extract text: `python -m markitdown template.pptx > template-content.md`
+   * Read `template-content.md`: Read the entire file to understand the contents of the template presentation. **NEVER set any range limits when reading this file.**
+   * Create thumbnail grids: `python scripts/thumbnail.py template.pptx`
+   * See [Creating Thumbnail Grids](#creating-thumbnail-grids) section for more details
+
+2. **Analyze template and save inventory to a file**:
+   * **Visual Analysis**: Review thumbnail grid(s) to understand slide layouts, design patterns, and visual structure
+   * Create and save a template inventory file at `template-inventory.md` containing:
+     ```markdown
+     # Template Inventory Analysis
+     **Total Slides: [count]**
+     **IMPORTANT: Slides are 0-indexed (first slide = 0, last slide = count-1)**
+
+     ## [Category Name]
+     - Slide 0: [Layout code if available] - Description/purpose
+     - Slide 1: [Layout code] - Description/purpose
+     - Slide 2: [Layout code] - Description/purpose
+     [... EVERY slide must be listed individually with its index ...]
+     ```
+   * **Using the thumbnail grid**: Reference the visual thumbnails to identify:
+     - Layout patterns (title slides, content layouts, section dividers)
+     - Image placeholder locations and counts
+     - Design consistency across slide groups
+     - Visual hierarchy and structure
+   * This inventory file is REQUIRED for selecting appropriate templates in the next step
+
+3. **Create presentation outline based on template inventory**:
+   * Review available templates from step 2.
+   * Choose an intro or title template for the first slide. This should be one of the first templates.
+   * Choose safe, text-based layouts for the other slides.
+   * **CRITICAL: Match layout structure to actual content**:
+     - Single-column layouts: Use for unified narrative or single topic
+     - Two-column layouts: Use ONLY when you have exactly 2 distinct items/concepts
+     - Three-column layouts: Use ONLY when you have exactly 3 distinct items/concepts
+     - Image + text layouts: Use ONLY when you have actual images to insert
+     - Quote layouts: Use ONLY for actual quotes from people (with attribution), never for emphasis
+     - Never use layouts with more placeholders than you have content
+     - If you have 2 items, don't force them into a 3-column layout
+     - If you have 4+ items, consider breaking into multiple slides or using a list format
+   * Count your actual content pieces BEFORE selecting the layout
+   * Verify each placeholder in the chosen layout will be filled with meaningful content
+   * Select one option representing the **best** layout for each content section.
+   * Save `outline.md` with content AND template mapping that leverages available designs
+   * Example template mapping:
+      ```
+      # Template slides to use (0-based indexing)
+      # WARNING: Verify indices are within range! Template with 73 slides has indices 0-72
+      # Mapping: slide numbers from outline -> template slide indices
+      template_mapping = [
+          0,   # Use slide 0 (Title/Cover)
+          34,  # Use slide 34 (B1: Title and body)
+          34,  # Use slide 34 again (duplicate for second B1)
+          50,  # Use slide 50 (E1: Quote)
+          54,  # Use slide 54 (F2: Closing + Text)
+      ]
+      ```
+
+4. **Duplicate, reorder, and delete slides using `rearrange.py`**:
+   * Use the `scripts/rearrange.py` script to create a new presentation with slides in the desired order:
+     ```bash
+     python scripts/rearrange.py template.pptx working.pptx 0,34,34,50,52
+     ```
+   * The script handles duplicating repeated slides, deleting unused slides, and reordering automatically
+   * Slide indices are 0-based (first slide is 0, second is 1, etc.)
+   * The same slide index can appear multiple times to duplicate that slide
+
+5. **Extract ALL text using the `inventory.py` script**:
+   * **Run inventory extraction**:
+     ```bash
+     python scripts/inventory.py working.pptx text-inventory.json
+     ```
+   * **Read text-inventory.json**: Read the entire text-inventory.json file to understand all shapes and their properties. **NEVER set any range limits when reading this file.**
+
+   * The inventory JSON structure:
+      ```json
+        {
+          "slide-0": {
+            "shape-0": {
+              "placeholder_type": "TITLE",  // or null for non-placeholders
+              "left": 1.5,                  // position in inches
+              "top": 2.0,
+              "width": 7.5,
+              "height": 1.2,
+              "paragraphs": [
+                {
+                  "text": "Paragraph text",
+                  // Optional properties (only included when non-default):
+                  "bullet": true,           // explicit bullet detected
+                  "level": 0,               // only included when bullet is true
+                  "alignment": "CENTER",    // CENTER, RIGHT (not LEFT)
+                  "space_before": 10.0,     // space before paragraph in points
+                  "space_after": 6.0,       // space after paragraph in points
+                  "line_spacing": 22.4,     // line spacing in points
+                  "font_name": "Arial",     // from first run
+                  "font_size": 14.0,        // in points
+                  "bold": true,
+                  "italic": false,
+                  "underline": false,
+                  "color": "FF0000"         // RGB color
+                }
+              ]
+            }
+          }
+        }
+      ```
+
+   * Key features:
+     - **Slides**: Named as "slide-0", "slide-1", etc.
+     - **Shapes**: Ordered by visual position (top-to-bottom, left-to-right) as "shape-0", "shape-1", etc.
+     - **Placeholder types**: TITLE, CENTER_TITLE, SUBTITLE, BODY, OBJECT, or null
+     - **Default font size**: `default_font_size` in points extracted from layout placeholders (when available)
+     - **Slide numbers are filtered**: Shapes with SLIDE_NUMBER placeholder type are automatically excluded from inventory
+     - **Bullets**: When `bullet: true`, `level` is always included (even if 0)
+     - **Spacing**: `space_before`, `space_after`, and `line_spacing` in points (only included when set)
+     - **Colors**: `color` for RGB (e.g., "FF0000"), `theme_color` for theme colors (e.g., "DARK_1")
+     - **Properties**: Only non-default values are included in the output
+
+6. **Generate replacement text and save the data to a JSON file**
+   Based on the text inventory from the previous step:
+   - **CRITICAL**: First verify which shapes exist in the inventory - only reference shapes that are actually present
+   - **VALIDATION**: The replace.py script will validate that all shapes in your replacement JSON exist in the inventory
+     - If you reference a non-existent shape, you'll get an error showing available shapes
+     - If you reference a non-existent slide, you'll get an error indicating the slide doesn't exist
+     - All validation errors are shown at once before the script exits
+   - **IMPORTANT**: The replace.py script uses inventory.py internally to identify ALL text shapes
+   - **AUTOMATIC CLEARING**: ALL text shapes from the inventory will be cleared unless you provide "paragraphs" for them
+   - Add a "paragraphs" field to shapes that need content (not "replacement_paragraphs")
+   - Shapes without "paragraphs" in the replacement JSON will have their text cleared automatically
+   - Paragraphs with bullets will be automatically left aligned. Don't set the `alignment` property on when `"bullet": true`
+   - Generate appropriate replacement content for placeholder text
+   - Use shape size to determine appropriate content length
+   - **CRITICAL**: Include paragraph properties from the original inventory - don't just provide text
+   - **IMPORTANT**: When bullet: true, do NOT include bullet symbols (•, -, *) in text - they're added automatically
+   - **ESSENTIAL FORMATTING RULES**:
+     - Headers/titles should typically have `"bold": true`
+     - List items should have `"bullet": true, "level": 0` (level is required when bullet is true)
+     - Preserve any alignment properties (e.g., `"alignment": "CENTER"` for centered text)
+     - Include font properties when different from default (e.g., `"font_size": 14.0`, `"font_name": "Lora"`)
+     - Colors: Use `"color": "FF0000"` for RGB or `"theme_color": "DARK_1"` for theme colors
+     - The replacement script expects **properly formatted paragraphs**, not just text strings
+     - **Overlapping shapes**: Prefer shapes with larger default_font_size or more appropriate placeholder_type
+   - Save the updated inventory with replacements to `replacement-text.json`
+   - **WARNING**: Different template layouts have different shape counts - always check the actual inventory before creating replacements
+
+   Example paragraphs field showing proper formatting:
+   ```json
+   "paragraphs": [
+     {
+       "text": "New presentation title text",
+       "alignment": "CENTER",
+       "bold": true
+     },
+     {
+       "text": "Section Header",
+       "bold": true
+     },
+     {
+       "text": "First bullet point without bullet symbol",
+       "bullet": true,
+       "level": 0
+     },
+     {
+       "text": "Red colored text",
+       "color": "FF0000"
+     },
+     {
+       "text": "Theme colored text",
+       "theme_color": "DARK_1"
+     },
+     {
+       "text": "Regular paragraph text without special formatting"
+     }
+   ]
+   ```
+
+   **Shapes not listed in the replacement JSON are automatically cleared**:
+   ```json
+   {
+     "slide-0": {
+       "shape-0": {
+         "paragraphs": [...] // This shape gets new text
+       }
+       // shape-1 and shape-2 from inventory will be cleared automatically
+     }
+   }
+   ```
+
+   **Common formatting patterns for presentations**:
+   - Title slides: Bold text, sometimes centered
+   - Section headers within slides: Bold text
+   - Bullet lists: Each item needs `"bullet": true, "level": 0`
+   - Body text: Usually no special properties needed
+   - Quotes: May have special alignment or font properties
+
+7. **Apply replacements using the `replace.py` script**
+   ```bash
+   python scripts/replace.py working.pptx replacement-text.json output.pptx
+   ```
+
+   The script will:
+   - First extract the inventory of ALL text shapes using functions from inventory.py
+   - Validate that all shapes in the replacement JSON exist in the inventory
+   - Clear text from ALL shapes identified in the inventory
+   - Apply new text only to shapes with "paragraphs" defined in the replacement JSON
+   - Preserve formatting by applying paragraph properties from the JSON
+   - Handle bullets, alignment, font properties, and colors automatically
+   - Save the updated presentation
+
+   Example validation errors:
+   ```
+   ERROR: Invalid shapes in replacement JSON:
+     - Shape 'shape-99' not found on 'slide-0'. Available shapes: shape-0, shape-1, shape-4
+     - Slide 'slide-999' not found in inventory
+   ```
+
+   ```
+   ERROR: Replacement text made overflow worse in these shapes:
+     - slide-0/shape-2: overflow worsened by 1.25" (was 0.00", now 1.25")
+   ```
+
+## Creating Thumbnail Grids
+
+To create visual thumbnail grids of PowerPoint slides for quick analysis and reference:
+
+```bash
+python scripts/thumbnail.py template.pptx [output_prefix]
+```
+
+**Features**:
+- Creates: `thumbnails.jpg` (or `thumbnails-1.jpg`, `thumbnails-2.jpg`, etc. for large decks)
+- Default: 5 columns, max 30 slides per grid (5×6)
+- Custom prefix: `python scripts/thumbnail.py template.pptx my-grid`
+  - Note: The output prefix should include the path if you want output in a specific directory (e.g., `workspace/my-grid`)
+- Adjust columns: `--cols 4` (range: 3-6, affects slides per grid)
+- Grid limits: 3 cols = 12 slides/grid, 4 cols = 20, 5 cols = 30, 6 cols = 42
+- Slides are zero-indexed (Slide 0, Slide 1, etc.)
+
+**Use cases**:
+- Template analysis: Quickly understand slide layouts and design patterns
+- Content review: Visual overview of entire presentation
+- Navigation reference: Find specific slides by their visual appearance
+- Quality check: Verify all slides are properly formatted
+
+**Examples**:
+```bash
+# Basic usage
+python scripts/thumbnail.py presentation.pptx
+
+# Combine options: custom name, columns
+python scripts/thumbnail.py template.pptx analysis --cols 4
+```
+
+## Converting Slides to Images
+
+To visually analyze PowerPoint slides, convert them to images using a two-step process:
+
+1. **Convert PPTX to PDF**:
+   ```bash
+   soffice --headless --convert-to pdf template.pptx
+   ```
+
+2. **Convert PDF pages to JPEG images**:
+   ```bash
+   pdftoppm -jpeg -r 150 template.pdf slide
+   ```
+   This creates files like `slide-1.jpg`, `slide-2.jpg`, etc.
+
+Options:
+- `-r 150`: Sets resolution to 150 DPI (adjust for quality/size balance)
+- `-jpeg`: Output JPEG format (use `-png` for PNG if preferred)
+- `-f N`: First page to convert (e.g., `-f 2` starts from page 2)
+- `-l N`: Last page to convert (e.g., `-l 5` stops at page 5)
+- `slide`: Prefix for output files
+
+Example for specific range:
+```bash
+pdftoppm -jpeg -r 150 -f 2 -l 5 template.pdf slide  # Converts only pages 2-5
+```
+
+## Code Style Guidelines
+**IMPORTANT**: When generating code for PPTX operations:
+- Write concise code
+- Avoid verbose variable names and redundant operations
+- Avoid unnecessary print statements
+
+## Dependencies
+
+Required dependencies (should already be installed):
+
+- **markitdown**: `pip install "markitdown[pptx]"` (for text extraction from presentations)
+- **pptxgenjs**: `npm install -g pptxgenjs` (for creating presentations via html2pptx)
+- **playwright**: `npm install -g playwright` (for HTML rendering in html2pptx)
+- **react-icons**: `npm install -g react-icons react react-dom` (for icons)
+- **sharp**: `npm install -g sharp` (for SVG rasterization and image processing)
+- **LibreOffice**: `sudo apt-get install libreoffice` (for PDF conversion)
+- **Poppler**: `sudo apt-get install poppler-utils` (for pdftoppm to convert PDF to images)
+- **defusedxml**: `pip install defusedxml` (for secure XML parsing)
+
+## Html2pptx
+
+# 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**
+- Text in `<div>` or `<span>` without a text tag will be silently ignored
+
+**NEVER use manual bullet symbols (•, -, *, etc.)** - Use `<ul>` or `<ol>` lists instead
+
+**ONLY use web-safe fonts that are universally available:**
+- ✅ Web-safe fonts: `Arial`, `Helvetica`, `Times New Roman`, `Georgia`, `Courier New`, `Verdana`, `Tahoma`, `Trebuchet MS`, `Impact`, `Comic Sans MS`
+- ❌ Wrong: `'Segoe UI'`, `'SF Pro'`, `'Roboto'`, custom fonts - **Might cause rendering issues**
+
+### Styling
+
+- Use `display: flex` on body to prevent margin collapse from breaking overflow validation
+- Use `margin` for spacing (padding included in size)
+- Inline formatting: Use `<b>`, `<i>`, `<u>` tags OR `<span>` with CSS styles
+  - `<span>` supports: `font-weight: bold`, `font-style: italic`, `text-decoration: underline`, `color: #rrggbb`
+  - `<span>` does NOT support: `margin`, `padding` (not supported in PowerPoint text runs)
+  - Example: `<span style="font-weight: bold; color: #667eea;">Bold blue text</span>`
+- Flexbox works - positions calculated from rendered layout
+- Use hex colors with `#` prefix in CSS
+- **Text alignment**: Use CSS `text-align` (`center`, `right`, etc.) when needed as a hint to PptxGenJS for text formatting if text lengths are slightly off
+
+### Shape Styling (DIV elements only)
+
+**IMPORTANT: Backgrounds, borders, and shadows only work on `<div>` elements, NOT on text elements (`<p>`, `<h1>`-`<h6>`, `<ul>`, `<ol>`)**
+
+- **Backgrounds**: CSS `background` or `background-color` on `<div>` elements only
+  - Example: `<div style="background: #f0f0f0;">` - Creates a shape with background
+- **Borders**: CSS `border` on `<div>` elements converts to PowerPoint shape borders
+  - Supports uniform borders: `border: 2px solid #333333`
+  - Supports partial borders: `border-left`, `border-right`, `border-top`, `border-bottom` (rendered as line shapes)
+  - Example: `<div style="border-left: 8pt solid #E76F51;">`
+- **Border radius**: CSS `border-radius` on `<div>` elements for rounded corners
+  - `border-radius: 50%` or higher creates circular shape
+  - Percentages <50% calculated relative to shape's smaller dimension
+  - Supports px and pt units (e.g., `border-radius: 8pt;`, `border-radius: 12px;`)
+  - Example: `<div style="border-radius: 25%;">` on 100x200px box = 25% of 100px = 25px radius
+- **Box shadows**: CSS `box-shadow` on `<div>` elements converts to PowerPoint shadows
+  - Supports outer shadows only (inset shadows are ignored to prevent corruption)
+  - Example: `<div style="box-shadow: 2px 2px 8px rgba(0, 0, 0, 0.3);">`
+  - Note: Inset/inner shadows are not supported by PowerPoint and will be skipped
+
+### Icons & Gradients
+
+- **CRITICAL: Never use CSS gradients (`linear-gradient`, `radial-gradient`)** - They don't convert to PowerPoint
+- **ALWAYS create gradient/icon PNGs FIRST using Sharp, then reference in HTML**
+- For gradients: Rasterize SVG to PNG background images
+- For icons: Rasterize react-icons SVG to PNG images
+- All visual effects must be pre-rendered as raster images before HTML rendering
+
+**Rasterizing Icons with Sharp:**
+
+```javascript
+const React = require('react');
+const ReactDOMServer = require('react-dom/server');
+const sharp = require('sharp');
+const { FaHome } = require('react-icons/fa');
+
+async function rasterizeIconPng(IconComponent, color, size = "256", filename) {
+  const svgString = ReactDOMServer.renderToStaticMarkup(
+    React.createElement(IconComponent, { color: `#${color}`, size: size })
+  );
+
+  // Convert SVG to PNG using Sharp
+  await sharp(Buffer.from(svgString))
+    .png()
+    .toFile(filename);
+
+  return filename;
+}
+
+// Usage: Rasterize icon before using in HTML
+const iconPath = await rasterizeIconPng(FaHome, "4472c4", "256", "home-icon.png");
+// Then reference in HTML: <img src="home-icon.png" style="width: 40pt; height: 40pt;">
+```
+
+**Rasterizing Gradients with Sharp:**
+
+```javascript
+const sharp = require('sharp');
+
+async function createGradientBackground(filename) {
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="1000" height="562.5">
+    <defs>
+      <linearGradient id="g" x1="0%" y1="0%" x2="100%" y2="100%">
+        <stop offset="0%" style="stop-color:#COLOR1"/>
+        <stop offset="100%" style="stop-color:#COLOR2"/>
+      </linearGradient>
+    </defs>
+    <rect width="100%" height="100%" fill="url(#g)"/>
+  </svg>`;
+
+  await sharp(Buffer.from(svg))
+    .png()
+    .toFile(filename);
+
+  return filename;
+}
+
+// Usage: Create gradient background before HTML
+const bgPath = await createGradientBackground("gradient-bg.png");
+// Then in HTML: <body style="background-image: url('gradient-bg.png');">
+```
+
+### Example
+
+```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; }
+.box {
+  background: #70ad47; padding: 20pt; border: 3px solid #5a8f37;
+  border-radius: 12pt; box-shadow: 3px 3px 10px rgba(0, 0, 0, 0.25);
+}
+</style>
+</head>
+<body>
+<div class="content">
+  <h1>Recipe Title</h1>
+  <ul>
+    <li><b>Item:</b> Description</li>
+  </ul>
+  <p>Text with <b>bold</b>, <i>italic</i>, <u>underline</u>.</p>
+  <div id="chart" class="placeholder" style="width: 350pt; height: 200pt;"></div>
+
+  <!-- Text MUST be in <p> tags -->
+  <div class="box">
+    <p>5</p>
+  </div>
+</div>
+</body>
+</html>
+```
+
+## Using the html2pptx Library
+
+### Dependencies
+
+These libraries have been globally installed and are available to use:
+- `pptxgenjs`
+- `playwright`
+- `sharp`
+
+### Basic Usage
+
+```javascript
+const pptxgen = require('pptxgenjs');
+const html2pptx = require('./html2pptx');
+
+const pptx = new pptxgen();
+pptx.layout = 'LAYOUT_16x9';  // Must match HTML body dimensions
+
+const { slide, placeholders } = await html2pptx('slide1.html', pptx);
+
+// Add chart to placeholder area
+if (placeholders.length > 0) {
+    slide.addChart(pptx.charts.LINE, chartData, placeholders[0]);
+}
+
+await pptx.writeFile('output.pptx');
+```
+
+### API Reference
+
+#### Function Signature
+```javascript
+await html2pptx(htmlFile, pres, options)
+```
+
+#### Parameters
+- `htmlFile` (string): Path to HTML file (absolute or relative)
+- `pres` (pptxgen): PptxGenJS presentation instance with layout already set
+- `options` (object, optional):
+  - `tmpDir` (string): Temporary directory for generated files (default: `process.env.TMPDIR || '/tmp'`)
+  - `slide` (object): Existing slide to reuse (default: creates new slide)
+
+#### Returns
+```javascript
+{
+    slide: pptxgenSlide,           // The created/updated slide
+    placeholders: [                 // Array of placeholder positions
+        { id: string, x: number, y: number, w: number, h: number },
+        ...
+    ]
+}
+```
+
+### Validation
+
+The library automatically validates and collects all errors before throwing:
+
+1. **HTML dimensions must match presentation layout** - Reports dimension mismatches
+2. **Content must not overflow body** - Reports overflow with exact measurements
+3. **CSS gradients** - Reports unsupported gradient usage
+4. **Text element styling** - Reports backgrounds/borders/shadows on text elements (only allowed on divs)
+
+**All validation errors are collected and reported together** in a single error message, allowing you to fix all issues at once instead of one at a time.
+
+### Working with Placeholders
+
+```javascript
+const { slide, placeholders } = await html2pptx('slide.html', pptx);
+
+// Use first placeholder
+slide.addChart(pptx.charts.BAR, data, placeholders[0]);
+
+// Find by ID
+const chartArea = placeholders.find(p => p.id === 'chart-area');
+slide.addChart(pptx.charts.LINE, data, chartArea);
+```
+
+### Complete Example
+
+```javascript
+const pptxgen = require('pptxgenjs');
+const html2pptx = require('./html2pptx');
+
+async function createPresentation() {
+    const pptx = new pptxgen();
+    pptx.layout = 'LAYOUT_16x9';
+    pptx.author = 'Your Name';
+    pptx.title = 'My Presentation';
+
+    // Slide 1: Title
+    const { slide: slide1 } = await html2pptx('slides/title.html', pptx);
+
+    // Slide 2: Content with chart
+    const { slide: slide2, placeholders } = await html2pptx('slides/data.html', pptx);
+
+    const chartData = [{
+        name: 'Sales',
+        labels: ['Q1', 'Q2', 'Q3', 'Q4'],
+        values: [4500, 5500, 6200, 7100]
+    }];
+
+    slide2.addChart(pptx.charts.BAR, chartData, {
+        ...placeholders[0],
+        showTitle: true,
+        title: 'Quarterly Sales',
+        showCatAxisTitle: true,
+        catAxisTitle: 'Quarter',
+        showValAxisTitle: true,
+        valAxisTitle: 'Sales ($000s)'
+    });
+
+    // Save
+    await pptx.writeFile({ fileName: 'presentation.pptx' });
+    console.log('Presentation created successfully!');
+}
+
+createPresentation().catch(console.error);
+```
+
+## Using PptxGenJS
+
+After converting HTML to slides with `html2pptx`, you'll use PptxGenJS to add dynamic content like charts, images, and additional elements.
+
+### ⚠️ Critical Rules
+
+#### Colors
+- **NEVER use `#` prefix** with hex colors in PptxGenJS - causes file corruption
+- ✅ Correct: `color: "FF0000"`, `fill: { color: "0066CC" }`
+- ❌ Wrong: `color: "#FF0000"` (breaks document)
+
+### Adding Images
+
+Always calculate aspect ratios from actual image dimensions:
+
+```javascript
+// Get image dimensions: identify image.png | grep -o '[0-9]* x [0-9]*'
+const imgWidth = 1860, imgHeight = 1519;  // From actual file
+const aspectRatio = imgWidth / imgHeight;
+
+const h = 3;  // Max height
+const w = h * aspectRatio;
+const x = (10 - w) / 2;  // Center on 16:9 slide
+
+slide.addImage({ path: "chart.png", x, y: 1.5, w, h });
+```
+
+### Adding Text
+
+```javascript
+// Rich text with formatting
+slide.addText([
+    { text: "Bold ", options: { bold: true } },
+    { text: "Italic ", options: { italic: true } },
+    { text: "Normal" }
+], {
+    x: 1, y: 2, w: 8, h: 1
+});
+```
+
+### Adding Shapes
+
+```javascript
+// Rectangle
+slide.addShape(pptx.shapes.RECTANGLE, {
+    x: 1, y: 1, w: 3, h: 2,
+    fill: { color: "4472C4" },
+    line: { color: "000000", width: 2 }
+});
+
+// Circle
+slide.addShape(pptx.shapes.OVAL, {
+    x: 5, y: 1, w: 2, h: 2,
+    fill: { color: "ED7D31" }
+});
+
+// Rounded rectangle
+slide.addShape(pptx.shapes.ROUNDED_RECTANGLE, {
+    x: 1, y: 4, w: 3, h: 1.5,
+    fill: { color: "70AD47" },
+    rectRadius: 0.2
+});
+```
+
+### Adding Charts
+
+**Required for most charts:** Axis labels using `catAxisTitle` (category) and `valAxisTitle` (value).
+
+**Chart Data Format:**
+- Use **single series with all labels** for simple bar/line charts
+- Each series creates a separate legend entry
+- Labels array defines X-axis values
+
+**Time Series Data - Choose Correct Granularity:**
+- **< 30 days**: Use daily grouping (e.g., "10-01", "10-02") - avoid monthly aggregation that creates single-point charts
+- **30-365 days**: Use monthly grouping (e.g., "2024-01", "2024-02")
+- **> 365 days**: Use yearly grouping (e.g., "2023", "2024")
+- **Validate**: Charts with only 1 data point likely indicate incorrect aggregation for the time period
+
+```javascript
+const { slide, placeholders } = await html2pptx('slide.html', pptx);
+
+// CORRECT: Single series with all labels
+slide.addChart(pptx.charts.BAR, [{
+    name: "Sales 2024",
+    labels: ["Q1", "Q2", "Q3", "Q4"],
+    values: [4500, 5500, 6200, 7100]
+}], {
+    ...placeholders[0],  // Use placeholder position
+    barDir: 'col',       // 'col' = vertical bars, 'bar' = horizontal
+    showTitle: true,
+    title: 'Quarterly Sales',
+    showLegend: false,   // No legend needed for single series
+    // Required axis labels
+    showCatAxisTitle: true,
+    catAxisTitle: 'Quarter',
+    showValAxisTitle: true,
+    valAxisTitle: 'Sales ($000s)',
+    // Optional: Control scaling (adjust min based on data range for better visualization)
+    valAxisMaxVal: 8000,
+    valAxisMinVal: 0,  // Use 0 for counts/amounts; for clustered data (e.g., 4500-7100), consider starting closer to min value
+    valAxisMajorUnit: 2000,  // Control y-axis label spacing to prevent crowding
+    catAxisLabelRotate: 45,  // Rotate labels if crowded
+    dataLabelPosition: 'outEnd',
+    dataLabelColor: '000000',
+    // Use single color for single-series charts
+    chartColors: ["4472C4"]  // All bars same color
+});
+```
+
+#### Scatter Chart
+
+**IMPORTANT**: Scatter chart data format is unusual - first series contains X-axis values, subsequent series contain Y-values:
+
+```javascript
+// Prepare data
+const data1 = [{ x: 10, y: 20 }, { x: 15, y: 25 }, { x: 20, y: 30 }];
+const data2 = [{ x: 12, y: 18 }, { x: 18, y: 22 }];
+
+const allXValues = [...data1.map(d => d.x), ...data2.map(d => d.x)];
+
+slide.addChart(pptx.charts.SCATTER, [
+    { name: 'X-Axis', values: allXValues },  // First series = X values
+    { name: 'Series 1', values: data1.map(d => d.y) },  // Y values only
+    { name: 'Series 2', values: data2.map(d => d.y) }   // Y values only
+], {
+    x: 1, y: 1, w: 8, h: 4,
+    lineSize: 0,  // 0 = no connecting lines
+    lineDataSymbol: 'circle',
+    lineDataSymbolSize: 6,
+    showCatAxisTitle: true,
+    catAxisTitle: 'X Axis',
+    showValAxisTitle: true,
+    valAxisTitle: 'Y Axis',
+    chartColors: ["4472C4", "ED7D31"]
+});
+```
+
+#### Line Chart
+
+```javascript
+slide.addChart(pptx.charts.LINE, [{
+    name: "Temperature",
+    labels: ["Jan", "Feb", "Mar", "Apr"],
+    values: [32, 35, 42, 55]
+}], {
+    x: 1, y: 1, w: 8, h: 4,
+    lineSize: 4,
+    lineSmooth: true,
+    // Required axis labels
+    showCatAxisTitle: true,
+    catAxisTitle: 'Month',
+    showValAxisTitle: true,
+    valAxisTitle: 'Temperature (°F)',
+    // Optional: Y-axis range (set min based on data range for better visualization)
+    valAxisMinVal: 0,     // For ranges starting at 0 (counts, percentages, etc.)
+    valAxisMaxVal: 60,
+    valAxisMajorUnit: 20,  // Control y-axis label spacing to prevent crowding (e.g., 10, 20, 25)
+    // valAxisMinVal: 30,  // PREFERRED: For data clustered in a range (e.g., 32-55 or ratings 3-5), start axis closer to min value to show variation
+    // Optional: Chart colors
+    chartColors: ["4472C4", "ED7D31", "A5A5A5"]
+});
+```
+
+#### Pie Chart (No Axis Labels Required)
+
+**CRITICAL**: Pie charts require a **single data series** with all categories in the `labels` array and corresponding values in the `values` array.
+
+```javascript
+slide.addChart(pptx.charts.PIE, [{
+    name: "Market Share",
+    labels: ["Product A", "Product B", "Other"],  // All categories in one array
+    values: [35, 45, 20]  // All values in one array
+}], {
+    x: 2, y: 1, w: 6, h: 4,
+    showPercent: true,
+    showLegend: true,
+    legendPos: 'r',  // right
+    chartColors: ["4472C4", "ED7D31", "A5A5A5"]
+});
+```
+
+#### Multiple Data Series
+
+```javascript
+slide.addChart(pptx.charts.LINE, [
+    {
+        name: "Product A",
+        labels: ["Q1", "Q2", "Q3", "Q4"],
+        values: [10, 20, 30, 40]
+    },
+    {
+        name: "Product B",
+        labels: ["Q1", "Q2", "Q3", "Q4"],
+        values: [15, 25, 20, 35]
+    }
+], {
+    x: 1, y: 1, w: 8, h: 4,
+    showCatAxisTitle: true,
+    catAxisTitle: 'Quarter',
+    showValAxisTitle: true,
+    valAxisTitle: 'Revenue ($M)'
+});
+```
+
+### Chart Colors
+
+**CRITICAL**: Use hex colors **without** the `#` prefix - including `#` causes file corruption.
+
+**Align chart colors with your chosen design palette**, ensuring sufficient contrast and distinctiveness for data visualization. Adjust colors for:
+- Strong contrast between adjacent series
+- Readability against slide backgrounds
+- Accessibility (avoid red-green only combinations)
+
+```javascript
+// Example: Ocean palette-inspired chart colors (adjusted for contrast)
+const chartColors = ["16A085", "FF6B9D", "2C3E50", "F39C12", "9B59B6"];
+
+// Single-series chart: Use one color for all bars/points
+slide.addChart(pptx.charts.BAR, [{
+    name: "Sales",
+    labels: ["Q1", "Q2", "Q3", "Q4"],
+    values: [4500, 5500, 6200, 7100]
+}], {
+    ...placeholders[0],
+    chartColors: ["16A085"],  // All bars same color
+    showLegend: false
+});
+
+// Multi-series chart: Each series gets a different color
+slide.addChart(pptx.charts.LINE, [
+    { name: "Product A", labels: ["Q1", "Q2", "Q3"], values: [10, 20, 30] },
+    { name: "Product B", labels: ["Q1", "Q2", "Q3"], values: [15, 25, 20] }
+], {
+    ...placeholders[0],
+    chartColors: ["16A085", "FF6B9D"]  // One color per series
+});
+```
+
+### Adding Tables
+
+Tables can be added with basic or advanced formatting:
+
+#### Basic Table
+
+```javascript
+slide.addTable([
+    ["Header 1", "Header 2", "Header 3"],
+    ["Row 1, Col 1", "Row 1, Col 2", "Row 1, Col 3"],
+    ["Row 2, Col 1", "Row 2, Col 2", "Row 2, Col 3"]
+], {
+    x: 0.5,
+    y: 1,
+    w: 9,
+    h: 3,
+    border: { pt: 1, color: "999999" },
+    fill: { color: "F1F1F1" }
+});
+```
+
+#### Table with Custom Formatting
+
+```javascript
+const tableData = [
+    // Header row with custom styling
+    [
+        { text: "Product", options: { fill: { color: "4472C4" }, color: "FFFFFF", bold: true } },
+        { text: "Revenue", options: { fill: { color: "4472C4" }, color: "FFFFFF", bold: true } },
+        { text: "Growth", options: { fill: { color: "4472C4" }, color: "FFFFFF", bold: true } }
+    ],
+    // Data rows
+    ["Product A", "$50M", "+15%"],
+    ["Product B", "$35M", "+22%"],
+    ["Product C", "$28M", "+8%"]
+];
+
+slide.addTable(tableData, {
+    x: 1,
+    y: 1.5,
+    w: 8,
+    h: 3,
+    colW: [3, 2.5, 2.5],  // Column widths
+    rowH: [0.5, 0.6, 0.6, 0.6],  // Row heights
+    border: { pt: 1, color: "CCCCCC" },
+    align: "center",
+    valign: "middle",
+    fontSize: 14
+});
+```
+
+#### Table with Merged Cells
+
+```javascript
+const mergedTableData = [
+    [
+        { text: "Q1 Results", options: { colspan: 3, fill: { color: "4472C4" }, color: "FFFFFF", bold: true } }
+    ],
+    ["Product", "Sales", "Market Share"],
+    ["Product A", "$25M", "35%"],
+    ["Product B", "$18M", "25%"]
+];
+
+slide.addTable(mergedTableData, {
+    x: 1,
+    y: 1,
+    w: 8,
+    h: 2.5,
+    colW: [3, 2.5, 2.5],
+    border: { pt: 1, color: "DDDDDD" }
+});
+```
+
+### Table Options
+
+Common table options:
+- `x, y, w, h` - Position and size
+- `colW` - Array of column widths (in inches)
+- `rowH` - Array of row heights (in inches)
+- `border` - Border style: `{ pt: 1, color: "999999" }`
+- `fill` - Background color (no # prefix)
+- `align` - Text alignment: "left", "center", "right"
+- `valign` - Vertical alignment: "top", "middle", "bottom"
+- `fontSize` - Text size
+- `autoPage` - Auto-create new slides if content overflows
+
+## Ooxml
+
+# Office Open XML Technical Reference for PowerPoint
+
+**Important: Read this entire document before starting.** Critical XML schema rules and formatting requirements are covered throughout. Incorrect implementation can create invalid PPTX files that PowerPoint cannot open.
+
+## Technical Guidelines
+
+### Schema Compliance
+- **Element ordering in `<p:txBody>`**: `<a:bodyPr>`, `<a:lstStyle>`, `<a:p>`
+- **Whitespace**: Add `xml:space='preserve'` to `<a:t>` elements with leading/trailing spaces
+- **Unicode**: Escape characters in ASCII content: `"` becomes `&#8220;`
+- **Images**: Add to `ppt/media/`, reference in slide XML, set dimensions to fit slide bounds
+- **Relationships**: Update `ppt/slides/_rels/slideN.xml.rels` for each slide's resources
+- **Dirty attribute**: Add `dirty="0"` to `<a:rPr>` and `<a:endParaRPr>` elements to indicate clean state
+
+## Presentation Structure
+
+### Basic Slide Structure
+```xml
+<!-- ppt/slides/slide1.xml -->
+<p:sld>
+  <p:cSld>
+    <p:spTree>
+      <p:nvGrpSpPr>...</p:nvGrpSpPr>
+      <p:grpSpPr>...</p:grpSpPr>
+      <!-- Shapes go here -->
+    </p:spTree>
+  </p:cSld>
+</p:sld>
+```
+
+### Text Box / Shape with Text
+```xml
+<p:sp>
+  <p:nvSpPr>
+    <p:cNvPr id="2" name="Title"/>
+    <p:cNvSpPr>
+      <a:spLocks noGrp="1"/>
+    </p:cNvSpPr>
+    <p:nvPr>
+      <p:ph type="ctrTitle"/>
+    </p:nvPr>
+  </p:nvSpPr>
+  <p:spPr>
+    <a:xfrm>
+      <a:off x="838200" y="365125"/>
+      <a:ext cx="7772400" cy="1470025"/>
+    </a:xfrm>
+  </p:spPr>
+  <p:txBody>
+    <a:bodyPr/>
+    <a:lstStyle/>
+    <a:p>
+      <a:r>
+        <a:t>Slide Title</a:t>
+      </a:r>
+    </a:p>
+  </p:txBody>
+</p:sp>
+```
+
+### Text Formatting
+```xml
+<!-- Bold -->
+<a:r>
+  <a:rPr b="1"/>
+  <a:t>Bold Text</a:t>
+</a:r>
+
+<!-- Italic -->
+<a:r>
+  <a:rPr i="1"/>
+  <a:t>Italic Text</a:t>
+</a:r>
+
+<!-- Underline -->
+<a:r>
+  <a:rPr u="sng"/>
+  <a:t>Underlined</a:t>
+</a:r>
+
+<!-- Highlight -->
+<a:r>
+  <a:rPr>
+    <a:highlight>
+      <a:srgbClr val="FFFF00"/>
+    </a:highlight>
+  </a:rPr>
+  <a:t>Highlighted Text</a:t>
+</a:r>
+
+<!-- Font and Size -->
+<a:r>
+  <a:rPr sz="2400" typeface="Arial">
+    <a:solidFill>
+      <a:srgbClr val="FF0000"/>
+    </a:solidFill>
+  </a:rPr>
+  <a:t>Colored Arial 24pt</a:t>
+</a:r>
+
+<!-- Complete formatting example -->
+<a:r>
+  <a:rPr lang="en-US" sz="1400" b="1" dirty="0">
+    <a:solidFill>
+      <a:srgbClr val="FAFAFA"/>
+    </a:solidFill>
+  </a:rPr>
+  <a:t>Formatted text</a:t>
+</a:r>
+```
+
+### Lists
+```xml
+<!-- Bullet list -->
+<a:p>
+  <a:pPr lvl="0">
+    <a:buChar char="•"/>
+  </a:pPr>
+  <a:r>
+    <a:t>First bullet point</a:t>
+  </a:r>
+</a:p>
+
+<!-- Numbered list -->
+<a:p>
+  <a:pPr lvl="0">
+    <a:buAutoNum type="arabicPeriod"/>
+  </a:pPr>
+  <a:r>
+    <a:t>First numbered item</a:t>
+  </a:r>
+</a:p>
+
+<!-- Second level indent -->
+<a:p>
+  <a:pPr lvl="1">
+    <a:buChar char="•"/>
+  </a:pPr>
+  <a:r>
+    <a:t>Indented bullet</a:t>
+  </a:r>
+</a:p>
+```
+
+### Shapes
+```xml
+<!-- Rectangle -->
+<p:sp>
+  <p:nvSpPr>
+    <p:cNvPr id="3" name="Rectangle"/>
+    <p:cNvSpPr/>
+    <p:nvPr/>
+  </p:nvSpPr>
+  <p:spPr>
+    <a:xfrm>
+      <a:off x="1000000" y="1000000"/>
+      <a:ext cx="3000000" cy="2000000"/>
+    </a:xfrm>
+    <a:prstGeom prst="rect">
+      <a:avLst/>
+    </a:prstGeom>
+    <a:solidFill>
+      <a:srgbClr val="FF0000"/>
+    </a:solidFill>
+    <a:ln w="25400">
+      <a:solidFill>
+        <a:srgbClr val="000000"/>
+      </a:solidFill>
+    </a:ln>
+  </p:spPr>
+</p:sp>
+
+<!-- Rounded Rectangle -->
+<p:sp>
+  <p:spPr>
+    <a:prstGeom prst="roundRect">
+      <a:avLst/>
+    </a:prstGeom>
+  </p:spPr>
+</p:sp>
+
+<!-- Circle/Ellipse -->
+<p:sp>
+  <p:spPr>
+    <a:prstGeom prst="ellipse">
+      <a:avLst/>
+    </a:prstGeom>
+  </p:spPr>
+</p:sp>
+```
+
+### Images
+```xml
+<p:pic>
+  <p:nvPicPr>
+    <p:cNvPr id="4" name="Picture">
+      <a:hlinkClick r:id="" action="ppaction://media"/>
+    </p:cNvPr>
+    <p:cNvPicPr>
+      <a:picLocks noChangeAspect="1"/>
+    </p:cNvPicPr>
+    <p:nvPr/>
+  </p:nvPicPr>
+  <p:blipFill>
+    <a:blip r:embed="rId2"/>
+    <a:stretch>
+      <a:fillRect/>
+    </a:stretch>
+  </p:blipFill>
+  <p:spPr>
+    <a:xfrm>
+      <a:off x="1000000" y="1000000"/>
+      <a:ext cx="3000000" cy="2000000"/>
+    </a:xfrm>
+    <a:prstGeom prst="rect">
+      <a:avLst/>
+    </a:prstGeom>
+  </p:spPr>
+</p:pic>
+```
+
+### Tables
+```xml
+<p:graphicFrame>
+  <p:nvGraphicFramePr>
+    <p:cNvPr id="5" name="Table"/>
+    <p:cNvGraphicFramePr>
+      <a:graphicFrameLocks noGrp="1"/>
+    </p:cNvGraphicFramePr>
+    <p:nvPr/>
+  </p:nvGraphicFramePr>
+  <p:xfrm>
+    <a:off x="1000000" y="1000000"/>
+    <a:ext cx="6000000" cy="2000000"/>
+  </p:xfrm>
+  <a:graphic>
+    <a:graphicData uri="http://schemas.openxmlformats.org/drawingml/2006/table">
+      <a:tbl>
+        <a:tblGrid>
+          <a:gridCol w="3000000"/>
+          <a:gridCol w="3000000"/>
+        </a:tblGrid>
+        <a:tr h="500000">
+          <a:tc>
+            <a:txBody>
+              <a:bodyPr/>
+              <a:lstStyle/>
+              <a:p>
+                <a:r>
+                  <a:t>Cell 1</a:t>
+                </a:r>
+              </a:p>
+            </a:txBody>
+          </a:tc>
+          <a:tc>
+            <a:txBody>
+              <a:bodyPr/>
+              <a:lstStyle/>
+              <a:p>
+                <a:r>
+                  <a:t>Cell 2</a:t>
+                </a:r>
+              </a:p>
+            </a:txBody>
+          </a:tc>
+        </a:tr>
+      </a:tbl>
+    </a:graphicData>
+  </a:graphic>
+</p:graphicFrame>
+```
+
+### Slide Layouts
+
+```xml
+<!-- Title Slide Layout -->
+<p:sp>
+  <p:nvSpPr>
+    <p:nvPr>
+      <p:ph type="ctrTitle"/>
+    </p:nvPr>
+  </p:nvSpPr>
+  <!-- Title content -->
+</p:sp>
+
+<p:sp>
+  <p:nvSpPr>
+    <p:nvPr>
+      <p:ph type="subTitle" idx="1"/>
+    </p:nvPr>
+  </p:nvSpPr>
+  <!-- Subtitle content -->
+</p:sp>
+
+<!-- Content Slide Layout -->
+<p:sp>
+  <p:nvSpPr>
+    <p:nvPr>
+      <p:ph type="title"/>
+    </p:nvPr>
+  </p:nvSpPr>
+  <!-- Slide title -->
+</p:sp>
+
+<p:sp>
+  <p:nvSpPr>
+    <p:nvPr>
+      <p:ph type="body" idx="1"/>
+    </p:nvPr>
+  </p:nvSpPr>
+  <!-- Content body -->
+</p:sp>
+```
+
+## File Updates
+
+When adding content, update these files:
+
+**`ppt/_rels/presentation.xml.rels`:**
+```xml
+<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slide" Target="slides/slide1.xml"/>
+<Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideMaster" Target="slideMasters/slideMaster1.xml"/>
+```
+
+**`ppt/slides/_rels/slide1.xml.rels`:**
+```xml
+<Relationship Id="rId1" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/slideLayout" Target="../slideLayouts/slideLayout1.xml"/>
+<Relationship Id="rId2" Type="http://schemas.openxmlformats.org/officeDocument/2006/relationships/image" Target="../media/image1.png"/>
+```
+
+**`[Content_Types].xml`:**
+```xml
+<Default Extension="png" ContentType="image/png"/>
+<Default Extension="jpg" ContentType="image/jpeg"/>
+<Override PartName="/ppt/slides/slide1.xml" ContentType="application/vnd.openxmlformats-officedocument.presentationml.slide+xml"/>
+```
+
+**`ppt/presentation.xml`:**
+```xml
+<p:sldIdLst>
+  <p:sldId id="256" r:id="rId1"/>
+  <p:sldId id="257" r:id="rId2"/>
+</p:sldIdLst>
+```
+
+**`docProps/app.xml`:** Update slide count and statistics
+```xml
+<Slides>2</Slides>
+<Paragraphs>10</Paragraphs>
+<Words>50</Words>
+```
+
+## Slide Operations
+
+### Adding a New Slide
+When adding a slide to the end of the presentation:
+
+1. **Create the slide file** (`ppt/slides/slideN.xml`)
+2. **Update `[Content_Types].xml`**: Add Override for the new slide
+3. **Update `ppt/_rels/presentation.xml.rels`**: Add relationship for the new slide
+4. **Update `ppt/presentation.xml`**: Add slide ID to `<p:sldIdLst>`
+5. **Create slide relationships** (`ppt/slides/_rels/slideN.xml.rels`) if needed
+6. **Update `docProps/app.xml`**: Increment slide count and update statistics (if present)
+
+### Duplicating a Slide
+1. Copy the source slide XML file with a new name
+2. Update all IDs in the new slide to be unique
+3. Follow the "Adding a New Slide" steps above
+4. **CRITICAL**: Remove or update any notes slide references in `_rels` files
+5. Remove references to unused media files
+
+### Reordering Slides
+1. **Update `ppt/presentation.xml`**: Reorder `<p:sldId>` elements in `<p:sldIdLst>`
+2. The order of `<p:sldId>` elements determines slide order
+3. Keep slide IDs and relationship IDs unchanged
+
+Example:
+```xml
+<!-- Original order -->
+<p:sldIdLst>
+  <p:sldId id="256" r:id="rId2"/>
+  <p:sldId id="257" r:id="rId3"/>
+  <p:sldId id="258" r:id="rId4"/>
+</p:sldIdLst>
+
+<!-- After moving slide 3 to position 2 -->
+<p:sldIdLst>
+  <p:sldId id="256" r:id="rId2"/>
+  <p:sldId id="258" r:id="rId4"/>
+  <p:sldId id="257" r:id="rId3"/>
+</p:sldIdLst>
+```
+
+### Deleting a Slide
+1. **Remove from `ppt/presentation.xml`**: Delete the `<p:sldId>` entry
+2. **Remove from `ppt/_rels/presentation.xml.rels`**: Delete the relationship
+3. **Remove from `[Content_Types].xml`**: Delete the Override entry
+4. **Delete files**: Remove `ppt/slides/slideN.xml` and `ppt/slides/_rels/slideN.xml.rels`
+5. **Update `docProps/app.xml`**: Decrement slide count and update statistics
+6. **Clean up unused media**: Remove orphaned images from `ppt/media/`
+
+Note: Don't renumber remaining slides - keep their original IDs and filenames.
+
+
+## Common Errors to Avoid
+
+- **Encodings**: Escape unicode characters in ASCII content: `"` becomes `&#8220;`
+- **Images**: Add to `ppt/media/` and update relationship files
+- **Lists**: Omit bullets from list headers
+- **IDs**: Use valid hexadecimal values for UUIDs
+- **Themes**: Check all themes in `theme` directory for colors
+
+## Validation Checklist for Template-Based Presentations
+
+### Before Packing, Always:
+- **Clean unused resources**: Remove unreferenced media, fonts, and notes directories
+- **Fix Content_Types.xml**: Declare ALL slides, layouts, and themes present in the package
+- **Fix relationship IDs**: 
+   - Remove font embed references if not using embedded fonts
+- **Remove broken references**: Check all `_rels` files for references to deleted resources
+
+### Common Template Duplication Pitfalls:
+- Multiple slides referencing the same notes slide after duplication
+- Image/media references from template slides that no longer exist
+- Font embedding references when fonts aren't included
+- Missing slideLayout declarations for layouts 12-25
+- docProps directory may not unpack - this is optional