slidemind 0.2.2 → 0.2.4

package/.claude-plugin/plugin.json

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

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Connect Codex to the slidemind PowerPoint add-in — build and edit native, on-brand PowerPoint decks against the active corporate design. Requires the slidemind CLI (npm install -g slidemind); the skills explain the install when it is missing.",
   "author": {
     "name": "statworx",
@@ -25,6 +25,13 @@
     "category": "Productivity",
     "capabilities": [
       "Skills"
+    ],
+    "websiteURL": "https://www.statworx.com",
+    "brandColor": "#E07D44",
+    "logo": "./assets/app-icon.png",
+    "screenshots": [],
+    "defaultPrompt": [
+      "Turn this into an on-brand slide deck"
     ]
   }
 }

package/AGENTS.md

@@ -17,13 +17,58 @@ Both drive the same add-in bridge, so an agent and a human end up producing the
 
 The package is published to **public npm** as `slidemind` (`publishConfig.access: public`; license `UNLICENSED` — publicly installable, proprietary). The source lives in a private GitHub repo (`STATWORX/intern-slidemind-cli`); the npm tarball is the install artifact. The CLI is a thin client — the corporate design and the OOXML render live in the slidemind add-in and require an open host — so there is nothing secret in the tarball.
 
-Install + register with a harness:
+**Onboarding is one pasted command.** The add-in's Settings → General → Connect
+CLI → *Set up CLI* mints a claim and prints the whole line:
 
 ```bash
-npm install -g slidemind
-slidemind init --for all          # claude | codex | opencode | all | none
+npx --yes slidemind@latest setup smc1_<claim>
 ```
 
+npx runs the package from its cache but never installs it, so `cmdSetup` does
+the persistent work itself: decode the claim → redeem it → save the session →
+`npm install -g slidemind@latest` → deploy the skills → run `ready`. The user
+needs nothing but Node beforehand, and **there is no `init` step**: `--for auto`
+(the default) resolves through each installer's `detect()` to the coding agents
+actually present, minus any whose slidemind plugin already supplies the skills.
+`init` stays for the manual-install path and for adding a harness later.
+
+`detect()` reads **two** signals and treats either as present: the harness config
+dir (`~/.claude`, `$CODEX_HOME`/`~/.codex`, `~/.config/opencode`) and the harness
+binary on `PATH`. Neither alone is sufficient — those dirs are created the first
+time an agent RUNS, so a just-installed, never-launched agent has none, while a
+desktop-app-only install has no binary. A machine where BOTH miss (e.g. only a
+never-opened desktop app) still ends up connected but skill-less; the remedy is
+`slidemind init --for auto` once the agent has been opened, which is what the
+"none detected" line tells the user.
+
+**Why the claim carries a URL, and why onboarding must start in PowerPoint.**
+Every customer runs its own deployment, so a fresh CLI cannot know which backend
+its user belongs to — there is no address to start an approval at and nothing to
+discover it from. The authenticated add-in knows, so the claim (`smc1_` +
+base64url `{v,u,s}`) carries this deployment's origin next to a one-time secret.
+That is the same property the retired `pair <blob>` flow had; `setup` keeps it
+and removes the steps. **Do not "simplify" this into a CLI-first flow** (a device
+code the CLI mints, a browser PKCE page it opens): both need the backend URL
+*before* they can start, which is the one thing the CLI does not have. The
+backend builds `u` from the configured `FRONTEND_URL`, never from a request
+header — a spoofable header must not end up in a credential the CLI then trusts.
+
+Installation, skill distribution, and CLI authorization stay independent
+underneath. This matters for admin-distributed Codex plugins: the plugin already
+supplies the skills, so those users must **not** plant a second copy — which
+`--for auto` handles by itself, and `setup --for none --no-install` reduces to
+the connection alone.
+
+**mint → redeem is the ONLY way a CLI gets a session.** There is no device code
+and no `slidemind connect`: both were removed because each needs the backend URL
+*before* it can start, which is the one thing the CLI does not have. `ready` on an
+unconnected CLI therefore does not attempt a handshake — it emits a
+`not_connected` blocker naming the add-in button and exits. Consequently the CLI
+hardcodes **no backend URL at all**; `SLIDEMIND_CONNECT_URL` is gone, and
+`--backend`/`SLIDEMIND_BACKEND` only ever *scope* an existing session. The
+retired `slidemind pair <blob>` had the same carries-its-own-address property;
+`setup` keeps it and removes the steps.
+
 `npx slidemind <command>` runs it without a global install. `slidemind update` is a thin wrapper over `npm install -g slidemind@latest` (`--ref <version>` to pin, `--for <target>` to control the redeploy). The `files` whitelist in `package.json` controls what ships (`bin/ src/ skills/ .claude-plugin/ .codex-plugin/ .agents/plugins/ AGENTS.md README.md`); `archive/`, `docs/`, `scripts/`, and `test/` are excluded. Two traps live in that list:
 
 - `.agents/plugins/`, **not** `.agents/` — `files` globs the filesystem rather than git, and `.agents/` also holds gitignored per-developer harness scratch that a bare entry would publish.
@@ -38,7 +83,7 @@ Both agent harnesses can also install slidemind as a **plugin** — this private
 
 > The Codex **admin console** validates harder than the CLI does: it rejects an import when any `interface` block lacks a non-blank `longDescription`, which `codex plugin add` never complains about. `test/plugin-manifests.test.mjs` guards it.
 
-`slidemind init --for <target>` remains the universal fallback on all three harnesses; the Claude installer prints a dedup hint when it detects the plugin is also installed.
+`slidemind init --for <target>` remains the universal fallback on all three harnesses; the Claude and Codex installers each print a dedup hint when they detect the plugin is also installed (`~/.claude/plugins/cache/<marketplace>/slidemind/`, `$CODEX_HOME/plugins/cache/<marketplace>/slidemind/<version>/`). Plugin users only ever need `npm install -g slidemind` for the binary — never `init`, which would plant a second copy of the skills that drifts on the next plugin update. Both skills' *CLI missing* remediation says so, keyed off whether the running `SKILL.md` sits under a plugin cache.
 
 **Updating a plugin-installed CLI is `/plugin`, not `slidemind update`.** The Claude plugin ships its own copy of the CLI on the session's PATH, so `npm install -g slidemind@latest` drops a second, unrelated global and the session keeps running the old binary — a user following that advice would watch the update succeed and stay blocked on the add-in's version floor. `src/install-channel.mjs` detects the channel from the running code's path (plus `CLAUDE_PLUGIN_ROOT`) and every too-old-CLI remediation ends with `updateCliInstruction()`, so the message names the updater that actually replaces this binary; the `cli_update_required` rung of the readiness ladder also flips `actor` to `user` there, because the agent cannot drive `/plugin`.
 
@@ -89,7 +134,7 @@ slidemind/
 ├── .agents/
 │   └── plugins/marketplace.json  Codex marketplace — serves this repo (git clone) as the plugin; NOT in the npm tarball
 ├── bin/
-│   ├── slidemind.mjs             CLI dispatcher (ready, doctor, presentations, read, download-bundle, new, init, build, build-pptx, view-draft, push, ls engines, search, insert-slide, add-slide, install, pair/whoami/use/logout)
+│   ├── slidemind.mjs             CLI dispatcher (setup, connect, ready, doctor, presentations, read, download-bundle, new, init, build, build-pptx, view-draft, push, ls engines, search, insert-slide, add-slide, install, whoami/use/logout)
 │   └── slidemind + slidemind.cmd PATH shims for Claude Code plugin sessions (npm links slidemind.mjs itself)
 ├── skills/                       canonical, installable skill payload — thin CLI workflow glue only
 │   ├── create-slides/
@@ -99,11 +144,13 @@ slidemind/
 │   │                             composition/layouts/authoring/build-export) are READ from the materialized
 │   │                             bundle — owned by the add-in.
 │   └── search/
-│       └── SKILL.md              engine-search + slide-reuse skill (installs as slidemind-search): host gate +
-│                                 discover → search → pick → reuse loop + vocabulary→CLI command map. The craft is
+│       └── SKILL.md              engine-search + slide-reuse skill (installs as slidemind-search): host gate
+│                                 (insert-slide + reading an open deck only) + discover → search → pick → reuse
+│                                 loop + vocabulary→CLI command map. The craft is
 │                                 READ from the bundle's workflow/search.md — owned by the add-in.
 ├── src/                          implementation of the slidemind CLI
-│   ├── bridge/                   add-in local-bridge: client.mjs, bundle.mjs (materialize), build-and-push.mjs (server render; native-slide splicing), engine-download.mjs + recolor.mjs (image/icon fetch + recolour)
+│   ├── bridge/                   add-in local-bridge: client.mjs, bundle.mjs (materialize), build-and-push.mjs (server render; native-slide splicing), engine-download.mjs + recolor.mjs (image/icon fetch + recolour),
+│   │                             setup-claim.mjs (decode/redeem the add-in's one-command claim — the only connect path) + http-json.mjs + config.mjs (per-backend sessions)
 │   ├── builders/                 build.mjs (HTML preview), review.mjs (spatial preview-review gate + local server; stable per-deck port, graceful fallback, tab reuse across rounds), plan.mjs (plan sign-off gate) + plan-overlay.js + plan-md.mjs (markdown→HTML) + gate-server.mjs (shared gate primitives), resolve-skill.mjs (→ bundle), lint.mjs (runs the add-in's engine)
 │   ├── pptx/                     host-free local-.pptx support (fflate-based): read-local.mjs (read a file's slides — output-identical to the host read), slide-swap.mjs (fold a picked slide into a deck as native .pptx — swaps it into the lowest slot the splicer reads, then prunes the package to that slide's dependency closure so a slice carries only what it needs), zip.mjs + ooxml.mjs (shared unzip/order helpers)
 │   └── installers/               per-harness installers: claude.mjs, codex.mjs, opencode.mjs, lib.mjs
@@ -120,8 +167,8 @@ We **do not** ship separate slash commands. Earlier versions had a top-level `co
 ## CLI surface
 
 ```bash
-slidemind ready [deck]             # one-shot session start: connection ladder + design resolution + bundle download + deck bind; --to/--force/--connect-only/--json (HOST REQUIRED)
-slidemind doctor                   # read-only connection diagnostics (ordered next-action ladder; does NOT materialize or bind — `ready` is the preflight)
+slidemind ready [deck]             # one-shot session start: connection ladder + design resolution + bundle download + deck bind; --to/--brand/--force/--connect-only/--json (a BOUND deck, an explicit --brand, or a single listed design readies with PowerPoint closed)
+slidemind doctor                   # read-only diagnostics on TWO independent ladders — backend authoring (session/backend/version/engines) and live PowerPoint (windows/pane); does NOT materialize or bind — `ready` is the preflight
 slidemind presentations            # list PowerPoint windows registered with the add-in
 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 the active corporate design's bundle locally
@@ -129,27 +176,36 @@ slidemind new <name>               # scaffold ./decks/<name>/ (auto-binds to the
 slidemind plan <deck>              # plan sign-off gate on <deck>/plan.md; markdown editor + live preview + overall feedback, blocks for approve/comments (host-free)
 slidemind build <deck>             # build self-contained HTML preview
 slidemind review <deck>            # spatial preview-review gate; blocks for approve/comments (host-free)
-slidemind build-pptx <deck>        # render native .pptx via the add-in (HOST REQUIRED)
+slidemind build-pptx <deck>        # compose: add-in; template pack: host-free with --pack <dir>
+slidemind inspect-template-deck <deck> # normalized pack model for pack-owned validation; --pack <dir> --json
 slidemind view-draft <deck>        # render the deck's slides to per-slide PNGs so the agent can look before review; no push, no .pptx (host-free once the bundle is materialized)
 slidemind push <deck>              # render + push slides into a running PowerPoint (HOST REQUIRED)
-slidemind ls engines               # list the live engine catalog (image + slide; --type/--subtype) (HOST REQUIRED)
-slidemind search "<query>"         # search an engine for imagery or slides (--engine/--intent/--top) (HOST REQUIRED)
+slidemind ls engines               # list the live engine catalog (image + slide; --type/--subtype) (pane-free on add-ins with engineRoutes; HOST REQUIRED on older ones)
+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/--brand-style; paired backend, pane-free)
-slidemind add-slide [opts]         # fold slide(s) into a deck as native .pptx — from an engine (--search/--pick/--deck/--to/--at; HOST REQUIRED) or a local file (--from <file.pptx>/--pick/--deck/--at; host-free, mutually exclusive with --search)
-slidemind pair <code>              # pair with an add-in environment (copy from its "Connect CLI")
-slidemind whoami                   # list every paired environment (* = default)
+slidemind imagen "<prompt>" [opts] # generate ONE image via the add-in's image model into <deck>/assets/ (--deck/--out/--size/--quality/--brand-style; 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 + ready (--for/--no-install/--no-ready/--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 whoami                   # list every connected environment (* = default)
 slidemind use <url|env>            # set the default environment
 slidemind logout [url|env]         # unpair one environment (--all unpairs every one)
-slidemind init --for <target>   # install skill into claude | codex | opencode | all (also clears the bundle cache)
+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)
 ```
 
 `<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 pairing.** 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). Pair once per environment (local / dev / prod) and every command **fans out** across all paired backends, tags each open window with its `env`, and **routes by the presentation's origin backend** automatically — no manual switching. Scope a command to one backend with `--backend <url|env>` (or `SLIDEMIND_BACKEND`). This is a developer convenience; a normal user pairs exactly one. See the memory note *CLI↔add-in: cloud relay + pairing*.
+**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.
+
+**The design truth lives in the add-in, not the CLI.** The `.pptx` is rendered server-side over the local bridge (no local exporter), the corporate design is fetched as a bundle, brand imagery comes from the add-in's engine, and slide reuse (extract / insert / splice) executes in the add-in too. So `create`/`build-pptx`/`push`/`ls engines`/`search`/`insert-slide`/`add-slide` all need the **slidemind add-in with an active corporate design** behind them. The engine-search + slide-reuse wire contract is in `docs/slidemind-cli-connect/11-engine-search-slide-reuse.md`; see `docs/slidemind-cli-connect/` for the rest.
+
+**Engine ops are moving off the task pane.** An add-in that advertises `engineRoutes` in `/api/cli/capabilities` answers discovery, search, download and slide extraction on the CLI session itself (`GET /api/cli/engines`, `POST /api/cli/searches`, `GET /api/cli/searches/:id/results/:sel/{image,thumbnail,slide,source-presentation}`), so those commands need **no PowerPoint window at all** — the searchId is server-owned, `--to` becomes a no-op, and multi-environment routing goes by the deck's bound design (`.bundle-ref.json`), never by an open window's origin. Older add-ins keep relaying every one of them through the pane (`client.resolveEngineBackend()` returns null → `requirePaneHost()`), so **never remove the pane path and never raise `minCliVersion` for this**. Live `insert-slide` and reading an unsaved open deck stay pane-bound — that is Office.js physics, but even there the *extraction* backend is the one that **minted the searchId** (`client.resolveSearchBackend()`), never the target window's origin: with two environments connected those differ, and spending a server-owned id on the wrong one 404s as an "expired search" no re-search can clear.
+
+When the backend's permission snapshot ages out, corpus search (only) answers `403 permissions_stale`, rendered through `client.permissionsStaleBlocker(err)` as one user-actionable line — but the snapshot backs the **pane-free path only**, since a live pane signs every request with a browser token that is strictly fresher. So when a pane-ready window is open, `search` **relays through it** instead of blocking (one stderr note; the searchId is then the pane's, and every next step names that window), and the ops that cannot be replayed pane-side — anything bound to an opaque `searchId` — name that open pane as the route to a fresh search rather than telling the user to open an add-in that is already open. `slidemind ls engines` is the exception: `GET /api/cli/engines` is the catalog route on both add-in generations, so there is no second route to retry on and only the message widens. Plan: `docs/slidemind-cli-connect/13-pane-free-authoring.md`.
+
+**The two ops that stay pane-bound self-heal a presId churn.** Every pane reconnect mints a NEW presId for the same window, so `push`'s insert and `insert-slide` re-list the registry and re-match the window before giving up: `waitForPaneReady` matches the same presId, then `fileName`+`brandId`, then — when a Save-As renamed the window mid-run — the **design fingerprint alone** (`presFP == brandId`), and only when exactly one connected window carries it (two windows on one design are indistinguishable, and pushing into the wrong one is worse than waiting). `engineOpWithPaneWait` takes that window identity plus an opt-in `retargetOnMissing`, which **only the live insert sets**: for an idempotent engine read a 404 is the search record talking, not the window, so waiting on the registry would just stall the agent (`isMissingPresentationError` keeps a coded 404 like `unknown_search` out of it). Both retries re-send the SAME `operationId`, so the pane-side dedup makes them safe; both retry exactly ONCE and then surface the wake-PowerPoint blocker — `push` by saving the rendered `.pptx` next to the deck rather than throwing the bytes away, `insert-slide` by naming the click and the window-free `add-slide` alternative.
 
-**The design truth lives in the add-in, not the CLI.** The `.pptx` is rendered server-side over the local bridge (no local exporter), the corporate design is fetched as a bundle, brand imagery comes from the add-in's engine, and slide reuse (extract / insert / splice) executes in the add-in too. So `create`/`build-pptx`/`push`/`ls engines`/`search`/`insert-slide`/`add-slide` all hard-require an **open PowerPoint host with the slidemind add-in and an active corporate design**. The engine-search + slide-reuse wire contract is in `docs/slidemind-cli-connect/11-engine-search-slide-reuse.md`; see `docs/slidemind-cli-connect/` for the rest.
+**The readiness ladder is two ladders.** `bin/slidemind.mjs` authors them once: `backendBlocker(pub)` (paired → every backend unreachable → CLI below the floor) is what render, bundle and the pane-free engine routes ride on, and `paneBlocker(pub)` (no window → not render-ready → pane suspended) governs only push's insert, `insert-slide` and reading an open presentation. `connectionBlocker = backendBlocker ?? paneBlocker` keeps every pre-existing message byte-identical, `doctor` reports the two separately (`authoring` / `host` in `--json`) so an agent stops reading "pane gone" as "cannot work", and `permissions_stale` is reported as a **degradation** next to the authoring ladder — never a rung, because it must not gate render or bundle. `doctor`'s engine-search line reads the same `capabilities.permissionsStale` flag off `/api/cli/readiness`, so `doctor`, `ls engines` and `search` name ONE cause for that one condition instead of three. `ready`'s ladder for a **bound** deck is session → bundle freshness → (informational) engine + pane reachability: with an empty registry it materializes straight over the brand route instead of sitting out the hydration wait, and when a window IS registered the open add-in stays the design source of truth. An unbound deck with no window resolves through `GET /api/cli/brands` (capability `brandsList`, `client.listBrands()`): one design binds automatically, several stop with `ambiguous_brand` naming `--brand <presFP>`. `client.engineReachability({ backends })` is the engine half of both reports — env labels only, never a URL.
 
 ## External skill packs (this repo ships none)
 
@@ -165,7 +221,18 @@ Some decks build from a **template pack** (`mode: "fill-template"` in the pack's
 
 A pack that declares no `components.canonical` fails loudly in `layoutNumber()` — returning null instead would silently demote every master-backed slide to freeform and build a deck that quietly lost its template.
 
-Packs resolve through `locateSkillDir()` (`src/builders/resolve-skill.mjs`): `$SLIDEMIND_SKILLS_DIR/<name>` → `~/.config/slidemind/skills/<name>` → `<package>/skills/<name>` → the **harness** skill and plugin dirs (`~/.claude`, `~/.codex`, opencode; both `<name>` and `slidemind-<name>`). That last tier is what makes every distribution channel work — a plugin or admin upload lands the pack in a harness directory, never in ours — and it ranks *after* the package so this CLI's own skills are never shadowed by a stale copy.
+The preferred integration is explicit: `slidemind build-pptx <deck> --pack <exact-directory>`.
+The pack directory is resolved by its owning plugin, so the CLI does not need to
+know the plugin name or any harness cache layout. Pack-owned validation can use
+`slidemind inspect-template-deck <deck> --pack <exact-directory> --json`, which
+returns a normalized sequence without running domain-specific rules.
+
+For compatibility, direct builds still resolve through `locateSkillDir()`
+(`src/builders/resolve-skill.mjs`): `$SLIDEMIND_SKILLS_DIR/<name>` →
+`~/.config/slidemind/skills/<name>` → `<package>/skills/<name>` → the **harness**
+skill and plugin dirs (`~/.claude`, `~/.codex`, opencode; both `<name>` and
+`slidemind-<name>`). This fallback remains until external packs migrate to
+explicit paths.
 
 Pack-dependent integration tests belong in the pack's own repo, not here.
 

package/README.md

@@ -21,6 +21,8 @@ Both drive the same add-in bridge, so an agent and a human end up producing the
 
 - [Requirements](#requirements)
 - [Install](#install)
+  - [One command (recommended)](#one-command-recommended)
+  - [Manual install](#manual-install)
   - [Windows](#windows)
   - [macOS](#macos)
   - [Linux](#linux)
@@ -47,19 +49,45 @@ Both drive the same add-in bridge, so an agent and a human end up producing the
 | **PowerPoint** | Microsoft 365, PowerPoint 2021/2019/2016, or PowerPoint on the web — anything that loads Office Add-ins. |
 | **OS** | Windows, macOS, or Linux. See per-OS notes below. |
 
-The CLI reaches PowerPoint through the add-in's **cloud relay** (no localhost, no certificates). Because of that, the machine running the CLI **does not have to be the same machine running PowerPoint** — pair once and commands route to wherever your add-in is registered.
+The CLI reaches PowerPoint through the add-in's **cloud relay** (no localhost, no certificates). Because of that, the machine running the CLI **does not have to be the same machine running PowerPoint** — connect it once and commands route to wherever your add-in is registered.
 
-Commands that read the design, render, push, or reach an engine (`ready`, `download-bundle`, `build-pptx`, `push`, `ls engines`, `search`, `insert-slide`, `add-slide`) **require an open PowerPoint host with the add-in and an active corporate design.** `build`, `review`, and `view-draft` work fully offline against a previously materialized bundle. Reading a local PowerPoint file (`read <file.pptx>`) or folding a slide from one into a deck (`add-slide --from <file.pptx>`) is host-free too — no PowerPoint, no pairing, no bundle needed. `new` scaffolds offline too; when you're paired and a design is open it also best-effort binds the new deck (otherwise it just scaffolds and hints to run `slidemind ready <slug>`).
+Commands that read the design, render, push, or reach an engine (`ready`, `download-bundle`, `build-pptx`, `push`, `ls engines`, `search`, `insert-slide`, `add-slide`) **require an open PowerPoint host with the add-in and an active corporate design.** `build`, `review`, and `view-draft` work fully offline against a previously materialized bundle. Reading a local PowerPoint file (`read <file.pptx>`) or folding a slide from one into a deck (`add-slide --from <file.pptx>`) is host-free too — no PowerPoint, connection, or bundle needed. `new` scaffolds offline too; when you're connected and a design is open it also best-effort binds the new deck (otherwise it just scaffolds and hints to run `slidemind ready <slug>`).
 
 ---
 
 ## Install
 
-The package is published to **public npm** as [`slidemind`](https://www.npmjs.com/package/slidemind). The same two commands work on every platform:
+### One command (recommended)
+
+In PowerPoint, open the **slidemind add-in** → **Settings → General → Connect CLI** → **Set up CLI**, and copy the command it shows. Paste it into your terminal:
+
+```bash
+npx --yes slidemind@latest setup smc1_…
+```
+
+That single command installs slidemind globally, connects it to your account, deploys the skills into every coding agent it finds on this machine, and runs the first readiness check. **There is no `slidemind init` step** — setup detects Claude Code, Codex, and opencode itself (by their config directory *or* their command on your `PATH`, so a freshly installed agent you have not opened yet still counts), and skips any harness whose slidemind plugin already supplies the skills. The only prerequisite is **Node 18+**; you never type a backend address.
+
+If it reports *no coding agent found* — or you install one later — run `slidemind init --for auto` to deploy the skills then.
+
+The copied command carries a one-time claim that works once and expires after about 10 minutes. Copy a fresh one if it lapses.
+
+Flags, if you need them: `--for <claude|codex|opencode|all|auto|none>` overrides harness detection (`auto` is the default; `none` skips skills entirely), `--no-install` skips the global npm install, `--no-ready` skips the closing readiness check.
+
+### Manual install
+
+If your organization distributes the Codex plugin through the admin console, the skills are already present and you only install the CLI binary:
 
 ```bash
 npm install -g slidemind
-slidemind init --for all      # deploy the skill into Claude Code / Codex / opencode
+```
+
+Do not run `slidemind init` for an admin- or plugin-installed skill; that would create a second copy. The package is published to **public npm** as [`slidemind`](https://www.npmjs.com/package/slidemind).
+
+For a standalone/manual install, add the skills after installing the CLI:
+
+```bash
+npm install -g slidemind
+slidemind init --for auto     # deploy the skill into every coding agent found here
 ```
 
 Then confirm it's on your `PATH`:
@@ -68,7 +96,7 @@ Then confirm it's on your `PATH`:
 slidemind --version
 ```
 
-`slidemind init --for <claude|codex|opencode|all|none>` scopes the harness deployment. Use `none` to install the CLI only.
+`slidemind init --for <claude|codex|opencode|all|auto>` scopes the harness deployment; `auto` picks every coding agent found on this machine. You only need `init` if you installed the CLI by hand or added a new coding agent later — the one-command setup above already does it.
 
 > **Heads-up — first install downloads a headless Chrome.** slidemind renders decks by capturing slides with a local headless browser (then assembling the `.pptx` server-side), so `npm install -g slidemind` pulls a pinned Chromium (~150–300 MB) via `puppeteer`'s postinstall. Behind a corporate proxy/firewall this download can fail; set `HTTPS_PROXY` (and, if needed, `PUPPETEER_DOWNLOAD_BASE_URL`) so npm can reach it, or point `PUPPETEER_EXECUTABLE_PATH` at an existing Chrome/Edge. The browser lives in puppeteer's own cache, not the slidemind package.
 
@@ -81,7 +109,7 @@ slidemind runs on native Windows (PowerShell, Windows Terminal, or cmd) — no W
 
    ```powershell
    npm install -g slidemind
-   slidemind init --for all
+   slidemind init --for auto
    slidemind --version
    ```
 
@@ -96,7 +124,7 @@ The global install lands in `%APPDATA%\npm`, which the Node installer puts on yo
 
    ```bash
    npm install -g slidemind
-   slidemind init --for all
+   slidemind init --for auto
    slidemind --version
    ```
 
@@ -108,7 +136,7 @@ npm config set prefix ~/.npm-global
 echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc
 source ~/.zshrc
 npm install -g slidemind
-slidemind init --for all
+slidemind init --for auto
 ```
 
 Credentials are stored under `~/.config/slidemind/`.
@@ -119,7 +147,7 @@ The CLI runs fine on Linux. There's no PowerPoint desktop on Linux, so you'll co
 
 ```bash
 npm install -g slidemind
-slidemind init --for all
+slidemind init --for auto
 slidemind --version
 ```
 
@@ -133,6 +161,8 @@ Run any command without installing globally:
 npx slidemind <command>
 ```
 
+Note that npx only *runs* the package from its cache — it never installs it. That is why the one-command setup above goes through `npx --yes slidemind@latest setup …`: the bootstrap runs from the cache and then performs the persistent `npm install -g` itself.
+
 ### Install as a plugin (Claude Code / Codex)
 
 Both harnesses can install slidemind as a **plugin** instead of the two-command npm flow.
@@ -165,25 +195,34 @@ Codex plugins carry the skills only — the CLI still comes from `npm install -g
 
 ## Connect to PowerPoint
 
-The CLI talks to PowerPoint through the add-in's cloud relay, so you pair once per machine.
+Connecting starts **in PowerPoint**, because that is where slidemind already knows both who you are and which slidemind deployment you belong to. A freshly installed CLI knows neither — every organization runs its own backend, so there is no address it could guess.
 
-1. In PowerPoint, open the **slidemind add-in** task pane → **Settings → General → Connect CLI**, and press **Pair**.
-2. It shows a one-time command (it expires in ~10 min — press **Pair** again for a fresh one). Copy and run it:
+### Copy one command (recommended)
 
-   ```bash
-   slidemind pair <code>
-   ```
+1. In PowerPoint, open the **slidemind add-in** task pane → **Settings → General → Connect CLI** → **Set up CLI**.
+2. Press **Copy command** and paste it into your terminal.
+3. Done. The add-in flips to *Connected* on its own, and the CLI continues into its readiness check — no add-in restart, no backend URL, nothing else to confirm.
 
-3. **Restart the add-in once.** Pairing turns CLI integration on, but the task pane that's already running may not pick up the connection — so close the slidemind task pane and reopen it from the ribbon (if needed, reopen the presentation). The wizard doesn't prompt for this, but a freshly-booted pane is what registers your window with the CLI.
+This is the same command shown under [Install](#one-command-recommended): it works whether or not slidemind is already installed, and re-running it later connects an additional machine.
 
-4. Verify the link:
+### Already installed?
 
-   ```bash
-   slidemind whoami          # lists the paired environment(s)
-   slidemind presentations   # lists open PowerPoint windows the add-in sees
-   ```
+Same panel, same claim — press **CLI already installed?** and it swaps the copied line to the short form, skipping the npx bootstrap:
+
+```bash
+slidemind setup smc1_…
+```
+
+It does exactly the same work: connect, refresh the skills, run `ready`. Add `--no-install --for none` if you want the connection alone and nothing touched.
+
+Either way, verify with:
+
+```bash
+slidemind whoami          # lists connected environment(s)
+slidemind presentations   # lists open PowerPoint windows the add-in sees
+```
 
-If `slidemind presentations` is empty even though PowerPoint is open with the add-in and an active corporate design, restart the add-in (step 3) and retry.
+A setup command works once and expires after about 10 minutes; copy a fresh one from the add-in if that happens.
 
 ```bash
 slidemind logout            # unpair this machine
@@ -199,6 +238,7 @@ slidemind new my-deck             # scaffold ./decks/my-deck/ (auto-binds to the
 slidemind build my-deck           # build a self-contained HTML preview (offline)
 slidemind review my-deck          # spatial preview review: leave comments / approve in the browser (offline)
 slidemind build-pptx my-deck      # render a native .pptx via the add-in (host required)
+                                  # template packs may pass --pack <exact-pack-directory>
 slidemind push my-deck            # stream slides straight into an open PowerPoint (host required)
 slidemind read <presId|file.pptx> # read an open presentation (host required) or a local .pptx on disk (host-free)
 slidemind ls engines              # list the active design's image + slide engines (host required)
@@ -240,6 +280,9 @@ slidemind plan <deck>            Plan sign-off gate on <deck>/plan.md; blocks fo
 slidemind build <deck>           Build a self-contained HTML preview (offline)
 slidemind review <deck>          Spatial preview review; blocks for approve/comments (offline)
 slidemind build-pptx <deck>      Render a native .pptx via the add-in        (host required)
+                                 --pack <dir> for an explicit fill-template pack
+slidemind inspect-template-deck <deck>  Emit a normalized template-deck model for pack validation
+                                 --pack <dir> --json [--allow-unrendered-freeform]
 slidemind view-draft <deck>      Render slides to per-slide PNGs, no push — look before review (offline once cached)
                                  --to <presId> --out <dir> --open
 slidemind push <deck>            Build + push slides into an open PowerPoint  (host required)
@@ -259,11 +302,14 @@ slidemind download-bundle [deck] Materialize the active corporate design locally
 slidemind presentations          List PowerPoint windows registered with the add-in
 slidemind read [presId|file.pptx] Read an open presentation (presId; host required) or a local .pptx on disk (file path; host-free)
                                  --mode summary|raw (default raw) [--to <presId>] [--json]
-slidemind pair <code>            Pair with an add-in (copy the code from "Connect CLI")
-slidemind whoami                 Show paired environment(s)
+slidemind setup <claim>          One-command onboarding: connect + global install + skills + ready
+                                 --for <target> --no-install --no-ready --json
+slidemind whoami                 Show connected environment(s)
 slidemind use <url|env>          Set the default environment
 slidemind logout [url|env]       Unpair an environment (--all unpairs every one)
 slidemind init --for <target>    Install the skill into a harness (clears the bundle cache)
+                                 <target> = claude | codex | opencode | all | auto (every harness found here)
+                                 Not needed after `setup` — only when adding a coding agent later
 slidemind uninstall --for <t>    Remove a previously-installed skill (clears the bundle cache)
 slidemind update [--for <t>]     Fetch the latest release and redeploy
 slidemind --help                 Full usage
@@ -309,20 +355,20 @@ slidemind push my-deck --slides 02,05,07   # push only a subset of source slides
 
 ## Multiple environments (for slidemind developers)
 
-If you run the add-in against more than one backend (local / dev / prod), the CLI is **multi-environment**: pair once per backend and every command automatically discovers your open PowerPoint across all of them, tags each window with its environment, and routes to the right one — no manual switching.
+If you run the add-in against more than one backend (local / dev / prod), the CLI is **multi-environment**: connect once per backend and every command automatically discovers your open PowerPoint across all of them, tags each window with its environment, and routes to the right one — no manual switching.
 
 ```bash
-slidemind pair <local-code> --label local
-slidemind pair <dev-code>   --label dev
-slidemind whoami                           # lists every paired environment (* = default)
+slidemind setup <claim-from-local-add-in> --no-install --for none   # each claim carries its own backend
+slidemind setup <claim-from-dev-add-in>   --no-install --for none
+slidemind whoami                           # lists every connected environment (* = default)
 slidemind presentations                    # windows from all environments, each tagged [env]
 slidemind push my-deck --to <presId>       # routed to whichever environment owns that window
 slidemind use dev                          # set the default environment
-slidemind logout dev                       # unpair one (or --all to unpair every one)
+slidemind logout dev                       # disconnect one (or --all to disconnect every one)
 slidemind --backend local presentations    # scope a single command to one environment
 ```
 
-Each "Connect CLI" code carries its own backend and session token, so pairing is per-environment and routing is automatic. A normal user just pairs one.
+`setup` is the easiest way to add an environment because the claim carries its backend — that is exactly the fact the CLI cannot otherwise know. `--no-install --for none` keeps it to the connection alone, leaving your existing binary and skills untouched. Because the claim carries the backend, there is no environment to select and no URL to configure — the CLI hardcodes no backend at all. Once connected, sessions stay per-environment and routing is automatic. A normal user connects one environment.
 
 ---
 
@@ -334,7 +380,7 @@ slidemind update --ref 0.1.0     # pin a specific version
 slidemind update --for codex     # redeploy into one harness (--for none to skip)
 ```
 
-Equivalently: `npm install -g slidemind@latest && slidemind init --for all`.
+Equivalently: `npm install -g slidemind@latest && slidemind init --for auto`.
 
 ---
 
@@ -344,9 +390,11 @@ Equivalently: `npm install -g slidemind@latest && slidemind init --for all`.
 |---|---|
 | `slidemind: command not found` (or not recognized) | The npm global bin isn't on your `PATH`. Run `npm prefix -g` and add its `bin` (Windows: `%APPDATA%\npm`) to `PATH`, or use `npx slidemind`. |
 | PowerShell: *running scripts is disabled* | npm's `.ps1` shim hit the execution policy. Use `slidemind.cmd <command>`, or `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`. |
-| A command can't reach PowerPoint (empty `presentations`, "no host", nothing seems connected) | Run **`slidemind ready`** — it checks pairing, the connection, the CLI version, and open windows in one shot and prints the single next step to take (open PowerPoint / click the pane / pair / update). |
-| `slidemind presentations` is empty right after pairing (PowerPoint + add-in already open) | The just-paired task pane never registered. **Restart the add-in** — close the slidemind task pane and reopen it from the ribbon (or reopen the presentation). The pairing wizard doesn't prompt for this. |
-| `Not paired` | In the add-in, open **Settings → General → Connect CLI**, press **Pair**, and run the shown `slidemind pair <code>`. Codes are one-time and expire — generate a fresh one if it's stale. |
+| A command can't reach PowerPoint (empty `presentations`, "no host", nothing seems connected) | Run **`slidemind ready`** — it checks the secure connection, backend, CLI version, and open windows in one shot and prints the single next step to take. |
+| `slidemind presentations` is empty immediately after approval | Bring PowerPoint forward and click the slidemind pane once; its authenticated relay reconnects and registers automatically. Reopen the pane only if the Office webview itself is suspended. |
+| `Not connected` / `not_connected` | In **PowerPoint → slidemind → Settings → General → Connect CLI**, press the link button and run the command it shows. |
+| `this setup command has already been used or has expired` | A setup claim works exactly once and lasts ~10 minutes. Copy a fresh one from **Connect CLI → Set up CLI**. |
+| `this slidemind add-in is too old for one-command setup` | That deployment predates the setup route and must be updated before this CLI can connect to it. |
 | `build-pptx` / `push` / `search` error about no host | These require an open PowerPoint host with an active corporate design. `slidemind build` (HTML) is the only fully-offline preview. |
 | `EACCES` on `npm install -g` (macOS/Linux) | Don't `sudo npm`. Use a user-owned Node via [nvm](https://github.com/nvm-sh/nvm) or Homebrew, or run `mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global`, add `~/.npm-global/bin` to `PATH`, then retry. |