feat: supabase-only self-hosting with guided setup wizard

.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>

CONTRIBUTING.md

@@ -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).