@heylemon/lemonade 0.1.6 → 0.1.8

package/skills/docx/SKILL.md

@@ -1,37 +1,708 @@
 ---
-name: docx
-description: "Create professional, polished .docx documents (reports, memos, briefs, proposals, letters) with consistent formatting and validation. Trigger for requests to create or draft Word documents."
-license: Proprietary. LICENSE.txt has complete terms
+name: pro-docs
+description: "Create professional, polished documents — reports, memos, proposals, briefs, and letters — with consistent formatting, proper typography, and clear structure. Use this skill whenever the user wants to create a document, report, memo, proposal, brief, letter, write-up, analysis, or any structured written deliverable. Also trigger when someone says 'write me a report', 'create a document', 'draft a memo', 'make this look professional', or needs any written output that should look polished and ready to share with stakeholders."
 ---
 
-# Pro Docs for DOCX
+# Pro Docs — Professional Document Creation
 
-This skill uses deterministic scripts to generate polished `.docx` files.
+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.
 
-## Workflow
+## Quick Reference
 
-1. Understand request (document type, audience, goal).
-2. Build a JSON spec.
-3. Run creation script.
-4. Validate output.
-5. Deliver.
+| Task | Approach | Tool |
+|------|----------|------|
+| **Create new document** | Write docx-js code using Document, Packer, Paragraph, TextRun, Table | 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` |
+| **Visual QA** | Convert to PDF then to images | soffice + pdftoppm |
 
-## Build
+---
+
+## Creating New Documents with docx-js
+
+### Setup & Imports
+
+```javascript
+const { Document, Packer, Paragraph, TextRun, Table, TableCell, WidthType,
+        BorderStyle, UnderlineType, PageBreak, Header, Footer } = require("docx");
+const fs = require("fs");
+
+// Create a new document
+const doc = new Document({
+  sections: [
+    {
+      children: [
+        // Add paragraphs, tables, etc. here
+      ]
+    }
+  ]
+});
+
+// Write to file
+Packer.toBuffer(doc).then(buffer => {
+  fs.writeFileSync("output.docx", buffer);
+  console.log("Document created: output.docx");
+});
+```
+
+### Page Size & Margins
+
+Use US Letter (8.5 x 11 inches). docx-js works in **DXA units** (twentieths of a point):
+- 1 inch = 1440 DXA
+- US Letter = 12240 x 15840 DXA
+- Standard margins: 1 inch (1440 DXA) on sides, 0.8 inches (1152 DXA) top/bottom
+
+```javascript
+const doc = new Document({
+  sections: [
+    {
+      properties: {
+        page: {
+          margins: {
+            top: 1152,     // 0.8 inches
+            bottom: 1152,
+            left: 1440,    // 1 inch
+            right: 1440
+          }
+        }
+      },
+      children: [ /* content */ ]
+    }
+  ]
+});
+```
+
+For landscape, swap width/height but pass the document normally — docx-js handles orientation internally.
+
+### Typography Scale
+
+Establish a consistent hierarchy. All sizes in half-points (pt * 2):
+
+```javascript
+const TYPOGRAPHY = {
+  title: 52,        // 26pt — document title
+  subtitle: 28,     // 14pt — subtitle
+  h1: 36,           // 18pt — major sections
+  h2: 28,           // 14pt — subsections
+  h3: 24,           // 12pt — sub-subsections
+  body: 22,         // 11pt — normal text
+  small: 18,        // 9pt — captions, footers
+  caption: 16       // 8pt — figure captions
+};
+
+const COLORS = {
+  primary: "1B3A5C",      // Dark navy for headings
+  accent: "2E86AB",       // Teal for highlights
+  lightAccent: "E8F4F8",  // Light teal for backgrounds
+  text: "2C3E50",         // Dark gray for body
+  muted: "7F8C8D"         // Light gray for secondary text
+};
+```
+
+### Creating Headings with Styles
+
+Override built-in heading styles to ensure they appear in TOC. Use `outlineLevel` to control Table of Contents depth:
+
+```javascript
+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
+});
+
+new Paragraph({
+  text: "Subsection",
+  heading: HeadingLevel.HEADING_2,
+  outlineLevel: 1,
+  style: "Heading2",
+  run: { size: TYPOGRAPHY.h2, color: COLORS.primary },
+  spacing: { before: 360, after: 120 }
+});
+```
+
+### Lists: Never Use Unicode Bullets
+
+CRITICAL: Never manually insert bullet characters like •, ◦, ▪. Use the list APIs:
+
+```javascript
+// Bullet list (unordered)
+new Paragraph({
+  text: "First bullet point",
+  bullet: {
+    level: 0
+  },
+  run: { size: TYPOGRAPHY.body }
+}),
+new Paragraph({
+  text: "Second bullet point",
+  bullet: { level: 0 },
+  run: { size: TYPOGRAPHY.body }
+})
+
+// Numbered list
+new Paragraph({
+  text: "First step",
+  numbering: {
+    level: 0,
+    instance: 0  // Different instance for each numbered list
+  },
+  run: { size: TYPOGRAPHY.body }
+}),
+new Paragraph({
+  text: "Second step",
+  numbering: { level: 0, instance: 0 },
+  run: { size: TYPOGRAPHY.body }
+})
+```
+
+### Tables: Dual Width Rules (CRITICAL)
+
+Tables MUST specify width in two places. Always use `WidthType.DXA`, never PERCENTAGE:
+
+```javascript
+new Table({
+  width: {
+    size: 100,
+    type: WidthType.PERCENTAGE  // Table width = 100% of content area
+  },
+  rows: [
+    new TableRow({
+      children: [
+        new TableCell({
+          width: { size: 2000, type: WidthType.DXA },  // Individual cell width in DXA
+          children: [ new Paragraph("Header 1") ]
+        }),
+        new TableCell({
+          width: { size: 2500, type: WidthType.DXA },
+          children: [ new Paragraph("Header 2") ]
+        }),
+        new TableCell({
+          width: { size: 2000, type: WidthType.DXA },
+          children: [ new Paragraph("Header 3") ]
+        })
+      ]
+    }),
+    // Data rows follow
+    new TableRow({
+      children: [
+        new TableCell({
+          width: { size: 2000, type: WidthType.DXA },
+          shading: { fill: "E8F4F8", type: ShadingType.CLEAR },
+          children: [ new Paragraph("Data 1") ]
+        }),
+        // ... more cells
+      ]
+    })
+  ]
+});
+```
+
+Cell widths must sum to total table width. 6.5 inches of content (8.5 - 2 margins) = ~9360 DXA.
+
+### Cell Shading (Background Colors)
+
+Use `ShadingType.CLEAR`, never SOLID:
+
+```javascript
+new TableCell({
+  shading: {
+    fill: "1B3A5C",        // Hex color
+    type: ShadingType.CLEAR  // CRITICAL: use CLEAR
+  },
+  children: [ /* cell content */ ]
+})
+```
+
+### Headers & Footers with Page Numbers
+
+```javascript
+const doc = new Document({
+  sections: [
+    {
+      properties: {
+        page: { /* margin config */ }
+      },
+      children: [ /* content */ ],
+      header: {
+        children: [
+          new Paragraph({
+            text: "Company Name",
+            alignment: AlignmentType.RIGHT,
+            run: { size: TYPOGRAPHY.small, color: COLORS.muted }
+          })
+        ]
+      },
+      footer: {
+        children: [
+          new Paragraph({
+            text: "Page ",
+            alignment: AlignmentType.CENTER,
+            children: [
+              new PageNumber(),  // Inserts page number
+              new TextRun(" of "),
+              new PageBreakCount()
+            ]
+          })
+        ]
+      }
+    }
+  ]
+});
+```
+
+### Images (type parameter is REQUIRED)
+
+Always include `type` when adding images:
+
+```javascript
+new Paragraph({
+  children: [
+    new ImageRun({
+      data: fs.readFileSync("image.png"),
+      transformation: {
+        width: 400,
+        height: 300
+      },
+      type: "image/png"  // CRITICAL: PNG, JPG, GIF, etc.
+    })
+  ]
+})
+```
+
+### Page Breaks (Must Be Inside Paragraph)
+
+CRITICAL: PageBreak must always be inside a Paragraph, never standalone:
+
+```javascript
+// Correct
+new Paragraph({
+  children: [ new PageBreak() ]
+}),
+
+// Wrong — this will fail
+new PageBreak()
+```
+
+### Table of Contents
+
+docx-js can't generate TOC fields directly, but you can add placeholder text that users update in Word:
+
+```javascript
+new Paragraph({
+  text: "Table of Contents",
+  style: "Heading2",
+  run: { bold: true, size: TYPOGRAPHY.h2, color: COLORS.primary }
+}),
+new Paragraph({
+  text: "[Right-click to update Table of Contents in Word]",
+  run: { italic: true, color: COLORS.muted }
+}),
+new Paragraph({ children: [new PageBreak()] })
+```
+
+Or use a more sophisticated approach with field codes (requires XML manipulation).
+
+---
+
+## Critical Rules for docx-js
+
+**DO:**
+- Set page size explicitly (use US Letter dimensions)
+- For landscape: still pass standard margins, docx-js handles rotation
+- Create separate Paragraph objects for each paragraph (never use \n)
+- Use List APIs for bullets/numbers (never hardcode • or -)
+- Always include `type` parameter on ImageRun
+- 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
+- Set `spacing.before` and `spacing.after` explicitly on headings
+
+**DON'T:**
+- Use newlines (\n) — create separate Paragraphs instead
+- Mix WidthType.PERCENTAGE and WidthType.DXA on different table cells
+- Omit `type` on ImageRun (causes runtime errors)
+- Use unicode bullet characters manually
+- Put PageBreak outside a Paragraph
+- Forget cell width specifications (columns collapse)
+- Use `ShadingType.SOLID` (use CLEAR)
+- Assume A4 page size (always set explicitly to US Letter)
+- Mix font styles — stick to 2 fonts (heading + body)
+
+---
+
+## Writing Quality Rules
+
+Even if the code is perfect, content matters. Follow these principles:
+
+### Structure
+- **Answer first, support second.** Executive summaries at the top with conclusions. Don't bury decisions in 10 pages of analysis.
+- **One idea per paragraph.** If you see two points in one paragraph, split them.
+- **Action headings, not topic headings.** Not "Q3 Revenue" but "Q3 Revenue Missed Target by 22%." Headings should complete the thought.
+- **Three key points.** Group arguments into sets of three — it's how working memory works.
+
+### Clarity
+- **Short words over long.** Use "help" not "facilitate," "about" not "approximately," "use" not "utilize."
+- **Active voice.** "We recommend" not "it is recommended." "Sales grew" not "growth was achieved."
+- **Quantify.** "43% growth" not "significant growth." "3 weeks" not "soon."
+- **Cut filler.** "In order to" → "to." "At this point in time" → "now." "Due to the fact that" → "because."
+- **No weasel words.** Remove "arguably," "somewhat," "it could be said that."
+
+### Tables
+- Use tables for comparisons, timelines, structured data — not for prose.
+- Every table needs clear headers.
+- Keep tables under 7 columns (split wider tables).
+- Include units in headers ("Revenue ($M)") not in every cell.
+
+### Callouts
+- Use callouts for key decisions, critical warnings, or bottom-line takeaways.
+- Maximum one per major section — if everything is highlighted, nothing stands out.
+- **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.
+
+---
+
+## Design Guidance
+
+### Color Palettes
+
+**Professional (Default):**
+- Primary: #1B3A5C (dark navy)
+- Accent: #2E86AB (teal)
+- Light accent: #E8F4F8 (pale teal)
+- Text: #2C3E50 (charcoal)
+
+**Modern Tech:**
+- Primary: #0F3460 (deep blue)
+- Accent: #16213E (dark blue)
+- Light accent: #E0E7FF (pale blue)
+
+**Corporate:**
+- Primary: #1a1a2e (very dark blue)
+- Accent: #d62828 (red accent)
+- Light accent: #f7f7f7 (light gray)
+
+### Font Pairing
+
+Stick to **two fonts maximum**:
+- **Headings & body:** Arial or Calibri (clean, professional)
+- **Luxury documents:** Georgia (headings) + Garamond (body)
+- **Technical:** Consolas or Courier for code samples, Arial for prose
+
+Always verify fonts are installed on target systems. Arial and Calibri render everywhere.
+
+### When to Use Callouts
+
+- Executive summary conclusions
+- Budget figures in proposals
+- Critical deadlines or warnings
+- Key decisions needed from stakeholders
+- Not: every recommendation (overuse kills impact)
+
+---
+
+## QA & Validation Process
+
+### 1. Create & Validate
 
 ```bash
-pip install python-docx --break-system-packages 2>/dev/null
-python scripts/create_doc.py spec.json output.docx
+# Write docx-js code, run it
+node create-report.js
+
+# Validate the output
+python scripts/validate.py report.docx
 ```
 
-## Validate
+The validator checks:
+- XML well-formedness (can be opened in Word)
+- Font consistency (warns if > 3 fonts)
+- Paragraph length (warns if > 500 chars)
+- Empty headings
+- Manual bullet characters (should use List APIs)
+
+### 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. Visual Check (PDF Conversion)
+
+```bash
+# Convert to PDF
+soffice --headless --convert-to pdf report.docx
+
+# Convert to images for inspection (150 DPI, JPEG)
+pdftoppm -jpeg -r 150 report.pdf page
+
+# View: page-1.jpg, page-2.jpg, etc.
+```
+
+### 4. 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. Run `fix_tables.py` again (step 2)
+4. Re-validate with `validate.py`
+5. Re-convert to PDF if visual issues
+
+Iterate until both validation passes and visual output looks polished.
+
+---
+
+## Template Patterns by Document Type
+
+### Report Structure (Most Flexible)
+
+```javascript
+[
+  titleSection(),      // Title, date, author
+  tocSection(),        // Table of Contents
+  execSummary(),       // 2-3 paragraphs: findings, conclusions, recs upfront
+  background(),        // Brief context only
+  keyFindings(),       // 3 major findings with supporting data
+  recommendations(),   // Numbered action items with owners + timeline
+  nextSteps(),         // Action table with owners and due dates
+  appendices()         // Supporting details, raw data
+]
+```
+
+### Memo (1-2 pages max)
+
+```javascript
+[
+  titleSection(),
+  purpose(),           // One sentence: why this memo exists
+  background(),        // 2-3 sentences of context
+  recommendation(),    // Proposal + rationale + callout with ask
+  supportingDetails(), // Evidence
+  nextSteps()          // Bulleted actions with owners
+]
+```
+
+### Proposal (Pitch to client)
+
+```javascript
+[
+  titleSection(),       // With client name
+  executiveSummary(),   // Problem + solution + why us
+  understandingChallenge(), // Show you understand their pain
+  proposedSolution(),   // What you'll do + how it's different
+  approachTimeline(),   // Table: phases, activities, dates
+  investment(),         // Pricing table
+  whyUs(),              // Credentials, relevant projects
+  nextSteps()           // Call to action
+]
+```
+
+### Brief (1-pager)
+
+```javascript
+[
+  titleSection(),
+  objective(),          // One sentence
+  context(),            // 2-3 sentences
+  keyPoints(),          // Bulleted (3 max)
+  constraints(),        // Budget, timeline, scope
+  successCriteria(),    // How we measure success
+  decisionNeeded()      // Callout: specific ask + deadline
+]
+```
+
+---
+
+## Common Customizations
+
+### Landscape Orientation
+
+Swap dimensions but keep same margin structure:
+
+```javascript
+const doc = new Document({
+  sections: [
+    {
+      properties: {
+        page: {
+          // Landscape = wide table spreads, timelines, etc.
+          margins: {
+            top: 1152, bottom: 1152, left: 1440, right: 1440
+          }
+        }
+      },
+      children: [ /* wide tables */ ]
+    }
+  ]
+});
+```
+
+### Cover Page
+
+Add a dedicated section with large title, logo, date:
+
+```javascript
+new Paragraph({
+  text: "PROJECT PROPOSAL",
+  alignment: AlignmentType.CENTER,
+  spacing: { before: 2880, after: 240 },  // 2 inches before
+  run: { size: TYPOGRAPHY.title, bold: true, color: COLORS.primary }
+}),
+new Paragraph({
+  text: "Prepared for Acme Corp",
+  alignment: AlignmentType.CENTER,
+  run: { size: TYPOGRAPHY.subtitle, color: COLORS.muted }
+}),
+new Paragraph({ children: [new PageBreak()] })
+```
+
+### Header with Company Branding
+
+```javascript
+section.header = {
+  children: [
+    new Paragraph({
+      text: "Company Name — Confidential",
+      alignment: AlignmentType.RIGHT,
+      run: { size: TYPOGRAPHY.small, color: COLORS.muted }
+    })
+  ]
+};
+```
+
+---
+
+## Dependencies
 
 ```bash
-python scripts/validate_doc.py output.docx
+npm install docx
+npm install fs  # Built-in Node.js
 ```
 
-Use `references/templates.md` for template structures and choose the closest format:
-- report
-- memo
-- proposal
-- brief
-- letter
+For validation:
+```bash
+pip install python-docx --break-system-packages  # For validate.py
+```
+
+For visual QA:
+```bash
+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.
+
+**Tables look misaligned:** Missing cell widths or inconsistent width types. Ensure every cell has `width: { size: X, type: WidthType.DXA }`.
+
+**Page breaks in wrong place:** PageBreak must be inside Paragraph. `new Paragraph({ children: [new PageBreak()] })`.
+
+**Fonts not rendering:** Arial/Calibri are safest. If using specialty fonts, ensure they're installed on target system.
+
+**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
+
+See `references/templates.md` for full template examples with code.