start-vibing-stacks 2.3.0 → 2.4.1

package/README.md

@@ -1,100 +1,184 @@
-# 🎸 Start Vibing Stacks
+# Start Vibing Stacks
 
-**Multi-stack AI-powered development workflow for Claude Code.**
+**Multi-stack AI-powered development workflow for Claude Code & Cursor.**
 
-One command to set up agents, skills, hooks, and quality gates — tailored to your stack.
-
-## 🚀 Quick Start
+One command to set up agents, skills, hooks, security rules, and quality gates — tailored to your stack.
 
 ```bash
 npx start-vibing-stacks
 ```
 
-Or install globally:
+## What It Does
+
+Start Vibing Stacks transforms Claude Code into a stack-aware AI partner. Instead of a generic assistant, you get an AI that understands your framework, enforces your coding standards, and blocks insecure patterns — all before a single line of code is written.
+
+```
+You run the CLI
+    ↓
+Detects your stack (PHP/Node.js) from project files
+    ↓
+Scans existing standards (.cursorrules, composer.json, tsconfig, eslint, .env)
+    ↓
+Asks: adapt to YOUR standards or use defaults?
+    ↓
+Copies 6 agents + 25-40 skills + hooks + security rules
+    ↓
+Generates CLAUDE.md with architecture, rules, FORBIDDEN patterns
+    ↓
+Launches Claude Code — fully configured
+```
+
+## Supported Stacks
+
+### PHP 8.3+
+
+| Option | Choices |
+|--------|---------|
+| **Frameworks** | Laravel 12 + Octane (RoadRunner) + Inertia.js, Laravel 12 (standard) |
+| **Databases** | MySQL / MariaDB, PostgreSQL, SQLite |
+| **Frontend** | React 19 + Inertia.js + TailwindCSS 4, Blade + TailwindCSS, Livewire + Alpine.js, API only |
+| **Skills** | 13 PHP-specific (Octane, PHPStan, PHPUnit, Eloquent, API Security, Inertia i18n, ...) |
+
+### Node.js / TypeScript
+
+| Option | Choices |
+|--------|---------|
+| **Frameworks** | Next.js (App Router), Nuxt, Astro, Express, Fastify, Vanilla Node.js |
+| **Databases** | MongoDB, PostgreSQL, MySQL, SQLite/Turso, Redis (Upstash), None |
+| **Frontend** | React 19 + TailwindCSS 4, Vue.js / Nuxt, Svelte / SvelteKit, API only |
+| **Skills** | 5 Node-specific (TypeScript strict, Next.js App Router, tRPC, Bun, Mongoose) + 9 frontend skills |
+
+### Python (Coming Soon)
+
+Django, FastAPI, Flask support is planned.
+
+## What Gets Installed
 
-```bash
-npm install -g start-vibing-stacks
-svs  # shortcut
 ```
+your-project/
+├── CLAUDE.md                    # AI memory — architecture, rules, FORBIDDEN patterns
+└── .claude/
+    ├── agents/                  # 6 universal agents
+    │   ├── research-web.md      # Researches best practices before new features
+    │   ├── documenter.md        # Maps files to domains, tracks changes
+    │   ├── domain-updater.md    # Records problems, solutions, learnings
+    │   ├── commit-manager.md    # Conventional commits, merge workflow
+    │   ├── tester.md            # Creates tests (Vitest/PHPUnit/Playwright)
+    │   └── claude-md-compactor.md  # Compacts CLAUDE.md when > 40k chars
+    ├── skills/                  # 25-40 skills (stack + shared + frontend)
+    │   ├── quality-gate/        # Typecheck, lint, test validation
+    │   ├── security-scan/       # OWASP checks per language
+    │   ├── git-workflow/        # Branch management, conventional commits
+    │   ├── codebase-knowledge/  # Domain documentation system
+    │   └── ...                  # Stack-specific skills
+    ├── hooks/
+    │   ├── stop-validator.ts    # Blocks incomplete tasks (branch, git, docs)
+    │   └── user-prompt-submit.ts  # Injects workflow + standards context
+    ├── commands/                # /feature, /fix, /research, /validate
+    ├── config/
+    │   ├── active-project.json  # Stack, framework, database, skills
+    │   ├── security-rules.json  # OWASP checks + env exposure rules
+    │   ├── standards-review.json  # Imported project standards
+    │   └── ...                  # Quality gates, testing, domain mapping
+    └── settings.json            # Claude Code permissions & model config
+```
+
+## Security Features
+
+### Environment Variable Protection (Node.js)
+
+The tool enforces strict separation of server and client environment variables:
 
-## ✨ Features
+- **Scanner**: Detects `NEXT_PUBLIC_` with sensitive words (SECRET, TOKEN, API_KEY) in `.env*` files
+- **CLAUDE.md**: FORBIDDEN rules prevent AI from exposing secrets in browser bundles
+- **Skills**: Teach API proxy patterns — external API calls must go through Route Handlers
+- **security-rules.json**: Automated detection patterns for security audits
 
-- **🔍 Auto-detection** — Scans your project files to suggest the right stack
-- **🐘 PHP 8.3+** — PHPStan, PHPUnit, Composer, Laravel/Octane
-- **📦 Node.js/TS** — Vitest, TypeScript, Bun, Next.js, Express
-- **🎯 Multi-framework** — Choose your framework, database, frontend, deploy target
-- **🤖 6 Universal Agents** — research, documenter, domain-updater, commit-manager, tester, compactor
-- **🛡️ Quality Gates** — Stack-specific validation before every commit
-- **🔒 Security Skills** — OWASP checks adapted per language
-- **📝 .cursorrules support** — Imports existing Cursor IDE rules
-- **⚡ Auto-install** — Validates and installs missing deps (Homebrew on macOS)
+### PHP Security
 
-## 📋 Supported Stacks
+- OWASP Top 10 adapted for Laravel + Octane
+- Octane-safe patterns (no static state, no globals)
+- `env()` restriction (config files only)
+- Frontend secret isolation (Inertia props)
+- Rate limiting, CORS, CSP, encryption at rest
 
-| Stack | Status | Frameworks |
-|-------|--------|------------|
-| 🐘 PHP 8.3+ | ✅ Ready | Laravel, Laravel+Octane |
-| 📦 Node.js/TS | ✅ Ready | Next.js, Nuxt, Astro, Express, Fastify |
-| 🐍 Python | 🔜 Soon | Django, FastAPI, Flask |
-| 🦀 Rust | 🔜 Soon | Actix, Axum |
-| 🐹 Go | 🔜 Soon | Gin, Echo |
+## Standards Review
 
-## 🏗️ What It Creates
+Before modifying anything, the CLI scans your project for existing patterns:
 
 ```
-.claude/
-├── agents/          # 6 universal agents (stack-aware)
-├── skills/          # Stack-specific + shared skills
-├── hooks/           # stop-validator + prompt-inject
-├── config/          # Project config, quality gates, security rules
-├── commands/        # /feature, /fix, /validate
-└── settings.json    # Claude Code permissions
+Scans:  .cursorrules, composer.json, package.json, tsconfig.json,
+        eslint config, phpstan.neon, .env files, framework configs,
+        lockfiles, deploy configs, quality tool configs
+
+Detects: 50+ npm packages, 17+ Composer packages, TypeScript strict mode,
+         path aliases, ESLint config, PHPStan level, package manager,
+         deploy targets, exposed secrets in NEXT_PUBLIC_*
+
+Result:  "Adapt to your standards" or "Use plugin defaults"
+         → Saved in standards-review.json
+         → Injected into every Claude prompt via hook
 ```
 
-## 🔧 Options
+## CLI Options
 
 ```bash
 npx start-vibing-stacks [options]
 
 --force           Overwrite existing configuration
---no-claude       Skip Claude Code installation
+--no-claude       Skip Claude Code launch
 --no-install      Skip dependency installation
 --help, -h        Show help
 --version, -v     Show version
 ```
 
-## 🐘 PHP Requirements
+Or install globally:
 
-When selecting the PHP stack, the tool validates and auto-installs:
+```bash
+npm install -g start-vibing-stacks
+svs  # shortcut alias
+```
 
-- **PHP >= 8.3** (via `brew install php@8.3` on macOS)
-- **Composer >= 2.0** (auto-installed using PHP if missing)
-- **Node.js >= 18** (for frontend tooling)
+## How the Workflow Works
 
-### Laravel + Octane (RoadRunner)
+Once configured, Claude Code follows this workflow on every task:
 
-Select "Laravel + Octane (RoadRunner)" in the framework menu for:
-- RoadRunner server configuration
-- Octane-specific skills and patterns
-- High-performance deployment guides
+```
+0. TODO LIST      → Creates detailed task breakdown
+1. BRANCH         → Creates feature/ | fix/ | refactor/ | test/
+2. RESEARCH       → Runs research-web agent for new features
+3. IMPLEMENT      → Follows stack rules + strict types + security
+4. TEST           → Runs tester agent (PHPUnit / Vitest / Playwright)
+5. DOCUMENT       → Runs documenter agent for modified files
+6. UPDATE         → Updates CLAUDE.md with changes
+7. QUALITY        → Runs quality gates (typecheck, lint, test, build)
+8. COMMIT         → Conventional commits, merge to main
+```
 
-## 📝 Cursor IDE Support
+The **stop-validator hook** blocks task completion if:
+- Not on `main` branch (work must be merged)
+- Uncommitted changes exist
+- CLAUDE.md wasn't updated
+- Source files lack documentation
 
-If `.cursorrules` is detected in your project, the rules are automatically imported into the Claude agent configuration. Both AI tools work with the same context.
+## Cursor IDE Support
 
-## 🔄 How It Works
+If `.cursorrules` is detected, the rules are automatically imported into the Claude configuration. Both AI tools work with the same context.
 
-1. **Detect** — Scans project for `composer.json`, `package.json`, etc.
-2. **Select** — You choose stack, framework, database, frontend, deploy
-3. **Validate** — Checks system requirements, installs missing tools
-4. **Configure** — Copies agents, skills, hooks tailored to your choices
-5. **Launch** — Starts Claude Code with everything pre-configured
+## Requirements
 
-## 📄 License
+| Stack | Requirements |
+|-------|-------------|
+| **PHP** | PHP >= 8.3, Composer >= 2.0, Node.js >= 18 |
+| **Node.js** | Node.js >= 18 (Bun optional) |
 
-MIT
+Missing dependencies are auto-installed via Homebrew on macOS.
 
-## 🏠 Credits
+## Credits
 
 Inspired by [start-vibing](https://www.npmjs.com/package/start-vibing).
 Built by [FantasyLake](https://github.com/f1sc4ll-ai).
+
+## License
+
+MIT

package/dist/detector.js

@@ -25,10 +25,6 @@ const STACK_SIGNATURES = [
     { id: 'python', files: ['pyproject.toml'], weight: 90, reason: 'pyproject.toml detected' },
     { id: 'python', files: ['Pipfile'], weight: 85, reason: 'Pipfile detected' },
     { id: 'python', files: ['setup.py'], weight: 75, reason: 'setup.py detected' },
-    // Rust
-    { id: 'rust', files: ['Cargo.toml'], weight: 95, reason: 'Cargo.toml detected' },
-    // Go
-    { id: 'go', files: ['go.mod'], weight: 95, reason: 'go.mod detected' },
 ];
 export function detectProject(projectDir) {
     const result = {
@@ -95,8 +91,26 @@ export function detectNodeFramework(projectDir) {
         return 'nextjs';
     if (existsSync(join(projectDir, 'nuxt.config.ts')))
         return 'nuxt';
-    if (existsSync(join(projectDir, 'astro.config.mjs')))
+    if (existsSync(join(projectDir, 'astro.config.mjs')) || existsSync(join(projectDir, 'astro.config.ts')))
         return 'astro';
+    if (existsSync(join(projectDir, 'svelte.config.js')) || existsSync(join(projectDir, 'svelte.config.ts')))
+        return 'svelte';
+    const pkgPath = join(projectDir, 'package.json');
+    if (existsSync(pkgPath)) {
+        try {
+            const pkg = JSON.parse(readFileSync(pkgPath, 'utf8'));
+            const deps = { ...pkg.dependencies, ...pkg.devDependencies };
+            if (deps['express'])
+                return 'express';
+            if (deps['fastify'])
+                return 'fastify';
+            if (deps['hono'])
+                return 'hono';
+        }
+        catch {
+            // ignore parse errors
+        }
+    }
     return null;
 }
 export function detectPythonFramework(projectDir) {

package/dist/index.js

@@ -6,7 +6,8 @@
  * Detects project stack, validates requirements, and configures agents.
  */
 import { existsSync, readFileSync } from 'fs';
-import { join, basename } from 'path';
+import { join, basename, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
 import inquirer from 'inquirer';
 import chalk from 'chalk';
 import * as ui from './ui.js';
@@ -15,6 +16,10 @@ import { autoInstall, installComposer, installClaudeCode } from './installer.js'
 import { loadStackConfig, setupProject } from './setup.js';
 import { selectMcpServers, installMcpServers } from './mcp.js';
 import { scanProjectStandards } from './scanner.js';
+const __cli_filename = fileURLToPath(import.meta.url);
+const __cli_dirname = dirname(__cli_filename);
+const CLI_ROOT = resolve(__cli_dirname, '..');
+const PKG_VERSION = JSON.parse(readFileSync(join(CLI_ROOT, 'package.json'), 'utf8')).version;
 // =============================================================================
 // CLI Arguments
 // =============================================================================
@@ -28,7 +33,7 @@ const FLAGS = {
     version: args.includes('--version') || args.includes('-v'),
 };
 if (FLAGS.version) {
-    console.log('1.0.0');
+    console.log(PKG_VERSION);
     process.exit(0);
 }
 if (FLAGS.help) {
@@ -158,12 +163,15 @@ async function main() {
             : stackId === 'python'
                 ? detectPythonFramework(projectDir)
                 : null;
+    const defaultFramework = detectedFramework ||
+        stackConfig.frameworks.find((f) => f.default)?.id ||
+        undefined;
     const { framework } = await inquirer.prompt([
         {
             type: 'list',
             name: 'framework',
             message: 'Select framework:',
-            default: detectedFramework || undefined,
+            default: defaultFramework,
             choices: stackConfig.frameworks.map((f) => ({
                 name: `${f.icon}  ${f.name}`,
                 value: f.id,
@@ -185,11 +193,13 @@ async function main() {
     ]);
     // ─── Step 5: Frontend ──────────────────────────────────────────────────
     const compatibleFrontends = stackConfig.frontendOptions.filter((f) => !f.frameworks || f.frameworks.includes(framework));
+    const defaultFrontend = compatibleFrontends.find((f) => f.default)?.id || undefined;
     const { frontend } = await inquirer.prompt([
         {
             type: 'list',
             name: 'frontend',
             message: 'Frontend included?',
+            default: defaultFrontend,
             choices: compatibleFrontends.map((f) => ({
                 name: `${f.icon}  ${f.name}`,
                 value: f.id,
@@ -249,12 +259,14 @@ async function main() {
         }
     }
     // ─── Step 7: Show Summary & Confirm ────────────────────────────────────
+    const selectedFrontend = compatibleFrontends.find((f) => f.id === frontend);
     const config = {
         name: projectName,
         stack: stackId,
         framework,
         database,
         frontend,
+        frontendSkillsDir: selectedFrontend?.skillsDir,
         deploy,
         path: projectDir,
         createdAt: new Date().toISOString(),

package/dist/scanner.js

@@ -102,6 +102,8 @@ const NPM_PACKAGES = {
     // Media
     'uploadthing': { category: 'media', name: 'UploadThing file uploads' },
     'sharp': { category: 'media', name: 'Sharp image processing' },
+    // Design System
+    'preline': { category: 'ui', name: 'Preline UI design system' },
 };
 function readFileIfExists(path) {
     if (!existsSync(path))
@@ -424,8 +426,14 @@ function scanProjectFiles(projectDir) {
         patterns.push({ category: 'quality', name: 'Prettier config present', confidence: 100 });
     }
     // Environment files (works for both PHP and Node.js projects)
-    const envContent = readFileIfExists(join(projectDir, '.env.example')) ||
-        readFileIfExists(join(projectDir, '.env'));
+    const envFiles = ['.env.example', '.env', '.env.local', '.env.development', '.env.production'];
+    let envContent = null;
+    for (const envFile of envFiles) {
+        const content = readFileIfExists(join(projectDir, envFile));
+        if (content) {
+            envContent = (envContent || '') + '\n' + content;
+        }
+    }
     if (envContent) {
         if (/REDIS_HOST|REDIS_URL/i.test(envContent)) {
             patterns.push({ category: 'cache', name: 'Redis configured', confidence: 85 });
@@ -442,6 +450,19 @@ function scanProjectFiles(projectDir) {
         if (/STRIPE_SECRET|STRIPE_KEY/i.test(envContent)) {
             patterns.push({ category: 'billing', name: 'Stripe payments configured', confidence: 85 });
         }
+        // Security: detect NEXT_PUBLIC_ with sensitive values
+        const sensitivePublicEnv = envContent.match(/^NEXT_PUBLIC_\w*(SECRET|TOKEN|PRIVATE|PASSWORD|CREDENTIAL|OPENAI|API_KEY|DATABASE)\w*\s*=/gmi);
+        if (sensitivePublicEnv) {
+            for (const match of sensitivePublicEnv) {
+                const varName = match.split('=')[0].trim();
+                patterns.push({
+                    category: 'security',
+                    name: `EXPOSED SECRET: ${varName} is public (visible in browser)`,
+                    confidence: 100,
+                    detail: `${varName} uses NEXT_PUBLIC_ prefix which embeds the value in the client JS bundle. Remove NEXT_PUBLIC_ and access via Route Handler or Server Action.`,
+                });
+            }
+        }
     }
     if (patterns.length === 0)
         return null;

package/dist/setup.js

@@ -7,6 +7,7 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, statSy
 import { join, dirname, resolve } from 'path';
 import { fileURLToPath } from 'url';
 import ora from 'ora';
+import * as ui from './ui.js';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const PACKAGE_ROOT = resolve(__dirname, '..');
@@ -89,7 +90,8 @@ export async function setupProject(projectDir, config, options = {}) {
         copyDirRecursive(stackConfigDir, join(claudeDir, 'config'), options.force);
         // 8. Copy frontend-specific skills if applicable
         if (config.frontend && config.frontend !== 'none') {
-            const frontendDir = join(PACKAGE_ROOT, 'stacks', 'frontend', config.frontend);
+            const frontendId = config.frontendSkillsDir || config.frontend;
+            const frontendDir = join(PACKAGE_ROOT, 'stacks', 'frontend', frontendId);
             if (existsSync(frontendDir)) {
                 const feSkillCount = copyDirRecursive(join(frontendDir, 'skills'), join(claudeDir, 'skills'), options.force);
                 spinner.text = `Loaded ${feSkillCount} frontend skills`;
@@ -286,6 +288,20 @@ export async function setupProject(projectDir, config, options = {}) {
             settings.quality_gates = gates;
         }
         writeFileSync(join(claudeDir, 'settings.json'), JSON.stringify(settings, null, '\t'));
+        // 14. Detect Preline and suggest official agent skills
+        const projectPkgPath = join(projectDir, 'package.json');
+        if (existsSync(projectPkgPath)) {
+            try {
+                const projectPkg = JSON.parse(readFileSync(projectPkgPath, 'utf8'));
+                const allDeps = { ...projectPkg.dependencies, ...projectPkg.devDependencies };
+                if (allDeps['preline'] && !existsSync(join(claudeDir, 'skills', 'preline-theme-generator'))) {
+                    ui.info('Preline UI detected — run: npx skills add htmlstreamofficial/preline');
+                }
+            }
+            catch {
+                // package.json parse error, skip
+            }
+        }
         spinner.succeed(`Setup complete: ${agentCount} agents, ${sharedSkillCount + stackSkillCount} skills, ${hookCount} hooks`);
         return true;
     }

package/dist/types.d.ts

@@ -32,6 +32,7 @@ export interface FrameworkOption {
     icon: string;
     detectFiles?: string[];
     skills?: string[];
+    default?: boolean;
     extra?: Record<string, unknown>;
 }
 export interface DatabaseOption {
@@ -44,6 +45,8 @@ export interface FrontendOption {
     name: string;
     icon: string;
     frameworks?: string[];
+    skillsDir?: string;
+    default?: boolean;
 }
 export interface DeployTarget {
     id: string;
@@ -67,6 +70,7 @@ export interface ProjectConfig {
     framework: string;
     database: string;
     frontend: string;
+    frontendSkillsDir?: string;
     deploy: string;
     path: string;
     createdAt: string;

package/dist/ui.js

@@ -1,12 +1,13 @@
 /**
  * Start Vibing Stacks — Terminal UI
  */
+import { readFileSync } from 'fs';
+import { join, dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
 import chalk from 'chalk';
-const VERSION = '2.2.0';
-const gradient = (text) => {
-    const colors = [chalk.hex('#FF6B6B'), chalk.hex('#FF8E53'), chalk.hex('#FFBD2E'), chalk.hex('#48BB78'), chalk.hex('#4299E1'), chalk.hex('#9F7AEA')];
-    return text.split('').map((c, i) => colors[i % colors.length](c)).join('');
-};
+const __ui_filename = fileURLToPath(import.meta.url);
+const __ui_dirname = dirname(__ui_filename);
+const VERSION = JSON.parse(readFileSync(join(resolve(__ui_dirname, '..'), 'package.json'), 'utf8')).version;
 export const LOGO = `
 ${chalk.hex('#9F7AEA')('    ╔═══════════════════════════════════════════════╗')}
 ${chalk.hex('#9F7AEA')('    ║')}                                                 ${chalk.hex('#9F7AEA')('║')}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "start-vibing-stacks",
-  "version": "2.3.0",
+  "version": "2.4.1",
   "description": "AI-powered multi-stack dev workflow for Claude Code. Supports PHP, Node.js, Python and more.",
   "type": "module",
   "bin": {

package/stacks/_shared/config/security-rules.json

@@ -5,17 +5,39 @@
   },
   "sensitivePatterns": {
     "forbidden": [
-      "eval(",
-      "exec(",
-      "system(",
-      "passthru(",
-      "shell_exec(",
       "password:",
       "passwordHash",
       "apiKey:",
       "secret:"
     ]
   },
+  "envExposure": {
+    "$comment": "NEXT_PUBLIC_ vars are embedded in browser JS bundle. These patterns indicate secrets being exposed to the client.",
+    "forbiddenPublicEnvPatterns": [
+      "NEXT_PUBLIC_.*SECRET",
+      "NEXT_PUBLIC_.*TOKEN",
+      "NEXT_PUBLIC_.*PRIVATE",
+      "NEXT_PUBLIC_.*PASSWORD",
+      "NEXT_PUBLIC_.*CREDENTIAL"
+    ],
+    "forbiddenPublicEnvExact": [
+      "NEXT_PUBLIC_OPENAI_KEY",
+      "NEXT_PUBLIC_OPENAI_API_KEY",
+      "NEXT_PUBLIC_STRIPE_SECRET",
+      "NEXT_PUBLIC_STRIPE_SECRET_KEY",
+      "NEXT_PUBLIC_DATABASE_URL",
+      "NEXT_PUBLIC_SUPABASE_SERVICE_KEY",
+      "NEXT_PUBLIC_FIREBASE_ADMIN_KEY"
+    ],
+    "safePublicEnvPatterns": [
+      "NEXT_PUBLIC_.*URL",
+      "NEXT_PUBLIC_.*ID",
+      "NEXT_PUBLIC_STRIPE_KEY",
+      "NEXT_PUBLIC_GA_",
+      "NEXT_PUBLIC_SENTRY_DSN"
+    ],
+    "rule": "API keys, secrets, and tokens MUST stay server-side. Use Route Handlers or Server Actions as proxy."
+  },
   "cookies": {
     "httpOnly": true,
     "secure": true,

package/stacks/frontend/react/skills/preline-ui/SKILL.md

@@ -10,7 +10,7 @@ Preline is a **semantic token-based design system** built on TailwindCSS. It pro
 - Theme generator for custom color schemes
 - Light + dark mode via `data-theme` + `.dark`
 
-## Installation (Laravel + Inertia)
+## Installation
 
 ### Step 1: Install
 
@@ -21,7 +21,7 @@ npm install preline @tailwindcss/forms
 ### Step 2: CSS Config
 
 ```css
-/* resources/css/app.css */
+/* src/app/globals.css (Next.js) or styles/globals.css */
 @import "tailwindcss";
 
 /* Preline — MUST be in this order */
@@ -31,39 +31,35 @@ npm install preline @tailwindcss/forms
 @import "./node_modules/preline/themes/theme.css"; /* Base theme */
 ```
 
-### Step 3: Vite Config
+### Step 3: Init Preline on Route Changes (MANDATORY)
 
-```js
-// vite.config.js
-import { defineConfig } from 'vite';
-import laravel from 'laravel-vite-plugin';
-import react from '@vitejs/plugin-react';
+```tsx
+// src/components/PrelineInit.tsx
+'use client';
 
-export default defineConfig({
-  plugins: [
-    laravel({ input: ['resources/css/app.css', 'resources/js/app.tsx'], refresh: true }),
-    react(),
-  ],
-});
-```
+import { usePathname } from 'next/navigation';
+import { useEffect } from 'react';
 
-### Step 4: Init Preline in Inertia (MANDATORY)
+export function PrelineInit() {
+  const pathname = usePathname();
 
-```tsx
-// resources/js/app.tsx
-import { router } from '@inertiajs/react';
-
-// Re-init Preline components after every SPA navigation
-router.on('navigate', () => {
-  setTimeout(() => {
-    import('preline/preline').then(({ HSStaticMethods }) => {
-      HSStaticMethods.autoInit();
-    });
-  }, 100);
-});
+  useEffect(() => {
+    const timer = setTimeout(() => {
+      import('preline/preline').then(({ HSStaticMethods }) => {
+        HSStaticMethods.autoInit();
+      });
+    }, 100);
+    return () => clearTimeout(timer);
+  }, [pathname]);
+
+  return null;
+}
+
+// Add to root layout:
+// <PrelineInit />
 ```
 
-**Rule:** Without `HSStaticMethods.autoInit()`, dropdowns, modals, and accordions will NOT work after Inertia navigation.
+**Rule:** Without `HSStaticMethods.autoInit()`, dropdowns, modals, and accordions will NOT work after client-side navigation.
 
 ## Templates & Components (840+ free)
 
@@ -80,11 +76,11 @@ router.on('navigate', () => {
 
 1. Browse https://preline.co/examples.html
 2. Click a block → copy the HTML/JSX
-3. Adapt to React + Inertia:
-   - Replace `<a href>` with `<Link href>` (Inertia)
+3. Adapt to React:
+   - Replace `<a href>` with Next.js `<Link href>` (from `next/link`)
    - Replace `class=` with `className=`
    - Add Preline `data-*` attributes for interactive components
-   - Use `usePage().props` for dynamic data
+   - Pass data via props or fetch with TanStack Query / Server Components
 
 ### Example: Copy a Hero Block
 
@@ -245,7 +241,7 @@ function ThemeToggle() {
 }
 ```
 
-## Using Components with React (Inertia)
+## Using Components with React
 
 ### Navbar
 
@@ -327,7 +323,7 @@ function ThemeToggle() {
 
 ```bash
 # Generate theme from config
-npx preline-theme-generator /tmp/config.json ./resources/css/themes/brand.css
+npx preline-theme-generator /tmp/config.json ./src/styles/themes/brand.css
 
 # Config format:
 {
@@ -359,4 +355,4 @@ npx preline-theme-generator /tmp/config.json ./resources/css/themes/brand.css
 | Force HTML class changes | Theme activation via `data-theme` only |
 | Invent token names | Follow Preline's naming system |
 | `@apply` for component styles | React components with token classes |
-| Skip `HSStaticMethods.autoInit()` | Always re-init after Inertia navigation |
+| Skip `HSStaticMethods.autoInit()` | Always re-init after client-side navigation |