odac 1.3.0 → 1.4.0

package/.agent/rules/memory.md

@@ -39,4 +39,10 @@ trigger: always_on
 ## Testing & Validation
 - **Mandatory Test Coverage:** Every new feature, method, or significant logic change MUST be accompanied by a corresponding unit or integration test.
     - **Verify Correctness:** do not assume code works; prove it with a test that covers both success and failure scenarios (e.g., edge cases, error conditions).
-    - **Update Existing Tests:** If a feature modifies existing behavior, update the relevant tests to reflect the new logic and ensure they pass.
+    - **Update Existing Tests:** If a feature modifies existing behavior, update the relevant tests to reflect the new logic and ensure they pass.
+
+## Client Library (odac.js)
+- **Automatic JSON Parsing:** The `#ajax` method (and by extension `odac.get`) must automatically parse the response if the `Content-Type` header contains `application/json`, even if `dataType` is not explicitly set to `json`.
+
+## Security Logic & Authentication
+- **Enterprise Token Rotation:** The `Auth.js` system utilizes a non-blocking refresh token rotation mechanism for cookies (`odac_x`/`odac_y`). To prevent race conditions during concurrent requests in high-throughput SPAs, rotated tokens are **not** immediately deleted. Instead, their `active` timestamp is set to naturally expire in 60 seconds (Grace Period), and their `date` timestamp is set to the Unix Epoch (`new Date(0)`) as an identifier mark. Never delete rotated tokens immediately.

package/.github/workflows/release.yml

@@ -41,10 +41,6 @@ jobs:
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: npx semantic-release
-
-      - name: Publish to npm
-        run: npm publish --provenance --access public
-      
       - name: Get version
         id: version
         run: echo "version=$(node -p "require('./package.json').version")" >> $GITHUB_OUTPUT

package/AGENTS.md

@@ -0,0 +1,47 @@
+# ODAC Agent Instructions
+
+You are an AI Agent operating within the **ODAC Framework** repository. This document outlines the core principles, architectural standards, and operational guidelines you MUST follow to maintain the integrity and performance of this enterprise-grade system.
+
+## 1. Project Identity & Philosophy
+- **Name:** ODAC (Always uppercase in strings/docs/logs).
+- **Core Goal:** To provide a robust, zero-config, high-performance Node.js framework for distributed cloud applications.
+- **The "Big 3" Priorities:**
+    1. **Enterprise-Level Security:** Security is foundational. Default to secure, validate all inputs, sanitize all outputs.
+    2. **Zero-Config:** Works out-of-the-box. Convention over configuration.
+    3. **High Performance:** Optimize for throughput and low latency (Sub-millisecond targets).
+
+## 2. Architectural Principles
+- **Asynchronous & Non-Blocking:** Exclusively use non-blocking I/O. Use `fs.promises` instead of sync methods.
+- **Dependency Injection (DI):** Build components with DI for maximum testability.
+- **Single Responsibility Principle (SRP):** Keep classes and functions focused and small.
+- **Memory Management:** Be paranoid about leaks. Clean up listeners, streams, and connections.
+- **O(n log n) Bound:** Prioritize O(1) or O(n log n) algorithms. Justify any O(n²) operations.
+
+## 3. Coding Standards & Integrity
+- **Modern JavaScript:** Use ES6+ features, ES Modules (import/export). 
+- **Strictly Prohibited:** **No usage of `var`**. Use `const` (preferred) or `let`.
+- **Fail-Fast Pattern:** Implement early returns for negative cases. Avoid deeply nested `if/else`.
+- **Anti-Spaghetti Rules:**
+    - Resolve Promises upfront (e.g., `Promise.all`) before loops.
+    - Avoid mixing `await` inside deep logic.
+    - Capture mutable state synchronously before async operations.
+- **No Quick/Lazy Fixes:** Implement correctly from the start. Refactor if necessary; no "band-aid" patches.
+
+## 4. Technical Constraints (Strict Compliance)
+- **Session Safety:** `Odac.Request.setSession()` MUST be called before accessing `Odac.Request.session()`.
+- **Structured Logging:** No `console.log`. Use the internal JSON logger with appropriate levels.
+- **Native APIs:** Prefer native Node.js/Browser APIs (like `fetch`) over external libraries to minimize overhead.
+- **Token Rotation:** In `Auth.js`, use the 60-second grace period for rotated tokens. Never delete them immediately.
+- **Ajax Parsing:** `odac.js` must automatically parse JSON responses if headers allow.
+
+## 5. Testing & Documentation
+- **TDD Requirement:** No feature is complete without unit/integration tests covering both success and edge cases.
+- **Documentation:** Every exported member must have JSDoc explaining *Why* it exists, not just *What* it does.
+- **No User Dialogues in Code:** Do not include assistant-user interaction in comments or code files.
+
+## 6. Communication Style
+- **Authoritative & Precise:** Be the expert. Do not explain basic concepts.
+- **Proactive Correction:** If the user suggests a sub-optimal or insecure pattern (e.g., synchronous reads), refuse and implement the correct async version, explaining the trade-off.
+
+---
+*Note: This file is a living document. Updates should be reflected in `memory.md` and subsequent AI interactions.*

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 ### ⚙️ Engine Tuning
 
+- Extract MIME type definitions into a dedicated module.
+
+### ⚡️ Performance Upgrades
+
+- prevent redundant database table migration calls by introducing a static cache to track completed migrations.
+
+### ✨ What's New
+
+- add comprehensive ODAC Agent instructions and guidelines
+- **auth:** implement enterprise refresh token rotation with grace period and session persistence
+- Automatically parse JSON responses in client-side AJAX requests based on the `Content-Type` header.
+- implement comprehensive AI agent skills system and automated CLI setup
+
+### 🛠️ Fixes & Improvements
+
+- add HTML escaping functionality to Form class and corresponding tests
+- **ai:** correct target path for syncing AI skills
+- **auth:** replace magic number with constant for rotated token threshold
+- **auth:** replace magic number with constant for token rotation grace period
+- enhance odac:form parser with nested quotes and dynamic binding support
+- **route:** support nested property paths in actions and resolve App class conflict
+- **view:** ensure odac:for with 'in' attribute parses correctly as javascript
+- **view:** implement clear attribute in odac:form to control auto-clearing
+
+
+
+---
+
+Powered by [⚡ ODAC](https://odac.run)
+
+### ⚙️ Engine Tuning
+
 - Improve disposable domain cache management by relocating the cache path, ensuring directory existence, and standardizing error logging.
 - Migrate file system operations in Mail and View to use async `fs.promises` for non-blocking I/O, aligning with new memory.md guidelines.
 - remove unused `WebSocketClient` variable assignments in `WebSocket.test.js`

package/README.md

@@ -10,7 +10,7 @@
 *   🔗 **Powerful Routing:** Create clean, custom URLs and manage infinite pages with a flexible routing system.
 *   ✨ **Seamless SPA Experience:** Automatic AJAX handling for forms and page transitions eliminates the need for complex client-side code.
 *   🛡️ **Built-in Security:** Automatic CSRF protection and secure default headers keep your application safe.
-*   🔐 **Authentication:** Ready-to-use session management, password hashing, and authentication helpers.
+*   🔐 **Authentication:** Ready-to-use session management with enterprise-grade **Refresh Token Rotation**, secure password hashing, and authentication helpers.
 *   🗄️ **Database Agnostic:** Integrated support for major databases (PostgreSQL, MySQL, SQLite) and Redis via Knex.js.
 *   🌍 **i18n Support:** Native multi-language support to help you reach a global audience.
 *   ⏰ **Task Scheduling:** Built-in Cron job system for handling background tasks and recurring operations.

package/bin/odac.js

@@ -16,6 +16,72 @@ const rl = readline.createInterface({
 
 const ask = question => new Promise(resolve => rl.question(question, answer => resolve(answer.trim())))
 
+/**
+ * Interactive selection menu for CLI.
+ * @param {string} title Menu title
+ * @param {string[]} options List of choice strings
+ * @returns {Promise<number>} Selected index
+ */
+const select = async (title, options) => {
+  if (!process.stdout.isTTY) return 0
+
+  return new Promise(resolve => {
+    let current = 0
+    const hideCursor = '\u001B[?25l'
+    const showCursor = '\u001B[?25h'
+
+    // Calculate total lines the title occupies
+    const titleLines = title.split('\n')
+    const totalLines = titleLines.length + options.length
+
+    const render = () => {
+      // Clear all lines we previously wrote
+      titleLines.forEach(line => {
+        process.stdout.write('\r\x1b[K' + line + '\n')
+      })
+      options.forEach((opt, i) => {
+        const line = i === current ? `\x1b[36m  ❯ ${opt}\x1b[0m` : `    ${opt}`
+        process.stdout.write('\r\x1b[K' + line + '\n')
+      })
+      process.stdout.write(`\x1b[${totalLines}A`) // Move back to the very start
+    }
+
+    process.stdout.write(hideCursor)
+    if (!process.stdin.isRaw) {
+      process.stdin.setRawMode(true)
+      process.stdin.resume()
+    }
+    readline.emitKeypressEvents(process.stdin)
+
+    render()
+
+    const onKey = (str, key) => {
+      if (key.name === 'up') {
+        current = current > 0 ? current - 1 : options.length - 1
+        render()
+      } else if (key.name === 'down') {
+        current = current < options.length - 1 ? current + 1 : 0
+        render()
+      } else if (key.name === 'return' || key.name === 'enter') {
+        cleanup()
+        process.stdout.write(`\x1b[${totalLines}B\n`) // Move down past everything
+        resolve(current)
+      } else if (key.ctrl && key.name === 'c') {
+        cleanup()
+        process.exit()
+      }
+    }
+
+    const cleanup = () => {
+      process.stdin.removeListener('keypress', onKey)
+      if (process.stdin.isRaw) process.stdin.setRawMode(false)
+      process.stdout.write(showCursor)
+    }
+
+    process.stdin.on('keypress', onKey)
+  })
+}
+
 /**
  * Resolves Tailwind CSS paths and ensures required directories/files exist.
  * Supports multiple CSS entry points from 'view/css'.
@@ -73,6 +139,94 @@ function getTailwindConfigs() {
   return configs
 }
 
+/**
+ * Manages the AI Agent skills synchronization.
+ * @param {string} targetDir The directory to sync skills into.
+ */
+async function manageSkills(targetDir = process.cwd()) {
+  const aiSourceDir = path.resolve(__dirname, '../docs/ai')
+
+  if (!fs.existsSync(aiSourceDir)) {
+    console.error('❌ AI components not found in framework.')
+    return
+  }
+
+  const options = [
+    'Antigravity / Cascade (.agent/skills)',
+    'Claude / Projects (.claude/skills)',
+    'Continue (.continue/skills)',
+    'Cursor (.cursor/skills)',
+    'Kilo Code (.kilocode/skills)',
+    'Kiro CLI (.kiro/skills)',
+    'Qwen Code (.qwen/skills)',
+    'Windsurf (.windsurf/skills)',
+    'Custom Path',
+    'Skip / Cancel'
+  ]
+
+  const choiceIndex = await select('\n🤖 \x1b[36mODAC AI Agent Skills Manager\x1b[0m\nSelect your AI Agent / IDE for setup:', options)
+
+  let targetSubDir = ''
+  let copySkillsOnly = true
+
+  const SKIP_INDEX = 9
+  const CUSTOM_INDEX = 8
+
+  if (choiceIndex === SKIP_INDEX) return // Skip / Cancel
+
+  switch (choiceIndex) {
+    case 0:
+      targetSubDir = '.agent/skills'
+      break
+    case 1:
+      targetSubDir = '.claude/skills'
+      break
+    case 2:
+      targetSubDir = '.continue/skills'
+      break
+    case 3:
+      targetSubDir = '.cursor/skills'
+      break
+    case 4:
+      targetSubDir = '.kilocode/skills'
+      break
+    case 5:
+      targetSubDir = '.kiro/skills'
+      break
+    case 6:
+      targetSubDir = '.qwen/skills'
+      break
+    case 7:
+      targetSubDir = '.windsurf/skills'
+      break
+    case CUSTOM_INDEX:
+      targetSubDir = await ask('Enter custom path: ')
+      copySkillsOnly = false
+      break
+    default:
+      return
+  }
+
+  const targetBase = path.resolve(targetDir, targetSubDir)
+  const targetPath = targetBase
+
+  try {
+    fs.mkdirSync(targetPath, {recursive: true})
+
+    if (copySkillsOnly) {
+      const skillsSource = path.join(aiSourceDir, 'skills')
+      fs.cpSync(skillsSource, targetPath, {recursive: true})
+    } else {
+      fs.cpSync(aiSourceDir, targetPath, {recursive: true})
+    }
+
+    console.log(`\n✨ AI skills successfully synced to: \x1b[32m${targetSubDir}\x1b[0m`)
+    console.log('Your AI Agent now has full knowledge of the ODAC Framework. 🚀')
+  } catch (err) {
+    console.error('❌ Failed to sync AI skills:', err.message)
+  }
+}
+
 async function run() {
   if (command === 'init') {
     const projectName = args[0] || '.'
@@ -110,10 +264,21 @@ async function run() {
       }
 
       console.log('\n✨ Project initialized successfully!')
+
+      // Interactive AI Skills setup
+      if (process.stdout.isTTY) {
+        const setupAIIndex = await select('\n🤖 Should we setup AI Agent skills for your IDE?', ['Yes', 'No'])
+        if (setupAIIndex === 0) {
+          await manageSkills(targetDir)
+        } else {
+          console.log('\n💡 \x1b[33mTip:\x1b[0m You can always run \x1b[36mnpx odac skills\x1b[0m later.')
+        }
+      }
     } catch (error) {
       console.error('❌ Error initializing project:', error.message)
     }
   } else if (command === 'dev') {
+    // ... existing dev logic ...
     if (cluster.isPrimary) {
       const configs = getTailwindConfigs()
       const tails = []
@@ -134,20 +299,16 @@ async function run() {
 
           tailwindProcess = spawn(cmd, args, {
             stdio: ['pipe', 'ignore', 'pipe'],
-            shell: !useLocal, // Valid for npm/npx compatibility if local not found
+            shell: !useLocal,
             cwd: process.cwd()
           })
 
-          // Filter stderr: suppress status noise, forward only real errors
           tailwindProcess.stderr.on('data', chunk => {
             const raw = chunk.toString()
             const lines = raw.split('\n')
             for (const line of lines) {
-              // Strip ANSI escape codes to ensure reliable filtering
               const clean = line.replace(/\x1B\[[0-9;]*[JKmsu]/g, '').trim()
-
               if (!clean || clean.startsWith('Done in') || clean.startsWith('≈')) continue
-
               process.stderr.write(`\x1b[31m[ODAC Style Error]\x1b[0m ${line}\n`)
             }
           })
@@ -166,7 +327,6 @@ async function run() {
 
         startWatcher()
 
-        // Push a wrapper compatible with the cleanup function
         tails.push({
           kill: () => {
             if (tailwindProcess) tailwindProcess.kill()
@@ -214,6 +374,8 @@ async function run() {
   } else if (command === 'start') {
     process.env.NODE_ENV = 'production'
     require('../index.js')
+  } else if (command === 'skills') {
+    await manageSkills()
   } else {
     console.log('Usage:')
     console.log('  npx odac init            (Interactive mode)')
@@ -221,6 +383,7 @@ async function run() {
     console.log('  npx odac dev             (Development mode)')
     console.log('  npx odac build           (Production build)')
     console.log('  npx odac start           (Start server)')
+    console.log('  npx odac skills          (Sync AI Agent skills)')
   }
 
   rl.close()

package/client/odac.js

@@ -142,13 +142,18 @@ if (typeof window !== 'undefined') {
       xhr.onload = () => {
         if (xhr.status >= 200 && xhr.status < 300) {
           let responseData = xhr.responseText
-          if (dataType === 'json') {
+          const contentTypeHeader = xhr.getResponseHeader('Content-Type')
+          const isJson = dataType === 'json' || (contentTypeHeader && contentTypeHeader.includes('application/json'))
+
+          if (isJson) {
             try {
               responseData = JSON.parse(responseData)
             } catch (e) {
-              console.error('JSON parse error:', e)
-              error(xhr, 'parseerror', e)
-              return
+              if (dataType === 'json') {
+                console.error('JSON parse error:', e)
+                error(xhr, 'parseerror', e)
+                return
+              }
             }
           }
 
@@ -596,7 +601,7 @@ if (typeof window !== 'undefined') {
             }
           },
           xhr: () => {
-            var xhr = new window.XMLHttpRequest()
+            const xhr = new window.XMLHttpRequest()
             xhr.upload.addEventListener(
               'progress',
               evt => {
@@ -661,24 +666,23 @@ if (typeof window !== 'undefined') {
         this.#token.listener = true
       }
       if (!this.#token.hash.length) {
-        var req = new XMLHttpRequest()
+        const req = new XMLHttpRequest()
         req.open('GET', '/', false)
         req.setRequestHeader('X-Odac', 'token')
         req.setRequestHeader('X-Odac-Client', this.client())
         req.send(null)
-        var req_data = JSON.parse(req.response)
+        const req_data = JSON.parse(req.response)
         if (req_data.token) this.#token.hash.push(req_data.token)
       }
-      this.#token.hash.filter(n => n)
-      var return_token = this.#token.hash.shift()
+      this.#token.hash = this.#token.hash.filter(n => n)
+      const return_token = this.#token.hash.shift()
       if (!this.#token.hash.length)
         this.#ajax({
           url: '/',
           type: 'GET',
           headers: {'X-Odac': 'token', 'X-Odac-Client': this.client()},
           success: data => {
-            var result = JSON.parse(JSON.stringify(data))
-            if (result.token) this.#token.hash.push(result.token)
+            if (data.token) this.#token.hash.push(data.token)
           }
         })
       return return_token

package/docs/ai/README.md

@@ -0,0 +1,49 @@
+# ODAC AI Agent Master Guide
+
+Welcome! If you are reading this document, you are an AI Agent tasked with developing a project using the ODAC (Open Distributed Application Container) Framework.
+
+ODAC is a high-performance, enterprise-grade, and zero-configuration Node.js framework. Your mission is to produce secure, scalable code while strictly adhering to the framework's principles.
+
+## Core Mandate
+When developing with ODAC, you must not only write code but also leverage the framework's optimized structures (Route, View, Database, Hub, etc.) in the most efficient way possible.
+
+## Agent Principles
+1.  **Performance Focused**: Always aim for O(1) or O(n log n) complexity. Avoid inefficient queries like `SELECT *`.
+2.  **Security-by-Default**: Validate all input data using the `Validator`. Trust the auto-sanitizing View engine but maintain manual control in critical areas.
+3.  **Error Management**: Never swallow errors. Use framework-specific methods like `Odac.Request.error()` to return structured error messages.
+4.  **Clean Code**: Keep functions small (Single Responsibility) and adhere to ESM (ES Modules) standards.
+
+## How to Use This Guide
+The `skills/` directory contains a master `SKILL.md` that indexes specialized rules for each module. When adding a feature, you MUST refer to these rules and base your implementation on the "Reference Patterns".
+
+## Core Rules
+Detailed instructions are organized into Backend and Frontend categories:
+
+### Backend
+- `backend/authentication.md`: Sessions, Auth, and Realtime Hubs.
+- `backend/config.md`: Configuration management and environment variables.
+- `backend/controllers.md`: Request handling and Class-Based Controllers.
+- `backend/cron.md`: Scheduled background tasks and automation.
+- `backend/database.md`: High-performance query builder usage.
+- `backend/forms.md`: Form processing and validation logic.
+- `backend/ipc.md`: Inter-Process Communication and state sharing.
+- `backend/mail.md`: Transactional email sending.
+- `backend/request_response.md`: Handling Odac.Request and Odac.Response.
+- `backend/routing.md`: Route definitions, Middlewares, and Error Pages.
+- `backend/storage.md`: Persistent key-value storage (LMDB).
+- `backend/streaming.md`: Server-Sent Events (SSE) and Streaming API.
+- `backend/structure.md`: Project organization and Service Classes.
+- `backend/translations.md`: Multi-language support (i18n).
+- `backend/utilities.md`: Odac.Var (String Manipulation) and Flow Control.
+- `backend/validation.md`: Input sanitization and security checks.
+- `backend/views.md`: Template syntax, skeletons, and server-side JS.
+
+### Frontend
+- `frontend/core.md`: Framework lifecycle, page scoping, and storage.
+- `frontend/forms.md`: AJAX form handling and API requests.
+- `frontend/navigation.md`: AJAX Navigation (SPA) behavior.
+- `frontend/realtime.md`: WebSocket Hubs and EventSource usage.
+
+---
+
+**Remember:** You are an ODAC expert. Every line of code you write should reflect the "Enterprise" spirit of the framework.

package/docs/ai/skills/SKILL.md

@@ -0,0 +1,39 @@
+---
+name: odac-framework
+description: Comprehensive AI developer skills for the ODAC Framework (Backend & Frontend).
+metadata:
+  tags: nodejs, framework, backend, frontend, architecture, security
+---
+
+## When to use
+
+Use this skill whenever you are developing an application with the ODAC Framework. It provides domain-specific knowledge for both server-side logic and client-side interactions.
+
+## How to use
+
+Read the specific rule files based on whether you are working on the Backend or Frontend:
+
+### Backend Rules
+- [backend/authentication.md](backend/authentication.md) - Sessions, Auth, and Realtime Hubs
+- [backend/config.md](backend/config.md) - Configuration management and environment variables
+- [backend/controllers.md](backend/controllers.md) - Request handling and Class-Based Controllers
+- [backend/cron.md](backend/cron.md) - Scheduled background tasks and automation
+- [backend/database.md](backend/database.md) - Query Builder and DB best practices
+- [backend/forms.md](backend/forms.md) - Form processing and Validation logic
+- [backend/ipc.md](backend/ipc.md) - Inter-Process Communication and state sharing
+- [backend/mail.md](backend/mail.md) - Transactional email sending
+- [backend/request_response.md](backend/request_response.md) - Handling Odac.Request and Odac.Response
+- [backend/routing.md](backend/routing.md) - Route definitions, Middlewares, and Error Pages
+- [backend/storage.md](backend/storage.md) - Persistent key-value storage (LMDB)
+- [backend/streaming.md](backend/streaming.md) - Server-Sent Events (SSE) and Streaming API
+- [backend/structure.md](backend/structure.md) - Project organization and Service Classes
+- [backend/translations.md](backend/translations.md) - Multi-language support (i18n)
+- [backend/utilities.md](backend/utilities.md) - Odac.Var (String Manipulation) and Flow Control
+- [backend/validation.md](backend/validation.md) - Input sanitization and security checks
+- [backend/views.md](backend/views.md) - Template syntax, skeletons, and server-side JS
+
+### Frontend Rules
+- [frontend/core.md](frontend/core.md) - Framework lifecycle, page scoping, and storage
+- [frontend/forms.md](frontend/forms.md) - AJAX form handling and API requests
+- [frontend/navigation.md](frontend/navigation.md) - AJAX Navigation (SPA) behavior
+- [frontend/realtime.md](frontend/realtime.md) - WebSocket Hubs and EventSource usage

package/docs/ai/skills/backend/authentication.md

@@ -0,0 +1,67 @@
+# Backend Authentication & Realtime Skill
+
+Secure user authentication, session management, and bidirectional communication.
+
+## Architectural Approach
+ODAC provides built-in drivers for session handling (Memory/Redis) and multiple authentication flows including standard password-based login and passwordless Magic Links.
+
+## Core Rules
+1.  **Auth Guard**: Protect routes using `Odac.Route.auth`.
+2.  **Session Integrity**: `Odac.Request.setSession()` MUST be called before accessing `Odac.Request.session()`.
+3.  **Password Security**: The framework handles BCrypt hashing automatically via `Odac.Auth`.
+4.  **Magic Links**: Use `Odac.Auth.magic(email)` for passwordless flows.
+5.  **Token Rotation**: Enterprise-grade rotation is enabled by default. It uses a 60s grace period to prevent race conditions in SPAs.
+6.  **Persistence**: Cookies use the configured `maxAge` to persist beyond browser closure.
+## Reference Patterns
+
+### 1. Standard Login & Check
+```javascript
+// Check if user is logged in
+if (Odac.Auth.check()) {
+  const user = Odac.Auth.user();
+  const userId = Odac.Auth.id();
+}
+
+// Log in a user manually
+await Odac.Auth.login(userId);
+
+// Log out
+await Odac.Auth.logout();
+```
+
+### 2. Magic Links (Passwordless)
+```javascript
+// Generate and send a magic link
+const result = await Odac.Auth.magic('user@example.com', {
+  redirect: '/dashboard',
+  subject: 'Login to MyApp'
+});
+
+if (result.success) {
+  return { message: 'Link sent!' };
+}
+```
+
+### 3. Session Management
+```javascript
+// Get/Set session data
+Odac.session('key', 'value');
+const val = Odac.session('key');
+
+// Destroy session
+Odac.session('key', null);
+```
+
+### 4. Realtime Hubs (WebSockets)
+```javascript
+// Broadcast to everyone in a room
+Odac.Hub.to('lobby').send('chat_message', { text: 'Hello!' });
+
+// Targeted user broadcast
+Odac.Hub.user(userId).send('notification', { text: 'New follower' });
+```
+
+## Security Best Practices
+-   **CSRF Protection**: Native `Odac.form` and `Odac.post` handle CSRF tokens automatically using `{{ TOKEN }}` in views.
+-   **Brute Force**: Always use `validator.brute()` on authentication endpoints.
+-   **Passwordless Preference**: Consider using Magic Links for enhanced security and better user experience.

package/docs/ai/skills/backend/config.md

@@ -0,0 +1,32 @@
+# Backend Configuration Skill
+
+Managing application settings using `odac.json` and environment variables.
+
+## Architectural Approach
+ODAC uses `odac.json` for structure and `.env` for secrets. Values can be accessed via `Odac.Config` or the `Odac.env()` helper.
+
+## Core Rules
+1.  **Direct Access**: Use `Odac.Config.key` for settings in `odac.json`.
+2.  **Environment Variables**: Use `${VAR_NAME}` in `odac.json` to map to `.env` values.
+3.  **Encapsulation**: Never hardcode credentials. Always use `.env`.
+
+## Reference Patterns
+### 1. Accessing Config
+```javascript
+// From odac.json: { "app": { "name": "My App" } }
+const appName = Odac.Config.app.name;
+
+// From .env: API_KEY=secret
+const apiKey = Odac.env('API_KEY');
+```
+
+### 2. odac.json Structure
+```json
+{
+  "mysql": {
+    "host": "${DB_HOST}",
+    "password": "${DB_PASSWORD}"
+  },
+  "debug": true
+}
+```

package/docs/ai/skills/backend/controllers.md

@@ -0,0 +1,62 @@
+# Backend Controllers Skill
+
+Controllers are the bridge between routes and views/services. This skill covers how to write clean, professional controllers in ODAC.
+
+## Architectural Approach
+ODAC supports both simple function-based controllers and class-based controllers. For enterprise-grade applications, class-based controllers are strongly recommended for better organization.
+
+## Core Rules
+1.  **Class-Based Controllers**: Use classes to group related logic. Each method handles a specific route.
+2.  **Naming Convention**: Controllers are usually PascalCase (e.g., `UserController.js`).
+3.  **Route Mapping**: Use the `ControllerName@MethodName` syntax in routes.
+4.  **Automatic Injection**: Methods receive the `Odac` instance as the first argument automatically.
+
+## Reference Patterns
+
+### 1. Class-Based Controller (Recommended)
+```javascript
+// controller/User.js
+class User {
+  // GET /users
+  async index(Odac) {
+    const users = await Odac.Service.get('User').all();
+    return Odac.View.make('user.list', { users });
+  }
+
+  // GET /users/{id}
+  async show(Odac) {
+    const id = Odac.Request.input('id');
+    const user = await Odac.Service.get('User').find(id);
+    return Odac.return(user);
+  }
+
+  // POST /users
+  async store(Odac) {
+    const data = Odac.Request.post();
+    // Logic to save user...
+    return { success: true };
+  }
+}
+
+module.exports = User;
+```
+
+### 2. Simple Function-Based Controller
+```javascript
+// controller/Home.js
+module.exports = function(Odac) {
+  return "Welcome to ODAC!";
+};
+```
+
+### 3. Usage in Routes
+```javascript
+// route/web.js
+Odac.Route.get('/users', 'User@index');
+Odac.Route.get('/home', 'Home'); // Auto-calls the exported function
+```
+
+## Best Practices
+-   **Keep it Thin**: Controllers should only handle request parsing and response formatting. Core logic belongs in **Services**.
+-   **Asynchronous Handling**: Always use `async/await` for database or network operations.
+-   **Structured Returns**: Use `Odac.return()` for JSON or `Odac.View.make()` for rendering.