vibe-now 1.0.7 → 1.1.0

package/.claude/settings.local.json

@@ -0,0 +1,27 @@
+{
+  "permissions": {
+    "allow": [
+      "WebSearch",
+      "WebFetch(domain:tanstack.com)",
+      "WebFetch(domain:docs.convex.dev)",
+      "WebFetch(domain:www.anthropic.com)",
+      "WebFetch(domain:github.com)",
+      "WebFetch(domain:www.humanlayer.dev)",
+      "WebFetch(domain:ui.shadcn.com)",
+      "WebFetch(domain:dometrain.com)",
+      "Bash(npm link:*)",
+      "Bash(node:*)",
+      "Bash(chmod +x:*)",
+      "Bash(bash:*)",
+      "Bash(kill:*)",
+      "Bash(rm:*)",
+      "Bash(yes:*)",
+      "Bash(printf test-1\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n:*)",
+      "Bash(printf test-1\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n\\\\n:*)",
+      "Bash(git commit:*)",
+      "Bash(git pull:*)",
+      "Bash(git:*)",
+      "Bash(npm publish:*)"
+    ]
+  }
+}

package/PLAN.md

@@ -1,54 +1,155 @@
-# Custom CLI Wizard Plan (Plop.js + Next.js Stack)
-
-This project has been successfully implemented and released as **Vibe Now**.
-
-## 1. Project Overview
-A custom CLI (`vibe-now`) that:
-- Prompts for project name with validation.
-- Dynamically generates interactive prompts group by category.
-- Orchestrates project creation and dependency installation using a configuration-driven approach.
-- Generates dynamic documentation (AGENTS.md and README.md).
-
-## 2. Core Dependencies
-- **plop**: Generator framework.
-- **inquirer**: Interactive prompts.
-- **execa**: Process execution.
-- **ora**: Premium progress spinners.
-- **handlebars**: Template engine for file generation.
-
-## 3. Configuration-Driven Architecture (DRY & Scalable)
-The CLI uses a `PACKAGE_GROUPS` array in `lib/packages.js`. Adding a new package or category is fully decoupled from the core logic.
-
-## 4. Implementation Details & Commands
-
-### Base Next.js Setup
-- **Command**: `npx create-next-app@latest`
-
-### Features Implemented
-- **AI SDK**: Vercel AI SDK & OpenRouter.
-- **Linters**: ESLint/Prettier and Biome selection.
-- **UI & Helpers**: shadcn/ui, nuqs, hook-form, dayjs, lodash.
-- **Database**: Supabase & Drizzle ORM.
-- **Payments**: Stripe & Polar.sh.
-- **Authentication**: Better Auth.
-
-## 5. Implementation Status
-
-- [x] **Phase 1: Environment Setup** - Completed with ESM support and binary linking.
-- [x] **Phase 2: Configuration Hub** - Scalable group-based configuration implemented.
-- [x] **Phase 3: CLI Entry Point** - `index.js` and `plopfile.js` logic finalized.
-- [x] **Phase 4: Premium UI** - **Ora** spinners integrated for all major steps.
-- [x] **Phase 5: Smart Validation** - URL-safe project names and empty directory checks.
-- [x] **Phase 6: Dynamic Documentation** - Handlebars-based `README.md` and `AGENTS.md` generation.
-
-## 6. Project Structure
-```text
+# Vibe Now — v2 Plan
+
+## Overview
+
+Four new features: framework choice (Next.js vs TanStack Start), AI editor context (CLAUDE.md vs AGENTS.md), database provider selection (Supabase vs Convex), and auto-generated `.env.example` files.
+
+## Implementation Status
+
+- [x] **Feature 1: Framework Selection** — Next.js vs TanStack Start
+- [x] **Feature 2: Claude Code Repo** — CLAUDE.md vs AGENTS.md
+- [x] **Feature 3: Database Provider** — Supabase+Drizzle vs Convex (Cloud/Self-hosted)
+- [x] **Feature 4: .env.example Generation** — Auto-generated from selected packages
+
+---
+
+## Feature 1: Framework Selection (Next.js vs TanStack Start) — DONE
+
+**Prompt**: List choice, asked after project name.
+
+**Files changed:**
+- `plopfile.js` — New `framework` list prompt, conditional scaffold command (`create-next-app` vs `@tanstack/cli create`), `when` callbacks on confirm prompts to filter by framework, `devInstallNextjs` merging for ESLint, `isNextjs`/`isTanStack` template flags
+- `lib/packages.js` — Added `frameworks` field to `next-themes` (nextjs-only), `nuqs` (nextjs-only); added new `tanstack-theme-kit` package (tanstack-only); moved `eslint-config-next` into `devInstallNextjs` field
+- `templates/AGENTS.md.hbs` — Conditional architecture overview, directory structure (App Router vs TanStack routes), coding rules, state/data patterns, SEO guidance
+- `templates/CLAUDE.md.hbs` — Same conditional sections
+- `templates/README.md.hbs` — Conditional core framework listing
+
+### Package compatibility matrix
+
+| Package | Next.js | TanStack Start | Notes |
+|---|---|---|---|
+| zustand | Yes | Yes | Framework-agnostic |
+| zod | Yes | Yes | Framework-agnostic |
+| @tanstack/react-query | Yes | Yes | First-party TanStack |
+| shadcn/ui | Yes | Yes | Official support both |
+| next-themes | Yes | **No** | Use `tanstack-theme-kit` instead |
+| better-auth | Yes | Yes | Framework-agnostic |
+| resend | Yes | Yes | Server-side only |
+| stripe / polar | Yes | Yes | Server-side SDKs |
+| ai (Vercel AI SDK) | Yes | Yes | Core works; Next.js streaming helpers don't apply |
+| nuqs | Yes | **No** | TanStack Router has built-in `useSearch` |
+| react-hook-form | Yes | Yes | Framework-agnostic |
+| eslint-config-next | Yes | **No** | Next.js-specific; omitted for TanStack |
+| biome | Yes | Yes | Framework-agnostic |
+
+### TanStack CLI reference
+```bash
+npx @tanstack/cli create my-app -y --tailwind   # Non-interactive with Tailwind
+npx @tanstack/cli create --list-add-ons          # List available add-ons
+npx @tanstack/cli create my-app --add-ons shadcn # With add-ons
+```
+
+---
+
+## Feature 2: Claude Code Repo (AGENTS.md → CLAUDE.md) — DONE
+
+**Prompt**: Confirm after framework selection, defaults to yes.
+
+**Files changed:**
+- `plopfile.js` — New `isClaudeCode` confirm prompt, conditional rendering of CLAUDE.md vs AGENTS.md
+- `templates/CLAUDE.md.hbs` — New concise template (~50 lines) following Anthropic conventions: tech stack, commands, directory structure, code conventions, per-library guidance. Omits verbose "AI Coding Rules" section that AGENTS.md has.
+
+### CLAUDE.md conventions
+- Under 200 lines, shorter is better
+- Structure: WHAT (tech/stack) → WHY (purpose) → HOW (commands/workflow)
+- Put detailed docs in separate files (progressive disclosure)
+
+---
+
+## Feature 3: Database Provider (Supabase vs Convex) — DONE
+
+**Prompt**: List choice replacing the old individual Supabase/Drizzle confirms.
+
+**Files changed:**
+- `lib/packages.js` — Refactored `Database & ORM` from confirm-based (`items`) to list-based (`type: 'list'`) with `providerConfig` for Supabase+Drizzle, Convex Cloud, Convex Self-hosted. Added `envVars` to all three.
+- `plopfile.js` — Added `isSupabase`/`isConvex` booleans to templateData
+- `templates/AGENTS.md.hbs` — Conditional `db/` vs `convex/` directory structure, conditional security warnings
+- `templates/CLAUDE.md.hbs` — Same conditional updates
+
+### Key technical notes
+- Convex Cloud and Self-hosted use the same `convex` npm package
+- Self-hosted requires Docker + `CONVEX_SELF_HOSTED_URL` and `CONVEX_SELF_HOSTED_ADMIN_KEY` env vars
+- Convex replaces Drizzle entirely (own schema system in `convex/schema.ts`)
+- Better Auth has an official Convex adapter (`@convex-dev/better-auth`)
+
+---
+
+## Feature 4: .env.example Generation — DONE
+
+**No prompt** — auto-generated when any selected package has env vars.
+
+**Files changed:**
+- `lib/packages.js` — Added `envVars` arrays to: Supabase (4 vars), Convex Cloud (1), Convex Self-hosted (2), Better Auth (2), Resend (1), Stripe (3), Polar (2), AI SDK (1), OpenRouter (1)
+- `templates/env.example.hbs` — New template rendering vars grouped by package with comments
+- `plopfile.js` — Conditional `.env.example` generation, success message includes env note
+
+---
+
+## Other fixes applied
+- Fixed old "quick-vibe" footer in `templates/README.md.hbs` → "vibe-now"
+- Renamed generator from `next-app` to `vibe-app`
+
+---
+
+## Project Structure (current)
+```
 vibe-cli/
 ├── lib/
-│   └── packages.js     # Centralized configuration
-├── templates/          # HBS templates (README, AGENTS)
-├── index.js            # CLI Entry point 
-├── plopfile.js         # Plop logic & Action orchestrator
+│   └── packages.js          # Package configuration with frameworks, envVars
+├── templates/
+│   ├── README.md.hbs         # Framework-aware README template
+│   ├── AGENTS.md.hbs         # Full AI agent guidance (Cursor, Copilot, etc.)
+│   ├── CLAUDE.md.hbs         # Concise Claude Code memory file
+│   └── env.example.hbs       # .env.example grouped by package
+├── index.js                   # CLI entry point (Plop bootstrap)
+├── plopfile.js                # Prompts, actions, scaffold orchestration
 ├── package.json
+├── PLAN.md
 └── README.md
 ```
+
+---
+
+## Testing TODO
+
+- [ ] Run `npx @tanstack/cli create test-app -y --tailwind` to verify non-interactive mode works
+- [ ] Run `npx convex dev` first-run to check if interactive input is needed
+- [ ] Run full wizard with Next.js + Supabase + Claude Code selection
+- [ ] Run full wizard with TanStack Start + Convex Cloud + AGENTS.md selection
+- [ ] Verify `.env.example` generates correctly with multiple packages
+- [ ] Verify framework-filtered prompts (next-themes hidden for TanStack, nuqs hidden for TanStack, tanstack-theme-kit hidden for Next.js)
+- [ ] Decide: should TanStack Start projects use `--add-ons` flags instead of manual npm install?
+
+---
+
+## Future Enhancements (Post v2)
+
+### High-value
+- **Testing**: Vitest + React Testing Library, Playwright/Cypress for E2E
+- **Analytics**: PostHog, Vercel Analytics, or Plausible
+- **File/Image uploads**: UploadThing or Cloudinary
+- **Caching/Rate limiting**: Upstash Redis
+
+### Nice-to-haves
+- **Monitoring/Error tracking**: Sentry
+- **Background jobs**: Inngest or Trigger.dev
+- **Type-safe API layer**: tRPC (natural fit with TanStack Start)
+- **Icons**: `lucide-react` (already referenced in AGENTS.md guidance but not installed)
+
+### Infra/DX
+- **Docker**: Generate Dockerfile + docker-compose.yml
+- **CI/CD**: GitHub Actions workflow template (lint, test, build)
+- **Deployment target**: Vercel, Netlify, Railway, Fly.io config files
+
+### Framework-aware env vars
+- Use `VITE_` prefix instead of `NEXT_PUBLIC_` for TanStack Start client-exposed vars (Supabase URL, Stripe publishable key)

package/README.md

@@ -1,35 +1,38 @@
 # Vibe Now 🌌
 
-A premium, interactive CLI wizard for scaffolding modern Next.js applications with a perfectly curated stack. Stop running manual `npm install` commands and start building within seconds.
+A premium, interactive CLI wizard for scaffolding modern full-stack React applications with a perfectly curated stack. Choose between **Next.js** or **TanStack Start**, pick your database, payments, and tooling — and start building within seconds.
 
 <img width="3680" height="4144" alt="Terminal" src="https://github.com/user-attachments/assets/4a6e97c4-778b-432f-8fe0-46f1193aa543" />
 
 ## ✨ Features
 
+- **Framework Choice**: Scaffold with **Next.js** (App Router) or **TanStack Start** (file-based routing, type-safe).
 - **Interactive Wizard**: A beautiful CLI experience powered by Plop.js and Inquirer.
 - **World-Class Feedback**: Engaged progress tracking with **Ora** spinners for a premium feel.
-- **Smart Scaffolding**: Automatically orchestrates `create-next-app` and library-specific initializations (like `shadcn init` and `biome init`).
-- **Dynamic Documentation**: Automatically generates a project-specific `README.md` and a comprehensive `AGENTS.md` to guide AI assistants (Cursor, Claude) on your stack and standards.
+- **Smart Scaffolding**: Automatically orchestrates `create-next-app` or `@tanstack/cli create` and library-specific initializations (like `shadcn init` and `biome init`).
+- **AI Project Support**: Generates **CLAUDE.md** (for Claude Code) or **AGENTS.md** (for Cursor/other AI assistants) tailored to your chosen stack.
+- **Auto `.env.example`**: Generates a `.env.example` with all required environment variables grouped by package.
 - **Template System**: Powered by Handlebars templates in the `templates/` directory for highly customized project initialization.
 - **Safety First**: Project name validation and directory check to prevent accidental overwrites.
 
 ## 🛠️ The Curated Stack
 
-### Base
-- **Framework**: Next.js (App Router, TypeScript, Tailwind CSS v4)
+### Framework (choose one)
+- **Next.js** (App Router, TypeScript, Tailwind CSS v4)
+- **TanStack Start** (File-based routing, TypeScript, Tailwind CSS v4)
 
 ### Optional Libraries
 - **State**: Zustand
 - **Validation**: Zod
 - **Data Fetching**: TanStack React Query
-- **UI & Components**: shadcn/ui (Initializes & adds all components automatically)
-- **Database & ORM**: Supabase JS client, Drizzle ORM (Postgres + Drizzle Kit)
+- **UI & Components**: shadcn/ui, next-themes (Next.js) / tanstack-theme-kit (TanStack)
+- **Database (choose one)**: Supabase + Drizzle ORM, Convex (Cloud), or Convex (Self-hosted)
 - **Authentication**: Better Auth
 - **Email**: Resend
-- **Payments**: Mutually exclusive selection between **Stripe** and **Polar.sh**
+- **Payments (choose one)**: Stripe or Polar.sh
 - **AI SDK**: Vercel AI SDK & OpenRouter Provider support
-- **Linting & Formatting**: Choose between **ESLint + Prettier** or **Biome** (High speed)
-- **UI Helpers**: nuqs, React Hook Form, Day.js, Lodash
+- **Linting & Formatting (choose one)**: ESLint + Prettier or Biome
+- **UI Helpers**: nuqs (Next.js only), React Hook Form, Day.js, Lodash
 
 ---
 
@@ -81,7 +84,7 @@ The CLI uses a group-based configuration for easy maintenance. To add a new libr
 ```
 
 ### 4. Adding New Templates
-The wizard currently generates `README.md` and `AGENTS.md` automatically. To add a new template:
+The wizard generates `README.md`, `CLAUDE.md` or `AGENTS.md`, and `.env.example` automatically. To add a new template:
 1. Create a Handlebars file in the `templates/` directory (e.g., `templates/CONFIG.md.hbs`).
 2. Open `plopfile.js`.
 3. Locate the `// 3. Generate README and AGENTS files` section.

package/lib/packages.js

@@ -58,8 +58,17 @@ export const PACKAGE_GROUPS = [
         name: 'next-themes (Dark Mode)',
         install: ['next-themes'],
         default: true,
+        frameworks: ['nextjs'],
         guidance: 'Wrap the root layout with `ThemeProvider`. Use the `useTheme` hook to switch between dark, light, and system themes. Ensure `attribute="class"` is set for Tailwind support.',
       },
+      {
+        id: 'tanstackThemeKit',
+        name: 'tanstack-theme-kit (Dark Mode)',
+        install: ['tanstack-theme-kit'],
+        default: true,
+        frameworks: ['tanstack'],
+        guidance: 'A next-themes fork adapted for TanStack Start. Wrap the root layout with `ThemeProvider`. Use `useTheme` hook for dark/light/system themes. Supports SSR without flicker.',
+      },
     ],
   },
   {
@@ -71,28 +80,55 @@ export const PACKAGE_GROUPS = [
         install: ['better-auth'],
         default: false,
         guidance: 'Follow the Next.js App Router patterns. Keep the auth logic secure in Server Actions and use the provided middleware for route protection.',
+        envVars: [
+          { key: 'BETTER_AUTH_SECRET', comment: 'Secret key for Better Auth sessions' },
+          { key: 'BETTER_AUTH_URL', comment: 'Base URL of your app (e.g., http://localhost:3000)' },
+        ],
       },
     ],
   },
   {
-    category: 'Database & ORM',
-    items: [
-      {
-        id: 'supabase',
-        name: 'Supabase JS client',
-        install: ['@supabase/supabase-js'],
-        default: true,
-        guidance: 'Use the official Supabase SSR package for Next.js. Keep database queries inside Server Components or Server Actions to avoid exposing the Service Role key.',
-      },
-      {
-        id: 'drizzle',
-        name: 'Drizzle ORM',
-        install: ['drizzle-orm', 'pg'],
+    category: 'Database (Select One)',
+    type: 'list',
+    id: 'database',
+    choices: [
+      { name: 'None', value: 'none' },
+      { name: 'Supabase (Postgres + Drizzle ORM)', value: 'supabase' },
+      { name: 'Convex (Cloud)', value: 'convex_cloud' },
+      { name: 'Convex (Self-hosted)', value: 'convex_self' },
+    ],
+    default: 'supabase',
+    providerConfig: {
+      supabase: {
+        name: 'Supabase + Drizzle',
+        install: ['@supabase/supabase-js', 'drizzle-orm', 'pg'],
         devInstall: ['drizzle-kit'],
-        default: true,
-        guidance: 'Define schemas in `db/schema.ts`. Use `drizzle-kit` for migrations. Prefer the `db.query.xyz.findMany()` syntax for better type-safety and relations handling.',
+        guidance: 'Use Supabase SSR package for Next.js. Keep DB queries in Server Components/Actions. Define schemas in `db/schema.ts`. Use `drizzle-kit` for migrations. Prefer `db.query.xyz.findMany()` for type-safe relations.',
+        envVars: [
+          { key: 'NEXT_PUBLIC_SUPABASE_URL', comment: 'Supabase project URL' },
+          { key: 'NEXT_PUBLIC_SUPABASE_ANON_KEY', comment: 'Supabase anon/public key' },
+          { key: 'SUPABASE_SERVICE_ROLE_KEY', comment: 'Supabase service role key (server-only, never expose to client)' },
+          { key: 'DATABASE_URL', comment: 'Postgres connection string for Drizzle' },
+        ],
       },
-    ],
+      convex_cloud: {
+        name: 'Convex (Cloud)',
+        install: ['convex'],
+        guidance: 'Define schema in `convex/schema.ts`. Write queries and mutations as Convex functions in `convex/`. Run `npx convex dev` to sync with cloud. Convex provides real-time reactive queries out of the box.',
+        envVars: [
+          { key: 'CONVEX_URL', comment: 'Convex deployment URL (auto-set by npx convex dev)' },
+        ],
+      },
+      convex_self: {
+        name: 'Convex (Self-hosted)',
+        install: ['convex'],
+        guidance: 'Self-hosted Convex. Requires Docker (`docker compose up`). Set `CONVEX_SELF_HOSTED_URL` and `CONVEX_SELF_HOSTED_ADMIN_KEY` in `.env.local`. Define schema in `convex/schema.ts`. Run `npx convex dev` to sync.',
+        envVars: [
+          { key: 'CONVEX_SELF_HOSTED_URL', comment: 'Self-hosted Convex backend URL (e.g., http://127.0.0.1:3210)' },
+          { key: 'CONVEX_SELF_HOSTED_ADMIN_KEY', comment: 'Admin key from generate_admin_key.sh' },
+        ],
+      },
+    },
   },
   {
     category: 'Email',
@@ -103,6 +139,9 @@ export const PACKAGE_GROUPS = [
         install: ['resend'],
         default: false,
         guidance: 'Use React Email templates for rich emails. Centralize email logic in a `lib/email.ts` utility.',
+        envVars: [
+          { key: 'RESEND_API_KEY', comment: 'Resend API key' },
+        ],
       },
     ],
   },
@@ -121,11 +160,20 @@ export const PACKAGE_GROUPS = [
         name: 'Stripe',
         install: ['stripe', '@stripe/stripe-js', '@stripe/react-stripe-js'],
         guidance: 'Use Stripe webhooks to handle subscription lifecycle. Centralize price IDs in constants.',
+        envVars: [
+          { key: 'STRIPE_SECRET_KEY', comment: 'Stripe secret key (server-only)' },
+          { key: 'NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY', comment: 'Stripe publishable key' },
+          { key: 'STRIPE_WEBHOOK_SECRET', comment: 'Stripe webhook signing secret' },
+        ],
       },
       polar: {
         name: 'Polar.sh',
         install: ['@polar-sh/sdk', '@polar-sh/nextjs'],
         guidance: 'Integrate using Polar webhooks. Use the Next.js SDK for seamless integration with App Router.',
+        envVars: [
+          { key: 'POLAR_ACCESS_TOKEN', comment: 'Polar.sh access token' },
+          { key: 'POLAR_WEBHOOK_SECRET', comment: 'Polar.sh webhook signing secret' },
+        ],
       },
     },
   },
@@ -138,6 +186,9 @@ export const PACKAGE_GROUPS = [
         install: ['ai'],
         default: false,
         guidance: 'Use `streamText` for real-time chat interfaces. Keep LLM configurations in `lib/ai/` and use the UI hooks like `useChat`.',
+        envVars: [
+          { key: 'OPENAI_API_KEY', comment: 'OpenAI API key (or your preferred AI provider key)' },
+        ],
       },
       {
         id: 'openRouter',
@@ -145,6 +196,9 @@ export const PACKAGE_GROUPS = [
         install: ['@openrouter/ai-sdk-provider'],
         default: false,
         guidance: 'Use OpenRouter as a gateway for multiple models. Configure keys in `.env.local` and use the AI SDK provider pattern.',
+        envVars: [
+          { key: 'OPENROUTER_API_KEY', comment: 'OpenRouter API key' },
+        ],
       },
     ],
   },
@@ -163,12 +217,12 @@ export const PACKAGE_GROUPS = [
         name: 'ESLint + Prettier',
         devInstall: [
           'eslint',
-          'eslint-config-next',
           'prettier',
           'eslint-config-prettier',
           'eslint-plugin-prettier'
         ],
-        guidance: 'Standard Next.js linting combined with Prettier. Ensure `eslint-config-prettier` is the last item in the extends array.',
+        devInstallNextjs: ['eslint-config-next'],
+        guidance: 'Standard linting combined with Prettier. Ensure `eslint-config-prettier` is the last item in the extends array.',
       },
       biome: {
         name: 'Biome',
@@ -188,6 +242,7 @@ export const PACKAGE_GROUPS = [
         name: 'nuqs',
         install: ['nuqs'],
         default: false,
+        frameworks: ['nextjs'],
         guidance: 'Manage URL search parameters as state. Use the `parseAs...` helpers for strict type-casting.',
       },
       {

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "vibe-now",
-  "version": "1.0.7",
+  "version": "1.1.0",
   "main": "index.js",
   "type": "module",
   "bin": {
-    "vibe-now": "./index.js"
+    "vibe-now": "index.js"
   },
   "scripts": {
     "test": "echo \"Error: no test specified\" && exit 1"
@@ -16,7 +16,7 @@
   "keywords": [],
   "author": "Ed Moss <ed@mossified.com>",
   "license": "ISC",
-  "description": "Quickly scaffold a Next.js app with a curated stack",
+  "description": "Quickly scaffold a full-stack React app (Next.js or TanStack Start) with a curated stack",
   "dependencies": {
     "execa": "^8.0.1",
     "fs-extra": "^11.3.3",
@@ -25,4 +25,4 @@
     "ora": "^9.0.0",
     "plop": "^4.0.4"
   }
-}
+}

package/plopfile.js

@@ -8,8 +8,8 @@ import { PACKAGE_GROUPS, ALL_ITEMS } from './lib/packages.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
 export default function (plop) {
-    plop.setGenerator('next-app', {
-        description: 'Scaffold a custom Next.js app',
+    plop.setGenerator('vibe-app', {
+        description: 'Scaffold a custom full-stack React app',
         prompts: [
             {
                 type: 'input',
@@ -27,6 +27,22 @@ export default function (plop) {
                     return true;
                 }
             },
+            {
+                type: 'list',
+                name: 'framework',
+                message: 'Choose your framework:',
+                choices: [
+                    { name: 'Next.js (App Router, stable)', value: 'nextjs' },
+                    { name: 'TanStack Start (Full-stack, type-safe)', value: 'tanstack' },
+                ],
+                default: 'nextjs',
+            },
+            {
+                type: 'confirm',
+                name: 'isClaudeCode',
+                message: 'Is this a Claude Code project? (generates CLAUDE.md instead of AGENTS.md)',
+                default: true,
+            },
             ...PACKAGE_GROUPS.flatMap((group) => {
                 if (group.type === 'list') {
                     return [{
@@ -37,45 +53,64 @@ export default function (plop) {
                         default: group.default,
                     }];
                 }
-                return group.items.map(item => ({
-                    type: 'confirm',
-                    name: item.id,
-                    message: `${group.category}: Include ${item.name}?`,
-                    default: item.default,
-                }));
+                return group.items.map(item => {
+                    const prompt = {
+                        type: 'confirm',
+                        name: item.id,
+                        message: `${group.category}: Include ${item.name}?`,
+                        default: item.default,
+                    };
+                    if (item.frameworks) {
+                        prompt.when = (answers) => item.frameworks.includes(answers.framework);
+                    }
+                    return prompt;
+                });
             }),
         ],
         actions: (data) => {
             const actions = [];
             const projectPath = path.join(process.cwd(), data.projectName);
 
-            // 1. Create Base Next.js App
+            // 1. Create Base App (Next.js or TanStack Start)
             actions.push({
                 type: 'customSync',
                 async action(answers) {
+                    const isTanStack = answers.framework === 'tanstack';
+                    const label = isTanStack ? 'TanStack Start' : 'Next.js';
                     const spinner = ora({
-                        text: `Creating base Next.js app in ${answers.projectName}...`,
+                        text: `Creating base ${label} app in ${answers.projectName}...`,
                         color: 'cyan',
                     }).start();
 
                     try {
-                        await execa('npx', [
-                            'create-next-app@latest',
-                            answers.projectName,
-                            '--ts',
-                            '--tailwind',
-                            '--app',
-                            '--eslint',
-                            '--import-alias',
-                            '@/*',
-                            '--yes',
-                        ], {
-                            env: { ...process.env, npm_config_legacy_peer_deps: 'true' }
-                        });
-                        spinner.succeed('Base Next.js app created!');
-                        return 'Base Next.js app created';
+                        if (isTanStack) {
+                            await execa('npx', [
+                                '@tanstack/cli', 'create',
+                                answers.projectName,
+                                '-y',
+                                '--tailwind',
+                            ], {
+                                env: { ...process.env, npm_config_legacy_peer_deps: 'true' }
+                            });
+                        } else {
+                            await execa('npx', [
+                                'create-next-app@latest',
+                                answers.projectName,
+                                '--ts',
+                                '--tailwind',
+                                '--app',
+                                '--eslint',
+                                '--import-alias',
+                                '@/*',
+                                '--yes',
+                            ], {
+                                env: { ...process.env, npm_config_legacy_peer_deps: 'true' }
+                            });
+                        }
+                        spinner.succeed(`Base ${label} app created!`);
+                        return `Base ${label} app created`;
                     } catch (error) {
-                        spinner.fail('Failed to create Next.js app');
+                        spinner.fail(`Failed to create ${label} app`);
                         throw error;
                     }
                 },
@@ -88,14 +123,18 @@ export default function (plop) {
                     // Collect standard selections
                     const selectedPackages = ALL_ITEMS.filter(item => answers[item.id]);
 
-                    // Collect list-based selections (e.g. Payments)
+                    // Collect list-based selections (e.g. Payments, Database, Linting)
+                    const isNextjs = answers.framework === 'nextjs';
                     PACKAGE_GROUPS.filter(g => g.type === 'list').forEach(group => {
                         const choice = answers[group.id];
                         if (choice && choice !== 'none' && group.providerConfig[choice]) {
-                            selectedPackages.push({
-                                ...group.providerConfig[choice],
-                                id: `${group.id}_${choice}` // unique internal id
-                            });
+                            const config = { ...group.providerConfig[choice] };
+                            // Merge framework-specific dev dependencies
+                            if (isNextjs && config.devInstallNextjs) {
+                                config.devInstall = [...(config.devInstall || []), ...config.devInstallNextjs];
+                            }
+                            config.id = `${group.id}_${choice}`;
+                            selectedPackages.push(config);
                         }
                     });
 
@@ -165,21 +204,42 @@ export default function (plop) {
                     }).start();
 
                     try {
+                        const databaseChoice = answers.database || 'none';
+                        const isTanStack = answers.framework === 'tanstack';
                         const templateData = {
                             projectName: answers.projectName === '.' ? path.basename(projectPath) : answers.projectName,
-                            selectedPackages
+                            selectedPackages,
+                            isSupabase: databaseChoice === 'supabase',
+                            isConvex: databaseChoice === 'convex_cloud' || databaseChoice === 'convex_self',
+                            isNextjs: !isTanStack,
+                            isTanStack,
                         };
 
                         const readmeTmpl = fs.readFileSync(path.join(__dirname, 'templates/README.md.hbs'), 'utf8');
-                        const agentsTmpl = fs.readFileSync(path.join(__dirname, 'templates/AGENTS.md.hbs'), 'utf8');
-
                         const renderedReadme = plop.renderString(readmeTmpl, templateData);
-                        const renderedAgents = plop.renderString(agentsTmpl, templateData);
-
                         fs.writeFileSync(path.join(projectPath, 'README.md'), renderedReadme);
-                        fs.writeFileSync(path.join(projectPath, 'AGENTS.md'), renderedAgents);
 
-                        docSpinner.succeed('Documentation and AGENTS.md generated!');
+                        if (answers.isClaudeCode) {
+                            const claudeTmpl = fs.readFileSync(path.join(__dirname, 'templates/CLAUDE.md.hbs'), 'utf8');
+                            const renderedClaude = plop.renderString(claudeTmpl, templateData);
+                            fs.writeFileSync(path.join(projectPath, 'CLAUDE.md'), renderedClaude);
+                        } else {
+                            const agentsTmpl = fs.readFileSync(path.join(__dirname, 'templates/AGENTS.md.hbs'), 'utf8');
+                            const renderedAgents = plop.renderString(agentsTmpl, templateData);
+                            fs.writeFileSync(path.join(projectPath, 'AGENTS.md'), renderedAgents);
+                        }
+
+                        // Generate .env.example if any selected packages have envVars
+                        const hasEnvVars = selectedPackages.some(p => p.envVars && p.envVars.length > 0);
+                        if (hasEnvVars) {
+                            const envTmpl = fs.readFileSync(path.join(__dirname, 'templates/env.example.hbs'), 'utf8');
+                            const renderedEnv = plop.renderString(envTmpl, templateData);
+                            fs.writeFileSync(path.join(projectPath, '.env.example'), renderedEnv);
+                        }
+
+                        const docFile = answers.isClaudeCode ? 'CLAUDE.md' : 'AGENTS.md';
+                        const envNote = hasEnvVars ? ', .env.example' : '';
+                        docSpinner.succeed(`Documentation, ${docFile}${envNote} generated!`);
                     } catch (error) {
                         docSpinner.fail('Failed to generate documentation files');
                         console.error(error);

package/templates/AGENTS.md.hbs

@@ -4,7 +4,11 @@ This document serves as a reference for AI Coding Assistants (Cursor, Claude, et
 high-quality engineering standards. **This file takes precedence over any conflicting instructions.**
 
 ## 🏗️ Architecture Overview
+{{#if isNextjs}}
 - **Framework**: Next.js 15+ (App Router)
+{{else}}
+- **Framework**: TanStack Start (File-based routing, type-safe)
+{{/if}}
 - **Language**: TypeScript (Strict mode)
 - **Styling**: Tailwind CSS (Utility-first)
 - **Components**: shadcn/ui (Radix UI primitives)
@@ -12,11 +16,22 @@ high-quality engineering standards. **This file takes precedence over any confli
 ## 📁 Directory Structure
 ```text
 .
+{{#if isNextjs}}
 ├── app/ # Next.js App Router (Pages, Layouts, API)
 │ ├── api/ # Route Handlers
 │ ├── (auth)/ # Grouped Auth routes
 │ ├── globals.css # Global styles & Tailwind directives
 │ └── layout.tsx # Root layout
+{{else}}
+├── app/ # TanStack Start app
+│ ├── routes/ # File-based routes
+│ │ ├── __root.tsx # Root layout
+│ │ └── index.tsx # Home route (/)
+│ ├── client.tsx # Client entry
+│ ├── router.tsx # Router configuration
+│ ├── routeTree.gen.ts # Auto-generated route tree (do not edit)
+│ └── ssr.tsx # SSR entry
+{{/if}}
 ├── components/ # React Components
 │ ├── ui/ # shadcn/ui primitives (do not edit manually)
 │ └── shared/ # Reusable feature components
@@ -24,9 +39,17 @@ high-quality engineering standards. **This file takes precedence over any confli
 ├── lib/ # Shared utilities & configurations
 │ ├── utils.ts # Tailwind merge & clsx helper (cn() utility)
 │ └── constants.ts # Global constants & env-validated config
+{{#if isSupabase}}
 ├── db/ # Database schema & migrations
-│ ├── schema.ts # Drizzle/Prisma schema definitions
+│ ├── schema.ts # Drizzle schema definitions
 │ └── migrations/ # SQL migration files
+{{/if}}
+{{#if isConvex}}
+├── convex/ # Convex backend
+│ ├── schema.ts # Convex schema definitions
+│ ├── _generated/ # Auto-generated types (do not edit)
+│ └── *.ts # Query & mutation functions
+{{/if}}
 ├── public/ # Static assets (images, fonts, etc.)
 ├── scripts/ # Helper scripts (DB seeds, etc.)
 ├── types/ # Global TypeScript interfaces
@@ -50,7 +73,7 @@ high-quality engineering standards. **This file takes precedence over any confli
 
 ## 🛠️ Tech Stack Consistency & Guidance
 {{#each selectedPackages}}
-- **{{this.name}}**: {{#if this.guidance}}{{this.guidance}}{{else}}Use standard patterns as defined in official
+- **{{{this.name}}}**: {{#if this.guidance}}{{{this.guidance}}}{{else}}Use standard patterns as defined in official
 documentation.{{/if}}
 {{/each}}
 
@@ -60,9 +83,15 @@ documentation.{{/if}}
 - **Conciseness**: Write clean, modular code. Maintain DRY principles.
 - **Type Safety**: **Avoid `any`.** Use Zod for runtime validation and TypeScript for compile-time safety.
 - **Modern Syntax**: Prefer functional components, hooks, and async/await.
+{{#if isNextjs}}
 - **Server-First**: Favor Server Components by default; use `'use client'` sparingly and only at the leaf nodes (forms,
 triggers).
 - **Mutations**: Favor Next.js **Server Actions** for all data mutations.
+{{else}}
+- **Server-First**: Use TanStack Start server functions for data loading and mutations.
+- **Routing**: Use file-based routing in `app/routes/`. Dynamic segments use `$` prefix (e.g., `posts.$postId.tsx`).
+- **Data Loading**: Use route loaders for data fetching. Avoid `useState`/`useEffect` for data fetching.
+{{/if}}
 
 ### 2. Component Standards
 - **shadcn/ui**: Never modify components in `components/ui/` unless explicitly requested.
@@ -74,8 +103,13 @@ every component.
 avoid bundle bloat.
 
 ### 3. State & Data
+{{#if isNextjs}}
 - **Server State**: Use TanStack React Query or Server Actions.
 - **Client State**: Use Zustand for global state only if necessary. Favor URL state (`nuqs`) for UI-driven state.
+{{else}}
+- **Server State**: Use TanStack React Query or route loaders.
+- **Client State**: Use Zustand for global state only if necessary. Use TanStack Router's built-in `useSearch` for URL state.
+{{/if}}
 - **Forms**: Always use `useForm` from React Hook Form with a Zod resolver.
 - **Data Fetching**: Do not use `useState`/`useEffect` for data fetching.
 
@@ -85,15 +119,19 @@ avoid bundle bloat.
 - **Empty States**: Always use the `empty.tsx` shadcn component for missing data states.
 
 ### 5. Performance & SEO
-- **Images**: Use Next.js `
-<Image />` for optimized assets.
+{{#if isNextjs}}
+- **Images**: Use Next.js `<Image />` for optimized assets.
+- **SEO**: Implement metadata exports for every page.
+{{else}}
+- **Images**: Optimize images before serving. Use standard `<img>` with proper `loading="lazy"` attributes.
+- **SEO**: Use TanStack Start's `Meta` and `Head` components for per-route metadata.
+{{/if}}
 - **Accessibility**: Ensure proper semantic HTML and ARIA labels.
-- **SEO**: Implement metadata for every page.
 
 ## � Things to Avoid
 - **No Inline Styles**: Use Tailwind classes or `cn()`.
 - **No Direct Fetching in Hooks**: Avoid `useEffect` for manual fetching.
-- **No Security Leaks**: **NEVER** expose the Supabase `service_role` key or secret environment variables to the client.
+- **No Security Leaks**: **NEVER** expose secret environment variables to the client.{{#if isSupabase}} This includes the Supabase `service_role` key.{{/if}}
 - **No Magic Strings**: Move repeated strings, routes, or query keys to `lib/constants.ts`.
 
 ## 📝 Best Practices

package/templates/CLAUDE.md.hbs

@@ -0,0 +1,79 @@
+# {{projectName}}
+
+## Tech Stack
+{{#if isNextjs}}
+- **Framework**: Next.js 15+ (App Router)
+{{else}}
+- **Framework**: TanStack Start (File-based routing, type-safe)
+{{/if}}
+- **Language**: TypeScript (Strict mode)
+- **Styling**: Tailwind CSS (Utility-first)
+{{#each selectedPackages}}
+- **{{{this.name}}}**
+{{/each}}
+
+## Commands
+- Dev: `npm run dev`
+- Build: `npm run build`
+- Lint: `npm run lint`
+- Start: `npm start`
+
+## Directory Structure
+```
+{{#if isNextjs}}
+app/              # Pages, layouts, API route handlers
+{{else}}
+app/              # TanStack Start app
+  routes/         # File-based routes ($param for dynamic segments)
+    __root.tsx    # Root layout
+    index.tsx     # Home route (/)
+  client.tsx      # Client entry
+  router.tsx      # Router configuration
+  routeTree.gen.ts # Auto-generated route tree (do not edit)
+  ssr.tsx         # SSR entry
+{{/if}}
+components/
+  ui/             # shadcn/ui primitives (do not modify)
+  shared/         # Reusable feature components
+hooks/            # Custom React hooks (prefixed with use)
+lib/              # Utilities, constants, configs
+  utils.ts        # cn() helper (Tailwind merge + clsx)
+  constants.ts    # Global constants & env config
+{{#if isSupabase}}
+db/               # Database schema & migrations (Drizzle)
+  schema.ts       # Drizzle schema definitions
+  migrations/     # SQL migration files
+{{/if}}
+{{#if isConvex}}
+convex/           # Convex backend
+  schema.ts       # Convex schema definitions
+  _generated/     # Auto-generated types (do not edit)
+  *.ts            # Query & mutation functions
+{{/if}}
+types/            # Global TypeScript interfaces
+public/           # Static assets
+```
+
+## Code Conventions
+- Files & directories: `kebab-case`
+- Components: named exports, `PascalCase`
+- Variables & functions: `camelCase`
+- Constants: `SCREAMING_SNAKE_CASE`
+- Use `cn()` for all class name merging — never string concatenation
+{{#if isNextjs}}
+- Favor Server Components by default; use `'use client'` sparingly at leaf nodes
+- Use Server Actions for mutations
+{{else}}
+- Use TanStack Start server functions for data loading and mutations
+- Use file-based routing; dynamic segments use `$` prefix (e.g., `posts.$postId.tsx`)
+- Use TanStack Router's `useSearch` for type-safe URL state
+{{/if}}
+- Never use `useState`/`useEffect` for data fetching
+- Never expose secret env vars to the client{{#if isSupabase}} (e.g., Supabase `service_role` key){{/if}}{{#if isConvex}} (e.g., `CONVEX_SELF_HOSTED_ADMIN_KEY`){{/if}}
+
+## Library Guidance
+{{#each selectedPackages}}
+{{#if this.guidance}}
+- **{{{this.name}}}**: {{{this.guidance}}}
+{{/if}}
+{{/each}}

package/templates/README.md.hbs

@@ -5,13 +5,17 @@ This project was bootstrapped with [vibe-now](https://github.com/mosster/vibe-no
 ## 🚀 Installed Stack
 
 ### Core
+{{#if isNextjs}}
 - **Next.js** (App Router)
+{{else}}
+- **TanStack Start** (File-based routing)
+{{/if}}
 - **TypeScript**
 - **Tailwind CSS** (v4)
 
 ### Selected Features
 {{#each selectedPackages}}
-- **{{this.name}}**
+- **{{{this.name}}}**
 {{/each}}
 
 ## 🛠️ Getting Started
@@ -25,4 +29,4 @@ npm run dev
 Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
 
 ---
-Generated by quick-vibe
+Generated by vibe-now

package/templates/env.example.hbs

@@ -0,0 +1,13 @@
+# Generated by vibe-now
+# Copy this file to .env.local and fill in your values
+
+{{#each selectedPackages}}
+{{#if this.envVars}}
+# --- {{{this.name}}} ---
+{{#each this.envVars}}
+# {{this.comment}}
+{{this.key}}=
+{{/each}}
+
+{{/if}}
+{{/each}}

package/tests/TESTS.md

@@ -0,0 +1,92 @@
+# Test Configurations
+
+Generated by `node tests/generate-test-outputs.js` — renders all templates with different configs to verify conditional logic.
+
+## Test 1: `test-nextjs-supabase-claude/`
+
+| Setting | Value |
+|---------|-------|
+| Framework | Next.js |
+| AI Doc | CLAUDE.md |
+| Database | Supabase + Drizzle |
+| Payments | Stripe |
+| Linter | ESLint + Prettier |
+| Auth | Better Auth |
+| Theme | next-themes |
+
+**Packages:** Zustand, Zod, TanStack React Query, shadcn/ui, next-themes, Better Auth, React Hook Form, Supabase + Drizzle, Stripe, ESLint + Prettier
+
+**Generated files:** README.md, CLAUDE.md, .env.example (9 env vars)
+
+**Validates:**
+- Next.js-specific directory structure (`app/` with App Router)
+- `db/` directory shown (Supabase/Drizzle)
+- Server Components + Server Actions conventions
+- Supabase `service_role` key security warning
+- Stripe + Supabase + Better Auth env vars in `.env.example`
+
+---
+
+## Test 2: `test-nextjs-convex-agents/`
+
+| Setting | Value |
+|---------|-------|
+| Framework | Next.js |
+| AI Doc | AGENTS.md |
+| Database | Convex (Cloud) |
+| Payments | Polar.sh |
+| Linter | Biome |
+| Email | Resend |
+| Theme | next-themes |
+
+**Packages:** Zustand, Zod, TanStack React Query, shadcn/ui, next-themes, Resend, React Hook Form, Convex (Cloud), Polar.sh, Biome
+
+**Generated files:** README.md, AGENTS.md, .env.example (4 env vars)
+
+**Validates:**
+- AGENTS.md generated (not CLAUDE.md) — full AI coding rules doc
+- `convex/` directory shown (not `db/`)
+- Next.js framework with Convex backend
+- Biome guidance instead of ESLint
+- Resend, Convex, Polar env vars in `.env.example`
+
+---
+
+## Test 3: `test-tanstack-convex-self/`
+
+| Setting | Value |
+|---------|-------|
+| Framework | TanStack Start |
+| AI Doc | CLAUDE.md |
+| Database | Convex (Self-hosted) |
+| Payments | None |
+| Linter | ESLint + Prettier |
+| Auth | Better Auth |
+| AI | Vercel AI SDK + OpenRouter |
+| Theme | tanstack-theme-kit |
+
+**Packages:** Zustand, Zod, TanStack React Query, shadcn/ui, tanstack-theme-kit, Better Auth, Vercel AI SDK, OpenRouter AI SDK Provider, React Hook Form, Convex (Self-hosted), ESLint + Prettier
+
+**Generated files:** README.md, CLAUDE.md, .env.example (6 env vars)
+
+**Validates:**
+- TanStack Start directory structure (`routes/`, `__root.tsx`, `routeTree.gen.ts`)
+- `$` prefix routing convention (not Next.js `[param]`)
+- `convex/` directory with self-hosted config
+- `CONVEX_SELF_HOSTED_ADMIN_KEY` security warning
+- `useSearch` for URL state (not `nuqs`)
+- tanstack-theme-kit instead of next-themes
+- AI SDK + OpenRouter env vars in `.env.example`
+- No payment env vars (none selected)
+
+---
+
+## Config Validation Tests
+
+Run `node tests/validate-config.js` — 103 unit tests covering:
+- Package configuration integrity (ids, names, install arrays)
+- Framework-specific package filtering
+- Env var structure validation
+- ESLint framework-specific installs (`eslint-config-next` only for Next.js)
+- Template rendering for Next.js + Supabase and TanStack + Convex combinations
+- Database group structure and provider configs

package/tests/validate-config.js

@@ -0,0 +1,227 @@
+/**
+ * Validates the CLI configuration without running actual installs.
+ * Tests prompt generation, package filtering, template rendering, and env vars.
+ */
+
+import { PACKAGE_GROUPS, ALL_ITEMS } from '../lib/packages.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const Handlebars = require('handlebars');
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.join(__dirname, '..');
+
+let passed = 0;
+let failed = 0;
+
+function assert(condition, message) {
+    if (condition) {
+        console.log(`  ✅ ${message}`);
+        passed++;
+    } else {
+        console.error(`  ❌ ${message}`);
+        failed++;
+    }
+}
+
+// ============================================
+// Test 1: Package configuration integrity
+// ============================================
+console.log('\n📦 Test 1: Package configuration integrity\n');
+
+assert(PACKAGE_GROUPS.length > 0, 'PACKAGE_GROUPS is not empty');
+assert(ALL_ITEMS.length > 0, 'ALL_ITEMS is not empty');
+
+// Every item should have id, name, and install
+for (const item of ALL_ITEMS) {
+    assert(item.id && item.name, `Item ${item.id || '???'} has id and name`);
+    assert(Array.isArray(item.install), `${item.id} has install array`);
+}
+
+// List-based groups should have providerConfig
+const listGroups = PACKAGE_GROUPS.filter(g => g.type === 'list');
+for (const group of listGroups) {
+    assert(group.id, `List group "${group.category}" has id`);
+    assert(group.providerConfig, `List group "${group.category}" has providerConfig`);
+    assert(group.choices.length > 0, `List group "${group.category}" has choices`);
+
+    // Every non-none choice should have a providerConfig entry
+    for (const choice of group.choices) {
+        if (choice.value !== 'none') {
+            assert(
+                group.providerConfig[choice.value],
+                `${group.category}: providerConfig has entry for "${choice.value}"`
+            );
+        }
+    }
+}
+
+// ============================================
+// Test 2: Framework-specific packages
+// ============================================
+console.log('\n🔀 Test 2: Framework-specific packages\n');
+
+const nextjsOnly = ALL_ITEMS.filter(i => i.frameworks && i.frameworks.includes('nextjs') && !i.frameworks.includes('tanstack'));
+const tanstackOnly = ALL_ITEMS.filter(i => i.frameworks && i.frameworks.includes('tanstack') && !i.frameworks.includes('nextjs'));
+const universal = ALL_ITEMS.filter(i => !i.frameworks);
+
+assert(nextjsOnly.length > 0, `Found ${nextjsOnly.length} Next.js-only packages: ${nextjsOnly.map(i => i.id).join(', ')}`);
+assert(tanstackOnly.length > 0, `Found ${tanstackOnly.length} TanStack-only packages: ${tanstackOnly.map(i => i.id).join(', ')}`);
+assert(universal.length > 0, `Found ${universal.length} universal packages`);
+
+assert(nextjsOnly.some(i => i.id === 'nextThemes'), 'next-themes is Next.js-only');
+assert(tanstackOnly.some(i => i.id === 'tanstackThemeKit'), 'tanstack-theme-kit is TanStack-only');
+assert(nextjsOnly.some(i => i.id === 'nuqs'), 'nuqs is Next.js-only');
+
+// ============================================
+// Test 3: Env vars configuration
+// ============================================
+console.log('\n🔐 Test 3: Env vars configuration\n');
+
+// Check packages that should have envVars
+const packagesWithEnvVars = [];
+for (const group of PACKAGE_GROUPS) {
+    if (group.providerConfig) {
+        for (const [key, config] of Object.entries(group.providerConfig)) {
+            if (config.envVars) packagesWithEnvVars.push({ ...config, id: key });
+        }
+    }
+    if (group.items) {
+        for (const item of group.items) {
+            if (item.envVars) packagesWithEnvVars.push(item);
+        }
+    }
+}
+
+assert(packagesWithEnvVars.length > 0, `Found ${packagesWithEnvVars.length} packages with envVars`);
+
+// Validate envVar structure
+for (const pkg of packagesWithEnvVars) {
+    for (const envVar of pkg.envVars) {
+        assert(envVar.key && envVar.comment, `${pkg.id || pkg.name}: envVar "${envVar.key}" has key and comment`);
+    }
+}
+
+// Specific checks
+const supabaseConfig = PACKAGE_GROUPS.find(g => g.id === 'database')?.providerConfig?.supabase;
+assert(supabaseConfig?.envVars?.length === 4, `Supabase has 4 env vars`);
+
+const convexCloudConfig = PACKAGE_GROUPS.find(g => g.id === 'database')?.providerConfig?.convex_cloud;
+assert(convexCloudConfig?.envVars?.length === 1, `Convex Cloud has 1 env var`);
+
+const convexSelfConfig = PACKAGE_GROUPS.find(g => g.id === 'database')?.providerConfig?.convex_self;
+assert(convexSelfConfig?.envVars?.length === 2, `Convex Self-hosted has 2 env vars`);
+
+// ============================================
+// Test 4: ESLint framework-specific installs
+// ============================================
+console.log('\n🔧 Test 4: ESLint framework-specific installs\n');
+
+const linterGroup = PACKAGE_GROUPS.find(g => g.id === 'linter');
+const eslintConfig = linterGroup?.providerConfig?.eslint;
+
+assert(eslintConfig, 'ESLint config exists');
+assert(!eslintConfig.devInstall.includes('eslint-config-next'), 'eslint-config-next NOT in base devInstall');
+assert(eslintConfig.devInstallNextjs?.includes('eslint-config-next'), 'eslint-config-next IS in devInstallNextjs');
+
+// ============================================
+// Test 5: Template rendering
+// ============================================
+console.log('\n📄 Test 5: Template rendering\n');
+
+const templateFiles = ['README.md.hbs', 'AGENTS.md.hbs', 'CLAUDE.md.hbs', 'env.example.hbs'];
+for (const file of templateFiles) {
+    const filePath = path.join(rootDir, 'templates', file);
+    assert(fs.existsSync(filePath), `Template exists: ${file}`);
+}
+
+// Test rendering with mock data
+const mockData = {
+    projectName: 'test-project',
+    selectedPackages: [
+        { name: 'Zustand', guidance: 'Use stores wisely.' },
+        { name: 'Supabase + Drizzle', guidance: 'Keep queries server-side.', envVars: [
+            { key: 'NEXT_PUBLIC_SUPABASE_URL', comment: 'Supabase project URL' },
+            { key: 'SUPABASE_SERVICE_ROLE_KEY', comment: 'Service role key' },
+        ]},
+    ],
+    isNextjs: true,
+    isTanStack: false,
+    isSupabase: true,
+    isConvex: false,
+};
+
+for (const file of templateFiles) {
+    const tmplPath = path.join(rootDir, 'templates', file);
+    const tmpl = fs.readFileSync(tmplPath, 'utf8');
+    try {
+        const rendered = Handlebars.compile(tmpl)(mockData);
+        assert(rendered.length > 0, `${file} renders (Next.js + Supabase): ${rendered.length} chars`);
+
+        if (file === 'CLAUDE.md.hbs') {
+            assert(rendered.includes('Next.js'), 'CLAUDE.md contains Next.js for nextjs framework');
+            assert(rendered.includes('db/'), 'CLAUDE.md contains db/ for Supabase');
+            assert(!rendered.includes('convex/'), 'CLAUDE.md does NOT contain convex/ for Supabase');
+        }
+        if (file === 'env.example.hbs') {
+            assert(rendered.includes('NEXT_PUBLIC_SUPABASE_URL'), '.env.example contains Supabase URL');
+            assert(rendered.includes('SUPABASE_SERVICE_ROLE_KEY'), '.env.example contains service role key');
+        }
+    } catch (err) {
+        assert(false, `${file} rendering failed: ${err.message}`);
+    }
+}
+
+// Test TanStack + Convex rendering
+const tanstackConvexData = {
+    ...mockData,
+    isNextjs: false,
+    isTanStack: true,
+    isSupabase: false,
+    isConvex: true,
+    selectedPackages: [
+        { name: 'Zustand', guidance: 'Use stores wisely.' },
+        { name: 'Convex (Cloud)', guidance: 'Define schema in convex/.', envVars: [
+            { key: 'CONVEX_URL', comment: 'Convex deployment URL' },
+        ]},
+    ],
+};
+
+const claudeTmpl = fs.readFileSync(path.join(rootDir, 'templates/CLAUDE.md.hbs'), 'utf8');
+const renderedTanstack = Handlebars.compile(claudeTmpl)(tanstackConvexData);
+assert(renderedTanstack.includes('TanStack Start'), 'CLAUDE.md contains TanStack Start for tanstack framework');
+assert(renderedTanstack.includes('convex/'), 'CLAUDE.md contains convex/ for Convex');
+assert(!renderedTanstack.includes('db/'), 'CLAUDE.md does NOT contain db/ for Convex');
+assert(renderedTanstack.includes('routes/'), 'CLAUDE.md contains routes/ for TanStack');
+
+const envTmpl = fs.readFileSync(path.join(rootDir, 'templates/env.example.hbs'), 'utf8');
+const renderedEnv = Handlebars.compile(envTmpl)(tanstackConvexData);
+assert(renderedEnv.includes('CONVEX_URL'), '.env.example contains CONVEX_URL for Convex Cloud');
+assert(!renderedEnv.includes('SUPABASE'), '.env.example does NOT contain Supabase vars for Convex');
+
+// ============================================
+// Test 6: Database group structure
+// ============================================
+console.log('\n🗄️ Test 6: Database group structure\n');
+
+const dbGroup = PACKAGE_GROUPS.find(g => g.id === 'database');
+assert(dbGroup, 'Database group exists');
+assert(dbGroup.type === 'list', 'Database is a list-type group');
+assert(dbGroup.choices.length === 4, 'Database has 4 choices (none, supabase, convex_cloud, convex_self)');
+assert(dbGroup.providerConfig.supabase, 'Supabase provider config exists');
+assert(dbGroup.providerConfig.convex_cloud, 'Convex Cloud provider config exists');
+assert(dbGroup.providerConfig.convex_self, 'Convex Self-hosted provider config exists');
+assert(dbGroup.providerConfig.supabase.devInstall?.includes('drizzle-kit'), 'Supabase includes drizzle-kit as devDep');
+assert(!dbGroup.providerConfig.convex_cloud.devInstall, 'Convex Cloud has no devDeps');
+
+// ============================================
+// Summary
+// ============================================
+console.log(`\n${'='.repeat(40)}`);
+console.log(`Results: ${passed} passed, ${failed} failed`);
+console.log(`${'='.repeat(40)}\n`);
+
+process.exit(failed > 0 ? 1 : 0);