Commit Graph
5 Commits
Author SHA1 Message Date
Tejas ChopraandClaude Opus 5.5 4288fbd903 docs(teams): replace the 3-months-free perk with a talk-to-us pitch (#4524)
## Description

Removes the "3 months free with a 12-month plan" offer and every
headroom-perks.vercel.app link. Each place now says: not seeing the
savings you want? Headroom OSS is a framework built to show what's
possible, so it saves less; Headroom Enterprise saves more and adds more
cost savings, tokens secured, on premise deployment, deep attribution
and many more features. Teams and enterprises: talk to us at
hello@headroomlabs.ai or https://headroomlabs.ai.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [ ] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- README banner (`.github/assets/enterprise-perk.svg`): redrawn simple,
in the `hero.svg` type scale (title 42/700, lead 14.5, eyebrow 10.5); no
animation or chips.
- README "Headroom for teams" section and docs Teams page: the
OSS-vs-Enterprise table is replaced by the pitch, feature list and
contact.
- Docs site banner (`docs/app/layout.tsx`): new copy and link; new
banner id so people who dismissed the old one see it.
- Local dashboard offer (unlicensed installs only): new copy and link;
new localStorage dismissal key (`headroom-teams-contact-dismissed`) so
people who dismissed the old offer see the new one.
- Release-notes footer (`release.yml`) and `llms.txt`: same pitch, email
and site.
- `tests/test_dashboard_teams_perk.py`: asserts the contact email
instead of the perks URL.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [ ] Type checking passes (`mypy headroom`) (no Python source changed)
- [ ] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest -q tests/test_dashboard_teams_perk.py -k "not route"
4 passed, 4 deselected in 0.49s
$ ruff check headroom/dashboard tests/test_dashboard_teams_perk.py
All checks passed!
```

The 4 `/dashboard` route tests fail locally with `CancelledError` at
proxy startup; they fail the same way on unmodified `main` in the same
venv, so CI is the judge for those.

## Real Behavior Proof

- Environment: macOS, Python venv of this repo, headless Chrome.
- Exact command / steps: rendered
`get_dashboard_html(licensed=False/True)` and checked the offer block;
rendered the banner with `Google Chrome --headless=new --screenshot
--window-size=900,220 file://.github/assets/enterprise-perk.svg`; `grep
-rn "headroom-perks\|3 months"` over README, docs, llms.txt, headroom/
and .github/.
- Observed result: unlicensed: offer shown, contact email present, no
perks link, new dismissal key. Licensed: offer removed. Banner renders
cleanly within 880×200 with text in the hero font. The grep finds
nothing.
- Not tested: the docs site build (`docs/`) and the release-notes footer
step (runs only on release).

## Runtime Rollout Safety

- Rollout-managed feature(s): none
- Minimum rollout channel: n/a
- Stable/default behavior changed: only the text and link of the
dashboard offer on unlicensed installs
- Kill switch / disable path: setting `HEADROOM_LICENSE` removes the
offer, as before
- Unsafe override required: no
- Qualification impact: none
- Rollback path: revert this PR

## 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
- [ ] I have commented my code, particularly in hard-to-understand areas
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [ ] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Additional Notes

No test was added for the new dismissal key: it is browser localStorage
read by Alpine, which the Python tests do not run. Past release notes
still carry the old footer; editing them is a separate one-off.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-28 10:27:33 -07:00
1ad92f0cbc feat: show the Headroom for Teams offer in the dashboard, docs, llms.txt and release notes (#3991)
## Description

This PR puts the Headroom for Teams offer (3 months of Enterprise free
with a 12-month plan) in the places people go after the README (#3990):
the dashboard, the docs site, `llms.txt` and the release notes. Each
link carries its own `utm_source`/`utm_medium`, so we can see which
surface converts.

No linked issue.

## Type of Change

- [ ] Bug fix (non-breaking change that fixes an issue)
- [x] New feature (non-breaking change that adds functionality)
- [ ] Breaking change (fix or feature that would cause existing
functionality to change)
- [x] Documentation update
- [ ] Performance improvement
- [ ] Code refactoring (no functional changes)

## Changes Made

- **Dashboard:** a slim, dismissible banner under the header. It shows
the user's savings when they are $1 or more. It is a plain link, so
nothing is fetched or reported.
- The banner is removed server-side on any **licensed** proxy, using the
running proxy's effective licence: `ProxyConfig.license_key`,
`HEADROOM_LICENSE`, or the deprecated `HEADROOM_LICENSE_KEY`.
`create_app` resolves the licence once and passes it to
`get_dashboard_html(licensed=...)`. This is a review fix: before, only
`HEADROOM_LICENSE` was checked.
- This only hides a promotion. OSS still needs no licence and checks
none; licences belong to the Enterprise plugins.
- **Docs site:** a dismissible top banner, a sidebar link and a new
`/docs/teams` page.
- The page's Open source vs Enterprise table now states what OSS already
ships (tool search on Anthropic requests; opt-in, rule-based model
routing) and what Enterprise adds. This is a review fix.
- **`llms.txt`:** a Headroom for Teams section, with the same accuracy
fix.
- **Release notes:** a `release.yml` step appends one footer line under
the changelog. It is keyed on its own marker, `<!--
headroom-teams-footer -->`, rather than on the perks link, so a
changelog entry that mentions the link no longer suppresses the footer.
This is a review fix.
- **Telemetry opt-out:** `llms.txt` and `docs/content/docs/proxy.mdx`
named a `--offline` flag that does not exist. The switch is
`HEADROOM_OFFLINE=1`.

## Testing

- [x] Unit tests pass (`pytest`)
- [x] Linting passes (`ruff check .`)
- [x] Type checking passes (`mypy headroom`)
- [x] New tests added for new functionality
- [x] Manual testing performed

### Test Output

```text
$ pytest -q tests/test_dashboard_teams_perk.py tests/test_dashboard_static_assets.py
============================= 17 passed in 18.40s ==============================
# test_dashboard_teams_perk.py: renderer, with and without each licence env var and with an explicit flag;
# /dashboard route, unlicensed, with ProxyConfig.license_key, with HEADROOM_LICENSE, with HEADROOM_LICENSE_KEY

$ pytest -q tests -k "dashboard or release or license"
4 failed, 305 passed, 1 skipped
# the 4 failures are tests/test_dashboard/test_live_feed.py (Playwright browser tests). They fail identically
# on this branch without the review commit; it is this machine's browser setup.

$ ruff check headroom/dashboard/__init__.py headroom/proxy/server.py tests/test_dashboard_teams_perk.py
All checks passed!
$ mypy headroom/dashboard/__init__.py --ignore-missing-imports
Success: no issues found in 1 source file

# release footer step, simulated twice on notes that already link the perks page:
appended
skipped        # re-run is a no-op; footer present exactly once
```

## Real Behavior Proof

- Environment: macOS 26.6 (arm64), Python 3.12.13, FastAPI `TestClient`
against `create_app`.
- Exact command / steps: `pytest -q tests/test_dashboard_teams_perk.py`.
The release step's shell was run twice against a notes file that already
mentions `headroom-perks.vercel.app`.
- Observed result: the `/dashboard` route serves the banner unlicensed,
and strips it for each of the three licence sources while leaving the
rest of the page intact. The footer is appended once and is not
duplicated on a re-run.
- Not tested: the release step against a real GitHub release (it runs on
the next release), and the docs `next build` after this commit (only
Markdown/MDX text changed).

## Runtime Rollout Safety

- Rollout-managed feature(s): none.
- Minimum rollout channel: stable.
- Stable/default behavior changed: yes. Unlicensed dashboards show a
dismissible banner, and the docs site shows a dismissible banner.
- Kill switch / disable path: set any licence token to hide the
dashboard banner. It is a plain link, with no network calls.
- Unsafe override required: no.
- Qualification impact: none.
- Rollback path: revert this PR.

## 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
- [x] I have made corresponding changes to the documentation
- [x] My changes generate no new warnings
- [x] I have added tests that prove my fix is effective or that my
feature works
- [x] New and existing unit tests pass locally with my changes
- [x] I did **not** edit `CHANGELOG.md` — it is generated by
release-please from my Conventional Commit PR title (a CI guard enforces
this)

## Screenshots (if applicable)

N/A

## Additional Notes

- **Review fixes are in `eeb0008a`:** @JerrettDavis's two points (the
effective licence source, and the OSS routing row) and Devin's
footer-marker and `--offline` findings.
- **Not changed:** Devin's suggestion to show sub-dollar savings. The $1
floor is deliberate, because "you saved $0.40" weakens the offer, and
the cost card still shows the exact amount.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: JD Davis <mxjerrett@gmail.com>
2026-10-07 10:59:41 -05:00
Tejas ChopraandClaude Opus 5 4bca514acd docs: correct the published site against the code (#3388)
Audited all 52 pages of docs.headroomlabs.ai/docs against source,
executing code rather than reading it. **36 pages changed.** Every
figure that could not be traced to a benchmark, a test, or a committed
artifact was measured or removed — none was replaced with a different
guess.

## The site was telling users things that were not true

**Telemetry.** `proxy.mdx` stated *"nothing is sent to Headroom Labs"*
and that the anonymous beacon *"has been removed from the code."*
Neither is true — `BEACON_DEFAULT_ON = True`
(`headroom/telemetry/beacon.py:56`), `is_beacon_enabled()` is fail-open,
and there is a live POST at `headroom/telemetry/session.py:75`.

`proxy.mdx` and `limitations.mdx` now describe both switches accurately,
say why the beacon exists (compression quality is the product; it shows
when a release regresses a ratio across real workloads), and list the 12
fields the collector allowlists instead of asserting "content-free". The
install id is disclosed for what it is: a random UUID, not a machine
fingerprint, resettable by deleting the file.

**Numbers.** The landing page's "Proof" table claimed 92/92/47/73%
savings from a harness that seeded nothing, so it could not reproduce a
figure even in principle.

| Scenario | Claimed | Measured |
|---|---|---|
| Code search (100 results) | 92% | **21%** |
| SRE incident debugging | 92% | **57%** |
| Codebase exploration | 47% | **42%** |
| GitHub issue triage | 73% | **30%** |

`real_world_agent_benchmark.py` now seeds, and
`benchmarks/index_proof_table.py` measures the same four scenarios
through the real tokenizer and the real `compress()` path with no
network call. Stable across five seeds; the page cites the command.

Latency was wrong in the *other* direction — 189 ms and 943 ms published
against **0.21 ms and 0.80 ms** measured. The docs made the product look
~1000× slower than it is.

**Examples.** Every `agno` example was broken at line one, including
Quick Start: `HeadroomAgnoModel`'s first dataclass field is `id`, so a
positional wrapped model bound to the wrong field and raised
`ValueError`. `api-reference.mdx` — the canonical signature reference —
had 13 broken examples, including three `AttributeError`s in the first
three lines of its `simulate()` block. Four integration pages omitted
the `[proxy]` extra and then told the reader to run `headroom proxy`,
which fails immediately. `ccr.mdx` showed SDK-level retrieval that only
exists in the proxy handlers.

Also: six Prometheus metric names that are never emitted, a Grafana
dashboard filtering on a label no metric carries, a documented deploy
workflow that does not exist, a 365-day retention default the code caps
at 30, and CCR TTL stated as 5 minutes against an actual 1800s.

## Canonical URL bug

`robots.ts`, `sitemap.ts` and `layout.tsx` fell back to a hardcoded
`headroom-docs.vercel.app` when `NEXT_PUBLIC_SITE_URL` was unset — so
the live site served a sitemap and `Host:` on the wrong domain and
pointed crawlers at the wrong canonical. Verified in the build output:
robots and all 53 sitemap URLs now carry `docs.headroomlabs.ai`.

Setting `NEXT_PUBLIC_SITE_URL=https://docs.headroomlabs.ai` in Vercel is
still worth doing so previews match, but the code no longer depends on
it.

## Verification

Four adversarial judges re-checked this work. They confirmed the
landing-page table reproduces digit-for-digit across five seeds, found
**zero cross-page contradictions**, independently regenerated all nine
surviving compression percentages, and proved `headroom_keep_turns` dead
at runtime with a mocked-transport test. They also caught two links this
audit had reversed to the deprecated org, and 18 examples it had missed
— both fixed here.

`next build` passes with all 52 pages prerendered, matching the
pre-change baseline.

## Follow-up, not in this PR

- GitHub org migration (`chopratejas` → `headroomlabs-ai`) across
source, manifests and packaging, plus stale-domain fixes in `llms.txt`,
the dashboard UI and `pyproject.toml`.
- `wiki/` disposition: it is unpublished and unbuilt, and
`wiki/benchmarks.md` carried an invented production-telemetry section
(250+ instances, 1.4 billion tokens saved) that exists nowhere in the
repo.
- `langchain.mdx` imports are dead against LangChain 1.x
(`langchain.memory`, `langchain.retrievers`,
`create_openai_tools_agent`). Needs a pin-vs-rewrite decision.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

https://claude.ai/code/session_01HRaEPjQcCSAwD2xbQMNENu

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
2026-09-02 15:15:37 +05:30
chopratejas c1d2eec588 docs: improve discoverability for AI agents and search crawlers
Several signals AI agents and search engines use to discover and
install a project were misaligned or missing:

* ``docs/app/layout.tsx`` set ``metadataBase`` to
  ``https://chopratejas.github.io/headroom/`` while the live docs run
  on Vercel — every page's ``og:url`` and ``twitter:url`` resolved to
  a URL that returns 404 for ``/llms.txt``. Now points at the live
  Vercel host (overridable via ``NEXT_PUBLIC_SITE_URL`` for a future
  custom domain). Adds explicit ``openGraph`` and ``twitter`` metadata
  so social shares render a card with the project's pitch.
* No ``llms.txt`` at the GitHub repo root. AI agents crawling
  ``github.com/chopratejas/headroom/`` saw only the README. The new
  ``llms.txt`` follows the llmstxt.org convention: 1-line pitch,
  canonical docs links, copy-paste install commands (pip / npm /
  Docker / proxy / ``headroom wrap``), and entry points for the
  library, proxy, MCP server, and SDK integrations. Points at the
  Fumadocs-generated ``/llms.txt`` and ``/llms-full.txt`` for the
  full picture.
* ``pyproject.toml`` ``Documentation`` URL pointed at the GitHub
  README anchor. Updated to point at the docs site so PyPI visitors
  land on searchable docs, and adds an ``AI / LLM Index`` URL
  pointing at the Fumadocs ``/llms.txt``.
* No explicit AI-bot allow list. Added ``docs/app/robots.ts`` (Next
  13+ App Router convention) with explicit allows for GPTBot,
  ClaudeBot, PerplexityBot, Google-Extended, OAI-SearchBot,
  ChatGPT-User, Cohere-AI, CCBot, and Applebot-Extended. Wildcard
  allow as the catch-all. Advertises the sitemap.
* No ``sitemap.xml`` route. Added ``docs/app/sitemap.ts`` that pulls
  every Fumadocs page out of ``source`` (same source backing
  ``/llms.txt``, search, and OG images) so search and AI crawlers
  can enumerate doc pages without scraping HTML.
* README didn't tell AI agents where to look. Added a 2-line
  pointer near the top nav row: read ``/llms.txt`` here, or fetch
  the live index / full docs blob.

Also tightened the GitHub repo description and added five topics
(``claude-code``, ``cursor``, ``tokens``, ``prompt-engineering``,
``typescript``) via ``gh repo edit`` — that's already live on the
repo, not part of this commit.

No Python or Rust code changes; ``make ci-precheck`` was run to
confirm the test slice still passes.
2026-05-13 17:36:06 -07:00
Adib Mohsin 911eb85a44 new docs UI + ts doc coverage 2026-04-12 13:15:58 +06:00