@donotdev/cli 0.0.18 → 0.0.20

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
 

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

@@ -64,32 +64,37 @@ export default function HomePage() {
 export const meta: PageMeta = {
   // Translation/SEO namespace
   namespace: NAMESPACE,
-  
+
   // Route configuration
   route: '/custom-url',                    // Override auto-generated path
   route: { params: ['slug'] },            // Dynamic: /blog/:slug
-  
+
   // Page title (optional - auto-extracted from filename)
   title: 'Custom Title',
-  
+
   // Navigation icon (lucide-react JSX only)
   icon: <Rocket />,                        // Menu icon (default: Link)
-  
+
   // Hide from navigation menu
   hideFromMenu: false,                     // Default: false (shows in nav)
-  
+
+  // Layout preset override (per-route)
+  preset: 'admin',                         // Override app default for this route
+
   // Authentication
   auth: true,                              // Simple: auth required
   auth: { required: true },                // Explicit: auth required
   auth: { required: true, role: 'admin' }, // Role-based access
   auth: { required: true, tier: 'pro' },   // Tier-based access
-  auth: { 
+  auth: {
     required: true,
     validate: (role, tier) => role === 'admin' && tier === 'pro'
   },                                       // Custom validation
 };
 ```
 
+**Reference implementation:** The demo app (`packages/cli/templates/app-demo/`) shows all these patterns working together — landing, admin, docs presets, auth, showcase, CRUD, legal pages.
+
 ---
 
 ## Advanced: Dynamic Routes & Navigation
@@ -141,17 +146,15 @@ import { Link } from '@donotdev/ui';
 **Always import from `@donotdev/<package>` top-level.** Never use sub-paths.
 
 ```tsx
-// CORRECT
 import { PageContainer, Link, useNavigate } from '@donotdev/ui';
 import { Card, Button, Input } from '@donotdev/components';
 import { useCrud } from '@donotdev/crud';
-
-// WRONG — sub-paths do not exist
-import { Link } from '@donotdev/ui/routing';
-import { Card } from '@donotdev/components/card';
 ```
 
-**Exceptions** (server/config only): `@donotdev/core/server`, `@donotdev/core/vite`, `@donotdev/core/next`, `@donotdev/core/functions`.
+**Sub-path exceptions** (server, config, and provider-specific):
+- **Server:** `@donotdev/core/server`, `@donotdev/firebase/server`, `@donotdev/security/server`
+- **Config:** `@donotdev/core/vite`, `@donotdev/core/next`, `@donotdev/core/functions`
+- **Functions:** `@donotdev/functions/firebase`, `@donotdev/functions/vercel`, `@donotdev/functions/supabase`
 
 ---
 
@@ -172,8 +175,7 @@ src/pages/
 
 ```tsx
 // src/pages/HomePage.tsx — SaaS pattern
-import { useAuth } from '@donotdev/auth';
-import { useNavigate, PageContainer } from '@donotdev/ui';
+import { useAuthSafe, useNavigate, PageContainer } from '@donotdev/ui';
 import { LoginForm } from '@donotdev/templates';
 
 export const meta: PageMeta = {
@@ -182,7 +184,7 @@ export const meta: PageMeta = {
 };
 
 export default function HomePage() {
-  const { user } = useAuth();
+  const user = useAuthSafe('user');
   const navigate = useNavigate();
 
   // Redirect authenticated users to dashboard
@@ -196,6 +198,8 @@ export default function HomePage() {
 }
 ```
 
+> **Why `useAuthSafe` instead of `useAuth`?** HomePage is public — it renders before auth is guaranteed to be initialized. `useAuthSafe` (from `@donotdev/ui`) gracefully degrades if `@donotdev/auth` isn't installed or still initializing. `useAuth` (from `@donotdev/auth`) throws if auth isn't available. Use `useAuthSafe` on any page without `auth: true` in its meta.
+
 ---
 
 **Drop files, get routes. Framework handles the rest.**

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

@@ -52,8 +52,8 @@ For subscription testing without waiting for real billing cycles:
 ## 5. Verify
 
 ```bash
-dndev setup stripe   # Interactive key setup + validation
-dndev doctor         # Health check for all providers
+dndev setup          # Validates key formats + health check
+dndev doctor         # Full health check for all providers
 ```
 
 Check that:

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

@@ -4,29 +4,34 @@
 
 ---
 
-## Step 1: Run Supabase Setup
+## Step 1: Run Coach + Fill .env
 
 ```bash
-dndev setup supabase
+dndev coach
 ```
 
-This command:
-- Lets you choose the target app (if you have an `apps/` directory)
-- Asks for your **public** Supabase project URL and public key
-- Writes `VITE_SUPABASE_URL` and `VITE_SUPABASE_PUBLIC_KEY` to your app's `.env`
+This prints a numbered checklist of what to configure. For Supabase, you'll need:
+- **Project URL** and **public key** → paste into your app's `.env`
+- **service_role key** → paste into `supabase/functions/.env`
 
-**We only ask for public credentials** (safe to ship in your client bundle). We never ask for the service_role key.
+Get these from: [Supabase Dashboard](https://supabase.com/dashboard) → your project → **Settings → API**.
 
-Get URL and public key from: [Supabase Dashboard](https://supabase.com/dashboard) → your project → **Settings → API**.
+Then run setup to validate and automate:
+
+```bash
+dndev setup
+```
+
+Setup validates your .env values are present, links the Supabase CLI, generates SQL migrations, and runs an inline health check.
 
 ---
 
 ## Step 2: Generate Tables from Entities
 
-The framework generates PostgreSQL migrations from your entity definitions. This runs automatically as part of `dndev setup supabase`, or you can run it separately:
+The framework generates PostgreSQL migrations from your entity definitions. This runs automatically as part of `dndev setup`, or you can run it separately:
 
 ```bash
-dndev setup supabase
+dndev setup
 ```
 
 During setup, the wizard detects your entities and generates SQL migrations.
@@ -200,7 +205,7 @@ Or install the [Supabase CLI](https://supabase.com/docs/guides/cli) and run `sup
 ## Troubleshooting
 
 **"Table not found" / "relation does not exist"**
-→ Run `dndev setup supabase` (generates SQL) then apply migrations with `supabase db push`
+→ Run `dndev setup` (generates SQL) then apply migrations with `supabase db push`
 
 **"Permission denied" / RLS errors**
 → Check RLS policies in Supabase Dashboard → Database → Policies
@@ -212,4 +217,4 @@ Or install the [Supabase CLI](https://supabase.com/docs/guides/cli) and run `sup
 
 ---
 
-**`dndev setup supabase` → paste URL + public key → apply migrations → `dndev dev`. The adapter normalizes everything automatically.**
+**`dndev coach` → fill .env → `dndev setup` → apply migrations → `dndev dev`. The adapter normalizes everything automatically.**

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

@@ -29,9 +29,32 @@ The framework scaffolds `vercel.json` with CSP headers, rewrites, and caching ru
 
 ---
 
-## Step 2: Set Environment Variables
+## Step 2: Add Credentials to `.env.local`
 
-In Vercel Dashboard → Settings → Environment Variables, copy the env vars from your `apps/<app>/.env`:
+Add these 3 values to `apps/<your-app>/.env.local`:
+
+```env
+# Vercel Deployment Credentials (gitignored — never commit these)
+VERCEL_TOKEN=your_vercel_token
+VERCEL_ORG_ID=your_team_id
+VERCEL_PROJECT_ID=your_project_id
+```
+
+**Where to find them:**
+
+| Variable | Where |
+|----------|-------|
+| `VERCEL_TOKEN` | [vercel.com/account/tokens](https://vercel.com/account/tokens) — scope to your team |
+| `VERCEL_ORG_ID` | Vercel Dashboard → Settings → General → **Team ID** |
+| `VERCEL_PROJECT_ID` | Vercel Dashboard → Your Project → Settings → General → **Project ID** |
+
+That's it. No `vercel login`, no `vercel link`, no interactive prompts.
+
+---
+
+## Step 3: Set App Environment Variables
+
+In **Vercel Dashboard → Project → Settings → Environment Variables**, add your app's env vars:
 
 **If using Firebase:**
 - `VITE_FIREBASE_API_KEY`
@@ -57,26 +80,20 @@ For Next.js apps, replace the `VITE_` prefix with `NEXT_PUBLIC_` (same var names
 
 ---
 
-## Step 3: Deploy
-
-**Option A — Git push (recommended)**
-
-Push to your connected branch. Vercel auto-deploys.
+## Step 4: Deploy
 
 ```bash
-git push origin main
+dndev deploy
 ```
 
-**Option B — CLI**
+That's it. The CLI reads your credentials from `.env.local` and deploys to production.
 
-```bash
-dndev deploy
-```
+**Option B — Git push (auto-deploy)**
 
-Or directly:
+If your repo is connected to Vercel, pushing to your branch auto-deploys:
 
 ```bash
-bunx vercel --prod
+git push origin main
 ```
 
 ---
@@ -140,7 +157,7 @@ Available: auth (claims, status, delete account), billing (checkout, cancel, por
 | File | What Goes Here | Loaded By |
 |------|---------------|-----------|
 | `apps/<app>/.env` | Public keys (backend config, license key, Stripe publishable) | Vite/Next.js (dev + build) |
-| `apps/<app>/.env.local` | Local overrides (gitignored) | Vite/Next.js (overrides .env) |
+| `apps/<app>/.env.local` | Secrets: `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID` (gitignored) | `dndev deploy` |
 | `apps/<app>/.env.production` | Production overrides | Vite/Next.js (build --mode production) |
 | Vercel Dashboard | All production env vars (client + server) | Vercel runtime |
 
@@ -175,6 +192,10 @@ dndev emu start
 
 ## Troubleshooting
 
+**"Missing Vercel credentials"**
+→ Check `apps/<app>/.env.local` has all 3 vars: `VERCEL_TOKEN`, `VERCEL_ORG_ID`, `VERCEL_PROJECT_ID`
+→ Run `dndev setup` to validate
+
 **"Build fails on Vercel"**
 → Check Root Directory is set to your app directory
 → Ensure `package.json` has correct `build` script
@@ -190,4 +211,4 @@ dndev emu start
 
 ---
 
-**Import repo in Vercel → set env vars → `git push`. Vercel deploys automatically.**
+**3 values in `.env.local` → `dndev deploy` → done.**