@rehearsal-db/core 1.0.0 → 1.0.2

package/docs/architecture.md

@@ -70,6 +70,24 @@ typed registry and produce the same result contract:
 Command handlers receive an explicit context containing parsed flags, selected config,
 guided state, and session-local caches. They return a rendered, text, or silent result;
 only the shared output boundary creates JSON envelopes or writes final human output.
+`runtime/migration_failure.mts` owns bounded provider-envelope SQLSTATE recognition,
+fixed classification/remediation and closed safe diagnostic validation. Target drivers
+never forward SQL or provider error details. The manager summary reconstructs that
+fixed diagnostic across the child-process boundary; CLI JSON and private operation
+history expose the same projection. Activity adds a separate `recentFailures` list,
+leaving existing strict progress/recent receipt shapes unchanged for old clients.
+The optional `source` projection is owned by `runtime/migration_failure_source.mts`.
+For individually dispatched PostgreSQL files, it identifies the attempted execution
+input by its reviewed filename, exact SHA-256 and baseline/candidate kind. The driver
+hashes the bytes it loads before dispatch; changed reviewed bytes refuse execution.
+Only a safe project-relative candidate path may be included, never an absolute path;
+baseline inputs keep that path null. This is not attribution of the failing SQL's actual
+origin: included scripts, functions and triggers can fail elsewhere. SQL line and column
+remain null. Supabase batch execution currently supplies no file attribution, and
+ambiguous or unavailable evidence is not inferred from candidate count or provider text.
+`cli/failure_output.mts` preserves the outer category and cleanup warning when a
+stack failure wraps the original migration error. It projects only a validated fixed
+diagnosis from at most four original-error wrappers, never cleanup siblings or causes.
 Session caches never appear in the public parsed-flags type.
 Owned child output has a byte boundary. If a process floods it, Rehearsal sends TERM
 and forcibly reaps only that owned process group after one second; a child ignoring
@@ -129,14 +147,18 @@ Each scenario remains independently runnable through its `test:fixture:*` script
 complete release gate runs every catalog entry against the same immutable tarball and
 writes its version, SHA-256, tool environment, commands, timings, and results under
 `test-results/release-gate/`.
+The existing Supabase scenario includes native syntax and populated-row constraint
+failures, fixed public error/history diagnostics, reviewed corrections and independent
+data/Storage preservation checks. It does not infer a rollback from a failed migration.
 
 ## Runtime lifecycle
 
 `runtime/lifecycle_engine.mts` owns the target-neutral lifecycle contract. Both
 PostgreSQL and Supabase use it to dispatch commands, verify active baseline inputs,
 calculate and confirm the exact migration set, write target-bound receipts, validate
-runtime markers, and roll back a failed reset or migration without hiding the original
-failure.
+runtime markers, and attempt owned failure cleanup without hiding the original error.
+That cleanup can remove the disposable runtime; a failure message does not establish a
+SQL transaction rollback, restoration of sandbox edits, or successful resource removal.
 
 The files in `src/targets/` remain drivers. They prove ownership before deleting local
 resources and implement only the behavior that genuinely differs: Docker PostgreSQL
@@ -144,6 +166,14 @@ containers and SQL setup on one side; Supabase CLI, Auth, Storage, and generated
 on the other. An ordinary `stop` never enters rollback or discard, so later `start`
 preserves the sandbox database and Storage contents.
 
+CLI command completion and database lifecycle are separate. A successful `run` can finish
+and release its project lock while the configured keep-until-stop database remains
+running. The project-owned CLI proof has its own primary `application-proof` stage;
+HTTP readiness is optional and is not a prerequisite for a database-only proof. Public
+operation receipts record those past stages, not fresh proof of subsequently changed
+configuration, baseline or migration bytes. Editor presentation consumes that evidence
+without interpreting database liveness as an active command or successful proof.
+
 Repository contracts keep each target driver at 900 lines or fewer and the shared
 lifecycle engine at 300 lines or fewer. A new database target must use this lifecycle
 boundary rather than copying an existing driver's orchestration.

package/docs/commands.md

@@ -238,6 +238,41 @@ provides a stable category, code, safe message, suggestions, diagnostic ID, and
 context under `error`. Callers should use the category and code for decisions and show
 the message and suggestions to people.
 
+Failed migration execution additionally supplies `error.context.migrationFailure`:
+schema version `1`, provider (`postgresql` or `supabase`), classification (`syntax`,
+`schema`, `constraint`, `permission`, `connectivity`, `timeout_or_cancel`, or `unknown`),
+nullable `sqlState`, evidence (`provider_sqlstate`, `unavailable`, or `ambiguous`),
+fixed `summary` and fixed `suggestions`. Classification uses recognized native SQLSTATE
+envelopes, never SQL-text guessing. Unknown evidence does not establish syntax failure.
+Direct manager failures separately name the target in `error.context.target`; raw
+SQL, row values, provider DETAIL, absolute paths and connection strings are not
+included. Optional attempted-input metadata is described below; it does not locate
+the failing SQL statement. Existing exit codes and `MANAGER_RUN_FAILED` / `MANAGER_MIGRATE_FAILED`
+codes are unchanged. If cleanup also fails, the outer failure keeps its existing
+category, exit and cleanup warning while retaining the original fixed migration
+diagnosis. A diagnosis is not borrowed from a cleanup error, and is not evidence that
+cleanup completed.
+
+When PostgreSQL submits one known migration file, the diagnostic may include a closed
+`source` object: schema version `1`, `kind` (`baseline` or `candidate`), `filename`,
+`sha256`, nullable `workspaceRelativePath`, `line: null`, `column: null`, and
+`evidence: "owned_execution_input"`. The loaded bytes must match the reviewed hash.
+This identifies the attempted input, not the exact origin of failing SQL; statements,
+functions and included files can fail elsewhere. No statement counting, provider caret,
+or batch candidate count is converted into a source position. Baseline snapshot paths
+are not exposed; unavailable or ambiguous attribution is omitted, including the
+current Supabase batch path. The editor opens a project-local input only after fresh
+containment, regular-file, identity and exact-byte checks; a changed file needs manual
+review instead of a stale link.
+
+`activity --json` may also provide `data.recentFailures`: up to 20 entries with
+`operationId` and the same `diagnostic`, joined to a failed receipt in `data.recent`.
+Missing means an older producer; `null` means private history is unavailable; `[]`
+means no retained migration diagnosis. These are recent observations, not current
+runtime verification. Existing `recent[]` and progress object fields are unchanged,
+so older clients can ignore the new top-level projection. The local owner-only history
+stores only this fixed safe projection, not arbitrary errors or terminal output.
+
 Invalid positive-integer settings and rejected proposal structure or fields use
 `configuration_invalid` with code `CONFIGURATION_INVALID` (exit `2`), including
 baseline-retention settings and fields that require manual review. They are not

package/docs/getting-started.md

@@ -5,6 +5,54 @@ your computer. Normal setup and rehearsal commands never connect to a hosted dat
 
 Want to experiment first? Use the [safe hands-on tutorial](tutorial.md).
 
+## OS-specific setup files (optional)
+
+Separate setup folders are available for
+[Windows / WSL 2](https://github.com/Ddupasquier/rehearsal-db/tree/main/installers/windows),
+[macOS](https://github.com/Ddupasquier/rehearsal-db/tree/main/installers/macos) and
+[Linux](https://github.com/Ddupasquier/rehearsal-db/tree/main/installers/linux).
+They are readable helpers, not native executables or bundled Node/Docker installers.
+Existing Node.js 24 or 26 is required. The default only checks an existing project;
+installation needs an explicit option and does not start a database. Review the
+[shared behavior and release availability](https://github.com/Ddupasquier/rehearsal-db/blob/main/installers/README.md)
+before choosing an install option. An exact core 1.0.2 install requires that version to
+be published; a checked-in helper is not proof of publication.
+
+### Windows: use a WSL 2 Linux workspace
+
+The Windows compatibility route is Linux execution inside **WSL 2**, not a native
+PowerShell/Command Prompt database runtime. Core 1.0.1 and extension 0.1.21 make that
+boundary explicit; native Windows version/help/discovery do not authorize runtime work.
+
+1. Follow Microsoft's [WSL installation guide](https://learn.microsoft.com/en-us/windows/wsl/install)
+   to prepare a WSL 2 Linux distribution, such as Ubuntu 24.04. Do not use WSL 1.
+2. Clone or open the project inside the distribution's Linux home directory, such as
+   `/home/your-name/projects/app`. Do not keep the runtime project under `/mnt/c`, a
+   Windows share or a Windows-mounted drive. Rehearsal does not relocate your files.
+3. Install a supported **Linux** Node/npm and a Docker-compatible Linux engine in that
+   environment. Docker Engine in WSL or an already configured Docker Desktop WSL
+   integration are user-controlled setup choices; Rehearsal does not install or license
+   Docker Desktop for you. In the Linux terminal, check:
+
+   ```bash
+   node -p "process.platform"
+   pwd
+   docker info --format '{{.OSType}}'
+   ```
+
+   Both platform results must be `linux`, and `pwd` must be in the Linux filesystem.
+
+4. For editor use, install Microsoft's **WSL** extension, then run `code .` from that
+   Linux project directory. Confirm the VS Code window says **WSL** in its remote
+   indicator, and install Rehearsal into **WSL**, not only the Windows-side extension host.
+5. Continue below from that Linux terminal. Keep the existing baseline, approval and
+   local-only checks; do not substitute a hosted database to make setup pass.
+
+WSL is a compatibility preview. A real WSL PostgreSQL fixture and a native Remote-WSL
+editor walkthrough are different evidence; do not infer the latter from Linux unit
+tests. Supabase/Auth/Storage in WSL and other remote hosts remain unclaimed until their
+own checks pass. See the [complete platform boundary](https://github.com/Ddupasquier/rehearsal-db/blob/main/COMPATIBILITY.md#operating-systems-and-execution-location).
+
 ## 1. Check the required tools
 
 You need Node.js 22, 24, or 26, npm, and a running Docker-compatible engine. Node.js 24

package/docs/index.md

@@ -12,6 +12,11 @@ Rehearsal catches those problems before deployment. It restores a reviewed, sani
 baseline into a disposable local PostgreSQL or Supabase environment, applies only the
 exact migrations you approve, and runs your application's own proof.
 
+The [CLI is free and MIT-licensed](https://www.npmjs.com/package/@rehearsal-db/core).
+Prefer clicks to commands? [Install the free VS Code Starter preview](vscode.md).
+All features included in its Starter-licensed releases are free indefinitely, with no
+account, payment card, or trial period.
+
 | Empty-database tests miss…                        | Rehearsal exercises…                                      |
 | ------------------------------------------------- | --------------------------------------------------------- |
 | old rows and edge cases                           | a reviewed, production-shaped baseline                    |
@@ -23,15 +28,16 @@ exact migrations you approve, and runs your application's own proof.
 You do not need to read everything before your first rehearsal. Start with the outcome
 you want, then follow the links when a term or safety check is new.
 
-| I want to…                              | Go here                                                           |
-| --------------------------------------- | ----------------------------------------------------------------- |
-| Set up my own project                   | [Getting started](getting-started.md)                             |
-| Try Rehearsal without touching my app   | [Hands-on tutorial](tutorial.md)                                  |
-| Understand what makes a copy safe       | [Baselines](baselines.md) and [Sanitization](sanitization.md)     |
-| Look up a command or setting            | [CLI commands](commands.md) and [Configuration](configuration.md) |
-| Reduce Docker and Supabase resource use | [Container runtime lifecycle](runtime-lifecycle.md)               |
-| Add editor and compiler type checks     | [TypeScript](typescript.md)                                       |
-| Fix something that did not work         | [Troubleshooting](troubleshooting.md)                             |
+| I want to…                               | Go here                                                           |
+| ---------------------------------------- | ----------------------------------------------------------------- |
+| Set up my own project                    | [Getting started](getting-started.md)                             |
+| Use the free visual workbench in VS Code | [Install VS Code Starter](vscode.md)                              |
+| Try Rehearsal without touching my app    | [Hands-on tutorial](tutorial.md)                                  |
+| Understand what makes a copy safe        | [Baselines](baselines.md) and [Sanitization](sanitization.md)     |
+| Look up a command or setting             | [CLI commands](commands.md) and [Configuration](configuration.md) |
+| Reduce Docker and Supabase resource use  | [Container runtime lifecycle](runtime-lifecycle.md)               |
+| Add editor and compiler type checks      | [TypeScript](typescript.md)                                       |
+| Fix something that did not work          | [Troubleshooting](troubleshooting.md)                             |
 
 ## The short version
 

package/docs/releasing.md

@@ -95,23 +95,27 @@ than seven days or in the future. Public fields and timestamps must still match
 bypass metadata is hidden; an explicitly malformed or nonempty bypass list always
 refuses publication.
 
-The prepare job prints an exact approval comment in its summary. Independently check
-the live no-bypass settings and accepted artifact checksum, then paste the comment into
-**Review deployments → npm** and approve manually. Before publishing or repairing
-tags, the workflow reads GitHub's actual approval history and requires the configured
-owner's authenticated review for that npm environment. The comment binds the operation,
-run ID, run attempt, source commit, artifact SHA-256 and settings-record SHA-256.
-GitHub may store the form's line breaks as CRLF instead of LF. The checker treats
-those two encodings as equivalent; it does not trim whitespace or change any field.
-An approval copied from another artifact, run or attempt is refused. Rerun the whole
-workflow after failure so preparation prints a new attempt-bound comment; do not reuse
-an earlier comment when rerunning only the mutation job.
-
-The record alone is never authorization. This mechanism relies on the owner's fresh
-settings review and GitHub's reported timestamps; timestamps are not cryptographic
-proof of every hidden setting change. No settings check eliminates a subsequent
-administrator change or check-to-use race. Keep the npm environment's no-bypass human
-gate enforced. See [GitHub's ruleset metadata boundary](https://docs.github.com/en/rest/repos/rules#get-a-repository-ruleset)
+The prepare job displays the exact package version, SHA-256, source commit and run
+in its summary. Review the candidate and passed checks, then choose **Review
+deployments → npm → Approve and deploy**. That ordinary GitHub approval is the
+publication authorization: no separate chat approval, secret phrase or pasted block
+is required. Comments are optional.
+
+GitHub's enforced, no-bypass `npm` environment admits the publishing job only after
+its protection rules pass. The workflow also reads this run's actual review history
+to corroborate the configured human owner's approval for the exact npm environment.
+That history does not identify an approval's run attempt or verify artifact bytes;
+the workflow independently checks the prepared tarball's hashes before publication,
+and freshly downloads/checks registry bytes before tag repair. Reruns keep the same
+source/ref and remain subject to GitHub's environment controls; old review text is
+never presented as proof of new bytes or a fresh attempt.
+
+The unsigned settings record remains a bounded drift check, not authorization or
+cryptographic proof of current hidden bypass settings. Refresh its owner observation
+when stale or changed; never advance its timestamp without reading the settings.
+No settings check eliminates a later administrator change or check-to-use race.
+See [GitHub's deployment review](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/review-deployments),
+[ruleset metadata boundary](https://docs.github.com/en/rest/repos/rules#get-a-repository-ruleset)
 and [workflow approval history](https://docs.github.com/en/rest/actions/workflow-runs#get-the-review-history-for-a-workflow-run).
 
 Keep customer evidence, credentials, runtime data and the internal tracker out of public
@@ -137,11 +141,12 @@ release-source migration.
 5. Change `private` to `false` only in the reviewed release change.
 6. Record the exact tarball filename, SHA-1, SHA-256, allowlisted files, unpacked size,
    executable, declared runtime dependency inventory, and dependency audit result.
-7. Obtain explicit publication authorization for that exact version and artifact.
-8. Merge the approved release commit through protected `main` and create the exact
+7. Review the release change and its exact artifact evidence.
+8. Merge the reviewed release commit through protected `main` and create the exact
    `v<package-version>` tag and GitHub release.
-9. Review and approve the protected `npm` deployment only after its prepare job matches
-   the approved version and checksum, using its exact approval comment.
+9. Authorize publication once, in the protected `npm` deployment review, after its
+   prepare job matches the tested version and checksum. No comment or chat approval
+   is required.
 10. Verify public visibility, ownership, provenance, registry SHA-1, README rendering,
     exact-version clean installation, CLI execution, signatures, and the unrelated
     installed Docker fixture. Allow up to six minutes for a first package to propagate
@@ -199,6 +204,5 @@ package or select a different version. The `npm` environment must supply the ver
 human approval gate; a workflow reference to that environment is not sufficient.
 
 Creating the repository, passing CI, extracting the engine, merging a release branch,
-or creating a tag does not authorize npm publication. Publication requires explicit
-authorization for the exact packed artifact, and the protected GitHub environment
-supplies the final human gate.
+or creating a tag does not authorize npm publication. The protected GitHub deployment
+review supplies the single human authorization for the exact displayed artifact.

package/docs/roadmap.md

@@ -1,8 +1,13 @@
 # Next steps
 
-Rehearsal supports guided Supabase and ordinary PostgreSQL migration rehearsals. The
-current development track removes the need for consumer-owned Rehearsal engines while
-keeping application meaning and privacy decisions project-owned.
+Rehearsal core **1.0.0 is available on
+[npm](https://www.npmjs.com/package/@rehearsal-db/core)** for guided Supabase and
+ordinary PostgreSQL migration rehearsals. The [free VS Code Starter preview](vscode.md)
+adds a visual workbench. Neither requires a purchase or account.
+
+The standalone workflow keeps the rehearsal engine in the package while application
+meaning and privacy decisions remain project-owned. The sequence below explains its
+dependencies, not a list of features withheld from the published release.
 
 ## Standalone workflow
 

package/docs/stability.md

@@ -1,7 +1,10 @@
 # Stability and the first stable release
 
-Rehearsal leaves beta when the workflow it already promises is dependable. Stable
-`1.0.0` does not require every planned database, desktop interface, or paid feature.
+Rehearsal core **1.0.0 is published** on
+[npm](https://www.npmjs.com/package/@rehearsal-db/core). This page defines its
+compatibility promise and the verification policy for releases; it is not an
+unfinished launch checklist. Stable core does not require every planned database,
+editor interface, or paid feature.
 
 ## What becomes a compatibility promise
 
@@ -63,8 +66,9 @@ ready. The sequence below is policy, not a claim that its checks have passed.
    do not relabel old or unavailable manual checks as new results. No minimum number
    of calendar days replaces these checks.
 6. Publish `1.0.0` only when no blocking issue remains and the exact tarball has passed
-   the required release checks, consumer acceptance, exact-artifact authorization and
-   protected human publication approval.
+   the required release checks and consumer acceptance. The protected GitHub npm
+   review is the single human authorization for its displayed exact version and
+   checksum; no separate chat approval or pasted phrase is required.
 7. Independently verify registry bytes, provenance, signatures and channels, then
    confirm the published package in the real consumer. Promotion is complete only
    when the published artifact matches the tested tarball and these checks pass.

package/docs/troubleshooting.md

@@ -68,7 +68,9 @@ owner-only startup receipt. This cannot stop a manually started engine.
 When a container stays in `starting` or becomes `unhealthy`, Rehearsal reports a runtime
 dependency failure rather than a migration failure. The safe diagnostic includes Docker
 CPU, memory, and container counts; Colima also includes available VM memory when it can
-be read. Stop unrelated local stacks or increase the engine's resources before retrying.
+be read. These measurements alone do not establish a capacity problem. Review the
+reported startup evidence first; for a proven resource shortage, stop only stacks you
+own or increase the engine's resources before retrying.
 Rehearsal never changes engine settings or bypasses service health checks.
 
 Supabase startup failures retain a bounded summary of recognized provider evidence,
@@ -135,7 +137,7 @@ docker pull postgres:17-alpine
 npx rehearsal doctor
 ```
 
-## A port is already in use
+## A port is already in use or cannot be bound
 
 Rerun `rehearsal setup` to select a different available block. Setup checks both active
 listeners and whether every selected port can be bound, then checks again before writing.
@@ -143,6 +145,56 @@ For an existing configuration, choose unique non-privileged ports and mirror the
 dedicated Supabase config when using Supabase. Do not stop an unrelated database to make
 defaults fit.
 
+`port_in_use` reports an occupied bind; `port_unavailable` reports a denied or
+unavailable bind. Neither proves a memory shortage. On Windows/WSL, an excluded TCP
+range or host access policy can prevent binding even when no listener is visible.
+In **Windows PowerShell**, inspect the host without changing it:
+
+```powershell
+netsh interface ipv4 show excludedportrange protocol=tcp
+```
+
+If the configured port (for example the tutorial's `59422`) is excluded, select a
+different available port outside those ranges. For PostgreSQL, review
+`runtime.databasePort` in `rehearsal.config.mjs`. For Supabase, review the configured
+runtime ports and matching dedicated Supabase configuration together. Keep loopback
+binding. Do not delete reservations, disable host security, prune resources or stop
+someone else's listener to make the default work. Access-denied output is evidence
+of a bind problem, not proof of a particular Windows reservation.
+
+Microsoft documents the [read-only excluded-port command](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/netsh-interface).
+Windows database execution still uses the [WSL 2 compatibility preview](../COMPATIBILITY.md#operating-systems-and-execution-location), not native Windows database support.
+
+## A candidate migration failed, but SQL and provider output are withheld
+
+Rehearsal keeps SQL, row values, constraint names and raw provider output private.
+When the provider supplies a recognized SQLSTATE envelope, it reports that code plus
+a fixed explanation and next step. PostgreSQL codes are
+[provider-defined conditions](https://www.postgresql.org/docs/17/errcodes-appendix.html),
+not guesses from the SQL text:
+
+| Code              | Meaning                | Next step                                                                                 |
+| ----------------- | ---------------------- | ----------------------------------------------------------------------------------------- |
+| `42601`           | SQL syntax error       | Review malformed statements and punctuation.                                              |
+| `23502`           | NOT NULL violation     | Review NULL values and backfill before enforcing the requirement.                         |
+| `23503`           | Foreign-key violation  | Review missing referenced rows and migration ordering.                                    |
+| `23505`           | Uniqueness violation   | Review duplicates before enforcing uniqueness.                                            |
+| `23514`           | CHECK violation        | Existing or newly written rows do not satisfy the constraint; review/backfill them.       |
+| `42P01` / `42703` | Missing table / column | Review schema qualification and migration ordering; this is not a confirmed syntax error. |
+
+Unknown, unsupported, oversized or conflicting evidence remains explicitly unknown;
+it must not be labeled a syntax error from wording alone. JSON failures include the
+versioned `error.context.migrationFailure` projection with provider, classification,
+SQLSTATE, evidence, fixed summary and suggestions. PostgreSQL may identify its exact
+attempted input file, not the actual origin of the failing SQL or a line/column location.
+No automatic rewrite, retry, reset or hosted connection follows a diagnosis.
+
+Inspect `rehearsal status` after failure. Owned runtime cleanup and baseline preservation
+are separate facts; a failed operation does not prove SQL rollback or preservation of
+your disposable sandbox edits. A warning that cleanup could not be confirmed requires
+review before retrying. Follow the [break-and-fix tutorial](tutorial.md#5-break-a-migration-on-existing-data)
+to practice safely on synthetic data.
+
 ## Baseline checksum mismatch
 
 Do not edit the checksum or manifest. The artifact is no longer the reviewed input.

package/docs/tutorial.md

@@ -3,7 +3,7 @@
 This tutorial runs a complete PostgreSQL rehearsal in a temporary fictional project. It
 does not use your application, production data, or a hosted database.
 
-Allow about five minutes after downloading the database image. You need Git, Node.js 22,
+Allow about ten minutes after downloading the database image. You need Git, Node.js 22,
 24, or 26, npm, and a running Docker-compatible engine. Node.js 24 LTS is recommended.
 
 ## 1. Prepare Rehearsal
@@ -36,9 +36,14 @@ rehearsal_repo=$PWD
 tutorial_dir=$(mktemp -d)
 cp -R tests/fixtures/postgresql-project "$tutorial_dir/app"
 cd "$tutorial_dir/app"
-npm install --ignore-scripts --no-save "$rehearsal_repo"
+npm install --ignore-scripts --no-save --install-links "$rehearsal_repo"
 ```
 
+`--install-links` installs a local package copy in this temporary project instead of
+linking to the separate source checkout. Both the CLI and VS Code can use this copy;
+the extension deliberately refuses a package that resolves outside the project or its
+containing Git repository. Installation does not start or change a database.
+
 The temporary project contains:
 
 - one historical migration that creates a `widgets` table;
@@ -51,6 +56,12 @@ The fixture uses runtime ID `rehearsal-postgresql-fixture` and PostgreSQL port `
 Run only one copy at a time, or choose a distinct `runtime.projectId` and free
 `runtime.databasePort` in `rehearsal.config.mjs` before continuing. Rehearsal will not
 replace another listener.
+On Windows, run this tutorial inside WSL 2 on its Linux filesystem, with Linux Node
+and Docker integration enabled. A Windows-excluded port can fail even without a
+listener. If `59422` cannot be bound, inspect the Windows host's excluded TCP ranges
+with `netsh interface ipv4 show excludedportrange protocol=tcp` in PowerShell,
+then choose a different available `runtime.databasePort` before starting. Do not remove
+reservations or stop unrelated services. See [port troubleshooting](troubleshooting.md#a-port-is-already-in-use-or-cannot-be-bound).
 This is a database-only example, not a full application with a browser interface.
 
 ## 3. Create the baseline
@@ -77,10 +88,84 @@ Choose **Run a rehearsal**. The guide should show exactly one candidate:
 Confirm it. Rehearsal creates a loopback-only PostgreSQL container, restores the baseline,
 applies the candidate, and runs the fixture proof.
 
-Success ends with an application-proof message and suggests exercising the local
-application before verification.
+Success ends with the fixture's project-proof message. Here, the configured proof
+checks the migrated database; it does not start a browser application. The rehearsal
+command has finished even though its database can remain running. Continue with the
+deliberate failure below, or use `rehearsal verify` to check the runtime.
+
+## 5. Break a migration on existing data
+
+This is the useful failure: the SQL is valid, but the synthetic row's new `description`
+is NULL. Making that column required would work on an empty table and fail on this row.
+
+Exit the guide. From the temporary app directory, copy the deliberately unsafe example
+into a **new, unapplied** candidate:
+
+```bash
+cp demo/require-description.sql database/migrations/20260101000200_require_widget_description.sql
+npx --no-install rehearsal
+```
+
+Choose **Run a rehearsal** again. Review the two candidates, including the new
+`20260101000200_require_widget_description.sql`, and confirm the exact plan.
+The expected result is a failure, not a successful rehearsal:
+
+```text
+Migration SQLSTATE: 23502.
+Rows do not satisfy a NOT NULL requirement.
+```
+
+The safe explanation recommends reviewing NULL values and backfilling incompatible
+rows. SQL and provider row details remain private. A constraint failure is **not** a
+syntax error: PostgreSQL reported that the data violates the requirement.
+
+Rehearsal must not report the failed runtime as trusted. Its owned failure cleanup may
+remove the disposable runtime; a cleanup warning means resources may remain. The
+immutable baseline remains available. Do not infer a transaction rollback or preserved
+sandbox edits from a failure message alone. No production database is involved.
+
+## 6. Fix it, review again, and pass
+
+Exit the guide. Replace **only this new, never-successfully-applied tutorial candidate**
+with its data-preserving fix:
+
+```bash
+cp demo/backfill-and-require-description.sql database/migrations/20260101000200_require_widget_description.sql
+npx --no-install rehearsal
+```
+
+The fix first fills missing descriptions with a synthetic value, then enforces NOT NULL.
+Choose **Run a rehearsal**, review the changed candidate and its **new digest**, and
+confirm again. Rehearsal restores the same baseline and applies the corrected plan.
+The application proof should now pass. Do not reuse an earlier confirmation or alter a
+historical migration that was already deployed; real deployed history needs a forward
+migration instead.
+
+## 7. Continue in VS Code, or verify from the terminal
+
+To continue in the editor, leave the guide, open this temporary `app` folder in VS Code,
+and install [Rehearsal DB](vscode.md). On Windows, open the folder through **Remote -
+WSL**, not in a native Windows extension host. Trust only this project after reviewing
+its files, then choose **Rehearsal: Open Dashboard**. Refresh if the dashboard was
+already open. Opening or refreshing the dashboard performs read-only inspection; it
+does not rerun the rehearsal or reset its database.
+
+If an earlier tutorial install reports that the package resolves outside its repository,
+run the following from the same temporary `app` directory, using the source checkout
+you built in step 1, then refresh the dashboard:
+
+```bash
+npm install --ignore-scripts --no-save --install-links "$rehearsal_repo"
+```
+
+This replaces the external package link with a project-local copy. Do not edit
+Rehearsal's manifest or CLI paths to bypass the check. The baseline, project
+configuration, privacy key and database do not need to be reset. If the original shell
+was closed, set `rehearsal_repo` to the absolute path of that reviewed source checkout
+first. A copy does not track later source edits; rebuild and explicitly reinstall it
+when testing a changed checkout.
 
-## 5. Try the runtime commands
+## 8. Verify and clean up
 
 Exit the guide, then run:
 
@@ -97,9 +182,9 @@ directory remains on disk and can be deleted when you no longer need it.
 
 ## What you proved
 
-You used the same packaged CLI a normal project installs. Rehearsal verified the baseline,
-approved an exact migration, ran it in a disposable database, tested the result, and
-cleaned up only its own runtime.
+You saw valid SQL fail against existing data, used a safe database explanation to fix
+the unapplied migration, reviewed the changed plan, and proved the correction against
+the same baseline. Rehearsal verified the result and cleaned up only its own runtime.
 
 Next, follow [Getting started](getting-started.md) in your own project. Start with synthetic
 rows until the workflow and application proof are reliable.