@bloomneo/appkit 1.5.1 → 1.5.2

package/README.md

@@ -5,898 +5,246 @@
 [![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
 [![AI Ready](https://img.shields.io/badge/AI-Optimized-purple.svg)](https://github.com/bloomneo/appkit)
 
-> Previously published as `@voilajsx/appkit`. Same code, new home, new namespace. See the [migration note](#scope-change) below.
+> Minimal, framework-agnostic Node.js toolkit designed for AI agentic backend development.
+> Previously published as `@voilajsx/appkit`. Same code, new home, new namespace.
+> See [migration](#migration) below.
 
-> **Minimal and framework agnostic Node.js toolkit designed for AI agentic
-> backend development**
+**12 integrated modules. One pattern. Zero config to start, enterprise scaling on demand.**
 
-**Zero configuration. Enterprise features by default. Optimized for both human
-developers and AI code generation.**
-
-## 🚀 What Bloomneo AppKit Really Is
-
-Bloomneo AppKit is a **complete Node.js development toolkit** that eliminates
-the complexity of building production-ready applications. Instead of juggling
-dozens of libraries and configuration files, you get 12 integrated modules that
-work together seamlessly.
-
-### **How Developers Can Leverage AppKit**
-
-**🎯 For Rapid Development**
-
-- **One function per module**: `authClass.get()`, `databaseClass.get()`,
-  `securityClass.get()`
-- **Instant setup**: No configuration files, just environment variables
-- **Production patterns**: Enterprise-grade security and scalability built-in
-
-**🏗️ For Maintainable Architecture**
-
-- **Consistent APIs**: Same `{moduleClass}.get()` pattern across all modules
-- **Progressive complexity**: Start simple, scale to enterprise automatically
-- **Type-safe**: Full TypeScript support with intelligent IntelliSense
-
-**⚡ For Performance**
-
-- **Smart defaults**: Memory caching, connection pooling, resource management
-- **Auto-scaling**: Modules automatically upgrade (Memory → Redis → Database)
-- **Optimized**: Battle-tested patterns for high-throughput applications
-
-## 🤖 Enhanced for AI-Driven Development
-
-While perfectly designed for human developers, AppKit excels in AI-assisted
-development:
-
-- **🎯 Predictable Code Generation**: AI agents generate consistent, working
-  applications
-- **📝 LLM-Optimized Documentation**: Every function includes clear usage
-  patterns
-- **🔒 Built-in Best Practices**: Security, scalability, and maintainability by
-  default
-- **⚙️ Non-Ambiguous APIs**: Clear function signatures prevent common mistakes
-
-### **Why This Matters for Developers**
-
-| Traditional Approach                      | Bloomneo AppKit Approach                |
-| ----------------------------------------- | --------------------------------------- |
-| Research → Configure → Integrate → Secure | **Import → Use → Deploy**               |
-| Multiple libraries, version conflicts     | **Integrated modules, tested together** |
-| Manual scaling decisions                  | **Environment-driven auto-scaling**     |
-| Security implemented later                | **Security enabled by default**         |
-| Inconsistent error handling               | **Unified error patterns**              |
-
-## 🏢 Enterprise Benefits
-
-### **Progressive Complexity**
-
-```typescript
-// Day 1: Simple development
-const auth = authClass.get();
-const token = auth.signToken({ userId: 123, role: 'user', level: 'basic' });
-
-// Month 6: Multi-tenant (just add environment variable)
-// VOILA_DB_TENANT=auto
-const database = await databaseClass.get(); // Now auto-filtered by tenant
-
-// Year 1: Multi-organization enterprise (same code)
-// ORG_ACME=postgresql://acme.aws.com/prod
-const acmeDatabase = await databaseClass.org('acme').get(); // Enterprise scaling
-```
-
-## 🚀 Quick Start
-
-**Two Ways to Use AppKit:**
-
-**📦 As a Library** - Install AppKit modules into your existing Node.js/Express projects (NestJS, Fastify, Koa, etc.):
-```bash
-npm install @bloomneo/appkit
-```
-Import modules directly: `import { authClass, databaseClass } from '@bloomneo/appkit'`
-
-**🚀 Complete Microservice Scaffolding** - Use AppKit CLI to generate enterprise-ready backend applications:
-
-```bash
-# Step 1: Install AppKit CLI globally
-npm install -g @bloomneo/appkit
-
-# Check if you have the latest version
-npm list -g @bloomneo/appkit
-
-# Step 2: Create your app
-appkit generate app myproject
-cd myproject && npm run dev:api
-```
-
-**Done.** Your API is running with authentication, database, and enterprise features ready at http://localhost:3000/api
-
-### **Add Features Instantly**
-
-```bash
-# Add custom feature
-appkit generate feature product
-
-# Add complete authentication system
-appkit generate feature user
-
-# Add database-enabled feature
-appkit generate feature order --db
-```
-
-### **Library Integration Example**
-
-```bash
-# For library usage in existing projects
-npm install @bloomneo/appkit
-```
-
-```typescript
-import { authClass } from '@bloomneo/appkit/auth';
-import { databaseClass } from '@bloomneo/appkit/database';
-import { errorClass } from '@bloomneo/appkit/error';
-import { loggerClass } from '@bloomneo/appkit/logger';
+```ts
+import { authClass, databaseClass, errorClass, loggerClass } from '@bloomneo/appkit';
 
 const auth = authClass.get();
 const database = await databaseClass.get();
 const error = errorClass.get();
 const logger = loggerClass.get('api');
 
-// Protected API endpoint
 app.post(
   '/api/users',
-  auth.requireRole('admin.tenant'),
+  auth.requireLoginToken(),                    // 1. authenticate the user
+  auth.requireUserRoles(['admin.tenant']),     // 2. check the role (always chained)
   error.asyncRoute(async (req, res) => {
-    const user = auth.user(req);
-
-    if (!req.body.email) {
-      throw error.badRequest('Email required');
-    }
-
-    const newUser = await database.user.create({ data: req.body });
-    logger.info('User created', { userId: newUser.id });
-
-    res.json({ user: newUser });
+    if (!req.body?.email) throw error.badRequest('Email required');
+    const user = await database.user.create({ data: req.body });
+    logger.info('User created', { userId: user.id });
+    res.json({ user });
   })
 );
 
-// Error handling middleware (must be last)
-app.use(error.handleErrors());
+app.use(error.handleErrors());  // last middleware
 ```
 
-**Result**: Production-ready API with authentication, database, error handling,
-and logging. **Zero configuration needed.**
-
-## 🛠️ AppKit CLI
-
-### **Project Generation**
-
-```bash
-# Create complete backend application
-appkit generate app [name]
-
-# What you get:
-# ✅ TypeScript setup with proper configuration
-# ✅ Express server with auto-discovery routing
-# ✅ Environment variables with secure random keys
-# ✅ Database integration ready
-# ✅ Complete documentation included
-# ✅ Production-ready npm scripts
-```
-
-### **Feature Generation**
-
-```bash
-# Basic feature (route + service + types)
-appkit generate feature product
+**Production-ready API with auth, database, error handling, logging. Zero config files.**
 
-# Database-enabled feature (+ model + HTTP tests)
-appkit generate feature order --db
-
-# Complete authentication system (9-role hierarchy)
-appkit generate feature user
-```
-
-### **Generated Project Structure**
+---
 
-```
-myproject/
-├── docs/                         # Complete documentation
-│   ├── APPKIT_CLI.md            # CLI reference
-│   ├── APPKIT_LLM_GUIDE.md      # AI integration guide
-│   └── APPKIT_COMMENTS_GUIDELINES.md # Code standards
-├── src/api/
-│   ├── server.ts                # Main server
-│   ├── lib/api-router.ts        # Auto-discovery routing
-│   └── features/                # Feature-based architecture
-│       ├── welcome/             # Default endpoints
-│       └── [your-features]/     # Generated features
-├── .env                         # Secure environment variables
-├── package.json                 # With backend scripts
-└── README.md                    # Project-specific guide
-```
+## 🤖 For AI coding agents — read these first
 
-## 🎭 Complete Module Ecosystem
+Three files at the package root tell agents everything they need to know:
 
-| #   | Module                                  | Category                | Purpose                                               | Details                                                                                                                                   |
-| --- | --------------------------------------- | ----------------------- | ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
-| 1   | **[Auth](/src/auth/README.md)**         | 🔧 Infrastructure       | JWT tokens, dual token system, role-level permissions | `authClass.get()` - Login tokens (users) + API tokens (services), role.level hierarchy (user.basic → admin.system), automatic inheritance |
-| 2   | **[Database](/src/database/README.md)** | 🔧 Infrastructure       | Multi-tenant, progressive scaling                     | `databaseClass.get()` - Auto-tenant filtering, org management (.org()), mandatory future-proofing with tenant_id                          |
-| 3   | **[Security](/src/security/README.md)** | 🔧 Infrastructure       | CSRF, rate limiting, encryption                       | `securityClass.get()` - Enterprise-grade by default, AES-256-GCM encryption, input sanitization                                           |
-| 4   | **[Error](/src/error/README.md)**       | 🔧 Infrastructure       | HTTP status codes, semantic errors                    | `errorClass.get()` - Framework-agnostic middleware, semantic error types (badRequest, unauthorized)                                       |
-| 5   | **[Cache](/src/cache/README.md)**       | 📊 Data & Communication | Memory → Redis auto-scaling                           | `cacheClass.get('namespace')` - Namespace isolation, TTL management, getOrSet pattern                                                     |
-| 6   | **[Storage](/src/storage/README.md)**   | 📊 Data & Communication | Local → S3/R2 auto-scaling                            | `storageClass.get()` - CDN integration, signed URLs, automatic provider detection                                                         |
-| 7   | **[Queue](/src/queue/README.md)**       | 📊 Data & Communication | Memory → Redis → DB scaling                           | `queueClass.get()` - Background jobs, scheduling, retry logic with exponential backoff                                                    |
-| 8   | **[Email](/src/email/README.md)**       | 📊 Data & Communication | Console → SMTP → Resend                               | `emailClass.get()` - Templates, multi-provider, automatic strategy selection                                                              |
-| 9   | **[Event](/src/event/README.md)**       | 📊 Data & Communication | Memory → Redis distribution                           | `eventClass.get('namespace')` - Real-time, pub/sub, wildcard patterns (user.\*)                                                           |
-| 10  | **[Util](/src/util/README.md)**         | 🛠️ Developer Experience | 12 essential utilities                                | `utilClass.get()` - Safe property access (get), performance helpers (debounce, chunk)                                                     |
-| 11  | **[Config](/src/config/README.md)**     | 🛠️ Developer Experience | Environment variables                                 | `configClass.get()` - Type-safe, UPPER_SNAKE_CASE convention, validation included                                                         |
-| 12  | **[Logger](/src/logger/README.md)**     | 🛠️ Developer Experience | Structured logging                                    | `loggerClass.get('component')` - Multi-transport, auto-scaling (Console → File → HTTP)                                                    |
+| File | Purpose |
+|---|---|
+| **[`AGENTS.md`](./AGENTS.md)** | Rules: always-do, never-do, canonical patterns. Read first. |
+| **[`llms.txt`](./llms.txt)** | Reference: every export, every method, signatures + examples. |
+| **[`examples/`](./examples)** | 12 minimal `.ts` files, one per module. Copy and modify. |
+| **[`cookbook/`](./cookbook)** | Composed recipes for whole patterns (CRUD, multi-tenant, file upload, real-time). |
 
-### **Category Summary**
+All four ship inside the npm tarball. AI agents installing `@bloomneo/appkit`
+can read them directly from `node_modules/@bloomneo/appkit/`.
 
-- **🔧 Infrastructure (4 modules)**: Core application foundation - auth,
-  database, security, error handling
-- **📊 Data & Communication (5 modules)**: Data flow and external interactions -
-  cache, storage, queue, email, events
-- **🛠️ Developer Experience (3 modules)**: Development productivity - utilities,
-  configuration, logging
+---
 
-## 🌍 Environment-Driven Progressive Scaling
+## 🚀 Quick start
 
-### **Development** (Zero Configuration)
+### As a library (in any Node.js project)
 
 ```bash
-npm start  # Memory cache, local storage, console logs
-```
-
-### **Production** (Auto-Detection)
-
-```bash
-# Set these environment variables - everything scales automatically
-DATABASE_URL=postgresql://prod-db/app     # → Database persistence
-REDIS_URL=redis://prod-cache:6379         # → Distributed cache/queue
-AWS_S3_BUCKET=prod-assets                 # → Cloud storage + CDN
-RESEND_API_KEY=re_production_key          # → Professional email
-VOILA_DB_TENANT=auto                      # → Multi-tenant mode
-```
-
-**Same code. Different environment. Enterprise features automatically enabled.**
-
-## 🏢 Enterprise-Ready Examples
-
-### **Multi-Tenant SaaS API**
-
-```typescript
-import { authClass } from '@bloomneo/appkit/auth';
-import { databaseClass } from '@bloomneo/appkit/database';
-import { securityClass } from '@bloomneo/appkit/security';
-import { cacheClass } from '@bloomneo/appkit/cache';
-
-const auth = authClass.get();
-const database = await databaseClass.get(); // Auto-filtered by tenant
-const security = securityClass.get();
-const cache = cacheClass.get('api');
-
-// User endpoint (tenant-isolated)
-app.get(
-  '/api/users',
-  auth.requireLogin(),
-  security.requests(100, 900000), // Rate limiting
-  async (req, res) => {
-    const users = await cache.getOrSet(
-      'users',
-      async () => {
-        return await database.user.findMany(); // Only current tenant
-      },
-      300
-    );
-
-    res.json(users);
-  }
-);
-
-// Admin endpoint (cross-tenant access)
-app.get(
-  '/api/admin/analytics',
-  auth.requireRole('admin.system'),
-  async (req, res) => {
-    const dbTenants = await databaseClass.getTenants(); // All tenants
-    const stats = await dbTenants.user.groupBy({
-      by: ['tenant_id'],
-      _count: true,
-    });
-
-    res.json(stats);
-  }
-);
+npm install @bloomneo/appkit
 ```
 
-### **Real-Time Chat Application**
-
-```typescript
-import { eventClass } from '@bloomneo/appkit/event';
+```ts
 import { authClass } from '@bloomneo/appkit/auth';
 import { databaseClass } from '@bloomneo/appkit/database';
 
-const events = eventClass.get();
 const auth = authClass.get();
 const database = await databaseClass.get();
-
-// Handle user connections
-events.on('user.connected', async (data) => {
-  const { userId, socketId } = data;
-
-  // Join user to their rooms
-  await events.emit('socket.join', {
-    socketId,
-    rooms: [`user:${userId}`, `tenant:${data.tenantId}`],
-  });
-});
-
-// Handle chat messages
-events.on('message.send', async (data) => {
-  const message = await database.message.create({
-    data: {
-      content: data.content,
-      userId: data.userId,
-      roomId: data.roomId,
-    },
-  });
-
-  // Broadcast to room (tenant-isolated)
-  await events.emit('message.broadcast', {
-    roomId: data.roomId,
-    message: {
-      id: message.id,
-      content: message.content,
-      user: { name: data.userName },
-      timestamp: message.createdAt,
-    },
-  });
-});
-
-// REST API integration
-app.post('/api/notifications', auth.requireLogin(), async (req, res) => {
-  const user = auth.user(req);
-
-  // Send real-time notification
-  await events.emit('notification.send', {
-    userId: user.userId,
-    type: 'info',
-    message: req.body.message,
-    timestamp: new Date(),
-  });
-
-  res.json({ sent: true });
-});
 ```
 
-### **File Upload with Background Processing**
+### As a complete scaffold (CLI)
 
-```typescript
-import { storageClass } from '@bloomneo/appkit/storage';
-import { queueClass } from '@bloomneo/appkit/queue';
-import { loggerClass } from '@bloomneo/appkit/logger';
-import { securityClass } from '@bloomneo/appkit/security';
-
-const storage = storageClass.get();
-const queue = queueClass.get();
-const logger = loggerClass.get('upload');
-const security = securityClass.get();
+```bash
+npm install -g @bloomneo/appkit
+appkit generate app myproject
+cd myproject && npm run dev:api
+```
 
-// File upload with background processing
-app.post(
-  '/upload',
-  security.requests(10, 60000), // 10 uploads per minute
-  async (req, res) => {
-    // Sanitize filename
-    const safeName = security.input(req.file.originalname);
-    const key = `uploads/${Date.now()}-${safeName}`;
-
-    // Store file (auto-detects Local/S3/R2)
-    await storage.put(key, req.file.buffer, {
-      contentType: req.file.mimetype,
-    });
-
-    // Queue background processing
-    await queue.add('process-image', {
-      key,
-      userId: req.user.id,
-      originalName: req.file.originalname,
-    });
-
-    logger.info('File uploaded', { key, userId: req.user.id });
-
-    res.json({
-      url: storage.url(key),
-      key,
-      processing: true,
-    });
-  }
-);
+→ Production-ready Express API at `http://localhost:3000` with auth, database,
+logging, error handling all wired.
 
-// Background processing
-queue.process('process-image', async (data) => {
-  const logger = loggerClass.get('processor');
-
-  try {
-    const buffer = await storage.get(data.key);
-
-    // Process image (resize, optimize, etc.)
-    const processed = await processImage(buffer);
-
-    // Store processed version
-    const processedKey = data.key.replace('.', '-processed.');
-    await storage.put(processedKey, processed);
-
-    logger.info('Image processed', {
-      original: data.key,
-      processed: processedKey,
-    });
-
-    return { processedKey };
-  } catch (error) {
-    logger.error('Processing failed', {
-      key: data.key,
-      error: error.message,
-    });
-    throw error;
-  }
-});
-```
+For full-stack scaffolding (frontend + backend), use [`@bloomneo/bloom`](https://www.npmjs.com/package/@bloomneo/bloom)
+which assembles AppKit + UIKit + FBCA convention into one CLI.
 
-## 🤖 AI Agent Integration Examples
+---
 
-### **Prompt for Complete Auth System**
+## ✨ The one rule that matters most
 
-```
-Create a Node.js API with user authentication, role-based access control,
-and protected admin routes using Bloomneo AppKit.
+```ts
+const auth = authClass.get();   // ALWAYS .get(), NEVER `new AuthClass()`
 ```
 
-**AI Agent Output** (guaranteed to work):
+Every module follows this exact pattern. There are no exceptions, no
+constructors, no factories with custom names.
 
-```typescript
-import { authClass } from '@bloomneo/appkit/auth';
-import { errorClass } from '@bloomneo/appkit/error';
-import { databaseClass } from '@bloomneo/appkit/database';
-import { loggerClass } from '@bloomneo/appkit/logger';
-
-const auth = authClass.get();
-const error = errorClass.get();
+```ts
+const auth     = authClass.get();
 const database = await databaseClass.get();
-const logger = loggerClass.get('auth');
+const error    = errorClass.get();
+const cache    = cacheClass.get();           // default 'app' namespace
+const userCache = cacheClass.get('users');   // custom namespace
+const logger   = loggerClass.get('api');     // component-tagged
+```
 
-// Login endpoint
-app.post(
-  '/auth/login',
-  error.asyncRoute(async (req, res) => {
-    const { email, password } = req.body;
-
-    if (!email || !password) {
-      throw error.badRequest('Email and password required');
-    }
-
-    const user = await database.user.findUnique({ where: { email } });
-    if (!user) {
-      throw error.unauthorized('Invalid credentials');
-    }
-
-    const isValid = await auth.comparePassword(password, user.password);
-    if (!isValid) {
-      throw error.unauthorized('Invalid credentials');
-    }
-
-    // Generate login token for user authentication
-    const loginToken = auth.generateLoginToken({
-      userId: user.id,
-      role: user.role,
-      level: user.level,
-    });
-
-    logger.info('User logged in', { userId: user.id });
-    res.json({ token: loginToken, user: { id: user.id, email: user.email } });
-  })
-);
+**One function per module. Predictable. Non-ambiguous. AI-agent friendly.**
 
-// Create API token for external service
-app.post(
-  '/admin/api-tokens',
-  auth.requireLoginToken(),
-  auth.requireUserRoles(['admin.tenant']),
-  error.asyncRoute(async (req, res) => {
-    const { keyId, permissions } = req.body;
-
-    // Generate API token for service authentication
-    const apiToken = auth.generateApiToken(
-      {
-        keyId,
-        role: 'service',
-        level: 'external',
-        permissions,
-      },
-      '1y'
-    );
-
-    res.json({ apiToken });
-  })
-);
+---
 
-// Protected user route (requires login token)
-app.get(
-  '/api/profile',
-  auth.requireLoginToken(),
-  error.asyncRoute(async (req, res) => {
-    const user = auth.user(req);
-    const profile = await database.user.findUnique({
-      where: { id: user.userId },
-    });
-    res.json(profile);
-  })
-);
+## 🎭 The 12 modules
+
+| # | Module | Purpose | Auto-scales |
+|---|---|---|---|
+| 1 | **Auth** | JWT tokens, role.level permissions, middleware | — |
+| 2 | **Database** | Prisma/Mongoose with multi-tenant filtering | per-org databases |
+| 3 | **Security** | CSRF, rate limiting, AES-256-GCM, input sanitization | — |
+| 4 | **Error** | HTTP errors with semantic types + middleware | — |
+| 5 | **Cache** | Memory → Redis | `REDIS_URL` |
+| 6 | **Storage** | Local → S3/R2 | `AWS_S3_BUCKET` |
+| 7 | **Queue** | Memory → Redis → DB | `REDIS_URL` / `BLOOM_QUEUE_DB` |
+| 8 | **Email** | Console → SMTP → Resend | `RESEND_API_KEY` |
+| 9 | **Event** | Memory → Redis pub/sub | `REDIS_URL` |
+| 10 | **Logger** | Console → File → HTTP | `BLOOM_LOGGER_*` |
+| 11 | **Config** | Type-safe env var access | — |
+| 12 | **Util** | Safe property access, debounce, chunk, uuid, slugify | — |
+
+For full method signatures and per-module examples, read [`llms.txt`](./llms.txt).
 
-// Admin-only route (requires login token + admin role)
-app.get(
-  '/api/admin/users',
-  auth.requireLoginToken(),
-  auth.requireUserRoles(['admin.tenant']),
-  error.asyncRoute(async (req, res) => {
-    const users = await database.user.findMany();
-    res.json(users);
-  })
-);
+---
 
-// API endpoint (requires API token)
-app.post(
-  '/webhook/data',
-  auth.requireApiToken(),
-  error.asyncRoute(async (req, res) => {
-    const token = auth.user(req);
-    logger.info('Webhook received', { keyId: token.keyId });
-    res.json({ received: true });
-  })
-);
+## 🌍 Environment-driven progressive scaling
 
-// Error handling middleware (must be last)
-app.use(error.handleErrors());
-```
+Same code. Different `.env`. Enterprise features automatically enabled.
 
-### **Prompt for Multi-Tenant Data API**
+```bash
+# Day 1 — local development (zero config)
+BLOOM_AUTH_SECRET=<min 32 chars>
+DATABASE_URL=postgresql://localhost/myapp
+# → Memory cache, local file storage, console logs, console email
 
+# Month 6 — production (just add env vars, no code changes)
+REDIS_URL=redis://prod-cache:6379         # → distributed cache + queue
+AWS_S3_BUCKET=prod-assets                 # → cloud storage + CDN
+RESEND_API_KEY=re_production_key          # → professional email
+BLOOM_DB_TENANT=auto                      # → multi-tenant filtering
+BLOOM_LOGGER_HTTP_URL=https://logs.example.com  # → centralized logging
 ```
-Build a multi-tenant API where users can only see their organization's data,
-but admins can access all organizations.
-```
-
-**AI Agent Output**:
 
-```typescript
-import { databaseClass } from '@bloomneo/appkit/database';
-import { authClass } from '@bloomneo/appkit/auth';
-import { errorClass } from '@bloomneo/appkit/error';
+See [`examples/.env.example`](./examples/.env.example) for the full canonical template.
 
-const auth = authClass.get();
-const error = errorClass.get();
+---
 
-// User data (tenant-isolated)
-app.get(
-  '/api/projects',
-  auth.requireLogin(),
-  error.asyncRoute(async (req, res) => {
-    const database = await databaseClass.get(); // Auto-filtered by user's tenant
-    const projects = await database.project.findMany({
-      include: { tasks: true },
-    });
-    res.json(projects); // Only current tenant's projects
-  })
-);
+## 🛠️ AppKit CLI
 
-// Admin data (cross-tenant)
-app.get(
-  '/api/admin/all-projects',
-  auth.requireRole('admin.system'),
-  error.asyncRoute(async (req, res) => {
-    const dbTenants = await databaseClass.getTenants(); // All tenants
-    const allProjects = await dbTenants.project.findMany({
-      include: {
-        tasks: true,
-        _count: { select: { tasks: true } },
-      },
-    });
-    res.json(allProjects); // All organizations' projects
-  })
-);
+Project generation:
 
-// Organization-specific admin access
-app.get(
-  '/api/admin/org/:orgId/projects',
-  auth.requireRole('admin.org'),
-  error.asyncRoute(async (req, res) => {
-    const { orgId } = req.params;
-    const orgDatabase = await databaseClass.org(orgId).get();
-    const projects = await orgDatabase.project.findMany();
-    res.json(projects); // Specific organization's projects
-  })
-);
+```bash
+appkit generate app myproject       # full backend scaffold (Express + auth + db + error + logger)
 ```
 
-## 🚀 Production Deployment
-
-### **Required Environment Variables**
+Feature generation:
 
 ```bash
-# Core Security (Required)
-VOILA_AUTH_SECRET=your-super-secure-jwt-secret-minimum-32-chars
-
-# Database (Required)
-DATABASE_URL=postgresql://user:pass@host:5432/database
-
-# Production Services (Auto-detected)
-REDIS_URL=redis://user:pass@host:6379
-AWS_S3_BUCKET=your-bucket
-RESEND_API_KEY=re_your_api_key
-VOILA_SECURITY_CSRF_SECRET=your-csrf-secret-32-chars
-
-# Multi-tenancy (Optional)
-VOILA_DB_TENANT=auto
-
-# Organization Scaling (Optional)
-ORG_ACME=postgresql://acme.dedicated.aws.com/prod
-ORG_STARTUP=mongodb://startup.azure.com/db
+appkit generate feature product     # basic feature (route + service + types)
+appkit generate feature order --db  # database-enabled feature (+ model + HTTP tests)
+appkit generate feature user        # complete authentication system (9-role hierarchy)
 ```
 
-### **Docker Production Setup**
-
-```dockerfile
-FROM node:18-alpine
-WORKDIR /app
+Generated project structure:
 
-# Copy package files
-COPY package*.json ./
-RUN npm ci --only=production
-
-# Copy application
-COPY . .
-
-# Health check
-HEALTHCHECK --interval=30s --timeout=3s --start-period=5s --retries=3 \
-  CMD node -e "require('http').get('http://localhost:3000/health', (res) => { process.exit(res.statusCode === 200 ? 0 : 1) })"
-
-EXPOSE 3000
-CMD ["node", "server.js"]
 ```
-
-### **Kubernetes Deployment**
-
-```yaml
-apiVersion: apps/v1
-kind: Deployment
-metadata:
-  name: voila-app
-spec:
-  replicas: 3
-  selector:
-    matchLabels:
-      app: voila-app
-  template:
-    metadata:
-      labels:
-        app: voila-app
-    spec:
-      containers:
-        - name: app
-          image: my-app:latest
-          ports:
-            - containerPort: 3000
-          env:
-            - name: DATABASE_URL
-              valueFrom:
-                secretKeyRef:
-                  name: app-secrets
-                  key: database-url
-            - name: REDIS_URL
-              valueFrom:
-                secretKeyRef:
-                  name: app-secrets
-                  key: redis-url
-          livenessProbe:
-            httpGet:
-              path: /health
-              port: 3000
-            initialDelaySeconds: 30
-            periodSeconds: 10
+myproject/
+├── AGENTS.md                       # ← copied from @bloomneo/appkit at scaffold time
+├── llms.txt                        # ← copied from @bloomneo/appkit at scaffold time
+├── .env                            # ← contains generated BLOOM_AUTH_SECRET
+├── src/api/
+│   ├── server.ts                   # Express bootstrap
+│   ├── lib/api-router.ts           # auto-discovery routing
+│   └── features/
+│       ├── welcome/
+│       └── [your-features]/
+└── package.json
 ```
 
-## 📊 Performance & Scalability
-
-### **Benchmarks**
-
-- **Startup Time**: < 100ms (all modules loaded)
-- **Memory Usage**: < 50MB baseline (production)
-- **Request Throughput**: 10,000+ req/sec (with Redis)
-- **Database Connections**: Automatic pooling and management
-
-### **Scaling Characteristics**
+---
 
-| Environment     | Cache         | Storage     | Queue         | Database      |
-| --------------- | ------------- | ----------- | ------------- | ------------- |
-| **Development** | Memory        | Local       | Memory        | Single        |
-| **Staging**     | Redis         | S3          | Redis         | Single        |
-| **Production**  | Redis Cluster | S3/R2 + CDN | Redis Cluster | Read Replicas |
-| **Enterprise**  | Multi-region  | Multi-cloud | Distributed   | Multi-tenant  |
+## 🏗️ Migration
 
-## 🧪 Testing & Quality
+### From `@voilajsx/appkit`
 
-### **Testing Setup**
+Two breaking changes between `@voilajsx/appkit@1.2.8` and `@bloomneo/appkit@1.5.2`:
 
-```typescript
-import { utilClass } from '@bloomneo/appkit/util';
-import { loggerClass } from '@bloomneo/appkit/logger';
-import { cacheClass } from '@bloomneo/appkit/cache';
-import { databaseClass } from '@bloomneo/appkit/database';
-import { authClass } from '@bloomneo/appkit/auth';
+**1. The npm scope changed.** Project-wide find-and-replace:
 
-describe('API Tests', () => {
-  beforeEach(() => {
-    // Reset modules for clean tests
-    utilClass.clearCache();
-  });
-
-  afterEach(async () => {
-    // Clean up resources
-    await loggerClass.clear();
-    await cacheClass.clear();
-    await databaseClass.clear();
-  });
-
-  test('should handle user creation safely', async () => {
-    const auth = authClass.get();
-    const util = utilClass.get();
-
-    const userData = {
-      email: 'test@example.com',
-      name: 'Test User',
-    };
-
-    // Test safe property access
-    const email = util.get(userData, 'email');
-    expect(email).toBe('test@example.com');
-
-    // Test JWT token creation
-    const token = auth.signToken({
-      userId: 123,
-      role: 'user',
-      level: 'basic',
-    });
-
-    expect(token).toBeDefined();
-
-    // Test token verification
-    const payload = auth.verifyToken(token);
-    expect(payload.userId).toBe(123);
-  });
-});
+```diff
+- import { authClass } from '@voilajsx/appkit/auth';
++ import { authClass } from '@bloomneo/appkit/auth';
 ```
 
-### **Code Quality Standards**
-
-- **100% TypeScript**: Full type safety across all modules
-- **Comprehensive Tests**: Unit, integration, and e2e testing
-- **Security Audits**: Regular dependency and vulnerability scanning
-- **Performance Monitoring**: Built-in metrics and observability
-
-## 🔍 SEO & Discovery
-
-### **Keywords & Technologies**
+**2. The env var prefix changed.** This is a hard cutover with no fallback:
 
-- **Node.js Framework**: Enterprise-grade backend development
-- **AI Code Generation**: LLM-optimized, agentic programming
-- **Multi-tenant SaaS**: Progressive scaling, organization management
-- **Zero Configuration**: Environment-driven, production-ready
-- **TypeScript Ready**: Full type safety, modern development
-- **Microservices**: Modular architecture, independent scaling
-- **JWT Authentication**: Role-based access control, security
-- **Real-time Applications**: WebSocket support, event-driven, pub/sub
-- **Cloud Native**: Docker, Kubernetes, auto-scaling
-- **Developer Experience**: Fast development, maintainable code
-
-### **Use Cases**
-
-- **SaaS Applications**: Multi-tenant, progressive scaling
-- **API Backends**: RESTful, GraphQL, real-time
-- **E-commerce Platforms**: Payments, inventory, user management
-- **Content Management**: File handling, media processing
-- **Enterprise Applications**: Security, compliance, audit trails
-- **Microservices**: Independent, scalable, maintainable
-- **AI Applications**: LLM integration, automated workflows
-- **Startup MVPs**: Rapid development, production-ready
-
-## 📚 Learning Resources
-
-### **Quick References**
-
-- [🚀 CLI Reference](docs/APPKIT_CLI.md) - Complete command guide and usage
-  examples
-- [🤖 LLM Integration Guide](docs/APPKIT_LLM_GUIDE.md) - AI development patterns
-  and module usage
-- [📝 Code Standards](docs/APPKIT_COMMENTS_GUIDELINES.md) - Documentation
-  guidelines for backend apps
-
-### **Module Documentation**
-
-- [Authentication & Authorization](/src/auth/README.md) - Dual token system,
-  role.level hierarchy, automatic inheritance
-- [Database & Multi-tenancy](/src/database/README.md) - Progressive scaling,
-  organizations
-- [File Storage & CDN](/src/storage/README.md) - Local to cloud, automatic
-  optimization
-- [Caching & Performance](/src/cache/README.md) - Memory to Redis, namespace
-  isolation
-- [Background Jobs](/src/queue/README.md) - Processing, scheduling, reliability
-- [Email & Communications](/src/email/README.md) - Multi-provider, templates
-- [Real-time Events](/src/event/README.md) - WebSocket, pub/sub, notifications
-- [Security & Compliance](/src/security/README.md) - CSRF, encryption, rate
-  limiting
-- [Error Handling](/src/error/README.md) - HTTP status codes, semantic errors
-- [Logging & Observability](/src/logger/README.md) - Structured, multi-transport
-- [Configuration Management](/src/config/README.md) - Environment-driven,
-  type-safe
-- [Utilities & Helpers](/src/util/README.md) - 12 essential developer tools
-
-## 🌟 Community & Support
-
-### **Getting Help**
-
-- 🐙 [GitHub Issues](https://github.com/bloomneo/appkit/issues) - Bug reports
-  and feature requests
-- 📧 [Email Support](mailto:kt@voilacode.com) - Direct support for enterprises
+```diff
+- VOILA_AUTH_SECRET=...
++ BLOOM_AUTH_SECRET=...
 
-### **Contributing**
+- VOILA_SECURITY_CSRF_SECRET=...
++ BLOOM_SECURITY_CSRF_SECRET=...
 
-We welcome contributions! See our [Contributing Guide](CONTRIBUTING.md) for:
+- VOILA_DB_TENANT=auto
++ BLOOM_DB_TENANT=auto
+```
 
-- 🐛 Bug fixes and improvements
-- 📝 Documentation enhancements
-- ✨ New module features
-- 🧪 Test coverage improvements
-- 💡 Feature suggestions
+Every `VOILA_*` in your `.env` files needs to become `BLOOM_*`. There is no
+deprecation period — the legacy prefix is gone.
 
-<a id="scope-change"></a>
+Rationale: the rebrand was a clean break, the env var prefix was the last
+remaining piece of legacy branding, and shipping a backwards-compat shim
+just kept the old name visible in error messages and docs forever.
 
-## 🔁 Scope change (1.2.9)
+### From `@bloomneo/appkit@1.5.1` → `1.5.2`
 
-This package was previously published as **`@voilajsx/appkit`**. Starting with `1.2.9` it lives at **`@bloomneo/appkit`**. The old package on npm is frozen at `1.2.8` and will not receive further updates.
+Same env var rename as above. Source code (imports + module API) is
+unchanged. The breaking change is **only** the env var prefix.
 
-**Migration:**
+---
 
-```diff
-- npm install @voilajsx/appkit
-+ npm install @bloomneo/appkit
-```
+## 📚 Resources
 
-```diff
-- import { authClass } from '@voilajsx/appkit/auth';
-+ import { authClass } from '@bloomneo/appkit/auth';
-```
+- **[`AGENTS.md`](./AGENTS.md)** — agent-facing rules and conventions
+- **[`llms.txt`](./llms.txt)** — full machine-readable API reference
+- **[`examples/`](./examples)** — one minimal example per module
+- **[`cookbook/`](./cookbook)** — composed recipes (auth + crud, multi-tenant, file upload, real-time)
+- **[`CHANGELOG.md`](./CHANGELOG.md)** — release history
+- **[Per-module READMEs on GitHub](https://github.com/bloomneo/appkit/tree/main/src)** — long-form human docs (not shipped in tarball)
+- **Issues**: https://github.com/bloomneo/appkit/issues
 
-A project-wide find-and-replace of `@voilajsx/appkit` → `@bloomneo/appkit` is sufficient. The API surface, props, types, and behavior are identical between the two scopes — only the namespace changed.
+---
 
 ## 📄 License
 
-MIT © [Bloomneo](https://github.com/bloomneo) — See [LICENSE](LICENSE) for
-details.
+MIT © [Krishna Teja GS](https://github.com/ktvoilacode)
 
 ---
 
 <p align="center">
-  <strong>🚀 Built for the AI-first future of software development</strong><br>
+  <strong>🚀 Built for the AI-first future of backend development</strong><br>
   <strong>Where enterprise applications are generated, not written</strong><br><br>
-  <a href="https://github.com/bloomneo/appkit">⭐ Star us on GitHub</a> 
+  <a href="https://github.com/bloomneo/appkit">⭐ Star on GitHub</a>
 </p>
-
----
-
-### **🔖 Tags**
-
-`nodejs` `typescript` `framework` `ai-ready` `enterprise` `multi-tenant` `saas`
-`microservices` `jwt-authentication` `zero-config` `production-ready`
-`agentic-ai` `llm-optimized` `progressive-scaling` `real-time` `websocket`
-`pub-sub` `developer-experience`