@donotdev/cli 0.0.3

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

@@ -0,0 +1,132 @@
+# Configuration Setup
+
+**For AI Agents:** Configure `src/config/app.ts` and `vite.config.ts`. Framework handles the rest.
+
+---
+
+## 1. App Configuration
+
+```typescript
+// src/config/app.ts
+import type { AppConfig } from '@donotdev/core';
+
+export const appConfig: AppConfig = {
+  app: {
+    name: 'My App',
+    url: 'https://myapp.com',
+  },
+
+  preset: 'landing', // landing | admin | moolti | docs | blog | game | plain
+
+  features: {
+    debug: false, // Enable debug tools
+    requiredCookies: ['necessary'], // Cookie consent categories
+  },
+
+  auth: {
+    authRoute: '/login',
+    roleRoute: '/404',
+    tierRoute: '/404',
+    loginPath: '/login',
+    profilePath: '/profile',
+  },
+
+  i18n: {
+    defaultLanguage: 'en',
+    fallbackLanguage: 'en',
+  },
+
+  theme: {
+    defaultTheme: 'light',
+  },
+};
+```
+
+---
+
+## 2. Vite Configuration
+
+```typescript
+// vite.config.ts
+import { defineViteConfig } from '@donotdev/core/vite';
+import { appConfig } from './src/config/app';
+
+export default defineViteConfig({
+  appConfig,  // Required
+});
+```
+
+**Done.** Routes, themes, and translations are automatically detected from your `src/` directory.
+
+---
+
+## 3. Optional Vite Options
+
+```typescript
+export default defineViteConfig({
+  appConfig,
+
+  // Debug
+  debug: true,
+  verbose: true,
+
+  // Debug options
+  routes: { debug: true },
+  themes: { debug: true },
+  i18n: { debug: true },
+
+  // Server
+  server: {
+    port: 3000,
+    https: true,
+  },
+
+  // Build
+  build: {
+    sourcemap: false,
+  },
+
+  // SEO
+  seo: {
+    disabled: false,
+    generateRobotsTxt: true,
+    generateSitemap: true,
+  },
+
+  // PWA
+  pwa: {
+    enabled: false,
+  },
+});
+```
+
+---
+
+## 4. Environment Variables
+
+```bash
+# .env
+VITE_APP_NAME="My App"
+VITE_APP_URL=http://localhost:5173
+
+# 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
+
+# Auth providers
+VITE_AUTH_PARTNERS=password,emailLink,google,github
+
+# Stripe
+VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_...
+STRIPE_API_VERSION=2025-08-27.basil
+```
+
+---
+
+**Zero config. Override when needed.**

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

@@ -0,0 +1,48 @@
+# Emulator Setup Guide
+
+This guide covers how to set up your local development environment for the Firebase Emulator Suite.
+
+## Environment Variables
+
+The DoNotDev framework uses a strict separation between local development and production secrets for functions.
+
+### Local Development (.env.local)
+
+**`.env.local` is the exclusive source of truth for emulators.** 
+
+When you run `dn emu <app-name>`, the framework loads environment variables **ONLY** from `functions/.env.local`.
+
+1. Create `functions/.env.local` (it is git-ignored by default).
+2. Add your local development keys (e.g., Stripe ephemeral webhook secret).
+
+```bash
+# functions/.env.local
+STRIPE_SECRET_KEY=sk_test_...
+STRIPE_WEBHOOK_SECRET=whsec_... # Get this from 'stripe listen' output
+```
+
+### Production Secrets (.env)
+
+**`.env` is the source of truth for production secrets.**
+
+These are the secrets that will be synced to Firebase Cloud Functions when you run `dn deploy` or `dn sync-secrets`.
+
+```bash
+# functions/.env
+STRIPE_SECRET_KEY=sk_live_...
+STRIPE_WEBHOOK_SECRET=whsec_... # Your permanent production webhook secret
+```
+
+## Running the Emulator
+
+```bash
+# Start emulators for a specific app
+dn emu showcase
+```
+
+If you need Stripe webhook forwarding, the emulator command will provide instructions on how to start the Stripe CLI and where to paste the temporary webhook secret.
+
+## Troubleshooting
+
+1. **Signature Verification Error**: This usually means the `STRIPE_WEBHOOK_SECRET` in your `functions/.env.local` does not match the secret displayed in your active `stripe listen` terminal.
+2. **Missing Secrets**: Ensure you have created the `functions/.env.local` file. The emulator command will warn you if it's missing.

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

@@ -0,0 +1,286 @@
+# Using Features
+
+**Optional features with graceful degradation**
+
+---
+
+## Available Features
+
+DoNotDev provides 4 optional feature packages:
+
+1. **@donotdev/auth** - Firebase Authentication
+2. **@donotdev/billing** - Stripe subscriptions
+3. **@donotdev/oauth** - OAuth providers (GitHub, Google)
+
+---
+
+## Installation
+
+Install only the features you need:
+
+```bash
+# Authentication
+bun add @donotdev/auth
+
+# Billing (requires auth)
+bun add @donotdev/billing
+
+# OAuth
+bun add @donotdev/oauth
+```
+
+---
+
+## Using Auth
+
+### Basic Usage
+
+```typescript
+import { useAuth } from '@donotdev/auth';
+
+export function ProfilePage() {
+  const isEnabled = useAuth('isAvailable');
+  const isLoading = useAuth('loading');
+  const user = useAuth('user');
+  const signOut = useAuth('signOut');
+
+  if (!isEnabled) {
+    return <div>Auth not available</div>;
+  }
+
+  if (isLoading) {
+    return <div>Loading...</div>;
+  }
+
+  if (!user) {
+    return <LoginPage />;
+  }
+
+  return (
+    <div>
+      <h1>Welcome, {user.displayName}!</h1>
+      <button onClick={() => signOut()}>Logout</button>
+    </div>
+  );
+}
+```
+
+### Login
+
+```typescript
+const signInWithEmail = useAuth('signInWithEmail');
+
+async function handleLogin(email: string, password: string) {
+  try {
+    await signInWithEmail(email, password);
+    // User is now authenticated
+  } catch (error) {
+    console.error('Login failed:', error);
+  }
+}
+```
+
+### Sign Up
+
+```typescript
+const signUpWithEmail = useAuth('signUpWithEmail');
+
+async function handleSignUp(email: string, password: string) {
+  try {
+    await signUpWithEmail(email, password);
+    // User account created and authenticated
+  } catch (error) {
+    console.error('Sign up failed:', error);
+  }
+}
+```
+
+---
+
+## Using Billing
+
+**Requires:** `@donotdev/auth` installed
+
+### Check Subscription
+
+```typescript
+import { useStripeBilling } from '@donotdev/billing';
+
+export function UpgradePage() {
+  const isEnabled = useStripeBilling('isAvailable');
+  const subscription = useStripeBilling('subscription');
+  const checkout = useStripeBilling('checkout');
+
+  if (!isEnabled) {
+    return <div>Billing not available</div>;
+  }
+
+  return (
+    <div>
+      <h2>Current Plan: {subscription?.planId || 'Free'}</h2>
+      <button onClick={() => checkout({ priceId: 'pro', mode: 'subscription' })}>
+        Upgrade to Pro
+      </button>
+    </div>
+  );
+}
+```
+
+### Create Checkout Session
+
+```typescript
+const checkout = useStripeBilling('checkout');
+
+async function handleUpgrade() {
+  try {
+    // The checkout function handles redirecting to Stripe
+    await checkout({
+      priceId: 'pro', // The ID of the Stripe Price
+      mode: 'subscription',
+      successUrl: window.location.href, // Optional: URL to redirect on success
+      cancelUrl: window.location.origin, // Optional: URL to redirect on cancellation
+    });
+  } catch (error) {
+    console.error('Checkout failed:', error);
+  }
+}
+```
+
+---
+
+## Using OAuth
+
+### GitHub OAuth
+
+```typescript
+import { useOAuth } from '@donotdev/oauth';
+
+export function ConnectGitHub() {
+  const isEnabled = useOAuth('isAvailable');
+  const signInWithGitHub = useOAuth('signInWithGitHub');
+
+  if (!isEnabled) {
+    return null;
+  }
+
+  async function handleConnect() {
+    try {
+      await signInWithGitHub();
+      // User connected to GitHub
+    } catch (error) {
+      console.error('GitHub connection failed:', error);
+    }
+  }
+
+  return (
+    <button onClick={handleConnect}>
+      Connect GitHub
+    </button>
+  );
+}
+```
+
+---
+
+## Feature Detection
+
+All features export `use{Feature}()` hooks that include `isAvailable` check:
+
+```typescript
+import { useAuth } from '@donotdev/auth';
+import { useStripeBilling } from '@donotdev/billing';
+
+export function Navigation() {
+  const authIsAvailable = useAuth('isAvailable');
+  const user = useAuth('user');
+  const billingIsAvailable = useStripeBilling('isAvailable');
+
+  return (
+    <nav>
+      <Link to="/home">Home</Link>
+
+      {authIsAvailable && user && (
+        <Link to="/dashboard">Dashboard</Link>
+      )}
+
+      {billingIsAvailable && (
+        <Link to="/upgrade">Upgrade</Link>
+      )}
+    </nav>
+  );
+}
+```
+
+**Benefits:**
+
+- Features lazy-load when needed
+- Graceful degradation if not installed
+- Tree-shaking removes unused features
+
+---
+
+## Configuration
+
+### Firebase (for Auth)
+
+```typescript
+// src/App.tsx
+import { ViteAppProviders } from '@donotdev/ui';
+
+<ViteAppProviders
+  firebaseConfig={{
+    apiKey: import.meta.env.VITE_FIREBASE_API_KEY,
+    authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
+    projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
+    // ...
+  }}
+>
+  {/* Your app */}
+</ViteAppProviders>
+```
+
+### Stripe (for Billing)
+
+Set environment variables:
+
+```bash
+# .env
+VITE_STRIPE_PUBLISHABLE_KEY=pk_test_...
+```
+
+---
+
+## Protected Routes
+
+Use `meta.auth.required` to protect pages:
+
+```typescript
+import type { PageMeta } from '@donotdev/core';
+
+export const meta: PageMeta = {
+  auth: { required: true },
+};
+
+export function DashboardPage() {
+  // User is guaranteed to be authenticated here
+  return <div>Dashboard</div>;
+}
+```
+
+---
+
+## Best Practices
+
+- ✅ Always check `isEnabled` before using features
+- ✅ Handle loading and error states
+- ✅ Use feature detection for conditional UI
+- ✅ Set up environment variables properly
+- ❌ Don't assume features are installed
+- ❌ Don't call feature methods without checking `isEnabled`
+
+---
+
+**Related:**
+
+- [INSTALLATION.md](../../INSTALLATION.md) - Installing packages
+- [docs/architecture/FEATURE_DETECTION.md](../architecture/FEATURE_DETECTION.md) - How feature detection works

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

@@ -0,0 +1,97 @@
+# Framework Overview
+
+**DoNotDev Package Ecosystem**
+
+---
+
+## Free Public Tools
+
+**`@donotdev/cli`** - Command-line tool for scaffolding, dev servers, deployment
+
+**`@donotdev/components`** - UI component library (standalone, can use anywhere)
+
+**`@donotdev/templates`** - Pre-built page templates (open to contributions)
+
+---
+
+## Paid Framework Packages
+
+**Foundation:**
+
+- `@donotdev/core` - Engine (utilities, hooks, types, state management)
+- `@donotdev/ui` - Composition layer (layouts, routing, feature integration)
+
+**Features** (install what you need):
+
+- `@donotdev/auth` - Authentication & authorization
+- `@donotdev/billing` - Stripe integration
+- `@donotdev/crud` - Data operations (forms, tables)
+- `@donotdev/oauth` - Social sign-on
+
+**Backend:**
+
+- `@donotdev/firebase` - Firebase platform
+- `@donotdev/functions` - Serverless function templates (Firebase/Vercel)
+
+---
+
+## Architecture
+
+```
+Your App
+├── @donotdev/ui (Layouts, Routing)
+├── @donotdev/templates (Pre-built Pages)
+├── Features (auth, billing, crud - optional)
+└── @donotdev/core (Foundation)
+```
+
+**Key:** Framework detects installed features, keeps bundle lean.
+
+---
+
+## Getting Started
+
+**1. Install CLI:**
+
+```bash
+npm install -g @donotdev/cli
+```
+
+**2. Create project:**
+
+```bash
+dndev init my-app
+```
+
+**3. Add features:**
+
+```bash
+cd my-app
+npm install @donotdev/auth @donotdev/billing
+```
+
+**4. Start dev server:**
+
+```bash
+dndev dev
+```
+
+---
+
+## Import Pattern
+
+Import everything from `@donotdev/core`:
+
+```typescript
+import { useAuth, useTranslation, useThemeStore } from '@donotdev/core';
+```
+
+Import UI components from `@donotdev/ui`:
+
+```typescript
+import { Button, Card } from '@donotdev/ui';
+```
+
+---
+
+**Simple. Modular. Type-safe.**