webspresso 0.0.96 → 0.0.98

package/.agents/ADMIN.md

@@ -133,7 +133,59 @@ registry.registerPageDir(path.join(__dirname, 'admin-pages'));
 
 ---
 
-## 5. Custom Field Renderers (`registerFieldRenderer`)
+## 5. Page & Plugin Title Management
+
+Admin Panel supports configurable base titles, title templates, and dynamic SPA page titles:
+
+### Plugin Configuration
+```js
+adminPanelPlugin({
+  db,
+  title: 'Acme Admin',           // Base title in <title> and header (default: 'Admin Panel')
+  titleTemplate: '%s | %b',      // Format template: %s = page title, %b = base title (default: '%s | %b')
+});
+```
+
+### Module & Page Title Configuration
+When registering modules and custom pages, titles are automatically propagated to navigation and browser document title:
+```js
+adminApi.registerModule({
+  id: 'reports',
+  title: 'Reports & Analytics',   // Module fallback title
+  pages: [
+    {
+      id: 'monthly-report',
+      title: 'Monthly Report',    // Document title -> "Monthly Report | Acme Admin"
+      path: '/reports/monthly',
+      component: ...,
+    },
+    {
+      id: 'live-dashboard',
+      documentTitle: 'Live Monitor (Fullscreen)', // Raw document.title override
+      path: '/reports/live',
+      layout: false,
+      component: ...,
+    }
+  ]
+});
+```
+
+### Dynamic Client-Side Title Helper (`setAdminPageTitle`)
+From any Mithril component or client script:
+```js
+// Dynamic title formatted with template (e.g. "Sales Overview | Acme Admin")
+window.setAdminPageTitle('Sales Overview');
+
+// Custom template override
+window.setAdminPageTitle('Sales Overview', { template: '%s — %b' });
+
+// Raw document title without template
+window.setAdminPageTitle('Sales Overview', { raw: true });
+```
+
+---
+
+## 6. Custom Field Renderers (`registerFieldRenderer`)
 
 Register custom display and edit renderers for specific column types:
 
@@ -152,7 +204,7 @@ registry.registerFieldRenderer('color-picker', {
 
 ---
 
-## 6. Dashboard Widgets (`registerWidget`)
+## 7. Dashboard Widgets (`registerWidget`)
 
 Register dashboard widgets for the Admin overview screen:
 
@@ -164,9 +216,20 @@ registry.registerWidget('recent-orders', {
 });
 ```
 
+### Built-in Dashboard Widgets
+- **`model-stats`**: Model overview cards displaying record counts, column counts, and last update timestamps.
+- **`database-storage`**: Database Storage & Health monitor showing:
+  - Database engine (SQLite, PostgreSQL, MySQL) & active file sizes
+  - Total tables and total record counts across the schema
+  - Storage health status badge with high-volume alerts for unpruned logs
+  - 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).
+
 ---
 
-## 7. Single Record & Bulk Table Actions
+## 8. Single Record & Bulk Table Actions
 
 Add custom action buttons to model table views:
 
@@ -196,7 +259,7 @@ registry.registerBulkAction('Product', {
 
 ---
 
-## 8. Client Components & Custom Client Script Injections
+## 9. Client Components & Custom Client Script Injections
 
 Inject custom client-side JavaScript / Mithril components into the Admin SPA runtime:
 
@@ -213,7 +276,7 @@ registry.registerClientComponent('custom-banner', `
 
 ---
 
-## 9. Offline & Zero-CDN Architecture
+## 10. Offline & Zero-CDN Architecture
 
 The Admin Panel is 100% self-contained and operates completely offline without external CDN dependencies (`unpkg.com`, `cdn.jsdelivr.net`, or `cdn.tailwindcss.com`):
 - **Vendored Static Assets (`plugins/admin-panel/vendor/`)**:
@@ -223,3 +286,88 @@ The Admin Panel is 100% self-contained and operates completely offline without e
 - **Local Asset Serving**: Served locally at `GET /_admin/vendor/:file` with proper MIME types, path traversal protections, and `Cache-Control: public, max-age=86400` caching.
 - **Hardened CSP**: Works in air-gapped / intranet environments with strict `'self'` Content Security Policy without leaking third-party network requests.
 
+---
+
+## 11. Toast Notifications, Modal Confirmations & Session Expiry UX
+
+The Admin SPA includes a built-in reactive notification and modal system that replaces intrusive browser `alert()` and `confirm()` dialogs.
+
+### Toast Notifications (`window.notify`)
+Display auto-dismissing, animated toasts in the top-right corner with pause-on-hover:
+
+```js
+// Available on window.notify or as global helpers: notifySuccess, notifyError, notifyWarning, notifyInfo
+notify.success('Record created successfully');
+notify.error('Failed to save record: Validation error');
+notify.warning('Please review unsaved changes');
+notify.info('Export started in the background');
+
+// Custom duration (TTL in milliseconds, default 4000ms):
+notify.success('Saved!', 2000);
+```
+
+### Confirmation Modal (`window.confirmModal` / `confirmAction`)
+Display an accessible, styled modal dialog returning a Promise resolving to `true` or `false`:
+
+```js
+// Destructive confirmation (danger: true highlights the confirm button in red)
+const confirmed = await confirmAction({
+  title: 'Delete User',
+  message: 'Are you sure you want to permanently delete this user?',
+  confirmText: 'Delete',
+  cancelText: 'Cancel',
+  danger: true,
+});
+
+if (confirmed) {
+  await api.delete(`/users/${id}`);
+  notify.success('User deleted');
+}
+```
+
+### Session Expiration & Intended Return-To Redirection
+When an authenticated staff user's session expires or an API call returns `401 Unauthorized`:
+1. `redirectToLogin('expired')` captures the active route and redirects to `/_admin/#!/login?returnTo=<route>&reason=expired`.
+2. The login screen displays an informational notice banner: *"Your session has expired. Please sign in again."*
+3. After authenticating successfully, the user is automatically redirected to their intended route.
+4. **Open-Redirect Hardening**: All return destinations are strictly validated by `isSafeIntendedRoute(path)` to disallow protocol-relative URLs (`//evil.com`), foreign protocols (`http:`, `javascript:`), or backslashes.
+
+---
+
+## 12. Admin Login Brute-Force Protection & Rate Limiting
+
+The Admin Panel includes built-in in-memory rate limiting to defend staff login endpoints against credential stuffing and brute-force password guessing.
+
+### Configuration (`adminPanelPlugin`)
+
+```js
+import { createApp, adminPanelPlugin } from 'webspresso';
+
+const app = createApp({
+  plugins: [
+    adminPanelPlugin({
+      db,
+      // Configure or disable login rate limiting:
+      loginRateLimit: {
+        enabled: true,                  // Default: true
+        maxAttempts: 5,                 // Max failed attempts before blocking (default: 5)
+        windowMs: 15 * 60 * 1000,       // Tracking window (default: 15 minutes)
+        blockDurationMs: 15 * 60 * 1000 // Temporary block duration (default: 15 minutes)
+      },
+    }),
+  ],
+});
+```
+
+To disable rate limiting (e.g. in test or internal automated environments):
+```js
+adminPanelPlugin({ db, loginRateLimit: false });
+```
+
+### Protection Mechanics
+- **IP Tracking**: Tracks failed attempts keyed by client IP (`req.ip` or upstream trusted proxy headers).
+- **Automatic Block**: After `maxAttempts` failed logins within `windowMs`, returns HTTP 429 Too Many Requests with a `Retry-After: <seconds>` response header and JSON error payload.
+- **Success Reset**: A single successful login clears the failed attempt counter for that IP.
+- **Programmatic Reset**: Cleared automatically upon server restart or via `plugin.api.resetLoginAttempts(ip)`.
+
+

package/.agents/ARCHITECTURE.md

@@ -116,4 +116,14 @@ Plugins expose `name`, `version`, `dependencies`, and lifecycle hooks (`register
 | `xlsxPlugin` | Excel / Export | Excel spreadsheet generation, parsing, ORM streaming export (`res.xlsx`), and services |
 | `csvPlugin` | CSV / Export | RFC 4180 CSV generator, parser, Excel UTF-8 BOM, streaming writer (`res.csv`), and services |
 
+---
+
+## 5. Developer Experience & Live/Hot Reload (`src/dev-reload/`)
+
+- **Zero-Dependency SSE Reload Hub**: Enabled via `createApp({ devReload: true })` (or `devReload: { watchTemplates: true, watchCss: true, debounce: 50 }`).
+- **Instant CSS Hot Swap**: Modifying `.css` files dynamically refreshes all `<link rel="stylesheet">` elements without page refresh or DOM state loss.
+- **Template & Layout Live Reload**: Modifying Nunjucks templates (`.njk`, `.html`) in `views/` or pages in `pages/` automatically invalidates frontmatter/loader caches and broadcasts a debounced `'full'` reload event to active browser tabs.
+- **Error Overlay Frame**: Client runtime script automatically renders terminal-free in-browser error frames for compile/build errors with line numbers and dismiss keyboard shortcuts (`Esc`).
+- **DevTools Toolbar & Dashboard**: Embedded via `fsy.devToolbar()` and available at `/_webspresso` for interactive inspection of routes, models, services, cache, and profiler metrics.
+
 

package/.agents/CLI.md

@@ -13,8 +13,12 @@ npx webspresso dev
 #   --port, -p <number> (default: 3001)
 #   --host <string> (default: localhost)
 
-# Build production bundle / verify assets
+# Build production bundle / compile assets (Tailwind + esbuild with manifest.json)
 npx webspresso build
+# Flags:
+#   --no-css    (skip CSS build)
+#   --no-js     (skip JS bundle build)
+#   --no-hash   (disable content hashing in filenames)
 ```
 
 ---
@@ -113,3 +117,193 @@ npx webspresso agents:init
 npx webspresso agents:init --force
 ```
 
+---
+
+## 8. Tailwind CSS Setup & Migration (`add:tailwind`)
+
+Add or upgrade Tailwind CSS in a project:
+
+```bash
+# Add Tailwind CSS v4 (Oxide engine, LightningCSS, zero-config)
+npx webspresso add tailwind --v4
+
+# Add Tailwind CSS v3 (legacy PostCSS engine)
+npx webspresso add tailwind --v3
+
+# Upgrade existing Tailwind v3 project to v4
+npx webspresso add tailwind --upgrade
+```
+
+---
+
+## 9. Client Bundler Setup (`add:esbuild`)
+
+Add client-side JS/TS bundling with esbuild incremental watching:
+
+```bash
+# Scaffold esbuild client bundler setup
+npx webspresso add esbuild
+# or
+npx webspresso add:esbuild
+```
+
+---
+
+## 10. Data Retention & Storage Cleanup Commands
+
+Keep databases and storage clean by pruning historical records and unreferenced files:
+
+```bash
+# Delete audit log entries older than N days (default: 90)
+npx webspresso audit:prune --days 90
+
+# Delete email delivery logs older than N days (default: 90)
+npx webspresso email:prune --days 90
+
+# Delete completed/failed background jobs older than N days (default: 30)
+npx webspresso queue:prune --days 30
+
+# Delete expired site analytics visits & JS errors older than N days
+npx webspresso analytics:prune --days 90
+
+# Scan and delete orphaned uploads not referenced by any database model
+npx webspresso upload:prune
+
+# Dry run mode (inspect orphaned files without deleting)
+npx webspresso upload:prune --dry-run
+```
+
+---
+
+## 11. Routes Introspection (`routes`)
+
+List and inspect all compiled file-based and API routes in terminal:
+
+```bash
+# List all application routes in a colorized table
+npx webspresso routes
+
+# Filter to only API endpoints
+npx webspresso routes --api
+
+# Filter to only SSR page routes
+npx webspresso routes --pages
+
+# Output routes as machine-readable JSON
+npx webspresso routes --json
+```
+
+---
+
+## 12. Dev Server DX & Query Profiler
+
+When starting in development mode (`isDev: true` / `process.env.NODE_ENV !== 'production'`), Webspresso automatically:
+
+- **Displays Startup Banner**: ASCII box with Node/Framework version, Local & Admin URLs, Database dialect, and counts of routes, models, services, and plugins.
+- **Request Profiler & Logger**: Color-coded HTTP requests with status, response duration, and database metrics:
+  ```text
+  [GET 200] /api/notes — 14.2ms | 2 DB queries (2.8ms)
+  ```
+- **N+1 Query Detection**: Flags queries executing repeatedly against the same table within a single request:
+  ```text
+  ⚠️  [webspresso:n+1] Potential N+1 query pattern detected on table 'users' (5 queries, 6.4ms). Consider eager loading with repo.query().include('users') or batching.
+  ```
+- **Configuration (`dev` options in `createApp`)**:
+  ```javascript
+  createApp({
+    dev: {
+      banner: true,        // show startup banner (default: true in dev)
+      routeTable: true,    // show route table in banner (default: true)
+      profiler: true,      // enable request & DB profiler (default: true)
+      nPlusOne: true,      // detect N+1 queries (default: true)
+      nPlusOneThreshold: 4,// query count threshold for warning (default: 4)
+      slowQueryMs: 50,     // flag queries slower than N ms (default: 50)
+      verbose: false,      // log individual SQL statements
+    }
+  });
+  ```
+
+---
+
+## 13. Scaffolding & Code Generation (`make:*` Commands)
+
+Quickly generate boilerplate adhering strictly to Webspresso contracts:
+
+```bash
+# 1. Scaffold an ORM Model in models/<Name>.js with parsed zdb fields and Knex migration
+npx webspresso make:model Post --fields title:string,content:text,published:boolean,views:integer --migration
+# Flags:
+#   --fields <list>   (title:string,content:text,views:integer,price:number,published:boolean,authorId:id)
+#   --table <name>    (custom table name; defaults to pluralized lowercase)
+#   --migration, -m   (auto-generate timestamped Knex migration in migrations/)
+#   --soft-deletes    (include deletedAt column and default scope)
+
+# 2. Scaffold API Endpoints in pages/api/
+# Single endpoint with Zod validation and handler:
+npx webspresso make:api notes/export --method POST --auth
+
+# Full REST CRUD Suite (list, create, detail, update, delete) in pages/api/posts:
+npx webspresso make:api posts --crud --model Post
+
+# 3. Scaffold an SSR Page in pages/
+npx webspresso make:page blog/[slug]
+# Generates pages/blog/[slug].njk template + companion loader pages/blog/[slug].js
+
+# 4. Scaffold a Service in services/<domain>/<action>.js
+npx webspresso make:service order.process --transaction --auth admin
+
+# 5. Scaffold a Background Queue Worker in jobs/<name>.js
+npx webspresso make:job send-welcome-email --queue default --retries 3
+```
+
+---
+
+## 14. OpenAPI & API Documentation Export (`openapi` / `api:docs`)
+
+Generate and export standard OpenAPI 3.0 JSON specification from file-based API routes and Zod schemas:
+
+```bash
+# Print OpenAPI 3.0 specification to stdout
+npx webspresso openapi
+
+# Export directly to a JSON file
+npx webspresso openapi --out openapi.json
+
+# Export with custom title, version, and server URL
+npx webspresso api:docs --out public/openapi.json --title "My API" --api-version "2.0.0" --server "https://api.myapp.com"
+
+# Include ORM model schemas in components.schemas
+npx webspresso openapi --out openapi.json --include-orm
+```
+
+---
+
+## 15. TypeScript Definitions & IDE Auto-Complete Generator (`typegen` / `types`)
+
+Scan ORM models, business services, and routes to automatically generate typed TypeScript declaration files (`.webspresso/types.d.ts` and `webspresso-env.d.ts`) with module augmentation:
+
+```bash
+# Generate TypeScript definitions
+npx webspresso typegen
+
+# Aliases
+npx webspresso types
+npx webspresso generate:types
+
+# Watch mode (automatically regenerates on model/service/page edits)
+npx webspresso typegen --watch
+
+# Custom output destination
+npx webspresso typegen --out types/webspresso.d.ts --no-env-file
+```
+
+### Generated Capabilities & IDE DX:
+- **Typed Models (`db.getRepository('Model')`)**: Auto-completes model names and infers entity column types from Zod schemas.
+- **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.
+
+
+
+
+
+

package/.agents/PLUGINS.md

@@ -91,6 +91,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 +124,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 +217,86 @@ 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 and audit history with scheduled retention and manual purge API.
+- **Options**:
+  - `db`: Database instance (must expose `.knex`).
+  - `tableName`: Database table name (default `'audit_logs'`).
+  - `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).
+- **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.
 
 ### 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');
+
+  const { app } = createApp({
+    plugins: [
+      adminPanelPlugin({ db }),
+      schemaExplorerPlugin({ admin: true }),
+    ],
+  });
+  ```
 
-### 2.15 `swaggerPlugin` (`plugins/swagger`)
-Interactive OpenAPI 3.0 Swagger UI documentation.
+### 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 +523,41 @@ 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.
+
+
 
 

package/.agents/QUEUE.md

@@ -111,3 +111,46 @@ 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
+```
+