/brand-pptx

name: brand-pptx
description: >-
  Brand-aware PowerPoint engine. Use to (1) EXTRACT a company's brand from a .pptx template into a
  reusable "Brand Profile", (2) COMPREHEND the template with the model (optional), (3) VERIFY it,
  (4) GENERATE a new on-brand .pptx from an IntermediateDocument. Trigger on "extract our brand",
  "use our deck template", "generate a branded deck from our profile", or when a ./brand-kit
  exists. For one-off slide edits with no saved brand profile, use the normal pptx skill instead.
  NOT for .docx (brand-docx), .xlsx (brand-xlsx), or PDFs.

brand-pptx

Use this skill when the user wants reusable branded PowerPoint generation from a company `.pptx` template and variable user-provided content.

This is an AI-agent skill for Codex and Claude Code. The user should describe the deck they want; the agent converts that request into an IntermediateDocument, uses the internal Python engine, verifies the output, and returns the generated `.pptx`.

The seven verbs: three deterministic + four model-assisted

Every brand skill (`brand-docx`, `brand-pptx`, `brand-xlsx`) implements the same contract. The deterministic core is **extract / verify / generate**; on top of it sit the optional learning verbs **comprehend / learn / propose-overrides / refine**, each fail-closed (the engine validates every proposal and authors every value).

| Verb | Input | Output | |---|---|---| | **extract** | a company `.pptx` template | a reusable Brand Profile | | **comprehend** *(optional, model-driven)* | a saved profile + a model-authored `comprehension.json` | the profile with a validated, cached `comprehension` block | | **verify** | a saved Brand Profile | QA findings + a verdict | | **generate** | content (an IntermediateDocument) + a profile | a new on-brand `.pptx` | | **learn** *(deterministic distillation)* | the profile's cross-run generation history | recurring QA findings distilled into shell-frozen overrides, advisory until `--accept` | | **propose-overrides** *(model-driven)* | the recurring remainder `learn` could not bind + a model-authored proposal | shell-backed corrections through the same fail-closed sink, advisory until `--accept` | | **refine** | end-of-generation user feedback (text or a screenshot) as a `refinement.json` delta | the existing comprehension overlaid for FUTURE generations, advisory until `--accept` |

`comprehend` is **optional**: `generate` works on the deterministic profile alone. See [reference/comprehension.md](reference/comprehension.md) for the full step.

Hard Rules

• Treat `python scripts/cli.py ...` as an internal engine command, not the user-facing workflow.
• `scripts/cli.py` is a LAUNCHER that locates the engine root by itself: it works from this skill folder AND from the repo/plugin root (set `BRAND_DOCS_ROOT` to override). Never guess deeper paths like `scripts/brandkit/...`.
• Run the dependency preflight before starting extract / comprehend / verify / generate, and report missing or unusable dependencies before proceeding.
• Extract opens the source template read-only and saves `brand-kit/<name>/template/shell.pptx` byte-for-byte.
• Generate opens the saved shell and resolves every semantic block through `profile.json`.
• Do not put style names, colors, fonts, or brand identifiers in an IntermediateDocument.
• If the user did not provide a template or enough content, ask for the missing input.
• Return the generated file path plus a QA summary.
• Consult `profile.json.artifact_catalog` before generation when the user asks to mimic a specific piece of the template.

Preflight (always first)

Before doing any work, run:

python scripts/cli.py doctor

Use its output to decide the run mode:

• If a required Python dependency is missing, install/repair it before extraction

or generation; the core engine is not ready.

• If only visual renderers are missing or unusable (`soffice` plus `pdftoppm` or

optional PyMuPDF/`fitz`), the core L0 workflow can still run, but a full visual audit cannot be claimed. Tell the user what is missing, include the install/repair hint printed by `doctor`, and either proceed with degraded QA or install the renderer first.

• If optional OCR (`tesseract`) is missing, the visual audit can still run, but

rendered residual-text proof is incomplete. Report that limitation when judging stale placeholders or field caches.

• For `--qa deep` or `--qa strict`, prefer repairing/installing renderers before

generation. If the environment cannot run them, `deep` generates a degraded manifest and `strict` fails with a visual proof blocker.

Agent Workflow

1. Run the dependency preflight above and report any degraded capability. 2. Determine the brand name and locate the user-provided `.pptx` template. 3. If no matching `brand-kit/<name>` exists, **extract** one. 4. **Comprehend** the template (optional, model-driven; see below). Skip when a current comprehension is already cached or no model is available. 5. Convert the user's outline/content into `IntermediateDocument` JSON. 6. **Generate** the `.pptx` with the internal engine. 7. Run **QA** and report any warnings honestly. 8. **Feedback** (only after returning the file): invite a refinement of the understanding for future decks (see below).

Before generation, inspect `profile.json.artifact_catalog` when the user asks to mimic a specific template piece. It records OOXML parts, media parts, slide layouts, masters, placeholder geometry, slide texts, and slide size.

Authoring the IntermediateDocument

The IDoc is where "correct deck" becomes "great deck". Author it role-first, against the profile, never layout-first:

1. **Read `brand-kit/<name>/PROFILE.md` before writing a block.** It lists the role table and the brand palette tokens. Choose every block by MEANING from that table; the engine maps it to the template's real masters and layouts. 2. **One idea per slide.** A slide carries one heading and a few su