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

package/docs/getting-started.md

@@ -1,282 +1,151 @@
 # Getting started
 
-This guide creates a safe local Rehearsal project from synthetic data. It does not
-connect to production, request hosted credentials, or require an existing baseline.
+This guide sets up Rehearsal in an existing project. It creates a disposable database on
+your computer and never connects to a hosted database.
 
-## Prerequisites
+Want to experiment first? Use the [safe hands-on tutorial](tutorial.md).
 
-- Node.js 24
-- npm
-- Supabase CLI 2.117.0 (the version proved by package CI)
-- Docker Desktop, Colima, or another Docker-compatible engine
-- a Supabase project with timestamped SQL migrations
+## 1. Check the required tools
 
-Confirm the tools first:
+You need Node.js 24, npm, and a running Docker-compatible engine:
 
 ```bash
 node --version
 npm --version
-supabase --version
 docker info
 ```
 
-If you want to see the complete lifecycle before touching your own project, clone the
-Rehearsal repository and run:
+`node --version` must begin with `v24`. If `docker info` fails, start Docker Desktop,
+Colima, or your usual Docker engine.
 
-```bash
-npm ci --ignore-scripts
-npm run test:fixture
-```
+Choose the extra requirement for your project:
 
-That proof installs the packed package into a disposable fictional project, restores a
-row and Storage object, applies a valid migration, rejects invalid SQL, and removes only
-its labeled local runtime. It does not need a hosted Supabase project or credentials.
+- **Supabase:** install Supabase CLI 2.117.0 and run `supabase --version`.
+- **PostgreSQL:** download the local database image once:
 
-## 1. Install and initialize
+  ```bash
+  docker pull postgres:17-alpine
+  ```
 
-Confirm this shell is running the supported Node.js major before installing:
+Rehearsal will use that image with downloads disabled.
 
-```bash
-node --version # v24.x
-```
+## 2. Install and open the guide
+
+Run these commands from the directory containing your project's `package.json`:
 
 ```bash
 npm install --save-dev @rehearsal-db/core@beta
 npx rehearsal
 ```
 
-Choose **Set up Rehearsal** in the guide. It previews a versioned configuration, a
-dedicated local-only Supabase configuration using available ports, and protective
-`.gitignore` entries before asking permission to write. The guide remains open afterward
-and recommends the next incomplete stage.
+Choose **Set the stage**, then choose Supabase or PostgreSQL. Rehearsal previews every file
+before asking to create it. It will not replace an existing file.
 
-The same flow is available noninteractively as an explicit preview and write:
+Review the generated `rehearsal.config.mjs`, especially:
 
-```bash
-npx rehearsal setup
-npx rehearsal setup --write
-```
+- the migration directory;
+- the application start and proof commands;
+- the local ports.
 
-Rehearsal never overwrites an existing configuration. For config-only/manual setup, use
-`npx rehearsal init` followed by `npx rehearsal init --write`.
+The proof command should check behavior changed by the migration. A test that only checks
+whether the home page loads is usually too weak.
 
-The generated configuration is intentionally incomplete until you review its ports,
-project ID, application commands, and project-owned input paths. Do not run `doctor`
-until the next section's files exist.
+## 3. Prepare safe baseline inputs
 
-## 2. Add the project-owned inputs
+A **baseline** is the locked starting point restored before each rehearsal. Start with a
+small synthetic dataset. Do not use raw production data.
 
-Review or create the project-owned inputs named by `rehearsal.config.mjs`:
+Rehearsal needs:
 
-- the dedicated local Supabase `config.toml` (`setup` creates a conservative one);
-- a sanitization policy describing every exported field;
-- an active baseline below `.rehearsal/`;
-- an application proof command that exits nonzero when the restored app is wrong.
+| Input               | What it contains                                     |
+| ------------------- | ---------------------------------------------------- |
+| Records             | Safe rows in NDJSON format: one JSON object per line |
+| Migration ledger    | The historical migrations represented by those rows  |
+| Sanitization policy | A decision for every included table and column       |
+| Storage manifest    | Optional Supabase Storage files only                 |
 
-If you used config-only `init`, also create the dedicated Supabase config manually:
+A record looks like this:
 
-```bash
-mkdir -p infrastructure/rehearsal/supabase infrastructure/rehearsal rehearsal
-cp supabase/config.toml infrastructure/rehearsal/supabase/config.toml
+```json
+{ "table": "widgets", "row": { "id": 1, "name": "Synthetic Widget" } }
 ```
 
-Edit the copied Supabase config. Give it the same unique `project_id`, API port, database
-port, and Studio port used by `rehearsal.config.mjs`. Disable services your proof does
-not need. This must remain an unlinked local config; never run `supabase link` from it.
+Put your safe records and ledger inside the project. Conventional names such as
+`rehearsal/sanitized-data.ndjson` and `rehearsal/migration-ledger.json` are discovered
+automatically. The guide inspects their structure but does not print row values.
 
-Also replace the generated `application.startCommand`, `application.proofCommand`, and
-`verification.commands` with real commands from your project. The proof should check a
-restored relationship and the candidate schema—not merely that `/` returns 200.
+Follow the guide's recommended actions:
 
-Start with synthetic rows shaped like your schema. Do not start onboarding with
-production data. The following SQL, policy, row, and ledger form one matched example;
-do not mix them with differently shaped snippets.
+1. **Prepare the script** creates a draft sanitization policy.
+2. **Review the script** asks you to classify every table and column.
+3. **Create the baseline** validates and activates the reviewed inputs.
 
-If you already have the safe NDJSON rows and migration ledger, Rehearsal can enumerate
-their table and column shape into a fail-closed policy draft without printing values:
-
-```bash
-npx rehearsal baseline prepare \
-  --records=rehearsal/synthetic-data.ndjson \
-  --ledger=rehearsal/migration-ledger.json
-npx rehearsal baseline prepare \
-  --records=rehearsal/synthetic-data.ndjson \
-  --ledger=rehearsal/migration-ledger.json \
-  --write
-```
+Rehearsal will not activate a policy containing undecided fields.
 
-After creating the draft, choose **Review the script** in the guide. Rehearsal walks each
-column through sanitization action, generated status, identity status, and optional
-foreign-key metadata. Every answer is explicit, the complete policy is validated before
-writing, and the original draft is replaced only if it did not change during review.
+The ledger must describe the exact historical SQL included in the baseline. Do not type
+years of migration history by hand for a real project. Generate it through reviewed
+project tooling. The [tutorial](tutorial.md) contains a complete synthetic example, and
+[Baselines](baselines.md) explains the file formats.
 
-For noninteractive workflows, review every `REVIEW REQUIRED` field directly and remove
-`"draft": true` only after that review. Rehearsal refuses to activate a draft.
+## 4. Reach READY
 
-Historical migration `supabase/migrations/20260101000000_create_widgets.sql`:
+The guide displays four setup stages. Continue with its recommended action until all
+checks are complete and the project reports `READY`.
 
-```sql
-create table public.widgets (
-	id bigint generated by default as identity primary key,
-	name text not null,
-	created_at timestamptz not null default now()
-);
+You can run the same check directly:
 
-insert into storage.buckets (id, name, public)
-values ('fixture-assets', 'fixture-assets', false);
+```bash
+npx rehearsal doctor
 ```
 
-Sanitization policy `infrastructure/rehearsal/sanitization-policy.json`:
-
-```json
-{
-  "policyVersion": 1,
-  "migrationCutoff": "20260101000000",
-  "tables": [
-    {
-      "name": "widgets",
-      "group": "synthetic",
-      "sourceRows": "STREAM AND SANITIZE",
-      "columns": [
-        {
-          "name": "id",
-          "action": "KEEP EXACTLY",
-          "generated": "NEVER",
-          "identity": "YES",
-          "foreignKey": null
-        },
-        {
-          "name": "name",
-          "action": "REPLACE WITH SYNTHETIC",
-          "generated": "NEVER",
-          "identity": "NO",
-          "foreignKey": null
-        },
-        {
-          "name": "created_at",
-          "action": "DERIVE",
-          "generated": "NEVER",
-          "identity": "NO",
-          "foreignKey": null
-        }
-      ]
-    }
-  ]
-}
-```
+If it reports `NOT READY`, fix the listed item and run it again. Do not bypass a check or
+add a hosted connection string.
 
-Safe row `rehearsal/synthetic-data.ndjson` (one JSON object per physical line):
+## 5. Run the rehearsal
 
-```json
-{
-  "table": "widgets",
-  "row": {
-    "id": 1,
-    "name": "Synthetic Widget",
-    "created_at": "2026-01-01T00:00:00.000Z"
-  }
-}
-```
+Choose **Run a rehearsal**. Rehearsal shows the exact candidate migrations and asks for
+confirmation before it changes the disposable runtime.
 
-Migration ledger `rehearsal/migration-ledger.json`:
+A successful run:
 
-```json
-[
-  {
-    "version": "20260101000000",
-    "name": "create_widgets",
-    "statements": [
-      "create table public.widgets (\n\tid bigint generated by default as identity primary key,\n\tname text not null,\n\tcreated_at timestamptz not null default now()\n)",
-      "insert into storage.buckets (id, name, public)\nvalues ('fixture-assets', 'fixture-assets', false)"
-    ]
-  }
-]
-```
+1. restores the baseline;
+2. applies only the migrations you approved;
+3. verifies the local database;
+4. runs your application proof.
 
-The ledger is evidence, not a second migration language. Its version, name, order, and
-statements must exactly represent the historical migration bytes in the baseline. SQL
-that is merely equivalent is rejected. For a production-shaped baseline, generate this
-ledger through the project's reviewed source/export tooling; do not reconstruct years of
-history by hand.
+Your original baseline remains unchanged.
 
-Then activate the safe input:
+## 6. Test and clean up
 
-```bash
-npx rehearsal baseline create \
-  --records=rehearsal/synthetic-data.ndjson \
-  --ledger=rehearsal/migration-ledger.json
-```
+Use the guide for normal runtime tasks:
 
-The independent fixture in this repository is the executable reference example.
+- **Verify** checks the current runtime.
+- **Reset** discards runtime edits and restores the baseline.
+- **Stop** stops the runtime but keeps its local state.
+- **Discard** removes this project's disposable runtime and volume.
 
-Expected result:
+Press `Ctrl+Z` at any prompt to exit the entire guide. It will not leave a suspended
+process behind.
 
-```text
-Activated synthetic baseline ...: 1 rows across 1 tables; 1 migrations through 20260101000000.
-```
+## Command-line setup
 
-## 3. Check readiness
+The guide is recommended for people. Scripts and CI can use explicit commands:
 
 ```bash
+npx rehearsal setup --target=postgresql --write
 npx rehearsal doctor
-```
-
-Do not continue until it ends with `READY`. Doctor checks the local-only boundary,
-dependencies, artifact integrity, migration lineage, ports, and project commands.
-
-If it reports `NOT READY`, fix each named prerequisite and rerun it. Do not bypass a
-check or copy a hosted connection string into the generated runtime environment.
-
-## 4. Review pending work
-
-```bash
-npx rehearsal explain
 npx rehearsal candidates
-npx rehearsal inspect baseline
-npx rehearsal inspect migrations
-```
-
-The plan prints an exact candidate digest. It does not start services or change data.
-
-## 5. Run the rehearsal
-
-```bash
-npx rehearsal run --confirm-candidates=<sha256>
+npx rehearsal run --confirm-candidates=PASTE_DIGEST_HERE
 ```
 
-Rehearsal restores the immutable baseline, applies only the confirmed migration suffix,
-verifies the runtime, and runs the project-owned application proof. The resulting local
-database is writable, so you can test real application changes without mutating the
-baseline.
-
-## 6. Work, verify, and reset
-
-```bash
-npx rehearsal status
-npx rehearsal start
-npx rehearsal verify
-npx rehearsal reset
-npx rehearsal stop
-```
-
-Changes persist in the disposable runtime until `reset` or runtime removal. `start`
-resumes that runtime without resetting it. `reset` restores the exact baseline. `stop`
-stops only this project's runtime.
-
-## Next steps
-
-- Follow [the full tutorial](tutorial.md).
-- Read [the security model](security-model.md) before designing a production export.
-- Define an exhaustive [sanitization policy](sanitization.md).
-- Learn the [baseline lifecycle](baselines.md).
+Replace `postgresql` with `supabase` when needed. See [CLI commands](commands.md) for the
+complete reference and [Troubleshooting](troubleshooting.md) when a check fails.
 
-## Generated files
+## Files Rehearsal creates
 
-- `rehearsal.config.mjs` is written only by `init --write`. Its explicit ESM extension
-  works whether the consuming project's `package.json` uses CommonJS or ESM.
-- `.rehearsal/generations/<id>/` contains one immutable baseline generation.
-- `.rehearsal/current` selects the active generation atomically.
-- `.rehearsal/runtime/` contains the disposable local Supabase project and receipts.
-- `.rehearsal/runtime.env` contains generated loopback-only application credentials.
+- `rehearsal.config.mjs` — reviewed project configuration
+- `.rehearsal/` — ignored baselines, runtime files, and receipts
+- `.rehearsal/runtime.env` — generated local-only application variables
+- `infrastructure/rehearsal/supabase/config.toml` — Supabase-only local configuration
 
-Ignore all of `.rehearsal/`. Do not commit it even when its inputs were synthetic.
+Keep `.rehearsal/` out of source control, even when its data is synthetic.

package/docs/glossary.md

@@ -1,4 +1,4 @@
-# Glossary and architecture
+# Glossary
 
 **Baseline** — immutable sanitized starting artifact.
 
@@ -19,13 +19,12 @@ baseline.
 
 ```mermaid
 flowchart LR
-  A[Project-owned approved source] --> B[Project-owned sanitization]
-  B --> C[Immutable baseline]
-  D[Project migrations] --> E[Digest planner]
-  C --> F[Disposable local Supabase]
-  E --> F
-  F --> G[Project application proof]
-  G --> H[Verified local receipt]
+  A[Safe rows] --> B[Locked baseline]
+  C[Migration files] --> D[Reviewed plan]
+  B --> E[Disposable local database]
+  D --> E
+  E --> F[Application proof]
+  F --> G[Verified result]
 ```
 
 The reusable package owns the path from a completed baseline plus migration directory to

package/docs/sanitization.md

@@ -19,11 +19,14 @@ whether it is an identity column, and its foreign-key target or explicit absence
 draft uses `REVIEW REQUIRED` placeholders and cannot be activated until they are
 replaced and the `draft` marker is removed.
 
-In an interactive terminal, the guided **Review the script** action completes these
-decisions one column at a time. Replacement-oriented actions are shown first, retaining
-a value is explicitly labeled as sensitive, and no choice is silently inferred. The
-reviewer validates the completed policy and refuses to overwrite a draft changed during
-the session.
+In an interactive terminal, the guided **Review the script** action works table by table.
+For larger tables, a human can explicitly apply safe defaults (`REPLACE`, `NEVER`
+generated, `NO` identity, and no foreign key), then review only exceptions. Likely
+structural columns such as `id`, `*_id`, and timestamps start selected as exceptions.
+Users can instead review every column individually. Retaining a value is explicitly
+labeled as sensitive, every saved field remains classified, and no preset is silently
+applied. The reviewer validates the completed policy and refuses to overwrite a draft
+changed during the session.
 
 The package exports `validateSanitizationCoverage` and
 `applySanitizationAction` as generic primitives:

package/docs/security-model.md

@@ -13,12 +13,16 @@ changed migration history, incomplete artifacts, or an unverified runtime.
 ## Independent barriers
 
 - loopback-only application and service URLs;
-- a dedicated unlinked Supabase workdir and project ID;
+- a dedicated unlinked Supabase workdir, or an exactly named and labeled PostgreSQL
+  container and volume;
 - exact non-overlapping local ports;
 - a clean child-process environment that omits hosted credentials;
 - immutable baseline files and checksums;
 - exact migration-prefix and candidate digests;
 - local runtime labels used for bounded stop/removal;
+- PostgreSQL images must already exist locally and are never pulled implicitly;
+- plain PostgreSQL receives a fresh random password per disposable runtime, retained
+  only in owner-readable ignored runtime files;
 - successful receipts written only after verification.
 
 No single environment variable or config edit should redirect the tool to production.

package/docs/troubleshooting.md

@@ -1,5 +1,25 @@
 # Troubleshooting
 
+Start with:
+
+```bash
+npx rehearsal doctor
+```
+
+Doctor names each missing or unsafe item. If you still need help, run
+`npx rehearsal support`, review the report, and attach it to a GitHub issue.
+
+## `npx rehearsal` cannot find the command
+
+Confirm you are in the project directory and install the beta locally:
+
+```bash
+npm install --save-dev @rehearsal-db/core@beta
+npx rehearsal --help
+```
+
+Do not use `sudo` or require a global install.
+
 ## Setup says Node.js 24 is required
 
 Rehearsal intentionally supports one maintained Node.js major in its first beta. Switch
@@ -19,12 +39,32 @@ writes setup files.
 Start Docker Desktop or Colima, confirm `docker info`, then rerun `rehearsal doctor`.
 Restarting the computer is rarely necessary.
 
+## The guide does not show styled menus
+
+Rehearsal uses numbered menus when terminal styling is unavailable, `NO_COLOR` is set, or
+`--plain` is used. Enter the number beside your choice. This is the same workflow and has
+the same safety checks.
+
+If bare `npx rehearsal` prints help, the command is not connected to an interactive
+terminal. Run it directly in a terminal rather than through a pipe or background task.
+
+## Doctor says the PostgreSQL image is unavailable
+
+Rehearsal will not download an image during a rehearsal. Pull and review the exact image
+declared in `rehearsal.config.mjs`, then rerun Doctor:
+
+```bash
+docker pull postgres:17-alpine
+npx rehearsal doctor
+```
+
 ## A port is already in use
 
 Rerun `rehearsal setup` to select a different available block. Setup checks both active
 listeners and whether every selected port can be bound, then checks again before writing.
 For an existing configuration, choose unique non-privileged ports and mirror them in the
-dedicated Supabase config. Do not stop an unrelated database to make defaults fit.
+dedicated Supabase config when using Supabase. Do not stop an unrelated database to make
+defaults fit.
 
 ## Baseline checksum mismatch
 
@@ -62,5 +102,10 @@ is the local Auth callback. Do not paste provider secrets into config or termina
 `reset` deliberately restores the immutable baseline. `stop` should preserve Docker
 state, but runtime removal or a failed migration discards untrusted state.
 
+## `Ctrl+Z` exits instead of suspending
+
+This is intentional inside the guided interface. It exits the entire Rehearsal session
+and restores the terminal. Choose **Exit** for the same result.
+
 Use `--debug` only after ordinary output is insufficient. Diagnostics are redacted, but
 you should still review output before sharing it publicly.