docs: document which prompts trigger headroom compression

[devin-ai-integration]

Summary

Documents which prompts actually trigger Headroom compression, prompted by confusion in #docs-feedback where a tester saw zero savings from a 21-token prompt.

Adds a terse "What triggers compression" section to the Headroom doc: compression only fires on large machine-generated payloads carried as tool messages (JSON API responses, DB dumps, large file reads / RAG chunks), engages around a thousand-plus tokens, and never touches user/system (unless HEADROOM_COMPRESS_USER_MESSAGES=1) or cache_control-marked messages.

Adds a runnable static/scripts/headroom_compression_check.sh (linked from the doc, served at /scripts/headroom_compression_check.sh). It calls /v1/compress directly (the same call the guardrail makes, no LLM key needed) with a tiny prompt and a large tool result and prints tokens_before/after/saved + transforms_applied:

HEADROOM_URL=http://localhost:8787 bash headroom_compression_check.sh
=== tiny prompt (expect 0 saved) ===
{"tokens_before":18,"tokens_after":18,"tokens_saved":0,"transforms_applied":["router:noop"]}
=== large JSON tool result (expect compression) ===
{"tokens_before":10837,"tokens_after":9534,"tokens_saved":1303,"transforms_applied":["router:smart_crusher:0.37"]}

Validated against a local Headroom 0.28.0 (matching the demo's version) and earlier against headroom-compress.onrender.com directly (x-headroom-tokens-saved of 1189 on a tabular result and 3881 on a JSON result). The script deliberately uses the JSON payload as its "compresses" case because that path is deterministic; the tabular router fires conditionally, so the doc no longer asserts a specific transform or ratio.

Docusaurus npm run build passes; the script asset is emitted to build/scripts/ and the only broken-anchor warnings are pre-existing release-notes pages.

Link to Devin session: https://app.devin.ai/sessions/fe103b990cdf49848eea092cadaf61f3
Requested by: @krrish-berri-2

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment, CI, and merge conflict monitoring

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
litellm	Ready	Preview, Comment	Jul 14, 2026 9:33pm