insika 0.2.0 → 0.7.0

data/docs/ARTIFACTS.md

@@ -0,0 +1,95 @@
+---
+title: Artifacts
+parent: Operate
+nav_order: 3
+permalink: /artifacts/
+---
+
+# Artifacts — a report the agent can hand you a URL to
+
+A channel message is ephemeral, unformatted and capped. A scheduled report turn
+(see [Schedules](SCHEDULING.md)) produces something no message can carry: a page
+— tables, sections, inline charts. An **artifact** is that page as a thing that
+exists afterwards: listable, linkable, and — because it carries customer PII —
+deletable on the same terms as everything else the engine stores.
+
+Deliberately small: a store, a tool, a route. Not a CMS.
+
+## The `save_artifact` tool
+
+A registry tool, allowlisted per agent like every tool — **the allowlist IS the
+switch**:
+
+```ruby
+agent = Insika.agent("reporter") do
+  instructions "…"
+  tools_allow %w[save_artifact]   # without this, the tool is not even offered
+end
+```
+
+The agent hands in `title` + `content` (default mime `text/html`; also
+`text/markdown` and `image/svg+xml`) and gets the URL back, which it can include
+in a channel message ("today's report: <url>"). When a signing key is
+configured (below), the result also carries a `signed_url` that expires.
+
+```jsonc
+{ "id": "…", "url": "https://…/studio/artifacts/<id>/content",
+  "signed_url": "https://…/studio/artifacts/s/<id>?exp=…&sig=…" }   // only with a key
+```
+
+The tenant binding is **inherited, never chosen**: an artifact belongs to the
+tenant of the agent that saved it — a binding of the tool instance, never a
+parameter the model types. Store A's report can never appear in, or be linked
+from, store B.
+
+## Serving
+
+- `GET /studio/artifacts` — the Studio's per-agent list (the listing IS the
+  history; no versioning — one report per run).
+- `GET /studio/artifacts/:id` — the preview page, rendered **inside a sandboxed
+  iframe** (no scripts, no same-origin, no forms).
+- `GET /studio/artifacts/:id/content` — the raw page (authenticated).
+- `GET /studio/artifacts/s/:id?exp=…&sig=…` — the **signed link**: the only
+  artifact route that works without a Studio session. HMAC-SHA256 over
+  `(id, expiry)` with `INSIKA_ARTIFACT_SIGNING_KEY`, verified in constant time.
+  Expired or bad signatures **404 (never 403 — no oracle)**. Rotating the key
+  invalidates every outstanding link — the documented behavior, not a bug.
+  Without `INSIKA_ARTIFACT_SIGNING_KEY` there is no signed surface at all.
+
+**Artifact content is untrusted.** It is LLM output. Both content routes send:
+
+```http
+Content-Security-Policy: default-src 'none'; style-src 'unsafe-inline'; img-src data:
+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.
+
+## Limits and retention
+
+- **Size cap** — `INSIKA_ARTIFACT_MAX_BYTES` (default 1 MB): an artifact is a
+  page, not an attachment. The mime allowlist is `text/html`, `text/markdown`,
+  `image/svg+xml`; no binaries, no uploads.
+- **Expiry** — the settings key `artifact_ttl_days` (Integer days; absent = OFF)
+  ages artifacts out on the retention sweep's own daily pass, **independent of
+  `retention_days`**: a deployment that keeps its conversations forever must
+  still expire the reports. This is the guarantee that PII inside a report
+  expires — the honest reach, because no reader can see inside the opaque HTML.
+
+## Privacy
+
+- `delete_tenant_data` deletes the tenant's artifacts (the tenant binding is
+  the isolation boundary).
+- `forget_customer` **cannot** know which artifacts mention a customer (content
+  is opaque HTML), so per-customer redaction inside a report is not pretended to
+  exist; the `artifact_ttl_days` knob is the guarantee that a report's PII
+  expires.
+
+## See also
+
+- [Schedules](SCHEDULING.md) — the recurring turns whose output lands here.
+- [Tools](TOOLS.md) — how a tool enters the per-agent allowlist.
+- [`examples/scheduled-report/`](https://github.com/guizaols/insika/tree/main/examples/scheduled-report/)
+  — schedule + skill + data tool + artifact, tenant-bound, end to end.

data/docs/BENCHMARK.md

@@ -1,7 +1,7 @@
 ---
 title: Benchmark
-parent: Operate & prove it
-nav_order: 2
+parent: Operate
+nav_order: 6
 permalink: /benchmark/
 ---
 

data/docs/CHANNELS.md

@@ -1,7 +1,7 @@
 ---
 title: Channels
-parent: Build an agent
-nav_order: 6
+parent: Integrate
+nav_order: 2
 permalink: /channels/
 ---
 
@@ -176,21 +176,24 @@ again.
 ## Relay or the drop-in API?
 
 If you already own your messaging platform, you can reach the engine two ways: the
-drop-in [`POST /v1/responses`](/architecture/) — you hold an SSE connection for the
+drop-in [`POST /v1/responses`](ARCHITECTURE.md) — you hold an SSE connection for the
 whole turn and read the answer off it — or the relay, where the engine acks in
 milliseconds and POSTs the answer to you when it exists.
 
 The instinct is that streaming gets the customer their reply sooner, and that the
-relay trades that away. **It does not, and the reason is structural:** the engine
-publishes `:content` as the ANSWER, whole, after the turn's hooks
-([what crosses the edge](/architecture/#what-crosses-the-edge)). During the turn the
-stream carries tool activity; the text arrives in one piece at the end. Measured on
-a real store agent, the text frames span **0 ms** — there is nothing to deliver
-progressively, on either path.
+relay trades that away. **For the default relay it does not, and the reason is
+structural:** the engine publishes `:content` as the ANSWER, whole, after the
+turn's hooks ([what crosses the edge](ARCHITECTURE.md#what-crosses-the-edge)).
+During the turn the stream carries tool activity; the text arrives in one piece at
+the end. Measured on a real store agent, the text frames span **0 ms** — there is
+nothing to deliver progressively. That is the `:at_end` fact, true of `/v1/responses`
+and of a relay that never opted into [progressive delivery](#delivery-policy).
+The relay can opt out of it per channel — the opt-in is below, and it is the one
+thing that changes the 0 ms span.
 
 |  | drop-in `/v1/responses` | relay |
 |---|---|---|
-| What the customer receives | one message, at the end | one message, at the end |
+| What the customer receives | one message, at the end | one message at the end (`:at_end`), or one WhatsApp balloon per paragraph with the first one as soon as the answer exists (`delivery: :progressive`) |
 | Your app's request | held open for the whole turn (seconds) | acked in **milliseconds** |
 | A turn that outlives your HTTP timeout | your problem | already handled — the answer arrives later |
 | Retry on a failed handover | yours to build | the engine's outbox, bounded, at-most-once |
@@ -201,7 +204,7 @@ That last row is the one that cannot be had the other way. `/v1/responses` answe
 the request it was given, so a message that arrives while a turn is running is a
 second turn — the engine has no way to tell you "this joined the previous one". The
 relay's `merged` / `steered` acks exist precisely to say that, which is why
-[the inbound queue](/agents/#queue_mode--when-a-message-arrives-while-the-agent-is-busy)
+[the inbound queue](AGENTS.md#queue_mode--when-a-message-arrives-while-the-agent-is-busy)
 is only reachable from here.
 
 **Measured, so you can judge it rather than take our word:** same agent, same
@@ -279,18 +282,20 @@ answers, and **they are four different facts**:
 answer two or three times.** That is the one contract mistake that is visible to
 the end user, so it is worth a line of code: only deliver for a `202`.
 
-`merged` and `steered` come from the [inbound queue](/agents/#queue_mode--when-a-message-arrives-while-the-agent-is-busy)
+`merged` and `steered` come from the [inbound queue](AGENTS.md#queue_mode--when-a-message-arrives-while-the-agent-is-busy)
 (`limits[:queue_mode]`). They only ever occur if you turned that on for the agent;
 with the default `followup` you will only see `202` and `duplicate`.
 
 ### Outbound
 
-One POST per reply, to the URL you configured:
+One POST per **balloon**, to the URL you configured. For the default `:at_end`
+delivery a turn emits exactly one; a progressive turn may emit several — `task_id`
+is the correlation, `index` is the order.
 
 ```jsonc
 POST <INSIKA_RELAY_DELIVER_URL>
 Authorization: Bearer <INSIKA_RELAY_DELIVER_TOKEN>   // omitted if unset
-X-Insika-Delivery: 0f2c…                              // stable idempotency key
+X-Insika-Delivery: 0f2c…                              // stable idempotency key, PER balloon
 Content-Type: application/json
 
 {
@@ -307,9 +312,49 @@ short backoff, and then the delivery is marked `failed` and stops.
 `content` is the turn's **answer** — one message, whole. The model's narration on
 the way to an answer ("vou verificar o cardápio…") does not come through here; it
 stays internal unless the agent opts in. That contract is
-[the edge contract](/architecture/#what-crosses-the-edge), and it is why you can
+[the edge contract](ARCHITECTURE.md#what-crosses-the-edge), and it is why you can
 forward `content` straight to the customer.
 
+### Delivery policy
+
+A relay declares **how the outbox flushes** — a property of the surface
+(WhatsApp balloons), not of the model:
+
+- **`:at_end`** (the default, also `INSIKA_RELAY_DELIVERY=at_end` or unset): one
+  POST at the end with the whole answer. Byte-identical to the contract above.
+- **`:progressive`** (`INSIKA_RELAY_DELIVERY=progressive`): the answer is split
+  into balloons at paragraph boundaries (a soft 600-char cap splits a single long
+  paragraph on sentences; fenced code blocks are atomic), and each balloon is its
+  own POST, in order, starting as soon as the answer exists. The consumer sends
+  each POST as its own platform message.
+
+A progressive POST carries two additive fields **only when the turn split into
+more than one balloon** — a one-balloon progressive turn is indistinguishable
+from `:at_end` on the wire:
+
+```jsonc
+{
+  "external_id": "5511999998888",
+  "session_id":  "relay:5511999998888",
+  "task_id":     "…",
+  "content":     "Seu pedido saiu para entrega hoje",
+  "index":       0,          // this balloon's position, 0-based
+  "final":       false       // true on the LAST balloon of this task_id
+}
+```
+
+When `index`/`final` are present, this POST is **one balloon of several for the
+same `task_id`** — forward `content` as its own platform message and honor
+`X-Insika-Delivery` per balloon. If you only forward `content` and ignore the new
+fields, progressive turns still read as N messages in arrival order (which is
+index order — the engine dispatches the chain sequentially); single-balloon turns
+behave exactly as before. A consumer that ignores unknown keys keeps working.
+
+The engine measures the win in-process: every channel turn records
+`first_balloon_ms` (inbound receipt → first outbox flush) on the task record and
+the terminal event, so the Studio task page shows whether the 2 s target is being
+hit without toggling any flag.
+
 ### Deduplication
 
 Send `event_id` and a retried webhook costs you nothing: the engine recognizes the
@@ -334,7 +379,7 @@ your side: you already have the customer's conversation, and `GET /v1/tasks/:id`
 tells you the turn's terminal state.
 
 A turn that **failed** delivers nothing — an error string is not an answer. Watch
-`GET /v1/tasks/:id` or the [event stream](/observability/) for those.
+`GET /v1/tasks/:id` or the [event stream](OBSERVABILITY.md) for those.
 
 ## Setting up the relay
 
@@ -344,6 +389,7 @@ Three environment variables on the engine:
 INSIKA_RELAY_TOKEN=<a long random secret>       # the switch AND the credential
 INSIKA_RELAY_DELIVER_URL=https://you.example/insika/deliver
 INSIKA_RELAY_DELIVER_TOKEN=<another secret>     # optional; what we send to you
+INSIKA_RELAY_DELIVERY=progressive               # optional; "at_end" (the default) = one POST
 ```
 
 `INSIKA_RELAY_TOKEN` is the switch: without it the channel is not mounted and
@@ -351,7 +397,7 @@ INSIKA_RELAY_DELIVER_TOKEN=<another secret>     # optional; what we send to you
 without a credential — a public inbound route with an LLM behind it is a money
 faucet, so it fails closed by construction.
 
-The delivery POST goes through the same [egress guard](/security/#egress-the-ssrf-boundary) as
+The delivery POST goes through the same [egress guard](SECURITY.md#egress-the-ssrf-boundary) as
 data-tools: **https only**, and private/loopback destinations blocked. For local
 development, where your consumer is on `localhost`:
 
@@ -367,6 +413,50 @@ nothing at all).
 A runnable consumer in ~40 lines lives in
 [`examples/relay-channel/`](https://github.com/guizaols/insika/tree/main/examples/relay-channel).
 
+## Shadow mode
+
+Shadow mode lets one channel run every turn **end to end and deliver
+nothing** — the experiment that answers "can we replace the incumbent?" before
+any customer is handed over. The incumbent keeps answering; the engine records
+what it *would* have answered, and the two replies are judged pairwise against a
+**frozen criterion** — the file `INSIKA_PARITY_CRITERION` points at.
+
+```bash
+INSIKA_RELAY_SHADOW=1    # the switch
+# INSIKA_PARITY_CRITERION — required in shadow mode
+```
+
+Three things change when it is on:
+
+- The turn still runs; the reply is recorded as a **pair** and never reaches the
+  customer. Zero outbox records, ever — and `Relay#deliver` refuses loudly if one
+  somehow exists.
+- The inbound ack becomes `200 {"task_id": …, "shadow": true}` instead of `202`,
+  so a consumer wired to "202 means a reply is coming" cannot be misled.
+- `event_id` becomes **required** — it is the correlation key both halves of the
+  pair are built from.
+
+The incumbent's reply enters the same pair through one of two shapes: alongside
+the mirror call itself (`"incumbent_reply": "…"` on `POST /channels/relay/events`),
+or as a follow-up when the consumer answers first:
+
+```jsonc
+POST /channels/relay/shadow-reply
+Authorization: Bearer <INSIKA_RELAY_TOKEN>
+{ "external_id": "5511999998888", "event_id": "wamid.HBg…",
+  "reply": "Claro! Me passa o número do pedido?", "at": "2026-…Z" }
+→ 202 { "pair_id": "9f2c…", "status": "open" }
+```
+
+Both shapes land in one command; a retried reply is ignored (first write wins —
+the customer received one reply, and a retry must not rewrite evidence).
+
+**No criterion, no shadow.** Boot refuses when shadow is on and
+the criterion file is missing or unparseable — a number nobody pre-registered
+does not count. The Studio's Parity page folds the running verdict on demand
+from the pair store; `insika doctor` reports the shadow configuration before
+boot does.
+
 ## Sessions
 
 The engine mints the session id: `relay:<your external_id>`. Namespacing is not
@@ -380,7 +470,7 @@ redirect its own conversation.
 ## Writing your own channel
 
 A channel is a plain object — no base class. Register it from a plugin
-(see [Plugins](/plugins/)) with `contracts: { channels: [<id>] }` in the manifest,
+(see [Plugins](PLUGINS.md)) with `contracts: { channels: [<id>] }` in the manifest,
 and it mounts under `/channels/<id>/`.
 
 Two members are always there; the rest of the object decides which shape you get.
@@ -446,8 +536,8 @@ command carries `transport: "channel:<id>"`.
 
 ## See also
 
-- [Security](/security/) — the tokens, the egress guard, and why the rate limit
+- [Security](SECURITY.md) — the tokens, the egress guard, and why the rate limit
   matters for anything public.
-- [Agents](/agents/) — `limits[:queue_mode]`, which is what produces `merged` and
+- [Agents](AGENTS.md) — `limits[:queue_mode]`, which is what produces `merged` and
   `steered`.
-- [Observability](/observability/) — the event stream and OpenTelemetry.
+- [Observability](OBSERVABILITY.md) — the event stream and OpenTelemetry.

data/docs/CONTEXT.md

@@ -1,7 +1,7 @@
 ---
 title: Context
-parent: Build an agent
-nav_order: 4
+parent: Core concepts
+nav_order: 5
 permalink: /context/
 ---
 
@@ -20,26 +20,30 @@ Providers are chosen by a double gate (the provider opts in for the profile **an
 the agent's `context_providers` allowlist permits it), then assembled by priority
 into a deterministic prompt:
 
-| Provider | Block | Priority | Notes |
-|----------|-------|:--------:|-------|
-| **Identity** | system | **100 — pinned** | The agent's prompt files (global system files first). Never cut. |
-| **Skill trigger** | `<active_skill>` | 85 | Level-2 bodies: the agent's `skills_eager` set, plus the ones whose `triggers:` match the message — see [Skills](SKILLS.md). |
-| **Skills** | `<available_skills>` | 80 | Level-1 skill list, minus whatever is already eager — see [Skills](SKILLS.md). |
-| **Memory** | `<memory>` | 75 | Durable facts + recent notes, only if `memory` is on. Cuttable. |
-| **Tool search** | `<available_tools>` | 70 | Level-1 list of deferred tools — see [Tools](TOOLS.md). |
-| **Session** | history | 60–79 | The running transcript; priority scales with recency. |
-| **Request** | `<request_context>` | 40 | Turn variables + tenant. Most cuttable; sits last. |
-
-The ordering is deliberate: the **stable identity sits first**, the **volatile
-request context sits last**. That keeps the cacheable prefix byte-stable (see the
-prefix cache below).
+| Provider | Block | Priority | Layer | Notes |
+|----------|-------|:--------:|-------|-------|
+| **Identity** | system | **100 — pinned** | identity | The agent's prompt files (global system files first). Never cut. |
+| **Skills** | `<available_skills>` | 80 | identity | Level-1 skill list, minus whatever is already eager — see [Skills](SKILLS.md). |
+| **Tool search** | `<available_tools>` | 70 | identity | Level-1 list of deferred tools — see [Tools](TOOLS.md). |
+| **Skill trigger** | `<active_skill>` | 85 | volatile | Level-2 bodies: the agent's `skills_eager` set, plus the ones whose `triggers:` match the message — see [Skills](SKILLS.md). |
+| **Knowledge** | `<knowledge>` | 77 | volatile | Level-1 top-K learned concepts for the turn's message (+ one-hop `[[links]]`), only if `knowledge.retrieve` is on. Cuttable — see [Knowledge](KNOWLEDGE.md). |
+| **Memory** | `<memory>` | 75 | volatile | Durable facts + recent notes, only if `memory` is on. Cuttable. |
+| **Briefing** | `<briefing>` | 65 | volatile | The session's working state (known fields, still-missing list, next step) — only if the pack declared `briefing_fields`. Cuttable. |
+| **Session** | history | 60–79 | volatile | The running transcript; priority scales with recency. |
+| **Request** | `<request_context>` | 40 | volatile | Turn variables + tenant. Most cuttable; sits last. |
+
+The ordering is deliberate: the render order is **identity layer first, volatile
+layer after** — nothing volatile can sit above the cache boundary, whatever its
+priority — and within each layer the priority sort above holds. That keeps the
+cacheable prefix byte-stable (see the prefix cache below).
 
 ## Budget and eviction — the actual "compaction"
 
 - The cap is `profile.limits[:context_budget]`, **default 8000 tokens**.
 - To fit the budget, the builder cuts **non-pinned** fragments
   lowest-priority-first (ties broken by oldest history first). Under pressure you
-  lose old history, then the memory block, then request context — **the pinned
+  lose request context first, then old history, then briefing, then memory, then
+  learned knowledge, then the skill/tool-search level-1 lists — **the pinned
   identity is never truncated**.
 - A **pinned** fragment (the identity) that *alone* exceeds the budget raises an
   error — the turn fails rather than shipping a truncated identity.
@@ -78,19 +82,82 @@ budget first.
 With `memory` enabled, an agent gains a built-in `remember` tool for durable
 facts, and those facts (plus recent notes) are injected back into the prompt on
 later turns — **including turns in a different session**. Memory is scoped per
-agent. This is distinct from *session history*, which is the transcript of one
+agent, per `(tenant, customer)` when the message carries a `customer`, and per
+session otherwise — a session's own memory lives in a marked `memory:chat:<session id>`
+cell, never a bare one, so the Customers drill cannot read a conversation as a
+customer. This is distinct from *session history*, which is the transcript of one
 conversation; memory is the small set of facts that should outlive any single
 conversation. Facts and notes are editable from the Studio agent page. See
 [`examples/memory/`](https://github.com/guizaols/insika/tree/main/examples/memory/) for a runnable cross-session example.
 
+Facts carry **provenance metadata**: every fact record stores `origin`
+(who wrote it — `"engine"`, `"operator"`, `"legacy"` or `"distilled"`),
+`created_at` / `updated_at` timestamps, and an optional `expires_at` (ISO8601) —
+**an expired fact is never injected**, even before the daily sweep prunes it. The
+Studio Customers drill reads and edits the same cell the next turn reads (injection
+unchanged), and every operator mutation lands in the content-free audit trail
+(digests, never values). The sweep honors the `memory_ttl_days` setting on its own
+knob — see [Security](SECURITY.md#memory-and-the-right-to-be-forgotten-lgpd).
+
+An **approved distilled fact** (see [Facts](FACTS.md)) lands in the
+same cell this provider injects, stamped `distilled:<session_ref>` — approved on
+the Studio Facts page, never applied automatically.
+
+## Briefing — the session's working state
+
+The **briefing** is the per-conversation working state the agent keeps and asks
+for: which facts it already learned (size, budget, delivery day) and the agreed
+next step. It is **engine-owned data** — one `"briefing"` key on the session
+record, written only by the agent through tools — whose *fields* come from the
+pack:
+
+```jsonc
+// pack agent.config.json
+{ "id": "store-support", "briefing_fields": ["size", "budget", "delivery_day"] }
+```
+
+```ruby
+# or the DSL — [] = the feature is off (no block, no tools)
+briefing_fields "size", "budget", "delivery_day"
+```
+
+With fields declared, the turn's `:system` context gains a `<briefing>` block
+(priority 65 — below identity/skill/memory so it never breaks the cacheable
+prefix, above the turn's own `<request_context>`):
+
+```
+<briefing>
+known:
+  size: M
+still missing: budget, delivery_day
+next step: send the payment link tomorrow at 10
+</briefing>
+```
+
+The `still missing` list is the point: the *model* sees which declared fields are
+still unanswered, so it stops re-asking for something already given. Stored keys
+that the pack no longer declares are never rendered. The Studio session screen
+shows the persisted state (known fields + next step), read-only.
+
+The agent writes the briefing through two built-in tools, wired only when the
+pack declared fields:
+
+- `update_briefing(field:, value:)` — records a field. An undeclared `field`
+  returns an envelope error (`unknown field '…'; declared: …`) and nothing is
+  persisted; a blank `value` clears the field.
+- `set_next_step(text:)` — records the agreed next step; a blank `text` clears it.
+
+Both are deterministic in-process writes (never enveloped) and survive across
+turns and resumes — a resumed conversation re-opens with the briefing intact.
+
 ## The provider prefix cache
 
 Two distinct caching mechanisms — don't conflate them:
 
 - **Automatic server-side prefix cache.** Some providers prefix-cache a stable
   system prefix automatically, at no cost to configure. This works **only because**
-  the identity is at the top of the system block and the volatile
-  `<request_context>` is at the bottom, keeping the cacheable prefix byte-stable.
+  the engine renders the system in two layers (below) and the volatile half sits
+  **under** the identity boundary, keeping the cacheable prefix byte-stable.
   Anything that injects volatile content high in the system block breaks the cache.
 - **Manual cache breakpoints (opt-in).** With `prompt_caching` on **and** a
   provider that supports explicit cache control, the builder sets one cache
@@ -100,6 +167,52 @@ Two distinct caching mechanisms — don't conflate them:
 Cache accounting surfaces as `cached_tokens` (reads) and `cache_creation_tokens`
 (writes), visible in telemetry and the Studio tokens chip.
 
+### The two layers
+
+The system block is partitioned into two cache layers:
+
+- **Identity** — bytes that change only on deploy/config edit: the persona
+  prompt (`Prompt`), the level-1 skill list (`Skill`) and the deferred-tool
+  catalog (`ToolSearch`). This is the cacheable prefix.
+- **Volatile** — bytes that may change per turn: memory, session history,
+  triggered skill bodies, the `<request_context>`. Everything else.
+
+The layer is a **provider-class contract**, not profile data: `ContextProvider`
+declares `def layer = :volatile` (conservative — nothing gets pinned by
+accident) and the three identity builtins override to `:identity`. A pack does
+not set it — a pack reorganizes *which content goes into the Prompt provider vs
+the volatile providers*. The Builder stamps the layer on every fragment at
+production, and the render order is **identity first, volatile after** — a
+volatile block can never land above the cache boundary, whatever its priority.
+Within each partition the existing priority sort is untouched.
+
+The engine's own `doctor` check verifies the declaration: an engine-known
+volatile provider (Memory, Session, Request, SkillTrigger) that overrides to
+`:identity` is an **error** (guaranteed cache kill); any other custom
+`:identity` provider is a **warning** (purity unverifiable from outside — the
+output must be byte-stable across turns).
+
+### The observable cache: fingerprints and the invalidation reason
+
+Each turn, the Executor hashes the rendered prefix into a PII-free fingerprint
+chain — one SHA-256 per system category in render order, one for the tool
+schemas, one cumulative `prefix` — and compares it against the previous turn's
+entry. The **invalidation reason** is the first category whose bytes changed (or
+vanished); a turn whose prefix held reports nothing. History is deliberately
+excluded: a new user message is a divergence every turn, which would be noise,
+not a reason.
+
+The Studio surfaces it in two places: the **session Context card** shows the
+turn's cache-hit percentage and the `broke: <category>` line (plus the
+`identity` marker on the category rows), and the **agent detail** carries a
+cache tab with the per-agent hit series over time. The per-agent series lives
+in its own capped store, because a session does not stamp its author — the
+per-session trace cannot answer "cache-hit over time for *this* agent".
+
+With the prefix stable by construction, the existing `prompt_caching` breakpoint
+sits on bytes that stay put — the first (write) turn of a deployment pays the
+cache write once, every subsequent turn reads.
+
 ## The volume
 
 Agents, prompts, skills, and tools are **data in SQLite**, not files on a volume.

data/docs/DEMO.md

@@ -0,0 +1,80 @@
+---
+title: Demo data
+parent: Start here
+nav_order: 4
+permalink: /demo/
+---
+
+# Demo data — see every loop working at once
+
+Most of what makes Insika worth looking at only shows up after data has
+accumulated: a [funnel](OUTCOMES.md#the-outcome-funnel) with a frozen
+baseline needs weeks of folded outcomes, a [refinement](REFINEMENT.md)
+proposal needs a run that actually found something, an
+[approval](POLICY.md#layer-2-policies-and-approvals) needs a tool call
+someone is waiting on. A fresh instance shows none of that — every one of
+those pages renders its empty state, which makes it hard to tell "nothing
+happened yet" from "this doesn't work."
+
+`insika demo:seed` closes that gap in one shot: it provisions a single
+fictional agent (`demo-store`, an e-commerce support bot) and writes enough
+realistic-looking data to see every loop at once.
+
+## What it creates
+
+| Page | What you'll see |
+|------|------------------|
+| [Funnel](OUTCOMES.md#the-outcome-funnel) — `/studio/funnel?agent=demo-store` | 40 days of folded outcomes (`greeted → browsing → cart_started → checkout_started → purchased`) and a **frozen baseline** |
+| [Follow-ups](OUTCOMES.md#follow-ups--the-seller-who-comes-back) — `/studio/followups?agent=demo-store` | one record in each state: `pending`, `fired` (one per arm, so the A/B card has something to compare), `cancelled`, `blocked` |
+| [Refinement](REFINEMENT.md) — `/studio/refinement?agent=demo-store` | four runs across the lifecycle: `awaiting_approval`, `applied`, `rejected` (gate failed), `no_findings` |
+| [Approvals](POLICY.md#layer-2-policies-and-approvals) — `/studio/approvals` | two pending tool calls waiting on a human, one already resolved |
+| [Facts](FACTS.md) — `/studio/facts` | three distillation proposals (`pending`, `approved` — with the resulting memory fact, `rejected`) |
+| [Evals](EVALS.md) — `/studio/evals?agent=demo-store` | six golden cases and a baseline run with a mix of passes and one failure |
+
+Every record is written through the same store APIs a real turn would use
+(`OutcomeStore#create` + the funnel fold, `FollowupStore#create` + its
+transitions, and so on) — there is no bulk-insert shortcut, and no bundled
+`.rb` script outside `lib/` (nothing here needs a checkout; it ships in the
+gem).
+
+## Running it
+
+From the CLI, against whichever store the rest of your commands already use
+([Running locally](RUNNING-LOCAL.md#variables-all-optional) — `INSIKA_DB`
+unset means an ephemeral, in-memory store, which is a fine place to try this):
+
+```bash
+insika demo:seed
+```
+
+A second run is a safe no-op once `demo-store` exists; pass `--force` to seed
+another batch on top (the funnel baseline recomputes cleanly, but follow-ups,
+refinement runs, approvals, proposals and goldens accumulate rather than
+reset — none of those stores expose a per-agent bulk-delete that a shared
+"platform" tenant could call without risking another agent's data).
+
+From the Studio, open **Settings → Demo data** and click **Seed demo data**.
+It dispatches the exact same command the CLI runs — the Studio never writes a
+store directly, here or anywhere else.
+
+**This writes into whatever store the running instance already has open.**
+There's no separate demo database and no isolation: point `INSIKA_DB` at a
+scratch file (or leave it unset, for an ephemeral store) before seeding —
+never at a deployment holding real tenant data.
+
+## Then look around
+
+Once seeded, the CLI prints the same six paths listed above. If Studio isn't
+running yet, boot it the way you already do — see [Running
+locally](RUNNING-LOCAL.md#boot) for a checkout, or [Embedding](EMBEDDING.md)
+for `Insika.agent { … }.serve` — pointed at the same `INSIKA_DB`. Studio reads
+every agent's profile from the same config store, so it will show
+`demo-store` next to whatever agent you're actually building, no matter which
+one the running process itself defines.
+
+## See also
+
+- [Refinement](REFINEMENT.md), [Facts](FACTS.md), [Evals](EVALS.md) — what
+  each seeded page actually means.
+- [Running locally](RUNNING-LOCAL.md) — booting Studio against a durable
+  `INSIKA_DB`.