webspresso 0.0.98 → 0.0.99

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,7 +44,7 @@ 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 19 built-in official plugins (including `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).

package/.agents/AUTH.md

@@ -101,3 +101,172 @@ 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 });
+  },
+};
+```
+
+

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' }`
@@ -217,23 +252,37 @@ 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 history with scheduled retention and manual purge API.
+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
   ```
-- **API & Admin Panel**:
-  - `POST /_admin/api/audit-logs/purge`: `{ days: 90 }` or `{ olderThan: '2026-01-01' }`
-  - "Purge 90d" button directly in the Admin Panel audit log viewer.
-  - Lifecycle integration: background timers use `.unref()` and clean up on server shutdown.
 
 ### 2.13 `ormCacheAdminPlugin` (`plugins/orm-cache-admin`)
 ORM Cache inspection and invalidation dashboard.
@@ -558,6 +607,25 @@ Interactive Webspresso Developer Dashboard SPA mounted at `/_webspresso` and Flo
     - **💻 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

@@ -154,3 +154,87 @@ webspresso queue:prune --days 7
 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.
+