insika 0.1.0 → 0.3.0

data/docs/CHANNELS.md

@@ -181,16 +181,19 @@ 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/#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 |
@@ -259,7 +262,7 @@ Content-Type: application/json
   "external_id": "5511999998888",        // required — YOUR key for this conversation
   "message":     "queria saber do pedido", // required
   "event_id":    "wamid.HBg…",           // optional but strongly recommended (dedup)
-  "vars":        { "store": "ocean-drop" } // optional — session vars on first contact
+  "vars":        { "store": "demo-store" } // optional — session vars on first contact
 }
 ```
 
@@ -285,12 +288,14 @@ 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
 
 {
@@ -310,6 +315,46 @@ stays internal unless the agent opts in. That contract is
 [the edge contract](/architecture/#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
@@ -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
@@ -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 (RFC-0025) 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

data/docs/CONTEXT.md

@@ -20,18 +20,21 @@ 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. |
-| **Skills** | `<available_skills>` | 80 | Level-1 skill list — 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). |
+| **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"
 
@@ -48,32 +51,111 @@ prefix cache below).
 > returns empty turns, raise `context_budget` (e.g. to `60000`) before looking
 > anywhere else. See [Agents](AGENTS.md#default-limits).
 
-### Compaction is not wired
+### Compaction is not wired — except the mechanical dedupe
 
 There is a settings stub for LLM-summarization compaction (`enabled: false`,
-`keep_last`, a reserved utility-model slot), and the Studio exposes it, but
-**nothing consumes it today** — size is managed purely by hard budget eviction.
+`keep_last`, a reserved utility-model slot), but **nothing consumes it today**
+— and the Studio no longer shows a form for it, so the setting cannot be
+switched on by accident. Size is managed purely by hard budget eviction.
 Do not rely on compaction to shrink a bloated agent: tune `context_budget` and
-keep the identity lean. Turning the setting on does nothing yet.
+keep the identity lean.
+
+One cheap half **is** wired, opt-in per agent: `tool_output_compression` (DSL
+`tool_output_compression`, or `"tool_output_compression": true` in the pack).
+When on, byte-identical repeated **tool results** in the replayed history
+collapse to a compact back-reference (the first occurrence stays full, with a
+one-line summary) — no LLM involved. It changes what the model sees, so it is
+never a default: an older detail is only in the first occurrence, and a model
+that wants it re-calls the tool. Reach for it when a tool keeps returning the
+same body (a catalog page, a status) and history is the fragment blowing the
+budget first.
+
+> The **Studio session screen** shows what the builder assembled per turn —
+> tokens per category (identity, history, memory, …), the tools-schema estimate
+> and the budget verdict (`used / cap`, evicted sources). Counts only, never
+> fragment content.
 
 ## Memory
 
 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** (RFC-0031): 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).
+
+An **approved distilled fact** (RFC-0034 — 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
@@ -83,6 +165,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 (RFC-0030)
+
+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/DEPLOY.md

@@ -33,9 +33,14 @@ curl localhost:9292/up      # {"status":"ok"}
 ## The process model
 
 The image boots **N Falcon worker processes over one SQLite file**
-(`WEB_CONCURRENCY`, default 2). That number is a **contract input, not a tuning
+(`WEB_CONCURRENCY`, default 1). That number is a **contract input, not a tuning
 knob**: it decides which engine semantics hold cluster-wide and which are
-per-worker. The contract:
+per-worker. The default is 1 because the per-worker semantics are the product
+— the queue modes (`collect`/`steer`) and FIFO ordering need one
+session actor; raise N only with sticky routing per session in front. It is
+also a [Soak](SOAK.md) precondition: with more than one worker the hourly RSS
+series is a random process per sample, and a soak refuses to start. The
+contract:
 
 > Everything here describes N workers of **one** deployment — one graph, replicated.
 > N *graphs* inside one process is a different contract, and it is
@@ -76,6 +81,18 @@ per-worker. The contract:
    that buffer defaults to 0** — SIGKILL right after SIGTERM, which cancels the
    whole drain — so set `RAILWAY_DEPLOYMENT_DRAINING_SECONDS=30` on the
    service.
+5. **A periodic tick closes the gap between boots.** Serving workers run a tick
+   every `INSIKA_TICK_INTERVAL` (default **60s**, `0` disables) as a child of
+   the turn supervisor: it re-drives any outbox record left `:pending` (each
+   carries its own claim — every worker may drain), and sweeps orphaned tasks
+   **without waiting for a deploy** — which is what recovers the orphans of a
+   worker respawned mid-generation (item 3's hole). One worker per window
+   sweeps (a single transactional claim), and only `:queued`/`:running` tasks
+   untouched for `INSIKA_TICK_STALE_AFTER` (default **900s**) are candidates:
+   a live turn is bounded by `turn_timeout`, so anything older cannot be alive.
+   **If you raise `turn_timeout` past it, raise `INSIKA_TICK_STALE_AFTER` too** —
+   the threshold must exceed the largest `turn_timeout` of the deployment.
+   `:waiting`/`:paused` tasks are idle by nature and stay boot recovery's.
 
 `deploy/entrypoint.sh` sets `WEB_CONCURRENCY` next to a pointer to this section;
 this section is the single source of truth for what changing it means.
@@ -86,19 +103,22 @@ this section is the single source of truth for what changing it means.
 |-----|---------|--------|
 | `INSIKA_DB` | `/data/insika.db` (in the image) | durable SQLite path (**mount a volume!**) |
 | `PORT` | `9292` | HTTP bind port |
-| `WEB_CONCURRENCY` | `2` | number of Falcon worker processes — a contract input, see [The process model](#the-process-model) |
+| `WEB_CONCURRENCY` | `1` | number of Falcon worker processes — a contract input, see [The process model](#the-process-model) |
 | `INSIKA_BOOT_ID` | set by `deploy/entrypoint.sh` | boot generation id; the recovery **task sweep** runs once per id (process model, item 3). Unset = every boot sweeps (single-process default) |
 | `INSIKA_DRAIN_TIMEOUT` | `20` | seconds a stopping worker waits for in-flight turns before abandoning them to the next boot's recovery (process model, item 4). The entrypoint sizes Falcon's `--graceful-stop` from it; on Railway also set `RAILWAY_DEPLOYMENT_DRAINING_SECONDS` ≥ drain + 10 |
+| `INSIKA_TICK_INTERVAL` | `60` | seconds between tick passes — outbox drain + stale recovery sweep (process model, item 5). `0` disables |
+| `INSIKA_TICK_STALE_AFTER` | `900` | seconds a `:queued`/`:running` task must sit untouched before the tick sweeps it. Must exceed the largest `turn_timeout` of the deployment |
 | `OPENCLAW_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN` | Bearer for `/v1/responses` and `/v1/agents` (the API contract) |
 | `ADMIN_TOKEN` | `local-demo` | login token for `/studio` (**change in production**) |
 | `DEEPSEEK_API_KEY` | — | provider key. **Without it the engine still boots** (`/up` green), but turns fail until it is configured (env or Studio → LLM providers) — cloud resilience |
-| `DEEPSEEK_MODEL` | `deepseek-chat` | model |
-| `ACHEI_INTERNAL_URL` | — | base URL for data-tools calling back a consumer's internal API (see below) |
+| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | model |
+| `CONSUMER_INTERNAL_URL` | — | base URL for data-tools calling back a consumer's internal API (see below) |
 | `INSIKA_EGRESS_HOSTS` | — | outbound host allowlist (SSRF guard) |
-| `INSIKA_EGRESS_ALLOW_HTTP` / `_ALLOW_PRIVATE` | off | for `http`/loopback callbacks only (**never in cloud**) |
+| `INSIKA_EGRESS_ALLOW_HTTP` / `_ALLOW_PRIVATE` | off | for `http`/loopback callbacks only (**never in cloud**). Also opens inbound **media** fetches (audio/image URLs) to `http`/private targets — a local run serving media over `http://` needs it |
 | `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_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 |
@@ -165,10 +185,13 @@ insika env               # lists known keys + current values (secrets masked)
 Checks: env (the schema above), settings schema version (a pending migration →
 `--fix` applies it), a missing platform `default_model` (`--fix` seeds it from
 `DEEPSEEK_MODEL`), durable vs ephemeral backend, LLM provider configured,
-`ADMIN_TOKEN` set, data-tool definitions still valid, and **prompt files that hold
+`ADMIN_TOKEN` set, data-tool definitions still valid, **prompt files that hold
 text rather than a serialized object** (a file whose content is a stringified Hash
 serves a mangled prompt on every turn while looking perfectly healthy — present,
-non-empty, and the agent still answers). Settings-schema migrations are **explicit**
+non-empty, and the agent still answers), and **skill drift** — a shared skill whose
+body names one store, a prompt file routing to a skill the agent cannot load, a broken
+companion pair, a stale `eager:` key (see
+[Skills](SKILLS.md#drift-guards)). Settings-schema migrations are **explicit**
 — no Studio save silently reinterprets old-shape data.
 
 ### Data-tool callbacks to a backend — via a tunnel
@@ -178,8 +201,8 @@ cloud** and your backend **on your machine** (`:3000`), expose it over a public
 `https` tunnel and point the engine at it:
 
 ```bash
-# in the tool/manifest: base_url = {{env.ACHEI_INTERNAL_URL}}
-ACHEI_INTERNAL_URL=https://your-tunnel.example.dev
+# in the tool/manifest: base_url = {{env.CONSUMER_INTERNAL_URL}}
+CONSUMER_INTERNAL_URL=https://your-tunnel.example.dev
 INSIKA_EGRESS_HOSTS=your-tunnel.example.dev
 ```
 
@@ -197,7 +220,7 @@ healthcheck, and a restart policy.
 2. **Volume**: mount it at `/data` (the default `INSIKA_DB` points there) —
    without a volume, SQLite is ephemeral and recovery resumes nothing after a
    redeploy.
-3. **Vars**: `DEEPSEEK_API_KEY`, `OPENCLAW_GATEWAY_TOKEN`, `ACHEI_INTERNAL_URL`,
+3. **Vars**: `DEEPSEEK_API_KEY`, `OPENCLAW_GATEWAY_TOKEN`, `CONSUMER_INTERNAL_URL`,
    `INSIKA_EGRESS_HOSTS` (and `WEB_CONCURRENCY` to match your plan/CPU).
 4. The healthcheck hits `/up`.
 5. Point your consumer at the service's public URL, with a matching API token

data/docs/EMBEDDING.md

@@ -21,7 +21,7 @@ makes your responsibility.
 # config/initializers/insika.rb
 INSIKA = Insika.embed(backend: Insika::Stores::SQLite.new(path: Rails.root.join("storage/insika.sqlite3").to_s)) do
   agent "support" do
-    model "deepseek-chat"
+    model "deepseek-v4-flash"
     provider :deepseek
     api_key ENV.fetch("DEEPSEEK_API_KEY")
     instructions "You answer questions about orders. Be brief."
@@ -57,7 +57,7 @@ Rails' `mount` (and `Rack::URLMap`, and anything else that moves the prefix into
 
 ## Why the store is an argument
 
-Until RFC-0017 the engine was not one process — it was one *program*. Two graphs
+The engine was not always one process — it was one *program*. Two graphs
 built in the same Ruby process shared things they never declared:
 
 | What | What actually happened |
@@ -163,15 +163,19 @@ was given a backend never looks at it.
 | The reactor / `supervised` | You, matching your server |
 | Recovery of orphaned turns at boot | You, if you want it — the sweep is `Insika::Recovery`, wired by `Insika::Server::Boot` for the standalone deployment, not by `embed` |
 
-### Embedding is not multi-tenancy
+### Embedding is not the multi-tenant server
 
 Two graphs stop corrupting each other. That is all this contract says. **Who is
 allowed to talk to which graph** is authorization, and it is not here: `token:` is
 a single Bearer gating the whole mounted app, exactly as it does for the
-standalone server — the written decision is [one deployment, one token;
-multi-tenancy belongs to the host](SECURITY.md#the-bearer-gate). If your app has
-users, put the mounted app behind your own authentication and pass `session:`
-yourself — do not hand the mount point to the browser.
+standalone server in the default mode. Multi-tenancy is a property of the
+*standalone* server, not of an embed: with `INSIKA_TENANCY=multi_tenant` the
+Bearer resolves to a principal before the routes — per-tenant tokens scoped to
+their own sessions, tasks and events, operator tokens with the run of the
+deployment (see [Security](SECURITY.md#the-bearer-gate)). An embedded graph keeps
+no token store, so an embed's tenancy belongs to the host: put the mounted app
+behind your own authentication and pass `session:` yourself — do not hand the
+mount point to the browser.
 
 ---
 

data/docs/EVALS.md

@@ -132,7 +132,7 @@ reference:
 ```
 
 ```bash
-ruby evals/run.rb --agent ocean-drop --pairwise
+ruby evals/run.rb --agent loja-chocolates --pairwise
 ```
 
 Three outcomes — `better`, `comparable`, `worse` — and two more the panel can produce
@@ -232,6 +232,15 @@ That is what you run before merging a prompt, tool or model change. A case with
 baseline entry never blocks: it shows as failing in the report, but a brand-new case is
 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
+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
+gate, and cannot promote.
+
 ## Honest limits
 
 - **A judge is a model.** It has taste and it has bad days; that is why the
@@ -271,3 +280,13 @@ needs to score a candidate agent with the same judge, and a second copy of the j
 would be the worst possible outcome. It stays a **client** even so: it reaches a running
 deployment over HTTP through `POST /v1/responses` and never reads a store directly.
 `evals/run.rb` is a thin CLI over it.
+
+## Parity — the shadow criterion
+
+The shadow experiment's rule lives in a **deployment-side criterion file** —
+the path `INSIKA_PARITY_CRITERION` points at, prose a human reads and a `yaml`
+block the machine applies, in one file, so there is exactly one place to edit.
+The file's whole bytes are hashed; every shadow pair records that hash,
+and a window whose pairs disagree produces `:invalid`, never a verdict. Editing
+the criterion mid-experiment is *caught*, not averaged away. The fold itself is
+`lib/insika/parity/*` (see [Channels](CHANNELS.md#shadow-mode)).