slidemind 0.3.19 → 0.4.0

package/src/cli/workspace-ui.mjs

@@ -0,0 +1,260 @@
+// `slidemind workspace …` — the persistent local workspace (browser UI, deck
+// library, discovery). Adoption/push/new live in workspace.mjs; this module is
+// the UI/process surface only.
+//
+// Exit codes (contracts §1): 0 done, 1 operational error, 2 blocked / busy /
+// incompatible, 3 conflict. Under --json exactly one JSON value goes to stdout;
+// everything else to stderr. The code is set on process.exitCode so bin's
+// post-command hooks still run.
+
+import { addDeck, listDecks } from "../workspace/registry.mjs";
+import { deckRoot } from "../lib/deck-paths.mjs";
+import { resolveDeckArg } from "./common.mjs";
+import { startDiscovery } from "../workspace/discovery.mjs";
+import { daemonRequest, ensureRunning, readDescriptor, registerDeck, stopWorkspace, workspaceStatus } from "../workspace/lifecycle.mjs";
+import { resolveRemoteLink, selectChoice } from "../workspace/remote-links.mjs";
+import { connectDestination, remoteStatus, uploadToDestination } from "../workspace/remote-status.mjs";
+
+const EXIT_BY_CODE = {
+  deck_busy: 2,
+  registry_busy: 2,
+  workspace_upgrade_required: 2,
+  workspace_start_failed: 1,
+  // the workspace cannot run here (an agent sandbox) or is wedged: blocked, not broken
+  workspace_sandboxed: 2,
+  workspace_unresponsive: 2,
+  cli_update_required: 2,
+  path_registered: 3,
+  // remote association: blocked (2) vs a conflict with existing work (3)
+  backend_ambiguous: 2,
+  select_deck: 2,
+  login_required: 2,
+  access_denied: 2,
+  write_disabled: 2,
+  selection_expired: 2,
+  unsupported_link: 2,
+  offline: 2,
+  dirty_target: 3,
+  already_bound: 3,
+  name_exists: 3,
+  cross_tenant: 3,
+};
+const VALUE_FLAGS = ["--deck", "--backend", "--folder", "--selection", "--choice", "--name"];
+
+function parse(rest) {
+  const flags = { json: false, open: true, foreground: false };
+  const positional = [];
+  for (let i = 0; i < rest.length; i++) {
+    const a = rest[i];
+    if (VALUE_FLAGS.includes(a)) {
+      const v = rest[++i];
+      if (v === undefined || v.startsWith("--")) throw Object.assign(new Error(`${a} needs a value`), { code: "usage" });
+      flags[a.slice(2)] = v;
+    } else if (a === "--json") flags.json = true;
+    else if (a === "--no-open") flags.open = false;
+    else if (a === "--foreground") flags.foreground = true;
+    else if (a.startsWith("--")) throw Object.assign(new Error(`unknown flag ${a}`), { code: "usage" });
+    else positional.push(a);
+  }
+  return { flags, positional };
+}
+
+function emit(flags, payload, human) {
+  const write = flags.write ?? ((s) => process.stdout.write(s));
+  write((flags.json ? JSON.stringify(payload) : human) + "\n");
+}
+
+// A settled link job on stdout; blocked/failed set the exit code by its error.
+function finishJob(flags, job) {
+  const base = { jobId: job.id, state: job.state, result: job.result, error: job.error, selection: job.selection ? { selectionId: job.selection.selectionId, expiresAt: job.selection.expiresAt, choices: job.selection.choices, nextCursor: job.selection.cursor } : null };
+  let human;
+  if (job.state === "completed" && job.result?.type === "folder") {
+    human = `select one (selection ${job.result.selectionId}):\n` + job.result.choices.map((c) => `  ${c.id}\t${c.kind}\t${c.name}`).join("\n") + `\n  slidemind workspace select ${job.id} --selection ${job.result.selectionId} --choice <id>`;
+  } else if (job.state === "completed") {
+    human = `${job.result.type} ${job.result.name ?? ""}: ${job.result.existing ? "already registered as" : "opened as"} deck ${job.result.deckId}`;
+  } else {
+    human = `${job.state}: ${job.error?.code} — ${job.error?.message}` + (job.error?.choices ? `\n  choices: ${JSON.stringify(job.error.choices)}` : "");
+  }
+  emit(flags, base, human);
+  if (job.state !== "completed") process.exitCode = EXIT_BY_CODE[job.error?.code] ?? 1;
+}
+
+// A deck argument the way every deck command takes it (a slug under ./decks, a
+// relative or absolute path); its ROOT is what the library registers.
+function deckRootArg(arg) {
+  const ws = resolveDeckArg(arg, { allowUnfinished: true });
+  return deckRoot(ws);
+}
+
+/** Ask the open workspace page to show this deck (SSE `focus`); false when it could not be told. */
+async function focusDeck(deckId) {
+  try {
+    const { status } = await daemonRequest(`/decks/${deckId}/attention`, { method: "POST", body: { focus: true }, timeoutMs: 3000 });
+    return status === 200;
+  } catch {
+    return false;
+  }
+}
+
+export function deckUrl(base, deckId) {
+  return `${base}/deck/${deckId}`;
+}
+
+/**
+ * A signed-in browser link into the live workspace, or null when none is live:
+ * `<url>[/deck/<id>[/plan|/preview|/tasks/<id>]]#bootstrap=<key>`. The key is
+ * the workspace's link key (auth.mjs): the link brings the user there every
+ * time it is clicked, in any browser, and never expires. Asking for it is no
+ * new trust boundary: whoever runs this already holds the CLI bearer from the
+ * user-private config dir. A question's link names its VIEW, never the task, so
+ * it stays right when the agent asks again.
+ */
+export async function browserUrl({ deckId = null, taskId = null, view = null } = {}) {
+  const d = readDescriptor();
+  if (!d || d.malformed) return null;
+  let answer;
+  try {
+    answer = await daemonRequest("/bootstrap", { method: "POST", timeoutMs: 3000 });
+  } catch {
+    return null;
+  }
+  const body = answer.status === 200 ? answer.body : null;
+  if (!body?.token) throw Object.assign(new Error(`workspace refused a sign-in link (HTTP ${answer.status})`), { code: "workspace_start_failed" });
+  const p = deckId ? `/deck/${deckId}${view ? `/${view}` : taskId ? `/tasks/${taskId}` : ""}` : "/";
+  return `${d.url}${p}#bootstrap=${body.token}`;
+}
+
+async function defaultOpen(url) {
+  const { openInBrowser } = await import("../builders/build.mjs");
+  return openInBrowser(url, { quiet: true });
+}
+
+export async function cmdWorkspace(rest, { open = defaultOpen, write = null } = {}) {
+  let flags;
+  try {
+    const parsed = parse(rest);
+    flags = parsed.flags;
+    if (write) flags.write = write; // test seam: capture stdout without patching the stream
+    const [sub, ...args] = parsed.positional;
+    switch (sub) {
+      case "status": {
+        // A headless run (gates auto-approve: no human is there to review)
+        // has no workspace to wait for — the agent goes on without one.
+        const headless = process.env.SLIDEMIND_GATE_AUTOAPPROVE === "1";
+        const s = { ...(await workspaceStatus()), ...(headless ? { headless: true } : {}) };
+        emit(flags, s, s.running ? `workspace running at ${s.url} (pid ${s.pid}, ${s.pendingJobs} pending job(s))` : headless ? "workspace is not running — headless run (gates auto-approve): continue without it" : "workspace is not running");
+        return;
+      }
+      case "start": {
+        // `slidemind workspace start` — what the login item runs (autostart.mjs): start
+        // the workspace unless it runs, silently, and never open a browser
+        const run = await ensureRunning({ note: () => {} });
+        emit(flags, { url: run.url, started: run.started, pid: run.pid, protocolVersion: run.protocolVersion }, `${run.started ? "started" : "running"} — workspace at ${run.url}`);
+        return;
+      }
+      case "stop": {
+        const r = await stopWorkspace();
+        emit(flags, r, r.stopped ? `workspace stopped (${r.pendingJobs} pending job(s) kept on disk)` : "workspace was not running");
+        return;
+      }
+      case "add": {
+        if (!args[0]) throw Object.assign(new Error("usage: slidemind workspace add <path>"), { code: "usage" });
+        const entry = await registerDeck(args[0]);
+        const s = await workspaceStatus();
+        const url = s.running ? deckUrl(s.url, entry.id) : null;
+        emit(flags, { deckId: entry.id, url, path: entry.path, created: entry.created }, `${entry.created ? "registered" : "already registered"} ${entry.path}${url ? `\n${url}` : ""}`);
+        return;
+      }
+      case "discover": {
+        if (!args[0]) throw Object.assign(new Error("usage: slidemind workspace discover <root>"), { code: "usage" });
+        // ponytail: scans in this process until done; the API lane can hand this to the daemon's job route.
+        const { jobId, done } = startDiscovery(args[0]);
+        const job = await done;
+        emit(flags, { jobId, state: job.state, found: job.found.length, warnings: job.warnings }, `${job.state}: ${job.found.length} deck(s) under ${job.root}${job.warnings.length ? ` (${job.warnings.length} warning(s))` : ""}`);
+        if (job.state === "failed") process.exitCode = 1;
+        return;
+      }
+      case "open-remote": {
+        if (!args[0]) throw Object.assign(new Error("usage: slidemind workspace open-remote <url> [--deck <path>] [--backend <env>]"), { code: "usage" });
+        const deckId = flags.deck ? addDeck(flags.deck).id : null;
+        finishJob(flags, await resolveRemoteLink({ url: args[0], backendURL: flags.backend ?? null, deckId }));
+        return;
+      }
+      case "select": {
+        if (!args[0] || !flags.selection || !flags.choice) throw Object.assign(new Error("usage: slidemind workspace select <jobId> --selection <id> --choice <id> [--deck <path>]"), { code: "usage" });
+        const localTarget = flags.deck ? addDeck(flags.deck).id : null;
+        finishJob(flags, await selectChoice(args[0], { selectionId: flags.selection, choiceId: flags.choice, localTarget }));
+        return;
+      }
+      case "connect": {
+        if (!args[0] || !flags.folder) throw Object.assign(new Error("usage: slidemind workspace connect <deck> --folder <url> [--name <file.pptx>] [--backend <env>]"), { code: "usage" });
+        const entry = addDeck(args[0]);
+        const r = await connectDestination({ deckRoot: entry.path, folderRef: flags.folder, pptxName: flags.name ?? null, backendURL: flags.backend ?? null });
+        // a deck built before its folder was connected: that build goes up now
+        const upload = r.shouldPublish ? await uploadToDestination(entry.path) : null;
+        const remote = await remoteStatus(entry.path);
+        const uploaded = upload ? (upload.state === "done" ? `\n  uploaded ${r.destination.pptxName} there` : `\n  ${r.destination.pptxName} was not uploaded (${upload.reason}) — \`slidemind publish ${entry.path}\` retries`) : "";
+        emit(flags, { deckId: entry.id, ...r, upload, remote }, `${entry.name}: destination ${r.destination.folderName ?? r.destination.webUrl} (${r.destination.state}, plan writes ${r.writes}, presentation writes ${r.publishWrites})${r.shouldCreatePlan ? "\n  the plan will be shared there on the next sync" : ""}${uploaded}${r.publishWrites === "disabled" ? "\n  this deployment does not save presentations to SharePoint" : "\n  every build-pptx publishes the presentation there"}`);
+        return;
+      }
+      case "list": {
+        const { decks, total } = listDecks();
+        emit(flags, { total, decks }, decks.map((d) => `${d.missing ? "! " : "  "}${d.name}\t${d.path}`).join("\n") || "no registered decks");
+        return;
+      }
+      case undefined:
+      default: {
+        // `slidemind workspace [<deck>]` — an agent runs this when the user asks
+        // to see the workspace; it starts or reuses the daemon and never strands
+        // the user in a terminal.
+        const deckArg = sub;
+        const run = await ensureRunning({ foreground: flags.foreground });
+        let deckId = null;
+        if (deckArg) deckId = (await registerDeck(deckRootArg(deckArg))).id;
+        const plain = deckId ? deckUrl(run.url, deckId) : run.url;
+        // A page already connected is the user's workspace: no second tab per call.
+        let pages = 0;
+        try {
+          pages = Number((await workspaceStatus()).pages) || 0;
+        } catch {
+          pages = 0;
+        }
+        // One link for both: the tab we open and the line we print for the user to
+        // click, in this browser or any other, as often as they like.
+        // `url` stays the plain base other commands build on; `link` is the one to click.
+        const link = (await browserUrl({ deckId })) ?? plain;
+        let opened = false;
+        let focused = false;
+        if (flags.open && (run.started || pages === 0)) opened = (await open(link)) !== false;
+        else if (flags.open && deckId && pages > 0) focused = await focusDeck(deckId);
+        const where = opened
+          ? "opened in a new browser tab"
+          : focused
+            ? "already open in the user's browser — it now shows this deck (no new tab)"
+            : pages > 0
+            ? "already open in the user's browser (no new tab)"
+            : flags.open
+              ? "could NOT open a browser tab — give the user the link"
+              : "not opened (--no-open)";
+        emit(
+          flags,
+          { url: plain, link, deckId, started: run.started, opened, focused, pages, protocolVersion: run.protocolVersion },
+          `${run.started ? "started" : "reusing"} workspace — ${where}\nWorkspace: ${link}`,
+        );
+        if (run.daemon) {
+          process.stderr.write("slidemind: workspace running in the foreground; Ctrl-C drains and stops it\n");
+          await run.daemon.stopped;
+        }
+      }
+    }
+  } catch (err) {
+    const code = err?.code ?? "error";
+    const exit = code === "usage" ? 1 : EXIT_BY_CODE[code] ?? 1;
+    if (flags?.json) {
+      process.stdout.write(JSON.stringify({ ok: false, error: { code, message: err.message, retryable: exit === 2 } }) + "\n");
+    } else {
+      process.stderr.write(`slidemind: ${err.message}\n`);
+    }
+    process.exitCode = exit;
+  }
+}

package/src/cli/workspace.mjs

@@ -1,7 +1,9 @@
 import fs from "node:fs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
-import { fail, requireReviewApproved, LOCAL_PPTX_RE, resolveDecksDir, resolveDeckArg, splitDeckArg, renderProgressPrinter, freshenDeckBundle, loadBridgeModule, SRC_DIR } from "./common.mjs";
+import { requireAuthorizedEdits } from "./revision.mjs";
+import { fail, requireReviewApproved, requireSlidesDraftChecked, requireSlidesPreserved, LOCAL_PPTX_RE, resolveDecksDir, resolveDeckArg, registerDeckHook, splitDeckArg, renderProgressPrinter, freshenDeckBundle, loadBridgeModule, SRC_DIR } from "./common.mjs";
+import { WORKSPACE_DIRNAME } from "../lib/deck-paths.mjs";
 import { readDesignName } from "./designs.mjs";
 
 // `slidemind adopt <file.pptx> [--deck <slug>] [--brand <presFP>] [--no-convert]`
@@ -11,11 +13,34 @@ import { readDesignName } from "./designs.mjs";
 // conversion route where it is available (`docs/slidemind-cli-connect/
 // 14-foreign-slide-conversion.md`); whatever it declines folds in as native
 // reused .pptx. See also intern-slidemind docs/deck-embedded-source-spec.md.
+// "2,7,10" / "2-4,9" / "all" → [2,3,4,9] (1-based play order), or null for all.
+function parseSlideSelection(raw) {
+  if (!raw || raw === "all") return null;
+  const out = new Set();
+  for (const chunk of String(raw).split(",")) {
+    const range = /^(\d+)\s*-\s*(\d+)$/.exec(chunk.trim());
+    if (range) {
+      const [from, to] = [Number(range[1]), Number(range[2])];
+      if (from < 1 || to < from) fail(`--slides: '${chunk.trim()}' is not a slide range`);
+      for (let n = from; n <= to; n++) out.add(n);
+      continue;
+    }
+    const n = Number(chunk.trim());
+    if (!Number.isInteger(n) || n < 1) {
+      fail(`--slides expects 1-based slide numbers like '2,7' or '2-4', got '${chunk.trim()}'`);
+    }
+    out.add(n);
+  }
+  return [...out].sort((a, b) => a - b);
+}
+
 export async function cmdAdopt(rest) {
   const args = [...rest];
   let deckSlug = null;
   let brand = null;
   let convert = true;
+  let slides = null;
+  let inPlace = false;
   const positional = [];
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -25,8 +50,14 @@ export async function cmdAdopt(rest) {
     } else if (a === "--brand") {
       brand = args[++i] ?? null;
       if (!brand) fail("--brand expects a design id (presFP)");
+    } else if (a === "--slides") {
+      const next = args[++i] ?? null;
+      if (!next) fail("--slides expects slide numbers, e.g. --slides 2,7 or --slides 2-4");
+      slides = parseSlideSelection(next);
     } else if (a === "--no-convert") {
       convert = false;
+    } else if (a === "--in-place") {
+      inPlace = true;
     } else if (a.startsWith("-")) {
       fail(`unknown flag: ${a}`);
     } else {
@@ -35,20 +66,30 @@ export async function cmdAdopt(rest) {
   }
   const pptxArg = positional[0];
   if (!pptxArg) {
-    fail("usage: slidemind adopt <file.pptx> [--deck <slug>] [--brand <presFP>] [--no-convert]");
+    fail(
+      "usage: slidemind adopt <file.pptx> [--deck <slug>] [--brand <presFP>] [--slides <sel>] [--no-convert]\n" +
+        "       slidemind adopt <deck>/.slidemind/slides/<NN-name>.pptx --in-place [--brand <presFP>]",
+    );
   }
   // v1 is FILE decks only. A presId (or any non-file argument) would mean
   // converting a LIVE presentation, which needs slide-export and tag-read
   // events the relay does not have — say so instead of "no such file".
-  const {
-    LIVE_DECK_UNSUPPORTED,
-    adoptDeckFromPptx,
-    convertUntaggedSlides,
-    readSourceDeck,
-  } = await import(pathToFileURL(path.join(SRC_DIR, "lib", "adopt.mjs")).href);
+  const { LIVE_DECK_UNSUPPORTED, adoptWorkspace } = await import(
+    pathToFileURL(path.join(SRC_DIR, "lib", "adopt.mjs")).href
+  );
   if (!LOCAL_PPTX_RE.test(pptxArg)) fail(LIVE_DECK_UNSUPPORTED);
   const pptxPath = path.resolve(pptxArg);
   if (!fs.existsSync(pptxPath)) fail(`no such file: ${pptxArg}`);
+  // A folded slide of an existing deck (`<deck>/.slidemind/slides/NN-*.pptx`, from
+  // add-slide) converts in place only when asked by name: inferring it from
+  // the path would turn any `slides/` folder on disk into a deck and replace
+  // the user's file.
+  if (inPlace) {
+    if (deckSlug || slides || !convert) {
+      fail("--in-place converts one folded slide on its own: `slidemind adopt <deck>/.slidemind/slides/<NN-name>.pptx --in-place [--brand <presFP>]`");
+    }
+    return adoptFoldedSlide(pptxPath, brand);
+  }
   const slug = deckSlug ?? path.basename(pptxPath).replace(/\.pptx$/i, "");
   // The decks dir, not a hardcoded ./decks — otherwise `adopt` writes where no
   // other subcommand looks whenever SLIDEMIND_DECKS is set. A RELATIVE slug
@@ -56,41 +97,97 @@ export async function cmdAdopt(rest) {
   // every other untrusted name in this feature is escape-guarded, and this one
   // rides agent-authored command lines.
   const decksRoot = path.resolve(resolveDecksDir());
-  const deckDir = path.isAbsolute(slug) ? slug : path.resolve(decksRoot, slug);
+  const rootDir = path.isAbsolute(slug) ? slug : path.resolve(decksRoot, slug);
+  // The deck ROOT keeps only the deliverables; the adopted workspace is nested.
+  // An existing flat deck (no `.slidemind/`) is adopted into where it already is.
+  const deckDir = fs.existsSync(path.join(rootDir, "slides"))
+    ? rootDir
+    : path.join(rootDir, WORKSPACE_DIRNAME);
   if (
     !path.isAbsolute(slug) &&
-    (deckDir === decksRoot || !deckDir.startsWith(decksRoot + path.sep))
+    (rootDir === decksRoot || !rootDir.startsWith(decksRoot + path.sep))
   ) {
     fail(
       `--deck '${slug}' escapes the decks directory (${decksRoot}) — ` +
         "pass an absolute path to adopt somewhere else on purpose",
     );
   }
-  // ONE read/unzip/tag-decode of the source file, threaded into both halves —
-  // they must see the same snapshot (and a 40 MB deck decodes slowly).
-  const source = readSourceDeck(pptxPath);
-  const converted = convert
-    ? await convertUntaggedSlides({
-        pptxPath,
-        deckDir,
-        brandId: brand,
-        note: (line) => process.stderr.write(`${line}\n`),
-        source,
-      })
-    : null;
-  const result = adoptDeckFromPptx({ pptxPath, deckDir, converted, source });
+  // Adoption is repeatable, so it runs under the deck's own ownership: a second
+  // `adopt` while a session is mid-edit must queue behind it, not race it.
+  fs.mkdirSync(deckDir, { recursive: true });
+  const { acquireOwner } = await import(
+    pathToFileURL(path.join(SRC_DIR, "lib", "revision.mjs")).href
+  );
+  let held;
+  try {
+    held = acquireOwner(deckDir, { command: "adopt" });
+  } catch (err) {
+    if (err?.code === "deck_busy") fail(err.message, 2);
+    throw err;
+  }
+
+  let outcome;
+  try {
+    outcome = await adoptWorkspace({
+      pptxPath,
+      deckDir,
+      brandId: brand,
+      slides,
+      convert,
+      owner: held.token,
+      note: (line) => process.stderr.write(`${line}\n`),
+    });
+  } catch (err) {
+    if (err?.code === "needs_reconcile") fail(err.message, 2);
+    throw err;
+  } finally {
+    held.release();
+  }
+  registerDeckHook(deckDir);
+
   // A decks dir outside the cwd (SLIDEMIND_DECKS) relativizes to ../../.. noise
   // — print the absolute path there instead.
-  const shown = path.relative(process.cwd(), deckDir);
+  const shown = path.relative(process.cwd(), rootDir);
+  const where = shown.startsWith("..") ? rootDir : shown;
+
+  if (outcome.mode === "unchanged") {
+    process.stdout.write(
+      `${slug} is already adopted from this exact file — nothing was rewritten.\n` +
+        `Hydrate more slides to editable jsx with \`slidemind adopt ${pptxArg} --deck ${slug} --slides <n,m>\`.\n`,
+    );
+    return;
+  }
+  if (outcome.mode === "hydrated") {
+    process.stdout.write(
+      `Hydrated ${outcome.hydrated.length} slide(s) of ${slug} to editable jsx: ${outcome.hydrated.join(", ")}\n` +
+        `The rest of the deck, and any edits in progress, were left untouched.\n`,
+    );
+    return;
+  }
+  if (outcome.mode === "rebased") {
+    const r = outcome.rebase;
+    process.stdout.write(
+      `${slug} was already adopted, so this file was reconciled onto it (generation ${r.generation}):\n` +
+        `  refreshed from the newer file: ${r.refreshed.length}\n` +
+        `  removed (deleted there):       ${r.removed.length}\n` +
+        (r.stillDirty.length ? `  still unpublished locally:     ${r.stillDirty.join(", ")}\n` : ""),
+    );
+    return;
+  }
+
+  const result = outcome.result;
   process.stdout.write(
     `Adopted ${result.adopted.length} slide(s) with embedded source` +
       (result.converted.length
-        ? `, converted ${result.converted.length} foreign slide(s) to editable jsx`
+        ? `, converted ${result.converted.length} slide(s) from their CURRENT content to editable jsx`
         : "") +
       (result.native.length
-        ? ` and folded ${result.native.length} untagged slide(s) as native .pptx`
+        ? ` and kept ${result.native.length} slide(s) as lossless native .pptx`
+        : "") +
+      ` into ${where}/ (workspace ${path.basename(deckDir) === WORKSPACE_DIRNAME ? `${WORKSPACE_DIRNAME}/` : "."}).\n` +
+      (slides
+        ? `Only slide(s) ${slides.join(", ")} were hydrated; the rest keep their notes, comments and native objects verbatim.\n`
         : "") +
-      ` into ${shown.startsWith("..") ? deckDir : shown}/.\n` +
       (result.skipped.length
         ? `${result.skipped.length} slide(s) stayed native: ` +
           `${result.skipped
@@ -100,10 +197,53 @@ export async function cmdAdopt(rest) {
       (result.bundle?.presFP && result.bundle.presFP !== "unknown"
         ? `Deck bound to bundle ${result.bundle.presFP}.\n`
         : `No bundle reference found in the file — run 'slidemind download-bundle ${slug}' before rendering.\n`) +
+      `The file you adopted is the accepted base; a build proposes a candidate and never replaces it ` +
+      `until \`slidemind revision accept ${slug} --candidate <id>\`.\n` +
       `Edit slides/*.jsx and run 'slidemind push ${slug}' or 'slidemind build-pptx ${slug}'.\n`,
   );
 }
 
+async function adoptFoldedSlide(pptxPath, brand) {
+  const deckDir = path.dirname(path.dirname(pptxPath));
+  const { convertFoldedSlide, notFoldedReason } = await import(
+    pathToFileURL(path.join(SRC_DIR, "lib", "convert-folded.mjs")).href
+  );
+  const notFolded = notFoldedReason(pptxPath);
+  if (notFolded) fail(notFolded, 2);
+  const { acquireOwner, journalIncomplete } = await import(
+    pathToFileURL(path.join(SRC_DIR, "lib", "revision.mjs")).href
+  );
+  const unfinished = journalIncomplete(deckDir);
+  if (unfinished) fail(`this deck has an unfinished ${unfinished.op}; finish it before converting a slide.`);
+  let held;
+  try {
+    held = acquireOwner(deckDir, { command: "adopt" });
+  } catch (err) {
+    if (err?.code === "deck_busy") fail(err.message, 2);
+    throw err;
+  }
+  let out;
+  try {
+    out = await convertFoldedSlide({
+      pptxPath,
+      deckDir,
+      brandId: brand,
+      owner: held.token,
+      note: (line) => process.stderr.write(`${line}\n`),
+    });
+  } catch (err) {
+    if (["not_folded", "not_one_slide", "local_dirty", "not_converted"].includes(err?.code)) fail(err.message, 2);
+    throw err;
+  } finally {
+    held.release();
+  }
+  process.stdout.write(
+    `Converted ${out.replaced} to editable jsx in place: slides/${out.file} (same play position; the .pptx is gone).\n` +
+      (out.route === "source" ? "Its embedded slidemind source was restored verbatim.\n" : "It is converted-dialect jsx: edit it per workflow/edit.md.\n") +
+      (out.warnings.length ? `Notes: ${out.warnings.join("; ")}\n` : ""),
+  );
+}
+
 export async function cmdPush(rest) {
   const { deck, passthrough } = splitDeckArg(rest, "push");
   let to = null;
@@ -149,6 +289,10 @@ export async function cmdPush(rest) {
     fail(`expected 'slides/' folder in ${deckDir}`);
   }
   await requireReviewApproved(deckDir);
+  requireAuthorizedEdits(deckDir);
+  await requireSlidesPreserved(deckDir);
+  // A push renders the whole deck, so every authored slide needs its check.
+  await requireSlidesDraftChecked(deckDir);
   await freshenDeckBundle(deckDir);
 
   const mod = await import(
@@ -164,9 +308,18 @@ export async function cmdPush(rest) {
     force,
     onProgress: renderProgressPrinter(),
   });
-  for (const w of result.warnings ?? []) {
+  // Classed by the shared draft-line table, as build-pptx classes them.
+  const { splitPackageLines, packageDefectsText } = await import(
+    pathToFileURL(path.join(SRC_DIR, "builders", "draft-check.mjs")).href
+  );
+  const lines = splitPackageLines(result.warnings);
+  for (const w of lines.notes) {
     process.stderr.write(`  warning: ${w}\n`);
   }
+  if (lines.defects.length > 0) {
+    process.exitCode = 1;
+    process.stdout.write(packageDefectsText(lines.defects, deck));
+  }
   for (const s of result.skippedSlides ?? []) {
     process.stderr.write(`  skipped ${s.stem}: ${s.reason}\n`);
   }
@@ -188,10 +341,16 @@ export async function cmdNew(rest) {
   let to = null;
   let brand = null;
   let noBind = false;
+  // Every deck command takes --json; agents reach for it here too (a failed
+  // `new --json` cost a round in three sim sessions). The human lines still
+  // print; the payload is appended for the parser.
+  let asJson = false;
   const positional = [];
   for (let i = 0; i < rest.length; i++) {
     const a = rest[i];
-    if (a === "--to") {
+    if (a === "--json") {
+      asJson = true;
+    } else if (a === "--to") {
       to = rest[++i];
       if (!to) fail("--to expects a presId");
     } else if (a === "--brand") {
@@ -209,15 +368,18 @@ export async function cmdNew(rest) {
     fail("--brand and --to are mutually exclusive (a design id or a window, not both)");
   }
   const name = positional[0];
-  if (!name) fail("usage: slidemind new <name> [--brand <presFP> | --to <presId>] [--no-bind]");
+  if (!name) fail("usage: slidemind new <name> [--brand <presFP> | --to <presId>] [--no-bind] [--json]");
   if (!/^[a-z0-9][a-z0-9-]*$/i.test(name)) {
     fail(`deck name must be kebab-case alphanumerics, got '${name}'`);
   }
   const decksDir = resolveDecksDir();
-  const deckDir = path.join(decksDir, name);
-  if (fs.existsSync(deckDir)) {
-    fail(`deck already exists: ${deckDir}`);
+  const rootDir = path.join(decksDir, name);
+  if (fs.existsSync(rootDir)) {
+    fail(`deck already exists: ${rootDir}`);
   }
+  // Two halves from the first command: the root holds what the user will want
+  // (the .pptx, plan.html), `.slidemind/` everything the CLI works with.
+  const deckDir = path.join(rootDir, WORKSPACE_DIRNAME);
   fs.mkdirSync(path.join(deckDir, "slides"), { recursive: true });
   fs.writeFileSync(
     path.join(deckDir, "plan.md"),
@@ -226,10 +388,26 @@ export async function cmdNew(rest) {
       `the slidemind-create-slides skill fills this in, then writes slides under ./slides/\n` +
       `as NN-<topic>.jsx (zero-padded prefix — slide order is filename order).\n`,
   );
-  process.stdout.write(`Created ${path.relative(process.cwd(), deckDir)}\n`);
+  const { writePlanPage } = await import(
+    pathToFileURL(path.join(SRC_DIR, "builders", "plan.mjs")).href
+  );
+  writePlanPage(deckDir);
+  registerDeckHook(deckDir);
+  process.stdout.write(`Created ${path.relative(process.cwd(), rootDir)} (workspace ${WORKSPACE_DIRNAME}/)\n`);
   process.stdout.write(
     `Next: ask your agent to author "${name}", then \`slidemind view-draft ${name}\`\n`,
   );
+  if (asJson) {
+    process.on("exit", () => {
+      let bound = null;
+      try {
+        bound = JSON.parse(fs.readFileSync(path.join(deckDir, "state", "bundle-ref.json"), "utf8"));
+      } catch {}
+      process.stdout.write(
+        `${JSON.stringify({ deck: name, dir: rootDir, workspace: deckDir, bound: bound?.presFP ?? null })}\n`,
+      );
+    });
+  }
 
   // Stateless auto-bind: bind the fresh deck to whatever design is OPEN so the
   // agent skips a follow-up `download-bundle`. Best-effort — a bind miss (no