slidemind 0.1.0 → 0.1.2

package/CLAUDE.md

@@ -64,7 +64,7 @@ slidemind/
 ├── .claude-plugin/
 │   └── plugin.json               Claude Code plugin manifest
 ├── bin/
-│   └── slidemind.mjs             CLI dispatcher (presentations, download-bundle, init, build, build-pptx, push, search, install)
+│   └── slidemind.mjs             CLI dispatcher (presentations, download-bundle, init, build, build-pptx, push, search, install, pair/whoami/use/logout)
 ├── skills/                       canonical, installable skill payload — thin CLI workflow glue only
 │   └── create-slides/
 │       └── SKILL.md              the whole skill: host gate + intake/plan + create flow + CLI⇄in-app command map.
@@ -95,12 +95,18 @@ slidemind build <deck>             # build self-contained HTML preview
 slidemind build-pptx <deck>        # render native .pptx via the add-in (HOST REQUIRED)
 slidemind push <deck>              # render + push slides into a running PowerPoint (HOST REQUIRED)
 slidemind search "<query>"         # search the brand engine for imagery (HOST REQUIRED)
+slidemind pair <code>              # pair with an add-in environment (copy from its "Connect CLI")
+slidemind whoami                   # list every paired 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
 slidemind uninstall --for <target>
 ```
 
 `<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*.
+
 **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, and brand imagery comes from the add-in's engine. So `create`/`build-pptx`/`push`/`search` all hard-require an **open PowerPoint host with the slidemind add-in and an active corporate design**. See `docs/slidemind-cli-connect/`.
 
 ## Design system ground rules
@@ -134,4 +140,4 @@ slidemind search "<query>"        # search the brand engine for imagery (host re
 npm run lint:parity               # assert the skill carries no brand rules (CI guard)
 ```
 
-No linter beyond the parity guard, `node --test` for the suite, no package manager beyond npm itself. The HTML preview is self-contained except for React + Babel-standalone pulled from a CDN on first load.
+No linter beyond the parity guard, `node --test` for the suite, no package manager beyond npm itself. CI (`.github/workflows/test.yml`) runs the suite + parity guard on Linux, **Windows**, and macOS (Node 18 + 22) — the CLI promises native-Windows support, so keep it green there. The HTML preview is self-contained except for React + Babel-standalone pulled from a CDN on first load.

package/README.md

@@ -1,100 +1,292 @@
 # slidemind
 
-Connect Claude Code, Codex, and opencode to the **slidemind PowerPoint add-in** — so your coding agent can build and edit native, on-brand PowerPoint decks against your active corporate design, without leaving the terminal.
+[![npm version](https://img.shields.io/npm/v/slidemind.svg)](https://www.npmjs.com/package/slidemind)
+[![node](https://img.shields.io/node/v/slidemind.svg)](https://nodejs.org)
+[![platforms](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-blue.svg)](#install)
 
-This is the companion CLI for the slidemind PowerPoint add-in (coming to the Microsoft Office Store). The add-in owns the corporate design and the native `.pptx` render; slidemind is the bridge that lets a coding agent drive it. It ships two things:
+Connect **Claude Code, Codex, and opencode** to the **slidemind PowerPoint add-in** — so your coding agent (or you, from the terminal) can build and edit **native, on-brand PowerPoint decks** against your active corporate design, without leaving the editor.
 
-1. **A CLI + MCP server** that talks to a running PowerPoint over the add-in's local bridge — render native `.pptx`, push slides straight into an open window, and search the active design's brand engine for imagery.
-2. **An installable skill** for Claude Code, Codex, and opencode — so the agent in your editor knows how to drive that bridge and compose slides on-brand from the design bundle the add-in serves.
+> **Preview.** slidemind is in early access while the PowerPoint add-in makes its way to the Microsoft Office Store. The CLI is functional and published, but expect rough edges and breaking changes between releases. You need access to the slidemind add-in to use it.
+
+slidemind is a **thin client**. The corporate design, the layout palette, and the native `.pptx` render all live in the **slidemind PowerPoint add-in** — this package is the bridge that lets a coding agent drive it. It ships two things:
+
+1. **A CLI + MCP server** that talks to a running PowerPoint over the add-in's cloud bridge — render native `.pptx`, push slides straight into an open window, and search the active design's brand engine for imagery.
+2. **An installable skill** for Claude Code, Codex, and opencode — so the agent in your editor knows how to plan, compose, and review slides on-brand from the design bundle the add-in serves.
+
+Both drive the same add-in bridge, so an agent and a human end up producing the same artefact: native PowerPoint slides on the active corporate design.
+
+---
+
+## Contents
+
+- [Requirements](#requirements)
+- [Install](#install)
+  - [Windows](#windows)
+  - [macOS](#macos)
+  - [Linux](#linux)
+  - [Without a global install (npx)](#without-a-global-install-npx)
+- [Connect to PowerPoint](#connect-to-powerpoint)
+- [Quick start](#quick-start)
+- [Using it with a coding agent](#using-it-with-a-coding-agent)
+- [Command reference](#command-reference)
+- [Pushing slides into an open PowerPoint](#pushing-slides-into-an-open-powerpoint)
+- [Multiple environments (for slidemind developers)](#multiple-environments-for-slidemind-developers)
+- [Updating](#updating)
+- [Troubleshooting](#troubleshooting)
+- [Uninstall](#uninstall)
+- [How it works](#how-it-works)
+
+---
+
+## Requirements
+
+| | |
+|---|---|
+| **Node.js** | **18 or newer** (`node --version`). Ships with npm. |
+| **slidemind PowerPoint add-in** | Installed in PowerPoint, with a presentation open and a **corporate design active**. The design and the `.pptx` render live here — the CLI cannot work without it. |
+| **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.
+
+Commands that read the design, render, or push (`download-bundle`, `build-pptx`, `push`, `search`) **require an open PowerPoint host with the add-in and an active corporate design.** Only `new` and `build` (HTML preview) work fully offline.
+
+---
 
 ## Install
 
-From public npm. macOS / Linux / Windows; requires **Node 18+**.
+The package is published to **public npm** as [`slidemind`](https://www.npmjs.com/package/slidemind). The same two commands work on every platform:
 
 ```bash
 npm install -g slidemind
 slidemind init --for all      # register the MCP server + skill into Claude Code / Codex / opencode
 ```
 
-`slidemind init --for <claude|codex|opencode|all|none>` scopes the harness deployment (`none` installs the CLI only). `slidemind --version` confirms it's on your `PATH`.
+Then confirm it's on your `PATH`:
+
+```bash
+slidemind --version
+```
+
+`slidemind init --for <claude|codex|opencode|all|none>` scopes the harness deployment. Use `none` to install the CLI only.
+
+### Windows
+
+slidemind runs on native Windows (PowerShell, Windows Terminal, or cmd) — no WSL or Git Bash required.
+
+1. Install **Node 18+** from [nodejs.org](https://nodejs.org) (the LTS installer adds Node + npm to your `PATH` and ticks the right boxes by default).
+2. Open **Windows Terminal** or **PowerShell** and run:
+
+   ```powershell
+   npm install -g slidemind
+   slidemind init --for all
+   slidemind --version
+   ```
 
-One-off, without a global install:
+The global install lands in `%APPDATA%\npm`, which the Node installer puts on your `PATH`. Your pairing credentials are stored under `%APPDATA%\slidemind\`.
+
+> **If PowerShell blocks the command** with an execution-policy error, that's the `.ps1` shim npm generates — run `slidemind.cmd <command>` instead, or use a cmd.exe tab in Windows Terminal. (To permanently allow local scripts — downloaded ones still need a signature: `Set-ExecutionPolicy -Scope CurrentUser RemoteSigned`.)
+
+### macOS
+
+1. Install **Node 18+** — the [nodejs.org](https://nodejs.org) installer, or `brew install node`.
+2. In Terminal (or iTerm):
+
+   ```bash
+   npm install -g slidemind
+   slidemind init --for all
+   slidemind --version
+   ```
+
+If `npm install -g` fails with `EACCES`, you've hit a permissions issue with a system-owned npm prefix — the cleanest fix is a user-owned Node from [Homebrew](https://brew.sh) or [nvm](https://github.com/nvm-sh/nvm) (avoid `sudo npm`). Credentials are stored under `~/.config/slidemind/`.
+
+### Linux
+
+The CLI runs fine on Linux. There's no PowerPoint desktop on Linux, so you'll connect to a PowerPoint host elsewhere — a Windows/Mac desktop, or PowerPoint on the web — over the cloud relay.
 
 ```bash
-npx slidemind <command>
+npm install -g slidemind
+slidemind init --for all
+slidemind --version
 ```
 
-### Updating
+If a system Node gives you `EACCES` on global installs, use [nvm](https://github.com/nvm-sh/nvm) or set a user-writable npm prefix rather than `sudo`. Credentials honor `XDG_CONFIG_HOME` (default `~/.config/slidemind/`).
+
+### Without a global install (npx)
+
+Run any command without installing globally:
 
 ```bash
-slidemind update                 # = npm install -g slidemind@latest, then redeploy the skill
-slidemind update --ref 0.1.0     # pin a specific version
-slidemind update --for codex     # redeploy into one harness (or --for none to skip)
+npx slidemind <command>
 ```
 
-Equivalently: `npm install -g slidemind@latest && slidemind init --for all`.
+---
+
+## Connect to PowerPoint
+
+The CLI talks to PowerPoint through the add-in's cloud relay, so you pair once per machine.
+
+1. In PowerPoint, open the **slidemind add-in** task pane and click **"Connect CLI"**.
+2. It shows a one-time command. Copy and run it:
+
+   ```bash
+   slidemind pair <code>
+   ```
 
-> **Heads up:** the design system and the `.pptx` render now live in the **slidemind PowerPoint add-in** — the CLI is a thin client. `build-pptx`, `push`, `download-bundle`, and `search` require an open PowerPoint window with the add-in loaded and an active corporate design. See [`docs/slidemind-cli-connect/`](./docs/slidemind-cli-connect/).
+3. Verify the link:
+
+   ```bash
+   slidemind whoami          # lists the paired environment(s)
+   slidemind presentations   # lists open PowerPoint windows the add-in sees
+   ```
+
+If `slidemind presentations` is empty, the add-in isn't reachable — open PowerPoint with the slidemind add-in and an active corporate design, then retry.
+
+```bash
+slidemind logout            # unpair this machine
+```
+
+---
 
 ## Quick start
 
 ```bash
 slidemind new my-deck             # scaffold ./decks/my-deck/
-slidemind build my-deck           # build self-contained HTML
-slidemind build-pptx my-deck      # render native .pptx via the add-in (host required)
-slidemind search "shield"         # search the brand engine for imagery (host required)
+slidemind build my-deck           # build a self-contained HTML preview (offline)
+slidemind build-pptx my-deck      # render a native .pptx via the add-in (host required)
+slidemind push my-deck            # stream slides straight into an open PowerPoint (host required)
+slidemind search "shield"         # search the active design's brand engine (host required)
 ```
 
-Decks live under `./decks/` in your current working directory. Each deck is one folder: `decks/<name>/slides/*.jsx`.
+Decks live under `./decks/` in your current working directory — one folder per deck: `decks/<name>/slides/*.jsx`. Override the location with `SLIDEMIND_DECKS=/abs/path`.
 
-## Pushing slides into an open PowerPoint
+You don't hand-write OOXML or hardcode brand colors — slides are small `.jsx` files that compose the layouts and tokens the add-in serves. The render happens server-side in PowerPoint; `slidemind build` gives you a quick HTML preview while you iterate.
 
-If you have PowerPoint open with the **slidemind add-in** loaded, you can build a deck and stream its slides straight into the running window — no `.pptx` file written to disk:
+---
 
-```bash
-slidemind presentations                   # list registered PowerPoint windows (presId, title, fileName)
-slidemind push my-deck                    # append my-deck after the current slides
-slidemind push my-deck --to <presId>      # required if more than one PowerPoint window is open
-slidemind push my-deck --at 0             # insert after slide 1 (0-based index)
-slidemind push my-deck --replace          # delete every existing slide first (destructive — confirm!)
-slidemind push my-deck --slides 02,05,07  # push only a subset of source slides
+## Using it with a coding agent
+
+`slidemind init` installs a **skill** into your coding agent. After that, just ask:
+
+> "Make me a 5-slide deck introducing our Q3 roadmap."
+
+Your agent (Claude Code, Codex, or opencode) auto-discovers the `slidemind-create-slides` skill, reads the active corporate design's rules from the add-in, writes the slide files, and renders + pushes them into PowerPoint for you. The skill owns the whole **plan → create → edit → render** workflow — there are no slash commands to memorize.
+
+The MCP server registered by `slidemind init` gives the agent direct tools to list open presentations, push decks, and search brand imagery.
+
+---
+
+## Command reference
+
+```text
+slidemind new <name>             Scaffold ./decks/<name>/
+slidemind build <deck>           Build a self-contained HTML preview (offline)
+slidemind build-pptx <deck>      Render a native .pptx via the add-in        (host required)
+slidemind push <deck>            Build + push slides into an open PowerPoint  (host required)
+slidemind search "<query>"       Search the active design's brand engine      (host required)
+slidemind download-bundle [deck] Materialize the active corporate design locally (host required)
+slidemind presentations          List PowerPoint windows registered with the add-in
+slidemind pair <code>            Pair with an add-in (copy the code from "Connect CLI")
+slidemind whoami                 Show paired 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 + MCP server into a harness
+slidemind uninstall --for <t>    Remove a previously-installed skill
+slidemind update [--for <t>]     Fetch the latest release and redeploy
+slidemind --help                 Full usage
+slidemind --version              Print version
 ```
 
-If `slidemind presentations` returns nothing, the add-in isn't running — open PowerPoint with the slidemind add-in and an active corporate design, then retry. (Rendering is server-side now, so `build-pptx` needs a host too.)
+`<target>` is `claude | codex | opencode | all | none`. `<deck>` resolves as: absolute path → `./<arg>` if it exists → `./decks/<arg>`.
 
-## Export formats at a glance
+### Export formats at a glance
 
 | Command | Output | When to use |
 |---|---|---|
-| `slidemind build <deck>` | `decks/<deck>/presentation.html` | Self-contained HTML (browser) |
-| `slidemind build-pptx <deck>` | `decks/<deck>/<deck>.pptx` | Editable PowerPoint file |
-| `slidemind push <deck>` | (streamed via add-in) | Live insertion into an open PowerPoint window |
+| `slidemind build <deck>` | `decks/<deck>/presentation.html` | Self-contained HTML preview in a browser (offline) |
+| `slidemind build-pptx <deck>` | `decks/<deck>/<deck>.pptx` | An editable native PowerPoint file |
+| `slidemind push <deck>` | (streamed via the add-in) | Live insertion into an open PowerPoint window |
 
-## Icon / image search
+---
 
-`slidemind search "<query>"` searches the active corporate design's **brand engine** (icons/images) over the local bridge, using the add-in's server-side bridge when available so it returns the same results the in-app design agent sees (an open host is required). It prints a `searchId` plus numbered results; the agent then fetches a chosen result into the deck's `assets/` via the MCP tool `slidemind_download_result`. The agent-facing flow (`slidemind_search_engine` → `slidemind_download_result`) is owned by the add-in's design bundle and read by the skill. There is no local icon library anymore.
+## Pushing slides into an open PowerPoint
+
+With PowerPoint open and the slidemind add-in loaded, stream a deck's slides straight into the running window — no `.pptx` written to disk:
+
+```bash
+slidemind presentations                   # list windows (presId, env, title)
+slidemind push my-deck                     # append after the current slides
+slidemind push my-deck --to <presId>       # required if more than one window is open
+slidemind push my-deck --at 0              # insert after slide 1 (0-based index)
+slidemind push my-deck --replace           # delete every existing slide first (destructive — confirm!)
+slidemind push my-deck --slides 02,05,07   # push only a subset of source slides
+```
 
-## Install into a coding-agent harness
+---
 
-Pick a target and run:
+## 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.
 
 ```bash
-slidemind init --for claude        # ~/.claude/skills/slidemind-create-slides/
-slidemind init --for codex         # ~/.codex/skills/slidemind-create-slides/
-slidemind init --for opencode      # ~/.config/opencode/{agent,slidemind}/
-slidemind init --for all
+slidemind pair <local-code> --label local
+slidemind pair <dev-code>   --label dev
+slidemind whoami                           # lists every paired 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 --backend local presentations    # scope a single command to one environment
 ```
 
-Each installer drops the slidemind skill files into the harness-specific location. After install, your agent auto-discovers the `slidemind-create-slides` skill and loads it on demand whenever you ask for a slide, deck, or presentation. The skill owns the entire plan → create → edit workflow — there are no separate slash commands to remember.
+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.
 
-Add `--link` to symlink instead of copy (useful while hacking on slidemind itself).
+---
 
-To remove:
+## Updating
 
 ```bash
-slidemind uninstall --for <target>
+slidemind update                 # = npm install -g slidemind@latest, then redeploy the skill
+slidemind update --ref 0.1.0     # pin a specific version
+slidemind update --for codex     # redeploy into one harness (--for none to skip)
 ```
 
-## Project layout
+Equivalently: `npm install -g slidemind@latest && slidemind init --for all`.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `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`. |
+| `slidemind presentations` is empty | The add-in isn't reachable. Open PowerPoint with the slidemind add-in and an active corporate design; click the task pane once to re-register, then retry. |
+| `Not paired` | Run `slidemind pair <code>` using the code from the add-in's **"Connect CLI"**. Codes are one-time and expire — generate a fresh one if it's stale. |
+| `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 set a user-writable npm prefix. |
+
+---
+
+## Uninstall
+
+```bash
+slidemind uninstall --for all    # remove the skill + MCP registration from each harness
+npm uninstall -g slidemind       # remove the CLI
+```
+
+---
+
+## How it works
+
+The design truth lives in the **add-in**, not the CLI:
+
+- The `.pptx` is **rendered server-side** over the bridge — there's no local exporter.
+- The corporate design is fetched as a **bundle** (`slidemind download-bundle`) — tokens, layout palette, brand rules, assets — keyed to the active presentation.
+- Brand imagery comes from the add-in's **engine** (`slidemind search` → the agent downloads a result into the deck's `assets/`).
+
+So an open PowerPoint host with the slidemind add-in and an active corporate design is required for everything except the offline HTML preview. The CLI ships no brand and no exporter of its own — it's deliberately brand-agnostic, working against whatever corporate design the add-in has loaded.
+
+---
 
-See [CLAUDE.md](./CLAUDE.md) for the full repo tour and the design-system ground rules.
+slidemind is published by **statworx**. Source lives in a private repository; the npm tarball is the install artifact. License: `UNLICENSED` (publicly installable, proprietary).