create-fluxstack 1.12.0 → 1.13.0

package/README.md

@@ -2,7 +2,7 @@
 
 # ⚡ FluxStack
 
-### The Revolutionary Full-Stack TypeScript Framework
+### The Full-Stack TypeScript Framework for Real-Time Apps
 
 *Build modern web apps with Bun, Elysia, React, and Eden Treaty*
 
@@ -12,7 +12,7 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-007ACC?style=flat&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
 [![React](https://img.shields.io/badge/React-20232A?style=flat&logo=react&logoColor=61DAFB)](https://reactjs.org/)
 
-[Quick Start](#-quick-start) • [Features](#-key-features) • [Documentation](#-documentation--support) • [Examples](#-type-safe-api-development)
+[Quick Start](#-quick-start) • [Features](#-key-features) • [Live Components](#-live-components) • [Documentation](#-documentation--support)
 
 </div>
 
@@ -42,18 +42,19 @@
 <tr>
 <td width="50%">
 
-### 🛠️ **Zero Configuration**
-- **One Command Setup** - `bunx create-fluxstack`
-- **Hot Reload Built-in** - Backend + Frontend
-- **Swagger Auto-Generated** - API docs out of the box
+### ⚡ **Live Components**
+- **WebSocket Sync** - Real-time state synchronization
+- **Reactive Proxy** - `this.state.count++` auto-syncs
+- **Room System** - Multi-room real-time communication
+- **Auth System** - Declarative RBAC for components
 
 </td>
 <td width="50%">
 
 ### 🎯 **Production Ready**
 - **Docker Multi-Stage** - Optimized containers
-- **Declarative Config** - Environment management
-- **WebSocket Support** - Real-time features
+- **Declarative Config** - Laravel-inspired config system
+- **Plugin Security** - Whitelist-based NPM plugin safety
 
 </td>
 </tr>
@@ -61,35 +62,23 @@
 
 ---
 
-## 🚀 Quick Start
-
-```bash
-# Create a new FluxStack app
-bunx create-fluxstack my-awesome-app
-cd my-awesome-app
-bun run dev
-```
-
-**That's it!** Your full-stack app is running at:
-
-- 🌐 **Frontend & Backend**: http://localhost:3000
-- 📚 **API Documentation**: http://localhost:3000/swagger
-- ⚡ **Hot Reload**: Automatic on file changes
-
-### 🔀 Frontend Routes (React Router v7)
-
-Default routes in the demo app:
-
-- `/` Home
-- `/counter` Live Counter
-- `/form` Live Form
-- `/upload` Live Upload
-- `/api-test` Eden Treaty API Test
-
-### 🧭 Router Package
-
-This project now uses **React Router v7** via the `react-router` package (recommended by the v7 docs).
-If you are upgrading from an older setup that used `react-router-dom`, update imports to `react-router`.
+## 🚀 Quick Start
+
+```bash
+# Create a new FluxStack app
+bunx create-fluxstack my-awesome-app
+cd my-awesome-app
+bun run dev
+```
+
+**That's it!** Your full-stack app is running:
+
+| Service | URL |
+|---------|-----|
+| 🌐 **Frontend** | http://localhost:5173 |
+| ⚙️ **Backend API** | http://localhost:3000 |
+| 📚 **Swagger Docs** | http://localhost:3000/swagger |
+| 🩺 **Health Check** | http://localhost:3000/api/health |
 
 ### Alternative Installation
 
@@ -102,36 +91,68 @@ bun run dev
 
 ---
 
-## 💎 What You Get
+## 💎 Tech Stack
 
-<details open>
-<summary><b>🎨 Modern Tech Stack (2025)</b></summary>
-
-| Layer | Technology | Version | Why? |
-|-------|-----------|---------|------|
-| 🏃 **Runtime** | Bun | 1.2+ | 3x faster than Node.js |
-| ⚙️ **Backend** | Elysia.js | 1.4.6 | Ultra-fast API framework |
-| ⚛️ **Frontend** | React | 19.1 | Latest React features |
-| ⚡ **Build Tool** | Vite | 7.1.7 | Instant dev server |
-| 💅 **Styling** | Tailwind CSS | 4.1.13 | Utility-first CSS |
-| 📘 **Language** | TypeScript | 5.8.3 | Full type safety |
-| 🔌 **API Client** | Eden Treaty | 1.3.2 | Type-safe API calls |
-
-</details>
-
-<details open>
-<summary><b>⚙️ Zero-Config Features</b></summary>
-
-- ✅ **Automatic Type Inference** - Eden Treaty connects backend types to frontend
-- ✅ **Coordinated Hot Reload** - Backend and frontend reload independently
-- ✅ **Auto-Generated Swagger** - API documentation updates automatically
-- ✅ **Docker Templates** - Production-ready multi-stage builds included
-- ✅ **AI-Focused Docs** - LLM-optimized documentation (`LLMD/`)
-- ✅ **Declarative Config** - Laravel-inspired configuration system
-- ✅ **WebSocket Support** - Real-time features built-in
-- ✅ **Testing Setup** - Vitest + React Testing Library ready
-
-</details>
+<table>
+<tr>
+<td align="center" width="12.5%">
+<br>
+<img src="https://img.shields.io/badge/Bun-000?style=for-the-badge&logo=bun&logoColor=white" alt="Bun">
+<br><b>Runtime</b><br>
+<sub>Bun >= 1.2</sub>
+<br><br>
+</td>
+<td align="center" width="12.5%">
+<br>
+<img src="https://img.shields.io/badge/Elysia-7c3aed?style=for-the-badge&logoColor=white" alt="Elysia">
+<br><b>Backend</b><br>
+<sub>Elysia.js 1.4</sub>
+<br><br>
+</td>
+<td align="center" width="12.5%">
+<br>
+<img src="https://img.shields.io/badge/React-20232A?style=for-the-badge&logo=react&logoColor=61DAFB" alt="React">
+<br><b>Frontend</b><br>
+<sub>React 19</sub>
+<br><br>
+</td>
+<td align="center" width="12.5%">
+<br>
+<img src="https://img.shields.io/badge/Vite-646CFF?style=for-the-badge&logo=vite&logoColor=white" alt="Vite">
+<br><b>Build</b><br>
+<sub>Vite 7</sub>
+<br><br>
+</td>
+<td align="center" width="12.5%">
+<br>
+<img src="https://img.shields.io/badge/Tailwind-06B6D4?style=for-the-badge&logo=tailwindcss&logoColor=white" alt="Tailwind">
+<br><b>Styling</b><br>
+<sub>Tailwind CSS 4</sub>
+<br><br>
+</td>
+<td align="center" width="12.5%">
+<br>
+<img src="https://img.shields.io/badge/TypeScript-3178C6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript">
+<br><b>Language</b><br>
+<sub>TypeScript 5.8</sub>
+<br><br>
+</td>
+<td align="center" width="12.5%">
+<br>
+<img src="https://img.shields.io/badge/Eden-7c3aed?style=for-the-badge&logoColor=white" alt="Eden Treaty">
+<br><b>API Client</b><br>
+<sub>Eden Treaty 1.3</sub>
+<br><br>
+</td>
+<td align="center" width="12.5%">
+<br>
+<img src="https://img.shields.io/badge/Vitest-6E9F18?style=for-the-badge&logo=vitest&logoColor=white" alt="Vitest">
+<br><b>Testing</b><br>
+<sub>Vitest 3</sub>
+<br><br>
+</td>
+</tr>
+</table>
 
 ---
 
@@ -143,33 +164,29 @@ bun run dev
 graph TB
     subgraph "🎨 Frontend Layer"
         React[React 19 + Vite]
-        Components[Components]
-        Hooks[Custom Hooks]
+        LiveClient[Live Components Client]
+        Eden[Eden Treaty]
     end
 
-    subgraph "🔌 Communication Layer"
-        Eden[Eden Treaty]
-        WS[WebSockets]
+    subgraph "🔌 Communication"
+        HTTP[HTTP / REST]
+        WS[WebSocket]
     end
 
     subgraph "⚙️ Backend Layer"
         Elysia[Elysia.js]
         Routes[API Routes]
-        Controllers[Controllers]
-    end
-
-    subgraph "🗄️ Data Layer"
-        DB[(Your Database)]
-        Cache[(Cache)]
+        LiveServer[Live Components Server]
+        Rooms[Room System]
     end
 
     React --> Eden
-    Eden --> Elysia
+    Eden --> HTTP
+    HTTP --> Elysia
     Elysia --> Routes
-    Routes --> Controllers
-    Controllers --> DB
-    React --> WS
-    WS --> Elysia
+    LiveClient --> WS
+    WS --> LiveServer
+    LiveServer --> Rooms
 ```
 
 </div>
@@ -183,119 +200,277 @@ graph TB
 FluxStack/
 ├── 🔒 core/                    # Framework Core (Read-Only)
 │   ├── framework/             # FluxStack orchestrator
-│   ├── plugins/               # Built-in plugins (Swagger, Vite, etc.)
-│   ├── build/                 # Build system & Docker scaffolding
+│   ├── server/                # Elysia plugins, middleware, live engine
+│   ├── client/                # Vite integration, Live hooks, providers
 │   ├── cli/                   # CLI commands & generators
-│   ├── config/                # Config schema helpers
-│   └── utils/                 # Logging, environment, etc.
+│   ├── plugins/               # Built-in plugins (Swagger, Vite, etc.)
+│   ├── types/                 # Framework type definitions
+│   └── utils/                 # Logger, config schema, errors
 │
 ├── 👨‍💻 app/                     # Your Application Code
 │   ├── server/                # Backend (Elysia + Bun)
 │   │   ├── controllers/       # Business logic
 │   │   ├── routes/            # API endpoints + schemas
-│   │   ├── types/             # Shared types & App export
-│   │   └── live/              # WebSocket components
+│   │   ├── live/              # Live Components (server-side)
+│   │   └── app.ts             # Elysia app instance (Eden Treaty export)
 │   │
 │   ├── client/                # Frontend (React + Vite)
-│   │   ├── src/
-│   │   │   ├── components/    # React components
-│   │   │   ├── hooks/         # Custom React hooks
-│   │   │   ├── lib/           # Eden Treaty client
-│   │   │   └── App.tsx        # Main app
-│   │   └── public/            # Static assets
+│   │   └── src/
+│   │       ├── components/    # React components
+│   │       ├── pages/         # Route pages
+│   │       ├── live/          # Live Components (client-side)
+│   │       └── lib/           # Eden Treaty client
 │   │
-│   └── shared/                # Shared types & utilities
+│   └── shared/                # Shared type definitions
 │
-├── ⚙️ config/                  # Application Configuration
-│   ├── app.config.ts          # App settings
-│   ├── server.config.ts       # Server & CORS
-│   ├── logger.config.ts       # Logging
-│   └── database.config.ts     # Database
-│
-├── 🔌 plugins/                 # External Plugins
-│   └── crypto-auth/           # Example: Crypto authentication
+├── ⚙️ config/                  # Declarative Configuration
+│   ├── system/                # Config files (app, server, db, logger, etc.)
+│   ├── fluxstack.config.ts    # FluxStack config
+│   └── index.ts               # Centralized exports
 │
+├── 🔌 plugins/                 # Project Plugins (auto-discovered)
+├── 🧪 tests/                   # Test suite (unit + integration)
 ├── 🤖 LLMD/                    # LLM-Optimized Documentation
-│   ├── INDEX.md               # Navigation hub
-│   ├── core/                  # Framework internals
-│   ├── config/                # Configuration system
-│   ├── resources/             # Creating routes, controllers
-│   ├── patterns/              # Best practices
-│   └── reference/             # CLI, hooks, troubleshooting
-│
-└── 📦 Package Files
-    ├── package.json           # Dependencies
-    ├── tsconfig.json          # TypeScript config
-    └── README.md              # This file
+└── 🐳 Dockerfile               # Multi-stage production build
 ```
 
 </details>
 
 ---
 
-## 📜 Available Scripts
+## ⚡ Live Components
+
+Real-time WebSocket components with **automatic state synchronization** between server and client. Define state and logic on the server, interact with it from React — updates sync instantly via WebSocket.
 
 <table>
 <tr>
 <td width="50%">
 
-### 🔨 Development
+### 🖥️ Server Side
 
-```bash
-# Full-stack development
-bun run dev
-
-# Frontend only (port 5173)
-bun run dev:frontend
-
-# Backend only (port 3001)
-bun run dev:backend
+```typescript
+// app/server/live/LiveCounter.ts
+import { LiveComponent } from '@/core/server'
+
+export class LiveCounter extends LiveComponent<{
+  count: number
+}> {
+  static defaultState = { count: 0 }
+
+  async increment() {
+    this.state.count++ // auto-syncs via Proxy
+    return { success: true }
+  }
+
+  async decrement() {
+    this.state.count--
+    return { success: true }
+  }
+
+  async reset() {
+    this.state.count = 0
+    return { success: true }
+  }
+}
 ```
 
 </td>
 <td width="50%">
 
-### 🚀 Production
+### ⚛️ Client Side
 
-```bash
-# Build for production
-bun run build
+```tsx
+// app/client/src/live/CounterDemo.tsx
+import { Live } from '@/core/client'
+import { LiveCounter } from '@server/live/LiveCounter'
 
-# Start production server
-bun run start
+export function CounterDemo() {
+  const counter = Live.use(LiveCounter, {
+    room: 'global-counter',
+    initialState: LiveCounter.defaultState
+  })
+
+  return (
+    <div>
+      <span>{counter.$state.count}</span>
+
+      <button
+        onClick={() => counter.increment()}
+        disabled={counter.$loading}
+      >
+        +
+      </button>
+
+      <button onClick={() => counter.decrement()}>
+        -
+      </button>
+
+      <span>
+        {counter.$connected ? '🟢' : '🔴'}
+      </span>
+    </div>
+  )
+}
 ```
 
 </td>
 </tr>
+</table>
+
+### 🔑 Client Proxy API
+
+The `Live.use()` hook returns a Proxy object with full access to server state and actions:
+
+```typescript
+const component = Live.use(MyComponent)
+
+// State access
+component.$state           // Full state object
+component.myProp           // Direct property access via Proxy
+component.$connected       // Boolean - WebSocket connected?
+component.$loading         // Boolean - action in progress?
+component.$error           // Error message or null
+
+// Actions
+await component.myAction() // Call server method (type-safe)
+component.$set('key', val) // Set a single property
+
+// Form field binding
+<input {...component.$field('email', { syncOn: 'change', debounce: 500 })} />
+<input {...component.$field('name', { syncOn: 'blur' })} />
+await component.$sync()    // Manual sync for deferred fields
+
+// Room events
+component.$room.emit('event', data)
+component.$room.on('message', handler)
+```
+
+### 🏠 Room System
+
+Multi-room real-time communication for Live Components — users in the same room share events.
+
+<table>
 <tr>
 <td width="50%">
 
-### 🧪 Testing & Quality
+**Server: join rooms and emit events**
 
-```bash
-# Run tests
-bun run test
+```typescript
+// app/server/live/ChatRoom.ts
+export class ChatRoom extends LiveComponent<State> {
+
+  async joinRoom(payload: { roomId: string }) {
+    this.$room(payload.roomId).join()
+
+    this.$room(payload.roomId).on('message:new', (msg) => {
+      this.setState({
+        messages: [...this.state.messages, msg]
+      })
+    })
 
-# Test with UI
-bun run test:ui
+    return { success: true }
+  }
 
-# Type checking
-bunx tsc --noEmit
+  async sendMessage(payload: { text: string }) {
+    const message = { id: Date.now(), text: payload.text }
+    this.setState({
+      messages: [...this.state.messages, message]
+    })
+    this.$room('chat').emit('message:new', message)
+    return { success: true }
+  }
+}
 ```
 
 </td>
 <td width="50%">
 
-### 🛠️ Utilities
+**HTTP API for external integrations**
 
 ```bash
-# Sync version across files
-bun run sync-version
+# Send a message to a room via API
+curl -X POST \
+  http://localhost:3000/api/rooms/general/messages \
+  -H "Content-Type: application/json" \
+  -d '{"user": "Bot", "text": "Hello from API!"}'
+
+# Emit a custom event to a room
+curl -X POST \
+  http://localhost:3000/api/rooms/tech/emit \
+  -H "Content-Type: application/json" \
+  -d '{
+    "event": "notification",
+    "data": {"type": "alert", "msg": "Deploy done!"}
+  }'
+```
+
+Rooms are accessible both from Live Components (WebSocket) and via REST API for webhooks, bots, and external services.
 
-# Run CLI commands
-bun run cli
+</td>
+</tr>
+</table>
+
+### 🔐 Authentication
+
+Declarative auth for Live Components with role-based access control.
+
+<table>
+<tr>
+<td width="50%">
+
+**Server: protect components and actions**
+
+```typescript
+// app/server/live/AdminPanel.ts
+export class AdminPanel extends LiveComponent<State> {
+  static componentName = 'AdminPanel'
+  static defaultState = { users: [] }
+
+  // Component requires admin role
+  static auth = {
+    required: true,
+    roles: ['admin']
+  }
+
+  // Per-action permissions
+  static actionAuth = {
+    deleteUser: { permissions: ['users.delete'] }
+  }
+
+  async deleteUser(payload: { userId: string }) {
+    // Access user info via $auth
+    console.log(`${this.$auth.user?.id} deleting user`)
+    return { success: true }
+  }
+}
 ```
 
+</td>
+<td width="50%">
+
+**Client: authenticate dynamically**
+
+```tsx
+import { useLiveComponents } from '@/core/client'
+
+function LoginButton() {
+  const { authenticated, authenticate } = useLiveComponents()
+
+  const handleLogin = async () => {
+    await authenticate({ token: 'my-jwt-token' })
+    // Components auto re-mount with new auth!
+  }
+
+  return (
+    <button onClick={handleLogin}>
+      {authenticated ? 'Logged in' : 'Login'}
+    </button>
+  )
+}
+```
+
+Components that fail with `AUTH_DENIED` automatically retry when authentication succeeds.
+
 </td>
 </tr>
 </table>
@@ -304,18 +479,19 @@ bun run cli
 
 ## 🔒 Type-Safe API Development
 
-**FluxStack uses Eden Treaty to eliminate manual DTOs and provide automatic type inference from backend to frontend.**
+**Eden Treaty infers types from Elysia route definitions automatically. No manual DTOs.**
+
+<table>
+<tr>
+<td width="50%">
 
 ### 📝 Define Backend Route
 
 ```typescript
-// app/server/routes/users.ts
+// app/server/routes/users.routes.ts
 import { Elysia, t } from 'elysia'
 
 export const userRoutes = new Elysia({ prefix: '/users' })
-  .get('/', () => ({
-    users: listUsers()
-  }))
   .post('/', ({ body }) => createUser(body), {
     body: t.Object({
       name: t.String(),
@@ -326,179 +502,200 @@ export const userRoutes = new Elysia({ prefix: '/users' })
       user: t.Optional(t.Object({
         id: t.Number(),
         name: t.String(),
-        email: t.String(),
-        createdAt: t.Date()
-      })),
-      message: t.Optional(t.String())
+        email: t.String()
+      }))
     })
   })
 ```
 
+</td>
+<td width="50%">
+
 ### ✨ Use in Frontend (Fully Typed!)
 
 ```typescript
-// app/client/src/App.tsx
-import { api } from '@/app/client/src/lib/eden-api'
+// app/client/src/lib/eden-api.ts
+import { api } from './eden-api'
 
-// ✅ TypeScript knows all types automatically!
-const { data: response, error } = await api.users.post({
-  name: 'Ada Lovelace',        // ✅ Type: string
-  email: 'ada@example.com'     // ✅ Type: string (email format)
+// TypeScript knows all types automatically!
+const { data, error } = await api.users.post({
+  name: 'Ada Lovelace',       // ✅ string
+  email: 'ada@example.com'    // ✅ string (email)
 })
 
-// ✅ response is typed as the exact response schema
-if (!error && response?.user) {
-  console.log(response.user.name)     // ✅ Type: string
-  console.log(response.user.id)       // ✅ Type: number
-  console.log(response.user.createdAt) // ✅ Type: Date
+if (data?.user) {
+  console.log(data.user.name)  // ✅ string
+  console.log(data.user.id)    // ✅ number
 }
 ```
 
-### 🎯 Benefits
+</td>
+</tr>
+</table>
 
-- ✅ **Zero Manual Types** - Types flow automatically from backend to frontend
-- ✅ **Autocomplete** - Full IntelliSense in your IDE
-- ✅ **Type Safety** - Catch errors at compile time, not runtime
-- ✅ **Refactor Friendly** - Change backend schema, frontend updates automatically
+**Benefits:**
+- ✅ **Zero Manual Types** — Types flow automatically from backend to frontend
+- ✅ **Full Autocomplete** — IntelliSense in your IDE
+- ✅ **Refactor Friendly** — Change backend schema, frontend updates automatically
 
 ---
 
-## 🎨 Customization Examples
+## ⚙️ Declarative Configuration
 
-<details>
-<summary><b>➕ Add a New API Route</b></summary>
+Laravel-inspired config system with schema validation and full type inference.
 
 ```typescript
-// app/server/routes/posts.ts
-import { Elysia, t } from 'elysia'
+// config/system/app.config.ts
+import { defineConfig, config } from '@/core/utils/config-schema'
 
-export const postRoutes = new Elysia({ prefix: '/posts' })
-  .get('/', () => ({
-    posts: getAllPosts()
-  }))
-  .post('/', ({ body }) => ({
-    post: createPost(body)
-  }), {
-    body: t.Object({
-      title: t.String({ minLength: 3 }),
-      content: t.String({ minLength: 10 })
-    })
-  })
+const appConfigSchema = {
+  name: config.string('APP_NAME', 'FluxStack', true),
+  port: config.number('PORT', 3000, true),
+  env: config.enum('NODE_ENV', ['development', 'production', 'test'] as const, 'development', true),
+  debug: config.boolean('DEBUG', false),
+} as const
+
+export const appConfig = defineConfig(appConfigSchema)
+// appConfig.port → number, appConfig.env → "development" | "production" | "test"
 ```
 
-**Then register it:**
-```typescript
-// app/server/index.ts
-import { postRoutes } from './routes/posts'
+All environment variables are validated at boot time. See [`.env.example`](.env.example) for available options.
 
-app.use(postRoutes)
-```
+---
 
-</details>
+## 🔌 Plugin System
 
-<details>
-<summary><b>🔌 Create a Custom Plugin</b></summary>
+Three-layer plugin architecture with security-first design:
 
-```typescript
-// app/server/plugins/audit.ts
-import { Elysia } from 'elysia'
-
-export const auditPlugin = new Elysia({ name: 'audit' })
-  .derive(({ request }) => ({
-    timestamp: Date.now(),
-    ip: request.headers.get('x-forwarded-for')
-  }))
-  .onRequest(({ request, timestamp }) => {
-    console.log(`[${new Date(timestamp).toISOString()}] ${request.method} ${request.url}`)
-  })
-  .onResponse(({ request, timestamp }) => {
-    const duration = Date.now() - timestamp
-    console.log(`[AUDIT] ${request.method} ${request.url} - ${duration}ms`)
-  })
+| Layer | Location | Auto-discovered | Trusted |
+|-------|----------|-----------------|---------|
+| 🔒 **Built-in** | `core/plugins/` | No (manual `.use()`) | ✅ Yes |
+| 📁 **Project** | `plugins/` | ✅ Yes | ✅ Yes |
+| 📦 **NPM** | `node_modules/` | ❌ No (opt-in) | 🔒 Whitelist required |
+
+NPM plugins are **blocked by default**. To add one safely:
+
+```bash
+bun run cli plugin:add fluxstack-plugin-auth
+# Audits the package, installs it, and adds it to the whitelist
 ```
 
-**Use it:**
-```typescript
-import { auditPlugin } from './plugins/audit'
+---
+
+## 📜 Available Scripts
+
+<table>
+<tr>
+<td width="50%">
 
-app.use(auditPlugin)
+### 🔨 Development
+
+```bash
+bun run dev             # Full-stack with hot reload
+bun run dev:frontend    # Frontend only (port 5173)
+bun run dev:backend     # Backend only (port 3001)
 ```
 
-</details>
+</td>
+<td width="50%">
 
-<details>
-<summary><b>⚙️ Add Environment Configuration</b></summary>
+### 🚀 Production
 
-```typescript
-// config/features.config.ts
-import { defineConfig, config } from '@/core/utils/config-schema'
+```bash
+bun run build           # Production build
+bun run start           # Start production server
+```
 
-const featuresConfigSchema = {
-  enableAnalytics: config.boolean('ENABLE_ANALYTICS', false),
-  maxUploadSize: config.number('MAX_UPLOAD_SIZE', 5242880), // 5MB
-  allowedOrigins: config.array('ALLOWED_ORIGINS', ['http://localhost:3000'])
-} as const
+</td>
+</tr>
+<tr>
+<td width="50%">
+
+### 🧪 Testing & Quality
 
-export const featuresConfig = defineConfig(featuresConfigSchema)
+```bash
+bun run test            # Run tests (Vitest)
+bun run test:ui         # Vitest with browser UI
+bun run test:coverage   # Coverage report
+bun run typecheck:api   # Strict TypeScript check
 ```
 
-**Use it with full type safety:**
-```typescript
-import { featuresConfig } from '@/config/features.config'
+</td>
+<td width="50%">
 
-if (featuresConfig.enableAnalytics) {
-  // Type: boolean (not string!)
-  trackEvent('user_action')
-}
+### 🛠️ CLI & Utilities
+
+```bash
+bun run cli             # CLI interface
+bun run make:component  # Generate a Live Component
+bun run sync-version    # Sync version across files
 ```
 
-</details>
+</td>
+</tr>
+</table>
 
 ---
 
-## 📚 Documentation & Support
+## 🔀 Frontend Routes
 
-<table>
-<tr>
-<td width="33%">
+Default routes included in the demo app (React Router v7):
 
-### 📖 **Documentation**
-- [LLM Documentation](./LLMD/) ⭐ **NEW**
-- [LLMD Index](./LLMD/INDEX.md) - Navigation hub
-- [Development Patterns](./LLMD/patterns/project-structure.md)
-- [CLI Reference](./LLMD/reference/cli-commands.md)
-- [CLAUDE.md](./CLAUDE.md)
-- [AI Context (deprecated)](./ai-context/)
+| Route | Page |
+|-------|------|
+| `/` | Home |
+| `/counter` | Live Counter |
+| `/form` | Live Form |
+| `/upload` | Live Upload |
+| `/auth` | Auth Demo |
+| `/api-test` | Eden Treaty Demo |
 
-</td>
-<td width="33%">
+---
 
-### 💬 **Community**
-- [GitHub Issues](https://github.com/MarcosBrendonDePaula/FluxStack/issues)
-- [Discussions](https://github.com/MarcosBrendonDePaula/FluxStack/discussions)
-- [Repository](https://github.com/MarcosBrendonDePaula/FluxStack)
+## 🔧 Environment Variables
 
-</td>
-<td width="33%">
+Copy `.env.example` to `.env` and adjust as needed:
 
-### 🔄 **Upgrading**
 ```bash
-bunx create-fluxstack@latest
+cp .env.example .env
+```
+
+<details>
+<summary><b>Key variables</b></summary>
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PORT` | `3000` | Backend server port |
+| `HOST` | `localhost` | Server host |
+| `FRONTEND_PORT` | `5173` | Vite dev server port |
+| `NODE_ENV` | `development` | Environment |
+| `LOG_LEVEL` | `info` | Logging level |
+| `CORS_ORIGINS` | `localhost:3000,localhost:5173` | Allowed CORS origins |
+| `SWAGGER_ENABLED` | `true` | Enable Swagger UI |
+| `SWAGGER_PATH` | `/swagger` | Swagger UI path |
+
+See [`.env.example`](.env.example) for the full list.
+
+</details>
+
+---
 
-# Check version
-npm list -g create-fluxstack
+## 🐳 Docker
+
+```bash
+# Build
+docker build -t fluxstack-app .
+
+# Run
+docker run -p 3000:3000 fluxstack-app
 ```
 
-</td>
-</tr>
-</table>
+The Dockerfile uses a multi-stage build with `oven/bun:1.2-alpine` and runs as a non-root user.
 
 ---
 
 ## 🤔 Why FluxStack?
 
-### 🆚 **Comparison with Other Stacks**
-
 <table>
 <tr>
 <th>Feature</th>
@@ -513,22 +710,22 @@ npm list -g create-fluxstack
 <td>❌ Node.js</td>
 </tr>
 <tr>
-<td><b>Backend Framework</b></td>
+<td><b>Backend</b></td>
 <td>✅ Elysia (ultra-fast)</td>
-<td>⚠️ Next.js API Routes</td>
+<td>⚠️ API Routes</td>
 <td>✅ tRPC</td>
 </tr>
 <tr>
 <td><b>Type Safety</b></td>
-<td>✅ Eden Treaty (auto-inferred)</td>
+<td>✅ Eden Treaty (auto)</td>
 <td>⚠️ Manual types</td>
 <td>✅ tRPC</td>
 </tr>
 <tr>
-<td><b>Configuration</b></td>
-<td>✅ Declarative with validation</td>
-<td>⚠️ Manual setup</td>
-<td>⚠️ Manual setup</td>
+<td><b>Real-Time</b></td>
+<td>✅ Live Components built-in</td>
+<td>⚠️ Third-party</td>
+<td>⚠️ Third-party</td>
 </tr>
 <tr>
 <td><b>API Docs</b></td>
@@ -537,53 +734,16 @@ npm list -g create-fluxstack
 <td>❌ Manual</td>
 </tr>
 <tr>
-<td><b>WebSockets</b></td>
-<td>✅ Built-in</td>
-<td>⚠️ Third-party</td>
-<td>⚠️ Third-party</td>
+<td><b>Config System</b></td>
+<td>✅ Declarative + validation</td>
+<td>⚠️ Manual</td>
+<td>⚠️ Manual</td>
 </tr>
 <tr>
 <td><b>Docker</b></td>
 <td>✅ Multi-stage ready</td>
-<td>⚠️ Manual setup</td>
-<td>⚠️ Manual setup</td>
-</tr>
-</table>
-
-### 💡 **Key Advantages**
-
-<table>
-<tr>
-<td width="50%">
-
-#### 🚀 **Performance**
-- **3x faster** startup with Bun
-- **Ultra-fast** API routing with Elysia
-- **Instant** HMR with Vite 7
-- **Optimized** production builds
-
-#### 🔒 **Type Safety**
-- **Automatic** type inference
-- **Zero manual** DTO definitions
-- **End-to-end** type checking
-- **Refactor-friendly** architecture
-
-</td>
-<td width="50%">
-
-#### 🛠️ **Developer Experience**
-- **Zero configuration** needed
-- **One command** to start
-- **Auto-generated** documentation
-- **AI-optimized** documentation
-
-#### 🎯 **Production Ready**
-- **Docker** templates included
-- **Declarative** configuration
-- **Unified** error handling
-- **Built-in** monitoring support
-
-</td>
+<td>⚠️ Manual</td>
+<td>⚠️ Manual</td>
 </tr>
 </table>
 
@@ -595,15 +755,15 @@ npm list -g create-fluxstack
 <tr>
 <td width="50%">
 
-### 📦 **System Requirements**
-- **Bun** ≥ 1.2.0 (required)
+### 📦 System Requirements
+- **Bun** >= 1.2.0 (required runtime)
 - **Git** (for version control)
-- **Modern OS**: Linux, macOS, or Windows
+- Linux, macOS, or Windows
 
 </td>
 <td width="50%">
 
-### 📥 **Install Bun**
+### 📥 Install Bun
 
 **macOS / Linux:**
 ```bash
@@ -619,46 +779,63 @@ powershell -c "irm bun.sh/install.ps1 | iex"
 </tr>
 </table>
 
-> ⚠️ **Important**: FluxStack is designed exclusively for the Bun runtime. Node.js is not supported.
+> ⚠️ **Important**: FluxStack requires Bun. Node.js is not supported as a runtime.
 
 ---
 
-## 🚀 Ready to Build?
+## 📚 Documentation & Support
 
-<div align="center">
+<table>
+<tr>
+<td width="33%">
 
-### Start your next project in seconds
+### 📖 Documentation
+- [LLMD Index](./LLMD/INDEX.md) — Navigation hub
+- [Framework Lifecycle](./LLMD/core/framework-lifecycle.md)
+- [Live Components](./LLMD/resources/live-components.md)
+- [Live Auth](./LLMD/resources/live-auth.md)
+- [Live Rooms](./LLMD/resources/live-rooms.md)
+- [Routes & Eden Treaty](./LLMD/resources/routes-eden.md)
+- [CLI Reference](./LLMD/reference/cli-commands.md)
+- [Troubleshooting](./LLMD/reference/troubleshooting.md)
 
-```bash
-bunx create-fluxstack my-awesome-app
-cd my-awesome-app
-bun run dev
-```
+</td>
+<td width="33%">
 
-### Welcome to the future of full-stack development 🎉
+### 💬 Community
+- [GitHub Issues](https://github.com/MarcosBrendonDePaula/FluxStack/issues)
+- [Discussions](https://github.com/MarcosBrendonDePaula/FluxStack/discussions)
+- [Repository](https://github.com/MarcosBrendonDePaula/FluxStack)
 
-[![GitHub Repo](https://img.shields.io/badge/GitHub-FluxStack-blue?style=for-the-badge&logo=github)](https://github.com/MarcosBrendonDePaula/FluxStack)
-[![npm](https://img.shields.io/badge/npm-create--fluxstack-red?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/create-fluxstack)
+</td>
+<td width="33%">
 
-</div>
+### 🔄 Upgrading
+```bash
+bunx create-fluxstack@latest
+```
+
+</td>
+</tr>
+</table>
 
 ---
 
-## 📄 License
+## 🤝 Contributing
 
-This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/my-feature`)
+3. Commit your changes (`git commit -m 'Add my feature'`)
+4. Push to the branch (`git push origin feature/my-feature`)
+5. Open a Pull Request
+
+Please open an [issue](https://github.com/MarcosBrendonDePaula/FluxStack/issues) first to discuss larger changes.
 
 ---
 
-## 🙏 Acknowledgments
+## 📄 License
 
-Built with amazing open-source technologies:
-- [Bun](https://bun.sh) - Fast all-in-one JavaScript runtime
-- [Elysia.js](https://elysiajs.com) - Ergonomic framework for humans
-- [React](https://react.dev) - Library for web and native interfaces
-- [Vite](https://vite.dev) - Next generation frontend tooling
-- [Tailwind CSS](https://tailwindcss.com) - Utility-first CSS framework
-- [TypeScript](https://www.typescriptlang.org) - JavaScript with syntax for types
+[MIT](LICENSE) - Marcos Brendon De Paula
 
 ---
 
@@ -668,6 +845,9 @@ Built with amazing open-source technologies:
 
 *Star ⭐ this repo if you find it helpful!*
 
+[![GitHub Repo](https://img.shields.io/badge/GitHub-FluxStack-blue?style=for-the-badge&logo=github)](https://github.com/MarcosBrendonDePaula/FluxStack)
+[![npm](https://img.shields.io/badge/npm-create--fluxstack-red?style=for-the-badge&logo=npm)](https://www.npmjs.com/package/create-fluxstack)
+
 [Report Bug](https://github.com/MarcosBrendonDePaula/FluxStack/issues) · [Request Feature](https://github.com/MarcosBrendonDePaula/FluxStack/issues) · [Contribute](https://github.com/MarcosBrendonDePaula/FluxStack/pulls)
 
 </div>