Setup

Prerequisites

• Node.js 20 or newer and pnpm
• A Supabase account (free tier works for development)
• A Google Cloud project for the OAuth client

Create a Supabase project

1. Create a new Supabase project and note the project URL.
2. Collect the anonymous key and the service-role key from the project API settings.
3. Use the project's Postgres connection string as DATABASE_URL, or run a local Postgres and point DATABASE_URL at it for offline development.

Set SUPABASE_URL, SUPABASE_ANON_KEY, and SUPABASE_SERVICE_ROLE_KEY in your local env file. Never commit env values.

Configure Google OAuth

1. In the Google Cloud Console, create an OAuth client of type Web application.
2. Add the authorized redirect URI for Supabase: https://<project-ref>.supabase.co/auth/v1/callback.
3. In the Supabase dashboard, enable the Google provider under Authentication and paste the client id and secret.
4. Add the app callback URLs to the allowed redirect list:
   • local development: http://localhost:3000/auth/callback
   • public sample: https://demo.buildgrain.com/auth/callback
5. Set GOOGLE_OAUTH_CLIENT_ID and GOOGLE_OAUTH_CLIENT_SECRET in your env file.

If the OAuth env vars are missing in development, the login screen shows a setup blocker that links back to this guide. The kit never fakes a Google login.

Environment variables

The full matrix of key names per mode (development / test / demo / production-kit) lives in the env matrix module and renders in the admin Developer surface. Key names only — values are never displayed or stored in content.

Database: migrate and seed

pnpm install
pnpm db:setup   # run Drizzle migrations
pnpm db:seed    # seed sample-co, atlas-pilot, northstar-trial

The three seed accounts are protected: they cannot be deleted and the nightly reset restores them to their seed state.

Run the app

pnpm dev   # http://localhost:3000

Sign in with Google. Your first sign-in clones the seed template into a private sample workspace and assigns you the owner role.

System admin access

Add your email to ADMIN_ALLOWLIST_EMAILS (comma-separated, case-insensitive). On your next sign-in the kit upserts systemAdmin=true for that account; removing the email downgrades it on the following sign-in. There is no UI toggle for system admin — the allowlist is the only mechanism.

Verification commands

pnpm lint
pnpm typecheck
pnpm test
pnpm build
pnpm e2e
pnpm check:ui-copy
pnpm secret:scan
pnpm verify

Run pnpm verify before handing work off; it chains the lint, test, build, and copy-scan gates.