@asrunjs/asrun 0.5.2 → 0.6.0

package/dist/scripts/go.mjs

@@ -1,188 +1,188 @@
-// One-liner for a fresh machine: install everything, prepare the workspace, then start the web UI and open it.
-// Plain Node on purpose: it may run before the dependencies are installed.
-//
-//   pnpm add -D @asrunjs/asrun        (or github:wizcas/asrun#v0.1.0)
-//   pnpm exec asrun init
-//   pnpm go
-import {spawn, spawnSync} from 'node:child_process';
-import fs from 'node:fs';
-import path from 'node:path';
-
-const FRAMEWORK = path.resolve(import.meta.dirname, '..');
-const PACKAGE = '@asrunjs/asrun';
-const MARKERS = ['.asrun.json', 'profiles.yaml'];
-const port = Number(process.env.ASRUN_UI_PORT ?? 4173);
-const url = `http://127.0.0.1:${port}`;
-const openBrowser = !process.argv.includes('--no-open');
-const shell = process.platform === 'win32';
-
-// `.env` next to the command, or the framework's own `.env`; a real environment variable always wins.
-function loadRootEnv(file) {
-  try {
-    for (const raw of fs.readFileSync(file, 'utf8').split(/\r?\n/)) {
-      if (process.env.ASRUN_ROOT !== undefined) return;
-      const match = /^(?:export\s+)?ASRUN_ROOT\s*=\s*(.*)$/.exec(raw.trim());
-      if (match) {
-        process.env.ASRUN_ROOT = path.resolve(path.dirname(file), match[1].trim().replace(/^(['"])(.*)\1$/, '$2'));
-      }
-    }
-  } catch {
-    // no .env: nothing to do
-  }
-}
-loadRootEnv(path.join(process.cwd(), '.env'));
-if (process.env.ASRUN_ROOT === undefined) loadRootEnv(path.join(FRAMEWORK, '.env'));
-
-// The workspace: the project that owns profiles.yaml, cases/ and tests/. Inside the framework repository
-// (which has none of those) the demo workspace is used, so the framework itself can be developed this way.
-function findWorkspace(from) {
-  for (let dir = path.resolve(from); ; dir = path.dirname(dir)) {
-    if (MARKERS.some((marker) => fs.existsSync(path.join(dir, marker)))) return dir;
-    if (path.dirname(dir) === dir) return null;
-  }
-}
-const demo = path.join(FRAMEWORK, 'examples', 'demo');
-const ROOT = (process.env.ASRUN_ROOT && path.resolve(process.env.ASRUN_ROOT)) || findWorkspace(process.cwd()) || demo;
-if (ROOT === FRAMEWORK && !fs.existsSync(demo)) {
-  console.error('No workspace found: run this command in the project that uses asrun, or set ASRUN_ROOT.');
-  process.exit(1);
-}
-
-const step = (n, text) => console.log(`\n\x1b[1;36m[${n}/4] ${text}\x1b[0m`);
-const warn = (text) => console.log(`\x1b[33m! ${text}\x1b[0m`);
-const fail = (text) => {
-  console.error(`\x1b[31m${text}\x1b[0m`);
-  process.exit(1);
-};
-const run = (command, args, options = {}) =>
-  spawnSync(command, args, {cwd: ROOT, stdio: 'inherit', shell, ...options}).status === 0;
-const exists = (command) => spawnSync(command, ['--version'], {stdio: 'ignore', shell}).status === 0;
-
-/** The JavaScript entry point of a package's command-line tool, without relying on node_modules/.bin shims. */
-function packageBin(name, command = name) {
-  for (const base of [FRAMEWORK, path.dirname(path.dirname(FRAMEWORK)), ROOT]) {
-    const dir = path.join(base, 'node_modules', name);
-    const manifest = path.join(dir, 'package.json');
-    if (!fs.existsSync(manifest)) continue;
-    const bin = JSON.parse(fs.readFileSync(manifest, 'utf8')).bin;
-    const entry = typeof bin === 'string' ? bin : bin?.[command];
-    if (entry) return path.join(dir, entry);
-  }
-  return null;
-}
-
-/** The installed command of this workspace, or the framework's own bin while developing it here. */
-const bin = packageBin(PACKAGE) ?? path.join(FRAMEWORK, 'bin', 'asrun.mjs');
-/** The workspace's copy of the package, if any. */
-const installed = fs.existsSync(path.join(ROOT, 'node_modules', PACKAGE, 'package.json'));
-const frameworkRelative = installed
-  ? './' + path.relative(ROOT, path.join(ROOT, 'node_modules', PACKAGE)).split(path.sep).join('/')
-  : (() => {
-      const relative = path.relative(ROOT, FRAMEWORK).split(path.sep).join('/');
-      return relative === '' ? '.' : relative.startsWith('.') ? relative : `./${relative}`;
-    })();
-
-/** pnpm only installs dependencies normally; its build scripts need an explicit approval in pnpm-workspace.yaml. */
-function ensurePnpmWorkspace() {
-  if (frameworkRelative.startsWith('..')) return 'skipped';
-  const file = path.join(ROOT, 'pnpm-workspace.yaml');
-  const block = 'allowBuilds:\n  esbuild: true\n  ffmpeg-static: true\n';
-  if (!fs.existsSync(file)) {
-    fs.writeFileSync(file, `# asrun's dependencies (esbuild through tsx, ffmpeg-static) compile a binary on install.\n${block}`);
-    return 'created';
-  }
-  const text = fs.readFileSync(file, 'utf8');
-  if (text.includes('allowBuilds')) return 'kept';
-  fs.writeFileSync(file, `${text.replace(/\n*$/, '\n')}\n${block}`);
-  return 'updated';
-}
-
-async function uiIsUp() {
-  try {
-    return (await fetch(`${url}/api/info`, {signal: AbortSignal.timeout(1500)})).ok;
-  } catch {
-    return false;
-  }
-}
-
-function open(target) {
-  const [command, args] =
-    process.platform === 'darwin'
-      ? ['open', [target]]
-      : process.platform === 'win32'
-        ? ['cmd', ['/c', 'start', '', target]]
-        : ['xdg-open', [target]];
-  spawn(command, args, {stdio: 'ignore', detached: true}).on('error', () => {}).unref();
-}
-
-// ffmpeg joins the videos of a test's browser tabs into one. Never fatal: the optional ffmpeg-static package is the fallback.
-function ensureFfmpeg() {
-  // ffmpeg does not know `--version`, only `-version`.
-  if (spawnSync('ffmpeg', ['-version'], {stdio: 'ignore', shell}).status === 0) return console.log('ffmpeg: ok');
-  const installer =
-    process.platform === 'darwin' && exists('brew')
-      ? ['brew', ['install', 'ffmpeg']]
-      : process.platform === 'win32' && exists('winget')
-        ? ['winget', ['install', '--id', 'Gyan.FFmpeg', '-e', '--accept-source-agreements', '--accept-package-agreements']]
-        : null;
-  if (!installer) {
-    return warn('ffmpeg not found; the bundled ffmpeg-static is used instead. To install it yourself: brew install ffmpeg | winget install Gyan.FFmpeg | sudo apt install ffmpeg');
-  }
-  console.log(`ffmpeg not found, installing it: ${installer[0]} ${installer[1].join(' ')}`);
-  if (run(...installer)) console.log('ffmpeg: installed');
-  else warn('Could not install ffmpeg; the bundled ffmpeg-static is used instead.');
-}
-
-step(1, 'Checking this machine');
-const nodeMajor = Number(process.versions.node.split('.')[0]);
-if (nodeMajor < 22) fail(`Node 22 or newer is required (this is ${process.versions.node}). Install it from https://nodejs.org and run "pnpm go" again.`);
-console.log(`Node ${process.versions.node}: ok`);
-console.log(`workspace: ${ROOT}`);
-console.log(`framework: ${FRAMEWORK}${installed ? ' (installed)' : ' (development checkout)'}`);
-ensureFfmpeg();
-if (!exists('claude') && !exists('opencode')) {
-  warn('Neither "claude" (Claude Code) nor "opencode" found. Everything works except the AI steps (make cases, review, generate specs).');
-}
-
-step(2, 'Installing dependencies and the browser (a minute the first time, seconds after that)');
-const workspaceFile = ensurePnpmWorkspace();
-if (workspaceFile === 'created') console.log('pnpm-workspace.yaml: created (allowBuilds)');
-else if (workspaceFile === 'updated') console.log('pnpm-workspace.yaml: updated (allowBuilds)');
-const installRoot = frameworkRelative.startsWith('..') ? FRAMEWORK : ROOT;
-if (!run('pnpm', ['install'], {cwd: installRoot})) fail('Install failed. Fix the error above and run "pnpm go" again.');
-const playwright = packageBin('@playwright/test', 'playwright');
-if (playwright) {
-  if (!run(process.execPath, [playwright, 'install', 'chromium'])) warn('Could not install the Chromium browser; run "pnpm exec playwright install chromium".');
-} else {
-  warn('@playwright/test is not installed yet. Run this command again after the workspace files are in place.');
-}
-
-step(3, 'Preparing the workspace');
-// `--root` names the workspace, but the command runs where the person is: that is where `.env` belongs.
-if (!run(process.execPath, [bin, 'init', '--root', ROOT], {cwd: process.cwd()})) {
-  fail('Could not initialize the workspace. Run "pnpm asrun init" and read the message.');
-}
-run(process.execPath, [bin, 'doctor']);
-
-step(4, `Starting the web UI at ${url}`);
-if (await uiIsUp()) {
-  console.log('The UI is already running.');
-  if (openBrowser) open(url);
-  process.exit(0);
-}
-
-const env = {...process.env, ASRUN_ROOT: ROOT};
-const child = spawn(process.execPath, [bin, 'ui'], {cwd: ROOT, stdio: 'inherit', env, shell});
-// Ctrl+C reaches the UI server directly (same terminal); we only wait for it to shut down.
-process.on('SIGINT', () => {});
-process.on('SIGTERM', () => child.kill('SIGTERM'));
-child.on('exit', (code) => process.exit(code ?? 0));
-
-for (let i = 0; i < 240 && child.exitCode === null; i++) {
-  if (await uiIsUp()) {
-    console.log(`\n\x1b[1;32mReady: ${url}\x1b[0m  (Ctrl+C to stop)`);
-    if (openBrowser) open(url);
-    break;
-  }
-  await new Promise((resolve) => setTimeout(resolve, 500));
-}
+// One-liner for a fresh machine: install everything, prepare the workspace, then start the web UI and open it.
+// Plain Node on purpose: it may run before the dependencies are installed.
+//
+//   pnpm add -D @asrunjs/asrun        (or github:wizcas/asrun#<tag>)
+//   pnpm exec asrun init
+//   pnpm go
+import {spawn, spawnSync} from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+
+const FRAMEWORK = path.resolve(import.meta.dirname, '..');
+const PACKAGE = '@asrunjs/asrun';
+const MARKERS = ['.asrun.json', 'profiles.yaml'];
+const port = Number(process.env.ASRUN_UI_PORT ?? 4173);
+const url = `http://127.0.0.1:${port}`;
+const openBrowser = !process.argv.includes('--no-open');
+const shell = process.platform === 'win32';
+
+// `.env` next to the command, or the framework's own `.env`; a real environment variable always wins.
+function loadRootEnv(file) {
+  try {
+    for (const raw of fs.readFileSync(file, 'utf8').split(/\r?\n/)) {
+      if (process.env.ASRUN_ROOT !== undefined) return;
+      const match = /^(?:export\s+)?ASRUN_ROOT\s*=\s*(.*)$/.exec(raw.trim());
+      if (match) {
+        process.env.ASRUN_ROOT = path.resolve(path.dirname(file), match[1].trim().replace(/^(['"])(.*)\1$/, '$2'));
+      }
+    }
+  } catch {
+    // no .env: nothing to do
+  }
+}
+loadRootEnv(path.join(process.cwd(), '.env'));
+if (process.env.ASRUN_ROOT === undefined) loadRootEnv(path.join(FRAMEWORK, '.env'));
+
+// The workspace: the project that owns profiles.yaml, cases/ and tests/. Inside the framework repository
+// (which has none of those) the demo workspace is used, so the framework itself can be developed this way.
+function findWorkspace(from) {
+  for (let dir = path.resolve(from); ; dir = path.dirname(dir)) {
+    if (MARKERS.some((marker) => fs.existsSync(path.join(dir, marker)))) return dir;
+    if (path.dirname(dir) === dir) return null;
+  }
+}
+const demo = path.join(FRAMEWORK, 'examples', 'demo');
+const ROOT = (process.env.ASRUN_ROOT && path.resolve(process.env.ASRUN_ROOT)) || findWorkspace(process.cwd()) || demo;
+if (ROOT === FRAMEWORK && !fs.existsSync(demo)) {
+  console.error('No workspace found: run this command in the project that uses asrun, or set ASRUN_ROOT.');
+  process.exit(1);
+}
+
+const step = (n, text) => console.log(`\n\x1b[1;36m[${n}/4] ${text}\x1b[0m`);
+const warn = (text) => console.log(`\x1b[33m! ${text}\x1b[0m`);
+const fail = (text) => {
+  console.error(`\x1b[31m${text}\x1b[0m`);
+  process.exit(1);
+};
+const run = (command, args, options = {}) =>
+  spawnSync(command, args, {cwd: ROOT, stdio: 'inherit', shell, ...options}).status === 0;
+const exists = (command) => spawnSync(command, ['--version'], {stdio: 'ignore', shell}).status === 0;
+
+/** The JavaScript entry point of a package's command-line tool, without relying on node_modules/.bin shims. */
+function packageBin(name, command = name) {
+  for (const base of [FRAMEWORK, path.dirname(path.dirname(FRAMEWORK)), ROOT]) {
+    const dir = path.join(base, 'node_modules', name);
+    const manifest = path.join(dir, 'package.json');
+    if (!fs.existsSync(manifest)) continue;
+    const bin = JSON.parse(fs.readFileSync(manifest, 'utf8')).bin;
+    const entry = typeof bin === 'string' ? bin : bin?.[command];
+    if (entry) return path.join(dir, entry);
+  }
+  return null;
+}
+
+/** The installed command of this workspace, or the framework's own bin while developing it here. */
+const bin = packageBin(PACKAGE) ?? path.join(FRAMEWORK, 'bin', 'asrun.mjs');
+/** The workspace's copy of the package, if any. */
+const installed = fs.existsSync(path.join(ROOT, 'node_modules', PACKAGE, 'package.json'));
+const frameworkRelative = installed
+  ? './' + path.relative(ROOT, path.join(ROOT, 'node_modules', PACKAGE)).split(path.sep).join('/')
+  : (() => {
+      const relative = path.relative(ROOT, FRAMEWORK).split(path.sep).join('/');
+      return relative === '' ? '.' : relative.startsWith('.') ? relative : `./${relative}`;
+    })();
+
+/** pnpm only installs dependencies normally; its build scripts need an explicit approval in pnpm-workspace.yaml. */
+function ensurePnpmWorkspace() {
+  if (frameworkRelative.startsWith('..')) return 'skipped';
+  const file = path.join(ROOT, 'pnpm-workspace.yaml');
+  const block = 'allowBuilds:\n  esbuild: true\n  ffmpeg-static: true\n';
+  if (!fs.existsSync(file)) {
+    fs.writeFileSync(file, `# asrun's dependencies (esbuild through tsx, ffmpeg-static) compile a binary on install.\n${block}`);
+    return 'created';
+  }
+  const text = fs.readFileSync(file, 'utf8');
+  if (text.includes('allowBuilds')) return 'kept';
+  fs.writeFileSync(file, `${text.replace(/\n*$/, '\n')}\n${block}`);
+  return 'updated';
+}
+
+async function uiIsUp() {
+  try {
+    return (await fetch(`${url}/api/info`, {signal: AbortSignal.timeout(1500)})).ok;
+  } catch {
+    return false;
+  }
+}
+
+function open(target) {
+  const [command, args] =
+    process.platform === 'darwin'
+      ? ['open', [target]]
+      : process.platform === 'win32'
+        ? ['cmd', ['/c', 'start', '', target]]
+        : ['xdg-open', [target]];
+  spawn(command, args, {stdio: 'ignore', detached: true}).on('error', () => {}).unref();
+}
+
+// ffmpeg joins the videos of a test's browser tabs into one. Never fatal: the optional ffmpeg-static package is the fallback.
+function ensureFfmpeg() {
+  // ffmpeg does not know `--version`, only `-version`.
+  if (spawnSync('ffmpeg', ['-version'], {stdio: 'ignore', shell}).status === 0) return console.log('ffmpeg: ok');
+  const installer =
+    process.platform === 'darwin' && exists('brew')
+      ? ['brew', ['install', 'ffmpeg']]
+      : process.platform === 'win32' && exists('winget')
+        ? ['winget', ['install', '--id', 'Gyan.FFmpeg', '-e', '--accept-source-agreements', '--accept-package-agreements']]
+        : null;
+  if (!installer) {
+    return warn('ffmpeg not found; the bundled ffmpeg-static is used instead. To install it yourself: brew install ffmpeg | winget install Gyan.FFmpeg | sudo apt install ffmpeg');
+  }
+  console.log(`ffmpeg not found, installing it: ${installer[0]} ${installer[1].join(' ')}`);
+  if (run(...installer)) console.log('ffmpeg: installed');
+  else warn('Could not install ffmpeg; the bundled ffmpeg-static is used instead.');
+}
+
+step(1, 'Checking this machine');
+const nodeMajor = Number(process.versions.node.split('.')[0]);
+if (nodeMajor < 22) fail(`Node 22 or newer is required (this is ${process.versions.node}). Install it from https://nodejs.org and run "pnpm go" again.`);
+console.log(`Node ${process.versions.node}: ok`);
+console.log(`workspace: ${ROOT}`);
+console.log(`framework: ${FRAMEWORK}${installed ? ' (installed)' : ' (development checkout)'}`);
+ensureFfmpeg();
+if (!exists('claude') && !exists('opencode')) {
+  warn('Neither "claude" (Claude Code) nor "opencode" found. Everything works except the AI steps (make cases, review, generate specs).');
+}
+
+step(2, 'Installing dependencies and the browser (a minute the first time, seconds after that)');
+const workspaceFile = ensurePnpmWorkspace();
+if (workspaceFile === 'created') console.log('pnpm-workspace.yaml: created (allowBuilds)');
+else if (workspaceFile === 'updated') console.log('pnpm-workspace.yaml: updated (allowBuilds)');
+const installRoot = frameworkRelative.startsWith('..') ? FRAMEWORK : ROOT;
+if (!run('pnpm', ['install'], {cwd: installRoot})) fail('Install failed. Fix the error above and run "pnpm go" again.');
+const playwright = packageBin('@playwright/test', 'playwright');
+if (playwright) {
+  if (!run(process.execPath, [playwright, 'install', 'chromium'])) warn('Could not install the Chromium browser; run "pnpm exec playwright install chromium".');
+} else {
+  warn('@playwright/test is not installed yet. Run this command again after the workspace files are in place.');
+}
+
+step(3, 'Preparing the workspace');
+// `--root` names the workspace, but the command runs where the person is: that is where `.env` belongs.
+if (!run(process.execPath, [bin, 'init', '--root', ROOT], {cwd: process.cwd()})) {
+  fail('Could not initialize the workspace. Run "pnpm asrun init" and read the message.');
+}
+run(process.execPath, [bin, 'doctor']);
+
+step(4, `Starting the web UI at ${url}`);
+if (await uiIsUp()) {
+  console.log('The UI is already running.');
+  if (openBrowser) open(url);
+  process.exit(0);
+}
+
+const env = {...process.env, ASRUN_ROOT: ROOT};
+const child = spawn(process.execPath, [bin, 'ui'], {cwd: ROOT, stdio: 'inherit', env, shell});
+// Ctrl+C reaches the UI server directly (same terminal); we only wait for it to shut down.
+process.on('SIGINT', () => {});
+process.on('SIGTERM', () => child.kill('SIGTERM'));
+child.on('exit', (code) => process.exit(code ?? 0));
+
+for (let i = 0; i < 240 && child.exitCode === null; i++) {
+  if (await uiIsUp()) {
+    console.log(`\n\x1b[1;32mReady: ${url}\x1b[0m  (Ctrl+C to stop)`);
+    if (openBrowser) open(url);
+    break;
+  }
+  await new Promise((resolve) => setTimeout(resolve, 500));
+}

package/dist/scripts/init.js

@@ -14,7 +14,7 @@ const USAGE = `Usage: pnpm asrun init [--root <dir>] [--update] [--force <path>]
   --force <path>  overwrite one file this tool writes, e.g. --force playwright.config.ts (may be repeated)
   --reset-rules   allow --force on AGENTS.md, CLAUDE.md or .claude/skills/** (project-owned rules)
   --no-env        do not write .env (ASRUN_ROOT)
-  --install [spec]  also add the dependency (default "asrun"; e.g. --install github:wizcas/asrun#v0.1.0)`;
+  --install [spec]  also add the dependency (default "asrun"; e.g. --install github:<owner>/<repo>#<tag>)`;
 /** Files `init` owns: `--update` rewrites exactly these, and a project never edits them. */
 export const GENERATED = [
     { file: 'playwright.config.ts', template: 'playwright.config.ts' },

package/docs/agents/case-format.md

@@ -0,0 +1,193 @@
+# Case document contract (for AI agents)
+
+This file describes the shape that `lib/case-doc.ts`, `lib/values.ts` and `lib/targets.ts` read, and how a generated
+spec consumes it. It holds no rules of its own: the rules are in the framework `AGENTS.md`, in the skill, and in the
+references listed at the end.
+
+Read `AGENTS.md` first. If a project has `.claude/skills/<skill>.md`, that override comes after the skill; the
+project's `AGENTS.md` §2 comes last and wins over both. `F1`–`F6` always win.
+
+## Identity and paths
+
+- A case id is its path below `cases/` without `.md`: `header-logo`, or `documents/landing-page` with **one** group
+  folder (`^[a-z0-9]+(-[a-z0-9]+)*(/[a-z0-9]+(-[a-z0-9]+)*)?$`).
+- The spec is at the same path below `tests/` (`tests/documents/landing-page.spec.ts`), with its `*-snapshots/`
+  folder next to it.
+- `cases/_template.md` and names starting with `_` are not cases.
+- Specs import the framework by package name (`@asrunjs/asrun/*`), so a group folder changes no import.
+
+## Fixed tokens
+
+The parser and the web panel match these literals. A project language never translates them:
+
+- Section headings: `## Goal`, `## Steps`, `## Expected`, `## Values`, `## Visual checks`, `## Targets`, `## Notes`,
+  and `## Source` when the case was made from notes.
+- Front matter keys: `id`, `title`, `login`, `suites`, `writes`, `writes-note`, `envs`.
+- Step tags at the end of a step line: `[input]`, `[writes]`, `[email]`.
+- Under a step: `- Ready when:` lines and `- Recipe (phase):` lines.
+- Target cards: `### T<n> <name>` and their references `[T<n>]`.
+- Questions: `🚫 TODO [blocking]`, `❓ TODO [non-blocking]`, `✍️ Answer:`, and the markers
+  `🔍 to be confirmed by QA` / `👁️ not observed`.
+- The last line of a run: `RESULT: ready` or `RESULT: needs-input`.
+
+## Front matter
+
+`---` on the first line, YAML, `---` to close. `pnpm case:check` calls `parseCaseMeta`, which refuses the file when
+`suites`, `writes` or `envs` break the rules below. `id`, `title` and `login` are required by convention: keep them
+present (the editor shows them, and the generator reads the title and the login mode), but `case:check` does not
+enforce them.
+
+| Key | Required | Rule |
+|---|---|---|
+| `id` | yes | The case id; the editor keeps it in step with the path. |
+| `title` | yes | One line. |
+| `login` | no | `required` (default) or `none`. `none` → the spec sets `test.use({mustLogin: false})`. |
+| `suites` | yes | Non-empty list of lowercase words. Missing `suites` is an error. |
+| `writes` | no | List of environments. Omit for read-only. Any value other than a known environment is refused; the old `writes: test-data` is refused with a hint. |
+| `writes-note` | with `writes` | Non-empty text: what the case creates or changes. |
+| `envs` | no | List of environments; every environment in `writes` must also be in `envs`. |
+
+`priority: <level>` is the old name of `suites`: it is read as `suites: [<level>]`, and naming both is an error.
+Unknown environments are refused against the environments of `profiles.yaml`.
+
+`caseTags(id)` (`@asrunjs/asrun/cases`) turns the front matter into Playwright tags: one `@<suite>` per suite, plus
+`@writes` for a case that writes. The spec passes `{tag: caseTags('<id>')}` to the top-level `test.describe`; it never
+hard-codes tags.
+
+## Sections
+
+### Steps
+
+- Numbered Markdown lines (`1.`, `2.`, ...). The spec wraps each one in `test.step('<n>. <text>', ...)` with the text
+  verbatim, including the number. Do not paraphrase it.
+- A step's tags are the last tokens of its line: `[input]` (a person makes a choice), `[writes]` (it changes data),
+  `[email]` (it sends email). All may appear.
+- `- Ready when:` is a sub-line of the step: the positive signal that what the step loads is there. The spec waits
+  for it before reading; it is not an assertion.
+- `- Recipe (phase):` is a sub-line of an `[input]`/`[writes]` step: what a person did in the browser during an
+  attended exploration (positions, `[asrun]` names, control labels; no selectors). A tagged step with no recipe is a
+  `needs-input` stop for `/gen-spec`.
+- A question block is indented under the sentence it belongs to: 4 spaces under a numbered step, 2 under a bullet.
+  The parent line is the suggestion, written as a finished sentence; the `TODO` line holds one question and optional
+  `(evidence)`; the block ends with `- ✍️ Answer:` at one level deeper and that line is the last line of the block.
+  Details: `.claude/skills/exploring-cases/references/open-questions.md`.
+
+### Expected
+
+A bullet list of behaviour that must hold for every profile. Profile differences are values, not prose.
+
+### Values
+
+One fenced `yaml` block, and nothing else in `## Values`:
+
+```yaml
+default:
+  createButton: Create New
+example-staging:
+  previewLogoAlt: Example
+```
+
+- The top level is a map of profile id (or `default`) to a map of keys. Any other shape, an unknown profile id, or
+  a value that is not a map is an error.
+- `requireValues('<id>', profile)` deep-merges `default` under the profile's own entry.
+- A profile with no entry and no `default` fails with "Missing values ...". An empty value or one that starts with
+  `TODO` fails with "Incomplete values ...". Fill them before running; never make a spec read the YAML itself.
+- Values hold literals only: names, labels, options, test-data names. The checks themselves stay in `## Steps` and
+  `## Expected`, and selectors come from `## Targets`.
+
+### Visual checks
+
+Bullets naming what must match a screenshot baseline. A check on a logo, image, icon, file, PDF, screenshot or
+repeated text needs a `[T<n>]` card.
+
+### Targets
+
+One card per distinct thing a check looks at:
+
+```markdown
+### T1 Header logo
+- What: <the thing itself, and what it is not when a look-alike exists>
+- Where: <region of the page, dialog, tab or file page>
+- Identified by: <role and name, test id, alt text or title; never a position>
+- Not: <look-alikes that must not be matched>
+- Ready when: <what shows that the content has loaded>
+- Reference <profile-id>: .explore/targets/<case-id>/T1-<profile-id>.png
+```
+
+- `What`, `Where` and `Identified by` are required for a card that is not blocking.
+- `Reference <profile-id>:` must point under `.explore/targets/<case-id>/` (git-ignored), or be `none: <reason>`.
+  A missing file on this machine is a warning, not a failure: a fresh checkout has the card but not the screenshot.
+- A card may hold a `🚫 TODO [blocking]` block. Such a card is not complete; `pnpm case:check` does not fail on it,
+  and the check that uses it is not generated yet.
+- Every `[T<n>]` in a step, a ready signal or a check resolves to a card. `pnpm case:check` fails on a reference with
+  no card.
+- The binding rules for choosing a target (never guess, list candidates) are in
+  `.claude/skills/exploring-cases/references/assertion-targets.md`.
+
+### Notes and Source
+
+`## Notes` is free prose for a reviewer. `## Source` holds the original lines of a memo, written by `/make-case`.
+The panel shows both read-only.
+
+## How a spec consumes the case
+
+```ts
+// case: cases/<id>.md
+import {caseTags} from '@asrunjs/asrun/cases';
+import {configureCase, expect, test} from '@asrunjs/asrun/fixtures';
+import {requireValues} from '@asrunjs/asrun/values';
+
+test.describe('<Case title>', {tag: caseTags('<id>')}, () => {
+  configureCase('<id>'); // no retries and a longer timeout for a case that writes data
+  test('<single outcome>', async ({page, profile}) => {
+    const expected = requireValues<{/* keys */}>('<id>', profile);
+
+    await test.step('1. <step text, verbatim>', async () => {
+      // an action that loads content: actAndWait(page, () => click(), {responses, ready})
+      // a confirmation that may appear: clickOptionalUntilHidden(confirm, target, {message})
+      // a download: verifyDownload(page, trigger, {kind})
+    });
+  });
+});
+```
+
+- The first line `// case: cases/<id>.md` is what `pnpm spec:lint` uses to find the case and its targets.
+- `// target: T<n>` goes on the line before an image/screenshot/PDF check. `// ready: <signal>` goes before a check
+  for absence ("missing", "empty", "hidden") and needs a positive wait before it. `// pages: <the case's words>` goes
+  before an `expectPdf` that follows a case limit written in strong words ("only", "exactly", "must").
+- Import `test`/`expect` from `@asrunjs/asrun/fixtures`, never from `@playwright/test`. Locators:
+  `getByTestId` > `getByRole` > `getByLabel` > text.
+- No branching on `profile.id` or `profile.env`: differences go into `## Values`, selectors into `## Targets`.
+- Paths are relative (`page.goto('/account/')`); the Playwright project sets `baseURL`.
+
+## Profiles, values and the write gate
+
+- Each entry in `profiles.yaml` is one Playwright project named after its `id`. A spec runs once per profile.
+- The `profile` fixture exposes `id`, `env`, `baseURL`, `account`, `tags`, `email`.
+- The `caseGate` fixture enforces `envs` and `writes` at run time, also when `playwright test` is called directly:
+  a case limited to some environments is skipped elsewhere; a case that writes elsewhere only is skipped with a
+  notice; a write in a non-staging environment needs the confirmation the CLI sets, never an environment variable
+  that was merely present.
+- Write cases: name everything `[asrun] ...`, register it with `records.track` right after creating it, remove it
+  newest first (also after a failure), turn retries off with `configureCase`, and keep email steps behind
+  `emailStepAllowed(profile, '<step title>')`.
+
+## Checks to run before reporting
+
+| Command | Must |
+|---|---|
+| `pnpm case:check [<id>]` | no `FAIL` |
+| `pnpm typecheck` | no errors |
+| `pnpm spec:lint <id>` | no `FAIL` |
+| `pnpm baselines:review <id>` | every new image is looked at (a person's job) |
+
+## Related references
+
+In the framework package:
+
+- `.claude/skills/exploring-cases/references/assertion-targets.md` — what a check looks at, and when to ask.
+- `.claude/skills/exploring-cases/references/readiness.md` — wait for the content, optional confirmations, downloads.
+- `.claude/skills/exploring-cases/references/open-questions.md` — question blocks and how answers are folded in.
+- `.claude/skills/exploring-cases/references/user-handoff.md` — attended exploration and the handoff card.
+- `.claude/skills/generating-specs/references/conventions.md` — spec shape, assertion layers, readable failures.
+- `docs/cases.md` — the same format for people writing a case by hand.