chore: Implement Dual-Track differentiation (Class 1 Simplicity vs Class 2 Scale)

Author: hyperpolymath

0-AI-MANIFEST.a2ml

@@ -9,6 +9,24 @@ This is the AI manifest for **Bundle of Joy Server**. It declares:
 - Critical invariants (rules that must NEVER be violated)
 - Repository structure and organization
 
+## 🏰 DUAL-TRACK ARCHITECTURE (CLASS 1 vs CLASS 2)
+
+This repository implements a Dual-Track design to balance simplicity and scale.
+
+### **Class 1: Simple Track (Canonical)**
+- **Focus:** Zero-infrastructure simplicity.
+- **Workflow:** Repositories trigger builds via GitHub Actions (CLI/curl).
+- **Cartridge Pattern:** Each cartridge has its own self-contained V-lang adapters.
+- **Path:** Standard `cartridges/<name>/adapter/`.
+
+### **Class 2: Orchestrator Track (Advanced)**
+- **Focus:** High-performance unified gateways.
+- **Workflow:** Secure Webhooks (HMAC-SHA256) and Real-time (MQTT/WS).
+- **Cartridge Pattern:** Uses core generic handlers to wrap cartridge FFI.
+- **Path:** `adapter/v/src/class_2_orchestrator/`.
+
+**INVARIANT:** Class 2 features must NEVER damage or replace the Class 1 foundation.
+
 ## CANONICAL LOCATIONS (UNIVERSAL RULE)
 
 ### Machine-Readable Metadata: `.machine_readable/` ONLY
@@ -98,7 +116,8 @@ boj-server/
 │   └── src/loader.zig         # Dynamic cartridge loader
 ├── generated/abi/             # Auto-generated C headers from Idris2
 ├── adapter/v/                 # V-lang triple adapter (REST+gRPC+GraphQL)
-│   └── src/main.v             # Unified console on port 9000
+│   ├── src/main.v             # Unified console on port 9000
+│   └── src/class_2_orchestrator/ # Advanced gateway logic (WS/MQTT/Webhook)
 ├── cartridges/                # One dir per matrix cell (Idris2+Zig+V)
 │   ├── database-mcp/          # MCP × Database cartridge
 │   ├── nesy-mcp/              # MCP × NeSy cartridge

README.md

@@ -12,6 +12,24 @@ A genuine 'bundle of joy'.
   <img src="https://www.bestpractices.dev/projects/12164/badge" alt="OpenSSF Best Practices passing (115%)" />
 </a>
 
+## 🏰 Dual-Track Architecture
+
+BoJ Server provides two distinct ways to interact with cartridges, catering to different needs for simplicity and scale.
+
+### **Class 1: Simple Track (Canonical)**
+- **Focus:** Simplicity, local-first, zero-infrastructure.
+- **Workflow:** Repositories use standard GitHub Actions (`curl` triggers) to talk to the server.
+- **Implementation:** Each cartridge is self-contained with its own adapters.
+- **Best for:** Most users, quick setups, and easy debugging.
+
+### **Class 2: Orchestrator Track (Advanced)**
+- **Focus:** Unified transport, high-performance, massive scale.
+- **Workflow:** Uses secure Webhooks (HMAC-SHA256) and unified real-time gateways (MQTT/WebSockets).
+- **Implementation:** Core-level generic handlers located in `adapter/v/src/class_2_orchestrator/`.
+- **Best for:** Production environments, IoT integration, and multi-agent orchestration.
+
+---
+
 ## Quick Start
 
 **1. Clone and build**
@@ -97,13 +115,3 @@ See [docs/READINESS.md](docs/READINESS.md) for the full component-by-component a
 ## Architecture (For Contributors)
 
 BoJ uses Idris2 for interface proofs (zero `believe_me`), Zig for the C-compatible FFI layer, V-lang for the REST/gRPC/GraphQL adapter, and JavaScript for the MCP bridge. If that sounds like a lot of languages, it is -- each was chosen for a specific guarantee. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for the rationale and contributor guide.
-
-Cartridges are loaded as shared libraries (`.so` files) at runtime, verified by hash before mounting. Community-contributed cartridges go through the same verification pipeline.
-
-## License
-
-SPDX-License-Identifier: PMPL-1.0-or-later (Palimpsest License)
-
-Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath)
-
-See [LICENSE](LICENSE) for the full text.