aegisnode 0.0.2 → 0.0.4

package/README.md

@@ -43,6 +43,7 @@ It keeps the development model simple, but adds enough structure and tooling to
 Core features:
 
 - CLI generators (`startproject`, `createapp`, `runserver`)
+- Startup entry generator (`generateloader`)
 - Project health checker (`doctor`)
 - Dependency updater (`updatedeps`)
 - Maintenance mode with custom HTML responses
@@ -91,13 +92,14 @@ aegisnode runserver --project blog
 aegisnode createapp users --project blog
 aegisnode generate view profile --app users --project blog
 aegisnode generate route profile --app users --project blog
+aegisnode generateloader --project blog
 aegisnode doctor --project blog
 aegisnode updatedeps --project blog
 ```
 
 `cd blog` is optional. You can run commands from parent folder with `--project blog`.
 
-`createapp`, `generate`, `runserver`, `doctor`, and `updatedeps` are project-level commands.
+`createapp`, `generate`, `runserver`, `generateloader`, `doctor`, and `updatedeps` are project-level commands.
 Run them from the project root; do not `cd` into `apps/<app>`.
 Startup mode rules:
 - Development (`env === development`): start with `aegisnode runserver` only.
@@ -162,11 +164,20 @@ aegisnode doctor
 
 `doctor` checks:
 - Project structure (`settings.js`, `routes.js`, app folders)
+- Startup entry files (`app.js`, `loader.cjs`), with production errors when `loader.cjs` is missing
 - App declarations vs filesystem
 - Security baseline (`appSecret`, csrf/headers/ddos toggles)
 - Auth safety checks (JWT secret, OAuth2 `allowHttp` in production)
 - Template directory availability
 
+Regenerate project startup entry files if needed:
+
+```bash
+aegisnode generateloader
+```
+
+This restores `loader.cjs` and also recreates `app.js` if it is missing.
+
 Update project dependencies to the current npm `latest` dist-tag:
 
 ```bash
@@ -223,7 +234,7 @@ Access environment values anywhere with `process.env`:
 export default {
   port: process.env.PORT ? Number(process.env.PORT) : 3000,
   security: {
-    appSecret: process.env.APP_SECRET || '',
+    appSecret: process.env.APP_SECRET || '<generated-at-scaffold-time>',
   },
 };
 ```
@@ -240,7 +251,7 @@ export default {
   port: process.env.PORT ? Number(process.env.PORT) : 3000,
   trustProxy: false,
   security: {
-    appSecret: process.env.APP_SECRET || '',
+    appSecret: process.env.APP_SECRET || '<generated-at-scaffold-time>',
   },
   logging: {
     level: process.env.LOG_LEVEL || 'info',
@@ -265,1877 +276,1961 @@ export default {
 
 Notes:
 - Keep `AEGIS_APPS_START/END` markers; `createapp` updates this list automatically.
-- `startproject` also writes a local `.env` with a generated `APP_SECRET`.
+- `startproject` writes a local `.env` with a generated `APP_SECRET` and also embeds the same generated secret in `settings.js` as a fallback.
 - Add optional blocks manually only when needed: `https`, `templates`, `i18n`, `helpers`, `staticDir`, `websocket`, `uploads`, `mail`, `auth`, `api`, `swagger`, `loaders`, `environments`, `architecture`, `security.headers/ddos/csrf`.
 - Any section you omit uses framework defaults from `src/runtime/config.js`.
 
-<!-- SETTINGS_REFERENCE_START -->
-## Full Settings Reference
+## Core Concepts And App Structure
 
-All fields below are supported in `settings.js`. If you omit a field, AegisNode uses the runtime default.
+### App File Usage Examples
 
-Merge order used at startup:
-1. Framework defaults (`defaultConfig`)
-2. `settings.js`
-3. Legacy `settings/index.js` (if present)
-4. Legacy `settings/db.js` (merged into `database`)
-5. Legacy `settings/cache.js` (merged into `cache`)
-6. Legacy `settings/apps.js` (used only when `settings.js` does not define apps)
-7. `environments.default`
-8. `environments[env]` where `env = settings.env` (fallback `NODE_ENV`, then `development`)
+Each generated app usually contains:
+- `apps/<app>/views.js`
+- `apps/<app>/models.js`
+- `apps/<app>/services.js`
+- `apps/<app>/subscribers.js`
+- `apps/<app>/routes.js`
 
-### Top-Level
+Usage by file:
+- `views.js`: HTTP handlers (`req`, `res`, `next`). Default signature can be context-first: `handler({ service, validator, services, validators, ... }, req, res, next)`.
+- `models.js`: data access layer only (SQL/NoSQL operations).
+- `services.js`: business logic layer; orchestrates models.
+- `subscribers.js`: event listeners (for example `app.booted`, `ws.connection`, custom events).
+- `routes.js`: route mapping only (`route.get(...)`, `route.post(...)`, `route.use(...)`) to view handlers.
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `appName` | `string` / folder name | Application name used in logs and defaults. |
-| `env` | `string` / `process.env.NODE_ENV || 'development'` | Active environment key for `environments` overrides. |
-| `host` | `string` / `process.env.HOST || '0.0.0.0'` | Bind host for HTTP server. |
-| `port` | `number` / `process.env.PORT || 3000` | Bind port for HTTP server. |
-| `trustProxy` | `boolean \| number \| string` / `false` | Express `trust proxy` value. Set this when HTTPS is terminated by a reverse proxy/load balancer. |
-| `https` | `object \| false` / see HTTPS table | Direct TLS server settings for Node-hosted HTTPS. |
-| `staticDir` | `string \| null` / `null` | Static assets directory, relative to project root (if set). |
-| `templates` | `object \| false` / see templates table | EJS template engine + layout settings. |
-| `i18n` | `object` / see i18n table | Built-in locale detection + translator bridge (`req.aegis.t`, injected `i18n.t`). |
-| `helpers` | `object` / see helpers table | Runtime helper defaults (for example currency/locale for `helpers.money`). |
-| `security` | `object` / see security tables | Security headers, DDoS limiter, CSRF settings, app secret. |
-| `logging` | `object` / `{ level: 'info' }` | Runtime logger level. |
-| `database` | `object` / see database table | SQL or MongoDB connection settings. |
-| `cache` | `object` / `{ enabled: true, driver: 'memory' }` | Cache backend settings. |
-| `websocket` | `object` / `{ enabled: true, cors: { origin: false } }` | Socket.IO server options. |
-| `uploads` | `object` / see uploads table | Built-in file upload middleware settings used by `route.upload`. |
-| `mail` | `object` / see mail table | Nodemailer-backed mail manager available as injected `mail` and `req.aegis.mail`. |
-| `api` | `object` / see API table | API-app middleware behavior (JSON enforcement, no-store, CSRF skip for API mounts). |
-| `auth` | `object` / see auth tables | JWT or OAuth2 provider settings. |
-| `swagger` | `object` / see swagger table | OpenAPI JSON + Swagger UI settings. |
-| `architecture` | `object` / `{ strictLayers: false }` | Layering enforcement mode. |
-| `autoMountApps` | `boolean` / `false` | Auto-mount each app route file from `settings.apps`. |
-| `loaders` | `array` / `[]` | Startup loaders run before routes mounting. |
-| `apps` | `array` / `[]` | Declared apps with mount points. |
-| `environments` | `object` / `{}` | Environment-specific deep overrides. |
+Route modules are mapping-only (`register(route)`).
+Framework context is injected into handlers as first argument (when handler uses 4 args): `{ service, validator, services, models, validators, auth, mail, helpers, i18n, events, ... }`.
+`req.aegis` is also available.
+`service`/`validator` are app-scoped conveniences. For root/non-app routes, use `services.get('<app>.<name>')` / `validators.get('<app>.<name>')`, or create an app-scoped accessor with `services.forApp('<app>')`.
 
-Notes:
-- `rootDir` is internal and set by runtime; do not manage it manually.
-- Arrays are replaced (not merged) during deep merge.
+What “app-scoped” means:
+- In app routes (for example inside `apps/users/routes.js`), `{ service }` resolves to that app service.
+- In root/global routes (`routes.js`), there is no single app context, so use `{ services }` and fetch with `services.forApp('<app>').get('<name>')` or `services.get('<app>.<name>')`.
 
-### HTTPS (`https`)
+Injected runtime dependencies:
 
-Use this only when Node should serve HTTPS directly. If HTTPS is handled by Passenger, Nginx, Apache, or another proxy, keep `https.enabled` off and set top-level `trustProxy` instead.
+AegisNode injects resolved runtime objects instead of asking app layers to import framework internals. `config` is the resolved runtime config from `settings.js` plus defaults and runtime overrides.
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `enabled` | `boolean` / `false` | Create an HTTPS server instead of HTTP. |
-| `key` | `string \| Buffer` / `null` | TLS private key content. |
-| `cert` | `string \| Buffer` / `null` | TLS certificate content. |
-| `ca` | `string \| Buffer \| array` / `null` | Optional CA/intermediate certificate content. |
-| `pfx` | `string \| Buffer` / `null` | PFX/PKCS#12 archive content. Use instead of `key` + `cert`. |
-| `keyPath` | `string` / `''` | Path to TLS private key, relative to project root or absolute. |
-| `certPath` | `string` / `''` | Path to TLS certificate, relative to project root or absolute. |
-| `caPath` | `string \| string[]` / `null` | Optional CA/intermediate certificate path(s). |
-| `pfxPath` | `string` / `''` | Path to PFX/PKCS#12 archive. |
-| `passphrase` | `string` / `''` | Optional passphrase for encrypted key/PFX files. |
-| `options` | `object` / `{}` | Extra Node `https.createServer` options (for example `minVersion`). |
+Available by layer:
+- Views/handlers (`views.js` or any context-first route/controller action): `appName`, `app`, `config`, `env`, `i18n`, `mail`, `logger`, `events`, `cache`, `io`, `auth`, `helpers`, `jlive`, `upload`, `services`, `models`, `validators`, `service`, `model`, `validator`, `database`, `dbClient`
+- Services (`constructor({ ... })`): `appName`, `config`, `env`, `i18n`, `mail`, `logger`, `events`, `cache`, `io`, `auth`, `helpers`, `jlive`, `models`, `validators`, `services`
+- Models (`constructor({ ... })`): `appName`, `config`, `env`, `i18n`, `mail`, `logger`, `events`, `cache`, `io`, `helpers`, `jlive`, `dbClient`, `database`
+- Validators (`constructor({ ... })`): `appName`, `config`, `env`, `i18n`, `mail`, `logger`, `events`, `cache`, `io`, `auth`, `helpers`, `jlive`, `dbClient`, `database`
+- Subscribers (`export default function ({ ... })`): `appName`, `rootDir`, `config`, `env`, `i18n`, `mail`, `logger`, `events`, `cache`, `io`, `auth`, `helpers`, `jlive`, `upload`, `services`, `models`, `validators`, `database`, `dbClient`, `app`, `server`, `templates`, `protocol`, `container`, `declaredAppNames`
+- Controllers (`constructor({ ... })`): `appName`, `rootDir`, `config`, `env`, `i18n`, `mail`, `logger`, `events`, `cache`, `io`, `auth`, `helpers`, `jlive`, `upload`, `services`, `models`, `validators`, `database`, `dbClient`, `container`, `app`
+- Loaders (`loaders` entry function): `rootDir`, `config`, `env`, `i18n`, `mail`, `logger`, `events`, `cache`, `io`, `auth`, `helpers`, `jlive`, `upload`, `services`, `models`, `validators`, `database`, `dbClient`, `app`, `server`, `templates`, `protocol`, `container`, `declaredAppNames`, `options`
+- Request bridge (`req.aegis`): `config`, `env`, `i18n`, `locale`, `localeSource`, `t`, `setLocale`, `logger`, `events`, `cache`, `io`, `auth`, `mail`, `helpers`, `jlive`, `upload`, `services`, `models`, `validators`, `database`, `dbClient`, `appName`, `app`
+- Template locals: `helpers`, `jlive`, `t`, `locale`, `i18n`, `money`, `number`, `dateTime`, `timeElapsed`, `timeDifference`, `breakStr`
 
-Direct HTTPS example:
+Key meanings:
+
+| Key | Description |
+| --- | --- |
+| `config` | Resolved runtime config from `settings.js`, framework defaults, environment overrides, and runtime overrides. |
+| `env` | Frozen environment snapshot (`process.env` plus runtime additions such as `APP_SECRET`). |
+| `i18n` | Translator bridge. During a request it follows the active request locale; outside a request it falls back to `defaultLocale` unless you pass `{ locale }`. |
+| `mail` | Mail manager. Use `mail.send({ to, subject, text/html })` or `mail.sendMail(...)`. |
+| `logger` | Runtime logger instance. |
+| `events` | Event bus used by subscribers and app code. |
+| `cache` | Cache backend instance (memory by default). |
+| `io` | Socket.IO server instance when websocket support is enabled. |
+| `auth` | Auth manager for JWT/OAuth2 flows. |
+| `helpers` | Runtime helper functions such as `money`, `number`, `dateTime`, and `timeElapsed`. |
+| `jlive` | jlive bridge instance. |
+| `upload` | Upload manager used by `route.upload`. |
+| `services` | Layer accessor used to fetch services by app/name. |
+| `models` | Layer accessor used to fetch models by app/name. |
+| `validators` | Layer accessor used to fetch validators by app/name. |
+| `service` | App-scoped convenience service for the current app only. |
+| `model` | App-scoped convenience model for the current app only. |
+| `validator` | App-scoped convenience validator for the current app only. |
+| `database` | Database runtime wrapper. |
+| `dbClient` | Low-level database/query client. |
+| `appName` | Current app name. |
+| `app` | Current app metadata/context. |
+| `rootDir` | Absolute project root. |
+| `server` | HTTP/HTTPS server instance. |
+| `templates` | Resolved template-engine configuration. |
+| `protocol` | Server protocol (`http` or `https`). |
+| `container` | Internal DI container. |
+| `declaredAppNames` | Set of apps declared in config/routes. |
+| `options` | Loader-specific options object from a `{ path, options }` loader entry. |
+| `locale` | Active request locale. Available on `req.aegis` and template locals. |
+| `localeSource` | Where the current locale came from (`query`, `cookie`, `header`, `manual`, or `disabled`). |
+| `t` | Convenience translator shortcut for the current request/template scope. |
+| `setLocale` | Request helper used to change and optionally persist the active locale. |
 
 ```js
+// routes.js (root/global)
 export default {
-  host: '0.0.0.0',
-  port: 3443,
-  https: {
-    enabled: true,
-    keyPath: 'certs/localhost-key.pem',
-    certPath: 'certs/localhost-cert.pem',
-    options: {
-      minVersion: 'TLSv1.2',
-    },
+  register(route) {
+    route.get('/dashboard', async ({ services }, req, res, next) => {
+      try {
+        const usersService = services.forApp('users').get('users');
+        const ordersService = services.forApp('orders').get('orders');
+        res.json({
+          users: await usersService.list(),
+          orders: await ordersService.list(),
+        });
+      } catch (error) {
+        next(error);
+      }
+    });
   },
 };
 ```
 
-Reverse-proxy HTTPS example:
+Example `views.js`:
 
 ```js
-export default {
-  host: '127.0.0.1',
-  port: 3000,
-  trustProxy: 1,
-};
-```
+class UsersView {
+  static async index({ service }, req, res, next) {
+    try {
+      const data = await service.listUsers();
+      res.json({ data });
+    } catch (error) {
+      next(error);
+    }
+  }
 
-Notes:
-- `https` requires either `pfx`/`pfxPath` or both `key`/`keyPath` and `cert`/`certPath`.
-- Paths resolve from project root unless absolute.
-- `trustProxy` affects `req.secure`, `req.protocol`, secure cookies, and OAuth2 secure transport checks.
-- Prefer `1`, a subnet, or another exact Express `trust proxy` value instead of `true` when rate limiting is enabled.
+  static async create({ service, validator }, req, res, next) {
+    try {
+      const payload = validator.create(req.body || {});
+      const created = await service.createUser(payload);
+      res.status(201).json({ data: created });
+    } catch (error) {
+      next(error);
+    }
+  }
 
-### Templates (`templates`)
+  static async tools({ service, helpers, jlive }, req, res, next) {
+    try {
+      const stats = await service.stats();
+      res.json({
+        stats,
+        total: helpers.money(1299.5, { currency: 'USD' }),
+        elapsed: helpers.timeElapsed(Date.now() - 60_000),
+        token: jlive.generate(16),
+      });
+    } catch (error) {
+      next(error);
+    }
+  }
+}
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `enabled` | `boolean` / `true` | Enable template engine. |
-| `engine` | `string` / `'ejs'` | Template engine. Only `ejs` is supported. |
-| `dir` | `string` / `'templates'` | Templates folder (absolute or relative to project root). |
-| `base` | `string \| false \| null` / `'base'` | Default layout template (without `.ejs`). Set `false`/`null` to disable layout wrapping globally. |
-| `appBases` | `object` / `{}` | Per-app layout override map: `{ appName: 'layout/name' }`. Set app value to `false`/`null` to disable layout for that app only. |
-| `locals` | `object \| function` / `{}` | Global locals. If function, signature is `({ req, res, helpers, jlive, env }) => object`. |
+export default UsersView;
+```
 
-Layout notes:
-- `res.render('view', data)` renders `view.ejs` and wraps it with `base.ejs` (or configured layout).
-- Per-app layout override: `templates.appBases = { users: 'users/base', admin: 'admin/base' }`.
-- In layout, both `<%- body %>` and `<%- content %>` are available.
-- Per-render layout override: pass `layout: 'custom-layout'` or `layout: false` in locals.
+Example `models.js`:
 
-### Internationalization (`i18n`)
+```js
+class UsersModel {
+  constructor({ dbClient }) {
+    this.dbClient = dbClient;
+  }
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `enabled` | `boolean` / `false` | Enable built-in i18n translator bridge. |
-| `defaultLocale` | `string` / `'en'` | Default locale used when detection fails. |
-| `fallbackLocale` | `string` / `'en'` | Fallback locale used when key is missing in active locale. |
-| `supported` | `string[]` / `['en']` | Allowed locales. Values normalize to lowercase (for example `en-US` -> `en-us`). |
-| `queryParam` | `string` / `'lang'` | Query parameter used for locale selection (for example `?lang=fr`). |
-| `cookieName` | `string` / `'aegis_locale'` | Cookie used to persist locale. |
-| `detectFromHeader` | `boolean` / `true` | Enable locale detection from `Accept-Language` header. |
-| `detectFromCookie` | `boolean` / `true` | Enable locale detection from configured cookie. |
-| `detectFromQuery` | `boolean` / `true` | Enable locale detection from query parameter. |
-| `translations` | `object` / `{}` | Translation map by locale. Values can be objects or JSON file paths: `{ en: { ... }, fr: 'locales/fr.json' }`. Alias keys `locales` and `messages` are also accepted. |
-| `translationsFile` | `string` / unset | Path to a JSON file containing all locales (example: `{ "en": {...}, "fr": {...} }`). Inline `translations` overrides file values for same locale keys. |
+  async list() {
+    return [{ id: '1', name: 'Alice' }];
+  }
 
-i18n notes:
-- Detection order: query -> cookie -> `Accept-Language` -> `defaultLocale`.
-- Use dotted keys like `home.title`.
-- Placeholder interpolation supports `{name}` style tokens.
-- Relative JSON paths resolve from project root (`settings.js` location).
-- Injected `i18n` is available in handlers, services, models, validators, controllers, subscribers, and loaders. Use `i18n.t('key', vars, { locale })`.
-- During a request, injected `i18n.t(...)` follows the active request locale. Outside a request, it falls back to `defaultLocale`.
+  async create(payload) {
+    return { id: '2', ...payload };
+  }
+}
 
-### Helpers Defaults (`helpers`)
+export default { users: UsersModel };
+```
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `locale` | `string` / `'en-US'` | Default locale used by runtime helpers when locale is not passed explicitly. |
-| `money` | `object` / `{ currency: 'USD' }` | Default money formatting settings used by `helpers.money`. |
-| `money.currency` | `string` / `'USD'` | Default currency code for `helpers.money(amount)` when no currency option is provided. |
-| `money.locale` | `string` / `helpers.locale` | Locale override only for `helpers.money`. |
-| `money.currencyDisplay` | `'symbol' | 'code' | 'name' | 'narrowSymbol'` / `'symbol'` | Currency display style passed to `Intl.NumberFormat`. |
-| `money.minimumFractionDigits` | `number` / unset | Optional minimum fraction digits for money formatting. |
-| `money.maximumFractionDigits` | `number` / unset | Optional maximum fraction digits for money formatting. |
-
-Helpers defaults notes:
-- Per-call options always override these defaults.
-- If `helpers.locale` is not set, AegisNode falls back to `i18n.defaultLocale` for helper locale.
-- Legacy shorthand keys are also accepted for compatibility: `helpers.currency`, top-level `currency`, and `app.currency`.
+Example `services.js`:
 
-### Security (`security`)
+```js
+class UsersService {
+  constructor({ models, env }) {
+    this.usersModel = models.get('users');
+    this.env = env;
+  }
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `appSecret` | `string` / `''` | Shared secret for signing security artifacts. Use at least 16 chars. |
-| `headers` | `object` / see headers table | Helmet + CSP configuration. |
-| `ddos` | `object` / see ddos table | `express-rate-limit` based protection. |
-| `csrf` | `object` / see csrf table | CSRF cookie/token behavior. |
+  async listUsers() {
+    return this.usersModel.list();
+  }
 
-#### Security Headers (`security.headers`)
+  async createUser(payload) {
+    return this.usersModel.create(payload);
+  }
+}
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `enabled` | `boolean` / `true` | Enable Helmet middleware. |
-| `csp` | `object` / see CSP table | Content Security Policy behavior. |
+export default { users: UsersService };
+```
 
-#### CSP (`security.headers.csp`)
+Example `subscribers.js`:
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `enabled` | `boolean` / `true` | Enable CSP header from Helmet. |
-| `reportOnly` | `boolean` / `false` | Use report-only mode. |
-| `directives` | `object` / `{}` | Directive overrides. Set a directive to `false`/`null` to remove it. |
+```js
+export default function registerUsersSubscribers({ events, logger }) {
+  events.subscribe('app.booted', ({ appName }) => {
+    logger.info('[users] booted: %s', appName);
+  });
+}
+```
 
-Default CSP base includes safe defaults such as `defaultSrc 'self'`, `objectSrc 'none'`, `frameAncestors 'none'`, and websocket-aware `connectSrc`.
+Injected `env` is also available in:
+- view handler context: `static index({ env }, req, res) { ... }`
+- model constructors: `constructor({ dbClient, env }) { ... }`
+- subscribers: `export default function ({ events, env }) { ... }`
+- request runtime bridge: `req.aegis.env`
 
-Allow multiple external domains by adding them per directive (not globally):
+Example `routes.js`:
 
 ```js
-security: {
-  headers: {
-    csp: {
-      directives: {
-        scriptSrc: ["'self'", 'https://cdn.jsdelivr.net', 'https://unpkg.com'],
-        scriptSrcElem: ["'self'", 'https://cdn.jsdelivr.net', 'https://unpkg.com'],
-        styleSrc: ["'self'", "'unsafe-inline'", 'https://cdn.jsdelivr.net'],
-        styleSrcElem: ["'self'", 'https://cdn.jsdelivr.net'],
-        imgSrc: ["'self'", 'data:', 'https://cdn.jsdelivr.net'],
-        connectSrc: ["'self'", 'https://api.example.com', 'wss://socket.example.com'],
-      },
-    },
+import UsersView from './views.js';
+
+export default {
+  appName: 'users',
+  register(route) {
+    route.get('/home', UsersView.home);
+    route.get('/', UsersView.index);
+    route.post('/', UsersView.create);
   },
-},
+};
 ```
 
-Notes:
-- Add each origin to the exact directive needed (scripts, styles, images, API/WebSocket connections).
-- If browser reports a `script-src-elem` violation, whitelist the domain in `scriptSrcElem`.
-- Prefer explicit origins instead of `*` in production.
+## Common Tasks And Feature Guides
 
-Google Fonts example:
+### File Uploads
+
+AegisNode provides built-in upload middleware on route API as `route.upload`.
+
+Storage location:
+- Default folder: `<project-root>/uploads`
+- Change with `settings.uploads.dir` (relative or absolute path)
+
+Recommended upload settings:
 
 ```js
-security: {
-  headers: {
-    csp: {
-      directives: {
-        styleSrc: ["'self'", "'unsafe-inline'", 'https://fonts.googleapis.com'],
-        styleSrcElem: ["'self'", 'https://fonts.googleapis.com'],
-        fontSrc: ["'self'", 'data:', 'https://fonts.gstatic.com'],
-      },
-    },
-  },
+uploads: {
+  enabled: true,
+  dir: 'storage/uploads',
+  createDir: true,
+  preserveExtension: true,
+  maxFileSize: '5mb',
+  maxFiles: 5,
+  maxFields: 50,
+  maxFieldSize: '1mb',
+  allowedMimeTypes: ['image/png', 'image/jpeg'],
+  allowedExtensions: ['.png', '.jpg', '.jpeg'],
+  allowApiMultipart: true,
 },
 ```
 
-#### DDoS / Rate Limit (`security.ddos`)
+Route middleware modes:
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `enabled` | `boolean` / `true` | Enable rate limiter. |
-| `windowMs` | `number` / `60000` | Rate limit window in milliseconds. |
-| `maxRequests` | `number` / `120` | Max requests per window per key. |
-| `message` | `string` / `'Too many requests, please try again later.'` | JSON error message text. |
-| `statusCode` | `number` / `429` | Response status code when limited. |
-| `standardHeaders` | `boolean` / `true` | Emit modern rate-limit headers. |
-| `legacyHeaders` | `boolean` / `false` | Emit legacy `X-RateLimit-*` headers. |
-| `skipSuccessfulRequests` | `boolean` / `false` | Do not count successful responses. |
-| `skipFailedRequests` | `boolean` / `false` | Do not count failed responses. |
-| `trustProxy` | `boolean \| number \| string` / `false` | Legacy alias for top-level `trustProxy`. Still supported for backward compatibility. |
-| `store` | `object \| null` / `null` | Custom rate-limit store implementation. |
-| `skipPaths` | `string[]` / `['/health']` | Path prefixes excluded from limiter. |
+```js
+import UsersView from './views.js';
 
-#### CSRF (`security.csrf`)
+export default {
+  appName: 'users',
+  register(route) {
+    // One file -> req.file
+    route.post('/avatar', route.upload.single('avatar'), UsersView.uploadAvatar);
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `enabled` | `boolean` / `true` | Enable CSRF middleware. |
-| `rejectForms` | `boolean` / `true` | Enforce CSRF on form submissions. |
-| `rejectUnsafeMethods` | `boolean` / `true` | Enforce CSRF for unsafe methods (`POST/PUT/PATCH/DELETE`) in general. |
-| `cookieName` | `string` / `'_aegis_csrf'` | CSRF cookie name. |
-| `fieldName` | `string` / `'_csrf'` | Body form field name for CSRF token. |
-| `headerName` | `string` / `'x-csrf-token'` | Header token key (normalized lowercase). |
-| `requireSignedCookie` | `boolean` / `true` | Require signed CSRF cookie values. |
-| `sameSite` | `'lax' \| 'strict' \| 'none' \| false` / `'lax'` | CSRF cookie same-site mode. |
-| `secure` | `boolean \| 'auto'` / `'auto'` | Secure cookie flag (`auto` respects request security). |
-| `httpOnly` | `boolean` / `true` | Make CSRF cookie httpOnly. |
-| `path` | `string` / `'/'` | CSRF cookie path. |
+    // Many files from one input name -> req.files (array)
+    route.post('/gallery', route.upload.array('photos', 6), UsersView.uploadGallery);
 
-CSRF notes:
-- With `requireSignedCookie: true` (default), `security.appSecret` must be strong (minimum 16 chars) or startup fails.
-- CSRF is skipped for configured API app mounts when `api.disableCsrf: true`.
-- CSRF is skipped on built-in OAuth2 server endpoints.
+    // Many named file inputs -> req.files.<fieldName> (array)
+    route.post(
+      '/documents',
+      route.upload.fields([
+        { name: 'avatar', maxCount: 1 },
+        { name: 'docs', maxCount: 3 },
+      ]),
+      UsersView.uploadDocuments,
+    );
 
-### Logging (`logging`)
+    // Accept all file fields -> req.files (array)
+    route.post('/any-upload', route.upload.any(), UsersView.uploadAny);
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `level` | `'error' \| 'warn' \| 'info' \| 'debug' \| 'trace'` / `'info'` | Logger verbosity threshold. |
+    // No files, parse multipart text fields only
+    route.post('/multipart-no-file', route.upload.none(), UsersView.multipartNoFile);
+  },
+};
+```
 
-### Database (`database`)
+`req` payload shape:
+- `single()`: `req.file` + `req.body`
+- `array()`: `req.files` (array) + `req.body`
+- `fields()`: `req.files` object (`req.files.avatar`, `req.files.docs`, ...) + `req.body`
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `enabled` | `boolean` / `false` | Enable database bootstrap. |
-| `dialect` | `string` / `'pg'` | SQL: `mysql`, `pg`/`postgres`/`postgresql`, `sqlite`, `mssql`, `oracle`; NoSQL: `mongo`/`mongodb`/`mongoose`. |
-| `config` | `object` / `{}` | Connection options passed to database driver. |
-| `options` | `object` / `{}` | Extra options (used directly for Mongo when enabled). |
-| `uri` | `string` / unset | Legacy Mongo URI fallback (still accepted). Prefer `config.connectionString`. |
+Custom route with form fields + file:
 
-Mongo config shortcuts accepted in `database.config`:
-- `connectionString` (preferred)
-- or `server`/`host`, `port`, `database`/`dbName`, `user`/`username`, `password`
+```js
+// apps/users/routes.js
+import UsersView from './views.js';
 
-### Cache (`cache`)
+export default {
+  appName: 'users',
+  register(route) {
+    route.post('/profile/update', route.upload.single('avatar'), UsersView.updateProfile);
+  },
+};
+```
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `enabled` | `boolean` / `true` | Enable cache service. |
-| `driver` | `string` / `'memory'` | Cache driver. Currently only `memory` is built-in. |
-| `options` | `object` / `{}` | Reserved for future/custom drivers. |
+```js
+// apps/users/views.js
+class UsersView {
+  static updateProfile(_context, req, res) {
+    const { username, bio } = req.body;
+    const avatar = req.file || null;
 
-### WebSocket (`websocket`)
+    return res.json({
+      username,
+      bio,
+      avatar: avatar ? {
+        name: avatar.filename,
+        originalName: avatar.originalname,
+        mimeType: avatar.mimetype,
+        size: avatar.size,
+        path: avatar.path,
+      } : null,
+    });
+  }
+}
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `enabled` | `boolean` / `true` | Enable Socket.IO server. |
-| `cors` | `object` / `{ origin: false }` | Passed directly to Socket.IO `cors` option. |
+export default UsersView;
+```
 
-### Uploads (`uploads`)
+```html
+<form action="/users/profile/update" method="POST" enctype="multipart/form-data">
+  <%= csrfToken %>
+  <input name="username" />
+  <textarea name="bio"></textarea>
+  <input type="file" name="avatar" />
+  <button type="submit">Save</button>
+</form>
+```
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `enabled` | `boolean` / `true` | Enable built-in upload manager. |
-| `dir` | `string` / `'uploads'` | Upload destination folder (absolute or relative to project root). |
-| `createDir` | `boolean` / `true` | Create upload directory automatically on boot. |
-| `preserveExtension` | `boolean` / `true` | Preserve original file extension in generated file name. |
-| `maxFileSize` | `number \| string` / `5 * 1024 * 1024` | Per-file max size in bytes. String units like `'5mb'` are accepted. |
-| `maxFiles` | `number` / `5` | Max file count per request. |
-| `maxFields` | `number` / `50` | Max non-file form fields per request. |
-| `maxFieldSize` | `number \| string` / `1024 * 1024` | Max size per form field value. String units are accepted. |
-| `allowedMimeTypes` | `string[] \| string` / `[]` | Allowed MIME types. Empty means allow all. |
-| `allowedExtensions` | `string[] \| string` / `[]` | Allowed file extensions (`.jpg`, `.pdf`, ...). Empty means allow all. |
-| `allowApiMultipart` | `boolean` / `true` | Allow `multipart/form-data` on API mounts even when `api.requireJsonForUnsafeMethods` is true. |
+Upload limits and rejections:
+- Per-file size limit from `uploads.maxFileSize` returns `413` when exceeded.
+- Total files limit from `uploads.maxFiles` returns `413` when exceeded.
+- `allowedMimeTypes` / `allowedExtensions` mismatch returns `415`.
 
-### Mail (`mail`)
+Important behavior:
+- If `uploads.enabled=false`, using `route.upload.*` throws at route registration.
+- For API mounts, multipart is allowed only when `uploads.allowApiMultipart=true`.
+- For non-API form submissions, CSRF token is required by default.
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `enabled` | `boolean` / `false` | Enable the built-in mail manager. |
-| `defaults` | `object` / `{ from: '', replyTo: '' }` | Default message fields merged into every outgoing mail payload. |
-| `defaults.from` | `string` / `''` | Default sender used when `mail.send(...)` omits `from`. |
-| `defaults.replyTo` | `string` / `''` | Default `replyTo` header for outgoing mail. |
-| `transport` | `object \| string` / `{}` | Nodemailer transport config or SMTP connection URL passed to `nodemailer.createTransport(...)`. |
-| `transporter` | `object \| null` / `null` | Prebuilt transporter object with `sendMail()`. Useful in tests or custom integrations. |
-| `transportFactory` | `function \| null` / `null` | Factory that returns a transporter object with `sendMail()`. |
-| `verifyOnStartup` | `boolean` / `false` | Call `transporter.verify()` during boot when the transporter supports it. |
+### API Apps
 
-Mail notes:
-- The runtime uses [Nodemailer](https://nodemailer.com/).
-- `mail.send(payload)` and `mail.sendMail(payload)` are aliases.
-- Each payload must include at least one of `to`, `cc`, or `bcc`.
-- Each payload must include `from`, or configure `mail.defaults.from`.
-- Injected `mail` is available in handlers, services, models, validators, controllers, subscribers, and loaders, plus `req.aegis.mail`.
+`api` does not create a separate app type. You still build a normal AegisNode app with `routes.js`, `views.js`, `services.js`, and `validators.js`.
+The `api` setting only changes middleware behavior for selected app mounts.
 
-### API (`api`)
+Think of it this way:
+- `api` controls request/response behavior for an app mount.
+- `auth` controls who can access routes and how tokens are issued/verified.
+- You can use `api` without auth, auth without `api`, or both together.
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `apps` | `string[]` / `[]` | App names treated as API apps. Mounts are resolved from `settings.apps`. |
-| `disableCsrf` | `boolean` / `true` | Skip CSRF checks for API app mounts. |
-| `requireJsonForUnsafeMethods` | `boolean` / `true` | Reject unsafe API payloads unless `Content-Type` is JSON (`415`). Multipart is allowed when `uploads.allowApiMultipart=true`. |
-| `noStoreHeaders` | `boolean` / `true` | Set `Cache-Control: no-store` on API responses. |
+Common combinations:
+- `api` only: public or internal JSON endpoints with no token auth.
+- `api` + JWT: first-party SPA/mobile/frontend calling your own backend.
+- `api` + OAuth2: third-party clients, machine-to-machine access, or standards-based authorization flows.
 
-API notes:
-- `api.apps` contains app names from `settings.apps`, not URL paths.
-- Marking an app as API does not generate REST routes or change the app file structure. It only applies API middleware to that app mount.
-- The effective API mount comes from `settings.apps[].mount` (or `/${app}` by default). Keep that aligned with your `route.use(...)` mount when `autoMountApps` is off.
+Quick start:
 
-### Auth (`auth`)
+1. Declare the app in `settings.apps` and give it a mount.
+2. Add that app name to `api.apps`.
+3. Mount the app at the same path in `routes.js` when `autoMountApps` is off.
+4. Return JSON from your handlers.
+5. Send JSON for unsafe methods unless you intentionally allow multipart uploads.
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `enabled` | `boolean` / `false` | Enable auth manager. |
-| `provider` | `'jwt' \| 'oauth2'` / `'jwt'` | Active auth provider. |
-| `tablePrefix` | `string` / `'aegisnode'` | Prefix for auth storage namespaces/tables; sanitized to lowercase `[a-z0-9_]`. |
-| `storage` | `object` / see storage table | Persistence backend for auth state. |
-| `jwt` | `object` / see jwt table | JWT configuration. |
-| `oauth2` | `object` / see oauth2 table | OAuth2 server and token configuration. |
+Example `settings.js`:
 
-#### Auth Storage (`auth.storage`)
+```js
+export default {
+  apps: [
+    { name: 'users', mount: '/users' },
+  ],
+  api: {
+    apps: ['users'],
+    disableCsrf: true,
+    requireJsonForUnsafeMethods: true,
+    noStoreHeaders: true,
+  },
+};
+```
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `driver` | `'cache' \| 'memory' \| 'file' \| 'database'` / `'cache'` | Storage backend for revocations/clients/tokens. |
-| `filePath` | `string` / `'storage/aegisnode-auth-store.json'` | Used when `driver: 'file'`. Relative to project root if not absolute. |
-| `tableName` | `string` / `'aegisnode_auth_store'` (prefix-based) | Used when `driver: 'database'` for SQL table or Mongo collection. |
-| `collectionName` | `string` / alias only | Legacy alias; if set and `tableName` missing, it becomes `tableName`. |
+Example root `routes.js`:
 
-#### JWT (`auth.jwt`)
+```js
+import users from './apps/users/routes.js';
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `secret` | `string` / `security.appSecret` fallback | Signing secret. Required for JWT auth. |
-| `algorithm` | `'HS256' \| 'HS384' \| 'HS512'` / `'HS256'` | JWT HMAC algorithm. |
-| `issuer` | `string` / `appName` | JWT issuer claim. |
-| `audience` | `string` / `appName` | JWT audience claim. |
-| `expiresIn` | `string` / `'15m'` | Access token TTL. |
-| `refreshExpiresIn` | `string` / `'7d'` | Refresh token TTL. |
+export default {
+  register(route) {
+    route.use('/users', users); // keep this aligned with settings.apps[].mount
+  },
+};
+```
 
-#### OAuth2 Core (`auth.oauth2`)
+Example `apps/users/routes.js`:
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `accessTokenTtlSeconds` | `number` / `3600` | Access token TTL in seconds. |
-| `refreshTokenTtlSeconds` | `number` / `1209600` | Refresh token TTL in seconds. |
-| `authorizationCodeTtlSeconds` | `number` / `600` | Authorization code TTL in seconds. |
-| `rotateRefreshToken` | `boolean` / `true` | Rotate refresh token on refresh flow. |
-| `requireClientSecret` | `boolean` / `true` | Require secret for confidential client flows. |
-| `requirePkce` | `boolean` / `true` | Require PKCE for authorization_code flow. |
-| `allowPlainPkce` | `boolean` / `false` | Allow PKCE `plain` method. |
-| `grants` | `string[]` / `['authorization_code','refresh_token','client_credentials']` | Enabled OAuth2 grants. |
-| `defaultScopes` | `string[]` / `[]` | Scopes assigned when none requested/provided. |
-| `clientAuthMethod` | `'client_secret_basic' \| 'client_secret_post' \| 'none'` / `'client_secret_basic'` | Default client authentication method. |
-| `server` | `object` / see OAuth2 server table | Built-in authorization server endpoint settings. |
+```js
+import UsersView from './views.js';
 
-#### OAuth2 Server (`auth.oauth2.server`)
+export default {
+  appName: 'users',
+  register(route) {
+    route.get('/', UsersView.index);
+    route.post('/', UsersView.create);
+  },
+};
+```
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `enabled` | `boolean` / `true` | Mount built-in OAuth2 endpoints. |
-| `basePath` | `string` / `'/oauth'` | Base path used to derive endpoint defaults. |
-| `authorizePath` | `string` / `'/oauth/authorize'` | Authorization endpoint path. |
-| `tokenPath` | `string` / `'/oauth/token'` | Token endpoint path. |
-| `introspectionPath` | `string` / `'/oauth/introspect'` | Introspection endpoint path. |
-| `revocationPath` | `string` / `'/oauth/revoke'` | Revocation endpoint path. |
-| `metadataPath` | `string` / `'/.well-known/oauth-authorization-server'` | OAuth2 metadata endpoint path. |
-| `issuer` | `string` / `server.baseUrl` fallback, then `appName` | Issuer value in OAuth2 metadata/tokens. |
-| `baseUrl` | `string` / optional alias | Alias used as fallback for `issuer` when `issuer` is empty. |
-| `autoApprove` | `boolean` / `true` | Auto-approve auth requests once subject is resolved. |
-| `requireAuthenticatedUser` | `boolean` / `true` | Require authenticated user/subject for authorize endpoint. |
-| `requireConsent` | `boolean` / `false` | Require explicit consent before issuing auth code. |
-| `allowSubjectFromParams` | `boolean` / `false` | Allow subject from request params (`subject`/`user_id`). Keep disabled in production. |
-| `allowHttp` | `boolean` / `false` | Allow OAuth2 endpoints on non-HTTPS requests. Keep `false` in production. |
-| `resolveSubject` | `function \| null` / `null` | Hook to resolve subject: `({ req, params, client }) => string|null`. |
-| `resolveConsent` | `function \| null` / `null` | Hook to resolve consent: `({ req, params, client, subject }) => boolean`. |
+Example `apps/users/views.js`:
 
-### Swagger (`swagger`)
+```js
+class UsersView {
+  static async index({ service }, req, res, next) {
+    try {
+      const users = await service.list();
+      res.json({ data: users });
+    } catch (error) {
+      next(error);
+    }
+  }
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `enabled` | `boolean` / `false` | Enable Swagger UI + OpenAPI JSON endpoints. |
-| `docsPath` | `string` / `'/docs'` | Swagger UI route. |
-| `jsonPath` | `string` / `'/openapi.json'` | OpenAPI JSON route. |
-| `document` | `object \| null` / `null` | Inline OpenAPI document object. |
-| `documentPath` | `string` / `'openapi.json'` | JSON file path used when `document` is not provided. |
-| `explorer` | `boolean` / `true` | Enable Swagger UI explorer mode. |
+  static async create({ service, validator }, req, res, next) {
+    try {
+      const payload = validator.create(req.body || {});
+      const created = await service.create(payload);
+      res.status(201).json({ data: created });
+    } catch (error) {
+      next(error);
+    }
+  }
+}
 
-### Architecture (`architecture`)
+export default UsersView;
+```
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `strictLayers` | `boolean` / `false` | Enforce `route -> validator -> service -> model` restrictions. |
+Example requests:
 
-### Auto Mount (`autoMountApps`)
+```bash
+curl http://127.0.0.1:3000/users
 
-| Key | Type / Default | Description |
-| --- | --- | --- |
-| `autoMountApps` | `boolean` / `false` | If `true`, each `apps/<name>/routes.js` is mounted automatically from `settings.apps`. If `false`, central `routes.js` controls mounting. |
+curl -X POST http://127.0.0.1:3000/users \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Alice"}'
+```
 
-### Loaders (`loaders`)
+What the API middleware changes:
+- `POST`, `PUT`, `PATCH`, and `DELETE` with a request body must use `application/json` when `requireJsonForUnsafeMethods: true`.
+- `multipart/form-data` is still allowed for API mounts when `uploads.allowApiMultipart: true`.
+- CSRF is skipped only for configured API app mounts when `disableCsrf: true`.
+- API responses get `Cache-Control: no-store` when `noStoreHeaders: true`.
 
-`loaders` accepts an array of entries run in order during startup:
+What it does not change:
+- It does not auto-generate CRUD endpoints.
+- It does not force a separate `controllers/` or `api/` folder.
+- It does not convert a view into JSON automatically; your handler still decides what to return.
 
-1. Function entry:
+### API And Auth Together
 
-```js
-loaders: [
-  async ({ logger, options, config }) => {
-    logger.info('loader ran');
-  },
-]
-```
+`api` and `auth` are separate features that are often used together:
 
-2. Path entry (relative or absolute):
+- `api` makes an app behave like an API mount: JSON body enforcement, optional CSRF skip, and `Cache-Control: no-store`.
+- `auth` adds token issuance, token verification, route protection, client registration, and revocation/introspection behavior.
 
-```js
-loaders: ['loaders/init-db.js']
-```
+Examples:
+- Public JSON API: enable `api`, leave `auth.enabled` off.
+- Protected JSON API for your own frontend/mobile app: enable `api` and `auth.provider = 'jwt'`.
+- Protected partner/developer API: enable `api` and `auth.provider = 'oauth2'`.
 
-3. Object entry with options:
+Rule of thumb:
+- If you only need JSON routes, use `api`.
+- If you need authenticated access, add `auth`.
+- If outside clients need a standard auth protocol, choose OAuth2 instead of rolling custom JWT login flows.
 
-```js
-loaders: [
-  { path: 'loaders/init-queue.js', options: { queue: 'jobs' } },
-]
-```
+Quick comparison:
 
-Each loader module must export a function (default export preferred).
-Each loader receives the shared runtime context documented in the injection matrix above, plus `options` from the loader entry.
+| Setup | Use it when | What you configure |
+| --- | --- | --- |
+| `api` only | You need JSON endpoints without token auth. Good for public read APIs or trusted internal services. | `api.apps = [...]` |
+| `api` + JWT | Your own frontend/mobile app talks to your backend and you control both sides. | `api.apps = [...]`, `auth.enabled = true`, `auth.provider = 'jwt'`, plus your own login/token routes |
+| `api` + OAuth2 | External clients, partner apps, or machine clients need standard token flows. | `api.apps = [...]`, `auth.enabled = true`, `auth.provider = 'oauth2'` |
 
-### Apps (`apps`)
+### Database Config
 
-`apps` supports two forms:
+Use `database.config` for every dialect (SQL and MongoDB/Mongoose):
 
 ```js
-apps: ['users', 'billing']
+database: {
+  enabled: true,
+  dialect: 'pg', // pg | mysql | mssql | sqlite | oracle | mongo | mongodb | mongoose
+  config: {
+    // SQL example:
+    server: 'localhost',
+    port: 5432,
+    user: 'postgres',
+    password: 'postgres',
+    database: 'appdb',
+
+    // Mongo example:
+    // connectionString: 'mongodb://localhost:27017/appdb',
+    // or:
+    // server: 'localhost',
+    // port: 27017,
+    // database: 'appdb',
+    // user: 'mongo_user',
+    // password: 'mongo_pass',
+  },
+  options: {},
+},
 ```
 
-or
+Legacy note:
+- `database.uri` is still accepted for MongoDB, but `database.config.connectionString` is preferred.
+
+Model usage for `mongo` / `mongodb` / `mongoose`:
+- `dbClient` is a QueryMesh client, so you can use the same fluent API as SQL models.
 
 ```js
-apps: [
-  { name: 'users', mount: '/users' },
-  { name: 'billing', mount: '/payments' },
-]
+class UsersModel {
+  constructor({ dbClient }) {
+    this.db = dbClient;
+  }
+
+  async list() {
+    return this.db.table('users').select(['id', 'name']).get();
+  }
+}
 ```
 
-Rules:
-- `name` is required in object form.
-- `mount` defaults to `/${name}`.
-- Mounts are normalized to a single leading slash (except root `/`).
-- App route modules must be declared in `settings.apps` before they can load/mount.
+Mongo `_id` / `ObjectId` handling:
+- Use built-in helper `helpers.toObjectId(...)` before filtering on `_id`.
+- Validate with `helpers.isObjectId(...)` when needed.
+- Keep this conversion in model/service layer.
+- If your collection stores string `_id` values (not native Mongo `ObjectId`), skip conversion.
 
-### Environment Overrides (`environments`)
+```js
+class UsersModel {
+  constructor({ dbClient, helpers }) {
+    this.db = dbClient;
+    this.helpers = helpers;
+  }
 
-Example:
+  async findById(id) {
+    const _id = this.helpers.toObjectId(id);
+    if (!_id) throw new Error('Invalid Mongo ObjectId');
+    return this.db.table('users').where('_id', '=', _id).first();
+  }
+}
+```
+
+### Environment Overrides (Single settings.js)
+
+You can keep a single `settings.js` and define per-environment overrides:
 
 ```js
-environments: {
-  default: {
-    logging: { level: 'debug' },
+export default {
+  env: process.env.NODE_ENV || 'development',
+  logging: {
+    level: 'info',
   },
-  production: {
-    logging: { level: 'warn' },
-    security: { ddos: { maxRequests: 80 } },
+  security: {
+    ddos: {
+      maxRequests: 120,
+    },
   },
-}
+  environments: {
+    development: {
+      logging: { level: 'debug' },
+    },
+    production: {
+      logging: { level: 'warn' },
+      security: { ddos: { maxRequests: 80 } },
+    },
+  },
+};
 ```
 
 Behavior:
-- Base config loads first.
-- `environments.default` is merged next (if present).
-- `environments[env]` is merged last.
-- Arrays in overrides replace full arrays from base.
+- Base config is loaded first.
+- `environments.default` is applied (if present).
+- `environments[env]` is applied last.
+- `env` comes from `settings.env` (fallback: `NODE_ENV`, then `development`).
 
-<!-- SETTINGS_REFERENCE_END -->
+### Auth (JWT Or OAuth2)
 
-## Core Concepts And App Structure
+`auth` is independent from `api`.
+You can protect normal web routes, API routes, or both.
+If your app is already listed in `api.apps`, adding `auth` simply means those JSON routes can now require tokens.
 
-### App File Usage Examples
+Choose the provider based on who is calling your app:
 
-Each generated app usually contains:
-- `apps/<app>/views.js`
-- `apps/<app>/models.js`
-- `apps/<app>/services.js`
-- `apps/<app>/subscribers.js`
-- `apps/<app>/routes.js`
+- `provider: 'jwt'`
+  Best for first-party apps you control.
+  You create your own login/token/refresh/logout routes and call `auth.issue(...)` yourself.
+- `provider: 'oauth2'`
+  Best when you need a standard authorization server.
+  AegisNode mounts `/oauth/*` endpoints for you and supports `authorization_code` + PKCE, `client_credentials`, and `refresh_token`.
 
-Usage by file:
-- `views.js`: HTTP handlers (`req`, `res`, `next`). Default signature can be context-first: `handler({ service, validator, services, validators, ... }, req, res, next)`.
-- `models.js`: data access layer only (SQL/NoSQL operations).
-- `services.js`: business logic layer; orchestrates models.
-- `subscribers.js`: event listeners (for example `app.booted`, `ws.connection`, custom events).
-- `routes.js`: route mapping only (`route.get(...)`, `route.post(...)`, `route.use(...)`) to view handlers.
+Quick decision guide:
+- Use JWT when your own frontend/mobile app talks only to your backend.
+- Use OAuth2 when external clients, partner apps, or machine-to-machine integrations need standard token flows.
+- Use `auth.middleware()` to protect routes in both modes.
 
-Route modules are mapping-only (`register(route)`).
-Framework context is injected into handlers as first argument (when handler uses 4 args): `{ service, validator, services, models, validators, auth, mail, helpers, i18n, events, ... }`.
-`req.aegis` is also available.
-`service`/`validator` are app-scoped conveniences. For root/non-app routes, use `services.get('<app>.<name>')` / `validators.get('<app>.<name>')`, or create an app-scoped accessor with `services.forApp('<app>')`.
+Enable auth in `settings.js`:
 
-What “app-scoped” means:
-- In app routes (for example inside `apps/users/routes.js`), `{ service }` resolves to that app service.
-- In root/global routes (`routes.js`), there is no single app context, so use `{ services }` and fetch with `services.forApp('<app>').get('<name>')` or `services.get('<app>.<name>')`.
+```js
+auth: {
+  enabled: true,
+  provider: 'jwt', // or 'oauth2'
+  tablePrefix: 'aegisnode',
+  storage: {
+    // cache | memory | file | database
+    driver: 'cache',
+    filePath: 'storage/aegisnode-auth-store.json',
+    // Used by database driver for both SQL table and Mongo collection.
+    tableName: 'aegisnode_auth_store',
+  },
+  jwt: {
+    secret: 'replace-with-strong-secret',
+    algorithm: 'HS256',
+    expiresIn: '15m',
+    refreshExpiresIn: '7d',
+    issuer: 'blog',
+    audience: 'blog',
+  },
+  oauth2: {
+    accessTokenTtlSeconds: 3600,
+    refreshTokenTtlSeconds: 1209600,
+    authorizationCodeTtlSeconds: 600,
+    rotateRefreshToken: true,
+    requireClientSecret: true,
+    requirePkce: true,
+    allowPlainPkce: false,
+    grants: ['authorization_code', 'refresh_token', 'client_credentials'],
+    defaultScopes: [],
+    clientAuthMethod: 'client_secret_basic',
+    server: {
+      enabled: true,
+      basePath: '/oauth',
+      authorizePath: '/oauth/authorize',
+      tokenPath: '/oauth/token',
+      introspectionPath: '/oauth/introspect',
+      revocationPath: '/oauth/revoke',
+      metadataPath: '/.well-known/oauth-authorization-server',
+      issuer: '',
+      autoApprove: true,
+      requireAuthenticatedUser: true,
+      requireConsent: false,
+      allowHttp: false,
+    },
+  },
+},
+```
 
-Injected runtime dependencies:
+`tablePrefix` is used for auth storage names when enabled:
+- `${tablePrefix}_users`
+- `${tablePrefix}_jwt_revocations`
+- `${tablePrefix}_oauth_clients`
+- `${tablePrefix}_oauth_authorization_codes`
+- `${tablePrefix}_oauth_access_tokens`
+- `${tablePrefix}_oauth_refresh_tokens`
 
-AegisNode injects resolved runtime objects instead of asking app layers to import framework internals. `config` is the resolved runtime config from `settings.js` plus defaults and runtime overrides.
+By default, these names are used as key namespaces.
+- With `storage.driver = 'cache'` or `memory`, they are in-memory/cache key prefixes.
+- With `storage.driver = 'database'`, they are prefixes stored inside `auth.storage.tableName` (used as SQL table name or Mongo collection name).
 
-Available by layer:
-- Views/handlers (`views.js` or any context-first route/controller action): `appName`, `app`, `config`, `env`, `i18n`, `mail`, `logger`, `events`, `cache`, `io`, `auth`, `helpers`, `jlive`, `upload`, `services`, `models`, `validators`, `service`, `model`, `validator`, `database`, `dbClient`
-- Services (`constructor({ ... })`): `appName`, `config`, `env`, `i18n`, `mail`, `logger`, `events`, `cache`, `io`, `auth`, `helpers`, `jlive`, `models`, `validators`, `services`
-- Models (`constructor({ ... })`): `appName`, `config`, `env`, `i18n`, `mail`, `logger`, `events`, `cache`, `io`, `helpers`, `jlive`, `dbClient`, `database`
-- Validators (`constructor({ ... })`): `appName`, `config`, `env`, `i18n`, `mail`, `logger`, `events`, `cache`, `io`, `auth`, `helpers`, `jlive`, `dbClient`, `database`
-- Subscribers (`export default function ({ ... })`): `appName`, `rootDir`, `config`, `env`, `i18n`, `mail`, `logger`, `events`, `cache`, `io`, `auth`, `helpers`, `jlive`, `upload`, `services`, `models`, `validators`, `database`, `dbClient`, `app`, `server`, `templates`, `protocol`, `container`, `declaredAppNames`
-- Controllers (`constructor({ ... })`): `appName`, `rootDir`, `config`, `env`, `i18n`, `mail`, `logger`, `events`, `cache`, `io`, `auth`, `helpers`, `jlive`, `upload`, `services`, `models`, `validators`, `database`, `dbClient`, `container`, `app`
-- Loaders (`loaders` entry function): `rootDir`, `config`, `env`, `i18n`, `mail`, `logger`, `events`, `cache`, `io`, `auth`, `helpers`, `jlive`, `upload`, `services`, `models`, `validators`, `database`, `dbClient`, `app`, `server`, `templates`, `protocol`, `container`, `declaredAppNames`, `options`
-- Request bridge (`req.aegis`): `config`, `env`, `i18n`, `locale`, `localeSource`, `t`, `setLocale`, `logger`, `events`, `cache`, `io`, `auth`, `mail`, `helpers`, `jlive`, `upload`, `services`, `models`, `validators`, `database`, `dbClient`, `appName`, `app`
-- Template locals: `helpers`, `jlive`, `t`, `locale`, `i18n`, `money`, `number`, `dateTime`, `timeElapsed`, `timeDifference`, `breakStr`
+Restart behavior:
+- `auth.enabled = true`: auth manager is available in context after restart.
+- `auth.enabled = false`: auth manager stays safe; `auth.middleware()` returns `503` instead of crashing boot.
+- `auth.storage.driver = 'file'`: OAuth2 clients/tokens and JWT revocations persist across restarts.
+- `auth.storage.driver = 'database'`: OAuth2 clients/tokens and JWT revocations persist in your configured `database` backend.
 
-Key meanings:
+JWT usage in routes:
 
-| Key | Description |
-| --- | --- |
-| `config` | Resolved runtime config from `settings.js`, framework defaults, environment overrides, and runtime overrides. |
-| `env` | Frozen environment snapshot (`process.env` plus runtime additions such as `APP_SECRET`). |
-| `i18n` | Translator bridge. During a request it follows the active request locale; outside a request it falls back to `defaultLocale` unless you pass `{ locale }`. |
-| `mail` | Mail manager. Use `mail.send({ to, subject, text/html })` or `mail.sendMail(...)`. |
-| `logger` | Runtime logger instance. |
-| `events` | Event bus used by subscribers and app code. |
-| `cache` | Cache backend instance (memory by default). |
-| `io` | Socket.IO server instance when websocket support is enabled. |
-| `auth` | Auth manager for JWT/OAuth2 flows. |
-| `helpers` | Runtime helper functions such as `money`, `number`, `dateTime`, and `timeElapsed`. |
-| `jlive` | jlive bridge instance. |
-| `upload` | Upload manager used by `route.upload`. |
-| `services` | Layer accessor used to fetch services by app/name. |
-| `models` | Layer accessor used to fetch models by app/name. |
-| `validators` | Layer accessor used to fetch validators by app/name. |
-| `service` | App-scoped convenience service for the current app only. |
-| `model` | App-scoped convenience model for the current app only. |
-| `validator` | App-scoped convenience validator for the current app only. |
-| `database` | Database runtime wrapper. |
-| `dbClient` | Low-level database/query client. |
-| `appName` | Current app name. |
-| `app` | Current app metadata/context. |
-| `rootDir` | Absolute project root. |
-| `server` | HTTP/HTTPS server instance. |
-| `templates` | Resolved template-engine configuration. |
-| `protocol` | Server protocol (`http` or `https`). |
-| `container` | Internal DI container. |
-| `declaredAppNames` | Set of apps declared in config/routes. |
-| `options` | Loader-specific options object from a `{ path, options }` loader entry. |
-| `locale` | Active request locale. Available on `req.aegis` and template locals. |
-| `localeSource` | Where the current locale came from (`query`, `cookie`, `header`, `manual`, or `disabled`). |
-| `t` | Convenience translator shortcut for the current request/template scope. |
-| `setLocale` | Request helper used to change and optionally persist the active locale. |
+- JWT does not create login routes for you.
+- You define the endpoints that authenticate users and issue tokens.
+- This is usually the simplest choice for a private API used only by your own frontend/mobile app.
 
 ```js
-// routes.js (root/global)
 export default {
   register(route) {
-    route.get('/dashboard', async ({ services }, req, res, next) => {
-      try {
-        const usersService = services.forApp('users').get('users');
-        const ordersService = services.forApp('orders').get('orders');
-        res.json({
-          users: await usersService.list(),
-          orders: await ordersService.list(),
-        });
-      } catch (error) {
-        next(error);
-      }
+    const authGuard = (req, res, next) => req.aegis.auth.middleware()(req, res, next);
+
+    route.get('/auth/token', (req, res) => {
+      const token = req.aegis.auth.issue({ subject: 'u1', scope: ['read:users'] });
+      res.json({ token });
+    });
+
+    route.get('/auth/me', authGuard, (req, res) => {
+      res.json({ user: req.auth });
     });
   },
 };
 ```
 
-Example `views.js`:
+OAuth2 built-in authorization server endpoints (when `auth.provider='oauth2'` and `auth.oauth2.server.enabled=true`):
 
-```js
-class UsersView {
-  static async index({ service }, req, res, next) {
-    try {
-      const data = await service.listUsers();
-      res.json({ data });
-    } catch (error) {
-      next(error);
-    }
-  }
+- `GET /oauth/authorize`
+- `POST /oauth/authorize`
+- `POST /oauth/token`
+- `POST /oauth/introspect`
+- `POST /oauth/revoke`
+- `GET /.well-known/oauth-authorization-server`
 
-  static async create({ service, validator }, req, res, next) {
-    try {
-      const payload = validator.create(req.body || {});
-      const created = await service.createUser(payload);
-      res.status(201).json({ data: created });
-    } catch (error) {
-      next(error);
-    }
-  }
+Flows supported:
+- `authorization_code` (with PKCE)
+- `client_credentials`
+- `refresh_token`
 
-  static async tools({ service, helpers, jlive }, req, res, next) {
-    try {
-      const stats = await service.stats();
-      res.json({
-        stats,
-        total: helpers.money(1299.5, { currency: 'USD' }),
-        elapsed: helpers.timeElapsed(Date.now() - 60_000),
-        token: jlive.generate(16),
-      });
-    } catch (error) {
-      next(error);
-    }
-  }
-}
+OAuth2 is the better choice when:
+- you need standards-based client registration and token exchange,
+- you need machine clients as well as browser/mobile clients,
+- or third parties must integrate without depending on your custom JWT login route shape.
 
-export default UsersView;
-```
+#### Route Usage (JWT vs OAuth2)
 
-Example `models.js`:
+`startproject` gives you one root route file: `routes.js`.
+All your custom HTTP routes are defined there (or in app routes you mount with `route.use(...)`).
 
 ```js
-class UsersModel {
-  constructor({ dbClient }) {
-    this.dbClient = dbClient;
-  }
-
-  async list() {
-    return [{ id: '1', name: 'Alice' }];
-  }
+// routes.js
+import users from './apps/users/routes.js';
 
-  async create(payload) {
-    return { id: '2', ...payload };
-  }
-}
+export default {
+  register(route) {
+    route.use('/users', users);
 
-export default { users: UsersModel };
+    // Your custom auth/business routes
+    route.post('/auth/login', (req, res) => {
+      const token = req.aegis.auth.issue({ subject: 'u1' });
+      res.json({ token });
+    });
+  },
+};
 ```
 
-Example `services.js`:
-
-```js
-class UsersService {
-  constructor({ models, env }) {
-    this.usersModel = models.get('users');
-    this.env = env;
-  }
+How this behaves:
+- `provider: 'jwt'`: Aegis does not create JWT endpoints automatically. You define login/token/refresh/logout routes yourself in `routes.js` (or mounted app routes).
+- `provider: 'oauth2'`: Aegis auto-mounts OAuth2 server endpoints (`/oauth/authorize`, `/oauth/token`, `/oauth/introspect`, `/oauth/revoke`, metadata). You only define your own extra routes (for example admin client setup, protected APIs, business routes).
+- Do not reuse built-in OAuth2 endpoint paths for your own handlers when OAuth2 server is enabled.
 
-  async listUsers() {
-    return this.usersModel.list();
-  }
+Typical setup patterns:
+- API + JWT:
+  `api.apps = ['users']`, `auth.provider = 'jwt'`, custom `/auth/login`, protect `/users/*` with `req.aegis.auth.middleware()`.
+- API + OAuth2:
+  `api.apps = ['users']`, `auth.provider = 'oauth2'`, use built-in `/oauth/token`, protect `/users/*` with `req.aegis.auth.middleware()`.
+- Web app + JWT:
+  no `api` block required if routes are normal form/web routes, but you can still use JWT for selected endpoints.
 
-  async createUser(payload) {
-    return this.usersModel.create(payload);
-  }
-}
+#### OAuth2 Full Usage
 
-export default { users: UsersService };
-```
+1. Register clients (server-side only)
 
-Example `subscribers.js`:
+Register clients programmatically with `auth.registerClient(...)`.
+Do not expose this publicly in production without admin protection.
 
 ```js
-export default function registerUsersSubscribers({ events, logger }) {
-  events.subscribe('app.booted', ({ appName }) => {
-    logger.info('[users] booted: %s', appName);
-  });
-}
+export default {
+  register(route) {
+    route.post('/admin/oauth/setup-clients', (req, res) => {
+      const webClient = req.aegis.auth.registerClient({
+        clientId: 'web',
+        clientSecret: 'secret',
+        redirectUris: ['https://client.example.com/callback'],
+        grants: ['authorization_code', 'refresh_token'],
+        scopes: ['read:users'],
+      });
+
+      const machineClient = req.aegis.auth.registerClient({
+        clientId: 'machine',
+        clientSecret: 'machine-secret',
+        grants: ['client_credentials'],
+        scopes: ['read:users'],
+      });
+
+      res.json({ webClient, machineClient });
+    });
+  },
+};
 ```
 
-Injected `env` is also available in:
-- view handler context: `static index({ env }, req, res) { ... }`
-- model constructors: `constructor({ dbClient, env }) { ... }`
-- subscribers: `export default function ({ events, env }) { ... }`
-- request runtime bridge: `req.aegis.env`
+Notes:
+- Secret is stored hashed (scrypt).
+- Returned client object does not include the secret/hash.
+- `authorization_code` clients must have at least one `redirectUri`.
 
-Example `routes.js`:
+2. Authorization Code + PKCE flow
+
+Create PKCE verifier/challenge:
 
 ```js
-import UsersView from './views.js';
+import crypto from 'crypto';
 
-export default {
-  appName: 'users',
-  register(route) {
-    route.get('/home', UsersView.home);
-    route.get('/', UsersView.index);
-    route.post('/', UsersView.create);
-  },
-};
+function b64url(buffer) {
+  return Buffer.from(buffer).toString('base64')
+    .replace(/\+/g, '-')
+    .replace(/\//g, '_')
+    .replace(/=+$/g, '');
+}
+
+const codeVerifier = b64url(crypto.randomBytes(48));
+const codeChallenge = b64url(crypto.createHash('sha256').update(codeVerifier).digest());
 ```
 
-## Common Tasks And Feature Guides
+Redirect user-agent to authorize endpoint:
 
-### File Uploads
+```txt
+GET /oauth/authorize
+  ?response_type=code
+  &client_id=web
+  &redirect_uri=https%3A%2F%2Fclient.example.com%2Fcallback
+  &scope=read%3Ausers
+  &state=abc123
+  &code_challenge=<CODE_CHALLENGE>
+  &code_challenge_method=S256
+```
 
-AegisNode provides built-in upload middleware on route API as `route.upload`.
+The server redirects back to:
 
-Storage location:
-- Default folder: `<project-root>/uploads`
-- Change with `settings.uploads.dir` (relative or absolute path)
+```txt
+https://client.example.com/callback?code=<AUTH_CODE>&state=abc123
+```
 
-Recommended upload settings:
+Exchange code for tokens:
 
-```js
-uploads: {
-  enabled: true,
-  dir: 'storage/uploads',
-  createDir: true,
-  preserveExtension: true,
-  maxFileSize: '5mb',
-  maxFiles: 5,
-  maxFields: 50,
-  maxFieldSize: '1mb',
-  allowedMimeTypes: ['image/png', 'image/jpeg'],
-  allowedExtensions: ['.png', '.jpg', '.jpeg'],
-  allowApiMultipart: true,
-},
+```bash
+curl -X POST http://127.0.0.1:3000/oauth/token \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -u web:secret \
+  -d "grant_type=authorization_code" \
+  -d "code=<AUTH_CODE>" \
+  -d "redirect_uri=https://client.example.com/callback" \
+  -d "code_verifier=<CODE_VERIFIER>"
 ```
 
-Route middleware modes:
+Response shape:
 
-```js
-import UsersView from './views.js';
+```json
+{
+  "access_token": "...",
+  "token_type": "Bearer",
+  "expires_in": 3600,
+  "scope": "read:users",
+  "refresh_token": "...",
+  "refresh_expires_in": 1209600
+}
+```
 
+3. Protect API routes with OAuth2 access tokens
+
+```js
 export default {
-  appName: 'users',
   register(route) {
-    // One file -> req.file
-    route.post('/avatar', route.upload.single('avatar'), UsersView.uploadAvatar);
-
-    // Many files from one input name -> req.files (array)
-    route.post('/gallery', route.upload.array('photos', 6), UsersView.uploadGallery);
-
-    // Many named file inputs -> req.files.<fieldName> (array)
-    route.post(
-      '/documents',
-      route.upload.fields([
-        { name: 'avatar', maxCount: 1 },
-        { name: 'docs', maxCount: 3 },
-      ]),
-      UsersView.uploadDocuments,
-    );
-
-    // Accept all file fields -> req.files (array)
-    route.post('/any-upload', route.upload.any(), UsersView.uploadAny);
-
-    // No files, parse multipart text fields only
-    route.post('/multipart-no-file', route.upload.none(), UsersView.multipartNoFile);
+    const authGuard = (req, res, next) => req.aegis.auth.middleware()(req, res, next);
+    route.get('/users/me', authGuard, (req, res) => {
+      res.json({
+        sub: req.auth.sub || null,
+        clientId: req.auth.clientId,
+        scope: req.auth.scope,
+      });
+    });
   },
 };
 ```
 
-`req` payload shape:
-- `single()`: `req.file` + `req.body`
-- `array()`: `req.files` (array) + `req.body`
-- `fields()`: `req.files` object (`req.files.avatar`, `req.files.docs`, ...) + `req.body`
-
-Custom route with form fields + file:
-
-```js
-// apps/users/routes.js
-import UsersView from './views.js';
+Use token:
 
-export default {
-  appName: 'users',
-  register(route) {
-    route.post('/profile/update', route.upload.single('avatar'), UsersView.updateProfile);
-  },
-};
+```bash
+curl http://127.0.0.1:3000/users/me \
+  -H "Authorization: Bearer <ACCESS_TOKEN>"
 ```
 
-```js
-// apps/users/views.js
-class UsersView {
-  static updateProfile(_context, req, res) {
-    const { username, bio } = req.body;
-    const avatar = req.file || null;
-
-    return res.json({
-      username,
-      bio,
-      avatar: avatar ? {
-        name: avatar.filename,
-        originalName: avatar.originalname,
-        mimeType: avatar.mimetype,
-        size: avatar.size,
-        path: avatar.path,
-      } : null,
-    });
-  }
-}
+4. Refresh token flow
 
-export default UsersView;
+```bash
+curl -X POST http://127.0.0.1:3000/oauth/token \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -u web:secret \
+  -d "grant_type=refresh_token" \
+  -d "refresh_token=<REFRESH_TOKEN>"
 ```
 
-```html
-<form action="/users/profile/update" method="POST" enctype="multipart/form-data">
-  <%= csrfToken %>
-  <input name="username" />
-  <textarea name="bio"></textarea>
-  <input type="file" name="avatar" />
-  <button type="submit">Save</button>
-</form>
+5. Client Credentials flow (machine-to-machine)
+
+```bash
+curl -X POST http://127.0.0.1:3000/oauth/token \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -u machine:machine-secret \
+  -d "grant_type=client_credentials" \
+  -d "scope=read:users"
 ```
 
-Upload limits and rejections:
-- Per-file size limit from `uploads.maxFileSize` returns `413` when exceeded.
-- Total files limit from `uploads.maxFiles` returns `413` when exceeded.
-- `allowedMimeTypes` / `allowedExtensions` mismatch returns `415`.
+This returns access token only (no refresh token).
 
-Important behavior:
-- If `uploads.enabled=false`, using `route.upload.*` throws at route registration.
-- For API mounts, multipart is allowed only when `uploads.allowApiMultipart=true`.
-- For non-API form submissions, CSRF token is required by default.
+6. Introspection and revocation
 
-### API Apps
+Introspection:
 
-`api` does not create a separate app type. You still build a normal AegisNode app with `routes.js`, `views.js`, `services.js`, and `validators.js`.
-The `api` setting only changes middleware behavior for selected app mounts.
+```bash
+curl -X POST http://127.0.0.1:3000/oauth/introspect \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -u web:secret \
+  -d "token=<ACCESS_TOKEN>"
+```
 
-Think of it this way:
-- `api` controls request/response behavior for an app mount.
-- `auth` controls who can access routes and how tokens are issued/verified.
-- You can use `api` without auth, auth without `api`, or both together.
+Revocation:
 
-Common combinations:
-- `api` only: public or internal JSON endpoints with no token auth.
-- `api` + JWT: first-party SPA/mobile/frontend calling your own backend.
-- `api` + OAuth2: third-party clients, machine-to-machine access, or standards-based authorization flows.
+```bash
+curl -X POST http://127.0.0.1:3000/oauth/revoke \
+  -H "Content-Type: application/x-www-form-urlencoded" \
+  -u web:secret \
+  -d "token=<ACCESS_OR_REFRESH_TOKEN>"
+```
 
-Quick start:
+7. Custom subject/consent resolution
 
-1. Declare the app in `settings.apps` and give it a mount.
-2. Add that app name to `api.apps`.
-3. Mount the app at the same path in `routes.js` when `autoMountApps` is off.
-4. Return JSON from your handlers.
-5. Send JSON for unsafe methods unless you intentionally allow multipart uploads.
+By default, `/oauth/authorize` resolves subject from:
+- `req.user.id`
+- `req.user.sub`
+- `req.auth.sub`
+- `subject`/`user_id` query/body params
 
-Example `settings.js`:
+You can override with hooks in `settings.js`:
 
 ```js
-export default {
-  apps: [
-    { name: 'users', mount: '/users' },
-  ],
-  api: {
-    apps: ['users'],
-    disableCsrf: true,
-    requireJsonForUnsafeMethods: true,
-    noStoreHeaders: true,
+auth: {
+  provider: 'oauth2',
+  oauth2: {
+    server: {
+      resolveSubject: ({ req }) => req.user?.id || '',
+      resolveConsent: ({ req, client, subject }) => {
+        // return true to approve, false to deny
+        return true;
+      },
+    },
   },
-};
+},
 ```
 
-Example root `routes.js`:
+8. Production checklist
 
-```js
-import users from './apps/users/routes.js';
+- Keep `auth.oauth2.server.allowHttp = false` (default).
+- Use HTTPS with trusted reverse proxy config.
+- Keep `requirePkce = true`.
+- Use strong client secrets and rotate regularly.
+- Restrict client setup endpoints to admins only.
+- Set explicit `defaultScopes` and per-client scopes.
+- Set `issuer` to your public auth server URL.
 
-export default {
-  register(route) {
-    route.use('/users', users); // keep this aligned with settings.apps[].mount
-  },
-};
-```
+Implementation notes:
+- OAuth2 server in AegisNode is framework-native (custom implementation).
+- CSRF checks are skipped for OAuth2 server endpoints (`/oauth/*` + metadata) by design.
+- This is OAuth2 (not OpenID Connect); no `id_token` endpoint/flow.
 
-Example `apps/users/routes.js`:
+### Swagger (OpenAPI UI)
 
-```js
-import UsersView from './views.js';
+Enable Swagger in `settings.js`:
 
-export default {
-  appName: 'users',
-  register(route) {
-    route.get('/', UsersView.index);
-    route.post('/', UsersView.create);
-  },
-};
+```js
+swagger: {
+  enabled: true,
+  docsPath: '/docs',
+  jsonPath: '/openapi.json',
+  documentPath: 'openapi.json',
+  explorer: true,
+},
 ```
 
-Example `apps/users/views.js`:
+Behavior:
+- UI available at `docsPath` (default `/docs`).
+- OpenAPI JSON available at `jsonPath` (default `/openapi.json`).
+- If `openapi.json` exists in project root, it is loaded.
+- If no file is found, AegisNode serves a default minimal OpenAPI document.
 
-```js
-class UsersView {
-  static async index({ service }, req, res, next) {
-    try {
-      const users = await service.list();
-      res.json({ data: users });
-    } catch (error) {
-      next(error);
-    }
-  }
+### Templates (EJS + base.ejs)
 
-  static async create({ service, validator }, req, res, next) {
-    try {
-      const payload = validator.create(req.body || {});
-      const created = await service.create(payload);
-      res.status(201).json({ data: created });
-    } catch (error) {
-      next(error);
-    }
-  }
-}
+Set template config in `settings.js`:
 
-export default UsersView;
+```js
+templates: {
+  enabled: true,
+  engine: 'ejs',
+  dir: 'templates',
+  base: 'base',
+  appBases: {
+    users: 'users/base',
+    admin: 'admin/base',
+  },
+}
 ```
 
-Example requests:
+Then in a route handler:
 
-```bash
-curl http://127.0.0.1:3000/users
+```js
+route.get('/', (req, res) => {
+  res.render('home', {
+    title: 'Home',
+    message: 'Welcome',
+  });
+});
+```
 
-curl -X POST http://127.0.0.1:3000/users \
-  -H "Content-Type: application/json" \
-  -d '{"name":"Alice"}'
-```
+`home.ejs` is rendered first, then injected into `base.ejs`.
+Use `<%- content %>` (or `<%- body %>`) in your `base.ejs` to print page content.
 
-What the API middleware changes:
-- `POST`, `PUT`, `PATCH`, and `DELETE` with a request body must use `application/json` when `requireJsonForUnsafeMethods: true`.
-- `multipart/form-data` is still allowed for API mounts when `uploads.allowApiMultipart: true`.
-- CSRF is skipped only for configured API app mounts when `disableCsrf: true`.
-- API responses get `Cache-Control: no-store` when `noStoreHeaders: true`.
+### Internationalization (i18n)
 
-What it does not change:
-- It does not auto-generate CRUD endpoints.
-- It does not force a separate `controllers/` or `api/` folder.
-- It does not convert a view into JSON automatically; your handler still decides what to return.
+Configure i18n in `settings.js`:
 
-### API And Auth Together
+```js
+i18n: {
+  enabled: true,
+  defaultLocale: 'en',
+  fallbackLocale: 'en',
+  supported: ['en', 'fr'],
+  queryParam: 'lang',
+  translations: {
+    en: {
+      home: {
+        title: 'Welcome {name}',
+      },
+    },
+    fr: {
+      home: {
+        title: 'Bienvenue {name}',
+      },
+    },
+  },
+}
+```
 
-`api` and `auth` are separate features that are often used together:
+You can also load locale JSON files directly (no import needed):
 
-- `api` makes an app behave like an API mount: JSON body enforcement, optional CSRF skip, and `Cache-Control: no-store`.
-- `auth` adds token issuance, token verification, route protection, client registration, and revocation/introspection behavior.
+```js
+i18n: {
+  enabled: true,
+  defaultLocale: 'en',
+  supported: ['en', 'fr'],
+  translations: {
+    en: 'locales/en.json',
+    fr: 'locales/fr.json',
+  },
+  // optional single-file source (inline `translations` wins per locale key):
+  // translationsFile: 'locales/all.json',
+}
+```
 
-Examples:
-- Public JSON API: enable `api`, leave `auth.enabled` off.
-- Protected JSON API for your own frontend/mobile app: enable `api` and `auth.provider = 'jwt'`.
-- Protected partner/developer API: enable `api` and `auth.provider = 'oauth2'`.
+Route usage:
 
-Rule of thumb:
-- If you only need JSON routes, use `api`.
-- If you need authenticated access, add `auth`.
-- If outside clients need a standard auth protocol, choose OAuth2 instead of rolling custom JWT login flows.
+```js
+route.get('/i18n-demo', (req, res) => {
+  // Auto-detected from query/cookie/header.
+  res.json({
+    locale: req.aegis.locale,
+    title: req.aegis.t('home.title', { name: 'Jason' }),
+  });
+});
+```
 
-Quick comparison:
+Choosing the API:
 
-| Setup | Use it when | What you configure |
-| --- | --- | --- |
-| `api` only | You need JSON endpoints without token auth. Good for public read APIs or trusted internal services. | `api.apps = [...]` |
-| `api` + JWT | Your own frontend/mobile app talks to your backend and you control both sides. | `api.apps = [...]`, `auth.enabled = true`, `auth.provider = 'jwt'`, plus your own login/token routes |
-| `api` + OAuth2 | External clients, partner apps, or machine clients need standard token flows. | `api.apps = [...]`, `auth.enabled = true`, `auth.provider = 'oauth2'` |
+- `req.aegis.t('home.title')`
+  Shortcut for `req.aegis.i18n.t('home.title')`. Use this in routes/views when you only need a translated string.
+- `req.aegis.i18n`
+  Request-scoped i18n object. Use this when you also need locale metadata or helpers such as `locale`, `localeSource`, `setLocale(...)`, `resolveLocale(...)`, or `forLocale(...)`.
+- Injected `i18n` in handlers/services/models/validators/controllers/subscribers/loaders
+  Runtime-injected i18n bridge. During an HTTP request, `i18n.t(...)` resolves with the same active locale as `req.aegis.i18n.t(...)`, so the translation result is the same.
 
-### Database Config
+Important differences:
 
-Use `database.config` for every dialect (SQL and MongoDB/Mongoose):
+- `req.aegis.t` and `req.aegis.i18n.t` return the same translation for the current request.
+- Injected `i18n.t(...)` in a service/model/validator/subscriber is not the same object as `req.aegis.i18n`, but during a request it produces the same translation result for the same key/options.
+- Outside a request, injected `i18n.t(...)` falls back to `defaultLocale`.
+- In background jobs, loaders, or boot-time code, pass an explicit locale when needed: `i18n.t('home.title', { name: 'Jason' }, { locale: 'fr' })`.
+
+Service/model usage:
 
 ```js
-database: {
-  enabled: true,
-  dialect: 'pg', // pg | mysql | mssql | sqlite | oracle | mongo | mongodb | mongoose
-  config: {
-    // SQL example:
-    server: 'localhost',
-    port: 5432,
-    user: 'postgres',
-    password: 'postgres',
-    database: 'appdb',
+class UsersService {
+  constructor({ i18n }) {
+    this.i18n = i18n;
+  }
 
-    // Mongo example:
-    // connectionString: 'mongodb://localhost:27017/appdb',
-    // or:
-    // server: 'localhost',
-    // port: 27017,
-    // database: 'appdb',
-    // user: 'mongo_user',
-    // password: 'mongo_pass',
-  },
-  options: {},
-},
+  greeting(name) {
+    return this.i18n.t('home.title', { name });
+  }
+}
 ```
 
-Legacy note:
-- `database.uri` is still accepted for MongoDB, but `database.config.connectionString` is preferred.
+Template usage:
 
-Model usage for `mongo` / `mongodb` / `mongoose`:
-- `dbClient` is a QueryMesh client, so you can use the same fluent API as SQL models.
+```ejs
+<html lang="<%= locale %>">
+  <body>
+    <h1><%= t('home.title', { name: 'Jason' }) %></h1>
+  </body>
+</html>
+```
 
-```js
-class UsersModel {
-  constructor({ dbClient }) {
-    this.db = dbClient;
-  }
+Manual locale switch inside a request:
 
-  async list() {
-    return this.db.table('users').select(['id', 'name']).get();
-  }
-}
+```js
+route.get('/fr', (req, res) => {
+  req.aegis.setLocale('fr'); // persists in i18n cookie by default
+  res.send(req.aegis.t('home.title', { name: 'Jason' }));
+});
 ```
 
-Mongo `_id` / `ObjectId` handling:
-- Use built-in helper `helpers.toObjectId(...)` before filtering on `_id`.
-- Validate with `helpers.isObjectId(...)` when needed.
-- Keep this conversion in model/service layer.
-- If your collection stores string `_id` values (not native Mongo `ObjectId`), skip conversion.
+Persist user-selected language as default:
 
 ```js
-class UsersModel {
-  constructor({ dbClient, helpers }) {
-    this.db = dbClient;
-    this.helpers = helpers;
-  }
+route.post('/lang', (req, res) => {
+  const selected = String(req.body?.lang || '').trim();
+  req.aegis.setLocale(selected); // writes i18n cookie (aegis_locale by default)
+  res.redirect('back');
+});
+```
 
-  async findById(id) {
-    const _id = this.helpers.toObjectId(id);
-    if (!_id) throw new Error('Invalid Mongo ObjectId');
-    return this.db.table('users').where('_id', '=', _id).first();
-  }
-}
+Language picker template (keeps selected option):
+
+```ejs
+<form method="post" action="/lang">
+  <select name="lang">
+    <option value="en" <%= locale === 'en' ? 'selected' : '' %>>English</option>
+    <option value="fr" <%= locale === 'fr' ? 'selected' : '' %>>Français</option>
+  </select>
+  <button type="submit">Change</button>
+</form>
 ```
 
-### Environment Overrides (Single settings.js)
+Notes:
+- `defaultLocale` is used only when user has no saved locale.
+- After selection, cookie locale becomes the default for that user on next requests.
+- `?lang=fr` also persists automatically when `detectFromQuery` is enabled.
+- Templates get `t`, `locale`, and `i18n` in locals.
 
-You can keep a single `settings.js` and define per-environment overrides:
+### Mail
+
+Configure mail transport in `settings.js`:
 
 ```js
 export default {
-  env: process.env.NODE_ENV || 'development',
-  logging: {
-    level: 'info',
-  },
-  security: {
-    ddos: {
-      maxRequests: 120,
-    },
-  },
-  environments: {
-    development: {
-      logging: { level: 'debug' },
+  mail: {
+    enabled: true,
+    defaults: {
+      from: 'noreply@example.com',
+      replyTo: 'support@example.com',
     },
-    production: {
-      logging: { level: 'warn' },
-      security: { ddos: { maxRequests: 80 } },
+    transport: {
+      host: process.env.SMTP_HOST,
+      port: process.env.SMTP_PORT ? Number(process.env.SMTP_PORT) : 587,
+      secure: false,
+      auth: {
+        user: process.env.SMTP_USER,
+        pass: process.env.SMTP_PASS,
+      },
     },
+    verifyOnStartup: true,
   },
 };
 ```
 
-Behavior:
-- Base config is loaded first.
-- `environments.default` is applied (if present).
-- `environments[env]` is applied last.
-- `env` comes from `settings.env` (fallback: `NODE_ENV`, then `development`).
-
-### Auth (JWT Or OAuth2)
-
-`auth` is independent from `api`.
-You can protect normal web routes, API routes, or both.
-If your app is already listed in `api.apps`, adding `auth` simply means those JSON routes can now require tokens.
-
-Choose the provider based on who is calling your app:
-
-- `provider: 'jwt'`
-  Best for first-party apps you control.
-  You create your own login/token/refresh/logout routes and call `auth.issue(...)` yourself.
-- `provider: 'oauth2'`
-  Best when you need a standard authorization server.
-  AegisNode mounts `/oauth/*` endpoints for you and supports `authorization_code` + PKCE, `client_credentials`, and `refresh_token`.
+Available mail APIs:
 
-Quick decision guide:
-- Use JWT when your own frontend/mobile app talks only to your backend.
-- Use OAuth2 when external clients, partner apps, or machine-to-machine integrations need standard token flows.
-- Use `auth.middleware()` to protect routes in both modes.
+- Injected `mail` in handlers/services/models/validators/controllers/subscribers/loaders
+  Shared runtime mail manager. Use `mail.send(...)` or `mail.sendMail(...)`.
+- `req.aegis.mail`
+  Request bridge to the same mail manager used in handler context.
 
-Enable auth in `settings.js`:
+Handler usage:
 
 ```js
-auth: {
-  enabled: true,
-  provider: 'jwt', // or 'oauth2'
-  tablePrefix: 'aegisnode',
-  storage: {
-    // cache | memory | file | database
-    driver: 'cache',
-    filePath: 'storage/aegisnode-auth-store.json',
-    // Used by database driver for both SQL table and Mongo collection.
-    tableName: 'aegisnode_auth_store',
-  },
-  jwt: {
-    secret: 'replace-with-strong-secret',
-    algorithm: 'HS256',
-    expiresIn: '15m',
-    refreshExpiresIn: '7d',
-    issuer: 'blog',
-    audience: 'blog',
-  },
-  oauth2: {
-    accessTokenTtlSeconds: 3600,
-    refreshTokenTtlSeconds: 1209600,
-    authorizationCodeTtlSeconds: 600,
-    rotateRefreshToken: true,
-    requireClientSecret: true,
-    requirePkce: true,
-    allowPlainPkce: false,
-    grants: ['authorization_code', 'refresh_token', 'client_credentials'],
-    defaultScopes: [],
-    clientAuthMethod: 'client_secret_basic',
-    server: {
-      enabled: true,
-      basePath: '/oauth',
-      authorizePath: '/oauth/authorize',
-      tokenPath: '/oauth/token',
-      introspectionPath: '/oauth/introspect',
-      revocationPath: '/oauth/revoke',
-      metadataPath: '/.well-known/oauth-authorization-server',
-      issuer: '',
-      autoApprove: true,
-      requireAuthenticatedUser: true,
-      requireConsent: false,
-      allowHttp: false,
-    },
-  },
-},
-```
-
-`tablePrefix` is used for auth storage names when enabled:
-- `${tablePrefix}_users`
-- `${tablePrefix}_jwt_revocations`
-- `${tablePrefix}_oauth_clients`
-- `${tablePrefix}_oauth_authorization_codes`
-- `${tablePrefix}_oauth_access_tokens`
-- `${tablePrefix}_oauth_refresh_tokens`
-
-By default, these names are used as key namespaces.
-- With `storage.driver = 'cache'` or `memory`, they are in-memory/cache key prefixes.
-- With `storage.driver = 'database'`, they are prefixes stored inside `auth.storage.tableName` (used as SQL table name or Mongo collection name).
-
-Restart behavior:
-- `auth.enabled = true`: auth manager is available in context after restart.
-- `auth.enabled = false`: auth manager stays safe; `auth.middleware()` returns `503` instead of crashing boot.
-- `auth.storage.driver = 'file'`: OAuth2 clients/tokens and JWT revocations persist across restarts.
-- `auth.storage.driver = 'database'`: OAuth2 clients/tokens and JWT revocations persist in your configured `database` backend.
+route.post('/contact', async ({ mail }, req, res, next) => {
+  try {
+    const info = await mail.send({
+      to: 'support@example.com',
+      subject: 'Contact form',
+      text: req.body?.message || '',
+      html: `<p>${req.body?.message || ''}</p>`,
+    });
 
-JWT usage in routes:
+    res.status(202).json({ messageId: info.messageId });
+  } catch (error) {
+    next(error);
+  }
+});
+```
 
-- JWT does not create login routes for you.
-- You define the endpoints that authenticate users and issue tokens.
-- This is usually the simplest choice for a private API used only by your own frontend/mobile app.
+Service usage:
 
 ```js
-export default {
-  register(route) {
-    const authGuard = (req, res, next) => req.aegis.auth.middleware()(req, res, next);
-
-    route.get('/auth/token', (req, res) => {
-      const token = req.aegis.auth.issue({ subject: 'u1', scope: ['read:users'] });
-      res.json({ token });
-    });
+class UsersService {
+  constructor({ mail }) {
+    this.mail = mail;
+  }
 
-    route.get('/auth/me', authGuard, (req, res) => {
-      res.json({ user: req.auth });
+  async sendWelcome(user) {
+    return this.mail.send({
+      to: user.email,
+      subject: 'Welcome',
+      html: `<h1>Hello ${user.name}</h1><p>Your account is ready.</p>`,
     });
-  },
-};
+  }
+}
 ```
 
-OAuth2 built-in authorization server endpoints (when `auth.provider='oauth2'` and `auth.oauth2.server.enabled=true`):
-
-- `GET /oauth/authorize`
-- `POST /oauth/authorize`
-- `POST /oauth/token`
-- `POST /oauth/introspect`
-- `POST /oauth/revoke`
-- `GET /.well-known/oauth-authorization-server`
-
-Flows supported:
-- `authorization_code` (with PKCE)
-- `client_credentials`
-- `refresh_token`
+Notes:
+- `mail.send(...)` and `mail.sendMail(...)` are the same method.
+- Messages must include at least one of `to`, `cc`, or `bcc`.
+- Messages must include `from`, or configure `mail.defaults.from`.
+- For tests or custom providers, you can set `mail.transporter` or `mail.transportFactory` instead of `mail.transport`.
 
-OAuth2 is the better choice when:
-- you need standards-based client registration and token exchange,
-- you need machine clients as well as browser/mobile clients,
-- or third parties must integrate without depending on your custom JWT login route shape.
+### Helpers And jlive
 
-#### Route Usage (JWT vs OAuth2)
+Helpers and the `jlive` bridge are available in request context (`req.aegis`) and in EJS locals.
+They are also available in:
+- Service constructors (`constructor({ helpers, jlive, env, i18n, models, ... })`)
+- Model constructors (`constructor({ helpers, jlive, env, i18n, dbClient, ... })`)
+- Subscribers context (`registerSubscribers({ helpers, jlive, env, i18n, events, ... })`)
+- Any view/handler via request bridge: `req.aegis.helpers`, `req.aegis.jlive`, `req.aegis.env`, `req.aegis.locale`, `req.aegis.t`, `req.aegis.i18n`
 
-`startproject` gives you one root route file: `routes.js`.
-All your custom HTTP routes are defined there (or in app routes you mount with `route.use(...)`).
+Set helper defaults in `settings.js` (currency/locale):
 
 ```js
-// routes.js
-import users from './apps/users/routes.js';
-
-export default {
-  register(route) {
-    route.use('/users', users);
-
-    // Your custom auth/business routes
-    route.post('/auth/login', (req, res) => {
-      const token = req.aegis.auth.issue({ subject: 'u1' });
-      res.json({ token });
-    });
+helpers: {
+  locale: 'fr-FR',
+  money: {
+    currency: 'EUR',
+    currencyDisplay: 'code',
   },
-};
+},
 ```
 
-How this behaves:
-- `provider: 'jwt'`: Aegis does not create JWT endpoints automatically. You define login/token/refresh/logout routes yourself in `routes.js` (or mounted app routes).
-- `provider: 'oauth2'`: Aegis auto-mounts OAuth2 server endpoints (`/oauth/authorize`, `/oauth/token`, `/oauth/introspect`, `/oauth/revoke`, metadata). You only define your own extra routes (for example admin client setup, protected APIs, business routes).
-- Do not reuse built-in OAuth2 endpoint paths for your own handlers when OAuth2 server is enabled.
-
-Typical setup patterns:
-- API + JWT:
-  `api.apps = ['users']`, `auth.provider = 'jwt'`, custom `/auth/login`, protect `/users/*` with `req.aegis.auth.middleware()`.
-- API + OAuth2:
-  `api.apps = ['users']`, `auth.provider = 'oauth2'`, use built-in `/oauth/token`, protect `/users/*` with `req.aegis.auth.middleware()`.
-- Web app + JWT:
-  no `api` block required if routes are normal form/web routes, but you can still use JWT for selected endpoints.
-
-#### OAuth2 Full Usage
-
-1. Register clients (server-side only)
+Then `helpers.money(2500)` automatically uses your configured defaults unless you pass per-call overrides.
 
-Register clients programmatically with `auth.registerClient(...)`.
-Do not expose this publicly in production without admin protection.
+Route usage:
 
 ```js
 export default {
   register(route) {
-    route.post('/admin/oauth/setup-clients', (req, res) => {
-      const webClient = req.aegis.auth.registerClient({
-        clientId: 'web',
-        clientSecret: 'secret',
-        redirectUris: ['https://client.example.com/callback'],
-        grants: ['authorization_code', 'refresh_token'],
-        scopes: ['read:users'],
-      });
-
-      const machineClient = req.aegis.auth.registerClient({
-        clientId: 'machine',
-        clientSecret: 'machine-secret',
-        grants: ['client_credentials'],
-        scopes: ['read:users'],
+    route.get('/tools', (req, res) => {
+      res.json({
+        price: req.aegis.helpers.money(1299.5, { currency: 'USD' }),
+        createdAgo: req.aegis.helpers.timeElapsed(Date.now() - 60_000),
+        createdAgoShort: req.aegis.helpers.timeElapsed(Math.floor(Date.now() / 1000) - 60, true),
+        progress: req.aegis.helpers.timeDifference(65, 0, 100),
+        summary: req.aegis.helpers.breakStr('AegisNode framework helper utilities', 18, '...', true),
+        objectIdValid: req.aegis.helpers.isObjectId('507f1f77bcf86cd799439011'),
+        objectIdString: req.aegis.helpers.toObjectId('507f1f77bcf86cd799439011')?.toString() || null,
+        secret: req.aegis.jlive.generate(32),
+        jliveAvailable: req.aegis.jlive.available,
       });
-
-      res.json({ webClient, machineClient });
     });
   },
 };
 ```
 
-Notes:
-- Secret is stored hashed (scrypt).
-- Returned client object does not include the secret/hash.
-- `authorization_code` clients must have at least one `redirectUri`.
+Template usage (`res.render(...)`):
 
-2. Authorization Code + PKCE flow
+```ejs
+<h1><%= title %></h1>
+<p>Total: <%= money(1299.5, { currency: 'USD' }) %></p>
+<p>Updated: <%= timeElapsed(updatedAt) %></p>
+<p>Progress: <%= timeDifference(65, 0, 100) %>%</p>
+<p>Summary: <%= breakStr("AegisNode framework helper utilities", 18, "...", true) %></p>
+<p>With helper object: <%= helpers.number(1000000) %></p>
+```
 
-Create PKCE verifier/challenge:
+Available EJS locals:
+- `helpers`
+- `jlive`
+- `money`
+- `number`
+- `dateTime`
+- `timeElapsed`
+- `timeDifference`
+- `breakStr`
+- `isObjectId`
+- `toObjectId`
+- `locale`
+- `t`
+- `csrfToken` (raw hidden input HTML)
+- `csrfValue` (token string)
 
-```js
-import crypto from 'crypto';
+`timeElapsed` supports both styles:
+- `timeElapsed(value, { now, locale, numeric })` (Intl relative style)
+- `timeElapsed(unixTime, true)` (short legacy-style mode)
 
-function b64url(buffer) {
-  return Buffer.from(buffer).toString('base64')
-    .replace(/\+/g, '-')
-    .replace(/\//g, '_')
-    .replace(/=+$/g, '');
-}
+Mongo id helpers:
+- `isObjectId(value)` validates Mongo ObjectId format.
+- `toObjectId(value)` returns a Mongo ObjectId instance or `null` when invalid.
 
-const codeVerifier = b64url(crypto.randomBytes(48));
-const codeChallenge = b64url(crypto.createHash('sha256').update(codeVerifier).digest());
-```
+`jlive` behavior:
+- If `jlive` package is installed, bridge uses its methods.
+- If not installed, `jlive.generate()` still works (crypto fallback), while crypto methods throw `JLIVE_UNAVAILABLE`.
 
-Redirect user-agent to authorize endpoint:
-
-```txt
-GET /oauth/authorize
-  ?response_type=code
-  &client_id=web
-  &redirect_uri=https%3A%2F%2Fclient.example.com%2Fcallback
-  &scope=read%3Ausers
-  &state=abc123
-  &code_challenge=<CODE_CHALLENGE>
-  &code_challenge_method=S256
-```
-
-The server redirects back to:
-
-```txt
-https://client.example.com/callback?code=<AUTH_CODE>&state=abc123
-```
-
-Exchange code for tokens:
-
-```bash
-curl -X POST http://127.0.0.1:3000/oauth/token \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -u web:secret \
-  -d "grant_type=authorization_code" \
-  -d "code=<AUTH_CODE>" \
-  -d "redirect_uri=https://client.example.com/callback" \
-  -d "code_verifier=<CODE_VERIFIER>"
-```
+### Template Locals From Settings
 
-Response shape:
+You can inject custom functions/classes into all template renders from `settings.js`:
 
-```json
-{
-  "access_token": "...",
-  "token_type": "Bearer",
-  "expires_in": 3600,
-  "scope": "read:users",
-  "refresh_token": "...",
-  "refresh_expires_in": 1209600
-}
+```js
+templates: {
+  enabled: true,
+  engine: 'ejs',
+  dir: 'templates',
+  base: 'base',
+  locals: {
+    formatCurrency: (value) => '$' + Number(value || 0).toFixed(2),
+    ViewBag: class ViewBag {
+      constructor(title) {
+        this.title = title;
+      }
+    },
+  },
+},
 ```
 
-3. Protect API routes with OAuth2 access tokens
+You can also pass already-defined class/function references by name (object shorthand):
 
 ```js
+import { formatCurrency, ViewBag } from './app/template-locals.js';
+
 export default {
-  register(route) {
-    const authGuard = (req, res, next) => req.aegis.auth.middleware()(req, res, next);
-    route.get('/users/me', authGuard, (req, res) => {
-      res.json({
-        sub: req.auth.sub || null,
-        clientId: req.auth.clientId,
-        scope: req.auth.scope,
-      });
-    });
+  templates: {
+    locals: { formatCurrency, ViewBag },
   },
 };
 ```
 
-Use token:
-
-```bash
-curl http://127.0.0.1:3000/users/me \
-  -H "Authorization: Bearer <ACCESS_TOKEN>"
-```
+Note:
+- Use JS references/imports (as above).
+- String names like `{ formatCurrency: 'formatCurrency' }` are not auto-resolved.
 
-4. Refresh token flow
+Then in EJS:
 
-```bash
-curl -X POST http://127.0.0.1:3000/oauth/token \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -u web:secret \
-  -d "grant_type=refresh_token" \
-  -d "refresh_token=<REFRESH_TOKEN>"
+```ejs
+<p><%= formatCurrency(123.45) %></p>
+<p><%= new ViewBag('Dashboard').title %></p>
 ```
 
-5. Client Credentials flow (machine-to-machine)
-
-```bash
-curl -X POST http://127.0.0.1:3000/oauth/token \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -u machine:machine-secret \
-  -d "grant_type=client_credentials" \
-  -d "scope=read:users"
-```
+<!-- SETTINGS_REFERENCE_START -->
+## Full Settings Reference
 
-This returns access token only (no refresh token).
+All fields below are supported in `settings.js`. If you omit a field, AegisNode uses the runtime default.
 
-6. Introspection and revocation
+Merge order used at startup:
+1. Framework defaults (`defaultConfig`)
+2. `settings.js`
+3. Legacy `settings/index.js` (if present)
+4. Legacy `settings/db.js` (merged into `database`)
+5. Legacy `settings/cache.js` (merged into `cache`)
+6. Legacy `settings/apps.js` (used only when `settings.js` does not define apps)
+7. `environments.default`
+8. `environments[env]` where `env = settings.env` (fallback `NODE_ENV`, then `development`)
 
-Introspection:
+### Top-Level
 
-```bash
-curl -X POST http://127.0.0.1:3000/oauth/introspect \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -u web:secret \
-  -d "token=<ACCESS_TOKEN>"
-```
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `appName` | `string` / folder name | Application name used in logs and defaults. |
+| `env` | `string` / `process.env.NODE_ENV || 'development'` | Active environment key for `environments` overrides. |
+| `host` | `string` / `process.env.HOST || '0.0.0.0'` | Bind host for HTTP server. |
+| `port` | `number` / `process.env.PORT || 3000` | Bind port for HTTP server. |
+| `trustProxy` | `boolean \| number \| string` / `false` | Express `trust proxy` value. Set this when HTTPS is terminated by a reverse proxy/load balancer. |
+| `https` | `object \| false` / see HTTPS table | Direct TLS server settings for Node-hosted HTTPS. |
+| `staticDir` | `string \| null` / `null` | Static assets directory, relative to project root (if set). |
+| `templates` | `object \| false` / see templates table | EJS template engine + layout settings. |
+| `i18n` | `object` / see i18n table | Built-in locale detection + translator bridge (`req.aegis.t`, injected `i18n.t`). |
+| `helpers` | `object` / see helpers table | Runtime helper defaults (for example currency/locale for `helpers.money`). |
+| `security` | `object` / see security tables | Security headers, DDoS limiter, CSRF settings, app secret. |
+| `logging` | `object` / `{ level: 'info' }` | Runtime logger level. |
+| `database` | `object` / see database table | SQL or MongoDB connection settings. |
+| `cache` | `object` / `{ enabled: true, driver: 'memory' }` | Cache backend settings. |
+| `websocket` | `object` / `{ enabled: true, cors: { origin: false } }` | Socket.IO server options. |
+| `uploads` | `object` / see uploads table | Built-in file upload middleware settings used by `route.upload`. |
+| `mail` | `object` / see mail table | Nodemailer-backed mail manager available as injected `mail` and `req.aegis.mail`. |
+| `api` | `object` / see API table | API-app middleware behavior (JSON enforcement, no-store, CSRF skip for API mounts). |
+| `auth` | `object` / see auth tables | JWT or OAuth2 provider settings. |
+| `swagger` | `object` / see swagger table | OpenAPI JSON + Swagger UI settings. |
+| `architecture` | `object` / `{ strictLayers: false }` | Layering enforcement mode. |
+| `autoMountApps` | `boolean` / `false` | Auto-mount each app route file from `settings.apps`. |
+| `loaders` | `array` / `[]` | Startup loaders run before routes mounting. |
+| `apps` | `array` / `[]` | Declared apps with mount points. |
+| `environments` | `object` / `{}` | Environment-specific deep overrides. |
 
-Revocation:
+Notes:
+- `rootDir` is internal and set by runtime; do not manage it manually.
+- Arrays are replaced (not merged) during deep merge.
 
-```bash
-curl -X POST http://127.0.0.1:3000/oauth/revoke \
-  -H "Content-Type: application/x-www-form-urlencoded" \
-  -u web:secret \
-  -d "token=<ACCESS_OR_REFRESH_TOKEN>"
-```
+### HTTPS (`https`)
 
-7. Custom subject/consent resolution
+Use this only when Node should serve HTTPS directly. If HTTPS is handled by Passenger, Nginx, Apache, or another proxy, keep `https.enabled` off and set top-level `trustProxy` instead.
 
-By default, `/oauth/authorize` resolves subject from:
-- `req.user.id`
-- `req.user.sub`
-- `req.auth.sub`
-- `subject`/`user_id` query/body params
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` / `false` | Create an HTTPS server instead of HTTP. |
+| `key` | `string \| Buffer` / `null` | TLS private key content. |
+| `cert` | `string \| Buffer` / `null` | TLS certificate content. |
+| `ca` | `string \| Buffer \| array` / `null` | Optional CA/intermediate certificate content. |
+| `pfx` | `string \| Buffer` / `null` | PFX/PKCS#12 archive content. Use instead of `key` + `cert`. |
+| `keyPath` | `string` / `''` | Path to TLS private key, relative to project root or absolute. |
+| `certPath` | `string` / `''` | Path to TLS certificate, relative to project root or absolute. |
+| `caPath` | `string \| string[]` / `null` | Optional CA/intermediate certificate path(s). |
+| `pfxPath` | `string` / `''` | Path to PFX/PKCS#12 archive. |
+| `passphrase` | `string` / `''` | Optional passphrase for encrypted key/PFX files. |
+| `options` | `object` / `{}` | Extra Node `https.createServer` options (for example `minVersion`). |
 
-You can override with hooks in `settings.js`:
+Direct HTTPS example:
 
 ```js
-auth: {
-  provider: 'oauth2',
-  oauth2: {
-    server: {
-      resolveSubject: ({ req }) => req.user?.id || '',
-      resolveConsent: ({ req, client, subject }) => {
-        // return true to approve, false to deny
-        return true;
-      },
+export default {
+  host: '0.0.0.0',
+  port: 3443,
+  https: {
+    enabled: true,
+    keyPath: 'certs/localhost-key.pem',
+    certPath: 'certs/localhost-cert.pem',
+    options: {
+      minVersion: 'TLSv1.2',
     },
   },
-},
+};
 ```
 
-8. Production checklist
-
-- Keep `auth.oauth2.server.allowHttp = false` (default).
-- Use HTTPS with trusted reverse proxy config.
-- Keep `requirePkce = true`.
-- Use strong client secrets and rotate regularly.
-- Restrict client setup endpoints to admins only.
-- Set explicit `defaultScopes` and per-client scopes.
-- Set `issuer` to your public auth server URL.
-
-Implementation notes:
-- OAuth2 server in AegisNode is framework-native (custom implementation).
-- CSRF checks are skipped for OAuth2 server endpoints (`/oauth/*` + metadata) by design.
-- This is OAuth2 (not OpenID Connect); no `id_token` endpoint/flow.
-
-### Swagger (OpenAPI UI)
-
-Enable Swagger in `settings.js`:
+Reverse-proxy HTTPS example:
 
 ```js
-swagger: {
-  enabled: true,
-  docsPath: '/docs',
-  jsonPath: '/openapi.json',
-  documentPath: 'openapi.json',
-  explorer: true,
-},
+export default {
+  host: '127.0.0.1',
+  port: 3000,
+  trustProxy: 1,
+};
 ```
 
-Behavior:
-- UI available at `docsPath` (default `/docs`).
-- OpenAPI JSON available at `jsonPath` (default `/openapi.json`).
-- If `openapi.json` exists in project root, it is loaded.
-- If no file is found, AegisNode serves a default minimal OpenAPI document.
+Notes:
+- `https` requires either `pfx`/`pfxPath` or both `key`/`keyPath` and `cert`/`certPath`.
+- Paths resolve from project root unless absolute.
+- `trustProxy` affects `req.secure`, `req.protocol`, secure cookies, and OAuth2 secure transport checks.
+- Prefer `1`, a subnet, or another exact Express `trust proxy` value instead of `true` when rate limiting is enabled.
 
-### Templates (EJS + base.ejs)
+### Templates (`templates`)
 
-Set template config in `settings.js`:
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` / `true` | Enable template engine. |
+| `engine` | `string` / `'ejs'` | Template engine. Only `ejs` is supported. |
+| `dir` | `string` / `'templates'` | Templates folder (absolute or relative to project root). |
+| `base` | `string \| false \| null` / `'base'` | Default layout template (without `.ejs`). Set `false`/`null` to disable layout wrapping globally. |
+| `appBases` | `object` / `{}` | Per-app layout override map: `{ appName: 'layout/name' }`. Set app value to `false`/`null` to disable layout for that app only. |
+| `locals` | `object \| function` / `{}` | Global locals. If function, signature is `({ req, res, helpers, jlive, env }) => object`. |
 
-```js
-templates: {
-  enabled: true,
-  engine: 'ejs',
-  dir: 'templates',
-  base: 'base',
-  appBases: {
-    users: 'users/base',
-    admin: 'admin/base',
-  },
-}
-```
+Layout notes:
+- `res.render('view', data)` renders `view.ejs` and wraps it with `base.ejs` (or configured layout).
+- Per-app layout override: `templates.appBases = { users: 'users/base', admin: 'admin/base' }`.
+- In layout, both `<%- body %>` and `<%- content %>` are available.
+- Per-render layout override: pass `layout: 'custom-layout'` or `layout: false` in locals.
 
-Then in a route handler:
+### Internationalization (`i18n`)
 
-```js
-route.get('/', (req, res) => {
-  res.render('home', {
-    title: 'Home',
-    message: 'Welcome',
-  });
-});
-```
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` / `false` | Enable built-in i18n translator bridge. |
+| `defaultLocale` | `string` / `'en'` | Default locale used when detection fails. |
+| `fallbackLocale` | `string` / `'en'` | Fallback locale used when key is missing in active locale. |
+| `supported` | `string[]` / `['en']` | Allowed locales. Values normalize to lowercase (for example `en-US` -> `en-us`). |
+| `queryParam` | `string` / `'lang'` | Query parameter used for locale selection (for example `?lang=fr`). |
+| `cookieName` | `string` / `'aegis_locale'` | Cookie used to persist locale. |
+| `detectFromHeader` | `boolean` / `true` | Enable locale detection from `Accept-Language` header. |
+| `detectFromCookie` | `boolean` / `true` | Enable locale detection from configured cookie. |
+| `detectFromQuery` | `boolean` / `true` | Enable locale detection from query parameter. |
+| `translations` | `object` / `{}` | Translation map by locale. Values can be objects or JSON file paths: `{ en: { ... }, fr: 'locales/fr.json' }`. Alias keys `locales` and `messages` are also accepted. |
+| `translationsFile` | `string` / unset | Path to a JSON file containing all locales (example: `{ "en": {...}, "fr": {...} }`). Inline `translations` overrides file values for same locale keys. |
 
-`home.ejs` is rendered first, then injected into `base.ejs`.
-Use `<%- content %>` (or `<%- body %>`) in your `base.ejs` to print page content.
+i18n notes:
+- Detection order: query -> cookie -> `Accept-Language` -> `defaultLocale`.
+- Use dotted keys like `home.title`.
+- Placeholder interpolation supports `{name}` style tokens.
+- Relative JSON paths resolve from project root (`settings.js` location).
+- Injected `i18n` is available in handlers, services, models, validators, controllers, subscribers, and loaders. Use `i18n.t('key', vars, { locale })`.
+- During a request, injected `i18n.t(...)` follows the active request locale. Outside a request, it falls back to `defaultLocale`.
 
-### Internationalization (i18n)
+### Helpers Defaults (`helpers`)
 
-Configure i18n in `settings.js`:
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `locale` | `string` / `'en-US'` | Default locale used by runtime helpers when locale is not passed explicitly. |
+| `money` | `object` / `{ currency: 'USD' }` | Default money formatting settings used by `helpers.money`. |
+| `money.currency` | `string` / `'USD'` | Default currency code for `helpers.money(amount)` when no currency option is provided. |
+| `money.locale` | `string` / `helpers.locale` | Locale override only for `helpers.money`. |
+| `money.currencyDisplay` | `'symbol' | 'code' | 'name' | 'narrowSymbol'` / `'symbol'` | Currency display style passed to `Intl.NumberFormat`. |
+| `money.minimumFractionDigits` | `number` / unset | Optional minimum fraction digits for money formatting. |
+| `money.maximumFractionDigits` | `number` / unset | Optional maximum fraction digits for money formatting. |
+
+Helpers defaults notes:
+- Per-call options always override these defaults.
+- If `helpers.locale` is not set, AegisNode falls back to `i18n.defaultLocale` for helper locale.
+- Legacy shorthand keys are also accepted for compatibility: `helpers.currency`, top-level `currency`, and `app.currency`.
+
+### Security (`security`)
+
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `appSecret` | `string` / `''` | Shared secret for signing security artifacts. Use at least 16 chars. |
+| `headers` | `object` / see headers table | Helmet + CSP configuration. |
+| `ddos` | `object` / see ddos table | `express-rate-limit` based protection. |
+| `csrf` | `object` / see csrf table | CSRF cookie/token behavior. |
+
+#### Security Headers (`security.headers`)
+
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` / `true` | Enable Helmet middleware. |
+| `csp` | `object` / see CSP table | Content Security Policy behavior. |
+
+#### CSP (`security.headers.csp`)
+
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` / `true` | Enable CSP header from Helmet. |
+| `reportOnly` | `boolean` / `false` | Use report-only mode. |
+| `directives` | `object` / `{}` | Directive overrides. Set a directive to `false`/`null` to remove it. |
+
+Default CSP base includes safe defaults such as `defaultSrc 'self'`, `objectSrc 'none'`, `frameAncestors 'none'`, and websocket-aware `connectSrc`.
+
+Allow multiple external domains by adding them per directive (not globally):
 
 ```js
-i18n: {
-  enabled: true,
-  defaultLocale: 'en',
-  fallbackLocale: 'en',
-  supported: ['en', 'fr'],
-  queryParam: 'lang',
-  translations: {
-    en: {
-      home: {
-        title: 'Welcome {name}',
-      },
-    },
-    fr: {
-      home: {
-        title: 'Bienvenue {name}',
+security: {
+  headers: {
+    csp: {
+      directives: {
+        scriptSrc: ["'self'", 'https://cdn.jsdelivr.net', 'https://unpkg.com'],
+        scriptSrcElem: ["'self'", 'https://cdn.jsdelivr.net', 'https://unpkg.com'],
+        styleSrc: ["'self'", "'unsafe-inline'", 'https://cdn.jsdelivr.net'],
+        styleSrcElem: ["'self'", 'https://cdn.jsdelivr.net'],
+        imgSrc: ["'self'", 'data:', 'https://cdn.jsdelivr.net'],
+        connectSrc: ["'self'", 'https://api.example.com', 'wss://socket.example.com'],
       },
     },
   },
-}
+},
 ```
 
-You can also load locale JSON files directly (no import needed):
+Notes:
+- Add each origin to the exact directive needed (scripts, styles, images, API/WebSocket connections).
+- If browser reports a `script-src-elem` violation, whitelist the domain in `scriptSrcElem`.
+- Prefer explicit origins instead of `*` in production.
+
+Google Fonts example:
 
 ```js
-i18n: {
-  enabled: true,
-  defaultLocale: 'en',
-  supported: ['en', 'fr'],
-  translations: {
-    en: 'locales/en.json',
-    fr: 'locales/fr.json',
+security: {
+  headers: {
+    csp: {
+      directives: {
+        styleSrc: ["'self'", "'unsafe-inline'", 'https://fonts.googleapis.com'],
+        styleSrcElem: ["'self'", 'https://fonts.googleapis.com'],
+        fontSrc: ["'self'", 'data:', 'https://fonts.gstatic.com'],
+      },
+    },
   },
-  // optional single-file source (inline `translations` wins per locale key):
-  // translationsFile: 'locales/all.json',
-}
+},
 ```
 
-Route usage:
+#### DDoS / Rate Limit (`security.ddos`)
 
-```js
-route.get('/i18n-demo', (req, res) => {
-  // Auto-detected from query/cookie/header.
-  res.json({
-    locale: req.aegis.locale,
-    title: req.aegis.t('home.title', { name: 'Jason' }),
-  });
-});
-```
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` / `true` | Enable rate limiter. |
+| `windowMs` | `number` / `60000` | Rate limit window in milliseconds. |
+| `maxRequests` | `number` / `120` | Max requests per window per key. |
+| `message` | `string` / `'Too many requests, please try again later.'` | JSON error message text. |
+| `statusCode` | `number` / `429` | Response status code when limited. |
+| `standardHeaders` | `boolean` / `true` | Emit modern rate-limit headers. |
+| `legacyHeaders` | `boolean` / `false` | Emit legacy `X-RateLimit-*` headers. |
+| `skipSuccessfulRequests` | `boolean` / `false` | Do not count successful responses. |
+| `skipFailedRequests` | `boolean` / `false` | Do not count failed responses. |
+| `trustProxy` | `boolean \| number \| string` / `false` | Legacy alias for top-level `trustProxy`. Still supported for backward compatibility. |
+| `store` | `object \| null` / `null` | Custom rate-limit store implementation. |
+| `skipPaths` | `string[]` / `['/health']` | Path prefixes excluded from limiter. |
 
-Choosing the API:
+#### CSRF (`security.csrf`)
 
-- `req.aegis.t('home.title')`
-  Shortcut for `req.aegis.i18n.t('home.title')`. Use this in routes/views when you only need a translated string.
-- `req.aegis.i18n`
-  Request-scoped i18n object. Use this when you also need locale metadata or helpers such as `locale`, `localeSource`, `setLocale(...)`, `resolveLocale(...)`, or `forLocale(...)`.
-- Injected `i18n` in handlers/services/models/validators/controllers/subscribers/loaders
-  Runtime-injected i18n bridge. During an HTTP request, `i18n.t(...)` resolves with the same active locale as `req.aegis.i18n.t(...)`, so the translation result is the same.
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` / `true` | Enable CSRF middleware. |
+| `rejectForms` | `boolean` / `true` | Enforce CSRF on form submissions. |
+| `rejectUnsafeMethods` | `boolean` / `true` | Enforce CSRF for unsafe methods (`POST/PUT/PATCH/DELETE`) in general. |
+| `cookieName` | `string` / `'_aegis_csrf'` | CSRF cookie name. |
+| `fieldName` | `string` / `'_csrf'` | Body form field name for CSRF token. |
+| `headerName` | `string` / `'x-csrf-token'` | Header token key (normalized lowercase). |
+| `requireSignedCookie` | `boolean` / `true` | Require signed CSRF cookie values. |
+| `sameSite` | `'lax' \| 'strict' \| 'none' \| false` / `'lax'` | CSRF cookie same-site mode. |
+| `secure` | `boolean \| 'auto'` / `'auto'` | Secure cookie flag (`auto` respects request security). |
+| `httpOnly` | `boolean` / `true` | Make CSRF cookie httpOnly. |
+| `path` | `string` / `'/'` | CSRF cookie path. |
 
-Important differences:
+CSRF notes:
+- With `requireSignedCookie: true` (default), `security.appSecret` must be strong (minimum 16 chars) or startup fails.
+- CSRF is skipped for configured API app mounts when `api.disableCsrf: true`.
+- CSRF is skipped on built-in OAuth2 server endpoints.
 
-- `req.aegis.t` and `req.aegis.i18n.t` return the same translation for the current request.
-- Injected `i18n.t(...)` in a service/model/validator/subscriber is not the same object as `req.aegis.i18n`, but during a request it produces the same translation result for the same key/options.
-- Outside a request, injected `i18n.t(...)` falls back to `defaultLocale`.
-- In background jobs, loaders, or boot-time code, pass an explicit locale when needed: `i18n.t('home.title', { name: 'Jason' }, { locale: 'fr' })`.
+### Logging (`logging`)
 
-Service/model usage:
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `level` | `'error' \| 'warn' \| 'info' \| 'debug' \| 'trace'` / `'info'` | Logger verbosity threshold. |
 
-```js
-class UsersService {
-  constructor({ i18n }) {
-    this.i18n = i18n;
-  }
+### Database (`database`)
 
-  greeting(name) {
-    return this.i18n.t('home.title', { name });
-  }
-}
-```
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` / `false` | Enable database bootstrap. |
+| `dialect` | `string` / `'pg'` | SQL: `mysql`, `pg`/`postgres`/`postgresql`, `sqlite`, `mssql`, `oracle`; NoSQL: `mongo`/`mongodb`/`mongoose`. |
+| `config` | `object` / `{}` | Connection options passed to database driver. |
+| `options` | `object` / `{}` | Extra options (used directly for Mongo when enabled). |
+| `uri` | `string` / unset | Legacy Mongo URI fallback (still accepted). Prefer `config.connectionString`. |
 
-Template usage:
+Mongo config shortcuts accepted in `database.config`:
+- `connectionString` (preferred)
+- or `server`/`host`, `port`, `database`/`dbName`, `user`/`username`, `password`
 
-```ejs
-<html lang="<%= locale %>">
-  <body>
-    <h1><%= t('home.title', { name: 'Jason' }) %></h1>
-  </body>
-</html>
-```
+### Cache (`cache`)
 
-Manual locale switch inside a request:
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` / `true` | Enable cache service. |
+| `driver` | `string` / `'memory'` | Cache driver. Currently only `memory` is built-in. |
+| `options` | `object` / `{}` | Reserved for future/custom drivers. |
 
-```js
-route.get('/fr', (req, res) => {
-  req.aegis.setLocale('fr'); // persists in i18n cookie by default
-  res.send(req.aegis.t('home.title', { name: 'Jason' }));
-});
-```
+### WebSocket (`websocket`)
 
-Persist user-selected language as default:
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` / `true` | Enable Socket.IO server. |
+| `cors` | `object` / `{ origin: false }` | Passed directly to Socket.IO `cors` option. |
 
-```js
-route.post('/lang', (req, res) => {
-  const selected = String(req.body?.lang || '').trim();
-  req.aegis.setLocale(selected); // writes i18n cookie (aegis_locale by default)
-  res.redirect('back');
-});
-```
+### Uploads (`uploads`)
 
-Language picker template (keeps selected option):
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` / `true` | Enable built-in upload manager. |
+| `dir` | `string` / `'uploads'` | Upload destination folder (absolute or relative to project root). |
+| `createDir` | `boolean` / `true` | Create upload directory automatically on boot. |
+| `preserveExtension` | `boolean` / `true` | Preserve original file extension in generated file name. |
+| `maxFileSize` | `number \| string` / `5 * 1024 * 1024` | Per-file max size in bytes. String units like `'5mb'` are accepted. |
+| `maxFiles` | `number` / `5` | Max file count per request. |
+| `maxFields` | `number` / `50` | Max non-file form fields per request. |
+| `maxFieldSize` | `number \| string` / `1024 * 1024` | Max size per form field value. String units are accepted. |
+| `allowedMimeTypes` | `string[] \| string` / `[]` | Allowed MIME types. Empty means allow all. |
+| `allowedExtensions` | `string[] \| string` / `[]` | Allowed file extensions (`.jpg`, `.pdf`, ...). Empty means allow all. |
+| `allowApiMultipart` | `boolean` / `true` | Allow `multipart/form-data` on API mounts even when `api.requireJsonForUnsafeMethods` is true. |
 
-```ejs
-<form method="post" action="/lang">
-  <select name="lang">
-    <option value="en" <%= locale === 'en' ? 'selected' : '' %>>English</option>
-    <option value="fr" <%= locale === 'fr' ? 'selected' : '' %>>Français</option>
-  </select>
-  <button type="submit">Change</button>
-</form>
-```
+### Mail (`mail`)
+
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` / `false` | Enable the built-in mail manager. |
+| `defaults` | `object` / `{ from: '', replyTo: '' }` | Default message fields merged into every outgoing mail payload. |
+| `defaults.from` | `string` / `''` | Default sender used when `mail.send(...)` omits `from`. |
+| `defaults.replyTo` | `string` / `''` | Default `replyTo` header for outgoing mail. |
+| `transport` | `object \| string` / `{}` | Nodemailer transport config or SMTP connection URL passed to `nodemailer.createTransport(...)`. |
+| `transporter` | `object \| null` / `null` | Prebuilt transporter object with `sendMail()`. Useful in tests or custom integrations. |
+| `transportFactory` | `function \| null` / `null` | Factory that returns a transporter object with `sendMail()`. |
+| `verifyOnStartup` | `boolean` / `false` | Call `transporter.verify()` during boot when the transporter supports it. |
+
+Mail notes:
+- The runtime uses [Nodemailer](https://nodemailer.com/).
+- `mail.send(payload)` and `mail.sendMail(payload)` are aliases.
+- Each payload must include at least one of `to`, `cc`, or `bcc`.
+- Each payload must include `from`, or configure `mail.defaults.from`.
+- Injected `mail` is available in handlers, services, models, validators, controllers, subscribers, and loaders, plus `req.aegis.mail`.
+
+### API (`api`)
+
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `apps` | `string[]` / `[]` | App names treated as API apps. Mounts are resolved from `settings.apps`. |
+| `disableCsrf` | `boolean` / `true` | Skip CSRF checks for API app mounts. |
+| `requireJsonForUnsafeMethods` | `boolean` / `true` | Reject unsafe API payloads unless `Content-Type` is JSON (`415`). Multipart is allowed when `uploads.allowApiMultipart=true`. |
+| `noStoreHeaders` | `boolean` / `true` | Set `Cache-Control: no-store` on API responses. |
+
+API notes:
+- `api.apps` contains app names from `settings.apps`, not URL paths.
+- Marking an app as API does not generate REST routes or change the app file structure. It only applies API middleware to that app mount.
+- The effective API mount comes from `settings.apps[].mount` (or `/${app}` by default). Keep that aligned with your `route.use(...)` mount when `autoMountApps` is off.
+
+### Auth (`auth`)
+
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` / `false` | Enable auth manager. |
+| `provider` | `'jwt' \| 'oauth2'` / `'jwt'` | Active auth provider. |
+| `tablePrefix` | `string` / `'aegisnode'` | Prefix for auth storage namespaces/tables; sanitized to lowercase `[a-z0-9_]`. |
+| `storage` | `object` / see storage table | Persistence backend for auth state. |
+| `jwt` | `object` / see jwt table | JWT configuration. |
+| `oauth2` | `object` / see oauth2 table | OAuth2 server and token configuration. |
+
+#### Auth Storage (`auth.storage`)
+
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `driver` | `'cache' \| 'memory' \| 'file' \| 'database'` / `'cache'` | Storage backend for revocations/clients/tokens. |
+| `filePath` | `string` / `'storage/aegisnode-auth-store.json'` | Used when `driver: 'file'`. Relative to project root if not absolute. |
+| `tableName` | `string` / `'aegisnode_auth_store'` (prefix-based) | Used when `driver: 'database'` for SQL table or Mongo collection. |
+| `collectionName` | `string` / alias only | Legacy alias; if set and `tableName` missing, it becomes `tableName`. |
+
+#### JWT (`auth.jwt`)
+
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `secret` | `string` / `security.appSecret` fallback | Signing secret. Required for JWT auth. |
+| `algorithm` | `'HS256' \| 'HS384' \| 'HS512'` / `'HS256'` | JWT HMAC algorithm. |
+| `issuer` | `string` / `appName` | JWT issuer claim. |
+| `audience` | `string` / `appName` | JWT audience claim. |
+| `expiresIn` | `string` / `'15m'` | Access token TTL. |
+| `refreshExpiresIn` | `string` / `'7d'` | Refresh token TTL. |
+
+#### OAuth2 Core (`auth.oauth2`)
+
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `accessTokenTtlSeconds` | `number` / `3600` | Access token TTL in seconds. |
+| `refreshTokenTtlSeconds` | `number` / `1209600` | Refresh token TTL in seconds. |
+| `authorizationCodeTtlSeconds` | `number` / `600` | Authorization code TTL in seconds. |
+| `rotateRefreshToken` | `boolean` / `true` | Rotate refresh token on refresh flow. |
+| `requireClientSecret` | `boolean` / `true` | Require secret for confidential client flows. |
+| `requirePkce` | `boolean` / `true` | Require PKCE for authorization_code flow. |
+| `allowPlainPkce` | `boolean` / `false` | Allow PKCE `plain` method. |
+| `grants` | `string[]` / `['authorization_code','refresh_token','client_credentials']` | Enabled OAuth2 grants. |
+| `defaultScopes` | `string[]` / `[]` | Scopes assigned when none requested/provided. |
+| `clientAuthMethod` | `'client_secret_basic' \| 'client_secret_post' \| 'none'` / `'client_secret_basic'` | Default client authentication method. |
+| `server` | `object` / see OAuth2 server table | Built-in authorization server endpoint settings. |
+
+#### OAuth2 Server (`auth.oauth2.server`)
+
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` / `true` | Mount built-in OAuth2 endpoints. |
+| `basePath` | `string` / `'/oauth'` | Base path used to derive endpoint defaults. |
+| `authorizePath` | `string` / `'/oauth/authorize'` | Authorization endpoint path. |
+| `tokenPath` | `string` / `'/oauth/token'` | Token endpoint path. |
+| `introspectionPath` | `string` / `'/oauth/introspect'` | Introspection endpoint path. |
+| `revocationPath` | `string` / `'/oauth/revoke'` | Revocation endpoint path. |
+| `metadataPath` | `string` / `'/.well-known/oauth-authorization-server'` | OAuth2 metadata endpoint path. |
+| `issuer` | `string` / `server.baseUrl` fallback, then `appName` | Issuer value in OAuth2 metadata/tokens. |
+| `baseUrl` | `string` / optional alias | Alias used as fallback for `issuer` when `issuer` is empty. |
+| `autoApprove` | `boolean` / `true` | Auto-approve auth requests once subject is resolved. |
+| `requireAuthenticatedUser` | `boolean` / `true` | Require authenticated user/subject for authorize endpoint. |
+| `requireConsent` | `boolean` / `false` | Require explicit consent before issuing auth code. |
+| `allowSubjectFromParams` | `boolean` / `false` | Allow subject from request params (`subject`/`user_id`). Keep disabled in production. |
+| `allowHttp` | `boolean` / `false` | Allow OAuth2 endpoints on non-HTTPS requests. Keep `false` in production. |
+| `resolveSubject` | `function \| null` / `null` | Hook to resolve subject: `({ req, params, client }) => string|null`. |
+| `resolveConsent` | `function \| null` / `null` | Hook to resolve consent: `({ req, params, client, subject }) => boolean`. |
+
+### Swagger (`swagger`)
+
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `enabled` | `boolean` / `false` | Enable Swagger UI + OpenAPI JSON endpoints. |
+| `docsPath` | `string` / `'/docs'` | Swagger UI route. |
+| `jsonPath` | `string` / `'/openapi.json'` | OpenAPI JSON route. |
+| `document` | `object \| null` / `null` | Inline OpenAPI document object. |
+| `documentPath` | `string` / `'openapi.json'` | JSON file path used when `document` is not provided. |
+| `explorer` | `boolean` / `true` | Enable Swagger UI explorer mode. |
+
+### Architecture (`architecture`)
 
-Notes:
-- `defaultLocale` is used only when user has no saved locale.
-- After selection, cookie locale becomes the default for that user on next requests.
-- `?lang=fr` also persists automatically when `detectFromQuery` is enabled.
-- Templates get `t`, `locale`, and `i18n` in locals.
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `strictLayers` | `boolean` / `false` | Enforce `route -> validator -> service -> model` restrictions. |
 
-### Mail
+### Auto Mount (`autoMountApps`)
 
-Configure mail transport in `settings.js`:
+| Key | Type / Default | Description |
+| --- | --- | --- |
+| `autoMountApps` | `boolean` / `false` | If `true`, each `apps/<name>/routes.js` is mounted automatically from `settings.apps`. If `false`, central `routes.js` controls mounting. |
+
+### Loaders (`loaders`)
+
+`loaders` accepts an array of entries run in order during startup:
+
+1. Function entry:
 
 ```js
-export default {
-  mail: {
-    enabled: true,
-    defaults: {
-      from: 'noreply@example.com',
-      replyTo: 'support@example.com',
-    },
-    transport: {
-      host: process.env.SMTP_HOST,
-      port: process.env.SMTP_PORT ? Number(process.env.SMTP_PORT) : 587,
-      secure: false,
-      auth: {
-        user: process.env.SMTP_USER,
-        pass: process.env.SMTP_PASS,
-      },
-    },
-    verifyOnStartup: true,
+loaders: [
+  async ({ logger, options, config }) => {
+    logger.info('loader ran');
   },
-};
+]
 ```
 
-Available mail APIs:
-
-- Injected `mail` in handlers/services/models/validators/controllers/subscribers/loaders
-  Shared runtime mail manager. Use `mail.send(...)` or `mail.sendMail(...)`.
-- `req.aegis.mail`
-  Request bridge to the same mail manager used in handler context.
-
-Handler usage:
+2. Path entry (relative or absolute):
 
 ```js
-route.post('/contact', async ({ mail }, req, res, next) => {
-  try {
-    const info = await mail.send({
-      to: 'support@example.com',
-      subject: 'Contact form',
-      text: req.body?.message || '',
-      html: `<p>${req.body?.message || ''}</p>`,
-    });
-
-    res.status(202).json({ messageId: info.messageId });
-  } catch (error) {
-    next(error);
-  }
-});
+loaders: ['loaders/init-db.js']
 ```
 
-Service usage:
+3. Object entry with options:
 
 ```js
-class UsersService {
-  constructor({ mail }) {
-    this.mail = mail;
-  }
-
-  async sendWelcome(user) {
-    return this.mail.send({
-      to: user.email,
-      subject: 'Welcome',
-      html: `<h1>Hello ${user.name}</h1><p>Your account is ready.</p>`,
-    });
-  }
-}
+loaders: [
+  { path: 'loaders/init-queue.js', options: { queue: 'jobs' } },
+]
 ```
 
-Notes:
-- `mail.send(...)` and `mail.sendMail(...)` are the same method.
-- Messages must include at least one of `to`, `cc`, or `bcc`.
-- Messages must include `from`, or configure `mail.defaults.from`.
-- For tests or custom providers, you can set `mail.transporter` or `mail.transportFactory` instead of `mail.transport`.
+Each loader module must export a function (default export preferred).
+Each loader receives the shared runtime context documented in the injection matrix above, plus `options` from the loader entry.
 
-### Helpers And jlive
+### Apps (`apps`)
 
-Helpers and the `jlive` bridge are available in request context (`req.aegis`) and in EJS locals.
-They are also available in:
-- Service constructors (`constructor({ helpers, jlive, env, i18n, models, ... })`)
-- Model constructors (`constructor({ helpers, jlive, env, i18n, dbClient, ... })`)
-- Subscribers context (`registerSubscribers({ helpers, jlive, env, i18n, events, ... })`)
-- Any view/handler via request bridge: `req.aegis.helpers`, `req.aegis.jlive`, `req.aegis.env`, `req.aegis.locale`, `req.aegis.t`, `req.aegis.i18n`
+`apps` supports two forms:
 
-Set helper defaults in `settings.js` (currency/locale):
+```js
+apps: ['users', 'billing']
+```
+
+or
 
 ```js
-helpers: {
-  locale: 'fr-FR',
-  money: {
-    currency: 'EUR',
-    currencyDisplay: 'code',
-  },
-},
+apps: [
+  { name: 'users', mount: '/users' },
+  { name: 'billing', mount: '/payments' },
+]
 ```
 
-Then `helpers.money(2500)` automatically uses your configured defaults unless you pass per-call overrides.
+Rules:
+- `name` is required in object form.
+- `mount` defaults to `/${name}`.
+- Mounts are normalized to a single leading slash (except root `/`).
+- App route modules must be declared in `settings.apps` before they can load/mount.
 
-Route usage:
+### Environment Overrides (`environments`)
+
+Example:
 
 ```js
-export default {
-  register(route) {
-    route.get('/tools', (req, res) => {
-      res.json({
-        price: req.aegis.helpers.money(1299.5, { currency: 'USD' }),
-        createdAgo: req.aegis.helpers.timeElapsed(Date.now() - 60_000),
-        createdAgoShort: req.aegis.helpers.timeElapsed(Math.floor(Date.now() / 1000) - 60, true),
-        progress: req.aegis.helpers.timeDifference(65, 0, 100),
-        summary: req.aegis.helpers.breakStr('AegisNode framework helper utilities', 18, '...', true),
-        objectIdValid: req.aegis.helpers.isObjectId('507f1f77bcf86cd799439011'),
-        objectIdString: req.aegis.helpers.toObjectId('507f1f77bcf86cd799439011')?.toString() || null,
-        secret: req.aegis.jlive.generate(32),
-        jliveAvailable: req.aegis.jlive.available,
-      });
-    });
+environments: {
+  default: {
+    logging: { level: 'debug' },
   },
-};
+  production: {
+    logging: { level: 'warn' },
+    security: { ddos: { maxRequests: 80 } },
+  },
+}
 ```
 
-Template usage (`res.render(...)`):
-
-```ejs
-<h1><%= title %></h1>
-<p>Total: <%= money(1299.5, { currency: 'USD' }) %></p>
-<p>Updated: <%= timeElapsed(updatedAt) %></p>
-<p>Progress: <%= timeDifference(65, 0, 100) %>%</p>
-<p>Summary: <%= breakStr("AegisNode framework helper utilities", 18, "...", true) %></p>
-<p>With helper object: <%= helpers.number(1000000) %></p>
-```
+Behavior:
+- Base config loads first.
+- `environments.default` is merged next (if present).
+- `environments[env]` is merged last.
+- Arrays in overrides replace full arrays from base.
 
-Available EJS locals:
-- `helpers`
-- `jlive`
-- `money`
-- `number`
-- `dateTime`
-- `timeElapsed`
-- `timeDifference`
-- `breakStr`
-- `isObjectId`
-- `toObjectId`
-- `locale`
-- `t`
-- `csrfToken` (raw hidden input HTML)
-- `csrfValue` (token string)
+<!-- SETTINGS_REFERENCE_END -->
 
-`timeElapsed` supports both styles:
-- `timeElapsed(value, { now, locale, numeric })` (Intl relative style)
-- `timeElapsed(unixTime, true)` (short legacy-style mode)
+## Runtime Patterns And Advanced Topics
 
-Mongo id helpers:
-- `isObjectId(value)` validates Mongo ObjectId format.
-- `toObjectId(value)` returns a Mongo ObjectId instance or `null` when invalid.
+### Middleware
 
-`jlive` behavior:
-- If `jlive` package is installed, bridge uses its methods.
-- If not installed, `jlive.generate()` still works (crypto fallback), while crypto methods throw `JLIVE_UNAVAILABLE`.
+Route API supports Express-style middleware chains:
 
-### Template Locals From Settings
+```js
+route.get('/secured', authGuard, UsersView.index);
+route.post('/users', validateBody, createUser);
+```
 
-You can inject custom functions/classes into all template renders from `settings.js`:
+You can also use `route.use()`:
 
 ```js
-templates: {
-  enabled: true,
-  engine: 'ejs',
-  dir: 'templates',
-  base: 'base',
-  locals: {
-    formatCurrency: (value) => '$' + Number(value || 0).toFixed(2),
-    ViewBag: class ViewBag {
-      constructor(title) {
-        this.title = title;
-      }
-    },
-  },
-},
+route.use(requestLogger);
+route.use('/admin', adminGuard, adminRoutes);
 ```
 
-You can also pass already-defined class/function references by name (object shorthand):
+Basic middleware example:
 
 ```js
-import { formatCurrency, ViewBag } from './app/template-locals.js';
+function requestLogger(req, res, next) {
+  console.log(req.method, req.originalUrl);
+  next();
+}
+
+function requireModerator(req, res, next) {
+  if (!req.auth?.roles?.includes('moderator')) {
+    return res.status(403).json({ error: 'Moderator access required' });
+  }
+  next();
+}
 
 export default {
-  templates: {
-    locals: { formatCurrency, ViewBag },
+  register(route) {
+    route.use(requestLogger);
+    route.get('/threads/:id/edit', requireModerator, ThreadsView.edit);
+    route.use('/admin', requireModerator, adminRoutes);
   },
 };
 ```
 
-Note:
-- Use JS references/imports (as above).
-- String names like `{ formatCurrency: 'formatCurrency' }` are not auto-resolved.
+AegisNode-specific middleware with injected runtime context:
 
-Then in EJS:
+```js
+async function forumContext({ helpers, i18n, logger }, req, res, next) {
+  logger.info(`Forum request: ${req.method} ${req.originalUrl}`);
+  res.locals.t = i18n.t;
+  res.locals.formatNumber = helpers.number;
+  next();
+}
 
-```ejs
-<p><%= formatCurrency(123.45) %></p>
-<p><%= new ViewBag('Dashboard').title %></p>
+export default {
+  register(route) {
+    route.use(forumContext);
+    route.get('/threads', ThreadsView.index);
+  },
+};
 ```
 
-## Runtime Patterns And Advanced Topics
-
-### Middleware
+Injected middleware context can include:
+- `config`
+- `env`
+- `i18n`
+- `mail`
+- `logger`
+- `events`
+- `cache`
+- `io`
+- `auth`
+- `helpers`
+- `upload`
+- `services`
+- `models`
+- `validators`
+- `service`
+- `model`
+- `validator`
+- `database`
+- `dbClient`
 
-Route API supports Express-style middleware chains:
+Auth middleware example:
 
 ```js
-route.get('/secured', authGuard, UsersView.index);
-route.post('/users', validateBody, createUser);
+export default {
+  register(route) {
+    const authGuard = (req, res, next) => req.aegis.auth.middleware()(req, res, next);
+    route.get('/account', authGuard, UsersView.account);
+  },
+};
 ```
 
-You can also use `route.use()`:
+Uploads also work as route middleware:
 
 ```js
-route.use(requestLogger);
-route.use('/admin', adminGuard, adminRoutes);
+route.post('/avatar', route.upload.single('avatar'), UsersView.uploadAvatar);
 ```
 
+Important note:
+- In AegisNode, a 4-argument function is treated as `(context, req, res, next)`.
+- Do not use Express error-handler shape `(err, req, res, next)` in route chains, because the first argument is reserved for injected runtime context.
+
 ### Validators (Between Route And Service)
 
 Each app can define `apps/<app>/validators.js`.
@@ -2428,7 +2523,7 @@ security: {
 ```
 
 `security.appSecret` should be strong (at least 16 chars). It is used to sign CSRF cookies and is required when `security.csrf.requireSignedCookie` is true (default).
-New projects load it from `.env` through `APP_SECRET` by default.
+New projects load it from `.env` through `APP_SECRET` by default, and the generated `settings.js` also contains the same scaffold-time secret as a fallback literal.
 If neither `APP_SECRET` nor `security.appSecret` is set, AegisNode generates a fallback secret and persists it to `.aegis/app-secret`.
 If you run behind a reverse proxy, prefer top-level `trustProxy` (for example `1`) so client IP, secure-cookie detection, and HTTPS-aware auth logic are correct.
 
@@ -2447,6 +2542,8 @@ For forms, include token from `csrfToken`:
 </form>
 ```
 
+For `multipart/form-data` routes, use `route.upload.*` so AegisNode can parse the multipart body and validate the hidden `_csrf` field before your handler runs.
+
 If you need the raw token string (for AJAX header), use `csrfValue`.
 For API clients (Postman/mobile) you can either send `x-csrf-token` or set `security.csrf.rejectUnsafeMethods = false`.