📦 deps(thirdparty): update snapshots

2026-07-18 00:02:59 +00:00
parent 82f7c6e56a
commit 47ce7f78dc
1446 changed files with 141041 additions and 6442 deletions
@@ -0,0 +1,275 @@
+---
+name: pptx-deck-creation
+description: "Create editable, production-ready PPTX decks with narrative planning, explicit layout specs, asset guidance, and quality checks."
+category: office-productivity
+risk: critical
+source: community
+source_repo: kimtth/agent-pptify-kit
+source_type: community
+date_added: "2026-07-14"
+author: kimtth
+tags: [powerpoint, pptx, presentation, slide-design, document-generation]
+tools: [claude, cursor, gemini, codex, antigravity]
+license: "MIT"
+license_source: "https://github.com/kimtth/agent-pptify-kit/blob/main/LICENSE"
+---
+
+# PPTX Deck Creation
+
+## Overview
+
+Create an editable PowerPoint deck from a clear narrative, source evidence, and
+explicit layout decisions. Keep the deck specification and its native
+PowerPoint objects as the source of truth. Images may support a slide, but they
+must not replace editable titles, labels, data, tables, or diagrams.
+
+Use the bundled references for design-profile selection, reference-deck
+analysis, visual-asset decisions, and final quality checks. The skill does not
+ship a general-purpose renderer or bundled runtime scripts.
+
+## Scope Boundary
+
+Use this skill as the primary workflow for creating a new, editable PPTX deck.
+It owns the path from a deck brief through narrative planning, a
+coordinate-explicit specification, task-specific PPTX generation, and final
+quality assurance. Do not redirect a net-new deck to another skill merely
+because the requested deliverable is a `.pptx` file.
+
+Use `@pptx-official` when work starts with an existing PPTX and requires
+package-level operations: raw OOXML editing, template duplication and text
+replacement, speaker notes, comments, animations, or other structural changes
+to that file. It may support a build when those operations are necessary, but
+it is not the default workflow for a net-new deck authored here.
+
+## When to Use This Skill
+
+* Use when a user asks to create a new editable PowerPoint or PPTX deck
+* Use as the default workflow when a new deck needs to be delivered as a `.pptx` file
+* Use when a deck needs a narrative framework, a design direction, and final coordinates
+* Use when analyzing a reference PPTX without copying its binary content
+* Use when reviewing a generated PPTX for layout, package, or accessibility defects
+
+## How It Works
+
+### Step 1: Understand the requested deck
+
+Collect the audience, decision or purpose, language, slide count, source
+material, brand requirements, and delivery format. Ask the user to select a
+narrative framework if they have not already done so. Do not select one on the
+user's behalf.
+
+Use one of these framework spines, or a user-defined alternative:
+
+| Framework | Use case |
+|---|---|
+| `mckinsey` | Executive proposals and strategic recommendations |
+| `scqa` | Situation, complication, question, answer narratives |
+| `pyramid` | Main answer followed by supporting arguments |
+| `mece` | Issue decomposition and workstream synthesis |
+| `action-title` | Executive communications with conclusion-led titles |
+| `assertion-evidence` | Technical or research presentations |
+| `exec-summary-first` | Board and leadership briefings |
+| `custom` | User-defined structure or organization playbook |
+
+Record the resolved framework, its source, title rules, slide sequence, and
+any approved assumptions in the deck summary.
+
+### Step 2: Establish source and design context
+
+Give each factual source a stable ID. Record a source reference for every
+metric, chart value, quotation, and factual claim that appears in the deck.
+Summarize source material into one message per slide rather than pasting long
+documents into the specification.
+
+For a reference presentation, inspect it read-only. Extract palette, font,
+slide-size, template, layout-flow, and topic-sequence signals. Re-author target
+slides with their own explicit coordinates. Do not copy, mutate, or use the
+source PPTX as a template for generated content.
+
+Select a documented design profile from
+[design profiles](references/design-profiles.md). Use the user's named profile
+first. Use a reference deck when one is available. Otherwise, use Fluent UI
+Design Token Guidance by default, use Primer Primitives for GitHub-focused
+technical decks, and use a broader style catalog only when the user requests
+multiple visual directions. Record the selected profile, source URL, license,
+palette, typography, spacing, and signature visual treatment in
+`summary.design_context`.
+
+### Step 3: Plan the story and visual structure
+
+Create one defensible message per slide. Use conclusion-led slide titles when
+the selected framework calls for them. Keep the storyline mutually exclusive
+and collectively exhaustive where appropriate. Include concrete numbers, dates,
+owners, and sources only when supported by the evidence.
+
+Every normal content slide needs a visible, style-derived structure such as an
+accent band, card shell, divider, grid, diagram primitive, or image treatment.
+Avoid plain title-and-bullets slides, default theme colors, and Calibri-only
+output unless the user explicitly requests that treatment.
+
+### Step 4: Author a coordinate-explicit specification
+
+Create a JSON object with `summary` and `slides`. Every generated slide needs
+an `id`, `title`, and complete `layout_tree`. Use final inch-based bounding
+boxes, z-order, colors, font sizes, and grouping. Do not rely on a renderer to
+make layout decisions.
+
+Include this production metadata before building:
+
+```json
+{
+  "summary": {
+    "layout_policy": {
+      "safe_margin": 0.5,
+      "content_bottom": 6.7,
+      "footer_top": 6.85,
+      "minimum_gap": 0.12
+    },
+    "accessibility": {
+      "language": "en-US",
+      "presentation_title": "Deck title"
+    }
+  }
+}
+```
+
+Keep content inside the safe margin and above the footer rail. Use native
+`text`, `shape`, `line`, `table`, and `image` objects. Add alt text to
+meaningful images and a reading order for each production slide. Use images as
+supporting visuals only; recreate essential labels, legend entries, process
+steps, and data values as editable objects.
+
+Use the following object constraints:
+
+* Keep content text at 9 pt or larger; prefer 10 to 12 pt for body copy
+* Keep every child object inside its parent group bounding box
+* Keep table column widths equal to the table width and split dense tables across slides
+* Keep normal content objects within slide bounds; only decorative full-bleed elements may cross an edge
+* Keep images behind overlapping text and preserve their aspect ratio
+* Store `source_ref` with source ID, locator, claim type, and verification status for sourced claims
+
+### Step 5: Create the PPTX deck when requested
+
+Own net-new PPTX creation in this workflow. When a PPTX file is required,
+create a small task-specific builder with the user's approved environment. Start
+slides from a blank layout and create native objects from the final bounding
+boxes. Enable word wrap, disable automatic text resizing, set text insets and
+alignment explicitly, and reject zero or negative bounding boxes before
+building.
+
+Save the authored specification, PPTX, build manifest, audit records, and
+source manifest together. Do not add a large shared renderer or copy source
+presentation content. Use `@pptx-official` only when the requested result also
+requires an existing-file or OOXML workflow.
+
+### Step 6: Validate and repair
+
+Apply the [manual audit checklist](references/audit-checklist.md) before and
+after building. Check collisions, text capacity, font sizes, safe margins,
+group containment, table fit, object bounds, design context, and native
+editability. Reopen the PPTX to verify slide count, package structure, hidden
+slides, actual geometry, language, image alt text, reading order, and table
+headers.
+
+Inspect rendered previews when a compatible renderer is available. Check
+clipping, font fallback, contrast, image crops, and visual hierarchy. Repair
+the specification or the task-specific builder, rebuild, and repeat the audit
+until all deterministic failures are resolved. Report any remaining exception
+with the slide ID, object ID, reason, owner, and review date.
+
+## Reference-Deck Analysis
+
+The skill provides a read-only analysis contract, not packaged code. For a
+specific task, use `python-pptx` and the Office Open XML package to inspect a
+presentation. Produce only the context needed for the task:
+
+* Compact prompt context with slide count, styles, brands, template, and layout
+* Full extraction with `layout_tree`, summary metrics, and render-aware elements
+* Folder-level diagnostics with one result per deck and a manifest
+* Style-master analysis with colors, fonts, layout usage, and flow patterns
+
+Use [reference-deck analysis recipes](references/reference-deck-analysis.md)
+and [Python guidance](references/python-snippets.md) as static implementation
+references. Keep all extraction read-only.
+
+## Visual Assets
+
+Use [visual asset guidelines](references/visual-asset-adapters.md) when an icon,
+image, SVG, or user-managed infographic is needed. Confirm image licensing
+before placing it. Record asset provenance, local path, and alt text. Never ask
+users to provide secrets in chat, and never use a placeholder when acquisition
+fails.
+
+When a provider, output path, or other required setting is missing, ask for the
+non-secret information before generating an infographic. If no configured
+provider is available, omit the asset and continue with editable native slide
+objects.
+
+Before any external generation call, disclose the provider and model, what
+prompt or source material will leave the machine, the likely cost, and the
+output path. Obtain explicit confirmation unless the user already authorized
+that exact operation. Never overwrite an existing output without separate
+confirmation.
+
+## Examples
+
+### Example 1: Executive recommendation deck
+
+A user asks for a 10-slide leadership deck based on a project brief. Confirm
+the audience, choose `exec-summary-first`, summarize the brief into one claim
+per slide, and create coordinate-explicit content cards with a documented
+Fluent UI design context. Add source references for each brief-derived metric,
+then build and audit the requested PPTX.
+
+### Example 2: Reference-deck-informed proposal
+
+A user supplies a prior PPTX and asks for a new proposal in a similar visual
+language. Extract only the existing deck's palette, typography, layout rhythm,
+and template usage. Use those signals to design a new outline and native layout
+tree. Do not duplicate slides, copy the deck's binary parts, or present the
+reference deck as the new deliverable.
+
+## Best Practices
+
+* Keep the business framework and source lineage visible in the deck summary
+* Make each slide title convey the slide's conclusion or narrative role
+* Use source evidence for charts and dashboard-like exhibits
+* Build meaningful content from native editable PowerPoint objects
+* Add a deliberate visual structure to every normal content slide
+* Rebuild and inspect previews after repairing layout or text issues
+
+## Limitations
+
+* This skill does not replace a user-provided brand guide, legal asset review, or expert accessibility review
+* It does not include a general renderer, a bundled extraction module, or credentials for external providers
+* It does not own raw OOXML editing, template duplication, or other mutations of an existing PPTX package
+* Stop and ask for clarification when the audience, source evidence, brand requirements, or required output path is missing
+
+## Security and Safety Notes
+
+* Keep reference-deck analysis read-only and never overwrite the source deck
+* Request confirmation before any task-specific build or repair overwrites an existing output file
+* Use user-managed providers only and keep credentials outside chat and skill content
+* Omit unlicensed or license-ambiguous visual assets instead of substituting placeholders
+
+## Common Pitfalls
+
+### Problem: A slide has more copy than its bounding box can hold
+
+Shorten the copy, enlarge the bounding box, or split the content across slides.
+Do not solve the issue by reducing meaningful content below 9 pt.
+
+### Problem: The deck resembles an unstyled default PowerPoint file
+
+Select and record a design profile, then add explicit background, typography,
+accent, card, divider, or grid primitives to the layout tree.
+
+### Problem: A reference deck is used as a source file for the output
+
+Treat the reference deck as read-only context. Re-author the target deck with
+its own slide specification and native editable content.
+
+## Related Skills
+
+* `@pptx-official` - Use for existing PPTX, OOXML, and template-mutation workflows, not default net-new deck creation
+* `@python-pptx-generator` - Use for focused Python PPTX generation patterns
@@ -0,0 +1,156 @@
+# PPTX Manual Audit Checklist
+
+Apply the specification checks before building. Reopen the PPTX for the final
+geometry, accessibility, package, and rendered-preview checks.
+
+## 1. Content Collisions
+
+For every slide, inspect all `layout_tree` objects. Two `classification: "content"` objects collide when their bounding boxes overlap:
+
+```
+A.x < B.x + B.w  AND  B.x < A.x + A.w
+A.y < B.y + B.h  AND  B.y < A.y + A.h
+```
+
+- **Pass:** zero overlapping content objects per slide.
+- **Fail:** any overlap → move objects, resize bboxes, reduce content density, or split the slide.
+
+## 2. Text Overflows
+
+For each text object estimate whether its text fits within its bbox.
+
+Rough capacity (Latin):
+- Characters per line ≈ `(bbox.w × 72) / (font_size × 0.5)`, using `0.5 em` as an average Latin glyph-width factor
+- Lines available ≈ `(bbox.h × 72) / (font_size × 1.2)`
+  _(bbox in inches, font_size in pt)_
+
+Adjustments:
+- **CJK / full-width text:** use a glyph-width factor near `1.0 em` instead of `0.5 em`. The extractor reports `non_ascii_text` — use it to flag CJK-heavy slides.
+- **Text on a shape/card:** subtract ≈0.1 in of inner padding from each side of the shape before computing capacity; the text occupies the inset inner area, not the full shape.
+
+- **Pass:** estimated text volume ≤ available capacity.
+- **Warning:** likely overflow → inspect the generated PPTX or rendered preview, then shorten bullets, enlarge the bbox, or split the slide when clipping is confirmed. This estimate is a triage heuristic, not a deterministic failure by itself.
+  **Never set `font_size` below 9 pt for `classification: "content"` objects.**
+
+## 3. Font Size Minimums
+
+Scan every object with `classification: "content"`. Check `style.font_size`.
+
+- **Pass:** all content objects ≥ 9 pt.
+- **Fail:** any content object < 9 pt → increase font size and split content if needed.
+
+## 4. Design Context Presence
+
+Inspect `summary.design_context` in the spec root.
+
+- **Pass:** field present and contains `profile_id`, source URL, and license ID.
+- **Fail — any of the following:**
+  - `summary.design_context` absent -> load a design profile from [design-profiles.md](design-profiles.md) and rebuild.
+  - Plain white backgrounds throughout with no accent elements.
+  - Calibri-only text with default theme colors across all slides.
+  - All slides are title-plus-bullets only (no cards, shapes, rules, or image treatments).
+
+## 5. Visual Design Per Slide
+
+For each normal content slide (exclude section headers and hidden appendix slides):
+
+- **Pass:** at least one style-derived visual element present — accent band, card shell, grid cell, rule/divider, shape motif, image treatment, or background pattern.
+- **Fail:** slide is plain white with only text objects → add a design element derived from the selected profile's `source_signals`.
+
+## 6. Narrative and Count
+
+- Slide count is within ±2 of the user's requested count.
+- Topic sequence matches the requested business framework (McKinsey, SCQA, pyramid, etc.) or the user's stated structure.
+- For action-title frameworks (e.g., `action-title`, McKinsey): every content slide has an **action title** (not a descriptive label). Run the ghost-deck test: read only slide titles — they must tell the full story on their own.
+
+## 7. Hidden Slides
+
+If the deck contains hidden slides (`hidden: true`):
+
+- **Pass:** hidden slides are last in the `slides` array unless the user specified otherwise.
+- In the rendered PPTX, confirm `ppt/presentation.xml` contains `p:sldId show="0"` on the correct entries.
+
+## 8. Asset Layering
+
+For slides mixing image/SVG objects with text:
+
+- **Pass:** image/SVG `z_index` is lower than all overlapping text objects.
+- **Fail:** image covers text → lower `z_index`, adjust bbox, or reclassify as `classification: "layout_design"`.
+- A visible slide must not rely on one raster or SVG as its complete content. Recreate essential titles, labels, metrics, chart values, and process steps with native editable objects. Keep the original raster or SVG only as a supporting visual or hidden reference.
+- **Image aspect ratio:** the object `bbox` aspect should match the image's native aspect (fit or crop-to-fill); a mismatched bbox stretches the image. Keep captions in adjacent space, not overlaid on the image.
+
+## 9. Slide Bounds & Safe Margins
+
+For every slide, check each object against the slide rectangle (0,0)–(`slide_size.width`, `slide_size.height`):
+
+- **Pass:** every `classification: "content"` object lies fully inside the slide and inside the content-safe margin (default 0.5 in per edge).
+- **Fail:** an object extends off-slide or into the margin → move or resize it inside. Only `classification: "layout_design"` full-bleed bands may touch or cross an edge.
+
+## 10. Containment
+
+- **Pass:** every child object and child group fits inside its parent group `bbox`; on-shape text fits inside the shape minus ≈0.1 in inner padding.
+- **Fail:** a child spills out of its group, or card text spills past the card padding → resize the child or the parent, or split content.
+
+## 11. Table Fit
+
+For every `kind: "table"` object:
+
+- **Pass:** column widths sum to the table `bbox.width`, each cell's wrapped text fits its row height at the cell font size, and row count is within the per-slide budget (≈8–10 body rows at 10–11 pt).
+- **Fail:** columns overflow the table width, cells clip, or the table is too tall → rebalance columns, raise row height, or split the table across slides (repeat the header).
+
+## 12. Native Editable Content
+
+For every visible slide, inspect the objects that carry the message.
+
+- **Pass:** titles, body text, metrics, labels, tables, charts, and process steps
+  are native editable PowerPoint objects. Images are supporting visuals only.
+- **Fail:** a single raster or SVG contains the only meaningful text, data,
+  explanation, chart values, or diagram labels → recreate that information with
+  editable text, shapes, lines, and tables.
+
+## 13. Post-Build Checks
+
+Reopen the generated PPTX and inspect the actual artifact.
+
+- **Geometry:** confirm the slide count, actual object bounds, safe margins,
+  footer rail, group containment, image placement, and hidden-slide state match
+  the specification. Record failures in the geometry audit.
+- **Accessibility:** confirm document language, unique accessible slide titles,
+  meaningful image alt text, reading order, and table headers. Record failures
+  in the accessibility audit.
+- **Rendered preview:** when a compatible renderer is available, inspect each
+  slide for clipping, font fallback, contrast, image crops, and visual hierarchy.
+  Record the renderer and the review result.
+
+## 14. Production Metadata and Source Lineage
+
+Inspect the summary and the objects that make factual claims.
+
+- **Layout policy:** `summary.layout_policy` names the safe margin, content
+  bottom, footer top, and minimum gap. Confirm `content_bottom` is lower than
+  `footer_top` and that content stays above the footer rail.
+- **Accessibility metadata:** `summary.accessibility` contains a document
+  language and presentation title. Each production slide supplies a reading
+  order for its meaningful objects.
+- **Source lineage:** each sourced metric, chart value, quotation, or factual
+  claim has a `source_ref` containing a source ID, locator, claim type, and
+  verification status. Confirm the source ID appears in the sources manifest.
+- **Build record:** the build manifest records the builder path, input spec,
+  output PPTX, slide count, time, and warnings.
+
+## 15. Positive Geometry
+
+Before and after build, inspect every object bbox and line endpoint.
+
+- **Pass:** every non-line object has positive width and height. A line has two
+  distinct endpoints (`x1 != x2` or `y1 != y2`); horizontal and vertical lines
+  may legitimately have a zero-height or zero-width bounding box.
+- **Fail:** a non-line object has a zero or negative dimension, or a line has
+  identical endpoints. Correct the source geometry before rebuild.
+
+## Completion Criterion
+
+All 15 checks pass before delivery, or each exception is documented with its
+slide ID, object ID, reason, owner, and review date. Any failure triggers the
+repair loop in Step 6 of the parent `pptx-deck-creation` skill: fix the spec,
+rebuild, and re-audit.
@@ -0,0 +1,96 @@
+# PPTX Design Profile Catalog
+
+**This is the bundled reference for design profiles.** Use it for all new decks. Design context is built-in and always available.
+
+## Quick-Select Guide
+
+| Profile ID | Best for |
+|---|---|
+| `fluent-ui-design-tokens` | Microsoft, M365, Teams, Power Platform, enterprise — **default for new decks** |
+| `getdesign-md-design-systems` | **Live fetch** — brand-accurate DESIGN.md analyses (Apple, Stripe, Linear, Notion, …) from getdesign.md when matching a real product's look |
+| `corazzon-pptx-design-styles` | 30 modern style catalog; use when visual variety or multiple direction options are needed |
+| `primer-primitives` | GitHub-style, developer products, token-driven UI reviews, engineering docs |
+
+## Profiles
+
+### `fluent-ui-design-tokens`
+**Name:** Fluent UI Design Token Guidance
+**Kind:** design-system-context
+**License:** MIT — Copyright (c) Microsoft Corporation
+**Source:** [microsoft/fluentui](https://github.com/microsoft/fluentui/blob/master/docs/architecture/design-tokens.md)
+**Token categories:** color, spacing, border radius, font, line height, stroke, shadow, duration, easing
+**Themes:** webLightTheme, webDarkTheme, teamsLightTheme, teamsDarkTheme, teamsHighContrastTheme
+**Agent rule:** Use design tokens instead of hardcoded colors, spacing, or typography values.
+**Best for:** Microsoft-aligned decks, Teams, M365, Power Platform governance, enterprise product reviews
+
+---
+
+### `getdesign-md-design-systems`
+**Name:** getdesign.md — Production-grade DESIGN.md Brand Analyses (Live Fetch)
+**Kind:** live-design-reference-context
+**License:** Per-entry; independent analyses published by VoltAgent. Reference/inspiration only — **not** official, not affiliated with or endorsed by the brands, and not redistributable assets. All trademarks belong to their owners.
+**Source:** [getdesign.md](https://getdesign.md/) · catalog: [getdesign.md/design-md](https://getdesign.md/design-md) · spec basis: Google Stitch's DESIGN.md · awesome list: [VoltAgent/awesome-design-md](https://github.com/VoltAgent/awesome-design-md)
+**Catalog size:** 300+ brand/product DESIGN.md analyses (e.g., Apple, Stripe, Linear, Notion, Vercel, Figma, Airbnb, Spotify, Tesla, IBM/Carbon, NVIDIA)
+
+**What getdesign.md is:** A browsable frontend for the open-source `awesome-design-md` collection. Each catalog entry is a single `DESIGN.md` file — a structured Markdown document (the format introduced by Google Stitch) that captures the *publicly observable* design language of a real website so a coding agent can use it as reference while building original UI. They are analyses of patterns, not pixel-exact reproductions of the source sites.
+
+**Anatomy of a DESIGN.md entry** (consistent section taxonomy across the catalog):
+- **01 — Colors:** Core palette as named tokens with hex + role (e.g., `Primary #533afd`, `Ink #0d253d`, `Canvas #ffffff`, `Canvas Alt`, `Hairline`, `Muted`, `Accent`), plus an extended brand/accent and gradient-stop set.
+- **02 — Typography:** A type scale split into display and body tiers; each token lists size / weight / line-height / letter-spacing and its role (e.g., `display-xxl 56px/300/1.12/-1.4px`, `body-md 16/400/1.55`, `micro-cap 12/700` eyebrow).
+- **03–05 — Components:** Button variants (primary/secondary/outline/on-dark), card examples (incl. inverted/featured tiers), and form-element conventions (input borders, focus treatment).
+- **06–08 — Foundations:** Spacing scale (typically an 8px base with sub-units), border-radius scale (input → pill `9999px`), and elevation/shadow stacks (L0 flat → L3 toast).
+- **09 — Responsive:** Breakpoint stair (mobile/tablet/desktop/wide), touch-target minimums (≥44×44px), and collapsing strategy.
+- Plus a short prose intro describing the brand's "signature" (mood, motifs, hero treatment) and an Additional Links/preview block.
+
+**How users consume it (outside this skill):** The getdesign package offers an `add {slug}` action that drops the file into a project, or users can choose "Download DESIGN.md"; some entries also offer a full website starter kit at `…/design-md/kit`. Inside this skill, treat the page as a *read-only reference* — fetch and extract signals; do not run the installer.
+
+**Fetch contract:** Each entry is reachable at `https://getdesign.md/{slug}/design-md` (e.g., `https://getdesign.md/stripe/design-md`, `https://getdesign.md/linear.app/design-md`). Some slugs include the TLD (`linear.app`, `mistral.ai`, `x.ai`, `opencode.ai`). Browse `https://getdesign.md/design-md` to resolve the correct `{slug}`.
+**Agent rule:** Use this profile only when the user asks for a deck that should match a specific real-world brand or product aesthetic. Fetch the matching DESIGN.md entry, extract the color tokens, type scale, spacing/radius/elevation foundations, and signature motifs, then lock them in `summary.design_context`. Translate signals into explicit `layout_tree` primitives — do not embed scraped images, screenshots, or copy proprietary brand assets/logos. Record the entry URL and the "independent analysis, not affiliated" disclaimer as the design source. If the fetch fails or no slug matches, fall back to a bundled profile and note the fallback.
+**Best for:** Decks that must visually echo a known product or company; brand-accurate palette/typography/foundation sourcing without maintaining a local copy
+
+---
+
+### `corazzon-pptx-design-styles`
+**Name:** corazzon/pptx-design-styles — 30 Modern PPTX Style Templates
+**Kind:** pptx-style-template-context
+**License:** MIT — Copyright TodayCode / corazzon contributors
+**Source:** [corazzon/pptx-design-styles](https://github.com/corazzon/pptx-design-styles)
+**30 styles:** Glassmorphism, Neo-Brutalism, Bento Grid, Dark Academia, Gradient Mesh, Claymorphism, Swiss International, Aurora Neon Glow, Retro Y2K, Nordic Minimalism, Typographic Bold, Duotone Color Split, Monochrome Minimal, Cyberpunk Outline, Editorial Magazine, Pastel Soft UI, Dark Neon Miami, Hand-crafted Organic, Isometric 3D Flat, Vaporwave, Art Deco Luxe, Brutalist Newspaper, Stained Glass Mosaic, Liquid Blob Morphing, Memphis Pop Pattern, Dark Forest Nature, Architectural Blueprint, Maximalist Collage, SciFi Holographic Data, Risograph Print
+**Style families:** modern-ui, editorial, retro, technical, luxury, organic, experimental
+**Source inputs per style:** hex colors, font pairings, layout rules, signature elements, avoid lists
+**Agent rule:** Pick one style, lock its palette and typography, then translate visual effects into explicit editable `layout_tree` primitives. Use raster assets only as supporting visuals. Do not mix styles accidentally.
+**Best for:** Choosing a predefined modern style from a broad catalog; generating multiple visual direction options before deck production
+
+---
+
+### `primer-primitives`
+**Name:** Primer Primitives Design Tokens
+**Kind:** design-system-context
+**License:** MIT — Copyright (c) 2018 GitHub Inc.
+**Source:** [primer/primitives](https://github.com/primer/primitives)
+**Token categories:** color, spacing, typography, motion, z-index
+**Spacing scale:** xxs, xs, sm, md, lg, xl
+**Typography roles:** display, title, subtitle, body, caption, codeBlock, codeInline
+**Color examples:** `#ffffff`, `#1f2328`, `#F6F8FA`, `#0969da`, `#1a7f37`, `#cf222e`
+**Best for:** GitHub-style decks, developer products, token-driven UI reviews, engineering documentation
+
+Use the entries above to:
+
+1. Select the profile ID that best matches the user's audience, topic, and delivery context.
+2. Lock the palette, typography, and signature element conventions described in the profile's `source_signals`.
+3. Record the selected profile ID, source URL, and license in `summary.design_context` before building the deck spec.
+4. Translate the style signals directly into explicit `layout_tree` primitives — colors, fills, rules, card shells, accent bands, and bboxes.
+
+### Fetching Live References from getdesign.md
+
+When the user wants a deck that mirrors a specific real brand or product, use the `getdesign-md-design-systems` profile to pull a live analysis:
+
+1. Browse the catalog at `https://getdesign.md/design-md` to find the brand and its `{slug}` (some slugs carry a TLD, e.g. `linear.app`, `mistral.ai`).
+2. Fetch the entry at `https://getdesign.md/{slug}/design-md` (e.g., `https://getdesign.md/apple/design-md`).
+3. Read the DESIGN.md sections and map them onto deck decisions:
+   - **Colors (01)** → deck palette: `Primary`/`Accent` for emphasis and CTAs, `Ink`/`Muted` for text, `Canvas`/`Canvas Alt` for backgrounds and bands, `Hairline` for rules and dividers.
+   - **Typography (02)** → title vs. body type roles, weights, and relative size hierarchy (display tier for slide titles/kickers, body tier for content).
+   - **Foundations (06–08)** → spacing rhythm, corner radii for card shells/buttons, and elevation cues for layered cards.
+   - **Components (03–05)** + **signature motifs** (intro prose) → card/pill/divider styling and the brand's hallmark accents (e.g., gradient bands).
+4. Record the entry URL, the "independent analysis / not affiliated" disclaimer, and the extracted tokens in `summary.design_context`, then translate the signals into explicit `layout_tree` primitives.
+5. Never embed scraped imagery, screenshots, logos, or other proprietary brand assets; use the signals as design guidance only. If the fetch fails or no slug matches, fall back to a bundled profile and flag the fallback in `summary.design_context`.
@@ -0,0 +1,150 @@
+# PPTX Python Snippets
+
+It describes how to approach PPTX extraction and style analysis with `python-pptx`, using short illustrative
+snippets — not a packaged module to copy wholesale.
+
+- Do not treat these snippets as bundled runtime modules.
+- Do not import from this file or recreate `.py` files under this skill as packaged resources.
+- When a task needs extraction or style analysis, write task-local code with `python-pptx`, using these patterns as reference.
+
+## Shared constants
+
+Most helpers depend on two values: the EMU-per-inch conversion factor and the
+DrawingML namespace used when reading raw OOXML.
+
+```python
+EMU_PER_INCH = 914400
+DRAWING_NS = "{http://schemas.openxmlformats.org/drawingml/2006/main}"
+
+
+def _inches(value: int) -> float:
+    return round(int(value or 0) / EMU_PER_INCH, 4)
+```
+
+## Style master: compact design context
+
+**Goal:** summarize a reference deck into a compact "style master" (colors,
+fonts, font sizes, shape styles, layout/region usage) suitable for prompting a
+generator. Counters drive a `most_common` ranking; results are truncated by
+`max_items`.
+
+### Approach
+
+1. Open with `Presentation(path)`; read slide size in inches.
+2. Pull theme tokens (colors/fonts) directly from `ppt/theme/theme1.xml` via `zipfile`.
+3. Walk each slide's shapes (recursing into groups), tallying tokens into `Counter`s.
+4. Emit `styles`, `brands`, `template`, and `layout` sections from the top-N tallies.
+
+### Illustrative snippet
+
+```python
+from collections import Counter
+
+def analyze(presentation) -> dict:
+    colors: Counter[str] = Counter()
+    fonts: Counter[str] = Counter()
+    for slide in presentation.slides:
+        for shape in _iter_shapes(slide.shapes):
+            colors.update(_shape_colors(shape).values())
+            fonts.update(_text_styles(shape)["fonts"])
+    return {
+        "colors": [{"value": v, "count": c} for v, c in colors.most_common(10)],
+        "fonts": [{"value": v, "count": c} for v, c in fonts.most_common(10)],
+    }
+```
+
+### Key helper patterns
+
+- **Recursive shape walk** — yield each shape, then recurse when it exposes `.shapes`:
+
+  ```python
+  def _iter_shapes(shapes):
+      for shape in shapes:
+          yield shape
+          if hasattr(shape, "shapes"):
+              yield from _iter_shapes(shape.shapes)
+  ```
+
+- **Color normalization** — read `color.rgb`, fall back to `theme_color`, and
+  normalize to `#RRGGBB` or `theme:<token>`.
+- **Region/flow classification** — bucket each shape's bbox center into
+  `top/middle/bottom` × `left/center/right`, and infer `row` / `column` / `grid`
+  from the spread of centers.
+- **Neutral filtering** — treat colors with low channel spread (`max-min <= 18`)
+  as neutrals so brand accents rank above grays.
+
+## Extractor: structured deck capture
+
+**Goal:** turn a deck into a structured tree of slides → groups → objects, with
+optional media extraction and a parallel list of raw OOXML render elements.
+
+### Approach
+
+1. For each slide, build a root group bbox covering the full slide.
+2. Walk shapes recursively; groups become nested groups, leaf shapes become objects.
+3. Classify each object by `kind` (`text`, `table`, `image`, `chart`, `connector`, …)
+   and capture kind-specific `content` plus `style`.
+4. Optionally write media to an asset dir, or base64-embed when no dir is given.
+5. Read speaker notes by resolving slide `_rels` to their `notesSlide` parts.
+
+### Illustrative snippet
+
+```python
+def _bbox(shape) -> dict:
+    return {
+        "x": _inches(getattr(shape, "left", 0)),
+        "y": _inches(getattr(shape, "top", 0)),
+        "width": _inches(getattr(shape, "width", 0)),
+        "height": _inches(getattr(shape, "height", 0)),
+    }
+
+def _kind(shape, shape_type: str) -> str:
+    if getattr(shape, "has_table", False):
+        return "table"
+    if getattr(shape, "has_chart", False):
+        return "chart"
+    if "picture" in shape_type or getattr(shape, "image", None):
+        return "image"
+    if getattr(shape, "has_text_frame", False) and shape.text.strip():
+        return "text"
+    return "shape"
+```
+
+### Kind-specific content notes
+
+- **text** — capture `text` plus rich paragraphs (runs with font size, bold,
+  italic, color, hyperlink, paragraph alignment/level).
+- **table** — emit `rows`, plus row/col counts, widths/heights, banding flags,
+  and merged-cell origins (`span_rows` / `span_cols`).
+- **image** — record alt text, crop fractions, and either a written asset path
+  or base64 blob; flag `missing_embedded_image` when the blob is absent.
+- **chart** — record `chart_type`, optional title, categories, and series values.
+- **line / connector** — derive endpoints from the bbox plus flip flags, and read
+  arrow head/tail types from the `<a:ln>` element.
+
+### Media & notes helpers
+
+- **Embedded relationship ids** — iterate the shape element and collect attributes
+  ending in `}embed`, then resolve via `shape.part.related_part(rid)`.
+- **Package media counts** — open the `.pptx` with `zipfile` and count names under
+  `ppt/media/` and `ppt/embeddings/`.
+- **Notes** — parse each `ppt/slides/_rels/slideN.xml.rels`, follow the
+  `notesSlide` relationship, and join `<a:t>` text nodes.
+
+## Safe attribute access
+
+`python-pptx` raises on many optional properties (fills, colors, line styles).
+Wrap reads in a small guard so extraction degrades gracefully:
+
+```python
+def _safe_attr(value, name):
+    if value is None:
+        return None
+    try:
+        return getattr(value, name)
+    except (AttributeError, TypeError, ValueError):
+        return None
+```
+
+Apply the same defensive pattern around `fill.type`, `line.width`, `color.rgb`,
+`shape.image`, and chart/table accessors, since any of them can fail on real-world decks.
@@ -0,0 +1,91 @@
+# PPTX Reference Deck Analysis Recipes
+
+This file is static guidance for inspecting existing `.pptx` files and defining expected analysis outputs.
+
+## Scope
+
+- Keep only static guidance for reference-deck prompt context, extraction, folder analysis, and style-master inspection.
+- Do not place runtime scripts, model assets, importable Python modules, or generated artifacts here.
+- This skill ships no importable code; implement the extraction/style-analysis contract on demand with `python-pptx`.
+- `python-snippets.md` holds documentation-only `python-pptx` guidance — approach notes plus short illustrative snippets. Do not import from it or recreate packaged `.py` resources from it.
+
+## Analysis Recipes
+
+### 1. Prompt Context Recipe
+
+Build compact LLM-ready context from a reference deck.
+
+Expected result:
+
+- `slide_count`, `slide_size`
+- `styles`, `brands`, `template`, `layout`
+- Per-slide title/text snippets and shape counts
+
+### 2. Full Extraction Recipe
+
+Produce a full JSON extraction including:
+
+- `summary` complexity metrics
+- `slides[*].layout_tree` with groups/objects
+- `ooxml_elements` for render-aware inspection
+
+### 3. Folder Batch Recipe
+
+Process a folder of decks to produce:
+
+- One `.pptx-spec.json` file per deck
+- A `manifest.json` to track outputs
+
+### 4. Style Master Recipe
+
+Run style-only analysis when you need design lock signals:
+
+- Palette and accent colors
+- Typography and font-size distribution
+- Master/layout usage and flow patterns
+
+### 5. Reference Template Catalog Recipe
+
+When a reference deck should inform a new deck's layout rhythm, produce a
+human-readable catalog from the existing prompt-context, extraction, and
+style-master outputs. This is a view over the same analysis, not a separate
+extraction workflow.
+
+- List every source slide by **zero-based** index.
+- Record `layout_role`, a short visual description, usable regions,
+	placeholder roles, visual structures, and content-fit constraints.
+- Use the catalog to select layout inspiration for the new outline. Re-author
+	every target slide with an independent coordinate-explicit `layout_tree`.
+- Do not clone, rearrange, replace text in, or otherwise mutate the source deck.
+- Do not inherit source content, fonts, images, or proprietary assets without
+	explicit permission and licensing evidence.
+
+Suggested catalog shape:
+
+```json
+{
+	"source_deck": "reference.pptx",
+	"slide_count": 12,
+	"slides": [
+		{
+			"source_index": 0,
+			"layout_role": "cover",
+			"description": "Dark cover with title and subtitle regions",
+			"regions": ["title", "subtitle", "supporting visual"],
+			"placeholder_roles": ["ctrTitle", "subTitle"],
+			"visual_structures": ["full-bleed color field", "corner motif"],
+			"reuse_constraints": ["best for one title and one short subtitle"]
+		}
+	]
+}
+```
+
+## Related Responsibilities
+
+This reference covers PPTX prompt context, extraction, folder batch analysis,
+style-master inspection, and the derived reference-template catalog only.
+
+- Use the parent `pptx-deck-creation` workflow for narrative/source preparation,
+  together with [design profiles](design-profiles.md) for profile selection.
+- Use [visual asset guidelines](visual-asset-adapters.md) for acquiring and
+  placing icons, images, SVGs, and infographics.
@@ -0,0 +1,158 @@
+# Visual Asset Guidelines
+
+This skill cannot bundle helper scripts, so these guidelines show how to **perform each visual-asset
+ability inline** using public APIs and short, self-contained snippets you run at request time
+(scratch cell or terminal).
+
+How to use a guideline:
+
+1. Pick the ability you need below.
+2. Run the inline snippet (adjust inputs) in an ephemeral scratch file or terminal — do not save it
+   into the skill, since the skill keeps only `references/`.
+3. Place the returned local asset path into `layout_tree.objects` with `content.path`, `content.alt`,
+   `bbox`, `z_index`, and `classification`.
+
+Shared rules:
+
+- Always return a **local file path** for any placed asset, plus `content.alt`.
+- Record provenance (`source`, `license`, `provider`, `model`) for audits.
+- On failure, write a failure manifest; never substitute a placeholder and call it generated.
+- Never request secrets in chat or a prompt dialog. For cloud auth use `.env` or `az login`.
+- Before a billable generation call or any request that sends user-provided or
+  source material to a third party, disclose the provider/model, the material
+  that will leave the machine, likely cost, and output path. Obtain explicit
+  confirmation unless the user already authorized that exact operation.
+
+---
+
+## 1. Icon Search
+
+Use the public Iconify API — no key required.
+
+- Search: `https://api.iconify.design/search?query=<q>&limit=<n>`
+- Download SVG: `https://api.iconify.design/<prefix>/<name>.svg?color=%23<hex>`
+
+```python
+import json, urllib.parse, urllib.request
+from pathlib import Path
+
+def icon_search(query, limit=8, prefix=None, color=None, out_dir="assets/icons"):
+    q = urllib.parse.quote(query)
+    url = f"https://api.iconify.design/search?query={q}&limit={limit}"
+    if prefix:
+        url += f"&prefix={urllib.parse.quote(prefix)}"
+    data = json.load(urllib.request.urlopen(url, timeout=15))
+    Path(out_dir).mkdir(parents=True, exist_ok=True)
+    results = []
+    for icon_id in data.get("icons", []):
+        pfx, name = icon_id.split(":", 1)
+        svg_url = f"https://api.iconify.design/{pfx}/{name}.svg"
+        if color:
+            svg_url += f"?color=%23{color}"
+        svg_path = Path(out_dir) / f"{pfx}_{name}.svg"
+        svg_path.write_bytes(urllib.request.urlopen(svg_url, timeout=15).read())
+        results.append({"id": icon_id, "svg_path": str(svg_path), "license": "per-set (see iconify.design)"})
+    return {"query": query, "results": results}
+```
+
+- Prefer simple, single-color icons matching the theme accent.
+- Use icons as supporting cues, not replacements for required text.
+
+---
+
+## 2. Web Image Search
+
+Prefer the browsing or image-search capability available in the current client.
+When you already have a direct image URL (from search results or the user), download it locally:
+
+```python
+import urllib.request
+from pathlib import Path
+
+def download_image(url, out_path="assets/images/img1.jpg"):
+    Path(out_path).parent.mkdir(parents=True, exist_ok=True)
+    req = urllib.request.Request(url, headers={"User-Agent": "pptx-builder/1.0"})
+    Path(out_path).write_bytes(urllib.request.urlopen(req, timeout=20).read())
+    return {"url": url, "local_path": out_path}
+```
+
+- Capture `source` and `license` for attribution; verify usage rights before placing.
+- Reference the saved file via `content.path`; do not hotlink remote URLs into the deck.
+- Do not use image placeholders as fallback assets; select an approved asset or omit the object.
+
+---
+
+## 3. Vector Asset Decision
+
+Use a true SVG only when it is already a clean vector asset or when the source
+contains no essential text or data that needs editing. Do not wrap a raster in
+an SVG and treat the result as editable.
+
+- Do not trace a raster merely to satisfy an editability requirement.
+- If an illustration contains essential text, recreate the text with native
+    PowerPoint objects.
+- Keep the original raster or a non-compliant SVG only as a supporting visual or
+    hidden reference.
+
+---
+
+## 4. Text → Infographic
+
+Generate through a user-managed provider (OpenAI or Azure OpenAI). Read credentials from environment;
+never accept secrets via chat.
+
+Before running the snippet, obtain the external-call confirmation described in
+the shared rules. If `output_path` already exists, choose a new path or obtain
+separate overwrite confirmation; do not silently replace it.
+
+```python
+import base64, json, os
+from pathlib import Path
+from openai import OpenAI, AzureOpenAI  # provided by the user's environment
+
+def text_to_infographic(prompt, output_path, provider="openai",
+                        model_or_deployment="gpt-image-1", size="1024x1024"):
+    output = Path(output_path)
+    manifest_path = output.with_suffix(".manifest.json")
+    existing = [path for path in (output, manifest_path) if path.exists()]
+    if existing:
+        raise FileExistsError(f"Refusing to overwrite existing paths: {existing}")
+    manifest_path.parent.mkdir(parents=True, exist_ok=True)
+    manifest = {"provider": provider, "model_or_deployment": model_or_deployment,
+                "output_path": output_path}
+    try:
+        if provider == "azure-openai":
+            client = AzureOpenAI(
+                azure_endpoint=os.environ["AZURE_OPENAI_ENDPOINT"],
+                api_key=os.environ.get("AZURE_OPENAI_API_KEY"),
+                api_version=os.environ.get("AZURE_OPENAI_API_VERSION", "2024-02-01"),
+            )
+        else:
+            client = OpenAI(api_key=os.environ["OPENAI_API_KEY"])
+        result = client.images.generate(model=model_or_deployment, prompt=prompt, size=size)
+        output.parent.mkdir(parents=True, exist_ok=True)
+        output.write_bytes(base64.b64decode(result.data[0].b64_json))
+        manifest["status"] = "ok"
+    except Exception as exc:  # report, never fake-generate
+        manifest.update(status="error", error=str(exc))
+    manifest_path.write_text(json.dumps(manifest, indent=2))
+    return manifest
+```
+
+- Ask the user for any missing non-secret values: provider, prompt,
+  model/deployment, size, and output path.
+- Use `.env` or `az login` for auth; never ask for keys/tokens in chat or the dialog.
+- Use generated art as a supporting visual. Recreate essential text, labels,
+  metrics, and steps with native PowerPoint objects. Add a vector asset only
+  when it is a clean, editable source.
+
+---
+
+## 5. NotebookLM Infographic Bridge
+
+NotebookLM has no public generation API, so treat this as an optional, user-configured bridge.
+
+- If the user has a NotebookLM/MCP bridge tool configured, call it with `source_refs` + `prompt`,
+  then save the returned image locally and record provenance.
+- If no bridge is configured, **fall back to Text → Infographic (section 4)** or omit the asset.
+- Apply the same provenance and failure-manifest rules as the other generation guidelines.