@rehearsal-db/core 0.1.0-beta.16 → 0.1.0-beta.18

package/dist/src/cli/project_commands.d.mts

@@ -27,7 +27,7 @@ export declare const createProjectCommands: ({ projectRoot, runManager, }: {
     projectRoot: string;
     runManager: RunManager;
 }) => Readonly<{
-    loadIdentityClaimPlan: ({ flags, planOptions, }: ProjectCommandInput) => Promise<{
+    loadIdentityClaimPlan: ({ flags, planOptions, session, }: ProjectCommandInput) => Promise<{
         loaded: Readonly<{
             config: Readonly<{
                 schemaVersion: 1;
@@ -151,6 +151,130 @@ export declare const createProjectCommands: ({ projectRoot, runManager, }: {
         }>;
         plan: import("../identity/claim_contract.mjs").IdentityClaimPlan;
     }>;
+    loadIdentityPolicy: ({ planOptions }: ProjectCommandInput) => Promise<{
+        loaded: Readonly<{
+            config: Readonly<{
+                schemaVersion: 1;
+                project: Readonly<{
+                    name: string;
+                }>;
+                supabase: Readonly<{
+                    workdir: string;
+                    migrationDirectory: string;
+                    rehearsalConfig: string;
+                    runtimeWorkdir: string;
+                    authentication: Readonly<{
+                        enableLocalSignup: true;
+                        environmentFile: string;
+                        providers: readonly Readonly<{
+                            name: "github" | "google";
+                            clientIdEnvironmentVariable: string;
+                            clientSecretEnvironmentVariable: string;
+                            skipNonceCheck: boolean;
+                            emailOptional: boolean;
+                        }>[];
+                    }> | null;
+                    serviceEnvironmentFile: string | null;
+                    serviceEnvironmentVariables: readonly string[];
+                }> | null;
+                postgresql: Readonly<{
+                    migrationDirectory: string;
+                    runtimeWorkdir: string;
+                    image: string;
+                    database: string;
+                    user: string;
+                }> | null;
+                baseline: Readonly<{
+                    artifactDirectory: string;
+                    sanitizationPolicy: string;
+                }>;
+                containerRuntime: Readonly<{
+                    autoStartColima: boolean;
+                }>;
+                cleanup: Readonly<{
+                    retainBaselineGenerations: number;
+                }>;
+                preparation: Readonly<{
+                    sourcePolicy: string;
+                    privacyKey: string;
+                    batchRows: number;
+                    maximumRows: number;
+                    maximumBytes: number;
+                    diskHeadroomBytes: number;
+                }> | null;
+                runtimePolicy: string | null;
+                identityPolicy: string | null;
+                dependentTargets: readonly Readonly<{
+                    name: string;
+                    configPath: string;
+                    prepareCommand: string | null;
+                }>[];
+                application: Readonly<{
+                    startCommand: string;
+                    proofCommand: string;
+                    environmentFile: string;
+                    environmentVariables: Readonly<Record<string, string>>;
+                    readiness: Readonly<{
+                        url: string;
+                        expectedStatus: number;
+                        timeoutSeconds: number;
+                    }> | null;
+                    httpProofs: readonly Readonly<{
+                        name: string;
+                        kind: "positive" | "negative";
+                        url: string;
+                        method: string;
+                        expectedStatus: number;
+                        json: Readonly<{
+                            path: readonly string[];
+                            equals?: unknown;
+                            notEquals?: unknown;
+                            minimumItems?: number;
+                        }> | null;
+                    }>[];
+                    runtimeAdapter: string | null;
+                }>;
+                runtime: Readonly<{
+                    target: "postgresql" | "supabase";
+                    applicationUrl: string;
+                    projectId: string;
+                    ports: Readonly<{
+                        api?: number;
+                        database: number;
+                        studio?: number;
+                    }>;
+                }>;
+                safety: Readonly<{
+                    allowedHosts: readonly string[];
+                    blockedEnvironmentVariables: readonly string[];
+                    authenticationProviders: readonly string[];
+                    hostedAccess: "disabled";
+                    outboundNetwork: "deny";
+                }>;
+                verification: Readonly<{
+                    commands: readonly string[];
+                }>;
+            }>;
+            configPath: string;
+            projectRoot: string;
+            paths: Readonly<{
+                artifactDirectory: string;
+                applicationEnvironment: string;
+                migrationDirectory: string;
+                rehearsalConfig: string | null;
+                runtimeWorkdir: string;
+                serviceEnvironment: string | null;
+                sanitizationPolicy: string;
+                sourcePolicy: string | null;
+                privacyKey: string | null;
+                runtimePolicy: string | null;
+                identityPolicy: string | null;
+                supabaseWorkdir: string | null;
+                runtimeAdapter: string | null;
+            }>;
+        }>;
+        policy: import("../identity/claim_contract.mjs").IdentityPolicy;
+    }>;
     planRuntimeStackCleanup: ({ flags, planOptions, }: ProjectCommandInput) => Promise<RehearsalCleanupPlan | CleanupStackPlan>;
     runBaselinePreparation: ({ flags, planOptions, session, }: ProjectCommandInput) => Promise<ReturnType<typeof summarizeBaselinePreparation>>;
     runCleanup: ({ flags, planOptions, session, }: ProjectCommandInput) => Promise<unknown>;

package/dist/src/cli/project_commands.mjs

@@ -156,15 +156,23 @@ export const createProjectCommands = ({ projectRoot, runManager, }) => {
         });
         return { mode: "written", plan, applied };
     };
-    const loadIdentityClaimPlan = async ({ flags, planOptions, }) => {
+    const loadIdentityPolicy = async ({ planOptions }) => {
         const loaded = await loadRehearsalConfig(planOptions);
         if (!loaded.paths.identityPolicy) {
             throw new Error("No config.identityPolicy is configured.");
         }
+        const policy = validateIdentityPolicy(JSON.parse(await readFile(loaded.paths.identityPolicy, "utf8")));
+        return { loaded, policy };
+    };
+    const loadIdentityClaimPlan = async ({ flags, planOptions, session, }) => {
+        const { loaded, policy } = await loadIdentityPolicy({
+            flags,
+            planOptions,
+            ...(session === undefined ? {} : { session }),
+        });
         if (!flags.identityName) {
             throw new Error("Choose a declared identity with --identity=<name>.");
         }
-        const policy = validateIdentityPolicy(JSON.parse(await readFile(loaded.paths.identityPolicy, "utf8")));
         return {
             loaded,
             plan: createIdentityClaimPlan({
@@ -175,6 +183,7 @@ export const createProjectCommands = ({ projectRoot, runManager, }) => {
     };
     return Object.freeze({
         loadIdentityClaimPlan,
+        loadIdentityPolicy,
         planRuntimeStackCleanup,
         runBaselinePreparation,
         runCleanup,

package/dist/src/cli/runtime_commands.d.mts

@@ -223,6 +223,31 @@ export declare const createRuntimeCommands: ({ packageRoot, projectRoot, manager
             diagnostics: import("../application/session.mjs").ApplicationDiagnostics;
         };
     }>;
+    startRuntimeApplication: ({ flags, planOptions, session: commandSession, }: {
+        flags: RehearsalCliFlags;
+        planOptions: RehearsalConfigPathOptions;
+        session: CliSessionState;
+    }) => Promise<{
+        started: ManagerReceipt | Readonly<{
+            action: RuntimeAction;
+            durationMs: number;
+            output: string;
+            targets: readonly ManagerReceipt[];
+        }>;
+        verified: ManagerReceipt | Readonly<{
+            action: RuntimeAction;
+            durationMs: number;
+            output: string;
+            targets: readonly ManagerReceipt[];
+        }>;
+        preparations: {
+            command: string;
+            output: string;
+            target: string;
+        }[];
+        command: string;
+        session: import("../application/session.mjs").ApplicationSession;
+    }>;
     prepareCandidateConfirmation: ({ command, flags, planOptions, session, }: {
         command: RuntimeAction;
         flags: RehearsalCliFlags;

package/dist/src/cli/runtime_commands.mjs

@@ -479,7 +479,7 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
         });
         return { applicationProof, dependentProofs };
     };
-    const openRuntimeApplication = async ({ flags, planOptions, session: commandSession, onReady = () => undefined, }) => {
+    const startRuntimeApplication = async ({ flags, planOptions, session: commandSession, }) => {
         const topology = await loadRuntimeTopology(planOptions);
         const application = topology.primary.config.application;
         if (!application.readiness) {
@@ -515,22 +515,39 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
             topology,
             environment: topologyCommandEnvironment(topology),
         });
-        const session = await startApplicationSession({
+        const applicationSession = await startApplicationSession({
             command: application.startCommand,
             cwd: topology.projectRoot,
             files: topologyEnvironmentFiles(topology),
             mappings: application.environmentVariables,
             readiness: application.readiness,
         });
-        const closed = await holdApplicationSession({ session, onReady });
         return {
-            action: "open",
             started: started.runtime,
             verified: verified.runtime,
             preparations,
+            command: application.startCommand,
+            session: applicationSession,
+        };
+    };
+    const openRuntimeApplication = async ({ flags, planOptions, session: commandSession, onReady = () => undefined, }) => {
+        const active = await startRuntimeApplication({
+            flags,
+            planOptions,
+            session: commandSession,
+        });
+        const closed = await holdApplicationSession({
+            session: active.session,
+            onReady,
+        });
+        return {
+            action: "open",
+            started: active.started,
+            verified: active.verified,
+            preparations: active.preparations,
             application: {
-                command: application.startCommand,
-                readiness: session.ready,
+                command: active.command,
+                readiness: active.session.ready,
                 stoppedBy: closed.signal,
                 diagnostics: closed.diagnostics,
             },
@@ -592,6 +609,7 @@ export const createRuntimeCommands = ({ packageRoot, projectRoot, managerPath, g
     };
     return {
         openRuntimeApplication,
+        startRuntimeApplication,
         prepareCandidateConfirmation,
         prepareDependentTargets,
         proveRuntimeStack,

package/dist/src/identity/claim_identity_lookup.d.mts

@@ -10,8 +10,14 @@ export interface VerifiedLocalIdentity {
     readonly id: string;
     readonly provider: IdentityProvider;
 }
-export declare const findVerifiedLocalIdentity: ({ client, plan, matchValue, }: {
+export declare class IdentityLookupError extends Error {
+    readonly reason: "none" | "ambiguous" | "conflict" | "invalid";
+    constructor(reason: "none" | "ambiguous" | "conflict" | "invalid", message: string);
+}
+export declare const isIdentityNotFoundError: (error: unknown) => error is IdentityLookupError;
+export declare const findVerifiedLocalIdentity: ({ client, plan, matchValue, lock, }: {
     client: IdentityDatabaseClient;
     plan: IdentityClaimPlan;
     matchValue: string;
+    lock?: boolean;
 }) => Promise<VerifiedLocalIdentity>;

package/dist/src/identity/claim_identity_lookup.mjs

@@ -48,7 +48,16 @@ export const countIdentityRows = async ({ client, reference, userId, }) => {
     }
     return count;
 };
-export const findVerifiedLocalIdentity = async ({ client, plan, matchValue, }) => {
+export class IdentityLookupError extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.name = "IdentityLookupError";
+        this.reason = reason;
+    }
+}
+export const isIdentityNotFoundError = (error) => error instanceof IdentityLookupError && error.reason === "none";
+export const findVerifiedLocalIdentity = async ({ client, plan, matchValue, lock = true, }) => {
     const matcher = plan.identity.matcher;
     if (matcher.type === "verified-email") {
         const match = await client.query(`select u.id::text, i.provider
@@ -60,23 +69,23 @@ export const findVerifiedLocalIdentity = async ({ client, plan, matchValue, }) =
            coalesce((i.identity_data->>'email_verified')::boolean, false)
            or u.email_confirmed_at is not null
          )
-       for update of u`, [matchValue, matcher.providers]);
+         ${lock ? "for update of u" : ""}`, [matchValue, matcher.providers]);
         if (match.rows.length !== 1) {
-            throw new Error(match.rows.length === 0
+            throw new IdentityLookupError(match.rows.length === 0 ? "none" : "ambiguous", match.rows.length === 0
                 ? "No verified local identity matches the reviewed email and provider allowlist."
                 : "More than one verified local identity matches the reviewed email and provider allowlist.");
         }
         const matchedRow = match.rows[0];
         if (!matchedRow)
-            throw new Error("Matched local identity is invalid.");
+            throw new IdentityLookupError("invalid", "Matched local identity is invalid.");
         const matchedProvider = matchedRow.provider ??
             (matcher.providers.length === 1 ? matcher.providers[0] : null);
         if (typeof matchedProvider !== "string" ||
             !matcher.providers.includes(matchedProvider)) {
-            throw new Error("Matched local identity provider is invalid.");
+            throw new IdentityLookupError("invalid", "Matched local identity provider is invalid.");
         }
         if (typeof matchedRow.id !== "string") {
-            throw new Error("Matched local identity is invalid.");
+            throw new IdentityLookupError("invalid", "Matched local identity is invalid.");
         }
         return {
             id: matchedRow.id,
@@ -94,7 +103,7 @@ export const findVerifiedLocalIdentity = async ({ client, plan, matchValue, }) =
          coalesce((i.identity_data->>'email_verified')::boolean, false)
          or u.email_confirmed_at is not null
        )
-     for update of u`, [matcher.provider]);
+     ${lock ? "for update of u" : ""}`, [matcher.provider]);
     const matches = [];
     for (const candidate of candidates.rows) {
         const subjects = [candidate.provider_id, candidate.subject]
@@ -103,23 +112,23 @@ export const findVerifiedLocalIdentity = async ({ client, plan, matchValue, }) =
         const uniqueSubjects = [...new Set(subjects)];
         if (uniqueSubjects.some((subject) => hash(subject) === matcher.approvedSubjectSha256)) {
             if (uniqueSubjects.length !== 1) {
-                throw new Error("The matched local provider identity has conflicting stable subjects.");
+                throw new IdentityLookupError("conflict", "The matched local provider identity has conflicting stable subjects.");
             }
             if (typeof candidate.id !== "string" ||
                 candidate.provider !== matcher.provider) {
-                throw new Error("Matched local identity provider is invalid.");
+                throw new IdentityLookupError("invalid", "Matched local identity provider is invalid.");
             }
             matches.push({ id: candidate.id, provider: matcher.provider });
         }
     }
     if (matches.length !== 1) {
-        throw new Error(matches.length === 0
+        throw new IdentityLookupError(matches.length === 0 ? "none" : "ambiguous", matches.length === 0
             ? "No verified local identity matches the reviewed provider subject."
             : "More than one verified local identity matches the reviewed provider subject.");
     }
     const match = matches[0];
     if (!match || match.provider !== matcher.provider) {
-        throw new Error("Matched local identity provider is invalid.");
+        throw new IdentityLookupError("invalid", "Matched local identity provider is invalid.");
     }
     return match;
 };

package/dist/src/identity/connect.d.mts

@@ -0,0 +1,30 @@
+/** Read-only discovery and redacted review for the guided account connection. */
+import type { IdentityClaimPlan, IdentityClientFactory, IdentityProvider } from "./claim_contract.mjs";
+export interface IdentityConnectionPreview {
+    readonly name: string;
+    readonly provider: IdentityProvider;
+    readonly planDigest: string;
+    readonly relationalGroups: number;
+    readonly preservedAuditGroups: number;
+    readonly nestedJsonGroups: number;
+    readonly signupDefaults: number;
+    readonly storagePathGroups: number;
+    readonly assetScopes: number;
+    readonly claimKeys: number;
+    readonly tokenHookConfigured: boolean;
+    readonly associated: boolean;
+}
+export declare const inspectIdentityConnection: ({ plan, connectionString, clientFactory, }: {
+    plan: IdentityClaimPlan;
+    connectionString: string;
+    clientFactory?: IdentityClientFactory;
+}) => Promise<IdentityConnectionPreview>;
+export declare const waitForIdentityConnection: ({ plan, connectionString, clientFactory, inspect, signal, pollIntervalMs, timeoutMs, }: {
+    plan: IdentityClaimPlan;
+    connectionString: string;
+    clientFactory?: IdentityClientFactory;
+    inspect?: typeof inspectIdentityConnection;
+    signal?: AbortSignal;
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+}) => Promise<IdentityConnectionPreview>;

package/dist/src/identity/connect.mjs

@@ -0,0 +1,111 @@
+/** Read-only discovery and redacted review for the guided account connection. */
+import pg from "pg";
+import { findVerifiedLocalIdentity, isIdentityNotFoundError, } from "./claim_identity_lookup.mjs";
+import { getIdentityPlanMatchValue } from "./claim_plan.mjs";
+const { Client } = pg;
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/iu;
+const assertLocalDatabase = (connectionString) => {
+    let target;
+    try {
+        target = new URL(connectionString);
+    }
+    catch {
+        throw new Error("Identity connection requires a valid local database URL.");
+    }
+    if (!["postgres:", "postgresql:"].includes(target.protocol) ||
+        !["127.0.0.1", "::1", "localhost"].includes(target.hostname)) {
+        throw new Error("Identity connection may inspect only the local Rehearsal database.");
+    }
+};
+const hasAssociationReceipt = async ({ client, name, placeholderUserId, localUserId, }) => {
+    const relation = await client.query("select to_regclass('rehearsal_internal.identity_claims')::text as relation");
+    if (relation.rows[0]?.relation !== "rehearsal_internal.identity_claims") {
+        return false;
+    }
+    const receipt = await client.query(`select 1
+     from rehearsal_internal.identity_claims
+     where identity_name = $1
+       and placeholder_user_id = $2::uuid
+       and local_user_id = $3::uuid
+     limit 1`, [name, placeholderUserId, localUserId]);
+    return receipt.rows.length === 1;
+};
+export const inspectIdentityConnection = async ({ plan, connectionString, clientFactory, }) => {
+    assertLocalDatabase(connectionString);
+    const matchValue = getIdentityPlanMatchValue(plan);
+    if (!matchValue) {
+        throw new Error("Identity connection plans must use the reviewed local matcher environment.");
+    }
+    const client = clientFactory
+        ? await clientFactory(connectionString)
+        : new Client({
+            connectionString,
+            application_name: "rehearsal-identity-connect",
+        });
+    await client.connect?.();
+    try {
+        const localIdentity = await findVerifiedLocalIdentity({
+            client,
+            plan,
+            matchValue,
+            lock: false,
+        });
+        if (!UUID.test(localIdentity.id)) {
+            throw new Error("Matched local identity is invalid.");
+        }
+        return Object.freeze({
+            name: plan.review.name,
+            provider: localIdentity.provider,
+            planDigest: plan.digest,
+            relationalGroups: plan.review.references.filter((reference) => reference.strategy === "transfer").length,
+            preservedAuditGroups: plan.review.references.filter((reference) => reference.strategy === "preserve-audit").length,
+            nestedJsonGroups: plan.review.jsonReferences.length,
+            signupDefaults: plan.review.signupDefaults.length,
+            storagePathGroups: plan.review.pathReferences.length,
+            assetScopes: plan.review.assets.length,
+            claimKeys: plan.review.claimKeys.length,
+            tokenHookConfigured: plan.review.tokenHook !== null,
+            associated: await hasAssociationReceipt({
+                client,
+                name: plan.identity.name,
+                placeholderUserId: plan.identity.placeholderUserId,
+                localUserId: localIdentity.id,
+            }),
+        });
+    }
+    finally {
+        await client.end?.();
+    }
+};
+const abortableDelay = (milliseconds, signal) => new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+        reject(signal.reason ?? new Error("Identity connection was cancelled."));
+        return;
+    }
+    const timeout = setTimeout(resolve, milliseconds);
+    signal?.addEventListener("abort", () => {
+        clearTimeout(timeout);
+        reject(signal.reason ?? new Error("Identity connection was cancelled."));
+    }, { once: true });
+});
+export const waitForIdentityConnection = async ({ plan, connectionString, clientFactory, inspect = inspectIdentityConnection, signal, pollIntervalMs = 750, timeoutMs = 15 * 60 * 1_000, }) => {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (signal?.aborted) {
+            throw signal.reason ?? new Error("Identity connection was cancelled.");
+        }
+        try {
+            return await inspect({
+                plan,
+                connectionString,
+                ...(clientFactory === undefined ? {} : { clientFactory }),
+            });
+        }
+        catch (error) {
+            if (!isIdentityNotFoundError(error))
+                throw error;
+        }
+        await abortableDelay(pollIntervalMs, signal);
+    }
+    throw new Error("Timed out waiting for the approved verified local identity. Nothing was changed.");
+};

package/dist/src/project/configuration_rendering.mjs

@@ -58,6 +58,7 @@ export default defineRehearsalConfig({
 	// runtimePolicy: "infrastructure/rehearsal/runtime-policy.json",
 	// Optional copied-account association. The JSON stores only reviewed matcher hashes;
 	// raw emails/subjects and provider credentials stay in ignored environment files.
+	// After setup, run: npx rehearsal identity connect
 	// identityPolicy: "infrastructure/rehearsal/identity-policy.json",
 
 	// Reuse any running Docker-compatible engine; start Colima only when needed.
@@ -162,6 +163,7 @@ export default defineRehearsalConfig({
 	// runtimePolicy: "infrastructure/rehearsal/runtime-policy.json",
 	// Optional copied-account association. The JSON stores only reviewed matcher hashes;
 	// raw emails/subjects and provider credentials stay in ignored environment files.
+	// After setup, run: npx rehearsal identity connect
 	// identityPolicy: "infrastructure/rehearsal/identity-policy.json",
 
 	// Reuse any running Docker-compatible engine; start Colima only when needed.

package/docs/README.md

@@ -32,6 +32,7 @@ want to accomplish and follow that path.
 ## Follow the project
 
 - [Roadmap](roadmap.md)
+- [Stability and the first stable release](stability.md)
 - [Repository architecture](architecture.md)
 - [Release process](releasing.md)
 

package/docs/architecture.md

@@ -142,6 +142,8 @@ and confirmed execution while keeping those responsibilities separate:
 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

package/docs/commands.md

@@ -73,20 +73,26 @@ In short: `refresh` gets a new source copy; `reset` restores the copy you alread
 
 ## Local identity association
 
-For a reviewed Google, GitHub, or email identity, use this sequence:
+For a reviewed Google, GitHub, or email identity, use the guided connection:
 
-1. Run a successful rehearsal, then start the persistent app:
+```bash
+npx rehearsal identity connect
+```
 
-   ```bash
-   npx rehearsal open
-   ```
+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.
 
-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. Provider setup and credentials belong to the local
-   Supabase runtime, not the identity policy.
+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.
 
-3. Preview and confirm the reviewed association:
+For automation or detailed inspection, keep using the explicit commands:
 
 ```bash
 npx rehearsal identity plan --identity=approved-owner
@@ -94,14 +100,11 @@ npx rehearsal identity claim --identity=approved-owner \
   --confirm-identity=<sha256>
 ```
 
-4. Run `npx rehearsal open` again. Sign out and sign in again so the browser receives a
-   fresh session, then check the copied account. Rehearsal does not bypass application
-   role checks, account blocks, RLS, or MFA.
-
 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

package/docs/configuration.md

@@ -79,6 +79,7 @@ export default defineRehearsalConfig({
   // runtimePolicy: "infrastructure/rehearsal/runtime-policy.json",
   // Optional copied-account association. The JSON stores reviewed matcher hashes only;
   // raw emails/subjects and provider credentials stay in ignored environment files.
+  // After setup, run: npx rehearsal identity connect
   // identityPolicy: "infrastructure/rehearsal/identity-policy.json",
   containerRuntime: {
     autoStartColima: true,

package/docs/releasing.md

@@ -58,16 +58,21 @@ The independent Rehearsal Test Lab is the primary pre-release consumer environme
 Real product integrations provide additional compatibility evidence; they do not
 replace the package-owned release gate or Test Lab.
 
-The workflow publishes prereleases under the `beta` dist-tag and refuses a stable
-version. While Rehearsal has no stable release, the workflow also moves `latest` to the
-same reviewed beta. This keeps the npm package page and the ordinary
-`npm install @rehearsal-db/core` command current. When Rehearsal gains a stable release,
-`latest` must switch to the stable line while `beta` continues to identify prereleases.
+The workflow publishes beta and release-candidate versions under the `beta` dist-tag.
+While Rehearsal has no stable release, it also moves `latest` to the same reviewed
+prerelease. This keeps the npm package page and the ordinary
+`npm install @rehearsal-db/core` command current. A stable version publishes under
+`latest` without changing `beta`; after that point, later prereleases update only `beta`
+and cannot replace the stable `latest` line. The GitHub prerelease setting must agree
+with the package version or preparation fails.
+
+The objective promotion checklist and compatibility boundary live in
+[Stability and the first stable release](stability.md).
 
 The trusted publisher allows `npm dist-tag` only so this workflow can maintain those two
-tags without a stored npm token. A manual workflow run from `main` can repair the tags
-for the exact prerelease version currently recorded in `package.json`; it cannot publish
-a package or select a different version. The protected `npm` environment still supplies
+tags without a stored npm token. A manual workflow run from `main` can repair the correct
+channel for the exact version currently recorded in `package.json`; it cannot publish a
+package or select a different version. The protected `npm` environment still supplies
 the human approval gate.
 
 Creating the repository, passing CI, extracting the engine, merging a release branch,