insika 0.7.0 → 0.9.0

data/docs/FACTS.md

@@ -38,6 +38,10 @@ decides; the engine never applies its own proposal.
 5. Approved facts join the customer's memory cell and are injected by the
    Memory provider on the next turn of any session of that customer.
 
+The extraction transcript contains only nonblank `user` and `assistant` text,
+with original message indexes preserved. Tool payloads are excluded regardless
+of `fencing`; an assistant's repetition of tool text can still be included.
+
 ## Enabling it — the `distill:` block
 
 Distillation is pack data on the agent, exactly like `refinement:` or

data/docs/KNOWLEDGE.md

@@ -27,6 +27,13 @@ and an operator can see, edit and resolve all of it in the Studio. Only the
 optional FTS5 index remains, deferred with a measured trigger — see
 [What's not here yet](#whats-not-here-yet).
 
+Extraction reads only nonblank `user` and `assistant` text, retaining original
+message indexes. Direct tool payloads are excluded regardless of `fencing`;
+assistant paraphrases can still reach the extractor. The names and descriptions
+in the injected `<knowledge>` block are sanitized when
+[fencing](AGENTS.md#fencing--third-party-text-is-data-never-instructions) is on.
+The full body returned by `load_knowledge` is not fenced.
+
 ## The concept format
 
 One concept is one record — a markdown document with a YAML frontmatter

data/docs/LOADTEST.md

@@ -67,7 +67,7 @@ frame that carries it.
 
 ```bash
 INSIKA_URL=http://localhost:9292 \
-OPENCLAW_GATEWAY_TOKEN=xxx \
+INSIKA_GATEWAY_TOKEN=xxx \
 bundle exec ruby scripts/loadtest.rb \
   --agents demo,my-store --concurrency 16 --iterations 3 \
   --message "hi, how are you?"
@@ -80,7 +80,7 @@ Runs against a local server **or** a remote one (e.g. Railway) — just point
 
 | Flag | Default | Meaning |
 |------|---------|---------|
-| `--agents a,b,c` | `demo` | comma-separated agent ids (mapped to `model: openclaw:<agent>`) |
+| `--agents a,b,c` | `demo` | comma-separated agent ids (mapped to `model: insika:<agent>`) |
 | `--concurrency N` | `8` | concurrent turns per wave |
 | `--iterations N` | `1` | number of waves per agent |
 | `--message TEXT` | greeting | user message sent every turn |
@@ -95,14 +95,14 @@ Runs against a local server **or** a remote one (e.g. Railway) — just point
 | Env | Default | Meaning |
 |-----|---------|---------|
 | `INSIKA_URL` | `http://localhost:9292` | base URL of the engine |
-| `OPENCLAW_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN`, then `local-demo` | Bearer for `/v1/responses` |
+| `INSIKA_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN`, then `local-demo` | Bearer for `/v1/responses` |
 | `DEEPSEEK_API_KEY` | — | must be configured **on the server** for real turns (not read by the client) |
 
 Use `--dry-run` to sanity-check your flags/URL/token before firing real traffic
 (and to confirm the request body without needing a running server):
 
 ```bash
-INSIKA_URL=http://localhost:9292 OPENCLAW_GATEWAY_TOKEN=xxx \
+INSIKA_URL=http://localhost:9292 INSIKA_GATEWAY_TOKEN=xxx \
   bundle exec ruby scripts/loadtest.rb --agents demo --concurrency 16 --dry-run
 ```
 
@@ -133,7 +133,7 @@ DEEPSEEK_API_KEY=sk-... ./scripts/loadtest-local.sh [WORKERS] [CONCURRENCY]
 | Env | Default | Meaning |
 |-----|---------|---------|
 | `DEEPSEEK_API_KEY` | — (required) | real turns hit the provider; also auto-sourced from `.env.local` |
-| `OPENCLAW_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN`, then `local-demo` | Bearer for the sweep |
+| `INSIKA_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN`, then `local-demo` | Bearer for the sweep |
 | `PORT` | `9299` | bind port for the local Falcon |
 | `AGENT` | `demo` | agent id to load |
 
@@ -158,30 +158,18 @@ the engine, once at the gateway (its `/v1/responses` speaks the same protocol).
 Keep `--agents`, `--concurrency`, `--iterations` and `--message` identical, and use
 matching agents on both sides. Compare the printed TTFB/total/cache/error lines.
 
-### 4b. Reuse OpenClaw's `loadtest-gateway.mjs` unmodified
+### 4b. Comparing against an OpenClaw gateway
 
-`loadtest.rb` is the Ruby port of OpenClaw's `loadtest-gateway.mjs`. You do **not**
-need to change that script to point it at the engine — because the engine is a
-drop-in for the gateway, you only change **where it points**:
+The engine speaks its own wire names (`model: insika:<agent>`, header
+`X-Insika-Agent`), so OpenClaw's `loadtest-gateway.mjs` cannot be pointed at it
+unmodified. For a shadow comparison, run `loadtest.rb` (section 4a) against each
+side with identical `--agents`, `--concurrency`, `--iterations` and `--message`,
+and diff the reports. What you still need in hand:
 
-```bash
-# In the OpenClaw checkout, run its gateway loadtest against the HARNESS:
-OPENCLAW_GATEWAY_URL=http://localhost:9292 \
-OPENCLAW_GATEWAY_TOKEN=<same bearer the engine accepts> \
-node scripts/loadtest-gateway.mjs --agents demo --concurrency 16 --iterations 3
-```
-
-Then run the exact same command with `OPENCLAW_GATEWAY_URL` pointing at the real
-gateway, and diff the two reports. This is the shadow comparison the pilot needs.
-
-**What the operator must have in hand** (this repo does not vendor OpenClaw):
-
-- The OpenClaw checkout containing `scripts/loadtest-gateway.mjs` and Node installed.
-- A **bearer token accepted by both** sides. For the engine that is
-  `OPENCLAW_GATEWAY_TOKEN` (see DEPLOY.md); point the gateway run at its own token.
-- **The same agent id provisioned on both** sides (e.g. `demo`) so `model:
-  openclaw:<agent>` resolves on each. On the engine, provision via
-  `scripts/import_pack.rb`.
+- A bearer token accepted by each side — `INSIKA_GATEWAY_TOKEN` for the engine
+  (see DEPLOY.md), the gateway's own token for the gateway run.
+- **The same agent id provisioned on both** sides (e.g. `demo`). On the engine,
+  provision via `scripts/import_pack.rb`.
 - The **same provider** (or an equivalent-latency one) behind each, otherwise you
   are comparing providers, not engines.
 - Both endpoints reachable from where you run the client, warmed up (hit `/up` on

data/docs/MEDIA.md

@@ -87,7 +87,7 @@ receive it (`channel.capabilities` on the request):
 
 ```bash
 curl -X POST /v1/responses -H "Authorization: Bearer $TOKEN" -d '{
-  "model": "openclaw:store-support", "user": "chat-7",
+  "model": "insika:store-support", "user": "chat-7",
   "input": "manda a foto do sofá da promoção",
   "channel": { "capabilities": ["image_output", "audio_output"] }
 }'

data/docs/OBSERVABILITY.md

@@ -25,13 +25,17 @@ authoring writes (`:golden_written`, `:agent_file_written`, …), queue bookkeep
 channel delivery (`:channel_delivered` — see [Channels](CHANNELS.md))
 travel the same stream and are **ignored** by the bridge: they open no span and
 touch no instrument, because they are not part of a turn's latency or cost. Any
-other subscriber still sees them.
+other subscriber still sees them. Additional events feed counters without opening
+spans: `:tool_loop_intervened`, `:tool_blocked` and `:context_compacted`.
 
 They are worth subscribing to even so, because each is the ONLY record of
 something that left no task of its own behind:
 
 | Event | Data | What it answers |
 |---|---|---|
+| `:tool_blocked` | `name`, `gate`, `param` | a provenance gate refused a call before execution; no rejected value in this event |
+| `:ui` | `component`, `title`, `items`, `count`, `dropped` | the presentation selection, including customer-facing card content; see [API](API.md#tool-and-presentation-sse-events) |
+| `:session_seeded` | `session_id`, `tenant`, `keys` | an eval snapshot was loaded; no snapshot contents |
 | `:turn_coalesced` | `task_id`, `merged`, `arrivals[]` | the fragments a customer typed in a row arrived as separate messages, and when |
 | `:turn_steered` | `task_id`, `count`, `total` | a message arrived mid-run and was appended to the turn in flight |
 | `:turn_steer_released` | `task_id`, `released_as`, `count` | the run could not absorb it, so it became the turn `released_as` |
@@ -68,8 +72,9 @@ and correct while the customer got nothing, because delivery is a separate,
 retried, out-of-band step. `status: "failed"` means the reply is sitting in the
 outbox and the customer is still waiting.
 
-Counts, ids and times only — never message content. The text lives in the
-transcript, which is the surface that is allowed to carry it.
+Operational audit events use metadata rather than transcript bodies. Presentation
+`:ui` events intentionally contain customer-facing card content; tool-call events
+can contain arguments. Do not treat the whole event stream as content-free.
 
 The bridge speaks the standard the market already runs on: point any OTLP backend
 at Insika and a real turn shows up as a full trace, next to counters and histograms
@@ -80,6 +85,14 @@ backend config, no vendor file. It ships a stable set of attribute and instrumen
 names, and the recipes below tell you what to chart against them — in whatever you
 already run.
 
+### Blocked tool calls
+
+`tool_blocked` carries `name`, `gate`, and `param`, with task/session correlation
+in event metadata. It never carries the rejected value. The `insika.tool.blocked`
+counter (unit `{call}`) uses the turn's agent/tenant/command labels plus
+`insika.tool` and `insika.gate`. Session traces keep the `gate` field alongside the
+masked result; `insika tools:report` lists blocked calls separately from errors.
+
 ## Contents
 
 - [Turning it on](#turning-it-on-opt-in-parity-when-off)
@@ -143,14 +156,35 @@ knows its outcome.
 | `insika.turn.duration` | histogram | `s` | same, when both timestamps are known |
 | `insika.tokens` | counter | `{token}` | the turn reported usage |
 | `insika.cost` | counter | `{USD}` | the turn's model is priced (see below) |
+| `insika.tool.blocked` | counter | `{call}` | a `tool_blocked` gate refusal |
 | `insika.tool.calls` | counter | `{call}` | a tool call completes |
 | `insika.tool.duration` | histogram | `s` | a `tool_call`/`tool_result` pair completes |
+| `insika.cache.hit_rate` | histogram | `%` | a turn reported billed prompt tokens (see below) |
+| `insika.tool.loop_intervened` | counter | `{intervention}` | the loop detector delivered its one-shot warning |
+| `insika.context.compacted` | counter | `{compaction}` | an in-session compaction was persisted (RFC-0044) |
 
 `insika.tool.duration` is deliberately **not** recorded for data-tools: those are a
 single point-in-time event, so there is no measured duration to report. A tool left
 open by a mid-turn failure is not counted as a completed call either — its span is
 closed, but a failed call must not inflate the success histogram.
 
+`insika.cache.hit_rate` is the same arithmetic the Studio's per-agent series uses:
+cache **reads** over the whole **billed** prompt (fresh input + cache reads + cache
+writes), always in `[0,100]`. A turn with no billed prompt tokens records nothing —
+absence is not a 0% hit. It is recorded per turn on the terminal event, so it
+carries the turn labels (`insika.agent`, `insika.model`, …); the token-counter
+recipe below still works and answers the fleet-wide version of the question.
+
+`insika.tool.loop_intervened` counts deliveries of the loop detector's one
+warning per turn (see [Agents](AGENTS.md) `max_tool_repeat`), labelled with
+`insika.tool`. It counts interventions, not repeats: a turn contributes at most 1.
+
+`insika.context.compacted` counts persisted in-session compactions
+(`:context_compacted` — see [Context](CONTEXT.md)), labelled with
+`insika.agent` and `insika.model` (the summarizer's model, not the turn's). It
+fires post-turn, after the turn span already closed, so it deliberately rides
+its own labels rather than the open-turn set.
+
 ## Attribute reference
 
 The same names are used on spans and on metrics. **Metrics carry a deliberate
@@ -267,7 +301,17 @@ climbing while `input` stays flat.
 
 **Cache hit ratio**
 `insika.tokens` filtered to `insika.token.type="cached"` over the same counter
-filtered to `input`. This is the number that moves your bill.
+filtered to `input`. This is the number that moves your bill. For the per-turn
+distribution (does every turn hit, or do fleet averages hide cold agents?), chart
+`insika.cache.hit_rate` — p50 by `insika.agent`. Compare with that agent's baseline:
+cache eligibility, expiry and changing history affect the ratio. The
+[identity-prefix fingerprint](CONTEXT.md#the-observable-cache-fingerprints-and-the-invalidation-reason)
+explains identity/tool-schema changes; volatile category digests are separate.
+
+**Loop interventions**
+`insika.tool.loop_intervened`, rate, grouped by `insika.agent` and `insika.tool`.
+Any sustained non-zero rate means one tool keeps being retried with identical
+arguments — fix the tool's contract or the prompt, not the detector.
 
 **Spend per tenant**
 `insika.cost`, rate (or `increase` over a billing window), grouped by

data/docs/POLICY.md

@@ -18,17 +18,26 @@ matters, and editable hot.
 ## Layer 1: Tools (what it can call)
 
 `tools_allow` / `tools_deny` / `tools_allow_groups` decide which tools enter the
-turn's tool-loop, enforced by the tool-allowlist policy. See [Tools](TOOLS.md)
-for how tools are defined and registered, and [`examples/data-tool/`](https://github.com/guizaols/insika/tree/main/examples/data-tool/).
+turn's tool-loop, enforced by the builtin `tool_allowlist` policy — which the
+engine adds for you the moment any of the three is declared, so you never have to
+name it in `policies` (see [Agents](AGENTS.md#the-allowlist-convention)). See
+[Tools](TOOLS.md) for how tools are defined and registered, and
+[`examples/data-tool/`](https://github.com/guizaols/insika/tree/main/examples/data-tool/).
 
 ## Layer 2: Policies and approvals
 
-Policies are named entries evaluated before the turn runs. Builtins cover
-tool-, skill-, and workflow-allowlisting, plus **`ApprovalRequired`** — which
+Policies are named entries evaluated before the turn runs. **Only the policies a
+profile names run** — which is why `tool_allowlist` is added implicitly by a
+declared tool list; an allowlist nobody applies is worse than no allowlist.
+Builtins cover tool-, skill-, and workflow-allowlisting, plus
+**`ApprovalRequired`** — which
 does not allow or deny but *tags* a tool as needing human approval. Set
 `approvals_required: [tool names]`; the gate then fires when the model tries to
 call that tool, suspending the turn until an operator approves it in the Studio.
-See [Security](SECURITY.md#human-approval).
+A data tool's `requires_evidence` check runs before this approval gate; an unknown
+ID is blocked without asking the operator. See
+[Tools](TOOLS.md#provenance-checking-ids-before-a-write) and
+[Security](SECURITY.md#human-approval).
 
 ## Layer 3: Guardrails (content safety)
 

data/docs/RELEASING.md

@@ -19,6 +19,10 @@ is invisible to it. Do not publish on rspec alone.
 3. Every new `lib/` file is **tracked in git**. The gemspec's `files` come from
    `git ls-files`: an untracked file builds without a warning and the installed
    gem fails at `require` — this is exactly the failure this proof exists to catch.
+4. If changing the `fencing` default (currently off), first run the deployment's
+   golden cases with it enabled, retain the comparison report, and document the
+   behavior change in `CHANGELOG.md`. A default change needs evaluation evidence;
+   a scheduled version number alone is not the release gate.
 
 ## Cut the gem
 

data/docs/RUNNING-LOCAL.md

@@ -62,7 +62,7 @@ whole surface answers `503`, never open by omission.
 | `INSIKA_DB` | — (ephemeral memory) | SQLite path → config + execution survive a restart |
 | `BIND` | `http://localhost:9292` | host:port |
 | `ADMIN_TOKEN` | `local-demo` | token for `/studio` |
-| `OPENCLAW_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN` | Bearer for the whole `/v1` + `/a2a` surface |
+| `INSIKA_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN` | Bearer for the whole `/v1` + `/a2a` surface |
 | `DEEPSEEK_MODEL` | `deepseek-v4-flash` | model |
 
 With persistence:
@@ -128,7 +128,7 @@ Provision it (runs as a client against the live server; the internal token comes
 from the environment, never disk):
 
 ```bash
-INSIKA_URL=http://localhost:9292 OPENCLAW_GATEWAY_TOKEN=local-demo \
+INSIKA_URL=http://localhost:9292 INSIKA_GATEWAY_TOKEN=local-demo \
   bundle exec ruby scripts/import_pack.rb /path/to/pack
 ```
 

data/docs/SECURITY.md

@@ -27,7 +27,7 @@ The layers, from the edge inward:
 ## The Bearer gate
 
 The `/v1` and `/a2a` surface answers only with
-`Authorization: Bearer <OPENCLAW_GATEWAY_TOKEN>` (which falls back to `ADMIN_TOKEN`).
+`Authorization: Bearer <INSIKA_GATEWAY_TOKEN>` (which falls back to `ADMIN_TOKEN`).
 The check runs in the router, **before** any dispatch, against an **allowlist** of
 public routes — so a route added later is closed until someone deliberately publishes
 it. Only these answer without a token:
@@ -205,6 +205,32 @@ category: the agent's category reply → the agent's default → the builtin
 category → the builtin default. All of it is editable in the Studio Configuration
 form. See [Agents §Layer 3](POLICY.md#layer-3-guardrails-content-safety).
 
+## Third-party text is data (fencing)
+
+Input guardrails cover the incoming message. The opt-in `fencing` flag also
+sanitizes ordinary tool result strings, memory text and the injected knowledge
+names/descriptions, and places a
+fixed notice under the identity. It reduces known markup and Unicode tricks;
+it does not make arbitrary third-party instructions safe.
+
+The user/assistant-only extraction filter applies even when fencing is off.
+Attachment captions and `load_knowledge` bodies are not fenced. The extraction
+filter excludes direct tool messages,
+but assistant paraphrases can still become extraction input. See
+[Agents](AGENTS.md#fencing--third-party-text-is-data-never-instructions) for the
+exact scope, exceptions, default and size cap.
+
+## Write provenance and serial execution
+
+A data tool's `requires_evidence` gate checks IDs against the session ledger
+before approval or backend execution. A known ID proves a prior lookup; it does
+not authorize access or establish current stock, price or quantity limits.
+Those checks remain the backend's responsibility.
+
+Tools marked `side_effect` execute one at a time within a session, including in
+parallel batches. This is not a cross-session or distributed backend lock.
+See [Tools](TOOLS.md#provenance-checking-ids-before-a-write).
+
 ## Human approval
 
 Some tool calls should not happen unattended. Mark them with
@@ -242,7 +268,7 @@ defense-in-depth: without it, `ALLOW_PRIVATE` opens *any* private destination.
 > the request never leaves the process, and the conversation *looks* fine. Verify
 > tool health by the Studio session **trace** (a healthy call shows the backend's
 > `200`), never by the model's reply. Full detail in
-> [Tools §Egress](TOOLS.md#egress-the-ssrf-guard-and-its-silent-failure).
+> [Tools §Egress](TOOLS.md#egress-the-ssrf-guard).
 
 ## Sandbox: confined execution
 

data/docs/SOAK.md

@@ -88,7 +88,7 @@ insika soak --dry-run --envelope soak-envelope.md
 # every precondition, and nothing else
 insika soak --preflight --envelope soak-envelope.md
 
-# the run itself (INSIKA_URL + OPENCLAW_GATEWAY_TOKEN, like loadtest.rb)
+# the run itself (INSIKA_URL + INSIKA_GATEWAY_TOKEN, like loadtest.rb)
 INSIKA_URL=https://<target> insika soak --run --envelope soak-envelope.md --out soak-out/
 
 # resume after a short outage (the gap is recorded and counts against the window)

data/docs/TOOLS.md

@@ -12,10 +12,10 @@ 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
@@ -120,7 +120,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 +199,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 +224,63 @@ 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.
+
 ### Grounding: policing claims against the ledger
 
 With the ledger fed, the pack declares how claims are policed — data on the agent,
@@ -263,11 +310,63 @@ 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
+Three ways to write a data tool into the store — all **hot** (registry and catalog
 reload, no restart):
 
 1. **DSL** — `data_tool(name:, …)` in a `Insika.agent { … }` block.
@@ -275,8 +374,6 @@ reload, no restart):
 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
 
@@ -298,7 +395,7 @@ at turn time, not ingestion).
 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.
 
@@ -405,9 +502,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 +532,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 +544,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 +562,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.
 
@@ -485,6 +577,32 @@ and gets the URL back; the tenant is bound from the turn, never a parameter the
 model types. See [Artifacts](ARTIFACTS.md) for the tool contract, the serving
 routes, the signed link and the retention/LGPD reach.
 
+## The usage report — `insika tools:report`
+
+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 four shapes:
+
+- **`never_called`** — in `tools_allow`, zero calls in any stored trace. Dead
+  weight: its schema ships on every request and buys nothing.
+- **`error_rate`** — over 30% conventional errors (the trace's `ok` flag) inside
+  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
+insika tools:report --agent store-support  # one agent
+insika tools:report --days 30 --json       # wider window, machine-readable
+```
+
+Read-only by design: the report names candidates, the **operator** removes — a
+flagged tool may still be the one a rare but critical flow needs. Counts are
+"at least", never exact: the trace keeps a capped tail per session.
+
 ## See also
 
 - [Agents](AGENTS.md) — allowlists, groups, and per-agent tool exposure.