{"id":"a08e6ebb-b3df-45bd-acee-03efe19044ed","entityType":"agent","slug":"clawhub-simon2256928-deckcraft","name":"DeckCraft","canonicalUrl":"https://www.xpersona.co/agent/clawhub-simon2256928-deckcraft","canonicalPath":"/agent/clawhub-simon2256928-deckcraft","generatedAt":"2026-10-10T11:50:57.485Z","source":"CLAWHUB","claimStatus":"UNCLAIMED","verificationTier":"NONE","summary":{"evidence":{"source":"editorial-content","verified":true,"confidence":"high","updatedAt":"2026-10-10T09:00:31.943Z","emptyReason":null},"description":"AI PPT creation skill with structured 5-stage generation, machine-readable QA gates, checkpoint recovery, and experience accumulation. 20 layout methods, nat... Skill: DeckCraft Owner: simon2256928 Summary: AI PPT creation skill with structured 5-stage generation, machine-readable QA gates, checkpoint recovery, and experience accumulation. 20 layout methods, nat... Tags: ai:5.3.0, canvas:5.3.0, docx:5.3.0, importer:5.3.0, latest:6.0.0, pdf:5.3.0, ppt:5.3.0, pptx:5.3.0, presentation:5.3.0 Version history: v6.0.0 | 2026-06-11T12:02:59.632Z | user v6.0.0: PPT Master integration","descriptionLabel":"Technical summary","evidenceSummary":"Capability contract not published. No trust telemetry is available yet. 1.5K downloads reported by the source. Last updated 10/10/2026.","installCommand":"clawhub skill install s1748cg1a8j1ccg72hajzkk8m1846mzf:deckcraft","sourceUrl":"https://clawhub.ai/simon2256928/deckcraft","homepage":"https://clawhub.ai/simon2256928/skills/deckcraft","primaryLinks":[{"label":"View on ClawHub","url":"https://clawhub.ai/simon2256928/deckcraft","kind":"source"},{"label":"Homepage","url":"https://clawhub.ai/simon2256928/skills/deckcraft","kind":"homepage"}],"safetyScore":84,"overallRank":62,"popularityScore":64,"trustScore":null,"claimedByName":null,"isOwner":false,"seoDescription":"AI PPT creation skill with structured 5-stage generation, machine-readable QA gates, checkpoint recovery, and experience accumulation. 20 layout methods, nat..."},"coverage":{"evidence":{"source":"public-profile","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:00:31.943Z","emptyReason":null},"protocols":[{"protocol":"OPENCLEW","label":"OpenClaw","status":"self-declared","notes":"Declared in the public agent profile."}],"capabilities":[],"verifiedCount":0,"selfDeclaredCount":1,"capabilityMatrix":{"rows":[{"key":"OPENCLEW","type":"protocol","support":"unknown","confidenceSource":"profile","notes":"Listed on profile"}],"flattenedTokens":"protocol:OPENCLEW|unknown|profile"}},"adoption":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:00:31.943Z","emptyReason":null},"stars":null,"forks":null,"downloads":1541,"packageName":null,"latestVersion":"6.0.0","tractionLabel":"1.5K downloads"},"release":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"medium","updatedAt":"2026-10-10T09:00:31.943Z","emptyReason":null},"lastUpdatedAt":"2026-10-10T09:00:31.943Z","lastCrawledAt":"2026-10-10T09:00:31.943Z","lastIndexedAt":null,"nextCrawlAt":"2026-10-11T09:00:31.943Z","lastVerifiedAt":null,"highlights":[{"version":"6.0.0","createdAt":"2026-06-11T12:02:59.632Z","changelog":"v6.0.0: PPT Master integration. 37 icon library, URL/WeChat source auto-fetch, CRAP design optimizer, speaker notes, 9 new chart types (funnel/gantt/swot/porter/sankey/heatmap/radar/treemap/waterfall), optional multi-role workflow, 8 new canvas aliases, 14 industry color palettes, image resource manifest. 184 tests pass. python-pptx native preserved (PPTX remains editable). Backward-compatible with v5.3.","fileCount":44,"zipByteSize":113996},{"version":"5.3.0","createdAt":"2026-06-03T04:10:06.762Z","changelog":"v5.3.0: Source importers (PDF via PyMuPDF, DOCX via python-docx, TXT/MD). New CLI scripts/import_source.py converts documents to outline JSON. 34 new importer tests (149 total). 100% backward compatible with v5.2.","fileCount":33,"zipByteSize":71693},{"version":"5.2.0","createdAt":"2026-06-03T03:03:27.942Z","changelog":"test","fileCount":24,"zipByteSize":52890},{"version":"5.1.1","createdAt":"2026-05-19T13:49:30.826Z","changelog":"Fix YAML frontmatter","fileCount":12,"zipByteSize":27686},{"version":"5.1.0","createdAt":"2026-05-19T13:24:50.739Z","changelog":"Native charts, visual QA, all elements editable","fileCount":11,"zipByteSize":26482},{"version":"5.0.2","createdAt":"2026-05-18T13:34:35.996Z","changelog":"v5.0.2 — Audit fix: removed stale experiences/ references in SKILL.md, corrected version headers in gate scripts (v4→v5).","fileCount":11,"zipByteSize":25166},{"version":"5.0.1","createdAt":"2026-05-18T13:26:29.302Z","changelog":"v5.0.1 — Cleaned public release: removed internal experiences, redundant style YAMLs, legacy scripts, and template editing utilities. Core only: engine + gate checks + layout matrix.","fileCount":11,"zipByteSize":25177},{"version":"5.0.0","createdAt":"2026-05-18T13:06:27.762Z","changelog":"v5.0.0 — Major rewrite: DeckEngine rendering engine (20 layout methods, 40+ API), ChartEngine (bar/pie/line/gauge via matplotlib), visual QA pipeline (LibreOffice→PDF→images), machine-readable gate checks (S3 content + S4 QA → JSON output), template editing system (text replacement, image swap, XML sanitize), design spec library (23 layout definitions, 10 theme YAMLs), experience accumulation, checkpoint recovery, 3 anti-patterns, Fast Track mode.","fileCount":31,"zipByteSize":44140}]},"execution":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No published capability contract is available yet."},"installCommand":"clawhub skill install s1748cg1a8j1ccg72hajzkk8m1846mzf:deckcraft","setupComplexity":"low","setupSteps":["Setup complexity is classified as HIGH. You must provision dedicated cloud infrastructure or an isolated VM. Do not run this directly on your local workstation.","Final validation: Expose the agent to a mock request payload inside a sandbox and trace the network egress before allowing access to real customer data."],"contract":{"contractStatus":"missing","authModes":[],"requires":[],"forbidden":[],"supportsMcp":false,"supportsA2a":false,"supportsStreaming":false,"inputSchemaRef":null,"outputSchemaRef":null,"dataRegion":null,"contractUpdatedAt":null,"sourceUpdatedAt":null,"freshnessSeconds":null},"invocationGuide":{"preferredApi":{"snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-simon2256928-deckcraft/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-simon2256928-deckcraft/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-simon2256928-deckcraft/trust"},"curlExamples":["curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-simon2256928-deckcraft/snapshot\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-simon2256928-deckcraft/contract\"","curl -s \"https://www.xpersona.co/api/v1/agents/clawhub-simon2256928-deckcraft/trust\""],"jsonRequestTemplate":{"query":"summarize this repo","constraints":{"maxLatencyMs":2000,"protocolPreference":["OPENCLEW"]}},"jsonResponseTemplate":{"ok":true,"result":{"summary":"...","confidence":0.9},"meta":{"source":"CLAWHUB","generatedAt":"2026-10-10T11:50:57.482Z"}},"retryPolicy":{"maxAttempts":3,"backoffMs":[500,1500,3500],"retryableConditions":["HTTP_429","HTTP_503","NETWORK_TIMEOUT"]}},"endpoints":{"dossierUrl":"https://www.xpersona.co/api/v1/agents/clawhub-simon2256928-deckcraft/dossier","snapshotUrl":"https://www.xpersona.co/api/v1/agents/clawhub-simon2256928-deckcraft/snapshot","contractUrl":"https://www.xpersona.co/api/v1/agents/clawhub-simon2256928-deckcraft/contract","trustUrl":"https://www.xpersona.co/api/v1/agents/clawhub-simon2256928-deckcraft/trust"}},"reliability":{"evidence":{"source":"runtime-metrics","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No trust, reliability, or runtime telemetry is available."},"trust":{"status":"unavailable","handshakeStatus":"UNKNOWN","verificationFreshnessHours":null,"reputationScore":null,"p95LatencyMs":null,"successRate30d":null,"fallbackRate":null,"attempts30d":null,"trustUpdatedAt":null,"trustConfidence":"unknown","sourceUpdatedAt":null,"freshnessSeconds":null},"decisionGuardrails":{"doNotUseIf":["Contract metadata is missing or unavailable for deterministic execution."],"safeUseWhen":[],"riskFlags":["missing_or_unavailable_contract","trust_data_unavailable","schema_references_missing"],"operationalConfidence":"low"},"executionMetrics":{"observedLatencyMsP50":null,"observedLatencyMsP95":null,"estimatedCostUsd":null,"uptime30d":null,"rateLimitRpm":null,"rateLimitBurst":null,"lastVerifiedAt":null,"verificationSource":null},"runtimeMetrics":{"successRate":null,"avgLatencyMs":null,"avgCostUsd":null,"hallucinationRate":null,"retryRate":null,"disputeRate":null,"p50Latency":null,"p95Latency":null,"lastUpdated":null}},"benchmarks":{"evidence":{"source":"no-benchmark-data","verified":false,"confidence":"low","updatedAt":null,"emptyReason":"No benchmark suites or observed failure patterns are available."},"suites":[],"failurePatterns":[]},"artifacts":{"evidence":{"source":"CLAWHUB","verified":false,"confidence":"high","updatedAt":"2026-10-10T09:00:31.943Z","emptyReason":null},"readme":"Skill: DeckCraft\n\nOwner: simon2256928\n\nSummary: AI PPT creation skill with structured 5-stage generation, machine-readable QA gates, checkpoint recovery, and experience accumulation. 20 layout methods, nat...\n\nTags: ai:5.3.0, canvas:5.3.0, docx:5.3.0, importer:5.3.0, latest:6.0.0, pdf:5.3.0, ppt:5.3.0, pptx:5.3.0, presentation:5.3.0\n\nVersion history:\n\nv6.0.0 | 2026-06-11T12:02:59.632Z | user\n\nv6.0.0: PPT Master integration. 37 icon library, URL/WeChat source auto-fetch, CRAP design optimizer, speaker notes, 9 new chart types (funnel/gantt/swot/porter/sankey/heatmap/radar/treemap/waterfall), optional multi-role workflow, 8 new canvas aliases, 14 industry color palettes, image resource manifest. 184 tests pass. python-pptx native preserved (PPTX remains editable). Backward-compatible with v5.3.\n\nv5.3.0 | 2026-06-03T04:10:06.762Z | user\n\nv5.3.0: Source importers (PDF via PyMuPDF, DOCX via python-docx, TXT/MD). New CLI scripts/import_source.py converts documents to outline JSON. 34 new importer tests (149 total). 100% backward compatible with v5.2.\n\nv5.2.0 | 2026-06-03T03:03:27.942Z | user\n\ntest\n\nv5.1.1 | 2026-05-19T13:49:30.826Z | user\n\nFix YAML frontmatter\n\nv5.1.0 | 2026-05-19T13:24:50.739Z | user\n\nNative charts, visual QA, all elements editable\n\nv5.0.2 | 2026-05-18T13:34:35.996Z | user\n\nv5.0.2 — Audit fix: removed stale experiences/ references in SKILL.md, corrected version headers in gate scripts (v4→v5).\n\nv5.0.1 | 2026-05-18T13:26:29.302Z | user\n\nv5.0.1 — Cleaned public release: removed internal experiences, redundant style YAMLs, legacy scripts, and template editing utilities. Core only: engine + gate checks + layout matrix.\n\nv5.0.0 | 2026-05-18T13:06:27.762Z | user\n\nv5.0.0 — Major rewrite: DeckEngine rendering engine (20 layout methods, 40+ API), ChartEngine (bar/pie/line/gauge via matplotlib), visual QA pipeline (LibreOffice→PDF→images), machine-readable gate checks (S3 content + S4 QA → JSON output), template editing system (text replacement, image swap, XML sanitize), design spec library (23 layout definitions, 10 theme YAMLs), experience accumulation, checkpoint recovery, 3 anti-patterns, Fast Track mode.\n\nv3.0.3 | 2026-05-15T19:31:09.124Z | user\n\nv3.0.3: English, single version, clean professional documentation\n\nv3.0.2 | 2026-05-15T19:29:48.474Z | user\n\nv3.0.2: 移除 internal-notes，踩坑笔记归属 AGENTS.md\n\nv3.0.1 | 2026-05-15T19:28:35.946Z | user\n\nv3.0.1: 清理发布内容，移除私人笔记，保持专业\n\nv3.0.0 | 2026-05-15T19:13:27.963Z | user\n\nv3: 加入设计原则、QA强制检查、踩坑清单、三路分流、新增页面类型(calendar/heatmap/timeline)\n\nv1.0.0 | 2026-05-06T04:55:27.127Z | user\n\nInitial release: 10 built-in styles, AI illustration support, template library, guided 5-step workflow, image-rich layouts\n\nArchive index:\n\nArchive v6.0.0: 44 files, 113996 bytes\n\nFiles: _meta.json (128b), CHANGELOG.md (11240b), designs/layout_matrix.yaml (6608b), engine/__init__.py (702b), engine/chart_engine.py (43666b), engine/constants.py (11939b), engine/core.py (7885b), engine/deck_engine.py (62114b), engine/icons.py (21788b), engine/importers/__init__.py (2808b), engine/importers/base.py (7039b), engine/importers/docx.py (7403b), engine/importers/pdf.py (5921b), engine/importers/text.py (2891b), examples/01_basic_cover_to_closing.py (1705b), examples/02_multi_canvas.py (2767b), examples/03_from_outline_json.py (5835b), examples/04_from_source.py (3701b), examples/05_icons.py (2266b), examples/06_role_mode.py (4339b), examples/output/03_outline.json (2352b), examples/output/test_doc_outline.json (1270b), importers/url.py (4702b), importers/wechat.py (7054b), LICENSE (1079b), MIGRATION.md (9582b), PUBLISHING.md (3233b), README.md (9129b), requirements.txt (380b), scripts/add_notes.py (3482b), scripts/gate_check_content.py (7669b), scripts/gate_check.py (5418b), scripts/generate_ppt.py (11352b), scripts/import_source.py (7070b), scripts/optimize_crap.py (13762b), skill-card.md (2563b), SKILL.md (9915b), templates/design_spec_demo.md (2178b), templates/design_spec.md (1589b), tests/test_charts_extended.py (7940b), tests/test_importers.py (9480b), tests/test_role_mode.py (4435b), tests/test_smoke.py (5706b), tests/test_validation.py (7545b)\n\nFile v6.0.0:SKILL.md\n\n---\nname: deckcraft\ndescription: >\n  AI PPT creation skill with structured 5-stage generation, machine-readable QA gates,\n  checkpoint recovery, and experience accumulation. 20 layout methods, native charts,\n  visual QA pipeline, automated gate checks, and multi-canvas output (16:9/9:16/1:1/4:3/A4).\n---\n\n# DeckCraft v6 — Harness Engineering\n\n> **Version**: 6.0.0 · **Engine**: DeckEngine (python-pptx native charts) + ChartEngine (native)\n>\n> **Required tools**: Read, Write, Bash\n> **Requires**: `pip install python-pptx lxml Pillow`\n> **Render QA**: LibreOffice Impress (soffice --headless) + poppler-utils (pdftoppm)\n\n---\n\n## Anti-Patterns (Read Before Every Generation)\n\n### Anti-Pattern 1: Declaring \"Gate Passed\" Verbally\n\n**Wrong**: \"QA found 5 errors but all are minor, gate passed.\"\n**Correct**: Run `gate_check.py`, read the JSON, only `\"passed\": true` means pass.\n\n### Anti-Pattern 2: \"I Checked In My Head\"\n\nFormat errors in content JSON are invisible to mental review.\n**Correct**: Run `gate_check_content.py`, read the JSON output.\n\n### Anti-Pattern 3: Skipping the Process for \"Simple\" Decks\n\nEven simple decks can have overflow, font issues, or broken layouts.\n**Correct**: Use Fast Track (see below), but **never skip the QA gate**.\n\n---\n\n## HARD RULES\n\n1. **Every generation must follow the 5-stage flow**\n2. **Gates must be machine-readable** — run the script, read the JSON\n3. **Experience accumulation is recommended** — note pattern-level fixes for future improvement\n4. **All positioning values must use `int()` wrapping** for python-pptx\n5. **Clear paragraphs before adding runs** — never assume `p.runs[0]` exists\n\n---\n\n## 5-Stage Generation Flow\n\n```\nS1 Brief → S2 Structure → S3 Content → S4 Render+QA → S5 Deliver\n                          ⭐ gate        ⭐⭐ gate\n```\n\n### Stage 1: Brief\n\nCollect: audience, goal, duration, key messages, style preference.\n**Output**: `<project>/brief.md`\n\n**Design Spec Template (v6.0+)**: Use `templates/design_spec.md` to capture structured design decisions (canvas, page count, audience, color scheme, typography, speaker notes). A filled example is at `templates/design_spec_demo.md`. Recommended for any deck ≥ 8 pages.\n\n### Stage 2: Structure\n\nAssign page types, write key points (full insight sentences).\n**Output**: `<project>/outline.json`\n\n### Stage 3: Content\n\nFill copy, numbers, chart data. Respect char budgets in `designs/layout_matrix.yaml`.\n**Output**: `<project>/content.json`\n\n**⭐ Gate S3**:\n\n```bash\npython3 scripts/gate_check_content.py <project>/content.json <project>\n```\n\nRead `gate_content.json` — only `\"passed\": true` allows proceeding.\n\n### Stage 4: Render + QA\n\nGenerate PPTX from content.json, then run QA.\n\n```bash\npython3 scripts/gate_check.py <pptx_path> <project>\n```\n\nRead `gate_result.json` — only `\"passed\": true` allows proceeding.\n\n**Visual QA (render preview)**:\n\n```bash\n# Render PPT → PDF → PNG for visual inspection\nsoffice --headless --convert-to pdf <pptx_path> --outdir <project>/\npdftoppm -png -r 200 <pdf_path> <project>/preview/slide\n```\n\nInspect the PNG images to verify layout, fonts, colors, and chart rendering.\nFix any visual issues found, regenerate, and re-run gate.\n\n### Stage 5: Deliver + Self-Refinement\n\nDeliver the PPTX.\n\n---\n\n## Fast Track (Simple Requests)\n\nWhen **all** conditions are met, skip S2/S3 gates:\n- Total pages ≤ 5\n- No data charts\n- User says \"quick\" / \"fast\" / \"simple\"\n\n**Still required**: S1 + S4 QA gate + S5 delivery.\n\n---\n\n## Checkpoint Recovery\n\nWhen resuming a deck project, check which files exist:\n\n- No `brief.md` → Stage 1\n- No `outline.json` → Stage 2\n- No `content.json` → Stage 3\n- No `gate_content.json` → Stage 3-gate\n- No `.pptx` → Stage 4\n- No `gate_result.json` → Stage 4-gate\n- All present → Stage 5\n\nResume from the identified stage. Do not restart from S1.\n\n---\n\n## DeckEngine API\n\n```python\nimport sys, os\nsys.path.insert(0, '<skill-path>')\nfrom engine import DeckEngine\n\n# v5.2+: canvas parameter (16:9 / 9:16 / 1:1 / 4:3 / A4)\neng = DeckEngine(theme_name=\"business\", canvas=\"16:9\")  # default\neng = DeckEngine(theme_name=\"business\", canvas=\"9:16\")   # vertical mobile (TikTok, Reels, Stories)\neng = DeckEngine(theme_name=\"business\", canvas=\"1:1\")    # square (Instagram)\neng = DeckEngine(theme_name=\"business\", canvas=\"4:3\")    # classic projector\neng = DeckEngine(theme_name=\"business\", canvas=\"A4\")     # print landscape\n\n# v6.0+: Multi-role mode (optional strategist → executor workflow)\neng = DeckEngine(theme_name=\"business\", canvas=\"16:9\", role_mode=\"multi\")\nplan = eng.strategist_plan({\"title\": \"My Brief\"})  # get plan template\n# ... fill plan with your LLM ...\neng.execute_plan(filled_plan)                       # generate from plan\neng.cover(title=\"Title\", subtitle=\"Sub\", author=\"Author\", date=\"2026\")\neng.toc(items=[(\"1\", \"Chapter\", \"Description\")])\neng.section_divider(\"Section Title\", section_number=1)\neng.content(title=\"Slide\", bullets=[\"Point 1\", \"Point 2\"], key_point=\"Insight\")\neng.content_with_icon(title=\"Slide\", items=[(\"01\", \"Head\", \"Desc\")])\neng.two_col(title=\"Compare\", left_title=\"A\", left_items=[], right_title=\"B\", right_items=[])\neng.vs_compare(title=\"VS\", left_title=\"Before\", right_title=\"After\", rows=[(\"Dim\", \"Val1\", \"Val2\")])\neng.table(title=\"Data\", headers=[\"H1\", \"H2\"], rows=[[\"a\", \"b\"]], insights=[\"Key takeaway\"])\neng.stat_cards(title=\"KPIs\", stats=[(\"99%\", \"Uptime\"), (\"$2M\", \"Revenue\")])\neng.chart_bar(title=\"Revenue\", data=[[4.2, 3.8]], labels=[\"A\", \"B\"], series_names=[\"S1\"])\neng.chart_pie(title=\"Mix\", data=[45, 30, 25], labels=[\"X\", \"Y\", \"Z\"], donut=True)\neng.chart_line(title=\"Trend\", data=[[1, 2, 3]], labels=[\"Q1\", \"Q2\", \"Q3\"])\neng.chart_gauge(title=\"Score\", value=87, max_value=100, label=\"NPS\")\neng.timeline(title=\"Roadmap\", milestones=[(\"Q1\", \"Launch\"), (\"Q2\", \"Scale\")])\neng.process_flow(title=\"Steps\", steps=[\"Research\", \"Build\", \"Launch\"])\neng.matrix_2x2(title=\"Priority\", quadrants=[(\"TL\", \"desc\"), (\"TR\", \"desc\"), (\"BL\", \"desc\"), (\"BR\", \"desc\")])\neng.quote(title=\"Insight\", quote_text=\"Words matter.\", attribution=\"Author\")\neng.image_full(title=\"Visual\", image_path=\"photo.jpg\", caption=\"Detail\")\neng.image_split(title=\"Split\", image_path=\"photo.jpg\", bullets=[\"Point\"])\neng.kpi_dashboard(title=\"Dashboard\", kpis=[(\"Revenue\", 12.4, 15, \"M\")])\neng.team_grid(title=\"Team\", members=[(\"Name\", \"Role\")])\neng.checklist(title=\"Tasks\", items=[\"Task 1\", \"Task 2\"], checked=[True, False])\neng.summary(title=\"Takeaways\", key_points=[\"Point 1\"], conclusion=\"Next step\")\neng.closing(title=\"Thank You\", message=\"Questions?\")  # no page_num (closing slide)\neng.save(\"output.pptx\")\n```\n\n**10 themes**: business, business_dark, tech, tech_gradient, minimal, elegant, creative, green, red, ocean\n\n**Canvas presets (v5.2+)**: `16:9` (default, widescreen), `9:16` (vertical mobile, TikTok/Reels/Stories), `1:1` (square, Instagram), `4:3` (classic projector), `A4` (print landscape), `A4-portrait`. Aliases: `mobile`=9:16, `square`=1:1, `ppt`=16:9.\n\nList available canvases: `from engine.constants import list_canvases; print(list_canvases())`\n\n---\n\n## Design Guide\n\n### Color\n\nExtract from user's original PPT first. Pick a bold palette matching the topic.\nOne dominant color (60-70%), 1-2 supporting, one sharp accent.\n\n### Typography\n\n| Element | Size | Notes |\n|---------|------|-------|\n| Slide title | 26-36pt bold | Must stand out |\n| Body text | 14-16pt | Never below 10pt |\n| Captions | 10-12pt | Muted color |\n\nCJK: Noto Sans CJK SC / Latin: Arial / Calibri\n\n### Spacing\n\n- Minimum margin: 0.5\"\n- Between blocks: 0.3-0.5\"\n- Leave breathing room\n\n### Avoid\n\n- Repeating the same layout on every slide\n- Text-only slides — add visual elements\n- Center-aligned body text\n- Low-contrast text (light on light, dark on dark)\n\n---\n\n## Dependencies\n\n| Tool | Install |\n|------|---------|\n| python-pptx | `pip install python-pptx` |\n| lxml | `pip install lxml` |\n| Pillow | `pip install Pillow` |\n\n**Render QA (optional but recommended)**:\n\n| Tool | Install |\n|------|----------|\n| LibreOffice Impress | `apt install libreoffice-impress` |\n| poppler-utils | `apt install poppler-utils` |\n| Noto Sans CJK | `apt install fonts-noto-cjk` |\n\n---\n\n## Skill File Structure\n\n```\ndeckcraft/\n├── SKILL.md                     # This file\n├── engine/\n│   ├── __init__.py\n│   ├── constants.py             # 10 theme color palettes, typography, grid\n│   ├── core.py                  # Drawing primitives, XML cleanup, CJK font\n│   ├── chart_engine.py          # Native bar/pie/line/gauge charts (python-pptx)\n│   ├── deck_engine.py           # 20 layout methods, 40+ high-level API\n│   └── importers/               # v5.3+ source importers\n│       ├── __init__.py\n│       ├── base.py              # Shared heuristics\n│       ├── pdf.py               # PDF → outline (PyMuPDF)\n│       ├── docx.py              # DOCX → outline (python-docx)\n│       └── text.py              # TXT/MD → outline\n├── scripts/\n│   ├── generate_ppt.py          # CLI: outline JSON → PPTX\n│   ├── import_source.py         # v5.3+ CLI: PDF/DOCX/MD → outline\n│   ├── gate_check.py            # S4 QA gate → gate_result.json\n│   └── gate_check_content.py   # S3 content gate → gate_content.json\n├── designs/\n│   └── layout_matrix.yaml       # 23 layout definitions with char budgets\n├── examples/                    # Working code samples\n│   ├── 01_basic_cover_to_closing.py\n│   ├── 02_multi_canvas.py\n│   ├── 03_from_outline_json.py\n│   └── 04_from_source.py        # v5.3+\n└── tests/\n    ├── test_smoke.py            # 95 layout × canvas tests\n    ├── test_validation.py       # 20 input validation tests\n    └── test_importers.py        # v5.3+ 34 importer tests\n```\n\nFile v6.0.0:README.md\n\n# DeckCraft\n\n> **AI-native PPTX generation with structured workflow, machine-readable QA gates, and multi-canvas output.**\n\nGenerate professional, **natively-editable** PowerPoint files (`.pptx`) with a 5-stage structured workflow. Every shape is a real DrawingML object — not an image — so users can click and edit any element in PowerPoint.\n\n[![Version](https://img.shields.io/badge/version-5.2.0-blue)]()\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue)]()\n[![License](https://img.shields.io/badge/license-MIT-green)]()\n\n---\n\n## ✨ Features\n\n- 🎨 **20+ high-level layout methods** — cover, TOC, content, comparison, table, chart, timeline, matrix, quote, summary, closing, and more\n- 📐 **6 canvas presets** — `16:9`, `9:16`, `1:1`, `4:3`, `A4`, `A4-portrait` (mobile, square, classic, print)\n- 🎨 **10 built-in themes** — business, tech, elegant, creative, green, red, ocean, etc.\n- 📊 **Native charts** — bar, pie, line, gauge (using python-pptx's chart engine, not images)\n- ✅ **5-stage structured workflow** — Brief → Structure → Content → Render+QA → Deliver\n- 🚦 **Machine-readable QA gates** — `gate_check.py` + `gate_check_content.py` produce JSON verdict\n- 🔄 **Checkpoint recovery** — resume mid-project without restarting\n- 🌏 **CJK font support** — Noto Sans CJK SC built-in\n- 🛠️ **3 interfaces** — Python API, CLI (`generate_ppt.py`), and outline-JSON mode\n\n---\n\n## 📦 Installation\n\n```bash\npip install python-pptx lxml Pillow\n```\n\nOptional (for visual QA preview):\n\n```bash\napt install libreoffice-impress poppler-utils fonts-noto-cjk\n```\n\nFrom source (after cloning):\n\n```bash\ngit clone <repo> deckcraft\ncd deckcraft\npip install -r requirements.txt\n```\n\n---\n\n## 🚀 Quick Start\n\n### Python API\n\n```python\nimport sys\nsys.path.insert(0, \"path/to/deckcraft\")\nfrom engine import DeckEngine\n\n# 16:9 widescreen (default)\neng = DeckEngine(theme_name=\"business\")\neng.cover(title=\"Q3 Marketing Plan\", subtitle=\"Strategic Roadmap\", author=\"Marketing Team\", date=\"2026-06-03\")\neng.toc(items=[(\"01\", \"Market Analysis\", \"Industry trends & competitor landscape\")])\neng.content(title=\"Key Insights\", bullets=[\"Gen-Z prefers short-form video\", \"ROI 2.3x on creator partnerships\"], key_point=\"Lean into TikTok + Xiaohongshu\")\neng.summary(title=\"Takeaways\", key_points=[\"Lead with creative, not media\"], conclusion=\"Approve 60% budget shift by June 15\")\neng.closing(message=\"Questions?\")\neng.save(\"q3_plan.pptx\")\n```\n\n### CLI\n\n```bash\npython3 scripts/generate_ppt.py outline.json -o output.pptx --theme business --canvas 16:9\n```\n\n### Multi-canvas\n\n```python\n# 9:16 for social media (mobile, TikTok, Instagram Reels)\neng = DeckEngine(canvas=\"9:16\")\neng.cover(title=\"Product Launch\")\neng.content(title=\"Features\", bullets=[\"Fast\", \"Beautiful\", \"Affordable\"])\neng.save(\"launch_vertical.pptx\")\n\n# 1:1 for Instagram square\neng = DeckEngine(canvas=\"1:1\")\n# ... \n\n# A4 for printing\neng = DeckEngine(canvas=\"A4\")\n# ...\n```\n\n### Importing from existing documents (v5.3+)\n\nTurn a PDF, DOCX, or Markdown file into a deck outline, then render:\n\n```bash\n# 1. Import → outline JSON\npython3 scripts/import_source.py brief.pdf -o outline.json\n\n# 2. Edit outline.json (optional) to fine-tune page types and content\n\n# 3. Render → PPTX\npython3 scripts/generate_ppt.py -i outline.json -o deck.pptx\n```\n\nSupported formats: **PDF** (via PyMuPDF), **DOCX** (via python-docx), **TXT**, **MD**.\n\nThe importer auto-classifies each section as `cover`, `toc`, `content`, `table`, or `stat_cards` using heuristics. You can override with `--page-types \"cover,toc,content,...\"`.\n\nSee [examples/](examples/) for full working samples.\n\n---\n\n## 🎨 Canvas Presets\n\n| Preset | Dimensions | Aliases | Use Case |\n|--------|------------|---------|----------|\n| `16:9` (default) | 10.0\" × 5.625\" | `ppt`, `ppt-16x9` | Standard widescreen |\n| `9:16` | 5.625\" × 10.0\" | `mobile` | Vertical/mobile (TikTok, Reels) |\n| `1:1` | 7.5\" × 7.5\" | `square` | Square (Instagram) |\n| `4:3` | 10.0\" × 7.5\" | — | Classic projector |\n| `A4` | 11.69\" × 8.27\" | — | Print landscape |\n| `A4-portrait` | 8.27\" × 11.69\" | — | Print portrait |\n\nList all: `python3 -c \"from engine.constants import list_canvases; print(list_canvases())\"`\n\n---\n\n## 🏗️ The 5-Stage Workflow\n\n```\nS1 Brief → S2 Structure → S3 Content → S4 Render+QA → S5 Deliver\n                          ⭐ gate        ⭐⭐ gate\n```\n\n### Stage 1: Brief\nCollect audience, goal, duration, key messages, style. Output: `brief.md`\n\n### Stage 2: Structure\nAssign page types, write key points. Output: `outline.json`\n\n### Stage 3: Content\nFill copy, numbers, chart data. Output: `content.json`\n\n**⭐ Gate S3**: `python3 scripts/gate_check_content.py content.json <project>`\n\n### Stage 4: Render + QA\nGenerate PPTX, then run QA. Output: `output.pptx`\n\n**⭐⭐ Gate S4**: `python3 scripts/gate_check.py output.pptx <project>`\n\n### Stage 5: Deliver\nHand off the PPTX.\n\n**Fast Track** (≤5 pages, no charts, user says \"quick\"): skip S2/S3 gates, but **never skip S4 QA gate**.\n\n---\n\n## 📚 API Reference\n\n### DeckEngine (20+ methods)\n\n| Method | Purpose |\n|--------|---------|\n| `cover(title, subtitle, author, date, image_path)` | Title slide |\n| `toc(items)` | Table of contents |\n| `section_divider(title, section_number, subtitle)` | Section break |\n| `content(title, bullets, key_point, image_path)` | Bullets + optional image |\n| `content_with_icon(title, items)` | Icon-style content |\n| `two_col(left_title, left_items, right_title, right_items)` | Side-by-side |\n| `vs_compare(left_title, right_title, rows)` | Comparison table |\n| `table(headers, rows, insights)` | Data table |\n| `stat_cards(stats)` | KPI cards |\n| `chart_bar/pie/line/gauge(...)` | Native charts |\n| `timeline(milestones)` | Roadmap timeline |\n| `process_flow(steps)` | Step-by-step flow |\n| `matrix_2x2(quadrants)` | 2×2 grid |\n| `quote(text, attribution)` | Quote slide |\n| `image_full(image_path, caption)` | Full-width image |\n| `image_split(image_path, bullets, image_side)` | Image + text |\n| `kpi_dashboard(kpis)` | KPI dashboard |\n| `team_grid(members)` | Team grid |\n| `checklist(items, checked)` | Checklist |\n| `summary(key_points, conclusion)` | Summary slide |\n| `closing(title, message, contact)` | Thank you |\n| `save(path)` | Save PPTX |\n\n### Themes (10)\n\n`business`, `business_dark`, `tech`, `tech_gradient`, `minimal`, `elegant`, `creative`, `green`, `red`, `ocean`\n\n---\n\n## 🧪 QA Gates\n\n### S3 Content Gate\n\n```bash\npython3 scripts/gate_check_content.py content.json <project_dir>\n```\n\nValidates content JSON format. Catches:\n- Unsupported page types\n- Missing required fields\n- Char budget overflow\n- Element count exceeded\n\n### S4 Render Gate\n\n```bash\npython3 scripts/gate_check.py output.pptx <project_dir>\n```\n\nValidates rendered PPTX. Catches:\n- Text/shape overflow (off-slide)\n- Image positioning issues\n- Aspect ratio mismatches\n- Font issues (rough check)\n\nBoth gates output machine-readable JSON. **AI must read the JSON verdict; verbal declaration is not accepted.**\n\n---\n\n## 🎯 Design Principles\n\n1. **Native > Image** — Every shape is real DrawingML. Users can edit, recolor, reposition in PowerPoint.\n2. **Canvas-aware** — Layouts adapt to aspect ratio. No content overflow.\n3. **Theme-driven** — One `theme_name` swap changes entire deck's color/typography.\n4. **Predictable** — Same API + same theme = same output. Easy to iterate.\n5. **Composable** — Mix `content()`, `table()`, `chart_*()` in any order.\n\n---\n\n## 📁 Project Structure\n\n```\ndeckcraft/\n├── SKILL.md                     # Detailed skill spec\n├── README.md                    # This file\n├── CHANGELOG.md                 # Version history\n├── LICENSE                      # MIT\n├── requirements.txt             # Python dependencies\n├── MIGRATION.md                 # Migration guides\n├── engine/\n│   ├── __init__.py\n│   ├── constants.py             # 10 themes + 6 canvas presets\n│   ├── core.py                  # Drawing primitives\n│   ├── chart_engine.py          # Native bar/pie/line/gauge\n│   └── deck_engine.py           # 20+ layout methods\n├── scripts/\n│   ├── generate_ppt.py          # CLI entry point\n│   ├── gate_check.py            # S4 QA gate\n│   └── gate_check_content.py   # S3 content gate\n├── designs/\n│   └── layout_matrix.yaml       # Layout constraints\n├── examples/                    # Working code samples\n│   ├── 01_basic_cover_to_closing.py\n│   ├── 02_multi_canvas.py\n│   └── 03_from_outline_json.py\n└── tests/\n    └── test_smoke.py            # Smoke test (all layouts × all canvases)\n```\n\n---\n\n## 🤝 Contributing\n\nBug reports and PRs welcome. For major changes, please open an issue first.\n\n---\n\n## 📄 License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n## 🔗 Links\n\n- **Changelog**: [CHANGELOG.md](CHANGELOG.md)\n- **Migration**: [MIGRATION.md](MIGRATION.md)\n- **Skill spec**: [SKILL.md](SKILL.md)\n- **Examples**: [examples/](examples/)\n\nFile v6.0.0:_meta.json\n\n{\n  \"ownerId\": \"kn7d5t4546sckyvpj7bb694dn9846fsf\",\n  \"slug\": \"deckcraft\",\n  \"version\": \"6.0.0\",\n  \"publishedAt\": 1781179379632\n}\n\nFile v6.0.0:CHANGELOG.md\n\n# DeckCraft Changelog\n\n## [6.0.0] - 2026-06-11 — PPT Master Integration (Icon Library / Source Auto-Fetch / CRAP Optimizer / Multi-Role Workflow / 9 New Charts / Industry Colors)\n\n> **Major release** — borrows select capabilities from PPT Master (@lzfxxx, ClawHub score 3.69) while preserving DeckCraft's core philosophy: **python-pptx native (PPTX is editable, not a SVG image dump) + machine-readable gates + 5-stage discipline**.\n\n### Tier 1 (Must-Have)\n\n- **Icon Library (`engine/icons.py`)** — 37 hand-built icons rendered as `python-pptx` native freeform shapes\n  - No SVG embedding — every icon is editable in PowerPoint\n  - `from engine import icon, ICON_NAMES` — 37 icons: `arrow-right`, `arrow-up`, `arrow-up-right`, `bell`, `bookmark`, `calendar`, `chart-bar`, `check`, `circle-checkmark`, `clock`, `cog`, `download`, `edit`, `file`, `filter`, `mail`, `map-pin`, `phone`, `rocket`, `search`, `settings`, `shield`, `star`, `target`, `trending-up`, `user`, `users`, `video`, `zap`, etc.\n  - New example: `examples/05_icons.py`\n\n- **URL → Markdown importer (`importers/url.py`)** — fetch any URL and convert HTML → MD\n  - CLI: `python3 scripts/import_source.py url https://example.com -o out.md`\n\n- **WeChat Article → Markdown importer (`importers/wechat.py`)** — bypass WeChat anti-scraping with custom UA + Referer\n  - CLI: `python3 scripts/import_source.py wechat https://mp.weixin.qq.com/s/xxx -o out.md`\n\n- **CRAP Design Optimizer (`scripts/optimize_crap.py`)** — optional Stage 4.5 diagnostic\n  - Four-dimension analysis: **C**ontrast / **R**epetition / **A**lignment / **P**roximity\n  - Reads PPTX shapes via python-pptx, outputs MD report (does NOT modify the deck)\n  - Use the report to drive a follow-up LLM-driven optimization pass\n\n- **Speaker Notes Module (`scripts/add_notes.py` + `generate_ppt.py --notes-file`)**\n  - Input: `notes.json` (format: `{\"1\": \"page 1 notes\", \"2\": \"page 2 notes\"}`)\n  - Writes to `slide.notes_slide.notes_text_frame.text` for every slide\n  - Integrated as post-processing step in `generate_ppt.py`\n\n### Tier 2 (Recommended)\n\n- **9 New Chart Types (`engine/chart_engine.py`)** — all python-pptx native, no SVG fallback\n  - `chart_funnel(title, stages, values)` — horizontal funnel, 5-7 stages\n  - `chart_gantt(title, tasks, start_date, end_date)` — timeline + task bars\n  - `chart_swot(title, strengths, weaknesses, opportunities, threats)` — 2x2 SWOT matrix\n  - `chart_porter(title, forces)` — Porter's Five Forces (5 circles around center)\n  - `chart_sankey(title, nodes, links)` — simplified flow diagram (rectangles + trapezoid connectors)\n  - `chart_heatmap(title, rows, cols, values)` — color-mapped grid (green→yellow→red)\n  - `chart_radar(title, axes, series_data, series_names)` — polygon-based radar\n  - `chart_treemap(title, items)` — squarified single-level treemap\n  - `chart_waterfall(title, categories, values, is_total)` — waterfall (start/+/-/end + connector line)\n  - New test file: `tests/test_charts_extended.py` (23 tests, all pass)\n\n- **Multi-Role Workflow (Optional) — `role_mode=\"multi\"`**\n  - `DeckEngine(theme_name=\"business\", role_mode=\"multi\")` enables a Strategist → Executor two-phase flow\n  - `eng.strategist_plan(brief)` returns a plan schema for LLM to fill\n  - `eng.execute_plan(plan)` consumes LLM-filled plan and generates slides\n  - **Default is `role_mode=\"single\"`** — single-pass LLM flow unchanged from v5.3\n  - New example: `examples/06_role_mode.py` (12 tests in `tests/test_role_mode.py`)\n\n- **Design Spec Template (`templates/design_spec.md` + `templates/design_spec_demo.md`)**\n  - Standardized 9-section design spec: canvas / page count / audience / style / colors / icons / images / typography / speaker notes\n  - Bridges brief.md → design spec → content.json\n  - Borrowed from PPT Master `design_spec_reference.md`, trimmed to DeckCraft essentials\n\n### Tier 3 (Nice-to-Have)\n\n- **8 New Canvas Aliases** — `xiaohongshu`, `moments`, `weibo`, `story`, `reels`, `ppt`, `mobile`, `square`\n  - `xiaohongshu` / `story` / `reels` / `mobile` → 9:16\n  - `moments` / `weibo` / `square` → 1:1\n  - `ppt` → 16:9\n  - Total 15 canvas names (7 presets + 8 aliases), accessible via `list_canvases()`\n\n- **14 Industry Color Palettes (`INDUSTRY_COLORS` + `get_industry_theme()`)**\n  - `finance`, `tech`, `healthcare`, `government`, `education`, `retail`, `manufacturing`, `energy`, `media`, `real_estate`, `fashion`, `food`, `travel`, `consulting`\n  - Each: `primary` (60%) + `secondary` (30%) + `accent` (10%) + `label`\n  - 60-30-10 color rule baked in\n\n- **Image Resource Manifest (`engine/importers/__init__.py: extract_image_manifest`)**\n  - Extracts `![](...)` references from MD sources, generates PPT Master-style manifest\n  - Output: list of `{filename, size, aspect_ratio, layout_hint, usage, type, status}` dicts\n  - Integrated into `import_source.py` output as `<content>.images.json`\n\n### What we DID NOT borrow from PPT Master (and why)\n\n- ❌ **SVG-only rendering pipeline** — would lose PowerPoint editability (DeckCraft's core value)\n- ❌ **Forced multi-role reading** — default is still single-pass LLM (faster, cheaper); `role_mode=\"multi\"` is opt-in\n- ❌ **PPT-incompatible SVG features** (filter, mask, clipPath) — DeckCraft remains PPTX-pure\n- ❌ **Heavy project_manager / image analysis pipeline** — DeckCraft stays lightweight\n\n### Test coverage\n\n- 95 smoke + 20 validation + 23 charts_extended + 12 role_mode = **150 tests, all passing**\n- 6 examples work end-to-end (cover→closing, multi-canvas, outline JSON, source import, icons, role_mode)\n\n### Compatibility\n\n- ✅ **Default `role_mode=\"single\"` and default `canvas=\"16:9\"` are 100% backward-compatible with v5.3**\n- ✅ All v5.3 examples (`01-04`) work unchanged\n- ✅ All v5.3 importer APIs (`detect_and_import`, `pdf_to_outline`, `docx_to_outline`, `text_to_outline`) work unchanged\n- 🆕 New optional `role_mode` parameter, new optional `xiaohongshu` etc. canvas names\n- See [MIGRATION.md](MIGRATION.md) for full upgrade guide\n\n---\n\n## [5.3.0] - 2026-06-03 — Source Importers\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n---\n\n## [5.3.0] - 2026-06-03 — Source Importers\n\n### Added\n\n- **New `engine.importers` package** for converting documents to outline JSON:\n  - `pdf_to_outline()` — PDF → outline via PyMuPDF\n  - `docx_to_outline()` — Word .docx → outline via python-docx\n  - `text_to_outline()` — .txt / .md → outline (built-in)\n  - `detect_and_import()` — auto-detect format by extension\n- **New `scripts/import_source.py` CLI**:\n  - `python3 scripts/import_source.py <file.pdf|docx|txt|md> -o outline.json`\n  - Options: `--theme`, `--canvas`, `--page-types`, `--max-pages`, `--print`\n  - Supports PDF, DOCX, TXT, MD\n- **Heuristic page-type classification**:\n  - First page → `cover`\n  - \"Agenda\"/\"目录\" headings + numbered lists → `toc`\n  - \"Part N\"/\"Section N\" → `section`\n  - Pipe-delimited tables → `table`\n  - \"99% Uptime\" / \"$2M Revenue\" patterns → `stat_cards`\n  - Default → `content`\n- New example: `examples/04_from_source.py` (end-to-end PDF → PPTX)\n- New test: `tests/test_importers.py` (34 tests covering heuristics + 3 importers)\n- New dependencies: `PyMuPDF>=1.23.0`, `python-docx>=1.0.0`\n\n### Test coverage\n\n- 95 smoke + 20 validation + 34 importers = **149 tests, all passing**\n- End-to-end: PDF/DOCX → outline → PPTX → gate_check 100/100\n\n### Notes\n\n- Importers are heuristic — review the generated outline and adjust before publishing\n- Manual page-type override: pass `--page-types \"cover,toc,content,...\"` to skip heuristic\n- See [README.md#importing-from-existing-documents](README.md) for the full workflow\n\n---\n\n## [5.2.0] - 2026-06-03 — Multi-Canvas Support\n\n### Added\n\n- **New `canvas` parameter** for `DeckEngine.__init__()`\n- **6 canvas presets** with **4 aliases**:\n  - `16:9` (default) — 10.0\" × 5.625\" — widescreen (alias: `ppt`, `ppt-16x9`)\n  - `9:16` — 5.625\" × 10.0\" — vertical mobile (TikTok/Reels/Stories) (alias: `mobile`)\n  - `1:1` — 7.5\" × 7.5\" — square (Instagram) (alias: `square`)\n  - `4:3` — 10.0\" × 7.5\" — classic projector\n  - `A4` — 11.69\" × 8.27\" — print landscape\n  - `A4-portrait` — 8.27\" × 11.69\" — print portrait\n- New helper API: `from engine.constants import list_canvases`\n- New tests: `tests/test_smoke.py` (95 layout × canvas tests) + `tests/test_validation.py` (20 input validation tests)\n- New CLI options: `--theme`, `--canvas`, `--list-themes`, `--list-canvases` in `generate_ppt.py`\n- New documentation: `README.md`, `MIGRATION.md`, `LICENSE`\n- New examples: `examples/01_basic_cover_to_closing.py`, `examples/02_multi_canvas.py`, `examples/03_from_outline_json.py`\n\n### Changed\n\n- **Refactored** `deck_engine.py` geometry calculations:\n  - Module-level constants `SLIDE_WIDTH/SLIDE_HEIGHT/MARGIN_*/CONTENT_*` replaced with instance attributes `self.cw/self.ch/self.ml/...` (74 references updated)\n  - All 20 layout methods now use canvas-aware calculations instead of hardcoded `Inches()` values\n- **Input validation** on `__init__`, `cover`, `closing`, `content`, `summary`, `save`:\n  - Invalid theme/canvas raises `ValueError` with helpful list of valid options\n  - Empty/None text raises `ValueError`\n  - Non-string text raises `TypeError`\n  - Out-of-bounds lists raise `ValueError`\n  - Non-`.pptx` path raises `UserWarning`\n  - Missing image file raises `UserWarning` (slide is still created)\n- **Type hints** added to `__init__`, `cover`, `closing`, `content`, `summary`, `save`, plus helpers `_validate_text/_validate_list/_validate_int/_validate_image_path`\n- **Improved CLI** (`generate_ppt.py`): full argparse, `--help`, error handling, exit codes\n- 4 layout methods (cover/content/closing/summary) had a bug where each call added 2 slides instead of 1. **Fixed.**\n\n### Compatibility\n\n- ✅ **16:9 default behavior is 100% backward-compatible** with v5.1\n- ❌ Direct imports of `SLIDE_WIDTH`/`SLIDE_HEIGHT`/`MARGIN_*`/`CONTENT_*` from `engine.constants` are removed (use `DeckEngine` instance attributes or `get_canvas()`)\n- See [MIGRATION.md](MIGRATION.md) for upgrade guide\n\n### Testing\n\n- 95 layout × canvas smoke tests pass (5 canvases × 19 layouts)\n- 20 input validation tests pass\n- 4 layouts × 19 layouts gate check: all 100/100\n\n---\n\n## [5.1.1] - 2026-05 (ClawHub release)\n\nInitial ClawHub release. 5-stage workflow, gate mechanisms, 20+ layout methods.\n\n### Highlights\n\n- 5-stage generation flow: Brief → Structure → Content → Render+QA → Deliver\n- 20+ high-level layout methods\n- 10 built-in color themes\n- 2 QA gates (S3 content + S4 render)\n- Checkpoint recovery\n- Anti-patterns documentation\n\n---\n\n## [5.0.0] - 2026-04 (Initial release)\n\nMajor rewrite from v4. New high-level API, structured workflow, native chart support.\n\n### Highlights\n\n- Replaced v4's low-level `create_slide()`/`add_text()` with high-level layout methods\n- Native chart support via python-pptx (bar, pie, line, gauge)\n- 10 built-in themes\n- CJK font support\n\nFile v6.0.0:MIGRATION.md\n\n# DeckCraft — Migration Guides\n\nHow to upgrade between major versions without breaking your existing code.\n\n---\n\n## v5.3 → v6.0 (PPT Master Integration)\n\n### What changed\n\n- **New `role_mode` parameter** on `DeckEngine.__init__` (default `\"single\"` — backward-compatible)\n- **New canvas aliases** recognized by `DeckEngine` (8 new names: `xiaohongshu`, `moments`, `weibo`, `story`, `reels`, `ppt`, `mobile`, `square`)\n- **New chart methods** on `chart_engine`: `chart_funnel`, `chart_gantt`, `chart_swot`, `chart_porter`, `chart_sankey`, `chart_heatmap`, `chart_radar`, `chart_treemap`, `chart_waterfall`\n- **New icon API**: `from engine import icon, ICON_NAMES`\n- **New industry color API**: `from engine import INDUSTRY_COLORS, get_industry_theme`\n- **New source importers**: URL and WeChat article → MD (extends `scripts/import_source.py`)\n- **New tools**: `scripts/optimize_crap.py` (CRAP design diagnostic), `scripts/add_notes.py` (speaker notes injection)\n- **New templates**: `templates/design_spec.md` and `templates/design_spec_demo.md`\n- **New test files**: `tests/test_charts_extended.py` (23 tests), `tests/test_role_mode.py` (12 tests)\n- **New examples**: `examples/05_icons.py`, `examples/06_role_mode.py`\n\n### Migration steps\n\n#### If you used `DeckEngine()` with no args\n\n**No changes needed.** Default `theme_name=\"business\"`, `canvas=\"16:9\"`, `role_mode=\"single\"` preserves exact v5.3 behavior.\n\n```python\n# v5.3 and v6.0 — same code, same output\neng = DeckEngine(theme_name=\"business\")\neng.cover(title=\"Hello\")\neng.save(\"out.pptx\")\n```\n\n#### If you specified `canvas=\"16:9\"` (or any existing preset)\n\n**No changes needed.** All v5.3 canvas names (`16:9`, `9:16`, `1:1`, `4:3`, `A4`, `A4-portrait`, `ppt-16x9`, `mobile`, `square`, `ppt`) still work.\n\n#### If you want to try a new alias\n\n```python\n# v6.0: new alias names map to existing canvases\neng = DeckEngine(canvas=\"xiaohongshu\")  # → 9:16\neng = DeckEngine(canvas=\"moments\")      # → 1:1\neng = DeckEngine(canvas=\"story\")        # → 9:16\n```\n\n#### If you want to try multi-role workflow (optional)\n\n```python\n# v6.0: opt-in multi-role mode\neng = DeckEngine(theme_name=\"business\", canvas=\"16:9\", role_mode=\"multi\")\nplan = eng.strategist_plan(brief={...})  # LLM fills this\neng.execute_plan(plan)                   # LLM-driven generation\n```\n\nDefault `role_mode=\"single\"` keeps the v5.3 single-pass behavior.\n\n#### If you want new chart types\n\n```python\neng.chart_funnel(title=\"Funnel\", stages=[\"A\",\"B\",\"C\",\"D\"], values=[100, 80, 40, 20])\neng.chart_swot(title=\"SWOT\", strengths=[...], weaknesses=[...], opportunities=[...], threats=[...])\neng.chart_heatmap(title=\"Heatmap\", rows=[...], cols=[...], values=[[...]])\n# ... and 6 more\n```\n\n#### If you want icons\n\n```python\nfrom engine import icon\nicon(slide=eng._current_slide, name=\"rocket\", x=100, y=100, size=48, color=\"FF6B35\")\n```\n\n#### If you want industry colors\n\n```python\nfrom engine import get_industry_theme\ntheme = get_industry_theme(\"tech\")  # {\"primary\": \"#1565C0\", \"secondary\": \"#42A5F5\", \"accent\": \"#FF6B35\", ...}\n```\n\n### What we did NOT do (and why)\n\n- ❌ **No SVG-embed rendering pipeline** — DeckCraft remains python-pptx native (PPTX is editable in PowerPoint)\n- ❌ **No forced multi-role workflow** — default is `role_mode=\"single\"` (fast, single LLM pass)\n- ❌ **No PPT-incompatible SVG features** (filter, mask, clipPath) — DeckCraft is PPTX-pure\n\n### Testing the upgrade\n\n```bash\n# All v5.3 tests still pass\npython3 tests/test_smoke.py            # 95 tests\npython3 tests/test_validation.py       # 20 tests\npython3 tests/test_importers.py        # 34 tests\n\n# New v6.0 tests\npython3 -m pytest tests/test_charts_extended.py  # 23 tests\npython3 -m pytest tests/test_role_mode.py        # 12 tests\n\n# All v5.3 examples still work\npython3 examples/01_basic_cover_to_closing.py\npython3 examples/02_multi_canvas.py\npython3 examples/03_from_outline_json.py\npython3 examples/04_from_source.py\n\n# New v6.0 examples\npython3 examples/05_icons.py\npython3 examples/06_role_mode.py\n```\n\nAll 150 tests + 6 examples should pass.\n\n---\n\n## v5.2 → v5.3 (Source Importers)\n\n### What changed\n\n- **New `engine.importers` package** for PDF/DOCX/MD → outline conversion\n- **New `scripts/import_source.py` CLI** for batch import\n- **New example**: `examples/04_from_source.py`\n- **New test**: `tests/test_importers.py` (34 tests)\n- **New dependencies**: `PyMuPDF>=1.23.0`, `python-docx>=1.0.0`\n\n### Migration steps\n\n#### No code changes needed\n\nThe v5.3 release is purely **additive**. All v5.2 code continues to work unchanged.\n\n#### To use the new import feature\n\n```bash\n# 1. Install new dependencies\npip install -r requirements.txt\n\n# 2. Import a document\npython3 scripts/import_source.py brief.pdf -o outline.json\n\n# 3. Render (use existing CLI)\npython3 scripts/generate_ppt.py -i outline.json -o deck.pptx\n```\n\nOr use the Python API:\n\n```python\nfrom engine.importers import detect_and_import\noutline = detect_and_import(\"brief.pdf\", theme=\"business\", canvas=\"16:9\")\n```\n\n### Limitations (v5.3 first cut)\n\n- Importers use heuristics for page-type classification — always review the output\n- Image extraction from PDF/DOCX is not supported in v5.3 (text-only)\n- Complex tables may not be detected — use `--page-types` to override\n\n### Testing the upgrade\n\n```bash\npip install pymupdf python-docx\npython3 tests/test_smoke.py        # 95 tests\npython3 tests/test_validation.py   # 20 tests\npython3 tests/test_importers.py    # 34 tests (new)\n```\n\nAll 149 tests should pass.\n\n---\n\n## v5.1 → v5.2 (Multi-Canvas)\n\n### What changed\n\n- `DeckEngine.__init__()` accepts a new `canvas` parameter (default: `\"16:9\"`)\n- Module-level constants (`SLIDE_WIDTH`, `SLIDE_HEIGHT`, `MARGIN_LEFT`, etc.) are now instance attributes (`self.cw`, `self.ch`, `self.ml`, etc.) on `DeckEngine`. **Direct imports of these constants are no longer supported.**\n- New: 6 canvas presets + 4 aliases\n\n### Migration steps\n\n#### If you used `DeckEngine()` with no args\n\n**No changes needed.** Default `canvas=\"16:9\"` preserves exact v5.1 behavior.\n\n```python\n# v5.1 and v5.2 — same code, same output\neng = DeckEngine(theme_name=\"business\")\neng.cover(title=\"Hello\")\neng.save(\"out.pptx\")\n```\n\n#### If you imported constants directly from `engine.constants`\n\n**BREAKING:** Module-level constants are removed. Use `get_canvas()` or the `DeckEngine` instance attributes.\n\n```python\n# ❌ v5.1 (no longer works)\nfrom engine.constants import SLIDE_WIDTH, SLIDE_HEIGHT\nx = SLIDE_WIDTH / 2  # crashes in v5.2\n\n# ✅ v5.2: use DeckEngine instance attributes\neng = DeckEngine(canvas=\"16:9\")\nx = eng.cw / 2\n\n# ✅ v5.2: use get_canvas() for canvas-agnostic access\nfrom engine.constants import get_canvas\ncanvas = get_canvas(\"16:9\")\nx = canvas[\"width\"]\n```\n\n#### If you need a non-16:9 canvas\n\n**New in v5.2.** Add the `canvas` parameter:\n\n```python\n# 9:16 for mobile/social (TikTok, Reels, Stories)\neng = DeckEngine(canvas=\"9:16\")\n\n# 1:1 for Instagram square\neng = DeckEngine(canvas=\"1:1\")\n\n# A4 for print\neng = DeckEngine(canvas=\"A4\")\n```\n\nSee [README.md](README.md#canvas-presets) for the full list of presets and aliases.\n\n#### If you customized layout internals via Inches()\n\n**Most layout positions are now canvas-aware.** If you monkey-patched `deck_engine.py` to use specific `Inches()` values, you may need to recompute for the new canvas dimensions. The 16:9 default still works identically.\n\n### Behavior change: input validation\n\n**v5.2 raises** for invalid inputs that v5.1 silently accepted:\n\n```python\n# v5.1: silently created a slide with empty content\neng.cover(title=\"\")\n\n# v5.2: raises ValueError\n# ValueError: title is required (got empty string)\n```\n\nIf your code generates titles dynamically, add a default or guard:\n\n```python\ntitle = user_input.get(\"title\", \"Untitled\") or \"Untitled\"\neng.cover(title=title)\n```\n\n### Behavior change: slide counts\n\nv5.2 fixes a bug where `cover()`, `content()`, `closing()`, and `summary()` each added **2 slides** per call. They now correctly add **1 slide** per call.\n\nIf you depended on this bug, add an explicit no-op call to compensate (not recommended).\n\n### New CLI options\n\n```bash\n# v5.1\npython3 generate_ppt.py --outline out.json --output out.pptx --style business\n\n# v5.2: --style renamed to --theme, plus new --canvas\npython3 generate_ppt.py -i out.json -o out.pptx --theme business --canvas 16:9\n\n# New: list available themes/canvases\npython3 generate_ppt.py --list-themes\npython3 generate_ppt.py --list-canvases\n```\n\n### Testing the migration\n\nAfter upgrading, run:\n\n```bash\npython3 tests/test_smoke.py        # 95 layout × canvas tests\npython3 tests/test_validation.py   # 20 input validation tests\n```\n\nBoth should pass. If your existing code uses canvas=\"16:9\" (default), it should work unchanged.\n\n---\n\n## v5.0 → v5.1 (Gate Refinements)\n\nv5.1 was a refinement release. The 5-stage workflow and core API are unchanged from v5.0. The main additions were:\n\n- `gate_check_content.py` for S3 content gate (was implicit before)\n- `Checkpoint Recovery` section in SKILL.md\n- `Anti-Patterns` section in SKILL.md\n- Stronger error messages in `gate_check.py`\n\nNo code changes required for v5.0 → v5.1.\n\n---\n\n## v4 → v5 (Major Rewrite)\n\nv5 introduced the 5-stage structured workflow. The v4 API (`create_slide()`, `add_text()`, etc.) was replaced by high-level layout methods (`cover()`, `content()`, `two_col()`, etc.).\n\nIf you have v4 code, you'll need to rewrite. The new API is significantly higher-level and produces better output. See [SKILL.md](SKILL.md#deckengine-api) for the full v5 API.\n\nFile v6.0.0:PUBLISHING.md\n\n# Publishing DeckCraft to ClawHub\n\nHow to publish a new version of DeckCraft.\n\n## Prerequisites\n\n1. **ClawHub CLI installed**:\n   ```bash\n   npm install -g clawhub\n   ```\n\n2. **Logged in**:\n   ```bash\n   clawhub login\n   clawhub whoami  # confirm\n   ```\n\n## Pre-publish checklist\n\nRun all checks before publishing:\n\n```bash\n# 1. All tests pass\npython3 tests/test_smoke.py        # 95 layout × canvas tests\npython3 tests/test_validation.py   # 20 input validation tests\npython3 tests/test_importers.py    # 34 importer tests (v5.3+)\n\n# 2. All examples work\npython3 examples/01_basic_cover_to_closing.py\npython3 examples/02_multi_canvas.py\npython3 examples/03_from_outline_json.py\npython3 examples/04_from_source.py     # v5.3+\n\n# 3. CLI works\npython3 scripts/generate_ppt.py --list-themes\npython3 scripts/generate_ppt.py --list-canvases\npython3 scripts/generate_ppt.py -i examples/03_outline.json -o /tmp/cli_test.pptx\npython3 scripts/import_source.py --help    # v5.3+\n\n# 4. No personal info or local paths\ngrep -rn \"天天\\|毛毛\\|simon\\|@user\\|localhost\" .  # should be empty\ngrep -rn \"/home/\\|/Users/\" .                        # should be empty (only test files)\n```\n\n## Version bump\n\nUpdate version in:\n\n- `SKILL.md` (line: `**Version**: X.Y.Z`)\n- `CHANGELOG.md` (new section header)\n- `engine/__init__.py` (if applicable)\n- This file (`PUBLISHING.md`)\n\nUse [SemVer](https://semver.org/):\n- **MAJOR** (5.x → 6.x): breaking API changes\n- **MINOR** (5.1 → 5.2): backward-compatible new features\n- **PATCH** (5.1.0 → 5.1.1): bug fixes, no new features\n\n## Build & validate\n\nBefore publishing, do a clean test:\n\n```bash\n# Fresh install\npip install -r requirements.txt\n\n# Run all tests\npython3 -m pytest tests/  # if pytest installed\n# or\npython3 tests/test_smoke.py && python3 tests/test_validation.py\n```\n\n## Publish\n\n```bash\nclawhub publish ./deckcraft \\\n  --slug deckcraft \\\n  --name \"DeckCraft\" \\\n  --version 5.2.0 \\\n  --changelog \"v5.2.0: Multi-canvas support (16:9/9:16/1:1/4:3/A4), input validation, 95+20 tests, MIT license, README/MIGRATION docs\"\n```\n\nThe CLI will:\n1. Hash local files\n2. Resolve any matching published version\n3. Upload new version to the registry\n4. Confirm success with the new version URL\n\n## Post-publish\n\n1. **Verify the listing**:\n   ```bash\n   clawhub search \"deckcraft\"\n   clawhub list  # confirm in installed skills\n   ```\n\n2. **Test install** in a fresh environment:\n   ```bash\n   clawhub install deckcraft --version 5.2.0\n   python3 -c \"from engine import DeckEngine; eng = DeckEngine(canvas='9:16'); eng.cover(title='Hello'); eng.save('/tmp/test.pptx')\"\n   ```\n\n3. **Update local** (if you have it installed via ClawHub):\n   ```bash\n   clawhub update deckcraft\n   ```\n\n## Versioning policy\n\n- **Patch releases** (5.2.0 → 5.2.1): bug fixes only, automatic\n- **Minor releases** (5.2 → 5.3): new features, must pass all tests, must update CHANGELOG\n- **Major releases** (5 → 6): breaking changes, must update MIGRATION.md, may require user action\n\n## Rollback\n\nIf a release is broken:\n\n1. Fix the issue in source\n2. Bump version (5.2.0 → 5.2.1) — never overwrite\n3. Re-publish\n4. Notify users via CHANGELOG\n\nYou cannot delete a published version from ClawHub, only supersede it.\n\nFile v6.0.0:skill-card.md\n\n## Description:\n\nDeckCraft helps agents generate editable PowerPoint decks through a structured 5-stage workflow with machine-readable QA gates, checkpoint recovery, native charts, icons, and multi-canvas output.\n\nThis skill is ready for commercial/non-commercial use.\n\n## Publisher:\n\n[simon2256928](https://clawhub.ai/user/simon2256928)\n\n### License/Terms of Use:\n\nMIT-0\n\n## Use Case:\n\nDevelopers, employees, and external users can use this skill to turn briefs, outlines, source documents, and structured content into editable PPTX presentations with built-in QA checks. It is suited to business decks, reports, multi-canvas social or print presentations, and chart-heavy slide generation.\n\n### Deployment Geography for Use:\n\nGlobal\n\n## Known Risks and Mitigations:\n\nRisk: URL and WeChat importers can fetch arbitrary or internal resources from the runtime environment.\n\nMitigation: Use the skill only in a constrained workspace, avoid untrusted links, and block localhost, private networks, cloud metadata endpoints, and non-HTTP(S) schemes at the environment level.\n\nRisk: Dependency ranges are not pinned to exact versions.\n\nMitigation: Install in a virtual environment with pinned, reviewed dependency versions before production use.\n\nRisk: Generated decks may contain layout, content, or rendering issues if QA gates are skipped.\n\nMitigation: Run the content and render gate scripts, read their JSON verdicts, and inspect rendered previews before delivery.\n\n## Reference(s):\n\n- [DeckCraft README](README.md)\n- [DeckCraft Skill Spec](SKILL.md)\n- [DeckCraft Changelog](CHANGELOG.md)\n- [DeckCraft Migration Guide](MIGRATION.md)\n- [DeckCraft Design Spec Template](templates/design_spec.md)\n\n## Skill Output:\n\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration, Files, Guidance]\n\n**Output Format:** [Markdown guidance, JSON outlines and content files, Python code or shell commands, QA reports, preview assets, and editable PPTX files.]\n\n**Output Parameters:** [1D]\n\n**Other Properties Related to Output:** [May create project files such as brief.md, outline.json, content.json, gate_content.json, gate_result.json, PPTX decks, rendered previews, and optional speaker notes.]\n\n## Skill Version(s):\n\n6.0.0 (source: server release metadata, SKILL.md, CHANGELOG, _meta.json)\n\n## Ethical Considerations:\n\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment.\n\nFile v6.0.0:templates/design_spec_demo.md\n\n# 设计规范示例：8 页商业汇报\n\n> 这是一个完整的 design_spec 填写示例，展示 8 页「Q3 战略汇报」的规范。\n\n---\n\n## 1. 画布格式\n\n- 格式: ppt169\n- 尺寸: 10\" × 5.625\" (254 × 143.5mm)\n- 用途: 内部季度汇报\n\n## 2. 页数范围\n\n- 目标页数: 8\n- 每页功能分配:\n  - P1: Cover（标题页）\n  - P2: Agenda（议程目录）\n  - P3: Section Divider — Q2 回顾\n  - P4: Content — Q2 关键成果\n  - P5: Content — 市场洞察\n  - P6: Stat Cards + Chart — 核心数据\n  - P7: Summary — Q3 战略要点\n  - P8: Closing\n\n## 3. 目标受众\n\n- 主要受众: CEO + 董事会成员（5-8 人）\n- 场合: 季度经营会议，60 分钟议程中占 20 分钟\n- 受众期待: 数据支撑的决策建议，不是流水账\n\n## 4. 风格目标\n\n- [x] B. 一般咨询 — 结构清晰，数据驱动\n- 配合 business_dark 主题（深色背景 + 高对比数据展示）\n\n## 5. 配色方案\n\n- 主导色(60%): #1B2A4A（深蓝） — 背景、大面积填充\n- 辅助色(30%): #3D5A80（中蓝） — 卡片、次要元素\n- 强调色(10%): #EE6352（珊瑚红） — KPI 数字、CTA、关键高亮\n\n## 6. 图标使用\n\n- 方式: 内置库（Lucide Icons 风格） + 数字标号\n- 关键页面:\n  - P4: 四个成果各配一个圆形数字图标\n  - P5: 三个洞察用 📊 🎯 🔮 emoji 标记\n\n## 7. 图片使用\n\n- 方式: 不使用（纯数据汇报，避免装饰性图片分散注意力）\n- 资源清单:\n\n| 页面 | 图片类型 | 来源 | 备注 |\n|------|---------|------|------|\n| — | — | — | 纯文字 + 图表 |\n\n## 8. 排版方案\n\n- 标题字体: Noto Sans CJK SC Bold / Arial Bold\n- 正文字号基准: 16pt（宽松型，汇报场景需要远距离可读）\n- 字号体系:\n  - 标题: 26-36pt (1.5-2x)\n  - 正文: 16pt (1x)\n  - 注释/脚注: 12pt (0.75x)\n\n## 9. 演讲备注要求\n\n- 演讲总时长: 20 分钟\n- 备注风格: 口语化（用「我们」而非「公司」）\n- 讲演目的: 汇报（Q2 总结） + 说服（Q3 预算审批）\n- 时间分配:\n  - Q2 回顾: 5 分钟（P3-P4）\n  - 市场洞察: 5 分钟（P5）\n  - 核心数据: 5 分钟（P6）\n  - Q3 战略: 5 分钟（P7）\n\nFile v6.0.0:templates/design_spec.md\n\n# 设计规范与内容大纲\n\n> DeckCraft v6.0+ 设计规范模板。在 Stage 1 (Brief) 阶段填写此模板，指导后续生成。\n\n---\n\n## 1. 画布格式\n\n- 格式: [ppt169 / ppt43 / xiaohongshu / moments / phone9_16 / a4]\n- 尺寸: [width × height]\n- 用途: [商务汇报 / 社交媒体 / 海报 / ...]\n\n## 2. 页数范围\n\n- 目标页数: [N]\n- 每页功能分配: [cover + toc + content × N + closing]\n\n## 3. 目标受众\n\n- 主要受众: [...]\n- 场合: [客户提案 / 内部汇报 / 公开演讲]\n- 受众期待: [...]\n\n## 4. 风格目标\n\n- [ ] A. 通用灵活 — 适合大多数场景，配色中性\n- [ ] B. 一般咨询 — 结构清晰，数据驱动\n- [ ] C. 顶级咨询(MBB 级) — 极简高级感，大量留白，精准用色\n\n## 5. 配色方案\n\n- 主导色(60%): #HEX — 用途: [背景/大面积填充]\n- 辅助色(30%): #HEX — 用途: [卡片/次要元素]\n- 强调色(10%): #HEX — 用途: [CTA/关键数据/高亮]\n\n## 6. 图标使用\n\n- 方式: [内置库(推荐) / Emoji / AI 生成 / 自定义]\n- 关键页面: [...]\n\n## 7. 图片使用\n\n- 方式: [不使用 / 用户提供 / AI 生成 / 占位符]\n- 资源清单: 见下表\n\n| 页面 | 图片类型 | 来源 | 备注 |\n|------|---------|------|------|\n|      |         |      |      |\n\n## 8. 排版方案\n\n- 标题字体: [...]\n- 正文字号基准: [24px 宽松 / 18px 密集]\n- 字号体系: 标题 1.5-2x / 正文 1x / 注释 0.75x\n\n## 9. 演讲备注要求\n\n- 演讲总时长: [分钟]\n- 备注风格: [正式 / 口语化 / 互动]\n- 讲演目的: [告知 / 说服 / 激励 / 指导 / 汇报]\n\nFile v6.0.0:examples/output/03_outline.json\n\n{\n  \"theme\": \"tech\",\n  \"canvas\": \"16:9\",\n  \"pages\": [\n    {\n      \"type\": \"cover\",\n      \"title\": \"Engineering Productivity Report\",\n      \"subtitle\": \"Q1–Q2 2026\",\n      \"author\": \"Platform Team\",\n      \"date\": \"2026-06-03\"\n    },\n    {\n      \"type\": \"toc\",\n      \"items\": [\n        [\n          \"01\",\n          \"Deploy Frequency\",\n          \"How often we ship\"\n        ],\n        [\n          \"02\",\n          \"Lead Time\",\n          \"Commit to production\"\n        ],\n        [\n          \"03\",\n          \"MTTR\",\n          \"Mean time to recover\"\n        ],\n        [\n          \"04\",\n          \"Change Fail Rate\",\n          \"Defects in production\"\n        ]\n      ]\n    },\n    {\n      \"type\": \"stat_cards\",\n      \"title\": \"Q2 Numbers at a Glance\",\n      \"stats\": [\n        [\n          \"42\",\n          \"Deploys / day\"\n        ],\n        [\n          \"2.1h\",\n          \"Lead time (median)\"\n        ],\n        [\n          \"18m\",\n          \"MTTR (median)\"\n        ],\n        [\n          \"3.2%\",\n          \"Change fail rate\"\n        ]\n      ]\n    },\n    {\n      \"type\": \"chart_bar\",\n      \"title\": \"Deploy Frequency by Service\",\n      \"data\": [\n        [\n          48,\n          32,\n          24,\n          16,\n          8\n        ]\n      ],\n      \"labels\": [\n        \"Auth\",\n        \"API\",\n        \"Frontend\",\n        \"Workers\",\n        \"Reports\"\n      ],\n      \"series_names\": [\n        \"Deploys / week\"\n      ]\n    },\n    {\n      \"type\": \"vs_compare\",\n      \"title\": \"Before vs After Platform Engineering\",\n      \"left_title\": \"Before (2025)\",\n      \"right_title\": \"After (2026)\",\n      \"rows\": [\n        [\n          \"Deploys / day\",\n          \"8\",\n          \"42\"\n        ],\n        [\n          \"Lead time\",\n          \"3.5 days\",\n          \"2.1h\"\n        ],\n        [\n          \"MTTR\",\n          \"2.4h\",\n          \"18m\"\n        ],\n        [\n          \"On-call load\",\n          \"High\",\n          \"Low\"\n        ]\n      ]\n    },\n    {\n      \"type\": \"summary\",\n      \"title\": \"What's Next\",\n      \"content\": [\n        \"Reduce lead time further (target: < 1h by Q4)\",\n        \"Invest in self-service deployment tooling\",\n        \"Expand on-call rotation fairness\"\n      ],\n      \"conclusion\": \"Roadmap finalized in next week's eng leadership sync\"\n    },\n    {\n      \"type\": \"closing\",\n      \"title\": \"Q&A\",\n      \"message\": \"Let's discuss tradeoffs\"\n    }\n  ]\n}\n\nFile v6.0.0:examples/output/test_doc_outline.json\n\n{\n  \"theme\": \"business\",\n  \"canvas\": \"16:9\",\n  \"pages\": [\n    {\n      \"type\": \"cover\",\n      \"title\": \"Q3 Marketing Plan\",\n      \"subtitle\": \"Strategic Roadmap for Q3 2026\",\n      \"author\": \"Marketing Team\",\n      \"date\": \"June 2026\"\n    },\n    {\n      \"type\": \"toc\",\n      \"items\": [\n        [\n          \"01\",\n          \"Market Context\",\n          \"\"\n        ],\n        [\n          \"02\",\n          \"Q2 Recap\",\n          \"\"\n        ],\n        [\n          \"03\",\n          \"Q3 Strategy\",\n          \"\"\n        ],\n        [\n          \"04\",\n          \"Budget & Timeline\",\n          \"\"\n        ]\n      ]\n    },\n    {\n      \"type\": \"content\",\n      \"title\": \"Part 1: Market Context\",\n      \"bullets\": [\n        \"Part 1: Market Context\",\n        \"Industry Trends\",\n        \"Short-form video dominates with 3.2x engagement\",\n        \"AI-generated content adoption up 47% YoY\",\n        \"Privacy-first measurement becoming table stakes\"\n      ],\n      \"key_point\": \"\"\n    },\n    {\n      \"type\": \"stat_cards\",\n      \"title\": \"Part 2: Q2 Recap\",\n      \"stats\": [\n        [\n          \"99%\",\n          \"Campaign delivery rate\"\n        ],\n        [\n          \"$2.4M\",\n          \"Q2 spend\"\n        ],\n        [\n          \"12\",\n          \"New brand partners\"\n        ]\n      ]\n    }\n  ]\n}\n\nFile v6.0.0:designs/layout_matrix.yaml\n\n# Layout Matrix — DeckCraft v5\n# Each layout's constraints: char budget, element limits, recommended content density\n\nlayouts:\n  cover:\n    display_name: \"Cover Slide\"\n    description: \"Title slide with optional subtitle, author, date, background image\"\n    char_budget:\n      title: 60\n      subtitle: 40\n    element_limits:\n      max_images: 1\n    recommended_for: [opening, title]\n    dark_bg: true\n\n  closing:\n    display_name: \"Closing Slide\"\n    description: \"Thank you slide with optional message and contact\"\n    char_budget:\n      title: 30\n      message: 50\n      contact: 40\n    element_limits: {}\n    recommended_for: [closing, q_and_a]\n    dark_bg: true\n\n  toc:\n    display_name: \"Table of Contents\"\n    description: \"Agenda slide with numbered items\"\n    char_budget:\n      item_title: 30\n      item_desc: 40\n    element_limits:\n      max_items: 6\n    recommended_for: [agenda, overview]\n\n  section_divider:\n    display_name: \"Section Divider\"\n    description: \"Full dark background section separator\"\n    char_budget:\n      title: 40\n      subtitle: 50\n    element_limits: {}\n    recommended_for: [transition, section_break]\n    dark_bg: true\n\n  content:\n    display_name: \"Content Slide\"\n    description: \"Standard bullet slide with optional image and key point\"\n    char_budget:\n      title: 50\n      bullet: 80\n      key_point: 80\n    element_limits:\n      max_bullets: 5\n      max_images: 1\n    recommended_for: [overview, explanation, data_commentary]\n\n  content_with_icon:\n    display_name: \"Icon Row Content\"\n    description: \"Content with icon-style rows (icon + heading + description)\"\n    char_budget:\n      heading: 30\n      description: 60\n    element_limits:\n      max_items: 5\n    recommended_for: [features, capabilities, list]\n\n  two_col:\n    display_name: \"Two-Column Comparison\"\n    description: \"Side-by-side comparison with card layout\"\n    char_budget:\n      title: 50\n      card_title: 20\n      bullet: 60\n    element_limits:\n      max_items_per_col: 5\n    recommended_for: [comparison, before_after, pros_cons]\n\n  vs_compare:\n    display_name: \"VS Comparison Table\"\n    description: \"Structured comparison table with dimension rows\"\n    char_budget:\n      title: 50\n      dimension: 20\n      value: 20\n    element_limits:\n      max_rows: 6\n    recommended_for: [comparison, competitive_analysis]\n\n  table:\n    display_name: \"Data Table\"\n    description: \"Structured data table with optional insight bullets\"\n    char_budget:\n      title: 50\n      header: 15\n      cell: 20\n      insight: 60\n    element_limits:\n      max_cols: 6\n      max_rows: 8\n      max_insights: 3\n    recommended_for: [data, metrics, financials]\n\n  stat_cards:\n    display_name: \"Stat Cards\"\n    description: \"Big number KPI cards\"\n    char_budget:\n      number: 12\n      label: 20\n    element_limits:\n      max_cards: 4\n    recommended_for: [kpis, headline_numbers, quarterly_results]\n\n  chart_bar:\n    display_name: \"Bar Chart\"\n    description: \"Vertical or horizontal bar chart\"\n    char_budget:\n      title: 50\n      label: 15\n    element_limits:\n      max_categories: 8\n      max_series: 3\n    recommended_for: [comparison, trends, budget_allocation]\n\n  chart_pie:\n    display_name: \"Pie/Donut Chart\"\n    description: \"Pie or donut chart for proportions\"\n    char_budget:\n      title: 50\n      label: 15\n    element_limits:\n      max_segments: 6\n    recommended_for: [market_share, segmentation, distribution]\n\n  chart_line:\n    display_name: \"Line/Area Chart\"\n    description: \"Line or area chart for trends over time\"\n    char_budget:\n      title: 50\n      label: 10\n    element_limits:\n      max_points: 12\n      max_series: 3\n    recommended_for: [trends, growth, forecasting]\n\n  chart_gauge:\n    display_name: \"Gauge Chart\"\n    description: \"Speedometer-style single metric\"\n    char_budget:\n      title: 50\n      label: 15\n    element_limits: {}\n    recommended_for: [single_metric, target_vs_actual, score]\n\n  timeline:\n    display_name: \"Timeline\"\n    description: \"Horizontal timeline with milestone nodes\"\n    char_budget:\n      period: 10\n      event: 25\n    element_limits:\n      max_milestones: 5\n    recommended_for: [roadmap, milestones, project_timeline]\n\n  process_flow:\n    display_name: \"Process Flow\"\n    description: \"Sequential steps with colored cards\"\n    char_budget:\n      step: 30\n    element_limits:\n      max_steps: 5\n    recommended_for: [process, workflow, methodology]\n\n  matrix_2x2:\n    display_name: \"2×2 Matrix\"\n    description: \"Priority/BCG/SWOT-style quadrant matrix\"\n    char_budget:\n      quadrant_title: 20\n      quadrant_desc: 50\n    element_limits: {}\n    recommended_for: [prioritization, bcg_matrix, swot, strategic_framework]\n\n  quote:\n    display_name: \"Quote Slide\"\n    description: \"Large quote with attribution on dark background\"\n    char_budget:\n      quote: 120\n      attribution: 30\n    element_limits: {}\n    recommended_for: [testimonial, vision_statement, keynote_moment]\n    dark_bg: true\n\n  image_full:\n    display_name: \"Full Image\"\n    description: \"Full-width image with title and caption\"\n    char_budget:\n      title: 50\n      caption: 60\n    element_limits:\n      max_images: 1\n    recommended_for: [visual_evidence, screenshot, product_photo]\n\n  image_split:\n    display_name: \"Split Image + Text\"\n    description: \"Image on one side, bullets on the other\"\n    char_budget:\n      title: 50\n      bullet: 60\n    element_limits:\n      max_bullets: 4\n      max_images: 1\n    recommended_for: [product_feature, case_study, data_with_visual]\n\n  kpi_dashboard:\n    display_name: \"KPI Dashboard\"\n    description: \"Dashboard with stat cards and progress bars\"\n    char_budget:\n      label: 15\n      value: 8\n      unit: 5\n    element_limits:\n      max_kpis: 4\n    recommended_for: [dashboard, performance_review, metrics_overview]\n\n  team_grid:\n    display_name: \"Team Grid\"\n    description: \"Team member cards with avatar initials\"\n    char_budget:\n      name: 15\n      role: 20\n    element_limits:\n      max_members: 6\n    recommended_for: [team_introduction, stakeholders, about_us]\n\n  checklist:\n    display_name: \"Checklist\"\n    description: \"Checkable items with done/pending status\"\n    char_budget:\n      item: 50\n    element_limits:\n      max_items: 8\n    recommended_for: [action_items, requirements, audit]\n\n  summary:\n    display_name: \"Summary / Key Takeaways\"\n    description: \"Key takeaways on dark background with card list\"\n    char_budget:\n      title: 40\n      point: 80\n      conclusion: 60\n    element_limits:\n      max_points: 5\n    recommended_for: [closing, key_takeaways, recommendations]\n    dark_bg: true\n\nArchive v5.3.0: 33 files, 71693 bytes\n\nFiles: CHANGELOG.md (5145b), designs/layout_matrix.yaml (6608b), engine/__init__.py (379b), engine/chart_engine.py (9677b), engine/constants.py (9143b), engine/core.py (7885b), engine/deck_engine.py (48699b), engine/importers/__init__.py (488b), engine/importers/base.py (7039b), engine/importers/docx.py (7403b), engine/importers/pdf.py (5921b), engine/importers/text.py (2891b), examples/01_basic_cover_to_closing.py (1705b), examples/02_multi_canvas.py (2767b), examples/03_from_outline_json.py (5835b), examples/04_from_source.py (3701b), examples/output/03_outline.json (2352b), examples/output/test_doc_outline.json (1270b), LICENSE (1079b), MIGRATION.md (5608b), PUBLISHING.md (3233b), README.md (9129b), requirements.txt (380b), scripts/gate_check_content.py (7669b), scripts/gate_check.py (5418b), scripts/generate_ppt.py (10456b), scripts/import_source.py (5508b), skill-card.md (2425b), SKILL.md (9321b), tests/test_importers.py (9480b), tests/test_smoke.py (5706b), tests/test_validation.py (7545b), _meta.json (128b)\n\nFile v5.3.0:SKILL.md\n\n---\nname: deckcraft\ndescription: >\n  AI PPT creation skill with structured 5-stage generation, machine-readable QA gates,\n  checkpoint recovery, and experience accumulation. 20 layout methods, native charts,\n  visual QA pipeline, automated gate checks, and multi-canvas output (16:9/9:16/1:1/4:3/A4).\n---\n\n# DeckCraft v5 — Harness Engineering\n\n> **Version**: 5.3.0 · **Engine**: DeckEngine (python-pptx native charts) + ChartEngine (native)\n>\n> **Required tools**: Read, Write, Bash\n> **Requires**: `pip install python-pptx lxml Pillow`\n> **Render QA**: LibreOffice Impress (soffice --headless) + poppler-utils (pdftoppm)\n\n---\n\n## Anti-Patterns (Read Before Every Generation)\n\n### Anti-Pattern 1: Declaring \"Gate Passed\" Verbally\n\n**Wrong**: \"QA found 5 errors but all are minor, gate passed.\"\n**Correct**: Run `gate_check.py`, read the JSON, only `\"passed\": true` means pass.\n\n### Anti-Pattern 2: \"I Checked In My Head\"\n\nFormat errors in content JSON are invisible to mental review.\n**Correct**: Run `gate_check_content.py`, read the JSON output.\n\n### Anti-Pattern 3: Skipping the Process for \"Simple\" Decks\n\nEven simple decks can have overflow, font issues, or broken layouts.\n**Correct**: Use Fast Track (see below), but **never skip the QA gate**.\n\n---\n\n## HARD RULES\n\n1. **Every generation must follow the 5-stage flow**\n2. **Gates must be machine-readable** — run the script, read the JSON\n3. **Experience accumulation is recommended** — note pattern-level fixes for future improvement\n4. **All positioning values must use `int()` wrapping** for python-pptx\n5. **Clear paragraphs before adding runs** — never assume `p.runs[0]` exists\n\n---\n\n## 5-Stage Generation Flow\n\n```\nS1 Brief → S2 Structure → S3 Content → S4 Render+QA → S5 Deliver\n                          ⭐ gate        ⭐⭐ gate\n```\n\n### Stage 1: Brief\n\nCollect: audience, goal, duration, key messages, style preference.\n**Output**: `<project>/brief.md`\n\n### Stage 2: Structure\n\nAssign page types, write key points (full insight sentences).\n**Output**: `<project>/outline.json`\n\n### Stage 3: Content\n\nFill copy, numbers, chart data. Respect char budgets in `designs/layout_matrix.yaml`.\n**Output**: `<project>/content.json`\n\n**⭐ Gate S3**:\n\n```bash\npython3 scripts/gate_check_content.py <project>/content.json <project>\n```\n\nRead `gate_content.json` — only `\"passed\": true` allows proceeding.\n\n### Stage 4: Render + QA\n\nGenerate PPTX from content.json, then run QA.\n\n```bash\npython3 scripts/gate_check.py <pptx_path> <project>\n```\n\nRead `gate_result.json` — only `\"passed\": true` allows proceeding.\n\n**Visual QA (render preview)**:\n\n```bash\n# Render PPT → PDF → PNG for visual inspection\nsoffice --headless --convert-to pdf <pptx_path> --outdir <project>/\npdftoppm -png -r 200 <pdf_path> <project>/preview/slide\n```\n\nInspect the PNG images to verify layout, fonts, colors, and chart rendering.\nFix any visual issues found, regenerate, and re-run gate.\n\n### Stage 5: Deliver + Self-Refinement\n\nDeliver the PPTX.\n\n---\n\n## Fast Track (Simple Requests)\n\nWhen **all** conditions are met, skip S2/S3 gates:\n- Total pages ≤ 5\n- No data charts\n- User says \"quick\" / \"fast\" / \"simple\"\n\n**Still required**: S1 + S4 QA gate + S5 delivery.\n\n---\n\n## Checkpoint Recovery\n\nWhen resuming a deck project, check which files exist:\n\n- No `brief.md` → Stage 1\n- No `outline.json` → Stage 2\n- No `content.json` → Stage 3\n- No `gate_content.json` → Stage 3-gate\n- No `.pptx` → Stage 4\n- No `gate_result.json` → Stage 4-gate\n- All present → Stage 5\n\nResume from the identified stage. Do not restart from S1.\n\n---\n\n## DeckEngine API\n\n```python\nimport sys, os\nsys.path.insert(0, '<skill-path>')\nfrom engine import DeckEngine\n\n# v5.2+: canvas parameter (16:9 / 9:16 / 1:1 / 4:3 / A4)\neng = DeckEngine(theme_name=\"business\", canvas=\"16:9\")  # default\neng = DeckEngine(theme_name=\"business\", canvas=\"9:16\")   # vertical mobile (TikTok, Reels, Stories)\neng = DeckEngine(theme_name=\"business\", canvas=\"1:1\")    # square (Instagram)\neng = DeckEngine(theme_name=\"business\", canvas=\"4:3\")    # classic projector\neng = DeckEngine(theme_name=\"business\", canvas=\"A4\")     # print landscape\neng.cover(title=\"Title\", subtitle=\"Sub\", author=\"Author\", date=\"2026\")\neng.toc(items=[(\"1\", \"Chapter\", \"Description\")])\neng.section_divider(\"Section Title\", section_number=1)\neng.content(title=\"Slide\", bullets=[\"Point 1\", \"Point 2\"], key_point=\"Insight\")\neng.content_with_icon(title=\"Slide\", items=[(\"01\", \"Head\", \"Desc\")])\neng.two_col(title=\"Compare\", left_title=\"A\", left_items=[], right_title=\"B\", right_items=[])\neng.vs_compare(title=\"VS\", left_title=\"Before\", right_title=\"After\", rows=[(\"Dim\", \"Val1\", \"Val2\")])\neng.table(title=\"Data\", headers=[\"H1\", \"H2\"], rows=[[\"a\", \"b\"]], insights=[\"Key takeaway\"])\neng.stat_cards(title=\"KPIs\", stats=[(\"99%\", \"Uptime\"), (\"$2M\", \"Revenue\")])\neng.chart_bar(title=\"Revenue\", data=[[4.2, 3.8]], labels=[\"A\", \"B\"], series_names=[\"S1\"])\neng.chart_pie(title=\"Mix\", data=[45, 30, 25], labels=[\"X\", \"Y\", \"Z\"], donut=True)\neng.chart_line(title=\"Trend\", data=[[1, 2, 3]], labels=[\"Q1\", \"Q2\", \"Q3\"])\neng.chart_gauge(title=\"Score\", value=87, max_value=100, label=\"NPS\")\neng.timeline(title=\"Roadmap\", milestones=[(\"Q1\", \"Launch\"), (\"Q2\", \"Scale\")])\neng.process_flow(title=\"Steps\", steps=[\"Research\", \"Build\", \"Launch\"])\neng.matrix_2x2(title=\"Priority\", quadrants=[(\"TL\", \"desc\"), (\"TR\", \"desc\"), (\"BL\", \"desc\"), (\"BR\", \"desc\")])\neng.quote(title=\"Insight\", quote_text=\"Words matter.\", attribution=\"Author\")\neng.image_full(title=\"Visual\", image_path=\"photo.jpg\", caption=\"Detail\")\neng.image_split(title=\"Split\", image_path=\"photo.jpg\", bullets=[\"Point\"])\neng.kpi_dashboard(title=\"Dashboard\", kpis=[(\"Revenue\", 12.4, 15, \"M\")])\neng.team_grid(title=\"Team\", members=[(\"Name\", \"Role\")])\neng.checklist(title=\"Tasks\", items=[\"Task 1\", \"Task 2\"], checked=[True, False])\neng.summary(title=\"Takeaways\", key_points=[\"Point 1\"], conclusion=\"Next step\")\neng.closing(title=\"Thank You\", message=\"Questions?\")  # no page_num (closing slide)\neng.save(\"output.pptx\")\n```\n\n**10 themes**: business, business_dark, tech, tech_gradient, minimal, elegant, creative, green, red, ocean\n\n**Canvas presets (v5.2+)**: `16:9` (default, widescreen), `9:16` (vertical mobile, TikTok/Reels/Stories), `1:1` (square, Instagram), `4:3` (classic projector), `A4` (print landscape), `A4-portrait`. Aliases: `mobile`=9:16, `square`=1:1, `ppt`=16:9.\n\nList available canvases: `from engine.constants import list_canvases; print(list_canvases())`\n\n---\n\n## Design Guide\n\n### Color\n\nExtract from user's original PPT first. Pick a bold palette matching the topic.\nOne dominant color (60-70%), 1-2 supporting, one sharp accent.\n\n### Typography\n\n| Element | Size | Notes |\n|---------|------|-------|\n| Slide title | 26-36pt bold | Must stand out |\n| Body text | 14-16pt | Never below 10pt |\n| Captions | 10-12pt | Muted color |\n\nCJK: Noto Sans CJK SC / Latin: Arial / Calibri\n\n### Spacing\n\n- Minimum margin: 0.5\"\n- Between blocks: 0.3-0.5\"\n- Leave breathing room\n\n### Avoid\n\n- Repeating the same layout on every slide\n- Text-only slides — add visual elements\n- Center-aligned body text\n- Low-contrast text (light on light, dark on dark)\n\n---\n\n## Dependencies\n\n| Tool | Install |\n|------|---------|\n| python-pptx | `pip install python-pptx` |\n| lxml | `pip install lxml` |\n| Pillow | `pip install Pillow` |\n\n**Render QA (optional but recommended)**:\n\n| Tool | Install |\n|------|----------|\n| LibreOffice Impress | `apt install libreoffice-impress` |\n| poppler-utils | `apt install poppler-utils` |\n| Noto Sans CJK | `apt install fonts-noto-cjk` |\n\n---\n\n## Skill File Structure\n\n```\ndeckcraft/\n├── SKILL.md                     # This file\n├── engine/\n│   ├── __init__.py\n│   ├── constants.py             # 10 theme color palettes, typography, grid\n│   ├── core.py                  # Drawing primitives, XML cleanup, CJK font\n│   ├── chart_engine.py          # Native bar/pie/line/gauge charts (python-pptx)\n│   ├── deck_engine.py           # 20 layout methods, 40+ high-level API\n│   └── importers/               # v5.3+ source importers\n│       ├── __init__.py\n│       ├── base.py              # Shared heuristics\n│       ├── pdf.py               # PDF → outline (PyMuPDF)\n│       ├── docx.py              # DOCX → outline (python-docx)\n│       └── text.py              # TXT/MD → outline\n├── scripts/\n│   ├── generate_ppt.py          # CLI: outline JSON → PPTX\n│   ├── import_source.py         # v5.3+ CLI: PDF/DOCX/MD → outline\n│   ├── gate_check.py            # S4 QA gate → gate_result.json\n│   └── gate_check_content.py   # S3 content gate → gate_content.json\n├── designs/\n│   └── layout_matrix.yaml       # 23 layout definitions with char budgets\n├── examples/                    # Working code samples\n│   ├── 01_basic_cover_to_closing.py\n│   ├── 02_multi_canvas.py\n│   ├── 03_from_outline_json.py\n│   └── 04_from_source.py        # v5.3+\n└── tests/\n    ├── test_smoke.py            # 95 layout × canvas tests\n    ├── test_validation.py       # 20 input validation tests\n    └── test_importers.py        # v5.3+ 34 importer tests\n```\n\nFile v5.3.0:README.md\n\n# DeckCraft\n\n> **AI-native PPTX generation with structured workflow, machine-readable QA gates, and multi-canvas output.**\n\nGenerate professional, **natively-editable** PowerPoint files (`.pptx`) with a 5-stage structured workflow. Every shape is a real DrawingML object — not an image — so users can click and edit any element in PowerPoint.\n\n[![Version](https://img.shields.io/badge/version-5.2.0-blue)]()\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue)]()\n[![License](https://img.shields.io/badge/license-MIT-green)]()\n\n---\n\n## ✨ Features\n\n- 🎨 **20+ high-level layout methods** — cover, TOC, content, comparison, table, chart, timeline, matrix, quote, summary, closing, and more\n- 📐 **6 canvas presets** — `16:9`, `9:16`, `1:1`, `4:3`, `A4`, `A4-portrait` (mobile, square, classic, print)\n- 🎨 **10 built-in themes** — business, tech, elegant, creative, green, red, ocean, etc.\n- 📊 **Native charts** — bar, pie, line, gauge (using python-pptx's chart engine, not images)\n- ✅ **5-stage structured workflow** — Brief → Structure → Content → Render+QA → Deliver\n- 🚦 **Machine-readable QA gates** — `gate_check.py` + `gate_check_content.py` produce JSON verdict\n- 🔄 **Checkpoint recovery** — resume mid-project without restarting\n- 🌏 **CJK font support** — Noto Sans CJK SC built-in\n- 🛠️ **3 interfaces** — Python API, CLI (`generate_ppt.py`), and outline-JSON mode\n\n---\n\n## 📦 Installation\n\n```bash\npip install python-pptx lxml Pillow\n```\n\nOptional (for visual QA preview):\n\n```bash\napt install libreoffice-impress poppler-utils fonts-noto-cjk\n```\n\nFrom source (after cloning):\n\n```bash\ngit clone <repo> deckcraft\ncd deckcraft\npip install -r requirements.txt\n```\n\n---\n\n## 🚀 Quick Start\n\n### Python API\n\n```python\nimport sys\nsys.path.insert(0, \"path/to/deckcraft\")\nfrom engine import DeckEngine\n\n# 16:9 widescreen (default)\neng = DeckEngine(theme_name=\"business\")\neng.cover(title=\"Q3 Marketing Plan\", subtitle=\"Strategic Roadmap\", author=\"Marketing Team\", date=\"2026-06-03\")\neng.toc(items=[(\"01\", \"Market Analysis\", \"Industry trends & competitor landscape\")])\neng.content(title=\"Key Insights\", bullets=[\"Gen-Z prefers short-form video\", \"ROI 2.3x on creator partnerships\"], key_point=\"Lean into TikTok + Xiaohongshu\")\neng.summary(title=\"Takeaways\", key_points=[\"Lead with creative, not media\"], conclusion=\"Approve 60% budget shift by June 15\")\neng.closing(message=\"Questions?\")\neng.save(\"q3_plan.pptx\")\n```\n\n### CLI\n\n```bash\npython3 scripts/generate_ppt.py outline.json -o output.pptx --theme business --canvas 16:9\n```\n\n### Multi-canvas\n\n```python\n# 9:16 for social media (mobile, TikTok, Instagram Reels)\neng = DeckEngine(canvas=\"9:16\")\neng.cover(title=\"Product Launch\")\neng.content(title=\"Features\", bullets=[\"Fast\", \"Beautiful\", \"Affordable\"])\neng.save(\"launch_vertical.pptx\")\n\n# 1:1 for Instagram square\neng = DeckEngine(canvas=\"1:1\")\n# ... \n\n# A4 for printing\neng = DeckEngine(canvas=\"A4\")\n# ...\n```\n\n### Importing from existing documents (v5.3+)\n\nTurn a PDF, DOCX, or Markdown file into a deck outline, then render:\n\n```bash\n# 1. Import → outline JSON\npython3 scripts/import_source.py brief.pdf -o outline.json\n\n# 2. Edit outline.json (optional) to fine-tune page types and content\n\n# 3. Render → PPTX\npython3 scripts/generate_ppt.py -i outline.json -o deck.pptx\n```\n\nSupported formats: **PDF** (via PyMuPDF), **DOCX** (via python-docx), **TXT**, **MD**.\n\nThe importer auto-classifies each section as `cover`, `toc`, `content`, `table`, or `stat_cards` using heuristics. You can override with `--page-types \"cover,toc,content,...\"`.\n\nSee [examples/](examples/) for full working samples.\n\n---\n\n## 🎨 Canvas Presets\n\n| Preset | Dimensions | Aliases | Use Case |\n|--------|------------|---------|----------|\n| `16:9` (default) | 10.0\" × 5.625\" | `ppt`, `ppt-16x9` | Standard widescreen |\n| `9:16` | 5.625\" × 10.0\" | `mobile` | Vertical/mobile (TikTok, Reels) |\n| `1:1` | 7.5\" × 7.5\" | `square` | Square (Instagram) |\n| `4:3` | 10.0\" × 7.5\" | — | Classic projector |\n| `A4` | 11.69\" × 8.27\" | — | Print landscape |\n| `A4-portrait` | 8.27\" × 11.69\" | — | Print portrait |\n\nList all: `python3 -c \"from engine.constants import list_canvases; print(list_canvases())\"`\n\n---\n\n## 🏗️ The 5-Stage Workflow\n\n```\nS1 Brief → S2 Structure → S3 Content → S4 Render+QA → S5 Deliver\n                          ⭐ gate        ⭐⭐ gate\n```\n\n### Stage 1: Brief\nCollect audience, goal, duration, key messages, style. Output: `brief.md`\n\n### Stage 2: Structure\nAssign page types, write key points. Output: `outline.json`\n\n### Stage 3: Content\nFill copy, numbers, chart data. Output: `content.json`\n\n**⭐ Gate S3**: `python3 scripts/gate_check_content.py content.json <project>`\n\n### Stage 4: Render + QA\nGenerate PPTX, then run QA. Output: `output.pptx`\n\n**⭐⭐ Gate S4**: `python3 scripts/gate_check.py output.pptx <project>`\n\n### Stage 5: Deliver\nHand off the PPTX.\n\n**Fast Track** (≤5 pages, no charts, user says \"quick\"): skip S2/S3 gates, but **never skip S4 QA gate**.\n\n---\n\n## 📚 API Reference\n\n### DeckEngine (20+ methods)\n\n| Method | Purpose |\n|--------|---------|\n| `cover(title, subtitle, author, date, image_path)` | Title slide |\n| `toc(items)` | Table of contents |\n| `section_divider(title, section_number, subtitle)` | Section break |\n| `content(title, bullets, key_point, image_path)` | Bullets + optional image |\n| `content_with_icon(title, items)` | Icon-style content |\n| `two_col(left_title, left_items, right_title, right_items)` | Side-by-side |\n| `vs_compare(left_title, right_title, rows)` | Comparison table |\n| `table(headers, rows, insights)` | Data table |\n| `stat_cards(stats)` | KPI cards |\n| `chart_bar/pie/line/gauge(...)` | Native charts |\n| `timeline(milestones)` | Roadmap timeline |\n| `process_flow(steps)` | Step-by-step flow |\n| `matrix_2x2(quadrants)` | 2×2 grid |\n| `quote(text, attribution)` | Quote slide |\n| `image_full(image_path, caption)` | Full-width image |\n| `image_split(image_path, bullets, image_side)` | Image + text |\n| `kpi_dashboard(kpis)` | KPI dashboard |\n| `team_grid(members)` | Team grid |\n| `checklist(items, checked)` | Checklist |\n| `summary(key_points, conclusion)` | Summary slide |\n| `closing(title, message, contact)` | Thank you |\n| `save(path)` | Save PPTX |\n\n### Themes (10)\n\n`business`, `business_dark`, `tech`, `tech_gradient`, `minimal`, `elegant`, `creative`, `green`, `red`, `ocean`\n\n---\n\n## 🧪 QA Gates\n\n### S3 Content Gate\n\n```bash\npython3 scripts/gate_check_content.py content.json <project_dir>\n```\n\nValidates content JSON format. Catches:\n- Unsupported page types\n- Missing required fields\n- Char budget overflow\n- Element count exceeded\n\n### S4 Render Gate\n\n```bash\npython3 scripts/gate_check.py output.pptx <project_dir>\n```\n\nValidates rendered PPTX. Catches:\n- Text/shape overflow (off-slide)\n- Image positioning issues\n- Aspect ratio mismatches\n- Font issues (rough check)\n\nBoth gates output machine-readable JSON. **AI must read the JSON verdict; verbal declaration is not accepted.**\n\n---\n\n## 🎯 Design Principles\n\n1. **Native > Image** — Every shape is real DrawingML. Users can edit, recolor, reposition in PowerPoint.\n2. **Canvas-aware** — Layouts adapt to aspect ratio. No content overflow.\n3. **Theme-driven** — One `theme_name` swap changes entire deck's color/typography.\n4. **Predictable** — Same API + same theme = same output. Easy to iterate.\n5. **Composable** — Mix `content()`, `table()`, `chart_*()` in any order.\n\n---\n\n## 📁 Project Structure\n\n```\ndeckcraft/\n├── SKILL.md                     # Detailed skill spec\n├── README.md                    # This file\n├── CHANGELOG.md                 # Version history\n├── LICENSE                      # MIT\n├── requirements.txt             # Python dependencies\n├── MIGRATION.md                 # Migration guides\n├── engine/\n│   ├── __init__.py\n│   ├── constants.py             # 10 themes + 6 canvas presets\n│   ├── core.py                  # Drawing primitives\n│   ├── chart_engine.py          # Native bar/pie/line/gauge\n│   └── deck_engine.py           # 20+ layout methods\n├── scripts/\n│   ├── generate_ppt.py          # CLI entry point\n│   ├── gate_check.py            # S4 QA gate\n│   └── gate_check_content.py   # S3 content gate\n├── designs/\n│   └── layout_matrix.yaml       # Layout constraints\n├── examples/                    # Working code samples\n│   ├── 01_basic_cover_to_closing.py\n│   ├── 02_multi_canvas.py\n│   └── 03_from_outline_json.py\n└── tests/\n    └── test_smoke.py            # Smoke test (all layouts × all canvases)\n```\n\n---\n\n## 🤝 Contributing\n\nBug reports and PRs welcome. For major changes, please open an issue first.\n\n---\n\n## 📄 License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n## 🔗 Links\n\n- **Changelog**: [CHANGELOG.md](CHANGELOG.md)\n- **Migration**: [MIGRATION.md](MIGRATION.md)\n- **Skill spec**: [SKILL.md](SKILL.md)\n- **Examples**: [examples/](examples/)\n\nFile v5.3.0:_meta.json\n\n{\n  \"ownerId\": \"kn7d5t4546sckyvpj7bb694dn9846fsf\",\n  \"slug\": \"deckcraft\",\n  \"version\": \"5.3.0\",\n  \"publishedAt\": 1780459806762\n}\n\nFile v5.3.0:CHANGELOG.md\n\n# DeckCraft Changelog\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n---\n\n## [5.3.0] - 2026-06-03 — Source Importers\n\n### Added\n\n- **New `engine.importers` package** for converting documents to outline JSON:\n  - `pdf_to_outline()` — PDF → outline via PyMuPDF\n  - `docx_to_outline()` — Word .docx → outline via python-docx\n  - `text_to_outline()` — .txt / .md → outline (built-in)\n  - `detect_and_import()` — auto-detect format by extension\n- **New `scripts/import_source.py` CLI**:\n  - `python3 scripts/import_source.py <file.pdf|docx|txt|md> -o outline.json`\n  - Options: `--theme`, `--canvas`, `--page-types`, `--max-pages`, `--print`\n  - Supports PDF, DOCX, TXT, MD\n- **Heuristic page-type classification**:\n  - First page → `cover`\n  - \"Agenda\"/\"目录\" headings + numbered lists → `toc`\n  - \"Part N\"/\"Section N\" → `section`\n  - Pipe-delimited tables → `table`\n  - \"99% Uptime\" / \"$2M Revenue\" patterns → `stat_cards`\n  - Default → `content`\n- New example: `examples/04_from_source.py` (end-to-end PDF → PPTX)\n- New test: `tests/test_importers.py` (34 tests covering heuristics + 3 importers)\n- New dependencies: `PyMuPDF>=1.23.0`, `python-docx>=1.0.0`\n\n### Test coverage\n\n- 95 smoke + 20 validation + 34 importers = **149 tests, all passing**\n- End-to-end: PDF/DOCX → outline → PPTX → gate_check 100/100\n\n### Notes\n\n- Importers are heuristic — review the generated outline and adjust before publishing\n- Manual page-type override: pass `--page-types \"cover,toc,content,...\"` to skip heuristic\n- See [README.md#importing-from-existing-documents](README.md) for the full workflow\n\n---\n\n## [5.2.0] - 2026-06-03 — Multi-Canvas Support\n\n### Added\n\n- **New `canvas` parameter** for `DeckEngine.__init__()`\n- **6 canvas presets** with **4 aliases**:\n  - `16:9` (default) — 10.0\" × 5.625\" — widescreen (alias: `ppt`, `ppt-16x9`)\n  - `9:16` — 5.625\" × 10.0\" — vertical mobile (TikTok/Reels/Stories) (alias: `mobile`)\n  - `1:1` — 7.5\" × 7.5\" — square (Instagram) (alias: `square`)\n  - `4:3` — 10.0\" × 7.5\" — classic projector\n  - `A4` — 11.69\" × 8.27\" — print landscape\n  - `A4-portrait` — 8.27\" × 11.69\" — print portrait\n- New helper API: `from engine.constants import list_canvases`\n- New tests: `tests/test_smoke.py` (95 layout × canvas tests) + `tests/test_validation.py` (20 input validation tests)\n- New CLI options: `--theme`, `--canvas`, `--list-themes`, `--list-canvases` in `generate_ppt.py`\n- New documentation: `README.md`, `MIGRATION.md`, `LICENSE`\n- New examples: `examples/01_basic_cover_to_closing.py`, `examples/02_multi_canvas.py`, `examples/03_from_outline_json.py`\n\n### Changed\n\n- **Refactored** `deck_engine.py` geometry calculations:\n  - Module-level constants `SLIDE_WIDTH/SLIDE_HEIGHT/MARGIN_*/CONTENT_*` replaced with instance attributes `self.cw/self.ch/self.ml/...` (74 references updated)\n  - All 20 layout methods now use canvas-aware calculations instead of hardcoded `Inches()` values\n- **Input validation** on `__init__`, `cover`, `closing`, `content`, `summary`, `save`:\n  - Invalid theme/canvas raises `ValueError` with helpful list of valid options\n  - Empty/None text raises `ValueError`\n  - Non-string text raises `TypeError`\n  - Out-of-bounds lists raise `ValueError`\n  - Non-`.pptx` path raises `UserWarning`\n  - Missing image file raises `UserWarning` (slide is still created)\n- **Type hints** added to `__init__`, `cover`, `closing`, `content`, `summary`, `save`, plus helpers `_validate_text/_validate_list/_validate_int/_validate_image_path`\n- **Improved CLI** (`generate_ppt.py`): full argparse, `--help`, error handling, exit codes\n- 4 layout methods (cover/content/closing/summary) had a bug where each call added 2 slides instead of 1. **Fixed.**\n\n### Compatibility\n\n- ✅ **16:9 default behavior is 100% backward-compatible** with v5.1\n- ❌ Direct imports of `SLIDE_WIDTH`/`SLIDE_HEIGHT`/`MARGIN_*`/`CONTENT_*` from `engine.constants` are removed (use `DeckEngine` instance attributes or `get_canvas()`)\n- See [MIGRATION.md](MIGRATION.md) for upgrade guide\n\n### Testing\n\n- 95 layout × canvas smoke tests pass (5 canvases × 19 layouts)\n- 20 input validation tests pass\n- 4 layouts × 19 layouts gate check: all 100/100\n\n---\n\n## [5.1.1] - 2026-05 (ClawHub release)\n\nInitial ClawHub release. 5-stage workflow, gate mechanisms, 20+ layout methods.\n\n### Highlights\n\n- 5-stage generation flow: Brief → Structure → Content → Render+QA → Deliver\n- 20+ high-level layout methods\n- 10 built-in color themes\n- 2 QA gates (S3 content + S4 render)\n- Checkpoint recovery\n- Anti-patterns documentation\n\n---\n\n## [5.0.0] - 2026-04 (Initial release)\n\nMajor rewrite from v4. New high-level API, structured workflow, native chart support.\n\n### Highlights\n\n- Replaced v4's low-level `create_slide()`/`add_text()` with high-level layout methods\n- Native chart support via python-pptx (bar, pie, line, gauge)\n- 10 built-in themes\n- CJK font support\n\nFile v5.3.0:MIGRATION.md\n\n# DeckCraft — Migration Guides\n\nHow to upgrade between major versions without breaking your existing code.\n\n---\n\n## v5.2 → v5.3 (Source Importers)\n\n### What changed\n\n- **New `engine.importers` package** for PDF/DOCX/MD → outline conversion\n- **New `scripts/import_source.py` CLI** for batch import\n- **New example**: `examples/04_from_source.py`\n- **New test**: `tests/test_importers.py` (34 tests)\n- **New dependencies**: `PyMuPDF>=1.23.0`, `python-docx>=1.0.0`\n\n### Migration steps\n\n#### No code changes needed\n\nThe v5.3 release is purely **additive**. All v5.2 code continues to work unchanged.\n\n#### To use the new import feature\n\n```bash\n# 1. Install new dependencies\npip install -r requirements.txt\n\n# 2. Import a document\npython3 scripts/import_source.py brief.pdf -o outline.json\n\n# 3. Render (use existing CLI)\npython3 scripts/generate_ppt.py -i outline.json -o deck.pptx\n```\n\nOr use the Python API:\n\n```python\nfrom engine.importers import detect_and_import\noutline = detect_and_import(\"brief.pdf\", theme=\"business\", canvas=\"16:9\")\n```\n\n### Limitations (v5.3 first cut)\n\n- Importers use heuristics for page-type classification — always review the output\n- Image extraction from PDF/DOCX is not supported in v5.3 (text-only)\n- Complex tables may not be detected — use `--page-types` to override\n\n### Testing the upgrade\n\n```bash\npip install pymupdf python-docx\npython3 tests/test_smoke.py        # 95 tests\npython3 tests/test_validation.py   # 20 tests\npython3 tests/test_importers.py    # 34 tests (new)\n```\n\nAll 149 tests should pass.\n\n---\n\n## v5.1 → v5.2 (Multi-Canvas)\n\n### What changed\n\n- `DeckEngine.__init__()` accepts a new `canvas` parameter (default: `\"16:9\"`)\n- Module-level constants (`SLIDE_WIDTH`, `SLIDE_HEIGHT`, `MARGIN_LEFT`, etc.) are now instance attributes (`self.cw`, `self.ch`, `self.ml`, etc.) on `DeckEngine`. **Direct imports of these constants are no longer supported.**\n- New: 6 canvas presets + 4 aliases\n\n### Migration steps\n\n#### If you used `DeckEngine()` with no args\n\n**No changes needed.** Default `canvas=\"16:9\"` preserves exact v5.1 behavior.\n\n```python\n# v5.1 and v5.2 — same code, same output\neng = DeckEngine(theme_name=\"business\")\neng.cover(title=\"Hello\")\neng.save(\"out.pptx\")\n```\n\n#### If you imported constants directly from `engine.constants`\n\n**BREAKING:** Module-level constants are removed. Use `get_canvas()` or the `DeckEngine` instance attributes.\n\n```python\n# ❌ v5.1 (no longer works)\nfrom engine.constants import SLIDE_WIDTH, SLIDE_HEIGHT\nx = SLIDE_WIDTH / 2  # crashes in v5.2\n\n# ✅ v5.2: use DeckEngine instance attributes\neng = DeckEngine(canvas=\"16:9\")\nx = eng.cw / 2\n\n# ✅ v5.2: use get_canvas() for canvas-agnostic access\nfrom engine.constants import get_canvas\ncanvas = get_canvas(\"16:9\")\nx = canvas[\"width\"]\n```\n\n#### If you need a non-16:9 canvas\n\n**New in v5.2.** Add the `canvas` parameter:\n\n```python\n# 9:16 for mobile/social (TikTok, Reels, Stories)\neng = DeckEngine(canvas=\"9:16\")\n\n# 1:1 for Instagram square\neng = DeckEngine(canvas=\"1:1\")\n\n# A4 for print\neng = DeckEngine(canvas=\"A4\")\n```\n\nSee [README.md](README.md#canvas-presets) for the full list of presets and aliases.\n\n#### If you customized layout internals via Inches()\n\n**Most layout positions are now canvas-aware.** If you monkey-patched `deck_engine.py` to use specific `Inches()` values, you may need to recompute for the new canvas dimensions. The 16:9 default still works identically.\n\n### Behavior change: input validation\n\n**v5.2 raises** for invalid inputs that v5.1 silently accepted:\n\n```python\n# v5.1: silently created a slide with empty content\neng.cover(title=\"\")\n\n# v5.2: raises ValueError\n# ValueError: title is required (got empty string)\n```\n\nIf your code generates titles dynamically, add a default or guard:\n\n```python\ntitle = user_input.get(\"title\", \"Untitled\") or \"Untitled\"\neng.cover(title=title)\n```\n\n### Behavior change: slide counts\n\nv5.2 fixes a bug where `cover()`, `content()`, `closing()`, and `summary()` each added **2 slides** per call. They now correctly add **1 slide** per call.\n\nIf you depended on this bug, add an explicit no-op call to compensate (not recommended).\n\n### New CLI options\n\n```bash\n# v5.1\npython3 generate_ppt.py --outline out.json --output out.pptx --style business\n\n# v5.2: --style renamed to --theme, plus new --canvas\npython3 generate_ppt.py -i out.json -o out.pptx --theme business --canvas 16:9\n\n# New: list available themes/canvases\npython3 generate_ppt.py --list-themes\npython3 generate_ppt.py --list-canvases\n```\n\n### Testing the migration\n\nAfter upgrading, run:\n\n```bash\npython3 tests/test_smoke.py        # 95 layout × canvas tests\npython3 tests/test_validation.py   # 20 input validation tests\n```\n\nBoth should pass. If your existing code uses canvas=\"16:9\" (default), it should work unchanged.\n\n---\n\n## v5.0 → v5.1 (Gate Refinements)\n\nv5.1 was a refinement release. The 5-stage workflow and core API are unchanged from v5.0. The main additions were:\n\n- `gate_check_content.py` for S3 content gate (was implicit before)\n- `Checkpoint Recovery` section in SKILL.md\n- `Anti-Patterns` section in SKILL.md\n- Stronger error messages in `gate_check.py`\n\nNo code changes required for v5.0 → v5.1.\n\n---\n\n## v4 → v5 (Major Rewrite)\n\nv5 introduced the 5-stage structured workflow. The v4 API (`create_slide()`, `add_text()`, etc.) was replaced by high-level layout methods (`cover()`, `content()`, `two_col()`, etc.).\n\nIf you have v4 code, you'll need to rewrite. The new API is significantly higher-level and produces better output. See [SKILL.md](SKILL.md#deckengine-api) for the full v5 API.\n\nFile v5.3.0:PUBLISHING.md\n\n# Publishing DeckCraft to ClawHub\n\nHow to publish a new version of DeckCraft.\n\n## Prerequisites\n\n1. **ClawHub CLI installed**:\n   ```bash\n   npm install -g clawhub\n   ```\n\n2. **Logged in**:\n   ```bash\n   clawhub login\n   clawhub whoami  # confirm\n   ```\n\n## Pre-publish checklist\n\nRun all checks before publishing:\n\n```bash\n# 1. All tests pass\npython3 tests/test_smoke.py        # 95 layout × canvas tests\npython3 tests/test_validation.py   # 20 input validation tests\npython3 tests/test_importers.py    # 34 importer tests (v5.3+)\n\n# 2. All examples work\npython3 examples/01_basic_cover_to_closing.py\npython3 examples/02_multi_canvas.py\npython3 examples/03_from_outline_json.py\npython3 examples/04_from_source.py     # v5.3+\n\n# 3. CLI works\npython3 scripts/generate_ppt.py --list-themes\npython3 scripts/generate_ppt.py --list-canvases\npython3 scripts/generate_ppt.py -i examples/03_outline.json -o /tmp/cli_test.pptx\npython3 scripts/import_source.py --help    # v5.3+\n\n# 4. No personal info or local paths\ngrep -rn \"天天\\|毛毛\\|simon\\|@user\\|localhost\" .  # should be empty\ngrep -rn \"/home/\\|/Users/\" .                        # should be empty (only test files)\n```\n\n## Version bump\n\nUpdate version in:\n\n- `SKILL.md` (line: `**Version**: X.Y.Z`)\n- `CHANGELOG.md` (new section header)\n- `engine/__init__.py` (if applicable)\n- This file (`PUBLISHING.md`)\n\nUse [SemVer](https://semver.org/):\n- **MAJOR** (5.x → 6.x): breaking API changes\n- **MINOR** (5.1 → 5.2): backward-compatible new features\n- **PATCH** (5.1.0 → 5.1.1): bug fixes, no new features\n\n## Build & validate\n\nBefore publishing, do a clean test:\n\n```bash\n# Fresh install\npip install -r requirements.txt\n\n# Run all tests\npython3 -m pytest tests/  # if pytest installed\n# or\npython3 tests/test_smoke.py && python3 tests/test_validation.py\n```\n\n## Publish\n\n```bash\nclawhub publish ./deckcraft \\\n  --slug deckcraft \\\n  --name \"DeckCraft\" \\\n  --version 5.2.0 \\\n  --changelog \"v5.2.0: Multi-canvas support (16:9/9:16/1:1/4:3/A4), input validation, 95+20 tests, MIT license, README/MIGRATION docs\"\n```\n\nThe CLI will:\n1. Hash local files\n2. Resolve any matching published version\n3. Upload new version to the registry\n4. Confirm success with the new version URL\n\n## Post-publish\n\n1. **Verify the listing**:\n   ```bash\n   clawhub search \"deckcraft\"\n   clawhub list  # confirm in installed skills\n   ```\n\n2. **Test install** in a fresh environment:\n   ```bash\n   clawhub install deckcraft --version 5.2.0\n   python3 -c \"from engine import DeckEngine; eng = DeckEngine(canvas='9:16'); eng.cover(title='Hello'); eng.save('/tmp/test.pptx')\"\n   ```\n\n3. **Update local** (if you have it installed via ClawHub):\n   ```bash\n   clawhub update deckcraft\n   ```\n\n## Versioning policy\n\n- **Patch releases** (5.2.0 → 5.2.1): bug fixes only, automatic\n- **Minor releases** (5.2 → 5.3): new features, must pass all tests, must update CHANGELOG\n- **Major releases** (5 → 6): breaking changes, must update MIGRATION.md, may require user action\n\n## Rollback\n\nIf a release is broken:\n\n1. Fix the issue in source\n2. Bump version (5.2.0 → 5.2.1) — never overwrite\n3. Re-publish\n4. Notify users via CHANGELOG\n\nYou cannot delete a published version from ClawHub, only supersede it.\n\nFile v5.3.0:skill-card.md\n\n## Description: <br>\nDeckCraft helps agents create natively editable PowerPoint presentations through a structured 5-stage workflow with machine-readable QA gates, checkpoint recovery, native charts, document importers, and multi-canvas output. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[simon2256928](https://clawhub.ai/user/simon2256928) <br>\n\n### License/Terms of Use: <br>\nMIT <br>\n\n\n## Use Case: <br>\nEmployees, developers, and presentation authors use DeckCraft to turn briefs, outlines, or source documents into editable PPTX decks with consistent layouts, charts, and validation gates before delivery. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: Parsing user-supplied documents and images depends on third-party libraries and may expose the agent environment to malformed or untrusted files. <br>\nMitigation: Install patched versions of Pillow, PyMuPDF, lxml, python-docx, and python-pptx, and avoid running importers on untrusted source files. <br>\nRisk: Document importers classify sections heuristically, so generated outlines can miss structure or assign the wrong slide type. <br>\nMitigation: Review and adjust imported outline JSON before rendering or publishing a deck. <br>\n\n\n## Reference(s): <br>\n- [DeckCraft ClawHub listing](https://clawhub.ai/simon2256928/deckcraft) <br>\n- [DeckCraft publisher profile](https://clawhub.ai/user/simon2256928) <br>\n- [README](README.md) <br>\n- [CHANGELOG](CHANGELOG.md) <br>\n- [MIGRATION](MIGRATION.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Text, Markdown, Code, Shell commands, Configuration, Guidance] <br>\n**Output Format:** [Markdown guidance with JSON outlines, Python snippets, bash commands, and generated PPTX file paths] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Produces editable PowerPoint decks through python-pptx workflows; source importers can produce outline JSON from PDF, DOCX, TXT, or Markdown for review before rendering.] <br>\n\n## Skill Version(s): <br>\n5.3.0 (source: server evidence and changelog, released 2026-06-03) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v5.3.0:examples/output/03_outline.json\n\n{\n  \"theme\": \"tech\",\n  \"canvas\": \"16:9\",\n  \"pages\": [\n    {\n      \"type\": \"cover\",\n      \"title\": \"Engineering Productivity Report\",\n      \"subtitle\": \"Q1–Q2 2026\",\n      \"author\": \"Platform Team\",\n      \"date\": \"2026-06-03\"\n    },\n    {\n      \"type\": \"toc\",\n      \"items\": [\n        [\n          \"01\",\n          \"Deploy Frequency\",\n          \"How often we ship\"\n        ],\n        [\n          \"02\",\n          \"Lead Time\",\n          \"Commit to production\"\n        ],\n        [\n          \"03\",\n          \"MTTR\",\n          \"Mean time to recover\"\n        ],\n        [\n          \"04\",\n          \"Change Fail Rate\",\n          \"Defects in production\"\n        ]\n      ]\n    },\n    {\n      \"type\": \"stat_cards\",\n      \"title\": \"Q2 Numbers at a Glance\",\n      \"stats\": [\n        [\n          \"42\",\n          \"Deploys / day\"\n        ],\n        [\n          \"2.1h\",\n          \"Lead time (median)\"\n        ],\n        [\n          \"18m\",\n          \"MTTR (median)\"\n        ],\n        [\n          \"3.2%\",\n          \"Change fail rate\"\n        ]\n      ]\n    },\n    {\n      \"type\": \"chart_bar\",\n      \"title\": \"Deploy Frequency by Service\",\n      \"data\": [\n        [\n          48,\n          32,\n          24,\n          16,\n          8\n        ]\n      ],\n      \"labels\": [\n        \"Auth\",\n        \"API\",\n        \"Frontend\",\n        \"Workers\",\n        \"Reports\"\n      ],\n      \"series_names\": [\n        \"Deploys / week\"\n      ]\n    },\n    {\n      \"type\": \"vs_compare\",\n      \"title\": \"Before vs After Platform Engineering\",\n      \"left_title\": \"Before (2025)\",\n      \"right_title\": \"After (2026)\",\n      \"rows\": [\n        [\n          \"Deploys / day\",\n          \"8\",\n          \"42\"\n        ],\n        [\n          \"Lead time\",\n          \"3.5 days\",\n          \"2.1h\"\n        ],\n        [\n          \"MTTR\",\n          \"2.4h\",\n          \"18m\"\n        ],\n        [\n          \"On-call load\",\n          \"High\",\n          \"Low\"\n        ]\n      ]\n    },\n    {\n      \"type\": \"summary\",\n      \"title\": \"What's Next\",\n      \"content\": [\n        \"Reduce lead time further (target: < 1h by Q4)\",\n        \"Invest in self-service deployment tooling\",\n        \"Expand on-call rotation fairness\"\n      ],\n      \"conclusion\": \"Roadmap finalized in next week's eng leadership sync\"\n    },\n    {\n      \"type\": \"closing\",\n      \"title\": \"Q&A\",\n      \"message\": \"Let's discuss tradeoffs\"\n    }\n  ]\n}\n\nFile v5.3.0:examples/output/test_doc_outline.json\n\n{\n  \"theme\": \"business\",\n  \"canvas\": \"16:9\",\n  \"pages\": [\n    {\n      \"type\": \"cover\",\n      \"title\": \"Q3 Marketing Plan\",\n      \"subtitle\": \"Strategic Roadmap for Q3 2026\",\n      \"author\": \"Marketing Team\",\n      \"date\": \"June 2026\"\n    },\n    {\n      \"type\": \"toc\",\n      \"items\": [\n        [\n          \"01\",\n          \"Market Context\",\n          \"\"\n        ],\n        [\n          \"02\",\n          \"Q2 Recap\",\n          \"\"\n        ],\n        [\n          \"03\",\n          \"Q3 Strategy\",\n          \"\"\n        ],\n        [\n          \"04\",\n          \"Budget & Timeline\",\n          \"\"\n        ]\n      ]\n    },\n    {\n      \"type\": \"content\",\n      \"title\": \"Part 1: Market Context\",\n      \"bullets\": [\n        \"Part 1: Market Context\",\n        \"Industry Trends\",\n        \"Short-form video dominates with 3.2x engagement\",\n        \"AI-generated content adoption up 47% YoY\",\n        \"Privacy-first measurement becoming table stakes\"\n      ],\n      \"key_point\": \"\"\n    },\n    {\n      \"type\": \"stat_cards\",\n      \"title\": \"Part 2: Q2 Recap\",\n      \"stats\": [\n        [\n          \"99%\",\n          \"Campaign delivery rate\"\n        ],\n        [\n          \"$2.4M\",\n          \"Q2 spend\"\n        ],\n        [\n          \"12\",\n          \"New brand partners\"\n        ]\n      ]\n    }\n  ]\n}\n\nFile v5.3.0:designs/layout_matrix.yaml\n\n# Layout Matrix — DeckCraft v5\n# Each layout's constraints: char budget, element limits, recommended content density\n\nlayouts:\n  cover:\n    display_name: \"Cover Slide\"\n    description: \"Title slide with optional subtitle, author, date, background image\"\n    char_budget:\n      title: 60\n      subtitle: 40\n    element_limits:\n      max_images: 1\n    recommended_for: [opening, title]\n    dark_bg: true\n\n  closing:\n    display_name: \"Closing Slide\"\n    description: \"Thank you slide with optional message and contact\"\n    char_budget:\n      title: 30\n      message: 50\n      contact: 40\n    element_limits: {}\n    recommended_for: [closing, q_and_a]\n    dark_bg: true\n\n  toc:\n    display_name: \"Table of Contents\"\n    description: \"Agenda slide with numbered items\"\n    char_budget:\n      item_title: 30\n      item_desc: 40\n    element_limits:\n      max_items: 6\n    recommended_for: [agenda, overview]\n\n  section_divider:\n    display_name: \"Section Divider\"\n    description: \"Full dark background section separator\"\n    char_budget:\n      title: 40\n      subtitle: 50\n    element_limits: {}\n    recommended_for: [transition, section_break]\n    dark_bg: true\n\n  content:\n    display_name: \"Content Slide\"\n    description: \"Standard bullet slide with optional image and key point\"\n    char_budget:\n      title: 50\n      bullet: 80\n      key_point: 80\n    element_limits:\n      max_bullets: 5\n      max_images: 1\n    recommended_for: [overview, explanation, data_commentary]\n\n  content_with_icon:\n    display_name: \"Icon Row Content\"\n    description: \"Content with icon-style rows (icon + heading + description)\"\n    char_budget:\n      heading: 30\n      description: 60\n    element_limits:\n      max_items: 5\n    recommended_for: [features, capabilities, list]\n\n  two_col:\n    display_name: \"Two-Column Comparison\"\n    description: \"Side-by-side comparison with card layout\"\n    char_budget:\n      title: 50\n      card_title: 20\n      bullet: 60\n    element_limits:\n      max_items_per_col: 5\n    recommended_for: [comparison, before_after, pros_cons]\n\n  vs_compare:\n    display_name: \"VS Comparison Table\"\n    description: \"Structured comparison table with dimension rows\"\n    char_budget:\n      title: 50\n      dimension: 20\n      value: 20\n    element_limits:\n      max_rows: 6\n    recommended_for: [comparison, competitive_analysis]\n\n  table:\n    display_name: \"Data Table\"\n    description: \"Structured data table with optional insight bullets\"\n    char_budget:\n      title: 50\n      header: 15\n      cell: 20\n      insight: 60\n    element_limits:\n      max_cols: 6\n      max_rows: 8\n      max_insights: 3\n    recommended_for: [data, metrics, financials]\n\n  stat_cards:\n    display_name: \"Stat Cards\"\n    description: \"Big number KPI cards\"\n    char_budget:\n      number: 12\n      label: 20\n    element_limits:\n      max_cards: 4\n    recommended_for: [kpis, headline_numbers, quarterly_results]\n\n  chart_bar:\n    display_name: \"Bar Chart\"\n    description: \"Vertical or horizontal bar chart\"\n    char_budget:\n      title: 50\n      label: 15\n    element_limits:\n      max_categories: 8\n      max_series: 3\n    recommended_for: [comparison, trends, budget_allocation]\n\n  chart_pie:\n    display_name: \"Pie/Donut Chart\"\n    description: \"Pie or donut chart for proportions\"\n    char_budget:\n      title: 50\n      label: 15\n    element_limits:\n      max_segments: 6\n    recommended_for: [market_share, segmentation, distribution]\n\n  chart_line:\n    display_name: \"Line/Area Chart\"\n    description: \"Line or area chart for trends over time\"\n    char_budget:\n      title: 50\n      label: 10\n    element_limits:\n      max_points: 12\n      max_series: 3\n    recommended_for: [trends, growth, forecasting]\n\n  chart_gauge:\n    display_name: \"Gauge Chart\"\n    description: \"Speedometer-style single metric\"\n    char_budget:\n      title: 50\n      label: 15\n    element_limits: {}\n    recommended_for: [single_metric, target_vs_actual, score]\n\n  timeline:\n    display_name: \"Timeline\"\n    description: \"Horizontal timeline with milestone nodes\"\n    char_budget:\n      period: 10\n      event: 25\n    element_limits:\n      max_milestones: 5\n    recommended_for: [roadmap, milestones, project_timeline]\n\n  process_flow:\n    display_name: \"Process Flow\"\n    description: \"Sequential steps with colored cards\"\n    char_budget:\n      step: 30\n    element_limits:\n      max_steps: 5\n    recommended_for: [process, workflow, methodology]\n\n  matrix_2x2:\n    display_name: \"2×2 Matrix\"\n    description: \"Priority/BCG/SWOT-style quadrant matrix\"\n    char_budget:\n      quadrant_title: 20\n      quadrant_desc: 50\n    element_limits: {}\n    recommended_for: [prioritization, bcg_matrix, swot, strategic_framework]\n\n  quote:\n    display_name: \"Quote Slide\"\n    description: \"Large quote with attribution on dark background\"\n    char_budget:\n      quote: 120\n      attribution: 30\n    element_limits: {}\n    recommended_for: [testimonial, vision_statement, keynote_moment]\n    dark_bg: true\n\n  image_full:\n    display_name: \"Full Image\"\n    description: \"Full-width image with title and caption\"\n    char_budget:\n      title: 50\n      caption: 60\n    element_limits:\n      max_images: 1\n    recommended_for: [visual_evidence, screenshot, product_photo]\n\n  image_split:\n    display_name: \"Split Image + Text\"\n    description: \"Image on one side, bullets on the other\"\n    char_budget:\n      title: 50\n      bullet: 60\n    element_limits:\n      max_bullets: 4\n      max_images: 1\n    recommended_for: [product_feature, case_study, data_with_visual]\n\n  kpi_dashboard:\n    display_name: \"KPI Dashboard\"\n    description: \"Dashboard with stat cards and progress bars\"\n    char_budget:\n      label: 15\n      value: 8\n      unit: 5\n    element_limits:\n      max_kpis: 4\n    recommended_for: [dashboard, performance_review, metrics_overview]\n\n  team_grid:\n    display_name: \"Team Grid\"\n    description: \"Team member cards with avatar initials\"\n    char_budget:\n      name: 15\n      role: 20\n    element_limits:\n      max_members: 6\n    recommended_for: [team_introduction, stakeholders, about_us]\n\n  checklist:\n    display_name: \"Checklist\"\n    description: \"Checkable items with done/pending status\"\n    char_budget:\n      item: 50\n    element_limits:\n      max_items: 8\n    recommended_for: [action_items, requirements, audit]\n\n  summary:\n    display_name: \"Summary / Key Takeaways\"\n    description: \"Key takeaways on dark background with card list\"\n    char_budget:\n      title: 40\n      point: 80\n      conclusion: 60\n    element_limits:\n      max_points: 5\n    recommended_for: [closing, key_takeaways, recommendations]\n    dark_bg: true\n\nFile v5.3.0:LICENSE\n\nMIT License\n\nCopyright (c) 2026 DeckCraft Contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n\nFile v5.3.0:requirements.txt\n\n# DeckCraft v5.3.0 — Python dependencies\n# Core\npython-pptx>=0.6.21\nlxml>=4.9.0\nPillow>=9.0.0\n\n# Source importers (v5.3+)\nPyMuPDF>=1.23.0   # PDF parsing\npython-docx>=1.0.0  # DOCX parsing\n\n# Optional: visual QA preview\n# LibreOffice Impress (soffice): apt install libreoffice-impress\n# Poppler (pdftoppm): apt install poppler-utils\n# Noto CJK fonts: apt install fonts-noto-cjk\n\nArchive v5.2.0: 24 files, 52890 bytes\n\nFiles: CHANGELOG.md (3592b), designs/layout_matrix.yaml (6608b), engine/__init__.py (185b), engine/chart_engine.py (9677b), engine/constants.py (9143b), engine/core.py (7885b), engine/deck_engine.py (48699b), examples/01_basic_cover_to_closing.py (1705b), examples/02_multi_canvas.py (2767b), examples/03_from_outline_json.py (5835b), examples/output/03_outline.json (2352b), LICENSE (1079b), MIGRATION.md (4162b), PUBLISHING.md (3072b), README.md (8491b), requirements.txt (285b), scripts/gate_check_content.py (7669b), scripts/gate_check.py (5418b), scripts/generate_ppt.py (10456b), skill-card.md (2177b), SKILL.md (8419b), tests/test_smoke.py (5706b), tests/test_validation.py (7545b), _meta.json (128b)\n\nFile v5.2.0:SKILL.md\n\n---\nname: deckcraft\ndescription: >\n  AI PPT creation skill with structured 5-stage generation, machine-readable QA gates,\n  checkpoint recovery, and experience accumulation. 20 layout methods, native charts,\n  visual QA pipeline, automated gate checks, and multi-canvas output (16:9/9:16/1:1/4:3/A4).\n---\n\n# DeckCraft v5 — Harness Engineering\n\n> **Version**: 5.2.0 · **Engine**: DeckEngine (python-pptx native charts) + ChartEngine (native)\n>\n> **Required tools**: Read, Write, Bash\n> **Requires**: `pip install python-pptx lxml Pillow`\n> **Render QA**: LibreOffice Impress (soffice --headless) + poppler-utils (pdftoppm)\n\n---\n\n## Anti-Patterns (Read Before Every Generation)\n\n### Anti-Pattern 1: Declaring \"Gate Passed\" Verbally\n\n**Wrong**: \"QA found 5 errors but all are minor, gate passed.\"\n**Correct**: Run `gate_check.py`, read the JSON, only `\"passed\": true` means pass.\n\n### Anti-Pattern 2: \"I Checked In My Head\"\n\nFormat errors in content JSON are invisible to mental review.\n**Correct**: Run `gate_check_content.py`, read the JSON output.\n\n### Anti-Pattern 3: Skipping the Process for \"Simple\" Decks\n\nEven simple decks can have overflow, font issues, or broken layouts.\n**Correct**: Use Fast Track (see below), but **never skip the QA gate**.\n\n---\n\n## HARD RULES\n\n1. **Every generation must follow the 5-stage flow**\n2. **Gates must be machine-readable** — run the script, read the JSON\n3. **Experience accumulation is recommended** — note pattern-level fixes for future improvement\n4. **All positioning values must use `int()` wrapping** for python-pptx\n5. **Clear paragraphs before adding runs** — never assume `p.runs[0]` exists\n\n---\n\n## 5-Stage Generation Flow\n\n```\nS1 Brief → S2 Structure → S3 Content → S4 Render+QA → S5 Deliver\n                          ⭐ gate        ⭐⭐ gate\n```\n\n### Stage 1: Brief\n\nCollect: audience, goal, duration, key messages, style preference.\n**Output**: `<project>/brief.md`\n\n### Stage 2: Structure\n\nAssign page types, write key points (full insight sentences).\n**Output**: `<project>/outline.json`\n\n### Stage 3: Content\n\nFill copy, numbers, chart data. Respect char budgets in `designs/layout_matrix.yaml`.\n**Output**: `<project>/content.json`\n\n**⭐ Gate S3**:\n\n```bash\npython3 scripts/gate_check_content.py <project>/content.json <project>\n```\n\nRead `gate_content.json` — only `\"passed\": true` allows proceeding.\n\n### Stage 4: Render + QA\n\nGenerate PPTX from content.json, then run QA.\n\n```bash\npython3 scripts/gate_check.py <pptx_path> <project>\n```\n\nRead `gate_result.json` — only `\"passed\": true` allows proceeding.\n\n**Visual QA (render preview)**:\n\n```bash\n# Render PPT → PDF → PNG for visual inspection\nsoffice --headless --convert-to pdf <pptx_path> --outdir <project>/\npdftoppm -png -r 200 <pdf_path> <project>/preview/slide\n```\n\nInspect the PNG images to verify layout, fonts, colors, and chart rendering.\nFix any visual issues found, regenerate, and re-run gate.\n\n### Stage 5: Deliver + Self-Refinement\n\nDeliver the PPTX.\n\n---\n\n## Fast Track (Simple Requests)\n\nWhen **all** conditions are met, skip S2/S3 gates:\n- Total pages ≤ 5\n- No data charts\n- User says \"quick\" / \"fast\" / \"simple\"\n\n**Still required**: S1 + S4 QA gate + S5 delivery.\n\n---\n\n## Checkpoint Recovery\n\nWhen resuming a deck project, check which files exist:\n\n- No `brief.md` → Stage 1\n- No `outline.json` → Stage 2\n- No `content.json` → Stage 3\n- No `gate_content.json` → Stage 3-gate\n- No `.pptx` → Stage 4\n- No `gate_result.json` → Stage 4-gate\n- All present → Stage 5\n\nResume from the identified stage. Do not restart from S1.\n\n---\n\n## DeckEngine API\n\n```python\nimport sys, os\nsys.path.insert(0, '<skill-path>')\nfrom engine import DeckEngine\n\n# v5.2+: canvas parameter (16:9 / 9:16 / 1:1 / 4:3 / A4)\neng = DeckEngine(theme_name=\"business\", canvas=\"16:9\")  # default\neng = DeckEngine(theme_name=\"business\", canvas=\"9:16\")   # vertical mobile (TikTok, Reels, Stories)\neng = DeckEngine(theme_name=\"business\", canvas=\"1:1\")    # square (Instagram)\neng = DeckEngine(theme_name=\"business\", canvas=\"4:3\")    # classic projector\neng = DeckEngine(theme_name=\"business\", canvas=\"A4\")     # print landscape\neng.cover(title=\"Title\", subtitle=\"Sub\", author=\"Author\", date=\"2026\")\neng.toc(items=[(\"1\", \"Chapter\", \"Description\")])\neng.section_divider(\"Section Title\", section_number=1)\neng.content(title=\"Slide\", bullets=[\"Point 1\", \"Point 2\"], key_point=\"Insight\")\neng.content_with_icon(title=\"Slide\", items=[(\"01\", \"Head\", \"Desc\")])\neng.two_col(title=\"Compare\", left_title=\"A\", left_items=[], right_title=\"B\", right_items=[])\neng.vs_compare(title=\"VS\", left_title=\"Before\", right_title=\"After\", rows=[(\"Dim\", \"Val1\", \"Val2\")])\neng.table(title=\"Data\", headers=[\"H1\", \"H2\"], rows=[[\"a\", \"b\"]], insights=[\"Key takeaway\"])\neng.stat_cards(title=\"KPIs\", stats=[(\"99%\", \"Uptime\"), (\"$2M\", \"Revenue\")])\neng.chart_bar(title=\"Revenue\", data=[[4.2, 3.8]], labels=[\"A\", \"B\"], series_names=[\"S1\"])\neng.chart_pie(title=\"Mix\", data=[45, 30, 25], labels=[\"X\", \"Y\", \"Z\"], donut=True)\neng.chart_line(title=\"Trend\", data=[[1, 2, 3]], labels=[\"Q1\", \"Q2\", \"Q3\"])\neng.chart_gauge(title=\"Score\", value=87, max_value=100, label=\"NPS\")\neng.timeline(title=\"Roadmap\", milestones=[(\"Q1\", \"Launch\"), (\"Q2\", \"Scale\")])\neng.process_flow(title=\"Steps\", steps=[\"Research\", \"Build\", \"Launch\"])\neng.matrix_2x2(title=\"Priority\", quadrants=[(\"TL\", \"desc\"), (\"TR\", \"desc\"), (\"BL\", \"desc\"), (\"BR\", \"desc\")])\neng.quote(title=\"Insight\", quote_text=\"Words matter.\", attribution=\"Author\")\neng.image_full(title=\"Visual\", image_path=\"photo.jpg\", caption=\"Detail\")\neng.image_split(title=\"Split\", image_path=\"photo.jpg\", bullets=[\"Point\"])\neng.kpi_dashboard(title=\"Dashboard\", kpis=[(\"Revenue\", 12.4, 15, \"M\")])\neng.team_grid(title=\"Team\", members=[(\"Name\", \"Role\")])\neng.checklist(title=\"Tasks\", items=[\"Task 1\", \"Task 2\"], checked=[True, False])\neng.summary(title=\"Takeaways\", key_points=[\"Point 1\"], conclusion=\"Next step\")\neng.closing(title=\"Thank You\", message=\"Questions?\")  # no page_num (closing slide)\neng.save(\"output.pptx\")\n```\n\n**10 themes**: business, business_dark, tech, tech_gradient, minimal, elegant, creative, green, red, ocean\n\n**Canvas presets (v5.2+)**: `16:9` (default, widescreen), `9:16` (vertical mobile, TikTok/Reels/Stories), `1:1` (square, Instagram), `4:3` (classic projector), `A4` (print landscape), `A4-portrait`. Aliases: `mobile`=9:16, `square`=1:1, `ppt`=16:9.\n\nList available canvases: `from engine.constants import list_canvases; print(list_canvases())`\n\n---\n\n## Design Guide\n\n### Color\n\nExtract from user's original PPT first. Pick a bold palette matching the topic.\nOne dominant color (60-70%), 1-2 supporting, one sharp accent.\n\n### Typography\n\n| Element | Size | Notes |\n|---------|------|-------|\n| Slide title | 26-36pt bold | Must stand out |\n| Body text | 14-16pt | Never below 10pt |\n| Captions | 10-12pt | Muted color |\n\nCJK: Noto Sans CJK SC / Latin: Arial / Calibri\n\n### Spacing\n\n- Minimum margin: 0.5\"\n- Between blocks: 0.3-0.5\"\n- Leave breathing room\n\n### Avoid\n\n- Repeating the same layout on every slide\n- Text-only slides — add visual elements\n- Center-aligned body text\n- Low-contrast text (light on light, dark on dark)\n\n---\n\n## Dependencies\n\n| Tool | Install |\n|------|---------|\n| python-pptx | `pip install python-pptx` |\n| lxml | `pip install lxml` |\n| Pillow | `pip install Pillow` |\n\n**Render QA (optional but recommended)**:\n\n| Tool | Install |\n|------|----------|\n| LibreOffice Impress | `apt install libreoffice-impress` |\n| poppler-utils | `apt install poppler-utils` |\n| Noto Sans CJK | `apt install fonts-noto-cjk` |\n\n---\n\n## Skill File Structure\n\n```\ndeckcraft/\n├── SKILL.md                     # This file\n├── engine/\n│   ├── __init__.py\n│   ├── constants.py             # 10 theme color palettes, typography, grid\n│   ├── core.py                  # Drawing primitives, XML cleanup, CJK font\n│   ├── chart_engine.py          # Native bar/pie/line/gauge charts (python-pptx)\n│   └── deck_engine.py           # 20 layout methods, 40+ high-level API\n├── scripts/\n│   ├── generate_ppt.py          # CLI entry point\n│   ├── gate_check.py            # S4 QA gate → gate_result.json\n│   └── gate_check_content.py   # S3 content gate → gate_content.json\n└── designs/\n    └── layout_matrix.yaml       # 23 layout definitions with char budgets\n```\n\nFile v5.2.0:README.md\n\n# DeckCraft\n\n> **AI-native PPTX generation with structured workflow, machine-readable QA gates, and multi-canvas output.**\n\nGenerate professional, **natively-editable** PowerPoint files (`.pptx`) with a 5-stage structured workflow. Every shape is a real DrawingML object — not an image — so users can click and edit any element in PowerPoint.\n\n[![Version](https://img.shields.io/badge/version-5.2.0-blue)]()\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue)]()\n[![License](https://img.shields.io/badge/license-MIT-green)]()\n\n---\n\n## ✨ Features\n\n- 🎨 **20+ high-level layout methods** — cover, TOC, content, comparison, table, chart, timeline, matrix, quote, summary, closing, and more\n- 📐 **6 canvas presets** — `16:9`, `9:16`, `1:1`, `4:3`, `A4`, `A4-portrait` (mobile, square, classic, print)\n- 🎨 **10 built-in themes** — business, tech, elegant, creative, green, red, ocean, etc.\n- 📊 **Native charts** — bar, pie, line, gauge (using python-pptx's chart engine, not images)\n- ✅ **5-stage structured workflow** — Brief → Structure → Content → Render+QA → Deliver\n- 🚦 **Machine-readable QA gates** — `gate_check.py` + `gate_check_content.py` produce JSON verdict\n- 🔄 **Checkpoint recovery** — resume mid-project without restarting\n- 🌏 **CJK font support** — Noto Sans CJK SC built-in\n- 🛠️ **3 interfaces** — Python API, CLI (`generate_ppt.py`), and outline-JSON mode\n\n---\n\n## 📦 Installation\n\n```bash\npip install python-pptx lxml Pillow\n```\n\nOptional (for visual QA preview):\n\n```bash\napt install libreoffice-impress poppler-utils fonts-noto-cjk\n```\n\nFrom source (after cloning):\n\n```bash\ngit clone <repo> deckcraft\ncd deckcraft\npip install -r requirements.txt\n```\n\n---\n\n## 🚀 Quick Start\n\n### Python API\n\n```python\nimport sys\nsys.path.insert(0, \"path/to/deckcraft\")\nfrom engine import DeckEngine\n\n# 16:9 widescreen (default)\neng = DeckEngine(theme_name=\"business\")\neng.cover(title=\"Q3 Marketing Plan\", subtitle=\"Strategic Roadmap\", author=\"Marketing Team\", date=\"2026-06-03\")\neng.toc(items=[(\"01\", \"Market Analysis\", \"Industry trends & competitor landscape\")])\neng.content(title=\"Key Insights\", bullets=[\"Gen-Z prefers short-form video\", \"ROI 2.3x on creator partnerships\"], key_point=\"Lean into TikTok + Xiaohongshu\")\neng.summary(title=\"Takeaways\", key_points=[\"Lead with creative, not media\"], conclusion=\"Approve 60% budget shift by June 15\")\neng.closing(message=\"Questions?\")\neng.save(\"q3_plan.pptx\")\n```\n\n### CLI\n\n```bash\npython3 scripts/generate_ppt.py outline.json -o output.pptx --theme business --canvas 16:9\n```\n\n### Multi-canvas\n\n```python\n# 9:16 for social media (mobile, TikTok, Instagram Reels)\neng = DeckEngine(canvas=\"9:16\")\neng.cover(title=\"Product Launch\")\neng.content(title=\"Features\", bullets=[\"Fast\", \"Beautiful\", \"Affordable\"])\neng.save(\"launch_vertical.pptx\")\n\n# 1:1 for Instagram square\neng = DeckEngine(canvas=\"1:1\")\n# ... \n\n# A4 for printing\neng = DeckEngine(canvas=\"A4\")\n# ...\n```\n\nSee [examples/](examples/) for full working samples.\n\n---\n\n## 🎨 Canvas Presets\n\n| Preset | Dimensions | Aliases | Use Case |\n|--------|------------|---------|----------|\n| `16:9` (default) | 10.0\" × 5.625\" | `ppt`, `ppt-16x9` | Standard widescreen |\n| `9:16` | 5.625\" × 10.0\" | `mobile` | Vertical/mobile (TikTok, Reels) |\n| `1:1` | 7.5\" × 7.5\" | `square` | Square (Instagram) |\n| `4:3` | 10.0\" × 7.5\" | — | Classic projector |\n| `A4` | 11.69\" × 8.27\" | — | Print landscape |\n| `A4-portrait` | 8.27\" × 11.69\" | — | Print portrait |\n\nList all: `python3 -c \"from engine.constants import list_canvases; print(list_canvases())\"`\n\n---\n\n## 🏗️ The 5-Stage Workflow\n\n```\nS1 Brief → S2 Structure → S3 Content → S4 Render+QA → S5 Deliver\n                          ⭐ gate        ⭐⭐ gate\n```\n\n### Stage 1: Brief\nCollect audience, goal, duration, key messages, style. Output: `brief.md`\n\n### Stage 2: Structure\nAssign page types, write key points. Output: `outline.json`\n\n### Stage 3: Content\nFill copy, numbers, chart data. Output: `content.json`\n\n**⭐ Gate S3**: `python3 scripts/gate_check_content.py content.json <project>`\n\n### Stage 4: Render + QA\nGenerate PPTX, then run QA. Output: `output.pptx`\n\n**⭐⭐ Gate S4**: `python3 scripts/gate_check.py output.pptx <project>`\n\n### Stage 5: Deliver\nHand off the PPTX.\n\n**Fast Track** (≤5 pages, no charts, user says \"quick\"): skip S2/S3 gates, but **never skip S4 QA gate**.\n\n---\n\n## 📚 API Reference\n\n### DeckEngine (20+ methods)\n\n| Method | Purpose |\n|--------|---------|\n| `cover(title, subtitle, author, date, image_path)` | Title slide |\n| `toc(items)` | Table of contents |\n| `section_divider(title, section_number, subtitle)` | Section break |\n| `content(title, bullets, key_point, image_path)` | Bullets + optional image |\n| `content_with_icon(title, items)` | Icon-style content |\n| `two_col(left_title, left_items, right_title, right_items)` | Side-by-side |\n| `vs_compare(left_title, right_title, rows)` | Comparison table |\n| `table(headers, rows, insights)` | Data table |\n| `stat_cards(stats)` | KPI cards |\n| `chart_bar/pie/line/gauge(...)` | Native charts |\n| `timeline(milestones)` | Roadmap timeline |\n| `process_flow(steps)` | Step-by-step flow |\n| `matrix_2x2(quadrants)` | 2×2 grid |\n| `quote(text, attribution)` | Quote slide |\n| `image_full(image_path, caption)` | Full-width image |\n| `image_split(image_path, bullets, image_side)` | Image + text |\n| `kpi_dashboard(kpis)` | KPI dashboard |\n| `team_grid(members)` | Team grid |\n| `checklist(items, checked)` | Checklist |\n| `summary(key_points, conclusion)` | Summary slide |\n| `closing(title, message, contact)` | Thank you |\n| `save(path)` | Save PPTX |\n\n### Themes (10)\n\n`business`, `business_dark`, `tech`, `tech_gradient`, `minimal`, `elegant`, `creative`, `green`, `red`, `ocean`\n\n---\n\n## 🧪 QA Gates\n\n### S3 Content Gate\n\n```bash\npython3 scripts/gate_check_content.py content.json <project_dir>\n```\n\nValidates content JSON format. Catches:\n- Unsupported page types\n- Missing required fields\n- Char budget overflow\n- Element count exceeded\n\n### S4 Render Gate\n\n```bash\npython3 scripts/gate_check.py output.pptx <project_dir>\n```\n\nValidates rendered PPTX. Catches:\n- Text/shape overflow (off-slide)\n- Image positioning issues\n- Aspect ratio mismatches\n- Font issues (rough check)\n\nBoth gates output machine-readable JSON. **AI must read the JSON verdict; verbal declaration is not accepted.**\n\n---\n\n## 🎯 Design Principles\n\n1. **Native > Image** — Every shape is real DrawingML. Users can edit, recolor, reposition in PowerPoint.\n2. **Canvas-aware** — Layouts adapt to aspect ratio. No content overflow.\n3. **Theme-driven** — One `theme_name` swap changes entire deck's color/typography.\n4. **Predictable** — Same API + same theme = same output. Easy to iterate.\n5. **Composable** — Mix `content()`, `table()`, `chart_*()` in any order.\n\n---\n\n## 📁 Project Structure\n\n```\ndeckcraft/\n├── SKILL.md                     # Detailed skill spec\n├── README.md                    # This file\n├── CHANGELOG.md                 # Version history\n├── LICENSE                      # MIT\n├── requirements.txt             # Python dependencies\n├── MIGRATION.md                 # Migration guides\n├── engine/\n│   ├── __init__.py\n│   ├── constants.py             # 10 themes + 6 canvas presets\n│   ├── core.py                  # Drawing primitives\n│   ├── chart_engine.py          # Native bar/pie/line/gauge\n│   └── deck_engine.py           # 20+ layout methods\n├── scripts/\n│   ├── generate_ppt.py          # CLI entry point\n│   ├── gate_check.py            # S4 QA gate\n│   └── gate_check_content.py   # S3 content gate\n├── designs/\n│   └── layout_matrix.yaml       # Layout constraints\n├── examples/                    # Working code samples\n│   ├── 01_basic_cover_to_closing.py\n│   ├── 02_multi_canvas.py\n│   └── 03_from_outline_json.py\n└── tests/\n    └── test_smoke.py            # Smoke test (all layouts × all canvases)\n```\n\n---\n\n## 🤝 Contributing\n\nBug reports and PRs welcome. For major changes, please open an issue first.\n\n---\n\n## 📄 License\n\nMIT — see [LICENSE](LICENSE).\n\n---\n\n## 🔗 Links\n\n- **Changelog**: [CHANGELOG.md](CHANGELOG.md)\n- **Migration**: [MIGRATION.md](MIGRATION.md)\n- **Skill spec**: [SKILL.md](SKILL.md)\n- **Examples**: [examples/](examples/)\n\nFile v5.2.0:_meta.json\n\n{\n  \"ownerId\": \"kn7d5t4546sckyvpj7bb694dn9846fsf\",\n  \"slug\": \"deckcraft\",\n  \"version\": \"5.2.0\",\n  \"publishedAt\": 1780455807942\n}\n\nFile v5.2.0:CHANGELOG.md\n\n# DeckCraft Changelog\n\nAll notable changes to this project will be documented in this file.\n\nThe format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),\nand this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).\n\n---\n\n## [5.2.0] - 2026-06-03 — Multi-Canvas Support\n\n### Added\n\n- **New `canvas` parameter** for `DeckEngine.__init__()`\n- **6 canvas presets** with **4 aliases**:\n  - `16:9` (default) — 10.0\" × 5.625\" — widescreen (alias: `ppt`, `ppt-16x9`)\n  - `9:16` — 5.625\" × 10.0\" — vertical mobile (TikTok/Reels/Stories) (alias: `mobile`)\n  - `1:1` — 7.5\" × 7.5\" — square (Instagram) (alias: `square`)\n  - `4:3` — 10.0\" × 7.5\" — classic projector\n  - `A4` — 11.69\" × 8.27\" — print landscape\n  - `A4-portrait` — 8.27\" × 11.69\" — print portrait\n- New helper API: `from engine.constants import list_canvases`\n- New tests: `tests/test_smoke.py` (95 layout × canvas tests) + `tests/test_validation.py` (20 input validation tests)\n- New CLI options: `--theme`, `--canvas`, `--list-themes`, `--list-canvases` in `generate_ppt.py`\n- New documentation: `README.md`, `MIGRATION.md`, `LICENSE`\n- New examples: `examples/01_basic_cover_to_closing.py`, `examples/02_multi_canvas.py`, `examples/03_from_outline_json.py`\n\n### Changed\n\n- **Refactored** `deck_engine.py` geometry calculations:\n  - Module-level constants `SLIDE_WIDTH/SLIDE_HEIGHT/MARGIN_*/CONTENT_*` replaced with instance attributes `self.cw/self.ch/self.ml/...` (74 references updated)\n  - All 20 layout methods now use canvas-aware calculations instead of hardcoded `Inches()` values\n- **Input validation** on `__init__`, `cover`, `closing`, `content`, `summary`, `save`:\n  - Invalid theme/canvas raises `ValueError` with helpful list of valid options\n  - Empty/None text raises `ValueError`\n  - Non-string text raises `TypeError`\n  - Out-of-bounds lists raise `ValueError`\n  - Non-`.pptx` path raises `UserWarning`\n  - Missing image file raises `UserWarning` (slide is still created)\n- **Type hints** added to `__init__`, `cover`, `closing`, `content`, `summary`, `save`, plus helpers `_validate_text/_validate_list/_validate_int/_validate_image_path`\n- **Improved CLI** (`generate_ppt.py`): full argparse, `--help`, error handling, exit codes\n- 4 layout methods (cover/content/closing/summary) had a bug where each call added 2 slides instead of 1. **Fixed.**\n\n### Compatibility\n\n- ✅ **16:9 default behavior is 100% backward-compatible** with v5.1\n- ❌ Direct imports of `SLIDE_WIDTH`/`SLIDE_HEIGHT`/`MARGIN_*`/`CONTENT_*` from `engine.constants` are removed (use `DeckEngine` instance attributes or `get_canvas()`)\n- See [MIGRATION.md](MIGRATION.md) for upgrade guide\n\n### Testing\n\n- 95 layout × canvas smoke tests pass (5 canvases × 19 layouts)\n- 20 input validation tests pass\n- 4 layouts × 19 layouts gate check: all 100/100\n\n---\n\n## [5.1.1] - 2026-05 (ClawHub release)\n\nInitial ClawHub release. 5-stage workflow, gate mechanisms, 20+ layout methods.\n\n### Highlights\n\n- 5-stage generation flow: Brief → Structure → Content → Render+QA → Deliver\n- 20+ high-level layout methods\n- 10 built-in color themes\n- 2 QA gates (S3 content + S4 render)\n- Checkpoint recovery\n- Anti-patterns documentation\n\n---\n\n## [5.0.0] - 2026-04 (Initial release)\n\nMajor rewrite from v4. New high-level API, structured workflow, native chart support.\n\n### Highlights\n\n- Replaced v4's low-level `create_slide()`/`add_text()` with high-level layout methods\n- Native chart support via python-pptx (bar, pie, line, gauge)\n- 10 built-in themes\n- CJK font support\n\nFile v5.2.0:MIGRATION.md\n\n# DeckCraft — Migration Guides\n\nHow to upgrade between major versions without breaking your existing code.\n\n---\n\n## v5.1 → v5.2 (Multi-Canvas)\n\n### What changed\n\n- `DeckEngine.__init__()` accepts a new `canvas` parameter (default: `\"16:9\"`)\n- Module-level constants (`SLIDE_WIDTH`, `SLIDE_HEIGHT`, `MARGIN_LEFT`, etc.) are now instance attributes (`self.cw`, `self.ch`, `self.ml`, etc.) on `DeckEngine`. **Direct imports of these constants are no longer supported.**\n- New: 6 canvas presets + 4 aliases\n\n### Migration steps\n\n#### If you used `DeckEngine()` with no args\n\n**No changes needed.** Default `canvas=\"16:9\"` preserves exact v5.1 behavior.\n\n```python\n# v5.1 and v5.2 — same code, same output\neng = DeckEngine(theme_name=\"business\")\neng.cover(title=\"Hello\")\neng.save(\"out.pptx\")\n```\n\n#### If you imported constants directly from `engine.constants`\n\n**BREAKING:** Module-level constants are removed. Use `get_canvas()` or the `DeckEngine` instance attributes.\n\n```python\n# ❌ v5.1 (no longer works)\nfrom engine.constants import SLIDE_WIDTH, SLIDE_HEIGHT\nx = SLIDE_WIDTH / 2  # crashes in v5.2\n\n# ✅ v5.2: use DeckEngine instance attributes\neng = DeckEngine(canvas=\"16:9\")\nx = eng.cw / 2\n\n# ✅ v5.2: use get_canvas() for canvas-agnostic access\nfrom engine.constants import get_canvas\ncanvas = get_canvas(\"16:9\")\nx = canvas[\"width\"]\n```\n\n#### If you need a non-16:9 canvas\n\n**New in v5.2.** Add the `canvas` parameter:\n\n```python\n# 9:16 for mobile/social (TikTok, Reels, Stories)\neng = DeckEngine(canvas=\"9:16\")\n\n# 1:1 for Instagram square\neng = DeckEngine(canvas=\"1:1\")\n\n# A4 for print\neng = DeckEngine(canvas=\"A4\")\n```\n\nSee [README.md](README.md#canvas-presets) for the full list of presets and aliases.\n\n#### If you customized layout internals via Inches()\n\n**Most layout positions are now canvas-aware.** If you monkey-patched `deck_engine.py` to use specific `Inches()` values, you may need to recompute for the new canvas dimensions. The 16:9 default still works identically.\n\n### Behavior change: input validation\n\n**v5.2 raises** for invalid inputs that v5.1 silently accepted:\n\n```python\n# v5.1: silently created a slide with empty content\neng.cover(title=\"\")\n\n# v5.2: raises ValueError\n# ValueError: title is required (got empty string)\n```\n\nIf your code generates titles dynamically, add a default or guard:\n\n```python\ntitle = user_input.get(\"title\", \"Untitled\") or \"Untitled\"\neng.cover(title=title)\n```\n\n### Behavior change: slide counts\n\nv5.2 fixes a bug where `cover()`, `content()`, `closing()`, and `summary()` each added **2 slides** per call. They now correctly add **1 slide** per call.\n\nIf you depended on this bug, add an explicit no-op call to compensate (not recommended).\n\n### New CLI options\n\n```bash\n# v5.1\npython3 generate_ppt.py --outline out.json --output out.pptx --style business\n\n# v5.2: --style renamed to --theme, plus new --canvas\npython3 generate_ppt.py -i out.json -o out.pptx --theme business --canvas 16:9\n\n# New: list available themes/canvases\npython3 generate_ppt.py --list-themes\npython3 generate_ppt.py --list-canvases\n```\n\n### Testing the migration\n\nAfter upgrading, run:\n\n```bash\npython3 tests/test_smoke.py        # 95 layout × canvas tests\npython3 tests/test_validation.py   # 20 input validation tests\n```\n\nBoth should pass. If your existing code uses canvas=\"16:9\" (default), it should work unchanged.\n\n---\n\n## v5.0 → v5.1 (Gate Refinements)\n\nv5.1 was a refinement release. The 5-stage workflow and core API are unchanged from v5.0. The main additions were:\n\n- `gate_check_content.py` for S3 content gate (was implicit before)\n- `Checkpoint Recovery` section in SKILL.md\n- `Anti-Patterns` section in SKILL.md\n- Stronger error messages in `gate_check.py`\n\nNo code changes required for v5.0 → v5.1.\n\n---\n\n## v4 → v5 (Major Rewrite)\n\nv5 introduced the 5-stage structured workflow. The v4 API (`create_slide()`, `add_text()`, etc.) was replaced by high-level layout methods (`cover()`, `content()`, `two_col()`, etc.).\n\nIf you have v4 code, you'll need to rewrite. The new API is significantly higher-level and produces better output. See [SKILL.md](SKILL.md#deckengine-api) for the full v5 API.\n\nFile v5.2.0:PUBLISHING.md\n\n# Publishing DeckCraft to ClawHub\n\nHow to publish a new version of DeckCraft.\n\n## Prerequisites\n\n1. **ClawHub CLI installed**:\n   ```bash\n   npm install -g clawhub\n   ```\n\n2. **Logged in**:\n   ```bash\n   clawhub login\n   clawhub whoami  # confirm\n   ```\n\n## Pre-publish checklist\n\nRun all checks before publishing:\n\n```bash\n# 1. All tests pass\npython3 tests/test_smoke.py        # 95 layout × canvas tests\npython3 tests/test_validation.py   # 20 input validation tests\n\n# 2. All examples work\npython3 examples/01_basic_cover_to_closing.py\npython3 examples/02_multi_canvas.py\npython3 examples/03_from_outline_json.py\n\n# 3. CLI works\npython3 scripts/generate_ppt.py --list-themes\npython3 scripts/generate_ppt.py --list-canvases\npython3 scripts/generate_ppt.py -i examples/03_outline.json -o /tmp/cli_test.pptx\n\n# 4. No personal info or local paths\ngrep -rn \"天天\\|毛毛\\|simon\\|@user\\|localhost\" .  # should be empty\ngrep -rn \"/home/\\|/Users/\" .                        # should be empty (only test files)\n```\n\n## Version bump\n\nUpdate version in:\n\n- `SKILL.md` (line: `**Version**: X.Y.Z`)\n- `CHANGELOG.md` (new section header)\n- `engine/__init__.py` (if applicable)\n- This file (`PUBLISHING.md`)\n\nUse [SemVer](https://semver.org/):\n- **MAJOR** (5.x → 6.x): breaking API changes\n- **MINOR** (5.1 → 5.2): backward-compatible new features\n- **PATCH** (5.1.0 → 5.1.1): bug fixes, no new features\n\n## Build & validate\n\nBefore publishing, do a clean test:\n\n```bash\n# Fresh install\npip install -r requirements.txt\n\n# Run all tests\npython3 -m pytest tests/  # if pytest installed\n# or\npython3 tests/test_smoke.py && python3 tests/test_validation.py\n```\n\n## Publish\n\n```bash\nclawhub publish ./deckcraft \\\n  --slug deckcraft \\\n  --name \"DeckCraft\" \\\n  --version 5.2.0 \\\n  --changelog \"v5.2.0: Multi-canvas support (16:9/9:16/1:1/4:3/A4), input validation, 95+20 tests, MIT license, README/MIGRATION docs\"\n```\n\nThe CLI will:\n1. Hash local files\n2. Resolve any matching published version\n3. Upload new version to the registry\n4. Confirm success with the new version URL\n\n## Post-publish\n\n1. **Verify the listing**:\n   ```bash\n   clawhub search \"deckcraft\"\n   clawhub list  # confirm in installed skills\n   ```\n\n2. **Test install** in a fresh environment:\n   ```bash\n   clawhub install deckcraft --version 5.2.0\n   python3 -c \"from engine import DeckEngine; eng = DeckEngine(canvas='9:16'); eng.cover(title='Hello'); eng.save('/tmp/test.pptx')\"\n   ```\n\n3. **Update local** (if you have it installed via ClawHub):\n   ```bash\n   clawhub update deckcraft\n   ```\n\n## Versioning policy\n\n- **Patch releases** (5.2.0 → 5.2.1): bug fixes only, automatic\n- **Minor releases** (5.2 → 5.3): new features, must pass all tests, must update CHANGELOG\n- **Major releases** (5 → 6): breaking changes, must update MIGRATION.md, may require user action\n\n## Rollback\n\nIf a release is broken:\n\n1. Fix the issue in source\n2. Bump version (5.2.0 → 5.2.1) — never overwrite\n3. Re-publish\n4. Notify users via CHANGELOG\n\nYou cannot delete a published version from ClawHub, only supersede it.\n\nFile v5.2.0:skill-card.md\n\n## Description: <br>\nDeckCraft helps agents create editable PowerPoint decks through a structured workflow with QA gates, checkpoint recovery, native charts, and multi-canvas output. <br>\n\nThis skill is ready for commercial/non-commercial use. <br>\n\n## Publisher: <br>\n[simon2256928](https://clawhub.ai/user/simon2256928) <br>\n\n### License/Terms of Use: <br>\nMIT <br>\n\n\n## Use Case: <br>\nDevelopers, employees, and external users use DeckCraft to turn briefs or outline JSON into editable PPTX decks, with generated project files, render checks, and QA results supporting review before delivery. <br>\n\n### Deployment Geography for Use: <br>\nGlobal <br>\n\n## Known Risks and Mitigations: <br>\nRisk: The skill creates local deck project files and rendered presentation artifacts. <br>\nMitigation: Run it in a dedicated project directory and review generated files before sharing or publishing. <br>\nRisk: The workflow may run local validation, rendering, and preview commands that depend on Python packages and optional system tools. <br>\nMitigation: Review package and system-tool installs before execution, then rely on the machine-readable QA gate results rather than verbal status. <br>\n\n\n## Reference(s): <br>\n- [DeckCraft ClawHub listing](https://clawhub.ai/simon2256928/deckcraft) <br>\n- [README](README.md) <br>\n- [Migration Guide](MIGRATION.md) <br>\n- [Changelog](CHANGELOG.md) <br>\n\n\n## Skill Output: <br>\n**Output Type(s):** [Guidance, Markdown, Code, Shell commands, Configuration, Files] <br>\n**Output Format:** [Markdown guidance, JSON project files, QA result JSON, shell commands, Python code, and editable PPTX deck files] <br>\n**Output Parameters:** [1D] <br>\n**Other Properties Related to Output:** [Generated decks and QA artifacts are written to local project directories.] <br>\n\n## Skill Version(s): <br>\n5.2.0 (source: CHANGELOG, released 2026-06-03; server release metadata) <br>\n\n## Ethical Considerations: <br>\nUsers should evaluate whether this skill is appropriate for their environment, review any generated or modified files before relying on them, and apply their organization's safety, security, and compliance requirements before deployment. <br>\n\nFile v5.2.0:examples/output/03_outline.json\n\n{\n  \"theme\": \"tech\",\n  \"canvas\": \"16:9\",\n  \"pages\": [\n    {\n      \"type\": \"cover\",\n      \"title\": \"Engineering Productivity Report\",\n      \"subtitle\": \"Q1–Q2 2026\",\n      \"author\": \"Platform Team\",\n      \"date\": \"2026-06-03\"\n    },\n    {\n      \"type\": \"toc\",\n      \"items\": [\n        [\n          \"01\",\n          \"Deploy Frequency\",\n          \"How often we ship\"\n        ],\n        [\n          \"02\",\n          \"Lead Time\",\n          \"Commit to production\"\n        ],\n        [\n          \"03\",\n          \"MTTR\",\n          \"Mean time to recover\"\n        ],\n        [\n          \"04\",\n          \"Change Fail Rate\",\n          \"Defects in production\"\n        ]\n      ]\n    },\n    {\n      \"type\": \"stat_cards\",\n      \"title\": \"Q2 Numbers at a Glance\",\n      \"stats\": [\n        [\n          \"42\",\n          \"Deploys / day\"\n        ],\n        [\n          \"2.1h\",\n          \"Lead time (median)\"\n        ],\n        [\n          \"18m\",\n          \"MTTR (median)\"\n        ],\n        [\n          \"3.2%\",\n          \"Change fail rate\"\n        ]\n      ]\n    },\n    {\n      \"type\": \"chart_bar\",\n      \"title\": \"Deploy Frequency by Service\",\n      \"data\": [\n        [\n          48,\n          32,\n          24,\n          16,\n          8\n        ]\n      ],\n      \"labels\": [\n        \"Auth\",\n        \"API\",\n        \"Frontend\",\n        \"Workers\",\n        \"Reports\"\n      ],\n      \"series_names\": [\n        \"Deploys / week\"\n      ]\n    },\n    {\n      \"type\": \"vs_compare\",\n      \"title\": \"Before vs After Platform Engineering\",\n      \"left_title\": \"Before (2025)\",\n      \"right_title\": \"After (2026)\",\n      \"rows\": [\n        [\n          \"Deploys / day\",\n          \"8\",\n          \"42\"\n        ],\n        [\n          \"Lead time\",\n          \"3.5 days\",\n          \"2.1h\"\n        ],\n        [\n          \"MTTR\",\n          \"2.4h\",\n          \"18m\"\n        ],\n        [\n          \"On-call load\",\n          \"High\",\n          \"Low\"\n        ]\n      ]\n    },\n    {\n      \"type\": \"summary\",\n      \"title\": \"What's Next\",\n      \"content\": [\n        \"Reduce lead time further (target: < 1h by Q4)\",\n        \"Invest in self-service deployment tooling\",\n        \"Expand on-call rotation fairness\"\n      ],\n      \"conclusion\": \"Roadmap finalized in next week's eng leadership sync\"\n    },\n    {\n      \"type\": \"closing\",\n      \"title\": \"Q&A\",\n      \"message\": \"Let's discuss tradeoffs\"\n    }\n  ]\n}\n\nFile v5.2.0:designs/layout_matrix.yaml\n\n# Layout Matrix — DeckCraft v5\n# Each layout's constraints: char budget, element limits, recommended content density\n\nlayouts:\n  cover:\n    display_name: \"Cover Slide\"\n    description: \"Title slide with optional subtitle, author, date, background image\"\n    char_budget:\n      title: 60\n      subtitle: 40\n    element_limits:\n      max_images: 1\n    recommended_for: [opening, title]\n    dark_bg: true\n\n  closing:\n    display_name: \"Closing Slide\"\n    description: \"Thank you slide with optional message and contact\"\n    char_budget:\n      title: 30\n      message: 50\n      contact: 40\n    element_limits: {}\n    recommended_for: [closing, q_and_a]\n    dark_bg: true\n\n  toc:\n    display_name: \"Table of Contents\"\n    description: \"Agenda slide with numbered items\"\n    char_budget:\n      item_title: 30\n      item_desc: 40\n    element_limits:\n      max_items: 6\n    recommended_for: [agenda, overview]\n\n  section_divider:\n    display_name: \"Section Divider\"\n    description: \"Full dark background section separator\"\n    char_budget:\n      title: 40\n      subtitle: 50\n    element_limits: {}\n    recommended_for: [transition, section_break]\n    dark_bg: true\n\n  content:\n    display_name: \"Content Slide\"\n    description: \"Standard bullet slide with optional image and key point\"\n    char_budget:\n      title: 50\n      bullet: 80\n      key_point: 80\n    element_limits:\n      max_bullets: 5\n      max_images: 1\n    recommended_for: [overview, explanation, data_commentary]\n\n  content_with_icon:\n    display_name: \"Icon Row Content\"\n    description: \"Content with icon-style rows (icon + heading + description)\"\n    char_budget:\n      heading: 30\n      description: 60\n    element_limits:\n      max_items: 5\n    recommended_for: [features, capabilities, list]\n\n  two_col:\n    display_name: \"Two-Column Comparison\"\n    description: \"Side-by-side comparison with card layout\"\n    char_budget:\n      title: 50\n      card_title: 20\n      bullet: 60\n    element_limits:\n      max_items_per_col: 5\n    recommended_for: [comparison, before_after, pros_cons]\n\n  vs_compare:\n    display_name: \"VS Comparison Table\"\n    description: \"Structured comparison table with dimension rows\"\n    char_budget:\n      title: 50\n      dimension: 20\n      value: 20\n    element_limits:\n      max_rows: 6\n    recommended_for: [comparison, competitive_analysis]\n\n  table:\n    display_name: \"Data Table\"\n    description: \"Structured data table with optional insight bullets\"\n    char_budget:\n      title: 50\n      header: 15\n      cell: 20\n      insight: 60\n    element_limits:\n      max_cols: 6\n      max_rows: 8\n      max_insights: 3\n    recommended_for: [data, metrics, financials]\n\n  stat_cards:\n    display_name: \"Stat Cards\"\n    description: \"Big number KPI cards\"\n    char_budget:\n      number: 12\n      label: 20\n    element_limits:\n      max_cards: 4\n    recommended_for: [kpis, headline_numbers, quarterly_results]\n\n  chart_bar:\n    display_name: \"Bar Chart\"\n    description: \"Vertical or horizontal bar chart\"\n    char_budget:\n      title: 50\n      label: 15\n    element_limits:\n      max_categories: 8\n      max_series: 3\n    recommended_for: [comparison, trends, budget_allocation]\n\n  chart_pie:\n    display_name: \"Pie/Donut Chart\"\n    description: \"Pie or donut chart for proportions\"\n    char_budget:\n      title: 50\n      label: 15\n    element_limits:\n      max_segments: 6\n    recommended_for: [market_share, segmentation, distribution]\n\n  chart_line:\n    display_name: \"Line/Area Chart\"\n    description: \"Line or area chart for trends over time\"\n    char_budget:\n      title: 50\n      label: 10\n    element_limits:\n      max_points: 12\n      max_series: 3\n    recommended_for: [trends, growth, forecasting]\n\n  chart_gauge:\n    display_name: \"Gauge Chart\"\n    description: \"Speedometer-style single metric\"\n    char_budget:\n      title: 50\n      label: 15\n    element_limits: {}\n    recommended_for: [single_metric, target_vs_actual, score]\n\n  timeline:\n    display_name: \"Timeline\"\n    description: \"Horizontal timeline with milestone nodes\"\n    char_budget:\n      period: 10\n      event: 25\n    element_limits:\n      max_milestones: 5\n    recommended_for: [roadmap, milestones, project_timeline]\n\n  process_flow:\n    display_name: \"Process Flow\"\n    description: \"Sequential steps with colored cards\"\n    char_budget:\n      step: 30\n    element_limits:\n      max_steps: 5\n    recommended_for: [process, workflow, methodology]\n\n  matrix_2x2:\n    display_name: \"2×2 Matrix\"\n    description: \"Priority/BCG/SWOT-style quadrant matrix\"\n    char_budget:\n      quadrant_title: 20\n      quadrant_desc: 50\n    element_limits: {}\n    recommended_for: [prioritization, bcg_matrix, swot, strategic_framework]\n\n  quote:\n    display_name: \"Quote Slide\"\n    description: \"Large quote with attribution on dark background\"\n    char_budget:\n      \n\nArchive v5.1.1: 12 files, 27686 bytes\n\nFiles: designs/layout_matrix.yaml (6608b), engine/__init__.py (185b), engine/chart_engine.py (9677b), engine/constants.py (7226b), engine/core.py (7885b), engine/deck_engine.py (39939b), scripts/gate_check_content.py (7669b), scripts/gate_check.py (5418b), scripts/generate_ppt.py (7021b), skill-card.md (2137b), SKILL.md (8407b), _meta.json (128b)\n\nArchive v5.1.0: 11 files, 26482 bytes\n\nFiles: designs/layout_matrix.yaml (6608b), engine/__init__.py (185b), engine/chart_engine.py (9677b), engine/constants.py (7226b), engine/core.py (7885b), engine/deck_engine.py (39939b), scripts/gate_check_content.py (7669b), scripts/gate_check.py (5418b), scripts/generate_ppt.py (7021b), SKILL.md (8150b), _meta.json (128b)\n\nArchive v5.0.2: 11 files, 25166 bytes\n\nFiles: designs/layout_matrix.yaml (6608b), engine/__init__.py (185b), engine/chart_engine.py (9083b), engine/constants.py (7225b), engine/core.py (7885b), engine/deck_engine.py (39173b), scripts/gate_check_content.py (7385b), scripts/gate_check.py (5418b), scripts/generate_ppt.py (3751b), SKILL.md (7032b), _meta.json (128b)\n\nArchive v5.0.1: 11 files, 25177 bytes\n\nFiles: designs/layout_matrix.yaml (6608b), engine/__init__.py (185b), engine/chart_engine.py (9083b), engine/constants.py (7225b), engine/core.py (7885b), engine/deck_engine.py (39173b), scripts/gate_check_content.py (7385b), scripts/gate_check.py (5418b), scripts/generate_ppt.py (3751b), SKILL.md (7086b), _meta.json (128b)\n\nArchive v5.0.0: 31 files, 44140 bytes\n\nFiles: designs/layout_matrix.yaml (6608b), designs/styles/business_dark.yaml (493b), designs/styles/business.yaml (499b), designs/styles/creative.yaml (500b), designs/styles/elegant.yaml (496b), designs/styles/green.yaml (492b), designs/styles/index.yaml (365b), designs/styles/minimal.yaml (491b), designs/styles/ocean.yaml (482b), designs/styles/red.yaml (483b), designs/styles/tech_gradient.yaml (495b), designs/styles/tech.yaml (486b), engine/__init__.py (185b), engine/chart_engine.py (9083b), engine/constants.py (7225b), engine/core.py (7885b), engine/deck_engine.py (39173b), experiences/chart-limits.md (256b), experiences/cjk-issues.md (986b), experiences/layout-pitfalls.md (1598b), experiences/overflow.md (248b), scripts/analyze_template.py (6727b), scripts/edit_ppt.py (10198b), scripts/gate_check_content.py (7385b), scripts/gate_check.py (5418b), scripts/generate_ppt.py (3751b), scripts/qa_check.py (3412b), scripts/slide_to_images.py (2869b), SKILL.md (18122b), templates/README.md (1231b), _meta.json (128b)\n\nArchive v3.0.3: 6 files, 10482 bytes\n\nFiles: scripts/analyze_template.py (3441b), scripts/generate_ppt.py (15293b), scripts/qa_check.py (3293b), SKILL.md (5805b), templates/README.md (295b), _meta.json (128b)\n\nArchive v3.0.2: 6 files, 10481 bytes\n\nFiles: scripts/analyze_template.py (3441b), scripts/generate_ppt.py (15293b), scripts/qa_check.py (3293b), SKILL.md (5281b), templates/README.md (295b), _meta.json (128b)","readmeExcerpt":"Skill: DeckCraft Owner: simon2256928 Summary: AI PPT creation skill with structured 5-stage generation, machine-readable QA gates, checkpoint recovery, and experience accumulation. 20 layout methods, nat... Tags: ai:5.3.0, canvas:5.3.0, docx:5.3.0, importer:5.3.0, latest:6.0.0, pdf:5.3.0, ppt:5.3.0, pptx:5.3.0, presentation:5.3.0 Version history: v6.0.0 | 2026-06-11T12:02:59.632Z | user v6.0.0: PPT Master integration","codeSnippets":[],"executableExamples":[{"language":"text","snippet":"S1 Brief → S2 Structure → S3 Content → S4 Render+QA → S5 Deliver\n                          ⭐ gate        ⭐⭐ gate"},{"language":"bash","snippet":"python3 scripts/gate_check_content.py <project>/content.json <project>"},{"language":"bash","snippet":"python3 scripts/gate_check.py <pptx_path> <project>"},{"language":"bash","snippet":"# Render PPT → PDF → PNG for visual inspection\nsoffice --headless --convert-to pdf <pptx_path> --outdir <project>/\npdftoppm -png -r 200 <pdf_path> <project>/preview/slide"},{"language":"python","snippet":"import sys, os\nsys.path.insert(0, '<skill-path>')\nfrom engine import DeckEngine\n\n# v5.2+: canvas parameter (16:9 / 9:16 / 1:1 / 4:3 / A4)\neng = DeckEngine(theme_name=\"business\", canvas=\"16:9\")  # default\neng = DeckEngine(theme_name=\"business\", canvas=\"9:16\")   # vertical mobile (TikTok, Reels, Stories)\neng = DeckEngine(theme_name=\"business\", canvas=\"1:1\")    # square (Instagram)\neng = DeckEngine(theme_name=\"business\", canvas=\"4:3\")    # classic projector\neng = DeckEngine(theme_name=\"business\", canvas=\"A4\")     # print landscape\n\n# v6.0+: Multi-role mode (optional strategist → executor workflow)\neng = DeckEngine(theme_name=\"business\", canvas=\"16:9\", role_mode=\"multi\")\nplan = eng.strategist_plan({\"title\": \"My Brief\"})  # get plan template\n# ... fill plan with your LLM ...\neng.execute_plan(filled_plan)                       # generate from plan\neng.cover(title=\"Title\", subtitle=\"Sub\", author=\"Author\", date=\"2026\")\neng.toc(items=[(\"1\", \"Chapter\", \"Description\")])\neng.section_divider(\"Section Title\", section_number=1)\neng.content(title=\"Slide\", bullets=[\"Point 1\", \"Point 2\"], key_point=\"Insight\")\neng.content_with_icon(title=\"Slide\", items=[(\"01\", \"Head\", \"Desc\")])\neng.two_col(title=\"Compare\", left_title=\"A\", left_items=[], right_title=\"B\", right_items=[])\neng.vs_compare(title=\"VS\", left_title=\"Before\", right_title=\"After\", rows=[(\"Dim\", \"Val1\", \"Val2\")])\neng.table(title=\"Data\", headers=[\"H1\", \"H2\"], rows=[[\"a\", \"b\"]], insights=[\"Key takeaway\"])\neng.stat_cards(title=\"KPIs\", stats=[(\"99%\", \"Uptime\"), (\"$2M\", \"Revenue\")])\neng.chart_bar(title=\"Revenue\", data=[[4.2, 3.8]], labels=[\"A\", \"B\"], series_names=[\"S1\"])\neng.chart_pie(title=\"Mix\", data=[45, 30, 25], labels=[\"X\", \"Y\", \"Z\"], donut=True)\neng.chart_line(title=\"Trend\", data=[[1, 2, 3]], labels=[\"Q1\", \"Q2\", \"Q3\"])\neng.chart_gauge(title=\"Score\", value=87, max_value=100, label=\"NPS\")\neng.timeline(title=\"Roadmap\", milestones=[(\"Q1\", \"Launch\"), (\"Q2\", \"Scale\")])\neng.process_flow(title=\"Steps\", steps=[\"Research\", \"Build\", \"Launc"},{"language":"text","snippet":"deckcraft/\n├── SKILL.md                     # This file\n├── engine/\n│   ├── __init__.py\n│   ├── constants.py             # 10 theme color palettes, typography, grid\n│   ├── core.py                  # Drawing primitives, XML cleanup, CJK font\n│   ├── chart_engine.py          # Native bar/pie/line/gauge charts (python-pptx)\n│   ├── deck_engine.py           # 20 layout methods, 40+ high-level API\n│   └── importers/               # v5.3+ source importers\n│       ├── __init__.py\n│       ├── base.py              # Shared heuristics\n│       ├── pdf.py               # PDF → outline (PyMuPDF)\n│       ├── docx.py              # DOCX → outline (python-docx)\n│       └── text.py              # TXT/MD → outline\n├── scripts/\n│   ├── generate_ppt.py          # CLI: outline JSON → PPTX\n│   ├── import_source.py         # v5.3+ CLI: PDF/DOCX/MD → outline\n│   ├── gate_check.py            # S4 QA gate → gate_result.json\n│   └── gate_check_content.py   # S3 content gate → gate_content.json\n├── designs/\n│   └── layout_matrix.yaml       # 23 layout definitions with char budgets\n├── examples/                    # Working code samples\n│   ├── 01_basic_cover_to_closing.py\n│   ├── 02_multi_canvas.py\n│   ├── 03_from_outline_json.py\n│   └── 04_from_source.py        # v5.3+\n└── tests/\n    ├── test_smoke.py            # 95 layout × canvas tests\n    ├── test_validation.py       # 20 input validation tests\n    └── test_importers.py        # v5.3+ 34 importer tests"}],"parameters":null,"dependencies":[],"permissions":[],"extractedFiles":[{"path":"SKILL.md","content":"---\nname: deckcraft\ndescription: >\n  AI PPT creation skill with structured 5-stage generation, machine-readable QA gates,\n  checkpoint recovery, and experience accumulation. 20 layout methods, native charts,\n  visual QA pipeline, automated gate checks, and multi-canvas output (16:9/9:16/1:1/4:3/A4).\n---\n\n# DeckCraft v6 — Harness Engineering\n\n> **Version**: 6.0.0 · **Engine**: DeckEngine (python-pptx native charts) + ChartEngine (native)\n>\n> **Required tools**: Read, Write, Bash\n> **Requires**: `pip install python-pptx lxml Pillow`\n> **Render QA**: LibreOffice Impress (soffice --headless) + poppler-utils (pdftoppm)\n\n---\n\n## Anti-Patterns (Read Before Every Generation)\n\n### Anti-Pattern 1: Declaring \"Gate Passed\" Verbally\n\n**Wrong**: \"QA found 5 errors but all are minor, gate passed.\"\n**Correct**: Run `gate_check.py`, read the JSON, only `\"passed\": true` means pass.\n\n### Anti-Pattern 2: \"I Checked In My Head\"\n\nFormat errors in content JSON are invisible to mental review.\n**Correct**: Run `gate_check_content.py`, read the JSON output.\n\n### Anti-Pattern 3: Skipping the Process for \"Simple\" Decks\n\nEven simple decks can have overflow, font issues, or broken layouts.\n**Correct**: Use Fast Track (see below), but **never skip the QA gate**.\n\n---\n\n## HARD RULES\n\n1. **Every generation must follow the 5-stage flow**\n2. **Gates must be machine-readable** — run the script, read the JSON\n3. **Experience accumulation is recommended** — note pattern-level fixes for future improvement\n4. **All positioning values must use `int()` wrapping** for python-pptx\n5. **Clear paragraphs before adding runs** — never assume `p.runs[0]` exists\n\n---\n\n## 5-Stage Generation Flow\n\n```\nS1 Brief → S2 Structure → S3 Content → S4 Render+QA → S5 Deliver\n                          ⭐ gate        ⭐⭐ gate\n```\n\n### Stage 1: Brief\n\nCollect: audience, goal, duration, key messages, style preference.\n**Output**: `<project>/brief.md`\n\n**Design Spec Template (v6.0+)**: Use `templates/design_spec.md` to capture structured design decisions (canvas, page count, audience, color scheme, typography, speaker notes). A filled example is at `templates/design_spec_demo.md`. Recommended for any deck ≥ 8 pages.\n\n### Stage 2: Structure\n\nAssign page types, write key points (full insight sentences).\n**Output**: `<project>/outline.json`\n\n### Stage 3: Content\n\nFill copy, numbers, chart data. Respect char budgets in `designs/layout_matrix.yaml`.\n**Output**: `<project>/content.json`\n\n**⭐ Gate S3**:\n\n```bash\npython3 scripts/gate_check_content.py <project>/content.json <project>\n```\n\nRead `gate_content.json` — only `\"passed\": true` allows proceeding.\n\n### Stage 4: Render + QA\n\nGenerate PPTX from content.json, then run QA.\n\n```bash\npython3 scripts/gate_check.py <pptx_path> <project>\n```\n\nRead `gate_result.json` — only `\"passed\": true` allows proceeding.\n\n**Visual QA (render preview)**:\n\n```bash\n# Render PPT → PDF → PNG for visual inspection\nsoffice --headless --convert-to pdf <pptx_path> --outdir <project>/\npdftoppm -p"},{"path":"README.md","content":"# DeckCraft\n\n> **AI-native PPTX generation with structured workflow, machine-readable QA gates, and multi-canvas output.**\n\nGenerate professional, **natively-editable** PowerPoint files (`.pptx`) with a 5-stage structured workflow. Every shape is a real DrawingML object — not an image — so users can click and edit any element in PowerPoint.\n\n[![Version](https://img.shields.io/badge/version-5.2.0-blue)]()\n[![Python](https://img.shields.io/badge/python-3.10%2B-blue)]()\n[![License](https://img.shields.io/badge/license-MIT-green)]()\n\n---\n\n## ✨ Features\n\n- 🎨 **20+ high-level layout methods** — cover, TOC, content, comparison, table, chart, timeline, matrix, quote, summary, closing, and more\n- 📐 **6 canvas presets** — `16:9`, `9:16`, `1:1`, `4:3`, `A4`, `A4-portrait` (mobile, square, classic, print)\n- 🎨 **10 built-in themes** — business, tech, elegant, creative, green, red, ocean, etc.\n- 📊 **Native charts** — bar, pie, line, gauge (using python-pptx's chart engine, not images)\n- ✅ **5-stage structured workflow** — Brief → Structure → Content → Render+QA → Deliver\n- 🚦 **Machine-readable QA gates** — `gate_check.py` + `gate_check_content.py` produce JSON verdict\n- 🔄 **Checkpoint recovery** — resume mid-project without restarting\n- 🌏 **CJK font support** — Noto Sans CJK SC built-in\n- 🛠️ **3 interfaces** — Python API, CLI (`generate_ppt.py`), and outline-JSON mode\n\n---\n\n## 📦 Installation\n\n```bash\npip install python-pptx lxml Pillow\n```\n\nOptional (for visual QA preview):\n\n```bash\napt install libreoffice-impress poppler-utils fonts-noto-cjk\n```\n\nFrom source (after cloning):\n\n```bash\ngit clone <repo> deckcraft\ncd deckcraft\npip install -r requirements.txt\n```\n\n---\n\n## 🚀 Quick Start\n\n### Python API\n\n```python\nimport sys\nsys.path.insert(0, \"path/to/deckcraft\")\nfrom engine import DeckEngine\n\n# 16:9 widescreen (default)\neng = DeckEngine(theme_name=\"business\")\neng.cover(title=\"Q3 Marketing Plan\", subtitle=\"Strategic Roadmap\", author=\"Marketing Team\", date=\"2026-06-03\")\neng.toc(items=[(\"01\", \"Market Analysis\", \"Industry trends & competitor landscape\")])\neng.content(title=\"Key Insights\", bullets=[\"Gen-Z prefers short-form video\", \"ROI 2.3x on creator partnerships\"], key_point=\"Lean into TikTok + Xiaohongshu\")\neng.summary(title=\"Takeaways\", key_points=[\"Lead with creative, not media\"], conclusion=\"Approve 60% budget shift by June 15\")\neng.closing(message=\"Questions?\")\neng.save(\"q3_plan.pptx\")\n```\n\n### CLI\n\n```bash\npython3 scripts/generate_ppt.py outline.json -o output.pptx --theme business --canvas 16:9\n```\n\n### Multi-canvas\n\n```python\n# 9:16 for social media (mobile, TikTok, Instagram Reels)\neng = DeckEngine(canvas=\"9:16\")\neng.cover(title=\"Product Launch\")\neng.content(title=\"Features\", bullets=[\"Fast\", \"Beautiful\", \"Affordable\"])\neng.save(\"launch_vertical.pptx\")\n\n# 1:1 for Instagram square\neng = DeckEngine(canvas=\"1:1\")\n# ... \n\n# A4 for printing\neng = DeckEngine(canvas=\"A4\")\n# ...\n```\n\n### Importing from existing documents (v5.3+)\n\nTurn a PDF, DOCX, or Mark"},{"path":"_meta.json","content":"{\n  \"ownerId\": \"kn7d5t4546sckyvpj7bb694dn9846fsf\",\n  \"slug\": \"deckcraft\",\n  \"version\": \"6.0.0\",\n  \"publishedAt\": 1781179379632\n}"},{"path":"CHANGELOG.md","content":"# DeckCraft Changelog\n\n## [6.0.0] - 2026-06-11 — PPT Master Integration (Icon Library / Source Auto-Fetch / CRAP Optimizer / Multi-Role Workflow / 9 New Charts / Industry Colors)\n\n> **Major release** — borrows select capabilities from PPT Master (@lzfxxx, ClawHub score 3.69) while preserving DeckCraft's core philosophy: **python-pptx native (PPTX is editable, not a SVG image dump) + machine-readable gates + 5-stage discipline**.\n\n### Tier 1 (Must-Have)\n\n- **Icon Library (`engine/icons.py`)** — 37 hand-built icons rendered as `python-pptx` native freeform shapes\n  - No SVG embedding — every icon is editable in PowerPoint\n  - `from engine import icon, ICON_NAMES` — 37 icons: `arrow-right`, `arrow-up`, `arrow-up-right`, `bell`, `bookmark`, `calendar`, `chart-bar`, `check`, `circle-checkmark`, `clock`, `cog`, `download`, `edit`, `file`, `filter`, `mail`, `map-pin`, `phone`, `rocket`, `search`, `settings`, `shield`, `star`, `target`, `trending-up`, `user`, `users`, `video`, `zap`, etc.\n  - New example: `examples/05_icons.py`\n\n- **URL → Markdown importer (`importers/url.py`)** — fetch any URL and convert HTML → MD\n  - CLI: `python3 scripts/import_source.py url https://example.com -o out.md`\n\n- **WeChat Article → Markdown importer (`importers/wechat.py`)** — bypass WeChat anti-scraping with custom UA + Referer\n  - CLI: `python3 scripts/import_source.py wechat https://mp.weixin.qq.com/s/xxx -o out.md`\n\n- **CRAP Design Optimizer (`scripts/optimize_crap.py`)** — optional Stage 4.5 diagnostic\n  - Four-dimension analysis: **C**ontrast / **R**epetition / **A**lignment / **P**roximity\n  - Reads PPTX shapes via python-pptx, outputs MD report (does NOT modify the deck)\n  - Use the report to drive a follow-up LLM-driven optimization pass\n\n- **Speaker Notes Module (`scripts/add_notes.py` + `generate_ppt.py --notes-file`)**\n  - Input: `notes.json` (format: `{\"1\": \"page 1 notes\", \"2\": \"page 2 notes\"}`)\n  - Writes to `slide.notes_slide.notes_text_frame.text` for every slide\n  - Integrated as post-processing step in `generate_ppt.py`\n\n### Tier 2 (Recommended)\n\n- **9 New Chart Types (`engine/chart_engine.py`)** — all python-pptx native, no SVG fallback\n  - `chart_funnel(title, stages, values)` — horizontal funnel, 5-7 stages\n  - `chart_gantt(title, tasks, start_date, end_date)` — timeline + task bars\n  - `chart_swot(title, strengths, weaknesses, opportunities, threats)` — 2x2 SWOT matrix\n  - `chart_porter(title, forces)` — Porter's Five Forces (5 circles around center)\n  - `chart_sankey(title, nodes, links)` — simplified flow diagram (rectangles + trapezoid connectors)\n  - `chart_heatmap(title, rows, cols, values)` — color-mapped grid (green→yellow→red)\n  - `chart_radar(title, axes, series_data, series_names)` — polygon-based radar\n  - `chart_treemap(title, items)` — squarified single-level treemap\n  - `chart_waterfall(title, categories, values, is_total)` — waterfall (start/+/-/end + connector line)\n  - New test file: `tests/test_charts_extended.py` (23 tests, all pas"},{"path":"MIGRATION.md","content":"# DeckCraft — Migration Guides\n\nHow to upgrade between major versions without breaking your existing code.\n\n---\n\n## v5.3 → v6.0 (PPT Master Integration)\n\n### What changed\n\n- **New `role_mode` parameter** on `DeckEngine.__init__` (default `\"single\"` — backward-compatible)\n- **New canvas aliases** recognized by `DeckEngine` (8 new names: `xiaohongshu`, `moments`, `weibo`, `story`, `reels`, `ppt`, `mobile`, `square`)\n- **New chart methods** on `chart_engine`: `chart_funnel`, `chart_gantt`, `chart_swot`, `chart_porter`, `chart_sankey`, `chart_heatmap`, `chart_radar`, `chart_treemap`, `chart_waterfall`\n- **New icon API**: `from engine import icon, ICON_NAMES`\n- **New industry color API**: `from engine import INDUSTRY_COLORS, get_industry_theme`\n- **New source importers**: URL and WeChat article → MD (extends `scripts/import_source.py`)\n- **New tools**: `scripts/optimize_crap.py` (CRAP design diagnostic), `scripts/add_notes.py` (speaker notes injection)\n- **New templates**: `templates/design_spec.md` and `templates/design_spec_demo.md`\n- **New test files**: `tests/test_charts_extended.py` (23 tests), `tests/test_role_mode.py` (12 tests)\n- **New examples**: `examples/05_icons.py`, `examples/06_role_mode.py`\n\n### Migration steps\n\n#### If you used `DeckEngine()` with no args\n\n**No changes needed.** Default `theme_name=\"business\"`, `canvas=\"16:9\"`, `role_mode=\"single\"` preserves exact v5.3 behavior.\n\n```python\n# v5.3 and v6.0 — same code, same output\neng = DeckEngine(theme_name=\"business\")\neng.cover(title=\"Hello\")\neng.save(\"out.pptx\")\n```\n\n#### If you specified `canvas=\"16:9\"` (or any existing preset)\n\n**No changes needed.** All v5.3 canvas names (`16:9`, `9:16`, `1:1`, `4:3`, `A4`, `A4-portrait`, `ppt-16x9`, `mobile`, `square`, `ppt`) still work.\n\n#### If you want to try a new alias\n\n```python\n# v6.0: new alias names map to existing canvases\neng = DeckEngine(canvas=\"xiaohongshu\")  # → 9:16\neng = DeckEngine(canvas=\"moments\")      # → 1:1\neng = DeckEngine(canvas=\"story\")        # → 9:16\n```\n\n#### If you want to try multi-role workflow (optional)\n\n```python\n# v6.0: opt-in multi-role mode\neng = DeckEngine(theme_name=\"business\", canvas=\"16:9\", role_mode=\"multi\")\nplan = eng.strategist_plan(brief={...})  # LLM fills this\neng.execute_plan(plan)                   # LLM-driven generation\n```\n\nDefault `role_mode=\"single\"` keeps the v5.3 single-pass behavior.\n\n#### If you want new chart types\n\n```python\neng.chart_funnel(title=\"Funnel\", stages=[\"A\",\"B\",\"C\",\"D\"], values=[100, 80, 40, 20])\neng.chart_swot(title=\"SWOT\", strengths=[...], weaknesses=[...], opportunities=[...], threats=[...])\neng.chart_heatmap(title=\"Heatmap\", rows=[...], cols=[...], values=[[...]])\n# ... and 6 more\n```\n\n#### If you want icons\n\n```python\nfrom engine import icon\nicon(slide=eng._current_slide, name=\"rocket\", x=100, y=100, size=48, color=\"FF6B35\")\n```\n\n#### If you want industry colors\n\n```python\nfrom engine import get_industry_theme\ntheme = get_industry_theme(\"tech\")  # {\"primary\": \"#1565C0\", \""}],"languages":[],"docsSourceLabel":"CLAWHUB","editorialOverview":"AI PPT creation skill with structured 5-stage generation, machine-readable QA gates, checkpoint recovery, and experience accumulation. 20 layout methods, nat... Skill: DeckCraft Owner: simon2256928 Summary: AI PPT creation skill with structured 5-stage generation, machine-readable QA gates, checkpoint recovery, and experience accumulation. 20 layout methods, nat... Tags: ai:5.3.0, canvas:5.3.0, docx:5.3.0, importer:5.3.0, latest:6.0.0, pdf:5.3.0, ppt:5.3.0, pptx:5.3.0, presentation:5.3.0 Version history: v6.0.0 | 2026-06-11T12:02:59.632Z | user v6.0.0: PPT Master integration","editorialQuality":{"score":100,"threshold":65,"status":"ready","wordCount":1235,"uniquenessScore":56,"reasons":[]}},"media":{"evidence":{"source":"no-media","verified":false,"confidence":"low","updatedAt":"2026-10-10T09:00:31.943Z","emptyReason":"No screenshots, media assets, or demo links are available."},"primaryImageUrl":null,"mediaAssetCount":0,"assets":[],"demoUrl":null},"ownerResources":{"evidence":{"source":"unclaimed","verified":false,"confidence":"low","updatedAt":"2026-10-10T09:00:31.943Z","emptyReason":"This page has not been claimed by the agent owner."},"hasCustomPage":false,"customPageUpdatedAt":null,"customLinks":[],"structuredLinks":{"docsUrl":null,"demoUrl":null,"supportUrl":null,"pricingUrl":null,"statusUrl":null},"customPage":null},"relatedAgents":{"evidence":{"source":"protocol-neighbors","verified":false,"confidence":"medium","updatedAt":"2026-10-10T11:50:57.485Z","emptyReason":null},"items":[{"id":"8ebccd8e-3863-4187-8355-c3f14e1f9edf","entityType":"agent","canonicalPath":"/agent/iofficeai-aionui","slug":"iofficeai-aionui","name":"AionUi","description":"Free, local, open-source 24/7 Cowork app and OpenClaw for Gemini CLI, Claude Code, Codex, OpenCode, Qwen Code, Goose CLI, Auggie, and more | 🌟 Star if you like it!","url":"https://github.com/iOfficeAI/AionUi","homepage":"https://www.aionui.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-10-09T19:11:12.944Z","createdAt":"2026-02-25T03:38:16.584Z","downloads":null},{"id":"b917f68a-ebff-438e-84f8-3f4b2494c0bc","entityType":"agent","canonicalPath":"/agent/activepieces-activepieces","slug":"activepieces-activepieces","name":"activepieces","description":"AI Agents & MCPs & AI Workflow Automation • (~400 MCP servers for AI agents) • AI Automation / AI Agent with MCPs • AI Workflows & AI Agents • MCPs for AI Agents","url":"https://github.com/activepieces/activepieces","homepage":"https://www.activepieces.com","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-15T02:22:12.426Z","createdAt":"2026-02-25T03:38:12.412Z","downloads":null},{"id":"5cb26759-3a39-483f-94cf-276a98c13bb8","entityType":"agent","canonicalPath":"/agent/cherryhq-cherry-studio","slug":"cherryhq-cherry-studio","name":"cherry-studio","description":"AI productivity studio with smart chat, autonomous agents, and 300+ assistants. Unified access to frontier LLMs","url":"https://github.com/CherryHQ/cherry-studio","homepage":"https://cherry-ai.com","source":"GITHUB_REPOS","protocols":["MCP","OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-04-11T14:38:40.986Z","createdAt":"2026-02-25T03:38:19.379Z","downloads":null},{"id":"6f6582d0-5d76-4f0f-b81d-86520247950b","entityType":"agent","canonicalPath":"/agent/copilotkit-copilotkit","slug":"copilotkit-copilotkit","name":"CopilotKit","description":"The Frontend for Agents & Generative UI. React + Angular","url":"https://github.com/CopilotKit/CopilotKit","homepage":"https://docs.copilotkit.ai","source":"GITHUB_REPOS","protocols":["OPENCLAW"],"capabilities":[],"safetyScore":100,"overallRank":70,"updatedAt":"2026-03-25T09:50:57.846Z","createdAt":"2026-02-25T03:39:14.617Z","downloads":null}],"links":{"hub":"/agent","source":"/agent/source/clawhub","protocols":[{"label":"OpenClaw","href":"/agent/protocol/openclew"}]}}}