@nguyenphp/antigravity-marketing 1.0.18 → 1.0.20

package/templates/.agent/skills/pptx-generator/references/design-system.md

@@ -0,0 +1,392 @@
+# Design System
+
+## Color Palette Reference
+
+| # | Name | Colors | Style | Use Cases | Tips |
+|---|------|--------|-------|-----------|------|
+| 1 | Modern & Wellness | `#006d77` `#83c5be` `#edf6f9` `#ffddd2` `#e29578` | Fresh, soothing | Healthcare, counseling, skincare, yoga/spa | Deep teal for titles, light pink for background |
+| 2 | Business & Authority | `#2b2d42` `#8d99ae` `#edf2f4` `#ef233c` `#d90429` | Formal, classic | Annual reports, financial analysis, corporate intro, government | Deep blue for professionalism, bright red to highlight data |
+| 3 | Nature & Outdoors | `#606c38` `#283618` `#fefae0` `#dda15e` `#bc6c25` | Grounded, earthy | Outdoor gear, environmental, agriculture, historical culture | Dark green base, cream text |
+| 4 | Vintage & Academic | `#780000` `#c1121f` `#fdf0d5` `#003049` `#669bbc` | Classic, scholarly | Academic lectures, history reviews, museums, heritage brands | Strong contrast between deep red and deep blue |
+| 5 | Soft & Creative | `#cdb4db` `#ffc8dd` `#ffafcc` `#bde0fe` `#a2d2ff` | Dreamy, candy-toned | Mother & baby, desserts, women's fashion, kindergarten | Use dark gray or black for text |
+| 6 | Bohemian | `#ccd5ae` `#e9edc9` `#fefae0` `#faedcd` `#d4a373` | Gentle, muted | Wedding planning, home decor, organic food, slow living | Cream background, green-brown accents |
+| 7 | Vibrant & Tech | `#8ecae6` `#219ebc` `#023047` `#ffb703` `#fb8500` | High energy, sporty | Sports events, gyms, startup pitches, youth education | Deep blue for stability, orange as focal accent |
+| 8 | Craft & Artisan | `#7f5539` `#a68a64` `#ede0d4` `#656d4a` `#414833` | Rustic, coffee-toned | Coffee shops, handicrafts, traditional culture, bakery | Suited for paper/leather textures |
+| 9 | Tech & Night | `#000814` `#001d3d` `#003566` `#ffc300` `#ffd60a` | Deep, luminous | Tech launches, astronomy, night economy, luxury automobiles | Must use dark mode |
+| 10 | Education & Charts | `#264653` `#2a9d8f` `#e9c46a` `#f4a261` `#e76f51` | Clear, logical | Statistical reports, education, market analysis, general business | Perfect chart color scheme |
+| 11 | Forest & Eco | `#dad7cd` `#a3b18a` `#588157` `#3a5a40` `#344e41` | Monochrome gradient, forest | Landscape design, ESG reports, environmental causes, botanical | Monochrome palette is safe and cohesive |
+| 12 | Elegant & Fashion | `#edafb8` `#f7e1d7` `#dedbd2` `#b0c4b1` `#4a5759` | Muted, Morandi tones | Haute couture, art galleries, beauty brands, magazine style | Negative space is key |
+| 13 | Art & Food | `#335c67` `#fff3b0` `#e09f3e` `#9e2a2b` `#540b0e` | Rich, vintage-poster | Food documentaries, art exhibitions, ethnic themes, vintage restaurants | Works well with large color blocks |
+| 14 | Luxury & Mysterious | `#22223b` `#4a4e69` `#9a8c98` `#c9ada7` `#f2e9e4` | Cool, purple-toned | Jewelry showcases, hotel management, high-end consulting, psychology | Purple evokes premium atmosphere |
+| 15 | Pure Tech Blue | `#03045e` `#0077b6` `#00b4d8` `#90e0ef` `#caf0f8` | Futuristic, clean | Cloud/AI, water/ocean, hospitals, clean energy | Deep ocean to sky gradient |
+| 16 | Coastal Coral | `#0081a7` `#00afb9` `#fdfcdc` `#fed9b7` `#f07167` | Refreshing, summery | Travel, summer events, beverage brands, ocean themes | Teal and coral as complementary focal colors |
+| 17 | Vibrant Orange Mint | `#ff9f1c` `#ffbf69` `#ffffff` `#cbf3f0` `#2ec4b6` | Bright, cheerful | Children's events, promotional posters, FMCG, social media | Orange grabs attention, mint feels fresh |
+| 18 | Platinum White Gold | `#0a0a0a` `#0070F3` `#D4AF37` `#f5f5f5` `#ffffff` | Premium, professional | Agent products, corporate websites, fintech, luxury brands | White-gold base, blue for action, gold for emphasis |
+
+---
+
+### Agent Design System — Full Color Scale
+
+Based on the Platinum White-Gold Theme design tokens. Provides complete color scales for fine-grained design work.
+
+#### White Scale (Backgrounds & Light Surfaces)
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| white-0 | `#ffffff` | Primary background |
+| white-50 | `#fefefe` | Slightly warm white |
+| white-75 | `#fcfcfc` | Near-white |
+| white-100 | `#fafafa` | Secondary background |
+| white-200 | `#f7f7f7` | Card background |
+| white-300 | `#f5f5f5` | Tertiary background |
+| white-400 | `#f0f0f0` | Separator zones |
+| white-500 | `#ebebeb` | Light border |
+| white-600 | `#e5e5e5` | Disabled background |
+| white-700 | `#e0e0e0` | Deep white-gray |
+| white-800 | `#d9d9d9` | Placeholder |
+| white-900 | `#d4d4d4` | Divider lines |
+| white-1000 | `#cccccc` | Deepest white |
+
+#### Gold Scale (Platinum Business Accent)
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| gold-25 | `#FFFDF5` | Extremely light gold background |
+| gold-50 | `#FEF9E7` | Light gold background |
+| gold-75 | `#FCF3D0` | Pale gold highlight |
+| gold-100 | `#FAECB8` | Gold hover state |
+| gold-200 | `#F5DC8A` | Bright gold accent |
+| gold-300 | `#E8C860` | Gold hover |
+| gold-400 | `#D4AF37` | **Primary gold (core)** |
+| gold-500 | `#B8972E` | Gold text |
+| gold-600 | `#9A7E26` | Deep gold accent |
+| gold-700 | `#7C651E` | Dark gold border |
+| gold-800 | `#5E4C16` | Deep gold background |
+| gold-900 | `#40330F` | Very deep gold |
+| gold-1000 | `#221A08` | Black gold |
+
+#### Blue Scale (Primary Action Color)
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| blue-25 | `#F0F7FF` | Extremely light blue background |
+| blue-50 | `#E0EFFF` | Info alert background |
+| blue-75 | `#C2DFFF` | Light blue highlight |
+| blue-100 | `#A3CFFF` | Disabled blue |
+| blue-200 | `#66AFFF` | Bright blue |
+| blue-300 | `#338FFF` | Blue hover |
+| blue-400 | `#0070F3` | **Primary blue (core)** |
+| blue-500 | `#005FCC` | Blue text |
+| blue-600 | `#004FA6` | Deep blue accent |
+| blue-700 | `#003F80` | Dark blue border |
+| blue-800 | `#002F5A` | Deep blue background |
+| blue-900 | `#001F3D` | Very deep blue |
+| blue-1000 | `#001026` | Black blue |
+
+#### Gray Scale (Text & Neutral Colors)
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| gray-0 | `#ffffff` | White |
+| gray-50 | `#fafafa` | Extremely light gray |
+| gray-75 | `#f5f5f5` | Light gray background |
+| gray-100 | `#ededed` | Light divider |
+| gray-200 | `#d4d4d4` | Light border |
+| gray-300 | `#a3a3a3` | Quaternary text |
+| gray-400 | `#737373` | Tertiary text |
+| gray-500 | `#525252` | Secondary text |
+| gray-600 | `#404040` | Dark gray |
+| gray-700 | `#2e2e2e` | Dark background |
+| gray-800 | `#1f1f1f` | Deep background |
+| gray-900 | `#141414` | Very deep background |
+| gray-1000 | `#0a0a0a` | **Primary text (core)** |
+
+#### Opacity Values
+
+##### Opacity Black
+
+| Opacity | Value | Usage |
+|---------|-------|-------|
+| 0% | `#0a0a0a00` | Fully transparent |
+| 2% | `#0a0a0a05` | Subtle overlay |
+| 4% | `#0a0a0a0a` | Secondary interactive background |
+| 8% | `#0a0a0a14` | Border / divider |
+| 15% | `#0a0a0a26` | Pressed state |
+| 20% | `#0a0a0a33` | Light overlay |
+| 25% | `#0a0a0a40` | Medium overlay |
+| 50% | `#0a0a0a80` | Semi-transparent |
+| 70% | `#0a0a0ab2` | Deep overlay |
+| 80% | `#0a0a0acc` | Hover state |
+| 90% | `#0a0a0ae5` | Tooltip |
+| 95% | `#0a0a0af2` | Modal |
+
+##### Opacity White
+
+| Opacity | Value | Usage |
+|---------|-------|-------|
+| 0% | `#ffffff00` | Fully transparent |
+| 2% | `#ffffff05` | Subtle overlay |
+| 4% | `#ffffff0a` | Secondary interactive background |
+| 8% | `#ffffff12` | Border / divider |
+| 15% | `#ffffff26` | Pressed state |
+| 20% | `#ffffff33` | Light overlay |
+| 25% | `#ffffff40` | Medium overlay |
+| 50% | `#ffffff80` | Semi-transparent |
+| 70% | `#ffffffb2` | Deep overlay |
+| 80% | `#ffffffcc` | Hover state |
+| 90% | `#ffffffe5` | Tooltip |
+| 95% | `#fffffff2` | Modal |
+
+---
+
+## Color Palette Rules (MANDATORY)
+
+### Strict Palette Adherence
+
+**Use ONLY the provided color palette. Do NOT create or modify colors.**
+
+- All colors must come from the user-provided palette
+- Do NOT use colors outside the palette
+- Do NOT modify palette colors (brightness, saturation, mixing)
+- **Only exception**: Add transparency using the `transparency` property (0-100)
+
+```javascript
+// Correct: Using palette colors
+slide.addShape(pres.shapes.RECTANGLE, { fill: { color: theme.primary } });
+slide.addText("Title", { color: theme.accent });
+
+// Wrong: Colors outside palette
+slide.addShape(pres.shapes.RECTANGLE, { fill: { color: "1a1a2e" } });
+```
+
+### No Gradients
+
+**Gradients are prohibited. Use solid colors only.**
+
+### No Animations
+
+**Animations and transitions are prohibited.** All slides must be static.
+
+---
+
+## Font Reference
+
+### Recommended Fonts
+
+| Language | Default Font | Alternatives |
+|----------|-------------|--------------|
+| **Chinese** | Microsoft YaHei | — |
+| **English** | Arial | Georgia, Calibri, Cambria, Trebuchet MS |
+
+- For mixed Chinese-English content: use Microsoft YaHei for Chinese, the chosen font for English
+- Prefer system fonts for cross-platform compatibility
+- Titles and body text can use different font pairings (e.g. Georgia + Calibri)
+
+### Recommended Font Pairings
+
+| Header Font | Body Font |
+|-------------|-----------|
+| Georgia | Calibri |
+| Arial Black | Arial |
+| Calibri | Calibri Light |
+| Cambria | Calibri |
+| Trebuchet MS | Calibri |
+| Impact | Arial |
+| Palatino | Garamond |
+| Consolas | Calibri |
+
+**Choose an interesting font pairing** — don't default to Arial for everything. Pick a header font with personality and pair it with a clean body font.
+
+### No Bold for Body Text
+
+**Plain body text and caption/legend text must NOT use bold.**
+
+- Body paragraphs, descriptions → normal weight
+- Captions, legends, footnotes → normal weight
+- Reserve bold for titles and headings only
+
+```javascript
+// Correct
+slide.addText("Main Title", { bold: true, fontSize: 36, fontFace: "Arial" });
+slide.addText("Body text here.", { bold: false, fontSize: 14, fontFace: "Arial" });
+
+// Wrong
+slide.addText("Body text here.", { bold: true, fontSize: 14 });
+```
+
+---
+
+## Style Recipes
+
+The same design can be rendered in 4 distinct visual styles by adjusting corner radius (`rectRadius`) and spacing. Choose the style recipe that fits the presentation tone.
+
+> **Unit note**: PptxGenJS uses inches. Slide dimensions are 10" x 5.625" (LAYOUT_16x9).
+
+### Style Overview
+
+| Style | Corner Radius | Spacing | Best For |
+|-------|--------------|---------|----------|
+| **Sharp & Compact** | 0 ~ 0.05" | Tight | Data-dense, tables, professional reports |
+| **Soft & Balanced** | 0.08" ~ 0.12" | Moderate | Corporate, business presentations, general use |
+| **Rounded & Spacious** | 0.15" ~ 0.25" | Relaxed | Product intros, marketing, creative showcases |
+| **Pill & Airy** | 0.3" ~ 0.5" | Open | Brand showcases, launch events, premium presentations |
+
+### Sharp & Compact
+
+**Visual character**: Geometric, high information density, formal and serious.
+
+| Category | Value (inches) | Notes |
+|----------|---------------|-------|
+| Corner radius — small | 0" | Full right angle |
+| Corner radius — medium | 0.03" | Micro-rounded |
+| Corner radius — large | 0.05" | Slight rounding |
+| Element padding | 0.1" ~ 0.15" | Compact |
+| Element gap | 0.1" ~ 0.2" | Compact |
+| Page margin | 0.3" | Narrow |
+| Block gap | 0.25" ~ 0.35" | Compact |
+
+### Soft & Balanced
+
+**Visual character**: Moderate rounding, comfortable whitespace, professional yet approachable.
+
+| Category | Value (inches) | Notes |
+|----------|---------------|-------|
+| Corner radius — small | 0.05" | Slight rounding |
+| Corner radius — medium | 0.08" | Medium rounding |
+| Corner radius — large | 0.12" | Larger rounding |
+| Element padding | 0.15" ~ 0.2" | Moderate |
+| Element gap | 0.15" ~ 0.25" | Moderate |
+| Page margin | 0.4" | Standard |
+| Block gap | 0.35" ~ 0.5" | Moderate |
+
+### Rounded & Spacious
+
+**Visual character**: Large corners, generous whitespace, friendly and modern.
+
+| Category | Value (inches) | Notes |
+|----------|---------------|-------|
+| Corner radius — small | 0.1" | Medium rounding |
+| Corner radius — medium | 0.15" | Large rounding |
+| Corner radius — large | 0.25" | Very large rounding |
+| Element padding | 0.2" ~ 0.3" | Relaxed |
+| Element gap | 0.25" ~ 0.4" | Relaxed |
+| Page margin | 0.5" | Wide |
+| Block gap | 0.5" ~ 0.7" | Relaxed |
+
+### Pill & Airy
+
+**Visual character**: Full pill-shaped corners, abundant whitespace, light and open feel, strong brand presence.
+
+| Category | Value (inches) | Notes |
+|----------|---------------|-------|
+| Corner radius — small | 0.2" | Large rounding |
+| Corner radius — medium | 0.3" | Pill shape |
+| Corner radius — large | 0.5" | Full pill |
+| Element padding | 0.25" ~ 0.4" | Open |
+| Element gap | 0.3" ~ 0.5" | Open |
+| Page margin | 0.6" | Wide |
+| Block gap | 0.6" ~ 0.9" | Open |
+
+### Component Style Mapping
+
+| Component | Sharp | Soft | Rounded | Pill |
+|-----------|-------|------|---------|------|
+| **Button / Tag** | rectRadius: 0 | rectRadius: 0.05 | rectRadius: 0.1 | rectRadius: 0.2 |
+| **Card / Container** | rectRadius: 0.03 | rectRadius: 0.1 | rectRadius: 0.2 | rectRadius: 0.3 |
+| **Image Container** | rectRadius: 0 | rectRadius: 0.08 | rectRadius: 0.15 | rectRadius: 0.25 |
+| **Input Field** | rectRadius: 0 | rectRadius: 0.05 | rectRadius: 0.1 | rectRadius: 0.2 |
+| **Badge** | rectRadius: 0.02 | rectRadius: 0.05 | rectRadius: 0.08 | rectRadius: 0.15 |
+| **Avatar Frame** | rectRadius: 0 | rectRadius: 0.1 | rectRadius: 0.2 | rectRadius: 0.5 (circle) |
+
+#### PptxGenJS Corner Radius Examples
+
+```javascript
+// Sharp style card
+slide.addShape("rect", {
+  x: 0.5, y: 1, w: 4, h: 2.5,
+  fill: { color: "F5F5F5" },
+  rectRadius: 0.03
+});
+
+// Rounded style card
+slide.addShape("rect", {
+  x: 0.5, y: 1, w: 4, h: 2.5,
+  fill: { color: "F5F5F5" },
+  rectRadius: 0.2
+});
+
+// Pill style button (height 0.4", rectRadius 0.2" = perfect pill)
+slide.addShape("rect", {
+  x: 3, y: 4, w: 2, h: 0.4,
+  fill: { color: "4A90D9" },
+  rectRadius: 0.2
+});
+```
+
+### Mixing Rules
+
+#### 1. Outer container corner >= inner element corner
+
+```javascript
+// Correct: outer > inner
+card:   rectRadius: 0.2
+button: rectRadius: 0.1
+
+// Wrong: inner > outer → visual overflow effect
+card:   rectRadius: 0.1
+button: rectRadius: 0.2
+```
+
+#### 2. Information density drives spacing
+
+| Zone Type | Recommended Style |
+|-----------|------------------|
+| Data display zone | Sharp / Soft (compact spacing) |
+| Content browsing zone | Rounded / Pill (relaxed spacing) |
+| Title zone | Soft / Rounded (moderate spacing) |
+
+#### 3. Corner radius vs element height
+
+| Element Height | Sharp | Soft | Rounded | Pill |
+|---------------|-------|------|---------|------|
+| Small (< 0.3") | 0" | 0.03" | 0.08" | height/2 |
+| Medium (0.3" ~ 0.6") | 0.02" | 0.05" | 0.12" | height/2 |
+| Large (0.6" ~ 1.2") | 0.03" | 0.08" | 0.2" | 0.3" |
+| Extra large (> 1.2") | 0.05" | 0.12" | 0.25" | 0.4" |
+
+> **Pill tip**: For a perfect pill shape, set `rectRadius = element height / 2`
+
+### Typography Scale (PPT)
+
+| Usage | Size (pt) | Notes |
+|-------|-----------|-------|
+| Annotations / Sources | 10 ~ 12 | Minimum readable size |
+| Body / Description | 14 ~ 16 | Standard body |
+| Subtitle | 18 ~ 22 | Secondary heading |
+| Title | 28 ~ 36 | Page title |
+| Large Title | 44 ~ 60 | Cover / section title |
+| Data Callout | 60 ~ 96 | Key number display |
+
+### Spacing Scale (PPT)
+
+Based on 10" x 5.625" slide dimensions:
+
+| Usage | Recommended (inches) |
+|-------|---------------------|
+| Icon-to-text gap | 0.08" ~ 0.15" |
+| List item spacing | 0.15" ~ 0.25" |
+| Card inner padding | 0.2" ~ 0.4" |
+| Element group gap | 0.3" ~ 0.5" |
+| Page safe margin | 0.4" ~ 0.6" |
+| Major block gap | 0.5" ~ 0.8" |
+
+### Quick Selection Guide
+
+| Presentation Type | Recommended Style | Reason |
+|------------------|------------------|--------|
+| Finance / Data reports | Sharp & Compact | High density, serious and precise |
+| Corporate / Business | Soft & Balanced | Balances professionalism and approachability |
+| Product intro / Marketing | Rounded & Spacious | Modern feel, friendly |
+| Launch events / Brand | Pill & Airy | Premium feel, visual impact |
+| Training / Education | Soft / Rounded | Clear, readable, friendly |
+| Tech sharing | Sharp / Soft | Professional, information-dense |

package/templates/.agent/skills/pptx-generator/references/editing.md

@@ -0,0 +1,162 @@
+# Editing Existing Presentations
+
+## Template-Based Workflow
+
+When using an existing presentation as a template:
+
+1. **Copy and analyze**:
+   ```bash
+   cp /path/to/user-provided.pptx template.pptx
+   python -m markitdown template.pptx > template.md
+   ```
+   Review `template.md` to see placeholder text and slide structure.
+
+2. **Plan slide mapping**: For each content section, choose a template slide.
+
+   **USE VARIED LAYOUTS** — monotonous presentations are a common failure mode. Don't default to basic title + bullet slides. Actively seek out:
+   - Multi-column layouts (2-column, 3-column)
+   - Image + text combinations
+   - Full-bleed images with text overlay
+   - Quote or callout slides
+   - Section dividers
+   - Stat/number callouts
+   - Icon grids or icon + text rows
+
+   **Avoid:** Repeating the same text-heavy layout for every slide.
+
+   Match content type to layout style (e.g., key points -> bullet slide, team info -> multi-column, testimonials -> quote slide).
+
+3. **Unpack**: Extract the PPTX into an editable XML tree using Python's `zipfile` module. Pretty-print the XML for readability.
+
+4. **Build presentation** (do this yourself, not with subagents):
+   - Delete unwanted slides (remove from `<p:sldIdLst>`)
+   - Duplicate slides you want to reuse (copy slide XML, relationships, and update `Content_Types.xml` and `presentation.xml`)
+   - Reorder slides in `<p:sldIdLst>`
+   - **Complete all structural changes before step 5**
+
+5. **Edit content**: Update text in each `slide{N}.xml`.
+   **Use subagents here if available** — slides are separate XML files, so subagents can edit in parallel.
+
+6. **Clean**: Remove orphaned files — slides not in `<p:sldIdLst>`, unreferenced media, orphaned rels.
+
+7. **Pack**: Repack the XML tree into a PPTX file. Validate, repair, condense XML, re-encode smart quotes.
+
+   Always write to `/tmp/` first, then copy to the final path. Python's `zipfile` module uses `seek` internally, which fails on some volume mounts (e.g. Docker bind mounts). Writing to a local temp path avoids this.
+
+## Output Structure
+
+Copy the user-provided file to `template.pptx` in cwd. This preserves the original and gives a predictable name for all downstream operations.
+
+```bash
+cp /path/to/user-provided.pptx template.pptx
+```
+
+```text
+./
+├── template.pptx               # Copy of user-provided file (never modified)
+├── template.md                 # markitdown extraction
+├── unpacked/                   # Editable XML tree
+└── edited.pptx                 # Final repacked deck
+```
+
+Minimum expected deliverable: `edited.pptx`.
+
+## Slide Operations
+
+Slide order is in `ppt/presentation.xml` -> `<p:sldIdLst>`.
+
+**Reorder**: Rearrange `<p:sldId>` elements.
+
+**Delete**: Remove `<p:sldId>`, then clean orphaned files.
+
+**Add**: Copy the source slide's XML file, its `.rels` file, and update `Content_Types.xml` and `presentation.xml`. Never manually copy slide files without updating all references — this causes broken notes references and missing relationship IDs.
+
+## Editing Content
+
+**Subagents:** If available, use them here (after completing step 4). Each slide is a separate XML file, so subagents can edit in parallel. In your prompt to subagents, include:
+- The slide file path(s) to edit
+- **"Use the Edit tool for all changes"**
+- The formatting rules and common pitfalls below
+
+For each slide:
+1. Read the slide's XML
+2. Identify ALL placeholder content — text, images, charts, icons, captions
+3. Replace each placeholder with final content
+
+**Use the Edit tool, not sed or Python scripts.** The Edit tool forces specificity about what to replace and where, yielding better reliability.
+
+## Formatting Rules
+
+- **Bold all headers, subheadings, and inline labels**: Use `b="1"` on `<a:rPr>`. This includes:
+  - Slide titles
+  - Section headers within a slide
+  - Inline labels like (e.g.: "Status:", "Description:") at the start of a line
+- **Never use unicode bullets**: Use proper list formatting with `<a:buChar>` or `<a:buAutoNum>`
+- **Bullet consistency**: Let bullets inherit from the layout. Only specify `<a:buChar>` or `<a:buNone>`.
+
+## Common Pitfalls — Template Editing
+
+### Template Adaptation
+
+When source content has fewer items than the template:
+- **Remove excess elements entirely** (images, shapes, text boxes), don't just clear text
+- Check for orphaned visuals after clearing text content
+- Run content QA with `markitdown` to catch mismatched counts
+
+When replacing text with different length content:
+- **Shorter replacements**: Usually safe
+- **Longer replacements**: May overflow or wrap unexpectedly
+- Verify with `markitdown` after text changes
+- Consider truncating or splitting content to fit the template's design constraints
+
+**Template slots != Source items**: If template has 4 team members but source has 3 users, delete the 4th member's entire group (image + text boxes), not just the text.
+
+### Multi-Item Content
+
+If source has multiple items (numbered lists, multiple sections), create separate `<a:p>` elements for each — **never concatenate into one string**.
+
+**WRONG** — all items in one paragraph:
+```xml
+<a:p>
+  <a:r><a:rPr .../><a:t>Step 1: Do the first thing. Step 2: Do the second thing.</a:t></a:r>
+</a:p>
+```
+
+**CORRECT** — separate paragraphs with bold headers:
+```xml
+<a:p>
+  <a:pPr algn="l"><a:lnSpc><a:spcPts val="3919"/></a:lnSpc></a:pPr>
+  <a:r><a:rPr lang="en-US" sz="2799" b="1" .../><a:t>Step 1</a:t></a:r>
+</a:p>
+<a:p>
+  <a:pPr algn="l"><a:lnSpc><a:spcPts val="3919"/></a:lnSpc></a:pPr>
+  <a:r><a:rPr lang="en-US" sz="2799" .../><a:t>Do the first thing.</a:t></a:r>
+</a:p>
+<a:p>
+  <a:pPr algn="l"><a:lnSpc><a:spcPts val="3919"/></a:lnSpc></a:pPr>
+  <a:r><a:rPr lang="en-US" sz="2799" b="1" .../><a:t>Step 2</a:t></a:r>
+</a:p>
+<!-- continue pattern -->
+```
+
+Copy `<a:pPr>` from the original paragraph to preserve line spacing. Use `b="1"` on headers.
+
+### Smart Quotes
+
+The Edit tool converts smart quotes to ASCII. **When adding new text with quotes, use XML entities:**
+
+```xml
+<a:t>the &#x201C;Agreement&#x201D;</a:t>
+```
+
+| Character | Name | Unicode | XML Entity |
+|-----------|------|---------|------------|
+| \u201c | Left double quote | U+201C | `&#x201C;` |
+| \u201d | Right double quote | U+201D | `&#x201D;` |
+| \u2018 | Left single quote | U+2018 | `&#x2018;` |
+| \u2019 | Right single quote | U+2019 | `&#x2019;` |
+
+### Other
+
+- **Whitespace**: Use `xml:space="preserve"` on `<a:t>` with leading/trailing spaces
+- **XML parsing**: Use `defusedxml.minidom`, not `xml.etree.ElementTree` (corrupts namespaces)

package/templates/.agent/skills/pptx-generator/references/pitfalls.md

@@ -0,0 +1,112 @@
+# QA Process & Common Pitfalls
+
+## QA Process
+
+**Assume there are problems. Your job is to find them.**
+
+Your first render is almost never correct. Approach QA as a bug hunt, not a confirmation step. If you found zero issues on first inspection, you weren't looking hard enough.
+
+### Content QA
+
+```bash
+python -m markitdown output.pptx
+```
+
+Check for missing content, typos, wrong order.
+
+**Check for leftover placeholder text:**
+
+```bash
+python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|placeholder|this.*(page|slide).*layout"
+```
+
+If grep returns results, fix them before declaring success.
+
+### Verification Loop
+
+1. Generate slides -> Extract text with `python -m markitdown output.pptx` -> Review content
+2. **List issues found** (if none found, look again more critically)
+3. Fix issues
+4. **Re-verify affected slides** — one fix often creates another problem
+5. Repeat until a full pass reveals no new issues
+
+**Do not declare success until you've completed at least one fix-and-verify cycle.**
+
+### Per-Slide QA (for from-scratch creation)
+
+```bash
+python -m markitdown slide-XX-preview.pptx
+```
+
+Check for missing content, placeholder text, missing page number badge.
+
+---
+
+## Common Mistakes to Avoid
+
+- **Don't repeat the same layout** — vary columns, cards, and callouts across slides
+- **Don't center body text** — left-align paragraphs and lists; center only titles
+- **Don't skimp on size contrast** — titles need 36pt+ to stand out from 14-16pt body
+- **Don't default to blue** — pick colors that reflect the specific topic
+- **Don't mix spacing randomly** — choose 0.3" or 0.5" gaps and use consistently
+- **Don't style one slide and leave the rest plain** — commit fully or keep it simple throughout
+- **Don't create text-only slides** — add images, icons, charts, or visual elements; avoid plain title + bullets
+- **Don't forget text box padding** — when aligning lines or shapes with text edges, set `margin: 0` on the text box or offset the shape to account for padding
+- **Don't use low-contrast elements** — icons AND text need strong contrast against the background
+- **NEVER use accent lines under titles** — these are a hallmark of AI-generated slides; use whitespace or background color instead
+- **NEVER use "#" with hex colors** — causes file corruption in PptxGenJS
+- **NEVER encode opacity in hex strings** — use the `opacity` property instead
+- **NEVER use async/await in createSlide()** — compile.js won't await
+- **NEVER reuse option objects across PptxGenJS calls** — PptxGenJS mutates objects in-place
+
+---
+
+## Critical Pitfalls — PptxGenJS
+
+### NEVER use async/await in createSlide()
+
+```javascript
+// WRONG - compile.js won't await
+async function createSlide(pres, theme) { ... }
+
+// CORRECT
+function createSlide(pres, theme) { ... }
+```
+
+### NEVER use "#" with hex colors
+
+```javascript
+color: "FF0000"      // CORRECT
+color: "#FF0000"     // CORRUPTS FILE
+```
+
+### NEVER encode opacity in hex strings
+
+```javascript
+shadow: { color: "00000020" }              // CORRUPTS FILE
+shadow: { color: "000000", opacity: 0.12 } // CORRECT
+```
+
+### Prevent text wrapping in titles
+
+```javascript
+// Use fit:'shrink' for long titles
+slide.addText("Long Title Here", {
+  x: 0.5, y: 2, w: 9, h: 1,
+  fontSize: 48, fit: "shrink"
+});
+```
+
+### NEVER reuse option objects across calls
+
+```javascript
+// WRONG
+const shadow = { type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 };
+slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });
+slide.addShape(pres.shapes.RECTANGLE, { shadow, ... });
+
+// CORRECT - factory function
+const makeShadow = () => ({ type: "outer", blur: 6, offset: 2, color: "000000", opacity: 0.15 });
+slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });
+slide.addShape(pres.shapes.RECTANGLE, { shadow: makeShadow(), ... });
+```