{
  "schema": 1,
  "generated_by": "scripts/build_site.py",
  "base_url": "https://millivolt.llm4people.dev/",
  "version": "0.4.24",
  "pages": [
    {
      "path": "docs/README.md",
      "slug": "docs/index",
      "output": "docs/index.html",
      "markdown": "docs/index.md",
      "url": "https://millivolt.llm4people.dev/docs/index.html",
      "markdown_url": "https://millivolt.llm4people.dev/docs/index.md",
      "title": "Documentation",
      "description": "millivolt is one self-hosted service for routing model traffic across OpenAI Chat Completions, OpenAI Responses and Anthropic Messages, seeing what...",
      "group": "Start",
      "order": 0,
      "bytes": 3680,
      "sha256": "1ad8758bd008ea2189ba8ceb8647da514a12bfbbbe4bade0b5b033eb332ecec4",
      "sections": [
        {
          "heading": "First ten minutes",
          "id": "first-ten-minutes",
          "text": "Install and first run from Compose or a source checkout. Send one request on a client protocol and find it in the dashboard ; the capture gallery shows every surface in both themes. Read configuration before changing the example or a setting. Read security before exposing the listener. Keep operations nearby for health, storage and the known limits.",
          "context": ""
        },
        {
          "heading": "If you want to ...",
          "id": "if-you-want-to-",
          "text": "Task Start with Install and send a first request Install and first run Configure a setting, request override or provider alias Configuration Look up a setting's default or a CLI flag Settings reference See every dashboard surface on both themes Capture gallery Expose the listener behind TLS or a network boundary Reverse proxy , security Debug a 429 or a 5xx Routes and debugging , pause and limits Back up or restore Settings backup and restore , image-only backup , online database backup Upgrade or restart Versions and images , reload, restart and shutdown Integrate a client or translate between protocols Protocol , adapters Drive the operator plane from an LLM MCP server Read or search the docs from an LLM llms.txt , docs.json , MCP server Drive it from a terminal Operator CLI Contribute a change Contributing , architecture , support The operations overview owns health, storage and the runtime cost model. Measurements live in performance ; ownership and invariants live in architecture . Project pages are support , releases , license and third-party notices .",
          "context": ""
        },
        {
          "heading": "Verification and limitations",
          "id": "verification-and-limitations",
          "text": "The generated settings reference lists every setting and proxy flag with its type, default, accepted values and reload behavior. Every page also has a Markdown twin, and llms.txt , llms-full.txt and docs.json index the same sources for an LLM or the docs_list , docs_search and docs_read MCP tools. proxy.example.yaml is the commented deployment example. internal/config owns defaults, validation and Settings metadata; local proxy.yaml is not a public reference or a test fixture. Current commands live in Contributing . Runtime limits live in operations ; measurement caveats live in performance . The architecture map connects invariants to their shared implementation and regression coverage. Past development notes are not an operating guide or a capacity guarantee.",
          "context": ""
        }
      ],
      "markdown_text": "# Documentation\n\nmillivolt is one self-hosted service for routing model traffic across OpenAI\nChat Completions, OpenAI Responses and Anthropic Messages, seeing what happened,\nand controlling the operator surface. Start with the path\nthat matches what you need to do.\n\n## First ten minutes\n\n1. [Install and first run](install.md) from Compose or a source checkout.\n2. Send one request on a client protocol and find it in the\n   [dashboard](dashboard.md); the [capture gallery](gallery.md) shows every\n   surface in both themes.\n3. Read [configuration](configuration.md) before changing the example or a\n   setting.\n4. Read [security](../SECURITY.md) before exposing the listener.\n5. Keep [operations](operations.md) nearby for health, storage and the known\n   limits.\n\n## If you want to ...\n\n| Task | Start with |\n| --- | --- |\n| Install and send a first request | [Install and first run](install.md) |\n| Configure a setting, request override or provider alias | [Configuration](configuration.md) |\n| Look up a setting's default or a CLI flag | [Settings reference](settings.md) |\n| See every dashboard surface on both themes | [Capture gallery](gallery.md) |\n| Expose the listener behind TLS or a network boundary | [Reverse proxy](reverse-proxy.md), [security](../SECURITY.md) |\n| Debug a 429 or a 5xx | [Routes and debugging](routes.md#error-storm-protection), [pause and limits](routes.md#pause-and-limits) |\n| Back up or restore | [Settings backup and restore](containers.md#settings-backup-and-restore), [image-only backup](containers.md#image-only-backup-and-restore), [online database backup](operations.md#storage-and-accounting) |\n| Upgrade or restart | [Versions and images](containers.md#versions-and-images), [reload, restart and shutdown](containers.md#reload-restart-and-shutdown) |\n| Integrate a client or translate between protocols | [Protocol](protocol.md), [adapters](adapters.md) |\n| Drive the operator plane from an LLM | [MCP server](mcp.md) |\n| Read or search the docs from an LLM | [llms.txt](https://millivolt.llm4people.dev/llms.txt), [docs.json](https://millivolt.llm4people.dev/docs.json), [MCP server](mcp.md#tools) |\n| Drive it from a terminal | [Operator CLI](cli.md) |\n| Contribute a change | [Contributing](../CONTRIBUTING.md), [architecture](architecture.md), [support](../SUPPORT.md) |\n\nThe [operations overview](operations.md) owns health, storage and the runtime\ncost model. Measurements live in [performance](performance.md); ownership and\ninvariants live in [architecture](architecture.md). Project pages are\n[support](../SUPPORT.md), [releases](https://github.com/LLM-4-People/millivolt/releases),\n[license](../LICENSE) and [third-party notices](../THIRD_PARTY_NOTICES.md).\n\n## Verification and limitations\n\nThe generated [settings reference](settings.md) lists every setting and proxy\nflag with its type, default, accepted values and reload behavior. Every page\nalso has a Markdown twin, and `llms.txt`, `llms-full.txt` and `docs.json` index\nthe same sources for an LLM or the `docs_list`, `docs_search` and `docs_read`\nMCP tools.\n[proxy.example.yaml](../proxy.example.yaml) is the commented deployment example.\n`internal/config` owns defaults, validation and Settings metadata; local\n`proxy.yaml` is not a public reference or a test fixture.\n\nCurrent commands live in [Contributing](../CONTRIBUTING.md#checks). Runtime\nlimits live in [operations](operations.md#known-limits); measurement caveats\nlive in [performance](performance.md#limitations). The\n[architecture map](architecture.md) connects invariants to their shared\nimplementation and regression coverage. Past development notes are not an\noperating guide or a capacity guarantee.\n"
    },
    {
      "path": "docs/install.md",
      "slug": "docs/install",
      "output": "docs/install.html",
      "markdown": "docs/install.md",
      "url": "https://millivolt.llm4people.dev/docs/install.html",
      "markdown_url": "https://millivolt.llm4people.dev/docs/install.md",
      "title": "Install and first run",
      "description": "Install millivolt from the published image or a source checkout, set the operator credential, and send a first request on each client protocol. The...",
      "group": "Start",
      "order": 1,
      "bytes": 6523,
      "sha256": "0d63318d062196e6217c8d8b39ad8b46ef9d26aa1fd321dbf2bffe286517c032",
      "sections": [
        {
          "heading": "Before you start",
          "id": "before-you-start",
          "text": "The container path needs Linux with Docker Engine and the Compose plugin. No Go, Node or source checkout is needed for it. The source path needs the Go toolchain required by go.mod . Important One shared operator credential protects the dashboard and operator plane only. Inference is transparent: it forwards your upstream key and does not use the operator token. There are no user accounts. Keep the listener on loopback, or put the network or ingress boundary in front. With the token unset, the dashboard denies every request. Read Security before network exposure.",
          "context": ""
        },
        {
          "heading": "Install with Docker Compose",
          "id": "install-with-docker-compose",
          "text": "curl -fsSL https://raw.githubusercontent.com/LLM-4-People/millivolt/main/compose.yaml -o compose.yaml export MILLIVOLT_OPERATOR_TOKEN='replace-with-a-long-random-value' docker compose up -d Open http://127.0.0.1:8080/ and sign in with that token. If the container exits, run docker compose logs --tail 50 . The Compose file publishes on loopback only. It keeps history and settings in named volumes, runs non-root with a read-only root filesystem, and accepts MILLIVOLT_PORT for an unused host port. For bind mounts, pre-create directories writable by UID/GID 65532:65532 ; see persistent state . For image selection, backups, updates, shutdown, or protected ingress, see container operation and the reverse-proxy guide . The published image is ghcr.io/llm-4-people/millivolt:main for amd64 and arm64. Version tags identify releases; pin a digest when exact bytes matter. See versions and images .",
          "context": ""
        },
        {
          "heading": "Install from a source checkout",
          "id": "install-from-a-source-checkout",
          "text": "Install the Go toolchain required by go.mod , then: git clone https://github.com/LLM-4-People/millivolt.git cd millivolt test -e proxy.yaml || cp proxy.example.yaml proxy.yaml export MILLIVOLT_OPERATOR_TOKEN='replace-with-a-long-random-value' go run ./cmd/proxy -config proxy.yaml -listen 127.0.0.1:8080 For isolated development and checks, see Contributing .",
          "context": ""
        },
        {
          "heading": "Environment and defaults",
          "id": "environment-and-defaults",
          "text": "The Compose inputs are environment variables; their defaults live in compose.yaml , not server configuration. Supply them consistently through the environment or an ignored local .env file. Variable Meaning MILLIVOLT_OPERATOR_TOKEN The single operator credential. It is read once at boot from the process environment and never from proxy.yaml , so rotating it requires a real process restart. A nonempty value shorter than 16 or longer than 512 bytes fails the boot. Unset or empty leaves the dashboard denied. MILLIVOLT_IMAGE Image reference; defaults to ghcr.io/llm-4-people/millivolt:main . MILLIVOLT_PORT Loopback host port; default 8080 . MILLIVOLT_STOP_GRACE_PERIOD Container stop grace; default 30s . MILLIVOLT_MEM_LIMIT Container memory ceiling; default 1g . MILLIVOLT_PIDS_LIMIT Process and thread ceiling; default 512 . docker compose config shows the resolved deployment. A source deployment configures the same service through -config PATH (default local proxy.yaml ), -listen ADDRESS and -db-path PATH ; the generated example and the Settings schema are the field reference. See configuration .",
          "context": ""
        },
        {
          "heading": "Send a first request",
          "id": "send-a-first-request",
          "text": "Point a client at the proxy and supply the upstream base URL and key on each request. The proxy registers no providers or keys. X-Proxy-Format selects a different upstream protocol; absent, the request passes through. See protocol and adapters . OpenAI Chat Completions: curl -sS http://127.0.0.1:8080/v1/chat/completions \\ -H \"X-Proxy-Base-URL: $UPSTREAM_BASE_URL\" \\ -H \"Authorization: Bearer $UPSTREAM_API_KEY\" \\ -H 'Content-Type: application/json' \\ -d \"{\\\"model\\\":\\\"$UPSTREAM_MODEL\\\",\\\"messages\\\":[{\\\"role\\\":\\\"user\\\",\\\"content\\\":\\\"hello\\\"}]}\" OpenAI Responses: curl -sS http://127.0.0.1:8080/v1/responses \\ -H \"X-Proxy-Base-URL: $UPSTREAM_BASE_URL\" \\ -H \"Authorization: Bearer $UPSTREAM_API_KEY\" \\ -H 'Content-Type: application/json' \\ -d \"{\\\"model\\\":\\\"$UPSTREAM_MODEL\\\",\\\"input\\\":\\\"hello\\\"}\" Anthropic Messages, using the native upstream's own auth header, prefix and API version: curl -sS http://127.0.0.1:8080/v1/messages \\ -H \"X-Proxy-Base-URL: $UPSTREAM_BASE_URL\" \\ -H \"X-Proxy-Key: $UPSTREAM_API_KEY\" \\ -H 'X-Proxy-Auth-Header: x-api-key' \\ -H 'X-Proxy-Auth-Prefix;' \\ -H \"anthropic-version: $ANTHROPIC_VERSION\" \\ -H 'Content-Type: application/json' \\ -d \"{\\\"model\\\":\\\"$UPSTREAM_MODEL\\\",\\\"m",
          "context": ""
        },
        {
          "heading": "The dashboard",
          "id": "the-dashboard",
          "text": "The dashboard is the site root, http://127.0.0.1:8080/ . It asks for the operator token once per browser tab, keeps it in sessionStorage, attaches it to gated calls only and drops it as soon as the server rejects it. The same credential gates /metrics/* , /admin/* and /mcp ; transparent inference does not use it. See operator access for the canonical open-path list.",
          "context": ""
        },
        {
          "heading": "What to read next",
          "id": "what-to-read-next",
          "text": "Documentation routes by task. For the next step, read configuration before changing settings, or the dashboard tour to find the request you just sent.",
          "context": ""
        }
      ],
      "markdown_text": "# Install and first run\n\nInstall millivolt from the published image or a source checkout, set the\noperator credential, and send a first request on each client protocol. The\n[quickstart](../README.md#quickstart) is the short form of the same procedure;\nthis page carries the full path.\n\n## Before you start\n\nThe container path needs Linux with Docker Engine and the Compose plugin. No Go,\nNode or source checkout is needed for it. The source path needs the Go toolchain\nrequired by [go.mod](../go.mod).\n\n> [!IMPORTANT]\n> One shared operator credential protects the dashboard and operator plane only.\n> Inference is transparent: it forwards your upstream key and does not use the\n> operator token. There are no user accounts. Keep the listener on loopback, or\n> put the network or ingress boundary in front. With the token unset, the\n> dashboard denies every request. Read [Security](../SECURITY.md) before network\n> exposure.\n\n## Install with Docker Compose\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/LLM-4-People/millivolt/main/compose.yaml -o compose.yaml\nexport MILLIVOLT_OPERATOR_TOKEN='replace-with-a-long-random-value'\ndocker compose up -d\n```\n\nOpen [http://127.0.0.1:8080/](http://127.0.0.1:8080/) and sign in with that\ntoken. If the container exits, run `docker compose logs --tail 50`.\n\nThe Compose file publishes on loopback only. It keeps history and settings in\nnamed volumes, runs non-root with a read-only root filesystem, and accepts\n`MILLIVOLT_PORT` for an unused host port. For bind mounts, pre-create\ndirectories writable by UID/GID `65532:65532`; see\n[persistent state](containers.md#persistent-state-and-configuration). For image\nselection, backups, updates, shutdown, or protected ingress, see\n[container operation](containers.md#containers) and the\n[reverse-proxy guide](reverse-proxy.md).\n\nThe published image is `ghcr.io/llm-4-people/millivolt:main` for amd64 and\narm64. Version tags identify releases; pin a digest when exact bytes matter. See\n[versions and images](containers.md#versions-and-images).\n\n## Install from a source checkout\n\nInstall the Go toolchain required by [go.mod](../go.mod), then:\n\n```sh\ngit clone https://github.com/LLM-4-People/millivolt.git\ncd millivolt\ntest -e proxy.yaml || cp proxy.example.yaml proxy.yaml\nexport MILLIVOLT_OPERATOR_TOKEN='replace-with-a-long-random-value'\ngo run ./cmd/proxy -config proxy.yaml -listen 127.0.0.1:8080\n```\n\nFor isolated development and checks, see [Contributing](../CONTRIBUTING.md).\n\n## Environment and defaults\n\nThe Compose inputs are environment variables; their defaults live in\n[compose.yaml](../compose.yaml), not server configuration. Supply them\nconsistently through the environment or an ignored local `.env` file.\n\n| Variable | Meaning |\n| --- | --- |\n| `MILLIVOLT_OPERATOR_TOKEN` | The single operator credential. It is read once at boot from the process environment and never from `proxy.yaml`, so rotating it requires a real process restart. A nonempty value shorter than 16 or longer than 512 bytes fails the boot. Unset or empty leaves the dashboard denied. |\n| `MILLIVOLT_IMAGE` | Image reference; defaults to `ghcr.io/llm-4-people/millivolt:main`. |\n| `MILLIVOLT_PORT` | Loopback host port; default `8080`. |\n| `MILLIVOLT_STOP_GRACE_PERIOD` | Container stop grace; default `30s`. |\n| `MILLIVOLT_MEM_LIMIT` | Container memory ceiling; default `1g`. |\n| `MILLIVOLT_PIDS_LIMIT` | Process and thread ceiling; default `512`. |\n\n`docker compose config` shows the resolved deployment. A source deployment\nconfigures the same service through `-config PATH` (default local `proxy.yaml`),\n`-listen ADDRESS` and `-db-path PATH`; the generated example and the Settings\nschema are the field reference. See [configuration](configuration.md).\n\n## Send a first request\n\nPoint a client at the proxy and supply the upstream base URL and key on each\nrequest. The proxy registers no providers or keys. `X-Proxy-Format` selects a\ndifferent upstream protocol; absent, the request passes through. See\n[protocol](protocol.md) and [adapters](adapters.md).\n\nOpenAI Chat Completions:\n\n```sh\ncurl -sS http://127.0.0.1:8080/v1/chat/completions \\\n  -H \"X-Proxy-Base-URL: $UPSTREAM_BASE_URL\" \\\n  -H \"Authorization: Bearer $UPSTREAM_API_KEY\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"{\\\"model\\\":\\\"$UPSTREAM_MODEL\\\",\\\"messages\\\":[{\\\"role\\\":\\\"user\\\",\\\"content\\\":\\\"hello\\\"}]}\"\n```\n\nOpenAI Responses:\n\n```sh\ncurl -sS http://127.0.0.1:8080/v1/responses \\\n  -H \"X-Proxy-Base-URL: $UPSTREAM_BASE_URL\" \\\n  -H \"Authorization: Bearer $UPSTREAM_API_KEY\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"{\\\"model\\\":\\\"$UPSTREAM_MODEL\\\",\\\"input\\\":\\\"hello\\\"}\"\n```\n\nAnthropic Messages, using the native upstream's own auth header, prefix and API\nversion:\n\n```sh\ncurl -sS http://127.0.0.1:8080/v1/messages \\\n  -H \"X-Proxy-Base-URL: $UPSTREAM_BASE_URL\" \\\n  -H \"X-Proxy-Key: $UPSTREAM_API_KEY\" \\\n  -H 'X-Proxy-Auth-Header: x-api-key' \\\n  -H 'X-Proxy-Auth-Prefix;' \\\n  -H \"anthropic-version: $ANTHROPIC_VERSION\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"{\\\"model\\\":\\\"$UPSTREAM_MODEL\\\",\\\"max_tokens\\\":1024,\\\"messages\\\":[{\\\"role\\\":\\\"user\\\",\\\"content\\\":\\\"hello\\\"}]}\"\n```\n\nThe semicolon in `-H 'X-Proxy-Auth-Prefix;'` is important: curl sends a present\nempty header. `-H 'X-Proxy-Auth-Prefix:'` instead omits it, leaving the proxy's\n`Bearer ` default. A response means the proxy answered; check the status code\nfor the upstream outcome. The request appears in the dashboard.\n\nOn a shared Compose network, use `http://millivolt:8080/v1` instead of loopback.\n`/v1/chat/completions`, `/v1/responses` and `/v1/messages` are all available.\nEach can reach Chat, Responses or Anthropic upstreams; only a Chat client can\ntarget the Cursor bridge. Read\n[upstream compatibility](adapters.md#client-and-upstream-compatibility) and\n[cross-protocol translation](adapters.md#cross-protocol-translation).\n\n## The dashboard\n\nThe dashboard is the site root, [http://127.0.0.1:8080/](http://127.0.0.1:8080/).\nIt asks for the operator token once per browser tab, keeps it in sessionStorage,\nattaches it to gated calls only and drops it as soon as the server rejects it.\nThe same credential gates `/metrics/*`, `/admin/*` and `/mcp`; transparent\ninference does not use it. See [operator access](routes.md#operator-access) for\nthe canonical open-path list.\n\n## What to read next\n\n[Documentation](README.md) routes by task. For the next step, read\n[configuration](configuration.md) before changing settings, or\n[the dashboard tour](dashboard.md) to find the request you just sent.\n"
    },
    {
      "path": "docs/dashboard.md",
      "slug": "docs/dashboard",
      "output": "docs/dashboard.html",
      "markdown": "docs/dashboard.md",
      "url": "https://millivolt.llm4people.dev/docs/dashboard.html",
      "markdown_url": "https://millivolt.llm4people.dev/docs/dashboard.md",
      "title": "Dashboard guide",
      "description": "The plate below is the complete dashboard. Use this guide to follow its charts, explorer, request drawer, operator console and Settings without hunting...",
      "group": "Start",
      "order": 2,
      "bytes": 38310,
      "sha256": "027e77df5b3a9c2dad811275f9b57ccf160e339693cad39e1d8db1063b043e33",
      "sections": [
        {
          "heading": "Error storm banner",
          "id": "error-storm-banner",
          "text": "When enabled in Settings, error storm protection adds a live banner below the header. Click an incident to inspect the number of requests with selected errors, failed upstream attempts, error category, queued requests, next retry time and recovery progress. It names the affected provider or exact provider/model, shows its safe error category, failed upstream-attempt percentage and window, queue count and recovery probe state. Provider incidents require all models active in the same window to have elevated errors. The banner shows that active-model evidence; its attempt percentage differs from the Errors chart's affected-request rate. It clears when protection recovers and can be hidden independently in Settings. See configuration and behavior . The static captures below show no banner because the capture session has no active incident; the banner stays hidden until protection fires.",
          "context": ""
        },
        {
          "heading": "Timelines",
          "id": "timelines",
          "text": "The KPI band remains global. Explorer filters scope the timeline and request log together. The timeframe control in the card head changes chart history, not the global KPI band. It offers a zoom ladder from one minute through one year plus All time , and the calendar presets today, yesterday, this week and this month. Its panel draws the stored coverage as a rail and disables any window wider than the stored history, so a selection can never promise more history than exists; All time means exactly the retained history, and a calendar preset clamps its start to the oldest stored request. The selection persists per browser. Legend controls show or hide individual series; hover a bucket for its precise values and time interval. Counts, sums and percentiles come from the server. A window with fewer than four plotted points paints a waiting message instead of the chart: one to three buckets are too few to read a trend, and the totals strip still tells the story until a fourth point arrives. A span with no stored history says so; a span inside history with no requests says that instead. 09 The window picker timelines · chart · window picker split · black / clear full size Windows wider t",
          "context": ""
        },
        {
          "heading": "Overview",
          "id": "overview",
          "text": "Overview is the summary: it carries no plot at all. The tiles are the whole surface and they take the card. Every headline metric reads its period value first, then its measured companion fact, then its evolution sparklines: requests / tokens: the request count over the blended token volume. tokens in/out/cached: one in / out / cached triple, with the input share of all tokens and the cache hit share of input underneath. Each share line names what it compares. spend with the server's blended per-Mtok price (the same blended-price rule as the KPI band, scoped to the viewed period and cost-reporting requests only). the health pair (errors in the error red / rate-limited requests in the 429 tone, over the request denominator). the merged timing tile: average latency / average speed over every measured request in the period (server-computed from the same samples the percentiles rank, never an average of bucket percentiles), each metric's low-high sample range underneath. Each tile carries one sparkline; combined tiles draw one self-scaled line per metric half in exactly the half's color. Sparks span only traffic-bearing buckets - the same empty-bucket removal the plots apply - so windo",
          "context": "Timelines"
        },
        {
          "heading": "Traffic",
          "id": "traffic",
          "text": "Traffic compares request and error counts. Bars represent bucket totals, not smoothed rates. Empty intervals may be omitted in this preset; the chart explains that below its legend. 04 Traffic timelines · chart · traffic split · black / clear full size Requests and errors share one time axis; the totals strip carries the window rate. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear.",
          "context": "Timelines"
        },
        {
          "heading": "Errors",
          "id": "errors",
          "text": "Errors compares the count of affected requests with an error-rate line on a separate percentage axis. A request that only encountered HTTP 429 is not an error. A recovered failure can still contribute an error signal. 05 Errors timelines · chart · errors split · black / clear full size A 429 is a rate limit, not an error; the two series stay separate. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear.",
          "context": "Timelines"
        },
        {
          "heading": "Token usage",
          "id": "token-usage",
          "text": "Tokens compares input, output, reasoning and cached usage. The upstream's reported fields determine which splits are available. The compressed vertical scale keeps large prompt/cache volumes and small outputs readable together. A cache-hit line on a separate percentage axis tracks cached prompt tokens as a share of input per bucket. The totals strip adds each side's share of the blended total, the cache share of input, and the in:out tile: the raw pair (one line, halves in the token bars' colors) with the input share riding underneath - a percentage reads the same in every locale, where a small comma-decimal ratio looked like a count. 06 Tokens timelines · chart · tokens split · black / clear full size Cached reads are drawn beside billed input, so a high cache share is visible rather than inferred. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear.",
          "context": "Timelines"
        },
        {
          "heading": "Speed and latency",
          "id": "speed-and-latency",
          "text": "Speed + latency compares generation speed (first token to last token) with time to first token on separate axes. TTFT is measured from each request's upstream attempt send, so a retry has its own TTFT. One percentile dropdown controls both series; the legend does not repeat it. Choose p50, p95 or p99. Each statistic needs at least four valid samples; smaller sets and missing measurements remain unavailable. A bucket plots only when both measurements exist at the selected percentile, and those unmeasured buckets compact out of the timeline instead of stranding gap points in dead space - the context row below the plot says when that happened. Period readouts use the period's samples, not an average of bucket percentiles. 07 Speed and latency timelines · chart · latency · p95 split · black / clear full size The percentile control applies to every measured rate in the preset. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear.",
          "context": "Timelines"
        },
        {
          "heading": "Provider-reported cost",
          "id": "provider-reported-cost",
          "text": "Cost shows reported spend alongside request counts. Values below $1 use cents, including tooltips and totals. Missing provider cost does not establish a zero bill, and there is no hardcoded per-model price table. 08 Provider-reported cost timelines · chart · cost split · black / clear full size Spend is whatever the upstream reported, plotted beside the request volume that produced it. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear.",
          "context": "Timelines"
        },
        {
          "heading": "Explorer",
          "id": "explorer",
          "text": "Changing the dimension in the rail changes the grouping, not the active filters. Selecting a card adds or replaces that dimension's exact filter; selecting it again removes it. Filters from other dimensions remain active. The breadcrumb chips remove individual selections or return to all traffic. The gallery ignores its own dimension's filter so alternatives remain visible; the timeline and request log still use the complete selected scope. Multi-valued dimensions, such as tools and errors, can overlap rather than partition requests. Dimension, in rail order What it groups Providers Server-derived upstream identities after configured aliases. Models Model groups produced by the configured canonicalization rules. Clients Explicit client labels or inferred SDK/User-Agent identities, retention-bounded before the ring and store. Conversations Conversation IDs from explicit sessions, tracked body params ( k: identities) or automatic grouping, with declared ancestry when resolvable. Selecting a conversation selects that leaf, not its descendants. Tools Observed tool names; one request can belong to several tools. Time Request start in the server's local timezone: weekday night 00:00-08:0",
          "context": ""
        },
        {
          "heading": "Providers",
          "id": "providers",
          "text": "Provider cards compare request share, reported cost, tokens, cache use, timing and health. Error and HTTP 429 badges count distinct affected requests and omit zero values independently. A request can contribute to both badges. 10 Providers explorer · #/by/provider split · black / clear full size The rail counts distinct values; each card shows its share and the signals that matter for that dimension. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear.",
          "context": "Explorer"
        },
        {
          "heading": "Models",
          "id": "models",
          "text": "Model cards group configured model variants for comparison. The shipped rules fold provider decorations (vendor namespaces, tags, quantization, service tiers, release channels and build stamps) into the base model, so one model served by several providers is one card. Model tiers, fine-tunes and parameter counts stay distinct. Selecting a card scopes the timeline and request log together. Model grouping is configuration-owned; stored model spellings remain available for exact export and deletion filters. Adapters can normalize those spellings before storage; see request metadata . 11 Models explorer · #/by/model split · black / clear full size The model dimension applies the configured grouping rules before it counts. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 19 A scoped reading explorer · #/ by provider · filtered split · black / clear full size A card toggles an exact filter; the chip removes it, and the timeline and log follow the same scope. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. The capture gallery carries all nine dimensions. This ",
          "context": "Explorer"
        },
        {
          "heading": "Request inspection",
          "id": "request-inspection",
          "text": "",
          "context": ""
        },
        {
          "heading": "Request table",
          "id": "request-table",
          "text": "The request table combines recent finalized records with current in-flight state during ordinary live use. Rows show status, retry information, latency, throughput, token/cache usage, tool calls, duration, queue time and reported cost. Columns size to their content and keep a per-column floor: a value wider than every value seen before grows its column, and a later shorter value never shrinks it back. A live row finalizing from streaming to its recorded status therefore cannot pull the status column back; a final value wider than its in-flight placeholder can still grow its own column once. When the card is narrower than the learned columns, the table scrolls inside its own region. The region is keyboard-scrollable and labelled, the identity cell carries the full client · provider · model value in a hover title, and compact status pills and the actions button abbreviate by design. Its status selector and older-history paging operate on the current scope. 20 The request log requests · #/by/model split · black / clear full size Each row is one crossing; the columns are the facts a later review needs first. Scroll the plate horizontally to see every column. The plate is split diagonal",
          "context": "Request inspection"
        },
        {
          "heading": "Request details",
          "id": "request-details",
          "text": "Click a row or its detail button to open the inspector. The header keeps the request identity and the previous/next controls. The summary below it shows the live or final status, method and path, client, provider and model, plus duration, TTFT, tokens, speed, cost and retries when captured. The full field inventory is classified into four sticky groups, each with the number of cards it contains: Request: identity, time bucket, request and response sizes, client/runtime, provider metadata, and captured model and parameters. Content: conversation and parent ids, turn and size composition, prompt and response previews. Usage: input, output, reasoning, answer, cache and generated tokens; timing, throughput, cost, transport decomposition, and tools. Diagnostics: queue and rate limits, absorbed retries, in-band upstream responses, response headers, and the Debug capture when one exists. Only the selected group is shown; its cards behave like the previous single page. Each card header can collapse or expand its section, and both the active group and collapse choices survive live updates until the inspector closes. Copy actions sit on the values that matter (identifiers, conversation ids, ",
          "context": "Request inspection"
        },
        {
          "heading": "Tokens and performance",
          "id": "tokens-and-performance",
          "text": "Open Usage for token splits, cache hit, generated-token composition, timestamps, the adopted attempt's send anchor, throughput, reported cost, finish state and transport timing. Absorbed retry attempts appear under Diagnostics when the selected request has them, each with its status, provider error detail, the attempt's own provider request id, and captured upstream server, model, processing and rate-limit facts. An in-band upstream response that arrived after a committed success is disclosed separately rather than presented as a retry. Clicking an absorbed attempt, a retry sub-row in the request table or an entry in the drawer's retry list opens that attempt's own detail view. 24 Diagnostics requests · drawer · diagnostics split · black / clear full size The diagnostics group is where a transparent retry stops being invisible. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. These captures deliberately omit request content and Debug payloads; ordinary opt-in captures remain sensitive. 23 Tokens and performance requests · drawer · usage split · black / clear full size Usage is grouped by the question it answers, so ti",
          "context": "Request inspection"
        },
        {
          "heading": "Operator console",
          "id": "operator-console",
          "text": "The header's operator readout is the one control surface. It stays in the header rail at every width, including the phone header; the theme tray and Settings sit behind the actions flyout there. It reads steady when no hold or capture is active, no limit policy is enforcing, no request is parked by the storm/quota gate and no restart is running, then one segment per active hold ( paused 1 ), capture session ( captures 1 ), enforcing limit policy ( limits 2 ) and gated request ( gated 3 ). A stored policy whose schedule window is closed enforces nothing, so it is named separately as off schedule N instead of being counted as a cap; the server owns that verdict and reports it per policy, so the header cannot re-derive a different answer from the stored minutes. The wording names the behaviour, because scheduled N read as \"the cap is on a schedule and working\" when it meant the opposite. While a rebuild runs, restarting comes first, with · step N when the server reports a real step. The counts are live state: a hold that expires, a stopped capture or a cleared limit leaves on the next state repaint. A hold takes the warning tone because it is the one state that stops live traffic; a r",
          "context": ""
        },
        {
          "heading": "Rule rows",
          "id": "rule-rows",
          "text": "Every rule is one calibration line: a kind tag in its state color, the human scope, the caps or schedule, then a live column for occupancy and actions. The scope sentence is generated from the selector the server enforces, so an empty dimension reads inside the sentence instead of as a separate checklist. Every rule kind offers the dimensions its own matcher honours: a limit and a hold both scope on providers, models, clients, key hashes and conversations, because the scheduler matches both against one request identity, while a capture scopes on clients, providers and models. A limit row names its budgets and schedule plus any remaining request and token budget; who set it rides the row title rather than a third line. A hold row names its remaining time, its queue cap or queue unlimited , and its queued count. A capture row names its retained count, its run time, and its duration or until stopped . A row is the one edit target: activating it opens its composer in edit mode. The action column offers copy, which starts a draft from the same scope and schedule with no budgets, and the terminating action for that kind: remove, resume or stop. A copied limit that still matches its sourc",
          "context": "Operator console"
        },
        {
          "heading": "Composer anatomy",
          "id": "composer-anatomy",
          "text": "Limits, pause and capture share one composer: a titled bench, one scope strip, budget or duration controls, a live preview sentence, and a footer with cancel and the one commit action. The composer opens above the rule list, so its form and its commit are in view the moment the operator asks for one. A phone pins that action row to the pane's bottom edge. The scope is one wrapping strip of dimension chips rather than five stacked rows. An unset dimension is a dim chip you click; a set one carries its values inside the same chip. One picker opens at a time, below the whole strip, with a filter only once the list is long enough to scan, the known values as checkable rows, and a free-value field except for key hashes. Provider, model, client and conversation scopes accept a typed value; the key scope lists only SHA-256 hashes already present in the live record ring. The preview states what the commit will enforce. Limits add concurrency, request and token budgets with their windows, an optional anti-burst ramp, and an optional day-of-week schedule with server-local from and to times. Burst control and schedule are peers on one row, each opening its own body below. A window is a native",
          "context": "Operator console"
        },
        {
          "heading": "Confirmation and the change ledger",
          "id": "confirmation-and-the-change-ledger",
          "text": "Removing a limit, resuming every hold, stopping every capture, draining the queue and restarting open the shared confirmation dialog. It states the consequence, focuses cancel first, and names the action on its confirm button. Individual stop, and a resume with nothing queued, commit directly; resuming a hold that has parked requests opens the shared confirmation first, because it releases that backlog to the provider. An edit commits when its composer is applied. All are recorded. The console footer is a bounded session ledger. It shows the newest change and offers Undo while that change has a defined inverse. Undo applies it once and appends an undid: ... receipt; the next change becomes the new undo target. The ledger has one owner: the console footer. Up to eight changes are retained for the page session. Changes without an inverse, such as a download or a restart, are recorded without an undo action. The ledger is browser memory, clears on reload and is not an audit log. A rejected write is named in the open pane, not hidden behind a closed panel.",
          "context": "Operator console"
        },
        {
          "heading": "Export",
          "id": "export",
          "text": "The export section owns record exports. Choose all history or matching records. Matching records offers provider, model, client, conversation and status in the same one-strip selector the composer uses, then errors-only, debug-only, newer-than and older-than, plus an exact error type field. The receipt and its download stay in the same view as the filters that shape them. Provider, model and client merge the server's known vocabularies with whatever the live record ring holds, so a quiet proxy or a fresh restart still offers them; all four accept a typed value as well, so a dimension the server has never seen is not a dead end. Status is the one list-only dimension, because a status code is not a name anyone can type reliably. Both modes preview through the same server count: all history is the same predicate with an empty filter. The receipt always names the number of records the download will carry, the download stays disabled until a nonzero count is ready, and the ledger repeats that number. A mode switch invalidates the count rather than quoting the previous mode's total, and filter mode with nothing selected asks for a filter instead of counting the unfiltered set. Downloads ",
          "context": "Operator console"
        },
        {
          "heading": "Request detail",
          "id": "request-detail",
          "text": "A request's detail drawer carries the two console prefills that record can seed: hold this scope and capture this scope . Both close the drawer and open a draft scoped to that request, so holding the client of a slow response does not require reading the value, closing the drawer and retyping it into a picker. They are prefills, not commits: the composer still gates every write, so no confirmation is added. The open is deferred one task, because the press that triggered it would otherwise reach the header's outside-press closer and dismiss the console it had just opened.",
          "context": "Operator console"
        },
        {
          "heading": "System",
          "id": "system",
          "text": "The system section owns restart and the console's link to Settings. It explains the rebuild and handoff, lists the four steps as they actually start ( rebuild from source , finish in-flight streams , flush metrics to disk , start the new process ), and disables restart while a run is active or the build cannot restart in place. A restart asks for confirmation and is recorded in the ledger without an undo action. Queue bounds, retry budgets, storage, retention and dashboard cadence are Settings fields, not console policies; the section links there instead of duplicating them. Static captures of the operator console publish to docs/images/console/ from the same authorized history workflow as the rest of the gallery. The retired menu screenshots were removed with the menus they pictured. Every section is recorded in its neutral starting state: no draft is committed, no rule is selected and no filter is armed. 25 Overview console · console · overview split · black / clear full size The overview is the register of what is in force, not a second settings form. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 26 Limits conso",
          "context": "Operator console"
        },
        {
          "heading": "Theme",
          "id": "theme",
          "text": "37 The theme tray themes · header · theme tray split · black / clear full size Palette, surface and order come from the same registry the site publishes; the seam is the surface switch made visible. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. Theme has two surfaces and eight palettes. Each palette owns a complete surface family (base, panels, rail and borders), its accent family, and its shadow and veil hue, so a switch changes the shell rather than only a few accent edges. Clear is the light family; Black is the near-black family. The palette ids, labels, order and defaults live once in js/theme_boot.js . js/theme_state.js owns normalization, the stored pair, the one apply path and the browser chrome color; theme.js owns only the dashboard tray. The public documentation site publishes css/themes.css and both scripts byte-for-byte from the dashboard and renders the same eight palettes and two surfaces in its own header tray. Each origin keeps its own choice under the millivolt.theme key, so the site and dashboard do not share browser storage. Instrument (the default), Slate, Midnight, Nord, Forest, Rose, Ember an",
          "context": ""
        },
        {
          "heading": "Settings",
          "id": "settings",
          "text": "Settings uses the same schema, validation and defaults as configuration files. Search finds fields across categories. Changed values are revision-checked; every row whose field is restart-bound carries its own restart marker instead of only a category banner. Closed vocabularies render as selects from the schema's choices , and duration/byte values are parsed and checked against the schema's numeric band before Apply. A read-only config disables its field controls, not only Apply. The category rail right-aligns its row counts beside the label; on a phone it becomes one horizontally scrollable chip strip so the field pane keeps the height. Switching categories resets the field scroller, and the footer status is a live region with a distinct error tone. Structured fields replace their whole map/list value rather than recursively merging nested entries. The generated configuration example documents every field, including categories not pictured here. The capture gallery records five categories, including the backup and restore sheet.",
          "context": ""
        },
        {
          "heading": "Dashboard cadence",
          "id": "dashboard-cadence",
          "text": "Dashboard settings control log-window size and polling/aggregate refresh cadence. Live rows and the in-flight gauge remain distinct from periodic chart and explorer aggregation. 32 Dashboard settings · settings · dashboard split · black / clear full size Every field is generated from the schema, including its help and the restart badge. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear.",
          "context": "Settings"
        },
        {
          "heading": "Queue and retry",
          "id": "queue-and-retry",
          "text": "Queue and retry settings bound admission and retry behavior. Their help text distinguishes queue waiting, provider retry hints, retry budgets and capacity. Tune them for the upstream and workload; the picture uses the public example. 33 Queue and retry settings · settings · queue split · black / clear full size Retry policy, error classes and pacing sit together because they act on the same wait. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear.",
          "context": "Settings"
        },
        {
          "heading": "Storage",
          "id": "storage",
          "text": "Storage settings control the SQLite writer and its bounded queue/batches. Metrics persistence is best-effort under sustained overload; a successful inference response does not prove its record was stored. The dashboard reports process-local storage drops. The category also carries both database deletion controls, which live here and nowhere else: Delete matching removes only the records matching its provider, model, client, status, errors, debug and age filters after a live count preview and a confirmation, and Delete everything permanently deletes all metrics history, the live ring and the entire durable database. Neither action can be undone. 34 Storage settings · settings · storage split · black / clear full size Deletion is scoped and previewed; the storage facts come from the running store. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear.",
          "context": "Settings"
        },
        {
          "heading": "Provider compatibility",
          "id": "provider-compatibility",
          "text": "The example enables Grok, OpenCode Zen and Cursor compatibility profiles without credentials or upstream registrations. Their headers and metadata mappings are editable operator-selected snapshots, not guaranteed current provider contracts. See adapters before relying on them. 35 Providers settings · settings · providers split · black / clear full size Provider data is a field map in configuration, not a branch in the router. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. See Contributing before refreshing the gallery. Never publish private configuration, bodies, credentials or raw history copies.",
          "context": "Settings"
        }
      ],
      "markdown_text": "# Dashboard guide\n\nThe plate below is the complete dashboard. Use this guide to follow its\ncharts, explorer, request drawer, operator console and Settings without\nhunting through the interface.\n\nThese are real application captures from explicitly authorized local history.\nRecorded timing, token and cost values are retained; identifiers are replaced,\nand request content, retained headers, debug captures and operator state are\nremoved. Settings and the theme tray show the public example, not private\nconfiguration.\n\nNo requests, holds, limits or debug sessions were created to make the\npictures. The capture session blocks external requests and disables live SSE,\nso its **offline** indicator describes a static screenshot session, not\nservice health. The images are not latency guarantees, capacity measurements\nor independent bills.\n\nEvery capture in this guide and in the [capture gallery](gallery.md) is one\nstate photographed on both primary surfaces and split along the diagonal. The\nupper-left half is Instrument Black, the lower-right half is Instrument Clear.\nData, scroll and any open surface are identical across the cut.\n\n![The millivolt dashboard at 1920 pixels, split diagonally between the Black and Clear surfaces](images/overview/dashboard.png)\n\n## Error storm banner\n\nWhen enabled in Settings, error storm protection adds a live banner below the\nheader. Click an incident to inspect the number of requests with selected\nerrors, failed upstream attempts, error category, queued requests, next retry\ntime and recovery progress.\n\nIt names the affected provider or exact provider/model, shows its safe error\ncategory, failed upstream-attempt percentage and window, queue count and\nrecovery probe state. Provider incidents require all models active in the same\nwindow to have elevated errors.\n\nThe banner shows that active-model evidence; its attempt percentage differs\nfrom the Errors chart's affected-request rate. It clears when protection\nrecovers and can be hidden independently in Settings. See [configuration and\nbehavior](routes.md#error-storm-protection).\n\nThe static captures below show no banner because the capture session has no\nactive incident; the banner stays hidden until protection fires.\n\n## Timelines\n\nThe KPI band remains global. Explorer filters scope the timeline and request\nlog together. The timeframe control in the card head changes chart history,\nnot the global KPI band. It offers a zoom ladder from one minute through one\nyear plus **All time**, and the calendar presets today, yesterday, this week\nand this month.\n\nIts panel draws the stored coverage as a rail and disables any window wider\nthan the stored history, so a selection can never promise more history than\nexists; **All time** means exactly the retained history, and a calendar preset\nclamps its start to the oldest stored request. The selection persists per\nbrowser.\n\nLegend controls show or hide individual series; hover a bucket for its precise\nvalues and time interval. Counts, sums and percentiles come from the server. A\nwindow with fewer than four plotted points paints a waiting message instead of\nthe chart: one to three buckets are too few to read a trend, and the totals\nstrip still tells the story until a fourth point arrives. A span with no\nstored history says so; a span inside history with no requests says that\ninstead.\n\n![Timeframe panel with the stored-coverage rail, the zoom ladder and the calendar presets](images/charts/window.png)\n\nA failed chart request never blanks a good payload: one transient error should\nnot hide the history you were reading. The context row states which of the two\nsituations applies. With nothing drawn it reads\n`chart unavailable - retrying`; with a last-good payload still on screen it\nreads the window and `stale, retrying`, so old buckets are never presented as\na current reading. Either way the next successful request clears it.\n\nThe **In-flight** KPI tile separates sending work from parked work. Its\nsummary names two totals that fit the narrowest tile - active and queued - and\nthe composition rail under the value splits every live state by color:\nsending, pending, operator-paused and throttled. Hover the rail, or focus it\nwith assistive technology, for the exact per-state counts.\n\nQueued covers both the admission queue (per-key concurrency, pacing, provider\ncaps, operator holds) and the retry send gate, so a provider's 429 pacing\nwindow shows its parked requests as queued instead of as idle streams. The\nrequest table's `throttled` pill marks the same state per row.\n\n### Overview\n\n**Overview** is the summary: it carries no plot at all. The tiles are the\nwhole surface and they take the card. Every headline metric reads its period\nvalue first, then its measured companion fact, then its evolution sparklines:\n\n- requests / tokens: the request count over the blended token volume.\n- tokens in/out/cached: one in / out / cached triple, with the input share of\n  all tokens and the cache hit share of input underneath. Each share line\n  names what it compares.\n- spend with the server's blended per-Mtok price (the same blended-price rule\n  as the KPI band, scoped to the viewed period and cost-reporting requests\n  only).\n- the health pair (errors in the error red / rate-limited requests in the 429\n  tone, over the request denominator).\n- the merged timing tile: average latency / average speed over every measured\n  request in the period (server-computed from the same samples the percentiles\n  rank, never an average of bucket percentiles), each metric's low-high sample\n  range underneath.\n\nEach tile carries one sparkline; combined tiles draw one self-scaled line per\nmetric half in exactly the half's color. Sparks span only traffic-bearing\nbuckets - the same empty-bucket removal the plots apply - so window padding\nnever squeezes the data into a corner.\n\nThe metrics picker in the card head chooses what shows: one menu of checkable\nrows, checked metrics render and unchecked ones leave the band (it reflows),\nand the selection persists per browser like every chart view.\n\nEvery selected tile always renders in both layouts: the band wraps into as\nmany whole rows of 170px tracks as the card needs, and the page scrolls past\nthem in the base layout; the picker's count reports the selection itself, so\nit can never disagree with the band. The wide layout is the 1200x750\none-screen lock: the page locks to the viewport with no scrolling, the\nexplorer compresses to one gallery row, and the timeline column floors at\n572px so the 5-metric selection wraps into at most two rows.\n\nEvery tile keeps one fixed size whatever it carries - spark or not, one share\nline or two, and the no-data skeleton swaps in without moving the card - and\nthe band sits at its natural height at the top of the card. Only the timeframe\ncontrol applies.\n\n![The overview preset with five summary tiles and their sparklines](images/charts/overview.png)\n\n### Traffic\n\n**Traffic** compares request and error counts. Bars represent bucket totals,\nnot smoothed rates. Empty intervals may be omitted in this preset; the chart\nexplains that below its legend.\n\n![Traffic timeline with request and error counts from recorded history](images/charts/traffic.png)\n\n### Errors\n\n**Errors** compares the count of affected requests with an error-rate line on\na separate percentage axis. A request that only encountered HTTP 429 is not an\nerror. A recovered failure can still contribute an error signal.\n\n![Error timeline with affected-request bars and a separate percentage axis](images/charts/errors.png)\n\n### Token usage\n\n**Tokens** compares input, output, reasoning and cached usage. The upstream's\nreported fields determine which splits are available. The compressed vertical\nscale keeps large prompt/cache volumes and small outputs readable together.\n\nA cache-hit line on a separate percentage axis tracks cached prompt tokens as\na share of input per bucket. The totals strip adds each side's share of the\nblended total, the cache share of input, and the in:out tile: the raw pair\n(one line, halves in the token bars' colors) with the input share riding\nunderneath - a percentage reads the same in every locale, where a small\ncomma-decimal ratio looked like a count.\n\n![Token timeline with input, output, reasoning and cached usage](images/charts/tokens.png)\n\n### Speed and latency\n\n**Speed + latency** compares generation speed (first token to last token) with\ntime to first token on separate axes. TTFT is measured from each request's\nupstream attempt send, so a retry has its own TTFT. One percentile dropdown\ncontrols both series; the legend does not repeat it. Choose p50, p95 or p99.\n\nEach statistic needs at least four valid samples; smaller sets and missing\nmeasurements remain unavailable. A bucket plots only when both measurements\nexist at the selected percentile, and those unmeasured buckets compact out of\nthe timeline instead of stranding gap points in dead space - the context row\nbelow the plot says when that happened.\n\nPeriod readouts use the period's samples, not an average of bucket\npercentiles.\n\n![Speed and latency timeline with independent axes and percentile control](images/charts/speed-latency.png)\n\n### Provider-reported cost\n\n**Cost** shows reported spend alongside request counts. Values below $1 use\ncents, including tooltips and totals. Missing provider cost does not establish\na zero bill, and there is no hardcoded per-model price table.\n\n![Cost timeline with spend and request-count axes](images/charts/cost.png)\n\n## Explorer\n\nChanging the dimension in the rail changes the grouping, not the active\nfilters. Selecting a card adds or replaces that dimension's exact filter;\nselecting it again removes it. Filters from other dimensions remain active.\nThe breadcrumb chips remove individual selections or return to all traffic.\n\nThe gallery ignores its own dimension's filter so alternatives remain visible;\nthe timeline and request log still use the complete selected scope.\nMulti-valued dimensions, such as tools and errors, can overlap rather than\npartition requests.\n\n| Dimension, in rail order | What it groups |\n| --- | --- |\n| Providers | Server-derived upstream identities after configured aliases. |\n| Models | Model groups produced by the configured canonicalization rules. |\n| Clients | Explicit client labels or inferred SDK/User-Agent identities, retention-bounded before the ring and store. |\n| Conversations | Conversation IDs from explicit sessions, tracked body params (`k:` identities) or automatic grouping, with declared ancestry when resolvable. Selecting a conversation selects that leaf, not its descendants. |\n| Tools | Observed tool names; one request can belong to several tools. |\n| Time | Request start in the server's local timezone: weekday night 00:00-08:00, work 08:00-16:00, evening 16:00-24:00, or a single weekend group. This is separate from chart history range. |\n| Status | Coarse outcome classes and live states. The Requests dropdown instead selects exact HTTP codes or named live states, grouped into live states and HTTP status; it stays a native select so the operating system picker is the touch affordance. |\n| Errors | Distinct observed error identities, including absorbed failures; one request can have several. HTTP 429 alone is not an error. |\n| Keys | SHA-256 hashes of upstream credentials, never raw keys. Labels show only an eight-hex-character prefix; identical short labels do not establish identical full hashes. |\n\n### Providers\n\nProvider cards compare request share, reported cost, tokens, cache use, timing\nand health. Error and HTTP 429 badges count distinct affected requests and\nomit zero values independently. A request can contribute to both badges.\n\n![Provider explorer with pseudonymous groups, recorded costs and health signals](images/explorer/providers.png)\n\n### Models\n\nModel cards group configured model variants for comparison. The shipped rules\nfold provider decorations (vendor namespaces, tags, quantization, service\ntiers, release channels and build stamps) into the base model, so one model\nserved by several providers is one card. Model tiers, fine-tunes and parameter\ncounts stay distinct.\n\nSelecting a card scopes the timeline and request log together. Model grouping\nis configuration-owned; stored model spellings remain available for exact\nexport and deletion filters. Adapters can normalize those spellings before\nstorage; see [request metadata](routes.md#request-rows-and-details).\n\n![Model explorer with pseudonymous model groups and recorded usage metrics](images/explorer/models.png)\n\n![Provider explorer filtered to one provider, with the removable scope chip above the rail and the selected card marked](images/explorer/scoped.png)\n\nThe [capture gallery](gallery.md#nine-ways-into-the-traffic) carries all nine\ndimensions. This guide shows the two that move the most.\n\nConversation ancestry is explicit, not guessed from timing or names. The\nauthorized snapshot has no parent declarations, so these screenshots do not\nfabricate an agent tree. See the [client protocol](protocol.md) for\nrelationship headers and the limits of missing, conflicting or ambiguous\ndeclarations.\n\n## Request inspection\n\n### Request table\n\nThe request table combines recent finalized records with current in-flight\nstate during ordinary live use. Rows show status, retry information, latency,\nthroughput, token/cache usage, tool calls, duration, queue time and reported\ncost.\n\nColumns size to their content and keep a per-column floor: a value wider than\nevery value seen before grows its column, and a later shorter value never\nshrinks it back. A live row finalizing from `streaming` to its recorded status\ntherefore cannot pull the status column back; a final value wider than its\nin-flight placeholder can still grow its own column once. When the card is\nnarrower than the learned columns, the table scrolls inside its own region.\n\nThe region is keyboard-scrollable and labelled, the identity cell carries the\nfull `client · provider · model` value in a hover title, and compact status\npills and the actions button abbreviate by design. Its status selector and\nolder-history paging operate on the current scope.\n\n![Request table with recorded statuses, token usage, latency, throughput and cost](images/requests/table.png)\n\n![Request table with one row expanded into its absorbed retry attempts](images/requests/retries.png)\n\n### Request details\n\nClick a row or its detail button to open the inspector. The header keeps the\nrequest identity and the previous/next controls. The summary below it shows\nthe live or final status, method and path, client, provider and model, plus\nduration, TTFT, tokens, speed, cost and retries when captured. The full field\ninventory is classified into four sticky groups, each with the number of cards\nit contains:\n\n- Request: identity, time bucket, request and response sizes, client/runtime,\n  provider metadata, and captured model and parameters.\n- Content: conversation and parent ids, turn and size composition, prompt and\n  response previews.\n- Usage: input, output, reasoning, answer, cache and generated tokens; timing,\n  throughput, cost, transport decomposition, and tools.\n- Diagnostics: queue and rate limits, absorbed retries, in-band upstream\n  responses, response headers, and the Debug capture when one exists.\n\nOnly the selected group is shown; its cards behave like the previous single\npage. Each card header can collapse or expand its section, and both the active\ngroup and collapse choices survive live updates until the inspector closes.\n\nCopy actions sit on the values that matter (identifiers, conversation ids,\npaths, models, headers, error detail and captured bodies), on field-list\ncards, and on the header's JSON action for the whole record or the selected\nattempt. One polite status line confirms each copy or reports a denied\nclipboard write.\n\nLong values wrap. Captured prompt, response and Debug bodies open in a bounded\ncode surface with a line count, wrap toggle, copy action and expand/collapse\ncontrol; a long single line scrolls inside that surface instead of widening\nthe inspector. A final upstream failure appears as a bordered alert above the\ncards with its type, code, message and copy action, plus the HTTP status when\nthe failure was an HTTP response.\n\nA rate limit the provider announced in its own type or code counts in the\nrate-limit card even when the status was not 429; a request that ended on one\nstill appears as an alert, and a bare 429 stays the flow-control handshake it\nis. On narrow viewports the inspector fills the width, stacks each key above\nits value, keeps touch-sized copy and close targets, and respects the bottom\nsafe area.\n\nPrevious/next controls follow the scoped table order. Explicit zero and false\nparameter values are retained instead of treated as missing. While a request\nis in flight, pause and throttle state appear as explicit rows.\n\n![Request drawer showing pseudonymous identity, the summary readout and recorded request parameters](images/requests/details.png)\n\n### Tokens and performance\n\nOpen Usage for token splits, cache hit, generated-token composition,\ntimestamps, the adopted attempt's send anchor, throughput, reported cost,\nfinish state and transport timing.\n\nAbsorbed retry attempts appear under Diagnostics when the selected request has\nthem, each with its status, provider error detail, the attempt's own provider\nrequest id, and captured upstream server, model, processing and rate-limit\nfacts. An in-band upstream response that arrived after a committed success is\ndisclosed separately rather than presented as a retry. Clicking an absorbed\nattempt, a retry sub-row in the request table or an entry in the drawer's\nretry list opens that attempt's own detail view.\n\n![Request drawer diagnostics group with queue and rate-limit facts and four absorbed attempts](images/requests/diagnostics.png)\n\nThese captures deliberately omit request content and Debug payloads; ordinary\nopt-in captures remain sensitive.\n\n![The same request drawer showing token and performance measurements](images/requests/performance.png)\n\n## Operator console\n\nThe header's operator readout is the one control surface. It stays in the\nheader rail at every width, including the phone header; the theme tray and\nSettings sit behind the actions flyout there.\n\nIt reads `steady` when no hold or capture is active, no limit policy is\nenforcing, no request is parked by the storm/quota gate and no restart is\nrunning, then one segment per active hold (`paused 1`), capture session\n(`captures 1`), enforcing limit policy (`limits 2`) and gated request\n(`gated 3`).\n\nA stored policy whose schedule window is closed enforces nothing, so it is\nnamed separately as `off schedule N` instead of being counted as a cap; the\nserver owns that verdict and reports it per policy, so the header cannot\nre-derive a different answer from the stored minutes. The wording names the\nbehaviour, because `scheduled N` read as \"the cap is on a schedule and\nworking\" when it meant the opposite.\n\nWhile a rebuild runs, `restarting` comes first, with ` · step N` when the\nserver reports a real step. The counts are live state: a hold that expires, a\nstopped capture or a cleared limit leaves on the next state repaint. A hold\ntakes the warning tone because it is the one state that stops live traffic; a\nrestart takes it too, with a pulsing dot.\n\nIf the live stream was open and then drops, the line keeps its last known\nwords and appends ` · offline`; if the operator poll instead stops answering,\nit appends ` · stale`. Both mark the words as last known rather than current.\n\nThe header readout is not a live region; it updates when operator state,\nconnectivity or restart status changes, and the trigger's accessible label\ncarries the same words plus the action the trigger performs in its current\nstate. The open console's head line repeats those words without a second total\nand is a polite live region.\n\nActivating the readout opens the console. On a wide viewport it is an anchored\npopover under the trigger: 520px wide, and only as tall as its content up to a\n560px cap, scrolling inside it.\n\nAt 800px or narrower it becomes a bottom sheet with a definite height of\n`min(88dvh, 100dvh - 16px)`, leaving a strip of page above it for\noutside-press dismissal. The height is definite rather than a cap: the body\nand the pane grow into the remainder, so a tall composer scrolls inside the\npane instead of being clipped by the panel.\n\nOn a landscape phone (800px or narrower and 500px or shorter) the header,\nrail, pane and ledger tighten and the sheet gives up its top gap, sitting\nflush with the top edge so only the 8px bottom dismissal strip remains; a very\nshort viewport turns every fixed band into space the form loses.\n\nThe section rail is one horizontally scrollable strip and fades its trailing\nedge while more sections remain; at 560px or narrower, where six chips\ngenuinely cannot share one row, it becomes a two-row grid. That threshold is\nthe content, not the device class: a landscape phone is 640-844 wide and keeps\nthe single-row strip.\n\nEscape, an outside press, the close button, or opening the theme tray or\nSettings closes it; opening the console closes the theme tray and Settings\nfirst. The session remembers the last section, so reopening returns where the\noperator left. Opening the console itself performs no action.\n\nThe rail names six sections: overview, limits, pause, capture, export and\nsystem. Limits, pause and capture carry a count badge: for limits the number\nof rules enforcing right now, for pause the active holds, for capture the\nrunning capture sessions. A rule outside its schedule window is installed but\nenforcing nothing, so it does not raise the limits badge.\n\nThe overview is the rule register: one row per hold, capture and every\ninstalled limit, each jumping to the section that owns it, with an\noff-schedule limit marked `off schedule` rather than reading as a live cap,\nplus the queue drain control when requests are actually parked.\n\nA request parked by the storm/quota gate is named in its own block instead:\nthat gate runs before admission, so a drain cannot release it, and the block\npoints at the controls that can. The counts are not repeated there, because\nthe head line and the section badges already state them.\n\nLimits, pause and capture hold rule rows and one composer; export holds the\ndownload builder, and system holds the restart and Settings cards.\n\n### Rule rows\n\nEvery rule is one calibration line: a kind tag in its state color, the human\nscope, the caps or schedule, then a live column for occupancy and actions. The\nscope sentence is generated from the selector the server enforces, so an empty\ndimension reads inside the sentence instead of as a separate checklist.\n\nEvery rule kind offers the dimensions its own matcher honours: a limit and a\nhold both scope on providers, models, clients, key hashes and conversations,\nbecause the scheduler matches both against one request identity, while a\ncapture scopes on clients, providers and models.\n\n- A limit row names its budgets and schedule plus any remaining request and\n  token budget; who set it rides the row title rather than a third line.\n- A hold row names its remaining time, its queue cap or `queue unlimited`, and\n  its queued count.\n- A capture row names its retained count, its run time, and its duration or\n  `until stopped`.\n\nA row is the one edit target: activating it opens its composer in edit mode.\nThe action column offers copy, which starts a draft from the same scope and\nschedule with no budgets, and the terminating action for that kind: remove,\nresume or stop. A copied limit that still matches its source selector is\nrefused and named, because a limit's identity is its selector: applying it\nwould edit the original rather than add a second rule. The edit action is not\nrepeated there, because the row already performs it.\n\nOn a narrow phone the row takes two lines so the scope can be read in full\ninstead of being clipped; the budget wraps beneath the scope rather than being\ndropped, because a limit's scope identifies it while its budget is what it\ndoes.\n\nA rule list that outgrows the pane offers a filter once it holds enough rules\nto need one, so a console with two rules never spends a row on an empty box.\nThe filter matches the text each row already renders, which gives limits,\npause and capture one search rule and makes a new row field searchable without\na second list of what to match.\n\nA filter that hides everything says how many rules are in force and offers to\nclear itself, so an empty result never reads as an empty policy.\n\n### Composer anatomy\n\nLimits, pause and capture share one composer: a titled bench, one scope strip,\nbudget or duration controls, a live preview sentence, and a footer with cancel\nand the one commit action. The composer opens above the rule list, so its form\nand its commit are in view the moment the operator asks for one. A phone pins\nthat action row to the pane's bottom edge.\n\nThe scope is one wrapping strip of dimension chips rather than five stacked\nrows. An unset dimension is a dim chip you click; a set one carries its values\ninside the same chip. One picker opens at a time, below the whole strip, with\na filter only once the list is long enough to scan, the known values as\ncheckable rows, and a free-value field except for key hashes.\n\nProvider, model, client and conversation scopes accept a typed value; the key\nscope lists only SHA-256 hashes already present in the live record ring. The\npreview states what the commit will enforce.\n\nLimits add concurrency, request and token budgets with their windows, an\noptional anti-burst ramp, and an optional day-of-week schedule with\nserver-local from and to times. Burst control and schedule are peers on one\nrow, each opening its own body below. A window is a native select: the list is\nlong and the track is one number wide, so the current choice is stated in one\nline and the rest is the platform's own picker.\n\nThe ramp is offered only on a single-provider rule without a schedule. Equal\nfrom and to times mean all day, and a window that starts after its end spans\nmidnight. Pause adds everything, new-clients and named clients/providers\nmodes, a duration or until-resumed choice, and an optional queue cap.\n\nIts head also carries a one-click bounded hold (`hold all 15m`), which writes\nthe same all-traffic document through the same gate, ledger and undo path. It\nis bounded by construction: an indefinite hold is still available, but only\nthrough the composer where the operator chooses it.\n\nCapture starts a scoped Debug session and adds client, provider and model\nscopes, a duration or until-stopped choice, and the retention and byte facts\nfor the current configuration.\n\n### Confirmation and the change ledger\n\nRemoving a limit, resuming every hold, stopping every capture, draining the\nqueue and restarting open the shared confirmation dialog. It states the\nconsequence, focuses cancel first, and names the action on its confirm button.\nIndividual stop, and a resume with nothing queued, commit directly; resuming a\nhold that has parked requests opens the shared confirmation first, because it\nreleases that backlog to the provider. An edit commits when its composer is\napplied. All are recorded.\n\nThe console footer is a bounded session ledger. It shows the newest change and\noffers Undo while that change has a defined inverse. Undo applies it once and\nappends an `undid: ...` receipt; the next change becomes the new undo target.\nThe ledger has one owner: the console footer. Up to eight changes are retained\nfor the page session.\n\nChanges without an inverse, such as a download or a restart, are recorded\nwithout an undo action. The ledger is browser memory, clears on reload and is\nnot an audit log. A rejected write is named in the open pane, not hidden\nbehind a closed panel.\n\n### Export\n\nThe export section owns record exports. Choose all history or matching\nrecords. Matching records offers provider, model, client, conversation and\nstatus in the same one-strip selector the composer uses, then errors-only,\ndebug-only, newer-than and older-than, plus an exact error type field. The\nreceipt and its download stay in the same view as the filters that shape them.\n\nProvider, model and client merge the server's known vocabularies with whatever\nthe live record ring holds, so a quiet proxy or a fresh restart still offers\nthem; all four accept a typed value as well, so a dimension the server has\nnever seen is not a dead end. Status is the one list-only dimension, because a\nstatus code is not a name anyone can type reliably.\n\nBoth modes preview through the same server count: all history is the same\npredicate with an empty filter. The receipt always names the number of records\nthe download will carry, the download stays disabled until a nonzero count is\nready, and the ledger repeats that number. A mode switch invalidates the count\nrather than quoting the previous mode's total, and filter mode with nothing\nselected asks for a filter instead of counting the unfiltered set.\n\nDownloads are gzip JSON artifacts. Configuration and database backups stay in\nSettings, and the console links there.\n\n### Request detail\n\nA request's detail drawer carries the two console prefills that record can\nseed: `hold this scope` and `capture this scope`. Both close the drawer and\nopen a draft scoped to that request, so holding the client of a slow response\ndoes not require reading the value, closing the drawer and retyping it into a\npicker.\n\nThey are prefills, not commits: the composer still gates every write, so no\nconfirmation is added. The open is deferred one task, because the press that\ntriggered it would otherwise reach the header's outside-press closer and\ndismiss the console it had just opened.\n\n### System\n\nThe system section owns restart and the console's link to Settings. It\nexplains the rebuild and handoff, lists the four steps as they actually start\n(`rebuild from source`, `finish in-flight streams`, `flush metrics to disk`,\n`start the new process`), and disables restart while a run is active or the\nbuild cannot restart in place.\n\nA restart asks for confirmation and is recorded in the ledger without an undo\naction. Queue bounds, retry budgets, storage, retention and dashboard cadence\nare Settings fields, not console policies; the section links there instead of\nduplicating them.\n\nStatic captures of the operator console publish to `docs/images/console/` from\nthe same authorized history workflow as the rest of the gallery. The retired\nmenu screenshots were removed with the menus they pictured. Every section is\nrecorded in its neutral starting state: no draft is committed, no rule is\nselected and no filter is armed.\n\n![Overview section with no policy in force](images/console/overview.png)\n\n![Limits section with no policy set](images/console/limits.png)\n\n![Limit composer with its scope chips, budgets, window and live preview](images/console/limits-composer.png)\n\n![Pause section before any hold exists](images/console/pause.png)\n\n![Capture section with no session start](images/console/capture.png)\n\n![Export section previewing the whole-history record count](images/console/export.png)\n\n![System section with restart available and the step list](images/console/system.png)\n\nSee [routes and debugging](routes.md) for exact admission, filtering and\nfailure behavior, [containers and data](containers.md) for restart, and\n[operations](operations.md) for persistence, before using these controls.\n\n## Theme\n\n![The theme tray split between the Black and Clear surfaces, with the two-pane comparator and all eight palettes](images/theme/tray.png)\n\nTheme has two surfaces and eight palettes. Each palette owns a complete\nsurface family (base, panels, rail and borders), its accent family, and its\nshadow and veil hue, so a switch changes the shell rather than only a few\naccent edges. Clear is the light family; Black is the near-black family.\n\nThe palette ids, labels, order and defaults live once in `js/theme_boot.js`.\n`js/theme_state.js` owns normalization, the stored pair, the one apply path and\nthe browser chrome color; `theme.js` owns only the dashboard tray. The public\ndocumentation site publishes `css/themes.css` and both scripts byte-for-byte\nfrom the dashboard and renders the same eight palettes and two surfaces in its\nown header tray. Each origin keeps its own choice under the `millivolt.theme`\nkey, so the site and dashboard do not share browser storage.\n\nInstrument (the default), Slate, Midnight, Nord, Forest, Rose, Ember and\nContrast are available in both modes. Contrast is the maximum-separation\npalette: black with signal yellow in Black, white with black in Clear.\n\nThe theme tray stays open while choosing and shows a two-pane comparator: the\ncommitted pair on the left and the candidate on the right. Both panes use the\nsame token-faithful miniature with a three-color series legend; the captions\noutside the decorative panes name the committed and candidate pairs. The\npreview line stays muted while it reads \"Preview: same\" and takes primary ink\nonly for a real candidate.\n\nHovering or focusing a palette or surface updates only the preview pane and\ncaptions. Clicking, Enter or Space commits immediately and persists the pair;\nthere is no apply step. Arrow keys, Home and End move focus and the preview\ncursor without committing, and the focused row keeps the group's single tab\nstop so Tab leaves and returns to it. The current surface's Clear/Black radios\nsit under a visible Surface label in the caption bar.\n\nPointer activation commits without writing the polite candidate status; only\nkeyboard focus announces a preview. The trigger's arrow keys open the tray on\nthe saved palette; while open they move the preview cursor. Reset restores\nInstrument Black; Close only dismisses the tray.\n\nOn touch or coarse pointers the comparator, preview line and hover hint are\nhidden, leaving the current caption, the surface control, all eight palette\nrows, Reset and Close.\n\nA window 800px wide or narrower uses the same compact picker inside the header\nactions flyout even with a fine pointer, and the flyout rather than the tray\nor palette list is the one vertical scroller. At a viewport height of 760px or\nbelow the comparator, preview line and hint are hidden.\n\nIn windows wider than 800px the tray scrolls so every action remains\nreachable; narrower windows keep the header flyout as the single scroller. At\n360px or below the caption bar stacks into one column with a full-width\nsurface control, and the palette hints are hidden while names and swatches\nremain.\n\nReopening the tray or flyout brings the saved palette row into view instead of\nrestoring an arbitrary previous scroll offset. The choice is stored in this\nbrowser only and is applied before the first paint, so a reload does not flash\nthe default. Charts follow the selected palette; status colors follow the\nselected surface, and the browser's theme color follows the selected palette's\nrail. The setting is presentation only: it does not change proxy behavior,\nstored history or the configuration revision.\n\n## Settings\n\nSettings uses the same schema, validation and defaults as configuration files.\nSearch finds fields across categories. Changed values are revision-checked;\nevery row whose field is restart-bound carries its own `restart` marker\ninstead of only a category banner.\n\nClosed vocabularies render as selects from the schema's `choices`, and\nduration/byte values are parsed and checked against the schema's numeric band\nbefore Apply. A read-only config disables its field controls, not only Apply.\n\nThe category rail right-aligns its row counts beside the label; on a phone it\nbecomes one horizontally scrollable chip strip so the field pane keeps the\nheight. Switching categories resets the field scroller, and the footer status\nis a live region with a distinct error tone.\n\nStructured fields replace their whole map/list value rather than recursively\nmerging nested entries. The generated [configuration\nexample](../proxy.example.yaml) documents every field, including categories\nnot pictured here. The [capture gallery](gallery.md#the-patch-panel) records\nfive categories, including the backup and restore sheet.\n\n### Dashboard cadence\n\nDashboard settings control log-window size and polling/aggregate refresh\ncadence. Live rows and the in-flight gauge remain distinct from periodic chart\nand explorer aggregation.\n\n![Settings dialog showing public dashboard configuration fields](images/settings/dashboard.png)\n\n### Queue and retry\n\nQueue and retry settings bound admission and retry behavior. Their help text\ndistinguishes queue waiting, provider retry hints, retry budgets and capacity.\nTune them for the upstream and workload; the picture uses the public example.\n\n![Queue and retry Settings with their public values and field descriptions](images/settings/queue.png)\n\n### Storage\n\nStorage settings control the SQLite writer and its bounded queue/batches.\nMetrics persistence is best-effort under sustained overload; a successful\ninference response does not prove its record was stored. The dashboard reports\nprocess-local storage drops.\n\nThe category also carries both database deletion controls, which live here and\nnowhere else: Delete matching removes only the records matching its provider,\nmodel, client, status, errors, debug and age filters after a live count\npreview and a confirmation, and Delete everything permanently deletes all\nmetrics history, the live ring and the entire durable database. Neither action\ncan be undone.\n\n![Storage Settings with bounded writer, queue, persistence and deletion controls](images/settings/storage.png)\n\n### Provider compatibility\n\nThe example enables Grok, OpenCode Zen and Cursor compatibility profiles\nwithout credentials or upstream registrations. Their headers and metadata\nmappings are editable operator-selected snapshots, not guaranteed current\nprovider contracts. See [adapters](adapters.md#bundled-compatibility-profiles)\nbefore relying on them.\n\n![Provider Settings showing the public Cursor compatibility profile](images/settings/providers.png)\n\nSee [Contributing](../CONTRIBUTING.md#documentation-screenshots) before\nrefreshing the gallery. Never publish private configuration, bodies,\ncredentials or raw history copies.\n"
    },
    {
      "path": "docs/gallery.md",
      "slug": "docs/gallery",
      "output": "docs/gallery.html",
      "markdown": "docs/gallery.md",
      "url": "https://millivolt.llm4people.dev/docs/gallery.html",
      "markdown_url": "https://millivolt.llm4people.dev/docs/gallery.md",
      "title": "Capture gallery",
      "description": "37 plates across 7 stations, captured 16 November 2026 UTC from 100,158 recorded requests with identifiers replaced and content removed.",
      "group": "Start",
      "order": 3,
      "bytes": 12219,
      "sha256": "98ba2df3b9895821f5c99e8149cf38b8f50e56ebfea6e5600787c2fc729aa8d7",
      "sections": [
        {
          "heading": "The whole bench",
          "id": "the-whole-bench",
          "text": "The default view at 1920 px and at phone width; every plate carries the Black and Clear surfaces across one diagonal. 01 The whole bench overview · #/by/provider split · black / clear full size Global totals stay fixed while the explorer scopes the timeline and log; upper-left Black, lower-right Clear. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 02 390 pixels wide overview · #/by/provider split · black / clear full size Below 1200 pixels the locked bench becomes a scrolling page and the nine-item rail becomes one picker. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear.",
          "context": ""
        },
        {
          "heading": "Six readings of one ruler",
          "id": "six-readings-of-one-ruler",
          "text": "The plotted presets, the summary tiles, and the window picker that bounds them. 03 Summary tiles timelines · chart · overview split · black / clear full size The overview preset answers what the window contains before any series is drawn. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 04 Traffic timelines · chart · traffic split · black / clear full size Requests and errors share one time axis; the totals strip carries the window rate. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 05 Errors timelines · chart · errors split · black / clear full size A 429 is a rate limit, not an error; the two series stay separate. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 06 Tokens timelines · chart · tokens split · black / clear full size Cached reads are drawn beside billed input, so a high cache share is visible rather than inferred. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 07 Speed and latency timelines · chart · latenc",
          "context": ""
        },
        {
          "heading": "Nine ways into the traffic",
          "id": "nine-ways-into-the-traffic",
          "text": "The dimension rail, its cards, and one scoped reading. 10 Providers explorer · #/by/provider split · black / clear full size The rail counts distinct values; each card shows its share and the signals that matter for that dimension. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 11 Models explorer · #/by/model split · black / clear full size The model dimension applies the configured grouping rules before it counts. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 12 Clients explorer · #/by/client split · black / clear full size The client dimension answers which caller produced a share of the window. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 13 Conversations explorer · #/by/conversation split · black / clear full size Conversation filters select exact leaves; the rail reports main and sub conversations separately. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 14 Tools explorer · #/by/tool split · black / clear full",
          "context": ""
        },
        {
          "heading": "Every crossing",
          "id": "every-crossing",
          "text": "The request log, an absorbed retry, and the drawer that explains a single crossing. 20 The request log requests · #/by/model split · black / clear full size Each row is one crossing; the columns are the facts a later review needs first. Scroll the plate horizontally to see every column. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 21 An absorbed retry requests · request log · retries split · black / clear full size A retry the client never saw is still a recorded upstream attempt. Scroll the plate horizontally to see every column. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 22 The request drawer requests · drawer · request split · black / clear full size The drawer opens on the record, not on a reconstruction of it. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 23 Tokens and performance requests · drawer · usage split · black / clear full size Usage is grouped by the question it answers, so timing and tokens do not compete in one list. The plate is split diagonally: the upper-le",
          "context": ""
        },
        {
          "heading": "The operator plane",
          "id": "the-operator-plane",
          "text": "The five policy sections and the composer behind them. 25 Overview console · console · overview split · black / clear full size The overview is the register of what is in force, not a second settings form. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 26 Limits console · console · limits split · black / clear full size An empty policy surface states the state instead of hiding it. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 27 The limit composer console · console · limits split · black / clear full size A draft is local until it is committed; the composer previews the effect before a write. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 28 Pause console · console · pause split · black / clear full size A hold parks new work for a scope without changing a route. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 29 Capture console · console · capture split · black / clear full size A capture session retains bodies for a",
          "context": ""
        },
        {
          "heading": "The patch panel",
          "id": "the-patch-panel",
          "text": "Five categories of the public example configuration. 32 Dashboard settings · settings · dashboard split · black / clear full size Every field is generated from the schema, including its help and the restart badge. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 33 Queue and retry settings · settings · queue split · black / clear full size Retry policy, error classes and pacing sit together because they act on the same wait. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 34 Storage settings · settings · storage split · black / clear full size Deletion is scoped and previewed; the storage facts come from the running store. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 35 Providers settings · settings · providers split · black / clear full size Provider data is a field map in configuration, not a branch in the router. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear. 36 Backup and restore settings · settings · backup split ·",
          "context": ""
        },
        {
          "heading": "One bench, two surfaces",
          "id": "one-bench-two-surfaces",
          "text": "The shared theme tray on Black and on Clear. 37 The theme tray themes · header · theme tray split · black / clear full size Palette, surface and order come from the same registry the site publishes; the seam is the surface switch made visible. The plate is split diagonally: the upper-left half is Instrument Black, the lower-right half is Instrument Clear.",
          "context": ""
        }
      ],
      "markdown_text": "# Capture gallery\n\n<!-- Generated by python3 -m scripts.gallery.render --write from scripts/gallery/data.py and\n     docs/images/capture.json. Do not edit. -->\n\n37 plates across 7 stations, captured 16 November 2026 UTC from 100,158 recorded requests with identifiers replaced and content removed.\n\nEvery plate is one state photographed on both primary surfaces and split along the diagonal from the bottom-left corner to the top-right. The upper-left half is Instrument Black, the lower-right half is Instrument Clear. Nothing else changes between the halves: the same data, the same scroll, the same open surface.\n\nValues are a static sample from recorded history, not a benchmark. The offline indicator describes the capture session.\n\n## The whole bench\n\nThe default view at 1920 px and at phone width; every plate carries the Black and Clear surfaces across one diagonal.\n\n<figure>\n<img src=\"images/overview/dashboard.png\" alt=\"The millivolt dashboard at 1920 pixels: nine global readings above a provider explorer, a traffic timeline and a request log of recorded requests.\">\n<figcaption><strong>01 · The whole bench</strong> Global totals stay fixed while the explorer scopes the timeline and log; upper-left Black, lower-right Clear.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/overview/mobile.png\" alt=\"The dashboard at phone width, with the KPI band stacked and the explorer reduced to a dimension picker.\">\n<figcaption><strong>02 · 390 pixels wide</strong> Below 1200 pixels the locked bench becomes a scrolling page and the nine-item rail becomes one picker.</figcaption>\n</figure>\n\n## Six readings of one ruler\n\nThe plotted presets, the summary tiles, and the window picker that bounds them.\n\n<figure>\n<img src=\"images/charts/overview.png\" alt=\"The Overview preset: five tiles for volume, tokens, cost, health and speed, each with a share line and a sparkline.\">\n<figcaption><strong>03 · Summary tiles</strong> The overview preset answers what the window contains before any series is drawn.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/charts/traffic.png\" alt=\"Traffic timeline with request and error counts from recorded history.\">\n<figcaption><strong>04 · Traffic</strong> Requests and errors share one time axis; the totals strip carries the window rate.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/charts/errors.png\" alt=\"Error timeline with affected-request bars and a separate percentage axis.\">\n<figcaption><strong>05 · Errors</strong> A 429 is a rate limit, not an error; the two series stay separate.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/charts/tokens.png\" alt=\"Token timeline with input, output, reasoning and cached usage.\">\n<figcaption><strong>06 · Tokens</strong> Cached reads are drawn beside billed input, so a high cache share is visible rather than inferred.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/charts/speed-latency.png\" alt=\"Speed and latency timeline with independent axes and the p95 percentile selected.\">\n<figcaption><strong>07 · Speed and latency</strong> The percentile control applies to every measured rate in the preset.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/charts/cost.png\" alt=\"Cost timeline with spend and request-count axes.\">\n<figcaption><strong>08 · Provider-reported cost</strong> Spend is whatever the upstream reported, plotted beside the request volume that produced it.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/charts/window.png\" alt=\"The timeframe panel open over the timeline: a coverage rail, a zoom ladder from one minute to one year, and calendar presets.\">\n<figcaption><strong>09 · The window picker</strong> Windows wider than the stored history are disabled, so the picker cannot promise history that is not there.</figcaption>\n</figure>\n\n## Nine ways into the traffic\n\nThe dimension rail, its cards, and one scoped reading.\n\n<figure>\n<img src=\"images/explorer/providers.png\" alt=\"Provider explorer with pseudonymous groups, recorded costs and health signals.\">\n<figcaption><strong>10 · Providers</strong> The rail counts distinct values; each card shows its share and the signals that matter for that dimension.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/explorer/models.png\" alt=\"Model explorer with pseudonymous model groups and recorded usage metrics.\">\n<figcaption><strong>11 · Models</strong> The model dimension applies the configured grouping rules before it counts.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/explorer/clients.png\" alt=\"Client explorer with pseudonymous client groups and their recorded traffic.\">\n<figcaption><strong>12 · Clients</strong> The client dimension answers which caller produced a share of the window.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/explorer/conversations.png\" alt=\"Conversation explorer with main and sub counts and recorded request totals.\">\n<figcaption><strong>13 · Conversations</strong> Conversation filters select exact leaves; the rail reports main and sub conversations separately.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/explorer/tools.png\" alt=\"Tool explorer with recorded call counts and the traffic behind them.\">\n<figcaption><strong>14 · Tools</strong> The tool dimension counts calls the relay observed, not calls a client claimed.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/explorer/time.png\" alt=\"Time explorer with recorded buckets and their request totals.\">\n<figcaption><strong>15 · Time</strong> Time is a grouping like any other, so a bucket can be filtered and compared with the rest of the window.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/explorer/status.png\" alt=\"Status explorer with final HTTP classes and their recorded counts.\">\n<figcaption><strong>16 · Status</strong> The status dimension separates what the client received from what the upstream first returned.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/explorer/errors.png\" alt=\"Error explorer with canonical error classes and their affected request counts.\">\n<figcaption><strong>17 · Error class</strong> The error dimension groups by the proxy&#x27;s canonical class, not by provider wording.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/explorer/keys.png\" alt=\"API key explorer with pseudonymous key groups and their recorded traffic.\">\n<figcaption><strong>18 · API keys</strong> Keys are hashed in the copy, so a group is stable without exposing a credential.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/explorer/scoped.png\" alt=\"The explorer filtered to one provider, with the scope chip above the rail and the selected card marked.\">\n<figcaption><strong>19 · A scoped reading</strong> A card toggles an exact filter; the chip removes it, and the timeline and log follow the same scope.</figcaption>\n</figure>\n\n## Every crossing\n\nThe request log, an absorbed retry, and the drawer that explains a single crossing.\n\n<figure>\n<img src=\"images/requests/table.png\" alt=\"Request table with recorded statuses, token usage, latency, throughput and cost.\">\n<figcaption><strong>20 · The request log</strong> Each row is one crossing; the columns are the facts a later review needs first.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/requests/retries.png\" alt=\"The request log with one row expanded into its absorbed retry attempts, each carrying its own status and timing.\">\n<figcaption><strong>21 · An absorbed retry</strong> A retry the client never saw is still a recorded upstream attempt.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/requests/details.png\" alt=\"Request drawer showing pseudonymous identity, the summary readout and recorded request parameters.\">\n<figcaption><strong>22 · The request drawer</strong> The drawer opens on the record, not on a reconstruction of it.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/requests/performance.png\" alt=\"The same request drawer showing token and performance measurements.\">\n<figcaption><strong>23 · Tokens and performance</strong> Usage is grouped by the question it answers, so timing and tokens do not compete in one list.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/requests/diagnostics.png\" alt=\"The request drawer&#x27;s diagnostics group, with queue waits, rate-limit handling and absorbed attempts.\">\n<figcaption><strong>24 · Diagnostics</strong> The diagnostics group is where a transparent retry stops being invisible.</figcaption>\n</figure>\n\n## The operator plane\n\nThe five policy sections and the composer behind them.\n\n<figure>\n<img src=\"images/console/overview.png\" alt=\"The operator console overview with the live line, section rail and the change ledger.\">\n<figcaption><strong>25 · Overview</strong> The overview is the register of what is in force, not a second settings form.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/console/limits.png\" alt=\"The limits section with no policy set and an empty rule register.\">\n<figcaption><strong>26 · Limits</strong> An empty policy surface states the state instead of hiding it.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/console/limits-composer.png\" alt=\"The limit composer open with its scope chips, budgets, window, schedule and live preview.\">\n<figcaption><strong>27 · The limit composer</strong> A draft is local until it is committed; the composer previews the effect before a write.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/console/pause.png\" alt=\"The pause section before any hold exists.\">\n<figcaption><strong>28 · Pause</strong> A hold parks new work for a scope without changing a route.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/console/capture.png\" alt=\"The capture section with no session running.\">\n<figcaption><strong>29 · Capture</strong> A capture session retains bodies for a bounded scope and time; the panel states both.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/console/export.png\" alt=\"The export section previewing the whole-history record count and the download receipt.\">\n<figcaption><strong>30 · Export</strong> The receipt counts what the chosen mode will write before the file is produced.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/console/system.png\" alt=\"The system section with restart available and the four restart steps.\">\n<figcaption><strong>31 · System</strong> A restart is a state machine with named steps, not a button with a spinner.</figcaption>\n</figure>\n\n## The patch panel\n\nFive categories of the public example configuration.\n\n<figure>\n<img src=\"images/settings/dashboard.png\" alt=\"Settings showing the public dashboard configuration fields.\">\n<figcaption><strong>32 · Dashboard</strong> Every field is generated from the schema, including its help and the restart badge.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/settings/queue.png\" alt=\"Queue and retry Settings with their public values and field descriptions.\">\n<figcaption><strong>33 · Queue and retry</strong> Retry policy, error classes and pacing sit together because they act on the same wait.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/settings/storage.png\" alt=\"Storage Settings with the bounded writer, queue, persistence and deletion controls.\">\n<figcaption><strong>34 · Storage</strong> Deletion is scoped and previewed; the storage facts come from the running store.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/settings/providers.png\" alt=\"Provider Settings showing the public Cursor compatibility profile.\">\n<figcaption><strong>35 · Providers</strong> Provider data is a field map in configuration, not a branch in the router.</figcaption>\n</figure>\n\n<figure>\n<img src=\"images/settings/backup.png\" alt=\"Backup Settings with the download and restore rows and their scope choices.\">\n<figcaption><strong>36 · Backup and restore</strong> A restore is inspected before it is applied; the sheet says what will be replaced.</figcaption>\n</figure>\n\n## One bench, two surfaces\n\nThe shared theme tray on Black and on Clear.\n\n<figure>\n<img src=\"images/theme/tray.png\" alt=\"The shared theme tray in both surfaces: two comparison panes, a surface switch and eight palettes.\">\n<figcaption><strong>37 · The theme tray</strong> Palette, surface and order come from the same registry the site publishes; the seam is the surface switch made visible.</figcaption>\n</figure>\n"
    },
    {
      "path": "docs/protocol.md",
      "slug": "docs/protocol",
      "output": "docs/protocol.html",
      "markdown": "docs/protocol.md",
      "url": "https://millivolt.llm4people.dev/docs/protocol.html",
      "markdown_url": "https://millivolt.llm4people.dev/docs/protocol.md",
      "title": "Protocol and client integration",
      "description": "The client-facing interface accepts OpenAI Chat Completions, OpenAI Responses and Anthropic Messages; a Chat request can also target the Cursor Connect...",
      "group": "Start",
      "order": 4,
      "bytes": 49076,
      "sha256": "092402d465c5c88174df64e6137cca0575368dcc833c2986fde9f37f0f8d2baf",
      "sections": [
        {
          "heading": "Endpoint behavior",
          "id": "endpoint-behavior",
          "text": "The dashboard, embedded assets, /admin/* actions, /healthz , /readyz , the /session login handshake, the /mcp MCP endpoint and registered /metrics/* routes belong to millivolt. Their methods and meanings are listed in routes and debugging . GET /v1/models and GET /models use the discovery path described below. POST /v1/chat/completions , POST /v1/responses and POST /v1/messages select the client wire protocol. Other paths reach the relay catch-all and require valid routing headers; the client chooses the upstream endpoint and model. A known client path is translated only when X-Proxy-Format selects a different upstream protocol. An absent X-Proxy-Format selects passthrough, as does an explicit format equal to the client protocol. Without a configured request rewrite, a passthrough request's body bytes are relayed unchanged; configured request overrides, a sub-conversation strip or ensured tools can still rewrite the upstream body (see request overrides ). X-Proxy-In-Format overrides the protocol named by the path, so an otherwise unknown path is translated when that header names the inbound wire; without the override, paths outside the three known endpoints are never translated. A ",
          "context": ""
        },
        {
          "heading": "Routing headers",
          "id": "routing-headers",
          "text": "Only X-Proxy-Base-URL is required by the proxy. The upstream may require a key. Routing validation and request construction live in request_target.go and request_upstream.go . Request header Meaning X-Proxy-Base-URL Absolute HTTP(S) upstream base; no userinfo, query or fragment, including a bare trailing ? or # (a percent-encoded %23 remains path data). X-Proxy-Key Upstream key; takes precedence over Authorization . Without it, a Bearer credential or the supplied Authorization value is used. No credential is also allowed. X-Proxy-Auth-Header Key's upstream header; defaults to Authorization . The chosen name joins the credential class for that request even when its own spelling looks harmless ( X-My-Gate ): it is redacted from retained headers and skipped by request overrides like a real credential. X-Proxy-Auth-Prefix Prefix before the key; defaults to Bearer . A present empty header selects no prefix. X-Proxy-Path HTTP relay: replace the incoming path before joining it to the base URL. Cursor uses its native path rule ; model discovery replaces its default models endpoint. X-Proxy-Query HTTP relay: nonempty query override; otherwise preserve the incoming query. Model discovery use",
          "context": ""
        },
        {
          "heading": "Upstream allowlist matching",
          "id": "upstream-allowlist-matching",
          "text": "allowed_base_urls is empty (allow any target) or a list of entry spellings; each entry admits exactly one authority plus that entry's path and its children. Both sides are compared as written, with one normalization: the scheme's default port is filled in when either side has no port. Entries are validated at load into the only spellings that can ever match, and those spellings are the contract: the scheme must be literally lowercase http:// or https:// ; the host must be lowercase ASCII as written, with an optional numeric port in 1..65535 after a hostname; no userinfo, query, fragment or trailing slash; a port-less entry admits only the scheme's default port, never every port on that host. What the byte comparison does not do: lowercase the request's own host, strip a trailing dot ( example.com. and example.com differ), normalize a leading-zero port ( :080 differs from :80 ), or apply IDNA folding (the punycode or Unicode bytes must be spelled the same on both sides). A path prefix is compared on the escaped path, so percent-encoding that decodes the same is still different bytes. The joined upstream path is not cleaned either. . and .. segments from X-Proxy-Path or the incoming ",
          "context": "Routing headers"
        },
        {
          "heading": "URL and auth examples",
          "id": "url-and-auth-examples",
          "text": "For the HTTP relay, a base ending in /v1 and request path /v1/chat/completions do not produce /v1/v1/chat/completions : the join removes the shared leading segment. A path override still joins to the selected base. Use X-Proxy-Query rather than embedding a query in the base URL. For a native Anthropic-compatible endpoint, use its documented base/model/key and set translation plus the appropriate upstream auth/path/version headers: curl http://127.0.0.1:8080/v1/chat/completions \\ -H \"X-Proxy-Base-URL: $NATIVE_BASE_URL\" \\ -H \"X-Proxy-Key: $NATIVE_API_KEY\" \\ -H 'X-Proxy-Auth-Header: x-api-key' \\ -H 'X-Proxy-Auth-Prefix;' \\ -H 'X-Proxy-Path: /messages' \\ -H 'X-Proxy-Format: anthropic' \\ -H \"X-Proxy-Headers: {\\\"anthropic-version\\\":[\\\"$NATIVE_API_VERSION\\\"]}\" \\ -H 'Content-Type: application/json' \\ -d \"{\\\"model\\\":\\\"$NATIVE_MODEL\\\",\\\"messages\\\":[{\\\"role\\\":\\\"user\\\",\\\"content\\\":\\\"hello\\\"}]}\" The example assumes JSON-safe model/version values. The semicolon in -H 'X-Proxy-Auth-Prefix;' is important: curl sends a present empty header. -H 'X-Proxy-Auth-Prefix:' instead omits it, leaving the proxy's Bearer default. See the official curl header guide . An unauthenticated local upstream needs no ",
          "context": ""
        },
        {
          "heading": "Relay, retries and model discovery",
          "id": "relay-retries-and-model-discovery",
          "text": "Ordinary requests relay the original body bytes unless a configured request override, sub-conversation strip or ensured-tools rule rewrites them; the request is buffered up to max_request_bytes before metadata extraction and sending. Larger requests are rejected with HTTP 413 without an upstream send. A decoded output cap above 1,000,000 tokens is rejected with HTTP 400 the same way, before any upstream send and at both trust boundaries - the original body's decode and the re-decode of a translated body - for any spelling ( max_tokens , max_completion_tokens or max_output_tokens ). A body that combines the Responses max_output_tokens spelling with a Chat max_tokens or max_completion_tokens spelling is rejected with HTTP 400 before an upstream send because the wire families are ambiguous. More than one top-level member that folds to the same cap name is also rejected with HTTP 400 before an upstream send, including case variants and escaped spellings: the relay sends every occurrence, so accepting duplicates would let the validated and recorded value differ from the bytes the upstream reads. A valid request is also rejected with HTTP 400 before an upstream send when it carries more ",
          "context": ""
        },
        {
          "heading": "Scheduling and timing",
          "id": "scheduling-and-timing",
          "text": "The provider-plus-key group controls simultaneous upstream sends and its waiting queue. A separate limit policy can apply to the whole provider or narrow to models, clients, key hashes and conversations, with an optional recurring server-local schedule; a provider-only rule combines all keys and clients. Queue capacity and wait limits can reject work locally; the configured queue_retry_after duration (for example 2s , never a bare integer) supplies the caller's retry hint. Operator-hold time is excluded from the ordinary queue-wait limit. A hold's own queue cap still applies. For the HTTP relay, upstream_timeout limits waiting for response headers, not the streaming body. X-Proxy-Timeout-Ms instead gives each upstream send a fresh deadline covering headers and body. Neither is a total end-to-end deadline across queueing, holds, retries and backoff; client cancellation is the way to stop the whole request. The request-body progress bound applies only while the body is being read. Reaching EOF or closing the body clears the connection read deadline, so a long-lived response stream is never cut by the upload guard. The Cursor bridge instead applies the tighter configured/per-request t",
          "context": "Relay, retries and model discovery"
        },
        {
          "heading": "Error storm protection",
          "id": "error-storm-protection",
          "text": "Enable storm_enabled in Settings to add shared provider/model protection to existing admission and retry pacing. Requests wait in the proxy with the caller connected; this is not a client SDK queue. The proxy keeps the existing bounded request bytes and credentials only for the request lifetime. Queues are in memory, cannot survive a restart, and stop waiting when the caller cancels. Each exact recorded model name within its resolved provider has a rolling storm_window . A model qualifies when its sampled attempts meet storm_min_samples and its selected-failure percentage reaches storm_error_percent . Provider-wide protection requires every active model to qualify, as well as the aggregate sample/rate threshold. Only models receiving requests within that same window are active; an idle model or an unused model in a provider catalog cannot affect that decision. This scope combines credentials and clients. Dashboard model-display rewrites do not merge storm scopes. The detector samples successful upstream attempts and selected failures, counting absorbed retries separately. Incident details also count distinct logical requests with a selected failure in the window; retries move the s",
          "context": "Relay, retries and model discovery"
        },
        {
          "heading": "Model discovery",
          "id": "model-discovery",
          "text": "GET /v1/models and GET /models are constructed discovery services, not ordinary inference records. The proxy normalizes recognized model lists, translates native formats, completes supported pagination, and optionally enriches missing fields. Unrecognized successful list bodies remain verbatim; primary discovery budget/errors fail explicitly, while optional enrichment can fall back to the complete base list. Discovery can apply limit headers without consuming an inference slot. Its time/byte/page/entry limits are configuration-owned. Primary and enrichment entries share one models_discovery_max_entries budget (default 10,000); enrichment degrades to the base list when the remaining budget cannot hold its metadata source. The rendered list is bounded by models_discovery_max_bytes plus a fixed per-entry normalization allowance (512 bytes for each configured entry) and is encoded without HTML escaping, so literal < , > , and & keep their wire size. A rendered list past that derived bound fails closed before any response bytes are written. Discovery addresses the format's own models endpoint regardless of translation: /v1/models on the shared base join, Anthropic's pagination query, or",
          "context": "Relay, retries and model discovery"
        },
        {
          "heading": "Main and sub-conversations",
          "id": "main-and-sub-conversations",
          "text": "",
          "context": ""
        },
        {
          "heading": "Automatic grouping",
          "id": "automatic-grouping",
          "text": "An explicit X-Proxy-Session takes precedence, then a configured tracked body param (see tracked body params ). Without either, the tracker partitions requests by client label and credential hash, then compares total user/assistant/tool turn counts against its open conversations. A nonexpired conversation with the greatest previous count no larger than the new count is the nearest match. A reset or idle gap can start another conversation, and the configured open-session cap evicts the oldest tracked conversation in that partition. This is a heuristic for clients that send conversation history, not a content comparison or a universal agent identity. Parallel tasks with similar turn counts can be ambiguous. Tracker state is process-local, so use explicit session IDs when predictable continuity matters and keep the client/key namespace stable. Automatic grouping never establishes a parent/child relationship.",
          "context": "Main and sub-conversations"
        },
        {
          "heading": "Tracked body params",
          "id": "tracked-body-params",
          "text": "The request body is client data, and one field can double as the conversation identity. When sub_conversations names the request's classified client, the tracked field the client already sends (exemplar: opencode's promptCacheKey ) supplies that request's identity in the k: namespace: behind an explicit X-Proxy-Session , ahead of automatic grouping. Params match only top-level body fields, checked in order. The first present field decides: a present value that is not a JSON string counts as absent and the next field is checked, while a present string that cannot be decoded or fails the identity rules drops the identity for the request - no later field is consulted. A top-level field that occurs more than once is ambiguous and drops the identity the same way, leaving the request on automatic grouping. The body is relayed unchanged unless the entry sets strip , which removes the entry's configured fields from the top level of the client request body before relay or translation. It applies to any JSON body, including a Responses client body. A request translated to the Anthropic wire gains a top-level prompt_cache_key carrying the tracked value. That field is a proxy tracking extensio",
          "context": "Main and sub-conversations"
        },
        {
          "heading": "Declaring a parent",
          "id": "declaring-a-parent",
          "text": "A parent sends X-Proxy-Session: main-task . Its child sends its own X-Proxy-Session: worker-1 plus X-Proxy-Parent-Session: main-task , using the same client label and API key. Send IDs without the stored s: prefix. When declaring a parent, both headers must occur once, contain nonempty valid UTF-8 without controls, differ from each other, and fit 512 bytes after trimming. Self-parent/invalid declarations return 400. The parent header is proxy-only; it neither edits the body nor instructs an upstream to create a child agent. The server resolves observed relationships within (client, key_hash, conversation_id) , including history outside the selected view. The explorer reports main/sub/unresolved counts and role/parent metadata. A missing parent is not observed , not an invented main. Conflicts, cycles or ambiguous reused IDs remain unresolved. “Main” means no parent declared in observed history, not independently verified orchestration. Parent links preserve the full representable client/key namespace. Conversation filters remain exact leaves, never descendant filters. A changed credential can change the namespace. Historical parentage cannot be inferred from absent data, message si",
          "context": "Main and sub-conversations"
        }
      ],
      "markdown_text": "# Protocol and client integration\n\nThe client-facing interface accepts OpenAI Chat Completions, OpenAI Responses\nand Anthropic Messages; a Chat request can also target the Cursor Connect\nbridge. The upstream-facing protocol can differ from any of\nthem. Per-request headers select the destination, credentials and optional\nnative adapter.\n\nThe [compatibility matrix](adapters.md#client-and-upstream-compatibility)\nmaps the supported combinations; [cross-protocol translation](adapters.md#cross-protocol-translation)\ndocuments the canonical model and its loss policy. No endpoint/API-key registry\nis required. Read\n[Security](../SECURITY.md): routing credentials do not authorize operator access,\nand the whole dashboard plane is gated by `MILLIVOLT_OPERATOR_TOKEN`\n([operator access](routes.md#operator-access)); only `/healthz` and\n`/readyz`, `/favicon.ico` (and the other origin-root brand/PWA files), the\n`/session` login handshake and the relay stay open.\n\n## Endpoint behavior\n\nThe dashboard, embedded assets, `/admin/*` actions, `/healthz`, `/readyz`, the\n`/session` login handshake, the `/mcp` MCP endpoint and registered `/metrics/*`\nroutes belong to millivolt. Their methods and meanings are listed in\n[routes and debugging](routes.md#operator-and-data-routes). `GET /v1/models` and\n`GET /models` use the discovery path described below. `POST /v1/chat/completions`,\n`POST /v1/responses` and `POST /v1/messages` select the client wire protocol.\nOther paths reach the relay catch-all and require valid routing headers; the\nclient chooses the upstream endpoint and model.\n\nA known client path is translated only when `X-Proxy-Format` selects a\ndifferent upstream protocol. An absent `X-Proxy-Format` selects passthrough, as\ndoes an explicit format equal to the client protocol. Without a configured\nrequest rewrite, a passthrough request's body bytes are relayed unchanged;\nconfigured request overrides, a sub-conversation strip or ensured tools can\nstill rewrite the upstream body (see\n[request overrides](configuration.md#request-overrides)).\n\n`X-Proxy-In-Format` overrides the protocol named by the path, so an otherwise unknown path\nis translated when that header names the inbound wire; without the override,\npaths outside the three known endpoints are never translated.\n\nA translated request addresses the outbound protocol's canonical\nendpoint (`/v1/chat/completions`, `/v1/responses` or `/v1/messages`) instead of\nforwarding the client's path, unless `X-Proxy-Path` overrides that endpoint. A same-protocol request on one of those three\nendpoints normalizes to the same canonical spelling, while one on any other path\nkeeps the path the client chose.\n\nThe path is matched in its escaped spelling, so\nan encoded spelling of a known route (for example `/v1%2Fchat%2Fcompletions` or\n`/v1%2Fmodels`) is an unknown path: on a same-protocol passthrough, or when no\ninbound override is present, it is relayed unchanged and is never normalized,\ntranslated or treated as model discovery.\n\nWhen `X-Proxy-In-Format` selects a\nwire that differs from `X-Proxy-Format`, the request is a translation like any\nother and addresses the outbound protocol's canonical endpoint. A base URL with\na path joins by comparing the first client segment's decoded spelling with the\nbase's last segment, so an encoded client spelling of that segment can be\ndropped from the joined upstream path.\n\nForwarding a body is not the same as understanding every field in it. The normal\nrelay does not rewrite an unfamiliar JSON shape just to observe it, but usage,\nfirst-token timing and quality classification depend on recognized formats.\nNative translation is explicit and narrower than arbitrary HTTP forwarding.\nThere is no automatic provider failover or model-selection registry.\n\n## Routing headers\n\nOnly `X-Proxy-Base-URL` is required by the proxy. The upstream may require a key.\nRouting validation and request construction live in\n[request_target.go](../internal/proxy/request_target.go) and\n[request_upstream.go](../internal/proxy/request_upstream.go).\n\n| Request header | Meaning |\n| --- | --- |\n| `X-Proxy-Base-URL` | Absolute HTTP(S) upstream base; no userinfo, query or fragment, including a bare trailing `?` or `#` (a percent-encoded `%23` remains path data). |\n| `X-Proxy-Key` | Upstream key; takes precedence over `Authorization`. Without it, a Bearer credential or the supplied Authorization value is used. No credential is also allowed. |\n| `X-Proxy-Auth-Header` | Key's upstream header; defaults to `Authorization`. The chosen name joins the credential class for that request even when its own spelling looks harmless (`X-My-Gate`): it is redacted from retained headers and skipped by request overrides like a real credential. |\n| `X-Proxy-Auth-Prefix` | Prefix before the key; defaults to `Bearer `. A present empty header selects no prefix. |\n| `X-Proxy-Path` | HTTP relay: replace the incoming path before joining it to the base URL. Cursor uses its [native path rule](adapters.md#cursor-connect-bridge); model discovery replaces its default models endpoint. |\n| `X-Proxy-Query` | HTTP relay: nonempty query override; otherwise preserve the incoming query. Model discovery uses it for the upstream discovery call; Cursor ignores it. |\n| `X-Proxy-Headers` | HTTP-relay header overrides as a JSON object of string arrays, e.g. `{\"x-example-version\":[\"2026-01\"]}`. `accept-encoding` and `range` are proxy-owned and rejected with 400. A JSON `null` member is treated as an omitted header. Values are JSON-decoded, so a raw obs-text byte (0x80..0xFF) that is not valid UTF-8 reaches the wire as U+FFFD instead of its original byte; send the UTF-8 spelling if the byte matters. Not applied to model discovery or the Cursor bridge. |\n| `X-Proxy-Timeout-Ms` | Positive milliseconds. HTTP relay: a fresh headers-and-body deadline per attempt, excluding queue/hold/backoff waits. Cursor applies it only to send header waits; model discovery uses its separate configured budget. |\n| `X-Proxy-Format` | Upstream format: `openai` (Chat Completions), `openai-responses` (Responses), `anthropic` (Messages), or `cursor` (agent.v1). Absent means passthrough; configured request rewrites can still change the body. See [supported combinations](adapters.md#client-and-upstream-compatibility). |\n| `X-Proxy-In-Format` | Optional client-protocol override: `openai`, `openai-chat` or `chat` (Chat Completions), `openai-responses` or `responses` (Responses), or `anthropic` (Messages). Aliases normalize to the canonical wire. Normally unnecessary because the request path selects the protocol. |\n| `X-Proxy-Client` | Observability/client label; one that only repeats the user agent's product name records the fuller user-agent identity instead. Otherwise inferred from client SDK/User-Agent metadata. |\n| `X-Proxy-Session` | Explicit conversation ID; otherwise a configured tracked body param or automatic grouping applies. |\n| `X-Proxy-Parent-Session` | Direct declared parent; requires an explicit own session on the same request. |\n| `X-Proxy-Max-Concurrency` | Positive provider-plus-key scheduler-group cap. Each admission updates the shared group's policy; later admissions, including headerless ones using config defaults, can replace it. Not the persistent operator limit policy, and not applied to model discovery, which returns before inference admission. |\n| `X-Proxy-Limit-Concurrency` | Sticky provider-wide in-flight cap. |\n| `X-Proxy-Limit-Requests` | Sticky provider-wide request rate as `COUNT/WINDOW`. |\n| `X-Proxy-Limit-Tokens` | Sticky provider-wide token rate as `COUNT/WINDOW`. |\n| `X-Proxy-Refresh-Token` | Opt-in stateless expired-token refresh for supported mechanisms. See [refresh](adapters.md#token-refresh). |\n\nEvery `X-Proxy-*` routing, limit and format header is read with first-value\nsemantics: when a request carries the header more than once, the first value is\nauthoritative and later values are ignored. The rule is deterministic across\nthe whole control prefix, including `X-Proxy-Query` and `X-Proxy-Headers`.\n\n### Upstream allowlist matching\n\n`allowed_base_urls` is empty (allow any target) or a list of entry spellings;\neach entry admits exactly one authority plus that entry's path and its children.\nBoth sides are compared as written, with one normalization: the scheme's\ndefault port is filled in when either side has no port. Entries are validated\nat load into the only spellings that can ever match, and those spellings are\nthe contract:\n\n- the scheme must be literally lowercase `http://` or `https://`;\n- the host must be lowercase ASCII as written, with an optional numeric port in\n  1..65535 after a hostname;\n- no userinfo, query, fragment or trailing slash;\n- a port-less entry admits only the scheme's default port, never every port on\n  that host.\n\nWhat the byte comparison does not do: lowercase the request's own host, strip a\ntrailing dot (`example.com.` and `example.com` differ), normalize a leading-zero\nport (`:080` differs from `:80`), or apply IDNA folding (the punycode or Unicode\nbytes must be spelled the same on both sides). A path prefix is compared on the\nescaped path, so percent-encoding that decodes the same is still different\nbytes.\n\nThe joined upstream path is not cleaned either. `.` and `..` segments from\n`X-Proxy-Path` or the incoming path travel verbatim, and an upstream that\nnormalizes request paths resolves them after the proxy has already allowed the\nbase. `X-Proxy-Path: /../../admin` under an entry for `http://host/v1` is sent\nas `/v1/../../admin` and reaches `/admin` at such an upstream, outside the\nallowlisted path prefix. The authority stays allowlisted either way; only the\npath prefix can be left.\n\n\nClient identity labels are retention-bounded before the record enters the live\nring, analytics or durable store: classified client and language 256 bytes,\nuser agent 1024 bytes, and `client_ip` 128 bytes. Longer values\nare cut on a UTF-8 boundary and end with `…`; normal labels are unchanged.\n`client_ip` records the first `X-Forwarded-For` element when that header is\npresent and the socket peer otherwise; the value is diagnostic, never verified,\nand a directly reachable caller can set it.\n\nFinalized and pending record text is retention-bounded at the record boundary\nbefore it enters the live ring, pending view or durable store:\n\n- path 1024 bytes, method 32 bytes;\n- provider label, model, provider model, provider request id,\n  provider server, finish reason, error type, error code, error message, request\n  tool choice, response format, service tier and last turn role 512 bytes each;\n- each tool name 128 bytes with at most 64 retained in order;\n- debug session id 128 bytes;\n- conversation identifiers 512 bytes before the namespace prefix\n  (retained identifier 514 bytes).\n\nAbsorbed-attempt provider model, provider\nrequest id, provider server, error type, error code and error message use the\nsame 512-byte bound; provider labels and attempt error messages are bounded at\nthe same record boundary. Longer values are cut on a UTF-8 boundary and end\nwith `…`; normal values are unchanged. These record bounds do not alter debug\ncapture bodies, retained headers, content previews or request-parameter JSON.\n\nOne caller setting `X-Proxy-Limit-*` affects every key/client of that provider.\nAbsent headers preserve limits. A present `X-Proxy-Max-Concurrency` or\n`X-Proxy-Timeout-Ms` value follows Go's HTTP field parsing: leading and\ntrailing optional whitespace is removed before the handler reads it, so a\nwhitespace-only value arrives empty and is treated as absent, while a padded\nnumeric value is read as its trimmed spelling. `0`, `off`, `none` or\n`unlimited` clear a `X-Proxy-Limit-*` policy.\n\nWindows accept Go durations from 1 second through 24 hours, plus `1d`.\nAnti-burst and its ramp duration are operator API policy (`/admin/throttle`, the\ndashboard and MCP), not header-driven; a header update changes only the three\ncaps and preserves the stored pair. The ramp is inert unless `anti_burst` is\ntrue, the concurrency target is at least 2 and `ramp_duration` is above 0, and\nits duration uses that same window grammar.\n\nMalformed limit values reject the\nrequest without applying any of its limit headers. A header update edits only\nthat provider's single-provider, unscheduled rule; operator rules scoped by\nmodel, client, key hash, conversation or schedule are untouched. The operator\nconsole shows every policy, its schedule and its source.\n\nRequest rates are strict sliding windows over the\nconfigured length, so no window ever admits more than the configured count;\ntoken rates remain continuously refilled budgets. See\n[Pause and Limits](routes.md#pause-and-limits) for charging and window\nbehavior.\n\nSupported proxy-control headers never forward upstream. Injected names must be\nvalid, unique case-insensitively, and not reserved control, framing\n(`content-length`), hop-by-hop or Host names; values must be valid HTTP field\nvalues. Ordinary hop-by-hop and Connection-nominated headers are removed.\nPrecedence depends on the request path:\n\n| Path | Header precedence, lowest to highest |\n| --- | --- |\n| HTTP relay, including Anthropic translation | Forwarded values → extracted authentication → configured provider headers → explicit injection → matching request overrides. Configured/injected authentication can override the extracted key. |\n| HTTP model discovery | Constructed authentication → configured provider headers. Explicit injection and request overrides are not applied. |\n| Cursor run/model discovery | Configured headers → matching request overrides (runs only) → required protocol/framing headers and extracted authentication when a key is present. Explicit injection is not applied. |\n\nThe provider label is server-derived from the base host's registrable domain;\nIPs retain their authority/port, and nonregistrable hostnames remain hostnames.\nOptional provider aliases apply afterward. There is no supported\n`X-Proxy-Provider` override.\n\n`Host` is the one name with a different mechanism rather than a different\nprecedence: it is accepted in a provider `headers` map and written to the\nrequest's host field, not its header map, because `net/http` sends the former\nand ignores the latter. A configured host, port included, is the authority the\nupstream sees on both paths above. The explicit `X-Proxy-Headers` map and an\n`X-Proxy-Auth-Header` still refuse `Host`, and no request override may set it.\n\n## URL and auth examples\n\nFor the HTTP relay, a base ending in `/v1` and request path\n`/v1/chat/completions` do not produce\n`/v1/v1/chat/completions`: the join removes the shared leading segment.\nA path override still joins to the selected base. Use `X-Proxy-Query` rather\nthan embedding a query in the base URL.\n\nFor a native Anthropic-compatible endpoint, use its documented base/model/key\nand set translation plus the appropriate upstream auth/path/version headers:\n\n```sh\ncurl http://127.0.0.1:8080/v1/chat/completions \\\n  -H \"X-Proxy-Base-URL: $NATIVE_BASE_URL\" \\\n  -H \"X-Proxy-Key: $NATIVE_API_KEY\" \\\n  -H 'X-Proxy-Auth-Header: x-api-key' \\\n  -H 'X-Proxy-Auth-Prefix;' \\\n  -H 'X-Proxy-Path: /messages' \\\n  -H 'X-Proxy-Format: anthropic' \\\n  -H \"X-Proxy-Headers: {\\\"anthropic-version\\\":[\\\"$NATIVE_API_VERSION\\\"]}\" \\\n  -H 'Content-Type: application/json' \\\n  -d \"{\\\"model\\\":\\\"$NATIVE_MODEL\\\",\\\"messages\\\":[{\\\"role\\\":\\\"user\\\",\\\"content\\\":\\\"hello\\\"}]}\"\n```\n\nThe example assumes JSON-safe model/version values. The semicolon in\n`-H 'X-Proxy-Auth-Prefix;'` is important: curl sends a present empty header.\n`-H 'X-Proxy-Auth-Prefix:'` instead omits it, leaving the proxy's Bearer default.\nSee the [official curl header guide](https://everything.curl.dev/http/modify/headers.html).\nAn unauthenticated local upstream needs no dummy API key.\n\n## Relay, retries and model discovery\n\nOrdinary requests relay the original body bytes unless a configured request\noverride, sub-conversation strip or ensured-tools rule rewrites them; the\nrequest is buffered up to `max_request_bytes` before metadata extraction and\nsending. Larger requests are rejected with HTTP 413 without an upstream send.\nA decoded output cap\nabove 1,000,000 tokens is rejected with HTTP 400 the same way, before any\nupstream send and at both trust boundaries - the original body's decode and\nthe re-decode of a translated body - for any spelling (`max_tokens`,\n`max_completion_tokens` or `max_output_tokens`).\n\nA body that combines the\nResponses `max_output_tokens` spelling with a Chat `max_tokens` or\n`max_completion_tokens` spelling is rejected with HTTP 400 before an upstream\nsend because the wire families are ambiguous. More than one top-level member\nthat folds to the same cap name is also rejected with HTTP 400 before an\nupstream send, including case variants and escaped spellings: the relay sends\nevery occurrence, so accepting duplicates would let the validated and recorded\nvalue differ from the bytes the upstream reads.\n\nA valid request is also\nrejected with HTTP 400 before an upstream send when it carries more than 10,000\nentries in a `messages`, `tools`, `functions`, `input`, `stop`,\n`stop_sequences` or `modalities` array, more than 10,000 members in a\n`metadata` or `stream_options` object, more than `request_tool_calls_max`\naggregate `tool_calls` members across every message (default 1,024), more than\n10,000 distinct top-level\nmembers, or more than 10,000 distinct `logit_bias` keys merged across duplicate\ntop-level objects. Those preflight bounds apply to native and translated\nrequests alike.\n\nA translated request also passes through its protocol codec,\nwhich rejects with HTTP 400 more than 10,000 entries in a Responses `include`\narray or in a tool `allowed_callers` array, or more than 4,096 blocks in an\nAnthropic `system` list.\n\nA native passthrough without a configured body\nrewrite does not apply those codec-only collection bounds: the body is relayed\nunchanged, so there is no materialization to bound. A configured\n`request_overrides` rule, a sub-conversation strip or an ensured tool can still\nrewrite that body, but those rewrites are not a codec decode.\n\nContent composition has two independent limits. A content array above 4,096\nparts is not rejected for that reason on the byte-transparent passthrough\npath: within the aggregate budget it still relays unchanged, but composition\nskips it, so it contributes no dashboard composition counts. On a translated\nrequest the codec applies its own limit: Chat drops the oversized content\nwith a warning, while Responses and Anthropic reject the request with HTTP\n400; `translation_loss: reject` turns any recorded loss into a 400.\n\nComposition reads the Chat `messages`/`system`\nand Anthropic `messages`/`system` shapes; a byte-transparent Responses body's\n`input`/`instructions` items contribute no composition counts (their model,\nstream flag and output cap are still recorded).\n\nSeparately, the aggregate\ncontent-part count over every message content array, a top-level `system`\narray and every Responses `input` item's nested `content`/`output` array is\ncapped at 16,384. Each Responses annotation array is capped at 4,096 members,\nand their aggregate inside those content parts is capped at 10,000.\n\nAnthropic citation arrays are capped at 10,000 members per array, and every\ncitation array in one document shares a 10,000-member aggregate.\n\nEach nested\ncontent array is capped at 4,096 blocks, and the nested content blocks of\none document share a separate 10,000-block aggregate; the citation and\nnested-block aggregates are independent, so their combined total can reach\n20,000. A document block's citations configuration object is reported as a\ndropped field instead of being decoded into text citations. A valid request\nabove any of these limits is rejected with HTTP 400 before an upstream send.\n\nInvalid JSON is passed through on the nontranslated path.\nSyntactically valid JSON whose strings carry raw invalid UTF-8 is bounded the\nsame way: valid UTF-8 and JSON escapes decode to no more bytes than their\nspelling, while the standard decoder replaces each invalid byte with a\nthree-byte U+FFFD.\n\nA body whose decoded strings would exceed its uploaded size\nby more than a small internal allowance is rejected with HTTP 400 before an\nupstream send; smaller invalid sequences remain accepted on the passthrough\npath, where a tracked value that fails the identity rules is still dropped\nrather than rejected.\n\nAnthropic translation requires the whole request body to\nbe valid UTF-8 and rejects a raw invalid byte before decoding it.\n\nThe proxy can retry transient transport failures, 429 and 5xx before\nreturning the final response, and retryable in-band error events on an open\nstream before any generation content was relayed.\n\nDurable quota/billing 429s follow `quota_pause_mode` instead of the transient retry ladder:\n`off` (default) surfaces them immediately; `retry` parks the triggering request\nand every new request to the same OpenAI-wire provider behind a recovery\ngate that closes after `quota_pause_recovery_successes` consecutive successful probes (the default 1\ncloses on the first 2xx); a provider `Retry-After` on the quota response paces the\nnext probe like any other 429; `manual` installs an indefinite provider pause\nthat only an operator resumes. Quota re-sends never burn the transient retry\nbudget.\n\nProvider retry hints and operator holds can substantially extend total wall\ntime.\n\nWith `suppress_client_retries` the proxy declares itself the client's sole retry authority: every\nerror response the relay returns then carries `x-should-retry: false`, the official OpenAI SDK\nconvention (python, node, go and ruby honor it from source), which overrides\nthe SDKs' 408/409/429/5xx auto-retry defaults and any `Retry-After`, including a\nprovider hint that would otherwise relay verbatim.\n\nNo response exists to carry the directive on transport-level failures,\nclients that ignore the header (the Vercel AI SDK / opencode stack, whose\nretry policy is status- and body-text driven) keep their own policy, and\nmid-stream SSE errors never auto-retry in official SDKs and cannot carry new\nheaders.\n\nSuccess responses are untouched, and the setting hot-reloads for new\nresponses.\n\nOne classifier owns every error decision: the retry ladder, the storm\nobserver, the health counts and the client-facing class all read the same\ncanonical class (`rate_limit`, `quota`, `unavailable`, `unreachable`,\n`timeout`, `content`, `client_error`, `proxy`, `canceled`, `upstream`),\ncomputed from the status, the provider's own structured type/code, and - for\na transport failure with no response at all - the transport kind, which is\n`unreachable` or, for a timed out send, the narrower `timeout`.\n\nTransport evidence outranks the proxy-minted arm, so a failure with no\nprovider answer is never filed as a proxy fault and never advised against a\nretry. Message text plays no part except for that transport timeout\nnarrowing.\n\nA rate limit announced by a non-429 status (a gateway answering `tier_limit_exceeded` or `resource_exhausted`\nwith a 400) is therefore retried, counted in the rate-limit series (and,\nbecause the request still failed, in the error rate), and labeled `rate_limit`\ninstead of `client_error`.\n\nWith `client_error_class: header` every error status the relay returns also carries `X-Proxy-Error-Class: <class>` and a\nclass-derived `X-Should-Retry: true|false` before the status line commits (the body is never\nrewritten; relayed errors stay verbatim), while `suppress_client_retries` still wins with a flat\n`false`. The directive is the class's own retry verdict, not a re-reading of the\nstatus:\n\n| Class | `X-Should-Retry` | Why |\n| --- | --- | --- |\n| `rate_limit` | `true` | transient flow control at any status |\n| `unavailable` | `true` | transient capacity or server failure |\n| `unreachable` | `true` | transport failed with no usable response, including a fresh send whose peer closed the socket |\n| `timeout` | `true` | the send or read deadline fired |\n| `content` | `false` | a 2xx with nothing usable; retried on the quality/thinking budgets instead |\n| `quota` | `false` | waiting does not clear it; `quota_pause_mode` owns the reaction |\n| `client_error` | `false` | the caller's own fault |\n| `proxy` | `false` | millivolt's own failure |\n| `canceled` | `false` | the local client left |\n| `upstream` | `false` | unclassified upstream failure, final by default |\n\nTwo settings extend the built-in vocabularies with gateway-specific\nspellings, additively: `rate_limit_error_classes` and `quota_error_classes` (plus the existing `retryable_error_classes` for in-band\ntransient errors). Entries are matched case-insensitively against the parsed\nenvelope's type and code; validation rejects a spelling that names a\nbuilt-in of a different class, so a built-in classification can never be\nmoved or weakened (the one exception is `retryable_error_classes` naming a built-in client-fault\nspelling, the documented override for a gateway that mislabels transient\nfailures).\n\nReload applies to new classifications, and the published predicates render\nper call, so they re-read stored history through the same effective\nvocabulary.\n\nA failed response's reason is read from the provider's own body, in two layers.\nThe OpenAI/Anthropic envelope (`{\"error\":{\"message\",\"type\",\"code\"}}`,\n`{\"type\":\"error\",\"error\":{…}}`, or a plain-string `\"error\"`) always wins and\nsupplies type, code and message.\n\nWhen the body carries no such envelope, the\nfailure path still recovers a human-readable reason from the members gateways\ncommonly use:\n\n- a top-level `detail`, `message`, `msg`, `reason` or\n  `error_description` string;\n- a FastAPI validation `detail` array (the first\n  item's `msg`);\n- Cloudflare's `errors` array (`message`, with its numeric\n  `code`).\n\nNested lookups are depth-bounded, a wrong-typed member is ignored\nrather than stringified, and every reason is truncated to the same record bound\nas an envelope message.\n\nA body that is valid JSON but carries no extractable\nreason stays classified as `provider_error` with no message, and an empty body\nstays unclassified - only the status remains.\n\nThis recovery runs only where the\nresponse is already known to have failed; the success paths keep treating\nthose same bodies as non-errors, so a 2xx completion carrying a top-level\n`message` is never mistaken for a failure.\n\nAn error body that cannot be read at all does not erase what the status already\ndecided. A `429` keeps both its status and the rate-limit series, because the\nstatus alone is flow control; other statuses fail closed to a `502`, and a\nprovider-decided type survives a later body-read or translation failure instead\nof being replaced by the proxy's `stream_read_error`.\n\nSSE pacing may insert comment keepalives. A known queue/hold wait may commit HTTP\n200 before the final upstream outcome, so a subsequent failure must be signaled\nin-band. Bounded terminal/quality handling can replace a degenerate completion\nwith an error.\n\nRelay framing follows SSE's own join rule: the data lines of one\nevent are joined with a newline, so a multi-line (pretty-printed) payload stays\none event and a synthetic blank separator is inserted only when the event's\njoined data is already one complete JSON document, or before the `[DONE]`\nsentinel.\n\nThe completeness check is incremental, so one long event costs linear\ntime in its bytes rather than quadratic in its line count; a bare scalar counts\nonly when it is exactly `true`, `false`, `null` or one well-formed number, so a\nprose line that merely starts with one of those bytes (`the cat`, `3 apples`)\nstays open for its continuation lines. Two single-line\nevents a provider sent without a separator therefore\nstay two events instead of merging into an unparseable payload.\n\nNon-streaming quality retries may make another upstream request;\nthe adopted attempt's response is spooled under the fixed 1 MiB quality buffer\nbefore the client status line commits, so the retry is delivered as one\nordinary response with no post-commit keepalive gap or partial payload.\n\nA stream truncated before any generation content was relayed is re-sent on\nthe same committed connection, while a truncation after relayed content\nsurfaces the in-band error for the client to retry. A trailing partial line\nthat a rescue or the degenerate terminal boundary drops was never delivered,\nso it neither counts as relayed content nor as the record's answer content\nor first-answer time, and it does not veto the re-send; only a delivering\npath feeds and writes it, exactly once.\n\nOnly the truncation class is decided before\nthat feed, and only when the analyzer's non-committing tail classifier says the\nline carries no completion terminal marker: a final Chat `[DONE]` or non-null\n`finish_reason` without a trailing newline is fed rather than dropped.\n\nA fed tail is delivered only when it supplies a complete answer or tool\ncall; an empty or reasoning-only completion resolves through the degenerate\nboundary, which withholds or replaces the terminal bytes. A terminal tail is\nclassified before the pre-content rescues, so it is never re-sent.\n\nA delivered tail is written as its own complete SSE event: a pending event\nis closed first and a blank boundary follows, on clean EOF and on a read\nerror. Answer content that the source places after its finish marker is\ntherefore relayed as a later event, and a client that stops at the finish\nreason may ignore it.\n\nA terminator-less partial line\nthat carries neither a completion terminal marker nor a completion is not\ndelivered, so the stream reports truncation rather than a completion or\nprovider error the client never saw. A standalone in-band error line is not a\ndelivery terminal and is dropped the same way, and a `[DONE]` on a Responses\nfeed is not its terminal marker, so it is also dropped as truncation.\n\nA translated streaming request whose 200 response body is not SSE is still\nrelabelled `text/event-stream`: the upstream bytes are never converted into SSE\nframes, and the relay surfaces the non-SSE body as a truncated-stream error\nrather than translating it.\n\nA provider error event streamed\nin-band on the 200 is retried the same way while nothing content-bearing was\nrelayed: the same availability and timeout vocabulary the status path treats\nas retryable (500 `server_error`, the 503 overloaded/unavailable family, the\ntimeout spellings, the equivalent Anthropic/gateway spellings including\n`bad_gateway`, `gateway_timeout` and `upstream_error`, and the\n`engine_overloaded` capacity code) is dropped before the wire and the request\nre-sent, so the client never sees the failure.\n\nA specific capacity code\noverrides the generic\n`invalid_request_error` wrapper, because the code names a transient overload\nrather than a malformed request; authentication, permission, not-found and\ntoo-large types stay final.\n\nThe `retryable_error_classes` setting extends that vocabulary with operator-supplied type or code\nstrings for gateway-specific spellings (durable quota/billing classes are\nrejected at load); rate limits in-band (no `Retry-After` exists there), durable\nrequest/billing classes, unknown types, Responses-API feeds once any of\ntheir events was relayed (per-response sequence numbers), and errors after\nrelayed contract bytes relay verbatim for the client to handle.\n\nMid-thinking rescues (`thinking_retries`) extend the re-send to requests that die or end\nwithout an answer during the reasoning phase: a truncation or upstream read\nerror after reasoning-only output, a cleanly finished reasoning-only\ncompletion (the withheld terminal region is replaced by the fresh attempt),\nand a retryable in-band error that arrived after reasoning-only output.\n\nThe fresh stream appends behind the already-relayed reasoning, which is\nauxiliary display text; answer content, tool calls, refusals, `finish_reason: length` (the\nclient's own token cap) and Responses-API feeds (per-response sequence\nnumbers) are never rescued.\n\nAn exhausted budget surfaces the\n`reasoning_only` class as a provider error (`upstream_error`) on both\nsurfaces: in-band on the streaming connection, and as an HTTP 502 error\nenvelope for non-streaming requests.\n\nStream accounting has two accepted limits. A source that never reports a\nnumeric tool-call index is counted per id-bearing fragment; a provider that\nrepeats the same id across continuation fragments can overcount the calls, and\nthe fallback is unchanged until such a provider shape is observed.\n\nProvider reasoning tokens are not cross-checked against output tokens: a\nreasoning count greater than the reported output is accepted, the derived\nanswer count is `max(0, output - reasoning)`, and the record keeps the provider's own totals. A\nfuture observed shape that violates the relation needs a targeted validation\nrather than a universal rejection.\n\nNeither transparency nor exactly-once upstream execution is unconditional.\n\nBefore relay or translation, the upstream request is subject to the configured\n`request_overrides` (see [request overrides](configuration.md#request-overrides)):\nmatching rules set, replace or remove upstream headers as the last header\nstage, and their body fields set `max_tokens` / `max_completion_tokens` on\nChat Completions or Anthropic client bodies before translation, whatever the\ntarget (a Responses client body is not rewritten), fail closed. A configured\n`sub_conversations` strip also removes tracked body fields before relay\n([tracked body params](#tracked-body-params)). Only the upstream request\nchanges; the client-visible contract is unchanged.\n\n### Scheduling and timing\n\nThe provider-plus-key group controls simultaneous upstream sends and its waiting\nqueue. A separate limit policy can apply to the whole provider or narrow to\nmodels, clients, key hashes and conversations, with an optional recurring\nserver-local schedule; a provider-only rule combines all keys and clients.\nQueue capacity and wait limits can reject work locally;\nthe configured `queue_retry_after` duration (for example `2s`, never a bare\ninteger) supplies the caller's retry hint. Operator-hold time is excluded from\nthe ordinary queue-wait limit. A hold's own queue cap still applies.\n\nFor the HTTP relay, `upstream_timeout` limits waiting for response headers,\nnot the streaming body.\n`X-Proxy-Timeout-Ms` instead gives each upstream send a fresh deadline covering\nheaders and body. Neither is a total end-to-end deadline across queueing, holds,\nretries and backoff; client cancellation is the way to stop the whole request.\n\nThe request-body progress bound applies only while the body is being read.\nReaching EOF or closing the body clears the connection read deadline, so a\nlong-lived response stream is never cut by the upload guard.\n\nThe [Cursor bridge](adapters.md#cursor-connect-bridge) instead applies the tighter\nconfigured/per-request timeout only until send headers arrive, without a body\ndeadline on its parked run. Model discovery ignores the per-request timeout\nand uses `models_discovery_timeout` for the whole discovery operation.\n\nBuffered whole-document reads (translated non-streaming responses and discovery\npages) use `whole_document_read_timeout` when the send has no deadline of its\nown and `whole_document_read_max` as the ceiling even against a longer\n`X-Proxy-Timeout-Ms`. A shorter caller deadline still wins. Configuration\nvalidation keeps `models_discovery_timeout` below the ceiling, so its\nconfigured budget is untouched.\n\nProvider Retry-After/reset hints are a floor on the wait, not a replacement\nfor adaptive exponential backoff. A long hint is not clamped by the ordinary\nadaptive cap and can therefore outlast it. A short hint does not reset the\ndoubling, so a 1s \"retry shortly\" cannot re-hammer a struggling upstream.\n\nWhen a 429 carries no header hint but its bounded error body contains an\nRFC3339 reset instant (for example \"... resets 2026-11-03T23:11:00Z\"), that\ninstant is used as the same bounded hint: a provider-specific code such as\n`tier_limit_exceeded` then waits for its window instead of exhausting the\nretry budget in seconds and surfacing to the client.\n\nA finalized request retains its absorbed attempts and final outcome in one\nrecord. Every retried or final attempt stores the same upstream-response\ninformation: the provider request id, server, processing time, echoed model,\nrate-limit state and the redacted response headers. A provider-side request id\ntherefore matches to the exact upstream attempt that produced it, including\nfailures the client never saw.\n\nTransport failures have no HTTP response, so\ntheir attempt entries leave those fields empty.\n\nAn in-band 429 is the one\nattempt entry that carries the in-band flag: when a keepalive already committed\nthe client's success 200, the upstream status cannot replace it, so the record\ndescribes the committed 200 and keeps\n`{status_code:429,at,in_band:true}` to preserve the distinct rate-limit\nsignal. The record likewise keeps the committed 200 for every other in-band\nfailure, including a failed retry re-send whose wire status never reached the\nclient.\n\nOnly a 429 mints one; any other in-band provider error stamps the\nrecord's own type and status instead, and a failed body read behind the commit\nkeeps the provider-decided type rather than replacing it.\n\nThe entry carries no retry or error detail, is not counted as a retry, and\nis excluded from retry disclosures and error enumerations.\n\nRecovered upstream failures can\ncount as errors even when the final status succeeds. A final, retried or\nin-band 429 is a separate affected-request signal.\n\nA client that disconnects before a final outcome is recorded as status 499\nwith `client_disconnected`; a plain 499 is a flow event, but one carrying a\nstructured error counts as the upstream error it observed. That is the\nprovider's in-band stream failure the client aborted around, or a truncated\nstream whose completion marker never arrived - an abort must be classified by\nits outcome, never by which relay write happened to fail.\n\nSee [metric interpretation](routes.md#dashboard-data-and-request-inspection)\nfor duration, first-token latency and throughput.\n\n### Error storm protection\n\nEnable `storm_enabled` in Settings to add shared provider/model protection to\nexisting admission and retry pacing. Requests wait in the proxy with the caller\nconnected; this is not a client SDK queue. The proxy keeps the existing bounded\nrequest bytes and credentials only for the request lifetime. Queues are in\nmemory, cannot survive a restart, and stop waiting when the caller cancels.\n\nEach exact recorded model name within its resolved provider has a rolling\n`storm_window`. A model qualifies when its sampled attempts meet\n`storm_min_samples` and its selected-failure percentage reaches\n`storm_error_percent`. Provider-wide protection requires **every active model**\nto qualify, as well as the aggregate sample/rate threshold. Only models receiving\nrequests within that same window are active; an idle model or an unused model in\na provider catalog cannot affect that decision. This scope combines credentials\nand clients. Dashboard model-display rewrites do not merge storm scopes.\n\nThe detector samples successful upstream attempts and selected failures, counting\nabsorbed retries separately. Incident details also count distinct logical\nrequests with a selected failure in the window; retries move the same request's\nlast-failure membership instead of adding another request.\n\nUnselected statuses, non-retryable HTTP account/auth rejections, recognized\ndurable quota envelopes, caller cancellations and fired per-send deadlines\nare excluded - quota outcomes never become storm evidence, even while a\nquota gate is open. A selected 429 is a storm failure sample but remains a\nseparate rate-limit signal in dashboard request health. Configurable\nresponse/stream failure detection observes a 2xx attempt once when its relay\ncompletes, or before an existing quality re-ask. It never adds a replay\nafter meaningful output or native tool execution.\n\nAn open scope holds new sends until its cooldown expires, then admits one shared\nprobe. Failed probes multiply the cooldown, with configurable jitter and a cap;\nvalid larger upstream retry hints remain effective. Recovery needs the configured\nnumber of consecutive successful probes.\n\nThe existing provider-plus-key queues,\noperator holds and provider Limits still apply. The HTTP relay checks storm\nreadiness before acquiring key concurrency, then claims a probe only at the\nactual send boundary. Readiness never reserves a probe while waiting for a key\nslot.\n\nNative parked runs remain resumable; fresh Cursor HTTP\nhandshakes use the shared native send owner and can retry before a run starts.\n\nThe quota pause (`quota_pause_mode: retry`) is a separate provider-wide gate in\nthe same scheduler: the first durable quota/billing 429 from an OpenAI-wire\nprovider opens it immediately (no sample thresholds), the triggering request\nabsorbs the 429 and re-sends per the same recovery cooldowns, and every new\nrequest to the provider parks at admission.\n\nThe gate closes after `quota_pause_recovery_successes` consecutive successful probes (the default 1\ncloses on the first 2xx) and the queue drains; a provider `Retry-After` on the quota\n429 is a floor on the next probe, bounded by the shared hint ceiling. Parked\nsends obey `storm_max_queue` and `storm_max_wait`; beyond them the proxy answers HTTP 429 locally.\n\nThe gate appears in the storm banner as a quota incident with an operator\n**Resume now** action; a manual-mode hold appears on the pause surface\ninstead. The gate is in-memory: a restart drops it and the provider's next\ndurable quota 429 re-arms it. Manual-mode holds persist like every operator\npause.\n\nThe ordinary HTTP retry budget remains `max_retries`. Selected failures during\nan active storm may use up to `storm_max_retries` additional attempts across the\nlogical request, including quality re-asks.\n\nCursor runs the same verdict: its\nfresh handshakes take the ordinary `max_retries` budget and, with protection\narmed, the additional storm budget, and a retried success leaves the group at\none probe exactly like the generic ladder. Exhaustion returns the final upstream\nfailure. Retrying inference can repeat upstream execution or billing even when\nno output arrived; this feature does not provide exactly-once processing. See\nthe [HTTP retry constraints](https://www.rfc-editor.org/rfc/rfc9110.html#section-9.2.2).\n\n`storm_max_queue` bounds callers waiting at storm gates across the process;\nordinary scheduler queues have their own limits. `storm_max_wait` bounds each\nstorm wait, not total request wall time. Scope capacity and oversized scope\nidentifiers also fail closed. Local storm admission rejection returns HTTP 429\nwith `queue_retry_after`; a streaming connection already committed by keepalive\ncomments receives an in-band error instead. Successful retries remain one\nfinalized request record with its absorbed attempts and accumulated queue wait.\n\n### Model discovery\n\n`GET /v1/models` and `GET /models` are constructed discovery services, not\nordinary inference records. The proxy normalizes recognized model lists,\ntranslates native formats, completes supported pagination, and optionally\nenriches missing fields. Unrecognized successful list bodies remain verbatim;\nprimary discovery budget/errors fail explicitly, while optional enrichment can\nfall back to the complete base list. Discovery can apply limit headers without\nconsuming an inference slot. Its time/byte/page/entry limits are\nconfiguration-owned.\n\nPrimary and enrichment entries share one `models_discovery_max_entries` budget\n(default 10,000); enrichment degrades to the base list when the remaining\nbudget cannot hold its metadata source. The rendered list is bounded by\n`models_discovery_max_bytes` plus a fixed per-entry normalization allowance\n(512 bytes for each configured entry) and is encoded without HTML escaping,\nso literal `<`, `>`, and `&` keep their wire size. A rendered list past that\nderived bound fails closed before any response bytes are written.\n\nDiscovery addresses the format's own models endpoint regardless of translation:\n`/v1/models` on the shared base join, Anthropic's pagination query, or Cursor's\nnative unary model service. The translator's inference path is not reused\nbecause both inference endpoints are POST-only upstream. An explicit\n`X-Proxy-Path` or `X-Proxy-Query` still replaces the endpoint and query, while\nthe incoming request query is not forwarded.\n\nA primary upstream non-200 response, including a redirect, becomes a 502\ndiscovery error. Discovery authenticates with the resolved target auth\nheader and prefix, the same construction as a relayed request, and has no\nprotocol-specific fallback: an Anthropic endpoint that requires `x-api-key` must be\ncalled with `X-Proxy-Auth-Header: x-api-key` and an empty `X-Proxy-Auth-Prefix`.\n\nThe ordinary HTTP relay returns upstream redirects rather than following them.\nForwarding also changes transport headers and may decompress an upstream gzip response;\ndo not compare transport framing as a byte-identical contract.\n\n## Main and sub-conversations\n\n### Automatic grouping\n\nAn explicit `X-Proxy-Session` takes precedence, then a configured tracked body\nparam (see [tracked body params](#tracked-body-params)). Without either, the\ntracker partitions requests by client label and credential hash, then compares\ntotal user/assistant/tool turn counts against its open conversations. A\nnonexpired conversation with the greatest previous count no larger than the new\ncount is the nearest match.\nA reset or idle gap can start another conversation, and the configured open-session\ncap evicts the oldest tracked conversation in that partition.\n\nThis is a heuristic for clients that send conversation history, not a content\ncomparison or a universal agent identity. Parallel tasks with similar turn counts\ncan be ambiguous. Tracker state is process-local, so use explicit session IDs\nwhen predictable continuity matters and keep the client/key namespace stable.\nAutomatic grouping never establishes a parent/child relationship.\n\n### Tracked body params\n\nThe request body is client data, and one field can double as the conversation\nidentity. When `sub_conversations` names the request's classified client, the\ntracked field the client already sends (exemplar: opencode's `promptCacheKey`)\nsupplies that request's identity in the `k:` namespace: behind an explicit\n`X-Proxy-Session`, ahead of automatic grouping. Params match only top-level\nbody fields, checked in order.\n\nThe first present field decides: a present\nvalue that is not a JSON string counts as absent and the next field is\nchecked, while a present string that cannot be decoded or fails the identity\nrules drops the identity for the request - no later field is consulted. A\ntop-level field that occurs more than once is ambiguous and drops the\nidentity the same way, leaving the request on automatic grouping.\n\nThe body is relayed unchanged unless the entry sets `strip`, which removes the\nentry's configured fields from the top level of the client request body\nbefore relay or translation. It applies to any JSON body, including a\nResponses client body.\n\nA request translated to the Anthropic wire gains a top-level `prompt_cache_key` carrying\nthe tracked value. That field is a proxy tracking extension, not an\nAnthropic cache control, and only upstreams that tolerate unknown top-level\nfields accept it.\n\nAn absent or dropped identity is never a client\nerror. A tracked identity never declares a parent: `X-Proxy-Parent-Session`\nstill requires its explicit session pair, and the session wins identity. The\nidentity rules, name grammar, caps and the settings surface live in\n[configuration](configuration.md#sub-conversation-tracking).\n\n### Declaring a parent\n\nA parent sends `X-Proxy-Session: main-task`. Its child sends its own\n`X-Proxy-Session: worker-1` plus `X-Proxy-Parent-Session: main-task`, using the\nsame client label and API key. Send IDs without the stored `s:` prefix.\n\nWhen declaring a parent, both headers must occur once, contain nonempty valid\nUTF-8 without controls, differ from each other, and fit 512 bytes after trimming.\nSelf-parent/invalid declarations return 400. The parent header is proxy-only;\nit neither edits the body nor instructs an upstream to create a child agent.\n\nThe server resolves observed relationships within\n`(client, key_hash, conversation_id)`, including history outside the selected\nview. The explorer reports main/sub/unresolved counts and role/parent metadata.\nA missing parent is **not observed**, not an invented main. Conflicts, cycles or\nambiguous reused IDs remain unresolved. “Main” means no parent declared in\nobserved history, not independently verified orchestration.\n\nParent links preserve the full representable client/key namespace. Conversation\nfilters remain exact leaves, never descendant filters. A changed credential can\nchange the namespace. Historical parentage cannot be inferred from absent data,\nmessage similarity, or ordinary conversation-continuity fields.\n"
    },
    {
      "path": "docs/adapters.md",
      "slug": "docs/adapters",
      "output": "docs/adapters.html",
      "markdown": "docs/adapters.md",
      "url": "https://millivolt.llm4people.dev/docs/adapters.html",
      "markdown_url": "https://millivolt.llm4people.dev/docs/adapters.md",
      "title": "Upstream compatibility, adapters and token refresh",
      "description": "The client-facing protocol is separate from the upstream protocol. Select an adapter with X-Proxy-Format ; do not infer one from a provider label. See...",
      "group": "Integrate",
      "order": 5,
      "bytes": 56519,
      "sha256": "e5a7e308a1f584d98e4e5207d38fb965e559af322e0608eaf0b8b963263dd4a0",
      "sections": [
        {
          "heading": "Client and upstream compatibility",
          "id": "client-and-upstream-compatibility",
          "text": "millivolt accepts three client wire families (Chat Completions, Responses and Messages) plus the Cursor Connect bridge, and translates between them and the supported upstream families. The client protocol is selected by the request path, or explicitly by X-Proxy-In-Format ; the upstream protocol is selected by X-Proxy-Format . Translation runs only when both are known and differ. An absent X-Proxy-Format never enters the IR, and an explicit format equal to the client protocol also stays passthrough. Passthrough is not an unconditional byte-identity promise: configured request_overrides , a sub_conversations strip, or ensured tools can still rewrite the upstream body before it is sent (see request overrides ). Without any of those configured, the body bytes are relayed unchanged. Client path Client protocol X-Proxy-Format Upstream protocol POST /v1/chat/completions OpenAI Chat Completions openai or absent OpenAI Chat Completions, passthrough when both are Chat POST /v1/chat/completions OpenAI Chat Completions openai-responses OpenAI Responses POST /v1/chat/completions OpenAI Chat Completions anthropic Anthropic Messages POST /v1/chat/completions OpenAI Chat Completions cursor Cursor",
          "context": ""
        },
        {
          "heading": "Cross-protocol translation",
          "id": "cross-protocol-translation",
          "text": "Cross-protocol translation goes through one canonical request, response and stream model in format/ir . Each wire family has one decoder and one encoder; the IR is the single source of truth for roles, content blocks, tool calls and results, reasoning artifacts, stop reasons and usage. Same-protocol requests never enter the IR: they relay unchanged unless a configured request override, sub-conversation strip or ensured-tools rule rewrites the upstream body first. Carried wherever the target protocol represents them: text, images (URL, base64 or file id), documents, audio where the target accepts it, system/developer/user/assistant turns, function tools, tool choice, parallel tool use, tool calls and results, structured outputs, reasoning effort and summary, stop sequences, sampling parameters, metadata, usage and cache-token accounting. A malformed Chat stop value is rejected before the upstream send on a translated request. Absent, null, a string and an array of strings are the accepted shapes; any other type returns 400 instead of silently dropping the stop filter. An array element that is null or not a string is also rejected: Go would otherwise decode it as an empty stop sequen",
          "context": ""
        },
        {
          "heading": "Bundled compatibility profiles",
          "id": "bundled-compatibility-profiles",
          "text": "The generated configuration example enables the Grok, OpenCode Zen and Cursor profiles and the opencode sub-conversation tracking exemplar (the promptCacheKey tracked param, strip on). config.Example() in internal/config owns the exact profile mappings, header values and that tracking entry; built-in config.Default() remains provider-neutral. The image installs the example into fresh config volumes. Existing saved configurations are not silently replaced. These are operator-selected compatibility snapshots, not verified current public API fingerprints or permission to use an account service. They contain no keys and do not choose the upstream URL or protocol adapter for a request. Review them for your integration and remove or adjust any unwanted profile in Settings. The Grok profile supplies client-identity/request-ID headers and model-modality enrichment through the model discovery endpoint. Model version is not context length, and the profile does not invent that mapping. Standard usage detection and USD-tick scaling already handle recognized cost fields; custom cost_keys must name USD values rather than bypassing that scaling. Streaming cost requires the upstream to report usag",
          "context": ""
        },
        {
          "heading": "Anthropic-compatible Messages",
          "id": "anthropic-compatible-messages",
          "text": "anthropic works in both directions: as an upstream selector for a Chat, Responses or Anthropic client, and as the inbound protocol for POST /v1/messages . Translation covers message history, system text, images, tools and results, thinking blocks, cache control, selected parameters, usage and streaming events. Fields with no target representation follow the translation loss policy . A configured sub-conversation tracking value is injected as a top-level prompt_cache_key . That field is a proxy tracking extension, not an Anthropic cache control: Anthropic caching uses cache_control , and the injection is only safe for upstreams that tolerate unknown top-level fields. The client's own spelling of the tracked field is otherwise dropped by the allowlist. The caller must supply the native endpoint's correct auth/version/path headers; the protocol example demonstrates the mechanism. Stored parameter and conversation-composition metadata describe the translated upstream body, not an exact copy of the original request. For a native or translated Anthropic body, the recorded stop count, tool choice, parallel-tool flag, reasoning effort, response format and service tier come from the Anthrop",
          "context": ""
        },
        {
          "heading": "Cursor Connect bridge",
          "id": "cursor-connect-bridge",
          "text": "cursor is a text/tool bridge from OpenAI chat to the native agent.v1 bidirectional Connect/protobuf protocol. It currently requires an OpenAI Chat client: a Responses or Anthropic client targeting cursor is rejected with a clear 400 instead of receiving the wrong response shape. It is not a general multimodal bridge or a promise of a stable public provider API. Check the provider's current access terms and supported integration options before using account credentials; the project does not establish permission on your behalf. The run owns a bidirectional HTTP/2 transport, framed messages, heartbeat, context/KV replies and one ordered event queue. Malformed known nested messages, invalid usage or error terminal frames fail explicitly. A validated turn-ended marker plus EOF remains a supported completion convention; bare EOF without completion is not a clean success. The event queue carries an internal retained byte budget and the pending tool-call map internal count and payload byte caps; the KV blob store carries per-run byte and entry caps. The parked-run store enforces aggregate budgets across all parked runs: retained pending plus queued event bytes, retained blob bytes, and blo",
          "context": ""
        },
        {
          "heading": "Cursor service and protobuf versions",
          "id": "cursor-service-and-protobuf-versions",
          "text": "The service name, transport version and codec are different layers, not two protobuf implementations running together: Layer What millivolt uses Cursor service agent.v1.AgentService : bidirectional Run and unary GetUsableModels . The v1 is part of the service namespace. Connect transport Connect-Protocol-Version: 1 . Run uses framed application/connect+proto ; model discovery uses unframed application/proto . Protobuf codec The limited handwritten encoder/decoder in proto.go , using the adapter's mapped fields. There is no Go protobuf APIv1 or APIv2 dependency. The Connect specification defines its version header separately from protobuf. Likewise, Go's APIv1/APIv2 distinction and Buf's JavaScript runtime v2 are library versions, not instructions to change agent.v1 to agent.v2 or protobuf syntax to proto2. The small codec avoids a generated-runtime dependency, but requires maintaining explicit field mappings and does not promise general protobuf conformance. A read-only check on 2026-09-06 of the installed Cursor CLI bundle 2026.08.11-e8db854 found agent.v1 descriptors with proto3 semantics and @bufbuild/protobuf 1.10.1 , not v2. This is evidence about that inspected client artifac",
          "context": "Cursor Connect bridge"
        },
        {
          "heading": "First-login helpers",
          "id": "first-login-helpers",
          "text": "grok-login.sh and cursor-login.sh obtain initial account credentials through interactive browser approval. Run them on a trusted Linux host or workstation, not inside the minimal proxy image. Neither a running millivolt instance nor the provider's CLI/desktop application is required by these scripts. Account eligibility, permitted integrations and model access remain the provider's decision; successful authentication does not establish subscription entitlement or a free inference allowance. The scripts do not write files or update client configuration. They print secret credential headers to standard output, and approval links/progress to standard error. Keep the terminal private: do not use shell tracing ( bash -x ), CI logs, screenshots or shared output redirection. Review a downloaded script before running it. These helpers have no command-line option parser; configure them with the environment variables below, not --help or invented flags.",
          "context": ""
        },
        {
          "heading": "Prerequisites and obtaining the scripts",
          "id": "prerequisites-and-obtaining-the-scripts",
          "text": "Both need Bash, curl , jq and standard Linux command-line utilities. Cursor also needs openssl and a curl build with HTTP/2 support; check that curl --version lists HTTP2 in Features, as described in the curl HTTP/2 guide . xdg-open is optional: without it, open the printed approval URL yourself, including from another browser-capable device. Source checkouts already contain both helpers under scripts/ . Image-only deployments can download just the desired helper on the host, without cloning or rebuilding millivolt: curl -fsSL https://raw.githubusercontent.com/LLM-4-People/millivolt/main/scripts/grok-login.sh -o grok-login.sh curl -fsSL https://raw.githubusercontent.com/LLM-4-People/millivolt/main/scripts/cursor-login.sh -o cursor-login.sh Use a new directory so downloads do not overwrite existing files. For a pinned installation, replace main in those URLs with the reviewed commit or release tag. Standalone downloads use bash ./grok-login.sh or bash ./cursor-login.sh instead of the checkout paths below. Do not pipe a download directly into Bash.",
          "context": "First-login helpers"
        },
        {
          "heading": "Grok login",
          "id": "grok-login",
          "text": "From a source checkout: bash scripts/grok-login.sh Open the printed verification URL, check the account and approve the displayed device code. The helper polls for approval and prints Authorization: Bearer with the access token, X-Proxy-Refresh-Token when supplied by the provider, and X-Proxy-Base-URL: https://api.x.ai/v1 . This is an account-login token flow, not creation of a pay-as-you-go xai- API key. It does not select a model or add a native-format header; the ordinary OpenAI-compatible relay is used. For SSH or a headless terminal, suppress automatic browser opening: NO_OPEN=1 bash scripts/grok-login.sh",
          "context": "First-login helpers"
        },
        {
          "heading": "Cursor login",
          "id": "cursor-login",
          "text": "From a source checkout: bash scripts/cursor-login.sh Open the printed login link and approve the account sign-in. The helper creates a PKCE challenge, requests HTTP/2 when polling the account endpoint, and prints the access token, optional refresh token, upstream base URL and X-Proxy-Format: cursor . Use the printed format header to select the Cursor bridge ; a provider profile by itself does not enable translation. The same headless switch is supported: NO_OPEN=1 bash scripts/cursor-login.sh",
          "context": "First-login helpers"
        },
        {
          "heading": "Configure the client after approval",
          "id": "configure-the-client-after-approval",
          "text": "Keep the client's API base pointed at millivolt , such as http://127.0.0.1:8080/v1 , using your actual host/port or protected ingress URL. The helper's X-Proxy-Base-URL instead identifies the upstream; do not replace the client's millivolt URL with it. Printed value Client configuration Access token after Authorization: Bearer Put only the token in an SDK's API-key field, or use the complete printed Authorization header if configuring headers directly. Do not add Bearer twice. X-Proxy-Base-URL Add as a custom request header. X-Proxy-Refresh-Token , when present Add as a custom request header if using automatic refresh ; the client must retain rotated credentials returned by the proxy. X-Proxy-Format: cursor Add for the Cursor helper only. Select a model your account is authorized to use. Keep tokens in private client configuration or a secret store, not proxy.example.yaml or a Git-tracked file. Millivolt does not register these credentials globally. If your ingress consumes Authorization, follow the separate upstream-key setup .",
          "context": "First-login helpers"
        },
        {
          "heading": "Helper environment overrides",
          "id": "helper-environment-overrides",
          "text": "These affect the login process only, not server Settings or the saved client. Use only origins and OAuth registrations you trust: they receive login material. Defaults remain owned by each script. Variable Helper Meaning and default NO_OPEN Both Any nonempty value suppresses xdg-open ; unset or empty permits it. The URL is still printed. GROK_LOGIN_TIMEOUT Grok Approval-poll budget in seconds; 600 . Use a positive integer. XAI_AUTH_BASE Grok Login origin; https://auth.x.ai . Does not change the printed inference base. XAI_OAUTH_CLIENT_ID Grok OAuth registration; defaults to the client ID shared with the proxy's xAI refresh implementation. CURSOR_LOGIN_TIMEOUT Cursor Approval-poll budget in seconds; 300 . Use a positive integer. CURSOR_API_BASE Cursor Poll origin and printed inference base; https://api2.cursor.sh . CURSOR_LOGIN_BASE Cursor Browser login origin; https://www.cursor.com . Timeouts are polling budgets, not strict end-to-end deadlines: a current HTTP operation or sleep can extend elapsed time. Changing Grok's auth origin/client ID does not change millivolt's xAI refresh endpoint/registration, so a custom login can be incompatible with renewal. Cursor refresh targets the ",
          "context": "First-login helpers"
        },
        {
          "heading": "Login troubleshooting",
          "id": "login-troubleshooting",
          "text": "Symptom What to check Required tool not found Install the named dependency on the host running the helper, not in the proxy image. No browser opens Open the printed URL manually. NO_OPEN=1 deliberately disables automatic opening. Cursor reports unsupported HTTP/2 or keeps waiting Check curl --version for HTTP2 support and inspect its diagnostics. The helper keeps polling non-200 responses until its budget expires. Approval times out, expires or is denied Verify the account/browser approval, then rerun for a fresh login challenge. Never reuse an expired code. No refresh token is printed The helper warns and omits that header. Millivolt cannot renew without it; obtain another login when the access token expires. Login succeeds but inference returns 401/403 Check client headers, upstream base, account permissions and model availability. Login alone does not prove inference access. Grok or Cursor repeatedly returns token_expired The client must adopt the returned access token and any rotated refresh token, then retry. Repeating the old credentials does not complete handback. Refresh is rejected Recheck provider access and perform a new interactive login. Do not publish token responses ",
          "context": "First-login helpers"
        },
        {
          "heading": "Token refresh",
          "id": "token-refresh",
          "text": "With auto_token_refresh enabled, a request may supply its own X-Proxy-Refresh-Token . The proxy can exchange an expiring JWT for supported mechanisms; it stores neither a credential database nor reusable refresh state. The JWT expiry check is not signature authentication. Grok and Cursor use the same inference handback behavior. A successful exchange returns HTTP 401 with error type authentication_error and code token_expired . The error object includes access_token and, when the exchange returned a different refresh token, refresh_token . The same values are in the error message. No inference is sent or recorded for that handback. The client stores the returned access token, adopts any returned refresh token, and retries the original request. Starting with 0.2.0 , Cursor no longer refreshes in place on inference requests. Clients that previously relied on that behavior must now handle the same 401 handback as Grok. Starting with 0.3.1 , credentials are in that error body, not X-Proxy-Access-Token / X-Proxy-Refresh-Token response headers. Update client handling before upgrading; a generic client that only reads those headers cannot complete automatic renewal. Retry only after adopt",
          "context": ""
        }
      ],
      "markdown_text": "# Upstream compatibility, adapters and token refresh\n\nThe client-facing protocol is separate from the upstream protocol. Select an\nadapter with `X-Proxy-Format`; do not infer one from a provider label.\nSee [protocol](protocol.md) for routing/auth headers and\n[operations](operations.md#known-limits) for current limitations.\n\n## Client and upstream compatibility\n\nmillivolt accepts three client wire families (Chat Completions, Responses and\nMessages) plus the Cursor Connect bridge, and translates between them and the\nsupported upstream families. The client protocol is selected by\nthe request path, or explicitly by `X-Proxy-In-Format`; the upstream protocol\nis selected by `X-Proxy-Format`. Translation runs only when both are known and\ndiffer.\n\nAn absent `X-Proxy-Format` never enters the IR, and an explicit format\nequal to the client protocol also stays passthrough. Passthrough is not an\nunconditional byte-identity promise: configured `request_overrides`, a\n`sub_conversations` strip, or ensured tools can still rewrite the upstream\nbody before it is sent (see\n[request overrides](configuration.md#request-overrides)). Without any of those\nconfigured, the body bytes are relayed unchanged.\n\n| Client path | Client protocol | `X-Proxy-Format` | Upstream protocol |\n| --- | --- | --- | --- |\n| `POST /v1/chat/completions` | OpenAI Chat Completions | `openai` or absent | OpenAI Chat Completions, passthrough when both are Chat |\n| `POST /v1/chat/completions` | OpenAI Chat Completions | `openai-responses` | OpenAI Responses |\n| `POST /v1/chat/completions` | OpenAI Chat Completions | `anthropic` | Anthropic Messages |\n| `POST /v1/chat/completions` | OpenAI Chat Completions | `cursor` | Cursor agent.v1 |\n| `POST /v1/responses` | OpenAI Responses | `openai` | OpenAI Chat Completions |\n| `POST /v1/responses` | OpenAI Responses | `openai-responses` or absent | OpenAI Responses, passthrough when both are Responses |\n| `POST /v1/responses` | OpenAI Responses | `anthropic` | Anthropic Messages |\n| `POST /v1/messages` | Anthropic Messages | `openai` | OpenAI Chat Completions |\n| `POST /v1/messages` | Anthropic Messages | `openai-responses` | OpenAI Responses |\n| `POST /v1/messages` | Anthropic Messages | `anthropic` or absent | Anthropic Messages, passthrough when both are Anthropic |\n\nxAI/Grok uses the ordinary OpenAI-compatible relay, not a separate native\nadapter. Other providers and local model servers can use that same path when\nthey expose a compatible API; there is no fixed provider registry. Native\ntranslation covers the fields listed under\n[cross-protocol translation](#cross-protocol-translation), not every endpoint\nor arbitrary provider protocol.\n\nClients must support custom routing headers or middleware that adds them.\nFor native formats, supply the adapter selection and the upstream's required\nauthentication, version and path headers; the\n[Anthropic example](protocol.md#url-and-auth-examples) and\n[Cursor login setup](#cursor-login) show these choices. Provider profiles enrich\nheaders, metadata and ensured tool signatures but do not select an adapter or\ngrant provider access.\n\n## Cross-protocol translation\n\nCross-protocol translation goes through one canonical request, response and\nstream model in [format/ir](../internal/format/ir/ir.go). Each wire family has\none decoder and one encoder; the IR is the single source of truth for roles,\ncontent blocks, tool calls and results, reasoning artifacts, stop reasons and\nusage. Same-protocol requests never enter the IR: they relay unchanged unless\na configured request override, sub-conversation strip or ensured-tools rule\nrewrites the upstream body first.\n\nCarried wherever the target protocol represents them: text, images (URL,\nbase64 or file id), documents, audio where the target accepts it,\nsystem/developer/user/assistant turns, function tools, tool choice, parallel\ntool use, tool calls and results, structured outputs, reasoning effort and\nsummary, stop sequences, sampling parameters, metadata, usage and cache-token\naccounting.\n\nA malformed Chat `stop` value is rejected before the upstream send on a\ntranslated request. Absent, null, a string and an array of strings are the\naccepted shapes; any other type returns 400 instead of silently dropping the\nstop filter.\n\nAn array element that is null or not a string is also rejected:\nGo would otherwise decode it as an empty stop sequence. The same element rule\napplies to Anthropic `stop_sequences`. Native Chat passthrough is not decoded:\nthe body is relayed unchanged, so `stop: 5` reaches the upstream and its\nresponse is returned. An empty string and an empty array still mean no stops.\n\nProtocol-only artifacts are preserved for the same family and reported when a\ntarget cannot consume them:\n\n- Anthropic thinking and redacted-thinking blocks keep their opaque signatures.\n  A Responses reasoning item has no Anthropic signature: a translated request\n  or non-streaming response emits its visible text with an approximation\n  warning instead of a `thinking` block, while a translated stream opens a\n  `thinking` block with an empty `signature`. The proxy keeps the reasoning\n  text and does not invent a signature; resending an empty-signature block is a\n  client choice and the target may reject it.\n- OpenAI Responses reasoning items keep `encrypted_content` and item ids.\n  A cross-family encrypted reasoning artifact is never replayed into another\n  provider's field. A non-streaming surface drops it with a warning; a stream\n  has no warning sink and drops it silently.\n- A Responses reasoning item exposes two independent text channels: the\n  summary parts and the content reasoning text. A translated stream emits both\n  as they arrive, so text the source places in both channels appears in two\n  target reasoning blocks. The proxy does not deduplicate across channels: a\n  native client accumulating the source observes the same two channels, and\n  merging them would corrupt genuinely distinct summary and content text.\n- Responses namespace tools are flattened, not dropped. A client may group\n  function tools under `{\"type\":\"namespace\",\"name\":\"mcp__context7\",\"tools\":[...]}`;\n  the target receives each member as an ordinary function whose name is\n  `<namespace>__<tool>`, and a returned call names the group again in the\n  client's `function_call` item. The flattened spelling is truncated to the\n  target name class and suffixed with a hash when it is longer than\n  Chat's 64-character limit, and two members that flatten to the same string\n  receive a numeric suffix, so every declared tool stays addressable.\n- Provider-executed tool definitions (web_search, file_search, mcp,\n  image_generation, tool_search and similar) are optional to the client's\n  remaining tools and are dropped with a `tool.<type>` warning when the target\n  cannot execute them; `translation_loss: reject` fails the request instead.\n- A freeform `custom` tool is dropped the same way. Its input is a grammar,\n  not a JSON schema, and the client expects a `custom_tool_call` item back, so\n  declaring it as a function would hand the model a tool whose call the client\n  cannot dispatch.\n- Provider-executed blocks such as server tool use and web search results have\n  no cross-protocol equivalent and are dropped with a warning.\n- A Responses `max_tool_calls` request field has no cross-protocol equivalent.\n  A native Responses relay forwards it byte for byte, so the provider still\n  caps its own tool calls. A translated request drops it with a\n  `max_tool_calls` warning and `translation_loss: reject` turns that loss into\n  a 400 before any upstream send. The translated turn therefore has no\n  provider tool-call cap unless the client also sets one the target protocol\n  understands.\n- A Responses item `phase` is a wire hint with no target equivalent. A\n  non-streaming request or response records one `input.phase` or `output.phase`\n  warning. A translated stream keeps one `output.phase` warning only in the\n  decoder's diagnostic state; no client header or stored record carries it.\n  The phase text never reaches the client wire.\n- A `response.output_text.delta` for a part the source never announced is\n  dropped, but the matching done event or the terminal document recovers the\n  full text, so only the incremental gap is lost. A Chat `[DONE]` without a\n  finish reason maps to `response.incomplete` for Responses and to a clean\n  `message_delta` with `end_turn` for Anthropic; both are accepted limits with\n  no reproduced client failure.\n- An Anthropic target derives its terminal from content when the canonical\n  reason maps to `end_turn`: a non-empty refusal becomes `refusal`, a tool call\n  becomes `tool_use`, and a refusal wins when both appear. The non-streaming\n  response reports the approximation in `X-Proxy-Warnings`; a stream has no\n  warning channel.\n- A canonical output block with no Responses content part, such as a file or\n  audio block carried from Anthropic, is dropped from the output with one\n  `output.<type>` warning. Text around the dropped block is preserved.\n- Responses provider-executed tool calls in the shared tool-item vocabulary\n  (`custom_tool_call`, `local_shell_call`, `mcp_call`, `computer_call`,\n  `tool_search_call` and their peers) are tool activity: they count toward a\n  `tool_calls` finish even though no cross-protocol content block exists for\n  them, and a translated record still counts them (retaining streamed names)\n  when the target wire drops the item. Provider-executed generation artifacts\n  (`program`, `program_output`, `image_generation_call`,\n  `code_interpreter_call`) are output presence\n  instead: a completed turn that carries only one of them is not an empty\n  completion, while its finish stays the source's stop rather than\n  `tool_calls`, because the item is generated source or media rather than a\n  model tool invocation. Extending the tool vocabulary waits for a\n  demonstrated client need.\n- `previous_response_id`, `item_reference`, `background`, `conversation` and\n  prompt templates require provider-side state and are rejected when the\n  target cannot honor them. `store: true` is honored by Chat Completions and\n  Responses targets and rejected by Anthropic. A Chat or Anthropic request\n  translated to a Responses target sets `store: false` when the source never\n  chose storage, because the Responses default retains data for at least 30\n  days while the source protocol has no such opt-in and the proxy has no\n  retrieval path. Explicit source values are preserved. A Responses source's\n  implicit storage cannot be honored on Chat or Anthropic, and no response id\n  is returned for later retrieval.\n- Every system or developer message before the first emitted conversation\n  turn, together with the Responses instructions, becomes the top-level\n  Anthropic `system` prompt. A mid-conversation system run stays in `messages`\n  only after an emitted user turn and before an assistant turn or the end; any\n  other position is lifted to the prompt with one approximation warning. A\n  later developer turn has no Anthropic role and is lifted to the prompt with\n  an approximation warning, which reports the positional change.\n- An Anthropic target drops leading assistant turns because the first message\n  must use the user role, reporting one `messages.leading_assistant` warning.\n  A tool result that answered a dropped leading call is dropped with one\n  `messages.orphan_tool_result` warning, so that result never reaches the\n  wire. A source-supplied result that matches no call in the source history is\n  content, not an artifact of the drop: it passes through unchanged as a\n  `tool_result` even though no preceding `tool_use` exists, with no warning.\n  Pairing happens before the drop: a result that names a dropped call stays\n  paired to it and is dropped with that call rather than retargeted to a later\n  same-name call, because the name may answer the dropped call and retargeting\n  could answer the wrong tool. A system or developer turn before\n  the first emitted turn is still lifted to the top-level prompt even when a\n  dropped assistant or an empty user turn preceded it.\n- Consecutive same-role turns are merged. A merged user turn keeps Anthropic's\n  results-first rule: when the later turn would otherwise put text before a\n  `tool_result`, the results move to the front with their relative order\n  preserved and one `approximated:messages.tool_result` warning reports the\n  reorder. An already-ordered or text-only merge keeps source order and warns\n  nothing.\n- A non-clean non-streaming terminal can carry a missing, null, whitespace or\n  partial tool-call argument value the source never finished: a Chat finish\n  other than `stop`, `tool_calls` or `function_call`, or a Responses\n  `incomplete` or `cancelled` terminal, including a `completed` response that\n  still carries an incomplete reason. The proxy drops only the unusable call\n  with one `tool_calls.arguments` or `function_call.arguments` warning and\n  keeps the text, refusal and source finish. A Responses `failed` terminal is not covered\n  by that rule: it returns the provider error envelope and discards the output,\n  so no block or warning is produced. A clean terminal still maps an omitted,\n  null or whitespace value to the empty object, but fails closed on a partial\n  or otherwise invalid value. Structural failures such as a missing name or id\n  remain fatal on every terminal, even when the arguments are also unusable.\n- A streamed Responses `function_call` that omits `call_id` uses its item id as\n  the target tool id. When both identities are absent, the block starts with a\n  stable `call_proxy_<output index>` id instead of an empty id, so Chat does not\n  write an empty tool call and Anthropic does not reject the block. An\n  announcement that carries both identities accepts either spelling on the\n  terminal item. A terminal item that uses the other identity kind, an item id\n  after a call-id announcement or the reverse, matches a unique open announced\n  call with the same name. A terminal entry that repeats an announced call\n  whose block already closed is skipped before open matching when its identity\n  and name agree; an id-less entry also requires its effective argument value\n  to agree. An id-less repeat is skipped before its array position is resolved,\n  so a closed call announced at a foreign position cannot claim a different\n  open call. Formatting differences and object key order do not affect that\n  agreement, but numeric literals are compared as written, so `1` and `1.0`\n  do not agree. A value above the canonicalization size, nesting or\n  member-separator bounds keeps the byte-exact rule, as does a partial or\n  otherwise invalid value, so formatting and key-order differences in such a\n  value do not agree. A named terminal item matches only an open announced call\n  with the same name; several same-name candidates are disambiguated only by\n  the announcement at the terminal position, and no same-name candidate starts\n  a new call instead of taking a differently named open call. An id-less\n  terminal item then matches a unique open announced call with the same name,\n  then the announcement at its own position among same-name candidates, then a\n  lone or first still-open id-less announced call in output order, so a\n  reordered terminal array completes the announced block rather than\n  synthesizing a second call. If no open call matches, an id-less entry whose\n  name and effective argument value agree with a closed id-less call is\n  skipped as that call's repeat. An unannounced id-less call at a colliding\n  announced position cannot be distinguished from a repeat and is dropped\n  rather than assigned to a different call. An identified terminal call also\n  matches only a same-name candidate whose identity kind is compatible: a\n  candidate keyed by the same identity kind must carry that identity, while a\n  cross-kind candidate stays eligible under the mixed-spelling rule. Position\n  alone never moves arguments to a conflicting identity. The non-streaming\n  decoder still rejects a call with both identities absent.\n- A legacy Chat `message.function_call` is treated as answer-shaped for retry\n  safety because the deprecated shape can represent either a tool invocation or\n  a final answer, and it is not counted as a tool call. A Chat source that uses\n  only that shape therefore records no tool-call count even though the call\n  translates.\n- Anthropic `metadata.user_id` is limited to 512 characters. A longer Chat or\n  Responses `user` value is rejected before any upstream send rather than\n  truncated, because truncation can collide two distinct identifiers.\n  Chat/Responses `service_tier: priority` maps to Anthropic `speed: fast` with\n  an approximation warning; `fast` maps without one. A translated stream takes\n  its tier and metadata from the source start event. A value that appears only\n  in the terminal document is not applied retroactively, because the target\n  `message_start` and earlier chunks are already on the wire.\n- An Anthropic document `title` is limited to 500 characters. A longer source\n  filename is dropped with a `document.title` warning while the document bytes\n  still translate; strict mode rejects the loss before any upstream send.\n- A response metadata map has no field on the Anthropic Message object, so a\n  non-streaming translated response drops it with a warning. A translated\n  Anthropic stream cannot report response-side warnings after its status line\n  is committed.\n- An image or document inside an Anthropic assistant request turn is\n  schema-valid because assistant request content shares the message content\n  type. The request encoder keeps it and reports an `assistant.image` or\n  `assistant.document` approximation warning; runtime acceptance of assistant\n  media is not verified. Anthropic's response `Message.content` union has no\n  image or document block, so the response encoder drops it with a\n  `response.assistant.image` or `response.assistant.document` dropped warning.\n  User media is carried without that warning.\n- A Responses `input_file` with inline `file_data` but no media-type\n  declaration has one inferred from a data-URL prefix, a `.pdf` or common\n  plain-text filename extension, or a base64 `%PDF-` signature. Unrecognized\n  bytes are dropped with one warning while a file id or URL on the same part\n  survives; a part with no remaining payload is dropped. Chat file parts keep\n  their existing PDF-only default.\n- A Chat response carries one refusal field, so multiple IR refusal parts are\n  concatenated in block order. An empty part contributes nothing and never\n  clears earlier text.\n- A translated response has no audio representation: the IR has no audio output\n  block, so a Chat `message.audio` or streamed `delta.audio` and a Responses\n  `output_audio` content part never reach a target wire. The non-streaming\n  Responses decoder reports one `content.output_audio` warning; the Chat\n  decoder carries no audio block and reports no warning. Native same-protocol\n  relay keeps the audio unchanged. Mapping a transcript to assistant text\n  would be a fidelity feature, not a lossless translation.\n- A translated non-streaming response assumes a schema-valid source identity.\n  A source that omits `id` or `model` yields an empty string on the target\n  rather than an invented identity. The Responses envelope carries protocol\n  defaults for request-echo fields (`parallel_tool_calls: true`, `tools: []`,\n  `tool_choice: \"auto\"`, null `instructions`/`temperature`/`top_p`,\n  `store: false`); a translated response cannot echo the source request's\n  parameters without threading the request IR into the encoder.\n- A Responses output tool-call `call_id` has no schema length bound, so a\n  provider id longer than 64 characters is relayed unchanged. If the client\n  replays that call as request history, the Responses request boundary enforces\n  its 1..64 character reference rule and rejects the request with 400. The\n  proxy never shortens or drops the output id, because that would break the\n  correlation the client already received.\n- Responses `include` options other than `message.output_text.logprobs` and a\n  non-string Chat metadata value have no target equivalent and are dropped\n  with a warning. The logprobs include maps to the target's request field, but\n  translated responses do not carry provider logprob details.\n- Deprecated Chat `functions` and `function_call` are converted to the\n  canonical tool list and tool choice; a legacy per-assistant `function_call`\n  pairs with its `role: function` reply by function name. Chat `prediction`,\n  audio output, non-text `modalities`, and `web_search_options` have no target\n  equivalent and are dropped with a warning.\n- A request-history tool call without an id gets a generated id and reports the\n  recorded approximation. Tool ids are pre-reserved once per request across\n  every message and item before any message is decoded: a generated id can\n  never collide with an explicit id anywhere in the request, including one that\n  appears later, and a repeated explicit id fails closed with HTTP 400. The\n  deprecated per-assistant Chat `function_call` keeps its function name as the\n  id because that shape carries no id; a repeated same-name legacy call is\n  inherently ambiguous and remains the documented exception. Pairing keeps the\n  kind of reference. A non-empty\n  `tool_call_id` answers the unanswered call with that exact id, so an explicit\n  id is never shadowed by another call's function name; when no id matches, a\n  generated call may still be addressed by the function name its client supplied\n  in place of the missing id. A message `name` (with no `tool_call_id`) addresses\n  a unique generated call. A reply with neither resolves only while exactly one\n  generated call is unresolved and no other call is unresolved. Any reference\n  matching more than one unresolved call fails closed, and an explicit call is\n  never answered by its name alone.\n- A `json_schema` response format must carry a valid JSON object `schema` to\n  translate; a schema-less, null, non-object or invalid `json_schema` schema is\n  rejected with 400 because a cross-protocol target has no meaningful mapping\n  for one. A native same-protocol Chat request is relayed unchanged, so the\n  passthrough path still forwards it.\n- A non-function tool type and malformed tool arguments are rejected before any\n  upstream send.\n\n`translation_loss` selects the policy. `warn` (default) drops the optional\nfields this proxy models but the target cannot represent, and reports each one\nin `X-Proxy-Warnings`. Provider-specific extension fields outside that modeled\nvocabulary are not inspected or reported; the passthrough path relays them\nunchanged.\n\n`reject` fails the request with 400 naming the fields before any\nupstream send,\nand it refuses every recorded loss, including a documented approximation such\nas a clamped temperature, a moved developer message, a generated tool-call id\nor a `json_object` response format, not only a field the target cannot\nrepresent at all.\n\nThe header is proxy-owned: a provider response header of the same name\nis never forwarded. Its whole value is bounded at 1024 bytes; an over-cap list\nis cut at the byte budget, possibly inside the final field, and ends with\n`; truncated`. Response-side warnings\nare never fatal; a non-streaming response reports them in `X-Proxy-Warnings`,\nwhile a streaming response cannot add a header after the status line is\ncommitted and drops them. The field is described under\n[settings](configuration.md#finding-a-setting).\n\nA provider error envelope that arrives inside HTTP 200 is translated too, but\nthe client status becomes 502: a translated client would read 200 as a\nsuccessful completion. A non-200 translated error body is buffered before the\nclient sees it, at most 64 KiB, under `whole_document_read_timeout` (default 2\nminutes), so a provider that holds an error stream open can delay the client\nuntil that bound expires.\n\nA non-200 status that forbids a response body (1xx,\n204 or 304) cannot carry the translated envelope, so it fails closed as 502\n`upstream_error` naming the upstream status instead of committing a status\nwhose error body the client cannot receive. Pre-commit failures (routing,\nrequest validation, translation, or an oversized translated body) answer in the\nclient protocol's own error envelope.\n\nNon-streaming translation reads the complete upstream 200\nbody and the translated document under `translated_response_max_bytes` each\n(default 32 MiB); exceeding either fails closed with 502 `response_too_large`\nbefore any client bytes. Translation buffers the whole document, so the\nsetting also bounds one in-flight translation's memory.\n\nStreaming translation is event-driven and bounded. Each target encoder owns its\nprotocol's ordering invariants: Anthropic opens a block before any delta and\ncloses it before `message_delta`; Responses emits `response.created`, per-item\nlifecycle events and one terminal event; Chat emits the role chunk, deltas, one\n`finish_reason` chunk and one `[DONE]`.\n\nThe official Anthropic event flow closes\nevery content block before `message_delta`. A nonconforming source that sends a\ncontent delta after `message_delta` is not given a runtime special case, because\nthe terminal contract and the target encoder ordering still own the turn.\n\nA truncated upstream is closed with the\nclient protocol's own error event, never a fabricated clean finish.\n\nThe Responses encoder can emit `response.cancelled` for a canonical cancelled finish. The\ncurrent `ResponseStreamEvent` union lists completed, failed and incomplete terminals, while\nthe `Response` status enum includes cancelled; the event is kept as a\nforward-compatible extension and a strict client may treat it as unknown.\n\nSynthetic Responses error and terminal frames emitted on a\ncommitted socket after an accepted non-completion status restart\n`sequence_number` at 0 and 1; relayed events before that keep their original\nsequence. The degenerate terminal-region substitution emits the same error plus\n`response.failed` pair at 0 and 1 even when earlier streamed events carried\nhigher numbers, because the relay does not retain the provider's counter. Both\nreset cases are documented contract gaps, not reproduced client failures; the\nterminal event is final for the turn.\n\n- A Chat stream chunk is decoded from its first choice only. A translated\n  request never emits `n` above 1 because only one choice can be translated,\n  so the limit is unreachable for compliant traffic; a noncompliant upstream\n  that interleaves several choices in one stream would mix them in the\n  translated stream.\n- A Chat stream must carry `chat.completion.chunk` documents. A full\n  completion document, or a choice carrying `message` instead of `delta`, is\n  rejected instead of becoming a successful empty answer; a chunk without\n  `object` stays accepted when it carries a delta.\n- A source in-band error followed by the protocol terminal is deliberate: Chat\n  and Responses clients receive the provider error and then `[DONE]` or the\n  terminal event, matching the source order. The relay does not suppress the\n  terminal after an error.\n- A streamed tool `arguments` value that is exactly `null` is emitted literally\n  and fails the block-close validation, while the non-streaming decoder\n  normalizes it to `{}`. The stream cannot rewrite bytes it already delivered,\n  and no official provider shape emits this value, so the inconsistency is an\n  accepted limit rather than a normalization path.\n- Anthropic `content_block_start` text is not counted as answer content,\n  first-answer time or a preview. The Anthropic wire is exempt from the OpenAI\n  degenerate substitution, so a completed start-text-only stream stays healthy\n  and records no answer content. Official start text is normally empty; this is\n  an accepted accounting limit.\n\nStreaming citations are not translated. A Responses\n`response.output_text.annotation.added` event is not decoded, and a streamed\ntarget does not emit citations or annotations; non-streaming responses do carry\nurl citations. A citation stream event is a separate feature, not a silent\nclaim of streaming parity.\n\nA non-streaming translated Responses message item carries\n`status: \"incomplete\"` when the response-level status is not `completed`, and\n`status: \"completed\"` otherwise. Function-call items always carry\n`status: \"completed\"` because every emitted call has validated arguments. The\nresponse-level `status` still owns the turn lifecycle.\n\nIn a translated stream,\n`response.output_item.added` carries `status: \"in_progress\"` and each\n`response.output_item.done` carries the status at which that item closed:\n`\"completed\"` for a normal close and `\"incomplete\"` for an aborted item. The\nterminal response output preserves those per-item statuses; only an item still\nopen at an incomplete or failed terminal is rendered `incomplete`, and a failed\nterminal omits an open call whose arguments were never validated.\n\nParallel tool calls translated to Anthropic open their indexed content blocks\nconcurrently (for example start 0, start 1, delta 0, delta 1, stop 0, stop 1).\nThe blocks carry the index the streaming contract requires, and SDKs accumulate\nby index; a strict assumption of sequential block lifecycles would need a\nseparate encoder design, not a per-request special case.\n\nA streamed Responses tool call is validated by its terminal class. A\ncompleted terminal fails closed on a partial function-call value. Incomplete\nand cancelled terminals do the same, because both are normal turn boundaries\nand an executable empty object must never close a call the model did not\nfinish. On those two terminals a call with missing, null or whitespace\narguments is also rejected unless the source explicitly sent `{}`.\n\nWhen validation fails, the target abort closes non-tool blocks but\nleaves an open tool block unclosed: Anthropic emits no `content_block_stop` over\nempty input, and Responses emits no done function-call item with empty\narguments. The proxy error frame terminates the stream, so a client that keeps\nreading cannot execute an empty call.\n\nA failed, errored or truncated terminal\ninstead drops only the unparseable call and keeps the provider error or\ntruncation. On Anthropic and Responses, an already-announced open call is left\nunclosed on those three terminals: Anthropic emits no `content_block_stop`,\nResponses emits no done function-call item, and the proxy error frame ends the\nstream.\n\nThe Chat target already streamed the announcement with empty arguments,\nand Chat reports a cancelled finish as `stop`, so that accepted limit is not\ndistinguishable there. A Chat `[DONE]`\nwithout a preceding non-null finish reason is a clean transport terminator but\nan empty finish: a Responses target receives `response.incomplete` with\n`incomplete_details: null`, and the record reports `finish=other`. That\ndegenerate classification is deliberate rather than a fabricated completion.\n\n## Bundled compatibility profiles\n\nThe generated [configuration example](../proxy.example.yaml) enables the Grok,\nOpenCode Zen and Cursor profiles and the opencode sub-conversation tracking\nexemplar (the `promptCacheKey` tracked param, strip on). `config.Example()` in\n[internal/config](../internal/config) owns the exact profile mappings, header\nvalues and that tracking entry; built-in `config.Default()` remains\nprovider-neutral. The image installs the example into fresh config volumes.\nExisting saved configurations are not silently replaced.\n\nThese are operator-selected compatibility snapshots, not verified current public\nAPI fingerprints or permission to use an account service. They contain no keys\nand do not choose the upstream URL or protocol adapter for a request. Review\nthem for your integration and remove or adjust any unwanted profile in Settings.\n\nThe Grok profile supplies client-identity/request-ID headers and model-modality\nenrichment through the model discovery endpoint. Model `version` is not context\nlength, and the profile does not invent that mapping. Standard usage detection\nand USD-tick scaling already handle recognized cost fields; custom `cost_keys`\nmust name USD values rather than bypassing that scaling. Streaming cost requires\nthe upstream to report usage; missing cost is not evidence of a free request.\nSee xAI's [model reference](https://docs.x.ai/developers/rest-api-reference/inference/models)\nand [cost tracking](https://docs.x.ai/developers/cost-tracking).\n\nThe Cursor profile supplies CLI compatibility, allowed-tool and request-ID\nheaders. Its ghost-mode field is a supplied wire preference, not a privacy or\nretention guarantee. Cursor's [public authentication documentation](https://cursor.com/docs/cli/reference/authentication)\ndoes not establish a stable public contract for this native bridge or its\ncompatibility headers. Keep authorization and current service support separate\nfrom a successful local fixture test.\n\nThe OpenCode Zen profile supplies the opencode CLI's client identity on the\nordinary OpenAI-compatible relay: the CLI's composite `User-Agent`,\n`x-opencode-client` and `x-opencode-project`, plus the CLI's per-conversation\n`x-opencode-request` and `x-opencode-session` headers, which the\n`{{opencode-msg-id}}` and `{{opencode-ses-id}}` templates mint fresh per\nrequest in the CLI's 26-character identifier format (provider headers\noverride client-forwarded values; the ids carry no session state, so\nreplacing a genuine client's own ids is functionally neutral). The profile\nalso sets `ensure_tools: [bash, read]`.\n\nA check on 2026-09-24 found zen's\nfree tier gated on that wire signature rather than on TLS, header order or\ncredentials: with the id headers in shape and a chat `tools` array containing\nthe `bash` and `read` tool names, the gated free models served even under\nthe anonymous `public` bearer.\n\n`ensure_tools` injects missing names as inert\nstubs. When the client sent no tools of its own, an absent, null, or `auto`\n`tool_choice` is forced to `none`, while an explicit `none` stays; a\n`required`, named, or malformed choice skips injection entirely, because\nforcing `none` would contradict the client and injecting would let the model\ncall an undeclared stub. When the client already declares at least one tool,\nthe configured names are added to that list and an explicit `required` or\nnamed `tool_choice` stays in force.\n\nA body that already satisfies the\nsignature is relayed unchanged, apart from any configured request override or\nsub-conversation strip that runs before it. The stubs are Chat-shaped, so they\nare injected only into an OpenAI Chat client body on a Chat outbound wire; an\nAnthropic, Responses, Cursor, or arbitrary body is never rewritten.\n\nThe same check found the signature also requires a streaming request\n(`\"stream\": true`): non-streaming requests to the gated free models get the\nprovider's `FreeTierError` 403, so clients of those models must stream (the\nCLI always does). That observation is about that day, not an entitlement: the\nprofile is not an account, key or permission, and there is no zen login\nhelper. Zen's models are listed in\n[OpenCode's Zen documentation](https://opencode.ai/docs/zen/).\n\nEvery profile is editable operator configuration, in the private config file\nor in Settings under Providers (each card edits the field maps, ensured tool\nnames and upstream headers, with hot reload): changing a signature tool set\nor a header value is an edit, never a code change.\n\nTo reproduce another first-party client's signature for a different\nprovider, work from evidence top down: capture the client's own requests\nagainst a local logging upstream, strip one signal at a time against the\nreal endpoint (TLS ClientHello, header order and values, body fields,\ncredentials) until only the gate remains, then express the surviving\nidentity as a provider profile - static headers directly, per-request\ndynamic values as `{{uuid4}}`, `{{platform}}` or a new mint placeholder in the single template\nexpander, and required tool names as `ensure_tools`.\n\nThe zen profile above is one worked example of that recipe,\nnot a hardcoded mechanism.\n\n## Anthropic-compatible Messages\n\n`anthropic` works in both directions: as an upstream selector for a Chat,\nResponses or Anthropic client, and as the inbound protocol for\n`POST /v1/messages`. Translation covers message history, system text,\nimages, tools and results, thinking blocks, cache control, selected parameters,\nusage and streaming events. Fields with no target representation follow the\n[translation loss policy](#cross-protocol-translation).\n\nA configured [sub-conversation\ntracking](configuration.md#sub-conversation-tracking) value is injected as a\ntop-level `prompt_cache_key`. That field is a proxy tracking extension, not an Anthropic\ncache control: Anthropic caching uses `cache_control`, and the injection is only safe\nfor upstreams that tolerate unknown top-level fields.\n\nThe client's own spelling of the tracked field is\notherwise dropped by the allowlist. The caller\nmust supply the native endpoint's correct auth/version/path headers; the\n[protocol example](protocol.md#url-and-auth-examples) demonstrates the mechanism.\n\nStored parameter and conversation-composition metadata describe the translated\nupstream body, not an exact copy of the original request. For a native or\ntranslated Anthropic body, the recorded stop count, tool choice, parallel-tool\nflag, reasoning effort, response format and service tier come from the\nAnthropic spellings (`stop_sequences`, the `tool_choice` type/name and\n`disable_parallel_tool_use`, `output_config`, and `speed`) when the Chat\nspelling is absent.\n\nA body that combines the Responses `max_output_tokens` spelling with a Chat\n`max_tokens` or `max_completion_tokens` spelling is rejected with HTTP 400\nbefore translation or any upstream send. If the caller omits\nall three output-limit spellings (`max_tokens`, `max_completion_tokens` and\n`max_output_tokens`), translation supplies `anthropic_default_max_tokens`,\nwhich can therefore appear in request details as a captured value.\n\nWhen a request supplies both Chat spellings, translation prefers `max_completion_tokens`; the\nproxy's request decode applies the same precedence when capturing the cap,\nso the captured value always agrees with the one the translated body carries\nupstream.\n\nA translated Chat body always spells its output cap `max_tokens`: it has the\nwidest OpenAI-compatible support. OpenAI documents `max_tokens` as deprecated\nand its o-series reasoning models require `max_completion_tokens` instead. A\nnative Chat client may send either spelling, and the decoder prefers\n`max_completion_tokens`, but a translated Chat request still carries\n`max_tokens` and can therefore be refused by a target that accepts only the\nnewer spelling.\n\nAn Anthropic target request forwards `temperature` (clamped to 0..1), `top_p`\nand `top_k` for older and compatible upstreams. The current Anthropic\n`MessageCreateParamsBase` request type no longer lists those sampling fields,\nso a strict current endpoint may reject them. The forwarding is kept as a\ncompatibility choice rather than silently dropping client values; revisit it\nif a live current endpoint is verified to reject them.\n\nNon-streaming translation buffers the full response before committing status;\na translation failure can therefore return a real error status. A translated\nstream is emitted in the client's protocol, not as OpenAI-shaped events, and it\nobserves original-source custom cost privately before final accounting.\nCache-inclusive native usage conversion has one owner; never add reasoning\ntwice when it is already part of output.\n\nA valid native stop marker closes the turn. Missing completion/error state must\nnot be converted into a fabricated clean finish. Legitimate empty/refusal/native\ntool turns are not permission to execute upstream tools again. General native\nmulti-line event assembly still has limits; fixture coverage is not a blanket\nprotocol-conformance claim.\n\nNative model discovery translates and completes supported paginated lists under\nthe shared discovery time/byte/page/entry budget. Optional enrichment fills missing\nfields without replacing upstream-owned values; it draws from the same\ndiscovery entry budget and degrades to the base list when the remainder cannot\nhold its metadata source.\n\nOwners: [format/anthropic.go](../internal/format/anthropic.go),\n[format/models.go](../internal/format/models.go),\n[proxy/relay_transform.go](../internal/proxy/relay_transform.go), and\n[proxy/models.go](../internal/proxy/models.go).\n\n## Cursor Connect bridge\n\n`cursor` is a text/tool bridge from OpenAI chat to the native agent.v1\nbidirectional Connect/protobuf protocol. It currently requires an OpenAI Chat\nclient: a Responses or Anthropic client targeting `cursor` is rejected with a\nclear 400 instead of receiving the wrong response shape. It is not a general multimodal bridge\nor a promise of a stable public provider API. Check the provider's current\naccess terms and supported integration options before using account credentials;\nthe project does not establish permission on your behalf.\n\nThe run owns a bidirectional HTTP/2 transport, framed messages, heartbeat,\ncontext/KV replies and one ordered event queue. Malformed known nested messages,\ninvalid usage or error terminal frames fail explicitly. A validated turn-ended\nmarker plus EOF remains a supported completion convention; bare EOF without\ncompletion is not a clean success.\n\nThe event queue carries an internal retained\nbyte budget and the pending tool-call map internal count and payload byte caps;\nthe KV blob store carries per-run byte and entry caps.\n\nThe parked-run store enforces aggregate budgets across all parked runs:\nretained pending plus queued event bytes, retained blob bytes, and blob\nentries. It holds one per-run pending-plus-queued allowance free for the run\nbeing actively driven, and it rejects admission or growth that would cross\nan aggregate bound. The entry caps bound unique zero-length blobs that the\nbyte cap cannot charge.\n\nExceeding a run or aggregate parked bound fails closed with a stable\ndescriptive error instead of retaining unbounded memory; an over-cap history\nfails the request and a refused park cold-starts the next turn. None of\nthese bounds is operator-tunable.\n\nWhen the upstream requests a client tool, the proxy returns OpenAI tool calls\nand parks the native stream. A later matching tool-result tail can resume that\nsame stream. Full route/auth/model/client scope prevents cross-identity reuse.\nRegistration, expiration and close share the run-store owner; client cancellation\nends active work, while a legitimate parked run lives until its configured TTL,\nupstream close, capacity eviction or process restart.\n\nFor each new send, the tighter of `upstream_timeout` and\n`X-Proxy-Timeout-Ms` bounds waiting for response headers. That wait deadline is\nremoved after headers; it is not an overall body deadline. Resuming an existing\nparked stream does not open another send. The default path is the native Run\nRPC; an explicit `X-Proxy-Path` is appended to the base with a leading slash,\nwithout the HTTP relay's shared-segment deduplication. Query overrides and the\nincoming query are not used.\n\nA lost park cold-starts from provided history. The quality-retry path may re-ask\nan empty continuation; a fresh Run is accepted only on HTTP 200, so any other\nresponse to the re-ask is a failed re-ask and the void surfaces instead of an\nacknowledgement being driven as a stream. Exhausted/invalid continuations\nsurface errors rather than silently completing.\n\nCursor's wire reports one\ncombined output total with no answer/reasoning split, so the generic\nmid-thinking rescue\n(`thinking_retries`) does not apply here: a Cursor turn that produced nothing\nis the existing empty-turn re-ask's business. This is not exactly-once\nexecution, checkpoint persistence, or a guarantee that an upstream keeps a\nparked stream alive.\n\nOutput usage comes from validated native counters. Input may use checkpoint\ncontext occupancy or a documented estimate when unavailable; unreported cache\nand reasoning splits are not invented. Fused model spellings are decomposed by\nthe existing protocol owner, not copied as raw native parameters. Stored model\nmetadata uses the canonical base ID, not the caller's fused spelling.\n\nModel discovery uses the native unary usable-models service and returns the\nconstructed OpenAI list. Context metadata is not guessed from a static price or\ncapability table. Discovery budgets cover this path as well as optional enrichment.\n\nOwners: [proxy/cursor_bidi.go](../internal/proxy/cursor_bidi.go),\n[proxy/cursor_store.go](../internal/proxy/cursor_store.go),\n[format/cursor_run.go](../internal/format/cursor_run.go), and neighboring\nformat/protocol tests. Keep protocol constants distinct from the configurable\n[compatibility profile](#bundled-compatibility-profiles); built-in defaults remain\nneutral and the example does not establish provider support.\n\n### Cursor service and protobuf versions\n\nThe service name, transport version and codec are different layers, not two\nprotobuf implementations running together:\n\n| Layer | What millivolt uses |\n| --- | --- |\n| Cursor service | `agent.v1.AgentService`: bidirectional `Run` and unary `GetUsableModels`. The `v1` is part of the service namespace. |\n| Connect transport | `Connect-Protocol-Version: 1`. Run uses framed `application/connect+proto`; model discovery uses unframed `application/proto`. |\n| Protobuf codec | The limited handwritten encoder/decoder in [proto.go](../internal/format/proto.go), using the adapter's mapped fields. There is no Go protobuf APIv1 or APIv2 dependency. |\n\nThe [Connect specification](https://connectrpc.com/docs/protocol/) defines its\nversion header separately from protobuf. Likewise, Go's\n[APIv1/APIv2 distinction](https://go.dev/blog/protobuf-apiv2) and Buf's\n[JavaScript runtime v2](https://buf.build/blog/protobuf-es-v2) are library versions,\nnot instructions to change `agent.v1` to `agent.v2` or protobuf syntax to proto2.\nThe small codec avoids a generated-runtime dependency, but requires maintaining\nexplicit field mappings and does not promise general protobuf conformance.\n\nA read-only check on 2026-09-06 of the installed Cursor CLI bundle\n`2026.08.11-e8db854` found `agent.v1` descriptors with proto3 semantics and\n`@bufbuild/protobuf` **1.10.1**, not v2. This is evidence about that inspected\nclient artifact, not a claim about every client release or the current server.\nNo live login or inference was used for this check.\n\n## First-login helpers\n\n[grok-login.sh](../scripts/grok-login.sh) and\n[cursor-login.sh](../scripts/cursor-login.sh) obtain initial account credentials\nthrough interactive browser approval. Run them on a trusted Linux host or\nworkstation, not inside the minimal proxy image. Neither a running millivolt\ninstance nor the provider's CLI/desktop application is required by these scripts.\nAccount eligibility, permitted integrations and model access remain the provider's\ndecision; successful authentication does not establish subscription entitlement\nor a free inference allowance.\n\nThe scripts do not write files or update client configuration. They print secret\ncredential headers to standard output, and approval links/progress to standard\nerror. Keep the terminal private: do not use shell tracing (`bash -x`), CI logs,\nscreenshots or shared output redirection. Review a downloaded script before\nrunning it. These helpers have no command-line option parser; configure them\nwith the environment variables below, not `--help` or invented flags.\n\n### Prerequisites and obtaining the scripts\n\nBoth need Bash, `curl`, `jq` and standard Linux command-line utilities. Cursor\nalso needs `openssl` and a curl build with HTTP/2 support; check that\n`curl --version` lists `HTTP2` in Features, as described in the\n[curl HTTP/2 guide](https://everything.curl.dev/http/versions/http2.html).\n`xdg-open` is optional: without it, open\nthe printed approval URL yourself, including from another browser-capable device.\n\nSource checkouts already contain both helpers under `scripts/`. Image-only\ndeployments can download just the desired helper on the host, without cloning\nor rebuilding millivolt:\n\n```sh\ncurl -fsSL https://raw.githubusercontent.com/LLM-4-People/millivolt/main/scripts/grok-login.sh -o grok-login.sh\ncurl -fsSL https://raw.githubusercontent.com/LLM-4-People/millivolt/main/scripts/cursor-login.sh -o cursor-login.sh\n```\n\nUse a new directory so downloads do not overwrite existing files. For a pinned\ninstallation, replace `main` in those URLs with the reviewed commit or release\ntag. Standalone downloads use `bash ./grok-login.sh` or `bash ./cursor-login.sh`\ninstead of the checkout paths below. Do not pipe a download directly into Bash.\n\n### Grok login\n\nFrom a source checkout:\n\n```sh\nbash scripts/grok-login.sh\n```\n\nOpen the printed verification URL, check the account and approve the displayed\ndevice code. The helper polls for approval and prints `Authorization: Bearer`\nwith the access token, `X-Proxy-Refresh-Token` when supplied by the provider, and\n`X-Proxy-Base-URL: https://api.x.ai/v1`. This is an account-login token flow, not\ncreation of a pay-as-you-go `xai-` API key. It does not select a model or add a\nnative-format header; the ordinary OpenAI-compatible relay is used.\n\nFor SSH or a headless terminal, suppress automatic browser opening:\n\n```sh\nNO_OPEN=1 bash scripts/grok-login.sh\n```\n\n### Cursor login\n\nFrom a source checkout:\n\n```sh\nbash scripts/cursor-login.sh\n```\n\nOpen the printed login link and approve the account sign-in. The helper creates\na PKCE challenge, requests HTTP/2 when polling the account endpoint, and prints the access\ntoken, optional refresh token, upstream base URL and `X-Proxy-Format: cursor`.\nUse the printed format header to select the [Cursor bridge](#cursor-connect-bridge);\na provider profile by itself does not enable translation.\n\nThe same headless switch is supported:\n\n```sh\nNO_OPEN=1 bash scripts/cursor-login.sh\n```\n\n### Configure the client after approval\n\nKeep the client's API base pointed at **millivolt**, such as\n`http://127.0.0.1:8080/v1`, using your actual host/port or protected ingress URL.\nThe helper's `X-Proxy-Base-URL` instead identifies the upstream; do not replace\nthe client's millivolt URL with it.\n\n| Printed value | Client configuration |\n| --- | --- |\n| Access token after `Authorization: Bearer ` | Put only the token in an SDK's API-key field, or use the complete printed Authorization header if configuring headers directly. Do not add `Bearer` twice. |\n| `X-Proxy-Base-URL` | Add as a custom request header. |\n| `X-Proxy-Refresh-Token`, when present | Add as a custom request header if using [automatic refresh](#token-refresh); the client must retain rotated credentials returned by the proxy. |\n| `X-Proxy-Format: cursor` | Add for the Cursor helper only. |\n\nSelect a model your account is authorized to use. Keep tokens in private client\nconfiguration or a secret store, not `proxy.example.yaml` or a Git-tracked file.\nMillivolt does not register these credentials globally. If your ingress consumes\nAuthorization, follow the [separate upstream-key setup](reverse-proxy.md#credentials-and-access-control).\n\n### Helper environment overrides\n\nThese affect the login process only, not server Settings or the saved client.\nUse only origins and OAuth registrations you trust: they receive login material.\nDefaults remain owned by each script.\n\n| Variable | Helper | Meaning and default |\n| --- | --- | --- |\n| `NO_OPEN` | Both | Any nonempty value suppresses `xdg-open`; unset or empty permits it. The URL is still printed. |\n| `GROK_LOGIN_TIMEOUT` | Grok | Approval-poll budget in seconds; `600`. Use a positive integer. |\n| `XAI_AUTH_BASE` | Grok | Login origin; `https://auth.x.ai`. Does not change the printed inference base. |\n| `XAI_OAUTH_CLIENT_ID` | Grok | OAuth registration; defaults to the client ID shared with the proxy's xAI refresh implementation. |\n| `CURSOR_LOGIN_TIMEOUT` | Cursor | Approval-poll budget in seconds; `300`. Use a positive integer. |\n| `CURSOR_API_BASE` | Cursor | Poll origin and printed inference base; `https://api2.cursor.sh`. |\n| `CURSOR_LOGIN_BASE` | Cursor | Browser login origin; `https://www.cursor.com`. |\n\nTimeouts are polling budgets, not strict end-to-end deadlines: a current HTTP\noperation or sleep can extend elapsed time. Changing Grok's auth origin/client\nID does not change millivolt's xAI refresh endpoint/registration, so a custom login\ncan be incompatible with renewal. Cursor refresh targets the request's base URL\nand still requires a recognized refresh mechanism. These overrides do not\nestablish support for arbitrary identity providers or compatible service clones.\n\n### Login troubleshooting\n\n| Symptom | What to check |\n| --- | --- |\n| Required tool not found | Install the named dependency on the host running the helper, not in the proxy image. |\n| No browser opens | Open the printed URL manually. `NO_OPEN=1` deliberately disables automatic opening. |\n| Cursor reports unsupported HTTP/2 or keeps waiting | Check `curl --version` for HTTP2 support and inspect its diagnostics. The helper keeps polling non-200 responses until its budget expires. |\n| Approval times out, expires or is denied | Verify the account/browser approval, then rerun for a fresh login challenge. Never reuse an expired code. |\n| No refresh token is printed | The helper warns and omits that header. Millivolt cannot renew without it; obtain another login when the access token expires. |\n| Login succeeds but inference returns 401/403 | Check client headers, upstream base, account permissions and model availability. Login alone does not prove inference access. |\n| Grok or Cursor repeatedly returns `token_expired` | The client must adopt the returned access token and any rotated refresh token, then retry. Repeating the old credentials does not complete handback. |\n| Refresh is rejected | Recheck provider access and perform a new interactive login. Do not publish token responses or credential headers for troubleshooting. |\n\n## Token refresh\n\nWith `auto_token_refresh` enabled, a request may supply its own\n`X-Proxy-Refresh-Token`. The proxy can exchange an expiring JWT for supported\nmechanisms; it stores neither a credential database nor reusable refresh state.\nThe JWT expiry check is not signature authentication.\n\n**Grok and Cursor use the same inference handback behavior.** A successful\nexchange returns HTTP 401 with error type `authentication_error` and code\n`token_expired`. The error object includes `access_token` and, when the\nexchange returned a different refresh token, `refresh_token`. The same\nvalues are in the error message. No inference is sent or recorded for that\nhandback. The client stores the returned access token, adopts any returned\nrefresh token, and retries the original request.\n\nStarting with **0.2.0**, Cursor no longer refreshes in place on inference requests.\nClients that previously relied on that behavior must now handle the same 401\nhandback as Grok. Starting with **0.3.1**, credentials are in that error body,\nnot `X-Proxy-Access-Token` / `X-Proxy-Refresh-Token` response headers. Update\nclient handling before upgrading; a generic client that only reads those\nheaders cannot complete automatic renewal. Retry only after adopting the\nfresh access token, not by blindly replaying an old key.\n\nModel discovery refreshes transparently instead of requiring the handback\nworkflow, but does not return updated tokens to the client.\nMissing refresh tokens, unknown mechanisms, non-JWT keys or disabled\nrefresh leave ordinary forwarding unchanged. Exchange failure falls back to the\noriginal upstream credential, allowing the provider to decide authentication.\n\nUse the [first-login helpers](#first-login-helpers) to obtain initial credentials.\nThey are not proxy startup dependencies. Treat terminal output and returned tokens\nas secrets; never paste them into issues or commit them. Adopt a returned\nrefresh token when present; if a successful exchange omits it, including when\nthe provider echoed the same refresh token, retain the existing refresh token\nrather than replacing it with an empty value.\n\nThe implementation lives in [tokenrefresh.go](../internal/proxy/tokenrefresh.go).\nProvider/account behavior can change; historic successful observations are not\ncompatibility or authorization guarantees.\n"
    },
    {
      "path": "docs/mcp.md",
      "slug": "docs/mcp",
      "output": "docs/mcp.html",
      "markdown": "docs/mcp.md",
      "url": "https://millivolt.llm4people.dev/docs/mcp.html",
      "markdown_url": "https://millivolt.llm4people.dev/docs/mcp.md",
      "title": "MCP server",
      "description": "The proxy's own /mcp endpoint exposes millivolt's operator and observability API to an LLM, using the official Model Context Protocol Go SDK . It is a...",
      "group": "Integrate",
      "order": 6,
      "bytes": 30609,
      "sha256": "4dac0fac6e635f0e5ed87e428f34fc253571f10ec93cf3df2dbed3a486ca6b42",
      "sections": [
        {
          "heading": "URL placement",
          "id": "url-placement",
          "text": "A URL-capable client (an editor agent, a hosted connector, an MCP-capable CLI) needs no binary and no environment: it points at the proxy's /mcp endpoint and presents the operator credential in an Authorization header, the same credential the dashboard uses. { \"mcpServers\": { \"millivolt\": { \"url\": \"http://127.0.0.1:8080/mcp\", \"headers\": { \"Authorization\": \"Bearer the same value the proxy was started with\" } } } } A remote client uses the reverse-proxied HTTPS origin from the reverse-proxy guide , with /mcp appended: { \"mcpServers\": { \"millivolt\": { \"url\": \"https://your-hostname/mcp\", \"headers\": { \"Authorization\": \"Bearer the same value the proxy was started with\" } } } } The header is the whole setup: the endpoint reads no environment, starts no process, and no session cookie or per-request state outlives the request. Every request is independently authenticated, so a missing or wrong Bearer is denied before any tool runs, and a request presenting only the dashboard session cookie is refused with 403, because the caller's own credential is what the internal calls carry. /mcp/ look-alikes are reserved: an unregistered path answers 404 and is never forwarded to inference. The publish",
          "context": ""
        },
        {
          "heading": "Tools",
          "id": "tools",
          "text": "describe is the one to call first for this instance's live schema; without it, correct SQL is guesswork. docs_list is the one to call first for how millivolt itself works: it indexes the same Markdown as the published site and needs no proxy request. The three docs tools read internal/docs/docs.json , which is generated from the same Markdown as the published site by scripts/build_site.py . Refresh the embedded copy with python3 scripts/build_site.py --output site --write-manifest after any page, title or navigation change. The tools never call the proxy, read storage, or use the operator credential. A full page is capped at 256 KiB by internal/mcp/tools_docs.go . Tool Purpose describe Live SQLite schema, the complete requests / request_debug / meta column reference, the exact health predicates, a value vocabulary for every filter dimension, the live known client/provider/model and tool names, the indexes, the complete result-limit set (the query row default and explicit max_rows ceiling, query bytes, log page band, default page size, explorer group and chart bucket caps, Prometheus line cap and capture byte budget), and the working SQL idioms for this build. docs_list Every publis",
          "context": ""
        },
        {
          "heading": "Filters",
          "id": "filters",
          "text": "explore , chart , records and the explorer facets share one grammar, owned in one place. Filters are dim:id , repeated, split on the FIRST colon, AND-ed across dimensions and OR-ed within one dimension. dim is one of client , provider , model , conversation , key , status , time , tool , error . key is the SHA-256 hash of the client key. status is a single selector: an exact HTTP status code ( 0 to 9999 ) or a live in-flight class ( streaming , paused , throttled , pending ). It is not the explorer's status-class vocabulary, which travels as status:2xx . Two bounds apply to f= itself: at most 64 filters, and each dim:id value at most 2048 bytes. The list is refused whole when either is exceeded; no filter is silently dropped. An unknown dimension, malformed filter or unknown status is refused before the request is sent. explore 's error_total uses two units. With dim: error it is the union of distinct affected requests represented by the error cards, including recovered quality failures whose final status is 200; for every other dimension it is the canonical error count. A card share is N / error_total and cannot exceed 100%. Do not compare it across the two cases as one metric.",
          "context": "Tools"
        },
        {
          "heading": "Pagination",
          "id": "pagination",
          "text": "records and audit_captures_list page newest-first with a paired (before_ms, before_id) cursor. Both fields or neither. The proxy scans a bounded number of rows per call, so a page can be short or empty while its more flag is still true. exhausted is true when a page that was given a cursor returns that same cursor, and also when more is false: treat it as \"stop paging\". A first page has no cursor to repeat, so any returned cursor counts as progress, including (0, \"\") . A non-advancing cursor means the scan budget cannot reach the next row, and treating it as \"keep going\" is an endless loop; an empty page with an advanced cursor is instead the normal shape of \"the budget ran out before a match\", so page again. Deep history needs this rather than OFFSET , which degrades on every page.",
          "context": "Tools"
        },
        {
          "heading": "Volume",
          "id": "volume",
          "text": "A model cannot read ten thousand rows. Every listing defaults to a small page, and every tool truncates with an explicit marker ( truncation.marker ) naming what was withheld and the way to continue for that tool, because only some of them have a cursor. What is not claimed: the explorer caps groups at 24 and the chart caps buckets at 31 SERVER-SIDE, so those drops happen inside the proxy and those tools' truncation.truncated is false when groups were dropped. A model that trusts that flag alone will read a short breakdown as a complete one.",
          "context": "Tools"
        },
        {
          "heading": "What each tool cannot do",
          "id": "what-each-tool-cannot-do",
          "text": "These are the limits that otherwise send a model down the wrong path. They are also in the tool descriptions, which is where a model reads them. describe first. Without the live schema, the column meanings, the health predicates and the value vocabularies, correct SQL is guesswork. explore has no time window. It always folds all history. It is also single-dimension: it cannot cross-tabulate provider by model. For either, use query with a WHERE on started_at and a GROUP BY . chart is the only windowed tool, and it cannot group. A window broken down by a dimension is a query . query is the only tool that can express a time range. There is no unixnow() in this SQLite build, so a relative window is strftime('%s','now')*1000 , for example WHERE started_at >= strftime('%s','now')*1000 - 3600000 for the last hour. Ready-to-run analysis SQL for exactly these time-ranged questions is collected in the operator recipes . An unknown filter value is an empty result, not an error. A misspelled client, provider, model, tool, conversation or key produces a confident zero. Call values before filtering on one of those. Model filters take the canonical name the proxy folds from model_rules (which is ",
          "context": "Tools"
        },
        {
          "heading": "Audit semantics",
          "id": "audit-semantics",
          "text": "Audit is the proxy's debug-capture subsystem. Capture requires durable storage. With db_path empty, audit_start is refused by the proxy with 503 durable storage is disabled and creates no session; every capture read-back is a 404 because no capture document can exist. audit_start and audit_captures_list therefore check the storage signal first and refuse with that explanation, and audit_status reports it. Starting a session that can never capture would be a silent no-op, which is worse than a refusal. Scope is explicit. An empty dimension matches anything; non-empty dimensions are AND-ed and names within one dimension are OR-ed. There is no unrestricted all-traffic scope, and there is no conversation dimension. Model names use the proxy's native model normalization, so use the known_models values rather than guessing spellings. A scope overlapping a live session is rejected ( 409 ) rather than silently replacing it. Edits change only named dimensions. With a session id, an omitted clients , providers or models field preserves that dimension and an explicitly empty array clears it. An omitted duration preserves the deadline and an explicit empty string clears it. A create response a",
          "context": ""
        },
        {
          "heading": "The destructive call",
          "id": "the-destructive-call",
          "text": "purge permanently deletes matching request history. The proxy has NO server-side confirmation, NO confirm flag and NO two-step protocol. The operator credential and this tool's own guards are the entire gate. Three guards apply together, and each alone would be insufficient: The filter must constrain at least one field. The bodyless request that deletes ALL history is never sent by this tool; an empty filter is refused before any request. The confirmation must be an exact phrase. confirmation: \"permanently delete the matching millivolt history\" . It is also a required tool argument, so a call that omits it is rejected by the schema before the handler runs. preview_token must be the token purge_preview issued for THIS filter. It is an opaque HMAC-bound token over the canonicalized filter, the count it authorized and an expiry, so it cannot be forged, cannot be reused for another filter, and expires 15 minutes after issue . A bare count could not do this: it is only a number, so two different filters matching the same number of rows authorized each other, and a count obtained from anywhere - a query , a guess, a preview of a different filter - satisfied the comparison. That was a liv",
          "context": ""
        },
        {
          "heading": "What the guard does not prevent",
          "id": "what-the-guard-does-not-prevent",
          "text": "Stated plainly, because an operator needs to know the size of the remaining window: The count compares a population, not row identities. The count is re-checked immediately before deleting, and the reviewed count travels with the delete, where the proxy counts it again inside the delete transaction and refuses with 409 when it moved. Nothing un-previewed is deleted by a refused call, but two different populations with the same row count are indistinguishable, and a refusal means previewing again. A filter that reaches a captured request deletes its capture document too. The preview and the deletion both say so in their output. Deleted history cannot be recovered from this API. The deletion preserves newer completions and in-flight work and does not reset live error-storm protection. set_config is the other consequential call, and it is a revision-checked partial patch: values carries only the keys to change, the whole result is validated before the file is written, CLI-overridden keys are stripped, and the response names the keys that need a restart. A supplied list or map replaces that whole field, so call config_get first for structured keys such as providers or model_rules , and",
          "context": "The destructive call"
        },
        {
          "heading": "Errors",
          "id": "errors",
          "text": "Every failure is a tool result the model can read and correct, carrying the proxy's own .error text and the status: 401 (credential wrong or missing), 403 (the proxy's operator plane is unarmed, or the request carried only the dashboard session cookie), 404 , 409 (overlap or stale revision), 413 (a result limit), and 429 with its Retry-After . An unreachable proxy, a timeout, and a body that is not the expected document are reported the same way. The .error field is read regardless of Content-Type , because the operator routes are inconsistent and some answer text/plain with a JSON body. The returned text is scrubbed of the operator credential first, because a reflecting endpoint could otherwise put the Authorization value into its own failure message and hand it to the model. The scrub removes the literal token, any contiguous 8-byte fragment of it (so a credential split across two JSON string fields leaks no usable piece), percent escapes in any hex case (including full-byte nested forms), the query + form of a space, and JSON-escaped forms, including backslash-doubled text and surrogate pairs. Each form is decoded to a fixed point before matching: an encoding is either fully see",
          "context": ""
        },
        {
          "heading": "Try it against a disposable instance",
          "id": "try-it-against-a-disposable-instance",
          "text": "Run the endpoint locally against a disposable instance with the repository's lifecycle owner, never the main instance on :8080 , and drive it with one stateless POST: ( set -e trap 'scripts/dev.sh stop' EXIT export MILLIVOLT_OPERATOR_TOKEN='dev-instance-credential' scripts/dev.sh curl -fsS -X POST http://127.0.0.1:8081/mcp \\ -H \"Authorization: Bearer $MILLIVOLT_OPERATOR_TOKEN\" \\ -H 'Accept: application/json, text/event-stream' \\ -H 'Content-Type: application/json' \\ -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{},\"clientInfo\":{\"name\":\"probe\",\"version\":\"0\"}}}' ) The answer carries the server identity. A full client session is the client configuration above pointed at http://127.0.0.1:8081/mcp ; a request without the Bearer credential answers 401 from the operator gate.",
          "context": ""
        },
        {
          "heading": "Security",
          "id": "security",
          "text": "The endpoint is driven with an operator credential, which is the whole dashboard plane: pause, limits, configuration, restart, purge. Treat the client configuration that carries it as sensitive and keep it out of shared repositories. See Security .",
          "context": ""
        },
        {
          "heading": "Verification",
          "id": "verification",
          "text": "The unit suite uses a fake proxy that pins the exact method, path, query and Authorization header of every tool, maps canned responses onto typed output, and covers the error shapes, setup validation, truncation markers, the pagination rule and the purge guards. tests/_go/internal/docs checks the embedded copy against every source hash. tests/python/site.py checks the published Markdown twins, llms.txt , llms-full.txt and docs.json against the same page model. The paging rule has one owner shared with audit_captures_list , so the two listings cannot disagree. One of its tests runs outside that harness on purpose: the redirect test stands up a second listener as the redirect target and asserts it received nothing, so \"we refused the redirect\" is an observation rather than an assertion about an error string. the capture listing test executes the generated SELECT against a real SQLite schema with empty, space-padded, tab-padded and NBSP-padded sidecars, and asserts they are excluded while every returned id has an unexpired sidecar and is the exact spelling audit_capture_get can fetch. This page is mechanically pinned by tests/python/mcp_docs.py : the tool table must match the addTool ",
          "context": ""
        }
      ],
      "markdown_text": "# MCP server\n\nThe proxy's own `/mcp` endpoint exposes millivolt's operator and\nobservability API to an LLM, using the official\n[Model Context Protocol Go SDK](https://github.com/modelcontextprotocol/go-sdk).\nIt is a client of a running proxy: it never starts, stops or restarts the proxy\nprocess. Its operator tools can reconfigure a running proxy, but only through\nthe same credential and the same routes the dashboard uses.\n\nThe endpoint serves 25 tools from one implementation. It is operator-gated\nand Bearer-only, enabled by default: `mcp_enabled: false` removes it from the\nprocess (the route stays reserved, answering 404 and never inference; restart\nto apply), and the limits are config fields in the `mcp` category. It\nforwards the caller's own `Authorization: Bearer` credential on its internal\ncalls, so the dashboard session cookie is refused there.\n\nThe token length band matches the proxy's own boot check (16 to 512\nbytes). A credential the proxy would refuse to arm with is not a\ncredential this server can use.\n\nRedirects are refused outright. No operator route redirects, and `net/http` strips\n`Authorization` only when the hostname changes, so a same-host different-port or\nsubdomain `307`/`308` would replay both the credential and the full request body\nto the redirect target.\n\n## URL placement\n\nA URL-capable client (an editor agent, a hosted connector, an MCP-capable CLI)\nneeds no binary and no environment: it points at the proxy's `/mcp` endpoint\nand presents the operator credential in an `Authorization` header, the same\ncredential the dashboard uses.\n\n```json\n{\n  \"mcpServers\": {\n    \"millivolt\": {\n      \"url\": \"http://127.0.0.1:8080/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer the same value the proxy was started with\"\n      }\n    }\n  }\n}\n```\n\nA remote client uses the reverse-proxied HTTPS origin from\n[the reverse-proxy guide](reverse-proxy.md), with `/mcp` appended:\n\n```json\n{\n  \"mcpServers\": {\n    \"millivolt\": {\n      \"url\": \"https://your-hostname/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer the same value the proxy was started with\"\n      }\n    }\n  }\n}\n```\n\nThe header is the whole setup: the endpoint reads no environment, starts no\nprocess, and no session cookie or per-request state outlives the request. Every\nrequest is independently authenticated, so a missing or wrong Bearer is denied\nbefore any tool runs, and a request presenting only the dashboard session\ncookie is refused with 403, because the caller's own credential is what the\ninternal calls carry.\n\n`/mcp/` look-alikes are reserved: an unregistered path\nanswers 404 and is never forwarded to inference. The published Compose port is\nloopback-only, so it is not a remote origin; remote clients terminate TLS at\nthe ingress as in the [reverse-proxy guide](reverse-proxy.md).\n\nThe transport is stateless and request/response only, and its limits are part\nof choosing a client:\n\n- `GET` and `DELETE` answer `405` with `Allow: POST`. There is no standalone\n  SSE stream and no session to delete.\n- There is no session id: the endpoint never sends `Mcp-Session-Id`, and no\n  per-request state outlives the request. No session cookie is minted here\n  either, unlike `/admin`, `/session`, `/metrics` and `/dash`, so an MCP client's\n  cookie jar gains no dashboard credential; a client must not expect or send a\n  session id. The admitted credential does key an in-process cache of the SDK\n  server object, so repeated calls do not rebuild all 25 tool registrations;\n  admitting a different credential replaces it. The credential is only the\n  in-memory cache key: it is never logged or persisted.\n- SSE resumption is not offered: no event store exists, so `Last-Event-ID`\n  replay is not available.\n- The server never sends requests to the client: there is no sampling and no\n  elicitation, so a client that waits for a server-initiated request waits\n  forever.\n- Every request must accept both types, for example\n  `Accept: application/json, text/event-stream`. A wildcard that covers both\n  (`*/*`, `application/*, text/*`) is accepted too; an `Accept` missing either\n  type, or one absent altogether, answers `400`.\n- The accepted protocol versions are the bundled SDK's full set, newest first:\n  `2026-07-28`, `2025-11-25`, `2025-06-18`, `2025-03-26` and `2024-11-05`.\n  This build does not narrow them. A classic `initialize` is answered with the\n  requested version when it is one of the legacy versions (`2025-11-25` and\n  older, verified live) and with `2025-11-25` for any other requested version;\n  `2026-07-28` is served only through the SDK's per-request metadata form:\n  the request carries `Mcp-Protocol-Version: 2026-07-28`, matching `_meta` keys\n  `io.modelcontextprotocol/protocolVersion` and\n  `io.modelcontextprotocol/clientCapabilities`\n  (`io.modelcontextprotocol/clientInfo` is optional), and the `Mcp-Method`\n  header. `tools/call` additionally requires an `Mcp-Name` header equal to\n  `params.name`; a form missing any required piece answers `400`.\n- The SDK's localhost DNS-rebinding check is deliberately off. It rejects a\n  loopback connection whose `Host` is not loopback, and the documented\n  reverse-proxied placement preserves the external `Host` while dialing the\n  proxy over loopback, so leaving it on would reject that placement. The\n  endpoint is Bearer-only and the operator gate re-validates the credential on\n  every request, which is the stronger check for an authenticated endpoint.\n\n## Tools\n\n`describe` is the one to call first for this instance's live schema; without\nit, correct SQL is guesswork. `docs_list` is the one to call first for how\nmillivolt itself works: it indexes the same Markdown as the published site and\nneeds no proxy request.\n\nThe three docs tools read `internal/docs/docs.json`, which is generated from the\nsame Markdown as the published site by `scripts/build_site.py`. Refresh the\nembedded copy with `python3 scripts/build_site.py --output site --write-manifest`\nafter any page, title or navigation change. The tools never call the proxy,\nread storage, or use the operator credential. A full page is capped at 256 KiB\nby `internal/mcp/tools_docs.go`.\n\n| Tool | Purpose |\n| --- | --- |\n| `describe` | Live SQLite schema, the complete `requests`/`request_debug`/`meta` column reference, the exact health predicates, a value vocabulary for every filter dimension, the live known client/provider/model and tool names, the indexes, the complete result-limit set (the query row default and explicit `max_rows` ceiling, query bytes, log page band, default page size, explorer group and chart bucket caps, Prometheus line cap and capture byte budget), and the working SQL idioms for this build. |\n| `docs_list` | Every published documentation page in navigation order, with its path, title, description, public URL, Markdown URL and section count. Starts the docs flow; local only. |\n| `docs_search` | Ranked section search across titles, headings and body text, with path, anchor, heading context and a snippet. Every query word must match; the result reports its total and truncation. Local only. |\n| `docs_read` | One page by path, or one anchored section by heading id. Full-page Markdown is capped at 256 KiB with an explicit marker. This is the canonical explanation of millivolt's routes, configuration, protocol and operator behavior. Local only. |\n| `query` | One bounded `SELECT`, clamped on both rows and encoded size, truncating with an explicit marker. The only tool that can express a time range. |\n| `values` | The distinct values one dimension has in durable history, most frequent first, so a filter value is discovered rather than guessed. |\n| `explore` | Faceted breakdown over all matching history by one dimension, with at most 24 groups. No time window. |\n| `chart` | Server-authoritative time series, at most 31 clock-aligned buckets. Cannot group. |\n| `records` | One durable newest-first log page, with the paired `before_ms`/`before_id` cursor and the page's `model_canon` map. |\n| `snapshot` | The dashboard's live snapshot: sequence, feed, counters, storage signal, recent records. With durable storage enabled, a full snapshot is capped at `2 * dash_log_rows`; with storage off the ring is the only history and the snapshot is not capped. |\n| `prometheus` | The text exposition, which covers the ring rather than durable since-inception totals. |\n| `audit_status` | Capture sessions, their scope and live capture counts, the scope vocabularies, and the storage prerequisite. |\n| `audit_start` | Start or edit one capture session. Requires `confirm: \"start capture\"` and refuses when durable storage is off. |\n| `audit_stop` | Stop one session by id, or every session with `stop_all: \"stop every capture session\"`. |\n| `audit_captures_list` | Page the requests that have a stored capture, through a bounded `SELECT` over `requests WHERE debug = 1` whose `request_debug` sidecar exists and has not expired. Ids are canonical: empty and whitespace-padded record ids are excluded because `audit_capture_get` could not read them back. |\n| `audit_capture_get` | Read one capture document by request record id. |\n| `operator_state` | Pause, limits, quota/storm and restart status in one call. |\n| `set_pause` | Create, edit or resume pause holds. |\n| `set_throttle` | Set, merge or clear one provider's caps, including the optional anti-burst pair. |\n| `resume_quota` | Close one provider's open retry-mode quota gate. |\n| `set_config` | Revision-checked partial configuration patch. |\n| `config_get` | The live configuration document: values, running overrides (the keys the process pins outside the file, which `set_config` strips), the canonical usage and model metadata field names, defaults, per-key schema, restart-required set and the revision a patch must echo. Credential-class provider headers and last-reload error text are redacted; use the operator CLI with `--reveal` for the raw bytes. |\n| `reload_config` | Re-read the configuration file. |\n| `purge_preview` | Count what a filter would delete, without deleting. |\n| `purge` | Delete matching history permanently. |\n\nThe routes are a closed set owned beside the HTTP client, so no tool can name\nan arbitrary path: nothing reaches the proxy's transparent inference\ncatch-all, and no restore-adjacent route is exposed. The HTTP endpoint\ndispatches those same calls in process to the proxy's own gated handler, so\nthey never leave the process and the gate re-validates the forwarded Bearer.\n\n`set_throttle` takes `provider` and any of `concurrency`,\n`requests`/`request_window`, `tokens`/`token_window`, `anti_burst` and\n`ramp_duration`; omitted dimensions keep their value.\n\nA count needs its own\nwindow only when the policy stores none for that dimension, a count of `0`\nclears the dimension with its window, and a window without a count is refused\nunless a count is already stored. `clear: true` drops the whole policy and\ncannot be combined with a dimension. The proxy owns\nthe duration grammar and band and refuses an explicit on-ramp without an\nactive limit.\n\nThis tool addresses one provider and has no selector or schedule\nfields. Scoped selectors and recurring schedules are available through the HTTP\nAPI (`/admin/throttle`) and the dashboard console, not through MCP.\n\n`set_pause` refuses a resume that carries a scope, and refuses `all` combined\nwith `new`, `clients` or `providers`. `config_get` and the `set_config` echo\nredact credential-class provider headers and last-reload error text; the CLI's\n`--reveal` flag is the explicit operator opt-in. A redacted document posted\nback through `set_config` keeps the loaded secret: the marker is restored at the\nwrite owner, so a read-then-repost round trip cannot erase a credential.\n\n### Filters\n\n`explore`, `chart`, `records` and the explorer facets share one grammar, owned in\none place. Filters are `dim:id`, repeated, split on the FIRST colon, AND-ed\nacross dimensions and OR-ed within one dimension. `dim` is one of `client`,\n`provider`, `model`, `conversation`, `key`, `status`, `time`, `tool`, `error`.\n`key` is the SHA-256 hash of the client key.\n\n`status` is a single selector: an exact HTTP status code (`0` to `9999`) or a\nlive in-flight class (`streaming`, `paused`, `throttled`, `pending`). It is not\nthe explorer's status-class vocabulary, which travels as `status:2xx`.\n\nTwo bounds apply to `f=` itself: at most 64 filters, and each `dim:id` value at\nmost 2048 bytes. The list is refused whole when either is exceeded; no filter\nis silently dropped.\n\nAn unknown dimension, malformed filter or unknown status is refused before the\nrequest is sent.\n\n`explore`'s `error_total` uses two units. With `dim: error` it is the union of\ndistinct affected requests represented by the error cards, including recovered\nquality failures whose final status is 200; for every other dimension it is the\ncanonical error count. A card share is `N / error_total` and cannot exceed 100%.\nDo not compare it across the two cases as one metric.\n\n### Pagination\n\n`records` and `audit_captures_list` page newest-first with a paired\n`(before_ms, before_id)` cursor. Both fields or neither.\n\nThe proxy scans a bounded number of rows per call, so a page can be short or\nempty while its `more` flag is still true. `exhausted` is true when a page that\nwas given a cursor returns that same cursor, and also when `more` is false:\ntreat it as \"stop paging\".\n\nA first page has no cursor to repeat, so any returned\ncursor counts as progress, including `(0, \"\")`. A non-advancing cursor means the\nscan budget cannot reach the next row, and treating it as \"keep going\" is an\nendless loop; an empty page with an advanced cursor is instead the normal shape\nof \"the budget ran out before a match\", so page again.\n\nDeep history needs this rather than `OFFSET`, which degrades on every page.\n\n### Volume\n\nA model cannot read ten thousand rows. Every listing defaults to a small page,\nand every tool truncates with an explicit marker (`truncation.marker`) naming\nwhat was withheld and the way to continue for that tool, because only some of\nthem have a cursor.\n\nWhat is *not* claimed: the explorer caps groups at 24 and the chart caps buckets\nat 31 SERVER-SIDE, so those drops happen inside the proxy and those tools'\n`truncation.truncated` is `false` when groups were dropped. A model that trusts\nthat flag alone will read a short breakdown as a complete one.\n\n### What each tool cannot do\n\nThese are the limits that otherwise send a model down the wrong path. They are\nalso in the tool descriptions, which is where a model reads them.\n\n- `describe` first. Without the live schema, the column meanings, the health\n  predicates and the value vocabularies, correct SQL is guesswork.\n- **`explore` has no time window.** It always folds all history. It is also\n  single-dimension: it cannot cross-tabulate provider by model. For either, use\n  `query` with a `WHERE` on `started_at` and a `GROUP BY`.\n- **`chart` is the only windowed tool, and it cannot group.** A window broken\n  down by a dimension is a `query`.\n- **`query` is the only tool that can express a time range.** There is no\n  `unixnow()` in this SQLite build, so a relative window is\n  `strftime('%s','now')*1000`, for example\n  `WHERE started_at >= strftime('%s','now')*1000 - 3600000` for the last hour.\n  Ready-to-run analysis SQL for exactly these time-ranged questions is\n  collected in the [operator recipes](routes.md#operator-recipes).\n- An **unknown filter value is an empty result, not an error.** A misspelled\n  client, provider, model, tool, conversation or key produces a confident zero.\n  Call `values` before filtering on one of those. Model filters take the\n  **canonical** name the proxy folds from `model_rules` (which is what the\n  `values` tool returns), never a raw stored spelling.\n- **`values(model)` is paged and folded.** The tool reads raw spellings in\n  bounded keyset pages, so a vocabulary larger than the proxy's\n  `storage_query_max_rows` no longer fails with 413, then folds and merges the\n  pages through `model_rules`. Past its documented raw-spelling,\n  canonical-name, or total page-query bound it fails explicitly rather than\n  returning a partial vocabulary. The ordinary `limit` still reports its own\n  explicit truncation marker.\n- `time` is a **daypart bucket**, not a duration: `time:24h` matches nothing. The\n  buckets are `night`, `work`, `evening` and `weekend`.\n- `status` takes the proxy's **status classes**, not HTTP shorthand: `2xx`,\n  `cancel` (499), `4xx`, `5xx` and `err` (anything outside those, including\n  3xx and below 200). There is no `3xx` class of its own.\n\n## Audit semantics\n\nAudit is the proxy's debug-capture subsystem.\n\n**Capture requires durable storage.** With `db_path` empty, `audit_start` is\nrefused by the proxy with 503 `durable storage is disabled` and creates no\nsession; every capture read-back is a 404 because no capture document can\nexist. `audit_start` and `audit_captures_list` therefore check the storage\nsignal first and refuse with that explanation, and `audit_status` reports it.\nStarting a session that can never capture would be a silent no-op, which is\nworse than a refusal.\n\n**Scope is explicit.** An empty dimension matches anything; non-empty dimensions\nare AND-ed and names within one dimension are OR-ed. There is no unrestricted\nall-traffic scope, and there is no conversation dimension. Model names use the\nproxy's native model normalization, so use the `known_models` values rather than\nguessing spellings. A scope overlapping a live session is rejected (`409`)\nrather than silently replacing it.\n\n**Edits change only named dimensions.** With a session id, an omitted\n`clients`, `providers` or `models` field preserves that dimension and an\nexplicitly empty array clears it. An omitted `duration` preserves the deadline\nand an explicit empty string clears it.\n\nA create response also carries\n`created_id`, the id its own request installed, so concurrent starts resolve\ntheir own sessions. `set_pause` follows the same presence rules for scope and\nduration when `hold_id` targets an edit; without `hold_id`, an omitted create\nscope is the documented global hold.\n\n**Starting requires a confirmation.** `audit_start` takes\n`confirm: \"start capture\"` because capture stores full request and response\nbodies.\n\n**Stopping does not delete, but a purge does.** Stopping a session, or all of\nthem, ends future captures only: a stopped session's documents stay readable by\nrecord id until `debug_capture_ttl` expires. There is no capture-specific delete\nendpoint, but a `purge` deletes the stored capture document of every request it\nmatches, in the same transaction as the request row. A filter that reaches a\ncaptured request takes its evidence with it. Only a backup taken beforehand\nrestores it.\n\n**A scope name must be known when the vocabulary is.** `audit_start` checks\nevery client, provider and model against the vocabulary `audit_status` reports.\nWhen that vocabulary is non-empty, an unknown name is refused with the known\nvalues offered, because a session scoped to a name that matches nothing would\nreport `enabled: true` and capture nothing.\n\nAn empty vocabulary is the\nexception: a proxy that has seen nothing knows no names, so refusing every name\nwould make the tool unusable rather than safer and the check is skipped. A\nvocabulary that cannot be read is not a skip: the start is refused, because the\nguard cannot be applied at all.\n\n**Read-back is by record id.** `audit_capture_get` takes the REQUEST RECORD id\n(`requests.id`), not the session id. There is no listing endpoint, so\n`audit_captures_list` discovers those ids by querying `requests WHERE debug = 1`\nwith an existing, unexpired `request_debug` sidecar and reports that it does so.\n\nThe listing also excludes an id that is empty or padded with whitespace: the\ncapture route trims the id before lookup while the sidecar key is stored\nverbatim, so such an id could be advertised but never fetched. Every listed id\nis therefore readable.\n\nCaptured documents are sensitive: credentials are\nredacted from headers, but body content is not sanitized.\n\n**Sessions survive a restart.** The proxy restores them from its own state, so a\nstart list may already contain sessions this server did not create.\n\n## The destructive call\n\n`purge` permanently deletes matching request history. The proxy has NO\nserver-side confirmation, NO confirm flag and NO two-step protocol. The operator\ncredential and this tool's own guards are the entire gate.\n\nThree guards apply together, and each alone would be insufficient:\n\n1. **The filter must constrain at least one field.** The bodyless request that\n   deletes ALL history is never sent by this tool; an empty filter is refused\n   before any request.\n2. **The confirmation must be an exact phrase.**\n   `confirmation: \"permanently delete the matching millivolt history\"`. It is\n   also a required tool argument, so a call that omits it is rejected by the\n   schema before the handler runs.\n3. **`preview_token` must be the token `purge_preview` issued for THIS filter.**\n   It is an opaque HMAC-bound token over the canonicalized filter, the count it\n   authorized and an expiry, so it cannot be forged, cannot be reused for another\n   filter, and expires **15 minutes after issue**. A bare count could not do this: it is only a number, so\n   two different filters matching the same number of rows authorized each other,\n   and a count obtained from anywhere - a `query`, a guess, a preview of a\n   different filter - satisfied the comparison. That was a live bypass, not a\n   theoretical one.\n\nAlways run `purge_preview` first and pass its `preview_token` back verbatim.\n\n### What the guard does not prevent\n\nStated plainly, because an operator needs to know the size of the remaining\nwindow:\n\n- **The count compares a population, not row identities.** The count is\n  re-checked immediately before deleting, and the reviewed count travels with\n  the delete, where the proxy counts it again inside the delete transaction and\n  refuses with 409 when it moved. Nothing un-previewed is deleted by a refused\n  call, but two different populations with the same row count are\n  indistinguishable, and a refusal means previewing again.\n- **A filter that reaches a captured request deletes its capture document too.**\n  The preview and the deletion both say so in their output.\n\nDeleted history cannot be recovered from this API. The deletion preserves newer\ncompletions and in-flight work and does not reset live error-storm protection.\n\n`set_config` is the other consequential call, and it is a revision-checked\npartial patch: `values` carries only the keys to change, the whole result is\nvalidated before the file is written, CLI-overridden keys are stripped, and the\nresponse names the keys that need a restart.\n\nA supplied list or map replaces\nthat whole field, so call `config_get` first for structured keys such as\n`providers` or `model_rules`, and echo the revision it returns.\n\nA failed reload is reported as a save, not as an error. The proxy writes the file\nand only then answers 500 with the reload failure in the body, so that response\nis decoded as the committed document it is: `saved` is `true` and `error` carries\nthe reload message. Reporting it as a tool error would tell a model that a\nmutation that succeeded had failed, and its retry would then fail with 409.\n\n`reload_config` re-reads the configuration file. It is the one state-changing\nroute the dashboard never calls. The operator token itself is process-bound and\nis not re-read.\n\n## Errors\n\nEvery failure is a tool result the model can read and correct, carrying the\nproxy's own `.error` text and the status: `401` (credential wrong or missing),\n`403` (the proxy's operator plane is unarmed, or the request carried only the\ndashboard session cookie), `404`, `409` (overlap or stale\nrevision), `413` (a result limit), and `429` with its `Retry-After`.\n\nAn\nunreachable proxy, a timeout, and a body that is not the expected document are\nreported the same way. The `.error` field is read regardless of `Content-Type`,\nbecause the operator routes are inconsistent and some answer `text/plain` with\na JSON body.\n\nThe returned text is scrubbed of the operator credential first, because a\nreflecting endpoint could otherwise put the `Authorization` value into its own\nfailure message and hand it to the model.\n\nThe scrub removes the literal token,\nany contiguous 8-byte fragment of it (so a credential split across two JSON\nstring fields leaks no usable piece), percent escapes in any hex case\n(including full-byte nested forms), the query `+` form of a space, and\nJSON-escaped forms, including backslash-doubled text and surrogate pairs.\n\nEach\nform is decoded to a fixed point before matching: an encoding is either fully\nseen or the excerpt fails closed. Text that still decodes after three escape\napplications is not published partly decoded: the whole excerpt is replaced by\n`[redacted]` instead.\n\nThat bound applies regardless of whether the credential\nappears in the body: a heavily re-encoded failure with no credential in it\nstill loses its diagnostics, because a credential could be hidden past the\nbound. The scan is bounded to the region that can still reach the excerpt, and\nthe raw bytes it reads are capped; a body whose whitespace collapse does not\nreach the excerpt target inside that cap fails closed to `[redacted]` too, for\nthe same reason.\n\nThe excerpt itself is whitespace-collapsed and truncated to\n4 KiB before the ` [truncated]` marker is appended, so the model-visible text\nruns up to the 12-byte marker past 4 KiB. Redaction runs before the truncation,\nso a credential straddling the boundary cannot survive as a fragment.\n\n## Try it against a disposable instance\n\nRun the endpoint locally against a disposable instance with the repository's\nlifecycle owner, never the main instance on `:8080`, and drive it with one\nstateless POST:\n\n```sh\n(\n  set -e\n  trap 'scripts/dev.sh stop' EXIT\n  export MILLIVOLT_OPERATOR_TOKEN='dev-instance-credential'\n  scripts/dev.sh\n  curl -fsS -X POST http://127.0.0.1:8081/mcp \\\n    -H \"Authorization: Bearer $MILLIVOLT_OPERATOR_TOKEN\" \\\n    -H 'Accept: application/json, text/event-stream' \\\n    -H 'Content-Type: application/json' \\\n    -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"initialize\",\"params\":{\"protocolVersion\":\"2025-06-18\",\"capabilities\":{},\"clientInfo\":{\"name\":\"probe\",\"version\":\"0\"}}}'\n)\n```\n\nThe answer carries the server identity. A full client session is the client\nconfiguration above pointed at `http://127.0.0.1:8081/mcp`; a request without\nthe Bearer credential answers 401 from the operator gate.\n\n## Security\n\nThe endpoint is driven with an operator credential, which is the whole\ndashboard plane: pause, limits, configuration, restart, purge. Treat the client\nconfiguration that carries it as sensitive and keep it out of shared\nrepositories. See [Security](../SECURITY.md).\n\n## Verification\n\nThe unit suite uses a fake proxy that pins the exact method, path, query and\n`Authorization` header of every tool, maps canned responses onto typed output,\nand covers the error shapes, setup validation, truncation markers, the pagination\nrule and the purge guards.\n\n`tests/_go/internal/docs` checks the embedded copy against every source hash.\n`tests/python/site.py` checks the published Markdown twins, `llms.txt`,\n`llms-full.txt` and `docs.json` against the same page model. The paging rule has one owner shared with\n`audit_captures_list`, so the two listings cannot disagree. One of its tests\nruns outside that harness on purpose:\n\n- the redirect test stands up a second listener as the redirect target and\n  asserts it received nothing, so \"we refused the redirect\" is an observation\n  rather than an assertion about an error string.\n- the capture listing test executes the generated `SELECT` against a real\n  SQLite schema with empty, space-padded, tab-padded and NBSP-padded sidecars,\n  and asserts they are excluded while every returned id has an unexpired\n  sidecar and is the exact spelling `audit_capture_get` can fetch.\n\nThis page is mechanically pinned by `tests/python/mcp_docs.py`: the tool table\nmust match the `addTool` registrations, every \"<n> tools\" mention must match\nthat count, every route the client owns must appear in the\n[routes and debugging route table](routes.md#operator-and-data-routes), and this page\nmay name no operator path the client does not own.\n\nThe live integration test starts a private instance through\n[scripts/dev.sh](../scripts/dev.sh) on a port and scratch database of its own, so\nconcurrent runs do not share a port or database, drives the tools through a real MCP session,\nand runs a full capture cycle against neutral loopback traffic:\n\n```sh\nMILLIVOLT_MCP_INTEGRATION=1 scripts/check.sh go test -count=1 ./internal/mcp/...\n```\n\nIt runs in CI as part of the isolated browser-fixtures step, which already has a\ndev instance and an operator token; it is not part of the core source-and-unit\njob, because that job should not have to start a second proxy.\n\nIt drives every registered tool against its own disposable instance.\n\nThe\nstate-changing tools are `set_pause`, `set_throttle`, `resume_quota`,\n`set_config`, `reload_config`, `audit_start`, `audit_stop` and `purge`.\n\nThe\nrun exercises `set_pause` (a hold scoped to the fixture client, resumed at\nonce), `set_throttle` (a limit set and then cleared), `resume_quota`,\n`set_config` and `reload_config` against the scratch config copy, a full\ncapture cycle (`audit_start` and `audit_stop`), and the purge path: the\nmissing confirmation, the wrong phrase, an unauthorized token and a token\nissued for a different filter each refuse with the row count unchanged, and\nthen an authorized purge deletes the fixture rows.\n\nThe read-only tools are\n`describe`, `docs_list`, `docs_search`, `docs_read`, `query`, `explore`,\n`chart`, `records`, `snapshot`, `prometheus`, `audit_status`,\n`audit_captures_list`, `audit_capture_get`, `operator_state`, `config_get`,\n`values` and `purge_preview`; the run drives each of them.\n\nA\nsuccessful purge and the config write are safe here because the instance, its\ndatabase and its config copy all belong to the test and are discarded.\n\nThe same run drives the proxy's own `/mcp` endpoint with a real streamable\nHTTP client: `initialize`, `tools/list` (25 tools), and `describe` and\n`records` returning the same documents the in-process session returns, plus the\nauth boundary (401 without a credential, 401 for a wrong Bearer from the shared\ngate, 403 for a cookie-only request or a wrong Bearer beside an admitted\ncookie) and the reserved `/mcp/` look-alike answering 404, never inference.\n"
    },
    {
      "path": "docs/cli.md",
      "slug": "docs/cli",
      "output": "docs/cli.html",
      "markdown": "docs/cli.md",
      "url": "https://millivolt.llm4people.dev/docs/cli.html",
      "markdown_url": "https://millivolt.llm4people.dev/docs/cli.md",
      "title": "Operator CLI (mvctl)",
      "description": "mvctl is the human command-line client for millivolt's operator plane. It calls the same documented /admin/* and /metrics/* routes as the dashboard and...",
      "group": "Integrate",
      "order": 7,
      "bytes": 14702,
      "sha256": "fb775e63d6b81d6eebb790d903e5c61ea3a62b39880ff4368a81aea96c6174b7",
      "sections": [
        {
          "heading": "Build and run",
          "id": "build-and-run",
          "text": "go run ./cmd/mvctl status --url http://127.0.0.1:8081 go build -o mvctl ./cmd/mvctl ./mvctl --url http://127.0.0.1:8081 status The origin is required: pass --url or set MILLIVOLT_URL . There is no production default, so a command cannot silently address 127.0.0.1:8080 . A trailing slash is normalized away. Only http and https origins are accepted; userinfo, a path, a query and a fragment are rejected.",
          "context": ""
        },
        {
          "heading": "Authentication",
          "id": "authentication",
          "text": "mvctl reads the operator credential from MILLIVOLT_OPERATOR_TOKEN , the one variable the proxy's boot gate reads. It never accepts the token on argv, because a command-line value is visible in ps and shell history. The shared client validates the token's length band before sending a request. export MILLIVOLT_OPERATOR_TOKEN='the-value-the-proxy-started-with' mvctl status Every request presents Authorization: Bearer . No cookie jar is kept: a session cookie minted by one call is deliberately not reused, so a rotated token takes effect on the next command. A missing or wrong credential is reported with the operator gate's own status. A non-loopback origin should use https ; the credential is otherwise sent in cleartext.",
          "context": ""
        },
        {
          "heading": "Output and exit codes",
          "id": "output-and-exit-codes",
          "text": "Human output is the default. --json (or -j ) prints one JSON document, and command output is stable enough for a pipeline. Diagnostics go to stderr as mvctl: ... . After argument parsing, --json turns a command failure into {\"error\": \"...\"} on stdout so a caller can parse one stream. A usage error detected while parsing the arguments still goes to stderr and exits 2, because JSON mode is not established yet; a usage error a command reports after a successful parse follows --json like any other failure. Exit Meaning 0 success, including a preview that made no change 1 transport, HTTP or proxy-reported failure 2 usage error, unknown flag or invalid input 130 interrupted during a request, stream or watch status and overview print an allowlisted state projection with --json : request rows and the full effective config are omitted, so use requests and config get for those. Request rows in that projection would carry previews, response headers and retry metadata that the dedicated commands keep out. ANSI color is off when stdout is not a terminal. --color , --no-color and NO_COLOR override the default. Request labels, model ids, error types and proxy error text are sanitized before a ter",
          "context": ""
        },
        {
          "heading": "Global flags",
          "id": "global-flags",
          "text": "Flag Meaning --url URL proxy origin; required unless MILLIVOLT_URL is set --timeout DURATION bound one request, default the shipped mcp_timeout ; 0 disables the deadline --json , -j emit one JSON document --yes confirm a state-changing command --color / --no-color override terminal color detection --help , -h command or global help --version print the mvctl version and source revision -- ends flag parsing; when no command has been named yet, the next word may still name one. Boolean flags accept --flag , --flag=true , --flag=1 , --flag=yes , --flag=on , and the false spellings false , 0 , no , off .",
          "context": ""
        },
        {
          "heading": "Commands",
          "id": "commands",
          "text": "",
          "context": ""
        },
        {
          "heading": "View",
          "id": "view",
          "text": "Command Purpose mvctl status health, origin, dashboard build and headline metrics mvctl overview KPI, storage, pause, throttle and debug state mvctl requests [N] one page of the request log, default the shipped dash_log_rows ; N must be inside that setting's schema band mvctl query \"SELECT ...\" bounded SQL through /metrics/query mvctl chart server-authoritative time series; --window is all history or whole minutes, --filter scopes it mvctl prometheus the Prometheus text exposition mvctl watch sample live counters and print a sparkline mvctl health check /healthz mvctl url print the normalized origin requests accepts --before-ms MS and --before-id ID together to fetch the next page; the id is an opaque keyset position and may be empty, so it is sent exactly as given. The command prints the next cursor when the page has more rows. Its JSON rows intentionally omit captured content previews, response headers and retry attempts. Use the dashboard capture drawer when full bodies are needed. query accepts --query-timeout DURATION ; the default is the shipped MCP query bound, and an explicit value must be greater than zero. The shared HTTP client carries that shipped bound on its query pat",
          "context": "Commands"
        },
        {
          "heading": "Config",
          "id": "config",
          "text": "Command Purpose mvctl config get [KEY] show one setting or every saved setting mvctl config keys [SUBSTRING] list schema keys mvctl config diff compare saved file values with built-in defaults mvctl config set KEY=VALUE ... [--yes] revision-checked save mvctl config reload [--yes] re-read the config file config set reads GET /admin/config for the current revision and the schema. The schema's kind decides coercion: bool , int , duration , bytes and string take their natural text form; strings , providers , aliases , model_rules , request_overrides and sub_conversations take a JSON value. A numeric-looking string stays a string. An empty value is never a boolean. An unknown key, an empty boolean or an undecodable composite value is a usage error before any write. The server writes the file and then answers 500 when the follow-up reload fails. mvctl treats that committed document as a warning, not a failure, and prints the reload error without inviting a retry that would fail with a stale revision. Credential-class provider header values are redacted from config get , config diff , the config set preview and its post-save document, in human output and --json , using the shared header-",
          "context": "Commands"
        },
        {
          "heading": "Pause",
          "id": "pause",
          "text": "Command Purpose mvctl pause [show] list holds and queued requests mvctl pause on --client X --provider P --yes create a scoped hold mvctl pause on --model M --conversation C --yes narrow a hold to a model or conversation mvctl pause on --new --yes hold clients first seen after the hold mvctl pause on --all --yes hold every client and provider mvctl pause on --id ID [flags] --yes edit one hold in place mvctl pause off --id ID --yes remove one hold mvctl pause off --all --yes remove every hold pause on requires a scope: --client , --provider , --model , --key-hash , --conversation , --new or --all , unless --id names an existing hold to edit. Set dimensions intersect and an unset dimension matches any value, exactly as they do for a limit. --duration and --max-queued are optional. pause off deliberately rejects scope flags: the proxy identifies a hold by id , and a scope-looking command that cleared every hold would be unsafe. Use exactly one of --id or --all . A resume carries only the hold id because the proxy has no scope-selective resume.",
          "context": "Commands"
        },
        {
          "heading": "Throttle and quota",
          "id": "throttle-and-quota",
          "text": "Command Purpose mvctl throttle [show] list provider limits mvctl throttle set --provider P [flags] [--yes] merge limit dimensions mvctl throttle clear --provider P [--yes] drop a provider limit mvctl quota [show] show storm and quota state mvctl quota resume --provider P [--yes] close a retry-mode quota gate throttle set flags are --concurrency , --requests , --request-window , --tokens , --token-window , --anti-burst and --ramp-duration . Windows and ramps take a duration such as 1m . A count needs its window unless the policy already stores one for that dimension, and a count of 0 clears the dimension with its window; a window without a count is refused unless a count is stored. At least one dimension is required. The set and clear commands are provider-only. Scoped selectors and recurring schedules are available through the HTTP API ( /admin/throttle ) and the dashboard console, not through this CLI.",
          "context": "Commands"
        },
        {
          "heading": "Queue and capture",
          "id": "queue-and-capture",
          "text": "Command Purpose mvctl drain --all [--yes] release every parked request mvctl drain --provider P [--yes] release one provider's parked requests mvctl drain --model M [--yes] release one model's parked requests mvctl drain --client C [--yes] release one client's parked requests mvctl debug [show] list capture sessions and their bounds mvctl debug on --client C --yes start a scoped capture mvctl debug off --id ID --yes stop one session mvctl debug off --all --yes stop every session Exactly one drain scope is required. debug on requires a scope unless --id names an existing session to edit, and it has no unrestricted all-traffic form, matching the MCP tool: a bare enable would capture every request body. Captures are sensitive even after header redaction, and a capture create needs durable storage; the proxy answers 503 without it. debug off identifies a session by id or --all , never by a scope flag, and the two are mutually exclusive. debug on refuses a scope name the proxy has not seen, because such a session reports enabled but captures nothing.",
          "context": "Commands"
        },
        {
          "heading": "History, backup and restart",
          "id": "history-backup-and-restart",
          "text": "Command Purpose mvctl purge [filters] [--all] [--yes] count first, then delete mvctl backup --out FILE download an archive mvctl restore --file FILE [--yes] inspect by default, apply with --yes mvctl restart --yes request a graceful restart purge filters are --client , --provider , --model , --conversation-id , --error-type , --status , --before-ms , --after-ms , --has-error and --debug . Every value must parse, and a zero or unparsable numeric filter is a usage error rather than an omitted constraint. --all cannot be combined with a filter. The command always calls /admin/purge/count first and prints the count; only --yes calls /admin/purge , and an unfiltered purge also needs --all . Before deleting, the command re-counts and refuses when the total changed since the preview, then sends that count with the delete so the proxy checks it once more inside the delete transaction. That compares counts, not row identities, so the guarantee is a refused moved population rather than a row-identity binding. A missing, fractional, negative or non-finite count is a failure, never zero. A genuinely bodyless purge is the proxy's delete-everything form. backup --out FILE is required; there is n",
          "context": "Commands"
        },
        {
          "heading": "Scope and non-goals",
          "id": "scope-and-non-goals",
          "text": "mvctl does not install, start, stop or update containers. It does not read or write proxy.yaml directly, does not add a listener, and does not keep a second copy of the proxy's routes, config schema, credential rules or backup grammar. Those facts stay with internal/mcp , internal/config and internal/backup . The command uses only the Go standard library and those repository packages. Because the shared operator client lives in internal/mcp , the resulting binary links the MCP Go SDK and its OAuth2 and jsonschema dependencies. The backup grammar and archive magic live in the dependency-free internal/backup/params leaf, so mvctl does not link SQLite or zstd and never opens a database.",
          "context": ""
        }
      ],
      "markdown_text": "# Operator CLI (mvctl)\n\n`mvctl` is the human command-line client for millivolt's operator plane. It\ncalls the same documented `/admin/*` and `/metrics/*` routes as the dashboard\nand reads them through the shared MCP operator client, so the origin check,\ncredential handling, redirect refusal, response bound and credential redaction\nhave one owner. It adds no server route, no server setting and no second\nlistener.\n\n`mvctl` is a sibling of `cmd/proxy`, `cmd/stress` and `cmd/release`. It is\nsource-only: the container image still ships the proxy, and deployment\nlifecycle stays with Compose.\n\n## Build and run\n\n```sh\ngo run ./cmd/mvctl status --url http://127.0.0.1:8081\ngo build -o mvctl ./cmd/mvctl\n./mvctl --url http://127.0.0.1:8081 status\n```\n\nThe origin is required: pass `--url` or set `MILLIVOLT_URL`. There is no\nproduction default, so a command cannot silently address `127.0.0.1:8080`. A\ntrailing slash is normalized away. Only `http` and `https` origins are\naccepted; userinfo, a path, a query and a fragment are rejected.\n\n## Authentication\n\n`mvctl` reads the operator credential from `MILLIVOLT_OPERATOR_TOKEN`, the one\nvariable the proxy's boot gate reads. It never accepts the token on argv,\nbecause a command-line value is visible in `ps` and shell history. The shared\nclient validates the token's length band before sending a request.\n\n```sh\nexport MILLIVOLT_OPERATOR_TOKEN='the-value-the-proxy-started-with'\nmvctl status\n```\n\nEvery request presents `Authorization: Bearer`. No cookie jar is kept: a\nsession cookie minted by one call is deliberately not reused, so a rotated\ntoken takes effect on the next command. A missing or wrong credential is\nreported with the operator gate's own status. A non-loopback origin should use\n`https`; the credential is otherwise sent in cleartext.\n\n## Output and exit codes\n\nHuman output is the default. `--json` (or `-j`) prints one JSON document, and\ncommand output is stable enough for a pipeline. Diagnostics go to stderr as\n`mvctl: ...`.\n\nAfter argument parsing, `--json` turns a command failure into\n`{\"error\": \"...\"}` on stdout so a caller can parse one stream. A usage error\ndetected while parsing the arguments still goes to stderr and exits 2, because\nJSON mode is not established yet; a usage error a command reports after a\nsuccessful parse follows `--json` like any other failure.\n\n| Exit | Meaning |\n| --- | --- |\n| 0 | success, including a preview that made no change |\n| 1 | transport, HTTP or proxy-reported failure |\n| 2 | usage error, unknown flag or invalid input |\n| 130 | interrupted during a request, stream or watch |\n\n`status` and `overview` print an allowlisted state projection with `--json`:\nrequest rows and the full effective config are omitted, so use `requests` and\n`config get` for those. Request rows in that projection would carry previews,\nresponse headers and retry metadata that the dedicated commands keep out.\n\nANSI color is off when stdout is not a terminal. `--color`, `--no-color` and\n`NO_COLOR` override the default. Request labels, model ids, error types and\nproxy error text are sanitized before a terminal sees them, so a captured value\ncannot inject an escape sequence.\n\n## Global flags\n\n| Flag | Meaning |\n| --- | --- |\n| `--url URL` | proxy origin; required unless `MILLIVOLT_URL` is set |\n| `--timeout DURATION` | bound one request, default the shipped `mcp_timeout`; 0 disables the deadline |\n| `--json`, `-j` | emit one JSON document |\n| `--yes` | confirm a state-changing command |\n| `--color` / `--no-color` | override terminal color detection |\n| `--help`, `-h` | command or global help |\n| `--version` | print the mvctl version and source revision |\n\n`--` ends flag parsing; when no command has been named yet, the next word may\nstill name one. Boolean flags accept `--flag`, `--flag=true`, `--flag=1`,\n`--flag=yes`, `--flag=on`, and the false spellings `false`, `0`, `no`, `off`.\n\n## Commands\n\n### View\n\n| Command | Purpose |\n| --- | --- |\n| `mvctl status` | health, origin, dashboard build and headline metrics |\n| `mvctl overview` | KPI, storage, pause, throttle and debug state |\n| `mvctl requests [N]` | one page of the request log, default the shipped `dash_log_rows`; `N` must be inside that setting's schema band |\n| `mvctl query \"SELECT ...\"` | bounded SQL through `/metrics/query` |\n| `mvctl chart` | server-authoritative time series; `--window` is all history or whole minutes, `--filter` scopes it |\n| `mvctl prometheus` | the Prometheus text exposition |\n| `mvctl watch` | sample live counters and print a sparkline |\n| `mvctl health` | check `/healthz` |\n| `mvctl url` | print the normalized origin |\n\n`requests` accepts `--before-ms MS` and `--before-id ID` together to fetch the\nnext page; the id is an opaque keyset position and may be empty, so it is sent\nexactly as given. The command prints the next cursor when the page has more\nrows. Its\nJSON rows intentionally omit captured content previews, response headers and\nretry attempts. Use the dashboard capture drawer when full bodies are needed.\n\n`query` accepts `--query-timeout DURATION`; the default is the shipped MCP\nquery bound, and an explicit value must be greater than zero. The shared HTTP\nclient carries that shipped bound on its query path too, which is the one\n`chart` takes. The statement must be a single `SELECT` without a semicolon,\nusing the same pre-check as the MCP query tool. The SQL text is sent as one `q`\nparameter and is never logged.\n\n`chart` prints the server-authoritative series: bucket geometry, percentile and\nstat arrays, blended cost per million tokens and the buckets themselves. Its\nfold runs through the client's query path with `--query-timeout` as the one\nbound, so `--timeout` (the generic per-request deadline) never cuts it short.\n\n`--window` takes `all` or a whole number of minutes; `--filter` takes\ncomma-separated `dim:id` pairs using the same dimensions as the log scope\n(`client`, `provider`, `model`, `conversation`, `key`, `status`, `time`, `tool`,\n`error`). `key` is the SHA-256 hash of the client key. A chart fold covers\nfinalized requests only, so a live in-flight status class is refused.\n\n`watch` accepts `--samples N`, bounded by the command's settings surface, and\n`--interval DURATION` (default the shipped `dash_poll_interval`). Interrupting\nany request or stream exits 130.\n\n### Config\n\n| Command | Purpose |\n| --- | --- |\n| `mvctl config get [KEY]` | show one setting or every saved setting |\n| `mvctl config keys [SUBSTRING]` | list schema keys |\n| `mvctl config diff` | compare saved file values with built-in defaults |\n| `mvctl config set KEY=VALUE ... [--yes]` | revision-checked save |\n| `mvctl config reload [--yes]` | re-read the config file |\n\n`config set` reads `GET /admin/config` for the current revision and the schema.\n\nThe schema's `kind` decides coercion: `bool`, `int`, `duration`, `bytes` and\n`string` take their natural text form; `strings`, `providers`, `aliases`,\n`model_rules`, `request_overrides` and `sub_conversations` take a JSON value.\n\nA numeric-looking string stays a string. An empty value is never a boolean. An\nunknown key, an empty boolean or an undecodable composite value is a usage\nerror before any write.\n\nThe server writes the file and then answers 500 when the follow-up reload\nfails. `mvctl` treats that committed document as a warning, not a failure, and\nprints the reload error without inviting a retry that would fail with a stale\nrevision.\n\nCredential-class provider header values are redacted from `config get`, `config\ndiff`, the `config set` preview and its post-save document, in human output and\n`--json`, using the shared header-name vocabulary. `--reveal` prints them. A historical\n`last_reload` error is replaced by the redaction marker because a rejected value\ncan be quoted there. Token counters, token windows and rate-limit values are\nmeasurements, not credentials, and are never redacted.\n\n### Pause\n\n| Command | Purpose |\n| --- | --- |\n| `mvctl pause [show]` | list holds and queued requests |\n| `mvctl pause on --client X --provider P --yes` | create a scoped hold |\n| `mvctl pause on --model M --conversation C --yes` | narrow a hold to a model or conversation |\n| `mvctl pause on --new --yes` | hold clients first seen after the hold |\n| `mvctl pause on --all --yes` | hold every client and provider |\n| `mvctl pause on --id ID [flags] --yes` | edit one hold in place |\n| `mvctl pause off --id ID --yes` | remove one hold |\n| `mvctl pause off --all --yes` | remove every hold |\n\n`pause on` requires a scope: `--client`, `--provider`, `--model`,\n`--key-hash`, `--conversation`, `--new` or `--all`, unless `--id` names an\nexisting hold to edit. Set dimensions intersect and an unset dimension matches\nany value, exactly as they do for a limit. `--duration` and `--max-queued` are\noptional.\n\n`pause off` deliberately rejects scope flags: the proxy identifies a hold by\n`id`, and a scope-looking command that cleared every hold would be unsafe. Use\nexactly one of `--id` or `--all`. A resume carries\nonly the hold id because the proxy has no scope-selective resume.\n\n### Throttle and quota\n\n| Command | Purpose |\n| --- | --- |\n| `mvctl throttle [show]` | list provider limits |\n| `mvctl throttle set --provider P [flags] [--yes]` | merge limit dimensions |\n| `mvctl throttle clear --provider P [--yes]` | drop a provider limit |\n| `mvctl quota [show]` | show storm and quota state |\n| `mvctl quota resume --provider P [--yes]` | close a retry-mode quota gate |\n\n`throttle set` flags are `--concurrency`, `--requests`, `--request-window`,\n`--tokens`, `--token-window`, `--anti-burst` and `--ramp-duration`. Windows and\nramps take a duration such as `1m`.\n\nA count needs its window unless the policy already stores one for that\ndimension, and a count of `0` clears the dimension with its window; a window\nwithout a count is refused unless a count is stored. At least one dimension is\nrequired.\n\nThe set and clear commands are provider-only. Scoped selectors and recurring\nschedules are available through the HTTP API (`/admin/throttle`) and the\ndashboard console, not through this CLI.\n\n### Queue and capture\n\n| Command | Purpose |\n| --- | --- |\n| `mvctl drain --all [--yes]` | release every parked request |\n| `mvctl drain --provider P [--yes]` | release one provider's parked requests |\n| `mvctl drain --model M [--yes]` | release one model's parked requests |\n| `mvctl drain --client C [--yes]` | release one client's parked requests |\n| `mvctl debug [show]` | list capture sessions and their bounds |\n| `mvctl debug on --client C --yes` | start a scoped capture |\n| `mvctl debug off --id ID --yes` | stop one session |\n| `mvctl debug off --all --yes` | stop every session |\n\nExactly one drain scope is required. `debug on` requires a scope unless `--id`\nnames an existing session to edit, and it has no unrestricted all-traffic form,\nmatching the MCP tool: a bare enable would capture every request body.\n\nCaptures are sensitive even after header redaction, and a capture create needs\ndurable storage; the proxy answers 503 without it.\n\n`debug off` identifies a session by `id` or `--all`, never by a scope flag,\nand the two are mutually exclusive. `debug on` refuses a scope name the proxy\nhas not seen, because such a session reports enabled but captures nothing.\n\n### History, backup and restart\n\n| Command | Purpose |\n| --- | --- |\n| `mvctl purge [filters] [--all] [--yes]` | count first, then delete |\n| `mvctl backup --out FILE` | download an archive |\n| `mvctl restore --file FILE [--yes]` | inspect by default, apply with `--yes` |\n| `mvctl restart --yes` | request a graceful restart |\n\n`purge` filters are `--client`, `--provider`, `--model`, `--conversation-id`,\n`--error-type`, `--status`, `--before-ms`, `--after-ms`, `--has-error` and\n`--debug`.\n\nEvery value must parse, and a zero or unparsable numeric filter is a usage\nerror rather than an omitted constraint. `--all` cannot be combined with a\nfilter.\n\nThe command always calls `/admin/purge/count` first and prints the count; only\n`--yes` calls `/admin/purge`, and an unfiltered purge also needs `--all`.\n\nBefore deleting, the command re-counts and refuses when the total changed since\nthe preview, then sends that count with the delete so the proxy checks it once\nmore inside the delete transaction. That compares counts, not row identities,\nso the guarantee is a refused moved population rather than a row-identity\nbinding. A missing, fractional, negative or non-finite count is a failure,\nnever zero. A genuinely bodyless purge is the proxy's delete-everything form.\n\n`backup --out FILE` is required; there is no default path. `--config` and\n`--database` default to true (the command's settings surface) and are always\nsent explicitly, so \"both off\" cannot silently become the server's both-on\ndefault.\n\nThe download streams to a private temporary file, checks the `MVB1` magic,\nsyncs the file, renames, and syncs the directory entry only on success.\nAn existing file is refused unless `--overwrite` is passed. A short HTTP body\nis a failed transfer, not a published archive. Backup and restore are bounded\nby cancellation, not by `--timeout`.\n\n`restore` defaults to `inspect=1`, which validates the archive without applying\nit; `--inspect` forces that mode even with `--yes`. `--yes` applies it.\n\nThe preview decodes and preflights the whole archived database member on the\nserver, so it costs about as much as the apply's decode; `--yes` alone skips\nthe preview and applies directly.\n\nThe member selection (`--config`, `--database`) and the mode (`--config-mode`,\n`--database-mode`; `merge` or `replace`) are always sent explicitly, and both\nthe inspect and apply output name the selected members and modes.\nThe default mode is `replace`, the proxy's documented default, so the preview\nnames the broader action instead of hiding it.\n\nAn inspect document's archived provider headers are redacted; `--reveal`\nprints them. The apply response's `restart_required` keys are called out in the\noutput.\n\n## Scope and non-goals\n\n`mvctl` does not install, start, stop or update containers. It does not read or\nwrite `proxy.yaml` directly, does not add a listener, and does not keep a second\ncopy of the proxy's routes, config schema, credential rules or backup grammar.\n\nThose facts stay with `internal/mcp`, `internal/config` and\n`internal/backup`. The command uses only the Go standard library and those\nrepository packages.\n\nBecause the shared operator client lives in `internal/mcp`, the resulting\nbinary links the MCP Go SDK and its OAuth2 and jsonschema dependencies. The\nbackup grammar and archive magic live in the dependency-free\n`internal/backup/params` leaf, so `mvctl` does not link SQLite or zstd and never\nopens a database.\n"
    },
    {
      "path": "docs/operations.md",
      "slug": "docs/operations",
      "output": "docs/operations.html",
      "markdown": "docs/operations.md",
      "url": "https://millivolt.llm4people.dev/docs/operations.html",
      "markdown_url": "https://millivolt.llm4people.dev/docs/operations.md",
      "title": "Operations",
      "description": "The whole embedded dashboard is protected: every dashboard, /metrics/* , /admin/* and /mcp request requires the MILLIVOLT_OPERATOR_TOKEN credential and is...",
      "group": "Operate",
      "order": 8,
      "bytes": 14681,
      "sha256": "ac3fe53d67faf23c39fd62339d3cb4d1b57806567369861d547d71c49a8bd5f5",
      "sections": [
        {
          "heading": "Overview",
          "id": "overview",
          "text": "This page is the operating overview. It covers health and readiness, durable storage and accounting, the runtime cost model, and the known limits. Each task-shaped page carries the detail. If you want to Start with Change a setting, an override or a provider alias Configuration Install, back up, upgrade or restart the deployment Containers and data Call an operator route, or debug traffic Routes and debugging Protect the listener Security , reverse proxy Measure the deployment Performance and resource usage",
          "context": ""
        },
        {
          "heading": "Health and readiness",
          "id": "health-and-readiness",
          "text": "Liveness ( /healthz ) answers \"the process is up and serving HTTP\". Readiness ( /readyz ) additionally answers \"this instance can persist\": it fails with 503 and a reason when the durable writer is wedged. Two arms answer that: the oldest record on the queue has waited, or no flush has succeeded, for longer than one flush interval plus a progress window. The window is four flush intervals clamped to at least 30 seconds and at most two minutes; the record's own interval is allowed on top, so a record inside its own cadence never convicts and a long configured interval cannot postpone the verdict by more than that one cadence. Every clock starts on arrival: the oldest record on the queue ages the first arm, and while no flush has succeeded since boot the first accepted record ages the second one, so a writer that never picks records up is convicted all the same. Readiness also fails when any durable flush has failed since boot. Readiness stays red after the first failed flush even once writes recover, because a lost batch is worth an operator's attention; restart or investigate. With durable storage disabled both routes answer 200 , since there is no pipeline to wedge. The Compose fi",
          "context": ""
        },
        {
          "heading": "Storage and accounting",
          "id": "storage-and-accounting",
          "text": "SQLite retains finalized records; the ring and pending registry support live observation. Full bootstrap windows are capped in durable mode and older log rows page from storage. Without storage, the ring is the available history. The durable log order owns one secondary index, idx_requests_log(started_at, id) . The log page pushes exact provider, client, key-hash, conversation and canonical numeric status predicates into SQL and rechecks them on that scan; model, status-class, tool, error and time-bucket filters stay Go-owned because they match canonical/derived values, not raw stored text. The export and purge filter surface is different: it accepts exact provider, model, client, conversation, error type, status code, has_error , debug , and time bounds, with no key-hash selector, and its equality-only preview count or purge scans the table instead of maintaining per-dimension composite indexes. BenchmarkStoreDiskBytes measures this on its deterministic synthetic fixture (10,000 and 100,000 seeded records). The current per-record and total bytes are published in storage and retained projection ; that is a reproducible fixture scope, not a prediction of a deployment's disk use or a",
          "context": ""
        },
        {
          "heading": "Performance and footprint",
          "id": "performance-and-footprint",
          "text": "Separate deployment size, cold startup, idle footprint, request overhead and loaded throughput. They answer different questions; a small image is not a RAM limit, and a cached dashboard read is not a cold-start measurement. The runtime contains a stripped Go binary with embedded UI assets, dependency notices and the generated configuration, on a minimal non-root base. There is no frontend build/runtime dependency in deployment. Docker's reported image size describes an image artifact, not compressed network transfer, persistent volume growth or the process's resident memory. On the request path, one bounded body read/metadata decode feeds shared routing and accounting. Upstream connections are pooled; streamed observation and durable enqueue avoid a per-request history scan or synchronous SQLite write. On the dashboard path, the initial HTML embeds bootstrap state and shared analytical projections/cache slots avoid building a separate history copy for each view. These implementation choices reduce repeated work, not every cost of a request. RAM still includes active request/response buffers, connection pools, the live ring and pending state, and the history/cardinality costs docume",
          "context": ""
        },
        {
          "heading": "Known limits",
          "id": "known-limits",
          "text": "Recognized provider fields drive usage/cost; this is not independent billing. Non-streaming usage/cost inspection keeps a bounded prefix, so larger valid responses can forward completely without complete accounting. Optional non-streaming translation reads the complete upstream 200 body and the translated document under the configured translated_response_max_bytes each (default 32 MiB). Exceeding either fails closed with 502 response_too_large before any client bytes; discovery budgets do not bound the path. General multi-line SSE accounting/native event assembly remains incomplete; some split terminal/content shapes can affect classification, not just metrics. SQL result limits do not bound every intermediate SQLite allocation. Automatically grouped sessions are not proof of agent ancestry. Explicit parent declarations and exact-leaf filtering are described in protocol . Existing values lost by older storage formats cannot be reconstructed. Extreme numeric data can produce explicit accounting/encoding errors rather than invented saturated prices or token counts.",
          "context": ""
        }
      ],
      "markdown_text": "# Operations\n\n> [!WARNING]\n> Read the [security boundary](../SECURITY.md) before exposing the listener.\n\nThe whole embedded dashboard is protected: every dashboard, `/metrics/*`,\n`/admin/*` and `/mcp` request requires the `MILLIVOLT_OPERATOR_TOKEN` credential\nand is denied while it is not configured. At the application gate, only the\nunauthenticated `/healthz` liveness and `/readyz` readiness probes, the\n`POST /session` login handshake, origin-root brand/PWA files and transparent\ninference stay open; see the canonical [operator access](routes.md#operator-access)\nlist.\n\n## Overview\n\nThis page is the operating overview. It covers health and readiness, durable\nstorage and accounting, the runtime cost model, and the known limits. Each\ntask-shaped page carries the detail.\n\n| If you want to | Start with |\n| --- | --- |\n| Change a setting, an override or a provider alias | [Configuration](configuration.md) |\n| Install, back up, upgrade or restart the deployment | [Containers and data](containers.md) |\n| Call an operator route, or debug traffic | [Routes and debugging](routes.md) |\n| Protect the listener | [Security](../SECURITY.md), [reverse proxy](reverse-proxy.md) |\n| Measure the deployment | [Performance and resource usage](performance.md) |\n\n## Health and readiness\n\nLiveness (`/healthz`) answers \"the process is up and serving HTTP\". Readiness\n(`/readyz`) additionally answers \"this instance can persist\": it fails with\n`503` and a reason when the durable writer is wedged.\n\nTwo arms answer that: the\noldest record on the queue has waited, or no flush has succeeded, for longer\nthan one flush interval plus a progress window. The window is four flush\nintervals clamped to at least 30 seconds and at most two minutes; the record's\nown interval is allowed on top, so a record inside its own cadence never\nconvicts and a long configured interval cannot postpone the verdict by more\nthan that one cadence.\n\nEvery clock starts on arrival: the oldest record on the\nqueue ages the first arm, and while no flush has succeeded since boot the first\naccepted record ages the second one, so a writer that never picks records up is\nconvicted all the same. Readiness also fails when\nany durable flush has failed since boot.\n\nReadiness stays red after the first failed flush even once writes recover,\nbecause a lost batch is worth an operator's attention; restart or investigate.\nWith durable storage disabled both routes answer `200`, since there is no\npipeline to wedge.\n\nThe Compose files use `-readycheck` as the service healthcheck, so\n`docker compose ps` reports `healthy` only for an instance that can persist.\nPoint an external load balancer or orchestrator at `/readyz` for the same\nsignal; both probe routes are unauthenticated and answer the exact body\n`{\"ok\":true}` on success.\n\nStorage state is also scrapeable at `/metrics/prometheus` (behind the operator\ncredential) as `llm_proxy_storage_enabled`,\n`llm_proxy_storage_queue_depth`, `llm_proxy_storage_queue_capacity`,\n`llm_proxy_storage_dropped_total{cause}` (`overflow`, `after_close`, `panic`,\n`flush_failed`), `llm_proxy_storage_flush_failed_total`,\n`llm_proxy_storage_last_flush_timestamp_seconds` and\n`llm_proxy_storage_wedged`. The block is rendered on every scrape, outside the\nmemoized request aggregate, so queue and drop movement shows up immediately.\nAlert on `llm_proxy_storage_wedged`, on a rising `flush_failed` counter, and on\n`overflow` drops that are not explained by a burst.\n\n## Storage and accounting\n\nSQLite retains finalized records; the ring and pending registry support live\nobservation. Full bootstrap windows are capped in durable mode and older log\nrows page from storage. Without storage, the ring is the available history.\n\nThe durable log order owns one secondary index, `idx_requests_log(started_at,\nid)`. The log page pushes exact provider, client, key-hash, conversation and\ncanonical numeric status predicates into SQL and rechecks them on that scan;\nmodel, status-class, tool, error and time-bucket filters stay Go-owned because\nthey match canonical/derived values, not raw stored text.\n\nThe export and purge\nfilter surface is different: it accepts exact provider, model, client,\nconversation, error type, status code, `has_error`, `debug`, and time bounds,\nwith no key-hash selector, and its equality-only preview count or purge scans\nthe table instead of maintaining per-dimension composite indexes.\n\n`BenchmarkStoreDiskBytes` measures\nthis on its deterministic synthetic fixture (10,000 and 100,000 seeded\nrecords). The current per-record and total bytes are published in\n[storage and retained projection](performance.md#storage-and-retained-projection);\nthat is a reproducible fixture scope, not a prediction of a deployment's disk\nuse or a capacity ceiling.\n\nDropping a superseded request-log index only moves its pages to SQLite's\nfreelist, so the first startup that finds and removes one also runs a one-time\n`VACUUM` after the migration. Fresh and already-migrated databases skip it.\n\nA\n`VACUUM` needs free temporary space up to roughly twice the database size; if\nit fails for space, locking or interruption, startup logs a warning and\ncontinues with every row intact, but the freed pages stay on the freelist.\n\nReclaim them manually during a maintenance window: stop the proxy, run\n`sqlite3 /data/proxy.db 'VACUUM;'` (or any SQLite client) against `db_path`,\nand confirm `PRAGMA freelist_count` returns 0. The automatic pass is never\nretried on a later boot, so a failed attempt needs this manual step.\n\nBoot migrations also own a small set of one-shot data repairs for shapes older\nbinaries could write but current writers never produce: an empty-string JSON\ndocument in `attempts` or `tool_names` is rewritten to the canonical `null`,\nand a positive `ttft_ms` with `final_attempt_at = 0` (the pre-0.3.34\nstart-anchored TTFT, recorded with upload, queueing and retry backoff\nincluded) is reset to 0 because the original per-attempt anchor was never\nstored and cannot be recovered.\n\nEach repair has its own `meta` marker\n(`attempts_repaired`, `tool_names_repaired`, `ttft_anchor_repaired`): the\nmarker is written after a clean probe or after the rewrite, later boots read\none row instead of rescanning the table, and deleting the marker (or restoring\na database that predates it) re-arms the probe.\n\nA repair that cannot run fails\nboot closed instead of serving history its own consumers would reject.\n\nThe\nfirst boot after an upgrade that finds rows to rewrite may pause while it\nscans and rewrites them, and the totals rebuild follows: the rewrite advances\nthe projection epoch, which invalidates the persisted totals document. The\nrewrite can transiently grow the WAL, so keep free space on the database\nvolume as for any other large write.\n\nEnqueue is bounded and nonblocking. Overflow or write failures can lose durable\nrecords even when HTTP succeeds. Bootstrap's\n`storage:{enabled,dropped,totals_degraded}` reports cumulative process-local\nloss and a failed startup history scan. Either appears in the status footer;\ndegraded since-inception totals count only rows committed since process start.\n\nIncreasing queue size absorbs bursts, not arbitrary sustained overload.\nStorage overload remains an unresolved capacity boundary, not a lossless mode.\nMeasure it with the [isolated stress workflow](../CONTRIBUTING.md#performance-evidence):\nsuccessful responses, exact durable accounting and process-local drops are\nseparate acceptance criteria. A short successful burst does not establish\nsustainable writer throughput or an absolute request-capacity ceiling.\n\n`storage_query_timeout` bounds interactive dashboard reads (chart, explorer,\nlog/bootstrap, capture reads) and the ad-hoc query route. A capture read waits\nfirst for the in-flight sidecar save of the same request, bounded by the\ndrawer client's own request context, and only then starts the read budget, so a\nslow save cannot spend the budget the read needs.\n\nStartup projection\npreload, the boot totals rebuild, an administrative purge, and a backup merge's\ntotals scan run under a separate internal ten-minute maintenance budget: they\nlegitimately read or rewrite full history and must not inherit the interactive\nbound.\n\nThe maintenance budget still honors an earlier caller cancellation or deadline,\nand its expiry fails the operation closed (a purge transaction rolls back). It is a\nfixed implementation guardrail, not a configuration field.\n\nOne shared analytical projection retains compact data and sorted metric orders\nproportional to stored history. Initial preload costs startup CPU/RAM; fast\ndashboard reuse is not free startup or bounded total-history memory.\nConcurrent independent proxy writers sharing a database are not a supported\ncoherent-KPI deployment.\n\nExpired debug sidecars are hidden from reads immediately by their TTL. Physical\nreclamation deletes bounded batches per writer tick and continues on a\nnear-term tick, so a large expired set drains without holding the sole writer\nconnection; the sidecar byte cap accounting is updated exactly for the rows\nremoved.\n\nScheduler groups and some observed-identity sets also retain historical labels.\nBounded request queues do not bound all process memory; long-running workloads\nwith many unique identities need their own memory/cardinality measurements.\n\nFrom a source checkout with Python installed, use the existing online backup\ninto a new destination:\n\n```sh\npython3 scripts/backup_db.py proxy.db /path/to/new-backup.db\n```\n\nThe helper opens the source read-only and includes committed WAL state. Do not\nplain-copy an open database or omit its WAL. Protect backups, debug captures and\nexports as sensitive data.\nThis helper backs up the database, not configuration. Operators can also\ndownload a self-checked config and/or database archive from\n[Settings backup and restore](containers.md#settings-backup-and-restore). For image-only\ndeployments and both persistent volumes, use\n[container backup and restore](containers.md#image-only-backup-and-restore).\n\n## Performance and footprint\n\nSeparate deployment size, cold startup, idle footprint, request overhead and\nloaded throughput. They answer different questions; a small image is not a RAM\nlimit, and a cached dashboard read is not a cold-start measurement.\n\nThe runtime contains a stripped Go binary with embedded UI assets, dependency\nnotices and the generated configuration, on a minimal non-root base. There is\nno frontend build/runtime dependency in deployment. Docker's reported image\nsize describes an image artifact, not compressed network transfer, persistent\nvolume growth or the process's resident memory.\n\nOn the request path, one bounded body read/metadata decode feeds shared routing\nand accounting. Upstream connections are pooled; streamed observation and durable\nenqueue avoid a per-request history scan or synchronous SQLite write. On the\ndashboard path, the initial HTML embeds bootstrap state and shared analytical\nprojections/cache slots avoid building a separate history copy for each view.\nThese implementation choices reduce repeated work, not every cost of a request.\n\nRAM still includes active request/response buffers, connection pools, the live\nring and pending state, and the history/cardinality costs documented under\n[storage](#storage-and-accounting). Raising queue/body/pool limits or concurrency\nchanges that footprint. Retained history and observed identities have no universal\nprocess-memory cap; configuration limits must be evaluated together.\n\nThe startup preload decodes every stored row once, so its transient allocations\n(SQL strings, attempts and tool-name JSON) exceed the retained projection several\ntimes over. The process returns those burst pages to the OS immediately after the\npreload completes; idle RSS after readiness reflects retained state, not the\nstartup burst.\n\nThe projection's per-record retained footprint is measured\nreproducibly by `BenchmarkProjectionFootprint` (retained and transient bytes per\nrecord over a seeded scratch database) and `BenchmarkProjectionProcessRSS`\n(process RSS after readiness), without a live instance; the\n[performance workflow](../CONTRIBUTING.md#performance-evidence) owns the commands.\n\n`go_memory_limit` is the operator's steady-state RSS lever: a soft cap on Go\nruntime managed memory (heap, stacks, runtime structures) applied once at\nstartup.\n\nWith the setting at 0, an operator `GOMEMLIMIT` wins and otherwise a\ndetected finite cgroup memory ceiling of at least 80MiB (v2 `memory.max` or v1\n`memory.limit_in_bytes`) becomes a soft limit at 80% of that ceiling so a\ncontainer's own bound actually reaches the Go runtime; smaller ceilings are\nignored and, with no `GOMEMLIMIT`, the runtime stays unbounded.\n\nA set value\noverrides `GOMEMLIMIT`, not `GOGC`, for the process lifetime. `GOGC` remains\nindependent.\n\nThe limit is soft - exceeding it makes the collector\nmore aggressive (capped near 50% of CPU time) instead of failing requests - and\nbounds Go-managed memory only, never SQLite's page cache or OS overhead.\n\nThe [performance and resource usage](performance.md) page is the single source\nfor the current measured tables, hardware, method, reproduce commands and\nlimitations. This section owns the implementation cost model above and the\n`go_memory_limit` behavior. Use the [isolated performance workflow](../CONTRIBUTING.md#performance-evidence)\nwhen adding evidence. Short local-upstream bursts and microbenchmarks are useful\nregressions, not sustained production capacity, provider-latency or lossless\nstorage guarantees.\n\n## Known limits\n\n- Recognized provider fields drive usage/cost; this is not independent billing.\n- Non-streaming usage/cost inspection keeps a bounded prefix, so larger valid\n  responses can forward completely without complete accounting.\n- Optional non-streaming translation reads the complete upstream 200 body and\n  the translated document under the configured `translated_response_max_bytes`\n  each (default 32 MiB). Exceeding either fails closed with 502\n  `response_too_large` before any client bytes; discovery budgets do not\n  bound the path.\n- General multi-line SSE accounting/native event assembly remains incomplete;\n  some split terminal/content shapes can affect classification, not just metrics.\n- SQL result limits do not bound every intermediate SQLite allocation.\n- Automatically grouped sessions are not proof of agent ancestry. Explicit parent\n  declarations and exact-leaf filtering are described in [protocol](protocol.md).\n- Existing values lost by older storage formats cannot be reconstructed.\n- Extreme numeric data can produce explicit accounting/encoding errors rather\n  than invented saturated prices or token counts.\n"
    },
    {
      "path": "docs/configuration.md",
      "slug": "docs/configuration",
      "output": "docs/configuration.html",
      "markdown": "docs/configuration.md",
      "url": "https://millivolt.llm4people.dev/docs/configuration.html",
      "markdown_url": "https://millivolt.llm4people.dev/docs/configuration.md",
      "title": "Configuration",
      "description": "How the configuration surface is owned, found and edited: the generated example, the settings schema, request overrides and sub-conversation tracking.",
      "group": "Operate",
      "order": 9,
      "bytes": 25563,
      "sha256": "286dc2ad828b58cf7bbabdd34caa670c21a7f16d6e654e8c1dd014b62342e960",
      "sections": [
        {
          "heading": "Configuration and CLI",
          "id": "configuration-and-cli",
          "text": "proxy.example.yaml is generated from the canonical config.Example() and schema documentation. Example() starts with neutral config.Default() values and adds the enabled Grok, OpenCode Zen and Cursor compatibility profiles and the opencode sub-conversation tracking exemplar (the promptCacheKey tracked param, strip on). It is not mutable repository state. Source deployments copy it to ignored local proxy.yaml ; images bundle their own copy for fresh config volumes. Do not start Settings against the committed example. The proxy's flags are listed once, with their registration defaults and usage text, in the settings reference . The effective -listen value is validated after every override, and a handoff child rewrites -pid-file with its own pid on boot so a supervisor keeps tracking the live process. The three output-only flags are mutually exclusive and exit without loading local config, opening a database or starting runtime services. Precedence is built-in defaults, then the YAML file, then CLI overrides. A missing file loads defaults; verify the path rather than assuming a typo created a new empty overlay. On startup, unknown keys, unknown nested fields and extra YAML documents ar",
          "context": ""
        },
        {
          "heading": "Finding a setting",
          "id": "finding-a-setting",
          "text": "The generated settings reference is the complete field list: every setting with its type, default, accepted values and hot-reload or restart behavior, grouped by the same categories as the Settings sheet. proxy.example.yaml remains the commented deployment example. GET /admin/config exposes the same field/category metadata alongside saved values, neutral defaults, CLI overrides, the process-effective snapshot and the current revision. Its last_reload section reports the most recent configuration application: ok , error (empty when ok), dropped_keys , restart_required and the unix-millisecond at timestamp. Settings searches labels, keys and help across categories. Durations and byte sizes use a magnitude plus unit ( 2s , 32MiB ) in YAML and Settings; do not write a bare number and assume seconds. A bare integer is still accepted as a count of bytes. Integer counts (retries, percents, tokens) stay unitless numbers with the unit in the schema label when it is not obvious. Settings categories Surface Server, Request, Upstream, Queue & retry, Error storm protection The proxy's traffic surfaces, in that order. Quota pause, Conversations, Format translation Provider reaction, grouping, an",
          "context": "Configuration and CLI"
        },
        {
          "heading": "Guardrails that are not settings",
          "id": "guardrails-that-are-not-settings",
          "text": "Every numeric guard is classified when it is added. A value becomes a setting when an operator can reasonably need a different number for legitimate traffic. It stays an internal constant when changing it independently would break an invariant, encode a protocol maximum, or only tune an internal heuristic. Family Examples Why it stays internal Protocol maxima Chat stop list of 4 The wire defines the practical maximum; a longer list is clamped to it with an approximation warning. Derived frame bounds NativeStreamFrameMax(eventMax) , ResponsesStreamFrameMaxBytes , the proxy's translated frame buffer Computed from the accepted source-event and retained-byte bounds plus the JSON escape expansion. A separate value could under-size a scanner, turning a valid frame into a translation error, or over-size it and defeat the retention bound. Recursion and canonicalization budgets Anthropic nested block depth 16, tool-argument canonical depth 64, separator budget, canonical byte cap They select a safe fallback (the raw-byte fingerprint) or cap decoder recursion. They are algorithm facts, not wire acceptance. Diagnostic echo bounds 128-byte warning echo, 512-byte identity and provider-text rete",
          "context": "Configuration and CLI"
        },
        {
          "heading": "Saving settings safely",
          "id": "saving-settings-safely",
          "text": "Settings collects a draft until Apply. Revert reloads the saved document, and closing a dirty sheet keeps it open until Apply or Revert; an open dirty draft also asks the browser to confirm a tab close or reload. The server validates the whole result and compares its revision before writing. A stale tab receives 409; reload/review its values instead of resubmitting an old full form. The sheet renders closed vocabularies as selects from the schema's choices and checks duration/byte text against the schema's numeric band before the POST; the server remains the authority. With no writable config the field controls are disabled, not only the Apply action. API saves overlay supplied top-level keys on the saved config. Omitted keys remain unchanged, but a supplied map/list replaces that entire field. For example, providers , provider_aliases and model_rules are not recursively patched. Read the current document and preserve wanted entries when editing a structured field. Explicitly empty collections clear those fields. The response separates saved values from the effective snapshot, reports restart-required keys and carries the same last_reload section as GET; the Settings sheet renders ",
          "context": "Configuration and CLI"
        },
        {
          "heading": "Provider aliases and model grouping",
          "id": "provider-aliases-and-model-grouping",
          "text": "provider_aliases merges provider labels in stored history at boot/reload and rekeys new requests. All aliases in one map commit as a single transaction, so a trigger or constraint failure on a later alias leaves every earlier label unchanged. It rejects self-maps and alias chains. This is a durable rename, not a temporary view: removing the alias does not reconstruct original labels. Existing in-memory ring records can retain their previous label until they age out or the process restarts. Back up before an intentional history rename. model_rules instead controls display/grouping. The list is capped at 64 rules. Its ordered exact, pattern and lowercase steps keep stored model spellings unchanged; an empty rule list groups by those raw spellings. The shipped pipeline folds case, strips one or more leading vendor/ namespaces and trailing :tag deployments, strips a trailing run of serving decorations, and unifies . with - between digits. A decoration is what a provider adds around the same weights: Decoration Examples Quantization or serving format -fp4 , -nvfp4 , -bf16 , -int8 , -q4_k_m , -gptq , -awq , -gguf Service tier -fast , -speed , -value , -free Release channel -preview , -la",
          "context": "Configuration and CLI"
        },
        {
          "heading": "Request overrides",
          "id": "request-overrides",
          "text": "request_overrides is an ordered rule list that rewrites the upstream request before relay; the default empty list leaves every request untouched. Each rule has a scope and at least one action: headers sets or replaces upstream headers, remove_headers deletes them, and body sets the output-token ceilings max_tokens / max_completion_tokens (1..1000000) on a Chat Completions or Anthropic client body before translation. A Responses client body is not rewritten by the body action because its cap is max_output_tokens ; header and removal rules still apply. A Chat client whose target is the Responses wire has the rewritten cap translated to max_output_tokens . Both override spellings address an Anthropic body's single max_tokens field, with max_completion_tokens winning when both are set. The list is capped at 64 rules and validated like every other setting: a rule needs at least one scope field and one action, duplicate scope triples are rejected, and one header name cannot be both set and removed in the same rule. Scope matching is exact leaf. A rule applies when every non-empty scope field equals the request's value exactly: client against the classified client label ( X-Proxy-Client w",
          "context": "Configuration and CLI"
        },
        {
          "heading": "Sub-conversation tracking",
          "id": "sub-conversation-tracking",
          "text": "sub_conversations gives requests from one client a conversation identity of their own, taken from a value the client already sends in its request body (exemplar: opencode's promptCacheKey ). The default empty list leaves tracking fully off, and the feature is deny-by-default per client: an entry applies only when its client equals the request's classified client label exactly (the same leaf the request-overrides client scope matches; no wildcard, no case folding), and a request from any other client is never inspected, leaving its bytes and grouping untouched. Each entry lists 1..4 exact JSON field names, matched only at the request body's top level and checked in order; the first present field decides. A present value that is not a JSON string counts as absent and the next field is checked, while a present string that cannot be decoded or fails the identity rules drops the identity for the request - no later field is consulted. A value is kept only when it is non-empty after trimming, valid UTF-8, free of control bytes and at most 512 bytes, the same bound explicit session declarations satisfy. The UTF-8 judgment runs on the value's raw bytes before JSON decoding: the standard dec",
          "context": "Configuration and CLI"
        }
      ],
      "markdown_text": "# Configuration\n\nHow the configuration surface is owned, found and edited: the generated example,\nthe settings schema, request overrides and sub-conversation tracking.\n\n> [!WARNING]\n> `provider_aliases` is a durable history rename, and a `request_overrides`\n> header value is operator-supplied and stamped onto a request whose\n> destination the caller chooses with `X-Proxy-Base-URL`. Back up before an\n> intentional rename, and review both sections before enabling them.\n\n## Configuration and CLI\n\n[proxy.example.yaml](../proxy.example.yaml) is generated from the canonical\n`config.Example()` and schema documentation. `Example()` starts with neutral\n`config.Default()` values and adds the enabled\n[Grok, OpenCode Zen and Cursor compatibility profiles](adapters.md#bundled-compatibility-profiles)\nand the opencode sub-conversation tracking exemplar (the `promptCacheKey`\ntracked param, strip on). It is not mutable repository state. Source\ndeployments copy it to ignored local `proxy.yaml`; images bundle their own copy\nfor fresh config volumes. Do not start Settings against the committed example.\n\nThe proxy's flags are listed once, with their registration defaults and usage\ntext, in the [settings reference](settings.md#proxy-cli-flags). The effective\n`-listen` value is validated after every override, and a handoff child rewrites\n`-pid-file` with its own pid on boot so a supervisor keeps tracking the live\nprocess. The three output-only flags are mutually exclusive and exit without\nloading local config, opening a database or starting runtime services.\n\nPrecedence is built-in defaults, then the YAML file, then CLI overrides.\nA missing file loads defaults; verify the path rather than assuming a typo\ncreated a new empty overlay.\n\nOn startup, unknown keys, unknown nested fields and\nextra YAML documents are dropped and the file is rewritten without them. An\ninvalid recognized value fails startup without rewriting the file, and an\nunparseable file is moved to `PATH.invalid` and replaced with the documented\ndefaults, except an ambiguous duplicate top-level key, which fails closed and\nstays in place.\n\nBecause replacing it with defaults would silently widen the\nbind and drop the origin allowlist, an unparseable file first has `listen` and\n`allowed_base_urls` salvaged from it block by block and applied over the\ndefaults; both `(unparseable yaml)` and `<key> (salvaged)` are reported in the\nboot log and `last_reload`.\n\nA named key with no usable value, or a salvaged\nvalue the config rejects, fails startup with the original file still in place.\nReload rejects an invalid document without rewriting it.\n\nSettings and restore merge treat a missing file as defaults, while\nan invalid or unreadable document fails closed and is reported instead of\nsubstituting a default.\n\nHealthcheck is stricter: a named file that cannot be\nread fails the probe, and only an empty `-config` reaches the built-in\ndefaults. Backup capture is stricter: a missing config file is an\nerror because there is nothing to archive.\n\nSettings POST still rejects invalid\ninputs. CLI-overridden fields cannot be saved from Settings. Healthcheck loads\nwhatever file it is given read-only and never rewrites it.\n\nTo regenerate the public example and the settings reference after changing\ntheir canonical owners:\n\n```sh\ngo run ./cmd/proxy -print-example-config > proxy.example.yaml\ngo run ./cmd/docgen -write\n```\n\nThe shared checks verify generated-file consistency. Built-in defaults remain\nneutral; compatibility-profile values belong only in `config.Example()`, never\nconsumer fallbacks or private credentials. Optional mappings are mechanisms,\nnot provider registrations, for example:\n\n```yaml\nproviders:\n  neutral.example:\n    cost_keys: [billing.charge_usd]\n    usage_keys:\n      input_tokens: prompt_toks\n```\n\nUse the derived provider label as the map key. The example file and Settings\nschema document other maps, model rules and header templates; do not maintain\na second complete list of defaults here.\n\n### Finding a setting\n\nThe generated [settings reference](settings.md) is the complete field list:\nevery setting with its type, default, accepted values and hot-reload or restart\nbehavior, grouped by the same categories as the Settings sheet.\n[proxy.example.yaml](../proxy.example.yaml) remains the commented deployment\nexample.\n\n`GET /admin/config` exposes the same field/category metadata alongside\nsaved values, neutral defaults, CLI overrides, the process-effective snapshot\nand the current revision. Its `last_reload` section reports the most recent\nconfiguration application: `ok`, `error` (empty when ok), `dropped_keys`,\n`restart_required` and the unix-millisecond `at` timestamp.\nSettings searches labels, keys and help across categories.\n\nDurations and byte sizes use a magnitude plus unit (`2s`, `32MiB`) in YAML and\nSettings; do not write a bare number and assume seconds. A bare integer is still\naccepted as a count of bytes. Integer counts (retries, percents, tokens) stay\nunitless numbers with the unit in the schema label when it is not obvious.\n\n| Settings categories | Surface |\n| --- | --- |\n| Server, Request, Upstream, Queue & retry, Error storm protection | The proxy's traffic surfaces, in that order. |\n| Quota pause, Conversations, Format translation | Provider reaction, grouping, and cross-protocol translation. |\n| Storage, Backup, MCP, Dashboard | Durable state, its archives, the LLM tool endpoint and the live view. |\n| Models, Providers, Request overrides | Grouping rules, upstream mappings and scoped rewrites. |\n\nThe category labels, their help and their membership are owned by\n`schema.Categories()` and `Schema()` over `GET /admin/config`; the generated\nexample carries the same sections with each field's type, range and default.\nThe rows above are names only, not a second copy of either.\n\nThe destructive controls sit in their category and each confirms first: a\nrebuild and restart is confirmed and single-flight, starting a capture through\nMCP needs its `confirm` phrase and stopping every session confirms separately,\na database delete confirms in the console (and over MCP needs the exact phrase\nplus the preview token for that filter), and a restore inspects before its\nconfirmed apply.\n\n### Guardrails that are not settings\n\nEvery numeric guard is classified when it is added. A value becomes a setting\nwhen an operator can reasonably need a different number for legitimate traffic.\nIt stays an internal constant when changing it independently would break an\ninvariant, encode a protocol maximum, or only tune an internal heuristic.\n\n| Family | Examples | Why it stays internal |\n| --- | --- | --- |\n| Protocol maxima | Chat `stop` list of 4 | The wire defines the practical maximum; a longer list is clamped to it with an approximation warning. |\n| Derived frame bounds | `NativeStreamFrameMax(eventMax)`, `ResponsesStreamFrameMaxBytes`, the proxy's translated frame buffer | Computed from the accepted source-event and retained-byte bounds plus the JSON escape expansion. A separate value could under-size a scanner, turning a valid frame into a translation error, or over-size it and defeat the retention bound. |\n| Recursion and canonicalization budgets | Anthropic nested block depth 16, tool-argument canonical depth 64, separator budget, canonical byte cap | They select a safe fallback (the raw-byte fingerprint) or cap decoder recursion. They are algorithm facts, not wire acceptance. |\n| Diagnostic echo bounds | 128-byte warning echo, 512-byte identity and provider-text retention, header echo caps | A request-sized diagnostic or identifier must never multiply across a stream or a stored row. Raising them cannot admit a request that is otherwise rejected; it only grows logs and frames. |\n| Record retention | Retained tool names (64), tool-call ids (1024), path/method/model/error caps, capture header caps | They bound the ring, pending snapshots and durable rows. Counts still count past the bound; only identities stop being retained. |\n| Metrics-only truncation | Non-streaming choice cap, SSE analyzer event buffer | The non-streaming choice cap never changes relayed bytes. The SSE analyzer cap can affect classification for events split across that bound, as the protocol limits note; raising it cannot admit a request that is otherwise rejected. |\n| Cursor run and store budgets | Parked run count, per-run pending call/byte caps, blob store caps, aggregate store budget | They bound per-run and process memory for a bridge whose counts come from live tool batches, not operator intent. The per-run and aggregate caps are coupled. |\n| Internal heuristic thresholds | Quality retry spool, error-body capture, discovery output allowance, storage sweep batch sizes, log scan and chart/explorer budgets | They decide whether an internal heuristic runs or how much work one pass may do. Changing them changes diagnostics or performance, not what a client may send or receive. |\n\nThe operator-facing bounds are settings: `request_tool_calls_max`,\n`stream_tool_calls_max`, `translated_response_max_bytes`,\n`models_discovery_max_entries`, `non_stream_capture_max`,\n`stream_terminal_hold_max`, `stream_event_max_bytes`, `token_response_max` and\n`upstream_response_header_max`. `non_stream_capture_max` trades accounting\naccuracy for memory and never changes relayed bytes. A new guard must be\nclassified in this table when it is added, and a guard that becomes\noperator-facing moves to the settings schema instead of keeping a parallel\nconstant.\n\n### Saving settings safely\n\nSettings collects a draft until Apply. Revert reloads the saved document, and\nclosing a dirty sheet keeps it open until Apply or Revert; an open dirty draft\nalso asks the browser to confirm a tab close or reload.\n\nThe server validates the\nwhole result and compares its revision before writing. A stale tab receives 409;\nreload/review its values instead of resubmitting an old full form.\n\nThe sheet\nrenders closed vocabularies as selects from the schema's `choices` and checks\nduration/byte text against the schema's numeric band before the POST; the server\nremains the authority. With no writable config the field controls are disabled,\nnot only the Apply action.\n\nAPI saves overlay supplied top-level keys on the saved config. Omitted keys\nremain unchanged, but a supplied map/list replaces that entire field. For\nexample, `providers`, `provider_aliases` and `model_rules` are not recursively\npatched. Read the current document and preserve wanted entries when editing a\nstructured field. Explicitly empty collections clear those fields.\n\nThe response separates saved values from the effective snapshot, reports\nrestart-required keys and carries the same `last_reload` section as GET; the\nSettings sheet renders it as its last-apply row with apply time, failure,\ndropped-key count and restart notice.\n\nA successful file write can still be\nfollowed by a reload failure; `saved:true` means the file changed even when\nthe response reports an error. Do not assume rollback.\n\nThe `writable`\nindicator means a config path is configured, not that filesystem permissions\nor every future write are guaranteed.\nSee [persistence](containers.md#persistent-state-and-configuration) and\n[reload behavior](containers.md#reload-restart-and-shutdown) before changing startup-bound fields.\n\n### Provider aliases and model grouping\n\n`provider_aliases` merges provider labels in stored history at boot/reload and\nrekeys new requests.\n\nAll aliases in one map commit as a single transaction, so\na trigger or constraint failure on a later alias leaves every earlier label\nunchanged. It rejects self-maps and alias chains.\n\nThis is a durable rename, not\na temporary view: removing the alias does not reconstruct original labels.\nExisting in-memory ring records can retain their previous label until they age\nout or the process restarts. Back up before an intentional history rename.\n\n`model_rules` instead controls display/grouping. The list is capped at 64 rules.\n\nIts ordered exact, pattern and lowercase steps keep stored model spellings\nunchanged; an empty rule list groups by those raw spellings.\n\nThe shipped pipeline folds case, strips one or more leading `vendor/` namespaces\nand trailing `:tag` deployments, strips a trailing run of serving decorations,\nand unifies `.` with `-` between digits.\n\nA decoration is what a provider adds around the same weights:\n\n| Decoration | Examples |\n| --- | --- |\n| Quantization or serving format | `-fp4`, `-nvfp4`, `-bf16`, `-int8`, `-q4_k_m`, `-gptq`, `-awq`, `-gguf` |\n| Service tier | `-fast`, `-speed`, `-value`, `-free` |\n| Release channel | `-preview`, `-latest`, `-beta`, `-alpha`, `-stable`, `-experimental` |\n| Reasoning or effort word | `-thinking`, `-reasoning`, `-xhigh`, `-high`, `-medium`, `-low`, `-minimal` |\n| Build stamp | `-1017`, `-20250929` |\n\nModel tiers, fine-tunes, specifications and parameter counts stay distinct:\n\n- Model tiers: `-flash`, `-pro`, `-mini`, `-ultra`, `-lite`, `-nano`, `-turbo`,\n  `-max`.\n- Fine-tunes: `-abliterated`, `-rl`.\n- Specifications: `-coder`, `-base`, `-chat`, `-it`.\n- Parameter counts.\n\nAdd an exact rule above the shipped pipeline to split a group, or one it cannot\nrecognize to merge the spelling. The Settings editor supports reordering,\nparking and previewing rules.\n\nRaw export/delete predicates do not silently expand to a display group.\nDebug's native-model normalization is separate from these rules.\n\n### Request overrides\n\n`request_overrides` is an ordered rule list that rewrites the upstream request\nbefore relay; the default empty list leaves every request untouched. Each rule\nhas a scope and at least one action: `headers` sets or replaces upstream\nheaders, `remove_headers` deletes them, and `body` sets the output-token\nceilings `max_tokens` / `max_completion_tokens` (1..1000000) on a Chat\nCompletions or Anthropic client body before translation.\n\nA Responses client\nbody is not rewritten by the body action because its cap is\n`max_output_tokens`; header and removal rules still apply. A Chat client whose\ntarget is the Responses wire has the rewritten cap translated to\n`max_output_tokens`. Both override spellings address an Anthropic body's single\n`max_tokens` field, with `max_completion_tokens` winning when both are set.\n\nThe\nlist is capped at 64 rules and validated like every\nother setting: a rule needs at least one scope field and one action, duplicate\nscope triples are rejected, and one header name cannot be both set and removed\nin the same rule.\n\nScope matching is exact leaf. A rule applies when every non-empty scope field\nequals the request's value exactly:\n\n- `client` against the classified client label (`X-Proxy-Client` when sent,\n  except a label that only repeats the user agent's product name, which records\n  the fuller user-agent identity; otherwise inferred from SDK/user-agent\n  metadata).\n- `provider` against the canonical label after `provider_aliases`.\n- `model` against the recorded model id (for Cursor requests the base id the\n  dashboard records, not the fused spelling).\n\nAn empty scope field matches anything. There is no model-rule canonicalization,\nregex or wildcard broadening. All matching rules apply in list order, and for\nthe same header or body field the later rule wins.\n\nThe client label is a claim, not an authenticated identity. The caller chooses\nit, and the proxy never verifies it, so a request presenting another client's\nlabel is treated as that client here and by every other client-scoped feature\n(sub-conversations, Debug sessions, pause holds, the Cursor parked-run scope).\n\nSee [client identity](../SECURITY.md#client-identity-is-a-claim-not-an-authentication)\nfor what that means for a listener reachable by parties you do not trust. What\nit cannot do is move a credential: credential-class header names are refused at\nload and skipped at send, so the exposure is the policy attached to the label,\nnot the secret behind it.\n\nHeader rules are the operator's last word on the upstream wire: the resolved\nmerge applies after client-forwarded values, configured provider headers and\nthe client's `X-Proxy-Headers` map, so a matching override wins over all of\nthem.\n\nOnly the proxy-owned transport-mode names `accept-encoding` and `range`\nare stripped from the final upstream request before send, whichever source set\nthem, so the transport keeps its own gzip negotiation and never sends a partial\nrange; the client header maps (`X-Proxy-Headers` and an\n`X-Proxy-Auth-Header` naming one) also reject them with a 400 before any send.\n\nThe request-override list refuses two further header classes at load. Protocol\nand framing names (`host`, `content-type`,\n`content-length`, `transfer-encoding`, `te`, `connection`, `keep-alive`,\n`proxy-authenticate`, `proxy-connection`, `trailer`, `upgrade`) and the whole\n`x-proxy-` control prefix belong to the proxy and the transport.\n\nCredential\nnames belong to whoever issued the secret: `authorization`, `cookie`,\n`proxy-authorization`, and every name the shared credential vocabulary\nclassifies. That vocabulary judges the header's *role*, not a list of vendor\nspellings: `auth`/`authorization`, `api-key`, `secret`, `password`,\n`credential`, `bearer`, `jwt`, `signature`, `cookie`, `key` and `token` are all\ncredential-class wherever they appear, so `x-auth-key`, `x-amz-credential`,\n`x-functions-key` and `x-subscription-key` are refused along with `x-api-key`.\n\nNames that mention a key or a token but carry an identifier or a measurement\nstay admitted: `x-key-id`, `idempotency-key`, `cache-key`, `x-prompt-tokens`,\n`x-token-count`, and the `x-ratelimit-*` and `anthropic-ratelimit-*` families.\n\nThat breadth is deliberate. An override\nvalue is operator-supplied and is stamped onto a request whose destination the\ncaller chooses with `X-Proxy-Base-URL`, so a secret in any unclassified header\nname would be delivered to that caller's host; vendor spellings cannot be\nenumerated in advance, which is why the check keys on role rather than a list.\n\nThe same vocabulary drives capture and debug\nredaction, so a stored capture never keeps a header the wire carried. At\nruntime the target's configured auth header is skipped as well, so a rule that\npredates this check, or a future grammar slip, still cannot move a credential.\n\nThe client header maps reject `content-length` before any send so the transport\nkeeps ownership of message framing. Header\nnames are trimmed and canonicalized\ncase-insensitively, and values must be non-empty single-line header values.\n\nProvider `headers` refuse neither class above. They are applied after the\nextracted credential is placed, so a credential name (including the target's\nown auth header) or an `x-proxy-` name is legal there and takes effect over the\nforwarded and extracted value. Configured provider values are still stripped\nfor `accept-encoding` and `range` at the final request, exactly like override\nvalues.\n\nThe body rewrite is fail closed. It applies to Chat Completions or Anthropic\nclient bodies before translation, whatever the target (a Responses client body\nis not rewritten); when the body is not a JSON object, or the rewritten\nresult would exceed `max_request_bytes`, nothing is written: the original\nbytes are used unchanged by the rewrite stage and are still translated when\ntranslation is active, with one process log line recording the reason. Only a\npassthrough relays them verbatim.\n\nA successful rewrite replaces the body for\nthe request's whole life, so every relay attempt, absorbed retry and quality\nre-send reuses it, and the recorded request cap is re-stamped from the\neffective body.\n\nA rule sets only the body\nfields it names, and the re-read pair keeps the wire's documented precedence -\n`max_completion_tokens` wins over `max_tokens` - so a rule setting only\n`max_tokens` cannot raise a request whose client already sent\n`max_completion_tokens`: set both fields to the same value to override either\nspelling.\n\nCursor targets carry no\ntoken ceilings on their wire, so the body section is skipped for them while\nheader rules still apply at the native send.\n\nOverrides apply to inference sends only, never model discovery or token\nrefresh. The list hot-reloads: changed rules apply to new requests. The\nSettings editor mirrors the server's checks and rejections live for each\nrule, marks empty scope fields as matching any request, and blocks Apply\non the first invalid rule.\n\nTo raise the output budget for one provider, either write:\n\n```yaml\nrequest_overrides:\n  - provider: nano-gpt.com\n    body:\n      max_completion_tokens: 65536\n```\n\nor open Settings, select **Request overrides**, pick **raise the output budget\nfor a provider** from the add-a-rule menu, and fill the provider scope; the\nother starter templates seed an empty rule and an upstream header for a\nclient.\n\n### Sub-conversation tracking\n\n`sub_conversations` gives requests from one client a conversation identity of\ntheir own, taken from a value the client already sends in its request body\n(exemplar: opencode's `promptCacheKey`).\n\nThe default empty list leaves tracking\nfully off, and the feature is deny-by-default per client: an entry applies only\nwhen its `client` equals the request's classified client label exactly (the same\nleaf the request-overrides `client` scope matches; no wildcard, no case\nfolding), and a request from any other client is never inspected, leaving its\nbytes and grouping untouched.\n\nEach entry lists 1..4 exact JSON field names, matched only at the request\nbody's top level and checked in order; the first present field decides. A\npresent value that is not a JSON string counts as absent and the next field is\nchecked, while a present string that cannot be decoded or fails the identity\nrules drops the identity for the request - no later field is consulted.\n\nA value is kept only when it is non-empty after trimming, valid UTF-8, free of\ncontrol bytes and at most 512 bytes, the same bound explicit session\ndeclarations satisfy.\n\nThe UTF-8 judgment runs on the value's raw bytes\nbefore JSON decoding: the standard decoder coerces invalid UTF-8 inside\nstrings to U+FFFD, so a raw invalid-UTF-8 sequence drops the identity while\nan escaped lone surrogate, whose bytes are ASCII, is kept and decodes to\nU+FFFD.\n\nThe drop is conservative: the value's raw spelling is\nscanned inside a bounded window, so a value whose raw span exceeds the window\n(escape sequences spend more raw bytes than they decode to, and trimmable\nedges count before trimming) is dropped even when its trimmed form would\npass.\n\nAn absent or dropped identity is never a client error: on the\npassthrough wire the body is payload, and the request keeps automatic\ngrouping. A translated target still requires the whole request body to be\nvalid UTF-8, as [protocol](protocol.md#relay-retries-and-model-discovery)\ndescribes.\n\nThe kept value groups the request under a `k:` conversation identity.\nPrecedence is the explicit `X-Proxy-Session` header first, then the tracked\nvalue, then automatic client+key grouping; a request carrying both header and\ntracked value keeps the header identity.\n\n`X-Proxy-Parent-Session` still owns\nparent linkage, and declaring a parent still requires the explicit session\npair, so a tracked identity never carries a parent. In the dashboard a `k:` id\nis an ordinary conversation id: lineage, filters, saved views and the request\ndrawer read it like any other.\n\n`strip: true` removes every configured field of the entry that is present at\nthe body's top level from the client body before relay or translation,\nincluding a Responses client body; the default `false` forwards them\nunchanged. Unlike the [request overrides](#request-overrides) body fields,\nstrip is not limited to Chat Completions or Anthropic inbound.\n\nThe removal\nrides the same body-rewrite engine: one document decode when both features\nmatch one request, the original bytes used unchanged by the rewrite stage when\nthe body is not a JSON object or the rewrite would exceed\n`max_request_bytes`, and cursor targets skipping the body section.\n\nWithout\n`strip`, the client's spelling reaches the upstream wire on a same-protocol\npassthrough; a translated body carries the value in `prompt_cache_key` or drops\nit.\n\nWhen a tracked value was extracted and the request translates to the Anthropic\nwire, the translated body gains a top-level `prompt_cache_key` carrying the\nvalue. This is a proxy tracking extension, not an Anthropic cache field:\nAnthropic caching uses `cache_control`, and an upstream that rejects unknown\ntop-level fields will reject the injected request. Injection follows extraction\nalone: `strip` governs the tracked client-body fields, never the injected\nfield.\n\nValidation runs at the load boundary for YAML and Settings saves alike: at most\n16 entries, at most 4 params per entry, param names one JSON key segment each\n(trimmed, non-empty, at most 64 bytes, printable ASCII, no quote, backslash or\ncontrol bytes), and duplicate clients or duplicate params within one entry are\nrejected. The list hot-reloads: changed entries apply to new requests.\n\nThe Settings editor lives in the Conversations category and mirrors every check\nlive per entry card: classified-client autocomplete from observed clients,\nordered param rows with add/remove gated at the caps, the strip toggle, a count\nline against the entry cap, the server's exact rejection wording, and an Apply\nblocked on the first invalid card. To track opencode's prompt cache key and\nstrip it from the upstream body, write:\n\n```yaml\nsub_conversations:\n  - client: \"opencode\"\n    params:\n      - \"promptCacheKey\"\n    strip: true\n```\n"
    },
    {
      "path": "docs/settings.md",
      "slug": "docs/settings",
      "output": "docs/settings.html",
      "markdown": "docs/settings.md",
      "url": "https://millivolt.llm4people.dev/docs/settings.html",
      "markdown_url": "https://millivolt.llm4people.dev/docs/settings.md",
      "title": "Settings reference",
      "description": "Settings and the proxy CLI write the same fields. The dashboard Settings sheet saves them through GET and POST /admin/config , the YAML file holds them at...",
      "group": "Operate",
      "order": 10,
      "bytes": 48356,
      "sha256": "f48c76a99125927161ccad0aa9d39e98155bf7ec5f3748f25330feccf6122a28",
      "sections": [
        {
          "heading": "Server",
          "id": "server",
          "text": "Bind address, database, and ring depth restart to apply. shutdown_timeout applies at the next SIGINT/SIGTERM. listen ¶ Listen address · string Default \":8080\" · Accepted - · Restart required Host:port the HTTP server binds. Restart required. db_path ¶ Database path · string Default \"proxy.db\" · Accepted - · Restart required SQLite metrics store. Empty disables durability (ring only). Restart required. history_size ¶ History size · int Default 10000 · Accepted 1..1000000 · Restart required In-memory ring depth and startup backfill count. Durable history and paged request logs can extend beyond this window. Restart required. shutdown_timeout ¶ Shutdown timeout · duration Default 5s · Accepted > 0s · Hot-reloads HTTP shutdown wait after active request contexts are canceled on SIGINT/SIGTERM. Storage draining follows separately. Must be > 0; applies at the next shutdown without restarting the listener. restart_drain_timeout ¶ Restart drain timeout · duration Default 10m · Accepted >= 0s (0s = wait indefinitely) · Hot-reloads How long a dashboard-triggered restart waits for in-flight streams. Expiry aborts the restart and resumes accepting traffic; unfinished streams are not killed. New",
          "context": ""
        },
        {
          "heading": "Request",
          "id": "request",
          "text": "Inbound body cap, tool-call history bound, SSRF allowlist, optional body-preview, token-refresh response cap, and debug-capture retention. max_request_bytes ¶ Max request bytes · bytes Default 32MiB · Accepted 1KiB..1GiB · Hot-reloads Inbound body the proxy will buffer to read routing metadata. Larger bodies are rejected with 413. request_tool_calls_max ¶ Max request tool calls · int Default 1024 · Accepted 1..10000 · Hot-reloads Most Chat tool calls across the whole message history of one inbound request, including the deprecated per-message function_call shape. Anthropic tool_use and Responses function_call history are bounded by their protocol collection limits instead. Real agent turns replay a handful; raise it only for clients that resend unusually long tool loops, because every call is materialized in memory during translation. allowed_base_urls ¶ Allowed base URLs · strings Default [] · Accepted - · Hot-reloads SSRF allowlist of upstream base URLs. Empty allows any target (single trusted operator). An entry admits only the same scheme, host and port once the scheme's default port is filled in, plus that entry's path and its children, so a port-less entry does not admit othe",
          "context": ""
        },
        {
          "heading": "Upstream",
          "id": "upstream",
          "text": "Connection pool, header timeout, stream keepalives, model-discovery budgets and response-buffer bounds. upstream_timeout ¶ Upstream header timeout · duration Default 5m · Accepted >= 0s (0s = no header cap) · Hot-reloads How long to wait for upstream response headers. Streaming bodies are not subject to this. Transient header timeouts are retried. upstream_dial_timeout ¶ Upstream dial timeout · duration Default 30s · Accepted > 0s · Hot-reloads How long establishing a new upstream connection may take. Applies to new connections after reload; in-flight streams keep their transport. upstream_dial_keepalive ¶ Upstream dial keepalive · duration Default 30s · Accepted > 0s · Hot-reloads TCP keepalive interval for upstream connections. Applies to new connections after reload. upstream_tls_handshake_timeout ¶ Upstream TLS handshake timeout · duration Default 10s · Accepted > 0s · Hot-reloads How long the TLS handshake with an upstream may take. Applies to new connections after reload. models_discovery_timeout ¶ Model discovery timeout · duration Default 30s · Accepted 1s..5m · Hot-reloads One upstream metadata budget for transparent key refresh, all model pages and optional enrichment. Ne",
          "context": ""
        },
        {
          "heading": "Queue & retry",
          "id": "queue--retry",
          "text": "Per-key concurrency, transparent 429/5xx retry and error classification, client error-class disclosure, and quality re-asks. max_concurrent ¶ Max concurrent · int Default 0 · Accepted >= 0 (0 = unlimited) · Hot-reloads In-flight sends per provider+key. 0 is unlimited. max_queue_size ¶ Max queue size · int Default 1024 · Accepted >= 0 (0 = unlimited) · Hot-reloads Queued waiters per group. 0 is unlimited. It also feeds the default queue cap of a new pause hold. max_inflight_requests ¶ Max in-flight requests · int Default 10000 · Accepted 0..1000000 · Hot-reloads Process-wide inference admission bound. Requests above it are refused with 503 and Retry-After instead of buffering their bodies. 0 = unlimited. Hot-reloads. max_inflight_body_bytes ¶ Max in-flight body bytes · bytes Default 256MiB · Accepted 1MiB..64GiB (0B = unlimited) · Hot-reloads Process-wide budget for buffered inbound request bodies. Admission charges the bytes actually read and refuses with 503 when the next read would exceed the budget. A declared Content-Length reserves nothing, so an idle connection cannot hold the budget. Bytes past max_request_bytes are neither charged nor retained: that body is answered 413 by ",
          "context": ""
        },
        {
          "heading": "Error storm protection",
          "id": "error-storm-protection",
          "text": "Bounded recovery queues for affected providers or exact model names. Hot-reloads; policy changes clear observations and wake waiters. Banner visibility changes do not reset protection. storm_enabled ¶ Enable protection · bool Default false · Accepted - · Hot-reloads Detect elevated upstream failure rates and queue affected sends for bounded recovery probes. Opt-in; requests can still fail on cancellation, exhausted retry budgets, queue limits or permanent errors. Retries can repeat upstream execution and billing. storm_provider_enabled ¶ Provider protection · bool Default true · Accepted - · Hot-reloads Gate every model on a provider only when all active models individually meet the sample and failure thresholds. Active means a request in the same detection window; idle models expire. storm_model_enabled ¶ Model protection · bool Default true · Accepted - · Hot-reloads Gate an affected exact recorded model name within its provider. Dashboard model grouping does not broaden this scope. storm_banner_enabled ¶ Show incident banner · bool Default true · Accepted - · Hot-reloads Show affected providers/models, safe error categories, failure percentages, queue state and recovery timing a",
          "context": ""
        },
        {
          "heading": "Quota pause",
          "id": "quota-pause",
          "text": "Provider-wide reaction to a 429 carrying a durable quota/billing error (insufficient_quota/credits, spend limits): surface it immediately, park the provider behind a recovery gate, or hold it until an operator resumes. OpenAI-compatible wire only; Anthropic and Cursor upstreams keep the off behavior. quota_error_classes ¶ Quota error classes · strings Default [] · Accepted - · Hot-reloads Operator extensions to the built-in durable quota/billing vocabulary (insufficient_quota/credits, spend and hard limits, and the numeric business codes of some gateways). A matching type or code string (case-insensitive) is a durable account condition: the ordinary retry ladder never absorbs it, quota_pause_mode owns the reaction, and it counts as an error rather than flow control. Entries add to the built-ins and never move one; a spelling already built into another class is rejected at load. Reload applies to new classifications and re-reads stored history through the same vocabulary. quota_pause_mode ¶ Mode · string Default \"off\" · Accepted off , retry , manual · Hot-reloads Reaction to a 429 carrying a durable quota/billing error (insufficient_quota/credits, spend limits; in-band occurrences i",
          "context": ""
        },
        {
          "heading": "Conversations",
          "id": "conversations",
          "text": "How the request log groups turns into conversations. conversation_idle_gap ¶ Idle gap · duration Default 30m · Accepted > 0s · Hot-reloads A gap longer than this starts a new conversation for the same client+key. Generous so thinking pauses inside one task don't split it. Must be > 0. conversation_max_open ¶ Max open · int Default 64 · Accepted 1..100000 · Hot-reloads Cap on concurrently-open conversations per client+key. Oldest is evicted past it. sub_conversations ¶ Sub-conversation tracking · sub_conversations Default [] · Accepted - · Hot-reloads Per-client tracking of a request body field that carries a sub-conversation identity, exemplified by opencode's promptCacheKey. Each entry names one classified client exactly (no wildcard, no case folding) plus 1..4 exact JSON field names matched only at the request body's top level; the first present field decides (a duplicate top-level key drops the identity): a present value that is not a JSON string value counts as absent and the next field is checked, while a present string that cannot be decoded or fails the identity rules (non-empty after trimming, valid UTF-8, free of control bytes, at most 512 bytes) drops the identity for the",
          "context": ""
        },
        {
          "heading": "Format translation",
          "id": "format-translation",
          "text": "Cross-protocol translation policy, streamed tool-call bound, Anthropic defaults and Cursor agent.v1 bridging. anthropic_default_max_tokens ¶ Anthropic default max tokens · int (tokens) Default 4096 · Accepted 1..1000000 · Hot-reloads Injected into translated Anthropic requests when the client sent none of max_tokens, max_completion_tokens or max_output_tokens. stream_tool_calls_max ¶ Max streamed tool calls · int Default 1024 · Accepted 1..10000 · Hot-reloads Most tool calls one translated response stream may carry: concurrent open blocks for Anthropic and Responses, distinct calls for Chat (its stream has no per-call close event). A stream past the bound ends with a translation_error. Raise it only for providers that emit unusually large parallel tool batches. translation_loss ¶ Translation loss policy · string Default \"warn\" · Accepted warn , reject · Hot-reloads What a cross-protocol translation does when the target cannot represent a client field. warn (default) drops optional fields and reports them in X-Proxy-Warnings; reject fails the request with 400 naming the fields before any upstream send and refuses every recorded loss, including a documented approximation. Structural ",
          "context": ""
        },
        {
          "heading": "Storage",
          "id": "storage",
          "text": "Durable SQLite write pipeline. Restart to apply. storage_write_chan_cap ¶ Write channel cap · int Default 8192 · Accepted 1..1000000 · Restart required Buffered records before overflow drops. Restart required. storage_batch_cap ¶ Batch cap · int Default 256 · Accepted >= 1 · Restart required Max records per SQLite transaction. Cannot exceed the write channel cap. Restart required. storage_flush_interval ¶ Flush interval · duration Default 500ms · Accepted > 0s · Restart required Partial-batch flush cadence. Must be > 0 (a zero ticker panics). Readiness convicts a wedged writer after one interval plus a progress window of four intervals clamped to 30s..2m. Restart required. storage_query_timeout ¶ Query timeout · duration Default 10s · Accepted > 0s · Restart required Bounds dashboard SELECT queries. Must be > 0. Open and AggAPI bind at start (restart required); pause/throttle persist reads the live snapshot. storage_query_max_bytes ¶ Query result bytes · bytes Default 8MiB · Accepted 4KiB..64MiB · Restart required Maximum JSON bytes returned by /metrics/query; also bounds SQLite string/blob values. Oversized results fail with HTTP 413, never truncate. Does not cap all SQLite workin",
          "context": ""
        },
        {
          "heading": "Backup",
          "id": "backup",
          "text": "Download or restore a self-checked archive of the saved config, the SQLite history, or both. Restore inspects first and the apply is confirmed. Merge keeps live defaults and live request ids; replace loads and validates the backup, writes canonical YAML, and preserves CLI-overridden listen and db_path. backup_max_bytes ¶ Backup size cap · bytes Default 1GiB · Accepted 1MiB..4GiB · Hot-reloads Maximum size of one Settings backup download or restore upload. Larger archives are refused. Downloads and restores stream through private staging files; this is the admit/reject ceiling, not a heap guarantee.",
          "context": ""
        },
        {
          "heading": "MCP",
          "id": "mcp",
          "text": "The operator-gated /mcp LLM tool endpoint: mcp_enabled registers the route or keeps it reserved (404, never inference), and the limits bound what its tools return to a model. Restart to apply; the route table and the endpoint's services are built once at boot. mcp_enabled ¶ Enable MCP endpoint · bool Default true · Accepted - · Restart required Register the streamable HTTP MCP endpoint at /mcp for LLM tool clients, operator-gated like /metrics and Bearer-only: a session cookie alone is refused. Off keeps the route reserved (404, never inference); the /mcp/ look-alike reservation and the operator gate stay either way. Restart required. mcp_page_size ¶ Page size · int Default 50 · Accepted 10..500 · Restart required Default page for the records, values and audit capture listings the endpoint serves to a model. Restart required. mcp_query_max_rows ¶ Query result rows · int Default 200 · Accepted 1..100000 · Restart required Default client-side row limit when a query call omits max_rows. An explicit max_rows may raise it up to this setting's maximum; the proxy's own storage_query_max_rows still answers 413 first. Restart required. mcp_query_max_bytes ¶ Query result bytes · bytes Defaul",
          "context": ""
        },
        {
          "heading": "Dashboard",
          "id": "dashboard",
          "text": "Live-view cadence and request-log window. Hot-reloads; open dashboards pick up the next tick. dash_log_rows ¶ Request log rows · int Default 60 · Accepted 10..500 · Hot-reloads Page size of the live request log (newest first). Scrolling near the bottom loads more, including older durable history. dash_poll_interval ¶ Poll interval · duration Default 5s · Accepted > 0s · Hot-reloads KPI / pause / SSE-fallback poll cadence. Must be > 0. dash_chart_refresh ¶ Chart refresh · duration Default 15s · Accepted > 0s · Hot-reloads How often the traffic chart re-fetches server-authoritative buckets and period totals. Must be > 0. dash_explorer_stale ¶ Explorer stale after · duration Default 15s · Accepted > 0s · Hot-reloads How old a cached explorer breakdown may be before it is re-fetched. Must be > 0. dash_background_refresh ¶ Background refresh · bool Default false · Accepted - · Hot-reloads Keep the dashboard current while its tab is hidden: the poll runs at the browser's throttled background cadence (about one wake per minute on Chromium) and a Web Lock keeps the SSE feed from being frozen. Desktop Chromium only; Android and iOS still suspend background pages at the OS level. Off keeps t",
          "context": ""
        },
        {
          "heading": "Models",
          "id": "models",
          "text": "Model grouping rules - an ordered rewrite pipeline merging spelling variants of the same model in every grouped surface. Records keep their exact spelling; hot-reloads. model_rules ¶ Model grouping rules · model_rules Default: - {mode: lower, from: \"\", to: \"\"} - {mode: pattern, from: \"^(?:[a-z0-9][a-z0-9._-]*/)+\", to: \"\"} - {mode: pattern, from: \"(?::[a-z0-9._-]+)+$\", to: \"\"} - {mode: pattern, from: \"(?:-(?:[a-z]{0,2}fp\\\\d+|bf\\\\d+|int\\\\d+|nf\\\\d+|[a-z]?q\\\\d+(?:_[0-9a-z]+)*|gptq|awq|gguf|exl2|mlx|onnx|ggml|fast|speed|value|free|preview|latest|beta|alpha|stable|experimental|thinking|reasoning|xhigh|high|medium|low|minimal|(?:\\\\d{4}|\\\\d{8})))+$\", to: \"\"} - {mode: pattern, from: \"(\\\\d)\\\\.(\\\\d)\", to: \"$1-$2\"} Accepted - · Hot-reloads Capped at 64 rules. Ordered rewrite pipeline that merges spelling variants of the same model in every grouped surface (explorer model dimension, scope filters, debug checklist, the Logs download and Settings delete-filter model optgroups, and the request-log leaf’s displayed name). Each rule is one step: exact (whole-string merge old → new), pattern (regex rewrite of all occurrences, $1 capture refs), lower (fold case). Rules apply once in order; the shipped",
          "context": ""
        },
        {
          "heading": "Providers",
          "id": "providers",
          "text": "Optional per-provider JSON field-name maps: usage/cost response keys, the models metadata endpoint merged into /v1/models, ensured tool names injected into relayed chat bodies, and optional upstream wire headers. Empty = auto-detect. providers ¶ Provider field maps · providers Default {} · Accepted - · Hot-reloads Per-provider cost/usage JSON field paths, optional models_path/models_keys enrichment, ensured tool names and headers (a string map). Field names only, never static prices. Custom cost_keys must report USD; leave cost_in_usd_ticks to automatic unit conversion. ensure_tools names function tools injected as inert stubs into relayed Chat Completions client bodies on a Chat outbound wire missing them. When the client sent no tools of its own, an absent, null, or auto tool_choice is forced to none; an explicit none stays; a required, named, or malformed choice skips injection entirely. A first-party client's tool-signature gate still recognizes the request. Header values expand {{uuid4}} to a fresh UUID, {{platform}} to the server's Rust-style os; arch pair, and {{opencode-msg-id}}/{{opencode-ses-id}} to fresh opencode-format identifiers; unknown templates stay literal. On HTT",
          "context": ""
        },
        {
          "heading": "Request overrides",
          "id": "request-overrides",
          "text": "Scoped rewrites of the upstream request: set, replace or remove HTTP headers and set output-token ceilings per client, provider and/or model. Rules match exactly, all matching rules apply in list order, and the later rule wins. Default: an empty list, the feature fully off. request_overrides ¶ Request override rules · request_overrides Default [] · Accepted - · Hot-reloads Capped at 64 rules. Ordered rules that rewrite the upstream request before relay. A rule matches when every non-empty scope field equals the request's value exactly: client as the classified client, provider as the canonical label after provider_aliases, model as the recorded model id; an empty scope field matches anything. All matching rules apply in list order, and for the same header or body field the later rule wins. headers sets or replaces upstream headers (names are canonicalized, values must be non-empty single-line), remove_headers deletes them, and body sets max_tokens / max_completion_tokens (1..1000000) on a Chat Completions or Anthropic client body. Credential and protocol headers are rejected in an override at load (provider headers may use them; they apply after the credential). Credential class is",
          "context": ""
        },
        {
          "heading": "Proxy CLI flags",
          "id": "proxy-cli-flags",
          "text": "The flag set in cmd/proxy owns these blocks. Every flag is parsed before any configuration is loaded, so the default below is the registration default, not the effective value after a config file or another override. -config ¶ string Default \"proxy.yaml\" path to config file (empty for built-in defaults) -print-config ¶ bool Default false print documented built-in defaults as YAML and exit without loading configuration -print-example-config ¶ bool Default false print the documented example with enabled provider profiles and exit without loading configuration -version ¶ bool Default false print application and source build metadata as JSON and exit without loading configuration -listen ¶ string Default \"\" override listen address (e.g. 127.0.0.1:8081); keeps instances on distinct ports -db-path ¶ string Default \"\" override storage DB path (\"\" = config value; \"none\" = disable durable storage) -pid-file ¶ string Default \"\" write the process pid to this file after boot -healthcheck ¶ bool Default false probe GET /healthz on the configured listen address and exit nonzero on failure (Docker HEALTHCHECK); loads config read-only -readycheck ¶ bool Default false probe GET /readyz on the confi",
          "context": ""
        }
      ],
      "markdown_text": "# Settings reference\n\n<!-- Generated by cmd/docgen from internal/config.Schema(), config.Default()\n     and the proxy flag registration. Do not edit: run `go run ./cmd/docgen -write`\n     after changing one of those owners. -->\n\nSettings and the proxy CLI write the same fields. The dashboard Settings sheet\nsaves them through `GET` and `POST /admin/config`, the YAML file holds them at\nrest, and the proxy flags override a few of them at launch. Every block below\nis generated from the code that owns it, so a setting's key, label, type,\nbound, reload behavior and help cannot describe one thing here and another in\nthe dashboard. A `-` under accepted values means the schema declares no bound\nand no closed vocabulary for that key.\n\nRead [configuration](configuration.md) for precedence, the YAML file and the\nsettings schema, [containers](containers.md) for image mounts, restore paths\nand the deployment lifecycle, and the [capture gallery](gallery.md) for the\nrendered sheet on both surfaces.\n\n## Server\n\nBind address, database, and ring depth restart to apply. shutdown_timeout applies at the next SIGINT/SIGTERM.\n\n#### `listen`\n\nListen address · `string`\n\nDefault `\":8080\"` · Accepted - · Restart required\n\nHost:port the HTTP server binds. Restart required.\n\n#### `db_path`\n\nDatabase path · `string`\n\nDefault `\"proxy.db\"` · Accepted - · Restart required\n\nSQLite metrics store. Empty disables durability (ring only). Restart required.\n\n#### `history_size`\n\nHistory size · `int`\n\nDefault `10000` · Accepted 1..1000000 · Restart required\n\nIn-memory ring depth and startup backfill count. Durable history and paged request logs can extend beyond this window. Restart required.\n\n#### `shutdown_timeout`\n\nShutdown timeout · `duration`\n\nDefault `5s` · Accepted > 0s · Hot-reloads\n\nHTTP shutdown wait after active request contexts are canceled on SIGINT/SIGTERM. Storage draining follows separately. Must be > 0; applies at the next shutdown without restarting the listener.\n\n#### `restart_drain_timeout`\n\nRestart drain timeout · `duration`\n\nDefault `10m` · Accepted >= 0s (0s = wait indefinitely) · Hot-reloads\n\nHow long a dashboard-triggered restart waits for in-flight streams. Expiry aborts the restart and resumes accepting traffic; unfinished streams are not killed. New connections queue during a successful handoff.\n\n#### `read_header_timeout`\n\nRead header timeout · `duration`\n\nDefault `10s` · Accepted >= 0s (0s = no timeout) · Restart required\n\nSlowloris guard on inbound headers. Restart required.\n\n#### `idle_timeout`\n\nIdle timeout · `duration`\n\nDefault `2m` · Accepted >= 0s (0s = no timeout) · Restart required\n\nKeep-alive idle connections. No write timeout (it would kill SSE). Restart required.\n\n#### `request_body_idle_timeout`\n\nRequest body idle timeout · `duration`\n\nDefault `30s` · Accepted > 0s · Hot-reloads\n\nHow long one inbound body read may wait for progress. Re-armed before every read and cleared at EOF or Close. Must not exceed request_body_read_timeout. Applies to requests started after reload.\n\n#### `request_body_read_timeout`\n\nRequest body read timeout · `duration`\n\nDefault `10m` · Accepted > 0s · Hot-reloads\n\nAbsolute bound for reading one inbound request body after headers. Must be at least request_body_idle_timeout. The restore upload is exempt (idle bound only). Applies to requests started after reload.\n\n#### `response_write_timeout`\n\nResponse write timeout · `duration`\n\nDefault `10m` · Accepted > 0s · Hot-reloads\n\nGeneric per-write bound for buffered responses. Streaming owners may arm a shorter bound. Must be at least sse_write_progress_timeout. Applies to requests started after reload.\n\n#### `go_memory_limit`\n\nGo memory limit · `bytes`\n\nDefault `0B` · Accepted 32MiB..1024GiB (0B = auto cgroup, else unbounded) · Restart required\n\nSoft cap on Go runtime managed memory (heap, stacks, runtime), applied once at startup. With the setting at 0, an operator GOMEMLIMIT wins and otherwise a detected finite cgroup memory ceiling applies at 80% (ceilings below 80MiB are ignored); a set value overrides GOMEMLIMIT, not GOGC. Exceeding it turns the collector more aggressive (capped near 50% CPU), never fails requests. Does not bound SQLite's page cache or OS overhead. Restart required.\n\n## Request\n\nInbound body cap, tool-call history bound, SSRF allowlist, optional body-preview, token-refresh response cap, and debug-capture retention.\n\n#### `max_request_bytes`\n\nMax request bytes · `bytes`\n\nDefault `32MiB` · Accepted 1KiB..1GiB · Hot-reloads\n\nInbound body the proxy will buffer to read routing metadata. Larger bodies are rejected with 413.\n\n#### `request_tool_calls_max`\n\nMax request tool calls · `int`\n\nDefault `1024` · Accepted 1..10000 · Hot-reloads\n\nMost Chat tool calls across the whole message history of one inbound request, including the deprecated per-message function_call shape. Anthropic tool_use and Responses function_call history are bounded by their protocol collection limits instead. Real agent turns replay a handful; raise it only for clients that resend unusually long tool loops, because every call is materialized in memory during translation.\n\n#### `allowed_base_urls`\n\nAllowed base URLs · `strings`\n\nDefault `[]` · Accepted - · Hot-reloads\n\nSSRF allowlist of upstream base URLs. Empty allows any target (single trusted operator). An entry admits only the same scheme, host and port once the scheme's default port is filled in, plus that entry's path and its children, so a port-less entry does not admit other ports on the host. Each entry must be an absolute URL whose prefix is literally lowercase http:// or https://, with a lowercase hostname, no userinfo, query, fragment or trailing slash, and a port after a hostname in 1..65535.\n\n#### `capture_body_preview`\n\nCapture body preview · `bool`\n\nDefault `false` · Accepted - · Hot-reloads\n\nStore a short bounded preview of the last user prompt / response in metrics. Off by default so content is not persisted.\n\n#### `debug_capture_ttl`\n\nDebug capture TTL · `duration`\n\nDefault `24h` · Accepted 1h..168h · Hot-reloads\n\nHow long a full debug capture (bodies and headers) is kept after the request finishes. Operator debug sessions choose which traffic is captured; this is blob retention, not the session timer.\n\n#### `debug_capture_max_bytes`\n\nDebug capture max bytes · `bytes`\n\nDefault `1MiB` · Accepted 4KiB..16MiB · Hot-reloads\n\nCap on one debug capture: retained headers are charged first and the remainder is split between the request body and the client-facing response bytes. Past the cap the rest is dropped and the capture is marked truncated.\n\n#### `debug_store_max_bytes`\n\nDebug store max bytes · `bytes`\n\nDefault `512MiB` · Accepted 16MiB..8GiB (0B = unlimited) · Restart required\n\nTotal durable debug-capture sidecar cap. New captures are skipped once the next write would exceed it; TTL expiry frees capacity. Bytes, not characters. 0 = unlimited. Restart required.\n\n#### `auto_token_refresh`\n\nAuto token refresh · `bool`\n\nDefault `true` · Accepted - · Hot-reloads\n\nExchange an expired or expiring JWT when the client sends X-Proxy-Refresh-Token. All supported providers use inference handback: HTTP 401 with token_expired and access_token in the error body, plus refresh_token only when the exchange returns a different replacement. No inference is sent; adopt the returned credentials and retry, retaining the old refresh token if no replacement is returned. Model discovery refreshes transparently without returning tokens. Stateless: no reusable credentials are retained.\n\n#### `token_response_max`\n\nToken response max bytes · `bytes`\n\nDefault `1MiB` · Accepted 4KiB..16MiB · Hot-reloads\n\nToken-endpoint response read during transparent credential refresh. Past it the refresh fails open and the original request is proxied unchanged.\n\n## Upstream\n\nConnection pool, header timeout, stream keepalives, model-discovery budgets and response-buffer bounds.\n\n#### `upstream_timeout`\n\nUpstream header timeout · `duration`\n\nDefault `5m` · Accepted >= 0s (0s = no header cap) · Hot-reloads\n\nHow long to wait for upstream response headers. Streaming bodies are not subject to this. Transient header timeouts are retried.\n\n#### `upstream_dial_timeout`\n\nUpstream dial timeout · `duration`\n\nDefault `30s` · Accepted > 0s · Hot-reloads\n\nHow long establishing a new upstream connection may take. Applies to new connections after reload; in-flight streams keep their transport.\n\n#### `upstream_dial_keepalive`\n\nUpstream dial keepalive · `duration`\n\nDefault `30s` · Accepted > 0s · Hot-reloads\n\nTCP keepalive interval for upstream connections. Applies to new connections after reload.\n\n#### `upstream_tls_handshake_timeout`\n\nUpstream TLS handshake timeout · `duration`\n\nDefault `10s` · Accepted > 0s · Hot-reloads\n\nHow long the TLS handshake with an upstream may take. Applies to new connections after reload.\n\n#### `models_discovery_timeout`\n\nModel discovery timeout · `duration`\n\nDefault `30s` · Accepted 1s..5m · Hot-reloads\n\nOne upstream metadata budget for transparent key refresh, all model pages and optional enrichment. Never applies to LLM streams. New discoveries use reloaded limits.\n\n#### `models_discovery_max_bytes`\n\nModel discovery bytes · `bytes`\n\nDefault `8MiB` · Accepted 4KiB..64MiB · Hot-reloads\n\nAggregate response bytes read after transport decoding across model pages, unary RPCs and enrichment. Primary overflow fails; optional enrichment is discarded. This is not a strict heap limit.\n\n#### `models_discovery_max_pages`\n\nModel discovery pages · `int`\n\nDefault `100` · Accepted 1..1000 · Hot-reloads\n\nMaximum upstream model responses per discovery, including a unary RPC and optional enrichment. Limits are captured once, never reset between pages.\n\n#### `models_discovery_max_entries`\n\nModel discovery entries · `int`\n\nDefault `10000` · Accepted 100..1000000 · Hot-reloads\n\nModel entries one discovery request may retain across every page and enrichment source. The byte budget alone cannot bound the decoded map cost of a compact catalog, so a source past this count fails closed instead of returning a partial list. Raise it for providers that publish unusually large catalogs.\n\n#### `translated_response_max_bytes`\n\nTranslated response max bytes · `bytes`\n\nDefault `32MiB` · Accepted 4KiB..1GiB · Hot-reloads\n\nWhole buffered non-streaming upstream response a cross-protocol translation may read, and the translated document it may write back. Past it the request fails with 502 response_too_large rather than relaying a prefix that breaks the translated shape.\n\n#### `upstream_response_header_max`\n\nUpstream response header max bytes · `bytes`\n\nDefault `1MiB` · Accepted 4KiB..64MiB · Hot-reloads\n\nUpstream response headers the proxy accepts. Past it the request fails as a transport error. The upstream client is rebuilt on reload, so new requests use the new value while in-flight streams keep the client they started on.\n\n#### `non_stream_capture_max`\n\nNon-streaming capture max bytes · `bytes`\n\nDefault `1MiB` · Accepted 16KiB..64MiB · Hot-reloads\n\nPrefix of a non-streaming response body kept for usage and cost parsing. Larger documents still relay in full; their accounting may be incomplete. This is a capture cap, not a forwarding cap, and it is per in-flight non-streaming request outside max_inflight_response_bytes.\n\n#### `stream_terminal_hold_max`\n\nStream terminal hold max bytes · `bytes`\n\nDefault `64KiB` · Accepted 4KiB..1MiB · Hot-reloads\n\nBytes withheld at the end of a relayed SSE stream while the relay decides between verbatim release and an in-band degenerate-error substitution. Past it the hold is abandoned and the bytes are released verbatim. A single complete event line can exceed it by up to stream_event_max_bytes. Raise it only if a legitimate terminal region is larger than the default.\n\n#### `stream_event_max_bytes`\n\nStream event max bytes · `bytes`\n\nDefault `2MiB` · Accepted 2MiB..16MiB · Hot-reloads\n\nLargest SSE event accepted on the passthrough relay and by every translated stream decoder: a single line, and the accumulated data of a multi-line event. The translated frame buffer is derived from this value, so both bounds move together. The floor is the built-in accepted size; raise it only for providers that emit larger events.\n\n#### `max_conns_per_host`\n\nMax conns per host · `int`\n\nDefault `512` · Accepted >= 0 (0 = unlimited) · Hot-reloads\n\nTotal connections per upstream host. Sized for concurrent SSE streams, not requests/sec.\n\n#### `max_idle_conns`\n\nMax idle conns · `int`\n\nDefault `512` · Accepted >= 0 (0 = unlimited) · Hot-reloads\n\nProcess-wide idle connection pool.\n\n#### `max_idle_conns_per_host`\n\nMax idle conns per host · `int`\n\nDefault `512` · Accepted >= 1 · Hot-reloads\n\nIdle connections kept per upstream host. Cannot exceed max conns per host when that is set. net/http treats 0 as a default of 2, not unlimited, so this must be >= 1.\n\n#### `idle_conn_timeout`\n\nIdle conn timeout · `duration`\n\nDefault `90s` · Accepted >= 0s (0s = never expire) · Hot-reloads\n\nHow long an idle upstream connection is kept before closing.\n\n#### `upstream_stream_idle_timeout`\n\nUpstream stream idle timeout · `duration`\n\nDefault `10m` · Accepted > 0s · Hot-reloads\n\nCancel an upstream response body after this much silence. Releases the handler, upstream connection and scheduler slot. New response bodies use the reloaded value.\n\n#### `whole_document_read_timeout`\n\nWhole-document read timeout · `duration`\n\nDefault `2m` · Accepted > 0s · Hot-reloads\n\nFallback bound for one whole-document upstream read when the caller supplied no deadline. Buffered reads only; streaming SSE is never subject to it.\n\n#### `whole_document_read_max`\n\nWhole-document read maximum · `duration`\n\nDefault `10m` · Accepted > 0s · Hot-reloads\n\nCeiling for whole-document upstream reads. Must cover whole_document_read_timeout and models_discovery_timeout.\n\n#### `sse_keepalive_interval`\n\nSSE keepalive interval · `duration`\n\nDefault `15s` · Accepted 1ns..10m · Hot-reloads\n\nHow often a quiet streaming socket gets a `: keepalive` comment (queue wait, operator hold, mid-stream gaps). Range 1ns..10m. Applies to streams started after reload.\n\n#### `sse_write_progress_timeout`\n\nSSE write progress timeout · `duration`\n\nDefault `1m` · Accepted > 0s · Hot-reloads\n\nPer-event and keepalive write bound for a client-facing SSE stream. A stalled reader fails that write instead of pinning shutdown. Must not exceed response_write_timeout. Applies to streams started after reload.\n\n## Queue & retry\n\nPer-key concurrency, transparent 429/5xx retry and error classification, client error-class disclosure, and quality re-asks.\n\n#### `max_concurrent`\n\nMax concurrent · `int`\n\nDefault `0` · Accepted >= 0 (0 = unlimited) · Hot-reloads\n\nIn-flight sends per provider+key. 0 is unlimited.\n\n#### `max_queue_size`\n\nMax queue size · `int`\n\nDefault `1024` · Accepted >= 0 (0 = unlimited) · Hot-reloads\n\nQueued waiters per group. 0 is unlimited. It also feeds the default queue cap of a new pause hold.\n\n#### `max_inflight_requests`\n\nMax in-flight requests · `int`\n\nDefault `10000` · Accepted 0..1000000 · Hot-reloads\n\nProcess-wide inference admission bound. Requests above it are refused with 503 and Retry-After instead of buffering their bodies. 0 = unlimited. Hot-reloads.\n\n#### `max_inflight_body_bytes`\n\nMax in-flight body bytes · `bytes`\n\nDefault `256MiB` · Accepted 1MiB..64GiB (0B = unlimited) · Hot-reloads\n\nProcess-wide budget for buffered inbound request bodies. Admission charges the bytes actually read and refuses with 503 when the next read would exceed the budget. A declared Content-Length reserves nothing, so an idle connection cannot hold the budget. Bytes past max_request_bytes are neither charged nor retained: that body is answered 413 by the cap owner. A refused request drains at most its remaining cap window so an over-cap body still answers 413 rather than a retryable 503. 0 = unlimited. Hot-reloads.\n\n#### `max_inflight_response_bytes`\n\nMax in-flight response bytes · `bytes`\n\nDefault `256MiB` · Accepted 1MiB..64GiB (0B = unlimited) · Hot-reloads\n\nProcess-wide budget for buffered upstream response bodies: whole-document translation of non-streaming responses, the non-streaming 200 quality spool (at most 1 MiB plus one 32 KiB chunk), and model discovery. Admission reserves the declared Content-Length when it fits the bounded read cap, otherwise that cap, and refuses with 503 and Retry-After before reading when the budget would be exceeded. The reservation is released once the buffer is written, translated, or abandoned. 0 = unlimited. Hot-reloads.\n\n#### `max_queue_wait`\n\nMax queue wait · `duration`\n\nDefault `10m` · Accepted >= 0s (0s = unlimited) · Hot-reloads\n\nHow long a request may sit in the queue before 429. 0s is unlimited. Operator-hold time is excluded.\n\n#### `max_retries`\n\nMax retries · `int`\n\nDefault `5` · Accepted 0..100 (0 = no retries) · Hot-reloads\n\nTransparent retries of transient 429 / 5xx / transport failures. Durable quota 429s follow quota_pause_mode instead of this budget.\n\n#### `queue_retry_after`\n\nQueue Retry-After · `duration`\n\nDefault `2s` · Accepted 0s..24h · Hot-reloads\n\nRetry-After hint sent when our own queue is full or the wait is exceeded. HTTP Retry-After is integer seconds, so the value must be a whole number of seconds.\n\n#### `base_backoff`\n\nBase backoff · `duration`\n\nDefault `1s` · Accepted > 0s · Hot-reloads\n\nInitial adaptive delay. Doubles each attempt and each consecutive failed request, up to max backoff. A provider Retry-After/reset is a floor (never retry sooner) and does not reset this doubling. Cannot exceed max backoff. Must be > 0.\n\n#### `max_backoff`\n\nMax backoff · `duration`\n\nDefault `2m` · Accepted > 0s · Hot-reloads\n\nCap on adaptive backoff. Does not clamp a provider Retry-After / rate-limit-reset (daily limits are often 30–60m). Must be > 0.\n\n#### `quality_retries`\n\nQuality retries · `int`\n\nDefault `1` · Accepted 0..3 (0 = disabled) · Hot-reloads\n\nTransparent re-attempts of a degenerate 200 (empty completion, empty tool_calls), a truncated stream that relayed no content yet, a retryable in-band provider error dropped before the wire, and Cursor's empty-resume re-ask. 0 disables.\n\n#### `thinking_retries`\n\nThinking retries · `int`\n\nDefault `1` · Accepted 0..3 (0 = disabled) · Hot-reloads\n\nTransparent rescue of requests that die or end without an answer during thinking: a stream truncated or reset after reasoning-only output, a cleanly finished reasoning-only completion, a retryable in-band provider error that arrived after reasoning-only output, and a non-streaming reasoning-only body. The fresh attempt appends after the relayed reasoning; answer content and tool calls are never rescued, and finish_reason length never is. Each rescue re-sends the full request (billed). 0 disables.\n\n#### `retryable_error_classes`\n\nRetryable error classes · `strings`\n\nDefault `[]` · Accepted - · Hot-reloads\n\nOperator extensions to the built-in retryable in-band error vocabulary: exact type or code strings (case-insensitive) that a provider reports inside a 200 and that authorize a transparent re-send while no generation content was relayed. Built-ins already cover server_error, the 503 overloaded/unavailable family, api_error, overloaded_error, timeout_error and common gateway spellings; list custom gateway spellings here. Entries add to the built-ins and never move one; a durable quota/billing class is rejected at load, and in-band rate limits, unknown classes and errors after relayed content stay verbatim.\n\nReload applies to new rescue decisions.\n\n#### `rate_limit_error_classes`\n\nRate-limit error classes · `strings`\n\nDefault `[]` · Accepted - · Hot-reloads\n\nOperator extensions to the built-in transient rate-limit vocabulary (rate_limit_error, rate_limit_exceeded, tier_limit_exceeded, resource_exhausted, rpm/tpm spellings and friends). A gateway that announces its limit under a custom type or code string (case-insensitive) is then retried transparently within the retry budget, counted in the rate-limit series, and classified rate_limit for clients. Unlike a bare 429, a non-429 status carrying the class still counts as a failed request on the health surface. Entries add to the built-ins and never move one; a durable quota/billing spelling is rejected at load.\n\nReload applies to new classifications and re-reads stored history through the same vocabulary.\n\n#### `suppress_client_retries`\n\nSuppress client retries · `bool`\n\nDefault `false` · Accepted - · Hot-reloads\n\nMake the proxy the clients' sole retry authority: stamp x-should-retry: false on every LLM-relay error response. The official OpenAI SDKs (python/node/go/ruby) honor it over their 408/409/429/5xx auto-retry and over Retry-After, including relayed provider hints; the proxy's own retry ladder has already run by then. Cannot suppress transport-level failures, and clients that ignore the header (the Vercel AI SDK / opencode stack) keep their own policy.\n\n#### `client_error_class`\n\nClient error class · `string`\n\nDefault `\"off\"` · Accepted `off`, `header` · Hot-reloads\n\nNegotiate millivolt's canonical error class to clients on the LLM relay surface. off leaves relayed responses exactly as the provider sent them. header stamps X-Proxy-Error-Class (rate_limit, quota, unavailable, unreachable, timeout, content, client_error, proxy, canceled, upstream) and a class-derived X-Should-Retry: true|false on every error status before the status line commits, so a client can tell a rate limit announced by a 400 from a client fault and a durable quota block from transient backpressure without parsing provider envelopes. The body is never rewritten.\n\nsuppress_client_retries still wins while it is on; mid-stream SSE errors cannot carry new headers. Reload applies to new responses.\n\n## Error storm protection\n\nBounded recovery queues for affected providers or exact model names. Hot-reloads; policy changes clear observations and wake waiters. Banner visibility changes do not reset protection.\n\n#### `storm_enabled`\n\nEnable protection · `bool`\n\nDefault `false` · Accepted - · Hot-reloads\n\nDetect elevated upstream failure rates and queue affected sends for bounded recovery probes. Opt-in; requests can still fail on cancellation, exhausted retry budgets, queue limits or permanent errors. Retries can repeat upstream execution and billing.\n\n#### `storm_provider_enabled`\n\nProvider protection · `bool`\n\nDefault `true` · Accepted - · Hot-reloads\n\nGate every model on a provider only when all active models individually meet the sample and failure thresholds. Active means a request in the same detection window; idle models expire.\n\n#### `storm_model_enabled`\n\nModel protection · `bool`\n\nDefault `true` · Accepted - · Hot-reloads\n\nGate an affected exact recorded model name within its provider. Dashboard model grouping does not broaden this scope.\n\n#### `storm_banner_enabled`\n\nShow incident banner · `bool`\n\nDefault `true` · Accepted - · Hot-reloads\n\nShow affected providers/models, safe error categories, failure percentages, queue state and recovery timing at the top of the dashboard. Changing visibility does not reset protection.\n\n#### `storm_window`\n\nDetection window · `duration`\n\nDefault `1m` · Accepted 1s..1h · Hot-reloads\n\nRolling time range for successful and eligible failed upstream attempts. Models with no requests in this window expire from provider-wide checks.\n\n#### `storm_min_samples`\n\nMinimum samples · `int`\n\nDefault `20` · Accepted 1..1000000 · Hot-reloads\n\nMinimum successful or eligible failed upstream attempts in the detection window before a model qualifies. Provider-wide protection requires every active model to qualify. Retries count as separate attempts; this is not a distinct-request percentage.\n\n#### `storm_error_percent`\n\nFailure threshold · `int (percent)`\n\nDefault `50` · Accepted 1..100 · Hot-reloads\n\nMinimum percentage of sampled upstream attempts with a selected failure. Applied to each exact model after the minimum sample count; all active models must qualify for provider-wide protection.\n\n#### `storm_initial_backoff`\n\nInitial recovery delay · `duration`\n\nDefault `5s` · Accepted 1ms..1h · Hot-reloads\n\nInitial storm cooldown before a recovery probe. Cannot exceed maximum recovery delay. Valid upstream Retry-After/reset hints still apply independently.\n\n#### `storm_max_backoff`\n\nMaximum recovery delay · `duration`\n\nDefault `2m` · Accepted 1ms..1h · Hot-reloads\n\nCap on exponentially increased storm cooldowns. Must be at least initial recovery delay. Does not shorten upstream Retry-After/reset hints.\n\n#### `storm_backoff_multiplier`\n\nRecovery delay multiplier · `int`\n\nDefault `2` · Accepted 2..10 · Hot-reloads\n\nMultiply the storm cooldown after a failed recovery probe, up to maximum recovery delay.\n\n#### `storm_jitter_percent`\n\nRecovery delay jitter · `int (percent)`\n\nDefault `20` · Accepted 0..100 (0 = no jitter) · Hot-reloads\n\nRandom spread as a percentage of the storm cooldown to separate recovery attempts. 0 disables jitter.\n\n#### `storm_recovery_successes`\n\nRecovery successes · `int`\n\nDefault `2` · Accepted 1..100 · Hot-reloads\n\nConsecutive successful recovery probes required before queued traffic resumes normally.\n\n#### `storm_max_queue`\n\nMaximum queued requests · `int`\n\nDefault `1000` · Accepted 1..100000 · Hot-reloads\n\nMaximum requests waiting for storm recovery. Excess work is rejected locally; requests and their bounded bodies stay in process memory while waiting.\n\n#### `storm_max_wait`\n\nMaximum queue wait · `duration`\n\nDefault `5m` · Accepted 1ms..24h · Hot-reloads\n\nMaximum duration of each storm gate wait, not total request duration across all retries and other queues. Caller cancellation may end the wait earlier.\n\n#### `storm_max_scopes`\n\nMaximum tracked scopes · `int`\n\nDefault `2048` · Accepted 2..100000 · Hot-reloads\n\nBound on provider and exact-model detector scopes retained in process memory. Increasing it does not establish a total process memory ceiling.\n\n#### `storm_max_retries`\n\nAdditional storm retries · `int`\n\nDefault `20` · Accepted 0..1000 (0 = no additional retries) · Hot-reloads\n\nAdditional retries beyond max_retries only while a relevant storm is active and the failure matches a selected eligible transient condition. Does not replay meaningful emitted upstream content. 0 keeps the ordinary retry budget.\n\n#### `storm_status_codes`\n\nHTTP failure statuses · `strings`\n\nDefault `- \"500\" - \"502\" - \"503\" - \"504\"` · Accepted - · Hot-reloads\n\nExact status strings selected for detection and additional storm retries: 429 or 500..599, without duplicates. Empty disables HTTP status triggers. 429 is opt-in because limits may be credential-specific; durable quota/billing 429s remain excluded from storm evidence (quota_pause_mode owns their reaction).\n\n#### `storm_transport_errors`\n\nTransient transport failures · `bool`\n\nDefault `true` · Accepted - · Hot-reloads\n\nInclude transport failures already eligible for the shared retry policy. Caller cancellation and permanent transport errors are excluded.\n\n#### `storm_stream_errors`\n\nResponse and stream failures · `bool`\n\nDefault `true` · Accepted - · Hot-reloads\n\nInclude recorded in-band, stream and quality failures to protect future sends. Reports a generic response error without retaining error bodies for the banner. Never replays meaningful emitted upstream content.\n\n## Quota pause\n\nProvider-wide reaction to a 429 carrying a durable quota/billing error (insufficient_quota/credits, spend limits): surface it immediately, park the provider behind a recovery gate, or hold it until an operator resumes. OpenAI-compatible wire only; Anthropic and Cursor upstreams keep the off behavior.\n\n#### `quota_error_classes`\n\nQuota error classes · `strings`\n\nDefault `[]` · Accepted - · Hot-reloads\n\nOperator extensions to the built-in durable quota/billing vocabulary (insufficient_quota/credits, spend and hard limits, and the numeric business codes of some gateways). A matching type or code string (case-insensitive) is a durable account condition: the ordinary retry ladder never absorbs it, quota_pause_mode owns the reaction, and it counts as an error rather than flow control. Entries add to the built-ins and never move one; a spelling already built into another class is rejected at load.\n\nReload applies to new classifications and re-reads stored history through the same vocabulary.\n\n#### `quota_pause_mode`\n\nMode · `string`\n\nDefault `\"off\"` · Accepted `off`, `retry`, `manual` · Hot-reloads\n\nReaction to a 429 carrying a durable quota/billing error (insufficient_quota/credits, spend limits; in-band occurrences included): off surfaces it immediately; retry opens a provider-wide recovery gate - the triggering request absorbs the 429 and re-sends per the storm recovery delays, new requests park on the gate (bounded by storm_max_queue/storm_max_wait), and the gate closes after quota_pause_recovery_successes consecutive successful probes (the default 1 closes on the first 2xx); manual creates an indefinite provider pause that only an operator resumes.\n\nThe built-in classification is fixed (quota_error_classes may add unknown spellings); only the reaction is configurable. OpenAI-compatible wire only; Anthropic and Cursor upstreams keep the off behavior.\n\n#### `quota_pause_recovery_successes`\n\nRecovery successes · `int`\n\nDefault `1` · Accepted 1..100 · Hot-reloads\n\nConsecutive successful recovery probes that close a retry-mode quota gate. 1 releases the queue on the first 2xx. Meaningful only in retry mode.\n\n## Conversations\n\nHow the request log groups turns into conversations.\n\n#### `conversation_idle_gap`\n\nIdle gap · `duration`\n\nDefault `30m` · Accepted > 0s · Hot-reloads\n\nA gap longer than this starts a new conversation for the same client+key. Generous so thinking pauses inside one task don't split it. Must be > 0.\n\n#### `conversation_max_open`\n\nMax open · `int`\n\nDefault `64` · Accepted 1..100000 · Hot-reloads\n\nCap on concurrently-open conversations per client+key. Oldest is evicted past it.\n\n#### `sub_conversations`\n\nSub-conversation tracking · `sub_conversations`\n\nDefault `[]` · Accepted - · Hot-reloads\n\nPer-client tracking of a request body field that carries a sub-conversation identity, exemplified by opencode's promptCacheKey.\n\nEach entry names one classified client exactly (no wildcard, no case folding) plus 1..4 exact JSON field names matched only at the request body's top level; the first present field decides (a duplicate top-level key drops the identity): a present value that is not a JSON string value counts as absent and the next field is checked, while a present string that cannot be decoded or fails the identity rules (non-empty after trimming, valid UTF-8, free of control bytes, at most 512 bytes) drops the identity for the request - no later field is consulted - and a dropped identity is never a client error.\n\nThe drop is conservative: a value whose raw spelling exceeds the bounded scan window is dropped even when its trimmed form would pass. The value groups the request under a k: conversation identity, after the X-Proxy-Session header (s:) and before automatic client+key grouping; X-Proxy-Parent-Session still owns parent linkage. Requests translated to the Anthropic wire gain a top-level prompt_cache_key carrying the value.\n\nstrip: true removes the entry's configured fields from the top level of the client body before relay or translation, including a Responses client body; the default false forwards the body unchanged. Unlike the request-overrides body fields, strip is not limited to Chat or Anthropic inbound. Param names are exact printable-ASCII JSON key segments up to 64 bytes, no quotes or backslashes; duplicate clients and duplicate params within an entry are rejected. Caps: 16 entries, 4 params per entry. Default: an empty list, tracking fully off.\n\nHot-reloads.\n\n## Format translation\n\nCross-protocol translation policy, streamed tool-call bound, Anthropic defaults and Cursor agent.v1 bridging.\n\n#### `anthropic_default_max_tokens`\n\nAnthropic default max tokens · `int (tokens)`\n\nDefault `4096` · Accepted 1..1000000 · Hot-reloads\n\nInjected into translated Anthropic requests when the client sent none of max_tokens, max_completion_tokens or max_output_tokens.\n\n#### `stream_tool_calls_max`\n\nMax streamed tool calls · `int`\n\nDefault `1024` · Accepted 1..10000 · Hot-reloads\n\nMost tool calls one translated response stream may carry: concurrent open blocks for Anthropic and Responses, distinct calls for Chat (its stream has no per-call close event). A stream past the bound ends with a translation_error. Raise it only for providers that emit unusually large parallel tool batches.\n\n#### `translation_loss`\n\nTranslation loss policy · `string`\n\nDefault `\"warn\"` · Accepted `warn`, `reject` · Hot-reloads\n\nWhat a cross-protocol translation does when the target cannot represent a client field. warn (default) drops optional fields and reports them in X-Proxy-Warnings; reject fails the request with 400 naming the fields before any upstream send and refuses every recorded loss, including a documented approximation. Structural features are always rejected when they cannot be honored. A response-side loss is never fatal: a non-streaming response reports it in X-Proxy-Warnings, and a streaming response drops it without a header. Hot-reloads.\n\n#### `cursor_default_context_window`\n\nCursor default context window · `int (tokens)`\n\nDefault `0` · Accepted >= 0 (0 = omit (client default)) · Hot-reloads\n\nOptional context-window hint stamped onto every model in GET /v1/models when X-Proxy-Format is cursor. 0 omits the field.\n\n#### `cursor_park_ttl`\n\nCursor park TTL · `duration`\n\nDefault `3h` · Accepted > 0s · Hot-reloads\n\nHow long a parked Cursor Run stream stays open waiting for tool results. Must be > 0. Expiry closes the stream; the next continuation cold-starts.\n\n#### `cursor_heartbeat_interval`\n\nCursor heartbeat · `duration`\n\nDefault `5s` · Accepted 1ns..10m · Hot-reloads\n\nHow often the proxy pings a Cursor agent.v1 run (idle parked runs included). Range 1ns..10m. Applies to runs created after reload.\n\n## Storage\n\nDurable SQLite write pipeline. Restart to apply.\n\n#### `storage_write_chan_cap`\n\nWrite channel cap · `int`\n\nDefault `8192` · Accepted 1..1000000 · Restart required\n\nBuffered records before overflow drops. Restart required.\n\n#### `storage_batch_cap`\n\nBatch cap · `int`\n\nDefault `256` · Accepted >= 1 · Restart required\n\nMax records per SQLite transaction. Cannot exceed the write channel cap. Restart required.\n\n#### `storage_flush_interval`\n\nFlush interval · `duration`\n\nDefault `500ms` · Accepted > 0s · Restart required\n\nPartial-batch flush cadence. Must be > 0 (a zero ticker panics). Readiness convicts a wedged writer after one interval plus a progress window of four intervals clamped to 30s..2m. Restart required.\n\n#### `storage_query_timeout`\n\nQuery timeout · `duration`\n\nDefault `10s` · Accepted > 0s · Restart required\n\nBounds dashboard SELECT queries. Must be > 0. Open and AggAPI bind at start (restart required); pause/throttle persist reads the live snapshot.\n\n#### `storage_query_max_bytes`\n\nQuery result bytes · `bytes`\n\nDefault `8MiB` · Accepted 4KiB..64MiB · Restart required\n\nMaximum JSON bytes returned by /metrics/query; also bounds SQLite string/blob values. Oversized results fail with HTTP 413, never truncate. Does not cap all SQLite working memory. Restart required.\n\n#### `storage_query_max_rows`\n\nQuery result rows · `int`\n\nDefault `10000` · Accepted 1..100000 · Restart required\n\nMaximum rows returned by /metrics/query. Oversized results fail with HTTP 413; use SQL filters or LIMIT. Does not limit dashboard aggregates or exports. Restart required.\n\n## Backup\n\nDownload or restore a self-checked archive of the saved config, the SQLite history, or both. Restore inspects first and the apply is confirmed. Merge keeps live defaults and live request ids; replace loads and validates the backup, writes canonical YAML, and preserves CLI-overridden listen and db_path.\n\n#### `backup_max_bytes`\n\nBackup size cap · `bytes`\n\nDefault `1GiB` · Accepted 1MiB..4GiB · Hot-reloads\n\nMaximum size of one Settings backup download or restore upload. Larger archives are refused. Downloads and restores stream through private staging files; this is the admit/reject ceiling, not a heap guarantee.\n\n## MCP\n\nThe operator-gated /mcp LLM tool endpoint: mcp_enabled registers the route or keeps it reserved (404, never inference), and the limits bound what its tools return to a model. Restart to apply; the route table and the endpoint's services are built once at boot.\n\n#### `mcp_enabled`\n\nEnable MCP endpoint · `bool`\n\nDefault `true` · Accepted - · Restart required\n\nRegister the streamable HTTP MCP endpoint at /mcp for LLM tool clients, operator-gated like /metrics and Bearer-only: a session cookie alone is refused. Off keeps the route reserved (404, never inference); the /mcp/ look-alike reservation and the operator gate stay either way. Restart required.\n\n#### `mcp_page_size`\n\nPage size · `int`\n\nDefault `50` · Accepted 10..500 · Restart required\n\nDefault page for the records, values and audit capture listings the endpoint serves to a model. Restart required.\n\n#### `mcp_query_max_rows`\n\nQuery result rows · `int`\n\nDefault `200` · Accepted 1..100000 · Restart required\n\nDefault client-side row limit when a query call omits max_rows. An explicit max_rows may raise it up to this setting's maximum; the proxy's own storage_query_max_rows still answers 413 first. Restart required.\n\n#### `mcp_query_max_bytes`\n\nQuery result bytes · `bytes`\n\nDefault `128KiB` · Accepted 1B..64MiB · Restart required\n\nClient-side cap on the encoded size of one query tool result. Keeps whole rows, truncating with an explicit marker rather than silently. Restart required.\n\n#### `mcp_capture_max_bytes`\n\nCapture max bytes · `bytes`\n\nDefault `256KiB` · Accepted 1B..64MiB · Restart required\n\nSize above which a stored capture document is withheld whole from the audit_capture_get tool; a document that large is more than a model should read in one call. Restart required.\n\n#### `mcp_query_timeout`\n\nQuery timeout · `duration`\n\nDefault `2m` · Accepted > 0s · Restart required\n\nBounds one proxy read the endpoint makes that is not the proxy's own bounded SQL reader (a full-history chart or explorer fold can take seconds). Must be > 0. Restart required.\n\n#### `mcp_timeout`\n\nRequest timeout · `duration`\n\nDefault `30s` · Accepted > 0s · Restart required\n\nBounds every in-process call the endpoint's tools make to the proxy, including mutations. Must be > 0. Restart required.\n\n## Dashboard\n\nLive-view cadence and request-log window. Hot-reloads; open dashboards pick up the next tick.\n\n#### `dash_log_rows`\n\nRequest log rows · `int`\n\nDefault `60` · Accepted 10..500 · Hot-reloads\n\nPage size of the live request log (newest first). Scrolling near the bottom loads more, including older durable history.\n\n#### `dash_poll_interval`\n\nPoll interval · `duration`\n\nDefault `5s` · Accepted > 0s · Hot-reloads\n\nKPI / pause / SSE-fallback poll cadence. Must be > 0.\n\n#### `dash_chart_refresh`\n\nChart refresh · `duration`\n\nDefault `15s` · Accepted > 0s · Hot-reloads\n\nHow often the traffic chart re-fetches server-authoritative buckets and period totals. Must be > 0.\n\n#### `dash_explorer_stale`\n\nExplorer stale after · `duration`\n\nDefault `15s` · Accepted > 0s · Hot-reloads\n\nHow old a cached explorer breakdown may be before it is re-fetched. Must be > 0.\n\n#### `dash_background_refresh`\n\nBackground refresh · `bool`\n\nDefault `false` · Accepted - · Hot-reloads\n\nKeep the dashboard current while its tab is hidden: the poll runs at the browser's throttled background cadence (about one wake per minute on Chromium) and a Web Lock keeps the SSE feed from being frozen. Desktop Chromium only; Android and iOS still suspend background pages at the OS level. Off keeps the current pause-while-hidden behavior.\n\n## Models\n\nModel grouping rules - an ordered rewrite pipeline merging spelling variants of the same model in every grouped surface. Records keep their exact spelling; hot-reloads.\n\n#### `model_rules`\n\nModel grouping rules · `model_rules`\n\nDefault:\n\n```yaml\n- {mode: lower, from: \"\", to: \"\"} - {mode: pattern, from: \"^(?:[a-z0-9][a-z0-9._-]*/)+\", to: \"\"} - {mode: pattern, from: \"(?::[a-z0-9._-]+)+$\", to: \"\"} - {mode: pattern, from: \"(?:-(?:[a-z]{0,2}fp\\\\d+|bf\\\\d+|int\\\\d+|nf\\\\d+|[a-z]?q\\\\d+(?:_[0-9a-z]+)*|gptq|awq|gguf|exl2|mlx|onnx|ggml|fast|speed|value|free|preview|latest|beta|alpha|stable|experimental|thinking|reasoning|xhigh|high|medium|low|minimal|(?:\\\\d{4}|\\\\d{8})))+$\", to: \"\"} - {mode: pattern, from: \"(\\\\d)\\\\.(\\\\d)\", to: \"$1-$2\"}\n```\n\nAccepted - · Hot-reloads\n\nCapped at 64 rules. Ordered rewrite pipeline that merges spelling variants of the same model in every grouped surface (explorer model dimension, scope filters, debug checklist, the Logs download and Settings delete-filter model optgroups, and the request-log leaf’s displayed name). Each rule is one step: exact (whole-string merge old → new), pattern (regex rewrite of all occurrences, $1 capture refs), lower (fold case).\n\nRules apply once in order; the shipped default folds case, strips one or more leading `vendor/` namespaces, strips trailing `:tag` deployments, strips a trailing run of serving decorations (quantization or format such as `-fp4`, `-q4_k_m`, `-gptq`; service tier such as `-fast`, `-speed`, `-value`; release channel such as `-preview`, `-latest`; build stamp such as `-1017`), and unifies `.` with `-` between digits. Model tiers such as `-flash` or `-pro`, fine-tunes such as `-abliterated` or `-rl`, and parameter counts stay distinct.\n\nAn explicitly empty list groups by the exact stored spelling. Stored values remain unchanged; purge/export match them exactly and request details show the original. Debug matching uses separate native base-model normalization, not these display rules. Hot-reloads.\n\n## Providers\n\nOptional per-provider JSON field-name maps: usage/cost response keys, the models metadata endpoint merged into /v1/models, ensured tool names injected into relayed chat bodies, and optional upstream wire headers. Empty = auto-detect.\n\n#### `providers`\n\nProvider field maps · `providers`\n\nDefault `{}` · Accepted - · Hot-reloads\n\nPer-provider cost/usage JSON field paths, optional models_path/models_keys enrichment, ensured tool names and headers (a string map). Field names only, never static prices. Custom cost_keys must report USD; leave cost_in_usd_ticks to automatic unit conversion. ensure_tools names function tools injected as inert stubs into relayed Chat Completions client bodies on a Chat outbound wire missing them.\n\nWhen the client sent no tools of its own, an absent, null, or auto tool_choice is forced to none; an explicit none stays; a required, named, or malformed choice skips injection entirely. A first-party client's tool-signature gate still recognizes the request. Header values expand {{uuid4}} to a fresh UUID, {{platform}} to the server's Rust-style os; arch pair, and {{opencode-msg-id}}/{{opencode-ses-id}} to fresh opencode-format identifiers; unknown templates stay literal. On HTTP relay requests, configured headers override forwarded/extracted-auth values and X-Proxy-Headers wins.\n\naccept-encoding and range are proxy-owned: the X-Proxy-Headers map rejects them with 400, and configured or override values are stripped from the final request. Model discovery and the Cursor bridge construct headers separately and do not apply X-Proxy-Headers. Headers can contain secrets; keep runtime configuration private.\n\n#### `provider_aliases`\n\nProvider aliases · `aliases`\n\nDefault `{}` · Accepted - · Hot-reloads\n\nMap an old provider label to a canonical label. Rewrites existing stored history at boot and on reload; new requests use the canonical label. Existing in-memory records keep their prior label until they age out or the process restarts. Removing a mapping does not restore rewritten history. Chains and self-maps are rejected.\n\n## Request overrides\n\nScoped rewrites of the upstream request: set, replace or remove HTTP headers and set output-token ceilings per client, provider and/or model. Rules match exactly, all matching rules apply in list order, and the later rule wins. Default: an empty list, the feature fully off.\n\n#### `request_overrides`\n\nRequest override rules · `request_overrides`\n\nDefault `[]` · Accepted - · Hot-reloads\n\nCapped at 64 rules. Ordered rules that rewrite the upstream request before relay. A rule matches when every non-empty scope field equals the request's value exactly: client as the classified client, provider as the canonical label after provider_aliases, model as the recorded model id; an empty scope field matches anything. All matching rules apply in list order, and for the same header or body field the later rule wins.\n\nheaders sets or replaces upstream headers (names are canonicalized, values must be non-empty single-line), remove_headers deletes them, and body sets max_tokens / max_completion_tokens (1..1000000) on a Chat Completions or Anthropic client body. Credential and protocol headers are rejected in an override at load (provider headers may use them; they apply after the credential).\n\nCredential class is judged by role, not by a list of vendor spellings: any name carrying authorization/auth, api-key, secret, password, credential, bearer, jwt, signature, cookie, key or token is refused, so x-auth-key, x-amz-credential, x-functions-key and x-subscription-key are covered. Identifier and accounting shapes stay admitted: key-id, cache-key, idempotency-key, and the token counters (x-prompt-tokens, x-token-count) plus the x-ratelimit-* and anthropic-ratelimit-* families. Protocol and framing names (host, content-type, content-length, transfer-encoding and the rest) and the whole x-proxy- control prefix are refused as well.\n\nThe override applies after provider headers and the client's X-Proxy-Headers map and wins over both, with two enforced exceptions: the target's resolved auth header and Authorization are never set or removed by an override, and Accept-Encoding and Range are stripped after the override merge because the transport owns them. It covers inference sends only, never model discovery or token refresh.\n\nBody rewrites apply to Chat Completions or Anthropic client bodies before translation, whatever the target (a Responses client body is not rewritten), and re-stamp the recorded request cap; the Cursor bridge reads no body fields, so body is skipped for cursor targets while header rules still apply. An empty list leaves every request untouched. Hot-reloads.\n\n## Proxy CLI flags\n\nThe flag set in `cmd/proxy` owns these blocks. Every flag is parsed before any\nconfiguration is loaded, so the default below is the registration default, not\nthe effective value after a config file or another override.\n\n#### `-config`\n\n`string`\n\nDefault `\"proxy.yaml\"`\n\npath to config file (empty for built-in defaults)\n\n#### `-print-config`\n\n`bool`\n\nDefault `false`\n\nprint documented built-in defaults as YAML and exit without loading configuration\n\n#### `-print-example-config`\n\n`bool`\n\nDefault `false`\n\nprint the documented example with enabled provider profiles and exit without loading configuration\n\n#### `-version`\n\n`bool`\n\nDefault `false`\n\nprint application and source build metadata as JSON and exit without loading configuration\n\n#### `-listen`\n\n`string`\n\nDefault `\"\"`\n\noverride listen address (e.g. 127.0.0.1:8081); keeps instances on distinct ports\n\n#### `-db-path`\n\n`string`\n\nDefault `\"\"`\n\noverride storage DB path (\"\" = config value; \"none\" = disable durable storage)\n\n#### `-pid-file`\n\n`string`\n\nDefault `\"\"`\n\nwrite the process pid to this file after boot\n\n#### `-healthcheck`\n\n`bool`\n\nDefault `false`\n\nprobe GET /healthz on the configured listen address and exit nonzero on failure (Docker HEALTHCHECK); loads config read-only\n\n#### `-readycheck`\n\n`bool`\n\nDefault `false`\n\nprobe GET /readyz on the configured listen address and exit nonzero when storage is not ready (Compose readiness); loads config read-only\n\n"
    },
    {
      "path": "docs/containers.md",
      "slug": "docs/containers",
      "output": "docs/containers.html",
      "markdown": "docs/containers.md",
      "url": "https://millivolt.llm4people.dev/docs/containers.html",
      "markdown_url": "https://millivolt.llm4people.dev/docs/containers.md",
      "title": "Containers and data",
      "description": "This page covers the image, Compose operation, persistent volumes, backups, versions and the restart lifecycle. The settings surface is in configuration .",
      "group": "Operate",
      "order": 11,
      "bytes": 34241,
      "sha256": "680bbc5f39568de4c33de3bedda37c0f7321b76ff9eac6cc8f55da6ef09a7b04",
      "sections": [
        {
          "heading": "Containers",
          "id": "containers",
          "text": "The Dockerfile builds Linux amd64 and arm64 targets and runs as UID/GID 65532:65532 , with no source tree, Go toolchain or shell in the runtime image. JavaScript/CSS are embedded in the Go binary; Node and Python are test tools, not runtime dependencies. The binary is stripped of debug and symbol tables. The final stage copies only that binary, dependency notices, the generated example and prepared state directories onto the minimal distroless base. The Compose quickstart downloads the image-only compose.yaml . Normal deployment never builds from source. Local builds use the separate development Compose . A registry tag is usable only after its publishing workflow succeeds.",
          "context": ""
        },
        {
          "heading": "Compose operation",
          "id": "compose-operation",
          "text": "Keep the same Compose project name to reuse its named volumes. The normal file names the project millivolt ; an explicit -p overrides it. The deployment inputs are: MILLIVOLT_IMAGE (image reference) MILLIVOLT_PORT (loopback host port) MILLIVOLT_OPERATOR_TOKEN (the operator credential, forwarded into the container environment only) MILLIVOLT_STOP_GRACE_PERIOD (container stop grace) MILLIVOLT_MEM_LIMIT (container memory ceiling, default 1g ) MILLIVOLT_PIDS_LIMIT (process/thread ceiling, default 512 ) Their defaults live in compose.yaml , not server configuration. Supply them consistently through the environment or an ignored local .env file. docker compose config shows the resolved deployment. The memory ceiling is also the source of the runtime's own soft limit: with go_memory_limit at its 0B default, a detected finite cgroup ceiling at or above 80 MiB becomes a soft limit at 80% of itself, so the container bound reaches the Go runtime instead of leaving it unbounded. Raise the ceiling with history_size , request buffers, concurrency or observed identity cardinality; a ceiling under 80 MiB is ignored by the runtime and leaves only the hard OOM kill. pids_limit bounds process and thr",
          "context": "Containers"
        },
        {
          "heading": "Persistent state and configuration",
          "id": "persistent-state-and-configuration",
          "text": "Container path Persistence and permissions /data Writable database directory, including SQLite WAL/SHM sidecars. Mount the directory, not just proxy.db . /config Writable private configuration directory. The image bundles /config/proxy.yaml from the generated example; if deliberately absent, the application uses neutral built-in defaults. Fresh named config volumes receive the image's bundled example, owned by UID/GID 65532:65532 with mode 0600 . No separate configuration download is required. Replacing an image does not overwrite an existing saved configuration; review example-profile changes deliberately when upgrading. These bundle semantics apply to images built from this revision. Existing release images are not changed by a main-branch update; consult the documentation at the selected release tag for older images. Existing volumes and host bind mounts must be owned by the runtime UID, or the database file must already be mode 0600 . Read/write permission alone is not sufficient: startup narrows a broader database mode to 0600 and fails closed when it cannot, naming the file path, owner and current mode. A foreign-owned 0600 database is left unchanged; a broader foreign-owned ",
          "context": "Containers"
        },
        {
          "heading": "Image-only backup and restore",
          "id": "image-only-backup-and-restore",
          "text": "The supplied deployment can back up both named volumes without a source checkout, Python, a shell inside the image or a helper image. This is an offline backup: stop callers first, allow active work to finish, and keep the service stopped while copying. Run from the deployment directory with the same Compose project and environment used to start it. If you use -p , repeat that selection on every Compose command. Do not concurrently replace or restart the source container. The following saves the original Compose file, the pulled image's registry digest, and both volume archives in a new private directory. It expects the supplied single-service layout, /data and /config , with a saved proxy.yaml present. Privately retain any local .env or other deployment inputs as well. ( set -eu umask 077 backup_dir=\"$(mktemp -d ./millivolt-backup.XXXXXXXX)\" printf 'Backup directory: %s\\n' \"$backup_dir\" container_id=\"$(docker compose ps -q millivolt)\" test -n \"$container_id\" image_id=\"$(docker inspect --format '{{.Image}}' \"$container_id\")\" docker image inspect --format '{{index .RepoDigests 0}}' \"$image_id\" > \"$backup_dir/image.txt\" cp compose.yaml \"$backup_dir/compose.yaml\" docker compose stop m",
          "context": "Containers"
        },
        {
          "heading": "Settings backup and restore",
          "id": "settings-backup-and-restore",
          "text": "The dashboard Settings Backup category downloads and restores a self-checked .mvb archive. Choose config, database, or both. The archive is a packed SQLite snapshot ( VACUUM INTO , so free pages are not copied) and/or the schema YAML, then zstd-compressed with a content checksum and an outer SHA-256 of the uncompressed payload. Encoding streams each member into the compressor while hashing and counting it, writes the archive once into a staging file, and self-checks that file before returning it; an archive that fails decode or semantic checks is never emitted, so a produced backup is never a silent corrupt file. The database member is read from the packed snapshot file in bounded chunks instead of being copied whole into memory, so the download cost does not grow with a heap copy of the database. A source file that changes size or cannot be read fails the encode before an archive is emitted. Restore streams the upload through the backup_max_bytes ceiling into one private staging file and decodes it with the same header, zstd, SHA-256 and member-framing checks. When a live store can stage it, the database member is written straight into a private file on the live database's volume ",
          "context": "Containers"
        },
        {
          "heading": "Versions and images",
          "id": "versions-and-images",
          "text": "VERSION is the application release source. The dashboard asset fingerprint is separate: it detects changed embedded frontend bytes, not a semantic release or a complete backend change. main is promotion-only. Full source, browser and live MCP integration, and native container checks run on all testing pull requests, code-bearing testing pushes, manually dispatched testing gates, and manually pushed v* tags; docs and site-only pushes use docs.yml . They also run on Dependabot's main security PRs. An ordinary promotion pull request from testing requires its head to be the current testing tip, main to be already merged back into testing , and a successful full-gate record for that exact commit: the canonical check.yml push run's own check suite, with unit , browser and both native container legs. When a final docs-only commit follows the closest gated testing commit, it reuses that gate if every path since it is docs/site-only; the fallback selects the closest gated testing commit from canonical testing push runs, with no commit-count bound. The proof polls pending exact check runs a bounded number of times and fails closed if they are still pending. For a code-bearing head, let the t",
          "context": ""
        },
        {
          "heading": "Reload, restart and shutdown",
          "id": "reload-restart-and-shutdown",
          "text": "SIGHUP , POST /admin/reload , a successful Settings save, and a backup config restore use the same hot-reload owner. Invalid reloads preserve the running config. Reloadable transport/scheduler settings affect new work without closing active transports. Startup-bound consumers keep their boot settings until restart. Settings reports restart_required ; its effective configuration snapshot can contain new values that those consumers have not adopted yet. The schema/example identify which fields require restart. Rebuild & restart requires Go on PATH and the original source tree available at its compiled-in path. Moved/trimpath builds may report it unavailable. It builds the working tree exactly as it is: uncommitted, unstaged and untracked files are compiled, so a restart is not a review gate and a dirty tree ships as-is. The rebuilt binary is written into the process temp directory, which must be writable ( TMPDIR , or /tmp when unset); an unusable directory is refused with that directory named rather than as a build fault. The choreography builds first, stops acceptance while retaining the listening socket, drains active handlers, flushes storage, then hands the socket to a ready chi",
          "context": ""
        }
      ],
      "markdown_text": "# Containers and data\n\nThis page covers the image, Compose operation, persistent volumes, backups,\nversions and the restart lifecycle. The settings surface is in\n[configuration](configuration.md).\n\n> [!WARNING]\n> This is an offline backup: stop callers first, allow active work to finish,\n> and keep the service stopped while copying. Never copy an open SQLite database\n> as plain files. Restore into a new project and fresh volumes, leaving the\n> original deployment and backups untouched.\n\n## Containers\n\nThe [Dockerfile](../Dockerfile) builds Linux `amd64` and `arm64` targets and runs\nas UID/GID `65532:65532`, with no source tree, Go toolchain or shell in the\nruntime image. JavaScript/CSS are embedded in the Go binary; Node and Python\nare test tools, not runtime dependencies. The binary is stripped of debug and\nsymbol tables.\n\nThe final stage copies only that binary, dependency notices, the generated\nexample and prepared state directories onto the minimal distroless base.\nThe [Compose quickstart](../README.md#docker-compose) downloads the image-only\n[compose.yaml](../compose.yaml). Normal deployment never builds from source.\n\nLocal builds use the separate\n[development Compose](../CONTRIBUTING.md#container-development).\nA registry tag is usable only after its publishing workflow succeeds.\n\n### Compose operation\n\nKeep the same Compose project name to reuse its named volumes. The normal file\nnames the project `millivolt`; an explicit `-p` overrides it.\n\nThe deployment inputs are:\n\n- `MILLIVOLT_IMAGE` (image reference)\n- `MILLIVOLT_PORT` (loopback host port)\n- `MILLIVOLT_OPERATOR_TOKEN` (the operator credential, forwarded into the\n  container environment only)\n- `MILLIVOLT_STOP_GRACE_PERIOD` (container stop grace)\n- `MILLIVOLT_MEM_LIMIT` (container memory ceiling, default `1g`)\n- `MILLIVOLT_PIDS_LIMIT` (process/thread ceiling, default `512`)\n\nTheir defaults live in [compose.yaml](../compose.yaml), not server\nconfiguration. Supply them consistently through the environment or an ignored\nlocal `.env` file. `docker compose config` shows the resolved deployment.\n\nThe memory ceiling is also the source of the runtime's own soft limit: with\n`go_memory_limit` at its `0B` default, a detected finite cgroup ceiling at or\nabove 80 MiB becomes a soft limit at 80% of itself, so the container bound\nreaches the Go runtime instead of leaving it unbounded.\n\nRaise the ceiling with `history_size`, request buffers, concurrency or observed\nidentity cardinality; a ceiling under 80 MiB is ignored by the runtime and\nleaves only the hard OOM kill. `pids_limit` bounds process and thread\namplification, not goroutines.\n\nThe image carries a Dockerfile `HEALTHCHECK` that probes the unauthenticated\n`/healthz` through the binary's `-healthcheck` mode, so `docker compose ps`\nreports health without any operator credential. Both Compose files replace that\nprobe with the [readiness check](operations.md#health-and-readiness), which is\nstrictly stronger.\n\n```sh\n# Start or adopt a newly pulled image while preserving volumes.\ndocker compose pull\ndocker compose up -d\ndocker compose ps\ndocker compose logs --tail 100\n\n# Stop without removing containers or data.\ndocker compose stop\n\n# Remove this project's containers and network, retaining named volumes.\ndocker compose down\n```\n\nDo not add `--volumes` or `-v` to `down` unless deliberately deleting its\nconfiguration and history. Changing the Compose project name selects different\nvolumes and can look like missing data. Back up before an upgrade; the existing\nimage can be replaced, but a database migration is not necessarily reversible.\nSee Docker's [Compose lifecycle](https://docs.docker.com/reference/cli/docker/compose/up/)\nand [volume removal](https://docs.docker.com/reference/cli/docker/compose/down/)\ndocumentation for the underlying behavior.\n\nDo not add a build section to the deployment file. The\n[development Compose](../CONTRIBUTING.md#container-development) owns\nsource builds, its private port and its separate project identity.\n\nThe Compose service drops Linux capabilities, disallows privilege escalation,\nuses a read-only root filesystem and a bounded temporary filesystem. These\ncontrols do not add application authentication or a tenant boundary. Access to\na rootful Docker daemon through the `docker` group is effectively root access;\nsee Docker's [Linux post-installation guidance](https://docs.docker.com/engine/install/linux-postinstall/).\n\n### Persistent state and configuration\n\n| Container path | Persistence and permissions |\n| --- | --- |\n| `/data` | Writable database directory, including SQLite WAL/SHM sidecars. Mount the directory, not just `proxy.db`. |\n| `/config` | Writable private configuration directory. The image bundles `/config/proxy.yaml` from the generated example; if deliberately absent, the application uses neutral built-in defaults. |\n\nFresh named config volumes receive the image's bundled example, owned by\nUID/GID `65532:65532` with mode `0600`. No separate configuration download is\nrequired. Replacing an image does not overwrite an existing saved configuration;\nreview example-profile changes deliberately when upgrading.\n\nThese bundle semantics apply to images built from this revision. Existing release\nimages are not changed by a main-branch update; consult the documentation at the\nselected release tag for older images.\n\nExisting volumes and host bind mounts must be owned by the runtime UID, or the\ndatabase file must already be mode `0600`. Read/write permission alone is not\nsufficient: startup narrows a broader database mode to `0600` and fails closed\nwhen it cannot, naming the file path, owner and current mode. A foreign-owned\n`0600` database is left unchanged; a broader foreign-owned file must be pre-set\nto `0600` or chown'd to `65532:65532`.\n\nBind mounts hide bundled files: supply a config yourself when using one, or\nintentionally accept the application's missing-file defaults. Use private\ndirectory permissions and mode `0600` for a supplied config; with rootless\nDocker or user namespaces, account for the host UID mapping. Do not make\nsensitive directories world-writable to work around ownership failures.\n\nA first launch cannot prepare its own bind-mount host directories. When a\nbind-mount target does not exist, Docker creates it as `root:root` mode `0755`,\nwhich the runtime UID cannot write, and startup fails with SQLite's\n`unable to open database file` error. The log names the database path, the\ndirectory state and the runtime UID.\n\nPre-create the host `data/` and `config/` directories owned by `65532:65532`\nbefore the first start, or `chown -R 65532:65532` them after a failed start,\nthen start the container again. Named volumes avoid this entirely: Docker seeds\nthem from the image with correct ownership.\n\nSettings saves by creating a temporary file beside the resolved config and\natomically renaming it; a symlinked config path is followed to its final\ntarget, so the link stays in place and the target receives the document. The\nrestore rollback publishes through the same writer, so a failed restore of a\nsymlinked config keeps the link too.\n\nA read-only mount, or a bind mount of only the config file, cannot support that\nsave contract. Mount the whole writable directory, or deliberately use\nread-only configuration and update it outside the dashboard. Do not mount the\ncommitted example as a mutable runtime config.\n\nThe container listens on `:8080`; restrict publication on the host with\n`-p 127.0.0.1:8080:8080`. Binding to loopback *inside* the container prevents\nordinary published-port access. Docker port publication does not add operator\nauthentication. Do not share one database among independent proxy containers.\n\nUpstream URLs are reached from the proxy container, so `localhost` in\n`X-Proxy-Base-URL` means that container, not the Docker host. Use an upstream\nhostname reachable on its network, such as another Compose service name.\nHost-service access needs an explicitly configured host-gateway mapping or\nanother reachable host address; it is not included in the supplied deployment.\n\nArguments after the image replace its complete default command. If overriding\na server flag, also keep `-config /config/proxy.yaml -db-path /data/proxy.db`\nunless intentionally selecting other paths or disabling storage. The\n`-print-config` and `-print-example-config` commands print their respective\ndocuments without starting a server.\n\nReplace the container to upgrade or adopt startup-bound settings; the dashboard\ncannot rebuild an immutable image. Keep the same volumes and back them up before\nupgrades. If only a saved config file changed, ordinary `up -d` need not replace\nthe container. Apply startup-bound changes explicitly:\n\n```sh\ndocker compose up -d --force-recreate millivolt\n```\n\nContainer stop sends SIGTERM, which cancels unfinished requests before\ndraining storage. Allow enough stop grace time for the configured shutdown and\nqueued writes; forced termination can prevent that drain. No stop/flush can\nrecover records already dropped under storage overload.\n\n### Image-only backup and restore\n\nThe supplied deployment can back up both named volumes without a source checkout,\nPython, a shell inside the image or a helper image. This is an **offline** backup:\nstop callers first, allow active work to finish, and keep the service stopped\nwhile copying. Run from the deployment directory with the same Compose project\nand environment used to start it. If you use `-p`, repeat that selection on every\nCompose command. Do not concurrently replace or restart the source container.\n\nThe following saves the original Compose file, the pulled image's registry digest,\nand both volume archives in a new private directory. It expects the supplied\nsingle-service layout, `/data` and `/config`, with a saved `proxy.yaml` present.\nPrivately retain any local `.env` or other deployment inputs as well.\n\n```sh\n(\n  set -eu\n  umask 077\n  backup_dir=\"$(mktemp -d ./millivolt-backup.XXXXXXXX)\"\n  printf 'Backup directory: %s\\n' \"$backup_dir\"\n  container_id=\"$(docker compose ps -q millivolt)\"\n  test -n \"$container_id\"\n  image_id=\"$(docker inspect --format '{{.Image}}' \"$container_id\")\"\n  docker image inspect --format '{{index .RepoDigests 0}}' \"$image_id\" > \"$backup_dir/image.txt\"\n  cp compose.yaml \"$backup_dir/compose.yaml\"\n  docker compose stop millivolt\n  test \"$(docker inspect --format '{{.State.Status}} {{.State.ExitCode}}' \"$container_id\")\" = 'exited 0'\n  docker compose cp millivolt:/data/. - > \"$backup_dir/data.tar\"\n  docker compose cp millivolt:/config/. - > \"$backup_dir/config.tar\"\n  docker compose start millivolt\n)\n```\n\nA failed stop or copy exits without automatically restarting the service; inspect\nthe failure before resuming. Copy the completed backup to protected independent\nstorage. The data archive includes any WAL/SHM files, not just `proxy.db`. Never\nuse this file-copy procedure while SQLite is open. An archive cannot recover\nrecords already dropped or writes lost through forced termination.\n\nRestore into a **new project and fresh volumes**, leaving the original deployment\nand backups untouched. Enter the completed backup directory and an unused\nloopback host port when prompted. The original supplied Compose file is required:\ndo not substitute resolved `docker compose config` output, custom external-volume\nnames or bind mounts, which can point the new project at existing data.\n\n```sh\n(\n  set -eu\n  umask 077\n  printf 'Backup directory to restore: '\n  IFS= read -r backup_dir\n  test -s \"$backup_dir/data.tar\"\n  test -s \"$backup_dir/config.tar\"\n  MILLIVOLT_IMAGE=\"$(head -n 1 \"$backup_dir/image.txt\")\"\n  case \"$MILLIVOLT_IMAGE\" in *@sha256:*) ;; *) exit 1 ;; esac\n  printf 'Unused loopback host port: '\n  IFS= read -r MILLIVOLT_PORT\n  case \"$MILLIVOLT_PORT\" in ''|*[!0-9]*) exit 1 ;; esac\n  test \"$MILLIVOLT_PORT\" -ge 1\n  test \"$MILLIVOLT_PORT\" -le 65535\n  export MILLIVOLT_IMAGE MILLIVOLT_PORT\n  restore_dir=\"$(mktemp -d ./millivolt-restore-XXXXXXXX)\"\n  restore_project=\"$(basename \"$restore_dir\" | tr '[:upper:]' '[:lower:]')\"\n  cp \"$backup_dir/compose.yaml\" \"$restore_dir/compose.yaml\"\n  restore_compose() {\n    docker compose --env-file /dev/null -p \"$restore_project\" -f \"$restore_dir/compose.yaml\" \"$@\"\n  }\n  existing_containers=\"$(docker ps -aq --filter \"label=com.docker.compose.project=$restore_project\")\"\n  test -z \"$existing_containers\"\n  existing_volumes=\"$(docker volume ls -q --filter \"name=^${restore_project}_\")\"\n  test -z \"$existing_volumes\"\n  restore_compose create millivolt\n  restore_compose cp --archive - millivolt:/data < \"$backup_dir/data.tar\"\n  restore_compose cp --archive - millivolt:/config < \"$backup_dir/config.tar\"\n  restore_compose up -d millivolt\n  restore_compose logs --tail 100 millivolt\n  printf 'Restored project: %s\\nCompose directory: %s\\nHost port: %s\\n' \"$restore_project\" \"$restore_dir\" \"$MILLIVOLT_PORT\"\n)\n```\n\nKeep the tar streams intact and retain `--archive` on restore: the private config\nmust remain owned by runtime UID/GID `65532:65532` with mode `0600`; the restored\ndatabase is subject to the same ownership and mode check at boot.\nCheck Settings and retained history on the new private port before redirecting\nclients. Save the printed project name and deployment inputs for later commands;\nthe example bypasses automatic `.env` loading during recovery.\n\nDocker documents [tar-stream copying](https://docs.docker.com/reference/cli/docker/container/cp/)\nand [Compose archive mode](https://docs.docker.com/reference/cli/docker/compose/cp/).\nThe repository's isolated container check exercises stopped-volume backup and\nrestore into fresh volumes, including settings, history and file permissions.\nSource deployments can instead use the live SQLite\n[online-backup helper](operations.md#storage-and-accounting) or the Settings archive\ndescribed next.\n\n### Settings backup and restore\n\nThe dashboard Settings Backup category downloads and restores a self-checked\n`.mvb` archive. Choose config, database, or both. The archive is a packed\nSQLite snapshot (`VACUUM INTO`, so free pages are not copied) and/or the\nschema YAML, then zstd-compressed with a content checksum and an outer SHA-256\nof the uncompressed payload.\n\nEncoding streams each member into the compressor while hashing and counting it,\nwrites the archive once into a staging file, and self-checks that file before\nreturning it; an archive that fails decode or semantic checks is never emitted,\nso a produced backup is never a silent corrupt file.\n\nThe database member is read from the packed snapshot file in bounded chunks\ninstead of being copied whole into memory, so the download cost does not grow\nwith a heap copy of the database. A source file that changes size or cannot be\nread fails the encode before an archive is emitted.\n\nRestore streams the upload through the `backup_max_bytes` ceiling into one\nprivate staging file and decodes it with the same header, zstd, SHA-256 and\nmember-framing checks.\n\nWhen a live store can stage it, the database member is written straight into a\nprivate file on the live database's volume instead of being materialized on the\nheap; a restore that selects the database member without a store fails closed\nbefore staging, and a member the request did not select is stream-discarded\nafter its framing checks.\n\nConfig bytes stay buffered within the same 16 MiB config-document bound\n`Config.Validate` enforces on the canonical rendered YAML, so a config that\nvalidates can never exceed what an archive may retain. A config member that\ndeclares a larger size is rejected before its bytes are copied, and encoding\nrefuses to emit one, so an older archive whose config member exceeds that bound\nfails restore. The bound covers only the config member; the database member\nstays streamed under the payload ceiling.\n\nRestore validates that hash, the zstd frame, member framing and config\n`Validate()` before applying anything. A selected database member is decoded\ninto its private staging file first, then must pass `PRAGMA integrity_check`;\nonly that checked file is published as the pending snapshot, which restore then\npreflights for admission before the config member is written.\n\nDecode holds the uncompressed payload to the same `backup_max_bytes` ceiling as\nthe upload (and to the Schema maximum, whichever is lower), so a small\ncompressed file cannot expand past what the operator configured; an over-cap\npayload answers 413 with the upload's wording and stages no pending snapshot.\n\nDownload lists how many live settings differ from default and how many stored\nrequests would be packed. Picking a file first inspects the archive: created\ntime, size, member sizes, each config key as default vs modified vs the live\nfile, and the database request span when a live store can stage the member.\n\nInspect loads the live file through the same strict, bounded reader used by\nconfig reload and restore, not the boot repair path: an unknown nested field,\nan extra YAML document, a non-regular file, or a file above the 16 MiB document\nbound fails the inspect instead of comparing against a repaired or partial\nview.\n\nInspect decodes and counts the database member in place and computes its\noverlap with the live store without writing another copy. Without a live store\nit reports `present:true`, the decoded `bytes`, `inspectable:false` and the\nreason, and produces no request span.\n\nConfig **replace** loads and validates the backup, writes canonical YAML, and\npreserves CLI-overridden `listen` and `db_path`. Config **merge** overlays only\nkeys that differ from `Default()` onto the live file, so live custom values\nstay unless the backup also customized them. An omitted `config_mode` or\n`database_mode` defaults to replace; an explicitly empty or whitespace value is\nrejected as malformed rather than treated as absent.\n\nEither way the restored config hot-applies through the same owner as a Settings\nsave, is reflected in `last_reload`, and reports restart-required keys.\n\nDatabase **replace** streams the decoded file into a pending snapshot next to\n`db_path`, syncs it, and atomically renames it into place; Open admits the\npending file only after it checks again, and the restore waits for process\nrestart.\n\nA `db_path` that is a symlink is resolved to its real target first, so staging,\nadmission, the rollback set and the state marker all belong to the file SQLite\nactually opened; the link stays intact and points at the replacement. A\ncombined merge compares the same resolved identities rather than the two\nspellings.\n\nDatabase **merge** attaches the decoded file read-only and inserts request ids\nthat are not already in the live store immediately (live rows win on conflict);\nthe attached snapshot rejects writes, while the live database stays writable\nfor the merge, and no restart is required. Its request rows, debug sidecars and\nsince-inception totals commit as one transaction, so a failed totals write\nleaves no partial merge behind. Truncated or bit-flipped files are rejected.\n\nThe `backup_max_bytes` setting is the encoded-archive and the decoded-payload\nceiling alike; encoding enforces it while the stream is written, so an over-cap\narchive is removed instead of partially served, an over-cap upload answers 413\nbefore decoding, and a decoded payload over it answers 413 before staging a\nsnapshot.\n\nRestore phases are ordered, not atomic. The database member runs first: a\nreplace stages the decoded file and preflights it with the same schema,\nwriter-INSERT and request-scan value checks boot runs before touching the live\ndatabase, bounded by the same maintenance budget as boot maintenance, and a\nmerge commits rows into the running store.\n\nOne restore owns the whole transaction from the first uploaded byte, so two\nrestores cannot stage and decode two full members on the database volume at\nonce; an inspect shares that serialization because it stages the same members.\nOnly then is the config written and hot-applied.\n\nA failed stage, preflight, or merge leaves the config file and live snapshot\nunchanged, and a failed config write or reload rolls the config back and\nrestores a replace's previous pending slot. A successful live merge has no\nrollback: if the later config phase fails, the merged rows stay applied.\n\nA crash between the database and config phases is likewise not atomic; the\npending snapshot or completed merge can be durable while the config file still\nhas its previous bytes.\n\nPreserved `.incoming`,\n`.incoming.invalid-<token>`, `.incoming.invalid-interrupted-<token>`,\n`.previous`, `.snapshot-state`, and `.millivolt-restore-pending-*` files next to\n`db_path` are boot-recovery evidence and may need operator inspection after such\na crash; do not remove them while a restore may have been in flight. Quarantine\nnames carry a unique token and keep their sidecars beside them, so repeated\nrejections accumulate instead of overwriting the previous one.\n\nThe `.millivolt-restore-pending-*` copy is a hard link to the snapshot that was\nqueued before the restore; it is created before the successor replaces the slot,\nso the pending queue is never empty, and a crash on either side leaves a\nrecoverable snapshot instead of an orphan that the 24 hour staging sweep\neventually deletes.\n\nA volume without hard links (exFAT, vfat, and several FUSE or SMB mounts)\nrejects `link(2)`; there the slot is moved aside instead, still without copying\nthe snapshot bytes, and a crash leaves only the preserved sibling, which boot\nre-admits. When the stage fails before the successor replaces the slot the\nrestore drops the copy again, and when a boot finds a rejected successor or an\nempty slot it renames the preserved copy back onto the slot and admits once, so\nthe queued snapshot is neither hidden nor swept.\n\nA combined config and database merge answers 400 when the restored config's\neffective `db_path` differs from the running store's file, because the rows\nwould be written to a database the next boot does not open; merge the database\nseparately or use database replace.\n\nAt boot, a pending snapshot is admitted only after the same schema, trigger,\nwriter-insert, request-scan value and capture-id preflight `Open` runs. The\ntrigger fence rejects every unowned trigger in the snapshot, not only those\nattached to `requests`: a trigger body is arbitrary SQL, so one attached to\n`meta` or `request_debug` can delete or rewrite request rows.\n\nThe capture-id fence rejects a `request_debug` id that is NULL, non-text or\nblank: such a row can never be fetched by id or reached by the expiry sweep,\nyet still counts against the debug byte budget. Restore merge applies the same\nfence before it imports any row.\n\nRecovery consults the durable `.snapshot-state` marker rather than inferring a\ntransition from the files present. A markerless rollback set from a pre-marker\nrelease cannot be classified: when a live main exists, recovery keeps it and\nremoves the `.previous` debris.\n\nDiscarding a non-empty `.previous-wal` in that markerless state logs a startup\nwarning, because its committed frames cannot be distinguished from debris and\nmay be lost. Marked pending and committed recovery behavior is unchanged.\n\nBoth directions stage database-sized transient files in the live database's own\ndirectory, so capacity follows the data volume rather than a hardened\ndeployment's small `/tmp` tmpfs. Budget roughly one compressed upload plus one\npacked database copy during a restore, and for a replace also the pending copy\nat `db_path`.\n\nThe download's `VACUUM INTO` snapshot directory is removed after the archive is\nencoded, including on failure or a client disconnect. A restore removes its\nprivate upload file and decoded database directory after inspect or apply on\nevery path: a normal response, an invalid or over-cap archive, a validation or\napply failure, or a client disconnect. A config-only upload may use the process\ntemp directory because it carries no database-sized member.\n\nA packed file already on the staging volume (VACUUM dest, decoded member,\npending `.incoming`) is integrity-checked in place, and inspect, overlap,\nreplace and merge consume it by path, so none writes a second database-sized\ncopy. A container's `/tmp` is a small tmpfs by design and never caps backup\nsize.\n\n## Versions and images\n\n[VERSION](../VERSION) is the application release source. The dashboard asset\nfingerprint is separate: it detects changed embedded frontend bytes, not a\nsemantic release or a complete backend change.\n\n`main` is promotion-only. Full source, browser and live MCP integration, and\nnative container checks run on all `testing` pull requests, code-bearing\n`testing` pushes, manually dispatched `testing` gates, and manually pushed `v*`\ntags; docs and site-only pushes use `docs.yml`. They also run on Dependabot's\n`main` security PRs.\n\nAn ordinary promotion pull request from `testing` requires its head to be the\ncurrent `testing` tip, `main` to be already merged back into `testing`, and a\nsuccessful full-gate record for that exact commit: the canonical `check.yml`\npush run's own check suite, with `unit`, `browser` and both native container\nlegs.\n\nWhen a final docs-only commit follows the closest gated `testing` commit, it\nreuses that gate if every path since it is docs/site-only; the fallback selects\nthe closest gated testing commit from canonical `testing` push runs, with no\ncommit-count bound. The proof polls pending exact check runs a bounded number of\ntimes and fails closed if they are still pending.\n\nFor a code-bearing head, let the `testing` `check.yml` push gate finish before\nopening or re-running a promotion PR. A docs/site-only head has no canonical\n`check.yml` push run of its own, so wait for `docs.yml` or only the `required`\ndocs validation. It does not rerun the suite.\n\nA code-bearing promotion must also have a `VERSION` newer than every existing\nrelease tag. Docs/site-only promotions skip the version and full-gate proofs,\nvalidate docs, workflow policy and the site in `required` within its ten-minute\nbudget, and do not rebuild images or cut a release.\n\nMerge with a merge commit. The merged-PR release workflow tags that reviewed\nmerge commit and publishes the image; a delivered code-bearing main push is an\nidempotent fallback. It never pushes `main`.\n\nDependabot security pull requests are the only other exception and normally do\nnot cut a release by themselves; an untagged pending `VERSION` can publish. A\nmanually pushed `v*` tag ships exactly as tagged.\n\nIf the version tag already points at the released commit but its GitHub release\nis missing, the publish job fails closed with a repair instruction instead of\nreporting a successful re-run. Repair the existing tag's release after verifying\nthe image; the job never moves a tag or republishes images. The full maintainer\nchecklist lives in [Contributing](../CONTRIBUTING.md#branch-workflow).\n\n`go run ./cmd/proxy -version` (or `/millivolt -version` in the image) prints\nJSON with `version`, `revision`, `modified`, and `go_version`. Unavailable VCS\nmetadata is reported honestly as revision `unknown` or `modified:null`.\n\nThe registry target is `ghcr.io/llm-4-people/millivolt`. Check the\n[container package](https://github.com/LLM-4-People/millivolt/pkgs/container/millivolt)\nand [image workflow](https://github.com/LLM-4-People/millivolt/actions/workflows/check.yml) for what has\nactually been published; a version in a checkout does not prove an image exists.\nUse a published digest to pin exact bytes. Version tags identify releases but\nare not intrinsically immutable; moving branch and stable aliases can change.\n\nThe [workflow](../.github/workflows/check.yml) runs source, race and browser\nchecks, then native container smoke checks on Linux `amd64` and `arm64` for all\n`testing` pull requests, code-bearing `testing` pushes, manually dispatched\n`testing` gates, and manually pushed `v*` tags, and for Dependabot's `main`\nsecurity PRs. The `unit`, `browser` and `container` jobs start together. Docs\nand site-only pushes use `docs.yml` instead.\n\nA normal promotion PR proves the current testing tip, merged-back main and the\nfull-gate record for that commit, or for the closest gated testing commit with\nonly docs changes after it, and requires a successful\n[escalation](../.github/workflows/escalation.yml) run (every Go test under the\nrace detector plus a five-run clock-sensitive flake sweep) for the reviewed\nhead; docs-only promotions validate the docs, workflow policy and site\ndirectly.\n\nThe merged promotion PR carries the reviewed merge commit and releases it; a\ndelivered code-bearing `main` push only reuses the same reviewed merge and is\nidempotent. Publication is limited to this repository's merged promotion pull\nrequests, delivered pushes to `main`, matching release tags, and\n`testing`-branch pushes (which publish only the moving `testing` tag).\n\nThe release `publish` job waits for `required`. The `publish-testing` job waits\nfor `unit`, `browser` and `container` instead, because a testing push has no\npromotion proof to wait for.\n\nA release run whose `VERSION` is already tagged, such as a Dependabot security\nmerge, normally does not publish; if main carries an untagged pending `VERSION`,\nthat run can publish it. Open or unmerged pull requests do not publish images; a\nmerged promotion PR does.\n\n| Image tag | Meaning |\n| --- | --- |\n| `main` | Moving production image for the released current `main` revision; updated by a non-prerelease versioned release cut from a merged promotion PR or a delivered main push. A prerelease does not move it, and a manually pushed release tag does not either. |\n| `testing` | Moving development image after a successful testing-branch push; never a release. Its OCI version label reports the embedded `VERSION`, which can lag the latest release. |\n| `sha-<full commit>` | Release tag for the exact cut revision built and published; the version bump is part of the reviewed promotion merge, so this is a main commit. Testing pushes do not publish it, while a manually pushed tag publishes it for the tagged revision. |\n| Version from `VERSION` | Created by the matching `v`-prefixed release tag on the promotion merge commit, or by a manually pushed tag. |\n| `latest` | Moving stable alias updated by every non-prerelease release, including a release cut by a merged promotion PR, a main push or a manually pushed tag. Prereleases and testing pushes do not update it. A tag push moves the version, `sha-` and `latest` tags only; `main` stays where the last main-branch release put it. |\n\nRelease builds request an SBOM and max-mode provenance. The image and its\nattestations are published before the tag and release are updated; the workflow\nnever pushes `main`. A failed image build does not leave a public release\npointing at a missing image. Verify\nthe published manifest and attestations with `docker buildx imagetools inspect`,\nverify the repository-associated artifact attestation with\n`gh attestation verify oci://ghcr.io/llm-4-people/millivolt:<version> -R LLM-4-People/millivolt`,\nand pin the digest for deployment. A tag name alone is not an integrity check.\n\nSet `MILLIVOLT_IMAGE` to the desired full image reference or published digest\nbefore the Compose pull/up commands. The `0.x` version series is initial\ndevelopment, not a promise of stable APIs across releases.\n\nGitHub initially publishes GHCR packages privately, even when their repository\nis public. A package administrator must make the package public separately and\nverify an anonymous pull. Repository linkage grants workflow access, not public\nvisibility; see GitHub's\n[package access documentation](https://docs.github.com/en/packages/learn-github-packages/configuring-a-packages-access-control-and-visibility).\n\n## Reload, restart and shutdown\n\n`SIGHUP`, `POST /admin/reload`, a successful Settings save, and a backup\nconfig restore use the same hot-reload owner. Invalid reloads preserve the\nrunning config. Reloadable transport/scheduler settings affect new work\nwithout closing active transports.\n\nStartup-bound consumers keep their boot settings until restart. Settings reports\n`restart_required`; its effective configuration snapshot can contain new values\nthat those consumers have not adopted yet. The schema/example identify which\nfields require restart.\n\nRebuild & restart requires Go on PATH and the original source tree available at\nits compiled-in path. Moved/trimpath builds may report it unavailable. It builds\nthe working tree exactly as it is: uncommitted, unstaged and untracked files are\ncompiled, so a restart is not a review gate and a dirty tree ships as-is.\n\nThe rebuilt binary is written into the process temp directory, which must be\nwritable (`TMPDIR`, or `/tmp` when unset); an unusable directory is refused with\nthat directory named rather than as a build fault.\n\nThe choreography builds first, stops acceptance while retaining the listening\nsocket, drains active handlers, flushes storage, then hands the socket to a\nready child. A flush failure aborts and resumes the old process. A drain timeout\nstill flushes and hands off: the in-flight requests are cut, but everything\nfinalized before them is durable before the child opens the database. The flush\nhas its own bound rather than sharing the drain window.\n\nThe handoff also takes the config transaction lock for its whole flush fence, so\na start while a reload, Settings save or backup restore is running is refused\nwith `409` naming the operation instead of queueing behind it; the fence itself\nis bounded by `restart_drain_timeout` plus the flush bound.\n\nA restore holds that lock across its streaming upload, so `POST /admin/reload`\nand a Settings save answer `409` while one is in flight rather than waiting for\na client-paced upload to finish.\n\nParked native-adapter runs are process-local and do not survive a successful\nrestart.\n\nOrdinary SIGINT/SIGTERM shutdown is different: it cancels active stream contexts,\nthen shuts down HTTP and drains/closes storage. Do not describe it as preserving\nunfinished streams. Already-dropped records cannot be recovered by any flush.\n\nStarting another matching proxy executable on an occupied port can trigger\nsame-binary port reclamation (SIGTERM, then escalation). This is not the graceful\nrebuild workflow; choose distinct ports and databases for separate instances.\n\n"
    },
    {
      "path": "docs/routes.md",
      "slug": "docs/routes",
      "output": "docs/routes.html",
      "markdown": "docs/routes.md",
      "url": "https://millivolt.llm4people.dev/docs/routes.html",
      "markdown_url": "https://millivolt.llm4people.dev/docs/routes.md",
      "title": "Routes and debugging",
      "description": "This page covers the operator and data routes, access control, pause and limits, error storm and quota protection, debug and preview capture, export and...",
      "group": "Operate",
      "order": 12,
      "bytes": 77454,
      "sha256": "b7b6d2bf663e683d08a31ff1135e83bce4e72a120ca22b5cc64dbd09e37c7e2f",
      "sections": [
        {
          "heading": "Operator and data routes",
          "id": "operator-and-data-routes",
          "text": "The routes below belong to millivolt. They are operator-gated unless the row is marked open; the canonical open-path list is in operator access . Read handlers enforce their supported methods; wrong-method requests must not fall through to inference. The namespace is standardized: /metrics/* and dashboard routes are the protected read plane, and /admin/* is the operator action plane; the credential gates both. Route Action / important contract GET /healthz Unauthenticated liveness probe for Docker HEALTHCHECK and load balancers. Reports process/HTTP liveness only, no storage depth. Trailing-slash look-alikes ( /healthz/... ) are reserved and answer 404, never inference. GET /readyz Unauthenticated readiness probe. 200 when the durable pipeline can persist; 503 with a reason when the writer is wedged or a flush failed since boot. Compose uses it through -readycheck . Trailing-slash look-alikes are reserved and answer 404, never inference. GET /favicon.ico Unauthenticated ICO brand mark. Browsers fetch this without Authorization; it is registered on the mux so it never reaches the inference catch-all. GET /favicon.svg , /apple-touch-icon.png , /icon-*.png Ungated SVG/PNG icons for ta",
          "context": ""
        },
        {
          "heading": "MCP transport",
          "id": "mcp-transport",
          "text": "The gate admits the session cookie on gated paths, but this endpoint refuses a cookie-only request with 403 . It forwards the caller's own Bearer on its in-process calls to the routes above, so no session cookie or per-request state is retained between requests. The admitted credential keys an in-memory cache of its SDK server object. The cache is never logged or persisted, and it lets repeated calls avoid rebuilding the 25 registrations. GET and DELETE answer 405 . /mcp/... look-alikes are reserved and answer 404 , never inference. A reserved-namespace spelling whose separator is single-encoded ( %2f or %5c , any hex case) is refused the same way. A double-encoded separator ( %252f ) is not a reserved-namespace spelling: it decodes to a literal %2f inside one segment, so it can reach neither the MCP handler nor a reserved namespace and is ordinary inference traffic. Three tools, docs_list , docs_search and docs_read , answer from the embedded documentation index and make no proxy request. The profiling subtree is operator-gated like every /metrics route: an unarmed plane answers 403, a wrong credential 401, and a reserved-namespace spelling with an encoded separator answers the re",
          "context": "Operator and data routes"
        },
        {
          "heading": "Operator access",
          "id": "operator-access",
          "text": "MILLIVOLT_OPERATOR_TOKEN is the single operator credential for the whole dashboard. It is read once at boot from the process environment, never from proxy.yaml, so it cannot leak through Settings, -print-config , /admin/config output, snapshots or logs. The gate is deny by default and lives in one chokepoint in front of every route. This is the canonical open-path list; Security and the reverse-proxy guide summarize it instead of maintaining a second list. Open: GET /healthz , GET /readyz , the POST /session login handshake (the one open operator route), origin-root brand/PWA files ( /favicon.ico , icons, /manifest.webmanifest , /sw.js ) and transparent inference. Provider credentials ride the same header name and are never inspected by the gate. Gated: the dashboard HTML and /dash/* assets, every /metrics/* surface and every /admin/* route, including unclassified future admin paths and unsupported methods, plus the /mcp endpoint and its reserved /mcp/* look-alikes. A gated MCP request also needs its credential as a Bearer header: the session cookie alone is refused there ( 403 ), because the caller's credential is forwarded on the endpoint's internal calls. Present the credential ",
          "context": "Operator and data routes"
        },
        {
          "heading": "Pause and Limits",
          "id": "pause-and-limits",
          "text": "Pause creates holds; it does not disconnect already-running sends. Matching new sends and retries wait until the hold expires or is resumed. Choose all traffic, any combination of the five scope dimensions, or clients that were unseen when a new-clients hold was created. \"New\" does not mean new requests or new conversations. A hold scopes on the same five dimensions a limit does: providers, models, clients, upstream key hashes and conversations. Values inside one dimension are alternatives, an unset dimension matches any value, and set dimensions intersect - the same rule limits use, because the scheduler matches both against one request identity. When named clients and new are combined, either client condition may match. A hold has its own duration and queue cap; the cap defaults to max_queue_size when the hold does not set one. Excess waiting work can be refused; an indefinite hold needs an explicit resume. Existing holds can be edited in place or resumed individually, while Resume all clears all holds. Overlapping scopes are rejected instead of silently replacing a different hold. The HTTP shape is closed. A resume carries only paused:false and an optional id ; supplying a scope",
          "context": "Operator and data routes"
        },
        {
          "heading": "Error storm protection",
          "id": "error-storm-protection",
          "text": "Open Settings, select Error storm protection , and turn on Enable protection . It is opt-in in both neutral defaults and the deployment example. Choose the rolling window, minimum samples and failure threshold, then select HTTP failure statuses, transient transport failures and response/stream failures. Provider protection requires all models receiving requests in that same window to meet the thresholds individually. A single affected model is held on its own while other active models remain healthy. If only one model is active, that model can establish a provider-wide incident. Provider and model protection can also be enabled independently. Configure initial/maximum recovery delays, multiplier, jitter, recovery successes, additional retries, queue capacity, per-wait timeout and retained scope capacity in that category. The generated example supplies every type, range and default. Existing Queue & retry limits and provider Limits still apply; neither storm_max_wait nor a per-send deadline is a total request timeout. Use a client timeout appropriate to the desired end-to-end wait. Each clickable banner identifies its current scope and safe failure category (HTTP status, transport e",
          "context": "Operator and data routes"
        },
        {
          "heading": "Quota pause",
          "id": "quota-pause",
          "text": "Open Settings, select Quota pause , and choose the reaction to a 429 whose error envelope is a durable account condition - insufficient_quota , insufficient_credits , spend/hard limits, the recognized numeric billing codes (the built-in classification is fixed and quota_error_classes may add spellings; only the reaction is configurable): off (default): the 429 surfaces to the client immediately. Nothing is parked or retried. retry : a provider-wide recovery gate opens on the first such 429 from an OpenAI-wire provider. The triggering request absorbs the 429 and re-sends per the error storm recovery delays; every new request to the provider parks on the gate (bounded by storm_max_queue and storm_max_wait ); the gate closes after quota_pause_recovery_successes consecutive successful probes (the default 1 closes on the first 2xx) and the queue drains. A provider Retry-After on the quota 429 paces the next probe like any other 429. manual : an indefinite provider-scoped pause (an operator hold labeled with the quota class) is created automatically; every request, triggering one included, queues until an operator resumes it on the pause surface. When a pre-existing hold already covers t",
          "context": "Operator and data routes"
        },
        {
          "heading": "Debug and preview capture",
          "id": "debug-and-preview-capture",
          "text": "Debug selects clients, providers and/or models and starts a capture session for a chosen duration or until stopped. At least one dimension is required; selected dimensions intersect, with alternatives inside each dimension. It does not have an unrestricted \"all\" switch. Sessions can be edited or stopped individually; Stop all ends every active session. A stop carries only enabled:false and an optional session id ; a scope or duration beside a stop is a 400 rather than a silent stop-everything. Conflicting scopes are rejected. Debug model matching uses the native-model normalization in debug.go , separate from display-only model rules. Do not assume that every model spelling is an independent exact scope. The session timer selects future captures. debug_capture_ttl separately controls retained capture lifetime after completion, and debug_capture_max_bytes bounds one capture document: retained headers are charged first and the remainder is split between the request and the client-facing response body. Oversized captures are marked truncated. debug_store_max_bytes (default 512 MiB) caps the whole capture sidecar; once the next write would exceed it, new captures are skipped and TTL ex",
          "context": "Operator and data routes"
        },
        {
          "heading": "Export and deletion",
          "id": "export-and-deletion",
          "text": "The operator console's export section downloads finalized request records as JSON, not the process's stderr log and not a complete administrative audit trail. With durable storage it reads the database; otherwise it uses available ring records. Open export, choose either all history or matching records, and review the previewed count before downloading. Provider, model, client and conversation merge the server's known vocabularies with whatever the live record ring holds, so a quiet proxy can still filter by what has run since it started, and each of them also accepts a typed value. Status is the one list-only dimension, because a status code is not a name anyone can type reliably. A debug-only export can include retained capture sidecars. A debug capture is written beside its record as a debug_capture member, and only when the row still has a stored sidecar. The artifact therefore carries debug bodies only while durable storage is live: a ring-record export, or a sidecar already reclaimed by the capture retention sweep, has the record alone. The bodies remain sensitive either way. The export predicate has no constraint for status_code=0 and debug=0 ; both are off rather than a mat",
          "context": "Operator and data routes"
        },
        {
          "heading": "Settings and Restart",
          "id": "settings-and-restart",
          "text": "Settings only reads configuration when opened. Its search, category rail and structured editors work on a local draft; Apply uses the revision-checked save contract . The console's system section reads restart availability and status when opened. The restart action is disabled while a restart is in progress or rebuilding is unavailable. Progress reports actual build/drain/flush/handoff phases; it is not a simulated timer. After a successful handoff, reconnect/bootstrap refreshes history, aggregates, operator state and config. Changed embedded frontend assets trigger a page reload through that same refresh owner. The lifecycle section distinguishes source rebuilds from container replacement and ordinary shutdown.",
          "context": "Operator and data routes"
        },
        {
          "heading": "Dashboard data and request inspection",
          "id": "dashboard-data-and-request-inspection",
          "text": "The KPI band is global. Explorer selections and the request status filter scope the timeline and request log; selecting a card adds a filter and entity links pivot within that shared route. Browser back/forward restores hash-based scopes. Chart preset, timeframe, percentile and series visibility persist in browser storage. These saved views are local browser state, not shared server settings. The In-flight tile separates work that is sending from work the scheduler is parking. Its summary names the two totals that fit the narrowest tile - active and queued - and the composition rail under the value splits every live state (sending, pending, operator-paused, throttled) by color; hovering the rail, or focusing it with assistive technology, reads the exact per-state counts. A queued request is one the proxy has not sent upstream yet: it can be waiting in the admission queue (per-key concurrency, pacing, a provider cap or an operator hold) or in the retry send gate behind a 429/5xx pacing window. The request table marks the same state with the throttled pill, and the status selector can filter on it. Explorer dimensions are Providers, Models, Client, Conversations, Tools, Time, Status,",
          "context": ""
        },
        {
          "heading": "Request rows and details",
          "id": "request-rows-and-details",
          "text": "The log starts with recent rows and pages older durable records as you scroll. Live rows show in-flight/queue/retry progress; final rows retain their outcomes. Retry disclosure opens absorbed attempts under the original request, not another inference record. The attempts log keeps the newest max_retries plus storm_max_retries entries (at least one): a durable quota wait re-sends without spending either budget, so the tail is what explains a long parked request. Click the detail arrow or a non-link row cell to open its drawer; previous/next controls navigate requests without changing the scope. The inspector presents available facts in four classified groups. Request covers identity/status/times, time bucket, wire sizes, client/runtime, provider metadata, model and captured parameters. Content covers conversation and parent ids, turn and size composition, and prompt/response previews. Usage covers token splits, generated tokens, timing, throughput, cost, transport decomposition and tools. Diagnostics covers queue/rate limits, retries, in-band upstream responses, retained headers and Debug. A summary readout carries the status, route, identity and first numbers, and a final upstream ",
          "context": "Dashboard data and request inspection"
        },
        {
          "heading": "Reading timing, cost and health",
          "id": "reading-timing-cost-and-health",
          "text": "Request duration starts after upload and includes metadata work, queue/hold/retry waits and response handling. TTFT is measured from the upstream attempt's own send start to the first token (reasoning or answer), so every retry has its own TTFT. The value excludes proxy scheduler queueing, request parsing and retry backoff, but it does span the upstream transport window from request handoff (dial, TLS, connection-pool wait, header wait). A request that produced no token, one that never sent an upstream attempt of its own (a parked cursor resume), and any non-streamed response have no TTFT: the log shows a placeholder, not 0 ms, and aggregates skip it. Rows written before 0.3.34 stored ttft_ms anchored at request start (upload, queueing and retry backoff included) and were zeroed once by the boot repair, so they report TTFT as absent; their started_at and first_token_at timestamps remain, keeping pre_token_ms and decode windows usable. TPS is the single generation-speed measure: (generation tokens - 1) over the first-token to last-token window. Average TTFT and average TPS are the arithmetic means of those per-request samples. TPS is absent for fewer than two tokens, a non-positive ",
          "context": "Dashboard data and request inspection"
        },
        {
          "heading": "Snapshots, live feeds and monitoring",
          "id": "snapshots-live-feeds-and-monitoring",
          "text": "The HTML includes the canonical bootstrap state so the first paint need not wait for a second state request. Live SSE carries pending progress and finalization; KPI/operator polling and configured aggregate refresh keep derived surfaces current. Reconnects use sequence/feed identity and fall back to full snapshots when replay cannot be trusted. The footer distinguishes live/offline, active holds/Debug, process-local storage drops, totals degraded by a failed startup history scan, and a degraded operator-state restore. The last one is the difference between \"nothing is held\" and \"a saved hold or limit document could not be read\": the served pause and throttle snapshots carry restore_degraded , so a truncated document does not boot as a healthy, unpaused proxy with its saved rules silently gone. The flag stays true for the life of the process; a restart that reads a document which decodes is what clears it. Each key holds one value, so the next accepted operator write replaces the unreadable document rather than preserving it: capture the bytes first if they are needed as evidence. An offline indicator alone does not prove inference is down. None of these mechanisms makes initial his",
          "context": "Dashboard data and request inspection"
        },
        {
          "heading": "Operator recipes",
          "id": "operator-recipes",
          "text": "The gated query route ( GET /metrics/query?q= , above) and the MCP query tool both take exactly one SELECT with no statement separator, and results are bounded by storage_query_max_rows and storage_query_max_bytes ; an over-budget result is an error on the route, so keep wide scans behind a started_at window or a LIMIT . The statement gate also denies the read-only capabilities SQLite exposes outside ordinary tables and columns: ATTACH , DETACH , PRAGMA , LOAD_EXTENSION , the sqlite_dbpage and dbstat table-valued functions, the whole result-bearing pragma_* family and the readfile / writefile functions. Those would read raw pages, page statistics or the absolute database path, which is not part of this console's surface. The denial is lexical over the raw query text, string literals included, so a keyword spelled inside a literal is refused too: SELECT 'attach' AS x and SELECT 'pragma_table_info' both fail. A name only has to contain the bare word at an ASCII boundary; attachment and attach_x pass. The driver executes a multi-statement string wholesale, returning the rows of the last statement, so both rules are load-bearing: without the ; refusal a second ATTACH statement would ru",
          "context": "Dashboard data and request inspection"
        }
      ],
      "markdown_text": "# Routes and debugging\n\nThis page covers the operator and data routes, access control, pause and limits,\nerror storm and quota protection, debug and preview capture, export and deletion,\nrestart, and the dashboard data and request inspector.\n\n> [!WARNING]\n> A genuinely bodyless `POST /admin/purge` deletes the whole history, and a\n> restore applies data before the config phase; both are irreversible without a\n> backup. Exports, debug captures and retained headers can carry sensitive\n> content.\n\n## Operator and data routes\n\nThe routes below belong to millivolt. They are operator-gated unless the row\nis marked open; the canonical open-path list is in\n[operator access](#operator-access). Read handlers enforce their supported\nmethods; wrong-method requests must not fall through to inference. The\nnamespace is standardized: `/metrics/*` and dashboard routes are the protected\nread plane, and `/admin/*` is the operator action plane; the credential gates\nboth.\n\n| Route | Action / important contract |\n| --- | --- |\n| `GET /healthz` | Unauthenticated liveness probe for Docker HEALTHCHECK and load balancers. Reports process/HTTP liveness only, no storage depth. Trailing-slash look-alikes (`/healthz/...`) are reserved and answer 404, never inference. |\n| `GET /readyz` | Unauthenticated readiness probe. `200` when the durable pipeline can persist; `503` with a reason when the writer is wedged or a flush failed since boot. Compose uses it through `-readycheck`. Trailing-slash look-alikes are reserved and answer 404, never inference. |\n| `GET /favicon.ico` | Unauthenticated ICO brand mark. Browsers fetch this without Authorization; it is registered on the mux so it never reaches the inference catch-all. |\n| `GET /favicon.svg`, `/apple-touch-icon.png`, `/icon-*.png` | Ungated SVG/PNG icons for tabs, home screens and the web app manifest. |\n| `GET /manifest.webmanifest` | Ungated web app manifest (name, standalone display, 192/512 icons). |\n| `GET /sw.js` | Ungated service worker. Precaches brand icons/manifest; cache-first only for a `/dash/` URL carrying exactly the stamped version, network-first with cache fallback for unversioned or stale `/dash/` URLs and brand paths. Navigations to `/` are fetched live (never cached: login vs bootstrap) with a static offline fallback. Its never-cache list is generated at load from the same canonical namespace table that drives the gate and the reserved routes, so the three cannot drift; it never intercepts `/`, `/index.html`, `/healthz`, `/readyz`, `/models`, `/sw.js`, `/admin/*`, `/session/*`, `/metrics/*`, `/mcp/*` or `/v1`. |\n| `POST /session` | The one open operator route: exchanges the credential for the session cookie the dashboard's live feed needs. Throttled like every gated route. Lives outside `/admin` so an external authentication layer can front the admin plane without gating millivolt's own login. |\n| `GET/POST /admin/config` | Schema/file/effective state; save `{revision,values}`. Stale revision returns 409, and so does a save while a restore holds the config transaction (its upload is client-paced). Saved-but-reload-failed is explicitly reported. GET and save responses carry a `last_reload` section: `ok`, `error`, `dropped_keys`, `restart_required`, `at`. GET returns provider header values verbatim, because the settings sheet must round-trip them on save; redaction applies to the model-visible `config_get` tool and the operator CLI instead (see [cli](cli.md) and [mcp](mcp.md)), where `--reveal` is the opt-in. Posting a redacted document back is safe: a credential header whose value is the marker keeps the loaded secret, while a posted real value replaces it. The same applies to `set_config`, so a model can read and re-post without erasing credentials. |\n| `POST /admin/reload` | Re-read config and report restart-required keys. Answers 409 while a restore holds the config transaction. |\n| `GET/POST /admin/restart` | Status / rebuild. `GET ?watch=1` streams progress; concurrent starts are rejected, and so is a start while a config transaction (reload, Settings save, backup restore) holds the reload lock: `409` names the operation. |\n| `GET/POST /admin/pause` | Inspect/add/edit/resume holds. POST requires `paused`; optional ID targets one hold. GET reports `queued` (admission and send-gate waiters, the populations an operator drain can release) and `storm_waiters` (requests parked by the storm/quota gate before admission, which only the gate opening or a quota resume frees). |\n| `GET/POST /admin/quota` | Inspect storm state (shared with the banner) / `POST {\"provider\",\"resume\":true}` closes a retry-mode quota gate; parked sends resume immediately. |\n| `GET/POST /admin/debug` | Inspect/add/edit/stop capture sessions. POST requires `enabled`; starting a session requires durable storage (503 `durable storage is disabled` otherwise); optional ID targets one session. |\n| `GET/POST /admin/throttle` | Inspect and edit limits. A policy is named by its opaque `id` or by its selector. Scope dimensions `providers` (the singular `provider` field is still accepted), `models`, `clients`, `key_hashes` and `conversations` intersect; an empty dimension matches any value. An optional schedule uses `days` (0 = Sunday), `start_minute` and `end_minute` in server-local time; equal minutes mean all day and a start after the end spans midnight. POST accepts `concurrency`, `requests`/`request_window`, `tokens`/`token_window`, `anti_burst` and `ramp_duration`; supplied limits merge. A count requires its own window only when the policy has no stored window for that dimension: a fresh count without one is refused, while a count may raise an already windowed dimension alone. A count of `0` clears that dimension and its window. A window without a count is a refused no-op unless a count is already stored. `clear:true` drops the whole policy. Anti-burst and its ramp require a single-provider policy without a schedule. GET also returns `known_providers`, `known_clients` and `known_models` for selector pickers. |\n| `POST /admin/queue/drain` | Release parked requests without waiting for their limit, pause hold or retry window, covering both the admission queue and the send gate. Requires exactly one scope: `all:true`, `provider`, `model` or `client`. Released requests answer with a retryable 503, never a provider error; a request already exchanging bytes with the provider finishes normally. |\n| `GET /admin/debug/capture?id=` | Load an unexpired durable debug sidecar; absent/no-store returns 404. `&download=1` serves the same document as a gzip artifact named `millivolt-debug-<captured_at>.json.gz`, falling back to the record id when `captured_at` does not decode. |\n| `POST /admin/purge/count` | Preview the same deletion/export predicate; traffic can change the count afterward. A genuinely bodyless POST counts the whole set, mirroring the bodyless delete; otherwise the body is `{\"filter\":{...}}`. Filters are body-only, so any query key is rejected with 400 before the body is read. |\n| `POST /admin/purge` | Delete matching finalized records. A genuinely bodyless POST deletes everything: that is the deliberate full-history command, it answers `200` rather than `404`, and any query key must be moved into a body instead. Otherwise the body is `{\"filter\":{...},\"reviewed_count\":N}`: an empty/invalid filter is rejected, and a supplied reviewed count is counted again inside the delete transaction, refusing with 409 when the row set moved. `status_code=0`, `debug=0` and `has_error=0` mean \"no constraint\" on that dimension, not a match for zero or false. The response is `{\"deleted\":N,\"buffer_removed\":N}`. Filters are body-only: any query key is rejected with 400 before the body is read, so `?provider=...` can never broaden the no-body full delete. |\n| `GET /admin/backup` | Download the self-checked `.mvb` Settings backup archive of config and/or database members. `?config=1` and `?database=1` select members, defaulting to both when no key is given; an explicit empty selection is an error. The query grammar is strict: parse errors, repeated or unknown keys, and malformed values all return 400. |\n| `POST /admin/restore` | Restore an uploaded `.mvb` Settings backup archive, validated before anything is applied. `?inspect=1` previews the archive (created time, member sizes, the config values plus their changed-key lists against defaults and the live config, and the database request span when a live store stages the member) without applying anything. A store-less preview still reports the member's presence and decoded size with `inspectable:false` and the reason. `?config=1` and `?database=1` select members as on backup; `?config_mode=` and `?database_mode=` take merge or replace and default to replace when omitted; an explicit empty or whitespace value is rejected as malformed. Success reports the `restart_required` keys. The upload is exempt from `request_body_read_timeout` (the idle bound still applies) and an expired read deadline answers 408. The query grammar is strict: parse errors, repeated or unknown keys, and malformed values all return 400. |\n| `GET /metrics/export` | Download all or exactly filtered finalized records as a gzip artifact named `millivolt-logs-<timestamp>.json.gz`; gunzip it for the JSON array. `status_code=0` and `debug=0` mean \"no constraint\" on that dimension. A debug capture rides as a sibling `debug_capture` member only for a row that has a stored sidecar, so debug bodies appear only while durable storage is live; a ring-only export never carries them, and debug bodies stay sensitive either way. |\n| `GET /metrics/query?q=` | Restricted SELECT with timeout/output limits; 503 when durable storage is disabled. Not a hostile-query sandbox. |\n| `GET /metrics/bootstrap` | Dashboard state and full/incremental recent-record snapshot. |\n| `GET /metrics/live/stream` | Replayable finalized SSE feed plus ephemeral pending lifecycle/reset events. |\n| `GET /metrics/agg/chart`, `/explorer`, `/log` | Scoped history chart, faceted explorer, and durable log paging. The Requests-card `s=` selector accepts an exact code or a live in-flight class on all three, but only the explorer folds pending rows: the chart answers a live class with `400 invalid scope` (its buckets are finalized-only, so an accepted class could only read as \"no traffic\"), and the log keeps its standing empty page so the archive pager does not stop. |\n| `GET /metrics/prometheus` | Prometheus exposition over the in-memory ring, not durable since-inception dashboard totals. |\n| `GET /metrics/pprof/` | Standard Go profiling handlers behind the same credential as every `/metrics` route: the index listing plus the `profile` (CPU), `heap`, `allocs`, `goroutine`, `block`, `mutex` and `threadcreate` profiles at `/metrics/pprof/<name>`. Unregistered subpaths answer the reserved namespace 404, never inference. See the capture workflow below the route table. |\n| `POST /mcp` | Streamable HTTP MCP endpoint, operator-gated like `/metrics` and enabled by default. `mcp_enabled: false` removes it from the process; the route stays reserved, answers 404 and never reaches inference. Serves the 25 MCP tools, Bearer-only and stateless. See [MCP transport](#mcp-transport) below. |\n\nPause/Debug/Limits successes may include a persistence warning: runtime state\nwas applied, but saving it failed. Do not retry as though the mutation rolled\nback. With storage disabled, Pause and Limits keep their memory-only state\nintentionally. Debug is the exception: starting a session answers 503 because\nwith no store every matched request would retain bodies for a sidecar that\ncould never be fetched.\n\n### MCP transport\n\nThe gate admits the session cookie on gated paths, but this endpoint refuses a\ncookie-only request with `403`. It forwards the caller's own Bearer on its\nin-process calls to the routes above, so no session cookie or per-request state\nis retained between requests.\n\nThe admitted credential keys an in-memory cache of its SDK server object. The\ncache is never logged or persisted, and it lets repeated calls avoid rebuilding\nthe 25 registrations. `GET` and `DELETE` answer `405`.\n\n`/mcp/...` look-alikes are reserved and answer `404`, never inference. A\nreserved-namespace spelling whose separator is single-encoded (`%2f` or `%5c`,\nany hex case) is refused the same way. A double-encoded separator (`%252f`) is\nnot a reserved-namespace spelling: it decodes to a literal `%2f` inside one\nsegment, so it can reach neither the MCP handler nor a reserved namespace and is\nordinary inference traffic.\n\nThree tools, `docs_list`, `docs_search` and `docs_read`, answer from the\nembedded documentation index and make no proxy request.\n\nThe profiling subtree is operator-gated like every `/metrics` route: an\nunarmed plane answers 403, a wrong credential 401, and a reserved-namespace\nspelling with an encoded separator answers the reserved 404. `go tool pprof`\ncannot send an `Authorization` header, so fetch the profile with curl and\nanalyze the file against a locally built binary. Against the dev instance\n([`scripts/dev.sh`](../scripts/dev.sh), loopback `127.0.0.1:8081`):\n\n```sh\ngo build -o /tmp/millivolt-profiling ./cmd/proxy\ncurl -fsS -H \"Authorization: Bearer $MILLIVOLT_OPERATOR_TOKEN\" \\\n  -o /tmp/cpu.pprof 'http://127.0.0.1:8081/metrics/pprof/profile?seconds=30'\ngo tool pprof /tmp/millivolt-profiling /tmp/cpu.pprof\n```\n\nThe `seconds=N` parameter on `/metrics/pprof/profile` is the capture window:\nthat one request stays open for the whole window while samples accumulate. The\nvalid range is 1 to `response_write_timeout` (600 by default); an absent or\nunparseable value uses 30 and a larger one is lowered to the bound, so a\ncapture never outlives the delivery contract unnoticed.\n\nA process runs one CPU profile at a time, so a second concurrent `profile`\nrequest fails with 500 until the first finishes. On `/metrics/pprof/heap`,\n`gc=1` forces a garbage collection cycle before the sample.\n\nThe proxy's own `/mcp` endpoint serves this whole surface to an LLM, using the\nsame credential and the same routes. It adds no route of its own and dispatches\neach tool call in process through the same gate, so its forwarded Bearer is\nre-validated exactly like an external request.\n\nFor its irreversible call, the\noperator credential and the tool's own guards are the entire gate: an empty\npurge filter, a purge without the exact confirmation phrase, and a purge\nwithout the `purge_preview` token issued for that same filter are each refused.\nThe preview token expires 15 minutes after it is issued, so a purge more than\n15 minutes after its preview needs a fresh one.\n\nIt also refuses a capture session on a proxy without durable storage, and an\nunknown name in a capture scope or a throttle provider is offered the known\nvalues instead. The throttle provider check fails open when the proxy's\nvocabulary is empty or cannot be read; the capture scope check accepts any name\nwhen the vocabulary is empty but refuses when the vocabulary cannot be read.\n\nIt never follows a redirect, and it presents the credential only in the\n`Authorization` header. See the [MCP server guide](mcp.md).\n\n### Operator access\n\n`MILLIVOLT_OPERATOR_TOKEN` is the single operator credential for the whole\ndashboard. It is read once at boot from the process environment, never from\nproxy.yaml, so it cannot leak through Settings, `-print-config`,\n`/admin/config` output, snapshots or logs.\n\nThe gate is deny by default and lives in one chokepoint in front of every\nroute. This is the canonical open-path list; [Security](../SECURITY.md) and the\n[reverse-proxy guide](reverse-proxy.md) summarize it instead of maintaining a\nsecond list.\n\n- Open: `GET /healthz`, `GET /readyz`, the `POST /session` login handshake (the\n  one open operator route), origin-root brand/PWA files (`/favicon.ico`, icons,\n  `/manifest.webmanifest`, `/sw.js`) and transparent inference. Provider\n  credentials ride the same header name and are never inspected by the gate.\n- Gated: the dashboard HTML and `/dash/*` assets, every `/metrics/*` surface\n  and every `/admin/*` route, including unclassified future admin paths and\n  unsupported methods, plus the `/mcp` endpoint and its reserved `/mcp/*`\n  look-alikes. A gated MCP request also needs its credential as a Bearer\n  header: the session cookie alone is refused there (`403`), because the\n  caller's credential is forwarded on the endpoint's internal calls.\n\nPresent the credential as `Authorization: Bearer <value>`. A valid Bearer\nrequest on a dashboard, admin, metrics or dash route also mints a session\ncookie, because the dashboard's live feed uses EventSource, which cannot send\nAuthorization headers. The `/mcp` endpoint deliberately returns no cookie: its\ncaller forwards the credential on the endpoint's internal calls.\n\nThe cookie is HttpOnly (script never reads it), SameSite Strict, scoped to\n12 hours, and signed with a key derived from the operator token, so a\ncontainer restart with the same credential keeps the session. Rotating the\ntoken invalidates outstanding cookies.\n\nThe cookie carries `Secure` only when the request arrived over TLS or\nany `X-Forwarded-Proto` token names a secure scheme (`https` or `wss`). The\nheader is a list: the canonical NGINX sample overwrites it with this server's\n`$scheme`, and an ingress that appends its own scheme after the client's\n`http` must not downgrade the cookie - hence any token, not the first. A\nloopback plain-HTTP dashboard keeps working\nwhile a TLS presentation gets the flag.\n\nEvery response to a secure presentation also carries\n`Strict-Transport-Security: max-age=15552000` (180 days), set once at the\noutermost server wrapper from the same secure-presentation test. There is no\n`includeSubDomains`, because millivolt cannot know whether sibling or parent\nhostnames are TLS-capable. A plain-HTTP response carries no header at all\n(browsers ignore it there), so the dev instance is unaffected.\n\nThe lifespan is\ndeliberately under a quarter: moving the dashboard off TLS becomes reachable\nagain within that window instead of pinning a browser for a year.\nDo not expose the listener over plaintext networks anyway.\n\nThe login page served for unauthenticated dashboard visits exchanges the\nentered value for that cookie through `POST /session` and works without JavaScript; API\nclients can call the same endpoint or simply send the Bearer header on every\nrequest. An expired cookie re-prompts in the dashboard or reappears as the\nlogin page on navigation.\n\nUnregistered `/admin/*`, `/session/*`, `/metrics/*` and `/mcp/*` paths are reserved: they\nanswer 404 and are never forwarded upstream. The gate also refuses 404 when an\nowned-namespace path is written with a percent-encoded separator (`%2f` or\n`%5c`, any hex case), a duplicated separator (leading or interior) or a dot\nsegment: the mux cannot route it to the reserved subtree unchanged, so it\nwould otherwise fall through to inference.\n\nA double-encoded separator\n(`%252f`) is not a reserved-namespace spelling: it decodes to a literal `%2f`\ninside one segment, matches no reserved route, and is ordinary inference\ntraffic.\n\nFailed authentications are throttled per source IP. The immediate hop is the\nonly trusted one, so the throttle key is the rightmost `X-Forwarded-For`\nelement (the address that hop appended) and `RemoteAddr` when the header is\nabsent; a client can prepend anything, and an unparseable element is skipped.\n\nThe shipped [NGINX example](../deploy/nginx.conf) resolves its own peer with\n`real_ip` first, so the rightmost element is the real client. A directly\nexposed instance lets a client choose its own key, which only ever relaxes the\nthrottle, never the credential decision: after five rejected credentials the IP\nis locked out with a window that doubles from 10 seconds to a 15 minute\nceiling.\n\nThe throttle counts only\npresented-but-wrong credentials, so an expired-cookie dashboard polling in a\nbackground tab cannot lock its own operator out, and a verified credential is\nalways admission: presenting the correct Bearer during a lockout clears the\nbudget, because the lockout exists to rate-limit guessing, not to lock the\noperator out of their own dashboard.\n\nThe map is hard-capped at 4096 source\nIPs with idle expiry, so spoofed-address floods cannot grow it; reaching the\ncap is logged once per episode, because from then on a new source evicts a\ntracked one. Crossing the five-failure threshold is logged once per source.\n\nA lockout response is `429` with a coarse rounded `Retry-After` and a generic JSON body,\nexcept `GET /` (and `/index.html`): the sign-in page is still served, read-only, with the\nsame `Retry-After`, the form intact and the lockout named in its notice slot, because\nthe form is the only route back to a credential and `POST /session` keeps working\nthrough the lockout.\n\nWith the variable unset or empty the deny-all state holds: the whole dashboard\nreturns 403, the open `POST /session` handshake cannot mint a cookie, and only\n`/healthz` and `/readyz`, brand/PWA files and inference respond.\n\nA nonempty value shorter than 16 or longer than 512 bytes fails the boot\ninstead of silently weakening the gate.\n\nThe credential is process bound: config reload does not re-read it,\nso rotating the value requires a real process restart (a supervisor restart\nor a fresh deployment; the dashboard's restart handoff inherits the parent\nenvironment, so it keeps the old credential by design).\n\nThe dashboard asks for the value once per browser tab, keeps it in\nsessionStorage, attaches it to gated calls only and drops it as soon as the\nserver rejects it. Non-browser callers send the header directly, for example\n`curl -H \"Authorization: Bearer $MILLIVOLT_OPERATOR_TOKEN\" -XPOST .../admin/purge`. Environment variables are readable by same-user processes through `/proc`,\nso run the proxy under a dedicated account.\n\n### Pause and Limits\n\nPause creates holds; it does not disconnect already-running sends. Matching new\nsends and retries wait until the hold expires or is resumed. Choose all traffic,\nany combination of the five scope dimensions, or clients that were unseen when a\nnew-clients hold was created. \"New\" does not mean new requests or new\nconversations.\n\nA hold scopes on the same five dimensions a limit does: providers, models,\nclients, upstream key hashes and conversations. Values inside one dimension are\nalternatives, an unset dimension matches any value, and set dimensions\nintersect - the same rule limits use, because the scheduler matches both against\none request identity. When named clients and new are combined, either client\ncondition may match.\n\nA hold has its own duration and queue cap; the cap defaults to `max_queue_size`\nwhen the hold does not set one. Excess waiting work can be refused;\nan indefinite hold needs an explicit resume. Existing holds can be edited in\nplace or resumed individually, while Resume all clears all holds. Overlapping\nscopes are rejected instead of silently replacing a different hold.\n\nThe HTTP shape is closed. A resume carries only `paused:false` and an optional\n`id`; supplying a scope, duration or queue cap beside it is a 400, because the\nproxy has no scope-selective resume and accepting one would clear more holds\nthan the caller named.\n\n`all:true` cannot be combined with `new` or any scope\ndimension; the global hold already covers them. Named clients plus `new`\nremains a valid union. An edit restates the dimensions it supplies and preserves\nthe ones it omits, so supplying an explicit empty array is how a dimension is\ncleared. These are enforced by the handler, not only by the MCP and CLI\nwrappers.\n\nThe known client/provider/model vocabularies (the pause and capture pickers,\nand the snapshot a new-clients hold compares against) are bounded at 4096 names\nper dimension.\n\nClient labels and model ids come from the request, so they are\nevictable: past the cap the least recently observed name makes room for the\nnewest, so a client that keeps sending requests outlives a burst of one-shot\nlabels that arrived after it.\n\nNames an operator documents - a hold scope, a debug session, a limit policy\n(including one installed from a request's `X-Limit-*` headers or restored at\nboot) - are pinned and are never evicted by later traffic, so a flood\nof distinct labels cannot hide the client you scoped a hold to.\n\nPins are derived from the documents that exist, not accumulated: resuming a\nhold or ending a debug session releases its names back to ordinary eviction.\nWhen a full vocabulary is entirely pinned, a new observed name is dropped\nrather than displacing operator intent, and a scope that cannot be listed is\nnamed in the log instead of disappearing silently.\n\nA hold scopes on the caller's claimed client label, so it separates your own\ntools from each other, not trusted callers from untrusted ones; a caller that\nsends another client's label is parked, or not parked, as that client. See\n[client identity](../SECURITY.md#client-identity-is-a-claim-not-an-authentication).\n\nLimits applies to an intersection of conditions: providers, models, clients,\nkey hashes and conversations. Values inside one condition are alternatives; an\nempty condition matches any value, so a rule with no condition covers every\nrequest. A request must satisfy every non-empty condition, and every matching\npolicy charges its own lease, so the tightest cap wins.\n\nA provider-only rule keeps the per-key concurrency and fairness behavior\nbelow; adding any other condition narrows the same machinery without\nchanging it. Conditions select the request's recorded identity, so models\nmatch the request spelling, keys match the SHA-256 digest, and conversations\nmatch the selected leaf.\n\nA rule may also carry a recurring schedule: `days` (0 = Sunday), `start_minute`\nand `end_minute` in the server's local timezone. Equal minutes mean all day, and\na start after the end spans midnight, with the after-midnight portion belonging\nto the previous day. An empty schedule is always active. Outside a rule's window\nit does not charge, settle or queue, and a request that matches no other rule\nproceeds normally.\n\nA policy's identity is the digest of its normalized conditions and schedule.\nEditing either one therefore creates a new identity, and two rules cannot\nsilently share counters. Provider-only policies keep the version 1 persisted\nshape and still accept the singular `provider` field; a rule with any other\ncondition persists its selector arrays. `clear:true` removes the whole policy\nand cannot be combined with a limit dimension: the handler refuses the\nambiguity instead of dropping the supplied value and reporting success.\n\nChoose concurrency, requests per window, tokens per window and the optional\nanti-burst ramp. The console shows whether a policy came from the console or a\nrequest header, its schedule, and available budget and in-flight/queued state.\n\nQueued counts every request the scheduler parks for that policy - admission\nwaits and send-gate waits behind a 429/5xx pacing window alike - not only work\nblocked by the configured cap. Send-gate waits are paced by the provider's retry\nhint and the retry budget; `max_queue_size` and `max_queue_wait` bound only the\nadmission FIFO.\n\nProvider admission is fair across keys: a release or refill\nrotates across the groups actually waiting on the shared provider gate\n(concurrency or the request/token bucket), granting one request per group per\npass. A group parked only on its own pacing window, hold, anti-burst ramp or\nper-key cap is outside that fair set and does not delay another key's fast\npath. A release settles the gate and drains once, and the drain stops as soon as\na grant refills a saturated provider concurrency cap.\n\nHeader semantics are in\n[protocol](protocol.md#routing-headers). Persisted policy does not mean the live\nscheduler's counters and in-flight requests survive a restart.\n\n**Drain queue** releases every request the scheduler has parked, or only those\nwhose recorded provider, model or client matches the one named in the console,\nwithout waiting for a limit window, pause hold or retry pacing to open. The\nselector reads each parked request's own identity, so it also releases work\nparked by a hold, by pacing, or by a provider without a limit row. The overview\nshows the total parked count.\n\nEach released request answers with a retryable 503\nand is recorded as `queue_drained`, never as a provider error; a request already\nexchanging bytes with the provider finishes normally. The API also accepts the\nsame three scopes for scripted drains.\n\nAnti-burst is opt-in and scoped to each provider+key group. It is available\nonly on a single-provider rule without a schedule, because a ramp is defined\nover the provider-plus-key groups the scheduler owns; the server rejects the\npair on any other rule.\n\nWith `anti_burst` enabled and a concurrency target of at\nleast 2, a group starts at one concurrent request and gains allowance linearly\nuntil it reaches the rule's `concurrency` target after `ramp_duration`. It is\ninert unless all three are set: the flag, a target of at least 2, and a duration\nabove zero.\n\n`ramp_duration` accepts the same 1s..24h window grammar as request and token\nwindows, including `1d`; empty, `0` or `0s` turns it off. Requests beyond the\ncurrent allowance stay in the existing per-key FIFO. A fully idle group whose\nidle period reaches `ramp_duration` starts a new epoch on its next grant, while a\nshorter idle gap continues the existing one.\n\nEnabling the ramp while a group\nalready has in-flight work anchors its epoch at the current occupancy, so\nrunning streams are not stalled. Changing the flag, duration or concurrency\ntarget resets every group's epoch.\n\nHeader updates change only the three cap\ndimensions and preserve the stored anti-burst pair. Clearing the last active cap\ndrops the whole policy, ramp included. The limit composer carries the checkbox\nand the ramp chips; applying sends both, and a form whose caps are all zero\nsends the pair off rather than an invalid on-ramp.\n\nOperator limit edits persist synchronously and report a warning when the store\nrejects the write. Header-driven limit changes apply in memory immediately and\nare persisted by one coalescing background writer: a burst of changes becomes\nthe latest whole-policy document, with bounded retry and backoff after a store\nfailure. A closed store is not retried - the generation stays dirty and the\nwriter stops - while a busy one keeps the ladder. That document also carries\nthe anti-burst pair, and one written before\nthose fields restores them off.\n\nA crash can therefore lose the most recent\nheader-driven changes, and a failed save never rejects inference. Graceful\nshutdown and restart flush the latest policy before storage closes or the\nrestarted process opens the database. Provider labels are capped at 255 bytes\nand the persisted throttle document at 8 MiB; normal provider labels derived\nfrom base URLs remain below both bounds.\n\nAdmission is bounded end to end.\n\n- `max_inflight_requests` is the process-wide\n  inference ceiling (default 10000).\n- `max_inflight_body_bytes` is its buffered\n  body budget (default 256 MiB; admission charges the allocation hint, the\n  declared length bounded by `max_request_bytes` and the read hint, and reconciles\n  it against the bytes actually read, so a short body refunds the difference and a\n  chunked one is charged as it arrives).\n- `max_inflight_response_bytes` is its\n  budget for buffered upstream response bodies (default 256 MiB): whole-document\n  translation of non-streaming responses, the non-streaming 200 quality spool\n  (at most 1 MiB plus one 32 KiB chunk), and model discovery.\n\nA request-slot refusal is answered with `503` and `Retry-After` before the body is read.\nThe body budget charges the allocation hint at admission and reconciles it\nagainst the bytes actually read; when the hint cannot be covered the slot is\nstill taken, and the first read decides without retaining the upload. The\nper-request cap still owns the status: a refused request drains at most the\nremaining `max_request_bytes` window so an over-cap body answers the definitive `413` instead\nof a retryable `503`, while a body that fits the cap answers `503`.\n\nRequest-body reads must make progress within\n`request_body_idle_timeout` and finish within the absolute\n`request_body_read_timeout`, so a stalled peer releases its reservation\nwithout cutting off a slow but progressing upload. The `POST /admin/restore`\nupload is exempt from the absolute bound only: a full database archive can\nlegitimately outlast it on a slow link, while the idle bound still cuts a\nclient that stops sending, and an expired deadline answers `408` with its own\nmessage instead of the archive-cap `413`.\n\nBuffered whole-document\nresponse reads use `whole_document_read_timeout` when the send has no deadline\nand `whole_document_read_max` as the ceiling even when `X-Proxy-Timeout-Ms` is\nlonger, so a slow or stalled body releases its response-buffer reservation; a\nshorter caller deadline wins and configuration validation preserves the\n`models_discovery_timeout` budget below the ceiling. The three admission\nbudgets accept `0` = unlimited and hot-reload.\n\n`max_queue_size` (default 1024\nper group) and `max_queue_wait` (default 10m) bound a held or saturated\nprovider's parked work; both accept explicit `0` = unlimited. Independent\nper-key/header concurrency remains unlimited by default.\n\nThe scheduler retains at most 100000 distinct provider+key groups, evicting\nthe least-recently-idle group (no in-flight or queued work) to admit a new\nkey at the bound; a new key is refused only when every retained group has\nactive work, so a table full of active groups still fails closed. Recent\npacing/backoff state for evicted groups is kept in a separate 4096-entry\nbounded LRU. The scheduler also retains at most 4096 header-created provider\nlimits, refusing new ones past that bound rather than growing process memory\nwithout limit.\n\nA new request body has the `request_body_read_timeout` budget, SSE writes have the `sse_write_progress_timeout` per-event\nprogress bound, and an upstream body that stops sending for `upstream_stream_idle_timeout` is canceled.\n\nRequest budgets are strict sliding windows: at most the configured count is\nadmitted in any trailing window of the configured length, so an idle provider\nbanks nothing and a busy one cannot spend future allowance as a present burst.\nCharging the window is what makes the limit match a provider that counts\nrequests per rolling or fixed minute; a refilling budget could emit the whole\ncount in one instant and then refill through the same span, which is how a\n`100 per minute` setting reached a provider's `101/100`.\n\nEach admitted request is charged once, at proxy admission, not again for\neach absorbed upstream retry. A count above 65536 is enforced by even\nspacing at the same ceiling instead of one timestamp per slot, so the memory\na window holds stays bounded.\n\nToken budgets remain refilling buckets: prompt tokens are reserved from the\ncaptured characters divided by four and then settled against final reported\nusage, and a reservation larger than the whole capacity may proceed while\ncredit is positive, leaving debt that refill or settlement repays. The\nclient's output ceiling (`max_tokens` and its spellings) is deliberately not\nreserved: it is a ceiling, not expected usage, and reserving it would turn\nthe token budget into a worst-case concurrency cap.\n\nA token budget therefore also sets the sustained\naverage rate: 500K tokens per 6h refills at about 23 tokens/s, so once the\ninitial budget is spent, later requests wait for refill unless actual usage\nsettles lower than the reservation.\n\n### Error storm protection\n\nOpen Settings, select **Error storm protection**, and turn on **Enable\nprotection**. It is opt-in in both neutral defaults and the deployment example.\nChoose the rolling window, minimum samples and failure threshold, then select\nHTTP failure statuses, transient transport failures and response/stream failures.\n\nProvider protection requires all models receiving requests in that same window\nto meet the thresholds individually. A single affected model is held on its own\nwhile other active models remain healthy. If only one model is active, that\nmodel can establish a provider-wide incident. Provider and model protection can\nalso be enabled independently.\n\nConfigure initial/maximum recovery delays, multiplier, jitter, recovery successes,\nadditional retries, queue capacity, per-wait timeout and retained scope capacity\nin that category. The generated [example](../proxy.example.yaml) supplies every\ntype, range and default. Existing Queue & retry limits and provider Limits still\napply; neither `storm_max_wait` nor a per-send deadline is a total request timeout.\nUse a client timeout appropriate to the desired end-to-end wait.\n\nEach clickable banner identifies its current scope and safe failure\ncategory (HTTP status, transport error or response error), percentage/count of\nfailed upstream attempts, detection window, queued callers and next probe or\nrecovery progress.\n\nOpen an incident to inspect the distinct requests that\nencountered a selected failure, failed attempts, total sampled attempts, error\ncategory, queue count and next retry time. Provider entries also show affected\nversus active models.\n\nDistinct request counts follow each request's latest selected failure in the\nrolling window, so repeated retries do not inflate that count. The percentage\nstill describes upstream attempts. These are process-local observations, refreshed\nthrough the normal dashboard bootstrap/poll cadence; they are not chart history or the\nErrors chart's distinct-request percentage. Scope counts can overlap where a\ncaller waits on both provider and model protection. Hide the banner independently\nwithout disabling protection.\n\nChanging a storm policy resets its samples/incidents and wakes waiters to\nre-evaluate the new policy. Banner visibility alone preserves detector state.\nA reset does not cancel work already sent or erase request history. Restart\nstarts detection afresh, and queued requests do not persist. History deletion\ndoes not reset live outage protection.\n\nStorage stays outside the detector: fixed 64 time buckets retain counters per\nscope, with oldest-edge precision within approximately `storm_window / 64`.\n`storm_max_scopes` includes provider aggregates and exact provider/model scopes;\nstale unreferenced healthy scopes can be evicted, while active or referenced\nscopes remain protected.\n\nScope identifiers over the internal 512-byte retention\nbound and exhausted scope capacity reject admission rather than silently bypass\nprotection. These bounds are not a total heap ceiling: waiting callers retain\nbounded request bodies, and existing ordinary queues remain separately sized.\nThe [protocol guide](protocol.md#error-storm-protection) defines retry safety,\nquota exclusions, native handshakes and client-facing failures.\n\n### Quota pause\n\nOpen Settings, select **Quota pause**, and choose the reaction to a 429 whose\nerror envelope is a durable account condition - `insufficient_quota`,\n`insufficient_credits`, spend/hard limits, the recognized numeric billing codes\n(the built-in classification is fixed and `quota_error_classes` may add\nspellings; only the reaction is configurable):\n\n- **off** (default): the 429 surfaces to the client immediately. Nothing is\n  parked or retried.\n- **retry**: a provider-wide recovery gate opens on the first such 429 from an\n  OpenAI-wire provider. The triggering request absorbs the 429 and re-sends\n  per the error storm recovery delays; every new request to the provider\n  parks on the gate (bounded by `storm_max_queue` and `storm_max_wait`); the\n  gate closes after `quota_pause_recovery_successes` consecutive successful\n  probes (the default 1 closes on the first 2xx) and the queue drains. A provider\n  `Retry-After` on the quota 429 paces the next probe like any other 429.\n- **manual**: an indefinite provider-scoped pause (an operator hold labeled\n  with the quota class) is created automatically; every request, triggering\n  one included, queues until an operator resumes it on the pause surface.\n  When a pre-existing hold already covers the provider, no duplicate is\n  created: the triggering request queues under that hold only if it parks\n  the triggering client too, and a hold that parks other clients only lets\n  the triggering request surface the 429 immediately.\n\nThe retry-mode gate shares the storm scheduler's parking, probes and pacing,\nso storm recovery settings configure it without storm protection being\nenabled. It surfaces in the storm banner as a quota incident with a\n**Resume now** action (`POST /admin/quota`); manual-mode holds appear on the\npause surface with their reason and resume like any hold, and they derive their\nprovider pin through the same commit owner as a manual pause so the provider\nstays offered in the scope pickers.\n\nA quota 429 never arms the rate-limit pacing trip (the rate-limit health\nseries still counts the 429 itself), and quota re-sends never burn the\ntransient `max_retries` budget. They are bounded by `storm_max_wait` instead, measured from the\nrequest's first park: when it expires the client receives the canonical\nretryable `error storm protection: ...` 429 rather than waiting on a gate that never opens, and the\nprovider stays parked for the next request.\n\nThe retry gate is in-memory - a restart drops it and\nthe provider's next durable quota 429 re-arms it - while manual-mode holds\npersist like every operator pause. In-band occurrences (the same envelope\ninside a 200 stream) arm the pause the same way; that request already\nanswered, so it is never parked.\n\nTranslated Anthropic-format and Cursor\nupstreams keep the off behavior in every mode. The built-in vocabulary is\nfixed; `quota_error_classes` may add a gateway-specific spelling as a durable\nquota class (it may never move a built-in spelling between classes, and it\nre-reads stored history through the same vocabulary).\n\n### Debug and preview capture\n\nDebug selects clients, providers and/or models and starts a capture session for\na chosen duration or until stopped. At least one dimension is required; selected\ndimensions intersect, with alternatives inside each dimension. It does not have\nan unrestricted \"all\" switch. Sessions can be edited or stopped individually;\nStop all ends every active session. A stop carries only `enabled:false` and an\noptional session `id`; a scope or duration beside a stop is a 400 rather than a\nsilent stop-everything. Conflicting scopes are rejected.\n\nDebug model matching uses the native-model normalization in\n[debug.go](../internal/proxy/debug.go), separate from display-only model rules.\nDo not assume that every model spelling is an independent exact scope.\n\nThe session timer selects future captures. `debug_capture_ttl` separately\ncontrols retained capture lifetime after completion, and\n`debug_capture_max_bytes` bounds one capture document: retained headers are\ncharged first and the remainder is split between the request and the\nclient-facing response body. Oversized captures are marked truncated.\n\n`debug_store_max_bytes`\n(default 512 MiB) caps the whole capture sidecar; once the next write would\nexceed it, new captures are skipped and TTL expiry frees capacity again.\nCapture writes are counted in bytes, not characters.\n\nThe request drawer loads an\navailable sidecar only for a captured request; expired/absent captures are not\nrecreated from ordinary metrics. Completion is published before the sidecar is\nencoded and saved, so a slow sidecar write delays neither the live end nor\ndurable accounting. A drawer fetch that follows the live end waits for that\nrequest's in-flight save instead of answering a transient 404; a disconnected\nclient stops waiting.\n\nStarting a capture requires durable storage. With `db_path` empty,\n`enabled:true` without an ID answers 503 `durable storage is disabled` and\ncreates no session. A store-less process\nalso has no persisted session document to restore, so it never starts with an\nenabled session; if one were present in memory, the request path still refuses\nto build a capture tap, so no headers or bodies are retained for an unfetchable\nsidecar. Editing or stopping a named existing session remains available.\n\nRetained request headers use the same policy as recorded response headers:\n\n- names are visited in sorted order for the budget;\n- each value is capped at 4 KiB and marked with `…` when cut;\n- at most 16 values are kept per name;\n- ordinary headers share a 16 KiB total budget per header map;\n- a header name is capped at 512 bytes;\n- at most 256 names are retained per map.\n\nA longer name or an extra\nname is omitted without a marker, exactly like a value beyond the budget.\n\nCredential headers (the\nconfigured auth header, `Authorization`, cookies, and token-, API-key- or\nsecret-bearing names) become `[REDACTED]` before any truncation, so a cut\nvalue is never a credential prefix. Headers or values beyond the budget are\nomitted without a marker; the capture schema has no header-truncation field.\nThe capture JSON is encoded without HTML escaping, so `<`, `>` and `&` appear\nliterally while JSON control escapes remain.\n\nThe drawer's Debug section also carries a Download button. It fetches the same\ncapture with `download=1` and saves a gzip artifact named\n`millivolt-debug-<captured_at>.json.gz`, using the record id in the name when\nthe capture does not carry a readable `captured_at`.\n\nCaptured request and response bodies render through the same bounded code\nsurface as record previews, with wrap, copy and expand controls; the\nDownload button remains the whole-capture path. The capture cards also\nsurface its schema and captured-at time, conversation and key correlation,\nfirst-answer timing, usage, cost and attempt count.\n\n`capture_body_preview` is a different opt-in feature: it retains short prompt/\nresponse previews in the normal record without starting a Debug session. The\ntwo features also retain different request bytes: on the passthrough wire\nthe record's prompt preview is the client's original body, captured at the\nmetadata decode before `request_overrides` or the sub-conversations strip\nrewrites it, while a debug capture's request body is the rewritten upstream\nbody sent after any rewrite.\n\nA translated Chat Completions or Anthropic target\nre-decodes the translated body for its prompt preview; a translated Responses\ntarget keeps the client-body prompt preview, because the generated item list is\nnot re-decoded for preview. The response preview follows the client-facing\nresponse content on every target.\n\nBoth features can retain sensitive content\neven when credential headers are redacted.\nExports/backups can outlive the configured retention period. See\n[Security](../SECURITY.md#upstream-destinations-and-credentials).\n\n### Export and deletion\n\nThe operator console's export section downloads finalized request records as\nJSON, not the process's stderr log and not a complete administrative audit\ntrail. With durable storage it reads the database; otherwise it uses available\nring records.\n\nOpen export, choose either all history or matching records, and\nreview the previewed count before downloading.\n\nProvider, model, client and\nconversation merge the server's known vocabularies with whatever the live record\nring holds, so a quiet proxy can still filter by what has run since it started,\nand each of them also accepts a typed value. Status is the one list-only\ndimension, because a status code is not a name anyone can type reliably. A\ndebug-only export can include retained capture sidecars.\n\nA debug capture is written beside its record as a `debug_capture` member, and\nonly when the row still has a stored sidecar. The artifact therefore carries\ndebug bodies only while durable storage is live: a ring-record export, or a\nsidecar already reclaimed by the capture retention sweep, has the record alone.\nThe bodies remain sensitive either way.\n\nThe export predicate has no constraint for `status_code=0` and `debug=0`; both\nare off rather than a match for the zero status or the false flag. A\ngenuinely bodyless `POST /admin/purge` deletes everything in one call, which is\nwhy a mistyped query key is refused instead of silently ignored.\n\nThe download is always a gzip artifact named `millivolt-logs-<timestamp>.json.gz`;\ngunzip it to read the JSON array of records. Compression is applied at the\nexport writer itself, so every export shape (filtered, all or debug-only,\nfrom the ring or durable storage) downloads compressed the same way. This is a\nbreaking change for scripts that consumed the plain JSON download: there is\nno uncompressed fallback, so scripted consumers must decompress the artifact\nfirst.\n\nA durable export holds one read snapshot for the whole stream, so the server\nbounds it with an internal total budget. If the budget expires after bytes were\nwritten, the download is aborted mid-artifact instead of completing as a\nsuccessful gzip: the saved file is partial and must be discarded. A caller\ncancellation or shorter caller deadline is reported separately from this\nserver budget.\n\nIn the dashboard, both database deletions live in Settings, in the storage\ncategory, and nowhere else. Delete matching uses the same filter/count owner\nas the export, and its scope is the chosen filter; Delete everything wipes\nthe whole database. Deletion requires confirmation in the dashboard; it does\nnot happen when the sheet opens.\n\nA selected filter makes a read-only\n`POST /admin/purge/count` preview; the count first commits the writer's queued\nbatch into the read view, so a just-finalized request cannot read as empty.\nThat barrier is bounded by the query timeout: a wedged writer lets the preview\nanswer from the committed snapshot instead of spinning the sheet forever, and\nthe delete's transactional re-check stays the guard.\n\nNeither the caller's deadline nor a client cancel fails the preview, even\nwhen it expires before the barrier does: each step runs detached on its own\nquery budget, so a short dashboard deadline answers the same as an unbounded\none.\n\nA ring-only deployment removes through the boundary the count saw, so a\nrecord that finalizes during the delete stays behind instead of disappearing\nuncounted.\n\nCurrent traffic can still change the count\nbefore the action, but the UI retains the previewed age cutoff rather than\nsilently moving it, and sends the rendered count with the delete so the\nproxy re-checks it inside the delete transaction and refuses a moved row\nset with 409 instead of deleting unpredicted rows.\n\nA 409 drops the sheet's\npreview and re-counts, so the operator confirms the new set instead of\nrepeating the refusal. The filter selections reset every time the sheet\nrefills, so a stale invisible filter never arms a destructive default.\nBoth actions are irreversible without a backup.\n\nEvery purge, backup and restore writes one audit line to the process log with\nits terminal outcome, before the response is written: the action, the rendered\nselection (`filter=\"all\"` for a bodyless full delete, `filter=\"unparsed\"` while\nthe body or query has not been accepted, and `members=\"unparsed\"` likewise for\na backup/restore), the previewed count when\none was supplied, and the committed `deleted` / `buffer_removed` counts, or the\nerror.\n\nEven a rejection at the method gate or the query grammar, before the\nselection exists, leaves a line. Each value is quoted with Go string escaping,\nso a label carrying a newline or a quote stays one token on one physical line. A\nlost or truncated response therefore stays diagnosable, and a\nretry can be compared against what was actually attempted. These lines are the\ndestructive-action trail; they are not a general request log.\n\nExport/delete filters are exact raw record fields, not display-name model\ncanonicalization. The API also supports conversation/error-type/time filters\nbeyond the console's common choices. See the shared\n[filter decoder](../cmd/proxy/log.go) and\n[PurgeFilter](../internal/storage/purge.go).\n\nEmpty-body full deletion is\ndeliberate and destructive; never use malformed or empty JSON as an all-records\ncommand. The count preview applies the same empty-filter rule, so `{}` answers\n400 on both routes rather than counting the full set for an ambiguous body; a\ngenuinely bodyless count previews the whole set, exactly like the bodyless\ndelete.\n\nThe delete fence preserves newer completions and in-flight work. A completed\npurge, and an expired debug-capture sweep, checkpoint-truncates the WAL after\nthe committed delete: `secure_delete` zeroes freed cells in the pages SQLite\nwrites, and the checkpoint removes the pre-delete frames that would otherwise\nkeep the old page images readable in the `-wal` sidecar. A reader holding an\nolder snapshot can defer the checkpoint; the writer's near-term tick retries it\nwhile the reader is gone, and a clean shutdown makes the final attempt after the\nread pool is closed.\n\n### Settings and Restart\n\nSettings only reads configuration when opened. Its search, category rail and\nstructured editors work on a local draft; Apply uses the\n[revision-checked save contract](configuration.md#saving-settings-safely).\n\nThe console's system section reads restart availability and status when opened.\nThe restart action is disabled while a restart is in progress or rebuilding is\nunavailable. Progress reports actual build/drain/flush/handoff phases; it is not\na simulated timer. After a successful handoff, reconnect/bootstrap refreshes\nhistory, aggregates, operator state and config. Changed embedded frontend assets\ntrigger a page reload through that same refresh owner. The\n[lifecycle section](containers.md#reload-restart-and-shutdown) distinguishes source rebuilds\nfrom container replacement and ordinary shutdown.\n\n## Dashboard data and request inspection\n\nThe KPI band is global. Explorer selections and the request status filter scope\nthe timeline and request log; selecting a card adds a filter and entity links\npivot within that shared route. Browser back/forward restores hash-based scopes.\nChart preset, timeframe, percentile and series visibility persist in browser storage.\nThese saved views are local browser state, not shared server settings.\n\nThe In-flight tile separates work that is sending from work the scheduler is\nparking. Its summary names the two totals that fit the narrowest tile - active\nand queued - and the composition rail under the value splits every live state\n(sending, pending, operator-paused, throttled) by color; hovering the rail, or\nfocusing it with assistive technology, reads the exact per-state counts.\n\nA queued request is one the proxy has not sent upstream yet: it can be\nwaiting in the admission queue (per-key concurrency, pacing, a provider cap\nor an operator hold) or in the retry send gate behind a 429/5xx pacing\nwindow. The request table marks the same state with the `throttled` pill, and the\nstatus selector can filter on it.\n\nExplorer dimensions are Providers, Models, Client, Conversations, Tools, Time,\nStatus, Errors and Keys. Their meanings are server-owned: model grouping and\ntime-bucket membership are not browser guesses. Conversations can show declared\nparents and main/sub/unresolved counts; read the\n[lineage contract](protocol.md#main-and-sub-conversations) before interpreting them.\n\nTools and error signatures can each have multiple memberships per request.\nTool cards count affected requests for N and share, with request-level card\nmetrics counted once per affected request; their calls KPI separately sums\nrequest ToolCalls, so repeated same-name calls do not inflate the request count.\nA request using several tools contributes to each tool card. Error/429 health\nbadges and every gallery share use distinct affected requests.\n\nThe [visual guide](dashboard.md) covers every timeline and its controls.\n\n- Overview\n  is the summary: it carries no plot, and its tiles take the whole card (requests\n  over the blended token volume, tokens in/out/cached with their shares, spend\n  with the blended per-Mtok price, the errors / 429 pair, and average latency /\n  speed over every measured request with each metric's low-high sample range).\n- Traffic compares requests/errors.\n- Tokens separates available input/output/reasoning/cache\n  usage and tracks the cache-hit share of input on a percentage axis.\n- Speed + latency\n  plots throughput on its own axis with TTFT and the decode window (first token to\n  last, the span decode speed measures) sharing a duration axis.\n- Errors compares\n  error count/rate.\n- Cost places reported USD spend beside request volume.\n\nOne percentile selection controls the timing series (the Overview keeps only\nthe timeframe control). Period readouts are computed from period samples,\nnot averages of bucket percentiles. Insufficient samples remain unavailable.\nAll time means the available retained history, not deleted, dropped or\nnever-observed requests, and the timeframe control never offers a window\nwider than it.\n\nThe chart endpoint takes either a minute `window` (or\n`all`) or an explicit `from_ms`/`to_ms` pair for calendar ranges; each payload\nreports the resolved right edge `to_ms` and the unscoped `data_from_ms` extent\nthe control gates on.\n\n### Request rows and details\n\nThe log starts with recent rows and pages older durable records as you scroll.\nLive rows show in-flight/queue/retry progress; final rows retain their outcomes.\nRetry disclosure opens absorbed attempts under the original request, not another\ninference record.\n\nThe attempts log keeps the newest `max_retries` plus\n`storm_max_retries` entries (at least one): a durable quota wait re-sends\nwithout spending either budget, so the tail is what explains a long parked\nrequest.\nClick the detail arrow or a non-link row cell to open its\ndrawer; previous/next controls navigate requests without changing the scope.\n\nThe inspector presents available facts in four classified groups.\n\n- Request covers\n  identity/status/times, time bucket, wire sizes, client/runtime, provider metadata,\n  model and captured parameters.\n- Content covers conversation and parent ids, turn\n  and size composition, and prompt/response previews.\n- Usage covers token splits,\n  generated tokens, timing, throughput, cost, transport decomposition and tools.\n- Diagnostics covers queue/rate limits, retries, in-band upstream responses,\n  retained headers and Debug.\n\nA summary readout carries the status, route, identity\nand first numbers, and a final upstream failure renders as an error alert above\nthe groups. Only the selected group is shown; card headers collapse, and the\nactive group and collapse choices survive live updates.\n\nA typed 429 is flow control, so its reason, code and message stay in the\nrate-limit card instead of the error alert; a rate limit carried by a non-429\nstatus is a final failure and renders the alert like any other.\nAn in-band upstream response that arrived after a committed success is disclosed\nin Diagnostics rather than counted as a retry. Live pause and throttle state\nappear as explicit rows while a request is in flight.\n\nCopy actions cover the values that matter (identifiers, paths, models, headers,\nerror detail and captured bodies), field-list cards and the header's JSON\naction. One clipboard path reports success or denial in a polite status line.\nLong captured bodies use a bounded code surface with line count, wrap, copy and\nexpand controls; a long single line scrolls inside that surface instead of\nwidening the inspector. Narrow viewports get the full-width inspector with keys\nstacked above values and touch-sized copy and close targets.\n\nRecognized parameters include sampling and output limits, stop/logprob controls,\nreasoning/verbosity, response format, tool choice and streaming flags. Explicit\nzero/false parameters remain distinct from absent ones. Ordinary HTTP relay\nmetadata does not infer missing parameter defaults. Adapters differ: Anthropic\nmetadata comes from the translated body, including its configured output-limit\ndefault, and Cursor stores the base model ID rather than its fused spelling. See\n[adapters](adapters.md) before treating these fields as an exact representation\nof the caller's original request.\n\nOpening ordinary details does not fetch private request content. Prompt/response\npreviews appear only if captured, and Debug sidecars use their separate opt-in\nand retention contract. Even ordinary labels, error text and headers can be\nsensitive; do not publish request drawers from private history without review.\n\n### Reading timing, cost and health\n\nRequest duration starts after upload and includes metadata work, queue/hold/retry\nwaits and response handling. TTFT is measured from the upstream attempt's own\nsend start to the first token (reasoning or answer), so every retry has its own\nTTFT. The value excludes proxy scheduler queueing, request parsing and retry\nbackoff, but it does span the upstream transport window from request handoff\n(dial, TLS, connection-pool wait, header wait).\n\nA request that produced no\ntoken, one that never sent an upstream attempt of its own (a parked cursor\nresume), and any non-streamed response have no TTFT: the log shows a\nplaceholder, not 0 ms, and aggregates skip it.\n\nRows written before 0.3.34 stored `ttft_ms` anchored at request start (upload,\nqueueing and retry backoff included) and were zeroed once by the boot\nrepair, so they report TTFT as absent; their `started_at` and `first_token_at` timestamps remain,\nkeeping `pre_token_ms` and decode windows usable.\n\nTPS is the single generation-speed measure: (generation tokens - 1) over the\nfirst-token to last-token window. Average TTFT and average TPS are the\narithmetic means of those per-request samples. TPS is absent for fewer than\ntwo tokens, a non-positive window, or a response that did not stream (no\ntoken timestamps). The compact surfaces (the KPI band and the Overview\ntiming tile) abbreviate this unit as `t/s`; roomier readouts spell it `tok/s`.\n\nThe numerator assumes the first observed content chunk carries one token; a provider that bundles several tokens into that chunk can\nstill overstate the rate. These are provider-attempt measurements, not claims\nabout total user wait or system-wide throughput.\n\nMoney stays USD in storage and APIs. The shared UI formatter uses cents below\n$1, including fractional cents, and dollars for larger magnitudes.\n\nUsage/cost comes from recognized upstream fields or configured field\nmappings; unavailable reporting and a displayed zero do not establish a zero\nbill. Reasoning/cache splits depend on what the upstream actually reports.\n\nWhen a stream carries no\nusage object, or carries one whose output count is zero, the recorded output\ntoken count is restored from the streamed chunk count, which includes\ntool-argument fragments; the count is an estimate, not a provider report.\n\nChat tool calls are deduplicated by delta index while the retained index set\nholds up to 1,024 distinct indexes. Once the set is full a further index\ncannot be retained, so each of its fragments counts again; a hostile stream\nof repeated indexes can overstate the tool-call count without growing memory\npast the bound.\n\nErrors count affected requests with a genuine failure, including recovered\nupstream failures. Rate limits count requests that saw a rate-limit class on\nthe final, a retried or an in-band attempt: an HTTP 429, a 429 whose status\nline a committed 200 could not relay, or a provider spelling the classifier\nrecognizes (such as `tier_limit_exceeded` on a 400); each request counts once.\n\nThe two signals can overlap: a bare 429 is not an error, but a non-429 status\nthat carries a rate-limit class failed the request and counts in both.\n\nClient-local cancellation is likewise distinct from an upstream failure -\nexcept a 499 whose record carries a structured error type: that observed a\nfailure before the client left, either the provider's in-band stream failure\n(typically an error event the client received and aborted around) or a\ntruncated stream whose completion marker never arrived, independent of which\nrelay write failed. It counts as the upstream error it is.\n\nZero explorer health badges are hidden independently. Error-dimension card\nheadlines count failure events (final plus absorbed), while card N counts\ndistinct affected requests.\n\nThe gallery share denominator `error_total` is the\nunion of affected requests represented by the error cards, so a card's share\nis N / `error_total` and can never exceed 100%. This denominator includes\nrecovered quality failures whose final status is not an error (for example an\nabsorbed empty-completion attempt), counting each affected request once even\nwhen no request ends in an error status. For every other dimension\n`error_total` remains the canonical affected-request error count. Do not treat\nevery displayed error number as the same metric.\n\nThe explorer gallery renders at most 24 cards. Its fold tracks exact\nper-value accumulators for at most 8192 distinct values in the active\ndimension; later values are combined into a synthetic `other` card with\naggregate count, cost, token, tool and health fields, competing for the 24\ncards by that count.\n\nThe synthetic card carries `synthetic: true` on the wire,\nrenders as `other (grouped)`, and is not filterable. A real value named `other`\nkeeps its own exact card and filter; `other` is a display bucket only when the\ncard is synthetic.\n\nRail distinct-value counts, footer scope totals and\nconversation summaries still cover the whole filtered history, so card counts\nneed not add up to them.\n\n### Snapshots, live feeds and monitoring\n\nThe HTML includes the canonical bootstrap state so the first paint need not wait\nfor a second state request. Live SSE carries pending progress and finalization;\nKPI/operator polling and configured aggregate refresh keep derived surfaces current.\nReconnects use sequence/feed identity and fall back to full snapshots when replay\ncannot be trusted.\n\nThe footer distinguishes live/offline, active holds/Debug,\nprocess-local storage drops, totals degraded by a failed startup history scan,\nand a degraded operator-state restore.\n\nThe last one is the difference between\n\"nothing is held\" and \"a saved hold or limit document could not be read\": the\nserved `pause` and `throttle` snapshots carry `restore_degraded`, so a truncated\ndocument does not boot as a healthy, unpaused proxy with its saved rules silently\ngone. The flag stays true for the life of the process; a restart that reads a\ndocument which decodes is what clears it.\n\nEach key holds one value, so the next\naccepted operator write replaces the unreadable document rather than preserving\nit: capture the bytes first if they are needed as evidence.\n\nAn offline indicator alone does not prove inference is down. None of these\nmechanisms makes initial history preload instantaneous.\n\nFor integrations, use the documented read routes rather than scraping the DOM.\nBootstrap/live data is a recent observation window; scoped aggregate routes query\navailable history; JSON export provides finalized records; restricted SQL queries\ndurable data within configured time/output limits. The API is in initial\ndevelopment, so pin and verify the selected revision for integrations.\n\nPrometheus is a bounded-ring view. Its request/token/error totals are gauges that\ncan shrink after eviction, purge or restart, not monotonic lifetime counters;\ndo not apply counter-only `rate()`/`increase()` assumptions to them. Its TTFT\nquantiles use the ring's sample contract, which differs from dashboard R7 history\npercentiles. Metric names and units are exposed with HELP/TYPE metadata at\n`/metrics/prometheus`; [prometheus.go](../internal/metrics/prometheus.go) owns them.\nAn unchanged finalized ring revision serves the exact last exposition without\nanother ring copy, aggregate or TTFT sort; any ring content transition rebuilds.\n\n### Operator recipes\n\nThe gated query route (`GET /metrics/query?q=`, above) and the [MCP](mcp.md)\n`query` tool both take exactly one `SELECT` with no statement separator, and\nresults are bounded by `storage_query_max_rows` and\n`storage_query_max_bytes`; an over-budget result is an error on the route, so\nkeep wide scans behind a `started_at` window or a `LIMIT`.\n\nThe statement gate also denies the read-only capabilities SQLite exposes\noutside ordinary tables and columns: `ATTACH`, `DETACH`, `PRAGMA`, `LOAD_EXTENSION`, the `sqlite_dbpage` and `dbstat`\ntable-valued functions, the whole result-bearing `pragma_*` family and the `readfile`/`writefile`\nfunctions. Those would read raw pages, page statistics or the absolute\ndatabase path, which is not part of this console's surface.\n\nThe denial is lexical over the raw query text, string literals included, so a\nkeyword spelled inside a literal is refused too: `SELECT 'attach' AS x` and\n`SELECT 'pragma_table_info'` both fail. A name only has to contain the bare\nword at an ASCII boundary; `attachment` and `attach_x` pass.\n\nThe driver executes a multi-statement string wholesale, returning the rows\nof the last statement, so both rules are load-bearing: without the `;`\nrefusal a second `ATTACH` statement would run behind a `SELECT` prefix the prefix\ncheck accepts, and the keyword scan alone would not see it.\n\nColumn meanings come from the MCP `describe` tool. `started_at` is Unix milliseconds: a\nrelative window is `started_at >= strftime('%s','now')*1000 - 3600000`, and calendar math divides by 1000 and applies\nSQLite's `unixepoch` modifier, with `localtime` for the host's zone.\n\nThe recipes below earn their keep in\nthe derived shapes no dashboard surface computes: the outlier ratio, the\nwrite/read ratio, the latency decompositions. Their ingredient aggregates\nare conceded up front, the way the decode window already is: the explorer\nsums per-group counts and cache reads (its `N` and `Cache` fields) and a\nper-group blended $/Mtok (its `cost_per_mtok` KPI, the same cost-reporting\nin+out rule), and the chart's dec series samples the shared decode window\n(`last_token_at - first_token_at`) that recipe 1 decomposes latency\naround.\n\nSeveral of the columns a recipe reads do overlap the aggregate\nscans: `ttft_ms`, `reasoning_tokens`, `status_code`, `attempts`,\n`output_tokens` and `cache_read_tokens` all appear in the dashboard's scan\nlists. The recipes' private reading set, which no aggregate scan reads, is\n`queue_wait_ms`, `first_answer_at`, `retry_after_ms`,\n`cache_write_tokens`, the `chars_*` columns, `total_tokens`,\n`req_max_tokens`, `duration_ms` and `retries`. Each recipe is a\nquestion, the SQL that answers it, and how to read the result.\n\n**Where did the time go on a slow request?**\n\n```sql\nSELECT started_at, duration_ms, queue_wait_ms, retries,\n       first_token_at - started_at AS pre_token_ms,\n       ttft_ms,\n       last_token_at - first_token_at AS decode_ms,\n       started_at + duration_ms - last_token_at AS tail_ms\nFROM requests\nWHERE started_at >= strftime('%s','now')*1000 - 3600000\n  AND first_token_at > 0\nORDER BY duration_ms DESC\nLIMIT 20\n```\n\n`pre_token_ms` is the wait the caller felt, including queue and retry waits;\n`ttft_ms` is measured from the adopted upstream attempt's send start, so a\nretried request shows a small ttft beside a large `pre_token_ms`.\n\nRows written before 0.3.34 carry a start-anchored `ttft_ms` and were zeroed once\nby the boot repair, so their `ttft_ms` reads 0 (absent) while `pre_token_ms` and `decode_ms` stay\nusable from the stored timestamps. `decode_ms` is the streaming window and `tail_ms` what\nremains after the last token, where a millisecond of rounding noise is\nnormal. A request that produced no token, or was not streamed, has nothing\nto decompose, hence the `first_token_at > 0` gate.\n\n**How long did a model think before answering?**\n\n```sql\nSELECT started_at, model, reasoning_tokens,\n       first_answer_at - first_token_at AS thinking_ms\nFROM requests\nWHERE started_at >= strftime('%s','now')*1000 - 3600000\n  AND first_answer_at > 0\nORDER BY thinking_ms DESC\nLIMIT 20\n```\n\n`thinking_ms` spans the first token of any kind, reasoning included, to the\nfirst answer token; 0 means the first token already was the answer.\n`first_answer_at` is streaming-only on the generic relay; cursor-format\nnon-streaming requests set it (the bridge synthesizes each delta and tracks\nit via cursorTrackDelta), and such rows legitimately enter the gate because\n`first_token_at` is stamped by the same helper. Tool-call-only streams keep\n0 and stay outside the gate.\n\n**How long does an agent idle between conversation turns?**\n\n```sql\nSELECT conversation_id, started_at,\n       started_at - LAG(started_at + duration_ms)\n         OVER (PARTITION BY conversation_id ORDER BY started_at) AS idle_ms\nFROM requests\nWHERE started_at >= strftime('%s','now')*1000 - 86400000\n  AND conversation_id != ''\nORDER BY conversation_id, started_at\n```\n\n`idle_ms` is the gap between one request's end and the next request's start\ninside the same conversation; the first turn has no predecessor and stays\nnull. Order by `idle_ms DESC` instead to surface the biggest stalls first.\n\n**What retried before the client saw a response?**\n\n```sql\nSELECT r.started_at, r.id, r.retries, r.status_code AS final_status,\n       j.value->>'status_code' AS attempt_status,\n       j.value->>'at' AS attempt_at,\n       j.value->>'retry_after_ms' AS retry_after_ms\nFROM requests r, json_each(r.attempts) j\nWHERE r.started_at >= strftime('%s','now')*1000 - 86400000\n  AND json_array_length(r.attempts) > 0\n  AND COALESCE(json_extract(j.value,'$.in_band'),0)=0\nORDER BY r.started_at, j.key\n```\n\nOne row per absorbed retry, oldest first. The `in_band` filter excludes a 429\nrecorded behind a committed 200: that entry is health evidence, not a retry.\nThe `json_array_length` gate is required: `attempts` defaults to the JSON\nliteral `null`, and `json_each` over that literal still yields a row. `retry_after_ms` appears (nonzero)\nwhen the provider sent a `Retry-After` header or a ratelimit-reset header\n(`x-ratelimit-reset-requests`/`-tokens`, `anthropic-ratelimit-requests-reset`,\n`anthropic-ratelimit-tokens-reset`), bounded by the proxy's hint ceiling.\n\n**Did a conversation's cache writes pay for themselves?**\n\n```sql\nSELECT conversation_id, COUNT(*) AS requests,\n       SUM(cache_write_tokens) AS cache_written,\n       SUM(cache_read_tokens) AS cache_read,\n       CASE WHEN SUM(cache_read_tokens) > 0\n            THEN ROUND(1.0 * SUM(cache_write_tokens) / SUM(cache_read_tokens), 2)\n       END AS write_per_read\nFROM requests\nWHERE conversation_id != ''\nGROUP BY conversation_id\nORDER BY cache_written DESC, cache_read DESC\nLIMIT 20\n```\n\n`write_per_read` at or below 1 means the reads repaid the writes; reads with\nno writes ride a cache somebody else warmed. A conversation with writes and\nno reads paid for a prompt that never came back.\n\n**When does traffic arrive?**\n\n```sql\nSELECT strftime('%w', started_at/1000, 'unixepoch', 'localtime') AS weekday,\n       strftime('%H', started_at/1000, 'unixepoch', 'localtime') AS hour,\n       COUNT(*) AS requests, SUM(cost) AS cost,\n       ROUND(AVG(duration_ms), 1) AS avg_ms\nFROM requests\nGROUP BY weekday, hour\nORDER BY weekday, hour\n```\n\n`weekday` is `0` (Sunday) through `6` and `hour` is two digits in the host's\nlocal zone; drop `localtime` for UTC. Cost is USD, summed as stored.\n\n**How far does the token estimate drift?**\n\n```sql\nSELECT model, COUNT(*) AS requests,\n       ROUND(AVG((chars_system + chars_user + chars_assistant + chars_tool) / 4), 1) AS avg_chars_est,\n       ROUND(AVG(input_tokens), 1) AS avg_input,\n       ROUND(AVG(1.0 * input_tokens /\n            ((chars_system + chars_user + chars_assistant + chars_tool) / 4)), 3) AS input_vs_chars4,\n       ROUND(AVG(1.0 * total_tokens /\n            ((chars_system + chars_user + chars_assistant + chars_tool) / 4 + req_max_tokens)), 3) AS total_vs_est\nFROM requests\nWHERE input_tokens > 0\n  AND chars_system + chars_user + chars_assistant + chars_tool > 0\nGROUP BY model\nORDER BY input_vs_chars4 DESC\n```\n\nThe scheduler reserves prompt chars/4 plus `req_max_tokens` when the client\nsent one. `input_vs_chars4` compares real input tokens with the chars/4\nshare, and `total_vs_est` compares settled total tokens with the full\nreservation. A ratio far from 1 on a well-represented model means the\nreservation systematically over- or under-reserves for it.\n\n**Which requests paid far above their model's blended rate?**\n\n```sql\nSELECT o.model, o.id, o.started_at,\n       ROUND(1e6 * o.cost / (o.input_tokens + o.output_tokens), 2) AS per_mtok,\n       ROUND(1e6 * a.cost_sum / a.tok_sum, 2) AS model_avg_per_mtok,\n       ROUND((1e6 * o.cost / (o.input_tokens + o.output_tokens)) /\n             (1e6 * a.cost_sum / a.tok_sum), 2) AS ratio\nFROM requests o\nJOIN (SELECT model, SUM(cost) AS cost_sum,\n             SUM(input_tokens + output_tokens) AS tok_sum\n      FROM requests WHERE cost > 0 GROUP BY model) a ON a.model = o.model\nWHERE o.cost > 0 AND o.input_tokens + o.output_tokens > 0\nORDER BY ratio DESC\nLIMIT 10\n```\n\n`per_mtok` is the request's own rate over its in+out tokens, and `ratio`\nscales it against the model's blended average, computed over cost-reporting\nrequests only so unpriced traffic cannot dilute it. A ratio far above 1\nmarks expensive outliers such as cache misses or long-tail pricing; flip the\nsort to find the bargains. SQLite has no `median()`, which is why the\nblended average plus a sorted ratio stands in for it.\n\n"
    },
    {
      "path": "docs/reverse-proxy.md",
      "slug": "docs/reverse-proxy",
      "output": "docs/reverse-proxy.html",
      "markdown": "docs/reverse-proxy.md",
      "url": "https://millivolt.llm4people.dev/docs/reverse-proxy.html",
      "markdown_url": "https://millivolt.llm4people.dev/docs/reverse-proxy.md",
      "title": "Reverse proxy and remote access",
      "description": "Use a protected ingress when accessing millivolt beyond a trusted local machine. The whole dashboard is gated by the shared MILLIVOLT_OPERATOR_TOKEN...",
      "group": "Operate",
      "order": 13,
      "bytes": 10328,
      "sha256": "cb15444d4164198849bf98998f88ba3ea02e21fe1e17cc4b0f9083e0aad1a948",
      "sections": [
        {
          "heading": "NGINX setup",
          "id": "nginx-setup",
          "text": "deploy/nginx.conf is the canonical example. It serves millivolt at the origin root, with NGINX on the same host as the loopback-published Compose service. Use a maintained NGINX release with the http2 on directive (introduced in 1.25.1), not the deprecated listen ... http2 syntax. The sample splits two prefix locations because they do not share an access model: location /v1 is the OpenAI-compatible inference base: preserve provider Authorization and routing headers, and allowlist API clients. location / covers everything else, including the dashboard and operator plane ( /dash/ , /metrics/ , /admin/ ) plus the application-open POST /session , /healthz , /readyz and brand/PWA paths: allowlist operators, and keep Host plus the session cookie so Settings origin checks and the live feed work; the comparison is case-insensitive, so a case-preserving ingress is fine. The /session handshake is open at millivolt so login works, but this location still allowlists it at the edge. A URL-capable MCP client uses this location with /mcp appended and the operator Bearer header: the application's MCP endpoint is Bearer-only and refuses the session cookie. Shared streaming proxy settings live on th",
          "context": ""
        },
        {
          "heading": "Streaming and request handling",
          "id": "streaming-and-request-handling",
          "text": "The example disables response/request buffering and proxy retries so the edge does not batch SSE events or independently replay inference. It leaves HTTP statuses intact, disables edge compression/caching, and ignores special upstream X-Accel-* controls for buffering, redirects, rate limits, caching and charset. Millivolt uses SSE, not a WebSocket endpoint; no Upgrade block is needed. It preserves the external Host , including a nondefault port, so browser-origin checks on Settings and other mutations keep working. It also overwrites X-Forwarded-Proto with this server's $scheme , so a TLS presentation reaches millivolt as https and the session cookie carries Secure ; a client-supplied value cannot spoof it. Overwriting is the recommended form. If your ingress appends its scheme instead ( $http_x_forwarded_proto,$scheme ), the application still marks the request secure when any token does, so a client-supplied http in first position cannot downgrade the cookie. The sample also resolves the client address with real_ip : set_real_ip_from 127.0.0.1; real_ip_header X-Forwarded-For; Without it, millivolt sees this hop's address as RemoteAddr for every request and the per-source authentic",
          "context": "NGINX setup"
        },
        {
          "heading": "Credentials and access control",
          "id": "credentials-and-access-control",
          "text": "The sample uses a trusted IP/VPN allowlist on each location, preserving provider Authorization on /v1 and the operator Bearer or session cookie on / . Replace each placeholder with the addresses you intend to trust for that plane. If another load balancer is in front of NGINX, list its addresses in set_real_ip_from and switch real_ip_recursive on, so the trusted chain matches reality; a hop that appends to X-Forwarded-For without being listed is ignored on the left of the real client. TLS encrypts traffic but does not authorize callers. A secure presentation also makes millivolt answer Strict-Transport-Security: max-age=15552000 (180 days, no includeSubDomains ) so a browser pins the scheme; NGINX's own add_header is not needed for it, and adding a second HSTS header at the edge would send two values. See NGINX's access module and TLS configuration . If you instead add HTTP Basic authentication on /v1 , Authorization contains the ingress credential and cannot simultaneously contain the provider bearer key. Supply the provider key through X-Proxy-Key , and clear the consumed ingress header before forwarding with proxy_set_header Authorization \"\"; . The same conflict applies on / : a",
          "context": ""
        },
        {
          "heading": "Container networking and other ingress servers",
          "id": "container-networking-and-other-ingress-servers",
          "text": "When NGINX itself is a container, 127.0.0.1 points back to NGINX, not millivolt. Attach it to the same private Docker network and use http://millivolt:8080 as its upstream instead. Only the edge needs a publicly reachable port. Do not bind millivolt to loopback inside its container, which would prevent peer access. MILLIVOLT_PORT changes host publication, not this internal service port. For another ingress implementation, preserve these same boundaries: protect the origin, keep inference and the operator plane as separate access rules, forward the original authority and required custom headers, allow streaming without response buffering, avoid automatic inference retries, and choose upload/idle limits deliberately. Subpath hosting is not the supplied deployment: dashboard assets and routes expect the origin root.",
          "context": ""
        }
      ],
      "markdown_text": "# Reverse proxy and remote access\n\nUse a protected ingress when accessing millivolt beyond a trusted local machine.\nThe whole dashboard is gated by the shared `MILLIVOLT_OPERATOR_TOKEN`\ncredential; there is no tenant isolation and no per-user identity.\n\nAt the application gate, only the unauthenticated `/healthz` and `/readyz`\nprobes, the `POST /session` login handshake, origin-root brand/PWA files and\ntransparent inference stay open, so a load balancer can health-check the\nservice without holding the credential and a browser can reach the login\nhandshake. The canonical open-path list is in\n[operator access](routes.md#operator-access); this guide only adds the ingress\nboundary. Read [Security](../SECURITY.md) first.\n\n![Reverse proxy topology: the API client and dashboard browser reach NGINX over TLS, NGINX forwards over loopback to millivolt, and millivolt sends requests to the selected upstream](images/diagrams/reverse-proxy.svg)\n\nThe diagram is a text-equivalent summary of the example below: NGINX terminates\nTLS and enforces access; millivolt owns routing, the operator session, and the\nhistory; the upstream receives the selected credentials.\n\n## NGINX setup\n\n[deploy/nginx.conf](../deploy/nginx.conf) is the canonical example. It serves\nmillivolt at the origin root, with NGINX on the same host as the loopback-published\nCompose service. Use a maintained NGINX release with the `http2 on` directive\n(introduced in 1.25.1), not the deprecated `listen ... http2` syntax.\n\nThe sample splits two prefix locations because they do not share an access\nmodel:\n\n- `location /v1` is the OpenAI-compatible inference base: preserve provider\n  `Authorization` and routing headers, and allowlist API clients.\n- `location /` covers everything else, including the dashboard and operator\n  plane (`/dash/`, `/metrics/`, `/admin/`) plus the application-open\n  `POST /session`, `/healthz`, `/readyz` and brand/PWA paths: allowlist\n  operators, and keep `Host` plus the session cookie so Settings origin checks\n  and the live feed work; the comparison is case-insensitive, so a\n  case-preserving ingress is fine.\n\nThe `/session` handshake is open at millivolt so login works, but this location\nstill allowlists it at the edge. A URL-capable MCP client uses this location\nwith `/mcp` appended and the operator Bearer header: the application's MCP\nendpoint is Bearer-only and refuses the session cookie.\n\nShared streaming proxy settings live on the `server` so both SSE paths stay\nunbuffered. Prefix `/v1` wins over `/` for `/v1/chat/completions` and\n`/v1/models`; `GET /models` without that prefix follows `location /` unless you\nadd an exact `/models` block with the inference rules.\n\n1. Start the normal [Compose deployment](../README.md#docker-compose), retaining\n   its loopback-only host port.\n2. Copy the example into your NGINX HTTP configuration. Replace its example\n   hostname, certificate paths and the two TEST-NET allowlists. The supplied\n   address is a placeholder; unmatched clients are denied. The lists may differ\n   when operators and API clients are not the same sources.\n   Set `proxy_pass` to the chosen host port if `MILLIVOLT_PORT` is not 8080.\n3. Validate with `nginx -t` before reloading your existing NGINX service. Confirm\n   a trusted client and a denied client on both `/` and `/v1`.\n4. Use `https://your-hostname/` for the dashboard and\n   `https://your-hostname/v1` as the client API base. Keep sending the actual\n   upstream base/key as described in the [client setup](../README.md#connect-a-client).\n\nThe sample is a `server` block, included under NGINX's existing `http` context,\nnot a replacement for the entire installation configuration. It does not issue\ncertificates or configure your firewall. Do not expose the original proxy port\nalongside the protected HTTPS endpoint.\n\n### Streaming and request handling\n\nThe example disables response/request buffering and proxy retries so the edge\ndoes not batch SSE events or independently replay inference. It leaves HTTP\nstatuses intact, disables edge compression/caching, and ignores special upstream\n`X-Accel-*` controls for buffering, redirects, rate limits, caching and charset.\nMillivolt uses SSE, not a WebSocket endpoint; no `Upgrade` block is needed.\n\nIt preserves the external `Host`, including a nondefault port, so browser-origin\nchecks on Settings and other mutations keep working.\n\nIt also overwrites `X-Forwarded-Proto` with this server's `$scheme`, so a TLS\npresentation reaches millivolt as `https` and the session cookie carries\n`Secure`; a client-supplied value cannot spoof it. Overwriting is the\nrecommended form. If your ingress appends its scheme instead\n(`$http_x_forwarded_proto,$scheme`), the application still marks the request\nsecure when any token does, so a client-supplied `http` in first position\ncannot downgrade the cookie.\n\nThe sample also resolves the client address with `real_ip`:\n\n```nginx\nset_real_ip_from 127.0.0.1;\nreal_ip_header X-Forwarded-For;\n```\n\nWithout it, millivolt sees this hop's address as `RemoteAddr` for every request\nand the per-source authentication throttle gets one bucket, so a single wrong\nguess locks out every operator. `set_real_ip_from` lists the addresses allowed\nto send a replacement address: this host's own loopback.\n\nIf another load balancer, tunnel or proxy fronts NGINX, add its address range\nthere and set `real_ip_recursive on` once every hop in the chain is listed.\n\n`real_ip` walks `X-Forwarded-For` from the right and keeps the last untrusted\naddress, so a client that prepends a forged entry cannot displace the real one;\nNGINX's default `$proxy_add_x_forwarded_for` then appends the resolved address\non the way inbound, and the per-source authentication throttle reads that last\nelement.\n\nThe record field is separate: `client_ip` records the first `X-Forwarded-For`\nelement when that header is present and the socket peer otherwise; the value is\ndiagnostic, never verified, and a directly reachable caller can set it.\n\nThe resolved address is a throttle key, not an identity: keep the location\nallowlists in force. Those lists evaluate the resolved address, so a caller\nthat already reaches this host's loopback chooses what they see: they separate\nremote networks from each other and from loopback callers, not loopback callers\nfrom each other.\n\nNGINX's body-size gate is\ndisabled in the sample: millivolt's existing `max_request_bytes` remains the\napplication limit, rather than an accidentally smaller duplicate at ingress.\nChoose edge idle timeouts for your deployment. `proxy_read_timeout` limits the\ngap between upstream reads, not the total lifetime of a stream.\n\nThese behaviors follow the official [proxy module](https://nginx.org/en/docs/http/ngx_http_proxy_module.html),\n[HTTP core module](https://nginx.org/en/docs/http/ngx_http_core_module.html),\n[HTTP/2 module](https://nginx.org/en/docs/http/ngx_http_v2_module.html) and\n[realip module](https://nginx.org/en/docs/http/ngx_http_realip_module.html).\n\n## Credentials and access control\n\nThe sample uses a trusted IP/VPN allowlist on each location, preserving\nprovider `Authorization` on `/v1` and the operator Bearer or session cookie on\n`/`. Replace each placeholder with the addresses you intend to trust for that\nplane.\n\nIf another load balancer is in front of NGINX, list its addresses in\n`set_real_ip_from` and switch `real_ip_recursive` on, so the trusted chain\nmatches reality; a hop that appends to `X-Forwarded-For` without being listed\nis ignored on the left of the real client.\n\nTLS encrypts traffic but does not authorize callers. A secure presentation also\nmakes millivolt answer `Strict-Transport-Security: max-age=15552000` (180 days,\nno `includeSubDomains`) so a browser pins the scheme; NGINX's own `add_header`\nis not needed for it, and adding a second HSTS header at the edge would send\ntwo values. See NGINX's\n[access module](https://nginx.org/en/docs/http/ngx_http_access_module.html)\nand [TLS configuration](https://nginx.org/en/docs/http/ngx_http_ssl_module.html).\n\nIf you instead add HTTP Basic authentication on `/v1`, `Authorization` contains\nthe ingress credential and cannot simultaneously contain the provider bearer\nkey. Supply the provider key through `X-Proxy-Key`, and clear the consumed\ningress header before forwarding with `proxy_set_header Authorization \"\";`.\n\nThe same conflict applies on `/`: a browser behind Basic auth cannot also\npresent the dashboard's Bearer credential in the same header, so gated actions\nfail. Prefer an address/VPN allowlist as in the sample, or an ingress that\nadds its own credential through a different mechanism and forwards\n`Authorization` untouched.\n\nDo not put Basic auth on `/v1` to \"protect inference\" while leaving `/` on\nBearer: that still overwrites the provider key. The same separation applies to\nother ingress-only credentials: do not forward them to an LLM provider. Clients\nmust support your ingress authentication and the proxy's custom routing\nheaders.\n\nThe session handshake lives at `/session`, outside the admin plane, which\nsupports one specific pattern: an external authentication layer may front\n`/admin/*` alone, because millivolt's own login stays reachable and the\nmutation and settings routes become double-gated, the external layer plus\nmillivolt's credential.\n\nOperators fronting `/admin` this way must still pass the session cookie and\n`Host` through to the proxy, since the dashboard's fetch-based mutations rely\non both.\n\n## Container networking and other ingress servers\n\nWhen NGINX itself is a container, `127.0.0.1` points back to NGINX, not millivolt.\nAttach it to the same private Docker network and use `http://millivolt:8080` as\nits upstream instead. Only the edge needs a publicly reachable port. Do not bind\nmillivolt to loopback inside its container, which would prevent peer access.\n`MILLIVOLT_PORT` changes host publication, not this internal service port.\n\nFor another ingress implementation, preserve these same boundaries: protect the\norigin, keep inference and the operator plane as separate access rules, forward\nthe original authority and required custom headers, allow streaming without\nresponse buffering, avoid automatic inference retries, and choose upload/idle\nlimits deliberately. Subpath hosting is not the supplied deployment: dashboard\nassets and routes expect the origin root.\n"
    },
    {
      "path": "docs/performance.md",
      "slug": "docs/performance",
      "output": "docs/performance.html",
      "markdown": "docs/performance.md",
      "url": "https://millivolt.llm4people.dev/docs/performance.html",
      "markdown_url": "https://millivolt.llm4people.dev/docs/performance.md",
      "title": "Performance and resource usage",
      "description": "This page is the single source for the published performance and resource numbers. It records what was measured, how it was measured, and what the result...",
      "group": "Operate",
      "order": 14,
      "bytes": 21700,
      "sha256": "e4171a08db49ffa5a1d815ee9e3ca47215a35ce922d16365372e244bfc6865ab",
      "sections": [
        {
          "heading": "Artifact and idle footprint",
          "id": "artifact-and-idle-footprint",
          "text": "Artifact or state Bytes Display Notes Static amd64 binary 21,663,904 20.7 MiB Stripped, no CGO amd64 runtime image 38,022,232 36.3 MiB Docker-reported content size Compressed image archive 9,887,262 9.4 MiB docker save piped through gzip -9 Idle process, empty SQLite 30,204 KiB 29.5 MiB After a 15-second quiet interval Idle process CPU 2 scheduler ticks 0.067% 2 ticks over 30 seconds The image size includes the distroless base, dependency notices, and the embedded UI. It is not a compressed download size, a registry digest, or a persistent-volume estimate. Idle RSS and CPU describe one process on this host. A short sample cannot prove that a longer idle period uses exactly the same resources.",
          "context": ""
        },
        {
          "heading": "Method",
          "id": "method",
          "text": "Item Setting Date 2026-11-16 Source revision 22c0b6b73655 Go toolchain go1.27.4, CGO_ENABLED=0 Platform Linux/amd64 under WSL2 CPU Intel(R) Core(TM) Ultra 9 285H, 12 visible logical CPUs Visible RAM 62 GiB Configuration Public example with private listen and database paths Debug captures Off Body previews Off Browser and live observer None during load stages Upstream Local synthetic server on loopback Load shape Closed-loop HTTP stages, then drain RSS sampling 100 ms CPU unit 100% equals one logical CPU Accounting check Exact stages reconcile rows, tokens and cost; a dropping stage reconciles durable plus dropped Host load (1-minute) 23.36 at start, 13.38 at end The public example configuration was used, with private listen and database paths supplied by scripts/dev.sh . The method table records the harness declarations for captures, previews, the observer and the upstream. CPU and RSS describe the native Go process, not Docker's container-wide accounting. Percentiles are nearest-rank.",
          "context": ""
        },
        {
          "heading": "Fast-response throughput",
          "id": "fast-response-throughput",
          "text": "Each stage used a fresh disposable database and the same synthetic response: 10 content frames, usage 100/10 , and fixture cost 0.001 . The upstream added no intentional delay. Each stage started requests for 5 seconds, then let active requests drain. The final row is a separate 10-second run used to reach about 129,442 durable rows without a storage drop. Client workers HTTP requests Requests/s p50 p95 p99 Proxy CPU Peak proxy RSS Durable rows 1 6,879 1,375.7 0.66 ms 1.09 ms 1.66 ms 52.6% 61.5 MiB Exact, 6,879 8 30,264 6,050.9 1.17 ms 2.28 ms 4.06 ms 239.3% 88.3 MiB Exact, 30,264 32 53,081 10,567.2 2.55 ms 6.01 ms 8.63 ms 374.3% 93.0 MiB Exact, 53,081 128 66,813 13,346.4 8.40 ms 20.19 ms 28.29 ms 465.2% 119.0 MiB Exact, 66,813 128, 10 s 129,442 12,931.5 8.50 ms 21.30 ms 31.58 ms 459.7% 124.5 MiB Exact, 129,442 The exact fast-response point is 13,346.4 requests/s at 128 workers, with p95 20.19 ms and p99 28.29 ms. The 128-worker 10-second stage used 227.3% CPU and 33.7 MiB peak RSS in the separate load generator and synthetic upstream process. All HTTP responses succeeded in these stages, including the 128-worker stage. That is not a promise that every configuration and history siz",
          "context": ""
        },
        {
          "heading": "Sustained capacity",
          "id": "sustained-capacity",
          "text": "The sustained capacity point is the highest tested closed-loop level that completed a 300-second run with zero durable drops and exact accounting. Each level started from a fresh disposable database. The upstream response and client shape were the same as the fast-response table: 10 content frames, usage 100/10 , and fixture cost 0.001 . Workers Duration HTTP requests Requests/s p50 p95 p99 Proxy CPU Peak proxy RSS Durable rows Drops 32 300.00 s 2,584,965 8,616.5 2.54 ms 9.93 ms 19.71 ms 289.1% 107.0 MiB Exact, 2,584,965 0 48 300.01 s 3,683,159 12,276.8 3.12 ms 8.92 ms 15.68 ms 421.1% 121.9 MiB Exact, 3,683,159 0 64 300.00 s 4,649,811 15,499.2 3.62 ms 8.18 ms 12.03 ms 522.6% 125.8 MiB 4,602,957 kept 46,854 128 300.03 s 4,169,782 13,897.8 7.77 ms 20.25 ms 32.11 ms 451.4% 141.1 MiB 3,775,709 kept 394,073 The exact 300-second point is 12,276.8 requests/s at 48 workers, with p95 8.92 ms and p99 15.68 ms. The 64-worker point dropped 46,854 rows (1.0% of its requests). A level that drops is an overload observation, not a capacity result; the bounded durable queue is not lossless at every load.",
          "context": ""
        },
        {
          "heading": "Streaming concurrency",
          "id": "streaming-concurrency",
          "text": "The synthetic upstream emitted 10-frame response across approximately 1-second stream, followed by usage and a terminator. Each stage started its fixed number of requests and then drained. Latency includes the intentional upstream delay, so these numbers are not proxy-only overhead. Workers HTTP requests Requests/s SSE events/s Output tokens/s Response KiB/s p50 p95 p99 First-byte p95 1 5 1.0 12 10 0.6 1,009.61 ms 1,010.49 ms 1,010.49 ms 2.22 ms 8 40 7.9 95 79 4.7 1,007.21 ms 1,009.82 ms 1,010.22 ms 3.59 ms 32 160 31.4 377 314 18.8 1,007.57 ms 1,016.44 ms 1,059.19 ms 8.23 ms 64 320 62.9 755 629 37.6 1,008.33 ms 1,037.34 ms 1,054.23 ms 31.17 ms 128 640 124.5 1,494 1,245 74.4 1,009.33 ms 1,074.57 ms 1,107.40 ms 69.27 ms 256 1,280 248.0 2,976 2,480 148.2 1,010.96 ms 1,093.08 ms 1,119.54 ms 89.49 ms 512 2,560 490.0 5,880 4,900 292.9 1,008.64 ms 1,150.71 ms 1,153.58 ms 145.75 ms 1,024 3,072 494.8 5,938 4,948 295.7 2,016.27 ms 2,144.02 ms 2,157.64 ms 1,133.32 ms Workers Proxy CPU Peak proxy RSS Upstream peak Durable rows Drops 1 0.2% 31.7 MiB 1 Exact, 5 0 8 1.0% 32.7 MiB 8 Exact, 40 0 32 3.7% 36.7 MiB 32 Exact, 160 0 64 6.9% 40.2 MiB 64 Exact, 320 0 128 13.2% 49.8 MiB 128 Exact, 640 0 25",
          "context": ""
        },
        {
          "heading": "Streaming throughput",
          "id": "streaming-throughput",
          "text": "scripts/perf.sh streaming runs the longer end-to-end throughput ramp. Each level starts a fresh private scripts/dev.sh instance and sends requests through the real proxy to a local synthetic SSE upstream. Each level ran for 60 seconds with 100 content frames over a roughly 1-second stream. Workers HTTP requests Requests/s SSE events/s Output tokens/s Response KiB/s p50 p95 p99 First-byte p95 1 57 0.9 96 94 4.8 1,067.07 ms 1,079.25 ms 1,085.80 ms 3.02 ms 8 448 7.5 760 746 37.9 1,066.92 ms 1,125.67 ms 1,146.53 ms 6.08 ms 32 1,824 30.3 3,086 3,026 153.7 1,055.96 ms 1,067.91 ms 1,073.94 ms 3.17 ms 64 3,648 60.2 6,140 6,020 305.9 1,061.67 ms 1,072.37 ms 1,088.48 ms 3.88 ms 128 7,296 120.5 12,291 12,050 612.3 1,060.13 ms 1,069.44 ms 1,113.02 ms 5.44 ms 256 14,592 239.2 24,395 23,916 1,215.2 1,061.58 ms 1,138.38 ms 1,174.13 ms 11.75 ms 512 28,789 471.5 48,094 47,151 2,395.8 1,063.37 ms 1,141.20 ms 1,300.62 ms 15.32 ms 1,024 29,696 478.6 48,819 47,861 2,431.9 2,128.84 ms 2,162.96 ms 2,285.10 ms 1,091.76 ms Workers Proxy CPU Peak proxy RSS Upstream peak Durable rows Drops 1 1.2% 31.5 MiB 1 Exact, 57 0 8 5.5% 37.1 MiB 8 Exact, 448 0 32 14.9% 47.8 MiB 32 Exact, 1,824 0 64 28.2% 59.0 MiB 64 Ex",
          "context": ""
        },
        {
          "heading": "Durable writer and overload",
          "id": "durable-writer-and-overload",
          "text": "These are isolated Go benchmarks from the test overlay, not HTTP runs. Every row and drop count is verified against successful requests. The overload benchmark deliberately fills the bounded queue, so its drop count is a fixture result, not a recommended operating point. Path Durable rows/s Allocations Direct batch insert at the configured batch capacity 62,921 425,396 B/op, 7,279 allocs/op Queued Record plus Flush at the queue capacity 56,055 13,594,117 B/op, 232,920 allocs/op Overload fixture Wire requests/s Durable rows/s Dropped rows 32 workers 72,619 19,994 101,507 128 workers 64,161 14,605 113,242 The overload fixture confirms the accounting invariant durable + dropped = successful requests . Increasing queue capacity alone cannot make sustained overload lossless. A higher HTTP success rate is not a complete-accounting result unless the durable row count and drop delta agree.",
          "context": ""
        },
        {
          "heading": "Storage and retained projection",
          "id": "storage-and-retained-projection",
          "text": "The storage fixture stores complete records, indexes, projection triggers, and marshaled response headers in SQLite. Disk bytes include the database, WAL, and shared-memory sidecar after a final flush. Measure 10,000 records 100,000 records SQLite bytes total 6.84 MiB 49.20 MiB SQLite bytes per record 717.3 515.9 Projection retained, built 449.6 B/record 470.8 B/record Projection interned dimensions 442.0 B/record 429.1 B/record Projection scanned decode 580.3 B/record 576.0 B/record Projection transient allocation 3,125 B/record 3,434 B/record The projection process benchmark is a relative measure inside the test binary, not the deployed proxy's RSS. At 100,000 records it measured 94.6 MiB process RSS and a 66.0 MiB projection delta; at 10,000 records it measured 40.6 MiB process RSS and a 12.0 MiB delta. The test binary and its linked packages are part of the absolute figure. A fast-response run reached a 119.0 MiB peak with 66,813 durable rows while no dashboard projection was preloaded. Use the projection delta above for the retained analytical cost, not the loaded-process peak as a substitute.",
          "context": ""
        },
        {
          "heading": "Query and metadata paths",
          "id": "query-and-metadata-paths",
          "text": "The query benchmarks seed a 100,000-row scratch database and decode a 200-row page. These are single-iteration measurements on a shared host, so small differences are not meaningful. Query Before cursor With cursor Allocations before cursor Provider equality 4.24 ms 3.85 ms 1.38 MB, 5,455 allocs Model equality 2.81 ms 2.93 ms 1.38 MB, 5,445 allocs Client equality 36.52 ms 18.73 ms 1.38 MB, 5,442 allocs Key-hash equality 33.68 ms 18.28 ms 23.5 KB, 265 allocs Conversation equality 40.16 ms 21.73 ms 23.2 KB, 264 allocs Status equality 38.98 ms 20.99 ms 698.1 KB, 2,942 allocs The request metadata path performs one bounded metadata decode; the allocation column is measured per call. Metadata body Time per request Throughput Allocations 1 KiB 428 ns 2,580.8 MB/s 16 B, 1 alloc 100 KiB 4,808 ns 21,314.0 MB/s 16 B, 1 alloc 1 MiB 75,397 ns 13,908.4 MB/s 16 B, 1 alloc",
          "context": ""
        },
        {
          "heading": "Implementation benchmarks",
          "id": "implementation-benchmarks",
          "text": "These are the isolated benchmark results the design notes cite. They are current measurements from the same run as the tables above, not a historical before and after across revisions. Benchmark Time Bytes per op Allocs per op BenchmarkAggregateFold/chart 2.74 ms 136,736 B 28 BenchmarkAggregateFold/explorer 4.38 ms 209,696 B 37 BenchmarkAggregateFold/explorer_tool 3.73 ms 807,840 B 38 BenchmarkAggregateFold/chart_window 413,833 ns 17,616 B 28 BenchmarkHandleLogPage/empty/limit_60 1.70 ms 987,376 B 3,533 BenchmarkHandleLogPage/sql_provider/limit_60 1.95 ms 550,080 B 2,645 BenchmarkHandleLogPage/go_status_class/limit_60 1.89 ms 903,504 B 2,686 BenchmarkHandleLogPage/go_status_class_5xx/limit_60 4.88 ms 1,819,616 B 21,125 BenchmarkHandleLogPage/go_tool_missing/limit_60 5.00 ms 1,883,032 B 29,360 BenchmarkHandleLogPage/empty/limit_200 4.26 ms 2,889,608 B 7,999 BenchmarkHandleLogPage/sql_provider/limit_200 4.92 ms 2,888,720 B 7,993 BenchmarkHandleLogPage/go_status_class/limit_200 4.14 ms 2,890,912 B 8,015 BenchmarkHandleLogPage/go_status_class_5xx/limit_200 3.88 ms 1,889,744 B 21,029 BenchmarkHandleLogPage/go_tool_missing/limit_200 4.72 ms 1,957,512 B 29,258 BenchmarkProjectionMetricApp",
          "context": ""
        },
        {
          "heading": "Reproduce",
          "id": "reproduce",
          "text": "scripts/perf.sh owns the repeatable local run: bench , stress , streaming , sustained , image , or all . scripts/perf.sh docs runs the full set, writes perf/results.json , and regenerates this page. It refuses a dirty tree unless PERF_ALLOW_DIRTY=1 is set, because published numbers must name a commit. The full run uses the documented levels and durations: 5 seconds for each fast stage, 300 seconds for each sustained level, and 60 seconds for each streaming throughput level. Override the level lists and durations with PERF_FAST_LEVELS , PERF_SUSTAINED_LEVELS , PERF_STREAMING_LEVELS , PERF_FAST_DURATION , PERF_SUSTAINED_DURATION , PERF_STREAMING_DURATION , PERF_STREAMING_HOLD and PERF_STREAMING_CHUNKS . The bundle records what ran; a changed run changes the page. The individual commands below are the same evidence path. Use a fresh DEV_COPY_DB=0 instance for each workload. Never target the main instance on port 8080. The stress harness verifies that the target is the private scripts/dev.sh instance before sending traffic. ( set -e trap 'scripts/dev.sh stop' EXIT export MILLIVOLT_OPERATOR_TOKEN='dev-instance-credential' DEV_COPY_DB=0 scripts/dev.sh go run ./cmd/stress -target http://1",
          "context": ""
        },
        {
          "heading": "Limitations",
          "id": "limitations",
          "text": "The host was shared. Other workloads can change absolute rates and latency. The upstream was a local synthetic server. Provider latency, TLS, retries, payload shape, and real identity cardinality are not represented. These are short closed-loop bursts, not sustained production capacity. No result here is a capacity ceiling or a guarantee. The streaming concurrency table is a short ramp on a 10-frame, roughly 1-second fixture. The streaming throughput table is a 60-second per-level ramp on a 100-frame, roughly 1-second fixture. Both are synthetic-fixture measurements, not universal maxima. The throughput table's 1,024-client level is above the example max_conns_per_host of 512 and measures queueing; it is a fixed level list, not an automatic saturation search. Its token rate is the fixture's usage count, not provider-token throughput. The 300-second sustained sweep uses the fast-response fixture with no intentional stream hold ( -stream-duration 0 ). A level with durable drops is an overload observation, not a maximum streaming rate. The streaming throughput ramp is the only sustained held-stream run; it stops at its fixed levels and does not search beyond the largest listed level. ",
          "context": ""
        }
      ],
      "markdown_text": "# Performance and resource usage\n\nThis page is the single source for the published performance and resource\nnumbers. It records what was measured, how it was measured, and what the result\ndoes not prove. The [performance and footprint](operations.md#performance-and-footprint)\nsection in operations owns the implementation cost model and `go_memory_limit`\nbehavior.\n\nThese are scoped local measurements of the native proxy process, not deployment\nguarantees. The page was regenerated from the result bundle on\n2026-11-16 UTC.\n\n## Artifact and idle footprint\n\n| Artifact or state | Bytes | Display | Notes |\n| --- | ---: | ---: | --- |\n| Static amd64 binary | 21,663,904 | 20.7 MiB | Stripped, no CGO |\n| amd64 runtime image | 38,022,232 | 36.3 MiB | Docker-reported content size |\n| Compressed image archive | 9,887,262 | 9.4 MiB | `docker save` piped through `gzip -9` |\n| Idle process, empty SQLite | 30,204 KiB | 29.5 MiB | After a 15-second quiet interval |\n| Idle process CPU | 2 scheduler ticks | 0.067% | 2 ticks over 30 seconds |\n\nThe image size includes the distroless base, dependency notices, and the\nembedded UI. It is not a compressed download size, a registry digest, or a\npersistent-volume estimate. Idle RSS and CPU describe one process on this host.\nA short sample cannot prove that a longer idle period uses exactly the same\nresources.\n\n## Method\n\n| Item | Setting |\n| --- | --- |\n| Date | 2026-11-16 |\n| Source revision | [`22c0b6b73655`](https://github.com/LLM-4-People/millivolt/commit/22c0b6b73655a349e086c345bc80907efbe16822) |\n| Go toolchain | go1.27.4, `CGO_ENABLED=0` |\n| Platform | Linux/amd64 under WSL2 |\n| CPU | Intel(R) Core(TM) Ultra 9 285H, 12 visible logical CPUs |\n| Visible RAM | 62 GiB |\n| Configuration | Public example with private listen and database paths |\n| Debug captures | Off |\n| Body previews | Off |\n| Browser and live observer | None during load stages |\n| Upstream | Local synthetic server on loopback |\n| Load shape | Closed-loop HTTP stages, then drain |\n| RSS sampling | 100 ms |\n| CPU unit | 100% equals one logical CPU |\n| Accounting check | Exact stages reconcile rows, tokens and cost; a dropping stage reconciles durable plus dropped |\n| Host load (1-minute) | 23.36 at start, 13.38 at end |\n\nThe public example configuration was used, with private listen and database\npaths supplied by `scripts/dev.sh`. The method table records the harness\ndeclarations for captures, previews, the observer and the upstream. CPU and RSS\ndescribe the native Go process, not Docker's container-wide accounting.\nPercentiles are nearest-rank.\n\n## Fast-response throughput\n\nEach stage used a fresh disposable database and the same synthetic response:\n10 content frames, usage `100/10`, and fixture cost `0.001`. The upstream added no intentional delay. Each stage started\nrequests for 5 seconds, then let active requests drain. The final\nrow is a separate\n10-second run used\nto reach about 129,442 durable rows\nwithout a storage drop.\n\n| Client workers | HTTP requests | Requests/s | p50 | p95 | p99 | Proxy CPU | Peak proxy RSS | Durable rows |\n| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |\n| 1 | 6,879 | 1,375.7 | 0.66 ms | 1.09 ms | 1.66 ms | 52.6% | 61.5 MiB | Exact, 6,879 |\n| 8 | 30,264 | 6,050.9 | 1.17 ms | 2.28 ms | 4.06 ms | 239.3% | 88.3 MiB | Exact, 30,264 |\n| 32 | 53,081 | 10,567.2 | 2.55 ms | 6.01 ms | 8.63 ms | 374.3% | 93.0 MiB | Exact, 53,081 |\n| 128 | 66,813 | 13,346.4 | 8.40 ms | 20.19 ms | 28.29 ms | 465.2% | 119.0 MiB | Exact, 66,813 |\n| 128, 10 s | 129,442 | 12,931.5 | 8.50 ms | 21.30 ms | 31.58 ms | 459.7% | 124.5 MiB | Exact, 129,442 |\n\nThe exact fast-response point is 13,346.4 requests/s at 128 workers, with p95 20.19 ms and p99 28.29 ms. The 128-worker 10-second stage used 227.3% CPU and 33.7 MiB peak RSS in the separate load generator and synthetic upstream process.\n\nAll HTTP responses succeeded in these stages, including the\n128-worker stage. That is not a\npromise that every configuration and history size stays exact under overload.\nThe durable queue is bounded and best-effort; the deliberate overload fixture\nbelow shows what a drop result looks like.\n\n## Sustained capacity\n\nThe sustained capacity point is the highest tested closed-loop level that\ncompleted a 300-second run with zero durable drops and exact\naccounting. Each level started from a fresh disposable database. The upstream\nresponse and client shape were the same as the fast-response table:\n10 content frames, usage `100/10`, and fixture cost `0.001`.\n\n| Workers | Duration | HTTP requests | Requests/s | p50 | p95 | p99 | Proxy CPU | Peak proxy RSS | Durable rows | Drops |\n| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |\n| 32 | 300.00 s | 2,584,965 | 8,616.5 | 2.54 ms | 9.93 ms | 19.71 ms | 289.1% | 107.0 MiB | Exact, 2,584,965 | 0 |\n| 48 | 300.01 s | 3,683,159 | 12,276.8 | 3.12 ms | 8.92 ms | 15.68 ms | 421.1% | 121.9 MiB | Exact, 3,683,159 | 0 |\n| 64 | 300.00 s | 4,649,811 | 15,499.2 | 3.62 ms | 8.18 ms | 12.03 ms | 522.6% | 125.8 MiB | 4,602,957 kept | 46,854 |\n| 128 | 300.03 s | 4,169,782 | 13,897.8 | 7.77 ms | 20.25 ms | 32.11 ms | 451.4% | 141.1 MiB | 3,775,709 kept | 394,073 |\n\nThe exact 300-second point is 12,276.8 requests/s at 48 workers, with p95 8.92 ms and p99 15.68 ms. The 64-worker point dropped 46,854 rows (1.0% of its requests). A level that drops is an overload observation, not a capacity result; the bounded durable queue is not lossless at every load.\n\n## Streaming concurrency\n\nThe synthetic upstream emitted 10-frame response across approximately\n1-second stream, followed by usage and a terminator. Each stage started its\nfixed number of requests and then drained. Latency includes the intentional\nupstream delay, so these numbers are not proxy-only overhead.\n\n| Workers | HTTP requests | Requests/s | SSE events/s | Output tokens/s | Response KiB/s | p50 | p95 | p99 | First-byte p95 |\n| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |\n| 1 | 5 | 1.0 | 12 | 10 | 0.6 | 1,009.61 ms | 1,010.49 ms | 1,010.49 ms | 2.22 ms |\n| 8 | 40 | 7.9 | 95 | 79 | 4.7 | 1,007.21 ms | 1,009.82 ms | 1,010.22 ms | 3.59 ms |\n| 32 | 160 | 31.4 | 377 | 314 | 18.8 | 1,007.57 ms | 1,016.44 ms | 1,059.19 ms | 8.23 ms |\n| 64 | 320 | 62.9 | 755 | 629 | 37.6 | 1,008.33 ms | 1,037.34 ms | 1,054.23 ms | 31.17 ms |\n| 128 | 640 | 124.5 | 1,494 | 1,245 | 74.4 | 1,009.33 ms | 1,074.57 ms | 1,107.40 ms | 69.27 ms |\n| 256 | 1,280 | 248.0 | 2,976 | 2,480 | 148.2 | 1,010.96 ms | 1,093.08 ms | 1,119.54 ms | 89.49 ms |\n| 512 | 2,560 | 490.0 | 5,880 | 4,900 | 292.9 | 1,008.64 ms | 1,150.71 ms | 1,153.58 ms | 145.75 ms |\n| 1,024 | 3,072 | 494.8 | 5,938 | 4,948 | 295.7 | 2,016.27 ms | 2,144.02 ms | 2,157.64 ms | 1,133.32 ms |\n\n| Workers | Proxy CPU | Peak proxy RSS | Upstream peak | Durable rows | Drops |\n| --- | ---: | ---: | ---: | ---: | ---: |\n| 1 | 0.2% | 31.7 MiB | 1 | Exact, 5 | 0 |\n| 8 | 1.0% | 32.7 MiB | 8 | Exact, 40 | 0 |\n| 32 | 3.7% | 36.7 MiB | 32 | Exact, 160 | 0 |\n| 64 | 6.9% | 40.2 MiB | 64 | Exact, 320 | 0 |\n| 128 | 13.2% | 49.8 MiB | 128 | Exact, 640 | 0 |\n| 256 | 24.6% | 67.4 MiB | 256 | Exact, 1,280 | 0 |\n| 512 | 48.6% | 103.7 MiB | 512 | Exact, 2,560 | 0 |\n| 1,024 | 48.6% | 137.9 MiB | 512 | Exact, 3,072 | 0 |\n\nThese stages measure concurrency and end-to-end latency for that fixed fixture.\nThey do not measure SSE event rate, bytes per second, token throughput, TTFT,\nchunk-size or hold-duration effects, sustained streaming, or the point where\nstreaming saturates. First-byte p95 is the first response byte, not the first\ngenerated token.\n\nThe 1,024-worker stage reached\n512 upstream connections\nand remained exact. This is a configured concurrency result on one host, not a\nuniversal request-capacity ceiling. The largest level also matches the example\nconfiguration's `max_conns_per_host` of 512. No higher level, sustained\nstreaming stage, or automatic saturation sweep was run; see\n[Limitations](#limitations).\n\n## Streaming throughput\n\n`scripts/perf.sh streaming` runs the longer end-to-end throughput ramp. Each\nlevel starts a fresh private `scripts/dev.sh` instance and sends requests\nthrough the real proxy to a local synthetic SSE upstream. Each level ran for\n60 seconds\nwith 100 content frames over a roughly 1-second\nstream.\n\n| Workers | HTTP requests | Requests/s | SSE events/s | Output tokens/s | Response KiB/s | p50 | p95 | p99 | First-byte p95 |\n| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |\n| 1 | 57 | 0.9 | 96 | 94 | 4.8 | 1,067.07 ms | 1,079.25 ms | 1,085.80 ms | 3.02 ms |\n| 8 | 448 | 7.5 | 760 | 746 | 37.9 | 1,066.92 ms | 1,125.67 ms | 1,146.53 ms | 6.08 ms |\n| 32 | 1,824 | 30.3 | 3,086 | 3,026 | 153.7 | 1,055.96 ms | 1,067.91 ms | 1,073.94 ms | 3.17 ms |\n| 64 | 3,648 | 60.2 | 6,140 | 6,020 | 305.9 | 1,061.67 ms | 1,072.37 ms | 1,088.48 ms | 3.88 ms |\n| 128 | 7,296 | 120.5 | 12,291 | 12,050 | 612.3 | 1,060.13 ms | 1,069.44 ms | 1,113.02 ms | 5.44 ms |\n| 256 | 14,592 | 239.2 | 24,395 | 23,916 | 1,215.2 | 1,061.58 ms | 1,138.38 ms | 1,174.13 ms | 11.75 ms |\n| 512 | 28,789 | 471.5 | 48,094 | 47,151 | 2,395.8 | 1,063.37 ms | 1,141.20 ms | 1,300.62 ms | 15.32 ms |\n| 1,024 | 29,696 | 478.6 | 48,819 | 47,861 | 2,431.9 | 2,128.84 ms | 2,162.96 ms | 2,285.10 ms | 1,091.76 ms |\n\n| Workers | Proxy CPU | Peak proxy RSS | Upstream peak | Durable rows | Drops |\n| --- | ---: | ---: | ---: | ---: | ---: |\n| 1 | 1.2% | 31.5 MiB | 1 | Exact, 57 | 0 |\n| 8 | 5.5% | 37.1 MiB | 8 | Exact, 448 | 0 |\n| 32 | 14.9% | 47.8 MiB | 32 | Exact, 1,824 | 0 |\n| 64 | 28.2% | 59.0 MiB | 64 | Exact, 3,648 | 0 |\n| 128 | 57.9% | 81.3 MiB | 128 | Exact, 7,296 | 0 |\n| 256 | 115.1% | 114.9 MiB | 256 | Exact, 14,592 | 0 |\n| 512 | 233.1% | 152.2 MiB | 513 | Exact, 28,789 | 0 |\n| 1,024 | 239.9% | 189.4 MiB | 512 | Exact, 29,696 | 0 |\n\nThroughput peaked at 478.6 requests/s at 1,024 workers. At 1,024 workers the upstream peak stayed at 512, throughput was 478.6 requests/s against 471.5 at 512 workers, and p50 latency rose from 1.06 s to 2.13 s. The extra clients queued behind the configured 512 upstream connections.\n\nEvery level completed with exact durable accounting unless its row reports\ndrops. This run started under the host load the harness recorded, so absolute\nrates are comparable only within this page and this host.\n\n## Durable writer and overload\n\nThese are isolated Go benchmarks from the test overlay, not HTTP runs. Every\nrow and drop count is verified against successful requests. The overload\nbenchmark deliberately fills the bounded queue, so its drop count is a fixture\nresult, not a recommended operating point.\n\n| Path | Durable rows/s | Allocations |\n| --- | ---: | ---: |\n| Direct batch insert at the configured batch capacity | 62,921 | 425,396 B/op, 7,279 allocs/op |\n| Queued `Record` plus `Flush` at the queue capacity | 56,055 | 13,594,117 B/op, 232,920 allocs/op |\n\n| Overload fixture | Wire requests/s | Durable rows/s | Dropped rows |\n| --- | ---: | ---: | ---: |\n| 32 workers | 72,619 | 19,994 | 101,507 |\n| 128 workers | 64,161 | 14,605 | 113,242 |\n\nThe overload fixture confirms the accounting invariant `durable + dropped =\nsuccessful requests`. Increasing queue capacity alone cannot make sustained\noverload lossless. A higher HTTP success rate is not a complete-accounting\nresult unless the durable row count and drop delta agree.\n\n## Storage and retained projection\n\nThe storage fixture stores complete records, indexes, projection triggers, and\nmarshaled response headers in SQLite. Disk bytes include the database, WAL, and\nshared-memory sidecar after a final flush.\n\n| Measure | 10,000 records | 100,000 records |\n| --- | ---: | ---: |\n| SQLite bytes total | 6.84 MiB | 49.20 MiB |\n| SQLite bytes per record | 717.3 | 515.9 |\n| Projection retained, built | 449.6 B/record | 470.8 B/record |\n| Projection interned dimensions | 442.0 B/record | 429.1 B/record |\n| Projection scanned decode | 580.3 B/record | 576.0 B/record |\n| Projection transient allocation | 3,125 B/record | 3,434 B/record |\n\nThe projection process benchmark is a relative measure inside the test binary,\nnot the deployed proxy's RSS. At 100,000 records it\nmeasured 94.6 MiB process RSS and a\n66.0 MiB projection delta; at\n10,000 records it measured\n40.6 MiB process RSS and a\n12.0 MiB delta. The test binary and its\nlinked packages are part of the absolute figure.\n\nA fast-response run reached a 119.0 MiB\npeak with 66,813 durable rows while no\ndashboard projection was preloaded. Use the projection delta above for the\nretained analytical cost, not the loaded-process peak as a substitute.\n\n## Query and metadata paths\n\nThe query benchmarks seed a 100,000-row\nscratch database and decode a 200-row\npage. These are single-iteration measurements on a shared host, so small\ndifferences are not meaningful.\n\n| Query | Before cursor | With cursor | Allocations before cursor |\n| --- | ---: | ---: | --- |\n| Provider equality | 4.24 ms | 3.85 ms | 1.38 MB, 5,455 allocs |\n| Model equality | 2.81 ms | 2.93 ms | 1.38 MB, 5,445 allocs |\n| Client equality | 36.52 ms | 18.73 ms | 1.38 MB, 5,442 allocs |\n| Key-hash equality | 33.68 ms | 18.28 ms | 23.5 KB, 265 allocs |\n| Conversation equality | 40.16 ms | 21.73 ms | 23.2 KB, 264 allocs |\n| Status equality | 38.98 ms | 20.99 ms | 698.1 KB, 2,942 allocs |\n\nThe request metadata path performs one bounded metadata decode; the allocation\ncolumn is measured per call.\n\n| Metadata body | Time per request | Throughput | Allocations |\n| --- | ---: | ---: | ---: |\n| 1 KiB | 428 ns | 2,580.8 MB/s | 16 B, 1 alloc |\n| 100 KiB | 4,808 ns | 21,314.0 MB/s | 16 B, 1 alloc |\n| 1 MiB | 75,397 ns | 13,908.4 MB/s | 16 B, 1 alloc |\n\n## Implementation benchmarks\n\nThese are the isolated benchmark results the design notes cite. They are current\nmeasurements from the same run as the tables above, not a historical before and\nafter across revisions.\n\n| Benchmark | Time | Bytes per op | Allocs per op |\n| --- | --- | --- | --- |\n| `BenchmarkAggregateFold/chart` | 2.74 ms | 136,736 B | 28 |\n| `BenchmarkAggregateFold/explorer` | 4.38 ms | 209,696 B | 37 |\n| `BenchmarkAggregateFold/explorer_tool` | 3.73 ms | 807,840 B | 38 |\n| `BenchmarkAggregateFold/chart_window` | 413,833 ns | 17,616 B | 28 |\n| `BenchmarkHandleLogPage/empty/limit_60` | 1.70 ms | 987,376 B | 3,533 |\n| `BenchmarkHandleLogPage/sql_provider/limit_60` | 1.95 ms | 550,080 B | 2,645 |\n| `BenchmarkHandleLogPage/go_status_class/limit_60` | 1.89 ms | 903,504 B | 2,686 |\n| `BenchmarkHandleLogPage/go_status_class_5xx/limit_60` | 4.88 ms | 1,819,616 B | 21,125 |\n| `BenchmarkHandleLogPage/go_tool_missing/limit_60` | 5.00 ms | 1,883,032 B | 29,360 |\n| `BenchmarkHandleLogPage/empty/limit_200` | 4.26 ms | 2,889,608 B | 7,999 |\n| `BenchmarkHandleLogPage/sql_provider/limit_200` | 4.92 ms | 2,888,720 B | 7,993 |\n| `BenchmarkHandleLogPage/go_status_class/limit_200` | 4.14 ms | 2,890,912 B | 8,015 |\n| `BenchmarkHandleLogPage/go_status_class_5xx/limit_200` | 3.88 ms | 1,889,744 B | 21,029 |\n| `BenchmarkHandleLogPage/go_tool_missing/limit_200` | 4.72 ms | 1,957,512 B | 29,258 |\n| `BenchmarkProjectionMetricAppend/history_100000` | 11,393 ns | 960 B | 5 |\n| `BenchmarkProjectionMetricAppend/history_1000000` | 11,716 ns | 960 B | 5 |\n| `BenchmarkProjectionMetricAppend/append_cross_100000` | 1.58 ms | 3,956,976 B | 14 |\n| `BenchmarkProjectionMetricAppend/append_cross_1000000` | 1.54 ms | 3,956,976 B | 14 |\n| `BenchmarkAggregateUnchanged/identity_marshal` | 33,009 ns | 6,456 B | 6 |\n| `BenchmarkAggregateUnchanged/unchanged` | 1,338 ns | 0 B | 0 |\n| `BenchmarkKPI/records_10000/miss` | 403,272 ns | 83,632 B | 6 |\n| `BenchmarkKPI/records_10000/hit` | 1,024 ns | 32 B | 3 |\n| `BenchmarkKPI/records_100000/miss` | 7.47 ms | 804,528 B | 6 |\n| `BenchmarkKPI/records_100000/hit` | 1,986 ns | 32 B | 3 |\n| `BenchmarkKPI/records_1000000/miss` | 91.84 ms | 8,005,296 B | 6 |\n| `BenchmarkKPI/records_1000000/hit` | 2,153 ns | 32 B | 3 |\n| `BenchmarkObserveModelNames4096` | 7.59 ms | 3,613,216 B | 70,975 |\n| `BenchmarkObserveModelNameEvent/rules0` | 29,568 ns | 3,136 B | 19 |\n| `BenchmarkObserveModelNameEvent/rules64` | 99,814 ns | 26,992 B | 29 |\n| `BenchmarkObserveModelNameEventWired/rules0` | 15,688 ns | 3,136 B | 19 |\n| `BenchmarkObserveModelNameEventWired/rules64` | 76,644 ns | 31,088 B | 30 |\n| `BenchmarkSkipJSONString/plain/102400` | 9,647 ns | 0 B | 0 |\n| `BenchmarkSkipJSONString/escaped/102400` | 8,821 ns | 0 B | 0 |\n| `BenchmarkSkipJSONString/tail/102400` | 6,882 ns | 0 B | 0 |\n| `BenchmarkSkipJSONString/plain/1048576` | 84,535 ns | 0 B | 0 |\n| `BenchmarkSkipJSONString/escaped/1048576` | 86,790 ns | 0 B | 0 |\n| `BenchmarkSkipJSONString/tail/1048576` | 67,966 ns | 0 B | 0 |\n| `BenchmarkRequestMetadataShapes/escaped` | 629,819 ns | 35,552 B | 370 |\n| `BenchmarkRequestMetadataShapes/many_messages` | 254,854 ns | 32,280 B | 30 |\n| `BenchmarkRequestMetadataShapes/multimodal` | 168,469 ns | 16,240 B | 73 |\n| `BenchmarkRequestMetadataShapes/tool_schema` | 85,121 ns | 3,480 B | 22 |\n| `BenchmarkRequestMetadataShapes/digit_description` | 73,440 ns | 2,648 B | 6 |\n| `BenchmarkAnalyzerFeed/content` | 3,503 ns | 0 B | 0 |\n| `BenchmarkAnalyzerFeed/reasoning` | 2,881 ns | 0 B | 0 |\n| `BenchmarkAnalyzerFeed/tool_call` | 6,972 ns | 240 B | 1 |\n| `BenchmarkAnalyzerFeed/usage` | 3,131 ns | 0 B | 0 |\n| `BenchmarkAnalyzerFeed/negative` | 1,798 ns | 0 B | 0 |\n| `BenchmarkAnalyzerToolNameDedupe/10000` | 4.88 ms | 192,096 B | 10,121 |\n| `BenchmarkAnalyzerToolNameDedupe/100000` | 48.39 ms | 694,264 B | 100,220 |\n\n## Reproduce\n\n`scripts/perf.sh` owns the repeatable local run: `bench`, `stress`, `streaming`,\n`sustained`, `image`, or `all`. `scripts/perf.sh docs` runs the full set,\nwrites `perf/results.json`, and regenerates this page. It refuses a dirty tree\nunless `PERF_ALLOW_DIRTY=1` is set, because published numbers must name a\ncommit.\n\nThe full run uses the documented levels and durations:\n5 seconds for each\nfast stage, 300\nseconds for each sustained level, and\n60 seconds for\neach streaming throughput level. Override the level lists and durations with\n`PERF_FAST_LEVELS`, `PERF_SUSTAINED_LEVELS`, `PERF_STREAMING_LEVELS`,\n`PERF_FAST_DURATION`, `PERF_SUSTAINED_DURATION`, `PERF_STREAMING_DURATION`,\n`PERF_STREAMING_HOLD` and `PERF_STREAMING_CHUNKS`. The bundle records what ran;\na changed run changes the page.\n\nThe individual commands below are the same evidence path. Use a fresh\n`DEV_COPY_DB=0` instance for each workload. Never target the main instance on\nport 8080. The stress harness verifies that the target is the private\n`scripts/dev.sh` instance before sending traffic.\n\n```sh\n(\n  set -e\n  trap 'scripts/dev.sh stop' EXIT\n  export MILLIVOLT_OPERATOR_TOKEN='dev-instance-credential'\n  DEV_COPY_DB=0 scripts/dev.sh\n  go run ./cmd/stress -target http://127.0.0.1:8081 \\\n    -concurrency 1,8,32,128 -duration 5s -stream-duration 0\n)\n```\n\nThe isolated benchmarks use the test overlay:\n\n```sh\nscripts/check.sh go test -run='^$' -bench='BenchmarkProjectionFootprint|BenchmarkStoreDiskBytes' \\\n  -benchtime=1x -count=1 ./internal/web\nscripts/check.sh go test -run='^$' -bench='BenchmarkProjectionProcessRSS' \\\n  -benchtime=1x -count=1 ./internal/web\nscripts/check.sh go test -run='^$' -bench='BenchmarkStorageWriter' \\\n  -benchtime=2s -benchmem -count=1 ./internal/storage\nscripts/check.sh go test -run='^$' -bench='BenchmarkQueryBeforeEquality' \\\n  -benchtime=1x -benchmem -count=1 ./internal/storage\nscripts/check.sh go test -run='^$' -bench='Benchmark(RequestMetadata|ProxyDurableContention)' \\\n  -benchtime=2s -benchmem -count=1 ./internal/proxy\n```\n\nThe image measurements use a disposable local image:\n\n```sh\ndocker build --platform linux/amd64 -t millivolt-perf .\ndocker image inspect millivolt-perf --format '{{.Size}}'\ndocker save millivolt-perf | gzip -9 | wc -c\n```\n\n## Limitations\n\n- The host was shared. Other workloads can change absolute rates and latency.\n- The upstream was a local synthetic server. Provider latency, TLS, retries,\n  payload shape, and real identity cardinality are not represented.\n- These are short closed-loop bursts, not sustained production capacity. No\n  result here is a capacity ceiling or a guarantee.\n- The streaming concurrency table is a short ramp on a 10-frame, roughly\n  1-second fixture. The streaming throughput table is a\n  60-second\n  per-level ramp on a\n  100-frame, roughly 1-second\n  fixture. Both are synthetic-fixture measurements, not universal maxima. The\n  throughput table's\n  1,024-client level is above the\n  example `max_conns_per_host` of 512 and measures queueing; it is a\n  fixed level list, not an automatic saturation search. Its token rate is the\n  fixture's usage count, not provider-token throughput.\n- The 300-second sustained sweep uses the fast-response fixture with no\n  intentional stream hold (`-stream-duration 0`). A level with durable drops is\n  an overload observation, not a maximum streaming rate. The streaming\n  throughput ramp is the only sustained held-stream run; it stops at its fixed\n  levels and does not search beyond the largest listed level.\n- Performance checks are manual (`scripts/perf.sh docs`), not CI. Each level is\n  one run per invocation on one host; there is no repetition or variance study.\n- Durable accounting is best-effort. The fast stages happened to remain exact;\n  the overload benchmark intentionally does not.\n- Container-wide CPU/RSS, cold-start time, browser rendering, arm64 image size,\n  disk throughput, and a full dashboard preload over a large authorized history\n  were not measured for this page.\n- The image archive is a local artifact, not a published registry digest.\n- Do not compare these numbers directly across differing hosts, workloads, or\n  revisions.\n"
    },
    {
      "path": "SECURITY.md",
      "slug": "security",
      "output": "security.html",
      "markdown": "security.md",
      "url": "https://millivolt.llm4people.dev/security.html",
      "markdown_url": "https://millivolt.llm4people.dev/security.md",
      "title": "Security",
      "description": "millivolt is a trusted-operator tool, not a multi-user security boundary. It has no authorization roles or tenant isolation. The whole dashboard is gated...",
      "group": "Operate",
      "order": 15,
      "bytes": 11740,
      "sha256": "78fa0ba76bcc57c95119ac19a181892c777f31e1294b948dd08878af506751d9",
      "sections": [
        {
          "heading": "Deployment boundary",
          "id": "deployment-boundary",
          "text": "millivolt is a trusted-operator tool, not a multi-user security boundary. It has no authorization roles or tenant isolation. The whole dashboard is gated by the shared MILLIVOLT_OPERATOR_TOKEN environment credential and denied while it is unset (see operator access ): there is one operator identity, no per-user accounts and no audit trail of who acted. Only the GET /healthz liveness and GET /readyz readiness probes, the POST /session login handshake, origin-root brand/PWA assets and transparent inference stay open at the application gate; the canonical open-path list is operator access . The upstream API key is forwarded for inference; it does not secure the dashboard or administration. The supplied listen address binds all interfaces. Prefer an explicit loopback listen for local use. Before network exposure, restrict access with network controls and an appropriately authenticated ingress. Protect the entire operator surface, including dashboard/bootstrap/live records, SQL, Debug, exports, Settings, Pause, Limits, purge and restart. Inference clients can also change provider-wide limits through request headers. For Docker, publish on host loopback, for example -p 127.0.0.1:8080:808",
          "context": ""
        },
        {
          "heading": "Upstream destinations and credentials",
          "id": "upstream-destinations-and-credentials",
          "text": "X-Proxy-Base-URL selects an HTTP(S) destination. An unrestricted caller can therefore make the proxy contact destinations reachable from its host. allowed_base_urls constrains accepted upstream targets: an entry admits the same scheme, host and port (with the scheme's default port filled in) and that entry's path and its children. A port-less entry therefore admits the default port only, not every port on that host. Use trusted destinations and appropriate egress controls. This is not a DNS/IP isolation sandbox. The proxy does not follow upstream redirects. Ordinary metrics group credentials by SHA256 rather than retaining the raw key. Known secret and configured authentication headers are redacted in retained metadata/captures without changing forwarded headers. This does not sanitize arbitrary text: request/response bodies, URLs, error messages, model names or user-supplied labels can contain sensitive data. Preview capture and Debug capture are opt-in, but enabling them can persist that data.",
          "context": ""
        },
        {
          "heading": "Client identity is a claim, not an authentication",
          "id": "client-identity-is-a-claim-not-an-authentication",
          "text": "X-Proxy-Client (and the classified client derived from SDK and user-agent headers when it is absent) is chosen by the caller. Nothing verifies it: a request that sends another client's label is treated as that client by every feature that scopes on client - request_overrides (so it inherits that client's header and token-ceiling rules), sub_conversations (so it gets that client's field mapping and strip list), Debug capture sessions, pause holds including the \"new clients\" comparison, and the Cursor parked-run scope. The recorded client, and therefore dashboard grouping and the client filter, also follow the claim. The recorded client address is likewise a hint. client_ip records the first X-Forwarded-For element when that header is present and the socket peer otherwise; the value is diagnostic, never verified, and a directly reachable caller can set it. Do not treat client_ip as a verified source for rate limiting, allowlisting or attribution outside the proxy. The operator gate's brute-force limiter is a separate key: it reads the address the immediate hop appended (the last X-Forwarded-For element) and falls back to the socket address, so it distinguishes clients behind a correc",
          "context": ""
        },
        {
          "heading": "Administrative data and resource limits",
          "id": "administrative-data-and-resource-limits",
          "text": "SQL is restricted to read-only queries with execution/output limits, not a sandbox for adversarial resource consumption. Debug has bounded capture sizes and retention, but captured bodies remain sensitive. Exports and backups can outlive those retention settings. Metrics storage is asynchronous and best-effort. Queue overflow/write failures can lose records; this is not a tamper-proof, complete compliance audit log. Do not rely on the dashboard as the sole security or billing record. See operations and limitations .",
          "context": ""
        },
        {
          "heading": "Code scanning",
          "id": "code-scanning",
          "text": "GitHub code scanning (CodeQL) reports on pull requests and the default branch. Alerts are triaged against the deployment boundary , not dismissed for convenience. True positives are fixed and covered by regression tests; accepted false positives record their rationale in the alert instead of being hidden by a broad path exclusion. The current categories and their trust-boundary evidence: Operator-only read-only SQL ( internal/storage/query_admin.go ). The query console sits behind the operator gate, accepts one SELECT, and enforces execution time, row, column and result-byte limits. The operator is already trusted with the database, so this is not an unauthenticated SQL surface. JSON, SSE and gzip response writers. The operator surfaces behind the gate encode the proxy's own output, and framing and compression state are bounded by the response-size guard. Two writers are intentionally reachable without the operator gate: the /healthz and /readyz probe JSON and the transparent inference SSE relay, which streams the upstream response to a client that supplied its own provider credentials. Neither exposes operator data (the readiness reason names queue depth and flush failures only), ",
          "context": ""
        },
        {
          "heading": "Scope",
          "id": "scope",
          "text": "In scope: the proxy, dashboard, MCP server, container image, and repository automation. Out of scope: findings that require a compromised host, an operator who already holds the credential, a misconfigured ingress, or a third-party provider. A report that depends on the documented trusted-operator boundary must show how that boundary is crossed.",
          "context": ""
        },
        {
          "heading": "Safe harbor",
          "id": "safe-harbor",
          "text": "The maintainers will not pursue or support legal action for good-faith research that stays within this scope, avoids privacy violations, service disruption, and data destruction, and allows reasonable time to fix the issue before disclosure.",
          "context": ""
        },
        {
          "heading": "Reporting a vulnerability",
          "id": "reporting-a-vulnerability",
          "text": "Do not publish credentials, private request content, or actionable exploit details in a public issue. Use the repository's enabled private vulnerability reporting channel. Include the affected revision, deployment assumptions, impact, and a minimal reproduction using neutral local fixtures. Test only systems you own or are explicitly authorized to assess.",
          "context": ""
        },
        {
          "heading": "Supported versions",
          "id": "supported-versions",
          "text": "Security fixes target the latest published release. The 0.x series is in active development; older releases are not backported. Version Supported Latest published 0.x release Yes Older releases No",
          "context": ""
        },
        {
          "heading": "Disclosure process",
          "id": "disclosure-process",
          "text": "Reports are acknowledged on a best-effort basis; no response-time SLA is promised. Maintainers will validate the report, prepare a fix, publish a GitHub security advisory, and credit the reporter unless they prefer otherwise. Please allow time for a coordinated fix before public disclosure. Dependency review and a scheduled Go vulnerability scan run in CI. A clean scan is not a security guarantee, and neither replaces a private report. GitHub documents private vulnerability reporting .",
          "context": ""
        }
      ],
      "markdown_text": "# Security\n\n## Deployment boundary\n\nmillivolt is a trusted-operator tool, not a multi-user security boundary. It\nhas no authorization roles or tenant isolation. The whole dashboard is gated\nby the shared `MILLIVOLT_OPERATOR_TOKEN` environment credential and denied\nwhile it is unset (see [operator access](docs/routes.md#operator-access)):\nthere is one operator identity, no per-user accounts and no audit trail of\nwho acted. Only the `GET /healthz` liveness and `GET /readyz` readiness probes,\nthe `POST /session` login handshake, origin-root brand/PWA assets and transparent\ninference stay open at the application gate; the canonical open-path list is\n[operator access](docs/routes.md#operator-access). The upstream API key is\nforwarded for inference; it does not secure the dashboard or administration.\n\nThe supplied listen address binds all interfaces. Prefer an explicit loopback\nlisten for local use. Before network exposure, restrict access with network\ncontrols and an appropriately authenticated ingress. Protect the entire operator\nsurface, including dashboard/bootstrap/live records, SQL, Debug, exports,\nSettings, Pause, Limits, purge and restart. Inference clients can also change\nprovider-wide limits through request headers.\n\nFor Docker, publish on host loopback, for example `-p 127.0.0.1:8080:8080`.\nA non-root container and a public image do not authenticate callers or make a\npublicly reachable operator listener safe. Protect persistent config/data\nvolumes as sensitive state, including backups and debug captures.\n\nBrowser same-origin mutation checks and framing denial are defense in depth\nbehind the operator credential, not a substitute for it. The live metrics feed\ndoes not opt into cross-origin\nbrowser sharing; the dashboard uses a same-origin EventSource authenticated\nby the HttpOnly session cookie. This does not\nprevent direct non-browser reads or secure a publicly reachable listener.\nExplicit non-browser calls remain supported; gated endpoints need the\n`Authorization: Bearer` credential or a session cookie minted through\n`POST /session`. The `/mcp` endpoint is the exception: it requires the\noperator credential as a Bearer header and refuses a session cookie alone with\n`403`, because the caller's credential is forwarded on its internal calls.\n\n## Upstream destinations and credentials\n\n`X-Proxy-Base-URL` selects an HTTP(S) destination. An unrestricted caller can\ntherefore make the proxy contact destinations reachable from its host.\n`allowed_base_urls` constrains accepted upstream targets: an entry admits the\nsame scheme, host and port (with the scheme's default port filled in) and that\nentry's path and its children. A port-less entry therefore admits the default\nport only, not every port on that host. Use trusted destinations and\nappropriate egress controls. This is not a DNS/IP isolation sandbox.\nThe proxy does not follow upstream redirects.\n\nOrdinary metrics group credentials by SHA256 rather than retaining the raw key.\nKnown secret and configured authentication headers are redacted in retained\nmetadata/captures without changing forwarded headers. This does not sanitize\narbitrary text: request/response bodies, URLs, error messages, model names or\nuser-supplied labels can contain sensitive data. Preview capture and Debug\ncapture are opt-in, but enabling them can persist that data.\n\n## Client identity is a claim, not an authentication\n\n`X-Proxy-Client` (and the classified client derived from SDK and user-agent\nheaders when it is absent) is chosen by the caller. Nothing verifies it: a\nrequest that sends another client's label is treated as that client by every\nfeature that scopes on client - `request_overrides` (so it inherits that\nclient's header and token-ceiling rules), `sub_conversations` (so it gets that\nclient's field mapping and strip list), Debug capture sessions, pause holds\nincluding the \"new clients\" comparison, and the Cursor parked-run scope. The\nrecorded client, and therefore dashboard grouping and the `client` filter, also\nfollow the claim.\n\nThe recorded client address is likewise a hint. `client_ip` records the first\n`X-Forwarded-For` element when that header is present and the socket peer\notherwise; the value is diagnostic, never verified, and a directly reachable\ncaller can set it. Do not treat `client_ip` as a verified source for\nrate limiting, allowlisting or attribution outside the proxy. The operator\ngate's brute-force limiter is a separate key: it reads the address the\nimmediate hop appended (the last `X-Forwarded-For` element) and falls back to\nthe socket address, so it distinguishes clients behind a correct ingress but a\ndirectly reachable caller can still pick its own bundle.\n\nThe example ingress trusts exactly one loopback hop (`set_real_ip_from\n127.0.0.1`, [deploy/nginx.conf](deploy/nginx.conf)) and its `allow` lists\nevaluate that rewritten address. A caller that can already reach the loopback\nlistener therefore chooses the address the lists see: they separate remote\nnetworks from each other and from local callers, not local callers from each\nother. Treat a location allowlist as reachability control for a network, not as\nidentity.\n\nTreat client scoping as a way to separate your own tools and traffic, not as a\nsecurity boundary between mutually untrusted parties. A proxy reachable by\nsomeone who should not act as another client needs that separation enforced\noutside these labels: distinct `allowed_base_urls`, distinct upstream\ncredentials per caller, or a separate proxy instance. Credential-class header\nnames are refused in `request_overrides` and redacted in retained data, so a\nclaimed label cannot by itself move an upstream secret; the exposure it does\ncreate is the policy attached to the label, not the credential behind it.\n\nToken-refresh handback responses contain credentials in the error body for the client to adopt.\nDo not publish them, browser exports, databases, backups, local config,\nlogin-script output or screenshots containing private history.\n\nProvider favicons can make browser requests to Google's favicon service, exposing\nthe provider hostname and the browser's network address to that service.\n`referrerpolicy=\"no-referrer\"` omits the dashboard referrer, not the requested\nhostname. Hostname syntax checks do not establish that every qualified provider\nlabel is public. The documentation capture workflow blocks all external browser\nrequests; that isolation is not the ordinary dashboard's network policy.\n\n## Administrative data and resource limits\n\nSQL is restricted to read-only queries with execution/output limits, not a\nsandbox for adversarial resource consumption. Debug has bounded capture sizes\nand retention, but captured bodies remain sensitive. Exports and backups can\noutlive those retention settings.\n\nMetrics storage is asynchronous and best-effort. Queue overflow/write failures\ncan lose records; this is not a tamper-proof, complete compliance audit log.\nDo not rely on the dashboard as the sole security or billing record. See\n[operations and limitations](docs/operations.md#storage-and-accounting).\n\n## Code scanning\n\nGitHub code scanning (CodeQL) reports on pull requests and the default branch.\nAlerts are triaged against the [deployment boundary](#deployment-boundary), not\ndismissed for convenience. True positives are fixed and covered by regression\ntests; accepted false positives record their rationale in the alert instead of\nbeing hidden by a broad path exclusion. The current categories and their\ntrust-boundary evidence:\n\n- Operator-only read-only SQL (`internal/storage/query_admin.go`). The query\n  console sits behind the operator gate, accepts one SELECT, and enforces\n  execution time, row, column and result-byte limits. The operator is already\n  trusted with the database, so this is not an unauthenticated SQL surface.\n- JSON, SSE and gzip response writers. The operator surfaces behind the gate\n  encode the proxy's own output, and framing and compression state are bounded\n  by the response-size guard. Two writers are intentionally reachable without\n  the operator gate: the `/healthz` and `/readyz` probe JSON and the transparent\n  inference SSE relay, which streams the upstream response to a client that\n  supplied its own provider credentials. Neither exposes operator data (the\n  readiness reason names queue depth and flush failures only), so this category\n  is not an authentication bypass.\n- Bounded allocations (`cmd/proxy/mcp.go`, `internal/sse/frames.go`). The MCP\n  recorder cap is the fixed `mcp.MaxResponseBytes` read budget (64 MiB) plus one\n  byte, not a configurable limit. The SSE frame's requested size is the\n  marshaled payload length plus the fixed framing overhead; `slices.Concat` may\n  round the capacity up to the allocator's size class. The payload is bounded by\n  the relay's scanner and encoder frame caps and the response-size guard. Input\n  is rejected at those bounds before the sized allocation, so neither is an\n  attacker-controlled unbounded size.\n\nThe operator-cookie and integer-conversion findings were true positives and are\nfixed. The operator session cookie now sets `Secure` when the request arrived\nover TLS or through an https-forwarding ingress. The jsonnum, config and\nthrottle paths now parse or bound at the target width, with regression tests.\n\nThe allocation findings are closed by construction, using overflow-safe capacity\nowners. The operator SQL console is an accepted boundary, and the transparent\nresponse-writer wrappers are false positives from interface fan-out; their\nalerts are dismissed with a recorded reason. Dismissing or resolving a\ncode-scanning alert is a maintainer action in the GitHub security UI; this note\nrecords triage rationale and does not dismiss any alert automatically.\n\n## Scope\n\nIn scope: the proxy, dashboard, MCP server, container image, and repository\nautomation. Out of scope: findings that require a compromised host, an operator\nwho already holds the credential, a misconfigured ingress, or a third-party\nprovider. A report that depends on the documented trusted-operator boundary must\nshow how that boundary is crossed.\n\n## Safe harbor\n\nThe maintainers will not pursue or support legal action for good-faith research\nthat stays within this scope, avoids privacy violations, service disruption, and\ndata destruction, and allows reasonable time to fix the issue before disclosure.\n\n## Reporting a vulnerability\n\nDo not publish credentials, private request content, or actionable exploit\ndetails in a public issue.\n\nUse the repository's enabled\n[private vulnerability reporting](https://github.com/LLM-4-People/millivolt/security/advisories/new)\nchannel.\n\nInclude the affected revision, deployment assumptions, impact, and a minimal\nreproduction using neutral local fixtures. Test only systems you own or are\nexplicitly authorized to assess.\n\n## Supported versions\n\nSecurity fixes target the latest published release. The `0.x` series is in\nactive development; older releases are not backported.\n\n| Version | Supported |\n| --- | --- |\n| Latest published 0.x release | Yes |\n| Older releases | No |\n\n## Disclosure process\n\nReports are acknowledged on a best-effort basis; no response-time SLA is\npromised. Maintainers will validate the report, prepare a fix, publish a GitHub\nsecurity advisory, and credit the reporter unless they prefer otherwise. Please\nallow time for a coordinated fix before public disclosure.\n\nDependency review and a scheduled Go vulnerability scan run in CI. A clean scan\nis not a security guarantee, and neither replaces a private report.\n\nGitHub documents [private vulnerability reporting](https://docs.github.com/en/code-security/how-tos/report-and-fix-vulnerabilities/configure-vulnerability-reporting/configure-for-a-repository).\n"
    },
    {
      "path": "docs/architecture.md",
      "slug": "docs/architecture",
      "output": "docs/architecture.html",
      "markdown": "docs/architecture.md",
      "url": "https://millivolt.llm4people.dev/docs/architecture.html",
      "markdown_url": "https://millivolt.llm4people.dev/docs/architecture.md",
      "title": "Architecture and ownership",
      "description": "millivolt is one Go HTTP service with an embedded, no-build dashboard. The client-facing protocol and upstream relay/translation are separate boundaries;...",
      "group": "Extend",
      "order": 16,
      "bytes": 61078,
      "sha256": "c490f5268773d9787b12d1f9af5c4d0a94651c62783bbcd69898d4b9408217ed",
      "sections": [
        {
          "heading": "Source map",
          "id": "source-map",
          "text": "Owner Responsibility cmd/proxy Config/CLI, dependency wiring, routes, process lifecycle. Restart, log, backup and operator-gate handlers have separate existing files. internal/config Config/defaults/validation, split by subject into config_types.go , config_defaults.go , config_clone.go , config_load.go , config_validate.go and config_validate_overrides.go ; schema, YAML generation, revision-checked Settings, model-rule execution, and the credential-class header vocabulary and redactor in credentials.go . internal/settingsdoc Renders the generated settings reference from Schema() , the defaults passed through the YAML writer and the proxy flag registration; cmd/docgen exposes it as -write and -check , and the config suite fails when the page drifts. internal/backup Streamed self-checked operator archive format (VACUUM INTO snapshot + zstd + SHA-256), with byte- and file-backed database members. One decoder core serves byte and file callers; restore stages its upload and decoded database as private files instead of heap copies. params/params.go owns the backup/restore query keys, boolean spelling, restore modes and archive magic shared by the HTTP handlers and mvctl ; the leaf impor",
          "context": ""
        },
        {
          "heading": "Logging",
          "id": "logging",
          "text": "internal/logging is the one owner of process log lines. It wraps the standard logger's sink and gives a request-scoped line the record id minted at the read boundary, so the line joins its stored row, capture and neighbouring lines. Process and operator-state lines pass no id. log.Fatal exits and the earliest flag errors that precede the process logger stay direct.",
          "context": ""
        },
        {
          "heading": "Release identity and promotion",
          "id": "release-identity-and-promotion",
          "text": "version.go owns VERSION validation and SemVer precedence. The workflow owns the promotion gate and release publication: unit , browser and container run the full gate on all testing pull requests, code-bearing testing pushes, and manually pushed v* tags, plus Dependabot's main PRs; docs and site-only pushes use docs.yml . The three gate jobs start independently and required aggregates them. required reuses that gate for ordinary promotions by requiring the head to be the current testing tip, main to be already merged back into it, a successful full-gate record for that exact commit or for the closest gated testing commit when every path since it is docs/site-only, and a VERSION newer than every tag for non-Dependabot code-bearing promotions. A non-Dependabot promotion also requires a successful escalation run (forced full-race sweep plus the repeated clock-sensitive flake sweep) for the reviewed head; the proof fails closed while that run is missing, pending, failed, from another workflow, branch or commit. Pending exact check runs get a short bounded wait and the proof fails closed if they are still pending; let the testing push gate finish before opening or re-running a promotion",
          "context": ""
        },
        {
          "heading": "Request and scheduling path",
          "id": "request-and-scheduling-path",
          "text": "readRequest retains bounded original bytes and calls the single metadata decoder. Ordinary content is measured without retaining decoded prompt/schema trees; opt-in previews stay bounded. Exceptional decoder compatibility belongs at that owner, not a second routing parser. Before the typed decode, parseLLMRequest bounds decoded JSON-string expansion: valid UTF-8 and JSON escapes decode to no more bytes than their spelling, so only raw invalid UTF-8 can consume the small allowance (the standard decoder writes a three-byte U+FFFD per invalid byte). A larger expansion is rejected before materializing; malformed JSON keeps its passthrough contract, and small invalid sequences still pass through. parseLLMRequestFast is a narrow lexical pre-pass for a minimal top-level object: model , stream , messages with printable-ASCII role and content strings, and system . It extracts the same routing and composition fields without the typed decode and delegates every other shape, including all parameter collections, escapes, duplicates, content part arrays, and preview capture, to the existing decoder and its bounds. Differential tests pin byte-for-byte record and rejection equivalence. SkipJSONStr",
          "context": ""
        },
        {
          "heading": "Finalized records, pending lifecycle and replay",
          "id": "finalized-records-pending-lifecycle-and-replay",
          "text": "PublishLive(begin/update) snapshots pending state without adding durable rows. The proxy registers its deferred Record before publishing begin , so a subscriber that fails while handling the begin event cannot leave a permanent in-flight row. Buffer.Record atomically finalizes the row, retires pending state, updates its gauge/revision and emits end. Exactly one finalized record per request is the accounting unit; proxy-owned IDs cannot collide with reused client request IDs. A debug capture registers its pending sidecar marker in debugRuntime before that publish and encodes/saves after it, so the sidecar write delays neither the live end nor durable accounting. A drawer fetch for the id waits on the marker, then reads the authoritative store; a resolved marker without a row keeps the normal 404. Buffer.Record , PublishLive and Backfill share the one record-retention pass ( internal/metrics/retain.go ) at that boundary. It bounds client-controlled paths/methods and provider-controlled model/request/finish/error text, tool names and attempt metadata; normal values stay byte-identical. The bounds and the UTF-8 cut marker are documented in the protocol . Existing lock order keeps seque",
          "context": ""
        },
        {
          "heading": "Durable writes and deletion",
          "id": "durable-writes-and-deletion",
          "text": "Store.Recorder(buffer) publishes the live final record and nonblocking enqueue under one short producer fence. SQLite is the durable authority; enqueue overflow and failed batches remain visible best-effort losses. internal/storage/health.go is the one owner of that loss accounting and of the pipeline's liveness. Every discard is counted under exactly one cause ( overflow , after_close , panic , flush_failed ); Dropped() sums them for the dashboard counter, and the exposition renders each cause so alerting can separate overload from shutdown, a panic and a failing database. The same owner publishes the oldest queued record's arrival and stamps every flush attempt, so /readyz can tell a stalled writer from a merely idle one: a non-empty queue whose oldest record, or last successful flush, has passed one flush interval plus the wedge window (four intervals clamped to 30 seconds and 2 minutes) reads wedged. The interval on top is the record's own cadence, so a record inside it never convicts and a long cadence cannot hide a stuck writer for longer than that. The arrival stamp comes from the producer when the queue was empty as well as from the writer, so a writer that dies before its ",
          "context": ""
        },
        {
          "heading": "History projection and aggregate math",
          "id": "history-projection-and-aggregate-math",
          "text": "One durable analytical projection retains compact contributions, request IDs, interned dimensions and immutable sorted metric row orders. It is not a second database or a per-view history cache. Startup preload and incremental catch-up share its builder. SQLite transactions capture rowid high-water/destructive epoch/schema authority; destructive changes rebuild. Failed or canceled reads never publish stale rows or advance authority. Folds check the caller's context once per 4,096-row block, and the ring visitors use the same cadence, so an abandoned request stops without publishing a partial result. The has429 flag (and any future vocabulary-derived classification) comes from the installed vocabulary, not from a stored column, so the projection stamps the metrics classifier revision and forces a full reclassification rebuild when a reload changes it. The chart and explorer memos include the same revision in their key, so neither a stale projection nor a pre-reload memo can answer a post-reload request. Materialization runs off the projection lock with one single-flight builder; concurrent readers keep serving the previous complete snapshot and wait for that builder instead of repea",
          "context": ""
        },
        {
          "heading": "Canonical observer meaning and conversation lineage",
          "id": "canonical-observer-meaning-and-conversation-lineage",
          "text": "Go's compiled model-rule executor owns canonical grouping. Observer payloads carry exact raw-to-canonical names and a rules-content revision; only full authoritative snapshots install a new revision. Deltas, archive and Debug names merge under that revision, with recapture on conflicts. Browser dictionaries prune to loaded rows/selector needs. RE2 patterns do not execute in JavaScript. The installed observer provider is an immutable atomic holder, so SSE record/end serialization never takes the ring lock. Canonical names are memoized across observer calls under the compiled rules revision, and each known-name vocabulary caches its sorted view under a set revision. Both caches are bounded and invalidate on content change, so bootstrap polls do not re-run the rules or re-sort thousands of names. The single-name memo owns the whole payload under one mutex keyed by the rules revision, so a repeat at event rate costs one lock and one lookup. Current event and vocabulary memo costs at the 64-rule maximum are published under implementation benchmarks ( BenchmarkObserveModelNameEvent , BenchmarkObserveModelNames4096 ). The canon the observer reads is memoized per live config pointer, so co",
          "context": ""
        },
        {
          "heading": "Operator plane clients",
          "id": "operator-plane-clients",
          "text": "The HTTP client in internal/mcp owns the operator credential, request building, the bounded response read and the .error extraction that reads the flat error body regardless of the declared Content-Type. The credential is redacted from both the transport error and the failure body. Redirects are refused rather than followed: net/http strips Authorization only when the hostname changes, so a same-host different-port 307 would replay the credential and the request body. Its route paths are one closed set beside it, so no tool can name a path outside the operator plane: nothing reaches the transparent inference catch-all, and no restore-adjacent route is exposed. Three registry tools are local-only: docs_list , docs_search and docs_read answer from the internal/docs index instead of constructing an HTTP request. They share the generated page model with the published site and never touch the operator credential. The explorer's f=dim:id / s= grammar is owned once and shared by every scoped tool, and the tools never loop: a non-advancing cursor is reported as exhaustion because the aggregate scan budget is bounded per call. An empty page is deliberately not exhaustion, because the proxy ",
          "context": ""
        },
        {
          "heading": "Dashboard render owners",
          "id": "dashboard-render-owners",
          "text": "HTML embeds the canonical bootstrap builder's JSON, safely escaped in an inert data block. Transit gzip is negotiated from Accept-Encoding with only the q parameter read: unknown parameters are ignored, a bare * accepts gzip, and an explicit gzip entry outranks the wildcard; an unparseable or out-of-range qvalue refuses. Deferred external assets download alongside HTML; the Settings sheet is the one exception: its ordered settings*.js set is injected by the Settings trigger on first open, one module at a time under the same versioned URL, and single-flighted across concurrent opens. Saved hash/chart choices apply before rendering; invalid/missing seed falls back to the endpoint. Dynamic HTML/state is private/no-store. Every local /dash/ CSS/JS URL in the shell carries the content version as ?v= . On a hit, the service worker answers a /dash/ request carrying exactly that version from its stamped CacheStorage before the network; on a miss it fetches once, stores a successful response, and returns it. This is the one cache-first path. A request with no v , a stale value, or more than one v stays network-first with cache fallback, as does every brand/PWA path, so an old index cannot p",
          "context": ""
        },
        {
          "heading": "Documentation captures",
          "id": "documentation-captures",
          "text": "scripts/gallery/data.py is the one registry for every published application capture: path, title, description, scene, viewport and setup. tests/docs_capture.py owns the scene strategies, and scripts/gallery/compose.py composes the two surfaces of each plate. A new view is one registry entry plus a scene, never a second list in the capture harness or the site build. The capture writes docs/images/capture.json : per-plate bytes, dimensions and SHA-256, the verified record count and a digest of internal/web/static . The digest is the freshness gate; a dashboard change fails tests/python/gallery.py until the plates are recaptured. The same run regenerates docs/gallery.md . scripts/site_plates.py is the one upgrade from a registered image to a plate. It serves both a plain Markdown image and the generated page's semantic figure, so the published gallery, the prose guide and the Markdown source agree about number, station, route and the Black/Clear split legend. scripts/gallery/__init__.py loads and validates the registry at import, so a missing alt, duplicate path, unknown scene or bad viewport fails before a browser starts. CI runs the same module through tests/python/gallery.py .",
          "context": ""
        }
      ],
      "markdown_text": "# Architecture and ownership\n\nmillivolt is one Go HTTP service with an embedded, no-build dashboard. The\nclient-facing protocol and upstream relay/translation are separate boundaries;\nthe [compatibility matrix](adapters.md#client-and-upstream-compatibility)\ndefines their supported combinations. [Contributing](../CONTRIBUTING.md)\ncovers change and verification rules; [protocol](protocol.md) and the\n[operations overview](operations.md) describe public behavior.\n\n## Source map\n\n| Owner | Responsibility |\n| --- | --- |\n| [cmd/proxy](../cmd/proxy/main.go) | Config/CLI, dependency wiring, routes, process lifecycle. Restart, log, backup and operator-gate handlers have separate existing files. |\n| [internal/config](../internal/config/config.go) | Config/defaults/validation, split by subject into `config_types.go`, `config_defaults.go`, `config_clone.go`, `config_load.go`, `config_validate.go` and `config_validate_overrides.go`; schema, YAML generation, revision-checked Settings, model-rule execution, and the credential-class header vocabulary and redactor in `credentials.go`. |\n| [internal/settingsdoc](../internal/settingsdoc/settingsdoc.go) | Renders the generated [settings reference](settings.md) from `Schema()`, the defaults passed through the YAML writer and the proxy flag registration; [cmd/docgen](../cmd/docgen/main.go) exposes it as `-write` and `-check`, and the config suite fails when the page drifts. |\n| [internal/backup](../internal/backup/archive.go) | Streamed self-checked operator archive format (VACUUM INTO snapshot + zstd + SHA-256), with byte- and file-backed database members. One decoder core serves byte and file callers; restore stages its upload and decoded database as private files instead of heap copies. `params/params.go` owns the backup/restore query keys, boolean spelling, restore modes and archive magic shared by the HTTP handlers and `mvctl`; the leaf imports no encoder, SQLite or zstd. |\n| [internal/proxy](../internal/proxy/proxy.go) | Routing, admission integration, retry/relay, request metadata, scoped request overrides, native-run ownership, operator state/capture; inbound/outbound protocol selection and canonical paths in [protocol.go](../internal/proxy/protocol.go); the quota-pause reaction owner [quotapause.go](../internal/proxy/quotapause.go) (settleQuotaFailure/addQuotaHold) and GET/POST /admin/quota. |\n| [internal/scheduler](../internal/scheduler/scheduler.go) | Provider/key admission, retry pacing, scoped holds, and limit policies selected by provider, model, client, key hash and conversation with optional recurring schedules; the provider-wide durable quota/billing recovery gate (quota facet, probe-paced recovery). |\n| [internal/metrics](../internal/metrics/metrics.go) | Records, numeric/usage/outcome semantics, pending/ring lifecycle, observers and Prometheus. |\n| [internal/sse](../internal/sse/analyzer.go) | Streaming content/usage/TTFT inspection for Chat, Responses and Anthropic SSE ([analyzer_anthropic.go](../internal/sse/analyzer_anthropic.go)), split into decode, feed, usage, terminal, error, fill and report modules; client-facing OpenAI SSE frames and completion envelopes. |\n| [internal/format](../internal/format) | Explicit wire codecs (Chat, Responses, Anthropic) over the canonical [IR](../internal/format/ir/ir.go), Connect/protobuf framing, and the same-protocol translation facade. |\n| [internal/storage](../internal/storage/store_open.go) | Asynchronous SQLite writing, schema/read fidelity, totals, purge fence, packed snapshots and bounded queries. |\n| [internal/web](../internal/web/aggregate.go) | Embedded shell/assets, bootstrap, canonical history projection and chart/explorer/log aggregates; `aggregate.go` owns the core row model and each surface has its own `aggregate_*.go` module. The site build republishes `css/themes.css`, `js/theme_boot.js` and `js/theme_state.js` byte-for-byte, so both surfaces share one palette registry and one apply path. |\n| [cmd/mvctl](../cmd/mvctl/main.go) | the human operator client: command dispatch, per-command flags, human and JSON rendering, and destructive-action guards. It reuses `internal/mcp` for the operator HTTP client, `internal/config` for setting kinds and bands, and `internal/backup` for archive and query grammar. |\n| [internal/mcp](../internal/mcp) | The MCP tool server for the operator plane: one HTTP client owner (credential, request building, error extraction), one scope-filter owner, one tool registry served by the proxy's streamable HTTP `/mcp` endpoint, the destructive-call guards, and the streamable HTTP handler the proxy mounts at `/mcp`. It owns no analytical projection of its own; the three docs tools read `internal/docs` locally. |\n| [internal/docs](../internal/docs/docs.go) | Embedded generated documentation index: strict decode of `docs.json`, ordered list, section read and ranked search for `docs_list`, `docs_search` and `docs_read`. The checked-in file is produced by `scripts/build_site.py --write-manifest`, and a source-hash test rejects a stale copy. |\n| [scripts/gallery](../scripts/gallery) | The documentation capture registry, scene composition, capture manifest and generated gallery page. `tests/docs_capture.py` executes the scenes against a private redacted instance; `scripts/site_plates.py` upgrades registered images into the published plate chrome. |\n\n## Logging\n\n[internal/logging](../internal/logging/logging.go) is the one owner of process\nlog lines. It wraps the standard logger's sink and gives a request-scoped line\nthe record id minted at the read boundary, so the line joins its stored row,\ncapture and neighbouring lines. Process and operator-state lines pass no id.\n`log.Fatal` exits and the earliest flag errors that precede the process logger\nstay direct.\n\n## Release identity and promotion\n\n[version.go](../version.go) owns VERSION validation and SemVer precedence. The\n[workflow](../.github/workflows/check.yml) owns the promotion gate and release\npublication: `unit`, `browser` and `container` run the full gate on all\n`testing` pull requests, code-bearing `testing` pushes, and manually pushed\n`v*` tags, plus Dependabot's `main` PRs; docs and site-only pushes use\n`docs.yml`.\n\nThe three gate jobs start independently and `required` aggregates them.\n`required` reuses that gate for ordinary promotions by requiring the head to\nbe the current `testing` tip, `main` to be already merged back into it, a\nsuccessful full-gate record for that exact commit or for the closest gated\n`testing` commit when every path since it is docs/site-only, and a VERSION\nnewer than every tag for non-Dependabot code-bearing promotions.\n\nA non-Dependabot promotion also requires a successful\n[escalation](../.github/workflows/escalation.yml) run (forced full-race sweep\nplus the repeated clock-sensitive flake sweep) for the reviewed head; the\nproof fails closed while that run is missing, pending, failed, from another\nworkflow, branch or commit. Pending exact check runs get a short bounded wait\nand the proof fails closed if they are still pending; let the `testing` push\ngate finish before opening or re-running a promotion PR.\n\nDocs/site-only promotions skip the VERSION and full-gate proofs and validate\ndocs, workflow policy and the site in `required`. The `required` job has a\nten-minute budget for that path.\n\n`publish` tags the reviewed promotion merge, publishes the image and creates\nthe release without pushing `main`; a manually pushed `v*` tag ships exactly\nas tagged. `publish-testing` instead waits for `unit`, `browser` and\n`container` directly, because a testing push has no promotion proof to wait\nfor. The `main-testing-first` ruleset adds the pull-request and merge-commit\nrequirements with no bypass actors.\n\n[Contributing](../CONTRIBUTING.md#branch-workflow) owns the maintainer\nchecklist; [operations](containers.md#versions-and-images) owns the published\ntag contract.\n\n## Request and scheduling path\n\n`readRequest` retains bounded original bytes and calls the single metadata\ndecoder. Ordinary content is measured without retaining decoded prompt/schema\ntrees; opt-in previews stay bounded. Exceptional decoder compatibility belongs\nat that owner, not a second routing parser.\n\nBefore the typed decode, `parseLLMRequest` bounds decoded JSON-string\nexpansion: valid UTF-8 and JSON escapes decode to no more bytes than their\nspelling, so only raw invalid UTF-8 can consume the small allowance (the\nstandard decoder writes a three-byte U+FFFD per invalid byte). A larger\nexpansion is rejected before materializing; malformed JSON keeps its\npassthrough contract, and small invalid sequences still pass through.\n\n`parseLLMRequestFast` is a narrow lexical pre-pass for a minimal top-level\nobject: `model`, `stream`, `messages` with printable-ASCII role and content\nstrings, and `system`. It extracts the same routing and composition fields\nwithout the typed decode and delegates every other shape, including all\nparameter collections, escapes, duplicates, content part arrays, and preview\ncapture, to the existing decoder and its bounds.\n\nDifferential tests pin byte-for-byte record and rejection equivalence.\n`SkipJSONString` finds each candidate quote with one `IndexByte` and reads its\nescape parity from the backslash run before it, so escaped content is one\nforward pass instead of a restart per escape. The metadata preflight counts\nmessage elements, content parts and tool calls in one walk instead of three.\nCurrent scanner and metadata-shape costs are published under [implementation\nbenchmarks](performance.md#implementation-benchmarks)\n(`BenchmarkSkipJSONString`, `BenchmarkRequestMetadataShapes`).\n\nThe streaming analyzer scans each frame once for its classifier keys and\nclassifies lexically wherever it can. Chat tool-call frames are scanned once\nfor the element index, id and `function.name`, with the typed decode kept only\nas the fallback for a shape the lexical grammar rejects. Current frame and\ndedupe costs are published under [implementation\nbenchmarks](performance.md#implementation-benchmarks)\n(`BenchmarkAnalyzerFeed/tool_call`, `BenchmarkAnalyzerToolNameDedupe`). A\ndifferential corpus and a fuzz target compare both paths over every analyzer\nfield they touch.\n\nThe Anthropic translator independently requires valid UTF-8 input, so it\ncannot materialize the replacement expansion either. The Start stamp follows\nbody upload and precedes metadata/translation CPU. Upstream whole-document\nbuffers share one process-wide `max_inflight_response_bytes` reservation:\ntranslated non-streaming responses, the non-streaming 200 quality spool, and\nmodel-discovery pages. Admission reserves the declared Content-Length when it\nfits the bounded read cap, otherwise that cap, and refuses with a retryable\n`503` and `Retry-After` before reading the upstream body.\n\n`resolveRequestOverrides` in\n[request_overrides.go](../internal/proxy/request_overrides.go) merges the\nmatching `request_overrides` rules once per request, after routing metadata is\nknown, and its merge has exactly two application stages: the final header\nstage of `buildUpstreamRequest`, and the cursor identity headers at the native\nsend.\n\nIts body stamp is fail closed (an undecodable or oversize result relays the\noriginal bytes with one log line, prefixed by the request id minted at the\nread boundary so the line joins the stored row), and a nil resolution - the\nfeature off or nothing matched - leaves the request path byte-identical.\n\nThe sub-conversation strip is the single body-rewrite engine's second\nconsumer: it fires independently of override resolution, after the tracked\nvalue is extracted from the buffered body and before translation, with\n[conversation.go](../internal/proxy/conversation.go) owning the extraction and\nthe `k:` identity.\n\nA provider's ensured tool names are the same engine's third consumer: they are\nrestricted to the OpenAI wire, because the injected stub tools are\nchat/completions-shaped and must never reach a translated-anthropic or cursor\nbody, and they fire with any override and strip actions through one document\ndecode.\n\nImmutable config/client snapshots hot-swap for new work; old transports finish\nactive requests. Admission is provider+key scoped, with persistent limit\npolicies layered at the same grant owner. A policy intersects its non-empty\nselector dimensions and an empty dimension matches any value, so a\nprovider-only rule is the provider-wide cap while a narrower rule reuses the\nsame machinery.\n\nEvery matching policy charges its own lease, and a scheduled policy outside\nits window neither charges nor queues. Acquisition release settles exactly\nonce. The provider gate and token-bucket epoch captured at admission keep\nclearing/replacing a cap from charging another generation's reservation.\n\nA provider-to-groups index in `Scheduler` keeps each group's slot in a\nfair-waiting set: a group joins when its queued head was refused by the shared\nprovider gate (concurrency or the request/token bucket), not when it is parked\non its own pacing window, hold, anti-burst ramp or per-key cap.\n\nA release settles the gate, then drains that set once in rotating\none-grant-per-group passes, starting after the last group served, so one key\ncannot take the whole provider allowance while peers wait; the drain stops as\nsoon as a grant refills a saturated provider concurrency cap.\n\nThe lock-free fair count is the fast path's precise witness: an unrelated key\nadmits immediately while peers wait on their own predicates, and a group that\nstops on one of those predicates leaves the set.\n\nAn anti-burst epoch starts a group at allowance 1 and raises it by\n`floor((concurrency-1) * elapsed / ramp_duration)`, clamped to the target; a\nfully idle period of at least the ramp duration resets the epoch on the next\ngrant, a shorter gap continues it, and changing the flag, duration or target\nresets every epoch.\n\n[tokenrefresh.go](../internal/proxy/tokenrefresh.go) separates provider\nexchanges from response policy. Exchange adapters return credential data only;\nthe shared `resolveKey` ends successful inference refreshes with handback\nbefore admission, live publication or recording. `resolveKeyTransparent` owns\nthe model-discovery exception. The token-refresh tests cover both mechanisms,\nadoption/retry, absent replacement tokens, applicability/failure gates and\nbounded exchange responses.\n\nRetries, provider hints, hold waits and per-send deadlines have distinct\nowners. Capture context error before canceling it for cleanup. Never retry a\ncanceled caller or replay meaningful emitted stream content. Quality failure\nhandling is explicitly exceptional; see [adapters](adapters.md) and the relay\ntests.\n\nQueue visibility has one owner across both park points: the bounded admission\nFIFO and `WaitSend`'s send gate. Every parked request publishes the live\nqueued edge (`Throttled`) for the whole wait and clears it on the grant.\n\n`Stats` reports send-gate waiters separately (`SendWaiters`) and the operator\nsnapshots add them to the global and per-provider queue totals, so a 429\npacing window reads as queued work rather than idle streams; a retrying owner\nwaiting out its own Retry-After hint is queued for the same reason. Send-gate\nwaits stay separate from the admission queue bound so `max_queue_size` keeps\nits own meaning.\n\n[scheduler/storm.go](../internal/scheduler/storm.go) owns bounded rolling\nattempt counters, active-model evidence, cross-key provider/model gates and\nexclusive recovery permits. Provider activation requires all models with\nactivity inside the same window to independently qualify. Old permits cannot\nrecover newer incidents. Initial admission waits for readiness without\nreserving a probe; only the actual send boundary claims a probe after key\nadmission.\n\nStorm policy changes reset observations and wake waiters without mutating\nretained history. Each request carries an observation for its provider and\nmodel, moving distinct failed-request membership between fixed buckets across\nretries without retaining a request-ID map. No storm observation scans metrics\nhistory or waits for SQLite.\n\n[proxy/storm.go](../internal/proxy/storm.go) maps config once into scheduler\noptions and bridges existing relay/native send outcomes. A 2xx permit settles\nafter relay or before an existing quality re-ask or thinking rescue re-send,\npreventing double samples and stream replay. Safe protocol-level reason labels\ncarry no provider error bodies. The banner uses the canonical bootstrap\nbuilder and browser apply/render gates, with no client-side event arithmetic.\nStorm scheduler/proxy/config regressions and the shared UI/browser suite cover\nthese boundaries.\n\nImportant coverage includes request metadata/parser fuzz tests,\n`BenchmarkRequestMetadata`, `BenchmarkProxyRequest`,\n`TestConcurrentStreamingAccounting`, transport lifecycle tests and scheduler\nefficiency/race tests. Proxy requests must not perform history scans or wait\nfor SQLite accounting.\n\n## Finalized records, pending lifecycle and replay\n\n`PublishLive(begin/update)` snapshots pending state without adding durable\nrows. The proxy registers its deferred `Record` before publishing `begin`, so\na subscriber that fails while handling the begin event cannot leave a\npermanent in-flight row. `Buffer.Record` atomically finalizes the row, retires\npending state, updates its gauge/revision and emits end. Exactly one finalized\nrecord per request is the accounting unit; proxy-owned IDs cannot collide with\nreused client request IDs.\n\nA debug capture registers its pending sidecar marker in `debugRuntime` before\nthat publish and encodes/saves after it, so the sidecar write delays neither\nthe live end nor durable accounting. A drawer fetch for the id waits on the\nmarker, then reads the authoritative store; a resolved marker without a row\nkeeps the normal 404.\n\n`Buffer.Record`, `PublishLive` and `Backfill` share the one record-retention\npass ([internal/metrics/retain.go](../internal/metrics/retain.go)) at that\nboundary. It bounds client-controlled paths/methods and provider-controlled\nmodel/request/finish/error text, tool names and attempt metadata; normal\nvalues stay byte-identical. The bounds and the UTF-8 cut marker are documented\nin the [protocol](protocol.md).\n\nExisting lock order keeps sequence assignment and finalized publication\nordered. A feed epoch changes on restart/deletion; queued fanout retains its\nmutation epoch. Subscribers attach before snapshot capture and overflow\nretires that subscriber so reconnect can replay, rather than silently dropping\npermanent rows.\n\nWhen more than one dashboard subscriber is attached, `Record` and\n`PublishLive` attach one lazy observed-JSON cache to that published event\n([internal/metrics/event_cache.go](../internal/metrics/event_cache.go)). The\nfirst consuming stream encodes the observer result and every subscriber of\nthat same event reuses the retained bytes; an encode error is retained too, so\nall of them close and resync. Zero or one subscriber keeps the direct\n`json.Marshal` path with no cache allocation, and no cache outlives its event\nor crosses a feed epoch.\n\n`SnapshotRequest` is the shared atomic cursor/feed gate for bootstrap and SSE.\nA foreign/stale cursor requires a full snapshot; deltas are never truncated.\nSnapshots include current pending rows and their revision. Full durable-mode\nsnapshots cap the recent window, with archives fetched separately.\n\nThe browser's one upsert owner deduplicates finalized replays. Pending upserts\ncannot overwrite finalized rows or a newer pending revision of the same ID.\nThe authoritative gauge revision is independent: an older event may still add\na missing different row without rolling back the gauge. Full bootstrap closes\nthe stream before capture; only the winning refresh reopens it. Stale\nsame-feed full SSE snapshots recapture through that barrier by\nsequence/pending revision.\n\nTests live under [tests/](../tests/README.md), with Go package mirrors in\n`tests/_go/`. Use the overlay-aware `scripts/check.sh go test` entry point.\nSee buffer snapshot/stream tests and the harness sections under\n`tests/ui_harness/sections/` for the lifecycle and bootstrap races. Do not\ncollapse these row, gauge, epoch and request-ownership gates into a\nwhole-event drop rule.\n\n## Durable writes and deletion\n\n`Store.Recorder(buffer)` publishes the live final record and nonblocking\nenqueue under one short producer fence. SQLite is the durable authority;\nenqueue overflow and failed batches remain visible best-effort losses.\n\n`internal/storage/health.go` is the one owner of that loss accounting and of\nthe pipeline's liveness. Every discard is counted under exactly one cause\n(`overflow`, `after_close`, `panic`, `flush_failed`); `Dropped()` sums them\nfor the dashboard counter, and the exposition renders each cause so alerting\ncan separate overload from shutdown, a panic and a failing database.\n\nThe same owner publishes the oldest queued record's arrival and stamps every\nflush attempt, so `/readyz` can tell a stalled writer from a merely idle one:\na non-empty queue whose oldest record, or last successful flush, has passed\none flush interval plus the wedge window (four intervals clamped to 30 seconds\nand 2 minutes) reads wedged. The interval on top is the record's own cadence,\nso a record inside it never convicts and a long cadence cannot hide a stuck\nwriter for longer than that.\n\nThe arrival stamp comes from the producer when the queue was empty as well as\nfrom the writer, so a writer that dies before its first pickup still ages the\nrecord, and with no flush since boot the first accepted record ages the\nlast-success arm too, so a zero flush stamp is not a blind spot. A failed\nflush stays sticky. `/healthz` stays the liveness contract; readiness is the\nstronger answer a scheduler needs.\n\n`tests/_go/internal/storage/health.go` pins the cause split, the wedge/ready\ntransition and the disabled-store answer, and\n`tests/_go/internal/metrics/prometheus_extra.go` pins that the storage block\nis rendered per scrape rather than from the ring-revision memo.\n\nThe one writer owns transactions and incremental totals. Its insertion plan\nbinds arbitrary values, using exact zero/empty literals only for absent scalar\nwork, and preserves existing conflict/rollback semantics. Record columns,\nmigration, scanner and request-parameter presence bits must evolve together;\nexplicit zero/false is not absence.\n\nBoot migrations also own one-shot data repairs for shapes current writers\ncannot produce.\n\nThe empty-string `attempts`/`tool_names` document becomes the canonical\n`null`. The pre-0.3.34 start-anchored `ttft_ms` (`ttft_ms > 0` with\n`final_attempt_at = 0`) is zeroed because its request-start anchor was never\nstored and cannot be re-derived; a snapshot merge applies the same TTFT\ncanonicalization so a pre-repair backup cannot reintroduce the shape.\n\nEach repair is guarded by a `meta` marker and re-armed when that marker is\nabsent (a restored backup predating it). A repair that rewrites rows fires the\nprojection update trigger, advancing the epoch and invalidating the persisted\ntotals document so boot rebuilds it. Provider-alias repair applies every pair\nin one transaction, in source-key order, so a later trigger or constraint\nfailure rolls earlier label rewrites back instead of leaving history\nhalf-merged.\n\nThe durable log order is `(started_at, id)`, owned by the sole request-log\nindex `idx_requests_log`. The web log page pushes exact provider, client, key\nhash, conversation id and canonical numeric status predicates into SQL; a\nfiltered page rechecks them while scanning the ordered index.\n\nModel filters remain wholly Go-owned: canonical matching trims every stored\nspelling and applies the configured rules, so raw SQL equality would silently\ndrop a padded or rewritten stored model that still matches. Status classes,\ntools, errors and time buckets also stay in Go.\n\nWithin one dimension, repeated filters are OR alternatives and are pushed as\none SQL `OR` group when that dimension is exact; a group that cannot be pushed\nstays Go-owned so the SQL candidate set never narrows below the group's union.\n\nThe ordered export and purge use the separate `PurgeFilter` surface (provider,\nmodel, client, conversation, error type, status code, `has_error`, `debug`,\nand time bounds; no key hash), whose equality-only preview count or purge\nscans the table. Results, order and pagination stay exact without six\nper-dimension composite indexes; a time bound becomes an index range.\n\nAn upgrade that actually finds and drops one of those superseded indexes\nrepacks the database once with `VACUUM`, because SQLite otherwise only moves\nthe freed index pages to its freelist. Fresh and already-migrated databases\nskip it, and a failed reclaim logs a warning without failing startup: every\nrow stays intact and manual reclamation remains possible. A successful reclaim\nresets the projection witness, because `VACUUM` may renumber implicit rowids.\n\nThe page handler classifies active filters: when every predicate is SQL-exact\nit requests exactly the remaining rows, and Go-only predicates grow\ngeometrically from the page size to the 512-row batch cap within the 4,096-row\nscan budget. Both preserve the exclusive `(started_at, id)` cursor and `more`.\nThe candidate statement selects only the columns the residual groups read, and\nthe derived error signature and tool labels are filled only when the plan\ndeclares them. Current filtered and unfiltered page costs are published under\n[implementation benchmarks](performance.md#implementation-benchmarks)\n(`BenchmarkHandleLogPage`).\n\n`Store.Clear` serializes administrative purges, captures an accepted-record\nboundary and publishes one command. The writer flushes earlier records,\ndeletes matching records/sidecars and rebuilds totals transactionally, then\nremoves only matching ring rows through that boundary. New completions\nsurvive.\n\nFailed SQL does not mutate the ring; postcommit memory effects finish even\nafter caller cancellation. The atomic command check must not acquire the\nproducer lock for every ordinary consumed record.\n\nA non-empty purge, and a drained expired-capture sweep, checkpoint-truncates\nthe WAL after the commit: `secure_delete` cleans the pages SQLite writes, and\ntruncation removes the pre-delete frames that would otherwise keep the old\npage images in the `-wal` sidecar.\n\nThe checkpoint is bounded and best effort; a busy reader raises a pending flag\nthat the writer's near-term tick retries, and `Store.Close` makes the final\nattempt after the read pool is closed, without failing the committed deletion.\n\nThe restricted SQL console (`GET /metrics/query` and the MCP `query` tool) is\ngated in `validateQuery`: one `SELECT`, no `;`, no\n`ATTACH`/`DETACH`/`PRAGMA`/`LOAD_EXTENSION` word, and no\n`sqlite_dbpage`/`dbstat`/`pragma_*`/`readfile`/`writefile`.\n\nThe scan is lexical over the raw text, string literals included, and the read\npool's `mode=ro` pins only the main database; SQLite still opens an `ATTACH`ed\nfile writable.\n\nFollow-up gap: the pinned modernc.org/sqlite v1.61.0 exposes an authorizer per\nphysical connection (`AuthorizerRegisterer`, installed through\n`RegisterConnectionHook`) and a `_defensive=1` DSN mode, and this build wires\nin neither. An authorizer policy at read-pool open plus defensive mode would\nturn the keyword list into defense in depth instead of the only owner.\n\nOperator backup and restore stage database-sized work as private files.\n`backup.EncodeFile` streams the packed snapshot, encoded archive and\nself-check in bounded chunks. On restore, the handler streams the capped\nupload into one private file, and `backup.DecodeFile` shares the byte\ndecoder's header, zstd, SHA-256 and member-framing owner while writing the\ndatabase member into a unique staging directory on the live database's volume.\nConfig bytes remain buffered; the database member does not.\n\nInspect and overlap integrity-check or attach that file in place, replace\nstreams it into the pending snapshot and atomically renames it, and merge\nattaches it to the held writer transaction. Decode and validation finish\nbefore an apply path takes the writer connection.\n\nThe upload and decoded database files are removed on every handler path,\nincluding over-cap, invalid archive, apply failure and client disconnect.\n\nA boot-time sweep reclaims only known staging names older than a safety age,\nexamining the directory in bounded batches up to a per-boot entry budget; the\nlive database, pending snapshot, rollback set, state marker and quarantined\nadmission evidence are outside that registry. A rejected or interrupted\npending file is preserved under a unique `.incoming.invalid-<token>` or\n`.incoming.invalid-interrupted-<token>` name with its sidecars, so a later\nrejection cannot overwrite earlier evidence.\n\nA pre-existing pending snapshot is hard-linked aside before the successor\nreplaces the slot: the restore drops that link again on its own rollback, and\na boot that rejects the successor renames the link back onto the slot and\nadmits it once, so the queue entry is never orphaned into the sweep. The\nattached inspect/merge and decoded source use the shared `SQLiteURI` with\n`mode=ro`, so a snapshot path with URI metacharacters stays literal and writes\nthrough the attached schema fail.\n\nRelevant coverage: storage writer/purge/request-parameter tests,\n`BenchmarkStorageWriter` and `BenchmarkProxyDurableContention`. The latter\ndeliberately overloads storage and separates durable throughput from drops.\n\nNon-stream responses decode once into one analysis: quality outcome, usage,\nmodel/id, finish reason, tool names, bounded preview and the top-level error\nenvelope share that pass, and the relay applies the same value at commit.\nCost-bearing bodies add the existing provider-keyed cost pass; streaming\nanalyzer semantics are unchanged.\n\n## History projection and aggregate math\n\nOne durable analytical projection retains compact contributions, request IDs,\ninterned dimensions and immutable sorted metric row orders. It is not a second\ndatabase or a per-view history cache. Startup preload and incremental catch-up\nshare its builder. SQLite transactions capture rowid high-water/destructive\nepoch/schema authority; destructive changes rebuild.\n\nFailed or canceled reads never publish stale rows or advance authority. Folds\ncheck the caller's context once per 4,096-row block, and the ring visitors use\nthe same cadence, so an abandoned request stops without publishing a partial\nresult.\n\nThe `has429` flag (and any future vocabulary-derived classification) comes\nfrom the installed vocabulary, not from a stored column, so the projection\nstamps the metrics classifier revision and forces a full reclassification\nrebuild when a reload changes it. The chart and explorer memos include the\nsame revision in their key, so neither a stale projection nor a pre-reload\nmemo can answer a post-reload request.\n\nMaterialization runs off the projection lock with one single-flight builder;\nconcurrent readers keep serving the previous complete snapshot and wait for\nthat builder instead of repeating its scan. The builder's token is released by\na defer, so a panic in the scan, decode or interning step frees the waiters\ninstead of wedging them until restart. A destructive change builds a complete\nreplacement off-lock and swaps it under a short write lock.\n\nThe durable since-inception totals are one meta row written in the same\ntransaction as every insert, purge and merge on the held writer connection;\nits recorded projection epoch is the mutation witness. A merge writes its\nrequest rows, debug sidecars and totals document in one transaction, so a\nfailed totals write rolls the whole merge back instead of advancing the epoch\nover partial rows. An unsupported external writer that advances the epoch\nleaves the pair mismatched, so the next boot rebuilds rather than trusting it.\n\nA boot with a changed epoch rebuilds once from the rows instead of trusting a\nstale cache, and a full purge has no surviving rows to scan. Restart readiness\ntherefore no longer scales with the sum of a totals scan plus a separate\npreload scan.\n\nChart and explorer each retain one immutable last-result slot. Keys include\nvalidated view/scope, canonical model rules, finalized/database revisions and,\nfor explorer, pending revisions. Clock-aligned geometry also gates chart\nreuse.\n\nOne in-flight fold per memo is shared by concurrent same-key callers: a\ndifferent key never waits, and a waiter that finds no published entry after\nthe leader ends recomputes as the next leader instead of inheriting its error.\nThe stability recheck hands over the fold's compiled rules identity instead of\nre-reading the config and re-marshalling up to 64 rules. The current 64-rule\nrecheck cost is published under [implementation\nbenchmarks](performance.md#implementation-benchmarks)\n(`BenchmarkAggregateUnchanged`).\n\nThe bootstrap KPI fold retains one exact totals slot keyed by the ring's\nfinalized revision and the store's durable accounting revision; live counters\nare filled at serve time and the ring snapshot itself is never retained. The\nunwritten set stays ring-derived. A record can be missing from the durable\nstore while never having been queued: an enqueue that overflowed the writer\nchannel and a batch whose insert failed are both dropped by design and counted\nby cause in the storage health owner; `Dropped()` sums the causes for the\ndashboard counter.\n\nThe writer queue is therefore not a superset of \"possibly not yet durable\",\nand only the written-id set can say which ring rows are already durable, so\nthe O(ring) probe under `aggMu` is the exact dedupe boundary. Current\ncold-fold costs at the default ring and the one-million-record ceiling are\npublished under [implementation\nbenchmarks](performance.md#implementation-benchmarks)\n(`BenchmarkKPI/records_1000000/miss`); the ceiling is a non-default\n`history_size`, and a correct-but-slow cold fold is the accepted cost of never\ndouble counting.\n\nSQLite data_version is read on one retained connection; unsupported external\nwriters are not made safe merely by cache invalidation. Log pages push exact\nprovider/client/key/conversation/status equalities into SQLite before\ndecoding; model filters are always Go-owned.\n\nThe Go scope matcher remains authoritative for canonical models, status\nclasses, errors, tools, time buckets and live-only classes. Ad-hoc SELECT\nresults are encoded once during the bounded scan and the endpoint writes that\narray directly; row/byte cap failure still precedes every response byte.\n\nExplorer uses dictionary IDs, scoped predicates and bitsets. The projection\nalso owns two derived tables keyed by its immutable build: the interned\nconversation topology (identities, parent declarations, resolved issues and\npublic-ID groups) and the canonical model IDs/dictionary for the compiled\nmodel-rule revision. Appends extend both by the new rows; destructive\nreplacement publishes fresh tables, and a rules change rebuilds only the model\ntable.\n\nRequests mark their own rail/gallery flags on the shared topology, resolve\nlineage metadata only for the returned conversation cards, and overlay\nring/pending declarations without mutating the published build. Projected\nmetric samples stay in shared sorted orders: single-valued dimensions retain\none group id per row, while tool/error membership spans preserve multi-valued\noccurrences.\n\nAn error's identity is `type|code|msg`; a backslash or the `|` separator\ninside a part is escaped, so arbitrary error text can never merge two distinct\nerrors into one dictionary id. Ordinary text keeps the historic spelling,\nwhich preserves saved error-filter ids.\n\nExact group accumulators are capped at `explorerGroupBudget` (8192) distinct\nvalues per fold. Values beyond the budget fold into one synthetic `other` card\ncarrying aggregate count, cost, token, tool and health fields; no per-value\naccumulator and no per-card request-ID set is allocated for either an exact\ncard or them. An error card's affected count is a counter plus the previous\nrequest id: one row's visits are contiguous, so that guard dedupes exactly\nwhat the old ID set did while staying bounded regardless of history.\n\nThe card carries an explicit `synthetic` wire marker and no filter key, so a\nreal value sharing its display label keeps its own exact, selectable card. The\ncard ranking remains exact among tracked values, with `other` competing by its\naggregate count, and overflow memberships map to the reserved other slot so\ntheir percentile samples still select correctly.\n\nRows store the group's 16-bit membership slot, not its dimension-wide\ndictionary id, so the per-row table is two bytes and the selected-card lookup\nis a bounded probe instead of a max-id-sized array; the current 100,000-row\nprovider fold cost is published under [implementation\nbenchmarks](performance.md#implementation-benchmarks)\n(`BenchmarkAggregateFold/explorer`). Rail distinct-value counts, scope totals\nand conversation summaries remain whole-history values and are not derived\nfrom the truncated group set.\n\nSelected groups use the same exact rank reader as chart buckets, and only top\ncards derive percentile payloads. Pending dedupe retains only relevant pending\nIDs, not another history-sized seen set. Chart's rank reader also produces the\noccurrence-weighted avg/min/max in the same traversal, so a metric order is no\nlonger walked separately for stats.\n\nThe all-history order is a compacted immutable base plus a bounded\nvalue-sorted pending delta (16,384 samples): a catch-up append folds only its\nnew samples, so it stays O(delta log delta) regardless of history, and\nreaching the bound arms one background fold that runs off the request and\npublishes the merged base under a one-assignment write. Readers keep the\ncurrent base and pending until then, so an interrupted fold only leaves the\npublished order in place.\n\nThe fold owns its armed flag behind a deferred release: an unwind there\n(recovered and logged) clears the arm with the pending delta intact, so the\nnext append folds again instead of the flag staying set and pending keeping\nthe whole delta for the process lifetime.\n\nAn append that crosses the bound at one million rows is published under\n[implementation benchmarks](performance.md#implementation-benchmarks), now off\nthe request (`BenchmarkProjectionMetricAppend`). Chart and explorer walk the\ntwo runs through one merge iterator, so a fresh view allocates no\nhistory-sized copy; a materialized merge stays cached per published snapshot\nonly for consumers that need a slice. A full rebuild replaces the base, clears\npending and discards a fold that has not published yet.\n\nA retained last-65,536-row order serves bounded chart windows whose earliest\nin-window durable row is inside that tail. It uses the same compacted base\nplus bounded pending delta design and its own per-snapshot view holder, so a\nsub-threshold catch-up merges only its new batch instead of copying the tail;\na rebuild of the newest 65,536 rows replaces its base, clears the pending\ndelta and releases samples that fell out of the tail.\n\nOlder or unscoped windows fall back to the all-history order, so the fast path\nnever changes rank or stat results. Chart membership is indexed from the first\nrow a bounded window accepts and sized only to that window's remaining span.\nThe current 15-minute view over 100,000 rows is published under\n[implementation benchmarks](performance.md#implementation-benchmarks); the All\npath keeps its historical allocation (`BenchmarkAggregateFold/chart_window`).\n\nBoth consumers share R7 rank/interpolation and the minimum-sample gate. Period\nspeed/TTFT percentiles use period samples, never means of bucket percentiles.\nPrometheus and the stress harness instead share `metrics.Percentile`'s\nnearest-rank contract; do not conflate these two intentionally distinct APIs.\nChecked counts/sums/ratios prevent wrapped tokens or non-finite JSON. Cost\nstays USD in storage/API; missing/unreportable data must not become fabricated\nprices.\n\n`Record.IsError` and `HasRateLimit` deliberately differ. Final/retried 429\ncounts once per affected request, not via the broad pacing flag. A real\nfailure and 429 may overlap.\n\nA 429 whose status line a committed keepalive 200 hid is retained as one\nin-band attempt entry, so the rate-limit count still sees the upstream status\nwhile the same request counts as an error through its final `error_type`; that\nentry is not a retry and adds no second error entry.\n\n`metrics.IsNonRetryableQuotaErr` is the fixed durable quota/billing\nclassification vocabulary: the retry ladder, storm evidence and in-band\nprecedence all consult it, so the account condition never counts as a rate\nlimit. A plain 499 (the local client's own abort) is a flow event; a 499\ncarrying a structured error observed the upstream's in-band failure before the\nclient left and counts like its 200 twin.\n\nThe shared first-membership gate keeps duplicate tool/error occurrences from\nduplicating these health counts without changing event/sample multiplicity.\nTests cover raw/projected/durable/ring/pending parity.\n\n`internal/metrics/errorclass.go` owns the canonical classifier: one\n`Classify(facts)` answers \"what is this\", and the retry ladder, the storm\nobserver, the Cursor transport, the health predicates, the client-facing class\nand the published SQL all read it. `metrics.OutcomeIsError` (composed by\n`Record.IsError`) owns the health arms, and the MCP describe document and the\ndurable purge filter render `metrics.IsErrorSQL`/`HasRateLimitSQL` per call\ninstead of carrying their own predicates, so an operator extension applied by\na reload reaches the published SQL too.\n\nClassification reads the status AND the provider's own type/code, never\nmessage text.\n\nThe two questions are separate and answer differently in the two documented\nfamilies: a 429 whose body names a durable quota/billing condition is\nClassQuota for the retry ladder and quota_pause_mode while the health surface\ncounts the 429 itself as flow control (not an error), and a rate-limit class\non any non-429 status is counted in the rate-limit series while the health\nsurface also counts the failed request as an error.\n\nThe health predicate reads the status and the error type only, so a spelling\ncarried solely in `error_code` (a shape the envelope parser does not produce -\nit pairs every code with a type) can move the class but not the health answer.\n\nThe operator's\n`rate_limit_error_classes`/`quota_error_classes`/`retryable_error_classes`\nextensions are installed as one value (`metrics.InstallClassExtensions`,\ninstalled by `proxy.New`/`proxy.Reload`) and every consumer reads the\neffective vocabulary, including the browser mirror, which receives it in the\nbootstrap payload when extensions are installed.\n\nExtensions add only: config validation rejects a spelling that names a\nbuilt-in of another class; the one documented exception is\n`retryable_error_classes` naming a built-in client-fault spelling, the\nexplicit override for a gateway that mislabels transient failures.\n\nWith `client_error_class: header` the relay's outer writer stamps\n`X-Proxy-Error-Class` and a class-derived `X-Should-Retry` on every error\nstatus before the line commits (`suppress_client_retries` still forces false);\nrelayed bodies stay verbatim.\n\nSee the files under `tests/_go/internal/web/`: `aggregate_projection.go`,\n`aggregate_dimensions.go`, `aggregate_percentiles.go`,\n`aggregate_explorer_fold.go`, `aggregate_rate_limit.go` and\n`conversation_lineage.go`.\n\n## Canonical observer meaning and conversation lineage\n\nGo's compiled model-rule executor owns canonical grouping. Observer payloads\ncarry exact raw-to-canonical names and a rules-content revision; only full\nauthoritative snapshots install a new revision. Deltas, archive and Debug\nnames merge under that revision, with recapture on conflicts. Browser\ndictionaries prune to loaded rows/selector needs. RE2 patterns do not execute\nin JavaScript.\n\nThe installed observer provider is an immutable atomic holder, so SSE\nrecord/end serialization never takes the ring lock. Canonical names are\nmemoized across observer calls under the compiled rules revision, and each\nknown-name vocabulary caches its sorted view under a set revision. Both caches\nare bounded and invalidate on content change, so bootstrap polls do not re-run\nthe rules or re-sort thousands of names.\n\nThe single-name memo owns the whole payload under one mutex keyed by the rules\nrevision, so a repeat at event rate costs one lock and one lookup. Current\nevent and vocabulary memo costs at the 64-rule maximum are published under\n[implementation benchmarks](performance.md#implementation-benchmarks)\n(`BenchmarkObserveModelNameEvent`, `BenchmarkObserveModelNames4096`). The\ncanon the observer reads is memoized per live config pointer, so consecutive\nevents hand the compiled-rule cache the same backing array and it skips the\nwhole-set compare; the wired shape's current cost is published there too\n(`BenchmarkObserveModelNameEventWired`).\n\nPinned names are derived from the live holds, debug sessions and limit\npolicies, never accumulated, so a removed document releases its scope. The\nderivation reads and applies the whole roster under the owning document locks:\nevery document commit happens under the same lock and re-derives right after,\nso a stale derivation can never overwrite a newer roster and unpin a live\nscope.\n\nObserver records carry server-local `time_bucket`; browser-local dates are\npresentation only. Raw names remain raw for exact export/delete semantics.\n\nThe explorer's one iterative lineage resolver validates declarations by\nclient/key/conversation before applying rail/gallery scopes. The resolved\ngraph is a projection-owned table, interned by dimension slot; a request only\nmarks flags and overlays unprojected ring/pending declarations. Parent-only\ndictionary names do not become observed memberships.\n\nConflicts, cycles and mixed namespaces remain unknown; missing parents are not\ninvented roots. Summary counts follow full-filter rail scope; conversation\ncards follow the gallery cross-filter. Payloads retain small resolved fields,\nnot a per-request graph. Parent pivots remain exact namespace-qualified\nleaves.\n\n## Operator plane clients\n\nThe HTTP client in [internal/mcp](../internal/mcp) owns the operator\ncredential, request building, the bounded response read and the `.error`\nextraction that reads the flat error body regardless of the declared\nContent-Type. The credential is redacted from both the transport error and the\nfailure body.\n\nRedirects are refused rather than followed: `net/http` strips `Authorization`\nonly when the hostname changes, so a same-host different-port `307` would\nreplay the credential and the request body.\n\nIts route paths are one closed set beside it, so no tool can name a path\noutside the operator plane: nothing reaches the transparent inference\ncatch-all, and no restore-adjacent route is exposed.\n\nThree registry tools are local-only: `docs_list`, `docs_search` and `docs_read`\nanswer from the `internal/docs` index instead of constructing an HTTP request.\nThey share the generated page model with the published site and never touch\nthe operator credential.\n\nThe explorer's `f=dim:id` / `s=` grammar is owned once and shared by every\nscoped tool, and the tools never loop: a non-advancing cursor is reported as\nexhaustion because the aggregate scan budget is bounded per call. An empty\npage is deliberately not exhaustion, because the proxy advances its cursor on\nevery row it scanned, including rows the scope excluded, so an empty page with\nan advanced cursor is a page that must be continued.\n\nThe same client backs the whole tool registry. The proxy's own `/mcp` endpoint\ninjects a transport that dispatches each synthesized request straight to the\nproxy's gated handler, with the caller's Bearer attached so the gate\nre-validates it, and a named non-routable origin (`http://millivolt.internal`)\nthat is never dialed and never derived from the request Host.\n\nThe endpoint is stateless and Bearer-only: every POST gets a temporary server\nsession bound to that request's credential, nothing survives it, and the\ndashboard session cookie is refused there because a cookie must not create an\ninternal call.\n\nThe SDK's own localhost DNS-rebinding `Host` check is deliberately off: the\ndocumented reverse-proxied placement preserves an external `Host` while\ndialing the proxy over loopback, so the check would reject that placement.\n\nProtection therefore rests entirely on the Bearer, which the same gate\nre-validates on every request; a missing or wrong credential is denied before\nany tool runs. The consequence is explicit: the endpoint admits any `Host` on\nthe listener it is reachable from, with a valid credential, and any\n`Host`-based allow rule has to sit at the ingress rather than here.\n\nThe destructive surface is guarded where the risk lives. A purge needs a\nfilter that constrains something (the bodyless delete-everything command is\nnever sent), an exact confirmation phrase, and the opaque `preview_token` that\n`purge_preview` issued for that same filter, its count and an expiry.\n\nA count cannot bind the two: it is only a number, so two filters matching the\nsame number would authorize each other.\n\nThe token is stateless and HMAC-bound under the operator credential, so\nnothing is persisted, no server-side cleanup is needed, and a rotated\ncredential invalidates every outstanding preview. It carries its own expiry,\nenforced when the token is verified, so a preview authorizes a deletion only\nshortly after it was taken.\n\nA refusal discloses no count, because a refusal that reports the live count is\na count oracle a model can retry its way through. The count is compared a\nsecond time inside the delete transaction in `Store.purgeTransaction`, so a\npopulation that moved refuses with 409 before any row is removed.\n\nThe remaining limit is stated rather than claimed away: a count compares a\npopulation, not row identities, so a same-size different row set passes and a\nrefusal needs a fresh preview.\n\nCapture refuses to start without durable storage, and checks a scope name\nagainst the vocabulary the proxy reports, because either way the session would\nreport success and store nothing. Stopping a capture session deletes nothing,\nand a purge deletes the stored capture document of every request it matches;\nthe tools say which is which rather than implying otherwise.\n\nWhen that vocabulary is readable and non-empty, an unknown capture scope or\nthrottle provider is refused and the known names are offered; both checks\naccept any name when it is empty, and the throttle provider check also accepts\none when the debug read fails, while the capture tool refuses when the same\nread fails. See the [MCP server guide](mcp.md).\n\n## Dashboard render owners\n\nHTML embeds the canonical bootstrap builder's JSON, safely escaped in an inert\ndata block. Transit gzip is negotiated from `Accept-Encoding` with only the\n`q` parameter read: unknown parameters are ignored, a bare `*` accepts gzip,\nand an explicit gzip entry outranks the wildcard; an unparseable or\nout-of-range qvalue refuses.\n\nDeferred external assets download alongside HTML; the Settings sheet is the\none exception: its ordered `settings*.js` set is injected by the Settings\ntrigger on first open, one module at a time under the same versioned URL, and\nsingle-flighted across concurrent opens. Saved hash/chart choices apply before\nrendering; invalid/missing seed falls back to the endpoint. Dynamic HTML/state\nis private/no-store.\n\nEvery local `/dash/` CSS/JS URL in the shell carries the content version as\n`?v=`. On a hit, the service worker answers a `/dash/` request carrying\nexactly that version from its stamped CacheStorage before the network; on a\nmiss it fetches once, stores a successful response, and returns it. This is\nthe one cache-first path.\n\nA request with no `v`, a stale value, or more than one `v` stays network-first\nwith cache fallback, as does every brand/PWA path, so an old index cannot pin\nnew bytes under an old URL. The server serves the exact-version response\n`private, max-age=31536000, immutable`, while a missing or stale version\nrevalidates with `no-cache`. A Bearer-authenticated response that also mints a\nsession cookie keeps the gate's stricter `no-store`. Immutable asset\nrepresentations and revalidation identities are precomputed.\n\nContent version changes use the same winning bootstrap gate to reload once.\nThe cache-first path is asset caching only, never an offline app shell:\nnavigation to `/` stays live with the static offline fallback, and\nlive/operator routes are never cached.\n\nVanilla modules under [static/js](../internal/web/static/js) have distinct\nowners:\n\n- `core`: formatters and shared state.\n- `feedback`: the one clipboard and toast path.\n- `entities`: identities and record labels.\n- `explorer`: routing and cards.\n- `chart`: uPlot plans.\n- `menu`: the one open/close, placement, dismissal and focus contract for menu\n  panels.\n- `chrome_menus`: the header menu registry and the remaining theme tray, nav\n  and dimension class menus.\n- `operator_console`: the header readout, console shell, section rail, shared\n  wording and bounded session change ledger.\n- `operator_console`'s four policy modules `operator_limits`,\n  `operator_holds`, `operator_export` and `operator_overview`, each owning its\n  own section.\n- `chrome_operator`: the mutation gate and request shape.\n- `chrome_lists`: the operator vocabularies, model grouping, capture storage\n  gate and footer words.\n- `chrome_restart`: the restart choreography.\n- `chrome_settings`: the Settings shell and trigger, the accepted debug\n  snapshot, hold liveness and the download paths.\n- `timeframe`: the chart time vocabulary, stored-extent availability and the\n  timeframe control.\n- `log`: the live log frame.\n- `log_rows`: the rows, day dividers and column registry.\n- `log_archive`: the durable archive window.\n- `log_drawer`: the detail drawer lifecycle and retry-attempt navigation.\n- `log_detail`: the detail primitives.\n- `log_debug`: the drawer's Debug capture section.\n- `chrome_storm`: the storm banner, incident identity and details dialog.\n- `theme_boot`: the palette ids, labels, order, defaults and the pre-paint guard.\n- `theme_state`: normalization, the stored pair, the one apply path and the\n  browser chrome color, shared by the dashboard and the site.\n- `theme`: the dashboard preview tray, comparator state and keyboard\n  lifecycle.\n- `settings`: the lazily loaded Settings sheet.\n- `live`: bootstrap/SSE/derived state.\n\n`theme_boot.js` is the one registry: palette ids, labels, order and defaults,\nplus the blocking guard that applies a stored pair before first paint.\n`theme_state.js` owns normalization, the single stored shape, the one apply\npath, the browser chrome color and the optional chart/menu callbacks. A commit\nchanges the live document pair; normalization also repairs storage at load when\nthe stored value is invalid.\n\n`theme.js` owns only the dashboard tray: preview, comparator state and the\nkeyboard lifecycle. The site's `site_theme.js` renders the same registry into\nits own header tray and reuses the same state module.\n\nHover or keyboard focus previews inside the tray only, and the polite live\nregion follows the keyboard cursor: pointer-induced focus never announces a\ncandidate. Arrow keys, Home and End move the cursor and its one tab stop;\nEnter/Space or a click commits. Compact touch, short and narrow layouts hide\nthe comparator, preview line and hint while keeping the current caption,\nsurface control and all eight rows.\n\n`css/themes.css` owns the complete surface, accent and material families every\npalette resolves in both modes and the Black/Clear mode material fallbacks. The\nsite publishes these exact bytes and loads them after its generated tokens and\nbefore `site.css`; its extra contrast rungs derive from the active mode tokens\nwith `color-mix`, so there is no second palette table.\n\n`dashboard.css` owns the default Instrument Black base, the header chrome and\nthe theme tray, including the comparator/caption-bar layout. The dashboard\nsheet is split by surface, linked in this order: `dashboard.css` (palette,\nbase, chrome and KPI band), `explorer.css`, `overlays.css` (drawer and\nsettings sheet), `charts.css`, `requests.css` (including the shared semantic\nstatus fills) and `inspector.css`, with `themes.css` next, then `console.css`\nfor the readout and operator console only, and the vendored uPlot sheet last.\n\nThe link order is the cascade; `dashboard.css` remains the `:root` palette and\ntype owner: its `@font-face` rules load the embedded Instrument Sans and\nJetBrains Mono faces from `static/fonts`, and its `--sans`/`--mono` tokens\nname the families every surface consumes. The docs build publishes the same\nfiles and adds Instrument Serif as the site-only display face for marketing\nand documentation titles, so neither surface makes a third-party font request.\n\nEach palette owns `--shadow-rgb` and `--veil-rgb`, and the mode veil tokens\ncompose that hue, so cool Clear palettes get cool elevation and scrims.\n`chrome_settings.js` owns the Settings trigger, loader, open-state probe,\nshared status line and the single close entry point; the lazy `settings*.js`\nmodules own the sheet's state, editors and apply/revert/backup/purge behavior.\n\nA clean open at the same document revision and writable state still fetches\nfreshness but keeps the retained rows and baseline; revision/writable changes,\ndrafts and Revert refill. The model-rule preview reuses one traffic-example\ncache keyed by the live revision, and its test spelling is preview-only: it\nnever revalidates the draft or marks the sheet dirty.\n\nOne memoized derivation serves scoped rows and shared readouts. O(1) ID\nupserts, pure-replay suppression and rAF-coalesced live rendering avoid\nrepeated scans. Incremental log groups preserve scroll/selection; archive\npaging uses paired timestamp/ID cursors and stays outside the live\narrival-ordered ring.\n\nOne single-entry memo reuses the merged ring+archive window within a live\nrevision, keyed by the live data and its revision plus the archive array\nidentity/length and the scoped-ring (or prior merged) array identity; archive\nreplacement or trim, reset, a live revision bump and a data replacement each\nrebuild it.\n\nThe explorer memoizes its filter-set identity on the canonical,\norder-independent scope (filter set plus status, excluding the `by/<dim>`\nbreakdown). A by-only hash change repaints the rail/gallery and fetches that\none breakdown while the scoped log window, chart and drawer keep their state.\n\nUnchanged explorer renders write nothing beyond card string construction: the\nrail and gallery HTML is compared before assignment, the shared dimension\ntrigger is rewritten only when its dimension/count presentation key changes,\nand gallery layout sizing runs only after the gallery content actually\nchanges.\n\nServer chart responses alone own buckets/totals at configured cadence.\nPresets, series, money/unit formatters and visible dimension order each have\none registry. Derived series (error rate, cache hit, blended totals) recompute\nfrom those server bucket sums; the browser never folds events into chart data.\nHidden lines keep stable columns; percentile/range changes reuse the plot.\nIsolated samples use filled/ring points without coordinate jitter. Shared axis\nformatting avoids duplicate labels. The percentile dropdown is the only\nvisible pXX label owner; conditional error/429 badges omit zero independently.\n\nOperators use shared mutation/revision gates, lossless Settings collection,\nstable event-path outside-click handling and a focus/inert dialog lifecycle.\nCSS owns responsive breakpoints. Preserve accessibility, saved state and cheap\nboot; jsdom tests do not replace real desktop/mobile canvas checks.\n\n## Documentation captures\n\n`scripts/gallery/data.py` is the one registry for every published application\ncapture: path, title, description, scene, viewport and setup. `tests/docs_capture.py`\nowns the scene strategies, and `scripts/gallery/compose.py` composes the two\nsurfaces of each plate. A new view is one registry entry plus a scene, never a\nsecond list in the capture harness or the site build.\n\nThe capture writes `docs/images/capture.json`: per-plate bytes, dimensions and\nSHA-256, the verified record count and a digest of `internal/web/static`. The\ndigest is the freshness gate; a dashboard change fails `tests/python/gallery.py`\nuntil the plates are recaptured. The same run regenerates `docs/gallery.md`.\n\n`scripts/site_plates.py` is the one upgrade from a registered image to a plate.\nIt serves both a plain Markdown image and the generated page's semantic figure,\nso the published gallery, the prose guide and the Markdown source agree about\nnumber, station, route and the Black/Clear split legend.\n\n`scripts/gallery/__init__.py` loads and validates the registry at import, so a\nmissing alt, duplicate path, unknown scene or bad viewport fails before a browser\nstarts. CI runs the same module through `tests/python/gallery.py`.\n"
    },
    {
      "path": "CONTRIBUTING.md",
      "slug": "contributing",
      "output": "contributing.html",
      "markdown": "contributing.md",
      "url": "https://millivolt.llm4people.dev/contributing.html",
      "markdown_url": "https://millivolt.llm4people.dev/contributing.md",
      "title": "Contributing",
      "description": "Start with the architecture map . Keep changes focused on existing shared owners, include regressions, and use neutral fixtures rather than real providers....",
      "group": "Extend",
      "order": 17,
      "bytes": 41681,
      "sha256": "8bd76202c9628463146ae723d65fa938d8fdc064bffec694b817cd4664ba9379",
      "sections": [
        {
          "heading": "Support and first change",
          "id": "support-and-first-change",
          "text": "SUPPORT.md routes usage questions, reproducible defects, concrete proposals, and security reports. For a first change, fork the repository, branch from origin/testing , update the existing shared owner, and add a targeted regression. Run scripts/check.sh and report what ran. Open the pull request against testing , not main . Use the good first issue label only for documentation, tests, or tooling with a clear scope and expected result. Do not label credential handling, authentication, storage, protocol-core, or release work. Ask in the issue before starting.",
          "context": ""
        },
        {
          "heading": "Branch workflow",
          "id": "branch-workflow",
          "text": "New features branch from and land on testing first, with their documentation and relevant checks in the same change. Fetch the current remote branch before starting follow-up work. Use feature branches targeting testing for review, or push a completed, checked feature directly there when that is authorized. main is promotion-only. Do not develop on it, push it directly, or bypass its rules. The main-testing-first ruleset requires a pull request and the required check, allows merge commits only, and has no bypass actors. The long-lived-branch-integrity ruleset also blocks deletion and non-fast-forward updates. Administrators have no bypass either. When release automation needs new behavior, change the workflow in a pull request; never add a bypass actor or use an administrator override. Inspect the active ruleset with: ruleset_id=\"$(gh api repos/LLM-4-People/millivolt/rulesets \\ --jq '.[] | select(.name == \"main-testing-first\") | .id')\" gh api \"repos/LLM-4-People/millivolt/rulesets/$ruleset_id\" \\ --jq '{name,enforcement,bypass_actors,current_user_can_bypass}' It must report enforcement: active , an empty bypass_actors , and current_user_can_bypass: never .",
          "context": ""
        },
        {
          "heading": "Commit as you go",
          "id": "commit-as-you-go",
          "text": "Commit each completed fix locally as soon as its targeted check passes. This includes every individual finding from a review, audit, or multi-agent round: do not hold those edits in the working tree until the end, and do not squash several findings into one final commit. If a fix depends on an earlier uncommitted change, commit that coherent change first, then commit the dependent fix. Keep unrelated user changes out of the commit. A push still waits for the full push gate on the exact commit being pushed. A commit subject also feeds the generated release notes: every subject whose type is not one of build , brand , checks , chore , ci , deps , doc , docs , merge , refactor , release , style , test , tests , tooling or version becomes a Highlight on the release that first contains it, and internal types are folded under \"Other changes\". Write the subject for an operator reading the release page. Completed feature pushes to testing publish only the moving development image. All pull requests to testing , all code-bearing pushes to testing , manually dispatched testing gates, and manually pushed v* tags run the full gate. Docs and site-only pushes to testing run the smaller documenta",
          "context": "Branch workflow"
        },
        {
          "heading": "Promote testing to main",
          "id": "promote-testing-to-main",
          "text": "Fetch and align the branches. testing must contain the feature work and main must be an ancestor: sh git fetch origin git switch testing git merge --ff-only origin/testing If main is not an ancestor of testing , merge origin/main into testing first and resolve conflicts before continuing. For a code-bearing promotion, bump VERSION on testing to a version newer than every existing v* tag. Normal SemVer precedence applies; a prerelease is lower than the same stable version. Commit the bump separately: sh printf '<next-version>\\n' > VERSION git add VERSION git commit -m \"bump version to <next-version>\" git push origin testing A docs/site-only promotion may skip this step. required detects that every changed path is covered by the docs/site filter (for example Markdown, docs/ , site-src/ , the docs and Pages workflows, and LICENSE ), and the merged main push stays docs-only. Open a pull request from testing to main . For a code-bearing head, wait for the testing check.yml push gate to finish first. A docs/site-only head has no canonical check.yml push run of its own, so wait for docs.yml or only the required docs validation. Then wait for required . The proof polls pending exact runs a",
          "context": "Branch workflow"
        },
        {
          "heading": "Development dependencies",
          "id": "development-dependencies",
          "text": "Linux is supported. Version sources are: Go: go.mod . Node: .node-version . Python: .python-version . jq : the workflow contract suite executes the promotion gate's shell predicates, so the core checks need the jq binary on PATH . Browser tooling: requirements-dev.txt . Documentation site: requirements-docs.txt . The proxy embeds its vanilla JavaScript/CSS and needs no frontend build or Node runtime in deployment. Node/jsdom, Python/Playwright, Python-Markdown and PyYAML are development and documentation tools. npm ci --ignore-scripts python3 -m venv .venv . .venv/bin/activate python -m pip install --require-hashes -r requirements-dev.txt python -m playwright install chromium On fresh Linux installations, Chromium may also need system libraries; use python -m playwright install --with-deps chromium with appropriate installation permissions. Go race checks require CGO_ENABLED=1 and a working C compiler; the regular proxy build does not require a native SQLite driver.",
          "context": ""
        },
        {
          "heading": "Checks",
          "id": "checks",
          "text": "scripts/check.sh The shared script owns the core verification commands. They include offline documentation-link, publication-ignore and typography regressions (Git is required), the generated-site contract, the documentation readability check and the workflow/automation policy. That policy suite runs the workflow files of the ref under test. A pull_request run evaluates its own head revision rather than the base branch's, so a workflow change is judged as this pull request ships it. Review the workflow diff itself, since the run that validates it was configured by the same commit; only the post-merge main state proves what landed. npm test runs the jsdom suites and the request-log merge regression probe separately. All tests and disposable harnesses live in tests/ , with suffix-free physical filenames. Go's temporary overlay adds its required virtual _test.go names; Python unit modules live in tests/python/ . Use scripts/check.sh go test for targeted Go checks and scripts/check.sh go vet or scripts/check.sh go mod tidy to include test code and dependencies. Raw go test ./... does not discover the relocated tests and can report success without running them. Re-run checks after your ",
          "context": ""
        },
        {
          "heading": "Documentation site",
          "id": "documentation-site",
          "text": "The public site is generated from the existing Markdown, not maintained as a second documentation tree. site-src/ owns the layout, styles, and brand assets; scripts/build_site.py renders the pages, rewrites repository links, and emits the search index, sitemap, 404 page and the machine-readable docs outputs described below. The generated site/ directory is ignored and never committed. python3 -m pip install --require-hashes -r requirements-docs.txt python3 -B -O -m tests.python.site python3 scripts/build_site.py --output site Both requirements files are hash-pinned and every install command passes --require-hashes , so resolution is reproducible and a substituted file fails the install. After changing a pin, regenerate the hash block for that version from the PyPI JSON document ( https://pypi.org/pypi/<project>/<version>/json , digests.sha256 of every non-yanked file, one --hash=sha256: line each), keep the pins sorted as they are, and run the install above once to prove the file. For a local preview, serve site/ from a separate terminal with python3 -m http.server --directory site 8082 ; do not point it at the proxy or use the main :8080 instance. The docs.yml workflow builds the ",
          "context": "Checks"
        },
        {
          "heading": "Machine-readable documentation",
          "id": "machine-readable-documentation",
          "text": "scripts/build_site.py drives scripts/site_llm.py , which writes a Markdown twin beside every rendered page, plus llms.txt , llms-full.txt and docs.json . The MCP server embeds a checked-in copy at internal/docs/docs.json ; never edit that file by hand. Regenerate it after any Markdown, title, navigation or description change: python3 scripts/build_site.py --output site --write-manifest tests/python/site.py fails when the embedded copy is stale, when a page does not advertise its Markdown twin, or when a generated URL names a missing file. The MCP tools docs_list , docs_search and docs_read read that index and make no proxy request.",
          "context": "Checks"
        },
        {
          "heading": "Documentation prose",
          "id": "documentation-prose",
          "text": "Write for a reader who is scanning. Keep one idea per paragraph and roughly 110 words or fewer. Use a list or table when a sentence carries three or more parallel items, and split a paragraph when it changes subject. tests/python/docs_readability.py enforces the word limit on hand-written Markdown. docs/settings.md is generated from the schema and is excluded. The site is published at https://millivolt.llm4people.dev/ . That origin has two owners, and neither is a file in this repository: the Pages custom domain in the repository settings, which is what GitHub serves and certifies, and the DNS record, which is a CNAME from millivolt to llm-4-people.github.io with the proxy disabled. scripts/build_site.py warns when a build for SITE_URL names a different host than DEFAULT_BASE_URL , because that is what a half-finished migration looks like. GitHub ignores a CNAME file in an Actions deployment, so this repository does not ship one.",
          "context": "Checks"
        },
        {
          "heading": "Brand plates",
          "id": "brand-plates",
          "text": "The README covers, specification strips, Open Graph card and GitHub social preview are generated, not hand-edited. scripts/brand/facts.py owns the headline, the four specification facts and the sample-history values. scripts/brand/manifest.json owns each target's dimensions and hash. Regenerate every plate after a copy or fact change: python3 -m pip install --require-hashes -r requirements-docs.txt python3 -m scripts.brand.build The PNG renders need Playwright's Chromium; the SVG strips do not. python3 -m scripts.brand.build --check verifies every committed asset against the manifest and re-renders both SVG strips from source. CI runs that check. The tool count in the specification strip comes from scripts/mcp_registry.py , the same parser the MCP docs test uses, so adding a tool cannot leave the art behind. Upload .github/social-preview.png under the repository's Settings, Social preview after it changes. That upload is a GitHub setting, not a repository file.",
          "context": "Checks"
        },
        {
          "heading": "Push gate",
          "id": "push-gate",
          "text": "Never push main directly: open a promotion pull request and merge it with a merge commit. Do not push testing until the exact commit you will push has passed the same CI gate jobs. A request to push is not a waiver. Package-scoped go test and npm test during development are not sufficient. CI's source-and-unit step is the default core suite: scripts/check.sh A run may not start while a code-scanning finding is unresolved. scripts/security_gate.py reads code-scanning/alerts?state=open from the repository API in the unit job and again in publish before the version tag is created. Fix the finding, or record a dismissal with a reason that explains why the code is correct; a dismissed alert is not open, and the security page keeps that reason beside the location. An API the gate cannot read fails closed rather than passing. CI sets GOTOOLCHAIN=local , so the host Go must match the go version in go.mod . On a host with an older base Go, install Go 1.27.2 or select the matching toolchain before running the gate; GOTOOLCHAIN=local alone cannot upgrade an older installation. Full-gate CI events also run the isolated browser fixtures (desktop and mobile) in the browser job. Use scripts/dev.s",
          "context": "Checks"
        },
        {
          "heading": "Isolated development",
          "id": "isolated-development",
          "text": "Never use an existing main instance on port 8080 for tests. Use the lifecycle script, with cleanup even if verification fails: ( set -e trap 'scripts/dev.sh stop' EXIT export MILLIVOLT_OPERATOR_TOKEN='dev-instance-credential' scripts/dev.sh scripts/check.sh browser --target http://127.0.0.1:8081 ) The dev instance shares your shell environment, so a local MILLIVOLT_OPERATOR_TOKEN arms its operator gate; browser and stress harnesses need the same value for gated fixture cleanup. An instance started without it serves reads only and denies every mutation. scripts/dev.sh status reports the private instance. The script builds first, then replaces only its tracked dev process; a failed build leaves it running. The tracked identity is the pid file. status / stop fall back to the listener on the instance's port when the file names a dead pid. A rebuild child rewrites the file only once it is fully booted, so a child that dies before readiness would otherwise strand the instance. The fallback still requires the process to carry this instance's exact -pid-file flag. Starting/restarting development resets its disposable database and private config, seeded from the public example by default. D",
          "context": ""
        },
        {
          "heading": "Live Chrome DevTools verification",
          "id": "live-chrome-devtools-verification",
          "text": "Frontend changes are additionally verified in a visible Chrome window through Chrome DevTools - headful, never headless. Sign in with the dev operator token, drive the real fixture traffic and the actual controls, and check console output, element geometry, the accessibility tree and screen flow in the rendered page. Narrow fixture data passes the harnesses but can hide distribution problems (wide values, wrapping, density); the live session is where those surface. Keep the dev instance and the window open while you look; stop the instance with scripts/dev.sh stop when done. Fixture traffic for these sessions has its own lifecycle owner, never a paid provider and never the main instance on :8080 : scripts/dev-traffic.sh # bursts of neutral loopback traffic at the dev instance scripts/dev-traffic.sh status scripts/dev-traffic.sh stop Bursts land about a minute apart so one-minute chart buckets gain a bucket per burst; each run includes recovered 429s (rate-limited, not errors) and one final 400 so both health surfaces carry data.",
          "context": "Isolated development"
        },
        {
          "heading": "Container development",
          "id": "container-development",
          "text": "Normal compose.yaml only runs a published image. For a local source build, use compose.dev.yaml from the checkout root. It is a complete Compose file, not an overlay: project and service are both millivolt-dev , and the container takes the project-scoped name Compose derives from them. docker compose -f compose.dev.yaml up -d --build docker compose -f compose.dev.yaml logs --tail 50 docker compose -f compose.dev.yaml down The development project keeps its containers and named volumes separate from a normal deployment, including when COMPOSE_PROJECT_NAME is set outside the checkout. Its MILLIVOLT_DEV_PORT and MILLIVOLT_DEV_IMAGE inputs are defined only there, and it shares the deployment Compose's MILLIVOLT_MEM_LIMIT and MILLIVOLT_PIDS_LIMIT bounds. Choose an unused development port if scripts/dev.sh is already running. Rerun the same up --build command after source changes. The resulting runtime image has no compiler or source tree, so dashboard rebuild is unavailable. down preserves its named volumes unless you explicitly request deletion. This source-image workflow does not replace scripts/dev.sh : the host browser and stress fixtures require that script's private process/databas",
          "context": ""
        },
        {
          "heading": "Documentation screenshots",
          "id": "documentation-screenshots",
          "text": "The published gallery uses recorded metrics from an explicitly authorized, redacted local-history snapshot, not fabricated timing or cost values. Never point capture tools at a main instance or serve a raw history copy for screenshots. The source is the checkout's local proxy.db , opened read-only through the existing online-backup helper. This workflow needs explicit authorization for that history. From a checkout with browser dependencies installed and that authorized source: ( set -e export DEV_PORT=18081 DEV_HOST=127.0.0.1 export DEV_DB=/tmp/millivolt/millivolt-dev-docs.db export DEV_CONFIG=proxy.example.yaml DEV_COPY_DB=redacted trap 'scripts/dev.sh stop' EXIT scripts/dev.sh up python3 -B -O -m tests.explorer_check \\ --target \"http://${DEV_HOST}:${DEV_PORT}\" --docs-history docs/images ) Choose an unused permitted dev port. Before startup, dev.sh derives a new metrics-only database: identifiers are replaced, content/headers/debug data are removed, and recorded timing, token and cost values are retained. The raw online snapshot is temporary and never served. Treat even the derived database as sensitive; retained usage and timestamps can reveal activity patterns. The view list is",
          "context": ""
        },
        {
          "heading": "Performance evidence",
          "id": "performance-evidence",
          "text": "The published tables, method and limitations live in performance and resource usage . That page is the single source for measured numbers; do not copy them into other documentation and do not edit the page by hand. It is rendered from perf/results.json , and tests/python/site.py fails when the two disagree. scripts/perf.sh owns a repeatable local measurement run without touching the main instance. It starts fresh private instances on a disposable port and stops them through scripts/dev.sh : scripts/perf.sh docs # every published measurement, bundle and page scripts/perf.sh bench # isolated Go benchmarks scripts/perf.sh stress # private fast and streaming ramps scripts/perf.sh streaming # sustained end-to-end SSE throughput ramp scripts/perf.sh sustained # fixed-duration fast-response capacity levels scripts/perf.sh image # disposable image content and compressed size scripts/perf.sh all # image, bench, then stress docs refuses a dirty tree, runs the complete documented set, writes perf/results.json , and regenerates docs/performance.md . Commit the bundle and the page together. Never hand-edit either one; a missing stage, failed response or unbalanced durable result aborts the run ",
          "context": ""
        },
        {
          "heading": "Versioning and publication",
          "id": "versioning-and-publication",
          "text": "VERSION is the only semantic version source; do not duplicate it in package manifests, build arguments or image metadata. Normal and prerelease SemVer are supported without build metadata. A release tag must be exactly v followed by that file's version. The release CLI validates the same contract: millivolt_version=\"$(tr -d '\\r\\n' < VERSION)\" go run ./cmd/release -revision \"$(git rev-parse HEAD)\" -tag \"v$millivolt_version\" Publication is automatic. A code-bearing versioned promotion releases when the promotion PR merges, after the full gate has passed for the promoted commit, or after the closest gated testing commit plus a docs-only delta. A non-Dependabot promotion also requires a successful escalation run for the reviewed head. The promotion PR starts it automatically, and required waits for it under a bounded, fail-closed proof. The merged-PR event carries the exact merge commit; a delivered main push is an idempotent fallback, so a dropped push event cannot leave the release untagged. A Dependabot security PR targets main and runs the full gate itself rather than reusing a testing result. The release publish job waits for required . The publish-testing job waits for unit , bro",
          "context": ""
        },
        {
          "heading": "If a release fails",
          "id": "if-a-release-fails",
          "text": "Before the tag is pushed, no public release exists. Fix the failure and rerun the main workflow or promote a new version. After the tag is pushed, keep the tag in place. If the GitHub release is missing, create it from that tag or publish a new patch version. An automatic tag push does not start a second workflow run. Do not move or delete a published version tag. For local container verification, build with Docker, resolve the image's immutable ID, then use the same fixture as CI: docker build -t millivolt:check . millivolt_image_id=\"$(docker image inspect --format '{{.Id}}' millivolt:check)\" scripts/check.sh container --image \"$millivolt_image_id\" The shared container mode validates Compose defaults and owns only its disposable, network-isolated Docker fixture, selected by immutable image ID. It checks startup, HTTP, Settings and durable state across stop/start, then backs up the stopped volumes and restores into another fresh container. Recovery must retain settings, history and private file ownership/modes. It never publishes a host port or reuses an operator volume. It complements, rather than replaces, the host lifecycle in scripts/dev.sh .",
          "context": "Versioning and publication"
        },
        {
          "heading": "Change checklist",
          "id": "change-checklist",
          "text": "Use sentence case or lowercase in prose, headings and labels. Avoid em dashes; preserve exact protocol names, identifiers, user data and license wording. Add a targeted regression for a reproduced defect; preserve existing coverage. Keep defaults, units, schemas and state transitions at their canonical owner. Measure allocations/latency when changing the hot path or analytical folds. Check saved views, mobile layout and accessibility for visible changes. Update the relevant existing documentation, not duplicate specifications. Exclude local configs, databases, tokens, captures and generated test artifacts. Preserve dependency licenses. Report vulnerabilities using SECURITY.md , not a public issue containing sensitive reproduction data. Dependabot checks Go, npm, Python, Docker and GitHub Actions dependencies weekly with grouped minor and patch updates. Review dependency changes and re-run checks; runtime version files still require deliberate updates and verification. The Docker golang base is deliberately left manual because its tag must move with go.mod; distroless updates remain automated. Security updates target main as described in the branch workflow. Dependency review runs o",
          "context": ""
        }
      ],
      "markdown_text": "# Contributing\n\nStart with the [architecture map](docs/architecture.md). Keep changes focused on\nexisting shared owners, include regressions, and use neutral fixtures rather\nthan real providers. Setup, safety and verification rules live in this guide.\n\nUse the [issue tracker](https://github.com/LLM-4-People/millivolt/issues) for\nnon-sensitive bugs and proposals, and\n[pull requests](https://github.com/LLM-4-People/millivolt/pulls) for changes.\nSecurity reports belong in the private channel in [SECURITY.md](SECURITY.md).\n\n## Support and first change\n\n[SUPPORT.md](SUPPORT.md) routes usage questions, reproducible defects, concrete\nproposals, and security reports. For a first change, fork the repository, branch\nfrom `origin/testing`, update the existing shared owner, and add a targeted\nregression. Run `scripts/check.sh` and report what ran. Open the pull request\nagainst `testing`, not `main`.\n\nUse the `good first issue` label only for documentation, tests, or tooling with\na clear scope and expected result. Do not label credential handling,\nauthentication, storage, protocol-core, or release work. Ask in the issue before\nstarting.\n\n## Branch workflow\n\nNew features branch from and land on `testing` first, with their documentation\nand relevant checks in the same change. Fetch the current remote branch before\nstarting follow-up work. Use feature branches targeting `testing` for review,\nor push a completed, checked feature directly there when that is authorized.\n\n`main` is promotion-only. Do not develop on it, push it directly, or bypass its\nrules. The `main-testing-first` ruleset requires a pull request and the\n`required` check, allows merge commits only, and has no bypass actors. The\n`long-lived-branch-integrity` ruleset also blocks deletion and non-fast-forward\nupdates. Administrators have no bypass either. When release automation needs new\nbehavior, change the workflow in a pull request; never add a bypass actor or use\nan administrator override. Inspect the active ruleset with:\n\n```sh\nruleset_id=\"$(gh api repos/LLM-4-People/millivolt/rulesets \\\n  --jq '.[] | select(.name == \"main-testing-first\") | .id')\"\ngh api \"repos/LLM-4-People/millivolt/rulesets/$ruleset_id\" \\\n  --jq '{name,enforcement,bypass_actors,current_user_can_bypass}'\n```\n\nIt must report `enforcement: active`, an empty `bypass_actors`, and\n`current_user_can_bypass: never`.\n\n### Commit as you go\n\nCommit each completed fix locally as soon as its targeted check passes. This\nincludes every individual finding from a review, audit, or multi-agent round:\ndo not hold those edits in the working tree until the end, and do not squash\nseveral findings into one final commit. If a fix depends on an earlier\nuncommitted change, commit that coherent change first, then commit the\ndependent fix. Keep unrelated user changes out of the commit. A push still\nwaits for the full push gate on the exact commit being pushed.\n\nA commit subject also feeds the generated release notes: every subject whose\ntype is not one of `build`, `brand`, `checks`, `chore`, `ci`, `deps`, `doc`,\n`docs`, `merge`, `refactor`, `release`, `style`, `test`, `tests`, `tooling` or\n`version` becomes a Highlight on the release that first contains it, and\ninternal types are folded under \"Other changes\". Write the subject for an\noperator reading the release page.\n\nCompleted feature pushes to `testing` publish only the moving development image.\nAll pull requests to `testing`, all code-bearing pushes to `testing`, manually\ndispatched `testing` gates, and manually pushed `v*` tags run the full gate.\nDocs and site-only pushes to `testing` run the smaller documentation gate in\n`docs.yml`.\n\nAn ordinary promotion pull request to `main` runs only `check.yml`'s lightweight\n`required` promotion gate. It verifies the head is the current `testing` tip,\n`main` is already merged back into `testing`, and the full gate already\nsucceeded for that commit: the canonical `check.yml` push run's own check\nsuite, with `unit`, `browser` and both native container legs.\n\nA final docs-only commit after the closest gated `testing` commit reuses that\ngate when every path since it is docs/site-only. Every non-Dependabot promotion\nalso starts [`escalation.yml`](.github/workflows/escalation.yml) on its head and\nmust carry a successful `race` job for that exact commit. The proof waits under\na bounded budget and fails closed. The fallback selects the closest gated\ntesting commit from canonical `testing` push runs, with no commit-count bound.\n\nFor a code-bearing head, let the `testing` `check.yml` push gate finish before\nopening or re-running a promotion PR. Pending exact check runs get a short\nbounded wait and the proof fails closed while they remain pending. A\ndocs/site-only head has no canonical `check.yml` push run of its own, so wait\nfor `docs.yml` or only the `required` docs validation. A Dependabot security\npull request targets `main` directly and therefore still runs the full gate.\n\n### Promote testing to main\n\n1. Fetch and align the branches. `testing` must contain the feature work and\n   `main` must be an ancestor:\n   ```sh\n   git fetch origin\n   git switch testing\n   git merge --ff-only origin/testing\n   ```\n   If `main` is not an ancestor of `testing`, merge `origin/main` into\n   `testing` first and resolve conflicts before continuing.\n2. For a code-bearing promotion, bump `VERSION` on `testing` to a version\n   newer than every existing `v*` tag. Normal SemVer precedence applies; a\n   prerelease is lower than the same stable version. Commit the bump\n   separately:\n   ```sh\n   printf '<next-version>\\n' > VERSION\n   git add VERSION\n   git commit -m \"bump version to <next-version>\"\n   git push origin testing\n   ```\n   A docs/site-only promotion may skip this step. `required` detects that every\n   changed path is covered by the docs/site filter (for example Markdown,\n   `docs/`, `site-src/`, the docs and Pages workflows, and `LICENSE`), and the\n   merged main push stays docs-only.\n3. Open a pull request from `testing` to `main`. For a code-bearing head, wait\n   for the `testing` `check.yml` push gate to finish first. A docs/site-only\n   head has no canonical `check.yml` push run of its own, so wait for `docs.yml`\n   or only the `required` docs validation. Then wait for `required`. The proof\n   polls pending exact runs a bounded number of times and fails closed while\n   they remain pending, so opening or re-running the PR early only produces a\n   red check. `required` does not rerun the full `testing` gate. For\n   every non-Dependabot\n   promotion it verifies that the head is the current `testing` tip and that\n   `main` is already merged back into `testing`; code-bearing promotions must\n   also have a successful full-gate record for that exact commit, or for the\n   closest gated `testing` commit when every path since it is docs/site-only,\n   and `VERSION` newer than every release tag. A non-Dependabot promotion also\n   needs the escalation workflow's `race` job to succeed for this head; it\n   starts with the PR, and `required` waits for it under a bounded budget.\n   If it fails with \"Promote the current testing tip\", push the final commit to\n   `testing` and reopen or update the PR. If it fails with \"Merge main back\n   into testing\", merge `origin/main` into `testing` first. If it fails with\n   \"changes non-docs paths after the gated commit\", push the final code commit\n   and let its full gate finish. If it fails with \"VERSION must be newer\", bump\n   `VERSION` above every tag and push the commit. If GitHub does not create the\n   `testing` push run, dispatch the full gate on the current tip and wait for it\n   to succeed; the proof accepts that run as an equivalent testing gate:\n   ```sh\n   gh workflow run check.yml --ref testing\n   ```\n4. Merge with a merge commit:\n   ```sh\n   gh pr merge <number> --merge\n   ```\n   Squash and rebase are disabled on `main`; they would replace the reviewed\n   testing history instead of preserving it.\n5. The merged-PR release run starts as soon as the promotion merge lands; wait\n   for its publish job (and the Pages run, when applicable) to finish, then\n   merge `main` back into `testing` so the next promotion is up to date:\n   ```sh\n   git fetch origin main\n   git switch testing\n   git merge --ff-only origin/main\n   git push origin testing\n   ```\n   If `testing` moved after the promotion merge, merge `origin/main` normally\n   and resolve conflicts before the next promotion.\n\nFor a code-bearing promotion, the merged-PR release run creates the annotated\nrelease tag on the reviewed merge commit and publishes the image. It never\npushes `main`. A delivered `main` push is an idempotent fallback; a manually\npushed `v*` tag remains the explicit recovery path. Do not push a `v*` tag as\npart of feature work; the manual tag path is only for an explicitly verified\nrelease and must match `VERSION`.\n\nDependabot version updates target `testing`. Dependabot security updates target\nthe default branch and are the only exception to the testing-ancestry check;\nthey also skip the version check. They still run the full gate and the\n`required` check. A security-only merge normally publishes no image and creates\nno tag because `VERSION` is already tagged; if `VERSION` is still untagged, that\nmerge can publish the pending version. Merge `main` back into `testing` and\ninclude the fix in the next versioned promotion.\n\nDocs and site-only pushes to `testing` skip image work. A docs/site-only\npromotion to `main` skips the `VERSION` and full-gate proofs, validates the\nMarkdown, generated site, workflow policy and docs contracts in `required`, and\nthe merged-PR release path records the change as docs-only, so it does not\nrebuild images or cut a release. A Pages-relevant change deploys the site from\nthe `main` push, or from the Pages `workflow_dispatch` fallback when that push\nworkflow is not delivered.\n\n`AGENTS.md` is intentionally local and ignored by the publication guard. Keep its\nworking instructions aligned with this shared guide; do not force-add private\ninstruction files to publish workflow policy.\n\n## Development dependencies\n\nLinux is supported. Version sources are:\n\n- Go: [go.mod](go.mod).\n- Node: [.node-version](.node-version).\n- Python: [.python-version](.python-version).\n- `jq`: the workflow contract suite executes the promotion gate's shell\n  predicates, so the core checks need the `jq` binary on `PATH`.\n- Browser tooling: [requirements-dev.txt](requirements-dev.txt).\n- Documentation site: [requirements-docs.txt](requirements-docs.txt).\n\nThe proxy embeds its vanilla JavaScript/CSS and needs no frontend build or Node\nruntime in deployment. Node/jsdom, Python/Playwright, Python-Markdown and PyYAML\nare development and documentation tools.\n\n```sh\nnpm ci --ignore-scripts\npython3 -m venv .venv\n. .venv/bin/activate\npython -m pip install --require-hashes -r requirements-dev.txt\npython -m playwright install chromium\n```\n\nOn fresh Linux installations, Chromium may also need system libraries; use\n`python -m playwright install --with-deps chromium` with appropriate installation\npermissions. Go race checks require `CGO_ENABLED=1` and a working C compiler;\nthe regular proxy build does not require a native SQLite driver.\n\n## Checks\n\n```sh\nscripts/check.sh\n```\n\nThe shared script owns the core verification commands. They include offline\ndocumentation-link, publication-ignore and typography regressions (Git is\nrequired), the generated-site contract, the documentation readability check and\nthe workflow/automation policy.\n\nThat policy suite runs the workflow files of the ref under test. A\n`pull_request` run evaluates its own head revision rather than the base\nbranch's, so a workflow change is judged as this pull request ships it. Review\nthe workflow diff itself, since the run that validates it was configured by the\nsame commit; only the post-merge `main` state proves what landed.\n\n`npm test` runs the jsdom suites and the request-log merge regression probe\nseparately. All tests and disposable harnesses\nlive in [tests/](tests/README.md), with suffix-free physical filenames. Go's\ntemporary overlay adds its required virtual `_test.go` names; Python unit\nmodules live in `tests/python/`. Use `scripts/check.sh go test` for targeted Go\nchecks and `scripts/check.sh go vet` or `scripts/check.sh go mod tidy` to include\ntest code and dependencies. Raw `go test ./...` does not discover the relocated\ntests and can report success without running them. Re-run checks after your\nlast edit. Concurrency changes need race coverage. JavaScript unit checks do\nnot establish real canvas rendering, layout, focus or viewport behavior.\n\n### Documentation site\n\nThe public site is generated from the existing Markdown, not maintained as a\nsecond documentation tree. `site-src/` owns the layout, styles, and brand\nassets; `scripts/build_site.py` renders the pages, rewrites repository links,\nand emits the search index, sitemap, 404 page and the machine-readable docs\noutputs described below. The generated `site/` directory is ignored and never\ncommitted.\n\n```sh\npython3 -m pip install --require-hashes -r requirements-docs.txt\npython3 -B -O -m tests.python.site\npython3 scripts/build_site.py --output site\n```\n\nBoth requirements files are hash-pinned and every install command passes\n`--require-hashes`, so resolution is reproducible and a substituted file fails\nthe install. After changing a pin, regenerate the hash block for that version\nfrom the PyPI JSON document (`https://pypi.org/pypi/<project>/<version>/json`,\n`digests.sha256` of every non-yanked file, one `--hash=sha256:` line each), keep\nthe pins sorted as they are, and run the install above once to prove the file.\n\nFor a local preview, serve `site/` from a separate terminal with\n`python3 -m http.server --directory site 8082`; do not point it at the proxy or\nuse the main `:8080` instance. The `docs.yml` workflow builds the site for\ndocumentation changes, and `pages.yml` deploys from `main` through the official\nGitHub Pages Actions flow. Repository-level Pages enablement and the\n`github-pages` environment are one-time administrator settings.\n\nThe shell every page loads before content renders is owned by `SHELL_ASSETS` in\n`scripts/build_site.py`: `tokens.css`, `themes.css`, `site.css`,\n`theme_boot.js`, `theme_state.js`, `site_theme.js` and `site.js`. Each is\npublished at a content-hashed name such as `site.11c6502e41.css`.\n\n`tokens.css` is derived from the dashboard palette. `themes.css`,\n`theme_boot.js` and `theme_state.js` are published byte-for-byte from\n`internal/web/static`, so the dashboard and the site share one palette owner,\none registry and one state module. `tests/python/site.py` checks that identity,\nthe load order and the registered palette ids.\n\nGitHub Pages sets its own `Cache-Control`, so the URL is the only cache key this\nrepository controls. A page cached from the previous deployment names the\nprevious hash, and it must find those bytes. The build republishes the last\n`SHELL_RETENTION` generations of each shell file, regenerated from the revisions\nthat produced them, which is why the Pages workflow checks out full history.\n\nA checkout without history still builds the current page correctly but cannot\nretain earlier generations. Do not add a hand-written reference to an unhashed\nname; `tests/python/site.py` rejects one.\n\n### Machine-readable documentation\n\n`scripts/build_site.py` drives `scripts/site_llm.py`, which writes a Markdown\ntwin beside every rendered page, plus `llms.txt`, `llms-full.txt` and\n`docs.json`. The MCP server embeds a checked-in copy at\n`internal/docs/docs.json`; never edit that file by hand.\n\nRegenerate it after any Markdown, title, navigation or description change:\n\n```sh\npython3 scripts/build_site.py --output site --write-manifest\n```\n\n`tests/python/site.py` fails when the embedded copy is stale, when a page does\nnot advertise its Markdown twin, or when a generated URL names a missing file.\nThe MCP tools `docs_list`, `docs_search` and `docs_read` read that index and\nmake no proxy request.\n\n### Documentation prose\n\nWrite for a reader who is scanning. Keep one idea per paragraph and roughly 110\nwords or fewer. Use a list or table when a sentence carries three or more\nparallel items, and split a paragraph when it changes subject.\n\n`tests/python/docs_readability.py` enforces the word limit on hand-written\nMarkdown. `docs/settings.md` is generated from the schema and is excluded.\n\nThe site is published at `https://millivolt.llm4people.dev/`. That origin has two\nowners, and neither is a file in this repository: the Pages custom domain in the\nrepository settings, which is what GitHub serves and certifies, and the DNS\nrecord, which is a `CNAME` from `millivolt` to `llm-4-people.github.io` with the\nproxy disabled. `scripts/build_site.py` warns when a build for `SITE_URL` names\na different host than `DEFAULT_BASE_URL`, because that is what a half-finished\nmigration looks like. GitHub ignores a `CNAME` file in an Actions deployment, so\nthis repository does not ship one.\n\n### Brand plates\n\nThe README covers, specification strips, Open Graph card and GitHub social\npreview are generated, not hand-edited. `scripts/brand/facts.py` owns the\nheadline, the four specification facts and the sample-history values.\n`scripts/brand/manifest.json` owns each target's dimensions and hash.\n\nRegenerate every plate after a copy or fact change:\n\n```sh\npython3 -m pip install --require-hashes -r requirements-docs.txt\npython3 -m scripts.brand.build\n```\n\nThe PNG renders need Playwright's Chromium; the SVG strips do not.\n`python3 -m scripts.brand.build --check` verifies every committed asset against\nthe manifest and re-renders both SVG strips from source. CI runs that check.\nThe tool count in the specification strip comes from\n`scripts/mcp_registry.py`, the same parser the MCP docs test uses, so adding a\ntool cannot leave the art behind.\n\nUpload `.github/social-preview.png` under the repository's Settings, Social\npreview after it changes. That upload is a GitHub setting, not a repository\nfile.\n\n### Push gate\n\nNever push `main` directly: open a promotion pull request and merge it with a\nmerge commit. Do not push `testing` until the exact commit you will push has\npassed the same CI gate jobs. A request to push is not a waiver.\nPackage-scoped `go test` and `npm test` during development are not sufficient.\nCI's source-and-unit step is the default core suite:\n\n```sh\nscripts/check.sh\n```\n\nA run may not start while a code-scanning finding is unresolved.\n`scripts/security_gate.py` reads `code-scanning/alerts?state=open` from the\nrepository API in the `unit` job and again in `publish` before the version tag\nis created. Fix the finding, or record a dismissal with a reason that explains\nwhy the code is correct; a dismissed alert is not open, and the security page\nkeeps that reason beside the location. An API the gate cannot read fails\nclosed rather than passing.\n\nCI sets `GOTOOLCHAIN=local`, so the host Go must match the `go` version in\n`go.mod`. On a host with an older base Go, install Go 1.27.2 or select the\nmatching toolchain before running the gate; `GOTOOLCHAIN=local` alone cannot\nupgrade an older installation.\n\nFull-gate CI events also run the isolated browser fixtures (desktop and mobile)\nin the `browser` job. Use `scripts/dev.sh` plus `scripts/check.sh browser` as\nbelow, with `MILLIVOLT_OPERATOR_TOKEN` set. Re-run both after the last commit. A\nred GitHub check after a push means the gate was skipped, stale, or unmonitored:\nfix, re-run, and push only a passing tree, then watch the new run to completion.\n\nThat same `browser` job also runs the live MCP integration test, which\n`scripts/check.sh browser` alone does not run. It is mandatory on the same\ncommit:\n\n```sh\nMILLIVOLT_MCP_INTEGRATION=1 scripts/check.sh go test -count=1 ./internal/mcp/...\n```\n\nThe test starts a private dev instance through `scripts/dev.sh` on its own\nloopback port and scratch database, drives every registered tool, and stops the\ninstance again, so it does not touch the instance the browser check uses.\n\nBefore every push, check open pull requests and report any that are awaiting\nthe user's review or approval. Do not approve or merge them without explicit\nauthorization. Use:\n\n```sh\ngh pr list --state open --json number,title,author,isDraft,reviewDecision,mergeable,statusCheckRollup,url\n```\n\nAfter pushing, monitor the GitHub Actions run for the pushed commit until every\nrequired job completes successfully. The local gate cannot see the browser,\nMCP integration, container, code-scanning, or dependency-review jobs. Find the run with\n`gh run list --branch <branch> --limit 1`, then wait for it with\n`gh run watch <run-id> --exit-status`. A queued or in-progress run is not green.\nIf any job fails, treat the push as incomplete: fix the root cause, rerun this\ngate, and push the fix. Do not leave `testing` or `main` red or start unrelated\nwork on top of a failing run.\n\nFor changes to configuration, update the Config/default/validation/schema owners\nand regenerate the example as described in [configuration](docs/configuration.md).\nDo not edit `proxy.yaml`: it may be a running operator's configuration.\n\n## Isolated development\n\nNever use an existing main instance on port 8080 for tests. Use the lifecycle\nscript, with cleanup even if verification fails:\n\n```sh\n(\n  set -e\n  trap 'scripts/dev.sh stop' EXIT\n  export MILLIVOLT_OPERATOR_TOKEN='dev-instance-credential'\n  scripts/dev.sh\n  scripts/check.sh browser --target http://127.0.0.1:8081\n)\n```\n\nThe dev instance shares your shell environment, so a local\n`MILLIVOLT_OPERATOR_TOKEN` arms its operator gate; browser and stress harnesses\nneed the same value for gated fixture cleanup. An instance started without it\nserves reads only and denies every mutation.\n\n`scripts/dev.sh status` reports the private instance. The script builds first,\nthen replaces only its tracked dev process; a failed build leaves it running.\n\nThe tracked identity is the pid file. `status`/`stop` fall back to the listener\non the instance's port when the file names a dead pid. A rebuild child rewrites\nthe file only once it is fully booted, so a child that dies before readiness\nwould otherwise strand the instance. The fallback still requires the\nprocess to carry this instance's exact `-pid-file` flag.\nStarting/restarting development resets its disposable database and private config,\nseeded from the public example by default. `DEV_CONFIG=proxy.yaml` explicitly\nopts into copying an operator config; it is never selected implicitly.\nUI-triggered rebuilds keep that private config and update the tracked PID.\n\nOverrides are deliberately restricted: `DEV_PORT` is a non-production port,\n`DEV_HOST` is loopback, and `DEV_DB` is a permitted scratch filename or `none`.\n`DEV_COPY_DB=1` seeds a consistent online backup of local history: use it only\nwhen that history is authorized for the task, and treat the scratch copy as\nsensitive. `DEV_COPY_DB=redacted` instead derives the separately validated\ndocumentation copy described below; `0` keeps fresh fixture state. Do not use\nbroad process kills or start an ad-hoc second main instance.\n\nThe browser fixtures share private-target/config/database and redirect guards.\nThey disable SSE and test bootstrap/poll rendering, not uninterrupted live-feed\ndelivery. They remove only their synthetic client records. Their assertions must\nremain enabled under Python `-O`; the guard suite verifies this.\n\n### Live Chrome DevTools verification\n\nFrontend changes are additionally verified in a visible Chrome window through\nChrome DevTools - headful, never headless. Sign in with the dev operator token,\ndrive the real fixture traffic and the actual controls, and check console\noutput, element geometry, the accessibility tree and screen flow in the\nrendered page. Narrow fixture data passes the harnesses but can hide\ndistribution problems (wide values, wrapping, density); the live session is\nwhere those surface. Keep the dev instance and the window open while you look;\nstop the instance with `scripts/dev.sh stop` when done.\n\nFixture traffic for these sessions has its own lifecycle owner, never a paid\nprovider and never the main instance on `:8080`:\n\n```sh\nscripts/dev-traffic.sh         # bursts of neutral loopback traffic at the dev instance\nscripts/dev-traffic.sh status\nscripts/dev-traffic.sh stop\n```\n\nBursts land about a minute apart so one-minute chart buckets gain a bucket\nper burst; each run includes recovered 429s (rate-limited, not errors) and one\nfinal 400 so both health surfaces carry data.\n\n## Container development\n\nNormal [compose.yaml](compose.yaml) only runs a published image. For a local\nsource build, use [compose.dev.yaml](compose.dev.yaml) from the checkout root.\nIt is a complete Compose file, not an overlay: project and service are both\n`millivolt-dev`, and the container takes the project-scoped name Compose\nderives from them.\n\n```sh\ndocker compose -f compose.dev.yaml up -d --build\ndocker compose -f compose.dev.yaml logs --tail 50\ndocker compose -f compose.dev.yaml down\n```\n\nThe development project keeps its containers and named volumes separate from a\nnormal deployment, including when `COMPOSE_PROJECT_NAME` is set outside the\ncheckout. Its `MILLIVOLT_DEV_PORT` and `MILLIVOLT_DEV_IMAGE` inputs are defined\nonly there, and it shares the deployment Compose's `MILLIVOLT_MEM_LIMIT` and\n`MILLIVOLT_PIDS_LIMIT` bounds. Choose an unused development port if `scripts/dev.sh` is already\nrunning.\n\nRerun the same `up --build` command after source changes. The resulting runtime\nimage has no compiler or source tree, so dashboard rebuild is unavailable.\n`down` preserves its named volumes unless you explicitly request deletion.\nThis source-image workflow does not replace `scripts/dev.sh`: the host browser\nand stress fixtures require that script's private process/database identity.\n\n## Documentation screenshots\n\nThe published gallery uses recorded metrics from an explicitly authorized,\nredacted local-history snapshot, not fabricated timing or cost values. Never\npoint capture tools at a main instance or serve a raw history copy for screenshots.\nThe source is the checkout's local `proxy.db`, opened read-only through the existing\nonline-backup helper. This workflow needs explicit authorization for that history.\n\nFrom a checkout with browser dependencies installed and that authorized source:\n\n```sh\n(\n  set -e\n  export DEV_PORT=18081 DEV_HOST=127.0.0.1\n  export DEV_DB=/tmp/millivolt/millivolt-dev-docs.db\n  export DEV_CONFIG=proxy.example.yaml DEV_COPY_DB=redacted\n  trap 'scripts/dev.sh stop' EXIT\n  scripts/dev.sh up\n  python3 -B -O -m tests.explorer_check \\\n    --target \"http://${DEV_HOST}:${DEV_PORT}\" --docs-history docs/images\n)\n```\n\nChoose an unused permitted dev port. Before startup, `dev.sh` derives a new\nmetrics-only database: identifiers are replaced, content/headers/debug data are\nremoved, and recorded timing, token and cost values are retained. The raw online\nsnapshot is temporary and never served. Treat even the derived database as\nsensitive; retained usage and timestamps can reveal activity patterns.\n\nThe view list is a registry, not a capture script. `scripts/gallery/data.py`\ndeclares every plate: its published path, title, description, scene, named\nviewport and setup. `tests/docs_capture.py` owns the scene strategies (page,\nelement, scoped explorer, absorbed retries, drawer, console, settings, chart,\nwindow picker, theme tray). `scripts/gallery/compose.py` turns each scene into\none plate: the same document is photographed on Instrument Black and Instrument\nClear, then split along the diagonal from bottom-left to top-right. `applyState`\nis the one theme mutation path, so an open drawer, a selected filter or an open\ntray survives the second half.\n\nThe run writes `docs/images/capture.json`, which records every plate's bytes,\ndimensions and SHA-256, the verified record count, and a digest of\n`internal/web/static`. It also writes the generated `docs/gallery.md`. Commit\nboth with the images. `tests/python/gallery.py` fails when a registered plate\nhas no capture, a capture is not registered, a byte or dimension drifts, the\ndigest no longer matches the dashboard source, or the gallery page is stale.\nA UI change therefore requires a recapture in the same branch, not a later one.\n\nCapture last. The gallery is a picture of the shipped dashboard, so a markup,\nCSS or layout change dates every image that shows the affected surface.\nRecapture in the same branch once the last layout edit is in, never before it,\nand recapture again if a later edit moves what an image shows. A recapture diff\nis the review set: inspect every changed plate, and expect geometry changes\n(for example the request table's 8px cell padding and retry sub-rows) to come\nwith them.\n\nThe capture mode revalidates every row and its provenance, plus exact public\nconfiguration bytes, before and after browser capture. It permits only read-only\nsame-origin requests: no inference, POST, purge or Settings save.\n\nImages are staged before publication, and the exit trap stops the private\nprocess. Review every plate before committing. SSE is deliberately disabled, so\nthe images' offline indicator describes a static capture session, not current\nservice health. Captures keep the same category folders under `docs/images/`:\n`overview`, `charts`, `explorer`, `requests`, `console`, `settings` and `theme`.\nThe site fails on any image under `docs/images/` without a Markdown consumer, so\na recapture that drops a view cannot leave an orphan behind.\n\nThe independent `--docs-images` option remains a strict synthetic regression.\nRun it only with `DEV_COPY_DB=0` and direct those two images to a scratch directory,\nnot `docs/images`. It creates and cleans up its own six-request fixture and\nrejects copied history. Neither capture mode is a performance or compatibility\nbenchmark; do not weaken one mode's admission checks to accommodate the other.\n\n## Performance evidence\n\nThe published tables, method and limitations live in\n[performance and resource usage](docs/performance.md). That page is the single\nsource for measured numbers; do not copy them into other documentation and do\nnot edit the page by hand. It is rendered from `perf/results.json`, and\n`tests/python/site.py` fails when the two disagree.\n\n`scripts/perf.sh` owns a repeatable local measurement run without touching the\nmain instance. It starts fresh private instances on a disposable port and stops\nthem through `scripts/dev.sh`:\n\n```sh\nscripts/perf.sh docs      # every published measurement, bundle and page\nscripts/perf.sh bench     # isolated Go benchmarks\nscripts/perf.sh stress    # private fast and streaming ramps\nscripts/perf.sh streaming # sustained end-to-end SSE throughput ramp\nscripts/perf.sh sustained # fixed-duration fast-response capacity levels\nscripts/perf.sh image     # disposable image content and compressed size\nscripts/perf.sh all       # image, bench, then stress\n```\n\n`docs` refuses a dirty tree, runs the complete documented set, writes\n`perf/results.json`, and regenerates `docs/performance.md`. Commit the bundle\nand the page together. Never hand-edit either one; a missing stage, failed\nresponse or unbalanced durable result aborts the run instead of publishing a\npartial page.\n\nThe bundle is also the source of the facts the page describes: the commit, date\nand platform, each stage's response shape (frame count, usage and unit cost),\nthe configured durations, and the harness declarations for captures, previews\nand the observer. `cmd/stress` records the fixture shape in its workload line\nand the collector validates it per stage, so a table and the sentence beside it\ncannot describe different runs. The landing headline reads the same bundle;\n`tests/python/performance.py` renders two bundles that differ only in those\nfields and fails if any published sentence keeps its old text.\n\nFor request, SSE-event, response-byte and output-token rates, use the\n`streaming` mode. It derives those rates from responses the client accepted\nbyte-for-byte, and it is still a synthetic-fixture measurement, not a universal\ncapacity claim.\n\nFor an individual stress run with the private dev instance already running:\n\n```sh\ngo run ./cmd/stress -target http://127.0.0.1:8081 -concurrency 1,8,32,128 -duration 5s\n```\n\nThe harness does not manage or reconfigure the proxy. It uses a local synthetic\nupstream and checks exact bytes, durable rows/tokens/cost and the same-process\nstorage-drop delta.\n\nA drop is a failed stage even if every HTTP request succeeded, unless the run\nasks for an overload observation with `-allow-drops`. That mode still requires\n`durable + dropped = successful requests` and still aborts on a response\nfailure. Read `go run ./cmd/stress -h` for workload/safety controls.\nThe ramp retains its cumulative fixture history across measured stages, then\nremoves only its unique client records after measurements finish. Cleanup has\nits own bounded wait even after cancellation and revalidates private process,\nconfig and database ownership before every deletion. A cleanup failure is\nreported, never silently treated as success.\n\nReport workload, duration, concurrency, configuration, contention and whether\nstorage/observers were active. Separate request throughput from durable\nthroughput. Closed-loop bursts, microbenchmarks and local upstreams do not\nestablish sustained production capacity. The current storage contract and\ncapacity caveats live in [operations](docs/operations.md#storage-and-accounting).\nUse the existing `BenchmarkStorageWriter` and `BenchmarkProxyDurableContention`\nfor isolated writer/contention comparisons; neither replaces a real HTTP run.\nFor the analytical projection's memory, use the self-seeded\n`BenchmarkProjectionFootprint` (retained and transient bytes per stored record)\nand `BenchmarkProjectionProcessRSS` (process RSS after readiness) from the test\noverlay; they need no running instance:\n\n```sh\nscripts/check.sh go test -run='^$' -bench='BenchmarkProjection' -count=1 ./internal/web\n```\n\n## Versioning and publication\n\n[VERSION](VERSION) is the only semantic version source; do not duplicate it in\npackage manifests, build arguments or image metadata. Normal and prerelease\nSemVer are supported without build metadata. A release tag must be exactly\n`v` followed by that file's version. The release CLI validates the same contract:\n\n```sh\nmillivolt_version=\"$(tr -d '\\r\\n' < VERSION)\"\ngo run ./cmd/release -revision \"$(git rev-parse HEAD)\" -tag \"v$millivolt_version\"\n```\n\nPublication is automatic. A code-bearing versioned promotion releases when the\npromotion PR merges, after the full gate has passed for the promoted commit, or\nafter the closest gated `testing` commit plus a docs-only delta.\n\nA non-Dependabot promotion also requires a successful\n[escalation](.github/workflows/escalation.yml) run for the reviewed head. The\npromotion PR starts it automatically, and `required` waits for it under a\nbounded, fail-closed proof. The merged-PR\nevent carries the exact merge commit; a delivered `main` push is an idempotent\nfallback, so a dropped push event cannot leave the release untagged. A\nDependabot security PR targets `main` and runs the full gate itself rather than\nreusing a `testing` result. The release `publish` job waits for `required`.\nThe `publish-testing` job waits for `unit`, `browser` and `container` instead,\nbecause a testing push has no promotion proof to wait for:\n\n1. A code-bearing promotion PR owns the version bump. `required` compares\n   VERSION against every existing `v*` tag with SemVer precedence and rejects a\n   non-Dependabot main PR unless VERSION is newer. Docs/site-only promotions\n   skip that comparison, validate docs, workflow policy and the site in\n   `required`, and stay release-free. If VERSION is already tagged, no\n   release is cut: this is the Dependabot security-merge case, and the next\n   versioned promotion releases the change.\n2. The workflow creates the annotated `v<version>` tag on the reviewed\n   promotion merge commit and builds and publishes the multi-arch image with\n   `main`, `sha-*`, `version` and (for non-prereleases) `latest` tags, including\n   an SBOM and max-mode provenance. The `sha-*` tag and OCI revision label name\n   the promotion merge commit that was built.\n3. Only after the image exists does it push the tag and create the GitHub\n   release. It never pushes `main`. Release notes filter merge commits, dedupe\n   subjects, use the lowercase image path, include the digest, and link the\n   compare range. A failed image build leaves no public release pointing at a\n   missing image. `main` and `latest` exclude prereleases; the `testing` alias\n   never moves them.\n\nDocs and site-only pushes to `testing` skip image work. They validate Markdown,\nthe generated site, workflow policy and docs contracts.\n\nA docs/site-only main promotion also skips the VERSION and full-gate proofs but\nruns the same Markdown, generated-site, workflow-policy and repository checks in\n`required`. A Pages-relevant merged main push stays docs-only, so Pages deploys\nwithout rebuilding images or cutting a release.\n\nThe merged-PR release path classifies the change and skips publication. A\ncode-bearing promotion must carry a VERSION newer than every existing tag and\ncuts a release. A manually pushed `v*` tag\nstill ships exactly as tagged through the same\npipeline, with the image published before the release is created. A manual tag\nmust match VERSION. Code-bearing pushes to `testing` publish the moving\n`ghcr.io/llm-4-people/millivolt:testing` image after the same checks and\ncontainer builds, without cutting a release or any version tag. Its OCI version\nlabel reports the embedded VERSION, which can lag the latest release.\nManual validation of a candidate remains available:\n\n```sh\nscripts/check.sh release -revision \"$(git rev-parse HEAD)\" -tag \"v$millivolt_version\"\n```\n\nRun the shared checks before relying on a release. Confirm the hosted container\nbuild and smoke tests succeed, then check the package visibility and anonymous\npull. Do not report a release/image as available merely because validation or a\nlocal build passed. Image usage and persistence limits live in\n[operations](docs/containers.md#versions-and-images). The gate clears inherited\nGit routing/configuration variables before checking\nsource identity, so another worktree or external ignore policy cannot satisfy\nthe release checks accidentally.\n\nOnly push the intended release tag after that check succeeds. Main changes go\nthrough the protected pull request path. The workflow publishes images\nautomatically and creates the release with notes generated from the commit log.\nNative container checks run before the multi-platform publish job. After the\npromotion run, verify the published tag and image:\n```sh\ngh release view \"v$millivolt_version\"\ndocker buildx imagetools inspect \"ghcr.io/llm-4-people/millivolt:$millivolt_version\"\n```\n\n### If a release fails\n\n- Before the tag is pushed, no public release exists. Fix the failure and rerun\n  the main workflow or promote a new version.\n- After the tag is pushed, keep the tag in place. If the GitHub release is\n  missing, create it from that tag or publish a new patch version. An automatic\n  tag push does not start a second workflow run.\n- Do not move or delete a published version tag.\n\nFor local container verification, build with Docker, resolve the image's\nimmutable ID, then use the same fixture as CI:\n\n```sh\ndocker build -t millivolt:check .\nmillivolt_image_id=\"$(docker image inspect --format '{{.Id}}' millivolt:check)\"\nscripts/check.sh container --image \"$millivolt_image_id\"\n```\n\nThe shared container mode validates Compose defaults and owns only its\ndisposable, network-isolated Docker fixture, selected by immutable image ID.\nIt checks startup, HTTP, Settings and durable state across stop/start, then backs\nup the stopped volumes and restores into another fresh container. Recovery must\nretain settings, history and private file ownership/modes. It never publishes\na host port or reuses an operator volume. It complements, rather\nthan replaces, the host lifecycle in `scripts/dev.sh`.\n\n## Change checklist\n\nUse sentence case or lowercase in prose, headings and labels. Avoid em dashes;\npreserve exact protocol names, identifiers, user data and license wording.\n\n- Add a targeted regression for a reproduced defect; preserve existing coverage.\n- Keep defaults, units, schemas and state transitions at their canonical owner.\n- Measure allocations/latency when changing the hot path or analytical folds.\n- Check saved views, mobile layout and accessibility for visible changes.\n- Update the relevant existing documentation, not duplicate specifications.\n- Exclude local configs, databases, tokens, captures and generated test artifacts.\n- Preserve dependency licenses. Report vulnerabilities using [SECURITY.md](SECURITY.md),\n  not a public issue containing sensitive reproduction data.\n\nDependabot checks Go, npm, Python, Docker and GitHub Actions dependencies weekly\nwith grouped minor and patch updates. Review dependency changes and re-run\nchecks; runtime version files still require deliberate updates and verification.\n\nThe Docker `golang` base is deliberately left manual because its tag must move\nwith go.mod; distroless updates remain automated. Security updates target\n`main` as described in the branch workflow. Dependency review runs on pull\nrequests, and a scheduled `govulncheck` workflow covers the Go module graph.\nThe scanner is pinned as a tool dependency in `tools.go`, so it resolves from\nthis module and `go.sum` covers it instead of a version being fetched fresh on\neach run. These scans complement tests; a clean scan is not a security guarantee.\n"
    },
    {
      "path": "SUPPORT.md",
      "slug": "support",
      "output": "support.html",
      "markdown": "support.md",
      "url": "https://millivolt.llm4people.dev/support.html",
      "markdown_url": "https://millivolt.llm4people.dev/support.md",
      "title": "Support",
      "description": "millivolt is pre-1.0 and maintained on a best-effort basis. There is no response-time SLA.",
      "group": "Project",
      "order": 18,
      "bytes": 1101,
      "sha256": "deb5db5ba19a8f3c21c997bcbbf5fe10d5ea1f3e299c7c7286a1d3210d6622b1",
      "sections": [
        {
          "heading": "Read first",
          "id": "read-first",
          "text": "Documentation index Quickstart Operations Reverse proxy Security",
          "context": ""
        },
        {
          "heading": "Where to ask",
          "id": "where-to-ask",
          "text": "Usage, configuration, or deployment question: open a usage question . Reproducible defect: open a bug report . Concrete proposal: open a feature request . Security vulnerability: use the private advisory channel . Do not open a public issue. Search existing issues before opening a new one. Include the millivolt version or revision and a sanitized configuration shape. Remove credentials, private prompts, databases, and host-specific paths.",
          "context": ""
        }
      ],
      "markdown_text": "# Support\n\nmillivolt is pre-1.0 and maintained on a best-effort basis. There is no\nresponse-time SLA.\n\n## Read first\n\n- [Documentation index](docs/README.md)\n- [Quickstart](README.md#quickstart)\n- [Operations](docs/operations.md)\n- [Reverse proxy](docs/reverse-proxy.md)\n- [Security](SECURITY.md)\n\n## Where to ask\n\n- **Usage, configuration, or deployment question:** open a\n  [usage question](https://github.com/LLM-4-People/millivolt/issues/new?template=question.yml).\n- **Reproducible defect:** open a\n  [bug report](https://github.com/LLM-4-People/millivolt/issues/new?template=bug_report.yml).\n- **Concrete proposal:** open a\n  [feature request](https://github.com/LLM-4-People/millivolt/issues/new?template=feature_request.yml).\n- **Security vulnerability:** use the\n  [private advisory channel](https://github.com/LLM-4-People/millivolt/security/advisories/new).\n  Do not open a public issue.\n\nSearch existing issues before opening a new one. Include the millivolt version\nor revision and a sanitized configuration shape. Remove credentials, private\nprompts, databases, and host-specific paths.\n"
    },
    {
      "path": "LICENSE",
      "slug": "license",
      "output": "license.html",
      "markdown": "license.md",
      "url": "https://millivolt.llm4people.dev/license.html",
      "markdown_url": "https://millivolt.llm4people.dev/license.md",
      "title": "MIT License",
      "description": "MIT license terms for millivolt.",
      "group": "Project",
      "order": 19,
      "bytes": 1079,
      "sha256": "41be007c4f4c5f9e5ef3cc85e50b6f37e950e87914ad2d98bc8ec584f28014f7",
      "sections": [],
      "markdown_text": "MIT License\n\nCopyright (c) 2026 millivolt contributors\n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE.\n"
    },
    {
      "path": "THIRD_PARTY_NOTICES.md",
      "slug": "third-party",
      "output": "third-party.html",
      "markdown": "third-party.md",
      "url": "https://millivolt.llm4people.dev/third-party.html",
      "markdown_url": "https://millivolt.llm4people.dev/third-party.md",
      "title": "Third-party notices",
      "description": "millivolt's MIT license covers the project's own work, not a relicensing of dependencies.",
      "group": "Project",
      "order": 20,
      "bytes": 3313,
      "sha256": "2060b9eee31bd4c5922bfdff505ee6c49ca9eebf798a5180b425b5726970a323",
      "sections": [
        {
          "heading": "Embedded dashboard library",
          "id": "embedded-dashboard-library",
          "text": "uPlot 1.6.32 is vendored as internal/web/static/vendor/uplot.js and uplot.css . Copyright (c) 2022 Leon Sorokin. Its complete MIT notice is kept beside the assets and included in the embedded filesystem. Preserve that notice when redistributing the library or built dashboard. The notice was checked against the upstream versioned license . Update the version, assets and notice together when changing this dependency.",
          "context": ""
        },
        {
          "heading": "Embedded typefaces",
          "id": "embedded-typefaces",
          "text": "The dashboard and the documentation site ship four WOFF2 faces in internal/web/static/fonts : Instrument Sans (roman and italic), Instrument Serif, and JetBrains Mono. They are Copyright 2022 The Instrument Sans Project Authors, Copyright 2022 The Instrument Serif Project Authors, and Copyright 2020 The JetBrains Mono Project Authors. All three families are licensed under the SIL Open Font License 1.1 ; the complete notice and copyright lines are kept beside the files and included in the embedded filesystem. The dashboard, the docs site and the generated brand plates all consume these exact faces, so no third-party font request is made at runtime. Preserve the notice when redistributing the fonts or a built dashboard.",
          "context": ""
        },
        {
          "heading": "Module and development dependencies",
          "id": "module-and-development-dependencies",
          "text": "go.mod and go.sum identify Go dependencies; their upstream module distributions carry their own licenses. package-lock.json pins development-only jsdom dependencies. requirements-dev.txt pins Python browser tooling; Playwright selects its corresponding Chromium build. requirements-docs.txt pins the Python-Markdown renderer (BSD-3-Clause) used to build the static documentation site; PyYAML (MIT) is a development dependency used by the workflow policy checks. Node, Python and these build/test dependencies are not required to run the proxy.",
          "context": ""
        },
        {
          "heading": "Container distribution",
          "id": "container-distribution",
          "text": "The Dockerfile runs the notice collector against the exact target binary's Go dependency graph. It preserves module, package-ancestor and Go toolchain license, copyright, notice and patent files, plus the embedded uPlot notice, under /usr/share/licenses/millivolt . The deterministic manifest.json records versions, relative paths and SHA-256 content hashes. Missing notices and module replacements fail the build for review; this collector does not classify licenses or grant additional rights. The pinned distroless runtime retains its own files and dependency notices. Its upstream project documents the base-image contents. Node, Python and development dependencies are not copied into the runtime image. When distributing a binary by another route, generate and include the same bundle with go run ./scripts/licenses -target linux/amd64 -out NEW_DIRECTORY (or linux/arm64 ) and review the actual distribution. This source notice alone is not a complete binary-release license bundle.",
          "context": ""
        }
      ],
      "markdown_text": "# Third-party notices\n\nmillivolt's [MIT license](LICENSE) covers the project's own work, not a\nrelicensing of dependencies.\n\n## Embedded dashboard library\n\n[uPlot 1.6.32](https://github.com/leeoniya/uPlot/tree/1.6.32) is vendored as\n`internal/web/static/vendor/uplot.js` and `uplot.css`. Copyright (c) 2022 Leon\nSorokin. Its complete [MIT notice](internal/web/static/vendor/uplot.LICENSE)\nis kept beside the assets and included in the embedded filesystem.\nPreserve that notice when redistributing the library or built dashboard.\n\nThe notice was checked against the\n[upstream versioned license](https://github.com/leeoniya/uPlot/blob/1.6.32/LICENSE).\nUpdate the version, assets and notice together when changing this dependency.\n\n## Embedded typefaces\n\nThe dashboard and the documentation site ship four WOFF2 faces in\n`internal/web/static/fonts`: Instrument Sans (roman and italic), Instrument\nSerif, and JetBrains Mono. They are Copyright 2022 The Instrument Sans Project\nAuthors, Copyright 2022 The Instrument Serif Project Authors, and Copyright 2020\nThe JetBrains Mono Project Authors. All three families are licensed under the\n[SIL Open Font License 1.1](internal/web/static/fonts/LICENSE); the complete\nnotice and copyright lines are kept beside the files and included in the\nembedded filesystem. The dashboard, the docs site and the generated brand\nplates all consume these exact faces, so no third-party font request is made at\nruntime. Preserve the notice when redistributing the fonts or a built\ndashboard.\n\n## Module and development dependencies\n\n[go.mod](go.mod) and [go.sum](go.sum) identify Go dependencies; their upstream\nmodule distributions carry their own licenses. [package-lock.json](package-lock.json)\npins development-only jsdom dependencies. [requirements-dev.txt](requirements-dev.txt)\npins Python browser tooling; Playwright selects its corresponding Chromium build.\n[requirements-docs.txt](requirements-docs.txt) pins the Python-Markdown renderer\n(BSD-3-Clause) used to build the static documentation site; PyYAML (MIT) is a\ndevelopment dependency used by the workflow policy checks. Node, Python and\nthese build/test dependencies are not required to run the proxy.\n\n## Container distribution\n\nThe [Dockerfile](Dockerfile) runs [the notice collector](scripts/licenses/main.go)\nagainst the exact target binary's Go dependency graph. It preserves module,\npackage-ancestor and Go toolchain license, copyright, notice and patent files,\nplus the embedded uPlot notice, under `/usr/share/licenses/millivolt`.\nThe deterministic `manifest.json` records versions, relative paths and SHA-256\ncontent hashes. Missing notices and module replacements fail the build for\nreview; this collector does not classify licenses or grant additional rights.\n\nThe pinned distroless runtime retains its own files and dependency notices.\nIts [upstream project](https://github.com/GoogleContainerTools/distroless)\ndocuments the base-image contents. Node, Python and development dependencies\nare not copied into the runtime image.\n\nWhen distributing a binary by another route, generate and include the same\nbundle with `go run ./scripts/licenses -target linux/amd64 -out NEW_DIRECTORY`\n(or `linux/arm64`) and review the actual distribution. This source notice alone\nis not a complete binary-release license bundle.\n"
    }
  ]
}
