feat: supabase-only self-hosting with guided setup wizard (#108)

## Summary

Phase B of the OSS-ready program: self-hosting becomes real. Local
development targets **any Supabase project** (free tier suffices)
instead of hard-pinning the owner's production database, and `pnpm
dev:setup` walks a contributor from a fresh clone to a verified running
stack.

- **Un-pinned validator**: `scripts/dev-worker-config.ts` accepts any
Supabase session pooler (host pattern, port 5432, exact TLS params,
`<role>.<projectRef>` usernames, host/port/db/ref equality across the
three role URLs). The previous production coordinates pass unchanged.
- **Shared env contract** (`scripts/local-env-contract.ts`) extracted
from `dev.ts` behavior-neutrally; wizard key metadata is compile-time
exhaustive.
- **Migration `0003_target_parity`**: installs `vector` +
`pg_stat_statements`, revokes all Data-API-role and implicit-PUBLIC
access (current + default ACLs) so the post-apply target assertion
passes on fresh projects exactly as on production. Contract gains
schema-privilege and effective-default-ACL checks scoped to
`postgres`-owned ACLs.
- **`pnpm dev:setup`**: preflight → guided prompts
(Supabase/Clerk/Daytona/optional groups) with generated secrets →
confirm → atomic 0600 env writes (bare values; `#`, `$`, quotes, edge
whitespace, control chars rejected as unrepresentable across dotenv
parsers) → migrations via sanitized child env → role passwords + Vault
rows on the admin connection → pooler-login and signed-context probes
(production signer reused) → optional force-recreated stack start.
`--check` is a zero-mutation doctor.
- **README** rewritten as a public front page (screenshot, architecture,
quickstart, self-host, license); **CONTRIBUTING** added; env examples
neutralized.

## ⚠️ One-time operator step at apply time (documented, deliberate)

The 0000 baseline was revised to delete twelve `supabase_admin`
default-ACL recreations that are **denied with SQLSTATE 42501 on every
Supabase project** (verified live on production AND on a fresh 2026
project) and that recreate platform state which already exists
everywhere. Production baselined 0000 without executing it, so its
ledger row must be updated once:

```sql
update drizzle.__drizzle_migrations set hash = '22b56335f7dc10125fb7bdebd46b053e4cceca0a732ddd9c410282d8430a5331' where created_at = 1784981026716;
```

followed immediately by `pnpm db:migrate -- --dry-run` proving no
divergence and 0001/0002/0003 pending. The remedy for any stray
environment is documented in `packages/db/README.md`. Alternatives
(engine-side superseded-checksum compat map; reverting the baseline)
were evaluated and declined — the revert resurrects the fresh-project
blocker, and compat machinery violates the repo's no-legacy rule.

## Verification notes

- [x] `pnpm lint` / `pnpm typecheck` / `pnpm turbo build --force` /
`pnpm deadcode` / `pnpm architecture:check` / `pnpm turbo skills:build`
— independent clean-install reruns, all green
- Adversarial review: **four rounds** with live SELECT-only probes
against production and a fresh throwaway project; 6 + 2 + 3 + 1 findings
all fixed and re-verified; final verdict SAFE-TO-SHIP. Highlights: 42501
permission walls proven empirically on both project generations; env
round-trip proven through the wizard's reader, wrangler's bundled
dotenv+expand, and compose semantics.
- Post-merge plan: prod ledger update + `--dry-run` review + `--apply`
(0001/0002/0003), then a full `pnpm dev:setup` e2e against a throwaway
free-tier project (already created) with an authenticated browser flow,
re-run preservation test, and `--check`.

Author: iamjr15

.env.example

@@ -1,55 +1,53 @@
-# Root .env.local is the only local application credential file. Local Workers
-# use the production Supabase database through its public session pooler and the
-# same three least-privilege roles as production Hyperdrive. Keep each password
-# identical to the password configured on only its matching production role.
-# Administrative migration credentials belong in .env.migrate, never here.
-SUPABASE_GATEWAY_DATABASE_URL=postgresql://app_gateway.snqtclnmhcaupqynjyux:replace_with_gateway_role_password@aws-0-ap-south-1.pooler.supabase.com:5432/postgres?sslmode=require&uselibpqcompat=true
-SUPABASE_AGENT_DATABASE_URL=postgresql://app_agent.snqtclnmhcaupqynjyux:replace_with_agent_role_password@aws-0-ap-south-1.pooler.supabase.com:5432/postgres?sslmode=require&uselibpqcompat=true
-SUPABASE_WEBHOOKS_DATABASE_URL=postgresql://app_webhooks.snqtclnmhcaupqynjyux:replace_with_webhooks_role_password@aws-0-ap-south-1.pooler.supabase.com:5432/postgres?sslmode=require&uselibpqcompat=true
+# Run `pnpm dev:setup` to create the permission-restricted .env.local file. These
+# neutral placeholders document the contract; do not hand-edit pooler URLs when
+# the wizard can assemble and validate them for you.
 
-# Clerk development instance. These test keys are for this laptop only; every
-# Vercel environment uses the production Clerk instance.
-NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_replace_me
-CLERK_SECRET_KEY=sk_test_replace_me
-# The seven optional Clerk/Composio/Daytona/Polar webhook, integration, and checkout keys may stay empty; affected local paths return 503.
-CLERK_WEBHOOK_SIGNING_SECRET=
+# Supabase session pooler only: *.pooler.supabase.com, port 5432, /postgres,
+# and the role-qualified username <role>.<project-ref>. A free dedicated
+# Supabase project is sufficient. Administrative credentials stay in
+# .env.migrate and never enter the application environment.
+SUPABASE_GATEWAY_DATABASE_URL=postgresql://app_gateway.<project-ref>:<generated-role-password>@<region-pooler-host>.pooler.supabase.com:5432/postgres?sslmode=require&uselibpqcompat=true
+SUPABASE_AGENT_DATABASE_URL=postgresql://app_agent.<project-ref>:<generated-role-password>@<region-pooler-host>.pooler.supabase.com:5432/postgres?sslmode=require&uselibpqcompat=true
+SUPABASE_WEBHOOKS_DATABASE_URL=postgresql://app_webhooks.<project-ref>:<generated-role-password>@<region-pooler-host>.pooler.supabase.com:5432/postgres?sslmode=require&uselibpqcompat=true
 
-# Browser-visible local routing configuration; these values are not secrets.
-# The real preview-proxy Worker is service-bound behind the
-# gateway and serves each sandbox on *.localhost:8787. No second preview domain
-# or cloud development deployment is required.
+# Clerk development instance. Production keys are rejected locally. Configure
+# the Clerk session token to expose metadata={{user.public_metadata}}.
+NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=pk_test_<clerk-publishable-key>
+CLERK_SECRET_KEY=sk_test_<clerk-secret-key>
+CLERK_WEBHOOK_SIGNING_SECRET=
 NEXT_PUBLIC_GATEWAY_URL=http://127.0.0.1:8787
 
-# Daytona development access.
-DAYTONA_API_KEY=
+# Daytona development access. DAYTONA_SANDBOX_SNAPSHOT is an immutable snapshot
+# built from infra/containers/sandbox. The webhook secret is required; unlike
+# optional provider groups, it may not stay empty.
+DAYTONA_API_KEY=<daytona-api-key>
 DAYTONA_API_URL=https://app.daytona.io/api
 DAYTONA_PREVIEW_HOST_SUFFIXES=daytonaproxy01.net,proxy.daytona.work
-# Required: set an explicit development snapshot so local startup can never
-# inherit the production snapshot from the committed Worker configuration.
-DAYTONA_SANDBOX_SNAPSHOT=
+DAYTONA_SANDBOX_SNAPSHOT=<immutable-snapshot-name>
 DAYTONA_TARGET=us
 DAYTONA_WORKSPACE_VOLUME=cheatcode-workspaces-development
-DAYTONA_WEBHOOK_SIGNING_SECRET=
-PREVIEW_TOKEN_SECRET=replace_with_a_distinct_32_byte_secret
-# Optional when the Daytona account requires an explicit organization.
+DAYTONA_WEBHOOK_SIGNING_SECRET=<daytona-webhook-signing-secret>
 DAYTONA_ORG_ID=
 
-# Agent providers and integrations.
+# Optional integrations. Skipping Composio disables connected apps; skipping
+# DeepSeek means users rely on BYOK for that provider.
 COMPOSIO_API_KEY=
 COMPOSIO_AUTH_CONFIGS=
 COMPOSIO_WEBHOOK_SECRET=
-# Optional platform fallback; users can rely on BYOK instead.
 DEEPSEEK_PLATFORM_API_KEY=
 
-# Polar local development always uses the sandbox account.
+# Optional Polar sandbox billing. Skipping this group disables local checkout
+# and billing webhooks while core agent flows remain available.
 POLAR_ACCESS_TOKEN=
 POLAR_SERVER=sandbox
 POLAR_WEBHOOK_SECRET=
 POLAR_PRODUCT_ID_PRO=
 POLAR_PRODUCT_ID_PREMIUM=
 
-# Internal local contracts.
-DATABASE_CONTEXT_SIGNING_SECRET_AGENT=replace_with_a_distinct_32_byte_secret
-DATABASE_CONTEXT_SIGNING_SECRET_GATEWAY=replace_with_a_distinct_32_byte_secret
-DATABASE_CONTEXT_SIGNING_SECRET_WEBHOOKS=replace_with_a_distinct_32_byte_secret
-OUTPUT_DOWNLOAD_SIGNING_SECRET=replace_with_a_distinct_32_byte_secret
+# Generated by `pnpm dev:setup`; each value is at least 32 bytes. Values within the
+# two documented distinctness groups are never reused.
+DATABASE_CONTEXT_SIGNING_SECRET_AGENT=<generated-by-pnpm-dev-setup>
+DATABASE_CONTEXT_SIGNING_SECRET_GATEWAY=<generated-by-pnpm-dev-setup>
+DATABASE_CONTEXT_SIGNING_SECRET_WEBHOOKS=<generated-by-pnpm-dev-setup>
+PREVIEW_TOKEN_SECRET=<generated-by-pnpm-dev-setup>
+OUTPUT_DOWNLOAD_SIGNING_SECRET=<generated-by-pnpm-dev-setup>

.env.migrate.example

@@ -1,8 +1,8 @@
-# Copy to .env.migrate only on an authorized operator workstation. This file
-# targets the production Supabase database and is never loaded by the app,
-# Compose, Wrangler, Next.js, or any Worker.
-SUPABASE_MIGRATION_URL=postgresql://postgres:replace_with_production_admin_password@db.snqtclnmhcaupqynjyux.supabase.co:5432/postgres?sslmode=require
-SUPABASE_MIGRATION_EXPECTED_HOST=db.snqtclnmhcaupqynjyux.supabase.co
+# Generated by `pnpm dev:setup` from a direct or session-pooler Supabase admin
+# connection. Keep this file on an authorized workstation only; the app never
+# loads it. Placeholders are intentionally project-neutral.
+SUPABASE_MIGRATION_URL=postgresql://postgres:<admin-password>@db.<project-ref>.supabase.co:5432/postgres?sslmode=require
+SUPABASE_MIGRATION_EXPECTED_HOST=db.<project-ref>.supabase.co
 SUPABASE_MIGRATION_EXPECTED_DATABASE=postgres
 SUPABASE_MIGRATION_EXPECTED_ROLE=postgres
-SUPABASE_MIGRATION_EXPECTED_SYSTEM_IDENTIFIER=replace_with_pg_control_system_identifier
+SUPABASE_MIGRATION_EXPECTED_SYSTEM_IDENTIFIER=<pg-control-system-identifier>

.github/assets/cheatcode-home.png

@@ -0,0 +1,84 @@
+# Contributing to Cheatcode
+
+Thanks for helping improve Cheatcode. Read [AGENTS.md](AGENTS.md) before making
+changes; it is the canonical architecture, security, and coding guide for
+people and coding agents.
+
+## Set up the repository
+
+Use the exact Node and pnpm versions declared in `package.json`, then run:
+
+```bash
+nvm install
+nvm use
+corepack enable
+CI=true pnpm install
+pnpm dev:setup
+```
+
+The guided wizard creates the ignored `.env.local` and `.env.migrate` files,
+prepares a dedicated Supabase project, verifies all three runtime database
+roles, and can start the Compose stack. A free Supabase project is sufficient.
+You also need Clerk development keys and a Daytona API key plus an immutable
+sandbox snapshot built from `infra/containers/sandbox`.
+
+Never commit either env file, real credentials, database dumps, or sanitized
+copies of secrets. Never run a migration apply against a target you have not
+positively identified and reviewed. Migration files are append-only.
+
+Run `pnpm dev:setup --check` for a read-only check of the host, environment,
+migration ledger, database connectivity, and signed-context probes.
+
+## Make changes
+
+- Preserve package and application ownership boundaries.
+- Read the relevant README before changing a public export, database contract,
+  deployment topology, sandbox boundary, or environment surface.
+- Use pnpm and Turborepo; do not substitute npm or Yarn.
+- Keep unrelated worktree changes intact.
+- Follow the strict TypeScript and naming conventions in `AGENTS.md`.
+
+To change or rotate local role passwords, signing secrets, or provider values,
+rerun `pnpm dev:setup` and replace the relevant prompted values. Existing values are
+preserved by default, missing values are generated, and the idempotent migration,
+Vault provisioning, and probe sequence resumes safely. There is intentionally no
+separate secret-rotation command.
+
+## Verify changes
+
+Run the full final-tree gate chain before requesting review:
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm turbo build --force
+pnpm deadcode
+pnpm architecture:check
+pnpm turbo skills:build
+```
+
+For user-visible or integration behavior, also exercise the real flow with
+`agent-browser --auto-connect --session cheatcode-debug`. Inspect screenshots,
+the browser console, network activity, and application logs. Do not add a
+parallel browser or product-flow test harness.
+
+Every pull request must include verification notes listing commands run, real
+flows exercised, and any omitted check with its reason.
+
+## Commits and pull requests
+
+Use Conventional Commits, for example:
+
+```text
+feat(agent): add a research tool
+fix(db): preserve tenant context on retry
+docs(setup): clarify Daytona snapshots
+```
+
+Keep commit subjects and human-authored pull request titles on one line and at
+or below 72 characters. Explain why the change is needed, call out migration or
+architecture effects, and include the verification notes above.
+
+By contributing repository-owned code, you agree that it is provided under the
+root [LICENSE](LICENSE). Assets and third-party materials remain subject to
+[NOTICE](NOTICE).