mkdocs.yml

site_name: context-guru
site_description: >-
  Provider-agnostic context engineering for LLM agents — shrink the tokens a
  request carries, losslessly or lossy-but-reversibly, without touching the agent.
site_url: https://rossoctl.github.io/context-guru/
repo_url: https://github.com/rossoctl/context-guru
repo_name: rossoctl/context-guru
edit_uri: edit/main/docs/
copyright: >-
  Apache-2.0 &middot; a <a href="https://github.com/rossoctl">Rossoctl</a> platform component

# The site ships its own theme — `theme/` — rather than Material for MkDocs.
# It is the design system already in production on the sibling cap-evolve site:
# dark-first CSS custom properties with a light override on `html[data-theme]`,
# one hand-written stylesheet, one small vanilla-JS file, no framework. MkDocs
# core stays as the Markdown engine, so `docs/**/*.md` is still the only source
# of prose and every page's nav, TOC and search index is still generated.
theme:
  name: null
  custom_dir: theme
  locale: en
  logo: img/context-guru.png
  favicon: img/context-guru.png
  # `name: null` means MkDocs never reads a `mkdocs_theme.yml`, so a theme's own
  # options have to live here.
  static_templates:
    - 404.html
  # The search plugin ships only its index. The search UI is a ~70-line overlay in
  # theme/js/site.js reading search/search_index.json directly, so there is no
  # lunr.js bundle, no web worker and no standalone /search/ page.
  include_search_page: false
  search_index_only: true
  # One-line announcement bar. Keep it factual and keep it to one clause.
  announce: >-
    SWE-bench Verified, live, four arms: <strong>13% cheaper</strong> than no
    compaction, and the highest reward.

markdown_extensions:
  - abbr
  - admonition
  - attr_list
  - def_list
  - footnotes
  - md_in_html
  - tables
  - toc:
      permalink: true
      permalink_title: Link to this section
      toc_depth: 3
  - pymdownx.details
  - pymdownx.highlight:
      anchor_linenums: true
      line_spans: __span
      pygments_lang_class: true
  - pymdownx.inlinehilite
  - pymdownx.snippets
  - pymdownx.keys
  - pymdownx.tabbed:
      alternate_style: true
  - pymdownx.superfences:
      custom_fences:
        - name: mermaid
          class: mermaid
          format: !!python/name:pymdownx.superfences.fence_code_format

# Wraps every generated <table> in a scroll container. A wide results table has to
# scroll inside its own column, not push the page body sideways, and no author
# should have to remember an HTML wrapper to get that.
hooks:
  - theme/hooks.py

# Fail the build on a link that points at nothing, not just on a bad config.
validation:
  omitted_files: warn
  absolute_links: warn
  unrecognized_links: warn
  anchors: warn

# docs/superpowers/ holds working plans/specs for the skill that authored them, not
# published site content — keep it out of the nav-completeness check above.
#
# docs/proposals/ is the same category and excluded for the same reason: design rationale
# addressed to whoever changes the code next, not to whoever runs it. sweep-adjudicator.md, for
# instance, argues against an earlier version of its own design and records which measurements
# refuted it — useful in review, actively confusing on a page a user reaches looking for how to
# configure something. Excluded rather than added to the nav so `mkdocs build --strict` stays
# green without publishing internal argument, and so a proposal can be added without a nav edit.
exclude_docs: |
  superpowers/
  proposals/
  plans/

# Nav mirrors how people arrive: install it the easy way and see what it saves
# (Get started) → run it yourself instead of the plugin (Advanced /
# Self-hosting) → understand it (Concepts) → look a component up (Components)
# → run it a particular way (Modes, Dashboard, Hosted) → check the claims
# (Results) → wire it in (Integrations). Every page under docs/ appears exactly
# once.
nav:
  - Home: index.md
  - Get started:
      - Install the Claude Code plugin: how-to/install-plugin.md
      - The plugin's recovery files: how-to/plugin-recovery-files.md
      - Use with Claude Code: how-to/use-with-claude-code.md
      - Claude Code plugin:
          - Overview and install: plugin/index.md
          - Commands: plugin/commands.md
          - Home and status: plugin/status.md
          - Insights: plugin/insights.md
          - Insights savings: plugin/savings.md
          - Insights cache: plugin/cache.md
          - Insights tools: plugin/waste.md
          - Session: plugin/session.md
          - Doctor: plugin/doctor.md
          - Save more: plugin/save-more.md
          - Remove MCP servers and skills: plugin/remove-mcp-and-skills.md
          - Cache campaign: plugin/cache-campaign.md
          - Terminal views: plugin/terminal-views.md
          - Status line: plugin/statusline.md
          - Configuration and troubleshooting: plugin/configuration.md
      - Test a subscription login in a sandbox: how-to/test-subscription-sandbox.md
      - How it saves money: get-started/how-it-saves.md
      - Technical overview: get-started/overview.md
      - "Quickstart: proxy": get-started/quickstart-proxy.md
  - Concepts:
      - Architecture: design.md
      - Reversibility & recovery: how-to/recover-context.md
      - Data dependence & storage off: data-dependence.md
      - When your agent compacts: how-to/agent-compaction.md
      - Measuring savings: how-to/measure-savings.md
      - Keep an idle prompt cache warm: how-to/cache-keepalive.md
      - Choose a cache TTL: how-to/kv-cache-ttl.md
      - Budget keep-alive pings: how-to/kv-cache-keepalive-budget.md
  - Components:
      - Overview: components.md
      - Choose a preset: reference/presets.md
      - Reformat components: components/reformat.md
      - Prompt caching: components/caching.md
      - "Offload: deterministic reducers": components/offload-reducers.md
      - cmdfilter: components/cmdfilter.md
      - extract_llm: components/extract_llm.md
      - skeleton: components/skeleton.md
      - summarize: components/summarize.md
      - coref: components/coref.md
      - Advanced & experimental Offload components: components/advanced-offload.md
      - The DSL filter engine: components/dsl.md
      - Examples: examples/live-captures.md
  - Modes:
      - Sync & observe: how-to/operating-modes.md
      - Config & routes reference: reference/reference.md
      - Session recorder (cg_record build): reference/session-recorder.md
      - Settings form & field descriptors: how-to/settings-form.md
  - Dashboard: dashboard.md
  - "The dashboard, tab by tab": how-to/dashboard-guide.md
  - Hosted service: hosted.md
  - Results:
      - Overview: RESULTS.md
      - Where the money went: results/vs-competitors.md
      - Full comparison: results/comparison.md
      - Measured value, Aug 2026: results/measured-2026-08.md
      - "saved_usd correction, Sep 2026": results/saved-usd-correction-2026-09.md
      - Component internals & examples: results/components.md
      - Reproduce the results: results/REPRODUCE.md
      - Improvement plan: results/improvement-plan.md
      - KV-cache TTL predictors, the whole story: results/kv-ttl-predictor-summary.md
      - TTL predictor feature catalog: results/kv-ttl-predictor-features.md
      - Rule-based and learned TTL arms, scored: results/kv-ttl-predictor-arms.md
      - TTL predictors compared, pooled and per tenant: results/kv-ttl-predictor-comparison.md
      - "Strategies vs Overview: reconciling keep-alive savings": results/kv-ttl-savings-reconciliation.md
      - "Accountant: where cg's saving differs from the expected figure": accountant/cg-differences.md
      - "Accountant: root causes of the differences": accountant/cg-differences-root-causes.md
      - "The keep-alive reuse model: features, fit, and what it is worth": results/kv-cache-keepalive-reusemodel.md
      - "SWE-bench Verified: per-arm detail": results/swebench-arms.md
      - "Terminal-Bench 2.0":
          - Four-way comparison: results/terminal-bench-comparison.md
          - Per-arm detail: results/terminal-bench-arms.md
      - "Co-reference density (measurement)": results/coref-density.md
      - "Co-reference selection (experiment)": results/coref-selection-experiment.md
      - "Co-reference reachability (measurement)": results/coref-reachability.md
      - "Co-reference on the eval box": results/coref-evalbox.md
      - "coref on LOCA-bench": results/coref-loca.md
      - "What can and cannot be measured": results/measurement-limits.md
      - "What actually fires (component gating)": results/component-gating.md
      - "The floor and the economic gate": results/min-tokens-vs-economic-gate.md
  - Integrations:
      - Host adapters: integrations.md
      - bifrost plugin: how-to/bifrost-plugin.md
      - llm-d compaction service: examples/llm-d-service.md
      - Contributing & community: community.md
      - Run the eval harness locally: setup.md