webspresso 0.0.98 → 0.0.100

package/.agents/ROUTING.md

@@ -53,7 +53,10 @@ All routes are automatically discovered and registered from the `pages/` directo
 | `pages/index.njk` | `GET` | `/` | Home page (SSR Nunjucks) |
 | `pages/about.njk` | `GET` | `/about` | Static SSR page |
 | `pages/notes/[id].njk` | `GET` | `/notes/:id` | Dynamic SSR route with param |
+| `pages/(marketing)/about.njk` | `GET` | `/about` | Route Group page (omits `(marketing)`) |
+| `pages/(auth)/login.njk` | `GET` | `/login` | Route Group with isolated layout & middleware |
 | `pages/api/notes.get.js` | `GET` | `/api/notes` | List notes API endpoint |
+| `pages/api/(v1)/notes.get.js` | `GET` | `/api/notes` | API route inside Route Group |
 | `pages/api/notes.post.js` | `POST` | `/api/notes` | Create note API endpoint |
 | `pages/api/notes/[id].get.js` | `GET` | `/api/notes/:id` | Get single note API endpoint |
 | `pages/api/notes/[id].put.js` | `PUT` | `/api/notes/:id` | Update note API endpoint |
@@ -148,7 +151,50 @@ module.exports = {
 
 ---
 
-## 4. SSR Page Routes (`load()` Loader)
+## 4. Route Groups `(group)` Syntax & Layout Isolation
+
+Webspresso supports Next.js / Nuxt-style **Route Groups**. Any directory name wrapped in parentheses `(groupName)` is treated as an organizational group:
+- **Clean Public URLs**: The parenthesized directory name is completely omitted from the generated URL path.
+- **Layout & Middleware Isolation**: The directory hierarchy is preserved for cascading middleware (`_middleware.js`) and nested layouts (`_layout.njk`), allowing distinct shells and security guards without polluting public route URLs.
+- **Nesting & Dynamic Route Support**: Route groups can be nested (e.g. `(shop)/(checkout)/cart.njk` → `/cart`), combined with dynamic segments (e.g. `(app)/users/[id].njk` → `/users/:id`), and applied to API routes (`pages/api/(v1)/items.get.js` → `/api/items` or `pages/(marketing)/api/newsletter.post.js` → `/api/newsletter`).
+
+### 4.1 Route Group Structure Example
+
+```
+pages/
+├── (marketing)/
+│   ├── _layout.njk          # Marketing layout (Hero header, footer)
+│   ├── _middleware.js       # Track analytics / marketing headers
+│   ├── index.njk            -> GET /
+│   ├── about.njk            -> GET /about
+│   └── api/
+│       └── newsletter.post.js -> POST /api/newsletter
+├── (auth)/
+│   ├── _layout.njk          # Centered card layout (no nav/footer)
+│   ├── _middleware.js       # Guest-only guard (redirects authenticated users)
+│   ├── login.njk            -> GET /login
+│   └── register.njk         -> GET /register
+└── (app)/
+    ├── _layout.njk          # App shell layout with sidebar
+    ├── _middleware.js       # Strict session auth guard
+    └── dashboard.njk        -> GET /dashboard
+```
+
+### 4.2 Programmatic Utilities
+Webspresso exports core helpers to inspect and transform route group paths:
+```javascript
+const { isRouteGroupSegment, stripRouteGroups } = require('webspresso');
+
+isRouteGroupSegment('(marketing)'); // true
+isRouteGroupSegment('about');       // false
+
+stripRouteGroups('/(marketing)/about'); // '/about'
+stripRouteGroups('/(shop)/(checkout)/cart'); // '/cart'
+```
+
+---
+
+## 5. SSR Page Routes (`load()` Loader)
 
 For server-rendered Nunjucks HTML pages, use `.njk` templates and companion `.js` loader files (or inline `async function load` in a `.js` file):
 
@@ -174,7 +220,7 @@ module.exports = {
 
 ---
 
-## 5. Module & File-Based Discovery (`src/pages`, `src/api`, `modules/{name}`)
+## 6. Module & File-Based Discovery (`src/pages`, `src/api`, `modules/{name}`)
 
 Webspresso supports clean, domain-driven module discovery alongside root-level pages and APIs:
 
@@ -204,7 +250,7 @@ src/
         auth-guard.js   -> module-local named middleware 'authGuard'
 ```
 
-### 5.1 `definePage()` Contract
+### 6.1 `definePage()` Contract
 ```javascript
 const { definePage } = require('webspresso');
 
@@ -230,7 +276,7 @@ module.exports = definePage({
 });
 ```
 
-### 5.2 `defineApi()` Contract
+### 6.2 `defineApi()` Contract
 ```javascript
 const { defineApi, z } = require('webspresso');
 
@@ -252,7 +298,7 @@ module.exports = defineApi({
 });
 ```
 
-### 5.3 `defineModule()` Contract
+### 6.3 `defineModule()` Contract
 ```javascript
 const { defineModule } = require('webspresso');
 
@@ -270,7 +316,7 @@ module.exports = defineModule({
 });
 ```
 
-### 5.4 Route Introspection (`app.routes.list()`)
+### 6.4 Route Introspection (`app.routes.list()`)
 Compiled routes are accessible at runtime for tooling, CLI inspection, and documentation:
 ```javascript
 const routeList = app.routes.list();
@@ -280,9 +326,116 @@ const routeList = app.routes.list();
 // ]
 ```
 
+### 6.5 Server-Sent Events (SSE) Streaming (`res.sse`)
+For real-time event streaming and LLM token outputs, use the native `res.sse()` helper (or `{ sse }` from `ctx`):
+
+```javascript
+// File: pages/api/ai/chat.post.js
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  handler: async (req, res, { sse }) => {
+    // 1. Controller mode with automatic keepalive & reconnection directives
+    const stream = sse({ heartbeat: 15000, retry: 3000 });
+
+    await stream.send({ delta: 'Hello ' });
+    await stream.send({ event: 'delta', data: { text: 'world!' }, id: '1' });
+    stream.close();
+
+    // 2. OR stream an async generator / LLM stream directly:
+    // return res.sse(async function*() {
+    //   for await (const chunk of llmStream) {
+    //     yield { token: chunk.text };
+    //   }
+    // });
+  },
+});
+```
+
+### 6.6 Cascading Middleware (`_middleware.js`) & Nested Layouts (`_layout.njk`)
+
+Webspresso supports folder-level cascading middleware inheritance and nested layouts across directory trees:
+
+#### 1. Cascading Middleware (`_middleware.js`)
+Any directory under `pages/` can declare a `_middleware.js` file:
+- **Execution Order**: Middlewares execute in top-down ancestral order (from root down to route leaf) before route handlers and route-specific middleware.
+- **Early Termination**: If any middleware sends headers (e.g. `res.status(401).json(...)` or `res.redirect('/login')`), execution halts immediately and downstream middlewares/handlers are skipped.
+- **Export Formats**: Standard Express middleware function `(req, res, next)`, async function, named middleware string/array `['auth', 'cors']`, or middleware tuples with options `[['rateLimit', { max: 100 }]]`.
+
+```
+pages/
+├── _middleware.js            # Runs for ALL routes (adds global headers / request ID)
+├── api/
+│   └── admin/
+│       ├── _middleware.js    # Protects all /api/admin/* endpoints
+│       └── metrics.get.js    # Inherits root + admin middleware
+└── dashboard/
+    ├── _middleware.js        # Auth guard for /dashboard/* pages
+    └── settings.njk
+```
+
+#### 2. Nested Layouts (`_layout.njk` & `_layout.js`)
+Pages under `pages/` automatically inherit ancestor layouts:
+- **Wrapping Order**: Child template is rendered first, then wrapped by layouts from innermost to outermost using `{{ content | safe }}`.
+- **Layout Loaders (`_layout.js`)**: Companion `_layout.js` files can export `async function load(req, ctx)` to supply shared data (e.g., site title, navigation, breadcrumbs) in top-down order before the page loader runs.
+- **Opt-Out**: A page can opt out of automatic layout wrapping by setting `layout: false` in its companion `.js` config/loader, or by explicitly using `{% extends "..." %}` in its Nunjucks template.
+
+```html
+{# pages/_layout.njk #}
+<!DOCTYPE html>
+<html>
+<head><title>{{ siteTitle }}</title></head>
+<body>
+  <header>Global Nav</header>
+  {{ content | safe }}
+</body>
+</html>
+```
+
+```html
+{# pages/dashboard/_layout.njk #}
+<div class="dashboard-shell">
+  <aside>Dashboard Sidebar</aside>
+  <main>{{ content | safe }}</main>
+</div>
+```
+
+#### 3. Folder-Level Error Boundaries (`_error.njk` & `_error.js`)
+When an exception occurs during SSR lifecycle execution (in `load()`, template rendering, hooks, or nested layout loaders):
+- **Ancestral Discovery**: Webspresso searches up the directory hierarchy from the route's directory up to `pages/` for the nearest `_error.njk`.
+- **Isolated Layout Preservation**: `_error.njk` is automatically wrapped inside the surrounding ancestor `_layout.njk` chain, keeping the UI intact (e.g. an error in `/dashboard/billing/invoices` renders the error card inside the dashboard sidebar and header).
+- **Companion Loader (`_error.js`)**: Can export `load({ error, req, res, ctx, db })` to attach custom error data or report exceptions.
+- **Status Code Propagation**: HTTP status is set to `error.status || error.statusCode || 500` (e.g., throwing `NotFoundError` returns HTTP 404).
+- **Opt-Out**: Disable layout wrapping with `layout: false` in `_error.js` or frontmatter (`--- layout: false ---`).
+- **Fallback**: If no `_error.njk` exists in any ancestor directory, execution falls through to the global Express error boundary (`app.setErrorHandler` / 500 page).
+
+```html
+{# pages/dashboard/_error.njk #}
+<div class="p-6 bg-red-50 dark:bg-red-950/30 rounded-xl border border-red-200">
+  <h2 class="text-xl font-bold text-red-700">Error {{ error.status }}</h2>
+  <p class="text-red-600 mt-2">{{ error.message }}</p>
+  {% if supportEmail %}<p class="mt-4 text-sm">Need help? Email {{ supportEmail }}</p>{% endif %}
+</div>
+```
+
+#### 4. Folder-Level Loading Skeletons (`_loading.njk`)
+In SSR streaming mode (`stream: true` or `renderStream`):
+- **Automatic Discovery**: Discovers the nearest `_loading.njk` up the directory chain.
+- **Auto-Populate Slots**: Any empty `<div data-stream-target="slotName"></div>` in the page template is automatically populated with the `_loading.njk` skeleton HTML in the initial flushed shell chunk!
+- **Context Availability**: Exposed as `{{ loadingSkeleton | safe }}` and `{{ loadingHtml | safe }}` in the template context.
+- **Layout Integration**: Cascading `_layout.njk` templates automatically wrap the streaming shell.
+
+```html
+{# pages/dashboard/_loading.njk #}
+<div class="animate-pulse space-y-4">
+  <div class="h-8 bg-slate-200 dark:bg-slate-800 rounded w-1/4"></div>
+  <div class="h-32 bg-slate-200 dark:bg-slate-800 rounded"></div>
+</div>
+```
+
 ---
 
-## 6. Summary Checklist for Agents
+## 7. Summary Checklist for Agents
 
 When a user asks to add or modify endpoints:
 1. Identify the URL and method (e.g. `POST /api/auth/register` or `POST /auth/login`).

package/.agents/STREAMING.md

@@ -71,3 +71,38 @@ export async function load({ req, db }) {
   };
 }
 ```
+
+---
+
+## 4. Folder-Based Loading Skeletons (`_loading.njk`)
+
+Directory trees under `pages/` support automatic loading skeleton discovery and injection:
+
+```
+pages/
+├── _loading.njk               # Root fallback skeleton
+└── dashboard/
+    ├── _loading.njk           # Dashboard-specific skeleton
+    ├── _layout.njk            # Cascading layout (wraps streaming shell)
+    ├── overview.njk
+    └── overview.js            # Returns { stream: true, defer: { metrics: ... } }
+```
+
+### Automatic Slot Population
+When `_loading.njk` exists in a folder hierarchy, any empty `<div data-stream-target="slotName"></div>` element is automatically populated with the rendered `_loading.njk` template inside the initial flushed HTML shell:
+
+```html
+<!-- pages/dashboard/overview.njk -->
+<h1>Dashboard Overview</h1>
+
+<!-- Automatically receives _loading.njk skeleton on initial flush! -->
+<div data-stream-target="metrics"></div>
+```
+
+### Template Context Availability
+The skeleton HTML is also directly accessible in the template context:
+- `{{ loadingSkeleton | safe }}`
+- `{{ loadingHtml | safe }}`
+
+### Nested Layouts with Streaming
+Cascading `_layout.njk` layouts automatically wrap the initial streaming shell chunk, preserving headers, navigation, and sidebars without extra configuration.

package/AGENTS.md

@@ -142,6 +142,8 @@ Plugins expose `name`, `version`, `dependencies`, and lifecycle hooks (`register
 - `restResourcePlugin`: Zero-boilerplate RESTful CRUD API generator directly from ORM models with eager loading, sanitization, filtering, pagination, and soft-delete scoping.
 - `xlsxPlugin`: Excel spreadsheet generation, parsing, ORM streaming export (`res.xlsx`), and built-in services (`xlsx.generate`, `xlsx.parse`, `xlsx.exportModel`).
 - `csvPlugin`: RFC 4180 CSV generator, parser, Excel UTF-8 BOM compatibility, formula sanitization, streaming writer (`res.csv`), and built-in services (`csv.generate`, `csv.parse`, `csv.exportModel`).
+- `apiKeyPlugin`: Zero-dependency B2B & Developer API Key Management with SHA-256 secure storage, constant-time verification, granular wildcard scopes, named route middleware (`ctx.middlewares.apiKey`), and non-blocking usage tracking.
+- `webhooksPlugin`: Outgoing Webhook Dispatcher with HMAC-SHA256 cryptographic signatures, wildcard event matching (`*`, `order.*`), automatic retries with exponential backoff, background job queue integration (`core/queue`), built-in services (`webhook.dispatch`, `webhook.ping`, `webhook.retry`), and Mithril.js Admin Panel management UI.
 
 ---
 

package/README.md

@@ -2,21 +2,22 @@
 
 [![npm version](https://img.shields.io/npm/v/webspresso.svg?style=flat-square)](https://www.npmjs.com/package/webspresso)
 [![vulnerabilities](https://npmx.dev/api/registry/badge/vulnerabilities/webspresso?style=shieldsio)](https://npmx.dev/package/webspresso)
+[![Node.js >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen.svg?style=flat-square)](https://nodejs.org)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
 
-A lightweight, zero-dependency-sprawl Express SSR framework featuring file-based routing, server-side Nunjucks rendering, an intuitive Knex-based ORM with ambient `AsyncLocalStorage` transactions, dual authentication (Session + JWT), zero-dependency streaming compression, graceful shutdown, and a customizable Mithril.js SPA Admin Panel.
+A batteries-included, full-stack Node.js framework combining Next.js/Nuxt-style file-based routing, server-rendered Nunjucks streaming, a Knex-based ORM with ambient transactions, zero-dependency dual authentication, background queues, and a customizable Mithril.js SPA Admin Panel.
 
 ---
 
-## ⚡ Quick Start (3 Minutes)
+## ⚡ Quick Start
 
-Scaffold a new project with interactive database and styling setup:
+Create a new Webspresso project in seconds:
 
 ```bash
-# Create a new project interactively
+# Scaffold a new application interactively
 npx webspresso new my-app --install
 
-# Navigate and start development server
+# Start development server with live reload
 cd my-app
 npm run dev
 ```
@@ -25,132 +26,183 @@ Open **`http://localhost:3000`** in your browser.
 
 ---
 
-## ✨ Why Webspresso?
+## 🌟 Core Capabilities
 
-- **Zero-Dependency Sprawl**: Core framework features (Dual Auth, JWT signing, Error handling, Streaming Compression, Graceful Shutdown, Template Helpers) rely strictly on native Node.js standard modules (`crypto`, `path`, `fs`, `events`, `zlib`, `async_hooks`) without bloated dependency trees.
-- **File-Based Routing & API Suffixes**: Pages and APIs automatically map to clean URLs with dynamic params (`[id]`), wildcards (`[...slug]`), and method suffixes (`.get.js`, `.post.js`, `.delete.js`, `.patch.js`, `.put.js`).
-- **Feature Modules (`defineModule`)**: Domain-driven modular organization for large projects (`modules/{name}/pages`, `api`, `services`, `middleware`).
-- **Modern Page & API Helpers (`definePage`, `defineApi`)**: Declarative Zod request schemas, unified execution context, and automatic JSON response serialization.
-- **Server Data Prefetching (`load()`)**: Page routes export `async function load({ req, res, db, ctx })` to fetch data server-side before template compilation.
-- **Services Layer**: File-based auto-discovery in `services/` with declarative Zod validation, role/predicate authorization guards, and memoization.
-- **Ambient Transactions**: Knex database transactions automatically bind to `AsyncLocalStorage` (`core/orm/transaction.js`). Scoped repositories seamlessly participate in active transactions without manual `trx` passing.
-- **Mithril.js Admin Panel SPA**: Built-in, isolated single-page admin panel mounted at `/_admin` with auto-layout wrapping for custom pages, widgets, and field renderers.
-- **TypeScript First-Class Support**: Shipped with complete [`index.d.ts`](index.d.ts) type definitions for IDE autocompletion and type checking.
+| Layer | Capabilities |
+| :--- | :--- |
+| **Routing & SSR** | 100% file-based routing (`pages/`), method suffixes (`.get.js`, `.post.js`), nested layouts (`_layout.njk`), directory-level error boundaries (`_error.njk`), loading skeletons (`_loading.njk`), and out-of-order chunked response streaming (`res.renderStream`). |
+| **Database & ORM** | Built-in Knex ORM with `defineModel`, `zdb` schema builder, Repository pattern (`db.getRepository('Model')`), relations (`belongsTo`, `hasMany`), cascade soft-delete & restore, and ambient transactions via `AsyncLocalStorage`. |
+| **Dual Auth & Sessions** | Stateful cookies for SSR + stateless HS256 JWT rotation for APIs, magic links, active device management & remote session revocation, CSRF protection, and zero external auth dependencies. |
+| **Services & Queues** | File-based auto-discovery in `services/` with declarative Zod validation, role-based access guards, and ACID transaction propagation. Background worker queues in `jobs/`. |
+| **Admin Panel SPA** | Integrated Mithril.js single-page admin panel mounted at `/_admin` with auto-layout wrapping, CRUD views, custom dashboard widgets, and custom field renderers. |
+| **Plugin Ecosystem** | 20+ official plugins: Polar.sh billing, Webhooks dispatcher with HMAC signatures, Realtime (WebSocket/SSE), Site Analytics, API Keys, File Manager, CSV/Excel generation, and more. |
+| **DevOps & Production** | Built-in streaming zlib compression (`brotli`/`gzip`), socket connection draining & graceful shutdown, `webspresso deploy:check` production readiness auditor, and Docker scaffolding. |
 
 ---
 
-## 🛠️ Minimal Example
+## 🛠️ Code at a Glance
 
-### 1. Server Entry Point (`server.js`)
-```javascript
-const path = require('path');
-require('./config/load-env');
-const { createApp, createDatabase } = require('webspresso');
-
-const db = createDatabase(require('./webspresso.db'));
-
-const { app } = createApp({
-  db,
-  pagesDir: path.join(__dirname, 'pages'),
-  viewsDir: path.join(__dirname, 'views'),
-  server: {
-    shutdown: { enabled: true, timeout: 10000 },
-    compression: true,
-  },
-});
+### 1. File-Based Page Route (`pages/notes.njk` + `pages/notes.js`)
 
-const PORT = process.env.PORT || 3000;
-app.listen(PORT, () => {
-  console.log(`Server listening at http://localhost:${PORT}`);
-});
-```
+Companion `.js` loaders fetch data server-side before template rendering:
 
-### 2. Server-Rendered Page (`pages/index.njk` + `pages/index.js`)
 ```html
-<!-- pages/index.njk -->
+<!-- pages/notes.njk -->
 {% extends "views/layout.njk" %}
 
 {% block content %}
-<div class="max-w-4xl mx-auto py-12 px-4">
-  <h1 class="text-3xl font-bold mb-4">{{ title }}</h1>
-  <p class="text-slate-600">Welcome, {{ user.name or "Guest" }}!</p>
+<div class="max-w-3xl mx-auto py-8">
+  <h1 class="text-2xl font-bold mb-4">My Notes</h1>
+  <ul class="space-y-2">
+    {% for note in notes %}
+      <li class="p-4 bg-white rounded border shadow-sm">{{ note.title }}</li>
+    {% else %}
+      <p class="text-slate-500">No notes yet.</p>
+    {% endfor %}
+  </ul>
 </div>
 {% endblock %}
 ```
 
 ```javascript
-// pages/index.js
-const { definePage } = require('webspresso');
-
-module.exports = definePage({
-  async load({ req, ctx }) {
-    return {
-      title: 'Home Page',
-      user: req.user || null,
-    };
+// pages/notes.js
+module.exports = {
+  async load({ req, db }) {
+    const notes = await db.getRepository('Note').find({
+      userId: req.user?.id,
+    });
+    return { notes };
   },
-});
+};
 ```
 
-### 3. Validated JSON API Endpoint (`pages/api/greet.post.js`)
+### 2. Method-Suffixed API Route (`pages/api/notes.post.js`)
+
+Export `{ schema, middleware, handler }` or `defineApi()` with declarative Zod validation:
+
 ```javascript
-const { defineApi, z } = require('webspresso');
+// pages/api/notes.post.js
+const { defineApi } = require('webspresso');
 
 module.exports = defineApi({
-  schema: {
+  schema: ({ z }) => ({
     body: z.object({
-      name: z.string().min(2),
+      title: z.string().min(1, 'Title is required').max(200),
+      content: z.string().min(1),
     }),
+  }),
+  middleware: ['auth'], // Built-in session or JWT guard
+  async handler(req, res) {
+    // req.input.body is validated and typed
+    const note = await req.db.getRepository('Note').create({
+      ...req.input.body,
+      userId: req.user.id,
+    });
+    return res.status(201).json(note);
+  },
+});
+```
+
+### 3. ORM Model Definition (`models/Note.js`)
+
+Define models with `defineModel` and the expressive `zdb` schema builder:
+
+```javascript
+// models/Note.js
+const { defineModel, zdb } = require('webspresso');
+
+module.exports = defineModel({
+  name: 'Note',
+  table: 'notes',
+  schema: {
+    id: zdb.id(),
+    title: zdb.string(200),
+    content: zdb.text(),
+    userId: zdb.integer(),
+    ...zdb.timestamps(),
+    ...zdb.softDeletes(),
   },
+  relations: {
+    user: { type: 'belongsTo', model: 'User', foreignKey: 'userId' },
+  },
+});
+```
+
+### 4. Application Server (`server.js`)
 
-  async handler(req, res, ctx) {
-    // req.input is typed and validated by Zod
-    const result = await ctx.service('user.greet', req.input.body);
-    return result; // Automatically serialized as JSON (HTTP 200)
+```javascript
+const path = require('path');
+const { createApp, createDatabase } = require('webspresso');
+
+const db = createDatabase(require('./webspresso.db'));
+
+const { app } = createApp({
+  db,
+  pagesDir: path.join(__dirname, 'pages'),
+  viewsDir: path.join(__dirname, 'views'),
+  server: {
+    compression: true,
+    shutdown: { enabled: true, timeout: 10000 },
   },
 });
+
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Server running at http://localhost:${PORT}`);
+});
+```
+
+---
+
+## 🧰 Essential CLI Commands
+
+```bash
+# Development & Builds
+npx webspresso dev                 # Start dev server with watch & live reload
+npx webspresso build               # Compile production assets
+npx webspresso start               # Run production server
+
+# Database & Migrations
+npx webspresso db:migrate          # Run pending database migrations
+npx webspresso db:rollback         # Roll back latest migration batch
+npx webspresso db:status           # Inspect migration status
+npx webspresso seed                # Run seed files
+
+# Code Generation
+npx webspresso page <path>         # Scaffold a new SSR page + loader
+npx webspresso api <path>          # Scaffold a new method-suffixed API route
+npx webspresso make:model <name>   # Generate a new ORM model
+npx webspresso make:job <name>     # Generate a background queue job
+
+# DevOps & Production Readiness
+npx webspresso doctor              # Run project health & configuration check
+npx webspresso deploy:check        # Pre-flight production readiness inspection
+npx webspresso add:docker          # Scaffold Dockerfile & docker-compose.yml
+npx webspresso add:tailwind        # Configure TailwindCSS integration
 ```
 
 ---
 
 ## 📚 Documentation
 
-The complete Webspresso documentation is organized into 5 focused pillars:
-
-### 🚀 Getting Started
-- **[Installation Guide](docs/getting-started/installation.md)** — Node.js 20 LTS prerequisites, CLI setup, and TypeScript.
-- **[Creating Your First App](docs/getting-started/first-app.md)** — Step-by-step walkthrough building an SSR page, API endpoint, and service.
-- **[Project Structure](docs/getting-started/project-structure.md)** — Anatomy of `pages/`, `views/`, `services/`, `models/`, and `config/`.
-- **[Deployment & Production](docs/getting-started/deployment.md)** — Production configuration, Docker, PM2, and Nginx.
-
-### 📖 Task Guides ("How do I...?")
-- **[File-Based Routing](docs/guides/routing.md)** — Static routes, dynamic params (`[id]`), and catch-all wildcards.
-- **[SSR & Templates](docs/guides/ssr-and-templates.md)** — Nunjucks layouts, `load()` loaders, `fsy` helper catalog, and chunked streaming.
-- **[Services Layer](docs/guides/services.md)** — Defining services, Zod validation, auth role guards, and ACID transactions.
-- **[Database & ORM](docs/guides/database-and-orm.md)** — Model definitions (`defineModel`), `zdb` schema builder, and Knex migrations.
-- **[Dual Authentication](docs/guides/authentication.md)** — Stateful Session cookies for SSR and stateless JWT rotation for REST APIs.
-- **[Admin Panel Customization](docs/guides/admin-panel.md)** — Custom Mithril.js SPA pages, KPI widgets, and custom field renderers.
-
-### 🧠 Concepts & Architecture ("How does it work and why?")
-- **[System Architecture](docs/concepts/architecture.md)** — Layered architecture, subsystem boundaries, and design principles.
-- **[Request Lifecycle](docs/concepts/request-lifecycle.md)** — End-to-end trace from TCP socket to template render and response stream.
-- **[Service Execution Pipeline](docs/concepts/service-execution-pipeline.md)** — Sanitization, Zod validation, auth guards, ambient transactions, and caching.
-- **[Ambient Transaction Propagation](docs/concepts/transaction-propagation.md)** — How `AsyncLocalStorage` manages ACID database transactions across nested services.
-
-### 📚 API Reference ("What is the exact contract?")
-- **[`createApp()` Configuration](docs/reference/create-app.md)** — Full `CreateAppOptions` parameter reference.
-- **[CLI Reference](docs/reference/cli.md)** — Complete `webspresso` CLI command manual.
-- **[Service Definition Spec](docs/reference/service-definition.md)** — `defineService` options and `ServiceContext` properties.
-- **[Model Definition Spec](docs/reference/model-definition.md)** — `defineModel` options, `zdb` column types, and `Repository` query methods.
-- **[Exceptions Catalog](docs/reference/exceptions.md)** — Built-in framework exception classes and HTTP status codes.
+Detailed topic guides are available in the repository:
+
+- **[Installation & First App](docs/getting-started/installation.md)** — Node.js requirements, setup, and first steps.
+- **[File-Based Routing & API Routes](.agents/ROUTING.md)** — Routing conventions, parameters, and cascading layouts.
+- **[SSR Streaming & Chunked Transfer](.agents/STREAMING.md)** — Out-of-order slots, `_loading.njk` skeletons, and TTFB optimization.
+- **[Database & ORM Guide](.agents/ORM.md)** — Repositories, relations, soft deletes, and ambient transactions.
+- **[Dual Authentication System](.agents/AUTH.md)** — Sessions, JWT rotation, magic links, and device management.
+- **[Plugin Ecosystem Reference](.agents/PLUGINS.md)** — Polar billing, webhooks, analytics, realtime, and more.
+- **[Admin Panel Customization](.agents/ADMIN.md)** — Extending the Mithril.js SPA admin panel.
+- **[Full TypeScript Reference](index.d.ts)** — Canonical framework types and signatures.
 
 ---
 
-## 🤖 For AI Coding Agents
+## 🤖 For AI Coding Assistants
 
-If you are an autonomous coding assistant or LLM working on a Webspresso codebase:
-- Read **[`AGENTS.md`](AGENTS.md)** for authoritative architectural guidelines, zero-regression policies, and critical signatures.
-- Consult **[`llms.txt`](llms.txt)** for a machine-readable sitemap of all documentation resources.
+If you are an autonomous coding agent working in a Webspresso codebase:
+- Read **[`AGENTS.md`](AGENTS.md)** for mandatory architectural rules, zero-regression policies, and code contracts.
+- Check **[`llms.txt`](llms.txt)** for a machine-readable directory map of all documentation.
 
 ---