insika 0.8.0 → 1.0.1

data/docs/AGENTS.md

@@ -132,7 +132,9 @@ block after the agent's identity in the system prompt: a weak or empty tool
 result means *try again with a different approach — a rephrased query, a
 synonym, a broader term — before telling the user you found nothing* (and don't
 narrate the retries); a tool error means *read it and fix the arguments*, never
-repeat the exact same call. Without it, a search that returns 0 results reads as
+repeat the exact same call; and an action is *reported as done only after its
+tool call returned success* — never before the call, never over a failed or
+blocked one. Without it, a search that returns 0 results reads as
 final and the model answers "I couldn't find it" when a synonym one call away
 would have.
 
@@ -144,9 +146,44 @@ the thing worth declaring:
 tool_persistence false   # remove the block for this agent
 ```
 
-The block is a byte-stable constant, so `prompt_caching` stays effective: the
-deploy that introduces it costs one cache write per agent, and every turn after
-that hits as before.
+The block is constant, so it does not invalidate the identity prefix between turns.
+
+### `prompt_caching` — explicit cache control
+
+Set `"prompt_caching": true` in the agent payload, or enable it in the Studio
+agent configuration. There is no dedicated DSL method for this flag.
+
+For Anthropic, this puts the cache breakpoint after the identity layer and leaves
+volatile system text below it. Other providers receive a plain system string and
+may cache automatically. See [Context](CONTEXT.md#the-provider-prefix-cache) for
+layering, fallback behavior and token accounting.
+
+### `fencing` — third-party text is data, never instructions
+
+```ruby
+fencing true
+```
+
+Off by default. When enabled, the engine sanitizes ordinary tool result string
+leaves after evidence processing, memory facts/notes, briefing values and the next
+step, the compaction summary, and the knowledge names and descriptions injected in
+the context block. It normalizes Unicode (NFKC), removes invisible format characters,
+replaces control characters except tabs/newlines/carriage returns, strips known
+engine/transcript tag shapes and defuses forged role markers. Tool result strings
+are also capped at `fencing.max_chars` (platform default 12,000); memory and knowledge
+context sanitization does not apply that cap. Tool error and halt results bypass
+this sanitizer; tool Hash keys, evidence item `id`s and attachment captions are
+unchanged (an id is a key the ledger holds byte-exact).
+`load_knowledge` returns the full body without fencing.
+
+A fixed notice beneath the identity tells the model to treat contextual material
+as data. It ships with the flag — the `context_providers` allowlist does not govern
+it. It is stable across turns; it does not guarantee prompt-injection resistance.
+
+Memory/knowledge extraction reads only nonblank user/assistant text regardless
+of the flag. Direct tool messages are excluded, but text repeated by the
+assistant can still reach extraction. `insika doctor` warns for unfenced agents
+exposed by the configured relay/widget environment settings.
 
 ### Why some limits are missing from that list
 
@@ -173,17 +210,16 @@ So the two groups read differently on purpose:
 ### `tool_concurrency` — parallel tool calls
 
 When the model asks for several tools in one step, they run **one at a time by
-default**. Raise `tool_concurrency` and they run together, capped at that number
-in flight:
+default**. Raise `tool_concurrency` to overlap independent reads, capped at that
+number in flight. Tools marked `side_effect` still execute one at a time per session:
 
 ```ruby
 limit :tool_concurrency, 4   # nil / 0 / 1 = serial (the default); N = at most N at once
 ```
 
 One number is both the switch and the cap. It pays off only when a turn issues
-several **slow, independent** calls (data tools waiting on HTTP) — the wall-clock
-becomes the slowest call instead of the sum. It buys nothing for fast in-process
-tools, and it is the *model* that decides the fan-out, which is why the cap is not
+several **slow, independent reads** (data tools waiting on HTTP). It buys nothing
+for fast in-process tools, and it is the *model* that decides the fan-out, which is why the cap is not
 optional: an uncapped batch of 15 data tools is 15 simultaneous requests to the
 same backend.
 
@@ -217,7 +253,7 @@ Which mode you want depends on **when** the message arrives:
 | `queue_mode` | The message arrives… | What happens |
 |---|---|---|
 | `followup` (default) | any time | it waits its turn in the queue — today's behavior, named |
-| `collect` | before the turn starts | the fragments merge into ONE turn |
+| `collect` | before the turn starts — including while it waits behind another turn | the fragments merge into ONE turn |
 | `steer` | while the turn is running tools | it is appended to the run in flight |
 | `interrupt` | while a turn is running that is now **wrong** | that turn is abandoned; this message becomes its own turn |
 
@@ -236,6 +272,13 @@ limit :debounce_max_ms, 10_000 # ceiling on the total wait, so typing forever
 With those settings the three fragments above become one turn carrying
 `"oi\nqueria saber do pedido\n1234567"`, released 2 s after the last one.
 
+**The window is not what opens the door.** A turn is "not started" from the moment
+it is created until it runs, and that includes the whole time it waits behind the
+turn in flight — so with `debounce_ms` at 0 a fragment still merges into a queued
+turn. What the window buys is the case where nothing is running: it holds the turn
+at the front of the queue so fragments have something to land on. Without it a
+burst on an idle session becomes one turn per message, each answered in order.
+
 All three follow the platform-layer rule above, with one extra rung on top:
 **session vars → this agent's limits → the platform default (Studio, `queue.*`) →
 off**. Pinning `queue_mode` in a session's vars is how an operator takes one
@@ -270,11 +313,13 @@ separately lives in one event, emitted when the window closes:
 Times and counts, never content. That is what answers "the customer says they
 sent the order number" without keeping a throwaway task per fragment.
 
-> **`steer` also collects at the door.** The two windows are the same policy's
-> halves, not two modes: a `steer` agent that set a `debounce_ms` also merges the
-> fragments that land before the turn starts. The window value is what
-> an operator replaces the legacy pre-batch buffer with — `steer` catches anything
-> that arrives after the turn started, the door window the fragments before it.
+> **`steer` also collects at the door.** The two are the same policy's halves, not
+> two modes: a `steer` agent merges the fragments that land before the turn starts
+> and appends the ones that land after it — `debounce_ms` only widens the first
+> half. That pairing is what makes a burst answerable at all: whatever the customer
+> sends either joins the run in flight (`steered`) or the turn behind it (`merged`),
+> and the caller hears which one immediately instead of holding a connection open
+> until someone else's turn ends.
 
 #### `steer` — the message arrives while the turn is already running
 
@@ -405,9 +450,9 @@ Three capabilities invert the default — `nil`/absent means **OFF**, not "all":
 `subagents`, `memory`, and `guardrails` (each defaults to off or a conservative
 setting, never "everything on"). `tool_output_compression` is a fourth: opt-in
 mechanical dedupe of repeated tool results in the history (see
-[Context](CONTEXT.md#compaction-is-not-wired--except-the-mechanical-dedupe)),
-off by default because it changes what the model sees. And one flag inverts the
-other way: `tool_persistence` is **ON unless you set it to `false`** (see
+[Context](CONTEXT.md#budget-and-eviction--the-actual-compaction)),
+off by default because it changes what the model sees; `fencing` is a fifth (see
+[`fencing`](#fencing--third-party-text-is-data-never-instructions)), off by default. One flag inverts the other way: `tool_persistence` is **ON unless you set it to `false`** (see
 [`tool_persistence`](#tool_persistence--dont-give-up-on-the-first-empty-result)).
 
 ### Declaring what this deployment has
@@ -598,6 +643,24 @@ a running agent.
 
 Photos, voice notes and documents travel through the message contract as additive content parts, and the engine can hand generated images back the same way. See [Media](MEDIA.md).
 
+## Caller context next to the message
+
+A caller that wraps each message with its own text (channel rules, the products
+the customer was just shown) sends that text in `context`, not in `message`:
+
+```bash
+curl -X POST /v1/messages?stream=false -H "Authorization: Bearer $TOKEN" \
+  -d '{ "agent": "store-support", "session_id": "chat-7",
+        "context": "<channel>sms</channel>", "message": "show me more" }'
+```
+
+The model is asked `context`, a blank line, then `message`, and the transcript
+keeps the same text. The input guardrail, retrieval and routing read `message`
+alone, so a product name in `context` never blocks the customer, and the
+customer cannot slip past the guardrail by typing a caller's tags. Optional
+String; absent = the message alone. `POST /v1/responses` takes the same `context`
+next to `input`.
+
 ## Customer-scoped memory and the right to be forgotten
 
 Memory is naturally **per customer, not per tenant**. A message that carries a
@@ -614,6 +677,10 @@ curl -X POST /v1/messages?stream=false -H "Authorization: Bearer $TOKEN" \
   tenant never see each other, and the `<request_context>` tenant label (the
   merchant) is untouched. Absent `customer` = today's per-tenant/per-chat
   behavior.
+- **Display labels** — optional `customer_name` and `customer_phone` (Strings)
+  label the conversation in the Studio (the name replaces the `customer` key;
+  the phone shows beside the agent) and the Chats search matches both. They
+  follow the latest value sent and have no effect on memory scope.
 - **Right to be forgotten** — `POST /v1/commands/forget_customer` (operator)
   purges the customer's memory cell, their sessions and everything those
   sessions left behind — per-session traces, the tasks (the message text lives
@@ -692,11 +759,68 @@ optionally shared outside the Studio via an expiring signed link
 saving agent — never a parameter the model types. Artifact content is LLM
 output and is served as untrusted. See [Artifacts](ARTIFACTS.md).
 
+## Review before enabling writes
+
+Does each ID come from the server? Declare `evidence` on the lookup tool and
+`requires_evidence` on the write tool so the engine enforces session provenance.
+Mark writes as `side_effect` so parallel batches serialize them and recovery skips
+completed calls. See [Tools](TOOLS.md#provenance-checking-ids-before-a-write).
+
+## Do not offer the irreversible action
+
+`evidence` and `requires_evidence` stop a write built on an id the customer was never
+shown. They do not stop a write the model decides the customer asked for. That is a
+prompt problem, and the [cross-harness bench](CROSS-HARNESS-BENCH.md) measured how
+large it is.
+
+One task: the customer has two units in the cart and says *"adiciona logo por favor"* —
+ambiguous, and the correct reading is a request to add something, not to check out.
+Ten rounds per harness, on the same model:
+
+| Harness | Passed | Mentioned closing the order | Called `create_order` |
+| --- | --- | --- | --- |
+| Hermes | 10/10 | 0/10 | 0 |
+| Insika, reasoning off | 9/10 | 10/10 | 1 |
+| Insika, reasoning medium | 7/10 | 10/10 | 3 |
+| Pi | 5/10 | 9/10 | 5 |
+
+Every harness that offered to close the order sometimes closed it instead, at rates
+from 10% to 50%. The one that never offered never closed it. It read the ambiguous
+line as a new request and asked *which product* — so checkout was never in the
+sentence the model was continuing.
+
+**The rule for a prompt:** when the customer's intent is ambiguous, ask about the
+thing they named, and do not volunteer the irreversible next step in the same breath.
+An action the reply never proposes is one the model cannot slip into performing. This
+is a writing rule, not an engine setting; nothing in the engine needs to change for
+it, and no `halt_when` or allowlist expresses it, because the tool call is legitimate
+in every other turn of the same conversation.
+
+**Its cost, before you copy it.** Asking *"which product?"* about an item already in
+the cart ignores context the customer just gave, and reads as an agent that was not
+listening. The bench rewards it because the bench grades the store's state. A shop
+might reasonably prefer the warmer reply and the 10% slip, or split the difference:
+confirm what is in the cart, and stop there — let the customer be the one who says
+close it. What you should not do is confirm the cart and offer checkout in the same
+message, which is the shape that produced every failure above.
+
+Reasoning level does not fix this. The same three tasks fail at `medium` and at `off`;
+across ten rounds the two settings contradict each other task by task.
+
+**The engine's alternative.** If the shop wants the warmer reply *and* zero slips,
+take the write out of the same turn as the offer: declare the tool under
+[`customer_confirm`](TOOLS.md#customer-confirmation-a-write-the-conversation-approves).
+The model may then propose closing the order as freely as it likes — the engine holds
+the call, the reply asks, and only the customer's next message runs it. The cost moves
+from the wording to the conversation: one extra turn on every legitimate close.
+
 ## See also
 
 - [Tools](TOOLS.md) — define, register, and troubleshoot tools.
 - [Artifacts](ARTIFACTS.md) — the report destination: the tool, the routes, the signed link.
 - [Skills](SKILLS.md) — progressive playbooks an agent loads on demand.
+- [Cross-harness bench](CROSS-HARNESS-BENCH.md) — the same store, six harnesses, and
+  where the prompt rule above came from.
 - [Context](CONTEXT.md) — what fills a turn's prompt, and memory.
 - [Security](SECURITY.md) — guardrails, sandbox, approvals, edge limits.
 - [Architecture](ARCHITECTURE.md) — how a turn actually runs.

data/docs/API.md

@@ -21,6 +21,7 @@ two cannot drift (a spec pins the gate's version to the date below).
 | `POST /v1/agents` | provisioning by definition/pack (idempotent, authoritative) |
 | `GET/DELETE /v1/agents` | list / remove agents |
 | `POST /v1/sessions` | create a session explicitly |
+| `POST /v1/conversations/:id/seed` | load an eval snapshot before the first turn; see [Seeding](#seeding-an-eval-conversation) |
 | `POST /v1/outcomes` | record a business outcome (`conversion`, `escalation`, any label) |
 | `GET /v1/outcomes` | last outcome per agent + the per-day series |
 | `POST /v1/commands/...` | operator commands (`forget_customer`, `delete_tenant_data`, the follow-up mutations) |
@@ -30,6 +31,78 @@ two cannot drift (a spec pins the gate's version to the date below).
 The turn endpoints speak the OpenAI `response.completed` wire format; the
 `Insika-Version` header declares the compatibility vintage of a request.
 
+## Tool and presentation SSE events
+
+`POST /v1/responses` emits a tool name on `response.output_item.added`, with
+`arguments` as a JSON string when available. `response.output_item.done` reports
+how it ended. These `ok` / `error` / `blocked` statuses and optional `gate` are
+Insika extensions, not OpenAI function-call lifecycle statuses.
+
+```text
+event: response.output_item.added
+data: {"type":"response.output_item.added","item":{"type":"function_call","name":"add_to_cart","call_id":"toolu_01","arguments":"{\"product_id\":\"SKU-1\"}"}}
+
+event: response.output_item.done
+data: {"type":"response.output_item.done","item":{"type":"function_call","name":"add_to_cart","call_id":"toolu_01","status":"blocked","gate":"provenance"}}
+```
+
+`added` and `done` are two frames of **one** call, paired by `call_id` (the provider's
+tool-call id, present whenever the provider gave one). A consumer that counts tool
+calls counts `added` frames; `done` only says how each ended.
+
+The completion frame does not contain the tool result body. Use stored session
+traces for a per-call audit of what a tool returned.
+
+A presentation call also emits a namespaced event:
+
+```text
+event: insika.ui
+data: {"type":"insika.ui","component":"product_cards","title":"Selected products","items":[{"type":"card","id":"SKU-1","url":"https://shop.example/products/1","caption":"Dark chocolate"}],"count":1,"dropped":[{"id":"SKU-2","reason":"no_card"}]}
+```
+
+`count` is the number shown; `dropped` reasons are `unknown`, `no_card` or `max`.
+An empty selection still emits the event with `count: 0`. Clients that render
+cards consume this event; text-only clients can ignore it. See
+[Presentation tools](TOOLS.md#presentation-tools-the-model-picks-ids-the-engine-shows-the-cards).
+
+## Seeding an eval conversation
+
+Enable `evals.seeding` in platform settings on the eval deployment. For example,
+an operator can `POST /v1/commands/update_settings` with
+`{"patch":{"evals":{"seeding":true}}}`. Turn it off after the run.
+
+`POST /v1/conversations/:id/seed` uses the same Bearer and tenant ID namespacing
+as a turn. Its body is the snapshot itself, plus optional `customer`; do not wrap
+it in `state`:
+
+```json
+{
+  "customer": "eval-customer-1",
+  "evidence": {
+    "ids": ["SKU-1"],
+    "cards": [{ "type": "card", "id": "SKU-1", "url": "https://shop.example/1", "caption": "Dark chocolate" }]
+  },
+  "history": [
+    { "role": "assistant", "content": "The dark chocolate is SKU-1." }
+  ],
+  "memory": { "facts": { "preference": "dark chocolate" }, "notes": [] },
+  "briefing": { "fields": { "delivery_day": "Friday" } }
+}
+```
+
+It creates a missing session and returns `200` with `{ "session": … }`; seeding
+does not run a model or create a task. Disabled seeding returns `403`, a session
+with messages returns `409`, and invalid supported field shapes return `422`.
+History accepts only `user` / `assistant` roles and is stamped `origin: engine`.
+
+Memory uses `[tenant:]customer` when `customer` is supplied; subsequent turns
+must carry the same customer. Without one, memory is written to the tenant cell,
+or `chat:<session-id>` when there is no tenant. Use an isolated eval deployment:
+a fresh conversation ID alone does not isolate tenant memory. Evidence IDs seed
+only the runtime ledger, never model-visible text; `evidence.cards` seeds the cards
+a presentation tool can show.
+See [Snapshot evals](EVALS.md#state--a-case-starts-from-a-snapshot).
+
 ## The compatibility rule
 
 **Request and response shapes are stable; changes are additive-only.** A new

data/docs/ARCHITECTURE.md

@@ -167,9 +167,11 @@ The order is not arbitrary:
 - **The initial checkpoint is written before the model call.** "The checkpoint of
   turn *n* holds the state at the *start* of turn *n*." Without it, a crash during
   the model call would orphan the task with no checkpoint — unrecoverable.
-- **Middleware wraps the model-facing stages**, so the edge limiter and input
-  guardrail run *before* the provider is ever touched — a flood or an injection is
-  refused without a paid model call.
+- **Middleware wraps the chat stages.** For opt-in reranking, the leading edge
+  limiter also wraps context preparation: admission runs once before paid retrieval.
+  Context still precedes policy; the input guardrail and plugin middleware receive
+  the prepared context, including any budget warning, before chat runs. Turns with
+  lexical-only retrieval keep the original order.
 - **Persistence is a fixed order** (checkpoint → session → task) and a pure drain
   point: the last stage never suspends, so a checkpoint is never left half-written.
 - **Output validation** runs as an after-task hook on the produced content
@@ -177,64 +179,65 @@ The order is not arbitrary:
 
 ## The tool-loop
 
-Stage 6 is the single agent interaction. RubyLLM owns the reason→act→observe loop;
-the engine wraps each tool the model may call in a **ToolEnvelope** that enforces
-the per-tool timeout, records side-effects for checkpointing, skips
-already-completed side-effects on resume, and fires the approval gate.
+Stage 6 is the agent interaction. RubyLLM owns the reason→act→observe loop;
+`ToolEnvelope` adds provenance, approval, concurrency, timeout, evidence processing,
+fencing, traces and side-effect checkpoints around registered tools.
 
-When a step contains several tool calls they are executed **one at a time**, unless
-the agent raised `limits[:tool_concurrency]` — then the batch runs on the turn's
-reactor with at most that many in flight, one fiber per call, and the envelope's
-shared semaphore is the cap. A turn with an approval-required tool always runs
-serially. See [Tools](TOOLS.md#parallel-tool-calls) for what that changes.
+Calls run serially unless `limits[:tool_concurrency]` permits parallel execution.
+Marked side effects acquire a serial gate before the shared concurrency slot,
+so writes in one session cannot overlap and queued writes leave slots for reads.
+Turns exposing approval-required tools run serially. See
+[Tools](TOOLS.md#parallel-tool-calls) for limits and timeout behavior.
 
 ```mermaid
 flowchart TD
-  ask[chat.ask -> model] --> dec{tool call?}
+  ask[chat.ask → model] --> dec{tool call?}
   dec -->|no| done[final content]
-  dec -->|yes| env[ToolEnvelope]
-  env --> appr{approval<br/>required?}
-  appr -->|yes| suspend[[suspend turn<br/>await operator]]
-  suspend --> appr
-  appr -->|no / approved| kind{tool kind}
-  kind -->|code| ruby[Ruby class<br/>in-process / sandbox]
-  kind -->|data / MCP| egress[EgressGuard] --> http[(external HTTP)]
-  ruby --> obs[result -> back to model]
-  http --> obs
-  obs --> ask
+  dec -->|yes| env[ToolEnvelope: skip completed side effects on resume]
+  env --> prov{declared evidence IDs known?}
+  prov -->|no| blocked[blocked: provenance]
+  blocked --> ask
+  prov -->|yes / undeclared| appr[approval gate]
+  appr --> gates[side-effect serial gate → shared concurrency slot → timeout]
+  gates --> kind{tool kind}
+  kind -->|code| ruby[Ruby / sandbox]
+  kind -->|HTTP data| http[EgressGuard → HTTP]
+  kind -->|MCP| mcp[live MCP client]
+  kind -->|presentation| cards[select turn or session evidence cards → UI event]
+  ruby --> result[evidence reshape → fencing → checkpoint and trace]
+  http --> result
+  mcp --> result
+  cards --> result
+  result --> ask
 ```
 
-A **data tool** is config, not code (see [Tools](TOOLS.md)): its result comes back
-to the model exactly like a code tool's, but it went out over HTTP through the
-egress guard. A tool exception is caught and returned *to the model* as an error
-result — it does not crash the turn. Side-effecting tools (POST and friends) are
-recorded in the checkpoint so a resume does not re-run them.
+HTTP data tools and presentation tools are both stored definitions. Presentation
+runs in-process; MCP remains a live server call (Streamable HTTP or stdio). HTTP egress
+is checked before a request. Tool errors reach the model as error results so it
+can recover; a provenance refusal reports `blocked` without contacting the backend
+or asking an operator. Completed side effects are recorded for resume.
 
 ## Ingesting tools: manifest and MCP
 
-Tools become data in the store through two runtime paths, both hot (no restart):
+Data definitions and MCP instances have separate stores. Both are hot config:
 
 ```mermaid
 flowchart TD
-  subgraph manifest [Manifest path]
-    m["POST /v1/tools/manifest"] --> sub["substitute<br/>{{env.*}} / {{secret.*}}"]
-    sub --> val1[validate each tool]
-  end
-  subgraph mcp [MCP path]
-    srv[(MCP server<br/>HTTP transport)] --> ing[MCP ingestor]
-    ing --> conv[each tool → HTTP data tool<br/>JSON-RPC tools/call]
-    conv --> val2[validate]
-  end
-  val1 --> store[(ToolStore)]
-  val2 --> store
-  store --> cat[reload catalog + registry]
-  cat --> loop[available in the tool-loop]
+  manifest[POST /v1/tools/manifest] --> substitute[resolve env / secret placeholders]
+  substitute --> validate[validate HTTP or presentation definition]
+  validate --> store[(ToolStore)]
+  store --> data[DataToolRegistry]
+  config[MCP instance configuration] --> mcpstore[(McpStore)]
+  mcpstore --> live[McpToolRegistry → live server tools]
+  data --> catalog[effective registry and catalog]
+  live --> catalog
+  catalog --> policy[agent allowlist → tool-loop]
 ```
 
-The manifest path is the **only** one that resolves `{{env.*}}` (at ingestion);
-every other write path requires a literal URL. Partial failure on the manifest
-path is isolated — one malformed tool is reported in `errors[]` while the rest
-import. See [Tools](TOOLS.md#registering-a-tool).
+Only manifest ingestion resolves `{{env.*}}` and `{{secret.*}}`; other data-tool
+write paths require literal values. One malformed manifest tool is reported in
+`errors[]` while valid entries import. MCP tools are never converted to stored
+HTTP data tools. See [Tools](TOOLS.md#registering-a-tool).
 
 ## Durability: checkpoints and resume
 
@@ -255,9 +258,12 @@ flowchart LR
   completed --> done(((  )))
 ```
 
-Resume always replays from the *start of the last checkpointed turn*. Tool calls
-that already completed in the interrupted turn are recorded in the checkpoint and
-**not** re-executed, so a non-idempotent side-effect fires at most once. A resumed
+Resume always replays from the *start of the last checkpointed turn*. Side-effect
+calls whose completion was recorded in the checkpoint are skipped when replayed
+with the same call id. An external effect can succeed before that record is saved;
+a crash or failed checkpoint write in that window can repeat the effect on resume.
+Use destination-supported idempotency keys or reconciliation for those operations:
+checkpointing alone does not provide exactly-once external execution. A resumed
 turn is also never re-counted against edge-limit ledgers. Cancellation is
 cooperative — checked at stage boundaries, never in the middle of a store write.
 
@@ -316,7 +322,7 @@ validator as the after-task hook, so both roots enforce content safety identical
 | Recovery | `lib/insika/recovery.rb` |
 | Inbound queue (one turn at a time per session, and what happens to a message that arrives while one is running) | `lib/insika/session_actor.rb`, `lib/insika/queue_policy.rb`, `lib/insika/steer_injector.rb` |
 | Channels (a way in and out for people; the reply that travels after the turn ends) | `lib/insika/channel_registry.rb`, `lib/insika/channels/*`, `lib/insika/channel_delivery.rb`, `lib/insika/outbox_store.rb`, `lib/insika/inbound_log.rb` |
-| Tools (data/manifest/MCP) | `lib/insika/tool_definition.rb`, `tool_manifest.rb`, `mcp_tool_ingestor.rb` |
+| Tools (data/manifest/MCP) | `lib/insika/tool_definition.rb`, `lib/insika/tool_manifest.rb`, `lib/insika/mcp_tool_registry.rb`, `lib/insika/tools/present.rb` |
 | Plugin loading (boot) | `lib/insika/plugin.rb`, `lib/insika/plugin/loader.rb` |
 | Refinement (traffic → report) | `lib/insika/refinement/*`, `lib/insika/refinement_store.rb` |
 | Post-turn learning (facts, skills, knowledge — extracted from finished conversations) | `lib/insika/distill.rb`, `lib/insika/harvest.rb`, `lib/insika/knowledge.rb`, `lib/insika/knowledge_store.rb`; the per-turn hook lives in `Executor#persist_turn`, next to `finalize_delegation` |

data/docs/ARTIFACTS.md

@@ -63,9 +63,39 @@ Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; img-src
 X-Content-Type-Options: nosniff
 ```
 
-No script, no external fetch, no forms. The model writes HTML with **inline
-SVG** for charts — that is a skill instruction (palette, tables, pure-SVG bars),
-not engine code. A "real" charting need is a plugin.
+No script, no external fetch, no forms. The model writes self-contained HTML/CSS
+with **inline SVG** or HTML bars for charts. Native radio controls and
+`details`/`summary` still work inside this boundary.
+
+## Interactive executive reports
+
+The tool description and `daily-digest` skill guide future HTML reports. Existing
+artifacts keep their saved content. The
+[example report](https://github.com/guizaols/insika/blob/main/examples/scheduled-report/interactive-report.html)
+uses explicitly fictional data and works without JavaScript or dependencies.
+
+- Lead with the title, reporting period, generation date and a concise takeaway
+  supported by the numbers. Include sources and limitations; mark missing data
+  and fictional examples honestly.
+- Use warm neutral surfaces and one amber or merchant accent. Keep typography,
+  spacing and KPI cards consistent; support system dark mode and narrow screens.
+- Label charts with units and exact values. Use responsive SVG or HTML bars and a
+  captioned table with column headers, so touch users can read every value.
+- Switch Chart/Table with labeled, focusable native radios in a `fieldset` with
+  a `legend`, styled through CSS `:checked`. These are radios, not ARIA tabs.
+- Use CSS hover/focus tooltips in reserved space, highlights, a visible 2px focus
+  outline, and `details`/`summary` for supporting evidence. Keep tooltips visible
+  when the pointer moves onto them. Do not make hover the only way to
+  read data or use `<title>` as the only tooltip.
+- Limit color/opacity transitions to 140ms and disable them under
+  `prefers-reduced-motion: reduce`. Avoid decorative animation. Print styles
+  include the complete table and details regardless of selected/collapsed state,
+  hide controls and keep text legible; use the browser's print command.
+
+Interactivity explores a **dated snapshot**. It does not fetch new data, recompute
+the source or imply a live feed. A later report run saves a new artifact. Do not
+add scripts, event handlers (including `onclick` print buttons), external resources
+or form submissions to generated reports.
 
 ## Reasoning effort on a report turn
 

data/docs/BENCHMARK.md

@@ -45,6 +45,7 @@ reports only the engine's contribution:
 | **gen** (p50/p95) | streaming the rest through the pipeline (filter/emit/event stream) |
 | **throughput** | turns/s a single process sustains at a given concurrency |
 | **pipeline overhead** | engine work per streamed token (µs) |
+| **allocations** | Ruby objects allocated per measured turn, including benchmark driver bookkeeping, excluding warmup |
 
 **Out of scope, on purpose:** end-to-end latency, time-to-first-token *against a
 provider*, and tokens/s of *model generation*. Those are provider-bound — the
@@ -52,8 +53,9 @@ Insika has no lever on them — so this suite makes no claim about them.
 
 The stub implements exactly the chat surface the executor touches, and each turn
 runs the full engine path: context build, policy resolution, guardrail
-detectors, chat assembly, the tool-call round-trip, streamed output, persistence,
-checkpointing, and the event stream. Only the network call is removed.
+detectors, chat assembly, tool-call callbacks, streamed output, persistence,
+checkpointing, and the event stream. The default mode replaces RubyLLM's Chat;
+use `--ruby-llm` below to include the real Chat and tool execution.
 
 ## Scenarios
 
@@ -62,8 +64,8 @@ imported the same way any pack is, so the measured path is the real one.
 
 - **greeting** — a minimal turn: a short system prompt, no tools. Baseline
   engine overhead.
-- **tool_call** — a turn where the agent calls one tool; exercises tool
-  assembly, the wrap/dispatch path, and the call→result round-trip.
+- **tool_call** — a turn simulating one tool call; exercises tool assembly and
+  call/result callbacks without executing the tool.
 - **multi_turn** — a one-shot carrying prior conversation messages; shows how
   overhead moves as the context the engine assembles grows.
 
@@ -80,12 +82,46 @@ imported the same way any pack is, so the measured path is the real one.
 | `--history-turns N` | `10` | prior messages for the `multi_turn` scenario |
 | `--output-tokens N` | `48` | tokens the stub streams per turn |
 | `--json` | off | emit results as JSON (for regression gating) |
+| `--ruby-llm` | off | run the real RubyLLM Chat with an offline provider |
 
 `--json` prints the engine version, Ruby/YJIT status, the full config, and every
 metric — a stable shape to diff across commits.
 
+## Offline RubyLLM benchmark
+
+```bash
+bundle exec ruby scripts/bench.rb --ruby-llm --json
+```
+
+This opt-in mode measures the engine **plus RubyLLM's real Chat and tool loop**.
+Only the provider is synthetic: it yields deterministic chunks without HTTP,
+credentials, or a model service. The normal executor creates the Chat, assembles
+its history and tools, and registers the production callbacks. The `tool_call`
+scenario executes two sequential lookup rounds; `greeting` streams an answer and
+`multi_turn` seeds the requested history before streaming.
+
+JSON includes the RubyLLM version, `mode`, and per-scenario `ruby_llm_activity`
+counts for provider calls, executed tools, history messages, and streamed chunks.
+Activity counts include warmup; allocation measurements exclude warmup and cover
+both measured passes. Compare matching modes and settings across versions; the
+default stub mode keeps its existing one-tool scenario. Neither mode measures
+HTTP serialization, network latency, or actual model generation.
+
+The offline provider supplies request `model_info`, as native RubyLLM 2 usage
+tracking does. Omitting it adds spurious catalog lookups during cost accounting.
+For an isolated, self-checking reproduction without Insika, run
+`ruby scripts/rubyllm_profile.rb 2.0.0 --profile` and repeat with
+`--request-context`. Use `1.16.0` for the old-gem comparison, outside Bundler.
+Method timings are inclusive and must not be summed; use runs without `--profile`
+for latency comparisons. This diagnostic still omits native HTTP processing.
+
 ## Reference numbers
 
+For the five-run main versus RubyLLM 2 migration comparison repeated on
+2026-09-24, see [current candidate results](RUBYLLM_2_MIGRATION.md#current-candidate-2026-09-24).
+It uses this harness, plus the API-equivalent baseline harness, without YJIT.
+The older YJIT reference below is not a migration acceptance result.
+
 A reference run. **The absolute milliseconds are machine-specific** — reproduce
 them on your own hardware with the command below; what travels across machines is
 the shape (sub-millisecond overhead, flat p95, thousands of turns/s per process).
@@ -109,6 +145,13 @@ work. The rest of any real turn's latency is the provider.
 ## Publication rule
 
 **Any public claim about the engine's performance must reference this suite.**
-Numbers produced against a specific provider, deployment, or competitor are not
-publishable — they are neither neutral nor reproducible. If a claim cannot be
-reproduced by running `scripts/bench.rb`, it does not go in public materials.
+Performance numbers produced against a specific provider, deployment, or competitor
+are not publishable — they are neither neutral nor reproducible. If a performance
+claim cannot be reproduced by running `scripts/bench.rb`, it does not go in public
+materials.
+
+The rule is about **performance**, which is what this suite measures. Claims about
+what an agent *gets right* live in a different suite with a different contract: the
+[cross-harness bench](CROSS-HARNESS-BENCH.md) needs a provider key, because a
+commerce conversation cannot be stubbed, and it names other harnesses. It carries its
+own publication rule, which is stricter about the rows it did not write.