insika 0.3.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,14 +176,14 @@ 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. **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/#what-crosses-the-edge)).
+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`
@@ -204,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
@@ -282,7 +282,7 @@ 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`.
 
@@ -312,7 +312,7 @@ 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
@@ -379,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
 
@@ -397,7 +397,7 @@ INSIKA_RELAY_DELIVERY=progressive               # optional; "at_end" (the defaul
 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`:
 
@@ -415,7 +415,7 @@ A runnable consumer in ~40 lines lives in
 
 ## Shadow mode
 
-Shadow mode (RFC-0025) lets one channel run every turn **end to end and deliver
+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
@@ -470,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.
@@ -536,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/
 ---
 
@@ -26,6 +26,7 @@ into a deterministic prompt:
 | **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. |
@@ -41,7 +42,8 @@ cacheable prefix byte-stable (see the prefix cache below).
 - 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.
@@ -88,16 +90,16 @@ 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** (RFC-0031): every fact record stores `origin`
+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-rfc-0031).
+knob — see [Security](SECURITY.md#memory-and-the-right-to-be-forgotten-lgpd).
 
-An **approved distilled fact** (RFC-0034 — see [Facts](FACTS.md)) lands in the
+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.
 
@@ -165,7 +167,7 @@ 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 (RFC-0030)
+### The two layers
 
 The system block is partitioned into two cache layers:
 

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`.

data/docs/DEPLOY.md

@@ -57,7 +57,14 @@ contract:
    worker that holds the session's actor. The engine does **not** promise them
    across workers. A deploy that needs those semantics for a session must route
    that session's traffic to one worker (sticky routing) — or accept per-worker
-   best-effort.
+   best-effort. **On Railway there is no sticky-routing option at any layer** —
+   confirmed against Railway's own docs, which distribute traffic randomly and
+   explicitly do not support sticky sessions — so N>1 there is not "per-worker
+   best-effort," it is a guaranteed cross-session leak the first time two
+   requests for the same session land on different workers. See the Railway
+   section below; `insika doctor` errors on `WEB_CONCURRENCY>1` there — unless
+   [`insika-router`](ROUTER.md), the session-sticky proxy, is in front,
+   which is what makes N>1 safe on Railway too (N local workers behind it).
 3. **Recovery is part of boot, in every wiring.** Every worker boots through
    `Server::Boot`, which runs recovery **before the listen**. The per-record
    sweeps (undelivered outbox records, undelivered delegation results) run in
@@ -118,7 +125,7 @@ this section is the single source of truth for what changing it means.
 | `INSIKA_RELAY_TOKEN` | — | **mounts the relay channel** at `POST /channels/relay/events`, and is the Bearer it requires. Empty = the route does not exist (`404`). See [Channels](CHANNELS.md) |
 | `INSIKA_RELAY_DELIVER_URL` | — | your callback; the engine POSTs each reply there. Goes through the egress guard |
 | `INSIKA_RELAY_DELIVER_TOKEN` | — | Bearer the engine sends **to** your callback (optional) |
-| `INSIKA_RELAY_DELIVERY` | `at_end` | how the relay flushes the outbox: `at_end` (one POST) or `progressive` (one POST per balloon — [RFC-0027](CHANNELS.md#delivery-policy)) |
+| `INSIKA_RELAY_DELIVERY` | `at_end` | how the relay flushes the outbox: `at_end` (one POST) or `progressive` (one POST per balloon — [delivery policy](CHANNELS.md#delivery-policy)) |
 | `INSIKA_WIDGET_ORIGINS` | — | exact-match origins allowed to embed the [web widget](CHANNELS.md#the-web-widget), comma-separated. No wildcards. **Half the switch**: with `INSIKA_WIDGET_AGENTS` unset, nothing is mounted (`404`) |
 | `INSIKA_WIDGET_AGENTS` | — | agent ids a widget visitor may address, comma-separated. The other half of the switch. **A chat rate limit is also required** or the widget answers `503` |
 | `LITESTREAM_REPLICA_URL` | — | **enables Litestream** (backup/DR). Empty = disabled (default). See below |
@@ -221,11 +228,64 @@ healthcheck, and a restart policy.
    without a volume, SQLite is ephemeral and recovery resumes nothing after a
    redeploy.
 3. **Vars**: `DEEPSEEK_API_KEY`, `OPENCLAW_GATEWAY_TOKEN`, `CONSUMER_INTERNAL_URL`,
-   `INSIKA_EGRESS_HOSTS` (and `WEB_CONCURRENCY` to match your plan/CPU).
+   `INSIKA_EGRESS_HOSTS`. **Leave `WEB_CONCURRENCY` at its default of 1** unless
+   you run [`insika-router`](ROUTER.md) in front. Railway's own docs say it
+   "does not support sticky sessions" and randomly distributes traffic across
+   replicas/workers — there is no way on this platform to satisfy the "sticky
+   routing per session in front" precondition item 2 of the process model
+   requires, at any layer (Railway replicas or Falcon's own `--count` workers
+   within one container). Raising `WEB_CONCURRENCY` without a router in front
+   is not a throughput knob, it is a guaranteed way to leak a reply across
+   sessions the first time two requests for the same session land on different
+   workers — `insika doctor` errors on this combination for exactly that
+   reason. `insika-router` is the fix: N local Falcon workers
+   behind one sticky proxy, still one Railway replica.
 4. The healthcheck hits `/up`.
 5. Point your consumer at the service's public URL, with a matching API token
    (see [RUNNING-LOCAL.md](RUNNING-LOCAL.md)).
 
+## Kubernetes
+
+Same contract as Railway, for the same reason, verified against
+ingress-nginx's own docs: **run one pod, `WEB_CONCURRENCY=1`.** Scale
+vertically (bigger pod) for now.
+
+Why a standard K8s setup does not get you out of this: the session id lives
+in the **JSON body** of `POST /v1/responses` (the `user` field), not in a
+header, cookie, or URL segment. That rules out every sticky-routing
+mechanism K8s gives you for free:
+
+- A vanilla `Service` (`ClusterIP`) load-balances across pod endpoints with
+  no notion of session at all — same failure mode as Railway's replicas,
+  one layer down.
+- `Service.spec.sessionAffinity: ClientIP` does not help either: the caller
+  is the consumer's own backend (achei-b2b, a server-to-server call), not
+  the end customer's browser, so many different customers' sessions arrive
+  from the same source IP and would collide on the same pod instead of
+  spreading — the opposite of what you want, and it still does not restore
+  a real per-session guarantee.
+- ingress-nginx's `nginx.ingress.kubernetes.io/upstream-hash-by` (the
+  standard sticky/consistent-hash annotation) hashes on nginx *variables* —
+  headers, cookies, `$request_uri`, client IP — not on a field parsed out of
+  a POST body. Reaching into the JSON body needs a custom Lua/OpenResty
+  snippet (or an Envoy filter) that parses the request and extracts `user`
+  before hashing. That is real, unbuilt engineering work, not a K8s
+  annotation to flip.
+
+If real horizontal throughput is ever needed, two paths get there, neither
+of them "just add replicas":
+1. **Build the body-aware sticky layer** above (Lua/Envoy consistent-hash on
+   the `user` field) in front of N pods, each still `WEB_CONCURRENCY=1`.
+2. **Move the session id into the URL**, the way the web widget transport
+   already does (`POST /api/widget/sessions/:token/messages` carries the
+   session token in the path) — that surface, unlike `/v1/responses`, *is*
+   sticky-routable today with a plain `upstream-hash-by: $request_uri`, no
+   custom scripting required.
+
+Neither is urgent while a single pod's throughput is enough — this section
+exists so scaling this deployment does not silently reintroduce the same
+cross-session leak the Railway incident above already found once.
+
 ## Backup / DR — Litestream (opt-in, configurable)
 
 A single volume is the **one point of total loss** between a pilot and production
@@ -300,6 +360,12 @@ per pod + **sticky-by-agent** routing (shard by tenant), or **LiteFS**, or an
 optional **Postgres** adapter. **Litestream** (above) for backup/DR from day one —
 orthogonal to topology.
 
+For the *session-routing* half specifically — as opposed to the storage
+topology above — see [`insika-router`](ROUTER.md): N pods behind a
+headless `Service`, one `insika-router` Deployment in front doing the
+consistent-hash routing ingress-nginx's own `upstream-hash-by` cannot (it
+hashes nginx variables, never a field parsed out of a POST body).
+
 ---
 
 ## Measuring performance / load
@@ -351,6 +417,8 @@ DEEPSEEK_API_KEY=sk-... ./scripts/loadtest-local.sh 4 24
 
 ## See also
 
+- [ROUTER.md](ROUTER.md) — `insika-router`, the session-sticky proxy for
+  scaling past one worker.
 - [RUNNING-LOCAL.md](RUNNING-LOCAL.md) — run the engine locally, single-process.
 - [Security](SECURITY.md) — tokens, egress, strict config.
 - [BENCHMARK.md](BENCHMARK.md) — the neutral, key-free engine benchmark.

data/docs/EMBEDDING.md

@@ -1,6 +1,6 @@
 ---
 title: Embedding
-parent: Ship it
+parent: Integrate
 nav_order: 4
 permalink: /embedding/
 ---

data/docs/EVALS.md

@@ -1,7 +1,7 @@
 ---
 title: Evals
-parent: Operate & prove it
-nav_order: 4
+parent: Improve
+nav_order: 1
 permalink: /evals/
 ---
 
@@ -157,6 +157,82 @@ Three rules make the number worth quoting:
 Cost: **two provider calls per judge per case**, which is why it is opt-in and never
 part of the gate.
 
+## Simulated users — conversations the agent never had
+
+A golden case fixes the user's turns in advance. Real customers branch — they answer
+the agent's question, or ignore it, or send an order number three messages later. A
+case with frozen turns can only ever test the path the author imagined.
+
+A **simulated** case generates the conversation instead: a persona model (the cheap
+platform `utility_model`) plays a customer with the persona as its **whole
+instruction**, and the target agent answers through the same transport a replay uses.
+They talk until the persona's `max_turns`, or until the persona emits a stop marker —
+`<<goal_met>>` when its goal is served, `<<gave_up>>` when it abandons. Both are
+recorded: "gave up at turn 3" is a finding.
+
+```yaml
+id: loja-objetivo-difuso
+agent: loja-chocolates
+persona:                          # the SIMULATED customer (alternative to `turns:`)
+  goal: "descobrir o que comprar de presente; não sabe nomes de produto"
+  style: "mensagens curtas, responde o que perguntam, desiste se tiver que explicar duas vezes"
+  opens_with: "oi, queria um presente"
+  knows:                          # the ONLY facts the persona may assert
+    orcamento: "até R$ 100"
+    ocasião: "aniversário"
+  max_turns: 8
+expect:
+  policy: investigate_first
+  rubric: |
+    Descobre o objetivo antes de recomendar (uma ou duas perguntas, não um formulário),
+    recomenda do catálogo real e fecha com um próximo passo claro. Reprova se despejar
+    catálogo antes de entender, ou se ficar perguntando sem nunca buscar.
+  min_score: 0.7
+```
+
+**The anti-invention rule is the soul of the feature.** The persona's prompt contains
+only the `knows` facts and the rule that it may assert exactly those and nothing else
+— asked about anything it does not have, it answers with ignorance ("não sei", "não
+tenho isso aqui"), like a real customer without that fact. A simulator that invents an
+order number produces a conversation the agent could never have had, and a case that
+tests nothing.
+
+```bash
+insika evals:simulate --persona persona.yml --target loja-chocolates --staging
+```
+
+- `--target <agent|url>` — an agent id over the deployment's `/v1/responses`, or a full
+  A2A URL (an agent that only speaks A2A rides the same Simulator through a thin A2A
+  transport; it polls once per second, bounded by `--timeout`, since a remote agent
+  takes seconds to finish a task).
+- `--staging` or `--eval-profile` — **one is required**. A simulated conversation
+  marks its transcript `simulated: true`; it does NOT disarm the agent's tools. So the
+  Simulator only runs against (a) a target the operator declares is a staging
+  deployment (`--staging`), or (b) an eval profile where the agent's side-effect tools
+  are swapped for dry-runs (`--eval-profile`).
+- `--eval-profile` is a **verified declaration, not a trust-me flag**. The CLI derives
+  the target's side-effect tools — the deployment's own registry over
+  `GET /v1/agents/:id` (`side_effect_tools`), or the local store when `INSIKA_DB`
+  points at it — and refuses unless `--eval-tools <a,b,c>` names every one of them.
+  The swap itself happens where the tools run (the deployment's eval profile; the
+  in-process overlay for a local graph, as in `examples/agent-tester/`); the
+  derivation is what keeps the client honest about what must be covered. An A2A target
+  has no reachable registry, so the explicit `--eval-tools` list is required there.
+- `--persona-model` — the model playing the customer (default: the platform
+  `utility_model`). The judge that scores the transcript comes from the same
+  panel configuration as a replay.
+- `--conv` — the conversation id. The default is unique per run
+  (`sim-<case id>-<random>`), because two runs on the same conv share the
+  deployment session: the second inherits the first's history — including
+  across the arms of an A/B comparison — and the grade stops measuring the
+  agent. Pass `--conv` only when continuing a session is the point.
+
+Every simulated run is **`simulated: true`** — the transcript carries the flag end to
+end, so a report never mixes a generated conversation with real traffic. A simulated
+case (`persona:`) is one of the two shapes of a case; the replay Runner **skips** it
+(the turns do not exist until a Simulator generates them) and only the simulate CLI
+drives it.
+
 Cases live in two places, and it is the same YAML in both:
 
 - **`evals/golden/**`** in the repo — the curated corpus, reviewable in a pull request,
@@ -178,6 +254,55 @@ A case whose stored YAML no longer validates is **listed as broken** on the Eval
 rather than skipped in silence — a test suite that quietly shrinks is worse than a red
 one.
 
+### `run_persona_eval` — a QA agent that tests other agents
+
+A tool (`lib/insika/tools/run_persona_eval.rb`), not a CLI: a QA agent picks one of its
+authored simulated cases and runs it **in-process**, against the case's declared
+target agent — the same Simulator + Judge machinery `evals:simulate` drives over HTTP,
+minus the network hop.
+
+```ruby
+tools %w[run_persona_eval save_artifact]
+```
+
+The model only sees `case_id`, enumerated with the ids the tool can actually run
+(never a free string it could invent) — every **simulated** case in the store, the same
+`persona:` shape as above.
+
+**Safety is derived here too, but there is no swap yet.** The tool computes the
+target's reachable side-effect tools (`Evals::EvalProfile`, the same derivation the CLI
+uses) and **refuses outright** — naming the tools — if that list is non-empty. Unlike
+the CLI, nothing here actually swaps a side-effect tool for a dry-run: `Evals::
+EvalProfile.registry` (the overlay) exists for exactly that, but nothing calls it yet.
+So `run_persona_eval` only runs against **read-only** target agents today; wiring the
+overlay into an in-process turn (so a target WITH a write tool can be tested safely) is
+follow-up work, not something this tool claims to do.
+
+**Budget**: the persona model + judge model calls are the cost of running the eval,
+charged to the **calling** agent's own turn — never the target's (the target's own
+turns bill normally, through the ordinary edge limiter, exactly as a real customer's
+would). A hard cap on the calling agent skips the run — visibly, in the tool's own
+result (`{skipped: true, reason: "budget", window: "daily"|"monthly"}`) — before a cent
+is spent; a soft cap just runs (the ledger's own alert already warns).
+
+Each run gets a **fresh session** (`eval-<case>-<random>`), never a reused one — a
+reused session lets the target agent "remember" earlier runs, which is not what a
+persona case is testing. See `examples/agent-tester/qa_scheduled.rb` for the full
+loop: `schedule` fires the QA agent, it calls `run_persona_eval`, then
+`save_artifact` publishes the quality report.
+
+**Tenant isolation.** A golden case carries a `tenant` (`platform` — the
+single-tenant default — unless the case declares one, the same convention
+`save_artifact` uses for its own binding tenant). `run_persona_eval` only ever
+lists or runs cases in the *calling* agent's own tenant: a case authored for
+another tenant is invisible, not merely refused — the model cannot even learn
+its id from the enum, and running it by a guessed id gets the same "unknown or
+invalid" error a nonexistent id would (the two must not be distinguishable).
+This is what makes "one QA agent per store" an actual boundary
+in a deployment where several stores' persona cases live in the same
+`GoldenStore` — without it, `qa-store-a` could enumerate and run
+`qa-store-b`'s persona and read its `knows` in the transcript.
+
 ## Running
 
 ```bash
@@ -235,7 +360,7 @@ not a regression.
 The same gate machinery guards the two automated loops — [Refinement](REFINEMENT.md)
 (cloned-agent replay of a proposed edit) and [Harvest](HARVEST.md) (cloned-agent
 replay of a mined skill). **Judges are mandatory for those gates** in exactly three
-shapes, the P18 lesson: a gate without a recorded baseline refuses, an all-red
+shapes: a gate without a recorded baseline refuses, an all-red
 baseline refuses, and a baseline recorded WITH judge scores, replayed with no judge
 configured, refuses — a rubric'd case with no verdict reads as a pass, so the
 candidate would beat a measurement it never took. A store with no golden cases cannot

data/docs/FACTS.md

@@ -1,7 +1,7 @@
 ---
 title: Facts
-parent: Operate & prove it
-nav_order: 6
+parent: Improve
+nav_order: 5
 permalink: /facts/
 ---
 
@@ -92,7 +92,7 @@ visible — the operator's edit always wins, never a silent overwrite.
 ## Provenance
 
 An approved fact is written with `origin: "distilled:<session_ref>"` — the
-RFC-0031 provenance discipline: `"engine"` (the `remember` tool), `"operator"`
+The provenance discipline: `"engine"` (the `remember` tool), `"operator"`
 (Studio edits), `"legacy"`, and `"distilled"` (+ the session that produced it).
 The Closed loop reads the same cell every later turn injects, and the
 distillation ledger suppresses re-proposing a fact that is already applied with