insika 0.1.0 → 0.3.0

data/docs/AGENTS.md

@@ -18,7 +18,7 @@ keeps the profile it captured when it started; the next turn sees the new one.
 >
 > ```ruby
 > agent = Insika.agent("assistant") do
->   model "deepseek-chat"
+>   model "deepseek-v4-flash"
 >   provider :deepseek
 >   instructions "You are a concise, friendly assistant."
 > end
@@ -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**
@@ -84,13 +84,44 @@ lookups.
 ```ruby
 DEFAULT_LIMITS = {
   turn_timeout: 300, tool_timeout: 60, provider_timeout: 5,
-  context_budget: 8_000, max_tool_calls: 50, approval_timeout: 3_600,
-  tool_concurrency: 1
+  context_budget: 8_000, max_tool_calls: 50, max_tool_repeat: 3,
+  approval_timeout: 3_600, tool_concurrency: 1
 }
 ```
 
 `build` merges your overrides over these — you set only the deltas.
 
+`max_tool_repeat` is the loop guard: the same tool called with **identical
+arguments** that many times in a row gets ONE in-turn warning (a user message at
+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`,
@@ -213,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
@@ -304,7 +341,7 @@ What "abandoned" means, exactly:
   visible to an *operator* (its `tool_call`/`tool_result` events and the trace), not to
   the model — a half batch in the history would be an invalid prompt.
 
-> **No grace knob.** RFC-0015 sketched an `interrupt_grace_ms`; it is not
+> **No grace knob.** An `interrupt_grace_ms` was sketched; it is not
 > implemented, and would buy nothing here. The new turn is queued behind the abandoned
 > one either way (one turn at a time per session is the invariant), and waiting for a
 > boundary inside the request would break the ack-fast rule that put the debounce
@@ -330,7 +367,12 @@ For tools, a paired deny list (`tools_deny`) **always wins**, and
 
 Three capabilities invert the default — `nil`/absent means **OFF**, not "all":
 `subagents`, `memory`, and `guardrails` (each defaults to off or a conservative
-setting, never "everything on").
+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. 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
 
@@ -386,6 +428,123 @@ per agent (blank inherits the platform value, `0` explicitly disables it).
 > *present but nil* reads as OFF for that agent — leave the key **absent** to
 > inherit. See [Security](SECURITY.md#edge-limits).
 
+#### Calendar budgets — the daily/monthly cost wall
+
+A third, opt-in ceiling for the *billing* shape the windows above cannot express:
+a spend cap over a CALENDAR day or month, per `(tenant, agent)` when
+multi-tenant. Data on the profile (DSL `budget` or the pack's `budget` key):
+
+```ruby
+budget daily: 100_000, monthly: 2_000_000, soft: false   # or soft: true
+```
+
+- Tokens count the **billed** spend — `input + output + cached + cache_creation`
+  (the cached prefix is the bulk of the bill, not an afterthought).
+- **Hard** (the default, `soft` absent/false): a turn that arrives with the
+  window's spend already at/over the cap **fails** with the typed
+  `Insika::BudgetExceeded` — the envelope reads `budget_exceeded` +
+  `retry_after` (seconds until the window rolls). It is NOT a customer reply; it
+  is an operator signal.
+- **Soft** (`soft: true`): the same turn RUNS — crossing the cap emits one
+  `budget_warning` event per window and injects a note into the context (the
+  model sees it, the transcript does not).
+- Either way, crossing `alert_at` (default `0.8` of the cap) fires the same
+  warning **before** the wall, once per window.
+
+> ⚠️ Unlike the ceilings above, the cap that counts is per **calendar** window —
+> a `daily` budget rolls at UTC midnight, a `monthly` one on the 1st, whatever
+> the sun. `agent_token_window` is a fixed seconds window and cannot express
+> "the day resets at midnight".
+
+#### Reliability — retries, fallback, circuit breaker (WS3)
+
+The provider interaction is a single attempt by default (RubyLLM's own 2
+transport retries aside). For a store that cannot have a dead model take the
+chat down, the reliability policy is DATA on the profile:
+
+```ruby
+reliability retries: 2, backoff: "exponential",
+            fallback: ["openai/gpt-4o-mini"],
+            circuit_breaker: { after: 10, within: 60, cooldown: 300 }
+```
+
+- **Retries** — transient failures (`:retryable` / `:rate_limited_*` per the
+  error classification) retry with exponential backoff, up to `retries`.
+  A `:fatal` (auth, billing, bad request) is NEVER retried or rotated. Each
+  attempt runs on a fresh chat — the customer-visible answer comes only from
+  the attempt that returns.
+- **Fallback** — after a node's retries, the turn ROTATES to the next model in
+  the chain: the profile's `fallback` refs first, then the platform
+  `fallback_models`. The turn's usage is attributed to the model that actually
+  spoke (`model_source: "fallback"`).
+- **Circuit breaker** — per `(tenant, provider/model)`: `after` failures within
+  `within` seconds open the circuit; while open, the turn fail-fasts with the
+  typed `circuit_open` + `retry_after` (remaining cooldown) and the provider is
+  never touched. After `cooldown` a half-open trial closes the circuit on
+  success or reopens it on failure.
+- **`timeout`** — per-attempt ceiling (default 30s), counted as a retryable
+  failure.
+
+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` —
+can be answered per agent with a webhook:
+
+```ruby
+alerts webhook: "https://ops.example.com/insika-alerts"
+```
+
+When present, each such event is POSTed to the URL as JSON (the event's
+type/data/meta, plus the agent). Delivery rides the same outbox + claim +
+bounded-retry pipeline as channel answers — at-most-once, crashed deliveries
+recovered at boot. The engine transports the event and does not interpret it: a
+Slack/CRM adapter is the consumer's. Absent `alerts` = nothing is sent.
+
+Separately, with `INSIKA_TURN_TIMING`, the provider's **live TTFB** is carried in
+the streaming envelope: the first content chunk emits an `insika.ttft` frame
+(`ttft_ms`) on `/v1/responses`, alongside the per-turn `timing` breakdown on the
+final `response.completed`. Additive and opt-in — absent by default.
+
 ### Layer 5: Reasoning (thinking)
 
 Controls the model's thinking budget, resolved by precedence
@@ -422,6 +581,41 @@ and each opted-in channel gets its own frame type, never the answer's. See
 > reads. That is the operator's call, which is why it is neither a default nor a
 > global.
 
+## The stuck signal — "I cannot proceed" (WS5)
+
+The engine doesn't decide what "I can't help you" means — the consumer does. What
+the engine provides is the deterministic signal, so that a product wanting
+**human escalation** can act on it instead of regexing the answer text:
+
+```ruby
+stuck_signal true
+```
+
+With `stuck_signal` on, the model may call `signal_stuck(reason:, message:)` when it
+determines it cannot proceed (out of scope, missing data, a case a human must take
+over). The turn then **ends** — a final message is published (the model's lead-in,
+or the tool's `message` when it wrote none) — and the contract carries the signal
+twice:
+
+- the terminal event `task_completed` gains an additive sibling
+  `"outcome": "stuck"` (and the OpenAI `response.completed` frame too), so a
+  consumer that only reads the response can react;
+- a dedicated `:turn_stuck` event is published with the `agent`, the `reason`, and
+  the final `message` — the subscription point for an operator inbox.
+
+```jsonc
+{ "type": "turn_stuck",
+  "data": { "agent": "store-support", "reason": "order outside my scope",
+            "message": "I'll transfer you to our human team." } }
+```
+
+Nothing about handing off, pausing, or resuming is in scope here — escalation is a
+consumer concern. How a human joins the conversation is exactly what
+`MessageOrigin.operator` ([Refinement](REFINEMENT.md#who-wrote-a-message)) stamps
+an imported transcript with; this workstream provides the point at which that
+handoff is *triggered*. Off by default (parity): without `stuck_signal`, the tool
+is not wired and the outcome never appears.
+
 ## Refinement
 
 `refinement` configures how an agent's own traffic is read back as a report — what
@@ -438,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
@@ -484,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).