Getting Started

Prerequisites

Before you begin, make sure you have:

• Node.js 22+ (or use nvm with the repo's .nvmrc)
• pnpm (npm install -g pnpm)
• Docker (with the daemon running) — required for the local Supabase instance
• A Supabase CLI install is optional — the repo will fall back to a pinned pnpm dlx supabase invocation if one is not found globally

Install dependencies

pnpm install

Local evaluation (fastest path)

This path boots the app locally without connecting any external providers. Authentication, the dashboard shell, and the AI tools all work via local Supabase and seeded test credentials.

1. Run setup

pnpm run setup

This command will:

• Check prerequisites (Docker, pnpm) and give guided recovery output if anything is missing
• Start a local Supabase instance (or use your globally installed CLI)
• Reset and seed the local database with a preview user
• Create apps/web/.env.local from the example file if it does not exist
• Auto-populate the boot-critical environment variables so you do not need to hunt for values

2. Start the app

pnpm dev

The app will be available at http://localhost:3500.

3. Sign in with the preview user

4. Run the smoke check (optional)

For a repeatable, automated proof that the local path is working:

pnpm local-eval:smoke

This reruns setup, verifies the seeded user exists in Postgres, starts the app, and checks that both / and /auth/login respond as expected.

Environment variables

After running setup, apps/web/.env.local will contain the boot-critical local defaults. The following additional variables unlock provider-gated features:

Authentication

Email

Set exactly one of these sets to enable transactional email:

Payments

Set one of these to enable billing, subscriptions, and credit purchases:

File storage

AI tools

Analytics

Monitoring

Full integrated setup (Vercel + external providers)

For a fully wired environment with real auth, email, payments, and storage:

1. Create a Vercel project and link it to your repository.
2. Create a Supabase project and copy the project URL and anon key into your Vercel environment variables.
3. Add the provider variables listed above to Vercel (Settings → Environment Variables).
4. Push to your branch — Vercel will build and deploy automatically.
5. Run pnpm db:migrate after each schema change to keep Supabase in sync.

Parallel development with worktrees

If you work across multiple features in parallel, the repo includes worktree helpers:

# Create a new worktree for a feature branch
pnpm worktree:create

# Resume an existing worktree
pnpm worktree:resume

# List all active worktrees
pnpm worktree:list

# Remove a worktree when done
pnpm worktree:remove

Each worktree gets its own .env.local and Supabase instance so branches do not interfere with each other. A global Supabase CLI install is optional here too — the same repo-owned fallback applies.