@heylemon/lemonade 0.1.6 → 0.1.7

package/skills/docx/scripts/validate.py

@@ -0,0 +1,237 @@
+#!/usr/bin/env python3
+"""
+Validate a .docx file for quality, consistency, and standards compliance.
+
+Checks for:
+- XML well-formedness and schema validity
+- Font consistency (warns if > 3 fonts)
+- Paragraph length and structure
+- Empty headings
+- Manual bullet characters (should use List APIs)
+- Table consistency
+- Page setup
+
+Usage: python validate.py document.docx
+"""
+
+import sys
+import os
+import zipfile
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+try:
+    from docx import Document
+    from docx.shared import Pt
+except ImportError:
+    print("ERROR: python-docx not installed. Run: pip install python-docx --break-system-packages")
+    sys.exit(1)
+
+
+def validate_xml_wellformedness(docx_path):
+    """Check that the document XML is well-formed."""
+    issues = []
+    try:
+        with zipfile.ZipFile(docx_path, 'r') as zip_ref:
+            try:
+                xml_content = zip_ref.read('word/document.xml')
+                ET.fromstring(xml_content)
+            except ET.ParseError as e:
+                issues.append(f"XML Parse Error: {str(e)}")
+    except zipfile.BadZipFile:
+        issues.append("File is not a valid ZIP archive (docx must be ZIP)")
+    except Exception as e:
+        issues.append(f"Could not read document.xml: {str(e)}")
+    return issues
+
+
+def validate_document(docx_path):
+    """Validate document structure, content, and formatting."""
+    issues = []
+    warnings = []
+    info = []
+
+    if not os.path.exists(docx_path):
+        print(f"ERROR: File not found: {docx_path}")
+        sys.exit(1)
+
+    # Check XML well-formedness first
+    xml_issues = validate_xml_wellformedness(docx_path)
+    if xml_issues:
+        issues.extend(xml_issues)
+        return issues, warnings, info
+
+    try:
+        doc = Document(docx_path)
+    except Exception as e:
+        issues.append(f"Could not open document: {str(e)}")
+        return issues, warnings, info
+
+    # ─── Page setup checks ───
+    section = doc.sections[0] if doc.sections else None
+    if section:
+        from docx.shared import Inches
+        if section.page_width and section.page_width < Inches(7):
+            warnings.append("Page width is unusually narrow (< 7 inches)")
+        if section.left_margin and section.left_margin < Inches(0.5):
+            warnings.append("Left margin is very small (< 0.5 inches) — may look cramped")
+        if section.right_margin and section.right_margin < Inches(0.5):
+            warnings.append("Right margin is very small (< 0.5 inches) — may look cramped")
+
+    # ─── Paragraph checks ───
+    paragraph_count = 0
+    heading_count = 0
+    empty_paragraphs = 0
+    consecutive_empty = 0
+    max_consecutive_empty = 0
+    fonts_used = set()
+    sizes_used = set()
+    manual_bullets = []
+
+    # Unicode bullet characters
+    bullet_chars = {'•', '◦', '▪', '●', '○', '■', '–', '—', '-', '*'}
+
+    for p in doc.paragraphs:
+        paragraph_count += 1
+        text = p.text.strip()
+
+        # Track empty paragraphs
+        if not text:
+            empty_paragraphs += 1
+            consecutive_empty += 1
+            max_consecutive_empty = max(max_consecutive_empty, consecutive_empty)
+        else:
+            consecutive_empty = 0
+
+        # Check headings
+        if p.style.name.startswith("Heading"):
+            heading_count += 1
+            # Heading shouldn't end with a period
+            if text.endswith("."):
+                warnings.append(f"Heading ends with period: \"{text[:50]}\"")
+            # Heading shouldn't be all caps (unless very short)
+            if text == text.upper() and len(text) > 3:
+                if "1" not in p.style.name:
+                    warnings.append(f"Heading is ALL CAPS (use Title Case): \"{text[:50]}\"")
+            # Check for empty headings
+            if not text:
+                issues.append(f"Empty heading found in style {p.style.name}")
+
+        # Detect manual bullet characters
+        if not p.style.name.startswith("List"):
+            # Check if text starts with bullet-like characters
+            for bullet_char in bullet_chars:
+                if text.startswith(bullet_char):
+                    manual_bullets.append(f"Manual bullet '{bullet_char}' in: \"{text[:50]}\"")
+                    break
+
+        # Track fonts and sizes
+        for run in p.runs:
+            if run.font.name:
+                fonts_used.add(run.font.name)
+            if run.font.size:
+                sizes_used.add(run.font.size)
+
+        # Check for very long paragraphs (over 500 chars)
+        if len(text) > 500:
+            word_count = len(text.split())
+            warnings.append(f"Very long paragraph ({len(text)} chars, {word_count} words): \"{text[:50]}...\" — consider breaking up")
+
+        # Check for excessive spacing/empty paragraphs
+        if len(text) == 0 and paragraph_count > 1:
+            # This is tracked separately
+            pass
+
+    # Report manual bullet issues
+    if manual_bullets:
+        for bullet_issue in manual_bullets[:5]:  # Show first 5
+            issues.append(f"Manual bullet character detected: {bullet_issue} — use List Bullet style instead")
+        if len(manual_bullets) > 5:
+            issues.append(f"... and {len(manual_bullets) - 5} more manual bullets")
+
+    # ─── Table checks ───
+    table_issues = 0
+    for ti, table in enumerate(doc.tables, 1):
+        if len(table.rows) == 0:
+            issues.append(f"Table {ti} has no rows")
+            table_issues += 1
+        if len(table.columns) == 0:
+            issues.append(f"Table {ti} has no columns")
+            table_issues += 1
+        # Check for empty cells in header row
+        if table.rows:
+            first_row = table.rows[0]
+            for ci, cell in enumerate(first_row.cells):
+                if not cell.text.strip():
+                    warnings.append(f"Table {ti}: empty header cell in column {ci+1}")
+
+    # ─── Font consistency checks ───
+    if len(fonts_used) > 3:
+        warnings.append(f"Too many fonts ({len(fonts_used)}): {', '.join(sorted(fonts_used))} — keep to 2 fonts max (heading + body)")
+    if len(sizes_used) > 8:
+        warnings.append(f"Many different font sizes used ({len(sizes_used)}) — use a consistent typography scale")
+
+    # ─── Structure checks ───
+    if max_consecutive_empty > 2:
+        warnings.append(f"Found {max_consecutive_empty} consecutive empty paragraphs — use spacing instead")
+
+    if heading_count == 0 and paragraph_count > 15:
+        warnings.append("No headings found in a longer document — add headings for structure")
+
+    if paragraph_count < 3:
+        warnings.append("Document is very short — consider if this is complete")
+
+    # ─── Summary info ───
+    info.append(f"Paragraphs: {paragraph_count}")
+    info.append(f"Headings: {heading_count}")
+    info.append(f"Tables: {len(doc.tables)}")
+    info.append(f"Sections: {len(doc.sections)}")
+    info.append(f"Fonts: {', '.join(sorted(fonts_used)) if fonts_used else 'default only'}")
+    if empty_paragraphs > 0:
+        info.append(f"Empty paragraphs: {empty_paragraphs}")
+
+    return issues, warnings, info
+
+
+def main():
+    if len(sys.argv) < 2:
+        print("Usage: python validate.py document.docx")
+        sys.exit(1)
+
+    docx_path = sys.argv[1]
+    issues, warnings, info = validate_document(docx_path)
+
+    # ─── Report ───
+    print(f"\n{'═' * 60}")
+    print(f"  Document Validation: {os.path.basename(docx_path)}")
+    print(f"{'═' * 60}\n")
+
+    for item in info:
+        print(f"  ℹ  {item}")
+    print()
+
+    if issues:
+        print(f"  ✘  {len(issues)} ISSUE(S):")
+        for issue in issues:
+            print(f"     • {issue}")
+        print()
+
+    if warnings:
+        print(f"  ⚠  {len(warnings)} WARNING(S):")
+        for w in warnings:
+            print(f"     • {w}")
+        print()
+
+    if not issues and not warnings:
+        print("  ✔  No issues found — document looks clean!\n")
+        return 0
+    elif not issues:
+        print("  ✔  No critical issues (warnings only)\n")
+        return 0
+    else:
+        print(f"  ✘  {len(issues)} critical issue(s) need fixing\n")
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/skills/docx/scripts/validate_doc.py

@@ -1,14 +1,17 @@
 #!/usr/bin/env python3
 """
 Validate a .docx file for common formatting issues.
+Checks typography, spacing, structure, and consistency.
+
+Usage: python validate_doc.py document.docx
 """
 
-import os
 import sys
+import os
 
 try:
     from docx import Document
-    from docx.shared import Inches
+    from docx.shared import Pt, Inches
 except ImportError:
     print("ERROR: python-docx not installed. Run: pip install python-docx --break-system-packages")
     sys.exit(1)
@@ -17,55 +20,133 @@ except ImportError:
 def validate(path):
     issues = []
     warnings = []
+    info = []
 
     if not os.path.exists(path):
         print(f"ERROR: File not found: {path}")
-        return 1
+        sys.exit(1)
 
     doc = Document(path)
 
+    # ── Page setup checks ──
     section = doc.sections[0]
+    if section.page_width and section.page_width < Inches(7):
+        warnings.append("Page width is unusually narrow (< 7 inches)")
     if section.left_margin and section.left_margin < Inches(0.5):
-        warnings.append("Left margin is very small (< 0.5 inches)")
+        warnings.append("Left margin is very small (< 0.5 inches) — may look cramped")
     if section.right_margin and section.right_margin < Inches(0.5):
-        warnings.append("Right margin is very small (< 0.5 inches)")
+        warnings.append("Right margin is very small (< 0.5 inches) — may look cramped")
 
+    # ── Paragraph checks ──
+    paragraph_count = 0
     heading_count = 0
+    empty_paragraphs = 0
+    consecutive_empty = 0
+    max_consecutive_empty = 0
     fonts_used = set()
+    sizes_used = set()
 
     for p in doc.paragraphs:
+        paragraph_count += 1
+
+        # Track empty paragraphs
+        if not p.text.strip():
+            empty_paragraphs += 1
+            consecutive_empty += 1
+            max_consecutive_empty = max(max_consecutive_empty, consecutive_empty)
+        else:
+            consecutive_empty = 0
+
+        # Check headings
         if p.style.name.startswith("Heading"):
             heading_count += 1
+            # Heading shouldn't end with a period
             if p.text.strip().endswith("."):
-                warnings.append(f'Heading ends with period: "{p.text.strip()[:50]}"')
-
-        if p.text.strip().startswith(("•", "◦", "▪", "●", "○", "■", "–", "—")):
-            if not p.style.name.startswith("List"):
-                issues.append(f'Manual bullet character detected: "{p.text.strip()[:50]}"')
+                warnings.append(f"Heading ends with period: \"{p.text.strip()[:50]}\"")
+            # Heading shouldn't be all caps (unless H1)
+            if p.text.strip() == p.text.strip().upper() and len(p.text.strip()) > 3:
+                if "1" not in p.style.name:
+                    warnings.append(f"Heading is all caps (consider title case): \"{p.text.strip()[:50]}\"")
 
+        # Track fonts and sizes
         for run in p.runs:
             if run.font.name:
                 fonts_used.add(run.font.name)
+            if run.font.size:
+                sizes_used.add(run.font.size)
+
+        # Check for very long paragraphs (over 300 words)
+        word_count = len(p.text.split())
+        if word_count > 300:
+            warnings.append(f"Very long paragraph ({word_count} words): \"{p.text.strip()[:50]}...\" — consider breaking up")
 
+        # Check for unicode bullet characters (should use list styles instead)
+        if p.text.strip().startswith(("•", "◦", "▪", "●", "○", "■", "–", "—")):
+            if not p.style.name.startswith("List"):
+                issues.append(f"Manual bullet character detected: \"{p.text.strip()[:50]}\" — use List Bullet style instead")
+
+    # ── Table checks ──
+    for ti, table in enumerate(doc.tables):
+        if len(table.rows) == 0:
+            issues.append(f"Table {ti+1} has no rows")
+        if len(table.columns) == 0:
+            issues.append(f"Table {ti+1} has no columns")
+        # Check for empty cells in header row
+        if table.rows:
+            first_row = table.rows[0]
+            for ci, cell in enumerate(first_row.cells):
+                if not cell.text.strip():
+                    warnings.append(f"Table {ti+1}: empty header cell in column {ci+1}")
+
+    # ── Consistency checks ──
     if len(fonts_used) > 3:
-        warnings.append(f"Too many fonts used ({len(fonts_used)}): {', '.join(sorted(fonts_used))}")
-    if heading_count == 0 and len(doc.paragraphs) > 10:
-        warnings.append("No headings found in a long document")
+        warnings.append(f"Too many fonts used ({len(fonts_used)}): {', '.join(sorted(fonts_used))} — keep to 2 max")
+    if len(sizes_used) > 6:
+        warnings.append(f"Many font sizes used ({len(sizes_used)}) — consider a tighter typography scale")
+
+    if max_consecutive_empty > 2:
+        warnings.append(f"Found {max_consecutive_empty} consecutive empty paragraphs — use spacing instead")
+
+    if heading_count == 0 and paragraph_count > 10:
+        warnings.append("No headings found in a long document — add headings for structure")
+
+    # ── Summary ──
+    info.append(f"Paragraphs: {paragraph_count}")
+    info.append(f"Headings: {heading_count}")
+    info.append(f"Tables: {len(doc.tables)}")
+    info.append(f"Sections: {len(doc.sections)}")
+    info.append(f"Fonts: {', '.join(sorted(fonts_used)) if fonts_used else 'default only'}")
+
+    # ── Report ──
+    print(f"\n{'═' * 50}")
+    print(f"  Document Validation: {os.path.basename(path)}")
+    print(f"{'═' * 50}\n")
+
+    for i in info:
+        print(f"  ℹ  {i}")
+    print()
 
     if issues:
-        print("Validation failed:")
+        print(f"  ✖  {len(issues)} ISSUE(S):")
         for issue in issues:
-            print(f"- {issue}")
-        return 1
+            print(f"     • {issue}")
+        print()
 
     if warnings:
-        print("Validation warnings:")
-        for warning in warnings:
-            print(f"- {warning}")
-        return 0
+        print(f"  ⚠  {len(warnings)} WARNING(S):")
+        for w in warnings:
+            print(f"     • {w}")
+        print()
 
-    print("Validation passed: no issues found")
-    return 0
+    if not issues and not warnings:
+        print("  ✔  No issues found — document looks clean!\n")
+        return 0
+    elif not issues:
+        print("  ✔  No critical issues (warnings only)\n")
+        return 0
+    else:
+        print(f"  ✖  {len(issues)} issue(s) need fixing\n")
+        return 1
 
 
 if __name__ == "__main__":

package/skills/pptx/SKILL.md

@@ -1,24 +1,181 @@
 ---
-name: pptx
-description: "Create professional, polished slide decks using a deterministic PptxGenJS script. Trigger for presentation, slides, deck, and .pptx requests."
-license: Proprietary. LICENSE.txt has complete terms
+name: pro-slides
+description: "Create professional, visually polished slide decks — pitch decks, board updates, keynotes, team presentations, and sales decks. Use this skill whenever the user wants to create a presentation, slide deck, pitch deck, keynote, or slides. Also trigger when someone says 'make me a deck', 'create a presentation', 'build slides', 'pitch deck', 'board update deck', or needs any visual presentation deliverable. Trigger for 'pptx', 'powerpoint', 'slides', 'deck', 'presentation'."
 ---
 
-# Pro Slides for PPTX
+# Pro Slides — Professional Presentation Creation
 
-Use the scripted path:
+This skill creates polished slide decks using PptxGenJS, a powerful JavaScript presentation engine. It generates visually designed presentations with consistent color themes, typography, spacing, and data visualization — not plain text slides.
 
+## Quick Reference
+
+| Task | Documentation | Command |
+|------|---|---|
+| **Analyze existing presentation** | — | `python -m markitdown presentation.pptx` |
+| **Edit slides from a template** | Read `editing.md` | Unpack → Edit → Pack |
+| **Create presentation from scratch** | Read `pptxgenjs.md` | Write PptxGenJS code inline |
+| **Convert to images for QA** | See QA section | `soffice --headless --convert-to pdf output.pptx && pdftoppm -jpeg -r 150 output.pdf slide` |
+
+## Design-First Approach
+
+**Do not create boring slides.** The difference between great presentations and forgettable ones comes down to deliberate design choices: color, contrast, hierarchy, and visual consistency.
+
+### Before Starting
+
+Before writing any code, make these decisions:
+
+1. **Pick a bold color palette** — Don't default to blue. Match the topic. Sustainability reports should feel natural (greens). Sales decks should feel urgent (warm reds/oranges). Finance should feel trustworthy (teals/navy). See palette table below.
+
+2. **Establish visual dominance** — Don't create visual equality between elements. One color should dominate 60-70% of the slides (usually the accent color in callouts and key numbers). Everything else recedes.
+
+3. **Design the contrast sandwich** — Title slides and closing slides have dark backgrounds with light text. Content slides have light backgrounds with dark text. This creates visual rhythm and keeps viewers engaged.
+
+4. **Commit to a visual motif** — Every slide should have at least one deliberate visual element: an accent bar, a stat card with color, an icon, or a highlighted quote. No empty slides.
+
+### Color Palettes
+
+Choose one palette for the entire deck. Consistency beats variety.
+
+| Palette Name | Primary | Secondary | Accent | Best For |
+|---|---|---|---|---|
+| **Midnight Executive** | `1E2761` | `CADCFC` | `F5A623` | Board decks, investor pitches, formal settings |
+| **Forest & Moss** | `2C5F2D` | `97BC62` | `F5F5F5` | Sustainability, growth, environmental topics |
+| **Coral Energy** | `F96167` | `F9E795` | `2F3C7E` | Marketing, launches, startups, excitement |
+| **Warm Terracotta** | `B85042` | `E7E8D1` | `A7BEAE` | Culture, HR, team building, warmth |
+| **Ocean Gradient** | `065A82` | `1C7293` | `21295C` | Tech, product, data, trustworthiness |
+| **Charcoal Minimal** | `36454F` | `F2F2F2` | `212121` | Design, minimal aesthetics, agency work |
+| **Teal Trust** | `028090` | `00A896` | `02C39A` | Healthcare, finance, security, reliability |
+| **Cherry Bold** | `990011` | `FCF6F5` | `2F3C7E` | Sales, urgency, high-stakes decisions |
+
+### For Each Slide: Design Checklist
+
+Every content slide needs visual structure. Choose from these approaches:
+
+**Layout Options:**
+- **Two-column layout** — Left text, right callout. Left bullets, right image. Left data, right quote.
+- **Icon + text rows** — Small icons on left, supporting text on right. Great for feature lists or process steps.
+- **2x2 grid** — Four quadrants for options, scenarios, or related concepts.
+- **Half-bleed image** — Image on right, text on left. Image extends to slide edge for drama.
+- **Large stat + context** — Big number top-center, supporting bullets below.
+
+**Data Display:**
+- **Large stat callouts** — Use color (from palette accent). 60pt numbers, 12pt labels.
+- **Comparison columns** — Two cards, one accent color each, bullets inside.
+- **Timeline** — Vertical or horizontal bars with milestones.
+- **Simple table** — Only 2-3 columns. Striped rows for readability.
+
+**Visual Polish:**
+- **Icons in circles** — Accent color background, white icons inside.
+- **Italic accents** — Key phrases in italic to break up text uniformity.
+- **Subtle shadows** — Cards have soft drop shadows (blur 6, offset 2, opacity 0.08).
+- **Accent bars** — Thin colored rectangles (0.06 inches) above card titles.
+- **Breathing room** — 0.5" margins minimum. 0.3-0.5" gap between content blocks.
+
+### Typography
+
+Use one font pairing for the entire deck. Consistency.
+
+| Pairing | Heading Font | Body Font | Best For |
+|---|---|---|---|
+| Professional | Arial Black | Arial | Corporate, finance, formal |
+| Friendly | Trebuchet | Calibri | Tech, startups, modern |
+| Classic | Georgia | Calibri | Editorial, thoughtful content |
+| Modern | Arial Black | Helvetica | Design, tech, minimal |
+
+**Size Guide:**
+- Slide titles: 20pt (content slides) or 28pt (section slides)
+- Section headings: 18pt
+- Body text: 14pt
+- Captions / footnotes: 10-11pt
+- Stat numbers: 60pt
+- Stat labels: 12pt
+
+**Spacing:**
+- 0.5" minimum margins on all sides
+- 0.3-0.5" vertical gap between content blocks
+- Never center body text (left-align only)
+- Use `paraSpaceAfter: 6` for bullet spacing, never `lineSpacing`
+
+### 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.
+- **Don't center body text** — Always left-align body copy. Centers work only for titles, stats, and closing slides.
+- **Don't skimp on size contrast** — If you have a headline and body text, the headline must be significantly larger (at least 1.4x). Avoid small variations that create visual confusion.
+- **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.
+
+## QA Process
+
+**Assume there are problems. Your job is to find them.**
+
+The QA process is not optional. It's the difference between generating slides and delivering presentation-ready decks.
+
+### Content QA
+
+After generation, extract and verify the text:
 ```bash
-npm install -g pptxgenjs 2>/dev/null
-node scripts/create_pptx.js spec.json output.pptx
+python -m markitdown output.pptx > extracted.txt
 ```
+Check:
+- All intended content is present
+- No text truncation or overflow
+- No garbled Unicode or smart quotes breaking bullets
+- Slide order matches the intended narrative
+- Speaker notes are complete
 
-Use `references/spec-format.md` for slide schema and themes.
-
-Recommended QA:
+### Visual QA
 
+Convert to images and inspect with your eyes:
 ```bash
-python -m markitdown output.pptx
-python scripts/office/soffice.py --headless --convert-to pdf output.pptx
+soffice --headless --convert-to pdf output.pptx
 pdftoppm -jpeg -r 150 output.pdf slide
 ```
+
+This generates `slide-1.jpg`, `slide-2.jpg`, etc. Open each image and check:
+- **Text overflow** — Is any text cut off at slide edges?
+- **Element overlap** — Are shapes, text, or images on top of each other?
+- **Spacing consistency** — Do margins and gaps look balanced?
+- **Color contrast** — Can you read all text easily? Light text on light background?
+- **Missing elements** — Should there be an icon, image, or accent color that's not there?
+- **Typography** — Do font sizes and weights feel right?
+- **Alignment** — Are elements left-aligned where they should be?
+
+### Verification Loop
+
+1. **Generate** — Write PptxGenJS code, save presentation
+2. **Convert** — Run soffice + pdftoppm to get images
+3. **Inspect** — Open slide images in an image viewer
+4. **Fix** — Identify problems and update the code
+5. **Re-verify** — Regenerate and check again
+6. **Repeat** — Continue until at least one fix-and-verify cycle is complete
+
+**Do not declare success until you've completed at least one fix-and-verify cycle.** Even a "simple" request often has spacing issues, contrast problems, or missing visual elements that only appear when you see the actual slides.
+
+## Dependencies
+
+- **Node.js** (for running PptxGenJS)
+- **pptxgenjs** — JavaScript presentation generation library
+- **Python** with `markitdown` — For text extraction and QA
+- **LibreOffice** (`soffice`) — For PDF conversion
+- **pdftoppm** — For PDF to image conversion (part of poppler-utils)
+
+Installation (first time only):
+```bash
+npm install -g pptxgenjs
+pip install markitdown
+apt-get install libreoffice poppler-utils  # Linux
+brew install libreoffice poppler  # macOS
+```
+
+## Workflow Summary
+
+1. **Understand** — Who, what, how long?
+2. **Design** — Pick a palette, decide on visual approach, sketch slide structure
+3. **Write** — Create PptxGenJS code inline (see `pptxgenjs.md`)
+4. **Generate** — Save .pptx file
+5. **Convert** — Create .jpg images for visual inspection
+6. **Inspect** — Open images, look for problems
+7. **Fix** — Update code based on findings
+8. **Re-verify** — Regenerate and confirm fixes
+9. **Deliver** — Provide final .pptx to user