@donotdev/cli 0.0.15 → 0.0.17

package/templates/root-consumer/guides/dndev/SETUP_FIREBASE.md.example

@@ -1,13 +1,13 @@
 # Setup: Firebase
 
-**From zero to deployed in 5 steps.**
+**From zero to deployed in 5 steps. Covers Auth, Firestore, Storage, Cloud Functions, and Hosting.**
 
 ---
 
 ## Step 1: Run Firebase Setup
 
 ```bash
-dndev firebase:setup
+dndev setup firebase
 ```
 
 This command:
@@ -60,7 +60,7 @@ dndev emu start
 
 Select services: Auth + Firestore + Functions. This starts Firebase emulators so you can develop without touching production.
 
-**Verify:** Open the app (`bun dev`), sign up, create some data. Everything runs locally.
+**Verify:** Open the app (`dndev dev`), sign up, create some data. Everything runs locally.
 
 ---
 
@@ -81,6 +81,66 @@ This handles everything:
 
 ---
 
+## Cloud Functions
+
+Functions are scaffolded in `functions/` and auto-deployed with `dndev deploy`.
+
+**Server secrets** (Stripe, OAuth, etc.) go in `functions/.env` — see the [Secrets](#secrets-stripe-oauth-etc) section below.
+
+### CRUD Functions (one line)
+
+```typescript
+// functions/src/index.ts
+import { initializeApp } from 'firebase-admin/app';
+import { createCrudFunctions } from '@donotdev/functions/firebase';
+import * as entities from 'entities';
+
+initializeApp();
+export const crud = createCrudFunctions(entities);
+```
+
+**Result:** Auto-generates CRUD handlers for each entity. The export name (camelCase, e.g. `crud`) is what you use client-side: `httpsCallable(functions, 'crud')`. The operation ID (snake_case, e.g. `create_products`) is used internally for logging and rate limiting.
+
+### Custom Functions
+
+```typescript
+import * as v from 'valibot';
+import { createFunction } from '@donotdev/functions/firebase';
+import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
+
+const schema = v.object({ productId: v.string() });
+
+export const getProductDetails = createFunction(schema, 'get_product_details', async (data, { uid }) => {
+  const db = getFirebaseAdminFirestore();
+  const doc = await db.collection('products').doc(data.productId).get();
+  return doc.data();
+});
+```
+
+Rate limiting, metrics, auth, schema validation — all included by default.
+
+### Import Rules
+
+**Functions run on Node.js — you MUST use `/server` imports:**
+
+```typescript
+// ✅ CORRECT
+import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
+import { handleError } from '@donotdev/core/server';
+
+// ❌ WRONG - crashes on deploy
+import { getFirestore } from '@donotdev/firebase';
+import { handleError } from '@donotdev/core';
+```
+
+### Cloud Run IAM (Technical Detail)
+
+Firebase 2nd gen Cloud Functions run on Cloud Run. By default, Cloud Run blocks unauthenticated OPTIONS requests (CORS preflight). `dndev deploy` automatically runs `gcloud run services update --no-invoker-iam-check` on all deployed functions.
+
+If you deploy manually with `firebase deploy`, you'll see `403 Forbidden` on CORS preflight. Use `dndev deploy` instead.
+
+---
+
 ## Environment Variables
 
 **Vite loads `.env` from the app directory only. NOT from the repo root.**
@@ -94,17 +154,20 @@ This handles everything:
 | `functions/.env` | Server secrets: STRIPE_SECRET_KEY, OAuth secrets | Cloud Functions runtime |
 | Root `.env` | **Not read by Vite.** Reference only. | Nothing |
 
-**`dndev firebase:setup` writes Firebase vars to `apps/<app>/.env` automatically.**
+**`dndev setup firebase` writes Firebase vars to `apps/<app>/.env` automatically.**
 
-**Custom domains:** Framework uses `APP_URL` hostname as `authDomain` in production (not Firebase's `projectId.firebaseapp.com`). Copy/paste `FIREBASE_AUTH_DOMAIN` from Firebase Console in both `.env.local` and `.env.production` — framework handles the rest.
+**Custom domains:** Framework uses `APP_URL` hostname as `authDomain` in production (not Firebase's `projectId.firebaseapp.com`). Set your `FIREBASE_AUTH_DOMAIN` env var (with the appropriate `VITE_` or `NEXT_PUBLIC_` prefix) in `.env.local` and `.env.production` — framework handles the rest.
 
 ---
 
 ## Staging Environment (Optional)
 
 1. Create a second Firebase project (e.g., `my-app-staging`)
-2. Run `dndev firebase:setup` again and select the staging project
-3. Add to `.firebaserc`: `{ "projects": { "staging": "my-app-staging" } }`
+2. Run `dndev setup firebase` again and select the staging project
+3. The wizard updates `.firebaserc` — add a `"staging"` alias manually if the wizard only sets `"default"`:
+   ```json
+   { "projects": { "default": "my-app-prod", "staging": "my-app-staging" } }
+   ```
 4. Create `service-account-key.staging.json` (same steps as production)
 5. Deploy: `dndev staging`
 
@@ -120,14 +183,13 @@ Server-side secrets go in `functions/.env`, not the app `.env`.
 # functions/.env
 STRIPE_SECRET_KEY=sk_live_...
 STRIPE_WEBHOOK_SECRET=whsec_...
-SUPABASE_SERVICE_ROLE_KEY=eyJ...   # if using Supabase
 GITHUB_CLIENT_SECRET=...
 ```
 
 Then sync to your runtime and CI/CD:
 
 ```bash
-dndev sync-secrets                    # Firebase Secret Manager / Vercel env
+dndev sync-secrets                    # Firebase Secret Manager
 dndev sync-secrets --target github    # GitHub Secrets (for CI/CD workflows)
 ```
 
@@ -137,16 +199,6 @@ See [ENV_SETUP.md → Secrets Philosophy](./ENV_SETUP.md#secrets-philosophy) for
 
 ---
 
-## Cloud Run IAM (Technical Detail)
-
-Firebase 2nd gen Cloud Functions run on Cloud Run. By default, Cloud Run blocks unauthenticated OPTIONS requests (CORS preflight). This breaks browser calls to your functions.
-
-`dndev deploy` automatically runs `gcloud run services update --no-invoker-iam-check` on all deployed functions. Your functions still validate Firebase Auth in code — this only allows the CORS preflight to pass.
-
-If you deploy manually with `firebase deploy`, you'll need to run this yourself. Use `dndev deploy` instead.
-
----
-
 ## Troubleshooting
 
 **"Service account key not found"**
@@ -171,4 +223,4 @@ If you deploy manually with `firebase deploy`, you'll need to run this yourself.
 
 ---
 
-**`dndev firebase:setup` → download service account key → enable Auth + Firestore → `dndev emu start` → `dndev deploy`. That's it.**
+**`dndev setup firebase` → download service account key → enable Auth + Firestore → `dndev emu start` → `dndev deploy`. That's it.**

package/templates/root-consumer/guides/dndev/SETUP_FUNCTIONS.md.example

@@ -1,114 +1,9 @@
-# Setup: Firebase Functions
+# Setup: Functions
 
-**Most is pre-configured.** Functions scaffolded. Just add config and deploy.
+**This guide has been merged into provider-specific guides.**
 
----
+- **Firebase Cloud Functions** → See [SETUP_FIREBASE.md § Cloud Functions](./SETUP_FIREBASE.md#cloud-functions)
+- **Supabase Edge Functions** → See [SETUP_SUPABASE.md § Edge Functions](./SETUP_SUPABASE.md#edge-functions)
+- **Vercel Functions** → See [SETUP_VERCEL.md § Vercel Functions](./SETUP_VERCEL.md#vercel-functions-optional)
 
-## ⚠️ CRITICAL: Import Rules
-
-**Functions run on Node.js - you MUST use `/server` imports or your function will crash.**
-
-```typescript
-// ✅ CORRECT
-import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
-import { handleError } from '@donotdev/core/server';
-
-// ❌ WRONG - crashes on deploy
-import { getFirestore } from '@donotdev/firebase';
-import { handleError } from '@donotdev/core';
-```
-
-**Rule:** Always use `/server` suffix for:
-- `@donotdev/firebase/server`
-- `@donotdev/core/server`
-- `@donotdev/utils/server`
-
----
-
-## CRUD Functions Setup
-
-**One line to register all entity functions:**
-
-```typescript
-// functions/src/index.ts
-import { initializeApp } from 'firebase-admin/app';
-import { createCrudFunctions } from '@donotdev/functions/firebase';
-import * as entities from 'entities';
-
-initializeApp();
-export const crud = createCrudFunctions(entities);
-```
-
-**Result:** Auto-generates `create_products`, `get_products`, `list_products`, `update_products`, `delete_products` for each entity.
-
-**Access control:** Configured via `entity.access` (see SETUP_CRUD.md). All functions use `invoker: 'public'` - security enforced via role-based access in code.
-
----
-
-## Custom Functions
-
-**Use `createFunction` — handles config, validation, auth, rate limiting, metrics automatically:**
-
-```typescript
-import * as v from 'valibot';
-import { createFunction } from '@donotdev/functions/firebase';
-import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
-
-const schema = v.object({ productId: v.string() });
-
-export const getProductDetails = createFunction(schema, 'get_product_details', async (data, { uid }) => {
-  const db = getFirebaseAdminFirestore();
-  const doc = await db.collection('products').doc(data.productId).get();
-  return doc.data();
-});
-```
-
-**That's it.** Rate limiting, metrics, auth, schema validation — all included by default. No config needed.
-
-**Advanced:** Use `createBaseFunction` if you need custom config (memory, timeout, region override).
-
----
-
-## Post-Deployment: Cloud Run IAM
-
-**`dndev deploy` handles this automatically.** It runs `gcloud run services update --no-invoker-iam-check` on all deployed functions after each deploy.
-
-If you deploy manually with `firebase deploy` (not recommended), you'll see `403 Forbidden` on CORS preflight. Fix by using `dndev deploy` instead, or run manually:
-
-```bash
-gcloud run services update <function-name> --region=<region> --no-invoker-iam-check --project=<project-id>
-```
-
-**Why?** Cloud Run blocks unauthenticated OPTIONS (CORS preflight) by default. Your function still validates Firebase Auth in code — this only allows the preflight to pass.
-
----
-
-## Function Naming
-
-**Export name (camelCase):**
-```typescript
-export const getDashboardMetrics = onCall(...);
-// Client: httpsCallable(functions, 'getDashboardMetrics')
-```
-
-**Operation ID (snake_case):**
-```typescript
-createBaseFunction(config, handler, 'get_dashboard_metrics')
-// Used for logging, rate limiting
-```
-
----
-
-## Environment
-
-```bash
-# .env.local (local)
-STRIPE_SECRET_KEY=sk_test_...
-
-# .env (production, synced via dndev sync-secrets)
-STRIPE_SECRET_KEY=sk_live_...
-```
-
----
-
-**Add functions, get backend. Framework handles the rest.**
+Each provider guide covers function setup, CRUD registration, custom functions, import rules, and deployment for that stack.

package/templates/root-consumer/guides/dndev/SETUP_OAUTH_PROVIDERS.md.example

@@ -0,0 +1,60 @@
+# OAuth Provider Setup Guide
+
+Each OAuth provider requires manual registration in their developer console.
+`dndev setup oauth` computes the correct redirect URI for you.
+
+## Redirect URIs
+
+### Firebase
+```
+https://{{PROJECT_ID}}.firebaseapp.com/__/auth/handler
+```
+> If you use a custom auth domain, replace `{{PROJECT_ID}}.firebaseapp.com` with your custom domain.
+
+### Supabase
+```
+https://{{PROJECT_ID}}.supabase.co/auth/v1/callback
+```
+
+---
+
+## Google OAuth
+
+1. Go to https://console.cloud.google.com/apis/credentials
+2. Create **OAuth 2.0 Client ID** (type: Web application)
+3. Add **Authorized redirect URI** (see above)
+4. Copy **Client ID** and **Client Secret**
+5. Enable in your backend:
+   - Firebase: Console > Authentication > Sign-in method > Google
+   - Supabase: Dashboard > Authentication > Providers > Google
+
+## GitHub OAuth
+
+1. Go to https://github.com/settings/developers
+2. Click **New OAuth App**
+3. Set **Authorization callback URL** (see redirect URI above)
+4. Copy **Client ID** and **Client Secret**
+5. Enable in your backend:
+   - Firebase: Console > Authentication > Sign-in method > GitHub
+   - Supabase: Dashboard > Authentication > Providers > GitHub
+
+## Apple Sign In
+
+1. Go to https://developer.apple.com/account/resources/identifiers/list/serviceId
+2. Create a **Services ID**
+3. Enable **Sign In with Apple**
+4. Add **Redirect URL** (see above)
+5. Create a **Key** for Sign In with Apple
+6. Enable in your backend:
+   - Firebase: Console > Authentication > Sign-in method > Apple
+   - Supabase: Dashboard > Authentication > Providers > Apple
+
+> **Note:** Apple requires an Apple Developer Program membership ($99/year).
+
+## Verify
+
+```bash
+dndev doctor
+```
+
+Check that auth providers are detected and backend configuration is referenced.

package/templates/root-consumer/guides/dndev/SETUP_STRIPE.md.example

@@ -0,0 +1,62 @@
+# Stripe Setup Guide
+
+## Prerequisites
+- Stripe account (https://dashboard.stripe.com)
+- `@donotdev/billing` installed
+
+## 1. Get API Keys
+
+1. Go to https://dashboard.stripe.com/apikeys
+2. Copy your **Publishable key** (`pk_test_...`) → `.env`
+3. Copy your **Secret key** (`sk_test_...`) → `supabase/functions/.env` or `functions/.env`
+
+> **Security:** Never commit secret keys. Stripe also supports restricted keys (`rk_test_...`, `rk_live_...`) for tighter permissions.
+
+## 2. Configure Webhook
+
+1. Go to https://dashboard.stripe.com/webhooks
+2. Click **Add endpoint**
+3. Set endpoint URL:
+   - Supabase: `https://{{PROJECT_ID}}.supabase.co/functions/v1/stripe-webhook`
+   - Firebase: `https://europe-west1-{{PROJECT_ID}}.cloudfunctions.net/stripeWebhook` (replace `europe-west1` with your region if different)
+4. Select events:
+   - `checkout.session.completed`
+   - `customer.subscription.created`
+   - `customer.subscription.updated`
+   - `customer.subscription.deleted`
+   - `invoice.payment_succeeded`
+   - `invoice.payment_failed`
+5. Copy the **Signing secret** (`whsec_...`) → `supabase/functions/.env`
+
+## 3. Environment Variables
+
+### App `.env` (public)
+```
+VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...
+```
+
+### Functions `.env` (secret)
+```
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+## 4. Test Clocks (Optional)
+
+For subscription testing without waiting for real billing cycles:
+1. Go to https://dashboard.stripe.com/test/test-clocks
+2. Create a test clock
+3. Create customers attached to the test clock
+4. Advance time to trigger billing events
+
+## 5. Verify
+
+```bash
+dndev setup stripe   # Interactive key setup + validation
+dndev doctor         # Health check for all providers
+```
+
+Check that:
+- Publishable key format is valid
+- Secret key format is valid
+- Key modes match (both test or both live)

package/templates/root-consumer/guides/dndev/SETUP_SUPABASE.md.example

@@ -1,47 +1,44 @@
 # Setup: Supabase
 
-**From zero to a working Supabase backend: env, tables, RLS, and adapter behavior.**
+**From zero to a working Supabase backend. Covers Auth, PostgreSQL, Storage, Edge Functions, and deployment.**
 
 ---
 
 ## Step 1: Run Supabase Setup
 
 ```bash
-dndev supabase:setup
+dndev setup supabase
 ```
 
 This command:
 - Lets you choose the target app (if you have an `apps/` directory)
-- Asks for your **public** Supabase project URL and anon key
-- Writes `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY` to your app's `.env`
+- Asks for your **public** Supabase project URL and public key
+- Writes `VITE_SUPABASE_URL` and `VITE_SUPABASE_PUBLIC_KEY` to your app's `.env`
 
 **We only ask for public credentials** (safe to ship in your client bundle). We never ask for the service_role key.
 
-Get URL and anon key from: [Supabase Dashboard](https://supabase.com/dashboard) → your project → **Settings → API**.
+Get URL and public key from: [Supabase Dashboard](https://supabase.com/dashboard) → your project → **Settings → API**.
 
 ---
 
 ## Step 2: Generate Tables from Entities
 
-The framework can generate PostgreSQL migrations from your entity definitions (same source as the schema used by the app).
+The framework generates PostgreSQL migrations from your entity definitions. This runs automatically as part of `dndev setup supabase`, or you can run it separately:
 
 ```bash
-dn generate sql
+dndev setup supabase
 ```
 
+During setup, the wizard detects your entities and generates SQL migrations.
+
 **What it does:**
-- Discovers entities (e.g. in `entities/` or your configured `--entity-dir`)
+- Discovers entities (e.g. in `entities/` or your configured entity directory)
 - For each entity: `CREATE TABLE` with columns mapped from field types (text, number, boolean, timestamptz, uuid, jsonb, etc.)
 - Adds technical columns: `id` (uuid, default `gen_random_uuid()`), `user_id`, `created_at`, `updated_at` (with `DEFAULT now()`), `created_by_id`, `updated_by_id`, `status`
 - Enables **Row Level Security (RLS)** and creates policies so rows are scoped by `auth.uid() = user_id`
 - Adds a trigger so `updated_at` is set automatically on every `UPDATE`
 
-**Options (optional):**
-- `--entity-dir <path>` — where to find entity files (default: from app root)
-- `--output-dir <path>` — where to write migrations (default: `supabase/migrations`)
-- `--no-single-file` — one migration file per entity instead of one combined file
-
-Output is written to `supabase/migrations/` (or your `--output-dir`) as a timestamped `.sql` file. Apply it with the Supabase CLI or Dashboard SQL editor.
+Output is written to `supabase/migrations/` as a timestamped `.sql` file.
 
 ---
 
@@ -63,7 +60,80 @@ Copy the contents of the generated migration file into the SQL Editor in the Sup
 
 ---
 
-## Step 4: Adapter Behavior (DB-Managed Timestamps)
+## Step 4: Enable Supabase Services
+
+Go to the Supabase Dashboard and configure:
+
+**Authentication** (enabled by default on new projects):
+- Authentication → Providers → Verify Email is enabled
+- Add OAuth providers if needed (Google, GitHub, etc.)
+
+**Storage** (optional — only if your app uploads files):
+- Storage → Create bucket (e.g. `uploads`)
+- Configure public or RLS policies as needed
+
+---
+
+## Edge Functions
+
+Supabase Edge Functions run on Deno at the edge. If you selected functions during scaffolding, they're in `supabase/functions/`.
+
+### CRUD Functions (one line)
+
+```typescript
+// supabase/functions/crud/index.ts
+import * as entities from '../_shared/entities.ts';
+import { createSupabaseCrudFunctions } from '@donotdev/functions/supabase';
+
+const { serve } = createSupabaseCrudFunctions(entities);
+Deno.serve(serve);
+```
+
+**Result:** Auto-generates create, get, list, update, delete handlers for each entity. The dispatcher routes via `_functionName` in the request body.
+
+### Custom Functions
+
+```typescript
+// supabase/functions/my-function/index.ts
+import * as v from 'valibot';
+import { createSupabaseHandler } from '@donotdev/functions/supabase';
+
+const schema = v.object({ productId: v.string() });
+
+export default createSupabaseHandler(
+  'get_product_details',
+  schema,
+  async (data, ctx) => {
+    const { data: product } = await ctx.supabaseAdmin
+      .from('products')
+      .select('*')
+      .eq('id', data.productId)
+      .single();
+    return product;
+  },
+  'user'  // requiredRole (default)
+);
+```
+
+**Context available in handler:** `ctx.uid` (authenticated user ID), `ctx.userRole`, `ctx.supabaseAdmin` (admin client with full access).
+
+Rate limiting, metrics, auth, schema validation — all included by default.
+
+### Deploy Edge Functions
+
+```bash
+supabase functions deploy
+```
+
+Or deploy everything with:
+
+```bash
+dndev deploy
+```
+
+---
+
+## Adapter Behavior (DB-Managed Timestamps)
 
 Tables use **snake_case** column names and **timestamptz** for `created_at` / `updated_at`. The framework expects **camelCase** and **ISO date strings** in the app.
 
@@ -74,7 +144,7 @@ The **Supabase CRUD adapter** handles this automatically:
 | **Read** (get, query, subscribe) | Rows from Supabase are normalized: snake_case → camelCase (e.g. `created_at` → `createdAt`), and timestamp columns are converted to ISO strings. Your UI receives the same shape as with Firebase. |
 | **Write** (add, set, update) | The adapter does **not** send `createdAt` / `updatedAt` (or snake equivalents). The database sets them via `DEFAULT now()` and the `updated_at` trigger. |
 
-So you never set timestamps in app code when using Supabase — the DB owns them.
+You never set timestamps in app code — the DB owns them.
 
 ---
 
@@ -85,40 +155,61 @@ So you never set timestamps in app code when using Supabase — the DB owns them
 | Variable | Purpose |
 |----------|---------|
 | `VITE_SUPABASE_URL` | Project URL (public) |
-| `VITE_SUPABASE_ANON_KEY` | Anon key (public, safe in bundle) |
+| `VITE_SUPABASE_PUBLIC_KEY` | Public key (safe in bundle) |
 
-**Server (e.g. API routes, Edge Functions):** use the same URL and `SUPABASE_SERVICE_ROLE_KEY` for admin operations. Never expose the service_role key to the client. Put it in `functions/.env` or your host’s env (Vercel, etc.).
+**Server (Edge Functions, API routes):** use the same URL and `SUPABASE_SERVICE_ROLE_KEY` for admin operations. Never expose the service_role key to the client. Put it in `functions/.env` or your host's env (Vercel, etc.).
 
-See [ENV_SETUP.md](./ENV_SETUP.md) for where to put secrets.
+See [ENV_SETUP.md](./ENV_SETUP.md) for the full secrets policy.
 
 ---
 
-## Storage (Optional)
+## Hosting the Frontend
+
+Supabase provides **Auth, PostgreSQL, Storage, and Edge Functions**. It does **not** host your built frontend.
+
+**We recommend Vercel** — see [SETUP_VERCEL.md](./SETUP_VERCEL.md).
+
+```bash
+dndev deploy
+```
 
-If your app uploads files, create a storage bucket in the Supabase Dashboard (e.g. `uploads`). The default bucket name used by the framework is `uploads`. Configure public or RLS policies in the Dashboard as needed.
+For Supabase projects, `dndev deploy` deploys frontend to Vercel (via scaffolded `vercel.json`) and Edge Functions to Supabase. Make sure you've set `VITE_SUPABASE_*` in Vercel Dashboard → Environment Variables.
 
 ---
 
-## Hosting the frontend
+## Local Development
+
+**Against hosted Supabase:**
 
-Supabase gives you **Auth, Postgres, Storage, and Edge Functions**. It does **not** host your built frontend (Vite/Next SPA). You need a separate host for the `dist/` output.
+```bash
+dndev dev
+```
 
-**We recommend:**
+The app talks to your Supabase project directly.
 
-- **Vercel** — Connect your repo, set `VITE_SUPABASE_URL` and `VITE_SUPABASE_ANON_KEY` in the project env, then deploy. Good fit for Next.js or Vite.
-- We scaffold **vercel.json**; run `dndev deploy` and choose Frontend (Vercel) or Frontend + Edge Functions. Set `VITE_SUPABASE_*` in Vercel project env.
+**Local emulation:**
 
-**Deploy:** Frontend goes to Vercel (scaffolded vercel.json); Edge Functions to Supabase. It does **not** deploy your Supabase app’s frontend to Vercel/Netlify. For that, use the host’s dashboard or CLI (e.g. `vercel`, `netlify deploy`) after building. See [ENV_SETUP.md](./ENV_SETUP.md) for production env vars on Vercel.
+```bash
+dndev emu start
+```
+
+Or install the [Supabase CLI](https://supabase.com/docs/guides/cli) and run `supabase start` for a local Postgres + Auth + Storage stack. Point `VITE_SUPABASE_URL` and keys to the local instance.
 
 ---
 
-## Local Development
+## Troubleshooting
 
-- **Against hosted Supabase:** After `supabase:setup`, run `bun dev` — the app talks to your Supabase project.
-- **Local Supabase:** Install the [Supabase CLI](https://supabase.com/docs/guides/cli) and run `supabase start` for a local Postgres + Auth + Storage stack. Point `VITE_SUPABASE_URL` and keys to the local instance.
+**"Table not found" / "relation does not exist"**
+→ Run `dndev setup supabase` (generates SQL) then apply migrations with `supabase db push`
 
----
+**"Permission denied" / RLS errors**
+→ Check RLS policies in Supabase Dashboard → Database → Policies
+→ Generated migrations include default policies — verify they were applied
 
-## Summary
+**"Service role key" errors in functions**
+→ Put `SUPABASE_SERVICE_ROLE_KEY` in `functions/.env` (never in `VITE_*` vars)
+→ Get it from Supabase Dashboard → Settings → API
+
+---
 
-**`dndev supabase:setup`** → paste URL + anon key → **`dn generate sql`** → apply migrations → **`bun dev`**. The adapter normalizes read (snake→camel, ISO) and leaves timestamps to the DB on write.
+**`dndev setup supabase` → paste URL + public key → apply migrations → `dndev dev`. The adapter normalizes everything automatically.**