insika 0.8.0 → 1.0.1

data/docs/CHANNELS.md

@@ -149,16 +149,24 @@ Content-Type: application/json
 { "agent": "support", "session_id": "web:8f3c…", "message": "cadê meu pedido?" }
 ```
 
-The reply is SSE on that same connection — four frame types, and an unknown one is
+The reply is SSE on that same connection — five frame types, and an unknown one is
 safe to ignore:
 
 ```
-event: delta     data: {"delta":"Seu pedido "}     the answer, token by token
+event: delta     data: {"delta":"Seu pedido chegou."}  the published answer
 event: working   data: {"name":"order_status"}     a tool is running
+event: ui        data: {"component":"product_cards","title":"Chocolate","items":[{"id":"SKU-1","url":"https://shop.example/1","caption":"Dark chocolate"}]}
+                                                   a presentation tool picked cards to show
 event: done      data: {}                          the turn ended
 event: error     data: {"message":"…"}             it ended badly
 ```
 
+The shipped widget renders `ui` as a plain list of caption + link under the
+conversation (only an `http(s)` url becomes a link; any other scheme renders as
+text); a host page that wants real cards restyles or replaces that — the
+protocol is the frame. An empty selection sends `items: []`. Unlike `/v1/responses`,
+the web frame omits `count` and `dropped`. See [presentation tools](TOOLS.md#presentation-tools-the-model-picks-ids-the-engine-shows-the-cards).
+
 **The engine issues the session id and the client never proposes one.** `POST
 /messages` with an id nobody minted is a `404`, never a new conversation: on an
 anonymous endpoint, create-on-write means anyone who guesses an id can read someone
@@ -315,6 +323,15 @@ stays internal unless the agent opts in. That contract is
 [the edge contract](ARCHITECTURE.md#what-crosses-the-edge), and it is why you can
 forward `content` straight to the customer.
 
+The last balloon may also carry `attachments`: objects with `type`, `url`, `caption`
+and an optional `id`,
+the cards an evidence tool returned (see [Evidence](TOOLS.md#evidence-the-lean-envelope-and-grounding)).
+When the turn called a **presentation tool**, the list is exactly the cards the model
+selected, in call order, each also carrying the `component` and `title` of that call;
+otherwise it is every card the turn's evidence tools returned. An empty presentation
+selection suppresses that automatic fallback. Ignore the key if the consumer only
+supports text.
+
 ### Delivery policy
 
 A relay declares **how the outbox flushes** — a property of the surface

data/docs/CONTEXT.md

@@ -23,6 +23,7 @@ into a deterministic prompt:
 | Provider | Block | Priority | Layer | Notes |
 |----------|-------|:--------:|-------|-------|
 | **Identity** | system | **100 — pinned** | identity | The agent's prompt files (global system files first). Never cut. |
+| **Fence notice** | system | **99 — pinned** | identity | Fixed instruction to treat contextual material as data; only with `fencing` on. |
 | **Skills** | `<available_skills>` | 80 | identity | Level-1 skill list, minus whatever is already eager — see [Skills](SKILLS.md). |
 | **Tool search** | `<available_tools>` | 70 | identity | Level-1 list of deferred tools — see [Tools](TOOLS.md). |
 | **Skill trigger** | `<active_skill>` | 85 | volatile | Level-2 bodies: the agent's `skills_eager` set, plus the ones whose `triggers:` match the message — see [Skills](SKILLS.md). |
@@ -86,6 +87,28 @@ Compaction does not replace the budget: eviction stays as the hard backstop
 for a single oversized turn. Tune `context_budget` and keep the identity lean
 regardless.
 
+#### Native Responses compaction
+
+Set `compaction.mode` to `"native"` alongside `enabled: true` to use RubyLLM's
+manual compaction endpoint on supported OpenAI, Azure and xAI Responses chats.
+The default is `"summary"`, described above. Native mode uses the turn's resolved
+model and credential context; `compaction.model`, `prompt` and `utility_model`
+do not apply. Unsupported providers remain uncompacted; there is no second
+summary request or automatic switch to another provider.
+
+After the turn commits, a fresh chat compacts the stored, filtered prefix.
+The original messages remain stored. Opaque state is separate from the spoken
+transcript and is replayed only with the same provider, model and protocol.
+Fallbacks and protocol changes restore the original prefix. Checkpoints retain
+both alternatives. A native marker is also skipped if another context provider
+has already supplied history, because Responses would replace that history.
+
+The budget conservatively counts the original prefix as well as the native state,
+and can evict this entire unit. This version reduces provider input when that unit
+fits; it does not increase local context-budget capacity. Each compaction rebuilds
+the whole stored prefix rather than chaining opaque state. Native usage is reported
+on `context_compacted`; the opaque payload is not included in that event.
+
 One cheap half **is** wired, opt-in per agent: `tool_output_compression` (DSL
 `tool_output_compression`, or `"tool_output_compression": true` in the pack).
 When on, byte-identical repeated **tool results** in the replayed history
@@ -101,19 +124,60 @@ budget first.
 > and the budget verdict (`used / cap`, evicted sources). Counts only, never
 > fragment content.
 
+### Repairing stored assistant context
+
+An operator may attach a string `context_content` to a stored plain assistant
+message. Session replay uses that text while preserving the original `content`
+for display and audit. User messages, tool results, assistant tool calls, explicit
+history and checkpoint replay ignore this field. Existing compaction summaries
+are not rewritten. This is a targeted data repair, not an automatic tool-markup
+parser; text is never converted into tool execution.
+
 ## Memory
 
 With `memory` enabled, an agent gains a built-in `remember` tool for durable
 facts, and those facts (plus recent notes) are injected back into the prompt on
 later turns — **including turns in a different session**. Memory is scoped per
-agent, per `(tenant, customer)` when the message carries a `customer`, and per
-session otherwise — a session's own memory lives in a marked `memory:chat:<session id>`
-cell, never a bare one, so the Customers drill cannot read a conversation as a
-customer. This is distinct from *session history*, which is the transcript of one
+`(tenant, customer)` when the message carries a `customer`. Without a customer,
+it uses the tenant's cell; without either, it uses the session's marked
+`memory:chat:<session id>` cell. A fresh session therefore does not isolate
+memory when it still carries the same tenant. This is distinct from *session history*, which is the transcript of one
 conversation; memory is the small set of facts that should outlive any single
 conversation. Facts and notes are editable from the Studio agent page. See
 [`examples/memory/`](https://github.com/guizaols/insika/tree/main/examples/memory/) for a runnable cross-session example.
 
+In Studio, open **Agents → select an agent → Configuration → Memory & knowledge**.
+Memory, knowledge learning and knowledge retrieval have separate switches. Each
+source has its own optional rerank provider, model, candidate limit and timeout;
+reranking is off by default. Disabling rerank keeps memory and knowledge working
+with their usual retrieval and clears only that source's rerank configuration.
+The memory selection count applies only while memory reranking is on. The knowledge
+selection count also applies without reranking. Provider credentials are configured
+separately, never in this form. Changes apply to this agent's future turns.
+
+To select a smaller memory block for each message, keep `"memory": true` and add
+`"memory_retrieval": {"top_k": 3, "rerank": {"provider": "cohere", "model": "rerank-v3.5", "candidate_limit": 20, "timeout_seconds": 2}}`
+to the agent profile or pack. The engine first reads only the current memory cell,
+ranks active facts and considers the newest `candidate_limit` notes by word overlap and recency,
+then sends at most `candidate_limit` redacted candidates to the configured reranker.
+An empty message or reranker failure keeps the usual full facts and ten recent notes.
+Older notes outside that read window remain available in the store and Studio, but
+cannot be selected for the turn.
+
+Knowledge can use the same opt-in reranker: set `knowledge.retrieve: true`,
+`knowledge.top_k: 3`, and `knowledge.rerank` to the `provider`, `model`,
+`candidate_limit`, and `timeout_seconds` object above. The Scan index first
+finds matching concepts in the agent and tenant scope. The reranker can reorder
+only those candidates; a paraphrase with no matching terms still finds nothing.
+Knowledge sends the candidate name, description, and body; memory sends the
+fact key/value or note text. The built-in PII and secret detector redacts
+recognized patterns before transmission, but it cannot recognize every secret.
+Use a provider and credentials appropriate for this external text transfer.
+Reranker failure keeps lexical knowledge matches or the usual memory block.
+The reranker adds a provider call and may add cost; missing provider usage is
+reported as unknown, not zero. Keep reranking off until an agent's own live
+evaluation shows better answers within its latency and cost budget.
+
 Facts carry **provenance metadata**: every fact record stores `origin`
 (who wrote it — `"engine"`, `"operator"`, `"legacy"` or `"distilled"`),
 `created_at` / `updated_at` timestamps, and an optional `expires_at` (ISO8601) —
@@ -174,7 +238,7 @@ Attention is strongest at the end of the context: a goal stated only at the top
 is the first thing a 30-call turn forgets. So the recitation was **moved** there,
 not copied — the head never repeats it, and the turn pays for it once. It rides
 as a `user` message, like every other engine append inside a turn, so the system
-prefix stays byte-stable and the cache breakpoint at its end keeps hitting.
+identity prefix stays byte-stable.
 
 The `still missing` list is the point: the *model* sees which declared fields are
 still unanswered, so it stops re-asking for something already given. Stored keys
@@ -194,17 +258,21 @@ turns and resumes — a resumed conversation re-opens with the briefing intact.
 
 ## The provider prefix cache
 
-Two distinct caching mechanisms — don't conflate them:
+A stable prefix makes provider caching possible; eligibility, expiry and reported
+savings still depend on the provider.
 
-- **Automatic server-side prefix cache.** Some providers prefix-cache a stable
-  system prefix automatically, at no cost to configure. This works **only because**
-  the engine renders the system in two layers (below) and the volatile half sits
-  **under** the identity boundary, keeping the cacheable prefix byte-stable.
-  Anything that injects volatile content high in the system block breaks the cache.
-- **Manual cache breakpoints (opt-in).** With `prompt_caching` on **and** a
-  provider that supports explicit cache control, the builder sets one cache
-  breakpoint at the end of the system block. Only enable this for a byte-stable
-  system — a volatile system turns every turn into a paid cache *write*.
+- **Automatic prefix caching** needs no Insika flag. The identity-first render
+  order keeps changing memory and request data below the stable prefix.
+- **Explicit cache breakpoints** are opt-in via `"prompt_caching": true` on
+  the agent profile and applied only when the resolved provider is `anthropic`. With both system layers present,
+  Insika sends two text blocks: identity with `cache_control`, then volatile text
+  without it. With no volatile text there is one block; with no identity there is
+  no breakpoint. Other providers receive a plain system string.
+
+Custom context builders and hooks must keep `system_identity`, `system_volatile`
+and their joined `system` consistent. Without a split, or after a hook replaces
+only `system`, the chat builder falls back to treating the whole system as identity.
+That fallback cannot protect a volatile suffix from cache invalidation.
 
 Cache accounting surfaces as `cached_tokens` (reads) and `cache_creation_tokens`
 (writes), visible in telemetry and the Studio tokens chip.
@@ -215,13 +283,14 @@ The system block is partitioned into two cache layers:
 
 - **Identity** — bytes that change only on deploy/config edit: the persona
   prompt (`Prompt`), the level-1 skill list (`Skill`) and the deferred-tool
-  catalog (`ToolSearch`). This is the cacheable prefix.
+  catalog (`ToolSearch`), the fixed tool-discipline instructions and, when enabled,
+  the fencing notice. This is the cacheable prefix.
 - **Volatile** — bytes that may change per turn: memory, session history,
   triggered skill bodies, the `<request_context>`. Everything else.
 
 The layer is a **provider-class contract**, not profile data: `ContextProvider`
 declares `def layer = :volatile` (conservative — nothing gets pinned by
-accident) and the three identity builtins override to `:identity`. A pack does
+accident) and the identity providers override to `:identity`. A pack does
 not set it — a pack reorganizes *which content goes into the Prompt provider vs
 the volatile providers*. The Builder stamps the layer on every fragment at
 production, and the render order is **identity first, volatile after** — a
@@ -236,13 +305,14 @@ output must be byte-stable across turns).
 
 ### The observable cache: fingerprints and the invalidation reason
 
-Each turn, the Executor hashes the rendered prefix into a PII-free fingerprint
-chain — one SHA-256 per system category in render order, one for the tool
-schemas, one cumulative `prefix` — and compares it against the previous turn's
-entry. The **invalidation reason** is the first category whose bytes changed (or
-vanished); a turn whose prefix held reports nothing. History is deliberately
-excluded: a new user message is a divergence every turn, which would be noise,
-not a reason.
+Each turn, the Executor hashes the rendered identity and tool schemas into
+SHA-256 fingerprints and a cumulative `prefix`. The invalidation reason names
+the first changed part of that stable prefix. Volatile system categories have
+separate diagnostic digests: changes to memory, knowledge or request context do
+not report an identity-prefix invalidation. History is excluded.
+
+These fingerprints explain local prompt changes; they do not prove a provider
+cache hit. Use the provider's token accounting for that.
 
 The Studio surfaces it in two places: the **session Context card** shows the
 turn's cache-hit percentage and the `broke: <category>` line (plus the
@@ -251,9 +321,8 @@ cache tab with the per-agent hit series over time. The per-agent series lives
 in its own capped store, because a session does not stamp its author — the
 per-session trace cannot answer "cache-hit over time for *this* agent".
 
-With the prefix stable by construction, the existing `prompt_caching` breakpoint
-sits on bytes that stay put — the first (write) turn of a deployment pays the
-cache write once, every subsequent turn reads.
+A stable identity can be reused while the provider cache remains eligible and valid.
+A changed tool schema still invalidates the local prefix fingerprint.
 
 ## The volume
 

data/docs/CROSS-HARNESS-BENCH.md

@@ -0,0 +1,157 @@
+---
+title: Cross-harness bench
+parent: Operate
+nav_order: 7
+permalink: /cross-harness-bench/
+---
+
+# Cross-harness bench — the same store, six harnesses
+
+Six agent harnesses answer the same twelve customer conversations against the same
+MCP store, on the same model at the same reasoning setting, graded on the store's own
+state. It answers a question the engine benchmark deliberately does not touch: not
+"what does the engine cost per turn" but "does a shop staffed by this agent behave".
+
+This is a **different suite with a different contract** from
+[Benchmark](BENCHMARK.md), which measures engine overhead with no provider, no key and
+no competitor. This one needs a provider key by design — a commerce conversation
+cannot be stubbed — and it names other harnesses. Read the publication rule at the
+bottom before quoting anything from it.
+
+## Running it
+
+```bash
+cd evals/bench
+cp .env.example .env      # OPENROUTER_API_KEY, BENCH_MODEL
+docker compose build      # six images, every version pinned
+bash cut3.sh              # ~4-5h, ~$6, resumable
+```
+
+`RUNBOOK.md` in that directory is the operator's copy: the traps already paid for, the
+resumability contract, and what to do after the run. Every entrant is a pinned Docker
+image driven through the same one-JSON-in, one-JSON-out adapter; the store is reset
+between every cell; three rounds is the floor, because a single run is not a
+measurement.
+
+## Two scorecards, and why
+
+**A is parity** — same tools, same model, same prompt, none of anyone's own product
+layer, ours included. **B is out of the box** — each harness as it ships. The distance
+between a harness's two rows is what its product adds over the bare harness.
+
+That distance is the number this bench was built to produce. In cut 3 it was zero for
+us: scorecard B did not show our commerce layer paying for itself, and it was published
+as a null result. In cut 4, with the one irreversible write held for the customer's
+word, it is one cell — and that cell is described below, because one cell is a
+mechanism to read, not a number to quote.
+
+## What cut 3 found, for us
+
+Twelve tasks, three rounds, `deepseek/deepseek-v4-flash` at reasoning `medium`, run
+2026-09-09.
+
+| | Scorecard A | Scorecard B |
+| --- | --- | --- |
+| Passed | 34/36 (94%) | 34/36 (94%) |
+| Tokens per success | 2170 | 2263 |
+| Wall clock p50 | 10.0s | 11.8s |
+
+Two findings hold regardless of where the other rows land:
+
+**Cost is where the spread is.** Accuracy across the field sits inside eleven points;
+tokens per success spans an order of magnitude. Ours is the cheapest row on both
+cards, at comparable accuracy. When five harnesses answer equally well, what separates
+them is what they spend answering.
+
+**Take the rules out of the prompt and the field separates.** The shared `AGENTS.md`
+carries the rules the three hardest tasks test, which means a guarded cut partly
+measures the prompt. Re-run with those rules removed, our rows hold at 9/9 on both
+scorecards while the field spreads from 44% to 100%. That is the engine holding a rule
+the prompt no longer states — the closest thing to a claim in this bench, and it is
+about the engine, not about scorecard B.
+
+## What cut 4 found, for us
+
+Same model, same setting, run 2026-09-11, with our scorecard-B entry declaring
+`customer_confirm "create_order"` — the close is held until the customer's next
+message confirms it — and task 07 given the third turn that makes that answerable.
+
+| | Scorecard A | Scorecard B |
+| --- | --- | --- |
+| Passed | 35/36 (97%) | 36/36 (100%) |
+| Tokens per success | 2349 | 2890 |
+| Wall clock p50 | 11.6s | 8.7s |
+
+The one A cell we lose is task 09: *"adiciona logo por favor"* over two units already
+in the cart, and the parity entry closed the order. The B entry, same engine, wrote no
+order in any round of that task and closed task 07 on the confirming turn every time.
+That pair of rows is the distance between A and B made of exactly one thing, and it is
+the thing [Agents](AGENTS.md#do-not-offer-the-irreversible-action) describes: an
+action the reply may offer freely because the engine will not run it in the same turn.
+Three rounds is the floor, not a proof; the mechanism is in `docs/TOOLS.md`, the cells
+in `evals/bench/cuts/2026-09-11/`.
+
+Claude Code did not run this cut — the provider's Anthropic-shaped endpoint returned
+nothing visible to it, with the same image that scored 94% two days earlier. Its cells
+are kept outside the scorecard; a row that cannot run is not a row that ran badly.
+
+## Reasoning is a deployment variable, not an axis
+
+Every entrant is pinned to `medium` because that is what production runs. Crossing
+reasoning against the table is eight combinations and roughly 1500 cells, so it gets
+its own arm instead: ours against itself, both scorecards, at `medium` and at `off`.
+
+Better on one card, worse on the other, with the same three tasks failing at both
+settings. A focused probe — the three tasks we lose, ten rounds each — came back 24/30
+at medium and 27/30 at off, the three tasks contradicting each other. **Reasoning does
+not decide these cases.** Choose it on cost and latency.
+
+## Reading a cut
+
+`scorecard.rb` says who scored what. `viewer.rb` says what was actually said, which is
+the question every finding here has turned on:
+
+```bash
+evals/bench/viewer.rb --runs cuts/2026-09-09
+open evals/bench/bench.html
+```
+
+One self-contained HTML file: a harness-by-task matrix, and behind each square the
+verdict, the checks that failed with their detail, and the whole conversation — the
+customer's line, the reply verbatim, the tool calls, the timing. Every cell is also a
+JSON file under `evals/bench/cuts/<date>/`, so any table here can be recomputed or
+contested.
+
+## Publication rule
+
+**Everything here is published with its evidence. The comparison table is not a
+ranking we will quote until someone outside this repo has reviewed the configs.**
+
+Every entrant's configuration in this repo was written by us, and cut 3 found two
+failures in our own wiring before anyone else did:
+
+- OpenClaw's config carried a thinking level under `reasoningDefault`, which is a
+  visibility setting taking only `on|off|stream`. OpenClaw rejected the whole config
+  and ran no turn; the adapter read an empty answer off the error object and scored it
+  as a harness that answered nothing. Seventy-two cells published a broken row as 33%.
+  Fixed, the same harness scores 97% on both cards.
+- Fifteen Hermes cells resumed from an earlier session had run against a store image
+  that was never rebuilt after its code changed.
+
+Both were caught by someone reading transcripts, not by the bench. So the tables ship
+with every cell behind them — anyone can reproduce a row or show it is wrong — but
+until each entrant's configuration has been reviewed by someone who does not maintain
+this repo, **we do not cite another harness's row as a ranking** in comparative or
+marketing material. Our own rows carry no such problem: we can read our own config.
+
+Publishing the numbers and declining to market them is the point, not a hedge. A
+ranking whose losing rows we wired ourselves is worth less than a bench anyone can
+clone, rewire and re-run — and the two failures above are the argument for that, not
+against it. Fix an entrant's config, re-run one harness, send back the cut.
+
+## See also
+
+- [Benchmark](BENCHMARK.md) — engine overhead: neutral, keyless, reproducible.
+- [Evals](EVALS.md) — the grading corpus and the runner this bench drives.
+- [Agents](AGENTS.md#do-not-offer-the-irreversible-action) — what the bench taught us
+  about writing a store agent's prompt.

data/docs/DEPLOY.md

@@ -117,10 +117,11 @@ this section is the single source of truth for what changing it means.
 | `INSIKA_TICK_STALE_AFTER` | `900` | seconds a `:queued`/`:running` task must sit untouched before the tick sweeps it. Must exceed the largest `turn_timeout` of the deployment |
 | `INSIKA_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN` | Bearer for `/v1/responses` and `/v1/agents` (the API contract) |
 | `ADMIN_TOKEN` | `local-demo` | login token for `/studio` (**change in production**) |
+| `INSIKA_ENV` | `RACK_ENV`, else `local` | environment name on the Studio banner; `production`/`prod` hides the banner |
 | `DEEPSEEK_API_KEY` | — | provider key. **Without it the engine still boots** (`/up` green), but turns fail until it is configured (env or Studio → LLM providers) — cloud resilience |
 | `DEEPSEEK_MODEL` | `deepseek-v4-flash` | model |
 | `CONSUMER_INTERNAL_URL` | — | base URL for data-tools calling back a consumer's internal API (see below) |
-| `INSIKA_EGRESS_HOSTS` | — | outbound host allowlist (SSRF guard) |
+| `INSIKA_EGRESS_HOSTS` | — | outbound host allowlist for data tools (SSRF guard). An MCP server is pinned by it only when its host resolves to a private address |
 | `INSIKA_EGRESS_ALLOW_HTTP` / `_ALLOW_PRIVATE` | off | for `http`/loopback callbacks only (**never in cloud**). Also opens inbound **media** fetches (audio/image URLs) to `http`/private targets — a local run serving media over `http://` needs it |
 | `INSIKA_RELAY_TOKEN` | — | **mounts the relay channel** at `POST /channels/relay/events`, and is the Bearer it requires. Empty = the route does not exist (`404`). See [Channels](CHANNELS.md) |
 | `INSIKA_RELAY_DELIVER_URL` | — | your callback; the engine POSTs each reply there. Goes through the egress guard |
@@ -128,16 +129,17 @@ this section is the single source of truth for what changing it means.
 | `INSIKA_RELAY_DELIVERY` | `at_end` | how the relay flushes the outbox: `at_end` (one POST) or `progressive` (one POST per balloon — [delivery policy](CHANNELS.md#delivery-policy)) |
 | `INSIKA_WIDGET_ORIGINS` | — | exact-match origins allowed to embed the [web widget](CHANNELS.md#the-web-widget), comma-separated. No wildcards. **Half the switch**: with `INSIKA_WIDGET_AGENTS` unset, nothing is mounted (`404`) |
 | `INSIKA_WIDGET_AGENTS` | — | agent ids a widget visitor may address, comma-separated. The other half of the switch. **A chat rate limit is also required** or the widget answers `503` |
+| `INSIKA_DATABASE_URL` | — | **Postgres store** (`postgres://…`, Postgres 13+). Set, it replaces `INSIKA_DB` and Litestream is skipped. Needs the `pg` gem. See [Postgres store](#postgres-store-optional) |
+| `INSIKA_DATABASE_POOL` | `10` | Postgres connections per process |
 | `LITESTREAM_REPLICA_URL` | — | **enables Litestream** (backup/DR). Empty = disabled (default). See below |
 | `LITESTREAM_ENDPOINT` | — | S3-compatible endpoint (R2/MinIO). Empty = AWS S3 |
 | `LITESTREAM_REGION` | — | bucket region (AWS: `us-east-1`; R2: `auto`) |
 | `LITESTREAM_ACCESS_KEY_ID` / `LITESTREAM_SECRET_ACCESS_KEY` | — | bucket credentials (read natively by Litestream) |
 
-> **Renamed from `HARNESS_*` → `INSIKA_*`.** Every engine variable now uses the
-> `INSIKA_` prefix. The old `HARNESS_*` names are still honored as deprecated aliases
-> — set either one and the engine reads it, logging a one-line deprecation notice at
-> boot (`insika doctor` reports it too). Migrate at your convenience; the legacy names
-> will be dropped in a future release.
+> **Renamed from `HARNESS_*` → `INSIKA_*`.** Every engine variable uses the `INSIKA_`
+> prefix. The old `HARNESS_*` names were removed in 1.0 and are no longer read: a
+> leftover one is reported as an error naming its replacement (at boot and in
+> `insika doctor`). Rename it before upgrading.
 
 > **The database filename changed too** — the image now defaults to
 > `INSIKA_DB=/data/insika.db` (it was `/data/harness.db`). **Existing volumes are
@@ -188,7 +190,7 @@ insika doctor --json     # machine-readable (CI / monitoring)
 insika doctor --fix      # applies the safe autofixes and re-diagnoses
 insika env               # lists known keys + current values (secrets masked)
 insika tools:report      # tool audit over the stored traces: never-called
-                         # allowlisted tools, error rate > 30%, stale tools —
+                         # allowlisted tools, error rate > 30%, stale tools, gate refusals —
                          # read-only, the operator removes ([--agent ID] [--days N] [--json])
 ```
 
@@ -203,7 +205,18 @@ text rather than a serialized object** (a file whose content is a stringified Ha
 serves a mangled prompt on every turn while looking perfectly healthy — present,
 non-empty, and the agent still answers), **a prompt file that outgrew a prompt**
 (WARN past ~6 000 estimated tokens or 600 lines — the LLM-generated pack shape
-that costs 20%+ extra tokens per turn for no better instruction-following), and
+that costs 20%+ extra tokens per turn for no better instruction-following),
+**in-session compaction enabled with no model slot** (WARN — neither
+`compaction.model` nor the platform `utility_model` is set, so it can never run;
+see [Context](CONTEXT.md)), **eval seeding left on** (WARN — `evals.seeding`
+opens `POST /v1/conversations/:id/seed`, which writes a fabricated conversation
+state under the tenant token; fine while running snapshot evals, off in
+production — see [Evals](EVALS.md#state--a-case-starts-from-a-snapshot)),
+**provenance and presentation tools without an allowed evidence data tool**
+(WARN — the check only sees stored data declarations; verify any code-tool source),
+**fencing off for agents exposed by relay/widget environment configuration**,
+**cache-layer declarations** (known volatile providers marked identity are errors;
+custom identity providers need a byte-stability review), and
 **skill drift** — a shared skill whose
 body names one store, a prompt file routing to a skill the agent cannot load, a broken
 companion pair, a stale `eager:` key (see
@@ -336,6 +349,21 @@ LITESTREAM_SECRET_ACCESS_KEY=...
 Credentials are read natively by Litestream (they are not in `deploy/litestream.yml`,
 which only references URL/endpoint/region via `${VAR}`).
 
+### One writer per replica path
+
+- **Never point two deployments at the same `LITESTREAM_REPLICA_URL`** (two services,
+  or staging and production). Both replicate into the same lineage and a later restore
+  can bring back the wrong database.
+- **A database already on the volume skips the restore** and is replicated as it is.
+  Give a new deployment an empty volume, and do not set the replica URL on a box whose
+  volume holds the wrong file — it will be copied over the backup.
+- **Moving a database** to another deployment or path: stop replication on the old box
+  first (unset the variable and redeploy), and give the new one a fresh path. If the old
+  box's local state is stale (`LTX file is missing`), run `litestream reset <db>`.
+- **Point-in-time recovery** into a separate file, to inspect before swapping it in:
+  `litestream ltx -level all <url>` lists the history, then
+  `litestream restore -txid <id> -o /data/recovered.db <url>`.
+
 ### Restore drill (the real "done" — an untested backup does not count)
 
 The pilot→production gap only closes once a restore has been **exercised**. Two ways:
@@ -353,8 +381,8 @@ scripts/litestream-restore-drill.sh      # needs docker, sqlite3, curl
 
 ```bash
 # a. with the service live and replicating, generate some config/conversation and
-#    confirm the replica has generations:
-litestream snapshots -config deploy/litestream.yml "$INSIKA_DB"
+#    confirm the replica has files (Litestream 0.5 lists them as LTX files):
+litestream ltx -config deploy/litestream.yml "$INSIKA_DB"
 
 # b. boot a NEW box (empty volume) with the same LITESTREAM_* vars → the entrypoint
 #    restores on boot. Verify manually in /studio that conversations and config came
@@ -362,12 +390,41 @@ litestream snapshots -config deploy/litestream.yml "$INSIKA_DB"
 litestream restore -config deploy/litestream.yml -o /tmp/restored.db "$INSIKA_DB"
 ```
 
+## Postgres store (optional)
+
+SQLite is the default and the right choice for one box, including several worker
+processes (`INSIKA_WORKERS` > 1): their writes share commits (group commit), so
+they only queue behind the file's single write lock under sustained bursts of
+writes. Postgres removes that lock — writers only meet on the keys they share — but
+every store call becomes a network round trip, and a turn makes many store calls,
+so on one box it is usually slower per turn, not faster.
+
+Choose Postgres when the store must be shared: several nodes or replicas running
+the engine, or other systems that query the data directly. Measure your own load
+before switching for speed alone.
+
+1. Add `gem "pg"` to your Gemfile (the reference image already has it and libpq).
+2. Set `INSIKA_DATABASE_URL=postgres://user:pass@host:5432/db` (Postgres 13+).
+   It replaces `INSIKA_DB`; Litestream is skipped. `INSIKA_DATABASE_POOL` sets the
+   connections per process (default 10). A transaction keeps its connection while
+   its turn waits for the reactor, so under many concurrent turns a small pool is
+   where calls queue; raise it, keeping workers × pool under the server's
+   `max_connections` (100 by default).
+3. The table (`insika_kv`) is created on first boot.
+4. Moving an existing SQLite store into an **empty** database (the copy adds and
+   overwrites keys, it does not remove extra ones): stop the app, then
+   `INSIKA_DB=/data/insika.db INSIKA_DATABASE_URL=… bundle exec ruby scripts/store_copy.rb`,
+   then boot with `INSIKA_DATABASE_URL` set. Unsetting it goes back to the SQLite
+   file as it was at the copy.
+
+Backups are Postgres's job (your provider's snapshots or point-in-time recovery).
+
 ## Kubernetes (evolution)
 
 SQLite does not share one file across nodes. Paths forward: a StatefulSet + a PVC
-per pod + **sticky-by-agent** routing (shard by tenant), or **LiteFS**, or an
-optional **Postgres** adapter. **Litestream** (above) for backup/DR from day one —
-orthogonal to topology.
+per pod + **sticky-by-agent** routing (shard by tenant), or **LiteFS**, or the
+[Postgres store](#postgres-store-optional), which every pod can share.
+**Litestream** (above) for backup/DR of SQLite — orthogonal to topology.
 
 For the *session-routing* half specifically — as opposed to the storage
 topology above — see [`insika-router`](ROUTER.md): N pods behind a

data/docs/EMBEDDING.md

@@ -98,6 +98,16 @@ It also holds for runtime reconfiguration. Editing a provider key in the Studio
 (or dispatching `:upsert_llm_provider`) applies to **that graph only** — the
 change is real, takes effect without a restart, and stops at the graph boundary.
 
+Each turn's chat gets a copied RubyLLM configuration with Insika's diagnostic
+instrumenter. It composes with a host instrumenter already on that configuration:
+host notifications still run, and the graph and global configurations keep the
+host instrumenter. Insika attributes only those chat operations to the task;
+auxiliary model work on the graph's original context has no task correlation.
+Each graph stores its task diagnostics in its own backend, so separate backends
+keep those records isolated. Insika's diagnostic fields are allowlisted, but a
+host instrumenter receives RubyLLM's original payload and must apply its own
+data policy. See [Observability](OBSERVABILITY.md#native-model-diagnostics).
+
 ### 3. The process still owns signals and the reactor
 
 Draining in-flight turns on SIGTERM ([the process model](DEPLOY.md)) is a process