slidemind 0.3.14 → 0.3.16

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "description": "Connect Claude Code to the slidemind PowerPoint add-in — build and edit native, on-brand PowerPoint decks against the active corporate design, from the terminal.",
   "author": {
     "name": "statworx",

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "description": "Connect Codex to the slidemind PowerPoint add-in — build and edit native, on-brand PowerPoint decks against the active corporate design. Requires the slidemind CLI (npm install -g slidemind); the skills explain the install when it is missing.",
   "author": {
     "name": "statworx",

package/AGENTS.md

@@ -186,7 +186,7 @@ slidemind/
 │   │                             download-bundle · ready · diagnose · read · session (login/whoami/logout) · install (init/uninstall/update) · setup
 │   ├── bridge/                   add-in local-bridge: client.mjs (the public surface; implementation split by job under client/: transport, presentations, pane-ops, brands, render, engine-routing, engine-search, engine-slides), bundle.mjs (materialize), build-and-push.mjs (server render; native-slide splicing), engine-download.mjs + recolor.mjs (image/icon fetch + recolour),
 │   │                             setup-claim.mjs (decode/redeem the add-in's one-command claim — the only connect path) + http-json.mjs + config.mjs (per-backend sessions)
-│   ├── builders/                 build.mjs (HTML preview; the page itself is preview.html), review.mjs (spatial preview-review gate + local server; stable per-deck port, graceful fallback, tab reuse across rounds), plan.mjs (plan sign-off gate) + plan-overlay.js + plan-md.mjs (markdown→HTML) + gate-server.mjs (shared gate primitives), resolve-skill.mjs (→ bundle), lint.mjs (runs the add-in's engine)
+│   ├── builders/                 layout-jobs.mjs (a layout's job — cover/agenda/divider/quote/closing/content — from the bundle's PLACEHOLDERS `job` or the add-in's name table; the deck frame is composed from it, docs/slidemind-cli-connect/17-deck-frame.md), build.mjs (HTML preview; the page itself is preview.html), review.mjs (spatial preview-review gate + local server; stable per-deck port, graceful fallback, tab reuse across rounds), plan.mjs (plan sign-off gate) + plan-overlay.js + plan-md.mjs (markdown→HTML) + gate-server.mjs (shared gate primitives), resolve-skill.mjs (→ bundle), lint.mjs (runs the add-in's engine)
 │   ├── pptx/                     host-free local-.pptx support (fflate-based): read-local.mjs (read a file's slides — output-identical to the host read), slide-swap.mjs (fold a picked slide into a deck as native .pptx — swaps it into the lowest slot the splicer reads, then prunes the package to that slide's dependency closure so a slice carries only what it needs), zip.mjs + ooxml.mjs (shared unzip/order helpers)
 │   ├── lib/                      deck-workspace bookkeeping: adopt.mjs (rebuild a deck from a file's embedded source + convert its foreign slides through the add-in's convert-pptx route), conversions.mjs (the deck's `conversions/<stem>.json` identity+evidence records and the preserve source package push threads back), slide-guids.mjs, slide-order.mjs, reused-slides.mjs
 │   └── installers/               per-harness installers: claude.mjs, codex.mjs, opencode.mjs, lib.mjs

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.3.14",
+  "version": "0.3.16",
   "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

@@ -360,6 +360,14 @@ 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).
@@ -388,11 +396,25 @@ part on its own route instead of forcing the whole thing onto one.
 - **Replay and get sign-off — always, at every size.** Persist a **story-focused plan with body
   storyboards** in `decks/<slug>/plan.md` and run the gate on it, whether the request is one slide or
   forty. A single slide gets the same document with one `### Slide N` section: shorter, never
-  skipped. Two top-level sections in order:
-  - `## Red thread` — one presentation **move** per slide, as bullets or one arrow-separated line.
-    The number of moves MUST equal the number of `### Slide N` sections: when the user names a slide
-    count, write exactly that many moves and sections — never expand the narrative arc beyond the
-    requested count. Name the *teaching function* of each slide — short verb+noun labels for what
+  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.
@@ -447,6 +469,8 @@ part on its own route instead of forcing the whole thing onto one.
   ```storyboard-canvas
   {
     "version": 1,
+    "role": "body",
+    "layoutSelection": "automatic",
     "slide": 1,
     "layout": "<ComponentName from design.md's Layout Catalog>",
     "blocks": [
@@ -594,7 +618,8 @@ From here:
    `.pptx` that coexists with your JSX in play order and survives re-push. The slide can come from
    an engine search **or** from a local `.pptx` on disk (`add-slide --from <file.pptx> --pick <n>
    --deck <slug>`, host-free); both fold in identically — see `slidemind-search`.
-3. **Reopen the concepts, then author in small batches.** Once the searches and asset downloads are
+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'

package/src/bridge/client/transport.mjs

@@ -424,7 +424,10 @@ export function nodeRequestToFile(urlString, init = {}, destPath) {
           reject(err);
         });
         out.on("error", reject);
-        out.on("finish", () =>
+        // `close`, not `finish`: finish fires before the fd is released, and
+        // on Windows the caller's next rename/rm of that file then hits
+        // EPERM/ENOTEMPTY (flaky CI teardown was the symptom).
+        out.on("close", () =>
           resolve({
             status,
             statusText: res.statusMessage ?? "",

package/src/builders/draft-check.mjs

@@ -37,7 +37,14 @@ export function seedAssetPlan(deckDir, images) {
   const slides = [...images]
     .sort((a, b) => a.slideNumber - b.slideNumber)
     .map((img) =>
-      [
+      img.frame
+        ? [
+            `## Slide ${pad2(img.slideNumber)} — ${img.label ?? `Slide ${img.slideNumber}`}`,
+            `jsx: slides/${pad2(img.slideNumber)}-<name>.jsx`,
+            `(frame slide — ${img.frame}: chrome slots only, authored from the plan as the layout's props; no inventory, no mockup, no verdict)`,
+            "",
+          ].join("\n")
+        : [
         `## Slide ${pad2(img.slideNumber)} — ${img.label ?? `Slide ${img.slideNumber}`}`,
         `jsx: slides/${pad2(img.slideNumber)}-<name>.jsx`,
         "regions:",

package/src/builders/layout-jobs.mjs

@@ -0,0 +1,129 @@
+// Layout JOB — what a bundle layout is for (cover / agenda / divider / quote /
+// closing / content / blank), brand-agnostically.
+//
+// The add-in writes `"job"` into every layout's `// PLACEHOLDERS` metadata
+// (`lib/corporate-design/layout-job.ts` is the owner of the rule). Bundles
+// emitted before that field existed carry none, so this module reads the
+// field when present and otherwise runs the SAME name/placeholder table the
+// add-in uses — a port, not a second opinion. Consumers: `concepts` (frame
+// slides get no mockup), the plan gate (frame ⇔ shape validation, layout
+// picker), the sim checker (body-only slide counts).
+//
+// docs/slidemind-cli-connect/17-deck-frame.md
+
+import fs from "node:fs";
+import path from "node:path";
+
+export const FRAME_JOBS = new Set(["cover", "agenda", "divider", "closing", "frame"]);
+
+const NAME_KEYWORDS = [
+  ["agenda", ["agenda", "inhaltsverzeichnis", "inhaltsubersicht", "contents", "overview", "ubersicht", "uebersicht", "table of contents", "toc"]],
+  ["closing", ["closing", "ending", "end slide", "abschluss", "schluss", "ende", "thank", "danke", "contact", "kontakt", "back cover", "last"]],
+  ["divider", ["divider", "section", "sektion", "abschnitt", "chapter", "kapitel", "trenner", "zwischentitel", "break"]],
+  ["quote", ["quote", "zitat", "testimonial", "statement"]],
+  ["cover", ["cover", "title slide", "titelfolie", "titel", "deckblatt", "start", "front", "opening", "intro"]],
+];
+
+function fold(value) {
+  return String(value ?? "")
+    .toLowerCase()
+    .replace(/ä/g, "a")
+    .replace(/ö/g, "o")
+    .replace(/ü/g, "u")
+    .replace(/ß/g, "ss")
+    .replace(/[_\-./]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function byName(...names) {
+  const haystack = names.map(fold).filter(Boolean).join(" | ");
+  if (!haystack) return null;
+  const saysContent = ["inhalt", "content", "body", "text", "text slide"].some((w) => haystack.includes(w));
+  for (const [job, words] of NAME_KEYWORDS) {
+    if (words.some((w) => haystack.includes(w))) {
+      if (job === "cover" && saysContent) continue;
+      return job;
+    }
+  }
+  return null;
+}
+
+/** Same decision table as the add-in's classifyLayoutJob. */
+export function classifyLayoutJob({ layoutType = null, placeholderTypes = [], hasCanvas = false, nativeLayoutName = null, componentName = null }) {
+  const type = String(layoutType ?? "").trim();
+  const ph = new Set(placeholderTypes.map((t) => String(t).trim()));
+  const named = byName(nativeLayoutName, componentName);
+  if (type === "title" || type === "ctrTitle") return "cover";
+  if (type === "secHead") return named === "agenda" ? "agenda" : "divider";
+  if (type === "blank" && !hasCanvas) return named ?? "blank";
+  if (!hasCanvas) {
+    if (ph.has("ctrTitle")) return "cover";
+    if (ph.has("subTitle") && !ph.has("body")) return "cover";
+    if (named) return named;
+    if (ph.size === 0) return "blank";
+    return "divider";
+  }
+  if (named === "agenda" || named === "quote") return named;
+  return "content";
+}
+
+export const isFrameJob = (job) => FRAME_JOBS.has(job);
+
+const PLACEHOLDERS_PREFIX = "// PLACEHOLDERS: ";
+
+/** `{ componentName → { job, nativeLayoutName, hasCanvas, fromBundle } }` for every layouts/*.jsx. */
+export function layoutJobs(bundleDir) {
+  const out = new Map();
+  const dir = bundleDir ? path.join(bundleDir, "layouts") : null;
+  if (!dir || !fs.existsSync(dir)) return out;
+  for (const file of fs.readdirSync(dir)) {
+    if (!file.endsWith(".jsx")) continue;
+    const componentName = file.slice(0, -4);
+    let source = "";
+    try {
+      source = fs.readFileSync(path.join(dir, file), "utf8");
+    } catch {
+      continue;
+    }
+    let meta = null;
+    for (const line of source.split("\n")) {
+      if (!line.startsWith(PLACEHOLDERS_PREFIX)) continue;
+      try {
+        meta = JSON.parse(line.slice(PLACEHOLDERS_PREFIX.length));
+      } catch {}
+      break;
+    }
+    const nativeLayoutName = meta?.nativeLayoutName ?? componentName;
+    const hasCanvas = Boolean(meta?.content) || /\{children\}/.test(source);
+    const job =
+      typeof meta?.job === "string"
+        ? meta.job
+        : classifyLayoutJob({
+            placeholderTypes: (meta?.chrome ?? []).map((c) => c.type),
+            hasCanvas,
+            nativeLayoutName,
+            componentName,
+          });
+    out.set(componentName, { job, nativeLayoutName, hasCanvas, fromBundle: typeof meta?.job === "string" });
+  }
+  return out;
+}
+
+/** The job a layout NAME alone implies (cover/agenda/divider/quote/closing), or null. */
+export function nameJob(...names) {
+  return byName(...names);
+}
+
+/** Job of one component name: the bundle's field, else what the name says, else `content`. */
+export function jobOf(jobs, componentName) {
+  if (!componentName) return "content";
+  return jobs.get(componentName)?.job ?? nameJob(componentName) ?? "content";
+}
+
+/** Explicit planned role wins; layout jobs are read compatibility for old plans only. */
+export function plannedJob(data, jobs = new Map()) {
+ if (data?.role === "body") return "content";
+ if (data?.role === "frame") return FRAME_JOBS.has(data.frameKind) ? data.frameKind : "frame";
+ return jobOf(jobs, data?.layout);
+}

package/src/builders/plan-overlay.js

@@ -1134,6 +1134,9 @@
             var d = {};
             for (var k in chipSegment.data) d[k] = chipSegment.data[k];
             d.layout = componentName;
+          d.layoutSelection = "explicit";
+          d.layoutKey = (CFG.layouts || []).find(function(o) { return o.componentName === componentName; })?.layoutKey;
+          delete d.layoutReason;
             commitStoryboard(chipSegment, d);
           },
         });
@@ -1602,6 +1605,7 @@
 
   function renderLayoutPicker(value, opts) {
     var options = Array.isArray(CFG.layouts) ? CFG.layouts : [];
+    if (opts.bodyOnly) options = options.filter(function(o) { return o.canvasBounds || o.contentAreas?.length; });
     var root = el("div", "plan-storyboard-layout-picker" + (opts.className ? " " + opts.className : ""));
     var selected = null;
     for (var i = 0; i < options.length; i++) {
@@ -1623,7 +1627,7 @@
       current.appendChild(thumb);
     }
     var nameSpan = el("span", "plan-storyboard-layout-name");
-    nameSpan.textContent = value || opts.placeholder || "No layout chosen";
+    nameSpan.textContent = (selected && selected.nativeLayoutName) || value || opts.placeholder || "No layout chosen";
     current.appendChild(nameSpan);
     if (value && options.length > 0 && !selected) {
       var badge = el("span", "plan-storyboard-layout-unknown");
@@ -1676,7 +1680,9 @@
         }
         var text = el("span", "plan-storyboard-layout-option-text");
         var n = el("span", "plan-storyboard-layout-name");
-        n.textContent = option.componentName;
+        n.textContent = option.nativeLayoutName || option.componentName;
+        if (options.filter(function (other) { return other.nativeLayoutName === option.nativeLayoutName; }).length > 1 && option.selection?.masterName) n.textContent += " · " + option.selection.masterName;
+        if (option.selection) n.title = option.selection.masterName || "";
         text.appendChild(n);
         if (option.purpose) {
           var p = el("span", "plan-storyboard-layout-purpose");
@@ -1685,11 +1691,11 @@
         }
         var c = el("span", "plan-storyboard-layout-canvas");
         c.textContent = contentAreaSummary(option);
+        if (option.selection) { var u = option.selection; c.textContent += u.currentCount ? " · " + u.currentCount + " uses in this presentation" : u.usage.count ? " · " + u.usage.count + " observed uses" : ""; }
         text.appendChild(c);
         btn.appendChild(text);
         btn.addEventListener("click", function () {
           closeMenu();
-          if (option.componentName === value) return;
           opts.onPick(option.componentName);
         });
         menu.appendChild(btn);
@@ -1704,7 +1710,7 @@
   // pick binds EVERY storyboard's `layout` in one commit.
   function renderDeckLayoutKnob(storyboardData) {
     var wrap = el("div", "plan-storyline-deck-layout");
-    wrap.appendChild(el("span", "plan-storyline-deck-layout-label", "Deck layout"));
+    wrap.appendChild(el("span", "plan-storyline-deck-layout-label", "Body defaults"));
     var seen = {};
     var distinct = 0;
     for (var i = 0; i < storyboardData.length; i++) {
@@ -1718,17 +1724,39 @@
     wrap.appendChild(
       renderLayoutPicker(common || undefined, {
         placeholder: distinct > 1 ? "Mixed" : undefined,
-        ariaLabel: "Set one layout for every slide",
+        ariaLabel: "Set the default for compatible body slides",
+        bodyOnly: true,
         onPick: function (componentName) {
-          commitPlan(PLAN.setStoryboardLayoutForAll(S.value, componentName));
+          commitPlan(PLAN.setStoryboardLayoutForAll(S.value, componentName, CFG.layouts || []));
         },
       }),
     );
+    if ((CFG.layouts || []).some(function(o) { return o.selection?.counterpartKey; })) {
+      ["light", "dark"].forEach(function(tone) {
+        var button = el("button", "plan-storyboard-layout-current", tone === "dark" ? "Dark variants" : "Light variants");
+        button.type = "button";
+        button.addEventListener("click", function() { commitPlan(PLAN.setStoryboardStyle(S.value, tone, CFG.layouts || [])); });
+        wrap.appendChild(button);
+      });
+    }
     return wrap;
   }
 
   function renderDetails(data, segment) {
     var aside = el("aside", "plan-storyboard-detail");
+    var roleSelect = document.createElement("select");
+    roleSelect.setAttribute("aria-label", "Slide role");
+    ["body", "cover", "agenda", "divider", "closing"].forEach(function(role) {
+      var option = document.createElement("option"); option.value = role; option.textContent = role;
+      option.selected = role === (data.role === "frame" ? data.frameKind : "body"); roleSelect.appendChild(option);
+    });
+    roleSelect.addEventListener("change", function() { var d = Object.assign({}, data);
+      d.role = roleSelect.value === "body" ? "body" : "frame";
+      d.frameKind = d.role === "frame" ? roleSelect.value : undefined;
+      commitStoryboard(segment, d);
+    });
+    aside.appendChild(roleSelect);
+    if (data.layoutReason) aside.appendChild(el("div", "plan-storyboard-layout-purpose", data.layoutReason));
     aside.appendChild(el("div", "plan-storyboard-detail-label", "Layout"));
     aside.appendChild(
       renderLayoutPicker(data.layout, {
@@ -1736,6 +1764,9 @@
           var d = {};
           for (var k in data) d[k] = data[k];
           d.layout = componentName;
+          d.layoutSelection = "explicit";
+          d.layoutKey = (CFG.layouts || []).find(function(o) { return o.componentName === componentName; })?.layoutKey;
+          delete d.layoutReason;
           commitStoryboard(segment, d);
         },
       }),

package/src/builders/plan.mjs

@@ -55,6 +55,8 @@ import { openInBrowser } from "./build.mjs";
 import { loadReviewState } from "./review.mjs";
 import { renderPlanMarkdown } from "./plan-md.mjs";
 import { splitPlanFrontmatter } from "./resolve-skill.mjs";
+import { layoutJobs, isFrameJob, plannedJob } from "./layout-jobs.mjs";
+import { splitPlanMarkdownIntoSegments } from "./storyboard-markdown.mjs";
 import {
   FAVICON_LINK,
   MIME,
@@ -286,6 +288,7 @@ const PLAN_NAMESPACE_EXPORTS = [
   "splitPlanMarkdownIntoSegments",
   "replaceStoryboardSegment",
   "setStoryboardLayoutForAll",
+  "setStoryboardStyle",
   "extractRedThreadMessages",
   "findRedThreadSection",
   "parseStoryboardCanvas",
@@ -467,6 +470,95 @@ export function parsePlaceholderOutlines(source, layoutsCss) {
 // chrome-render thumbnail from `assets/chrome-<Name>.*` served at
 // `/brand/chrome/<file>`. No bundle → `{ layouts: [], chromeDir: null }` and
 // the picker degrades to read-only (the host-free contract holds).
+// ---------------------------------------------------------------------------
+// The plan's `## Deliverable` block and the deck frame it implies
+// (docs/slidemind-cli-connect/17-deck-frame.md). Parsed leniently: the block
+// is a contract the agent writes and the user edits by hand.
+// ---------------------------------------------------------------------------
+
+export function parseDeliverable(markdown) {
+  const m = /^##\s+Deliverable\s*\n([\s\S]*?)(?=^##\s|(?![\s\S]))/m.exec(markdown ?? "");
+  if (!m) return null;
+  const get = (key) => {
+    const r = new RegExp(`^\\s*-?\\s*${key}\\s*:\\s*(.+)$`, "im").exec(m[1]);
+    return r ? r[1].trim() : null;
+  };
+  const shape = (get("shape") ?? "").toLowerCase().replace(/[^a-z]/g, "");
+  const body = Number.parseInt(get("body slides") ?? get("body") ?? "", 10);
+  const frameRaw = (get("frame") ?? "").toLowerCase();
+  const frame = /^(none|-|—|no)\b/.test(frameRaw)
+    ? []
+    : frameRaw.split(/[,;/]+/).map((x) => x.trim().replace(/s$/, "")).filter(Boolean);
+  return {
+    shape: shape === "deck" || shape === "slides" ? shape : null,
+    bodySlides: Number.isFinite(body) ? body : null,
+    frame,
+    target: get("target"),
+  };
+}
+
+/**
+ * `[plan:warn]` lines for a plan whose deliverable block and storyboards do
+ * not agree with each other or with the bundle's layout jobs. Advisory: the
+ * gate still opens — the user decides in it — but the agent reads these
+ * before the user does.
+ */
+export function planDeliverableWarnings(deckDir, markdown) {
+  const out = [];
+  const dir = resolveBundleDirForDeck(deckDir);
+  const jobs = layoutJobs(dir);
+  const beats = [];
+  for (const segment of splitPlanMarkdownIntoSegments(markdown ?? "")) {
+    if (segment.type !== "storyboard" || !segment.data) continue;
+    const layout = segment.data.layout ?? null;
+    if (!segment.data.role) out.push(`[plan:warn] slide ${segment.data.slide} has no role; legacy layout inference is being used. Write role: body | frame before the next approval.`);
+    if (segment.data.role === "frame" && !segment.data.frameKind) out.push(`[plan:warn] frame slide ${segment.data.slide} needs a frameKind.`);
+    beats.push({ slide: segment.data.slide, layout, job: plannedJob(segment.data, jobs) });
+  }
+  if (beats.length === 0) return out;
+  const frameBeats = beats.filter((b) => isFrameJob(b.job));
+  const bodyBeats = beats.filter((b) => !isFrameJob(b.job));
+  const d = parseDeliverable(markdown);
+  if (!d) {
+    out.push(
+      `[plan:warn] plan.md has no \`## Deliverable\` block (shape: deck | slides, body slides: N, frame: <jobs>, target). ` +
+        `Without it the frame (cover/agenda/dividers/closing) is unspecified — write the block before the gate.`,
+    );
+    return out;
+  }
+  if (d.shape === "deck" && frameBeats.length === 0) {
+    const offered = [...jobs.values()].filter((j) => isFrameJob(j.job)).map((j) => j.job);
+    out.push(
+      `[plan:warn] shape is deck but no storyboard sits on a frame layout — this design offers ${offered.length ? [...new Set(offered)].join(", ") : "no frame layouts"}; a deck ships its cover${offered.includes("closing") ? " and closing" : ""}.`,
+    );
+  }
+  if (d.shape === "slides" && frameBeats.length > 0 && d.frame.length === 0) {
+    out.push(
+      `[plan:warn] shape is slides but slide${frameBeats.length > 1 ? "s" : ""} ${frameBeats.map((b) => b.slide).join(", ")} sit on frame layouts (${[...new Set(frameBeats.map((b) => b.job))].join(", ")}) — slides extend a deck that has its own frame; drop them or set shape: deck.`,
+    );
+  }
+  if (d.bodySlides != null && d.bodySlides !== bodyBeats.length) {
+    out.push(
+      `[plan:warn] Deliverable says body slides: ${d.bodySlides}, the storyboards carry ${bodyBeats.length} body slide${bodyBeats.length === 1 ? "" : "s"} (frame slides excluded).`,
+    );
+  }
+  for (const want of d.frame) {
+    if (!isFrameJob(want)) continue;
+    if (!frameBeats.some((b) => b.job === want)) {
+      out.push(`[plan:warn] frame lists ${want} but no storyboard declares that frameKind.`);
+    }
+  }
+  const cover = frameBeats.find((b) => b.job === "cover");
+  if (cover && beats.some((b) => b.slide < cover.slide)) {
+    out.push(`[plan:warn] the cover is slide ${cover.slide} — a cover is slide 1.`);
+  }
+  const closing = frameBeats.find((b) => b.job === "closing");
+  if (closing && beats.some((b) => b.slide > closing.slide)) {
+    out.push(`[plan:warn] the closing is slide ${closing.slide} but slides follow it — a closing is the last slide.`);
+  }
+  return out;
+}
+
 export function resolvePlanLayouts(deckDir) {
   const dir = resolveBundleDirForDeck(deckDir);
   if (!dir) return { layouts: [], chromeDir: null };
@@ -484,7 +576,9 @@ export function resolvePlanLayouts(deckDir) {
   // are the only place these bullets follow a ### heading in the generated
   // design.md.
   const purposes = new Map();
+  const selections = new Map();
   const canvases = new Map();
+  const jobs = layoutJobs(dir);
   try {
     const md = fs.readFileSync(path.join(dir, "design.md"), "utf8");
     let current = null;
@@ -495,6 +589,8 @@ export function resolvePlanLayouts(deckDir) {
         continue;
       }
       if (!current) continue;
+      const selection = /^- Selection:\s*(.+)$/.exec(line);
+      if (selection) { try { selections.set(current, JSON.parse(selection[1])); } catch {} }
       const purpose = /^- Purpose:\s*(.+)$/.exec(line);
       if (purpose) purposes.set(current, purpose[1].trim());
       // Newer add-ins write `- Content areas:`; the deployed one still writes
@@ -578,10 +674,19 @@ export function resolvePlanLayouts(deckDir) {
       if (canvasBounds && contentAreas.length === 0) contentAreas = [canvasBounds];
     }
     const chrome = chromeByComponent.get(componentName);
+    const jobInfo = jobs.get(componentName);
+    const selectionLine = /^\/\/ SELECTION: (.+)$/m.exec(source);
+    let selection = selections.get(componentName);
+    if (selectionLine) { try { selection = JSON.parse(selectionLine[1]); } catch {} }
     layouts.push({
       componentName,
       purpose: purposes.get(componentName) ?? null,
-      mode: content ? "workhorse" : "purpose-built",
+      // Original names remain visible; legacy jobs are read compatibility only.
+      nativeLayoutName: selection?.nativeLayoutName ?? jobInfo?.nativeLayoutName ?? componentName,
+      selection,
+      layoutKey: selection?.layoutKey,
+      job: jobInfo?.job ?? (content ? "content" : "blank"),
+      mode: content ? "composition" : "purpose-built",
       canvas,
       canvasBounds,
       contentAreas,
@@ -589,6 +694,35 @@ export function resolvePlanLayouts(deckDir) {
       previewUrl: chrome ? `/brand/chrome/${chrome}` : null,
     });
   }
+  // Target context is opt-in, written by `read --deck`; it never changes the brand bundle.
+  try {
+    const context = JSON.parse(fs.readFileSync(path.join(deckDir, ".layout-context.json"), "utf8"));
+    for (const layout of layouts) {
+      const selected = context.selections?.[layout.componentName];
+      if (!layout.selection) continue;
+      // A modern scoped identity mismatch must never fall back to a name join.
+      if (selected?.layoutKey) {
+        if (selected.layoutKey !== layout.layoutKey) continue;
+        layout.selection = { ...layout.selection, currentCount: selected.currentCount,
+          sectionCount: selected.sectionCount };
+      } else if (context.selections === undefined &&
+        Object.hasOwn(context.layoutCounts ?? {}, layout.nativeLayoutName) &&
+        layouts.filter((other) => other.nativeLayoutName === layout.nativeLayoutName).length === 1) {
+        layout.selection = { ...layout.selection, currentCount: context.layoutCounts[layout.nativeLayoutName] };
+      }
+      const p = layout.selection;
+      p.source = p.sectionCount > 0 ? "section" : p.currentCount > 0 ? "presentation" : p.usage?.count > 0 ? "brand" : "suggested";
+    }
+  } catch {}
+  // Same precedence as the add-in profile: capability, section, target, brand.
+  // Brand ranks are supplied by the add-in; legacy bundles retain their order.
+  layouts.sort((a, b) => {
+    if (!a.selection || !b.selection) return (a.selection?.rank ?? Infinity) - (b.selection?.rank ?? Infinity);
+    return Number(b.selection.composition) - Number(a.selection.composition) ||
+      (b.selection.sectionCount ?? 0) - (a.selection.sectionCount ?? 0) ||
+      (b.selection.currentCount ?? 0) - (a.selection.currentCount ?? 0) ||
+      b.selection.usage.share - a.selection.usage.share || a.componentName.localeCompare(b.componentName);
+  });
   return { layouts, chromeDir: chromeFiles.length ? assetsDir : null };
 }
 
@@ -871,6 +1005,10 @@ export async function runPlanReview({
     return;
   }
 
+  for (const line of planDeliverableWarnings(deckDir, fs.readFileSync(planPath, "utf8"))) {
+    process.stdout.write(`  ${line}\n`);
+  }
+
   // Headless simulation runs (scripts/codex-sim.mjs): approve without a browser.
   if (process.env.SLIDEMIND_GATE_AUTOAPPROVE === "1") {
     savePlanState(deckDir, {

package/src/builders/storyboard-markdown.mjs

@@ -120,14 +120,38 @@ export function replaceStoryboardSegment(markdown, segment, nextData) {
 // Deck-level layout knob: binds EVERY valid storyboard fence to `layout`.
 // Fences are spliced last-to-first so earlier offsets stay valid; malformed
 // fences are left untouched. Mirrors the add-in's setStoryboardLayoutForAll.
-export function setStoryboardLayoutForAll(markdown, layout) {
-  let next = markdown;
-  const boards = splitPlanMarkdownIntoSegments(markdown).filter(
-    (segment) => segment.type === "storyboard" && segment.data !== null,
-  );
-  for (const segment of boards.reverse()) {
-    if (segment.data.layout === layout) continue;
-    next = replaceStoryboardSegment(next, segment, { ...segment.data, layout });
-  }
-  return next;
+export function setStoryboardLayoutForAll(markdown, layout, options = []) {
+ let next = markdown;
+ const target = options.find((option) => option.componentName === layout);
+ // Unknown capabilities cannot safely support a bulk substitution.
+ if (!target || (!target.canvasBounds && !target.contentAreas?.length)) return markdown;
+ const boards = splitPlanMarkdownIntoSegments(markdown).filter((segment) => segment.type === "storyboard");
+ for (const segment of boards.reverse()) {
+  if (segment.type !== "storyboard" || !segment.data) continue;
+  const data = segment.data;
+  const current = options.find((option) => option.componentName === data.layout);
+  if (data.role === "frame" || data.layoutSelection === "explicit") continue;
+  if (!current || (!current.canvasBounds && !current.contentAreas?.length)) continue;
+  // Specialized geometries stay put. Bulk defaults change equivalent canvases only.
+  if (JSON.stringify(current.contentAreas ?? current.canvasBounds) !== JSON.stringify(target.contentAreas ?? target.canvasBounds)) continue;
+  if (data.layout === layout) continue;
+  next = replaceStoryboardSegment(next, segment, { ...data, role: "body", layout,
+   layoutKey: target.layoutKey, layoutSelection: "automatic", layoutReason: undefined });
+ }
+ return next;
+}
+
+/** Change only verified counterparts; preserve explicit layout choices. */
+export function setStoryboardStyle(markdown, tone, options) {
+ let next = markdown;
+ for (const segment of splitPlanMarkdownIntoSegments(markdown).reverse()) {
+  if (segment.type !== "storyboard" || !segment.data || segment.data.layoutSelection === "explicit") continue;
+  const current = options.find((option) => option.componentName === segment.data.layout);
+  if (!current?.selection?.counterpartKey || current.selection.tone === tone) continue;
+  const targets = options.filter((option) => option.selection?.counterpartKey === current.selection.counterpartKey && option.selection?.tone === tone);
+  if (targets.length !== 1) continue;
+  next = replaceStoryboardSegment(next, segment, { ...segment.data, layout: targets[0].componentName,
+   layoutKey: targets[0].layoutKey, layoutSelection: "automatic", layoutReason: undefined });
+ }
+ return next;
 }

package/src/builders/storyboard-schema.mjs

@@ -157,6 +157,15 @@ export function parseStoryboardCanvas(raw) {
     SB_MAX_VISUAL_FAMILY_LENGTH,
   );
   const layout = sbAsTrimmedString(parsed.layout, SB_MAX_LAYOUT_NAME_LENGTH);
+  const selectionFields = {};
+  if (parsed.role === "body" || parsed.role === "frame") selectionFields.role = parsed.role;
+  if (parsed.role === "frame" && ["cover", "agenda", "divider", "closing"].includes(parsed.frameKind)) selectionFields.frameKind = parsed.frameKind;
+  if (parsed.role === "frame" && !selectionFields.frameKind) warnings.push("A frame slide needs frameKind: cover, agenda, divider or closing.");
+  if (parsed.layoutSelection === "automatic" || parsed.layoutSelection === "explicit") selectionFields.layoutSelection = parsed.layoutSelection;
+  for (const key of ["layoutKey", "layoutReason", "sectionId"]) {
+    const value = sbAsTrimmedString(parsed[key], 500);
+    if (value) selectionFields[key] = value;
+  }
   const imagePrompts = {};
   if (sbIsRecord(parsed.imagePrompts)) {
     for (const [key, value] of Object.entries(parsed.imagePrompts)) {
@@ -184,6 +193,7 @@ export function parseStoryboardCanvas(raw) {
       blocks,
       ...(visualFamily ? { visualFamily } : {}),
       ...(layout ? { layout } : {}),
+    ...selectionFields,
       ...(keyMessage ? { keyMessage } : {}),
       ...(contentNotes?.length ? { contentNotes } : {}),
       ...(Object.keys(imagePrompts).length > 0 ? { imagePrompts } : {}),

package/src/cli/concepts.mjs

@@ -116,6 +116,28 @@ export async function cmdConceptImages(rest) {
     pathToFileURL(path.join(BUILDERS_DIR, "visual-families.mjs")).href
   );
   const planned = new Set(families.plannedSlideNumbers(planMarkdown));
+  // Frame slides (cover / agenda / divider / closing by the layout's job) get
+  // no mockup: they are chrome with text slots, authored from the plan. The
+  // server skips them too; taking them out of `planned` keeps them out of the
+  // "missing" list and the stale prune. (docs/…/17-deck-frame.md §2.5)
+  const jobsMod = await import(pathToFileURL(path.join(BUILDERS_DIR, "layout-jobs.mjs")).href);
+  const sbMod = await import(pathToFileURL(path.join(BUILDERS_DIR, "storyboard-markdown.mjs")).href);
+  const bundleMod = await import(pathToFileURL(path.join(SRC_DIR, "bridge", "bundle.mjs")).href);
+  const jobs = jobsMod.layoutJobs(bundleMod.resolveBundleDirForDeck(deckDir));
+  const frameSlides = [];
+  for (const segment of sbMod.splitPlanMarkdownIntoSegments(planMarkdown)) {
+    if (segment.type !== "storyboard" || !segment.data?.layout) continue;
+    const job = jobsMod.plannedJob(segment.data, jobs);
+    if (jobsMod.isFrameJob(job) && planned.has(segment.data.slide)) {
+      planned.delete(segment.data.slide);
+      frameSlides.push({ slideNumber: segment.data.slide, job, layout: segment.data.layout });
+    }
+  }
+  if (frameSlides.length) {
+    process.stderr.write(
+      `slidemind: ${frameSlides.length} frame slide${frameSlides.length === 1 ? "" : "s"} (${frameSlides.map((f) => `${f.slideNumber}:${f.job}`).join(", ")}) — no mockup; author from the plan using the layout's slots and content areas, including required images.\n`,
+    );
+  }
 
   // Idempotent fast path: mockups already on disk are re-printed IMMEDIATELY.
   // Generation takes 1-2 minutes and agent harnesses time commands out and
@@ -293,9 +315,12 @@ export async function cmdConceptImages(rest) {
   );
   const seeded = check.seedAssetPlan(
     deckDir,
-    images
-      .filter((img) => writtenNums.has(Number(img?.slideNumber)))
-      .map((img) => ({ slideNumber: Number(img.slideNumber), label: img.label })),
+    [
+      ...images
+        .filter((img) => writtenNums.has(Number(img?.slideNumber)))
+        .map((img) => ({ slideNumber: Number(img.slideNumber), label: img.label })),
+      ...frameSlides.map((f) => ({ slideNumber: f.slideNumber, label: `${f.job} (${f.layout})`, frame: f.job })),
+    ],
   );
   finish({
     paths: written,

package/src/cli/deck.mjs

@@ -490,6 +490,9 @@ export async function cmdViewDraft(rest) {
       ...rules.fill([{ stem, render }]),
       ...rules.typeScale([{ stem, render }], typeTokens),
       ...rules.overlap([{ stem, render }]),
+      // Text leaving its painted card — engines from 2026-09-06 on; older
+      // ones simply have no rule here.
+      ...(typeof rules.escape === "function" ? rules.escape([{ stem, render }]) : []),
     ].map((l) => l.trim());
 
   const written = [];

package/src/cli/help.mjs

@@ -151,9 +151,10 @@ export function printHelp(cmd = null) {
       `                                     --all           refresh every design already cached on this machine\n` +
       `                                     --force         re-download even if the cached bundle is current\n` +
 
-      `  slidemind read [presId|file.pptx]  Pull the content of an open presentation (requires a host),\n` +
+      `  slidemind read [presId|file.pptx] [--deck <deck>]  Pull the content of an open presentation (requires a host),\n` +
       `                                     or of a local .pptx path (read host-free from disk)\n` +
       `                                     --mode <m>      summary | raw (default: raw)\n` +
+      `                                     --deck <deck>   use this presentation as layout context for the plan\n` +
       `                                     --to <presId>   target a specific window (required if >1 open)\n` +
       `                                     --json          print the raw content payload\n` +
       `  slidemind push <deck> [opts]     Build deck and push slides into a running PowerPoint\n` +

package/src/cli/read.mjs

@@ -50,6 +50,7 @@ export async function cmdRead(rest) {
   let mode = "raw";
   let asJson = false;
   let toGiven = false;
+  let deckArg = null;
   let fileArg = null; // the positional (a candidate local .pptx path)
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
@@ -63,6 +64,9 @@ export async function cmdRead(rest) {
       presId = rest[++i];
       if (!presId) fail("--to expects a presId");
       toGiven = true;
+    } else if (a === "--deck") {
+      deckArg = rest[++i];
+      if (!deckArg) fail("--deck expects a deck");
     } else if (a === "--json") {
       asJson = true;
     } else if (a.startsWith("-")) {
@@ -98,6 +102,7 @@ export async function cmdRead(rest) {
       } catch (err) {
         fail(`read failed: ${err.message}`);
       }
+      if (deckArg) saveLayoutContext(deckArg, res, p);
       printReadResult(res, asJson);
       return;
     }
@@ -116,5 +121,18 @@ export async function cmdRead(rest) {
   if (!res?.ok) {
     fail(`read failed: ${res?.error ?? "unknown error"}`);
   }
+  if (deckArg) saveLayoutContext(deckArg, res, entry.presId);
   printReadResult(res, asJson);
 }
+
+// A reference must be deliberately bound to this workspace; it never changes brand evidence.
+export function saveLayoutContext(deck, result, target) {
+ const deckDir = path.resolve(fs.existsSync(deck) ? deck : path.join(process.env.SLIDEMIND_DECKS || "decks", deck));
+ if (!fs.existsSync(deckDir) || !fs.statSync(deckDir).isDirectory()) fail("--deck must name an existing deck workspace");
+ const context = { ...result.layoutContext, target, observedAt: result.layoutContext?.observedAt || new Date().toISOString(),
+  layoutCounts: Object.fromEntries((result.slides || []).reduce((counts, slide) => {
+   if (slide.layout && !slide.hidden) counts.set(slide.layout, (counts.get(slide.layout) || 0) + 1);
+   return counts;
+  }, new Map())) };
+ fs.writeFileSync(path.join(deckDir, ".layout-context.json"), JSON.stringify(context, null, 2) + "\n");
+}

package/src/pptx/read-local.mjs

@@ -35,6 +35,7 @@ export function readLocalPptx(buffer, { mode = "raw" } = {}) {
     const { title, subtitle, text } = slideText(xml);
     return {
       index: i + 1,
+      ...(/<p:sld\b[^>]*\bshow\s*=\s*["'](?:0|false)["']/.test(xml) ? { hidden: true } : {}),
       layout: layoutName(files, slidePath),
       title,
       subtitle,