@donotdev/cli 0.0.18 → 0.0.19

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.**

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

@@ -13,7 +13,7 @@ import { Link, useNavigate, useParams } from 'react-router-dom'; // ❌ BREAKS F
 
 **✅ CORRECT:**
 ```tsx
-import { Link, useNavigate, useParams } from '@donotdev/ui/routing'; // ✅ Framework routing
+import { Link, useNavigate, useParams } from '@donotdev/ui'; // ✅ Framework routing
 ```
 
 **Why?** The framework's routing components:
@@ -30,7 +30,7 @@ import { Link, useNavigate, useParams } from '@donotdev/ui/routing'; // ✅ Fram
 ### Components
 
 ```tsx
-import { Link, DnDevNavigationMenu } from '@donotdev/ui/routing';
+import { Link, DnDevNavigationMenu } from '@donotdev/ui';
 ```
 
 **Link Component:**
@@ -55,7 +55,7 @@ import {
   useRouteParam,
   useSearchParams,
   useNavigationItems,
-} from '@donotdev/ui/routing';
+} from '@donotdev/ui';
 ```
 
 ---
@@ -66,7 +66,7 @@ import {
 
 **✅ Use framework Link:**
 ```tsx
-import { Link } from '@donotdev/ui/routing';
+import { Link } from '@donotdev/ui';
 
 function ProductCard({ product }) {
   return (
@@ -77,7 +77,7 @@ function ProductCard({ product }) {
 
 **✅ Use framework useNavigate:**
 ```tsx
-import { useNavigate } from '@donotdev/ui/routing';
+import { useNavigate } from '@donotdev/ui';
 
 function ProductForm() {
   const navigate = useNavigate();
@@ -107,7 +107,7 @@ function ProductForm() {
 
 **✅ Use framework useRouteParam:**
 ```tsx
-import { useRouteParam } from '@donotdev/ui/routing';
+import { useRouteParam } from '@donotdev/ui';
 
 function ProductPage() {
   const id = useRouteParam('id'); // ✅ Returns string | undefined
@@ -117,7 +117,7 @@ function ProductPage() {
 
 **✅ Or use framework useParams:**
 ```tsx
-import { useParams } from '@donotdev/ui/routing';
+import { useParams } from '@donotdev/ui';
 
 function ProductPage() {
   const params = useParams();
@@ -136,7 +136,7 @@ import { useParams } from 'react-router-dom'; // ❌ Type issues, breaks framewo
 
 **✅ Use DnDevNavigationMenu (auto-fetches routes):**
 ```tsx
-import { DnDevNavigationMenu, DISPLAY } from '@donotdev/ui/routing';
+import { DnDevNavigationMenu, DISPLAY } from '@donotdev/ui';
 
 function Sidebar() {
   return (
@@ -151,7 +151,7 @@ function Sidebar() {
 
 **✅ Or use useNavigationItems for custom sidebar:**
 ```tsx
-import { Link, useNavigationItems } from '@donotdev/ui/routing';
+import { Link, useNavigationItems } from '@donotdev/ui';
 
 function CustomSidebar() {
   const menuItems = useNavigationItems(); // ✅ Auth-filtered routes
@@ -194,7 +194,7 @@ function Sidebar() {
 
 **✅ Use framework useNavigate:**
 ```tsx
-import { useNavigate } from '@donotdev/ui/routing';
+import { useNavigate } from '@donotdev/ui';
 
 function LoginForm() {
   const navigate = useNavigate();
@@ -228,7 +228,7 @@ navigate('/products', {
 
 **✅ Use framework useSearchParams (read-only, returns URLSearchParams directly):**
 ```tsx
-import { useSearchParams } from '@donotdev/ui/routing';
+import { useSearchParams } from '@donotdev/ui';
 
 function ProductList() {
   const searchParams = useSearchParams();
@@ -240,7 +240,7 @@ function ProductList() {
 
 **✅ Or use useQueryParams helper:**
 ```tsx
-import { useQueryParams } from '@donotdev/ui/routing';
+import { useQueryParams } from '@donotdev/ui';
 
 function ProductList() {
   const { page, sort } = useQueryParams({ page: '1', sort: 'name' });
@@ -254,7 +254,7 @@ function ProductList() {
 
 **✅ Use framework useMatch:**
 ```tsx
-import { useMatch } from '@donotdev/ui/routing';
+import { useMatch } from '@donotdev/ui';
 
 function NavigationItem({ path }) {
   const isActive = useMatch(path);
@@ -360,7 +360,7 @@ import { Link, useNavigate } from 'react-router-dom';
 **Fix:**
 ```tsx
 // ✅ CORRECT
-import { Link, useNavigate } from '@donotdev/ui/routing';
+import { Link, useNavigate } from '@donotdev/ui';
 ```
 
 ---
@@ -416,7 +416,7 @@ function Sidebar() {
 **Fix:**
 ```tsx
 // ✅ CORRECT
-import { DnDevNavigationMenu } from '@donotdev/ui/routing';
+import { DnDevNavigationMenu } from '@donotdev/ui';
 
 function Sidebar() {
   return <DnDevNavigationMenu vertical />; // Auto-fetches routes
@@ -437,7 +437,7 @@ import { Link } from 'react-router-dom';
 **Fix:**
 ```tsx
 // ✅ CORRECT
-import { Link } from '@donotdev/ui/routing';
+import { Link } from '@donotdev/ui';
 
 <Link path="/products" label="Products" />
 ```
@@ -459,7 +459,7 @@ import {
   useSearchParams,
   useNavigationItems,
   DnDevNavigationMenu,
-} from '@donotdev/ui/routing';
+} from '@donotdev/ui';
 ```
 
 ### Common Patterns
@@ -489,7 +489,7 @@ const menuItems = useNavigationItems(); // Auth-filtered routes
 
 ## Summary
 
-1. **Always use `@donotdev/ui/routing`** - never `react-router-dom`
+1. **Always import from `@donotdev/ui`** — never `react-router-dom`
 2. **Use `DnDevNavigationMenu`** for sidebars/headers
 3. **Use `useNavigationItems()`** for custom navigation
 4. **Don't use `<Outlet />` manually** - framework handles it

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

@@ -1,9 +1,10 @@
 /**
- * Reference: Framework essences (Brutalist, Luxury).
+ * Reference: Framework essences (Brutalist, Luxury, Retro).
  * Copy the blocks you need into your app's src/themes.css.
  * Default essence = SaaS (Inter); these do not apply until you set the class on <html>.
  *
- * Fonts: Space Grotesk (Brutalist), Playfair Display (Luxury), Inter, Roboto are bundled in @donotdev/ui (no external requests).
+ * Fonts: Space Grotesk (Brutalist), Playfair Display (Luxury), Press Start 2P (Retro),
+ * Inter, Roboto are bundled in @donotdev/ui (no external requests).
  */
 
 /** =========================================================================
@@ -172,3 +173,119 @@
   --shadow-md: 0 4px 12px var(--shadow-color);
   --shadow-xl: 0 8px 24px var(--shadow-color);
 }
+
+
+/** =========================================================================
+ *  Retro — 8-bit pixel aesthetic, Press Start 2P, neon on dark, CRT vibes.
+ *  Set <html class="retro"> to apply.
+ *  ========================================================================= */
+.retro {
+  --theme-icon: 'Gamepad2';
+  --theme-label: 'Retro';
+  --theme-is-dark: 1;
+
+  /* 1. Core Colors - Muted neon on zinc */
+  --background: #1c1c22;
+  --foreground: #c8e6c9;
+  --primary: #5eead4;
+  --secondary: #c084fc;
+  --accent: #fbbf24;
+
+  /* 2. Semantic */
+  --success: #6ee7b7;
+  --warning: #fbbf24;
+  --destructive: #f87171;
+
+  /* 3. Surfaces - Zinc CRT glass */
+  --muted: #27272f;
+  --muted-foreground: #8bae8b;
+  --border: #4a6a4a;
+  --input: #1c1c22;
+  --ring: #5eead4;
+  --card: #222228;
+  --card-foreground: #c8e6c9;
+  --popover: #222228;
+  --popover-foreground: #c8e6c9;
+  --surface-1: #1e1e24;
+
+  /* 4. Text on Colors */
+  --primary-foreground: #0f172a;
+  --secondary-foreground: #0f172a;
+  --accent-foreground: #0f172a;
+  --success-foreground: #0f172a;
+  --warning-foreground: #0f172a;
+  --destructive-foreground: #ffffff;
+
+  /* 5. Radius - Hard pixel corners */
+  --radius-interactive: 0;
+  --radius-surface: 0;
+  --radius-floating: 0;
+
+  /* 6. Typography - Press Start 2P (pixel font, 400 only) */
+  --font-family: 'Press Start 2P', var(--font-mono);
+  --font-headline: 'Press Start 2P', var(--font-mono);
+  --font-weight-normal: 400;
+  --font-weight-medium: 400;
+  --font-weight-semibold: 400;
+  --font-weight-bold: 400;
+
+  /* 7. Font scale - smaller base (pixel font reads large) */
+  --font-size-xs: 0.5rem;
+  --font-size-sm: 0.625rem;
+  --font-size-base: 0.75rem;
+  --font-size-lg: 0.875rem;
+  --font-size-xl: 1rem;
+  --font-size-2xl: 1.25rem;
+  --font-size-3xl: 1.5rem;
+  --line-height: 1.6;
+
+  /* 8. Borders - Chunky pixel borders */
+  --border-width: 3px;
+  --border-huge: 4px;
+
+  /* 9. Shadows — soft neon glow */
+  --shadow-color: #5eead433;
+  --shadow-sm: 0 0 4px #5eead422;
+  --shadow-md: 0 0 8px #5eead433, 0 0 16px #5eead41a;
+  --shadow-xl: 0 0 12px #5eead444, 0 0 24px #5eead42a, 0 0 48px #c084fc1a;
+  --shadow-cta: 0 0 16px #5eead444, 0 0 32px #5eead422;
+
+  /* 10. Per-variant shadows — soft neon matching */
+  --shadow-primary: 0 0 8px #5eead42a;
+  --shadow-primary-xl: 0 0 16px #5eead444, 0 0 32px #5eead422;
+  --shadow-secondary: 0 0 8px #c084fc2a;
+  --shadow-secondary-xl: 0 0 16px #c084fc44, 0 0 32px #c084fc22;
+
+  /* 11. Header padding */
+  --header-shadow-padding: 0;
+}
+
+/* Body - subtle CRT scanlines */
+.retro body {
+  background-color: var(--background);
+  background-image:
+    repeating-linear-gradient(
+      0deg,
+      transparent,
+      transparent 2px,
+      rgba(0, 0, 0, 0.08) 2px,
+      rgba(0, 0, 0, 0.08) 4px
+    );
+}
+
+/* Uppercase headings (pixel fonts look best in caps) */
+.retro {
+  :is(h1, h2, h3, h4, h5, h6),
+  [data-level^='h'] {
+    text-transform: uppercase;
+  }
+}
+
+/* Flat surfaces - no gradient, pixel-sharp */
+.retro .dndev-surface { background: var(--card); }
+.retro .dndev-surface[data-variant='outline'] { border: var(--border-width) solid var(--border); }
+
+.retro .dndev-card[data-variant='outline'] {
+  background: transparent;
+  box-shadow: none;
+}

package/templates/root-consumer/guides/wai-way/blueprints/1_scaffold.md.example

@@ -37,6 +37,20 @@ Apply the chosen essence (SaaS, Luxury, Brutalist) to your `src/themes.css`.
 
 ---
 
+## Reference: Demo App
+
+**Before creating pages, study the demo app:** `packages/cli/templates/app-demo/src/pages/`
+
+It shows the canonical pattern:
+- Thin page wrappers (~5 lines) that import templates
+- `PageMeta.preset` for per-route layout switching (landing → admin → docs)
+- Component showcase with filterable grid
+- Entity definition with `defineEntity()`
+
+**Copy from the demo app, customize for your spec.**
+
+---
+
 ## Step 3: Review Spec Pages
 
 From your spec, you have a list of pages. Now create them.

package/templates/root-consumer/guides/wai-way/blueprints/2_entities.md.example

@@ -46,6 +46,12 @@ export const productEntity = defineEntity({
 });
 ```
 
+> **Status field:** Auto-added with locked `type`, `visibility`, `editable`. Don't redefine those. To add custom options:
+> ```typescript
+> status: { validation: { options: [{ value: 'shipped', label: 'Shipped' }] } }
+> // Merged result: [draft, available, deleted, shipped]
+> ```
+
 ---
 
 ## Step 3: Export Entities

package/templates/root-consumer/guides/wai-way/blueprints/3_compose.md.example

@@ -20,6 +20,20 @@
 
 ---
 
+## Reference: Demo App
+
+**Before composing pages, study the demo app:** `packages/cli/templates/app-demo/src/pages/`
+
+It shows the canonical pattern:
+- Thin page wrappers (~5 lines) that import templates
+- `PageMeta.preset` for per-route layout switching (landing → admin → docs)
+- CRUD with `ProductCardListTemplate` + `defineEntity()`
+- Component showcase with filterable grid
+
+**Copy from the demo app, customize for your spec.**
+
+---
+
 ## Step 2: Read Page Patterns
 
 **READ:** `guides/wai-way/page_patterns.md` for all patterns:

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

@@ -309,12 +309,9 @@ export const orderEntity = defineEntity({
       visibility: 'owner',
       editable: 'never',
     },
+    // status is auto-added with type/visibility/editable locked.
+    // Only define validation.options — framework auto-adds [draft, available, deleted].
     status: {
-      name: 'status',
-      label: 'status',
-      type: 'select',
-      visibility: 'owner',
-      editable: 'admin',
       validation: {
         options: [
           { value: 'pending', label: 'Pending' },
@@ -341,6 +338,8 @@ export const orderEntity = defineEntity({
 });
 ```
 
+> **Merged status options:** `[draft, available, deleted, pending, paid, shipped, delivered, cancelled]`. The three defaults are always first and cannot be removed.
+
 ---
 
 ## Review