@donotdev/cli 0.0.13 → 0.0.15

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

@@ -20,6 +20,34 @@
 
 ---
 
+## 0. Provider configuration (required)
+
+CRUD operations use the **CRUD provider** registered at app startup. You must call `configureProviders()` before any component uses `useCrud`.
+
+- **Where:** In a dedicated module, e.g. `src/config/providers.ts`.
+- **When:** Import that module from your root component (e.g. `App.tsx`) so it runs before any CRUD usage.
+
+```typescript
+// App.tsx
+import './config/providers';  // Before any useCrud
+// ...
+```
+
+```typescript
+// config/providers.ts
+import { configureProviders } from '@donotdev/core';
+import { FirestoreAdapter } from '@donotdev/firebase';  // or SupabaseCrudAdapter from '@donotdev/supabase'
+
+configureProviders({
+  crud: new FirestoreAdapter(),
+  // auth, storage optional
+});
+```
+
+If you skip this step, `useCrud` will throw at runtime: "Provider \"crud\" not available. Call configureProviders() at app startup."
+
+---
+
 ## 1. Define Entity
 
 ```typescript
@@ -80,7 +108,7 @@ For multi-tenant apps where data belongs to a company/tenant/workspace:
 ### Step 1: Register Scope Provider (once at app startup)
 
 ```typescript
-// src/main.tsx or src/App.tsx
+// src/App.tsx
 import { registerScopeProvider } from '@donotdev/core';
 import { useCurrentCompanyStore } from './stores/currentCompanyStore';
 
@@ -665,9 +693,15 @@ transmission: {
 
 ## 7. Custom Fields & Schemas
 
-### Custom Field Types with UI Components
+A custom field type (when the requirement is not a built-in type) needs up to four things: **(1)** entity field with your custom `type` and `validation.schema`, **(2)** form component(s) so the field is editable, **(3)** optional **display** formatter so list/card/detail views render the value correctly, **(4)** optional **filter** so the field appears in EntityFilters with the right filter UI. All four are wired through a single `registerFieldType({ ... })` call.
+
+> **Custom type strings work out of the box.** Just use any string as the `type` — no declaration file or module augmentation needed. The framework accepts any string while still autocompleting built-in types.
+>
+> `CustomFieldOptionsMap` augmentation (see below) is only needed if you want type-checked `options.fieldSpecific` for your custom type.
 
-For custom field types that need custom UI components:
+### Form (required for editable fields)
+
+You must register a **controlled component** so the field appears in forms. Optionally register an **uncontrolled component** (e.g. for submit/reset-style fields).
 
 ```typescript
 import { registerFieldType, useController } from '@donotdev/crud';
@@ -687,7 +721,6 @@ function RepairOperationsField({
     control: control,
   });
 
-  // Use field.value and field.onChange for form state
   const value = (field.value as any) || [];
 
   return (
@@ -701,13 +734,13 @@ function RepairOperationsField({
   );
 }
 
-// Register UI component
+// Minimal registration (form only)
 registerFieldType({
   type: 'repairOperations',
   controlledComponent: RepairOperationsField,
 });
 
-// Then define schema in entity
+// Entity with schema
 export const carEntity = defineEntity({
   name: 'Car',
   collection: 'cars',
@@ -715,11 +748,10 @@ export const carEntity = defineEntity({
     repairs: {
       name: 'repairs',
       label: 'repairs',
-      type: 'repairOperations' as any,
+      type: 'repairOperations',
       visibility: 'admin',
       validation: {
         required: false,
-        // Custom Valibot schema - single source of truth
         schema: v.nullish(v.array(v.object({
           operation: v.string(),
           cost: v.number(),
@@ -730,10 +762,109 @@ export const carEntity = defineEntity({
 });
 ```
 
-**Important:**
-- Custom controlled components receive `control` prop, NOT `field` prop
-- You MUST use `useController` hook to get `field` and `fieldState`
-- Define schema in `validation.schema` - it's the single source of truth
+**Important:** Custom controlled components receive `control` prop, NOT `field` prop. You MUST use `useController` to get `field` and `fieldState`. Define schema in `validation.schema` — it's the single source of truth.
+
+### Display (list/card/detail)
+
+Without a **displayFormatter**, list/card/detail views show the raw value (or a fallback). To control how the value is rendered in read-only views, pass `displayFormatter` in the same `registerFieldType` call. Signature: `(value, fieldConfig, t, options?) => string | ReactNode`. Use `options?.compact` for list/card vs detail.
+
+```typescript
+// Example: format a custom object for display
+displayFormatter: (value, fieldConfig, t, options) => {
+  if (value == null) return '';
+  const arr = Array.isArray(value) ? value : [];
+  if (options?.compact) return `${arr.length} item(s)`;
+  return arr.map((item: any) => `${item.operation}: ${item.cost}`).join(', ') || '—';
+}
+```
+
+### Filter (EntityFilters)
+
+For the field to appear in the list/card **filters** section (EntityFilters), set **filterable: true** and **filterType** in `registerFieldType`. The filter type determines the filter UI:
+
+| filterType     | Use for |
+|----------------|--------|
+| `'text'`       | Free text search |
+| `'range'`      | Numbers, dates (min/max) |
+| `'select'`     | Single choice (e.g. enum) |
+| `'multiselect'`| Multiple choices |
+| `'address'`    | Address-based filter |
+| `'none'`       | Not filterable (omit or set filterable: false) |
+
+```typescript
+registerFieldType({
+  type: 'repairOperations',
+  controlledComponent: RepairOperationsField,
+  displayFormatter: (value, fieldConfig, t, options) => { /* ... */ },
+  filterable: true,
+  filterType: 'text',  // or 'range', 'select', 'multiselect', 'address', 'none'
+});
+```
+
+### Full example: form + display + filter
+
+One registration with form, displayFormatter, and filter:
+
+```typescript
+import { registerFieldType, useController } from '@donotdev/crud';
+import type { ControlledFieldProps } from '@donotdev/crud';
+import { defineEntity } from '@donotdev/core';
+import * as v from 'valibot';
+
+function StatusTierField({ fieldConfig, control, errors, t }: ControlledFieldProps) {
+  const { field, fieldState } = useController({ name: fieldConfig.name, control });
+  return (
+    <div>
+      <label>{t(fieldConfig.label)}</label>
+      <select value={field.value ?? ''} onChange={(e) => field.onChange(e.target.value)}>
+        <option value="">—</option>
+        <option value="basic">Basic</option>
+        <option value="premium">Premium</option>
+      </select>
+      {fieldState?.error && <span className="error">{fieldState.error.message}</span>}
+    </div>
+  );
+}
+
+registerFieldType({
+  type: 'statusTier',
+  controlledComponent: StatusTierField,
+  displayFormatter: (value) => (value ? String(value) : '—'),
+  filterable: true,
+  filterType: 'select',
+});
+
+export const productEntity = defineEntity({
+  name: 'Product',
+  collection: 'products',
+  fields: {
+    statusTier: {
+      name: 'statusTier',
+      label: 'statusTier',
+      type: 'statusTier',
+      visibility: 'guest',
+      validation: { schema: v.optional(v.picklist(['basic', 'premium'])) },
+    },
+  },
+});
+```
+
+### Typing custom field options
+
+To get type-checked `options.fieldSpecific` for custom types (e.g. `extractDistrictCode: boolean`), augment the framework's `CustomFieldOptionsMap` in your app:
+
+```typescript
+// e.g. in src/types/crud.d.ts or next to your entity
+import '@donotdev/core';
+declare module '@donotdev/core' {
+  interface CustomFieldOptionsMap {
+    'repairOperations': { maxItems?: number };
+    'isousou-address': { extractDistrictCode?: boolean };
+  }
+}
+```
+
+Then in entity fields you can use `type: 'repairOperations'` and `options: { fieldSpecific: { maxItems: 10 } }` without type errors or `as any`.
 
 ### Custom Schemas (No Custom UI)
 

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

@@ -112,23 +112,29 @@ This handles everything:
 
 ## Secrets (Stripe, OAuth, etc.)
 
-Server-side secrets go in `functions/.env`, not the app `.env`:
+Server-side secrets go in `functions/.env`, not the app `.env`.
+
+**We NEVER ask for secret keys.** You place them yourself:
 
 ```bash
 # functions/.env
 STRIPE_SECRET_KEY=sk_live_...
 STRIPE_WEBHOOK_SECRET=whsec_...
+SUPABASE_SERVICE_ROLE_KEY=eyJ...   # if using Supabase
 GITHUB_CLIENT_SECRET=...
 ```
 
-Push to Firebase Secret Manager:
+Then sync to your runtime and CI/CD:
 
 ```bash
-dndev sync-secrets
+dndev sync-secrets                    # Firebase Secret Manager / Vercel env
+dndev sync-secrets --target github    # GitHub Secrets (for CI/CD workflows)
 ```
 
 Secrets are auto-loaded by Cloud Functions at runtime. Never put server secrets in `VITE_*` variables — those are exposed to the browser.
 
+See [ENV_SETUP.md → Secrets Philosophy](./ENV_SETUP.md#secrets-philosophy) for the full policy.
+
 ---
 
 ## Cloud Run IAM (Technical Detail)

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

@@ -47,21 +47,26 @@ export const crud = createCrudFunctions(entities);
 
 ## Custom Functions
 
-**When writing custom functions, use `/server` imports:**
+**Use `createFunction` — handles config, validation, auth, rate limiting, metrics automatically:**
 
 ```typescript
-import { onCall } from 'firebase-functions/v2/https';
-import { FUNCTION_CONFIG } from '@donotdev/functions/firebase';
+import * as v from 'valibot';
+import { createFunction } from '@donotdev/functions/firebase';
 import { getFirebaseAdminFirestore } from '@donotdev/firebase/server';
-import { handleError } from '@donotdev/core/server';
 
-export const myFunction = onCall(FUNCTION_CONFIG, async (request) => {
+const schema = v.object({ productId: v.string() });
+
+export const getProductDetails = createFunction(schema, 'get_product_details', async (data, { uid }) => {
   const db = getFirebaseAdminFirestore();
-  // Your logic here
-  return { data: 'result' };
+  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

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

@@ -0,0 +1,234 @@
+# Setup: SOC2 Readiness
+
+**DoNotDev auto-enforces SOC2 baseline controls.** Zero config needed for the MVP. This guide covers advanced controls and audit verification.
+
+---
+
+## Zero-Config Baseline (Always On)
+
+When you wire `DndevSecurity` into your app, these controls activate automatically:
+
+| Control | Default | SOC2 Criteria |
+|---------|---------|---------------|
+| Structured audit logging (all CRUD + auth) | ✅ Automatic | CC7.1 |
+| Rate limiting (100 writes/min, 500 reads/min) | ✅ Automatic | CC6.6 |
+| Brute-force lockout (5 attempts → 15 min) | ✅ Automatic | CC6.1 |
+| Session timeout (8h idle) | ✅ Automatic | CC6.1 |
+| Field-level RBAC + visibility | ✅ Always on (entity config) | CC6.3 |
+| Supabase RLS / Firestore default-deny | ✅ By convention | CC6.3 |
+
+---
+
+## 1. Wire `DndevSecurity` (Required Once)
+
+```typescript
+// src/security.ts
+import { DndevSecurity } from '@donotdev/security/server';
+
+export const security = new DndevSecurity({
+  // Optional: override defaults
+  // rateLimit: { writesPerMin: 50, readsPerMin: 200 },
+  // lockout: { maxAttempts: 3, lockoutMs: 30 * 60 * 1000 },
+  // sessionTimeoutMs: 4 * 60 * 60 * 1000,
+
+  // Required for PII encryption (see § PII Encryption below)
+  // piiSecret: process.env.PII_SECRET,
+
+  // Optional: send anomaly alerts to your SIEM/Slack
+  // anomalyHandler: async (alert) => { await fetch(process.env.SIEM_WEBHOOK!, { method: 'POST', body: JSON.stringify(alert) }); },
+});
+```
+
+```typescript
+// src/main.ts (or app entry point)
+import { security } from './security';
+import { crudService } from './crud'; // your CrudService instance
+import { auth } from './auth';        // your SupabaseAuth or FirebaseSDK instance
+
+crudService.setSecurity(security);
+auth.setSecurity(security);
+```
+
+---
+
+## 2. PII Encryption (Opt-In — C1 Confidentiality)
+
+Required only for entities storing personal data (email, phone, SSN, health data, etc.).
+
+```typescript
+// entities/user.ts
+export const userEntity = defineEntity({
+  name: 'User',
+  collection: 'users',
+  security: {
+    piiFields: ['email', 'phone', 'dateOfBirth'], // Encrypted at rest with AES-256-GCM
+  },
+  fields: { /* ... */ },
+});
+```
+
+```bash
+# Add to .env (min 32 chars, generate with: openssl rand -hex 32)
+PII_SECRET=your-secret-key-min-32-chars-here
+```
+
+Pass to security:
+```typescript
+export const security = new DndevSecurity({
+  piiSecret: process.env.PII_SECRET,
+});
+```
+
+---
+
+## 3. MFA Enforcement (Opt-In — CC6.1)
+
+Enforce MFA for specific roles on sensitive entities:
+
+```typescript
+export const paymentEntity = defineEntity({
+  name: 'Payment',
+  collection: 'payments',
+  security: {
+    requireMfa: 'admin', // 'admin' | 'manager' | 'user'
+  },
+  fields: { /* ... */ },
+});
+```
+
+Enable MFA in your provider:
+- **Supabase:** Dashboard → Auth → Multi Factor Authentication → Enable TOTP
+- **Firebase:** Firebase Console → Authentication → Multi-factor Auth → Enable
+
+---
+
+## 4. Data Retention (Opt-In — P6 Privacy)
+
+```typescript
+export const auditLogEntity = defineEntity({
+  name: 'AuditLog',
+  collection: 'audit_logs',
+  security: {
+    retention: { days: 365 }, // Auto-flag records for purge after 1 year
+  },
+  fields: { /* ... */ },
+});
+```
+
+Run retention purge (e.g., in a scheduled Cloud Function):
+```typescript
+import { privacyManager } from '@donotdev/security/server';
+// privacyManager.shouldPurge(record.createdAt, retentionDays) → boolean
+```
+
+---
+
+## 5. Right to Erasure (GDPR Art. 17 / P8)
+
+```typescript
+import { DndevSecurity } from '@donotdev/security/server';
+
+// In your account deletion handler:
+await security.privacyManager.eraseUser(userId, async (uid) => {
+  // Your custom erasure logic per collection
+  await db.from('orders').update({ userId: null }).eq('userId', uid);
+  await db.from('profiles').delete().eq('id', uid);
+});
+```
+
+---
+
+## 6. Health Monitoring (Opt-In — A1 Availability)
+
+```typescript
+// src/client/health.ts
+import { HealthMonitor } from '@donotdev/security';
+
+const dbMonitor = new HealthMonitor({ failureThreshold: 3, successThreshold: 2, timeoutMs: 5000 });
+
+// Wrap all downstream DB calls through the circuit breaker
+export const safeQuery = (fn: () => Promise<unknown>) => dbMonitor.protect(fn);
+
+// Expose a health endpoint (Next.js example)
+// app/api/health/route.ts
+export async function GET() {
+  return Response.json({ status: dbMonitor.checkLiveness() });
+}
+```
+
+---
+
+## 7. Anomaly Detection (Opt-In — CC7.2)
+
+Triggered automatically when brute-force or bulk-delete thresholds are exceeded. Wire a handler to send alerts:
+
+```typescript
+export const security = new DndevSecurity({
+  anomalyHandler: async (alert) => {
+    // Send to Slack, PagerDuty, Datadog, etc.
+    await fetch(process.env.SLACK_WEBHOOK!, {
+      method: 'POST',
+      body: JSON.stringify({ text: `🚨 SOC2 Anomaly: ${alert.type} — ${alert.details}` }),
+    });
+  },
+});
+```
+
+---
+
+## 8. Audit Log Output
+
+Audit events write to `process.stdout` as NDJSON — pipe to your SIEM:
+
+```json
+{"timestamp":"2025-01-15T10:23:00.000Z","type":"crud.create","userId":"u_123","resource":"products","resourceId":"p_456","ip":"192.168.1.1"}
+{"timestamp":"2025-01-15T10:23:01.000Z","type":"auth.login.failure","userId":"unknown","resource":"auth","ip":"10.0.0.5","details":"brute_force_lockout"}
+```
+
+**Cloud Logging (Firebase / GCP):** Stdout is captured automatically.
+**Datadog:** Set `DD_LOGS_INJECTION=true` and pipe stdout to the Datadog agent.
+**Supabase:** Export `process.stderr` anomaly alerts to Logflare.
+
+---
+
+## SOC2 Readiness Check
+
+Run before any audit:
+
+```bash
+dn soc2                    # Scan current app
+dn soc2 --app my-app       # Scan specific app
+dn soc2 --json             # Machine-readable JSON output (CI/CD)
+dn soc2 --verbose          # Show details for passing checks too
+```
+
+**Exit codes:** `0` = all checks pass, `1` = one or more checks failed (CI-friendly).
+
+**Checks run:**
+
+| Check | Criteria | What It Looks For |
+|-------|----------|--------------------|
+| SecurityContext wired | CC6.1 | `DndevSecurity` in source |
+| PII encryption secret | C1 | `PII_SECRET` in env when `piiFields` defined |
+| Firestore default-deny | CC6.3 | `allow read, write: if false` in `firestore.rules` |
+| Supabase RLS | CC6.3 | `ENABLE ROW LEVEL SECURITY` in SQL migrations |
+| Audit logging | CC7.1 | `.audit()` / `AuditLogger` usage |
+| Rate limiting | CC6.6 | `rateLimit` / `DndevRateLimiter` usage |
+| Retention policies | P6 | `retention.days` in entity config |
+| Health monitoring | A1 | `HealthMonitor` or `/api/health` endpoint |
+| MFA enforcement | CC6.1 | `requireMfa` in sensitive entities |
+
+---
+
+## Coverage After Full Setup
+
+| SOC2 Criteria | Control | Status |
+|---------------|---------|--------|
+| CC6.1 Auth hardening | Lockout + session timeout + MFA | Framework-enforced |
+| CC6.3 Authorization | RBAC + field visibility + RLS/Firestore rules | Framework-enforced |
+| CC6.6 Rate limiting | Per-user sliding window | Framework-enforced |
+| CC7.1 Audit logging | All CRUD + auth events as NDJSON | Framework-enforced |
+| CC7.2 Anomaly detection | Auth failures + bulk ops threshold alerts | Opt-in handler |
+| A1 Availability | Circuit breaker + liveness probes | Opt-in `HealthMonitor` |
+| C1 Confidentiality | AES-256-GCM field encryption | Opt-in `piiFields` |
+| P1–P8 Privacy | Retention policies + right-to-erasure | Opt-in `retention` |

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

@@ -0,0 +1,124 @@
+# Setup: Supabase
+
+**From zero to a working Supabase backend: env, tables, RLS, and adapter behavior.**
+
+---
+
+## Step 1: Run Supabase Setup
+
+```bash
+dndev supabase:setup
+```
+
+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`
+
+**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**.
+
+---
+
+## 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).
+
+```bash
+dn generate sql
+```
+
+**What it does:**
+- Discovers entities (e.g. in `entities/` or your configured `--entity-dir`)
+- 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.
+
+---
+
+## Step 3: Apply Migrations
+
+After generating SQL:
+
+**Option A — Supabase CLI (recommended)**
+
+```bash
+supabase db push
+```
+
+(or `supabase migration up` if you manage migrations locally)
+
+**Option B — Dashboard**
+
+Copy the contents of the generated migration file into the SQL Editor in the Supabase Dashboard and run it.
+
+---
+
+## Step 4: 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.
+
+The **Supabase CRUD adapter** handles this automatically:
+
+| Direction | Behavior |
+|-----------|----------|
+| **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.
+
+---
+
+## Environment Variables
+
+**Client (Vite):** in `apps/<app>/.env`
+
+| Variable | Purpose |
+|----------|---------|
+| `VITE_SUPABASE_URL` | Project URL (public) |
+| `VITE_SUPABASE_ANON_KEY` | Anon key (public, 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.).
+
+See [ENV_SETUP.md](./ENV_SETUP.md) for where to put secrets.
+
+---
+
+## Storage (Optional)
+
+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.
+
+---
+
+## Hosting the frontend
+
+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.
+
+**We recommend:**
+
+- **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.
+
+**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.
+
+---
+
+## Local Development
+
+- **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.
+
+---
+
+## Summary
+
+**`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.

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

@@ -1,12 +1,16 @@
 # Setup: Themes
 
-**Most is pre-configured.** Override CSS variables in `src/themes.css`. Framework handles theme switching, auto-computed colors.
+**Single source of truth:** `src/themes.css`. Import it from `globals.css`; do not set font/color overrides in globals. Framework handles theme switching.
+
+**Default essence = SaaS** (Inter, neutral). Optional essences (Brutalist, Luxury) are in the scaffold; they do **not** apply until you set the class on `<html>` (e.g. `class="brutalist"`) or use the theme switcher.
+
+**Reference:** Copy Brutalist/Luxury blocks from `guides/dndev/essences_reference.css` into your `src/themes.css` if you need them. Default-essence fonts (Inter, Space Grotesk, Playfair, Roboto) are bundled via `@donotdev/ui`; no Google Fonts, no `public/fonts/` required.
 
 ---
 
 ## Standard Use
 
-**File:** `src/themes.css` (scaffolded with all variables)
+**File:** `src/themes.css` (scaffolded with light, dark, and optional Brutalist/Luxury)
 
 **Override colors:**
 ```css