From 3960aeef88a3a33e9e8634eee465a848a5b80f82 Mon Sep 17 00:00:00 2001
From: Patrick Buckley <eous@users.noreply.github.com>
Date: Sun, 2 Aug 2026 13:13:54 -0700
Subject: [PATCH] docs(readme): lead the what-is-a-harness section with the
 diagram

- docs/diagrams/harness.png: cartoon rendering of the HYPOTHESIS.md tuple
  (256-color quantized, 803KB)
- README: image served via absolute raw URL so the PyPI page renders it;
  caption formula corrected to tau_H (the doc's notation) and the ill-typed
  rho(M_W(pi), E) composition shorthand dropped; formalism linked beside
  the primer
---
 README.md                 | 10 ++++++++--
 docs/diagrams/harness.png |  3 +++
 2 files changed, 11 insertions(+), 2 deletions(-)
 create mode 100644 docs/diagrams/harness.png

diff --git a/README.md b/README.md
index b810edb0..ba606dfe 100644
--- a/README.md
+++ b/README.md
@@ -17,11 +17,17 @@ Named after the [Ruddy Turnstone](https://en.wikipedia.org/wiki/Ruddy_turnstone)
 
 **What is a harness?**
 
+<p align="center">
+  <a href="https://raw.githubusercontent.com/turnstonelabs/turnstone/main/docs/diagrams/harness.png">
+    <img src="https://raw.githubusercontent.com/turnstonelabs/turnstone/main/docs/diagrams/harness.png" alt="ℋ : s_{n+1} ~ T(s_n) for n < τ_H — the whole controlled loop: π lowers state to context, M_W proposes a readout, γ authorizes it, Q_E acts on the world, ρ verifies and folds back" width="960"/>
+  </a>
+</p>
+
 ```
-ℋ :  s_{n+1} ~ T(s_n)   for n < τ*,    T = ρ ∘ (M_W ∘ π, E)
+ℋ :  s_{n+1} ~ T(s_n)   for n < τ_H
 ```
 
-[**the primer →**](PRIMER.md)
+[**the primer →**](PRIMER.md) · [**the formalism →**](HYPOTHESIS.md)
 
 ### Release Tracks
 
diff --git a/docs/diagrams/harness.png b/docs/diagrams/harness.png
new file mode 100644
index 00000000..5093806b
--- /dev/null
+++ b/docs/diagrams/harness.png
@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:6e2bfdf968e96f3720ed58674103288e2f57e9c056f5c479a57f37a849f3e69c
+size 821878