Compress tool outputs, logs, files, and RAG chunks before they reach the LLM. 20% fewer tokens for coding agents, 60-95% fewer tokens for JSON, same answers. Library, proxy, MCP server.
Python agentaianthropicclaude-codecompressioncontext-engineeringcontext-windowcursorfastapilangchainllmmcpopenaiprompt-engineeringproxypythonragtoken-optimizationtokenstypescript
chore(docs): one documentation site, not two (#2784)
Tejas Chopra3c10e8ff00f8
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.ymlindex e22833c03..0fd773191 100644--- a/.github/workflows/docs.yml+++ b/.github/workflows/docs.yml@@ -1,26 +1,27 @@-name: Deploy Documentation+name: Validate Docs++# There is ONE documentation site: the Next.js/Fumadocs app in `docs/`, published+# at https://headroom-docs.vercel.app by Vercel's own Git integration. That URL is+# what README and `pyproject.toml` (Homepage, Documentation) point at.+#+# This workflow therefore only *validates* — it deploys nothing. Vercel owns+# deployment; duplicating it here is what produced a `deploy-vercel` job that+# failed 30 times on main without ever deploying (no VERCEL_* secrets were set).+#+# A second site used to be built from `wiki/` by MkDocs and published to GitHub+# Pages off the `gh-pages` branch. It was linked from nowhere in the repo, it meant+# every documented change had to be written twice, and each Pages deploy+# force-pushed `gh-pages` — which Vercel then tried to build, failing with+# "The specified Root Directory 'docs' does not exist" because that branch holds+# only the rendered site. Removed. `wiki/` stays in the repo as unpublished+# markdown pending migration of the pages `docs/` does not yet cover (notably+# `wiki/cli.md`); nothing builds or publishes it, so it needs no syncing.on:pull_request:branches: [main]paths:- 'docs/**'- - 'wiki/**'- - 'mkdocs.yml'- - '.github/workflows/docs.yml'- # Push only deploys GitHub Pages, and `mkdocs.yml` sets `docs_dir: wiki` — so the- # sources that matter here are wiki/ and mkdocs.yml, NOT docs/ (that is the- # Next.js site, which Vercel deploys through its own Git integration).- #- # wiki/** was missing, so a merge touching only wiki/ never triggered this- # workflow and the published Pages site silently went stale. docs/** was present- # but mkdocs never reads it, so it only bought a no-op Pages rebuild.- push:- branches:- - main- paths:- - 'wiki/**'- - 'mkdocs.yml'- '.github/workflows/docs.yml'workflow_dispatch:@@ -28,35 +29,8 @@ permissions:contents: readjobs:- validate-mkdocs:- name: Validate mkdocs build- if: github.event_name == 'pull_request'- runs-on: ubuntu-latest- timeout-minutes: 10- steps:- - uses: actions/checkout@v7-- - name: Set up Python- uses: actions/setup-python@v6- with:- python-version: '3.11'-- - name: Cache pip- uses: actions/cache@v6- with:- path: ~/.cache/pip- key: ${{ runner.os }}-pip-docs-${{ hashFiles('mkdocs.yml') }}- restore-keys: ${{ runner.os }}-pip-docs--- - name: Install dependencies- run: pip install mkdocs-material-- - name: Build docs- run: mkdocs build-validate-nextjs:name: Validate Next.js build- if: github.event_name == 'pull_request'runs-on: ubuntu-latesttimeout-minutes: 15steps:@@ -76,43 +50,3 @@ jobs:- name: Build docsrun: npm run buildworking-directory: docs-- deploy-github-pages:- name: Deploy GitHub Pages- if: github.event_name != 'pull_request'- runs-on: ubuntu-latest- permissions:- contents: write- steps:- - uses: actions/checkout@v7- with:- fetch-depth: 0-- - name: Set up Python- uses: actions/setup-python@v6- with:- python-version: '3.11'-- - name: Cache pip- uses: actions/cache@v6- with:- path: ~/.cache/pip- key: ${{ runner.os }}-pip-docs-${{ hashFiles('mkdocs.yml') }}- restore-keys: ${{ runner.os }}-pip-docs--- - name: Install dependencies- run: pip install mkdocs-material-- - name: Build and deploy- run: mkdocs gh-deploy --force--# The Next.js docs site is deployed by Vercel's own Git integration, so there is no-# deploy job for it here. A `deploy-vercel` job used to run `npx vercel deploy-# --prod` on every push to main, but VERCEL_TOKEN / VERCEL_ORG_ID /-# VERCEL_PROJECT_ID are not configured as secrets (repo or org), so it invoked the-# CLI with an empty `--token=` and exited 1. It therefore never deployed anything:-# 30 failed runs on main between 2026-07-14 and 2026-08-04. `deploy-github-pages`-# succeeded in those same runs — only this job failed — so the red was pure noise.-#-# `Validate Next.js build` above still guards docs/** on pull requests, so a broken-# MDX change is caught before merge.diff --git a/docs/content/docs/configuration.mdx b/docs/content/docs/configuration.mdxindex c4bf1bc8f..40ee56530 100644--- a/docs/content/docs/configuration.mdx+++ b/docs/content/docs/configuration.mdx@@ -399,7 +399,7 @@ precedence rules: explicit argument > per-resource env var > derivedfrom canonical root > default. Every legacy env var continues to workunchanged.-See the **[Filesystem Contract](https://github.com/headroomlabs-ai/headroom/blob/main/wiki/filesystem-contract.md)**+See the **[Filesystem Contract](/docs/filesystem-contract)**page for the full bucket table, plugin-author guidance, and the Dockernaming overlap note (`HEADROOM_WORKSPACE` is *not* the same as`HEADROOM_WORKSPACE_DIR`).diff --git a/mkdocs.yml b/mkdocs.ymldeleted file mode 100644index 5d41f8b3c..000000000--- a/mkdocs.yml+++ /dev/null@@ -1,136 +0,0 @@-site_name: Headroom-docs_dir: wiki-site_description: "The Context Optimization Layer for LLM Applications — compress everything your AI agent reads."-site_url: https://chopratejas.github.io/headroom-repo_url: https://github.com/chopratejas/headroom-repo_name: chopratejas/headroom-edit_uri: edit/main/docs/--theme:- name: material- custom_dir: docs/overrides- palette:- - media: "(prefers-color-scheme: light)"- scheme: default- primary: deep purple- accent: amber- toggle:- icon: material/brightness-7- name: Switch to dark mode- - media: "(prefers-color-scheme: dark)"- scheme: slate- primary: deep purple- accent: amber- toggle:- icon: material/brightness-4- name: Switch to light mode- font:- text: Inter- code: JetBrains Mono- features:- - content.code.copy- - content.code.annotate- - content.tabs.link- - navigation.instant- - navigation.instant.progress- - navigation.tabs- - navigation.tabs.sticky- - navigation.sections- - navigation.expand- - navigation.top- - navigation.indexes- - search.highlight- - search.suggest- - search.share- - toc.follow- - header.autohide- icon:- repo: fontawesome/brands/github- logo: material/layers-outline--plugins:- - search--extra_css:- - stylesheets/extra.css--markdown_extensions:- - admonition- - attr_list- - def_list- - md_in_html- - tables- - toc:- permalink: true- - pymdownx.highlight:- anchor_linenums: true- line_spans: __span- pygments_lang_class: true- - pymdownx.inlinehilite- - pymdownx.snippets- - pymdownx.superfences:- custom_fences:- - name: mermaid- class: mermaid- format: !!python/name:pymdownx.superfences.fence_code_format- - pymdownx.tabbed:- alternate_style: true- - pymdownx.details- - pymdownx.emoji:- emoji_index: !!python/name:material.extensions.emoji.twemoji- emoji_generator: !!python/name:material.extensions.emoji.to_svg- - pymdownx.tasklist:- custom_checkbox: true--nav:- - Home: index.md- - Getting Started:- - Quickstart: quickstart.md- - Installation: getting-started.md- - Docker-Native Install: docker-install.md- - Persistent Installs: persistent-installs.md- - Configuration: configuration.md- - User Guide:- - Proxy Server: proxy.md- - Compression Pipeline: compression.md- - CCR (Lossless Retrieval): ccr.md- - Image Compression: image-compression.md- - Memory System: memory.md- - Shared Context: shared-context.md- - Failure Learning: learn.md- - Integrations:- - Overview: integration-guide.md- - Vertex AI: vertex.md- - LangChain: langchain.md- - Agno: agno.md- - Strands: strands.md- - MCP Tools: mcp.md- - How It Works:- - Architecture: ARCHITECTURE.md- - Transforms Pipeline: transforms.md- - Text Compression: text-compression.md- - LLMLingua: llmlingua.md- - Benchmarks:- - Accuracy: benchmarks.md- - Latency: LATENCY_BENCHMARKS.md- - Limitations: LIMITATIONS.md- - Reference:- - CLI: cli.md- - API: api.md- - SDK: sdk.md- - Differential Network Capture: network-diff-capture.md- - Metrics & Observability: metrics.md- - Error Codes: errors.md- - Troubleshooting: troubleshooting.md- - Deployment:- - macOS LaunchAgent: macos-deployment.md--extra:- social:- - icon: fontawesome/brands/github- link: https://github.com/chopratejas/headroom- - icon: fontawesome/brands/python- link: https://pypi.org/project/headroom-ai/- - icon: fontawesome/brands/discord- link: https://discord.gg/yRmaUNpsPJ- generator: false