@donotdev/cli 0.0.14 → 0.0.16

package/templates/root-consumer/AI.md.example

@@ -4,147 +4,68 @@
 
 ## What To Do Right Now
 
-1. **Verify MCP is working.** Try calling `list_features()`. If it works, you're good. If not:
-   - **Cursor:** Settings → Tools & MCP → toggle "donotdev" ON. MCP only works in Composer mode (`Cmd/Ctrl+I`).
-   - **Claude Code / Windsurf:** Auto-connects from `.mcp.json`. If broken, check `bun` is in PATH.
-2. **Check environment setup.** Ask the user: "Have you run `bun install`? Run `dndev dev` and open the app — the homepage has setup steps for Git, Firebase, and .env."
-3. Call `start_phase(0)` — begin **Phase 0: BRAINSTORM**
-4. Follow each phase in order. Do not skip phases.
-
-## Environment Variables — Where They Go
-
-**Vite loads `.env` from the app directory only. NOT from the repo root.**
-
-| File | What Goes Here |
-|------|---------------|
-| `apps/<app>/.env` | Firebase config, license key, Stripe publishable key, all `VITE_*` vars |
-| `apps/<app>/.env.local` | Local overrides (gitignored) |
-| `apps/<app>/.env.staging` | Staging Firebase config (used by `dndev staging`) |
-| `functions/.env` | Server-side secrets: `STRIPE_SECRET_KEY`, OAuth client secrets |
-| Root `.env` | **Not read by Vite.** Reference only. |
-
-If the user says their license key or Firebase config "doesn't work", check which `.env` file they put it in. It must be in `apps/<app>/.env`, not the root.
+1. **Verify MCP is working.** Call `list_features()`. If it fails, run `get_guide("AGENT_START_HERE")` for IDE-specific setup.
+2. Call `start_phase(0)` — begin **Phase 0: BRAINSTORM**
+3. Follow each phase in order. Do not skip phases.
 
 ## The 5 Phases
 
 | Phase | Name | What Happens |
 |-------|------|-------------|
-| 0 | **BRAINSTORM** | Ask questions, understand requirements deeply, produce validated spec |
+| 0 | **BRAINSTORM** | Ask questions, understand requirements, produce validated spec |
 | 1 | **SCAFFOLD** | Create all routes and page stubs from spec |
 | 2 | **ENTITIES** | Define all data models (fields, access, visibility) |
 | 3 | **COMPOSE** | Build pages with framework components (hardcode strings) |
-| 4 | **CONFIGURE** | Config, test, polish, optional i18n |
-
-Each phase has a blueprint in `guides/wai-way/blueprints/` — read it before starting the phase.
+| 4 | **CONFIGURE** | Config, test, polish, i18n. Run `/grill` and `/techdebt` before shipping |
 
-For large projects, you can scope phases to a module (e.g., "user-management", "billing").
-
-## The Workflow Per Phase
+## Workflow Per Phase
 
 ```
-start_phase(N)          → get blueprint + context + lessons from previous sessions
-  ↓
-work                    → follow blueprint, use lookup_symbol for every component
+start_phase(N)          → get blueprint + persona + context + lessons
   ↓
-complete_phase(files)   → validate conventions + symbol usage + submit for review
+work                    → follow blueprint, lookup_symbol for every component
   ↓
-[user reviews]          → user confirms or requests changes
+complete_phase(files)   → validate conventions + symbol usage → submit for review
   ↓
-approve_phase()         → phase is done, move to next
+approve_phase()         → phase done, move to next
 ```
 
-## How To Use Components Without Hallucinating
+## Component Usage — Non-Negotiable
 
-**CRITICAL:** Never guess component props. Always look up the actual TypeScript types first.
+**Never guess component props.** Call `lookup_symbol({ symbol: "ComponentName" })` before writing ANY `@donotdev` component. Every call is tracked — `complete_phase` flags components used without lookup.
 
-**With MCP (auto-configured):**
-```
-lookup_symbol({ symbol: "DataTable" })   → returns real TypeScript interface
-lookup_symbol({ symbol: "Card" })        → returns real TypeScript interface
-```
+Without MCP: read `.d.ts` files directly from `node_modules/@donotdev/*/dist/`.
 
-Every `lookup_symbol` call is tracked. When you call `complete_phase`, it checks that every @donotdev component you used was looked up first. Components used without lookup are flagged.
+## CLI Commands
 
-**Without MCP:**
-Read the `.d.ts` file directly:
-```
-node_modules/@donotdev/crud/dist/index.d.ts    → CRUD components
-node_modules/@donotdev/ui/dist/index.d.ts      → UI components
-node_modules/@donotdev/core/dist/index.d.ts    → Core utilities
-```
+`dndev` is an **installed CLI** (globally via `npm install -g @donotdev/cli`). Run it directly — **never** use `bunx dndev` or `npx dndev`.
+
+| Command | What it does |
+|---------|-------------|
+| `dndev create-app` | Interactive wizard — creates a new app in the monorepo |
+| `dndev dev` | Start the dev server (Vite/Next.js via Turbo) |
+| `dndev emu start` | Start Firebase emulators |
+| `dndev deploy` | Deploy to production |
+| `dndev setup firebase` | Configure Firebase project + .env |
+| `dndev setup supabase` | Configure Supabase project + .env |
+
+`dndev create-app` is **interactive** — it prompts for builder (Vite/Next.js/Expo), backend (Firebase/Supabase/none), and features. There is no `--preset` flag.
+
+## Rules
+
+- **ESM only** — never `require()`
+- **RTL safe** — use `start`/`end`, never `left`/`right`
+- **Import order** — React → vendors → @donotdev → relative
+- **Framework-first** — if something's missing, say what and stop
+- **No .md file creation** — never create documentation/analysis/summary .md files unless explicitly asked. Session notes go in `.dndev/`
+- **Follow existing patterns** — the scaffolded files ARE your documentation
+
+## MCP Tools
+
+Call `get_guide("AGENT_START_HERE")` for the full tool reference, IDE setup, env var guide, and fallback instructions.
+
+Key tools: `start_phase` · `complete_phase` · `approve_phase` · `lookup_symbol` · `get_guide` · `get_guideline` · `search_framework` · `list_features` · `record_lesson`
+
+## Security Gate
 
-## Supported IDEs
-
-MCP gives the AI agent real TypeScript types instead of hallucinated props. Config files are auto-created by `dndev init`.
-
-| IDE | Config | Setup |
-|-----|--------|-------|
-| **Claude Code** | `.mcp.json` | Auto-connects. Nothing to do. |
-| **Windsurf** | `.mcp.json` | Auto-connects. Nothing to do. |
-| **Cursor** | `.cursor/mcp.json` | Settings → Tools & MCP → toggle "donotdev" ON. **MCP only works in Composer mode** (`Cmd/Ctrl+I`). |
-| **Gemini CLI** | `.gemini/settings.json` | Auto-connects. Nothing to do. |
-
-**If MCP tools aren't available**, guide the user:
-1. Check `bun` is in PATH (`which bun`)
-2. **Cursor:** Must be in Composer mode (`Cmd/Ctrl+I`) and server toggled ON
-3. Check MCP logs: `Cmd/Ctrl+Shift+U` → Output → "MCP Logs"
-
-**Without MCP (ChatGPT, Copilot, etc.):** Read blueprints from `guides/wai-way/blueprints/` and types from `node_modules/@donotdev/*/dist/*.d.ts`. You lose symbol tracking and convention enforcement.
-
-## MCP Tools (13 — Pre-Configured)
-
-MCP config files are auto-created in `.mcp.json` / `.cursor/mcp.json` / `.gemini/settings.json`. **You must enable the server in your IDE settings** (see "Supported IDEs" above). Once enabled, your IDE connects automatically.
-
-| Tool | What It Does |
-|------|-------------|
-| `start_phase(N)` | Begin a phase — returns blueprint, agent persona, context, and lessons |
-| `complete_phase({ files })` | Validate conventions + symbol usage + submit for review (does NOT auto-advance) |
-| `approve_phase()` | User approved — phase is done, advance to next |
-| `get_phase_status()` | Current phase, symbols tracked, review status |
-| `lookup_symbol("X")` | Get actual TypeScript types — tracked per phase |
-| `get_guide("CRUD")` | Fetch framework setup guides |
-| `get_guideline("styling:colors")` | Fetch architecture guidelines (supports sections) |
-| `search_framework("keyword")` | Search across all guides and type definitions |
-| `list_features()` | List all framework packages with summaries |
-| `record_lesson("text")` | Save to project memory (returned on next start_phase) |
-| `init_implementation({ from_spec: true })` | Create `.dndev/implementation.md` to track progress |
-| `update_progress({ item: "...", done: true })` | Tick/untick items in implementation checklist |
-| `get_progress()` | Read implementation progress stats |
-| `get_project_history()` | Get captain's log with full session history |
-
-## Convention Enforcement
-
-`complete_phase` checks for:
-- Inline styles (`style={{}}`) — use className
-- fontSize/font-size — use Text levels or Card props
-- textAlign left/right — use start/end for RTL
-- require() — use ESM imports
-- Manual date formatting — use formatDate() from @donotdev/core
-- Import order — React > vendors > @donotdev > relative
-- Unverified components — @donotdev components used without lookup_symbol
-
-## Without MCP — Manual Fallback
-
-Read the blueprints directly:
-
-| Phase | Read This |
-|-------|-----------|
-| 0 | `guides/wai-way/blueprints/0_brainstorm.md` |
-| 1 | `guides/wai-way/blueprints/1_scaffold.md` |
-| 2 | `guides/wai-way/blueprints/2_entities.md` |
-| 3 | `guides/wai-way/blueprints/3_compose.md` |
-| 4 | `guides/wai-way/blueprints/4_configure.md` |
-
-Agent personas: `guides/wai-way/agents/` (extractor, architect, builder, polisher)
-
-## Golden Rule
-
-> **The scaffolded files ARE your documentation.**
-> Read the existing code. Follow the pattern. Extend it. Never invent from scratch.
-
-## Key References
-
-- `guides/wai-way/spec_template.md` — App specification template (Phase 0 output)
-- `guides/wai-way/entity_patterns.md` — Common entity schemas
-- `guides/wai-way/page_patterns.md` — Common page structures
-- `guides/dndev/` — Framework setup guides (CRUD, Auth, Components, etc.)
+Before production: run `dn soc2`. See `get_guide("SOC2")` for details.

package/templates/root-consumer/CLAUDE.md.example

@@ -1,134 +1 @@
-# Agent Behavior - All Projects
-
-**⚠️ CRITICAL: READ FIRST - ENFORCE ALWAYS ⚠️**
-
-**NEVER act without explicit command. Questions = analysis only.**
-**Commands = execute immediately. No assumptions, no auto-actions.**
-
----
-
-## ⚠️ WORKING MODE: Consumer App Development
-
-**YOU ARE IN:** Consumer App Development Mode
-
-**Location:** Consumer repository (scaffolded by `dndev init`)
-
-**Your Role:**
-- **Creating with framework** (Mode 3): Build new app features
-- **Tweaking framework app** (Mode 4): Modify existing app features
-
-**CLI:** `dndev` (public CLI, installed globally via `npm install -g @donotdev/cli`)
-
-**Workflow:**
-1. `/design [requirement]` → Architect designs solution
-2. `/build [requirement]` → Prompt Engineer + Coder implement
-3. Iterate with WAI-WAY agents
-
-**Reference:** [Modes Guide](https://github.com/donotdev/framework/blob/main/docs/development/MODES.md) | Framework guides in `guides/dndev/`
-
-**⚠️ IMPORTANT:**
-- Use ONLY published `@donotdev/*` packages
-- Cannot modify framework internals
-- If framework needs changes, work in the framework monorepo (this repo)
-
----
-
-**PRIME DIRECTIVE: PRECISION OVER SPEED.**
-
-## **Correctness is non-negotiable. Concise, even at the cost of grammar. Never guess, every output must be verifiable. Check every assumption against actual codebase, documentation or user. If ambiguity exists, ask. No exceptions.**
-
-## Identity & Persona Mandate
-
-**Human user** - Architect, Product Owner, Product Manager
-**AI assistant** - Lead Developer, UX/UI Designer, Expert Adviser
-
-**Objective:** Multi-faceted, critical advisor applications. Blunt, on-point feedback driving applications quality. No sugarcoating.
-
-Persona adapts to task:
-
-- **Lead Developer:** Implementation, code quality, patterns respect
-- **UX/UI Designer:** UX/UI considerations
-- **Expert Adviser:** Strategic feedback, trade-offs
-
-## Communication Style
-
-Extremely concise. Sacrifice grammar for concision while maintaining correctness.
-Never guess, always search (codebase, documentation, online) or ask.
-
-**Response hygiene:**
-
-- NO MIRRORING - never echo user's tone, mood, or phrasing
-- ALWAYS DELIVER facts, analysis, decisions; no motivation or encouragement
-- ALWAYS and ONLY execute the task at hand
-
-**Examples:**
-
-- ❌ "I will now proceed to update the configuration file"
-- ✅ "Updating config"
-- ❌ "Added support for dark mode theming"
-- ✅ "add dark mode support"
-- ❌ "I have implemented the feature you requested"
-- ✅ "Done"
-
-**ALWAYS DO**
-
-- Brutal, blunt honest feedback
-- Challenge ideas aggressively
-- Provide pros/cons/trade-offs with evidence/research/studies
-- Suggest better approaches
-- Extremely concise
-- **NEVER act without explicit command** - Questions are for analysis only
-- **NEVER ask follow-up questions** like "Do you want me to...?" or "Should I...?"
-
-## Plans
-
-At end of each plan, list unresolved questions (if any). Extremely concise.
-
-**Example:**
-
-```
-**Unresolved:**
-- Auth strategy ? (google or more?)
-- Backend target? (Vercel vs Firebase)
-```
-
-## Environment Constraints
-
-## General Principles
-- **Code reading/writing:** Be critical and concise/precise. Question redundant systems, conflicting logic, unnecessary complexity. You need to **ANALYZE** code.
-- **Conventions:** Always follow project's conventions when updating/adding/fixing files
-
-## Component Usage - MCP REQUIRED
-
-**BEFORE writing ANY @donotdev component:**
-
-1. Call `lookup_symbol({ symbol: "ComponentName" })`
-2. Read the actual props from the returned TypeScript interface
-3. Use ONLY those props
-
-**NEVER guess props. NEVER use props from memory/training.**
-
-If MCP tools unavailable → STOP and tell user to enable MCP.
-
-**Key MCP tools:**
-- `lookup_symbol` — get actual TypeScript types from `.d.ts`
-- `get_guide` — fetch framework setup guides (CRUD, Auth, etc.)
-- `get_guideline` — fetch architecture guidelines
-- `search_framework` — search across all guides and symbols
-
-## Project Args & Gotchas
-
-- **`.dndev/args.json`** — Per-project config (platform, strictness, features, region). All features ON by default. Phase 0 narrows down. Edit `strictness` to control validation: `enforced` (default) | `warnings` | `permissive`.
-- **`guides/dndev/GOTCHAS.md`** — Common mistakes, phase-tagged. Read directly or loaded by MCP `start_phase()`.
-- **Without MCP:** Both files are plain JSON/markdown — any agent reads them directly. MCP automates filtering + enforcement but is not required.
-
-## WAI-WAY Workflow
-
-**Read `AI.md` at the project root for the full workflow.**
-
-For each phase (0=BRAINSTORM, 1=SCAFFOLD, 2=ENTITIES, 3=COMPOSE, 4=CONFIGURE):
-
-1. `mcp:start_phase(N)` — returns blueprint, context, lessons, project args, and phase-relevant gotchas
-2. Work — follow blueprint, call `lookup_symbol` before using any component
-3. `mcp:complete_phase({ files })` — validates conventions + symbol usage (respects `strictness`), submits for review
-4. `mcp:approve_phase()` — user approves, phase is done
+Enforce AI.md

package/templates/root-consumer/CONVENTIONS.md.example

@@ -0,0 +1 @@
+Enforce AI.md

package/templates/root-consumer/GEMINI.md.example

@@ -0,0 +1 @@
+Enforce AI.md

package/templates/root-consumer/firebase.json.example

@@ -314,7 +314,7 @@
         "**/*.test.ts",
         "**/__tests__/**"
       ],
-      "runtime": "nodejs20"
+      "runtime": "nodejs22"
     }
   ],
   "firestore": {

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

@@ -9,6 +9,26 @@
 
 ---
 
+## Getting Started (for humans)
+
+**Canonical flow:** The showcase app’s **Get Started** page is the single source of truth: `apps/showcase/src/pages/GetStartedPage.tsx` and `apps/showcase/src/pages/locales/getstarted_*.json`. Below is the same flow in short form.
+
+1. **P0 — Prerequisites**
+   - **Runtime:** **Node.js 24** (nodejs.org) and **Bun 1.3+** (bun.sh). Both required.
+   - **IDE:** Any IDE (Cursor, VS Code, Windsurf, etc.). Need help? Use the collapsible “Need help setting up?” on the Get Started page.
+2. **Install our CLI and create your project’s monorepo**
+   - `npm install -g @donotdev/cli`
+   - `dndev init my-app`
+3. **Open the repo in your IDE, terminal, bun install**
+   - Start your IDE in that repo, open the terminal: `cd my-app` → `bun install`
+4. **Enable MCP, then read AI.md and follow the flow**
+   - Talk with your agent; ask it to load the MCP (Cursor: Ctrl+Shift+P → “MCP Server” → enable “donotdev”; other IDEs: see “How to enable MCP” collapsible on the Get Started page).
+   - Then have the agent read the root **`AI.md`** and this file (**`guides/dndev/AGENT_START_HERE.md`**). Follow the phases.
+5. **AI helps with provider; cd there, bun install, run**
+   - AI helps you choose and set up your provider (Firebase, Supabase, or custom). Then `cd` into the app directory if needed, `bun install`, and `dndev dev` / `dndev build` / `dndev deploy`.
+
+---
+
 ## First Thing to Call: list_features()
 
 Call **`list_features()`** before designing or coding. It lists all framework packages with a one-line summary from each README (templates, core, ui, auth, billing, etc.). Use it so you don't reinvent what the framework already provides (blog, CRUD, billing, legal pages, etc.).
@@ -26,7 +46,7 @@ Call `start_phase(N)` to begin each phase. It returns the blueprint, agent perso
 
 ### Phase 1: SCAFFOLD (Extractor)
 - **MCP:** `start_phase(1)`
-- **Goal:** Running skeleton. Use `dndev create-app` and create `*Page.tsx` stubs.
+- **Goal:** Running skeleton. Run `dndev create-app` (interactive wizard, run directly — never `bunx`) and create `*Page.tsx` stubs.
 
 ### Phase 2: ENTITIES (Architect)
 - **MCP:** `start_phase(2)`
@@ -61,7 +81,7 @@ Check that the user has completed environment setup:
 2. Service account key exists? (`service-account-key.json` in app root)
 3. Emulators work? (`dndev emu start` runs without errors)
 
-If not, coach them: "Run `dndev firebase:setup` first, then follow the prompts." See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md).
+If not, coach them: "Run `dndev setup firebase` first, then follow the prompts." See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md).
 
 ---
 

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

@@ -335,24 +335,6 @@ import { StartChallengeForm } from '@donotdev/adv-comps';
 />
 ```
 
-### Waterfall
-
-Waterfall component with lazy loading built-in. Features clean cascade layout with diagonal staircase effect, perfect for step-by-step processes or feature showcases.
-
-```tsx
-import { Waterfall } from '@donotdev/adv-comps';
-import type { WaterfallProps } from '@donotdev/adv-comps';
-
-<Waterfall
-  items: ComponentData[]
-  className?: string
-  connectorClassName?: string
-  density?: 'compact' | 'comfortable'
-  ariaLabel?: string
-  direction?: 'horizontal' | 'descending'
-/>
-```
-
 ## Notes
 
 - All components are lazy-loaded by default for optimal performance

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

@@ -83,7 +83,7 @@
 - **usePrefetch** - Prefetch route data.
 - **useLocation** - Get current location.
 - **useParams** - Get route parameters.
-- **useSearchParams** - Get URL search parameters.
+- **useSearchParams** - Get URL search parameters. Returns `URLSearchParams` directly (NOT a tuple). Use `.get('key')` to read values.
 - **useMatch** - Match current route pattern.
 - **useQueryParams** - Get and set query parameters.
 - **useRedirectGuard** - Guard against redirects.

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

@@ -2,16 +2,20 @@
 
 **The complete onboarding flow — from `dndev init` to deployed app.**
 
+If you haven’t run `dndev init` yet, see [AGENT_START_HERE.md](./AGENT_START_HERE.md) § **Getting started (for humans)** (P0 → Install CLI → Run AI.md → Enjoy).
+
 ---
 
 ## The Flow
 
 ```
-bun install                    → install dependencies
-bun dev                        → start app, read the homepage setup guide
-dndev firebase:setup           → configure Firebase project + .env
-dndev emu start                → test locally with emulators
-dndev deploy                   → deploy to production
+bun install                    -> install dependencies
+bun dev                        -> start app, read the homepage setup guide
+dndev setup firebase           -> configure Firebase project + .env
+  -- or --
+dndev setup supabase           -> configure Supabase project + .env
+dndev emu start                -> test locally with emulators (Firebase)
+dndev deploy                   -> deploy to production
 ```
 
 ---
@@ -43,29 +47,45 @@ git push -u origin main
 
 ---
 
-## Step 3: Firebase
+## Step 3: Backend Setup
+
+### Firebase
 
 ```bash
-dndev firebase:setup
+dndev setup firebase
 ```
 
-Automates: project selection/creation, web app, SDK config → `.env`, `.firebaserc`.
+Automates: project selection/creation, web app, SDK config -> `.env`, `.firebaserc`.
 
 Then 2 manual steps (CLI gives you direct links):
-1. Download service account key → save as `service-account-key.json`
+1. Download service account key -> save as `service-account-key.json`
 2. Enable Auth + Firestore in Firebase Console
 
 See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md) for full details.
 
+### Supabase
+
+```bash
+dndev setup supabase
+```
+
+Asks for your **public** project URL and anon key (both safe to share -- shipped in client bundle).
+
+Get them from: https://supabase.com/dashboard -> your project -> Settings -> API
+
+See [SETUP_SUPABASE.md](./SETUP_SUPABASE.md) for full details (tables, RLS, `dn generate sql`). See [Secrets Philosophy](#secrets-philosophy) for how we handle secret keys.
+
 ---
 
 ## Step 4: Test Locally
 
 ```bash
-dndev emu start
+dndev emu start          # Firebase emulators
 ```
 
-Select Auth + Firestore + Functions. Develops against local emulators.
+Select services: Auth + Firestore + Functions. This starts Firebase emulators so you can develop without touching production.
+
+For Supabase, development runs against your Supabase project directly (or use `supabase start` for local Supabase if installed).
 
 ---
 
@@ -74,11 +94,11 @@ Select Auth + Firestore + Functions. Develops against local emulators.
 Open the project in **Cursor**, **Claude Code**, **Windsurf**, or **AntiGravity**.
 
 The AI reads `AI.md` and follows the WAI-WAY protocol:
-- Phase 0: Brainstorm → produce a spec
-- Phase 1: Scaffold → create pages
-- Phase 2: Entities → define data models
-- Phase 3: Compose → build pages with components
-- Phase 4: Configure → generate tests, firestore rules, CI/CD
+- Phase 0: Brainstorm -> produce a spec
+- Phase 1: Scaffold -> create pages
+- Phase 2: Entities -> define data models
+- Phase 3: Compose -> build pages with components
+- Phase 4: Configure -> generate tests, firestore rules, CI/CD
 
 Read `guides/wai-way/WAI_WAY_CLI.md` for the full workflow.
 
@@ -90,7 +110,51 @@ Read `guides/wai-way/WAI_WAY_CLI.md` for the full workflow.
 dndev deploy
 ```
 
-Deploys hosting + functions + rules. Cloud Run IAM handled automatically.
+Deploys hosting + functions + rules. Syncs runtime secrets automatically before deploying functions.
+
+---
+
+## Secrets Philosophy
+
+**DoNotDev follows strict rules about credentials:**
+
+### Tier 1: Public Keys -- We Ask Directly
+
+These are safe to share, shipped in your client JS bundle. We ask for them during setup.
+
+| Key | Where It Goes |
+|-----|--------------|
+| Firebase API key, project ID, auth domain, etc. | `apps/<app>/.env` as `VITE_FIREBASE_*` |
+| Supabase project URL | `apps/<app>/.env` as `VITE_SUPABASE_URL` |
+| Supabase anon key (public JWT) | `apps/<app>/.env` as `VITE_SUPABASE_ANON_KEY` |
+| Stripe publishable key | `apps/<app>/.env` as `VITE_STRIPE_PUBLISHABLE_KEY` |
+
+### Tier 2: Secret Keys -- We NEVER Ask, We Tell You Where To Put Them
+
+These are server-side only. We never prompt for them, never store them in client code.
+
+| Key | Where It Goes | How To Get It |
+|-----|--------------|---------------|
+| Stripe secret key | `functions/.env` as `STRIPE_SECRET_KEY` | https://dashboard.stripe.com/apikeys |
+| Stripe webhook secret | `functions/.env` as `STRIPE_WEBHOOK_SECRET` | Stripe Dashboard -> Webhooks |
+| Supabase service_role key | `functions/.env` as `SUPABASE_SERVICE_ROLE_KEY` | Supabase Dashboard -> Settings -> API |
+| OAuth client secrets | `functions/.env` as `*_CLIENT_SECRET` | Provider dashboard |
+
+Then sync to your runtime:
+
+```bash
+dndev sync-secrets                    # -> Firebase Secret Manager or Vercel env
+dndev sync-secrets --target github    # -> GitHub Secrets (for CI/CD)
+```
+
+### Tier 3: Service Account Files -- Download, Place, Gitignore
+
+| File | Where It Goes | How To Get It |
+|------|--------------|---------------|
+| `service-account-key.json` | App root (next to firebase.json) | Firebase Console -> Settings -> Service Accounts |
+| `service-account-key.staging.json` | Same location, for staging | Same, from staging project |
+
+These files are `.gitignored`. Never commit them. For CI/CD, upload the file content as a GitHub Secret and decode it in your workflow.
 
 ---
 
@@ -100,18 +164,21 @@ Deploys hosting + functions + rules. Cloud Run IAM handled automatically.
 
 ```
 my-project/
-├── .env.example              ← NOT loaded by Vite (reference only)
-├── apps/
-│   └── my-app/
-│       ├── .env              ← Vite reads THIS
-│       ├── .env.local        ← Overrides .env (gitignored)
-│       ├── .env.staging      ← Used by dndev staging
-│       └── .env.production   ← Production overrides
-└── functions/
-    └── .env                  ← Server secrets (Stripe, OAuth)
++-- .env.example              <-- NOT loaded by Vite (reference only)
++-- apps/
+|   +-- my-app/
+|       +-- .env              <-- Vite reads THIS (public keys: VITE_*)
+|       +-- .env.local        <-- Overrides .env (gitignored)
+|       +-- .env.staging      <-- Used by dndev staging
+|       +-- .env.production   <-- Production overrides
++-- functions/
+    +-- .env                  <-- Server secrets (Stripe, OAuth, service_role)
 ```
 
-**Rule:** `VITE_*` vars go in `apps/<app>/.env`. Server secrets go in `functions/.env`.
+**Rules:**
+- `VITE_*` / `NEXT_PUBLIC_*` vars -> `apps/<app>/.env` (public, shipped to browser)
+- Server secrets -> `functions/.env` (never exposed to client)
+- Service account files -> app root, gitignored
 
 ---
 
@@ -121,10 +188,12 @@ my-project/
 |---------|-------------|
 | `bun dev` | Start dev server |
 | `dndev emu start` | Start Firebase emulators |
-| `dndev firebase:setup` | Configure Firebase project + .env |
-| `dndev deploy` | Deploy to Firebase (hosting + functions + rules) |
+| `dndev setup firebase` | Configure Firebase project + .env |
+| `dndev setup supabase` | Configure Supabase project + .env |
+| `dndev deploy` | **Firebase:** hosting + functions + rules. **Supabase:** deploys frontend to [Vercel](https://vercel.com) (via scaffolded vercel.json) and Edge Functions to Supabase. Set `VITE_SUPABASE_*` in Vercel project env. |
 | `dndev staging` | Deploy to staging environment |
-| `dndev sync-secrets` | Push functions/.env to Firebase Secret Manager |
+| `dndev sync-secrets` | Push functions/.env to runtime (Firebase/Vercel) |
+| `dndev sync-secrets --target github` | Push secrets to GitHub Secrets (CI/CD) |
 | `bun test` | Run tests (after Phase 4) |
 | `bun run type-check` | TypeScript validation |
 
@@ -135,8 +204,8 @@ my-project/
 | Feature | Required? | When to Set Up |
 |---------|-----------|---------------|
 | Git + GitHub | Recommended | Before starting development |
-| Firebase (Auth + Firestore) | Yes | Before building any features |
-| Cloud Functions | If using backend | Before deploying functions |
+| Firebase or Supabase | Yes (pick one) | Before building any features |
+| Cloud Functions | If using server logic | Before deploying functions |
 | Stripe | If using billing | When adding payment features |
 | GitHub Actions CI/CD | Optional | Phase 4 generates the workflow |
 | Staging environment | Optional | When you want a test environment |

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

@@ -8,9 +8,11 @@
 
 ## Getting Started
 
-- [ENV_SETUP.md](./ENV_SETUP.md) - **START HERE** — Full onboarding flow (install → firebase → deploy)
+- **Human flow:** P0 (Bun/Node + AI IDE) → Install CLI & `dndev init` → Run **AI.md** → Enjoy. See [AGENT_START_HERE.md](./AGENT_START_HERE.md) § Getting started (for humans).
+- [ENV_SETUP.md](./ENV_SETUP.md) — After `dndev init`: env, Firebase/Supabase, deploy
 - [GOTCHAS.md](./GOTCHAS.md) - **Common mistakes & pitfalls** (phase-tagged, read before coding)
-- [SETUP_FIREBASE.md](./SETUP_FIREBASE.md) - Firebase project setup (`dndev firebase:setup`)
+- [SETUP_FIREBASE.md](./SETUP_FIREBASE.md) - Firebase project setup (`dndev setup firebase`)
+- [SETUP_SUPABASE.md](./SETUP_SUPABASE.md) - Supabase project setup (`dndev setup supabase`, `dn generate sql`)
 - [SETUP_TESTING.md](./SETUP_TESTING.md) - Test generation (Phase 4)
 
 ---

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

@@ -109,14 +109,14 @@ export default defineViteConfig({
 
 **Vite loads `.env` from the app directory only.** Not the repo root.
 
-Run `dndev firebase:setup` to auto-populate Firebase config. See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md).
+Run `dndev setup firebase` to auto-populate Firebase config. See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md).
 
 ```bash
 # apps/<your-app>/.env — client-side variables (exposed to browser)
 VITE_APP_URL=http://localhost:5173
 VITE_DONOTDEV_LICENSE_KEY=dndev_your_key_here
-VITE_FIREBASE_API_KEY=...          # Written by dndev firebase:setup
-VITE_FIREBASE_PROJECT_ID=...       # Written by dndev firebase:setup
+VITE_FIREBASE_API_KEY=...          # Written by dndev setup firebase
+VITE_FIREBASE_PROJECT_ID=...       # Written by dndev setup firebase
 VITE_AUTH_PARTNERS=github,google
 VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...