webspresso 0.0.98 → 0.0.100

package/.agents/ADMIN.md

@@ -225,7 +225,7 @@ registry.registerWidget('recent-orders', {
   - Top tables by row count with visual progress percentage bars
   - Direct navigation links to model CRUD screens
 - **`quick-actions`**: Fast shortcuts to create new records across enabled models.
-- **`recent-activity`**: Timeline of recent administrative mutations (creates, updates, deletes).
+- **`recent-activity`**: Timeline of recent administrative mutations (creates, updates, deletes) powered by `audit_logs` / `admin_activity_logs` with direct links to record changes.
 
 ---
 
@@ -245,6 +245,16 @@ registry.registerAction('Product', {
   },
 });
 
+// Record action with navigation redirect (e.g. audit-timeline)
+registry.registerAction('Product', {
+  id: 'view-history',
+  label: 'History',
+  icon: 'clock',
+  handler: async (record, model) => {
+    return { redirect: `/_admin/audit-log?model=${model.name}&recordId=${record.id}` };
+  },
+});
+
 // Bulk multi-select table action
 registry.registerBulkAction('Product', {
   id: 'bulk-archive',

package/.agents/AGENTS.md

@@ -44,11 +44,11 @@ This `.agents/` customization root is organized into modular topic guides:
 6. **[HTTP Response Compression](.agents/COMPRESSION.md)** — Native streaming zlib compression (`server.compression`), Brotli/Gzip/Deflate negotiation, threshold handling, and `res.compress(false)` route opt-out.
 7. **[Dual Authentication System](.agents/AUTH.md)** — Stateful Session + Cookie & Stateless HS256 JWT + Refresh Token Rotation, `req.auth` helpers, and `middleware: ['jwt']` guard integrations.
 8. **[ORM & Database Layer](.agents/ORM.md)** — Model definitions with `defineModel`, `zdb` schemas, Repositories API, Query Caching, Relations, Soft Delete, Scopes & Migrations.
-9. **[Plugin Ecosystem Guide](.agents/PLUGINS.md)** — Lifecycle hooks (`register`, `onRoutesReady`), CSP headers, and detailed reference for all 18 built-in official plugins (including `xlsxPlugin`, `csvPlugin`, `fileManagerPlugin`, `realtimePlugin`, and `basicAuthPlugin`).
+9. **[Plugin Ecosystem Guide](.agents/PLUGINS.md)** — Lifecycle hooks (`register`, `onRoutesReady`), CSP headers, and detailed reference for all 20 built-in official plugins (including `webhooksPlugin`, `apiKeyPlugin`, `xlsxPlugin`, `csvPlugin`, `fileManagerPlugin`, `realtimePlugin`, and `basicAuthPlugin`).
 10. **[Realtime Layer & Adapters](.agents/REALTIME.md)** — Framework-agnostic realtime layer (`core/realtime`), generic WebSocket, SSE, and Socket.IO adapters, subscription identity, backoff reconnect, and auth lifecycle.
 11. **[Email Plugin Guide](.agents/EMAIL.md)** — MJML template compilation, Nodemailer transport, DB delivery logs, Auth Email bridge, and Admin UI.
 12. **[Admin Panel Customization](.agents/ADMIN.md)** — Extending Mithril.js Admin Panel SPA (Custom pages `component.js`, custom field renderers, widgets, single & bulk actions).
-13. **[CLI Tooling & Commands](.agents/CLI.md)** — `webspresso dev`, `build`, `doctor`, `db:migrate`, `db:seed`, `polar:migrate`, `favicon:generate`, `add:tailwind`, `agents:init`.
+13. **[CLI Tooling & Commands](CLI.md)** — `webspresso dev`, `build`, `doctor`, `db:migrate`, `db:seed`, `polar:migrate`, `favicon:generate`, `add:tailwind`, `add:docker`, `deploy:check`, `agents:init`.
 14. **[Development & Testing Workflow](.agents/WORKFLOW.md)** — CLI commands, Vitest unit/integration testing, Playwright E2E tests, TypeScript type checking, and zero regression policy.
 15. **[Coding Standards & Conventions](.agents/CONVENTIONS.md)** — Zero external dependencies policy, strict function signature & schema verification, clean component separation, and log traceback inspection rules.
 16. **[Background Job Queue](.agents/QUEUE.md)** — In-Memory, Knex Database, and Distributed Redis queue adapters, job auto-discovery (`jobs/`), retries, and graceful draining.

package/.agents/AUTH.md

@@ -45,6 +45,10 @@ Attached to Express request during auth middleware execution:
 | `req.auth.refreshAccessToken(refreshToken, options)` | Refresh access token & rotate refresh token |
 | `req.auth.check()` / `req.auth.guest()` | Check if user is authenticated or guest |
 | `req.auth.user()` / `req.auth.id()` | Get current user object or ID |
+| `req.auth.sessions()` | List active sessions & device info for current user |
+| `req.auth.revokeSession(sessionId)` | Revoke a specific session (remotely log out device) |
+| `req.auth.revokeOtherSessions()` | Revoke all sessions except the current active session |
+| `req.auth.revokeAllSessions(userId?)` | Revoke all active sessions (force logout from all devices) |
 
 ---
 
@@ -101,3 +105,414 @@ module.exports = {
   },
 };
 ```
+
+---
+
+## 5. Zero-Dependency OAuth 2.0 & Social Login (`plugins/oauth`, `core/auth/oauth`)
+
+Webspresso includes a built-in, zero-dependency OAuth 2.0 client and plugin with RFC 7636 PKCE, HMAC-SHA256 signed anti-CSRF state tokens, profile normalization, and seamless Dual Auth integration:
+
+### 5.1 Plugin Configuration
+```javascript
+const { createApp, oauthPlugin } = require('webspresso');
+
+const app = createApp({
+  plugins: [
+    oauthPlugin({
+      secret: process.env.SESSION_SECRET,
+      providers: {
+        google: {
+          clientId: process.env.GOOGLE_CLIENT_ID,
+          clientSecret: process.env.GOOGLE_CLIENT_SECRET,
+          // redirectUri is optional; auto-inferred from request host if omitted
+        },
+        github: {
+          clientId: process.env.GITHUB_CLIENT_ID,
+          clientSecret: process.env.GITHUB_CLIENT_SECRET,
+        },
+      },
+      // Optional hook to find or create the user in your database
+      async findOrCreateUser({ provider, profile, tokens, db }) {
+        let user = await db.getRepository('User').findOne({ email: profile.email });
+        if (!user) {
+          user = await db.getRepository('User').create({
+            email: profile.email,
+            name: profile.name,
+            avatar_url: profile.avatarUrl,
+          });
+        }
+        return user;
+      },
+      defaultReturnTo: '/dashboard',
+    }),
+  ],
+});
+```
+
+### 5.2 Automatic Routes
+- `GET /auth/:provider` (e.g. `/auth/google?returnTo=/dashboard`): Generates PKCE code challenge and HMAC-signed state token with embedded return URL, redirecting the browser to the provider's authorization page.
+- `GET /auth/:provider/callback`: Validates anti-CSRF state, exchanges authorization code for tokens, fetches normalized profile, calls `findOrCreateUser`, automatically establishes session via `req.auth.login(user)`, and redirects to `returnTo`. For API/mobile clients (`format=json` or `Accept: application/json`), returns `{ success: true, user, token }`.
+
+### 5.3 Template Helper (`fsy.oauthUrl`)
+In Nunjucks templates:
+```html
+<a href="{{ fsy.oauthUrl('google') }}" class="btn">Sign in with Google</a>
+<a href="{{ fsy.oauthUrl('github', { returnTo: '/settings' }) }}" class="btn">Connect GitHub</a>
+```
+
+---
+
+## 6. Zero-Dependency Two-Factor Authentication (2FA / TOTP)
+
+Webspresso provides an enterprise-grade, zero-dependency 2FA/TOTP suite adhering strictly to **RFC 6238 (TOTP)**, **RFC 4226 (HOTP)**, and **RFC 4648 (Base32)**. It requires NO external npm libraries and features offline SVG QR code generation to prevent leaking secret keys to third-party APIs.
+
+### 6.1 Key Capabilities
+- **RFC 6238 Time-Based OTP**: Standard 30s step, 6/8 digits, HMAC-SHA1/SHA256/SHA512.
+- **Time Drift Tolerance**: Built-in clock drift window (`window: 1` verifies $t \pm 30s$) and detailed delta analysis.
+- **Offline QR Code Generator**: Generates crisp vector SVG strings and data URIs directly in pure Node.js.
+- **Single-Use Recovery Codes**: Cryptographically secure alphanumeric codes, SHA-256 hashed storage, and timing-safe single-use burning.
+- **Session & Guard Integration**: `req.auth.verify2Fa()`, `req.auth.is2FaVerified()`, and `middleware: ['2fa']`.
+
+### 6.2 Initializing 2FA Setup for a User
+```javascript
+const { totp } = require('webspresso');
+
+// In an API route: POST /api/user/2fa/setup
+module.exports = {
+  middleware: ['auth'],
+  async handler(req, res) {
+    const setup = totp.createTotpSetup({
+      user: req.user,
+      issuer: 'My SaaS App',
+      recoveryCodeCount: 8,
+    });
+
+    // 1. Temporarily save secret and hashed recovery codes to DB for confirmation
+    await req.db.getRepository('User').update(req.user.id, {
+      temp_totp_secret: setup.secret,
+      temp_recovery_codes: JSON.stringify(setup.recoveryCodesHashed),
+    });
+
+    // 2. Return QR SVG and plaintext recovery codes for user to record
+    return res.json({
+      secret: setup.secret,
+      qrSvg: setup.qrSvg,
+      qrDataUri: setup.qrDataUri,
+      recoveryCodes: setup.recoveryCodes,
+    });
+  },
+};
+```
+
+### 6.3 Confirming 2FA Activation
+```javascript
+// In an API route: POST /api/user/2fa/confirm
+module.exports = {
+  middleware: ['auth'],
+  schema: ({ z }) => ({
+    body: z.object({ token: z.string().min(6).max(8) }),
+  }),
+  async handler(req, res) {
+    const user = req.user;
+    const { token } = req.input.body;
+
+    const isValid = totp.verifyTotp(token, user.temp_totp_secret);
+    if (!isValid) {
+      return res.status(400).json({ error: 'Invalid verification code' });
+    }
+
+    // Activate 2FA on user record
+    await req.db.getRepository('User').update(user.id, {
+      two_factor_enabled: true,
+      totp_secret: user.temp_totp_secret,
+      recovery_codes: user.temp_recovery_codes,
+      temp_totp_secret: null,
+      temp_recovery_codes: null,
+    });
+
+    req.auth.set2FaVerified(true);
+    return res.json({ success: true, message: '2FA enabled successfully' });
+  },
+};
+```
+
+### 6.4 2FA Login Flow & Guard Middleware
+```javascript
+// Step 1: Initial password login
+const user = await req.auth.findUserByCredentials(email, password);
+if (user.two_factor_enabled) {
+  // Mark session as 2FA pending without full login
+  req.auth.set2FaPending(user);
+  return res.json({ require2Fa: true });
+}
+await req.auth.login(user);
+
+// Step 2: 2FA Verification Endpoint (accepts 6-digit TOTP token OR recovery code)
+const verification = req.auth.verify2Fa(tokenOrRecoveryCode, user);
+if (verification.success) {
+  if (verification.type === 'recovery_code') {
+    // Burn used recovery code
+    await req.db.getRepository('User').update(user.id, {
+      recovery_codes: JSON.stringify(verification.remainingHashedCodes),
+    });
+  }
+  await req.auth.login(user);
+  req.auth.set2FaVerified(true);
+  return res.json({ success: true });
+}
+```
+
+### 6.5 Route Protection with `middleware: ['2fa']`
+```javascript
+// In pages/api/account/billing.get.js or pages/security/index.njk
+module.exports = {
+  middleware: ['auth', '2fa'], // Rejects unverified users with 403 or redirects to /2fa
+  async handler(req, res) {
+    return res.json({ secureData: true });
+  },
+};
+```
+
+---
+
+## 7. Magic Link & Passwordless Authentication
+
+Webspresso includes zero-dependency, cryptographically secure **Magic Link / Passwordless Authentication**:
+- **Single-Use Timed Tokens**: 32-byte cryptographically secure random tokens stored hashed (`SHA-256`) in the `auth_tokens` table (`type = 'magic_link'`) with a default 15-minute TTL.
+- **Anti-Enumeration Protection**: `requestMagicLink` returns `{ sent: true, userFound: false }` for unknown emails by default so attackers cannot probe user existence.
+- **Auto-Verification**: Successfully signing in via a magic link automatically marks `email_verified_at` if the user is not yet verified.
+- **Dual Session & JWT Support**: Seamlessly establishes web sessions (`req.auth.login`) and/or issues JWT access/refresh token pairs.
+- **Native Email Plugin Integration**: Built-in `auth-magic-link` MJML template, automated delivery via `plugins/email`'s `wireAuthEmails`, and pre-wired `/api/auth/magic-link` routes.
+
+### 7.1 Setup in `quickAuth`
+```javascript
+const { quickAuth } = require('webspresso/core/auth');
+
+const auth = quickAuth({
+  db,
+  userModel: 'User',
+  identifierField: 'email',
+  magicLink: true, // Automatically provisions Knex auth_tokens adapter
+});
+```
+
+### 7.2 Requesting a Magic Link (`pages/api/auth/magic-link.post.js`)
+```javascript
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  schema: ({ z }) => ({
+    body: z.object({
+      email: z.string().email(),
+    }),
+  }),
+  async handler(req, res) {
+    const { email } = req.input.body;
+
+    // Dispatches email notification via plugins/email (if active)
+    await req.auth.requestMagicLink(email, {
+      tokenTtlMs: 15 * 60 * 1000, // 15 mins (default)
+      path: '/auth/magic-link/verify',
+    });
+
+    return res.json({
+      ok: true,
+      message: 'If an account exists with this email, a sign-in link has been sent.',
+    });
+  },
+});
+```
+
+### 7.3 Verifying & Logging In (`pages/api/auth/magic-link/verify.get.js`)
+```javascript
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  schema: ({ z }) => ({
+    query: z.object({
+      token: z.string().min(1),
+    }),
+  }),
+  async handler(req, res) {
+    const { token } = req.input.query;
+
+    // Verifies token, consumes it, marks email verified, logs into session and/or generates JWTs
+    const result = await req.auth.loginWithMagicLink(token, {
+      remember: true,
+      jwt: false, // Set to true to receive accessToken and refreshToken
+    });
+
+    // For browser requests, redirect to dashboard:
+    if (req.accepts('html')) {
+      return res.redirect('/dashboard');
+    }
+
+    return res.json({ ok: true, user: result.user });
+  },
+});
+```
+
+### 7.4 Using Built-in Route Middlewares
+You can also mount Webspresso's pre-configured Express middlewares directly:
+```javascript
+const {
+  createMagicLinkRequestHandler,
+  createMagicLinkVerifyMiddleware,
+} = require('webspresso/core/auth');
+
+// Request link: POST /auth/magic-link
+app.post('/auth/magic-link', createMagicLinkRequestHandler(authManager));
+
+// Verify & Login: GET /auth/magic-link/verify
+app.get('/auth/magic-link/verify', createMagicLinkVerifyMiddleware(authManager, {
+  redirectTo: '/dashboard',
+  failureRedirect: '/login?error=invalid_magic_link',
+  jwt: false,
+}));
+```
+
+### 7.5 AuthManager Magic Link Events
+`AuthManager` extends `EventEmitter`, allowing you to hook into magic link lifecycle events:
+```javascript
+authManager.on('magicLink:requested', ({ userId, email, expiresAt }) => {
+  console.log(`Magic link requested for ${email}, expires at ${expiresAt}`);
+});
+
+authManager.on('magicLink:verified', ({ userId }) => {
+  console.log(`User ${userId} signed in via magic link`);
+});
+```
+
+---
+
+## 8. Active Devices & Remote Session Revocation
+
+Webspresso provides a zero-dependency session management and device tracking system (`webspresso/core/auth`) allowing users to view all active logins, detect browser/OS/hardware types, and remotely revoke unwanted sessions.
+
+### 8.1 Database Migration
+Create the `user_sessions` table using the built-in migration helper:
+```javascript
+const { createUserSessionsTable } = require('webspresso/core/auth');
+
+exports.up = async function(knex) {
+  await createUserSessionsTable(knex);
+};
+
+exports.down = async function(knex) {
+  const { dropUserSessionsTable } = require('webspresso/core/auth');
+  await dropUserSessionsTable(knex);
+};
+```
+
+Schema columns:
+- `id`: Bigint primary key
+- `session_id`: Unique Express session ID
+- `user_id`: User ID reference
+- `ip_address`: Proxy-safe client IP (`x-forwarded-for`, `x-real-ip`, or socket)
+- `user_agent`: Raw User-Agent string
+- `browser`: Detected browser and version (e.g. `Chrome 128`, `Safari 17`, `Firefox 125`, `Edge 122`)
+- `os`: Detected operating system (e.g. `macOS 14`, `Windows 10/11`, `iOS 17.4`, `Android 14`, `Ubuntu Linux`)
+- `device`: Device form factor (`desktop`, `mobile`, `tablet`, `bot`)
+- `last_active_at`: Last seen timestamp (throttled to 60s by default to protect DB performance)
+- `created_at`: Initial login timestamp
+
+### 8.2 Enabling Session Tracking
+Enable session tracking in `createAuth` or `quickAuth`:
+```javascript
+const { quickAuth } = require('webspresso/core/auth');
+
+const auth = quickAuth({
+  db,
+  sessionTracking: true, // Automatically enables Knex session tracker and active session verification
+});
+```
+
+Or manually with custom options:
+```javascript
+const { createAuth, createKnexSessionTracker } = require('webspresso/core/auth');
+
+const auth = createAuth({
+  db,
+  sessionTracking: true,
+  sessionTracker: createKnexSessionTracker(db),
+  sessionTouchThrottleMs: 60000, // Touch session at most once per minute
+  // ...other config
+});
+```
+
+### 8.3 File-Based API Routes (`pages/api/*`)
+
+#### List Active Devices (`pages/api/auth/sessions.get.js`)
+```javascript
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  middleware: ['auth'],
+  async handler(req, res) {
+    // Returns array of active sessions with is_current flag for current device
+    const sessions = await req.auth.sessions();
+    return res.json({ ok: true, sessions });
+  },
+});
+```
+
+#### Revoke Session / Remote Logout (`pages/api/auth/sessions/revoke.post.js`)
+```javascript
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  middleware: ['auth'],
+  schema: ({ z }) => ({
+    body: z.object({
+      sessionId: z.string().optional(),
+      allOthers: z.boolean().optional(),
+    }),
+  }),
+  async handler(req, res) {
+    const { sessionId, allOthers } = req.input.body;
+
+    if (allOthers) {
+      // Revokes all sessions except current device
+      const count = await req.auth.revokeOtherSessions();
+      return res.json({ ok: true, revokedCount: count, message: 'All other sessions revoked' });
+    }
+
+    if (sessionId) {
+      // Revokes specified session (logs out current user if it is the current session)
+      await req.auth.revokeSession(sessionId);
+      return res.json({ ok: true, message: 'Session revoked' });
+    }
+
+    return res.status(400).json({ error: 'sessionId or allOthers is required' });
+  },
+});
+```
+
+### 8.4 Automatic Invalidation in Middleware
+When a session is revoked remotely, Webspresso's `authenticate` middleware automatically detects it on the next incoming request from that device:
+- The revoked session is destroyed in `req.sessionStore`.
+- `req.user` is set to `null`.
+- Any subsequent `requireAuth` or `middleware: ['auth']` guard immediately redirects or rejects the request with `401 Unauthorized`.
+
+### 8.5 Session Lifecycle Events
+`AuthManager` emits EventEmitter events for monitoring and security audits:
+```javascript
+auth.on('session:created', ({ sessionId, userId, ip, browser, os, device }) => {
+  console.log(`New session created for user ${userId} from ${device} (${browser} on ${os}) at ${ip}`);
+});
+
+auth.on('session:revoked', ({ sessionId, userId, revokedBy }) => {
+  console.log(`Session ${sessionId} was revoked`);
+});
+
+auth.on('sessions:revoked_others', ({ userId, currentSessionId, count }) => {
+  console.log(`User ${userId} revoked ${count} other sessions`);
+});
+
+auth.on('sessions:revoked_all', ({ userId, count }) => {
+  console.log(`All ${count} sessions revoked for user ${userId}`);
+});
+```
+
+
+

package/.agents/CLI.md

@@ -302,8 +302,55 @@ npx webspresso typegen --out types/webspresso.d.ts --no-env-file
 - **Typed Services (`req.service('name', input)`)**: Auto-completes registered service names and enforces validated input payloads.
 - **Typed Route Table (`AppRoute`, `AppRoutePath`)**: Union types for all discovered SSR and API routes.
 
+---
+
+## 16. Containerization & Docker Setup (`add:docker` / `docker`)
+
+Generate production-ready, security-hardened, multi-stage `Dockerfile`, `.dockerignore`, and `docker-compose.yml`:
+
+```bash
+# Generate Dockerfile, .dockerignore, and docker-compose.yml
+npx webspresso add:docker
+
+# Customize Node.js version, database service, or container port
+npx webspresso add:docker --node 22-alpine --db postgres --redis --port 3000
 
+# Overwrite existing files
+npx webspresso add:docker --force
+```
 
+### Generated Artifacts:
+- **Multi-Stage `Dockerfile`**:
+  - `deps` stage: caches production dependencies with native build tools (`python3`, `make`, `g++`).
+  - `builder` stage: runs asset build scripts (`npm run build`).
+  - `runner` stage: runs as unprivileged user `webspresso` (UID 1001), health check with `/health` and `/healthz`, and `SIGTERM` signal handling.
+- **`.dockerignore`**: Excludes `node_modules`, `.env`, local `.sqlite` databases, test files, and git metadata while preserving upload directories.
+- **`docker-compose.yml`**: Configures app container with persistent upload volumes, database services (PostgreSQL, MySQL, or SQLite), and optional Redis.
+- **`package.json` Scripts**: Adds `docker:build`, `docker:run`, `docker:up`, and `docker:down`.
 
+---
 
+## 17. Production Deployment Preflight Check (`deploy:check` / `check:deploy`)
+
+Run comprehensive pre-flight verification before deploying to Fly.io, Railway, Render, VPS, or Kubernetes:
+
+```bash
+# Run production preflight verification
+npx webspresso deploy:check
+
+# Run against a specific environment (.env.staging or .env.production)
+npx webspresso deploy:check --env staging
+
+# Strict mode: fail with exit code 1 on warnings as well as errors (ideal for CI/CD)
+npx webspresso deploy:check --strict
+
+# Machine-readable JSON output for automated deployment pipelines
+npx webspresso deploy:check --json
+```
 
+### Audited Verification Areas:
+1. **Secrets & Cryptography**: Ensures `SESSION_SECRET` or `APP_KEY` is set, >= 32 characters, and not using weak placeholder defaults.
+2. **Git & Leak Prevention**: Verifies `.env` and local database files are excluded in `.gitignore`.
+3. **Container Hardening**: Ensures `Dockerfile` runs as a non-root `USER`, configures a `HEALTHCHECK`, and uses multi-stage caching.
+4. **Database & Migrations**: Audits for pending unapplied migrations and warns against ephemeral SQLite storage.
+5. **Server Optimizations**: Validates HTTP compression (`compression: true`), graceful shutdown, and health check endpoints.

package/.agents/ERRORS.md

@@ -199,3 +199,62 @@ In server logs, 500 errors are automatically highlighted with visual banners pin
   Phase:  handler
 ```
 
+---
+
+## 6. Directory-Level Error Boundaries (`_error.njk` & `_error.js`)
+
+In addition to API JSON errors and the top-level 500 error page, Webspresso provides **Directory-Level Error Boundaries** for SSR pages (similar to Next.js `error.js` or Nuxt `error.vue`):
+
+```
+pages/
+├── _layout.njk                # Root site layout
+├── _error.njk                 # Global site error fallback
+└── dashboard/
+    ├── _layout.njk            # Dashboard layout (sidebar, header)
+    ├── _error.njk             # Dashboard-scoped error boundary
+    ├── _error.js              # Optional companion loader
+    ├── billing/
+    │   └── invoices.njk       # If load() fails here...
+    └── settings.njk
+```
+
+### 6.1 Isolated Error Containment
+When an unhandled error is thrown in a page route's `load()`, template rendering, or lifecycle hooks:
+1. Webspresso searches up the directory hierarchy (innermost leaf to root `pages/`) for the nearest `_error.njk`.
+2. The error boundary is rendered **inside** the ancestor cascading layouts (`_layout.njk`), ensuring that headers, sidebars, and navigation remain visible while displaying the isolated error state.
+3. The HTTP response status is preserved from `error.status || error.statusCode || 500` (e.g. throwing `NotFoundError` sets HTTP 404).
+
+### 6.2 Companion Loader (`_error.js`)
+An optional companion `_error.js` can prefetch support data, report errors to monitoring services, or enrich the context:
+
+```javascript
+// pages/dashboard/_error.js
+module.exports = {
+  load: async ({ error, req, res, ctx, db }) => {
+    return {
+      supportEmail: 'support@example.com',
+      incidentId: req.id,
+    };
+  },
+};
+```
+
+### 6.3 Template Context Variables
+Inside `_error.njk`, the following variables are injected:
+- `error`: `{ message, status, statusCode, code, name, details, fields, stack }` (stack is only exposed when `isDev === true`).
+- `route`: `{ routePath, file }`.
+- `req`: `{ path, query, params, method, url }`.
+- `fsy`: Template helper suite.
+- Plus any data returned by companion `_error.js` loader.
+
+### 6.4 Layout Opt-Out
+To render a full-page custom error view without the parent layout, set `layout: false` in `_error.js` or frontmatter:
+```yaml
+---
+layout: false
+---
+<div class="standalone-error-screen">
+  <h1>{{ error.status }} - {{ error.message }}</h1>
+</div>
+```
+