From c4848cf467c773d61f90a3ed7e89f2cacda00bf2 Mon Sep 17 00:00:00 2001
From: Andre <200930841+Andre-Bzk@users.noreply.github.com>
Date: Sat, 18 Jul 2026 16:18:20 +0200
Subject: [PATCH] docs: document the three progress bars and their color
 thresholds

The color logic lives in two files (context bar in cship.toml, the usage
bars in the wrapper), so the behavior was not discoverable from either one
alone. A single reference table records the thresholds and where to edit
each, so future changes keep the two color sources in sync.
---
 README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/README.md b/README.md
index 1d29adb..690f6b2 100644
--- a/README.md
+++ b/README.md
@@ -29,6 +29,28 @@ with a single command.
   installer nevertheless installs a Nerd Font (Hack, ~17 MB) **per-user, no
   admin rights** if none is present — see below.
 
+### Progress bars & color thresholds
+
+The statusline has three progress bars. Each fills from 0–100 % and switches
+color at fixed thresholds:
+
+| Bar          | Measures                    | 🔵 blue  | 🟡 yellow | 🔴 bold red |
+| ------------ | --------------------------- | -------- | --------- | ----------- |
+| 🧠 Context   | context window filled       | `< 20 %` | `≥ 20 %`  | `≥ 40 %`    |
+| ⏳ 5h        | 5-hour usage limit used     | `< 40 %` | `≥ 40 %`  | `≥ 70 %`    |
+| 📅 7d        | 7-day usage limit used      | `< 40 %` | `≥ 40 %`  | `≥ 70 %`    |
+
+Thresholds are **percentages**, so they stay model-independent. On a 1M-token
+context window the 🧠 bar therefore turns yellow at **200k** tokens and red at
+**400k**. Colors: blue `#7dcfff`, yellow, bold red.
+
+Where to change them:
+
+- **🧠 Context** — `warn_threshold` / `critical_threshold` in
+  `[cship.context_bar]` (`assets/cship.toml`).
+- **⏳ 5h / 📅 7d** — the color block in `assets/cship-statusline.ps1`; both
+  bars share it, so keep the two thresholds in sync.
+
 ### Install on a new PC
 
 ```powershell
@@ -100,6 +122,28 @@ einem einzigen Befehl auf jeden Windows-PC installiert.
   installiert der Installer dennoch einen Nerd-Font (Hack, ~17 MB) **per-user,
   ohne Admin-Rechte**, falls keiner vorhanden ist — siehe unten.
 
+### Progress-Bars & Farbschwellen
+
+Die Statusline hat drei Progress-Bars. Jeder füllt sich von 0–100 % und wechselt
+an festen Schwellen die Farbe:
+
+| Bar          | Misst                          | 🔵 blau  | 🟡 gelb  | 🔴 fett rot |
+| ------------ | ------------------------------ | -------- | -------- | ----------- |
+| 🧠 Kontext   | Kontextfenster gefüllt         | `< 20 %` | `≥ 20 %` | `≥ 40 %`    |
+| ⏳ 5h        | 5-Stunden-Limit ausgelastet    | `< 40 %` | `≥ 40 %` | `≥ 70 %`    |
+| 📅 7d        | 7-Tage-Limit ausgelastet       | `< 40 %` | `≥ 40 %` | `≥ 70 %`    |
+
+Die Schwellen sind **Prozentwerte** und damit model-unabhängig. Bei einem
+Kontextfenster von 1M Tokens wird der 🧠-Bar deshalb bei **200k** Tokens gelb
+und bei **400k** rot. Farben: blau `#7dcfff`, gelb, fett rot.
+
+Wo man sie ändert:
+
+- **🧠 Kontext** — `warn_threshold` / `critical_threshold` in
+  `[cship.context_bar]` (`assets/cship.toml`).
+- **⏳ 5h / 📅 7d** — der Farbblock in `assets/cship-statusline.ps1`; beide Bars
+  teilen ihn sich, also beide Schwellen synchron halten.
+
 ### Installation auf einem neuen PC
 
 ```powershell