@donotdev/cli 0.0.14 → 0.0.16

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

@@ -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 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`
+
+**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 `dndev setup supabase`, 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 setup supabase`** → 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

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

@@ -0,0 +1,176 @@
+# Setup: Vercel
+
+**From zero to deployed: Vercel hosting + API routes with Firebase data layer.**
+
+---
+
+## Architecture
+
+Vercel is your **hosting and API platform** — it serves your frontend and runs serverless API routes.
+Firebase is your **data layer** — Firestore (CRUD), Firebase Auth (users), Firebase Storage (files).
+
+The framework generates API routes as Vercel Serverless Functions that talk to Firebase on the backend.
+
+---
+
+## Step 1: Create Firebase Project (Data Layer)
+
+Even though you deploy to Vercel, you still need Firebase for data.
+
+1. Go to [Firebase Console](https://console.firebase.google.com) → Create a project
+2. Enable **Authentication** → Email/Password (+ OAuth providers if needed)
+3. Enable **Cloud Firestore** → Create Database → select region
+4. Enable **Storage** if your app uploads files
+
+Get the Firebase web config from: **Project Settings → General → Your apps → Web app → SDK config**.
+
+---
+
+## Step 2: Run Setup
+
+```bash
+dndev setup firebase
+```
+
+This writes Firebase SDK config to your app's `.env`. The `overlay-vercel` providers.ts initializes the Firebase client SDK.
+
+---
+
+## Step 3: Configure Vercel
+
+1. Create a [Vercel](https://vercel.com) account and link your Git repo
+2. Import the project in Vercel Dashboard
+3. Set the **Root Directory** to `apps/<your-app>` (or leave blank if monorepo auto-detected)
+4. Set **Framework Preset** to Vite (or Next.js if using Next)
+
+**Environment Variables** (in Vercel Dashboard → Settings → Environment Variables):
+
+Copy your Firebase vars from `.env`:
+- `VITE_FIREBASE_API_KEY`
+- `VITE_FIREBASE_PROJECT_ID`
+- `VITE_FIREBASE_AUTH_DOMAIN`
+- `VITE_FIREBASE_STORAGE_BUCKET`
+- `VITE_FIREBASE_MESSAGING_SENDER_ID`
+- `VITE_FIREBASE_APP_ID`
+
+For Next.js apps, use `NEXT_PUBLIC_` prefix instead of `VITE_`.
+
+**Server secrets** (for API routes):
+- `STRIPE_SECRET_KEY`
+- `STRIPE_WEBHOOK_SECRET`
+- Any OAuth client secrets
+
+---
+
+## Step 4: API Routes (Functions)
+
+Your backend functions are in `functions/` and deploy as Vercel Serverless Functions.
+
+```
+functions/
+├── src/
+│   ├── auth/        # Auth endpoints (signup, login, etc.)
+│   ├── billing/     # Stripe endpoints (checkout, webhook, etc.)
+│   ├── crud/        # CRUD endpoints (create, read, update, delete)
+│   └── oauth/       # OAuth callback handlers
+├── vercel.json      # Route configuration
+├── tsconfig.json
+└── package.json
+```
+
+Functions use the Firebase Admin SDK on the server side to access Firestore, verify auth tokens, etc.
+
+---
+
+## Step 5: Deploy
+
+**Option A — Git push (recommended)**
+
+Push to your connected branch. Vercel auto-deploys.
+
+```bash
+git push origin main
+```
+
+**Option B — Vercel CLI**
+
+```bash
+npx vercel --prod
+```
+
+---
+
+## Environment Variables
+
+| File | What Goes Here | Loaded By |
+|------|---------------|-----------|
+| `apps/<app>/.env` | Firebase config, license key, Stripe publishable key | Vite/Next.js (dev + build) |
+| `apps/<app>/.env.local` | Local overrides (gitignored) | Vite/Next.js (overrides .env) |
+| `apps/<app>/.env.production` | Production overrides | Vite/Next.js (build --mode production) |
+| `functions/.env` | Server secrets: STRIPE_SECRET_KEY, OAuth secrets | API routes runtime |
+| Vercel Dashboard | All production env vars (client + server) | Vercel runtime |
+
+**Client vars** (browser-safe): `VITE_*` or `NEXT_PUBLIC_*` prefix.
+**Server vars** (secrets): No prefix needed in Vercel Dashboard — only accessible in API routes.
+
+---
+
+## Local Development
+
+```bash
+bun dev
+```
+
+The app runs locally, talking to your Firebase project. API routes can be tested with:
+
+```bash
+vercel dev
+```
+
+Or use Firebase emulators for fully local development:
+
+```bash
+dndev emu start
+```
+
+---
+
+## Secrets
+
+Server-side secrets go in `functions/.env` locally and in Vercel Dashboard for production.
+
+**We NEVER ask for secret keys.** You place them yourself:
+
+```bash
+# functions/.env
+STRIPE_SECRET_KEY=sk_live_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+```
+
+Then add the same values in Vercel Dashboard → Settings → Environment Variables.
+
+See [ENV_SETUP.md → Secrets Philosophy](./ENV_SETUP.md#secrets-philosophy) for the full policy.
+
+---
+
+## Troubleshooting
+
+**"Firebase config not loading"**
+→ Check `.env` is in your **app directory** (`apps/<app>/.env`), not repo root
+→ Vite vars must start with `VITE_`, Next.js vars with `NEXT_PUBLIC_`
+
+**"401 / Permission denied on API routes"**
+→ Check Firebase service account key is configured in Vercel env vars
+→ Verify `GOOGLE_APPLICATION_CREDENTIALS` or inline credentials in API routes
+
+**"CORS error"**
+→ Vercel handles CORS for same-origin requests automatically
+→ For cross-origin: add CORS headers in your API route handler
+
+**"Build fails on Vercel"**
+→ Check Root Directory is set to your app directory
+→ Ensure `package.json` has correct `build` script
+
+---
+
+**`dndev setup firebase` → configure Vercel project → set env vars → `git push`. Vercel deploys automatically.**

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

@@ -226,18 +226,14 @@ navigate('/products', {
 
 ### 5. Query Parameters
 
-**✅ Use framework useSearchParams:**
+**✅ Use framework useSearchParams (read-only, returns URLSearchParams directly):**
 ```tsx
 import { useSearchParams } from '@donotdev/ui/routing';
 
 function ProductList() {
-  const [searchParams, setSearchParams] = useSearchParams();
+  const searchParams = useSearchParams();
   const page = searchParams.get('page') || '1';
-  
-  const handlePageChange = (newPage: string) => {
-    setSearchParams({ page: newPage });
-  };
-  
+
   return <div>Page: {page}</div>;
 }
 ```
@@ -478,8 +474,8 @@ navigate('/products', { replace: true });
 // Route params
 const id = useRouteParam('id');
 
-// Query params
-const [searchParams, setSearchParams] = useSearchParams();
+// Query params (read-only, returns URLSearchParams directly)
+const searchParams = useSearchParams();
 const page = searchParams.get('page');
 
 // Navigation menu

package/templates/root-consumer/guides/dndev/essences_reference.css.example

@@ -0,0 +1,174 @@
+/**
+ * Reference: Framework essences (Brutalist, Luxury).
+ * Copy the blocks you need into your app's src/themes.css.
+ * Default essence = SaaS (Inter); these do not apply until you set the class on <html>.
+ *
+ * Fonts: Space Grotesk (Brutalist), Playfair Display (Luxury), Inter, Roboto are bundled in @donotdev/ui (no external requests).
+ */
+
+/** =========================================================================
+ *  Brutalist — Industrial, monospace body, Space Grotesk headlines, orange/black.
+ *  Set <html class="brutalist"> to apply.
+ *  ========================================================================= */
+.brutalist {
+  --theme-icon: 'Construction';
+  --theme-label: 'Brutalist';
+  --theme-is-dark: 1;
+
+  /* 1. Core Colors - Black + white + industrial orange */
+  --background: #000000;
+  --foreground: #ffffff;
+  --primary: #f97316;
+  --secondary: #ffffff;
+  --accent: #f97316;
+
+  /* 2. Semantic */
+  --success: #22c55e;
+  --warning: #f97316;
+  --destructive: #dc2626;
+
+  /* 3. Surfaces - Dark, industrial */
+  --muted: #111111;
+  --muted-foreground: #888888;
+  --border: #ffffff;
+  --input: #111111;
+  --ring: #f97316;
+  --card: #000000;
+  --card-foreground: #f97316;
+  --popover: #000000;
+  --popover-foreground: #ffffff;
+  --surface-1: #0a0a0a;
+
+  /* 4. Text on Colors */
+  --primary-foreground: #ffffff;
+  --secondary-foreground: #000000;
+  --accent-foreground: #000000;
+  --success-foreground: #ffffff;
+  --warning-foreground: #000000;
+  --destructive-foreground: #ffffff;
+
+  /* 5. Radius - Hard zero */
+  --radius-interactive: 0;
+  --radius-surface: 0;
+  --radius-floating: 0;
+
+  /* 6. Typography - Monospace for body, Space Grotesk 700 for headings */
+  --font-family: var(--font-mono);
+  --font-headline: "Space Grotesk", var(--font-sans);
+  --font-weight-semibold: 700;
+  --font-weight-bold: 700;
+
+  /* 7. Borders */
+  --border-width: 2px;
+  --border-huge: 4px;
+
+  /* 8. Shadows — flat by default, hard offset on interactive */
+  --shadow-color: var(--foreground);
+  --shadow-sm: none;
+  --shadow-md: none;
+  --shadow-xl: 8px 8px 0px 0px var(--shadow-color);
+  --shadow-cta: 20px 20px 0px 0px var(--shadow-color);
+
+  /* 9. Per-variant shadows — only at xl level (elevated/clickable) */
+  --shadow-primary: none;
+  --shadow-primary-xl: 8px 8px 0px 0px var(--background);
+  --shadow-secondary: none;
+  --shadow-secondary-xl: 8px 8px 0px 0px var(--primary);
+
+  /* 10. Header padding for hard-offset shadows */
+  --header-shadow-padding: 0.75rem;
+}
+
+/* Body - grid background */
+.brutalist body {
+  background-color: var(--background);
+  background-image:
+    linear-gradient(#111 1px, transparent 1px),
+    linear-gradient(90deg, #111 1px, transparent 1px);
+  background-size: 40px 40px;
+}
+
+/* Uppercase headings (both native elements and Text component levels) */
+.brutalist {
+  :is(h1, h2, h3, h4, h5, h6),
+  [data-level^='h'] {
+    text-transform: uppercase;
+  }
+}
+
+/* Flat surface - no gradient glow */
+.brutalist .dndev-surface { background: var(--card); }
+.brutalist .dndev-surface[data-variant='outline'] { border: var(--border-width) solid var(--border); }
+
+.brutalist .dndev-card[data-variant='outline'] {
+  background: transparent;
+  box-shadow: none;
+}
+
+
+/** =========================================================================
+ *  Luxury — Playfair Display headlines, gold/cream, warm shadows.
+ *  Set <html class="luxury"> to apply.
+ *  ========================================================================= */
+.luxury {
+  --theme-icon: 'Gem';
+  --theme-label: 'Luxury';
+  --theme-is-dark: 0;
+
+  /* 1. Core Colors */
+  --background: #faf8f5;
+  --foreground: #1c1917;
+  --primary: #b45309;
+  --secondary: #fef3c7;
+  --accent: #92400e;
+
+  /* 2. Semantic */
+  --success: #15803d;
+  --warning: #b45309;
+  --destructive: #b91c1c;
+
+  /* 3. Surfaces */
+  --muted: #fef9c3;
+  --muted-foreground: #78716c;
+  --border: #e7e5e4;
+  --border-hairline: 1px;
+  --input: #ffffff;
+  --ring: #b45309;
+  --card: #ffffff;
+  --card-foreground: #1c1917;
+  --popover: #ffffff;
+  --popover-foreground: #1c1917;
+  --surface-1: #faf8f5;
+
+  /* 4. Text on Colors */
+  --primary-foreground: #ffffff;
+  --secondary-foreground: #1c1917;
+  --accent-foreground: #ffffff;
+  --success-foreground: #ffffff;
+  --warning-foreground: #1c1917;
+  --destructive-foreground: #ffffff;
+
+  /* 5. Radius */
+  --radius-interactive: 0.375rem;
+  --radius-surface: 0.5rem;
+  --radius-floating: 0.5rem;
+
+  /* 6. Typography — lighter weights, serif headlines */
+  --font-family: var(--font-sans);
+  --font-headline: 'Playfair Display', var(--font-serif);
+  --font-weight-normal: 300;
+  --font-weight-medium: 400;
+  --font-weight-semibold: 500;
+  --font-weight-bold: 600;
+
+  /* 7. Spacing — generous, one notch above expressive */
+  --gap-sm: 0.75rem;
+  --gap-md: 1.5rem;
+  --gap-lg: 3rem;
+
+  /* 8. Shadows — warm gold-tinted, soft diffused */
+  --shadow-color: color-mix(in oklab, #b45309 8%, transparent);
+  --shadow-sm: 0 1px 3px var(--shadow-color);
+  --shadow-md: 0 4px 12px var(--shadow-color);
+  --shadow-xl: 0 8px 24px var(--shadow-color);
+}

package/templates/root-consumer/guides/wai-way/WAI_WAY_CLI.md.example

@@ -168,18 +168,17 @@ Present completed spec summary:
 **READ:**
 - `guides/wai-way/page_patterns.md` - Page structure patterns
 
-```bash
-# Create new app
-dndev create-app my-app --preset [from spec]
+**`dndev` is an installed CLI — run directly, never via `bunx` or `npx`.**
 
-# Install dependencies
-cd my-app && bun install
+```bash
+# Create new app (interactive wizard — no --preset flag, it prompts you)
+dndev create-app
 
-# Start emulators
+# Start emulators (if Firebase backend was selected)
 dndev emu start
 
-# Verify it runs
-bun dev
+# Start the dev server
+dndev dev
 ```
 
 ### Step 1.1: Create Page Files

package/templates/root-consumer/guides/wai-way/agents/builder.md.example

@@ -31,6 +31,10 @@ core_principles:
   - HARDCODE strings first - validate UX before i18n
   - Use framework components only - no custom CSS
   - Trust component defaults
+  - **70/30 Hierarchy:** Use `primary` variant for the North Star action; `outline`/`ghost` for others.
+  - **Benefit-First Copy:** For Heros/Cards, translate technical features into outcomes (e.g., 'Optimize Your Fleet' vs 'Manage Cars').
+  - **Success Intent:** Trust framework defaults for CRUD (automatic toasts/loaders). Only propose custom redirects or celebratory components for the 'North Star' action or if the user asks for more polish.
+  - **Spec Drift:** If you must deviate from the spec (field types, logic), log it in `spec_changes.md`. Do NOT modify `spec_template.md` directly.
 
 crud_pattern:
   list_page: |
@@ -83,5 +87,11 @@ Rules:
 3. HARDCODE all strings (no i18n yet)
 4. Use framework components only
 
+**Apply UX Mandates:**
+- **Visual Anchor:** Every page must have ONE clear primary focus (Hero or Main Card).
+- **Mobile First:** Ensure all touch targets are > 44px.
+- **Kano Filter:** Use 'Benefit' copy for marketing/dashboard pages. Use 'Utility' copy for forms.
+- **Success Intent:** Trust framework defaults. Only propose custom redirects/celebration for the 'North Star' action.
+
 Build each page following the scaffolded patterns.
 ```