docs: fix markdown formatting by replacing brittle KaTeX with clean ASCII diagrams

README.md

@@ -58,26 +58,68 @@ model-index:
 
 ## Overview
 
-Spark-Servitor is a high-throughput, headless neural decision engine for code security and patch verification. It serves as a deeper, larger variant in the Servitor family, complementing [`wxsys/qwen-servitor`](https://huggingface.co/wxsys/qwen-servitor).
+Spark-Servitor is a headless neural decision engine for code security, patch verification, and automated pull request review. It serves as a larger, deeper variant in the Servitor family, complementing [`wxsys/qwen-servitor`](https://huggingface.co/wxsys/qwen-servitor).
 
-While Qwen-Servitor is engineered around Qwen3.5-0.8B linear attention (Gated DeltaNet) for sub-15ms pre-commit screening, Spark-Servitor scales up to **Spark-X2.5-1.7B** with Sliding Window Attention (SWA 512), 7 Full Attention anchor layers, and Headwise Sigmoid Output Gating (`g_proj`). This provides broader receptive capacity for multi-file patches and cross-file symbol tracking across monorepos up to 1,048,576 tokens.
+While Qwen-Servitor is engineered around Qwen3.5-0.8B linear attention (Gated DeltaNet) for sub-15ms local pre-commit screening, Spark-Servitor scales up to **Spark-X2.5-1.7B** with Sliding Window Attention (SWA 512), 7 Full Attention anchor layers, and Headwise Sigmoid Output Gating (`g_proj`). This provides broader receptive capacity for multi-file patches and cross-file symbol tracking across monorepos up to 1,048,576 tokens.
 
-The generative projection head (`lm_head`, 311M parameters) has been removed. Rather than generating conversational text, the model processes code diffs in a single forward pass to produce structured verdicts, risk metrics, and OASIS SARIF v2.1.0 code flows.
+The generative projection head (`lm_head`, 311M parameters) has been removed. Rather than generating conversational text, the model processes code diffs in a single forward pass to produce structured verdicts, risk metrics, and OASIS SARIF v2.1.0 exploit flows.
+
+---
+
+## Technical Architecture
+
+```text
+                      [ RAW DIFF / 1M TOKEN CONTEXT ]
+                                     │
+                                     ▼
+      ┌─────────────────────────────────────────────────────────────┐
+      │               SPARK-X2.5 NEURAL SPINE                       │
+      │   • 21x Sliding Window Attention Layers (Window = 512)      │
+      │   • 7x Gated Full Attention Layers (Cross-File Context)     │
+      │   • Headwise Sigmoid Output Gating (g_proj)                 │
+      │   • Zero-Allocation Circular Ring Buffer (Peak RAM <= 16MB) │
+      │   • 311M-parameter Generative Head: EXCISED / REMOVED       │
+      └─────────────────────────────────────────────────────────────┘
+                                     │
+                        [ Final Hidden State (h_T) ]
+                                     │
+                                     ▼
+      ┌─────────────────────────────────────────────────────────────┐
+      │         DIFF-CAMQP DUAL-SOFTMAX CORTEX HEAD                 │
+      │   • Differential query filtering (A1 - lambda * A2)         │
+      │   • Latent Recurrent Pondering (Adaptive halting k = 1..4)  │
+      └─────────────────────────────────────────────────────────────┘
+                                     │
+            ┌────────────────────────┼────────────────────────┐
+            ▼                        ▼                        ▼
+    ┌───────────────┐        ┌───────────────┐        ┌───────────────┐
+    │ VERDICT HEAD  │        │   RISK HEAD   │        │ PATHOLOGY HEAD│
+    │ 3-Way Output  │        │  Sigmoid(1)   │        │ 10-Class Multi│
+    │ • APPROVE     │        │  Continuous   │        │ • SECURITY    │
+    │ • QUARANTINE  │        │  Risk Score   │        │ • DEADLOCK    │
+    │ • REJECT      │        │  (0.00-1.00)  │        │ • PERF_COLLAP │
+    └───────┬───────┘        └───────────────┘        └───────────────┘
+            │
+            ▼ (If QUARANTINE: Formal Neuro-Symbolic SMT Hand-Off)
+    ┌───────────────┐
+    │ Z3 SMT Solver │ ──> [ Final Verified Gate ]
+    └──────────��────┘
+```
 
 ---
 
 ## Specifications
 
-| Metric | Specification |
+| Parameter | Specification |
 |---|---|
 | **Base Architecture** | Decapitated `XHToken/Spark-X2.5-1.7B` |
-| **Hidden Size ($d_{\text{model}}$)** | 2048 |
+| **Hidden Dimension (d_model)** | 2048 |
 | **Attention Layers** | 28 total (21 Sliding Window Attention, window 512 + 7 Full Attention) |
 | **Attention Heads** | 16 Query Heads, 2 Key/Value Heads (Grouped-Query Attention) |
 | **Output Gating** | Headwise Sigmoid Projection (`g_proj`) |
 | **Context Window** | Up to 1,048,576 tokens via circular SWA buffer |
 | **Decision Mechanism** | Dual-Softmax Differential Cortex Head (`DiffCAMQPCortexHead`) |
-| **Format & Quantization** | Outlier-Preserved AWQ INT4 / W8A8 (~1.6 GB binary on disk) |
+| **Format & Quantization** | Outlier-Preserved AWQ INT4 / W8A8 (1.6 GB binary on disk) |
 | **Resident Memory** | 4.08 MB VmRSS (C++ daemon via UNIX domain socket) |
 | **Inference Latency** | 0.044 ms per diff (CPU Intel AVX2 SIMD) |
 
@@ -85,14 +127,14 @@ The generative projection head (`lm_head`, 311M parameters) has been removed. Ra
 
 ## Core Capabilities
 
-### 1. Single-Pass 3-Way Verdict
+### 1. Single-Pass 3-Way Verdict Gate
 Diffs route directly into three deterministic states:
-- **`APPROVE`**: Patch contains verified modifications with no detected pathology ($r^* \le 0.20$).
+- **`APPROVE`**: Patch contains verified modifications with no detected pathology (risk <= 0.20).
 - **`QUARANTINE`**: Borderline invariant changes, formal boundary shifts, or ambiguous concurrency locks routed to SMT verification.
-- **`REJECT`**: Confirmed vulnerability or regression ($r^* \ge 0.80$).
+- **`REJECT`**: Confirmed vulnerability or regression (risk >= 0.80).
 
-### 2. Calibrated Continuous Risk Metric ($r^*$)
-Outputs a normalized risk score $r^* \in [0.0, 1.0]$. The metric is trained using Brier score Mean Squared Error alignment against soft targets, avoiding raw binary cliffs.
+### 2. Calibrated Continuous Risk Metric
+Outputs a normalized risk score from 0.000 to 1.000. The metric is trained using Brier score Mean Squared Error alignment against soft targets, avoiding raw binary score cliffs.
 
 ### 3. Multilabel Pathology Attribution
 Detects 10 specific code defect categories simultaneously:
@@ -109,7 +151,11 @@ Detects 10 specific code defect categories simultaneously:
 
 ### 4. OASIS SARIF v2.1.0 Exploit Flow Reconstruction
 For any detected vulnerability, Spark-Servitor reconstructs the complete data-flow path:
-$$\text{Source (Untrusted Input)} \longrightarrow \text{Propagation (Variable Flow)} \longrightarrow \text{Sanitizer Status} \longrightarrow \text{Sink (Vulnerable Call)}$$
+
+```text
+[1. SOURCE: Untrusted Input] ──> [2. PROPAGATION: Variable Flow] ──> [3. SANITIZER: Status] ──> [4. SINK: Vulnerable Call]
+```
+
 Emits standard SARIF `codeFlows` and `threadFlows` compatible with GitHub Advanced Security and VS Code SARIF Viewer.
 
 ### 5. Parameter-Aware Anti-False-Alarm