insika 0.9.0 → 1.0.1

data/docs/CONTEXT.md

@@ -87,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
@@ -102,6 +124,15 @@ 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
@@ -115,6 +146,38 @@ 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) —

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
@@ -347,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:
@@ -364,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
@@ -373,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

data/docs/EVALS.md

@@ -109,7 +109,8 @@ check, and the report names the one that failed.
 
 | Key | Checks |
 |-----|--------|
-| `tools_called: [name, name?]` | each required tool was called (`?` = optional, never fails) |
+| `tools_called: [name, name?]` | each required tool was called on the LAST turn (`?` = optional, never fails) |
+| `turns[i].tools_called: [names]` | the calls one specific turn must make — a two-turn case where turn one claimed an action and turn two repaired the store passes the key above and fails this one |
 | `never_calls: [names]` | none of these was called — the negative every `tools_called` needs |
 | `calls_one_of: [names]` | at least one of these was called |
 | `first_tool: name` | the first call's name |
@@ -119,7 +120,8 @@ check, and the report names the one that failed.
 | `blocked_gates: ["tool:gate"]` | each pair appears among the turn's blocked calls |
 | `ui_components: [names]` | a presentation tool showed at least one card of each component (the `insika.ui` frames) |
 | `no_ui: true` | the turn showed nothing — the negative of `ui_components` |
-| `must_not: [detectors]` | the negative detectors (`pii_leak`, `tool_error`, …); a blocked call is not a tool error |
+| `must_not: [detectors]` | the negative detectors (`pii_leak`, `tool_error`, `phantom_action`, …); a blocked call is not a tool error |
+| `claims: { tool: pattern }` | what `phantom_action` reads — per mutation, the words a reply uses to say it did it (a regex, case-insensitive); the store's language, so it lives in the case |
 
 **Every positive has a negative.** A case that only says `tools_called: [add_to_cart]`
 passes an agent that also re-searched, or that echoed the SKU to the customer. Pin
@@ -128,6 +130,22 @@ in the same case. Snapshots avoid the model calls needed to reconstruct the setu
 use the simulator when later customer messages need to branch on the replies.
 
 `tools_called` confirms an attempted call, not a successful backend mutation.
+
+`must_not: phantom_action` reads the other direction: a reply that SAYS it did
+something ("adicionei", "removi", "fechei o pedido") on a turn where the matching
+tool never ran, errored, or was blocked. It is cumulative over the conversation, so
+"já adicionei" on turn two is true when turn one did it, and it only pins the words
+against the calls — a cart that ended up right by accident is still a lie to the
+customer. The words come from the case's `claims:` map, in the store's own
+language, past tense on purpose: "quer adicionar?" is a question.
+
+```yaml
+expect:
+  must_not: [tool_error, phantom_action]
+  claims:
+    add_to_cart: '\b(?:adicion(?:ei|ad[oa]s?)|coloquei)\b'
+    create_order: '\b(?:fechei|finalizei|pedido (?:criado|fechado))\b'
+```
 Arguments are collected for inspection; there is no generic argument or cart-state
 grader. `blocked_gates` needs completion statuses from the HTTP transport. The
 in-process `GraphTransport` records tool names and UI events, but not completion
@@ -183,12 +201,13 @@ judge is told the rule instead of guessing it.
 
 ```yaml
 expect:
-  policy: ask_once
+  policy: ask_once                    # the strict reading: one question, full stop
+  policy: { ask_once: { max: 2 } }    # a store that greets its customers
 ```
 
 | policy | the check | the judge is told |
 |---|---|---|
-| `ask_once` | no reply asks more than one question | two questions in one message is a failure |
+| `ask_once` | no reply asks more than `max` questions (default 1) | at most `max` per reply, and a greeting formula is courtesy rather than a question |
 | `investigate_first` | turn 1 asks something and calls no tool | ask on a vague request, don't search immediately |
 | `act_fast` | turn 1 calls a tool | asking what a search would answer is a failure |
 
@@ -201,6 +220,16 @@ so a tracking link's query string is not read as the agent asking something. It
 policy signal, not grammar — and crude was enough to catch an agent breaking a rule
 written in its own prompt, twice, with no model in the loop.
 
+**`max` is the store's, and it matters more than it looks.** The default of 1 comes from
+a real store's rule, quoted down to the punctuation: *"Máximo 1 pergunta principal por
+mensagem = 1 ponto de interrogação no fim"*. A store that greets its customers spends
+one of those on courtesy — measured across six harnesses answering the same "oi", `max:
+1` failed every reply containing "tudo bem?" and passed every reply without it, and
+nothing else. That grades a greeting habit, not the rule the policy exists for, which is
+the form: *"qual seu nome? qual o número do pedido? e o motivo?"*. Set `max` to what
+your store actually tolerates; the judge is told the same number, so the two halves
+never grade different rules.
+
 ### `reference` — compared against the system you want to replace
 
 `min_score: 0.7` says a reply cleared a bar you invented. It says nothing about

data/docs/FACTS.md

@@ -70,12 +70,14 @@ The engine never writes store vocabulary.
 
 The **Facts** page (operate group, next to Follow-ups) shows:
 
-- **Pending** — oldest first, because evidence ages. Each card is the fact,
-  its confidence, its scope (`tenant:customer`), and the evidence excerpt read
-  from the transcript at request time (evidence is a link, never a copy). Three
-  buttons: **Approve & save to memory**, **Reject** (with an optional reason,
-  shown on the card), **Dismiss** (ghost — labelled "will not be proposed
-  again").
+- **Pending** — oldest first, because evidence ages. Select a fact to review its
+  proposed value, model confidence and conversation evidence. Long excerpts scroll
+  within the evidence panel; **Open conversation** shows their source. Keys and
+  scope/session IDs live under **Technical details**. **Approve & save to memory**
+  saves the value; **Reject or dismiss** expands the alternatives, including an
+  optional rejection reason. Both prevent the same key and value from being proposed
+  again. Decisions refresh the queue and open the next pending fact in the selected
+  agent/scope.
 - **Stale** — the CAS-lost re-present (below): the proposed value struck
   through next to the operator's current value, resolved by dismissal.
 - **Recent** — every resolved proposal, most recent first, with operator and

data/docs/HARVEST.md

@@ -35,8 +35,10 @@ A mine reads ONLY durable, finished data — never an in-flight turn, never a
 live prompt prefix (the "fork" is structural: the mining writes nothing to the
 sessions it read, so a customer turn's cache is untouched by construction). The
 miner gets the transcript slices (masked), the session's evidence-ledger ids,
-and the agent's current skill names so it does not re-propose them. Then the
-filters, each drop counted and logged:
+the agent's current skill names and the candidates still open (name and
+description), so it does not re-propose an idea under another name.
+Simulator and eval sessions (`sim-…`, `eval-…`) are never mined: they are
+not customers. Then the filters, each drop counted and logged:
 
 1. **The negative list** — the versioned rules file (seed, imported
    per store by `insika harvest:negative import --agent ID --file F`) and the
@@ -111,6 +113,9 @@ back, re-promoted is three readable rows.
 - `insika harvest:criterion check --file F` — strict-load the frozen conversion criterion (the hook before any promotion).
 - The **Harvest page** in the Studio: the human's inbox (each candidate with
   its evidence excerpt, the eval report, the conversion card, promote/reject),
-  the gated-but-blocked rows with the named ruler hole, the pending list, the
+  the gated-but-blocked rows with the named ruler hole and a "Run checks
+  again" once the hole is fixed, the pending list (every row with the skill
+  text, the rationale and a link to its origin conversation), a notice when
+  the loop skips the agent (harvest off, or no grounding matcher), the
   append-only promoted log with the rollback mirror, the negative list with
   per-rule rejection counts, and the criterion block read-only.

data/docs/KNOWLEDGE.md

@@ -95,6 +95,13 @@ end
 recalling (write-only, inspected by hand), or recall without learning
 (curate every concept by hand in the Studio, `provenance: policy`).
 
+The same settings are available in **Studio → Agents → select an agent →
+Configuration → Memory & knowledge**: learn from conversations, use knowledge in
+replies, concepts per turn, concept types, learning model and instructions.
+Knowledge reranking has its own switch and settings, independent of memory
+reranking, and defaults to off. Options authored in a pack but not exposed in the
+form, such as `index`, are preserved when saving.
+
 ## The write path
 
 After a turn completes, off the turn's critical path (the customer already has

data/docs/MEDIA.md

@@ -39,6 +39,8 @@ curl -X POST /v1/messages?stream=false -H "Authorization: Bearer $TOKEN" \
   the usage flows like any ask. The first image URL is also
   `{{ctx.image_url}}` for data tools — photo analysis outside the prompt, the
   tool's own egress applying when it fetches.
+  DeepSeek images require RubyLLM's [image-attachment fix](https://github.com/crmne/ruby_llm/pull/972),
+  included in this deployment's pinned revision, and a vision-capable model.
 - **Documents** (a prescription, a recipe, an invoice — most often a PDF)
   attach the same way images do; the first document URL is
   `{{ctx.document_url}}`. A model without document support fails the ask at
@@ -117,8 +119,10 @@ end
 - **Seams, not magic.** The generator is injectable per kind (specs stub it);
   the defaults are lazy: images via RubyLLM (paint), speech via a thin POST to
   the OpenAI-compatible `/audio/speech` endpoint using the same provider
-  config the chat uses — RubyLLM as of 1.16.0 has no speech API. A generated
-  part over 8 MB refuses loudly, never silently truncates.
+  config the chat uses. RubyLLM 2 has a speech API, but its inspected native
+  transport buffers non-audio/error responses without yielding chunks. Insika
+  retains its bounded HTTP transport until native limits cover those responses.
+  A generated part over 8 MB refuses loudly, never silently truncates.
 - **Not here:** what the generated image *means* — a fitting room, a product
   mockup — is a skill on top. The engine transports bytes and cost.