webspresso 0.0.91 → 0.0.94

package/README.md

@@ -2,2915 +2,154 @@
 
 [![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)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](LICENSE)
 
-A minimal, file-based SSR framework for Node.js with Nunjucks templating.
+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.
 
-## Features
-
-- **File-Based Routing**: Create pages by adding `.njk` files to a `pages/` directory
-- **Dynamic Routes**: Use `[param]` for dynamic params and `[...rest]` for catch-all routes
-- **API Endpoints**: Add `.js` files to `pages/api/` with method suffixes (e.g., `health.get.js`)
-- **Schema Validation**: Zod-based request validation for body, params, and query
-- **Built-in i18n**: JSON-based translations with automatic locale detection
-- **Lifecycle Hooks**: Global and route-level hooks for request processing
-- **Template Helpers**: Laravel-inspired helper functions available in templates
-- **Plugin System**: Extensible architecture with version control and inter-plugin communication
-- **Built-in Plugins**: Development dashboard, sitemap generator, SEO checker, analytics integration (Google, Yandex, Bing), self-hosted site analytics, optional Swagger UI for HTTP APIs, configurable HTTP health probe endpoint, optional REST CRUD routes from ORM models, optional admin UI for ORM query cache metrics and purge, optional **admin-only spreadsheet exchange** (Excel export, CSV/XLSX import via `dataExchangePlugin`)
-- **Session authentication** (optional): `createAuth` / `quickAuth` in **`webspresso/core/auth`** — pass the manager to **`createApp({ auth })`** for `express-session`, `req.user` / `req.auth`, remember-me tokens, and policy-style authorization. Full walkthrough: **[`doc/index.html#authentication`](doc/index.html#authentication)**.
-- **Optional client runtime** (Alpine.js + [swup](https://swup.js.org/)): **`createApp({ clientRuntime: { alpine, swup } })`** serves scripts under **`/__webspresso/client-runtime/`** and exposes **`clientRuntime`** in Nunjucks; layouts can include **`views/partials/webspresso-client-runtime.njk`**. Env overrides: **`WEBSPRESSO_ALPINE`**, **`WEBSPRESSO_SWUP`**. Demo: **`examples/alpine-swup-demo/`**. Details: **[`doc/index.html#client-runtime`](doc/index.html#client-runtime)**.
-- **TypeScript**: Published **`index.d.ts`** (via `package.json` `"types"`) for `createApp`, ORM, plugins, and router helpers — use from TS/JS with IDE autocomplete; runtime stays CommonJS
-- **Application kernel (optional)**: In-process **`kernel`** API (`require('webspresso').kernel`) — event bus (`dispatch` / `publish`), **`kernel.createApp()`** (namespaced differently from SSR **`createApp`**), **`definePlugin`** / **`defineFlow`**, minimal **`{{ }}` view resolver**, and simulated **`BaseRepository`** with `orm.<resource>.*` events. Ships as **`core/kernel/`** on npm. Demo: **`node core/kernel/run-demo.js`**. Docs: **[`doc/index.html#application-kernel`](doc/index.html#application-kernel)**.
-
-## Installation
-
-```bash
-npm install -g webspresso
-# or
-npm install webspresso
-```
-
-## TypeScript
-
-The npm package ships with **[`index.d.ts`](index.d.ts)** so consumers get typings for the public API (`createApp`, `defineModel`, `createDatabase`, `zdb`, plugins, etc.). No extra `@types/webspresso` package is required.
-
-```typescript
-import { createApp, defineModel, zdb } from 'webspresso';
-```
-
-Install **`@types/express`** in your app if you want full **`Express.Application`** / **`Request`** / **`Response`** inference when you touch `createApp().app` or write middleware. **`knex`** and **`zod`** bring their own types.
-
-Framework development (this repo): run **`npm run check:types`** to typecheck the declarations against a small smoke file (`tests/ts-smoke/`).
-
-## Application kernel (`kernel`)
-
-Do **not** confuse **`kernel.createApp()`** with the package root **`createApp`** used for SSR—it returns a different object (event bus, optional flows, and a minimal view resolver). It does **not** modify Knex ORM behavior or Express routing.
-
-```javascript
-const { kernel } = require('webspresso');
-const app = kernel.createApp();
-app.events.on('orm.post.afterCreate', async (ctx) => { /* ... */ });
-```
-
-See **[`doc/index.html#application-kernel`](doc/index.html#application-kernel)** · source modules: [`core/kernel/`](core/kernel/). Cursor skill: **`REFERENCE-kernel.md`** (installed via `webspresso skill --preset webspresso`).
+---
 
-## Quick Start
+## ⚡ Quick Start (3 Minutes)
 
-### Using CLI (Recommended)
+Scaffold a new project with interactive database and styling setup:
 
 ```bash
-# Create a new project (Tailwind CSS included by default)
-webspresso new my-app
+# Create a new project interactively
+npx webspresso new my-app --install
 
-# Navigate to project
+# Navigate and start development server
 cd my-app
-
-# Install dependencies
-npm install
-
-# Build Tailwind CSS
-npm run build:css
-
-# Start development server (watches both CSS and server)
-webspresso dev
-# or
 npm run dev
 ```
 
-> **Note:** New projects include Tailwind CSS by default. Use `--no-tailwind` flag to skip it.
-
-## CLI Commands
-
-### `webspresso new [project-name]`
-
-Create a new Webspresso project with Tailwind CSS (default).
-
-```bash
-# Create in a new directory
-webspresso new my-app
-
-# Create in current directory (interactive)
-webspresso new
-# → Prompts: "Install in current directory?"
-# → If yes, asks for project name (for package.json)
-
-# Auto install dependencies and build CSS
-webspresso new my-app --install
-
-# Without Tailwind
-webspresso new my-app --no-tailwind
-```
-
-**Interactive Mode (no arguments):**
-- Asks if you want to install in the current directory
-- If current directory is not empty, shows a warning
-- Prompts for project name (defaults to current folder name)
-- Asks if you will use a database (SQLite, PostgreSQL, or MySQL)
-- If yes, adds the appropriate driver to `package.json` and creates `webspresso.db.js` config
-- After project creation, asks if you want to install dependencies
-- If yes, runs `npm install` and `npm run build:css`
-- Then asks if you want to start the development server
-- If yes, starts `npm run dev` automatically
-
-**Auto Installation:**
-```bash
-# With --install flag (semi-interactive)
-webspresso new my-app --install
-# → Automatically runs: npm install && npm run build:css
-# → Then prompts: "Start development server?" [Y/n]
-# → If yes: starts npm run dev (with watch:css if Tailwind enabled)
-
-# Without --install flag (fully interactive)
-webspresso new my-app
-# → Prompts: "Install dependencies and build CSS now?" [Y/n]
-# → If yes: runs npm install && npm run build:css
-# → Then: "Start development server?" [Y/n]
-# → If yes: starts npm run dev (with watch:css if Tailwind enabled)
-```
-
-**Note:** When dev server starts with Tailwind CSS, it automatically runs `watch:css` in the background to watch for CSS changes.
-
-**Database Selection:**
-During project creation, you'll be asked if you want to use a database:
-- **SQLite** (better-sqlite3) - Recommended for development and small projects
-- **PostgreSQL** (pg) - For production applications
-- **MySQL** (mysql2) - Alternative SQL database
-
-If you select a database:
-- The appropriate driver is added to `package.json` dependencies
-- `webspresso.db.js` config file is created with proper settings
-- `migrations/` directory is created
-- `models/` directory is created
-- `DATABASE_URL` is added to `.env.example` with a template
-
-**Scaffold: `config/` and environment files**
-
-New projects include:
-
-- **`config/load-env.js`** — loads, in order, `.env`, `.env.local`, `.env.${NODE_ENV}`, and `.env.${NODE_ENV}.local` (each file overrides keys from earlier ones).
-- **`config/env.schema.js`** — validates `process.env` with **Zod** before the app starts (`PORT`, `NODE_ENV`, i18n vars, `BASE_URL`, optional `DATABASE_URL`).
-- **`config/app.js`** — returns `createApp()` options (paths; if `webspresso.db.js` exists, also **`createDatabase`** as `db`).
-- **`server.js`** — calls `loadEnv()`, then `createApp(getCreateAppOptions())`, then `listen` using the parsed `PORT`.
-
-Copy **`.env.example`** to **`.env`** (and use `.env.local` for machine-specific overrides). Patterns such as `.env.development.local` are gitignored via `.env.*.local`.
-
-**Seed Data Generation:**
-After selecting a database, you'll be asked if you want to generate seed data:
-- If yes, `@faker-js/faker` is added to dependencies
-- `seeds/` directory is created with `seeds/index.js`
-- `npm run seed` script is added to `package.json`
-- The seed script automatically detects models in `models/` directory and generates fake data based on their schemas
-
-To run seeds after creating models:
-```bash
-npm run seed
-```
-
-The seed script will:
-- Load all models from `models/` directory
-- Generate 10 fake records per model (by default)
-- Use smart field detection based on column names (email, name, title, etc.)
-
-You can always add database support later by:
-1. Installing the driver: `npm install better-sqlite3` (or `pg`, `mysql2`)
-2. Creating `webspresso.db.js` config file
-3. Adding `DATABASE_URL` to your `.env` file
-4. Creating `models/` directory and defining your models
-5. Optionally adding seed support: `npm install @faker-js/faker` and creating `seeds/index.js`
-
-Options:
-- `-i, --install` - Auto run `npm install` and `npm run build:css` (non-interactive)
-- `--no-tailwind` - Skip Tailwind CSS setup
-
-The project includes:
-- Tailwind CSS with build process
-- Optimized layout template with navigation and footer
-- Responsive starter page
-- i18n setup (e.g. en/de)
-- Development and production scripts
-
-### `webspresso page`
-
-Add a new page to your project (interactive prompt).
-
-```bash
-webspresso page
-```
-
-The CLI will ask you:
-- Route path (e.g., `/about` or `/blog/post`)
-- Whether to add a route config file
-- Whether to add locale files
-
-### `webspresso api`
-
-Add a new API endpoint (interactive prompt).
-
-```bash
-webspresso api
-```
-
-The CLI will ask you:
-- API route path (e.g., `/api/users` or `/api/users/[id]`)
-- HTTP method (GET, POST, PUT, PATCH, DELETE)
-
-### `webspresso dev`
-
-Start development server with hot reload.
-
-```bash
-webspresso dev
-# or with custom port
-webspresso dev --port 3001
-```
-
-### `webspresso start`
-
-Start production server.
-
-```bash
-webspresso start
-# or with custom port
-webspresso start --port 3000
-```
-
-### `webspresso doctor`
-
-Check Node.js version, `package.json` / `engines.node`, typical project files (`server.js`, `pages/`), and whether `webspresso.db.js` or `knexfile.js` exists. Use `--db` to run a quick connection test when a config is present. Warnings alone exit with code `0`; pass `--strict` to fail (exit `1`) on any warning—useful in CI.
-
-```bash
-webspresso doctor
-webspresso doctor --db
-webspresso doctor --strict
-```
-
-### `webspresso skill`
-
-Scaffold an **Agent Skill**: creates `.agents/skills/<name>/SKILL.md` with valid YAML frontmatter (`name`, `description`) and a short markdown template for AI tooling. Use `--global` to write under `~/.agents/skills/` instead of the current project.
-
-**Bundled preset:** `--preset webspresso` copies **`SKILL.md`** (short index), **`REFERENCE-framework.md`** (SSR `createApp`, routes, ORM, auth, plugins, CLI), and **`REFERENCE-kernel.md`** (`kernel` event bus / flows) into **`.agents/skills/webspresso-usage/`** — no prompts.
-
-
-```bash
-webspresso skill my-workflow
-webspresso skill review-pr --description "Runs PR review checklist. Use when reviewing pull requests."
-webspresso skill deploy-check -g
-
-# Install the bundled Webspresso agent reference (same content shipped in templates/skills/)
-webspresso skill --preset webspresso
-webspresso skill -p webspresso --global
-```
-
-### `webspresso add tailwind`
-
-Add Tailwind CSS to your project with build process.
-
-```bash
-webspresso add tailwind
-```
-
-This command will:
-- Install Tailwind CSS, PostCSS, and Autoprefixer as dev dependencies
-- Create `tailwind.config.js` and `postcss.config.js`
-- Create `src/input.css` with Tailwind directives
-- Add build scripts to `package.json`
-- Update your layout to use the built CSS instead of CDN
-- Create `public/css/style.css` for the compiled output
-
-After running this command:
-```bash
-npm install
-npm run build:css      # Build CSS once
-npm run watch:css      # Watch and rebuild CSS on changes
-npm run dev            # Starts both CSS watch and dev server
-```
-
-### `webspresso favicon:generate <source.png>`
-
-Generate favicon PNG files and `favicons.njk` partial from a single source PNG.
-
-```bash
-# Basic usage (creates files in public/, views/partials/)
-webspresso favicon:generate logo.png
-
-# With PWA manifest options
-webspresso favicon:generate logo.png --name "My App" --short-name "App" --theme-color "#22c55e"
-
-# Custom output directory
-webspresso favicon:generate logo.png -o static
-
-# Skip adding include to layout.njk
-webspresso favicon:generate logo.png --no-layout
-```
-
-This command will:
-- Resize the source PNG to all required sizes (Apple touch 57–180px, Android 192px, favicon 16/32/96px, MS Tile 144px)
-- Write PNGs to `public/` (or `-o` path)
-- Create `public/manifest.json` (PWA format)
-- Create `views/partials/favicons.njk` with `<link>` and `<meta>` tags
-- Add `{% include "partials/favicons.njk" %}` to `views/layout.njk` (unless `--no-layout`)
-
-**Options:**
-- `-o, --output-dir <path>` – Output directory for PNGs (default: `public`)
-- `--partial-dir <path>` – Directory for favicons.njk (default: `views/partials`)
-- `--layout-file <path>` – Layout file to update (default: `views/layout.njk`)
-- `--theme-color <hex>` – theme-color and msapplication-TileColor (default: `#ffffff`)
-- `--name <string>` – manifest.json `name` (PWA)
-- `--short-name <string>` – manifest.json `short_name` (PWA)
-- `--no-layout` – Do not add include to layout.njk
-
-### Admin Panel Commands
-
-```bash
-# Create admin_users table migration
-webspresso admin:setup
-
-# List all admin users
-webspresso admin:list
-
-# Reset admin password (interactive)
-webspresso admin:password
-
-# Reset with options
-webspresso admin:password -e admin@example.com -p yeni_sifre123
-webspresso admin:password -c ./webspresso.db.js -E production
-```
-
-> **Note:** Requires `webspresso.db.js` or `knexfile.js` in project root. Run from project directory.
+Open **`http://localhost:3000`** in your browser.
 
-## Project Structure
-
-Create your app with this structure:
-
-```
-my-app/
-├── pages/
-│   ├── locales/          # Global i18n translations
-│   │   ├── en.json
-│   │   └── de.json
-│   ├── _hooks.js         # Global lifecycle hooks
-│   ├── index.njk         # Home page (GET /)
-│   ├── about/
-│   │   ├── index.njk     # About page (GET /about)
-│   │   └── locales/      # Route-specific translations
-│   ├── tools/
-│   │   ├── index.njk     # Tools list (GET /tools)
-│   │   ├── index.js      # Route config with load()
-│   │   ├── [slug].njk    # Dynamic tool page (GET /tools/:slug)
-│   │   └── [slug].js     # Route config for dynamic page
-│   └── api/
-│       ├── health.get.js # GET /api/health
-│       └── echo.post.js  # POST /api/echo
-├── views/
-│   └── layout.njk        # Base layout template
-├── public/               # Static files
-└── server.js
-```
-
-## API
-
-### `createApp(options)`
-
-Creates and configures the Express app.
-
-**Options:**
-- `pagesDir` (required): Path to pages directory
-- `viewsDir` (optional): Path to views/layouts directory
-- `publicDir` (optional): Path to public/static directory
-- `db` (optional): Database instance — exposed as `ctx.db` in plugin hooks (`register`, `onRoutesReady`) and in page `load`/`meta` functions; also registered for [`getDb()` / `getAppContext()`](#app-context-getdb-hasdb-getappcontext) below
-- `logging` (optional): Enable request logging (default: true in development)
-- `helmet` (optional): Helmet security configuration
-  - `true` or `undefined`: Use default secure configuration
-  - `false`: Disable Helmet
-  - `Object`: Custom Helmet configuration (merged with defaults)
-- `middlewares` (optional): Named middleware registry for routes
-- `clientRuntime` (optional): **`{ alpine?: boolean | object, swup?: boolean | object }`**. When either flag is enabled, mounts vendored Alpine 3 / swup 4 (+ Head + Scripts plugins) at **`/__webspresso/client-runtime/*`** and passes resolved **`{ alpine, swup }`** into SSR templates as **`clientRuntime`**. Override with env **`WEBSPRESSO_ALPINE`** / **`WEBSPRESSO_SWUP`** (`1` or `true`). Package exports **`resolveClientRuntime`** and **`CLIENT_RUNTIME_BASE`**. See **[Client runtime](#client-runtime)** below and **[`doc/index.html#client-runtime`](doc/index.html#client-runtime)**.
-- `auth` (optional): `AuthManager` from **`createAuth()`** / **`quickAuth()`** (`require('webspresso/core/auth')`). Registers session + cookie parsing, attaches **`req.auth`** / **`req.user`**, and injects named route middleware **`auth`** and **`guest`** (do not reuse those names for custom handlers if you pass `auth`). See **[`doc/index.html#authentication`](doc/index.html#authentication)**.
-- `setupRoutes(app, ctx)` (optional): Register custom Express routes after file routes and plugin `onRoutesReady`, before the 404 handler — use for login/logout handlers when using the auth module; **`ctx.authMiddleware`** exposes `requireAuth`, `requireGuest`, etc.; **`ctx.clientRuntime`** is **`{ alpine, swup }`**
-
-**Example with middlewares:**
-
-```javascript
-const { createApp } = require('webspresso');
-
-const { app } = createApp({
-  pagesDir: './pages',
-  viewsDir: './views',
-  middlewares: {
-    auth: (req, res, next) => {
-      if (!req.session?.user) {
-        return res.redirect('/login');
-      }
-      next();
-    },
-    admin: (req, res, next) => {
-      if (req.session?.user?.role !== 'admin') {
-        return res.status(403).send('Forbidden');
-      }
-      next();
-    },
-    rateLimit: require('express-rate-limit')({ windowMs: 60000, max: 100 })
-  }
-});
-```
+---
 
-Then use in route configs by name:
+## ✨ Why Webspresso?
 
-```javascript
-// pages/admin/index.js
-module.exports = {
-  middleware: ['auth', 'admin'], // Use named middlewares
-  load(req, ctx) { ... }
-};
+- **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**: Templates in `pages/` automatically become public URL routes with support for dynamic params (`[id]`) and catch-all wildcards (`[...slug]`).
+- **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.
 
-// pages/api/data.get.js
-module.exports = {
-  middleware: ['auth', 'rateLimit'],
-  handler: (req, res) => res.json({ data: 'protected' })
-};
-```
+---
 
-**Parameterized named middleware:** entries in `middlewares` can be **factories** `(options) => (req, res, next) => …`. A bare string calls the factory with `{}`; a **tuple** passes options:
+## 🛠️ Minimal Example
 
+### 1. Server Entry Point (`server.js`)
 ```javascript
-// pages/api/account.get.js
-module.exports = {
-  middleware: [['auth', { api: true }], 'rateLimit'], // JSON 401 instead of redirect when using createApp({ auth })
-  handler: (req, res) => res.json({ ok: true }),
-};
-
-// server.js — custom factory
-middlewares: {
-  oauth: (opts) => (req, res, next) => {
-    if (opts.google && !req.headers['x-google']) return res.status(401).end();
-    next();
-  },
-};
-// pages/example/index.js → middleware: [['oauth', { google: true }], 'auth']
-```
-
-Plain `(req, res, next) => …` handlers still work as today. Tuple form **requires** a factory for that name (you get a clear error if you mix a plain handler with `['name', opts]`).
-
-### Client runtime
-
-Alpine.js + swup — opt-in progressive enhancement for SSR pages:
-
-- **`clientRuntime: { alpine: true, swup: true }`** (each can be toggled independently). Default is off; no scripts are injected when both are disabled.
-- Include **`{% include "partials/webspresso-client-runtime.njk" %}`** in your layout (copy from the npm package’s **`views/partials/`** or the framework repo). When **swup** is on, wrap the main content in **`<main id="swup">…</main>`** so transitions replace the correct region.
-- **swup** uses Head + Scripts plugins; **Alpine** is re-bound after each visit via **`Alpine.initTree`** on the container. Use **`data-no-swup`** on links for a full page load. Paths **`/_admin`** and **`/_webspresso`** are ignored by the default bootstrap; the admin panel and dev dashboard stay separate Mithril apps.
-- Dynamic UI can call **`pages/api/*`** from Alpine with **`fetch`** (see **`examples/alpine-swup-demo/`**).
-- **Helmet / CSP**: production **`script-src 'self'`** works for **`/__webspresso/client-runtime/`**; some Alpine builds may need **`unsafe-eval`** — validate for your version or use a stricter build.
+const path = require('path');
+require('./config/load-env');
+const { createApp, createDatabase } = require('webspresso');
 
-```javascript
-const { createApp } = require('webspresso');
+const db = createDatabase(require('./webspresso.db'));
 
 const { app } = createApp({
-  pagesDir: './pages',
-  viewsDir: './views',
-  publicDir: './public',
-  clientRuntime: { alpine: true, swup: true },
-});
-```
-
-### App context (`req.db`, `getDb`, `attachDbMiddleware`)
-
-With **`createApp({ db })`**, file-based **API** routes (`pages/api/*.js`) get the same ORM instance on **`req.db`** before your **`middleware`** array and the handler run — no extra `require` in the handler:
-
-```javascript
-module.exports = async function handler(req, res) {
-  if (!req.db) {
-    return res.status(503).json({ error: 'Database not configured' });
-  }
-  const posts = await req.db.getRepository('Post').query().limit(10).list();
-  res.json(posts);
-};
-
-module.exports.middleware = ['auth']; // can use req.db too
-```
-
-The framework also registers that instance for **non-request** code (scripts, jobs) and for tests:
-
-```javascript
-const { getDb, hasDb } = require('webspresso');
-// hasDb() / getDb() — getDb() throws if createApp had no db
-```
-
-For routes you add manually in **`setupRoutes`**, run **`attachDbMiddleware`** early so those handlers get `req.db`:
-
-```javascript
-const { createApp, attachDbMiddleware } = require('webspresso');
-
-createApp({
-  pagesDir: './pages',
   db,
-  setupRoutes(app) {
-    app.use(attachDbMiddleware);
-    app.get('/custom/api', (req, res) => res.json({ ok: !!req.db }));
+  pagesDir: path.join(__dirname, 'pages'),
+  viewsDir: path.join(__dirname, 'views'),
+  server: {
+    shutdown: { enabled: true, timeout: 10000 },
+    compression: true,
   },
 });
-```
-
-| Export | Role |
-|--------|------|
-| `req.db` | Set on each API request when `createApp({ db })` was used (file-based API routes + after `attachDbMiddleware`) |
-| `getDb()` | Same instance as `req.db`; **throws** if no `db` was passed to `createApp` |
-| `hasDb()` | `true` if `createApp` was given `db` |
-| `getAppContext()` | `{ db }` — `db` may be `null` |
-| `attachDbMiddleware` | Express middleware to populate `req.db` for non–file-router routes |
-| `resetAppContext()` | Clears context (mainly for tests) |
-| `setAppContext(partial)` | Low-level merge; normally only `createApp` uses this |
-
-**Custom Error Pages:**
-
-```javascript
-const { createApp } = require('webspresso');
 
-const { app } = createApp({
-  pagesDir: './pages',
-  viewsDir: './views',
-  errorPages: {
-    // 404 Not Found: Template path (relative to viewsDir) or custom handler fn
-    notFound: '404.njk', // or 'errors/404.njk', or (req, res, ctx) => res.render('404.njk', ctx)
-    
-    // 500 Internal Server Error: Template path or custom handler fn
-    serverError: 'errors/500.njk', // or (err, req, res, ctx) => ...
-    
-    // 503 Request Timeout: Template path or custom handler fn
-    timeout: 'errors/503.njk' // or (req, res, ctx) => ...
-  }
+const PORT = process.env.PORT || 3000;
+app.listen(PORT, () => {
+  console.log(`Server listening at http://localhost:${PORT}`);
 });
 ```
 
-#### Error Template Context & Behavior
-
-All error templates rendered with Nunjucks automatically receive a rich request context:
-- **`404.njk` (`notFound`)**: `{ fsy, locale, isDev, url, method }` — sets HTTP status `404`. If omitted, Webspresso provides a responsive built-in HTML 404 page for browsers, or `{ error: 'Not Found', status: 404 }` JSON for API requests.
-- **`500.njk` (`serverError`)**: `{ fsy, locale, isDev, url, method, error, status }` — sets HTTP status `500` (or `err.status`).
-- **`503.njk` (`timeout`)**: `{ fsy, locale, isDev, url, method }` — sets HTTP status `503`.
-
-```njk
-{# Example views/404.njk #}
-{% extends "layout.njk" %}
+### 2. Server-Rendered Page (`pages/index.njk` + `pages/index.js`)
+```html
+<!-- pages/index.njk -->
+{% extends "views/layout.njk" %}
 
 {% block content %}
-<div class="max-w-xl mx-auto text-center py-20">
-  <h1 class="text-6xl font-bold text-slate-800">404</h1>
-  <p class="text-xl text-slate-600 mt-4">Page Not Found: <code>{{ url }}</code></p>
-  <a href="{{ fsy.url('/') }}" class="mt-6 inline-block bg-blue-600 text-white px-6 py-2 rounded-lg">
-    Back to Home
-  </a>
+<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>
 {% endblock %}
 ```
 
-**How errors reach this handler**
-
-Unhandled errors from file-based routes (`pages/**/*.njk` `load()` / middleware / render, and `pages/api/**/*.js` handlers) are forwarded with `next(err)`, so they go through this 4-argument Express error middleware. That means `errorPages.serverError` and `errorPages.timeout` apply to those failures as well (not only to routes you add with `setupRoutes`).
-
-- **`pages/_hooks.js` `onError(ctx, err)`** runs **before** the central handler (for both SSR and API file routes). Use it for logging or APM (`Sentry.captureException`, `newrelic.noticeError`, etc.). The error is also on **`ctx.error`**.
-
-- **JSON vs HTML:** Requests whose path starts with **`/api`** always get a **JSON** error body from the default branch (and the default **string** `serverError` / `timeout` Nunjucks templates are skipped for those paths). Other clients use **`Accept`** as before: prefer HTML when the client accepts HTML.
-
-**Request Timeout:**
-
-Configure request timeout with `connect-timeout`:
-
-```javascript
-const { app } = createApp({
-  pagesDir: './pages',
-  timeout: '30s',  // Default: 30 seconds
-  // timeout: '1m',  // 1 minute
-  // timeout: false, // Disable timeout
-});
-```
-
-**Asset Management & Cache-Busting:**
-
-Webspresso includes a built-in `AssetManager` that automates static asset URL resolution, query-string cache-busting, Vite/Webpack build manifest lookups, and CDN prefixing in Nunjucks SSR templates.
-
-Configure asset handling in `createApp`:
-
-```javascript
-const { createApp } = require('webspresso');
-const path = require('path');
-
-const { app } = createApp({
-  pagesDir: './pages',
-  viewsDir: './views',
-  publicDir: './public', // default: 'public'
-  assets: {
-    // 1. Static query-string versioning (Cache Busting)
-    // Appends ?v=1.2.3 (or &v=... if existing query params) to asset URLs
-    version: process.env.APP_VERSION || '1.0.0', // or Git commit hash, build timestamp
-
-    // 2. Build Tool Manifest (Vite, Webpack, etc.)
-    // Resolves hashed bundle filenames automatically (e.g. style.css -> assets/style-abc123.css)
-    manifestPath: path.join(__dirname, 'public/.vite/manifest.json'),
-
-    // 3. Asset URL Prefix / CDN
-    // Prepended to all resolved asset paths
-    prefix: process.env.CDN_URL || '' // e.g. 'https://cdn.example.com' or '/static'
-  }
-});
-```
-
-#### How Asset Resolution Works
-
-1. **Manifest Match First**: If `manifestPath` is configured and an entry matches the asset key, `AssetManager` resolves to the hashed filename (from Vite or Webpack manifest) and prepends `prefix`.
-2. **Fallback to Path & Versioning**: If no manifest is provided or the asset is not listed in the manifest, `AssetManager` uses the original path, prepends `prefix`, and appends `?v=<version>` (or `&v=<version>`) if `version` is set.
-3. **Leading Slash Normalization**: Paths with or without leading slashes (e.g., `'css/style.css'` or `'/css/style.css'`) are handled seamlessly.
-
-```json
-// Example Vite manifest format (.vite/manifest.json)
-{
-  "css/style.css": { "file": "assets/style-abc123.css", "src": "css/style.css" },
-  "js/app.js": { "file": "assets/app-xyz789.js", "src": "js/app.js" }
-}
-
-// Example Webpack manifest format (manifest.json)
-{
-  "/css/style.css": "/dist/style.abc123.css",
-  "/js/app.js": "/dist/app.xyz789.js"
-}
-```
-
-#### Template Helpers (`fsy`)
-
-Use `fsy` helpers inside your Nunjucks layouts and pages:
-
-```njk
-{# 1. URL string resolution #}
-<link rel="stylesheet" href="{{ fsy.asset('/css/style.css') }}">
-{# Outputs: <link rel="stylesheet" href="/css/style.css?v=1.0.0"> (or /assets/style-abc123.css) #}
-
-{# 2. CSS link tag helper #}
-{{ fsy.css('/css/style.css') | safe }}
-{# With custom attributes (media, id, integrity, etc.): #}
-{{ fsy.css('/css/print.css', { media: 'print', id: 'print-styles' }) | safe }}
-
-{# 3. JS script tag helper #}
-{{ fsy.js('/js/app.js') | safe }}
-{# Supports boolean flags (async, defer) and module type: #}
-{{ fsy.js('/js/main.js', { defer: true, type: 'module' }) | safe }}
-{# Outputs: <script src="/js/main.js?v=1.0.0" defer type="module"></script> #}
-
-{# 4. Image tag helper #}
-{{ fsy.img('/images/logo.png', 'Company Logo') | safe }}
-{# With attributes (loading, class, width, height): #}
-{{ fsy.img('/images/hero.jpg', 'Hero Banner', { loading: 'lazy', class: 'w-full rounded', width: 1200, height: 600 }) | safe }}
-```
-
-#### Programmatic Asset Manager API
-
-You can also import and use `AssetManager` directly:
-
-```javascript
-const { AssetManager, configureAssets, getAssetManager } = require('webspresso');
-
-// Configure global manager
-configureAssets({
-  version: '2.0.0',
-  prefix: 'https://cdn.example.com'
-});
-
-const manager = getAssetManager();
-console.log(manager.asset('/css/style.css')); // -> 'https://cdn.example.com/css/style.css?v=2.0.0'
-```
-
-**Returns:** `{ app, nunjucksEnv, pluginManager, authMiddleware }` — `authMiddleware` is `null` when `auth` was not passed.
-
-### Authentication (session)
-
-Optional **session-based** auth lives under **`webspresso/core/auth`**: **`createAuth`**, **`quickAuth`**, **`hash`** / **`verify`**, **`setupAuthMiddleware`**, **`createRememberTokensTable`**, and policy helpers. Pass the manager to **`createApp({ auth })`** so routes can use **`middleware: ['auth']`** or **`['guest']`** and handlers can call **`req.auth.attempt()`**, **`req.auth.logout()`**, **`req.auth.can()`**, etc.
-
-The **admin panel** plugin uses its **own** session and `/api/auth/*` routes (`req.session.adminUser`) — it is separate from **`createApp({ auth })`**.
-
-For integration patterns (remember-me table, `setupRoutes`, file-router ordering), see **[`doc/index.html#authentication`](doc/index.html#authentication)**.
-
-## Plugin System
-
-Webspresso has a built-in plugin system with version control and dependency management.
-
-**Error handling:** On plugin errors (missing dependencies, version mismatch, `register()` or `onRoutesReady()` failure), the app does not crash; only a `console.warn` is logged and other plugins continue to run.
-
-### Using Plugins
-
-```javascript
-const { createApp } = require('webspresso');
-const { sitemapPlugin, analyticsPlugin, dashboardPlugin } = require('webspresso/plugins');
-
-const { app } = createApp({
-  pagesDir: './pages',
-  viewsDir: './views',
-  plugins: [
-    dashboardPlugin(),  // Dev dashboard at /_webspresso
-    sitemapPlugin({
-      hostname: 'https://example.com',
-      exclude: ['/admin/*', '/api/*'],
-      i18n: true,
-      locales: ['en', 'de']
-    }),
-    analyticsPlugin({
-      google: {
-        measurementId: 'G-XXXXXXXXXX',
-        verificationCode: 'xxxxx'
-      },
-      yandex: {
-        counterId: '12345678',
-        verificationCode: 'xxxxx'
-      },
-      bing: {
-        uetId: '12345678',
-        verificationCode: 'xxxxx'
-      }
-    })
-  ]
-});
-```
-
-### Built-in Plugins
-
-**Dashboard Plugin:**
-- Development dashboard at `/_webspresso`
-- Monitor all routes (SSR pages and API endpoints)
-- View loaded plugins and configuration
-- Filter and search routes
-- Only active in development mode (disabled in production)
-
 ```javascript
-const { dashboardPlugin } = require('webspresso/plugins');
-
-const { app } = createApp({
-  pagesDir: './pages',
-  plugins: [
-    dashboardPlugin()  // Available at /_webspresso in dev mode
-  ]
-});
+// pages/index.js
+module.exports = {
+  async load({ req, ctx }) {
+    return {
+      title: 'Home Page',
+      user: req.user || null,
+    };
+  },
+};
 ```
 
-Options:
-- `path` - Custom dashboard path (default: `/_webspresso`)
-- `enabled` - Force enable/disable (default: auto based on NODE_ENV)
-
-**Redirect plugin:**
-- Runs in `register()` **before** file-based routes, so configured paths override SSR pages.
-- Rules: `from` (string or `RegExp`), `to` (path or URL), optional `status` (301/302/303/307/308), optional `methods` (`'*'` or a list; default plugin methods are `GET` and `HEAD` only).
-- `preserveQuery` (default `true`) appends the request query when `to` has no `?`. External `to` values require `allowExternal: true`.
-
+### 3. Validated JSON API Endpoint (`pages/api/greet.post.js`)
 ```javascript
-const { redirectPlugin } = require('webspresso/plugins');
+module.exports = {
+  schema({ z }) {
+    return {
+      body: z.object({
+        name: z.string().min(2),
+      }),
+    };
+  },
 
-redirectPlugin({
-  rules: [
-    { from: '/old-blog', to: '/blog', status: 301 },
-    { from: /^\/wiki\/(.*)$/, to: '/docs' },
-  ],
-});
+  async handler(req, res) {
+    // req.input is typed and validated by Zod
+    const result = await req.service('user.greet', req.input.body);
+    res.json(result);
+  },
+};
 ```
 
-**Sitemap Plugin:**
-- Generates `/sitemap.xml` from routes automatically
-- **Dynamic Database Content**: Generate URLs from database records
-- Excludes dynamic routes and API endpoints
-- Supports i18n with hreflang tags
-- Generates `/robots.txt`
-- Configurable caching for performance
-
-```javascript
-sitemapPlugin({
-  hostname: 'https://example.com',
-  db, // Database instance
-  dynamicSources: [
-    {
-      model: 'Post',                    // Model name
-      urlPattern: '/blog/:slug',        // URL pattern
-      lastmodField: 'updated_at',       // Field for lastmod
-      filter: (r) => r.published,       // Filter records
-      priority: 0.9,
-    },
-    {
-      // Custom query function
-      query: async (db) => {
-        return db.getRepository('Product')
-          .query()
-          .where('active', true)
-          .list();
-      },
-      urlPattern: '/products/:slug',
-    },
-  ],
-})
-```
+---
 
-**Analytics Plugin:**
-- Google Analytics (GA4) and Google Ads
-- Google Tag Manager
-- Yandex.Metrika
-- Microsoft/Bing UET
-- Facebook Pixel
-- Verification meta tags for all services
+## 📚 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.
 
-Template helpers from analytics plugin:
+---
 
-```njk
-<head>
-  {{ fsy.verificationTags() | safe }}
-  {{ fsy.analyticsHead() | safe }}
-</head>
-<body>
-  {{ fsy.analyticsBodyOpen() | safe }}
-  ...
-</body>
-```
+## 🤖 For AI Coding Agents
 
-Individual helpers: `gtag()`, `gtm()`, `gtmNoscript()`, `yandexMetrika()`, `bingUET()`, `facebookPixel()`, `allAnalytics()`
+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.
 
-**Admin Panel Plugin:**
-- Modular admin panel with SPA (Mithril.js)
-- Model CRUD UI (auto-generated from ORM)
-- Extensible via custom pages, menu items, API routes, and dashboard widgets
-- Other plugins (e.g. site-analytics) can register their own admin pages
-
-```javascript
-const { adminPanelPlugin } = require('webspresso/plugins');
-
-const { app } = createApp({
-  pagesDir: './pages',
-  plugins: [
-    adminPanelPlugin({
-      db,
-      path: '/_admin',           // Admin URL (default: /_admin)
-      auth: authManager,         // Optional: for user management
-      userManagement: { enabled: true, model: 'User' },
-    })
-  ]
-});
-```
-
-Options:
-- `db` (required) - Database instance
-- `path` - Admin panel path (default: `/_admin`)
-- `auth` - Same **`AuthManager`** instance as **`createApp({ auth })`** when you use **`userManagement`** — enables **Active Sessions** / revoke APIs if **`rememberTokens`** (remember-me) is configured; optional for user CRUD-only
-- `userManagement` - Site-user admin UI (`enabled`, `model` matching ORM user table, optional `fields` map). SPA routes: `/_admin/users`, `/_admin/users/new`, …; APIs: `/_admin/api/users*`. Admin staff still use **`admin_users`** / `/_admin` login; this is separate from **`req.user`** on the public site
-- `configure` - Callback `(registry) => void` for manual setup
-
-See **`doc/index.html#admin-user-management`** and **Session authentication** in **`.agents/skills/webspresso-usage/REFERENCE-framework.md`** for the split between **`adminUser`** and **`createApp({ auth })`**.
-
-**3-State Table Column Sorting & Configuration:**
-
-Admin Panel table headers support interactive 3-state column sorting:
-- **State 1 (`Unsorted`)**: Default state (`↕` icon).
-- **State 2 (`ASC`)**: 1st click sorts ascending (`▲` icon, `?sort=col&order=asc`).
-- **State 3 (`DESC`)**: 2nd click sorts descending (`▼` icon, `?sort=col&order=desc`).
-- **State 4 (`Unsorted`)**: 3rd click clears sorting and reverts to default primary key ordering.
-
-Configuration options:
-- **Column-level**: Standard scalar columns (`string`, `number`, `boolean`, `timestamp`) are sortable by default. Disable or enable per column:
-  ```javascript
-  schema: zdb.schema({
-    name: zdb.string({ sortable: true }),
-    secret_notes: zdb.text().config({ sortable: false }), // or zdb.text({ sortable: false })
-  })
-  ```
-- **Model-level**: Restrict sortable columns or disable sorting completely on a model in `defineModel`:
-  ```javascript
-  admin: {
-    enabled: true,
-    sortableColumns: ['name', 'price'], // Only name and price are sortable
-    // Or disable all sorting:
-    // sortable: false,
-  }
-  ```
-
-
-
-**Custom Admin Pages (registerModule):**
-
-Plugins can add custom admin pages using `registerModule` (or `registerPageDir`) in `onRoutesReady`:
-
-```javascript
-// In your plugin's onRoutesReady(ctx)
-const adminApi = ctx.usePlugin('admin-panel');
-if (adminApi) {
-  // Option 1: File-based registration with auto Layout wrapping
-  adminApi.registerModule({
-    id: 'my-module',
-
-    pages: [{
-      id: 'reports',
-      title: 'Reports',
-      path: '/reports',
-      icon: 'chart',
-      description: 'View reports',
-      componentFile: path.join(__dirname, 'admin/reports.js'), // JS component file
-      layout: true, // Auto-wraps view in Admin Layout (default: true)
-    }],
-
-    menu: [{ id: 'reports', label: 'Reports', path: '/reports', icon: 'chart', order: 5 }],
-
-    api: {
-      prefix: '/reports',
-      routes: [
-        { method: 'get', path: '/summary', handler: getSummaryHandler, auth: true },
-      ],
-    },
-  });
-
-  // Option 2: Folder-based auto registration (dir containing page.json + component.js)
-  adminApi.registerPageDir(path.join(__dirname, 'admin/pages'));
-}
-```
-
-| Field | Description |
-|-------|-------------|
-| `id` | Unique module identifier (required) |
-| `pages` | Custom admin pages (`id`, `title`, `path`, `icon`, `description`, `url`, `iframeUrl`, `html`, `htmlFile`, `componentFile`, `component`, `layout`) |
-| `pagesDir` | Path to directory containing page folders/configs for automatic discovery |
-| `menu` | Sidebar menu items (`id`, `label`, `path`, `icon`, `order`) |
-| `menuGroups` | Collapsible menu groups (`id`, `label`, `order`) |
-| `api` | API routes (`prefix`, `routes`: `method`, `path`, `handler`, `auth`) |
-| `widgets` | Dashboard widgets (`id`, `title`, `dataLoader`) |
-| `scripts` | External script URLs, script objects, or inline scripts injected into SSR Admin Panel (`registerScript`) |
-| `styles` | External stylesheet URLs or inline CSS injected into SSR Admin Panel (`registerStyle`) |
-
-Pages support JavaScript client components (`componentFile`, `pagesDir`, `component`), external URLs (`url` or `iframeUrl` inside `<iframe>`), as well as **native custom HTML pages** (`html` or `htmlFile` for local HTML files like EUIX Engine apps, Vue, or Alpine). HTML pages render directly in the page DOM with full Tailwind CSS styling, dark mode, and script execution without iframe overhead. Set `iframe: true` to isolate in an iframe if needed. By default (`layout: true`), custom page views are automatically wrapped in the Admin Layout with Breadcrumbs. Set `layout: false` for full-screen / custom canvas pages.
-
-**Example component file (`admin/reports.js`):**
-
-```javascript
-// Clean Mithril.js component object (no manual m(Layout, ...) needed!)
-({
-  oninit: async (vnode) => {
-    vnode.state.data = [];
-    try {
-      const res = await api.get('/reports/summary');
-      vnode.state.data = res.data || [];
-      m.redraw();
-    } catch (err) {
-      console.error('Failed to load report data:', err);
-    }
-  },
-  view: (vnode) => {
-    const data = vnode.state.data || [];
-    return m('div.space-y-4', [
-      m('h1.text-2xl.font-bold.text-gray-900.dark:text-slate-100', 'Report Summary'),
-      m('p.text-gray-600.dark:text-slate-400', `Total records: ${data.length}`),
-    ]);
-  }
-})
-```
-
-
-
-**Manual registry API** (alternative to registerModule):
-
-```javascript
-adminPanelPlugin({
-  db,
-  configure(registry) {
-    registry.registerPage('custom', { title: 'Custom', path: '/custom', icon: 'tool' });
-    registry.registerClientComponent('custom', 'window.__customPages["custom"] = { view: () => m("p","Hi") };');
-    registry.registerMenuItem({ id: 'custom', label: 'Custom', path: '/custom', icon: 'tool' });
-  },
-})
-```
-
-### Data exchange plugin (`dataExchangePlugin`)
-
-- **Admin session only** — same `requireAuth` / `req.session.adminUser` as the admin panel; paths live under your admin prefix (default `/_admin`).
-- **Excel export** (`.xlsx`) for models with `admin.enabled`; record selection matches the built-in JSON/CSV export (`ids`, `selectAll`, `filters` via query or POST body).
-- **Import** — `multipart/form-data` field `file` (`.csv` or `.xlsx`); query/body `mode=insert|upsert`, `upsertKey` (default primary key). Rows are validated through the ORM (`repository.create` / `update`). Hidden columns are excluded; caps: `maxRows`, `maxFileBytes`.
-- **UI** — when the plugin is loaded, the admin model list adds **Export Excel**, **Import**, and bulk **Export Excel** (alongside the existing JSON/CSV export actions). Registers bulk action `export-xlsx` for download URLs.
-- **Dependencies** — implemented with `exceljs` and `csv-parse` (declared on the `webspresso` package).
-
-Register **after** `adminPanelPlugin` so session middleware and the admin registry exist; use the **same** `db` and `adminPath`:
-
-```javascript
-const { adminPanelPlugin, dataExchangePlugin } = require('webspresso/plugins');
-
-const { app } = createApp({
-  pagesDir: './pages',
-  db,
-  plugins: [
-    adminPanelPlugin({ db, path: '/_admin' }),
-    dataExchangePlugin({
-      db,
-      adminPath: '/_admin',
-      maxRows: 10_000,
-      maxFileBytes: 10 * 1024 * 1024,
-    }),
-  ],
-});
-```
-
-Options:
-- `db` — database instance (defaults to `ctx.db` in `onRoutesReady` if omitted but `createApp({ db })` was set)
-- `adminPath` — must match the admin panel path (default `/_admin`)
-- `enabled` — set `false` to skip registering routes (default `true`)
-- `maxRows` — export and import row limit (default `10000`)
-- `maxFileBytes` — multipart upload limit (default 10 MiB)
-
-API (all require admin cookie):
-- `GET|POST ${adminPath}/api/data-exchange/export/:model` — spreadsheet download
-- `POST ${adminPath}/api/data-exchange/import/:model` — import summary `{ success, created, updated, failed, errors: [{ row, message }] }`
-
-**Site Analytics Plugin:**
-- Self-hosted page view analytics (no external services required)
-- Automatic page view tracking via Express middleware
-- Bot detection (40+ patterns: Googlebot, GPTBot, curl, etc.)
-- Country detection (CDN headers, Accept-Language fallback)
-- Admin panel dashboard with Chart.js visualizations
-- Privacy-first: IP addresses are hashed, no cookies required
-
-```javascript
-const { siteAnalyticsPlugin, adminPanelPlugin } = require('webspresso/plugins');
-
-const { app } = createApp({
-  pagesDir: './pages',
-  plugins: [
-    adminPanelPlugin({ db }),
-    siteAnalyticsPlugin({
-      db,
-      excludePaths: ['/health', '/favicon.ico'],
-      trackBots: true,  // Record bot visits separately (default: true)
-    }),
-  ]
-});
-```
-
-Admin panel analytics page includes:
-- **Summary cards**: Total views, unique visitors, unique pages, sessions
-- **Views over time**: Line chart (Chart.js) with daily views/visitors/sessions
-- **Bot activity**: Bot request counts with horizontal bar visualization
-- **Top pages**: Most viewed pages sorted by view count
-- **Recent activity**: Latest page views with country flags and timestamps
-- **Country stats**: Country breakdown with flag emojis and bar charts
-- **Date filtering**: Last 7, 30, or 90 days toggle
-
-Options:
-- `db` (required) - Database instance
-- `excludePaths` - Additional paths to exclude from tracking (admin, API, and static files are auto-excluded)
-- `trackBots` - Whether to record bot visits (default: `true`)
-- `tableName` - Custom table name (default: `analytics_page_views`)
-
-The `analytics_page_views` table is automatically created on first request.
-
-**Audit log plugin:**
-- Records successful (`2xx`) admin panel model mutations: `create`, `update`, `delete`, `restore` on `${adminPath}/api/models/:model/records…`
-- Actor from `req.session.adminUser` after login; optional IP / user-agent; update metadata stores changed field names only (not full body)
-- `GET ${adminPath}/api/audit-logs` with pagination and filters (`page`, `perPage`, `model`, `action`, `from`, `to`) — use from custom admin pages or the bundled Mithril list (`includeDefaultPage` default `true`)
-- Run `webspresso db:migrate` after adding the migration (see `plugins/audit-log/migration-template.js` or the example under `migrations/`). Prune old rows with the CLI (recommended on a schedule):
-
-```bash
-npx webspresso audit:prune --days 90
-```
-
-```javascript
-const { adminPanelPlugin, auditLogPlugin } = require('webspresso/plugins');
-
-const { app } = createApp({
-  pagesDir: './pages',
-  plugins: [
-    adminPanelPlugin({ db }),
-    auditLogPlugin({
-      db,
-      // adminPath: '/_admin', // must match admin panel `path`
-      // tableName: 'audit_logs',
-      // includeDefaultPage: true,
-      // apiPrefix: '/audit-logs',
-    }),
-  ],
-});
-```
-
-Programmatic API (other plugins): `ctx.usePlugin('audit-log')` exposes `queryLogs`, `purgeAuditLogs`, and `getMigrationTemplate()`.
-
-**Email plugin:**
-- Sends email via **Nodemailer** with **MJML** templates (`{{variable}}` interpolation)
-- Template sources: `templatesDir` (`*.mjml`, **Node.js only** — skipped on edge/workers), `templates` map with inline `{ mjml }`, runtime `registerTemplate`, or inline `send({ mjml, html, data })`
-- Transport: `transport`, `smtp`, or env (`SMTP_HOST`, `SMTP_PORT`, `SMTP_USER`, `SMTP_PASS`, `SMTP_SECURE`, `MAIL_FROM`)
-- Optional DB logging to `email_logs` when `db` is passed; prune with `webspresso email:prune --days 90`
-- **Build:** `webspresso build` embeds `emails/*.mjml` (config `emailDir`) + bundled auth templates into `manifest.emailTemplates` and `email-templates.mjs` (Cloudflare). Use `emailPlugin({ manifest })` or `emailPlugin({ emailTemplates: manifest.emailTemplates })` on edge.
-- Admin page at `/_admin/email` (test send, preview, SMTP verify, logs) when `adminPanelPlugin` is loaded
-- Optional **auth bridge**: `authEmails: { enabled: true }` sends password-reset / email-verification mails and can register `POST /api/auth/forgot-password`, `/reset-password`, `/verify-email`, `/resend-verification`
-
-```javascript
-const { quickAuth, createAuthTokensTable } = require('webspresso/core/auth');
-const { adminPanelPlugin, emailPlugin } = require('webspresso/plugins');
-
-const auth = quickAuth({ db, authTokens: true });
-await createAuthTokensTable(db.knex);
-
-const { app, pluginManager } = createApp({
-  pagesDir: './pages',
-  db,
-  auth,
-  plugins: [
-    emailPlugin({
-      db,
-      auth,
-      templatesDir: './emails',
-      smtp: {
-        host: process.env.SMTP_HOST,
-        port: 587,
-        auth: { user: process.env.SMTP_USER, pass: process.env.SMTP_PASS },
-      },
-      defaults: { from: process.env.MAIL_FROM },
-      authEmails: {
-        enabled: true,
-        baseUrl: process.env.BASE_URL,
-        registerRoutes: true,
-      },
-    }),
-    adminPanelPlugin({ db }),
-  ],
-});
-
-// From a route handler or another plugin:
-await pluginManager.getPluginAPI('email').sendTemplate('welcome', {
-  to: 'user@example.com',
-  subject: 'Welcome',
-  data: { name: 'Ali' },
-});
-```
-
-Programmatic API: `ctx.usePlugin('email')` exposes `send`, `sendTemplate`, `preview`, `registerTemplate`, `listTemplates`, `verifyConnection`, `queryLogs`, `purgeLogs`, `getMigrationTemplate()`.
-
-**ORM cache admin plugin:**
-- Depends on **`adminPanelPlugin`** and a database instance created with **`createDatabase({ cache: true | { … } })`** so **`db.cache`** is non-null
-- Registers an **ORM Cache** admin page (metrics, full purge, per-model invalidation, reset counters) backed by **`db.cache`**
-- If `db.cache` is disabled, the plugin logs a warning and skips registration
-
-```javascript
-const { adminPanelPlugin, ormCacheAdminPlugin } = require('webspresso');
-
-const { app } = createApp({
-  pagesDir: './pages',
-  plugins: [
-    adminPanelPlugin({ db }),
-    ormCacheAdminPlugin({ db }),
-  ],
-});
-```
-
-**reCAPTCHA plugin:**
-- Google reCAPTCHA **v2** (checkbox) or **v3** (score): server verification via `https://www.google.com/recaptcha/api/siteverify` (no extra npm dependency; Node 18+ `fetch`)
-- Registers CSP entries for Google scripts/iframes; Nunjucks helpers: `recaptchaScript`, `recaptchaWidget` (v2), `recaptchaV3Token` (hidden input + execute for v3 — use with `version: 'v3'` and `recaptchaScript` loads `api.js?render=siteKey`)
-- Secret key: `options.secretKey` or env `RECAPTCHA_SECRET_KEY` (never expose to templates)
-
-```javascript
-const {
-  recaptchaPlugin,
-  createRecaptchaMiddleware,
-  resolveRecaptchaMiddlewareParams,
-} = require('webspresso/plugins/recaptcha');
-
-const recaptchaConfig = {
-  siteKey: process.env.RECAPTCHA_SITE_KEY,
-  secretKey: process.env.RECAPTCHA_SECRET_KEY,
-  version: 'v2', // or 'v3'
-  minScore: 0.5,
-  expectedAction: 'contact', // v3 verification only
-  defaultV3Action: 'submit', // for recaptchaV3Token helper
-};
-
-const { app } = createApp({
-  pagesDir: './pages',
-  plugins: [recaptchaPlugin(recaptchaConfig)],
-  middlewares: {
-    recaptcha: createRecaptchaMiddleware({
-      ...resolveRecaptchaMiddlewareParams(recaptchaConfig),
-      bodyField: 'g-recaptcha-response',
-    }),
-  },
-});
-```
-
-**File-based API** (`pages/api/...post.js`): use the named middleware instead of duplicating verification in the handler; on success, `req.recaptcha` contains a short summary of Google’s response.
-
-```javascript
-// pages/api/contact.post.js
-module.exports = async function post(req, res) {
-  // recaptcha middleware already returned 400 if token invalid
-  return res.json({ ok: true, hostname: req.recaptcha.hostname });
-};
-
-module.exports.middleware = ['recaptcha'];
-```
-
-Optional: after `createApp`, use `pluginManager.getPluginAPI('recaptcha').createMiddleware({ bodyField: '...' })` to override plugin defaults and attach to the `app.use` chain (after body parsers).
-
-Low-level usage (without middleware): import `verifyRecaptcha` / `getRemoteIp` from `webspresso/plugins/recaptcha/verify`.
-
-**SEO Checker Plugin:**
-- Client-side SEO analysis tool (inspired by django-check-seo)
-- Integrated with dev toolbar
-- 40+ SEO checks across 7 categories
-- Real-time analysis with score calculation
-- Only active in development mode
-
-```javascript
-const { seoCheckerPlugin } = require('webspresso/plugins');
-
-const { app } = createApp({
-  pagesDir: './pages',
-  plugins: [
-    seoCheckerPlugin({
-      settings: {
-        titleLength: [30, 60],        // Min/max title length
-        descriptionLength: [50, 160], // Min/max description length
-        minContentWords: 300,         // Minimum content words
-        minInternalLinks: 1,          // Minimum internal links
-        minExternalLinks: 1,          // Minimum external links
-        maxUrlLength: 75,             // Maximum URL length
-        maxUrlDepth: 3                // Maximum URL depth
-      }
-    })
-  ]
-});
-```
-
-SEO Check Categories:
-| Category | Checks |
-|----------|--------|
-| **Meta** | Title, Description, Canonical, Viewport, Robots, Charset, Lang |
-| **Headings** | H1 existence, Single H1, Hierarchy, Non-empty headings |
-| **Content** | Word count, Paragraphs, Keyword usage, Keywords early |
-| **Links** | Internal links, External links, Nofollow, Anchor text |
-| **Images** | Alt text, Descriptive alt, Dimensions, Lazy loading |
-| **Structured** | Open Graph, Twitter Card, JSON-LD, Hreflang |
-| **URL** | Length, Depth, Readability, HTTPS |
-
-The SEO Checker panel appears as a floating widget and can be opened via:
-- Dev toolbar "SEO Check" button
-- Floating toggle button (🔍) in bottom-right corner
-
-**Basic Auth Plugin:**
-- Zero-dependency HTTP Basic Authentication (RFC 7617) with timing-safe password verification (`crypto.timingSafeEqual`).
-- Can protect the entire application globally or expose named route middleware (`middleware: ['basicAuth']`).
-
-```javascript
-const { basicAuthPlugin } = require('webspresso/plugins');
-
-const { app } = createApp({
-  pagesDir: './pages',
-  plugins: [
-    basicAuthPlugin({
-      global: false, // Set to true to protect the whole app
-      users: {
-        admin: 'supersecret',
-      },
-      realm: 'Protected Area',
-    }),
-  ],
-});
-```
-
-**Realtime Layer & Plugin:**
-- Framework-agnostic, plugin-based, and adapter-supported realtime layer (`core/realtime` and `plugins/realtime`).
-- Adapters for **Generic WebSocket**, **SSE (Server-Sent Events)**, and **Socket.IO**.
-- Universal API for browsers and SSR safety (never initializes network connections during server-side rendering).
-- Built-in exponential backoff reconnection with jitter, multi-strategy authentication (token, cookie, custom), auto-recovery of subscriptions on reconnect, and token sanitization.
-
-```javascript
-const { createApp } = require('webspresso');
-const { realtimePlugin, websocket } = require('webspresso/plugins');
-
-// 1. App Plugin Setup
-const { app } = createApp({
-  plugins: [
-    realtimePlugin({
-      adapter: websocket({ url: '/realtime' }),
-      auth: { strategy: 'cookie' },
-      autoConnect: true,
-    }),
-  ],
-});
-
-// 2. Subscription & RPC
-const sub = app.realtime.subscribe('project:123', { role: 'editor' }, {
-  connected() {
-    console.log('Connected to project:123');
-  },
-  received(data) {
-    console.log('Live message:', data);
-  },
-});
-
-sub.perform('user_typing', { userId: 42, isTyping: true });
-sub.send({ text: 'Hello team!' });
-
-// 3. Standalone Client Usage (with Token Auth & Refresh)
-const { realtime, websocket } = require('webspresso');
-
-const client = realtime({
-  adapter: websocket({ url: 'wss://api.example.com/realtime' }),
-  auth: {
-    strategy: 'token',
-    getToken: async () => localStorage.getItem('token'),
-    refreshToken: async () => {
-      const res = await fetch('/api/auth/refresh', { method: 'POST' });
-      const { token } = await res.json();
-      localStorage.setItem('token', token);
-      return token;
-    },
-    onUnauthorized: (err) => {
-      window.location.href = '/login';
-    },
-  },
-});
-```
-
-### Creating Custom Plugins
-
-```javascript
-const myPlugin = {
-  name: 'my-plugin',
-  version: '1.0.0',
-  
-  // Optional: depend on other plugins
-  dependencies: {
-    'analytics': '^1.0.0'
-  },
-  
-  // Optional: expose API for other plugins
-  api: {
-    getData() { return this.data; }
-  },
-  
-  // Called during registration
-  register(ctx) {
-    // Access Express app
-    ctx.app.use((req, res, next) => next());
-    
-    // Access database (when createApp({ db }) is used)
-    if (ctx.db) {
-      // Use ctx.db.getRepository('Model'), ctx.db.knex, etc.
-    }
-    
-    // Add template helpers
-    ctx.addHelper('myHelper', () => 'Hello!');
-    
-    // Add Nunjucks filters
-    ctx.addFilter('myFilter', (val) => val.toUpperCase());
-    
-    // Use other plugins
-    const analytics = ctx.usePlugin('analytics');
-  },
-  
-  // Called after all routes are mounted
-  onRoutesReady(ctx) {
-    // ctx.db available when createApp({ db }) is used
-    // Access route metadata
-    console.log('Routes:', ctx.routes);
-    
-    // Add custom routes
-    ctx.addRoute('get', '/my-route', (req, res) => {
-      res.json({ hello: 'world' });
-    });
-  },
-  
-  // Called before server starts
-  onReady(ctx) {
-    console.log('Server ready!');
-  }
-};
-
-// Use as factory function for configuration
-function myPluginFactory(options = {}) {
-  return {
-    name: 'my-plugin',
-    version: '1.0.0',
-    _options: options,
-    register(ctx) {
-      // ctx.options contains the passed options
-    }
-  };
-}
-```
-
-### Plugin Error Handling
-
-The plugin system does not crash the app on errors; it only logs warnings:
-
-- **Missing dependency**: If a plugin in `dependencies` is not loaded → warning, plugin still loads
-- **Version mismatch**: If a dependent plugin version is incompatible → warning, plugin still loads
-- **Circular dependency**: If two plugins depend on each other → warning, plugins in the cycle are skipped
-- **Duplicate plugin name**: Two plugins with the same name → warning, second one is skipped
-- **`register()` error**: If `register(ctx)` throws → warning, plugin is removed from the registry
-- **`onRoutesReady()` error**: If the hook throws → warning, server stays up
-
-A single faulty plugin does not block the entire application.
-
-## File-Based Routing
-
-### SSR Pages
-
-Create `.njk` files in the `pages/` directory:
-
-| File Path | Route |
-|-----------|-------|
-| `pages/index.njk` | `/` |
-| `pages/about/index.njk` | `/about` |
-| `pages/tools/[slug].njk` | `/tools/:slug` |
-| `pages/docs/[...rest].njk` | `/docs/*` |
-
-### API Routes
-
-Create `.js` files in `pages/api/` with optional method suffixes:
-
-| File Path | Route |
-|-----------|-------|
-| `pages/api/health.get.js` | `GET /api/health` |
-| `pages/api/echo.post.js` | `POST /api/echo` |
-| `pages/api/users/[id].get.js` | `GET /api/users/:id` |
-
-**Basic API Handler:**
-
-```javascript
-// pages/api/health.get.js
-module.exports = async function handler(req, res) {
-  res.json({ status: 'ok' });
-};
-```
-
-**Object export (`handler`, `middleware`, `schema`):**
-
-Use a single export object when you need **named middleware** from `createApp({ middlewares })` and/or a **Zod** `schema`. Order at runtime: **`req.db`** (if configured) → **schema** (`req.input`) → **middleware** chain → **handler**.
-
-```javascript
-// pages/api/search.post.js
-module.exports = {
-  middleware: ['requireAuth'],
-  schema: ({ z }) => ({
-    body: z.object({ q: z.string() }),
-  }),
-  handler: async (req, res) => {
-    const { q } = req.input.body;
-    const results = [];
-    return res.json({ results, q });
-  },
-};
-```
-
-Register `requireAuth` (and any other names) on the app:
-
-```javascript
-createApp({
-  pagesDir: './pages',
-  middlewares: {
-    requireAuth: (req, res, next) => {
-      if (!req.session?.user) return res.status(401).json({ error: 'Unauthorized' });
-      next();
-    },
-  },
-});
-```
-
-### Authentication & JWT Support (`quickAuth`)
-
-Webspresso provides a zero-dependency **Dual Authentication** system (`webspresso/core/auth`):
-- **Session + Cookie**: Stateful auth for browser SSR routes and Admin Panel (`/`, `/_admin`).
-- **JWT + Refresh Token**: Stateless HS256 auth for REST APIs, Mobile Apps, and SPAs (`/api/*`).
-
-```javascript
-// createApp setup with quickAuth
-const { quickAuth } = require('webspresso/core/auth');
-
-const auth = quickAuth({
-  db,
-  userModel: 'User',
-  jwt: {
-    expiresIn: '15m',        // Access token duration (default: 24h)
-    refreshExpiresIn: '30d', // Refresh token duration (default: 30d)
-  },
-});
-
-createApp({
-  pagesDir: './pages',
-  db,
-  auth,
-});
-```
-
-**File-Based API Route Examples (`pages/api/*`):**
-
-```javascript
-// 1. pages/api/auth/login.post.js (Login & Token Generation)
-module.exports = {
-  schema: ({ z }) => ({
-    body: z.object({
-      email: z.string().email(),
-      password: z.string().min(1),
-    }),
-  }),
-  async handler(req, res) {
-    const { email, password } = req.input.body;
-    const user = await req.auth.attempt(email, password);
-    if (!user) return res.status(401).json({ error: 'Invalid credentials' });
-
-    const accessToken = req.auth.generateUserToken(user);
-    const refreshToken = req.auth.generateRefreshToken(user);
-
-    return res.json({ accessToken, refreshToken, user: { id: user.id, email: user.email } });
-  },
-};
-```
-
-```javascript
-// 2. pages/api/auth/refresh.post.js (Token Rotation Endpoint)
-module.exports = {
-  schema: ({ z }) => ({
-    body: z.object({
-      refreshToken: z.string(),
-    }),
-  }),
-  async handler(req, res) {
-    const { refreshToken } = req.input.body;
-    try {
-      const result = await req.auth.refreshAccessToken(refreshToken, { rotate: true });
-      return res.json({ accessToken: result.accessToken, refreshToken: result.refreshToken });
-    } catch (err) {
-      return res.status(401).json({ error: err.message });
-    }
-  },
-};
-```
-
-```javascript
-// 3. pages/api/profile.get.js (Protected REST API Route)
-module.exports = {
-  middleware: ['jwt'],
-  async handler(req, res) {
-    return res.json({ user: req.user, token: req.token });
-  },
-};
-```
-
-**With Schema Validation (same object shape):**
-
-```javascript
-// pages/api/posts.post.js
-module.exports = {
-  schema: ({ z }) => ({
-    body: z.object({
-      title: z.string().min(3).max(100),
-      content: z.string(),
-      tags: z.array(z.string()).optional()
-    }),
-    query: z.object({
-      draft: z.coerce.boolean().default(false)
-    })
-  }),
-
-  async handler(req, res) {
-    // Validated & parsed data available in req.input
-    const { title, content, tags } = req.input.body;
-    const { draft } = req.input.query;
-    
-    // Original req.body, req.query remain untouched
-    res.json({ success: true, title, draft });
-  }
-};
-```
-
-**Schema Options:**
-
-| Key | Description |
-|-----|-------------|
-| `body` | Validates `req.body` (POST/PUT/PATCH) |
-| `params` | Validates route parameters (e.g., `:id`) |
-| `query` | Validates query string parameters |
-| `response` | Response schema (for documentation, not enforced) |
-
-All schemas use [Zod](https://zod.dev) for validation. Invalid requests receive **`400 JSON`**: `{ error: 'Validation Error', issues: [...] }` (no `handler` / `middleware` run).
-
-For **nanoid** route parameters (same alphabet and default length as **`generateNanoid`** / **`zdb.nanoid()`**), use **`z.nanoid()`** on the `z` passed into your API schema (Webspresso extends it; no extra import). Optional: **`z.nanoid(12)`** or **`z.nanoid({ maxLength: 12 })`** (matches **`zdb.nanoid({ maxLength })`**). For scripts or tests outside `schema: ({ z })`, **`zodNanoid(z, size?)`** and **`extendZ(z)`** are exported from `webspresso`.
-
-```javascript
-module.exports = {
-  schema: ({ z }) => ({
-    params: z.object({
-      id: z.nanoid(),                  // default 21 chars
-      shortId: z.nanoid(12),           // numeric length
-      other: z.nanoid({ maxLength: 8 }), // zdb-style options
-    }),
-  }),
-  async handler(req, res) {
-    const { id } = req.input.params;
-    // ...
-  },
-};
-```
-
-**Dynamic Route with Params Validation:**
-
-```javascript
-// pages/api/users/[id].get.js
-module.exports = {
-  schema: ({ z }) => ({
-    params: z.object({
-      id: z.string().uuid()
-    }),
-    query: z.object({
-      fields: z.string().optional()
-    })
-  }),
-
-  async handler(req, res) {
-    const { id } = req.input.params;  // Validated UUID
-    const user = await getUser(id);
-    res.json(user);
-  }
-};
-```
-
-### Route Config
-
-Add a `.js` file alongside your `.njk` file to configure the route:
-
-```javascript
-// pages/tools/index.js
-module.exports = {
-  // Middleware for this route
-  middleware: [(req, res, next) => next()],
-  
-  // Load data for SSR
-  async load(req, ctx) {
-    // ctx.db is available when createApp({ db }) is used
-    if (ctx.db) {
-      const posts = await ctx.db.getRepository('Post').query().limit(10);
-      return { posts };
-    }
-    return { tools: await fetchTools() };
-  },
-  
-  // Override meta tags
-  meta(req, ctx) {
-    return {
-      title: 'Tools',
-      description: 'Developer tools'
-    };
-  },
-  
-  // Route-level hooks
-  hooks: {
-    beforeLoad: async (ctx) => {},
-    afterRender: async (ctx) => {}
-  }
-};
-```
-
-## i18n & Localization
-
-Webspresso features a zero-dependency, ultra-fast internationalization engine built directly on native Node.js `Intl` APIs (`Intl.PluralRules`, `Intl.NumberFormat`, `Intl.DateTimeFormat`, `Intl.RelativeTimeFormat`).
-
-### 1. Global & Route-Specific Translations
-
-Add JSON files to `pages/locales/` for global dictionary entries, or inside any route directory `pages/catalog/locales/` for route-specific overrides:
-
-```json
-// pages/locales/en.json
-{
-  "nav": {
-    "home": "Home",
-    "about": "About"
-  },
-  "cart": {
-    "zero": "Your cart is empty",
-    "one": "You have 1 item in your cart",
-    "other": "You have {{count}} items in your cart"
-  }
-}
-```
-
-### 2. Basic Translation & Interpolation
-
-```nunjucks
-{# Direct function call #}
-<h1>{{ t('nav.home') }}</h1>
-
-{# With parameter interpolation #}
-<p>{{ t('welcome', { name: currentUser.username }) }}</p>
-
-{# With Nunjucks filter #}
-<h1>{{ 'nav.home' | t }}</h1>
-<p>{{ 'welcome' | t({ name: currentUser.username }) }}</p>
-```
-
-### 3. Native Pluralization (`Intl.PluralRules`)
-
-Pass `count` (or `n`, `cardinal`) to automatically select the correct CLDR plural category (`zero`, `one`, `two`, `few`, `many`, `other`) or exact number (`0`, `1`):
-
-```nunjucks
-<p>{{ t('cart', { count: cart.items.length }) }}</p>
-```
-
-You can also use the inline `t.plural()` helper:
-```nunjucks
-<p>{{ t.plural(items.length, { one: '1 item', other: '{{count}} items' }) }}</p>
-```
-
-### 4. Fallback Locales Chain
-
-If a translation key is missing in the requested locale (e.g. `tr`), Webspresso automatically falls back to `DEFAULT_LOCALE` (default: `en`) before returning the key name or default fallback value. Check key existence with `t.has('key')` or `t.exists('key')`.
-
-### 5. Built-in `Intl` Formatters on `t`
-
-Format numbers, currencies, dates, and relative times according to the active locale without external date/number libraries:
-
-```nunjucks
-{# Numbers #}
-<span>{{ t.number(1234567.89) }}</span> {# TR: 1.234.567,89 | EN: 1,234,567.89 #}
-
-{# Currencies #}
-<span>{{ t.currency(199.99, 'TRY') }}</span> {# ₺199,99 #}
-<span>{{ t.currency(49.99, 'USD') }}</span>  {# $49.99 #}
-
-{# Dates #}
-<span>{{ t.date(post.created_at, { dateStyle: 'long' }) }}</span>
-
-{# Relative Time #}
-<span>{{ t.relativeTime(-2, 'day') }}</span> {# "2 days ago" or "2 gün önce" #}
-```
-
-### 6. Language Switcher Helpers
-
-Use `fsy.localeUrl(targetLocale)` to generate a URL with the current page path and query parameters preserved:
-
-```nunjucks
-<a href="{{ fsy.localeUrl('en') }}">English</a>
-<a href="{{ fsy.localeUrl('tr') }}">Türkçe</a>
-<a href="{{ fsy.localeUrl('de') }}">Deutsch</a>
-```
-
-## Template Helpers
-
-The `fsy` object is available in all templates:
-
-```nunjucks
-{# URL helpers #}
-{{ fsy.url('/tools', { page: 1 }) }}
-{{ fsy.fullUrl('/tools') }}
-{{ fsy.route('/tools/:slug', { slug: 'test' }) }}
-
-{# Request helpers #}
-{{ fsy.q('page', 1) }}
-{{ fsy.param('slug') }}
-{{ fsy.hdr('User-Agent') }}
-
-{# Utility helpers #}
-{{ fsy.slugify('Hello World') }}
-{{ fsy.truncate(text, 100) }}
-{{ fsy.prettyBytes(1024) }}
-{{ fsy.prettyMs(5000) }}
-
-{# Date/Time helpers (dayjs) #}
-{{ fsy.dateFormat(post.created_at, 'YYYY-MM-DD HH:mm') }}
-{{ fsy.dateFromNow(post.created_at) }} {# "2 hours ago" #}
-{{ fsy.dateAgo(post.created_at) }} {# "2 hours ago" #}
-{{ fsy.dateUntil(event.date) }} {# "in 2 hours" #}
-{{ fsy.date(post.created_at).format('MMMM D, YYYY') }} {# Full dayjs API #}
-{% if fsy.dateIsBefore(post.created_at, fsy.date()) %}Published{% endif %}
-{{ fsy.dateDiff(post.created_at, fsy.date(), 'day') }} days ago
-{{ fsy.dateAdd(post.created_at, 7, 'day').format('YYYY-MM-DD') }}
-{{ fsy.dateStartOf(post.created_at, 'month').format('YYYY-MM-DD') }}
-
-{# Environment #}
-{% if fsy.isDev() %}Dev mode{% endif %}
-
-{# SEO #}
-{{ fsy.canonical() }}
-{{ fsy.jsonld(schema) | safe }}
-```
-
-## Lifecycle Hooks
-
-### Global Hooks
-
-Create `pages/_hooks.js`:
-
-```javascript
-module.exports = {
-  onRequest(ctx) {},
-  beforeLoad(ctx) {},
-  afterLoad(ctx) {},
-  beforeRender(ctx) {},
-  afterRender(ctx) {},
-  onError(ctx, err) {}
-};
-```
-
-### Hook Execution Order
-
-1. Global `onRequest`
-2. Route `onRequest`
-3. Route `beforeMiddleware`
-4. Route middleware
-5. Route `afterMiddleware`
-6. Route `beforeLoad`
-7. Route `load()`
-8. Route `afterLoad`
-9. Route `beforeRender`
-10. Nunjucks render
-11. Route `afterRender`
-
-## Services Layer
-
-Webspresso includes a lightweight, framework-agnostic **Services Layer** to organize reusable business logic, query flows, and multi-step mutations under `services/`.
-
-Services are automatically discovered from the filesystem and can be invoked from SSR data loaders (`ctx.service()`), API routes (`req.service()`), background jobs, cron, CLI tasks, or other services.
-
-### 1. File Structure & Service Names
-
-Files inside `services/` map directly to dot-separated service names:
-
-```text
-services/
-  user/
-    get.js           → user.get
-    create.js        → user.create
-    profile/
-      get.js         → user.profile.get
-  post/
-    publish.js       → post.publish
-    listByUser.js    → post.listByUser
-  payment/
-    refund.js        → payment.refund
-```
-
-### 2. Service Definition
-
-Services export a handler and an optional input validation schema:
-
-```javascript
-// services/user/get.js
-module.exports = {
-  schema: {
-    id: 'number',
-  },
-
-  async handler({ id }, ctx) {
-    return ctx.db.users.findById(id);
-  },
-};
-```
-
-You can also use the `defineService` helper:
-
-```javascript
-// services/payment/refund.js
-const { defineService } = require('webspresso');
-
-module.exports = defineService({
-  // Zod functional schema syntax ({ z }) with built-in nanoid support
-  schema: ({ z }) => z.object({
-    transactionId: z.string().min(3),
-    amount: z.number().positive(),
-    reason: z.string().optional(),
-  }),
-
-  async handler({ transactionId, amount, reason }, ctx) {
-    // Process refund logic...
-    return { refundId: 'ref_123', transactionId, amount, status: 'succeeded' };
-  },
-});
-```
-
-### 3. Service-to-Service Composition
-
-Services can seamlessly call other services via `ctx.service()` while sharing the exact same request context (`ctx.db`, `ctx.auth`, `ctx.session`, `ctx.user`):
-
-```javascript
-// services/post/publish.js
-module.exports = {
-  schema: ({ z }) => z.object({
-    title: z.string(),
-    authorId: z.number(),
-  }),
-
-  async handler({ title, authorId }, ctx) {
-    const author = await ctx.service('user.get', { id: authorId });
-
-    return ctx.db.posts.create({
-      title,
-      author_id: author.id,
-      published_at: new Date(),
-    });
-  },
-};
-```
-
-> **Circular Call Protection**: Webspresso automatically tracks service call stacks and detects recursive/circular dependencies (e.g. `user.get -> profile.get -> user.get`), throwing an informative `Circular service call detected` error.
-
-### 4. Invoking from SSR & API Routes
-
-In SSR page data loaders (`pages/users/[id].njk`):
-
-```javascript
-// pages/users/[id].js
-module.exports = {
-  async load(req, ctx) {
-    const user = await ctx.service('user.get', { id: Number(req.params.id) });
-    return { user };
-  },
-};
-```
-
-In API routes or Express middleware:
-
-```javascript
-// pages/api/users.post.js
-module.exports = async function(req, res) {
-  const user = await req.service('user.create', req.body);
-  res.status(201).json(user);
-};
-```
-
-### 5. Service Caching & Memoization (`cache: '5m'`)
-
-Services can be cached in-memory with automatic TTL expiration and deterministic key serialization:
-
-```javascript
-// services/product/stats.js
-module.exports = {
-  // Cache result for 5 minutes based on input arguments
-  cache: '5m', // supports '30s', '5m', '1h', '1d', ms numbers, or { ttl: '5m', key: (input) => input.id }
-
-  async handler({ productId }, ctx) {
-    return ctx.db.stats.getProductStats(productId);
-  },
-};
-```
-
-You can invalidate cache keys explicitly on mutations:
-
-```javascript
-// From any service or route:
-ctx.service.invalidate('product.stats', { productId: 42 });
-
-// Or clear all cached entries for a service:
-ctx.service.clearCache('product.stats');
-```
-
-You can also use `memoize` as a standalone utility for any async function:
-
-```javascript
-const { memoize } = require('webspresso');
-
-const fetchRemoteRates = memoize(async () => {
-  return fetchExchangeRates();
-}, { ttl: '10m', maxSize: 100 });
-```
-
-### 6. Timeouts & Database Transactions (`timeout`, `transaction`)
-
-You can protect services against hanging handlers and ensure automatic ACID transaction rollbacks:
-
-```javascript
-// services/order/checkout.js
-module.exports = {
-  // Abort with 504 Gateway Timeout if execution exceeds 5 seconds
-  timeout: '5s',
-
-  // Wrap execution in an automatic Knex transaction (rolls back on any error)
-  transaction: true,
-
-  async handler({ orderId, items }, ctx) {
-    // ctx.trx and ctx.db are automatically bound to the active transaction
-    await ctx.db('orders').where({ id: orderId }).update({ status: 'paid' });
-    await ctx.service('inventory.deduct', { items }); // Nested services reuse the exact same transaction!
-
-    return { orderId, success: true };
-  },
-};
-```
-
-### 7. Authorization & Role Guards (`auth`)
-
-Services can enforce authentication and role-based access control (RBAC) automatically:
-
-```javascript
-// services/admin/billing.js
-module.exports = {
-  // Requires authenticated user with 'admin' or 'finance' role
-  auth: ['admin', 'finance'], // or auth: true (any logged in user) or auth: (user, ctx) => boolean
-
-  async handler(input, ctx) {
-    // Guaranteed to have authorized ctx.user
-    return ctx.db('billing_records').select();
-  },
-};
-```
-
-Throws `UnauthorizedError` (401) when unauthenticated or `ForbiddenError` (403) when role permissions are insufficient.
-
-### 8. Interactive CLI Runner (`webspresso service`)
-
-You can test and run any service directly from the command line without starting the HTTP server:
-
-```bash
-# Interactive selection & prompt mode
-npx webspresso service
-
-# Run a specific service with JSON payload
-npx webspresso service user.get -i '{"id": 42}'
-
-# Run with key=value query string
-npx webspresso service payment.refund -i 'transactionId=tx_123 amount=49.99'
-```
-
-### 7. Programmatic Usage & Testing
-
-You can execute services directly in unit tests or background scripts:
-
-```javascript
-const { createServiceRegistry } = require('webspresso');
-
-const services = createServiceRegistry({ servicesDir: './services' });
-const user = await services.call('user.get', { id: 42 }, { db: mockDb });
-```
-
----
-
-## Environment Variables
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `NODE_ENV` | `development` | Environment |
-| `DEFAULT_LOCALE` | `en` | Default locale |
-| `SUPPORTED_LOCALES` | `en` | Comma-separated locales |
-| `BASE_URL` | `http://localhost:3000` | Base URL for canonical URLs |
-| `DATABASE_URL` | - | Database connection string (for ORM) |
-
-## ORM (Database)
-
-Webspresso includes a minimal, Eloquent-inspired ORM built on Knex with Zod schemas as the single source of truth.
-
-### Quick Start
-
-```javascript
-const { zdb, defineModel, createDatabase } = require('webspresso');
-
-// 1. Define your schema with database metadata
-const UserSchema = zdb.schema({
-  id: zdb.id(),
-  email: zdb.string({ unique: true, index: true }),
-  name: zdb.string({ maxLength: 100 }),
-  status: zdb.enum(['active', 'inactive'], { default: 'active' }),
-  company_id: zdb.foreignKey('companies', { nullable: true }),
-  created_at: zdb.timestamp({ auto: 'create' }),
-  updated_at: zdb.timestamp({ auto: 'update' }),
-  deleted_at: zdb.timestamp({ nullable: true }),
-});
-
-// 3. Define your model
-const User = defineModel({
-  name: 'User',
-  table: 'users',
-  schema: UserSchema,
-  relations: {
-    company: { type: 'belongsTo', model: () => Company, foreignKey: 'company_id' },
-    posts: { type: 'hasMany', model: () => Post, foreignKey: 'user_id' },
-  },
-  scopes: { softDelete: true, timestamps: true },
-});
-
-// 4. Create database (models auto-loaded from ./models directory)
-const db = createDatabase({
-  client: 'pg',
-  connection: process.env.DATABASE_URL,
-  models: './models', // Optional, defaults to './models'
-});
-
-// Models are automatically loaded from models/ directory
-// Use getRepository with model name
-const UserRepo = db.getRepository('User');
-const user = await UserRepo.findById(1, { with: ['company', 'posts'] });
-```
-
-### Schema Helpers (zdb)
-
-The `zdb` helpers wrap Zod schemas with database column metadata:
-
-| Helper | Description | Options |
-|--------|-------------|---------|
-| `zdb.id()` | Primary key (bigint, auto-increment) | |
-| `zdb.uuid()` | UUID primary key | |
-| `zdb.nanoid(opts)` | Nanoid primary key (URL-safe string, stored as VARCHAR) | `maxLength` (default `21`) |
-| `zdb.string(opts)` | VARCHAR column | `maxLength`, `unique`, `index`, `nullable` |
-| `zdb.text(opts)` | TEXT column | `nullable` |
-| `zdb.integer(opts)` | INTEGER column | `nullable`, `default` |
-| `zdb.bigint(opts)` | BIGINT column | `nullable` |
-| `zdb.float(opts)` | FLOAT column | `nullable` |
-| `zdb.decimal(opts)` | DECIMAL column | `precision`, `scale`, `nullable` |
-| `zdb.boolean(opts)` | BOOLEAN column | `default`, `nullable` |
-| `zdb.date(opts)` | DATE column | `nullable` |
-| `zdb.datetime(opts)` | DATETIME column | `nullable` |
-| `zdb.timestamp(opts)` | TIMESTAMP column | `auto: 'create'\|'update'`, `nullable` |
-| `zdb.json(opts)` | JSON column | `nullable` |
-| `zdb.array(itemSchema, opts)` | ARRAY column (stored as JSON) | `nullable` |
-| `zdb.enum(values, opts)` | ENUM column | `default`, `nullable` |
-| `zdb.foreignKey(table, opts)` | Foreign key (bigint) | `referenceColumn`, `nullable` |
-| `zdb.foreignUuid(table, opts)` | Foreign key (uuid) | `referenceColumn`, `nullable` |
-| `zdb.foreignNanoid(table, opts)` | Foreign key (nanoid string) | `referenceColumn`, `nullable`, `maxLength` (must match referenced PK) |
-
-**Nanoid columns:** Migration scaffolding emits `table.string(column, maxLength)`. For a **nanoid primary key**, if you omit the primary key on `repository.create()`, Webspresso fills it with a cryptographically random ID using the same default alphabet as the [`nanoid`](https://github.com/ai/nanoid) package (implemented in-framework; no extra dependency). You can also call **`generateNanoid`** (exported from `webspresso`) anywhere you need the same generator.
-
-### Model Definition
-
-```javascript
-const User = defineModel({
-  name: 'User',           // Model name
-  table: 'users',         // Database table
-  schema: UserSchema,     // Zod schema
-  primaryKey: 'id',       // Primary key column (default: 'id')
-  
-  relations: {
-    // belongsTo: this model has foreign key
-    company: {
-      type: 'belongsTo',
-      model: () => Company,
-      foreignKey: 'company_id',
-    },
-    // hasMany: related model has foreign key
-    posts: {
-      type: 'hasMany',
-      model: () => Post,
-      foreignKey: 'user_id',
-    },
-    // hasOne: like hasMany but returns single record
-    profile: {
-      type: 'hasOne',
-      model: () => Profile,
-      foreignKey: 'user_id',
-    },
-  },
-  
-  scopes: {
-    softDelete: true,     // Use deleted_at column
-    timestamps: true,     // Auto-manage created_at/updated_at
-    tenant: 'tenant_id',  // Multi-tenant column (optional)
-  },
-
-  hidden: ['password_hash', 'api_token'],  // Never expose in API/templates (security)
-});
-```
-
-**Hidden columns:** Add column names to `hidden` so they are never exposed in admin API responses, exports, or when passing to templates. Use for sensitive data like `password_hash`, `api_token`, `secret_key`. The admin panel will exclude these from list views and forms automatically.
-
-### Auto-Loading Models
-
-Models are automatically loaded from the `models/` directory when you create a database instance:
-
-```javascript
-// models/User.js
-const { defineModel, zdb } = require('webspresso');
-
-module.exports = defineModel({
-  name: 'User',
-  table: 'users',
-  schema: zdb.schema({
-    id: zdb.id(),
-    email: zdb.string({ unique: true }),
-    name: zdb.string(),
-    created_at: zdb.timestamp({ auto: 'create' }),
-    updated_at: zdb.timestamp({ auto: 'update' }),
-  }),
-});
-
-// In your application code
-const db = createDatabase({
-  client: 'pg',
-  connection: process.env.DATABASE_URL,
-  models: './models', // Optional, defaults to './models'
-});
-
-// Models are automatically loaded, use getRepository with model name
-const UserRepo = db.getRepository('User');
-```
-
-Pass `db` to `createApp({ db })` to expose it as `ctx.db` in plugin hooks and page `load`/`meta` functions.
-
-**Model File Structure:**
-- Place model files in `models/` directory (or custom path via `config.models`)
-- Each file should export a model defined with `defineModel()`
-- Files starting with `_` are ignored (useful for shared utilities)
-- Models are loaded in alphabetical order
-
-### Repository API
-
-```javascript
-const db = createDatabase({ client: 'pg', connection: '...' });
-const UserRepo = db.getRepository('User'); // Use model name string
-
-// Find by ID (with eager loading)
-const user = await UserRepo.findById(1, { with: ['company', 'posts'] });
-
-// Find one by conditions
-const admin = await UserRepo.findOne({ email: 'admin@example.com' });
-
-// Find all
-const users = await UserRepo.findAll({ with: ['company'] });
-
-// Create
-const newUser = await UserRepo.create({
-  email: 'new@example.com',
-  name: 'New User',
-});
-
-// Create many
-const users = await UserRepo.createMany([
-  { email: 'user1@test.com', name: 'User 1' },
-  { email: 'user2@test.com', name: 'User 2' },
-]);
-
-// Update
-const updated = await UserRepo.update(1, { name: 'Updated Name' });
-
-// Update where
-await UserRepo.updateWhere({ status: 'inactive' }, { status: 'banned' });
-
-// Delete (soft delete if enabled)
-await UserRepo.delete(1);
-
-// Force delete (permanent)
-await UserRepo.forceDelete(1);
-
-// Restore soft-deleted
-await UserRepo.restore(1);
-
-// Count
-const count = await UserRepo.count({ status: 'active' });
-
-// Exists
-const exists = await UserRepo.exists({ email: 'test@example.com' });
-```
-
-### Query Builder
-
-```javascript
-const users = await UserRepo.query()
-  .where({ status: 'active' })
-  .where('created_at', '>', '2024-01-01')
-  .whereIn('role', ['admin', 'moderator'])
-  .whereNotNull('email_verified_at')
-  .orderBy('name', 'asc')
-  .orderBy('created_at', 'desc')
-  .limit(10)
-  .offset(20)
-  .with('company', 'posts')
-  .list();
-
-// First result
-const user = await UserRepo.query()
-  .where({ email: 'admin@example.com' })
-  .first();
-
-// Count
-const count = await UserRepo.query()
-  .where({ status: 'active' })
-  .count();
-
-// Pagination
-const result = await UserRepo.query()
-  .where({ status: 'active' })
-  .orderBy('created_at', 'desc')
-  .paginate(1, 20);  // page 1, 20 per page
-
-// result = { data: [...], total: 150, page: 1, perPage: 20, totalPages: 8 }
-
-// Soft delete scopes
-await UserRepo.query().withTrashed().list();   // Include deleted
-await UserRepo.query().onlyTrashed().list();   // Only deleted
-
-// Multi-tenant
-await UserRepo.query().forTenant(tenantId).list();
-```
-
-`list()`, `first()`, and `paginate()` emit the same `beforeFind` / `afterFind` lifecycle hooks as `findAll` / `findOne` (one `afterFind` per row). `count()` ignores any `.limit()` / `.offset()` on the builder so it returns the full matching row count.
-
-`query().delete()` runs a SQL `DELETE` for matching rows. On models with soft deletes, use `UserRepo.delete(id)` (or equivalent) to set `deleted_at`; the query builder does not convert deletes to soft deletes.
-
-### Transactions
-
-```javascript
-await db.transaction(async (trx) => {
-  const userRepo = trx.getRepository('User'); // Use model name
-  const postRepo = trx.getRepository('Post');
-  
-  const user = await userRepo.create({ email: 'new@test.com', name: 'New' });
-  await postRepo.create({ title: 'First Post', user_id: user.id });
-  
-  // All changes committed on success
-  // Rolled back on error
-});
-```
-
-**ORM reads inside `db.transaction()` always bypass the query cache** (Knex transaction client), so you never serve stale rows mid-transaction.
-
-### ORM query cache (optional)
-
-Enable an in-process, tag-based cache for common read paths. Default provider is in-memory (`createMemoryCacheProvider`); you can pass a custom **`provider`** with the same shape (`get`, `set` with optional `tags` / `ttlMs`, `invalidateTags`, `clear`, `getSizeStats`).
-
-**Turn it on:**
-
-```javascript
-const db = createDatabase({
-  client: 'pg',
-  connection: process.env.DATABASE_URL,
-  models: './models',
-  cache: true, // same as { enabled: true, defaultStrategy: 'auto', memory provider }
-  // cache: {
-  //   enabled: true,
-  //   defaultStrategy: 'auto', // or 'smart'
-  //   memory: { maxEntries: 50_000, defaultTtlMs: undefined },
-  //   // provider: myRedisLikeAdapter,
-  // },
-});
-```
-
-When enabled, **`db.cache`** exposes **`purge()`**, **`invalidateTags(string[])`**, **`invalidateModel('ModelName')`**, **`getMetrics()`**, and **`resetMetrics()`**. When the cache is off, **`db.cache`** is **`null`**.
-
-**Per-model opt-in / strategy** (inherits the database **`defaultStrategy`** when set to `true`):
-
-```javascript
-defineModel({
-  name: 'User',
-  table: 'users',
-  schema: UserSchema,
-  cache: true,              // use db defaultStrategy
-  // cache: 'auto', // invalidate all cached reads for this model on any row change
-  // cache: 'smart', // finer-grained tags: PK reads vs list/collection queries
-  // cache: { strategy: 'smart' },
-  // cache: false,         // never cache this model
-});
-```
-
-**What gets cached:** **`findById`**, **`findOne`**, **`findAll`**, and query builder **`first`**, **`list`**, **`count`**, **`paginate`** — only when the model participates in caching and the read is not on a transaction connection. Some query shapes are never cached (e.g. raw `where` fragments); the layer increments a **`bypassed`** metric for those.
-
-**Invalidation:** Hooks on **`afterCreate`**, **`afterUpdate`**, **`afterDelete`**, and **`afterRestore`** schedule tag invalidation after the Knex transaction commits (when applicable). With **`auto`**, every mutation clears all cache entries tagged for that model. With **`smart`**, creates invalidate collection query tags; updates/deletes target the row’s primary key tag plus collection tags when the record exposes an id (falls back to full-model invalidation if the id is missing). Bulk **`updateWhere`** / query-builder **`update`** / **`delete`** that affect rows call **`invalidateModelAll`** for safety.
-
-**Exports:** **`createMemoryCacheProvider`**, **`OrmCacheLayer`**, and **`createOrmCacheFromConfig`** are available from **`webspresso`** for advanced/testing setups.
-
-### Migrations
-
-**CLI Commands:**
-
-```bash
-# Run pending migrations
-webspresso db:migrate
-
-# Rollback last batch
-webspresso db:rollback
-
-# Rollback all
-webspresso db:rollback --all
-
-# Show migration status
-webspresso db:status
-
-# Create empty migration
-webspresso db:make create_posts_table
-
-# Create migration from model (scaffolding)
-webspresso db:make create_users_table --model User
-
-# Scaffold create-table migrations for all models in models/
-webspresso db:scaffold
-webspresso db:scaffold --only User,Post
-webspresso db:scaffold --dry-run
-
-# Admin Panel Setup
-webspresso admin:setup   # Create admin_users migration
-webspresso admin:list    # List all admin users
-webspresso admin:password  # Reset admin password (interactive or -e -p)
-```
-
-**Admin CLI Commands:**
-
-```bash
-# Create admin_users table migration
-webspresso admin:setup
-
-# List all admin users
-webspresso admin:list
-
-# Reset admin password (interactive: prompts for email and password)
-webspresso admin:password
-
-# Reset with options
-webspresso admin:password -e admin@example.com -p yeni_sifre123
-
-# Use custom config or environment
-webspresso admin:password -c ./webspresso.db.js -E production
-webspresso admin:list -c ./webspresso.db.js
-```
-
-> **Note:** Database config is loaded from `webspresso.db.js` or `knexfile.js` in the project root. Run commands from your project directory.
-
-**Database Config File (`webspresso.db.js`):**
-
-```javascript
-module.exports = {
-  client: 'pg',  // or 'mysql2', 'better-sqlite3'
-  connection: process.env.DATABASE_URL,
-  migrations: {
-    directory: './migrations',
-    tableName: 'knex_migrations',
-  },
-  
-  // Environment overrides
-  production: {
-    connection: process.env.DATABASE_URL,
-    pool: { min: 2, max: 10 },
-  },
-};
-```
-
-**Programmatic API:**
-
-```javascript
-const db = createDatabase({
-  client: 'pg',
-  connection: process.env.DATABASE_URL,
-  migrations: { directory: './migrations' },
-});
-
-await db.migrate.latest();                      // Run pending
-await db.migrate.rollback();                    // Rollback last batch
-await db.migrate.rollback({ all: true });       // Rollback all
-const status = await db.migrate.status();       // Get status
-```
-
-### Migration Scaffolding
-
-Generate migration from model schema:
-
-```javascript
-const { scaffoldMigration } = require('webspresso');
-
-const migration = scaffoldMigration(User);
-// Outputs complete migration file content with:
-// - All columns with proper types
-// - Indexes
-// - Foreign key constraints
-// - Up and down functions
-```
-
-### Supported Databases
-
-Install the appropriate driver as a peer dependency:
-
-```bash
-# PostgreSQL
-npm install pg
-
-# MySQL
-npm install mysql2
-
-# SQLite
-npm install better-sqlite3
-```
-
-### Design Philosophy
-
-| Boundary | Zod's Job | ORM's Job |
-|----------|-----------|-----------|
-| Schema definition | Type shape, validation rules | Column metadata extraction |
-| Input validation | `.parse()` / `.safeParse()` | Never - pass through to Zod |
-| Query building | N/A | Full ownership |
-| Relation resolution | N/A | Eager loading with batch queries |
-| Timestamps/SoftDelete | N/A | Auto-inject on operations |
-
-**N+1 Prevention:** Relations are always loaded with batch `WHERE IN (...)` queries, never with individual queries per record.
-
-### Database Seeding
-
-**CLI Command:**
-
-The easiest way to seed your database is using the CLI command:
-
-```bash
-# Run seeds (requires seeds/index.js)
-webspresso seed
-
-# Setup seed files if they don't exist
-webspresso seed --setup
-
-# Use custom database config
-webspresso seed --config ./custom-db-config.js
-
-# Use different environment
-webspresso seed --env production
-```
-
-The `webspresso seed` command:
-- Automatically loads all models from `models/` directory
-- Generates fake data based on model schemas
-- Creates 10 records per model by default
-- Uses smart field detection for appropriate fake data
-
-**Manual Setup:**
-
-Generate fake data for testing and development using `@faker-js/faker`:
-
-```bash
-npm install @faker-js/faker
-```
-
-**Basic Usage:**
-
-```javascript
-const { faker } = require('@faker-js/faker');
-const db = createDatabase({ /* config */ });
-
-const seeder = db.seeder(faker);
-
-// Generate a single record
-const user = await seeder.factory('User').create();
-
-// Generate multiple records
-const users = await seeder.factory('User').create(10);
-
-// Generate without saving (for testing)
-const userData = seeder.factory('User').make();
-```
-
-**Define Factories with Defaults and States:**
-
-```javascript
-seeder.defineFactory('User', {
-  // Default values
-  defaults: {
-    status: 'pending',
-  },
-  
-  // Custom generators
-  generators: {
-    username: (f) => f.internet.username().toLowerCase(),
-  },
-  
-  // Named states for variations
-  states: {
-    admin: { role: 'admin', status: 'active' },
-    verified: (f) => ({
-      status: 'verified',
-      verified_at: f.date.past().toISOString(),
-    }),
-  },
-});
-
-// Use states
-const admin = await seeder.factory('User').state('admin').create();
-const verified = await seeder.factory('User').state('verified').create();
-```
-
-**Smart Field Detection:**
-
-The seeder automatically generates appropriate fake data based on column names:
-
-| Field Name Pattern | Generated Data |
-|-------------------|----------------|
-| `email`, `*_email` | Valid email address |
-| `name`, `first_name`, `last_name` | Person names |
-| `username` | Username |
-| `title` | Short sentence |
-| `content`, `body`, `description` | Paragraphs |
-| `slug` | URL-safe slug |
-| `phone`, `tel` | Phone number |
-| `address`, `city`, `country` | Location data |
-| `price`, `amount`, `cost` | Decimal numbers |
-| `*_url`, `avatar`, `image` | URLs |
-
-**Override and Custom Generators:**
-
-```javascript
-const user = await seeder.factory('User')
-  .override({ email: 'test@example.com' })
-  .generators({
-    code: (f) => `USR-${f.string.alphanumeric(8)}`,
-  })
-  .create();
-```
-
-**Batch Seeding:**
-
-```javascript
-// Seed multiple models at once
-const results = await seeder.run([
-  { model: 'Company', count: 5 },
-  { model: 'User', count: 20, state: 'active' },
-  { model: 'Post', count: 50 },
-]);
-
-// Access results
-console.log(results.Company); // Array of 5 companies
-console.log(results.User);    // Array of 20 users
-```
-
-**Cleanup:**
-
-```javascript
-// Truncate specific tables
-await seeder.truncate('User');
-await seeder.truncate(['User', 'Post']);
-
-// Clear all registered model tables
-await seeder.clearAll();
-```
-
-### Schema Explorer Plugin
-
-A plugin that exposes ORM schema information via API endpoints. Useful for frontend code generation, documentation, or admin tools.
-
-**Setup:**
-
-```javascript
-const { createApp, schemaExplorerPlugin } = require('webspresso');
-
-const app = createApp({
-  plugins: [
-    schemaExplorerPlugin({
-      path: '/_schema',           // Endpoint path (default: '/_schema')
-      enabled: true,              // Force enable (default: auto based on NODE_ENV)
-      exclude: ['Secret'],        // Exclude specific models
-      includeColumns: true,       // Include column metadata
-      includeRelations: true,     // Include relation metadata
-      includeScopes: true,        // Include scope configuration
-      authorize: (req) => {       // Custom authorization
-        return req.headers['x-api-key'] === 'secret';
-      },
-    }),
-  ],
-});
-```
-
-**Endpoints:**
-
-- `GET /_schema` - List all models
-- `GET /_schema/:modelName` - Get single model details
-- `GET /_schema/openapi` - Export in OpenAPI 3.0 schema format
-
-**Example Response (`GET /_schema`):**
-
-```json
-{
-  "meta": {
-    "version": "1.0.0",
-    "generatedAt": "2024-01-01T12:00:00.000Z",
-    "modelCount": 2
-  },
-  "models": [
-    {
-      "name": "User",
-      "table": "users",
-      "primaryKey": "id",
-      "columns": [
-        { "name": "id", "type": "bigint", "primary": true, "autoIncrement": true },
-        { "name": "email", "type": "string", "unique": true },
-        { "name": "company_id", "type": "bigint", "references": "companies" }
-      ],
-      "relations": [
-        { "name": "company", "type": "belongsTo", "relatedModel": "Company", "foreignKey": "company_id" }
-      ],
-      "scopes": { "softDelete": true, "timestamps": true, "tenant": null }
-    }
-  ]
-}
-```
-
-**Plugin API (programmatic usage):**
-
-```javascript
-const plugin = schemaExplorerPlugin();
-
-// Plugin API can be used by other plugins or in code
-const models = plugin.api.getModels();       // All models
-const user = plugin.api.getModel('User');    // Single model
-const names = plugin.api.getModelNames();    // Model names
-```
-
-### REST resources plugin
-
-Registers **REST-style CRUD** routes for ORM models (`GET` list, `GET /:id`, `POST`, `PATCH /:id`, `DELETE /:id`). Relations are eager-loaded only when the client passes **`?include=relation1,relation2`**; loading uses the ORM batch eager loader (no classic N+1 from relation queries). **Nested includes** (e.g. `posts.comments`) are **not** supported—only top-level relation names defined on the model.
-
-**Model opt-in** via `defineModel({ ..., rest: { enabled: true, path: 'optional-segment', allowInclude: ['company'] } })`. If you pass **`models: ['User', 'Post']`** to the plugin, those names are exposed even when `rest.enabled` is false.
-
-**Setup:**
-
-```javascript
-const { createApp, restResourcePlugin } = require('webspresso');
-
-const { app } = createApp({
-  pagesDir: './pages',
-  db,
-  plugins: [
-    restResourcePlugin({
-      path: '/api/rest',
-      middleware: [], // optional Express handlers (e.g. auth) — `attachDbMiddleware` is applied after these
-      models: null,   // optional whitelist of model names; when omitted, only `rest.enabled` models are exposed
-      excludeModels: [],
-      filter: null,   // optional (model) => boolean
-    }),
-  ],
-});
-```
-
-List query parameters: `page`, `perPage`, `sort`, `order`, `include`, `trashed` (`only` / `include` when the model uses soft delete), plus **equality filters** on real columns (unknown keys are ignored).
-
-### File upload plugin
-
-Registers **POST** `multipart/form-data` (field name **`file`** by default) and stores the file(s) via a pluggable provider. The framework ships with **`createLocalFileProvider({ destDir, publicBasePath })`** (writes to disk and returns public URL paths). Use **`mimeAllowlist`** / **`extensionAllowlist`**, **`maxBytes`** (default **10 MiB**), **`multiple`** (default **`false`**), and **`maxFiles`** (default **10**) on the server; production apps should prefer an explicit MIME allowlist.
-
-**Setup:**
-
-```javascript
-const { createApp, uploadPlugin, adminPanelPlugin } = require('webspresso');
-
-const { app } = createApp({
-  pagesDir: './pages',
-  publicDir: './public',
-  db,
-  plugins: [
-    uploadPlugin({
-      path: '/api/upload',
-      local: {
-        destDir: './public/uploads',
-        publicBasePath: '/uploads',
-      },
-      maxBytes: 10 * 1024 * 1024,
-      mimeAllowlist: ['image/jpeg', 'image/png', 'application/pdf'],
-      extensionAllowlist: ['jpg', 'jpeg', 'png', 'pdf'],
-      middleware: [], // optional Express handlers (e.g. session auth)
-      fieldName: 'file',
-      multiple: false, // set to true to allow multiple file uploads in a single request
-      maxFiles: 10,     // max number of files to accept when multiple is true
-    }),
-    adminPanelPlugin({
-      db,
-      // uploadUrl optional: defaults to app.get('webspresso.uploadPath') set by uploadPlugin
-    }),
-  ],
-});
-```
-
-- **ORM (Single File):** `zdb.file({ maxLength: 2048, nullable: true })` — string column for the stored public URL or path; migrations use `table.string(..., maxLength)`.
-- **ORM (Multiple Files):** `zdb.files({ nullable: true })` — array column that stores a list of file URLs/paths as a JSON field in the database; migrations use `table.json()`.
-- **Admin forms:** columns with `zdb.file()` or `zdb.files()` automatically render a drag-and-drop upload widget (or a manual URL text field when `uploadUrl` is not configured). Multiple file upload fields (`zdb.files()`) allow adding and removing multiple files concurrently and show preview grids. Image URLs show an inline thumbnail preview; use `ui.accept: 'image/*'` for image-only fields. Optional `ui: { label, hint, accept, maxBytes }` on the column customizes the widget. For existing `zdb.string()` columns you can use `admin.customFields: { columnName: { type: 'file-upload' } }` instead of changing the schema type.
-- **Admin:** the panel reads **`settings.uploadUrl`** from the registry (set automatically when `uploadPlugin` is registered **before** `adminPanelPlugin`, or pass **`adminPanelPlugin({ uploadUrl: '/api/upload' })`**). File fields (`type: 'file'`, `'files'` or `customFields` type `file-upload`) POST to that URL with credentials; the saved record stores the returned **`url`** / **`publicUrl`** string (or an array of URLs for `'files'`).
-- **Response:** Single: `{ url, publicUrl, key? }`. Multiple: `[{ url, publicUrl, key? }, ...]`.
-- **Custom storage:** `uploadPlugin({ provider: { async put({ buffer, originalName, mimeType, size, req }) { return { publicUrl: '...' }; } } })`.
-
-**Admin model example** (`zdb.file()` and `zdb.files()` pick up the upload widgets from schema; no extra `customFields` needed):
-
-```javascript
-const { defineModel, zdb } = require('webspresso');
-
-const Post = defineModel({
-  name: 'Post',
-  table: 'posts',
-  schema: zdb.schema({
-    id: zdb.id(),
-    title: zdb.string(),
-    cover_image: zdb.file({
-      maxLength: 2048,
-      nullable: true,
-      ui: { label: 'Cover', accept: 'image/*', hint: 'JPEG or PNG' },
-    }),
-    gallery: zdb.files({
-      nullable: true,
-      ui: { label: 'Gallery Images', accept: 'image/*' },
-    }),
-  }),
-  admin: { enabled: true, label: 'Posts' },
-});
-```
-
-For a plain string column, use `admin.customFields: { attachment: { type: 'file-upload' } }` instead of `zdb.file()`.
-
-### Health check plugin
-
-Exposes a lightweight **GET** endpoint for load balancers and orchestrators (Kubernetes, Docker healthcheck, etc.). **Enabled by default** in all environments; set `enabled: false` to turn it off.
-
-**Setup:**
-
-```javascript
-const { createApp, healthCheckPlugin } = require('webspresso');
-
-const app = createApp({
-  plugins: [
-    healthCheckPlugin({
-      path: '/health',              // default
-      verbose: true,                // timestamp, uptime, NODE_ENV, framework name/version
-      authorize: (req) => true,     // optional — restrict who can read the endpoint
-      checks: async ({ db }) => {
-        if (db) await db.knex.raw('select 1');
-        return { database: 'ok' };
-      },
-    }),
-  ],
-});
-```
-
-- **`checks`**: If this function throws, the handler responds with **503** and `{ status: 'unhealthy', error, ... }`. Return a plain object to merge into `checks` on success (e.g. dependency status).
-- Use a **custom `path`** if your app already serves `GET /health` from `pages/`.
-
-### Swagger / OpenAPI plugin
-
-Serves **OpenAPI 3** for file-based `pages/api` routes and optional [Zod](https://zod.dev) `schema` exports, plus a **Swagger UI** page. Defaults to **development only** (same idea as the schema explorer).
-
-**Setup:**
-
-```javascript
-const { createApp, swaggerPlugin } = require('webspresso');
-
-const app = createApp({
-  plugins: [
-    swaggerPlugin({
-      path: '/_swagger',           // UI: GET /_swagger, spec: GET /_swagger/openapi.json
-      enabled: true,               // default: true in development, false in production
-      title: 'My API',             // optional OpenAPI info.title
-      serverUrl: 'https://api.example.com', // optional servers[0].url (else BASE_URL or localhost)
-      includeOrmSchemas: false,    // merge ORM model schemas into components.schemas
-      ormExclude: ['Secret'],      // when includeOrmSchemas is true
-      authorize: (req) => true,  // optional gate for both UI and JSON
-    }),
-  ],
-});
-```
-
-**Endpoints:**
-
-- `GET /_swagger/openapi.json` — Full OpenAPI document (`paths` from API routes; request/response shapes from exported `schema({ z })` when present).
-- `GET /_swagger` — Swagger UI (loads the JSON above; requires network access for CDN assets).
-
-In production, keep the plugin disabled or protect it with `authorize` / your own middleware.
-
-### CSRF protection plugin
-
-Protects mutating requests against Cross-Site Request Forgery (CSRF) using the double-submit token pattern. Supports session storage (when `req.session` is available) and automatically falls back to cookie-based storage.
-
-**Setup:**
-
-```javascript
-const { createApp, csrfPlugin } = require('webspresso');
-
-const app = createApp({
-  plugins: [
-    csrfPlugin({
-      global: true,                 // Enable globally for all routes
-      cookie: true,                 // Use cookie-based storage (default uses session if present)
-      ignorePaths: ['/api/webhook'], // Skip CSRF verification for specific routes
-    }),
-  ],
-});
-```
-
-**Route-Specific Middleware:**
-
-If `global: false` (default), you can protect specific routes by applying the named route middleware `csrf` in your route configuration:
-
-```javascript
-// pages/submit.js
-module.exports = {
-  middleware: ['csrf'],
-  post(req, res) {
-    res.send('Success!');
-  }
-};
-```
-
-**Template Helpers:**
-
-The plugin registers two Nunjucks template helpers:
-- `{{ fsy.csrfToken() }}`: Returns the raw token string (useful for API fetch/headers).
-- `{{ fsy.csrfInput() }}`: Renders a hidden input field: `<input type="hidden" name="_csrf" value="...">`.
-
-## Development
-
-Native addons (**better-sqlite3**, **bcrypt**, **sharp**) are compiled for your current Node ABI. After switching Node major versions (e.g. nvm, fnm, Volta), run **`npm run rebuild:native`** or a clean install: `rm -rf node_modules && npm ci`. **chokidar** is not ABI-tied like those drivers; if file watching misbehaves, reinstall dependencies. The repo includes [`.nvmrc`](.nvmrc) (Node 20 LTS) as a known-good default for this project.
-
-```bash
-# Install dependencies
-npm install
-
-# If you changed Node version and see MODULE_VERSION or .node load errors:
-npm run rebuild:native
-
-# Run tests
-npm test
-
-# Run tests in watch mode
-npm run test:watch
-
-# Run tests with coverage
-npm run test:coverage
-
-# Micro-benchmarks (Vitest bench; CI: main push uploads benchmark-baseline artifact, PRs compare against it)
-npm run bench
-# Local baseline + compare: npm run bench:ci:local
-```
+---
 
-## License
+## 📄 License
 
-MIT
+MIT © [Webspresso Contributors](LICENSE)