## Description
Bring the published docs (headroom-docs.vercel.app) back in line with
the current codebase. The docs described an older architecture,
advertised user/community statistics the code no longer supports (the
telemetry beacon was removed), shipped code samples that raise on
import, and lacked an in-depth treatment of proxy-mode configuration.
Docs-only change — no `headroom/` source touched.
## Type of Change
- [x] Documentation update
## Changes Made
- **Remove user/community stats.** The anonymous telemetry beacon was
removed from the code and `HEADROOM_TELEMETRY` is now local-only, but
the docs still advertised aggregate "instances worldwide" figures —
which were hardcoded/fabricated. Deleted `community-savings.mdx` (+ nav
entry), the community/live stat widgets and their components
(`community-charts`, `community-stats-header`, `live-stats`, `stats`,
`lib/telemetry`, and a second fabricated `LiveStats` in
`marketing.tsx`), and the `## Production Telemetry` section in
`benchmarks.mdx`. Reframed all telemetry wording as local-only.
- **Correct the architecture docs.** Rewrote `architecture.mdx` to the
real pipeline (interceptor → CacheAligner *off-by-default* →
ContentRouter; Rust `_core`; CCR on by default). Dropped the removed
3-stage / Context Manager / RollingWindow model. Fixed
`how-compression-works.mdx` (3-stage framing, dead LLMLingua reference,
wrong compressor class names) and added an off-by-default note to
`cache-optimization.mdx`.
- **Fix broken code samples** (verified against source):
`TextCompressor`→`TextCrusher` + real `SearchCompressorConfig` fields
(`text-and-logs`), `MemoryCategory`→plain string (`memory`),
`unload_tree_sitter` import path (`code-compression`).
- **In-depth proxy configuration.** Added a "Configuration in depth"
section to `proxy.mdx` (Kompress, CCR/lossless, file-read handling,
reliability, tool-search/MCP, cost-aware routing, observability,
security/networking, performance). Fixed the `HEADROOM_MODE` default
(`token`→`cache`) in three pages and removed a duplicate
`HEADROOM_TELEMETRY` row.
- **Nav + links.** Un-orphaned `crewai`/`autogen` in the sidebar;
normalized `chopratejas`→`headroomlabs-ai` repo/GHCR links (kept the
real HF model id `chopratejas/technique-router`);
`litellm-vertex`→`vertex_ai`.
## Testing
- [ ] Unit tests pass (`pytest`) — N/A, no `headroom/` code changed
- [ ] Linting passes (`ruff check .`) — N/A, no Python changed
- [ ] Type checking passes (`mypy headroom`) — N/A, no Python changed
- [x] Manual testing performed (static docs validation; output below)
### Test Output
```text
-- dangling refs to deleted components/pages (expect empty) --
(none)
-- meta.json valid --
pages: 60 | community-savings present: false | crewai: true | autogen: true
-- Callout balance (open == close) --
docs/content/docs/proxy.mdx open=6 close=6
docs/content/docs/cache-optimization.mdx open=1 close=1
```
## Real Behavior Proof
- Environment: docs are static MDX (Fumadocs/Next.js); no runtime
behavior. Corrections were checked against `headroom/` source.
- Exact command / steps: grepped for references to deleted
components/pages; validated `meta.json` parses and no longer contains
`community-savings`; confirmed `<Callout>` open/close balance and
frontmatter on every edited page; verified every corrected API
name/field/import against the source modules (`text_crusher.py`,
`search_compressor.py`, `memory/__init__.py`, `code_compressor.py`).
- Observed result: no dangling references; nav valid; balanced JSX;
corrected code samples match the real importable API.
- Not tested: full `next build` / `npm run types:check` —
`docs/node_modules` is not installed in this environment. Recommend a
Vercel preview deploy (or `cd docs && npm i && npm run types:check`) as
the merge gate.
## Review Readiness
- [x] I have performed a self-review
- [x] This PR is ready for human review
## Checklist
- [x] My code follows the project's style guidelines
- [x] I have performed a self-review of my code
- [x] I have commented my code, particularly in hard-to-understand areas
— N/A (docs)
- [x] I have made corresponding changes to the documentation — this *is*
the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests — N/A (docs-only)
- [x] New and existing unit tests pass locally with my changes — N/A, no
code changed
- [x] I did **not** edit `CHANGELOG.md`
## Additional Notes
- Docs-only; no `headroom/` package code touched, so the
pytest/ruff/mypy items are N/A.
- The full Next.js build was not run locally (deps not installed) — a
Vercel preview is the recommended gate.
- Org normalization assumes `headroomlabs-ai` is canonical (matches
CI/GHCR + the newer docs). If `chopratejas/headroom` is still the
canonical **public** repo, revert the `docs/lib/*.ts` + install/docker
link changes.
- Heads-up: a separate `docs` branch exists on the remote — if the
Vercel docs site deploys from `docs` rather than `main`, retarget this
PR there.
