Run Modes

Use the lightest mode that proves the decision in front of you. Do not treat a local pass, dry-run, or staging smoke as production approval.

Local Development

Use local development for UI, route, validation, entitlement, and persistence work:

pnpm dev
pnpm check
pnpm test:e2e

This mode is fast and secret-free. It does not prove remote Cloudflare resources, Worker secrets, custom domains, or real provider execution.

Local Release Verification

Use local release verification before any deploy attempt:

pnpm verify:local
pnpm verify:release-targets
pnpm verify:release

verify:release runs the local gate, builds the staging Worker, and performs a Wrangler deploy dry-run. It still does not publish the Worker.

Use quick staging when you need a real Worker URL quickly. For a downstream copy, the simplest first target is a workers.dev URL with no custom-domain route. That proves the Worker, D1, R2, secrets, health smoke, and conversion smoke before DNS and zone permissions enter the picture.

Core command path:

export CONVERSION_DEMO_AUTH_TOKEN=<same-token-configured-on-staging-worker>
pnpm release:deploy-staging-local
pnpm release:deploy-staging-local -- --yes

When CLOUDFLARE_API_TOKEN is present, the helper uses token preflight. When it is absent, it validates the local Wrangler OAuth login with wrangler whoami.

GitHub Staging

Use GitHub staging after repository secrets and Actions billing are ready:

pnpm secrets:sync-github
pnpm secrets:sync-github -- --yes
pnpm release:dispatch-staging
pnpm release:dispatch-staging -- --yes

The deploy workflow builds with RELEASE_COMMIT_SHA=${{ github.sha }}, applies remote D1 migrations, deploys the selected Worker target, runs deploy health smoke, and can run the real conversion smoke for the same commit.

Provider Canaries

Use canary Workers to prove behavior that should not replace default staging yet:

auth_canary for Better Auth conversion actors.
billing_canary for trusted billing lifecycle evidence.
replicate_canary for Replicate async provider evidence.
image_safety_canary for fail-closed source-image safety evidence.

Run the provider matrix before canary deploy work:

pnpm report:provider-matrix
pnpm doctor:config -- --environment replicate_canary --require-local-secrets

Production Cutover

Production is operator-gated. Start with a plan, then attach evidence:

pnpm plan:production-resources
cp docs/operations/production-resource-ready-evidence.manifest.example.json resource-ready-evidence.json
pnpm evidence:production-resource-ready -- --manifest resource-ready-evidence.json --strict --json
pnpm preflight:production-cutover -- --stage resource-ready --production-resource-ready-evidence resource-ready-evidence.json --strict

Do not enable production traffic from staging evidence alone. Traffic-ready cutover also needs operator production evidence, DNS/custom-domain evidence, rollback evidence, and image-safety approval.