@asrunjs/asrun 0.10.0 → 0.11.0

package/dist/lib/explore-notes.js

@@ -0,0 +1,242 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { isValidCaseId } from './case-id.js';
+import { CASES_DIR, EXPLORE_DIR } from './paths.js';
+/**
+ * The local exploration note: what `/explore-case` saw on the page, in a form `/gen-spec` can read.
+ *
+ * It lives under `.explore/notes/<case-id>/<profile-id>.json`, one file per profile, so a run with `--profiles` never
+ * has to merge with an earlier one. `.explore/` is git-ignored local state: a note is optional, may be deleted at any
+ * time, and a fresh checkout simply has none (generation then replays the case as before).
+ *
+ * A note holds only what the case does not: locators the agent confirmed on the page, the data-call paths of the
+ * actions that load something, and the match count of a target card's element. Expected values stay in the case's
+ * `## Values`, ready signals in the case's `Ready when:` lines, and assertions nowhere near this file.
+ */
+export const NOTES_VERSION = 1;
+const HASH = /^[a-f0-9]{64}$/;
+const PROFILE_FILE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const STEP_KEY = /^[1-9]\d*$/;
+const TARGET_KEY = /^T[1-9]\d*$/;
+// A request pattern is a path, never a URL with a host or a query string that could carry a token.
+const UNSAFE_REQUEST = /[?#]|:\/\//;
+const SECRET_PARAM = /(?:^|[/&])(?:token|cookie|password|authorization|secret|signature|sig|session)=/i;
+const MAX_LOCATOR = 400;
+const MAX_PURPOSE = 200;
+const MAX_REQUEST = 200;
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+const isOneLine = (value) => !/[\r\n]/.test(value);
+/** The folder that holds one case's notes; `<case-id>` may contain its group folder (`documents/landing-page`). */
+export function exploreNotesDir(caseId) {
+    if (!isValidCaseId(caseId))
+        throw new Error(`"${caseId}" is not a valid case id`);
+    return path.join(EXPLORE_DIR, 'notes', ...caseId.split('/'));
+}
+/** The note of one profile: `.explore/notes/<case-id>/<profile-id>.json`. */
+export function exploreNotesFile(caseId, profileId) {
+    if (!PROFILE_FILE.test(profileId))
+        throw new Error(`"${profileId}" is not a valid profile id`);
+    return path.join(exploreNotesDir(caseId), `${profileId}.json`);
+}
+/** sha256 of the case document, or null when it does not exist. */
+export function caseSha256(caseId) {
+    if (!isValidCaseId(caseId))
+        return null;
+    try {
+        return crypto.createHash('sha256').update(fs.readFileSync(path.join(CASES_DIR, `${caseId}.md`))).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Whether a note still describes the case. A stale note is not an error: `/gen-spec` replays the case and ignores it.
+ */
+export function noteFreshness(note) {
+    const current = caseSha256(note.caseId);
+    if (current === null)
+        return { state: 'no-case', reason: 'the case file does not exist' };
+    if (current !== note.caseSha256)
+        return { state: 'stale', reason: 'the case file changed after the note was written' };
+    return { state: 'fresh' };
+}
+function checkLocator(value, where, problems) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        problems.push(`${where} must be a locator string`);
+        return;
+    }
+    if (!isOneLine(value))
+        problems.push(`${where} must be one line`);
+    if (value.length > MAX_LOCATOR)
+        problems.push(`${where} is longer than ${MAX_LOCATOR} characters`);
+    if (!value.startsWith('page.'))
+        problems.push(`${where} must start with "page." (use browser_generate_locator)`);
+    if (value.includes('=>'))
+        problems.push(`${where} must be a locator, not code`);
+}
+function checkRequest(value, where, problems) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        problems.push(`${where} must be a request path`);
+        return;
+    }
+    if (!isOneLine(value))
+        problems.push(`${where} must be one line`);
+    if (value.length > MAX_REQUEST)
+        problems.push(`${where} is longer than ${MAX_REQUEST} characters`);
+    if (!value.startsWith('/') || value.startsWith('//'))
+        problems.push(`${where} must start with "/" (a path, not a URL)`);
+    if (UNSAFE_REQUEST.test(value))
+        problems.push(`${where} must have no host, query string or fragment`);
+    if (SECRET_PARAM.test(value))
+        problems.push(`${where} must not carry a token, cookie or session`);
+}
+function checkPurpose(value, where, problems) {
+    if (typeof value !== 'string' || value.trim() === '')
+        problems.push(`${where} must be a short description`);
+    else if (!isOneLine(value))
+        problems.push(`${where} must be one line`);
+    else if (value.length > MAX_PURPOSE)
+        problems.push(`${where} is longer than ${MAX_PURPOSE} characters`);
+}
+function checkSteps(value, problems) {
+    if (!isRecord(value)) {
+        problems.push('steps must be an object keyed by step number');
+        return;
+    }
+    for (const [step, body] of Object.entries(value)) {
+        const where = `steps["${step}"]`;
+        if (!STEP_KEY.test(step))
+            problems.push(`${where}: the key must be a positive step number`);
+        if (!isRecord(body)) {
+            problems.push(`${where} must be an object`);
+            continue;
+        }
+        if (body.url !== undefined) {
+            const url = body.url;
+            if (typeof url !== 'string' || !url.startsWith('/'))
+                problems.push(`${where}.url must start with "/"`);
+            else if (UNSAFE_REQUEST.test(url))
+                problems.push(`${where}.url must have no host, query string or fragment`);
+        }
+        if (body.locators !== undefined) {
+            if (!Array.isArray(body.locators))
+                problems.push(`${where}.locators must be a list`);
+            else {
+                for (const [index, locator] of body.locators.entries()) {
+                    const item = `${where}.locators[${index}]`;
+                    if (!isRecord(locator)) {
+                        problems.push(`${item} must be an object with "purpose" and "locator"`);
+                        continue;
+                    }
+                    checkPurpose(locator.purpose, `${item}.purpose`, problems);
+                    checkLocator(locator.locator, `${item}.locator`, problems);
+                }
+            }
+        }
+        if (body.requests !== undefined) {
+            if (!Array.isArray(body.requests))
+                problems.push(`${where}.requests must be a list`);
+            else
+                body.requests.forEach((request, index) => checkRequest(request, `${where}.requests[${index}]`, problems));
+        }
+        const known = new Set(['url', 'locators', 'requests']);
+        for (const key of Object.keys(body))
+            if (!known.has(key))
+                problems.push(`${where}.${key} is not a known field`);
+    }
+}
+function checkTargets(value, problems) {
+    if (!isRecord(value)) {
+        problems.push('targets must be an object keyed by target id');
+        return;
+    }
+    for (const [id, target] of Object.entries(value)) {
+        const where = `targets["${id}"]`;
+        if (!TARGET_KEY.test(id))
+            problems.push(`${where}: the key must be a target id such as "T1"`);
+        if (!isRecord(target)) {
+            problems.push(`${where} must be an object`);
+            continue;
+        }
+        checkLocator(target.locator, `${where}.locator`, problems);
+        if (target.matches !== undefined && (!Number.isInteger(target.matches) || target.matches < 1)) {
+            problems.push(`${where}.matches must be a positive whole number`);
+        }
+        const known = new Set(['locator', 'matches']);
+        for (const key of Object.keys(target))
+            if (!known.has(key))
+                problems.push(`${where}.${key} is not a known field`);
+    }
+}
+/** Every reason the note is not usable, in plain words. An empty list means it is valid. */
+export function validateExploreNote(value, expected) {
+    const problems = [];
+    if (!isRecord(value))
+        return ['the note is not a JSON object'];
+    if (value.version !== NOTES_VERSION)
+        problems.push(`version must be ${NOTES_VERSION}`);
+    if (value.caseId !== expected.caseId)
+        problems.push(`caseId must be "${expected.caseId}"`);
+    if (value.profile !== expected.profile)
+        problems.push(`profile must be "${expected.profile}"`);
+    if (typeof value.profile !== 'string' || !PROFILE_FILE.test(value.profile)) {
+        problems.push('profile must be a profile id (letters, digits, ".", "_" and "-")');
+    }
+    if (typeof value.caseSha256 !== 'string' || !HASH.test(value.caseSha256)) {
+        problems.push('caseSha256 must be the sha256 of the case file (run "explore:notes <case-id> --hash")');
+    }
+    if (typeof value.capturedAt !== 'string' || value.capturedAt.trim() === '') {
+        problems.push('capturedAt must be an ISO date-time');
+    }
+    if (value.updatedAt !== undefined && typeof value.updatedAt !== 'string')
+        problems.push('updatedAt must be a string');
+    if (value.env !== undefined && (typeof value.env !== 'string' || value.env.trim() === '')) {
+        problems.push('env must be a non-empty string when it is present');
+    }
+    checkSteps(value.steps, problems);
+    if (value.targets !== undefined)
+        checkTargets(value.targets, problems);
+    const known = new Set(['version', 'caseId', 'profile', 'env', 'caseSha256', 'capturedAt', 'updatedAt', 'steps', 'targets']);
+    for (const key of Object.keys(value))
+        if (!known.has(key))
+            problems.push(`${key} is not a known field`);
+    return problems;
+}
+/**
+ * Reads every note of a case (or one profile's), parses and validates it. A malformed file is reported, never thrown:
+ * the caller decides whether it matters, and generation treats an unreadable note as a missing one.
+ */
+export function readExploreNotes(caseId, profileId) {
+    const errors = [];
+    const notes = [];
+    if (!isValidCaseId(caseId))
+        return { notes, errors: [{ file: caseId, problems: ['not a valid case id'] }] };
+    let files;
+    try {
+        files = fs.readdirSync(exploreNotesDir(caseId)).filter((file) => file.endsWith('.json'));
+    }
+    catch {
+        return { notes, errors };
+    }
+    for (const file of files.sort()) {
+        const profile = path.basename(file, '.json');
+        if (profileId !== undefined && profile !== profileId)
+            continue;
+        const full = path.join(exploreNotesDir(caseId), file);
+        let parsed;
+        try {
+            parsed = JSON.parse(fs.readFileSync(full, 'utf8'));
+        }
+        catch (error) {
+            errors.push({ file: full, problems: [`not valid JSON: ${error.message}`] });
+            continue;
+        }
+        const problems = validateExploreNote(parsed, { caseId, profile });
+        if (problems.length > 0)
+            errors.push({ file: full, problems });
+        else
+            notes.push(parsed);
+    }
+    return { notes, errors };
+}

package/dist/lib/paths.d.ts

@@ -25,6 +25,8 @@ export declare const CASES_DIR: string;
 export declare const TESTS_DIR: string;
 export declare const REPORTS_DIR: string;
 export declare const TMP_DIR: string;
+/** Local agent output (reference screenshots, exploration notes), git-ignored and safe to delete. */
+export declare const EXPLORE_DIR: string;
 export declare const TEMPLATES_DIR: string;
 export declare const SKILLS_DIR: string;
 /**

package/dist/lib/paths.js

@@ -82,6 +82,8 @@ export const CASES_DIR = path.join(ROOT, 'cases');
 export const TESTS_DIR = path.join(ROOT, 'tests');
 export const REPORTS_DIR = path.join(ROOT, 'reports');
 export const TMP_DIR = path.join(ROOT, '.tmp');
+/** Local agent output (reference screenshots, exploration notes), git-ignored and safe to delete. */
+export const EXPLORE_DIR = path.join(ROOT, '.explore');
 export const TEMPLATES_DIR = path.join(FRAMEWORK_ROOT, 'templates');
 export const SKILLS_DIR = path.join(FRAMEWORK_ROOT, '.claude', 'skills');
 /**

package/dist/scripts/cli.js

@@ -32,13 +32,19 @@ async function main() {
         process.exitCode = await migrate(rest);
         return;
     }
+    if (command === 'explore:notes') {
+        // The script reads `process.argv` itself; drop the subcommand so it sees only its own arguments.
+        process.argv.splice(2, 1);
+        await import('./explore-notes.js');
+        return;
+    }
     if (command === 'help' || command === '--help-init') {
         console.log(USAGE);
         return;
     }
     await import('./run.js');
 }
-const USAGE = `Usage: pnpm asrun [init|doctor|reset|upgrade|migrate] [options]
+const USAGE = `Usage: pnpm asrun [init|doctor|reset|upgrade|migrate|explore:notes] [options]
 
   (no subcommand)  Run the tests of one environment. See "pnpm asrun --help".
   init             Create the files a workspace needs (never overwrites; --update refreshes generated files,
@@ -50,5 +56,6 @@ const USAGE = `Usage: pnpm asrun [init|doctor|reset|upgrade|migrate] [options]
   upgrade          Install the newest asrun, refresh the workspace files and apply its migrations, after checking the
                    target release for breaking changes (see "pnpm asrun upgrade --help").
   migrate          Apply the workspace migrations of the installed release, or list them (see "pnpm asrun migrate
-                   --help"). "upgrade" runs it; use it after a manual install.`;
+                   --help"). "upgrade" runs it; use it after a manual install.
+  explore:notes    Print or validate the local exploration note of a case (see "pnpm asrun explore:notes --help").`;
 await main();

package/dist/scripts/explore-notes.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/explore-notes.js

@@ -0,0 +1,131 @@
+import path from 'node:path';
+import { isValidCaseId } from '../lib/case-id.js';
+import { caseSha256, exploreNotesDir, exploreNotesFile, noteFreshness, readExploreNotes, } from '../lib/explore-notes.js';
+import { ROOT } from '../lib/paths.js';
+import { loadProfiles } from '../lib/profiles.js';
+const USAGE = `Usage: pnpm explore:notes <case-id> [--profile <profile-id>] [--json] [--check] [--hash]
+
+Prints the exploration notes /explore-case wrote for a case under .explore/notes/<case-id>/.
+They are local, git-ignored and optional: /gen-spec reads a fresh one to verify instead of rediscovering the page,
+and falls back to a full replay when it is missing or stale.
+
+  --profile <id>  only this profile's note
+  --json          the parsed notes (and any errors) as JSON, for a run that reads them
+  --check         validate every note; fails on a malformed file, warns on a stale one
+  --hash          print the case file's sha256, for "caseSha256" in a note
+
+Paths are relative to the workspace root (${ROOT}).`;
+const args = process.argv.slice(2);
+let caseId;
+let profile;
+let json = false;
+let check = false;
+let hash = false;
+let help = false;
+for (let index = 0; index < args.length; index++) {
+    const arg = args[index];
+    if (arg === '--help' || arg === '-h')
+        help = true;
+    else if (arg === '--json')
+        json = true;
+    else if (arg === '--check')
+        check = true;
+    else if (arg === '--hash')
+        hash = true;
+    else if (arg === '--profile') {
+        const value = args[++index];
+        if (value === undefined || value.startsWith('--')) {
+            console.error(`--profile needs a profile id.\n\n${USAGE}`);
+            process.exit(2);
+        }
+        profile = value;
+    }
+    else if (!arg.startsWith('--') && caseId === undefined)
+        caseId = arg;
+    else {
+        console.error(`Unexpected argument: ${arg}\n\n${USAGE}`);
+        process.exit(2);
+    }
+}
+if (help) {
+    console.log(USAGE);
+    process.exit(0);
+}
+if (caseId === undefined) {
+    console.error(USAGE);
+    process.exit(1);
+}
+if (!isValidCaseId(caseId)) {
+    console.error(`"${caseId}" is not a valid case id (one optional group folder, for example documents/landing-page).`);
+    process.exit(1);
+}
+if (hash) {
+    const value = caseSha256(caseId);
+    if (value === null) {
+        console.error(`cases/${caseId}.md does not exist.`);
+        process.exit(1);
+    }
+    console.log(value);
+    process.exit(0);
+}
+const { notes, errors } = readExploreNotes(caseId, profile);
+const relative = (file) => path.relative(ROOT, file).split(path.sep).join('/');
+if (json) {
+    console.log(JSON.stringify({
+        caseId,
+        notes: notes.map((note) => ({ ...note, freshness: noteFreshness(note) })),
+        errors: errors.map((error) => ({ file: relative(error.file), problems: error.problems })),
+    }, null, 2));
+}
+else {
+    console.log(`Exploration notes for cases/${caseId}.md (${relative(exploreNotesDir(caseId))})`);
+    if (notes.length === 0)
+        console.log('  none yet: /gen-spec replays the case.');
+    for (const note of notes) {
+        console.log(`  ${note.profile.padEnd(24)} ${describe(note)}`);
+    }
+}
+let failed = false;
+for (const error of errors) {
+    failed = true;
+    for (const problem of error.problems)
+        console.log(`FAIL ${relative(error.file)}: ${problem}`);
+}
+if (check) {
+    const value = caseSha256(caseId);
+    if (value === null) {
+        failed = true;
+        console.log(`FAIL cases/${caseId}.md does not exist`);
+    }
+    const known = new Set(knownProfiles());
+    for (const note of notes) {
+        const freshness = noteFreshness(note);
+        if (freshness.state !== 'fresh') {
+            console.log(`WARN ${relative(exploreNotesFile(caseId, note.profile))}: ${freshness.reason}; current caseSha256 is ${value ?? '(unknown)'}`);
+        }
+        if (!known.has(note.profile)) {
+            console.log(`WARN ${relative(exploreNotesFile(caseId, note.profile))}: "${note.profile}" is not in profiles.yaml`);
+        }
+    }
+    if (failed) {
+        console.error('\nA note that fails here is ignored by /gen-spec. Fix it, or delete it and let the case be replayed.');
+        process.exit(1);
+    }
+}
+function describe(note) {
+    const freshness = noteFreshness(note);
+    const steps = Object.keys(note.steps)
+        .sort((a, b) => Number(a) - Number(b))
+        .join(',');
+    const targets = Object.keys(note.targets ?? {}).sort().join(',');
+    const state = freshness.state === 'fresh' ? 'fresh' : `stale (${freshness.reason})`;
+    return `${state}  steps ${steps || '-'}  targets ${targets || '-'}  captured ${note.capturedAt}${note.updatedAt ? `  refreshed ${note.updatedAt}` : ''}`;
+}
+function knownProfiles() {
+    try {
+        return loadProfiles().map((entry) => entry.id);
+    }
+    catch {
+        return [];
+    }
+}

package/docs/agents/case-format.md

@@ -223,5 +223,6 @@ In the framework package:
 - `.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/exploring-cases/references/notes.md` — the local exploration note `/gen-spec` reads (not part of the case).
 - `.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.

package/docs/agents/framework-dev.md

@@ -53,6 +53,10 @@ is relevant to a project that uses asrun as a dependency.
 - Everything the framework reads for a project goes through `ROOT` in `lib/paths.ts` (the workspace root); its own
   assets (templates, docs, skills, its `node_modules`) go through `FRAMEWORK_ROOT`. Never write into
   `FRAMEWORK_ROOT` at run time.
+- `.explore/` is local state (git-ignored): target reference screenshots and the exploration notes that
+  `lib/explore-notes.ts` reads (`.explore/notes/<case-id>/<profile-id>.json`). Nothing there is committed, and a
+  workspace without it generates specs by replaying the case. `scripts/explore-notes.ts` (`pnpm explore:notes`) prints
+  and validates those notes.
 - After changing `lib/`, run `pnpm build` before exercising the demo's specs.
 - `pnpm build` copies `scripts/*.mjs` into `dist/scripts/`, where they sit one folder deeper than in this repository.
   `pnpm verify:pack` (part of CI) checks that layout on a packed tarball; the checkout alone hides such bugs, because

package/docs/ai-workflow.md

@@ -83,7 +83,10 @@ publishes, shares or deletes anything, in staging or in production. It:
 - turns what it cannot know into `🚫 TODO [blocking]` / `❓ TODO [non-blocking]` questions, each under a sentence that
   is its suggestion and can stand in the case as it is, with a last line `- ✍️ Answer:`;
 - lists the candidates instead of guessing a target (`## Targets`);
-- edits the case file only (plus reference screenshots under `.explore/targets/`).
+- edits the case file and the `.explore/` files (reference screenshots and the note below), and nothing else;
+- writes a local **exploration note** (`.explore/notes/<case-id>/<profile-id>.json`, git-ignored) with the locators and
+  data-call paths it saw. `/gen-spec` reads it to verify instead of rediscovering, and a page that only exists after a
+  write step is written from it. Delete it at any time: without it, generation replays the case.
 
 With many profiles, `--profiles a,b` opens only those (ids from `profiles.yaml`, comma-separated). The others are not
 opened and nothing is written about them, so a case can be explored in passes: A and B first, C later. Runs add up; the
@@ -138,6 +141,11 @@ subset adds up: explore A and B first and C later, and `/gen-spec` covers all th
 about runs on `default` alone, and the report names it. A profile that is not logged in is not dropped: its part is
 written from the case and marked `not verified on the page`.
 
+It reads each profile's **exploration note** first: a fresh note supplies the locators and request patterns, which it
+confirms on the page instead of rediscovering; a missing or stale note means a full replay. A page that only exists
+after a write step is written from a fresh note. `pnpm explore:notes <case-id> [--profile <id>]` shows what was
+recorded, and `--check` validates it.
+
 It does **not** run the spec and does **not** create screenshot baselines: running is a separate step (6).
 
 - A case must be in the project's artifact language. If it is in another language, `/gen-spec` translates the case

package/docs/cases.md

@@ -207,7 +207,7 @@ that cannot be answered in place.
 
 ## Rename or move a case
 
-Use the Cases page (click the file name or the pencil icon). The spec and the baseline images move with it and the
-spec is rewritten to match. By hand, move the three things together (`cases/...md`, `tests/...spec.ts`, its
-`*-snapshots/`), and keep the spec's `// case:` line and its imports unchanged: specs import the framework by package
-name, so their folder depth does not change the imports.
+Use the Cases page (open the case, then **Rename or move** in the **⋯** menu at the end of the tab strip). The spec
+and the baseline images move with it and the spec is rewritten to match. By hand, move the three things together
+(`cases/...md`, `tests/...spec.ts`, its `*-snapshots/`), and keep the spec's `// case:` line and its imports
+unchanged: specs import the framework by package name, so their folder depth does not change the imports.

package/docs/commands.md

@@ -18,6 +18,7 @@ thin wrappers, so `pnpm asrun`, `pnpm signin` and the rest work as below. The sa
 | Run tests | `pnpm asrun --env <env> [filters]` |
 | Open the last report | `pnpm report` |
 | Look around a page as a profile | `pnpm explore <profile-id> [path]` |
+| See or validate what an exploration recorded for a case | `pnpm explore:notes <case-id> [--profile <id>] [--json] [--check]` |
 | Read what the last report says about a case | `pnpm heal:evidence --case <case-id> --env <env>` |
 | List or forget test data that could not be removed | `pnpm cleanup --env <env> [--forget]` |
 | Create or validate a case | `pnpm case:new <id>`, `pnpm case:check [case-id]` |
@@ -141,6 +142,9 @@ pnpm pdf:render report.pdf --out .explore/targets/header-logo --corner top-left
 
 ```bash
 pnpm explore example-staging /app/home
+pnpm explore:notes conduit/header-navigation
+pnpm explore:notes conduit/header-navigation --profile example-staging --json
+pnpm explore:notes conduit/header-navigation --check
 pnpm heal:evidence --case header-logo --env staging
 ```
 
@@ -149,6 +153,13 @@ are saved to `~/Downloads` and never overwrite an existing file. `heal:evidence`
 step, error, call log and screenshots for a case, and whether the report is stale; it is what `/heal-spec` reads
 first.
 
+`explore:notes` reads the **exploration note** that `/explore-case` writes for a case under
+`.explore/notes/<case-id>/<profile-id>.json`. It prints one line per profile (fresh or stale, the steps and targets it
+covers) and `--json` prints the parsed notes for a run that reads them. A note is local, git-ignored and optional:
+`/gen-spec` uses a fresh one to verify the locators and request patterns instead of rediscovering them, and replays the
+case when it is missing or stale. `--check` fails on a malformed note and warns about a stale one (it prints the current
+`caseSha256`); `--hash` prints that hash. Deleting `.explore/notes/` is always safe.
+
 ## Cleanup
 
 ```bash

package/docs/theme-guide.html

@@ -330,6 +330,7 @@
     <a href="#icons">Icons</a>
     <a href="#tooltips">Tooltips</a>
     <a href="#editor">Markdown editor</a>
+    <a href="#document-tabs">Document tabs</a>
     <a href="#surfaces">Surfaces</a>
     <a href="#sections">Sidebar sections</a>
     <a href="#checklist">Checklist</a>
@@ -959,6 +960,61 @@ import {FilterChips} from '../components/filter-chips';
       <li><b>Every expand/collapse animates.</b> Use <code>Collapse</code> from <code>components/collapse.tsx</code> (height and fade, 200ms, <code>ease-out</code>) for content that appears and disappears, and rotate the chevron with <code>transition-transform duration-200</code> instead of swapping two icons. Always add <code>motion-reduce:transition-none</code>. Turn transitions off while the user drags a resize handle.</li>
     </ul>
 
+    <h2 id="document-tabs">Document tabs</h2>
+    <p class="muted">
+      A page that holds more than one file of the same thing puts them in a tab strip: <code>DocumentTabs</code> in
+      <code>pages/cases.tsx</code>, where <b>Case</b> is the source a person writes and <b>Spec</b> what a run
+      generated from it. The strip is the only place the file names appear. The bar under it carries the tools of the
+      file on screen (<code>WorkbenchControls</code>, the layout and pane switches), never a second copy of the name,
+      and <b>Save</b> / <b>Discard</b> always sit at the same end of the strip and act on the file on screen.
+    </p>
+    <div class="demo" style="align-items:flex-end;gap:16px;padding:12px 16px 0;background:var(--warm);border-bottom:1px solid var(--line-mid)">
+      <span style="display:flex;align-items:center;gap:8px;margin-bottom:-1px;padding:6px 12px;border-bottom:2px solid var(--theme-btn);border-radius:6px 6px 0 0;background:var(--card);font-size:14px">
+        <span style="font-size:12px;font-weight:500;letter-spacing:.05em;color:var(--theme-ink)">Case</span>
+        <span class="mono">favorite-article.md</span>
+        <span title="Unsaved changes" style="width:6px;height:6px;border-radius:9999px;background:var(--gold-deep)"></span>
+      </span>
+      <span style="display:flex;align-items:center;gap:8px;padding:6px 12px;border-bottom:2px solid transparent;border-radius:6px 6px 0 0;font-size:14px;color:var(--ink-2)">
+        <span style="font-size:12px;font-weight:500;letter-spacing:.05em;color:var(--ink-3)">Spec</span>
+        <span class="mono">favorite-article.spec.ts</span>
+      </span>
+      <span style="display:flex;align-items:center;gap:8px;margin-left:auto;padding-bottom:8px">
+        <span class="btn btn-secondary">Discard</span>
+        <span class="btn btn-primary">Save</span>
+        <span class="btn btn-secondary">...</span>
+      </span>
+    </div>
+    <div class="demo" style="gap:16px;background:var(--card);border-bottom:1px solid var(--line-mid);padding:8px 16px">
+      <span style="display:flex;align-items:center;gap:6px">
+        <span style="font-size:12px;color:var(--ink-3)">Layout</span>
+        <span style="display:flex;overflow:hidden;border-radius:4px;box-shadow:0 0 0 1px var(--line-mid)">
+          <span style="padding:4px 10px;font-size:14px;background:var(--card);color:var(--ink-2)">Split</span>
+          <span style="padding:4px 10px;font-size:14px;background:var(--theme-btn);color:#fff">Single</span>
+        </span>
+      </span>
+      <span style="display:flex;align-items:center;gap:6px">
+        <span style="font-size:12px;color:var(--ink-3)">Pane</span>
+        <span style="display:flex;overflow:hidden;border-radius:4px;box-shadow:0 0 0 1px var(--line-mid)">
+          <span style="padding:4px 10px;font-size:14px;background:var(--theme-btn);color:#fff">Panel</span>
+          <span style="padding:4px 10px;font-size:14px;background:var(--card);color:var(--ink-2)">Editor</span>
+          <span style="padding:4px 10px;font-size:14px;background:var(--card);color:var(--ink-2)">Doc</span>
+        </span>
+      </span>
+    </div>
+    <ul class="tight">
+      <li>The active tab is <code>bg-card</code> with a <code>border-b-2 border-theme-btn</code> underline; the others are
+        <code>text-ink-2</code> on the warm strip. The name is <code>font-mono</code>; the kind in front of it is
+        <code>text-xs tracking-wider</code>, <code>text-theme-ink</code> when active and <code>text-ink-3</code> otherwise.</li>
+      <li>Unsaved changes are a 6px <code>bg-gold-deep</code> dot on the tab, never a badge in the page header. A file
+        that does not exist yet keeps its tab, disabled at 45% opacity, with a tooltip that says how to create it.</li>
+      <li>The switches of the bar under the tabs are a segmented control, not buttons: active <code>bg-theme-btn</code>
+        with white text, the others <code>bg-card</code>, the whole group ringed with <code>ring-1 ring-line-mid</code>, and
+        a <code>text-xs text-ink-3</code> label in front (<code>Layout</code>, <code>Pane</code>). A switch group without a
+        label is not discoverable; never ship one.</li>
+      <li>Switching tabs keeps the other tab's draft, so <b>Save</b> and <b>Discard</b> take the active file; the tab
+        dot is what says another file still has unsaved changes.</li>
+    </ul>
+
     <h2 id="sections">Sidebar sections and selection</h2>
     <div class="row" style="align-items:flex-start">
       <div class="side">

package/docs/web-ui.md

@@ -55,9 +55,26 @@ One row per profile, with the same login check as `pnpm status`.
 
 ## Cases
 
-The case list is grouped by folder and collapses. The editor opens in **Single** with the **Panel** full width; the
-toolbar switches to **Split** (source left, one pane right; drag the divider to resize, double-click to reset) or, in
-Single, between **Panel**, **Editor** and **Doc**.
+The case list is grouped by folder and collapses. A case opens on the **Case** tab, with the **Spec** tab beside it:
+
+- **Case** (`favorite-article.md`) is the source a person writes: the steps, values, rules and questions.
+- **Spec** (`favorite-article.spec.ts`) is what a generate or heal run wrote from it. It stays visible but disabled
+  until the case has a spec, and its tooltip says how to make one.
+
+The tab is the page's state: it lives in the URL (`?view=spec`), so a reload, a shared link and the Back button land on
+the same file, and every other link opens the case. Each tab keeps its own unsaved draft while you switch between them;
+an amber dot on a tab means that file has unsaved changes, and **Save** (`Ctrl/Cmd+S`) and **Discard** always sit at the
+right of the tab strip and act on the file on screen.
+
+Under the tabs, the first row is the AI toolbar (command, environment, profiles, attended, **Run AI**, copy the shell
+command, AI guide). It is the same on both tabs, because every AI command acts on the case. The row below holds the
+tools of the file on screen: on **Case** the **Layout** (Split / Single) and **Pane** (Panel / Editor / Doc) switches
+and the previous / next of an outstanding mark; on **Spec** the line that says the file is generated from the case
+(with a link back to it), **Open in editor**, **Copy path** and copy the spec. **Rename or move** and **Delete** live
+in the **⋯** menu at the end of the tab strip.
+
+The editor opens in **Single** with the **Panel** full width; **Split** puts the source on the left and one pane on the
+right (drag the divider to resize, double-click to reset).
 
 - **Source and preview** scroll together, the preview block at the caret is shaded, and a click in the preview puts
   the caret on that line. `Ctrl/Cmd+S` saves.
@@ -84,15 +101,19 @@ Single, between **Panel**, **Editor** and **Doc**.
   when it saved one, the **screenshot** from the exploration, so you look at the image instead of opening the page
   again. Rows that change an assertion are highlighted; **Confirm** settles one line and **Confirm all** settles the
   list in one undo step. None of this blocks generating a spec; healing stops until the case is settled.
-- **Spec view** is editable too (`Ctrl/Cmd+S`; refused when the file changed on disk meanwhile). **Open in editor**
-  opens it in the default application for `.spec.ts`, **Copy path** copies its absolute path.
-- Click the file name (or the pencil icon) to **rename** or move the case: the spec and the baselines move with it and
-  the spec is rewritten. **Delete** (type the id, or fill it in with the feather icon) removes the case, its spec and
-  its baselines; both dialogs list exactly what they touch, and are refused while an AI or test run is in progress.
-- **Toolbar:** command (explore / generate / heal, explore by default), **Environment** (required, no default),
+- **Spec view** is editable too (`Ctrl/Cmd+S`; refused when the file changed on disk meanwhile), and its tab links back
+  to the case it was generated from. **Open in editor** opens it in the default application for `.spec.ts`, **Copy
+  path** copies its absolute path.
+- **Rename or move** (in the **⋯** menu) keeps the spec and the baselines with the case and rewrites the spec;
+  **Delete** (type the id, or fill it in with the feather icon) removes the case, its spec and its baselines. Both
+  dialogs list exactly what they touch, and are refused while an AI or test run is in progress or while a draft is
+  unsaved.
+- **AI toolbar:** command (explore / generate / heal, explore by default), **Environment** (required, no default),
   **Profiles** (explore only: every profile that is logged in is ticked, the choice is remembered per environment, and
   only the ticked ones are opened), **Attended** (only for explore, ticked by default), **Run AI**, copy the shell
   command, open the AI guide.
+- **Writes in …** is one line under the toolbar, in red: the environments whose data the case writes, then its note,
+  with the full note in its tooltip. A case that only runs in some environments shows that line instead.
 - **From memo** opens a Markdown editor with a preview for raw notes. **Make cases** saves them to `.tmp/memos/` and
   runs `/make-case` one-shot (defaults for gaps, `TODO` for unknown values, no page exploration, existing cases never
   overwritten); **Copy /make-case** copies the memo for the interactive dialogue. When the run ends, **What to do