@zenithfoundry/slm-gate 1.2.1

package/configs/claude-desktop/.env.24gb.example

@@ -0,0 +1,674 @@
+# ==============================================================================
+# SMALL-LANGUAGE-MODEL-GATE CONFIGURATION FOR: CLAUDE DESKTOP
+# RAM PRESET: 24GB
+#  (Includes TLS configuration example)
+
+# ==============================================================================
+# 
+# HOW TO USE THIS FILE:
+# 1. Copy this entire template to a new file named `.env`.
+# 2. Open `.env` and fill in the values following the steps below.
+# 3. This file is the SINGLE source of truth for env var NAMES. The agent must
+#    not invent new names; if a new variable is needed, extend this template first.
+# 4. SECRETS: Leave API keys blank in this template file. Only put secrets in `.env`.
+#
+# --- CONFIGURATION STEPS (Top to Bottom Sequence) ---
+#
+# STEP 1: Local Small Model (SLM) Setup
+#   - SLM_PROVIDER: Choose your backend ('ollama' or 'openai' for OpenAI-compatible APIs).
+#   - OLLAMA_HOST: URL for your local inference server (e.g., http://localhost:11434).
+#     Include the http:// scheme; Ollama's own OLLAMA_HOST is a bare host:port and will not work here.
+#   - SLM_BRAIN_MODEL: Your "smart" local model used for drafting and heavy lifting.
+#     (Example: qwen3:14b, llama3:8b)
+#   - SLM_GATE_MODEL: Your fastest, smallest local model for routing and quick classification.
+#     (Example: qwen3:1.7b, phi3:mini)
+#     Not sure which models fit your computer? llmfit shows what runs best on it: https://github.com/AlexsJones/llmfit
+#   - SLM_GATE_TESTING_MODEL: Dedicated model for offline benchmarks and test suites (`slm-gate bench`).
+#     Defaults to matching SLM_GATE_MODEL to avoid VRAM exhaustion/timeouts during concurrent test runs.
+#   - NUM_CTX: Caps the context window. Large contexts rapidly inflate RAM usage via the KV cache.
+#     > What `slm-gate init` and `slm-gate doctor` pick for your RAM (src/hardware.ts recommendNumCtx), leaving
+#     > room for your OS and apps while both local models are loaded. slm-gate needs 16 GB of RAM or more:
+#       * 16GB RAM          -> NUM_CTX=4096
+#       * 24GB RAM and more -> NUM_CTX=8192   (raise it if you like: more context uses more RAM, replies slower)
+#   - TEMPERATURE: Keep at 0 for deterministic output during logical routing and compression.
+#
+# STEP 2: Verifier Settings
+#   - STRICTNESS_LEVELS: Defines the available grading scales (0 = loose, 5 = max strictness).
+#   - HEADLINE_STRICTNESS: Set to a single integer to dictate the active strictness level (e.g., 4).
+#
+# STEP 3: API model (optional; NOT used by the model gate, which forwards each tool's own login)
+#   - Used only by the benchmark, the resolver's cloud tier and SLM_PROVIDER=openai.
+#   - CLOUD_API_STYLE: Set to 'openai' or 'anthropic'.
+#   - Fill in your API Key, Base URL, and specific Cloud Model. 
+#     (Example: CLOUD_BASE_URL=https://api.openai.com/v1 | CLOUD_MODEL=gpt-5.6-terra)
+#   Semantic Cache (Optional)
+#   - SEMCACHE: Set to 'on' to enable local semantic caching of cloud requests.
+#   - SEMCACHE_THRESHOLD: Similarity threshold (0.0 to 1.0) for a cache hit.
+#   - EMBED_MODEL: The embedding model to use for the semantic cache.
+#
+# STEP 4: Server Configurations (Layer 1 & 2)
+#   - Set the ports for the LLM Gate (Layer 2) and MCP Gate (Layer 1).
+#   - The model gate's switches: LLM_GATE_AUTOSTART, LLM_GATE_DISTILL, LLM_GATE_LOCAL_FIRST,
+#     LOCAL_ATTEMPT_BUDGET_MS, and UPSTREAM_* (only behind a company gateway).
+#   - DOWNSTREAM_MCP: How the agent talks to tools. Leave blank to run standalone. 
+#     If connecting to an MCP server, provide a JSON config:
+#       > Stdio Example: {"command":"node","args":["/[...]/[...]/[...]/ai-dev/agent-toolbox/tech-lead-stack/dist/mcp-server.mjs"],"env":{}}
+#       > HTTP Example:  {"url":"https://host/mcp","headers":{"Authorization":"Bearer TOKEN"}}
+#
+# STEP 5: Logging & Telemetry (Ledger / Langfuse)
+#   - LEDGER_PATH: Where local SQLite logs are saved.
+#   - Langfuse: Optional cloud observability. Fill keys to enable, or leave blank to keep it local.
+#
+# STEP 6: Clarification Resolver & Misc
+#   - RESOLVER_CLOUD_TIER: Set to 'on' to permit bounded cloud API calls for unresolved queries.
+#   - RAM_PRESET: Your RAM size (ram-16, ram-24, ram-32, ram-48, ram-64, ram-128, or custom) picks default models.
+#   - Tool-Output Distillation & Elision: Configure caps for tool outputs and cache limits.
+#     (DISTILL_MAX_TOKENS, ELISION_MAX_MB, etc.)
+#   - Dynamic Routing Tuning: Toggle automatic exploration of routing thresholds.
+#
+# ==============================================================================
+# ==============================================================================
+# SMALL-LANGUAGE-MODEL-GATE ENVIRONMENT CONTRACT & SETUP GUIDE
+# ==============================================================================
+#
+# HOW TO USE THIS FILE
+#   1. Copy this whole file to `.env`  ->  cp .env.example .env
+#   2. Fill in the values below (secrets ONLY go in `.env`, never in this template).
+#   3. This file is the SINGLE source of truth for env var NAMES. The build agent
+#      must not invent new names; if a new setting is needed, add it here first.
+#
+# HOW TO READ EACH ENTRY
+#   Every variable has a comment block:
+#     What:   what the value is
+#     Why:    why it exists / what problem it solves
+#     Does:   how the code actually uses it
+#     Values: allowed values / examples / defaults
+#
+# MENTAL MODEL (so the sections make sense)
+#   A request has two possible "gates":
+#     - LAYER 1  mcp-gate  sits between your IDE and an MCP server; it *conditions*
+#                            skill/prompt text with a LOCAL model before it reaches the cloud.
+#     - LAYER 2  llm-gate  the "model gate": an HTTP server your coding tool sends its model
+#                            requests to. It answers a first message LOCALLY when it can, shrinks
+#                            large tool output, and sends the rest on to the tool's own provider
+#                            with the tool's own login.
+#   "Local" model  = the SLM you run in Ollama (free per token, costs only RAM + latency).
+#   "Cloud" model  = the provider your coding tool already uses (Anthropic, OpenAI, Google).
+#   Everything is logged to a local SQLite "ledger" and (optionally) to Langfuse.
+#
+# ============================================================
+#
+#  WHAT THIS TOOL DOES
+#    Runs a small AI model on YOUR computer to handle the easy parts of a
+#    request, so you hit the expensive PAID model less. Two parts, use either:
+#      - llm-gate : a local mini-server your coding tool sends its model requests to. Answers
+#                   easy first messages with the local model, shrinks large tool output, and
+#                   sends everything else to the provider the tool uses anyway, with the tool's
+#                   own login (subscription or API key). Starts by itself (LLM_GATE_AUTOSTART).
+#      - mcp-gate : sits in front of a tool server (MCP) and trims the instructions
+#                   before they reach whatever model your editor uses (often your subscription).
+#
+#  WHO PAYS FOR WHAT
+#    Requests the gate sends on are billed exactly as without it: to your subscription or
+#    your API key, whichever the tool is logged in with. There are just fewer of them, and
+#    they are smaller. The "API model" in STEP 3 is a separate, optional key used only by
+#    the benchmark and the resolver's cloud tier.
+#
+#  OTHER TERMS
+#    local model / SLM  the small model you run via Ollama. Free to run.
+#    ledger             a local log file of every request's cost + tokens (STEP 5).
+#    tech-lead-stack    a SEPARATE, OPTIONAL project this can plug into. Not using it? Leave TLS off.
+#
+#  MINIMUM TO GET RUNNING: just STEP 1. Everything else is optional.
+# ============================================================
+
+
+# ============================================================
+#  STEP 1 the local model  (required)
+# ============================================================
+
+# Where the local model runs.
+#   ollama = on your machine (normal).  openai = some other OpenAI-style server.
+SLM_PROVIDER=ollama
+
+# Address of your local Ollama. Leave as-is unless you changed Ollama's port.
+# Must include http:// -- Ollama's own OLLAMA_HOST variable is a bare host:port, this one is a URL.
+OLLAMA_HOST=http://localhost:11434
+
+# The main local model (does the real work). Any Ollama tag works.
+#   Note: there is no `qwen3:9b`. For a 9B use `qwen3.5:9b` instead.
+SLM_BRAIN_MODEL=qwen3.5:4b
+
+# A tiny, fast local model for quick "is this easy?" checks and prompt distillation.
+SLM_GATE_MODEL=qwen2.5-coder:3b
+
+# Model used specifically for offline benchmarks and testing suites (`slm-gate bench`).
+# Defaults to matching SLM_GATE_MODEL so high-concurrency benchmark batches avoid VRAM contention and timeouts.
+SLM_GATE_TESTING_MODEL=qwen2.5-coder:3b
+
+# How long models stay loaded in Ollama's memory (e.g. 5m, 1h, 12h, or -1 for indefinite).
+OLLAMA_KEEP_ALIVE=12h
+
+# ── DUAL-MODEL MEMORY CONCURRENCY (OLLAMA_MAX_LOADED_MODELS) ────────────
+# By default, Ollama keeps only 1 model loaded in memory at a time.
+# When running both a Gate model (e.g. 3B) and Brain model (e.g. 9B), Ollama will 
+# swap model weights back and forth between disk and GPU unless configured to hold both.
+# If your machine has >=16GB - 24GB RAM (e.g. Apple Silicon M4 24GB):
+#   - Set OLLAMA_MAX_LOADED_MODELS=2 in your environment or shell profile:
+#     * macOS (persistent): `launchctl setenv OLLAMA_MAX_LOADED_MODELS 2`
+#     * Terminal / Linux:   `export OLLAMA_MAX_LOADED_MODELS=2`
+#     > Note: Loading two models requires allocating two KV caches. On Apple Silicon, 
+#       GPU memory is capped. If models get evicted, halve your NUM_CTX (24GB->8192, 16GB->4096) 
+#       to ensure both models fit within your machine's GPU memory envelope.
+
+# ── ⚠️ RAM TROUBLESHOOTING DISCLAIMER: IF YOUR RAM CONFIG IS NOT WORKING ──
+# If models get evicted, Ollama is thrashing, or you hit OOM, consider:
+#
+# Memory Formula:
+#   Memory = Model Weights + (NUM_CTX × KV-Cache) × Models Loaded
+#
+# Dropping the brain model to a 7B is exactly the right lever, and yes it'll cut RAM.
+# But don't just hand-edit NUM_CTX to a smaller number and call it done — memory is 
+# model weights + (NUM_CTX × KV-cache) × models loaded.
+#
+# General rule for all RAM capacities (e.g. moving down from 9B/14B):
+#   1. Inspect pulled tags: `ollama list`
+#   2. Pick a smaller brain: e.g. `qwen2.5:7b` (ollama pull qwen2.5:7b).
+#      Keep the small gate model (qwen2.5-coder:3b) as-is; it's already tiny (~2GB).
+#   3. Set it in slm-gate's .env (the model gate reads only that file). If your coding
+#      tool's MCP config also sets these in an "env" block, change them there too: that
+#      block overrides .env for that tool's MCP server (e.g. Antigravity keeps it in
+#      ~/.gemini/config/mcp_config.json). When your tool starts slm-gate, it checks that
+#      the models named in both places are downloaded.
+#      Example "env" block:
+#        "SLM_BRAIN_MODEL": "qwen2.5:7b",
+#        "SLM_GATE_MODEL": "qwen2.5-coder:3b",
+#        "OLLAMA_MAX_LOADED_MODELS": "2",
+#        "NUM_CTX": "4096"
+#   4. Lower NUM_CTX from 8192 -> 4096: This shrinks the KV-cache directly and is the
+#      single biggest knob after model size.
+#   5. If still heavy: Set OLLAMA_MAX_LOADED_MODELS="1" to force one model in memory
+#      at a time (slower switching between models, but drastically lower RAM).
+#   6. Confirm exact variable names: SLM_BRAIN_MODEL, SLM_GATE_MODEL, NUM_CTX, OLLAMA_MAX_LOADED_MODELS.
+#   7. Sanity-check with doctor: run `pnpm run dev doctor` or `slm-gate doctor`.
+# ───────────────────────────────────────────────────────────────────────────
+
+# How much text the local model can hold at once. Bigger = more RAM used.
+#   16GB->4096  24GB and more->8192 (what slm-gate init picks; src/hardware.ts recommendNumCtx)
+NUM_CTX=8192
+
+# Randomness of the local model. Keep 0 so the same input gives the same result.
+TEMPERATURE=0
+
+# Maximum time (in ms) to wait for a local model response per call.
+# If an SLM call exceeds this limit, it safely fails-open (e.g. returning uncompressed text).
+# Recommended values:
+#   * Fast GPU or small 1.5B-3B models: 30000 (30s)
+#   * 7B-14B models or CPU/unified RAM inference: 120000 (120s)
+SLM_TIMEOUT_MS=120000
+
+# The verifier re-asks the local model this many times to check it's consistent.
+SELF_CONSISTENCY_K=3
+
+# Randomness for those re-asks (must be above 0, or every re-ask is identical).
+SELF_CONSISTENCY_TEMP=0.7
+
+
+# ============================================================
+#  STEP 2 when to trust the local answer vs. use the API model
+# ============================================================
+
+# The "pickiness" ladder (the eval tool sweeps all of these). Keep as-is.
+#   0 = always trust local          3 = + escalate if it hedges ("not sure")
+#   1 = + escalate if empty         4 = + escalate if the re-asks disagree
+#   2 = + escalate if wrong format  5 = always escalate to the API model
+STRICTNESS_LEVELS=0,1,2,3,4,5
+
+# Which level to actually use when running. 4 is a good default.
+HEADLINE_STRICTNESS=4
+
+
+# ============================================================
+#  STEP 3 the API model  (metered, pay-per-token)  — OPTIONAL, most people leave it blank
+#  The model gate does NOT use these: it sends each request on with the coding tool's own
+#  login (your subscription or your API key). These are read only by the benchmark
+#  (`slm-gate bench`), the resolver's optional cloud tier (STEP 6) and SLM_PROVIDER=openai.
+#  (These vars keep the CLOUD_ prefix to match the build playbook they mean the API model.)
+# ============================================================
+
+# Request format of the API provider.  Gemini uses `openai`.
+CLOUD_API_STYLE=openai
+
+# The provider's API URL. Examples:
+#   OpenAI     https://api.openai.com/v1
+#   Anthropic  https://api.anthropic.com
+#   Gemini     https://generativelanguage.googleapis.com/v1beta/openai/
+CLOUD_BASE_URL=
+
+# Your paid API key (this is the metered bill). Put the real value in `.env` only.
+CLOUD_API_KEY=
+
+# Exact model id from the provider.
+#   Gemini 3.1 Pro is `gemini-3.1-pro-preview` (NOT `gemini-3.1-pro`).
+#   List valid ids:  curl -s "https://generativelanguage.googleapis.com/v1beta/models?key=$CLOUD_API_KEY" | jq -r '.models[].name'
+CLOUD_MODEL=
+
+# ── SEMANTIC CACHE ────────────────────────────────────────────────────────
+# Caches the ANSWERS to read-only requests locally and reuses them when a new
+# request is semantically near-identical, so a repeat question costs zero cloud
+# tokens instead of a full round-trip. Unlike prompt caching (which only
+# discounts repeated INPUT), this can skip the cloud call entirely.
+#
+# Safety scope: only read-only / explanatory turns are ever cached. Write
+# actions and anything with side effects are never cached. Each entry is tied to
+# the hash of the files it referenced, so if one of those files changes the entry
+# is invalidated automatically (you won't get a stale answer for edited code).
+#
+# on | off. Default off — it changes behaviour (answers can come from cache), so
+# it's opt-in. Turn it on once you're comfortable it's returning correct results.
+SEMCACHE=off
+
+# How similar a new request must be to a stored one to count as a "hit", measured
+# as cosine similarity between their embeddings (0.0 = unrelated, 1.0 = identical).
+# Trade-off:
+#   Higher (e.g. 0.97-0.99) = stricter: fewer hits, but only near-identical
+#     requests match, so almost no risk of answering the wrong question.
+#   Lower  (e.g. 0.90-0.93) = looser: more hits and more savings, but a subtly
+#     different question can match and get the wrong cached answer.
+# Start at 0.95 and only lower it if you're seeing few hits AND you've confirmed
+# the hits you do get are correct. Valid range 0.0-1.0.
+SEMCACHE_THRESHOLD=0.95
+
+# The local Ollama embedding model used to measure that similarity. It runs
+# on-device and is free (no cloud cost). You must pull it first:
+#     ollama pull nomic-embed-text
+# Note: this defines the "meaning space" for the cache. If you change this model,
+# existing cache entries are no longer comparable and should be cleared, or they
+# simply won't match new requests. Keep it consistent once chosen.
+EMBED_MODEL=nomic-embed-text
+
+
+# ============================================================
+#  STEP 4 ports & connections  (defaults are fine)
+# ============================================================
+
+# Port the model gate (llm-gate) listens on. Your coding tools send their model requests to
+# http://localhost:8787; `slm-gate doctor` prints the exact line for each tool.
+# Port taken by another program? Pick a free one here, run `slm-gate restart`, then run
+# `slm-gate doctor` and paste the new lines into each coding tool.
+# Set it only in this file: a value in a coding tool's MCP "env" block or in your shell is
+# ignored when finding and starting the model gate, so every tool looks in the same place.
+LLM_GATE_PORT=8787
+
+# Start the model gate by itself. When a coding tool starts slm-gate's MCP server, the MCP server
+# also starts the model gate in the background if it is not running, and brings it back within a
+# minute if it stops. It keeps running until you log out or restart, or run `slm-gate stop`.
+#   on (default) | off = you start it yourself with `slm-gate start`.
+# The model gate reads its settings ONLY from this .env file, never from a coding tool's MCP "env"
+# block: one gate serves every tool, so it cannot take settings from whichever tool started it.
+LLM_GATE_AUTOSTART=on
+
+# Shrink large command, search and listing results (tool output) before a request leaves your
+# machine. Each result is shrunk once and the same shorter text is resent every later turn, so
+# the provider's prompt cache keeps working. on (default) | off = send requests unchanged.
+LLM_GATE_DISTILL=on
+
+# Let the local model try to answer the FIRST message of a conversation (not slash commands, not
+# coding tasks that need the tool's tools). If it cannot, or its answer fails the check, the
+# request goes on to your provider as normal. on (default) | off.
+LLM_GATE_LOCAL_FIRST=on
+
+# How long (ms) that first message may wait for a local answer before it goes on to your provider.
+LOCAL_ATTEMPT_BUDGET_MS=6000
+
+# Where the model gate sends each kind of request (optional).
+# You don't need to fill any of these, whether you use a subscription or an API key. Leave all
+# four blank. The gate already knows where each request goes and uses the correct address
+# automatically.
+# The only reason to set one: your company makes all AI traffic go through its own proxy server.
+# Then you would put that proxy's address in the matching line. Everyone else leaves them blank.
+# These four are split by provider, not by subscription vs API. Here is which one each login uses:
+#   UPSTREAM_ANTHROPIC_URL  Claude Pro/Max login in Claude Code, AND an Anthropic API key
+#                           default https://api.anthropic.com
+#   UPSTREAM_OPENAI_URL     OpenAI API key (Codex, Cline and others)
+#                           default https://api.openai.com/v1
+#   UPSTREAM_CHATGPT_URL    ChatGPT login in Codex (subscription)
+#                           default https://chatgpt.com/backend-api/codex
+#   UPSTREAM_GEMINI_URL     Gemini API key only (a Google-account login can't go through the gate)
+#                           default https://generativelanguage.googleapis.com
+# Your coding tool's own login (subscription or API key) is sent either way.
+UPSTREAM_ANTHROPIC_URL=
+UPSTREAM_OPENAI_URL=
+UPSTREAM_CHATGPT_URL=
+UPSTREAM_GEMINI_URL=
+
+# Which tool server (MCP) mcp-gate sits in front of. General setting — works with ANY MCP server.
+#   Not using a tool server    -> leave BLANK (mcp-gate runs standalone: condition_prompt only).
+#   Using tech-lead-stack      -> THIS MUST BE SET (TLS_ADAPTER=on requires it — see STEP 6).
+#        1) build TLS once:  cd /ABS/PATH/ai.tech-lead-stack && pnpm install && pnpm run mcp:build
+#        2) set this to the built file (ONE line, valid JSON):
+#   DOWNSTREAM_MCP={"command":"node","args":["/[...]/[...]/[...]/ai-dev/agent-toolbox/tech-lead-stack/dist/mcp-server.mjs"],"env":{}}
+#   A different MCP server (HTTP) -> {"url":"https://host/mcp","headers":{"Authorization":"Bearer ${TOKEN}"}}
+#   Any file path inside the JSON must be the FULL path on your machine (see LEDGER_PATH below for why).
+#   Ships blank = standalone. Copy the example above onto the line below only if you are proxying a server.
+DOWNSTREAM_MCP=
+
+# How your editor connects to mcp-gate. stdio = normal local setup.
+MCP_GATE_TRANSPORT=stdio
+
+# Only used when MCP_GATE_TRANSPORT=http.
+MCP_GATE_PORT=8788
+
+
+# ============================================================
+#  STEP 5 logs: how you SEE what you saved
+#    Every request is logged locally to a small database (the "ledger"). It records
+#    LOCAL-model calls ($0) and API-model calls (real $). Your SUBSCRIPTION usage is NOT
+#    dollar-tracked here (flat fee) only its token/turn count.
+#    View the ledger either way:
+#      - locally:  sqlite3 ./output/ledger.sqlite "select route,cost_usd,in_tok,out_tok from events;"
+#                  (or run `slm-gate bench` for a summary + chart)
+#      - online:   fill the 3 LANGFUSE_ keys below, then open your project at
+#                  https://cloud.langfuse.com   (same data, with dashboards)
+#    No Langfuse keys = local-only. That's fine.
+# ============================================================
+
+# ── LEDGER_PATH: MUST BE A FULL PATH ON YOUR MACHINE (or blank) ──
+# Where the local log file lives.
+#   Blank (as shipped) -> output/ledger.sqlite inside the folder you installed slm-gate in,
+#                         already resolved to a full path. This is the safe choice.
+#   If you set it     -> use the FULL path from the root of your disk, specific to YOUR machine:
+#                           macOS/Linux: LEDGER_PATH=/Users/yourname/projects/small-language-model-gate/output/ledger.sqlite
+#                           Windows:     LEDGER_PATH=C:\Users\yourname\projects\small-language-model-gate\output\ledger.sqlite
+#                         (run `pwd` inside the repo folder and append /output/ledger.sqlite)
+#   NEVER a path relative to the repo such as ./output/ledger.sqlite.
+# Why: your editor / MCP host launches slm-gate from a working directory that is NOT this repo
+#      (Claude Desktop launches from one that does not exist at all). A relative path is resolved
+#      against that directory and the server dies on startup with
+#      "ENOENT: no such file or directory, mkdir './output'". The same value works from a terminal
+#      inside the repo, which is why it can look fine in `doctor` and still fail in the app.
+#      `doctor` reports an issue for any value that is not a full path.
+# Also: if you run CLI commands (ledger:sync, metrics) from a shell, they read this same .env, so
+#      the MCP server and the CLI always land on the same file. If your host's config `env` block
+#      sets LEDGER_PATH directly, put the same full path there.
+LEDGER_PATH=
+
+# Langfuse dashboards (optional). Fill ALL THREE to turn it on, or leave blank.
+LANGFUSE_PUBLIC_KEY=
+LANGFUSE_SECRET_KEY=
+LANGFUSE_HOST=
+
+# ── PROVIDER ATTRIBUTION ────────────────────────────────────────────────────
+# The cloud provider your IDE sends traffic to. Used for per-provider cycle
+# extension metrics when the inbound request carries no recognizable model
+# string (common on llm-gate when CLOUD_MODEL is unset).
+# This is NOT SLM_PROVIDER (which selects ollama vs openai for the local model).
+# Valid values: gemini, claude, chatgpt. Leave blank to skip attribution.
+PROVIDER=
+
+# ── ⚠️  SUBSCRIPTION WINDOW BUDGETS — REQUIRED FOR THE CYCLE CARDS ──
+# Paid AI plans give you an allowance that refreshes on a timer called a "usage
+# window" (Claude and Gemini: every 5 hours, ChatGPT: every 3 hours). Each
+# provider gets two dashboard cards showing how much of that window the gate
+# frees up: "Est. Seconds Saved (per prompt)" and "Est. Minutes Saved (total)".
+#
+# SET ALL THREE, even if you only use one provider. If a budget is blank, both
+# of that provider's cards stay EMPTY (show 0). The gate can't find out your
+# plan's limit on its own, so without a budget it reports nothing rather than
+# guess.
+#
+#   estimated minutes saved per event = units saved × (window minutes ÷ WINDOW_BUDGET)
+#
+# What a "unit" is depends on how the provider counts usage:
+#   CLAUDE / GEMINI   → TOKENS per window. Every token saved counts, including
+#                       tool results shrunk by the slm-gate MCP server.
+#   CHATGPT           → MESSAGES per window. ChatGPT caps messages, so only a
+#                       prompt answered fully by the local model saves one. A
+#                       shrunk prompt still costs one message and adds 0 minutes.
+#
+# ⚠️  THESE ARE ESTIMATES, WITHIN A MARGIN OF ERROR. Anthropic, OpenAI and Google
+# do not publish these limits (only multipliers such as "Max 5x = 5x Pro"), so the
+# minutes shown are estimates too. Pick the value for your plan:
+#   Claude  (tokens/5h)  : Pro ~460000 · Max 5x ~2300000 · Max 20x ~9200000
+#                          (Max 5x measured 2026-09-16 from Claude Code usage logs
+#                           against the /usage session meter; Pro and 20x scaled)
+#   ChatGPT (messages/3h): Plus ~160 (third-party reports, 2026)
+#   Gemini  (tokens/5h)  : AI Pro ~500000 · Ultra ~10000000
+#                          (best guess: AI Pro assumed close to Claude Pro;
+#                           Ultra = 20x AI Pro per Google's plan page)
+# A better number for YOUR account: tokens sent in a window ÷ share of the window
+# used (Claude Code shows the share with /usage). Restart the gate / MCP server
+# after changing these; they are read once at startup. (Most plans also have a
+# weekly cap; this metric only models the short refresh window.)
+CLAUDE_WINDOW_BUDGET=2300000   # tokens per 5-hour window (Claude Max 5x, estimate)
+CHATGPT_WINDOW_BUDGET=160      # messages per 3-hour window (ChatGPT Plus, estimate)
+GEMINI_WINDOW_BUDGET=10000000  # tokens per 5-hour window (Gemini Ultra, estimate)
+
+# ── SUBSCRIPTION PLAN (window length) ───────────────────────────────────────
+# Rather than setting individual window minutes overrides, you can set a single
+# SUBSCRIPTION_PLAN. It sets the window LENGTH only. It does NOT set the window
+# budgets above; those must be set separately.
+#
+# Valid values: claude-pro, claude-max-5x, claude-max-20x, chatgpt-go,
+#               chatgpt-plus, chatgpt-pro-5x, chatgpt-pro-20x, gemini-plus,
+#               gemini-pro, gemini-ultra.
+#
+# Sources (verified 2026-09-09; claude link updated 2026-09-16):
+#   claude  : https://support.claude.com/en/articles/11049741-what-is-the-max-plan
+#   chatgpt : https://help.openai.com          (search "ChatGPT usage limits")
+#   gemini  : https://support.google.com/gemini/answer/16275805
+SUBSCRIPTION_PLAN=claude-max-5x
+
+# ============================================================
+#  STEP 6 optional extras
+# ============================================================
+
+# Let mcp-gate make an EXTRA call to the API MODEL (STEP 3) to clear up an unclear request.
+#   This spends metered, per-token API dollars SEPARATE from (on top of) your subscription
+#   and each call is logged in the ledger. Needs STEP 3 filled. off = never (default).
+RESOLVER_CLOUD_TIER=off
+
+# Cap on total API dollars for the setting above. 0 = never spend.
+RESOLVER_CLOUD_BUDGET_USD=0
+
+# Bump this string (v1 -> v2 ...) whenever you change the prompt logic, to clear the cache.
+# It is part of both cache keys (prompt conditioning and tool-output distillation), so changing
+# it invalidates every previously cached result. Bump it after you change prompts, swap either
+# SLM model, or pull a version of slm-gate whose release notes say to.
+PROMPT_VERSION=v1
+
+# Shortcut that picks default models for your RAM. Your explicit SLM_*_MODEL above win.
+#   ram-16 | ram-24 | ram-32 | ram-48 | ram-64 | ram-128 | custom
+#   slm-gate init picks it from your RAM: a size between two presets gets the smaller one, and more than
+#   128 GB gets custom. Models per preset: https://github.com/zenithfoundry/slm-gate/blob/main/docs/prerequisites-and-hardware.md
+#   To choose other models that fit your computer: https://github.com/AlexsJones/llmfit
+RAM_PRESET=ram-24
+
+# tech-lead-stack integration. Adds TLS-specific handling (preserves TLS's skill gates, feeds
+# TLS's own cost report). It ONLY does anything when mcp-gate is proxying TLS.
+#   RULE: if this is `on`, DOWNSTREAM_MCP (STEP 4) MUST point at the TLS server.
+#         `on` + blank DOWNSTREAM_MCP is invalid — there is nothing for the adapter to attach to.
+#   Not using tech-lead-stack -> off.
+TLS_ADAPTER=on
+
+# ── PROTECTING CRITICAL TEXT: which lines the local model must NEVER summarize ──
+# When the proxy shrinks a large result (like a long log or a big file), it automatically
+# recognizes and protects structured information like Markdown tables, code blocks,
+# and headers from being summarized or deleted.
+#
+# However, you might want to protect specific sentences or keywords from ever being 
+# summarized. For example, you might want to protect any line containing the word "DEADLINE".
+# The built-in defaults already protect common critical words like MUST, SHALL, and URLs.
+
+# Optional: You can provide a custom JSON file that lists extra text patterns you want to protect.
+#   Format of the file:  { "mode": "extend", "patterns": ["^## Acceptance Criteria", "\\bDEADLINE\\b"] }
+#   Why a separate file?: We require you to put these rules in a separate file rather than 
+#   typing them directly here. This prevents confusing formatting errors and keeps this file clean.
+#   Example: "configs/preserve/tls.json" is used for the tech-lead-stack framework. You can 
+#   change this path to point to any custom JSON file you create.
+#   Leave this blank if you only want to use the built-in defaults.
+DISTILL_PRESERVE_PATH=
+
+# How should your custom patterns combine with the built-in defaults?
+#   extend  = Your custom patterns are ADDED to our built-in defaults (recommended).
+#   replace = ONLY your custom patterns are used — the built-in defaults are completely ignored.
+DISTILL_PRESERVE_MODE=extend
+
+# Turn off summarization entirely for known "skill" or instruction files.
+#   Why: Summarizing a file that contains strict rules (like "never push code without asking") 
+#        might accidentally cause the local model to forget or change those rules.
+#   Tradeoff: Turning this off guarantees your rules are kept 100% untouched, but 
+#             it will use up more of your context window if the instruction file is very large.
+#   Default: off (this means summarization is disabled for skill files)
+DISTILL_SKILLS=off
+
+# ── SMART MEMORY: The Adaptive Semantic Feedback Loop ──────────────────────
+# The proxy learns from your actions! If the local model summarizes a text and you 
+# subsequently ask the agent to "read the hidden lines", the proxy memorizes the meaning 
+# of those missing lines. 
+# In the future, if the proxy sees a line that means the exact same thing as something 
+# you previously had to uncover, it will PREEMPTIVELY protect it from being summarized!
+
+# Turn this smart memory learning on/off. 
+#   off = Rely only on the automatic structure and text pattern rules above.
+#   on  = Actively compare new text against the memory of your past expansions.
+DISTILL_ADAPTIVE=on
+
+# How similar does a new line need to be to your past expansions to trigger protection?
+#   0.86 = Very similar meaning (recommended default). 
+#   Higher (e.g., 0.95) = Stricter. Protects only near-exact matches.
+#   Lower (e.g., 0.75)  = Looser. Protects lines that share a similar theme or topic.
+DISTILL_ADAPTIVE_THRESHOLD=0.86
+
+# To prevent this smart memory from slowing down your computer by checking every single line, 
+# we only check a random percentage of the unprotected lines against the memory database.
+#   0.15 = 15% of unprotected lines are checked against memory.
+DISTILL_ADAPTIVE_EXPLORE_RATE=0.15
+
+# ── SUMMARIZATION LIMITS & SIZES ───────────────────────────────────────────
+# When a tool returns a massive amount of text (like a massive log file), the proxy shrinks
+# it using the local model BEFORE it reaches your editor. This ensures you don't waste your
+# expensive cloud tokens on useless text. The original, full text is secretly saved locally 
+# so your agent can cheaply recover anything that was trimmed if it needs it later.
+#
+# A quick guide to "tokens": roughly 4 characters is 1 token. 
+# As a rule of thumb, 1,000 tokens is about 750 words or 100 lines of code.
+
+# MAXIMUM LIMIT. The largest size a SINGLE tool result is allowed to be AFTER shrinking. 
+# This is a safety net to stop massive text dumps from crashing your context window.
+# If a result is still larger than this number after being shrunk, the extra text is cut off 
+# entirely and replaced with a marker the agent can use to expand it on demand.
+#   Lower it = saves more tokens (but causes more "expand" requests).
+#   Raise it = keeps more context visible at once (but costs more tokens).
+# NOTE: this is also the point at which the local model is asked to summarize at all. In
+# STANDALONE mode (DOWNSTREAM_MCP blank) it is the ONLY trigger, because the deterministic
+# per-tool heuristics need a tool name that standalone calls do not carry. Shipping 8000 here
+# meant nothing under ~28,000 characters was ever compressed. Matches the code default.
+DISTILL_MAX_TOKENS=2000
+
+# MINIMUM LIMIT. Any tool result SMALLER than this number is ignored and left completely untouched.
+# Compressing tiny outputs is a waste of time and risks changing important small details 
+# (like mangling a single filename) to save almost nothing.
+#   Lower it = shrinks more aggressively.
+#   Raise it = leaves more small results alone.
+# Matches the code default and the README. (Both thresholds previously diverged from both.)
+DISTILL_MIN_TOKENS=500
+
+# How long (ms) the model gate may hold one request while it shrinks that request's new tool
+# results. Past it, the result is sent as it was (and stays that way for the rest of the
+# conversation, so the provider's prompt cache keeps working). The request is never blocked.
+DISTILL_BUDGET_MS=3000
+
+# The proxy always keeps the last few tool results completely FULL and un-shrunk, because
+# whatever the agent just fetched is almost certainly still needed for its very next step. 
+# Only OLDER tool results become candidates for shrinking.
+#   Higher = safer (keeps your immediate history completely intact) but uses more context window.
+KEEP_RECENT_TOOL_TURNS=4
+
+# ── Elision registry (the "get it back cheaply" safety net) ────────────────
+# Whenever the gate shrinks or drops a tool result, it stashes the ORIGINAL in a
+# small local SQLite table so the agent can retrieve exactly what was trimmed
+# without re-running the tool or re-reading the whole file. These three settings
+# bound that stash. (It only ever holds trimmed tool outputs — never your cost or
+# analytics data.)
+
+# Max number of stashed originals to keep. Past this, the oldest are deleted.
+#   Higher = more originals available for cheap re-fetch (more disk used); lower =
+#   less disk, but re-fetching an evicted original falls back to re-running the
+#   original tool.
+ELISION_MAX_ENTRIES=5000
+
+# How long a stashed original is kept before automatic deletion. Old ones are
+# removed on startup and when next looked up.
+#   180 = ~6 months. In practice a stashed original is almost always re-fetched
+#   within minutes, so this is deliberately generous — the size cap below usually
+#   kicks in first. Lower it (e.g. 30) if you'd rather rely mainly on the size cap.
+ELISION_RETENTION_DAYS=180
+
+# Disk budget for the stash, in megabytes. When exceeded, the least-recently-used
+# originals are deleted first. This is usually the limit that actually bites (it
+# triggers before the 6-month age above).
+ELISION_MAX_MB=500
+
+# ── DYNAMIC ROUTING TUNING ─────────────────────────────────────────────────
+# The gate can answer a request two ways: the FREE local model, or the PAID cloud
+# model. It tries local first, a verifier checks the answer, and it falls back to
+# cloud only if the local answer isn't good enough. These settings let the gate
+# LEARN which KINDS of requests the local model is actually good at, so it stops
+# wasting local attempts on kinds it usually fails and sends those straight to
+# cloud. (Categories that improve still get re-tested — see the explore rate.)
+
+# Turn the adaptive learning on/off. off = always try local first, regardless of
+# past results. on = skip local for categories the local model has been failing.
+ROUTING_TUNE=off
+
+# How many recent requests (per category) to look back over when measuring the
+# local model's success rate.
+#   Larger = a smoother, slower-to-change picture; smaller = adapts faster but is
+#   noisier (a couple of flukes swing it more).
+ROUTING_TUNE_WINDOW=20
+
+# The minimum number of past requests needed for a category before the gate is
+# allowed to act on that category's success rate. Stops it from deciding "local
+# is bad at this" off one or two data points.
+ROUTING_TUNE_MIN_SAMPLES=8
+
+# The local success rate BELOW which the gate stops trying local for a category
+# and escalates straight to cloud.
+#   0.5 = if the local model succeeds less than half the time for this kind of
+#   request, skip it and go to cloud. Higher (e.g. 0.7) = stricter, escalates more
+#   to cloud (more reliable, costs more); lower (e.g. 0.3) = keeps trying local
+#   (cheaper, but more failed local attempts that then escalate).
+ROUTING_TUNE_THRESHOLD=0.5
+
+# Even for categories it has learned to skip, the gate deliberately tries local
+# this fraction of the time, to keep learning (a category might have improved, or
+# was judged on stale data). This is the classic "explore vs exploit" knob.
+#   0.15 = explore ~15% of the time. Higher = adapts faster but runs more risky
+#   trials; lower = more conservative, adapts more slowly.
+ROUTING_TUNE_EXPLORE_RATE=0.15
+
+# ============================================================
+#  STEP 7 downstream multi-agent configuration (OPTIONAL)
+# ============================================================
+#
+# These variables configure the agents in downstream orchestration 
+# frameworks (like tech-lead-stack). 
+# If you are not using a multi-agent framework or prefer to use 
+# its defaults, leave these entirely BLANK.
+
+# The reasoning-heavy model used for architecture and planning.
+# MODEL_PLANNER=claude-opus-4-6
+
+# The fast, high-context model used for writing code.
+# MODEL_IMPLEMENTER=gemini-3.5-flash
+
+# The high-precision model used for reviewing and grading plans.
+# MODEL_AUDITOR=claude-sonnet-4-6
+
+# The model used for final decisions in cross-model verification.
+# MODEL_ADJUDICATOR=claude-sonnet-4-6
+
+# Downstream API Keys (if different from CLOUD_API_KEY in STEP 3)
+# ANTHROPIC_API_KEY=sk-ant-...
+# GEMINI_API_KEY=...