webspresso 0.0.100 → 0.0.101

package/.agents/ADMIN.md

@@ -46,6 +46,31 @@ export default defineModel({
     sortableColumns: ['name', 'price'], // Optional whitelist of sortable columns
     sortable: true,          // Set false to disable table sorting completely
     readOnly: false,         // Disable create/edit/delete actions
+    
+    // Django Admin-inspired Features:
+    inlines: [               // Parent-child relational editing (Tabular/Stacked)
+      {
+        model: 'ProductVariant',
+        foreignKey: 'product_id',
+        fields: ['sku', 'price', 'inventory'],
+        title: 'Variants',
+      },
+    ],
+    listEditable: ['price', 'status'], // Direct table row quick-edit without opening edit form
+    dateHierarchy: 'created_at',        // Period drilldown navigation (Years -> Months -> Days)
+    listFilter: ['status'],             // Faceted filtering with record counts per value
+    actions: [                          // Declarative model-level bulk operations
+      {
+        id: 'mark-active',
+        label: 'Mark as Active',
+        handler: async ({ ids, repo, db, req, user }) => {
+          for (const id of ids) {
+            await repo.update(id, { status: 'active' });
+          }
+          return { updated: ids.length };
+        },
+      },
+    ],
   },
 });
 ```
@@ -68,13 +93,31 @@ Column sortability can be configured per-column:
 The Admin SPA communicates with the backend via JSON REST endpoints:
 
 - `GET /_admin/api/models` — List all models exposed to admin with schemas & metadata.
-- `GET /_admin/api/models/:modelName/records` — List paginated records (query params: `page`, `limit`, `search`, `filter`, `sort`).
-- `GET /_admin/api/models/:modelName/records/:id` — Retrieve single record details.
-- `POST /_admin/api/models/:modelName/records` — Create new record.
-- `PUT /_admin/api/models/:modelName/records/:id` — Update existing record.
+- `GET /_admin/api/models/:modelName/records` — List paginated records (query params: `page`, `limit`, `search`, `filter`, `sort`, `year`, `month`, `day`).
+- `GET /_admin/api/models/:modelName/records/:id` — Retrieve single record details (auto-loads `_inlines` if defined).
+- `POST /_admin/api/models/:modelName/records` — Create new record (syncs `_inlines` automatically).
+- `PUT /_admin/api/models/:modelName/records/:id` — Update existing record (syncs `_inlines` updates, additions, and deletions with `_delete: true`).
 - `DELETE /_admin/api/models/:modelName/records/:id` — Delete record (soft or hard delete).
 - `POST /_admin/api/models/:modelName/records/:id/restore` — Restore soft-deleted record.
 
+### Inline Model Relational Endpoints (Django Inlines)
+- `GET /_admin/api/models/:model/records/:id/inlines/:inlineModel` — List child items belonging to parent record.
+- `POST /_admin/api/models/:model/records/:id/inlines/:inlineModel` — Create a child item attached to parent.
+- `PUT /_admin/api/models/:model/records/:id/inlines/:inlineModel/:inlineId` — Update specific child item.
+- `DELETE /_admin/api/models/:model/records/:id/inlines/:inlineModel/:inlineId` — Delete child item.
+
+### Fast Inline & Batch Editing (Django `list_editable`)
+- `PATCH /_admin/api/models/:model/records/:id/quick-edit` — Quickly update allowed `listEditable` columns for a single row without full form submission.
+- `PATCH /_admin/api/models/:model/records/batch-edit` — Save multiple table row edits simultaneously (`{ updates: [{ id, changes }] }`).
+
+### Date Hierarchy & Faceted Filters (Django `date_hierarchy` & `list_filter`)
+- `GET /_admin/api/models/:model/date-hierarchy` — Drilldown periods with counts (`?year=...&month=...`).
+- `GET /_admin/api/models/:model/filter-facets` — Retrieve distinct values with record counts for `listFilter` columns.
+
+### Model Actions (Django Actions)
+- `POST /_admin/api/models/:model/actions/:actionId` — Execute declarative action on selected record IDs (`{ ids: [...] }`).
+
+
 ---
 
 ## 4. Custom Pages (`registerModule` / `registerPageDir`)

package/.agents/AGENTS.md

@@ -17,6 +17,7 @@ When tasked with a feature or bugfix, **immediately consult the corresponding to
 | **Admin Panel (Page, Widget, Action, UI)** | [`.agents/ADMIN.md`](ADMIN.md) | `plugins/admin-panel/` |
 | **Authentication (Session / JWT / Guard)** | [`.agents/AUTH.md`](AUTH.md) | `core/auth/` |
 | **Background Jobs & Worker Queue** | [`.agents/QUEUE.md`](QUEUE.md) | `jobs/` |
+| **Decoupled Events & Signals** | [`.agents/EVENTS.md`](EVENTS.md) | `core/events/`, `listeners/` |
 | **API Signatures & Types Verification** | [`index.d.ts`](../index.d.ts) | **Canonical Ground Truth** |
 
 ---
@@ -54,6 +55,7 @@ This `.agents/` customization root is organized into modular topic guides:
 16. **[Background Job Queue](.agents/QUEUE.md)** — In-Memory, Knex Database, and Distributed Redis queue adapters, job auto-discovery (`jobs/`), retries, and graceful draining.
 17. **[SSR Streaming & Chunked Transfer](.agents/STREAMING.md)** — Native HTTP chunked streaming (`res.renderStream()`), deferred data loader slots (`defer: { key: promise }`), and TTFB optimization.
 18. **Polar billing production checklist** — [docs/guides/polar-production-checklist.md](../docs/guides/polar-production-checklist.md) (env, webhooks, rate limits, external tier hooks, CSP). Plugin reference: [PLUGINS.md § polarPlugin](PLUGINS.md).
+19. **[Decoupled Events & Signals Architecture](.agents/EVENTS.md)** — Zero-dependency enterprise event dispatcher (`core/events`), sync/async/parallel/serial/waterfall dispatch, wildcard listeners (`order.*`), Django-style `Signal` and sender filtering, queue bridging, and listener auto-discovery.
 
 ---
 

package/.agents/AUTH.md

@@ -514,5 +514,68 @@ auth.on('sessions:revoked_all', ({ userId, count }) => {
 });
 ```
 
+---
+
+## 9. Authorization & Policies (AdonisJS Bouncer & Django Permissions-inspired)
+
+Webspresso provides an authorization layer combining AdonisJS Bouncer policies/gates with Django-style permission matrices and superuser bypass:
+
+### 9.1 Defining Policies & Gates
+Define domain policies and simple gates using `definePolicy` and `defineGate`:
+
+```javascript
+const { definePolicy, defineGate } = require('webspresso');
+
+// 1. Resource Policy
+definePolicy('Post', {
+  view: (user, post) => true,
+  update: (user, post) => user && (user.id === post.user_id || user.role === 'admin'),
+  delete: (user, post) => user && user.role === 'admin',
+});
+
+// 2. Named Gate
+defineGate('admin-only', (user) => Boolean(user && user.role === 'admin'));
+```
+
+### 9.2 Request Bouncer (`req.bouncer`)
+Incoming requests automatically receive `req.bouncer` bound to `req.user`:
+
+```javascript
+// Inside API Route or Loader:
+if (req.bouncer.allows('Post.update', post)) {
+  // Authorized
+}
+
+if (req.bouncer.denies('admin-only')) {
+  // Denied
+}
+
+// Throws ForbiddenError (403) or UnauthorizedError (401) on failure:
+req.bouncer.authorize('Post.update', post);
+
+// Inline rule check:
+req.bouncer.authorize((user) => user.isVip);
+```
+
+### 9.3 Django Permissions Matrix & Superuser Bypass
+Users with permissions arrays or superuser flags are evaluated automatically:
+- `user.permissions = ['post.create', 'post.update']`
+- Wildcards: `user.permissions = ['post.*']` or `['*']`
+- Django Superuser: `user.isSuperuser = true` or `user.is_superuser = true` automatically bypasses all permission checks.
+- Custom methods: `user.hasPerm(perm, resource)` or `user.hasPermission(...)`.
+
+### 9.4 Nunjucks Template Helpers (`fsy.can`, `fsy.cannot`)
+Check permissions directly in `.njk` templates:
+
+```jinja
+{% if fsy.can('Post.update', post) %}
+  <a href="/posts/{{ post.id }}/edit" class="btn">Edit Post</a>
+{% endif %}
+
+{% if fsy.cannot('admin-only') %}
+  <p class="text-muted">Admin access required</p>
+{% endif %}
+```
+
 
 

package/.agents/CLI.md

@@ -354,3 +354,84 @@ npx webspresso deploy:check --json
 3. **Container Hardening**: Ensures `Dockerfile` runs as a non-root `USER`, configures a `HEALTHCHECK`, and uses multi-stage caching.
 4. **Database & Migrations**: Audits for pending unapplied migrations and warns against ephemeral SQLite storage.
 5. **Server Optimizations**: Validates HTTP compression (`compression: true`), graceful shutdown, and health check endpoints.
+
+---
+
+## 18. Custom Management Commands (`run`, `command:run`, `defineCommand`) [Django manage.py & Adonis Ace]
+
+Create and execute isolated management scripts, background cron tasks, data migrations, or maintenance routines with full framework dependency injection (`db`, `queue`, `services`, `mailer`, `events`, `logger`, `args`, `flags`):
+
+```bash
+# List all custom management commands in commands/
+npx webspresso run
+
+# Execute a custom command with positional arguments and options
+npx webspresso run sync-stripe --dry-run --limit 100
+```
+
+### Defining a Custom Command (`commands/<name>.js`):
+
+```javascript
+const { defineCommand } = require('webspresso');
+
+module.exports = defineCommand({
+  name: 'sync-stripe',
+  description: 'Synchronize customer subscriptions from Stripe',
+  options: [
+    { flags: '-d, --dry-run', description: 'Simulate without committing changes', defaultValue: false },
+    { flags: '-l, --limit <count>', description: 'Maximum customers to sync', defaultValue: 100 },
+  ],
+  handle: async ({ db, queue, services, mailer, events, logger, args, flags }) => {
+    logger.log('Starting sync, dryRun:', flags.dryRun);
+
+    const userRepo = db.getRepository('User');
+    const users = await userRepo.find({ active: true });
+
+    // Events, mailer, and background jobs are fully accessible:
+    events.emit('stripe:sync-started', { count: users.length });
+
+    return { synced: users.length };
+  },
+});
+```
+
+---
+
+## 19. Command Palette Index (`list`, `commands`)
+
+Print an organized catalog of all built-in commands (scaffolding, database, server, developer tools) alongside all auto-discovered custom commands in your project:
+
+```bash
+npx webspresso list
+# or
+npx webspresso commands
+```
+
+---
+
+## 20. Advanced Scaffolding Generators (`make:*`) [Adonis Ace style]
+
+Rapidly generate boilerplate code following Webspresso architectural conventions:
+
+```bash
+# 1. Custom Management Command
+npx webspresso make:command users:cleanup --desc "Purge unverified user accounts"
+# Outputs: commands/users/cleanup.js
+
+# 2. Authorization Policy (Bouncer)
+npx webspresso make:policy Article
+# Outputs: policies/article.policy.js
+
+# 3. Model Factory (Testing & Seeding)
+npx webspresso make:factory Product
+# Outputs: factories/product.factory.js
+
+# 4. Decoupled Event Listener
+npx webspresso make:event order:completed
+# Outputs: listeners/order-completed.js
+
+# 5. Declarative Mailable Class
+npx webspresso make:mail Welcome
+# Outputs: emails/WelcomeEmail.js
+```
+

package/.agents/EMAIL.md

@@ -102,11 +102,92 @@ emailApi.registerTemplate('notification', '<mjml><mj-body>...</mj-body></mjml>')
 const isReady = await emailApi.verifyConnection();
 const logs = await emailApi.queryLogs({ status: 'sent', limit: 20 });
 await emailApi.purgeLogs({ olderThan: '30d' });
+
+// 6. In-memory outbox inspection & clearing (memory backend / tests)
+const outbox = emailApi.getOutbox();
+const lastSent = emailApi.lastMessage();
+emailApi.clearOutbox();
+```
+
+---
+
+## 5. Declarative `Mailable` Classes (AdonisJS-style)
+
+Define structured, reusable, object-oriented emails by extending `Mailable`:
+
+```javascript
+import { Mailable } from 'webspresso';
+
+export class WelcomeEmail extends Mailable {
+  constructor(user) {
+    super();
+    this.user = user;
+  }
+
+  build() {
+    this.to(this.user.email, this.user.name)
+      .from('team@myapp.com', 'Acme Team')
+      .subject(`Welcome to Acme, ${this.user.name}!`)
+      .view('welcome', { user: this.user }) // references registered template
+      .attach({
+        filename: 'welcome-guide.pdf',
+        content: Buffer.from('...'),
+      });
+  }
+}
+
+// In route handlers or services:
+await req.mailer.send(new WelcomeEmail(user));
+// Or via email API:
+await emailApi.send(new WelcomeEmail(user));
+```
+
+### Fluent Mailable Methods
+
+- `to(address, name?)`, `cc(address, name?)`, `bcc(address, name?)`, `replyTo(address, name?)`, `from(address, name?)`
+- `subject(title)`
+- `view(templateName, data?)` or `template(templateName)`
+- `html(htmlContent)`, `text(textContent)`
+- `attach({ filename, content, path, contentType })`
+- `header(name, value)`
+- `prepare()` and `build()` lifecycle hooks
+- `toMessage()` serializes the definition into a message payload
+
+---
+
+## 6. Pluggable Transports (Django-style Backends)
+
+Configure backends via `backend`: `'smtp' | 'memory' | 'console' | 'file'`:
+
+```javascript
+const email = emailPlugin({
+  backend: process.env.NODE_ENV === 'production' ? 'smtp' : 'memory',
+  fileDir: './storage/emails', // when backend: 'file'
+  devInbox: true, // enables developer inbox web UI
+});
 ```
 
+- **`MemoryTransport`**: Stores messages in an in-memory inspectable outbox (`mailer.getOutbox()`). Automatically chosen in test environments.
+- **`ConsoleTransport`**: Pretty-prints sent emails to stdout/logger for zero-setup terminal debugging.
+- **`FileTransport`**: Writes JSON/EML email files to a local directory for disk-based inspection.
+- **`NodemailerTransport`**: Delivers real emails via SMTP or custom transport in production.
+
 ---
 
-## 5. Auth Email Bridge (`authEmails`)
+## 7. Developer Mail Preview & Dev Inbox (`/_webspresso/mail-preview`)
+
+When `devInbox: true` or running in `development` mode, Webspresso automatically mounts a local inbox viewer:
+
+- **Web UI Route**: `GET /_webspresso/mail-preview` (responsive inbox viewer with desktop, tablet, and mobile viewport switcher)
+- **JSON List Route**: `GET /_webspresso/mail-preview/api/messages`
+- **Single Message Route**: `GET /_webspresso/mail-preview/api/messages/:id`
+- **Iframe HTML View**: `GET /_webspresso/mail-preview/api/messages/:id/html`
+- **Clear Inbox Route**: `POST /_webspresso/mail-preview/api/clear`
+- **Template Preview**: `POST /_webspresso/mail-preview/api/preview`
+
+---
+
+## 8. Auth Email Bridge (`authEmails`)
 
 Automatically wires password reset and email verification flows with `AuthManager`:
 
@@ -131,7 +212,7 @@ const email = emailPlugin({
 
 ---
 
-## 6. Admin Panel UI & Database Logs
+## 9. Admin Panel UI & Database Logs
 
 When `includeAdminPage: true` and `adminPanelPlugin` are present, an interactive Email Management module is mounted at `/_admin/email`:
 
@@ -139,3 +220,4 @@ When `includeAdminPage: true` and `adminPanelPlugin` are present, an interactive
 - **Test Sender**: Send test emails directly from the Admin Panel to verify SMTP configuration.
 - **Audit Logs Inspector**: Filter sent email logs by status (`sent`, `failed`), view error tracebacks, and purge historic logs.
 - **Database Schema**: Log entries are stored in `email_logs` table (`id`, `to_email`, `subject`, `template_name`, `status`, `error`, `created_at`).
+

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

@@ -400,5 +400,64 @@ await authorRepo.restore(authorId, { cascade: false });
 
 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/ROUTING.md

@@ -435,7 +435,70 @@ In SSR streaming mode (`stream: true` or `renderStream`):
 
 ---
 
-## 7. Summary Checklist for Agents
+## 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 }}
+```
+
+---
+
+## 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`).

package/AGENTS.md

@@ -17,6 +17,7 @@ When tasked with a feature or bugfix, **immediately consult the corresponding to
 | **Admin Panel (Page, Widget, Action, UI)** | [`.agents/ADMIN.md`](.agents/ADMIN.md) | `plugins/admin-panel/` |
 | **Authentication (Session / JWT / Guard)** | [`.agents/AUTH.md`](.agents/AUTH.md) | `core/auth/` |
 | **Background Jobs & Worker Queue** | [`.agents/QUEUE.md`](.agents/QUEUE.md) | `jobs/` |
+| **Decoupled Events & Signals** | [`.agents/EVENTS.md`](.agents/EVENTS.md) | `core/events/`, `listeners/` |
 | **API Signatures & Types Verification** | [`index.d.ts`](index.d.ts) | **Canonical Ground Truth** |
 
 ---