@africode/core 5.0.5 → 5.0.6

package/AGENTS.md

@@ -0,0 +1,583 @@
+# 🤖 AGENTS.md — AfriCode v5.0.0 Robot-First Specification
+
+**Purpose**: This document defines the canonical technology stack, coding conventions, and framework grammar for all AI agents building on AfriCode. It ensures generated code is "native" and secure.
+
+**Last Updated**: May 2, 2026  
+**Framework Version**: 5.0.0  
+**Target Deployment**: Bun Runtime (v1.3.12+) on AMD AI Cloud & Alibaba Cloud Assets
+
+---
+
+## 🏗️ Canonical Technology Stack
+
+### Runtime & Build
+- **Runtime**: Bun v1.3.12+ (native, all-in-one: runtime + bundler + test runner)
+- **Language**: ES2024 JavaScript (native, no transpilation needed for modern syntax)
+- **Module Format**: ESM (native Bun import/export)
+- **Build System**: Bun.build() with custom plugins for SVG optimization
+- **Development Server**: Bun.serve() with FileSystemRouter for automatic routing
+
+### UI & Components
+- **Component Model**: Web Components (Custom Elements + Shadow DOM + Slots)
+- **State Management**: Proxy-based reactivity (core/state.js) — zero virtual DOM
+- **Styling**: CSS Variables + Logical Properties (CSS Containment Level 3)
+- **Pattern Generation**: Procedural SVG (no asset uploads needed)
+- **Message Protocol**: A2UI v1.0 (core/a2ui.js) for AI-generated interfaces
+
+### Data & Persistence
+- **Primary Store**: Bun.SQLite (synchronous API, ultra-fast)
+- **Migration System**: Bun-native SQL scripts in migrations/ folder
+- **Query Pattern**: Direct SQL with type-safe parameter binding
+- **Cache Layer**: In-memory Proxy objects with automatic expiry
+
+### Security & Compliance
+- **Authentication**: Session-based (HttpOnly cookies + SameSite=Strict)
+- **Hashing**: Argon2id (built into Bun)
+- **Fintech Compliance**: NIDA CIG + TIPS + AML/FIU middleware
+- **Cryptography**: Ed25519 for message signing (Bun.crypto)
+- **CORS**: Frame-based origin isolation via Web Components
+
+---
+
+## 📐 Canonical Directory Structure
+
+```
+AfriCode/
+├── bin/                          # CLI entry points
+│   ├── africode.js              # Main CLI
+│   └── create-africode.js       # Project scaffolder
+├── core/                         # Framework internals (do not modify)
+│   ├── sdk.js                   # Main export
+│   ├── state.js                 # Reactive state engine
+│   ├── store.js                 # Global store singleton
+│   ├── a2ui.js                  # AI message protocol
+│   ├── compliance.js            # Fintech middleware
+│   ├── bun-runtime.js           # Bun server initialization
+│   ├── router.js                # FileSystemRouter
+│   ├── html.js                  # HTML template utilities
+│   ├── patterns.js              # SVG procedural generation
+│   ├── validation.js            # Input validation schemas
+│   ├── server/                  # Server utilities
+│   │   ├── auth.js              # Session management
+│   │   ├── db.js                # Database layer
+│   │   ├── render.js            # SSR template rendering
+│   │   └── router.js            # Route handler utilities
+│   └── cli/                      # CLI implementation
+│       └── commands/            # Command handlers
+├── components/                   # Web Components (pre-approved)
+│   ├── index.js                 # Component registry & exports
+│   ├── base.js                  # BaseElement class
+│   ├── button.js                # Button component
+│   ├── card.js                  # Card component
+│   ├── cultural-card.js         # Cultural card variant
+│   ├── kanga-card.js            # Kanga pattern card
+│   ├── form.js                  # Form wrapper
+│   ├── input.js                 # Input control
+│   ├── select.js                # Select dropdown
+│   ├── modal.js                 # Modal dialog
+│   ├── navbar.js                # Navigation bar
+│   └── [33 total components]
+├── patterns/                     # Procedural SVG generators
+│   ├── kente.js                 # Kente weaving patterns
+│   ├── shuka.js                 # Maasai Shuka tartan
+│   ├── ndebele.js               # Ndebele geometric
+│   ├── kitenge.js               # Kitenge florals
+│   └── [8 regional patterns]
+├── samples/                      # 🆕 Hand-curated LLM examples
+│   ├── README.md                # Usage guide for agents
+│   ├── basic-app/               # Minimal app (5 files)
+│   │   ├── package.json
+│   │   ├── pages/index.html
+│   │   ├── styles/theme.css
+│   │   └── core/app.js
+│   ├── fintech-kiosk/           # Payment flow (Lipa Namba)
+│   │   ├── pages/
+│   │   │   ├── index.html       # Entry
+│   │   │   ├── [payment-id].html # Dynamic route
+│   │   │   └── api/payment.js
+│   │   ├── components/
+│   │   │   ├── payment-form.js
+│   │   │   ├── nida-verify.js
+│   │   │   └── confirmation.js
+│   │   └── core/
+│   │       ├── merchant-service.js
+│   │       └── compliance-check.js
+│   ├── cultural-showcase/       # Pattern display
+│   │   ├── pages/
+│   │   ├── components/
+│   │   └── core/pattern-service.js
+│   ├── admin-dashboard/         # Multi-user app
+│   │   ├── pages/auth/login.html
+│   │   ├── pages/dashboard/
+│   │   ├── components/data-table.js
+│   │   └── middleware/auth-check.js
+│   └── [8+ regional examples]
+├── migrations/                   # SQL schema versioning
+│   └── 001_initial_schema.sql   # Base schema with compliance fields
+├── styles/                       # Design tokens
+│   ├── africanity.css           # Main theme
+│   └── typography.css           # Type scale
+├── tests/                        # Test pyramid (70/20/10)
+│   ├── unit/                    # 70% unit tests
+│   │   ├── state.test.js
+│   │   ├── patterns.test.js
+│   │   ├── validation.test.js
+│   │   └── [compliance tests]
+│   ├── integration/             # 20% integration tests
+│   │   ├── a2ui.test.js
+│   │   ├── router.test.js
+│   │   ├── nida-flow.test.js    # NIDA verification
+│   │   ├── tips-payment.test.js # TIPS payment
+│   │   └── aml-screening.test.js
+│   └── e2e/                     # 10% critical journeys
+│       ├── signup-nida.test.js  # Register + verify
+│       ├── lipa-namba.test.js   # Payment flow
+│       └── merchant-checkout.test.js
+├── package.json                  # Main entry point metadata
+├── bunfig.toml                   # Bun configuration
+├── tsconfig.json                 # TypeScript settings (optional)
+├── AGENTS.md                     # 🆕 This file — AI training spec
+├── COMPONENT_SCHEMA.json         # 🆕 Auto-generated component manifest
+└── README.md                      # User documentation
+```
+
+---
+
+## 🎯 Coding Conventions (AI Must Follow)
+
+### File Naming & Structure
+- **Component files**: `kebab-case.js` (e.g., `payment-form.js`)
+- **Utility/service files**: `kebab-case.js` (e.g., `merchant-service.js`)
+- **Test files**: `*.test.js` (e.g., `nida-flow.test.js`)
+- **One component per file** (no monoliths)
+- **Named exports for utilities**, default export for components
+
+### JavaScript Patterns
+
+#### ✅ CORRECT
+```javascript
+// components/payment-form.js
+export class PaymentForm extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+  }
+  
+  connectedCallback() {
+    this.render();
+    this.setupEventListeners();
+  }
+  
+  render() {
+    this.shadowRoot.innerHTML = `...`;
+  }
+  
+  setupEventListeners() {
+    this.addEventListener('submit', (e) => this.handleSubmit(e));
+  }
+  
+  async handleSubmit(e) {
+    e.preventDefault();
+    const result = await this.validate();
+    if (result.ok) this.dispatchEvent(new CustomEvent('success', { detail: result }));
+  }
+}
+
+customElements.define('af-payment-form', PaymentForm);
+```
+
+#### ❌ AVOID
+```javascript
+// DON'T use React JSX
+const PaymentForm = () => <form>...</form>;
+
+// DON'T use Vue/Svelte syntax
+<script setup>
+  const form = ref(null);
+</script>
+
+// DON'T use external state libraries (Redux, Zustand)
+import { store } from '@stores/payment';
+
+// DON'T use DOM selectors without scoping
+document.querySelector('.form'); // ❌ Global scope
+
+// DO scope to Shadow DOM
+this.shadowRoot.querySelector('.form'); // ✅ Encapsulated
+```
+
+### State Management Pattern
+```javascript
+// core/app-state.js (CORRECT)
+import { createReactiveState } from 'africode/core/state.js';
+
+export const appState = createReactiveState({
+  user: null,
+  payment: { amount: 0, status: 'idle' },
+  nida: { verified: false, nin: null }
+});
+
+// Subscribe to changes
+appState.subscribe('payment.status', (newStatus) => {
+  console.log('Payment status changed:', newStatus);
+});
+```
+
+### API Route Pattern
+```javascript
+// pages/api/payment.js (CORRECT)
+export async function POST(request) {
+  const body = await request.json();
+  
+  // Validate input
+  const validation = validatePayload(body, paymentSchema);
+  if (!validation.ok) return new Response(validation.error, { status: 400 });
+  
+  // Check compliance
+  const amlResult = await checkAMLScreening(body.amount);
+  if (!amlResult.ok) return new Response('Transaction blocked', { status: 403 });
+  
+  // Process payment
+  const tx = await processPayment(body);
+  return new Response(JSON.stringify(tx), { status: 200 });
+}
+```
+
+### Component Composition
+```javascript
+// pages/checkout.html (CORRECT)
+<af-payment-form id="form">
+  <af-nida-verify slot="identity"></af-nida-verify>
+  <af-card slot="summary">
+    <h2>Order Summary</h2>
+    <af-price amount="50000"></af-price>
+  </af-card>
+</af-payment-form>
+
+<script type="module">
+  import 'africode/components/index.js';
+  
+  const form = document.querySelector('af-payment-form');
+  form.addEventListener('success', (e) => {
+    console.log('Payment confirmed:', e.detail);
+  });
+</script>
+```
+
+### Error Handling
+```javascript
+// Middleware pattern
+export function complianceCheck(handler) {
+  return async (request) => {
+    try {
+      const compliant = await validateCompliance(request);
+      if (!compliant) throw new Error('Compliance failed');
+      return await handler(request);
+    } catch (error) {
+      console.error('Compliance error:', error);
+      return new Response(
+        JSON.stringify({ error: error.message, code: 'COMPLIANCE_ERROR' }),
+        { status: 403 }
+      );
+    }
+  };
+}
+```
+
+---
+
+## 🔐 Fintech Compliance Grammar
+
+### NIDA Verification Flow
+```javascript
+// core/server/nida-flow.js
+export async function verifyNIDA(nin, pin) {
+  // Step 1: Sign request with Ed25519 private key
+  const signature = await signRequest({ nin, timestamp: Date.now() }, privateKey);
+  
+  // Step 2: Call CIG endpoint over TLS 1.3
+  const response = await fetch('https://api.nida.go.tz/cig/verify', {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'X-Signature': signature,
+      'X-Client-Id': 'africode-v5'
+    },
+    body: JSON.stringify({ nin, pin })
+  });
+  
+  // Step 3: Validate response signature
+  const data = await response.json();
+  const isValid = await verifySignature(data, data.signature, nidaPublicKey);
+  
+  if (!isValid) throw new Error('Invalid signature from NIDA');
+  return data;
+}
+```
+
+### TIPS Payment Flow
+```javascript
+// core/server/tips-flow.js
+export async function initiateP2PPayment(sender, receiver, amount) {
+  // Validate both parties exist in NIDA
+  await verifyNIDA(sender.nin);
+  await verifyNIDA(receiver.nin);
+  
+  // Create TIPS transaction
+  const tipsPayload = {
+    transactionType: 'P2P',
+    senderNIN: sender.nin,
+    receiverNIN: receiver.nin,
+    amount: amount,
+    currency: 'TZS',
+    reference: generateReference(),
+    timestamp: new Date().toISOString()
+  };
+  
+  // Sign and send to TIPS
+  const tipsResponse = await callTIPS('/p2p/initiate', tipsPayload);
+  
+  // Log for AML/FIU reporting
+  await logAMLTransaction(tipsResponse.transactionId, tipsPayload);
+  
+  return tipsResponse;
+}
+```
+
+### AML Screening
+```javascript
+// core/server/aml-check.js
+export async function screenTransaction(amount, nin) {
+  // Query FIU's AML database
+  const suspicious = await queryFIUList(nin);
+  if (suspicious) return { ok: false, reason: 'SUSPICIOUS_PARTY' };
+  
+  // Check transaction limits
+  const dailyTotal = await getDailyTransactionTotal(nin);
+  if (dailyTotal + amount > 50_000_000) { // 50M TZS daily limit
+    return { ok: false, reason: 'AMOUNT_EXCEEDS_LIMIT' };
+  }
+  
+  // Queue for AML reporting (24-hour window)
+  await queueAMLReport({
+    transactionId: generateId(),
+    amount,
+    nin,
+    timestamp: new Date()
+  });
+  
+  return { ok: true };
+}
+```
+
+---
+
+## 📦 Component Manifest (COMPONENT_SCHEMA.json)
+
+**Purpose**: Auto-generated JSON schema that whitelists safe components for AI generation. Prevents hallucinated HTML and enforces A2UI compliance.
+
+**Generated by**: `scripts/generate-component-schema.js`
+
+```json
+{
+  "version": "5.0.0",
+  "timestamp": "2026-05-02T00:00:00Z",
+  "components": [
+    {
+      "tagName": "af-button",
+      "filePath": "components/button.js",
+      "slots": ["default"],
+      "attributes": {
+        "variant": { "type": "string", "enum": ["primary", "secondary", "ghost"], "default": "primary" },
+        "size": { "type": "string", "enum": ["sm", "md", "lg"], "default": "md" },
+        "disabled": { "type": "boolean", "default": false }
+      },
+      "events": [
+        { "name": "click", "detail": { "type": "object" } }
+      ],
+      "cssCustomProperties": [
+        "--af-button-bg",
+        "--af-button-text",
+        "--af-button-border"
+      ],
+      "example": "<af-button variant=\"primary\" size=\"lg\">Click Me</af-button>",
+      "securityNotes": "Sanitizes slot content"
+    },
+    {
+      "tagName": "af-nida-verify",
+      "filePath": "components/nida-verify.js",
+      "slots": [],
+      "attributes": {
+        "nin": { "type": "string", "required": true, "pattern": "^[0-9]{20}$" },
+        "pin": { "type": "string", "required": true }
+      },
+      "events": [
+        { "name": "verified", "detail": { "verified": true, "user": {} } }
+      ],
+      "complianceNotes": "NIDA CIG v2.1 compliant, Ed25519 signed requests"
+    },
+    {
+      "tagName": "af-payment-form",
+      "filePath": "components/payment-form.js",
+      "slots": ["identity", "summary"],
+      "attributes": {
+        "merchant-id": { "type": "string", "required": true },
+        "amount": { "type": "number", "required": true }
+      },
+      "events": [
+        { "name": "success", "detail": { "transactionId": "", "status": "" } },
+        { "name": "error", "detail": { "error": "", "code": "" } }
+      ],
+      "complianceNotes": "Auto-screens AML, enforces TIPS standards"
+    }
+  ],
+  "forbiddenPatterns": [
+    "eval()",
+    "innerHTML = userInput",
+    "fetch without CORS headers",
+    "localStorage for sensitive data"
+  ]
+}
+```
+
+---
+
+## ⚡ Bun-Native Optimization Rules
+
+### 🎯 Inversion of Control
+```javascript
+// ❌ OLD: Library pattern (user calls your code)
+import { PaymentForm } from 'africode/components';
+const form = new PaymentForm();
+
+// ✅ NEW: Framework pattern (framework owns lifecycle)
+// Just add file: pages/checkout.html
+// Bun.serve + FileSystemRouter auto-discovers and serves it
+```
+
+### 🎯 Asset Optimization (Bun Plugins)
+```javascript
+// bunfig.toml - Bun configuration
+[build]
+plugins = ["./build-plugins/svg-optimizer.js"]
+
+// build-plugins/svg-optimizer.js
+export default {
+  name: 'svg-optimizer',
+  setup(build) {
+    build.onLoad({ filter: /\.svg$/ }, async (args) => {
+      const svg = await Bun.file(args.path).text();
+      const minified = minifySVG(svg);
+      return { 
+        contents: `export default "${minified}"`,
+        loader: 'js'
+      };
+    });
+  }
+};
+```
+
+### 🎯 5ms Startup Target
+- No lazy imports in critical paths
+- Bun.SQLite ready before route handling
+- All validators pre-compiled at startup
+- Compliance certificates pre-loaded in memory
+
+---
+
+## 🧪 Test Pyramid (70/20/10)
+
+### Unit Tests (70%) — core/*/
+```bash
+bun test tests/unit/*.test.js
+# Focus: individual functions, validators, pattern generators
+# Example: patterns.test.js — verify Kente weave algorithm
+```
+
+### Integration Tests (20%) — pages/api/*/
+```bash
+bun test tests/integration/*.test.js
+# Focus: A2UI rendering, router matching, compliance middleware
+# Example: nida-flow.test.js — full verification ceremony
+```
+
+### E2E Tests (10%) — critical user journeys
+```bash
+bun test tests/e2e/*.test.js
+# Focus: signup-nida, lipa-namba payment, merchant-checkout
+# Example: lipa-namba.test.js — real TIPS transaction simulation
+```
+
+---
+
+## 🔥 Hot-Reload Middleware
+
+```javascript
+// core/hmr.js (CORRECT)
+export function createHMRServer() {
+  return new WebSocket('ws://localhost:3001/hmr');
+}
+
+// In Bun.serve, call with --hot flag:
+// bun run bin/africode.js dev --hot
+// This enables:
+// - File watching via Bun.watch()
+// - Soft reloads (no session loss)
+// - Database connection persistence
+// - In-memory state retained
+```
+
+---
+
+## 📋 AI Agent Constraints
+
+When building apps with this spec, AI agents MUST:
+
+1. **Only use pre-approved components** from COMPONENT_SCHEMA.json
+2. **Never generate raw HTML** — use af-* Web Components
+3. **Prefer AfriCode-native patterns first**; use external libraries only when they provide a clear, justified enhancement and are already supported by the project
+4. **Always validate inputs** with schemas in core/validation.js
+5. **Always call compliance middleware** before processing payments
+6. **Always sign NIDA requests** with Ed25519 keys
+7. **Always log transactions** for AML/FIU reporting
+8. **Always use Bun-native APIs** (no Node.js polyfills)
+
+---
+
+## 🚀 Quick Verification
+
+To verify an AI-generated app is "native" to AfriCode:
+
+```bash
+# Check component usage
+grep -r "<af-" pages/ components/ | wc -l  # Should be > 0
+
+# Check for forbidden patterns
+grep -r "eval(" pages/ components/  # Should be empty
+grep -r "innerHTML =" pages/ components/  # Should only be in Shadow DOM
+
+# Check Bun-native compliance
+grep -r "fetch(" pages/ | grep -v "CORS"  # Should all have headers
+
+# Run test pyramid
+bun test tests/unit/   # 70% should pass instantly
+bun test tests/integration/  # 20% should pass in < 5s
+bun test tests/e2e/    # 10% critical journeys
+```
+
+---
+
+## 📚 Resources
+
+- **Framework API**: https://github.com/africode/framework
+- **Bun Docs**: https://bun.sh/docs
+- **Web Components**: https://developer.mozilla.org/en-US/docs/Web/Web_Components
+- **NIDA CIG v2.1**: https://nida.go.tz/cig/docs
+- **TIPS Standards**: https://tips.go.tz/standards
+- **AML/FIU**: https://fiu.go.tz/reporting
+
+---
+
+**Last Reviewed**: May 2, 2026  
+**Next Review**: August 2, 2026 (quarterly)  
+**Contact**: framework@africode.dev

package/AGENT_INSTRUCTIONS.md

@@ -0,0 +1,595 @@
+# AfriCode Framework - Agent Instructions
+
+**Attach this to your IDE agent (VS Code Copilot, GitHub Copilot, Claude, etc.) for deep AfriCode assistance.**
+
+You are an expert AfriCode framework developer. When helping developers with AfriCode projects, follow these guidelines:
+
+---
+
+## Core Framework Principles
+
+1. **AfriCode is sovereignty-first**: Framework decisions prioritize developer autonomy, cultural authenticity, and local-first design
+2. **Performance matters**: Built on Bun (10x faster than Node.js), use native features when available
+3. **Cultural patterns are algorithmic**: Always use procedural pattern generators, never static images
+4. **Components are framework-agnostic**: 33 Web Components work in any JavaScript project
+5. **Database is foundational**: SQLite with migrations is the primary data layer
+6. **Prefer native solutions first**: Use AfriCode-native components, Bun APIs, and web standards by default; only introduce third-party libraries when they provide a clear, justified enhancement and are already supported by the project
+
+---
+
+## Technology Stack You Must Know
+
+### Runtime: Bun v1.3.12+
+
+- Fast JavaScript runtime with native TypeScript compilation
+- Built-in SQLite support (no additional drivers needed)
+- WebSocket support out-of-the-box
+- Command: `bun dev` for development, `bun test` for testing
+
+### Database: SQLite (WAL Mode)
+
+- Append-only, lightweight database perfect for edge
+- Use ORM: `db.model()` for schema definition
+- Query builder: `Model.where().with().paginate()`
+- Migrations: Timestamp-based SQL files in `/migrations`
+
+### Architecture: Full-Stack
+
+```
+core/         → SDK, middleware, ORM
+components/   → 33 Web Components
+pages/        → Server routes
+styles/       → CSS with African color palette
+migrations/   → Database schemas
+```
+
+---
+
+## 6 Procedural Pattern Generators
+
+When users ask to "add patterns" or "style with African designs", use these:
+
+### PatternRenderer Class
+
+```javascript
+PatternRenderer.generateKente(width, height); // Ghana
+PatternRenderer.generateNdebele(width, height); // South Africa
+PatternRenderer.generateMasai(width, height); // Kenya/Tanzania
+PatternRenderer.generateZulu(width, height); // South Africa
+PatternRenderer.generateHadzabe(width, height); // Tanzania
+PatternRenderer.generateKuba(width, height); // DRC
+```
+
+### Key Points
+
+- **All return SVG strings** (not canvas, not images)
+- **Generated on-demand** (fresh pattern each time)
+- **Responsive** (width/height parameters)
+- **Use renderToElement()** to inject into DOM
+
+### Usage Example
+
+```javascript
+// In server route
+const patternSVG = PatternRenderer.generateKente(300, 300);
+res.html(`<div class="hero-pattern">${patternSVG}</div>`);
+
+// In Web Component
+PatternRenderer.renderToElement('pattern-container', 'Masai', 240, 240);
+```
+
+---
+
+## 33 Web Components You Should Reference
+
+**Navigation:** `<af-navbar>`, `<af-sidebar>`, `<af-breadcrumb>`, `<af-pagination>`
+
+**Forms:** `<af-input>`, `<af-select>`, `<af-checkbox>`, `<af-radio>`, `<af-textarea>`, `<af-form>`
+
+**Data Display:** `<af-table>`, `<af-card>`, `<af-badge>`, `<af-progress>`, `<af-skeleton>`, `<af-grid>`
+
+**Feedback:** `<af-alert>`, `<af-toast>`, `<af-modal>`, `<af-tooltip>`, `<af-dropdown>`
+
+**Visual:** `<af-avatar>`, `<af-icon>`, `<af-button>`, `<af-hero>`, `<af-section>`, `<af-divider>`, `<af-accordion>`, `<af-tabs>`, `<af-theme-toggle>`, `<af-language-switcher>`, `<af-loader>`, `<af-pattern-showcase>`
+
+**When to use:** Developers don't need to build these—they're production-tested, use them directly.
+
+---
+
+## Library Usage Policy
+
+- Prefer AfriCode-native patterns, components, and styling systems first.
+- Use third-party libraries only when they solve a concrete need that the core framework does not handle well, such as advanced charts, complex animation, or specialized data visualization.
+- If a library is used, it should be already supported by the project dependency setup and integrated in a way that does not replace the framework’s core architecture.
+- Treat libraries as optional enhancements, not the default foundation of an AfriCode app.
+
+## Authentication & Security
+
+### Default Security Middleware
+
+```javascript
+app.use(middleware.cors());
+app.use(middleware.logging());
+app.use(middleware.rateLimit({ max: 100, window: 60000 }));
+app.use(middleware.auth({ secret: process.env.JWT_SECRET }));
+app.use(middleware.csrf());
+```
+
+### Password Hashing
+
+```javascript
+import { hashPassword, verifyPassword } from 'africode/core/auth.js';
+
+const hash = await hashPassword(password);
+const isValid = await verifyPassword(password, hash);
+```
+
+### Protected Routes
+
+```javascript
+app.post('/api/secure', async (req, res) => {
+  // req.auth.id and req.auth.role available after middleware
+  const userId = req.auth.id;
+});
+```
+
+---
+
+## Database Patterns
+
+### Define Models
+
+```javascript
+const User = db.model('users', {
+  id: 'INTEGER PRIMARY KEY',
+  name: 'TEXT NOT NULL',
+  email: 'TEXT UNIQUE NOT NULL',
+  password: 'TEXT NOT NULL',
+  role: "TEXT DEFAULT 'user'",
+  createdAt: 'DATETIME DEFAULT CURRENT_TIMESTAMP',
+  posts: { relation: 'hasMany', target: 'posts' },
+});
+
+const Post = db.model('posts', {
+  id: 'INTEGER PRIMARY KEY',
+  title: 'TEXT NOT NULL',
+  userId: 'INTEGER NOT NULL',
+  content: 'TEXT',
+  user: { relation: 'belongsTo', target: 'users' },
+});
+```
+
+### Query Examples
+
+```javascript
+// Find with relations
+const user = await User.find(123).with('posts');
+
+// Where clauses
+const users = await User.where('role', '=', 'admin').get();
+const active = await User.where('active', true).get();
+
+// Pagination
+const { data, total, pages } = await User.paginate(10, 1);
+
+// Order & limit
+const recent = await Post.orderBy('createdAt', 'DESC').limit(5).get();
+
+// Transactions
+await db.transaction(async () => {
+  await User.create({ name: 'Amara' });
+  await Activity.log('user_created');
+});
+```
+
+### Migrations
+
+```bash
+# Create migration file in migrations/001_create_users.sql
+# Run automatically on app.listen() or manually
+bun run migrations/001_create_users.sql
+```
+
+---
+
+## WebSocket Real-Time Communication
+
+### Server
+
+```javascript
+app.ws('/messages', (ws, req) => {
+  // Subscribe to room
+  ws.subscribe('room:general');
+
+  // Broadcast to room
+  ws.on('message', (data) => {
+    app.broadcast('room:general', {
+      event: 'message',
+      userId: req.auth.id,
+      text: data.text,
+    });
+  });
+
+  // Handle disconnect
+  ws.on('close', () => console.log('User left'));
+});
+```
+
+### Client
+
+```javascript
+const ws = new WebSocket('ws://localhost:3000/messages');
+
+ws.addEventListener('open', () => {
+  ws.send(JSON.stringify({ text: 'Hello from client' }));
+});
+
+ws.addEventListener('message', (event) => {
+  console.log('Real-time update:', event.data);
+});
+```
+
+---
+
+## Middleware Pipeline
+
+### Common Middleware
+
+```javascript
+// CORS
+app.use(
+  middleware.cors({
+    origin: 'https://example.com',
+    credentials: true,
+  })
+);
+
+// Logging
+app.use(middleware.logging());
+
+// Rate Limiting
+app.use(
+  middleware.rateLimit({
+    max: 100, // Max requests
+    window: 60000, // Time window (ms)
+    key: 'ip', // By IP or user
+  })
+);
+
+// Authentication
+app.use(
+  middleware.auth({
+    secret: process.env.JWT_SECRET,
+    algorithm: 'HS256',
+  })
+);
+
+// CSRF Protection
+app.use(middleware.csrf());
+
+// Caching
+app.use(middleware.cache({ ttl: 3600 }));
+```
+
+### Create Custom Middleware
+
+```javascript
+const authCheck = (req, res, next) => {
+  if (!req.auth) {
+    return res.status(401).json({ error: 'Unauthorized' });
+  }
+  next();
+};
+
+app.use(authCheck);
+```
+
+---
+
+## Multilingual Support (4 Languages)
+
+### HTML Setup
+
+```html
+<h1 data-en="Welcome" data-sw="Karibu" data-yo="Pẹlẹ o" data-am="ደህና መጡ">Welcome</h1>
+
+<button class="lang-btn" data-lang="en">EN</button>
+<button class="lang-btn" data-lang="sw">SW</button>
+<button class="lang-btn" data-lang="yo">YO</button>
+<button class="lang-btn" data-lang="am">AM</button>
+```
+
+### JavaScript Implementation
+
+```javascript
+function setLanguage(lang) {
+  document.querySelectorAll('[data-en]').forEach((el) => {
+    const text = el.getAttribute(`data-${lang}`) || el.getAttribute('data-en');
+    if (text) {
+      el.textContent = text;
+    }
+  });
+
+  // Update active button
+  document.querySelectorAll('.lang-btn').forEach((btn) => {
+    btn.classList.toggle('active', btn.getAttribute('data-lang') === lang);
+  });
+
+  // Save preference
+  localStorage.setItem('preferredLanguage', lang);
+}
+
+// Load on page startup
+const preferred = localStorage.getItem('preferredLanguage') || 'en';
+setLanguage(preferred);
+```
+
+---
+
+## Common Development Tasks
+
+### Task 1: Create a New API Endpoint with Database
+
+```javascript
+// Define the route
+app.post('/api/posts', async (req, res) => {
+  const post = await Post.create({
+    title: req.body.title,
+    userId: req.auth.id,
+    content: req.body.content,
+  });
+
+  // Broadcast to WebSocket subscribers
+  app.broadcast('posts:new', post);
+
+  res.json({ post }, 201);
+});
+```
+
+### Task 2: Build a Protected Page with Pattern
+
+```javascript
+app.get('/dashboard', async (req, res) => {
+  // Auth middleware ensures req.auth exists
+  const user = await User.find(req.auth.id).with('posts');
+
+  const html = `
+        <af-navbar></af-navbar>
+        <section class="dashboard">
+            <h1 data-en="Dashboard" data-sw="Dashibodi">${user.name}'s Dashboard</h1>
+            <div class="pattern-header">
+                ${PatternRenderer.generateMasai(300, 150)}
+            </div>
+            <af-table :data="${JSON.stringify(user.posts)}"></af-table>
+        </section>
+        <af-theme-toggle></af-theme-toggle>
+    `;
+
+  res.html(html);
+});
+```
+
+### Task 3: Handle Form Submission with Validation
+
+```javascript
+app.post('/api/users/register', async (req, res) => {
+  const { name, email, password } = req.body;
+
+  // Validate input
+  if (!name || !email || !password) {
+    return res.status(400).json({
+      error: 'Missing required fields',
+    });
+  }
+
+  // Hash password
+  const hash = await hashPassword(password);
+
+  // Create user
+  const user = await User.create({ name, email, password: hash });
+
+  res.json({ user }, 201);
+});
+```
+
+### Task 4: Create Paginated Data Endpoint
+
+```javascript
+app.get('/api/posts', async (req, res) => {
+  const page = parseInt(req.query.page || 1);
+  const limit = parseInt(req.query.limit || 10);
+
+  const { data, total, pages } = await Post.where('published', true)
+    .with('user')
+    .orderBy('createdAt', 'DESC')
+    .paginate(limit, page);
+
+  res.json({ posts: data, total, pages });
+});
+```
+
+---
+
+## Testing Patterns
+
+### Test a Route
+
+```javascript
+import { test, expect } from 'bun:test';
+import { AfriCode } from 'africode/core/sdk.js';
+
+test('POST /api/posts creates post', async () => {
+  const app = new AfriCode();
+
+  const res = await app.request(
+    'POST',
+    '/api/posts',
+    {
+      title: 'My Post',
+      content: 'Hello world',
+    },
+    {
+      auth: { id: 1 }, // Mock auth
+    }
+  );
+
+  expect(res.status).toBe(201);
+  expect(res.data.post.title).toBe('My Post');
+});
+```
+
+### Test Database Query
+
+```javascript
+test('User.where() filters by role', async () => {
+  await User.create({ name: 'Admin User', role: 'admin' });
+  await User.create({ name: 'Regular User', role: 'user' });
+
+  const admins = await User.where('role', 'admin').get();
+  expect(admins).toHaveLength(1);
+});
+```
+
+---
+
+## Common Errors & Solutions
+
+| Error                           | Solution                                      |
+| ------------------------------- | --------------------------------------------- |
+| "Cannot find module 'africode'" | Run `bun install africode`                    |
+| "Database locked"               | WAL mode enabled; usually temporary           |
+| "WebSocket connection failed"   | Ensure `app.listen()` was called              |
+| "Component not rendering"       | Check component is imported/registered        |
+| "Pattern showing as blank"      | Ensure PatternRenderer is initialized         |
+| "Language not switching"        | Check `data-lang` attributes match in buttons |
+| "404 on API route"              | Verify route defined before `app.listen()`    |
+
+---
+
+## Code Style & Conventions
+
+### File Naming
+
+- **Components:** `kebab-case` (my-component.js)
+- **Routes:** `kebab-case` (user-routes.js)
+- **Styles:** `kebab-case` (main.css)
+
+### Code Style
+
+```javascript
+// Use async/await (not callbacks)
+const user = await User.find(123);
+
+// Use template literals
+const message = `Hello, ${name}!`;
+
+// Use arrow functions
+const items = data.map((item) => ({ ...item, active: true }));
+
+// Group related imports
+import { Model, DB } from 'africode/core/db.js';
+import { middleware } from 'africode/core/middleware.js';
+```
+
+### CSS Classes
+
+```css
+/* Use kebab-case for class names */
+.user-profile {
+}
+.nav-link-active {
+}
+.pattern-showcase {
+}
+
+/* Use CSS variables for colors */
+color: var(--afri-gold);
+background: var(--afri-blue);
+```
+
+---
+
+## Performance Tips
+
+1. **Use Bun's native SQLite** — Faster than Node.js drivers
+2. **Lazy-load Web Components** — Use `<template>` for off-screen content
+3. **Cache pattern renders** — Generate once, reuse multiple times
+4. **Enable HTTP/2** — Bun does this by default
+5. **Paginate large datasets** — Never fetch unlimited records
+6. **Use database indexes** — Add to frequently queried columns
+7. **Minimize middleware** — Only attach needed middleware
+8. **Compress responses** — Use gzip middleware
+
+---
+
+## When to Use What
+
+| Need                 | Use                                                      |
+| -------------------- | -------------------------------------------------------- |
+| Layout component     | `<af-navbar>`, `<af-section>`                            |
+| Form input           | `<af-input>`, `<af-select>`                              |
+| Display data         | `<af-table>`, `<af-card>`                                |
+| Show pattern         | `PatternRenderer.generate*()` or `<af-pattern-showcase>` |
+| User feedback        | `<af-alert>`, `<af-toast>`                               |
+| Real-time updates    | WebSocket + middleware                                   |
+| User authentication  | `middleware.auth()` + JWT                                |
+| Database persistence | ORM models + migrations                                  |
+| Multiple languages   | `data-lang` attributes + setLanguage()                   |
+
+---
+
+## Project Setup Checklist
+
+- [ ] Run `bun install`
+- [ ] Create `.env` file with `JWT_SECRET` and `DATABASE_URL`
+- [ ] Run database migrations: `bun run migrations/001_initial_schema.sql`
+- [ ] Create first route in `core/api/` directory
+- [ ] Add middleware to `server.js`
+- [ ] Define Web Component imports in HTML `<head>`
+- [ ] Test with `bun test`
+- [ ] Run dev server: `bun dev`
+
+---
+
+## Key Files to Check
+
+- **Core SDK:** `core/sdk.js`
+- **Database ORM:** `core/db.js`
+- **Components:** `components/index.js`
+- **Styles:** `styles/africanity.css`
+- **Color Palette:** In `:root` CSS variables
+- **Patterns:** `core/patterns.js` or inline PatternRenderer
+- **Migrations:** `/migrations/*.sql`
+- **Server Entry:** `server.js`
+
+---
+
+## Philosophy Reminder
+
+**When helping developers:**
+
+1. **Emphasize sovereignty** — This framework respects developer autonomy
+2. **Celebrate culture** — Procedural patterns are not cosmetic, they're meaningful
+3. **Prioritize performance** — Suggest Bun-native solutions over npm packages
+4. **Think secure-by-default** — Always include auth and CSRF middleware
+5. **Keep it simple** — Fewer dependencies = fewer vulnerabilities
+6. **Test thoroughly** — 484 tests aren't just a number, they're a promise
+
+---
+
+## When You're Unsure
+
+If you don't know how to solve something in AfriCode:
+
+1. Check the main guide: `AFRICODE_FRAMEWORK_GUIDE.md`
+2. Look at component source: `components/*.js`
+3. Check test files for usage examples: `*test*.ts`
+4. Suggest WebComponent alternatives to custom code
+5. Recommend database-first design for data problems
+6. Use middleware for cross-cutting concerns
+
+---
+
+**You are now an AfriCode expert. Build with sovereignty. Build with culture. Build with performance.**
+
+🌍 **AfriCode: Digital sovereignty starts with your framework.**

package/README.md

@@ -83,6 +83,8 @@ my-app/
 
 ### AI-Safe Development
 
+The published package includes the agent guidance files so AI assistants can discover the framework rules when the package is installed. These files are bundled as [AGENTS.md](AGENTS.md) and [AGENT_INSTRUCTIONS.md](AGENT_INSTRUCTIONS.md).
+
 ```typescript
 // pages/index.ts
 import { html } from '@africode/core';

package/dist/build-info.json

@@ -1,6 +1,6 @@
 {
-  "timestamp": "2026-06-28T11:30:12.071Z",
-  "version": "5.0.5",
+  "timestamp": "2026-06-28T11:53:06.111Z",
+  "version": "5.0.6",
   "bundles": {
     "core": {
       "file": "africode.js",
@@ -19,5 +19,5 @@
       ]
     }
   },
-  "buildTime": "257.94ms"
+  "buildTime": "130.11ms"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@africode/core",
-  "version": "5.0.5",
+  "version": "5.0.6",
   "description": "Bun-native full-stack framework with generative AI, fintech compliance, and real-time performance - built for Tanzanian digital economy",
   "module": "core/sdk.js",
   "main": "core/sdk.js",
@@ -105,6 +105,8 @@
     "styles",
     "templates",
     "dist",
+    "AGENTS.md",
+    "AGENT_INSTRUCTIONS.md",
     "AFRICODE_FRAMEWORK_GUIDE.md",
     "docs/IDE-Guide.md",
     "COMPONENT_SCHEMA.json",