Scratch Install Rehearsal

Use this rehearsal before promoting changes that affect install, setup, provider authorization, Build Studio, Work Capsules, sandbox promotion, or platform shell routing.

The rehearsal is intentionally separate from scripts/fresh-install.ps1. The fresh-install script resets the local developer stack. The scratch rehearsal creates an isolated git worktree and Docker Compose project so first-run behavior can be checked beside the real install.

What It Proves

• The current committed source can boot from empty runtime volumes.
• The portal reaches /api/health without copying secrets from the source install.
• Generated scratch credentials are isolated to the scratch worktree.
• Codex CLI and Claude CLI availability is recorded as evidence when present on the host.
• The scratch portal and sandbox use alternate host ports so the production-served local install can remain online.

Plan-Only Preview

.\scripts\scratch-install-rehearsal.ps1

The default mode prints the source SHA, scratch paths, Compose project name, generated URLs, and CLI availability without creating containers or worktrees.

Run The Rehearsal

.\scripts\scratch-install-rehearsal.ps1 -Execute

The script will:

1. Create a detached scratch worktree from HEAD.
2. Generate a scratch-only .env.
3. Generate a Compose override with non-default host ports.
4. Start the portal and sandbox with a unique Compose project and a low Compose parallel limit.
5. Wait for the scratch portal health endpoint.
6. Write evidence files under the scratch evidence directory.
7. Stop the scratch stack, remove scratch volumes, remove scratch image tags, and remove the scratch worktree unless keep flags are supplied.

Use a different port range if the defaults are occupied:

.\scripts\scratch-install-rehearsal.ps1 -Execute -PortBase 4100

By default the script searches forward from -PortBase until it finds a free set of host ports. Add -NoAutoPortSearch when you want port conflicts to fail immediately.

Leave the scratch portal online for browser inspection:

.\scripts\scratch-install-rehearsal.ps1 -Execute -KeepRunning

The stop command is printed at the end when -KeepRunning is used.

Run the first-run customer walkthrough while the scratch portal is live:

.\scripts\scratch-install-rehearsal.ps1 -Execute -RunFirstRunWalkthrough

The walkthrough opens the scratch portal with Playwright, confirms /setup is reachable on empty runtime volumes, creates the scratch organization and owner account, verifies the provider setup surface, and verifies /build/work after first login. It writes screenshots and first-run-walkthrough-result.json to the same evidence directory. The scratch password is used only for that local browser session and is not written to evidence JSON. The walkthrough uses a 120-second per-step timeout by default to allow clean production containers to complete cold first-auth navigation; use -WalkthroughTimeoutSeconds <seconds> when a slower machine needs more room.

Use -ComposeParallelLimit to tune build concurrency. The default is 1 to avoid Docker Desktop memory pressure during full-stack first-run rehearsal.

Use -KeepWorktree when you want to inspect generated scratch files after a completed run. Evidence JSON remains under the scratch evidence directory even when the worktree is removed.

Use -KeepImages when you want to inspect the built scratch image tags after the run. Build cache may still make later rehearsals faster even when the tags are removed.

Evidence Files

The evidence directory contains:

• scratch-rehearsal-manifest.json
• scratch-rehearsal-result.json after health passes
• first-run-walkthrough-result.json and screenshots when -RunFirstRunWalkthrough is used
• compose-ps.txt and portal-logs.txt if health fails

Attach these files to the Work Capsule or release evidence before opening a PR for merge-ready promotion work.

Backlog And Provider State

This rehearsal does not copy the source install database or provider secrets. That is deliberate.

For platform replacement or re-baselining, preserve backlog and epic records through the approved backup/export path before promotion, then re-authorize providers in the scratch or replacement install. Provider rows may be restored as setup requirements, but raw OAuth/client secrets must not be copied into the scratch evidence bundle.