slidemind 0.2.2 → 0.2.3

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "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.3",
   "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/
@@ -103,7 +148,8 @@ slidemind/
 │                                 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
@@ -135,19 +181,19 @@ slidemind push <deck>              # render + push slides into a running PowerPo
 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 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 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; 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 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 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.
 

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
@@ -259,11 +298,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 +351,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 +376,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 +386,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. |