insika 0.2.0 → 0.3.0

data/docs/AGENTS.md

@@ -41,7 +41,7 @@ ergonomics, not in what they produce.
   re-import that drops a tool or skill also removes it. `DELETE /v1/agents/:id`
   removes an agent.
 - **Studio** — create and edit an agent by hand in the control UI (Config /
-  Prompts / Skills / Memory / History tabs), backed by the same commands.
+  Prompts / Skills / Memory / Outcomes / Cache / History / **loops** tabs), backed by the same commands.
 
 Creating an agent validates its id (required, must be unique) and its subagent
 graph (cycle/depth — see [subagents](#delegation-subagents)) **before**
@@ -97,6 +97,31 @@ the next tool-batch boundary: "you already ran this, answer with what you
 have"). A repeat after the warning aborts the turn like `max_tool_calls` does.
 Set it below 2 to switch it off.
 
+### `tool_persistence` — don't give up on the first empty result
+
+The loop guard's mirror image. `max_tool_repeat` stops the model from repeating
+the *same* call; `tool_persistence` stops it from giving up after *one* weak
+call. When ON (the default), the engine appends a short **"Tool discipline"**
+block after the agent's identity in the system prompt: a weak or empty tool
+result means *try again with a different approach — a rephrased query, a
+synonym, a broader term — before telling the user you found nothing* (and don't
+narrate the retries); a tool error means *read it and fix the arguments*, never
+repeat the exact same call. Without it, a search that returns 0 results reads as
+final and the model answers "I couldn't find it" when a synonym one call away
+would have.
+
+This is the **one default-ON profile flag** — every field above is opt-in, this
+one is opt-out, because the behavior is the proven default and the exception is
+the thing worth declaring:
+
+```ruby
+tool_persistence false   # remove the block for this agent
+```
+
+The block is a byte-stable constant, so `prompt_caching` stays effective: the
+deploy that introduces it costs one cache write per agent, and every turn after
+that hits as before.
+
 ### Why some limits are missing from that list
 
 `chat_rate_limit`, `agent_token_ceiling`, `queue_mode`, `debounce_ms`,
@@ -219,6 +244,12 @@ separately lives in one event, emitted when the window closes:
 Times and counts, never content. That is what answers "the customer says they
 sent the order number" without keeping a throwaway task per fragment.
 
+> **`steer` also collects at the door.** The two windows are the same policy's
+> halves, not two modes: a `steer` agent that set a `debounce_ms` also merges the
+> fragments that land before the turn starts (RFC-0027). The window value is what
+> an operator replaces the legacy pre-batch buffer with — `steer` catches anything
+> that arrives after the turn started, the door window the fragments before it.
+
 #### `steer` — the message arrives while the turn is already running
 
 `collect` only ever touches a turn that has **not started**. Once the agent is
@@ -339,7 +370,9 @@ Three capabilities invert the default — `nil`/absent means **OFF**, not "all":
 setting, never "everything on"). `tool_output_compression` is a fourth: opt-in
 mechanical dedupe of repeated tool results in the history (see
 [Context](CONTEXT.md#compaction-is-not-wired--except-the-mechanical-dedupe)),
-off by default because it changes what the model sees.
+off by default because it changes what the model sees. And one flag inverts the
+other way: `tool_persistence` is **ON unless you set it to `false`** (see
+[`tool_persistence`](#tool_persistence--dont-give-up-on-the-first-empty-result)).
 
 ### Declaring what this deployment has
 
@@ -455,6 +488,43 @@ reliability retries: 2, backoff: "exponential",
 Absent `reliability` = the plain single attempt, byte-for-byte today's
 behavior.
 
+#### Intent routing — classify before you answer (WS4)
+
+For a store that must tell "shopping" from "order" from "human" up front,
+routing is data on the profile:
+
+```ruby
+routes "shopping" => "the customer wants to browse products",
+       "order"    => { "description" => "asks about an existing order",
+                       "delegate" => "order-agent" },
+       "human"    => { "description" => "the customer asks for a person",
+                       "stuck" => true, "message" => "A person will help you." },
+       "default"  => "shopping",
+       "model"    => "deepseek-v4-flash"   # the cheap classifier (absent = the agent's own)
+```
+
+- **Classification** — when `routes:` is present, the message is classified into
+  one route with the configured model BEFORE the agent chat is assembled, from
+  a prompt auto-generated out of the descriptions (no per-route prompt file).
+  The route rides the turn: `state.route`, the `:route_classified` event, and
+  the terminal event additively.
+- **Deterministic default** — the model's answer must be a route name; prose,
+  an unknown name, or an empty answer falls back to `default`, never invents.
+  A classifier call that FAILS leaves the turn unrouted (routing is additive —
+  it must not break the turn).
+- **Cost** — the classification is an extra provider call, counted in the
+  turn's usage (the trace, the token ceiling and the budget all see it).
+- **Actions** — a route value may be a description string, or a Hash:
+  `delegate: "<agent-id>"` hands the turn to that existing agent and its
+  answer becomes the parent's; `stuck: true` ends the turn with the [stuck
+  outcome](#the-stuck-signal--i-cannot-proceed-ws5) and the route's `message`
+  (or description) as the lead-in — the consumer interprets it. A route with
+  neither is just a label. A delegation counts against the same delegation
+  depth cap as a subagent (`INSIKA_SUBAGENT_DEPTH_CAP`, default 5), so a pair
+  of agents routing to each other stops instead of looping.
+
+Absent `routes` = no classification, no extra call, byte-identical turn.
+
 #### Operator alerts — the webhook (WS6)
 
 Three operational events — `budget_warning`, `breaker_open`, `delivery_failed` —
@@ -562,6 +632,56 @@ allowlist, one or more `proposers`, a token `budget`, and a gate that replays th
 golden set before anything reaches a human. All of it is in
 [Refinement](REFINEMENT.md); none of it is on until you name it.
 
+## Distillation of customer facts
+
+`distill` configures how finished, idle customer conversations are read back as
+proposed facts — the human-gated loop documented in [Facts](FACTS.md). Pack
+data, `refinement:`'s shape, and absent = off for that agent:
+
+```ruby
+distill enabled: true,
+        idle_hours: 6,      # how idle a session must be before it distills
+        min_messages: 3,    # a shorter session distills noise
+        max_proposals: 10   # cap per session pass
+        # prompt: "<what counts as a fact for THIS store>" (the forge's half)
+        # model:  "<ref — absent = the platform utility_model>"
+```
+
+Nothing is ever applied automatically: the engine writes **proposals**, the
+operator approves/rejects/dismisses them on the Studio **Facts** page (the
+latch: a dismissed or rejected tuple is never proposed again), and an approval
+writes the fact to the customer's memory cell stamped
+`distilled:<session_ref>` through an optimistic CAS — an approval never
+silently overwrites an operator edit. Sessions are the only candidates, and
+the distiller rides the platform `utility_model`, never a new model slot.
+
+## Harvest of skills from real traffic
+
+`harvest` configures how finished, idle conversations are read back as
+proposed **SKILLS** for the agent's playbook — the human-gated loop documented
+in [Harvest](HARVEST.md). Pack data, `distill:`'s shape, and absent = off for
+that agent:
+
+```ruby
+harvest enabled: true,
+        negative_list: [ { rule: "no-competitor-prices", pattern: "concorrente" } ],
+        miner: { model: "deepseek-v4-flash",  # absent = the platform utility_model
+                 window: { last_sessions: 200 } },
+        idle_hours: 24,
+        min_messages: 3
+        # prompt: "<what a harvestable skill is for THIS store>" (the forge's half)
+```
+
+The loop reads only finished traffic (the fork is structural — the mining
+writes nothing to the sessions it read), filters every proposal through the
+negative list and the evidence ledger (product claims must reference IDs the
+origin sessions actually saw — an agent without `grounding.matcher.sku` does
+not mine at all), scores survivors with a double gate (the eval replay against
+the clone's golden set, judges mandatory in the three P18 shapes; the
+conversion "not worse" check against the RFC-0032 frozen baseline), and lands
+a skill **only after a human approves** — snapshot-first, append-only
+promotion log, deterministic rollback. Nothing is ever applied automatically.
+
 ## Delegation (subagents)
 
 An agent can delegate to **subagents**: named child agents it may invoke as a
@@ -608,6 +728,261 @@ next turn with no restart. See [Deploy](DEPLOY.md) for the durable-volume setup
 [Context](CONTEXT.md#the-volume) for why editing a committed file does *not* change
 a running agent.
 
+## Media in the message contract (WS9)
+
+The engine transports media, it never means it. The message accepts additive
+**content parts** alongside the text — voice notes and photos travel, and any
+skill (a fitting room, an image QA) stays a consumer layer on top:
+
+```bash
+curl -X POST /v1/messages?stream=false -H "Authorization: Bearer $TOKEN" \
+  -d '{ "agent": "store-support", "session_id": "chat-7",
+        "message": "", "parts": [
+          { "type": "audio", "url": "https://cdn.example.com/voz.ogg" },
+          { "type": "image", "url": "https://cdn.example.com/sofa.jpg" }
+        ] }'
+```
+
+- **Audio** is transcribed (RubyLLM STT; model via `INSIKA_STT_MODEL`) and the
+  text enters the turn marked `source: "voice"` on the terminal event — the
+  consumer's signal the person spoke. A consumer that transcribes itself can
+  send the text with `"source": "voice"` directly.
+- **Images** attach to the model's ask (vision); the provider bills them and
+  the usage flows like any ask. The first image URL is also
+  `{{ctx.image_url}}` for data tools — photo analysis outside the prompt, the
+  tool's own egress applying when it fetches. Media URLs (audio AND image) are fetched by
+  the engine through the same egress guard (a private/metadata target is
+  refused — SSRF) and the same size ceiling (1 MB audio, 5 MB image: the bytes
+  land in this process). A refused, oversized or unreadable part fails the turn
+  loudly at the `:media` stage, never a silent drop.
+- **Media alone is a turn.** A voice note with no caption is `parts` and an
+  empty `message` — the transcription becomes the message at the `:media`
+  stage. A media message never joins another turn (`collect`/`steer` move text
+  only, and the parts would be left behind), and a transcription that comes
+  back empty fails the turn instead of asking the model about nothing.
+- **Parts are contract at the edge** — a malformed part (unknown type, an
+  image/audio without `url`, a text without `text`) is a 422 before dispatch
+  on `/v1/messages` and `/v1/responses`.
+- `/v1/responses` accepts the OpenAI multimodal shape: `input` as an array of
+  text/image/audio parts.
+
+## Generated media as outputs (WS9, saída)
+
+The turn can **produce** an image or a voice clip — but only when both sides of
+the gate agree, because nothing leaks by default. The agent declares it may
+generate media (`outputs` on the profile), and the **channel** declares it can
+receive it (`channel.capabilities` on the request):
+
+```bash
+curl -X POST /v1/responses -H "Authorization: Bearer $TOKEN" -d '{
+  "model": "openclaw:store-support", "user": "chat-7",
+  "input": "manda a foto do sofá da promoção",
+  "channel": { "capabilities": ["image_output", "audio_output"] }
+}'
+```
+
+```ruby
+agent = Insika.agent("store-support") do
+  instructions "…"
+  outputs image: { model: "gpt-image-1", size: "1024x1024" },   # the AGENT's half
+          tts:   { model: "tts-1", voice: "alloy" }
+end
+```
+
+- **Both gates** must pass for the model to even see the `generate_image` /
+  `tts` tools: the agent opted in (`outputs`) and the request declared the
+  matching capability (`image_output` / `audio_output` — an unknown value is a
+  422, never a silent ignore). The "abstraction admits only what leaks" rule.
+- **The media rides the envelope, never the answer text.** The terminal event
+  and the `/v1/responses` completed frame carry an additive `output_parts`
+  array — `{ type: "image", mime_type:, base64:, model: }` /
+  `{ type: "audio", mime_type:, base64:, model: }`. The model's prose stays
+  the `:content` answer; the channel consumes the bytes next to it.
+- **Generation is billed and counted.** Image tokens join the turn's usage
+  (like any ask). The speech API reports no token counts, so a TTS call adds
+  an honest `usage.media` counter and the part carries the `model` for
+  consumer-side pricing.
+- **Seams, not magic.** The generator is injectable per kind (specs stub it);
+  the defaults are lazy: images via RubyLLM (paint), speech via a thin POST to
+  the OpenAI-compatible `/audio/speech` endpoint using the same provider
+  config the chat uses — RubyLLM as of 1.16.0 has no speech API. A generated
+  part over 8 MB refuses loudly, never silently truncates.
+- **Not here:** what the generated image *means* — a fitting room, a product
+  mockup — is a skill on top. The engine transports bytes and cost.
+
+## Customer-scoped memory and the right to be forgotten (WS8)
+
+Memory is naturally **per customer, not per tenant**. A message that carries a
+`customer` key moves the engine's memory scope to that person:
+
+```bash
+curl -X POST /v1/messages?stream=false -H "Authorization: Bearer $TOKEN" \
+  -d '{ "agent": "store-support", "session_id": "chat-7",
+        "customer": "c-123", "message": "cadê meu pedido" }'
+```
+
+- **Scope** — with `customer` present, the `remember` tool and the `<memory>`
+  block read/write the `[tenant:]customer` cell: two customers under the same
+  tenant never see each other, and the `<request_context>` tenant label (the
+  merchant) is untouched. Absent `customer` = today's per-tenant/per-chat
+  behavior.
+- **Right to be forgotten** — `POST /v1/commands/forget_customer` (operator)
+  purges the customer's memory cell, their sessions and everything those
+  sessions left behind — per-session traces, the tasks (the message text lives
+  in the persisted command), their checkpoints (the transcript) and the outbox
+  deliveries (the answer as it was handed to the channel) — and nothing else's:
+  `{ "customer": "c-123", "tenant": "acme" }`. **Name the tenant**: the
+  operator credential carries none, and without one the purge means the whole
+  deployment (the untagged memory cell, plus that customer's sessions in every
+  tenant) — right for a single-tenant deployment, never what a multi-tenant
+  operator means. Facts also support an optimistic CAS write
+  (`replace_if_revision`) for an integration that must not clobber a concurrent
+  edit.
+- **Tenant deletion** — `POST /v1/commands/delete_tenant_data` (operator)
+  purges EVERYTHING the engine holds about one tenant: its sessions and their
+  whole footprint (traces, tasks, checkpoints, outbox deliveries), every memory
+  cell under the tenant (its own + the customer cells — enumerated from the
+  store, so even a cell whose session was already deleted goes) and its outcome
+  records: `{ "tenant": "acme" }`. Its API tokens are **revoked first** (before
+  the sweep): an offboarded tenant whose credentials still resolved kept
+  authenticating and could open a new session over the erasure. The tenant
+  string is the isolation boundary; a neighbour is untouched.
+- **Retention** — the age-based counterpart, as data: the settings key
+  `retention_days` (Integer days; absent/0 = OFF, the engine never sweeps by
+  default). The tick's daily sweep (at most once per 24 h, behind the same
+  single-key claim the stale-task sweep uses) purges sessions (+traces),
+  terminal tasks (+checkpoints), delivered/failed outbox records, memory
+  facts/notes and outcomes older than the window. A non-terminal task is never
+  touched — the Recovery sweep owns those lives — and neither is a delivery
+  still owed to somebody. One thing the same daily pass sweeps **regardless of
+  `retention_days`**: the budget counter cells whose window already rolled over
+  (and their once-per-window alert markers). Those are engine bookkeeping, not
+  customer content, and nothing else ever collected them.
+
+## Outcomes — business results over real traffic (WS7)
+
+The engine measures what it is told to measure. The operator or the integration
+records a conversation's business outcome after the fact — `conversion`,
+`escalation`, `deflected`, anything, optionally with a monetary `value`:
+
+```bash
+curl -X POST /v1/outcomes -H "Authorization: Bearer $TOKEN" \
+  -d '{ "agent": "store-support", "session_id": "chat-7",
+        "outcome": "conversion", "value": 129.9 }'
+```
+
+The endpoint is **additive and outside the response contract** — the turn never
+knows or cares; the engine transports the outcome and never interprets it (what
+"conversion" means is yours). Records are tenant-stamped (a tenant principal
+writes and reads only its own), and `GET /v1/outcomes?agent=` serves the last
+outcome per agent plus the per-day series — the last-outcome pill on the Studio
+agent grid, and the per-day series on the agent detail.
+
+### The outcome funnel (RFC-0032)
+
+A store's funnel is pack data on the agent — the engine folds WS7 outcomes into
+the **declared** stages, and never hard-codes one itself (the stage vocabulary
+is the forge's):
+
+```ruby
+agent = Insika.agent("store-support") do
+  instructions "…"
+  funnel stages: %w[greeted qualified cart paid],
+         advance_on: { "abandoned_cart" => "cart", "pix_paid" => "paid" },
+         primary: "paid", attribution_window: "72h"
+end
+```
+
+The fold contract:
+
+- **Tick-driven, cumulative event counts on the declared order.** An outcome of
+  kind K means the session *reached* `advance_on[K]`; the fold increments
+  `stages[0..index]` for the reached stage. A per-stage-complete integration
+  and a terminal-event integration therefore produce identical counts — a
+  session that paid also emitted the earlier events. A duplicate event
+  double-counts (the integration's defect, not the engine's); **do not declare
+  a stage off the linear path** (a "handoff" stage would be inflated by every
+  later event). Counts are **event counts, not distinct sessions** — the
+  baseline is events-based.
+- **Idempotent**: a per-pair `{at, ids}` cursor inside one transaction; a crash
+  mid-fold never double counts, and a second pass folds only what is new.
+- **The attribution window is carried data, never computed** — `72h` is
+  validated, rendered, and copied into the baseline snapshot; causal
+  attribution stays human.
+- **The baseline freeze** (Studio > Funnel, or `:freeze_funnel_baseline` on the
+  bus) sums the folded cells over a span of **≥ 28 days** (shorter spans are
+  refused) into one current snapshot per `(tenant, agent)` — the number
+  RFC-0033 (follow-up A/B) and RFC-0035 (promotion gate) compare against.
+- **Malformed declarations never crash the tick**: the fold skips them, the
+  doctor names the defect, the Studio shows nothing until it is fixed.
+- Vocabulary note: in the gem this is the **outcome funnel** — the stage names
+  are the forge's, and a bare install (no `funnel:` on any agent) shows no
+  funnel and no stage names at all.
+
+## Follow-ups — the seller who comes back (RFC-0033)
+
+The agent can book a follow-up with a customer at a future time — "te chamo
+amanhã se o PIX não cair" said in-conversation and meant. The engine fires the
+synthetic turn on its own tick, with consent and without spam. Everything is
+pack data on the profile:
+
+```ruby
+agent = Insika.agent("store-support") do
+  instructions "…"
+  followup arm: "schedule",
+           policy: { quiet_hours: { timezone: "America/Sao_Paulo",
+                                    start: "21:30", end: "09:00" },
+                     max_frequency: "2/24h",       # N outbound per window, per customer
+                     cancel_keywords: ["não quero mais contato"],
+                     silence_after_sends: 3 }      # N fires without a reply -> :unavailable
+end
+```
+
+The pieces:
+
+- **`schedule(at:, reason:)`** — a built-in tool the agent calls when the
+  customer agrees to be contacted again (a product, a cart, a pending payment).
+  The call itself IS the consent record — recorded without ever lifting
+  `:unavailable` or resetting the silence counter (ONLY a customer message
+  reopens, so a re-booking inside a follow-up turn cannot clear the silence
+  protection). `cancel_followup(id:)` is the sibling. A customer who opted out
+  can never be rescheduled.
+- **Contact state per customer** — `granted | revoked | unavailable` in a
+  durable cell per `(tenant, customer)`. Only `granted` may be messaged;
+  `revoked` is immediate and permanent until the customer speaks again;
+  `unavailable` means silence ≠ refusal — the engine stops firing after
+  `silence_after_sends` unanswered sends, and ANY customer message reopens.
+  The policy's `cancel_keywords` are matched on every inbound message: a
+  match revokes the contact and cancels its pending follow-ups in one
+  transaction.
+- **Firing is the tick's third duty** — the engine claims the due records
+  (one per claim window, at-most-once across workers), applies the policy in
+  force AT FIRE TIME (contact state, quiet hours, dedup per
+  `(customer, reason)`, frequency ceiling) and either enqueues the synthetic
+  turn or marks the record `blocked` with the failing rule — auditable, never
+  silent. Blocking happens at fire time, never at schedule time: the schedule
+  is a promise made in-conversation, and only the policy in force then may
+  revoke it.
+- **The synthetic turn** — a first-class inbound turn stamped
+  `origin: "scheduled"` (a refinement read can never mistake the engine's
+  kick for the customer repeating themselves), delivered through the full
+  pipeline on the channel the conversation came in on. It skips the edge's
+  ENTRY rate/token checks like a resume does — a follow-up she agreed to must
+  not receive the rate-limit reply; its usage still lands on the ledger.
+- **The Follow-ups page** (Studio) — per agent: the pending/fired/cancelled/
+  blocked records (blocked rows carry the reason), the read-only policy
+  summary and the A/B card: per arm, `sent` vs `conversions` (against the
+  RFC-0032 baseline) vs `opt-outs`. The only mutations — cancel a pending
+  record, force-revoke a contact — go through bus commands.
+- **LGPD** — the records and cells die with the customer (`forget_customer`),
+  the tenant (`delete_tenant_data`) and age out under the same
+  `retention_days` sweep as the rest of the footprint.
+
+Absent `followup:` = the feature is off for that agent — no tools wired, no
+records, byte-identical turns. The A/B against an existing cron is an
+operator experiment: the engine only keeps the records and the read card (the
+cron arm writes through the same store class with its own `arm` label).
+
 ## See also
 
 - [Tools](TOOLS.md) — define, register, and troubleshoot tools.

data/docs/API.md

@@ -0,0 +1,56 @@
+---
+title: The /v1 API
+parent: Build an agent
+nav_order: 9
+permalink: /api/
+---
+
+# The /v1 API — the frozen compatibility contract
+
+The HTTP surface is the drop-in OpenAI-Responses-compatible contract: a client
+that speaks `/v1` today speaks it tomorrow. This page is the WRITTEN promise
+(RFC-0036 C6) — the mechanical half is the version gate in the server, and the
+two cannot drift (a spec pins the gate's version to the date below).
+
+## The surface
+
+| Route | What it is |
+|-------|------------|
+| `POST /v1/responses` | the OpenAI-Responses-compatible turn ingress (streaming SSE) |
+| `POST /v1/messages` | the channel-style message ingress (one turn per message, ack-fast) |
+| `POST /v1/agents` | provisioning by definition/pack (idempotent, authoritative) |
+| `GET/DELETE /v1/agents` | list / remove agents |
+| `POST /v1/sessions` | create a session explicitly |
+| `POST /v1/outcomes` | record a business outcome (`conversion`, `escalation`, any label) |
+| `GET /v1/outcomes` | last outcome per agent + the per-day series |
+| `POST /v1/commands/...` | operator commands (`forget_customer`, `delete_tenant_data`, the follow-up mutations) |
+| `GET /v1/vitals` | process health/uptime vitals |
+| `GET /v1/...` | the onboarding surface (`start.md`, `models.json`, `/docs/<name>.md`) |
+
+The turn endpoints speak the OpenAI `response.completed` wire format; the
+`Insika-Version` header declares the compatibility vintage of a request.
+
+## The compatibility rule
+
+**Request and response shapes are stable; changes are additive-only.** A new
+field on a request or response is a release. Removing, renaming or re-typing a
+field is a BREAKING change and requires, together, all three:
+
+1. a new `Insika-Version` entry in the server's known-versions gate (an
+   unknown value is refused with 400 before auth — fail-closed);
+2. a route branch that serves both vintages (a compatibility branch, per
+   RFC-0016 A5), so an old client keeps working while the new shape rolls;
+3. a new `**Frozen as of:**` line below.
+
+Additive changes need none of the three.
+
+**Frozen as of: 2026-08-08** — the date that is the 1.0 promise. The gate's
+first known version, pinned by `spec/insika/server/version_gate_spec.rb`; the
+release writes the 1.0 freeze date here at release time.
+
+## The 400-on-unknown rule
+
+A request carrying an `Insika-Version` the gate does not know is refused with
+`400 Bad Request` BEFORE authentication — a client that speaks a future or
+misspelled vintage learns immediately, and an unauthenticated probe cannot
+distinguish the gate from auth (fail-closed, constant-time).

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 |
@@ -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