skilldrop-cli 0.12.0 → 0.12.2

package/README.md

@@ -314,7 +314,7 @@ Designing the agentic systems themselves — the loops, orchestrations, and budg
 |---|---|
 | [`audience-profile`](skills/audience-profile/SKILL.md) | Translate an audience type (exec, board, technical, sales, investor, internal, partner, customer) into structural rules — slide count, density, tone, must-have sections. Reusable input for the next three skills. |
 | [`slide-outliner`](skills/slide-outliner/SKILL.md) | Outline an architecture-review or pitch deck — slide titles, key points, and speaker notes — sized to a target time budget. Doesn't generate PPTX. |
-| [`deck-builder`](skills/deck-builder/SKILL.md) | Generate a real PowerPoint (`.pptx`) file from content + audience + color palette. Uses `python-pptx`; supports 7 layout types and audience-tuned density. Pairs naturally with `audience-profile` + `slide-outliner`. |
+| [`deck-builder`](skills/deck-builder/SKILL.md) | Generate a real PowerPoint (`.pptx`) file from content + audience + a brand `.potx`/`.pptx` template or colour palette. Uses `python-pptx`; 10 layouts including charts, tables and images, audience-tuned density. Pairs naturally with `audience-profile` + `slide-outliner`. |
 | [`exec-summary`](skills/exec-summary/SKILL.md) | Compress a long technical document into a one-page executive summary structured around an Ask, business impact, cost/timeline, risks, and what you need from the audience. |
 | [`decision-log`](skills/decision-log/SKILL.md) | Extract decisions, action items, owners, and due dates from meeting notes, Slack threads, or transcripts into a structured log with source attribution. |
 | [`incident-comms`](skills/incident-comms/SKILL.md) | Draft the messages you send *while an incident is still burning* — audience-segmented into customer status-page posts, internal stakeholder updates that arm the relayer, and three-sentence exec briefs (business impact + the ask). Every message leads with reader-facing impact (not internal symptom), uses the precise status vocabulary (investigating / identified / monitoring / resolved), commits only to the **next-update time** (never a fix ETA or speculative cause you'd have to retract), and stays blameless and screenshot-safe. Acknowledge → update-on-committed-cadence → verified resolve. Completes the operate triad with `runbook-generator` (how to fix) and `postmortem-generator` (what to say after). |

package/bin/skilldrop.js

@@ -55,6 +55,8 @@ Usage:
   skilldrop scan [<skill...>] [--from <src>]  supply-chain scan — flag network/exec/credential
                                           patterns in scripts and injection-shaped instructions
                                           in SKILL.md before you trust a catalog (RFC-0022)
+  skilldrop bootstrap                     add the skilldrop marketplace to ~/.claude/settings.json
+                                          (idempotent — safe to run in onboarding scripts)
 
 Catalogs:
   (default)          the catalog bundled with this package
@@ -1153,9 +1155,44 @@ function validateCmd(args) {
   console.log(`OK: ${names.length} skills in catalog '${cat.source}' pass the structural check.`);
 }
 
+/* ---------- bootstrap (enterprise distribution) ----------
+   Writes the skilldrop marketplace into ~/.claude/settings.json so every Claude Code
+   session on this machine discovers the catalogue without any per-session /plugin command.
+   Idempotent: safe to run in a provisioning script or onboarding runbook. */
+const BOOTSTRAP_MARKETPLACE_KEY = "skilldrop";
+const BOOTSTRAP_GITHUB_OWNER = "sananthanarayan";
+const BOOTSTRAP_GITHUB_REPO = "skilldrop";
+
+function bootstrap() {
+  const settingsPath = path.join(os.homedir(), ".claude", "settings.json");
+  let data = {};
+  const raw = readIfPresent(settingsPath, null);
+  if (raw !== null) {
+    try { data = JSON.parse(raw); }
+    catch (e) { die(`${settingsPath} is not valid JSON — fix it first, then re-run bootstrap`); }
+  }
+  data.extraKnownMarketplaces = data.extraKnownMarketplaces || {};
+  const entry = { source: { source: "github", owner: BOOTSTRAP_GITHUB_OWNER, repo: BOOTSTRAP_GITHUB_REPO } };
+  const existing = data.extraKnownMarketplaces[BOOTSTRAP_MARKETPLACE_KEY];
+  if (existing && JSON.stringify(existing) === JSON.stringify(entry)) {
+    console.log(`already configured: ${BOOTSTRAP_MARKETPLACE_KEY} -> github:${BOOTSTRAP_GITHUB_OWNER}/${BOOTSTRAP_GITHUB_REPO}`);
+    console.log(`\nIn any Claude Code session:\n  /plugin install <pack>@${BOOTSTRAP_MARKETPLACE_KEY}`);
+    return;
+  }
+  data.extraKnownMarketplaces[BOOTSTRAP_MARKETPLACE_KEY] = entry;
+  fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+  fs.writeFileSync(settingsPath, JSON.stringify(data, null, 2) + "\n");
+  console.log(`configured ${settingsPath}:`);
+  console.log(`  extraKnownMarketplaces.${BOOTSTRAP_MARKETPLACE_KEY} -> github:${BOOTSTRAP_GITHUB_OWNER}/${BOOTSTRAP_GITHUB_REPO}`);
+  console.log(`\nIn any Claude Code session, install a role pack:\n  /plugin install solution-architect@${BOOTSTRAP_MARKETPLACE_KEY}`);
+  console.log(`  /plugin install dev-team@${BOOTSTRAP_MARKETPLACE_KEY}`);
+  console.log(`  /plugin install ai-engineering@${BOOTSTRAP_MARKETPLACE_KEY}`);
+  console.log(`\nOr install the full catalogue:\n  /plugin install ${BOOTSTRAP_MARKETPLACE_KEY}@${BOOTSTRAP_MARKETPLACE_KEY}`);
+}
+
 const args = parseArgs(process.argv.slice(2));
 const cmd = args._.shift();
-const commands = { list, info, packs: listPacks, agents: listAgents, loops: listLoops, install, update, outdated, uninstall, validate: validateCmd, scan };
+const commands = { list, info, packs: listPacks, agents: listAgents, loops: listLoops, install, update, outdated, uninstall, validate: validateCmd, scan, bootstrap };
 if (!cmd || cmd === "help" || args.flags.help) console.log(HELP);
 else if (commands[cmd]) commands[cmd](args);
 else die(`unknown command '${cmd}' — run: skilldrop help`);

package/model-routing.json

@@ -104,7 +104,7 @@
     "adr-generator": { "tier": "standard", "rationale": "Structures a decision into MADR/Nygard. Some judgment on title/consequences; not adversarial." },
     "architecture-diagrams": { "tier": "standard", "rationale": "Translates prose to diagram syntax. Correctness matters; reasoning is bounded." },
     "brief-intake": { "tier": "standard", "rationale": "Extraction + tagging [explicit]/[implied]/[inferred]. The tagging needs care — above light, below heavy." },
-    "deck-builder": { "tier": "standard", "rationale": "Generates pptx content + runs a script. Content shaping, not hard reasoning." },
+    "deck-builder": { "tier": "standard", "rationale": "Shapes content, maps a brand template's layouts, and runs a script. Judgment, not hard reasoning." },
     "design-doc": { "tier": "standard", "rationale": "Synthesizes a design doc from a brief. Escalate to heavy via large-input or ambiguous-input when alternatives are genuinely contested." },
     "exec-summary": { "tier": "standard", "rationale": "Compression to one page. Needs to keep the right signal; escalate on very long source docs." },
     "figma-diagrams": { "tier": "standard", "rationale": "API calls + spec generation. Bounded transformation." },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skilldrop-cli",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "description": "Portable AI-agent skills for the deliverables knowledge workers ship \u2014 diagrams, ADRs, PRDs, runbooks, decks, reviews \u2014 installable into Claude Code, Cursor, Kiro, and any IDE that takes custom instructions. One command per skill or per role-based pack.",
   "author": {
     "name": "Sanjay Ananthanarayan",

package/skills/deck-builder/SKILL.md

@@ -1,114 +1,181 @@
 ---
 name: deck-builder
-description: Generate a real PowerPoint (.pptx) file from content, target audience, and a color palette. Produces structurally-appropriate decks (slide count, density, layout choice) tuned for the audience — execs, technical reviewers, sales prospects, investors, internal teams. Use when the user wants an actual editable .pptx, not just an outline.
+description: Generate a real PowerPoint (.pptx) file from content, audience, and either a brand template or a color palette — with charts, tables and images, not only bullets. Slide count, density and layout are tuned to the audience: execs, boards, technical reviewers, sales prospects, investors, internal teams. Use when the user wants an actual editable .pptx rather than an outline, wants their corporate template or brand colours applied, or says "build the deck", "make it a pptx", "use our template".
 ---
 
 # deck-builder
 
-You help the user produce an **actual editable `.pptx` file**, not just an outline. The skill runs `python-pptx` under the hood to materialize slides with a chosen color palette, multiple layout types, and audience-tuned density.
+This skill produces an **actual editable `.pptx` file**, not an outline. It runs `python-pptx`
+to materialise slides — either on a brand template's own masters and layouts, or on the skill's
+built-in design driven by a colour palette.
 
-This skill pairs with two others:
-- **[`audience-profile`](../audience-profile/SKILL.md)** — decides how dense / how many / which sections the deck should have
-- **[`slide-outliner`](../slide-outliner/SKILL.md)** — drafts the per-slide content before this skill turns it into a `.pptx`
+It pairs with two others:
+- **[`audience-profile`](../audience-profile/SKILL.md)** — decides how dense, how many, which sections
+- **[`slide-outliner`](../slide-outliner/SKILL.md)** — drafts per-slide content before this skill builds it
 
-For a single fast pipeline, use all three in order: profile → outline → build.
+For a single fast pipeline, run all three in order: profile → outline → build.
 
 ## How to respond
 
-1. **Gather three inputs** before generating anything:
-
-   - **Content.** Either a finished outline (from `slide-outliner`), a long doc the user wants compressed into slides, or a list of points. If the content is thin ("here's the topic, you fill in"), pause and ask — *making slides up is the easiest way to make a bad deck*.
-   - **Audience.** One of: `exec`, `board`, `technical`, `sales`, `internal`, `investor`, `partner`, `customer`. If the user gives a free-form description ("VP of Eng + their staff at a partner"), map to the closest archetype and call out your choice. Use [`audience-profile`](../audience-profile/SKILL.md) for the structural rules.
-   - **Palette.** Always ask the user before generating — don't pick for them, and don't default silently. Present the choice like this:
-
-     > Pick a palette before I generate the deck:
-     > - `corporate-blue` — default for B2B / enterprise audiences
-     > - `monochrome` — restrained / when content is sensitive
-     > - `vibrant` — internal / sales / pitch decks
-     > - `dark-mode` — engineering audiences, live demos
-     > - `editorial` — long-form / read-ahead decks
-     > - `forest` — calm, nature-leaning
-     > - `sunset` — warm, narrative-leaning
-     > - Or give me hex values for `primary` / `secondary` / `accent` / `background` / `text`
-     > - Or paste your brand colors and I'll map them into the five roles
-
-     If the user gives brand colors as a partial set (e.g. just a primary), derive the missing roles using the rules in [`reference.md`](reference.md#color-palette-principles) and call out what you filled in.
-
-2. **Plan the slide list against the audience archetype.** For example:
-
-   | Audience | Slide count | Density | Required sections |
-   |---|---|---|---|
-   | `exec` | 6–10 | Low — 3 bullets max | Ask • TL;DR • Business impact • Risks • Ask (closing) |
-   | `board` | 8–12 | Low — big numbers | Cover • TL;DR • Strategic context • Financials • Risks • Ask |
-   | `technical` | 12–20 | High — detail welcome | Context • Goals • Proposal (3–5) • Alternatives • Risks • Rollout |
-   | `sales` | 8–12 | Story arc, visual | Hook • Pain • Solution • Proof • Pricing • Close |
-   | `internal` | 5–10 | Mixed | Context • Proposal • Discussion topics • Action items |
-   | `investor` | 10–15 | Polished, narrative | Problem • Market • Product • Traction • Team • Ask |
-
-   The full archetype spec is in [`audience-profile`](../audience-profile/SKILL.md).
-
-3. **Build a deck spec.** The spec is a JSON document with this shape — full schema in [`templates/deck-spec.json`](templates/deck-spec.json):
-
-   ```json
-   {
-     "title": "ProjectX Migration — Board Update",
-     "audience": "board",
-     "palette": { "primary": "#1A2A6C", "accent": "#FDBB2D", ... },
-     "slides": [
-       { "layout": "title", "title": "...", "subtitle": "..." },
-       { "layout": "section", "title": "..." },
-       { "layout": "content", "title": "...", "bullets": ["..."] },
-       { "layout": "big_number", "title": "...", "number": "$24M", "caption": "ARR at risk" },
-       { "layout": "two_column", "title": "...", "left": {...}, "right": {...} },
-       { "layout": "quote", "quote": "...", "attribution": "..." },
-       { "layout": "closing", "title": "Approval requested", "subtitle": "..." }
-     ]
-   }
-   ```
-
-   Available layouts: `title`, `section`, `content`, `two_column`, `big_number`, `quote`, `closing`. Most slides should be `content`; sprinkle in `big_number` and `quote` for emphasis.
-
-4. **Run the build script** to produce the actual `.pptx`:
-
-   ```bash
-   # Claude Code
-   python3 "${CLAUDE_SKILL_DIR}/scripts/build_deck.py" /tmp/deck-spec.json -o ./out/deck.pptx
-
-   # Other IDEs (from the skill folder)
-   cd path/to/deck-builder && python3 scripts/build_deck.py /tmp/deck-spec.json -o ./out/deck.pptx
-   ```
-
-   The script writes a real `.pptx` the user can open in PowerPoint, Keynote, or Google Slides and edit further. Tell the user where the file landed and what to do next.
-
-5. **Recommend post-generation refinement.** A generated deck is a strong first draft, not a finished artifact. Always suggest:
-
-   - Reviewing speaker notes (they were written by the agent — verify before presenting)
-   - Replacing any placeholder images with real visuals
-   - Doing one "audience pass" — read every slide title in order, does the *narrative* make sense to that specific audience?
+### 1. Run the setup block — once
+
+Ask everything in **one** message, with defaults already chosen, so the user can answer with a
+single line or say "go". Never trickle out four separate questions, and never generate a deck
+with the design silently defaulted.
+
+> Before I build, confirm these — reply "go" to take the defaults:
+> 1. **Audience** — `exec` · `board` · `technical` · `sales` · `internal` · `investor` · `partner` · `customer`
+> 2. **Format** — live presentation / read-ahead / async share, **how many minutes**, and **16:9** (default) or **4:3**
+> 3. **Design** — either
+>    - a **template**: path to a corporate `.pptx` / `.potx`, and the deck inherits its masters, fonts, colours and slide size; or
+>    - a **palette**: `corporate-blue` (default for B2B) · `monochrome` · `vibrant` · `dark-mode` · `editorial` · `forest` · `sunset`, or brand hex values for `primary` / `secondary` / `accent` / `background` / `text`
+> 4. **Anything to embed** — numbers to chart, a table, diagram PNGs
+
+Rules for reading the answers:
+
+- **Content is the one hard input.** If the user supplied only a topic, stop and ask for the
+  material. Inventing the content is the easiest way to produce a bad deck.
+- **A free-form audience maps to the closest archetype** — "VP of Eng and their staff at a
+  partner" → `technical`, stated out loud. Mixed audience → the least technical archetype, with
+  the rest served by appendix slides.
+- **Time sets slide count**, not the other way round: 1.5–2 minutes per slide live. 30 minutes →
+  12–15 slides including cover and close.
+- **A partial brand palette gets completed**, using the rules in
+  [`reference.md`](reference.md#color-palette-principles) — say which roles were filled in.
+- **Template beats palette** for chrome; the palette still colours charts, tables, big numbers
+  and quote bars, so ask for brand hexes even when a template is supplied.
+
+**Non-interactive runs** (subagent, CI, headless): audience, format, time and palette degrade to
+`[assumption]` lines stated at the top of the response — default `exec`, live, 16:9,
+`corporate-blue`. Missing *content* does not degrade: emit `BLOCKED: need deck content
+(outline, doc, or point list)` and build nothing.
+
+### 2. Plan the slide list against the audience archetype
+
+| Audience | Slide count | Density | Required sections |
+|---|---|---|---|
+| `exec` | 6–10 | Low — 3 bullets max | Ask • TL;DR • Business impact • Risks • Ask (closing) |
+| `board` | 8–12 | Low — big numbers | Cover • TL;DR • Strategic context • Financials • Risks • Ask |
+| `technical` | 12–20 | High — detail welcome | Context • Goals • Proposal (3–5) • Alternatives • Risks • Rollout |
+| `sales` | 8–12 | Story arc, visual | Hook • Pain • Solution • Proof • Pricing • Close |
+| `internal` | 5–10 | Mixed | Context • Proposal • Discussion topics • Action items |
+| `investor` | 10–15 | Polished, narrative | Problem • Market • Product • Traction • Team • Ask |
+
+Full archetype spec: [`audience-profile`](../audience-profile/SKILL.md). Slide-count budgets per
+format and time: [`reference.md`](reference.md#slide-count-budgets).
+
+### 3. Build a deck spec
+
+A JSON document — full schema, with every layout and the template block, in
+[`templates/deck-spec.json`](templates/deck-spec.json):
+
+```json
+{
+  "title": "ProjectX Migration — Board Update",
+  "audience": "board",
+  "aspect": "16:9",
+  "template": "./brand/acme-master.potx",
+  "layout_map": { "title": "Title Slide", "content": "Title and Content" },
+  "palette": { "primary": "#1A2A6C", "accent": "#FDBB2D" },
+  "slides": [
+    { "layout": "title", "title": "...", "subtitle": "...", "presenter": "...", "date": "..." },
+    { "layout": "content", "title": "...", "bullets": ["..."], "notes": "..." },
+    { "layout": "chart", "title": "...", "takeaway": "...", "chart": { "type": "column", "categories": ["..."], "series": [{ "name": "...", "values": [1, 2] }] }, "source": "..." },
+    { "layout": "table", "title": "...", "columns": ["..."], "rows": [["..."]] },
+    { "layout": "image", "title": "...", "image": "./diagram.png", "position": "right", "bullets": ["..."] },
+    { "layout": "big_number", "title": "...", "number": "$24M", "caption": "ARR at risk" },
+    { "layout": "closing", "title": "Approval requested", "subtitle": "..." }
+  ]
+}
+```
+
+Ten layouts: `title`, `section`, `content`, `two_column`, `big_number`, `quote`, `image`,
+`table`, `chart`, `closing`. Most slides are `content`; `chart`, `table` and `big_number` carry
+the evidence; `quote` and `image` break the rhythm. Which content shape earns which layout:
+[`reference.md`](reference.md#layout--content-matching).
+
+Every slide gets a `notes` field. Slide numbers appear automatically past 10 slides — override
+with `"slide_numbers": false`.
+
+### 4. Build from the user's template when there is one
+
+A corporate template is the difference between a deck that gets presented and one that gets
+rebuilt by hand. When the user names one:
+
+```bash
+# Claude Code — list the template's layouts first
+python3 "${CLAUDE_SKILL_DIR}/scripts/build_deck.py" --list-layouts ~/brand/acme-master.potx
+
+# Other IDEs (from the skill folder)
+python3 scripts/build_deck.py --list-layouts ~/brand/acme-master.potx
+```
+
+Map each logical layout to one of the printed names in `layout_map`, then build. The template's
+masters, theme fonts, colours, logos and slide size are inherited; any sample slides it ships
+with are dropped. A logical layout left out of the map falls back to the skill's built-in
+design on the template's blank layout — acceptable for `big_number` or `quote`, wrong for
+`title` and `content`, which is where the branding shows.
+
+`.potx` and `.pptx` both work. Templates carry no charts or tables of their own, so those are
+drawn into whatever content region the mapped layout defines.
+
+### 5. Run the build script
+
+```bash
+# Claude Code
+python3 "${CLAUDE_SKILL_DIR}/scripts/build_deck.py" /tmp/deck-spec.json -o ./out/deck.pptx
+
+# Other IDEs (from the skill folder)
+cd path/to/deck-builder && python3 scripts/build_deck.py /tmp/deck-spec.json -o ./out/deck.pptx
+```
+
+Add `--strict` to fail the build on a missing or unreadable image instead of drawing a
+placeholder box — use it in CI, not in a conversation.
+
+**Read the warnings.** The script degrades rather than crashing: a missing image, a short data
+series, an unresolvable template layout each produce a warning and a visible fallback. Report
+every warning to the user with the file path; never present a deck with an unexplained
+placeholder box in it.
+
+### 6. Recommend the refinement pass
+
+A generated deck is a strong first draft. Always tell the user to:
+
+- Review the speaker notes — the agent wrote them, and they get read aloud
+- Replace any placeholder box with the real diagram
+- Do one audience pass: read every slide title in order, does the *narrative* land for that audience?
+- Run [`doc-critique`](../doc-critique/SKILL.md) against the deck rubric before it goes out
 
 ## Useful references
 
-- [`reference.md`](reference.md) — Color palette principles + layout-vs-content matching guide
-- [`templates/deck-spec.json`](templates/deck-spec.json) — Full JSON schema with every layout demonstrated
-- [`templates/palettes.json`](templates/palettes.json) — Pre-built color palettes (corporate-blue, monochrome, vibrant, dark-mode, editorial, forest, sunset)
-- [`examples/exec-board-update.md`](examples/exec-board-update.md) — Worked example: brief → spec → resulting deck
-- [`scripts/build_deck.py`](scripts/build_deck.py) — The generator (don't edit unless extending layouts)
+- [`reference.md`](reference.md) — palette principles, layout-vs-content matching, chart and table rules, density and slide-count budgets
+- [`templates/deck-spec.json`](templates/deck-spec.json) — full JSON schema with every layout and the template block
+- [`templates/palettes.json`](templates/palettes.json) — the seven presets
+- [`examples/exec-board-update.md`](examples/exec-board-update.md) — worked example: brief → spec → deck
+- [`examples/templated-brand-deck.md`](examples/templated-brand-deck.md) — worked example: corporate `.potx` → layout map → deck
+- [`scripts/build_deck.py`](scripts/build_deck.py) — the generator (don't edit unless adding a layout)
 
 ## Quality bar
 
-- **Title slide isn't blank** — it has a real title, subtitle, presenter, date.
+- **Design is chosen by the user, never silently defaulted** — a template path or a named palette, confirmed in the setup block.
+- **A supplied template is actually inherited** — `layout_map` covers `title`, `section`, `content` and `closing` at minimum. A branded deck rendered on the blank layout has thrown away the branding.
+- **Title slide isn't blank** — real title, subtitle, presenter, date.
+- **Numbers are charted, not bulleted** — three or more comparable figures belong in a `chart` or a `table`, not a bullet list.
+- **Every chart and table cites its `source`** and uses only figures from the user's material.
+- **Bullet density matches audience** — `exec`, *3 bullets max*, period. `technical`, up to 6 when the content needs it.
+- **Speaker notes on every slide** — even one sentence.
 - **Section dividers used sparingly** — at most one every 4–5 content slides.
-- **Big numbers are real** — never invent statistics for emphasis. If the user gave you a number, use it; otherwise pick a different layout.
-- **Bullet density matches audience** — for `exec`, *max 3 bullets per slide*, period. For `technical`, up to 6 if the content really needs it.
-- **Speaker notes for every slide** — even one sentence. They're how the presenter remembers what's *between* the bullets.
-- **Color palette is consistent** — don't mix in random colors that aren't in the palette.
-- **No surprise pages** — first and last slides match in style; the deck reads as one document.
+- **Zero unexplained warnings** — every warning the script emits is fixed or reported to the user.
+- **Colour is consistent** — palette roles only, no stray colours; text-on-background contrast ≥ 4.5:1.
 
 ## Anti-patterns to avoid
 
-- ❌ Generating a deck without confirming the audience. The same content for execs vs engineers is a different deck.
-- ❌ Writing fake numbers to fill a `big_number` slide.
-- ❌ Defaulting to bullets when a `big_number`, `quote`, or `two_column` would land harder.
-- ❌ Skipping speaker notes because the user "knows the topic" — they're for the reviewer/co-presenter too.
-- ❌ Choosing low-contrast palettes (light grey text on white). If the palette has poor contrast, swap to a sensible default and explain.
-- ❌ More than ~20 slides for any audience. If you can't make the point in 20, the deck isn't the right format.
+- ❌ Ignoring a template the user already named, or asking for a palette after they supplied one. The template is the answer to "what should this look like".
+- ❌ Mapping every logical layout onto the template's one title-and-bullets layout. That is a branded deck that still looks generated.
+- ❌ Generating without confirming audience. The same content for execs and engineers is a different deck.
+- ❌ Inventing a statistic to fill a `big_number`, or a series to fill a chart. No source, no chart.
+- ❌ A table with 20 rows. Over ~12 it is an appendix or a spreadsheet, not a slide.
+- ❌ Passing an SVG or EMF diagram to `image` — `python-pptx` reads raster only. Convert to PNG first.
+- ❌ Shipping the deck with a grey placeholder box still in it because the warning went unread.
+- ❌ Defaulting to bullets when a `big_number`, `chart`, `quote` or `two_column` would land harder.
+- ❌ More than ~20 slides for any audience. If the point needs 21, the deck is the wrong format.

package/skills/deck-builder/evals/eval_queries.json

@@ -1,34 +1,14 @@
 [
-  {
-    "query": "Build me a PowerPoint from this content",
-    "should_trigger": true
-  },
-  {
-    "query": "Generate a .pptx deck for this exec presentation",
-    "should_trigger": true
-  },
-  {
-    "query": "Turn this into actual slides I can present, with our brand colors",
-    "should_trigger": true
-  },
-  {
-    "query": "I need a real deck file, not an outline",
-    "should_trigger": true
-  },
-  {
-    "query": "Just outline the slides — I'll build the deck myself",
-    "should_trigger": false
-  },
-  {
-    "query": "Write a one-page summary for executives",
-    "should_trigger": false
-  },
-  {
-    "query": "Which audience archetype should I target and what are its rules?",
-    "should_trigger": false
-  },
-  {
-    "query": "Critique the deck I already made",
-    "should_trigger": false
-  }
+  { "query": "Build me a PowerPoint from this content", "should_trigger": true },
+  { "query": "Generate a .pptx deck for this exec presentation", "should_trigger": true },
+  { "query": "Turn this into actual slides I can present, with our brand colors", "should_trigger": true },
+  { "query": "I need a real deck file, not an outline", "should_trigger": true },
+  { "query": "Build the deck on our corporate template — marketing rejects anything else", "should_trigger": true },
+  { "query": "Use our .potx master for this QBR deck", "should_trigger": true },
+  { "query": "Put these quarterly numbers on a slide as a chart", "should_trigger": true },
+  { "query": "Just outline the slides — I'll build the deck myself", "should_trigger": false },
+  { "query": "Write a one-page summary for executives", "should_trigger": false },
+  { "query": "Which audience archetype should I target and what are its rules?", "should_trigger": false },
+  { "query": "Critique the deck I already made", "should_trigger": false },
+  { "query": "Extract the text out of this existing .pptx so I can email it", "should_trigger": false }
 ]

package/skills/deck-builder/evals/evals.json

@@ -6,12 +6,35 @@
       "prompt": "Build a .pptx from this content for an exec audience, using our brand palette (navy/white).",
       "assertions": [
         "A real .pptx file is produced, not an outline",
+        "Audience, format and design are confirmed in a single setup block rather than as a trickle of separate questions",
         "The title slide carries a real title, subtitle, presenter, and date — never left blank",
         "Section dividers appear sparingly, at most one every 4-5 content slides",
         "Big-number layouts use only numbers the user supplied; no statistic is invented for emphasis",
         "Bullet density matches the stated audience rather than a fixed default",
         "The requested palette is applied rather than the default theme"
       ]
+    },
+    {
+      "id": 2,
+      "prompt": "Build the Q3 QBR deck on our corporate template at ~/brand/acme-master.potx — 25 minutes, live, partner audience.",
+      "assertions": [
+        "The template's layouts are listed with --list-layouts before the spec is written, rather than layout names being guessed",
+        "The spec sets `template` and a `layout_map` covering at least title, section, content and closing",
+        "A palette is still collected, because the template does not colour charts, tables or big numbers",
+        "`aspect` is not fought with — the template's own slide size is accepted and stated",
+        "Slide count is derived from the 25-minute budget at roughly 2 minutes per slide"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Here are our renewal rates for the last three quarters (88%, 91%, 94%) and the SLA table from the contract. Put them in the deck.",
+      "assertions": [
+        "The three comparable figures become a `chart` slide, not a bullet list",
+        "The chart carries a `takeaway` sentence and a `source`",
+        "The SLA data becomes a `table` slide rather than aligned bullets",
+        "No figure appears that the user did not supply",
+        "Any build warning (missing image, short series) is reported to the user with its path rather than left in the file"
+      ]
     }
   ]
 }

package/skills/deck-builder/examples/templated-brand-deck.md

@@ -0,0 +1,148 @@
+# Example: Q3 partner QBR on the company's own PowerPoint template
+
+**Prompt the user gave:** *"Make the Q3 QBR deck for Northwind. Use our corporate template at
+`~/brand/acme-master.potx` — it's mandatory, marketing rejects anything else. 25 minutes, live,
+with the partner's CTO and two of their architects in the room. Renewal rate went 88 → 91 → 94%
+over the last three quarters, ticket volume is down 31%, and we want to land the co-sell
+expansion ask. Brand colours are #0B3D6B and #E8A33D."*
+
+## Step 1 — Setup block, answered in one pass
+
+| Input | Value | How it was resolved |
+|---|---|---|
+| Content | Renewal trend, ticket volume, expansion ask | Supplied |
+| Audience | `partner` | Stated ("partner's CTO and architects") |
+| Format | Live, 25 min → 12–14 slides | Stated; slide count derived at ~2 min/slide |
+| Aspect | From the template | `aspect` ignored — the `.potx` is 16:9 |
+| Design | `~/brand/acme-master.potx` + brand hexes | Template for chrome, palette for charts |
+| Embeds | Renewal trend (chart), SLA table | Three comparable figures ⇒ chart, not bullets |
+
+The palette is still collected: the template does not colour charts, tables or big numbers.
+`primary: #0B3D6B`, `accent: #E8A33D`; `secondary`, `background` and `text` derived per
+[`reference.md`](../reference.md#color-palette-principles) and called out to the user.
+
+## Step 2 — Read the template's layouts before writing the spec
+
+```bash
+python3 "${CLAUDE_SKILL_DIR}/scripts/build_deck.py" --list-layouts ~/brand/acme-master.potx
+```
+
+```
+acme-master.potx — slide size 13.33in x 7.50in
+  [0] Acme Cover
+  [1] Acme Section Break
+  [2] Acme Title and Body
+  [3] Acme Two Column
+  [4] Acme Statement
+  [5] Acme Full Bleed Image
+  [6] Blank
+```
+
+The names are the template's, not PowerPoint's defaults — which is exactly why the map is read
+from the file rather than guessed.
+
+## Step 3 — The deck spec
+
+```json
+{
+  "title": "Northwind QBR — Q3 FY26",
+  "audience": "partner",
+  "template": "~/brand/acme-master.potx",
+  "layout_map": {
+    "title": "Acme Cover",
+    "section": "Acme Section Break",
+    "content": "Acme Title and Body",
+    "two_column": "Acme Two Column",
+    "big_number": "Acme Statement",
+    "quote": "Acme Statement",
+    "chart": "Acme Statement",
+    "table": "Acme Statement",
+    "image": "Acme Full Bleed Image",
+    "closing": "Acme Statement"
+  },
+  "palette": {
+    "primary": "#0B3D6B",
+    "secondary": "#4A6E94",
+    "accent": "#E8A33D",
+    "background": "#FFFFFF",
+    "text": "#222222"
+  },
+  "slides": [
+    {
+      "layout": "title",
+      "title": "Northwind × Acme — Q3 business review",
+      "subtitle": "Renewals, service quality, and the FY27 co-sell ask",
+      "presenter": "Jane Roe, Partner Director",
+      "date": "2026-09-30",
+      "notes": "Thank them for the quarter before the first slide. Name the ask now so it isn't a surprise at slide 12."
+    },
+    {
+      "layout": "chart",
+      "title": "Renewal rate has climbed every quarter this year",
+      "takeaway": "Three consecutive quarters of improvement — the joint success plan is what changed.",
+      "chart": {
+        "type": "line",
+        "categories": ["Q1 FY26", "Q2 FY26", "Q3 FY26"],
+        "series": [{ "name": "Renewal rate (%)", "values": [88, 91, 94] }],
+        "number_format": "0\"%\""
+      },
+      "source": "Northwind CS dashboard, 30 Sep 2026",
+      "notes": "Let them claim the win — ask their CTO what drove Q2. The answer is usually the thing to double down on in FY27."
+    },
+    {
+      "layout": "big_number",
+      "title": "Support load is down as adoption is up",
+      "number": "-31%",
+      "caption": "Ticket volume vs. Q3 FY25, on 2.4× the seat count",
+      "notes": "The pairing is the point: more users, fewer tickets. Pause after saying it."
+    },
+    {
+      "layout": "table",
+      "title": "SLA performance against contract",
+      "columns": ["Metric", "Contracted", "Q3 actual", "Status"],
+      "rows": [
+        ["Availability", "99.9%", "99.97%", "Met"],
+        ["P1 response", "15 min", "9 min", "Met"],
+        ["P1 resolution", "4 hrs", "3h 10m", "Met"],
+        ["Change failure", "< 5%", "6.2%", "Missed"]
+      ],
+      "caption": "Change-failure remediation plan on the next slide.",
+      "notes": "Do not skip the missed row. Naming it before they do is what makes the other three credible."
+    },
+    {
+      "layout": "closing",
+      "title": "Ask: co-sell motion for FY27, two named accounts each",
+      "subtitle": "Kick-off 15 Oct, joint pipeline review monthly",
+      "notes": "Land on the ask. Get the kick-off date agreed in the room, not in follow-up email."
+    }
+  ]
+}
+```
+
+*(Abridged — the full deck is 13 slides; the four above are the ones that show the new layouts.)*
+
+## Step 4 — Build
+
+```bash
+python3 "${CLAUDE_SKILL_DIR}/scripts/build_deck.py" /tmp/northwind-qbr.json -o ./out/northwind-qbr.pptx
+```
+
+```
+template: dropped 2 sample slide(s), kept masters and layouts
+wrote ./out/northwind-qbr.pptx (13 slides, template)
+```
+
+No warnings, so nothing to report. Had the SLA table's diagram been an `.svg`, the build would
+have drawn a placeholder box and warned — which gets reported to the user with the path, not
+quietly shipped.
+
+## What the template bought
+
+| Without the template | With it |
+|---|---|
+| Calibri, generated-looking cover | Acme's typeface, cover, and logo on every slide |
+| Palette-coloured title bars | The master's own chrome |
+| Marketing sends it back | Passes brand review unchanged |
+
+The palette still did real work: the line chart, the `-31%`, and the table header are brand
+colours because `palette` was collected *alongside* the template, not instead of it.