state-scenarios-cli 0.2.0 → 0.4.0

package/dist/record.d.ts

@@ -0,0 +1,41 @@
+export type VideoFormat = 'mp4' | 'gif' | 'webm';
+export interface Crop {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/**
+ * The part of an element's box the video shows. Video holds only the viewport, so a crop must
+ * stay inside it; `clipped` says the element was larger than the visible area.
+ */
+export declare function visibleCrop(box: Crop, viewport: {
+    width: number;
+    height: number;
+}): {
+    crop: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    clipped: boolean;
+} | undefined;
+/**
+ * ffmpeg arguments that trim the page load off the start, crop to an element, and encode.
+ * MP4 is H.264 in yuv420p so it plays everywhere, including Safari and phones; GIF uses a
+ * generated palette, which keeps it sharp at a fraction of the naive size.
+ */
+export declare function ffmpegArgs({ input, output, format, start, crop }: {
+    input: string;
+    output: string;
+    format: VideoFormat;
+    /** Seconds to skip, e.g. the page loading before the steps begin. */
+    start: number;
+    crop?: Crop;
+}): string[];
+/**
+ * Convert Playwright's WebM into the requested format. Uncropped WebM is copied as recorded
+ * (page load included), so it works without ffmpeg.
+ */
+export declare function encodeVideo(options: Parameters<typeof ffmpegArgs>[0]): void;

package/dist/skills-NQRJHKHG.js

@@ -0,0 +1,80 @@
+import {
+  CliError
+} from "./chunk-GCYOLAFU.js";
+
+// src/skills.ts
+import {
+  cpSync,
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync
+} from "fs";
+import { dirname, join, relative } from "path";
+import { fileURLToPath } from "url";
+import { z } from "zod";
+var SKILLS = fileURLToPath(new URL("../skills/", import.meta.url));
+var SKILL_NAMES = ["state-scenarios", "create-scenario-map"];
+var topics = () => readdirSync(join(SKILLS, "state-scenarios/references")).map((f) => f.replace(/\.md$/, "")).toSorted();
+function guide(topic) {
+  if (!topic) return readFileSync(join(SKILLS, "state-scenarios/SKILL.md"), "utf8");
+  if (!topics().includes(topic)) {
+    throw new CliError("INVALID_ARGUMENT", `Unknown topic "${topic}". Topics: ${topics().join(", ")}`);
+  }
+  return readFileSync(join(SKILLS, `state-scenarios/references/${topic}.md`), "utf8");
+}
+function installSkills(cwd) {
+  return SKILL_NAMES.map((name) => {
+    const target = join(cwd, ".agents/skills", name);
+    rmSync(target, { recursive: true, force: true });
+    mkdirSync(dirname(target), { recursive: true });
+    cpSync(join(SKILLS, name), target, { recursive: true });
+    const link = join(cwd, ".claude/skills", name);
+    mkdirSync(dirname(link), { recursive: true });
+    if (existsSync(link) || isLink(link)) rmSync(link, { recursive: true, force: true });
+    try {
+      symlinkSync(relative(dirname(link), target), link, "dir");
+    } catch {
+      cpSync(target, link, { recursive: true });
+    }
+    return `Installed skill ${relative(cwd, target).replaceAll("\\", "/")} (and .claude/skills/${name})`;
+  });
+}
+var isLink = (path) => {
+  try {
+    return lstatSync(path).isSymbolicLink();
+  } catch {
+    return false;
+  }
+};
+var McpConfig = z.looseObject({ mcpServers: z.record(z.string(), z.unknown()).optional() });
+function registerMcp(cwd, args) {
+  const server = process.platform === "win32" ? { command: "cmd", args: ["/c", "npx", "state-scenarios", ...args] } : { command: "npx", args: ["state-scenarios", ...args] };
+  const files = [".mcp.json", ...existsSync(join(cwd, ".cursor")) ? [".cursor/mcp.json"] : []];
+  return files.map((file) => {
+    const path = join(cwd, file);
+    const config = existsSync(path) ? McpConfig.parse(JSON.parse(readFileSync(path, "utf8"))) : {};
+    if (config.mcpServers?.["state-scenarios"]) return `Kept the state-scenarios server in ${file}`;
+    writeFileSync(
+      path,
+      `${JSON.stringify(
+        { ...config, mcpServers: { ...config.mcpServers, "state-scenarios": server } },
+        null,
+        2
+      )}
+`
+    );
+    return `Registered the state-scenarios MCP server in ${file}`;
+  });
+}
+export {
+  SKILL_NAMES,
+  guide,
+  installSkills,
+  registerMcp
+};
+//# sourceMappingURL=skills-NQRJHKHG.js.map

package/dist/skills-NQRJHKHG.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/skills.ts"],"sourcesContent":["import {\n  cpSync,\n  existsSync,\n  lstatSync,\n  mkdirSync,\n  readdirSync,\n  readFileSync,\n  rmSync,\n  symlinkSync,\n  writeFileSync,\n} from 'node:fs';\nimport { dirname, join, relative } from 'node:path';\nimport { fileURLToPath } from 'node:url';\nimport { z } from 'zod';\nimport { CliError } from './errors.js';\n\n/** Shipped in the package, so the guidance always matches the installed version. */\nconst SKILLS = fileURLToPath(new URL('../skills/', import.meta.url));\n\nexport const SKILL_NAMES = ['state-scenarios', 'create-scenario-map'];\n\nconst topics = () =>\n  readdirSync(join(SKILLS, 'state-scenarios/references')).map((f) => f.replace(/\\.md$/, '')).toSorted();\n\n/** The skill's overview, or one topic of it. */\nexport function guide(topic?: string): string {\n  if (!topic) return readFileSync(join(SKILLS, 'state-scenarios/SKILL.md'), 'utf8');\n\n  if (!topics().includes(topic)) {\n    throw new CliError('INVALID_ARGUMENT', `Unknown topic \"${topic}\". Topics: ${topics().join(', ')}`);\n  }\n\n  return readFileSync(join(SKILLS, `state-scenarios/references/${topic}.md`), 'utf8');\n}\n\n/**\n * Copy the skills into `.agents/skills/` (Codex, Cursor and others read it) and link them\n * from `.claude/skills/` for Claude Code. Rerun after an upgrade to update them.\n */\nexport function installSkills(cwd: string): string[] {\n  return SKILL_NAMES.map((name) => {\n    const target = join(cwd, '.agents/skills', name);\n    rmSync(target, { recursive: true, force: true });\n    mkdirSync(dirname(target), { recursive: true });\n    cpSync(join(SKILLS, name), target, { recursive: true });\n\n    const link = join(cwd, '.claude/skills', name);\n    mkdirSync(dirname(link), { recursive: true });\n\n    if (existsSync(link) || isLink(link)) rmSync(link, { recursive: true, force: true });\n\n    try {\n      symlinkSync(relative(dirname(link), target), link, 'dir');\n    } catch {\n      // Windows without Developer Mode can't create symlinks: copy instead.\n      cpSync(target, link, { recursive: true });\n    }\n\n    return `Installed skill ${relative(cwd, target).replaceAll('\\\\', '/')} (and .claude/skills/${name})`;\n  });\n}\n\nconst isLink = (path: string) => {\n  try {\n    return lstatSync(path).isSymbolicLink();\n  } catch {\n    return false;\n  }\n};\n\nconst McpConfig = z.looseObject({ mcpServers: z.record(z.string(), z.unknown()).optional() });\n\n/**\n * Register `state-scenarios mcp` with Claude Code (`.mcp.json`) and, when the project uses it,\n * Cursor (`.cursor/mcp.json`). An existing entry is kept.\n */\nexport function registerMcp(cwd: string, args: string[]): string[] {\n  // Windows can't spawn npx directly from an MCP client: go through cmd.\n  const server = process.platform === 'win32'\n    ? { command: 'cmd', args: ['/c', 'npx', 'state-scenarios', ...args] }\n    : { command: 'npx', args: ['state-scenarios', ...args] };\n\n  const files = ['.mcp.json', ...(existsSync(join(cwd, '.cursor')) ? ['.cursor/mcp.json'] : [])];\n\n  return files.map((file) => {\n    const path = join(cwd, file);\n    const config = existsSync(path) ? McpConfig.parse(JSON.parse(readFileSync(path, 'utf8'))) : {};\n\n    if (config.mcpServers?.['state-scenarios']) return `Kept the state-scenarios server in ${file}`;\n    writeFileSync(\n      path,\n      `${\n        JSON.stringify(\n          { ...config, mcpServers: { ...config.mcpServers, 'state-scenarios': server } },\n          null,\n          2,\n        )\n      }\\n`,\n    );\n\n    return `Registered the state-scenarios MCP server in ${file}`;\n  });\n}\n"],"mappings":"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","names":[]}

package/dist/skills.d.ts

@@ -0,0 +1,13 @@
+export declare const SKILL_NAMES: string[];
+/** The skill's overview, or one topic of it. */
+export declare function guide(topic?: string): string;
+/**
+ * Copy the skills into `.agents/skills/` (Codex, Cursor and others read it) and link them
+ * from `.claude/skills/` for Claude Code. Rerun after an upgrade to update them.
+ */
+export declare function installSkills(cwd: string): string[];
+/**
+ * Register `state-scenarios mcp` with Claude Code (`.mcp.json`) and, when the project uses it,
+ * Cursor (`.cursor/mcp.json`). An existing entry is kept.
+ */
+export declare function registerMcp(cwd: string, args: string[]): string[];

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "state-scenarios-cli",
-  "version": "0.2.0",
-  "description": "state-scenarios CLI: validate, list, screenshot (shoot) and AI-suggest scenarios.",
+  "version": "0.4.0",
+  "description": "state-scenarios CLI: init, guide, doctor, validate, list, shoot, record, mcp, suggest and promote scenarios.",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -10,7 +10,8 @@
   },
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "bin": {
     "state-scenarios": "./dist/cli.js"
@@ -28,7 +29,7 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.131.0",
     "ajv": "^8.20.0",
-    "state-scenarios": "^0.2.0",
+    "state-scenarios": "^0.4.0",
     "zod": "4.6.5"
   },
   "peerDependencies": {

package/skills/create-scenario-map/SKILL.md

@@ -0,0 +1,88 @@
+---
+name: create-scenario-map
+description: >
+  Map every user-facing feature of an app that uses state-scenarios to the UI states it can be in
+  (loading, empty, error, signed out, edge cases), mark which have scenarios, capture the missing
+  ones from the running app, and write it all as a project-local skill so later agents can show,
+  check or screenshot any state. Use for /create-scenario-map, "which states are we missing",
+  "map our UI states", or before relying on scenarios for QA or docs images.
+disable-model-invocation: true
+---
+
+# Create a scenario map
+
+A coding agent that changes UI should be able to open every state that change touches, by name,
+without clicking through the app. This skill writes that map for one project as a skill,
+`.agents/skills/scenarios-<app>/`, built on state-scenarios, then captures the most important
+missing states and proves the map once. Write it for the next agent, which reads it cold, mid-task.
+
+The `state-scenarios` skill is the reference for the library. Read it first and link to its topics
+(`setup`, `capture`, `verify`, `mcp`, `debugging`) rather than restating them. It is
+`.agents/skills/state-scenarios/SKILL.md` once `npx state-scenarios init` ran, and
+`npx state-scenarios guide <topic>` prints it from the installed package.
+
+## 1. Learn the app from the repo, not the user
+
+Ask the user only what the code can't tell you.
+
+| Question           | Where the answer is                                                                                            | What it decides                                                                                                                                      |
+| ------------------ | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Wiring             | `startScenarios` call, scenarios folder, `doctor`                                                              | Nothing wired: follow topic `setup` first. `doctor` must pass before you map anything                                                                |
+| Run                | Dev command, port, env vars, seed data                                                                         | The launch line and `--base-url`                                                                                                                     |
+| Features           | Routes, navigation, page components, docs                                                                      | One map row per user-facing feature                                                                                                                  |
+| States             | Each feature's data fetching, conditionals, error boundaries, empty branches, permission checks, feature flags | The states per feature: loading, empty, populated, long content, error, partial failure, signed out, no permission, and the feature's own edge cases |
+| Endpoints          | API clients, query hooks, existing MSW handlers and fixtures                                                   | Which `network` entries a state needs, and whether `handlers` can reuse test handlers                                                                |
+| Auth               | How the app decides who is signed in                                                                           | The `signed-in` base scenario (topic `auth`)                                                                                                         |
+| Existing scenarios | `npx state-scenarios list <dir> --json`                                                                        | Which states are covered already                                                                                                                     |
+
+## 2. Write the map
+
+`.agents/skills/scenarios-<app>/SKILL.md`, with frontmatter (`name: scenarios-<app>`, a description
+naming the app and when to use it), then:
+
+| Section        | Holds                                                                                          |
+| -------------- | ---------------------------------------------------------------------------------------------- |
+| Read first     | One line sending the reader to the `state-scenarios` skill, and the scenarios folder           |
+| Launch         | The exact dev command, port, env and seed data; the line that shows it's ready                 |
+| Doctor         | `npx state-scenarios doctor <dir> --base-url <url>`; run it first whenever something looks off |
+| Open a state   | The link pattern and the MCP server; that links beat clicking through                          |
+| Base scenarios | What `default` and `signed-in` (or the app's equivalents) contain, and which to extend         |
+| Map            | A table: feature, route, state, scenario name, status (`covered`, `missing`, `can't mock`)     |
+| Gotchas        | What reads as broken but isn't; third parties in `ignore`; states only the server can produce  |
+
+For more than a handful of features, put one file per feature under `features/` with the same
+columns and link them from the map.
+
+Name scenarios `<feature>-<state>`, e.g. `orders-empty`, `orders-error`, `checkout-card-declined`.
+
+## 3. Fill the most important gaps
+
+Capture the missing states users hit most (empty and error for each main feature first), using
+topic `capture`: over MCP, `open_app` or `open_scenario`, act until the state shows, `check_ready`,
+`save_scenario` with `extends`. Mark each `covered` as you go. Leave the rest `missing`; the map is
+the to-do list.
+
+A state the browser can't produce (server-rendered data, a native permission prompt) is
+`can't mock`, with one line on why.
+
+## 4. Prove it before handing over
+
+1. `doctor` passes.
+2. `npx state-scenarios validate <dir>` passes.
+3. `npx state-scenarios shoot <dir> --base-url <url> --only <the scenarios you added>` passes. Look
+   at each screenshot: it must show the state the map says.
+4. Open one state through the link pattern the map gives.
+
+Fix what fails. A map that was never run is a draft.
+
+## 5. Hand over
+
+Tell the user: the skill path, features mapped, states covered and missing, the scenarios you added,
+and the screenshot folder. Don't commit for them. When a feature gains a state, its map row changes
+in the same commit as the scenario.
+
+## Rules
+
+- Write from what you observed. A section that could apply to any app isn't finished.
+- No secrets or real personal data in scenarios or the map. Use fictional people.
+- Link the `state-scenarios` topics instead of repeating them.

package/skills/state-scenarios/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: state-scenarios
+description: >
+  Open any UI state of a web app from a URL with state-scenarios: JSON scenarios that mock API
+  responses, set URL params and store or cache state. Covers adding it to an app, writing and
+  capturing scenarios, signed-in states, strict network mode, checking a UI change across every
+  state with `shoot`, docs screenshots and videos with `record`, driving the app over the
+  `state-scenarios mcp` server, and fixing failures with `doctor` and error codes. Use when a
+  project depends on state-scenarios, when asked to show, test, demo, screenshot or record a
+  loading, empty, error, signed-in or edge-case state, after changing UI code, or when a
+  `?scenario=` link or `shoot` run fails.
+---
+
+# state-scenarios: any UI state from a URL
+
+A scenario is a JSON file describing one UI state: the route, the API responses (served by MSW in
+the browser), URL params, and store or cache state. `startScenarios` runs before the app renders and
+applies the scenario named in the URL. `?scenario=orders-empty` opens that state; nothing else in
+the app changes.
+
+```json
+{
+  "$schema": "../scenario.schema.json",
+  "name": "orders-empty",
+  "extends": "default",
+  "path": "/orders",
+  "network": [{ "method": "GET", "path": "/api/orders", "response": { "body": [] } }],
+  "ready": "text=No orders yet"
+}
+```
+
+## Reach a state with a link, not by clicking
+
+Any browser tool can open a state directly: the `state-scenarios mcp` server, Playwright,
+agent-browser, Playwright MCP, or an AI testing agent. Use the link instead of clicking through the
+app to reach a state:
+
+```
+http://localhost:5173/orders?scenario=orders-empty&scenario-strict
+```
+
+`npx state-scenarios list <dir> --base-url <url> --json` prints every scenario with its link.
+`&scenario-strict` answers any request the scenario didn't mock with a 501, so nothing reaches a
+real backend. Once `<html data-scenario="orders-empty">` is set and the `ready` selector is
+visible, the state is on screen.
+
+## Topics
+
+Read the topic for the job before you start. The files sit next to this one, and
+`npx state-scenarios guide <topic>` prints the same text from the installed package.
+
+| Topic               | File                                                               | Read it when                                                                                         |
+| ------------------- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- |
+| `setup`             | [references/setup.md](references/setup.md)                         | Adding state-scenarios to an app: install, wiring before render, routers created on import, adapters |
+| `writing-scenarios` | [references/writing-scenarios.md](references/writing-scenarios.md) | Writing or editing scenario JSON: fields, `extends`, sequences, loading states, rules                |
+| `capture`           | [references/capture.md](references/capture.md)                     | Making a scenario from the running app: the panel, `?scenario-record`, MCP `save_scenario`           |
+| `auth`              | [references/auth.md](references/auth.md)                           | Signed-in and signed-out states, cookies, apps that validate a token on startup                      |
+| `network`           | [references/network.md](references/network.md)                     | Strict mode, `allow`, `ignore` for analytics, an existing MSW setup, named handlers                  |
+| `verify`            | [references/verify.md](references/verify.md)                       | Checking a UI change across every state with `shoot`, reading failure pages, PR evidence             |
+| `media`             | [references/media.md](references/media.md)                         | Screenshots and videos for docs and websites: viewports, dark mode, locales, `record`                |
+| `mcp`               | [references/mcp.md](references/mcp.md)                             | Driving the live app from a coding agent: open, observe, act, check ready, save                      |
+| `debugging`         | [references/debugging.md](references/debugging.md)                 | Something fails: `doctor`, error codes and exit codes, common causes                                 |
+
+## Workflow
+
+1. Look at what exists: `state-scenarios` in `package.json`, the scenarios folder (often
+   `src/scenarios/*.json`), and where `startScenarios` is called. Nothing there: follow `setup`.
+2. If anything looks off, run `npx state-scenarios doctor <dir> --base-url <url>` first. It checks
+   the wiring one step at a time and prints the fix for each problem.
+3. New state: capture it from the running app (topic `capture`) instead of writing fixtures by
+   hand. Set a `ready` selector and check it matches.
+4. Changed UI: `npx state-scenarios shoot <dir> --base-url <url>` and look at the screenshots of the
+   states your change touches (topic `verify`). Each failed scenario gets `<out>/<name>.md` with the
+   fix; read that page, not the JSON.
+5. `npx state-scenarios validate <dir>` before committing.
+
+## Rules
+
+- Every scenario gets a `ready` selector: text or a role that appears only once this state is on
+  screen. Without it, tools screenshot whatever rendered first.
+- Run in strict mode (`&scenario-strict`, the default for `shoot`, `openScenario` and MCP). A
+  request that reaches a real backend makes the state depend on that backend.
+- Prefer mocking the network over setting store state: a mocked response exercises the app's real
+  fetching and error handling. Use `state` only for what no response can produce.
+- Prefer capturing over hand-writing fixtures, and `extends: "default"` so a scenario holds only
+  what differs.
+- Never put real secrets or personal data in a scenario. Recording redacts secret-looking fields
+  and re-issues JWTs unsigned, but check what it saved before committing.
+- Don't edit recorded fixtures by hand to make a test pass; record again or fix the app.
+- Keep `startScenarios` behind the app's development check so production bundles skip it.
+- Run the CLI as `npx state-scenarios ...` (or `pnpm exec state-scenarios ...`).

package/skills/state-scenarios/references/auth.md

@@ -0,0 +1,52 @@
+# Signed-in and signed-out states
+
+## Cookie sessions
+
+`cookiesAdapter()` from `state-scenarios/cookies` sets cookies before the app renders, so a cookie
+check lets the scenario in:
+
+```json
+{ "name": "signed-in", "state": { "cookies": { "session": "scenario" } } }
+```
+
+It overwrites real cookies of the same name. It applies from catalog scenarios only, never from
+inline `#scenario-data=` links, which anyone can write.
+
+## Apps that validate a token on startup
+
+Many apps read a stored token, send it to a validate endpoint, decode the JWT that comes back and
+fill stores from its claims. A signed-in scenario then needs the cookie (so the check runs) and a
+mocked validate response carrying a token. `unsignedJwt(claims)` builds one: UTF-8 safe, so names
+in any script decode, and unsigned (`alg: "none"`), so anything that verifies signatures rejects
+it. Build that scenario in code and let JSON scenarios extend it:
+
+```ts
+import { type ScenarioInput, startScenarios, unsignedJwt } from 'state-scenarios';
+import { cookiesAdapter } from 'state-scenarios/cookies';
+
+const signedIn: ScenarioInput = {
+  name: 'signed-in',
+  state: { cookies: { session: 'scenario' } }, // so the app's startup check runs
+  network: [{
+    method: 'POST',
+    path: '/api/auth/validate-token',
+    response: {
+      body: {
+        token: unsignedJwt({ sub: 'user-1', name: 'Amara Okafor', roles: ['admin'], exp: 4102444800 }),
+      },
+    },
+  }],
+};
+
+await startScenarios({ scenarios: [signedIn], adapters: [cookiesAdapter()] });
+```
+
+Use the claim names and endpoint the app reads; find them where the app decodes the token. Set
+`exp` in the future when the app checks expiry. `?scenario-record` captures the real exchange too;
+recording keeps the claims and drops the signature.
+
+## Signed out and expired
+
+Mock the validate endpoint with a 401 (or whatever the app treats as an expired session), and ready
+on the sign-in screen's heading. A scenario without the cookie only shows signed out in a browser
+that never had it, such as `shoot` and the MCP server, which start each run fresh.

package/skills/state-scenarios/references/capture.md

@@ -0,0 +1,45 @@
+# Capturing scenarios from the running app
+
+Capturing beats writing fixtures by hand: the responses are real, and the scenario matches what the
+app actually renders.
+
+## From a coding agent (MCP)
+
+With the `state-scenarios` MCP server registered (topic `mcp`):
+
+1. `open_app { path: "/orders", record: true }`: requests reach the real backend and their JSON
+   responses are recorded. Or `open_scenario { name: "default" }` to start from a scenario.
+2. Drive the app into the state with `click`, `fill` and `press`; `observe` shows the page.
+3. `check_ready { selector: "text=No orders yet" }` until it reports `match` and `visible`. Its
+   `suggestions` list distinctive selectors on the page.
+4. `save_scenario { name: "orders-empty", ready: "text=No orders yet", extends: "default" }` writes
+   `<dir>/orders-empty.json` with only the differences from `default`, and reports problems.
+5. `open_scenario { name: "orders-empty" }` replays it offline in strict mode. It should come back
+   with `ok: true`.
+
+## From the panel (people)
+
+1. Open the app with `?scenario-record` and click through to the state.
+2. Panel → **Save as scenario** → **Mark ready** and click distinctive UI (or pick a suggestion).
+   The line under Ready says whether it matches.
+3. Choose **Extends** (`default` when present) → **Save to src/scenarios** (Vite plugin or Next.js
+   route), or **Download JSON**. **Copy link** shares a self-contained snapshot instead.
+
+## From code
+
+`captureScenario(session, { name, ready, base })` returns `{ flat, forCatalog }`; write `forCatalog`
+to the scenarios folder. `checkReadySelector` and `suggestReadySelectors` check and propose ready
+selectors.
+
+## What recording keeps and removes
+
+- JSON responses only. Repeated calls to one endpoint become a `sequence` in call order.
+- Secrets: values under secret-like keys (`password`, `secret`, `apiKey`, `token`, `sessionId`, …)
+  become `"[redacted]"`, and signed JWTs are re-issued unsigned with the same claims, so the app
+  still decodes them but no server accepts them. The browser console lists what was redacted.
+- Inside any string, `Bearer`/`Basic` credentials, `user:pass@` in URLs and signed URL params
+  are redacted too.
+- Saving applies the same rules to adapter state, and leaves secret URL params (`key`,
+  `access_token`, …) out of `url` and recorded queries.
+- Personal data (names, emails, addresses) is kept. Record with a test account, or replace it
+  before committing.

package/skills/state-scenarios/references/debugging.md

@@ -0,0 +1,52 @@
+# Debugging
+
+Start with doctor. It is read-only: it opens one scenario and writes nothing.
+
+```bash
+npx state-scenarios doctor src/scenarios --base-url http://localhost:5173
+```
+
+It checks, in order: the scenarios parse and resolve; ffmpeg; the skills and MCP server are
+installed; the dev server answers; `/mockServiceWorker.js` is served when scenarios mock the
+network; Chromium starts; a scenario becomes active and shows its ready selector; the panel can
+save into the project. Each problem prints its code and fix. `--json` for scripts.
+
+## Exit codes
+
+| Exit | Class  | Meaning                                                                      |
+| ---: | ------ | ---------------------------------------------------------------------------- |
+|    0 |        | Everything passed                                                            |
+|    1 | failed | A scenario ran and failed, or validation found problems                      |
+|    2 | config | Bad arguments, invalid or unknown scenarios                                  |
+|    3 | infra  | Something needed is missing or down: dev server, browser, ffmpeg, MSW worker |
+
+## Error codes
+
+| Code                  | Exit | Cause                                                                | Fix                                                                                                                             |
+| --------------------- | ---: | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `SESSION_NOT_STARTED` |    1 | `<html data-scenario>` never named the scenario                      | `startScenarios` must run and be awaited before render, outside production-only code; import routers created on import after it |
+| `SCENARIO_NOT_IN_APP` |    1 | The session runs, but the app's catalog has no scenario by that name | Add the file to the folder or list the app loads; reload or restart the dev server for new files                                |
+| `READY_TIMEOUT`       |    1 | The ready selector never became visible                              | Read `<out>/<name>.md` and the screenshot: fix the selector or the app                                                          |
+| `UNMOCKED_REQUEST`    |    1 | The scenario didn't cover a request                                  | Add the pasted `network` entries, `extends` a scenario that has them, or `ignore` third-party SDKs                              |
+| `PAGE_ERROR`          |    1 | Uncaught exception while rendering                                   | Fix the app, or the fixture that crashes it                                                                                     |
+| `CONSOLE_ERROR`       |    1 | `console.error` during render                                        | Same; browser "Failed to load resource" logs are not counted                                                                    |
+| `ELEMENT_NOT_FOUND`   |    1 | `--element` matched nothing visible                                  | Check the selector                                                                                                              |
+| `STEPS_FAILED`        |    1 | A `record` step threw                                                | Fix the step; selectors must match the scenario's UI                                                                            |
+| `INVALID_ARGUMENT`    |    2 | A flag or argument is wrong                                          | The message says which                                                                                                          |
+| `INVALID_SCENARIO`    |    2 | A scenario file doesn't parse or resolve                             | `validate` lists them                                                                                                           |
+| `UNKNOWN_SCENARIO`    |    2 | A name isn't in the catalog                                          | The message lists known names                                                                                                   |
+| `DEV_SERVER_DOWN`     |    3 | Nothing answers at `--base-url`                                      | Start the dev server, or pass the URL it prints                                                                                 |
+| `BROWSER_MISSING`     |    3 | Playwright or Chromium isn't installed                               | `npm i -D @playwright/test && npx playwright install chromium`                                                                  |
+| `FFMPEG_MISSING`      |    3 | `record` needs ffmpeg                                                | Install it, or set `FFMPEG_PATH`                                                                                                |
+| `WORKER_NOT_SERVED`   |    3 | `/mockServiceWorker.js` 404s                                         | `msw({ mode: 'worker-only' })` in Vite, or `npx msw init public`                                                                |
+
+## Common causes
+
+- A scenario works in the panel but not from a link: the app reads the URL before
+  `startScenarios` finishes. Await it before render.
+- A state flickers to real data: the scenario misses a request, so it went to the backend. Use
+  strict mode and read the unmocked list.
+- Switching scenarios reloads the page: expected when URL params differ, state can't be un-applied,
+  or scenarios mock the network without `refresh`.
+- A path with a file extension (`/api/data.json`) passes as an asset in strict mode; mock it
+  explicitly.

package/skills/state-scenarios/references/mcp.md

@@ -0,0 +1,39 @@
+# Driving the app over MCP
+
+`state-scenarios mcp <dir> --base-url <url>` serves the running app to a coding agent over MCP
+(stdio). `init` registers it in `.mcp.json` (Claude Code) and `.cursor/mcp.json` (Cursor). By hand:
+
+```bash
+claude mcp add state-scenarios -- npx state-scenarios mcp src/scenarios --base-url http://localhost:5173
+codex mcp add state-scenarios -- npx state-scenarios mcp src/scenarios --base-url http://localhost:5173
+```
+
+The dev server must already be running. Each agent's client starts its own server, and each server
+has its own headless browser page. Browser flags (`--viewport`, `--locale`, `--timezone`,
+`--color-scheme`) apply.
+
+## Tools
+
+| Tool                     | Does                                                                                                                            |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `list_scenarios`         | Every scenario with description, ready selector and link                                                                        |
+| `validate`               | Problems in the catalog; empty means valid                                                                                      |
+| `open_scenario`          | Opens a scenario in strict mode, waits for ready; returns codes, unmocked requests, errors and a screenshot                     |
+| `open_app`               | Opens a path without a scenario; `record: true` records real responses for `save_scenario`                                      |
+| `observe`                | The page as an accessibility tree, plus URL, active scenario, unmocked requests and errors                                      |
+| `screenshot`             | PNG of the page or of one element                                                                                               |
+| `click`, `fill`, `press` | Act on the page; selectors are Playwright selectors (`text=Save`, `role=button[name="Save"]`, CSS)                              |
+| `check_ready`            | Whether a selector matches and is visible now, plus selectors that would work                                                   |
+| `save_scenario`          | Saves the current state as `<dir>/<name>.json`, `extends` writing only differences; refuses to overwrite unless `replace: true` |
+
+Failed calls return `isError` with a code in brackets, e.g. `[UNKNOWN_SCENARIO]`.
+
+## Loops
+
+Check a change: `list_scenarios`, then `open_scenario` for each affected state; read the codes and
+look at the screenshot.
+
+Add a state: `open_app` (with `record: true`) or `open_scenario`, act until the state shows,
+`check_ready`, `save_scenario`, then `open_scenario` on the new name to prove it replays offline.
+
+The panel is hidden in MCP sessions; agents read the page through `observe`.

package/skills/state-scenarios/references/media.md

@@ -0,0 +1,50 @@
+# Screenshots and videos for docs and websites
+
+## Screenshots
+
+```bash
+npx state-scenarios shoot src/scenarios --base-url http://localhost:5173 --out shots \
+  --no-panel --viewport 1440x900 --scale 2 --color-scheme dark --element main
+```
+
+- `--no-panel` hides the dev panel. `--scale 2` gives sharp images on high-density screens.
+- `--element <selector>` captures one component instead of the full page.
+- A scenario's `viewport` overrides `--viewport`, so phone and desktop layouts shoot in one run.
+- `--locale` (BCP 47: `en-GB`, `de-DE`, `ar-EG`, `hi-IN`, `ja-JP`, `pt-BR`) and `--timezone` (IANA:
+  `Europe/Berlin`, `Asia/Kolkata`, `America/Sao_Paulo`) set what `Intl`, `Date` and
+  `navigator.language` report. Set both, or shots change with each machine's settings. Run once
+  per market to show dates, numbers, currencies and right-to-left layouts as people there see them.
+
+## Videos
+
+```ts
+// steps.ts: scenario name → what to do once it is ready
+import type { Page } from '@playwright/test';
+
+export default {
+  'search-no-results': async (page: Page) => {
+    await page.getByRole('searchbox').click();
+    await page.keyboard.type('Atlantis', { delay: 100 });
+  },
+};
+```
+
+```bash
+npx state-scenarios record src/scenarios --base-url http://localhost:5173 --steps steps.ts --format mp4
+```
+
+- The panel is hidden and a cursor is drawn (Playwright videos don't show the mouse). Actions are
+  slowed slightly so the cursor reaches each target before the click.
+- The video starts once the scenario is ready and holds the last frame briefly. Uncropped
+  `--format webm` is the exception: it keeps the page load, and needs no ffmpeg.
+- `--format mp4` (default) plays in every browser and phone at a fraction of a GIF's size; use it
+  on websites. `--format gif` for READMEs and other image-only places. `--element` crops: the
+  element is scrolled into view first, and one larger than the viewport is cut to the visible part
+  (use a larger `--viewport`). Steps that scroll the page move the element out of the crop.
+- Video records at viewport size, so use a larger `--viewport` for sharper video; `--scale`
+  affects screenshots only.
+- MP4, GIF and `--element` need ffmpeg on `PATH`, or `FFMPEG_PATH`. Uncropped WebM doesn't.
+- In your own Playwright scripts, `showCursor(page)` from `state-scenarios/playwright` draws the
+  cursor; call it before `openScenario(page, name, { panel: false })`.
+
+Use demo data in scenarios meant for public images: fictional names, no real customer records.