@asrunjs/asrun 0.13.0 → 0.15.0

package/dist/ui/server/ai-stream.js

@@ -271,11 +271,15 @@ const BROWSER_RUN_CODE = /browser_run_code/;
  * badge on.
  */
 const HANDOFF_CFG_TTL_MS = 300_000;
-/** `message: '...'` of the options call that comes right before the card. */
-function handoffMessage(code) {
-    const match = /message\s*:\s*(['"`])((?:\\.|(?!\1)[^\\])*)\1/.exec(code);
+/** A plain string literal of the options call that comes right before the card (`message: '...'`, `finish: '...'`). */
+function handoffText(code, key) {
+    const match = new RegExp(`(?:^|[^\\w$])${key}\\s*:\\s*(['"\`])((?:\\\\.|(?!\\1)[^\\\\])*)\\1`).exec(code);
     return match ? match[2].replace(/\\(['"`\\])/g, '$1').trim() || null : null;
 }
+/** `message: '...'` of the options call that comes right before the card. */
+const handoffMessage = (code) => handoffText(code, 'message');
+/** `finish: '...'` of the options call that comes right before the card. */
+const handoffFinish = (code) => handoffText(code, 'finish');
 const codeOf = (input) => {
     if (!input || typeof input !== 'object')
         return '';
@@ -306,8 +310,12 @@ export class AiStreamFormatter {
     pending = new Map();
     cardCalls = new Set();
     waitingForUser = null;
-    /** The message of the last options call, kept so a card that runs after unrelated calls still carries it. */
+    /**
+     * The message and finish condition of the last options call, kept so a card that runs after unrelated calls still
+     * carries them.
+     */
     lastHandoffMessage = null;
+    lastHandoffFinish = null;
     lastEventAt = Date.now();
     lastWaitAt = 0;
     /** The last call the agent finished, so a quiet spell can say what it is doing instead of only that nothing came. */
@@ -348,18 +356,29 @@ export class AiStreamFormatter {
                 this.waitingForUser = null;
             else {
                 this.cardCalls.add(id);
-                // `??=` on purpose: the options call before it already knows the message and when the wait started.
-                this.waitingForUser ??= { message: handoffMessage(codeOf(input)) ?? this.lastHandoffMessage, since: Date.now() };
+                // `??=` on purpose: the options call before it already knows the message, the finish condition and the start.
+                this.waitingForUser ??= {
+                    message: handoffMessage(codeOf(input)) ?? this.lastHandoffMessage,
+                    finish: handoffFinish(codeOf(input)) ?? this.lastHandoffFinish,
+                    since: Date.now(),
+                };
             }
             return null;
         }
         if (kind === 'options') {
             const message = handoffMessage(codeOf(input));
+            const finish = handoffFinish(codeOf(input));
             if (message)
                 this.lastHandoffMessage = message;
+            if (finish)
+                this.lastHandoffFinish = finish;
             // Keep the start time when the wait is already set: a second report of the same handoff must not announce it twice.
             const since = this.waitingForUser?.since ?? Date.now();
-            this.waitingForUser = { message: message ?? this.lastHandoffMessage, since };
+            this.waitingForUser = {
+                message: message ?? this.lastHandoffMessage,
+                finish: finish ?? this.lastHandoffFinish,
+                since,
+            };
             return null;
         }
         // Anything else ends the wait, unless it was set too recently to be an abandoned one: the card runs right after it.

package/dist/ui/server/app.js

@@ -15,6 +15,7 @@ import { JobConflictError, jobs } from './jobs.js';
 import { listAiModels } from './ai-models.js';
 import { fileEvents } from './watch-files.js';
 import { refreshUpdate, updateEvents, updateInfo } from './update.js';
+import { upgradePrompt } from '../../lib/upgrade-prompt.js';
 const REPORTS_DIR = path.join(ROOT, 'reports');
 // Built by `prepack` and shipped with the package; the framework repository builds it with `pnpm ui`.
 const WEB_DIST = path.join(FRAMEWORK_ROOT, 'ui', 'dist');
@@ -240,6 +241,9 @@ export function createApp({ port }) {
             void refreshUpdate(true);
         return c.json(info);
     });
+    // What an upgrade leaves open, and the prompt that hands it to an agent. Read-only; the dialog asks for it only when
+    // it opens, because it reads the installed templates and can be long.
+    api.get('/upgrade/prompt', (c) => c.json(upgradePrompt(ROOT)));
     api.get('/reports', (c) => {
         if (!fs.existsSync(REPORTS_DIR))
             return c.json([]);

package/dist/ui/server/jobs.d.ts

@@ -102,6 +102,16 @@ declare class JobManager {
     private verifyLeftoverStopped;
     /** Publishes a change of "waiting for the person" (a handoff card) like any other status change. */
     private syncAwaiting;
+    /**
+     * Shows a desktop notification now. Neither the agent (whose shell the CLI may refuse) nor the page (not open, not
+     * focused, not allowed) can be relied on for this, so the server shows it itself.
+     */
+    private notifyWaiting;
+    /**
+     * Why no notification appeared, written where the person reads next: never a reason to fail the job, and the next
+     * run of the same kind leaves no line at all when the notifier works.
+     */
+    private pushNotificationFailure;
     /**
      * Stops a run whose agent has said nothing for `STALL_MS`: a tool call that never returns leaves the CLI waiting for
      * ever, and the log would only keep repeating "still waiting for ...". The block above the cancel names what to do.

package/dist/ui/server/jobs.js

@@ -5,6 +5,7 @@ import fs from 'node:fs';
 import { StringDecoder } from 'node:string_decoder';
 import { ROOT } from '../../lib/paths.js';
 import { spawnTarget } from '../../lib/command.js';
+import { notifyDesktop } from '../../lib/desktop-notify.js';
 import { AiStreamFormatter } from './ai-stream.js';
 import { parseResultState } from './result-state.js';
 import { appendChunkNow, chunksFile, ensureJobDir, logFile, pruneJobs, readChunks, readJobs, writeRecord, } from './job-store.js';
@@ -244,6 +245,11 @@ class JobManager {
             finished = true;
             this.finish(record, code, signal);
         });
+        // A login waits for a person at the browser window it just opened: say so on the desktop, where they are looking.
+        if (spec.kind === 'signin') {
+            this.notifyWaiting(record, 'AsRun — log in', `Log in to ${[spec.profile, spec.env].filter(Boolean).join(' @ ')}, then press "Done, save the session" on ` +
+                'the card in the browser window.');
+        }
         this.events.emit('job', record.info);
         return record.info;
     }
@@ -476,9 +482,39 @@ class JobManager {
             return;
         if (now && before && before.since === new Date(now.since).toISOString())
             return;
-        info.awaitingUser = now ? { message: now.message, since: new Date(now.since).toISOString() } : null;
+        info.awaitingUser = now
+            ? { message: now.message, finish: now.finish, since: new Date(now.since).toISOString() }
+            : null;
         this.persist(record);
         this.events.emit('job', info);
+        // A handoff that starts right now: the person is told on the desktop, because the browser window is somewhere else
+        // and the page may be closed, focused or not allowed to notify. The dedupe keeps one handoff to one notification.
+        if (!before && now) {
+            this.notifyWaiting(record, 'AsRun — your turn', `${info.caseId ? `${info.caseId}: ` : ''}${now.message ?? 'A step in the browser window waits for you.'}` +
+                (now.finish ? ` Done when ${now.finish}.` : ''));
+        }
+    }
+    /**
+     * Shows a desktop notification now. Neither the agent (whose shell the CLI may refuse) nor the page (not open, not
+     * focused, not allowed) can be relied on for this, so the server shows it itself.
+     */
+    notifyWaiting(record, title, body) {
+        notifyDesktop({ title, body, sound: true }, (reason) => this.pushNotificationFailure(record, reason));
+    }
+    /**
+     * Why no notification appeared, written where the person reads next: never a reason to fail the job, and the next
+     * run of the same kind leaves no line at all when the notifier works.
+     */
+    pushNotificationFailure(record, reason) {
+        const line = `\n[no desktop notification shown: ${reason}. "pnpm asrun notify-test" checks the notifier of this machine]\n`;
+        // The job may have ended while the notifier was still running: its log stream is closed then, so the files get the
+        // line directly (a running job is told through its stream, so the page shows it at once).
+        if (record.info.status === 'running' && record.logStream) {
+            this.pushPart(record, { kind: 'hint', at: Date.now(), data: line });
+        }
+        else {
+            this.pushRecovered(record, line);
+        }
     }
     /**
      * Stops a run whose agent has said nothing for `STALL_MS`: a tool call that never returns leaves the CLI waiting for
@@ -586,6 +622,10 @@ class JobManager {
                         : `[process exited with code ${code}]`);
         if (record.spec.ai && info.status === 'succeeded')
             info.resultState = parseResultState(resultText(record));
+        // The agent stopped with questions in the case file: that waits for a person exactly like a handoff card does.
+        if (info.resultState === 'needs-input') {
+            this.notifyWaiting(record, 'AsRun — answers needed', `${info.caseId ? `${info.caseId}: ` : 'The case: '}the agent wrote open questions into the case file.`);
+        }
         this.push(record, 'system', `\n${summary}\n`);
         record.logStream?.end();
         record.chunkStream?.end();

package/dist/ui/shared/ai-commands.js

@@ -134,8 +134,10 @@ const ATTENDED = 'Attended run: a person is at the machine and the browser windo
     'need a choice to them and wait, as the skill describes. Start every handoff (also a second one in the same run) ' +
     'with its own call that sets __handoffCfg, before the call that runs handoff-card.js, and never change those options ' +
     'inside the call that runs the card: the web UI sees that a person is needed only from that call, so without it ' +
-    'there is no "Your turn" badge and no notification. Nobody can answer questions in the chat, so write open ' +
-    `questions into the case file as the skill describes. ${RESULT_LINE_RULE}`;
+    'there is no "Your turn" badge and no notification. Put one action per string in `steps` (the card numbers them), ' +
+    'keep `message` to one sentence, write the finish condition into `finish` as plain text, and set `doneText` to the ' +
+    'exact text that appears when the step is done so the card ends by itself. Nobody can answer ' +
+    `questions in the chat, so write open questions into the case file as the skill describes. ${RESULT_LINE_RULE}`;
 /** The prompt of a one-shot run. Every command may leave open questions in the case, so every one ends with a RESULT line. */
 export function headlessPrompt(command, caseId, options) {
     const slash = slashCommand(command, caseId, options);

package/dist/ui/shared/types.d.ts

@@ -60,6 +60,8 @@ export interface JobInfo {
 export interface AwaitingUserInfo {
     /** What the person is asked to do, as the agent wrote it on the card; null when unknown. */
     message: string | null;
+    /** The finish condition the card shows in its "DONE WHEN" block; null when the agent gave none. */
+    finish?: string | null;
     since: string;
 }
 /** `needs-input`: the agent wrote open questions into the case file and cannot go on without answers. */
@@ -346,6 +348,12 @@ export interface ReportInfo {
     counts: Record<ResultStatus, number> | null;
 }
 export type { ParsedError, ResultStatus, RunSettings, RunSummary, TestRunResult } from '../../lib/run-summary.js';
+/**
+ * What an upgrade leaves to a person or an AI, and the prompt that hands it over. Built by `lib/upgrade-prompt.ts`,
+ * the same module `pnpm asrun upgrade --prompt --json` prints.
+ */
+export type { ScaffoldDrift, ScaffoldState } from '../../lib/scaffold.js';
+export type { OutstandingFile, OutstandingMigration, UpgradeOutstanding, UpgradePromptPayload } from '../../lib/upgrade-prompt.js';
 export interface InfoResponse {
     root: string;
     envs: string[];

package/docs/agents/case-format.md

@@ -94,7 +94,8 @@ Wrong: `- Create a draft named ... and delete it at the end.` (a write → a tag
 - 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.
-  Hang it under the immediate sentence, never under a broader one above it, and never inside the `## Values` yaml.
+  Hang it under the immediate sentence, never under a broader sentence that merely contains it, and never inside the
+  `## Values` yaml.
   Details: `.claude/skills/exploring-cases/references/open-questions.md`.
 - A marker (`🔍 to be confirmed: <what a person must decide>`) is the alternative to a question, not a companion: it
   says nobody has to decide, only to check. `(seen on <profile>)` is a plain note the run checks by itself. Its
@@ -148,6 +149,8 @@ One card per distinct thing a check looks at:
 - `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 carries one line per profile that was looked at separately: an `--lead` exploration adds its own line for a
+  profile whose element differs, and `none: <reason>` for one that shares the lead's 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
@@ -207,6 +210,10 @@ test.describe('<Case title>', {tag: caseTags('<id>')}, () => {
   by `pnpm asrun rules`) and the stamp is the run's UTC time; 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>')`.
+- `/explore-case --lead` explores one profile in full and the others only where they can differ. What a diff profile
+  adds to the case is its `## Values` entry and its `Reference <profile-id>:` line, never a second copy of the steps;
+  `/gen-spec` writes those profiles' parts from the lead's note and names them `not verified`. A step whose recipe
+  would differ per profile has no per-profile form (`- Recipe:` belongs to the step): split the case, or ask.
 
 ## Checks to run before reporting
 

package/docs/agents/framework-dev.md

@@ -124,16 +124,55 @@ A release can require an *existing* workspace to change; `docs/commands.md` has
 - `version` is the release that introduces the change. `pnpm asrun migrate` runs an entry when
   `migrations.since < version <= installed`, in version order, and moves `since` only after every entry of that
   release has been processed, so a failed run repeats the release instead of skipping its other entries.
+- **Never write a version by hand.** Release Please names the version in its release pull request, after the change is
+  merged, so an author cannot know it (and a guessed version that is too high never runs: `since` moves past it and the
+  workspace is silently skipped for a release). Write `id: 'unreleased-<slug>'` and `version: 'unreleased'`.
+  `resolveMigrations()` turns the sentinel into the installed release's own version — the release that carries the
+  code — so the runtime and the built manifest are always right; `pnpm migrations:freeze` rewrites the sentinel into a
+  real version and id, and `.github/workflows/release-freeze.yml` runs it on the release pull request so the id a
+  workspace sees in `doctor` names a release. That frozen version has no tag yet (the tag comes with the merge), so
+  `migrations:check` accepts the version `package.json` declares as the release being prepared — see below.
 - `auto: true` with an `apply` runs after the install, when `detect` says the workspace is not migrated yet. Keep it
   idempotent: a run that failed repeats the entry.
 - Anything a person has to do is `manual: string[]`. The id is remembered in `.asrun.json` (`migrations.manual`) and
-  `doctor` keeps reminding until `pnpm asrun migrate --ack <id>`.
-- `breaking: true` makes `pnpm asrun upgrade` ask before installing anything. The pre-install check reads
-  `dist/migrations/manifest.json` out of the target tarball, so `pnpm build` has to write it (`scripts/build.ts`
-  serialises `MIGRATIONS` with `toManifest`). `verify:pack` asserts that a packed tarball carries the manifest and that
-  the reader in `lib/tar.ts` finds it.
+  `doctor` keeps reminding until `pnpm asrun migrate --ack <id>`; every output prints that command with the real id.
+- `files: string[]` names the project files the change touches. A once-only scaffold file there (`AGENTS.md`,
+  `.mcp.json`, ...) also has its template baseline advanced when the migration is acknowledged, so one `migrate --ack`
+  clears both the manual step and the file from the upgrade's `NEXT` block.
+- `advisory: true` is for a release that touched a surface but asks nothing of an existing workspace (documentation, a
+  clarified contract, a new optional flag). It makes `pnpm migrations:check` pass without inventing manual steps, and
+  `migrate` reports it and moves on.
+- `breaking: true` makes `pnpm asrun upgrade` ask before installing anything (`Proceed? [y/N]`; `--yes`/`-y` for an
+  unattended run). The pre-install check reads `dist/migrations/manifest.json` out of the target tarball, so
+  `pnpm build` has to write it (`scripts/build.ts` serialises `MIGRATIONS` with `toManifest`) and `verify:pack` asserts
+  the packed manifest carries real versions.
 - Append only: never delete or renumber an entry, because a workspace on an older release may still need it. A change
   that only concerns brand-new workspaces belongs in `templates/`, not in a migration.
+
+**`pnpm migrations:check` is the gate.** It compares the working tree with the newest release tag and fails when a
+change touched a surface that needs an entry (`templates/**` of a once-only file, the case document format, the rule
+ids, the peer dependency range) and no entry names it, or when an entry is malformed (a duplicate id, an id that does
+not start with the version it declares, neither `manual` nor `auto` nor `advisory`). It runs in `verify.yml`, so a
+forgotten entry stops the pull request. `/check-migrations` in Claude Code walks the same steps and writes the entry.
+
+An entry's version must be `unreleased` or a release that already has a tag. The single exception is the version
+`package.json` declares: on the release pull request release-please has bumped it and `release-freeze.yml` has frozen
+the entries to it, while the tag only appears when that pull request is merged. So `migrations:check` reads
+`package.json` as the release being prepared — that version needs no tag and every entry has to stay at or below it,
+which is exactly the "a guess that is too high never runs" rule. `doctor` warns about an entry above the installed
+release for the same reason: `migrate` filters at the installed version and would silently skip it.
+
+A command this repository uses itself lives in **both** `.claude/commands/` and `.opencode/commands/`: Claude Code reads
+only the first, OpenCode only the second (it reloads them without a restart). The two files are identical and neither is
+shipped for a workspace's own commands — those come from `templates/.claude/commands/` through `GENERATED`, which writes
+each one into both folders of the workspace.
+
+**The scaffold baseline** (`lib/scaffold.ts`, `.asrun.json` → `scaffold`) is what tells "the template changed and nobody
+edited the file" (`replace`) from "both changed" (`merge`) and "no baseline yet" (`unknown-base`). `init` records it
+when it writes a once-only file; `init --ack <file>` records it after a merge; nothing else writes it. A release that
+changes a `templates/**` file a workspace owns therefore needs an entry with `files`, or the change reaches the user as
+silent drift that only the baseline comparison reports.
+
 - `scripts/migrate.ts` applies the *installed* package's registry, so it never runs an entry from a release that is not
   installed. `scripts/upgrade.ts` installs first, then runs `init --update`, `migrate` and `doctor` through the newly
   installed bin (`bin/asrun.mjs`), never through the process that started the upgrade.

package/docs/ai-workflow.md

@@ -3,16 +3,19 @@
 Four commands carry a test case from rough notes to a Playwright spec, and repair it when the product changes. They
 work the same in Claude Code and OpenCode: each command is a thin shell that loads a skill from the framework package,
 so the procedure lives in one place and a project can refine it (see
-[Customizing the prompts](#customizing-the-prompts)).
+[Customizing the prompts](#customizing-the-prompts)). A fifth, `/upgrade-workspace`, keeps the workspace itself in step
+with the release it runs; it needs no environment and never touches what a test case means.
 
 | Command | What it does |
 |---|---|
 | `/make-case <notes-or-path>` | Turn raw notes into case documents. Optional step. |
-| `/explore-case <case-id> <env> [--attended] [--profiles a,b] [--hints <file>]` | Open the real pages and write what they show into the case. |
+| `/explore-case <case-id> <env> [--attended] [--profiles a,b] [--lead <profile-id>] [--hints <file>]` | Open the real pages and write what they show into the case. |
 | `/gen-spec <case-id> <env> [--force] [--hints <file>]` | Write `tests/<case-id>.spec.ts` and fill the case's `## Values`. |
 | `/heal-spec <case-id> <env> [--profiles a,b] [--report <run-id>] [--hints <file>]` | Repair a failing spec, or refine a case and its spec on request, from the last report and what you asked for. |
+| `/upgrade-workspace` | Run `pnpm asrun upgrade --prompt` and follow it: merge the scaffold text of a project-owned file, fix case structure, run the checks. It never writes data, runs tests or acknowledges a migration step. |
 
-The environment is **required** by every command except `/make-case`, which does not open pages. There is no default.
+The environment is **required** by every command except `/make-case` and `/upgrade-workspace`, which do not open
+pages. There is no default.
 
 `--profiles` exists on `/explore-case` and `/heal-spec`, not on `/gen-spec`: a spec runs once per profile in the
 environment, so it is generated from every profile the case holds information for, never from a chosen subset.
@@ -88,10 +91,23 @@ publishes, shares or deletes anything, in staging or in production. It:
   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
-case keeps what the earlier runs recorded. In the web UI the profile picker of the toolbar does the same: every profile
-that is logged in in that environment is ticked, and the list you tick is remembered for the next run there.
+With many profiles, `--profiles a,b` opens only those (ids from `profiles.yaml`, comma-separated), each in its own
+session; without the flag the agent opens one logged-in profile per domain. Two different hosts are two domains even
+when they serve the same product, so the list is never collapsed into one profile. The profiles the list leaves out 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 case keeps what the earlier runs recorded. In the web UI the profile picker of the toolbar does the same: every
+profile that is logged in in that environment is ticked, and the list you tick is passed to the run and remembered for
+the next one there.
+
+`--lead <profile-id>` stops paying for the same flow on every profile. The lead profile is explored in full — every
+step, every handoff, the recipe lines, an exploration note with every step — and each other selected profile only
+where it can differ: its own `## Values` entries, its target screenshots and the steps that reach them. A case states
+the same behaviour for every profile, so values and target screenshots are the only place a difference can live. A
+profile whose page structure or flow turns out to differ from the lead's is explored in full instead, and the report
+says so; a differing check that cannot be reached is a blocking question, never "same as the lead". A write step that a
+differing check needs is still a handoff on that profile (test data is usually private to its account), so the person
+still creates it — the saving is the pages and steps around it, not the write. Keep lead and diff profiles in one run:
+the notes are written at its end and share one `caseSha256`, so a split run makes the earlier notes stale.
 
 **To keep what the case says, delete the whole block.** **To answer, write after `Answer:`.** Then run the command
 again. In the web UI the panel calls the first action **Keep what the case says**. The run's **What to do next** bar
@@ -104,9 +120,10 @@ restarted.
 Use it for a case that creates or edits data, or needs a choice (an existing document, items). Stay at the computer:
 the browser window opens and the agent waits while you do those steps.
 
-- The window shows a small draggable card in the bottom-left corner with what to do, **Done** (hand control back) and
-  **Cannot do this**. The agent also continues by itself when the finish condition it named shows up (for example a
-  "Saved" message); the card turns green when control is back. It waits up to 10 minutes per step.
+- The window shows a small draggable card in the bottom-left corner: one sentence about the step, the steps numbered,
+  the texts to copy, and a green **DONE WHEN** block with the finish condition. **Done** hands control back, and
+  **Cannot do this** gives the step up. The agent also continues by itself when the finish condition shows up (for
+  example a "Saved" message); the card turns green when control is back. It waits up to 10 minutes per step.
 - Recording starts and stops by itself. If Playwright's own recording toolbar shows at the top of the page, leave it
   alone: it can stop the recording.
 - The card records what you did, and the agent writes it into the case under the step as **general recipe lines**

package/docs/cases.md

@@ -113,11 +113,11 @@ report and the trace read like the case.
   exploration: positions instead of names of changeable data (`select items #1 to #3`), created names (project prefix
   plus run stamp), control labels but no selectors. Several lines per step are normal. A tagged step with no recipe is
   not generated: `/gen-spec` stops with `needs-input`.
-- **Open questions** go in a `🚫 TODO [blocking]` or `❓ TODO [non-blocking]` block under the sentence they are about,
-  with the agent's suggestion written above and a last line `- ✍️ Answer:`. Accepting a question means deleting the
-  whole block; answering means writing after `Answer:`. In the web panel the two actions are **Keep what the case
-  says** and **Write your answer**. Hang the block under the sentence that makes the claim, not under a broader one
-  above it, and one claim gets one block.
+- **Open questions** go in a `🚫 TODO [blocking]` or `❓ TODO [non-blocking]` block under the sentence they are about:
+  that sentence is the agent's suggestion, and the block's last line is `- ✍️ Answer:`. Accepting a question means
+  deleting the whole block; answering means writing after `Answer:`. In the web panel the two actions are **Keep what
+  the case says** and **Write your answer**. Hang the block under the sentence that makes the claim, not under a
+  broader sentence that merely contains it, and one claim gets one block.
 - **What the AI saw** is marked by what happens if it is wrong: `(seen on <profile>)` is a plain note the run checks by
   itself, and `(observed on <profile>, 🔍 to be confirmed: <what a person must decide>)` is a line that would pass even
   if it were wrong, so a person settles it. A marker may name a screenshot (`evidence: .explore/.../x.png`) so nobody

package/docs/commands.md

@@ -8,7 +8,8 @@ thin wrappers, so `pnpm asrun`, `pnpm signin` and the rest work as below. The sa
 | I want to... | Command |
 |---|---|
 | Install the framework in a project | `pnpm dlx @asrunjs/asrun init --install` |
-| Upgrade the framework and migrate the workspace | `pnpm asrun upgrade [--version <v>] [--dry-run]` |
+| Upgrade the framework and migrate the workspace | `pnpm asrun upgrade [--version <v>] [--dry-run] [--yes]` |
+| Let an AI finish what an upgrade left to the project | `pnpm asrun upgrade --prompt`, or `/upgrade-workspace` |
 | Prepare or check the workspace | `pnpm asrun init [--update]`, `pnpm asrun doctor` |
 | See the effective rules and project settings | `pnpm asrun rules [--json] [--case <case-id>]` |
 | See or apply the workspace migrations after a manual install | `pnpm asrun migrate [--list] [--dry-run]` |
@@ -16,6 +17,7 @@ thin wrappers, so `pnpm asrun`, `pnpm signin` and the rest work as below. The sa
 | Start the web UI | `pnpm go`, `pnpm ui`, `pnpm ui:dev` |
 | See which profiles are logged in | `pnpm status [--env <env>]` |
 | Log in a profile (a person, with 2FA) | `pnpm signin <profile-id>` |
+| Check that desktop notifications reach you | `pnpm asrun notify-test` |
 | 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]` |
@@ -116,6 +118,23 @@ pnpm signin example-staging
 The login is done by a person, including 2FA; the session is saved to `.auth/<profile-id>.json` and verified. See
 [profiles.md](./profiles.md).
 
+## Notifications
+
+```bash
+pnpm asrun notify-test
+```
+
+The UI server shows a **desktop notification** when a run waits for you: an AI run handed a step to the browser window,
+a login opened its window, or a run ended with open questions in the case file. It is the server's own call
+(`osascript` on macOS, `notify-send` on Linux, a PowerShell toast on Windows), so it arrives whether or not the UI page
+is open, focused or allowed to notify. The browser's bell is separate: it is for "a run ended", while the tab is in the
+background (see [web-ui.md](./web-ui.md)).
+
+`notify-test` shows one through the same code and prints the command it ran. Exit code 0 with nothing on screen means
+the operating system dropped the notification, not that asrun failed: allow the app that runs the command (Terminal,
+iTerm2, ...) in its notifications settings. The job log says `[no desktop notification shown: ...]` when the command
+itself failed.
+
 ## Cases and checks
 
 ```bash
@@ -155,10 +174,12 @@ step, error, call log and screenshots for a case, and whether the report is stal
 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:
+`.explore/notes/<case-id>/<profile-id>.json`. It prints one line per profile (fresh or stale, `full` or `diff` with the
+lead profile it leans on, and 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
+case when it is missing or stale. `--check` fails on a malformed note and warns about a stale one or a `diff` note whose
+lead has no note (it prints the current
 `caseSha256`); `--hash` prints that hash. Deleting `.explore/notes/` is always safe.
 
 ## Rules
@@ -224,15 +245,47 @@ pnpm asrun upgrade --version 0.9.0
    `installed -> target`;
 2. reads the **migration manifest of the target release out of its tarball, before installing anything**, and prints
    the migrations and breaking changes between the workspace's baseline (`.asrun.json` → `migrations.since`) and that
-   release. A breaking change needs a person's confirmation (type `upgrade`); an unattended run passes `--yes`. A
-   release that ships no manifest (it predates the manifest) cannot be checked in advance: `upgrade` says so and asks
-   before it installs;
+   release. A breaking change needs a person's confirmation (`Proceed? [y/N]`, an empty line means no); an unattended
+   run passes `--yes` (or `-y`). A release that ships no manifest (it predates the manifest) cannot be checked in
+   advance: `upgrade` says so and asks before it installs;
 3. installs `@asrunjs/asrun@<target>` (it first exempts a fresh release from pnpm's release age, or pnpm would install
    the previous one);
 4. runs `init --update`, `migrate` and `doctor` through the package that was just installed.
 
 `--dry-run` stops after step 2. `--version` pins a release; `upgrade` never downgrades.
 
+### What an upgrade leaves to a person or an AI
+
+`init --update` refreshes only the files the framework generates. A release can also change a file the *project* owns
+(`AGENTS.md`, `CLAUDE.md`, `.mcp.json`, `opencode.jsonc`, `tsconfig.json`, `pnpm-workspace.yaml`, `profiles.yaml`,
+`.claude/settings.json`, `cases/_template.md`) or ask for a manual migration step. Both are recorded, and `upgrade` ends
+with a framed `NEXT` block that lists them with the exact command for each. When there is nothing to do it prints one
+quiet line instead.
+
+`pnpm asrun upgrade --prompt` prints that work as a task for an AI agent, and changes nothing (it reads the workspace
+and the installed package only, so it works offline):
+
+```bash
+pnpm asrun upgrade --prompt          # the task, as Markdown
+pnpm asrun upgrade --prompt --json   # the same answer as JSON (the web UI uses this)
+pnpm asrun migrate --prompt          # the same, after a manual "pnpm add" + "init --update"
+```
+
+In Claude Code or OpenCode, `/upgrade-workspace` does the same: it runs the command above and follows its output.
+
+The prompt is the same for every release; the release-specific part is data — which migrations are outstanding, and
+which project files the templates moved under. For each project file it says how to resolve it:
+
+| File state | Meaning | Command |
+|---|---|---|
+| `replace` | the template changed and nobody edited the file | `pnpm asrun init --force <file>` |
+| `merge` | the template and the project both changed it | merge the template's part, then `pnpm asrun init --ack <file>` |
+| `unknown-base` | the workspace has no recorded template for the file | compare and report, then `pnpm asrun init --ack <file>` |
+| `missing` | the template has the file and the workspace does not | `pnpm asrun init` |
+
+`init --ack <file>` only records that the file is aligned with the installed templates; it never edits the file. The
+baseline lives in `.asrun.json` (`scaffold`) and is committed, so the whole team sees the same state after a `git pull`.
+
 Every `asrun` command also checks the registry for a newer release, at most once a day (the answer is cached in `.tmp/`
 and shared with the web UI), and prints one line on stderr before it starts:
 `@asrunjs/asrun 0.8.0 is available (installed 0.7.0). Upgrade: pnpm asrun upgrade`. On a terminal the line carries an
@@ -257,11 +310,14 @@ can simply be repeated. A migration marked `auto` runs by itself; one with `manu
 until a person does it and acknowledges it. `init --update` never advances the baseline, which is why a manual
 `pnpm add -D @asrunjs/asrun@latest` followed by `pnpm asrun init --update` still leaves its migrations pending.
 
+A migration that names project files (`files: ['AGENTS.md']`) also advances those files' template baseline when it is
+acknowledged, so one command clears both the manual step and the `NEXT` block reminder about the file.
+
 ```bash
 pnpm asrun migrate              # apply what the installed release brings
 pnpm asrun migrate --dry-run    # show it, change nothing
 pnpm asrun migrate --list       # every migration of the installed release, and its state
-pnpm asrun migrate --ack <id>   # a manual step is done (--ack-all for every one)
+pnpm asrun migrate --ack <id>   # a manual step is done (--ack-all for every one); no file is touched
 pnpm asrun migrate --to <v>     # stop at that release
 ```
 
@@ -271,20 +327,22 @@ migration is the installed package. `doctor` warns while migrations or manual st
 ## Workspace
 
 ```bash
-pnpm asrun init [--update] [--force] [--force <file>] [--reset-rules] [--root <dir>] [--no-env] [--no-extras] [--install [spec]]
+pnpm asrun init [--update] [--force] [--force <file>] [--reset-rules] [--ack <file>] [--root <dir>] [--no-env] [--no-extras] [--install [spec]]
 pnpm asrun doctor
-pnpm asrun upgrade [--version <v>] [--dry-run] [--yes]
-pnpm asrun migrate [--list] [--dry-run] [--yes] [--ack <id>|--ack-all]
+pnpm asrun upgrade [--version <v>] [--dry-run] [--yes|-y] [--prompt [--json]]
+pnpm asrun migrate [--list] [--dry-run] [--yes|-y] [--ack <id>|--ack-all] [--prompt [--json]]
 pnpm asrun reset [--root <dir>] [--dry-run] [--yes] [--state] [--lockfile]
 ```
 
 `init` writes the workspace files; `--update` refreshes only the generated ones, and `--force` rewrites every file
 init writes (a single file with `--force <file>`). `--force` still keeps `profiles.yaml` and `package.json`; name
-`--force profiles.yaml` to replace profiles, and add `--reset-rules` to replace `AGENTS.md` or `CLAUDE.md`. It also
-adds the `allowBuilds` entries `pnpm-workspace.yaml` lacks, and installs the optional packages this machine lacks
-(`ffmpeg-static`; `--no-extras` skips them).
+`--force profiles.yaml` to replace profiles, and add `--reset-rules` to replace `AGENTS.md` or `CLAUDE.md`. `--ack
+<file>` records that a project-owned file is aligned with the installed templates without editing it (after a merge).
+It also adds the `allowBuilds` entries `pnpm-workspace.yaml` lacks, and installs the optional packages this machine
+lacks (`ffmpeg-static`; `--no-extras` skips them).
 `doctor` checks profiles, `tsconfig.json`, `playwright.config.ts`, the generated files, the installed version, the
-project rule table, the skill overrides and the workspace migrations. `upgrade` and `migrate` are described above.
+project rule table, the skill overrides, the workspace migrations and the PDF renderer (a missing or unloadable
+`pdfjs-dist` fails every PDF check). `upgrade` and `migrate` are described above.
 
 `reset` removes `node_modules` and the files `init` writes, for a clean reinstall. It deletes a once-only file only
 when it is still identical to its template, so edited files stay; `cases/`, specs, baselines, `profiles.yaml`,

package/docs/install.md

@@ -6,7 +6,7 @@ and is never edited: a project commits only its own test content.
 
 ## Requirements
 
-- **Node.js 22 or newer** and **pnpm**.
+- **Node.js 22.13 or newer** and **pnpm**.
 - **ffmpeg** joins the recordings of one test (a new browser tab has its own video) into one video for the report.
   `pnpm go` installs it with Homebrew on macOS or winget on Windows; on Linux run `sudo apt install ffmpeg`. When it is
   missing, `pnpm go` / `pnpm asrun init` install the bundled `ffmpeg-static` package into the workspace; if neither
@@ -123,10 +123,22 @@ pnpm asrun upgrade
 One command installs the newest release, refreshes the generated files to its templates, applies the workspace
 migrations and runs `doctor`. Before it installs anything it reads the migration manifest of the target release and
 prints the breaking changes and migrations between the workspace's baseline and that release; a breaking change needs
-a person's confirmation (type `upgrade`), and an unattended run passes `--yes`. `--dry-run` shows the same plan and
-changes nothing; `--version <v>` pins a release; it never downgrades.
+a person's confirmation (`Proceed? [y/N]`, an empty line cancels), and an unattended run passes `--yes` (or `-y`).
+`--dry-run` shows the same plan and changes nothing; `--version <v>` pins a release; it never downgrades.
 
-`upgrade` arrives with this release, so a workspace that predates it updates once by hand:
+The upgrade ends with a `NEXT` block when the release changed something the project owns (`AGENTS.md`, `.mcp.json`,
+`cases/_template.md`, ...) or recorded manual migration steps. Each line carries the exact command; an AI can do the
+whole block:
+
+```bash
+pnpm asrun upgrade --prompt
+```
+
+That prints the task as Markdown and changes nothing. Paste it into any agent, or — in Claude Code or OpenCode — run
+`/upgrade-workspace`, which does the same. The prompt is the same for every release: the release-specific part (which
+files moved, which steps are open) is read from the workspace and the installed package.
+
+`upgrade` arrives with this release, so a workspace that predates `upgrade` updates once by hand:
 
 ```bash
 pnpm add -D @asrunjs/asrun@latest
@@ -142,7 +154,8 @@ you when the workspace is behind the installed version, and what is still to mig
 
 An upgrade never replaces what belongs to the project: `cases/`, `tests/` with their baselines, `profiles.yaml`,
 `AGENTS.md`, `CLAUDE.md`, the skill overrides and `.claude/settings.json` stay as they are. A release that needs a
-project-owned file to change says so as a migration with manual steps.
+project-owned file to change says so as a migration with manual steps, and the `NEXT` block (or
+`pnpm asrun upgrade --prompt`) tells a person or an agent what to merge.
 
 To go back to an older release, install it yourself and refresh:
 

package/docs/troubleshooting.md

@@ -45,6 +45,23 @@ bundled `ffmpeg-static` package into the workspace; if neither works, the report
 
 **The UI port is busy** — set `ASRUN_UI_PORT` (and `ASRUN_UI_WEB_PORT` for `pnpm ui:dev`).
 
+## Notifications
+
+**"It is my turn" showed no notification** — run `pnpm asrun notify-test`. It shows one notification through the same
+code the UI server uses and prints the command behind it, so the two failures are told apart:
+
+- It prints `No notification: ...` — the command itself failed (not installed, refused, timed out). The job log has the
+  same reason as `[no desktop notification shown: ...]`.
+- It prints `Done` and nothing appeared — the operating system dropped it. Allow the app that runs it (Terminal, iTerm2,
+  the editor's terminal on macOS; Windows PowerShell on Windows) in the notifications settings of the system, and turn
+  off Focus assist / Do Not Disturb. asrun cannot see or fix this: the notification reached the system.
+- Linux without `libnotify` has no `notify-send`: install it (`sudo apt install libnotify-bin`).
+
+**A run that ended showed no browser notification** — that is the bell in the top bar, and it only fires while its tab is
+in the background: the switch must be on, the browser allowed to notify for this site, and the browser itself allowed in
+the operating system. Its tooltip says when the browser or the system refuses it. Nothing that waits for you depends on
+it: a login, a handoff card and open questions are desktop notifications from the server.
+
 ## Cases and specs
 
 **`Missing values: cases/<id>.md has no "## Values" for profile ...`** — add the profile's values (or a `default`