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

package/CHANGELOG.md

@@ -5,6 +5,32 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## Unreleased
 
+## [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 +314,8 @@ 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.11...HEAD
+[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

@@ -37,11 +37,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:
 
@@ -64,7 +68,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 +124,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 +171,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,11 @@ 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` 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 +72,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 +80,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
@@ -54,7 +60,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 +121,26 @@ 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.
+
+### 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 +162,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

package/docs/getting-started.md

@@ -38,15 +38,20 @@ 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.
 
@@ -161,6 +166,10 @@ 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.
+
 ## 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,18 @@ graph without an application callback patch:
 }
 ```
 
+Authentication has three separate parts:
+
+1. The local Supabase configuration enables Google, GitHub, or email sign-in and reads
+   any provider credentials from the environment.
+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 +178,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 +241,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.

package/docs/sanitization.md

@@ -40,9 +40,110 @@ Two policy versions exist:
   Rehearsal can sanitize without project callbacks.
 
 Version 2 supports keyed UUID, email, text, and integer pseudonyms; explicit constant
-replacement; bounded date shifting; and exhaustively classified JSON objects. Unknown
-tables, columns, nested keys, formats, recipes, or missing fields fail closed. It never
-evaluates JavaScript or SQL from the policy.
+replacement; bounded date shifting; approved-owner conditionals; exhaustively classified
+JSON objects; and bounded JSON arrays. Unknown tables, columns, nested keys, formats,
+recipes, or missing required fields fail closed. It never evaluates JavaScript or SQL
+from the policy.
+
+## Approved-owner values
+
+Keep the raw approved owner outside the policy and baseline. The policy stores only its
+environment-variable name and SHA-256 receipt:
+
+```json
+{
+  "bindings": {
+    "approved-owner": {
+      "environmentVariable": "REHEARSAL_APPROVED_OWNER_ID",
+      "approvedValueSha256": "<lowercase sha256 of the exact owner value>"
+    }
+  },
+  "tables": [
+    {
+      "name": "profiles",
+      "sourceRows": "STREAM AND SANITIZE",
+      "ownerBinding": { "binding": "approved-owner", "column": "user_id" },
+      "columns": [
+        {
+          "name": "user_id",
+          "action": "PSEUDONYMIZE",
+          "recipe": { "format": "uuid", "namespace": "account-id" },
+          "generated": "NEVER",
+          "identity": "YES",
+          "foreignKey": null
+        },
+        {
+          "name": "display_name",
+          "action": "DERIVE",
+          "recipe": {
+            "kind": "approved-owner",
+            "approved": { "action": "KEEP" },
+            "otherwise": {
+              "action": "REPLACE",
+              "recipe": { "kind": "constant", "value": "Synthetic account" }
+            }
+          },
+          "generated": "NEVER",
+          "identity": "NO",
+          "foreignKey": null
+        }
+      ]
+    }
+  ]
+}
+```
+
+Generate the receipt without putting the owner value in shell history:
+
+```sh
+node -e 'const {createHash}=require("node:crypto"); process.stdout.write(createHash("sha256").update(process.env.REHEARSAL_APPROVED_OWNER_ID).digest("hex")+"\n")'
+```
+
+Every conditional table names its owner column. Missing bindings, hash mismatches,
+missing owner columns, null/unsupported owner values, and conditionals without an owner
+binding are refused. The owner column must be marked `identity: "YES"` and use
+`PSEUDONYMIZE`, preventing a conditional policy from retaining raw account IDs. Other
+owners take the declared `otherwise` path; every other identity-bearing field still
+needs its own pseudonymization declaration. Supply the binding only to the local
+server-side Rehearsal process; do not put it in the policy, baseline, or tracked files.
+
+## Structured JSON
+
+`json-object` fields are required by default. Set `"required": false` on an explicitly
+optional field. Unknown keys remain errors. `json-array` declares one item recipe and a
+required `maximumItems`. Both recipes accept `maximumDepth`, `maximumBytes`, and
+`allowNull`; defaults are 8 levels, 65,536 bytes, and no null container. Bounds are
+checked before producing the transformed structure. Nested objects and arrays repeat
+the same declarations, and every nested identity uses an explicit pseudonym recipe.
+
+```json
+{
+  "action": "DERIVE",
+  "recipe": {
+    "kind": "json-array",
+    "maximumItems": 25,
+    "maximumDepth": 4,
+    "maximumBytes": 8192,
+    "items": {
+      "action": "DERIVE",
+      "recipe": {
+        "kind": "json-object",
+        "fields": {
+          "actor_id": {
+            "action": "PSEUDONYMIZE",
+            "recipe": { "format": "uuid", "namespace": "account-id" }
+          },
+          "note": {
+            "action": "REPLACE",
+            "required": false,
+            "recipe": { "kind": "constant", "value": "Synthetic note" }
+          }
+        }
+      }
+    }
+  }
+}
+```
 
 The package still exports `validateSanitizationCoverage` and
 `applySanitizationAction` for existing version 1 preparation tools:

package/docs/standalone-workflow.md

@@ -28,6 +28,8 @@ name:
 - whether rows are approved public data or belong to one explicitly approved
   owner;
 - privacy actions and bounded transformation recipes;
+- hashed server-side owner bindings and explicit approved/other-owner branches;
+- bounded nested JSON objects and arrays with required/optional fields;
 - licensed or consented Storage buckets and prefixes;
 - schema and extension prerequisites;
 - local identities and reference locations;

package/docs/troubleshooting.md

@@ -20,6 +20,20 @@ npx rehearsal --help
 
 Do not use `sudo` or require a global install.
 
+## Installation did not create `rehearsal.config.mjs`
+
+Rehearsal intentionally skips automatic creation when install scripts are disabled, the
+install is global or temporary, or more than one workspace application could own the
+config. From the intended application directory, run:
+
+```bash
+npx rehearsal
+```
+
+Choose **Set the stage** and approve the preview. For pnpm and Yarn, use this guided path;
+automatic root generation is currently tested with npm. An existing supported config is
+kept in place, including `infrastructure/rehearsal/rehearsal.config.mjs`.
+
 ## Setup says Node.js 24 is required
 
 Rehearsal intentionally supports one maintained Node.js major in its first beta. Switch
@@ -136,6 +150,17 @@ Confirm the provider is enabled in the dedicated local Supabase config, the allo
 service environment file exists with owner-only permissions, and the provider callback
 is the local Auth callback. Do not paste provider secrets into config or terminal output.
 
+If `identity plan` refuses the matcher, read the message literally:
+
+- **Provider or matcher type is unsupported:** use only the combinations documented in
+  [Runtime and identity policies](runtime-policies.md).
+- **No verified identity matches:** complete an ordinary local sign-in, confirm the
+  correct environment value is present, then run the plan again.
+- **More than one identity matches:** narrow the provider allowlist or use a hashed
+  provider-subject matcher. Rehearsal will not guess between accounts.
+- **Provider subject conflicts:** the local Auth identity disagrees with itself; remove
+  and recreate that disposable local sign-in instead of forcing a claim.
+
 ## Runtime changes disappeared
 
 `reset` deliberately restores the immutable baseline. `stop` should preserve Docker