@donotdev/cli 0.0.3

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

@@ -0,0 +1,273 @@
+# Styling Your App
+
+**Guide for:** DoNotDev framework consumers
+
+---
+
+## Quick Start: Zero CSS Required
+
+DoNotDev components work out of the box. Just pass props:
+
+```tsx
+import { Card, Button, Section } from '@donotdev/components';
+import { PageContainer } from '@donotdev/ui';
+
+<PageContainer>
+  <Section gridCols={3}>
+    <Card title="Feature 1" content="Description" />
+    <Card title="Feature 2" content="Description" />
+    <Card title="Feature 3" content="Description" />
+  </Section>
+</PageContainer>;
+```
+
+**Result:** Responsive, accessible, themed. No CSS written.
+
+---
+
+## Page Structure (90% of use cases)
+
+```tsx
+<PageContainer>
+  <HeroSection title="Title" subtitle="Subtitle" />
+
+  <Section gridCols={3} title="Features">
+    <Card title="Feature 1" />
+    <Card title="Feature 2" />
+    <Card title="Feature 3" />
+  </Section>
+
+  <CallToAction title="Get Started" primaryAction={<Button>Action</Button>} />
+</PageContainer>
+```
+
+**PageContainer handles:**
+
+- Width constraints (`variant`: `full`, `standard`, `narrow`, `text`, `form`, `table`, `dashboard`)
+- Spacing and typography via density system (`density`: `compact`, `standard`, `expressive`)
+
+**Section handles:**
+
+- Full-width backgrounds (`tone`: `base`, `muted`, `elevated`, `contrast`, `accent`)
+- Grid layout (`gridCols`: `1`, `2`, `3`, `4`)
+- Grid gap (`gridGap`: `none`, `tight`, `medium`, `large`)
+
+---
+
+## Density System
+
+Control spacing and typography globally:
+
+```tsx
+<PageContainer density="expressive">
+  {/* All components automatically use expressive scale */}
+  <HeroSection title="Large Hero" />
+  <Section gridCols={3}>
+    <Card title="Card" />
+  </Section>
+</PageContainer>
+```
+
+**Three densities:**
+
+- **compact** - Dense layouts (admin, dashboards) - Minor Third (1.2×)
+- **standard** - DEFAULT, balanced (docs, SaaS) - Major Third (1.25×)
+- **expressive** - Spacious (marketing) - Perfect Fourth (1.333×)
+
+All spacing (`--gap-sm/md/lg`) and typography (`--font-size-*`) adjust automatically based on musical scale ratios.
+
+---
+
+## Breakthrough Components
+
+Some components break out of PageContainer width constraints to achieve full-width backgrounds:
+
+```tsx
+<PageContainer variant="standard">
+  {' '}
+  {/* 1480px max */}
+  <Section tone="muted" gridCols={3}>
+    {/* Section has full-width gray background */}
+    {/* But content is constrained to 1480px */}
+    <Card title="Card 1" />
+    <Card title="Card 2" />
+    <Card title="Card 3" />
+  </Section>
+  <CallToAction
+    title="Get Started"
+    subtitle="Ready to build?"
+    primaryAction={<Button>Start Now</Button>}
+  />
+  {/* CTA has full-width background, constrained content */}
+</PageContainer>
+```
+
+**Breakthrough components:**
+
+- `Section` - Full-width backgrounds with grid layout
+- `HeroSection` - Full-width hero sections
+- `CallToAction` - Full-width conversion sections
+
+**Why?** Marketing pages need full-width colored backgrounds while keeping text readable (constrained width).
+
+---
+
+## Overriding Styles
+
+### Via className
+
+```tsx
+// Default styling
+<Card title="Feature" />
+
+// Tighter gap
+<Card title="Feature" className="dndev-gap-sm" />
+
+// Custom layout
+<div className="dndev-flex dndev-gap-md">
+  <Card title="Left" />
+  <Card title="Right" />
+</div>
+```
+
+**Available utilities:**
+
+- Gap: `dndev-gap-none`, `dndev-gap-sm`, `dndev-gap-md`, `dndev-gap-lg`
+- Layout: `dndev-flex`, `dndev-flex-col`, `dndev-grid`, `dndev-center`
+- Padding: `dndev-p-{none|tight|medium|large}`
+
+### Via Data Attributes
+
+**Text Alignment:**
+```tsx
+<HeroSection data-text-align="center" title="Centered Hero" />
+<CallToAction data-text-align="center" title="Centered CTA" />
+<div data-text-align="end">Right-aligned text</div>
+```
+
+**Universal data attributes:**
+- `data-text-align="start|center|end"` - Text alignment (RTL-aware)
+- `data-gap="none|tight|medium|large"` - Gap spacing
+- `data-radius="none|md|full"` - Border radius
+- `data-cols="1|2|3|4"` - Grid columns (when using grid utilities)
+
+**Why data attributes?**
+- DRY: Single CSS rule handles all components
+- No prop conflicts: `align` prop in Stack/Grid is for flex alignment, not text alignment
+- No nesting issues: Each element controls its own styling
+- Works with any element, not just framework components
+
+### Via inline styles
+
+```tsx
+<Button style={{ minWidth: '200px' }}>
+  Wide Button
+</Button>
+
+<div style={{
+  display: 'grid',
+  gridTemplateColumns: '2fr 1fr',
+  gap: 'var(--gap-md)'
+}}>
+  <Card title="Main" />
+  <Card title="Sidebar" />
+</div>
+```
+
+---
+
+## CSS Variables
+
+All design tokens available as CSS variables:
+
+```css
+/* Your custom styles */
+.my-component {
+  padding: var(--gap-md);
+  background: var(--color-surface);
+  border-radius: var(--radius-md);
+  box-shadow: var(--shadow-md);
+}
+```
+
+**Common variables:**
+
+- **Gap:** `--gap-none`, `--gap-sm`, `--gap-md`, `--gap-lg`
+- **Radius:** `--radius-none`, `--radius-md`, `--radius-full`
+- **Shadows:** `--shadow-sm`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`
+- **Colors:** `--color-primary`, `--color-surface`, `--color-text`
+
+---
+
+## Theming
+
+Override CSS variables in your `themes.css`:
+
+```css
+[data-theme='custom'] {
+  --color-primary: #ff6b6b;
+  --gap-md: 1.5rem;
+  --radius-md: 1rem;
+}
+```
+
+See [THEMING.md](./THEMING.md) for complete guide.
+
+---
+
+## Advanced: Using Primitives
+
+For complex UI, use primitives directly:
+
+```tsx
+import {
+  TooltipPrimitive,
+  TooltipTriggerPrimitive,
+  TooltipContentPrimitive,
+} from '@donotdev/components';
+
+<TooltipPrimitive>
+  <TooltipTriggerPrimitive asChild>
+    <Button>Hover</Button>
+  </TooltipTriggerPrimitive>
+  <TooltipContentPrimitive>
+    <div className="dndev-flex-col dndev-gap-sm">
+      <h4>Title</h4>
+      <p>Description</p>
+      <Button>Action</Button>
+    </div>
+  </TooltipContentPrimitive>
+</TooltipPrimitive>;
+```
+
+**When to use:**
+
+- Simple content → Props-based components
+- Complex/interactive content → Primitives
+
+---
+
+## Styling Approaches (All Valid)
+
+The framework is flexible. Use what works:
+
+✅ Utility classes
+✅ Inline styles
+✅ CSS modules
+✅ Tailwind (if you prefer)
+✅ Styled components
+✅ Emotion
+
+**Build your way.**
+
+---
+
+## Related
+
+- [COMPONENTS.md](./COMPONENTS.md) - Component catalog
+- [LAYOUTS.md](./LAYOUTS.md) - Layout patterns
+- [THEMING.md](./THEMING.md) - Theme customization
+
+---
+
+**Last Updated:** 2025-12-03

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

@@ -0,0 +1,119 @@
+# Theming Setup
+
+**For AI Agents:** Override `src/themes.css`. CSS variables control everything.
+
+---
+
+## 1. Theme File
+
+**Scaffolded:** `src/themes.css` (already imported in your app)
+
+```css
+/* src/themes.css */
+.light {
+  --theme-icon: 'Sun';
+  --theme-label: 'Light';
+  --primary: #3b82f6;
+  --background: #ffffff;
+  --foreground: #0a0a0a;
+  /* ... more variables with JSDoc in scaffolded file */
+}
+
+.dark {
+  --theme-icon: 'Moon';
+  --theme-label: 'Dark';
+  --primary: #60a5fa;
+  --background: #0a0a0a;
+  --foreground: #fafafa;
+}
+```
+
+---
+
+## 2. Add Custom Theme
+
+```css
+.ocean {
+  --theme-icon: 'Waves';
+  --theme-label: 'Ocean';
+  --primary: #0ea5e9;
+  --background: #001a33;
+  --foreground: #e0f2fe;
+}
+```
+
+Framework auto-discovers themes. ThemeToggle auto-populated.
+
+---
+
+## 3. Key Variables
+
+**Base colors:**
+- `--background` / `--foreground`
+- `--primary` / `--primary-foreground`
+- `--secondary` / `--secondary-foreground`
+
+**Containers:**
+- `--card` / `--card-foreground`
+- `--popover` / `--popover-foreground`
+
+**Status:**
+- `--destructive`, `--success`, `--warning`
+
+**Radius:**
+- `--radius-surface` - Cards (rounded)
+- `--radius-floating` - Dropdowns (square)
+- `--radius-interactive` - Buttons (square)
+
+---
+
+## 4. Using Theme Colors
+
+**In CSS:**
+```css
+.my-component {
+  background: var(--background);
+  color: var(--foreground);
+}
+```
+
+**In components:**
+All framework components auto-use theme colors.
+
+---
+
+## 5. Theme Switching
+
+**Automatic (built-in):**
+```tsx
+import { ThemeToggle } from '@donotdev/ui';
+
+// Auto-included in layout presets
+// Hides if 1 theme, icon if 2, dropdown if 3+
+<ThemeToggle />
+```
+
+**Manual:**
+```tsx
+import { useThemeStore } from '@donotdev/core';
+
+const { theme, setTheme } = useThemeStore();
+setTheme('dark');
+```
+
+---
+
+## 6. Configuration
+
+```typescript
+// src/config/app.ts
+export const appConfig: AppConfig = {
+  theme: {
+    defaultTheme: 'light',
+  },
+};
+```
+
+---
+
+**Zero config. Infinite themes. Read JSDoc in scaffolded file for all variables.**

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

@@ -0,0 +1,181 @@
+# Version Control Guide
+
+**How to upgrade DoNotDev framework packages in your project**
+
+---
+
+## Quick Start
+
+```bash
+# Check for available updates
+dndev bump --check
+
+# Apply safe updates (minor/patch versions)
+dndev bump
+
+# Preview changes without applying
+dndev bump --dry-run
+```
+
+---
+
+## How It Works
+
+### Automatic Updates
+
+**Patch versions (0.0.x):**
+- Handled automatically by `bun install`
+- No action needed - `^` ranges allow automatic patch updates
+- Example: `^0.0.2` → `0.0.3`, `0.0.4`, etc.
+
+**Minor versions (0.x.y):**
+- Handled automatically by `dndev bump`
+- **RISK FREE:** All changes are backward compatible via deprecation
+- No breaking changes in 0.x.y range
+- Example: `^0.0.2` → `^0.1.0` (auto-updated, safe)
+
+### Manual Validation Required
+
+**Major versions (0.*.* → 1.x.y):**
+- `dndev bump` detects major version changes
+- Shows migration guide with breaking changes
+- **You must validate manually** before updating
+- **Only place where breaking changes occur**
+- Example: `^0.1.0` → `^1.0.0` (requires validation)
+
+---
+
+## Upgrade Process
+
+### Step 1: Check for Updates
+
+```bash
+dndev bump --check
+```
+
+This shows:
+- Available updates for `@donotdev/*` packages (from npm)
+- Available updates for external peer dependencies (from matrix)
+- Major version changes (with migration guides)
+
+### Step 2: Review Migration Guides
+
+If major version changes are detected:
+- Read the migration guide shown in the output
+- Check for breaking changes that affect your code
+- Review the migration guide file (path shown in output)
+
+### Step 3: Apply Updates
+
+```bash
+# Safe updates (minor/patch) - auto-applied
+dndev bump
+
+# Or preview first
+dndev bump --dry-run
+```
+
+**What gets updated:**
+- `@donotdev/*` packages: Updated to latest compatible version
+- External peer dependencies: Updated to matrix versions
+- All `package.json` files in your project
+
+---
+
+## Understanding Version Ranges
+
+### `^` Range (Caret)
+
+**What it means:**
+- Allows updates to latest minor/patch version
+- Same major version required
+- Example: `^0.0.2` allows `0.0.2` through `0.0.9`, but not `0.1.0`
+
+**Why we use it:**
+- Automatic patch updates via `bun install`
+- Safe minor updates via `dndev bump`
+- Prevents accidental major version updates
+
+### Version Format
+
+```json
+{
+  "dependencies": {
+    "@donotdev/core": "^0.0.2",
+    "react": "^19.2.3"
+  }
+}
+```
+
+- `^0.0.2` = allows `0.0.2` to `0.0.x` (patch updates)
+- `^0.1.0` = allows `0.1.0` to `0.x.x` (minor updates)
+- `^1.0.0` = allows `1.0.0` to `1.x.x` (minor updates, not `2.0.0`)
+
+---
+
+## Migration Guides
+
+When upgrading major versions, migration guides are provided:
+
+**Location:** Shown in `dndev bump` output
+
+**Contains:**
+- List of breaking changes
+- Step-by-step migration instructions
+- Code examples for updated APIs
+
+**Example:**
+```
+⚠️  Major version update detected: @donotdev/core 0.1.0 → 1.0.0
+
+Migration guide: docs/migration/v0.1-to-v1.0.md
+
+Breaking changes:
+- Removed useAuth() - use useAuthentication() instead
+- Theme API changed - see migration guide
+
+Review the migration guide before updating.
+```
+
+---
+
+## Troubleshooting
+
+### "No updates available"
+
+- All packages are up to date
+- Or you're already on latest version
+
+### "Major version change detected"
+
+- Review migration guide
+- Check breaking changes
+- Update code if needed
+- Run `dndev bump` again to apply
+
+### "Package not found on npm"
+
+- Package may not be published yet
+- Check package name spelling
+- Verify you're using correct registry
+
+---
+
+## Best Practices
+
+1. **Regular updates:** Run `dndev bump --check` monthly
+2. **Test after updates:** Run your test suite after applying updates
+3. **Review major changes:** Always read migration guides for major versions
+4. **Use `--dry-run`:** Preview changes before applying
+5. **Commit changes:** Commit updated `package.json` files after successful updates
+
+---
+
+## Related
+
+- **[Dependency System](../../docs/development/DEPENDENCY_SYSTEM.md)** - How dependency management works
+- **[Architecture Hub](../../docs/architecture/INDEX.md)** - Framework structure
+
+---
+
+**Keep your dependencies up to date. Stay secure. Stay compatible.**

package/templates/root-consumer/tsconfig.functions.json.example

@@ -0,0 +1,15 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2022"],
+    "types": ["node"],
+    "noEmit": false,
+    "outDir": "./functions/lib",
+    "rootDir": "./functions/src"
+  },
+  "include": ["functions/src/**/*", "entities/**/*"],
+  "exclude": ["node_modules", "**/node_modules", "**/dist", "**/.next", "**/lib"]
+}
+

package/templates/root-consumer/tsconfig.json.example

@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "preserve",
+    "moduleResolution": "bundler",
+    "lib": ["ESNext", "DOM", "DOM.Iterable"],
+    "strict": true,
+    "skipLibCheck": true,
+    "esModuleInterop": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "jsx": "react-jsx",
+    "forceConsistentCasingInFileNames": true
+  },
+  "include": ["apps/*/tsconfig.json"],
+  "exclude": ["node_modules", "**/node_modules", "dist", "**/dist", "**/.next", "**/lib"]
+}
+

package/templates/root-consumer/turbo.json.example

@@ -0,0 +1,46 @@
+{
+  "$schema": "https://turbo.build/schema.json",
+  "globalDependencies": [
+    "**/.env.*local"
+  ],
+  "tasks": {
+    "build": {
+      "dependsOn": [
+        "^build"
+      ],
+      "outputs": [
+        "*/dist/**",
+        "!**/node_modules/**"
+      ]
+    },
+    "type-check": {
+      "dependsOn": [
+        "^type-check"
+      ],
+      "cache": true
+    },
+    "preview": {
+      "dependsOn": ["build"],
+      "cache": false,
+      "persistent": true
+    },
+    "test": {
+      "dependsOn": [
+        "^build"
+      ],
+      "outputs": [
+        "coverage/**"
+      ]
+    },
+    "lint": {
+      "outputs": []
+    },
+    "dev": {
+      "cache": false,
+      "persistent": true
+    },
+    "clean": {
+      "cache": false
+    }
+  }
+}