From a75c41a483f38204b007ffde17dd86a9f817d953 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Wed, 13 May 2026 05:16:37 +0000
Subject: [PATCH] =?UTF-8?q?=F0=9F=8E=A8=20Palette:=20Enhance=20README=20ac?=
 =?UTF-8?q?cessibility=20and=20visual=20documentation?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Improve badge alt-text and add title attributes for better accessibility.
- Add GitHub Alert block ([!CAUTION]) to clearly communicate experimental status.
- Add Mermaid architecture diagram to visualize project structure.

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

diff --git a/README.md b/README.md
index 80d6c39..a9b2e3c 100644
--- a/README.md
+++ b/README.md
@@ -1,7 +1,10 @@
 # ⚖️ 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 - Open source software license](https://img.shields.io/badge/License-MIT-yellow.svg "License: MIT")](https://opensource.org/licenses/MIT)
+![Status: Experimental - Not recommended for production use](https://img.shields.io/badge/Status-Experimental-orange "Status: Experimental")
+
+> [!CAUTION]
+> This project is currently **experimental** and is not recommended for production use. It involves quantum-accelerated scheduling and low-level hardware management which may be unstable.
 
 Dual nature—combining bare-metal virtualized hardware management (aSHARD VRAM pinning) with quantum-accelerated Kubernetes scheduling.
 
@@ -16,6 +19,34 @@ Dual nature—combining bare-metal virtualized hardware management (aSHARD VRAM
 - ⚛️ **Next-Gen Scheduling**: Leverages quantum-accelerated algorithms for complex Kubernetes workloads.
 - ⚖️ **Unified Orchestration**: A single control plane for both hardware and cluster-level operations.
 
+## 🏗️ Architecture
+
+```mermaid
+graph TD
+    subgraph "Cloud Native"
+        K8s[Kubernetes Cluster]
+        Workloads[AI Workloads]
+    end
+
+    subgraph "Orchestration"
+        Arbiter((Arbiter Core))
+        Scheduler[Quantum-Accelerated Scheduler]
+    end
+
+    subgraph "Infrastructure"
+        BareMetal[Bare-Metal Nodes]
+        VRAM[aSHARD VRAM Pinning]
+    end
+
+    Workloads --> K8s
+    K8s <--> Arbiter
+    Arbiter <--> Scheduler
+    Arbiter <--> BareMetal
+    BareMetal --- VRAM
+
+    style Arbiter fill:#f96,stroke-width:4px
+```
+
 ## ⚖️ License
 
 This project is licensed under the [MIT License](LICENSE).