@rehearsal-db/core 0.1.0-beta.10 → 0.1.0-beta.12

package/CHANGELOG.md

@@ -5,6 +5,67 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## Unreleased
 
+## [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
@@ -288,7 +349,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.10...HEAD
+[Unreleased]: https://github.com/Ddupasquier/rehearsal-db/compare/v0.1.0-beta.12...HEAD
+[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

package/COMPATIBILITY.md

@@ -21,6 +21,15 @@ 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.
 
+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,5 +1,9 @@
 # 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.
@@ -37,11 +41,15 @@ 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 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 +59,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,7 +77,8 @@ 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.
@@ -119,7 +133,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
@@ -166,3 +180,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/docs/README.md

@@ -1,29 +1,38 @@
-# Documentation map
+# Rehearsal documentation
+
+Welcome. You do not need to read this documentation from top to bottom. Choose what you
+want to accomplish and follow that path.
 
 ## Start here
 
-- [Getting started](getting-started.md)
-- [Hands-on tutorial](tutorial.md)
-- [Troubleshooting](troubleshooting.md)
+| Your goal                           | Best next page                        |
+| ----------------------------------- | ------------------------------------- |
+| Add Rehearsal to a project          | [Getting started](getting-started.md) |
+| Try it in a disposable project      | [Hands-on tutorial](tutorial.md)      |
+| Fix a setup or runtime problem      | [Troubleshooting](troubleshooting.md) |
+| Browse the friendlier web-docs home | [Documentation home](index.md)        |
 
-## Understand the safety model
+## Work safely
 
-- [Baselines](baselines.md)
-- [Sanitization](sanitization.md)
-- [Production source boundary](production-source.md)
-- [Security model](security-model.md)
+- [Baselines](baselines.md) — the verified starting copy
+- [Sanitization](sanitization.md) — what may enter that copy
+- [Production-shaped preparation](production-source.md) — the optional source boundary
+- [Security model](security-model.md) — the independent safety barriers
+- [Standalone workflow](standalone-workflow.md) — the complete declarative contract
 
-## Configure Rehearsal
+## Look something up
 
+- [CLI commands](commands.md)
 - [Configuration](configuration.md)
-- [Commands](commands.md)
-- [Runtime policies](runtime-policies.md)
+- [Runtime and identity policies](runtime-policies.md)
 - [Database adapters](adapters.md)
-- [Standalone PostgreSQL workflow](standalone-workflow.md)
+- [Glossary](glossary.md)
 
-## Maintain the project
+## Follow the project
 
+- [Roadmap](roadmap.md)
 - [Repository architecture](architecture.md)
 - [Release process](releasing.md)
-- [Roadmap](roadmap.md)
-- [Glossary](glossary.md)
+
+To preview the styled documentation locally, run `npm run docs:preview`, then open the
+address it prints.

package/docs/commands.md

@@ -23,7 +23,7 @@ bare `npx rehearsal` prints help instead of waiting for input.
 | `npx rehearsal setup --target=supabase`                           | Preview Supabase setup files.                          |
 | `npx rehearsal setup --target=postgresql`                         | Preview PostgreSQL setup files.                        |
 | Add `--write` to either setup command                             | Create the previewed files without overwriting.        |
-| `npx rehearsal init`                                              | Preview only `rehearsal.config.mjs`.                   |
+| `npx rehearsal init`                                              | Preview the current config template without writing.   |
 | `npx rehearsal init --write`                                      | Create only `rehearsal.config.mjs`.                    |
 | `npx rehearsal baseline prepare --records=<path> --ledger=<path>` | Preview a sanitization-policy draft.                   |
 | Add `--write` to `baseline prepare`                               | Write the draft for human review.                      |
@@ -32,6 +32,12 @@ bare `npx rehearsal` prints help instead of waiting for input.
 Add `--assets=<manifest.json>` to `baseline create` only for approved local Supabase
 Storage files. `baseline create` and `baseline prepare` are local-only.
 
+`setup --write` is idempotent: supported existing config files and completed runtime
+files remain unchanged, while missing safe ignore entries may be appended. On upgrades,
+`init` first lists important optional settings that are available but not enabled, then
+prints the installed release's template for comparison. `init --write` never replaces an
+existing config.
+
 ## Optional source preparation
 
 These commands are separate from ordinary rehearsals. Configure `preparation` only after
@@ -67,7 +73,7 @@ In short: `refresh` gets a new source copy; `reset` restores the copy you alread
 
 ## Local identity association
 
-For a reviewed Google identity, use this sequence:
+For a reviewed Google, GitHub, or email identity, use this sequence:
 
 1. Run a successful rehearsal, then start the persistent app:
 
@@ -75,9 +81,10 @@ For a reviewed Google identity, use this sequence:
    npx rehearsal open
    ```
 
-2. Open the printed local URL and complete the normal Google sign-in. Press `Ctrl+C`
+2. Open the printed local URL and complete the normal provider sign-in. Press `Ctrl+C`
    after the callback returns. This closes only the app; the databases and Storage stay
-   running with their current data.
+   running with their current data. Provider setup and credentials belong to the local
+   Supabase runtime, not the identity policy.
 
 3. Preview and confirm the reviewed association:
 

package/docs/configuration.md

@@ -1,15 +1,21 @@
 # Configuration reference
 
-Most users should let the guide create this file:
+An ordinary npm application install creates this file in the application root when the
+root can be identified safely:
 
 ```bash
-npx rehearsal
+npm install --save-dev @rehearsal-db/core@beta
 ```
 
-The first run uses your chosen database type and detects the project name, migration
-folder, package-manager commands, and free local ports. After you approve the setup
-preview, it creates a commented `rehearsal.config.mjs` with those values filled in.
-Installation itself does not use a `postinstall` script or silently modify the project.
+The install hook detects the database type, project name, migration folder,
+package-manager commands, and free local ports. It also creates the dedicated local
+runtime config and appends the two Rehearsal local-artifact entries to `.gitignore`.
+Existing configs and existing ignore content are never rewritten.
+
+When lifecycle scripts are disabled or the application root is not provable, run
+`npx rehearsal` inside the application. The guide provides the same setup with a preview
+and confirmation. Automatic root generation is tested with npm. pnpm and Yarn users
+should use this guided fallback because their lifecycle and workspace layouts vary.
 
 Review lines marked `CHECK`, especially the application proof command. Optional settings
 are present as commented examples, and secrets never belong in this file. Rehearsal will
@@ -36,9 +42,21 @@ export default defineRehearsalConfig({
     rehearsalConfig: "infrastructure/rehearsal/supabase/config.toml",
     runtimeWorkdir: ".rehearsal/runtime",
 
-    // Optional; configure both keys together.
-    // serviceEnvironmentFile: ".env.rehearsal-service.local",
-    // serviceEnvironmentVariables: ["LOCAL_IDP_CLIENT_ID", "LOCAL_IDP_SECRET"],
+    // Optional local OAuth connection. Secrets stay in the ignored owner-only file.
+    // Register http://127.0.0.1:58321/auth/v1/callback with the provider.
+    // authentication: {
+    //   enableLocalSignup: true,
+    //   environmentFile: ".env.rehearsal-service.local",
+    //   providers: [
+    //     {
+    //       name: "google",
+    //       clientIdEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_ID",
+    //       clientSecretEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_SECRET",
+    //       skipNonceCheck: false,
+    //       emailOptional: false,
+    //     },
+    //   ],
+    // },
   },
   baseline: {
     artifactDirectory: ".rehearsal",
@@ -54,7 +72,8 @@ export default defineRehearsalConfig({
   //   diskHeadroomBytes: 67108864,
   // },
   // runtimePolicy: "infrastructure/rehearsal/runtime-policy.json",
-  // Optional signup defaults, role/reference transfer, Storage paths, and token checks.
+  // Optional copied-account association. The JSON stores reviewed matcher hashes only;
+  // raw emails/subjects and provider credentials stay in ignored environment files.
   // identityPolicy: "infrastructure/rehearsal/identity-policy.json",
   containerRuntime: {
     autoStartColima: true,
@@ -114,6 +133,27 @@ All paths resolve inside the consuming project. The artifact directory must be n
 Rehearsal never overwrites this config. To start over, move the existing file somewhere
 safe, run setup again, and compare the two files before deleting either one.
 
+After upgrading, run `npx rehearsal init` to print the current release's generated
+template beside the path of your existing config. This comparison is read-only; adding a
+new optional key remains your decision. `npx rehearsal init --write` still refuses to
+replace an existing config. Rehearsal lists important optional settings that are
+available but not enabled before printing the template, so they are easier to find.
+
+### Workspaces and custom paths
+
+For an npm workspace, automatic creation proceeds only when exactly one application
+package already declares `@rehearsal-db/core` in the manifest or lockfile visible to the
+install hook. npm can save a new `--workspace` dependency after that hook runs, so a
+first workspace install may safely skip creation. If several applications declare it,
+Rehearsal also refuses to choose. Run `npx rehearsal` inside each intended application.
+Global installs, package caches, temporary `npx` installs, and Rehearsal's own source
+checkout never receive project files.
+
+Supported existing config paths—including
+`infrastructure/rehearsal/rehearsal.config.mjs`—are preserved, and a second root config
+is not created. Use `--config=<project-relative-path>` for other explicit paths when
+running commands.
+
 `preparation.privacyKey` must stay inside `.rehearsal`; it is ignored and owner-readable
 only. Source, runtime, and identity policy files are declarations that may be reviewed in
 source control. They must never contain passwords, tokens, production URLs, raw owner
@@ -135,8 +175,11 @@ approval sequence.
 
 `runtimePolicy` replaces common restore adapters with reviewed schemas, allowlisted
 extensions, managed triggers, local-only singleton rows, and structural expectations.
-`identityPolicy` declares a hashed verified email, copied placeholder, safe signup
-defaults, required role/reference transfers, Storage path rewrites, and token checks. See
+`identityPolicy` declares a hashed verified-email or provider-subject matcher, copied
+placeholder, safe signup defaults, required role/reference transfers, Storage path
+rewrites, and token checks. Provider credentials stay in the local Supabase runtime
+environment; association values stay in named environment variables and only their
+SHA-256 receipts are tracked. See
 [Runtime and identity policies](runtime-policies.md).
 
 ## Container runtime and cleanup
@@ -217,19 +260,72 @@ negative controls, such as unauthorized, malformed, withheld, or missing records
 response that merely avoids a server error does not prove that eligible data was
 published or can be found.
 
-## Supabase service environment
+## Supabase authentication
 
-Some local identity providers need a client ID and secret. Configure both fields or
-neither:
+Rehearsal can configure a Google or GitHub OAuth connection in its disposable local
+Supabase runtime. Declare the provider and the names of its credential variables:
 
 ```ts
-serviceEnvironmentFile: ".env.rehearsal-service.local",
-serviceEnvironmentVariables: ["LOCAL_IDP_CLIENT_ID", "LOCAL_IDP_SECRET"],
+authentication: {
+  enableLocalSignup: true,
+  environmentFile: ".env.rehearsal-service.local",
+  providers: [
+    {
+      name: "google",
+      clientIdEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_ID",
+      clientSecretEnvironmentVariable: "REHEARSAL_GOOGLE_CLIENT_SECRET",
+      skipNonceCheck: false,
+      emailOptional: false,
+    },
+  ],
+},
+```
+
+Create the ignored file, add the values, then restrict it to your account:
+
+```dotenv
+REHEARSAL_GOOGLE_CLIENT_ID=your-local-oauth-client-id
+REHEARSAL_GOOGLE_CLIENT_SECRET=your-local-oauth-client-secret
+```
+
+```bash
+chmod 600 .env.rehearsal-service.local
 ```
 
-The file must be ignored, owner-readable only, and contain only the exact allowlisted
-names. These credentials may authorize an identity handshake, but the callback must
-terminate at local Auth. They do not grant hosted database access.
+Register `http://127.0.0.1:<apiPort>/auth/v1/callback` with the provider, using the
+`runtime.apiPort` value from this config. `rehearsal explain` also prints the exact URL.
+Rehearsal writes that callback and `env(...)` references into the disposable runtime; it
+never copies credential values into tracked configuration. Use `name: "github"` and
+distinct GitHub variable names for GitHub. Duplicate providers, reused variable names,
+unsupported providers, extra keys, and a template that already owns the same provider
+are refused. This follows Supabase's documented
+[`env()` configuration pattern](https://supabase.com/docs/guides/local-development/managing-config).
+
+`enableLocalSignup: true` explicitly acknowledges that disposable local Auth may create
+the temporary user returned by OAuth. Rehearsal changes the generated runtime copy only;
+the tracked Supabase template and every hosted project remain unchanged.
+
+The older `serviceEnvironmentFile`, `serviceEnvironmentVariables`, and
+`safety.authenticationProviders` fields remain compatible for projects that manually
+own their Supabase provider TOML. Do not combine those fields with the declarative
+`authentication` block.
+
+To migrate a manual Google or GitHub setup, replace those three legacy config fields
+with the `authentication` block together. The tracked Supabase template may keep its
+existing provider section: Rehearsal replaces a compatible legacy section only in the
+generated disposable runtime copy. The section may contain `enabled`, `client_id`,
+`secret`, `redirect_uri`, `skip_nonce_check`, and `email_optional`. The latter two must
+match the explicit `skipNonceCheck` and `emailOptional` declarations, which default to
+`false`. Keep them false unless the provider integration has a reviewed need; Supabase
+warns in its [CLI configuration reference](https://supabase.com/docs/guides/local-development/cli/config#auth.external.provider.skip_nonce_check)
+that skipping nonce validation reduces replay protection. Unknown settings,
+duplicate sections, nested provider tables, or mismatched options fail
+`rehearsal doctor` before reset. Rehearsal never edits the tracked template during this
+transition.
+
+Provider connection and copied-account association are separate. This block lets the
+ordinary application sign-in reach local Auth. An optional `identityPolicy` decides
+whether that verified local identity may claim a reviewed copied account.
 
 ## Safety fields
 

package/docs/getting-started.md

@@ -38,18 +38,30 @@ npm install --save-dev @rehearsal-db/core@beta
 npx rehearsal
 ```
 
-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.
-
-Review the generated `rehearsal.config.mjs`, especially:
+With npm, a normal application install creates `rehearsal.config.mjs`, the dedicated
+local runtime config, and the required `.gitignore` entries when Rehearsal can prove the
+application root. It never replaces an existing file. Review the generated config,
+especially:
 
 - the migration directory;
 - the application start and proof commands;
 - the local ports.
 
+If lifecycle scripts were disabled, a global/cache install was used, or a workspace has
+more than one possible application, no project files are created automatically. Run
+`npx rehearsal` inside the intended application, choose **Set the stage**, select
+Supabase or PostgreSQL, and approve the same safe setup preview.
+
 The proof command should check behavior changed by the migration. A test that only checks
 whether the home page loads is usually too weak.
 
+If the sandbox needs Google or GitHub sign-in, uncomment
+`supabase.authentication` in `rehearsal.config.mjs`. Add the named credentials to
+`.env.rehearsal-service.local`, run `chmod 600 .env.rehearsal-service.local`, and
+register the local callback printed in the config. See
+[Supabase authentication](configuration.md#supabase-authentication). Rehearsal keeps the
+values out of tracked files and generates the disposable provider configuration for you.
+
 ## 3. Prepare safe baseline inputs
 
 A **baseline** is the locked starting point restored before each rehearsal. Start with a
@@ -161,6 +173,12 @@ npx rehearsal run --confirm-candidates=PASTE_DIGEST_HERE
 Replace `postgresql` with `supabase` when needed. See [CLI commands](commands.md) for the
 complete reference and [Troubleshooting](troubleshooting.md) when a check fails.
 
+Running setup again is safe: existing configuration and runtime files are reported as
+unchanged. Rehearsal only adds missing ignore entries. It never refreshes an existing
+config during an upgrade. After upgrading, run `npx rehearsal init` to see important
+optional settings you have not enabled and compare your file with the installed
+release's current template.
+
 ## Files Rehearsal creates
 
 - `rehearsal.config.mjs` — reviewed project configuration

package/docs/index.md

@@ -0,0 +1,47 @@
+# Rehearsal documentation
+
+## Pick the path that fits today
+
+You do not need to read everything before your first rehearsal. Start with the outcome
+you want, then follow the links when a term or safety check is new.
+
+| I want to…                            | Go here                                                           |
+| ------------------------------------- | ----------------------------------------------------------------- |
+| Set up my own project                 | [Getting started](getting-started.md)                             |
+| Try Rehearsal without touching my app | [Hands-on tutorial](tutorial.md)                                  |
+| Understand what makes a copy safe     | [Baselines](baselines.md) and [Sanitization](sanitization.md)     |
+| Look up a command or setting          | [CLI commands](commands.md) and [Configuration](configuration.md) |
+| Fix something that did not work       | [Troubleshooting](troubleshooting.md)                             |
+
+## The short version
+
+Rehearsal restores an approved local baseline, applies only the migration files you
+reviewed, and runs the application checks your project owns. The normal workflow stays
+on your computer and does not deploy anything.
+
+1. **Prepare** a safe baseline.
+2. **Review** the exact candidate migrations.
+3. **Run** them in a disposable local database.
+4. **Prove** the application behavior that matters.
+5. **Open** the sandbox for hands-on testing.
+
+## Safety is part of the workflow
+
+Rehearsal does not ask you to trust one giant switch. Baseline checksums, local-only
+networking, exact confirmation digests, project-owned proofs, and narrowly owned cleanup
+each protect a different boundary.
+
+Start with synthetic data when you can. If a project needs a production-shaped copy,
+read [Production-shaped preparation](production-source.md) before providing any source
+access.
+
+## Still unsure where to begin?
+
+Run the interactive guide from the project you want to test:
+
+```bash
+npx rehearsal
+```
+
+It reads the project state, explains the next safe step, and keeps the full command
+reference available when you need it.

package/docs/runtime-policies.md

@@ -77,9 +77,12 @@ graph without an application callback patch:
   "identities": [
     {
       "name": "approved-owner",
-      "provider": "google",
-      "emailEnvironmentVariable": "REHEARSAL_APPROVED_OWNER_EMAIL",
-      "approvedEmailSha256": "<sha256 of the lowercase approved email>",
+      "matcher": {
+        "type": "verified-email",
+        "providers": ["google"],
+        "emailEnvironmentVariable": "REHEARSAL_APPROVED_OWNER_EMAIL",
+        "approvedEmailSha256": "<sha256 of the lowercase approved email>"
+      },
       "placeholderUserId": "11111111-1111-4111-8111-111111111111",
       "references": [
         {
@@ -152,9 +155,20 @@ graph without an application callback patch:
 }
 ```
 
+Authentication has three separate parts:
+
+1. `config.supabase.authentication` can enable a Google or GitHub connection in local
+   Supabase and reads its credentials from the ignored owner-only environment file.
+   Existing projects may still own that local provider TOML manually. Email sign-in does
+   not use an OAuth credential declaration.
+2. The application completes the ordinary sign-in and receives a normal Supabase
+   session. Rehearsal does not intercept the callback.
+3. The identity policy matches that verified local identity and transfers only the
+   reviewed copied-account graph.
+
 The email stays in an environment variable; only its reviewed hash is committed. Run
-`rehearsal open`, complete the ordinary local Google sign-in, and stop the app with
-`Ctrl+C`. Then preview and confirm the association:
+`rehearsal open`, complete the ordinary local sign-in, and stop the app with `Ctrl+C`.
+Then preview and confirm the association:
 
 ```bash
 npx rehearsal identity plan --identity=approved-owner
@@ -166,6 +180,50 @@ Rehearsal requires exactly one verified matching local provider identity. Every
 `required` reference must exist after transfer. Declare application role tables as
 references; `claims` alone is not a replacement for a database-backed token hook.
 
+### Supported identity matchers
+
+Rehearsal currently supports the Supabase provider values `email`, `google`, and
+`github`. Other provider names fail closed until their Auth representation has package
+coverage. Two matcher types are supported:
+
+- `verified-email` accepts one or more supported providers. It lowercases the email from
+  the named environment variable and compares its SHA-256 receipt before querying Auth.
+- `provider-subject` accepts one OAuth provider (`google` or `github`). It compares the
+  reviewed SHA-256 to Supabase's stable provider ID/subject without placing the raw
+  subject in the policy, baseline, command output, SQL parameters, or receipt.
+
+Google by verified email:
+
+```json
+"matcher": {
+  "type": "verified-email",
+  "providers": ["google"],
+  "emailEnvironmentVariable": "REHEARSAL_APPROVED_OWNER_EMAIL",
+  "approvedEmailSha256": "<sha256 of the lowercase email>"
+}
+```
+
+Supabase email/password or magic-link sign-in uses the same matcher with
+`"providers": ["email"]`. An account intentionally allowed to use either ordinary
+email or Google can declare `"providers": ["email", "google"]`; the claim still refuses
+zero or multiple matching identities.
+
+GitHub by stable provider subject:
+
+```json
+"matcher": {
+  "type": "provider-subject",
+  "provider": "github",
+  "subjectEnvironmentVariable": "REHEARSAL_APPROVED_OWNER_SUBJECT",
+  "approvedSubjectSha256": "<sha256 of the exact GitHub subject>"
+}
+```
+
+Set the raw value only in the local shell or an ignored environment file. Existing
+policies using the older top-level `provider`, `emailEnvironmentVariable`, and
+`approvedEmailSha256` fields remain accepted as a single-provider verified-email
+matcher. New policies should use the explicit `matcher` object.
+
 References use `"strategy": "transfer"` by default. Use `"preserve-audit"` only for
 immutable historical authorship, such as a completed review. Rehearsal leaves that row
 and its synthetic Auth actor unchanged, but still transfers the active profile, roles,
@@ -185,6 +243,10 @@ configured `tokenHook` must return the declared claim subset before commit. The
 refresh its session or sign in again because Rehearsal cannot rewrite an issued JWT.
 Run `rehearsal open` again for that fresh-session check; runtime data is preserved.
 
+After a claim, sign out and sign in again (or otherwise force a full token refresh) before
+judging application roles. This preserves normal RLS, account blocks, role checks, and
+MFA; identity association is not an authentication bypass.
+
 The transaction does not import production passwords, sessions, refresh tokens,
 cookies, MFA secrets, or provider credentials. Local MFA and authorization rules remain
 real.