@heylemon/lemonade 0.1.7 → 0.1.9

package/dist/build-info.json

@@ -1,5 +1,5 @@
 {
-  "version": "0.1.7",
-  "commit": "d184adc6a2e41a87e3e128818c8fb4691ed284fa",
-  "builtAt": "2026-02-21T17:43:41.892Z"
+  "version": "0.1.9",
+  "commit": "148a3ecd94824b7bed57702ff16e416442b7d831",
+  "builtAt": "2026-02-21T19:41:57.574Z"
 }

package/dist/canvas-host/a2ui/.bundle.hash

@@ -1 +1 @@
-3c0c2fd2a7ea5c555231422230609ed18d2ba0fc3505ef930a0a92cb6a91760e
+b3ce500e7c71ed0a3415b4d2d8e472926cb0135cdb8a2f66ab05abb127c334ac

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heylemon/lemonade",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "AI gateway CLI for Lemon - local AI assistant with integrations",
   "publishConfig": {
     "access": "restricted"

package/skills/docx/SKILL.md

@@ -7,14 +7,30 @@ description: "Create professional, polished documents — reports, memos, propos
 
 Create polished, production-ready documents using docx-js, the clean standards-compliant Node.js library for producing .docx files. This skill writes bespoke code for each request rather than using JSON templates — you have full control over the document API.
 
+## ⚠️ MANDATORY: Post-Processing After Every Build
+
+docx-js has TWO bugs that cause documents to look wrong in Apple Pages and Google Docs. **After generating ANY document, you MUST run BOTH scripts:**
+
+```bash
+# Step 1: Fix table column grids (tables break in Pages without this)
+python scripts/fix_tables.py output.docx
+
+# Step 2: Fix heading styles (headings show wrong colors/fonts in Pages without this)
+python scripts/fix_styles.py output.docx
+```
+
+These are not optional. Without fix_tables.py, tables render as 1-character-wide columns in Pages. Without fix_styles.py, headings appear in default blue instead of your custom colors. Run both immediately after `node create-doc.js`, before delivering the file. The scripts are located in the same skill folder as this SKILL.md.
+
 ## Quick Reference
 
 | Task | Approach | Tool |
 |------|----------|------|
-| **Create new document** | Write docx-js code using Document, Packer, Paragraph, TextRun, Table | Node.js + docx-js |
+| **Create new document** | Write docx-js code, then run both fix scripts | Node.js + docx-js |
 | **Read/analyze existing** | Unzip → read document.xml or use pandoc for content extraction | unzip or pandoc |
 | **Edit existing file** | Unzip → modify XML → repack into .docx | unzip + JSZip |
 | **Validate output** | Check XML, fonts, structure, paragraphs | `python scripts/validate.py` |
+| **Fix tables (MANDATORY)** | Patch tblGrid for cross-platform | `python scripts/fix_tables.py output.docx` |
+| **Fix styles (MANDATORY)** | Patch heading styles for cross-platform | `python scripts/fix_styles.py output.docx` |
 | **Visual QA** | Convert to PDF then to images | soffice + pdftoppm |
 
 ---
@@ -102,33 +118,37 @@ const COLORS = {
 
 ### Creating Headings with Styles
 
-Override built-in heading styles to ensure they appear in TOC. Use `outlineLevel` to control Table of Contents depth:
+**CRITICAL: Use `children` with TextRun, NOT the `run` property.** The `run` property puts formatting in `pPr/rPr` (paragraph default run properties) but the actual `<w:r>` gets no `<w:rPr>`. Word inherits from `pPr/rPr` just fine, but Apple Pages reads from `styles.xml` instead and ignores inline paragraph-level overrides. By using `children` with an explicit `TextRun`, the formatting goes directly on the run itself, which Pages always respects.
 
 ```javascript
+// ✅ CORRECT — formatting on the TextRun (works in Pages)
 new Paragraph({
-  text: "Section Title",
   heading: HeadingLevel.HEADING_1,
-  outlineLevel: 0,  // Appears in TOC
-  style: "Heading1",
-  run: {
-    bold: true,
-    size: TYPOGRAPHY.h1,
-    color: COLORS.primary,
-    font: "Arial"
-  },
-  spacing: { before: 480, after: 160 }  // 12pt before, 4pt after
+  spacing: { before: 480, after: 160 },
+  children: [
+    new TextRun({
+      text: "Section Title",
+      bold: true,
+      size: TYPOGRAPHY.h1,
+      color: COLORS.primary,
+      font: "Arial"
+    })
+  ]
 });
 
+// ❌ WRONG — formatting on `run` property (breaks in Pages)
 new Paragraph({
   text: "Subsection",
-  heading: HeadingLevel.HEADING_2,
-  outlineLevel: 1,
-  style: "Heading2",
-  run: { size: TYPOGRAPHY.h2, color: COLORS.primary },
-  spacing: { before: 360, after: 120 }
+  heading: HeadingLevel.HEADING_1,
+  style: "Heading1",
+  run: { bold: true, size: TYPOGRAPHY.h1, color: COLORS.primary, font: "Arial" },
+  spacing: { before: 480, after: 160 }
 });
 ```
 
+Also note: use `italics: true` (with 's'), not `italic: true`. The latter silently does nothing in docx-js.
+```
+
 ### Lists: Never Use Unicode Bullets
 
 CRITICAL: Never manually insert bullet characters like •, ◦, ▪. Use the list APIs:
@@ -324,7 +344,8 @@ Or use a more sophisticated approach with field codes (requires XML manipulation
 - Set both table width AND individual cell widths in DXA
 - Use `ShadingType.CLEAR` for cell backgrounds
 - Use `HeadingLevel.HEADING_1`, etc., with `outlineLevel` for TOC
-- Override heading styles with explicit `style: "Heading1"` properties
+- Use `children` with TextRun for headings, NOT the `run` property (Pages ignores `run`)
+- Use `italics: true` (with 's'), not `italic: true`
 - Set `spacing.before` and `spacing.after` explicitly on headings
 
 **DON'T:**
@@ -336,6 +357,8 @@ Or use a more sophisticated approach with field codes (requires XML manipulation
 - Forget cell width specifications (columns collapse)
 - Use `ShadingType.SOLID` (use CLEAR)
 - Assume A4 page size (always set explicitly to US Letter)
+- Use `run` property on headings (use `children` with TextRun instead — Pages ignores `run`)
+- Use `italic: true` without the 's' (use `italics: true`)
 - Mix font styles — stick to 2 fonts (heading + body)
 
 ---
@@ -366,7 +389,7 @@ Even if the code is perfect, content matters. Follow these principles:
 ### Callouts
 - Use callouts for key decisions, critical warnings, or bottom-line takeaways.
 - Maximum one per major section — if everything is highlighted, nothing stands out.
-- Format as a highlighted paragraph with accent left border and light background.
+- **Always use paragraph borders** (left border + shading), never narrow table cells as accent stripes. Narrow table cells break in Apple Pages. See "Cross-Platform Compatibility" section.
 
 ---
 
@@ -428,7 +451,39 @@ The validator checks:
 - Empty headings
 - Manual bullet characters (should use List APIs)
 
-### 2. Visual Check (PDF Conversion)
+### 2. Fix Tables for Cross-Platform (MANDATORY if document contains tables)
+
+docx-js has a bug where table grid definitions (`tblGrid`) don't match cell widths. This causes tables to render as 1-character-wide columns in Apple Pages, Google Docs, and LibreOffice. Run this fix on every document that contains tables:
+
+```bash
+python scripts/fix_tables.py report.docx
+```
+
+This script:
+- Reads each table's first-row cell widths (`tcW`)
+- Patches the `tblGrid` column definitions to match
+- Adds `tblLayout type="fixed"` for consistent rendering
+- Overwrites the file in place (or pass a second arg for a new file)
+
+**Always run this after generating any document with tables.** Without it, tables will look correct in Word but break in Pages and Google Docs.
+
+### 3. Fix Heading Styles for Cross-Platform (MANDATORY)
+
+docx-js generates default blue heading styles in `styles.xml` regardless of your inline formatting. Word uses inline run properties, but Pages reads `styles.xml` first, causing headings to appear in the wrong color/font/size.
+
+```bash
+python scripts/fix_styles.py report.docx
+```
+
+This script:
+- Reads each heading's actual inline formatting (color, font, size, bold) from the document
+- Patches `styles.xml` heading style definitions to match
+- Adds paragraph spacing to style definitions
+- Overwrites the file in place (or pass a second arg for a new file)
+
+**Always run this after generating any document with headings.** Without it, headings will look correct in Word but show default blue colors in Pages.
+
+### 4. Visual Check (PDF Conversion)
 
 ```bash
 # Convert to PDF
@@ -440,13 +495,15 @@ pdftoppm -jpeg -r 150 report.pdf page
 # View: page-1.jpg, page-2.jpg, etc.
 ```
 
-### 3. Fix & Re-validate
+### 5. Fix & Re-validate
 
 If the validator reports issues or the PDF looks off:
 1. Fix the docx-js code
 2. Re-run to regenerate .docx
-3. Re-validate with `validate.py`
-4. Re-convert to PDF if visual issues
+3. Run `fix_tables.py` again (step 2)
+4. Run `fix_styles.py` again (step 3)
+5. Re-validate with `validate.py`
+6. Re-convert to PDF if visual issues
 
 Iterate until both validation passes and visual output looks polished.
 
@@ -591,6 +648,85 @@ sudo apt-get install libreoffice poppler-utils  # soffice, pdftoppm
 
 ---
 
+## Cross-Platform Compatibility (Pages, Google Docs, LibreOffice)
+
+Documents must look correct in Apple Pages, Google Docs, and LibreOffice — not just Microsoft Word. These apps interpret .docx features differently and many advanced Word features break silently.
+
+### Features That Break in Pages
+
+**Narrow decorative table cells (< 200 DXA):**
+Pages collapses very narrow cells, causing adjacent text to render vertically (one character per line). This is the most common Pages rendering bug.
+
+- ❌ **Never:** Use a 120 DXA cell as a colored accent stripe next to a content cell
+- ❌ **Never:** Use single-cell tables as horizontal rule/divider decorations
+- ✅ **Instead:** Use paragraph borders for accent effects:
+
+```javascript
+// Callout box — cross-platform safe
+// Uses left border on the paragraph itself, not a narrow table cell
+new Paragraph({
+    spacing: { before: 200, after: 200 },
+    indent: { left: 360 },
+    border: {
+        left: { style: BorderStyle.SINGLE, size: 12, color: "2E86AB", space: 10 }
+    },
+    shading: { fill: "E8F4F8", type: ShadingType.CLEAR },
+    children: [
+        new TextRun({ text: "Decision needed: ", bold: true, size: 22, color: "1B3A5C" }),
+        new TextRun({ text: "Approve the $400K budget by February 28.", size: 22, color: "2C3E50" })
+    ]
+})
+```
+
+**Decorative tables as horizontal lines:**
+```javascript
+// ❌ BREAKS in Pages — tiny table used as accent line
+new Table({
+    width: { size: 2880, type: WidthType.DXA },
+    rows: [new TableRow({ children: [new TableCell({
+        width: { size: 2880, type: WidthType.DXA },
+        shading: { fill: "2E86AB", type: ShadingType.CLEAR },
+        children: [new Paragraph({ children: [new TextRun({ text: " ", size: 4 })] })]
+    })] })]
+})
+
+// ✅ WORKS everywhere — paragraph bottom border as accent line
+new Paragraph({
+    spacing: { after: 200 },
+    border: {
+        bottom: { style: BorderStyle.SINGLE, size: 6, color: "2E86AB", space: 8 }
+    },
+    children: []  // Empty paragraph with just a bottom border
+})
+```
+
+### Other Cross-Platform Pitfalls
+
+- **Text boxes / floating elements**: Pages and Google Docs don't support them — content disappears or overlaps
+- **Custom XML / content controls**: Ignored by non-Word apps
+- **Complex nested tables**: Keep nesting to 1 level max; Pages handles deeply nested tables poorly
+- **Tab stops for alignment**: Use tables instead — tab rendering varies between apps
+- **Form fields**: Only work in Word
+- **Watermarks**: Render differently or not at all in Pages
+- **SmartArt / ActiveX**: Not supported outside Word
+
+### Safe Cross-Platform Features
+
+These features render consistently across all apps:
+- Simple tables with explicit cell widths (minimum 400 DXA per cell)
+- Paragraph borders (left, bottom, top — great for callouts and dividers)
+- Paragraph shading/highlighting
+- Bold, italic, underline, font color, font size
+- Heading styles (Heading 1-6)
+- Bullet and numbered lists
+- Page breaks
+- Headers and footers with page numbers
+- Images (inline, not floating)
+
+### The 400 DXA Rule
+
+**Never create a table cell narrower than 400 DXA (roughly 0.28 inches).** Cells below this width are rendered unpredictably in Pages and LibreOffice. If you need a thin accent stripe, use a paragraph left border instead.
+
 ## Troubleshooting
 
 **Document won't open in Word:** XML malformed. Check for unclosed tags, invalid characters. Run `validate.py` to check structure.
@@ -603,6 +739,8 @@ sudo apt-get install libreoffice poppler-utils  # soffice, pdftoppm
 
 **TOC not generating:** docx-js doesn't support field codes natively. Use placeholder text or manually update in Word after opening.
 
+**Text renders vertically in Pages:** A table cell is too narrow (< 200 DXA). Replace narrow decorative cells with paragraph borders. See "Cross-Platform Compatibility" section above.
+
 ---
 
 ## Example: Simple Report

package/skills/docx/scripts/fix_styles.py

@@ -0,0 +1,394 @@
+#!/usr/bin/env python3
+"""
+fix_styles.py — Patch styles.xml in a .docx for Apple Pages compatibility.
+
+docx-js generates styles.xml with THREE problems that break Pages rendering:
+
+1. Empty docDefaults — <w:rPrDefault/> and <w:pPrDefault/> with no content.
+   Pages needs proper defaults (font, size, language, paragraph spacing) to
+   correctly interpret inline paragraph properties like w:jc (alignment).
+
+2. Missing Normal style — No default paragraph style is defined. Pages needs
+   a Normal style with w:default="1" as the base for all paragraph rendering.
+   Without it, Pages ignores inline paragraph formatting like center alignment.
+
+3. Wrong heading colors — Heading styles have default blue (#2E74B5) colors
+   regardless of what colors you use in the document. Pages reads styles.xml
+   instead of inline run properties.
+
+This script fixes all three issues by:
+- Adding proper docDefaults with font, size, language, and paragraph spacing
+- Adding a Normal style with w:default="1" if it doesn't exist
+- Reading actual heading formatting from the document and patching styles.xml
+
+Usage:
+    python fix_styles.py input.docx [output.docx]
+
+If output is omitted, the file is modified in place.
+"""
+
+import os
+import shutil
+import sys
+import tempfile
+import zipfile
+from xml.etree import ElementTree as ET
+
+NS = {
+    "w": "http://schemas.openxmlformats.org/wordprocessingml/2006/main",
+    "mc": "http://schemas.openxmlformats.org/markup-compatibility/2006",
+    "r": "http://schemas.openxmlformats.org/officeDocument/2006/relationships",
+}
+
+# Register all namespaces to preserve them on write
+for prefix, uri in NS.items():
+    ET.register_namespace(prefix, uri)
+
+# Register additional namespaces commonly in docx
+EXTRA_NS = {
+    "wpc": "http://schemas.microsoft.com/office/word/2010/wordprocessingCanvas",
+    "o": "urn:schemas-microsoft-com:office:office",
+    "m": "http://schemas.openxmlformats.org/officeDocument/2006/math",
+    "v": "urn:schemas-microsoft-com:vml",
+    "wp14": "http://schemas.microsoft.com/office/word/2010/wordprocessingDrawing",
+    "wp": "http://schemas.openxmlformats.org/drawingml/2006/wordprocessingDrawing",
+    "w10": "urn:schemas-microsoft-com:office:word",
+    "w14": "http://schemas.microsoft.com/office/word/2010/wordml",
+    "w15": "http://schemas.microsoft.com/office/word/2012/wordml",
+    "wpg": "http://schemas.microsoft.com/office/word/2010/wordprocessingGroup",
+    "wpi": "http://schemas.microsoft.com/office/word/2010/wordprocessingInk",
+    "wne": "http://schemas.microsoft.com/office/word/2006/wordml",
+    "wps": "http://schemas.microsoft.com/office/word/2010/wordprocessingShape",
+}
+for prefix, uri in EXTRA_NS.items():
+    ET.register_namespace(prefix, uri)
+
+W = NS["w"]
+WNS = f"{{{W}}}"
+
+
+def fix_doc_defaults(root):
+    """
+    Ensure docDefaults has proper rPrDefault and pPrDefault.
+    Pages needs these to correctly resolve inline paragraph properties.
+    """
+    doc_defaults = root.find(f"{WNS}docDefaults")
+    if doc_defaults is None:
+        # Insert docDefaults as first child
+        doc_defaults = ET.SubElement(root, f"{WNS}docDefaults")
+        root.insert(0, doc_defaults)
+
+    fixed = False
+
+    # Fix rPrDefault
+    rpr_default = doc_defaults.find(f"{WNS}rPrDefault")
+    if rpr_default is None:
+        rpr_default = ET.SubElement(doc_defaults, f"{WNS}rPrDefault")
+
+    rpr = rpr_default.find(f"{WNS}rPr")
+    if rpr is None or len(rpr) == 0:
+        # Empty rPrDefault — add proper defaults
+        if rpr is not None:
+            doc_defaults.remove(rpr_default)
+            rpr_default = ET.SubElement(doc_defaults, f"{WNS}rPrDefault")
+
+        rpr = ET.SubElement(rpr_default, f"{WNS}rPr")
+
+        # Default fonts
+        fonts = ET.SubElement(rpr, f"{WNS}rFonts")
+        fonts.set(f"{WNS}asciiTheme", "minorHAnsi")
+        fonts.set(f"{WNS}eastAsiaTheme", "minorEastAsia")
+        fonts.set(f"{WNS}hAnsiTheme", "minorHAnsi")
+        fonts.set(f"{WNS}cstheme", "minorBidi")
+
+        # Default size (11pt = 22 half-points)
+        sz = ET.SubElement(rpr, f"{WNS}sz")
+        sz.set(f"{WNS}val", "22")
+        sz_cs = ET.SubElement(rpr, f"{WNS}szCs")
+        sz_cs.set(f"{WNS}val", "22")
+
+        # Language
+        lang = ET.SubElement(rpr, f"{WNS}lang")
+        lang.set(f"{WNS}val", "en-US")
+        lang.set(f"{WNS}eastAsia", "en-US")
+        lang.set(f"{WNS}bidi", "ar-SA")
+
+        fixed = True
+
+    # Fix pPrDefault
+    ppr_default = doc_defaults.find(f"{WNS}pPrDefault")
+    if ppr_default is None:
+        ppr_default = ET.SubElement(doc_defaults, f"{WNS}pPrDefault")
+
+    ppr = ppr_default.find(f"{WNS}pPr")
+    if ppr is None or len(ppr) == 0:
+        # Empty pPrDefault — add proper defaults
+        if ppr is not None:
+            doc_defaults.remove(ppr_default)
+            ppr_default = ET.SubElement(doc_defaults, f"{WNS}pPrDefault")
+
+        ppr = ET.SubElement(ppr_default, f"{WNS}pPr")
+
+        # Default paragraph spacing (after=200, line=276, lineRule=auto)
+        spacing = ET.SubElement(ppr, f"{WNS}spacing")
+        spacing.set(f"{WNS}after", "200")
+        spacing.set(f"{WNS}line", "276")
+        spacing.set(f"{WNS}lineRule", "auto")
+
+        fixed = True
+
+    return fixed
+
+
+def fix_normal_style(root):
+    """
+    Ensure a proper Normal style exists with w:default="1".
+    Pages needs this as the base paragraph style to correctly resolve
+    inline formatting like center alignment and spacing.
+    """
+    # Check if Normal style already exists
+    for style_el in root.findall(f"{WNS}style"):
+        style_id = style_el.get(f"{WNS}styleId", "")
+        if style_id == "Normal":
+            # Ensure it has w:default="1"
+            if style_el.get(f"{WNS}default") != "1":
+                style_el.set(f"{WNS}default", "1")
+                return True
+            return False
+
+    # Normal style doesn't exist — create it
+    normal = ET.SubElement(root, f"{WNS}style")
+    normal.set(f"{WNS}type", "paragraph")
+    normal.set(f"{WNS}default", "1")
+    normal.set(f"{WNS}styleId", "Normal")
+
+    name = ET.SubElement(normal, f"{WNS}name")
+    name.set(f"{WNS}val", "Normal")
+
+    ET.SubElement(normal, f"{WNS}qFormat")
+
+    # Move it to be the first style (after docDefaults and latentStyles)
+    root.remove(normal)
+    insert_pos = 0
+    for i, child in enumerate(root):
+        tag = child.tag.split("}")[-1] if "}" in child.tag else child.tag
+        if tag in ("docDefaults", "latentStyles"):
+            insert_pos = i + 1
+    root.insert(insert_pos, normal)
+
+    return True
+
+
+def extract_heading_styles_from_document(doc_tree):
+    """
+    Scan document.xml for heading paragraphs and extract their inline formatting.
+    Returns dict: { 'Heading1': { 'color': '6B2D2D', 'sz': '36', ... }, ... }
+    """
+    root = doc_tree.getroot()
+    body = root.find(f".//{WNS}body")
+    if body is None:
+        return {}
+
+    heading_styles = {}
+
+    for para in body.findall(f".//{WNS}p"):
+        p_pr = para.find(f"{WNS}pPr")
+        if p_pr is None:
+            continue
+
+        p_style = p_pr.find(f"{WNS}pStyle")
+        if p_style is None:
+            continue
+        style_id = p_style.get(f"{WNS}val", "")
+        if not style_id.startswith("Heading"):
+            continue
+        if style_id in heading_styles:
+            continue
+
+        fmt = {}
+        # Try inline run properties first (w:r/w:rPr)
+        run = para.find(f"{WNS}r")
+        if run is not None:
+            r_pr = run.find(f"{WNS}rPr")
+            if r_pr is not None:
+                _extract_rpr(r_pr, fmt)
+
+        # Fall back to paragraph default rPr (pPr/rPr)
+        if not fmt:
+            p_rpr = p_pr.find(f"{WNS}rPr")
+            if p_rpr is not None:
+                _extract_rpr(p_rpr, fmt)
+
+        # Extract paragraph spacing
+        spacing = p_pr.find(f"{WNS}spacing")
+        if spacing is not None:
+            before = spacing.get(f"{WNS}before")
+            after = spacing.get(f"{WNS}after")
+            if before:
+                fmt["spacing_before"] = before
+            if after:
+                fmt["spacing_after"] = after
+
+        if fmt:
+            heading_styles[style_id] = fmt
+
+    return heading_styles
+
+
+def _extract_rpr(r_pr, fmt):
+    """Extract formatting properties from a w:rPr element."""
+    color = r_pr.find(f"{WNS}color")
+    if color is not None:
+        fmt["color"] = color.get(f"{WNS}val", "")
+
+    sz = r_pr.find(f"{WNS}sz")
+    if sz is not None:
+        fmt["sz"] = sz.get(f"{WNS}val", "")
+
+    fonts = r_pr.find(f"{WNS}rFonts")
+    if fonts is not None:
+        fmt["font"] = fonts.get(f"{WNS}ascii", "")
+
+    bold = r_pr.find(f"{WNS}b")
+    if bold is not None:
+        fmt["bold"] = True
+
+    italics = r_pr.find(f"{WNS}i")
+    if italics is not None:
+        fmt["italics"] = True
+
+
+def patch_heading_styles(root, heading_styles):
+    """Update heading style definitions with actual formatting from the document."""
+    patched = 0
+
+    for style_el in root.findall(f"{WNS}style"):
+        style_id = style_el.get(f"{WNS}styleId", "")
+        if style_id not in heading_styles:
+            continue
+
+        fmt = heading_styles[style_id]
+
+        # Patch run properties
+        r_pr = style_el.find(f"{WNS}rPr")
+        if r_pr is None:
+            r_pr = ET.SubElement(style_el, f"{WNS}rPr")
+
+        if "color" in fmt:
+            color = r_pr.find(f"{WNS}color")
+            if color is None:
+                color = ET.SubElement(r_pr, f"{WNS}color")
+            color.set(f"{WNS}val", fmt["color"])
+
+        if "sz" in fmt:
+            for tag_name in ["sz", "szCs"]:
+                el = r_pr.find(f"{WNS}{tag_name}")
+                if el is None:
+                    el = ET.SubElement(r_pr, f"{WNS}{tag_name}")
+                el.set(f"{WNS}val", fmt["sz"])
+
+        if "font" in fmt:
+            fonts = r_pr.find(f"{WNS}rFonts")
+            if fonts is None:
+                fonts = ET.SubElement(r_pr, f"{WNS}rFonts")
+            for attr in ["ascii", "hAnsi", "eastAsia", "cs"]:
+                fonts.set(f"{WNS}{attr}", fmt["font"])
+
+        if fmt.get("bold"):
+            if r_pr.find(f"{WNS}b") is None:
+                ET.SubElement(r_pr, f"{WNS}b")
+            if r_pr.find(f"{WNS}bCs") is None:
+                ET.SubElement(r_pr, f"{WNS}bCs")
+
+        if fmt.get("italics"):
+            if r_pr.find(f"{WNS}i") is None:
+                ET.SubElement(r_pr, f"{WNS}i")
+
+        # Patch paragraph spacing
+        if "spacing_before" in fmt or "spacing_after" in fmt:
+            p_pr = style_el.find(f"{WNS}pPr")
+            if p_pr is None:
+                p_pr = ET.SubElement(style_el, f"{WNS}pPr")
+            spacing = p_pr.find(f"{WNS}spacing")
+            if spacing is None:
+                spacing = ET.SubElement(p_pr, f"{WNS}spacing")
+            if "spacing_before" in fmt:
+                spacing.set(f"{WNS}before", fmt["spacing_before"])
+            if "spacing_after" in fmt:
+                spacing.set(f"{WNS}after", fmt["spacing_after"])
+
+        patched += 1
+
+    return patched
+
+
+def fix_styles(input_path, output_path=None):
+    if output_path is None:
+        output_path = input_path
+
+    tmp_dir = tempfile.mkdtemp(prefix="fix_styles_")
+
+    try:
+        extract_dir = os.path.join(tmp_dir, "extracted")
+        with zipfile.ZipFile(input_path, "r") as zf:
+            zf.extractall(extract_dir)
+
+        doc_path = os.path.join(extract_dir, "word", "document.xml")
+        styles_path = os.path.join(extract_dir, "word", "styles.xml")
+
+        if not os.path.exists(doc_path) or not os.path.exists(styles_path):
+            print("Error: Missing document.xml or styles.xml")
+            return
+
+        doc_tree = ET.parse(doc_path)
+        styles_tree = ET.parse(styles_path)
+        styles_root = styles_tree.getroot()
+
+        fixes = []
+
+        # Fix 1: docDefaults
+        if fix_doc_defaults(styles_root):
+            fixes.append("docDefaults")
+
+        # Fix 2: Normal style
+        if fix_normal_style(styles_root):
+            fixes.append("Normal style")
+
+        # Fix 3: Heading styles
+        heading_styles = extract_heading_styles_from_document(doc_tree)
+        if heading_styles:
+            patched = patch_heading_styles(styles_root, heading_styles)
+            if patched:
+                fixes.append(f"{patched} heading style(s)")
+
+        if not fixes:
+            print(f"No fixes needed in {output_path}")
+            return
+
+        # Write back
+        styles_tree.write(styles_path, xml_declaration=True, encoding="UTF-8")
+
+        # Repack
+        tmp_docx = os.path.join(tmp_dir, "output.docx")
+        with zipfile.ZipFile(tmp_docx, "w", zipfile.ZIP_DEFLATED) as zf:
+            for root_dir, _, files in os.walk(extract_dir):
+                for f in files:
+                    full_path = os.path.join(root_dir, f)
+                    arc_name = os.path.relpath(full_path, extract_dir)
+                    zf.write(full_path, arc_name)
+
+        shutil.copy2(tmp_docx, output_path)
+        print(f"Fixed {', '.join(fixes)} in {output_path}")
+
+    finally:
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+
+
+if __name__ == "__main__":
+    if len(sys.argv) < 2:
+        print("Usage: python fix_styles.py input.docx [output.docx]")
+        sys.exit(1)
+
+    input_file = sys.argv[1]
+    output_file = sys.argv[2] if len(sys.argv) > 2 else None
+    fix_styles(input_file, output_file)

package/skills/docx/scripts/fix_tables.py

@@ -0,0 +1,118 @@
+"""
+Post-process a docx-js generated .docx file to fix tblGrid values for Pages compatibility.
+
+docx-js generates <w:gridCol w:w="100"/> for all columns regardless of actual cell widths.
+Pages relies on tblGrid for layout, so tables render as 1-char-wide columns.
+This script reads the tcW values from each table's first row and patches tblGrid to match.
+"""
+import sys
+import zipfile
+import os
+import re
+import shutil
+from lxml import etree
+
+WORD_NS = 'http://schemas.openxmlformats.org/wordprocessingml/2006/main'
+NSMAP = {'w': WORD_NS}
+
+def fix_tables(xml_content):
+    """Fix tblGrid values to match first-row cell widths."""
+    root = etree.fromstring(xml_content)
+    tables = root.findall('.//w:tbl', NSMAP)
+    fixes = 0
+
+    for tbl in tables:
+        grid = tbl.find('w:tblGrid', NSMAP)
+        if grid is None:
+            continue
+
+        # Get first row's cell widths
+        first_row = tbl.find('w:tr', NSMAP)
+        if first_row is None:
+            continue
+
+        cells = first_row.findall('w:tc', NSMAP)
+        cell_widths = []
+        for tc in cells:
+            tcPr = tc.find('w:tcPr', NSMAP)
+            if tcPr is not None:
+                tcW = tcPr.find('w:tcW', NSMAP)
+                if tcW is not None:
+                    w_val = tcW.get(f'{{{WORD_NS}}}w')
+                    w_type = tcW.get(f'{{{WORD_NS}}}type', 'dxa')
+                    if w_type == 'dxa' and w_val:
+                        try:
+                            cell_widths.append(int(w_val))
+                        except ValueError:
+                            cell_widths.append(2340)  # default fallback
+                    else:
+                        cell_widths.append(2340)
+                else:
+                    cell_widths.append(2340)
+            else:
+                cell_widths.append(2340)
+
+        # Check if grid needs fixing (all gridCol are 100 = docx-js default)
+        grid_cols = grid.findall('w:gridCol', NSMAP)
+        all_100 = all(gc.get(f'{{{WORD_NS}}}w') == '100' for gc in grid_cols)
+
+        if all_100 and len(cell_widths) == len(grid_cols):
+            for gc, width in zip(grid_cols, cell_widths):
+                gc.set(f'{{{WORD_NS}}}w', str(width))
+            fixes += 1
+
+        # Also ensure tblLayout is set to fixed for Pages
+        tblPr = tbl.find('w:tblPr', NSMAP)
+        if tblPr is not None:
+            layout = tblPr.find('w:tblLayout', NSMAP)
+            if layout is None:
+                layout = etree.SubElement(tblPr, f'{{{WORD_NS}}}tblLayout')
+                layout.set(f'{{{WORD_NS}}}type', 'fixed')
+
+    return etree.tostring(root, xml_declaration=True, encoding='UTF-8', standalone=True), fixes
+
+def fix_docx(input_path, output_path=None):
+    """Fix a .docx file's table grids for Pages compatibility."""
+    if output_path is None:
+        output_path = input_path
+
+    import tempfile
+    tmp_dir = tempfile.mkdtemp(prefix='fix_tables_')
+
+    try:
+        # Extract
+        with zipfile.ZipFile(input_path, 'r') as z:
+            z.extractall(tmp_dir)
+
+        # Fix document.xml
+        doc_path = os.path.join(tmp_dir, 'word', 'document.xml')
+        with open(doc_path, 'rb') as f:
+            xml_content = f.read()
+
+        fixed_xml, num_fixes = fix_tables(xml_content)
+
+        with open(doc_path, 'wb') as f:
+            f.write(fixed_xml)
+
+        # Repack
+        with zipfile.ZipFile(output_path, 'w', zipfile.ZIP_DEFLATED) as zout:
+            for root_dir, dirs, files in os.walk(tmp_dir):
+                for file in files:
+                    file_path = os.path.join(root_dir, file)
+                    arcname = os.path.relpath(file_path, tmp_dir)
+                    zout.write(file_path, arcname)
+
+        print(f"Fixed {num_fixes} table(s) in {output_path}")
+        return num_fixes
+
+    finally:
+        shutil.rmtree(tmp_dir, ignore_errors=True)
+
+if __name__ == '__main__':
+    if len(sys.argv) < 2:
+        print("Usage: python fix_docx_tables.py <input.docx> [output.docx]")
+        sys.exit(1)
+
+    input_file = sys.argv[1]
+    output_file = sys.argv[2] if len(sys.argv) > 2 else input_file
+    fix_docx(input_file, output_file)

package/skills/pptx/SKILL.md

@@ -96,6 +96,57 @@ Use one font pairing for the entire deck. Consistency.
 - Never center body text (left-align only)
 - Use `paraSpaceAfter: 6` for bullet spacing, never `lineSpacing`
 
+### Slide Boundary Rules (CRITICAL — Content Overflow)
+
+**Nothing may extend beyond the slide edges.** Content that overflows is invisible — it gets cut off and looks broken in presentation mode.
+
+Standard 16:9 slide dimensions: **10" wide × 5.625" tall**
+
+Every element must satisfy these constraints:
+- `x + w ≤ 10` (right edge)
+- `y + h ≤ 5.625` (bottom edge)
+- `x ≥ 0` and `y ≥ 0` (top-left origin)
+
+**Before placing any element, calculate remaining space:**
+```
+available_height = 5.625 - current_y - 0.5   // 0.5" bottom margin
+```
+
+If content doesn't fit, you MUST do one of these (in order of preference):
+1. **Split across two slides** — A second slide is always better than overflow
+2. **Reduce font sizes** — Body → 12pt, stats → 48pt instead of 60pt, title → 18pt
+3. **Remove items** — Fewer bullets, fewer cards. Less is more
+4. **Tighten spacing** — Reduce gaps between elements to 0.2" minimum
+
+**Safe content zones (with 0.5" margins):**
+```
+Title area:     y = 0.5,  h = 0.6
+Content start:  y = 1.2
+Content end:    y = 5.1   (0.5" bottom margin)
+Usable content height: 3.9 inches — plan ALL layouts within this
+```
+
+**Layout height budgets — know these before coding:**
+
+| Layout Type | Title | Content Area | Max Items |
+|---|---|---|---|
+| Bullet list | 0.7" | 3.9" | 8 bullets max (0.35" each) |
+| 2-column bullets | 0.7" | 3.9" | 5 bullets per column |
+| Stat cards (1 row) | 0.7" | 1.8" for cards | 3-4 cards |
+| Stat cards (2 rows) | 0.7" | 3.4" for cards | 6-8 cards |
+| Comparison (side-by-side) | 0.7" | 3.2" max per card | 4 bullets per card |
+| Table | 0.7" | 3.9" | 7 rows max (0.4" per row) |
+| Title + subtitle + cards | 1.2" | 3.4" | 3 cards |
+
+**Common overflow traps:**
+- **Comparison layouts** — Two side-by-side cards are taller than you think. Budget 2.5-3" max per card, not 3.5". If each card has a title + 5 bullets, it needs ~3" minimum — split to two slides
+- **Bullet lists with 6+ items** — Each bullet needs ~0.35". Six bullets = 2.1". Add title + spacing = 3.5"+
+- **Stat cards stacked in 2 rows** — stat (60pt) + label (12pt) + padding = ~1.5" per row. Two rows + title = 4" before you add anything else
+- **Tables with 5+ rows** — Header + 5 data rows = ~2.4". Add title + margins = 3.5"
+- **"Just one more element"** — Adding a footnote, source line, or page number below a full slide. Check remaining space first
+
+**Validation rule: After writing code for any slide, mentally verify that the lowest element's `y + h` does not exceed 5.5 inches (leaving 0.125" safety margin). If it does, refactor before moving to the next slide.**
+
 ### What to Avoid
 
 - **Don't repeat the same layout** — Two content slides in a row can feel monotonous. Vary between text-heavy, stat cards, comparisons, and two-column layouts.
@@ -104,6 +155,7 @@ Use one font pairing for the entire deck. Consistency.
 - **Don't default to blue** — Blue is overdone. It's the safe choice. Pick a palette that matches the content's emotional tone.
 - **Never add accent lines under titles** — This is the hallmark of AI-generated slides. If you add an underline, make it purposeful (color bar on stat cards) not decorative.
 - **Don't create text-only slides** — Every slide needs at least one visual anchor: a stat card, an accent color, an icon, or a highlighted quote.
+- **Never let content overflow the slide** — If `y + h > 5.625`, content is cut off. Always calculate remaining space before placing elements. See "Slide Boundary Rules" above.
 
 ## QA Process
 

package/skills/pptx/pptxgenjs.md

@@ -29,16 +29,28 @@ Key point: Always create a fresh `PptxGenJS()` instance per presentation. Don't
 Standard 16:9 layout is 10 inches wide by 5.625 inches tall. All positioning is in inches.
 
 ```javascript
-// Slide area
-const W = 10;          // Width
-const H = 5.625;       // Height
+// Slide area — HARD LIMITS (nothing may exceed these)
+const W = 10;          // Width (inches)
+const H = 5.625;       // Height (inches)
 const M = 0.5;         // Margin (standard)
-const contentWidth = W - 2 * M;  // 9 inches
+const contentWidth = W - 2 * M;  // 9 inches usable
 
 // Common positioning
-const titleY = M;           // Top margin
-const contentStartY = M + 0.8;  // After title
-const bottomY = H - 0.8;    // Near bottom for footer
+const titleY = M;                // Top margin
+const contentStartY = M + 0.8;  // After title (y = 1.3)
+const maxContentY = H - M;      // 5.125 — absolute bottom of content
+const contentHeight = maxContentY - contentStartY;  // ~3.8" available
+
+// BOUNDARY CHECK — use before placing every element:
+// if (elementY + elementH > H) → content will overflow, reduce or split slide
+```
+
+**CRITICAL: Every element must satisfy `y + h ≤ 5.625`.** If an element's bottom edge exceeds the slide height, it will be cut off in presentation mode. Always calculate remaining space before placing elements:
+```javascript
+const remainingHeight = H - currentY - M;  // available space below current position
+if (cardHeight > remainingHeight) {
+    // Split to next slide or reduce content
+}
 ```
 
 ## Text & Formatting
@@ -622,3 +634,33 @@ slide.addText([
 
 pres.writeFile({ fileName: "output.pptx" });
 ```
+
+## Common Pitfalls: Stat Cards & Large Numbers
+
+**Large numbers overflow their text boxes.** At 48pt+ with bold fonts like Arial Black, values like "12.4K", "$156K", or "$48K" are often wider than narrow card text boxes (2-3 inches). When they overflow, the text wraps and produces broken-looking results — e.g. "12.4" on one line and "K" huge on the next.
+
+**Always use `shrinkText: true` on stat values:**
+```javascript
+slide.addText("$156K", {
+    x: cardX, y: cardY + 0.5, w: cardW, h: 1,
+    fontSize: 52,
+    fontFace: "Arial Black",
+    color: accentColor,
+    bold: true,
+    align: "center",
+    valign: "middle",
+    shrinkText: true  // CRITICAL — auto-scales text to fit the box
+});
+```
+
+This tells PowerPoint to auto-shrink the font size if the text doesn't fit. It's invisible when text fits fine, but prevents wrapping when values are wider than expected.
+
+**When to use `shrinkText: true`:**
+- All stat card values (any font ≥ 36pt in a box < 3" wide)
+- Slide titles on section dividers (large font + long titles)
+- Any text box where the content length is unpredictable
+
+**Alternative approaches if `shrinkText` isn't sufficient:**
+- Reduce font size for longer values: `fontSize: value.length > 4 ? 40 : 52`
+- Widen cards: use 3 cards per row instead of 4
+- Abbreviate values: "$156K" instead of "$156,000"

package/skills/pptx/scripts/create_pptx.js

@@ -8,8 +8,8 @@
  * JSON spec format: see references/spec-format.md
  */
 
-import pptxgen from "pptxgenjs";
-import fs from "node:fs";
+const pptxgen = require("pptxgenjs");
+const fs = require("fs");
 
 // ═══════════════════════════════════════════
 // DEFAULT THEME