@donotdev/cli 0.0.4 → 0.0.5

package/templates/app-demo/src/pages/components/DemoLayout.tsx.example

@@ -49,7 +49,7 @@ export function DemoLayout({
   const [isMobileMenuOpen, setIsMobileMenuOpen] = useState(false);
   const location = useLocation();
   const navigate = useNavigate();
-  const isDesktop = useMediaQuery('(min-width: 1024px)');
+  const isLaptop = useMediaQuery('(min-width: 1024px)');
 
   const handleBack = () => {
     if (location.pathname === '/full') {
@@ -140,11 +140,11 @@ export function DemoLayout({
   return (
     <Grid
       className="dndev-h-screen dndev-w-full dndev-overflow-hidden"
-      templateColumns={isDesktop ? '280px 1fr' : '1fr'}
-      areas={isDesktop ? 'sidebar main' : 'main'}
+      templateColumns={isLaptop ? '280px 1fr' : '1fr'}
+      areas={isLaptop ? 'sidebar main' : 'main'}
       gap="none"
     >
-      {isDesktop && (
+      {isLaptop && (
         <GridArea
           name="sidebar"
           style={{
@@ -224,7 +224,7 @@ export function DemoLayout({
             {/* Right side: Theme Toggle + Mobile Menu */}
             <Stack direction="row" gap="medium" justify="end" align="center">
               <ThemeToggle />
-              {!isDesktop && (
+              {!isLaptop && (
                 <Sheet
                   open={isMobileMenuOpen}
                   onOpenChange={setIsMobileMenuOpen}

package/templates/app-next/src/app/ClientLayout.tsx.example

@@ -25,7 +25,7 @@ export function ClientLayout({ children, serverCookies }: ClientLayoutProps) {
         config={appConfig}
         serverCookies={serverCookies}
         layout={{
-          breadcrumbs: 'smart', // 'smart' | 'always' | 'never' | false
+          breadcrumbs: 'smart', // 'smart' | 'always' | 'never'
           header: {
             // end: () => <YourHeaderActions />,
           },

package/templates/app-vite/src/App.tsx.example

@@ -29,7 +29,7 @@ export function App() {
     <ViteAppProviders
       config={appConfig}
       layout={{
-        breadcrumbs: 'smart', // 'smart' | 'always' | 'never' | false
+        breadcrumbs: 'smart', // 'smart' | 'always' | 'never'
         header: {
           // end: () => <YourHeaderActions />,
         },

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

@@ -10,15 +10,44 @@
 
 **Never guess. Always verify.**
 
+---
+
+## ✅ Success Path: Follow These Steps
+
+**Step 1: Install dependencies**
+- Run `bun install` in project root
+- Wait for completion - framework components will load correctly
+- TypeScript imports will resolve properly
+
+**Step 2: Create pages correctly**
+- Name files ending in `Page.tsx` (e.g., `HomePage.tsx`)
+- Place them in `src/pages/` folder
+- Framework will auto-discover and route them
+- Navigation will show them automatically
+
+**Step 3: Configure app**
+- Edit `src/config/app.ts` with your preset and app name
+- Framework will use your configuration
+- Footer and legal links will be included automatically
+
+**Step 4: Customize via config files**
+- Override defaults in `src/config/app.ts`
+- Override themes in `src/themes.css`
+- Framework preserves your changes on updates
+
 
 ** dndev ** is our custom CLI, dndev --help for info.
 
 
 **🧠 PHILOSOPHY & MINDSET (READ THIS):**
+
+**CRITICAL: ALL YOU NEED TO DO IS FOLLOW OUR NAMING CONVENTIONS + FILE STRUCTURE CONVENTIONS AND FOCUS ON THE INSIDE OF YOUR PAGES, WITH OUR COMPONENTS. EVERYTHING ELSE IS HANDLED. JUST TRUST THE FRAMEWORK AND CODE AS FEW AS POSSIBLE.**
+
 *   **Speed > Polish:** Your goal is to reach UAT (User Acceptance Testing) fast. The app should look "good enough" (80%) using standard components.
 *   **Composition > Customization:** Do not waste time writing CSS to make it "perfect" pixel-wise. Drop components, use props, move on.
 *   **Standardize:** If it looks like a standard DoNotDev app, you succeeded. If you are writing custom CSS to fight the framework, you failed.
 *   **Polishing:** Deep styling is for *after* the core functionality is approved and the User asks you to polish, with their preferred method.
+*   **Trust the Framework:** Navigation, routing, layouts, auth, themes, i18n - all handled automatically. Focus on page content only.
 
 ---
 
@@ -49,19 +78,135 @@ import type { PageMeta } from '@donotdev/core';
 
 ## New App Setup
 
+**CRITICAL: Follow these steps IN ORDER. Complete each step before moving to the next.**
+
+**✅ SCAFFOLDING PHILOSOPHY:**
+The `dndev init` or `dndev create-app` commands create files with working defaults. Your job is to UPDATE these scaffolded files with your specific needs - update values, add content, customize configuration. The scaffolded files are correctly structured and framework-ready. Preserve the structure and imports, update the values and content.
+
+### Step 1: Create Project (if starting from scratch)
+```bash
+dndev init my-project-name
+# OR if adding to existing project:
+cd existing-project
+dndev create-app my-app-name
+```
+
+### Step 2: Install Dependencies (REQUIRED - FIRST STEP)
+```bash
+cd my-project-name  # or cd apps/my-app-name
+bun install
+```
+**✅ CRITICAL:** Run `bun install` as the first step. This installs all framework dependencies and enables framework components to work correctly.
+
+### Step 3: Configure App (REQUIRED)
+**CRITICAL:** The scaffolding process creates these files with working defaults. UPDATE them with your specific needs - do not replace them entirely.
+
+**File: `src/config/app.ts`** (scaffolded - update with your values):
+```typescript
+import type { AppConfig } from '@donotdev/core';
+
+export const appConfig: AppConfig = {
+  preset: 'landing', // Update: Choose your preset (landing | admin | moolti | docs | blog | game | plain)
+  app: {
+    name: 'My App', // Update: Your app name
+    url: 'https://myapp.com', // Update: Your app URL
+  },
+};
+```
+
+**File: `src/config/legal.ts`** (scaffolded - update with your legal pages):
+```typescript
+export const legalConfig = {
+  // Update: Add your legal pages (privacy, terms, etc.)
+};
+```
+
+**File: `vite.config.ts`** (scaffolded - already configured correctly):
+```typescript
+import { defineViteConfig } from '@donotdev/core/vite';
+import { appConfig } from './src/config/app';
+
+export default defineViteConfig({
+  appConfig,  // Already configured - framework imports your appConfig
+});
+```
+
+**✅ UPDATE STRATEGY:**
+- Scaffolded files are already correctly structured
+- Update values (app name, preset, URLs) to match your needs
+- Keep the file structure and imports as-is
+- Framework expects these exact file paths and exports
+
+**✅ CORRECT FILE PATHS:**
+- `src/config/app.ts` - Place in `src/config/` folder
+- `src/config/legal.ts` - Place in `src/config/` folder  
+- `vite.config.ts` - Place at project root (same level as `package.json`)
+- `src/pages/*Page.tsx` - Place in `src/pages/` folder
+
+### Step 4: Add Logo (Optional but recommended)
+Drop `logo.svg` in `public/` folder. Framework auto-generates favicon, icons, PWA assets.
+
+### Step 5: Create or Update Pages
+**Scaffolding creates `src/pages/HomePage.tsx` with a working example. UPDATE it with your content:**
+
+```tsx
+import { PageContainer } from '@donotdev/ui';
+
+export default function HomePage() {
+  return <PageContainer><h1>Hello</h1></PageContainer>;
+}
+```
+
+**✅ UPDATE STRATEGY:**
+- Scaffolded `HomePage.tsx` is already correctly structured
+- Update the content inside `PageContainer` with your components
+- Keep the imports and export structure as-is
+- Add more pages by creating new `*Page.tsx` files in `src/pages/`
+
+### Step 6: Verify Setup (BEFORE running dev)
+**Check these files exist:**
+- ✅ `src/config/app.ts` exists
+- ✅ `vite.config.ts` exists and imports `appConfig` from `src/config/app.ts`
+- ✅ `src/pages/HomePage.tsx` exists (or at least one `*Page.tsx` file)
+- ✅ `package.json` exists with `@donotdev/*` dependencies
+- ✅ `bun install` completed successfully
 
-**If not scaffolded:** `dndev create-app`
+### Step 7: Run Development Server
+```bash
+bun run dev
+```
+
+**Expected output:**
+- Server starts on `http://localhost:5173` (or configured port)
+- No "Cannot find module" errors
+- Browser shows your app (may show watermark if no license key)
 
-**Configure:**
-1. `config/app.ts` - Choose layout preset + footer links + auth behavior (if needed)
-2. `config/legal.ts` - Set legal pages data
-3. `public/logo.svg` - Drop logo (framework generates rest - optional)
+**If you see errors:**
+1. **"Cannot find module '@donotdev/...'"** → Run `bun install` again
+2. **"Cannot find module './src/config/app'"** → Check `vite.config.ts` path is correct
+3. **"No routes found"** → Check you have `*Page.tsx` files in `src/pages/`
+4. **TypeScript errors** → Run `bun run type-check` to see details
+
+**✅ ALWAYS DO:**
+- Run `bun install` first - required for dependencies
+- Create pages in `src/pages/` folder - framework discovers them automatically
+- Name files ending in `Page.tsx` - framework routes them automatically
+- Trust framework defaults - routing, navigation, layouts are automatic
+- Use preset components - LanguageSelector, ThemeToggle, AuthMenu are included automatically
 
 ---
 
 ## Generic Conventions
 
-**Routing:** Drop `*Page.tsx` files in `pages/**` → auto-discovered. Use `PageMeta` for routes, auth, icons.
+**File Routing Rule: Only files ending in `Page.tsx` inside `src/pages` become routes.**
+
+**✅ ROUTING RULES:**
+- Name files with `Page.tsx` suffix (e.g., `HomePage.tsx`, `AboutPage.tsx`)
+- Place files inside `src/pages/` directory (or subdirectories)
+- Framework auto-discovers routes from `src/pages/*Page.tsx` files
+- Framework automatically generates navigation from discovered routes
+
+**Routing:** Drop `*Page.tsx` files in `src/pages/**` → auto-discovered. Use `PageMeta` for routes, auth, icons.
 
 **i18n:** Drop `<namespace>_<lng>.json` in `/locales` (eager) or `/pages/locales` (lazy). Framework auto-discovers languages.
 
@@ -69,6 +214,21 @@ import type { PageMeta } from '@donotdev/core';
 
 ---
 
+## Success Checklist
+
+**✅ Follow these to ensure success:**
+
+1. **✅ Always name pages with `Page.tsx` suffix** - Example: `HomePage.tsx`, `AboutPage.tsx`
+2. **✅ Always run `bun install` first** - Required before any other commands
+3. **✅ Trust framework routing** - Framework auto-discovers routes from `src/pages/*Page.tsx`
+4. **✅ Use preset components** - LanguageSelector, ThemeToggle, AuthMenu are included automatically
+5. **✅ Configure via config files** - Edit `src/config/app.ts`, never modify `node_modules`
+6. **✅ Create pages in `src/pages/` folder** - Framework discovers them automatically
+7. **✅ Configure `src/config/app.ts`** - Set your preset and app name
+8. **✅ Run `bun install` before `bun run dev`** - Dependencies must be installed first
+
+---
+
 ## Landing Page Example
 
 ```tsx
@@ -91,7 +251,7 @@ export default function HomePage() {
       </Section>
       
       <Section title="Layout Examples">
-        <Grid cols={2} gap="medium">
+        <Grid cols={[1, 1, 2, 2]} gap="medium">
           <Card title="Left Column" />
           <Card title="Right Column" />
         </Grid>
@@ -115,6 +275,68 @@ export default function HomePage() {
 
 ---
 
+---
+
+## Required File Structure
+
+**CRITICAL:** Your project MUST have this exact structure:
+
+```
+my-project/
+├── package.json              # At root - contains dependencies
+├── vite.config.ts            # At root - imports appConfig
+├── src/
+│   ├── config/
+│   │   ├── app.ts            # REQUIRED - app configuration
+│   │   └── legal.ts           # REQUIRED - legal pages config
+│   ├── pages/
+│   │   └── HomePage.tsx       # Your pages (must end in Page.tsx)
+│   ├── App.tsx                # App entry point
+│   └── main.tsx               # Vite entry point
+└── public/
+    └── logo.svg               # Optional - framework generates assets
+```
+
+**✅ CORRECT FILE PATHS EXAMPLES:**
+- ✅ `src/config/app.ts` (correct location)
+- ✅ `src/pages/HomePage.tsx` (correct location)
+- ✅ `src/pages/AboutPage.tsx` (correct - in pages subfolder)
+- ✅ `src/pages/blog/BlogPostPage.tsx` (correct - nested pages work)
+
+---
+
+## Troubleshooting
+
+### "Cannot find module '@donotdev/...'"
+**Solution:** Run `bun install` in the project root. Dependencies must be installed before running the app.
+
+### "No routes found"
+**Solution:** 
+1. Check files are in `src/pages/` folder
+2. Check files end in `Page.tsx` (not `.tsx` or `.ts`)
+3. Check files are exported as default: `export default function HomePage()`
+
+### "Cannot find module './src/config/app'"
+**Solution:**
+1. Check `vite.config.ts` is at project root (same level as `package.json`)
+2. Check `src/config/app.ts` exists
+3. Check import path in `vite.config.ts`: `import { appConfig } from './src/config/app';`
+
+### App shows blank page
+**Solution:**
+1. Check browser console for errors
+2. Verify at least one `*Page.tsx` file exists in `src/pages/`
+3. Verify `vite.config.ts` imports `appConfig` correctly
+4. Check `src/App.tsx` uses `ViteAppProviders` with `config={appConfig}`
+
+### TypeScript errors
+**Solution:**
+1. Run `bun run type-check` to see all errors
+2. Ensure all `@donotdev/*` packages are installed
+3. Check imports use root package names: `@donotdev/components`, not deep paths
+
+---
+
 **Component references:** [COMPONENTS_ATOMIC.md](./COMPONENTS_ATOMIC.md) | [COMPONENTS_UI.md](./COMPONENTS_UI.md) | [COMPONENTS_CRUD.md](./COMPONENTS_CRUD.md)
 
 **Full guides:** [INDEX.md](./INDEX.md) - 50-100 LOC per topic (SETUP_*.md, advanced/*.md)

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

@@ -0,0 +1,360 @@
+# Advanced Components (@donotdev/adv-comps)
+
+High-level, opinionated, and marketing-focused UI components for DoNotDev framework.
+
+## Setup
+
+**IMPORTANT:** You must import the styles in your `globals.css` file:
+
+```css
+@import '@donotdev/adv-comps/styles';
+```
+
+Without this import, components will not have their required CSS styles.
+
+## Components
+
+### Crawl
+
+Cinematic 3D text crawl component with lazy loading.
+
+```tsx
+import { Crawl } from '@donotdev/adv-comps';
+
+<Crawl
+  intro?: ReactNode | string
+  title?: ReactNode | string
+  content: ReactNode | string | string[]
+  duration?: number // @default 26
+  contentHeight?: string // @default "150vh"
+  tiltAngle?: number
+  className?: string
+  style?: CSSProperties
+  aria-label?: string
+/>
+```
+
+### Marquee
+
+Production-grade marquee with accessibility, reduced motion support, and smart behavior detection.
+
+```tsx
+import { Marquee } from '@donotdev/adv-comps';
+
+<Marquee<T>
+  items: T[]
+  renderItem: (item: T, index: number) => ReactNode
+  className?: string
+  itemClassName?: string
+  gap?: 'none' | 'tight' | 'medium' | 'large' // @default 'medium'
+  speed?: number // px per second
+  direction?: 'left' | 'right' | 'up' | 'down' | 'auto' // @default 'auto'
+  pauseOnHover?: boolean
+  ariaLabel?: string
+  reducedMotion?: 'respect' | 'ignore'
+  behavior?: 'bounce' | 'infinite' | 'auto'
+  pauseOnFocusWithin?: boolean
+  easing?: 'linear' | 'ease-in-out' | 'ease-out'
+/>
+```
+
+### Roadmap
+
+Timeline component with horizontal (desktop) / vertical (mobile) layout. Features animated progress line, glowing nodes, and lift-on-hover cards.
+
+```tsx
+import { Roadmap } from '@donotdev/adv-comps';
+import type { RoadmapStep } from '@donotdev/adv-comps';
+
+<Roadmap
+  steps: RoadmapStep[]
+  className?: string
+  variant?: CardVariant // @default 'default'
+/>
+
+// RoadmapStep interface:
+interface RoadmapStep {
+  phase: string // e.g., "Week 1", "Days 1-2"
+  icon: LucideIcon
+  title: string
+  subtitle: string
+  description?: string
+  content?: CardContent // Optional content shown in popover on click
+}
+```
+
+### StackedCards
+
+Simple scroll-reveal stacked cards. Active card shows full content, stacked cards show only bottom edge with number.
+
+```tsx
+import { StackedCards } from '@donotdev/adv-comps';
+import type { StackedCardData } from '@donotdev/adv-comps';
+
+<StackedCards
+  items: StackedCardData[]
+  variant?: SurfaceVariantProps['variant']
+  ariaLabel?: string
+  threshold?: number // Intersection threshold (0.0 - 1.0) @default 0.3
+  className?: string
+  style?: CSSProperties
+/>
+
+// StackedCardData extends ComponentData with:
+interface StackedCardData extends ComponentData {
+  number?: string | number // Custom number/label (e.g. "01", "Week 1"). Defaults to index.
+}
+```
+
+### Reveal
+
+Reveal component for staggered animations. Features viewport-based visibility detection, directional animations, and customizable stagger delays.
+
+```tsx
+import { Reveal } from '@donotdev/adv-comps';
+
+<Reveal
+  items: string[] | ReactNode[]
+  direction?: 'left' | 'right' | 'top' | 'bottom' | 'fade-in' | 'alternate-h' | 'alternate-v'
+  stagger?: number // milliseconds between items
+  threshold?: number
+  distance?: number // animation distance in pixels
+  duration?: number // animation duration in milliseconds
+  once?: boolean // if true, only animate once
+  viewport?: boolean // if true, only animate items in viewport
+  overrides?: Array<{
+    index: number
+    direction: 'left' | 'right' | 'top' | 'bottom' | 'fade-in'
+  }>
+  className?: string
+  children?: ReactNode
+/>
+```
+
+### InspectorGadget
+
+Floating code inspector component. Displays a floating eye icon button that opens a dialog showing the page's source code.
+
+```tsx
+import { InspectorGadget } from '@donotdev/adv-comps';
+
+<InspectorGadget
+  data?: string // Source code string
+  sourcePath?: string // Path to source file (import with ?raw) - overrides data if provided
+  sourceCode?: string // Source code loaded from file
+  language?: string // Code language for syntax highlighting @default 'tsx'
+  title?: string // Dialog title @default 'Page Source'
+  className?: string
+/>
+```
+
+### Breathing Components
+
+Breathing exercise components for meditation and wellness apps.
+
+```tsx
+import { LungsAnimation, BreathingExerciseLayout } from '@donotdev/adv-comps';
+import type { BreathingExerciseDnDevLayoutProps } from '@donotdev/adv-comps';
+
+<BreathingExerciseLayout
+  status?: ReactNode
+  animation: ReactNode
+  instructions: ReactNode
+  debug?: boolean
+  onSkip?: () => void
+  statusValue?: string
+  onRestart?: () => void
+  isPaused?: boolean
+  isComplete?: boolean
+/>
+
+<LungsAnimation ... />
+```
+
+### Carousel
+
+Premium carousel component with lazy loading built-in. Features true infinite circular loop, hardware-accelerated animations, swipe/touch gestures, and autoplay with pause-on-hover.
+
+```tsx
+import { Carousel } from '@donotdev/adv-comps';
+import type { CarouselProps, CarouselRef } from '@donotdev/adv-comps';
+
+<Carousel<T>
+  items: T[]
+  renderItem: (item: T, index: number, isActive: boolean) => ReactNode
+  className?: string
+  slideClassName?: string
+  showArrows?: boolean
+  showDots?: boolean
+  showProgress?: boolean
+  autoplay?: boolean
+  autoplayInterval?: number // milliseconds
+  transitionDuration?: number // milliseconds
+  loop?: boolean
+  // ... and more props
+/>
+```
+
+### ComparisonGrid
+
+Comparison grid component for displaying feature comparisons. Provides lazy-loaded content with skeleton loading states.
+
+```tsx
+import { ComparisonGrid } from '@donotdev/adv-comps';
+import type { ComparisonItem } from '@donotdev/adv-comps';
+
+<ComparisonGrid
+  title?: string
+  items: ComparisonItem[]
+  gridCols?: 1 | 2 | 3 | 4 // @default 2
+  className?: string
+  ariaLabel?: string
+/>
+
+// ComparisonItem interface:
+interface ComparisonItem {
+  useCase: string
+  bestFit: string
+  dndev: string
+  reason: string
+}
+```
+
+### CongratulationsCard
+
+Card component for displaying congratulatory messages. Features customizable icon and text with centered layout.
+
+```tsx
+import { CongratulationsCard } from '@donotdev/adv-comps';
+
+<CongratulationsCard
+  text: string
+  icon?: ReactNode // @default '🎉'
+  className?: string
+/>
+```
+
+### GuideModal
+
+Modal component for displaying guides and tutorials. Provides step-by-step guide display with navigation, progress tracking, and completion handling.
+
+```tsx
+import { GuideModal } from '@donotdev/adv-comps';
+import type { GuideModalProps, GuideTemplate } from '@donotdev/adv-comps';
+
+<GuideModal
+  open: boolean
+  onOpenChange: (open: boolean) => void
+  guide: GuideTemplate
+  icon?: LucideIcon
+/>
+
+// GuideTemplate interface:
+interface GuideTemplate {
+  title: string
+  subtitle: string
+  quickStart?: {
+    title: string
+    code: string
+    description: string
+  }
+  steps?: GuideStep[]
+  features?: string[]
+  templates?: Array<{
+    name: string
+    description: string
+  }>
+  actions?: Array<{
+    label: string
+    href: string
+    variant?: 'default' | 'outline'
+    icon?: LucideIcon
+  }>
+}
+
+// GuideStep interface:
+interface GuideStep {
+  icon: LucideIcon
+  title: string
+  description: string
+  code?: string
+  details?: string
+}
+```
+
+### SplitReveal
+
+Split reveal component for displaying content in two columns. Features left column content and right column stat cards or custom content with reveal animations.
+
+```tsx
+import { SplitReveal } from '@donotdev/adv-comps';
+import type { StatCardData } from '@donotdev/adv-comps';
+
+<SplitReveal
+  left: ReactNode
+  right: ReactNode | StatCardData[]
+  leftDirection?: 'left' | 'right' | 'top' | 'bottom' | 'fade-in' // @default 'left'
+  rightDirection?: 'left' | 'right' | 'top' | 'bottom' | 'fade-in' // @default 'right'
+  threshold?: number // @default 0.3
+  className?: string
+/>
+
+// StatCardData interface:
+interface StatCardData {
+  title: string
+  description: string
+}
+```
+
+### StartChallengeForm
+
+Generic form layout component for input + CTA button patterns.
+
+```tsx
+import { StartChallengeForm } from '@donotdev/adv-comps';
+
+<StartChallengeForm
+  input={{
+    value: string
+    onChange: (value: string) => void
+    placeholder?: string
+    label?: string
+    maxLength?: number
+    className?: string
+  }}
+  button={{
+    label: string
+    onClick: () => void
+    icon?: ComponentType<{ className?: string }>
+    variant?: ButtonVariant
+    className?: string
+  }}
+  size?: 'sm' | 'md' | 'lg'
+  className?: string
+/>
+```
+
+### Waterfall
+
+Waterfall component with lazy loading built-in. Features clean cascade layout with diagonal staircase effect, perfect for step-by-step processes or feature showcases.
+
+```tsx
+import { Waterfall } from '@donotdev/adv-comps';
+import type { WaterfallProps } from '@donotdev/adv-comps';
+
+<Waterfall
+  items: ComponentData[]
+  className?: string
+  connectorClassName?: string
+  density?: 'compact' | 'comfortable'
+  ariaLabel?: string
+  direction?: 'horizontal' | 'descending'
+/>
+```
+
+## Notes
+
+- All components are lazy-loaded by default for optimal performance
+- Components use framework theme variables for consistent styling
+- Most components support reduced motion preferences
+- All components are SSR-safe and work with both Vite and Next.js