@asrunjs/asrun 0.13.0 → 0.15.0

package/dist/lib/upgrade-prompt.js

@@ -0,0 +1,233 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { UNRELEASED, migrationState, pendingMigrations, readMarker, resolveMigrations, } from './migrations.js';
+import { MIGRATIONS } from '../migrations/index.js';
+import { frameworkPath, frameworkVersion, isInstalled, outstandingDrift, scaffoldDrift } from './scaffold.js';
+import { card } from './term.js';
+/** The checks every upgrade ends with: the workspace's own tools, which know the installed release's rules. */
+const CHECKS = ['pnpm asrun doctor', 'pnpm case:check', 'pnpm spec:lint', 'pnpm typecheck'];
+/** The version of the framework installed in this workspace (not the one running the command). */
+function installedVersion(root) {
+    try {
+        const manifest = JSON.parse(fs.readFileSync(path.join(root, frameworkPath(root), 'package.json'), 'utf8'));
+        if (typeof manifest.version === 'string' && manifest.version !== '')
+            return manifest.version;
+    }
+    catch {
+        // fall back to the framework this command runs from
+    }
+    return frameworkVersion().version;
+}
+/** How the workspace reaches the framework: a registry install, or the framework's own git checkout. */
+function installKind(root) {
+    return isInstalled(root) && !frameworkPath(root).startsWith('..') ? 'installed' : 'checkout';
+}
+/** One project file, as the upgrade output and the prompt describe it. */
+function describeFile(entry) {
+    const ack = `pnpm asrun init --ack ${entry.file}`;
+    switch (entry.state) {
+        case 'missing':
+            return { file: entry.file, state: entry.state, action: 'missing in the workspace', command: 'pnpm asrun init', projectData: entry.projectData };
+        case 'replace':
+            return {
+                file: entry.file,
+                state: entry.state,
+                action: 'the template changed and nobody edited the file',
+                command: `pnpm asrun init --force ${entry.file}`,
+                projectData: entry.projectData,
+            };
+        case 'merge':
+            return {
+                file: entry.file,
+                state: entry.state,
+                action: 'the template and the project both changed it: merge the template part, then acknowledge',
+                command: ack,
+                projectData: entry.projectData,
+            };
+        case 'unknown-base':
+            return {
+                file: entry.file,
+                state: entry.state,
+                action: 'no baseline for this file: compare it with the template, report what differs, then acknowledge',
+                command: ack,
+                projectData: entry.projectData,
+            };
+        default:
+            return { file: entry.file, state: entry.state, action: 'nothing to do', command: null, projectData: entry.projectData };
+    }
+}
+/** Everything an upgrade still leaves open, computed from the marker, the registry and the installed templates. */
+export function upgradeOutstanding(root, marker = readMarker(root)) {
+    const to = installedVersion(root);
+    const registry = resolveMigrations(MIGRATIONS, to);
+    const state = migrationState(marker, to);
+    const pending = pendingMigrations(registry, state.since, to);
+    const byId = new Map(registry.map((migration) => [migration.id, migration]));
+    // Outstanding manual steps: what an earlier migrate recorded, plus the manual entries that are still pending here
+    // (a workspace that was installed by hand and has not run "migrate" yet).
+    const ids = [...new Set([...state.manual, ...pending.filter((migration) => (migration.manual ?? []).length > 0).map((migration) => migration.id)])];
+    const migrations = [];
+    for (const id of ids) {
+        const migration = byId.get(id);
+        if (migration === undefined) {
+            migrations.push({ id, version: 'unknown', summary: 'a migration this release no longer knows', manual: [], files: [], ack: `pnpm asrun migrate --ack ${id}` });
+            continue;
+        }
+        migrations.push({
+            id,
+            version: migration.version,
+            summary: migration.summary,
+            ...(migration.details !== undefined && { details: migration.details }),
+            manual: migration.manual ?? [],
+            files: migration.files ?? [],
+            ack: `pnpm asrun migrate --ack ${id}`,
+        });
+    }
+    const drift = scaffoldDrift(root, marker);
+    // An advisory entry asks nothing: `migrate` still records it, but it is not work a person has to see.
+    const work = pending.filter((migration) => migration.advisory !== true);
+    return {
+        drift,
+        files: outstandingDrift(drift).map(describeFile),
+        migrations,
+        pending: work.length,
+    };
+}
+/** True when an upgrade leaves nothing for a person or an AI to do. */
+export function nothingToDo(outstanding) {
+    return outstanding.files.length === 0 && outstanding.migrations.length === 0 && outstanding.pending === 0;
+}
+/**
+ * The rows of the "NEXT" card: one per file or migration, each with the exact command. A person must be able to finish
+ * the upgrade by copying from here, without reading the prompt or the docs.
+ */
+export function nextStepRows(outstanding) {
+    const rows = outstanding.files.map((entry) => ({
+        label: entry.file,
+        // The command goes on its own line: a wrapped command is a command nobody can copy.
+        text: entry.command === null ? entry.action : `${entry.action}\n${entry.command}`,
+    }));
+    for (const migration of outstanding.migrations) {
+        const first = migration.manual[0];
+        rows.push({
+            label: migration.id,
+            text: `${first ?? migration.summary}\nwhen done: ${migration.ack}`,
+        });
+    }
+    if (outstanding.pending > 0) {
+        rows.push({ label: 'migrations', text: `${outstanding.pending} apply to this workspace: pnpm asrun migrate` });
+    }
+    return rows;
+}
+/** One sentence for the title of the card, so the count and the work agree. */
+export function nextStepTitle(outstanding) {
+    const files = outstanding.files.length;
+    const migrations = outstanding.migrations.length + (outstanding.pending > 0 ? 1 : 0);
+    const parts = [];
+    if (files > 0)
+        parts.push(`${files} project file${files === 1 ? '' : 's'}`);
+    if (migrations > 0)
+        parts.push(`${migrations} migration step${migrations === 1 ? '' : 's'}`);
+    return `${parts.join(' and ')} still need${files + migrations === 1 ? 's' : ''} a person or an AI`;
+}
+/** The prompt as Markdown: what an agent reads, and what the web UI copies. */
+function renderPrompt(payload) {
+    const lines = [];
+    const none = payload.files.length === 0 && payload.migrations.length === 0;
+    lines.push(`# Bring this asrun workspace to ${payload.to}`, '');
+    lines.push(`Workspace: ${payload.workspace}`, `Framework: ${payload.framework} (${payload.to})${payload.from === null ? '' : `, upgraded from ${payload.from}`}`, 'Start from a clean tree: `git status` must be empty. If it is not, stop and say so.', '');
+    lines.push('Before you change anything, read:', '');
+    lines.push(`- \`${payload.framework}/AGENTS.md\` — the framework baseline that wins over everything else`, '- `pnpm asrun rules` — this project\'s §2 rules and its test-data prefix', `- \`${payload.framework}/docs/agents/case-format.md\` — the case document contract`);
+    lines.push('');
+    if (none) {
+        lines.push('## 1. Nothing in the project\'s own files needs updating', '');
+        lines.push('This release changed nothing a workspace has to merge. Run the checks below and report; do not change files.');
+        lines.push('');
+    }
+    else {
+        lines.push('## 1. Project files that need updating', '');
+        if (payload.files.length === 0)
+            lines.push('None.');
+        else {
+            lines.push('| File | State | What to do |');
+            lines.push('|---|---|---|');
+            for (const entry of payload.files) {
+                lines.push(`| \`${entry.file}\` | ${entry.state} | ${entry.action}${entry.command === null ? '' : ` → \`${entry.command}\``} |`);
+            }
+        }
+        lines.push('');
+        lines.push('## 2. Manual steps of this release', '');
+        if (payload.migrations.length === 0)
+            lines.push('None.');
+        for (const migration of payload.migrations) {
+            lines.push(`- \`${migration.id}\` (${migration.version}) — ${migration.summary}`);
+            if (migration.details !== undefined)
+                lines.push(`  ${migration.details}`);
+            for (const step of migration.manual)
+                lines.push(`  - ${step}`);
+            lines.push(`  - when done: \`${migration.ack}\``);
+        }
+        lines.push('');
+    }
+    lines.push(`## ${none ? 2 : 3}. Checks — fix every finding, and do nothing else`, '');
+    for (const check of payload.checks)
+        lines.push(`    ${check}`);
+    lines.push('');
+    lines.push(`## ${none ? 3 : 4}. In a case document, only structure may change`, '');
+    lines.push('Front-matter keys, section headings, `- Recipe` lines, `### T<n>` cards and their `[T<n>]` references, and the', '`❓ TODO` / `🚫 TODO` blocks. Never change what a case expects and never invent a value: an ambiguity becomes a', '`❓ TODO [non-blocking]` block with an empty `✍️ Answer:` line. Step tags stay as they are (`[input]`, `[writes]`,', '`[email]`).');
+    lines.push('');
+    lines.push(`## ${none ? 4 : 5}. Boundaries`, '');
+    lines.push(`- Never edit anything inside \`${payload.framework}\` (the installed package).`, '- Never read `.auth/`. Do not run the tests. Do not create test data.', '- Never use `--allow-writes` or `ASRUN_ALLOW_WRITES`. Do not run `pnpm asrun migrate --ack`: the person does that.', '- Do not change what a spec asserts. What `spec:lint` and `typecheck` cannot fix is left for `/heal-spec`.');
+    lines.push('');
+    lines.push(`## ${none ? 5 : 6}. Report`, '');
+    lines.push('A table: file → changed / left alone (why) / needs a person (why), then the commands the person should run,', 'verbatim:');
+    const acks = [...payload.files.filter((entry) => entry.command !== null && entry.command !== 'pnpm asrun init').map((entry) => entry.command), ...payload.acks.map((ack) => ack.command)];
+    if (acks.length === 0)
+        lines.push('    (none)');
+    else
+        for (const command of [...new Set(acks)])
+            lines.push(`    ${command}`);
+    lines.push('', 'The last line of your final message is plain text and nothing else: exactly "RESULT: ready" when nothing needs a', 'person, or "RESULT: needs-input" when something does. Never put it in a code fence or in emphasis.');
+    lines.push('');
+    return lines.join('\n');
+}
+/** The payload and the prompt of one workspace, ready for the command line and for the web UI. */
+export function upgradePrompt(root) {
+    const outstanding = upgradeOutstanding(root);
+    const marker = readMarker(root);
+    const previous = marker?.previous;
+    const base = {
+        workspace: root,
+        framework: frameworkPath(root),
+        kind: installKind(root),
+        from: typeof previous?.version === 'string' && previous.version !== UNRELEASED ? previous.version : null,
+        to: installedVersion(root),
+        drift: outstanding.drift,
+        files: outstanding.files,
+        migrations: outstanding.migrations,
+        pending: outstanding.pending,
+        acks: outstanding.migrations.map((migration) => ({ id: migration.id, command: migration.ack })),
+        checks: [...CHECKS],
+    };
+    return { ...base, prompt: renderPrompt(base) };
+}
+/**
+ * The framed "what is left" block, or null when the workspace has nothing outstanding. It carries the exact commands and
+ * names the recommended way to have an agent do them, so a person never has to remember a flag or an id.
+ */
+export function nextStepsText(root, options) {
+    const outstanding = upgradeOutstanding(root);
+    if (nothingToDo(outstanding))
+        return null;
+    return card({
+        label: 'NEXT',
+        title: nextStepTitle(outstanding),
+        rows: nextStepRows(outstanding),
+        lines: [
+            '',
+            'Recommended: run /upgrade-workspace in Claude Code or OpenCode.',
+            'Without an AI CLI: pnpm asrun upgrade --prompt, and paste it to your agent.',
+        ],
+        color: options.color,
+    }, options.width);
+}

package/dist/migrations/index.d.ts

@@ -8,16 +8,24 @@ import type { Migration } from '../lib/migrations.js';
  * for), and anything that only concerns brand-new workspaces belongs in `templates/`.
  *
  * Adding one:
- * 1. Append an entry with an id of `<version>-<slug>` and the version of the release that *introduces* the change
- *    (`version` in `package.json` after the release PR is merged, which is the next version at the time of writing).
+ * 1. Run `pnpm migrations:check`: it lists the surfaces this change touched. Append an entry with an id of
+ *    `unreleased-<slug>` and `version: '0.15.0'`; never write a version number, because release-please only names
+ *    the version in the release pull request. `scripts/build.ts` and `pnpm asrun migrate` resolve the sentinel to the
+ *    installed release, so the published manifest is always correct; `pnpm migrations:freeze` turns it into a real
+ *    version and id on the release branch (the release pull request does it automatically).
  * 2. Explain it for the person: `summary` is one line, `appliesTo` says which workspaces it matters for, `details`
- *    adds what the summary cannot, and `manual` lists what only a person can do.
+ *    adds what the summary cannot, and `manual` lists what only a person can do. `files` names the project-owned
+ *    workspace files the change touches: acknowledging the migration then also records them as aligned with this
+ *    release's templates, which is what clears them from the upgrade's NEXT block.
  * 3. `auto: true` only when the change is idempotent and safe to run without asking (`apply` decides, `detect` skips a
  *    workspace that is already fine). A change to a file the project owns (`AGENTS.md`, `profiles.yaml`, a project
  *    config) is a `manual` step, never an automatic edit.
  * 4. Set `breaking: true` when an untouched workspace can stop working. `pnpm asrun upgrade` then asks before it
  *    installs anything, using the manifest `pnpm build` writes (`dist/migrations/manifest.json`).
- * 5. Never delete or renumber an entry: a workspace on any older release may still need it. The interface is documented
+ * 5. A release that touched one of those surfaces but asks nothing of an existing workspace (documentation, a
+ *    clarified contract, a new optional flag) gets an entry with `advisory: true` and no `manual` steps: it tells
+ *    `pnpm migrations:check` that the change was reviewed, and `migrate` reports it and moves on.
+ * 6. Never delete or renumber an entry: a workspace on any older release may still need it. The interface is documented
  *    in `docs/agents/framework-dev.md`.
  */
 export declare const MIGRATIONS: Migration[];

package/dist/migrations/index.js

@@ -7,16 +7,51 @@
  * for), and anything that only concerns brand-new workspaces belongs in `templates/`.
  *
  * Adding one:
- * 1. Append an entry with an id of `<version>-<slug>` and the version of the release that *introduces* the change
- *    (`version` in `package.json` after the release PR is merged, which is the next version at the time of writing).
+ * 1. Run `pnpm migrations:check`: it lists the surfaces this change touched. Append an entry with an id of
+ *    `unreleased-<slug>` and `version: '0.15.0'`; never write a version number, because release-please only names
+ *    the version in the release pull request. `scripts/build.ts` and `pnpm asrun migrate` resolve the sentinel to the
+ *    installed release, so the published manifest is always correct; `pnpm migrations:freeze` turns it into a real
+ *    version and id on the release branch (the release pull request does it automatically).
  * 2. Explain it for the person: `summary` is one line, `appliesTo` says which workspaces it matters for, `details`
- *    adds what the summary cannot, and `manual` lists what only a person can do.
+ *    adds what the summary cannot, and `manual` lists what only a person can do. `files` names the project-owned
+ *    workspace files the change touches: acknowledging the migration then also records them as aligned with this
+ *    release's templates, which is what clears them from the upgrade's NEXT block.
  * 3. `auto: true` only when the change is idempotent and safe to run without asking (`apply` decides, `detect` skips a
  *    workspace that is already fine). A change to a file the project owns (`AGENTS.md`, `profiles.yaml`, a project
  *    config) is a `manual` step, never an automatic edit.
  * 4. Set `breaking: true` when an untouched workspace can stop working. `pnpm asrun upgrade` then asks before it
  *    installs anything, using the manifest `pnpm build` writes (`dist/migrations/manifest.json`).
- * 5. Never delete or renumber an entry: a workspace on any older release may still need it. The interface is documented
+ * 5. A release that touched one of those surfaces but asks nothing of an existing workspace (documentation, a
+ *    clarified contract, a new optional flag) gets an entry with `advisory: true` and no `manual` steps: it tells
+ *    `pnpm migrations:check` that the change was reviewed, and `migrate` reports it and moves on.
+ * 6. Never delete or renumber an entry: a workspace on any older release may still need it. The interface is documented
  *    in `docs/agents/framework-dev.md`.
  */
-export const MIGRATIONS = [];
+export const MIGRATIONS = [
+    {
+        id: '0.15.0-upgrade-workspace',
+        version: '0.15.0',
+        summary: 'A new /upgrade-workspace command aligns a workspace with the release it runs',
+        appliesTo: 'every workspace: the command is generated, its one line in the project-owned AGENTS.md is not',
+        details: 'The generated commands now include /upgrade-workspace (Claude Code and OpenCode): it runs "pnpm asrun upgrade ' +
+            '--prompt" and follows the task it prints, which is the work an upgrade leaves to a person or an AI. The layout ' +
+            'list in AGENTS.md names the new command; that file belongs to the project and is never rewritten.',
+        files: ['AGENTS.md'],
+        manual: [
+            'Add `/upgrade-workspace` to the command list in your AGENTS.md (the "Layout of this workspace" section, outside ' +
+                '## 2 and ## 3). The file the command itself lives in is generated and was already refreshed.',
+        ],
+    },
+    {
+        id: '0.15.0-explore-lead-docs',
+        version: '0.15.0',
+        summary: 'The case format documents per-profile reference lines for /explore-case --lead, and the workflow text names the flag',
+        appliesTo: 'every workspace: this is documentation; no file a workspace owns has to change',
+        details: 'A target card may now carry one "Reference <profile-id>:" line per profile that was looked at separately, and a ' +
+            'profile that shares the lead screenshot says "none: <reason>". The case format gained a paragraph about what a ' +
+            'diff profile adds to a case (its Values entry and its reference line, never a second copy of the steps). None of ' +
+            'this changes an existing case: a card with one reference line stays valid.',
+        files: ['AGENTS.md', 'cases/**'],
+        advisory: true,
+    },
+];

package/dist/migrations/manifest.json

@@ -1 +1,27 @@
-[]
+[
+  {
+    "id": "0.15.0-upgrade-workspace",
+    "version": "0.15.0",
+    "summary": "A new /upgrade-workspace command aligns a workspace with the release it runs",
+    "appliesTo": "every workspace: the command is generated, its one line in the project-owned AGENTS.md is not",
+    "details": "The generated commands now include /upgrade-workspace (Claude Code and OpenCode): it runs \"pnpm asrun upgrade --prompt\" and follows the task it prints, which is the work an upgrade leaves to a person or an AI. The layout list in AGENTS.md names the new command; that file belongs to the project and is never rewritten.",
+    "manual": [
+      "Add `/upgrade-workspace` to the command list in your AGENTS.md (the \"Layout of this workspace\" section, outside ## 2 and ## 3). The file the command itself lives in is generated and was already refreshed."
+    ],
+    "files": [
+      "AGENTS.md"
+    ]
+  },
+  {
+    "id": "0.15.0-explore-lead-docs",
+    "version": "0.15.0",
+    "summary": "The case format documents per-profile reference lines for /explore-case --lead, and the workflow text names the flag",
+    "appliesTo": "every workspace: this is documentation; no file a workspace owns has to change",
+    "details": "A target card may now carry one \"Reference <profile-id>:\" line per profile that was looked at separately, and a profile that shares the lead screenshot says \"none: <reason>\". The case format gained a paragraph about what a diff profile adds to a case (its Values entry and its reference line, never a second copy of the steps). None of this changes an existing case: a card with one reference line stays valid.",
+    "files": [
+      "AGENTS.md",
+      "cases/**"
+    ],
+    "advisory": true
+  }
+]

package/dist/scripts/build.js

@@ -23,6 +23,9 @@ for (const file of COPIED_SCRIPTS) {
 }
 // The migration manifest of the published package. A still-old `pnpm asrun upgrade` reads it out of the *target*
 // tarball before installing, so it has to be in `dist/`, next to the compiled registry the installed command uses.
+// `version: 'unreleased'` entries are resolved to the version being built: the manifest must never carry a sentinel,
+// because the reader compares versions without knowing about one.
 const manifestFile = path.join(FRAMEWORK_ROOT, MANIFEST_FILE);
+const built = JSON.parse(fs.readFileSync(path.join(FRAMEWORK_ROOT, 'package.json'), 'utf8'));
 fs.mkdirSync(path.dirname(manifestFile), { recursive: true });
-fs.writeFileSync(manifestFile, JSON.stringify(toManifest(MIGRATIONS), null, 2) + '\n');
+fs.writeFileSync(manifestFile, JSON.stringify(toManifest(MIGRATIONS, built.version ?? '0.0.0'), null, 2) + '\n');

package/dist/scripts/check-cases.js

@@ -58,7 +58,7 @@ function questionProblems(id) {
             warnings.push(`the "✍️ Answer:" line of the question on line ${question.line} is not the last line of its block`);
         }
         if (!question.parent) {
-            warnings.push(`the question on line ${question.line} has no text above it: accepting it would delete a claim nobody sees`);
+            warnings.push(`the question on line ${question.line} has no sentence it is about: accepting it would delete a claim nobody sees`);
             continue;
         }
         const step = doc.steps.find((candidate) => candidate.line === question.parent?.line);
@@ -67,8 +67,8 @@ function questionProblems(id) {
         }
         const anchor = immediateAnchor(splitLines(doc.text), question.line, question.indent);
         if (anchor !== null && anchor !== question.parent.line) {
-            const above = splitLines(doc.text).find((line) => line.number === anchor)?.text.trim() ?? '';
-            warnings.push(`the question on line ${question.line} hangs under "${above.slice(0, 80)}", but the panel shows "${question.parent.text.slice(0, 80)}" as the text above it; indent it under that sentence or lift that sentence to a top-level bullet`);
+            const anchorText = splitLines(doc.text).find((line) => line.number === anchor)?.text.trim() ?? '';
+            warnings.push(`the question on line ${question.line} hangs under "${anchorText.slice(0, 80)}", but the panel shows "${question.parent.text.slice(0, 80)}" as the sentence it is about; indent it under that sentence or lift that sentence to a top-level bullet`);
         }
     }
     for (const step of doc.steps) {

package/dist/scripts/cli.js

@@ -44,13 +44,18 @@ async function main() {
         await import('./explore-notes.js');
         return;
     }
+    if (command === 'notify-test') {
+        const { main: notifyTest } = await import('./notify-test.js');
+        process.exitCode = await notifyTest(rest);
+        return;
+    }
     if (command === 'help' || command === '--help-init') {
         console.log(USAGE);
         return;
     }
     await import('./run.js');
 }
-const USAGE = `Usage: pnpm asrun [init|doctor|rules|reset|upgrade|migrate|explore:notes] [options]
+const USAGE = `Usage: pnpm asrun [init|doctor|rules|reset|upgrade|migrate|explore:notes|notify-test] [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,
@@ -62,8 +67,11 @@ const USAGE = `Usage: pnpm asrun [init|doctor|rules|reset|upgrade|migrate|explor
   reset            Remove node_modules and the files init writes, for a clean reinstall (keeps cases, specs,
                    profiles.yaml, package.json and edited scaffold files; see "pnpm asrun reset --help").
   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").
+                   target release for breaking changes. It ends with what an AI agent should still fix, and "upgrade
+                   --prompt" prints that task (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.
-  explore:notes    Print or validate the local exploration note of a case (see "pnpm asrun explore:notes --help").`;
+  explore:notes    Print or validate the local exploration note of a case (see "pnpm asrun explore:notes --help").
+  notify-test      Show one desktop notification and print the command behind it, to tell a hidden notification from a
+                   broken one (see "pnpm asrun notify-test --help").`;
 await main();

package/dist/scripts/doctor.js

@@ -2,13 +2,14 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { createRequire } from 'node:module';
 import { loadProfiles, listEnvs, PROFILES_FILE } from '../lib/profiles.js';
-import { FRAMEWORK_ROOT, ROOT, SKILLS_DIR } from '../lib/paths.js';
+import { FRAMEWORK_ROOT, ROOT, SKILLS_DIR, packageDir } from '../lib/paths.js';
 import { readWorkspaceConfig } from '../lib/config.js';
 import { readProjectRules, mentionedTestDataPrefixes } from '../lib/rules.js';
 import { spawnTarget } from '../lib/command.js';
-import { migrationState, pendingMigrations } from '../lib/migrations.js';
+import { compareVersions, migrationState, pendingMigrations, resolveMigrations } from '../lib/migrations.js';
 import { MIGRATIONS } from '../migrations/index.js';
 import { GENERATED, frameworkPath, frameworkVersion, PACKAGE, renderTemplate } from './init.js';
+import { outstandingDrift, scaffoldDrift } from '../lib/scaffold.js';
 import { BUILD_APPROVALS, RUNTIME_EXTRAS, hasCapability, installedInWorkspace } from '../lib/runtime-deps.js';
 import { builtFile, COPIED_SCRIPTS } from '../lib/build-artifacts.js';
 /**
@@ -85,6 +86,33 @@ function documentedBrowserTools() {
     const section = /^## Runnable\n([\s\S]*?)^## /m.exec(text)?.[1] ?? '';
     return [...new Set(section.match(/browser_[a-z0-9_]+/g) ?? [])];
 }
+/**
+ * The PDF renderer, which is how an exploring agent looks at a downloaded PDF and how a spec checks one: `lib/pdf.js`
+ * imports `pdfjs-dist` and `@napi-rs/canvas` at run time, and pdf.js reads its fonts and cmaps from the package folder
+ * `packageDir` names. Both are runtime dependencies of the framework, so a failure means the install (or the Node
+ * version) is broken — and it used to surface only when someone rendered a PDF, halfway through an exploration.
+ */
+async function pdfRenderer() {
+    let dir;
+    try {
+        dir = packageDir('pdfjs-dist');
+    }
+    catch {
+        // `packageDir` already says where it looked; the caller adds what to do about it.
+        return { ok: false, reason: 'pdfjs-dist is not installed where the framework can reach it' };
+    }
+    try {
+        const version = JSON.parse(read(path.join(dir, 'package.json')) ?? '{}').version ?? 'unknown';
+        // Loading both is what proves it: the module import resolves exactly like the one in `lib/pdf.js`, and the native
+        // canvas is what draws the page.
+        await import('pdfjs-dist/legacy/build/pdf.mjs');
+        await import('@napi-rs/canvas');
+        return { ok: true, version };
+    }
+    catch (error) {
+        return { ok: false, reason: error.message };
+    }
+}
 export async function main(args) {
     if (args.includes('--help')) {
         console.log('Usage: pnpm asrun doctor');
@@ -134,6 +162,28 @@ export async function main(args) {
         }
     }
     const framework = recordedPath ?? actualPath;
+    // The registry, read before the workspace state: an entry above the installed release never runs, because
+    // `pendingMigrations` stops at the installed version. That is what a workspace several releases behind should see (the
+    // entry waits for its own release), but it is a mistake in the registry itself — a hand-written version, a checkout of
+    // a release that is not published yet — so doctor names it instead of letting the entry disappear silently.
+    const registry = resolveMigrations(MIGRATIONS, installedVersion.version);
+    const reportRegistryError = (error) => {
+        const message = `The migration registry is invalid: ${error instanceof Error ? error.message : String(error)}`;
+        if (!errors.includes(message))
+            errors.push(message);
+    };
+    try {
+        const newer = registry.filter((entry) => compareVersions(entry.version, installedVersion.version) > 0);
+        if (newer.length > 0) {
+            warnings.push(`${newer.length} migration entr${newer.length === 1 ? 'y' : 'ies'} in the registry ` +
+                `${newer.length === 1 ? 'names' : 'name'} a release newer than the installed ${installedVersion.version} ` +
+                `(${newer.map((entry) => entry.id).join(', ')}): ${newer.length === 1 ? 'it never runs' : 'they never run'} ` +
+                'here, so an entry written by hand stays "unreleased" until the release names it.');
+        }
+    }
+    catch (error) {
+        reportRegistryError(error);
+    }
     // Workspace migrations: `migrations.since` is the release the workspace matches, so newer ones are still to do. A
     // workspace upgraded by hand (pnpm add + init --update) keeps the old baseline, which is what makes this check work.
     if (marker !== null) {
@@ -141,7 +191,7 @@ export async function main(args) {
             const state = migrationState(marker, installedVersion.version);
             const outstanding = state.manual.length;
             facts.push(`migrations: since ${state.since}${outstanding > 0 ? `, ${outstanding} manual step(s) outstanding` : ''}`);
-            const pending = pendingMigrations(MIGRATIONS, state.since, installedVersion.version);
+            const pending = pendingMigrations(registry, state.since, installedVersion.version);
             if (pending.length > 0) {
                 warnings.push(`${pending.length} workspace migration(s) apply between ${state.since} and ${installedVersion.version} ` +
                     `(${pending.map((migration) => migration.id).join(', ')}): run "pnpm asrun migrate".`);
@@ -150,9 +200,17 @@ export async function main(args) {
                 warnings.push(`Manual migration steps are still open (${state.manual.join(', ')}): run "pnpm asrun migrate --list" to see ` +
                     'them, then "pnpm asrun migrate --ack <id>" once they are done.');
             }
+            // Project-owned files whose template moved under the workspace: no command can merge them, so doctor keeps
+            // naming them until somebody does it and records it. The prompt is the one entry point that explains the rest.
+            const drift = outstandingDrift(scaffoldDrift(ROOT, marker));
+            if (drift.length > 0) {
+                const shown = drift.map((entry) => `${entry.file} (${entry.state})`).join(', ');
+                warnings.push(`${drift.length} project file(s) to align with ${installedVersion.version}: ${shown}. Run ` +
+                    '"pnpm asrun migrate --prompt" for the task, then "pnpm asrun init --ack <file>" (or "init --force <file>").');
+            }
         }
         catch (error) {
-            errors.push(`The migration registry is invalid: ${error instanceof Error ? error.message : String(error)}`);
+            reportRegistryError(error);
         }
     }
     // The framework repository compiles itself into `dist/`, and `templates/playwright.config.ts` makes every workspace
@@ -296,6 +354,17 @@ export async function main(args) {
         warnings.push(`${extra.pkg} is not installed and this machine does not provide it: ${extra.provides} is skipped. Run ` +
             '"pnpm asrun init" (or "pnpm go") to install it, or install the tool yourself and run doctor again.');
     }
+    // The PDF renderer: "pnpm pdf:render", the exploring agent's look at a downloaded PDF, and every `expectPdf` check.
+    const pdf = await pdfRenderer();
+    if (pdf.ok) {
+        facts.push(`pdf renderer:  pdfjs-dist ${pdf.version} (canvas ok)`);
+    }
+    else {
+        // An Error message may already end with a period; the sentence around it must not double it.
+        const reason = pdf.reason.replace(/\.\s*$/, '');
+        errors.push(`The PDF renderer does not work, so "pnpm pdf:render" and every PDF check fail (${reason}). To fix it, run ` +
+            '"pnpm install" in the workspace root (Node 22.13 or newer is required), or install the framework again.');
+    }
     let scripts = null;
     try {
         const packageJson = read(path.join(ROOT, 'package.json'));

package/dist/scripts/explore-notes.js

@@ -1,6 +1,6 @@
 import path from 'node:path';
 import { isValidCaseId } from '../lib/case-id.js';
-import { caseSha256, exploreNotesDir, exploreNotesFile, noteFreshness, readExploreNotes, } from '../lib/explore-notes.js';
+import { caseSha256, exploreNotesDir, exploreNotesFile, noteCoverage, 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]
@@ -14,6 +14,9 @@ and falls back to a full replay when it is missing or stale.
   --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
 
+A note is "full" (it explored every step) or "diff" (an /explore-case --lead run explored only the steps that can
+differ on that profile, and "basedOn" names the lead profile the rest comes from).
+
 Paths are relative to the workspace root (${ROOT}).`;
 const args = process.argv.slice(2);
 let caseId;
@@ -98,6 +101,9 @@ if (check) {
         console.log(`FAIL cases/${caseId}.md does not exist`);
     }
     const known = new Set(knownProfiles());
+    // A --profile run must still see the lead note a diff note leans on.
+    const all = profile === undefined ? notes : readExploreNotes(caseId).notes;
+    const byProfile = new Map(all.map((note) => [note.profile, note]));
     for (const note of notes) {
         const freshness = noteFreshness(note);
         if (freshness.state !== 'fresh') {
@@ -106,6 +112,15 @@ if (check) {
         if (!known.has(note.profile)) {
             console.log(`WARN ${relative(exploreNotesFile(caseId, note.profile))}: "${note.profile}" is not in profiles.yaml`);
         }
+        if (note.depth !== 'diff' || note.basedOn === undefined)
+            continue;
+        const lead = byProfile.get(note.basedOn);
+        if (lead === undefined) {
+            console.log(`WARN ${relative(exploreNotesFile(caseId, note.profile))}: based on "${note.basedOn}", which has no note; /gen-spec replays the steps this note does not hold`);
+        }
+        else if (lead.depth === 'diff') {
+            console.log(`WARN ${relative(exploreNotesFile(caseId, note.profile))}: based on "${note.basedOn}", which is itself a diff note; /gen-spec replays the steps neither note holds`);
+        }
     }
     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.');
@@ -119,7 +134,9 @@ function describe(note) {
         .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}` : ''}`;
+    const coverage = noteCoverage(note);
+    const cover = coverage.depth === 'diff' ? `diff, based on ${coverage.basedOn}` : 'full';
+    return `${state}  ${cover}  steps ${steps || '-'}  targets ${targets || '-'}  captured ${note.capturedAt}${note.updatedAt ? `  refreshed ${note.updatedAt}` : ''}`;
 }
 function knownProfiles() {
     try {

package/dist/scripts/init.d.ts

@@ -1,31 +1,11 @@
 import { MARKER, PACKAGE } from '../lib/paths.js';
-/** Files `init` owns: `--update` rewrites exactly these, and a project never edits them. */
-export declare const GENERATED: {
-    file: string;
-    template: string;
-}[];
-/** Files `init` creates once; after that the project owns them and may edit them freely. */
-export declare const ONCE: {
-    file: string;
-    template: string;
-}[];
+/**
+ * The files `init` writes come from `lib/scaffold.ts`, together with the baseline that records which template a
+ * project-owned file is aligned with. They are re-exported here because `doctor`, `reset` and the prompt import them
+ * from the command that writes them.
+ */
+export { GENERATED, ONCE, frameworkPath, frameworkVersion, isInstalled, renderTemplate } from '../lib/scaffold.js';
 export { MARKER };
 export { PACKAGE };
 export declare const DOTENV_HEADER = "# asrun: the workspace these commands run against (relative to this file).";
-/** How the workspace reaches the framework: `./node_modules/@asrunjs/asrun`, or a relative folder in the framework repo. */
-export declare function frameworkPath(root: string): string;
-/** True when this workspace has the package installed (or is the framework's own checkout). */
-export declare function isInstalled(root: string): boolean;
-/** Fills the `{{framework}}`, `{{playwright}}` and `{{asrun}}` placeholders of a template. */
-export declare function renderTemplate(name: string, root: string): string;
-/**
- * The Playwright CLI the MCP server runs. The workspace's own install is the normal place; a workspace that lives
- * inside the framework repository (examples/demo) has no `node_modules` of its own, so it points at the framework's.
- * Kept relative: the file is committed and must not name a machine.
- */
-export declare function playwrightBin(root: string): string;
-export declare function frameworkVersion(): {
-    version: string;
-    commit: string;
-};
 export declare function main(args: string[]): Promise<number>;