@bivelio/savings-layer 0.5.2 → 1.0.0

package/docs/terminales/README.md

@@ -9,20 +9,21 @@ terminal). Cada afirmación va marcada **[V]** (verificada en fuente) o **[I]**
 
 `bvsala gateway` es un proxy local medidor: escucha en `127.0.0.1`, reenvía
 cada petición al proveedor (`https://api.anthropic.com` por defecto) —**byte a
-byte**, salvo las palancas que se explican abajo (con licencia PRO, la de tarifa
-va encendida por defecto)— y, una vez servida la respuesta, lee el `usage` del
+byte**, salvo las palancas que se explican abajo (la de tarifa va armada por
+defecto)— y, una vez servida la respuesta, lee el `usage` del
 stream y lo convierte en coste. Ni tus prompts, ni las respuestas, ni la clave de
 tu proveedor salen de tu máquina hacia BiVelio: solo viaja el uso de cada
 petición —cuentas de tokens, coste, el id del modelo, un id de petición y los ids
 opacos de asiento y de sesión—, y la lista exacta de campos está en la
-LICENSE §5. Es fail-closed como el SDK: arranca solo con tu clave de servicio
-(`BIVELIO_SERVICE_KEY`) y una licencia BiVelio activa, que recoge con esa clave y
-cuya firma verifica en tu máquina. Una vez arrancado, jamás corta una petición en
-curso: si la licencia caduca o se revoca, solo las peticiones NUEVAS reciben un
-HTTP 402 hasta renovarla. La medición es best-effort: con la ingesta caída,
+LICENSE-CLOUD.md §5. **Open core**: arranca sin ninguna clave, en modo Community —todas
+las palancas locales armadas, cero telemetría, y el metering se queda en las
+rutas locales `/_bvsala`—. `BIVELIO_SERVICE_KEY` (opcional) añade el panel, los
+entitlements de la org y la recogida de licencia; una licencia PRESENTE pero
+caducada o revocada solo corta las peticiones NUEVAS con un HTTP 402 hasta
+renovarla, jamás una en curso. La medición es best-effort: con la ingesta caída,
 reenvía y avisa.
 
-Mide cada petición. Con licencia PRO aplica por defecto **una sola palanca**:
+Mide cada petición con contador de proveedor. La **palanca por defecto**:
 rebaja el TTL de escritura de caché mientras la sesión sigue caliente — cambia la
 tarifa, nunca el contenido que lee el modelo. Las demás (modelo hermano, esfuerzo
 por turno) van apagadas hasta que las enciendes. Y mide **todo el tráfico de inferencia**
@@ -31,8 +32,7 @@ lo que su terminal manda por fuera.
 
 En suscripción (login de claude.ai en Claude Code, cuenta ChatGPT en Codex) no
 hay factura por tokens: ese tráfico se mide a precio de lista equivalente y
-nunca se le acredita ahorro ni comisión; la licencia por asiento hace falta
-igual.
+nunca se le acredita ahorro ni comisión.
 
 ## Índice
 
@@ -51,8 +51,10 @@ igual.
 | [Crush](crush.md) | `http://127.0.0.1:8402/v1` | **con**, sin barra final | `~/.config/crush/crushrc` | — (config de usuario) | [V] |
 | [Droid](droid.md) | `http://127.0.0.1:8402` | sin **[I]** | `~/.factory/settings.json` | — (config de usuario) | validar en mano |
 | [Cline](cline.md) | `http://127.0.0.1:8402/v1` | **con** | UI | — | [V] |
-| [Gemini CLI](no-soportados.md#gemini-cli--no-se-mide-todavía) | — | — | env `GOOGLE_GEMINI_BASE_URL` | — | **no se mide**: el gateway no lee el dialecto de Gemini |
-| [Cursor](no-soportados.md#cursor--no-se-puede) | — | — | sus servidores, no tu máquina | — | **no se puede**: Cursor no alcanza `127.0.0.1` |
+| [Gemini CLI](gemini.md) | `http://127.0.0.1:8402` | n/a (protocolo Gemini) | env `GOOGLE_GEMINI_BASE_URL` | `bvsala gemini` ✅ | [V] en test (upstream falso): `:generateContent` y `:streamGenerateContent` |
+| [Cursor](cursor.md) (BYOK) | `http://127.0.0.1:8402/v1` | **con** | UI → Settings → Models → OpenAI API Base URL | — (config de la UI) | [I]: solo el tráfico con TU clave pasa por el gateway |
+| [Claude Code con DeepSeek](deepseek.md) | `http://127.0.0.1:8402` | **sin** | env `ANTHROPIC_BASE_URL` | `bvsala gateway --upstream deepseek` | [V] en test: `/v1/messages` → `/anthropic` |
+| [Ollama / vLLM / LM Studio](ollama.md) (locales) | `http://127.0.0.1:8402/v1` | **con** | `base_url` del SDK | `bvsala gateway --upstream ollama|vllm|lmstudio` | [V] en test; sin precio de lista → reenviado, no metido en dólares |
 | [Python y cualquier SDK](../../README.md#python-and-any-other-language-the-local-gateway) (OpenAI · Anthropic) | OpenAI: `http://127.0.0.1:8403/v1` · Anthropic: `http://127.0.0.1:8402` | OpenAI **con**, Anthropic **sin** | `base_url` del SDK | `bvsala gateway --upstream openai` | [V] en test (upstream falso) |
 
 Reglas de la columna «Base URL»: **nunca barra final**, **nunca redirecciones**
@@ -60,9 +62,9 @@ Reglas de la columna «Base URL»: **nunca barra final**, **nunca redirecciones*
 en vez de seguirlo). Y nunca copies el URL de un terminal a otro: cada SDK añade
 su propio tramo de ruta y el error es silencioso (§ «Comprobar que mide»).
 
-Claude Code, Codex, Goose, Qwen Code, opencode, Kilo, Copilot CLI (BYOK) y Aider
-tienen **envoltorio propio** (`bvsala
-claude|codex|goose|qwen|opencode|kilo|copilot|aider`): arrancan un gateway en
+Claude Code, Codex, Goose, Qwen Code, opencode, Kilo, Copilot CLI (BYOK), Aider
+y Gemini CLI tienen **envoltorio propio** (`bvsala
+claude|codex|goose|qwen|opencode|kilo|copilot|aider|gemini`): arrancan un gateway en
 puerto efímero, lanzan el terminal apuntándole y lo apagan al salir. Cero
 configuración persistente: opencode y Kilo reciben la suya por variable
 (`OPENCODE_CONFIG_CONTENT`, `KILO_CONFIG_CONTENT`), fusionada con la tuya. La
@@ -88,24 +90,26 @@ tráfico degradado: no viaja a BiVelio.
 
 ```bash
 npm i -g @bivelio/savings-layer      # trae el binario `bvsala`
-export BIVELIO_SERVICE_KEY=bvk_…     # clave de servicio, desde tu panel. Obligatoria: sin ella el gateway no arranca
-bvsala gateway                        # escucha en http://127.0.0.1:8402
+bvsala gateway                        # escucha en http://127.0.0.1:8402 — sin claves: modo Community
 bvsala gateway --port 8500            # otro puerto si el 8402 está ocupado
+bvsala gateway --upstream deepseek    # Claude Code con DeepSeek; qwen|glm|moonshot|minimax|gemini|ollama|vllm|lmstudio también
+export BIVELIO_SERVICE_KEY=bvk_…      # OPCIONAL: panel + entitlements de org (sin ella: modo Community)
 ```
 
 Al arrancar imprime, entre otras, estas líneas:
 
 ```
-[bvsala gateway] v0.4.x listening on http://127.0.0.1:8402 → https://api.anthropic.com
-[bvsala gateway] license: PRO, active until 2026-10-24 (+14 days grace), collected with your service key and verified on this machine
-[bvsala gateway] metering: ON (service key present)
+[bvsala gateway] v0.6.x listening on http://127.0.0.1:8402 → https://api.anthropic.com
+[bvsala gateway] COMMUNITY MODE (open core): every local saving lever on, zero telemetry - no BiVelio keys set
+[bvsala gateway] metering: OFF (community mode - no BiVelio service key; local reports stay available with x-bvsala-report)
 ```
 
-Si no arranca (sale con código 1), el mensaje dice exactamente qué falta:
+Con `BIVELIO_SERVICE_KEY` la licencia se recoge sola (línea `license: PRO, active
+until …`) y el metering queda ON. Si algo no arranca (sale con código 1), el
+mensaje dice exactamente qué falta:
 
 | Mensaje | Qué pasa | Arreglo |
 |---|---|---|
-| `BIVELIO_SERVICE_KEY is not set` | falta la clave de servicio | créala en el panel (Instalar, paso 2), expórtala y relanza |
 | `BIVELIO_SERVICE_KEY is not recognised` | clave borrada, rotada o copiada a medias | crea otra |
 | `your organization has no active BiVelio license` | no hay suscripción | suscríbete en Cuenta y relanza |
 | `your BiVelio license expired on …` | licencia caducada y sin gracia | renueva en Cuenta |
@@ -151,22 +155,24 @@ como salen hoy:
 
 | `· not metered: …` | Qué pasa | Arreglo |
 |---|---|---|
-| `no BIVELIO_SERVICE_KEY` | un gateway arrancado desde código sin clave de servicio: reenvía, no mide (el CLI `bvsala` ni arranca sin ella) | exporta `BIVELIO_SERVICE_KEY` |
+| `no BIVELIO_SERVICE_KEY` | modo Community: sin clave no hay ingesta a la que medir — el tráfico se reenvía y los informes locales (`/_bvsala`) siguen funcionando | exporta `BIVELIO_SERVICE_KEY` si quieres el panel |
 | `model "…" has no list price in the catalog` | modelo fuera del catálogo de precios, a propósito: un precio presente y equivocado es peor que ninguno (la consola lo avisa una vez por modelo) | nada; se reenvía sin medir |
 | `could not read the model from the request body (content-encoding: …)` | el cuerpo no se pudo leer: JSON ilegible o una compresión que este Node no abre (zstd, el de Codex, necesita Node ≥ 22.15) | actualiza Node |
 | `the request did not ask for usage (stream_options.include_usage)` | Chat Completions en stream sin `include_usage`: el proveedor no manda contador | añade `stream_options={"include_usage": True}` a la llamada, o arranca con `BVSALA_GATEWAY_USAGE_INJECT=1` |
 | `…; usage injection skips compressed request bodies` | la inyección está puesta, pero solo añade la opción a cuerpos sin comprimir | pídelo en la llamada |
 | `…, and the upstream rejects that option` | el upstream rechazó `stream_options` y la inyección quedó apagada para el resto del proceso | en stream no hay arreglo desde el gateway; con `stream: false` sí se mide |
-| `the stream ended without the provider's final usage event` | el stream se cortó antes de su evento final (`message_delta`, `response.completed`/`incomplete`/`failed`, el chunk de uso o `[DONE]`): sin él no hay contador | nada |
+| `the stream ended without the provider's final usage event` | el stream se cortó antes de completarse (`message_delta` y `message_stop` en Anthropic, `response.completed`/`incomplete`/`failed`, el chunk de uso o `[DONE]`): sin contador y cierre terminal no hay medida | nada |
 | `the response ended as response.failed without usage` | la Responses API cerró con `response.failed` sin `usage`. Si lo trae, sí se mide | nada |
 | `the response ended as response.incomplete without usage` | la Responses API cerró con `response.incomplete` sin `usage`. Si lo trae, sí se mide: un `response.incomplete` por `max_output_tokens` o por el filtro de contenido lo factura el proveedor | nada |
 | `the response carried no usage` | respuesta JSON (`stream: false`) sin `usage` | nada |
 | `the response was too large to read its usage` | respuesta JSON de más de 5 MB: el gateway no la guarda entera para leerla | nada |
 | `the response is neither JSON nor an event stream (content-type: …)` | el upstream contestó con otro tipo de contenido en una ruta que sí sabe medir | revisa el upstream |
-| `no usage dialect for this route` | ruta sin contador que el gateway sepa leer (embeddings, imágenes, audio…): solo mide `/v1/messages`, `…/chat/completions` y `…/responses` | nada |
+| `no usage dialect for this route` | ruta sin contador que el gateway sepa leer (embeddings, imágenes, audio…): solo mide `/v1/messages`, `…/chat/completions`, `…/responses` y el protocolo Gemini (`:generateContent` / `:streamGenerateContent`) | nada |
 
-Con `BVSALA_GATEWAY_COALESCE=1` (apagada por defecto), una petición idéntica a
-otra que sigue en vuelo no viaja: recibe la réplica y su línea lleva
+Con `BVSALA_GATEWAY_COALESCE=1` (apagada por defecto), una petición idéntica de
+inferencia de lectura (`messages`, `chat/completions`, `responses` o `embeddings`)
+a otra que sigue en vuelo no viaja: recibe la réplica. Batches, administración y
+rutas desconocidas siempre se ejecutan por separado. La línea lleva
 `· COALESCED (call avoided)`. Detrás va `· by reference: floor $… (cache read
 price, …)` cuando se valora con el contador de la petición que sí viajó —a
 precio de lectura de caché, sin primas y con la salida solo si el cuerpo trae
@@ -180,7 +186,7 @@ razonamiento que declara el proveedor y la regla `reference-v2` los exige.
 |---|---|
 | `no-primary-record` | la petición que viajó no dejó su contador final (ni evento final del stream ni `usage` en el JSON) |
 | `subscription` | tráfico de suscripción (Claude o ChatGPT): no hay factura por token |
-| `unofficial-upstream` | el gateway no habla con `api.anthropic.com` ni `api.openai.com` (un mock, un proxy, Azure, un revendedor): el precio de lista no está en ninguna factura |
+| `unofficial-upstream` | el gateway no habla con el origen oficial de un proveedor (un mock, un proxy, Azure, un revendedor — Ollama/vLLM/LM Studio y OpenRouter incluidos): el precio de lista no está en ninguna factura |
 | `layer-changed-request` | una palanca cambió lo que viajó (modelo, cuerpo, cabeceras; también la rebaja de TTL de la caché): ya no es la petición del cliente byte a byte |
 | `primary-failed` | la petición que viajó cerró con `response.failed` |
 | `client-disconnected` | el cliente de esta petición se fue antes de recibir la réplica entera |
@@ -202,7 +208,7 @@ sistemas. Lo que cambia es cómo se fija la clave en la sesión — el `export`
 estas guías es POSIX; en PowerShell:
 
 ```powershell
-$env:BIVELIO_SERVICE_KEY = "bvk_…"
+$env:BIVELIO_SERVICE_KEY = "bvk_…"  # OPCIONAL: panel + entitlements de org (sin ella: modo Community)
 bvsala claude
 ```
 
@@ -283,8 +289,8 @@ license state. These routes are answered by the gateway and never forwarded;
 the gateway listens on 127.0.0.1 only, they send no CORS headers, they answer
 403 to a `Host` other than 127.0.0.1 or localhost (so a web page cannot reach
 them by rebinding its own name to 127.0.0.1), no route lists reports (you need
-the id), and like every other route they answer 402 when the license does not
-serve. The gateway
+the id), and like every other route they answer 402 when a live license does not
+serve (in COMMUNITY mode there is no license: they answer as usual). The gateway
 keeps the last 1,000 reports for one hour at most, in memory; nothing is
 written to disk and nothing more is sent to BiVelio.
 
@@ -301,7 +307,7 @@ would fail it.
 
 | Lever | Applies to | What changes | What does not |
 |---|---|---|---|
-| Cache TTL (`cache_ttl_tuning`, on by default with PRO) | `/v1/messages` requests where a large part of the prompt is new (session start, compaction); a chained turn travels untouched | every `cache_control` with `ttl: "1h"` becomes `"5m"`, the top-level one included (a 1-hour top-level marker behind 5-minute block markers would be a 400) | a key named `cache_control` inside a tool call's `input` or a tool's `input_schema` is content and stays as it is; so does the advisor's `caching`; headers are untouched |
+| Cache TTL (`cache_ttl_tuning`, armed by default in community and PRO) | `/v1/messages` requests where a large part of the prompt is new (session start, compaction); a chained turn travels untouched | every `cache_control` with `ttl: "1h"` becomes `"5m"`, the top-level one included (a 1-hour top-level marker behind 5-minute block markers would be a 400) | a key named `cache_control` inside a tool call's `input` or a tool's `input_schema` is content and stays as it is; so does the advisor's `caching`; headers are untouched |
 | Per-turn effort (`BVSALA_GATEWAY_EFFORT=low` or `medium`) | `/v1/messages` for `claude-fable-5-1`, `claude-mythos-5-1`, `claude-opus-5-5` and `claude-opus-5`, when the level is below the model's default effort (`high`; `medium` on `claude-opus-5-5`) and the request carries no `output_config` of its own (top level or in a message); a level at or above the default leaves the request untouched | one message appended at the end of `messages`, `{"role":"system","content":[],"output_config":{"effort":…}}`, and `mid-conversation-output-config-2026-07-01` appended after your `anthropic-beta` value | your `anthropic-beta` value is kept verbatim in front; nothing earlier in `messages` moves |
 | Sibling model (`BVSALA_GATEWAY_SIBLING_MODEL=1`) | `/v1/messages` and `/v1/messages/count_tokens` for `claude-fable-5`, except with a forced `tool_choice` or the 1M-context beta | `model` becomes `claude-fable-5-1` | headers are untouched |
 | Context-editing dials (`BVSALA_GATEWAY_DIALES_ELISION=1`; measured as a net loss, off) | `/v1/messages` | your `clear_tool_uses_20250919` edit in `context_management` is replaced by ours | your other edits are kept, `clear_thinking_20251015` first; your `anthropic-beta` value is kept verbatim, with `context-management-2025-06-27` appended if it was not there |
@@ -330,7 +336,7 @@ Each kind is logged once per session (Claude Code's session id; once per gateway
 process for clients that send none) and every case is counted. `bvsala` prints
 the totals when it exits, because the per-request log is silent inside `bvsala
 claude|codex|goose|qwen` (unless `BVSALA_GATEWAY_LOG=1`). None of this is sent to BiVelio: the usage record has
-no field for it (LICENSE §5), so it stays on your machine.
+no field for it (LICENSE-CLOUD.md §5), so it stays on your machine.
 
 **Limits.**
 

package/docs/terminales/aider.md

@@ -9,7 +9,7 @@ variables que mandan son las de litellm [V].
 ## Qué necesitas
 
 - `aider` en el PATH y tu **API key** (`ANTHROPIC_API_KEY` o `OPENAI_API_KEY`).
-- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (ver [README](README.md)).
+- `bvsala` instalado. Open core: sin claves arranca en modo Community; `BIVELIO_SERVICE_KEY` (opcional) añade el panel y los entitlements (ver [README](README.md)).
 
 ## Envoltorio: `bvsala aider [args…]`
 

package/docs/terminales/claude-code.md

@@ -15,12 +15,12 @@ construcción, con test.
   pero ahí no hay factura por token: el gateway lo mide a precio de lista
   equivalente y nunca le acredita ahorro ni comisión (la licencia por asiento
   hace falta igual).
-- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
+- `bvsala` instalado. Open core: sin claves el gateway arranca en modo Community (todo el ahorro local, cero telemetría); `BIVELIO_SERVICE_KEY` añade el panel y los entitlements de la org (ver [README](README.md)).
 
 ## Envoltorio: `bvsala claude` (recomendado)
 
 ```bash
-export BIVELIO_SERVICE_KEY=bvk_…
+export BIVELIO_SERVICE_KEY=bvk_…  # OPCIONAL: panel + entitlements de org (sin ella: modo Community)
 bvsala claude                    # cualquier argumento pasa tal cual: bvsala claude -p "hola"
 ```
 

package/docs/terminales/cline.md

@@ -14,7 +14,7 @@ que se usa.
 
 - Cline instalado en VS Code.
 - Tu **API key** de Anthropic.
-- `bvsala gateway` corriendo en `http://127.0.0.1:8402` (necesita `BIVELIO_SERVICE_KEY` y una licencia BiVelio activa; ver [README](README.md)).
+- `bvsala gateway` corriendo en `http://127.0.0.1:8402` (sin claves: modo Community; `BIVELIO_SERVICE_KEY` opcional; ver [README](README.md)).
 
 ## Pasos en la UI
 

package/docs/terminales/codex.md

@@ -14,12 +14,12 @@ cifras.
   suscripción ChatGPT (se enruta y se mide a precio de lista equivalente, **sin
   comisión**: no hay factura por tokens; la licencia por asiento hace falta
   igual; ver más abajo).
-- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
+- `bvsala` instalado. Open core: sin claves el gateway arranca en modo Community (todo el ahorro local, cero telemetría); `BIVELIO_SERVICE_KEY` añade el panel y los entitlements de la org (ver [README](README.md)).
 
 ## Envoltorio: `bvsala codex [args…]`
 
 ```bash
-export BIVELIO_SERVICE_KEY=bvk_…
+export BIVELIO_SERVICE_KEY=bvk_…  # OPCIONAL: panel + entitlements de org (sin ella: modo Community)
 bvsala codex                       # cualquier argumento pasa tal cual a codex
 ```
 
@@ -107,7 +107,7 @@ del staff, a diferencia de Anthropic, que lo documenta). Postura idéntica a
 Claude Code: cero persistencia de `Authorization` / `ChatGPT-Account-ID`,
 binario sin modificar, y no se promociona como modo de ahorro.
 
-**Comisión 0 por diseño (desde la versión en que el gateway exige licencia):**
+**Comisión 0 por diseño:**
 el gateway clasifica como suscripción el tráfico de `/backend-api/…` o con
 upstream chatgpt.com (y el de Claude Code con `anthropic-beta: oauth-*`) y no le
 acredita ahorro: `baseline == actual`. Laguna que queda: el registro no lleva

package/docs/terminales/copilot.md

@@ -26,7 +26,7 @@ tokens por modelo). Con BYOK, la CLI funciona **sin cuenta de GitHub** [V].
   ```
 
   (Con OpenAI, el tipo por defecto, el base URL es `https://api.openai.com/v1`: ver «El tipo `openai`» abajo.)
-- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (ver [README](README.md)).
+- `bvsala` instalado. Open core: sin claves arranca en modo Community; `BIVELIO_SERVICE_KEY` (opcional) añade el panel y los entitlements (ver [README](README.md)).
 
 ### Envoltorio: `bvsala copilot [args…]`
 

package/docs/terminales/crush.md

@@ -10,7 +10,7 @@ relativa, y eso dicta la forma del URL: **con `/v1`, sin barra final**.
 - `crush` instalado.
 - `ANTHROPIC_API_KEY` exportada (Crush retiró su OAuth de Claude en ene-2026:
   solo API key).
-- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
+- `bvsala` instalado. Open core: sin claves el gateway arranca en modo Community (todo el ahorro local, cero telemetría); `BIVELIO_SERVICE_KEY` añade el panel y los entitlements de la org (ver [README](README.md)).
 
 ## Config de usuario: `~/.config/crush/crushrc`
 

package/docs/terminales/cursor.md

@@ -0,0 +1,32 @@
+# Cursor (BYOK: tu propia clave OpenAI-compatible)
+
+Cursor solo pasa por un gateway local cuando la petición va con **tu** clave de
+proveedor: sus modelos propios viajan por los servidores de Cursor y no alcanzan
+`127.0.0.1` (su panel de uso mide esos).
+
+**Mecanismo [I]:** Cursor → Settings → Models → **OpenAI API Base URL**. Las
+peticiones OpenAI-compatibles con tu clave salen hacia esa URL.
+
+## Receta
+
+1. Arranca el gateway con el upstream que quieras:
+
+   ```bash
+   bvsala gateway --upstream openai --port 8402    # deepseek, qwen, glm, moonshot, ollama… también
+   ```
+
+2. En Cursor: Settings → Models → **OpenAI API Base URL** =
+   `http://127.0.0.1:8402/v1` (**con** `/v1`).
+
+3. Añade un modelo OpenAI-compatible con tu API key, como harías sin el gateway.
+
+## Qué se mide y qué no
+
+- Se mide: lo que Cursor manda con TU clave a esa base URL, a precio de lista
+  para los modelos con fila en el catálogo.
+- No se mide: los modelos propios de Cursor (su dashboard de uso es el medidor
+  ahí) y los streams sin `stream_options.include_usage`.
+
+## Comprobar que mide
+
+El log del gateway tiene que mostrar `POST /v1/chat/completions …` con `$`.

package/docs/terminales/deepseek.md

@@ -0,0 +1,28 @@
+# Claude Code con DeepSeek (endpoint en formato Anthropic)
+
+DeepSeek publica un endpoint compatible con el protocolo Anthropic
+(`https://api.deepseek.com/anthropic`): el gateway reescribe `/v1/messages` hacia
+`/anthropic/v1/messages` automáticamente, así que Claude Code habla con DeepSeek
+sin tocar su configuración **[V] en test** (`test/gateway-gemini.test.ts`).
+
+Por qué merece la pena: las lecturas de caché de DeepSeek cuestan $0,003/1M y la
+entrada off-peak $0,15/1M — el hermano barato más agresivo para tráfico Claude.
+
+## Receta
+
+```bash
+bvsala gateway --upstream deepseek --port 8402
+ANTHROPIC_BASE_URL=http://127.0.0.1:8402 \
+ANTHROPIC_AUTH_TOKEN=<tu API key de DeepSeek> \
+ANTHROPIC_MODEL=deepseek-flash \
+claude
+```
+
+## Notas
+
+- Se mide a precio de lista para `deepseek-flash` y `deepseek-v4-pro` (el
+  catálogo los tarifa a PEAK, el lado conservador: off-peak es la mitad).
+- `deepseek-chat` (el alias clásico) no tiene fila propia: se reenvía y el log
+  dice «not metered». Usa `deepseek-flash`.
+- La calidad del modelo es asunto tuyo: el gateway no enruta por calidad, solo
+  mide lo que le mandas.

package/docs/terminales/droid.md

@@ -9,7 +9,7 @@ lo dice tal cual; no hay validación hecha.
 ## Qué necesitas
 
 - `droid` instalado, en modo BYOK con tu **API key** de Anthropic.
-- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
+- `bvsala` instalado. Open core: sin claves el gateway arranca en modo Community (todo el ahorro local, cero telemetría); `BIVELIO_SERVICE_KEY` añade el panel y los entitlements de la org (ver [README](README.md)).
 
 ## Config de usuario: `~/.factory/settings.json`
 

package/docs/terminales/gemini.md

@@ -0,0 +1,38 @@
+# Gemini CLI
+
+`bvsala gemini` lanza la CLI de Gemini a través del gateway local, sin tocar su
+configuración.
+
+**Mecanismo [V]:** la CLI de Gemini solo habla el protocolo generativelanguage;
+el gateway lo entiende desde la 0.6 (`:generateContent` y
+`:streamGenerateContent`, con SSE `alt=sse` o JSON por líneas) y lee el
+`usageMetadata` de cada respuesta. El `GOOGLE_GEMINI_BASE_URL` de la CLI apunta
+al gateway, y tu `GEMINI_API_KEY` viaja en `x-goog-api-key`, intacta.
+
+## Requisitos
+
+- `bvsala` instalado (`npm i -g @bivelio/savings-layer`). Sin claves arranca en
+  modo Community; `BIVELIO_SERVICE_KEY` (opcional) añade el panel.
+- La CLI de Gemini instalada y tu `GEMINI_API_KEY` exportada.
+
+## Un comando
+
+```bash
+bvsala gemini
+```
+
+A la salida imprime cuántas peticiones midió y cuáles reenvió sin medir, y por
+qué.
+
+## A mano
+
+```bash
+bvsala gateway --upstream gemini --port 8402   # el gateway con el dialecto Gemini
+GOOGLE_GEMINI_BASE_URL=http://127.0.0.1:8402 gemini
+```
+
+## Comprobar que mide
+
+El log del gateway tiene que mostrar `POST /v1beta/models/…:streamGenerateContent`
+con `$` y los tokens. Los modelos con precio de lista en el catálogo se meten a
+precio de lista; uno sin fila se reenvía y la línea lo dice.

package/docs/terminales/goose.md

@@ -9,12 +9,12 @@ forma del URL.
 
 - `goose` en el PATH, con el proveedor Anthropic elegido.
 - `ANTHROPIC_API_KEY` exportada (Goose es solo BYOK).
-- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
+- `bvsala` instalado. Open core: sin claves el gateway arranca en modo Community (todo el ahorro local, cero telemetría); `BIVELIO_SERVICE_KEY` añade el panel y los entitlements de la org (ver [README](README.md)).
 
 ## Envoltorio: `bvsala goose`
 
 ```bash
-export BIVELIO_SERVICE_KEY=bvk_…
+export BIVELIO_SERVICE_KEY=bvk_…  # OPCIONAL: panel + entitlements de org (sin ella: modo Community)
 bvsala goose                       # espejo exacto de `bvsala claude`
 ```
 

package/docs/terminales/kilo.md

@@ -11,7 +11,7 @@ Esto sustituye a la receta anterior (proveedor custom por UI, forma inferida).
 ## Qué necesitas
 
 - Kilo (CLI `kilo`, o la extensión) con el proveedor **`anthropic`** y tu **API key** de Anthropic.
-- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
+- `bvsala` instalado. Open core: sin claves el gateway arranca en modo Community (todo el ahorro local, cero telemetría); `BIVELIO_SERVICE_KEY` añade el panel y los entitlements de la org (ver [README](README.md)).
 
 **Lo que no pasa por aquí:** el proveedor por defecto de Kilo es su propia
 pasarela (Kilo Gateway, modelos alojados por Kilo con su cuenta). Ese tráfico va
@@ -20,7 +20,7 @@ a Kilo, no a un base URL tuyo, y no se mide. Tampoco los demás proveedores.
 ## Envoltorio (CLI): `bvsala kilo [args…]`
 
 ```bash
-export BIVELIO_SERVICE_KEY=bvk_…
+export BIVELIO_SERVICE_KEY=bvk_…  # OPCIONAL: panel + entitlements de org (sin ella: modo Community)
 bvsala kilo
 ```
 

package/docs/terminales/no-soportados.md

@@ -2,33 +2,11 @@
 
 **Fuente:** `docs/investigacion/2026-09-27/agentes-de-codigo.md`. Decir que no es
 parte de la receta: un terminal apuntado al gateway que no se puede medir sería
-pagar una licencia por un proxy vacío.
-
-## Gemini CLI — no se mide todavía
-
-Gemini CLI acepta un base URL propio: `GOOGLE_GEMINI_BASE_URL` (y
-`GOOGLE_VERTEX_BASE_URL` con Vertex), en HTTPS salvo que apunte a `localhost` o
-`127.0.0.1` [V: `docs/reference/configuration.md` de `google-gemini/gemini-cli`,
-2026-09-27]. El problema no es enrutarlo: es que habla la **API de Gemini**
-(`…/models/<modelo>:streamGenerateContent`, contador en `usageMetadata`), y el
-gateway solo sabe leer el contador de Anthropic Messages y de OpenAI Chat
-Completions y Responses. Cada petición se reenviaría con la línea
-`not metered: no usage dialect for this route`, sin coste.
-
-Hasta que el gateway lea ese dialecto, el contador de Gemini CLI es su propio
-`/stats model` (tokens por modelo y cuota) [V]. Qué haría falta para medirlo, y
-por qué no se ha hecho hoy (los precios de contexto largo de los modelos Pro),
-está en el informe.
-
-## Cursor — no se puede
-
-Cursor manda **todas** las peticiones, también las de tu propia clave, a través
-de sus servidores: «all requests are routed through Cursor's servers for final
-prompt building» [V: cursor.com/docs/settings/api-keys, 2026-09-27]. Un gateway
-en `127.0.0.1` es inalcanzable desde ahí, y exponerlo a Internet no es una
-opción (escucha solo en loopback a propósito). Las claves propias, además, solo
-cubren los modelos de chat; Tab sigue con los modelos de Cursor [V]. El contador
-de Cursor es su panel de uso.
+pagar por un proxy vacío.
+
+> Actualización 2026-11 (open core): Gemini CLI **ya se mide**
+> ([gemini.md](gemini.md)) y Cursor **ya tiene receta** para su override de base
+> URL BYOK ([cursor.md](cursor.md)). Quedan aquí los casos que siguen sin medirse.
 
 ## Copilot con modelos de GitHub — no pasa por un base URL
 
@@ -39,3 +17,14 @@ GitHub y no a un base URL tuyo. Con BYOK sí se mide: ver [copilot.md](copilot.m
 
 El proveedor por defecto de Kilo son sus modelos alojados; ese tráfico va a Kilo.
 Con el proveedor `anthropic` y tu clave sí se mide: ver [kilo.md](kilo.md).
+
+## Cursor con sus modelos propios — no pasa por un base URL tuyo
+
+Con modelos de Cursor (sin BYOK) las peticiones van a los servidores de Cursor y
+no alcanzan un gateway en `127.0.0.1`; su panel de uso es el medidor ahí. Con tu
+propia clave OpenAI-compatible sí se mide: ver [cursor.md](cursor.md).
+
+## Modelos locales (Ollama, vLLM, LM Studio) — sin precio de lista
+
+Se reenvían y el log lo dice; no hay precio de lista que meter en dólares. Ver
+[ollama.md](ollama.md).

package/docs/terminales/ollama.md

@@ -0,0 +1,19 @@
+# Ollama, vLLM y LM Studio (modelos locales)
+
+El gateway también se pone delante de un servidor local OpenAI-compatible: útil
+para dar a un agente un tier local gratis mientras el gateway sigue midiendo las
+llamadas de pago.
+
+```bash
+bvsala gateway --upstream ollama --port 8402    # http://localhost:11434
+bvsala gateway --upstream vllm --port 8402      # http://localhost:8000
+bvsala gateway --upstream lmstudio --port 8402  # http://localhost:1234
+```
+
+Luego apunta cualquier SDK OpenAI a `http://127.0.0.1:8402/v1` (**con** `/v1`).
+
+**Honestidad de la medición:** los modelos locales no tienen precio de lista, así
+que este tráfico se reenvía y el log lo dice (`not metered: model "…" has no
+list price in the catalog`). En dólares no se acredita nada; el valor es
+operativo: un solo base URL para todos los modelos, con el metering de los
+providers de pago funcionando al lado.

package/docs/terminales/opencode.md

@@ -9,12 +9,12 @@ defecto: por eso aquí el URL lleva `/v1` [V].
 ## Qué necesitas
 
 - `opencode` instalado, proveedor `anthropic` con tu **API key** de Anthropic.
-- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
+- `bvsala` instalado. Open core: sin claves el gateway arranca en modo Community (todo el ahorro local, cero telemetría); `BIVELIO_SERVICE_KEY` añade el panel y los entitlements de la org (ver [README](README.md)).
 
 ## Envoltorio: `bvsala opencode [args…]`
 
 ```bash
-export BIVELIO_SERVICE_KEY=bvk_…
+export BIVELIO_SERVICE_KEY=bvk_…  # OPCIONAL: panel + entitlements de org (sin ella: modo Community)
 bvsala opencode
 ```
 

package/docs/terminales/qwen-code.md

@@ -10,7 +10,7 @@ catálogo a propósito (más abajo).
 - `qwen` en el PATH.
 - **Una API key de Anthropic** (`ANTHROPIC_API_KEY`), con Qwen Code configurado
   para usar el proveedor Anthropic.
-- `bvsala` instalado, `BIVELIO_SERVICE_KEY` exportada y una licencia BiVelio activa (la recoge el gateway con la clave; ver [README](README.md)).
+- `bvsala` instalado. Open core: sin claves el gateway arranca en modo Community (todo el ahorro local, cero telemetría); `BIVELIO_SERVICE_KEY` añade el panel y los entitlements de la org (ver [README](README.md)).
 
 ## Config de usuario: `~/.qwen/settings.json`
 
@@ -31,7 +31,7 @@ verá nada.
 ## Envoltorio: `bvsala qwen`
 
 ```bash
-export BIVELIO_SERVICE_KEY=bvk_…
+export BIVELIO_SERVICE_KEY=bvk_…  # OPCIONAL: panel + entitlements de org (sin ella: modo Community)
 bvsala qwen
 ```