webspresso 0.0.97 → 0.0.99

package/.agents/ORM.md

@@ -122,17 +122,32 @@ const result = await productRepo.query()
 
 ---
 
-## 3. Relations & Eager Loading
+## 3. Relations & Nested Eager Loading
 
-Support for `belongsTo`, `hasMany`, and `hasOne`:
+Support for `belongsTo`, `hasMany`, and `hasOne` with arbitrary-depth batch nested loading:
 
 ```js
-// Eager-load relations using include
-const productsWithCategory = await productRepo.query()
+// 1. Direct eager loading
+const products = await productRepo.query()
   .include('category', 'reviews')
   .find();
+
+// 2. Nested eager loading (dot notation)
+const posts = await postRepo.query()
+  .include('author.profile', 'author.company.country', 'comments.author')
+  .find();
+
+// 3. Eager loading via repository methods
+const post = await postRepo.findById(id, { include: ['author.profile'] });
+const list = await postRepo.find({ active: true }, { include: ['author.company'] });
+
+// 4. Shorthand repository chaining
+const result = await postRepo.include('author.profile').where('user_id', 1).find();
 ```
 
+> [!TIP]
+> Nested relations are loaded using optimized batch queries (`whereIn`) with zero N+1 queries. Shared object references and JSON columns on related models are automatically handled.
+
 ---
 
 ## 4. Ambient Transactions & AsyncLocalStorage
@@ -228,3 +243,72 @@ defineModel({
 - **Include Guards**: Excessive `query().with(...)` or `?include=...` relations beyond `maxIncludes` throw `QueryComplexityError` or safely cap relations.
 - **REST Resources Protection**: Automatically validates client parameters (`?perPage=5000` or `?include=...`) against model complexity boundaries.
 
+---
+
+## 8. Universal Full-Text Search (FTS)
+
+Webspresso ORM provides database-agnostic full-text and keyword search with transparent dialect optimizations for SQLite, PostgreSQL, and MySQL.
+
+### 8.1 Model Configuration (`searchable`)
+
+Declare default searchable columns on your model:
+
+```javascript
+defineModel({
+  name: 'Article',
+  table: 'articles',
+  schema: zdb.schema({
+    id: zdb.id(),
+    title: zdb.string(),
+    content: zdb.text(),
+    author: zdb.string(),
+  }),
+  searchable: ['title', 'content'], // Default columns for .search()
+});
+```
+
+*(Note: If `searchable` is not defined, `.search()` automatically falls back to `admin.searchFields` if available.)*
+
+### 8.2 Using Search in Application Code
+
+Search is available both on repository instances (`repo.search`) and on query builders (`query().search()` / `query().orSearch()`):
+
+```javascript
+const articleRepo = req.db.getRepository('Article');
+
+// 1. Basic search across default searchable columns
+const results = await articleRepo.search('webspresso framework').get();
+
+// 2. Chained with filtering, ordering, and pagination
+const page = await articleRepo
+  .search(req.query.q) // Safe no-op when req.query.q is empty or undefined
+  .where('status', 'published')
+  .orderBy('created_at', 'desc')
+  .paginate({ page: 1, limit: 10 });
+
+// 3. Dynamic column override
+const byAuthor = await articleRepo.search('Alice', ['author']).get();
+
+// 4. Exact phrase matching
+const exact = await articleRepo.search('zero dependency sprawl', null, { exact: true }).get();
+
+// 5. OR matching between words (default is AND)
+const anyWord = await articleRepo.search('vue react angular', null, { matchAllWords: false }).get();
+
+// 6. Disjoined search conditions with orSearch()
+const mixed = await articleRepo.query()
+  .where('author', 'Bob')
+  .orSearch('featured article', ['title'])
+  .get();
+```
+
+### 8.3 Dialect Features & Modes
+
+| Dialect | Mode (`options.mode`) | SQL Strategy | Notes |
+| :--- | :--- | :--- | :--- |
+| **SQLite** | `'auto'` (default) | Tokenized case-insensitive `LIKE` | Safe out-of-the-box, no virtual table required. |
+| **SQLite** | `'fts'` | `articles MATCH ?` or virtual table subquery | Set `{ mode: 'fts', ftsTable: 'articles_fts' }` for FTS5 tables. |
+| **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. |
+
+

package/.agents/PLUGINS.md

@@ -77,6 +77,41 @@ Zero-dependency HTTP Basic Authentication (RFC 7617) plugin with timing-safe equ
   - `onAuthenticated`: Callback hook `(req, user) => ...`.
 - **Named Middleware**: Registers `ctx.middlewares.basicAuth` for route files.
 
+### 2.2 `apiKeyPlugin` (`plugins/api-key`)
+Zero-dependency B2B & Developer API Key Management Plugin with standard prefix format (`wsp_live_...`), SHA-256 secure hash storage, timing-safe constant-time verification (`crypto.timingSafeEqual`), granular scopes/permissions with wildcard support, non-blocking `last_used_at` usage tracking, and programmatic creation/revocation APIs.
+- **Options**:
+  - `db` / `knex`: Webspresso Database or Knex instance.
+  - `tableName`: Database table name (default `'api_keys'`).
+  - `prefix`: Default key prefix (default `'wsp_live_'`).
+  - `byteLength`: Random byte count for key generation (default `24`).
+  - `global`: Boolean, whether to protect routes globally (default `false`).
+  - `routes`: Route prefix(es) to protect when `global: true`.
+  - `skipPaths` / `skip`: Exclusion paths or predicate function `(req) => boolean`.
+  - `keys`: Static in-memory keys for testing / serverless / simple setups (`[{ key, name, scopes }]` or map).
+  - `trackUsage`: Boolean (default `true`), whether to automatically update `last_used_at` on verified keys.
+  - `updateLastUsedThrottleMs`: Throttle period in ms to avoid DB write thrashing (default `60000`).
+  - `allowQueryParam`: Boolean (default `false`), allow extracting API key via `?apiKey=...`.
+  - `findKeyByHash` / `verify`: Custom key lookup or verification hook.
+  - `getUser`: Custom async user resolver `(apiKeyRecord, req) => Promise<User | null>`.
+  - `onAuthenticated`: Callback hook `(req, apiKeyRecord) => void`.
+- **Named Middleware**:
+  - `middleware: ['apiKey']`: Requires valid API key via `X-API-Key`, `api-key`, or `Authorization: Bearer <key>`.
+  - `middleware: [['apiKey', { scopes: ['reports:read', 'orders:*'] }]]`: Enforces required granular scopes with prefix wildcard support (`*`, `namespace:*`).
+  - `middleware: [['apiKey', { optional: true }]]`: Non-blocking authentication (populates `req.apiKey` if present, passes through if absent).
+- **Request Context Injected**:
+  - `req.apiKey`: The authenticated API key record (including name, key_hint, scopes, metadata).
+  - `req.auth.apiKey`: Equivalent reference inside `req.auth`.
+  - `req.auth.user` & `req.user`: Associated user record (if `user_id` or `getUser` resolved).
+- **Programmatic API (`apiKeyPlugin.api`)**:
+  - `generateKey(options)`: Generate fresh key with hash and masked hint (`wsp_live_...4f2a`).
+  - `hashKey(rawKey)`: Compute SHA-256 hex string.
+  - `maskKey(rawKey, prefix)`: Mask raw key for logs/UI.
+  - `createApiKey(data, options)`: Generates key, hashes it, and stores in database table (returns raw key once).
+  - `verifyApiKey(rawKey, options)`: Verify raw key against DB, checking expiration and revocation.
+  - `revokeApiKey(idOrHash, options)`: Mark key as revoked in DB (`revoked_at = now()`).
+  - `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`)
 Mithril.js SPA Admin Panel mounted at `/_admin`.
 - **Options**: `{ path: '/_admin', db, title: 'Webspresso Admin' }`
@@ -91,6 +126,8 @@ Schema-driven headless CMS & inline content editing.
 Multipart file upload manager with local / cloud storage providers.
 - **Options**: `{ path: '/api/upload', local: { destDir, publicBasePath }, maxBytes: 10000000, mimeAllowlist: ['image/png', 'image/jpeg'] }`
 - **Features**: Single & multi-file uploads, file size & extension validation, storage drivers.
+- **Orphan Pruning**: `scanOrphanedUploads({ db, destDir })` and `pruneOrphanedUploads({ db, destDir, dryRun })` to detect and remove disk files no longer referenced by any database model, accompanied by CLI command `webspresso upload:prune [--dry-run]`.
+
 
 ### 2.5 `fileManagerPlugin` (`plugins/file-manager`)
 Filesystem-first media library, directory explorer, and modal asset picker for Admin Panel.
@@ -122,12 +159,49 @@ Request rate limiting using express-rate-limit logic.
 - **Options**: `{ windowMs: 15 * 60 * 1000, max: 100 }`
 
 ### 2.9 `siteAnalyticsPlugin` (`plugins/site-analytics`)
-Self-hosted privacy-focused page view analytics and client error tracking.
-- **Options**: `{ path: '/_analytics', db }`
+Self-hosted privacy-focused page view analytics, client error tracking, and automated retention cleanup.
+- **Options**:
+  - `db`: Knex database instance.
+  - `tableName`: Table name for page views (default: `'analytics_page_views'`).
+  - `errorsTableName`: Table name for client errors (default: `'analytics_client_errors'`).
+  - `retentionDays`: Page views retention window in days (default: `90`).
+  - `errorRetentionDays`: Client error logs retention window in days (default: `30`).
+  - `cleanupIntervalMs`: Background scheduled cleanup interval in milliseconds (default: `86400000` / 24 hours).
+  - `autoCleanup`: Enable automated periodic background cleanup (default: `true`).
+  - `cleanupOnStart`: Run an initial non-blocking cleanup shortly after startup (default: `true`).
+  - `retention`: Shorthand object `{ enabled, days, errorDays, intervalMs, runOnStart }` or `false` to disable retention cleanup.
+  - `excludePaths`, `excludeBots`, `customBots`, `anonymizeIp`, `trustProxy`, `collectErrors`, `dashboard`.
+- **Programmatic API (`plugin.api`)**:
+  - `purge({ days, errorDays, olderThan, errorsOlderThan })`: Manual purge of page views and error logs.
+  - `purgeAnalyticsData(knex, options)`: Standalone query purge helper.
+  - `startCleanup(intervalMs)` / `stopCleanup()`: Control background cleanup lifecycle.
+  - `getRetentionConfig()`: Inspect active retention configuration.
+- **Admin REST Endpoint**: `POST /_admin/api/analytics/purge` (accepts `{ days, errorDays }`).
+- **Admin UI**: "Purge Old Data" button with confirmation prompt in the Analytics admin dashboard header.
+- **CLI Command**:
+  ```bash
+  webspresso analytics:prune --days 90 --error-days 30
+  ```
+- **Lifecycle Integration**: Background timer uses `.unref()` to avoid keeping Node event loop open, and registers a framework disposer to clear timers on shutdown.
 
 ### 2.10 `emailPlugin` (`plugins/email`)
-Transactional email compiler (MJML) & Nodemailer transport integration.
-- **Options**: `{ transport, from: 'noreply@example.com', templatesDir }`
+Transactional email compiler (MJML) & Nodemailer transport integration with database delivery logging and auto-retention cleanup.
+- **Options**:
+  - `transport` / `smtp`: Nodemailer transport or SMTP settings.
+  - `defaults`: Default sender/reply-to address.
+  - `templatesDir`: Directory containing `.mjml` templates.
+  - `logToDb`: Store delivery history in database (default `true` when `db` is supplied).
+  - `tableName`: Database table name (default `'email_logs'`).
+  - `retentionDays`: Days to retain email logs (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).
+- **Pruning CLI**:
+  ```bash
+  webspresso email:prune --days 90
+  ```
+- **Admin Panel UI**: Includes log listing, test email dispatch, template preview, connection verification, and "Purge 90d" action.
 
 ### 2.11 `polarPlugin` (`plugins/polar`)
 Polar.sh subscription billing — checkout, customer portal, webhooks, Customer State sync, tier columns. Zero extra deps (`crypto` + `fetch`).
@@ -178,17 +252,100 @@ Polar.sh subscription billing — checkout, customer portal, webhooks, Customer
   - [docs/guides/polar-production-checklist.md](../docs/guides/polar-production-checklist.md)
 
 ### 2.12 `auditLogPlugin` (`plugins/audit-log`)
-Admin mutation tracking and audit log audit history.
-- **Options**: `{ db, retainDays: 90 }`
+Admin mutation tracking, record change timeline, and audit history with scheduled retention and manual purge API.
+- **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`).
+  - `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)**.
+  - **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.
+- **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.
+  - `POST /_admin/api/audit-logs/purge`: `{ days: 90 }` or `{ olderThan: '2026-01-01' }`.
+- **Programmatic Plugin API**:
+  ```javascript
+  const audit = ctx.usePlugin('audit-log');
+  const history = await audit.queryTimeline('Post', 42);
+  const logs = await audit.queryLogs({ model: 'User', action: 'delete' });
+  ```
+- **Pruning CLI**:
+  ```bash
+  webspresso audit:prune --days 90
+  ```
 
 ### 2.13 `ormCacheAdminPlugin` (`plugins/orm-cache-admin`)
 ORM Cache inspection and invalidation dashboard.
 
 ### 2.14 `schemaExplorerPlugin` (`plugins/schema-explorer`)
-Interactive JSON schema & OpenAPI route specification generator.
+Interactive Database Schema & ER Diagram Explorer for both raw JSON/OpenAPI endpoints and Admin Panel SPA.
+- **Admin Panel Page (`/_admin/schema`)**:
+  - Interactive Table & Column details (Primary Keys, Foreign Keys, Nullability, Types, Constraints, Scopes).
+  - Visual Relationship Map (ER Diagram) with bidirectional incoming & outgoing relation links.
+  - Interactive table cards highlighting connected models and key mappings (`posts.author_id ➔ authors.id`).
+  - One-click Mermaid.js ER diagram code generation and copy.
+  - JSON schema export.
+- **Options**:
+  - `admin: true` — Automatically registers into `adminPanelPlugin` when present.
+  - `adminPath: '/schema'` — Custom path inside Admin Panel.
+  - `menuLabel: 'Schema Explorer'` — Sidebar menu label.
+  - `menuIcon: 'database'` — Sidebar icon.
+  - `path: '/_schema'` — Raw JSON endpoint path.
+  - `exclude: ['SecretModel']` — Models to exclude.
+- **Usage**:
+  ```js
+  const { createApp } = require('webspresso');
+  const { adminPanelPlugin, schemaExplorerPlugin } = require('webspresso/plugins');
 
-### 2.15 `swaggerPlugin` (`plugins/swagger`)
-Interactive OpenAPI 3.0 Swagger UI documentation.
+  const { app } = createApp({
+    plugins: [
+      adminPanelPlugin({ db }),
+      schemaExplorerPlugin({ admin: true }),
+    ],
+  });
+  ```
+
+### 2.15 `swaggerPlugin` / `openapiPlugin` (`plugins/swagger`)
+Interactive OpenAPI 3.0 API documentation supporting both modern **Scalar API Reference** and classic **Swagger UI**, automated parameter/tag/summary inference, auth detection, Admin Panel embedding, and CLI export.
+
+- **Options**:
+  - `path`: Base path for documentation (default: `/_swagger`). Spec served at `{path}/openapi.json`.
+  - `ui`: Default playground engine: `'swagger'` or `'scalar'` (default: `'swagger'`).
+  - `theme`: Theme for Scalar UI (`'default'`, `'purple'`, `'moon'`, `'solarized'`, etc.).
+  - `darkMode`: Scalar dark mode toggle (default: `true`).
+  - `admin`: Auto-register inside Admin Panel (`/_admin/#!/api-docs`) when `admin-panel` plugin is loaded (default: `true`).
+  - `adminTitle`: Admin navigation label (default: `'API Docs'`).
+  - `includeOrmSchemas`: Merge ORM models into `components.schemas` (default: `false`).
+  - `authorize`: Custom `(req) => boolean` guard function.
+- **Endpoints**:
+  - `GET /_swagger`: Primary UI (Scalar or Swagger based on `ui` option).
+  - `GET /_swagger/scalar`: Always serves modern Scalar UI.
+  - `GET /_swagger/swagger`: Always serves Swagger UI.
+  - `GET /_swagger/openapi.json`: OpenAPI 3.0 specification document.
+- **Example**:
+  ```javascript
+  const { createApp, openapiPlugin } = require('webspresso');
+
+  const { app } = createApp({
+    plugins: [
+      openapiPlugin({
+        ui: 'scalar',
+        theme: 'purple',
+        includeOrmSchemas: true,
+      }),
+    ],
+  });
+  ```
 
 ### 2.16 `realtimePlugin` (`plugins/realtime`, `core/realtime`)
 Framework-agnostic, plugin-based, and adapter-driven Realtime layer supporting WebSocket, SSE, Socket.IO, and distributed Redis Pub/Sub transports with zero SSR execution hazards.
@@ -415,5 +572,60 @@ RFC 4180 compliant CSV generator, parser, ORM model export, streaming chunk writ
   - `csv.createStreamWriter(stream, options)` → `{ writeHeader, writeRow, writeRows, end }`
 - **Built-in Services**: `csv.generate`, `csv.parse`, `csv.exportModel` accessible via `ctx.service()` or `req.service()`.
 
+### 2.19 `dashboardPlugin` / `devToolbarPlugin` (`plugins/dashboard`)
+Interactive Webspresso Developer Dashboard SPA mounted at `/_webspresso` and Floating In-Page DevTools bar (`fsy.devToolbar()`) inspired by Django Debug Toolbar and Nuxt DevTools.
+
+- **Aliases**: `dashboardPlugin`, `devToolbarPlugin`, `devtoolsPlugin`.
+- **Options**:
+  - `path`: Base URL path for dashboard (default `/_webspresso`).
+  - `title`: Dashboard browser title (default `'Webspresso Developer Dashboard'`).
+  - `enabled`: Boolean to force enable in production (default `process.env.NODE_ENV !== 'production'`).
+- **Dashboard Features (`/_webspresso`)**:
+  - **Routes Tab**: Full table of file-based SSR and API routes with live search, method badges, dynamic parameters (`[id]`), and target files.
+  - **Models Tab**: All registered ORM models with database tables, columns list, cache strategy (`smart` / `auto`), and soft-delete status.
+  - **Services Tab**: All business services with transaction safety status, authentication guards (`admin`, roles), schemas, and cache TTL.
+  - **Plugins & Config Tabs**: Active plugin manifests, dependencies, and sanitized framework configuration.
+  - **JSON API Endpoints**:
+    - `GET /_webspresso/api/routes`
+    - `GET /_webspresso/api/plugins`
+    - `GET /_webspresso/api/config`
+    - `GET /_webspresso/api/models`
+    - `GET /_webspresso/api/services`
+    - `GET /_webspresso/api/overview` (aggregate system metrics, memory, uptime, node version)
+- **Floating In-Page Dev Toolbar (`fsy.devToolbar()`)**:
+  - Automatically embedded in `views/layout.njk` during development (`NODE_ENV !== 'production'`).
+  - **Collapsed Bottom Pill**:
+    - `⚡ DEV` toggle button with `Alt+D` hotkey shortcut.
+    - Current route method, HTTP status code (`[GET 200] /path`).
+    - Ambient database queries pill (`🗄️ N queries (Xms)`) from `AsyncLocalStorage` request profiler.
+    - Prominent N+1 warning alert badge (`⚠️ N+1 (M)`).
+    - Quick access buttons to `Dashboard (/_webspresso)`, `Admin (/_admin)`, `API Docs (/_swagger)`, and `Schema (/_schema)`.
+  - **Expandable DevTools Drawer (toggled via click or `Alt+D`)**:
+    - **🗄️ SQL Queries Tab**: Execution duration (<40ms green, >40ms red), table pills, formatted SQL statement, and N+1 warning box with actionable suggestions (`repo.query().include(...)`).
+    - **📄 Route & Page Tab**: Route path, matched file, template name, params, and parsed query string.
+    - **🚀 Quick Links Tab**: Configurable tool cards for fast navigation between admin, swagger, and custom tooling.
+    - **💻 System Tab**: Process uptime, memory usage, environment, and Node platform metrics.
+  - **Zero Production Overhead**: When `process.env.NODE_ENV === 'production'`, `devToolbar()` immediately returns `""` with zero overhead.
+
+### 2.19 `oauthPlugin` (`plugins/oauth`)
+Zero-dependency OAuth 2.0 & Social Login plugin supporting Google, GitHub, and custom providers with RFC 7636 PKCE, HMAC-signed anti-CSRF state tokens, and Dual Auth integration.
+- **Options**:
+  - `secret`: Secret key for HMAC state signing (`process.env.OAUTH_SECRET || process.env.SESSION_SECRET`).
+  - `pathPrefix`: Base path for OAuth routes (default `'/auth'`).
+  - `providers`: Provider configuration dictionary (`google`, `github`, or custom).
+  - `defaultReturnTo`: Fallback redirect path after successful login (default `'/'`).
+  - `failureRedirect`: Redirect path on OAuth failure (default `'/login'`).
+  - `findOrCreateUser`: `async ({ provider, profile, tokens, db, req, res }) => user`.
+  - `onSuccess`: `async ({ provider, user, profile, tokens, stateData, req, res, client }) => void`.
+  - `onError`: `async ({ error, provider, req, res, client }) => void`.
+- **Automatic Routes**:
+  - `GET /auth/:provider`: Initiates OAuth authorization flow with PKCE and signed state.
+  - `GET /auth/:provider/callback`: Exchanges authorization code, fetches normalized profile, links or creates user, and logs into session or returns JWT token.
+- **Template Helper**:
+  - `fsy.oauthUrl('google')` ➔ `"/auth/google"`
+  - `fsy.oauthUrl('github', { returnTo: '/dashboard' })` ➔ `"/auth/github?returnTo=%2Fdashboard"`
+
+
+
 
 

package/.agents/QUEUE.md

@@ -111,3 +111,130 @@ module.exports.options = {
   backoff: { type: 'exponential', delay: 2000 },
 };
 ```
+
+---
+
+## 5. Job Retention & Pruning
+
+To prevent the queue database table or memory cache from accumulating indefinitely:
+
+### 1. Auto-Retention in `createQueueManager` / `queuePlugin`
+```js
+queuePlugin({
+  adapter: 'database',
+  db: appDb,
+  retentionDays: 7, // Keep completed jobs for 7 days
+  cleanupIntervalMs: 24 * 60 * 60 * 1000, // Run every 24h
+  autoCleanup: true,
+  retentionStatuses: ['completed'], // or ['completed', 'failed']
+});
+```
+
+### 2. Programmatic `clean()`
+```js
+// Delete completed jobs older than 7 days
+const deletedCount = await queue.clean({
+  days: 7,
+  status: ['completed'], // or 'failed', or ['completed', 'failed']
+});
+
+// Or with an explicit cutoff date:
+await queue.clean({
+  olderThan: new Date(Date.now() - 30 * 24 * 60 * 60 * 1000),
+  status: 'failed',
+});
+```
+
+### 3. CLI Command: `queue:prune`
+```bash
+# Delete completed jobs older than 7 days
+webspresso queue:prune --days 7
+
+# Delete both completed and failed jobs older than 14 days
+webspresso queue:prune --days 14 --status completed,failed
+```
+
+---
+
+## 6. Cron & Recurring Task Scheduler
+
+Webspresso includes a native, zero-dependency task scheduler with a POSIX-compliant 5-field cron parser (`core/queue/cron.js` & `core/queue/scheduler.js`).
+
+### 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`
+- Lists: `1,15,30`, `MON,WED,FRI`
+- Descriptive aliases:
+  - `@yearly`, `@annually` (`0 0 1 1 *`)
+  - `@monthly` (`0 0 1 * *`)
+  - `@weekly` (`0 0 * * 0`)
+  - `@daily`, `@midnight` (`0 0 * * *`)
+  - `@hourly` (`0 * * * *`)
+  - `@every_minute`, `@minutely` (`* * * * *`)
+  - `@every <N>m` (e.g. `@every 5m` → `*/5 * * * *`)
+  - `@every <N>h` (e.g. `@every 2h` → `0 */2 * * *`)
+
+### 2. Programmatic Scheduling
+```js
+// Schedule daily digest at 09:00 AM
+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
+});
+
+// Or use the .cron() alias
+queue.cron('@every 15m', 'metrics.collect');
+
+// Query schedules
+const schedules = queue.getSchedules();
+// [{ id, name, cronExpression, nextRunAt, lastRunAt, isRunning, runsCount, ... }]
+
+// Unschedule by schedule ID or job name
+queue.unschedule('metrics.collect');
+```
+
+### 3. Schedule Options
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `id` | `string` | `schedule:${job}:${cron}` | Custom unique identifier |
+| `overlap` | `boolean` | `false` | When `false`, skips tick if a previous job run is still processing |
+| `maxRuns` | `number` | `null` | Automatically unschedules task after N runs |
+| `utc` | `boolean` | `false` | Evaluate cron expressions in UTC instead of local timezone |
+| `runImmediately` | `boolean` | `false` | Triggers a run right after scheduling |
+
+### 4. File-Based Cron Discovery (`jobs/`)
+Jobs in the `jobs/` folder can automatically declare their recurrence in two ways:
+
+#### Option A: `cron` / `schedule` property in job module
+```js
+// jobs/reports/summary.js
+module.exports = async function(job, ctx) {
+  // run summary logic...
+};
+
+module.exports.cron = '0 8 * * 1-5'; // Every weekday at 8:00 AM
+module.exports.data = { reportType: 'executive' };
+module.exports.options = {
+  overlap: false,
+};
+```
+
+#### Option B: `.cron.js` file naming
+```js
+// jobs/cleanup-logs.cron.js (auto-discovers job name 'cleanup-logs')
+module.exports = {
+  cron: '@daily',
+  handler: async function(job, ctx) {
+    // perform cleanup
+  },
+};
+```
+
+### 5. Lifecycle & Overlap Management
+- The scheduler automatically pauses when `queue.pause()` is called and resumes with `queue.resume()`.
+- On `queue.drain()` or `queue.stop()`, recurring schedules are stopped and active dispatched jobs are given time to complete.
+- Overlap prevention (`overlap: false`) hooks into `job:completed` and `job:failed` events, ensuring slow asynchronous tasks never collide or duplicate.
+