insika 0.9.0 → 1.0.1

data/docs/OBSERVABILITY.md

@@ -5,7 +5,44 @@ nav_order: 1
 permalink: /observability/
 ---
 
-# Observability — OpenTelemetry (opt-in)
+# Observability — native model diagnostics and OpenTelemetry
+
+## Studio Models
+
+Open the operator-authenticated `/studio/models` page to filter native
+requests by the last 24 hours, 7 days, or 30 days, agent, provider, and model. It shows
+request volume, failures, retries, reported USD cost and unknown-cost coverage,
+p50/p90/p95 latency, separate input/output/cache-read/cache-write/thinking token
+subtotals, and the 20 slowest measured requests linked to their tasks.
+
+Charts show request volume, reported cost, and p50/p90/p95 latency over time,
+plus a ranked cost comparison by model. They share the page filters. The 24-hour
+view uses hourly intervals, 7 days uses six-hour intervals, and 30 days uses
+daily intervals, all in UTC. Each chart has an expandable table of exact values.
+Missing cost or duration leaves a gap; no-call intervals have zero requests.
+The page is a snapshot: apply the filters again to refresh it.
+
+Request latency includes native retries. Retries count usage attempts beyond the
+first within a request, not Insika task executions. Percentiles use completed
+requests with measured durations. Cost and token values sum only reported usage;
+when coverage is incomplete, they are subtotals, and a dash means no value was
+reported. An unknown-cost failed attempt followed by a priced success leaves
+partial cost coverage even when the subtotal is known.
+
+Every turn also leaves one row (agent, model, provider, status and its
+windows), whatever `INSIKA_TURN_TIMING` says. A failed turn keeps its row with
+the stage that failed and a total that runs to the failure, so timeouts stay in
+the p95 and the page shows the turn failure rate by stage; that flag only decides what the
+response exposes. **Turn latency** shows p50/p95 of ttft (the provider's first
+token), total, first balloon (what a channel customer waits), queue (debounce
+and FIFO wait before the turn starts), prep and tools. **Tool health** lists
+every tool call in those turns: calls, ok %, p50/p95 ms. A call is a failure
+when its result carries `error`; tools ms sums calls, so parallel calls count
+more than their wall time.
+
+The page reads content-free summaries stored independently of the capped task
+trace. History starts when the summaries are deployed; earlier requests are not
+backfilled. Task deletion, retention, and tenant purge remove their summaries.
 
 Insika already has an observability spine: the **event stream**. Every turn emits
 structured events (`task_started`, `tool_call`/`tool_result`, `data_tool_call`,
@@ -62,11 +99,22 @@ something that left no task of its own behind:
 | `:knowledge_deleted` | `name`, `agent` | an operator removed a concept from the Studio |
 | `:knowledge_retrieved` | `name`, `agent` | the model called `load_knowledge` — the adoption signal (retrieval calls per conversation), not the `<knowledge>` injection itself |
 | `:knowledge_backfilled` | `agent`, `sessions`, `concepts`, `conflicts`, `dropped{}` | the recovery re-scan (`insika knowledge:backfill`) finished replaying an agent's stored sessions |
+| `:retrieval_reranked` | `provider`, `candidate_count`, `selected_count` | an opt-in memory or knowledge rerank selected candidates; no candidate text |
+| `:provider_warning` | `provider`, `message` | a rerank failed or returned invalid indexes; fallback context remains available |
 
 `delivery_failed` and `breaker_open` are the two the operator config is pointed at
 (`alerts.webhook` on the profile): each only fires when something durable did
 not land. `:ttft` is additive debug, absent unless `INSIKA_TURN_TIMING` is set.
 
+Rerank requests have `operation: "rerank"` in native model diagnostics. Their
+reported cost is tracked separately from chat and included once in the total.
+If any rerank request lacks usage, the rerank and total cost remain unknown.
+Reported native rerank tokens, including reported failed attempts, count once
+against agent token ceilings and calendar budgets, separately from chat usage.
+Unknown token fields stay unknown. Diagnostics carry the task and captured turn.
+Candidate and selected counts measure narrowing, not recall: records excluded
+by the lexical index or recent-note window cannot appear in those counts.
+
 `:channel_delivered` is the one worth alerting on: a turn can be `:task_completed`
 and correct while the customer got nothing, because delivery is a separate,
 retried, out-of-band step. `status: "failed"` means the reply is sitting in the
@@ -80,7 +128,7 @@ The bridge speaks the standard the market already runs on: point any OTLP backen
 at Insika and a real turn shows up as a full trace, next to counters and histograms
 you can chart without touching a span.
 
-**This page is a convention, not an integration.** Insika ships no dashboard, no
+**The OpenTelemetry section is a convention, not an integration.** Insika ships no OTEL dashboard, no
 backend config, no vendor file. It ships a stable set of attribute and instrument
 names, and the recipes below tell you what to chart against them — in whatever you
 already run.
@@ -96,6 +144,7 @@ masked result; `insika tools:report` lists blocked calls separately from errors.
 ## Contents
 
 - [Turning it on](#turning-it-on-opt-in-parity-when-off)
+- [Native model diagnostics](#native-model-diagnostics)
 - [Traces: the span reference](#traces-the-span-reference)
 - [Metrics: the instrument reference](#metrics-the-instrument-reference)
 - [Attribute reference](#attribute-reference)
@@ -123,12 +172,43 @@ stay on; `OTEL_METRIC_EXPORT_INTERVAL` (ms) sets the export period. If the metri
 SDK is not in the bundle at all, the bridge degrades to traces only rather than
 failing to boot.
 
-**Off (the default):** `Insika::Telemetry.setup` returns `nil`, the OTEL gems are
-**never loaded** (lazy `require`, like the LLM client), and nothing is
-instrumented — zero overhead. This is enforced by a test
+**Off (the default):** `Insika::Telemetry.setup` returns `nil` and the OTEL gems are
+**never loaded** (lazy `require`, like the LLM client). No OTEL spans or metrics
+are exported; native model diagnostics remain available in Studio. The lazy
+load is enforced by a test
 (`spec/insika/load_guard_spec.rb`: "require insika does not load
 OpenTelemetry").
 
+A failed export (a 404 from an ingest that wants a header, a wrong key) is
+logged to stderr as `ERROR -- otel: OpenTelemetry error: OTLP exporter received
+http.code=…`. `OTEL_EXPORTER_OTLP_HEADERS` is `key=value[,key=value]` and each
+value is URL-decoded: a `+` in a token becomes a space, so write it as `%2B`
+(and `%` as `%25`).
+
+## Native model diagnostics
+
+The Studio task page shows `llm_request` and `llm_usage` rows from RubyLLM. A
+request is one logical model operation, including RubyLLM's transport retries;
+each attempt has its own usage row. A successful task can therefore show a failed
+attempt followed by a successful attempt under one request. These are not extra
+task executions. Each request has a locally generated `request_id` that links its
+rows; it is not the provider's HTTP request ID. The rows show operation,
+provider, model, outcome, and five token buckets (input, output, cache read,
+cache write, thinking). Only the request has a measured duration. Attempts have
+no measured duration. Cost is RubyLLM's reported attempt cost, or the
+`INSIKA_MODEL_PRICING` estimate when RubyLLM reports none: unknown
+remains an em dash, while a reported zero remains zero. These diagnostic values
+do not add to turn usage, `insika.tokens`, or `insika.cost`.
+
+The diagnostic store retains the latest 200 events per task. Studio marks a
+truncated tail; deleting the task deletes its diagnostics. Insika stores and
+exports only allowlisted scalar fields: event type, timestamp, turn number,
+operation, provider, model, outcome, request ID, duration, exception class,
+token counts, and cost. It excludes prompts, messages, tool arguments, responses,
+URLs, exception messages, and arbitrary RubyLLM payload fields. This restriction
+applies to Insika's diagnostics; an application-supplied RubyLLM instrumenter
+still receives RubyLLM's original payload under the host's own policy.
+
 ## Traces: the span reference
 
 One span per **turn**, with **child spans** per tool, correlated by `task_id`.
@@ -139,16 +219,29 @@ Latency is the span duration, reconstructed from the events' real `at` timestamp
 | `insika.turn` | one per turn, opened on `task_started`, closed on the terminal event | root |
 | `insika.tool` | one per tool call, `tool_call` → `tool_result` (FIFO-correlated) | `insika.turn` |
 | `insika.data_tool` | one per data-tool call — point-in-time (the engine emits a single event) | `insika.turn` |
+| `insika.llm.request` | one per retained native request with measured duration, exported when the turn ends | `insika.turn` |
 
 A turn that ends with `task_failed` also carries the OTEL **error status**, with
-the failure message.
+the exception class (or `Task failed` when the class is unavailable), never the
+exception message. A failed native request uses the same class-only rule.
+
+Request spans carry `insika.llm.request_id`, `insika.model`, `insika.provider`,
+`insika.operation`, `insika.status`, `insika.llm.duration_ms`,
+`insika.llm.attempts`, and `insika.llm.failures`. Each retained attempt adds
+`insika.llm.attempt.N.status` and, when known,
+`insika.llm.attempt.N.input_tokens`, `output_tokens`, `cache_read_tokens`,
+`cache_write_tokens`, `thinking_tokens`, and `cost`. The `N` starts at 1. Unknown
+values are omitted. Request spans wait until the turn ends so usage emitted after
+request completion is included. When the 200-event buffer overflows,
+`insika.llm.truncated=true` appears on the turn and request spans: their attempt
+counts describe only the retained tail.
 
 ## Metrics: the instrument reference
 
 The same events feed instruments, so volume, latency, tokens and cost are chartable
 **without aggregating spans** — which not every backend does, and none does cheaply
-at retention. Metrics are recorded on the *terminal* event, so every point already
-knows its outcome.
+at retention. Turn metrics are recorded on the *terminal* event, when its outcome
+is known. Native attempt counters are recorded as usage arrives.
 
 | Instrument | Type | Unit | Recorded when |
 |------------|------|------|----------------|
@@ -157,11 +250,19 @@ knows its outcome.
 | `insika.tokens` | counter | `{token}` | the turn reported usage |
 | `insika.cost` | counter | `{USD}` | the turn's model is priced (see below) |
 | `insika.tool.blocked` | counter | `{call}` | a `tool_blocked` gate refusal |
+| `insika.confirmation` | counter | `{hold}` | a customer confirmation is requested, confirmed, cancelled or expires (`insika.outcome`) |
 | `insika.tool.calls` | counter | `{call}` | a tool call completes |
 | `insika.tool.duration` | histogram | `s` | a `tool_call`/`tool_result` pair completes |
 | `insika.cache.hit_rate` | histogram | `%` | a turn reported billed prompt tokens (see below) |
 | `insika.tool.loop_intervened` | counter | `{intervention}` | the loop detector delivered its one-shot warning |
 | `insika.context.compacted` | counter | `{compaction}` | an in-session compaction was persisted (RFC-0044) |
+| `insika.llm.attempts` | counter | `{attempt}` | each native usage event, including retries |
+| `insika.llm.failures` | counter | `{attempt}` | each native usage event with failed status |
+
+The native attempt counters count every received attempt, even when the span
+buffer has discarded earlier rows. They use the turn's agent/tenant/command
+labels plus `insika.model`, `insika.provider`, `insika.operation`, and
+`insika.status`; neither task nor request ID becomes a metric label.
 
 `insika.tool.duration` is deliberately **not** recorded for data-tools: those are a
 single point-in-time event, so there is no measured duration to report. A tool left
@@ -201,10 +302,11 @@ metric attribute with per-turn cardinality is how you destroy a metrics backend.
 | `insika.status` | string | `turn` | turn instruments | `ok` / `error` / `cancelled` / `abandoned` |
 | `insika.model` | string | `turn` | all except tool | model id the provider reported |
 | `insika.model_source` | string | `turn` | — | which config layer resolved the model (chat / agent / model / global) |
-| `insika.tokens.input` | int | `turn` | — | input tokens (**includes** the cached ones) |
+| `insika.provider` | string | `turn` | — | provider of the turn's final model selection (the fallback's, when one answered) |
+| `insika.tokens.input` | int | `turn` | — | non-cached input tokens |
 | `insika.tokens.output` | int | `turn` | — | output tokens |
-| `insika.tokens.total` | int | `turn` | — | input + output |
-| `insika.tokens.cached` | int | `turn` | — | cache **reads**, a subset of `tokens.input` |
+| `insika.tokens.total` | int | `turn` | — | non-cached input + output subtotal; cache buckets are separate |
+| `insika.tokens.cached` | int | `turn` | — | cache **reads**, separate from `tokens.input` |
 | `insika.tokens.cache_creation` | int | `turn` | — | cache **writes**, *not* inside `tokens.input` |
 | `insika.token.type` | string | — | `insika.tokens` | `input` / `output` / `cached` / `cache_creation` |
 | `insika.cost.usd` | double | `turn` | — | estimated cost of the turn (span attribute; the metric is the `insika.cost` counter) |
@@ -231,12 +333,27 @@ attributes are there for it.
 
 ## Estimated cost
 
-Insika ships **no prices**. They change weekly, differ per contract and per region,
-and a stale table inside the engine would be worse than no number. You declare the
-rates; Insika multiplies. Unset, no cost is reported anywhere.
+RubyLLM supplies attempt-time usage and cost. Insika aggregates native chat usage
+across tool rounds and retries, including recorded usage before a failure, and
+exports the recorded `cost_usd`. Unknown costs remain unknown, not zero.
+Insika maintains no competing provider price catalog.
 
-Set `INSIKA_MODEL_PRICING` to a JSON object of model id → rates in **USD per
-million tokens**:
+Internal token buckets are disjoint. The `total_tokens` field retains its historical
+non-cached input/output subtotal; budgets and evals add the cache buckets once.
+The Responses HTTP adapter projects cache-inclusive `input_tokens` and `total_tokens`.
+
+RubyLLM prices from its model catalog. Insika keeps that catalog in its store
+and refreshes it every `INSIKA_MODEL_REFRESH_HOURS` (default 24; 0 keeps the
+gem's bundled catalog): one worker downloads it, the others reload it, and a
+restart starts from the last download instead of the catalog shipped with the gem.
+
+`INSIKA_MODEL_PRICING` optionally fills in cost where RubyLLM reports none (a
+model missing from its registry, a negotiated contract) — everywhere: Studio
+Models, task traces, turn usage and telemetry. RubyLLM's cost always wins, so the
+table never goes stale against a priced model. Rates are a JSON object of model
+id to **USD per million tokens**.
+Each request is priced under its own model, so a turn that ran a failed primary,
+a fallback and the router costs each at its own rate:
 
 ```bash
 INSIKA_MODEL_PRICING='{
@@ -249,13 +366,17 @@ INSIKA_MODEL_PRICING='{
   `provider/` prefix — `deepseek/deepseek-v4-flash` and `deepseek-v4-flash` both hit the
   same entry.
 - `input` / `output` are required (one of them is enough for the entry to load).
-- `cached_input`, when given, bills cache **reads** at that rate and subtracts them
-  from the fresh input. Omit it and cached tokens simply stay at the input rate.
+- `cached_input`, when given, bills cache **reads** separately at that rate.
+  Omit it and cache reads use the input rate; they are never subtracted from fresh input.
 - `cache_write`, when given, bills cache **creation** tokens at that rate. Omit it
   and they are billed at the input rate.
-- An **unpriced model reports nothing** — no attribute, no metric point. A missing
-  price is not a zero cost, and a dashboard should show the gap.
-- A malformed table degrades to "no cost". Telemetry config can never stop a boot.
+- A model RubyLLM prices never reads the table. If neither supplies a cost,
+  there is no attribute or metric point. A missing price is not zero.
+- A malformed table disables the override. Telemetry config cannot stop a boot.
+
+Routing (`operation: "routing"`) and summarizing compaction
+(`operation: "compaction"`) requests are recorded like the chat's, so they show
+on Studio Models next to it.
 
 The number is an **estimate for trend and attribution**, not a bill. Reconcile
 against your provider's invoice, never the other way round.
@@ -389,7 +510,7 @@ Set the OTEL envs on the deployment and every worker exports to your collector:
 INSIKA_OTEL=1
 OTEL_EXPORTER_OTLP_ENDPOINT=https://<your-collector>:4318
 OTEL_SERVICE_NAME=insika        # optional; names the service
-INSIKA_MODEL_PRICING='{...}'    # optional; unlocks the cost attribute + counter
+INSIKA_MODEL_PRICING='{...}'    # optional negotiated-rate override for telemetry
 # plus any standard OTEL_EXPORTER_OTLP_HEADERS your backend needs
 ```
 

data/docs/PERFORMANCE.md

@@ -0,0 +1,110 @@
+---
+title: Performance
+parent: Operate
+nav_order: 8
+permalink: /performance/
+---
+
+# Performance
+
+What the engine does to stay cheap per turn, and what was tried and left out. A turn
+mostly waits on the model provider, so the engine's job is to add little CPU, hold
+little memory and never block the other turns in the same process.
+
+To measure your own load, see [Deploy › Measuring performance](DEPLOY.md#measuring-performance--load),
+[Load test](LOADTEST.md) and the [Benchmark](BENCHMARK.md).
+
+## Numbers you can reproduce
+
+Each one comes from a script in this repository, with no API key and no real data.
+
+| What | Number | Run |
+|---|---|---|
+| Engine work per turn, model stubbed | p50 ≈ 0.4 ms, ~1,700–1,900 turns/s per process | `bundle exec ruby scripts/bench.rb` ([Benchmark](BENCHMARK.md)) |
+| SQLite writes, 1 to 8 processes on one file | ~25–30k writes/s in total, zero "database is locked" | `bundle exec ruby scripts/bench_store.rb 1,2,4,8 3000` ([Deploy](DEPLOY.md#1-sqlite-write-ceiling-no-provider--bench_storerb)) |
+| One key lookup, `execute` vs a cached prepared statement | ~2.7 µs vs ~0.9 µs (Ruby 4.0, laptop) | the snippet below |
+
+A turn makes a few hundred store calls at most. Saving ~2 µs on each is well under a
+millisecond per turn, which is why statement caching is in the "left out" table.
+
+```ruby
+require "sqlite3"; require "benchmark"
+db = SQLite3::Database.new(":memory:")
+db.execute("CREATE TABLE kv (scope TEXT, key TEXT, value TEXT, PRIMARY KEY (scope, key))")
+1000.times { |i| db.execute("INSERT INTO kv VALUES (?, ?, ?)", ["s", "k#{i}", "x" * 500]) }
+sql = "SELECT value FROM kv WHERE scope = ? AND key = ?"
+st = db.prepare(sql)
+Benchmark.bm(9) do |b|
+  b.report("execute")  { 200_000.times { |i| db.get_first_value(sql, ["s", "k#{i % 1000}"]) } }
+  b.report("prepared") { 200_000.times { |i| st.reset!; st.bind_params("s", "k#{i % 1000}"); st.step } }
+end
+```
+
+## What the engine does
+
+**No Rails, no ORM.** The server is Falcon with Rack and Roda. The store is a key-value
+table driven by the `sqlite3` gem directly. Nothing loads a framework or builds model
+objects on the hot path.
+
+**One fiber per turn.** Each turn runs as an `Async` task. While it waits on the provider,
+a tool or the store, the same process runs other turns. One worker holds many concurrent
+conversations without threads. See [Architecture](ARCHITECTURE.md).
+
+**Session actors end when idle.** Turns of the same session run in order through a small
+actor. Its loop ends as soon as its queue drains and it leaves the executor's table, so an
+idle session holds no fiber.
+
+**SQLite tuned for many writers.**
+
+- WAL mode with `synchronous = NORMAL`.
+- `busy_handler_timeout=` instead of `busy_timeout=`. The C-level handler sleeps while
+  holding the GVL, so a worker waiting on another process's write lock would freeze every
+  fiber it runs. The Ruby-level handler lets the scheduler keep the other turns going.
+- **Group commit.** Writes that arrive while one is waiting for the lock join the same
+  transaction and share one `COMMIT`. Each caller still returns only after its own write is
+  committed, so durability and per-fiber order do not change. Fewer commits means less
+  fighting over the file's single write lock when several workers share it.
+- Prefix and recent-items reads are one range query, not one query per key.
+- `INSIKA_SLOW_STORE_MS` logs every slow store call, and every slow group-commit batch with
+  its time split into wait, statements and commit. A long wait with a short commit means
+  another process holds the lock. A long commit means the batch itself is heavy.
+
+**Memory goes back to the OS.**
+
+- `MALLOC_ARENA_MAX=2` caps glibc's malloc arenas. Under a multi-worker load, the peak
+  stays lower with the same latency.
+- `MALLOC_MMAP_THRESHOLD_=131072` pins the mmap threshold. Large buffers stay mmapped and
+  return to the OS when freed instead of fragmenting the arenas.
+- `Insika::MemoryTrim` runs on a quiet worker: no turn in flight and enough allocated since
+  the last pass. It runs a full GC and then `malloc_trim(0)`. Without it, a worker stays at
+  its peak after a burst, because a GC alone gives nothing back to the OS. It needs the
+  `fiddle` gem and does nothing where `malloc_trim` does not exist (macOS, musl).
+- Long-lived fibers return `nil` from their blocks, so a finished task's result is not kept
+  alive by a stale reference.
+
+**YJIT on.** The reference image sets `RUBY_YJIT_ENABLE=1`. It lowers CPU per turn
+(serialization, streaming, context building) for a small memory cost per worker.
+
+**Workers are a contract input, not a tuning knob.** More worker processes means more
+memory and more writers on one SQLite file. Start with one. Add workers, and the
+[Router](ROUTER.md) in front of them, only when one process's CPU is the limit. See
+[Deploy › The process model](DEPLOY.md#the-process-model).
+
+## Tried and left out
+
+Each of these was measured on a production-like load and did not pay off. Measure again
+before you reopen one.
+
+| Idea | Why it is out |
+|---|---|
+| jemalloc or mimalloc instead of glibc | `MALLOC_ARENA_MAX` plus `MemoryTrim` already got most of the gain. Both left a higher memory floor after repeated loads, and `malloc_trim` does nothing under them. |
+| Preforking workers from a parent with the code loaded (copy-on-write) | Saves memory only right after boot. After a load, each worker's floor is its own heap, not duplicated code. |
+| `GC.compact` during the trim | Fewer heap pages, same RSS. |
+| Async HTTP adapter for the provider | Slower end to end than plain `Net::HTTP`, and it breaks Streamable-HTTP MCP outside an Async reactor. |
+| Write-behind for traces, compressing large stored values | No measurable gain over group commit. Old compressed rows are still read. |
+| Postgres store for speed on one box | Every store call becomes a network round trip, and a turn makes many store calls. Use it to share the store across nodes, not for speed. See [Deploy › Postgres store](DEPLOY.md#postgres-store-optional). |
+| Caching prepared SQLite statements | Saves microseconds per call. Too small next to a turn that waits on the provider. |
+
+Once group commit is in place, writer contention on one SQLite file under sustained heavy
+load is a matter of architecture: fewer writer processes, a faster volume, or a shared
+store. More application-level tuning does not move it.

data/docs/PLUGINS.md

@@ -73,7 +73,7 @@ require "ruby_llm"
 module WeatherPlugin
   class GetWeather < RubyLLM::Tool
     description "Looks up the current weather for a city"
-    param :city, desc: "City name"
+    parameter :city, description: "City name"
 
     def execute(city:) = { city: city, temp_c: 24, condition: "sunny" }
   end
@@ -169,9 +169,9 @@ require "insika/plugin"
 Insika::Plugin.announce(File.expand_path("../..", __dir__))
 ```
 
-Discovery details worth knowing: the manifest may be named `insika.plugin.yml`
-(preferred) or `plugin.yml` (deprecated — it warns); one manifest per directory,
-with `insika.plugin.yml` winning if both exist; and if two roots ship the same
+Discovery details worth knowing: the manifest is named `insika.plugin.yml` (a leftover
+`plugin.yml` from before 1.0 is not loaded and warns to rename it); one manifest per
+directory; and if two roots ship the same
 `id`, the **first root wins** and the second is skipped.
 
 ### Secrets

data/docs/POLICY.md

@@ -39,6 +39,11 @@ ID is blocked without asking the operator. See
 [Tools](TOOLS.md#provenance-checking-ids-before-a-write) and
 [Security](SECURITY.md#human-approval).
 
+Checkpoints preserve tools enabled by `tool_search`; resuming restores only those
+still allowed by the current policy. If a tool halts the turn, unanswered sibling
+calls receive a non-execution result instead of waiting for approval or executing.
+Their outstanding operator approvals are rejected with `resolved_by: engine:halted`.
+
 ## Layer 3: Guardrails (content safety)
 
 `guardrails` configures input/output content safety per agent — **opt-in**, so an
@@ -95,8 +100,8 @@ budget daily: 100_000, monthly: 2_000_000, soft: false   # or soft: true
 
 ### Reliability — retries, fallback, circuit breaker
 
-The provider interaction is a single attempt by default (RubyLLM's own 2
-transport retries aside). For a store that cannot have a dead model take the
+Without a reliability policy, transport retries use the provider context's
+configuration. For a store that cannot have a dead model take the
 chat down, the reliability policy is DATA on the profile:
 
 ```ruby
@@ -105,11 +110,12 @@ reliability retries: 2, backoff: "exponential",
             circuit_breaker: { after: 10, within: 60, cooldown: 300 }
 ```
 
-- **Retries** — transient failures (`:retryable` / `:rate_limited_*` per the
-  error classification) retry with exponential backoff, up to `retries`.
-  A `:fatal` (auth, billing, bad request) is NEVER retried or rotated. Each
-  attempt runs on a fresh chat — the customer-visible answer comes only from
-  the attempt that returns.
+- **Retries** — RubyLLM owns transport retries for native chats, up to `retries`
+  per request, using its transient-error classification and backoff. Once stream
+  data has arrived, the same request is not retried. `backoff: "exponential"`
+  doubles the native interval; `"constant"` keeps it fixed. Interval and jitter
+  come from the provider context. Insika does not add another retry loop.
+  Fatal authentication/billing/request errors do not trigger model rotation.
 - **Fallback** — after a node's retries, the turn ROTATES to the next model in
   the chain: the profile's `fallback` refs first, then the platform
   `fallback_models`. The turn's usage is attributed to the model that actually
@@ -118,12 +124,15 @@ reliability retries: 2, backoff: "exponential",
   `within` seconds open the circuit; while open, the turn fail-fasts with the
   typed `circuit_open` + `retry_after` (remaining cooldown) and the provider is
   never touched. After `cooldown` a half-open trial closes the circuit on
-  success or reopens it on failure.
-- **`timeout`** — per-attempt ceiling (default 30s), counted as a retryable
-  failure.
-
-Absent `reliability` = the plain single attempt, byte-for-byte today's
-behavior.
+  success or reopens it on failure. A native retry sequence that ultimately
+  fails counts once, not once per internal HTTP attempt. `provider_failure`
+  reports that exhausted sequence; native usage records retain individual attempts.
+- **`timeout`** — the native request timeout and the overall ceiling for one
+  model's execution (default 30s), including its retries. Exhaustion can rotate
+  to the next allowed model but never adds another same-model retry.
+
+Absent `reliability` leaves the provider context unchanged and does not enable
+Insika's model rotation or circuit breaker.
 
 ### Intent routing — classify before you answer
 

data/docs/RELEASING.md

@@ -14,6 +14,11 @@ is invisible to it. Do not publish on rspec alone.
 
 ## Before anything
 
+RubyLLM comes from RubyGems (`~> 2.1` in the gemspec); the development Gemfile must
+not Git-pin it, or the published gem resolves a different RubyLLM than the suite ran.
+The measured performance tradeoff was explicitly accepted for the RubyLLM 2 migration,
+not for future regressions; see [migration results](RUBYLLM_2_MIGRATION.md).
+
 1. The suite is green: `bundle exec rspec`.
 2. `lib/insika/version.rb` carries the version being published.
 3. Every new `lib/` file is **tracked in git**. The gemspec's `files` come from

data/docs/ROUTER.md

@@ -106,6 +106,13 @@ INSIKA_ROUTER_BACKENDS=http://127.0.0.1:9292,http://127.0.0.1:9293,http://127.0.
   bundle exec insika-router
 ```
 
+The image does this for you: set `INSIKA_WORKERS=N` (and keep
+`WEB_CONCURRENCY=1`) and `deploy/entrypoint.sh` runs `deploy/workers.sh`, which
+starts the N workers on ports from `INSIKA_WORKER_BASE_PORT` (default 9300),
+waits until each accepts connections, then binds the router on `$PORT` with a
+backend timeout of `INSIKA_ROUTER_BACKEND_TIMEOUT` (default 1300s there, so a
+long turn is never cut). Unset or `1` boots exactly as before.
+
 `insika doctor` treats `WEB_CONCURRENCY>1` as `ok` (not `error`/`warn`) once
 it sees `INSIKA_ROUTER_BACKENDS` or `INSIKA_ROUTER_BACKENDS_DNS` set — it
 cannot verify a router process is actually running at those addresses, only