From ddaa9b632933890f5a5ee36a44067c7ea76c2e26 Mon Sep 17 00:00:00 2001
From: ZachDreamZ <xxtheshadowcraft@gmail.com>
Date: Thu, 25 Jun 2026 12:08:34 +0800
Subject: [PATCH] docs: document the x-boxthis response header

The README mentioned x-boxthis briefly in the API section but didn't
explain what the header values mean or how to use them.

Added a dedicated section with:
- Header values table (fit vs over;by=<bytes>)
- HTTP response examples
- Use cases for CI gating, proxy rules, and monitoring

Closes #3
---
 README.md | 31 +++++++++++++++++++++++++++++++
 1 file changed, 31 insertions(+)

diff --git a/README.md b/README.md
index 66a471d..6a2ee2d 100644
--- a/README.md
+++ b/README.md
@@ -154,6 +154,37 @@ or test to assert the critical path stays under budget and at the network floor.
 The five-bucket classifier (mirrors `lightsout`). Feed it a real measured PRR
 (`networkFloorMs ÷ FCP`) to label any page, not just a boxthis shell.
 
+## The `x-boxthis` Response Header
+
+Every response sent by `ship()` includes an `x-boxthis` header so that proxies, CDNs, and CI pipelines can read the budget verdict without parsing the response body.
+
+### Header Values
+
+| Header | Meaning |
+|---|---|
+| `x-boxthis: fit` | The critical shell fits within the budget (default 14 KB gzipped). |
+| `x-boxthis: over;by=<bytes>` | The critical shell exceeds the budget by `<bytes>` bytes. |
+
+### Examples
+
+**Fits the budget:**
+```
+HTTP/1.1 200 OK
+x-boxthis: fit
+```
+
+**Over budget by 2048 bytes:**
+```
+HTTP/1.1 200 OK
+x-boxthis: over;by=2048
+```
+
+### Use Cases
+
+- **CI gating:** Check the header in integration tests to assert that a page stays under budget.
+- **Proxy/CDN rules:** Route or cache responses based on whether the shell fits.
+- **Monitoring:** Log the header value to track budget compliance over time.
+
 ## Honest limitations (know these before you defend it online)
 
 - **Compression middleware can defeat streaming.** A gzip layer that buffers the