slidemind 0.3.5 → 0.3.13

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.3.5",
+  "version": "0.3.13",
   "description": "Connect Claude Code, Codex & opencode to the slidemind PowerPoint add-in — let your coding agent build and edit native, on-brand PowerPoint decks against your active corporate design, from the terminal.",
   "type": "module",
   "bin": {

package/skills/create-slides/SKILL.md

@@ -22,6 +22,11 @@ workflow vocabulary — the harness-neutral verbs defined in the bundle's `workf
 spoken throughout `workflow/*.md` — into your `slidemind` CLI commands. Read the workflow + brand
 from the bundle; never restate or duplicate them here.
 
+Brand sample slides are private inputs to the add-in's concept generator. They are not authoring
+references and are deliberately not materialized into the local bundle. From the concept pass
+onward, re-read only `decks/<slug>/concepts/concept-slide-NN.png`; when a concept is unavailable,
+fall back to the approved storyboard plus `design.md` and the chosen layout, never to samples.
+
 **slidemind is a CLI you drive directly.** Run `slidemind <command>` in your shell — the same way
 you'd run `git` or `npm`. There is no separate tool layer to go through; every step below is a real
 command you type.
@@ -36,13 +41,43 @@ later stages (above all the review gate) from being skipped. The stages, as they
 1. `slidemind ready` — session preflight (*First step* below)
 2. Clarify with the user — the content **and the output target** (*Intake → plan* below; needs no
    host, so it can run while `ready` executes)
-3. Plan sign-off — `slidemind plan <deck>` (decks; single slides stay in chat)
-4. Concept mockups — `slidemind concepts <deck>`, then immediately inspect every mockup to drive
-   image/content search (a deck authored from an approved plan; see *The create flow* below)
-5. Author the slides
-6. Draft check — `slidemind view-draft`
-7. Review gate — `slidemind review`, the moment the deck builds clean
-8. Deliver — `slidemind push` or `slidemind build-pptx`, whichever target was locked in stage 2
+3. Plan sign-off — `slidemind plan <deck>` (every from-scratch request — one slide included)
+4. Concept mockups — `slidemind concepts <deck>`, then immediately inspect every mockup (anything
+   authored from an approved plan, a single slide included; see *The create flow* below). **The FILES ON DISK are the
+   truth, not the command output you saw.** Generation takes 1–2 minutes and your harness may
+   time the command out, showing you only progress lines while the detached process finishes
+   writing the PNGs — output that ends mid-progress means TIMED OUT, never "no mockups". The
+   moment the command returns (complete or cut off): run `ls decks/<slug>/concepts/`. PNGs
+   listed → re-run `slidemind concepts <deck>` once (it returns the full path list instantly for
+   already-generated mockups) and Read every file. **Claiming the concepts are missing requires
+   double evidence**: `asset-plan.md` may say "no mockups" ONLY when BOTH the re-run's output
+   printed zero paths AND `ls decks/<slug>/concepts/` is empty — quote both in the file.
+   Authoring a concept-seeded deck without having Read the concept PNGs that exist on disk is the
+   single largest fidelity failure this workflow has; nothing about a truncated stdout excuses it.
+   **User-provided images** go into this command, classified from the user's words: a sketch or
+   mockup to build ("build it like this") → `--concept <file>[@N,M]` (it becomes the mockup for
+   those slides, no generation); a look to emulate ("in this style") → `--style <file>[@N,M]`
+   (leads the generation; repeatable; `@` omitted = all slides). A photo or logo to place on a slide
+   is not a concept input: copy it into `decks/<slug>/assets/` and list it in `asset-plan.md`.
+5. Source assets — write `decks/<slug>/asset-plan.md` from the concepts, then search + download
+   every item in it (*The create flow* steps 2–3). **This stage is not optional and not mergeable
+   into authoring**: it is done when every plan item is checked off with a filename or marked
+   `(no result)` after its search ran. A deck with concept mockups and an empty `assets/` beyond
+   the brand chrome means this stage was skipped, not completed.
+6. Author the slides
+7. Draft check — `slidemind view-draft`
+8. Review gate — `slidemind review`, the moment the deck builds clean
+9. Deliver — `slidemind push` or `slidemind build-pptx`, whichever target was locked in stage 2
+
+**Changing slides that already exist runs a shorter list.** When the deck is on disk and the
+request targets slides in it — "make slide 13 clearer", "rescope 12 and 13", "fix the spacing",
+comments on a delivered deck — the stages are `ready` → edit → `view-draft` → `review` → deliver.
+Stages 2–5 do not run: there is nothing to plan and no mockup to render, the live slide is the
+starting point (the in-app equivalent is the manager's route B, `approvedPlan: null`; the design
+worker's small-edit fast path keeps no todo board at all). Updating `plan.md` afterwards is optional
+bookkeeping and never re-opens the plan gate — once a deck has passed a review, the CLI treats
+`plan.md` as a record, not a contract. The full route definitions are in *Intake → plan* below; new
+slides added to an existing deck are from-scratch work and run the full list.
 
 **Deliver is the last todo — the task ends when the slides are delivered.** Don't add a "sanity
 pass" or "report back" step after it: the visual QA already happened at the draft check and the user
@@ -50,8 +85,9 @@ already approved at the review gate, so on approval you push/build directly and
 full definition and the ordering invariants live in the bundle's `workflow/flow.md` — read it right
 after `ready` succeeds.
 
-**Concept mockups (stage 4) are a mandatory deck stage, not an optional aid.** After plan sign-off,
-for a deck authored from an approved plan, you **always** run `slidemind concepts <deck>` and
+**Concept mockups (stage 4) are a mandatory authoring stage, not an optional aid.** After plan
+sign-off, for anything authored from an approved plan — one slide as much as a deck — you **always**
+run `slidemind concepts <deck>` and
 **immediately Read every generated `concept-slide-NN.png` at full detail**. Use this first,
 deck-wide viewing pass to inventory the imagery, pictograms, factual/content checks, and other
 searches each slide needs; do those searches before authoring. This discovery read does **not**
@@ -60,23 +96,42 @@ The durable visual anchors are the repo-relative files under
 `decks/<slug>/concepts/concept-slide-NN.png`, never an earlier chat image or temporary attachment;
 after any continuation, re-list that directory and reopen the files from those paths.
 Rebuild each mockup toward its target — this is the local-harness equivalent of the in-app manager's
-*unconditional* concept pass on every full-deck delegation (`generateConceptImages` fires for
-`approvedPlan && !targetSlideScope`). It degrades benignly: if it returns no mockups (exit 0 — the
-add-in can't generate them) you author from the storyboards alone, but the *attempt* is not optional.
-Skip it only where the add-in's `!targetSlideScope` gate would — a single slide, a tiny in-chat set,
-or a targeted rework of existing slides.
+*unconditional* concept pass on every from-scratch delegation (`generateConceptImages` fires for
+every delegation carrying an approved plan). It degrades benignly: if it returns no mockups (exit 0 —
+the add-in can't generate them) you author from the storyboards alone, but the *attempt* is not
+optional. Skip it only for targeted work on slides that **already exist** — an edit or a rework,
+which designs from the live slide and never had a plan to render mockups from.
 
 Two gate invariants you must never break — one per gate, equally binding:
 
-- **Never jump from clarify to authoring for a deck** — the plan sign-off gate (`slidemind plan
-  <deck>`, stage 3) always sits between. Writing `decks/<slug>/slides/*.jsx` before that gate has
+- **Never jump from clarify to authoring** — the plan sign-off gate (`slidemind plan <deck>`,
+  stage 3) always sits between. Writing `decks/<slug>/slides/*.jsx` before that gate has
   returned `DECISION: approved` is the single most common way this workflow goes wrong — it means
-  the user never actually signed off on the story. The only exception is a single slide or a tiny
-  set genuinely handled in-chat (*Intake → plan* below) — that's a real design choice, not a
-  shortcut to take when a deck-sized request feels obvious.
+  the user never actually signed off on the story. **There is no small-request exception**: one new
+  slide runs the same gate with a one-beat plan. The only work that skips it is a change to slides
+  that already exist.
 - **Never jump from authoring to deliver** — the draft check and an approved review gate always sit
   between.
 
+## After a context summarization (compaction recovery)
+
+Long deck runs can exceed the context window mid-task; the harness then replaces the transcript
+with a summary. **Everything you only held in chat — viewed concept images, search results, the
+asset inventory, workflow rules you read from the bundle — is gone; the files on disk are not.**
+When you notice you are running from a summary (or after any interruption/continuation), do NOT
+improvise from the summary and do NOT restart finished work. Recover state from disk, in this
+order, then resume at the first incomplete stage:
+
+1. `decks/<slug>/plan.md` — the approved story.
+2. `decks/<slug>/asset-plan.md` — per-slide organisms + which assets are downloaded vs. missing
+   (unchecked items still need their search + fetch).
+3. `ls decks/<slug>/slides/ decks/<slug>/assets/ decks/<slug>/concepts/` — what already exists.
+4. Re-read `<bundle>/workflow/create.md` if you are still before or inside authoring, and reopen
+   the concept PNGs for the slides not yet authored (batches of ≤3) before writing them.
+
+The stage todo list still binds after a summary: a summary that says the deck is "mostly done" is
+never a reason to skip the remaining stages (assets, draft check, review gate).
+
 ## Bootstrap (set yourself up — don't make the user do it)
 
 **The first step of every session is `slidemind ready`** (continuing an existing deck: `slidemind
@@ -139,25 +194,36 @@ ask for a fresh one. The pane flips to **Connected** by itself once the claim is
 Everything about how a deck is authored, styled, and rendered is shaped by the corporate design
 **the add-in has open**, and every brand rule you follow is read from that design's **materialized
 bundle**. `slidemind ready` gets you there in one call: it walks the connection ladder (a saved
-session → reachable backend → CLI version → an open render-ready window), resolves which open design
-to build against, downloads or refreshes that design's bundle (incremental — unchanged files cost
-nothing), and — when you pass a deck — binds the deck to it by writing `<deck>/.bundle-ref.json`.
-
-- **New work:** `slidemind ready` — resolves + materializes the open design's bundle so you can read
-  its `design.md` while planning.
-- **Continuing a deck:** `slidemind ready <deck>` — same, and (re)binds the deck to whatever design
-  is open.
-
-**The open add-in is the source of truth.** `ready` binds to whatever design is open *now*; a deck's
-`.bundle-ref.json` records the last-resolved design for the render-time etag contract and host-free
-bundle reads — it is **not** a pinned design preference. So you never "start a session with design
-A" from a deck ref; you start it from what the add-in has open.
-
-**On exit 0** the JSON reports `presId`, `presFP`, `designName`, `bundleDir`, `bundleEtag`, `bound`,
-`paneSuspended`, and `engines` (`{available, envs}` — whether engine search reaches the corpus
-without a window), with `nextAction: "Ready."`. Read `workflow/flow.md` and `design.md` from
+session → reachable backend → CLI version), picks which design to build against, downloads or
+refreshes that design's bundle (incremental — unchanged files cost nothing), and — when you pass a
+deck — binds the deck to it by writing `<deck>/.bundle-ref.json`. PowerPoint does not have to be
+open: the designs cached on this machine are a first-class source.
+
+- **New work:** `slidemind ready` — picks + materializes a design's bundle so you can read its
+  `design.md` while planning.
+- **Continuing a deck:** `slidemind ready <deck>` — same, and the deck's own binding is what it
+  picks.
+
+**The design is the user's choice; `ready` only picks a sensible default.** Its order is: an
+explicit `--brand <presFP>`, else the deck's own `.bundle-ref.json`, else the one design the
+verified live PowerPoint windows agree on (a window whose pane is only suspended never outranks a
+live one), else the one design cached here, else the one design the backend lists. Anything
+that leaves several candidates is the `ambiguous_design` blocker (below). A live window is a
+suggestion, never an authority: it only decides when nothing stronger says otherwise. And whatever
+`ready` picked, when its `designs` list holds more than one entry the design is a Clarify question
+(below), and the answer is applied with `slidemind ready [deck] --brand <presFP>` before anything
+is planned.
+
+**On exit 0** the JSON reports `presId`, `presFP`, `designName`, `designs` (every design at hand
+— cached on this machine, open in a verified window, or listed by the backend — `{presFP, name,
+colors, current, cached, windows}`, `colors` being the master's theme colours as hex,
+`dk1`/`lt1`/`dk2`/`lt2`/`accent1..6`, `windows` the open PowerPoint windows on that design),
+`windows` (every verified open window — `{presId, env, title, fileName, presFP, paneReady}`; a
+window PowerPoint no longer has is pruned before anything is decided), `bundleDir`, `bundleEtag`,
+`bound`, `paneSuspended`, and `engines` (`{available, envs}` — whether engine search reaches the
+corpus without a window), with `nextAction: "Ready."`. Read `workflow/flow.md` and `design.md` from
 `bundleDir` (cached at `${XDG_CACHE_HOME:-~/.cache}/slidemind/bundles/<presFP>/`, alongside
-`corporate-design.css`, `layouts/*.jsx`, `layouts/layouts.css`, `assets/`, `samples/`, and the rest
+`corporate-design.css`, `layouts/*.jsx`, `layouts/layouts.css`, `assets/`, and the rest
 of the add-in-owned `workflow/*.md`) and start planning. A render-ready window whose pane is
 suspended still exits 0 with `paneSuspended: true` — the pane ops wait for a pane click on their
 own; **don't treat it as a blocker.**
@@ -181,24 +247,23 @@ complete the sign-in in the browser (you cannot) and keep waiting — don't kill
 command. One sign-in lasts ~90 days. Rendering, bundles, and already-materialized assets never need
 it, so a pure author→render session runs signed-out without ever seeing this.
 
-For a deck that was **never** bound and no window is open, `ready` asks the backend which corporate
-designs the user may build against: exactly one binds automatically, several stop with
-`ambiguous_brand` (below).
+For a deck that was **never** bound and no window is open, the one design cached here binds
+automatically; with nothing cached `ready` asks the backend which corporate designs the user may
+build against, and exactly one binds. Several of either stop with `ambiguous_design` (below).
 
 **On non-zero** the CLI names exactly one blocker `{code, actor, message}` and one `nextAction`.
 **The CLI owns the remediation text — relay `nextAction`, don't restate it.** These are the ones
 that need the user:
 
-- **`ambiguous_design`** — several windows with **different** corporate designs are open, so `ready`
-  can't choose. The CLI lists the candidates (each with its `env` and window `title`/`fileName`,
-  plus a design fingerprint); if the deck was last built against one of them it's marked
-  `suggested`. **Ask the user which design to build against, naming the windows by
-  `title`/`fileName` (and `env`) — never by raw id** — and mention the suggested one if present
-  ("this deck was last built against X — continue with it?"). Then re-run `slidemind ready --to
-  <presId>` for the window they pick.
-- **`ambiguous_brand`** — the same question with no window to ask it from: the backend offers
-  several designs (`brands[]`, each with a `name` and `env`). Ask the user by **name**, then re-run
-  `slidemind ready [deck] --brand <presFP>`.
+- **`ambiguous_design`** — several corporate designs are at hand and nothing says which: several
+  live windows on different designs, or no live window and several designs cached / listed by the
+  backend. The payload is the same `designs` menu as on success (name, `colors`, `cached`, and
+  the open `windows` on each) plus `windows`; if the deck was last built against one of them its
+  `presFP` is `suggested`. **Ask the user which design to build against exactly as the Clarify
+  question below does — by name and colours, naming any open window on it by `title`/`fileName`,
+  never by raw id** — and mention the suggested one if present ("this deck was last built against
+  X — continue with it?"). Then re-run `slidemind ready [deck] --brand <presFP>` for the design
+  they pick (`--to <presId>` also works when they named a window).
 - **`login_required`** — the automatic browser sign-in was refused or abandoned, so **corpus search
   and engine downloads** stop until the user runs `slidemind login` (browser step, whenever they're
   ready). It never blocks authoring, rendering, or the bundle — relay the line, keep working, and
@@ -213,9 +278,9 @@ that need the user:
 **The session spine** (= the stage todos you created up front): `slidemind ready` → read
 `workflow/flow.md` + `design.md` from `bundleDir` → intake/plan (below) → `slidemind new <slug>`
 (scaffolds **and** auto-binds the deck to the open design — zero extra download, because `ready`
-already materialized it) → `slidemind plan <slug>` (plan sign-off gate for decks; single slides stay
-in chat) → `slidemind concepts <slug>` (mandatory concept-mockup pass for a deck, then rebuild
-toward each) → author → `view-draft` → `review` (mandatory, the moment the deck builds clean) →
+already materialized it; `--brand <presFP>` binds to the design the user chose instead) → `slidemind plan <slug>` (plan sign-off gate for every
+from-scratch request, one slide included) → `slidemind concepts <slug>` (mandatory concept-mockup pass for everything
+authored from a plan, then rebuild toward each) → author → `view-draft` → `review` (mandatory, the moment the deck builds clean) →
 deliver (`push` / `build-pptx`). `slidemind new` best-effort binds when the open design is
 unambiguous and the bundle is already materialized; if it can't (ambiguous, or no host), it
 scaffolds anyway and hints to run `slidemind ready <slug>`.
@@ -264,9 +329,43 @@ This is your mapping of `workflow/flow.md` stages 1–2 (*clarify* + *plan sign-
 manager runs these; over the CLI the manager role collapses onto **you**, so you run the interview
 and the sign-off directly with the user. Don't write slide JSX until the plan is agreed.
 
+**First read which of three things the user wants**, from their words plus what you already have —
+the deck you are working in, the file they pointed at, what you built for them a moment ago. Judge it
+yourself and ask only when the request genuinely reads both ways. **Slide count never decides the
+route; intent does.**
+
+- **Author something new** ("a slide about X", "a deck for Friday", "add a closing slide", filling an
+  empty placeholder) → the full spine: plan → `slidemind plan` → `slidemind concepts` → author →
+  `view-draft` → `review` → deliver. One slide runs every one of those stages, just smaller.
+- **Change slides that already exist** ("make slide 4 stronger", "fix the spacing", "retitle these
+  three") → **no plan, no concepts**: there is nothing to plan, the live slide is the starting point.
+  Read `workflow/edit.md`, patch that slide's own `.jsx` (adopt a foreign slide on first touch), then
+  `view-draft` → `review` → deliver. The review gate still runs — over the CLI the deliver happens
+  out of the user's sight, so it is the only place they see the change.
+- **Reuse something that already exists elsewhere** ("do we have a slide on X?", "drop in our pricing
+  slide", "put our lighthouse icon here") → that is **`slidemind-search`**, not this create flow:
+  `slidemind search` → `download-result` / `add-slide`. Reuse is not authoring — no plan, no
+  concepts.
+
+A request can carry two of them ("find our pricing slide and write a summary after it") — run each
+part on its own route instead of forcing the whole thing onto one.
+
 - **Read scope from the wording**, don't ask redundantly: single slide ("make a slide about X"),
   small set ("add three slides on Y"), or whole deck ("a deck for Friday"). Only ask "one slide, a
   small set, or a full deck?" when truly ambiguous.
+- **Which corporate design — ask whenever more than one is cached.** `ready`'s `designs` list is
+  the menu: with a single entry there is no question; with several, put the choice to the user
+  **before planning**, even if PowerPoint has one of them open (that one is only the suggestion).
+  Never pick silently and never default to the open window or the deck's last binding — those
+  only chose `ready`'s `current` default, not the user's answer. Name each
+  design **and show its colours** so the user recognises it — the `name` plus its theme hexes in a
+  fixed order (`<name> — accent <accent1>, dark <dk1>, light <lt1>`, each a hex from `colors`; a
+  design without `colors` is listed by name alone), mark the `current` one, and ask which to build
+  against. Then
+  apply the answer: `slidemind ready [deck] --brand <presFP>` for the session, and `slidemind new
+  <slug> --brand <presFP>` when scaffolding a new deck. A design the user names that is not in the
+  list is not cached yet — `slidemind ready --brand <presFP>` fetches it when the backend serves
+  it; otherwise it must be opened in PowerPoint once.
 - **Interview just enough** to pin: audience/goal, the content and its sources (none / pasted /
   local files / existing deck / web research — a source that's already a local `.pptx` you read
   host-free with `slidemind read <file.pptx>`), and the slide outline (each slide's role + a layout
@@ -279,9 +378,10 @@ and the sign-off directly with the user. Don't write slide JSX until the plan is
   wording is clear ("add a slide to this deck" → push; "make me a deck I can send around" → a file)
   and ask only when genuinely ambiguous — but **always confirm the concrete target before
   delivering** (which window, or which output path).
-- **Replay and get sign-off.** Single slides / tiny sets → a compact in-chat plan (no gate). Decks →
-  persist a **story-focused plan with body storyboards** in `decks/<slug>/plan.md`, two top-level
-  sections in order:
+- **Replay and get sign-off — always, at every size.** Persist a **story-focused plan with body
+  storyboards** in `decks/<slug>/plan.md` and run the gate on it, whether the request is one slide or
+  forty. A single slide gets the same document with one `### Slide N` section: shorter, never
+  skipped. Two top-level sections in order:
   - `## Red thread` — one presentation **move** per slide, as bullets or one arrow-separated line.
     The number of moves MUST equal the number of `### Slide N` sections: when the user names a slide
     count, write exactly that many moves and sections — never expand the narrative arc beyond the
@@ -300,7 +400,11 @@ and the sign-off directly with the user. Don't write slide JSX until the plan is
   only two visible text fields: `designElement` (the visual mechanism in up to 5 words — e.g.
   "hub-spoke visual", "loop diagram", "timeline", "matrix", "before/after contrast", "scorecard")
   and `content` (a 1–2 word label), plus `emphasis` ("primary"/"secondary"/"tertiary") for
-  hierarchy. `keyMessage` is the slide's **story beat**: one plain sentence naming what this slide
+  hierarchy. A `designElement` may also name the chart family when the beat is quantitative
+  ("waterfall revenue to EBIT", "combo: revenue bars + margin line", "column chart by quarter");
+  that is a plan-level choice the authoring stage honours unless the data cannot be shown that
+  way, in which case it says so at the review gate.
+  `keyMessage` is the slide's **story beat**: one plain sentence naming what this slide
   does to move the story forward, stated abstractly — NOT the headline or copy that will appear on
   the slide, and not the red-thread move restated. `contentNotes` is the **content draft** that
   delivers that beat — facts, claims, examples, source points, caveats, draft copy, proof points —
@@ -323,14 +427,21 @@ and the sign-off directly with the user. Don't write slide JSX until the plan is
   Choose the block count from the slide's meaning and **never default to three** (1 for a hero idea,
   2 for a contrast or paired tension, 3 only for three genuinely distinct beats, 4–5 only for a true
   sequence or comparison set), and vary the spatial composition across slides — avoid repeating the
-  same left/right/bottom alignment. Ban style micromanagement only — no colours, fonts, exact layout
-  names, or final box/card counts: **the create stage owns realisation** of the approved body
-  storyboard in the corporate design. Use this exact JSON shape:
+  same left/right/bottom alignment. Ban style micromanagement — no colours, fonts, or final
+  box/card counts: **the create stage owns realisation** of the approved body storyboard in the
+  corporate design. The ONE exception is the top-level `layout` field: **choose each slide's
+  layout at plan time** from `design.md` → Layout Catalog (a workhorse with a freeform body for
+  content slides; a purpose-built layout for covers/quotes/agendas; match the background tone —
+  light vs dark — to the slide's intended look) and set `"layout": "<ComponentName>"` on the
+  storyboard block. The concept generator uses it to render the mockup INTO that layout's actual
+  chrome and canvas, so the image you later rebuild already fits the stage it will live on. Use
+  this exact JSON shape:
 
   ```storyboard-canvas
   {
     "version": 1,
     "slide": 1,
+    "layout": "<ComponentName from design.md's Layout Catalog>",
     "blocks": [
       {
         "id": "main-visual",
@@ -369,11 +480,10 @@ and the sign-off directly with the user. Don't write slide JSX until the plan is
   output was truncated). Change only what the comments require and keep unaffected slides verbatim
   (that is what makes the reviewer's per-slide "updated" badges meaningful), then **re-run the gate
   in the same turn**. **Expect several consecutive `DECISION: comments` rounds — that is the normal
-  shape of a review, not an error.** The reviewer's tab stays live while you revise, so they keep
-  reading and keep queueing comments; those queued comments are delivered by your next run, which
-  then returns *immediately* with them (a drain round) instead of waiting. So never end your turn on
-  a comments round, never claim to be "polling", and never send the user back to the browser between
-  rounds — nothing reaches them until the gate runs again. Only `DECISION: approved` or `DECISION:
+  shape of a review, not an error.** The reviewer's tab waits while you revise (reading stays live,
+  commenting is off) and refreshes with your next run, which blocks until they decide again. So
+  never end your turn on a comments round, never claim to be "polling", and never send the user
+  back to the browser between rounds — nothing reaches them until the gate runs again. Only `DECISION: approved` or `DECISION:
   pending` ends the loop; `DECISION: pending` → the gate timed out with no answer — not approval,
   not rejection: don't author; wrap up telling the user the plan still awaits their sign-off and
   re-run `slidemind plan <deck>` on their go-ahead. Loop until approved. A `plan.md` **approved in a
@@ -391,14 +501,7 @@ brand/layout/composition detail until create/edit.**
 to it by `slidemind ready <deck>` (continuing) or by `slidemind new <slug>`'s auto-bind (new work).
 From here:
 
-1. **Study brand samples (before composing).** The materialized bundle's `samples/` dir holds the
-   brand's own reference slides. If it's non-empty, pick **3 at random** and **Read** each (the Read
-   tool renders images) *before* writing any JSX — this is the local-harness stand-in for the in-app
-   persona's reference thumbnails, and it is what keeps a deck looking on-brand rather than merely
-   compliant. Study them for whitespace rhythm, shape density, hierarchy, accent use, and layering,
-   then compose in that spirit (never copy a sample 1:1). This is `composition.md`'s samples
-   discipline; skip only when `samples/` is empty.
-2. **Load create context, then inspect the concepts.** Read the create-stage references together —
+1. **Load create context, then inspect the concepts.** Read the create-stage references together —
    `workflow/create.md` (the procedure), `workflow/composition.md` (the composition baseline),
    `workflow/layouts.md` (palette + working area), and `workflow/authoring.md` (the substrate rules)
    — plus the deck's `design.md` and the specific `layouts/*.jsx` the plan uses. (That is the read
@@ -408,25 +511,39 @@ From here:
    sketch's geometry; how to interpret the `storyboard-canvas` blocks at author time (design
    hypothesis: reinterpret freely, never transcribe coordinates, block geometry, or block labels)
    is owned by `workflow/create.md` → Preconditions. **Generate concept mockups first — mandatory
-   for a deck (stage 4).** Before
-   authoring a deck from an approved plan, run `slidemind concepts <deck>` — the local-harness
+   for everything authored from a plan, a single slide included (stage 4).** Before
+   authoring from an approved plan, run `slidemind concepts <deck>` — the local-harness
    equivalent of the in-app manager's *unconditional* concept pass (`generateConceptImages` fires
-   for every `approvedPlan && !targetSlideScope` delegation). **Immediately after generation, Read
+   for every delegation carrying an approved plan). **Immediately after generation, Read
    every `decks/<slug>/concepts/concept-slide-NN.png` at full detail, before any engine or content
    search.** First list the directory and keep the literal repo-relative mapping in the task context:
    concept `NN` maps to `decks/<slug>/concepts/concept-slide-NN.png` and later to the `NN-*.jsx`
    slide. These workspace files are the durable source of truth across turns and compaction — never
    rely on an earlier rendered attachment. Inventory what each mockup requires — imagery, distinct
-   pictograms, factual/content verification, annotations, and other visible organisms — and use
-   that inventory to drive step 3. This first pass is deliberately deck-wide and search-oriented;
-   it is not the fresh authoring read required in step 4. Rebuild each mockup under your constraints
+   pictograms, factual/content verification, annotations, and other visible organisms — and
+   **persist the inventory to disk the moment you finish it: write `decks/<slug>/asset-plan.md`**,
+   one section per slide:
+
+   ```
+   ## Slide NN — <title>
+   organisms: <the mockup's regions, hero figure, badges, satellites, chips, connectors>
+   - [ ] icon: <what it depicts> — query: "<search query>"
+   - [ ] image: <what it shows> — query: "<search query>"
+   ```
+
+   Chat context is evicted when the conversation is summarized; this file is not. Every icon
+   decision you make only in your head is lost at the next compaction — the file is the contract
+   step 2 executes and step 3 authors from. Check items off (`- [x] … — assets/engine-<id>-<n>.svg`)
+   as downloads land, so the file always shows what is still missing. This first pass is
+   deliberately deck-wide and search-oriented; it is not the fresh authoring read required in
+   step 3. Rebuild each mockup under your constraints
    — the rebuild rule is owned by
    `workflow/create.md` → Preconditions (reproduce the mockup's composition, hierarchy, graphic
    mechanism, AND granularity — its organism count, badges, satellites, and annotation layers are
    part of the target, and restraint is a colour budget, never an element budget; texts follow the
    story). It never hard-fails: if it produces no mockups (exit 0 — the add-in can't generate them)
-   author from the storyboards alone. Skip it only where the add-in's `!targetSlideScope` gate would
-   — a single slide, a tiny in-chat set, or a targeted rework of existing slides.
+   author from the storyboards alone. Skip it only for targeted work on slides that **already
+   exist** — an edit or a rework.
    When storyboard objects share a `visualFamily`, rebuild those mockups as one recognizable visual
    series. The lowest-numbered member is the anchor. Preserve its shape vocabulary, framing,
    hierarchy, annotation style, illustration treatment, and spatial rhythm across the family, but
@@ -434,13 +551,26 @@ From here:
    own complete `keyMessage`, `contentNotes`, role, and structure. Never copy another member's text,
    claims, or data, never force its exact geometry, and never omit approved content because it does
    not fit the anchor composition.
-3. **Search and fetch from the concept inventory.** Resolve the image and content needs identified
-   in the immediate post-generation concept pass. Discover the available image engines by listing
-   them — `slidemind ls engines --subtype image` (the local-harness equivalent of the in-app design
-   agent's
-   `list_engines` tool; no PowerPoint window needed where the add-in serves the pane-free engine
-   routes) — judge which engine fits from its label and description, then search it and place
-   results. (`slidemind search` without `--engine` picks an image engine the same way.) The engine
+2. **Execute `asset-plan.md` — search and fetch every unchecked item.** Discover the available
+   image engines by listing them — `slidemind ls engines --subtype image` (no PowerPoint window
+   needed where the add-in serves the pane-free engine routes) — judge which engine fits from its
+   label and description, then run every query in `asset-plan.md` and fetch the picks.
+   (`slidemind search` without `--engine` picks an image engine the same way.) Listing the engines
+   is discovery, not sourcing: this step is done only when every `asset-plan.md` item is checked
+   off with a downloaded filename or marked `(no result)` after its search actually ran. Four
+   mechanics that waste rounds when gotten wrong:
+   - **Icon results have no preview.** `slidemind view-slide` serves slide-library results only —
+     on an image/icon search it answers "no image returned" every time, so never call it there and
+     never retry it. Pick from the `search` output's titles/scores; a download is cheap and
+     `download-result` prints each asset's size + recolor info — download first, judge from the
+     saved file, re-search once if it was wrong. At most two search rounds per need; two failed
+     downloads = mark it `(no result)` and move on.
+   - **Batch the downloads:** one `download-result --search <id> --pick <n,n,…>` per search id —
+     never one call per icon.
+   - **Quote hex colors:** `--icon-color "#<hex>"` (a value resolved from a corporate-design.css token) — an unquoted `#` makes the shell drop the
+     rest of the line.
+   - Searches come **from the file, after the concept pass** — never from plan nouns before the
+     concepts exist. The engine
    search/reuse mechanics live in **`slidemind-search`** — use it to find and fetch imagery; the
    create-only detail — sizing a fetched asset's box and recolouring an icon — is in *Placing engine
    imagery* below. To pull in an **existing whole slide** (not just an image), use
@@ -448,23 +578,30 @@ From here:
    `.pptx` that coexists with your JSX in play order and survives re-push. The slide can come from
    an engine search **or** from a local `.pptx` on disk (`add-slide --from <file.pptx> --pick <n>
    --deck <slug>`, host-free); both fold in identically — see `slidemind-search`.
-4. **Reopen the concepts, then author in small batches.** Once the searches and asset downloads are
+3. **Reopen the concepts, then author in small batches.** Once the searches and asset downloads are
    complete, split a concept-seeded deck into batches of at most **3 slides**. For each batch, first
    Read its matching anchored `decks/<slug>/concepts/concept-slide-NN.png` files together at full
    detail; as the **very next tool action**, create those slides'
    `decks/<slug>/slides/NN-<topic>.jsx` files. Put no search, command, reference read, user exchange,
    or unrelated work between the concept images and the JSX write.
-   The deck-wide discovery read in step 2 never counts as this authoring read. A user interruption,
+   The deck-wide discovery read in step 1 never counts as this authoring read. A user interruption,
    resumed turn, compaction, long wait, or unrelated tool work invalidates an earlier authoring read:
    re-list `decks/<slug>/concepts/` if needed and reopen the affected anchored files before writing.
    This batching is a local-harness context discipline, not a second create pass: the whole deck
    remains one create pass and every slide file is created exactly once. Use a zero-padded numeric
    prefix from the first file on (play order is filename order here; see the slide-file row in the
    command mapping), one default export per slide, and one bundle layout (Mode A) or blank-content
-   layout with freeform children (Mode B), exactly as the bundle docs prescribe.
-5. **Look at your own draft first (you, the agent).** This is the **draft check** in
-   `workflow/build-and-export.md` — your pre-check, *before* any human sees the deck. Run `slidemind
-   view-draft <deck>`: it renders each authored `slides/*.jsx` to a per-slide PNG and hands the
+   layout with freeform children (Mode B), exactly as the bundle docs prescribe. **A slide whose
+   `asset-plan.md` section lists downloaded assets is UNFINISHED until its jsx references them**
+   (`<img src="./assets/engine-….svg">`, sized per *Placing engine imagery* below) — a concept full
+   of pictograms rendered as bare text boxes is a failed rebuild, not a style choice.
+4. **Look at your own draft first (you, the agent).** This is the **draft check** in
+   `workflow/build-and-export.md` — your pre-check, *before* any human sees the deck. Two rules
+   moved early on purpose — do them NOW, not at the review gate when the run is long and attention
+   is spent: first run `slidemind build <deck>` once and fix every `[lint:warn]` it prints (a
+   mechanical pass on files you just wrote); and after any fix round below, one more `slidemind
+   view-draft` over the changed slides is mandatory — the verification must appear in your command
+   sequence, not only in prose. Run `slidemind view-draft <deck>`: it renders each authored `slides/*.jsx` to a per-slide PNG and hands the
    images back to you — **nothing is pushed, no `.pptx` is written, no review gate opens**. For
    every concept-seeded slide, Read its anchored
    `decks/<slug>/concepts/concept-slide-NN.png` and matching
@@ -479,7 +616,7 @@ From here:
    to capture, so they come back as a status line, not an image — judge those at the full-deck
    `review`/`build` step below. Do this self-check before the human review gate; don't push a draft
    you haven't looked at.
-6. **The review gate — the moment the deck builds clean.** This is the **review gate** in
+5. **The review gate — the moment the deck builds clean.** This is the **review gate** in
    `workflow/build-and-export.md`; the CLI's gate command is `slidemind review <deck>`. Run it the
    instant the authored set builds clean — before any deliver, without asking whether the user wants
    a review. It builds the HTML preview first (the same lint the render enforces, so a gate that
@@ -499,11 +636,10 @@ From here:
      it rather than trusting the cited line blindly. **Edit the cited files in place at the given
      line and re-run `slidemind review <deck>` in the same turn.** **Expect several consecutive
      `DECISION: comments` rounds — that is the normal shape of a review, not an error.** The user's
-     tab stays live while you fix: they keep browsing the preview and keep dropping pins, and those
-     queued pins are delivered by your next run, which then returns *immediately* with them (a drain
-     round) instead of waiting. So never end your turn on a comments round, never claim to be
-     "polling", and never send the user back to the browser between rounds — nothing reaches them
-     until the gate runs again. Addressed pins come back as read-only ghost pins so the user can
+     tab waits while you fix (browsing stays live, pinning is off) and refreshes with your next run,
+     which blocks until they send the next batch of pins or approve. So never end your turn on a
+     comments round, never claim to be "polling", and never send the user back to the browser
+     between rounds — nothing reaches them until the gate runs again. Addressed pins come back as read-only ghost pins so the user can
      confirm each note was worked in. Only `DECISION: approved` or `DECISION: pending` ends the
      loop. Nothing is exported on a comments round. **Every round is persisted verbatim in
      `<deck>/review.json`** — if your shell capture of the gate's output was truncated or lost
@@ -577,6 +713,29 @@ Three refusals are not foldable and need the user, not a retry:
   add-in is older than this contract, or its PowerPoint build cannot export slides. Tell the user to
   update the slidemind add-in. Do not paper over it with `--force`.
 
+## Charts (create-authoring specifics)
+
+A real series of numbers is a `<Chart>` element in your JSX — one self-closing element that renders
+as a native PowerPoint chart with its own embedded workbook, so the client double-clicks it and
+edits the data in Excel. Never hand-draw a chart from divs, bars, lines or SVG, and never let a
+table stand in for one; conceptual figures (process, framework, hub, timeline with no measured
+values) are not charts and stay HTML/SVG. The type list, the props each type accepts, the
+theme-first colour rule (leave `seriesStyle` off and the brand paints it) and the kinds that are
+out of the model live in the bundle's `workflow/authoring.md` → Charts — read them there, don't
+guess; the composition rule (one chart is the hero; the accent marks ONE series or point, not six)
+is in `workflow/composition.md` → Charts in the composition. Three local-harness facts: numbers the
+user states in chat go straight into the chart's `data` prop; this harness has **no analyst
+subagent**, so when the numbers live in a file you do the aggregation yourself, say what you did,
+and put the RESULT in the props (the deck carries the numbers, never a pointer to your workspace);
+and both the HTML preview and `slidemind view-draft` paint a **stand-in** for a chart, not
+PowerPoint's render — judge a chart's final look from the pushed slide (the review gate warns the
+user on chart slides itself). Editing a chart later — yours, or one on a slide
+the deck adopted from PowerPoint — is editing its `<Chart>` props and re-rendering; an adopted
+chart keeps its `data-sm-source-id` and its `conversions/<stem>.slide.pptx` (never delete either:
+the push patches the client's own chart part through them, so its Excel data and styling
+survive). To see what a chart on a live slide plots, `slidemind read <presId> --mode raw` prints a
+data table per chart; `slidemind read <file.pptx>` (host-free) reports text only, no chart data.
+
 ## Placing engine imagery (create-authoring specifics)
 
 Finding and fetching engine imagery is `slidemind-search`'s job (`slidemind search` → `slidemind
@@ -624,17 +783,17 @@ Vocabulary. You are the local harness — this is your mapping:
 |---|---|
 | (session setup — a CLI-only stage before the spine) | `slidemind ready [deck]` — the one-shot session start: connection ladder + design resolution (open window, the deck's own binding, or `--brand <presFP>`) + bundle materialize + deck bind. **Run it first, every session** (see *First step* above). `slidemind download-bundle` is the lower-level materialize-only command `ready` now covers — you rarely call it directly |
 | **track the stages** | your harness's task tracker — explicitly create the stage todo list before your first command and keep it current (see *Create a todo list* above) |
-| **clarify** / **plan sign-off** | intake stays in chat with the user (above); for decks, persist `decks/<slug>/plan.md` as `## Red thread` + `## Per-slide storyboards` (one `storyboard-canvas` JSON block per slide), then run `slidemind plan <deck>` — the same blocking `DECISION:` gate contract as `slidemind review`, on the plan (renders editable storyboards — red-thread strip + spatial canvases — plus slide-anchored comments; expect several comment rounds, some returning instantly with comments queued while you revised; loop until approved) |
-| concept mockups (mandatory deck stage, after plan sign-off) | `slidemind concepts <deck>` — renders one image mockup per approved-plan slide into the durable repo-relative path `decks/<slug>/concepts/concept-slide-NN.png`; immediately Read all of them for image/content search, then after searches reopen them in batches of at most 3 immediately before writing the matching `NN-*.jsx`. Re-list and reopen those paths after any interruption or continuation; never rely on an earlier chat image. The rebuild rule is owned by `workflow/create.md` → Preconditions. It never hard-fails: on an empty result (exit 0 — the add-in can't generate them) author from the storyboards alone, but for a deck you always run it. Skip only where the add-in's `!targetSlideScope` gate would — a single slide, a tiny in-chat set, or a targeted rework of existing slides |
+| **clarify** / **plan sign-off** | intake stays in chat with the user (above); for every from-scratch request — one slide included — persist `decks/<slug>/plan.md` as `## Red thread` + `## Per-slide storyboards` (one `storyboard-canvas` JSON block per slide), then run `slidemind plan <deck>` — the same blocking `DECISION:` gate contract as `slidemind review`, on the plan (renders editable storyboards — red-thread strip + spatial canvases — plus slide-anchored comments; expect several comment rounds; loop until approved) |
+| concept mockups (mandatory for every from-scratch set, after plan sign-off) | `slidemind concepts <deck>` — renders one image mockup per approved-plan slide into the durable repo-relative path `decks/<slug>/concepts/concept-slide-NN.png`; immediately Read all of them for image/content search, then after searches reopen them in batches of at most 3 immediately before writing the matching `NN-*.jsx`. Re-list and reopen those paths after any interruption or continuation; never rely on an earlier chat image. The rebuild rule is owned by `workflow/create.md` → Preconditions. It never hard-fails: on an empty result (exit 0 — the add-in can't generate them) author from the storyboards alone, but for anything authored from a plan — one slide included — you always run it. Skip only for targeted work on slides that already exist (edit/rework) |
 | **read** / **list** the workspace | read the files from the materialized bundle dir (`<bundle>/…`) and your `decks/<slug>/` |
 | **create / update a slide file** | write `decks/<slug>/slides/NN-<topic>.jsx` on disk with a **zero-padded numeric prefix** (`01-cover.jsx`, `02-agenda.jsx`, …) — over the CLI, "the ordered set you hand to build & push" is expressed as **numeric-aware filename order**; there is no ordered-list channel, so reordering = renaming files. For a concept-seeded create or structural rewrite, the immediately preceding tool action must Read the matching anchored concept path(s) at full detail |
-| brand reference samples (studied before composing) | **Read** 3 random images from the materialized bundle's `samples/` dir — the Read tool renders them (see *The create flow* step 1) |
 | **draft check** | `slidemind view-draft <deck>` — renders each `slides/*.jsx` to `decks/<slug>/.draft-preview/<slide-basename>.png` and returns the images to **you**; **no push, no `.pptx`, no review gate**. Read each concept/draft path pair together, fix the JSX, render, and pair again. A draft-only inspection does not count. Host-free once the bundle is materialized. Freeform slides only — purpose-built (Mode A) and reused native `.pptx` slides report as a status line (judge those at `review`/`build`). This is your self-check; `slidemind review` is the *human* gate |
 | **build & push** | `slidemind push <deck>` (into the open PowerPoint — the insert needs a window) · `slidemind build-pptx <deck> [--out <file>]` (to a `.pptx` file — **host-free** for a bound deck: no PowerPoint window at all) — deliver whichever target was locked at intake; both render server-side via the bridge and for a bound deck the render itself is pane-free |
-| **the review gate** | `slidemind review <deck>` — builds the HTML preview (lint-clean or it doesn't open), serves it with a spatial comment overlay and **blocks until the user decides**, then prints `DECISION: approved` or `DECISION: comments` (each comment cited to `slides/<file>.jsx:line:col` + the round it was dropped on). On approve → deliver (`slidemind push` / `build-pptx`); on comments → edit the cited files and re-run `slidemind review` in the same turn (addressed pins show as ghost pins); expect several comment rounds, some returning instantly with pins the user queued while you were fixing. CLI delivers happen out of the user's sight, so **every deliver follows an approved review of what it delivers — re-run `review` after any slide change**. `push`/`build-pptx` never pause; only `review` does. |
+| **the review gate** | `slidemind review <deck>` — builds the HTML preview (lint-clean or it doesn't open), serves it with a spatial comment overlay and **blocks until the user decides**, then prints `DECISION: approved` or `DECISION: comments` (each comment cited to `slides/<file>.jsx:line:col` + the round it was dropped on). On approve → deliver (`slidemind push` / `build-pptx`); on comments → edit the cited files and re-run `slidemind review` in the same turn (addressed pins show as ghost pins); the user pins as many comments as they like and sends them as one batch (Approve is off while unsent pins exist); expect several comment rounds. CLI delivers happen out of the user's sight, so **every deliver follows an approved review of what it delivers — re-run `review` after any slide change**. `push`/`build-pptx` never pause; only `review` does. |
 | **inspect the deck** | `slidemind read [presId\|file.pptx] [--mode summary\|raw]` — one verb, two sources: pull the current content of an open presentation (a presId; **host-required** — it reads the live, possibly unsaved file) **or** read a local `.pptx` on disk (a file path; host-free — no PowerPoint, no pairing). Prefer the file path when the deck is saved. `summary` = per-slide outline; `raw` = each slide's plain text — to inspect what's there before editing. Plain text, not authoring markup |
 | **discover engines** (`list_engines`) | `slidemind ls engines [--type <collection\|search\|scope>] [--subtype <image\|slide\|template\|content>]` — the live catalog is the only engine list (the bundle carries none); pick an `id` from it, never guess one. Needs no PowerPoint window where the add-in serves the pane-free engine routes. It also lists **search scopes** for unfiltered corpus search — those belong to `slidemind-search`, not to imagery |
 | **engine search / fetch** | **`slidemind-search`** owns the engine search + reuse mechanics (`slidemind search` → `slidemind download-result`, plus whole-slide reuse via `add-slide`). For placing a fetched asset in your JSX, size its box from the printed `width×height`, pass `--icon-color` / batch with `--pick <n,n,…>` and colour per *Placing engine imagery* below |
+| **generate an image** | `slidemind imagen "<prompt>" --deck <deck> [--out <name.png>] [--size <size>] [--quality <tier>]` — use only for a planned photograph or illustration when engine sourcing returned nothing; never generate pictograms |
 | **see** a live slide | no CLI analog — once delivered, the user is looking at the result; your visual authority runs at the draft check and the review gate instead |
 
 Everything else in `workflow/*.md` — the composition craft, the substrate/authoring rules, the