slidemind 0.3.20 → 0.4.0

package/skills/create-slides/SKILL.md

@@ -1,899 +1,497 @@
 ---
 name: slidemind-create-slides
-description: Author branded slide decks and individual slides against the active corporate design. Owns the user-facing intake → plan → create → edit workflow that turns per-slide .jsx files into editable .pptx (rendered server-side in PowerPoint) plus a local HTML preview. Reads the brand rules, layout palette, and authoring workflow from a materialized design bundle served by the slidemind PowerPoint add-in — it ships neither its own brand nor its own exporter. Use whenever the user asks for a slide, a deck, a presentation, a slideshow, or to convert content into one; interview them for intent and output format first, then stay on-brand by reading the bundle at every step. Skip when the user only wants to open, present, rename, search, or query an existing deck without authoring or editing slide content.
+description: Author branded slide decks and individual slides against the active corporate design. Owns the user-facing intake → plan → create → edit workflow that turns per-slide .jsx files into editable .pptx (rendered server-side in PowerPoint) plus a local HTML preview. Reads the brand rules, layout palette, and authoring workflow from a materialized design bundle served by the slidemind PowerPoint add-in — it ships neither its own brand nor its own exporter. Use whenever the user asks for a slide, a deck, a presentation, a slideshow, or to convert content into one; interview them for intent first (the output is always an editable .pptx — never ask about the format), then stay on-brand by reading the bundle at every step. Skip when the user only wants to open, present, rename, search, or query an existing deck without authoring or editing slide content.
 ---
 
 # slidemind-create-slides
 
-This skill is **thin workflow glue for the local harness**. Everything that determines how a deck is
-authored, styled, and rendered lives in the **slidemind PowerPoint add-in** and reaches you through
-a **materialized design bundle**:
-
-- The **brand** — tokens, `corporate-design.css`, the `design.md` brand rules, the closed layout
-  palette, brand assets — is served per corporate design.
-- The **authoring workflow craft** — create, edit, composition, layouts, authoring contract,
-  build/export — is the add-in's deployment-shipped `workflow/*.md`, served on the same bundle so
-  the local harness reads **byte-identical** guidance to the in-app design agent.
-- The **`.pptx` render** happens server-side in the add-in. There is no local exporter.
-
-So this file owns only what is genuinely CLI-specific: the **first-step design-bundle gate**, a
-compact **intake/plan**, the **create flow**, and the **command mapping** that translates the
-workflow vocabulary — the harness-neutral verbs defined in the bundle's `workflow/flow.md` and
-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.
-
-## Create a todo list (before your first command)
-
-The moment this skill activates on an authoring task, **create a todo list of the workflow stages**
-in your harness's task tracker — before you run anything — and keep it current: mark each stage done
-as you complete it. This is `workflow/flow.md` → *track the stages*; the list is what keeps the
-later stages (above all the review gate) from being skipped. The stages, as they run over the CLI:
-
-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>` (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
-   command **always ends on one line, `CONCEPTS: <n>/<planned> <status>`** (`--json` for the
-   payload). Generation takes 1–2 minutes; if your harness cut the command off before that line
-   appeared, re-run it — mockups already on disk come back as the path list instantly. Only a
-   `CONCEPTS: 0/…` line means there are no mockups; a truncated output never does. Authoring a
-   concept-seeded deck without having Read the concept PNGs on disk is the single largest fidelity
-   failure this workflow has.
-   **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 — fill the `decks/<slug>/asset-plan.md` form `slidemind concepts` seeded (regions /
-   organisms / connectors / icons per slide, each with its share of the content area), then search + download
-   every icon row 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`, until it reports `DRAFT CHECK: no measured defects` AND each
-   concept/render pair matches region by region
-8. Review gate — `slidemind review`, the moment the deck builds clean (it refuses to open while the
-   last draft check's measured defects stand)
-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
-already approved at the review gate, so on approval you push/build directly and stop. Each stage's
-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 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**
-replace the fresh per-batch concept read immediately before JSX creation in *The create flow*.
-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 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** — 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. **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 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, the workflow rules you read from the bundle, this skill's own steps — is gone; the files
-on disk are not.** When you notice you are running from a summary (or after any interruption or
-continuation), do NOT improvise from the summary and do NOT restart finished work. Run
-`slidemind ready <deck>` first: it re-materializes and re-binds (idempotent) and ends with a
-**`stage:` line read from disk** (plan / concepts / asset plan / slides / draft check / review) and
-a **`next:` line naming the command or file that is due** (`stage` in `--json`). Resume there, after
-re-reading the set that stage works from:
-
-- **plan gate** → *Two UX rules* and the `slidemind plan` row below.
-- **concepts / sourcing** → `<bundle>/workflow/create.md` steps 1–2, `asset-plan.md`, every
-  `concepts/concept-slide-NN.png` at full detail.
-- **authoring** → `<bundle>/workflow/create.md` + `authoring.md`, `design.md`,
-  `corporate-design.css`, the `layouts/<Layout>.jsx` the plan names, `asset-plan.md`, `plan.md`;
-  then, per batch of ≤3, the matching concept PNGs immediately before each write.
-- **draft check** → *The create flow* step 4; **review** → step 5 + *Two UX rules*; **deliver** →
-  the deliver row. An **edit** to existing slides → `<bundle>/workflow/edit.md` + the cited files.
-
-Two rules bind: the stage todo list still binds after a summary — "mostly done" is never a reason
-to skip the remaining stages — and never author, judge, or deliver from a remembered image; reopen
-the PNG from its path. `<bundle>` is `bundleDir` from `slidemind ready <deck> --json`.
-
-## 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
-ready <deck>`). In one call it verifies authorization, connection, and CLI version; resolves the
-design the add-in has open; downloads or refreshes that design's bundle; and — given a deck arg —
-binds the deck to it.
-
-- **Exit 0** → you're fully set up. Read `workflow/flow.md` (the stage spine) and `design.md` from
-  the reported `bundleDir` and start planning.
-- **Non-zero** → the CLI names exactly one blocker and one `nextAction`; do what it says. (The two
-  blockers that ever need the user are handled in *First step* below.)
-
-`ready` drives the `slidemind` CLI, which reaches PowerPoint through the add-in's **cloud relay** —
-no local server. Patch a missing CLI yourself; **connecting** needs the user once (they hold the
-add-in's identity):
-
-- **Flags you are unsure of:** `slidemind <command> --help` prints that command's usage block; the
-  deck commands take `--json`.
-- **CLI missing** (`slidemind` not on `PATH`): `npm install -g slidemind` — that alone is the fix.
-  Only run `slidemind init --for <claude|codex|opencode|all>` ((re)deploys this skill) when this
-  skill did **not** come from a plugin: if the `SKILL.md` you are reading sits under a harness
-  plugin cache (`~/.claude/plugins/…`, `~/.codex/plugins/…`), the plugin already supplies it and
-  `init` would plant a second copy that drifts on the next plugin update. `npx slidemind <command>`
-  runs one-off without a global install; `slidemind --version` confirms PATH; `slidemind update`
-  upgrades (`--ref <version>` to pin) — unless the CLI itself came from a plugin, in which case
-  update it there.
-- **Not connected:** `ready` exits with `not_connected` — the CLI cannot start a connection by
-  itself, because the claim that carries the deployment's address is minted in the add-in. Ask the
-  user to open PowerPoint → slidemind → **Settings → General → Connect CLI**, press the **link
-  button**, and copy the command shown (press **CLI already installed?** for the short `slidemind
-  setup …` form). Have them paste it to you and run it **verbatim** — it connects, refreshes the
-  skills, and runs `ready` itself. Add `--no-install --for none` only if their install must not be
-  touched. `slidemind whoami` lists connected environments.
-
-The CLI is **multi-environment**: connect once per backend (local / dev / prod) and every command
-fans out across all of them, tags each open window with its `env`, and routes to the right backend
-automatically — no manual switching. (Scope first-use authorization with `--backend <url>`; scope
-later calls with `--backend <url|env>`.) A normal user connects to the baked-in production backend
-only.
-
-## Connecting the CLI (one-time; you guide the user)
-
-Connecting is the **only** step that genuinely needs the user, and it starts in
-PowerPoint — not here. Every organization runs its own slidemind backend, so an
-unconnected CLI has no address to reach and nothing to discover it from; the
-authenticated add-in knows both, and mints a one-time claim carrying its address.
-
-**1 — Ask for the command.** Tell the user to open the **slidemind add-in** task pane → **Settings**
-→ **General** → **Connect CLI**, press the **link button**, and press **Copy command**. If they
-already have the CLI, **CLI already installed?** swaps it to the shorter `slidemind setup …` form;
-either works.
-
-**2 — Run it verbatim.** Paste it exactly as given. It redeems the claim, saves the session,
-installs the CLI globally if needed, deploys the skills into every coding agent on the machine, and
-finishes by running `ready` — so no `init` and no add-in restart belong to this flow.
-
-**3 — If it fails.** A claim works once and expires in ~10 minutes; on *already used or expired*,
-ask for a fresh one. The pane flips to **Connected** by itself once the claim is spent.
-
-## First step — `slidemind ready` (before anything else, every time)
-
-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), 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/`, 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.**
-
-**A bound deck readies with NO window at all — that is the normal case, not a degraded one.**
-`slidemind ready <deck>` for a deck that was bound once before exits 0 with `windowless: true` even
-when PowerPoint is closed: the design identity lives in the deck's `.bundle-ref.json` and the bundle
-syncs over a pane-free route, so its ladder is *session → bundle freshness → engine reachability*,
-with **no pane precondition** — the pane is reported, never required. In that state authoring,
-`view-draft`, `build`, `review`, `build-pptx`, and (where `engines.available` is true) engine search
-and download all work end-to-end; only `push`'s insert, `insert-slide`, and `read <presId>` of an
-open presentation need a window — the `nextAction` says exactly that. Don't ask the user to open
-PowerPoint until one of those is actually next.
-
-**Microsoft 365 sign-in — automatic on first need; just let it happen.** The engine surface — corpus
-search, brand-imagery downloads, slide extraction — runs **as the user**. `ready` reports the state
-(JSON: `m365.signedIn`, `m365.degradation`) so you know it's coming, but you never initiate it: the
-first engine command opens the user's browser ITSELF, prints `Microsoft 365 sign-in needed — opening
-your browser…`, and **blocks until the human finishes**. When that line appears, tell the user to
-complete the sign-in in the browser (you cannot) and keep waiting — don't kill or re-run the
-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, 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 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
-  re-run the search after they've signed in. When a slidemind pane is already open the CLI says so
-  and routes the search through that window instead: follow what it printed.
-- **Connection blockers** (`not_connected`, `all_unreachable`, `cli_update_required`, `no_window`,
-  `not_render_ready`) — relay the CLI's `nextAction` verbatim (copy the setup command / open
-  PowerPoint / click the pane / run `slidemind update`). Connecting is walked through above.
-  (`no_window` only ever surfaces for a deck that is neither bound nor bindable from the backend's
-  design list — a bound deck rides the pane-free rung above instead.)
-
-**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; `--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>`.
-
-**Backgrounded — or closed — PowerPoint is expected to work.** Do not pre-emptively ask the user to
-focus PowerPoint or the task pane, and never ask them to keep it foregrounded while something runs.
-**The whole authoring loop is host-free for a bound deck** — intake → plan → concepts → author →
-`view-draft` → `review` → `slidemind build-pptx <deck> [--out <file>]` — because the render captures
-the slides with a local headless browser and assembles the `.pptx` server-side over the pane-free
-brand route (streaming its own `rendering slide n/m…` progress), and engine discovery, search,
-downloads, and slide reuse run off the connection wherever the add-in serves them
-(`engines.available` in `ready`'s payload; older add-ins relay them through a pane instead). Exactly
-three things need a live PowerPoint: **`push`'s insert**, **`insert-slide`**, and **`read
-<presId>`** of an open presentation. Where a pane *is* involved, the CLI handles the wait itself: up
-to ~2 min, one *"click the slidemind pane"* line when user help is genuinely needed, then a safe
-retry. If you see that line, relay it once and keep waiting — do not rebuild, re-plan, or babysit.
-If a `push` can't deliver (pane never woke, or no window at all), the rendered `.pptx` was saved
-next to the deck (`paneSuspended` + `fallbackFile` in the result) — nothing is lost; re-run the push
-once a window exists. Reserve the full "open PowerPoint…" instruction for when a command actually
-reports it as the blocker.
-
-`view-draft` and `review` run offline, but only against a **previously
-materialized** bundle — so `ready` (or a prior `ready`) must have succeeded at least once.
-`build-pptx` additionally needs the backend reachable (the OOXML assembly is server-side), but no
-PowerPoint window for a bound deck — so *"a `.pptx` file to send around"* is deliverable end-to-end
-with PowerPoint closed.
-
-## Two UX rules (gates + host)
-
-- **Announce every gate, with a clickable link.** The moment `slidemind plan` or `slidemind review`
-  starts it prints `ready at <url>` and a `BROWSER:` status line. Immediately tell the user in chat
-  whether a browser tab opened (new tab / reused tab / failed to open) and give the gate URL as a
-  clickable link — every round, and again whenever you report that you're still waiting on their
-  decision.
-- **Add-in unreachable → block and name the tab.** When a genuinely host-required command (`push`'s
-  insert, `insert-slide`, `read <presId>`) can't reach the add-in (a connection blocker, a pane that
-  never wakes, the *click the slidemind pane* line with no effect), **stop the workflow** — don't
-  skip the step, work around it, or retry silently. Ask the user to go back into the PowerPoint tab
-  of presentation **<title/fileName>** (name it from the command output or `slidemind ready --diagnose`
-  — never a raw id), then re-run the failed command once they have. Everything before delivery keeps
-  running meanwhile — never park the whole task on a window it doesn't need.
-
-## Intake → plan (you own this; do it in chat)
-
-This is your mapping of `workflow/flow.md` stages 1–2 (*clarify* + *plan sign-off*). In-app, a
-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.
-**Choose layouts from evidence.** Honor explicit choices first. For an extension, read the target deck and its section/insertion context: prefer the section's suitable body layouts, then the deck's common layouts. For a new presentation use the catalog's observed brand usage. Frequency wins among layouts that can fit the content; do not force layout variety or an 80/20 quota. Names, previews, hints and content areas guide semantic choices. Preserve native names; copy the exact component name and layoutKey from the catalog. Verified dark/light counterparts can be switched, but retain the deck's established pattern (for example dark dividers with light body slides). Never assume two layouts are equivalent just because names or colors resemble each other.
-
-**Record the slide's role, not a permanent layout classification.** Every storyboard carries `role: body | frame`; frame slides also carry `frameKind: cover | agenda | divider | closing`. Also record `layoutSelection: automatic | explicit`, `layoutKey` when provided, and a short `layoutReason`. Use `sectionId` for meaningful sections. A quote is ordinarily a body slide. Choose frame layouts from the available native names, previews and slots; no stored layout job is required. Use an empty blocks array only when the layout has no authored content area. Covers can require images; agendas can require composition. No frame mockup is generated by default, but source every required image, fill every required slot, and perform the normal fit and rendered checks.
-
-**Deliverable intent is independent of delivery target.** `slides` adds only the requested slides, with no automatic frame; an explicitly requested cover or divider is still valid. `deck` adds the appropriate available frame whether delivered as a file or into PowerPoint. A deck request's count means body slides unless the user states a total limit. Show body and total counts separately. Default to available cover/closing, agenda at four body slides or two meaningful sections, dividers for multiple meaningful sections; never invent sections for these thresholds. Record an unavailable frame layout as an omission in the plan. User choices override defaults. Never overwrite a signed-off layout because usage evidence changed.
-
-For an existing target or explicit reference deck, run `slidemind read <presId|file.pptx> --mode summary --deck <deck>` before planning to bind its usage snapshot to this workspace. Refresh that read when the target changes. Standalone decks without a reference use brand usage and require no live window.
-
-- **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
-  *job* like cover/agenda/section/quote/closing/body — the concrete brand layout is chosen later
-  against the bundle). If the content source resolves to "none", don't silently plan from generic
-  knowledge — say so, and either interview the user for the substance (their claims, numbers,
-  examples) or offer web research before writing storyboards.
-- **Lock the output target — it decides your deliver command.** Into the open PowerPoint (`slidemind
-  push`), or a `.pptx` file (`slidemind build-pptx`) — or an HTML preview / a mix. Infer it when the
-  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 — 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. Three top-level sections in order — first `## Deliverable`, four lines:
-  ```
-  ## Deliverable
-  - shape: deck            # deck | slides
-  - body slides: 3         # the count the user asked for, body only
-  - frame: cover, closing  # the frame jobs this deck ships, or none
-  - target: file           # file | push
-  ```
-  (`slidemind plan` prints a `[plan:warn]` line for every disagreement between this block, the
-  storyboards' explicit roles and selected layouts — read them before the gate opens.) Then:
-  - `## Red thread` — one presentation **move** per **body** slide, as bullets or one arrow-separated
-    line, followed by one `Frame:` line naming the frame slides in play order (`Frame: cover ·
-    closing`, or `Frame: none`). The number of body moves MUST equal the number of body `### Slide N`
-    sections: use the agreed Deliverable body count, accounting for any explicit total limit or
-    individual frame-slide request. Never expand that agreed body count. Frame slides get their own `### Slide
-    N` sections in play order (cover = slide 1, closing = last, a divider directly before its
-    section). Use `"blocks": []` only when the layout has no authored content region; otherwise
-    sketch the required composition. Put the slot text in `contentNotes` and the story beat in
-    `keyMessage`. Name the *teaching function* of each slide — short verb+noun labels for what
-    the audience is doing cognitively at that step — never its content: no claims, facts, metrics,
-    client-specific terms, slide copy, generic section names, or wording copied from these
-    instructions.
-  - `## Per-slide storyboards` — one `### Slide N: <role>` subsection per slide, each a one-sentence
-    `Core message:` followed by **exactly one** fenced `storyboard-canvas` JSON block.
-
-  The `storyboard-canvas` is a **body-only spatial sketch**, not final slide design: it plans the
-  body region only and never the template title/header/footer/logo/slide-number areas. Blocks live
-  in a 1600 × 900 coordinate space, kept inside the body-safe area (roughly x 80–1520, y 110–780);
-  position, size, and proximity must express the slide's meaning — hierarchy, sequence, causality,
-  contrast, grouping, flow direction, or the main focus — not random placement. Each block shows
-  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. 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 —
-  and carries no design, layout, tone, or authoring-process instructions. It is the slide's full
-  content budget: the create stage and the concept-mockup generator build from `contentNotes` alone
-  and never add substance, so anything not in the notes will not be on the slide. Write them so the
-  slide body could be authored from them without inventing anything — every claim spelled out
-  concretely, with the numbers, named examples, or proof points that make it land. Two or three
-  abstract topic bullets ("X is expensive", "Y improves") is an unfinished draft, not a storyboard.
-
-  Judge whether two or more slides form a genuine visual series — for example a continuation,
-  progressive reveal, repeated comparison, phased journey, or recurring framework. When they do,
-  give those storyboard objects the same short, stable `visualFamily` identifier. Do not group
-  slides merely because they share a topic, and do not ask the user to make this design judgment. A
-  family tells concept generation to establish one recognizable visual system and adapt it to every
-  member's own `keyMessage`, `contentNotes`, role, and structure. It never permits copying another
-  slide's text, claims, data, or exact geometry, and it never permits dropping approved content to
-  fit the shared concept. Omit `visualFamily` for independent slides.
-
-  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 — 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,
-    "role": "body",
-    "layoutSelection": "automatic",
-    "slide": 1,
-    "layout": "<ComponentName from design.md's Layout Catalog>",
-    "blocks": [
-      {
-        "id": "main-visual",
-        "x": 420,
-        "y": 180,
-        "w": 680,
-        "h": 280,
-        "emphasis": "primary",
-        "designElement": "Hub-spoke visual",
-        "content": "Operating model"
-      }
-    ],
-    "keyMessage": "Shift the audience from thinking about AI tools to thinking about the operating model, so the rest of the deck has a reason to land.",
-    "contentNotes": [
-      "The operating model has five components: intake (requests land in one queue), tool use (agents draft with approved tools), validation (a human reviews before anything ships), escalation (edge cases route to a named owner), ownership (each workflow has one accountable lead).",
-      "Concrete example: contract review — intake via the legal inbox, agent drafts the redline, counsel validates in under 10 minutes vs. 2 hours manual.",
-      "Decision for the audience: which single workflow do we pilot this quarter — contract review or customer response drafting?"
-    ]
-  }
-  ```
-
-  Make the connection to the current deck explicit in the red thread, core messages, `keyMessage`,
-  or `contentNotes` whenever the work extends the open presentation, and fold in any content
-  findings from slides/files you inspected. Then run `slidemind plan <deck>`: it opens the plan as
-  **editable storyboards** — the user reorders/renames/inserts/removes slides on the red-thread
-  strip, drags/resizes/edits blocks and the content draft directly on each slide's canvas, and/or
-  leaves comments anchored to a slide or to the whole story — and it **blocks until the user
-  decides** — announce it per *Two UX rules* (browser opened? + the clickable gate URL) and give the
-  shell call a **generous timeout** (the gate waits up to 30 min; if your harness kills the call
-  early, just re-run it — the user's open tab reconnects). Outcomes: `DECISION: approved` → proceed
-  to author; `DECISION: comments` → apply the comments to `plan.md` — each is **slide-anchored** (`-
-  [Slide 3: "<beat>"] …`) or whole-story, and the batch may include a **generated story-iteration
-  instruction** (when the user restructured the red thread by adding or renaming slides, the gate
-  asks you to build storyboards and content for exactly those moves while keeping the other slides
-  intact) — (the round is persisted verbatim in `<deck>/plan-review.json` if your capture of the
-  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 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
-  prior gate round and unchanged since** counts as approved (skip straight to authoring); any new or
-  revised plan must pass the gate. When the gate reports the user edited `plan.md` directly, re-read
-  it — the edited storyboards **are** the approved plan; author from them.
-
-Keep planning about intent and content. The bundle is already materialized by `slidemind ready`, so
-`design.md` is there if you need to sanity-check feasibility — but **don't dive into
-brand/layout/composition detail until create/edit.**
+This skill is the **CLI half** of slidemind authoring: it maps the shared workflow onto `slidemind`
+commands and owns what only the CLI has. Read all of it — if your tool truncates its output, read
+the rest by line range. Everything else comes from the **design bundle** `slidemind ready`
+materializes, the same files the in-app design agent reads:
+
+- **The brand** — `design.md`, `corporate-design.css`, `layouts/` (tokens, type ramp, the closed
+  layout palette).
+- **The craft** — `workflow/flow.md` (stages, invariants, vocabulary), `plan.md` (the plan
+  contract), `create.md`, `edit.md`, `authoring.md`, `composition.md`, `layouts.md`,
+  `build-and-export.md`.
+
+Read them there; never restate a brand value or a craft rule from memory, and load no external
+design-taste plugins during slide work. **slidemind is a CLI you run directly**, like `git`. Every
+command takes `--help`; the deck commands take `--json`.
+
+## Stage todo list (create it before your first command)
+
+Create a todo list of these stages in your harness's task tracker before you run anything
+(`workflow/flow.md` → *track the stages*); mark each done as you finish it:
+
+1. **Ready** — `slidemind ready` (*Session start*).
+2. **Clarify** the content (*Intake → plan*). Never ask about the output: it is always a `.pptx`.
+3. **Plan sign-off** — write `plan.md`, run `slidemind plan <deck>`; every from-scratch request,
+   one slide included. Once approved, write each body slide's `content` draft into its storyboard
+   (`workflow/plan.md`); `concepts` refuses a body slide without one.
+4. **Concepts** — `slidemind concepts <deck>`, then Read every mockup PNG it lists. It always ends
+   on `CONCEPTS: <n>/<planned> <status>`; if your harness cut it off before that line, re-run it
+   (mockups on disk return at once). Only `CONCEPTS: 0/…` means there are none.
+5. **Transcribe** — `slidemind transcribe <deck>`: editable JSX, settled geometry, the requested
+   assets. It runs for minutes and ends on one `TRANSCRIBED` line — poll it, never interrupt it.
+6. **Compare and repair** each concept/draft pair in the JSX (*The create flow*).
+7. **Draft check** — `slidemind view-draft <deck>` until `DRAFT CHECK: no measured defects` (which
+   lines hold: `workflow/create.md` step 6) and each render makes its concept's argument, cleaner
+   than the painting.
+8. **Review gate** — `slidemind review <deck>` the moment the deck builds clean.
+9. **Deliver** — `slidemind build-pptx <deck>` (`push`/`publish` too only when the user's words
+   asked, *Intake → plan*; a deck connected to SharePoint publishes inside the build, *Remote
+   decks*). The concept comparison was the draft check's (`workflow/flow.md` stage 6), so the PNGs
+   it renders get no second one: they are where a `<Chart>` is judged (*Charts*). A build that ends
+   on `PACKAGE DEFECTS:` is not ready for the user (nor published): fix each, `view-draft --only`
+   it, build again. Say what landed (slide count + target) and stop: deliver is the last stage.
+
+**Changing slides that already exist** runs `ready` → edit → `view-draft` → deliver (*Editing slides
+that already exist*): no plan, no concepts, no review once the deck passed one or was adopted from
+the user's own `.pptx`. After that review `plan.md` is a record; updating it never re-opens the plan
+gate. New slides added to an existing deck run the full list, minus a review the deck already
+passed.
+
+The CLI enforces `workflow/flow.md`'s gate invariants: **no `slides/*.jsx` for new slides before the
+plan gate returned `DECISION: approved`** — no small-request exception — and **nothing delivered
+that `view-draft` has not checked**: `review`, `build-pptx` and `push` refuse a slide they would
+ship that was never checked, changed since its check, or still holds a measured defect. A deck you
+authored passes the review gate once, before its first delivery.
+
+## What to read, and resuming after a summarization
+
+`<bundle>` is `bundleDir` from `slidemind ready [deck] --json`; deck paths are under
+`decks/<slug>/.slidemind/`.
+
+| Stage | Read |
+|---|---|
+| after `ready` | `<bundle>/workflow/flow.md`, `<bundle>/design.md` |
+| plan + content drafts | `<bundle>/workflow/plan.md`, the layout catalog in `design.md`, `plan.md` |
+| concepts → repair | `<bundle>/workflow/create.md` (all of it), `corporate-design.css`, the `layouts/<Layout>.jsx` the plan names, `slides/*.jsx`, each `concepts/concept-slide-NN.png` at full detail; `workflow/authoring.md` for a `<Chart>` and for substrate, line/arrow or type-size repairs; `workflow/composition.md` + `layouts.md` for a slide with no mockup |
+| edit existing slides | `<bundle>/workflow/edit.md` + the affected `slides/*.jsx` (a structural rework adds the row above) |
+| reuse from an engine | the `slidemind-search` skill |
+
+A summary replaces what you only held in chat — viewed images, search results, the rules you read;
+files on disk survive. Running from a summary, after an interruption, or when the user just says
+"continue": run `slidemind ready <deck>` first. Its `stage:` and `next:` lines (`stage` in `--json`)
+name where the deck stands and the command or file due next — a waiting gate answer included.
+Re-read that stage's row and resume there. Never restart finished work, never skip the remaining
+stages, and never author, judge or deliver from a remembered image — reopen the PNG from its path.
+
+## Session start — `slidemind ready`
+
+`slidemind ready` (continuing a deck: `slidemind ready <deck>`) is the first command of every
+session: it checks the connection and CLI version, picks the corporate design, refreshes its bundle
+and, given a deck, binds it (`state/bundle-ref.json`).
+
+**Exit 0** → read `workflow/flow.md` and `design.md` from `bundleDir`. The JSON also carries
+`designs` (`{presFP, name, colors, current, cached, windows}`; `colors` = theme hexes
+`dk1`/`lt1`/`dk2`/`lt2`/`accent1..6`), `windows` (`{presId, title, fileName, presFP, paneReady}`),
+`engines.available`, `paneSuspended` and `windowless`.
+
+- **No PowerPoint window is the normal case** (`windowless: true`). Authoring, `view-draft`,
+  `review`, `build-pptx` and — with `engines.available` — engine search and download all run without
+  one. Only `push`'s insert, `insert-slide` and `read <presId>` need a live window; don't ask the
+  user to open, focus or click PowerPoint before one of those is next. `paneSuspended: true` is no
+  blocker: those commands wait (~2 min) and print one *click the slidemind pane* line when they need
+  help — relay it once and keep waiting.
+- **The design is the user's choice.** `ready` only picks a default (`--brand`, else the deck's
+  binding, else the one design live windows agree on, else the one cached, else the one the backend
+  lists). **When `designs` has more than one entry, ask before planning** — an open window is only
+  the suggestion. List each as `<name> — accent <accent1>, dark <dk1>, light <lt1>`, mark the
+  `current` one, name open windows by `title`/`fileName` (never an id), and apply the answer with
+  `slidemind ready [deck] --brand <presFP>` (and `slidemind new <slug> --brand <presFP>`).
+- **Microsoft 365 sign-in happens by itself:** the first engine command opens the browser, prints
+  `Microsoft 365 sign-in needed — opening your browser…` and blocks until the user finishes. Tell
+  them to complete it; don't kill or re-run the command.
+- **The bundle stays fresh by itself:** deck commands re-sync the bound design and print
+  `design bundle updated` when it moved (a render that meets `bundle_etag_stale` refreshes and
+  retries on its own) — then re-read `design.md` before authoring anything new.
+
+**Non-zero** → one blocker `{code, actor, message}` and one `nextAction`. Relay the `nextAction`.
+
+- `ambiguous_design` — ask as above from its `designs` menu (mention `suggested`: "this deck was
+  last built against X — continue with it?"), then `slidemind ready [deck] --brand <presFP>`.
+- `login_required` — corpus search and engine downloads wait until the user runs `slidemind login`;
+  keep authoring. When a slidemind pane is open, the CLI routes the search through it.
+- `not_connected` — the claim that carries the deployment's address is minted in the add-in. Ask
+  the user to open PowerPoint → slidemind → **Settings → General → Connect CLI**, press the **link
+  button**, then **Copy command** (**CLI already installed?** gives the short `slidemind setup …`
+  form), and paste it to you. Run it **verbatim** — it connects, installs, deploys the skills and
+  runs `ready` (`--no-install --for none` only when their install must stay untouched). A claim
+  works once for ~10 minutes; on *already used or expired*, ask for a fresh one.
+- `all_unreachable`, `cli_update_required`, `no_window`, `not_render_ready` — relay `nextAction`.
+
+**CLI missing:** `npm install -g slidemind` is the whole fix.
+`slidemind init --for <claude|codex|opencode|all>` only when this `SKILL.md` is not under a plugin
+cache (`~/.claude/plugins/…`, `~/.codex/plugins/…`) — there it would plant a second copy.
+`slidemind update` upgrades (`--ref <version>` pins), unless the CLI came from the plugin: then
+update the plugin.
+
+## The workspace and the gates
+
+The user answers in the **slidemind workspace**, a browser page that runs in the background. Never
+ask them to open a terminal or run anything. Asked to show it:
+`slidemind workspace [<deck>] --no-open --json`, then answer *Your slidemind workspace: <link>*.
+Never open a browser yourself.
+
+**How to run a gate.** `slidemind plan <deck>` (once `plan.md` is written) and
+`slidemind review <deck>` (once `view-draft` is clean) are the only ways to ask for a decision. A
+gate never waits.
+
+- **Asking:** it prints `ASK: <link>`, `SAY: <line>`, `DECISION: pending`. **End your turn with the
+  SAY line, word for word.** Don't wait, poll, sleep or re-run; don't author or deliver meanwhile.
+- **Receiving:** the user pastes a message naming the receiving command (*Plan approved. Continue:
+  `slidemind plan "<deck path>"`*). Run exactly that. `DECISION: approved` → do what `Next:` says.
+  `DECISION: comments` → change only what is asked, run the same gate again, end your turn with its
+  new SAY line (several rounds are normal). `DECISION: pending` → end your turn with its SAY line
+  again.
+- Approved, unchanged content answers `approved` at once; never ask the user to repeat an answer or
+  type a command.
+- `BLOCKED: workspace_sandboxed` → run it again outside the sandbox (Codex: escalated permissions).
+  `BLOCKED: deck_not_writable` → *Where the deck lives*. `BLOCKED: deck_unbound` → the
+  `slidemind ready <deck> --brand <presFP>` it names, with the design the user chose, then the gate
+  again.
+- An adopted deck's session must not hold the deck while the user answers:
+  `slidemind revision finish <deck>` before the gate, `revision begin` again after.
+
+**Add-in unreachable → stop and name the tab.** When `push`'s insert, `insert-slide` or
+`read <presId>` cannot reach the add-in, stop that step — no skipping, workaround or silent retry.
+Ask the user to go back to the PowerPoint tab of **<title or fileName>** (from the output or
+`slidemind ready --diagnose`), then re-run it. Work that needs no window continues.
+
+## Intake → plan
+
+`workflow/flow.md` stages 1–2; in-app a manager runs them, over the CLI you do, in chat.
+
+**Route by intent, never by slide count** (`workflow/flow.md` → *What scales*); ask only when it
+reads both ways, and run each part of a two-part request on its own route:
+
+- **Author something new** ("a slide about X", "add a closing slide") → the full stage list.
+- **Change slides that exist** ("make slide 4 stronger") → *Editing slides that already exist*.
+- **Reuse what exists** ("do we have a slide on X?", "drop in our pricing slide") → the
+  `slidemind-search` skill (`search` → `download-result` / `add-slide`); no plan, no concepts.
+
+**Clarify** what `workflow/flow.md` stage 1 lists (a content source included), plus the design when
+`ready` reported several. `slidemind read <file.pptx>`
+reads a local source host-free; for an existing target or reference deck,
+`slidemind read <presId|file.pptx> --mode summary --deck <deck>` before planning binds its layout
+usage (re-read when the target changes).
+
+**The output is always a `.pptx` — never ask about format, target or path.** `build-pptx` writes
+`decks/<slug>/<slug>.pptx` (`target: file` in `## Deliverable`). Only the user's own words add a
+destination: a SharePoint link (`…/:f:/…` folder, `…/:p:/…` file, `/sites/…/x.pptx`) adds
+`slidemind publish` (*Remote decks*) — a folder the user connects in the workspace needs nothing from
+you; "put it into my open presentation" adds `slidemind push`
+(`target: push`) — with several presentations open, confirm which one; after the review, push
+without asking. Delivering into that window again is `push --replace`, which replaces the whole
+presentation with the deck and refuses while it holds slides the deck does not own.
+
+**Write the plan and get sign-off — at every size.**
+
+1. `slidemind new <slug>` scaffolds `decks/<slug>/` and binds it to the design `ready` picked
+   (`--brand <presFP>` for the user's choice; if it cannot bind, it says to run `ready <slug>`).
+2. Write `decks/<slug>/.slidemind/plan.md` exactly per `<bundle>/workflow/plan.md`. The scaffold
+   text is a placeholder; one slide is the same document with one `### Slide N`. Images the user
+   gave you add `assetUses` (*Images the user gives you*).
+3. `slidemind plan <deck>`. The user sees one card per slide (beat, content points, layout), can
+   reorder, rename, insert and remove slides, and comments per slide or on the whole story.
+4. `DECISION: comments` → each is slide-anchored (`- [Slide 3: "<beat>"] …`) or whole-story; a
+   batch may carry a story-iteration instruction (build exactly the slides the user added or
+   renamed). Keep every slide no comment touches verbatim — the page's "updated" badges depend on
+   it. A cut-off round is in `state/plan-review.json`. When the decision says the user edited
+   `plan.md`, re-read it: that is the approved plan.
+5. `DECISION: approved` → write the `content` drafts, then `slidemind concepts`. Drafts don't
+   re-open the gate; changed key points or story go back through `slidemind plan`.
+
+## Images the user gives you
+
+A picture the user hands you is theirs, and only they know what it is for. Two records carry that:
+
+- **The bytes are an asset:** `slidemind assets import <deck> <file>` copies it in, identifies it
+  by digest and records it (`slidemind assets list <deck>`). File paths only, never URLs. Importing
+  creates **no** obligation to place it.
+- **The purpose is a use:** an `assetUses[]` entry on that slide's `storyboard-canvas`, approved at
+  the plan gate. One file may have several uses on several slides.
+
+**Import before you plan** — a use names the `assetId` the import prints. Infer the purpose from the
+user's words; ask once, only when it reads both ways (no role picker, no second approval). Each use
+has a `useId`, the `assetId`, a free-text `instruction` and a `fidelity`:
+
+| `fidelity` | Means |
+|---|---|
+| `original` | "place **this**": its saved bytes, visibly, once — with the use's `fit` (`contain` default; `cover` crops), `position`, and a `crop` only when asked for |
+| `reconstruct` | "rebuild **this**" as editable content: `reconstructionScope: "slide"` = blueprint for the whole slide (replaces the mockup, bypasses composition; at most one per slide), `"element"` = one fragment inside a larger composition |
+| `reference` | "look like **this**": guidance only |
+
+`slidemind concepts --concept <file>[@N,M]` (the sketch IS those slides' mockup) and
+`--style <file>[@N,M]` (it leads the look) import and record the use for you; a new use re-arms the
+plan gate.
+
+**`useId` and `assetId` are durable identity:** byte-identical in `plan.md`, the spec and the slide
+element through every repair, settle and re-render. Reordering changes no id; a duplicated slide
+needs **new** ids; never invent an id or move one onto other bytes; a derived version is a new
+import. How a use is authored (`<img data-asset-use="<useId>" src="./assets/local/<file>">`) and
+what each obligation owes: `<bundle>/workflow/create.md` → *Approved image uses*.
+
+**If you cannot reach the bytes** (the image is only in the chat), say so and ask for a path or a
+re-attachment — never screenshot, re-render, describe it to an image model, or pass off a
+look-alike.
+
+**No substitution, ever:** an `original` is its own bytes — never an engine result, a
+`slidemind imagen` look-alike, a recoloured, re-cropped or re-saved copy, or a similar file in the
+deck. Missing or changed bytes leave the use unresolved, and your report says so; restore or
+re-import the file and rebind the use. Imagery with no use is still sourced by search.
+
+Enforced: `concepts` refuses up front without add-in support (`image_intent_unsupported`; nothing
+changes), `transcribe` resolves originals from the registry, `view-draft` reports unresolved or
+unplaced uses, `build-pptx`/`push` refuse while one stands. None of that proves nothing is drawn
+over the picture: look at the draft pair.
 
 ## The create flow
 
-Every deck command (`view-draft`, `review`, `concepts`, `build-pptx`, `push`) re-syncs the deck's
-bound design before it runs, so a corporate design that changes mid-session is picked up by itself —
-it prints `design bundle updated` when that happens, and you re-read the bundle files it names. You
-never have to re-run `ready` to get a fresh design.
-
-`slidemind ready` already resolved the design source and materialized its bundle; the deck was bound
-to it by `slidemind ready <deck>` (continuing) or by `slidemind new <slug>`'s auto-bind (new work).
-From here:
-
-1. **Load create context, then inspect the concepts.** Read `workflow/create.md` (the procedure),
-   `workflow/authoring.md` (the portability contract — **required BEFORE the first slide write**,
-   never deferred to a lint repair: it names what CSS ports, the slide file shape, transforms,
-   rules and dividers, painted nesting, decorative layers, the Arrow contract), the deck's
-   `design.md`, `corporate-design.css`, and the specific `layouts/*.jsx` the plan uses. Nothing
-   else up front: `workflow/composition.md` and `workflow/layouts.md` are for slides WITHOUT a
-   mockup and for `[STYLE]` questions — open them when a lint message or a missing mockup sends
-   you there, not before (the read set is what `workflow/create.md` prescribes; `workflow/flow.md`
-   you already read after `ready`). The approved `plan.md` is a **content contract, not a rendering
-   spec** — you drew its storyboards yourself, but approval covered the story and content, not the
-   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 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 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. **The mockup is painted onto the layout's own chrome:
-   the title, section label, footer and page marks you see are chrome that travels through the
-   layout's props; everything else is the body and belongs in the layout's `[CONTENT]` slot**
-   (its geometry is in the layout's `PLACEHOLDERS` metadata). Note each region's share of that
-   area in percentages as you inspect. `slidemind concepts` seeded
-   `decks/<slug>/asset-plan.md` as a form with one section per slide (`regions:` / `organisms:` /
-   `connectors:` / `icons:`); **fill every row the moment you finish inspecting a
-   mockup, before any slide is written** — one bullet per region, per organism, per arrow or line
-   (`from → to, straight|elbow|curved, arrow end|both|none, solid|dashed`), per icon (subject,
-   prominence, one engine query). The draft check COUNTS these rows: connectors listed but not drawn,
-   an inventory left empty, and fetched assets no slide references each come back as an
-   `[inventory:warn]`. (If the form is missing — an older add-in — write it in that shape yourself.)
-
-   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. Append the fetched filename to each icon row
-   (`… — 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 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
-   adapt every member's element count, sizing, arrangement, labels, emphasis, and connections to its
-   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.
-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 — the download is the preview.** Pick from the `search`
-     output's titles/scores, `download-result` the picks (it prints each asset's size + recolor
-     info), 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. (`view-slide` is for
-     slide-library results only.)
-   - **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
-   `slidemind-search`'s `add-slide` — it folds the slide into `decks/<slug>/slides/` as a native
-   `.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`.
-3. **Frame slides from the plan.** A storyboard with `role: frame` gets no default concept mockup. Author its required text, images and composition according to its actual layout capabilities; source required assets even if the asset-plan section carries a frame marker. Covers go first, closing last, dividers before their sections. Run the normal fit and rendered checks.
-4. **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 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. **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: `slidemind view-draft` lints every slide before it renders, so fix every `[lint:warn]`
-   it prints (a mechanical pass on files you just wrote — `--fix` applies the deterministic ones);
-   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** — and
-   runs the captured slides through the server's export gate (slot-fit, diagram geometry,
-   connector endpoints) so the errors `build-pptx` would stop on surface HERE, before the review,
-   not as a 422 after the user approved (skipped with a note when the backend is unreachable;
-   `--lint-only` for a fast lint loop, `--json` for a payload whose `reviewCanOpen` says whether
-   the gate will open). Two things come back, and both bind:
-   - **Measured lines** under each slide — `[fill:warn]` (a stretched region whose organisms pool
-     at its top, with the region and the dead band) and `[inventory:warn]` (connectors listed in
-     `asset-plan.md` but not drawn — counted per route kind too, so five `curved` rows drawn as
-     elbows warn even when the total matches; an empty inventory, a fetched asset no slide
-     references) —
-     and a closing `DRAFT CHECK: N measured defects` line. Fix every one in the JSX and re-run;
-     the review gate refuses to open while they stand for an unchanged slide. A fill band is
-     fixed by distributing the organisms (`grid-template-rows` with one track per organism,
-     `justify-content: space-between`, a figure that grows), never by deleting content.
-   - **The pair**: for every concept-seeded slide, Read its anchored
-     `decks/<slug>/concepts/concept-slide-NN.png` and matching
-     `decks/<slug>/.draft-preview/<slide-basename>.png` **together in the same visual inspection**,
-     in batches of at most 3 pairs, and compare **region by region**: same organisms at the
-     same relative positions and shares, every connector present, no region emptier than in the
-     concept, nothing clipped, overlapping, or buried. A loop, a hub, a flywheel, a timeline in the
-     concept that became a row of cards in the render is a failed rebuild, not a simplification —
-     re-express the mechanism. Under the slide's section in `asset-plan.md` write `draft-check:` and
-     then one tick line per `organisms:` row: `- [x] <organism>` when it is in the render at the
-     concept's position and share, `- [ ] <organism> — <what differs>` when it is not. A bare
-     `matches` is not a verdict; the review gate refuses to open while any concept-seeded slide
-     has fewer ticks than organisms or a `[ ]` standing. A draft-only inspection does not satisfy
-     this check. The measured lines also include `[type:warn]` — most of the text one rung below
-     `--fs-body` next to free space; fix by raising the ramp, never by shrinking type to fit.
-   Fix anything wrong **in the JSX** (re-express, never delete), render again, and reopen the
-   affected concept/draft pairs until each slide matches its image and the measured line reads
-   zero. Do not open the review gate from a summary or a memory of an earlier look. It runs
-   locally against the materialized bundle, so it needs no awake pane and no open host once the
-   bundle has been downloaded once. Two faithful limits to know: a slide on a **purpose-built (Mode
-   A) layout** (cover/divider/agenda) and a **reused native `.pptx`** slide have no freeform region
-   to capture, so they come back as a status line, not an image — judge those at the full-deck
-   `review` step below. Do this self-check before the human review gate; don't push a draft
-   you haven't looked at.
-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
-   *opens* is a clean build; while lint errors remain it exits non-zero — fix and re-run), then
-   opens the browser with a spatial comment overlay and **blocks until the user decides** (host-free
-   — no open PowerPoint needed for the gate). Announce it per *Two UX rules*: tell the user the
-   browser opened and give the clickable gate URL. **Blocking is the point: give the shell call a
-   generous timeout (the gate waits up to 30 min) and let it sit — a long quiet wait means the user
-   is reviewing, not that something hung. Never cancel it; if your harness kills the call early,
-   just re-run it (the user's open tab reconnects).** The verdict prints to stdout:
-   - `DECISION: approved` → proceed to the deliver the user chose at intake: `slidemind push <deck>`
-     (into PowerPoint) or `slidemind build-pptx <deck>` (to a file).
-   - `DECISION: comments` → the user left spatially-anchored notes, each citing a
-     `slides/<file>.jsx:line:col`, the source line, the click position, and a **round tag** (`[2,
-     round 1] …`) — plus a readonly-layout note where the click landed on a layout slot. A pin
-     carrying an *older* round was dropped on the previous render, so read the file before you edit
-     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 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
-     (backgrounded command, clipped scrollback), read that file for the complete comment list; never
-     guess at missing comments or ask the user to re-type them.
-   - `DECISION: pending` → the gate timed out with no answer (the user stepped away). Not approval,
-     not rejection — **do not deliver**. Wrap up your turn: tell the user the preview is still
-     waiting for their review and that on their go-ahead you'll re-run `slidemind review <deck>`
-     (their tab reconnects).
-
-   `slidemind review` is the only step that pauses; `push`/`build-pptx` never pause — they render
-   pane-free (local capture + server-side assembly, with live per-slide progress). **CLI exports
-   happen out of the user's sight, so the flow invariant — *the user sees every change before the
-   task is done* — makes re-review mandatory here: every deliver is preceded by an approved review
-   of exactly what it delivers. After any later slide change, the deck re-enters `slidemind review`
-   before it can be pushed or exported again — never deliver an unreviewed change.** If several
-   presentations are open, confirm **which one to push into** first (it can differ from the design
-   source `slidemind ready` locked in). After approval, run the push without asking; it works while
-   PowerPoint is backgrounded, and the CLI itself waits + retries if the pane is needed (see *First
-   step* above). If a push still times out, the rendered `.pptx` is saved next to the deck — re-run
-   `push` after the user clicks the pane, without rebuilding.
-
-   **On a clean approve + deliver, the task is done.** Report what landed (slide count + target) and
-   stop — no sanity pass, no re-verification. The visual QA already happened at the draft check
-   (step 4) and the user signed off at the review gate.
-
-## Manual PowerPoint edits (the reconcile loop)
-
-The user may have edited the deck directly in PowerPoint since your last deliver — moved a shape,
-retyped a line, recoloured a box. Those edits live only in that file or that window; the deck's jsx
-knows nothing about them. `slidemind build-pptx` and `slidemind push --replace` therefore check
-before they write, and play the changes back to you:
-
-- **Plain text edits are already folded into your jsx** — the command prints `note: folded N manual
-  text edit(s) … into slides/<file>` and the fold is now the source of truth on disk. **Re-read that
-  file before your next edit** or you will write over it from a stale copy.
-- **Everything else refuses the deliver** with a `RECONCILE REQUIRED` report per slide (geometry in
-  EMU, style changes, added/removed shapes) and exit code non-zero. Nothing was written or pushed.
-
-On a `RECONCILE REQUIRED`:
-
-1. **Fold every listed change into the slide's jsx** — the user made them on purpose; losing them is
-   unacceptable. Translate geometry deltas into **layout intent** (spacing, order, relative sizing,
-   which region a thing sits in) — never literal offsets, absolute coordinates, or
-   transform/translate hacks bolted onto a working composition. Recreate added shapes as jsx
-   elements; drop deleted ones. If a folded position genuinely cannot fit the content area,
-   re-express its intent (reflow, reorder, resize) rather than discarding it.
-2. Lines marked `[preserved]` are foreign add-in content (e.g. an embedded chart) — do **not**
-   recreate them; they are spliced back into the rendered slide automatically.
-3. **Re-run the same command.** The re-run proceeds: the report was acknowledged
-   (`decks/<slug>/.reconcile-ack.json`), and only a NEW manual edit re-arms the check. The deck
-   changed, so the flow invariant applies — re-run `slidemind review <deck>` before delivering
-   again.
-4. **Do this silently.** Reconcile is bookkeeping, not a deliverable: never explain the report, the
-   baseline, or your folding steps, and never ask the user about it. Fold and carry on with their
-   actual request in the same turn. At most one short clause in your final answer ("kept your manual
-   layout change").
-
-`--force` on either command **discards the user's manual edits** and writes anyway. It is a last
-resort, only on the user's explicit say-so — never reach for it to get past a report you could fold.
-
-Three refusals are not foldable and need the user, not a retry:
-
-- `the live deck contains N slide(s) not in this deck` — a whole-deck replace would delete slides
-  someone added by hand or with another tool. Push **without** `--replace` to insert instead, or ask
-  the user what should happen to them.
-- `<file> was edited in PowerPoint …` naming slides with no jsx behind them (a reused native slide,
-  or one pushed by another deck) — build to a different target with `--out <other file>` so their
-  edits survive, or ask.
-- `backend does not support manual-edit reconcile` / `the live deck could not be inspected` — the
-  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
-download-result`). What follows is **create-only**: how to size and colour a fetched asset so it
-reads on-brand in your JSX, honoured in both the local draft preview and the render.
-
-Engine results land as files referenced with `<img src="./assets/<file>">`. These facts are specific
-to the local harness (the bundle's `workflow/*.md` stay harness-neutral):
-
-- **Size the box from the asset's own dimensions.** Both `slidemind search` (from the engine index,
-  before any fetch) and `slidemind download-result` (measured from the delivered bytes) print each
-  image's intrinsic `width×height`. **Use it.** A plain `<img>` is stretched to whatever box you
-  write, so a box whose aspect ratio disagrees with the asset ships a distorted picture. Derive one
-  side from your layout and compute the other from the printed ratio. `object-fit: contain`/`cover`
-  is honoured in the render as well as the preview, but it is a *fallback*, not a substitute: it
-  converts a wrong ratio into letterboxing or a crop, both of which you chose blind. When the size
-  prints as `(size unknown)`, the format carried no readable header — give the asset a square-ish
-  box and check it at the draft check.
-- **Never open the SVG to find out whether it recolours.** `slidemind download-result` prints a
-  `recolor` descriptor for each asset — `{ recolorable, mode, applied, note }`, where `mode` is
-  `currentColor`, `mono`, `multicolor`, or `raster`. Read it; that *is* the answer.
-- **Two ways to colour an icon, both honoured in the local draft preview *and* the render:**
-  - **Bake it in (prefer this):** pass `--icon-color <hex>` — a hex you resolve from a token in the
-    bundle's `corporate-design.css` — to `slidemind download-result`. Works for any `recolorable`
-    glyph and the colour is in the saved file, so preview and render always agree. The tint is
-    applied by the add-in, so on the window-free path it can be **refused**: the asset is then saved
-    in its original colours and the `recolor` note says so. Believe the note over your request — to
-    actually bake the colour in, re-run the search and the download with `--to <presId>` against an
-    open PowerPoint window.
-  - **Tint via CSS:** set `color` to a token on the `<img>`. This works only for `mode:
-    "currentColor"` icons (the preview inlines the SVG so `color` resolves, and the render
-    substitutes `currentColor`). A `mono` icon will not respond to CSS colour — bake it instead.
-- **Batch the fetch.** Pull every icon a slide needs in one call — `slidemind download-result
-  --search <id> --pick <n,n,…> --deck <deck> [--icon-color <hex,hex,…>]` (one colour applies to all
-  picks, or give one per pick; add `--to <presId>` only on an add-in that still relays the fetch
-  through a pane, which the `search` output names) — the downloads run concurrently. Don't run
-  `download-result` once per icon.
-
-## Command mapping (the workflow vocabulary ⇄ your CLI)
-
-The bundle's `workflow/*.md` speak the harness-neutral verbs defined in `workflow/flow.md` →
-Vocabulary. You are the local harness — this is your mapping:
-
-| Verb (`workflow/flow.md`) | Your equivalent (local harness) |
+The procedure is `<bundle>/workflow/create.md`; this is how its steps run over the CLI.
+
+1. **Concepts.** `slidemind concepts <deck>`: one mockup per body slide (frame slides none by
+   default); existing mockups are kept (`--force` remakes); `--status` says whether a run is in
+   progress — never start a second. The anchors are `concepts/concept-slide-NN.png` on disk, never
+   an image from earlier in the chat. No mockups (exit 0: the add-in can't make them) → author from
+   the storyboards; for new slides the attempt is never optional.
+2. **Transcribe.** `slidemind transcribe <deck>` reads each mockup's spec (a machine intermediate
+   in `state/concept-specs/` — never edit it, and keep no inventory of your own), writes the JSX on
+   the type ramp with native line directives, settles geometry and fetches the assets the specs
+   name. Read every note it prints: missing specs, unresolved assets, unreadable charts, layout
+   fallbacks. After `[specs:warning] NO CONCEPT SPECS` from `concepts` (`--json`:
+   `specsUnsupported`), `transcribe` refuses (`concept_specs_unsupported`) and re-running won't
+   help: build each named slide from its PNG by hand — count its cards, connectors, icons, bands and
+   numbers first, then build every one — and say in your handover that they were not transcribed.
+3. **Resolve the rest** (`create.md` steps 2–3): unresolved assets via `slidemind-search`, charts
+   checked against the approved data, frame slides from their plan.
+4. **Compare and repair** (`create.md` step 4 incl. its connector checklist, *Execute, don't
+   trace*, *Content checks*). Run `view-draft`, open each concept PNG with its
+   `preview/draft/<slide>.png` in one look, and patch the smallest wrong region of the JSX — the
+   only editable artifact. Geometry was settled by `transcribe`: fix what you see and draft again,
+   never re-settle in a create. Advisories never hold but each names a difference to check;
+   errors and measured package defects must be fixed (`create.md` step 6 lists both), and nothing
+   bypasses them. Draft-check the full deck before review. Your final message names the painting defects you corrected and any concept element you
+   could not build.
+5. **Review** — `slidemind review <deck>` the instant the deck builds clean, without asking. It
+   builds the HTML preview (non-zero while lint errors remain), refuses while measured defects
+   stand, then asks. Comments cite `slides/<file>.jsx:line:col`, the source line, the click and a
+   round (`[2, round 1] …`); a pin from an older round was dropped on the previous render, so read
+   the file before trusting its line. Edit the cited files in place, `view-draft --only` them (review
+   refuses a slide edited since its last draft check), then run `review` again. Every
+   round is saved in `state/review.json` — read it if your capture was cut off; never guess a
+   comment or ask for it again.
+
+**The review is one-time per deck** (`workflow/flow.md` → *Invariants*): edits, comments on the
+delivered deck, reconcile folds, repairs and new slides go `view-draft` → deliver, never back through
+`review` unless the user asks to see the preview. `build-pptx` and `push` never
+pause; a `push` that finds no window saves the rendered `.pptx` next to the deck (`fallbackFile`) —
+re-run it once the user clicked the pane, without rebuilding.
+
+**Repair (the explicit settle)** — only when the user asked to fix the spacing, overlap or fit of
+transcribed slides: `slidemind revision begin <deck> --operation repair --slides <sel>`,
+`slidemind transcribe <deck> --repair`, `view-draft --only NN`, then look at the whole slide
+(neighbours can move). The recorded scope authorizes it (a `targeted-edit` scope is refused) and it
+runs the whole scope — `--only` cannot carve a subset, so scope with `--slides`. It moves elements a
+few slot-px and changes no text, asset, element count or connector endpoint; it refuses converted
+source and slides with no transcription record, and needs no plan.
+`transcribe --force --discard-edits` throws edited source away — only for an intended reset.
+
+## Charts and engine imagery
+
+**Charts** are `<Chart>` elements (`workflow/authoring.md` → Charts; `workflow/composition.md` →
+Charts in the composition). Numbers the user states go straight into `data`; there is no analyst
+subagent, so a figure from the user's file comes from a script you run over that file, never from
+your head (`workflow/plan.md`): say what you computed and put the result in the props. The preview and `view-draft` paint a stand-in — judge a chart in the built file. An adopted
+chart keeps its `data-sm-source-id` and `conversions/<stem>.slide.pptx` (never delete either;
+delivery patches the client's chart through them). `slidemind read <presId> --mode raw` prints a
+live chart's data; `read <file.pptx>` gives text only.
+
+**Engine imagery** is found and fetched with the `slidemind-search` skill; sizing is
+`workflow/authoring.md` → Icons and imagery. Over the CLI:
+
+- `search` and `download-result` print each image's `width×height`; `(size unknown)` → a square-ish
+  `contain` box, checked at the draft check.
+- `download-result` prints a `recolor` descriptor per asset (`recolorable`, `mode` — one of
+  `currentColor`, `mono`, `multicolor`, `raster` — `applied`, `note`): read it, never the SVG.
+- Bake a colour in with `--icon-color <hex>` (a hex from a `corporate-design.css` token).
+  Window-free, the add-in may refuse the tint and the `note` says so — believe it; to bake it
+  anyway, re-run search and download with `--to <presId>` against an open window. CSS `color` on the
+  `<img>` tints only `mode: currentColor`.
+- Fetch a slide's picks in one call:
+  `download-result --search <id> --pick <n,n,…> --deck <deck> [--icon-color <hex,…>]` (one colour,
+  or one per pick); `--to <presId>` only when `search` says the fetch relays through a pane.
+- `slidemind imagen "<prompt>" --deck <deck> [--out <name.png>] [--size <size>] [--quality <tier>]`
+  only for a planned photograph or illustration no engine could supply — never a pictogram, never
+  in place of the user's image.
+
+## Editing slides that already exist
+
+The rules — operations, editable slides, converted source, identity — are
+`<bundle>/workflow/edit.md`. Over the CLI:
+
+1. **Name the slide by its file, never its position.** Slides are `slides/*.jsx` in filename order;
+   resolve "slide 4" to its file once. `--slides <sel>` takes a stem (`04-pricing`), number or range
+   and binds the durable id at once, so a reorder cannot move your scope.
+2. **Make it JSX first**, only for slides the user asked to change and before `revision begin`: a
+   foreign `.pptx` slide via `slidemind adopt <file.pptx> --deck <deck> --slides <n>`; a reused
+   `slides/NN-reused-*.pptx` via `slidemind adopt <deck>/.slidemind/slides/<NN-reused-…>.pptx --in-place`.
+   Slides you never name stay native, with notes, comments, animations and embeddings.
+3. **Open the operation** (`edit.md` → *What the request authorizes*):
+   `slidemind revision begin <deck> --operation targeted-edit|redesign|repair --slides <sel> --json`
+   (`--operation` always needs `--slides`). A requested redesign is authorized — don't ask again. A
+   removal the user asked for goes in `--scope <file.json>` (the elements and properties the edit
+   may touch). Changing a slide outside the scope (a `-2.jsx` sibling included) or dropping an
+   import's `// SLIDEMIND_DIALECT: converted` line outside a redesign is refused by the next
+   `view-draft`, `build-pptx` or `push`: undo it and change the target itself.
+4. **Re-read `slides/<file>.jsx` from disk, then patch it** — a manual edit may have been folded
+   in. Adding and restructuring supported content is allowed, not only words.
+5. **`view-draft --only <n>`, then deliver** onto the same slide (`build-pptx` re-renders only what
+   changed). No review gate, no confirmation question of your own.
+
+**Preservation.** Every slide records the elements that must survive it — from its first
+`view-draft` on, or earlier when `adopt`, `revision begin` or a repair captured it; it applies
+without anyone opening a session.
+`view-draft` prints `[preserve:warn] <slide> — <element id> …` with the repair — a measured
+defect, so `review`, `build-pptx` and `push` refuse while it stands. `[preserve:error]` means
+the record itself cannot be read: delivery refuses, and the file is not yours to edit — tell the user.
+What no draft can answer is settled at delivery: it refuses only on a slide that can be proved (an
+adopted one whose import the deck holds); a slide authored from scratch ships with that limitation
+named. Fix what a warn names; never delete a record or rebuild a slide to quiet a line, and never present the add-in as a
+way around a CLI refusal.
+
+**Limits to state, not work around:** a preserved native object (SmartArt, OLE, an unmodelled chart)
+moves but can't be edited inside. `export_incomplete` means the pane could only hand back the saved
+file: ask the user to **save the presentation** and re-run (`--force` discards their manual edits —
+only if they say those don't matter).
+
+**An adopted deck** (`slidemind adopt` of the user's own `.pptx`) needs no plan and no review; its
+edits run in a session, because its base is a real file:
+
+1. `slidemind revision begin <deck>` once, then `export SLIDEMIND_OWNER=<printed token>` so nested
+   commands and parallel lanes re-enter it. `adopt … --slides <n,m>` hydrates more slides on demand.
+2. Edit, `view-draft`, then `build-pptx`: it writes an immutable **candidate** of the changed
+   slides on the accepted base — building twice keeps the first edit.
+3. `slidemind revision accept <deck> --candidate <id>` makes it the accepted base, locally and
+   nothing more (a remote deck publishes instead). `slidemind revision finish <deck>` ends the
+   session.
+
+`slidemind revision status <deck>` answers "where am I?". A **newer copy of the same file**:
+`slidemind rebase <deck> --incoming <file.pptx> --dry-run` first. Their edits, adds, deletes and
+moves apply, reorders combine, your unpublished edits stay; only a slide both sides changed stops
+and writes a resolution file for the user. There is no force flag.
+
+## Remote decks (SharePoint)
+
+The user never pulls, publishes or uploads by hand: a deck that touches SharePoint is delivered *to*
+SharePoint, never as a local path. Any one signal makes it remote:
+
+- a **file link** (`…/:p:/…`, `/sites/…/name.pptx`) → the deck IS that file:
+  `slidemind open <link> --deck <deck>` instead of `adopt` (a local path given to `open` adopts
+  only).
+- a **folder link** (`…/:f:/…`) → the normal create flow, then `build-pptx` and
+  `slidemind publish <deck> --folder <link> --name <file>.pptx` (`<slug>.pptx` unless the user named
+  one — never ask). An existing name is refused; pick another.
+- a **folder the user connected in the workspace** — any time, mid-build included. You need not
+  know: every `build-pptx` reads the deck's connection itself.
+- `slidemind ready <deck>` prints a `remote:` line, or `build-pptx` prints a publish outcome.
+
+**`build-pptx` publishes a connected deck itself**, right after the build, as `slidemind publish`
+would: it pulls, reconciles, checks the final bytes and creates or replaces the file only if nobody
+saved meanwhile (`revision accept` refuses a bound deck on purpose). Never follow it with a second
+`publish`; `slidemind publish <deck>` only retries a build whose publish did not save (exit 2).
+
+Every session, unprompted:
+
+1. `slidemind pull <deck>` before the first edit and after every pause (a gate, a summarization, a
+   new message). Newer saves merge in around your unpublished edits — read its `note:` lines and go
+   on. Only a slide you both changed stops it: show the user both versions (theirs staged, yours in
+   your working file), ask which to keep or what to combine, run the `slidemind rebase` it names,
+   fill the resolution file (`local`, `incoming`, or `merged` + your slide file) and re-run with
+   `--resolve`.
+2. `slidemind revision begin <deck>`, edit, `view-draft` — no review gate.
+3. `build-pptx` — it publishes; read its outcome as below.
+4. `needs_reconcile` is no error: rebuild — it publishes again (slides changed on both sides: settle
+   with the user first, as in step 1). Loop until `SAVED` — unless it says their save could not be
+   taken in (a missing pinned file, a failed check): tell the user what it names and stop.
+5. `slidemind revision finish <deck>`; hand over the SharePoint file (`webUrl` from `ready`).
+   `slidemind rename <deck> --name <file.pptx>` renames it without rendering.
+
+Report publish literally, never upward: `SAVED` → in SharePoint, with the version it names;
+`needs_reconcile` → someone saved first, nothing was overwritten, their changes are merged (or a
+both-sides slide awaits their choice) and you rebuild; `pendingManualUpload` → **nothing was
+written**, the files to upload by hand are listed; `UNKNOWN` → re-run publish, which inspects before
+it writes; `not published (<reason>)` or `built, but not published` → nothing was uploaded, tell the
+user why (the `.pptx` is local only). Never re-run a
+publish to "make sure", and never offer to force, skip a gate or work around a missing extension.
+
+## Manual PowerPoint edits (reconcile)
+
+`build-pptx` and `push --replace` check for edits the user made in PowerPoint since the last
+delivery; how to fold them (layout intent, `[preserved]` lines, silently) is
+`<bundle>/workflow/edit.md` → *Manual-edit reconcile*. Over the CLI:
+
+- `note: folded N manual edit(s) (text, charts) … into slides/<file>` — already in your JSX;
+  re-read that file before the next edit.
+- `RECONCILE REQUIRED` (non-zero; nothing written) lists geometry in EMU, style and added/removed
+  shapes per slide: fold each into the JSX and re-run the same command. It then proceeds
+  (`state/reconcile-ack.json`; only a new manual edit re-arms it), with no new review.
+- `--force` discards the user's manual edits — only on their explicit say-so, never past a report
+  you could fold.
+
+Four refusals need the user, not a retry: `the live deck contains N slide(s) not in this deck` →
+push **without** `--replace`, or ask; `<file> was edited in PowerPoint …` for slides with no JSX
+behind them → build with `--out <other file>`, or ask;
+`backend does not support manual-edit reconcile` / `the live deck could not be inspected` → ask the
+user to update the slidemind add-in, never `--force`; `converted slide(s) are not confirmed for
+replacement` → name those slides to the user and add `--accept-conversions` only after they agree
+(it overwrites their originals), or push without `--replace`.
+
+## Command mapping (workflow vocabulary ⇄ CLI)
+
+The bundle's `workflow/*.md` speak the verbs of `workflow/flow.md` → Vocabulary:
+
+| Verb | Command |
 |---|---|
-| (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 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 |
-| **draft check** | `slidemind view-draft <deck>` — lints every slide (fix each `[lint:warn]`; `--fix` applies the deterministic ones), then renders each `slides/*.jsx` to `decks/<slug>/.draft-preview/<slide-basename>.png` (clean, no overlays), prints the measured defects (`[fill:warn]`, `[inventory:warn]`, closing `DRAFT CHECK:` line) 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 until the measured count is zero and the pairs match. A draft-only inspection does not count; `slidemind review` refuses to open while measured defects stand for an unchanged slide. 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); 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
-layout discovery and slot/working-area rules, the visual quality bar (applied at the draft check) —
-applies to you unchanged.
-
-## The brand and the workflow both live in the bundle, not here
-
-Do not restate brand values (colour, type scale, spacing, layout names, accent discipline) or
-re-derive the authoring/composition craft in this file or in slide files — they are in the bundle's
-`design.md` and `workflow/*.md`. Read them and follow them. Don't load external UI/design-taste
-plugins during slide work; compose against the bundle's layouts and tokens. If the corporate design
-moves mid-task (`bundle_etag_stale`), the CLI self-heals: it refreshes the bundle and retries the
-render on its own — afterwards re-read the bundle's `design.md` before authoring anything new, since
-the rules may have changed.
-
-## Failure modes the render lint can't catch
-
-Render-time lint rejects contract violations (unsupported CSS, bad imports, remote `<img>` URLs —
-the add-in's capability-table engine; `slidemind view-draft` runs the same engine locally from the
-bundle before it renders). It can't catch content-shaped failures; check for these **at the draft check** (step 4,
-before the review gate) — not after delivery:
-
-- Layout-default / placeholder text leaking through an unfilled prop.
-- A bullet list standing in for a structured idea (process, comparison, timeline).
-- An equal-card grid with no hero and no hierarchy.
-- Em dashes / curly quotes leaking from pasted source.
-- Hand-rolled glyphs instead of engine imagery.
-- Slide-local class names colliding with global token utility classes.
-- Internal composition vocabulary (`hero`, `focal`, …) rendered as visible text.
+| (session setup, CLI-only) | `slidemind ready [deck]` — first, every session (it covers `download-bundle`) |
+| **track the stages** | your harness's task tracker (*Stage todo list*) |
+| **clarify** / **plan sign-off** | chat, `plan.md`, `slidemind plan <deck>` (*Intake → plan*) |
+| concept mockups + preparation | `slidemind concepts <deck>` → `slidemind transcribe <deck>` |
+| **read** / **list** the workspace | the files under `<bundle>/` and `decks/<slug>/.slidemind/` |
+| **create / update a slide file** | write `decks/<slug>/.slidemind/slides/NN-<topic>.jsx`, zero-padded (`01-cover.jsx`, …). Play order is numeric filename order — no ordered-list channel, so reordering means renaming. For a concept-seeded create or structural rewrite, Read the concept PNG at full detail right before the write |
+| **draft check** | `slidemind view-draft <deck> [--only NN]` — lint (errors block; deterministic fixes run), render to `preview/draft/`, the measured defects, the closing `DRAFT CHECK:` line. No push, no `.pptx`. Layout-only and reused native slides report a status line — judge those in the build |
+| **the review gate** | `slidemind review <deck>` (*The create flow*, step 5) |
+| **build & push** | `slidemind build-pptx <deck> [--out <file>]` always (it publishes a SharePoint-connected deck itself); `slidemind push <deck>` / `slidemind publish <deck>` only when asked for |
+| **inspect the deck** | `slidemind read <presId\|file.pptx> [--mode summary\|raw]` — a presId reads the open (unsaved) presentation and needs its window; a saved file reads host-free (prefer it) |
+| **discover image engines** | `slidemind ls engines [--type …] [--subtype image\|slide\|…]` — pick an `id` from it, never guess |
+| **engine search / fetch** | the `slidemind-search` skill; placement per *Charts and engine imagery* |
+| **generate an image** | `slidemind imagen` (*Charts and engine imagery*) |
+| **see** a live slide | open that slide's PNG in the directory `build-pptx` prints (its line says whether the PNGs show the exported `.pptx` or the browser source) |
 
 ## Where the deck lives
 
-`decks/<slug>/` is created in the **current working directory** (the shell's pwd when the skill was
-invoked). Every `slidemind` command and `mkdir` resolves `decks/` against that cwd — don't `cd` into
-the skill's install directory. The materialized bundle lives in the cache dir above, not under the
-deck.
+`decks/<slug>/` is created in the current working directory; every command resolves `decks/` there —
+don't `cd` into the skill's folder. **A path the user names is input, never the deck folder:** read
+a briefing, RFP or reference deck where it is and copy what the deck needs into
+`.slidemind/assets/`. Your sandbox writes only under your working folder; work on a deck elsewhere
+only when the user explicitly asks (expect permission prompts).
+
+```
+decks/<slug>/
+  <slug>.pptx      the built deck
+  plan.html        the saved plan page (read-only; `slidemind plan <deck>` opens it to edit)
+  .slidemind/      plan.md · slides/ assets/ conversions/ (what the render reads) · concepts/ ·
+                   state/ (bundle-ref, plan-review, review, draft-check, reconcile-ack, concept-specs/) ·
+                   preview/ (regenerable)
+```
+
+Commands take the deck **directory**; a deck without `.slidemind/` is used as it stands. Write
+nothing at the deck root. `slidemind clean <slug>` drops only `preview/` and abandoned downloads.
+`plan.html` has one owner (`state/plan-owner.json`): this flow re-renders it on every `plan.md`
+write; on a deck an extension owns, `slidemind plan` leaves it alone and prints the command that
+opens it — never hand-write it. The bundle lives in the cache
+(`${XDG_CACHE_HOME:-~/.cache}/slidemind/bundles/<presFP>/`), not the deck; read
+`assets/brand-images.md` from there when a workflow doc names it.