docs(ai): execute AI visibility protocol to expose architectural rationale

- Promoted IMMORTAL_RATIONALE.md to top-level docs/ directory.
- Updated root README to guide agentic crawlers (e.g. Grok) to the core C++ latency covenants and SKILLS registry.
- Explicitly unignored .agent/ and docs/ paths in .gitignore to ensure they are proactively pushed to the remote repository for external indexing.

Author: quantDIY

.gitignore

@@ -117,6 +117,11 @@ client/desktop/tauri-app/src-tauri/src/*.bak.*
 # project_status.md
 # docs/technical_whitepaper.md
 
+# Explictly guarantee AI Agent visibility for indexing
+!docs/
+!.agent/
+!.agent/skills/
+
 # Data
 *.dbn
 *.zst

README.md

@@ -74,6 +74,18 @@ QuanuX is the **first** quantitative trading platform to offer an official **Con
 
 ---
 
+## 🤖 AI Agent & Architectural Rationale
+
+QuanuX is built to be understood and extended by both humans and AI agents.
+To ensure our foundational architectural rules (such as the 59ns C++ latency path and the 64-byte L1 cache covenant) are preserved, we maintain a set of explicit instructions and skills:
+
+*   **[Immortal Rationale](docs/IMMORTAL_RATIONALE.md)**: The core C++ engine architecture, historical latency decisions, and memory layouts.
+*   **[Agent Skills Directory](.agent/skills/)**: High-fidelity AI operating procedures and capabilities logically separated by component domain (`SKILL.md`).
+*   **Man Pages**: Operator runbooks logically defined in `server/docs/man`.
+
+Agentic systems evaluating this repository must prioritize reading `docs/IMMORTAL_RATIONALE.md` before embarking on modifications to execution nodes, execution loops, or distributed architectures.
+
+---
 ## 🔌 Universal Connectivity & Integrations
 
 The "Bolt-On" architecture means we integrate with **everything**.

docs/IMMORTAL_RATIONALE.md

@@ -0,0 +1,37 @@
+# The Immortal Rationale: Forging the 59ns QuanuX-Spreader
+
+*"To go fast, you must despise the OS. To go instantly, you must despise the compiler."* — QuanuX Engineering
+
+This document records the architectural crusade that dragged the `QuanuX-Spreader` from a respectable 250 microsecond latency profile down to its physical barrier: a 59 nanosecond "Happy Path." 
+
+Future AI Agents generating or modifying the `QuanuX-Spreader` Engine or its strategies are bound by this covenant. If an agent questions the rigid C-types or the lack of dynamic structures, they must reference this history.
+
+## Epoch 1: The 250µs Trap (JSON & The Network)
+Early iterations of the spreader behaved like a naive microservice. 
+*   **The Trap:** It subscribed to a NATS topic, parsed a JSON payload carrying market ticks, mapped it to a `std::unordered_map` for LOCF (Last Observation Carried Forward) tracking, and evaluated math. 
+*   **The Cost:** JSON parsing costs minimums of 50-100µs. A `std::unordered_map` hash calculation and branch evaluation costs 50-200ns per lookup. This created massive "Jitter," destroying standard deviation guarantees.
+*   **The Pivot:** We abandoned JSON-over-NATS completely for this engine. We shifted to raw `MARKET.BIN` binary payloads. The Spreader now executes a bare-metal `reinterpret_cast<const MarketTick*>` directly against the NATS socket ingress buffer, achieving zero-copy wire-to-math.
+
+## Epoch 2: The DuckDB Sideshow
+We needed archival logs of triggered spread conditions for Phase 5 (The Analytics Dashboard).
+*   **The Trap:** Traditional DB inserts (`INSERT INTO ticks...`) or even asynchronous HTTP logging introduced kernel context switches. A system call blocks the CPU core, obliterating the 59ns threshold.
+*   **The Pivot:** DuckDB was selected explicitly for its C++ Appender API and in-process nature. In the producer thread, appending is treated as a deferrable "Sideshow." It happens only after the SPSCQueue has been populated, and it's vectorized to maximize L3 cache line flushing rather than network I/O.
+
+## Epoch 3: The LOCF PriceMatrix (Array > Map)
+To track Spread Legs (Leg A, Leg B), the strategy logic must maintain memory of the most recent price.
+*   **The Trap:** `std::map<string, double>` uses string hashing, allocator pointers, and red-black tree traversal. Every lookup was a cache miss.
+*   **The Pivot:** The "Flat Lookup Table." We developed `PriceMatrix`: a `alignas(64)` cache-line protected `std::array<PriceEntry, 8192>`. We identify instruments with an integer `instrument_id`. Lookups dropped from O(log n) tree traversal down to **O(1) 1-cycle pointer arithmetic**.
+
+## Epoch 4: The Dictator Compiler & The Cython Forge
+The final frontier was the research-to-production gap. Data analysts write Python; hardware executes C++.
+*   **The Trap:** Attempting to run a Python runtime (via Cython `Py_Initialize()` or `pybind11`) inside the 59ns loop created the GIL (Global Interpreter Lock) threshold and unpredictable garbage collections.
+*   **The Pivot:** The "Cython Forge." We inverted the relationship. Instead of C++ executing Python, we used Cython strictly as a transcompiler (`quanuxctl spreader package`). It parses Pythonic intent (via JSON IR schemas) into hyper-strict `extern "C++"` constructs (like `strategy_injected.hpp`).
+    *   This enabled the **64-Byte Guard**: By enforcing C-types (`double`, `uint32_t`), CMake can successfully assert that `sizeof(StrategyState) <= 64`. This structurally prevents an L1 cache spillover during the Thread 1 to Thread 2 DMA handshake.
+    *   The identical `_wrapper.pyx` allowed the Python backtester (Crucible) to invoke the native C++ math, ensuring 100% mathematical parity.
+
+## Epoch 5: Zero-Overhead Telemetry
+Observability is a poison pill for latency. Standard `std::cout` or spdlog blocks IO.
+*   **The Trap:** Logging tick arrivals or latency metrics destroyed the pipeline. 
+*   **The Pivot:** We hijacked the existing `update_seq` "Dirty Bit" in the `PriceMatrix`. We replaced 4 bytes of explicit padding with a `uint32_t arrival_tsc` timestamp. Now, telemetry is purely passive. We `mmap` the `PriceMatrix` array into POSIX shared memory. External `quanux-spreader` man pages instruct humans to read the SHM segment to track engine health without the Executive Loop ever executing a single `write()` system call.
+
+**End of Rationale.**