@rehearsal-db/core 0.1.0-beta.4 → 0.1.0-beta.6

package/CHANGELOG.md

@@ -5,6 +5,58 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## Unreleased
 
+## [0.1.0-beta.6] - 2026-10-02
+
+### Changed
+
+- Beginner documentation now follows one guided path, defines unfamiliar terms where
+  they first appear, provides a disposable PostgreSQL tutorial, and keeps advanced detail
+  in focused reference pages.
+- Pressing `Ctrl+Z` at an interactive guide prompt now exits Rehearsal cleanly instead
+  of suspending the process and leaving it attached to the terminal.
+- Database lifecycle selection now goes through a closed runtime-driver boundary while
+  preserving Supabase as the backward-compatible default. This created the safe,
+  testable seam used by the PostgreSQL target without changing existing configurations.
+- The installed-package proof now chooses an available local port block and a unique
+  project identity, so local verification does not collide with another Rehearsal run.
+
+### Added
+
+- An ordinary PostgreSQL runtime target with guided setup, loopback-only Docker
+  isolation, exact migration receipts, baseline restore, application proof, lifecycle
+  commands, and a separate installed-package integration proof.
+- PostgreSQL setup refuses implicit image downloads and Supabase-only Storage baselines,
+  uses a fresh random local password per runtime, and requires exact Rehearsal ownership
+  labels before removing resources.
+
+### Fixed
+
+- Plain-terminal nested menus now print their choices before asking for a number,
+  including database selection, discovered baseline inputs, and runtime management.
+
+## [0.1.0-beta.5] - 2026-10-01
+
+### Added
+
+- Scalable policy review with explicit table-level safe defaults, suggested structural
+  exceptions, per-table summaries, and real-PTY coverage of the bulk-review journey.
+- Bounded project-local discovery for baseline records, migration ledgers, and optional
+  Storage manifests, plus a value-free structural preflight before activation.
+- A guided `Get help` action and scriptable `rehearsal support` report with tool
+  versions, readiness statuses, privacy guarantees, and a direct bug-report link.
+
+### Changed
+
+- Guided policy review can classify ordinary columns in bulk as synthetic replacements
+  while keeping likely identifiers, relationships, and timestamps selected for
+  individual review. The saved policy still records every required column decision.
+- The baseline guide offers detected inputs instead of requiring memorized paths,
+  validates referenced Storage files up front, previews counts without row values, and
+  returns to the guide with an actionable message when validation fails.
+- Beta support no longer requires users to assemble environment details by hand; the
+  generated report omits project paths, row values, credentials, migration SQL, and
+  baseline identifiers and remains available before setup is complete.
+
 ## [0.1.0-beta.4] - 2026-10-01
 
 ### Added
@@ -118,7 +170,9 @@ 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.4...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.6...HEAD
+[0.1.0-beta.6]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.5...v0.1.0-beta.6
+[0.1.0-beta.5]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.4...v0.1.0-beta.5
 [0.1.0-beta.4]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.3...v0.1.0-beta.4
 [0.1.0-beta.3]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.2...v0.1.0-beta.3
 [0.1.0-beta.2]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.1...v0.1.0-beta.2

package/COMPATIBILITY.md

@@ -20,3 +20,8 @@ or successful verification receipt.
 The first stable `1.0.0` requires external beta evidence, a support policy, and a settled
 public API. Supporting additional database families, package managers, or operating
 systems is not implied by the 0.x contract.
+
+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.

package/README.md

@@ -1,401 +1,138 @@
 # Rehearsal
 
-Rehearsal tests pending Supabase migrations against a verified, sanitized,
-production-shaped baseline in a disposable local environment. It is designed for the
-historical edge cases that synthetic seed data rarely represents.
+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.
 
-Version 0.1 targets Supabase CLI projects running PostgreSQL locally. It does not yet
-claim support for arbitrary unmanaged PostgreSQL installations.
+Rehearsal never connects to a hosted database. It is a migration-testing tool, not a
+backup system or a production deployment tool.
 
-Public beta releases are distributed through npm as `@rehearsal-db/core`. Publication is
-restricted to reviewed artifacts from protected `main`; source availability alone does
-not enable production access.
+> Rehearsal is in public beta. Use it on a branch and keep a working backup of your
+> project.
 
-## Documentation
+## What you need
 
-- [Getting started](docs/getting-started.md)
-- [End-to-end tutorial](docs/tutorial.md)
-- [Configuration reference](docs/configuration.md)
-- [CLI commands](docs/commands.md)
-- [Sanitization policy](docs/sanitization.md)
-- [Production source boundary](docs/production-source.md)
-- [Baselines](docs/baselines.md)
-- [Project adapters](docs/adapters.md)
-- [Security model](docs/security-model.md)
-- [Troubleshooting](docs/troubleshooting.md)
-- [Release process](docs/releasing.md)
-- [Glossary and architecture](docs/glossary.md)
+- Node.js 24 and npm
+- Docker Desktop, Colima, or another Docker-compatible engine
+- timestamped `.sql` migration files
+- a project test command that can prove the migrated application works
+- Supabase CLI 2.117.0 for a Supabase project, or the local
+  `postgres:17-alpine` image for a PostgreSQL project
 
-## Why use it?
+No database experience is required to follow the guide, but you should understand what
+your migration is intended to change.
 
-A migration passing against an empty database proves only that the migration can build
-a new schema. Rehearsal also proves that:
+## Quick start
 
-- the baseline is the exact immutable artifact you reviewed;
-- historical migration files still match the baseline's digest-addressed prefix;
-- only the exact suffix is treated as candidate work;
-- production-shaped relationships survive restore and migration;
-- optional bounded Storage objects retain exact checksums through local restore;
-- the resulting local application can pass a project-owned proof;
-- unsafe or ambiguous state stops execution.
+From your project directory:
 
-## What Rehearsal is—and is not
+```bash
+npm install --save-dev @rehearsal-db/core@beta
+npx rehearsal
+```
 
-Rehearsal complements existing database workflows instead of replacing them:
+The guide shows your progress and offers the next safe action. On first use, choose
+**Set the stage**, select Supabase or PostgreSQL, review the preview, and confirm the files
+it will create. Existing files are never overwritten.
 
-| Tool or environment                             | Primary job                                 | What Rehearsal adds                                                                                                        |
-| ----------------------------------------------- | ------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| Backups and point-in-time recovery              | Recover lost production data                | A disposable, writable migration test; Rehearsal is not disaster recovery.                                                 |
-| Staging                                         | Exercise an integrated deployed application | A local resettable database shaped by reviewed production history, without giving the runtime a hosted target.             |
-| Synthetic seed data                             | Create small, known test scenarios          | Sanitized production-shaped relationships and historical edge cases, when the project explicitly authorizes them.          |
-| Database branches or preview databases          | Isolate hosted database changes             | A loopback-only runtime with immutable baseline checks, exact candidate confirmation, and project-owned acceptance proofs. |
-| Migration linters and migration-only test tools | Inspect SQL or prove a migration applies    | Restore, migrate, run the real application proof, preserve sandbox edits, and reset to the verified baseline.              |
+For PostgreSQL, download the reviewed local image once before running the guide:
 
-The package does not extract production data. A project may use Rehearsal entirely with
-synthetic data, or build its own least-privilege extraction and sanitization boundary.
-The current beta runs local Supabase services and therefore does not support an arbitrary
-unmanaged PostgreSQL server.
+```bash
+docker pull postgres:17-alpine
+```
 
-## Local cost and storage
+Rehearsal itself never downloads a database image during a rehearsal.
 
-Rehearsal itself has no hosted-service fee and never creates a cloud database. Normal
-local costs are Docker CPU, memory, and disk space for Supabase images, the immutable
-baseline, optional retained Storage assets, and the disposable runtime. Production-shaped
-artifacts can be large: review their manifest size before activation, keep bounded
-retention, and use `rehearsal discard` when the runtime is no longer needed. Deleting the
-runtime does not delete the immutable baseline; baseline retention remains a project-owned
-privacy and disk-management decision.
+## Three terms you will see
 
-The restored runtime is intentionally writable. Exact baseline row counts and foreign
-keys are proved during reset before the runtime is accepted; later verification allows
-row-level divergence from sandbox interaction or candidate data migrations while still
-checking the immutable artifact, migration lineage, runtime boundary, and project-owned
-invariants. Reset restores and reproves the exact starting data.
+- **Baseline:** a locked, safe starting copy of your schema and test data.
+- **Candidate migration:** a new migration that is not part of the baseline yet.
+- **Runtime:** the disposable local database where the rehearsal happens.
 
-## Quick start
+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.
 
-Install the current beta from npm:
+## The normal workflow
 
-```bash
-npm install --save-dev @rehearsal-db/core@beta
-```
+1. Run `npx rehearsal`.
+2. Let the guide create the local-only configuration.
+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.
 
-Contributors testing an unreleased change can use `npm link` or install the tarball
-produced by `npm pack` from a local checkout. In a consuming project, the commands are:
+Press `Ctrl+Z` at any guided prompt to exit the whole session. Choose **Get help**, or run
+`npx rehearsal support`, to create a privacy-safe diagnostic report.
 
-```bash
-npx rehearsal
-npx rehearsal setup
-npx rehearsal setup --write
-npx rehearsal init
-npx rehearsal init --write
-npx rehearsal baseline prepare --records=<safe.ndjson> --ledger=<ledger.json>
-npx rehearsal baseline prepare --records=<safe.ndjson> --ledger=<ledger.json> --write
-npx rehearsal baseline create --records=<safe.ndjson> --ledger=<ledger.json>
-npx rehearsal doctor
-npx rehearsal explain
-npx rehearsal run --dry-run
-npx rehearsal candidates
-npx rehearsal inspect baseline
-npx rehearsal inspect migrations
-npx rehearsal start
-npx rehearsal migrate --confirm-candidates=<sha256>
-npx rehearsal status
-npx rehearsal verify
-npx rehearsal reset
-npx rehearsal stop
-npx rehearsal discard
-```
+## What Rehearsal protects
+
+- The database listens only on your computer.
+- Hosted database credentials are removed from child processes.
+- The approved baseline and migration history are checksum-verified.
+- A changed migration produces a new approval digest.
+- Failed migrations cannot leave a runtime marked as trusted.
+- Runtime cleanup targets only resources carrying the exact Rehearsal labels.
+
+Rehearsal does not prove that a migration is correct for every user workflow. Your
+project's proof command should test the behavior that matters, not only whether a page
+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      |
+
+See [COMPATIBILITY.md](COMPATIBILITY.md) for the exact support contract.
+
+## Documentation
+
+Start here:
+
+- [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
 
-Running `npx rehearsal` in a terminal opens a state-aware guide that shows completed
-setup steps and recommends available actions. The guide stays open after each action,
-re-inspects the project, and advances to the next useful step. It includes an interactive
-column-by-column policy reviewer, concise completion receipts, and optional technical
-details. The explicit commands remain the stable interface for automation and CI.
-
-`setup` previews a conservative first-run scaffold: the Rehearsal configuration, a
-dedicated local-only Supabase configuration on an available port block, and protective
-`.gitignore` entries. It writes only with `--write`, never overwrites project files, and
-does not copy enabled external providers from the application's Supabase configuration.
-After writing, it runs the same readiness checks as `doctor` and shows the remaining
-project-owned inputs. Use `init` when you want to create only the configuration file
-manually.
-
-`baseline prepare` inspects only the shape of explicit local synthetic records and writes
-a fail-closed sanitization-policy draft. Every column remains `REVIEW REQUIRED` until a
-human classifies its sanitization action, generated/identity behavior, and foreign key.
-Drafts cannot be activated, and a reviewed policy is checksum-bound to its baseline.
-
-`init` previews a type-aware ESM `rehearsal.config.mjs`; it writes only with `--write`
-and never overwrites an existing file. The explicit `.mjs` extension makes the generated
-configuration executable in both CommonJS and ESM projects. Review all detected values.
-Rehearsal intentionally does not detect, copy, or enable a hosted project.
-
-`doctor` must end with `READY` before execution. `explain` and `run --dry-run` use the
-same immutable planner and perform no state-changing operations. In a terminal,
-`rehearsal run` displays and confirms the exact candidate set before touching the local
-runtime. Automation supplies the digest explicitly:
+Reference:
+
+- [CLI commands](docs/commands.md)
+- [Configuration](docs/configuration.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)
+- [Release process](docs/releasing.md)
+
+## Getting support
+
+Run:
 
 ```bash
-npx rehearsal run --confirm-candidates=<sha256>
+npx rehearsal support
 ```
 
-The `rehearsal` executable is the public command contract. Repository availability does
-not itself authorize an npm publication.
-
-To try the entire workflow without configuring a project or touching hosted data, clone
-this repository and run `npm ci --ignore-scripts && npm run test:fixture`. It installs
-the exact packed artifact into a clean synthetic Supabase project and proves both
-success and failure.
-
-## Configuration
-
-Configuration has an explicit schema version. Version 1 rejects unknown versions,
-unknown properties, paths outside the project root, non-loopback targets, duplicate or
-privileged ports, enabled hosted access, and permissive outbound networking.
-
-```ts
-import { defineRehearsalConfig } from "@rehearsal-db/core";
-
-export default defineRehearsalConfig({
-  schemaVersion: 1,
-  project: { name: "my-supabase-app" },
-  supabase: {
-    workdir: ".",
-    migrationDirectory: "supabase/migrations",
-    rehearsalConfig: "infrastructure/rehearsal/supabase/config.toml",
-    runtimeWorkdir: ".rehearsal/runtime",
-    serviceEnvironmentFile: ".env.rehearsal-service.local",
-    serviceEnvironmentVariables: [
-      "LOCAL_IDENTITY_CLIENT_ID",
-      "LOCAL_IDENTITY_SECRET",
-    ],
-  },
-  baseline: {
-    artifactDirectory: ".rehearsal",
-    sanitizationPolicy: "infrastructure/rehearsal/sanitization-policy.json",
-  },
-  application: {
-    startCommand: "npm run dev:rehearsal",
-    proofCommand: "npm run test:rehearsal",
-    environmentFile: ".rehearsal/runtime.env",
-  },
-  runtime: {
-    applicationUrl: "http://localhost:5175",
-    projectId: "my-app-rehearsal",
-    apiPort: 58321,
-    databasePort: 58322,
-    studioPort: 58323,
-  },
-  safety: {
-    allowedHosts: ["127.0.0.1", "::1", "localhost"],
-    blockedEnvironmentVariables: [
-      "SUPABASE_ACCESS_TOKEN",
-      "SUPABASE_DB_PASSWORD",
-      "SUPABASE_PROJECT_ID",
-    ],
-    authenticationProviders: ["example-identity-provider"],
-    hostedAccess: "disabled",
-    outboundNetwork: "deny",
-  },
-  verification: { commands: ["npm run test:rehearsal"] },
-});
-```
+Review the result, then include it in a
+[GitHub issue](https://github.com/Ddupasquier/rehearsal-db/issues). Never share database
+rows, credentials, connection strings, private migrations, or baseline files. Security
+problems belong in the private process described in [SECURITY.md](SECURITY.md).
 
-| Property                               | Type       | Required | Default                   | Meaning and safety effect                                     |
-| -------------------------------------- | ---------- | -------- | ------------------------- | ------------------------------------------------------------- |
-| `schemaVersion`                        | `1`        | Yes      | None                      | Pins configuration meaning; unknown versions fail.            |
-| `project.name`                         | `string`   | Yes      | None                      | Stable lowercase local identifier.                            |
-| `supabase.workdir`                     | `string`   | Yes      | None                      | Project-owned Supabase workdir; cannot escape the project.    |
-| `supabase.migrationDirectory`          | `string`   | Yes      | None                      | Ordered application migration source.                         |
-| `supabase.rehearsalConfig`             | `string`   | Yes      | None                      | Dedicated unlinked local Supabase configuration.              |
-| `supabase.runtimeWorkdir`              | `string`   | Yes      | None                      | Must be `<artifactDirectory>/runtime`; always disposable.     |
-| `supabase.serviceEnvironmentFile`      | `string`   | No       | None                      | Owner-only ignored credentials for the local service stack.   |
-| `supabase.serviceEnvironmentVariables` | `string[]` | No       | `[]`                      | Exact variables accepted from the service environment file.   |
-| `baseline.artifactDirectory`           | `string`   | No       | `.rehearsal`              | Must be named `.rehearsal`; deletion-safe artifact boundary.  |
-| `baseline.sanitizationPolicy`          | `string`   | Yes      | None                      | Exhaustive project-owned classification policy.               |
-| `application.startCommand`             | `string`   | Yes      | None                      | Starts the app against the verified local runtime.            |
-| `application.proofCommand`             | `string`   | Yes      | None                      | Project-owned proof after migration.                          |
-| `application.environmentFile`          | `string`   | No       | `.rehearsal/runtime.env`  | Owner-only generated local runtime variables.                 |
-| `application.runtimeAdapter`           | `string`   | No       | None                      | Advanced project-owned post-restore adapter path.             |
-| `runtime.applicationUrl`               | URL        | No       | `http://localhost:5175`   | Must use an explicitly allowed loopback host.                 |
-| `runtime.projectId`                    | `string`   | No       | `rehearsal-local`         | Dedicated local Supabase/Docker identity.                     |
-| `runtime.apiPort`                      | TCP port   | Yes      | None                      | Dedicated non-privileged API port.                            |
-| `runtime.databasePort`                 | TCP port   | Yes      | None                      | Dedicated non-privileged PostgreSQL port.                     |
-| `runtime.studioPort`                   | TCP port   | Yes      | None                      | Dedicated non-privileged Studio port.                         |
-| `safety.allowedHosts`                  | `string[]` | No       | loopback hosts            | Version 1 rejects any non-loopback entry.                     |
-| `safety.blockedEnvironmentVariables`   | `string[]` | No       | Supabase hosted variables | Ambient values excluded from child processes.                 |
-| `safety.authenticationProviders`       | `string[]` | No       | `[]`                      | Declared identity-only external exchanges.                    |
-| `safety.hostedAccess`                  | `disabled` | No       | `disabled`                | Cannot be enabled in version 1.                               |
-| `safety.outboundNetwork`               | `deny`     | No       | `deny`                    | Cannot be weakened in version 1.                              |
-| `verification.commands`                | `string[]` | No       | `[]`                      | Additional declared project checks; commands remain explicit. |
-
-Most projects should not use `runtimeAdapter`. It exists for a project that must create
-synthetic local identities or add application-specific variables after a successful
-restore. The adapter is project-owned, receives only the verified local environment and
-baseline plus a local PostgreSQL executor, and is never bundled into the reusable
-package. Its `configureRuntime` export returns a status message and explicit environment
-variables. It must not read hosted credentials or perform network work.
-
-## What each command proves
-
-### `rehearsal doctor`
-
-Doctor checks Node 24, the Supabase CLI, a running Docker-compatible engine, required
-paths, config/runtime port agreement, baseline checksums and permissions, migration
-prefix integrity, application proof command ownership, and the fail-closed safety
-policy. Ambient hosted credential variables are reported only by name and remain
-quarantined from children.
-
-### `rehearsal explain` and `rehearsal run --dry-run`
-
-Both return the same plan data. They may read and hash configuration, migrations,
-policy, and baseline metadata. They never start or stop services, restore rows, apply a
-migration, launch the application, write a receipt, change an artifact, or contact a
-hosted resource.
-
-### `rehearsal inspect baseline`
-
-Inspection prints format and generation identifiers, the migration cutoff, table and
-row counts, and hashes for baseline data and sanitization policy. It never prints source
-rows or baseline values.
-
-### `rehearsal inspect migrations`
-
-Every local migration receives one interpretation:
-
-- `represented_by_baseline`: exact filename and SHA-256 in the baseline prefix;
-- `candidate`: exact suffix after that prefix, not yet proven in the current runtime;
-- `applied_to_current_runtime`: the exact suffix digest has a verified local receipt;
-- `modified`: a prefix filename or digest changed, so planning fails closed;
-- `invalid`: filename, ordering, uniqueness, or source structure is invalid.
-
-`rehearsal candidates` is the concise machine-friendly alias for this same migration
-inspection and exact candidate digest. It does not apply a migration.
-
-## Machine output and exit codes
-
-Commands that report state accept `--json`. The version-1 envelope contains
-`schemaVersion`, `command`, `status`, `startedAt`, `durationMs`, `warnings`, and `data`.
-Failures contain a versioned error with category, stable code, message, expected and
-actual state, context, refused action, suggestions, and a safe diagnostic identifier.
-
-| Exit | Category                       |
-| ---- | ------------------------------ |
-| 0    | Success                        |
-| 1    | Doctor completed but not ready |
-| 2    | Configuration invalid          |
-| 3    | Unsafe environment             |
-| 4    | Baseline invalid               |
-| 5    | Baseline checksum mismatch     |
-| 6    | Migration candidate failure    |
-| 7    | Migration verification failure |
-| 8    | Application proof failure      |
-| 9    | Runtime or dependency failure  |
-| 10   | Unexpected internal failure    |
-
-Human and JSON output are projections of the same model. `normal`, `--verbose`, and
-`--debug` increase explanation only; none may print secrets or baseline row values.
-
-## Guarantees
-
-Rehearsal version 1 intends to guarantee:
-
-- configuration and runtime targets are local-only;
-- hosted application/database credentials are neither required nor inherited by child processes;
-- application, provider-data, email, and hosted-database side effects fail closed;
-- any declared external identity exchange terminates in the local Auth service and its
-  credentials are read from an exact owner-only allowlist;
-- an active baseline verifies before restore;
-- migration identity uses ordered content digests, not timestamps alone;
-- a changed prefix is never silently reinterpreted as a candidate;
-- restore and migration failures cannot leave a runtime marked trusted;
-- reports omit source rows and redact credentials, connection strings, keys, tokens,
-  JWTs, passwords, and sensitive environment values.
-
-Independent barriers include strict loopback config, a dedicated unlinked Supabase
-workdir/project ID, an allowlisted child environment, and application egress denial.
-A project may explicitly declare an external identity provider, but that does not grant
-hosted application/database access. A single ambient connection string is therefore
-insufficient to redirect an operation.
-
-## Non-guarantees and user responsibilities
-
-Rehearsal does not prove that a migration is semantically correct for every application
-workflow, replace backups or disaster recovery, authorize production access, or make a
-sanitization policy correct merely because it is exhaustive. Project owners must review
-the policy, protect baseline artifacts, write meaningful application proofs, review the
-candidate digest, and keep production credentials outside the Rehearsal configuration.
-
-## Baseline lifecycle
-
-The source boundary exposes only reviewed versioned views through a least-privilege
-read-only role. Every included column has an explicit KEEP, PSEUDONYMIZE, REPLACE,
-EXCLUDE, or DERIVE action. Sanitized rows stream into an owner-only build directory.
-Only after exact hashes, counts, migration receipts, and policy metadata exist does an
-atomic pointer activate the generation. Failed builds cannot replace the current
-baseline.
+## For contributors
 
-Restore replays the immutable historical migration bundle, streams sanitized rows into
-the disposable local database, restores optional checksummed Storage assets through the
-loopback service, restores normal enforcement, and verifies counts and foreign keys
-before candidate work begins. The package accepts project-owned asset bytes; it does not
-know how to authorize or extract them from a hosted source.
-
-Project policies may attach field-aware JSON rules and project-owned identity adapters.
-A consuming project can use those boundaries to preserve reviewed application data
-while sanitizing unrelated private values, without teaching the package its table
-names, identity relationships, or privacy decisions.
-
-## CI example
-
-The tracked [verification workflow](.github/workflows/verify.yml) is intentionally based
-on the synthetic independent fixture. A real repository should provide its own protected
-sanitized baseline through an approved artifact mechanism; never commit production data
-or credentials just to make CI convenient.
-
-## Run the independent proof
-
-From this repository on Node.js 24 with Docker running:
+Use Node.js 24, run `npm ci`, then run:
 
 ```bash
+npm run check
+npm run test:fixture:postgresql
 npm run test:fixture
 ```
 
-The proof copies the tracked synthetic fixture to a disposable directory, builds its
-one-row and one-asset baseline, runs the public CLI through one valid migration and
-application proof, verifies the exact Storage byte, then introduces invalid PostgreSQL.
-Success means the valid migration preserved its row and asset, the invalid migration
-received the intended stable failure category, and the untrusted runtime was removed.
-It neither needs nor inherits application-specific or hosted credentials.
-
-## Support matrix for the first beta
-
-| Runtime or tool  | Status       | Initial contract                                      |
-| ---------------- | ------------ | ----------------------------------------------------- |
-| Node.js 24       | Supported    | Exact maintained major                                |
-| npm              | Supported    | Lockfile-backed install and CLI                       |
-| macOS            | Supported    | Directly exercised with Docker/Colima                 |
-| Linux            | Supported    | Ubuntu x64 CI and Bookworm arm64 Colima proofs        |
-| WSL              | Experimental | Must be exercised and documented before support claim |
-| Native Windows   | Unsupported  | Path, Docker, signal, and shell behavior unproven     |
-| pnpm             | Unsupported  | Detection is informational until direct proof exists  |
-| Yarn             | Unsupported  | Detection is informational until direct proof exists  |
-| MySQL/Mongo/etc. | Unsupported  | Version 1 is PostgreSQL/Supabase only                 |
-
-## Troubleshooting
-
-- `NOT READY` after Docker: start Docker Desktop or Colima, then rerun doctor.
-- Baseline checksum mismatch: do not repair the hash manually. Rebuild through the
-  reviewed extraction/sanitization workflow.
-- Migration prefix divergence: restore the exact reviewed historical file or create a
-  new baseline; never rename the edited file into the candidate suffix.
-- Candidate confirmation mismatch: rerun explain, review the exact ordered candidates,
-  and use the new digest only if those files are intended.
-- Hosted target refusal: remove the hosted value. Version 1 has no override.
-- Application proof failure: inspect the project-owned proof output; the database must
-  not be treated as verified.
-
-Security reporting, compatibility promises, and regression measurements are defined in
-[SECURITY.md](SECURITY.md), [COMPATIBILITY.md](COMPATIBILITY.md), and
-[BENCHMARKS.md](BENCHMARKS.md).
+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.

package/SECURITY.md

@@ -12,7 +12,8 @@ Supported security updates cover the latest released 0.x minor during beta. A se
 fix may deliberately tighten configuration or refuse a workflow that an earlier beta
 accepted. During beta, reports apply to the latest published release and current `main`.
 
-The threat boundary and explicit non-guarantees live in [README.md](README.md). Every
+The threat boundary and remaining responsibilities live in
+[docs/security-model.md](docs/security-model.md). Every
 release candidate must pass secret-pattern checks, dependency and package-content
 audits, the installed Linux fixture, and private-reporting verification. The current
 platform evidence covers protected Ubuntu x64 CI and a direct Bookworm arm64 Colima run;

package/SUPPORT.md

@@ -6,6 +6,11 @@ Docker engine, the failing command, safe diagnostics, and the smallest reproduct
 The first beta does not yet maintain a separate public discussion or feature-request
 channel.
 
+Run `npx rehearsal support` or choose **Get help** in the guide to collect the environment
+and readiness portion without assembling it by hand. The report intentionally excludes
+project paths, row values, credentials, migration SQL, and baseline identifiers. Review
+the report before pasting it into an issue.
+
 Do not include credentials, connection strings, source rows, baseline artifacts, private
 URLs, or proprietary migrations. Report security problems through private vulnerability
 reporting as described in [SECURITY.md](SECURITY.md).

package/docs/adapters.md

@@ -1,5 +1,10 @@
 # Project runtime adapters
 
+These project-owned hooks are different from Rehearsal's database runtime drivers. A
+database driver starts and manages a kind of local database, such as Supabase or plain
+PostgreSQL. A project
+runtime adapter adds narrowly scoped application behavior after that database is ready.
+
 Adapters are an advanced escape hatch for project-specific restore behavior. They live
 in the consuming repository and are loaded only from the path declared in config.