webspresso 0.0.99 → 0.0.100

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 19 built-in official plugins (including `apiKeyPlugin`, `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) |
 
 ---
 
@@ -269,4 +273,246 @@ module.exports = {
 };
 ```
 
+---
+
+## 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>
+```
+

package/.agents/ORM.md

@@ -311,4 +311,94 @@ const mixed = await articleRepo.query()
 | **PostgreSQL** | `'auto'` / `'fts'` | `to_tsvector @@ plainto_tsquery` / `websearch_to_tsquery` | Native Postgres tsvector search. Pass `{ rank: true }` to order by `ts_rank` relevance. |
 | **MySQL** | `'fts'` | `MATCH(...) AGAINST(? IN BOOLEAN MODE)` | Requires FULLTEXT index on table. |
 
+---
+
+## 9. Relational Cascading Soft-Delete & Selective Restore (`cascade: true`)
+
+Webspresso ORM supports automated relational cascade operations for `hasMany` and `hasOne` relationships. When a parent record is soft-deleted or restored, child records are synchronized automatically.
+
+### 9.1 Relation Configuration
+
+Configure `cascade` directly inside your model relations:
+
+```javascript
+defineModel({
+  name: 'Author',
+  table: 'authors',
+  schema: zdb.schema({
+    id: zdb.id(),
+    name: zdb.string(),
+    deleted_at: zdb.timestamp({ nullable: true }),
+  }),
+  relations: {
+    // 1. Full cascade (soft-delete, hard-delete, and restore)
+    posts: {
+      type: 'hasMany',
+      model: () => 'Post', // or () => Post
+      foreignKey: 'author_id',
+      cascade: true,
+    },
+    // 2. hasOne cascade
+    profile: {
+      type: 'hasOne',
+      model: () => 'Profile',
+      foreignKey: 'author_id',
+      cascade: true,
+    },
+    // 3. Delete-only cascade (child is deleted with parent, but NOT restored)
+    tokens: {
+      type: 'hasMany',
+      model: () => 'ApiToken',
+      foreignKey: 'author_id',
+      cascade: 'delete', // or { delete: true, restore: false }
+    },
+  },
+  scopes: {
+    softDelete: true,
+  },
+});
+```
+
+### 9.2 Cascade Deletion Behavior
+
+- **Soft Delete (`repo.delete(id)`)**:
+  When an Author is soft-deleted, all active child records in cascading relations (`hasMany`, `hasOne`) are soft-deleted with the **exact same `deleted_at` timestamp**.
+  Cascade is recursive: If `Post` also defines `comments` with `cascade: true`, all comments under those posts are cascaded automatically.
+- **Hard Delete (`repo.forceDelete(id)`)**:
+  When `forceDelete` is called (or when parent is a non-softDelete model), cascading child records are deleted **before** the parent to avoid foreign-key constraint violations (`FOREIGN KEY constraint failed`).
+- **Cache Invalidation**:
+  The ORM query cache for all affected related models is automatically invalidated.
+
+### 9.3 Selective Restore (Smart Timestamp Matching)
+
+A classic pitfall in soft-delete architectures is resurrecting child records that the user deliberately deleted prior to deleting the parent account:
+
+```
+T1 (10:00): User manually deletes Post #1 (deleted_at = 10:00).
+T2 (12:00): User account is soft-deleted (deleted_at = 12:00).
+            Post #2 and Post #3 receive deleted_at = 12:00.
+T3 (15:00): User account is restored.
+```
+
+By default, Webspresso ORM executes **selective restore**:
+- It restores only child records where `child.deleted_at === parent.deleted_at` (Post #2 and Post #3).
+- Post #1 remains soft-deleted because its `deleted_at` was `10:00`!
+
+```javascript
+// Default: Safe selective restore (protects previously deleted children)
+await authorRepo.restore(authorId);
+
+// Optional: Force restore ALL children regardless of when they were deleted
+await authorRepo.restore(authorId, { allChildren: true });
+
+// Optional: Bypass cascading for a specific operation
+await authorRepo.delete(authorId, { cascade: false });
+await authorRepo.restore(authorId, { cascade: false });
+```
+
+### 9.4 Cycle & Recursion Safety
+
+If your data model contains circular relations (e.g. `User.partner` <-> `Partner.user`), Webspresso ORM uses an internal visited set (`model:id`) to terminate recursion cleanly without stack overflows.
+
+
 

package/.agents/PLUGINS.md

@@ -112,7 +112,44 @@ Zero-dependency B2B & Developer API Key Management Plugin with standard prefix f
   - `getMigrationTemplate(tableName)`: Knex migration script creating `api_keys` table.
   - `createApiKeyModel(tableName)`: Webspresso ORM model definition with hidden `key_hash`.
 
-### 2.2 `adminPanelPlugin` (`plugins/admin-panel`)
+### 2.3 `webhooksPlugin` (`plugins/webhooks`)
+Outgoing Webhook Dispatcher and Management Plugin with zero external dependencies. Dispatches events to subscribed external HTTP endpoints, signs payloads with HMAC-SHA256 (`X-Webspresso-Signature` and standard timestamped `webhook-signature`), filters events with wildcards (`*`, `order.*`), automatically retries failed deliveries using exponential backoff, hooks directly into Webspresso Queue (`core/queue`), and provides an interactive Mithril.js Admin Panel management UI.
+- **Options**:
+  - `db` / `knex`: Webspresso Database or Knex instance.
+  - `endpointsTable`: Database table for endpoints (default `'webhook_endpoints'`).
+  - `deliveriesTable`: Database table for delivery logs (default `'webhook_deliveries'`).
+  - `maxAttempts`: Maximum retry attempts on delivery failure (default `3`).
+  - `backoffBaseMs`: Base delay for exponential backoff in milliseconds (default `1000`).
+  - `timeoutMs`: HTTP request timeout in milliseconds (default `10000`).
+  - `wrapPayload`: Boolean (default `true`), wrap data in standard `{ id, event, timestamp, data }` event envelope.
+  - `queue`: Custom `QueueManager` instance (auto-detected from `ctx.app.queue` if present).
+  - `endpoints`: Static in-memory endpoints array (useful for testing or serverless setups).
+  - `apiPrefix`: Admin REST API prefix (default `'/webhooks'`).
+  - `includeDefaultPage`: Register Admin UI page and sidebar menu item (default `true`).
+  - `pageTitle`: Admin page title (default `'Webhooks'`).
+  - `menuOrder`: Admin sidebar order (default `92`).
+- **Request & Application Context Injected**:
+  - `req.webhooks`: Direct reference to the `WebhookDispatcher` instance.
+  - `app.webhooks`: Direct reference on the Webspresso Application instance.
+- **Built-in Services Registered**:
+  - `'webhook.dispatch'`: Dispatch events via `ctx.service('webhook.dispatch', { event, payload })`.
+  - `'webhook.ping'`: Test endpoint connectivity via `ctx.service('webhook.ping', { endpointId })`.
+  - `'webhook.retry'`: Manually retry a delivery via `ctx.service('webhook.retry', { deliveryId })`.
+- **Programmatic API (`webhooksPlugin.api` / `dispatcher`)**:
+  - `dispatch(event, payload, options)`: Match endpoints and deliver payload asynchronously (or await with `wait: true`).
+  - `pingEndpoint(endpointId)`: Send a test `ping` event to verify destination connectivity.
+  - `retryDelivery(deliveryId)`: Re-send a failed delivery with incremented attempt count.
+  - `createEndpoint(data)`: Register a new webhook endpoint with custom or auto-generated `whsec_` secret.
+  - `updateEndpoint(id, data)` / `deleteEndpoint(id)`: Update or delete endpoint records.
+  - `listEndpoints(filters)`: List endpoints with delivery statistics.
+  - `listDeliveries(filters)`: Query delivery logs with filtering by endpoint, event, and success status.
+  - `purgeDeliveries(options)`: Purge logs older than specified retention days.
+  - `signPayload(payload, secret, options)`: Compute HMAC-SHA256 signature (`sha256=...` and `t=...,v1=...`).
+  - `verifySignature(payload, header, secret, options)`: Constant-time signature verification with drift tolerance.
+  - `getMigrationTemplate()`: Knex migration script for `webhook_endpoints` and `webhook_deliveries`.
+  - `getModels()`: Webspresso ORM model definitions for `WebhookEndpoint` and `WebhookDelivery`.
+
+### 2.4 `adminPanelPlugin` (`plugins/admin-panel`)
 Mithril.js SPA Admin Panel mounted at `/_admin`.
 - **Options**: `{ path: '/_admin', db, title: 'Webspresso Admin' }`
 - **Features**: Auto CRUD screens for ORM models, user staff auth, custom page registration, widgets, field renderers.
@@ -131,14 +168,14 @@ Multipart file upload manager with local / cloud storage providers.
 
 ### 2.5 `fileManagerPlugin` (`plugins/file-manager`)
 Filesystem-first media library, directory explorer, and modal asset picker for Admin Panel.
-- **Options**: `{ baseDir: './public/uploads', publicBasePath: '/uploads', apiPrefix: '/files', pageTitle: 'Dosya Yöneticisi', maxUploadBytes: 10485760, allowedExtensions, allowedMimeTypes, includePage: true }`
+- **Options**: `{ baseDir: './public/uploads', publicBasePath: '/uploads', apiPrefix: '/files', pageTitle: 'File Manager', maxUploadBytes: 10485760, allowedExtensions, allowedMimeTypes, includePage: true }`
 - **Features**:
   - Directory tree navigation (breadcrumbs), safe subfolder creation (`mkdir`), item rename, delete, and move.
   - Path traversal attack protection (`resolveSafePath`).
   - Grid (thumbnail gallery) & List (table) view modes.
   - Search by filename and type filter (Images, Documents, Videos, Audio, Archives, Code).
   - Media preview modal with copy URL and direct playback/preview.
-  - "Kütüphaneden Seç" modal picker integrated with `FileUploadField` and `zdb.file()` form fields.
+  - "Choose from Media Library" modal picker integrated with `FileUploadField` and `zdb.file()` form fields.
   - Built-in services: `fileManager.list`, `fileManager.mkdir`, `fileManager.rename`, `fileManager.delete`, `fileManager.move`, `fileManager.upload`.
 
 ### 2.6 `corsPlugin` (`plugins/cors`)
@@ -256,19 +293,19 @@ Admin mutation tracking, record change timeline, and audit history with schedule
 - **Options**:
   - `db`: Database instance (must expose `.knex`).
   - `tableName`: Database table name (default `'audit_logs'`).
-  - `registerRecordAction`: Register built-in "Zaman Tüneli" action on all admin models (default `true`).
+  - `registerRecordAction`: Register built-in "Timeline" action on all admin models (default `true`).
   - `retentionDays`: Days to retain audit trail entries (default `90`).
   - `cleanupIntervalMs`: Background cleanup timer frequency (default 24h).
   - `autoCleanup`: Enable scheduled background purge (default `true`).
   - `cleanupOnStart`: Run initial purge shortly after boot (default `true`).
   - `retention`: `{ enabled, days: 90, intervalMs: 86400000, runOnStart: true }` (or `false` to disable).
-- **Zaman Tüneli (Timeline UI) Features**:
-  - **Dual Mode**: Switch seamlessly between **Zaman Tüneli (Timeline View)** and **Tablo Görünümü (Table View)**.
+- **Timeline UI Features**:
+  - **Dual Mode**: Switch seamlessly between **Timeline View** and **Table View**.
   - **Record Focus Mode**: Clicking any `Model #ID` tag instantly filters and displays that specific record's revision timeline.
   - **Visual Spine & Status Icons**: Color-coded action nodes for `create` (emerald +), `update` (blue ✏️), `delete` (rose 🗑️), and `restore` (amber ↺).
   - **Changed Fields Diff**: Clearly lists modified fields (e.g. `title`, `price`) on every update event.
   - **Expandable Details**: Inspect full HTTP request path, actor IP, user agent, and pretty-printed JSON metadata.
-  - **Built-in Record Action**: One-click "Zaman Tüneli" button on record lists and edit forms jumps straight to that record's audit history.
+  - **Built-in Record Action**: One-click "Timeline" button on record lists and edit forms jumps straight to that record's audit history.
 - **API & Admin Panel Endpoints**:
   - `GET /_admin/api/audit-logs`: List paginated logs with filters (`model`, `recordId`, `action`, `search`, `from`, `to`).
   - `GET /_admin/api/audit-logs/timeline/:model/:id`: Dedicated chronological record change timeline with summary stats.

package/.agents/QUEUE.md

@@ -162,27 +162,30 @@ Webspresso includes a native, zero-dependency task scheduler with a POSIX-compli
 
 ### 1. Cron Expression Syntax
 - Standard 5 fields: `minute hour day-of-month month day-of-week`
-- Wildcards: `*`
-- Steps: `*/5`, `10-30/5`
-- Ranges: `1-5`, `MON-FRI`, `JAN-DEC`
+- Wildcards: `*`, `?` (supported in day-of-month and day-of-week)
+- Steps & Offsets: `*/5`, `10/15` (starting at minute 10, every 15 min), `10-30/5`
+- Ranges: `1-5`, `5-7` (Fri-Sun), `MON-FRI`, `MON-SUN`, `JAN-DEC`
 - Lists: `1,15,30`, `MON,WED,FRI`
 - Descriptive aliases:
   - `@yearly`, `@annually` (`0 0 1 1 *`)
   - `@monthly` (`0 0 1 * *`)
   - `@weekly` (`0 0 * * 0`)
+  - `@weekdays`, `@workdays` (`0 0 * * 1-5`)
+  - `@weekends` (`0 0 * * 6,0`)
   - `@daily`, `@midnight` (`0 0 * * *`)
-  - `@hourly` (`0 * * * *`)
+  - `@hourly`, `@every_hour` (`0 * * * *`)
   - `@every_minute`, `@minutely` (`* * * * *`)
   - `@every <N>m` (e.g. `@every 5m` → `*/5 * * * *`)
   - `@every <N>h` (e.g. `@every 2h` → `0 */2 * * *`)
+  - `@every <N>d` (e.g. `@every 2d` → `0 0 */2 * *`)
 
 ### 2. Programmatic Scheduling
 ```js
-// Schedule daily digest at 09:00 AM
+// Schedule daily digest at 09:00 AM with Timezone support
 queue.schedule('0 9 * * *', 'reports.daily-digest', { channel: 'slack' }, {
-  overlap: false, // Prevent concurrent execution if previous run is still active (default: false)
-  maxRuns: 10,    // Optional maximum executions before auto-unscheduling
-  utc: false,     // Use local timezone or UTC
+  timezone: 'Europe/Istanbul', // IANA timezone support ('Europe/Istanbul', 'America/New_York')
+  overlap: false,              // Prevent concurrent execution if previous run is still active (default: false)
+  maxRuns: 10,                 // Optional maximum executions before auto-unscheduling
 });
 
 // Or use the .cron() alias
@@ -190,9 +193,12 @@ queue.cron('@every 15m', 'metrics.collect');
 
 // Query schedules
 const schedules = queue.getSchedules();
-// [{ id, name, cronExpression, nextRunAt, lastRunAt, isRunning, runsCount, ... }]
+// [{ id, name, cronExpression, nextRunAt, lastRunAt, isRunning, activeJobId, activeJobIds, runsCount, ... }]
 
-// Unschedule by schedule ID or job name
+// Manually trigger a schedule immediately
+await queue.triggerSchedule('reports.daily-digest');
+
+// Unschedule by schedule ID or job name (removes all schedules matching the job name)
 queue.unschedule('metrics.collect');
 ```
 
@@ -201,8 +207,10 @@ queue.unschedule('metrics.collect');
 | :--- | :--- | :--- | :--- |
 | `id` | `string` | `schedule:${job}:${cron}` | Custom unique identifier |
 | `overlap` | `boolean` | `false` | When `false`, skips tick if a previous job run is still processing |
+| `preventOverlap` | `boolean` | `true` | Alias for `overlap: false` |
 | `maxRuns` | `number` | `null` | Automatically unschedules task after N runs |
 | `utc` | `boolean` | `false` | Evaluate cron expressions in UTC instead of local timezone |
+| `timezone` (`tz`) | `string` | `null` | IANA timezone name (e.g. `'Europe/Istanbul'`, `'America/New_York'`) |
 | `runImmediately` | `boolean` | `false` | Triggers a run right after scheduling |
 
 ### 4. File-Based Cron Discovery (`jobs/`)