refactor(skills): rename setup-plugin to verify-setup, drop install branch

.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
     {
       "name": "subtext",
       "source": "./",
-      "version": "0.2.1",
+      "version": "0.2.2",
       "description": "Tools that let coding agents verify and show their work against your running application",
       "category": "development",
       "keywords": ["subtext", "automation", "verification", "testing", "session-replay", "debugging", "fullstory"],

.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "subtext",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Tools for agents to build with Subtext",
   "license": "MIT",
   "author": {

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "subtext",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Tools that let coding agents verify and show their work against your running application",
   "author": {
     "name": "Subtext",

.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "subtext",
   "description": "Tools that let coding agents verify and show their work against your running application",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "license": "MIT",
   "author": {
     "name": "Subtext",

skills/README.md

@@ -27,14 +27,14 @@ Before creating or modifying any skill, read [`authoring.md`](authoring.md).
 ## Onboarding — "getting started"
 
 - **subtext:onboard** — Three-step first-run flow: connect to the user's local dev server, prove a small change with before/after evidence, bootstrap a starter `.sightmap/` from what was learned.
-- **subtext:setup-plugin** — Install the Subtext plugin and configure MCP servers (invoked implicitly by `onboard` if MCP isn't reachable).
+- **subtext:verify-setup** — Verify the plugin is connected and diagnose MCP / auth failures (invoked implicitly by `onboard` if MCP isn't reachable). Does not install — see https://subtext.fullstory.com/install/.
 - **subtext:first-session** — Agent-driven exploration of the user's site via the hosted browser.
 
 ## How they compose
 
 ```
 onboard
-  ├─ setup-plugin   (implicit health check; only runs on failure)
+  ├─ verify-setup   (implicit health check; only runs on failure)
   ├─ tunnel + live  (connect to user's local dev server)
   ├─ proof          (small change → before/after evidence)
   └─ sightmap       (write .sightmap/components.yaml from what was learned)

skills/authoring.md

@@ -66,7 +66,7 @@ A workflow earns its length through decision points. If every section is "call t
 
 ### Onboarding-shaped workflows
 
-Skills like `onboard`, `setup-plugin`, and `first-session` are workflow-shaped but user-facing — guided setup rather than agent-internal orchestration. They follow the same bare-name rule. Treat them as adjacent to the three buckets, not a fourth tier.
+Skills like `onboard`, `verify-setup`, and `first-session` are workflow-shaped but user-facing — guided setup rather than agent-internal orchestration. They follow the same bare-name rule. Treat them as adjacent to the three buckets, not a fourth tier.
 
 ## Conventions
 

skills/onboard/SKILL.md

@@ -17,7 +17,7 @@ The goal: walk a new user through one real, useful Subtext run end-to-end. They
 
 ## Implicit health check
 
-Do **not** announce a "plugin setup" step. Trust that the plugin is installed — the user just ran a slash command from it. If the first MCP call below fails (server unreachable, auth missing), invoke `subtext:setup-plugin`, then retry the call. Otherwise stay silent about plumbing.
+Do **not** announce a "plugin setup" step. Trust that the plugin is installed — the user just ran a slash command from it. If the first MCP call below fails (server unreachable, auth missing), invoke `subtext:verify-setup`, then retry the call. Otherwise stay silent about plumbing.
 
 ## Greeting
 
@@ -57,7 +57,7 @@ Once you have a `http://localhost:…` (or `http://127.0.0.1:…`) URL, follow t
 2. `tunnel-connect({ relayUrl, target: <base of the localhost URL> })` → confirm `state: "ready"`
 3. `live-view-new({ connection_id, url: <full localhost URL> })` → returns `trace_url` (and the initial snapshot)
 
-If any of these calls fails because the MCP server is unreachable, invoke `subtext:setup-plugin`, then retry.
+If any of these calls fails because the MCP server is unreachable, invoke `subtext:verify-setup`, then retry.
 
 **Print the `trace_url` immediately, on its own line, before saying anything else:**
 

skills/using-subtext/SKILL.md

@@ -64,7 +64,7 @@ These thoughts mean STOP — you're rationalizing:
 - **Atomics** (`shared`, `session`, `live`, `sightmap`, `tunnel`, `comments`) — tool catalogs.
 - **Workflows** (`proof`, `review`) — orchestration. `proof` is the inner loop, `review` is the outer loop.
 - **Recipes** (`recipe-sightmap-setup`) — short step lists.
-- **Onboarding** (`onboard`, `setup-plugin`, `first-session`) — first-time user setup.
+- **Onboarding** (`onboard`, `verify-setup`, `first-session`) — first-time user setup.
 
 ```
 proof ──▶ session recorded ──▶ review (optional handoff)

skills/verify-setup/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: verify-setup
+description: Verify the Subtext plugin/extension is connected and diagnose MCP connectivity or auth failures. Does not install — see https://subtext.fullstory.com/install/ for first-time setup.
+metadata:
+  requires:
+    skills: ["subtext:shared"]
+---
+
+# Verify Setup
+
+Confirm Subtext is wired up correctly and diagnose failures. This skill assumes the plugin/extension is already installed — you wouldn't be reading it otherwise. For first-time install, point users at https://subtext.fullstory.com/install/.
+
+## When to use
+
+- User asks *"is Subtext working?"* or *"is it set up?"*
+- A Subtext MCP tool just failed and you need to diagnose why
+- Invoked implicitly by `subtext:onboard` when an early MCP call errors out
+
+## Step 1: Test MCP connectivity
+
+Try a lightweight MCP call to confirm the server is reachable. Listing tools on the `subtext` server is a good probe — it doesn't require any session or scope beyond auth.
+
+Servers to consider:
+- `subtext` (US) or `subtext-eu1` (EU) — required for review, live, comments. Whichever the user's account region uses.
+- `subtext-tunnel` — optional, only needed for hosted-browser flows against a localhost dev server.
+
+If the call succeeds, the plugin is connected. Report which servers are reachable and move to Step 2.
+
+If the call fails, classify the failure:
+
+- **Tool / server not registered** (the MCP server name isn't even available) → the plugin or extension isn't activated in this agent. Tell the user to enable it via their platform's extension/plugin UI. Don't prescribe specific UI flows — different platforms differ; ask the user to check whichever they're on.
+- **401 / 403 / "auth required"** → MCP server is reachable but unauthenticated. Tell the user to complete the OAuth flow (typically opens a browser on first tool use), or to configure an API key per their platform's MCP server settings. Detailed install/auth steps live at https://subtext.fullstory.com/install/.
+- **Network error / 5xx / timeout** → MCP server is unreachable. Suggest checking network and retrying. If persistent, escalate to subtext@fullstory.com.
+
+## Step 2: Verify local dependencies
+
+The sightmap upload script (`skills/shared/collect_and_upload_sightmap.py`) needs Python 3 + PyYAML. Run as a single command:
+
+```bash
+python3 --version 2>&1 && python3 -c "import yaml; print('PyYAML OK')" 2>&1
+```
+
+- No Python 3 → suggest the user's OS-appropriate install (e.g. `brew install python@3.12` on macOS).
+- No PyYAML → suggest `python3 -m pip install pyyaml`.
+
+These aren't fatal — Subtext's MCP tools work without sightmap upload — but agents that try to upload sightmap on session start will fail silently if these are missing.
+
+## Step 3: Report
+
+If everything passes:
+
+> "Subtext is connected. MCP servers reachable, deps OK."
+
+If something failed, report the specific failure and the next step you suggested. Stay terse — the user wants to get unstuck, not read a plumbing essay.