@asrunjs/asrun 0.6.1 → 0.8.0

package/dist/ui/server/update.js

@@ -0,0 +1,87 @@
+import { EventEmitter } from 'node:events';
+import { checkForUpdate, formatNotice, upgradeCommand, useColor } from '../../lib/update-check.js';
+/**
+ * The release check of the web UI: once when the server starts, then once a day at 00:00 UTC. The answer is cached in
+ * `.tmp/` (see lib/update-check.ts), so several tabs and the command line share one registry read. Pages learn about a
+ * change through the `update` event of `/api/events`.
+ */
+export const updateEvents = new EventEmitter();
+// One listener per open page; the default warning at ten tabs is noise.
+updateEvents.setMaxListeners(0);
+let status = null;
+let inFlight = null;
+/** The notice already printed, so a daily re-check of the same release does not repeat it. */
+let printedNotice = null;
+/** What the UI should show now; before the first answer every field that needs one is null. */
+export function updateInfo() {
+    if (status === null) {
+        return {
+            current: null,
+            latest: null,
+            available: false,
+            checkedAt: null,
+            kind: null,
+            command: null,
+            disabled: false,
+            mocked: false,
+            error: null,
+        };
+    }
+    return {
+        current: status.current,
+        latest: status.latest,
+        available: status.available,
+        checkedAt: status.checkedAt,
+        kind: status.kind,
+        command: status.available ? upgradeCommand(status.kind) : null,
+        disabled: status.disabled,
+        mocked: status.mocked,
+        error: status.error,
+    };
+}
+/**
+ * Asks the registry again and tells the open pages. `force` goes past a fresh cache, which is what the startup and the
+ * daily checks do; the answer is written back to `.tmp/`, so the command line shares it. Overlapping calls share one
+ * read: the daily timer and the first page load can arrive together.
+ */
+export function refreshUpdate(force = true) {
+    if (inFlight !== null)
+        return inFlight;
+    inFlight = (async () => {
+        try {
+            status = checkForUpdate({ force });
+        }
+        catch {
+            // checkForUpdate reports a failed read instead of throwing; if that ever changes, keep serving the last answer.
+        }
+        const answer = updateInfo();
+        const notice = status === null || status.disabled ? null : formatNotice(status, { color: useColor(process.stdout) });
+        // Printed on the terminal only when something changed: once at startup, and again for a newer release.
+        if (notice !== printedNotice && notice !== null) {
+            printedNotice = notice;
+            console.log(notice);
+        }
+        if (notice === null)
+            printedNotice = null;
+        updateEvents.emit('update', answer);
+        return answer;
+    })().finally(() => {
+        inFlight = null;
+    });
+    return inFlight;
+}
+/** Today's check, then one at every UTC midnight while the server runs. */
+export function startUpdateWatcher() {
+    void refreshUpdate(true);
+    scheduleNextCheck();
+}
+function scheduleNextCheck() {
+    const now = new Date();
+    const nextMidnight = Date.UTC(now.getUTCFullYear(), now.getUTCMonth(), now.getUTCDate() + 1);
+    const timer = setTimeout(() => {
+        void refreshUpdate(true);
+        scheduleNextCheck();
+    }, Math.max(1_000, nextMidnight - now.getTime()));
+    // The check must never keep the server process alive on its own.
+    timer.unref();
+}

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

@@ -332,6 +332,30 @@ export interface InfoResponse {
     suites: string[];
     caseIds: string[];
 }
+/**
+ * What the web UI shows about a newer release. The first check of a server run may still be running, so every field
+ * that needs an answer is null until it finished.
+ */
+export interface UpdateInfo {
+    /** The version of the framework this server runs; null until the first check finished. */
+    current: string | null;
+    /** The newest release on the registry; null when there is none (or the registry could not be read). */
+    latest: string | null;
+    /** True when `latest` is newer than `current`. */
+    available: boolean;
+    /** When the answer was fetched, ISO. A cached answer keeps the time of the fetch. */
+    checkedAt: string | null;
+    /** `installed` when the framework comes from the registry, `checkout` for the framework's own git repository. */
+    kind: 'installed' | 'checkout' | null;
+    /** The line to run to get the newest release; null when there is nothing to upgrade. */
+    command: string | null;
+    /** True when ASRUN_NO_UPDATE_CHECK turned the check off. */
+    disabled: boolean;
+    /** True when the answer is a development mock (ASRUN_UPDATE_MOCK_* or `.tmp/update-mock.json`). */
+    mocked: boolean;
+    /** Why the last check could not read the registry; the UI stays quiet then. */
+    error: string | null;
+}
 /** Everything that belongs to one case. Shown before a delete or rename, and returned by them. */
 export interface CaseImpact {
     id: string;

package/docs/agents/framework-dev.md

@@ -44,10 +44,19 @@ is relevant to a project that uses asrun as a dependency.
 
   `pnpm demo:reset` deletes the database and seeds it again; logins must be redone afterwards. Demo accounts are in
   `examples/demo/README.md`.
+
+  `.env` is per machine and gitignored, so a fresh clone has none: `init --root examples/demo` writes it in the folder
+  the command runs in (`ASRUN_ROOT=examples/demo`), and `pnpm go` does the same in its third step, so no manual step is
+  needed. Without it `pnpm go` still finds the demo through its fallback, but the other commands (`pnpm asrun`,
+  `pnpm signin`, `pnpm explore`) resolve the workspace from `ASRUN_ROOT` and then from the current folder, and stop
+  with "No workspace found: this is the framework folder".
 - 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.
 - 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
+  there `scripts/go.mjs` is next to `bin/asrun.mjs`.
 - `templates/` is the source of the files a workspace gets. When a template changes, bump `version` in
   `package.json` so `pnpm asrun doctor` in a project shows that it is behind.
 - `init` owns two lists: `GENERATED` (rewritten by `--update`; the commands and the Playwright files) and `ONCE`
@@ -57,6 +66,74 @@ is relevant to a project that uses asrun as a dependency.
 - A project's rules never flow back here. The framework reads a workspace only through `ROOT` at run time; nothing
   under `templates/` or `.claude/skills/` is generated from a project.
 
+### Seeing the release notice without a release
+
+`lib/update-check.ts` asks the registry for the newest version. To see the notice without publishing anything, make it
+answer with a made-up version. The check is the same code the command line and the web UI run, so both show exactly
+what a real release would produce.
+
+```powershell
+# A framework checkout (the default in this repository): the notice says to update with git
+$env:ASRUN_UPDATE_MOCK_LATEST = '9.9.9'
+pnpm asrun doctor       # stderr: ... Update the framework checkout: git pull
+pnpm ui                  # top-bar badge, and the dialog offers git pull
+
+# A registry install: the notice offers "pnpm asrun upgrade"
+$env:ASRUN_UPDATE_MOCK_KIND = 'installed'
+pnpm ui
+```
+
+- `ASRUN_UPDATE_MOCK_LATEST=<version>` replaces the registry answer; `ASRUN_UPDATE_MOCK_KIND=installed|checkout`
+  replaces the install-kind detection. Each field falls back, in this order, to the environment, then to
+  `.tmp/update-mock.json` at the workspace root (in this repository that is `examples/demo/.tmp/update-mock.json`,
+  because `.env` points `ASRUN_ROOT` there; for example `{"latest": "9.9.9", "kind": "installed"}`). A mock is never
+  written to the `.tmp/update-check.json` cache, so deleting the variable or the file brings the real check straight
+  back.
+- The environment is read when a process starts: a running `pnpm ui` must be restarted after changing it. The mock file
+  is read on every check, so editing it and pressing **Check again** (or `GET /api/update?refresh=1`) is enough.
+- The UI marks a mocked answer with a **Dev mock** tag, and the API returns `mocked: true`.
+- `ASRUN_NO_UPDATE_CHECK=1` still wins over both: it turns the notice off entirely.
+
+`GET /api/update` answers with the state of the server's last check; `GET /api/update?refresh=1` checks again first
+(it is what the dialog's **Check again** button calls).
+
+### Optional runtime packages
+
+A dependency with an install script makes `pnpm dlx @asrunjs/asrun` stop at pnpm's build-approval picker: the dlx
+sandbox does not read the workspace's `allowBuilds`, and in a pipeline nobody can answer the prompt. So a package that
+is heavy and optional (the bundled `ffmpeg-static` today) is not a dependency at all:
+
+- Add it to `RUNTIME_EXTRAS` in `lib/runtime-deps.ts`, with the line the person sees (`provides`), a `probe` command
+  that proves the machine already has the capability, and `builds: true` when the package runs an install script.
+- `init` (and therefore `go`, whose third step runs it) writes the `allowBuilds` entry and installs the package as a
+  dependency of the workspace, only when the probe fails; `--no-extras` leaves it out. `BUILD_APPROVALS` is the one
+  list `doctor`, `go` and the template of `pnpm-workspace.yaml` follow.
+- Resolve an extra from `ROOT` first, then from the framework's own install, the way `lib/ffmpeg.ts` does.
+- `doctor` warns while an extra is missing, and `verify:pack` fails when one of them becomes a runtime dependency
+  again (that would bring the dlx prompt back). CI runs it on a packed tarball.
+
+### Workspace migrations
+
+A release can require an *existing* workspace to change; `docs/commands.md` has the user's view. The registry is
+`migrations/index.ts`, and the interface plus the helpers live in `lib/migrations.ts`:
+
+- `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.
+- `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.
+- 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.
+- `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.
+
 ### Installing this repository as a Git dependency (private)
 
 The npm package is the public channel for users. This repository is private, so a Git dependency works only on a
@@ -151,6 +228,27 @@ Every lead, label and tooltip is written for the person using the UI, never for
 - **Say what the user sees.** "The run appears in the Jobs bar", not "the command runs in a one-shot session"; "the
   browser shows a small card", not "the agent pauses on a `writes` step".
 
+## Releases
+
+Nothing bumps the version by hand. A merge to `main` runs `.github/workflows/release.yml`, and Release Please opens
+(or refreshes) one `chore(release): X.Y.Z` pull request holding the next `package.json` version and the matching
+`CHANGELOG.md` entry. Merging that pull request is the release: the same run tags the commit and publishes to npm.
+
+- Tags carry the package component, which manifest mode adds by default: `asrun-v0.7.0`, not `v0.7.0`. The publish check
+  accepts either, so a hand-made `v0.7.0` still works.
+
+- The next version comes from the commit messages on `main`, and a squashed pull request title becomes that message.
+  `fix:` is a patch, `feat:` a minor, `feat!:` a major (the project is past 0.x, so a breaking change releases
+  `1.0.0`). `chore:`, `ci:` and the rest ship nothing and open no release at all.
+  `.github/workflows/pr-title.yml` enforces the prefixes.
+- `templates/`, `docs/`, `ui/dist/` and `.claude/` are shipped files: a change to them needs `fix:` or `feat:`, not
+  `docs:`, or no release is made and no workspace ever sees the new version (`pnpm asrun doctor` compares it).
+- `release.yml` is the only uploader. When an upload fails after the tag exists, run it by hand with the tag instead of
+  re-running the failed job: `gh workflow run release.yml -f tag=asrun-v1.0.0` (`-f dry_run=true` packs without
+  uploading). A re-run of the push run finds the release already made and skips publishing.
+- npm authentication is trusted publishing (OIDC, no secret): the workflow filename in the package's trusted publisher
+  settings is `release.yml`. A private repository gets no provenance, so the package page shows no provenance badge.
+
 ## Before you open a pull request
 
 ```bash
@@ -162,6 +260,6 @@ pnpm ui:build       # ui/dist/ must match ui/web and ui/server
 ```
 
 - `pnpm build` and `pnpm ui:build` also run from `prepare` and `prepack`, so a published package is complete.
-- Bump `version` when `templates/` or the shipped docs change; `pnpm asrun doctor` in a project compares it.
+- The version is not bumped by hand (see Releases).
 - Keep the demo's committed expectations (`profiles.yaml`, `cases/`, `tests/`, baselines) in step with the demo site.
   Baselines are a person's decision: never let an agent regenerate them.

package/docs/commands.md

@@ -7,8 +7,11 @@ thin wrappers, so `pnpm asrun`, `pnpm signin` and the rest work as below. The sa
 
 | I want to... | Command |
 |---|---|
-| Install / update the framework | `pnpm dlx @asrunjs/asrun init --install`, `pnpm add -D @asrunjs/asrun@latest` |
+| 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]` |
 | Prepare or check the workspace | `pnpm asrun init [--update]`, `pnpm asrun doctor` |
+| See or apply the workspace migrations after a manual install | `pnpm asrun migrate [--list] [--dry-run]` |
+| Start over with fresh dependencies | `pnpm asrun reset [--yes] [--state] [--lockfile]` |
 | 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>` |
@@ -150,26 +153,110 @@ pnpm cleanup --env staging --forget
 
 A write case registers everything it creates (named `[asrun] ...`) and removes it after the test, also after a
 failure. Whatever could not be removed is listed in the report and by `cleanup`. Delete it by hand in the product,
-then run `--forget` so it is not listed again. `--env` is required.
+then run `--forget` so it is not listed again. `--env` is required. `cleanup` is about test data in the product;
+`pnpm asrun reset` (below) is the command that removes workspace files and dependencies.
 
 ## Web UI
 
 ```bash
-pnpm go          # install + build + start + open the browser (the usual command)
-pnpm ui          # build the web app and serve http://127.0.0.1:4173
-pnpm ui:dev      # Vite on :5173 with hot reload, API in watch mode
+pnpm go             # install + build + start + open the browser (the usual command)
+pnpm go --no-open   # same, without opening a browser
+pnpm go --no-ui     # install and prepare the workspace, then stop (no server)
+pnpm go --dry-run   # only print the resolved workspace, framework and asrun command
+pnpm ui             # build the web app and serve http://127.0.0.1:4173
+pnpm ui:dev         # Vite on :5173 with hot reload, API in watch mode
 ```
 
 The UI only listens on `127.0.0.1`. Set `ASRUN_UI_PORT` to change the port (`ASRUN_UI_WEB_PORT` for the Vite dev
 server). See [web-ui.md](./web-ui.md).
 
+The UI checks the registry for a newer release when it starts and then once a day at 00:00 UTC (the answer is cached in
+`.tmp/`, so the command line shares it). A newer release is printed on the terminal at startup and shows up as a badge
+in the top bar; click it to see the version and the command that upgrades this install. `pnpm asrun upgrade` is skipped
+there (it reads the registry itself). Set `ASRUN_NO_UPDATE_CHECK=1` to switch the check off, for a pipeline or a machine
+without a registry.
+
+## Upgrading the framework
+
+```bash
+pnpm asrun upgrade
+pnpm asrun upgrade --dry-run
+pnpm asrun upgrade --version 0.9.0
+```
+
+`upgrade` runs four steps, in this order:
+
+1. resolves the target release (`latest`, or the dist-tag/version `--version <v>` names) and prints
+   `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;
+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.
+
+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
+`UPDATE` badge and highlights the version and the command; a pipe or a log gets the plain sentence. Inside the
+framework's own git checkout the line names `git pull` instead, because there is no installed package to upgrade. A
+failed check is silent. Set `ASRUN_NO_UPDATE_CHECK=1` to switch it off; `NO_COLOR` and `FORCE_COLOR` decide the colors
+as they do everywhere else.
+
+### Migrations
+
+A migration is a change an existing workspace must make when the framework moves it forward: a config entry that
+moved, a file whose shape changed, a dependency range that has to follow the peer dependency. Anything `init --update`
+refreshes by itself is not a migration. The registry is `migrations/index.ts` in the framework package, and the state
+lives in `.asrun.json`:
+
+```json
+"migrations": {"since": "0.7.0", "manual": ["0.8.0-rename-..."]}
+```
+
+`since` is the release the workspace matches. It only moves forward when a migration succeeds, so an interrupted run
+can simply be repeated. A migration marked `auto` runs by itself; one with `manual` steps is printed and remembered
+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.
+
+```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 --to <v>     # stop at that release
+```
+
+`migrate` never installs anything, and refuses to migrate beyond the installed release: the code that applies a
+migration is the installed package. `doctor` warns while migrations or manual steps are outstanding.
+
 ## Workspace
 
 ```bash
-pnpm asrun init [--update] [--force <file>] [--reset-rules] [--root <dir>] [--no-env] [--install [spec]]
+pnpm asrun init [--update] [--force] [--force <file>] [--reset-rules] [--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 reset [--root <dir>] [--dry-run] [--yes] [--state] [--lockfile]
 ```
 
-`init` writes the workspace files; `--update` refreshes only the generated ones. `doctor` checks profiles,
-`tsconfig.json`, `playwright.config.ts`, the generated files, the installed version, the project rule table and the
-skill overrides. Full details in [install.md](./install.md).
+`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).
+`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.
+
+`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.json` and `.claude/skills/**` are never removed. `--state` also removes `.auth/`, `reports/`, `.tmp/`,
+`.explore/`, `test-results/`, `playwright-report/` and `.playwright-mcp/`; `--lockfile` also removes
+`pnpm-lock.yaml`. It lists what it would remove and asks for confirmation (`--yes` skips it, `--dry-run` only
+lists). After it, run `pnpm dlx @asrunjs/asrun init --install` and `pnpm go`.
+
+Full details in [install.md](./install.md).

package/docs/install.md

@@ -8,9 +8,9 @@ and is never edited: a project commits only its own test content.
 
 - **Node.js 22 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, the optional `ffmpeg-static` package is used instead; if neither works, the report lists the videos
-  separately. Not fatal.
+  `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
+  works, the report lists the videos separately. Not fatal.
 - **Claude Code or OpenCode** for the AI steps (make cases, explore, generate, heal). Everything else works without
   them; `pnpm go` warns when neither command is found.
 
@@ -22,9 +22,16 @@ pnpm go
 ```
 
 `init --install` scaffolds the workspace and then adds the dependency. Running `init` first matters on pnpm 12: it
-writes `pnpm-workspace.yaml` with the `allowBuilds` entry (`esbuild` through `tsx`, `ffmpeg-static`), and without it
-`pnpm add` exits with `ERR_PNPM_IGNORED_BUILDS`. An existing `pnpm-workspace.yaml` that lacks the entry gets a note
-instead: add the block by hand (see "Manual install").
+writes `pnpm-workspace.yaml` with the `allowBuilds` entry that `esbuild` needs, and without it `pnpm add` exits with
+`ERR_PNPM_IGNORED_BUILDS`. The same file lists `@asrunjs/asrun` under `minimumReleaseAgeExclude`, so pnpm's 24-hour
+release age does not hold a fresh release back (see
+[troubleshooting.md](./troubleshooting.md#installing)). A `pnpm-workspace.yaml` that already exists gets the entries
+it lacks: `init` adds them before it installs anything.
+
+Optional packages are not part of the framework's dependency graph: a dependency with an install script would make
+`pnpm dlx @asrunjs/asrun` stop at pnpm's build-approval picker, and the dlx sandbox does not read the workspace's
+`allowBuilds`. So `init` installs `ffmpeg-static` into the workspace only when this machine has no ffmpeg, adding its
+`allowBuilds` entry first. `--no-extras` skips that step.
 
 `init` also records `@asrunjs/asrun` (pinned to its own version) in the workspace `package.json`, so `pnpm install`
 installs the framework even without `--install`. When the install step itself fails — `pnpm` is not on `PATH`, the
@@ -35,11 +42,13 @@ registry is unreachable, or a build script is not approved — `init` names the
 
 1. checks Node (22+) and ffmpeg, and warns when no AI CLI is installed;
 2. installs the dependencies and the Chromium browser (`pnpm install` + `playwright install chromium`);
-3. runs `asrun init` (workspace files and `.env`) and `asrun doctor`;
+3. runs `asrun init` (workspace files, `.env`, and the optional packages this machine lacks) and `asrun doctor`;
 4. starts the web UI at http://127.0.0.1:4173 and opens it.
 
 Run it again on any day: the install step then takes seconds, and if the UI is already running it only opens it.
-`pnpm go --no-open` does not open a browser. Set `ASRUN_UI_PORT` to change the port.
+`pnpm go --no-open` does not open a browser; `pnpm go --no-ui` stops after step 3, with the workspace prepared and no
+server running; `pnpm go --dry-run` only prints the workspace, the framework and the `asrun` command it resolved, then
+exits. Set `ASRUN_UI_PORT` to change the port.
 
 The UI is optional: all commands in [commands.md](./commands.md) work without it.
 
@@ -53,22 +62,27 @@ pnpm asrun init
 pnpm go
 ```
 
-If pnpm refuses the build scripts of `esbuild` / `ffmpeg-static`, add this to `pnpm-workspace.yaml` and run the
-install again:
+If pnpm refuses the build script of `esbuild`, or installs the release before `latest`, add this to
+`pnpm-workspace.yaml` and run the install again:
 
 ```yaml
 allowBuilds:
   esbuild: true
-  ffmpeg-static: true
+minimumReleaseAgeExclude:
+  - '@asrunjs/asrun'
 ```
 
+`pnpm asrun init` adds the `allowBuilds` entry of an optional package (for example `ffmpeg-static`) itself, right
+before it installs that package, so this block only has to name what the framework's own dependencies need.
+
 To pin a version:
 
 ```bash
 pnpm add -D @asrunjs/asrun@<version>
 ```
 
-`pnpm asrun init` is safe to run many times: it never overwrites a file the project owns.
+`pnpm asrun init` is safe to run many times: it never overwrites a file the project owns unless `--force` asks for
+it (and `--reset-rules` for the project's rules).
 
 ## What `init` writes
 
@@ -78,7 +92,9 @@ pnpm add -D @asrunjs/asrun@<version>
 | Once | `AGENTS.md`, `CLAUDE.md`, `.mcp.json`, `opencode.jsonc`, `.claude/settings.json`, `tsconfig.json`, `pnpm-workspace.yaml`, `profiles.yaml`, `cases/_template.md`, `package.json` (scripts and devDependencies merged in) | kept |
 
 It also writes the asrun block in `.gitignore`, the `ASRUN_ROOT` line in `.env`, and `.asrun.json` (the marker with
-the framework version and the generated file list).
+the framework version, the migration baseline and the generated file list). It appends the `allowBuilds` entries an
+existing `pnpm-workspace.yaml` lacks, and installs the optional packages this machine lacks (`ffmpeg-static`, only
+when there is no ffmpeg).
 
 Flags:
 
@@ -86,24 +102,54 @@ Flags:
 |---|---|
 | `--root <dir>` | initialize that folder instead of the current one |
 | `--update` | refresh only the generated files |
+| `--force` | overwrite every file init writes, for a clean installation (keeps `profiles.yaml` and `package.json`) |
 | `--force <path>` | overwrite one file init owns (repeatable) |
 | `--reset-rules` | allow `--force` on `AGENTS.md`, `CLAUDE.md` or `.claude/skills/**` |
 | `--no-env` | do not write `.env` |
+| `--no-extras` | do not install the optional packages this machine lacks (`ffmpeg-static`) |
 | `--install [spec]` | also add the dependency (default `@asrunjs/asrun`) |
 
-`AGENTS.md`, `CLAUDE.md` and `.claude/skills/**` belong to the project. `init --force` refuses them without
-`--reset-rules`, so a framework update can never replace a project's rules.
+`AGENTS.md`, `CLAUDE.md` and `.claude/skills/**` belong to the project. `init --force` keeps them unless
+`--reset-rules` is given, so a framework update can never replace a project's rules. `--force` also keeps
+`profiles.yaml` and `package.json`: replace the profiles with `--force profiles.yaml`; `package.json` is only merged
+into, so your scripts and dependencies stay.
 
 ## Update
 
+```bash
+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.
+
+`upgrade` arrives with this release, so a workspace that predates it updates once by hand:
+
 ```bash
 pnpm add -D @asrunjs/asrun@latest
 pnpm asrun init --update
+pnpm asrun migrate
 pnpm asrun doctor
 ```
 
-`init --update` rewrites only the generated files and leaves project rules, case files, values and baselines alone.
-`doctor` tells you when the workspace is behind the installed version.
+After that, `pnpm asrun upgrade` is the command to remember. `init --update` alone only refreshes the generated files:
+it never moves the migration baseline, so a manual install that skipped `migrate` still shows up in `doctor`, and
+`pnpm asrun migrate` fixes it. `init --force` rewrites every file init writes (see the flags above). `doctor` tells
+you when the workspace is behind the installed version, and what is still to migrate.
+
+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.
+
+To go back to an older release, install it yourself and refresh:
+
+```bash
+pnpm add -D @asrunjs/asrun@<version>
+pnpm asrun init --update
+```
 
 There is no folder to move: the framework lives in `node_modules`, which the package manager owns. To change the
 framework itself, `pnpm patch @asrunjs/asrun` (a committed patch).
@@ -116,6 +162,7 @@ Run it after changing profiles, rules or overrides, and after an update. It chec
 - `tsconfig.json`, `playwright.config.ts` (its re-export of the framework config) and the generated files;
 - that `.gitignore` ignores `.auth/` and `reports/`;
 - whether the installed version is behind the package's templates, and whether `dist/` is out of date;
+- the workspace migrations: the baseline in `.asrun.json`, what still applies, and the manual steps left open;
 - the project rule table in `AGENTS.md` §2 (unknown ids, a missing `Effect`, a non-negotiable rule);
 - the framework skills and the project overrides under `.claude/skills/<skill>.md`, and lists the ones it sees.
 
@@ -149,7 +196,7 @@ CLAUDE.md           imports AGENTS.md for Claude Code
 .opencode/commands/ the same commands for OpenCode (it does not read .claude/commands)
 .mcp.json           the playwright-test MCP server for Claude Code
 opencode.jsonc      the same for OpenCode, plus an optional model
-.asrun.json         marker: framework version and the generated file list
+.asrun.json         marker: framework version, migration baseline and the generated file list
 package.json        the workspace scripts (`asrun`, `signin`, ...) and devDependencies
 .env                ASRUN_ROOT (which workspace the commands use) and local settings
 node_modules/@asrunjs/asrun/   the framework (installed dependency; never edited)
@@ -169,6 +216,32 @@ and `pnpm-workspace.yaml`.
 Never commit or share `.auth/` (one saved login per profile, as sensitive as a password), `reports/`, `.tmp/`,
 `.explore/`, `.env` or `node_modules/`. The asrun block of `.gitignore` covers them.
 
+## Reset and reinstall
+
+To get a clean environment without losing the project's test content:
+
+```bash
+pnpm asrun reset            # lists what it removes, then asks
+pnpm dlx @asrunjs/asrun init --install
+pnpm go
+```
+
+`reset` removes `node_modules/` and the files `init` writes: the generated config and commands, `.asrun.json`, the
+asrun block of `.gitignore` and the `ASRUN_ROOT` lines of `.env`. It deletes a once-only file only when it is still
+identical to its template, so a file you edited is kept (and listed). `cases/`, specs and their baselines,
+`profiles.yaml`, `package.json` and `.claude/skills/**` are never removed.
+
+| Flag | Meaning |
+|---|---|
+| `--root <dir>` | reset that folder instead of the current workspace |
+| `--dry-run` | list what would be removed, and change nothing |
+| `--yes` | skip the confirmation (for unattended runs) |
+| `--state` | also remove `.auth/`, `reports/`, `.tmp/`, `.explore/`, `test-results/`, `playwright-report/`, `.playwright-mcp/` |
+| `--lockfile` | also remove `pnpm-lock.yaml`, so the next install resolves the dependencies again |
+
+Without `--yes` it asks you to type `yes`; a run without a terminal refuses instead of removing anything. It refuses
+to run on the framework's own checkout. `--state` removes saved logins, so every profile must be signed in again.
+
 ## Uninstall
 
 ```bash
@@ -176,4 +249,4 @@ pnpm remove @asrunjs/asrun
 ```
 
 Then delete the workspace files you no longer want (`profiles.yaml`, `cases/`, `tests/`, the generated commands and
-configs, `.asrun.json`). They are ordinary files: keep them if another tool still uses them.
+configs, `.asrun.json`). `pnpm asrun reset` does most of that; keep the files if another tool still uses them.