@rehearsal-db/core 0.1.0-beta.9 → 0.1.0-rc.2

package/dist/src/targets/supabase_environment.mjs

@@ -0,0 +1,184 @@
+/**
+ * Purpose: Start and inspect local-only Supabase workdirs without inheriting hosted
+ * credentials. Do not run directly; this module is reusable script infrastructure.
+ */
+import { spawnSync } from "node:child_process";
+import { createCleanProcessEnvironment, } from "../shared/process_environment.mjs";
+export const parseSupabaseStatusEnvironment = (output) => {
+    const values = {};
+    for (const line of output.split("\n")) {
+        const match = line.match(/^([A-Z][A-Z0-9_]*)=(.*)$/u);
+        if (!match)
+            continue;
+        const key = match[1];
+        const rawValue = match[2];
+        if (key === undefined || rawValue === undefined)
+            continue;
+        let value = rawValue.trim();
+        if (value.startsWith('"') && value.endsWith('"')) {
+            const parsed = JSON.parse(value);
+            if (typeof parsed !== "string")
+                continue;
+            value = parsed;
+        }
+        values[key] = value;
+    }
+    return values;
+};
+export const parseLocalSupabaseEnvironment = (output) => {
+    const values = parseSupabaseStatusEnvironment(output);
+    const required = (label, value) => {
+        if (!value)
+            throw new Error(`Local Supabase status omitted its ${label}.`);
+        return value;
+    };
+    const apiUrl = required("API URL", values.API_URL);
+    const databaseUrl = required("database URL", values.DB_URL);
+    const publishableKey = required("publishable key", values.PUBLISHABLE_KEY ?? values.ANON_KEY);
+    const serviceRoleKey = required("service-role key", values.SERVICE_ROLE_KEY ?? values.SECRET_KEY);
+    const api = new URL(apiUrl);
+    const database = new URL(databaseUrl);
+    const loopbackHosts = ["127.0.0.1", "::1", "localhost"];
+    if (!loopbackHosts.includes(api.hostname) ||
+        !loopbackHosts.includes(database.hostname) ||
+        !["postgres:", "postgresql:"].includes(database.protocol)) {
+        throw new Error("Refusing to use a non-local Supabase status target.");
+    }
+    const databaseName = decodeURIComponent(database.pathname.replace(/^\//u, ""));
+    if (!database.port ||
+        !databaseName ||
+        !database.username ||
+        !database.password) {
+        throw new Error("Local Supabase status returned an incomplete database URL.");
+    }
+    return {
+        apiUrl,
+        databaseUrl,
+        publishableKey,
+        serviceRoleKey,
+        studioUrl: values.STUDIO_URL,
+        databaseHost: database.hostname,
+        databasePort: database.port,
+        databaseName,
+        databaseUser: decodeURIComponent(database.username),
+        databasePassword: decodeURIComponent(database.password),
+    };
+};
+export const runLocalCommand = (command, args, { capture = false, cwd = process.cwd(), input, environment = {}, maxBuffer = 16 * 1024 * 1024, } = {}) => {
+    const shouldPipe = capture || input !== undefined;
+    const result = spawnSync(command, args, {
+        cwd,
+        encoding: "utf8",
+        env: createCleanProcessEnvironment({ overrides: environment }),
+        input,
+        maxBuffer,
+        stdio: shouldPipe ? ["pipe", "pipe", "pipe"] : "inherit",
+    });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0) {
+        const detail = [result.stdout, result.stderr]
+            .filter(Boolean)
+            .join("\n")
+            .trim();
+        throw new Error(`${command} ${args.join(" ")} failed${detail ? `:\n${detail}` : "."}`);
+    }
+    return result.stdout ?? "";
+};
+export const localCommandSucceeds = (command, args, { cwd = process.cwd(), environment = {}, } = {}) => spawnSync(command, args, {
+    cwd,
+    env: createCleanProcessEnvironment({ overrides: environment }),
+    stdio: "ignore",
+}).status === 0;
+export const ensureLocalContainerRuntime = ({ cwd = process.cwd(), autoStartColima = false, } = {}) => {
+    if (localCommandSucceeds("docker", ["info"], { cwd }))
+        return;
+    if (autoStartColima && localCommandSucceeds("colima", ["version"], { cwd })) {
+        runLocalCommand("colima", ["start"], { cwd });
+        console.log("Started Colima because containerRuntime.autoStartColima is enabled. Rehearsal will not stop this shared Docker runtime automatically.");
+    }
+    if (!localCommandSucceeds("docker", ["info"], { cwd })) {
+        throw new Error(autoStartColima
+            ? "A local Docker-compatible runtime is required. Install Docker or Colima, then rerun the command."
+            : "A local Docker-compatible runtime is stopped or unavailable. Start Docker or Colima explicitly, or opt in with containerRuntime.autoStartColima: true.");
+    }
+};
+export const preventOwnedSupabaseAutoRestart = ({ cwd = process.cwd(), projectId, }) => {
+    if (!/^[a-z0-9][a-z0-9-]{1,62}$/u.test(projectId)) {
+        throw new Error("Refusing to change container restart policies without an exact safe Supabase project id.");
+    }
+    const label = `com.supabase.cli.project=${projectId}`;
+    const containers = runLocalCommand("docker", ["ps", "--all", "--filter", `label=${label}`, "--format", "{{.ID}}"], { capture: true, cwd })
+        .split("\n")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (containers.length) {
+        runLocalCommand("docker", ["update", "--restart=no", ...containers], {
+            capture: true,
+            cwd,
+        });
+    }
+    return Object.freeze(containers);
+};
+const withWorkdir = (args, workdir) => (workdir ? [...args, "--workdir", workdir] : [...args]);
+export const readLocalSupabaseEnvironment = ({ cwd, workdir, environment = {}, } = {}) => {
+    const output = runLocalCommand("supabase", withWorkdir(["status", "-o", "env"], workdir), { capture: true, cwd, environment });
+    return parseLocalSupabaseEnvironment(output);
+};
+export const startLocalSupabase = ({ cwd, workdir, exclude = [], environment = {}, applyMigrations = true, autoStartColima = false, projectId, } = {}) => {
+    ensureLocalContainerRuntime({ cwd, autoStartColima });
+    const startArguments = withWorkdir(["start", ...(exclude.length ? ["--exclude", exclude.join(",")] : [])], workdir);
+    runLocalCommand("supabase", startArguments, {
+        capture: true,
+        cwd,
+        environment,
+    });
+    if (projectId)
+        preventOwnedSupabaseAutoRestart({ cwd, projectId });
+    if (applyMigrations) {
+        runLocalCommand("supabase", withWorkdir(["migration", "up", "--local"], workdir), { capture: true, cwd, environment });
+    }
+    return readLocalSupabaseEnvironment({ cwd, workdir, environment });
+};
+export const stopLocalSupabase = ({ cwd, workdir, environment = {}, } = {}) => {
+    if (!localCommandSucceeds("docker", ["info"], { cwd }))
+        return;
+    runLocalCommand("supabase", withWorkdir(["stop"], workdir), {
+        cwd,
+        environment,
+    });
+};
+export const removeLocalSupabaseProjectResources = ({ cwd = process.cwd(), projectId, } = {}) => {
+    if (!/^[a-z0-9][a-z0-9-]{1,62}$/u.test(projectId ?? "")) {
+        throw new Error("Refusing to remove local Supabase resources without an exact safe project id.");
+    }
+    const label = `com.supabase.cli.project=${projectId}`;
+    const list = (resource, format) => runLocalCommand("docker", [resource, "ls", "--filter", `label=${label}`, "--format", format], { capture: true, cwd })
+        .split("\n")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    const containers = runLocalCommand("docker", ["ps", "--all", "--filter", `label=${label}`, "--format", "{{.ID}}"], { capture: true, cwd })
+        .split("\n")
+        .map((value) => value.trim())
+        .filter(Boolean);
+    if (containers.length) {
+        runLocalCommand("docker", ["rm", "--force", ...containers], {
+            capture: true,
+            cwd,
+        });
+    }
+    const volumes = list("volume", "{{.Name}}");
+    if (volumes.length) {
+        runLocalCommand("docker", ["volume", "rm", "--force", ...volumes], {
+            capture: true,
+            cwd,
+        });
+    }
+    const networks = list("network", "{{.ID}}");
+    if (networks.length) {
+        runLocalCommand("docker", ["network", "rm", ...networks], {
+            capture: true,
+            cwd,
+        });
+    }
+};

package/dist/src/targets/target.d.mts

@@ -0,0 +1,33 @@
+/**
+ * Purpose: Define the small, closed set of database runtimes Rehearsal can select.
+ * Runtime implementations stay behind this boundary so the shared CLI does not
+ * need target-specific branches.
+ */
+declare const TARGETS: Readonly<{
+    supabase: Readonly<{
+        id: "supabase";
+        label: "Supabase";
+    }>;
+    postgresql: Readonly<{
+        id: "postgresql";
+        label: "PostgreSQL";
+    }>;
+}>;
+export type RehearsalRuntimeTargetId = keyof typeof TARGETS;
+export type RehearsalRuntimeTarget = (typeof TARGETS)[RehearsalRuntimeTargetId];
+export interface RuntimeInvocation {
+    readonly action: string;
+    readonly configPath: string | undefined;
+    readonly confirmation: string | undefined;
+}
+export interface RuntimeManagerArguments {
+    managerPath: string;
+    action: string;
+    configPath?: string;
+    confirmation?: string;
+}
+export declare const REHEARSAL_RUNTIME_TARGETS: readonly ("postgresql" | "supabase")[];
+export declare const parseRuntimeInvocation: (arguments_?: readonly string[]) => RuntimeInvocation;
+export declare const buildRuntimeManagerArguments: ({ managerPath, action, configPath, confirmation, }: RuntimeManagerArguments) => string[];
+export declare const resolveRuntimeTarget: (value?: unknown) => RehearsalRuntimeTarget;
+export {};

package/dist/src/targets/target.mjs

@@ -0,0 +1,39 @@
+/**
+ * Purpose: Define the small, closed set of database runtimes Rehearsal can select.
+ * Runtime implementations stay behind this boundary so the shared CLI does not
+ * need target-specific branches.
+ */
+const TARGETS = Object.freeze({
+    supabase: Object.freeze({
+        id: "supabase",
+        label: "Supabase",
+    }),
+    postgresql: Object.freeze({
+        id: "postgresql",
+        label: "PostgreSQL",
+    }),
+});
+export const REHEARSAL_RUNTIME_TARGETS = Object.freeze(Object.keys(TARGETS));
+export const parseRuntimeInvocation = (arguments_ = process.argv.slice(2)) => {
+    const action = arguments_.find((argument) => !argument.startsWith("--"));
+    const valueAfter = (prefix) => arguments_
+        .find((argument) => argument.startsWith(prefix))
+        ?.slice(prefix.length);
+    return Object.freeze({
+        action: action ?? "status",
+        configPath: valueAfter("--config="),
+        confirmation: valueAfter("--confirm-candidates="),
+    });
+};
+export const buildRuntimeManagerArguments = ({ managerPath, action, configPath, confirmation, }) => [
+    managerPath,
+    action,
+    ...(configPath ? [`--config=${configPath}`] : []),
+    ...(confirmation ? [`--confirm-candidates=${confirmation}`] : []),
+];
+export const resolveRuntimeTarget = (value = "supabase") => {
+    if (typeof value !== "string" || !Object.hasOwn(TARGETS, value)) {
+        throw new Error(`Unsupported Rehearsal runtime target: ${String(value)}. Supported targets: ${REHEARSAL_RUNTIME_TARGETS.join(", ")}.`);
+    }
+    return TARGETS[value];
+};

package/docs/README.md

@@ -1,29 +1,48 @@
-# Documentation map
+# Rehearsal documentation
+
+Most migration tests start with an empty database. Production does not. Existing rows,
+relationships, authentication identities, stored files, and migration history are where
+risky changes break.
+
+Rehearsal restores a reviewed, sanitized baseline into a disposable local environment,
+applies only the exact migrations you approve, and runs your application's own proof.
+
+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)
+- [Container runtime lifecycle](runtime-lifecycle.md)
+- [TypeScript](typescript.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)
+- [Stability and the first stable release](stability.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/architecture.md

@@ -5,7 +5,7 @@ documentation so each file has one obvious home.
 
 ```text
 rehearsal-db/
-├── src/                    shipped package code
+├── src/                    TypeScript product source
 │   ├── application/       application lifecycle and HTTP proofs
 │   ├── baseline/          sanitized baseline creation and validation
 │   ├── cli/               the `rehearsal` executable
@@ -16,8 +16,12 @@ rehearsal-db/
 │   ├── source/            approved source access and refresh
 │   └── targets/           PostgreSQL and Supabase adapters
 ├── scripts/
-│   ├── runtime/           shipped internal runtime launcher
+│   ├── build/             clean TypeScript compilation helpers
+│   ├── install/           TypeScript install-hook source
+│   ├── runtime/           TypeScript runtime-launcher source
 │   └── verification/      repository-only package and fixture proofs
+├── dist/                   generated ESM and declaration output; never edit directly
+├── types/                  compatibility entry point for generated declarations
 ├── tests/
 │   ├── unit/              mirrors the `src/` domains
 │   ├── integration/       multi-module and terminal behavior
@@ -29,6 +33,7 @@ rehearsal-db/
 ## Boundaries
 
 - `src/` must never import from tests or repository-only verification scripts.
+- `dist/` is rebuilt from TypeScript before tests and packaging; never hand-edit it.
 - Database-specific lifecycle behavior belongs in `src/targets/`.
 - `scripts/verification/` is never included in the npm package.
 - Public consumers use only the paths declared in `package.json#exports`.
@@ -38,15 +43,132 @@ rehearsal-db/
 ## CLI modules
 
 The executable is split by responsibility so no command file becomes a second
-application layer:
+application layer. Scripted commands and the interactive guide resolve through the same
+typed registry and produce the same result contract:
 
-- `rehearsal.mjs` starts the process and dispatches commands.
-- `arguments.mjs` owns the command-line contract and mutation classification.
-- `guided.mjs` owns the interactive home screen and first-run questions.
-- `runtime_commands.mjs` coordinates local runtimes and project proofs.
-- `source_commands.mjs` coordinates approved source access and refresh.
-- `renderers.mjs` formats human-readable results without changing state.
-- `terminal.mjs` owns prompts, colors, and terminal exit behavior.
+- `rehearsal.mts` owns process lifecycle, project locking, guided-loop coordination, and
+  top-level error handling. It does not implement commands.
+- `arguments.mts` owns the command-line contract and mutation classification.
+- `command_contract.mts`, `command_registry.mts`, and `command_output.mts` define command
+  context, handler selection, stable JSON envelopes, human rendering, and exit codes.
+- `*_command_handlers.mts` and `runtime_action_handlers.mts` group handlers by project,
+  source, identity, inspection, application, or runtime responsibility.
+- `cli_commands.mts` composes those focused families in precedence order without
+  implementing their behavior.
+- `guided.mts` owns the interactive home screen and first-run questions.
+- `runtime_commands.mts` coordinates local runtimes and project proofs.
+- `source_commands.mts` coordinates approved source access and refresh.
+- `renderers.mts` formats human-readable results without changing state.
+- `terminal.mts` owns prompts, colors, and terminal exit behavior.
+
+Command handlers receive an explicit context containing parsed flags, selected config,
+guided state, and session-local caches. They return a rendered, text, or silent result;
+only the shared output boundary creates JSON envelopes or writes final human output.
+Session caches never appear in the public parsed-flags type.
+
+Repository contracts keep the process entry point at 300 lines or fewer and every
+handler-family module at 350 lines or fewer. A new command belongs in the narrowest
+existing family, or in a new focused family when it represents a genuinely separate
+responsibility.
+
+## Configuration pipeline
+
+The stable `project/configuration.mts` facade keeps existing imports compatible while
+configuration work moves through explicit phases:
+
+1. `configuration_discovery.mts` selects one supported project-owned config path.
+2. `configuration_schema.mts` validates the raw object shape and rejects unknown keys.
+3. `configuration_normalization.mts` applies defaults and semantic safety constraints.
+4. `configuration_resolution.mts` resolves owned paths from the project root and checks
+   destructive-operation boundaries.
+
+The public contract/defaults, primitive validators, project detection, and starter
+rendering have their own focused modules. `NormalizedRehearsalConfig` is inferred from
+the normalizer, while the package's public declarations are emitted from the same
+TypeScript implementation. Repository contracts keep the facade at 50 lines or fewer
+and each configuration phase at 700 lines or fewer.
+
+## Installed-consumer verification
+
+Repository verification installs the package tarball into disposable projects; it must
+not import unpublished product source by accident. One scenario catalog drives both the
+individual fixture commands and `npm run release:verify`.
+
+- `scenarios/artifact.mjs` selects or packs one tarball, reads its package identity, and
+  records its SHA-256 before installation.
+- `scenarios/workspace.mjs` creates and removes only scenario-owned scratch roots.
+- `scenarios/process.mjs` starts commands with inherited credentials removed unless a
+  scenario explicitly supplies a safe value.
+- `scenarios/application_session.mjs` owns persistent application and terminal-session
+  checks.
+- `scenarios/catalog.mjs` is the sole ordered list of installed-consumer scenarios.
+- Fixture files contain only the target setup and assertions unique to that scenario.
+
+Each scenario remains independently runnable through its `test:fixture:*` script. The
+complete release gate runs every catalog entry against the same immutable tarball and
+writes its version, SHA-256, tool environment, commands, timings, and results under
+`test-results/release-gate/`.
+
+## Runtime lifecycle
+
+`runtime/lifecycle_engine.mts` owns the target-neutral lifecycle contract. Both
+PostgreSQL and Supabase use it to dispatch commands, verify active baseline inputs,
+calculate and confirm the exact migration set, write target-bound receipts, validate
+runtime markers, and roll back a failed reset or migration without hiding the original
+failure.
+
+The files in `src/targets/` remain drivers. They prove ownership before deleting local
+resources and implement only the behavior that genuinely differs: Docker PostgreSQL
+containers and SQL setup on one side; Supabase CLI, Auth, Storage, and generated config
+on the other. An ordinary `stop` never enters rollback or discard, so later `start`
+preserves the sandbox database and Storage contents.
+
+Repository contracts keep each target driver at 900 lines or fewer and the shared
+lifecycle engine at 300 lines or fewer. A new database target must use this lifecycle
+boundary rather than copying an existing driver's orchestration.
+
+## Identity claim pipeline
+
+The stable `identity/claim.mts` facade exposes policy validation, deterministic planning,
+and confirmed execution while keeping those responsibilities separate:
+
+1. `claim_contract.mts` defines the normalized policy, plan, database, and receipt types.
+2. `claim_policy.mts` validates and normalizes the reviewed declaration.
+3. `claim_plan.mts` binds the local matcher value to an immutable redacted review and
+   digest without opening a database or Storage connection.
+4. `claim_sql.mts` generates identifier-safe relational, JSON, signup-default, and path
+   SQL without executing it.
+5. `claim_identity_lookup.mts` performs read-only local Auth and reference discovery.
+6. `claim_verification.mts` checks signup defaults and token-hook claim shapes.
+7. `claim_executor.mts` alone owns the database transaction, Storage staging, rollback,
+   commit, old-object cleanup, and final receipt.
+8. `connect.mts` performs read-only, provider-neutral sign-in discovery and produces the
+   redacted preview used by the interactive copied-account connection.
+
+Repository contracts keep the facade at 50 lines or fewer and every identity-claim
+stage at 600 lines or fewer. Provider callbacks and consumer application behavior stay
+outside this pipeline.
+
+## Privacy rule pipeline
+
+The stable `baseline/privacy_engine.mts` facade preserves the documented privacy import
+path while policy work is divided into fail-closed typed stages:
+
+1. `privacy_contract.mts` defines normalized policy and execution types.
+2. `privacy_recipe_validation.mts` normalizes only reviewed rule shapes;
+   `privacy_policy.mts` validates complete policy structure.
+3. `privacy_dependency_graph.mts` checks owner bindings, path mappings, sanitized digest
+   inputs, cycles, and shared date groups.
+4. `privacy_transforms.mts` implements deterministic pseudonyms and bounded paths.
+5. `privacy_rule_registry.mts` explicitly registers every action and derivation kind;
+   unknown kinds have no fallback execution path.
+6. `privacy_structured_json.mts` owns bounded object, array, union, and dictionary rules.
+7. `privacy_pipeline.mts` resolves reviewed bindings and executes rows, while
+   `privacy_key.mts` owns the local secret-file boundary.
+
+Repository contracts keep the facade at 50 lines or fewer and every privacy stage at
+700 lines or fewer. Adding a rule requires its normalized type, validator, registered
+handler, focused boundary tests, and documentation—without widening policy version 2.
 
 ## Adding something new
 
@@ -56,3 +178,6 @@ application layer:
 4. Add an integration or contract test only when behavior crosses domains or becomes a
    public promise.
 5. Update the documentation map when adding a new guide.
+
+Run `npm run build` after changing TypeScript source. Tests import the generated package
+code so the same JavaScript boundary consumers install is exercised locally.

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,22 +32,28 @@ 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
 reviewing [the standalone security contract](standalone-workflow.md).
 
-| Command                                                       | What it does                                                         |
-| ------------------------------------------------------------- | -------------------------------------------------------------------- |
-| `npx rehearsal privacy key`                                   | Preview the owner-only pseudonym-key path.                           |
-| `npx rehearsal privacy key --write`                           | Create the key once; refuses to replace an existing key.             |
-| `npx rehearsal source plan`                                   | Preview the exact temporary reader, views, columns, and asset scope. |
-| `npx rehearsal source apply --confirm-source-access=<sha256>` | Create only the reviewed, time-limited source access.                |
-| `npx rehearsal baseline refresh`                              | Replace only the baseline from a reviewed source.                    |
-| `npx rehearsal refresh`                                       | Preview a complete safe refresh of the baseline and local runtime.   |
-| Add `--confirm-refresh=<sha256>`                              | Create the replacement, reset locally, and prune listed old copies.  |
-| `npx rehearsal source retire`                                 | Preview exact reader/view/credential retirement.                     |
-| Add `--confirm-source-retirement=<sha256>`                    | Apply that retirement plan and verify the exact object inventory.    |
+| Command                                                       | What it does                                                            |
+| ------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| `npx rehearsal privacy key`                                   | Preview the owner-only pseudonym-key path.                              |
+| `npx rehearsal privacy key --write`                           | Create the key once; refuses to replace an existing key.                |
+| `npx rehearsal source plan`                                   | Preview the exact temporary reader, views, columns, and asset scope.    |
+| `npx rehearsal source apply --confirm-source-access=<sha256>` | Create managed access, or verify external access without source writes. |
+| `npx rehearsal baseline refresh`                              | Replace only the baseline from a reviewed source.                       |
+| `npx rehearsal refresh`                                       | Preview a complete safe refresh of the baseline and local runtime.      |
+| Add `--confirm-refresh=<sha256>`                              | Create the replacement, reset locally, and prune listed old copies.     |
+| `npx rehearsal source retire`                                 | Preview managed retirement or external local-secret cleanup.            |
+| Add `--confirm-source-retirement=<sha256>`                    | Apply that retirement plan and verify the exact object inventory.       |
 
 Source credentials are read from environment variables named in the reviewed source
 policy. Never paste a connection string into an argument. `baseline refresh` leaves the
@@ -67,7 +73,26 @@ In short: `refresh` gets a new source copy; `reset` restores the copy you alread
 
 ## Local identity association
 
-After an ordinary local Google or email sign-in creates a verified local Auth identity:
+For a reviewed Google, GitHub, or email identity, use the guided connection:
+
+```bash
+npx rehearsal identity connect
+```
+
+Rehearsal starts and checks the local runtime, keeps the configured application open,
+and waits for an ordinary provider sign-in. It reads only the local Auth database—not
+browser cookies, passwords, passkeys, MFA secrets, or session tokens. When exactly one
+approved verified identity matches, it stops the owned app, shows a redacted preview,
+and offers **Connect my copied account**. One confirmation binds the exact current plan.
+After the verified transfer, Rehearsal reopens the app and asks for one sign-out/sign-in
+so the application receives fresh role claims.
+
+If the policy declares more than one copied identity, choose one with
+`--identity=<reviewed-name>`. The interactive guide presents the reviewed names. A
+completed connection is recognized from its local runtime receipt and is not repeated.
+Resetting the runtime removes that receipt and requires a fresh review and connection.
+
+For automation or detailed inspection, keep using the explicit commands:
 
 ```bash
 npx rehearsal identity plan --identity=approved-owner
@@ -78,7 +103,8 @@ npx rehearsal identity claim --identity=approved-owner \
 The first command shows only hashes and declared reference counts. The second updates
 only the reviewed local relational, JSON, Storage-owner, and claim locations in one
 transaction. It rejects hosted database URLs, wrong or unverified people, ambiguity, and
-stale confirmation digests.
+stale confirmation digests. Reopen the application and sign in again afterward to obtain
+fresh claims. Neither flow bypasses application roles, account blocks, RLS, or MFA.
 
 If a runtime-policy seed moves with that identity, declare its `identityAssociation` in
 the runtime policy. Later `verify` calls then require the transferred row instead of the
@@ -100,11 +126,12 @@ obsolete placeholder key.
 State-reporting commands accept `--json` for scripts. Scripts should use the JSON fields
 and process exit code, not parse human-facing text.
 
-## Run and manage the local database
+## Run and manage the local sandbox
 
 | Command                                               | What it does                                                        |
 | ----------------------------------------------------- | ------------------------------------------------------------------- |
 | `npx rehearsal run --confirm-candidates=<sha256>`     | Reset, apply exact candidates, launch the app, and run its proofs.  |
+| `npx rehearsal open`                                  | Start, verify, and keep the configured application open.            |
 | `npx rehearsal migrate --confirm-candidates=<sha256>` | Apply the exact candidates without resetting existing runtime data. |
 | `npx rehearsal start`                                 | Start an existing verified runtime.                                 |
 | `npx rehearsal verify`                                | Verify the current runtime and receipt.                             |
@@ -117,6 +144,13 @@ In a terminal, the guide displays candidate filenames and asks for confirmation.
 script, copy the digest from `candidates` into `--confirm-candidates`. Adding, removing,
 reordering, or editing a migration changes that digest.
 
+`open` does not reset the runtime or apply migrations. It starts and verifies every
+configured database target, runs dependent preparation commands, and launches
+`application.startCommand` with the declared local environment mappings. It waits for
+`application.readiness`, then stays attached until `Ctrl+C` or `Ctrl+Z`. On exit it stops
+only the application process group it launched. Use `stop` separately when you also want
+to stop the databases; a later `open` preserves their database and Storage changes.
+
 ## Clean up disk space
 
 Start with a preview:
@@ -145,6 +179,8 @@ belonging to other projects are never included. This follows
 
 | Option                                 | Meaning                                                          |
 | -------------------------------------- | ---------------------------------------------------------------- |
+| `--help`, `-h`                         | Show the installed command reference.                            |
+| `--version`, `-V`                      | Print the installed package version and exit.                    |
 | `--json`                               | Return the versioned machine-readable result.                    |
 | `--verbose`                            | Show more safe detail.                                           |
 | `--debug`                              | Show the most diagnostic detail; still review it before sharing. |
@@ -162,6 +198,8 @@ belonging to other projects are never included. This follows
 | `--write`                              | Apply a setup, policy, or cleanup preview.                       |
 
 Run `npx rehearsal --help` to print the command list available in your installed version.
+Run `npx rehearsal --version` to print only its version number. Add `--json` when a
+script also needs the package name.
 
 When a project has more than one config, pass `--config=<path>` on every command for the
 non-default one. Rehearsal keeps that exact config selected through status, run, reset,