@donotdev/cli 0.0.17 → 0.0.19

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

@@ -16,11 +16,10 @@
 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`
+2. **Create your project’s monorepo**
+   - `bunx create-donotdev my-app`
+3. **Open the repo in your IDE**
+   - Start your IDE in that repo. Dependencies are already installed.
 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.
@@ -29,6 +28,22 @@
 
 ---
 
+## Demo App — Canonical Reference
+
+**Before building anything, look at the demo app:** `packages/cli/templates/app-demo/`
+
+It demonstrates the correct way to use the framework:
+- Per-route layout switching via `PageMeta.preset` (landing → admin → docs)
+- SaaS pages as thin template wrappers (~5 lines each)
+- Component showcase with filterable grid and detail pages
+- Entity definition with `defineEntity()`
+- Zero custom CSS in page files
+- Auth-guarded routes alongside public routes
+
+**Copy from the demo app, then customize.** Don't invent patterns — the demo app IS the pattern.
+
+---
+
 ## 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.).
@@ -81,7 +96,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 setup firebase` first, then follow the prompts." See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md).
+If not, coach them: "Run `dndev coach` to see what to configure, fill in the .env values, then run `dndev setup`." See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md) or [SETUP_SUPABASE.md](./SETUP_SUPABASE.md).
 
 ---
 

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

@@ -1,16 +1,9 @@
-# Advanced Components (@donotdev/adv-comps)
+# Advanced Components (@donotdev/components)
 
-High-level, opinionated, and marketing-focused UI components for DoNotDev framework.
+High-level, opinionated, and marketing-focused UI components from `@donotdev/components`.
 
-## Setup
-
-**IMPORTANT:** You must import the styles in your `globals.css` file:
-
-```css
-@import '@donotdev/adv-comps/styles';
-```
-
-Without this import, components will not have their required CSS styles.
+All advanced components are included in `@donotdev/components` — no additional package needed.
+Styles are automatically included via `@donotdev/components/styles`.
 
 ## Components
 
@@ -19,7 +12,7 @@ Without this import, components will not have their required CSS styles.
 Cinematic 3D text crawl component with lazy loading.
 
 ```tsx
-import { Crawl } from '@donotdev/adv-comps';
+import { Crawl } from '@donotdev/components';
 
 <Crawl
   intro?: ReactNode | string
@@ -39,7 +32,7 @@ import { Crawl } from '@donotdev/adv-comps';
 Production-grade marquee with accessibility, reduced motion support, and smart behavior detection.
 
 ```tsx
-import { Marquee } from '@donotdev/adv-comps';
+import { Marquee } from '@donotdev/components';
 
 <Marquee<T>
   items: T[]
@@ -63,8 +56,8 @@ import { Marquee } from '@donotdev/adv-comps';
 Timeline component with horizontal (desktop) / vertical (mobile) layout. Features animated progress line, glowing nodes, and lift-on-hover cards.
 
 ```tsx
-import { Roadmap } from '@donotdev/adv-comps';
-import type { RoadmapStep } from '@donotdev/adv-comps';
+import { Roadmap } from '@donotdev/components';
+import type { RoadmapStep } from '@donotdev/components';
 
 <Roadmap
   steps: RoadmapStep[]
@@ -88,8 +81,8 @@ interface RoadmapStep {
 Simple scroll-reveal stacked cards. Active card shows full content, stacked cards show only bottom edge with number.
 
 ```tsx
-import { StackedCards } from '@donotdev/adv-comps';
-import type { StackedCardData } from '@donotdev/adv-comps';
+import { StackedCards } from '@donotdev/components';
+import type { StackedCardData } from '@donotdev/components';
 
 <StackedCards
   items: StackedCardData[]
@@ -111,7 +104,7 @@ interface StackedCardData extends ComponentData {
 Reveal component for staggered animations. Features viewport-based visibility detection, directional animations, and customizable stagger delays.
 
 ```tsx
-import { Reveal } from '@donotdev/adv-comps';
+import { Reveal } from '@donotdev/components';
 
 <Reveal
   items: string[] | ReactNode[]
@@ -131,54 +124,13 @@ import { Reveal } from '@donotdev/adv-comps';
 />
 ```
 
-### InspectorGadget
-
-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';
-
-<InspectorGadget
-  data?: string // Source code string
-  sourcePath?: string // Path to source file (import with ?raw) - overrides data if provided
-  sourceCode?: string // Source code loaded from file
-  language?: string // Code language for syntax highlighting @default 'tsx'
-  title?: string // Dialog title @default 'Page Source'
-  className?: string
-/>
-```
-
-### Breathing Components
-
-Breathing exercise components for meditation and wellness apps.
-
-```tsx
-import { LungsAnimation, BreathingExerciseLayout } from '@donotdev/adv-comps';
-import type { BreathingExerciseDnDevLayoutProps } from '@donotdev/adv-comps';
-
-<BreathingExerciseLayout
-  status?: ReactNode
-  animation: ReactNode
-  instructions: ReactNode
-  debug?: boolean
-  onSkip?: () => void
-  statusValue?: string
-  onRestart?: () => void
-  onResume?: () => void
-  isPaused?: boolean
-  isComplete?: boolean
-/>
-
-<LungsAnimation ... />
-```
-
 ### Carousel
 
 Premium carousel component with lazy loading built-in. Features true infinite circular loop, hardware-accelerated animations, swipe/touch gestures, and autoplay with pause-on-hover.
 
 ```tsx
-import { Carousel } from '@donotdev/adv-comps';
-import type { CarouselProps, CarouselRef } from '@donotdev/adv-comps';
+import { Carousel } from '@donotdev/components';
+import type { CarouselProps, CarouselRef } from '@donotdev/components';
 
 <Carousel<T>
   items: T[]
@@ -196,100 +148,13 @@ import type { CarouselProps, CarouselRef } from '@donotdev/adv-comps';
 />
 ```
 
-### ComparisonGrid
-
-Comparison grid component for displaying feature comparisons. Provides lazy-loaded content with skeleton loading states.
-
-```tsx
-import { ComparisonGrid } from '@donotdev/adv-comps';
-import type { ComparisonItem } from '@donotdev/adv-comps';
-
-<ComparisonGrid
-  title?: string
-  items: ComparisonItem[]
-  gridCols?: 1 | 2 | 3 | 4 // @default 2
-  className?: string
-  ariaLabel?: string
-/>
-
-// ComparisonItem interface:
-interface ComparisonItem {
-  useCase: string
-  bestFit: string
-  dndev: string
-  reason: string
-}
-```
-
-### CongratulationsCard
-
-Card component for displaying congratulatory messages. Features customizable icon and text with centered layout.
-
-```tsx
-import { CongratulationsCard } from '@donotdev/adv-comps';
-
-<CongratulationsCard
-  text: string
-  icon?: ReactNode // @default '🎉'
-  className?: string
-/>
-```
-
-### GuideModal
-
-Modal component for displaying guides and tutorials. Provides step-by-step guide display with navigation, progress tracking, and completion handling.
-
-```tsx
-import { GuideModal } from '@donotdev/adv-comps';
-import type { GuideModalProps, GuideTemplate } from '@donotdev/adv-comps';
-
-<GuideModal
-  open: boolean
-  onOpenChange: (open: boolean) => void
-  guide: GuideTemplate
-  icon?: LucideIcon
-/>
-
-// GuideTemplate interface:
-interface GuideTemplate {
-  title: string
-  subtitle: string
-  quickStart?: {
-    title: string
-    code: string
-    description: string
-  }
-  steps?: GuideStep[]
-  features?: string[]
-  templates?: Array<{
-    name: string
-    description: string
-  }>
-  actions?: Array<{
-    label: string
-    href: string
-    variant?: 'default' | 'outline'
-    icon?: LucideIcon
-  }>
-}
-
-// GuideStep interface:
-interface GuideStep {
-  icon: LucideIcon
-  title: string
-  description: string
-  code?: string
-  details?: string
-}
-```
-
 ### SplitReveal
 
 Split reveal component for displaying content in two columns. Features left column content and right column stat cards or custom content with reveal animations.
 
 ```tsx
-import { SplitReveal } from '@donotdev/adv-comps';
-import type { StatCardData } from '@donotdev/adv-comps';
+import { SplitReveal } from '@donotdev/components';
+import type { StatCardData } from '@donotdev/components';
 
 <SplitReveal
   left: ReactNode
@@ -307,34 +172,6 @@ interface StatCardData {
 }
 ```
 
-### StartChallengeForm
-
-Generic form layout component for input + CTA button patterns.
-
-```tsx
-import { StartChallengeForm } from '@donotdev/adv-comps';
-
-<StartChallengeForm
-  input={{
-    value: string
-    onChange: (value: string) => void
-    placeholder?: string
-    label?: string
-    maxLength?: number
-    className?: string
-  }}
-  button={{
-    label: string
-    onClick: () => void
-    icon?: ComponentType<{ className?: string }>
-    variant?: ButtonVariant
-    className?: string
-  }}
-  size?: 'sm' | 'md' | 'lg'
-  className?: string
-/>
-```
-
 ## Notes
 
 - All components are lazy-loaded by default for optimal performance
@@ -346,7 +183,7 @@ import { StartChallengeForm } from '@donotdev/adv-comps';
 
 FAQ section component for displaying frequently asked questions using accordion. Reads FAQ items from i18n JSON files.
 
-**Note:** This component is from `@donotdev/core`, not `@donotdev/adv-comps`. It requires i18n setup with translation files.
+**Note:** This component is from `@donotdev/core`, not `@donotdev/components`. It requires i18n setup with translation files.
 
 ```tsx
 import { FAQSection, useTranslation } from '@donotdev/core';

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

@@ -10,12 +10,13 @@ If you haven’t run `dndev init` yet, see [AGENT_START_HERE.md](./AGENT_START_H
 
 ```
 bun install                    → install dependencies
-dndev 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
+dndev dev                      → start app, read the homepage setup guide
+dndev coach                    → see what to configure (numbered checklist)
+  (fill in .env values from dashboard)
+dndev setup                    → validate .env, automate provider config
+dndev doctor                   → health check
+dndev emu start                → test locally with emulators (Firebase)
+dndev deploy                   → deploy to production
 ```
 
 ---
@@ -49,31 +50,27 @@ git push -u origin main
 
 ## Step 3: Backend Setup
 
-### Firebase
+### 1. See what to configure
 
 ```bash
-dndev setup firebase
+dndev coach
 ```
 
-Automates: project selection/creation, web app, SDK config -> `.env`, `.firebaserc`.
+Prints a numbered checklist: which dashboard to visit, what to copy, where to paste it. No automation, no prompts.
 
-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
+### 2. Fill in .env values
 
-See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md) for full details.
+Follow the coach checklist. Paste credentials from your provider dashboards into the appropriate `.env` files.
 
-### Supabase
+### 3. Run setup
 
 ```bash
-dndev setup supabase
+dndev setup
 ```
 
-Asks for your **public** project URL and anon key (both safe to share -- shipped in client bundle).
+Validates all required env vars are present, runs provider automation (CLI linking, migrations, etc.), and runs an inline health check. If values are missing, it tells you which ones and points you back to `dndev coach`.
 
-Get them from: https://supabase.com/dashboard -> your project -> Settings -> API
-
-See [SETUP_SUPABASE.md](./SETUP_SUPABASE.md) for full details (tables, RLS, `dndev generate sql`). See [Secrets Philosophy](#secrets-philosophy) for how we handle secret keys.
+See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md) or [SETUP_SUPABASE.md](./SETUP_SUPABASE.md) for full details. See [Secrets Philosophy](#secrets-philosophy) for how we handle secret keys.
 
 ---
 
@@ -188,8 +185,9 @@ my-project/
 |---------|-------------|
 | `dndev dev` | Start dev server |
 | `dndev emu start` | Start Firebase emulators |
-| `dndev setup firebase` | Configure Firebase project + .env |
-| `dndev setup supabase` | Configure Supabase project + .env |
+| `dndev coach` | Show what to configure (numbered checklist) |
+| `dndev setup` | Validate .env, automate provider config, health check |
+| `dndev doctor` | Check project health (providers, .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 runtime (Firebase/Vercel) |

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

@@ -18,7 +18,7 @@ import { getFirestore } from '@donotdev/firebase';
 import { handleError } from '@donotdev/core';
 ```
 
-**Rule:** Always use `/server` suffix for `@donotdev/firebase/server`, `@donotdev/core/server`, `@donotdev/utils/server`.
+**Rule:** Always use `/server` suffix for `@donotdev/core/server`, `@donotdev/firebase/server`, `@donotdev/security/server`.
 
 **ESM only — never use `require()`.**
 
@@ -49,7 +49,7 @@ One line for values, one line for types. Blank line between categories.
 import { Link, useNavigate, useParams } from 'react-router-dom';
 
 // ✅ CORRECT
-import { Link, useNavigate, useParams } from '@donotdev/ui/routing';
+import { Link, useNavigate, useParams } from '@donotdev/ui';
 ```
 
 **Routes are auto-discovered** from `src/pages/*Page.tsx` with `pageMeta`. Don't use `<Routes>`, `<Route>`, or manual `<Outlet />`.
@@ -106,7 +106,18 @@ Common wrong props:
 ## CRUD [Phase 2, 3]
 
 **Hidden fields are auto-added by `defineEntity()` — don't define them manually:**
-- `id`, `createdAt`, `updatedAt`, `createdById`, `updatedById`, `status`
+- `id`, `createdAt`, `updatedAt`, `createdById`, `updatedById`
+
+**Status field — extend, don't redefine.**
+The `status` field is auto-added with locked `visibility: 'admin'`, `editable: 'admin'`, `type: 'select'`. Only `validation.options` can be extended.
+
+```typescript
+// ❌ WRONG - these properties are silently ignored
+status: { type: 'select', visibility: 'owner', editable: 'admin', validation: { options: [...] } }
+
+// ✅ CORRECT - only extend options (merged after defaults: draft, available, deleted)
+status: { validation: { options: [{ value: 'shipped', label: 'Shipped' }] } }
+```
 
 **Scope field is auto-added** when `scope` is configured. Don't manually define the scope field (e.g., `companyId`).
 

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

@@ -11,8 +11,8 @@
 - **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 setup firebase`)
-- [SETUP_SUPABASE.md](./SETUP_SUPABASE.md) - Supabase project setup (`dndev setup supabase`, `dndev generate sql`)
+- [SETUP_FIREBASE.md](./SETUP_FIREBASE.md) - Firebase project setup (`dndev coach` → `dndev setup`)
+- [SETUP_SUPABASE.md](./SETUP_SUPABASE.md) - Supabase project setup (`dndev coach` → `dndev setup`)
 - [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 setup firebase` to auto-populate Firebase config. See [SETUP_FIREBASE.md](./SETUP_FIREBASE.md).
+Run `dndev coach` to see what to configure, then `dndev setup` to validate and automate. 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 setup firebase
-VITE_FIREBASE_PROJECT_ID=...       # Written by dndev setup firebase
+VITE_FIREBASE_API_KEY=...          # Written by dndev setup
+VITE_FIREBASE_PROJECT_ID=...       # Written by dndev setup
 VITE_AUTH_PARTNERS=github,google
 VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...
 

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

@@ -212,14 +212,31 @@ const filtered = blog.getPostsByTag('react'); // Posts tagged 'react'
 
 ## RSS & Sitemap
 
-**Auto-generated at build time.** The SEO pipeline (Vite `SEOPlugin` / Next.js `SEOHandler`) automatically:
+**Fully automatic — zero configuration.** The framework handles everything:
+
+### Build-time generation
+
+The SEO pipeline (Vite `SEOPlugin` / Next.js `SEOHandler`) automatically:
 
 1. Discovers `src/content/blog/*_en.md` files
 2. Appends blog post URLs to `sitemap.xml`
-3. Generates `rss.xml` with all posts
+3. Generates `rss.xml` (RSS 2.0 with Atom self-link) with all posts
 
 No manual scripts needed. Just drop `.md` files and build.
 
+### RSS auto-discovery
+
+A `<link rel="alternate" type="application/rss+xml">` tag is automatically injected in the `<head>` by `AutoMetaTags`. This lets browsers and feed readers detect the feed without users needing to know the URL.
+
+**Requires:** `VITE_APP_URL` (or `NEXT_PUBLIC_APP_URL`) set in `.env` — the RSS link uses the base URL to construct `https://yourdomain.com/rss.xml`.
+
+### RSS feed contents
+
+Each blog post entry includes:
+- `<title>`, `<description>`, `<link>`, `<guid>`, `<pubDate>`
+- `<category>` (from frontmatter `tags`)
+- `<enclosure>` (from frontmatter `image`, if set)
+
 ---
 
 ## Scaling (50+ Posts)

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

@@ -28,6 +28,40 @@ export const productEntity = defineEntity({
 
 See `lookup_symbol("defineEntity")` for all options (scope, access, ownership, uniqueKeys, validation).
 
+### Status Field (auto-added)
+
+The `status` field is auto-added by `defineEntity()` with **locked** properties:
+
+| Property | Locked Value | Can Override? |
+|----------|-------------|---------------|
+| `type` | `'select'` | No |
+| `visibility` | `'admin'` | No |
+| `editable` | `'admin'` | No |
+| `required` | `true` | No |
+
+**Default options:** `draft`, `available`, `deleted` — always present, cannot be removed.
+**Default value:** `available`.
+
+To add custom options, define **only** `validation.options` — they merge after defaults:
+
+```typescript
+fields: {
+  status: {
+    validation: {
+      options: [
+        { value: 'shipped', label: 'Shipped' },
+        { value: 'returned', label: 'Returned' },
+      ],
+    },
+  },
+  // Result: [draft, available, deleted, shipped, returned]
+}
+```
+
+**Do NOT** set `type`, `visibility`, or `editable` on `status` — they are silently ignored.
+
+> `draft` and `deleted` items are hidden from non-admin users (server-side filtering).
+
 ---
 
 ## 2. Provider Setup (once)
@@ -111,7 +145,7 @@ access: { create: 'admin', read: 'guest', update: 'admin', delete: 'admin' }
 For marketplace patterns. See `lookup_symbol("defineEntity")` → `ownership`.
 
 **Firebase:** Enforced by generated secure Firebase Functions (server-side).
-**Supabase:** Enforced via RLS policies — generated by `dndev setup supabase`.
+**Supabase:** Enforced via RLS policies — generated by `dndev setup`.
 
 ---
 

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

@@ -4,19 +4,24 @@
 
 ---
 
-## Step 1: Run Firebase Setup
+## Step 1: Run Coach + Fill .env
 
 ```bash
-dndev setup firebase
+dndev coach
 ```
 
-This command:
-- Checks Firebase CLI is installed and you're logged in
-- Lists your Firebase projects (or creates a new one)
-- Creates a web app if the project doesn't have one
-- Gets the SDK config and writes it to your app's `.env`
-- Updates `.firebaserc` with the project ID
-- Updates `firebase.json` placeholders
+This prints a numbered checklist of what to configure. For Firebase, you'll need:
+- **SDK config** (API key, project ID, auth domain, etc.) → paste into your app's `.env`
+- **Service account key** → download and save as `service-account-key.json`
+- **Enable services** (Auth, Firestore, Storage) in Firebase Console
+
+Then run setup to validate and automate:
+
+```bash
+dndev setup
+```
+
+Setup validates .env values, checks Firebase CLI, selects/creates a web app, updates `.firebaserc` and `firebase.json`.
 
 **After running, it will prompt you for 2 manual steps (below).**
 
@@ -154,7 +159,7 @@ If you deploy manually with `firebase deploy`, you'll see `403 Forbidden` on COR
 | `functions/.env` | Server secrets: STRIPE_SECRET_KEY, OAuth secrets | Cloud Functions runtime |
 | Root `.env` | **Not read by Vite.** Reference only. | Nothing |
 
-**`dndev setup firebase` writes Firebase vars to `apps/<app>/.env` automatically.**
+**`dndev setup` writes Firebase vars to the app's `.env` automatically.**
 
 **Custom domains:** Framework uses `APP_URL` hostname as `authDomain` in production (not Firebase's `projectId.firebaseapp.com`). Set your `FIREBASE_AUTH_DOMAIN` env var (with the appropriate `VITE_` or `NEXT_PUBLIC_` prefix) in `.env.local` and `.env.production` — framework handles the rest.
 
@@ -163,7 +168,7 @@ If you deploy manually with `firebase deploy`, you'll see `403 Forbidden` on COR
 ## Staging Environment (Optional)
 
 1. Create a second Firebase project (e.g., `my-app-staging`)
-2. Run `dndev setup firebase` again and select the staging project
+2. Run `dndev setup firebase` to configure the staging project
 3. The wizard updates `.firebaserc` — add a `"staging"` alias manually if the wizard only sets `"default"`:
    ```json
    { "projects": { "default": "my-app-prod", "staging": "my-app-staging" } }
@@ -223,4 +228,4 @@ See [ENV_SETUP.md → Secrets Philosophy](./ENV_SETUP.md#secrets-philosophy) for
 
 ---
 
-**`dndev setup firebase` → download service account key → enable Auth + Firestore → `dndev emu start` → `dndev deploy`. That's it.**
+**`dndev coach` → fill .env → `dndev setup` → download service account key → enable Auth + Firestore → `dndev emu start` → `dndev deploy`. That's it.**

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

@@ -36,6 +36,38 @@ All presets automatically include these components when applicable:
 
 ---
 
+## Per-Route Layout Switching
+
+**Override the app preset on a per-page basis via `PageMeta.preset`:**
+
+```tsx
+// src/pages/DashboardPage.tsx
+import type { PageMeta } from '@donotdev/core';
+
+export const meta: PageMeta = {
+  preset: 'admin',  // This route uses admin layout (sidebar, compact density)
+  auth: true,
+};
+```
+
+- If `preset` is set → that route uses the specified layout
+- If `preset` is absent → the app's `appConfig.preset` is used
+- The override is **transient** — navigating away restores the next route's preset or the app default
+- No localStorage pollution — route presets are not persisted
+
+**Common pattern (SaaS app):**
+| Route | Preset | Purpose |
+|-------|--------|---------|
+| `/` | (app default: `landing`) | Marketing landing page |
+| `/pricing` | (app default: `landing`) | Pricing page |
+| `/dashboard` | `admin` | Dashboard with sidebar |
+| `/products` | `admin` | CRUD with sidebar |
+| `/changelog` | `docs` | Documentation layout |
+
+**Reference implementation:** See `packages/cli/templates/app-demo/` for a working example of per-route switching.
+
+---
+
 ## Advanced: Slot Overrides
 
 **Customize zones:**

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

@@ -1,7 +1,7 @@
 # OAuth Provider Setup Guide
 
 Each OAuth provider requires manual registration in their developer console.
-`dndev setup oauth` computes the correct redirect URI for you.
+`dndev coach` shows the correct redirect URI and setup steps for each provider.
 
 ## Redirect URIs