@xopcai/xopc 0.0.102 → 0.0.104

package/skills/documents/pptx/SKILL-zh.md

@@ -1,232 +0,0 @@
----
-name: pptx
-description: "在任何涉及 .pptx 文件的任务中使用本技能——无论是作为输入、输出或两者兼有。包括：创建幻灯片、路演文稿或演示文稿；读取、解析或从任何 .pptx 文件中提取文字（即使提取的内容将用于其他地方，如邮件或摘要）；编辑、修改或更新现有演示文稿；合并或拆分幻灯片文件；处理模板、布局、演讲者备注或批注。每当用户提到\"deck\"、\"slide\"、\"presentation\"或引用 .pptx 文件名时触发，无论他们之后打算如何处理内容。如果需要打开、创建或操作 .pptx 文件，请使用本技能。"
-license: 专有。完整条款见 LICENSE.txt
----
-
-# PPTX 技能
-
-## 快速参考
-
-| 任务 | 指南 |
-|------|------|
-| 读取/分析内容 | `python -m markitdown presentation.pptx` |
-| 编辑或从模板创建 | 阅读 [editing.md](editing.md) |
-| 从零创建 | 阅读 [pptxgenjs.md](pptxgenjs.md) |
-
----
-
-## 读取内容
-
-```bash
-# 文字提取
-python -m markitdown presentation.pptx
-
-# 视觉概览
-python scripts/thumbnail.py presentation.pptx
-
-# 原始 XML
-python scripts/office/unpack.py presentation.pptx unpacked/
-```
-
----
-
-## 编辑工作流
-
-**详细内容请阅读 [editing.md](editing.md)。**
-
-1. 使用 `thumbnail.py` 分析模板
-2. 解包 → 操作幻灯片 → 编辑内容 → 清理 → 打包
-
----
-
-## 从零创建
-
-**详细内容请阅读 [pptxgenjs.md](pptxgenjs.md)。**
-
-当没有模板或参考演示文稿时使用。
-
----
-
-## 设计思路
-
-**不要创建无聊的幻灯片。** 白底黑字的纯项目符号无法打动任何人。以下是每个幻灯片可参考的设计思路。
-
-### 开始之前
-
-- **选择大胆且与内容相关的配色方案**：配色应让你感觉是为这个特定主题设计的。如果换到完全不同的演示文稿仍能"正常工作"，说明你做的选择还不够具体。
-- **主次分明**：一种颜色应占主导（60-70% 的视觉权重），配以 1-2 种辅助色和一种锐利的点缀色。永远不要让所有颜色权重相同。
-- **明暗对比**：标题和结论幻灯片使用深色背景，内容页使用浅色（"三明治"结构）。或者全部使用深色以营造高级感。
-- **坚持视觉主题**：选择一个独特的元素并重复使用——圆角图片框、彩色圆圈内的图标、粗单侧边框。让它在每张幻灯片中贯穿始终。
-
-### 配色方案
-
-选择与主题匹配的颜色——不要默认使用通用蓝色。以下配色方案供参考：
-
-| 主题 | 主色 | 辅助色 | 点缀色 |
-|------|------|--------|--------|
-| **午夜行政风** | `1E2761`（深蓝） | `CADCFC`（冰蓝） | `FFFFFF`（白） |
-| **森林苔藓** | `2C5F2D（森林绿）` | `97BC62`（苔藓绿） | `F5F5F5`（奶油色） |
-| **珊瑚能量** | `F96167`（珊瑚） | `F9E795`（金色） | `2F3C7E`（深蓝） |
-| **暖陶土** | `B85042`（陶土） | `E7E8D1`（沙色） | `A7BEAE`（鼠尾草） |
-| **海洋渐变** | `065A82`（深蓝） | `1C7293`（青绿） | `21295C`（午夜蓝） |
-| **炭灰极简** | `36454F`（炭灰） | `F2F2F2`（米白） | `212121`（黑） |
-| **青绿信任** | `028090`（青绿） | `00A896`（海沫） | `02C39A`（薄荷） |
-| **浆果奶油** | `6D2E46`（浆果红） | `A26769`（灰粉） | `ECE2D0`（奶油色） |
-| **鼠尾草宁静** | `84B59F`（鼠尾草） | `69A297`（桉树绿） | `50808E`（石板灰） |
-| **樱桃大胆** | `990011`（樱桃红） | `FCF6F5`（米白） | `2F3C7E`（深蓝） |
-
-### 每张幻灯片
-
-**每张幻灯片都需要一个视觉元素**——图片、图表、图标或形状。纯文字幻灯片很容易被遗忘。
-
-**布局选项：**
-- 两栏（左文字，右图示）
-- 图标+文字行（彩色圆圈中的图标、粗体标题、下方描述）
-- 2x2 或 2x3 网格（一侧图片，另一侧内容块网格）
-- 半出血图片（整左侧或右侧）配合内容叠加
-
-**数据显示：**
-- 大号数据标注（大字 60-72pt，下方小号标签）
-- 对比栏（前后对比、优缺点、并列选项）
-- 时间线或流程（编号步骤、箭头）
-
-**视觉润色：**
-- 章节标题旁的小型彩色圆图标
-- 关键统计或标语用斜体点缀文字
-
-### 字体排印
-
-**选择有趣的字体搭配**——不要默认使用 Arial。选择有特色的标题字体，搭配清晰的正文字体。
-
-| 标题字体 | 正文字体 |
-|----------|----------|
-| Georgia | Calibri |
-| Arial Black | Arial |
-| Calibri | Calibri Light |
-| Cambria | Calibri |
-| Trebuchet MS | Calibri |
-| Impact | Arial |
-| Palatino | Garamond |
-| Consolas | Calibri |
-
-| 元素 | 字号 |
-|------|------|
-| 幻灯片标题 | 36-44pt 粗体 |
-| 章节标题 | 20-24pt 粗体 |
-| 正文 | 14-16pt |
-| 说明文字 | 10-12pt 浅色 |
-
-### 间距
-
-- 最小边距 0.5 英寸
-- 内容块之间 0.3-0.5 英寸
-- 留出呼吸空间——不要塞满每一寸
-
-### 避免（常见错误）
-
-- **不要重复相同的布局**——在幻灯片之间变化列、卡片和标注样式
-- **不要居中正文**——左对齐段落和列表；只居中标题
-- **不要吝啬大小对比**——标题需要 36pt+ 才能从 14-16pt 正文中脱颖而出
-- **不要默认使用蓝色**——选择反映特定主题的颜色
-- **不要随机混用间距**——选择 0.3 英寸或 0.5 英寸的间距并一致使用
-- **不要只美化一张幻灯片而其余保持平淡**——要么全心投入，要么全文保持简洁
-- **不要创建纯文字幻灯片**——添加图片、图标、图表或视觉元素；避免仅标题+项目符号
-- **不要忘记文本框内边距**——在排列线条或形状与文字边缘对齐时，设置文本框 `margin：0` 或相应偏移形状
-- **不要使用低对比度元素**——图标和文字都需要与背景有强烈对比；避免浅色背景上的浅色文字或深色背景上的深色文字
-- **永远不要在标题下使用装饰线**——这是 AI 生成幻灯片的标志；改用留白或背景色
-
----
-
-## QA（必需）
-
-**假设存在问题。你的工作就是找到它们。**
-
-第一次渲染几乎从不会是完美的。将 QA 视为排查漏洞，而非确认步骤。如果第一次检查发现零问题，说明你没有认真查找。
-
-### 内容 QA
-
-```bash
-python -m markitdown output.pptx
-```
-
-检查内容缺失、拼写错误、顺序不对。
-
-**使用模板时，检查是否残留占位文本：**
-
-```bash
-python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|this.*(page|slide).*layout"
-```
-
-如果 grep 有结果，在宣布成功之前修复它们。
-
-### 视觉 QA
-
-**⚠️ 使用子代理**——即使只有 2-3 张幻灯片也是如此。你一直盯着代码，会看到你期望的内容而非实际内容。子代理有全新的视角。
-
-将幻灯片转换为图片（参见[转换为图片](#转换为图片)），然后使用以下提示：
-
-```
-视觉检查这些幻灯片。假设存在问题——找到它们。
-
-查找：
-- 重叠元素（文字穿过形状、线条穿过文字、堆叠元素）
-- 文字溢出或在边缘/框边界处被截断
-- 装饰线为单行文字定位但标题换行为两行
-- 来源引用或页脚与上方内容碰撞
-- 元素间距太近（< 0.3 英寸间隙）或卡片/章节几乎相接
-- 间距不均匀（一处大面积空白，另一处拥挤）
-- 距离幻灯片边缘边距不足（< 0.5 英寸）
-- 列或类似元素未一致对齐
-- 低对比度文字（如奶油色背景上的浅灰文字）
-- 低对比度图标（如深色背景上的深色图标，无对比色圆圈）
-- 文本框过窄导致过多换行
-- 残留占位内容
-
-对每张幻灯片，列出问题或关注点，即使是很小的。
-
-阅读并分析这些图片：
-1. /path/to/slide-01.jpg（预期：[简要描述]）
-2. /path/to/slide-02.jpg（预期：[简要描述]）
-
-报告所有发现的问题，包括小的。
-```
-
-### 验证循环
-
-1. 生成幻灯片 → 转换为图片 → 检查
-2. **列出发现的问题**（如未发现问题，请更批判性地审查）
-3. 修复问题
-4. **重新验证受影响的幻灯片**——一次修复往往会产生新的问题
-5. 重复直到完整一轮检查未发现新问题
-
-**在完成至少一轮修复-验证循环之前，不要宣布成功。**
-
----
-
-## 转换为图片
-
-将演示文稿转换为单个幻灯片图片以便视觉检查：
-
-```bash
-python scripts/office/soffice.py --headless --convert-to pdf output.pptx
-pdftoppm -jpeg -r 150 output.pdf slide
-```
-
-这会创建 `slide-01.jpg`、`slide-02.jpg` 等。
-
-修复后重新渲染特定幻灯片：
-
-```bash
-pdftoppm -jpeg -r 150 -f N -l N output.pdf slide-fixed
-```
-
----
-
-## 依赖项
-
-- `pip install "markitdown[pptx]"` - 文字提取
-- `pip install Pillow` - 缩略图网格
-- `npm install -g pptxgenjs` - 从零创建
-- LibreOffice（`soffice`）- PDF 转换（通过 `scripts/office/soffice.py` 为沙箱环境自动配置）
-- Poppler（`pdftoppm`）- PDF 转图片

package/skills/documents/pptx/SKILL.md

@@ -1,232 +0,0 @@
----
-name: pptx
-description: "Use this skill any time a .pptx file is involved in any way — as input, output, or both. This includes: creating slide decks, pitch decks, or presentations; reading, parsing, or extracting text from any .pptx file (even if the extracted content will be used elsewhere, like in an email or summary); editing, modifying, or updating existing presentations; combining or splitting slide files; working with templates, layouts, speaker notes, or comments. Trigger whenever the user mentions \"deck,\" \"slides,\" \"presentation,\" or references a .pptx filename, regardless of what they plan to do with the content afterward. If a .pptx file needs to be opened, created, or touched, use this skill."
-license: Proprietary. LICENSE.txt has complete terms
----
-
-# PPTX Skill
-
-## Quick Reference
-
-| Task | Guide |
-|------|-------|
-| Read/analyze content | `python -m markitdown presentation.pptx` |
-| Edit or create from template | Read [editing.md](editing.md) |
-| Create from scratch | Read [pptxgenjs.md](pptxgenjs.md) |
-
----
-
-## Reading Content
-
-```bash
-# Text extraction
-python -m markitdown presentation.pptx
-
-# Visual overview
-python scripts/thumbnail.py presentation.pptx
-
-# Raw XML
-python scripts/office/unpack.py presentation.pptx unpacked/
-```
-
----
-
-## Editing Workflow
-
-**Read [editing.md](editing.md) for full details.**
-
-1. Analyze template with `thumbnail.py`
-2. Unpack → manipulate slides → edit content → clean → pack
-
----
-
-## Creating from Scratch
-
-**Read [pptxgenjs.md](pptxgenjs.md) for full details.**
-
-Use when no template or reference presentation is available.
-
----
-
-## Design Ideas
-
-**Don't create boring slides.** Plain bullets on a white background won't impress anyone. Consider ideas from this list for each slide.
-
-### Before Starting
-
-- **Pick a bold, content-informed color palette**: The palette should feel designed for THIS topic. If swapping your colors into a completely different presentation would still "work," you haven't made specific enough choices.
-- **Dominance over equality**: One color should dominate (60-70% visual weight), with 1-2 supporting tones and one sharp accent. Never give all colors equal weight.
-- **Dark/light contrast**: Dark backgrounds for title + conclusion slides, light for content ("sandwich" structure). Or commit to dark throughout for a premium feel.
-- **Commit to a visual motif**: Pick ONE distinctive element and repeat it — rounded image frames, icons in colored circles, thick single-side borders. Carry it across every slide.
-
-### Color Palettes
-
-Choose colors that match your topic — don't default to generic blue. Use these palettes as inspiration:
-
-| Theme | Primary | Secondary | Accent |
-|-------|---------|-----------|--------|
-| **Midnight Executive** | `1E2761` (navy) | `CADCFC` (ice blue) | `FFFFFF` (white) |
-| **Forest & Moss** | `2C5F2D` (forest) | `97BC62` (moss) | `F5F5F5` (cream) |
-| **Coral Energy** | `F96167` (coral) | `F9E795` (gold) | `2F3C7E` (navy) |
-| **Warm Terracotta** | `B85042` (terracotta) | `E7E8D1` (sand) | `A7BEAE` (sage) |
-| **Ocean Gradient** | `065A82` (deep blue) | `1C7293` (teal) | `21295C` (midnight) |
-| **Charcoal Minimal** | `36454F` (charcoal) | `F2F2F2` (off-white) | `212121` (black) |
-| **Teal Trust** | `028090` (teal) | `00A896` (seafoam) | `02C39A` (mint) |
-| **Berry & Cream** | `6D2E46` (berry) | `A26769` (dusty rose) | `ECE2D0` (cream) |
-| **Sage Calm** | `84B59F` (sage) | `69A297` (eucalyptus) | `50808E` (slate) |
-| **Cherry Bold** | `990011` (cherry) | `FCF6F5` (off-white) | `2F3C7E` (navy) |
-
-### For Each Slide
-
-**Every slide needs a visual element** — image, chart, icon, or shape. Text-only slides are forgettable.
-
-**Layout options:**
-- Two-column (text left, illustration on right)
-- Icon + text rows (icon in colored circle, bold header, description below)
-- 2x2 or 2x3 grid (image on one side, grid of content blocks on other)
-- Half-bleed image (full left or right side) with content overlay
-
-**Data display:**
-- Large stat callouts (big numbers 60-72pt with small labels below)
-- Comparison columns (before/after, pros/cons, side-by-side options)
-- Timeline or process flow (numbered steps, arrows)
-
-**Visual polish:**
-- Icons in small colored circles next to section headers
-- Italic accent text for key stats or taglines
-
-### Typography
-
-**Choose an interesting font pairing** — don't default to Arial. Pick a header font with personality and pair it with a clean body font.
-
-| Header Font | Body Font |
-|-------------|-----------|
-| Georgia | Calibri |
-| Arial Black | Arial |
-| Calibri | Calibri Light |
-| Cambria | Calibri |
-| Trebuchet MS | Calibri |
-| Impact | Arial |
-| Palatino | Garamond |
-| Consolas | Calibri |
-
-| Element | Size |
-|---------|------|
-| Slide title | 36-44pt bold |
-| Section header | 20-24pt bold |
-| Body text | 14-16pt |
-| Captions | 10-12pt muted |
-
-### Spacing
-
-- 0.5" minimum margins
-- 0.3-0.5" between content blocks
-- Leave breathing room—don't fill every inch
-
-### Avoid (Common Mistakes)
-
-- **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; avoid light text on light backgrounds or dark text on dark backgrounds
-- **NEVER use accent lines under titles** — these are a hallmark of AI-generated slides; use whitespace or background color instead
-
----
-
-## QA (Required)
-
-**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.
-
-**When using templates, check for leftover placeholder text:**
-
-```bash
-python -m markitdown output.pptx | grep -iE "xxxx|lorem|ipsum|this.*(page|slide).*layout"
-```
-
-If grep returns results, fix them before declaring success.
-
-### Visual QA
-
-**⚠️ USE SUBAGENTS** — even for 2-3 slides. You've been staring at the code and will see what you expect, not what's there. Subagents have fresh eyes.
-
-Convert slides to images (see [Converting to Images](#converting-to-images)), then use this prompt:
-
-```
-Visually inspect these slides. Assume there are issues — find them.
-
-Look for:
-- Overlapping elements (text through shapes, lines through words, stacked elements)
-- Text overflow or cut off at edges/box boundaries
-- Decorative lines positioned for single-line text but title wrapped to two lines
-- Source citations or footers colliding with content above
-- Elements too close (< 0.3" gaps) or cards/sections nearly touching
-- Uneven gaps (large empty area in one place, cramped in another)
-- Insufficient margin from slide edges (< 0.5")
-- Columns or similar elements not aligned consistently
-- Low-contrast text (e.g., light gray text on cream-colored background)
-- Low-contrast icons (e.g., dark icons on dark backgrounds without a contrasting circle)
-- Text boxes too narrow causing excessive wrapping
-- Leftover placeholder content
-
-For each slide, list issues or areas of concern, even if minor.
-
-Read and analyze these images:
-1. /path/to/slide-01.jpg (Expected: [brief description])
-2. /path/to/slide-02.jpg (Expected: [brief description])
-
-Report ALL issues found, including minor ones.
-```
-
-### Verification Loop
-
-1. Generate slides → Convert to images → Inspect
-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.**
-
----
-
-## Converting to Images
-
-Convert presentations to individual slide images for visual inspection:
-
-```bash
-python scripts/office/soffice.py --headless --convert-to pdf output.pptx
-pdftoppm -jpeg -r 150 output.pdf slide
-```
-
-This creates `slide-01.jpg`, `slide-02.jpg`, etc.
-
-To re-render specific slides after fixes:
-
-```bash
-pdftoppm -jpeg -r 150 -f N -l N output.pdf slide-fixed
-```
-
----
-
-## Dependencies
-
-- `pip install "markitdown[pptx]"` - text extraction
-- `pip install Pillow` - thumbnail grids
-- `npm install -g pptxgenjs` - creating from scratch
-- LibreOffice (`soffice`) - PDF conversion (auto-configured for sandboxed environments via `scripts/office/soffice.py`)
-- Poppler (`pdftoppm`) - PDF to images

package/skills/documents/pptx/editing.md

@@ -1,205 +0,0 @@
-# Editing Presentations
-
-## Template-Based Workflow
-
-When using an existing presentation as a template:
-
-1. **Analyze existing slides**:
-   ```bash
-   python scripts/thumbnail.py template.pptx
-   python -m markitdown template.pptx
-   ```
-   Review `thumbnails.jpg` to see layouts, and markitdown output to see placeholder text.
-
-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**: `python scripts/office/unpack.py template.pptx unpacked/`
-
-4. **Build presentation** (do this yourself, not with subagents):
-   - Delete unwanted slides (remove from `<p:sldIdLst>`)
-   - Duplicate slides you want to reuse (`add_slide.py`)
-   - 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**: `python scripts/clean.py unpacked/`
-
-7. **Pack**: `python scripts/office/pack.py unpacked/ output.pptx --original template.pptx`
-
----
-
-## Scripts
-
-| Script | Purpose |
-|--------|---------|
-| `unpack.py` | Extract and pretty-print PPTX |
-| `add_slide.py` | Duplicate slide or create from layout |
-| `clean.py` | Remove orphaned files |
-| `pack.py` | Repack with validation |
-| `thumbnail.py` | Create visual grid of slides |
-
-### unpack.py
-
-```bash
-python scripts/office/unpack.py input.pptx unpacked/
-```
-
-Extracts PPTX, pretty-prints XML, escapes smart quotes.
-
-### add_slide.py
-
-```bash
-python scripts/add_slide.py unpacked/ slide2.xml      # Duplicate slide
-python scripts/add_slide.py unpacked/ slideLayout2.xml # From layout
-```
-
-Prints `<p:sldId>` to add to `<p:sldIdLst>` at desired position.
-
-### clean.py
-
-```bash
-python scripts/clean.py unpacked/
-```
-
-Removes slides not in `<p:sldIdLst>`, unreferenced media, orphaned rels.
-
-### pack.py
-
-```bash
-python scripts/office/pack.py unpacked/ output.pptx --original input.pptx
-```
-
-Validates, repairs, condenses XML, re-encodes smart quotes.
-
-### thumbnail.py
-
-```bash
-python scripts/thumbnail.py input.pptx [output_prefix] [--cols N]
-```
-
-Creates `thumbnails.jpg` with slide filenames as labels. Default 3 columns, max 12 per grid.
-
-**Use for template analysis only** (choosing layouts). For visual QA, use `soffice` + `pdftoppm` to create full-resolution individual slide images—see SKILL.md.
-
----
-
-## Slide Operations
-
-Slide order is in `ppt/presentation.xml` → `<p:sldIdLst>`.
-
-**Reorder**: Rearrange `<p:sldId>` elements.
-
-**Delete**: Remove `<p:sldId>`, then run `clean.py`.
-
-**Add**: Use `add_slide.py`. Never manually copy slide files—the script handles notes references, Content_Types.xml, and relationship IDs that manual copying misses.
-
----
-
-## 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 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 visual QA to catch mismatched counts
-
-When replacing text with different length content:
-- **Shorter replacements**: Usually safe
-- **Longer replacements**: May overflow or wrap unexpectedly
-- Test with visual QA 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
-
-Handled automatically by unpack/pack. But 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 |
-|-----------|------|---------|------------|
-| `“` | Left double quote | U+201C | `&#x201C;` |
-| `”` | Right double quote | U+201D | `&#x201D;` |
-| `‘` | Left single quote | U+2018 | `&#x2018;` |
-| `’` | 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)