@donotdev/cli 0.0.12 → 0.0.13

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

@@ -1,367 +1,66 @@
 # DoNotDev Framework - Agent Quick Start
 
-**Persona:** Lead Developer (implementation, code quality) | UX/UI Designer (UX considerations) | Expert Adviser (strategic feedback, trade-offs). **Skills:** TypeScript, React, component composition, convention-over-configuration mindset. **Critical:** ALWAYS follow conventions and trust the framework. Framework handles 90% - discover before building custom.
+**Persona:** Lead Developer | UX Designer | Expert Adviser.
+**Intelligence Engine:** This project is pre-configured with the **`dndev` MCP Server** in `.mcp.json`.
 
-**When Stuck:**
-1. Check JSDoc (hover in IDE)
-2. Read relevant setup guide
-3. Trust framework defaults
-4. Ask user for clarification
-
-**Never guess. Always verify.**
+**Critical Rule:**
+> **DO NOT GUESS. DO NOT HALLUCINATE.**
+> Use `lookup_symbol("ComponentName")` to get actual TypeScript types. Every symbol has JSDoc and Types. Every setup has a Guide. Use them.
 
 ---
 
-## ✅ Success Path: Follow These Steps
-
-**Step 1: Install dependencies**
-- Run `bun install` in project root
-- Wait for completion - framework components will load correctly
-- TypeScript imports will resolve properly
-
-**Step 2: Create pages correctly**
-- Name files ending in `Page.tsx` (e.g., `HomePage.tsx`)
-- Place them in `src/pages/` folder
-- Framework will auto-discover and route them
-- Navigation will show them automatically
-
-**Step 3: Configure app**
-- Edit `src/config/app.ts` with your preset and app name
-- Framework will use your configuration
-- Footer and legal links will be included automatically
-
-**Step 4: Customize via config files**
-- Override defaults in `src/config/app.ts`
-- Override themes in `src/themes.css`
-- Framework preserves your changes on updates
-
-
-** dndev ** is our custom CLI, dndev --help for info.
-
-
-**🧠 PHILOSOPHY & MINDSET (READ THIS):**
-
-**CRITICAL: ALL YOU NEED TO DO IS FOLLOW OUR NAMING CONVENTIONS + FILE STRUCTURE CONVENTIONS AND FOCUS ON THE INSIDE OF YOUR PAGES, WITH OUR COMPONENTS. EVERYTHING ELSE IS HANDLED. JUST TRUST THE FRAMEWORK AND CODE AS FEW AS POSSIBLE.**
-
-*   **Speed > Polish:** Your goal is to reach UAT (User Acceptance Testing) fast. The app should look "good enough" (80%) using standard components.
-*   **Composition > Customization:** Do not waste time writing CSS to make it "perfect" pixel-wise. Drop components, use props, move on.
-*   **Standardize:** If it looks like a standard DoNotDev app, you succeeded. If you are writing custom CSS to fight the framework, you failed.
-*   **Polishing:** Deep styling is for *after* the core functionality is approved and the User asks you to polish, with their preferred method.
-*   **Trust the Framework:** Navigation, routing, layouts, auth, themes, i18n - all handled automatically. Focus on page content only.
-
----
-
-**✅ STYLING STANDARDS (ALWAYS FOLLOW):**
-
-1.  **Layout Strategy:** Use `<Stack>`, `<Grid>`, and `<Section>` components to organize content. These handle spacing and alignment automatically.
-2.  **Component Props:** Leverage component-specific props and trust their defaults, only add what you really need.
-3.  **Interactions:** Prefer native component interactions. E.g., Use `<Card onClick={...}>` instead of nesting a Button inside if the whole item is actionable.
-
----
-
-## Import Rules
-
-**Root imports only:**
-```tsx
-import { Button } from '@donotdev/components';
-import { PageContainer } from '@donotdev/ui';
-import { useAuth } from '@donotdev/auth';
-```
+## First Thing to Call: list_features()
 
-**Type imports (strict TypeScript):**
-```tsx
-import type { ButtonProps } from '@donotdev/components';
-import type { PageMeta } from '@donotdev/core';
-```
+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.).
 
 ---
 
-## New App Setup
+## The WAI-WAY Workflow (5 Phases)
 
-**CRITICAL: Follow these steps IN ORDER. Complete each step before moving to the next.**
+Call `start_phase(N)` to begin each phase. It returns the blueprint, agent persona, and files to read.
 
-**✅ SCAFFOLDING PHILOSOPHY:**
-The `dndev init` or `dndev create-app` commands create files with working defaults. Your job is to UPDATE these scaffolded files with your specific needs - update values, add content, customize configuration. The scaffolded files are correctly structured and framework-ready. Preserve the structure and imports, update the values and content.
+### Phase 0: BRAINSTORM (Extractor)
+- **MCP:** `start_phase(0)`
+- **Goal:** Validated spec. Use BMAD probing questions to turn a vague idea into a complete `spec_template.md`.
+- **Discovery:** `search_framework('topic')` to see what's possible.
 
-### Step 1: Create Project (if starting from scratch)
-```bash
-dndev init my-project-name
-# OR if adding to existing project:
-cd existing-project
-dndev create-app my-app-name
-```
+### Phase 1: SCAFFOLD (Extractor)
+- **MCP:** `start_phase(1)`
+- **Goal:** Running skeleton. Use `dndev create-app` and create `*Page.tsx` stubs.
 
-### Step 2: Install Dependencies (REQUIRED - FIRST STEP)
-```bash
-cd my-project-name  # or cd apps/my-app-name
-bun install
-```
-**✅ CRITICAL:** Run `bun install` as the first step. This installs all framework dependencies and enables framework components to work correctly.
+### Phase 2: ENTITIES (Architect)
+- **MCP:** `start_phase(2)`
+- **Goal:** Single Source of Truth. Define entities in `entities/` using `defineEntity()`.
+- **Types:** `lookup_symbol('defineEntity')` for exact props and @examples.
 
-### Step 3: Configure App (REQUIRED)
-**CRITICAL:** The scaffolding process creates these files with working defaults. UPDATE them with your specific needs - do not replace them entirely.
+### Phase 3: COMPOSE (Builder)
+- **MCP:** `start_phase(3)`
+- **Goal:** Functional pages. Hardcode all strings. No i18n yet.
+- **Types:** `lookup_symbol('Button')`, `lookup_symbol('EntityList')`, etc.
 
-**File: `src/config/app.ts`** (scaffolded - update with your values):
-```typescript
-import type { AppConfig } from '@donotdev/core';
+### Phase 4: CONFIGURE (Polisher)
+- **MCP:** `start_phase(4)`
+- **Goal:** QA & Polish. Update `app.ts`, `.env`, verify mobile (375px).
+- **Lessons:** `record_lesson('Project quirk found')`.
 
-export const appConfig: AppConfig = {
-  preset: 'landing', // Update: Choose your preset (landing | admin | moolti | docs | blog | game | plain)
-  app: {
-    name: 'My App', // Update: Your app name
-    url: 'https://myapp.com', // Update: Your app URL
-  },
-};
-```
-
-**File: `src/config/legal.ts`** (scaffolded - update with your legal pages):
-```typescript
-export const legalConfig = {
-  // Update: Add your legal pages (privacy, terms, etc.)
-};
-```
-
-**File: `vite.config.ts`** (scaffolded - already configured correctly):
-```typescript
-import { defineViteConfig } from '@donotdev/core/vite';
-import { appConfig } from './src/config/app';
-
-export default defineViteConfig({
-  appConfig,  // Already configured - framework imports your appConfig
-});
-```
-
-**✅ UPDATE STRATEGY:**
-- Scaffolded files are already correctly structured
-- Update values (app name, preset, URLs) to match your needs
-- Keep the file structure and imports as-is
-- Framework expects these exact file paths and exports
-
-**✅ CORRECT FILE PATHS:**
-- `src/config/app.ts` - Place in `src/config/` folder
-- `src/config/legal.ts` - Place in `src/config/` folder  
-- `vite.config.ts` - Place at project root (same level as `package.json`)
-- `src/pages/*Page.tsx` - Place in `src/pages/` folder
-
-### Step 4: Add Logo (Optional but recommended)
-Drop `logo.svg` in `public/` folder. Framework auto-generates favicon, icons, PWA assets.
-
-### Step 5: Create or Update Pages
-**Scaffolding creates `src/pages/HomePage.tsx` with a working example. UPDATE it with your content:**
-
-```tsx
-import { PageContainer } from '@donotdev/ui';
-
-export default function HomePage() {
-  return <PageContainer><h1>Hello</h1></PageContainer>;
-}
-```
-
-**✅ UPDATE STRATEGY:**
-- Scaffolded `HomePage.tsx` is already correctly structured
-- Update the content inside `PageContainer` with your components
-- Keep the imports and export structure as-is
-- Add more pages by creating new `*Page.tsx` files in `src/pages/`
-
-### Step 6: Verify Setup (BEFORE running dev)
-**Check these files exist:**
-- ✅ `src/config/app.ts` exists
-- ✅ `vite.config.ts` exists and imports `appConfig` from `src/config/app.ts`
-- ✅ `src/pages/HomePage.tsx` exists (or at least one `*Page.tsx` file)
-- ✅ `package.json` exists with `@donotdev/*` dependencies
-- ✅ `bun install` completed successfully
-
-### Step 7: Run Development Server
-```bash
-bun run dev
-```
-
-**Expected output:**
-- Server starts on `http://localhost:5173` (or configured port)
-- No "Cannot find module" errors
-- Browser shows your app (may show watermark if no license key)
-
-**If you see errors:**
-1. **"Cannot find module '@donotdev/...'"** → Run `bun install` again
-2. **"Cannot find module './src/config/app'"** → Check `vite.config.ts` path is correct
-3. **"No routes found"** → Check you have `*Page.tsx` files in `src/pages/`
-4. **TypeScript errors** → Run `bun run type-check` to see details
-
-**✅ ALWAYS DO:**
-- Run `bun install` first - required for dependencies
-- Create pages in `src/pages/` folder - framework discovers them automatically
-- Name files ending in `Page.tsx` - framework routes them automatically
-- Trust framework defaults - routing, navigation, layouts are automatic
-- Use preset components - LanguageSelector, ThemeToggle, AuthMenu are included automatically
+Call `complete_phase()` after each phase. It records progress and tells you what's next.
 
 ---
 
-## Generic Conventions
-
-**File Routing Rule: Only files ending in `Page.tsx` inside `src/pages` become routes.**
-
-**✅ ROUTING RULES:**
-- Name files with `Page.tsx` suffix (e.g., `HomePage.tsx`, `AboutPage.tsx`)
-- Place files inside `src/pages/` directory (or subdirectories)
-- Framework auto-discovers routes from `src/pages/*Page.tsx` files
-- Framework automatically generates navigation from discovered routes
-
-**Routing:** Drop `*Page.tsx` files in `src/pages/**` → auto-discovered. Use `PageMeta` for routes, auth, icons.
+## Mindset & Standards
 
-**i18n:** Drop `<namespace>_<lng>.json` in `/locales` (eager) or `/pages/locales` (lazy). Framework auto-discovers languages.
+* **SSOT Pattern:** The Entity is the brain. Change fields in `entities/*.ts` first. UI and DB follow.
+* **Composition > Customization:** Do not write custom CSS. Use `<Stack>`, `<Grid>`, and component props.
+* **Hardcode First:** In Phase 3, never use i18n. Validate the UI with real strings first.
+* **Zero Drift:** Your documentation is the **compiled code**. `lookup_symbol` shows the current reality.
 
-**Themes:** Override CSS variables in `src/themes.css`. Framework auto-computes surfaces, borders, text colors.
+## Before You Start Coding
 
----
-
-## Success Checklist
-
-**✅ Follow these to ensure success:**
-
-1. **✅ Always name pages with `Page.tsx` suffix** - Example: `HomePage.tsx`, `AboutPage.tsx`
-2. **✅ Always run `bun install` first** - Required before any other commands
-3. **✅ Trust framework routing** - Framework auto-discovers routes from `src/pages/*Page.tsx`
-4. **✅ Use preset components** - LanguageSelector, ThemeToggle, AuthMenu are included automatically
-5. **✅ Configure via config files** - Edit `src/config/app.ts`, never modify `node_modules`
-6. **✅ Create pages in `src/pages/` folder** - Framework discovers them automatically
-7. **✅ Configure `src/config/app.ts`** - Set your preset and app name
-8. **✅ Run `bun install` before `bun run dev`** - Dependencies must be installed first
-
----
-
-## 🤖 WAI-WAY: The "With AI Way" Protocol (BMAD-Based)
-
-**WAI-WAY** is a rigorous, agent-driven protocol based on the **BMAD Method**. It separates concerns into 4 distinct phases.
-
-**Entry Point:** Use commands in `.claude/commands/` (synced via `dndev bump`)
-
-**The 4 Phases:**
-1.  **`/brainstorm`** → BMAD EXTRACTOR extracts requirements, generates HLD
-2.  **`/design`** → BMAD PRINTER (Architect) creates technical plan (LLD)
-3.  **`/build`** → BMAD FORGER (Builder) implements code using framework defaults
-4.  **`/polish`** → BMAD FINISHER (Polisher) adds styling, customization, i18n
-
-**How It Works:**
-- Commands are in `.claude/commands/` (synced from framework)
-- Agents are in `.claude/agents/` (BMAD personas, synced from framework)
-- Run commands in Cursor: `/brainstorm [app idea]`, `/design [HLD]`, `/build [LLD]`, `/polish [app]`
-- Documentation syncs automatically via `dndev bump`
-
-**Why use it?**
-WAI-WAY forces your AI to "Think before it Codes". By separating Architecture from Build, we ensure **only valid DoNotDev primitives are used**, preventing custom CSS bloat and "hallucinated" patterns.
-
-**See:** `.claude/commands/` for command details | `guides/wai-way/WAI_WAY_CLI.md` for methodology
-
----
-
-## Landing Page Example
-
-```tsx
-import { PageContainer } from '@donotdev/ui';
-import { HeroSection, Section, Card, CallToAction, Button, Grid, Stack } from '@donotdev/components';
-
-export default function HomePage() {
-  return (
-    <PageContainer>
-      <HeroSection 
-        title="Welcome" 
-        subtitle="Build fast with DoNotDev" 
-        variant="primary"
-      />
-      
-      <Section title="Features" gridCols={3}>
-        <Card title="Fast" content="Lightning fast development" />
-        <Card title="Simple" content="Zero configuration needed" />
-        <Card title="Powerful" content="Enterprise-grade features" />
-      </Section>
-      
-      <Section title="Layout Examples">
-        <Grid cols={[1, 1, 2, 2]} gap="medium">
-          <Card title="Left Column" />
-          <Card title="Right Column" />
-        </Grid>
-        
-        <Stack direction="row" gap="medium">
-          <Button variant="primary">Primary</Button>
-          <Button variant="outline">Secondary</Button>
-        </Stack>
-      </Section>
-      
-      <CallToAction 
-        title="Get Started" 
-        subtitle="Ready to build?"
-        primaryAction={<Button variant="primary">Sign Up</Button>}
-        secondaryAction={<Button variant="outline">Learn More</Button>}
-      />
-    </PageContainer>
-  );
-}
-```
-
----
-
----
-
-## Required File Structure
-
-**CRITICAL:** Your project MUST have this exact structure:
-
-```
-my-project/
-├── package.json              # At root - contains dependencies
-├── vite.config.ts            # At root - imports appConfig
-├── src/
-│   ├── config/
-│   │   ├── app.ts            # REQUIRED - app configuration
-│   │   └── legal.ts           # REQUIRED - legal pages config
-│   ├── pages/
-│   │   └── HomePage.tsx       # Your pages (must end in Page.tsx)
-│   ├── App.tsx                # App entry point
-│   └── main.tsx               # Vite entry point
-└── public/
-    └── logo.svg               # Optional - framework generates assets
-```
-
-**✅ CORRECT FILE PATHS EXAMPLES:**
-- ✅ `src/config/app.ts` (correct location)
-- ✅ `src/pages/HomePage.tsx` (correct location)
-- ✅ `src/pages/AboutPage.tsx` (correct - in pages subfolder)
-- ✅ `src/pages/blog/BlogPostPage.tsx` (correct - nested pages work)
-
----
-
-## Troubleshooting
-
-### "Cannot find module '@donotdev/...'"
-**Solution:** Run `bun install` in the project root. Dependencies must be installed before running the app.
-
-### "No routes found"
-**Solution:** 
-1. Check files are in `src/pages/` folder
-2. Check files end in `Page.tsx` (not `.tsx` or `.ts`)
-3. Check files are exported as default: `export default function HomePage()`
-
-### "Cannot find module './src/config/app'"
-**Solution:**
-1. Check `vite.config.ts` is at project root (same level as `package.json`)
-2. Check `src/config/app.ts` exists
-3. Check import path in `vite.config.ts`: `import { appConfig } from './src/config/app';`
-
-### App shows blank page
-**Solution:**
-1. Check browser console for errors
-2. Verify at least one `*Page.tsx` file exists in `src/pages/`
-3. Verify `vite.config.ts` imports `appConfig` correctly
-4. Check `src/App.tsx` uses `ViteAppProviders` with `config={appConfig}`
-
-### TypeScript errors
-**Solution:**
-1. Run `bun run type-check` to see all errors
-2. Ensure all `@donotdev/*` packages are installed
-3. Check imports use root package names: `@donotdev/components`, not deep paths
-
----
+Check that the user has completed environment setup:
+1. Firebase configured? (`.env` has `VITE_FIREBASE_API_KEY` filled in)
+2. Service account key exists? (`service-account-key.json` in app root)
+3. Emulators work? (`dndev emu start` runs without errors)
 
-**Component references:** [COMPONENTS_ATOMIC.md](./COMPONENTS_ATOMIC.md) | [COMPONENTS_UI.md](./COMPONENTS_UI.md) | [COMPONENTS_CRUD.md](./COMPONENTS_CRUD.md)
+If not, coach them: "Run `dndev firebase:setup` first, then follow the prompts." See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md).
 
-**Full guides:** [INDEX.md](./INDEX.md) - 50-100 LOC per topic (SETUP_*.md, advanced/*.md)
+**Starting:** Call `list_features()` first, then `get_phase_status()` to see where you are, then `start_phase(0)` to begin.

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

@@ -133,7 +133,7 @@ import { Reveal } from '@donotdev/adv-comps';
 
 ### InspectorGadget
 
-Floating code inspector component. Displays a floating eye icon button that opens a dialog showing the page's source code.
+Floating code inspector component. Displays a floating button with Code icon and label that opens a dialog showing the page's source code.
 
 ```tsx
 import { InspectorGadget } from '@donotdev/adv-comps';
@@ -164,6 +164,7 @@ import type { BreathingExerciseDnDevLayoutProps } from '@donotdev/adv-comps';
   onSkip?: () => void
   statusValue?: string
   onRestart?: () => void
+  onResume?: () => void
   isPaused?: boolean
   isComplete?: boolean
 />

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

@@ -1,14 +1,149 @@
-# Environment Setup
+# Getting Started
 
-If you see this guide, you've already installed `@donotdev/cli` and ran `dndev init`.
+**The complete onboarding flow — from `dndev init` to deployed app.**
 
-## Next Steps
+---
 
-1. **AI Agent?** Have them read [AGENT_START_HERE.md](./AGENT_START_HERE.md)
-2. **Create app:** `dndev create-app` - choose Vite (SPA) or Next.js (SSR), with optional backend
-3. **Build:** Use auto-routing, auth, and translations
+## The Flow
 
-## Resources
+```
+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
+```
 
-- https://donotdev.com
-- Discord: https://discord.gg/fbeYWDak
+---
+
+## Step 1: Install & Run
+
+```bash
+bun install
+bun dev
+```
+
+Open the app. The homepage shows every setup step with instructions.
+
+---
+
+## Step 2: Git
+
+```bash
+git init
+git add . && git commit -m "Initial scaffold"
+```
+
+Create a repo on GitHub, then:
+
+```bash
+git remote add origin <your-repo-url>
+git push -u origin main
+```
+
+---
+
+## Step 3: Firebase
+
+```bash
+dndev firebase:setup
+```
+
+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`
+2. Enable Auth + Firestore in Firebase Console
+
+See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md) for full details.
+
+---
+
+## Step 4: Test Locally
+
+```bash
+dndev emu start
+```
+
+Select Auth + Firestore + Functions. Develops against local emulators.
+
+---
+
+## Step 5: Build With AI
+
+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
+
+Read `guides/wai-way/WAI_WAY_CLI.md` for the full workflow.
+
+---
+
+## Step 6: Deploy
+
+```bash
+dndev deploy
+```
+
+Deploys hosting + functions + rules. Cloud Run IAM handled automatically.
+
+---
+
+## Environment Variables
+
+**Each app has its own `.env`.** Vite loads from the app directory only.
+
+```
+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)
+```
+
+**Rule:** `VITE_*` vars go in `apps/<app>/.env`. Server secrets go in `functions/.env`.
+
+---
+
+## CLI Commands
+
+| Command | What It Does |
+|---------|-------------|
+| `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 staging` | Deploy to staging environment |
+| `dndev sync-secrets` | Push functions/.env to Firebase Secret Manager |
+| `bun test` | Run tests (after Phase 4) |
+| `bun run type-check` | TypeScript validation |
+
+---
+
+## What's Optional
+
+| 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 |
+| 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 |
+| Custom domain | Optional | After first deploy |
+| Sentry | Optional | When you want error tracking |
+| i18n | Optional | Phase 4 or after launch |
+
+---
+
+**Start here: `bun install && bun dev`. The homepage tells you everything else.**

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

@@ -6,6 +6,14 @@
 
 ---
 
+## Getting Started
+
+- [ENV_SETUP.md](./ENV_SETUP.md) - **START HERE** — Full onboarding flow (install → firebase → deploy)
+- [SETUP_FIREBASE.md](./SETUP_FIREBASE.md) - Firebase project setup (`dndev firebase:setup`)
+- [SETUP_TESTING.md](./SETUP_TESTING.md) - Test generation (Phase 4)
+
+---
+
 ## Core Setup
 
 - [SETUP_PAGES.md](./SETUP_PAGES.md) - Pages & routing (pre-configured)
@@ -23,6 +31,7 @@
 - [SETUP_AUTH.md](./SETUP_AUTH.md) - Authentication (pre-configured)
 - [SETUP_OAUTH.md](./SETUP_OAUTH.md) - OAuth connections (pre-configured)
 - [SETUP_BILLING.md](./SETUP_BILLING.md) - Stripe subscriptions (pre-configured)
+- [SETUP_BLOG.md](./SETUP_BLOG.md) - Convention-based markdown blog with i18n
 - [SETUP_PWA.md](./SETUP_PWA.md) - Progressive Web App setup
 - [SETUP_FUNCTIONS.md](./SETUP_FUNCTIONS.md) - Firebase Functions (pre-configured)
 

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

@@ -107,29 +107,26 @@ export default defineViteConfig({
 
 ## 4. Environment Variables
 
-```bash
-# .env
-VITE_APP_NAME="My App"
-VITE_APP_URL=http://localhost:5173
+**Vite loads `.env` from the app directory only.** Not the repo root.
 
-# Firebase
-VITE_FIREBASE_API_KEY=your-api-key
-VITE_FIREBASE_AUTH_DOMAIN=your-project.firebaseapp.com
-VITE_FIREBASE_PROJECT_ID=your-project-id
-VITE_FIREBASE_STORAGE_BUCKET=your-project.appspot.com
-VITE_FIREBASE_MESSAGING_SENDER_ID=123456789
-VITE_FIREBASE_APP_ID=1:123456789:web:abcdef
+Run `dndev firebase:setup` to auto-populate Firebase config. See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md).
 
-# Auth providers
-VITE_AUTH_PARTNERS=password,emailLink,google,github
-
-# Stripe
+```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_AUTH_PARTNERS=github,google
 VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...
+
+# functions/.env — server-side secrets (never exposed to browser)
 STRIPE_SECRET_KEY=sk_test_...
 STRIPE_WEBHOOK_SECRET=whsec_...
-STRIPE_API_VERSION=2025-08-27.basil
 ```
 
+Push server secrets to Firebase: `dndev sync-secrets`
+
 ---
 
 **Zero config. Override when needed.**