slidemind 0.3.19 → 0.4.0

package/AGENTS.md

@@ -141,11 +141,12 @@ Teammates pick up the release with `npm install -g slidemind@latest` (or `slidem
 
 **The update nudge + background self-update** (`src/update-check.mjs`). The version floor above only fires once a CLI is too old to talk to the add-in at all — by then the user is hard blocked. The softer signal runs after **every** command: the npm dist-tag (`https://registry.npmjs.org/slidemind/latest`, override with `SLIDEMIND_REGISTRY_URL`) is fetched at most once per 6h per config dir (`SLIDEMIND_UPDATE_CHECK_INTERVAL_MS`), cached in `<configDir>/update-check.json`, and a newer version prints one line on **stderr** (never stdout — `--json` payloads stay clean). On the npm channel it also spawns a detached `npm install -g slidemind@latest` (log: `<configDir>/update.log`), so the next run is current without anyone typing anything.
 
-Four rules the implementation exists to keep:
+Six rules the implementation exists to keep:
 
 - **After the command, never before.** A background global install replaces the package directory; running it mid-command could pull the rug out from under a dynamic import.
 - **Only the npm channel auto-updates.** `updateChannel()` returns `plugin` (only `/plugin` replaces that binary — a global install lands a second, unused copy), `npx` (nothing to update), `dev` (a checkout, i.e. `npm link` — an install would clobber the developer's symlink, so it is neither updated nor nudged; this is also why the test suite is silent by default, with `SLIDEMIND_UPDATE_CHECK=1` to force it on), or `npm`.
-- **One auto-update attempt per released version per interval.** A root-owned npm prefix makes the install fail forever; the cache records the attempt and the next run says the update did not take instead of respawning it every command.
+- **A write it can't make, it doesn't attempt — it asks for escalated rights instead.** `globalInstallBlock()` (`src/install-channel.mjs`) pre-flights whether a global `npm install -g` could actually replace THIS binary by probe-writing the node_modules that holds slidemind. It can't under a **Codex sandbox** (seatbelt/landlock, detected by `CODEX_SANDBOX` — a confined session that is also the statworx default, where full access is forbidden org-wide) or behind a **root-owned prefix**. In a sandbox the config dir is unwritable too, so the one-attempt record below can never persist and the doomed install would respawn on *every* command while the nudge claimed "updating in the background" — the exact misfire this rung fixes. So when the install is unwritable the CLI does **not** spawn it: the notice (and every version-floor remediation, via `updateCliInstruction(block)`) names `slidemind update` **run with escalated permissions** — approved outside the sandbox, or under `sudo` for a root-owned prefix. The CLI can't escalate itself (any child inherits the sandbox); the message is aimed at the agent/user who can. Do not reintroduce an unconditional background spawn.
+- **One auto-update attempt per released version per interval** (when the install IS writable). The cache records the attempt and the next run says the update did not take instead of respawning it every command.
 - **A version-floor hit forces the check.** When a command dies with `cli_update_required`, `bin/slidemind.mjs` passes `force: true`, which bypasses the 6h cache (it may predate the release that raised the floor) and the one-attempt guard, so the auto-update starts on the very command that hit the floor.
 - **Never fatal, never slow.** Fetch timeout 2s (`SLIDEMIND_UPDATE_CHECK_TIMEOUT_MS`), every failure swallowed. Opt out with `SLIDEMIND_NO_UPDATE_CHECK=1` (silence) or `SLIDEMIND_NO_AUTO_UPDATE=1` (nudge only); `CI` disables the auto-install by itself.
 
@@ -183,15 +184,25 @@ slidemind/
 ├── src/                          implementation of the slidemind CLI
 │   ├── cli/                      the subcommands, one module per job (each <= ~600 lines; ready.mjs is the one 783-line function): common.mjs (paths, fail, deck resolution, gates, lazy loaders) · help · designs · connection (the two readiness ladders) ·
 │   │                             deck (plan/review/imagen/inspect-template-deck/build-pptx/view-draft) · concepts · workspace (new/adopt/push) · engine-helpers + search (search/ls) + slide-reuse (insert-slide/add-slide) + engine-results (view-slide/read-source/download-result) ·
-│   │                             download-bundle · ready · diagnose · read · session (login/whoami/logout) · install (init/uninstall/update) · setup
+│   │                             download-bundle · ready · diagnose · read · record (create/open/sync/status — a shared JSON file, merged by the backend) · session (login/whoami/logout) · install (init/uninstall/update) · setup ·
+│   │                             workspace-ui (workspace start/status/stop/add/discover/open-remote/select/connect — NOT workspace.mjs, which is adoption) · tasks (list/request/get/wait)
+│   ├── workspace/                the persistent local workspace (opt-in SLIDEMIND_WORKSPACE=1; docs/slidemind-cli-connect/21-persistent-workspace.md): lifecycle + daemon (detached process, descriptor, log rotation), registry + discovery (deck library), server + auth + routes + events (loopback API, bootstrap cookie, SSE), operations (per-deck mutation wrapper over acquireOwner), adapters (installed pack subprocess protocol), edit (local save generations), tasks + task-actions (durable review tasks), sync (record queue, refresh, conflicts, shared approval), remote-links + remote-status (link intake, destination), ui/ (vanilla browser page + plan-bridge)
 │   ├── 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/                 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)
+│   ├── 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) + review-overlay.js, plan.mjs (plan sign-off gate) + plan-overlay.js (rail | stage | aside, laid out like the preview gate) + plan-md.mjs (markdown→HTML) + gate-server.mjs (shared gate primitives) + gate-session.js (the ledger/round machinery BOTH gates share) + gate-shell.js (the chrome BOTH gates share: brand bar, buttons, workspace strips, hand-off dialog, veil, rail card styling — never copy any of it into an overlay), 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
 ├── archive/                      retired code/assets (local exporter, icon library, brand design files) — NOT shipped
-├── decks/                        the user's working decks; sources are slides/*.jsx, design via .bundle-ref.json
+├── decks/                        the user's working decks: <slug>.pptx + plan.html at the root,
+│                              everything the CLI works with in <slug>/.slidemind/ (slides/, assets/,
+│                              conversions/, concepts/, state/, preview/) — src/lib/deck-paths.mjs,
+│                              which also owns the three rules a deck lives by: bundle ownership is the
+│                              bundle manifest PLUS matching bytes (never a filename prefix — a user's
+│                              assets/master-data.png is the deck's), plan.html has ONE owner declared in
+│                              state/plan-owner.json (core or an extension; neither overwrites the other's
+│                              page), and a deck without .slidemind/ is its own workspace — until the
+│                              workspace registers it: migrateLegacyDeck then moves the flat layout in
 ├── docs/slidemind-cli-connect/   the connect architecture (bridge contract, bundle, engine, phasing)
 └── test/                         node:test suites (bridge client/bundle/build-and-push/resolve-skill/lint-wrapper/packaging/plugin-manifests/engine-search/native-slides/cli-dispatch/cli-download-result)
 ```
@@ -208,9 +219,9 @@ slidemind ready --diagnose         # read-only report on TWO independent ladders
 slidemind read [presId|file.pptx]  # pull an open presentation's content (presId; HOST REQUIRED) OR read a local .pptx on disk (file path; host-free) — same per-slide output (--mode summary|raw)
 slidemind download-bundle [deck]   # materialize a corporate design's bundle locally — pane-free for a bound deck or --brand <presFP>; a window is only consulted when the design isn't named yet (or --to targets one)
 slidemind new <name>               # scaffold ./decks/<name>/ (auto-binds to the one open design, else the one cached design, when its bundle is already materialized; --brand <presFP> binds to the design the user chose instead; --to/--no-bind)
-slidemind plan <deck>              # plan sign-off gate on <deck>/plan.md; markdown editor + live preview + overall feedback, blocks for approve/comments (host-free)
-slidemind review <deck>            # spatial preview-review gate; blocks for approve/comments (host-free)
-slidemind build-pptx <deck>        # compose: add-in, pane-free (deck binding → the one cached design → the one listed design; a window only with --to or when none of those answers); template pack: host-free with --pack <dir>; never overwrites manual PowerPoint edits — text edits fold back, the rest refuses, --force discards (docs/slidemind-cli-connect/16-manual-edit-reconcile.md)
+slidemind plan <deck>              # plan sign-off gate on <deck>/plan.md: the storyline as a slide rail (drag to reorder, + to insert, × to remove, click the title to rename), the selected storyboard on stage, its layout gallery + details in the aside, a design dropdown over the rail (every design cached on this machine, shown as its name + accent colours; a pick moves the plan's layouts onto that design and rebinds the deck when the answer is sent, and the DECISION output tells the agent to re-read its design.md), one comment box + Send / Approve plan (Approve off while a comment waits; the click copies the message and ONE dialog says to paste it); asks in the workspace and returns at once — ASK + SAY, the agent ends its turn (host-free)
+slidemind review <deck>            # spatial preview-review gate; asks in the workspace and returns at once — ASK + SAY (host-free)
+slidemind build-pptx <deck>        # compose: add-in, pane-free (deck binding → the one cached design → the one listed design; a window only with --to or when none of those answers); template pack: host-free with --pack <dir>; never overwrites manual PowerPoint edits — text edits fold back, the rest refuses, --force discards (docs/slidemind-cli-connect/16-manual-edit-reconcile.md); a compose deck connected to SharePoint (bound file, or a folder connected in the workspace) is PUBLISHED right after the build — `--no-publish` keeps it local, a publish that did not save exits 2
 slidemind inspect-template-deck <deck> # normalized pack model for pack-owned validation; --pack <dir> --json
 slidemind view-draft <deck>        # lint + build the HTML preview (this is where `slidemind build` went), then render the deck's slides to per-slide PNGs so the agent can look before review; --fix applies the deterministic lint autofixes; --lint-only stops after the lint; no push, no .pptx (host-free once the bundle is materialized); --only NN for one slide; the server's export gate (slot-fit/diagram-geometry/connector-endpoints) runs on the captured slides BY DEFAULT — verdict only, skipped with a note when the backend is unreachable (--translate insists, --no-translate skips) — so a slide is proven buildable before review; --json
 slidemind push <deck>              # render + push slides into a running PowerPoint (HOST REQUIRED); --replace reconciles the LIVE deck first (same doc), insert pushes never do
@@ -218,16 +229,410 @@ slidemind ls engines               # list the live engine catalog (image + slide
 slidemind search "<query>"         # search an engine for imagery or slides (--engine/--intent/--top/--deck) (pane-free on add-ins with engineRoutes; HOST REQUIRED on older ones)
 slidemind insert-slide [opts]      # reuse found slide(s) live into a window (--search/--pick/--to/--at) (HOST REQUIRED)
 slidemind imagen "<prompt>" [opts] # generate ONE image via the add-in's image model into <deck>/assets/ (--deck/--out/--size/--quality; connected backend, pane-free)
-slidemind setup <claim>            # one-command onboarding from the add-in's Connect CLI button: redeem the claim + npm install -g + skills + best-effort Microsoft 365 sign-in (TTY only) + ready (--for/--no-install/--no-ready/--no-login/--json)
+slidemind concepts <deck>          # after plan sign-off: one mockup PNG per body slide + (add-ins with `conceptSpecs`) its concept SPEC — concept-slide-NN.spec.json (machine, slot px) and .spec.txt (the element inventory an agent reads); --force regenerates
+slidemind transcribe <deck>        # write each slide's JSX skeleton from its concept spec: one element per spec line at the spec's slot coordinates, connectors by literal id, icons as ./assets/NN-<icon id>.svg; existing slide files kept (--force), --only NN, --json
+slidemind assets <sub>             # the deck's image registry: import <deck> <file> copies a file in, identifies it from its BYTES (sniffed mime + intrinsic size), verifies the digest, dedupes within the deck and records it in state/image-assets.json under assets/local/<assetId>.<ext>; list <deck> reports it. File paths only — no URL fetch — and it infers NO intent: what an image is FOR is an assetUses record in the plan (--json on both)
+slidemind download-result [opts]   # download engine result(s) into <deck>/assets/ (--search/--pick/--deck/--icon-color); --name <file> fixes the asset's file name so a slide can reference it before the download runs
+slidemind setup <claim>            # one-command onboarding from the add-in's Connect CLI button: redeem the claim + npm install -g + skills + best-effort Microsoft 365 sign-in (TTY only) + starts the workspace and registers its login item + ready (--for/--no-install/--no-ready/--no-login/--json)
 slidemind add-slide [opts]         # fold slide(s) into a deck as native .pptx — from an engine (--search/--pick/--deck/--to/--at/--json; pane-free on add-ins with engineRoutes) or a local file (--from <file.pptx>/--pick/--deck/--at; host-free, mutually exclusive with --search)
-slidemind adopt <file.pptx>        # rebuild a deck workspace from a FILE's embedded source; foreign slides convert to editable jsx through the add-in's convert-pptx route where it is served (--deck/--brand/--no-convert) — live decks are add-in-only in v1 (docs/slidemind-cli-connect/14-foreign-slide-conversion.md)
+slidemind adopt <file.pptx>        # rebuild a deck workspace from a file's CURRENT content — embedded source is reused only when proved to still describe the slide, the rest converts or stays lossless native .pptx (--deck/--brand/--no-convert/--slides 2,7|2-4|all). Repeatable: same file is a no-op, a newer one reconciles a clean deck and refuses `needs_reconcile` over unpublished edits (docs 14 + 19)
+slidemind revision <sub> <deck>    # the adopted deck's own state — begin (take ownership for a whole edit session; export the printed token as SLIDEMIND_OWNER so nested commands re-enter) · finish · status [--json] (base, generation, dirty slides, candidates, staged, conflicts) · accept --candidate <id> (local-only; refuses stale, conflicted and remote-bound)
+slidemind rebase <deck>            # move an adopted deck onto a newer save of the same file (--incoming <file.pptx|revisionId>/--dry-run/--json): a conflict is ONLY a slide both sides changed — their edits, adds, deletes and moves apply, reorders on both sides combine, a design change is taken, local edits stay unpublished against the new base. "Changed" is read by meaning (`src/pptx/content-digest.mjs`), never bytes: a PowerPoint save rewrites most parts of a file nobody edited. A conflict activates NOTHING and writes a hash-bound resolution skeleton for --resolve <file>. No generic force flag, on purpose (doc 19)
+slidemind open <link|file.pptx>    # open a SharePoint presentation as a deck — the LINK selects the item (metadata never redirects it), one consistent snapshot is adopted through the same route as `adopt`, and the deck binds to that item. A local path adopts only and infers no destination (--deck/--slides/--rebind/--keep/--detach/--json); doc 20
+slidemind pull <deck>              # check the bound item AND every independently mutable input it names; unchanged = one metadata call and zero content requests. A newer save stages immutably and merges at an owned checkpoint — around unpublished local edits too; only a slide both sides changed stops it (--check/--json)
+slidemind publish <deck>           # (build-pptx runs it for a connected deck; this command retries one that did not save, or does a first --folder create) recover → pull → rebase → required extension release checks on the FINAL bytes → conditional replace under a server-enforced expected revision. Only a confirmed receipt advances the base; a 412 stages their save (--candidate/--manual/--shared-workbook/--json). Every write route is live (proved against the tenant 2026-09-16, doc 20 → Routes); the manual export branch is opt-in (`--manual`), and a deployment with `sharepointPublish` off refuses with `remote_saving_disabled`
+slidemind rename <deck> --name <f> # conditionally rename the bound item: same item, no render, no second file, an existing name refuses
+slidemind record <sub>             # share ONE JSON file through the backend's record service, which owns the three-way merge: create <deck> --folder <link> --name <file.json> --file <path> (prints the permanent link) · open <link> --deck <slug> --file <path> · sync <deck> --file <path> [--approval] [--resolve <file>] · status <deck>. State in `<deck>/.slidemind/state/record.json` (url, eTag, versionLabel, the plan as last RECEIVED, the link, the local file); a same-field clash writes `state/record-conflicts.json` and exits 3. Generic on purpose — the CLI never validates, never merges and never learns what the document means; whichever pack owns the schema does all three
 slidemind login [--backend <url|env>] # sign in to Microsoft 365 (browser + PKCE); usually unnecessary — the first engine command runs this flow ITSELF and blocks until the human finishes (graph-auth `ensureSignedIn`, once per process). One sign-in mints Graph + SharePoint tokens from one refresh token; docs/slidemind-cli-connect/15-graph-delegated-cli.md
-slidemind whoami                   # list every connected environment (* = default) + its Microsoft 365 sign-in state
+slidemind whoami [--json]          # list every connected environment (* = default) + its Microsoft 365 sign-in state, named as the account that signed in (`msGraphUsername`, written at login, dropped with the token). `--json` → `{ environments: [{ label, default, oid, tid, microsoft365: { signedIn, username } }] }` — storage only for the sign-in half, no probe
 slidemind logout [url|env]         # unpair one environment (--all unpairs every one; also drops its Microsoft 365 sign-in)
 slidemind init --for <target>   # install skill into claude | codex | opencode | all | auto (also clears the bundle cache); `setup` already does this
-slidemind uninstall --for <target>   # remove the skill (also clears the bundle cache)
+slidemind uninstall --for <target>   # remove the skill (also clears the bundle cache; --for all also removes the workspace's login item)
 ```
 
+**A build proposes; acceptance is deliberate.** For an adopted deck `build-pptx`
+renders only the slides that changed and applies them to the accepted base, so
+every part the change does not touch keeps its exact bytes — notes, comments,
+animations, embeddings and another add-in's tag parts included. What it writes is
+an immutable CANDIDATE: the build never advances the accepted base and never
+clears the dirty set, which is why `edit → build → build` keeps the first edit.
+Moving the base is the separate `slidemind revision accept <deck> --candidate
+<id>`, and `push` does not do it either — inserting slides into a window certifies
+nothing was saved anywhere. A deck connected to SharePoint is the exception that
+proves the rule: its acceptance door is a confirmed publish receipt, and the build
+walks through it itself (below). The protocol (the three states, ownership, the
+conflict classes, what blocks rather than degrades) is
+`docs/slidemind-cli-connect/19-pptx-first-adoption.md` — read it there, don't
+restate it.
+
+**Four operations, and what each one means today.** An edit names what it is
+allowed to do, so the kind is recorded rather than inferred from the diff it
+produced (`src/lib/edit-operations.mjs`, `OPERATION_KINDS`):
+
+| kind | what it is | how it starts |
+|---|---|---|
+| `create` | genuinely new slides | a build's own inference; **never** something a session claims, so `revision begin --operation create` is refused |
+| `targeted-edit` | change slides that already exist, within a declared scope | `slidemind revision begin <deck> --operation targeted-edit --slides <sel>` |
+| `repair` | bounded geometry/fit repair of existing source | `revision begin <deck> --operation repair --slides <sel>`, then `transcribe --repair` |
+| `redesign` | rebuild a slide against the same identity | `revision begin --operation redesign --slides <sel>` |
+
+`--operation` always needs `--slides`: a scope with no slides would silently
+claim the whole deck.
+
+**`transcribe --repair` is where "an operation is a permission" is clearest.**
+Nothing about a file's own bytes authorizes rewriting it — the recorded `repair`
+scope does, and a `targeted-edit` scope is refused by name. Three consequences
+worth not re-litigating:
+
+- **The scope is the unit.** `--only NN` may confirm a single-slide scope, never
+  carve a subset out of a wider one: a partial run would commit the operation
+  record as done for slides it never touched. The refusal points at
+  `--slides NN` instead.
+- **It is deliberately NOT gated on plan approval.** Repair authors nothing from
+  the plan, the recorded scope is the authorization, and an adopted deck being
+  repaired may have no plan at all — `runRepair` returns before
+  `requirePlanApproved` on purpose. Do not "fix" that later.
+- **It adds no approval step, and re-arms none.** The preview review is
+  one-time per deck (below), so repaired bytes go `view-draft` → deliver like
+  any other change after the approval.
+
+Everything it refuses, it refuses **before staging anything**: an unrecorded
+slide (no `state/transcribed.json` entry — an ancestry question, not a syntax
+one), converted provenance, a current representation the validator cannot parse,
+a bundle with no capture engine, and `--force`/`--discard-edits` alongside it.
+Blocked-not-malformed exits 2, the same code `deck_busy` and a rebase conflict
+use. The budget (`REPAIR_BUDGET`, `src/builders/settle.mjs`) is cumulative **from
+the original source**, not pass to pass: ≤3 mutating passes, ≤8 slot-px travel
+and ≤10% size change per element, zero text/asset/element-count/endpoint change,
+and no font change unless the operation permits it. What the operation authorizes is a **permission**, not a
+detection — it is what lets a named element be removed
+(`permittedChanges`/`applyRequirementAmendment`), and it is read by the draft
+verdict for exactly that. It is **not** how the CLI decides that a build is a
+replacement.
+
+**What a scope does not authorize is refused before anything renders.**
+`view-draft`, `build-pptx` and `push` refuse a slide changed outside the open
+scopes (compared by slide key against `preparedSourceHashes`, so a `-2.jsx`
+sibling reads as appeared) and an import whose pragma was dropped outside a
+redesign (`src/lib/edit-transitions.mjs`). The rule is the shared
+`editTransitionViolation` (`src/lib/edit-operations.mjs`, mirrored) the add-in
+enforces at every write; the CLI's agent writes files itself, so the next
+command that reads the deck is the earliest seam. An authorized restyle flips
+the conversion record to `dialect: "semantic"`, the counterpart of the add-in's
+dialect-sync. View-draft's autofix stays inside an open scope for the same
+reason.
+
+**A targeted edit may restructure, not only retype.** Adding elements,
+regrouping them and changing their relationships are supported inside the
+operation's scope; what is protected is the identities and properties the
+preservation record names, which is a different thing from "text only". Do not
+write guidance that implies an existing slide can only have its words changed.
+
+**Preservation obligations protect a slide whether or not anyone opened a
+scope.** `state/slide-preservation.json` records, per slide identity, what must
+survive an edit. `view-draft` seeds it for every rendered slide that has none,
+from current evidence (its concept spec while transcribe still owns the bytes) —
+the add-in seeds at every render the same way (`preservation-seed.ts`), as guide
+task 5.1 asks for new source too. `revision begin`, `adopt` (restored from the
+package's embedded tags, `src/lib/preservation-tags.mjs`) and `transcribe
+--repair` capture it earlier.
+
+So the gate keys on **the record**, never on an open operation
+(`src/builders/draft-check.mjs` → `preservationBlocker`): a user does NOT have
+to run `revision begin` for an adopted deck to be protected. The two
+moments differ on purpose:
+
+- `view-draft` **reports**: one `[preserve:warn]` per unmet obligation naming
+  the element id and the repair, and a `[preserve:error]` when the record
+  itself cannot be read. Both are measured defects (they hold `review`, and the
+  same line holds the add-in's preview gate). What a draft cannot answer prints
+  nothing: the agent cannot act on it, and delivery names it. The tags, their
+  wording (`preservationFailureLines` / `preservationUnreadableLine`) and their split (`draftLineTier`) live in
+  `draft-lines.mjs`, mirrored into the add-in, so both clients print and
+  classify the same lines.
+- `build-pptx` and `push` **refuse** (`requireSlidesPreserved`, next to
+  `requireReviewApproved` in `src/cli/common.mjs`), naming the slide and the
+  unmet elements.
+
+Delivery refuses on three things: an obligation that is **violated**; bytes that
+have **not been checked** (no verdict, or one bound to earlier source — the
+verdict carries the source hash + requirement-set hash it is bound to, so an edit
+after a draft goes stale rather than certifying the new bytes); and an obligation
+that **could have been proved and was not**.
+
+That third rung is the package channel. `src/pptx/package-evidence.mjs`
+(`composeSlideEvidence`) reads a slide's import (`conversions/<stem>.slide.pptx`)
+and the deck as last delivered (`<deck>/<slug>.pptx`, matched by the GUID in its
+baked source tags, never by position), and `comparePackageEvidence` turns the
+pair into the evidence a connector's endpoints and a native's dependency closure
+actually need. Both packages or neither: comparing a package with itself proves
+only that it exists.
+
+Two things that pairing taught, both load-bearing:
+
+- **A requirement's relationship targets live in three namespaces.** `start`/`end`
+  are element ids the package resolves; `package-part` is a WORKSPACE path the
+  filesystem resolves; `native-slot` is an index into the conversion record's
+  `preserved[]`. Resolving them all against the package's own targets reported
+  `relationship_broken` for a file sitting right there — a **false deletion**,
+  strictly worse than the `unknown` it replaced. `workspaceResolvedTargets`
+  resolves each in the namespace it was minted in, and anything that does not
+  resolve still fails.
+- **The source half must not veto the package.** `checkRequirements` reports every
+  non-`media` scope UNVERIFIED because source bytes cannot prove a text, fill or
+  geometry unchanged. That is "source cannot say", not "nobody can": once the
+  package has spoken, only the source's VIOLATIONS still count (a missing
+  element, a repointed connector, a swapped asset — facts no package makes
+  untrue). Merging its silence in capped every verdict at `unknown` forever.
+
+A slide with **no import baseline** (anything authored rather than converted) has
+no package to be proved against at all, so it ships with its unproven obligations
+NAMED on stderr and its record still reading `unknown` — never a pass. Refusing
+there would demand evidence that cannot exist, which is the outage this rung was
+briefly relaxed to avoid.
+
+> **Closed departure (recorded, not deleted) — and closed PER SLIDE, not
+> wholesale.** Between 5.4 and the package channel landing, `unknown` did not
+> refuse at all. Gating on `passed` alone made **every adopted deck permanently
+> unbuildable, a clean one included**, because `passed` was unreachable for
+> connectors and natives. The relaxation was deliberate and temporary; the
+> channel closed it *wherever the channel reaches* — `packageEvidenceReachable`
+> is evaluated per slide, so one deck can legitimately hold a slide that refuses
+> and a slide that ships with a note. The no-baseline case above is not a
+> leftover to be tidied away: it is the rule's other half.
+
+**Both surfaces follow one rule — *proof is demanded where proof is possible* —
+and they agree on more than the difference suggests.** Each refuses `unknown`
+exactly where `passed` is reachable FOR IT. The CLI's reachability predicate is
+per slide (`packageEvidenceReachable`): true for an adopted slide, **false for a
+concept-authored one**, because `packagePair` finds no
+`conversions/<stem>.slide.pptx` for source that was never imported. The add-in's
+is constantly false — it composes no package evidence at all. So:
+
+| deck | CLI | add-in |
+|---|---|---|
+| authored from scratch, with a connector | ships with the note | ships with the note — **identical** |
+| adopted from a `.pptx` | can prove, and refuses | ships with the limitation |
+
+Only the imported path differs. Do not describe this as "the CLI is stricter";
+describe it as one rule over two different sets of available evidence, and never
+as a way around the CLI's refusal.
+
+Two consequences worth stating rather than rediscovering:
+
+- **An authored slide's connector obligations cannot be proved on either client**,
+  and that is not a gap to close by relaxing the CLI. There is no baseline to
+  compare an authored slide against — one has never existed for source nobody
+  imported.
+- **The add-in will not be catching up soon, for a structural reason.** It
+  deliberately does not persist the conversion-time source package, and the bytes
+  it holds at render time are **pre-splice**, so native objects are still
+  placeholders there. The one obligation package evidence exists to answer is not
+  in those bytes; composing evidence there would look authoritative while being
+  unable to see the thing it checks.
+
+`test/preservation-gate.test.mjs` holds the invariant that keeps this honest:
+*"TRIPWIRE: draft-only evidence must NEVER reach `passed` — a render cannot speak
+for the package"*. That is a permanent property, not a phase gate: a render shows
+that a box painted, never that the thing it stands for survived into the
+delivered file. Do not relax it to make a build green.
+
+The limitation names the slide and the element it could not prove, never a
+generic caveat — a shipped-with-note slide must not be mistakable for a verified
+one.
+
+**Three channels the verdict does NOT bear, stated so nobody assumes them.**
+None is a regression — none was ever covered — but each is a place the gate can
+pass something a person would call a loss.
+
+- **A table's grid structure is not verdict-bearing.** `tableGrid` composes rows,
+  columns and merge continuations as *sibling* evidence, and deliberately not as
+  a property scope: `PROPERTY_SCOPES` is a shared contract
+  (`src/lib/edit-operations.mjs`) and a grid is not one of its seven. So a merged
+  cell that absorbed its neighbour, or a row removed **without losing text**,
+  passes. A row that takes text with it — the ordinary case — IS caught, because
+  `text` is a scope and the package compares it per shape.
+- **Connector endpoint pairing is imprecise with two or more connectors on a
+  slide.** `resolvedTargets` is one global set, so the verdict asks "is this
+  endpoint still on the slide", never "is it still THIS connector's endpoint".
+  Two connectors that swap ends both resolve and both pass. The precise pairing
+  exists — `composeSlideEvidence` returns `connectors[elementId]` as
+  `{start, end}` — and the verdict simply does not consult it. Closing it means
+  changing how `preservationVerdict` resolves relationships, which is a consumed
+  contract; it is not closable from the gate.
+- **`shape.chart` is not the same quantity in both clients.** The CLI's is a
+  DATA-RESIDUE digest (series names, category and value caches, and the formulas
+  they came from — `chartResidue`), chosen because PowerPoint re-serializes a
+  chart on every save and an XML hash reports drift on a deck nobody touched.
+  The add-in's is a hash over its canonical ChartSpec. Both answer "did this
+  chart's data change" and they are **not interchangeable**. Safe today only
+  because a verdict is always computed from ONE composer's own before and after.
+  If a cross-client chart verdict is ever wanted, the add-in adopts the residue —
+  the two must never be quietly assumed comparable.
+
+**Preservation is per ELEMENT, so sub-element content rides on a property
+scope.** A deleted table row leaves `<table id="50">` exactly where it was, so
+identity evidence never sees it. The package's per-shape `text` does —
+`parseTextRuns` walks `a:tbl` — so E09's "drops a table row" **is caught on a
+converted slide**, proved by `test/preservation-gate.test.mjs` → *"E09: a
+dropped table ROW fails on a CONVERTED slide"*. No new scope was needed; `text`
+already covers a table's cells and `chart` a chart's series.
+
+Catching it needs two things at once, and the two places it still fails are
+different from each other:
+
+| origin | protects `text`? | has an import baseline? | row caught? |
+|---|---|---|---|
+| `converted` | yes | yes (`conversions/<stem>.slide.pptx`) | **yes** |
+| `concept` | yes | **no** | no — for want of a baseline, not a scope |
+| `legacy-current` | **no** | no | no — neither |
+
+So the residue is two separate things, neither a missing mechanism: an authored
+slide has no package to be compared against, and what a `legacy-current` slide
+may claim is a **product decision** (`PROTECTED_BY_ORIGIN` grants it only
+`media`/`native` on purpose — its bytes prove an element is present, never which
+of its properties were intended). `test/preservation-gate.test.mjs` →
+*"E09 residue: a table row is NOT caught where no package can be compared"* pins
+both reasons separately, so closing one does not read as closing both.
+
+An intentional removal is cleared by superseding the obligation in a scope,
+never by deleting the record.
+
+**Publishing back to SharePoint is gated on evidence, not on optimism
+(2026-09-15).** `open`/`pull`/`publish`/`rename` talk to the tenant's SharePoint
+origin **directly**, with the delegated SharePoint token `slidemind login`
+already mints — the one documented exception to doc 15's "the token rides the
+bridge wire" doctrine, because a conditional write cannot be proxied honestly and
+the backend has nothing to add to replacing a file the user already named. The
+protocol is `docs/slidemind-cli-connect/20-sharepoint-pull-publish.md`; read it
+there. Four things not to undo:
+
+- **Every write carries the revision it expects to replace.** `If-Match` on the
+  small PUT, on upload-session creation and on the final chunk; a 412 is the
+  mechanism working and is staged for a rebase, never retried. The pull before
+  the write is what catches a foreign save in practice (observed live
+  2026-09-16); the in-upload 412 itself has not been observed. Do not add an
+  unconditional write path, and do not retry a write whose outcome is unknown.
+- **The bearer goes to the configured origin and nowhere else.** Download
+  redirects and upload-session URLs are preauthenticated: they carry their own
+  credential in the query string, so they get no Authorization header and their
+  query is never printed (`redactUrl`).
+- **Reads may retry; a write whose outcome is unknown may not.** It goes to
+  `inspectWriteOutcome`, which answers from content identity. A later save by
+  someone else is never proof that ours failed.
+- **Only a confirmed receipt advances the base.** `acceptCandidate` still refuses
+  a remote-bound deck; `acceptCandidateFromReceipt` is the other door and it
+  checks that the receipt names that candidate's bytes.
+
+**A connected deck publishes at the build, not when an agent remembers to
+(2026-10-12).** A user connected a workspace folder mid-build; the agent had read
+`ready` before the folder existed, built a local `.pptx` and stopped, and nothing
+ever reached SharePoint. A session-start report cannot carry a fact that appears
+later, so the connection is read where the deck CHANGES: `build-pptx` (compose
+path) calls `publishAfterBuild` (`src/cli/remote.mjs`), which publishes when the
+deck has `state/remote.json` or a saved `state/destination.json`, through the same
+`runPublish` the command uses — every gate stays. It never exits mid-build: a
+publish that did not save is printed next to the build and exits 2 (`--json`:
+`publish: { status: "not_published", reason }`). A folder connected AFTER the last
+build is the other seam: the workspace's connect route uploads an approved,
+current candidate at once (`uploadToDestination`, `slidemind publish` as a child)
+and records the outcome in `destination.json`'s `upload` for the card. Template
+packs save no candidate, so their builds do not publish. Two write answers live
+in a destination, never one: `writes` is the shared PLAN record (record service AND
+policy), `publishWrites` the PRESENTATION (`sharepointPublish` alone) — prod ships
+no record service, and the folded flag labelled a publishable deck "read-only".
+
+**The machine reads the image (2026-09-19).** Fourteen sim sessions (x19b–x26) showed a
+coding agent cannot be instructed into transcribing a mockup: the image is opened once,
+elements are missing from the FIRST write, and every self-declared contract (inventory
+form, `// image:` count line) gets edited down instead of honoured (29 of 32 `[image:warn]`s).
+So the see-step moved into the add-in and the first write into the CLI:
+
+- `POST /api/cli/brands/:id/concept-specs` (capability `conceptSpecs`; add-in
+  `concept-spec.ts`) runs the design model over a mockup and returns every element with
+  its rect (mapped from the image's body onto the layout's `[CONTENT]` slot), verbatim
+  text, type role, fill, silhouette, icon query + glyph colour, chart series, and every
+  connector between element ids. `slidemind concepts` writes the complete machine JSON under
+  `state/concept-specs/`; no second editable spec or outline is required. A spec is
+  bound to the mockup bytes it was read from (`imageSha256`, `src/lib/concept-spec-binding.mjs`):
+  transcribe, view-draft and the next `concepts` run take it only while the PNG on disk
+  still hashes to it (an unbound or stale spec is read again, never reused), `concepts`
+  generates only the mockups the plan lacks (a kept mockup keeps its spec; `--force`
+  remakes all), and a replaced mockup takes its spec with it in the same step (x112 GTM:
+  a partial set regenerated whole, slides 1–3 transcribed from pictures that no longer
+  existed). `src/builders/concept-spec.mjs` normalises the spec to the layout's
+  background tone from design.md (a black mockup on a white layout: light text flips to
+  dark, a white card gets `shadow`) and adds `~Npx`, the font size the image shows.
+- `slidemind transcribe <deck>` (`src/builders/transcribe.mjs`, `settle.mjs`) is the
+  first write AND most of the finishing: one JSX element per spec element with three
+  helpers (`B` box, `T` text, `I` icon), every line as a native line directive (below),
+  filled silhouettes as svg polygons, type at the image's measured even-pixel size with single lines no-wrap.
+  Then it **settles**: renders the slides, measures them, and applies three rules (a text
+  past its card grows the card and pushes what sits below; texts on the same pixels move
+  apart; anything past the slot lifts or shrinks its fonts) for up to three passes. Then
+  it **fetches every icon itself** (one engine search per motif, first result, retried
+  with shorter queries, the pre-named file; a miss keeps the unresolved reference and is reported).
+  **The JSX is the only editable artifact.** The spec is a machine intermediate under
+  `state/concept-specs/` (no outline file, nobody edits it); the agent compares PNG pairs
+  and edits the slide JSX like any other slide. `transcribe` stamps what it wrote
+  (`state/transcribed.json`): a slide whose bytes still match is machine-owned (the
+  spec's counts apply, `--force` may rebuild it); one that differs is hand-owned —
+  `transcribe --only NN` then only re-settles it in place (`settle.mjs` reads the
+  helpers back and rewrites the numbers), `--force` refuses unless `--discard-edits`,
+  and `view-draft` skips the count check with a `[spec:note]`. Colours: the spec carries
+  the hex the model saw (`fillHex`, `colorHex`); `design-tokens.mjs` snaps it to the
+  nearest token in `corporate-design.css` (`fillVar` / `colorVar`), and a colour the
+  design lacks (a green status dot on a blue palette) falls back to the tone word and is
+  named in a `note:` — the design's palette is never duplicated in the CLI. The body box
+  is the elements' own bounding box, not the model's, so no empty band opens under a
+  headline. `--no-settle` / `--no-icons` switch the steps off.
+- **Every stroke is one native line (nativeLinesV1, 2026-09-25).** A connector is
+  `<div data-connector>` (`cxnSp`: `data-prst` straight/bent/curved, `data-adj`, `data-rot`,
+  a glued end `#id` + `data-*-site` = an index into the node preset's real cxnLst, a free
+  end `x,y`), a free shape line `<div data-sm-line>` (`arc`, brackets, braces, `blockArc`,
+  `donut`, `ellipse`), a chain `<div data-sm-line-group>` (free pieces only); never svg,
+  never custGeom. `line-native.mjs` `fitNative` picks preset + adjusts by MEASUREMENT with
+  the shared evaluator (`preset-eval.mjs`); a glued relation is always ONE connector at the
+  nearest real site, its deviation a `[line:warn]`. Width and colour are design tokens
+  only: the reader's declared width snaps to `LINE_WEIGHT_RUNGS_PX` (`--bw-*`), never a
+  pixel measurement, and the agent sets final weights by proportion. Settle re-solves only
+  adjusts, turn and a glued end's site; nodes never move. `transcribe` refuses (exit 2) an
+  add-in that answered without `nativeLinesV1` — there is no older markup to fall back to.
+  The directive contract is the add-in's; the replaced attributes (`data-route`,
+  `data-arrow`, `data-head`, `data-bend`, `data-*-side`, `data-sm-glyph`) are refused, not read.
+- Spec extraction runs as a **polled job** (`POST /api/cli/brands/:id/concept-spec-jobs`,
+  capability `conceptSpecJobs`): a sync request died at the ingress's ~240 s on dense
+  slides; the job runs eight slides at once with an 8-minute budget each, the CLI writes
+  each spec as it arrives and prints a heartbeat every 30 s. The model's placeholder
+  grammar for "no text" (`/null`, `><null>`, `/slide`, `s:null`, "There is no text.") is
+  dropped in `cleanText`; it changes between runs, so the filter is by shape, not by list.
+- Result (x35, sol@low, both fixture decks): 0.825 / 0.77 fidelity, both built and
+  review-approved, $3.8, ~19 min each, no subagent, no agent-written JSX. The stock
+  skill's baseline for the same model was 0.69 / 0.62 at $5–8 with 5–20 draft rounds.
+  Hold-out on fresh topics with the general skill: 0.77 / 0.72, both built. Each spec
+  records the backend tokens it cost (`usage`); `scripts/codex-sim-report.mjs` prices
+  them in a `spec` column, so a run's cost is agent + specs (+ mockups via `--price-image`).
+- `view-draft` counts the RENDER (boxes with `imgSrc`, non-native `connector`, `chart`)
+  against the spec's counts — nothing the agent can edit. Without a spec the agent's own
+  `// image:` line is the fallback contract, first count binding. It also names every
+  `./assets/<file>` a slide references that is not on disk (`[asset:error]`, blocking): a
+  transcribed slide references its icons before the fetcher delivers them, and one
+  undelivered file used to surface only as a 422 at `build-pptx`, after review (x28).
+- The transcriber's own lessons, each from a judged run: the image's line breaks are kept
+  (a bullet, number or capital starts a line; lower-case or indented text continues), the
+  model's no-text stand-ins ("/null", ">", "There is no text.") are dropped, a bold lead-in
+  the model lists twice folds into its sentence as `<b>`, chevron/triangle/trapezoid become
+  `clip-path` polygons, a chart without readable values becomes a placeholder plus a
+  `note:` instead of a broken `<Chart>`, thumbnail charts carry no labels, and a plan
+  layout the bundle lacks falls back to a content layout with a `note:` (an agent once
+  spent 11 minutes editing the approved plan over that).
+
+Three add-in gate rules were also corrected on the same evidence: a computed style value
+(ternary/variable) warns as unreadable instead of erroring as "not in the capability
+table" (agents deleted the divider); the arrow-glyph rule is a warning (an axis label in
+the reference is faithful copy); an svg carrying `<text>`, or a lone axis-aligned
+markerless `<line>`, is a figure or a rule — never a bare connector whose ends are gated.
+
 **Bundle freshness is automatic (2026-09-04).** A corporate design can change
 while a session runs, and every local step afterwards — HTML build, lint,
 capture, the draft checks, and the etag the server render is validated against —
@@ -270,6 +675,26 @@ folded names (`build`, `doctor`, `presentations`, `status`, `connection`, `use`,
 `upgrade`) still resolve to a one-line redirect naming the owner — stale skills
 and habits type them — never to a bare "unknown command".
 
+**`--json` stdout carries the payload and nothing else — and that is a test,
+not vigilance.** Three separate leaks of this one class have been found and
+fixed (`ASSETS: n/m fetched`, `Autofixed N lint issue(s)`, and
+`freshenDeckBundle`'s "design bundle updated", which every `--json` command
+calls — so one helper was corrupting `view-draft`, `build-pptx`, `concepts` and
+`push` alike). Three instances is a class, so:
+
+- **Any new human-readable line goes to stderr.** Not "unless `--json`" — to
+  stderr, unconditionally. A line that is only wrong in one mode gets written in
+  the other mode by the next person.
+- **The test for a `--json` command is that its stdout `JSON.parse`s as a single
+  document**, run against a real deck. Asserting that a string moved streams
+  proves the edit; parsing the output proves the property — it is what showed
+  there were two leaks rather than the one that was reported.
+- The same holds for a **withheld mutation**: every guard that declines to
+  rewrite something says what it withheld and why, on stderr. `view-draft --fix`
+  and the `src/builders/build.mjs` dev script both print `[fix:withheld]`; the
+  duplication is deliberate, because sharing the printer would mean reshaping a
+  seam four production commands depend on.
+
 **Agent-facing conventions (2026-09-05).** Every command takes `--help` (its
 own usage block, `src/cli/help.mjs` → `commandBlock`); the deck commands take
 `--json` (`ready`, `view-draft`, `concepts`, `build-pptx`, `download-result`,
@@ -285,6 +710,112 @@ CLI's rendering changes. A fanned-out `ls engines` never opens the browser
 sign-in for an environment nobody asked about (`signIn: false` on the
 multi-environment listing; the refusing env is named in a note instead).
 
+**The preview review is one-time per deck (2026-10-08).** The approval builds
+the deck; every change after it — an edit, a comment on the delivered deck, a
+reconcile fold, a repair, an added slide — goes straight into the `.pptx`, which
+is where the user sees it. So `requireReviewApproved` asks whether the deck
+EVER passed the review (`review.json`'s `approval`, carried through any later
+comments round by `respondPreview`), never whether the slides still match it.
+The hash still binds the ROUND: an answer on since-edited slides is refused as
+`stale_subject`, and a gate asked again answers at once only when the latest
+round approved these exact bytes (`previewApprovedAsIs`). This holds for the
+create-slides skill and for packs like the proposal generator alike. Do not
+bring back "re-review after any slide change" — it made the user approve the
+same deck again for every fix.
+
+A deck adopted from the user's own `.pptx` (the edit route,
+`src/builders/edit-route.mjs` → `isEditRouteDeck`, which both gates import)
+needs no review at all (2026-10-09): it was a deck before any agent touched it,
+so all its edits are "afterwards". The workspace page shows it as *No review
+needed* (`approved.notNeeded`), never as an approval nobody gave, and `ready`'s
+`review` payload separates `current` (delivery may proceed) from `approved` (a
+human approved).
+
+**Every hand-back is a paste (2026-10-09; replaces the 2026-10-07 bounded
+waits).** Nothing can push into an agent session whose turn has ended:
+- the Codex desktop app runs a private app-server that `codex queue` doesn't
+  reach;
+- `codex://threads/<id>?prompt=` only pre-fills, and is undocumented;
+- Claude Code wakes an agent only for a command that agent backgrounded itself.
+
+Waiting didn't close the gap. On 2026-10-08 a Codex agent did as its skill said
+and ended its turn; the approval came 56 s later and went nowhere. So asking and
+answering have one shape everywhere (doc 21 → *Tasks and agent continuation*):
+1. The agent's question command prints `ASK:` + `SAY:` and returns at once.
+2. The agent ends its turn with the SAY line.
+3. The user decides in the workspace; the click copies a message.
+4. The user pastes it; the message carries the command that receives the answer.
+
+Things not to undo:
+
+- **No gate waits, loops or re-runs.** `plan` / `review` / `tasks request` never
+  long-poll; `--wait` and `DECISION: pending → run it again` are gone. `tasks
+  wait` stays for scripts and no skill names it. A wait reintroduces the
+  "maybe an agent is listening" branch, and with it a second thing the page
+  must say.
+- **The page claims nothing about agent processes.** No "delivered", "sending
+  to your agent", "your agent is waiting / away". After every answer it shows
+  the same dialog — "Paste this into your agent chat", then "Copied — press
+  ⌘V there and send." — and it says "Copied" only when a copy path actually
+  succeeded. "Your agent picked
+  it up" appears only once the receipt (`pickedUpAt`) lands, i.e. after the
+  paste. That dialog is the ONE place the page says to paste: the
+  buttons name only the decision (*Approve plan*, *Send 2 comments* — never
+  "& copy message"), and after *Done* nothing repeats it — no strip under the
+  bar, just a neutral "Answer saved" badge whose click reopens the dialog.
+- **The human's instruction is "paste it".** The copied message names the deck,
+  the decision and the receive command (`slidemind plan|review "<path>"`, or
+  `slidemind tasks get "<path>" <id>` for a pack's task). The human never
+  types a command; the agent reads one.
+- **One link per deck and view, and nothing opens a browser on its own.** The
+  link is `/deck/<id>/plan#bootstrap=…` or `/deck/<id>/preview#bootstrap=…`.
+  The Codex desktop app opens local URLs in its own browser pane by default;
+  it was verified 2026-10-09 (sign-in, both copy paths, `confirm()`,
+  notifications). A command that opened Chrome on top of that made two places.
+- **The workspace is always running, and an agent never starts it from a
+  sandbox.** `setup` starts it and registers the login item (doc 21 → *Launch
+  and stop*). With network off, Codex's sandbox can read the config but can't
+  write it, can't keep a detached process and can't even connect to
+  `127.0.0.1`. A sandboxed question with no workspace stops on
+  `workspace_sandboxed`, and the skill re-runs it outside the sandbox. There
+  is no automatic standalone fallback page: a second page on another port is
+  the second link this protocol removed. `SLIDEMIND_WORKSPACE=0` (rollback)
+  and `SLIDEMIND_GATE_AUTOAPPROVE=1` (headless) are the only ways to it.
+- **Decks live where the agent may write.** The skills create a deck under
+  `./decks/<slug>` of the agent's working folder. A path the user names (an
+  RFP, a reference deck) is input that is read, never adopted as the deck
+  folder. Working on a deck elsewhere is the user's explicit choice; there
+  Codex asks "Allow?", and that protection is never routed around through the
+  workspace (which runs outside the sandbox).
+- **A stopped command stops its gate.** `runNode` forwards SIGTERM/SIGINT/SIGHUP
+  to the script it runs (the standalone gate still blocks): a harness signals
+  the pid it started, and an orphaned gate kept its port.
+- **A framed view keeps its navigation; its MESSAGES are the page's.** The
+  plan gate, the review gate and a pack's plan page publish their status line,
+  every banner/notice and the hand-off dialog as one `chrome` object
+  (`slidemind-view-chrome`; doc 21 → *A framed view keeps its navigation*),
+  and the workspace page renders them above the frame. A view's own tabs,
+  title and switches stay inside the frame. Never paint a message inside the
+  frame it is about, and never move a view's navigation out of it.
+- **A state is a badge; a notice is for something the user must do.** The
+  people reading these pages are not technical. Approved (and when), ready for
+  your review, answer saved, the agent revising —
+  each is a few words in the view's status badge, its why in the badge's
+  tooltip (`status.detail`).
+  A notice appears only when the user has to act or something failed. No
+  hashes, error codes, ISO dates or record vocabulary ("amendment draft",
+  "locally", "bound") on screen, and nothing said twice: the review gate owns
+  the stale-preview line, the workspace's connection banner owns "offline",
+  and a status with nothing to say is no badge at all (never "up to date").
+- **No test may reach the real config dir.** A gate test that found the real
+  registry once spawned a real daemon. `npm test` preloads
+  `test/support/isolate-config.mjs` (a private `XDG_CONFIG_HOME` per file);
+  standalone-gate tests also pass `useWorkspace: false`. Nor the real
+  workspace PORT: the preload sets `SLIDEMIND_WORKSPACE_PORT` per file, so no
+  test server calls 57103 home (one took it while the real workspace restarted
+  into new code, and its links went dead). Run single files with
+  `XDG_CONFIG_HOME=$(mktemp -d) node --test --import ./test/support/isolate-config.mjs …`.
+
 `<deck>` resolves as: absolute path → `./<arg>` if it exists → `./decks/<arg>`. The decks directory is `./decks/` by default; override with `SLIDEMIND_DECKS=/abs/path`.
 
 **Multi-environment sessions.** The CLI stores one session **per backend** (`~/.config/slidemind/session.json`, v2 `{version, sessions[], default}`; the legacy single-record v1 shape is migrated on read). Connect once per environment (local / dev / prod) and every command **fans out** across all connected backends, tags each open window with its `env`, and **routes by the presentation's origin backend** automatically — no manual switching. Adding an environment is easiest with `slidemind setup <claim> --no-install --for none` — the claim carries its own backend, so nothing has to be typed or configured. There is no other way in: without a claim the CLI has no backend to talk to. Later commands may scope an existing session with `--backend <url|env>` / `SLIDEMIND_BACKEND`. A normal user connects exactly one backend.
@@ -343,6 +874,8 @@ The corporate design is **served by the add-in, not shipped by the CLI.** `slide
 
 Both skills are **brand-agnostic workflow guidance** and must not duplicate any brand rule — `scripts/check-skill-parity.mjs` (`npm run lint:parity`) scans **every** `skills/<name>/SKILL.md` and fails the build if a hardcoded color, design token, or layout name leaks into any skill doc.
 
+Each `SKILL.md` also has a **byte budget** (`test/packaging.test.mjs` → *every shipped SKILL.md fits in one Codex read*): Codex reads a skill with one capped `cat` and drops the middle of anything longer, which is how the create flow of a 95 KB skill silently never reached the agent (2026-10-11). The authoring craft that is not CLI-specific belongs in the add-in's `references/*.md` (served as the bundle's `workflow/*.md`, read by the CLI agent and the in-app designer alike — when you move a rule there, drop its copy from the designer's `design/prompt.ts` too); a skill keeps the CLI mechanics, each written once, and points at the workflow doc that owns the rest.
+
 ## Sanity rules when editing slides
 
 - One default export per slide file, composing one bundle layout (Mode A) or a blank-content layout with freeform `children` (Mode B) — exactly as the bundle's `design.md` prescribes. No imports — layouts are globals in slide scope at build time.
@@ -356,9 +889,9 @@ Both skills are **brand-agnostic workflow guidance** and must not duplicate any
 ```bash
 slidemind ready <deck>            # do this first: connection ladder + resolve the open design + materialize its bundle + bind the deck (host required)
 slidemind download-bundle <deck>  # lower-level: materialize-only (no connection ladder, no bind) — `ready` now covers this (host-free once the deck is bound)
-slidemind plan <deck>             # plan sign-off gate on <deck>/plan.md; blocks until approve/comments (host-free)
-slidemind review <deck>           # spatial preview-review gate; blocks until approve/comments (host-free)
-slidemind build-pptx <deck>       # native PPTX rendered server-side via the add-in (pane-free; a window only with --to)
+slidemind plan <deck>             # plan sign-off gate on <deck>/plan.md; asks in the workspace, returns at once; a pasted answer is received by running it again (host-free)
+slidemind review <deck>           # spatial preview-review gate; asks in the workspace, returns at once (host-free)
+slidemind build-pptx <deck>       # native PPTX rendered server-side via the add-in (pane-free; a window only with --to); publishes a SharePoint-connected deck too
 slidemind view-draft <deck>       # lint + HTML build, then per-slide PNG draft preview, no push/no .pptx — the agent's look-before-review self-check (host-free once the bundle is cached); --fix autofixes lint
 slidemind push <deck>             # render + push into a running PowerPoint (host required)
 slidemind read [presId|file.pptx] # pull current content of an open presentation (presId; host required) OR read a local .pptx (file path; host-free) (--mode summary|raw)
@@ -366,7 +899,50 @@ slidemind ls engines             # list the live engine catalog (image + slide)
 slidemind search "<query>"        # search an engine for imagery or slides (host required)
 slidemind insert-slide [opts]     # reuse found slide(s) live into a window (host required)
 slidemind add-slide [opts]        # fold slide(s) into a deck as native .pptx — engine (--search; host required) or local file (--from <file.pptx>; host-free)
+slidemind adopt <file.pptx>       # rebuild a deck workspace from a .pptx; --slides 2,7|2-4|all hydrates ONLY those slides to jsx, the rest stay lossless native — repeatable (same file = no-op, wider --slides hydrates the new ones, a different file reconciles)
+slidemind revision <sub> <deck>   # begin (owner token → export SLIDEMIND_OWNER) · status [--json] · accept --candidate <id> (the ONLY local way the base moves) · finish
+slidemind rebase <deck>           # --incoming <file.pptx|revisionId> [--dry-run]: onto a newer copy of the same file; a conflict activates nothing and writes a resolution skeleton for --resolve (no force flag)
 npm run lint:parity               # assert EVERY skill (create-slides + search) carries no brand rules (CI guard)
 ```
 
 No linter beyond the parity guard, `node --test` for the suite, no package manager beyond npm itself. Slide-JSX lint (run by `view-draft` and `review` via `buildDeck`) uses the **add-in's** capability-table engine, materialized into the bundle cache as `lint-engine.mjs` (+ `primitives.json`) and dynamic-imported by `src/builders/lint.mjs` — this repo owns no lint rules; they update on the next bundle fetch. CI (`.github/workflows/test.yml`) runs the suite + parity guard on Linux, **Windows**, and macOS (Node 18 + 22) — the CLI promises native-Windows support, so keep it green there. The HTML preview is self-contained except for React + Babel-standalone pulled from a CDN on first load.
+
+
+## Production x42 authoring parity
+
+The shipped CLI skill runs concepts → transcribe → compare/repair JSX → review → deliver.
+Compact-v1 is the default reader schema; `SLIDEMIND_SPEC_SCHEMA=legacy` explicitly requests the
+older schema. The manual `asset-plan.md` inventory is gone (2026-09-23): `transcribe` records and
+fetches every asset the spec requests (`state/spec-assets.json`), so there is no second list to fill.
+The production add-in mirrors the transcription modules listed in `scripts/sync-transcription-runtime.mjs` from `src/builders/` under
+`src/ui/src/node/agent/runtime/transcription/`. Run `node scripts/sync-transcription-runtime.mjs`
+to check parity, or `--write <addin-repo>` after changing the canonical CLI modules. The plan
+contract travels the same way (storyboard/plan parsers, `plan-checks.mjs`, `plan-comments.mjs`,
+`src/lib/image-intent.mjs` and its fixture): the add-in's plan review and runtime import the
+mirror, so a plan reads, checks and words the same in both clients. Neither
+runtime imports experiments. Existing and reverse-converted slides stay on the source-first
+edit route; concept generation/transcription is not an editing prerequisite.
+
+
+## Measuring a transcription change (2026-09-23)
+
+Single-run sim judge scores cannot resolve a transcription change: run-to-run noise is ~0.06–0.07
+per deck and the concept image is regenerated every run. Measure on the frozen-slide replay instead:
+`scripts/fidelity/replay.mjs --out <dir> <sim task dir>...` re-normalizes each stored reader spec
+with the code under test, re-transcribes offline (icons resolved from the frozen run), captures, and
+scores every element against the reader's spec (`scripts/fidelity/score.mjs`: overlaps the image
+does not have, text escaping its shape, figures merging into their ground, connector path distance
+matched by geometry, glued vs drawn connectors, `--gates` first-draft export-gate errors).
+`scripts/fidelity/compare.mjs <baseline> <candidate>` pairs the slides. One change per comparison;
+never edit `src/` while a replay runs (it spawns the live CLI). `SLIDEMIND_ABLATE=<step,...>` skips
+named normalization steps for an ablation row — a measurement knob, unset in production.
+
+The design palette is authoritative: colour is scored only as structure (a figure must stay apart
+from its ground), never as distance to the concept's colour; icons are judged by placement and
+variety, never by whether the glyph matches the concept's.
+
+Sims run each codex session in its own HOME (`scripts/codex-sim.mjs`): agents read whatever
+`~/.cache` and `~/.config` hold, and before x62 that was this machine's bundle cache and workspace
+registry. `scripts/sim-validity.mjs` → `hostLeaks` marks a session that read host state as
+contaminated. `slidemind workspace status` reports `headless: true` under
+`SLIDEMIND_GATE_AUTOAPPROVE=1`, and the skill continues without a workspace there.