@rehearsal-db/core 0.1.0-beta.9 → 0.1.0-rc.2

package/CHANGELOG.md

@@ -5,6 +5,313 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## Unreleased
 
+## [0.1.0-rc.2] - 2026-10-09
+
+### Changed
+
+- Container-engine startup is now explicit by default. Rehearsal starts Colima only
+  when a project deliberately enables `containerRuntime.autoStartColima`, reports that
+  action, and never silently stops the shared engine.
+- Package-managed Supabase containers use Docker's non-resuming restart policy after
+  each start, preventing stopped Rehearsal stacks from waking merely because Docker or
+  Colima restarts. Exact Supabase project labels keep the change inside the selected
+  disposable target.
+- Runtime diagnostics and a new lifecycle guide explain which commands need Docker,
+  what remains running, and how to finish a low-memory local session without pruning or
+  deleting persistent data.
+
+### Fixed
+
+- A stopped Colima VM no longer restarts from a default Rehearsal configuration.
+- Independent Test Lab acceptance now reaps exact workspace-owned interactive children
+  after success, failure, interruption, and timeout.
+
+## [0.1.0-rc.1] - 2026-10-08
+
+### Changed
+
+- Promotes the exact beta.18 behavior and documented compatibility surface to the first
+  release candidate. No runtime, configuration, policy, CLI, or public TypeScript
+  capability changed after beta.18.
+- Broad feature work is frozen while the release candidate completes two independent
+  Test Lab passes, one final package-only consumer upgrade, and its observation window.
+
+## [0.1.0-beta.18] - 2026-10-08
+
+### Added
+
+- A concise stability contract now defines the supported public surface, defects that
+  block the first stable release, and the exact beta-to-RC-to-stable promotion gate.
+- Automated release-policy tests cover beta, release-candidate, stable, malformed, and
+  mismatched GitHub release metadata.
+
+### Changed
+
+- Protected OIDC publication now supports both prerelease and stable versions. Beta and
+  release-candidate versions update `beta`; once a stable version exists they cannot
+  replace `latest`. Stable publication updates `latest` without rewriting `beta`.
+- npm channel selection lives only in the protected release workflow instead of static
+  package metadata, and missing beta.16 and beta.17 changelog comparisons are restored.
+- Vitest's locked patch release is updated from 5.0.2 to 5.0.3 after the complete CI
+  matrix passed.
+
+## [0.1.0-beta.17] - 2026-10-08
+
+### Added
+
+- `rehearsal identity connect` and the guided home screen now keep the sandbox app
+  available during ordinary provider sign-in, detect exactly one approved verified local
+  identity, show a redacted copied-account preview, and apply the existing exact claim
+  after one deliberate confirmation. The app is reopened automatically with an honest
+  fresh-session instruction; explicit `identity plan` and `identity claim` commands remain
+  available for scripts.
+
+## [0.1.0-beta.16] - 2026-10-08
+
+### Changed
+
+- The CLI now routes guided and scripted requests through focused typed command
+  handlers and one result/output contract. The executable retains only process
+  lifecycle, project locking, guided-loop coordination, and top-level error handling;
+  command-session caches no longer live in public parsed flags.
+- Configuration now passes through separate discovery, raw-schema validation,
+  normalization, project-root path resolution, project detection, and starter-rendering
+  modules behind the existing import path. Public declarations come from the same
+  TypeScript source, including the new `NormalizedRehearsalConfig` type.
+- Installed-consumer verification now shares one scenario catalog, artifact installer,
+  isolated workspace boundary, process boundary, and persistent application-session
+  helper. The complete release gate runs every scenario against one immutable tarball
+  and records its exact version, SHA-256, tool environment, commands, timings, and
+  results.
+- Identity policy validation, deterministic claim planning, SQL generation, local Auth
+  lookup, pure verification, and transactional execution now live in separate typed
+  stages behind the unchanged public claim API. Generated reference SQL is independently
+  testable, while only the executor can mutate the local database or Storage runtime.
+- PostgreSQL and Supabase now share one typed runtime lifecycle engine for command
+  dispatch, active-baseline loading, migration confirmation and receipts, runtime
+  markers, and rollback. Candidate receipts are bound to their exact database target,
+  while each driver retains its own ownership proof and database-specific behavior.
+- Privacy policy types, recipe normalization, dependency validation, deterministic
+  transforms, structured JSON, rule dispatch, row execution, and key handling now live
+  in focused typed stages behind the unchanged public privacy import. An explicit closed
+  registry covers every supported action and derivation without widening policy v2.
+
+## [0.1.0-beta.15] - 2026-10-08
+
+### Added
+
+- A strict, no-emit TypeScript gate now checks the first shared runtime utilities and
+  verifies that consumers can compile against Rehearsal's public configuration types.
+- The documentation site now explains the supported TypeScript surface with examples
+  that are compiled and checked against their rendered documentation source.
+- All shipped implementation and executable-helper source now uses TypeScript. Clean
+  builds emit Node-compatible ESM and declarations into the reviewed package boundary,
+  and tests exercise that compiled output rather than an alternate source path.
+- The published build omits repository-only JavaScript source maps while retaining
+  runtime JavaScript and declarations, keeping the installed package compact.
+
+### Fixed
+
+- Packed onboarding chooses an available local port block for preserved configuration
+  fixtures, so unrelated running Rehearsal projects cannot make the isolation test fail.
+
+## [0.1.0-beta.14] - 2026-10-05
+
+### Added
+
+- Packed-package onboarding is now a required CI job. It covers fresh Supabase and
+  PostgreSQL installs, beta.7 configuration preservation, missing credentials, occupied
+  ports, malformed configuration, and non-destructive partial-setup recovery.
+- The independent test lab can run the same first-install boundary against an exact
+  candidate tarball before either database lifecycle.
+- Installation and setup now report the exact active Rehearsal configuration path and
+  explain when a supported existing nested config prevents root-file generation.
+- Packed-package onboarding covers fresh, nested, existing-root, and repeated installs
+  while proving reviewed configuration bytes are preserved.
+- Privacy policy version 2 can explicitly treat nullable owners as non-matches and match
+  an approved owner through any of a bounded list of pseudonymized identity columns.
+- Bounded JSON unions classify each permitted root type, while JSON dictionaries require
+  reviewed runtime-key formats, key actions, value recipes, and item/depth/byte limits.
+- JSON dictionaries can restrict runtime keys to canonical signed integers within an
+  explicit safe-integer range, preserving positive, negative, and reviewed zero keys
+  without widening numeric maps to arbitrary text.
+- Date shifting can explicitly preserve numeric epoch-millisecond representation,
+  including inside structured JSON, while sharing a stable grouped offset with related
+  epoch or ISO-string dates.
+- Bounded scalar enums retain only explicitly reviewed structural strings, finite
+  numbers, or booleans inside ordinary fields and nested JSON declarations, rejecting
+  out-of-domain values without echoing them in diagnostics.
+- Validated strings preserve bounded, case-sensitive structural codes from open domains
+  using a package-owned portable alphabet, refusing credential-shaped and malformed
+  text without consumer regexes, callbacks, or static identifier lists.
+- Keyed hexadecimal and GTIN pseudonyms preserve reviewed database constraints, while
+  fixed-width digest recipes derive fingerprints only from explicitly named sanitized
+  columns and reject missing, excluded, duplicate, or cyclic inputs.
+- A single GTIN recipe can declare reviewed `allowedLengths`, preserving each source
+  value's 8-, 12-, 13-, or 14-digit shape and check digit even inside structured JSON.
+- Keyed URL pseudonyms replace private HTTPS URLs with deterministic, bounded HTTPS
+  loopback paths without retaining source hosts, paths, credentials, queries, or tokens.
+- Bounded binding substitution can retain permitted surrounding text while replacing
+  exact occurrences of a reviewed UUID with its corresponding keyed UUID pseudonym.
+- External PostgreSQL readers can declare a bounded exact allowlist of provider-owned
+  permission groups. Rehearsal verifies safe membership options, group attributes,
+  nesting, view ownership, and the complete effective privilege surface.
+
+### Documentation
+
+- First-time users now have a short recovery table for interrupted setup, failed
+  upgrades, port conflicts, missing OAuth credentials, and low Docker capacity.
+- The configuration guide documents a safe manual move to the project root, separating
+  config-file-relative JavaScript imports from project-root-relative Rehearsal paths.
+- The sanitization guide documents nullable and multi-column ownership, heterogeneous
+  JSON values, runtime-keyed dictionaries, keyed HTTPS replacements, bounded identity
+  substitution, and their fail-closed boundaries.
+
+### Fixed
+
+- Source preparation now stores and reads each target's access receipt and owner-only
+  reader credential under its configured baseline artifact directory. Nested and
+  multi-target state roots no longer collide, and retirement refuses a receipt from a
+  different target root.
+- Supabase Storage source preparation now recursively traverses real folder placeholder
+  entries while keeping the approved prefix, path, depth, object-count, per-object, and
+  total-byte boundaries fail closed.
+- Approved-owner selection now rejects non-finite numeric values in every declared
+  owner column before choosing a privacy branch, including when another column already
+  matches the approved owner.
+- Pseudonymized canonical integer dictionary keys now share the same keyed identity
+  mapping as numeric columns and nested numeric values using the same namespace, so
+  runtime maps keep their reviewed cross-representation joins.
+- External-reader membership mismatches now return a redacted, actionable source
+  authorization refusal instead of an internal-failure diagnostic.
+- All external-reader privilege, expiration, readable-surface, and security-definer
+  denials now use the same `SOURCE_AUTHORIZATION_REFUSED` diagnostic and exit code 3.
+- Identity claims now sequence PostgreSQL reads on their single transaction client,
+  avoiding deprecated overlapping queries and remaining compatible with pg 9.
+
+## [0.1.0-beta.13] - 2026-10-05
+
+### Added
+
+- Runtime and CI compatibility now cover maintained Node.js 22, 24, and 26 releases;
+  Node.js 24 LTS remains the recommended default and release-build runtime.
+- Source access policies can use an externally provisioned, database-expiring
+  PostgreSQL reader without administrator credentials. Rehearsal binds canonical export
+  view definitions, verifies the complete approved read surface and deny controls, and
+  never changes or retires provider-owned source objects.
+- `rehearsal --version`, its conventional `-V` alias, and `rehearsal version` now
+  report the installed package version without requiring project configuration.
+- Privacy policy version 2 can use one reviewed identity-aware path mapping for both
+  database references and physical Storage destinations. Owner prefixes stay in the
+  environment, review plans retain only their hashes, and unsafe or mismatched paths
+  fail closed.
+- Related timestamps can share a named deterministic date-shift group, preserving their
+  ordering and duration without consumer callbacks.
+- The baseline verification corpus now exercises two unrelated target schemas, a
+  10,003-row packed-package stream, concurrent row/schema/ledger changes, malformed and
+  truncated results, connection loss, low disk, interruption, and deterministic
+  fixed-key output.
+
+### Fixed
+
+- Baseline preparation now rejects missing, negative, overflowing, malformed, or
+  oversized PostgreSQL estimate and cursor results before activation. Every preparation
+  failure preserves the active baseline, removes private staging, and leaves an edited
+  runtime untouched.
+- Approved-owner UUID columns are no longer confused with PostgreSQL sequence-backed
+  identities. Restore checks the actual local schema before resetting a sequence, while
+  genuine numeric identity columns retain correct next-value behavior.
+- A failed Storage transfer now recursively restores write permission only within its
+  owned staging tree, removes that incomplete generation, and preserves the original
+  safe preparation error instead of replacing it with a cleanup error.
+- Storage preparation now records a canonical media type from reviewed object metadata,
+  removing response-only parameters such as a text charset that local bucket MIME
+  allowlists reject during restore.
+- Container startup and health failures are now classified as runtime dependency
+  failures and include safe Docker/Colima capacity context instead of being mislabeled
+  as migration verification failures.
+
+## [0.1.0-beta.12] - 2026-10-04
+
+### Added
+
+- Supabase projects can declaratively configure local Google or GitHub OAuth in
+  `rehearsal.config.mjs`. Rehearsal derives the credential allowlist, injects only the
+  ignored owner-only environment values, and generates the exact loopback callback in
+  the disposable runtime without tracking secrets. Local signup requires an explicit
+  acknowledgment and is enabled only in that generated runtime copy.
+- Branded, responsive documentation is now hosted on GitHub Pages with searchable
+  navigation, light and dark themes, and automatic deployment from `main`.
+- The documentation home page and packaged README show the live monthly npm download
+  count and link directly to the npm package.
+- Packed-package onboarding acceptance now proves both fresh root-config creation and a
+  real beta.11 upgrade that preserves the user's existing configuration byte for byte.
+
+### Changed
+
+- The packaged README now links prominently to the hosted documentation, npm package,
+  and issue tracker. Package homepage metadata also points to the hosted documentation.
+- GitHub Pages publishing uses the current Node.js 24 action generations without legacy
+  runtime warnings.
+- `rehearsal init` now calls out important optional settings that are available but not
+  enabled before showing the current installed-release template.
+
+### Fixed
+
+- Existing Google or GitHub provider sections can transition to declarative ownership
+  without editing the tracked Supabase template. Rehearsal replaces only a compatible
+  section in the disposable runtime copy, while `doctor` refuses ambiguous or
+  safety-weakening provider settings before reset.
+- Multi-target plain-text plans now print each declarative OAuth callback, and `init`
+  advertises the declarative replacement even when a project still uses legacy provider
+  fields.
+
+## [0.1.0-beta.11] - 2026-10-03
+
+### Added
+
+- Privacy policy version 2 now supports hashed approved-owner bindings, conditional
+  approved/other-owner transformations, bounded JSON arrays, nested recipes, and
+  explicitly optional object fields without consumer sanitizer callbacks.
+- Local npm installs now create a validated, commented project-root
+  `rehearsal.config.mjs`, dedicated local runtime configuration, and additive safe ignore
+  entries when exactly one consumer application can be proven. Guided setup remains the
+  tested recovery path when lifecycle scripts are disabled or a workspace is ambiguous.
+- Copied-account association accepts explicit verified-email provider allowlists and
+  hashed provider-subject matchers for supported Supabase identities. Google, GitHub,
+  and email sign-in now share one review-and-confirm claim workflow.
+
+### Changed
+
+- Setup is idempotent, supported custom config paths are preserved, `.gitignore` updates
+  use an exclusive lock and atomic replacement, and `rehearsal init` shows the current
+  release template without replacing an existing config.
+
+### Fixed
+
+- Identity plan JSON no longer serializes the raw approved email or provider subject;
+  only the environment-variable name and reviewed SHA-256 receipt leave the process.
+
+## [0.1.0-beta.10] - 2026-10-03
+
+### Added
+
+- `rehearsal open` starts and verifies the configured runtime stack, launches the normal
+  application with declared local environment mappings, and keeps it available for
+  hands-on testing until interrupted.
+- The guide now offers **Open the sandbox app** after a runtime exists.
+
+### Changed
+
+- Persistent application sessions stop only their owned application process group on
+  `Ctrl+C`, `Ctrl+Z`, terminal close, or termination. The database and Storage runtime
+  stay running with local changes preserved across later sessions.
+
+### Fixed
+
+- `rehearsal open` keeps interruption handling active throughout application teardown,
+  so an npm-forwarded `Ctrl+C` cannot terminate the CLI early or orphan the app.
+
 ## [0.1.0-beta.9] - 2026-10-02
 
 ### Added
@@ -268,7 +575,18 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
   publication uses short-lived trusted OIDC, and every release tag must already exist on
   protected `main`.
 
-[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.9...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.2...HEAD
+[0.1.0-rc.2]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.1...v0.1.0-rc.2
+[0.1.0-rc.1]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.18...v0.1.0-rc.1
+[0.1.0-beta.18]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.17...v0.1.0-beta.18
+[0.1.0-beta.17]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.16...v0.1.0-beta.17
+[0.1.0-beta.16]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.15...v0.1.0-beta.16
+[0.1.0-beta.15]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.14...v0.1.0-beta.15
+[0.1.0-beta.14]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.13...v0.1.0-beta.14
+[0.1.0-beta.13]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.12...v0.1.0-beta.13
+[0.1.0-beta.12]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.11...v0.1.0-beta.12
+[0.1.0-beta.11]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.10...v0.1.0-beta.11
+[0.1.0-beta.10]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.9...v0.1.0-beta.10
 [0.1.0-beta.9]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.8...v0.1.0-beta.9
 [0.1.0-beta.8]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.7...v0.1.0-beta.8
 [0.1.0-beta.7]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.6...v0.1.0-beta.7

package/COMPATIBILITY.md

@@ -21,6 +21,21 @@ The first stable `1.0.0` requires external beta evidence, a support policy, and
 public API. Supporting additional database families, package managers, or operating
 systems is not implied by the 0.x contract.
 
+Rehearsal supports maintained even-numbered Node.js release lines that pass its CI
+matrix. Beta.13 supports Node.js 22, 24, and 26; Node.js 24 LTS is the recommended
+default and the release-build runtime. End-of-life and odd-numbered Node.js releases are
+not supported. A future release may remove a Node.js line after its upstream end-of-life
+date, with that change called out in the changelog.
+
+The npm install hook may create project scaffolding only when it proves one application
+root. Ordinary npm application installs are covered. A workspace is automatic only when
+one declaring consumer is already visible in its manifest or lockfile; npm can save a
+new `--workspace` declaration after dependency hooks run, so a first workspace install
+may use the guided fallback. pnpm and Yarn install layouts are not yet an
+automatic-generation contract. Run `npx rehearsal` from the application directory for
+all skipped cases. Global, cache, temporary `npx`, and ambiguous multi-application
+workspace installs do not receive files.
+
 The PostgreSQL target covers timestamped SQL migrations running in a dedicated local
 `postgres` Docker image. Runtime commands reject hosted connection strings and existing
 unmanaged servers. The separately opted-in PostgreSQL preparation boundary may use a

package/README.md

@@ -1,8 +1,39 @@
-# Rehearsal
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Ddupasquier/rehearsal-db/main/docs/site/logo-mark.svg" width="104" height="104" alt="Rehearsal logo" />
+</p>
 
-Rehearsal tests PostgreSQL and Supabase migrations on your computer before you run them
-anywhere important. It restores safe test data into a disposable local database, applies
-only the migrations you approve, and runs your project's own test command.
+<h1 align="center">Rehearsal</h1>
+
+<p align="center"><strong>Your migration passed on an empty database. Production will not be empty.</strong></p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/@rehearsal-db/core"><img alt="npm version" src="https://img.shields.io/npm/v/%40rehearsal-db%2Fcore?style=flat-square&logo=npm&logoColor=white&labelColor=1c2a34&color=287b5c" /></a>
+  <a href="https://www.npmjs.com/package/@rehearsal-db/core"><img alt="Monthly npm downloads" src="https://img.shields.io/npm/dm/%40rehearsal-db%2Fcore?style=flat-square&logo=npm&logoColor=white&label=downloads&labelColor=1c2a34&color=287b5c" /></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/npm/l/%40rehearsal-db%2Fcore?style=flat-square&labelColor=1c2a34&color=287b5c" /></a>
+  <a href="https://ddupasquier.github.io/rehearsal-db/"><img alt="Read the documentation" src="https://img.shields.io/badge/docs-read_the_guide-269fab?style=flat-square&labelColor=1c2a34" /></a>
+</p>
+
+<p align="center">
+  <a href="https://ddupasquier.github.io/rehearsal-db/">Read the documentation</a> ·
+  <a href="https://www.npmjs.com/package/@rehearsal-db/core">View on npm</a> ·
+  <a href="https://github.com/Ddupasquier/rehearsal-db/issues">Report a problem</a>
+</p>
+
+Most migration tests start with an empty database. Production does not.
+
+Existing rows, relationships, authentication identities, stored files, and migration
+history are where risky changes break. A migration can build successfully and still fail
+against the data and application behavior you actually have.
+
+**Rehearsal catches those problems before deployment.** It restores a reviewed,
+sanitized baseline into a disposable local PostgreSQL or Supabase environment, applies
+only the exact migrations you approve, and runs your application's own proof.
+
+| An empty database cannot prove…                      | Rehearsal lets you verify…                                   |
+| ---------------------------------------------------- | ------------------------------------------------------------ |
+| old rows still satisfy new constraints               | the migration against a reviewed, production-shaped copy     |
+| relationships, identities, and stored files survive  | database, Auth, and Storage behavior in one local sandbox    |
+| the application still works after the schema changes | your own tests and hands-on flows before anything is shipped |
 
 Projects with a separate publication or read-model database can declare it as a
 dependent target. Rehearsal then manages the complete isolated runtime stack.
@@ -13,12 +44,12 @@ it through a reviewed privacy policy, and retire the access again. It is never p
 `run`, `reset`, `migrate`, or application launch. Rehearsal is not a backup system or a
 production deployment tool.
 
-> Rehearsal is in public beta. Use it on a branch and keep a working backup of your
+> **Pre-1.0 safety note:** use Rehearsal on a branch and keep a working backup of your
 > project.
 
 ## What you need
 
-- Node.js 24 and npm
+- Node.js 22, 24, or 26 and npm (Node.js 24 LTS recommended)
 - Docker Desktop, Colima, or another Docker-compatible engine
 - timestamped `.sql` migration files
 - a project test command that can prove the migrated application works
@@ -33,15 +64,21 @@ your migration is intended to change.
 From your project directory:
 
 ```bash
-npm install --save-dev @rehearsal-db/core@beta
+npm install --save-dev @rehearsal-db/core
 npx rehearsal
 ```
 
-The first run detects your project and offers to create a commented
-`rehearsal.config.mjs` with the project name, migration paths, commands, ports, and safe
-defaults already filled in. Choose **Set the stage**, select Supabase or PostgreSQL,
-review the preview, and confirm the files it will create. Existing files are never
-overwritten.
+For an ordinary npm application install, Rehearsal safely creates a commented
+`rehearsal.config.mjs` in the project root, adds only its local-artifact entries to
+`.gitignore`, and prepares the isolated local runtime configuration. It detects the
+project name, database target, migration paths, commands, and free ports. Review lines
+marked `CHECK`, then open the guide. Existing files are never overwritten. If a supported
+root or nested config already exists, Rehearsal reports that active path and does not
+create a competing file; see [Configuration](docs/configuration.md#workspaces-and-custom-paths).
+
+If install scripts are disabled or the workspace root is ambiguous, installation makes
+no guess. Run `npx rehearsal` inside the application and choose **Set the stage** for the
+same previewed setup.
 
 For PostgreSQL, download the reviewed local image once before running the guide:
 
@@ -51,6 +88,11 @@ docker pull postgres:17-alpine
 
 Rehearsal itself never downloads a database image during a rehearsal.
 
+For local Google or GitHub sign-in, the generated config includes a commented
+`supabase.authentication` example. It names an ignored owner-only credential file;
+Rehearsal generates the provider block and local callback inside the disposable runtime.
+See [Supabase authentication](docs/configuration.md#supabase-authentication).
+
 ## Three terms you will see
 
 - **Baseline:** a locked, safe starting copy of your schema and test data.
@@ -64,11 +106,17 @@ source-owner approval; see [Standalone workflow](docs/standalone-workflow.md).
 ## The normal workflow
 
 1. Run `npx rehearsal`.
-2. Let the guide create the local-only configuration.
+2. Review the generated local-only configuration, or let the guide create it when the
+   install hook safely skipped it.
 3. Review the sanitization policy and create the baseline.
 4. Review the exact candidate migration list.
 5. Run the rehearsal and your application proof.
-6. Test the local application, then verify, reset, stop, or discard the runtime.
+6. Choose **Open the sandbox app** for hands-on testing, then verify, reset, stop, or
+   discard the runtime.
+
+`npx rehearsal open` starts and verifies the existing local runtime, keeps the configured
+app available until you press `Ctrl+C`, and preserves database and Storage changes for
+the next session.
 
 For an approved production-shaped copy, the optional sequence is `source plan`, `source
 apply`, `refresh`, and `source retire`. `refresh` verifies the replacement before it
@@ -114,7 +162,7 @@ See [COMPATIBILITY.md](COMPATIBILITY.md) for the exact support contract.
 
 Start here:
 
-- [Documentation map](docs/README.md) — find the right guide quickly
+- [Documentation home](docs/index.md) — choose the shortest path for your goal
 - [Getting started](docs/getting-started.md) — set up your own project
 - [Safe hands-on tutorial](docs/tutorial.md) — try the full flow in a disposable project
 - [Troubleshooting](docs/troubleshooting.md) — fix common setup problems
@@ -124,6 +172,8 @@ Reference:
 
 - [CLI commands](docs/commands.md)
 - [Configuration](docs/configuration.md)
+- [Container runtime lifecycle](docs/runtime-lifecycle.md) — keep Docker and Supabase use on demand
+- [TypeScript types](docs/typescript.md)
 - [Baselines](docs/baselines.md)
 - [Sanitization](docs/sanitization.md)
 - [Security model](docs/security-model.md)
@@ -133,6 +183,7 @@ Reference:
 - [Runtime and local identity policies](docs/runtime-policies.md)
 - [Glossary](docs/glossary.md)
 - [Repository architecture](docs/architecture.md)
+- [Stability and the first stable release](docs/stability.md)
 - [Release process](docs/releasing.md)
 
 ## Getting support
@@ -150,7 +201,7 @@ problems belong in the private process described in [SECURITY.md](SECURITY.md).
 
 ## For contributors
 
-Use Node.js 24, run `npm ci`, then run:
+Use a supported Node.js release (22, 24, or 26), run `npm ci`, then run:
 
 ```bash
 npm run check
@@ -161,3 +212,9 @@ npm run test:fixture
 
 The fixture commands install the packed package into clean synthetic projects. They do
 not connect to hosted services. See [CONTRIBUTING.md](CONTRIBUTING.md) for the full rules.
+
+Preview the styled documentation site locally with:
+
+```bash
+npm run docs:preview
+```

package/dist/package.json

@@ -0,0 +1,100 @@
+{
+    "name": "@rehearsal-db/core",
+    "version": "0.1.0-rc.2",
+    "private": false,
+    "description": "Catch PostgreSQL and Supabase migrations that pass on empty databases but fail on real data—before deploy.",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Ddupasquier/rehearsal-db.git"
+    },
+    "bugs": {
+        "url": "https://github.com/Ddupasquier/rehearsal-db/issues"
+    },
+    "homepage": "https://ddupasquier.github.io/rehearsal-db/",
+    "publishConfig": {
+        "access": "public",
+        "provenance": true
+    },
+    "type": "module",
+    "engines": {
+        "node": "^22.0.0 || ^24.0.0 || ^26.0.0"
+    },
+    "bin": {
+        "rehearsal": "dist/src/cli/rehearsal.mjs"
+    },
+    "exports": {
+        ".": {
+            "types": "./types/configuration.d.mts",
+            "import": "./dist/src/index.mjs"
+        },
+        "./baseline": "./dist/src/baseline/artifact.mjs",
+        "./baseline-builder": "./dist/src/baseline/builder.mjs",
+        "./diagnostics": "./dist/src/shared/diagnostics.mjs",
+        "./migrations": "./dist/src/runtime/migration_history.mjs",
+        "./process-environment": "./dist/src/shared/process_environment.mjs",
+        "./privacy": "./dist/src/baseline/privacy_engine.mjs",
+        "./schema": "./dist/src/baseline/schema_snapshot.mjs",
+        "./service-environment": "./dist/src/runtime/service_environment.mjs",
+        "./source-access": "./dist/src/source/access.mjs"
+    },
+    "files": [
+        "dist",
+        "types",
+        "docs/*.md",
+        "README.md",
+        "BENCHMARKS.md",
+        "CHANGELOG.md",
+        "SECURITY.md",
+        "COMPATIBILITY.md",
+        "SUPPORT.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "postinstall": "node dist/scripts/install/create_root_config.mjs",
+        "prepack": "npm run build",
+        "build": "node scripts/build/clean.mjs && tsc --project tsconfig.build.json",
+        "docs:build": "node scripts/docs/build.mjs",
+        "docs:preview": "node scripts/docs/serve.mjs",
+        "test": "npm run build && vitest run",
+        "test:unit": "npm run build && vitest run tests/unit",
+        "test:integration": "npm run build && vitest run tests/integration tests/contracts",
+        "test:docs": "npm run build && vitest run tests/contracts/documentationCommands.test.mjs",
+        "test:fixture": "npm run build && node scripts/verification/run_scenario.mjs supabase",
+        "test:fixture:postgresql": "npm run build && node scripts/verification/run_scenario.mjs postgresql",
+        "test:fixture:dependent": "npm run build && node scripts/verification/run_scenario.mjs dependent-target",
+        "test:fixture:onboarding": "npm run build && node scripts/verification/run_scenario.mjs onboarding",
+        "test:fixture:typescript": "npm run build && node scripts/verification/run_scenario.mjs typescript",
+        "test:fixture:standalone": "npm run build && node scripts/verification/run_scenario.mjs standalone",
+        "test:fixture:privacy": "npm run build && node scripts/verification/run_scenario.mjs privacy",
+        "release:verify": "node scripts/verification/release_gate.mjs",
+        "check": "npm run check:syntax && npm run typecheck && npm run test && npm run docs:build && npm run format:check && npm run package:audit",
+        "check:syntax": "find scripts tests -type f -name '*.mjs' -exec node --check {} +",
+        "typecheck": "npm run build && tsc --project tsconfig.json",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "package:audit": "node scripts/verification/audit_package.mjs"
+    },
+    "keywords": [
+        "postgresql",
+        "supabase",
+        "migration",
+        "testing",
+        "database"
+    ],
+    "license": "MIT",
+    "dependencies": {
+        "@clack/prompts": "^1.8.1",
+        "pg": "^8.23.1"
+    },
+    "devDependencies": {
+        "@fontsource-variable/dm-sans": "^5.3.0",
+        "@fontsource-variable/fraunces": "^5.3.0",
+        "@lydell/node-pty": "^1.2.0-beta.15",
+        "@types/node": "22.20.5",
+        "@types/pg": "^8.23.1",
+        "marked": "^18.0.14",
+        "prettier": "^3.9.6",
+        "typescript": "7.0.2",
+        "vitest": "^5.0.2"
+    }
+}

package/dist/scripts/install/create_root_config.d.mts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+/** Create safe project-root Rehearsal scaffolding during a local install. */
+export {};

package/dist/scripts/install/create_root_config.mjs

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/** Create safe project-root Rehearsal scaffolding during a local install. */
+import { fileURLToPath } from "node:url";
+import { createInstalledRehearsalScaffold, renderInstalledRehearsalScaffold, } from "../../src/project/install_scaffold.mjs";
+const packageRoot = fileURLToPath(new URL("../../..", import.meta.url));
+try {
+    const result = await createInstalledRehearsalScaffold({ packageRoot });
+    console.log(renderInstalledRehearsalScaffold(result));
+}
+catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(`Rehearsal could not safely create project files during installation: ${message}\nNext: run npx rehearsal from the application directory.`);
+}

package/dist/scripts/runtime/manage_database.d.mts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Purpose: Select the configured database runtime and forward the requested
+ * lifecycle action to its isolated driver.
+ */
+export {};