fix(sdk-install): identity-verification truths from a live install run (0.3.1)

A real from-zero install against an enforcing environment corrected
three claims and added the trap that actually bit:

- "silently rejected" was imprecise: the identify() promise REJECTS with
  a misleading generic "check your network connection" message —
  identical for missing token / bad signature / no active secret — and a
  fire-and-forget call surfaces only as an empty-reason Uncaught
  (in promise). SKILL.md, identity-verification.md and troubleshooting.md
  now describe that real signal (and advise awaiting identify during
  rollout).
- New headline trap: even CORRECTLY signed tokens fail when the target
  environment has no ACTIVE secret — classically a secret copied from
  another environment's settings page. Secrets are per-environment.
- Secret lifecycle is console-only (the API/MCP deliberately has no
  signing-secret surface) — confirm registration with the admin before
  testing enforcement.
- verify.md: driving the widget programmatically — a11y snapshots show
  the iframe as an opaque frame (dispatch via contentDocument), and some
  controls need the full pointer event sequence, not a bare .click().

Version 0.3.0 → 0.3.1 across the six manifests (validate.js green).

Author: winter100004

.agents/plugins/marketplace.json

@@ -2,7 +2,7 @@
   "plugins": [
     {
       "name": "usertour",
-      "version": "0.3.0",
+      "version": "0.3.1",
       "category": "Coding",
       "source": {
         "type": "local",

.claude-plugin/marketplace.json

@@ -10,7 +10,7 @@
       "name": "usertour",
       "source": "./",
       "description": "Skills for authoring Usertour in-app onboarding content",
-      "version": "0.3.0"
+      "version": "0.3.1"
     }
   ]
 }

.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "usertour",
   "description": "Skills for Usertour in-app onboarding — authoring content (flows, checklists, launchers, banners, surveys) and installing the Web SDK — via the Usertour API/MCP",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "author": {
     "name": "Usertour",
     "url": "https://www.usertour.io"

.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "usertour",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Skills for Usertour in-app onboarding — authoring content (flows, checklists, launchers, banners, surveys) and installing the Web SDK — via the Usertour API/MCP",
   "author": {
     "name": "Usertour",

.cursor-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "usertour",
       "source": "./",
       "description": "Skills for authoring Usertour in-app onboarding content",
-      "version": "0.3.0"
+      "version": "0.3.1"
     }
   ]
 }

.cursor-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "usertour",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Skills for Usertour in-app onboarding — authoring content (flows, checklists, launchers, banners, surveys) and installing the Web SDK — via the Usertour API/MCP",
   "author": {
     "name": "Usertour",

skills/usertour-sdk-install/SKILL.md

@@ -56,7 +56,8 @@ ask the user for the environment token (Settings → Environments) — it is the
    target, or published content silently never shows. Call `usertour.reset()` on
    logout. If the environment **requires identity verification**, `identify()` /
    `group()` must also carry a backend-signed JWT (the `{ token }` option) or the
-   identity is **silently rejected** at connect — see
+   identity is rejected at connect — near-silently: the only signal is the
+   `identify()` promise rejecting with a misleading network-ish message — see
    [references/identity-verification.md](references/identity-verification.md).
 6. **SPA routing** — for single-page apps, confirm content re-evaluates on route
    change (see the framework reference).
@@ -74,8 +75,9 @@ ask the user for the environment token (Settings → Environments) — it is the
   segments / start-rules, or nothing renders (the #1 "it's not showing" cause).
 - **Enforced identity verification:** when the target environment requires it,
   the install is not done until `identify()`/`group()` carry a valid signed
-  token — unsigned calls are rejected **silently** (looks exactly like
-  "identify ignored"). See
+  token — unsigned calls are rejected near-silently (the promise rejects with a
+  misleading "check your network" message; looks exactly like "identify
+  ignored"). See
   [references/identity-verification.md](references/identity-verification.md).
 - **Defer the API to the docs:** this skill is the wiring + gotchas, not a copy of
   the snippet. Read the reference; it's the source of truth.

skills/usertour-sdk-install/references/identity-verification.md

@@ -2,10 +2,15 @@
 
 An environment can **require identity verification**: every `identify()` /
 `group()` call must carry a JWT minted by the app's backend, or the server
-rejects the claimed identity **at connect time — silently**. No SDK error, no
-console noise; the app looks installed but the user never appears in Usertour
-and nothing renders. If the target environment has enforcement ON, the install
-is NOT done until this is wired.
+rejects the claimed identity at connect time. The rejection is NEARLY silent —
+the user never appears in Usertour and nothing renders — and the one signal it
+does emit is **misleading**: the `identify()` promise REJECTS with a generic
+"request unsuccessful … check your network connection" message (never mentioning
+identity verification), and a fire-and-forget `identify()` surfaces only as an
+`Uncaught (in promise)` with an empty reason. The message is IDENTICAL for a
+missing token, a bad signature, and a no-active-secret environment — you cannot
+tell them apart client-side. If the target environment has enforcement ON, the
+install is NOT done until this is wired.
 
 Live guide (prefer it over this summary):
 https://docs.usertour.io/developers/identity-verification
@@ -17,6 +22,11 @@ https://docs.usertour.io/developers/identity-verification
   a "signed traffic" coverage stat.
 - Rule of thumb: wire it BEFORE enforcement is enabled — the intended rollout is
   "sign all traffic first, watch coverage hit 100%, then enforce".
+- **The secret lifecycle is console-only**: the API/MCP has no signing-secret
+  surface (deliberate — a secret grants identity forgery), so you cannot create,
+  list, or check secrets from here. Before testing against enforcement, have the
+  admin confirm a secret is registered **in the environment you're targeting**
+  and hand it to your backend config.
 
 ## Backend: mint the token
 
@@ -70,7 +80,16 @@ usertour.group(company.id, companyAttributes, { token: usertourToken });
   wrong algorithm (must be HS256) / malformed / missing `sub` / no active secret.
 - The **coverage stat** (last 7 days: valid / invalid / unsigned) tells you
   whether real traffic is signed before you flip enforcement.
+- **Even CORRECTLY signed tokens fail?** First check the environment has an
+  ACTIVE secret at all: with none registered, the server rejects every
+  non-anonymous identity (`no_active_secret`) and it looks exactly like a bad
+  signature. The classic cause is a secret copied from ANOTHER environment's
+  settings page — secrets are per-environment; a Production secret proves
+  nothing in Development. (Verified the hard way in a real install run.)
 - Symptom map: user identifies fine in an environment WITHOUT enforcement but
-  vanishes in the enforced one → the token is missing/invalid there (different
-  environment = different signing secret; check which secret the backend uses
-  per environment).
+  vanishes in the enforced one → the token is missing/invalid there, or that
+  environment has no active secret (different environment = different signing
+  secret; check which secret the backend uses per environment).
+- Client-side, the only tell of ANY rejection is the `identify()` promise
+  rejecting with the generic network-ish message above — `await`/`.catch()` it
+  during rollout so rejections are at least visible.

skills/usertour-sdk-install/references/troubleshooting.md

@@ -16,15 +16,23 @@ Non-negotiables. Check the linkage before anything else.
 ## `identify()` looks ignored — the user never appears in Usertour at all
 
 **Cause:** The environment **enforces identity verification** and the
-`identify()` / `group()` call carried no (or an invalid) backend-signed JWT. The
-server rejects the identity **at connect time, silently** — no SDK error, the
-user is never created, nothing renders. A tell: the same code works in an
-environment without enforcement but "does nothing" in the enforced one.
+`identify()` / `group()` call carried no (or an invalid) backend-signed JWT — or
+the environment has NO active signing secret at all, which rejects even
+correctly-signed tokens. The server rejects the identity at connect time; the
+user is never created, nothing renders. The only client-side signal is the
+`identify()` promise rejecting with a MISLEADING generic message ("…check your
+network connection…" — identical for missing token / bad signature / no active
+secret); fire-and-forget calls show it only as an `Uncaught (in promise)` with
+an empty reason. A tell: the same code works in an environment without
+enforcement but "does nothing" in the enforced one.
 **Solution:** Wire the signed token
 ([identity-verification.md](identity-verification.md)); validate a
 backend-minted JWT in Settings → Identity Verification (it names the exact
 problem: expired / wrong algorithm — HS256 only / missing `sub` / signed with a
-revoked secret / …). Remember each environment has its OWN signing secret.
+revoked secret / no active secret / …). Remember each environment has its OWN
+signing secret — a secret copied from another environment fails exactly like a
+wrong one, and the secret lifecycle is console-only (the API/MCP can't create
+or list secrets).
 
 ## A flow does a full page reload mid-tour (SPA)
 

skills/usertour-sdk-install/references/verify.md

@@ -35,6 +35,13 @@ one wired):
   The SDK swaps the iframe surface per step, so re-query it each step — a
   `contentDocument` reference held from a previous step goes stale (reads null),
   and a stale null can look like a trigger that didn't fire.
+- **Driving (not just reading) the widget programmatically** has two extra
+  gotchas: accessibility snapshots show the iframe as an opaque "Content Frame"
+  (no clickable uids inside — dispatch events via `contentDocument` instead),
+  and some controls (e.g. the resource-center launcher) ignore a bare
+  `.click()` — dispatch the full pointer sequence
+  (`pointerdown → mousedown → pointerup → mouseup → click`) when a programmatic
+  click seems to do nothing.
 
 ## 4. Security check