slidemind 0.2.1 → 0.2.3

package/.agents/plugins/marketplace.json

@@ -0,0 +1,29 @@
+{
+  "name": "slidemind",
+  "interface": {
+    "displayName": "slidemind",
+    "shortDescription": "On-brand PowerPoint decks from your coding agent",
+    "longDescription": "slidemind connects Codex to the slidemind PowerPoint add-in over its local bridge, so the agent can build and edit native .pptx decks against whatever corporate design the add-in has active. It is brand-agnostic: the corporate design, the layout palette, and the OOXML render all live in the add-in, and the agent reads every brand rule from the design bundle it serves. This marketplace publishes the slidemind plugin, which carries the authoring and search skills. The slidemind CLI itself is installed separately from public npm (npm install -g slidemind); the skills explain that step when the command is missing."
+  },
+  "plugins": [
+    {
+      "name": "slidemind",
+      "description": "Build and edit native, on-brand PowerPoint decks against the active corporate design.",
+      "source": {
+        "source": "local",
+        "path": "./"
+      },
+      "policy": {
+        "installation": "AVAILABLE",
+        "authentication": "ON_INSTALL"
+      },
+      "category": "Productivity",
+      "interface": {
+        "displayName": "slidemind",
+        "shortDescription": "On-brand PowerPoint decks from Codex",
+        "developerName": "statworx",
+        "longDescription": "Adds two skills. slidemind-create-slides owns the intake, plan, create and edit workflow that turns per-slide sources into an editable .pptx rendered by the add-in, plus a local HTML preview. slidemind-search discovers and reuses existing slides and brand imagery from the corporate design's engines, or from a PowerPoint file on disk. Both are brand-agnostic and read the active corporate design's rules, layout palette, and authoring workflow from the design bundle the add-in serves. Requires the slidemind CLI (npm install -g slidemind) and an open PowerPoint with the add-in for anything that renders or reads a live deck."
+      }
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "slidemind",
-  "version": "0.2.1",
+  "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.1",
+  "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",
@@ -20,10 +20,18 @@
   "interface": {
     "displayName": "slidemind",
     "shortDescription": "On-brand PowerPoint decks from Codex",
+    "longDescription": "Adds two skills. slidemind-create-slides owns the intake, plan, create and edit workflow that turns per-slide sources into an editable .pptx rendered by the add-in, plus a local HTML preview. slidemind-search discovers and reuses existing slides and brand imagery from the corporate design's engines, or from a PowerPoint file on disk. Both are brand-agnostic and read the active corporate design's rules, layout palette, and authoring workflow from the design bundle the add-in serves. Requires the slidemind CLI (npm install -g slidemind) and an open PowerPoint with the add-in for anything that renders or reads a live deck.",
     "developerName": "statworx",
     "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/{CLAUDE.md → AGENTS.md}

@@ -1,6 +1,6 @@
-# CLAUDE.md
+# AGENTS.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Guidance for coding agents working in this repository. `CLAUDE.md` is a symlink to this file — there is ONE guidance document, so edit it here and every harness sees the change. (It used to be two near-identical files kept in sync by hand, which drifted.)
 
 ## Project purpose
 
@@ -17,21 +17,73 @@ 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 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/ CLAUDE.md README.md`); `archive/`, `docs/`, `scripts/`, `test/`, and `.agents/` are excluded.
+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.
+- `AGENTS.md`, **not** `CLAUDE.md` — `CLAUDE.md` is a symlink and **npm silently drops symlinks from the tarball**, so listing it would ship nothing at all. The repo keeps the symlink for local harness convenience; the package ships the real `AGENTS.md`.
+
+A packaging test guards both.
 
 Both agent harnesses can also install slidemind as a **plugin** — this private repo doubles as the marketplace (a public marketplace repo can be split out later; the files move as-is). The marketplace is named `slidemind`, NOT `statworx`: the team already registers a `statworx` marketplace from `STATWORX/intern-marketplace-test`, and both harnesses allow only one marketplace per name.
 
-- **Claude Code** (one step, no `npm -g`): `/plugin marketplace add STATWORX/intern-slidemind-cli` → `/plugin install slidemind@slidemind`. The marketplace entry (`.claude-plugin/marketplace.json`) points at the **public npm package, unpinned** — Claude installs the latest tarball and the installed version comes from the tarball's `.claude-plugin/plugin.json`, so only the marketplace add needs repo access. The tarball's `bin/slidemind` + `bin/slidemind.cmd` shims land on PATH inside plugin sessions, so the plugin carries the CLI too.
-- **Codex**: `codex plugin marketplace add STATWORX/intern-slidemind-cli` → `codex plugin add slidemind@slidemind`. Codex clones the repo (marketplace file `.agents/plugins/marketplace.json`; plugin manifest `.codex-plugin/plugin.json`; plugin source = repo root) and carries the skills only — the CLI still arrives via `npm install -g slidemind`, which the skills' remediation covers.
+- **Claude Code** (one step, no `npm -g`, **no GitHub account**): `/plugin marketplace add https://unpkg.com/slidemind/.claude-plugin/marketplace.json` → `/plugin install slidemind@slidemind`. A Claude marketplace source may be a plain HTTPS URL, and an npm CDN serves files straight out of the published tarball — which ships `.claude-plugin/marketplace.json`. So the marketplace needs no repo of its own and follows releases automatically (no version in the URL, no version pin in the plugin entry). `https://cdn.jsdelivr.net/npm/slidemind/.claude-plugin/marketplace.json` is the equivalent fallback. The tarball's `bin/slidemind` + `bin/slidemind.cmd` shims land on PATH inside plugin sessions, so the plugin carries the CLI too. (`/plugin marketplace add STATWORX/intern-slidemind-cli` also works but needs read access to this private repo — prefer the URL.)
+- **Codex**: a Codex marketplace source must be a **local path or a git remote** — no URL, no npm — so the CDN trick does NOT transfer. Instead the tarball ships `.agents/plugins/marketplace.json`, which makes the INSTALLED package a valid local marketplace: `npm install -g slidemind` → `codex plugin marketplace add "$(npm root -g)/slidemind"` → `codex plugin add slidemind@slidemind`. No GitHub account needed. (`codex plugin marketplace add STATWORX/intern-slidemind-cli` works for anyone with repo access.) Codex plugins cannot put a binary on PATH, so the CLI always comes from npm; the skills' remediation covers that.
 
-`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.
+> 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 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`.
 
@@ -73,7 +125,7 @@ Teammates pick up the release with `npm install -g slidemind@latest` (or `slidem
 slidemind/
 ├── package.json                  npm package metadata, single bin: slidemind
 ├── README.md                     end-user quickstart
-├── CLAUDE.md                     this file
+├── AGENTS.md                     this file (CLAUDE.md is a symlink to it)
 ├── .claude-plugin/
 │   ├── plugin.json               Claude Code plugin manifest (version release-synced to package.json)
 │   └── marketplace.json          Claude Code marketplace — serves the plugin from public npm, unpinned
@@ -82,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/
@@ -96,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
@@ -128,22 +181,40 @@ 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.
 
+## External skill packs (this repo ships none)
+
+Some decks build from a **template pack** (`mode: "fill-template"` in the pack's `skill.json`) rather than from the design bundle. Those packs are distributed privately, on their own — as a harness plugin, an admin-pushed workspace skill, or a hand-installed directory. **This package must never carry, name, or hardcode anything from one.** No layout component names, no template file names, no master-fixed titles, no client names. `src/pptx/fill/` is generic machinery; every pack-specific fact is read from the pack:
+
+| Fact | Read from |
+|---|---|
+| semantic name → shape id | `fields.json` |
+| repeat groups | `repeats.json` |
+| immutable tables, hygiene deletions, freeform placeholders | `skill.json` `policy` |
+| layout component naming | `skill.json` `components` — `{ canonical, localized }`, regex sources; `canonical` group 1 is the slide number, `localized` group 1 the locale and group 2 the number |
+| template-fixed slide titles | `skill.json` `policy.fixedTitles` — `{ <locale>: [{ stem, title }] }`, `stem` a case-insensitive regex on the slide file stem |
+
+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.
+
+Pack-dependent integration tests belong in the pack's own repo, not here.
+
 ## Design system ground rules
 
 The corporate design is **served by the add-in, not shipped by the CLI.** `slidemind download-bundle` materializes it (keyed by the deck's `.bundle-ref.json`) into `${XDG_CACHE_HOME:-~/.cache}/slidemind/bundles/<presFP>/`:

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
+```
+
+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 all      # deploy the skill into Claude Code / Codex / opencode
+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,18 +161,24 @@ 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** from this repo's marketplace instead of the two-command npm flow. The repo is private, so the one-time `marketplace add` uses your existing GitHub credentials (`gh auth login`, a git credential helper, or SSH).
+Both harnesses can install slidemind as a **plugin** instead of the two-command npm flow.
 
-**Claude Code — fully self-contained (no `npm install -g` needed):**
+**Claude Code — fully self-contained (no `npm install -g`, no GitHub account):**
 
 ```
-/plugin marketplace add STATWORX/intern-slidemind-cli
+/plugin marketplace add https://unpkg.com/slidemind/.claude-plugin/marketplace.json
 /plugin install slidemind@slidemind
 ```
 
-The plugin ships both skills *and* the CLI: under the hood Claude Code installs the public npm package and puts `slidemind` on `PATH` inside its sessions (the headless-Chrome heads-up above applies to this install too). Outside Claude Code sessions the command is not on your `PATH` — add the global install if you also want to drive the CLI by hand. Updates ship with every release; apply them via `/plugin`. If background marketplace refreshes fail against the private repo, use SSH for the marketplace add or set `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1`.
+The marketplace is served straight out of the published npm package — the tarball ships `.claude-plugin/marketplace.json`, and an npm CDN serves it over plain HTTPS. Nothing here needs repo access, and it follows releases automatically (no version in the URL, no version pin in the plugin entry). `https://cdn.jsdelivr.net/npm/slidemind/.claude-plugin/marketplace.json` works the same way.
+
+The plugin ships both skills *and* the CLI: Claude Code installs the public npm package and puts `slidemind` on `PATH` inside its sessions (the headless-Chrome heads-up above applies to this install too). Outside Claude Code sessions the command is not on your `PATH` — add the global install if you also want to drive the CLI by hand. Apply updates via `/plugin`.
+
+> `/plugin marketplace add STATWORX/intern-slidemind-cli` also works if you have read access to the repo, but the URL above is preferred — it needs no credentials. If background refreshes ever fail against the private repo, use SSH or set `CLAUDE_CODE_PLUGIN_KEEP_MARKETPLACE_ON_FAILURE=1`.
 
 **Codex — skills via plugin, CLI via npm:**
 
@@ -153,7 +187,7 @@ codex plugin marketplace add STATWORX/intern-slidemind-cli
 codex plugin add slidemind@slidemind
 ```
 
-Codex plugins carry the skills only — the CLI still comes from `npm install -g slidemind` (the skills walk you through it if it's missing). `slidemind init --for codex` remains the most robust path; it additionally writes an `~/.codex/AGENTS.md` pointer.
+Codex plugins carry the skills only — the CLI still comes from `npm install -g slidemind` (the skills walk you through it if it's missing). Codex clones the repo for this, so it needs read access; without it, get the skills from your workspace's Codex admin skill upload and the CLI from npm. `slidemind init --for codex` remains the most robust path; it additionally writes an `~/.codex/AGENTS.md` pointer.
 
 > Already ran `slidemind init` and switching to a plugin? Drop the copied skills once with `slidemind uninstall --for claude` (or `--for codex`) so they don't duplicate the plugin's.
 
@@ -161,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
@@ -255,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
@@ -305,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.
 
 ---
 
@@ -330,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`.
 
 ---
 
@@ -340,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. |