slidemind 0.3.13 → 0.3.14

package/package.json

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

package/skills/create-slides/SKILL.md

@@ -43,30 +43,29 @@ later stages (above all the review gate) from being skipped. The stages, as they
    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 FILES ON DISK are the
-   truth, not the command output you saw.** Generation takes 1–2 minutes and your harness may
-   time the command out, showing you only progress lines while the detached process finishes
-   writing the PNGs — output that ends mid-progress means TIMED OUT, never "no mockups". The
-   moment the command returns (complete or cut off): run `ls decks/<slug>/concepts/`. PNGs
-   listed → re-run `slidemind concepts <deck>` once (it returns the full path list instantly for
-   already-generated mockups) and Read every file. **Claiming the concepts are missing requires
-   double evidence**: `asset-plan.md` may say "no mockups" ONLY when BOTH the re-run's output
-   printed zero paths AND `ls decks/<slug>/concepts/` is empty — quote both in the file.
-   Authoring a concept-seeded deck without having Read the concept PNGs that exist on disk is the
-   single largest fidelity failure this workflow has; nothing about a truncated stdout excuses it.
+   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 — write `decks/<slug>/asset-plan.md` from the concepts, then search + download
-   every item in it (*The create flow* steps 2–3). **This stage is not optional and not mergeable
+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`
-8. Review gate — `slidemind review`, the moment the deck builds clean
+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
@@ -115,22 +114,28 @@ Two gate invariants you must never break — one per gate, equally binding:
 
 ## After a context summarization (compaction recovery)
 
-Long deck runs can exceed the context window mid-task; the harness then replaces the transcript
-with a summary. **Everything you only held in chat — viewed concept images, search results, the
-asset inventory, workflow rules you read from the bundle — is gone; the files on disk are not.**
-When you notice you are running from a summary (or after any interruption/continuation), do NOT
-improvise from the summary and do NOT restart finished work. Recover state from disk, in this
-order, then resume at the first incomplete stage:
-
-1. `decks/<slug>/plan.md` — the approved story.
-2. `decks/<slug>/asset-plan.md` — per-slide organisms + which assets are downloaded vs. missing
-   (unchecked items still need their search + fetch).
-3. `ls decks/<slug>/slides/ decks/<slug>/assets/ decks/<slug>/concepts/` — what already exists.
-4. Re-read `<bundle>/workflow/create.md` if you are still before or inside authoring, and reopen
-   the concept PNGs for the slides not yet authored (batches of ≤3) before writing them.
-
-The stage todo list still binds after a summary: a summary that says the deck is "mostly done" is
-never a reason to skip the remaining stages (assets, draft check, review gate).
+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)
 
@@ -148,6 +153,8 @@ binds the deck to it.
 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
@@ -302,7 +309,7 @@ next to the deck (`paneSuspended` + `fallbackFile` in the result) — nothing is
 once a window exists. Reserve the full "open PowerPoint…" instruction for when a command actually
 reports it as the blocker.
 
-`slidemind build`, `review`, and `view-draft` run offline, but only against a **previously
+`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
@@ -319,7 +326,7 @@ with PowerPoint closed.
   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 presentations`
+  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.
 
@@ -497,16 +504,24 @@ brand/layout/composition detail until create/edit.**
 
 ## 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 the create-stage references together —
-   `workflow/create.md` (the procedure), `workflow/composition.md` (the composition baseline),
-   `workflow/layouts.md` (palette + working area), and `workflow/authoring.md` (the substrate rules)
-   — plus the deck's `design.md` and the specific `layouts/*.jsx` the plan uses. (That is the read
-   set `workflow/create.md` → Context loading prescribes; follow it as written — `workflow/flow.md`
-   you already read after `ready`.) The approved `plan.md` is a **content contract, not a rendering
+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)
@@ -519,22 +534,24 @@ From here:
    search.** First list the directory and keep the literal repo-relative mapping in the task context:
    concept `NN` maps to `decks/<slug>/concepts/concept-slide-NN.png` and later to the `NN-*.jsx`
    slide. These workspace files are the durable source of truth across turns and compaction — never
-   rely on an earlier rendered attachment. Inventory what each mockup requires — imagery, distinct
-   pictograms, factual/content verification, annotations, and other visible organisms — and
-   **persist the inventory to disk the moment you finish it: write `decks/<slug>/asset-plan.md`**,
-   one section per slide:
-
-   ```
-   ## Slide NN — <title>
-   organisms: <the mockup's regions, hero figure, badges, satellites, chips, connectors>
-   - [ ] icon: <what it depicts> — query: "<search query>"
-   - [ ] image: <what it shows> — query: "<search query>"
-   ```
+   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. Check items off (`- [x] … — assets/engine-<id>-<n>.svg`)
-   as downloads land, so the file always shows what is still missing. This first pass is
+   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
@@ -559,12 +576,11 @@ From here:
    is discovery, not sourcing: this step is done only when every `asset-plan.md` item is checked
    off with a downloaded filename or marked `(no result)` after its search actually ran. Four
    mechanics that waste rounds when gotten wrong:
-   - **Icon results have no preview.** `slidemind view-slide` serves slide-library results only —
-     on an image/icon search it answers "no image returned" every time, so never call it there and
-     never retry it. Pick from the `search` output's titles/scores; a download is cheap and
-     `download-result` prints each asset's size + recolor info — download first, judge from the
-     saved file, re-search once if it was wrong. At most two search rounds per need; two failed
-     downloads = mark it `(no result)` and move on.
+   - **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
@@ -598,23 +614,46 @@ From here:
 4. **Look at your own draft first (you, the agent).** This is the **draft check** in
    `workflow/build-and-export.md` — your pre-check, *before* any human sees the deck. Two rules
    moved early on purpose — do them NOW, not at the review gate when the run is long and attention
-   is spent: first run `slidemind build <deck>` once and fix every `[lint:warn]` it prints (a
-   mechanical pass on files you just wrote); and after any fix round below, one more `slidemind
+   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**. 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. Diff each pair organism by organism; a draft-only inspection does not
-   satisfy this check. Fix anything visibly wrong **in the JSX** (re-express, never delete), render
-   again, and reopen the affected anchored concept/draft pairs until each slide is sound. One round
-   usually suffices. It runs
+   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, 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`/`build` step below. Do this self-check before the human review gate; don't push a draft
+   `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
@@ -740,7 +779,7 @@ data table per chart; `slidemind read <file.pptx>` (host-free) reports text only
 
 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 `slidemind build` preview and the render.
+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):
@@ -757,7 +796,7 @@ to the local harness (the bundle's `workflow/*.md` stay harness-neutral):
 - **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 `slidemind build` preview *and* the render:**
+- **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
@@ -787,7 +826,7 @@ Vocabulary. You are the local harness — this is your mapping:
 | 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>` — renders each `slides/*.jsx` to `decks/<slug>/.draft-preview/<slide-basename>.png` and returns the images to **you**; **no push, no `.pptx`, no review gate**. Read each concept/draft path pair together, fix the JSX, render, and pair again. A draft-only inspection does not count. Host-free once the bundle is materialized. Freeform slides only — purpose-built (Mode A) and reused native `.pptx` slides report as a status line (judge those at `review`/`build`). This is your self-check; `slidemind review` is the *human* gate |
+| **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 |
@@ -813,8 +852,8 @@ 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 build` runs the same engine locally from the
-bundle). It can't catch content-shaped failures; check for these **at the draft check** (step 4,
+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.

package/skills/search/SKILL.md

@@ -96,8 +96,8 @@ commands then carry its `--to`), and a command that can't be re-routed tells you
 **Add-in unreachable → block and name the tab.** When a host-required command can't reach the add-in
 (a connection blocker, a pane that never wakes, the *click the slidemind pane* line with no effect),
 **stop** — 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
-presentations` — never a raw id), then re-run the failed command once they have.
+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.
 
 ## Discover → search → pick → reuse
 
@@ -145,11 +145,12 @@ Follow `workflow/search.md` for the discipline; this is the CLI shape of its loo
    path, Read that ONE file — every candidate is on it with its selection number burned in. With no
    contact sheet, previews depend on the result type: **slide-library results** support `slidemind
    view-slide --search <searchId> --pick <n>` (writes one result's preview to a file you can Read);
-   **image/icon results have NO preview on this path** — `view-slide` answers "no image returned"
-   for them, so never call it on an image search, and never retry it hoping for a different answer.
+   **image/icon results have NO preview on this path** (the search says so itself) — `view-slide`
+   answers "no image returned" for them, so never call it on an image search.
    For icons, pick by title + score, `download-result` the pick (downloads are cheap), Read the
    saved file, and re-search once if it was wrong — two failed downloads for the same need means
-   mark it unresolved and move on. Pick by **selection number(s)**.
+   mark it unresolved and move on. Pick by **selection number(s)**, and **cite the sources** (see
+   the rule below) whenever you report results back.
 5. **Read the source deck when the story matters.** A found slide came out of a real presentation,
    and often the answer the user needs is in the *rest* of it — how the slide was framed, what came
    before and after, whether that deck already covers more of the ask. `slidemind read-source
@@ -160,6 +161,14 @@ Follow `workflow/search.md` for the discipline; this is the CLI shape of its loo
    deck — image and collection results do not.
 6. **Reuse.** Insert live or fold into a deck — see the next section.
 
+> **Always provide sources.** Every time you report search results to the user — a shortlist, a
+> single pick, a "found it / didn't find it" answer — list, per result, the **presentation it came
+> from** (its title and slide number as printed) and its **link** when the CLI printed a `source:`
+> line (`sourceUrl` in `--json`; SharePoint-indexed results carry the file's browser URL). The user
+> must be able to open the original presentation without asking you for it. A result printed
+> without a `source:` line has no link on record — say so; **never invent, guess, or reconstruct a
+> URL**. This is not optional and does not depend on whether the user asked for sources.
+
 ## Reuse targets — insert live, or fold into a deck
 
 A found slide can be reused two ways. Both extract the picked result(s) as native PowerPoint slides
@@ -168,7 +177,7 @@ A found slide can be reused two ways. Both extract the picked result(s) as nativ
 - **Insert LIVE into an open PowerPoint** — `slidemind insert-slide --search <searchId> --pick
   <n[,n,…]> --to <presId> [--at <N>]`. **This is the one host-required step:** the picked slides
   land in that open window (at position `--at`, else appended), so PowerPoint must be open with the
-  slidemind pane. Name the target window from `slidemind presentations` (or, on the relayed path,
+  slidemind pane. Name the target window from `slidemind ready --diagnose` (or, on the relayed path,
   use the window the search ran on). A window that reconnects mid-run gets a **new** id; the CLI
   re-finds it and retries once by itself, so a stale id is not your problem. If it still reports the
   pane asleep, **don't loop** — relay its line, or fold the same pick into a deck (below) and push
@@ -239,7 +248,7 @@ insert live, fold into a deck, engine fetch). You are the local harness — this
 | Verb (`workflow/search.md`) | Your equivalent (local harness) |
 |---|---|
 | **discover engines** ("list what you can reach") | `slidemind ls engines [--type collection\|search\|scope] [--subtype …]` — returns the engine catalog **plus the search scopes** (pick an `id`; never guess one). The catalog is backend/user-scoped; `--to` is accepted but never needed. No window needed where the add-in serves the pane-free routes. |
-| **engine search** (with `intent`) | `slidemind search "<query>" --engine <id> --intent <auto\|content\|visual> [--top N] [--deck <deck>]` — leave `--to` off → a `searchId` + numbered results, plus the exact follow-up commands for the path it took (`--deck` routes by that deck's design when several environments are connected) |
+| **engine search** (with `intent`) | `slidemind search "<query>" --engine <id> --intent <auto\|content\|visual> [--top N] [--deck <deck>]` — leave `--to` off → a `searchId` + numbered results, plus the exact follow-up commands for the path it took (`--deck` routes by that deck's design when several environments are connected); each result may carry a `source:` link — **always cite it back** |
 | **search a scope** (unfiltered corpus, no engine) | `slidemind search "<query>" --engine <scope:all\|scope:sharepoint> --result-type <slide\|image> [--intent …]` — `--result-type` is required for a scope (defaults to `slide`). Results reuse identically to engine results. |
 | **pull an on-demand thumbnail** for a stored result | `slidemind view-slide --search <searchId> --pick <n>` — SLIDE-library results only; image/icon results have no preview ("no image returned") — download and Read the file instead (add `--to <searchWindow>` only on the relayed path) · or `slidemind search … --json` for the structured payload. |
 | **read a result's SOURCE deck** (the presentation it came from) | `slidemind read-source --search <searchId> --pick <n> [--from-slide N] [--to-slide N] [--out <file.md>]` — Markdown of the whole source presentation, one section per slide (add `--to <searchWindow>` only on the relayed path). Indexed text, not the live file. Slide results only. |
@@ -259,6 +268,15 @@ from `slidemind ls engines` (live discovery — the bundle carries no engine lis
 search/reuse craft is in `workflow/search.md`. Read them and follow them. If the corporate design
 moves mid-task, re-list engines before searching again, since the catalog may have changed.
 
+**Where the bundle is, and what to do when there isn't one.** Searching itself needs no bundle, but
+`workflow/search.md` lives in one, so a machine that has never materialized a design has nothing to
+read. `slidemind ready --json` prints the materialized bundle's directory as `bundleDir` (run it
+once — it resolves the design and materializes it); for a deck you are reusing into,
+`slidemind ready <deck> --json` uses that deck's own binding. When several designs are at hand and
+nothing says which, `slidemind ls designs` lists every one (cached here and listed by the add-in)
+so the user can choose, and `slidemind download-bundle --brand <presFP>` materializes it without a
+PowerPoint window.
+
 `workflow/search.md` also owns the judgement this skill deliberately does **not** restate: what an
 engine actually is (a saved filter over a shared corpus, not a library of its own), when to reach
 for a scope instead, and why zero results are not evidence that the content doesn't exist. Read it

package/src/bridge/build-and-push.mjs

@@ -33,6 +33,7 @@ import {
   materializeBundle,
   readDeckBundleRef,
   resolveBundleDirForDeck,
+  resolveWindowlessBrand,
   writeDeckBundleRef,
 } from "./bundle.mjs";
 import { bundleHasCaptureEngine, captureDeckLocally } from "./capture.mjs";
@@ -471,7 +472,10 @@ function mapCapturedSlide(fileName, cap, warnings) {
   for (const w of cap.render?.warnings ?? []) warnings.push(`${fileName}: ${w}`);
 
   if (cap.previewDataUrl) {
-    return { fileName, status: "ok", dataUri: cap.previewDataUrl };
+    // The serialised boxes ride along so view-draft can run the measured
+    // checks (fill band, content grid) the add-in's see_draft runs.
+    const { root = null, stage = null, boxes = null } = cap.render ?? {};
+    return { fileName, status: "ok", dataUri: cap.previewDataUrl, render: { root, stage, boxes } };
   }
   // A degraded render is a non-editable raster; push/build-pptx will REJECT it.
   // Attach it anyway (so the agent isn't blind) but flag the named cause.
@@ -515,7 +519,7 @@ function mapCapturedSlide(fileName, cap, warnings) {
 // note?}], warnings: [] }.
 export async function viewDraft(
   deckDir,
-  { presentationId = null, onProgress = null } = {},
+  { presentationId = null, onProgress = null, only = null, translate = false } = {},
 ) {
   if (!deckDir) throw new Error("viewDraft: deckDir is required");
   const slidesDir = path.join(deckDir, "slides");
@@ -525,12 +529,19 @@ export async function viewDraft(
   // Authored JSX + reused native .pptx share one play-order namespace, exactly
   // as the render path sees them — walk them in that order so the draft view
   // lines up with the deck the user will get.
-  const all = sortSlideFilenames(
+  let all = sortSlideFilenames(
     fs.readdirSync(slidesDir).filter((f) => f.endsWith(".jsx") || f.endsWith(".pptx")),
   );
   if (all.length === 0) {
     throw new Error(`No .jsx or .pptx slides under ${slidesDir}`);
   }
+  if (Array.isArray(only) && only.length > 0) {
+    const missing = only.filter((f) => !all.includes(f));
+    if (missing.length > 0) {
+      throw new Error(`no such slide file${missing.length > 1 ? "s" : ""} under ${slidesDir}: ${missing.join(", ")}`);
+    }
+    all = all.filter((f) => only.includes(f));
+  }
   const warnings = [];
   // Same identity reconcile as the render path — a reorder renames every file,
   // and a stale sidecar here would mislabel renamed converted slides (Chrome
@@ -553,6 +564,22 @@ export async function viewDraft(
   // cached engine.
   let ref = readDeckBundleRef(deckDir);
   let bundleDir = resolveBundleDirForDeck(deckDir);
+  if (hasJsx && !presentationId && (!bundleDir || !bundleHasCaptureEngine(bundleDir))) {
+    // Window-free first: the deck's binding or the one design at hand syncs
+    // over the brand route; only a miss (old add-in, revoked design) goes on
+    // to the registry below.
+    const brandId = await resolveWindowlessBrand(deckDir);
+    if (brandId) {
+      try {
+        const mat = await materializeBundle(null, { brandId });
+        writeDeckBundleRef(deckDir, { presFP: mat.presFP, etag: mat.etag });
+        ref = readDeckBundleRef(deckDir);
+        bundleDir = resolveBundleDirForDeck(deckDir);
+      } catch (err) {
+        if (!isBrandRouteMiss(err)) throw err;
+      }
+    }
+  }
   if (hasJsx && (!bundleDir || !bundleHasCaptureEngine(bundleDir))) {
     const registry = await requireRenderHost();
     const entry = pickPresentationEntry(registry, presentationId, {
@@ -587,19 +614,19 @@ export async function viewDraft(
     throw new Error(
       "draft preview needs the corporate design's capture engine, which ships in the " +
         "materialized bundle. Run `slidemind download-bundle <deck>` against an open " +
-        "PowerPoint host once, then retry — or use `slidemind build <deck>` for a " +
+        "PowerPoint host once, then retry — or use `slidemind view-draft <deck>` for a " +
         "host-free HTML preview.",
     );
   }
 
   let captured;
   try {
-    captured = await captureDeckLocally({ deckDir, bundleDir, onProgress });
+    captured = await captureDeckLocally({ deckDir, bundleDir, onProgress, only });
   } catch (err) {
     throw new Error(
       `local draft capture failed (${err instanceof Error ? err.message : String(err)}). ` +
-        "It runs a local headless Chrome; if Chrome can't launch here, use " +
-        "`slidemind build <deck>` for an HTML preview instead." +
+        "It runs a local headless Chrome; if Chrome can't launch here, " +
+        "`slidemind review <deck>` still builds and serves the HTML preview without it." +
         (Object.keys(conversions).length > 0 ? ` ${convertedNote}.` : ""),
     );
   }
@@ -619,7 +646,67 @@ export async function viewDraft(
     return mapCapturedSlide(fileName, byFile.get(fileName), warnings);
   });
 
-  return { slides, warnings };
+  // --translate: run the captured slides through the server's translate gate
+  // (slot-fit, diagram-geometry, connector-endpoints — the checks the local
+  // capture cannot make) and hand its verdict back per slide. The returned
+  // .pptx is discarded: this is validation, not delivery, so no review gate
+  // stands in front of it and a per-slide builder can prove its ONE slide
+  // buildable before reporting. Pane-free over the deck's bound design.
+  // `translate: "auto"` (the default) runs the gate when it can and reports
+  // why not otherwise — an unbound deck or a dead backend must not turn a
+  // host-free draft check into a failure; `true` (--translate) insists.
+  let translateErrors = null;
+  let translateWarnings = [];
+  let translateRan = false;
+  if (translate && captured?.slides?.length) {
+    const skip = (why) => {
+      if (translate !== "auto") throw new Error(why);
+      warnings.push(`export gate skipped: ${why}`);
+    };
+    if (!ref?.presFP) {
+      skip("the deck is not bound to a design (run `slidemind ready <deck>` first)");
+    } else {
+      let mat = null;
+      try {
+        mat = await materializeBundle(null, { brandId: ref.presFP });
+      } catch (err) {
+        skip(`the design's backend did not answer (${err?.message ?? err})`);
+      }
+      if (mat) writeDeckBundleRef(deckDir, { presFP: mat.presFP, etag: mat.etag });
+      if (mat && !mat.backendURL) {
+        skip("the bound design's backend could not be resolved (brand route unavailable)");
+      } else if (mat) {
+        try {
+          const res = await translateDeck({
+            brandId: ref.presFP,
+            backendURL: mat.backendURL,
+            deckName: path.basename(deckDir),
+            captured,
+            etag: mat.etag,
+          });
+          translateErrors = new Map();
+          translateWarnings = Array.isArray(res?.warnings) ? res.warnings : [];
+          translateRan = true;
+        } catch (err) {
+          if (err?.status === 422) {
+            const { parseTranslateErrors } = await import("../builders/draft-check.mjs");
+            translateErrors = parseTranslateErrors(err.message);
+            translateRan = true;
+          } else {
+            skip(`the export gate did not answer (${err?.message ?? err})`);
+          }
+        }
+      }
+    }
+  }
+  for (const slide of slides) {
+    if (translateErrors && slide.status === "ok") {
+      slide.translateErrors = translateErrors.get(slide.fileName) ?? [];
+    }
+  }
+  if (translateErrors?.has("")) warnings.push(...translateErrors.get(""));
+
+  return { slides, warnings, translateWarnings, translateRan };
 }
 
 // A brand-route miss is definitive for the pane-free path but NOT for the
@@ -631,7 +718,9 @@ function isBrandRouteMiss(err) {
     err?.code === "brand_route_unavailable" ||
     err?.code === "unknown_brand" ||
     err?.code === "no_active_cd" ||
-    err?.status === 404
+    // A 404 WITHOUT a machine code is Express saying "no such route" (an old
+    // add-in); a coded 404 is the route itself talking and must surface.
+    (err?.status === 404 && !err?.code)
   );
 }
 
@@ -776,8 +865,9 @@ export async function buildAndPush({
   // backgrounded during the render); the pane matters only for the insert. ---
   let result = null;
   let renderEntry = null;
-  if (!presentationId && deckRef?.presFP) {
-    const detached = await tryDetachedRender(deckDir, deckRef, onProgress, reconcile);
+  const brandId = presentationId ? null : await resolveWindowlessBrand(deckDir);
+  if (brandId) {
+    const detached = await tryDetachedRender(deckDir, { presFP: brandId }, onProgress, reconcile);
     if (detached) result = detached.result;
   }
   if (!result) {
@@ -983,10 +1073,13 @@ export async function buildPptxFile({
   // folded or reported.
   const reconcile = collectReconcileInputs({ deckDir, outFile: out, force });
 
-  // Pane-free path. `--to <presId>` names a window explicitly and therefore
-  // keeps the registry path.
-  if (!presentationId && deckRef?.presFP) {
-    const detached = await tryDetachedRender(deckDir, deckRef, onProgress, reconcile);
+  // Pane-free path: the deck's binding, else the one design at hand (cache /
+  // brand list). `--to <presId>` names a window explicitly and therefore keeps
+  // the registry path — reading the design off an open presentation is the one
+  // thing a render legitimately needs a window for.
+  const brandId = presentationId ? null : await resolveWindowlessBrand(deckDir);
+  if (brandId) {
+    const detached = await tryDetachedRender(deckDir, { presFP: brandId }, onProgress, reconcile);
     if (detached) {
       fs.writeFileSync(out, Buffer.from(detached.result.base64, "base64"));
       return {