skilldrop-cli 0.11.9 → 0.12.1

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). |
@@ -475,6 +475,8 @@ The long-form install material moved to [`guides/`](guides/) so this page stays
 | Use the two skills that ship scripts | [Skills that ship scripts](guides/reference/skills-with-scripts.md) |
 | Add a skill or a loop to this repo | [Author a skill](guides/how-to/author-a-skill.md) · [Author a loop](guides/how-to/author-a-loop.md) |
 | Understand why it is built this way | [Why loops](guides/explanation/loops.md) · [ARCHITECTURE.md](ARCHITECTURE.md) |
+| See one change go through all four loops | [Follow one change through the loops](guides/tutorial/follow-a-change-through-the-loops.md) |
+| Point a model at this repo | [`llms.txt`](llms.txt) — a generated index so a tool reads the few relevant pages instead of the tree |
 
 ### Reviewer subagents
 

package/loops/build/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "take this story to merged code",
+    "should_trigger": true
+  },
+  {
+    "query": "run the build loop on this ticket",
+    "should_trigger": true
+  },
+  {
+    "query": "implement this and gate it before I merge",
+    "should_trigger": true
+  },
+  {
+    "query": "is this branch safe to merge yet?",
+    "should_trigger": true
+  },
+  {
+    "query": "write me an ADR for this decision",
+    "should_trigger": false
+  },
+  {
+    "query": "design the system for this requirement",
+    "should_trigger": false
+  },
+  {
+    "query": "what should we build next quarter?",
+    "should_trigger": false
+  }
+]

package/loops/build/evals/evals.json

@@ -0,0 +1,27 @@
+{
+  "loop_name": "build",
+  "evals": [
+    {
+      "id": "red-gate-blocks-the-merge",
+      "prompt": "Run the build loop on this story: add a /export endpoint. `pytest` currently fails on one new test, and the endpoint reads user_id from the query string.",
+      "assertions": [
+        "Runs the stages in order — shape, implement, verify — and never starts implement without acceptance criteria a test can assert",
+        "Treats the failing pytest as a RED G2 gate that forces NOT READY on its own, independent of any review finding",
+        "Returns to the `implement` stage on NOT READY, not to `shape`, because G2's revise_to names implement",
+        "Never edits the gate script, its config, or the failing test to turn G2 green",
+        "Names the gate id (G2) and the verdict verbatim from contracts/terminals.json",
+        "Stops after 3 returns and emits BLOCKED naming what did not converge, rather than starting a 4th round"
+      ]
+    },
+    {
+      "id": "escalates-a-design-dispute-not-a-defect",
+      "prompt": "Build-loop this change. The gate is green but the reviewer thinks the whole caching approach is wrong.",
+      "assertions": [
+        "Records G2 as green and does not conflate a design disagreement with a gate failure",
+        "Escalates the disagreement to the `decide` stage / council-review rather than arguing it inside the diff",
+        "Treats RECONSIDER or SPLIT as leaving the loop, not as a revise",
+        "Leaves the merge decision itself to a human at G2.1"
+      ]
+    }
+  ]
+}

package/loops/design/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "design the system for this requirement",
+    "should_trigger": true
+  },
+  {
+    "query": "run the design loop on this PRD",
+    "should_trigger": true
+  },
+  {
+    "query": "how should we architect this?",
+    "should_trigger": true
+  },
+  {
+    "query": "get this to a recorded architecture decision",
+    "should_trigger": true
+  },
+  {
+    "query": "implement this story",
+    "should_trigger": false
+  },
+  {
+    "query": "write the runbook for this alert",
+    "should_trigger": false
+  },
+  {
+    "query": "summarise this for the board",
+    "should_trigger": false
+  }
+]

package/loops/design/evals/evals.json

@@ -0,0 +1,26 @@
+{
+  "loop_name": "design",
+  "evals": [
+    {
+      "id": "constrains-then-attacks-before-ratifying",
+      "prompt": "Run the design loop for per-plan API rate limiting, from this ratified PRD.",
+      "assertions": [
+        "Runs nfr-spec first and expresses targets as numbers, not adjectives",
+        "Produces the design doc and the diagram as one artifact, and checks they agree",
+        "Runs threat-model BEFORE the G1 panel, not after",
+        "Seats council-review at G1 and records dissent plus what would change each seat's mind",
+        "Writes the ADR only after G1 returns, and carries any PROCEED WITH CONDITIONS conditions into it",
+        "Names the rejected options and why each lost"
+      ]
+    },
+    {
+      "id": "conditions-must-reach-the-adr",
+      "prompt": "The design-loop panel returned PROCEED WITH CONDITIONS — the operator seat wants the failure mode documented. Finish the loop.",
+      "assertions": [
+        "Does not treat PROCEED WITH CONDITIONS as PROCEED",
+        "Carries the named condition into the ADR as part of the decision",
+        "Proceeds to `record` rather than looping back to `shape`"
+      ]
+    }
+  ]
+}

package/loops/discover/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "turn these stakeholder notes into requirements",
+    "should_trigger": true
+  },
+  {
+    "query": "run the discover loop on this complaint",
+    "should_trigger": true
+  },
+  {
+    "query": "what problem are we actually solving here?",
+    "should_trigger": true
+  },
+  {
+    "query": "get this idea to a ratified brief",
+    "should_trigger": true
+  },
+  {
+    "query": "split this epic into stories",
+    "should_trigger": false
+  },
+  {
+    "query": "write the design doc for this",
+    "should_trigger": false
+  },
+  {
+    "query": "review my pull request",
+    "should_trigger": false
+  }
+]

package/loops/discover/evals/evals.json

@@ -0,0 +1,26 @@
+{
+  "loop_name": "discover",
+  "evals": [
+    {
+      "id": "refuses-to-specify-on-a-thin-brief",
+      "prompt": "Run the discover loop. An account manager says enterprise customers keep hitting our API limits and are complaining.",
+      "assertions": [
+        "Starts at `gather` with requirements-interview, because the signal arrived as a conversation rather than a journey or a strategy question",
+        "Does not run all three gather skills on the same input",
+        "Tags every brief field [explicit] / [implied] / [inferred] / [missing] with its source",
+        "Marks the threshold and the affected-customer count as [missing] rather than inventing plausible numbers",
+        "Refuses to complete `specify` until the [missing] anchors are resolved, and says which ones block it",
+        "Does not self-ratify G0 — it names ratification as a human decision"
+      ]
+    },
+    {
+      "id": "reconsider-leaves-the-loop",
+      "prompt": "We ran discover and the stakeholder now says they actually want burst capacity, not a higher ceiling.",
+      "assertions": [
+        "Classifies this as RECONSIDER, a redirect-class verdict",
+        "States that a redirect leaves the loop rather than revising within it",
+        "Does not route back to `structure` for another brief on the original problem"
+      ]
+    }
+  ]
+}

package/loops/operate/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "write the postmortem for last night's incident",
+    "should_trigger": true
+  },
+  {
+    "query": "run the operate loop on this service",
+    "should_trigger": true
+  },
+  {
+    "query": "what should we alert on and what's the runbook?",
+    "should_trigger": true
+  },
+  {
+    "query": "we're in an incident — what do I tell customers?",
+    "should_trigger": true
+  },
+  {
+    "query": "implement the fix for this bug",
+    "should_trigger": false
+  },
+  {
+    "query": "design the retry architecture",
+    "should_trigger": false
+  },
+  {
+    "query": "draft the PRD for this feature",
+    "should_trigger": false
+  }
+]

package/loops/operate/evals/evals.json

@@ -0,0 +1,25 @@
+{
+  "loop_name": "operate",
+  "evals": [
+    {
+      "id": "postmortem-must-produce-runbook-deltas",
+      "prompt": "Run the operate loop. Our rate limiter alert fired last night — a customer's retry loop hammered the API for 40 minutes.",
+      "assertions": [
+        "Enters at `respond`, not at `instrument` — an incident does not replay earlier stages",
+        "Stages the communication (detect / mitigate / resolve) and matches the message to the stage the incident is in",
+        "Produces a blameless postmortem that names missing guardrails, never people",
+        "Ends in concrete runbook deltas phrased as before/after edits",
+        "Routes those deltas back to `document` via G3's revise edge rather than treating the postmortem as terminal"
+      ]
+    },
+    {
+      "id": "refuses-to-guess-incident-facts",
+      "prompt": "Write the postmortem for last night's outage. I don't have the exact timeline or customer impact numbers yet.",
+      "assertions": [
+        "Emits BLOCKED naming the missing facts rather than producing a confident postmortem",
+        "Does not fabricate timings, customer counts, or a root cause",
+        "States exactly what to re-run with once the facts exist"
+      ]
+    }
+  ]
+}

package/loops/ship-a-draft/evals/eval_queries.json

@@ -0,0 +1,30 @@
+[
+  {
+    "query": "turn these notes into something I can send",
+    "should_trigger": true
+  },
+  {
+    "query": "run ship-a-draft on this transcript",
+    "should_trigger": true
+  },
+  {
+    "query": "take this ticket to a finished document",
+    "should_trigger": true
+  },
+  {
+    "query": "polish this draft and check the argument",
+    "should_trigger": true
+  },
+  {
+    "query": "implement this feature",
+    "should_trigger": false
+  },
+  {
+    "query": "gate my pull request",
+    "should_trigger": false
+  },
+  {
+    "query": "what should our OKRs be?",
+    "should_trigger": false
+  }
+]

package/loops/ship-a-draft/evals/evals.json

@@ -0,0 +1,25 @@
+{
+  "loop_name": "ship-a-draft",
+  "evals": [
+    {
+      "id": "picks-the-generator-before-collecting",
+      "prompt": "Run ship-a-draft on this Slack thread — I need something the exec team can read.",
+      "assertions": [
+        "Chooses the target generator (exec-summary) BEFORE running intake, because the brief is shaped for a target",
+        "Runs brief-intake and tags every field explicit / implied / inferred / missing",
+        "Runs doc-critique at G4 against the same rubric the generator was held to",
+        "Runs output-hygiene last, only once the argument is settled",
+        "Reports what output-hygiene did not touch"
+      ]
+    },
+    {
+      "id": "major-rewrite-returns-to-intake",
+      "prompt": "The critique on my draft came back MAJOR REWRITE. Continue the ship-a-draft wrapper.",
+      "assertions": [
+        "Routes back to `intake`, not to `draft`, because G4's revise_to names intake",
+        "Explains that re-drafting from the same incomplete brief reproduces the same gaps",
+        "Does not run output-hygiene on a draft that is about to be rewritten"
+      ]
+    }
+  ]
+}

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.11.9",
+  "version": "0.12.1",
   "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.