@donotdev/cli 0.0.3

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

@@ -0,0 +1,98 @@
+# DoNotDev Framework - Agent Quick Start
+
+**For AI Agents: Read this first.**
+
+---
+
+## Prime Directive
+
+**Framework-first.** 90% of what you need already exists. Discover and use before building custom.
+
+**Trust conventions.** File-based routing, auto-discovery, defaults work.
+
+**Zero CSS.** Component props only. No inline styles, no custom CSS (unless explicitly needed).
+
+**Strict typing.** TypeScript mandatory. `any` forbidden. `import type` for types.
+
+---
+
+## Setup Guides (Read These)
+
+**Core setup:**
+- [PAGES_SETUP.md](./PAGES_SETUP.md) - Drop `*Page.tsx`, get routes
+- [CONFIG_SETUP.md](./CONFIG_SETUP.md) - `app.ts` + `vite.config.ts`
+- [EMULATOR_SETUP.md](./EMULATOR_SETUP.md) - Local secrets (.env.local)
+- [I18N_SETUP.md](./I18N_SETUP.md) - Drop `*_en.json`, get languages
+- [THEMING_SETUP.md](./THEMING_SETUP.md) - Override `themes.css`
+
+**Features:**
+- [AUTH_SETUP.md](./AUTH_SETUP.md) - Authentication
+- [BILLING_SETUP.md](./BILLING_SETUP.md) - Stripe subscriptions
+
+**Reference:**
+- [HOW_TO_USE.md](./HOW_TO_USE.md) - Component composition philosophy
+- [COMPONENTS.md](./COMPONENTS.md) - Component catalog
+- [LAYOUTS.md](./LAYOUTS.md) - Layout presets
+- [INDEX.md](./INDEX.md) - Full guide navigation
+
+---
+
+## Import Rules
+
+```tsx
+// ✅ Correct
+import { Button } from '@donotdev/components';
+import { useAuth } from '@donotdev/auth';
+import type { PageMeta } from '@donotdev/core';
+
+// ❌ Wrong
+import { Button } from '@donotdev/components/src/atomic/Button';
+import { PageMeta } from '@donotdev/core';  // Missing 'type'
+```
+
+See [IMPORT_PATTERNS.md](./IMPORT_PATTERNS.md)
+
+---
+
+## Component Philosophy
+
+**Props, not CSS:**
+
+```tsx
+// ✅ Correct
+<Card title="Feature" subtitle="Description" icon={Rocket} elevated />
+
+// ❌ Wrong
+<Card style={{ padding: '2rem' }}>
+  <CardTitle>Feature</CardTitle>
+</Card>
+```
+
+**Composition, not nesting:**
+
+```tsx
+// ✅ Correct
+<Section gridCols={3} tone="muted">
+  <Card title="One" />
+  <Card title="Two" />
+  <Card title="Three" />
+</Section>
+
+// ❌ Wrong - writing custom CSS
+<div className="my-custom-grid">...</div>
+```
+
+---
+
+## 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.**
+
+---
+
+**Start building. Framework handles the rest.**

package/templates/root-consumer/guides/APP_CHECK_SETUP.md.example

@@ -0,0 +1,111 @@
+# App Check Setup (Abuse Protection)
+
+**For AI Agents:** Configure reCAPTCHA key. Framework auto-enables App Check for all Firebase resources.
+
+---
+
+## 1. Environment Variables
+
+**Vite:**
+```bash
+# .env
+VITE_RECAPTCHA_SITE_KEY=6LcXXXX...         # reCAPTCHA v3 site key
+VITE_APPCHECK_DEBUG_TOKEN=XXXX-XXXX-XXXX   # Optional: localhost testing
+```
+
+**Next.js:**
+```bash
+# .env.local
+NEXT_PUBLIC_RECAPTCHA_SITE_KEY=6LcXXXX...
+NEXT_PUBLIC_APPCHECK_DEBUG_TOKEN=XXXX-XXXX-XXXX
+```
+
+**Functions (.env):**
+```bash
+ENFORCE_APP_CHECK=false   # Set 'true' to reject requests without tokens
+```
+
+---
+
+## 2. Get reCAPTCHA Enterprise Key
+
+1. Go to [Google Cloud Console - reCAPTCHA](https://console.cloud.google.com/security/recaptcha)
+2. Create key:
+   - Platform: Website
+   - Type: Score-based (checkbox optional)
+   - Domains: `localhost`, `yourdomain.com`
+3. Copy Site Key (starts with `6L...`)
+
+> First 1M calls/month are free.
+
+---
+
+## 3. Enable in Firebase Console
+
+1. [Firebase Console](https://console.firebase.google.com) → **App Check**
+2. Click **Register app** → select your web app
+3. Choose **reCAPTCHA v3**, paste Site Key
+4. Save
+
+---
+
+## 4. Localhost Debug Token
+
+reCAPTCHA doesn't work on localhost. Use debug tokens:
+
+1. Start app in dev mode
+2. Check console for: `App Check debug token: XXXXXXXX-XXXX-...`
+3. Copy token
+4. Firebase Console → App Check → **Manage debug tokens**
+5. Add token with name (e.g., "Local Dev - John")
+6. Add to `.env`:
+   - Vite: `VITE_APPCHECK_DEBUG_TOKEN=XXXXXXXX-XXXX-...`
+   - Next.js: `NEXT_PUBLIC_APPCHECK_DEBUG_TOKEN=XXXXXXXX-XXXX-...`
+
+---
+
+## 5. How It Works
+
+**Automatic:**
+- Framework detects `RECAPTCHA_SITE_KEY` env var
+- Auto-initializes App Check during Firebase init
+- All Firebase requests include tokens automatically
+- No code changes needed
+
+**Server-side:**
+- Default: Logs warnings for missing tokens
+- Set `ENFORCE_APP_CHECK=true` to reject invalid requests
+
+---
+
+## 6. Verification
+
+**Console messages:**
+| Message | Status |
+|---------|--------|
+| `[AppCheck] Enabled - all Firebase requests are protected` | Working |
+| `[AppCheck] Not configured...` | Key missing (prod only) |
+| `[AppCheck] Missing token for <operation>` | Server warning |
+
+---
+
+## 7. Rollout Strategy
+
+1. **Monitor:** Deploy without enforcement, check logs
+2. **Enforce:** Set `ENFORCE_APP_CHECK=true` when ready
+
+---
+
+## What App Check Protects
+
+- Bot/script attacks
+- Unauthorized API access
+- Request replay attacks
+
+**Does NOT replace:** Firebase Auth, Firestore Rules, Rate Limiting
+
+---
+
+**Files to configure:**
+- `.env` or `.env.local` - Add reCAPTCHA key
+- `functions/.env` - Optional enforcement

package/templates/root-consumer/guides/AUTH_SETUP.md.example

@@ -0,0 +1,92 @@
+# Authentication Setup
+
+**For AI Agents:** Configure auth providers and routes. Framework handles the rest.
+
+---
+
+## 1. Environment Variables
+
+```bash
+# .env
+VITE_AUTH_PARTNERS=password,emailLink,google,github,facebook
+```
+
+**Available Firebase Auth providers:** `password`, `emailLink`, `google`, `github`, `facebook`, `twitter`, `microsoft`, `yahoo`, `apple`
+
+**Default:** If not set, only `google` is enabled.
+
+---
+
+## 2. App Configuration
+
+```typescript
+// apps/your-app/src/config/app.ts
+import type { AppConfig } from '@donotdev/core';
+
+export const appConfig: AppConfig = {
+  auth: {
+    authRoute: '/login',   // Redirect when auth required (default: '/login')
+    roleRoute: '/404',      // Redirect when role insufficient (default: '/404')
+    tierRoute: '/404',      // Redirect when tier insufficient (default: '/404')
+    loginPath: '/login',   // Optional: Login page path (undefined = show providers in header)
+    profilePath: '/profile', // Optional: Profile page path (default: '/profile')
+  },
+};
+```
+
+---
+
+## 3. Firebase Console Setup
+
+**User must enable providers in Firebase Console:**
+- Authentication > Sign-in method
+- Enable Email/Password (for `password` and `emailLink`)
+- Enable OAuth providers (Google, GitHub, etc.) and configure credentials
+
+---
+
+## What You Get
+
+**Automatic:**
+- ✅ `AuthHeader` component in layout (null if auth not needed)
+- ✅ OAuth callbacks handled automatically
+- ✅ Protected routes via `PageMeta.auth`
+- ✅ Session management
+
+**Components:**
+- `AuthHeader`, `AuthMenu` from `@donotdev/ui`
+- `LoginTemplate` from `@donotdev/templates`
+- `EmailPasswordForm`, `MultipleAuthProviders` from `@donotdev/auth`
+
+**Hook:**
+```typescript
+import { useAuth } from '@donotdev/auth';
+
+const user = useAuth('user');
+const signIn = useAuth('signInWithEmail');
+const signOut = useAuth('signOut');
+```
+
+---
+
+## Protected Route Example
+
+```typescript
+// apps/your-app/src/pages/DashboardPage.tsx
+export const meta = {
+  namespace: 'dashboard',
+  auth: { required: true }, // ← Protected route
+};
+
+export default function DashboardPage() {
+  const user = useAuth('user');
+  return <PageContainer>Welcome, {user?.displayName}!</PageContainer>;
+}
+```
+
+---
+
+**Files to modify:**
+- `.env` - Add `VITE_AUTH_PARTNERS`
+- `src/config/app.ts` - Add `auth` config
+- `src/pages/**/*.tsx` - Add `auth` to `PageMeta` for protected routes

package/templates/root-consumer/guides/BILLING_SETUP.md.example

@@ -0,0 +1,120 @@
+# Billing Setup
+
+**For AI Agents:** Create Stripe config files. Framework handles checkout, webhooks, subscriptions.
+
+---
+
+## 1. Environment Variables
+
+**Local Emulators (.env.local):**
+```bash
+# apps/your-app/functions/.env.local
+STRIPE_SECRET_KEY=sk_test_xxx
+STRIPE_WEBHOOK_SECRET=whsec_xxx        # Get from 'stripe listen'
+```
+
+**Production (.env):**
+```bash
+# apps/your-app/functions/.env
+STRIPE_SECRET_KEY=sk_live_xxx
+STRIPE_WEBHOOK_SECRET=whsec_xxx        # Permanent production secret
+```
+
+**Frontend (.env):**
+```bash
+# apps/your-app/.env
+VITE_STRIPE_PUBLISHABLE_KEY=pk_test_xxx
+```
+
+---
+
+## 2. Stripe Dashboard
+
+**User must:**
+1. Create products in Stripe Dashboard
+2. Copy Price IDs (starts with `price_...`)
+
+---
+
+## 3. Frontend Config
+
+```typescript
+// apps/your-app/src/config/stripeFrontConfig.ts
+import type { StripeFrontConfig } from '@donotdev/core';
+
+export const stripeFrontConfig: StripeFrontConfig = {
+  pro_plan: {
+    name: 'Pro Plan',
+    price: 29,
+    currency: 'USD',
+    description: 'Perfect for growing teams',
+    features: ['Unlimited projects', 'Priority support'],
+    priceId: 'price_1234567890', // ← Stripe Price ID
+    allowPromotionCodes: true,
+  },
+};
+```
+
+---
+
+## 4. Backend Config
+
+```typescript
+// apps/your-app/functions/src/config/stripeBackConfig.ts
+import type { StripeBackConfig } from '@donotdev/core';
+
+export const stripeBackConfig: StripeBackConfig = {
+  pro_plan: {
+    type: 'StripeSubscription', // or 'StripePayment'
+    name: 'Pro Plan',
+    price: 2900, // In cents
+    currency: 'USD',
+    priceId: process.env.STRIPE_PRICE_PRO_PLAN!,
+    tier: 'pro',
+    duration: 'month',
+
+    // Optional hooks
+    onPurchaseSuccess: async (userId, metadata) => {
+      // Grant features, send email, etc.
+    },
+    onSubscriptionCancelled: async (userId) => {
+      // Revoke features, etc.
+    },
+  },
+};
+```
+
+---
+
+## 5. Wire Up Functions
+
+```typescript
+// apps/your-app/functions/src/index.ts
+import { createCheckoutSession } from '@donotdev/functions/firebase';
+import { stripeBackConfig } from './config/stripeBackConfig';
+
+export const createCheckout = createCheckoutSession(stripeBackConfig);
+```
+
+---
+
+## What You Get
+
+**Components:**
+- `SubscriptionTemplate`, `PaymentTemplate` from `@donotdev/templates`
+- `ProductCard`, `SubscriptionManager` from `@donotdev/billing`
+
+**Hook:**
+```typescript
+import { useStripeBilling } from '@donotdev/billing';
+
+const checkout = useStripeBilling('checkout');
+await checkout({ priceId: 'price_123', mode: 'subscription' });
+```
+
+---
+
+**Files to create:**
+- `src/config/stripeFrontConfig.ts` - Frontend config
+- `functions/src/config/stripeBackConfig.ts` - Backend config
+- `functions/src/index.ts` - Wire up functions

package/templates/root-consumer/guides/CLI.md.example

@@ -0,0 +1,293 @@
+# DoNotDev CLI Guide
+
+**Status:** Up to date with implementation.
+
+**Professional, cross-platform CLI for DoNotDev framework**
+
+## Installation
+
+```bash
+bun install -g @donotdev/cli
+```
+
+## Getting Started
+
+### Initialize a New Project
+
+```bash
+dndev init [project-name]
+```
+
+Creates a new DoNotDev project. If no name is provided, creates in current directory.
+
+```bash
+cd my-project
+bun install
+```
+
+## App Commands
+
+All app commands support smart app detection:
+
+### Development
+
+```bash
+# Launch specific app in development mode
+dndev dev:my-app
+
+# If only one app exists, you can omit the app name
+dndev dev
+
+# If multiple apps exist, you'll be prompted to choose
+dndev dev
+# ? Select app: (Use arrow keys)
+#   > my-app
+#     admin-panel
+#     landing-page
+```
+
+The CLI automatically detects your Vite app and runs the dev server.
+
+### Development with Emulators
+
+```bash
+# Launch app with Firebase emulators
+dndev emu:my-app
+
+# Smart detection works here too
+dndev emu
+```
+
+### Build
+
+```bash
+# Build specific app for production (prompts for frontend/functions/both)
+dndev build:my-app
+
+# Build with explicit type
+dndev build:my-app:front    # Frontend only
+dndev build:my-app:func     # Functions only
+dndev build:my-app:both     # Both frontend and functions
+
+# Smart detection
+dndev build
+```
+
+**Build prompts:**
+
+- If app has both frontend and functions:
+  ```
+  ? What would you like to build?
+    > Frontend only
+      Functions only
+      Both (frontend + functions)
+  ```
+- If app has only frontend or only functions, builds automatically
+
+### Preview
+
+```bash
+# Preview production build (builds if needed)
+dndev preview:my-app
+
+# Smart detection
+dndev preview
+```
+
+### Deploy
+
+```bash
+# Deploy app (asks what to deploy if both frontend and functions exist)
+dndev deploy:my-app
+
+# Smart detection
+dndev deploy
+```
+
+**Deployment prompts:**
+
+- If app has both frontend and functions:
+  ```
+  ? What would you like to deploy?
+    > Frontend only
+      Functions only
+      Both (frontend + functions)
+  ```
+- If app has only frontend or only functions, deploys automatically
+
+## Utility Commands
+
+### Format Code
+
+```bash
+dndev format
+```
+
+Formats code according to framework standards.
+
+### Clean
+
+```bash
+dndev clean
+```
+
+Removes build artifacts, caches, and `node_modules`. Use when troubleshooting build issues, then it'll bun install
+
+### Clear Caches
+
+```bash
+dndev cacheout
+```
+
+Clears build caches (`.turbo`, `.next`, `dist`, .vite, tsconfig.json.buildinfo, ...) without removing `node_modules`. Faster than `clean`.
+Use when you've made many changes to your app to make sure you don't have stale code.
+
+### Lint
+
+```bash
+# Check for linting issues
+dndev lint
+
+# Auto-fix linting issues
+dndev lint:fix
+```
+
+## Smart App Detection
+
+The CLI automatically detects apps in your project:
+
+1. **Single app**: Commands work without specifying app name
+
+   ```bash
+   dndev dev  # Uses the only app automatically
+   ```
+
+2. **Multiple apps**: CLI prompts you to choose
+
+   ```bash
+   dndev dev
+   # ? Select app:
+   #   > my-app
+   #     admin-panel
+   ```
+
+3. **Explicit app name**: Always works
+   ```bash
+   dndev dev:my-app  # Always uses my-app
+   ```
+
+## App Detection Logic
+
+The CLI looks for apps in:
+
+- `apps/*/package.json` (monorepo structure)
+- `package.json` with `name` matching app pattern (single app projects)
+
+For each app, it detects:
+
+- **Framework**: Vite (SPA)
+- **Backend**: Whether functions directory exists
+- **Platform**: Firebase or Vercel (from config files)
+
+## Examples
+
+### Monorepo with Multiple Apps
+
+```bash
+# Project structure:
+# apps/
+#   ├── web/          (Vite app)
+#   ├── admin/        (Vite app)
+#   └── api/          (Functions only)
+
+# Develop web app
+dndev dev:web
+
+# Deploy admin app
+dndev deploy:admin
+# ? What would you like to deploy?
+#   > Frontend only
+#     Functions only
+#     Both
+
+# Build all (if you have a build:all script)
+dndev build
+# ? Select app: web
+```
+
+### Single App Project
+
+```bash
+# Project structure:
+# package.json
+# src/
+# functions/
+
+# All commands work without app name
+dndev dev        # Automatically uses the app
+dndev build      # Automatically uses the app
+dndev deploy     # Automatically uses the app
+```
+
+## Cross-Platform Support
+
+The CLI works seamlessly on:
+
+- ✅ Windows (PowerShell, CMD)
+- ✅ Windows Subsystem for Linux (WSL)
+- ✅ macOS
+- ✅ Linux
+
+All commands use cross-platform path handling and work identically across platforms.
+
+## Error Handling
+
+The CLI provides clear error messages:
+
+```bash
+$ dndev dev:non-existent
+❌ App "non-existent" not found.
+
+Available apps:
+  - my-app
+  - admin-panel
+
+Run 'dndev dev' to select interactively.
+```
+
+## Best Practices
+
+1. **Use smart detection**: Omit app names when working with a single app
+2. **Be explicit in CI/CD**: Always specify app names in scripts
+3. **Use cacheout**: Clear caches before troubleshooting instead of full clean
+4. **Format before commit**: Run `dndev format` before committing code
+
+## Advanced Usage
+
+### Environment Variables
+
+The CLI respects environment variables:
+
+```bash
+# Skip build during deploy
+SKIP_BUILD=true dndev deploy:my-app
+
+# Verbose output
+VERBOSE=true dndev build:my-app
+```
+
+### Custom Scripts
+
+You can still use `package.json` scripts directly:
+
+```bash
+bun run dev:my-app
+bun run build:my-app
+```
+
+But `dndev` commands provide:
+
+- Cross-platform compatibility
+- Smart app detection
+- Consistent interface
+- Better error messages