@donotdev/cli 0.0.3

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

@@ -0,0 +1,296 @@
+# Installation Guide
+
+**Installing DoNotDev Framework Packages from npm**
+
+---
+
+## Prerequisites
+
+- [Bun](https://bun.sh/) >= 1.3.0 (recommended) or Node.js >= 20.19.0 / >= 22.12.0 (LTS)
+- Git
+
+---
+
+## Step 1: Install Packages
+
+### Install Framework Core
+
+```bash
+# Install core bundle + UI layer
+bun add @donotdev/core @donotdev/ui
+
+# Or with npm
+npm install @donotdev/core @donotdev/ui
+```
+
+### Install Features (Optional)
+
+```bash
+# Add authentication
+bun add @donotdev/auth
+
+# Add billing (Stripe)
+bun add @donotdev/billing
+
+# Add OAuth providers
+bun add @donotdev/oauth
+
+# Add Firebase provider (if using Firebase)
+bun add @donotdev/firebase
+```
+
+### Install Build Tools
+
+```bash
+# Add Vite config factories
+bun add -D @donotdev/config
+
+# Add CLI (for scaffolding)
+bun add -D @donotdev/cli
+```
+
+### Install Free Showcase Packages
+
+```bash
+# Pure UI components (public)
+bun add @donotdev/components
+
+# Page templates
+bun add @donotdev/templates
+```
+
+---
+
+## Step 2: Configure License Key
+
+To remove the watermark, add your license key:
+
+### For Vite Projects
+
+Add to `.env` file:
+
+```env
+VITE_DONOTDEV_LICENSE_KEY=dndev_your_key_here
+```
+
+### For Next.js Projects
+
+Add to `.env.local` file:
+
+```env
+NEXT_PUBLIC_DONOTDEV_LICENSE_KEY=dndev_your_key_here
+```
+
+### Or in Code (Before Framework Initialization)
+
+```typescript
+globalThis.__DONOTDEV_LICENSE_KEY__ = 'dndev_your_key_here';
+```
+
+**Get your license key:** [donotdev.com/pricing](https://donotdev.com/pricing)
+
+---
+
+## Step 3: Verify Installation
+
+```bash
+# Check installed packages
+bun pm ls | grep @donotdev
+
+# Or with npm
+npm list | grep @donotdev
+```
+
+You should see all installed `@donotdev/*` packages listed.
+
+---
+
+## Example: Complete Setup
+
+```bash
+# 1. Create project
+mkdir my-app
+cd my-app
+
+# 2. Initialize package.json
+bun init -y
+
+# 3. Install framework
+bun add @donotdev/core @donotdev/ui @donotdev/auth @donotdev/billing
+bun add -D @donotdev/cli @donotdev/config
+
+# 4. Create .env file
+echo "VITE_DONOTDEV_LICENSE_KEY=dndev_your_key_here" > .env
+
+# 5. Start development
+bun run dev
+```
+
+---
+
+## CI/CD Configuration
+
+### GitHub Actions
+
+```yaml
+# .github/workflows/build.yml
+name: Build
+
+on: [push]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: oven-sh/setup-bun@v1
+
+      - name: Install dependencies
+        run: bun install
+
+      - name: Build
+        run: bun run build
+        env:
+          VITE_DONOTDEV_LICENSE_KEY: ${{ secrets.DONOTDEV_LICENSE_KEY }}
+```
+
+**Add `DONOTDEV_LICENSE_KEY` secret:**
+
+1. Go to your repo settings → Secrets → Actions
+2. Add new secret: `DONOTDEV_LICENSE_KEY`
+3. Paste your license key
+
+### Vercel
+
+Add environment variable in Vercel dashboard:
+
+```
+VITE_DONOTDEV_LICENSE_KEY=dndev_your_key_here
+```
+
+Or for Next.js:
+
+```
+NEXT_PUBLIC_DONOTDEV_LICENSE_KEY=dndev_your_key_here
+```
+
+### Docker
+
+```dockerfile
+# Dockerfile
+FROM oven/bun:1
+
+WORKDIR /app
+
+# Copy package files
+COPY package.json bun.lockb ./
+
+# Install dependencies
+RUN bun install
+
+# Copy source
+COPY . .
+
+# Build
+RUN bun run build
+
+CMD ["bun", "run", "start"]
+```
+
+**Build with license key:**
+
+```bash
+docker build --build-arg VITE_DONOTDEV_LICENSE_KEY=your_key -t my-app .
+```
+
+---
+
+## Troubleshooting
+
+### "Package not found"
+
+**Problem:** `@donotdev/core` not found
+
+**Solutions:**
+
+1. Verify package name is correct (check spelling)
+2. Try clearing cache: `bun pm cache rm` or `npm cache clean --force`
+3. Check internet connection
+
+### "Failed to fetch"
+
+**Problem:** Network/registry errors
+
+**Solutions:**
+
+1. Check internet connection
+2. Verify npm registry is accessible
+3. Try with verbose logging: `bun install --verbose`
+
+### Watermark Still Showing
+
+**Problem:** License key not working
+
+**Solutions:**
+
+1. Verify license key is correct (starts with `dndev_`)
+2. Check environment variable name matches your framework (Vite vs Next.js)
+3. Restart development server after adding license key
+4. For production builds, ensure environment variable is set in deployment platform
+
+---
+
+## Updating Packages
+
+### Check for Updates
+
+```bash
+# Check outdated packages
+bun outdated | grep @donotdev
+
+# Or with npm
+npm outdated | grep @donotdev
+```
+
+### Update to Latest
+
+```bash
+# Update all @donotdev packages
+bun update @donotdev/core @donotdev/ui @donotdev/auth @donotdev/billing
+
+# Or with npm
+npm update @donotdev/core @donotdev/ui @donotdev/auth @donotdev/billing
+```
+
+### Update to Specific Version
+
+```bash
+# Install specific version
+bun add @donotdev/core@0.3.0
+
+# Or with npm
+npm install @donotdev/core@0.3.0
+```
+
+---
+
+## Next Steps
+
+After installation:
+
+1. **Read the guide:** [GETTING_STARTED.md](GETTING_STARTED.md)
+2. **Scaffold a project:** `bunx @donotdev/cli create-project`
+3. **Explore examples:** Check framework documentation
+4. **Join Discord:** Get help from the community
+
+---
+
+## Support
+
+- **Discord:** [Join our community](https://discord.gg/donotdev)
+- **Email:** mooti.web.app@gmail.com
+- **Issues:** [GitHub Issues](https://github.com/SkillsAreImba/dndev/issues)
+
+---
+
+**Get your license key:** [donotdev.com/pricing](https://donotdev.com/pricing)

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

@@ -0,0 +1,310 @@
+# Layouts
+
+**Status:** Up to date. See live examples at https://donotdev.com/showcase/layouts
+
+**Pre-Built Layout Presets**
+
+---
+
+## 7 Layout Presets
+
+**Landing** (default) - Marketing sites, landing pages
+
+```typescript
+// config/app.ts
+export const appConfig: AppConfig = {
+  preset: 'landing',
+  // ...
+};
+
+// App.tsx
+<ViteAppProviders
+  config={appConfig}
+  LandingPage={HomePage}
+/>
+```
+
+- Header + footer (no sidebar)
+- Full-width content area
+- Optimized for marketing content
+
+**Admin** - Dashboards, admin panels
+
+```typescript
+// config/app.ts
+export const appConfig: AppConfig = {
+  preset: 'admin',
+  // ...
+};
+
+// App.tsx
+<ViteAppProviders
+  config={appConfig}
+  LandingPage={HomePage}
+/>
+```
+
+- Header + collapsible sidebar (240px) + footer
+- Search bar, user menu, notifications
+- Content max-width: 1480px
+- Responsive with mobile hamburger menu
+
+**Moolti** - SaaS applications, productivity tools
+
+```typescript
+// config/app.ts
+export const appConfig: AppConfig = {
+  preset: 'moolti',
+  // ...
+};
+
+// App.tsx
+<ViteAppProviders
+  config={appConfig}
+  LandingPage={HomePage}
+/>
+```
+
+- Sidebar only (256px, no header/footer on desktop)
+- Mobile header with hamburger menu
+- Full-height immersive content
+- Integrated branding and controls in sidebar
+
+**Docs** - Documentation sites, knowledge bases
+
+```typescript
+// config/app.ts
+export const appConfig: AppConfig = {
+  preset: 'docs',
+  // ...
+};
+
+// App.tsx
+<ViteAppProviders
+  config={appConfig}
+  LandingPage={HomePage}
+/>
+```
+
+- Wide sidebar (300px) for TOC
+- Header with search
+- Reading-optimized spacing
+- Content-focused layout
+
+**Blog** - Blog platforms, content sites
+
+```typescript
+// config/app.ts
+export const appConfig: AppConfig = {
+  preset: 'blog',
+  // ...
+};
+
+// App.tsx
+<ViteAppProviders
+  config={appConfig}
+  LandingPage={HomePage}
+/>
+```
+
+- Header + sidebar + footer
+- Optimized for article reading
+
+**Game** - Mobile gaming interfaces
+
+```typescript
+// config/app.ts
+export const appConfig: AppConfig = {
+  preset: 'game',
+  // ...
+};
+
+// App.tsx
+<ViteAppProviders
+  config={appConfig}
+  LandingPage={HomePage}
+/>
+```
+
+- Fixed header (64px) + footer (24px)
+- No sidebar
+- Mobile-optimized
+
+**Plain** - Minimal, content-only
+
+```typescript
+// config/app.ts
+export const appConfig: AppConfig = {
+  preset: 'plain',
+  // ...
+};
+
+// App.tsx
+<ViteAppProviders
+  config={appConfig}
+  LandingPage={HomePage}
+/>
+```
+
+- No header, sidebar, or footer
+- Full control over layout
+
+---
+
+## Layout Customization
+
+Customize specific zones without rebuilding layouts:
+
+```typescript
+// config/app.ts
+export const appConfig: AppConfig = {
+  preset: 'admin',
+  // ...
+};
+
+// App.tsx
+<ViteAppProviders
+  config={appConfig}
+  layout={{
+    header: {
+      start: () => <CustomLogo />,
+      center: () => <SearchBar />,
+      end: () => <UserMenu />,
+    },
+    sidebar: {
+      top: () => <Branding />,
+      content: () => <CustomNavigation />,
+      bottom: () => <UserProfile />,
+    },
+    footer: () => <CustomFooter />,
+  }}
+  LandingPage={HomePage}
+/>
+```
+
+**Full zone override:**
+
+```typescript
+layout={{
+  header: () => <MyCustomHeader />,  // Replace entire header
+  sidebar: () => <MyCustomSidebar />, // Replace entire sidebar
+  footer: () => <MyCustomFooter />,   // Replace entire footer
+}}
+```
+
+**Available slots:**
+
+- `header.start`, `header.center`, `header.end` - Header zones (start=start-aligned, center=absolutely centered, end=end-aligned)
+- `sidebar.top`, `sidebar.content`, `sidebar.bottom` - Sidebar zones
+- `footer` - Footer component (function that returns ReactNode)
+- `mergedbar` - Mobile navigation bar (trigger, top, content, bottom)
+
+**Slot override behavior:**
+- Omit property → Uses preset defaults merged with framework defaults
+- `() => null` → Explicitly hides the slot (no content rendered)
+- `() => ReactNode` → Custom component override
+
+**Note:** All overrides are lazy functions `() => ReactNode | null` - components load when rendered, not in provider tree.
+
+**Example:**
+```typescript
+layout={{
+  header: {
+    start: () => <CustomLogo />,  // Override
+    center: () => null,            // Hide
+    // end omitted → uses defaults
+  }
+}}
+```
+
+## CSS Variable Overrides
+
+Fine-tune layout dimensions via CSS variables in `themes.css`:
+
+```css
+/* src/themes.css */
+:root {
+  /* Layout dimension overrides */
+  --header-height: 96px;
+  --sidebar-width: 320px;
+  --main-max-width: 1480px;
+  --section-gap: 2rem;
+}
+```
+
+**Common variables:**
+
+- `--header-height` - Header height (default varies by preset)
+- `--sidebar-width` - Sidebar width (default varies by preset)
+- `--footer-height` - Footer height
+- `--main-max-width` - Content max width
+- `--section-gap`, `--component-gap` - Spacing
+
+**Note:** CSS variable overrides in `themes.css` take priority over framework defaults. See scaffolded `themes.css.example` for complete reference.
+
+## Density System
+
+Control spacing and typography scale globally:
+
+```typescript
+// config/app.ts
+export const appConfig: AppConfig = {
+  preset: 'admin',
+  // ...
+};
+
+// App.tsx
+<ViteAppProviders
+  config={appConfig}
+  layout={{
+    density: 'compact', // compact | standard | expressive
+  }}
+  LandingPage={HomePage}
+/>
+```
+
+**Three densities:**
+
+- **compact** - Dense layouts for data-heavy interfaces (admin, dashboards)
+- **standard** - DEFAULT, balanced for readability (docs, SaaS)
+- **expressive** - Spacious, dramatic for marketing (landing pages)
+
+Each density uses a musical scale for harmonious typography:
+
+- Compact: Minor Third (1.2×)
+- Standard: Major Third (1.25×)
+- Expressive: Perfect Fourth (1.333×)
+
+**Per-page density:**
+
+```typescript
+<PageContainer density="expressive">
+  <HeroSection title="Hero" />
+</PageContainer>
+```
+
+All spacing (`gap-sm/md/lg`) and typography automatically adjust.
+
+## Changing Layout Preset at Runtime
+
+Change layout preset programmatically using the store:
+
+```typescript
+import { useLayout } from '@donotdev/core';
+
+function MyComponent() {
+  const setLayoutPreset = useLayout('setLayoutPreset');
+  
+  return (
+    <Button onClick={() => setLayoutPreset('plain')}>
+      Switch to Plain Layout
+    </Button>
+  );
+}
+```
+
+**Note:** Preset changes apply globally to the entire app. The store is the single source of truth.
+
+---
+
+**7 presets. Fully customizable via slots and CSS variables.**

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

@@ -0,0 +1,123 @@
+# Pages Setup
+
+**For AI Agents:** Drop `*Page.tsx` files in `src/pages/`. Routes auto-discovered.
+
+---
+
+## 1. File Naming
+
+**Pattern:** `src/pages/**/*Page.tsx` → routes
+
+```
+src/pages/
+├── AboutPage.tsx              → /about
+├── DashboardPage.tsx          → /dashboard
+└── blog/BlogPostPage.tsx      → /blog/blog-post
+```
+
+Root `/` handled separately (see step 4).
+
+---
+
+## 2. Basic Page
+
+```tsx
+// src/pages/AboutPage.tsx
+import { PageContainer } from '@donotdev/ui';
+
+export default function AboutPage() {
+  return <PageContainer><h1>About</h1></PageContainer>;
+}
+```
+
+---
+
+## 3. PageMeta (Optional)
+
+```tsx
+import type { PageMeta } from '@donotdev/core';
+import { Info } from 'lucide-react';
+
+export const meta: PageMeta = {
+  namespace: 'about',           // Translation namespace
+  icon: <Info />,               // Menu icon (default: Link)
+  hideFromMenu: false,          // Show in navigation
+  auth: { required: false },    // Protected route
+};
+```
+
+**Options:**
+- `route: '/custom-url'` - Override auto-generated path
+- `route: { params: ['slug'] }` - Dynamic route `/blog/:slug`
+- `auth: { required: true, role: 'admin' }` - Role-based access
+- `auth: { required: true, tier: 'pro' }` - Tier-based access
+
+---
+
+## 4. Root Route
+
+```tsx
+// src/App.tsx
+import { ViteAppProviders } from '@donotdev/ui/vite';
+
+export function App() {
+  return (
+    <ViteAppProviders
+      config={appConfig}
+      // HomePage.tsx in src/pages/ is automatically used for the root route "/"
+    />
+  );
+}
+```
+
+---
+
+## 5. Dynamic Routes
+
+```tsx
+// src/pages/blog/BlogPostPage.tsx
+import { useParams } from 'react-router-dom';
+
+export const meta: PageMeta = {
+  namespace: 'blog',
+  route: { params: ['slug'] },  // → /blog/:slug
+};
+
+export default function BlogPostPage() {
+  const { slug } = useParams<{ slug: string }>();
+  return <PageContainer><h1>{slug}</h1></PageContainer>;
+}
+```
+
+---
+
+## 6. Protected Routes
+
+```tsx
+export const meta: PageMeta = {
+  auth: { required: true },
+};
+
+export default function DashboardPage() {
+  const user = useAuth('user');
+  return <PageContainer>Welcome {user?.displayName}</PageContainer>;
+}
+```
+
+---
+
+## 7. Navigation
+
+```tsx
+import { useNavigate } from '@donotdev/core';
+import { Link } from '@donotdev/ui';
+
+const navigate = useNavigate();
+navigate('/about');
+
+<Link path="/about">About</Link>
+```
+
+---
+
+**That's it. Drop files, get routes.**