slidemind 0.3.19 → 0.4.0

package/src/cli/diagnose.mjs

@@ -37,7 +37,7 @@ export async function runDiagnose(rest) {
   // push/insert-slide and reading an open presentation. Reporting them
   // separately is the point — a dead pane is not "cannot work".
   const authoringBlocker = backendBlocker(status);
-  let engines = { available: false, envs: [] };
+  let engines = { available: false, envs: [], unknown: [] };
   if (!authoringBlocker) {
     try {
       engines = await client.engineReachability({ backends: statusRaw.backends });
@@ -73,7 +73,9 @@ export async function runDiagnose(rest) {
     `  engine search (no window needed): ${
       engines.available
         ? `yes [${engines.envs.join(", ")}]`
-        : "no — relayed through an open pane"
+        : engines.unknown?.length
+          ? `could not be checked [${engines.unknown.join(", ")}] — the capability probe got no answer; retry`
+          : "no — relayed through an open pane"
     }\n`,
   );
   // Human output only — the --json shape is a contract and the m365 state

package/src/cli/engine-helpers.mjs

@@ -387,18 +387,25 @@ export function writeAddSlideResult({ asJson, searchId, deckDir, deck, written,
 
 // Map a `--icon-color` value onto the `--pick` list. Accepts either one colour
 // (applied to every pick) or exactly one per pick (positional); an empty
-// segment means "no colour for this pick". Returns an array aligned to picks.
+// segment means "no colour for this pick". The `#` is optional: an unquoted
+// `#0A7E8C` starts a shell comment (zsh, bash) that swallows the value and
+// every flag after it, so the bare form is the one no shell eats (x74: 38
+// failed downloads). `raw` is null when the flag is absent, "" when it arrived
+// empty. Returns an array aligned to picks, each colour `#`-prefixed.
 export function parseIconColors(raw, pickCount) {
-  if (!raw) return new Array(pickCount).fill(null);
-  const colors = raw
-    .split(",")
-    .map((s) => s.trim())
-    .map((s) => (s.length ? s : null));
-  for (const c of colors) {
-    if (c !== null && !/^#[0-9a-fA-F]{3,8}$/.test(c)) {
-      fail(`--icon-color expects hex colours like #0A7E8C, got '${c}'`);
-    }
+  if (raw == null) return new Array(pickCount).fill(null);
+  if (!raw.trim()) {
+    fail(
+      "--icon-color got no value — an unquoted '#RRGGBB' starts a shell comment in zsh and bash " +
+        "(which also drops every flag after it); pass 0A7E8C, or quote it: '#0A7E8C'",
+    );
   }
+  const colors = raw.split(",").map((s) => {
+    const c = s.trim();
+    if (!c) return null;
+    if (!/^#?[0-9a-fA-F]{3,8}$/.test(c)) fail(`--icon-color expects hex colours like 0A7E8C or '#0A7E8C', got '${c}'`);
+    return c.startsWith("#") ? c : `#${c}`;
+  });
   if (colors.length === 1) return new Array(pickCount).fill(colors[0]);
   if (colors.length !== pickCount) {
     fail(

package/src/cli/engine-results.mjs

@@ -187,6 +187,45 @@ export async function cmdReadSource(rest) {
  * across every command.
  */
 
+
+// Register a downloaded image with the deck's image registry (task 2.6 of the
+// image-intent contract): the bytes get a digest-backed identity and engine
+// provenance, so a later plan can bind a use to THIS result rather than to a
+// file name someone might overwrite.
+//
+// Deliberately two things it is not: it is not a use — registering creates no
+// obligation to place the picture on any slide — and it is not allowed to sink
+// a download. A registry that cannot be written (the deck is held by another
+// command, the format is one the registry does not ship) leaves the asset file
+// exactly where it always landed and every existing output field untouched.
+async function registerDownloadedAsset(deckDir, result, searchId) {
+  try {
+    const { importImageAsset } = await import(
+      pathToFileURL(path.join(SRC_DIR, "lib", "image-assets.mjs")).href
+    );
+    const { asset, reused } = await importImageAsset(deckDir, result.path, {
+      displayName: path.basename(result.path),
+      provenance: { kind: "engine", sourceId: `${searchId}:${result.selection}` },
+    });
+    return {
+      assetId: asset.assetId,
+      sha256: asset.sha256,
+      mimeType: asset.mimeType,
+      width: asset.width,
+      height: asset.height,
+      byteLength: asset.byteLength,
+      workspacePath: asset.workspacePath,
+      reused,
+    };
+  } catch (err) {
+    process.stderr.write(
+      `note: ${result.reference} was downloaded but not registered as an image asset ` +
+        `(${err?.code ?? "error"}: ${err?.message ?? err}).\n`,
+    );
+    return null;
+  }
+}
+
 export async function cmdDownloadResult(rest) {
   let searchId = null;
   let picks = null;
@@ -194,6 +233,7 @@ export async function cmdDownloadResult(rest) {
   let to = null;
   let asJson = false;
   let iconColorsRaw = null;
+  let name = null;
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
     if (a === "--search") {
@@ -208,9 +248,16 @@ export async function cmdDownloadResult(rest) {
       if (!to) fail("--to expects a presId");
     } else if (a === "--json") {
       asJson = true;
+    } else if (a === "--name") {
+      // The asset's file name under assets/ (one pick only): lets a fetcher
+      // write `02-card-1-icon.svg` so the slide author references a path it
+      // knew before the download ran — the wiring gap that left fetched icons
+      // unused (x25/x26 sims).
+      name = rest[++i];
+      if (!name || /[\\/]/.test(name)) fail("--name expects a bare file name (no directories)");
     } else if (a === "--icon-color" || a === "--icon-colour") {
-      iconColorsRaw = rest[++i];
-      if (!iconColorsRaw) fail("--icon-color expects a hex colour (or comma-separated list aligned to --pick)");
+      // Empty when the shell ate an unquoted '#…' as a comment: parseIconColors explains that.
+      iconColorsRaw = rest[++i] ?? "";
     } else if (a.startsWith("-")) {
       fail(`unknown flag: ${a}`);
     } else {
@@ -222,6 +269,7 @@ export async function cmdDownloadResult(rest) {
       "usage: slidemind download-result --search <id> --pick <n[,n,...]> --deck <deck> [--to <presId>] [--icon-color <hex[,hex,...]>] [--json]",
     );
   }
+  if (name && picks.length !== 1) fail("--name takes exactly one --pick");
   const iconColors = parseIconColors(iconColorsRaw, picks.length);
   const deckDir = resolveDeckArg(deck);
   const assetsDir = path.join(deckDir, "assets");
@@ -292,6 +340,31 @@ export async function cmdDownloadResult(rest) {
       continue;
     }
     ok++;
+    if (name && r.path) {
+      // Keep the extension the bytes decided; only the stem is the caller's.
+      const ext = path.extname(r.path);
+      // `NN-<id>.asset` is the placeholder a transcribed slide references
+      // before its bytes exist; the file takes the real extension and every
+      // slide pointing at the placeholder follows it. Kept as `.asset`, the
+      // renderer dropped the picture with a warning and the check stayed clean.
+      const placeholder = /\.asset$/i.test(name) ? name : null;
+      const target = path.join(assetsDir, placeholder ? name.replace(/\.asset$/i, ext) : path.extname(name) ? name : `${name}${ext}`);
+      fs.renameSync(r.path, target);
+      r.path = target;
+      r.reference = `./assets/${path.basename(target)}`;
+      if (placeholder) {
+        const slidesDir = path.join(deckDir, "slides");
+        for (const f of fs.existsSync(slidesDir) ? fs.readdirSync(slidesDir).filter((n) => n.endsWith(".jsx")) : []) {
+          const file = path.join(slidesDir, f);
+          const src = fs.readFileSync(file, "utf8");
+          const from = JSON.stringify(`./assets/${placeholder}`);
+          if (src.includes(from)) fs.writeFileSync(file, src.split(from).join(JSON.stringify(r.reference)));
+        }
+      }
+    }
+    // Identity for the registry — additive: `file`, `size` and `recolor` below
+    // keep their exact shape for callers that predate the image contract.
+    r.asset = r.path ? await registerDownloadedAsset(deckDir, r, searchId) : null;
     const note = r.recolor?.note ? ` — ${r.recolor.note}` : "";
     // The intrinsic size is the agent's only handle on the asset's aspect
     // ratio — without it the <img> box is a guess and the render stretches.
@@ -302,7 +375,7 @@ export async function cmdDownloadResult(rest) {
   }
   if (asJson) {
     process.stdout.write(
-      `${JSON.stringify({ searchId, assetsDir, downloaded: ok, results: results.map((r) => (r.error ? { selection: r.selection, error: r.error } : { selection: r.selection, file: r.reference, size: r.size ?? null, recolor: r.recolor ?? null })) }, null, 2)}\n`,
+      `${JSON.stringify({ searchId, assetsDir, downloaded: ok, results: results.map((r) => (r.error ? { selection: r.selection, error: r.error } : { selection: r.selection, file: r.reference, size: r.size ?? null, recolor: r.recolor ?? null, asset: r.asset ?? null })) }, null, 2)}\n`,
     );
     if (ok === 0) process.exit(1);
     return;

package/src/cli/help.mjs

@@ -29,8 +29,8 @@ export function printHelp(cmd = null) {
       `                                     --force         re-download the bundle even if current\n` +
       `                                     --connect-only  check the connection only (no design/bundle)\n` +
       `                                     --diagnose      read-only report instead: both ladders (backend\n` +
-      `                                                     authoring / live PowerPoint), every paired backend,\n` +
-      `                                                     Microsoft 365 state and every registered window\n` +
+      `                                                     authoring / live PowerPoint), Microsoft 365 state\n` +
+      `                                                     and every registered window\n` +
       `                                     --json          machine-readable readiness payload\n` +
       `                                     With a deck, also prints its stage (plan / concepts / assets / slides /\n` +
       `                                     draft check / review) and the next command — read from disk.\n` +
@@ -38,10 +38,15 @@ export function printHelp(cmd = null) {
       `                                     --brand <presFP>  bind to a chosen (cached) design instead\n` +
       `                                     --to <presId>   bind to a specific open window\n` +
       `                                     --no-bind       skip the auto-bind\n` +
-      `  slidemind plan <deck>            Plan sign-off gate on <deck>/plan.md: opens it in the browser\n` +
-      `                                     as a markdown editor + live preview + overall feedback box,\n` +
-      `                                     blocks until the user decides, prints DECISION: approved | comments\n` +
-      `                                     --port <n>          bind a fixed port (default: ephemeral)\n` +
+      `  slidemind plan <deck>            Plan sign-off gate on <deck>/.slidemind/plan.md (## Red thread +\n` +
+      `                                     ## Per-slide storyboards, one storyboard-canvas block per slide):\n` +
+      `                                     the user answers in the workspace. It asks there and returns at once:\n` +
+      `                                     ASK: <link>, SAY: <the line to end your turn with>, DECISION: pending.\n` +
+      `                                     The user's pasted message names this command again; that run prints\n` +
+      `                                     their answer (DECISION: approved | comments). BLOCKED: <code> when the\n` +
+      `                                     workspace cannot be used (exit 2). Only SLIDEMIND_WORKSPACE=0 serves\n` +
+      `                                     the standalone page that blocks until the user decides\n` +
+      `                                     --port <n>          standalone page: a fixed port (default: per deck)\n` +
       `  slidemind concepts <deck>        After plan sign-off, generate one concept mockup PNG per planned\n` +
       `                                     slide into <deck>/concepts/concept-slide-NN.png (bound deck,\n` +
       `                                     pane-free — no PowerPoint window needed).\n` +
@@ -51,19 +56,62 @@ export function printHelp(cmd = null) {
       `                                                          mockup for slides N,M (default: all)\n` +
       `                                     --style <image>[@N,M]    the user's look-and-feel reference,\n` +
       `                                                          leads the generation (repeatable)\n` +
+      `                                     --status  whether a run is in progress and how many mockups and\n` +
+      `                                               specs are on disk (read-only; never starts a run)\n` +
+      `                                     Both flags IMPORT the file into the deck and record it in plan.md\n` +
+      `                                     as an image use (--concept: rebuild this slide; --style: reference).\n` +
+      `                                     A new use re-arms the plan gate — sign off again, then re-run.\n` +
       `                                     --json          machine-readable result (paths, missing, status)\n` +
       `                                     Always ends on one line: CONCEPTS: <n>/<planned> <status>\n` +
-      `  slidemind review <deck>          Open a spatial preview review; blocks until the user\n` +
-      `                                     approves or leaves comments (host-free)\n` +
-      `                                     --port <n>      bind a fixed port (default: ephemeral)\n` +
-      `                                     --allow-draft-defects  open even while the last view-draft's measured defects stand\n` +
+      `                                     With an add-in that extracts concept specs, also writes\n` +
+      `                                     state/concept-specs/concept-slide-NN.json (the mockup's element inventory)\n` +
+      `  slidemind transcribe <deck> --read-spec [--only NN]  Read complete specs through END OF SPEC\n` +
+      `  slidemind transcribe <deck>      Write each slide's JSX skeleton from its concept spec: one element per\n` +
+      `                                     spec line at the spec's slot coordinates, connectors by id, icons as\n` +
+      `                                     ./assets/NN-<icon id>.asset, fetched and renamed to the real file by\n` +
+      `                                     transcribe itself (download-result --name NN-<id>.asset for a miss).\n` +
+      `                                     --only NN      write just this slide (a SELECTION, not permission to rewrite)\n` +
+      `                                     --force        rebuild a slide that already exists from its spec\n` +
+      `                                     --discard-edits  with --force: also rebuild a slide edited since transcribe\n` +
+      `                                     --repair       bounded repair of RECORDED source, inside an open repair scope\n` +
+      `                                                    (\`revision begin <deck> --operation repair --slides <sel>\`;\n` +
+      `                                                    a targeted-edit scope is refused). Runs the WHOLE scope —\n` +
+      `                                                    --only cannot carve a subset out of it. Budget: <=3 passes,\n` +
+      `                                                    <=8 slot-px move and <=10% size change per element measured\n` +
+      `                                                    from the ORIGINAL source, and zero text/asset/element-count/\n` +
+      `                                                    endpoint change. Refuses (before staging anything) unrecorded\n` +
+      `                                                    source, converted source, an unparseable slide, and a bundle\n` +
+      `                                                    with no capture engine. Not combinable with --force/--discard-edits.\n` +
+      `                                     --no-assets    do not fetch or retry the slides' icons/images\n` +
+      `                                     --no-settle    write the JSX as the spec gives it; no geometry settling\n` +
+      `                                     --json         machine-readable result\n` +
+      `                                     A slide edited since transcribe wrote it, and any converted slide, is kept\n` +
+      `                                     byte-for-byte — edit its JSX directly.\n` +
+      `                                     A bare re-run RETRIES assets an earlier run could not resolve, including on\n` +
+      `                                     slides it now skips: the missing picture is fetched without re-extracting\n` +
+      `                                     the spec, regenerating the source or re-settling it. A reference you\n` +
+      `                                     repointed at your own file is left alone.\n` +
+      `  slidemind review <deck>          Spatial preview review (host-free): builds the preview, asks in the\n` +
+      `                                     workspace like \`plan\` and returns at once (ASK + SAY, DECISION:\n` +
+      `                                     pending); the user's pasted message names it again to receive the answer\n` +
+      `                                     --port <n>      standalone page: a fixed port (default: per deck)\n` +
       `  slidemind build-pptx <deck>      Export native .pptx — via the add-in for compose decks (pane-free: the deck's design, else the one design cached/listed; a window only with --to), LOCALLY for template packs (host-free)\n` +
       `                                     --pack <dir>   explicit template-pack directory (plugin integrations)\n` +
       `                                     --to <presId>   target a specific window (required if >1 open)\n` +
       `                                     --out <path>    output path (default <deck>/<deck>.pptx)\n` +
       `                                     --force         discard manual PowerPoint edits instead of reconciling them\n` +
-      `                                     --json          machine-readable result\n` +
-      `                                     (writes per-slide PNGs of the built deck to <deck>/.build-preview/)\n` +
+      `                                     --refresh-design  adopted decks: also re-render the untouched slides onto the current\n` +
+      `                                                     corporate design (by default only what you changed renders)\n` +
+      `                                     --no-publish    keep this build local (see below)\n` +
+      `                                     --json          machine-readable result (\`publish\`: the publish outcome, or null)\n` +
+      `                                     (writes per-slide PNGs of the built deck to <deck>/.slidemind/preview/build/)\n` +
+      `                                     A compose deck connected to SharePoint — the file it was opened from, or a\n` +
+      `                                     folder connected in the workspace — is PUBLISHED right after the build, as\n` +
+      `                                     \`slidemind publish\` would; a publish that did not save exits 2.\n` +
+      `                                     Refuses a slide whose recorded preservation obligations are unmet or\n` +
+      `                                     unproven, naming the elements. A record is seeded by adopt / revision\n` +
+      `                                     begin, so an adopted deck is protected WITHOUT opening a scope; a deck\n` +
+      `                                     authored from scratch has no record and is never gated.\n` +
       `  slidemind inspect-template-deck <deck>  Inspect a template deck as JSON for pack-owned validation\n` +
       `                                     --pack <dir>   explicit template-pack directory (required)\n` +
       `                                     --allow-unrendered-freeform  include JSX inserts without .pptx artifacts\n` +
@@ -71,18 +119,23 @@ export function printHelp(cmd = null) {
       `  slidemind view-draft <deck>      Lint + build the HTML preview, then render the deck's slides to\n` +
       `                                     per-slide PNGs (no push, no .pptx)\n` +
       `                                     so the agent can look before review; host-free once the\n` +
-      `                                     bundle is materialized. Prints the measured defects ([fill:warn], [inventory:warn])\n` +
+      `                                     bundle is materialized. Prints the draft lines (which hold: workflow/create.md\n` +
+      `                                     step 6) and, per unmet preservation obligation, a [preserve:warn] naming the\n` +
+      `                                     element and its repair ([preserve:error] names a preservation record that\n` +
+      `                                     cannot be read).\n` +
+      `                                     review, build-pptx and push refuse a slide never checked, changed since its\n` +
+      `                                     check, or with a measured defect standing.\n` +
       `                                     Also runs the server's export gate on the captured slides (slot-fit,\n` +
-      `                                     diagram geometry, connector endpoints) so build-pptx's 422s surface here.\n` +
+      `                                     diagram geometry, text escape, chrome) so build-pptx's 422s surface here.\n` +
       `                                     --only <file|N>[,…]  render just these slides (a per-slide builder's own check)\n` +
-      `                                     --fix           apply the deterministic lint autofixes first\n` +
+      `                                     --no-fix        skip the deterministic lint autofixes (on by default)\n` +
       `                                     --lint-only     lint + HTML build, no render (fast fix loop)\n` +
       `                                     --strict        converted slides: gate here like review does (they only warn by default)\n` +
       `                                     --no-translate  skip the export gate (purely local check)\n` +
       `                                     --translate     insist on the export gate (fail instead of skipping when the backend is unreachable)\n` +
       `                                     --json          machine-readable result (slides, defects, reviewCanOpen)\n` +
       `                                     --to <presId>   window to fetch the bundle from (only if not cached)\n` +
-      `                                     --out <dir>     output dir (default <deck>/.draft-preview/)\n` +
+      `                                     --out <dir>     output dir (default <deck>/.slidemind/preview/draft/)\n` +
       `                                     --open          open each rendered PNG\n` +
       `  slidemind search "<query>"       Search an engine or scope for images or slides (no window needed on\n` +
       `                                     add-ins that serve the pane-free engine routes; older ones relay\n` +
@@ -92,7 +145,7 @@ export function printHelp(cmd = null) {
       `                                     --result-type <t>  slide | image — required for a scope:* target\n` +
       `                                     --intent <i>    auto | content | visual (slide engines)\n` +
       `                                     --top <N>       max results\n` +
-      `                                     --deck <deck>   route by this deck's bound design (multi-environment)\n` +
+      `                                     --deck <deck>   use this deck's bound design\n` +
       `                                     --to <presId>   pin a window on the relayed path (ignored pane-free)\n` +
       `                                     --json          print the raw result payload (carries the searchId)\n` +
       `  slidemind view-slide [opts]      Fetch a slide search result's preview image to a file\n` +
@@ -113,8 +166,7 @@ export function printHelp(cmd = null) {
       `  slidemind ls engines             List the live engine catalog + search scopes\n` +
       `                                     --type <t>      collection | search | scope\n` +
       `                                     --subtype <s>   image | slide | template | content\n` +
-      `                                     --to <presId>   target a specific window/backend (relayed path only)\n` +
-      `                                     --all          include every paired backend\n` +
+      `                                     --to <presId>   target a specific window (relayed path only)\n` +
       `                                     --json          print the raw engine list\n` +
       `  slidemind insert-slide [opts]    Insert reused slide search results live into a window (requires a host)\n` +
       `                                     --search <id>   searchId from 'slidemind search'\n` +
@@ -131,16 +183,162 @@ export function printHelp(cmd = null) {
       `                                     --json          machine-readable result (carries the searchId)\n` +
       `  slidemind adopt <file.pptx>      Rebuild a deck workspace from a file's embedded source; foreign\n` +
       `                                     slides are converted to editable jsx where the add-in offers it\n` +
+      `                                     Repeatable: the SAME file again rewrites nothing, a wider --slides\n` +
+      `                                     hydrates only the new slides, a DIFFERENT file reconciles onto the\n` +
+      `                                     deck (with unpublished edits it refuses and names 'slidemind rebase')\n` +
       `                                     --deck <slug>   deck folder to write (default: the file's name)\n` +
       `                                     --brand <presFP>  design to convert against (when the file names none)\n` +
+      `                                     --slides <sel>  hydrate only these slides to editable jsx — '2,7',\n` +
+      `                                                     '2-4' or 'all'; every other slide stays a lossless\n` +
+      `                                                     native one-slide .pptx that keeps its notes,\n` +
+      `                                                     comments, animations and embeddings\n` +
       `                                     --no-convert    fold every untagged slide as native .pptx instead\n` +
-      `  slidemind download-result [opts] Download image/icon search result(s) into a deck's assets/\n` +
+      `  slidemind adopt <deck>/.slidemind/slides/<NN-name>.pptx --in-place  Convert ONE folded slide (add-slide) in place to\n` +
+      `                                     editable jsx: same play position, the .pptx is replaced; a slide\n` +
+      `                                     the add-in cannot convert stays native and nothing changes\n` +
+      `  slidemind revision <sub> <deck>  Local revision protocol for an ADOPTED deck: which bytes are the\n` +
+      `                                     accepted base, and which build may replace them\n` +
+      `                                     begin           take ownership for a whole edit session; prints an\n` +
+      `                                                     owner token to export as SLIDEMIND_OWNER so nested\n` +
+      `                                                     commands and parallel lanes re-enter instead of blocking\n` +
+      `                                                     --operation targeted-edit|repair|redesign  declare what this\n` +
+      `                                                       session may do; needs --slides <sel> (a scope with no\n` +
+      `                                                       slides would claim the deck). 'create' is a build's own\n` +
+      `                                                       inference for a new slide and is refused here.\n` +
+      `                                                       The operation PERMITS a named removal; it is not what\n` +
+      `                                                       makes a build a replacement — see build-pptx below.\n` +
+      `                                                     --scope <file.json>  the elements and properties it may touch\n` +
+      `                                     finish          release it — work, candidates and journals are kept\n` +
+      `                                     status          accepted base, generation, dirty slides, added/removed,\n` +
+      `                                                     candidates, staged snapshots, conflicts, owner, journal\n` +
+      `                                     accept          --candidate <id>: make a validated local candidate the\n` +
+      `                                                     accepted base; refuses a stale candidate, a deck with\n` +
+      `                                                     unresolved conflicts, and a remote-bound deck\n` +
+      `                                     --json          machine-readable result (begin | status | accept)\n` +
+      `  slidemind rebase <deck> [opts]   Move an adopted deck onto a newer version of the same file:\n` +
+      `                                     their edits, added/deleted slides and moves apply, reorders on both\n` +
+      `                                     sides combine, local edits stay unpublished against the new base.\n` +
+      `                                     Only a slide BOTH sides changed is a conflict, and it activates\n` +
+      `                                     NOTHING — it writes a conflict manifest plus a resolution skeleton\n` +
+      `                                     with every hash already filled in. There is deliberately no\n` +
+      `                                     generic force flag\n` +
+      `                                     --incoming <file.pptx|revisionId>  the newer file, or a staged one\n` +
+      `                                     --resolve <file.json>  apply the filled-in resolution skeleton\n` +
+      `                                     --dry-run       classify only (incoming-only / local-only / unchanged /\n` +
+      `                                                     conflicts) and write the skeleton if any conflict\n` +
+      `                                     --json          machine-readable result\n` +
+      `                                     (no flags)      finish a rebase that was interrupted partway\n` +
+      `  slidemind open <link|file>       Open a SharePoint presentation as a deck: resolve the item the LINK\n` +
+      `                                     names, take one consistent snapshot, adopt it, and bind the deck to\n` +
+      `                                     that item. A local file path adopts only — it never infers where to\n` +
+      `                                     publish. Metadata in the file never redirects the target\n` +
+      `                                     --deck <slug>   deck folder to write (default: the file's name)\n` +
+      `                                     --slides <sel>  hydrate only these slides to editable jsx (as adopt)\n` +
+      `                                     --rebind        point an already-bound deck at this item instead\n` +
+      `                                     --ordinary      classify unknown origin as ordinary (cannot remove gates)\n` +
+      `                                     --companion id=<file|link>  restore a hash-verified manual companion\n` +
+      `                                     --keep          local file: adopt these bytes, keep publishing where it does\n` +
+      `                                     --detach        local file: forget the binding, make it local-only\n` +
+      `                                     --json          machine-readable result\n` +
+      `  slidemind pull <deck>            Check the bound item and every independently mutable input it names.\n` +
+      `                                     Unchanged costs one metadata call and downloads nothing. A newer save\n` +
+      `                                     stages immutably and is merged in around unpublished local edits;\n` +
+      `                                     only a slide both sides changed stops it (then: slidemind rebase)\n` +
+      `                                     --check         report freshness only (never stages, never rebases)\n` +
+      `                                     --json          machine-readable result\n` +
+      `  slidemind publish <deck>         Publish the accepted candidate back to the bound item: recover, pull,\n` +
+      `                                     rebase, run every required extension's release checks on the FINAL\n` +
+      `                                     bytes, then replace under a server-enforced expected revision. Only a\n` +
+      `                                     confirmed receipt counts as saved; a 412 stages their save instead.\n` +
+      `                                     build-pptx runs this itself for a connected deck; run it to retry one\n` +
+      `                                     whose publish did not save. Unbound with no flags: the folder\n` +
+      `                                     connected in the workspace is the first create's target\n` +
+      `                                     --folder <link> --name <file.pptx>  first create, refusing name conflicts\n` +
+      `                                     --candidate <id>  publish this candidate (default: the newest valid one)\n` +
+      `                                     --manual        prepare the validated handoff without any remote write\n` +
+      `                                     --shared-workbook  declare authority to replace a shared mutable input\n` +
+      `                                                     (without it a changed workbook FORKS, never overwrites)\n` +
+      `                                     --json          machine-readable result\n` +
+      `  slidemind rename <deck> --name <file>  Rename the bound item under its expected revision. Same item, no\n` +
+      `                                     render, no second file; an existing name refuses\n` +
+      `                                     --json          machine-readable result\n` +
+      `  slidemind workspace [<deck>]     The user's workspace: one browser page with the deck library, plan\n` +
+      `                                     and preview review, served by a detached daemon on 127.0.0.1 that\n` +
+      `                                     outlives this shell; \`setup\` starts it at every login. \`plan\`/\`review\`\n` +
+      `                                     ask there (SLIDEMIND_WORKSPACE=0 opts out). An answer given there\n` +
+      `                                     copies a message the user pastes to their agent; it names the run\n` +
+      `                                     that receives it\n` +
+      `                                     (no sub) [<deck>]  start or reuse the daemon, register <deck>, open the page only\n` +
+      `                                                     when none is open, print its sign-in link (Workspace: <link>)\n` +
+      `                                     --no-open       print the link only\n` +
+      `                                     --foreground    stay attached (when the environment forbids a detached process)\n` +
+      `                                     start           start it unless it runs — silent, never opens a browser (the login item runs this)\n` +
+      `                                     status          running | url | pages | protocolVersion | pendingJobs | reason\n` +
+      `                                     stop            drain local commits (<= 5s), keep queued remote work, exit\n` +
+      `                                     add <path>      register one deck folder\n` +
+      `                                     discover <root> remember a root and scan it for decks (no symlinks, no scratch)\n` +
+      `                                     list            registered decks\n` +
+      `                                     open-remote <url>  resolve a SharePoint link (pptx | plan record | hosted page |\n` +
+      `                                                     folder); a folder answers a selection, never a guess\n` +
+      `                                     select <jobId> --selection <id> --choice <id>  pick one child of that selection\n` +
+      `                                     connect <deck> --folder <url> [--name <file.pptx>]  save the deck's SharePoint\n` +
+      `                                                     destination; the plan is created there once it is editable\n` +
+      `                                                     and the backend allows writes (destination-only until then)\n` +
+      `                                     --json          on every subcommand\n` +
+      `  slidemind tasks <sub>            Durable review tasks of a deck (survive agent exit; local, never published)\n` +
+      `                                     list [<deck>] [--status pending]  tasks of one deck or every registered deck\n` +
+      `                                     (agents run \`slidemind plan\` / \`review\`; these are for packs and scripts)\n` +
+      `                                     request <deck> --kind <k>  plan-edit | plan-approval | preview-review;\n` +
+      `                                                     hashes the current subject, dedupes, prints the task, its\n` +
+      `                                                     view's sign-in link and the SAY line; returns at once\n` +
+      `                                     get <deck> <id> the task and its verified outcome (records that you received it)\n` +
+      `                                     wait <deck> <id> [--timeout 45]  scripts only — saved answer first, else a\n` +
+      `                                                     bounded wait; {pending:true} means still waiting\n` +
+      `                                     --json          one JSON value on stdout, diagnostics on stderr\n` +
+      `                                     Exit codes (workspace + tasks): 0 done or read (a pending wait included)\n` +
+      `                                     | 1 operational error | 2 blocked, busy or incompatible | 3 conflict\n` +
+      `  slidemind record <sub>           Share ONE JSON file through the backend, which owns the merge:\n` +
+      `                                     several people and their agents edit the same record and\n` +
+      `                                     different fields combine instead of overwriting. The CLI never\n` +
+      `                                     reads what is in the file — whichever pack owns the schema does\n` +
+      `                                     create <deck> --folder <link> --name <file.json> --file <path>\n` +
+      `                                                     share the file into a SharePoint folder; prints the\n` +
+      `                                                     permanent link colleagues open\n` +
+      `                                     open <link> --deck <slug> --file <path>\n` +
+      `                                                     fetch a shared record into a (new) deck workspace\n` +
+      `                                     sync <deck> --file <path>\n` +
+      `                                                     send your version, get everyone's back merged into\n` +
+      `                                                     <path>; same-field clashes write\n` +
+      `                                                     state/record-conflicts.json and exit 3\n` +
+      `                                       --approval    also send the file's 'approval' field (stripped otherwise)\n` +
+      `                                       --resolve <f> send this resolved version against the conflicts file\n` +
+      `                                     status <deck>   current | behind (v…) | local edits\n` +
+      `                                     --json          machine-readable result on every subcommand\n` +
+      `  slidemind download-result [opts] Download image/icon search result(s) into a deck's assets/ (--name <file> to choose the asset's file name)\n` +
       `                                     --search <id>   searchId from 'slidemind search'\n` +
       `                                     --pick <n,..>   1-based selection number(s)\n` +
       `                                     --deck <deck>   deck to write the asset(s) into\n` +
       `                                     --to <presId>   the window the search ran on (relayed path only)\n` +
       `                                     --icon-color <hex[,hex,..]>  bake a colour into SVG result(s) (one for all, or one per --pick)\n` +
       `                                     --json          machine-readable result (file, size, recolor per pick)\n` +
+      `  slidemind assets <sub>           The deck's image registry — immutable bytes, identified by their own\n` +
+      `                                     digest. Registering an image creates NO obligation to place it:\n` +
+      `                                     what it is FOR is an assetUses record in the plan, approved at the\n` +
+      `                                     plan gate. Import BEFORE you plan — a use names an assetId.\n` +
+      `                                     import <deck> <file>  copy a file in (file paths only, never a URL),\n` +
+      `                                                     sniff its real format + size, verify and record it;\n` +
+      `                                                     the same bytes twice reuse the first assetId\n` +
+      `                                     list <deck>     what this deck has registered\n` +
+      `                                     --json          machine-readable result on both subcommands\n` +
+      `                                   A use is original (place THESE bytes — never searched for, generated\n` +
+      `                                     or substituted), reconstruct (rebuild it as editable slide content;\n` +
+      `                                     reconstructionScope slide | element) or reference (the model sees it,\n` +
+      `                                     no picture required). useId/assetId are durable — keep them byte-\n` +
+      `                                     identical in plan.md, the spec and the slide's data-asset-use.\n` +
+      `                                     view-draft reports unmet obligations; build-pptx/push refuse them.\n` +
+      `                                     Needs an add-in advertising imageIntentV1 (else the command stops\n` +
+      `                                     before generating, with image_intent_unsupported and nothing\n` +
+      `                                     written). Decks with no assetUses are unaffected.\n` +
       `  slidemind imagen "<prompt>"      Generate ONE image with the add-in's image model into a deck's assets/ (paired backend, pane-free)\n` +
       `                                     --deck <deck>   bound deck to write the image into (required)\n` +
       `                                     --out <name>    file name under assets/ (default imagen-N.png)\n` +
@@ -167,13 +365,18 @@ export function printHelp(cmd = null) {
       `                                     --at <index>    insert after slide N (0-based); default = append\n` +
       `                                     --replace       delete existing slides first (destructive)\n` +
       `                                     --slides <ids>  comma-separated source slide ids to push\n` +
-      `                                     --accept-conversions  replace even when a converted slide is unconfirmed\n` +
-      `                                     --force         discard manual PowerPoint edits instead of reconciling them\n` +
+      `                                     --accept-conversions  replace an unconfirmed converted slide (only on the user's go-ahead)\n` +
+      `                                     --force         discard manual PowerPoint edits instead of reconciling them\n` +      `                                     Refuses a slide whose recorded preservation obligations are unmet, same\n` +
+      `                                     as build-pptx; view-draft is where they are reported and repaired.\n` +
+      `  slidemind clean <deck>           Delete the deck's regenerable renders (.slidemind/preview/ and\n` +
+      `                                     abandoned .part downloads). Slides, assets, conversions, state,\n` +
+      `                                     concepts and a download still in flight are never touched\n` +
       `  slidemind login                  Sign in to Microsoft 365 in your browser so SharePoint-backed\n` +
       `                                     slides and images download without an open PowerPoint window\n` +
-      `                                     --backend <url|env>  environment to sign in for (default: the default one)\n` +
-      `  slidemind whoami                 Show every connected environment (* = default)\n` +
-      `  slidemind logout [url|env]       Unpair one environment (--all to unpair every one)\n` +
+      `  slidemind whoami                 Show the connection and its Microsoft 365 sign-in, named as\n` +
+      `                                     the account that signed in\n` +
+      `                                     --json          machine-readable (microsoft365.username = that account)\n` +
+      `  slidemind logout                 Disconnect the CLI (drops its Microsoft 365 sign-in too)\n` +
       `  slidemind init --for <t>         Set up slidemind in a harness (deploys the skill; clears the bundle cache)\n` +
       `                                     <t> = claude | codex | opencode | all | auto (every harness found here)\n` +
       `                                     'setup' already does this — only needed after installing a new agent\n` +
@@ -186,9 +389,10 @@ export function printHelp(cmd = null) {
       `  slidemind --version              Print version\n` +
       `\n` +
       `Install targets: claude | codex | opencode | all\n` +
-      `Decks live in ./decks/ relative to your current directory.\n` +
-      `Override with env: SLIDEMIND_DECKS=/abs/path/to/decks\n` +
-      `Global: --backend <url|env>  scope a command to one paired environment (also SLIDEMIND_BACKEND)\n`;
+      `Decks live in ./decks/ relative to your current directory. A deck keeps its\n` +
+      `deliverables at the root (<slug>.pptx, plan.html) and everything the CLI\n` +
+      `works with in <deck>/.slidemind/ — decks without it are used as-is.\n` +
+      `Override with env: SLIDEMIND_DECKS=/abs/path/to/decks\n`;
   process.stdout.write(cmd ? commandBlock(text, cmd) : text);
 }
 

package/src/cli/install.mjs

@@ -136,6 +136,15 @@ export async function cmdUninstall(rest) {
     value: cleared ? `${cleared} bundle${cleared === 1 ? "" : "s"}` : "empty",
   });
 
+  // Removing slidemind from every harness is removing it: the workspace's login
+  // item goes too (one harness out of several still needs it).
+  if (target === "all") {
+    const { removeAutostart } = await import("../workspace/autostart.mjs");
+    const r = removeAutostart();
+    await ui.section("workspace", "login item");
+    ui.step({ status: "remove", label: "at login", value: r.removed ? "removed" : "none" });
+  }
+
   ui.done(target === "all" ? "removed from all harnesses" : `removed from ${target}`);
 }