Staging-aware Supabase identity guard + staging setup runbook

[BigSimmo]

Summary

Makes staging provisioning turnkey without creating any live resource (per the decision to defer the billable Supabase project). Follows on from the production-platform work (PR #332).

The only code change staging needed was the identity guard: src/lib/supabase/project.ts pinned the expected project to production, so a staging deployment would fail check:supabase-project and throw at env-load (env.ts → assertExpectedSupabaseProjectConfig). This makes the guard accept a second, explicitly-declared staging project while preserving the anti-footgun property.

What changed

• src/lib/supabase/project.ts — accepts a staging project only when both SUPABASE_STAGING_PROJECT_REF and SUPABASE_STAGING_PROJECT_NAME are set. It refuses a staging ref that is invalid, partially declared, or collides with the production/stale ref (the "can't silently point staging at prod" speed bump the deployment doc asked for). expectedSupabaseProject stays the resolved default, so production behavior is byte-identical when the staging vars are unset. observed.environment now reports production | staging.
• src/lib/env.ts + scripts/check-supabase-project.ts — pass the two staging vars through, so activating staging is env-only, no code edit, and the CLI guard prints the resolved [environment].
• tests/supabase-project.test.ts — +4 cases: staging accepted, production unchanged with staging declared, prod-ref collision rejected, partial declaration rejected.
• docs/staging-setup.md — turnkey runbook: create project → supabase db push → seed synthetic corpus → build image → runtime-secrets table → soak validation, with operator-only steps (billable project create, Fly host) called out.

Verification

• verify:cheap ✅ — 1350 passed / 1 skipped (lint, typecheck, sitemap, unit).
• Live check:supabase-project for production still passes unchanged (now tagged [production]).
• Staging-declared config with a test ref resolves and passes (Supabase targets Clinical KB Staging), proving env-only activation.

How to activate staging (once the project exists)

1. Create the staging Supabase project (ap-southeast-2). Deferred — billable; can be done via Supabase MCP or dashboard.
2. supabase db push the migrations; seed a small synthetic corpus.
3. Set SUPABASE_STAGING_PROJECT_REF + SUPABASE_STAGING_PROJECT_NAME (plus the usual NEXT_PUBLIC_SUPABASE_URL/SUPABASE_PROJECT_REF/keys) on the staging host → it boots.

No production settings touched. No live resource created.

🤖 Generated with Claude Code

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.