@rehearsal-db/core 0.1.0-beta.8 → 0.1.0-rc.1

package/CHANGELOG.md

@@ -5,6 +5,358 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## Unreleased
 
+## [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
+
+- Primary configurations may declare isolated dependent database targets. Rehearsal
+  validates unique ownership boundaries, combines migration approval, orders lifecycle
+  actions, runs project-owned preparation and proofs, and previews cleanup across the
+  complete stack.
+- A packed-package two-target PostgreSQL fixture proves source-to-read-model preparation,
+  positive and negative assertions, reverse shutdown, and exact cleanup without a
+  project-owned container engine.
+- A separately opted-in, exact-digest PostgreSQL source-access lifecycle with scoped
+  temporary roles/views, deny checks, owner-only credentials, and exact retirement.
+- Bounded coherent baseline refresh with executable privacy policy version 2, stable
+  keyed pseudonyms, atomic activation, capacity limits, and drift/interruption safety.
+- Approved Supabase Storage inventory/transfer with bucket-prefix, size, path, version,
+  and exact-byte controls.
+- Declarative runtime prerequisites and structural checks, plus exact local identity
+  association without application callback patches.
+- Package-owned application startup, local environment mapping, readiness, child-process
+  teardown, and meaningful positive/negative HTTP proof orchestration.
+- An exact-preview `refresh` command that builds a verified replacement first, resets the
+  complete local runtime stack, rolls back on runtime failure, and only then prunes the
+  specifically reviewed old baseline generations.
+
+### Changed
+
+- Shipped source, runtime adapters, repository-only verification, and tests now use a
+  domain-based layout with documented placement rules and contract checks.
+- Generated configs include a commented dependent-target example, and the documentation
+  explains that avoiding server errors is not a sufficient positive-path proof.
+- Generated configs explain the optional standalone policy paths, direct local runtime
+  environment mappings, and application readiness contract.
+- Source, privacy, runtime, identity, onboarding, and security documentation now describe
+  the package-owned declarative workflow and its separate authorization boundaries.
+
+### Fixed
+
+- Supabase restores now install declared schemas and extensions before restoring
+  extension-dependent objects, preserve the original `public` schema privilege baseline,
+  and add declared triggers only after their functions exist.
+- Supabase runtime environments now include a validated loopback-only database URL and
+  standard PostgreSQL variables for package-owned commands.
+- Identity claims can safely replace complete signup defaults, require application role
+  references, remap declared text/JSONB and Storage object paths, and verify token-hook
+  claims while refusing edited or independent local account data.
+- Baselines and restore checks now identify relations by schema and table, default old
+  records to `public`, and restore same-named tables in separate schemas independently.
+- Identity claims can preserve immutable audit authorship while transferring the active
+  account, and retain only the synthetic Auth actor required by that history.
+- Storage path transfer now copies through the local Supabase API, verifies exact bytes,
+  rolls back staged copies on database failure, and removes the old physical objects
+  only after the database commit succeeds.
+- Identity Storage scopes now accept restored objects whose owner is unset, refuse
+  conflicting owners, and verify the destination owner before rewriting application
+  paths.
+- Runtime-policy seeds may explicitly follow a named identity association, so later
+  verification checks the transferred key without recreating an obsolete placeholder
+  role.
+- Failed project proofs always report their exit status and bounded output byte counts
+  without echoing arbitrary project logs.
+- State-changing commands now use a project-wide operation lock and detect replacement
+  of the installed Rehearsal package while an operation is running.
+- Identity claims now refuse to rewrite copied Storage paths when referenced physical
+  objects are missing.
+
 ## [0.1.0-beta.8] - 2026-10-02
 
 ### Fixed
@@ -202,7 +554,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.8...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-rc.1...HEAD
+[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
 [0.1.0-beta.6]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.5...v0.1.0-beta.6

package/COMPATIBILITY.md

@@ -21,7 +21,34 @@ 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. It does not imply support for hosted connection strings,
-existing unmanaged servers, ORM-specific nested migration formats, Supabase Storage, or
-Supabase Auth emulation.
+`postgres` Docker image. Runtime commands reject hosted connection strings and existing
+unmanaged servers. The separately opted-in PostgreSQL preparation boundary may use a
+reviewed, short-lived source reader; this does not make a hosted database a runtime
+target. ORM-specific nested migration formats remain unsupported. Supabase Storage and
+Auth behavior apply only to the Supabase runtime.
+
+A primary config may declare flat dependent PostgreSQL or Supabase targets. Each target
+must have its own complete config, immutable baseline, project ID, ports, environment
+file, and artifact directory. Nested dependency graphs and shared runtime ownership are
+not supported.
+
+Executable privacy policy version 2, source-access policy version 1, runtime policy
+version 1, and identity policy version 1 are strict declarative contracts. Unknown
+fields fail closed. They do not imply support for arbitrary transformations, SQL,
+provider administration, consent decisions, or every PostgreSQL extension.

package/README.md

@@ -1,18 +1,28 @@
 # Rehearsal
 
+[![Monthly npm downloads](https://img.shields.io/npm/dm/%40rehearsal-db%2Fcore?style=flat-square&logo=npm&logoColor=white&label=npm%20downloads&labelColor=1c2a34&color=287b5c)](https://www.npmjs.com/package/@rehearsal-db/core)
+
+[Read the documentation](https://ddupasquier.github.io/rehearsal-db/) · [View on npm](https://www.npmjs.com/package/@rehearsal-db/core) · [Report a problem](https://github.com/Ddupasquier/rehearsal-db/issues)
+
 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.
 
-Rehearsal never connects to a hosted database. It is a migration-testing tool, not a
-backup system or a production deployment tool.
+Projects with a separate publication or read-model database can declare it as a
+dependent target. Rehearsal then manages the complete isolated runtime stack.
+
+Normal rehearsal commands never connect to a hosted database. An optional, separately
+approved preparation workflow can create a short-lived read-only export surface, stream
+it through a reviewed privacy policy, and retire the access again. It is never part of
+`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
 > 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
@@ -31,11 +41,17 @@ npm install --save-dev @rehearsal-db/core@beta
 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:
 
@@ -45,6 +61,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.
@@ -52,16 +73,28 @@ Rehearsal itself never downloads a database image during a rehearsal.
 - **Runtime:** the disposable local database where the rehearsal happens.
 
 The baseline may contain synthetic data or properly sanitized production-shaped data.
-Start with synthetic data. Rehearsal does not copy or sanitize production data for you.
+Start with synthetic data. Real source preparation is opt-in and requires separate
+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
+resets the local runtime or removes an old copy. Every source-side or identity change has
+its own exact confirmation digest.
 
 When local disk space gets tight, choose **Clean up disk space** in the guide. Rehearsal
 previews old baseline generations first and keeps runtime or shared-image removal
@@ -85,15 +118,16 @@ loads.
 
 ## Supported today
 
-| Environment                                 | Support                |
-| ------------------------------------------- | ---------------------- |
-| Supabase CLI projects                       | Supported              |
-| Ordinary PostgreSQL in local Docker         | Supported              |
-| macOS and Linux                             | Supported              |
-| WSL                                         | Experimental           |
-| Native Windows                              | Not yet supported      |
-| Hosted database URLs                        | Intentionally rejected |
-| MySQL, MongoDB, and other database families | Not yet supported      |
+| Environment                                      | Support                |
+| ------------------------------------------------ | ---------------------- |
+| Supabase CLI projects                            | Supported              |
+| Ordinary PostgreSQL in local Docker              | Supported              |
+| macOS and Linux                                  | Supported              |
+| WSL                                              | Experimental           |
+| Native Windows                                   | Not yet supported      |
+| Hosted database URLs                             | Intentionally rejected |
+| Optional read-only PostgreSQL source preparation | Explicit opt-in beta   |
+| MySQL, MongoDB, and other database families      | Not yet supported      |
 
 See [COMPATIBILITY.md](COMPATIBILITY.md) for the exact support contract.
 
@@ -101,6 +135,7 @@ See [COMPATIBILITY.md](COMPATIBILITY.md) for the exact support contract.
 
 Start here:
 
+- [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
@@ -110,12 +145,17 @@ Reference:
 
 - [CLI commands](docs/commands.md)
 - [Configuration](docs/configuration.md)
+- [TypeScript types](docs/typescript.md)
 - [Baselines](docs/baselines.md)
 - [Sanitization](docs/sanitization.md)
 - [Security model](docs/security-model.md)
 - [Project adapters](docs/adapters.md)
 - [Production data boundary](docs/production-source.md)
-- [Glossary and architecture](docs/glossary.md)
+- [Standalone workflow and security gates](docs/standalone-workflow.md)
+- [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
@@ -133,13 +173,20 @@ 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
+npm run test:fixture:standalone
 npm run test:fixture:postgresql
 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
+```