From f34d5f35d4590d4a9a2263236d51ee16f8ded821 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Thu, 7 May 2026 05:30:10 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20Improve=20documentati?=
 =?UTF-8?q?on=20UX=20and=20accessibility?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-authored-by: igor-holt <125706350+igor-holt@users.noreply.github.com>
---
 README.md | 38 ++++++++++++++++++++++++++++++++------
 1 file changed, 32 insertions(+), 6 deletions(-)

diff --git a/README.md b/README.md
index 80d6c39..06a738a 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,9 @@
 # ⚖️ arbiter
 
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-![Status: Experimental](https://img.shields.io/badge/Status-Experimental-orange)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg "License: MIT - Open source software license")](https://opensource.org/licenses/MIT)
+
+> [!CAUTION]
+> This project is currently **Experimental**. It is not recommended for production use and is subject to significant changes as the architecture evolves.
 
 Dual nature—combining bare-metal virtualized hardware management (aSHARD VRAM pinning) with quantum-accelerated Kubernetes scheduling.
 
@@ -9,12 +11,36 @@ Dual nature—combining bare-metal virtualized hardware management (aSHARD VRAM
 
 `arbiter` is a specialized orchestration layer designed for high-performance computing environments. It bridges the gap between low-level hardware management and cloud-native scheduling, providing a unified interface for managing virtualized resources with precision.
 
+## 🏗️ Architecture
+
+```mermaid
+graph TD
+    subgraph CloudNative [Cloud Native Layer]
+        K8s[Kubernetes Cluster]
+    end
+
+    subgraph Orchestration [Orchestration Layer]
+        Arbiter((Arbiter Core))
+    end
+
+    subgraph Infrastructure [Infrastructure Layer]
+        BareMetal[Bare Metal Servers]
+        GPU[GPU Resources / VRAM]
+    end
+
+    K8s <--> Arbiter
+    Arbiter <--> BareMetal
+    Arbiter <--> GPU
+
+    style Arbiter fill:#f96,stroke:#333,stroke-width:4px
+```
+
 ## 🚀 Key Features
 
-- 🏗️ **Infrastructure Awareness**: Directly manages bare-metal resources for maximum performance.
-- 📍 **VRAM Optimization**: Uses aSHARD pinning to eliminate GPU memory fragmentation.
-- ⚛️ **Next-Gen Scheduling**: Leverages quantum-accelerated algorithms for complex Kubernetes workloads.
-- ⚖️ **Unified Orchestration**: A single control plane for both hardware and cluster-level operations.
+- 🏗️ **Bare-Metal Precision**: Bypass virtualization overhead with direct hardware management for latency-sensitive AI workloads.
+- 📍 **Intelligent VRAM Pinning**: Maximize GPU utilization and eliminate fragmentation using aSHARD-driven memory allocation.
+- ⚛️ **Quantum-Accelerated Scheduling**: Resolve complex multi-constraint resource allocations faster than traditional heuristics.
+- ⚖️ **Unified Control Plane**: Seamlessly bridge the gap between low-level hardware states and high-level Kubernetes orchestration.
 
 ## ⚖️ License