Skip to content

AI turns documents or topics into real, native PowerPoint decks—with native shapes, transitions and animations, data-backed charts and tables on demand, audio narration from speaker notes, and support for your own .pptx templates. · by Hugo He

docs(technical-design): consolidate repo architecture into single source of truth

hugohe322761c022ca8
diff --git a/docs/technical-design.md b/docs/technical-design.md
index 6b881f6d..3f3522ba 100644
--- a/docs/technical-design.md
+++ b/docs/technical-design.md
@@ -27,7 +27,7 @@ User Input (PDF/DOCX/XLSX/URL/Markdown)
↓
[Strategist] - Eight Confirmations & Design Specifications → design_spec.md + spec_lock.md
↓
-[Image_Generator] (When AI image generation is selected)
+[Image Acquisition] (when any row in the resource list needs AI generation or web search)
↓
[Executor]
├── Visual construction: generate all SVG pages → svg_output/
@@ -91,3 +91,385 @@ SVG wins because it shares the same world view as DrawingML: both are absolute-c
The conversion is a translation between two dialects of the same idea — not a format mismatch.
SVG is also the only format that simultaneously satisfies every role in the pipeline: **AI can reliably generate it, humans can preview and debug it in any browser, and scripts can precisely convert it** — all before a single line of DrawingML is written.
+
+---
+
+## Source Content Conversion
+
+Source content conversion is invisible to most users but shapes everything downstream: source documents (PDF / DOCX / EPUB / XLSX / PPTX / web pages) are normalized into Markdown before the pipeline starts. The Markdown becomes Strategist's reading material and the source of truth for every subsequent decision.
+
+Two cross-cutting design choices shape the converters:
+
+**Native-Python first, external binaries as fallback.** `doc_to_md.py` uses `mammoth` for `.docx`, `markdownify` + `beautifulsoup4` for `.html`, `ebooklib` for `.epub`, `nbconvert` for `.ipynb` — all pure Python wheels. Pandoc is only invoked for the long tail (`.doc` / `.odt` / `.rtf` / `.tex` / `.rst` / `.org` / `.typ`). PDF goes through `PyMuPDF` for native-text PDFs, with MinerU / OCR tools recommended only when the PDF is scanned. Rationale: avoid making every user install a system-level binary they may not have permissions for, while still covering edge cases.
+
+**TLS fingerprint impersonation for high-security sites.** `web_to_md.py` uses `curl_cffi` to impersonate a modern Chrome TLS fingerprint by default. This single dependency lets the same script handle WeChat Official Accounts (`mp.weixin.qq.com`) and other CDNs that block Python's default `requests` TLS handshake. The Node.js sibling `web_to_md.cjs` is retained only as a backup for environments where `curl_cffi` has no prebuilt wheel.
+
+All converters produce the same output convention: `<input>.md` plus a sibling `<input>_files/` directory with extracted images at relative paths. This convention is what `import-sources --move` keys off of during project initialization.
+
+---
+
+## Project Structure & Lifecycle
+
+A PPT Master project is a directory with a fixed shape:
+
+```
+projects/<name>_<format>_<timestamp>/
+├── sources/ # raw inputs after import-sources
+├── images/ # AI-generated + searched + user-supplied images
+├── templates/ # optional template SVGs / design_spec_reference
+├── design_spec.md # human-readable design narrative (Strategist output)
+├── spec_lock.md # machine-readable execution contract (Strategist output)
+├── notes/ # speaker notes, split per slide by total_md_split.py
+├── svg_output/ # Executor's authored SVG pages (source of truth)
+├── svg_final/ # post-processed self-contained SVGs (IDE preview)
+├── exports/ # final native pptx
+└── backup/<ts>/ # timestamped snapshots from svg_to_pptx
+```
+
+`project_manager.py init` creates this skeleton; `import-sources` is the only sanctioned way to bring source files into `sources/`. Two import semantics matter:
+
+- Files **outside** the repo: copied by default (preserve user's original); `--move` to consume them
+- Files **inside** the repo: moved by default (avoid leaving stray artifacts that get accidentally committed); `--copy` to override
+
+This asymmetry is deliberate. The default behavior matches the natural risk profile in each context — outside-repo files are typically user assets we shouldn't disturb; inside-repo files are typically intermediate artifacts that should be cleaned up.
+
+`batch_validate.py` exists for repository-wide health checks before release, and `error_helper.py` provides standardized fixes for the common project-structure errors so the AI can self-recover from broken state mid-pipeline.
+
+---
+
+## Canvas Format System
+
+PPT Master is not PPT-only. The same SVG → DrawingML pipeline can produce square posters, 9:16 stories, or A4 prints — only the `viewBox` changes. Nine canvas formats cover the common content purposes:
+
+| Format | viewBox | Ratio | Purpose |
+|---|---|---|---|
+| `ppt169` | 1280×720 | 16:9 | Modern presentations |
+| `ppt43` | 1024×768 | 4:3 | Traditional projectors / academic |
+| `xiaohongshu` | 1242×1660 | 3:4 | RED knowledge posts |
+| `moments` | 1080×1080 | 1:1 | WeChat / IG square |
+| `story` | 1080×1920 | 9:16 | TikTok / Stories |
+| `wechat_article` | 900×383 | 2.35:1 | WeChat article header |
+| `banner` | 1920×1080 | 16:9 | Web / digital screens |
+| `poster` | 1080×1920 | 9:16 | Phone / elevator ads |
+| `a4` | 1240×1754 | 1:√2 | Print |
+
+The viewBox dimensions are pixel values, not absolute units (EMU is computed at PPTX export time). Pixel viewBox makes it easier for the AI Executor to reason about layout (`x="100"` is unambiguously left edge + 100px), and easier for human inspection in any browser. The conversion to PowerPoint's EMU happens once, during `svg_to_pptx`, via the canonical EMU/px ratio (914400 EMU per inch ÷ 96 px per inch = 9525 EMU/px).
+
+Layout principles diverge per orientation:
+
+- **Landscape (16:9 / 4:3 / 2.35:1)** — Z-pattern visual flow, multi-column / left-right split / grid layouts, 40-80px margins
+- **Portrait (3:4 / 9:16)** — top-to-bottom flow, single-column / top-bottom split / card stack, 60-120px margins
+- **Square (1:1)** — center-radiating, ~800px core area, 60-100px margins
+
+Each format also has format-specific design conventions (page number position for PPT; brand area for RED; safe zones for Stories) — these live in `references/canvas-formats.md` for the Executor.
+
+---
+
+## Template System & Optional Path
+
+Templates are an opt-in path, not a default. The default Strategist flow is **free design** — open canvas, AI invents the visual system from the source content alone. The template path is entered only when an explicit user trigger fires: naming a specific template, naming a brand or style that maps to one, or asking what templates exist.
+
+**Why default to free design.** Templates are floors that easily become ceilings — they lock the deck into the template's visual idioms. AI is good at generating original layouts that match content rhythm; constraining it to a template often produces a worse fit than letting it design fresh. So the AI never proactively offers a template — the user must reach for it.
+
+**Soft-hint mechanism.** When the source content is an obvious strong match for an existing template (academic defense, government report, McKinsey-style deck) AND no user trigger fired, Strategist emits a one-sentence non-blocking notice: *"the library has a template `<name>` that matches this scenario closely. Say the word if you want to use it; otherwise I'll continue with free design."* This is a hint, not a question — generation continues without waiting. Skipped on weak or ambiguous matches.
+
+**Three template libraries.** The `templates/` directory hosts three libraries with different roles:
+
+| Library | Path | What it provides | When used |
+|---|---|---|---|
+| Layouts | `templates/layouts/<name>/` | Whole-deck templates: SVG pages + `design_spec_reference.md` + assets | Opt-in only, on user trigger |
+| Charts | `templates/charts/<name>.svg` | Reusable visualization SVGs (charts, infographics, diagrams, frameworks) | Every Executor references these for chart pages |
+| Icons | `templates/icons/<library>/` | Three icon libraries (`chunk-filled` / `tabler-filled` / `tabler-outline`) — pick one library per deck based on content tone | Every deck uses one library; never mixed |
+
+Charts and icons are referenced by every Executor regardless of layout choice; layout templates are the opt-in piece.
+
+**Creating new templates.** The `create-template` standalone workflow takes a reference PPTX, externalizes its assets, infers theme colors and typography, and produces SVG slides + manifest in `<pptx_stem>_template_import/`. This is a one-shot ingestion, not part of the deck-generation pipeline. Native SVG export from PPTX is Windows-only (uses installed PowerPoint COM); macOS falls back to Keynote → PDF → SVG.
+
+---
+
+## Role System: Three Specialized Agents in a Single Pipeline
+
+PPT Master uses **role switching within one main agent** rather than parallel sub-agents. Three roles, one continuous context, sequential execution:
+
+```
+Strategist → Image Acquisition (conditional) → Executor
+ ↓ ↓ ↓
+design_spec.md images/*.png svg_output/*.svg
+spec_lock.md image_prompts.md notes/total.md
+ image_sources.json
+```
+
+The Image Acquisition phase dispatches each row to one of two independent sub-roles based on its `Acquire Via`: `image-generator` for `ai` rows (AI generation), `image-searcher` for `web` rows (web search). They are loaded lazily — a deck with only `ai` rows never reads `image-searcher.md`. See "Image Acquisition & Embedding" below.
+
+**Why one agent, not parallel sub-agents?** Page design depends on the full upstream context — Strategist's color choices, the image resources that did or did not get acquired, prior pages' visual rhythm. SKILL.md explicitly forbids delegating page SVG generation to sub-agents (rule 6 of the Global Execution Discipline). Sequential page-by-page generation in one continuous pass is mandated (rule 7) — batched generation (e.g., 5 pages at a time) is forbidden because it accelerates context compression and breaks visual consistency.
+
+**Why role-specialized references rather than one mega prompt?** Each role has its own `references/<role>.md` with focused instructions. Mixing them all in one prompt would force the model to juggle Strategist's "negotiate with user" mode with Executor's "produce strict XML" mode in the same turn — they want different temperature, different formatting discipline, different failure tolerance.
+
+**Eight Confirmations.** The Strategist phase ends with eight bundled confirmations (canvas / page count / audience / style / color / icon / typography / image) that are presented to the user as a **single blocking decision point**. After confirmation, all subsequent phases run automatically without further user gates. This is the only blocking checkpoint in the deck-generation flow — every other gate is procedural.
+
+**User-provided image analysis (conditional, runs before the Eight Confirmations).** When the user supplies images alongside source documents, Strategist MUST run `analyze_images.py <project>/images` before drafting `design_spec.md`. The script extracts each image's dimensions, EXIF orientation, dominant color, and subject metadata into a textual summary. Strategist reasons over that summary — opening image bytes directly is forbidden by SKILL.md's image-handling rule, because the LLM doesn't need pixels to make layout decisions, it needs metadata that fits on a page (aspect ratio for placement, color tone for palette compatibility, subject for slide assignment). The output feeds into the image resource list inside `design_spec.md`, grounding the Eight Confirmations in actual provided assets rather than filenames.
+
+**Per-page spec_lock re-read.** Before generating each SVG page, Executor must re-read `spec_lock.md`. This is the explicit anti-drift mechanism that lets the system produce 20-page decks with consistent color/font/icon discipline despite the LLM's context window being lossy.
+
+Three Executor styles ship as separate references — `executor-general.md`, `executor-consultant.md`, `executor-consultant-top.md` — selected by the user's chosen style. Each loads only the relevant style file plus the shared `executor-base.md` and `shared-standards.md`, keeping the context payload minimal.
+
+---
+
+## Execution Discipline
+
+The pipeline is enforced by an 8-rule set in SKILL.md's Global Execution Discipline. They look bureaucratic but each one closes a specific failure mode observed in practice.
+
+| # | Rule | What it forbids | Why |
+|---|---|---|---|
+| 1 | **Serial execution** | Skipping or reordering steps | Each step's output is the next step's input; out-of-order execution silently uses stale or absent inputs |
+| 2 | **BLOCKING = hard stop** | Auto-deciding past a `⛔ BLOCKING` checkpoint (Eight Confirmations) | The user must own design choices; AI proxying the decision creates decks that don't match user intent |
+| 3 | **No cross-phase bundling** | Combining multiple phases into one turn | LLMs that try to do Strategist + Executor in one shot drift on either correctness or style |
+| 4 | **Gate before entry** | Starting a step before its prerequisites are met | Each step lists 🚧 GATE prerequisites; checking them prevents cascading errors |
+| 5 | **No speculative execution** | Pre-preparing later step's content (e.g., writing SVG during Strategist phase) | The earlier phase's outputs may invalidate that pre-work; doing it wastes context and creates inconsistency |
+| 6 | **No sub-agent SVG generation** | Delegating page SVG generation to sub-agents | Page design needs full upstream context (color choices, prior visual rhythm, available images); sub-agents start with stale partial context |
+| 7 | **Sequential page generation only** | Batching pages (e.g., 5 at a time) | Batching accelerates context compression and breaks visual consistency across the deck |
+| 8 | **Per-page spec_lock re-read** | Generating an SVG without re-reading `spec_lock.md` | Resists context-compression drift on long decks — page 18's color must match page 1's |
+
+**Role Switching Protocol.** When the agent switches roles (Strategist → Executor, etc.), it MUST first `read_file references/<role>.md` and output a markdown marker:
+
+```
+## [Role Switch: <Role Name>]
+📖 Reading role definition: references/<filename>.md
+📋 Current task: <brief description>
+```
+
+This serves two purposes: forces fresh role instructions into context (overriding any drift from the previous role's mode), and creates an audit trail in the conversation transcript so the user can see when the agent moved between modes.
+
+The discipline is intentionally explicit because LLMs default to "let me solve the whole problem in this turn" — which is the wrong shape for a serial pipeline where each step depends on bounded, checkpointed outputs from the previous one.
+
+---
+
+## Spec Propagation: spec_lock.md as Execution Contract
+
+The Strategist phase produces two artifacts that look redundant but serve different masters:
+
+- `design_spec.md` — human-readable narrative; the "why" of the design (target audience, style objective, color rationale, page outline)
+- `spec_lock.md` — machine-readable execution contract; the "what" Executor must literally use (HEX colors, exact font family string, icon library choice, image resource list with status)
+
+Why both? Without `spec_lock.md`, the Executor would re-read `design_spec.md` per page during long decks and the LLM's context-compression drift would gradually mutate colors and fonts mid-deck. `spec_lock.md` is the **anti-drift mechanism** — the SKILL.md mandates `read_file <project>/spec_lock.md` before every page, so values stay verbatim across 20+ slides.
+
+`update_spec.py` propagates a post-generation change in two coordinated steps: write the new value to `spec_lock.md`, then literal-replace it across every `svg_output/*.svg`. The tool's scope is deliberately narrow — only `colors.*` (HEX values, case-insensitive replacement) and `typography.font_family` (attribute-scoped). Other fields (font sizes, icons, images, canvas) are intentionally **not supported** because their replacements would need attribute-scoped or semantic awareness whose risk/benefit doesn't justify bulk propagation. For those, edit `spec_lock.md` and re-author the affected pages.
+
+The tool refuses to back up: it relies on git for revert. Adding a backup mechanism would just duplicate git's job and create stale snapshots.
+
+---
+
+## Image Acquisition & Embedding
+
+Image Acquisition is conditional. The design spec produces a resource list where each image row has an `Acquire Via` field: `ai` (AI generation), `web` (web search), `user` (already provided), or `placeholder` (defer). Only rows marked `ai` or `web` trigger this phase; pure-`user` decks skip it. The phase splits into two independent sub-roles dispatched per row: `image-generator` for `ai` rows, `image-searcher` for `web` rows. A mixed deck loads both reference files and runs each row through its own path; `ai`-only or `web`-only decks load only the relevant role.
+
+**Multi-backend image generation** (the `ai` path). `image_gen.py` is a thin dispatcher over a backend registry. Backends are tiered:
+
+- **Core** — production-ready (OpenAI gpt-image, Google Imagen, MiniMax, Qwen, Volcengine, Zhipu, Gemini)
+- **Extended** — specialized models opt-in by the user
+- **Experimental** — API-unstable, opt-in only
+
+Configuration uses **provider-specific keys only** (`OPENAI_API_KEY`, `MINIMAX_API_KEY`, `GEMINI_API_KEY`, ...). Generic fields like `IMAGE_API_KEY` / `IMAGE_MODEL` / `IMAGE_BASE_URL` are intentionally rejected — they cause silent confusion when multiple providers are configured in one `.env`. The active backend must be selected explicitly via `IMAGE_BACKEND=<name>`.
+
+**Web image search with license discipline** (the `web` path). `image_search.py` is the sister tool, used when the resource list says `Acquire Via: web`. Default chain: zero-config providers (Openverse, Wikimedia) → keyed providers (Pexels, Pixabay) when their key is set. License filter defaults to permissive (CC0, PDM, Pexels, Pixabay, CC BY, CC BY-SA) — Executor adds inline credit when the chosen image is `attribution-required`. `--strict-no-attribution` restricts to zero-attribution licenses, used for full-bleed hero images that have no visual room for a credit element. Auto-rejected: any non-commercial (CC BY-NC*) or no-derivatives (CC BY-ND*) license. Provenance is tracked in `image_sources.json` (provider / license / author / source URL / dimensions / attribution_text), idempotent on filename.
+
+**Embedding strategy.** During development, images stay as **external references** in `svg_output/` — fast iteration, easy replacement. `finalize_svg.py align-images` step Base64-inlines them when producing `svg_final/`, because IDE / browser / preview pptx all need self-contained files. The native pptx converter does **not** Base64-inline — it copies bitmap files into the PPTX media folder and uses `<a:srcRect>` to express SVG's `preserveAspectRatio="... slice"` cropping inside DrawingML. Two paths because external references are debuggable while embedded payloads are deliverable; they coexist by design.
+
+---
+
+## SVG Constraints: Banned Features and Conditional Allowances
+
+PowerPoint's DrawingML is a strict subset of what SVG can express. The Executor operates inside a **banned-features blacklist** designed empirically from PPT export failures:
+
+**Hard-banned (export breaks otherwise):**
+- `<mask>` — DrawingML has no per-pixel alpha
+- `<style>` / `class` — DrawingML has no CSS selector model
+- External CSS / `@font-face` — fonts must be system-installable, not file-loaded
+- `<foreignObject>` — embedded HTML inside SVG has no DrawingML mapping
+- `<symbol>` + `<use>` for general reuse — DrawingML has no symbol model (icon `<use data-icon>` is project-internal and gets expanded pre-conversion, not the same thing)
+- `textPath` — text along arbitrary path has no DrawingML primitive
+- `<animate*>` / `<set>` — SVG animation; PowerPoint animation is a separate timing model expressed in slide XML
+- `<script>` / event attributes / `<iframe>` — interactivity is a different layer
+
+**XML well-formedness:**
+- All text and attribute values must use **raw Unicode** for typography (`—`, `→`, `©`, NBSP) — HTML named entities (`&mdash;`, `&rarr;`) are XML-illegal in SVG
+- Reserved XML chars (`& < > " '`) must use XML entities (`&amp;` etc.) — bare `R&D` aborts export
+
+**Conditional allowances (with exact constraint sets in `references/shared-standards.md`):**
+- `marker-start` / `marker-end` on `<line>` / `<path>` — allowed only when the marker shape maps cleanly to DrawingML's three arrow-head primitives (triangle / diamond / oval), with marker fill matching line stroke
+- `clip-path` on `<image>` only — allowed when the clip shape is a single circle / ellipse / rect / path / polygon, mapping to DrawingML picture geometry. Clip on non-image elements is forbidden (a rect clipped to a circle should just be a circle)
+
+**Effect routing.** Because `<mask>` is banned, common visual effects route differently:
+
+| Effect | Substitute |
+|---|---|
+| Image gradient overlay (vignette/fade/tint) | Stacked `<rect>` with `<linearGradient>` / `<radialGradient>` |
+| Non-rectangular image crop | `clipPath` on `<image>` |
+| Inner glow / soft edge | `<filter>` with `<feGaussianBlur>` |
+| Drop shadow | Filter shadow or layered rect |
+| Pixel-level alpha (text-knockout fills, arbitrary alpha composites) | **No PPT path** — bake into source image at Image Acquisition stage |
+
+`svg_quality_checker.py` enforces this blacklist before post-processing — any banned feature is a blocking error, fixed by regenerating the offending page in the Executor.
+
+---
+
+## Quality Gate
+
+`svg_quality_checker.py` runs after Executor finishes all pages and before any post-processing. The placement is deliberate: post-processing rewrites SVG (icon embedding, image inlining) and would mask source-level violations. The checker reads `svg_output/` only.
+
+**What it checks:**
+
+- **`viewBox`** — present and matching the project's canvas format. Mismatch silently breaks layout when scripts assume canonical pixel space.
+- **Banned features** — every entry in the SVG blacklist (mask, style, class, foreignObject, symbol+use, textPath, @font-face, animate*, script, iframe). Any hit is a blocking error.
+- **width/height consistency** — `<svg>` root attributes match `viewBox` dimensions.
+- **Line-break structure** — multi-line `<text>` uses positional `<tspan>` with `x` + `dy`, not `\n` characters or sibling text drift.
+- **spec_lock drift** — colors / fonts / icons / images in the SVG must come from `spec_lock.md`. Off-spec values are warnings (sometimes legitimate) or errors (when they suggest the Executor went off-script).
+- **Low-resolution image / non-PPT-safe font tail** — soft warnings; fixed when straightforward, otherwise acknowledged and released.
+
+**Severity model:** errors block the pipeline (regenerate the offending page); warnings inform but don't block. There is intentionally no "auto-fix" mode — fixing a banned feature requires the Executor to re-author the page in context, not a mechanical patch.
+
+**Why this exists at all.** SVG generated by an LLM is not deterministic. Without a checker, banned features creep in over long decks and only surface when `svg_to_pptx` aborts mid-conversion or PowerPoint silently drops elements. The checker turns "PowerPoint export failed at page 14" into "the Executor used `<style>` on page 14, regenerate it" — an order of magnitude faster to diagnose.
+
+The quality checker is also the natural insertion point for **chart coordinate verification** (`verify-charts` workflow). Chart pages have geometric correctness requirements (bar heights / pie sweep angles / axis tick positions) that aren't structural and aren't caught by SVG validity rules. `svg_position_calculator.py` calculates expected coordinates from the data, and the workflow asks the AI to compare and fix mismatches before continuing to post-processing.
+
+---
+
+## Post-Processing Pipeline
+
+> Why each artifact and module exists in the engineering conversion stage, and which workflows would break if you delete it. Read this before considering any simplification of `svg_final/` / `finalize_svg.py` / `svg_to_pptx.py`.
+
+### Four artifacts, four workflows
+
+The post-processing stage produces four artifacts. Each one serves a workflow that nothing else in the pipeline can replace.
+
+| Artifact | Workflow it serves | Why nothing else replaces it |
+| --- | --- | --- |
+| `svg_output/` | source of truth, manual editing, `update_spec.py`, `svg_quality_checker.py` | only directory whose contents are authored, not derived |
+| `svg_final/` | IDE inline preview (VSCode/Cursor open `.svg` directly), browser open of a single page | `.pptx` is not openable in IDEs; `svg_output/` won't render fully because of external icon / image refs |
+| `exports/<name>_<ts>.pptx` (native) | primary deliverable — editable in PowerPoint with DrawingML shapes | only artifact whose shapes the user can resize / recolor / restyle natively in PowerPoint |
+| `backup/<ts>/<name>_svg.pptx` (preview) | cross-platform single-file distribution, multi-page browse, email attachment | self-contained, multi-page, opens in PowerPoint / Keynote / WPS / LibreOffice; an `svg_final/` folder is harder to distribute |
+
+### The `svg_finalize/` package has TWO consumers
+
+This is the key insight that's easy to miss when reading the code. The same modules under `skills/ppt-master/scripts/svg_finalize/` are used in two places, for two different products.
+
+**Disk consumer** — `finalize_svg.py` writes `svg_output/` → `svg_final/` once per run. `svg_final/` then feeds IDE preview and the preview pptx.
+
+**Memory consumer** — native pptx generation reads `svg_output/` directly (no disk hop), but DrawingML can't handle two SVG features inline, so the converter calls `svg_finalize` modules **in memory**:
+
+| In-memory call site | Module reused | Why native pptx needs it |
+| --- | --- | --- |
+| `svg_to_pptx/use_expander.py` | `svg_finalize.embed_icons` | DrawingML doesn't recognize `<use data-icon="...">`; without expansion every icon silently drops |
+| `svg_to_pptx/tspan_flattener.py` | `svg_finalize.flatten_tspan` | DrawingML text runs cannot reposition mid-paragraph; a dy-stacked block of `<tspan>`s would otherwise collapse onto one baseline, and an x-anchored tspan would render in the wrong column |
+
+### Per-module consumer table
+
+| Module | Disk consumer | Memory consumer | Delete impact |
+| --- | --- | --- | --- |
+| `embed_icons.py` | `finalize_svg` `embed-icons` step | `svg_to_pptx/use_expander.py` | native pptx loses all icons + `svg_final/` not self-contained |
+| `flatten_tspan.py` | `finalize_svg` `flatten-text` step | `svg_to_pptx/tspan_flattener.py` | **native pptx multi-line `dy`-stacked text collapses to one line** |
+| `align_embed_images.py` | `finalize_svg` `align-images` step | — | `svg_final/` loses image embedding → IDE preview / preview pptx have no images |
+| `crop_images.py` / `embed_images.py` / `fix_image_aspect.py` | imported by `align_embed_images.py` | — | `align_embed_images` `ImportError`, full chain broken |
+| `svg_rect_to_path.py` | `finalize_svg` `fix-rounded` step | — | only PowerPoint's manual "Convert to Shape" loses rounded corners; browsers / IDE / PowerPoint's own SVG renderer all OK without it |
+
+### FAQ — "Can I delete this?"
+
+| Question | Short answer | Why |
+| --- | --- | --- |
+| Drop the legacy / preview pptx? | **No** | Cross-platform single-file distribution and multi-page browse-of-backup are workflows neither `svg_final/` (a folder) nor native pptx satisfy |
+| Drop `svg_final/`? | **No** | IDE inline preview — `.pptx` is not openable in VSCode / Cursor; `svg_output/` won't render in IDE because of external icon / image refs |
+| Drop `finalize_svg.py`? | **No** | `svg_final/` has no other entry point; sub-modules are still memory-reused by native conversion |
+| Drop `svg_finalize/{flatten_tspan, embed_icons}`? | **No** — native pptx breaks | See "two consumers" above |
+| Drop `svg_finalize/{crop, embed, fix_image_aspect}_images.py`? | **No** | `align_embed_images.py` imports them |
+| Drop `svg_rect_to_path.py`? | **Maybe** | Only kept for PowerPoint's manual "Convert to Shape" rounded-corner fallback. Marginal; currently kept to avoid silent regressions on uncommon manual workflows |
+
+### Editing rules
+
+- Edit only `svg_output/` — `svg_final/` is regenerated by `finalize_svg.py` on every run
+- After editing `svg_output/`, re-run `finalize_svg.py` to refresh `svg_final/` for IDE preview
+- `update_spec.py` only touches `svg_output/` — re-run `finalize_svg.py` after spec changes so `svg_final/` reflects them too
+
+---
+
+## Native PPTX Conversion Internals
+
+`svg_to_pptx/` translates SVG into DrawingML element by element. The mapping table is extensive — see `references/shared-standards.md` for the user-facing version — but the architecture is:
+
+```
+svg_output/*.svg
+ ↓
+[parse to ElementTree]
+ ↓
+[in-memory pre-process]
+ ├─ use_expander ← svg_finalize.embed_icons
+ └─ tspan_flattener ← svg_finalize.flatten_tspan
+ ↓
+[per-element dispatch] drawingml_converter.convert_element(child, ctx)
+ ├─ rect / circle / ellipse / line → prstGeom (preset shapes)
+ ├─ rect with rx==ry → prstGeom roundRect (with adj value)
+ ├─ rect with rx!=ry → custGeom (Bézier per 90° arc)
+ ├─ path → custGeom (path commands → moveTo/lnTo/cubicBezTo/arcTo)
+ ├─ polygon / polyline → custGeom
+ ├─ text → txBody with run-level formatting
+ ├─ image → blipFill picture, with srcRect for slice cropping
+ └─ g → grpSp (group) with nested xfrm
+ ↓
+pptx_builder assembles slides → exports/<name>_<ts>.pptx
+```
+
+**Why per-element dispatch and not whole-file translation?** SVG's hierarchical model maps cleanly to DrawingML's group / shape / picture types. An element-level dispatcher means each shape kind has its own narrow translator (`drawingml_elements.py` is ~1500 lines of focused converters), debuggable and testable in isolation. There is no global SVG-to-PPTX optimizer — every shape converts independently, and the final PowerPoint file's quality is the sum of those local conversions.
+
+**Two pre-processing steps in memory.** Native pptx reads `svg_output/` directly (no `svg_final/` hop), but DrawingML can't handle two SVG features inline:
+
+- `<use data-icon="...">` placeholders — DrawingML doesn't know `<use>`, so `use_expander.py` calls `svg_finalize.embed_icons` to expand them into raw paths in memory before dispatch
+- positional `<tspan>` (with x/y/non-zero dy) — DrawingML text runs cannot reposition mid-paragraph; `tspan_flattener.py` calls `svg_finalize.flatten_tspan` to promote each positional tspan to an independent `<text>` element
+
+This is the "memory consumer" relationship described in the Post-Processing Pipeline section above.
+
+**Office compatibility mode (default on).** PowerPoint versions before 2019 can't render SVG natively. The converter generates a PNG fallback for each slide (via svglib + reportlab) and embeds it as a fallback alongside the native shapes. Newer Office still shows editable shapes; older Office shows the PNG. `--no-compat` disables this fallback.
+
+---
+
+## Animation & Transition Model
+
+PPT Master maps two layers of motion:
+
+**Page transitions** (`-t` flag) — applied between slides. Available effects: `fade` (default), `push`, `wipe`, `split`, `strips`, `cover`, `random`. Implemented as `<p:transition>` elements in slide XML. `none` disables.
+
+**Per-element entrance animations** (`-a` flag) — applied to top-level `<g id="...">` groups in z-order. Default `mixed` cycles through a curated visible-effect pool deterministically (first group always `fade`, then varied across the deck) to give visual variety without per-page configuration. Other choices: a single named effect, `random`, or `none`.
+
+Why anchor on top-level `<g>` groups? PowerPoint's animation timeline is shape-keyed — each animated object needs a stable shape ID. Top-level groups are the natural granularity (one logical content block per group), and Executor is required to use `<g id="...">` grouping anyway (memory rule). Aim for 3-8 content groups per slide; pages with no top-level groups fall back to top-level visible primitives, capped at 8.
+
+**Page chrome is auto-skipped.** Animation skips groups whose `id` matches `background` / `header` / `footer` / `decoration` / `watermark` / `page_number` tokens — these are static frame elements that shouldn't fly in.
+
+**Start mode** (`--animation-trigger`) mirrors PowerPoint's animation-pane Start dropdown:
+
+- `after-previous` (default) — cascade on slide entry, gap controlled by `--animation-stagger` (default 0.5s). Click-free.
+- `with-previous` — all groups start together on slide entry
+- `on-click` — one click per group, presenter-paced
+
+**Recorded narration.** Optional layer for video export. `notes_to_audio.py` generates per-slide audio (edge-tts default; cloud TTS providers like ElevenLabs / MiniMax / Qwen / CosyVoice opt-in) from `notes/*.md`. `svg_to_pptx --recorded-narration audio` embeds the audio per slide and sets auto-advance timings from each clip's duration, producing a deck PowerPoint can export to video using "use recorded timings and narrations".
+
+The full animation effect list, anchor logic, and chrome-skip tokens live in `references/animations.md`.
+
+---
+
+## Standalone Workflows
+
+The repository ships four workflows that are **not part of the main deck-generation pipeline**. Each is opt-in, triggered by a specific user need or content shape, and runs independently from the Strategist → Executor flow.
+
+| Workflow | Path | When to use |
+|---|---|---|
+| `create-template` | `workflows/create-template.md` | One-shot ingestion: turn a reference PPTX into a reusable template under `templates/layouts/` |
+| `verify-charts` | `workflows/verify-charts.md` | Insert between Executor and post-processing **only if** the deck contains data charts (bar / line / pie / radar). Calibrates chart coordinate math that AI routinely gets off by 10–50 px |
+| `visual-edit` | `workflows/visual-edit.md` | Post-export iteration. When the user vaguely points at "something looks off" on a generated slide, the workflow opens a browser-based visual editor for fine-grained edits. Skipped when the user describes the change with enough specificity to apply directly |
+| `generate-audio` | `workflows/generate-audio.md` | Recorded narration for video export. Picks a TTS backend (edge-tts default; cloud providers like ElevenLabs / MiniMax / Qwen / CosyVoice opt-in), generates per-slide audio from `notes/*.md`, optionally re-exports the PPTX with `--recorded-narration audio` so PowerPoint's video export uses the recorded timings |
+
+**Why these are workflows and not pipeline steps.** Each one solves a sharply scoped problem that doesn't apply to most decks:
+
+- `create-template` is a one-time setup activity per template, not per deck
+- `verify-charts` only matters for decks with data visualizations
+- `visual-edit` is reactive (responding to a specific complaint), not proactive
+- `generate-audio` is a downstream addition (video export), not deck construction
+
+Folding any of them into the default pipeline would either run unnecessary steps for most users (adding latency and failure surface) or force a one-size-fits-all narrowing. Keeping them opt-in lets the main pipeline stay tight while still offering the capability when the user needs it. Each workflow has its own self-contained `workflows/<name>.md` that the agent loads on demand — there is no global registry the agent must consult ahead of time.
diff --git a/docs/zh/technical-design.md b/docs/zh/technical-design.md
index 696b9550..5b142c24 100644
--- a/docs/zh/technical-design.md
+++ b/docs/zh/technical-design.md
@@ -8,7 +8,7 @@
生成的 PPTX 是一份**设计稿**,而非成品。把它理解成建筑师的效果图:AI 负责视觉设计、排版布局和内容结构,交付给你一个高质量的起点。要想获得真正精良的成品,**需要你自己在 PowerPoint 里做精装修**:换掉形状、细化图表、调整配色、把占位图形替换成原生对象。这个工具的目标是消除 90% 的从零开始的工作量,而不是替代人在最后一公里的判断。不要指望 AI 一遍搞定所有——好的演示文稿从来不是这样做出来的。
-**工具的上限是你的上限。** PPT Master 放大的是你已有的能力——你有设计感和内容判断力,它帮你快速落地;你不知道一个好的演示文稿应该长什么样,它也没法替你知道。输出的质量,归根结底是你自身品味与判断力的映射。
+**工具的上限是你的上限。** PPT Master 放大的是你已有的能力——你有设计感和内容判断力,它帮你快速落地;你不知道一个好的演示文稿应该长什么样,它也没法替你知道。输出的质量,归根结底是你自身品味与判断力的映射。
---
@@ -27,7 +27,7 @@
↓
[Strategist] 策略师 - 八项确认与设计规范 → design_spec.md + spec_lock.md
↓
-[Image_Generator] 图片生成师(当选择 AI 生图时)
+[Image Acquisition] 图片获取(当资源列表中有需要 AI 生成或网络搜索的图片时)
↓
[Executor] 执行师
├── 视觉构建:连续生成所有 SVG 页面 → svg_output/
@@ -91,3 +91,385 @@ SVG 胜出,因为它与 DrawingML 拥有相同的世界观:两者都是绝
转换不是格式错配,而是两种方言之间的精确翻译。
SVG 也是唯一同时满足流程中所有角色需要的格式:**AI 能可靠地生成它,人能在任意浏览器里直接预览和调试,脚本能精确地转换它**——在生成任何 DrawingML 之前,设计稿就已经完全透明可见。
+
+---
+
+## 源内容转换
+
+源内容转换对大多数用户不可见,但塑造了下游一切:源文档(PDF / DOCX / EPUB / XLSX / PPTX / 网页)在流水线启动前先被归一化为 Markdown。这份 Markdown 随后成为 Strategist 的阅读材料,是后续所有决策的事实源。
+
+两个贯穿性的设计选择塑造了转换器:
+
+**Native-Python 优先,外部二进制兜底。** `doc_to_md.py` 用 `mammoth` 处理 `.docx`、`markdownify` + `beautifulsoup4` 处理 `.html`、`ebooklib` 处理 `.epub`、`nbconvert` 处理 `.ipynb`——全是纯 Python wheel。Pandoc 仅在长尾格式(`.doc` / `.odt` / `.rtf` / `.tex` / `.rst` / `.org` / `.typ`)时被调用。PDF 主走 `PyMuPDF`(原生文本 PDF),扫描件才推荐 MinerU / OCR 工具。理由:避免每个用户都要安装可能没有权限装的系统级二进制,同时仍覆盖边缘场景。
+
+**TLS 指纹模拟应对高安全站点。** `web_to_md.py` 默认用 `curl_cffi` 模拟现代 Chrome 的 TLS 指纹。这一个依赖让同一个脚本能搞定微信公众号(`mp.weixin.qq.com`)和其他屏蔽 Python 默认 `requests` TLS 握手的 CDN。Node.js 兄弟脚本 `web_to_md.cjs` 仅作为 `curl_cffi` 没有预编译 wheel 的环境兜底。
+
+所有转换器产出统一约定:`<input>.md` 加一个同级 `<input>_files/` 目录,里面放抽取出的图片,相对路径引用。这个约定正是项目初始化阶段 `import-sources --move` 的工作前提。
+
+---
+
+## 项目结构与生命周期
+
+PPT Master 项目是一个**形状固定**的目录:
+
+```
+projects/<name>_<format>_<timestamp>/
+├── sources/ # import-sources 之后的原始输入
+├── images/ # AI 生成 + 网络搜到 + 用户提供的图片
+├── templates/ # 可选模板 SVG / design_spec_reference
+├── design_spec.md # 人类可读的设计叙述(Strategist 输出)
+├── spec_lock.md # 机器可读的执行契约(Strategist 输出)
+├── notes/ # speaker notes,由 total_md_split.py 按页拆分
+├── svg_output/ # Executor 手写的 SVG 页面(事实源)
+├── svg_final/ # 后处理后的自包含 SVG(IDE 预览用)
+├── exports/ # 最终的 native pptx
+└── backup/<ts>/ # svg_to_pptx 产生的时间戳快照
+```
+
+`project_manager.py init` 创建这个骨架;`import-sources` 是把源文件搬入 `sources/` 的唯一合法路径。两套 import 语义都重要:
+
+- **仓库外**的文件:默认 copy(保留用户原件);`--move` 强制消费
+- **仓库内**的文件:默认 move(避免遗留 stray artifact 被误提交);`--copy` 强制 copy
+
+这种不对称是有意为之。每种上下文中默认行为正好匹配自然的风险画像——仓库外的文件一般是用户资产,不该动;仓库内的文件一般是中间产物,应该清理掉。
+
+`batch_validate.py` 用于发版前的仓库级健康检查;`error_helper.py` 给常见的项目结构错误提供标准化修复,让 AI 在流水线中途从 broken 状态自恢复。
+
+---
+
+## Canvas 格式系统
+
+PPT Master 不只服务 PPT。同一套 SVG → DrawingML 流水线可以产出方形海报、9:16 故事、A4 印刷品——只需改 `viewBox`。九种 canvas 格式覆盖常见内容用途:
+
+| 格式 | viewBox | 比例 | 用途 |
+|---|---|---|---|
+| `ppt169` | 1280×720 | 16:9 | 现代演示 |
+| `ppt43` | 1024×768 | 4:3 | 传统投影仪 / 学术 |
+| `xiaohongshu` | 1242×1660 | 3:4 | 小红书知识帖 |
+| `moments` | 1080×1080 | 1:1 | 朋友圈 / IG 方图 |
+| `story` | 1080×1920 | 9:16 | 抖音 / Stories |
+| `wechat_article` | 900×383 | 2.35:1 | 微信公众号头图 |
+| `banner` | 1920×1080 | 16:9 | 网页 / 数字屏 |
+| `poster` | 1080×1920 | 9:16 | 手机 / 电梯广告 |
+| `a4` | 1240×1754 | 1:√2 | 印刷 |
+
+viewBox 维度是像素值,不是绝对单位(EMU 在 PPTX 导出时计算)。像素 viewBox 让 AI Executor 更容易思考布局(`x="100"` 明确就是左缘 +100px),人类在浏览器里检查也容易。到 PowerPoint EMU 的换算只发生一次——在 `svg_to_pptx` 中,按规范的 EMU/px 比率(914400 EMU/inch ÷ 96 px/inch = 9525 EMU/px)。
+
+各方向的布局原则不同:
+
+- **横版(16:9 / 4:3 / 2.35:1)** —— Z 字形视觉流,多列 / 左右分栏 / 网格布局,40-80px 边距
+- **竖版(3:4 / 9:16)** —— 自上而下流动,单列 / 上下分栏 / 卡片堆叠,60-120px 边距
+- **方形(1:1)** —— 中心放射,约 800px 核心区域,60-100px 边距
+
+每种格式还有特定的设计约定(PPT 的页码位置、小红书的品牌区、Stories 的安全区)——这些在 `references/canvas-formats.md` 里供 Executor 使用。
+
+---
+
+## 模板系统与可选路径
+
+模板是一条**可选路径**,不是默认。Strategist 阶段的默认流程是**自由设计**——开放画布,AI 完全凭源内容创造视觉系统。只有当用户显式触发时才进入模板路径:点名某个具体模板、点名某种映射到模板的品牌或风格、或问"有哪些模板"。
+
+**为什么默认自由设计。** 模板是地板,但很容易变成天花板——它会把整个 deck 锁进模板自有的视觉惯用语。AI 擅长生成与内容节奏匹配的原创布局;把它约束在模板里,常常比让它自由设计更不贴合。所以 AI 从不主动推荐模板——用户必须自己提出。
+
+**软提示机制。** 当源内容明显强匹配某个现有模板(学术答辩、政府报告、麦肯锡风 deck),且用户没有触发模板路径,Strategist 会发一句**非阻塞**提示:*「库里有个模板 `<name>` 跟这个场景非常贴合。需要的话说一声;否则我继续按自由设计走。」* 这是提示,不是问题——不等待,继续生成。弱匹配或模糊匹配时跳过。
+
+**三个模板库。** `templates/` 目录托管三个角色不同的库:
+
+| 库 | 路径 | 提供什么 | 何时使用 |
+|---|---|---|---|
+| 布局 | `templates/layouts/<name>/` | 整 deck 模板:SVG 页面 + `design_spec_reference.md` + 资产 | Opt-in,仅在用户触发时 |
+| 图表 | `templates/charts/<name>.svg` | 可复用可视化 SVG(图表、信息图、流程图、框架图) | 每个 Executor 都引用,含图表的页面 |
+| 图标 | `templates/icons/<library>/` | 三个图标库(`chunk-filled` / `tabler-filled` / `tabler-outline`)——根据内容调性每个 deck 选一个 | 每个 deck 必选其一;不能混用 |
+
+图表库和图标库是每个 Executor 都会引用的,跟是否选了布局模板无关;布局模板才是 opt-in 的那部分。
+
+**新建模板。** `create-template` standalone workflow 接受一份参考 PPTX,外部化它的资产,推断主题色和排版,输出 SVG 幻灯片 + manifest 到 `<pptx_stem>_template_import/`。这是一次性 ingestion 流程,不在 deck 生成流水线里。从 PPTX 原生导出 SVG 是 Windows-only(用安装的 PowerPoint COM);macOS 走 Keynote → PDF → SVG 兜底。
+
+---
+
+## 角色系统:单一流水线中的三个专业代理
+
+PPT Master 用的是**单主代理内的角色切换**,而不是并行子代理。三个角色,一份连续上下文,串行执行:
+
+```
+Strategist → Image Acquisition(条件触发) → Executor
+ ↓ ↓ ↓
+design_spec.md images/*.png svg_output/*.svg
+spec_lock.md image_prompts.md notes/total.md
+ image_sources.json
+```
+
+Image Acquisition 阶段按每行的 `Acquire Via` 派发到两个**独立的子角色**:`ai` 行走 `image-generator`(AI 生成),`web` 行走 `image-searcher`(网络搜索)。两者按需懒加载——纯 `ai` 行的 deck 永远不会读 `image-searcher.md`。详见下面的「图片获取与嵌入」一节。
+
+**为什么是单代理而非并行子代理?** 页面设计依赖完整的上游上下文——Strategist 的色彩选择、是否成功获取了图片资源、之前几页的视觉节奏。SKILL.md 明确禁止把页面 SVG 生成委托给子代理(全局执行纪律第 6 条)。串行逐页生成在一份连续 pass 里完成是被强制的(第 7 条)——分组(如每 5 页一批)是禁止的,因为它会加速上下文压缩并破坏视觉一致性。
+
+**为什么用角色专属 reference 而不是一个超大 prompt?** 每个角色有自己的 `references/<role>.md`,指令聚焦。把它们全混在一个 prompt 里,会强迫模型在同一个 turn 里同时切换 Strategist 的「跟用户协商」模式和 Executor 的「产出严格 XML」模式——这两个模式想要的温度、格式纪律、容错度都不同。
+
+**Eight Confirmations(八项确认)。** Strategist 阶段以八项打包确认(画布 / 页数 / 受众 / 风格 / 配色 / 图标 / 排版 / 图像)作为终点,作为**单一阻塞决策点**呈现给用户。确认后所有后续阶段自动运行,不再有用户卡点。这是 deck 生成流程中**唯一**的阻塞 checkpoint——其他都是程序性的。
+
+**用户已有图片的分析(条件触发,在八项确认之前)。** 当用户随源文档一并提供了图片时,Strategist **必须**先跑 `analyze_images.py <project>/images`,再起草 `design_spec.md`。脚本提取每张图的尺寸、EXIF 方向、主色调和主体元信息,输出一份文本化摘要。Strategist 在这份摘要上做推理——SKILL.md 的图像处理规则禁止直接打开图片字节,因为 LLM 做布局决策不需要像素,需要的是能塞进一页的元数据(用宽高比定位置、用色调判定调色板兼容性、用主体决定哪页放)。输出喂入 `design_spec.md` 里的图片资源列表,让八项确认建立在真实资产上,而不是仅靠文件名猜。
+
+**逐页 spec_lock 重读。** 生成每一页 SVG 之前,Executor 必须重读 `spec_lock.md`。这是显式的抗漂移机制,让系统能在 LLM 上下文窗口有损的情况下产出 20 页 deck 仍保持一致的色彩 / 字体 / 图标纪律。
+
+三种 Executor 风格分散在不同的 reference 文件里——`executor-general.md` / `executor-consultant.md` / `executor-consultant-top.md`——按用户选定的风格加载。每次只加载相关风格文件加上共享的 `executor-base.md` 和 `shared-standards.md`,让上下文负载最小。
+
+---
+
+## 执行纪律
+
+流水线由 SKILL.md 的全局执行纪律 8 条规则强制执行。它们看起来很官僚,但每一条都关闭了一个实际观察到的失败模式。
+
+| # | 规则 | 禁止什么 | 为什么 |
+|---|---|---|---|
+| 1 | **串行执行** | 跳步或乱序 | 每一步的输出是下一步的输入;乱序会静默使用过期或缺失的输入 |
+| 2 | **BLOCKING = 硬停** | 在 `⛔ BLOCKING` checkpoint(八项确认)越权决策 | 用户必须拥有设计决策权;AI 代为做主会让 deck 偏离用户意图 |
+| 3 | **无跨阶段打包** | 把多个阶段合进一个 turn | 想一次性做完 Strategist + Executor 的 LLM 会在正确性或风格上漂移 |
+| 4 | **进入前过门** | 在前置条件未满足时启动一步 | 每步都列出 🚧 GATE 前置条件;检查它们能阻止级联错误 |
+| 5 | **无投机执行** | 提前准备后续步骤的内容(比如在 Strategist 阶段写 SVG) | 前一阶段的输出可能让那些预先准备作废;浪费上下文还制造不一致 |
+| 6 | **不允许子代理生成 SVG** | 把页面 SVG 生成委托给子代理 | 页面设计需要完整的上游上下文(色彩选择、之前的视觉节奏、可用图片);子代理开始时只有过期的部分上下文 |
+| 7 | **仅串行逐页生成** | 分批生成(比如 5 页一组) | 分批会加速上下文压缩,并破坏 deck 的视觉一致性 |
+| 8 | **逐页 spec_lock 重读** | 生成一页 SVG 而不重读 `spec_lock.md` | 抵抗长 deck 中的上下文压缩漂移——第 18 页的颜色必须跟第 1 页一致 |
+
+**角色切换协议。** 当 agent 切换角色(Strategist → Executor 等)时,必须先 `read_file references/<role>.md` 并输出 markdown 标记:
+
+```
+## [Role Switch: <Role Name>]
+📖 Reading role definition: references/<filename>.md
+📋 Current task: <brief description>
+```
+
+这有两个作用:强制把新鲜的角色指令载入上下文(覆盖任何前一个角色模式的漂移),并在对话 transcript 中创建审计轨迹,让用户能看到 agent 何时切换了模式。
+
+这套纪律刻意做得很显式,因为 LLM 默认行为是「让我在这一 turn 里把整个问题搞定」——而这恰好是串行流水线最不该有的形状,串行流水线要求每一步都依赖前一步**有界且过 checkpoint** 的输出。
+
+---
+
+## 设计规范的传播:spec_lock.md 作为执行契约
+
+Strategist 阶段产出两份看起来冗余但服务不同对象的产物:
+
+- `design_spec.md` —— 人类可读叙述;设计的「为什么」(目标受众、风格目标、配色理由、页面大纲)
+- `spec_lock.md` —— 机器可读执行契约;Executor 必须**字面照搬**的「是什么」(HEX 颜色、确切的 font family 字符串、图标库选择、带状态的图片资源列表)
+
+为什么两份都要?没有 `spec_lock.md` 的话,Executor 在长 deck 里会逐页重读 `design_spec.md`,LLM 上下文压缩漂移会逐渐扭曲色值和字体。`spec_lock.md` 是**抗漂移机制**——SKILL.md 强制要求生成每一页前 `read_file <project>/spec_lock.md`,让数值在 20+ 页里保持字面一致。
+
+`update_spec.py` 把生成后的修改用两个协调步骤传播:把新值写入 `spec_lock.md`,然后字面替换到每一份 `svg_output/*.svg`。工具的范围**故意收得很窄**——只支持 `colors.*`(HEX 值,大小写不敏感替换)和 `typography.font_family`(属性级)。其他字段(字号、图标、图片、画布)**有意不支持**——它们的替换需要属性级或语义级理解,风险/收益不值得做批量传播。这些情况手动改 `spec_lock.md` 然后重做受影响的页面。
+
+工具拒绝做备份:依赖 git 回滚。加备份机制只是重复 git 的工作,还会留下过时快照。
+
+---
+
+## 图片获取与嵌入
+
+图片获取阶段是条件触发的。设计 spec 产出一份资源列表,每行图片有 `Acquire Via` 字段:`ai`(AI 生成)/ `web`(网络搜索)/ `user`(已提供)/ `placeholder`(推迟)。只有 `ai` 或 `web` 行触发这一阶段;纯 `user` 的 deck 跳过。这一阶段按每行的 `Acquire Via` 分裂为**两个独立的子角色**——`ai` 行走 `image-generator`,`web` 行走 `image-searcher`。混合 deck 同时加载两份 reference 文件,每行各走自己的路;纯 `ai` 或纯 `web` 的 deck 只加载相应的角色。
+
+**多 backend 图像生成**(`ai` 路径)。`image_gen.py` 是 backend 注册表上的一层薄派发器。Backend 分级:
+
+- **Core** —— 生产可用(OpenAI gpt-image / Google Imagen / MiniMax / Qwen / Volcengine / Zhipu / Gemini)
+- **Extended** —— 用户按需选择的特殊模型
+- **Experimental** —— API 不稳定,仅 opt-in
+
+配置只用 **provider-specific key**(`OPENAI_API_KEY` / `MINIMAX_API_KEY` / `GEMINI_API_KEY` / ...)。`IMAGE_API_KEY` / `IMAGE_MODEL` / `IMAGE_BASE_URL` 这种 generic 字段被故意拒绝——它们在 `.env` 里配多个 provider 时会造成静默混乱。当前 backend 必须通过 `IMAGE_BACKEND=<name>` 显式选定。
+
+**带 license 纪律的网络图片搜索**(`web` 路径)。`image_search.py` 是姊妹工具,资源列表里 `Acquire Via: web` 时使用。默认链:免配置 provider(Openverse、Wikimedia)→ 配置了 key 的 provider(Pexels、Pixabay)。License 过滤默认宽松(CC0 / PDM / Pexels / Pixabay / CC BY / CC BY-SA)——选定图片是 `attribution-required` 时 Executor 会加内联致谢。`--strict-no-attribution` 限制为零致谢的 license,用于全屏 hero image(视觉上没有放致谢的位置)。自动拒绝:任何 NC(非商用 CC BY-NC*)或 ND(禁止演绎 CC BY-ND*)。来源记录在 `image_sources.json`(provider / license / author / source URL / dimensions / attribution_text),按 filename 幂等。
+
+**嵌入策略。** 开发期间,图片在 `svg_output/` 中保持**外部引用**——快速迭代、易于替换。`finalize_svg.py` 的 `align-images` 步骤把它们 Base64 内联到 `svg_final/`,因为 IDE / 浏览器 / preview pptx 都需要自包含文件。Native pptx 转换器**不**做 Base64 内联——它把位图文件复制到 PPTX 的 media 文件夹,并通过 `<a:srcRect>` 在 DrawingML 中表达 SVG 的 `preserveAspectRatio="... slice"` 裁剪。两条路径——外部引用便于调试,嵌入 payload 适合交付——共存是设计如此。
+
+---
+
+## SVG 约束:禁用特性与条件允许
+
+PowerPoint 的 DrawingML 是 SVG 表达能力的严格子集。Executor 在一个**禁用特性黑名单**里运行,这份黑名单是从 PPT 导出失败的经验积累中归纳出来的:
+
+**硬禁用(否则导出会坏):**
+- `<mask>` —— DrawingML 没有像素级 alpha
+- `<style>` / `class` —— DrawingML 没有 CSS 选择器模型
+- 外部 CSS / `@font-face` —— 字体必须系统可安装,不能用文件加载
+- `<foreignObject>` —— SVG 内嵌 HTML 没有 DrawingML 映射
+- `<symbol>` + `<use>` 的通用复用 —— DrawingML 没有 symbol 模型(图标 `<use data-icon>` 是项目内部约定,会在转换前展开,不算 symbol)
+- `textPath` —— 文字沿任意路径没有 DrawingML 原语
+- `<animate*>` / `<set>` —— SVG 动画;PowerPoint 动画是单独的时序模型,写在 slide XML
+- `<script>` / 事件属性 / `<iframe>` —— 交互性是另一层
+
+**XML 良构性:**
+- 所有文本和属性值的排版字符(`—` / `→` / `©` / NBSP)必须用**裸 Unicode**——HTML 命名实体(`&mdash;` / `&rarr;`)在 SVG 里是非法 XML
+- XML 保留字符(`& < > " '`)必须用 XML 实体(`&amp;` 等)——裸 `R&D` 直接终止导出
+
+**条件允许(精确约束集见 `references/shared-standards.md`):**
+- `<line>` / `<path>` 上的 `marker-start` / `marker-end` —— 仅当 marker 形状能干净映射到 DrawingML 三种箭头原语之一(triangle / diamond / oval),且 marker 填色与 line stroke 颜色匹配
+- `<image>` 上的 `clip-path` —— 仅当 clip 形状是单一 circle / ellipse / rect / path / polygon 时允许,映射到 DrawingML picture 几何。非 image 元素上的 clip 是禁用的(一个 rect 被 clip 成 circle 不如直接是个 circle)
+
+**效果路由。** 因为 `<mask>` 被禁,常见视觉效果走不同的路:
+
+| 效果 | 替代方案 |
+|---|---|
+| 图片渐变叠加(vignette / fade / 着色) | 堆叠 `<rect>` + `<linearGradient>` / `<radialGradient>` |
+| 非矩形图片裁剪 | `clipPath` 作用于 `<image>` |
+| 内发光 / 软边 | `<filter>` + `<feGaussianBlur>` |
+| 投影 | filter shadow 或分层 rect |
+| 像素级 alpha(文字镂空填充、任意 alpha 合成) | **PPT 没有路径**——在 Image Acquisition 阶段烘焙到源图 |
+
+`svg_quality_checker.py` 在后处理之前强制执行这份黑名单——任何禁用特性都是阻塞错误,必须由 Executor 重新生成相关页面来修复。
+
+---
+
+## 质量门
+
+`svg_quality_checker.py` 在 Executor 完成所有页面之后、任何后处理之前运行。位置是有意安排的:后处理会重写 SVG(图标嵌入、图片内联),会掩盖源级别的违规。检查器只读 `svg_output/`。
+
+**它检查什么:**
+
+- **`viewBox`** —— 存在且匹配项目的 canvas 格式。不匹配会让脚本默认的「画布是规范像素空间」假设静默失效。
+- **禁用特性** —— SVG 黑名单的每一条(mask / style / class / foreignObject / symbol+use / textPath / @font-face / animate* / script / iframe)。任何命中都是阻塞错误。
+- **width/height 一致性** —— `<svg>` 根属性匹配 viewBox 维度。
+- **换行结构** —— 多行 `<text>` 用定位的 `<tspan>`(带 x + dy),而不是 `\n` 字符或兄弟 text 漂移。
+- **spec_lock 漂移** —— SVG 中的颜色 / 字体 / 图标 / 图片必须来自 `spec_lock.md`。off-spec 值是 warning(有时合理)或 error(暗示 Executor 跑偏了)。
+- **低分辨率图片 / 非 PPT 安全字体尾部** —— soft warning;能直接修就修,否则确认后放行。
+
+**严重性模型:** error 阻塞流水线(重新生成出错的页面);warning 提示但不阻塞。**有意没有 auto-fix 模式**——修复一个禁用特性需要 Executor 在上下文里重新写页面,不是机械的 patch。
+
+**为什么需要这层。** LLM 生成的 SVG 不是确定性的。没有检查器的话,禁用特性会在长 deck 中悄悄混入,只在 `svg_to_pptx` 中途崩或 PowerPoint 静默丢元素时才暴露。检查器把「PowerPoint 导出在第 14 页崩溃」转化为「Executor 在第 14 页用了 `<style>`,重新生成它」——诊断速度提升一个数量级。
+
+质量检查器也是**图表坐标验证**(`verify-charts` workflow)的天然插入点。图表页面有几何正确性需求(柱状图高度 / 饼图扇形角 / 坐标轴刻度位置),这些不是结构问题,SVG 合法性规则也抓不到。`svg_position_calculator.py` 从数据计算期望坐标,workflow 让 AI 对比并修复不一致,再继续后处理。
+
+---
+
+## 后处理流水线
+
+> 工程化转换阶段中每一份产物和每一个模块为何存在,删除它会破坏哪些工作流。在考虑简化 `svg_final/` / `finalize_svg.py` / `svg_to_pptx.py` 之前,先读这一节。
+
+### 四份产物,四种工作流
+
+后处理阶段产生四份产物。每一份都服务于一种流水线中无法替代的工作流。
+
+| 产物 | 服务的工作流 | 为何无可替代 |
+| --- | --- | --- |
+| `svg_output/` | 唯一源、手工编辑入口、`update_spec.py`、`svg_quality_checker.py` | 流水线中唯一**手写**而非派生的目录 |
+| `svg_final/` | IDE 内即时预览(VSCode/Cursor 直接打开 `.svg`)、浏览器单页预览 | `.pptx` 在 IDE 里打不开;`svg_output/` 因图标 / 图片是外部引用,IDE 中渲染不完整 |
+| `exports/<name>_<ts>.pptx`(native) | 主交付物——PowerPoint 中以 DrawingML 形状形态可编辑 | 唯一一份用户可在 PowerPoint 中原生改尺寸 / 改色 / 改样式的产物 |
+| `backup/<ts>/<name>_svg.pptx`(preview) | 跨平台单文件分发、整体多页浏览、邮件附件 | 自包含、多页、PowerPoint / Keynote / WPS / LibreOffice 都能直接打开;`svg_final/` 是文件夹,分发不便 |
+
+### `svg_finalize/` 包有**两种**消费者
+
+这是读代码时容易忽略的关键事实。同一组 `skills/ppt-master/scripts/svg_finalize/` 下的模块,在两个地方被使用,服务两份不同的产物。
+
+**写盘消费者** —— `finalize_svg.py` 每次运行都把 `svg_output/` → `svg_final/` 写到磁盘一次。`svg_final/` 随后供 IDE 预览和 preview pptx 使用。
+
+**内存消费者** —— native pptx 直接读 `svg_output/`(不经磁盘中转),但 DrawingML 无法内联处理两种 SVG 特性,所以转换器在内存中调用 `svg_finalize` 模块:
+
+| 内存调用点 | 复用的模块 | native pptx 为何需要 |
+| --- | --- | --- |
+| `svg_to_pptx/use_expander.py` | `svg_finalize.embed_icons` | DrawingML 不识别 `<use data-icon="...">`;不展开图标会静默丢失 |
+| `svg_to_pptx/tspan_flattener.py` | `svg_finalize.flatten_tspan` | DrawingML 文本块无法在段落中跳位置;`dy` 堆叠的多行 `<tspan>` 会塌成一行,`x` 锚定的 tspan 会跑到错误的列 |
+
+### 各模块消费者一览
+
+| 模块 | 写盘消费者 | 内存消费者 | 删除影响 |
+| --- | --- | --- | --- |
+| `embed_icons.py` | `finalize_svg` 的 `embed-icons` 步骤 | `svg_to_pptx/use_expander.py` | native pptx 丢失全部图标 + `svg_final/` 不再自包含 |
+| `flatten_tspan.py` | `finalize_svg` 的 `flatten-text` 步骤 | `svg_to_pptx/tspan_flattener.py` | **native pptx 中 `dy` 堆叠的多行文本塌成一行** |
+| `align_embed_images.py` | `finalize_svg` 的 `align-images` 步骤 | — | `svg_final/` 失去图片嵌入 → IDE 预览 / preview pptx 都没图 |
+| `crop_images.py` / `embed_images.py` / `fix_image_aspect.py` | 被 `align_embed_images.py` import | — | `align_embed_images` `ImportError`,整条链路 broken |
+| `svg_rect_to_path.py` | `finalize_svg` 的 `fix-rounded` 步骤 | — | 只影响 PowerPoint 内手动「Convert to Shape」时圆角丢失;浏览器 / IDE / PowerPoint 自带的 SVG 渲染器都正常 |
+
+### FAQ ——「这个能删吗?」
+
+| 问题 | 简答 | 原因 |
+| --- | --- | --- |
+| 能删 legacy / preview pptx 吗? | **不能** | 跨平台单文件分发、多页整体浏览备份——这两种工作流,`svg_final/`(文件夹)和 native pptx 都满足不了 |
+| 能删 `svg_final/` 吗? | **不能** | IDE 内即时预览—— `.pptx` 在 VSCode / Cursor 里打不开;`svg_output/` 因外部引用在 IDE 中渲染不完整 |
+| 能删 `finalize_svg.py` 吗? | **不能** | `svg_final/` 没有其他生成入口;子模块仍被 native 转换器在内存中复用 |
+| 能删 `svg_finalize/{flatten_tspan, embed_icons}` 吗? | **不能——native pptx 会坏** | 见「两种消费者」一节 |
+| 能删 `svg_finalize/{crop, embed, fix_image_aspect}_images.py` 吗? | **不能** | `align_embed_images.py` import 它们 |
+| 能删 `svg_rect_to_path.py` 吗? | **可以考虑** | 仅为 PowerPoint 手动「Convert to Shape」圆角兜底而保留;价值边缘;目前留着是为了避免少数手动场景下静默回归 |
+
+### 编辑规则
+
+- 只编辑 `svg_output/` —— `svg_final/` 每次运行 `finalize_svg.py` 都会重新生成
+- 编辑完 `svg_output/` 后,重跑 `finalize_svg.py` 让 IDE 预览的 `svg_final/` 同步刷新
+- `update_spec.py` 只动 `svg_output/` —— spec 改完后重跑 `finalize_svg.py`,让 `svg_final/` 反映变更
+
+---
+
+## Native PPTX 转换器内部
+
+`svg_to_pptx/` 把 SVG 翻译成 DrawingML,逐元素地。映射表很大——用户面向版本看 `references/shared-standards.md`——但架构是这样的:
+
+```
+svg_output/*.svg
+ ↓
+[parse 成 ElementTree]
+ ↓
+[内存中预处理]
+ ├─ use_expander ← svg_finalize.embed_icons
+ └─ tspan_flattener ← svg_finalize.flatten_tspan
+ ↓
+[逐元素派发] drawingml_converter.convert_element(child, ctx)
+ ├─ rect / circle / ellipse / line → prstGeom(preset 形状)
+ ├─ rect with rx==ry → prstGeom roundRect(带 adj 值)
+ ├─ rect with rx!=ry → custGeom(每 90° 弧用 Bézier)
+ ├─ path → custGeom(path 命令 → moveTo/lnTo/cubicBezTo/arcTo)
+ ├─ polygon / polyline → custGeom
+ ├─ text → txBody,run 级格式化
+ ├─ image → blipFill picture,slice 裁剪用 srcRect
+ └─ g → grpSp(group),嵌套 xfrm
+ ↓
+pptx_builder 拼装幻灯片 → exports/<name>_<ts>.pptx
+```
+
+**为什么是逐元素派发而不是整体翻译?** SVG 的层级模型干净地映射到 DrawingML 的 group / shape / picture 类型。元素级派发让每种形状都有自己窄的翻译器(`drawingml_elements.py` 约 1500 行聚焦的转换器),可单独调试和测试。没有全局的 SVG-to-PPTX 优化器——每个形状独立转换,最终 PPT 文件的质量是这些局部转换的总和。
+
+**两个内存中的预处理步骤。** Native pptx 直接读 `svg_output/`(不经 `svg_final/` 中转),但 DrawingML 不能内联处理两种 SVG 特性:
+
+- `<use data-icon="...">` 占位符——DrawingML 不识别 `<use>`,所以 `use_expander.py` 调用 `svg_finalize.embed_icons` 在内存中把它们展开为原始 path 后再派发
+- 定位的 `<tspan>`(带 x / y / 非零 dy)——DrawingML 文本块无法在段落中跳位置;`tspan_flattener.py` 调用 `svg_finalize.flatten_tspan` 把每个定位 tspan 提升为独立的 `<text>` 元素
+
+这就是上面「后处理流水线」一节描述的「内存消费者」关系。
+
+**Office 兼容模式(默认开启)。** 2019 之前的 PowerPoint 不能原生渲染 SVG。转换器为每页生成一份 PNG 兜底(通过 svglib + reportlab)并嵌入为 fallback,与原生形状并存。新版 Office 仍然显示可编辑形状;旧版显示 PNG。`--no-compat` 关闭这层兜底。
+
+---
+
+## 动画与转场模型
+
+PPT Master 映射两层运动:
+
+**页面转场**(`-t` 标志)—— 应用在幻灯片之间。可用效果:`fade`(默认)/ `push` / `wipe` / `split` / `strips` / `cover` / `random`。在 slide XML 中实现为 `<p:transition>` 元素。`none` 关闭。
+
+**逐元素入场动画**(`-a` 标志)—— 应用在顶层 `<g id="...">` group 上,按 z 序。默认 `mixed` 在精选的可见效果池中确定性循环(每页第一个 group 总是 `fade`,然后跨 deck 多样化)以提供视觉变化而无需逐页配置。其他选择:单一具名效果、`random`、或 `none`。
+
+为什么锚点在顶层 `<g>` group?PowerPoint 的动画时序基于形状 ID——每个被动画的对象需要稳定的 shape ID。顶层 group 是自然的粒度(一个逻辑内容块对应一个 group),而且 Executor 本来就被强制要求用 `<g id="...">` 分组(用户记忆规则)。每页 3-8 个内容 group 比较合理;没有顶层 group 的页面 fallback 到顶层可见原语,上限 8 个。
+
+**页面装饰自动跳过。** 动画跳过 `id` 匹配 `background` / `header` / `footer` / `decoration` / `watermark` / `page_number` 等 token 的 group——这些是静态画面元素,不应该飞入。
+
+**起始模式**(`--animation-trigger`)镜像 PowerPoint 动画窗格的 Start 下拉菜单:
+
+- `after-previous`(默认)—— 进入幻灯片时级联,间隔由 `--animation-stagger` 控制(默认 0.5 秒)。无需点击。
+- `with-previous` —— 所有 group 在进入幻灯片时一起开始
+- `on-click` —— 每个 group 一次点击,演讲者节奏控制
+
+**录制旁白。** 视频导出的可选层。`notes_to_audio.py` 从 `notes/*.md` 生成逐页音频(默认 edge-tts;云 TTS provider 如 ElevenLabs / MiniMax / Qwen / CosyVoice 可选)。`svg_to_pptx --recorded-narration audio` 逐页嵌入音频,并按每个片段时长设置自动推进时序,产出可被 PowerPoint 用「使用录制的时序和旁白」选项导出为视频的 deck。
+
+完整的动画效果列表、锚点逻辑、装饰跳过 token 在 `references/animations.md`。
+
+---
+
+## Standalone Workflows(独立工作流)
+
+仓库随附四个**不在主 deck 生成流水线里**的工作流。每个都是 opt-in 的,由特定的用户需求或内容形态触发,独立于 Strategist → Executor 主流程运行。
+
+| 工作流 | 路径 | 何时使用 |
+|---|---|---|
+| `create-template` | `workflows/create-template.md` | 一次性 ingestion:把参考 PPTX 转成 `templates/layouts/` 下的可复用模板 |
+| `verify-charts` | `workflows/verify-charts.md` | **仅当** deck 含数据图表(柱 / 折 / 饼 / 雷达)时,在 Executor 与后处理之间插入。校准 AI 在数据→像素映射上常见的 10–50px 偏差 |
+| `visual-edit` | `workflows/visual-edit.md` | 导出后迭代。当用户模糊指出"哪里看着不对"时,工作流打开浏览器可视化编辑器做精细编辑。如果用户描述足够具体可以直接修改,则跳过 |
+| `generate-audio` | `workflows/generate-audio.md` | 视频导出用的录制旁白。选 TTS 后端(默认 edge-tts;云端 ElevenLabs / MiniMax / Qwen / CosyVoice 可选),从 `notes/*.md` 生成逐页音频;可选地用 `--recorded-narration audio` 重新导出 PPTX,让 PowerPoint 视频导出用录制好的时序 |
+
+**为什么这些是 workflow 而不是流水线步骤。** 每一个解决的都是范围明确、不适用于大多数 deck 的问题:
+
+- `create-template` 是每个模板一次性的设置活动,不是每个 deck 都要做
+- `verify-charts` 只对含数据可视化的 deck 才有意义
+- `visual-edit` 是被动响应(针对具体投诉),不是主动行为
+- `generate-audio` 是下游附加(视频导出),不是 deck 构造的一部分
+
+把任何一个塞进默认流水线,要么对大多数用户运行无意义的步骤(增加延迟和失败面),要么强制一刀切收窄。保持 opt-in 让主流水线保持紧凑,同时在用户需要时仍提供这些能力。每个 workflow 有自己自包含的 `workflows/<name>.md`,agent 按需加载——没有 agent 必须提前查的全局注册表。
diff --git a/skills/ppt-master/scripts/docs/conversion.md b/skills/ppt-master/scripts/docs/conversion.md
index da53db87..efe03cce 100644
--- a/skills/ppt-master/scripts/docs/conversion.md
+++ b/skills/ppt-master/scripts/docs/conversion.md
@@ -1,5 +1,7 @@
# Conversion Tools
+> Architecture rationale (why native-Python first with pandoc fallback, why curl_cffi for TLS impersonation): see [docs/technical-design.md "Source Content Conversion"](../../../../docs/technical-design.md#source-content-conversion).
+
Source conversion tools turn PDFs, documents, slide decks, and web pages into Markdown before project creation.
## `source_to_md/pdf_to_md.py`
diff --git a/skills/ppt-master/scripts/docs/image.md b/skills/ppt-master/scripts/docs/image.md
index 1150b6d1..39a08a77 100644
--- a/skills/ppt-master/scripts/docs/image.md
+++ b/skills/ppt-master/scripts/docs/image.md
@@ -1,5 +1,7 @@
# Image Tools
+> Architecture rationale (multi-backend dispatcher design, why provider-specific keys only, license filter strategy, embedding strategy): see [docs/technical-design.md "Image Acquisition & Embedding"](../../../../docs/technical-design.md#image-acquisition--embedding).
+
Image tools cover prompt-based AI generation, web image search, image inspection, and Gemini watermark removal.
## `image_gen.py`
diff --git a/skills/ppt-master/scripts/docs/project.md b/skills/ppt-master/scripts/docs/project.md
index e406a487..e3c64a78 100644
--- a/skills/ppt-master/scripts/docs/project.md
+++ b/skills/ppt-master/scripts/docs/project.md
@@ -1,5 +1,7 @@
# Project Tools
+> Architecture rationale (project directory shape, import-sources copy/move asymmetry, batch_validate role): see [docs/technical-design.md "Project Structure & Lifecycle"](../../../../docs/technical-design.md#project-structure--lifecycle).
+
Project tools create, validate, and inspect the standard PPT Master workspace.
## `project_manager.py`
diff --git a/skills/ppt-master/scripts/docs/svg-pipeline.md b/skills/ppt-master/scripts/docs/svg-pipeline.md
index e8ca89df..690a10ab 100644
--- a/skills/ppt-master/scripts/docs/svg-pipeline.md
+++ b/skills/ppt-master/scripts/docs/svg-pipeline.md
@@ -1,5 +1,7 @@
# SVG Pipeline Tools
+> Architecture rationale (why each artifact / step exists, deletion impact, two-consumer relationship between `svg_finalize/` and native pptx conversion): see [docs/technical-design.md "Post-Processing Pipeline"](../../../../docs/technical-design.md#post-processing-pipeline).
+
These tools cover post-processing, SVG validation, speaker notes, recorded narration, and PPTX export.
## Recommended Pipeline
diff --git a/skills/ppt-master/scripts/docs/update_spec.md b/skills/ppt-master/scripts/docs/update_spec.md
index e005321c..93731f9a 100644
--- a/skills/ppt-master/scripts/docs/update_spec.md
+++ b/skills/ppt-master/scripts/docs/update_spec.md
@@ -1,5 +1,7 @@
# update_spec.py
+> Architecture rationale (why narrow scope, why no backups, the spec_lock as execution contract): see [docs/technical-design.md "Spec Propagation"](../../../../docs/technical-design.md#spec-propagation-spec_lockmd-as-execution-contract).
+
Propagate a `spec_lock.md` value change to both the lock file and every `svg_output/*.svg`. The single edit surface for bulk style tweaks after generation.
## Usage
diff --git a/skills/ppt-master/scripts/finalize_svg.py b/skills/ppt-master/scripts/finalize_svg.py
index f7a26685..3417f1b9 100644
--- a/skills/ppt-master/scripts/finalize_svg.py
+++ b/skills/ppt-master/scripts/finalize_svg.py
@@ -6,6 +6,12 @@ Processes SVG files from svg_output/ and outputs them to svg_final/.
By default, all processing steps are executed. You can also specify
individual steps via arguments.
+Architecture note: this module's outputs feed svg_final/ on disk AND its
+sub-modules (svg_finalize.embed_icons, svg_finalize.flatten_tspan, ...)
+are memory-reused by svg_to_pptx during native conversion. Deleting any
+step here may also break native pptx output, not just svg_final/.
+See docs/technical-design.md "Post-Processing Pipeline" before modifying.
+
Usage:
# Execute all processing steps (recommended)
python3 scripts/finalize_svg.py <project_directory>
diff --git a/skills/ppt-master/scripts/svg_finalize/__init__.py b/skills/ppt-master/scripts/svg_finalize/__init__.py
index 8327387b..9acef8ee 100644
--- a/skills/ppt-master/scripts/svg_finalize/__init__.py
+++ b/skills/ppt-master/scripts/svg_finalize/__init__.py
@@ -1 +1,12 @@
-"""Internal SVG finalize helpers used by finalize_svg.py and compatibility wrappers."""
+"""svg_finalize — shared self-containment + DrawingML-compat utilities.
+
+Used by two consumers:
+
+ 1. finalize_svg.py — writes svg_output/ → svg_final/ on disk
+ 2. svg_to_pptx (use_expander, tspan_flattener) — reuses these modules
+ in memory during native pptx conversion
+
+Deleting any module here is likely to break native pptx output, not just
+svg_final/. See docs/technical-design.md "Post-Processing Pipeline" for
+the full per-module consumer table.
+"""