webspresso 0.0.99 → 0.0.101

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/EVENTS.md

@@ -0,0 +1,179 @@
+# Webspresso Events & Signals Architecture
+
+[← Back to AGENTS.md](.agents/AGENTS.md)
+
+Webspresso provides an enterprise, zero-dependency **Decoupled Event & Signals System** (`core/events`), combining **AdonisJS Events** (wildcard matching, async parallel/serial/waterfall dispatch, queue bridging, and listener auto-discovery) with **Django Signals** (declarative `Signal` channels, sender filtering, and ORM model signals).
+
+---
+
+## 1. Overview & Key Capabilities
+
+- **Zero External Dependencies**: Built entirely with native Node.js standard modules (`events`, `path`, `fs`).
+- **Synchronous & Asynchronous Emission**:
+  - `events.emit(name, data)`: Fast sync/fire-and-forget dispatch.
+  - `await events.emitAsync(name, data)`: Parallel concurrent execution (`Promise.allSettled`).
+  - `await events.emitSerial(name, data)`: Sequential execution in priority order.
+  - `await events.emitWaterfall(name, initialData)`: Sequential pipeline where output of listener $N$ feeds listener $N+1$.
+- **Wildcard & Pattern Matching**:
+  - `events.on('order.*', (data, meta) => ...)`
+  - `events.on('system.**', (data, meta) => ...)`
+  - `events.onAny((eventName, data, meta) => ...)`
+- **Django-Style Signals & Sender Filtering**:
+  - `const orderPlaced = defineSignal('order_placed')`
+  - `orderPlaced.connect(receiver, { sender: 'Checkout' })`
+  - `orderPlaced.send({ orderId: 101 }, { sender: 'Checkout' })`
+- **Background Queue Bridging**:
+  - `events.listenAndQueue('user.created', 'send-welcome-email', { delay: 1000 })`
+  - Automatically bridges emitted events directly to Webspresso's job queue (`core/queue`).
+- **ORM Model Signals Auto-Bridge**:
+  - Automatically translates `ModelEvents` (`User.afterCreate`, `*.afterDelete`) to application events (`model:created`, `user:created`, `model:deleted`) with `sender: ctx.model`.
+- **Automatic Request & Context Decoration**:
+  - Injected onto `req.events` on every Express request.
+  - Available inside `req.context.events` for services: `ctx.events.emit('order.created', order)`.
+  - Accessible on `app.events` and plugin contexts.
+- **Graceful Shutdown Integration**:
+  - Cleaned up automatically on graceful shutdown via `ShutdownManager.onShutdown()`.
+
+---
+
+## 2. Using Events in API Routes & Services
+
+### 2.1 Emitting Events in File-Based Routes (`pages/api/...`)
+
+```javascript
+// pages/api/orders.post.js
+const { defineApi } = require('webspresso');
+
+module.exports = defineApi({
+  schema: ({ z }) => ({
+    body: z.object({
+      total: z.number().positive(),
+      items: z.array(z.string()),
+    }),
+  }),
+  async handler(req, res) {
+    const order = await req.db.getRepository('Order').create(req.input.body);
+
+    // Synchronous fire-and-forget or awaited async parallel
+    req.events.emit('order.created', order, { sender: 'Order' });
+    // or: await req.events.emitAsync('order.created', order);
+
+    return res.status(201).json(order);
+  },
+});
+```
+
+### 2.2 Emitting Events inside Services (`services/...`)
+
+```javascript
+// services/order/checkout.js
+const { defineService } = require('webspresso');
+
+module.exports = defineService({
+  transaction: true,
+  async handle(input, ctx) {
+    const order = await ctx.db.getRepository('Order').create(input);
+
+    // ctx.events is automatically available
+    ctx.events.emit('order.checkout.completed', { orderId: order.id, user: ctx.req?.user });
+
+    return order;
+  },
+});
+```
+
+---
+
+## 3. Registering Listeners
+
+### 3.1 Programmatic Subscriptions
+
+```javascript
+const { events } = require('webspresso');
+
+// 1. Basic Listener
+const unsub = events.on('order.created', (order, meta) => {
+  console.log(`Order ${order.id} received at ${meta.timestamp}`);
+});
+
+// 2. Wildcard Listener
+events.on('order.*', (data, meta) => {
+  console.log(`Order event ${meta.event} occurred`);
+});
+
+// 3. One-time Listener
+events.once('app.ready', () => {
+  console.log('Application initialized');
+});
+
+// 4. Priority Ordering (higher runs first)
+events.on('user.login', auditLogin, { priority: 100 });
+events.on('user.login', notifyFriends, { priority: 0 });
+```
+
+### 3.2 File-Based Discovery (`listeners/` directory)
+
+Webspresso auto-discovers listeners in the `listeners/` root directory:
+
+```javascript
+// listeners/send-welcome-email.js
+const { defineListener } = require('webspresso');
+
+module.exports = defineListener('user.created', async (user, meta) => {
+  console.log(`Sending welcome email to ${user.email}`);
+});
+```
+
+Or multiple listeners in a single file:
+
+```javascript
+// listeners/audit-events.js
+module.exports = [
+  {
+    event: 'order.*',
+    priority: 50,
+    handle: async (data, meta) => {
+      console.log(`Audit: ${meta.event}`, data);
+    },
+  },
+];
+```
+
+---
+
+## 4. Django-Style Signals
+
+For decoupled domain events with strict sender boundaries:
+
+```javascript
+const { defineSignal } = require('webspresso');
+
+// Define signal
+const invoicePaid = defineSignal('invoice_paid');
+
+// Connect receiver with sender filter
+invoicePaid.connect(
+  (invoice) => {
+    console.log(`Invoice ${invoice.id} processed for subscription`);
+  },
+  { sender: 'Subscription' }
+);
+
+// Trigger signal
+invoicePaid.send({ id: 'INV-100' }, { sender: 'Subscription' });
+```
+
+---
+
+## 5. Background Queue Bridging (`listenAndQueue`)
+
+Connect application events directly to background jobs without manual boilerplate:
+
+```javascript
+// In plugin or server setup:
+app.events.listenAndQueue('order.created', 'send-order-confirmation', {
+  delay: 2000,
+  attempts: 3,
+});
+```
+When `order.created` is emitted, Webspresso automatically calls `req.queue.dispatch('send-order-confirmation', order, options)`.

package/.agents/ORM.md

@@ -311,4 +311,153 @@ 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.
+
+---
+
+## 10. Django-inspired Auto-Migrations (`db:makemigrations`)
+
+Webspresso supports automatic schema diffing against your live database, similar to Django's `makemigrations`. It inspects your `models/*.js` definitions, checks the current database schema, and automatically generates required Knex migration files (`createTable` or `alterTable` with `dropColumn` rollbacks):
+
+```bash
+# Preview changes without writing files
+npx webspresso db:makemigrations --dry-run
+
+# Detect model changes and generate migration file
+npx webspresso db:makemigrations
+
+# Custom migration name
+npx webspresso db:makemigrations --name add_profile_fields
+
+# Apply migrations
+npx webspresso db:migrate
+```
+
+Programmatic usage via `db.migrate`:
+```javascript
+// Check diff
+const diff = await db.migrate.diff();
+if (diff.hasChanges) {
+  console.log(diff.changes);
+}
+
+// Generate files
+const result = await db.migrate.makeMigrations();
+```
+
+---
+
+## 11. AdonisJS-inspired Model Factories (`defineFactory`)
+
+For unit testing, integration tests, and dev database seeding, Webspresso provides declarative Model Factories inspired by AdonisJS Lucid:
+
+```javascript
+import { defineFactory } from 'webspresso';
+
+export const UserFactory = defineFactory('User', ({ faker, index }) => ({
+  name: faker.person.fullName(),
+  email: faker.internet.email(),
+  role: 'user',
+  isActive: true,
+}))
+  .state('admin', () => ({ role: 'admin' }))
+  .state('suspended', () => ({ isActive: false }));
+
+// In-memory object generation (No DB hit)
+const fakeUser = UserFactory.make({ name: 'Custom Name' });
+const fakeUsers = UserFactory.count(5).make();
+
+// Database persistence via Repository
+const user = await UserFactory.create({ db });
+const admins = await UserFactory.count(3).apply('admin').create({ db });
+```
+
+
 

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/`)

package/.agents/ROUTING.md

@@ -400,9 +400,105 @@ Pages under `pages/` automatically inherit ancestor layouts:
 </div>
 ```
 
+#### 3. Folder-Level Error Boundaries (`_error.njk` & `_error.js`)
+When an exception occurs during SSR lifecycle execution (in `load()`, template rendering, hooks, or nested layout loaders):
+- **Ancestral Discovery**: Webspresso searches up the directory hierarchy from the route's directory up to `pages/` for the nearest `_error.njk`.
+- **Isolated Layout Preservation**: `_error.njk` is automatically wrapped inside the surrounding ancestor `_layout.njk` chain, keeping the UI intact (e.g. an error in `/dashboard/billing/invoices` renders the error card inside the dashboard sidebar and header).
+- **Companion Loader (`_error.js`)**: Can export `load({ error, req, res, ctx, db })` to attach custom error data or report exceptions.
+- **Status Code Propagation**: HTTP status is set to `error.status || error.statusCode || 500` (e.g., throwing `NotFoundError` returns HTTP 404).
+- **Opt-Out**: Disable layout wrapping with `layout: false` in `_error.js` or frontmatter (`--- layout: false ---`).
+- **Fallback**: If no `_error.njk` exists in any ancestor directory, execution falls through to the global Express error boundary (`app.setErrorHandler` / 500 page).
+
+```html
+{# pages/dashboard/_error.njk #}
+<div class="p-6 bg-red-50 dark:bg-red-950/30 rounded-xl border border-red-200">
+  <h2 class="text-xl font-bold text-red-700">Error {{ error.status }}</h2>
+  <p class="text-red-600 mt-2">{{ error.message }}</p>
+  {% if supportEmail %}<p class="mt-4 text-sm">Need help? Email {{ supportEmail }}</p>{% endif %}
+</div>
+```
+
+#### 4. Folder-Level Loading Skeletons (`_loading.njk`)
+In SSR streaming mode (`stream: true` or `renderStream`):
+- **Automatic Discovery**: Discovers the nearest `_loading.njk` up the directory chain.
+- **Auto-Populate Slots**: Any empty `<div data-stream-target="slotName"></div>` in the page template is automatically populated with the `_loading.njk` skeleton HTML in the initial flushed shell chunk!
+- **Context Availability**: Exposed as `{{ loadingSkeleton | safe }}` and `{{ loadingHtml | safe }}` in the template context.
+- **Layout Integration**: Cascading `_layout.njk` templates automatically wrap the streaming shell.
+
+```html
+{# pages/dashboard/_loading.njk #}
+<div class="animate-pulse space-y-4">
+  <div class="h-8 bg-slate-200 dark:bg-slate-800 rounded w-1/4"></div>
+  <div class="h-32 bg-slate-200 dark:bg-slate-800 rounded"></div>
+</div>
+```
+
+---
+
+## 7. Form Handling, Flash Messages & Old Input (AdonisJS & Django-inspired)
+
+For classic SSR forms (POST-Redirect-GET), Webspresso provides built-in flash data propagation and Django-style ModelForm rendering helpers.
+
+### 7.1 Redirect with Old Input & Validation Errors
+In your form submission handler (API or custom POST action):
+```javascript
+// pages/api/auth/register.post.js
+module.exports = {
+  handler: async (req, res) => {
+    const { email, password } = req.body;
+    
+    if (!email.includes('@')) {
+      return res
+        .withInput() // Preserves req.body (sanitizes sensitive fields like password)
+        .withErrors({ email: 'Please enter a valid email address' })
+        .withFlash('warning', 'Please review the highlighted errors')
+        .redirect('/register');
+    }
+
+    await req.service('user.create', { email, password });
+    return res.withFlash('success', 'Account created! Please log in.').redirect('/login');
+  }
+};
+```
+
+### 7.2 Nunjucks Template Helpers (`fsy`)
+In your Nunjucks templates (`pages/*.njk`):
+```html
+{% if fsy.hasFlash('success') %}
+  <div class="alert alert-success">{{ fsy.flash('success') }}</div>
+{% endif %}
+
+<form method="POST" action="/api/auth/register">
+  {{ fsy.csrf() | safe }}
+
+  <!-- Manual field with old value and inline error -->
+  <div class="mb-3">
+    <label class="form-label">Email</label>
+    <input type="email" name="email" 
+           value="{{ fsy.old('email') }}" 
+           class="form-control {% if fsy.hasError('email') %}is-invalid{% endif %}">
+    {% if fsy.hasError('email') %}
+      <div class="invalid-feedback">{{ fsy.error('email') }}</div>
+    {% endif %}
+  </div>
+
+  <!-- Or use the Django-inspired field helper (one-liner) -->
+  {{ fsy.field('email', { type: 'email', placeholder: 'you@example.com' }) | safe }}
+
+  <button type="submit" class="btn btn-primary">Register</button>
+</form>
+```
+
+### 7.3 Django ModelForm Helper (`fsy.formFor`)
+Generate an entire HTML form from an ORM model definition with automatic widgets and validation error mapping:
+```html
+{# Automatically excludes id, created_at, updated_at and generates appropriate widgets #}
+{{ fsy.formFor(req.db.getRepository('Article'), { action: '/articles', submitLabel: 'Publish' }) | safe }}
+```
+
 ---
 
-## 7. Summary Checklist for Agents
+## 8. Summary Checklist for Agents
 
 When a user asks to add or modify endpoints:
 1. Identify the URL and method (e.g. `POST /api/auth/register` or `POST /auth/login`).