@ngockhoale/ukit 1.6.8 → 2.0.2

package/templates/.claude/skills/pdf-processing-pro/workflows-and-troubleshooting.md

@@ -0,0 +1,80 @@
+# PDF Processing Pro — Common Workflows and Troubleshooting
+
+## Common workflows
+
+### Workflow 1: Process form submissions
+
+```bash
+# 1. Analyze form structure
+python scripts/analyze_form.py template.pdf --output schema.json
+
+# 2. Validate submission data
+python scripts/validate_form.py submission.json schema.json
+
+# 3. Fill form
+python scripts/fill_form.py template.pdf submission.json completed.pdf
+
+# 4. Validate output
+python scripts/validate_pdf.py completed.pdf
+```
+
+### Workflow 2: Extract data from reports
+
+```bash
+# 1. Extract tables
+python scripts/extract_tables.py monthly_report.pdf --output data.csv
+
+# 2. Extract text for analysis
+python scripts/extract_text.py monthly_report.pdf --output report.txt
+```
+
+### Workflow 3: Batch processing
+
+```python
+import glob
+from pathlib import Path
+import subprocess
+
+# Process all PDFs in directory
+for pdf_file in glob.glob("invoices/*.pdf"):
+    output_file = Path("processed") / Path(pdf_file).name
+
+    result = subprocess.run([
+        "python", "scripts/extract_text.py",
+        pdf_file,
+        "--output", str(output_file)
+    ], capture_output=True)
+
+    if result.returncode == 0:
+        print(f"✓ Processed: {pdf_file}")
+    else:
+        print(f"✗ Failed: {pdf_file} - {result.stderr}")
+```
+
+## Troubleshooting
+
+### Common issues
+
+**"Module not found" errors**:
+```bash
+pip install -r requirements.txt
+```
+
+**Tesseract not found**:
+```bash
+# Install tesseract system package (see Dependencies)
+```
+
+**Memory errors with large PDFs**:
+```python
+# Process page by page instead of loading entire PDF
+with pdfplumber.open("large.pdf") as pdf:
+    for page in pdf.pages:
+        text = page.extract_text()
+        # Process page immediately
+```
+
+**Permission errors**:
+```bash
+chmod +x scripts/*.py
+```

package/templates/.claude/skills/pptx/SKILL.md

@@ -72,74 +72,7 @@ When creating a new PowerPoint presentation from scratch, use the **html2pptx**
 - **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
+For 18 example palettes to spark creativity and a menu of visual treatment options (geometric patterns, border/frame treatments, typography, chart styling, layout, backgrounds), read [`design-references.md`](design-references.md).
 
 ### Layout Tips
 **When creating slides with charts or tables:**
@@ -188,22 +121,11 @@ When you need to create a presentation that follows an existing template's desig
    * 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
+   * See [`utilities.md`](utilities.md) for thumbnail-grid options
 
 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 ...]
-     ```
+   * Create and save a template inventory file at `template-inventory.md`. Format example: [`template-replacement-reference.md`](template-replacement-reference.md#template-inventory--mapping-examples).
    * **Using the thumbnail grid**: Reference the visual thumbnails to identify:
      - Layout patterns (title slides, content layouts, section dividers)
      - Image placeholder locations and counts
@@ -227,20 +149,7 @@ When you need to create a presentation that follows an existing template's desig
    * 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)
-      ]
-      ```
+   * Save `outline.md` with content AND template mapping that leverages available designs. Example mapping: [`template-replacement-reference.md`](template-replacement-reference.md#template-inventory--mapping-examples).
 
 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:
@@ -257,212 +166,31 @@ When you need to create a presentation that follows an existing template's desig
      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
+   * Full JSON structure and field reference: [`template-replacement-reference.md`](template-replacement-reference.md#text-inventoryjson-structure-from-inventorypy)
 
 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
+   - **VALIDATION**: The replace.py script will validate that all shapes in your replacement JSON exist in the inventory before applying anything; all errors are shown at once
+   - **AUTOMATIC CLEARING**: ALL text shapes from the inventory will be cleared unless you provide a "paragraphs" field for them (not "replacement_paragraphs")
+   - Paragraphs with bullets will be automatically left aligned. Don't set the `alignment` property when `"bullet": true`
    - **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
+   - Headers/titles should typically have `"bold": true`; list items need `"bullet": true, "level": 0`
+   - **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
+   - Example paragraphs field, cleared-shape example, and common formatting patterns: [`template-replacement-reference.md`](template-replacement-reference.md#replacement-json-examples)
 
 7. **Apply replacements using the `replace.py` script**
    ```bash
    python scripts/replace.py working.pptx replacement-text.json output.pptx
    ```
+   Validates all shapes/slides referenced exist, clears every inventoried shape, then applies new text with formatting only to shapes with "paragraphs" defined. See [`template-replacement-reference.md`](template-replacement-reference.md#replacepy-behavior-and-validation-errors) for exact validation-error output.
 
-   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
+## Utility commands
 
-   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
-```
+Thumbnail-grid generation (`scripts/thumbnail.py`) and slide-to-image conversion (`soffice`/`pdftoppm`) — used for visual analysis and template review — are documented in [`utilities.md`](utilities.md).
 
 ## Code Style Guidelines
 **IMPORTANT**: When generating code for PPTX operations:

package/templates/.claude/skills/pptx/design-references.md

@@ -0,0 +1,81 @@
+# PPTX Design References
+
+Reference material for the html2pptx workflow's design step. Read this when picking a color palette or visual treatment for a from-scratch presentation.
+
+## 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

package/templates/.claude/skills/pptx/template-replacement-reference.md

@@ -0,0 +1,150 @@
+# Template Text-Replacement Reference
+
+Full JSON schemas and examples for steps 5-7 of the "using a template" workflow (`inventory.py` → replacement JSON → `replace.py`). Read this when you need the exact field shapes, not just the procedure.
+
+## Template inventory + mapping examples
+
+```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 ...]
+```
+
+```
+# 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)
+]
+```
+
+## `text-inventory.json` structure (from `inventory.py`)
+
+```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
+
+## Replacement JSON examples
+
+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
+
+## `replace.py` behavior and validation errors
+
+The script:
+- First extracts the inventory of ALL text shapes using functions from inventory.py
+- Validates that all shapes in the replacement JSON exist in the inventory
+- Clears text from ALL shapes identified in the inventory
+- Applies new text only to shapes with "paragraphs" defined in the replacement JSON
+- Preserves formatting by applying paragraph properties from the JSON
+- Handles bullets, alignment, font properties, and colors automatically
+- Saves 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")
+```