@asrunjs/asrun 0.7.0 → 0.9.0

package/docs/agents/framework-dev.md

@@ -66,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
@@ -164,8 +232,10 @@ Every lead, label and tooltip is written for the person using the UI, never for
 
 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 `vX.Y.Z` and publishes to
-npm.
+`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
@@ -174,8 +244,8 @@ npm.
 - `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=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.
+  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.
 

package/docs/ai-workflow.md

@@ -8,16 +8,25 @@ so the procedure lives in one place and a project can refine it (see
 | Command | What it does |
 |---|---|
 | `/make-case <notes-or-path>` | Turn raw notes into case documents. Optional step. |
-| `/explore-case <case-id> <env> [--attended]` | Open the real pages and write what they show into the case. |
+| `/explore-case <case-id> <env> [--attended] [--profiles a,b]` | Open the real pages and write what they show into the case. |
 | `/gen-spec <case-id> <env> [--force]` | 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>]` | Diagnose a failing spec from its last report and fix it. |
+| `/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. |
 
 The environment is **required** by every command except `/make-case`, which does 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.
+
 Every command ends with `RESULT: ready` or `RESULT: needs-input`. `needs-input` means somebody has to answer a
 question in the case file (or, in the web UI, in the job's **Answer** sheet). A one-shot run cannot ask in the chat:
 it writes its questions into the case and stops.
 
+A one-shot run is a **build** run: it writes the case or the spec, never a plan. AsRun starts OpenCode with
+`--agent build`, because OpenCode keeps the agent (build or plan) on the session and a plan session would only propose
+changes and ask a question nobody can answer. Whatever mode a run finds itself in, it still ends with the `RESULT:`
+line: a run that was not allowed to write files (plan mode, a read-only sandbox) is `needs-input`, not a plan and a
+question.
+
 In the web UI you never type a command: choose the step in a case toolbar and press **Run AI**, or paste notes on
 **Cases > From memo**. The UI runs the selected AI tool and streams the output into the Jobs bar.
 
@@ -55,6 +64,11 @@ publishes, shares or deletes anything, in staging or in production. It:
 - lists the candidates instead of guessing a target (`## Targets`);
 - edits the case file only (plus reference screenshots under `.explore/targets/`).
 
+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.
+
 **To accept the suggestion, delete the whole block.** **To answer, write after `Answer:`.** Then run the command
 again. In the web UI, the run's **What to do next** bar offers **Answer**: the question list, an answer box,
 **Use the suggested defaults** and **Generate spec**. A continued job keeps the same conversation and permissions, and
@@ -92,8 +106,14 @@ Skip this for a `login: none` case. Sessions are per profile; see [profiles.md](
 ```
 
 The agent replays the case on the real pages with your saved sessions (it never writes data) and writes
-`tests/header-logo.spec.ts`. It fills the case's `## Values` for the profiles it explored and checks the files
-(`pnpm typecheck`, `pnpm case:check`; `pnpm spec:lint <case-id>` must have no failure).
+`tests/header-logo.spec.ts`. It fills the case's `## Values` for the profiles the case holds information for and checks
+the files (`pnpm typecheck`, `pnpm case:check`; `pnpm spec:lint <case-id>` must have no failure).
+
+Its profile scope comes from the case, not from a selection: every profile id the case names — the keys of
+`## Values`, a target card's `Reference <profile-id>:` line, an observation — plus `default`. That is why one run per
+subset adds up: explore A and B first and C later, and `/gen-spec` covers all three. A profile the case says nothing
+about runs on `default` alone, and the report names it. A profile that is not logged in is not dropped: its part is
+written from the case and marked `not verified on the page`.
 
 It does **not** run the spec and does **not** create screenshot baselines: running is a separate step (6).
 
@@ -125,7 +145,7 @@ profile. Baselines are the source of truth for pixel checks.
 Then run all profiles and read the report: the video of each test, screenshots on failure, and the trace with the page
 and the network requests. See [commands.md](./commands.md) for filters and baselines.
 
-## Healing a failing spec
+## Healing or refining a spec
 
 ```
 /heal-spec header-logo staging
@@ -133,14 +153,15 @@ and the network requests. See [commands.md](./commands.md) for filters and basel
 
 or **Heal spec** in the case toolbar, or **Heal this failure** on a failed result of the Reports page.
 
-The agent decides whether the test needs updating or whether it found a real product problem. It **never** edits an
-expectation just to make a failure disappear.
+The command does two jobs: it repairs a spec that fails, and it refines a case and its spec when you ask for an
+improvement. A passing last run is not a reason to refuse a request. It decides whether the test needs updating or
+whether it found a real product problem, and it **never** edits an expectation just to make a failure disappear.
 
 - The environment is required. Only the profiles that are logged in there run (`--logged-in` leaves the others out
   instead of failing them).
-- The web UI first opens a dialog: which profiles to heal (every logged-in profile ticked) and an optional text box
-  for what you want healed, with evidence or clues. The text is stored in `.tmp/hints/` and passed as `--hints`.
-  Clues guide the diagnosis; they never lower the bar for a product finding.
+- The web UI first opens a dialog: which profiles to run (every logged-in profile ticked) and an optional text box
+  for what should be repaired or improved, with evidence. The text is stored in `.tmp/hints/` and passed as `--hints`.
+  It guides the work; it never lowers the bar for a product finding.
 - It reads the existing report first:
 
   ```bash
@@ -149,7 +170,13 @@ expectation just to make a failure disappear.
 
   It prints status, failed step, error, call log and screenshots per profile, and whether the report is fresh or
   stale. The case is run again only when there is no report, the report is stale, it does not explain the failure, or
-  a clue has to be checked. After editing the spec, it runs the case once to confirm.
+  a request has to be checked. It reads the pages (read-only) when a change has to be judged on them, and it never
+  performs a step that writes data. After editing the spec, it runs the case once to confirm.
+- The case is the source of truth: a change to a step, an expectation, a value or a target is written into the case
+  first, then into the spec. A large change regenerates the spec from the case.
+- **Review gate.** If the change leaves an open question or an unconfirmed observation in the case, healing stops
+  before the spec: you review the case, answer or accept what it asks, and run `/explore-case` again. The spec is
+  generated after that, not before.
 
 ## Why a generated spec can be trusted
 

package/docs/commands.md

@@ -7,8 +7,10 @@ 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>]` |
@@ -168,19 +170,87 @@ 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] [--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, 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`.
+`--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 and the skill overrides.
+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/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,11 +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`. 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)). An existing `pnpm-workspace.yaml` that lacks either 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
@@ -37,7 +42,7 @@ 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.
@@ -57,17 +62,19 @@ pnpm asrun init
 pnpm go
 ```
 
-If pnpm refuses the build scripts of `esbuild` / `ffmpeg-static`, or installs the release before `latest`, add this to
+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
@@ -85,7 +92,9 @@ it (and `--reset-rules` for the project's rules).
 | 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:
 
@@ -97,6 +106,7 @@ Flags:
 | `--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` keeps them unless
@@ -106,15 +116,40 @@ 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.
-`init --force` rewrites every file init writes (see the flags above). `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).
@@ -127,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.
 
@@ -160,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)

package/docs/theme-guide.html

@@ -257,6 +257,29 @@
   .side .item { padding: 8px 16px 8px 12px; border-bottom: 1px solid var(--line); border-left: 4px solid transparent; font-family: var(--mono); font-size: 14px; }
   .side .item.selected { background: var(--theme-bg); border-left-color: var(--theme); }
 
+  /* Filter bar (mirror components/filter-chips.tsx and components/search-field.tsx). */
+  .filters { display: flex; flex-wrap: wrap; align-items: center; gap: 4px; }
+  .filters .group-label { margin-right: 2px; font-size: 12px; color: var(--ink-3); }
+  .filter-chip {
+    display: inline-flex; align-items: center; gap: 4px; height: 24px; padding: 0 6px; border-radius: 2px;
+    background: var(--card); color: var(--ink-2); font-size: 12px; box-shadow: inset 0 0 0 1px var(--line-mid);
+  }
+  .filter-chip .count { color: var(--ink-3); }
+  .filter-chip.on {
+    background: var(--theme-btn); color: #fff; font-weight: 500;
+    box-shadow: inset 0 0 0 1px var(--theme-btn);
+  }
+  .filter-chip.on .count { color: rgb(255 255 255 / .75); }
+  .filter-chip.on.production { background: var(--jiang); box-shadow: inset 0 0 0 1px var(--jiang); }
+  .filter-chip.on.staging { background: var(--cheng); box-shadow: inset 0 0 0 1px var(--cheng); }
+  .filter-chip.on.other { background: var(--gold-deep); box-shadow: inset 0 0 0 1px var(--gold-deep); }
+  .filter-search { position: relative; width: 260px; max-width: 100%; }
+  .filter-search svg { position: absolute; left: 8px; top: 50%; transform: translateY(-50%); color: var(--ink-3); }
+  .filter-search .fake {
+    display: flex; align-items: center; height: 32px; padding: 0 8px 0 28px; border: 1px solid var(--line-mid);
+    border-radius: 4px; background: #fff; color: var(--ink-3); font-size: 14px;
+  }
+
   .seal-stamp {
     display: inline-flex; align-items: center; justify-content: center; width: 28px; height: 28px; border-radius: 3px;
     background: var(--seal); color: var(--paper); font-family: var(--serif); font-weight: 400; font-size: 16px; line-height: 1;
@@ -302,6 +325,7 @@
     <a href="#badges">Badges</a>
     <a href="#action-colors">Action colors</a>
     <a href="#dropdowns">Dropdowns</a>
+    <a href="#filter-bars">Filter bars</a>
     <a href="#multi-value">Multi-value fields</a>
     <a href="#icons">Icons</a>
     <a href="#tooltips">Tooltips</a>
@@ -503,6 +527,7 @@
         <tr><td><code>info</code> (light blue)</td><td>A view toggle that must be easy to find, not an action on data: "Full screen" / "Restore" in the Jobs drawer bar. Blue = read-only.</td></tr>
         <tr><td><code>secondary</code> (white)</td><td>Everything else: Verify, Visit, Discard, Copy, navigation.</td></tr>
         <tr><td><code>danger</code> (white, red text)</td><td>Cancel a running job, destructive confirmations.</td></tr>
+        <tr><td><code>invalid</code> (red field)</td><td>A control that is required and still empty, drawn as a button because it opens a panel instead of a native list (the environment picker of the case toolbar). The same red as an invalid dropdown; it is not an action.</td></tr>
       </tbody>
     </table>
     <p class="small muted">Hover lifts the button 1px; disabled is 50% opacity with no shadow. With an icon, add <code>gap-1.5</code> to the button.</p>
@@ -522,7 +547,7 @@
       <tbody>
         <tr><td><span class="badge green">green</span></td><td>ok: Logged in</td><td>Succeeded</td></tr>
         <tr><td><span class="badge red">red</span></td><td>expired, missing</td><td>Failed</td></tr>
-        <tr><td><span class="badge amber">amber</span></td><td>unverified, error</td><td>Needs your input (an AI run that ended with <code>RESULT: needs-input</code>)</td></tr>
+        <tr><td><span class="badge amber">amber</span></td><td>unverified, error</td><td>Needs your input (an AI run that ended with <code>RESULT: needs-input</code>) or No result (a run that printed no <code>RESULT:</code> line at all)</td></tr>
         <tr><td><span class="badge blue">blue</span></td><td>-</td><td>Running</td></tr>
         <tr><td><span class="badge gray">gray</span></td><td>-</td><td>Cancelled</td></tr>
       </tbody>
@@ -584,7 +609,7 @@
       <tbody>
         <tr><td><code>explore-case</code></td><td>blue (qing)</td><td>Edits only the case file (wording, observations, open questions, inputs). The agent only reads pages; you do the steps that write data.</td></tr>
         <tr><td><code>gen-spec</code></td><td>amber (gold)</td><td>Writes: creates the spec and fills the case's <code>## Values</code>. Does not run the tests.</td></tr>
-        <tr><td><code>heal-spec</code></td><td>red (seal)</td><td>Rewrites an existing spec and runs the tests.</td></tr>
+        <tr><td><code>heal-spec</code></td><td>red (seal)</td><td>Repairs the spec or refines the case and the spec, then runs the tests.</td></tr>
       </tbody>
     </table>
     <p class="small muted">
@@ -600,6 +625,14 @@
       <code>Select</code> is a button that draws its own list under it, in a <code>card-popup</code> panel, which is what
       gives every dropdown the same raised look.
     </p>
+    <p class="small muted">
+      Two controls put their label inside the button and open a panel with a title rather than a bare list: the
+      environment picker of the case toolbar (<code>Env: staging</code>, <code>components/env-picker.tsx</code>) and the
+      profile picker beside it (<code>Profiles: 2 of 3</code>, <code>components/profile-picker.tsx</code>). They are
+      buttons because their list needs a title and a line of explanation, not a <code>Select</code>; they keep this
+      section's height, <code>card-popup</code> panel, keyboard and click-outside rules. Do not turn them back into a
+      <code>Select</code> that repeats the label on every row.
+    </p>
     <div class="demo">
       <span class="select"><span class="fake">staging</span><svg class="chev" xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"></polyline></svg></span>
       <span class="select focus"><span class="fake">staging</span><svg class="chev" xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><polyline points="6 9 12 15 18 9"></polyline></svg></span>
@@ -654,6 +687,60 @@
       </tbody>
     </table>
 
+    <h3 id="filter-bars">Filter bars</h3>
+    <p>
+      A list that can get long (the profiles of the workspace, the profiles of a case's Values table) gets a filter bar
+      above it: <code>SearchField</code> and <code>FilterChips</code> from <code>ui/web/src/components/</code>. They are
+      controls only; the page decides what a value means and filters its own rows.
+    </p>
+    <div class="demo" style="display:block">
+      <div class="filter-search" style="margin-bottom:8px">
+        <svg xmlns="http://www.w3.org/2000/svg" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><circle cx="11" cy="11" r="8"></circle><line x1="21" y1="21" x2="16.65" y2="16.65"></line></svg>
+        <span class="fake">atpil</span>
+      </div>
+      <div style="display:flex;flex-wrap:wrap;gap:8px 16px">
+        <div class="filters">
+          <span class="group-label">Env</span>
+          <span class="filter-chip">All <span class="count">17</span></span>
+          <span class="filter-chip on production">PRODUCTION <span class="count">7</span></span>
+          <span class="filter-chip on staging">STAGING <span class="count">8</span></span>
+          <span class="filter-chip">SANDBOX <span class="count">2</span></span>
+        </div>
+        <div class="filters">
+          <span class="group-label">Tag</span>
+          <span class="filter-chip">All <span class="count">17</span></span>
+          <span class="filter-chip on">atp <span class="count">6</span></span>
+          <span class="filter-chip">compass <span class="count">4</span></span>
+          <span class="filter-chip">corp <span class="count">4</span></span>
+        </div>
+      </div>
+      <p class="small muted" style="margin:8px 0 0">Showing 6 of 17 profiles · <span style="text-decoration:underline">Clear filters</span></p>
+    </div>
+    <p class="small muted">
+      Search "atpil" with the dashes left out, both environments pressed and one tag: the two groups are combined with
+      AND.
+    </p>
+    <pre class="card mono" style="overflow:auto">import {SearchField} from '../components/search-field';
+import {FilterChips} from '../components/filter-chips';
+
+&lt;SearchField value={query} onChange={setQuery} ariaLabel="Search profiles" placeholder="Search id, name..." /&gt;
+&lt;FilterChips label="Env" selected={envFilter} onChange={setEnvFilter} allCount={profiles.length}
+  options={envs.map((env) =&gt; ({value: env, label: env.toUpperCase(), count: countOf(env), tone: envFillClass(env)}))} /&gt;</pre>
+    <table>
+      <thead><tr><th>Part</th><th>Rule</th></tr></thead>
+      <tbody>
+        <tr><td>Search</td><td>One <code>SearchField</code> at the top. It looks in id, name, account, environment, tags and address; every word of the query must match one of them. A compact copy without <code>-</code>, <code>_</code>, <code>.</code> or spaces lets <code>atpil</code> find <code>atp-il-staging</code>.</td></tr>
+        <tr><td>Groups</td><td>One <code>FilterChips</code> per kind of value (environment, tag). Inside a group a row matches <b>any</b> pressed value; the groups are combined with <b>AND</b>. An empty group filters nothing.</td></tr>
+        <tr><td>All</td><td>The first chip of a group clears that group only. It is pressed while the group has no selection, so "no filter" can always be told from "everything selected".</td></tr>
+        <tr><td>Counts</td><td>Each option shows how many rows it would leave, and <code>All</code> shows the group's total. Counts come from the unfiltered list, so they do not dance while a value is pressed.</td></tr>
+        <tr><td>Pressed look</td><td>Neutral chips take the page accent (<code>theme-btn</code>, white text). Environment chips pass <code>envFillClass(env)</code>, the same solid marker as <code>EnvBadge</code>, so color means the environment here too.</td></tr>
+        <tr><td>State</td><td>The chip is the button: <code>aria-pressed</code>, a tooltip with its name (and "pressed" while on), and the count as a second, quieter part of the label.</td></tr>
+        <tr><td>Feedback</td><td>While a filter is active, show <code>Showing N of M</code> and <b>Clear filters</b>. When nothing matches, the empty state repeats the clear action instead of leaving a blank table.</td></tr>
+        <tr><td>Not remembered</td><td>A filter is a way of looking, not a setting: do not put it in <code>localStorage</code>. A reload shows everything, so nothing looks missing after lunch.</td></tr>
+        <tr><td>In the case panel</td><td>The Values table adds a two-button <b>Rows: Keys / Profiles</b> switch beside the search as soon as a case names two profiles, and shows the search and the environment chips only when it names more than three. The filters and the switch belong to that case; opening another case starts unfiltered.</td></tr>
+      </tbody>
+    </table>
+
     <h2 id="multi-value">Multi-value fields</h2>
     <p>
       A field whose value is a list is never a <a href="#dropdowns">Dropdown</a> plus an "Add" text input: that mixes a
@@ -829,11 +916,12 @@
     </p>
     <p class="muted">
       The preview block that holds the editor caret is shaded with <code>theme-bg</code> at 60% and a 2px <code>theme</code> left
-      border (an overlay, so it follows the page theme). The editor and the preview scroll together and a click in the preview
-      moves the caret; the logic is in <code>ui/web/src/lib/preview-sync.ts</code>.
+      border (an overlay, so it follows the page theme). The overlay paints <b>behind</b> the text, never over it: the
+      highlighted block keeps its own text color instead of looking washed out. The editor and the preview scroll together
+      and a click in the preview moves the caret; the logic is in <code>ui/web/src/lib/preview-sync.ts</code>.
     </p>
     <p class="muted">
-      The previous / next buttons of the case toolbar move the caret to the next marker and blink that marker for a moment in
+      The previous / next buttons at the right end of the editor toolbar move the caret to the next marker and blink that marker for a moment in
       both panes (<code>cm-kw-flash</code> in the editor, <code>kw-flash</code> over the <code>&lt;mark&gt;</code> of the
       document): <code>gold-glow</code> at 65% behind it and a 2px <code>dai-deep</code> ring with a wider
       <code>gold-glow</code> glow around it, the ring blinking on and off three times (0.45&nbsp;s each), then it goes away.