@rehearsal-db/core 1.0.0 → 1.0.1

package/CHANGELOG.md

@@ -5,6 +5,18 @@ a Changelog, and versions will follow Semantic Versioning after the package exis
 
 ## [Unreleased]
 
+### Platform compatibility
+
+- Keep macOS Intel/Apple Silicon and Linux execution distinct from Windows desktop
+  access through WSL 2. Require the WSL project's Linux filesystem; document the
+  preview's actual component and runtime limits rather than claiming every OS works.
+- Verify installed package version/discovery on real desktop OS runners and exercise
+  PostgreSQL/dependent targets in an owned Windows 2025 WSL2 Ubuntu distribution.
+  Provision checksum-verified official Node and signed Docker Engine packages without
+  Docker Desktop, a daemon TCP endpoint or new branch-protection requirements.
+- Document native Windows runtime refusal and the Linux/Remote-WSL setup path; version,
+  help and project discovery remain distinct from database-runtime support.
+
 ## [1.0.0] - 2026-10-17
 
 ### Stable compatibility

package/COMPATIBILITY.md

@@ -32,6 +32,49 @@ default and the release-build runtime. End-of-life and odd-numbered Node.js rele
 not supported. A future release may remove a Node.js line after its upstream end-of-life
 date, with that change called out in the changelog.
 
+## Operating systems and execution location
+
+Core 1.0.1's platform boundary distinguishes the computer running VS Code from the
+operating system actually executing Node, Docker and Rehearsal. The corresponding editor
+changes are delivered with extension 0.1.21. A Windows desktop connected to WSL is not native
+Windows execution.
+
+| Execution environment                                                  | Runtime boundary                                                                                                           |
+| ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
+| macOS, Intel or Apple Silicon                                          | POSIX runtime; supported Node and a local Docker-compatible engine required                                                |
+| Linux                                                                  | POSIX runtime; Ubuntu 24.04 is the primary PostgreSQL/Supabase fixture environment                                         |
+| Windows with WSL 2                                                     | Run Linux Node and Docker inside the distribution, with the project on its Linux filesystem; compatibility preview         |
+| Native Windows Node, PowerShell or Command Prompt                      | Version, help and read-only project discovery remain available; runtime/setup/database operations refuse with WSL guidance |
+| WSL 1, a WSL project on `/mnt/c` or another Windows-mounted filesystem | Not a supported database-runtime environment                                                                               |
+| SSH, Dev Containers, Codespaces or browser-only VS Code                | No end-to-end support claim; different host, filesystem and port-forwarding boundaries need their own verification         |
+| iOS, iPadOS, Android, BSD and other unlisted systems                   | Not supported; installing a JavaScript package does not establish a compatible database engine or desktop extension host   |
+
+Do not bypass native Windows refusal with permission bits or a shell wrapper. Native
+Windows ACLs, process-tree retirement and baseline filesystem behavior are not certified
+by Linux tests. Keep keys, baselines and working files in the WSL Linux home filesystem,
+not a Windows share. The package does not move an existing project automatically.
+See [Windows and WSL setup](docs/getting-started.md#windows-use-a-wsl-2-linux-workspace).
+
+### What platform verification proves
+
+The separate `Platform compatibility` workflow preserves existing release/check names.
+Desktop jobs install the packed package and exercise version/discovery from a path with
+spaces and Unicode on real Linux, macOS and Windows runners. Windows also checks the
+intentional runtime refusal; a passing Windows job is not a working Windows database.
+The Windows 2025 WSL job provisions its own Ubuntu 24.04 distribution, verifies Linux
+execution and filesystem location, then runs the existing real PostgreSQL/dependent-target
+fixtures against a local Unix-socket Docker Engine. It does not install Docker Desktop
+or expose the daemon over TCP. Node uses the official release checksum; Docker packages
+use its signed apt repository. These integrity checks are not independent publisher
+authentication.
+
+A configured workflow is not passing evidence. Reports identify actual OS, architecture,
+installed artifact and exercised boundary. The WSL fixture does not certify native
+Windows runtime, WSL Supabase/Auth/Storage, a native Remote-WSL VS Code session, all Linux
+distributions, assistive technology or every architecture. Editor Node/controller tests
+are separate from real extension-host and browser walkthroughs. Intel/ARM labels and
+Windows/WSL are never interchangeable evidence.
+
 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

package/README.md

@@ -16,6 +16,7 @@
 <p align="center">
   <a href="https://ddupasquier.github.io/rehearsal-db/">Read the documentation</a> ·
   <a href="https://www.npmjs.com/package/@rehearsal-db/core">View on npm</a> ·
+  <a href="https://ddupasquier.github.io/rehearsal-db/vscode/">Free VS Code Starter</a> ·
   <a href="https://github.com/Ddupasquier/rehearsal-db">Source on GitHub</a> ·
   <a href="https://github.com/Ddupasquier/rehearsal-db/issues">Report a problem</a>
 </p>
@@ -45,8 +46,14 @@ it through a reviewed privacy policy, and retire the access again. It is never p
 `run`, `reset`, `migrate`, or application launch. Rehearsal is not a backup system or a
 production deployment tool.
 
-> **Pre-1.0 safety note:** use Rehearsal on a branch and keep a working backup of your
-> project.
+The CLI is free and MIT-licensed, with stable releases on
+[npm](https://www.npmjs.com/package/@rehearsal-db/core). This guide targets **1.0.1**;
+install only a version actually published there. Prefer a visual workflow?
+[Install the free VS Code Starter preview](docs/vscode.md). Its included features are
+free indefinitely for personal or commercial development—no account, card, or trial.
+
+Work on a branch and keep a working backup of your project. Rehearsal's local safety
+boundaries do not replace version control or backups.
 
 ## What you need
 
@@ -62,6 +69,12 @@ your migration is intended to change.
 
 ## Quick start
 
+Prefer OS-specific files? Use the [Windows / WSL 2](installers/windows/README.md),
+[macOS](installers/macos/README.md) or [Linux](installers/linux/README.md) setup folder.
+These readable helpers require existing Node.js 24 or 26 and check prerequisites by
+default; installation is an explicit option. They do not install OS tools or start a
+database. See [their exact behavior and release availability](installers/README.md).
+
 From your project directory:
 
 ```bash
@@ -157,18 +170,24 @@ loads.
 
 ## Supported today
 
-| Environment                                      | Support                |
-| ------------------------------------------------ | ---------------------- |
-| Supabase CLI projects                            | Supported              |
-| Ordinary PostgreSQL in local Docker              | Supported              |
-| macOS and Linux                                  | Supported              |
-| WSL                                              | Experimental           |
-| Native Windows                                   | Not yet supported      |
-| Hosted database URLs                             | Intentionally rejected |
-| Optional read-only PostgreSQL source preparation | Explicit opt-in beta   |
-| MySQL, MongoDB, and other database families      | Not yet supported      |
+| Environment                                      | Support                      |
+| ------------------------------------------------ | ---------------------------- |
+| Supabase CLI projects                            | Supported                    |
+| Ordinary PostgreSQL in local Docker              | Supported                    |
+| macOS and Linux                                  | Supported                    |
+| Windows via WSL 2 on its Linux filesystem        | Compatibility preview        |
+| Native Windows runtime                           | Not yet supported; use WSL 2 |
+| Hosted database URLs                             | Intentionally rejected       |
+| Optional read-only PostgreSQL source preparation | Explicit opt-in beta         |
+| MySQL, MongoDB, and other database families      | Not yet supported            |
 
 See [COMPATIBILITY.md](COMPATIBILITY.md) for the exact support contract.
+Native Windows metadata commands are not database-runtime support. For Windows, follow
+the [WSL 2 setup path](docs/getting-started.md#windows-use-a-wsl-2-linux-workspace):
+Linux Node, project files and Docker must live in the Linux execution environment.
+Core 1.0.1 and editor 0.1.21 add explicit platform guidance/refusal; older immutable
+releases retain their original behavior. Mobile, browser-only and unlisted systems are
+not implied by desktop or Linux compatibility.
 
 ## Documentation
 

package/dist/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@rehearsal-db/core",
-    "version": "1.0.0",
+    "version": "1.0.1",
     "private": false,
     "description": "Catch PostgreSQL and Supabase migrations that pass on empty databases but fail on real data—before deploy.",
     "repository": {
@@ -78,7 +78,7 @@
         "test:fixture:resources": "npm run build && node scripts/verification/run_scenario.mjs resources",
         "release:verify": "npm run build && node scripts/verification/release_gate.mjs",
         "check": "npm run check:syntax && npm run typecheck && npm run test && npm run docs:build && npm run format:check && npm run package:audit",
-        "check:syntax": "find scripts tests -type f -name '*.mjs' -exec node --check {} +",
+        "check:syntax": "node scripts/verification/check_syntax.mjs",
         "typecheck": "npm run build && tsc --project tsconfig.json",
         "format": "prettier --write .",
         "format:check": "prettier --check .",

package/dist/scripts/install/create_root_config.mjs

@@ -2,10 +2,17 @@
 /** Create safe project-root Rehearsal scaffolding during a local install. */
 import { fileURLToPath } from "node:url";
 import { createInstalledRehearsalScaffold, renderInstalledRehearsalScaffold, } from "../../src/project/install_scaffold.mjs";
+import { inspectHostPlatform } from "../../src/shared/host_platform.mjs";
 const packageRoot = fileURLToPath(new URL("../../..", import.meta.url));
 try {
-    const result = await createInstalledRehearsalScaffold({ packageRoot });
-    console.log(renderInstalledRehearsalScaffold(result));
+    const host = await inspectHostPlatform();
+    if (!host.supported) {
+        console.log(`Rehearsal installed without creating project files. ${host.remediation}`);
+    }
+    else {
+        const result = await createInstalledRehearsalScaffold({ packageRoot });
+        console.log(renderInstalledRehearsalScaffold(result));
+    }
 }
 catch (error) {
     const message = error instanceof Error ? error.message : String(error);

package/dist/src/cli/rehearsal.mjs

@@ -22,6 +22,7 @@ import { buildRefreshWorkflowPlan, createRefreshWorkflow, } from "./source_comma
 import { installGuidedExitShortcut, useStyledPrompts } from "./terminal.mjs";
 import { runWithOperationCancellation, supportsOperationCancellation, } from "../shared/cancellation.mjs";
 import { withOperationProgress } from "../shared/operation_progress.mjs";
+import { assertSupportedHostPlatform } from "../shared/host_platform.mjs";
 const packageRoot = fileURLToPath(new URL("../../..", import.meta.url));
 const projectRoot = process.cwd();
 const managerPath = join(packageRoot, "dist/scripts/runtime/manage_database.mjs");
@@ -94,8 +95,17 @@ const main = async () => {
         !flags.json &&
         process.stdin.isTTY &&
         process.stdout.isTTY;
-    const guided = command === "guide" || wantsAutomaticGuide;
-    const mutating = commandMutatesProject({ command, flags, guided });
+    const guided = !flags.help &&
+        !flags.version &&
+        (command === "guide" || wantsAutomaticGuide);
+    if (!flags.help &&
+        !flags.version &&
+        (guided || !["help", "version", "discover", "doctor"].includes(command))) {
+        await assertSupportedHostPlatform({ projectRoot });
+    }
+    const mutating = !flags.help &&
+        !flags.version &&
+        commandMutatesProject({ command, flags, guided });
     const operation = mutating
         ? await acquireProjectOperation({
             projectRoot,

package/dist/src/cli/runtime_commands.mjs

@@ -14,6 +14,7 @@ import { RehearsalError, normalizeRehearsalError, redactDiagnosticValue, } from
 import { assertInstalledPackageFingerprint } from "../shared/operation_guard.mjs";
 import { getOperationCancellationSignal, throwIfOperationCancelled, } from "../shared/cancellation.mjs";
 import { runOwnedProcess } from "../shared/owned_process.mjs";
+import { createCleanProcessEnvironment } from "../shared/process_environment.mjs";
 import { getOwnedOperationProgressId, trackOperationStage, } from "../shared/operation_progress.mjs";
 import { buildRuntimeManagerArguments } from "../targets/target.mjs";
 import { parseRuntimeStatusSnapshot, renderRuntimeStatusSnapshot, } from "../runtime/status.mjs";
@@ -55,23 +56,7 @@ const parseCommand = (source) => {
         throw new Error("Application proof command is empty.");
     return values;
 };
-const projectCommandEnvironment = (additional = {}) => ({
-    ...Object.fromEntries([
-        "CI",
-        "COLORTERM",
-        "FORCE_COLOR",
-        "HOME",
-        "LANG",
-        "LC_ALL",
-        "NO_COLOR",
-        "PATH",
-        "SHELL",
-        "TERM",
-        "TMPDIR",
-        "USER",
-    ].flatMap((key) => process.env[key] === undefined ? [] : [[key, process.env[key]]])),
-    ...additional,
-});
+const projectCommandEnvironment = (additional = {}) => createCleanProcessEnvironment({ overrides: additional });
 const RUNTIME_STARTUP_FAILURE_PATTERN = /container\b.*\b(?:is not ready|starting|unhealthy)|health(?:check)?\b.*\b(?:failed|starting|unhealthy)|out of memory|\boom\b|no space left|resource temporarily unavailable/iu;
 export const classifyManagerFailure = ({ action, output, inferredCategory, }) => {
     if (RUNTIME_STARTUP_FAILURE_PATTERN.test(output) ||

package/dist/src/cli/runtime_planning.mjs

@@ -1,6 +1,7 @@
 import { buildRehearsalPlan, runRehearsalDoctor } from "../runtime/plan.mjs";
 import { inspectRuntimeTopologyCandidates, loadRuntimeTopology, } from "../runtime/topology.mjs";
 import { redactDiagnosticValue } from "../shared/diagnostics.mjs";
+import { inspectHostPlatform } from "../shared/host_platform.mjs";
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 export const buildRuntimeStackPlan = async (planOptions) => {
     const topology = await loadRuntimeTopology(planOptions);
@@ -52,6 +53,11 @@ export const buildRuntimeStackPlan = async (planOptions) => {
     };
 };
 export const runRuntimeStackDoctor = async (planOptions) => {
+    const host = await inspectHostPlatform({
+        projectRoot: planOptions.projectRoot ?? process.cwd(),
+    });
+    if (!host.supported)
+        return runRehearsalDoctor(planOptions);
     let topology;
     try {
         topology = await loadRuntimeTopology(planOptions);

package/dist/src/project/install_scaffold.mjs

@@ -6,6 +6,7 @@ import { access, readFile, readdir, stat } from "node:fs/promises";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { applyRehearsalSetup, planRehearsalSetup } from "./setup.mjs";
 import { findRehearsalConfigPath, inspectDetectedProject, loadRehearsalConfig, } from "./configuration.mjs";
+import { inspectHostPlatform } from "../shared/host_platform.mjs";
 const PACKAGE_NAME = "@rehearsal-db/core";
 const DEPENDENCY_GROUPS = Object.freeze([
     "dependencies",
@@ -224,6 +225,12 @@ export const createInstalledRehearsalScaffold = async ({ packageRoot, environmen
     });
     if (resolution.status !== "resolved")
         return resolution;
+    const host = await inspectHostPlatform({
+        projectRoot: resolution.projectRoot,
+    });
+    if (!host.supported) {
+        return skip(`${host.detail} ${host.remediation}`.replace(/\.$/u, ""));
+    }
     const detected = await inspectDetectedProject({
         projectRoot: resolution.projectRoot,
     });

package/dist/src/project/project_discovery_metadata.mjs

@@ -7,6 +7,7 @@ import { lstat, readFile, readdir } from "node:fs/promises";
 import { basename, join, relative, resolve, sep } from "node:path";
 import { promisify } from "node:util";
 import { CONFIG_FILENAMES } from "./configuration_discovery.mjs";
+import { createCleanProcessEnvironment } from "../shared/process_environment.mjs";
 const MAX_METADATA_BYTES = 1024 * 1024;
 const execFileAsync = promisify(execFile);
 const inside = (root, path) => {
@@ -112,17 +113,14 @@ export const probeContainerEngineWithoutStarting = async () => {
         await execFileAsync("docker", ["info", "--format", "{{.ServerVersion}}"], {
             timeout: 2_000,
             maxBuffer: 64 * 1024,
-            env: Object.fromEntries([
-                "COLIMA_HOME",
-                "DOCKER_CONFIG",
-                "DOCKER_CONTEXT",
-                "DOCKER_HOST",
-                "HOME",
-                "PATH",
-                "USER",
-            ]
-                .map((key) => [key, process.env[key]])
-                .filter((entry) => Boolean(entry[1]))),
+            env: createCleanProcessEnvironment({
+                passthroughKeys: [
+                    "COLIMA_HOME",
+                    "DOCKER_CONFIG",
+                    "DOCKER_CONTEXT",
+                    "DOCKER_HOST",
+                ],
+            }),
         });
         return "running";
     }

package/dist/src/runtime/plan.mjs

@@ -21,6 +21,8 @@ import { readRehearsalServiceEnvironment } from "./service_environment.mjs";
 import { readBoundRuntimeSanitizationPolicy, validateRuntimeSanitizationPolicy, } from "../baseline/sanitization_policy.mjs";
 import { buildAuthenticationReview, buildBaselineScopeReview, } from "./project_review.mjs";
 import { readVerifiedBaselineShapeEvidence } from "../source/shape_files.mjs";
+import { inspectHostPlatform } from "../shared/host_platform.mjs";
+import { createCleanProcessEnvironment } from "../shared/process_environment.mjs";
 const errorMessage = (error) => error instanceof Error ? error.message : String(error);
 const hasErrorCode = (error, code) => typeof error === "object" &&
     error !== null &&
@@ -29,7 +31,7 @@ const hasErrorCode = (error, code) => typeof error === "object" &&
 const commandAvailable = (command, args = ["--version"]) => {
     const result = spawnSync(command, args, {
         encoding: "utf8",
-        env: Object.fromEntries(["HOME", "LANG", "LC_ALL", "PATH", "SHELL", "TMPDIR"].flatMap((key) => process.env[key] === undefined ? [] : [[key, process.env[key]]])),
+        env: createCleanProcessEnvironment(),
         stdio: ["ignore", "pipe", "pipe"],
     });
     return {
@@ -378,6 +380,23 @@ export const inspectRehearsalMigrations = async (options = {}) => {
     };
 };
 export const runRehearsalDoctor = async (options = {}) => {
+    const host = await inspectHostPlatform({
+        projectRoot: options.projectRoot ?? process.cwd(),
+    });
+    if (!host.supported) {
+        return {
+            state: "NOT READY",
+            checks: [
+                {
+                    id: "operating-system",
+                    label: "Operating-system support",
+                    status: "fail",
+                    detail: host.detail,
+                    remediation: host.remediation,
+                },
+            ],
+        };
+    }
     let loaded;
     try {
         loaded = await loadRehearsalConfig(options);
@@ -426,12 +445,9 @@ export const runRehearsalDoctor = async (options = {}) => {
             id: "operating-system",
             label: "Operating-system support",
             run: async () => {
-                if (!["darwin", "linux"].includes(process.platform)) {
-                    throw new Error(`${process.platform} is not supported by the version-1 contract.`);
-                }
-                return `${process.platform} is in the supported matrix`;
+                return host.detail;
             },
-            remediation: "Use macOS or Linux; WSL and native Windows require separate proof before support.",
+            remediation: host.remediation,
         },
         {
             id: "package-manager",
@@ -594,9 +610,7 @@ export const runRehearsalDoctor = async (options = {}) => {
                         ], {
                             cwd: projectRoot,
                             encoding: "utf8",
-                            env: Object.fromEntries(["HOME", "LANG", "LC_ALL", "PATH", "SHELL", "TMPDIR"].flatMap((key) => process.env[key] === undefined
-                                ? []
-                                : [[key, process.env[key]]])),
+                            env: createCleanProcessEnvironment(),
                             stdio: ["ignore", "pipe", "pipe"],
                         });
                         if (status.status !== 0 ||
@@ -614,12 +628,9 @@ export const runRehearsalDoctor = async (options = {}) => {
                     const status = spawnSync("supabase", ["status", "-o", "env", "--workdir", paths.runtimeWorkdir], {
                         cwd: projectRoot,
                         encoding: "utf8",
-                        env: {
-                            ...Object.fromEntries(["HOME", "LANG", "LC_ALL", "PATH", "SHELL", "TMPDIR"].flatMap((key) => process.env[key] === undefined
-                                ? []
-                                : [[key, process.env[key]]])),
-                            ...serviceEnvironment,
-                        },
+                        env: createCleanProcessEnvironment({
+                            overrides: serviceEnvironment,
+                        }),
                         stdio: ["ignore", "pipe", "pipe"],
                     });
                     if (status.status !== 0 ||

package/dist/src/shared/host_platform.d.mts

@@ -0,0 +1,16 @@
+export declare const NATIVE_WINDOWS_REMEDIATION = "Use WSL2, not a native Windows terminal: run wsl --install -d Ubuntu in PowerShell and confirm version 2 with wsl --list --verbose (upgrade with wsl --set-version Ubuntu 2 if needed). Enable Docker Desktop Settings > Resources > WSL integration for that distribution. Keep the project in its Linux home filesystem (for example ~/projects, not /mnt/c), install a supported Linux Node.js version and project tools there, open it with VS Code Remote - WSL, then rerun rehearsal doctor inside WSL2.";
+export interface HostPlatformInspection {
+    readonly kind: "macos" | "linux" | "wsl2" | "wsl-unverified" | "windows" | "other";
+    readonly supported: boolean;
+    readonly detail: string;
+    readonly remediation: string;
+}
+export interface HostPlatformOptions {
+    readonly projectRoot?: string;
+    readonly platform?: NodeJS.Platform;
+    readonly kernelRelease?: string;
+    readonly readKernelRelease?: () => Promise<string>;
+    readonly inspectFilesystem?: (path: string) => Promise<number>;
+}
+export declare const inspectHostPlatform: ({ projectRoot, platform, kernelRelease, readKernelRelease, inspectFilesystem, }?: HostPlatformOptions) => Promise<HostPlatformInspection>;
+export declare const assertSupportedHostPlatform: (options?: HostPlatformOptions) => Promise<void>;

package/dist/src/shared/host_platform.mjs

@@ -0,0 +1,109 @@
+/** Read-only host capability checks; never substitute environment hints for proof. */
+import { open, statfs } from "node:fs/promises";
+import { release } from "node:os";
+import { RehearsalError } from "./diagnostics.mjs";
+export const NATIVE_WINDOWS_REMEDIATION = "Use WSL2, not a native Windows terminal: run wsl --install -d Ubuntu in PowerShell and confirm version 2 with wsl --list --verbose (upgrade with wsl --set-version Ubuntu 2 if needed). Enable Docker Desktop Settings > Resources > WSL integration for that distribution. Keep the project in its Linux home filesystem (for example ~/projects, not /mnt/c), install a supported Linux Node.js version and project tools there, open it with VS Code Remote - WSL, then rerun rehearsal doctor inside WSL2.";
+const readProcKernelRelease = async () => {
+    const file = await open("/proc/sys/kernel/osrelease", "r");
+    try {
+        const buffer = Buffer.alloc(512);
+        const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
+        return buffer.subarray(0, bytesRead).toString("utf8");
+    }
+    finally {
+        await file.close();
+    }
+};
+// WSL's Windows drive mounts do not provide the private modes and atomic symlink
+// contract used by baselines. Accept proven Linux filesystem types, not paths.
+const WSL_POSIX_FILESYSTEM_TYPES = new Set([
+    0xef53, // ext2/ext3/ext4 (WSL2 distribution filesystem)
+    0x58465342, // XFS
+    0x9123683e, // Btrfs
+]);
+export const inspectHostPlatform = async ({ projectRoot = process.cwd(), platform = process.platform, kernelRelease = release(), readKernelRelease = readProcKernelRelease, inspectFilesystem = async (path) => (await statfs(path)).type, } = {}) => {
+    if (platform === "darwin") {
+        return {
+            kind: "macos",
+            supported: true,
+            detail: "macOS is in the supported host matrix; project readiness checks still apply.",
+            remediation: "Resolve the remaining project readiness checks on macOS.",
+        };
+    }
+    if (platform === "win32") {
+        return {
+            kind: "windows",
+            supported: false,
+            detail: "Native Windows runtime and preparation operations are unsupported: POSIX private-file, process-group, and atomic baseline-pointer guarantees have not been established.",
+            remediation: NATIVE_WINDOWS_REMEDIATION,
+        };
+    }
+    if (platform !== "linux") {
+        return {
+            kind: "other",
+            supported: false,
+            detail: "This operating system is outside the verified macOS/Linux runtime contract.",
+            remediation: "Use a supported macOS or Linux environment. Windows users should use WSL2 with the project on its Linux home filesystem and Docker Desktop WSL integration.",
+        };
+    }
+    let procRelease = "";
+    try {
+        procRelease = (await readKernelRelease()).slice(0, 512);
+    }
+    catch {
+        // os.release() is independent kernel evidence when procfs is unavailable.
+    }
+    const evidence = `${kernelRelease.slice(0, 512)}\n${procRelease}`;
+    if (!/microsoft|\bwsl2?\b/iu.test(evidence)) {
+        return {
+            kind: "linux",
+            supported: true,
+            detail: "Linux is in the supported host matrix; project readiness checks still apply.",
+            remediation: "Resolve the remaining project readiness checks on Linux.",
+        };
+    }
+    if (!/microsoft-standard|\bwsl2\b/iu.test(evidence)) {
+        return {
+            kind: "wsl-unverified",
+            supported: false,
+            detail: "A WSL kernel was detected, but WSL2 kernel capabilities were not proven. WSL1 is unsupported.",
+            remediation: NATIVE_WINDOWS_REMEDIATION,
+        };
+    }
+    let filesystemType = null;
+    try {
+        filesystemType = await inspectFilesystem(projectRoot);
+    }
+    catch {
+        // Unknown filesystem evidence must not be interpreted as POSIX capability.
+    }
+    if (filesystemType === null ||
+        !WSL_POSIX_FILESYSTEM_TYPES.has(filesystemType)) {
+        return {
+            kind: "wsl2",
+            supported: false,
+            detail: "WSL2 was detected, but this project is not on a proven Linux filesystem. Windows drive mounts and unknown filesystem types are unsupported for private baseline data.",
+            remediation: NATIVE_WINDOWS_REMEDIATION,
+        };
+    }
+    return {
+        kind: "wsl2",
+        supported: true,
+        detail: "WSL2 kernel and a Linux project filesystem were detected. Run in VS Code Remote - WSL with Linux tools and Docker Desktop WSL integration; the remaining readiness and private-file checks still apply.",
+        remediation: NATIVE_WINDOWS_REMEDIATION,
+    };
+};
+export const assertSupportedHostPlatform = async (options = {}) => {
+    const inspection = await inspectHostPlatform(options);
+    if (inspection.supported)
+        return;
+    throw new RehearsalError({
+        category: "unsafe_environment",
+        code: "HOST_PLATFORM_UNSUPPORTED",
+        message: inspection.detail,
+        expected: "A supported macOS/Linux runtime with its existing safety guarantees.",
+        actual: inspection.kind,
+        refused: "No project configuration, child process, or runtime operation was started.",
+        suggestions: [inspection.remediation],
+    });
+};

package/dist/src/shared/process_environment.d.mts

@@ -8,8 +8,9 @@ export interface CleanProcessEnvironmentOptions {
     inheritedEnvironment?: ProcessEnvironment;
     overrides?: ProcessEnvironment;
     passthroughKeys?: readonly string[];
+    platform?: NodeJS.Platform;
 }
 export declare const isLoopbackUrl: (value: string) => boolean;
 export declare const assertLoopbackUrl: (label: string, value: string) => void;
 export declare const pickEnvironmentVariables: (source: ProcessEnvironment, keys: readonly string[]) => Record<string, string>;
-export declare const createCleanProcessEnvironment: ({ inheritedEnvironment, overrides, passthroughKeys, }?: CleanProcessEnvironmentOptions) => Record<string, string>;
+export declare const createCleanProcessEnvironment: ({ inheritedEnvironment, overrides, passthroughKeys, platform, }?: CleanProcessEnvironmentOptions) => Record<string, string>;

package/dist/src/shared/process_environment.mjs

@@ -21,6 +21,17 @@ const SAFE_SYSTEM_ENVIRONMENT_KEYS = Object.freeze([
     "TEMP",
     "USER",
 ]);
+// Windows resolves environment names case-insensitively. Keep only infrastructure
+// needed to locate executables and user configuration, never ambient credentials.
+const SAFE_WINDOWS_ENVIRONMENT_KEYS = Object.freeze([
+    "SystemRoot",
+    "WINDIR",
+    "ComSpec",
+    "PATHEXT",
+    "USERPROFILE",
+    "APPDATA",
+    "LOCALAPPDATA",
+]);
 const LOOPBACK_HOSTNAMES = new Set(["127.0.0.1", "::1", "[::1]", "localhost"]);
 export const isLoopbackUrl = (value) => {
     try {
@@ -41,10 +52,41 @@ export const pickEnvironmentVariables = (source, keys) => Object.fromEntries(key
     const value = source[key];
     return value === undefined ? [] : [[key, value]];
 }));
-export const createCleanProcessEnvironment = ({ inheritedEnvironment = process.env, overrides = {}, passthroughKeys = [], } = {}) => ({
-    ...pickEnvironmentVariables(inheritedEnvironment, [
+const pickWindowsEnvironmentVariables = (source, keys) => {
+    const selected = {};
+    const seen = new Set();
+    for (const key of keys) {
+        const normalized = key.toUpperCase();
+        if (seen.has(normalized))
+            continue;
+        seen.add(normalized);
+        const sourceKey = source[key] !== undefined
+            ? key
+            : Object.keys(source).find((candidate) => candidate.toUpperCase() === normalized &&
+                source[candidate] !== undefined);
+        if (sourceKey !== undefined)
+            selected[key] = source[sourceKey];
+    }
+    return selected;
+};
+export const createCleanProcessEnvironment = ({ inheritedEnvironment = process.env, overrides = {}, passthroughKeys = [], platform = process.platform, } = {}) => {
+    const keys = [
         ...SAFE_SYSTEM_ENVIRONMENT_KEYS,
+        ...(platform === "win32" ? SAFE_WINDOWS_ENVIRONMENT_KEYS : []),
         ...passthroughKeys,
-    ]),
-    ...pickEnvironmentVariables(overrides, Object.keys(overrides)),
-});
+    ];
+    if (platform !== "win32") {
+        return {
+            ...pickEnvironmentVariables(inheritedEnvironment, keys),
+            ...pickEnvironmentVariables(overrides, Object.keys(overrides)),
+        };
+    }
+    const environment = pickWindowsEnvironmentVariables(inheritedEnvironment, keys);
+    for (const [key, value] of Object.entries(overrides)) {
+        if (value === undefined)
+            continue;
+        const existing = Object.keys(environment).find((candidate) => candidate.toUpperCase() === key.toUpperCase());
+        environment[existing ?? key] = value;
+    }
+    return environment;
+};

package/docs/getting-started.md

@@ -5,6 +5,54 @@ your computer. Normal setup and rehearsal commands never connect to a hosted dat
 
 Want to experiment first? Use the [safe hands-on tutorial](tutorial.md).
 
+## OS-specific setup files (optional)
+
+Separate setup folders are available for
+[Windows / WSL 2](https://github.com/Ddupasquier/rehearsal-db/tree/main/installers/windows),
+[macOS](https://github.com/Ddupasquier/rehearsal-db/tree/main/installers/macos) and
+[Linux](https://github.com/Ddupasquier/rehearsal-db/tree/main/installers/linux).
+They are readable helpers, not native executables or bundled Node/Docker installers.
+Existing Node.js 24 or 26 is required. The default only checks an existing project;
+installation needs an explicit option and does not start a database. Review the
+[shared behavior and release availability](https://github.com/Ddupasquier/rehearsal-db/blob/main/installers/README.md)
+before choosing an install option. An exact core 1.0.1 install requires that version to
+be published; a checked-in helper is not proof of publication.
+
+### Windows: use a WSL 2 Linux workspace
+
+The Windows compatibility route is Linux execution inside **WSL 2**, not a native
+PowerShell/Command Prompt database runtime. Core 1.0.1 and extension 0.1.21 make that
+boundary explicit; native Windows version/help/discovery do not authorize runtime work.
+
+1. Follow Microsoft's [WSL installation guide](https://learn.microsoft.com/en-us/windows/wsl/install)
+   to prepare a WSL 2 Linux distribution, such as Ubuntu 24.04. Do not use WSL 1.
+2. Clone or open the project inside the distribution's Linux home directory, such as
+   `/home/your-name/projects/app`. Do not keep the runtime project under `/mnt/c`, a
+   Windows share or a Windows-mounted drive. Rehearsal does not relocate your files.
+3. Install a supported **Linux** Node/npm and a Docker-compatible Linux engine in that
+   environment. Docker Engine in WSL or an already configured Docker Desktop WSL
+   integration are user-controlled setup choices; Rehearsal does not install or license
+   Docker Desktop for you. In the Linux terminal, check:
+
+   ```bash
+   node -p "process.platform"
+   pwd
+   docker info --format '{{.OSType}}'
+   ```
+
+   Both platform results must be `linux`, and `pwd` must be in the Linux filesystem.
+
+4. For editor use, install Microsoft's **WSL** extension, then run `code .` from that
+   Linux project directory. Confirm the VS Code window says **WSL** in its remote
+   indicator, and install Rehearsal into **WSL**, not only the Windows-side extension host.
+5. Continue below from that Linux terminal. Keep the existing baseline, approval and
+   local-only checks; do not substitute a hosted database to make setup pass.
+
+WSL is a compatibility preview. A real WSL PostgreSQL fixture and a native Remote-WSL
+editor walkthrough are different evidence; do not infer the latter from Linux unit
+tests. Supabase/Auth/Storage in WSL and other remote hosts remain unclaimed until their
+own checks pass. See the [complete platform boundary](https://github.com/Ddupasquier/rehearsal-db/blob/main/COMPATIBILITY.md#operating-systems-and-execution-location).
+
 ## 1. Check the required tools
 
 You need Node.js 22, 24, or 26, npm, and a running Docker-compatible engine. Node.js 24

package/docs/index.md

@@ -12,6 +12,11 @@ Rehearsal catches those problems before deployment. It restores a reviewed, sani
 baseline into a disposable local PostgreSQL or Supabase environment, applies only the
 exact migrations you approve, and runs your application's own proof.
 
+The [CLI is free and MIT-licensed](https://www.npmjs.com/package/@rehearsal-db/core).
+Prefer clicks to commands? [Install the free VS Code Starter preview](vscode.md).
+All features included in its Starter-licensed releases are free indefinitely, with no
+account, payment card, or trial period.
+
 | Empty-database tests miss…                        | Rehearsal exercises…                                      |
 | ------------------------------------------------- | --------------------------------------------------------- |
 | old rows and edge cases                           | a reviewed, production-shaped baseline                    |
@@ -23,15 +28,16 @@ exact migrations you approve, and runs your application's own proof.
 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) |
-| Reduce Docker and Supabase resource use | [Container runtime lifecycle](runtime-lifecycle.md)               |
-| Add editor and compiler type checks     | [TypeScript](typescript.md)                                       |
-| Fix something that did not work         | [Troubleshooting](troubleshooting.md)                             |
+| I want to…                               | Go here                                                           |
+| ---------------------------------------- | ----------------------------------------------------------------- |
+| Set up my own project                    | [Getting started](getting-started.md)                             |
+| Use the free visual workbench in VS Code | [Install VS Code Starter](vscode.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) |
+| Reduce Docker and Supabase resource use  | [Container runtime lifecycle](runtime-lifecycle.md)               |
+| Add editor and compiler type checks      | [TypeScript](typescript.md)                                       |
+| Fix something that did not work          | [Troubleshooting](troubleshooting.md)                             |
 
 ## The short version
 

package/docs/releasing.md

@@ -95,23 +95,27 @@ than seven days or in the future. Public fields and timestamps must still match
 bypass metadata is hidden; an explicitly malformed or nonempty bypass list always
 refuses publication.
 
-The prepare job prints an exact approval comment in its summary. Independently check
-the live no-bypass settings and accepted artifact checksum, then paste the comment into
-**Review deployments → npm** and approve manually. Before publishing or repairing
-tags, the workflow reads GitHub's actual approval history and requires the configured
-owner's authenticated review for that npm environment. The comment binds the operation,
-run ID, run attempt, source commit, artifact SHA-256 and settings-record SHA-256.
-GitHub may store the form's line breaks as CRLF instead of LF. The checker treats
-those two encodings as equivalent; it does not trim whitespace or change any field.
-An approval copied from another artifact, run or attempt is refused. Rerun the whole
-workflow after failure so preparation prints a new attempt-bound comment; do not reuse
-an earlier comment when rerunning only the mutation job.
-
-The record alone is never authorization. This mechanism relies on the owner's fresh
-settings review and GitHub's reported timestamps; timestamps are not cryptographic
-proof of every hidden setting change. No settings check eliminates a subsequent
-administrator change or check-to-use race. Keep the npm environment's no-bypass human
-gate enforced. See [GitHub's ruleset metadata boundary](https://docs.github.com/en/rest/repos/rules#get-a-repository-ruleset)
+The prepare job displays the exact package version, SHA-256, source commit and run
+in its summary. Review the candidate and passed checks, then choose **Review
+deployments → npm → Approve and deploy**. That ordinary GitHub approval is the
+publication authorization: no separate chat approval, secret phrase or pasted block
+is required. Comments are optional.
+
+GitHub's enforced, no-bypass `npm` environment admits the publishing job only after
+its protection rules pass. The workflow also reads this run's actual review history
+to corroborate the configured human owner's approval for the exact npm environment.
+That history does not identify an approval's run attempt or verify artifact bytes;
+the workflow independently checks the prepared tarball's hashes before publication,
+and freshly downloads/checks registry bytes before tag repair. Reruns keep the same
+source/ref and remain subject to GitHub's environment controls; old review text is
+never presented as proof of new bytes or a fresh attempt.
+
+The unsigned settings record remains a bounded drift check, not authorization or
+cryptographic proof of current hidden bypass settings. Refresh its owner observation
+when stale or changed; never advance its timestamp without reading the settings.
+No settings check eliminates a later administrator change or check-to-use race.
+See [GitHub's deployment review](https://docs.github.com/en/actions/how-tos/deploy/configure-and-manage-deployments/review-deployments),
+[ruleset metadata boundary](https://docs.github.com/en/rest/repos/rules#get-a-repository-ruleset)
 and [workflow approval history](https://docs.github.com/en/rest/actions/workflow-runs#get-the-review-history-for-a-workflow-run).
 
 Keep customer evidence, credentials, runtime data and the internal tracker out of public
@@ -137,11 +141,12 @@ release-source migration.
 5. Change `private` to `false` only in the reviewed release change.
 6. Record the exact tarball filename, SHA-1, SHA-256, allowlisted files, unpacked size,
    executable, declared runtime dependency inventory, and dependency audit result.
-7. Obtain explicit publication authorization for that exact version and artifact.
-8. Merge the approved release commit through protected `main` and create the exact
+7. Review the release change and its exact artifact evidence.
+8. Merge the reviewed release commit through protected `main` and create the exact
    `v<package-version>` tag and GitHub release.
-9. Review and approve the protected `npm` deployment only after its prepare job matches
-   the approved version and checksum, using its exact approval comment.
+9. Authorize publication once, in the protected `npm` deployment review, after its
+   prepare job matches the tested version and checksum. No comment or chat approval
+   is required.
 10. Verify public visibility, ownership, provenance, registry SHA-1, README rendering,
     exact-version clean installation, CLI execution, signatures, and the unrelated
     installed Docker fixture. Allow up to six minutes for a first package to propagate
@@ -199,6 +204,5 @@ package or select a different version. The `npm` environment must supply the ver
 human approval gate; a workflow reference to that environment is not sufficient.
 
 Creating the repository, passing CI, extracting the engine, merging a release branch,
-or creating a tag does not authorize npm publication. Publication requires explicit
-authorization for the exact packed artifact, and the protected GitHub environment
-supplies the final human gate.
+or creating a tag does not authorize npm publication. The protected GitHub deployment
+review supplies the single human authorization for the exact displayed artifact.

package/docs/roadmap.md

@@ -1,8 +1,13 @@
 # Next steps
 
-Rehearsal supports guided Supabase and ordinary PostgreSQL migration rehearsals. The
-current development track removes the need for consumer-owned Rehearsal engines while
-keeping application meaning and privacy decisions project-owned.
+Rehearsal core **1.0.0 is available on
+[npm](https://www.npmjs.com/package/@rehearsal-db/core)** for guided Supabase and
+ordinary PostgreSQL migration rehearsals. The [free VS Code Starter preview](vscode.md)
+adds a visual workbench. Neither requires a purchase or account.
+
+The standalone workflow keeps the rehearsal engine in the package while application
+meaning and privacy decisions remain project-owned. The sequence below explains its
+dependencies, not a list of features withheld from the published release.
 
 ## Standalone workflow
 

package/docs/stability.md

@@ -1,7 +1,10 @@
 # Stability and the first stable release
 
-Rehearsal leaves beta when the workflow it already promises is dependable. Stable
-`1.0.0` does not require every planned database, desktop interface, or paid feature.
+Rehearsal core **1.0.0 is published** on
+[npm](https://www.npmjs.com/package/@rehearsal-db/core). This page defines its
+compatibility promise and the verification policy for releases; it is not an
+unfinished launch checklist. Stable core does not require every planned database,
+editor interface, or paid feature.
 
 ## What becomes a compatibility promise
 
@@ -63,8 +66,9 @@ ready. The sequence below is policy, not a claim that its checks have passed.
    do not relabel old or unavailable manual checks as new results. No minimum number
    of calendar days replaces these checks.
 6. Publish `1.0.0` only when no blocking issue remains and the exact tarball has passed
-   the required release checks, consumer acceptance, exact-artifact authorization and
-   protected human publication approval.
+   the required release checks and consumer acceptance. The protected GitHub npm
+   review is the single human authorization for its displayed exact version and
+   checksum; no separate chat approval or pasted phrase is required.
 7. Independently verify registry bytes, provenance, signatures and channels, then
    confirm the published package in the real consumer. Promotion is complete only
    when the published artifact matches the tested tarball and these checks pass.

package/docs/vscode.md

@@ -4,6 +4,22 @@ The Rehearsal extension turns the local CLI into a project-aware database-change
 workbench. It is for developers who want the safety of exact migration plans and disposable
 local runtimes without memorizing every command.
 
+This guide targets **Free Starter 0.1.21**, named **Rehearsal DB** on
+[VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=rehearsal-db.rehearsal-db),
+with a [reviewed GitHub VSIX](https://github.com/Ddupasquier/rehearsal-vscode/releases/tag/v0.1.21)
+for direct installation. The canonical extension ID is **`rehearsal-db.rehearsal-db`**,
+published by **`rehearsal-db`**. The workbench and commands retain the **Rehearsal** brand.
+All included features are free indefinitely for personal or commercial development.
+No account, payment card, purchase, trial period, or license activation is required.
+The CLI is separately available on [npm](https://www.npmjs.com/package/@rehearsal-db/core)
+under the MIT license. There is no paid CLI tier.
+Confirm the target version appears in its official channel before installing. A guide
+or checked-in version does not mean that publication has completed.
+
+Already using the GitHub preview through 0.1.18? Follow the
+[one-time migration steps](#move-from-a-preview-through-0118) before installing the new
+identity. This is not an automatic rename or uninstall.
+
 ## What you can do
 
 - See what Rehearsal detected, what it suggests, and what still needs your decision.
@@ -14,6 +30,11 @@ local runtimes without memorizing every command.
 - Export a privacy-safe verification report and review bounded local activity.
 - Keep the sidebar and open workbench current when another terminal changes the project's
   Rehearsal package, lockfile, manifest, or known configuration.
+- Browse resource inventories in independent pages of 5, 10 or 25 cards, rather than
+  one unbounded list.
+- Read a configuration diff before choosing **Apply changes** or **Cancel**, then
+  return to the project from the saved result.
+- Choose independent, initially off automatic-update options for the extension and CLI.
 
 The extension does not become a second database engine. Rehearsal core still owns data
 boundaries, baselines, migration digests, runtime isolation, locks, rollback, and cleanup.
@@ -22,6 +43,11 @@ boundaries, baselines, migration digests, runtime isolation, locks, rollback, an
 
 Use desktop VS Code 1.101 or newer on macOS or Linux and a supported Node.js release
 (22, 24, or 26). You do not need the extension source repository or Test Lab.
+For a Windows desktop, use the [WSL 2 Linux-workspace setup](getting-started.md#windows-use-a-wsl-2-linux-workspace).
+With editor 0.1.21, native Windows inspection and foreground actions refuse before launching a child
+process and directs you to Remote-WSL. Install the extension into the Linux extension
+host and keep the project on its Linux filesystem. WSL compatibility remains a preview;
+real WSL core fixtures do not certify a native Remote-WSL editor walkthrough.
 
 1. Open your application's folder in VS Code—the one containing `package.json` and
    your migrations. Install Rehearsal there if it is missing:
@@ -30,31 +56,154 @@ Use desktop VS Code 1.101 or newer on macOS or Linux and a supported Node.js rel
    npm install --save-dev @rehearsal-db/core
    ```
 
-2. Open the [reviewed GitHub prereleases](https://github.com/Ddupasquier/rehearsal-vscode/releases).
-   Download the chosen release's `.vsix` and `SHA256SUMS`. Compare the file's SHA-256
-   with that release's checksum; do not substitute an unreviewed rebuild.
-3. In VS Code, open **Extensions → … → Install from VSIX…** and choose that file.
-   Reload the extension host if VS Code asks.
-4. Review Workspace Trust, then open the Command Palette and choose
+2. Open **Extensions** and search **`@id:rehearsal-db.rehearsal-db`**, or open the
+   [official Rehearsal DB listing](https://marketplace.visualstudio.com/items?itemName=rehearsal-db.rehearsal-db).
+   Confirm publisher **`rehearsal-db`** and the full extension ID, then choose **Install**.
+   The similar-looking legacy ID `rehearsal-db.rehearsal` is not the canonical package.
+   If you prefer a direct download, use the verified GitHub VSIX instructions below.
+3. Review Workspace Trust, then open the Command Palette and choose
    **Rehearsal: Open Dashboard**. The Rehearsal sidebar also has a dashboard button.
-5. Follow **Next best step**. Review the detected project and active configuration;
+4. Follow **Next best step**. Review the detected project and active configuration;
    setup, source access, migration execution and cleanup keep their own confirmations.
 
-The extension needs `@rehearsal-db/core@0.1.0-rc.4` or newer. A project that is not ready
-should show setup guidance, not require you to build the extension. Use
+The release pairing described here is core **1.0.1** with Starter **0.1.21**.
+Install it once both versions appear in their official release channels.
+The extension's minimum core is `0.1.0-rc.4`. A project that is not ready should show
+setup guidance, not require you to build the extension. Opening the dashboard does not
+start a database or run a migration. Use
 [Getting started](getting-started.md) for the CLI and safe baseline inputs.
 
-## Updates
-
-GitHub VSIX installations do not auto-update. Download and verify the next reviewed
-release, then use **Install from VSIX…** again. Keep the previous reviewed file for
-rollback. See the extension's [installation guide](https://github.com/Ddupasquier/rehearsal-vscode#install-and-open-your-project)
-for checksum commands and the optional command-line installer.
-
-Updating the project's core package is separate: its manifest, lockfile and installed
-metadata trigger a narrow read-only refresh automatically. You do not reload the VS Code
-window after an ordinary core-package update. Replacing the VSIX may require VS Code's
-one-time extension-host reload so the new extension code becomes active.
+Native Windows inspection refusal is not database-runtime support. Browser-based
+VS Code, Codespaces, SSH and Dev Containers have no end-to-end support claim.
+Native Windows means the Windows Node/extension host, not a Windows desktop
+connected to WSL. iOS/iPadOS, Android, BSD and unlisted systems are not
+supported by this desktop/local-runtime release. Consult the
+[platform matrix](https://github.com/Ddupasquier/rehearsal-db/blob/main/COMPATIBILITY.md#operating-systems-and-execution-location) for the
+distinction between desktop OS, extension host, architecture and actual database proof.
+
+### Direct GitHub installation
+
+The verified GitHub VSIX is an alternative to Marketplace. Open the
+[Starter 0.1.21 release](https://github.com/Ddupasquier/rehearsal-vscode/releases/tag/v0.1.21).
+Under **Assets**, download `rehearsal-db-0.1.21.vsix` and `SHA256SUMS`. In a terminal,
+run `shasum -a 256 /path/to/rehearsal-db-0.1.21.vsix` on macOS or
+`sha256sum /path/to/rehearsal-db-0.1.21.vsix` on Linux. Compare the result with that
+release's `SHA256SUMS`; stop if they differ. Do not substitute a local rebuild.
+Then open **Extensions → … → Install from VSIX…** and choose the verified file.
+Save your work and reload only if VS Code asks.
+
+### Move from a preview through 0.1.18
+
+Earlier GitHub previews use `rehearsal-db.rehearsal`, a separate VS Code identity.
+Their released 0.1.18 bytes, tag and checksum remain available and unchanged. Its updater
+looks for `rehearsal-<version>.vsix`, so it ignores the canonical
+`rehearsal-db-<version>.vsix` family instead of silently switching identities.
+
+1. Finish Rehearsal commands in all open project windows. If a sandbox app is open,
+   press **Ctrl+C** once in its owning terminal and wait for its normal shell prompt
+   and configured lifecycle result. Save your work.
+2. Explicitly uninstall the legacy extension: in **Extensions**, search
+   **`@id:rehearsal-db.rehearsal`**, then use its gear menu → **Uninstall**.
+3. Save remaining files and run **Developer: Reload Window**. Ensure the old extension
+   is no longer installed in each profile where you will use the canonical version.
+4. Install **Rehearsal DB**, ID **`rehearsal-db.rehearsal-db`**, using Marketplace or the
+   verified canonical VSIX above. Reload if asked, reopen the dashboard and review your
+   update preferences.
+
+The canonical extension refuses activation whenever VS Code still reports the legacy ID.
+Not currently active is not proof that an installed extension is disabled; uninstalling
+and reloading is the supported route. The extension does not automatically uninstall,
+disable or rename your existing installation, interrupt a command or force a reload.
+
+This identity change does not reset or modify databases, Storage, project configuration,
+keys or baselines. Private per-extension view state, activity history and metadata-check
+consent are not copied to the new identity; re-select views and review consent there.
+Shared VS Code user settings, including `rehearsal.automaticUpdates`, retain your existing
+values. Review or disable those flags before migration if desired. Do not run database
+cleanup or **Reset Saved Editor State** as a migration step.
+
+## Everyday editor workflow
+
+Use **Overview** for the next safe step, **Migrations** to review the complete ordered
+candidate set, and **Environments** for local resource inventory. Filters and sorting
+apply to the full inventory before pagination. Each list has its own **Previous/Next**
+controls and **5/10/25** page size. Paging preserves drafts and selections; bulk image
+selection selects safe candidates on the current page only. Off-page selections remain
+counted and can be cleared before the exact cleanup review. Display filters never narrow
+database cleanup ownership or the required migration set.
+
+For configuration, change only the values you intend to change, then choose
+**Review exact configuration diff** or **Review name & protection**. The review tab
+keeps the full diff readable. **Cancel** makes no changes; **Apply changes** saves the
+reviewed change. Wait for **Saved**, then choose **Return to project**. Concurrent edits
+refuse safely instead of overwriting someone else's work; a saved confirmation is tied
+to the exact bytes read back from disk, not merely a completed write request.
+
+Commands reuse the same Rehearsal terminal for a project only after its previous command
+has a confirmed exit and its directory still matches. A running sandbox or manually
+entered foreground command is never interrupted to make room for another action. If
+shell integration or completion evidence is unavailable, finish the command and close
+that terminal before retrying. An idle database lock is not proof that a terminal is free.
+
+**Open sandbox** is a persistent hands-on session, not a task that should finish while
+you browse. Overview distinguishes **Opening sandbox**, **Sandbox running** and
+**Closing sandbox** from core phase evidence. Missing evidence says **Sandbox session
+open**, not ready. Project inspection waits for that session; the app itself is not
+paused. Use the local address shown by the owning terminal. **Open application** opens
+that address without running another CLI command. Press **Ctrl+C** once in the owning
+terminal when done, then wait for its shell prompt and the configured lifecycle result.
+
+## Optional automatic updates
+
+Open **Rehearsal: Check for Updates** from the Command Palette, or use the dashboard's
+**Check for updates** action. The prompt has two independent, initially unchecked choices:
+
+- **Automatically keep the Rehearsal extension up to date**
+- **Automatically keep Rehearsal CLI dependencies up to date**
+
+Check the options you want, then choose **Save preferences**. Checking a box alone does
+not save consent: **Later**, **Skip versions**, or closing the tab do not opt you in.
+These choices are stored only in machine-scoped VS Code user settings, not your
+repository or Settings Sync. A project cannot authorize automatic installation. You can
+also edit the user setting directly:
+
+```json
+"rehearsal.automaticUpdates": { "extension": true, "cli": false }
+```
+
+Extension updates download only the official GitHub release, verify the checksum,
+package identity and engine compatibility, and hand the local VSIX to VS Code's
+installer. Rehearsal never forces a window reload; VS Code may ask you to reload when
+you are ready to activate installed code. Keep the previous reviewed VSIX for rollback.
+Canonical automatic updates require `rehearsal-db-<version>.vsix` and embedded identity
+`rehearsal-db.rehearsal-db`; they do not automatically import or replace a legacy package.
+
+CLI updates require the separate CLI opt-in. They update compatible registry-backed npm
+dependencies in trusted, idle projects, preserve the dependency group, pin the exact
+checked version and update the lockfile with install scripts disabled. Busy or
+unknown-completion terminals, dirty dependency files, another window's update, offline
+services and unverifiable artifacts defer the update rather than guessing. Breaking
+upgrades, unsupported package managers and local/candidate provenance remain manual.
+No migration, database lifecycle action or forced editor reload is requested.
+
+Enabled automatic options check at project opening and daily while the editor stays
+open; there is no separate background daemon. npm/GitHub receive ordinary connection
+information and requested public releases, not project files, database data, credentials
+or installed-version reports. Metadata-only advisory checks keep their separate consent.
+
+Turn either option off to revoke its future automatic work. **Rehearsal: Configure
+Update Checks → Disable updates** turns both automatic options off on this computer and
+stops this project's release checks. Existing installations are not rolled back. An
+interrupted package-manager update with unknown completion requires the support recovery
+route; do not delete its coordination lock while a package manager may still be running.
+
+Manual updating stays available: download and verify the next reviewed VSIX, then repeat
+**Install from VSIX…**. See the release's
+[installation guide](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.21/README.md#install-and-open-your-project).
+An ordinary core-package update is detected from its manifest, lockfile and installed
+metadata without reloading VS Code. The header shows loaded extension and core versions
+separately; installed → newest appears only after a successful release check. Unknown or
+offline availability is not proof that you are up to date.
 
 ## Privacy boundary
 
@@ -63,28 +212,37 @@ database access, or account. It does not read environment files, credentials, pr
 baseline contents, or project source. User-approved package operations and external links
 may use their own services.
 
-## Licensing and planned editions
-
-The approved direction is a complete free MIT CLI, a useful free VS Code Starter, and
-optional paid Pro editor workflows. The [extension's edition guide](https://github.com/Ddupasquier/rehearsal-vscode/blob/main/docs/commercial-readiness.md)
-owns that planned split. Database and safety capabilities stay in the free CLI.
-
-The split is not implemented yet: current preview artifacts retain their bundled 14-day
-evaluation and per-user license, without a technical trial countdown or feature paywall.
-GitHub VSIX installations do not auto-update, so each reviewed delivery includes its exact
-version, compatible core range, checksum, privacy statement, license, and support policy.
-
-Technical GitHub prereleases are already public; they are not a Marketplace listing or
-an announcement of paid availability. A development candidate is not a released artifact
-merely because it has the same version number. Read the release's license, privacy and
-support documents before evaluation.
-
-Starter/Pro license terms and Marketplace distribution still need approval. Paid Pro
-availability also needs reviewed seller identity, checkout/refund arrangements and support
-ownership. Do not send payment based on an unofficial download or message. Native Windows,
-browser-based VS Code, Codespaces, SSH and Dev Containers are not yet claimed as supported.
+## License, support and future Pro
+
+Starter 0.1.21 carries the same
+[free Starter license](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.21/LICENSE).
+Its current review, configuration, comparison and reporting tools are included; they
+are not a timed evaluation or a paid feature gate. Free use does not mean the extension
+is MIT-licensed: its bundled terms govern copying and redistribution. Core remains MIT.
+
+Future optional Pro editor workflows must be separately identified. They cannot
+retroactively remove Starter rights already granted for a received version. Pro pricing,
+billing and entitlements are not implemented; no payment is needed to use Starter.
+Database and safety capabilities stay in the free CLI. The
+[edition guide](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.21/docs/commercial-readiness.md)
+owns the detailed boundary.
+
+Preview describes stability, not a trial countdown. Support is best effort, with no
+service-level agreement, database hosting, backups or production support. Before use,
+read the release's [privacy statement](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.21/PRIVACY.md)
+and [support policy](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.21/SUPPORT.md).
+Report editor problems in the
+[Rehearsal issue tracker](https://github.com/Ddupasquier/rehearsal-db/issues), as
+described in the support policy.
+Use its [private security process](https://github.com/Ddupasquier/rehearsal-vscode/blob/v0.1.21/SECURITY.md)
+for vulnerabilities; never post credentials, private rows or baseline files publicly.
+
+Historical VSIX files retain their bundled terms. Choose a reviewed release carrying
+the Starter license; a development candidate is not released merely because its version
+number matches. The [release list](https://github.com/Ddupasquier/rehearsal-vscode/releases)
+is the authority for downloadable artifacts and their checksums.
 
 ## Try the free engine first
 
 Start with [Getting started](getting-started.md). A successful CLI rehearsal proves the
-project and local runtime are compatible before you evaluate the visual workflow.
+project and local runtime are compatible before you use the visual workflow.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rehearsal-db/core",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "private": false,
   "description": "Catch PostgreSQL and Supabase migrations that pass on empty databases but fail on real data—before deploy.",
   "repository": {
@@ -78,7 +78,7 @@
     "test:fixture:resources": "npm run build && node scripts/verification/run_scenario.mjs resources",
     "release:verify": "npm run build && node scripts/verification/release_gate.mjs",
     "check": "npm run check:syntax && npm run typecheck && npm run test && npm run docs:build && npm run format:check && npm run package:audit",
-    "check:syntax": "find scripts tests -type f -name '*.mjs' -exec node --check {} +",
+    "check:syntax": "node scripts/verification/check_syntax.mjs",
     "typecheck": "npm run build && tsc --project tsconfig.json",
     "format": "prettier --write .",
     "format:check": "prettier --check .",