insika 0.8.0 → 1.0.1

data/docs/SKILLS.md

@@ -249,9 +249,11 @@ in the allowlist → the model never sees it in `<available_skills>`.
 Two ways to satisfy both:
 
 - **Via a definition/pack import.** The import writes each skill directory into
-  the store and sets the agent's `skills` allowlist **authoritatively** from the
-  skills present — so a re-import that drops a skill also removes it. Keep the
-  definition complete.
+  that agent's scope, without overwriting another agent's or a shared skill, and
+  sets the agent's `skills` allowlist **authoritatively** from the skills present.
+  Dropping a skill removes it from the allowlist, not storage. Keep the definition
+  complete. Packs previously imported into shared scope must be reimported from
+  their original sources; the overwritten shared body cannot recover each agent's version.
 - **Directly (Studio / API / DSL).** Write the skill (upserts the row and reloads
   the catalog atomically — live immediately), then attach it to the agent(s) by
   adding its name to the `skills` allowlist.

data/docs/STUDIO.md

@@ -0,0 +1,122 @@
+---
+title: Studio
+parent: Operate
+nav_order: 0
+permalink: /studio/
+---
+
+# Studio — the operator UI
+
+The Studio is the web UI at `/studio`. Sign in with `ADMIN_TOKEN` (see
+[Deploy](DEPLOY.md#environment-variables)). This page covers the screens for
+watching conversations, reviewing what waits on a person, and seeing what a
+change did. Model metrics are on [Observability](OBSERVABILITY.md#studio-models).
+
+Outside production, a banner above every page names the environment
+(`INSIKA_ENV`, else `RACK_ENV`, else `local`): amber for staging, blue for
+anything else. Production (`production` or `prod`) shows no banner.
+
+## Navigation
+
+The sidebar groups pages as Operate, Review, Build, Insights and Platform. Each
+Review page shows a badge with how many items wait on it. `⌘K` (or Search in the
+sidebar) opens a palette that jumps to any page or agent.
+
+## Overview
+
+`/studio/home`. The Overview shows the headline numbers for the agent filter and
+a **Needs attention** row. The row lists the review queues, customers waiting for
+a reply and tools failing in the last 24 hours, each linking to its page. Only
+non-zero items show.
+
+## Live
+
+`/studio/live` shows one card per recent conversation: customer, agent, the last
+message, a presence dot (activity in the last 5 minutes) and the guardrail flag.
+Cards move with the event stream. While a turn runs, a card shows the tools it
+calls and "agent is writing…". A turn paused for an approval stops writing until
+it resumes. A ticker lists the latest events, without the streaming deltas.
+
+`?agent=<id>` shows only that agent's conversations.
+
+## Chats
+
+`/studio/chats` lists conversations with three tabs: **All**, **Active now**
+(activity in the last 5 minutes) and **Guardrail flagged**, each with its count.
+The session page shows the customer (key, name, phone) and links to their other
+conversations.
+
+### Why this reply
+
+Each agent reply has a collapsed **why this reply** panel for its own turn:
+
+- context tokens by category, and the skills injected with the reason;
+- the tool calls with status and timing;
+- the guardrail flags on the customer's message.
+
+From the panel, **Replay in Playground** opens the conversation in the
+Playground, and **Save as eval
+case** opens the Evals editor prefilled from the reply (the customer's turns,
+the transcript as the reference, the tools the turn called). A reply that
+streams in live offers the panel when its turn finishes.
+
+### Tool calls
+
+A turn with two or more tool calls draws a waterfall of when each one ran.
+Tool calls are grouped by turn within each task, since the turn number restarts
+at 1 for every task.
+
+### Markup tags
+
+Tags an agent or a host writes in the text, like `<carrossel/>`,
+`<vitrine formato="lista">` or `</b>`, show as highlighted tokens: in replies,
+customer messages, and the Live and Chats previews. They are escaped and never
+rendered. The channel decides what a tag does; the Studio only shows it is
+there. A tag inside inline code stays code.
+
+## Guardrail false positives
+
+On a guardrail flag in the session page, **Mark false positive** records the
+verdict on the flag itself, inside the session, so retention and tenant purges
+cover it. The flag can later be marked resolved, or the verdict undone.
+Reviewing a flag does not count as conversation activity: the session keeps its
+place in the recent lists. The command is `:review_guardrail_flag`.
+
+## Inbox
+
+`/studio/inbox` is one list, oldest first, of everything that waits on a person:
+approvals, fact proposals, mined skills, refinement runs and reported guardrail
+false positives. Tabs filter by type, with counts. Each row opens the page where
+the item is decided.
+
+## Agent History
+
+The **History** tab of an agent shows outcomes per day over the last 30 days:
+the funnel's primary outcome when the agent declares a funnel, else all
+outcomes. A dashed line marks each change to a prompt file or to one of this
+agent's own skills (shared skills change for every agent, so they are not
+marked).
+
+Under the chart, one card per change shows the file or skill, when, a short line
+diff, and the outcomes in the 7 days after against the 7 days before. A window
+that is not complete yet, or that starts before the outcome data, reads "not
+enough data". A prompt card has the Restore form; a skill card links to the
+skill.
+
+## Funnel: where conversations stop
+
+The Funnel page marks the biggest loss between two consecutive declared stages.
+Each loss opens (`?drop=<stage>`) the conversations that reached the stage but
+not the next one in the period, grouped by the last thing that happened:
+
+| Reason | Meaning |
+|--------|---------|
+| Last tool call failed | the conversation's last tool call returned an error |
+| A guardrail flagged a message | a guardrail flagged one of its messages |
+| Customer waiting on a reply | the customer wrote last |
+| Customer went quiet after the agent's reply | the agent wrote last |
+| No message to read | the conversation has no message to classify |
+| Conversation no longer stored | the conversation was deleted |
+
+Only the newest 200 stuck conversations are classified; the page says how many
+were left out.

data/docs/TOOLS.md

@@ -12,16 +12,16 @@ kinds, and the distinction that matters is **who can change one at runtime**:
 
 | | **Code tool** | **Data tool** | **MCP tool** |
 |---|---|---|---|
-| What | a Ruby class (`< RubyLLM::Tool`) | an HTTP call described by config, no Ruby | an MCP server's tool, called LIVE |
+| What | a Ruby class (`< RubyLLM::Tool`) | an HTTP call or card presentation described by config | an MCP server's tool, called LIVE |
 | Lives | in the deployment image | as a row in SQLite | on the MCP server, behind a live client |
 | Editable at runtime | no (shipped in the image) | **yes** (DSL / API / manifest / Studio) | **yes** — enable/edit the *instance* (DSL / CLI / API / JSON import / Studio); the server owns its own tools |
-| Reach for it when | logic must run in-process (file edit, shell, subagent) | calling an external HTTP API | adopting a whole external MCP server's toolset |
+| Reach for it when | logic must run in-process (file edit, shell, subagent) | calling an HTTP API or selecting evidence cards | adopting a whole external MCP server's toolset |
 
 **MCP tools are not data tools.** Configuring an enabled MCP **instance** (any
 surface below) is enough — its tools appear automatically, tagged
 `mcp:<instance>`, and each CALL goes straight to the server through a live,
-held client (stdio process / Streamable HTTP / SSE, with the full protocol
-handshake) — never a frozen snapshot. See [MCP servers](#mcp-servers) below.
+held native RubyLLM client (stdio / Streamable HTTP, with discovery and legacy
+handshake fallback) — never a frozen snapshot. See [MCP servers](#mcp-servers) below.
 
 Code tools **win name collisions** — you cannot register a data tool whose name
 shadows a code tool.
@@ -55,6 +55,9 @@ write path (`POST /v1/tools/manifest`) — writing this same shape via the DSL
 or Studio needs the literal header value instead; see
 "[The one gotcha](#the-one-gotcha-envsecret-templating-is-manifest-only)" below.
 
+`{{ctx.chat_id}}` is the external session ID. In multi-tenant mode, it excludes
+the authenticated tenant prefix used by Insika to isolate stored sessions.
+
 ### Parameters: the schema is the contract
 
 `parameters` is **JSON Schema**, and it reaches the provider verbatim — it is the only
@@ -120,7 +123,7 @@ once, at ingestion — see the gotcha below before reaching for it:
   (`object/array/string/number/integer/boolean`); `oneOf`/`anyOf`/`allOf`/`$ref`/
   `if`/`then`/`else` are forbidden (not every provider supports them).
 - `side_effect` defaults from the method (GET/HEAD → false, else true) and drives
-  checkpoint/replay semantics (a completed side-effecting tool is not re-run on
+  serial execution within a session and checkpoint/replay semantics (a completed side-effecting tool is not re-run on
   resume — see [Architecture](ARCHITECTURE.md#durability-checkpoints-and-resume)).
 
 ### `halt_when`: when the answer is already out
@@ -199,12 +202,10 @@ backend, not of whoever calls it. Every agent sharing the tool gets the same val
 
 ## Evidence: the lean envelope and grounding
 
-A catalog tool returns products; the model should only ever quote the ones the tool
-actually returned — the store dies of a SKU the model invented. `evidence` is the
-declaration that makes "no claim without a tool ID" an engine rule instead of a
-prompt convention. One declaration does **both** jobs: the engine strips the result
-down to what the model sees (the lean envelope) **and** records every returned id on
-the session's evidence ledger. There is no "lean but not evidence" mode.
+An `evidence` declaration reshapes a tool result into a lean list and records its
+IDs in the session ledger. The ledger supplies the write gate, presentation tools
+and optional output grounding below. Declaring evidence alone does not prevent
+unsupported claims in the final answer.
 
 ```jsonc
 { "name": "search_products",
@@ -226,14 +227,98 @@ the session's evidence ledger. There is no "lean but not evidence" mode.
   never a null. A malformed evidence result becomes `{ "error": … }` back to the
   model — a correctable tool answer, exactly like a malformed call.
 - **Attachments** are the optional second half: `[{ "type": "card"|"image",
-  "url": "…", "caption": "…" }]` (≤ 16, url ≤ 500 chars, malformed dropped). They
+  "url": "…", "caption": "…", "id": "…" }]` (≤ 16, url ≤ 500 chars, malformed dropped). They
   **never** reach the model context or the transcript — they ride the channel
   delivery as an additive `attachments` key on the outbox payload, and the channel
-  (or its consumer) decides what a card looks like.
+  (or its consumer) decides what a card looks like. Supply an explicit `id` when
+  cards are not one-to-one with items in the same order. Without one, an attachment
+  takes its item's ID at the original position, before malformed cards are dropped.
+- Lean `line` passes through the tool-result sanitizer only when `fencing` is on.
+  Attachment captions are normalized to UTF-8 but are not fenced. See
+  [Fencing](AGENTS.md#fencing--third-party-text-is-data-never-instructions).
 - A **code tool** opts in the same way: it either returns `{ items, attachments }`
   directly and declares `evidence` in its registry metadata, or exposes an
   `evidence` reader. No declaration = today's tool behavior, byte for byte.
 
+### Provenance: checking IDs before a write
+
+Declare `requires_evidence` on a data-defined tool to accept only IDs previously
+returned by an `evidence` tool in the same session:
+
+```json
+{ "requires_evidence": ["product_id"] }
+```
+
+The full form is `{ "requires_evidence": { "params": ["product_id"] } }`.
+The list must be non-empty and name declared top-level parameters. Scalar values
+and every element of an array are converted to strings and compared exactly:
+`SKU-1` and `sku-1` are different IDs. IDs typed by a customer do not count.
+The ledger includes earlier turns and completed evidence results in the current
+turn, capped at the latest 1,000 distinct IDs. Every declared parameter the call
+carries must pass before any write occurs; a parameter the schema marks optional
+and the model leaves out has nothing to check, a required one left out blocks.
+Search first, then write in a later batch: a search and write in the same parallel
+batch have no dependency ordering guarantee.
+
+An unknown ID returns `status: "blocked"`, `gate: "provenance"`, the parameter,
+the value, and an instruction to search or look it up before retrying. The backend
+is never called and no operator approval is requested. A missing ledger blocks the
+call too. Omit the declaration to keep the existing behavior; MCP tools do not
+support this declaration.
+
+The Studio tool editor exposes `requires_evidence`. Blocked calls appear in session
+traces and `insika tools:report`, emit `tool_blocked` with name/gate/parameter only,
+and increment `insika.tool.blocked`. `insika doctor` warns when an agent allows a
+gated data tool without an allowed data tool declaring `evidence`.
+
+### Side effects in parallel batches
+
+With `limits.tool_concurrency > 1`, tools marked `side_effect` execute one at a time
+within the session's runtime. Unmarked tools still run concurrently, including
+while a write is running. MCP tools are marked `side_effect: true` unless the server
+annotates them `readOnlyHint`; a read-only `POST` data tool needs an explicit
+`"side_effect": false` to keep its concurrency.
+A queued write holds no concurrency slot. Different sessions remain independent;
+backend rules such as quantity limits remain the backend's responsibility.
+
+The per-tool timeout starts after both gates are acquired. Trace duration includes
+queueing time, so it measures how long the model waited, not just backend execution.
+
+### Customer confirmation: a write the conversation approves
+
+Some writes should not happen on the strength of one ambiguous line — closing an
+order, deleting a record, sending a message on someone's behalf. Name them on the
+agent and the engine holds the call for the customer's word:
+
+```ruby
+customer_confirm "create_order"          # DSL; the Studio field is "customer confirm"
+```
+
+When the model calls a held tool, nothing runs. The engine records a pending action
+for the session and returns a `pending_confirmation` result carrying the arguments
+and an instruction: tell the customer exactly what will happen and ask. The turn ends
+with that question. On the next message the open hold is rendered at the tail of the
+context, and two system tools are available: `confirm_pending` runs the original call
+with the arguments recorded at the hold (no path exists to confirm different ones),
+`cancel_pending` drops it. A hold that the next message neither confirms nor cancels
+expires on its own — a customer who changed the subject did not agree.
+
+Three controls now sit on a write, and they compose in this order:
+
+| Control | Who decides | What happens to the turn | Declared on |
+| --- | --- | --- | --- |
+| Provenance (`requires_evidence`) | the ledger | the call is refused, the model is told how to resolve the id | the tool |
+| Customer confirmation (`customer_confirm`) | the customer, next message | the turn ends with a question | the agent |
+| Operator approval (`approvals_required`) | a person in the Studio | the turn suspends and waits | the agent |
+
+A tool is confirmed by the customer or approved by the operator, never both. The
+confirmed run still passes provenance, fencing, the side-effect record and the trace;
+the trace shows the hold as `gate: confirmation`, and the `:tool_result` event and the
+Responses stream report it as `status: held`, which the evals treat as neither a
+success nor an error. Whether the customer's "sim" means yes is the model's reading;
+what the engine guarantees is that the write runs only after an explicit question, a
+customer turn, and an explicit tool call.
+
 ### Grounding: policing claims against the ledger
 
 With the ledger fed, the pack declares how claims are policed — data on the agent,
@@ -263,20 +348,70 @@ grounding mode: :flag, matcher: { sku: '\b[A-Z]{2,4}\d{4,8}\b' }
 - Grounding is **independent of the guardrails opt-in**: an agent with guardrails
   off and `grounding.mode: :flag` still gets the check.
 
+## Presentation tools: the model picks ids, the engine shows the cards
+
+A **presentation tool** selects which evidence cards to show. Declare it with
+`presentation` instead of `request`; it runs in-process and is always
+`side_effect: false`. The model supplies IDs, never card URLs or captions.
+
+```jsonc
+{ "name": "present_products",
+  "description": "Show product cards to the customer. Pass only ids a search returned.",
+  "parameters": [{ "name": "product_ids", "type": "array:string" },
+                 { "name": "title", "type": "string", "required": false }],
+  "presentation": { "component": "product_cards",   // what the channel renders
+                    "ids": "product_ids",           // the array:string parameter
+                    "max": 8 } }                    // 1..16 (the attachment cap; default 16)
+```
+
+Exactly one of `request` / `presentation`; `ids` must name a declared `array:string`
+parameter; `component` follows the tool-name rule. Create it through the DSL,
+manifest or API. The Studio form preserves an existing `presentation` declaration
+on save but does not expose its fields. Requested IDs are deduplicated in order
+and compared case-sensitively. The engine then:
+
+1. keeps only ids the session's **evidence ledger** has seen — the rest are dropped
+   with reason `unknown` (an id the model invented, or the customer typed);
+2. joins each kept id to the card an evidence tool returned **this session** — this
+   turn's first, then the last 64 the ledger kept (cards carry the `id` of the item
+   they stand for); a known id with no card is dropped with reason `no_card`;
+3. truncates to `max` — the overflow is dropped with reason `max`;
+4. records the selection on the turn and emits `:ui` on the stream (published as
+   `insika.ui` on `/v1/responses`, as the `ui` frame on the web channel);
+5. answers the model with `shown` (IDs) and `dropped` (objects with `id` and `reason`) — plus one
+   instruction when nothing could be shown ("name the products in text or search
+   again").
+
+**Delivery.** When a turn made a presentation call, the outbox `attachments` are
+*exactly the presented cards*, in call order, each stamped with the call's `component`
+and `title`. A turn with no presentation call delivers every hoarded card, as before —
+a pack that declares no presentation tool sees no change. An empty selection also
+suppresses that fallback: it emits `count: 0` and delivers no cards from that call.
+An earlier turn's ID can be shown without a fresh lookup while its card remains
+in the session's 64-card ledger. IDs and cards have separate caps: a known ID can
+still return `no_card`. Cards are stored snapshots, not a stock or price refresh.
+
+A presentation tool needs an evidence source to populate the session's cards.
+`insika doctor` warns when an agent allows presentation without an allowed evidence
+data tool (`presentation-tools`); it cannot verify a code-tool evidence source. The line that tells the model
+*when* to show cards ("show cards with present_products, ids only") is the pack's.
+
+Not here: partial rendering while arguments stream, per-component enrichment (price
+today, stock — the card is what the evidence tool returned), and a second component
+such as suggestion chips (same mechanism, when a channel asks for it).
+
 ## Registering a tool
 
 A tool appears in the Studio panel and enters an agent's tool-loop when it is
 **registered** in the catalog **and** allowed by the agent's policy allowlist.
-Four ways to write a data tool into the store — all **hot** (registry and catalog
-reload, no restart):
+Three ways to write a data tool into the store — all **hot** (registry and catalog
+reload, no restart; with several workers, the others pick the change up within ~2 s):
 
 1. **DSL** — `data_tool(name:, …)` in a `Insika.agent { … }` block.
 2. **Studio** — the Tools panel editor.
 3. **Manifest** — `POST /v1/tools/manifest`. Partial failure is isolated: one
    malformed tool becomes an `errors[]` entry; only a structural manifest error
    fails the whole request. The response reports `{ version, created, updated, errors }`.
-4. ~~MCP ingestion~~ — retired. An MCP server's tools are no
-   longer written into this store at all; see [MCP servers](#mcp-servers).
 
 ### The one gotcha: env/secret templating is manifest-only
 
@@ -293,28 +428,67 @@ any other way must ship literal values** — a real URL, and a real (masked on
 read) header value. `{{ctx.*}}` and `{{param}}` work everywhere (they resolve
 at turn time, not ingestion).
 
+The Studio **Tools** screen groups permissions by origin: native tools, HTTP
+tools, and MCP tools by server instance. Selection remains per tool; grouping
+does not change tool names or grant permissions.
+Each section can be collapsed. Filtering by tool or server name opens matching
+sections without changing selections; clearing the filter restores their state.
+Section selection buttons affect every tool in that section, including filtered
+tools, but never override denied tools. Save tools applies the changes.
+
+An MCP instance is a connection, not a single tool. Enable its individual tools
+for the agent in Studio. **Test connection** validates discovery with that
+instance's credentials; it does not validate a separate HTTP data tool or every
+remote tool's execution permissions. When replacing an HTTP tool with MCP,
+remove the old tool from the agent's permissions and update prompt references
+to the actual MCP tool names. Keep the egress allowlist restricted to required hosts.
+
 ## MCP servers
 
 An MCP **instance** is durable config — transport, target, credentials, an
 `enabled` flag — held in its own store, separate from data tools. Once an
 instance is enabled, its tools appear in the catalog automatically (group
-`mcp:<instance>`, `side_effect: true`), and every call goes straight to the
+`mcp:<instance>`, `side_effect: true` unless annotated `readOnlyHint`), and every call goes straight to the
 server through a live, held client — the runtime never converts an MCP tool
 into a stored data tool.
 
-**Three transports**, picked by `transport:`:
+Each tool is named after its instance: `<instance>__<tool>`, with the instance
+lowercased and anything outside `a-z0-9` turned into `_` (instance
+`shop-staging`, tool `list_products` → `shop_staging__list_products`). That is
+the name the model calls and the one an agent's allowlist holds, so two
+instances that offer the same tool (a store's production and staging) stay two
+tools, each reaching its own server. Per-tool overrides (`tools:`) still use the
+server's own tool name. A qualified name over 64 characters is skipped with a
+warning, since providers reject it: shorten the instance name.
+
+The deployment's legacy `import_mcp_tools` command now aliases
+`refresh_mcp_tools`: it returns `{ instance:, tools: }` and emits
+`mcp_tools_refreshed`, replacing the old created/updated import report.
+Previously imported data tools remain unchanged and take precedence over live
+tools with the same name. After refreshing and verifying the live instance,
+delete those snapshots through the normal data-tool controls to use live calls.
+`insika doctor` identifies them by their `mcp:<instance>` group.
+
+**Two supported transports**, picked by `transport:`:
 
 | Transport | Target | Notes |
 |---|---|---|
 | `stdio` | `command` + `args`, run as a child process, `env` is its process environment | requires `INSIKA_MCP_STDIO=1` — see below |
-| `http` | `url` + `headers` (Streamable HTTP, the modern default) | egress-guarded like any outbound URL |
-| `sse` | `url` + `headers` | same egress guard as `http` |
+| `http` | `url` + `headers` (Streamable HTTP) | egress-guarded; HTTPS required outside loopback |
+
+Legacy `sse` records remain stored, but cannot connect through the native client.
+Change the record to `http` with the server's Streamable HTTP endpoint. Event-stream
+responses over Streamable HTTP remain supported; only the old SSE transport is removed.
 
 **The stdio gate.** A stdio instance is arbitrary command execution by
 config — it saves, but refuses to start ("stdio disabled by env") until the
 operator sets `INSIKA_MCP_STDIO=1` (config-over-convention, the same pattern
-as the egress envs). `http`/`sse` need no such gate; their URL is checked by
-the normal egress allowlist instead.
+as the egress envs). `http` needs no such gate; its URL goes through the
+egress guard instead: HTTPS, and a host that resolves to a private address
+needs `INSIKA_EGRESS_ALLOW_PRIVATE` and a place in `INSIKA_EGRESS_HOSTS`. A
+public host is not pinned by that list, since the operator fixed the URL and
+the model cannot change it. Native MCP additionally refuses plain HTTP
+outside loopback, even when `INSIKA_EGRESS_ALLOW_HTTP` is enabled.
 
 **Credentials are never visible in plaintext.** `env` (stdio) and `headers`
 (http/sse) mask every value as `__OCULTO__` on read, everywhere (CLI, API,
@@ -346,6 +520,31 @@ held client, which does its own discovery on first use regardless of whether
    `enabled` flag and its credentials are the **operator's** — a Studio/CLI/API
    edit made after boot is never clobbered back by the next restart.
 
+   The **first** boot after a declaration also lists the server's tools, because
+   until they are listed the agent is offered none of them and answers out of its
+   own head instead. A server that cannot be listed (stdio behind a closed gate, a
+   host that is down) does not stop the boot — it is warned about by name, and the
+   agent runs without those tools until `insika mcp refresh <name>` succeeds.
+
+   **What the deployment trusts each tool with** — a server describes what its tools
+   *do*; only the deployment can say which of its answers are evidence and which
+   parameter may only ever carry an id something already returned:
+
+   ```ruby
+   mcp "store", transport: :http, url: ENV.fetch("STORE_MCP"),
+       tools: {
+         # the store's own field names: no server renames them for us
+         "search_products" => { evidence: { kind: "products", items: "products",
+                                            id: "product_id", line: "line" } },
+         # a write that may only take an id the customer was actually shown
+         "add_to_cart" => { requires_evidence: ["product_id"] }
+       }
+   ```
+
+   Both are refused at ingestion, never at the turn: an `evidence:` typo that
+   survived would extract nothing and the gate below it would block every write.
+   A tool nobody names here behaves exactly as it did before.
+
 2. **CLI** — `insika mcp list | add | remove | import <file.json> | test <name> |
    refresh <name>`. `add` takes `--name`, `--transport`, `--command`/`--arg`
    (repeatable) or `--url`/`--header "Name: value"` (repeatable)/`--env
@@ -367,7 +566,7 @@ held client, which does its own discovery on first use regardless of whether
 
    `insika mcp import FILE.json` upserts every entry (a bare `command` implies
    `stdio`; a bare `url` implies `http`; add `"transport": "sse"` explicitly
-   for SSE — the bare format has no other way to spell it). The same parser
+   only to retain a legacy SSE record pending migration). The same parser
    backs `PUT /v1/mcp` and Studio's "Import JSON" box; `export` produces the
    document back with secrets masked as `__OCULTO__`, so round-tripping an
    export never wipes a stored credential.
@@ -405,9 +604,10 @@ held client, which does its own discovery on first use regardless of whether
 A model can ask for several tools in one step. By default the engine runs them one
 at a time. Set `limits[:tool_concurrency]` above 1 (see
 [Agents](AGENTS.md#tool_concurrency--parallel-tool-calls)) and the calls in that
-batch run concurrently, **at most N in flight**, on the turn's own reactor — so
-the wall-clock of a batch of slow data tools approaches the slowest call rather
-than their sum. The cap covers every enveloped tool of the turn, including the
+batch run concurrently, **at most N in flight**, on the turn's own reactor.
+Tools marked `side_effect` still execute one at a time per session; queued writes
+acquire that serial gate before taking a shared concurrency slot. See
+[Side effects](#side-effects-in-parallel-batches). The cap covers every enveloped tool, including the
 ones `tool_search` promotes mid-turn.
 
 It applies only to what the *model* fans out. Two primitives already parallelize
@@ -434,7 +634,7 @@ Turning it on changes three things, all of them worth knowing before you do:
 Approvals and concurrency are mutually exclusive per turn — the approval gate wins
 and the turn goes serial. That is a deadlock avoided, not a preference.
 
-## Egress: the SSRF guard (and its silent failure)
+## Egress: the SSRF guard
 
 Data tools make outbound HTTP, so every call passes through the **EgressGuard**, a
 Server-Side Request Forgery defense. The default posture is **strict: public
@@ -446,17 +646,10 @@ Server-Side Request Forgery defense. The default posture is **strict: public
 | `INSIKA_EGRESS_ALLOW_HTTP=1` | permit plain `http` — **loopback dev only** |
 | `INSIKA_EGRESS_ALLOW_PRIVATE=1` | permit private/loopback IPs — **dev only** |
 
-> ⚠️ **Egress failures are silent.** When a tool targets a blocked host (e.g. a
-> plain-`http` localhost backend without the opt-ins), the guard turns the block
-> into a `{ error: … }` returned **to the model** — the request never leaves the
-> process, yet the stream still emits a tool call, so the model narrates a
-> plausible failure and the conversation *looks* like it worked. You will not see
-> an exception.
->
-> **Always verify by the trace, never by the reply:** open the Studio session
-> viewer — a healthy call shows the request, args, and the backend's `200`; a
-> missing or errored call is almost always egress (host not in the allowlist, or
-> `http`/private without the opt-in).
+An egress rejection returns `{ error: … }` to the model without making the HTTP
+request. Inspect the session trace for the actual error; a plausible reply does
+not prove the backend ran. Provenance refusals instead report `status: "blocked"`
+and `gate: "provenance"`.
 
 Egress is **orthogonal** to registration and allowlisting: a tool can be
 registered, allowed, offered to the model, and still blocked at call time.
@@ -471,8 +664,9 @@ Work down this checklist:
    `data-tools` check is the only place that says so.
 2. **Allowed for this agent?** In `tools_allow` (or an allowed group), and not in
    `tools_deny`?
-3. **Egress?** If it *appears and is called* but "fails", open the trace — a
-   blocked call is ~99% egress.
+3. **Call refused or failed?** Inspect the trace. For `gate: "provenance"`, look up
+   the ID through an evidence tool before retrying. For an error, check its message
+   for schema, egress, timeout or backend failures.
 4. **URL literal?** For non-manifest tools, an unresolved `{{env.*}}` would have
    422'd at import — re-check the definition.
 
@@ -490,7 +684,7 @@ routes, the signed link and the retention/LGPD reach.
 The per-session trace answers "what did this conversation call"; nothing used to
 answer "what does this agent carry and never use". The report aggregates the
 stored traces per agent (tasks → sessions → `tool_traces`, the same read the
-Studio does) and flags three shapes:
+Studio does) and flags four shapes:
 
 - **`never_called`** — in `tools_allow`, zero calls in any stored trace. Dead
   weight: its schema ships on every request and buys nothing.
@@ -498,6 +692,8 @@ Studio does) and flags three shapes:
   the window (default 14 days). Either the tool is broken or the model cannot
   hold its contract.
 - **`stale`** — called at some point, but not once inside the window.
+- **`blocked`** — gate refusals in the window, counted by gate. These do not count
+  as conventional tool errors.
 
 ```bash
 insika tools:report                        # every stored agent

data/docs/operate.md

@@ -10,10 +10,13 @@ permalink: /operate/
 Running it once it is live: seeing what happened, firing turns nobody sent,
 handing back a report, and knowing what the box will take before it takes it.
 
+- **[Studio](STUDIO.md)** — the operator UI: live conversations, why each reply, the review inbox, what a change did.
 - **[Observability](OBSERVABILITY.md)** — the event stream, and turns as OpenTelemetry traces and metrics.
 - **[Schedules](SCHEDULING.md)** — recurring turns the engine fires on its own tick.
 - **[Artifacts](ARTIFACTS.md)** — a report the agent can hand you a URL to.
 - **[Load test](LOADTEST.md)** — end-to-end load testing, and comparing topologies before you choose one.
 - **[Soak](SOAK.md)** — the long run that finds what a short one cannot.
 - **[Benchmark](BENCHMARK.md)** — the engine's measured overhead, reproducible without an API key.
+- **[Cross-harness bench](CROSS-HARNESS-BENCH.md)** — the same store answered by six harnesses, graded on the store's own state.
+- **[Performance](PERFORMANCE.md)** — what keeps a turn cheap, and what was tried and left out.
 {: .card-grid }

data/docs/prompts/ADD-TOOL.md

@@ -30,6 +30,7 @@ with one turn. Nothing more.
 | The need | The kind | Where it lives |
 |---|---|---|
 | Call an external HTTP API | **data tool** (`data_tool` in the DSL block) | a row in SQLite, editable at runtime |
+| Show selected evidence cards | **presentation data tool** (`presentation`, no `request`) | the tool store; see [Tools](../TOOLS.md#presentation-tools-the-model-picks-ids-the-engine-shows-the-cards) |
 | Logic must run in-process | **code tool** (a Ruby class `< RubyLLM::Tool`) | the deployment image |
 | Adopt a whole external MCP server | **`mcp` instance** | durable config; its tools appear tagged `mcp:<name>` |
 | Teach a procedure (no data fetching) | **skill** (`skill "name", description:, instructions:`) | loads on demand via `load_skill` |
@@ -78,6 +79,12 @@ RULES:
   verbatim and arguments are checked against it at call time.
 - Author the FINAL url: the HTTP client does not follow redirects, and the egress guard
   cleared that host only.
+- For a write that accepts catalog IDs, declare `requires_evidence` for those
+  parameters and ensure an allowed lookup declares `evidence`. Mark the write
+  `side_effect: true`; the engine serializes marked writes within a session.
+- For presentation, follow the [card contract](../TOOLS.md#presentation-tools-the-model-picks-ids-the-engine-shows-the-cards):
+  pass known IDs to the presentation tool. Look up again if their cards are absent
+  from the session ledger or current information is needed.
 - Do not add a second capability "while we're here".
 
 ## Step 3 — Make sure it enters the tool-loop
@@ -96,8 +103,11 @@ instead of fighting it.
 ## Step 4 — Prove it with ONE turn
 
 Run one `reply()` whose message forces the call ("how many BRL is 1 USD right now?").
-The reply must use what the tool returned — if the model answers from imagination, the
-tool did not run: re-check Step 3 before touching the prompt.
+Inspect the trace to confirm the call and result; the reply alone is not proof.
+For a gated write, also verify that an unknown ID is blocked before any backend
+request. For presentation, verify the selected `insika.ui` items. Use
+[snapshot eval assertions](../EVALS.md#graders--what-a-turns-calls-and-reply-are-checked-against)
+when the flow needs a repeatable precondition.
 
 ## Step 5 — Self-check
 

data/docs/prompts/DIAGNOSE-TURN.md

@@ -43,6 +43,9 @@ text), roughly **when**, and expected vs. actual. Reproduce once locally if chea
 | turn completed, customer got nothing | delivery is separate from the turn: check `channel_delivered` / `delivery_failed` | [Channels](../CHANNELS.md) |
 | freshly created agent returns empty turns | persona overflows the default `context_budget` (8000) | [Context](../CONTEXT.md) |
 | tool never called (or "missing") | not registered OR not allowed (`tools_allow`) | [Tools](../TOOLS.md) § troubleshooting |
+| `tool_blocked` with `gate: provenance` | ID absent from session evidence; look up before retrying | [Tools](../TOOLS.md#provenance-checking-ids-before-a-write) |
+| presentation shows no cards | inspect dropped IDs: `unknown`, `no_card`, `max`; a known ID may have no retained card | [API](../API.md#tool-and-presentation-sse-events) |
+| cache reuse dropped | compare identity/tool-schema fingerprints with provider cache token accounting | [Context](../CONTEXT.md#the-provider-prefix-cache) |
 | identical `tool_call` repeated, then abort | the `max_tool_repeat` loop guard | [Agents](../AGENTS.md) § limits |
 | model gave up after one empty result | `tool_persistence` off (it is ON by default) | same |
 | `turn_stuck` event | the agent declared it cannot proceed — escalation signal, not a bug | [Agents](../AGENTS.md) § stuck |

data/docs/prompts/GO-LIVE.md

@@ -87,7 +87,9 @@ In order, each with evidence:
 
 1. `curl https://<host>/up` → `{"status":"ok"}`.
 2. `bin/insika doctor` against the deployed volume (or via the platform's shell) —
-   relay its findings verbatim; fix errors before continuing.
+   relay its findings verbatim; fix errors before continuing. Check evidence sources
+   for gated writes/presentation, review the fencing warning, and leave
+   `evals.seeding` off after snapshot evals. See [Deploy](../DEPLOY.md#strict-config-and-insika-doctor).
 3. One authenticated turn:
 
 ```bash