@donotdev/cli 0.0.3

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

@@ -0,0 +1,296 @@
+# How to Use DoNotDev Framework
+
+**For AI Agents & Developers**
+
+This guide explains how to build apps with DoNotDev following our conventions. The framework is designed for **AI-first development** - everything works by default, minimal configuration needed.
+
+---
+
+## Core Philosophy
+
+**No CSS. Just Compose.**
+
+- **NEVER write CSS** - use component props
+- **NEVER use inline styles** - components handle styling
+- **NEVER use Tailwind/utility classes** - props-based API only
+- **NEVER nest components** - use props instead (e.g., `Card` with `title` prop, NOT `<Card><CardTitle>`)
+- Compose components with props - that's it
+
+---
+
+## Quick Start: Building Your First App
+
+### 1. Scaffold Project
+
+```bash
+dndev init my-app
+cd my-app
+bun install
+```
+
+### 2. Choose Layout Preset
+
+Edit `apps/my-app/src/config/app.ts`:
+
+```tsx
+import type { AppConfig } from '@donotdev/core';
+
+export const appConfig: AppConfig = {
+  preset: 'landing', // 'landing' | 'admin' | 'moolti' | 'docs' | 'blog' | 'game' | 'plain'
+  app: {
+    name: 'My App',
+    // ...
+  },
+};
+```
+
+Edit `apps/my-app/src/App.tsx`:
+
+```tsx
+import { ViteAppProviders } from '@donotdev/ui/vite';
+import { appConfig } from './config/app';
+import HomePage from './pages/HomePage';
+
+export function App() {
+  return (
+    <ViteAppProviders
+      config={appConfig}
+      LandingPage={HomePage}
+    />
+  );
+}
+```
+
+**7 presets:** `landing`, `admin`, `moolti`, `docs`, `blog`, `game`, `plain`
+
+### 3. Create Pages
+
+**Drop pages in `apps/<my_app>/src/pages/**` - routes are automatic.**
+
+```tsx
+// apps/my-app/src/pages/AboutPage.tsx
+import { PageContainer, Card } from '@donotdev/ui';
+import type { PageMeta } from '@donotdev/core';
+import { Rocket } from 'lucide-react';
+
+export const meta: PageMeta = {
+  namespace: 'about',
+  icon: <Rocket />, // Optional - Lucide-react (default: Link)
+  hideFromMenu: true, // Hide from navigation
+  auth: { required: true }, // Require authentication
+};
+
+export default function AboutPage() {
+  return (
+    <PageContainer>
+      <Card title="About" content="Our story..." />
+    </PageContainer>
+  );
+}
+```
+
+---
+
+## Component Composition (No CSS)
+
+**Rule: Use props, not CSS. Compose components, don't nest.**
+
+### Layout Components
+
+```tsx
+import { PageContainer, Section } from '@donotdev/ui';
+
+<PageContainer variant="standard" density="comfortable">
+  <Section title="Features" gridCols={3} tone="muted">
+    {/* Children go here */}
+  </Section>
+</PageContainer>
+```
+
+**PageContainer props:**
+- `variant`: `'full' | 'standard' | 'docs' | 'fixed'`
+- `density`: `'compact' | 'comfortable' | 'spacious'`
+- `centered`: `boolean`
+
+**Section props:**
+- `title`: `string` - Section title
+- `subtitle`: `string` - Section subtitle
+- `gridCols`: `1 | 2 | 3 | 4` - Grid columns for children
+- `gridGap`: `'none' | 'tight' | 'medium' | 'large'`
+- `tone`: `'base' | 'muted' | 'elevated' | 'contrast' | 'accent'`
+- `badge`: `string` - Badge text
+- `eyebrow`: `{ label: string, icon?: Component }` - Eyebrow label
+
+### Card Component
+
+```tsx
+import { Card } from '@donotdev/components';
+import { Rocket } from 'lucide-react';
+
+// ✅ CORRECT: Props-based API
+<Card 
+  title="Feature Name"
+  subtitle="Feature description"
+  content="Detailed content here"
+  icon={Rocket}
+  footer={<Button>Action</Button>}
+  variant="default"
+  elevated
+/>
+
+// ❌ WRONG: No nested components
+// <Card>
+//   <CardTitle>Feature Name</CardTitle>
+//   <CardHeader>...</CardHeader>
+// </Card>
+```
+
+**Card props:**
+- `title`: `string | ReactNode` - Card title
+- `subtitle`: `string | ReactNode` - Card subtitle
+- `content`: `string | ReactNode` - Main content
+- `footer`: `ReactNode` - Footer content
+- `icon`: `IconType` - Icon component (Lucide-react)
+- `variant`: `'default' | 'muted' | 'accent'`
+- `elevated`: `boolean` - Add shadow/elevation
+- `onClick`: `() => void` - Click handler
+
+### Common Components
+
+```tsx
+import { Button, HeroSection, CallToAction } from '@donotdev/components';
+import { Rocket } from 'lucide-react';
+
+// Button
+<Button variant="primary" size="md" icon={Rocket}>Click</Button>
+
+// HeroSection
+<HeroSection 
+  title="Welcome"
+  subtitle="Build fast"
+  primaryAction={<Button>Get Started</Button>}
+/>
+
+// CallToAction
+<CallToAction
+  title="Ready to start?"
+  primaryAction={<Button>Sign Up</Button>}
+  secondaryAction={<Button variant="outline">Learn More</Button>}
+/>
+```
+
+---
+
+## Key Components Reference
+
+**From `@donotdev/ui`:**
+- `PageContainer` - Page wrapper with width constraints
+- `Section` - Layout section with grid
+- `HeroSection` - Hero banner
+- `CallToAction` - CTA section
+
+**From `@donotdev/components`:**
+- `Card` - Card with title/content/footer props
+- `Button` - Button with variant/size/icon props
+- `Input`, `Textarea`, `Select` - Form inputs
+- `Dialog`, `AlertDialog` - Modals
+- `DropdownMenu`, `Command` - Menus
+- `Table`, `DataTable` - Tables
+- `Tabs`, `Accordion` - Content organization
+- `Badge`, `Avatar`, `Separator` - UI elements
+- `Stack`, `Grid` - Layout utilities
+
+**All components use props-based API - no nesting, no CSS needed.**
+
+---
+
+## Critical Rules
+
+### ✅ DO
+
+- Compose components with props
+- Use `Card` with `title`/`content` props
+- Use `Section` with `gridCols` prop for layouts
+- Use `PageContainer` to wrap pages
+- Trust component defaults
+
+### ❌ DON'T
+
+- **NEVER write CSS** - use component props
+- **NEVER use inline styles** - `style={{ ... }}` forbidden
+- **NEVER use Tailwind/utility classes** - props only
+- **NEVER nest components** - `Card` has `title` prop, NOT `<CardTitle>`
+- **NEVER use native HTML** - use framework components
+- **NEVER override component styles** - use props/variants
+
+---
+
+## Example: Complete Page
+
+```tsx
+import { PageContainer, Section, Card, Button, HeroSection } from '@donotdev/ui';
+import { Zap, Sparkles, Rocket } from 'lucide-react';
+
+export default function HomePage() {
+  return (
+    <PageContainer>
+      <HeroSection 
+        title="Welcome"
+        subtitle="Build fast with DoNotDev"
+        primaryAction={<Button>Get Started</Button>}
+      />
+      
+      <Section title="Features" gridCols={3}>
+        <Card 
+          title="Fast"
+          content="Lightning fast development"
+          icon={Zap}
+        />
+        <Card 
+          title="Simple"
+          content="Zero configuration needed"
+          icon={Sparkles}
+        />
+        <Card 
+          title="Powerful"
+          content="Enterprise-grade features"
+          icon={Rocket}
+        />
+      </Section>
+    </PageContainer>
+  );
+}
+```
+
+**No CSS. No inline styles. Just compose.**
+
+---
+
+## Translations
+
+**File naming:** `namespace_lng.json`
+- `namespace` matches `PageMeta.namespace`
+- `lng` is ISO 2-letter code (en, fr, es, etc.)
+
+**Eager:** `src/locales/home_en.json` (loaded on start)
+**Lazy:** `src/pages/locales/about_en.json` (loaded per page)
+
+---
+
+## Theming
+
+Override `src/themes.css` to customize colors. Framework provides defaults - override selectively.
+
+---
+
+## Logos & Assets
+
+**Logo:**
+- Add your `logo.svg` to `public/`
+- Framework will prompt during build if missing: "Do you want us to provide one from the framework?"
+- Or manually copy from `node_modules/@donotdev/ui/assets/logo.svg`
+- Framework automatically generates favicon, app icons, and PWA assets from your logo
+
+---
+
+**Remember:** No CSS. Just compose components with props. Trust the defaults.

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

@@ -0,0 +1,204 @@
+# Internationalization Setup
+
+**For AI Agents:** Drop `{namespace}_{lng}.json` files. Framework discovers languages automatically.
+
+---
+
+## 1. File Naming & Locations
+
+**Pattern:** `{namespace}_{lng}.json`
+
+- `namespace` - Matches `PageMeta.namespace` - CAN NOT HAVE _ in its name
+- `lng` - ISO 2-letter language code (en, fr, es, de, ar, it, ja, ko, zh, pt, ru, hi, ...)
+
+**Eager (loaded on start):**
+```
+src/locales/
+├── common_en.json
+├── common_fr.json
+├── home_en.json
+└── home_fr.json
+```
+
+**Lazy (loaded per route):**
+```
+src/pages/locales/
+├── about_en.json
+└── about_fr.json
+```
+
+---
+
+## 2. Translation Files
+
+```json
+// src/locales/home_en.json
+{
+  "title": "Welcome",
+  "subtitle": "Build apps faster",
+  "welcome": "Hello {{name}}",
+  "features": ["Fast", "Simple", "Powerful"],
+  "benefits": {
+    "0": "Lightning fast",
+    "1": "Zero config",
+    "2": "Enterprise ready"
+  },
+  "cases": {
+    "0": {
+      "useCase": "E-commerce",
+      "bestFit": "Stripe integration",
+      "reason": "Built-in billing"
+    }
+  }
+}
+```
+
+---
+
+## 3. Advanced Translation Utilities
+
+**Import from `@donotdev/core`:**
+
+```tsx
+import { 
+  useTranslation,
+  maybeTranslate,
+  translateArray,
+  translateObjectArray,
+} from '@donotdev/core';
+```
+
+### `maybeTranslate` - Smart Translation Helper
+
+Auto-detects translation keys vs raw strings:
+
+```tsx
+const { t } = useTranslation('home');
+
+// Plain string → returns as-is
+maybeTranslate(t, "Early Bird Lifetime") 
+// → "Early Bird Lifetime"
+
+// Translation key → translates
+maybeTranslate(t, "purchase:products.earlyBird.name") 
+// → "Accès Anticipé à Vie" (if FR)
+
+// Namespace prefix optional
+maybeTranslate(t, "products.earlyBird.name") 
+// → Uses current namespace
+```
+
+**Use case:** Handle mixed content (some translated, some not).
+
+### `translateArray` - Array Translations
+
+Translates indexed array keys:
+
+```tsx
+const { t } = useTranslation('home');
+
+// JSON: { "benefits": { "0": "Fast", "1": "Simple", "2": "Powerful" } }
+const benefits = translateArray(t, 'benefits', 6);
+// → ["Fast", "Simple", "Powerful"]
+// Automatically filters out missing translations
+
+// Nested keys
+const features = translateArray(t, 'features.list', 5);
+// → Gets features.list.0 through features.list.4
+```
+
+**Options:**
+```tsx
+translateArray(t, 'items', 10, {
+  minLength: 2,        // Only include items with at least 2 characters
+  excludeEmpty: true,  // Exclude empty strings
+  customFilter: (item, index) => item.length > 5
+});
+```
+
+### `translateObjectArray` - Object Array Translations
+
+Translates arrays of objects:
+
+```tsx
+const { t } = useTranslation('home');
+
+// JSON: { "cases": { "0": { "useCase": "...", "bestFit": "..." }, "1": {...} } }
+const cases = translateObjectArray(
+  t, 
+  'cases', 
+  4, 
+  ['useCase', 'bestFit', 'dndev', 'reason']
+);
+// → [
+//     { useCase: "...", bestFit: "...", dndev: "...", reason: "..." },
+//     ...
+//   ]
+```
+
+**Automatically filters out missing translations.**
+
+### `translateArrayRange` - Range Translations
+
+Translates a specific range:
+
+```tsx
+// Get items 2-5 (indices 2, 3, 4)
+const items = translateArrayRange(t, 'items', 2, 5);
+```
+
+### `translateArrayWithIndices` - With Original Indices
+
+Returns items with their original indices:
+
+```tsx
+const benefits = translateArrayWithIndices(t, 'benefits', 6);
+// → [
+//     { item: "Fast", originalIndex: 0 },
+//     { item: "Simple", originalIndex: 1 },
+//     ...
+//   ]
+```
+
+---
+
+## 4. Basic Usage
+
+```tsx
+import { useTranslation, type PageMeta } from '@donotdev/core';
+
+export const meta: PageMeta = {
+  namespace: 'home',  // Matches home_*.json
+};
+
+export default function HomePage() {
+  const { t } = useTranslation('home');
+
+  return (
+    <div>
+      <h1>{t('title')}</h1>
+      <p>{t('welcome', { name: 'Alice' })}</p>
+    </div>
+  );
+}
+```
+
+---
+
+## 5. Configuration
+
+```typescript
+// src/config/app.ts
+export const appConfig: AppConfig = {
+  i18n: {
+    defaultLanguage: 'en',
+    fallbackLanguage: 'en',
+  },
+};
+```
+
+**Note:** `LanguageSelector` is included in default layout presets - no setup needed.
+
+---
+
+**Zero config. Drop files, languages auto-discovered. Use utilities for advanced patterns.**

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

@@ -0,0 +1,79 @@
+# Import Patterns
+
+**Status:** Single Source of Truth for Import Conventions.
+
+**GOLDEN RULE:**
+**NEVER import from internal paths like `src/...` or `dist/...`. Always import from the package root.**
+
+---
+
+## 1. The "Root Import" Mandate
+
+✅ **Correct:**
+
+```typescript
+import { Button } from '@donotdev/components';
+import { PageContainer } from '@donotdev/ui';
+import { useAuth } from '@donotdev/auth';
+```
+
+❌ **WRONG (Will break builds):**
+
+```typescript
+import { Button } from '@donotdev/components/src/atomic/Button';
+import { PageContainer } from '@donotdev/ui/src/components/layout/PageContainer';
+```
+
+---
+
+## 2. Verbatim Type Imports
+
+We use strict TypeScript settings. You must use `import type` for interfaces and types.
+
+✅ **Correct:**
+
+```typescript
+import type { ButtonProps } from '@donotdev/components';
+```
+
+❌ **Wrong:**
+
+```typescript
+import { ButtonProps } from '@donotdev/components'; // Error: Value not found
+```
+
+---
+
+## 3. Import Order (Organization)
+
+1.  **External Libraries** (React, Zustand, Lucide)
+2.  **DoNotDev Framework** (`@donotdev/*`)
+3.  **Local/Relative** (`./components`, `../../hooks`)
+
+**Example:**
+
+```typescript
+import React, { useState } from 'react';
+import { User } from 'lucide-react';
+
+import { Button, Card } from '@donotdev/components';
+import { useThemeStore } from '@donotdev/core';
+
+import { MyLocalComponent } from './MyLocalComponent';
+```
+
+---
+
+## 4. Package Guide
+
+| Package                    | Usage                        | Examples                                                    |
+| :------------------------- | :--------------------------- | :---------------------------------------------------------- |
+| **`@donotdev/core`**       | Logic, Hooks, Config, Stores | `useTranslation`, `useThemeStore`, `isClient`, `AppConfig`  |
+| **`@donotdev/components`** | Atomic UI Elements           | `Button`, `Card`, `Input`, `Text`, `Section`, `HeroSection` |
+| **`@donotdev/ui`**         | Layouts & Containers         | `PageContainer`, `Link`, `ViteAppProviders`                 |
+| **`@donotdev/auth`**       | Authentication               | `useAuth`, `SignInPage`                                     |
+| **`@donotdev/billing`**    | Stripe/Payments              | `useStripeBilling`, `PricingTable`                          |
+
+---
+
+**Adhere to these patterns to ensure your code is upgrade-safe and follows framework standards.**

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

@@ -0,0 +1,50 @@
+# DoNotDev Framework Guides
+
+**For AI Agents:** See [AGENT_START_HERE.md](./AGENT_START_HERE.md)
+
+---
+
+## Quick Setup
+
+1. [INSTALLATION.md](./INSTALLATION.md) - Install framework packages
+2. [GETTING_STARTED.md](./GETTING_STARTED.md) - Scaffold first app
+3. [FRAMEWORK_OVERVIEW.md](./FRAMEWORK_OVERVIEW.md) - Package structure
+
+---
+
+## Core Setup
+
+- [PAGES_SETUP.md](./PAGES_SETUP.md) - File-based routing
+- [CONFIG_SETUP.md](./CONFIG_SETUP.md) - App + Vite configuration
+- [I18N_SETUP.md](./I18N_SETUP.md) - Translations
+- [THEMING_SETUP.md](./THEMING_SETUP.md) - Themes + CSS variables
+
+---
+
+## Feature Setup
+
+- [AUTH_SETUP.md](./AUTH_SETUP.md) - Authentication
+- [BILLING_SETUP.md](./BILLING_SETUP.md) - Stripe subscriptions
+- [APP_CHECK_SETUP.md](./APP_CHECK_SETUP.md) - Abuse protection (reCAPTCHA)
+- [FUNCTIONS.md](./FUNCTIONS.md) - Firebase Cloud Functions
+
+---
+
+## Usage & Reference
+
+- [HOW_TO_USE.md](./HOW_TO_USE.md) - Component composition philosophy
+- [COMPONENTS.md](./COMPONENTS.md) - Component catalog
+- [FEATURES.md](./FEATURES.md) - Feature packages usage
+- [LAYOUTS.md](./LAYOUTS.md) - Layout presets
+- [STYLING.md](./STYLING.md) - Styling system
+- [IMPORT_PATTERNS.md](./IMPORT_PATTERNS.md) - Import conventions
+
+---
+
+## Tools
+
+- [CLI.md](./CLI.md) - `dndev` commands
+
+---
+
+**Convention over configuration. AI-first design.**