diff --git a/README.md b/README.md
index d08a0a1..412df46 100644
--- a/README.md
+++ b/README.md
@@ -64,6 +64,14 @@ Attesto stores source-system time separately from backend ingest time.
 `time.Now().UTC()` when omitted, but production integrations should pass the
 real upstream event timestamp whenever the source system provides one.
 
+## Committed payload number rule
+
+When events are committed to a Proofstream, payload and metadata numbers must
+serialize identically across Python, Go, and JavaScript. Non-integer numbers
+and integers beyond ±(2^53−1) are rejected at ingestion (HTTP 422); encode
+decimals and large integers as strings (e.g. `{"score": "0.87"}`). This keeps
+cross-language commitment recomputation byte-exact (`CanonicalJSON`).
+
 ## Verification
 
 Remote verification uses Attesto's public `/v2/verify` API. Offline receipt