insika 0.3.0 → 0.7.0

data/docs/AGENTS.md

@@ -1,6 +1,6 @@
 ---
 title: Agents
-parent: Build an agent
+parent: Core concepts
 nav_order: 1
 permalink: /agents/
 ---
@@ -70,6 +70,23 @@ injected text as the customer repeating themselves. See
 ## The AgentProfile
 
 A profile is built through one front door — `AgentProfile.build(id:, model: nil, …)`.
+`model`/`provider` are a straight pass-through to [RubyLLM](https://rubyllm.com) — Insika
+keeps no allowlist of "supported" models. Whatever RubyLLM's installed version
+reaches, an agent can name: today that's 13 provider adapters (Anthropic, OpenAI,
+Gemini, DeepSeek, Bedrock, Vertex AI, Azure, Mistral, xAI, OpenRouter,
+Perplexity, Ollama, GPUStack) and every model each one exposes — see
+[rubyllm.com/available-models](https://rubyllm.com/available-models/) for the
+current, live catalog. Upgrading the `ruby_llm` gem is the only thing that ever
+widens this list; no Insika code changes with it.
+
+Wire a provider's credentials once in the Studio's **Settings → LLM providers**
+(or `POST /v1/settings`) — `api` is any slug RubyLLM recognizes, and
+`LLMConfigurator` applies it by reflection (`<api>_api_key=`, `<api>_api_base=`),
+so a provider RubyLLM doesn't expose an accessor for is skipped, never a hard
+error. To *restrict* which models an agent may use — the opposite direction —
+declare `model_policy: { allow: [refs] }` on its profile (exact `"provider/model"`
+refs or a `"provider/*"` wildcard); absent means no fence, every configured
+model is fair game.
 A prompt file is **text**. Passing a structured value where the markdown belongs —
 a `{"content": …}` wrapper in a pack, or a store entry read and written back — is
 rejected, not coerced: `to_s` on a Hash produces Ruby's `#inspect`, and a prompt made
@@ -246,7 +263,7 @@ 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
+> fragments that land before the turn starts. 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.
 
@@ -384,204 +401,9 @@ has promotions" from data is how a test suite starts lying.
 
 ## The five access layers
 
-What an agent may do is layered. Each layer is independent, opt-in where it
-matters, and editable hot.
+What an agent may do is layered: which tools it may call, which calls need a human, content safety, edge limits on flood and spend, and how much it may think. See [Limits and policy](POLICY.md).
 
-### Layer 1: Tools (what it can call)
-
-`tools_allow` / `tools_deny` / `tools_allow_groups` decide which tools enter the
-turn's tool-loop, enforced by the tool-allowlist policy. See [Tools](TOOLS.md)
-for how tools are defined and registered, and [`examples/data-tool/`](https://github.com/guizaols/insika/tree/main/examples/data-tool/).
-
-### Layer 2: Policies and approvals
-
-Policies are named entries evaluated before the turn runs. Builtins cover
-tool-, skill-, and workflow-allowlisting, plus **`ApprovalRequired`** — which
-does not allow or deny but *tags* a tool as needing human approval. Set
-`approvals_required: [tool names]`; the gate then fires when the model tries to
-call that tool, suspending the turn until an operator approves it in the Studio.
-See [Security](SECURITY.md#human-approval).
-
-### Layer 3: Guardrails (content safety)
-
-`guardrails` configures input/output content safety per agent — **opt-in**, so an
-agent that says nothing gets a conservative default (deterministic detectors on,
-LLM moderator off). See [Security](SECURITY.md#guardrails) and
-[`examples/guardrails/`](https://github.com/guizaols/insika/tree/main/examples/guardrails/).
-
-### Layer 4: Edge limits (flood and spend control)
-
-Two independent, opt-in ceilings, enforced *before* the model is ever called —
-opt-in everywhere except on a public channel, where `chat_rate_limit` is
-[required](CHANNELS.md#a-rate-limit-is-required-not-suggested) and the
-[web widget](CHANNELS.md#the-web-widget) refuses to serve without one:
-
-- **`chat_rate_limit`** — turn attempts per session per `chat_rate_window`.
-- **`agent_token_ceiling`** — total tokens per agent per `agent_token_window`.
-
-On breach the turn halts gracefully with a configurable `limit_response` and
-**zero LLM calls**. Windows are set at the platform level; the ceilings can be set
-per agent (blank inherits the platform value, `0` explicitly disables it).
-
-> ⚠️ The token window default is **86400 (daily)**. To express "500k tokens per
-> **hour**", set `agent_token_window = 3600` explicitly. A per-agent key that is
-> *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
-**Chat > Agent > Model > Global** (first non-blank wins):
-
-| Scope | Where |
-|-------|-------|
-| Chat | session var `__llm__.thinking` |
-| Agent | `profile.params["thinking"]` |
-| Model | platform `model_params[<ref>].thinking` |
-| Global | platform `thinking` |
-
-Values: `off | on | low | medium | high`. `off`/`on` toggle thinking; the effort
-levels map to the provider's thinking-effort parameter. This is a control
-primitive, not a latency lever — turning reasoning off does not necessarily speed
-up a turn, because most of a turn's latency is the provider itself, not thinking.
-
-Whether the reasoning ever reaches the **customer** is a separate switch, off by
-default:
-
-```ruby
-edge_stream thinking: true, intermediate: false
-```
-
-`thinking` is the provider's reasoning; `intermediate` is the model narrating its
-own tool loop ("let me look that up"). Both are always on the event stream for the
-Studio and the trace — this decides only whether `/v1/responses` translates them,
-and each opted-in channel gets its own frame type, never the answer's. See
-[Architecture](ARCHITECTURE.md#what-crosses-the-edge).
-
-> ⚠️ Turn it on knowing your consumer. One that concatenates every text delta into
-> a single message — a WhatsApp adapter — will only be affected once it learns to
-> read the new frames, and when it does, the deliberation is what the customer
-> 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 stuck signal — "I cannot proceed"
 
 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
@@ -677,11 +499,36 @@ 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
+the clone's golden set, judges mandatory in three shapes; the
+conversion "not worse" check against the frozen funnel baseline), and lands
 a skill **only after a human approves** — snapshot-first, append-only
 promotion log, deterministic rollback. Nothing is ever applied automatically.
 
+## Knowledge from finished conversations
+
+`knowledge` configures the post-turn learning loop documented in
+[Knowledge](KNOWLEDGE.md): after a turn completes, the engine extracts durable
+**concepts** — facts, procedures, policies, objections — and persists them for
+the agent, separate from any one customer's memory. Pack data, `distill:`'s
+shape, and absent = off for that agent:
+
+```ruby
+knowledge extract: true,
+          types: %w[fact policy objection]  # what the extractor may emit
+          # prompt: "<what counts as a concept for THIS store>" (the forge's half)
+          # model:  "<ref — absent = the platform utility_model>"
+```
+
+The model proposes `name`/`description`/`type`/`body`; the engine stamps
+`provenance`/`confidence`/`sources`/timestamps itself (a model-authored one
+of those is dropped, never trusted) and redacts the body for PII. Writing a
+concept name that already exists never blindly overwrites: the engine
+decides same claim (bump the evidence), related claim (merge, one extra
+model call), or contradicting claim (never merged — appended under a
+heading, confidence drops, a human resolves it in the Studio's Knowledge
+page). Nothing is injected into a turn's prompt yet — see
+[Knowledge](KNOWLEDGE.md#whats-not-here-yet) for what's not here.
+
 ## Delegation (subagents)
 
 An agent can delegate to **subagents**: named child agents it may invoke as a
@@ -728,89 +575,11 @@ 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):
+## Media
 
-```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"] }
-}'
-```
+Photos, voice notes and documents travel through the message contract as additive content parts, and the engine can hand generated images back the same way. See [Media](MEDIA.md).
 
-```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)
+## Customer-scoped memory and the right to be forgotten
 
 Memory is naturally **per customer, not per tenant**. A message that carries a
 `customer` key moves the engine's memory scope to that person:
@@ -842,11 +611,12 @@ curl -X POST /v1/messages?stream=false -H "Authorization: Bearer $TOKEN" \
   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.
+  store, so even a cell whose session was already deleted goes), its outcome
+  records and its artifacts (a report is content, never kept behind an
+  offboarded tenant): `{ "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
@@ -857,135 +627,56 @@ curl -X POST /v1/messages?stream=false -H "Authorization: Bearer $TOKEN" \
   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.
+  customer content, and nothing else ever collected them. Artifacts (reports)
+  likewise expire on their **own** knob, `artifact_ttl_days` (settings; absent
+  = OFF) — the guarantee that PII inside a report dies even in a deployment
+  that keeps its conversations forever. See [Artifacts](ARTIFACTS.md).
 
-## Outcomes — business results over real traffic (WS7)
+## Outcomes and follow-ups
 
-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`:
+What the agent's traffic was worth in business terms, and the tool that lets it come back later on a promise it made. See [Outcomes and follow-ups](OUTCOMES.md).
 
-```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
-```
+## Schedules — recurring turns the engine fires
 
-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:
+The operator's counterpart to follow-ups: a turn **nobody sends** — the daily
+report at 22:00, the eval sweep every night. Declared per agent as pack data
+(`schedule "daily_report", cron: …, tz: …, message: …` or `every: N`), edited
+hot in the Studio's Schedules config group, fired by the engine's own tick
+one turn per claim window, never queued, no catch-up after a downtime (each
+missed window is a recorded skip, visible in the Studio):
 
 ```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
+agent = Insika.agent("reporter") do
+  schedule "daily_report", cron: "0 22 * * *", tz: "America/Sao_Paulo",
+           message: "Run the daily report now.",
+           overrides: { turn_timeout: 900, max_tool_calls: 200 }
 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).
+The run is a first-class turn stamped `origin: "scheduled"`; `session_mode:
+"new"` gives it a fresh session per run (the report shape), `"fixed"` a
+standing one; per-run `overrides` raise the chat-time ceilings a report needs.
+A hard calendar budget at its cap skips instead of burning the store's tokens.
+Distinct by shape and by law from the follow-up tool. See
+[Schedules](SCHEDULING.md).
+
+## Artifacts — a report the agent can hand you a URL to
+
+A scheduled report's natural output is not a message but a page — tables,
+sections, inline charts. The `save_artifact` tool (a registry tool, in the
+agent's `tools_allow`) gives the agent a durable destination: it hands in
+title + content and gets a URL back, which it can include in a channel message
+("today's report: <url>"). The report is stored (one per run, the listing is
+the history), served under `/studio/artifacts/…` inside a sandboxed iframe,
+optionally shared outside the Studio via an expiring signed link
+(`INSIKA_ARTIFACT_SIGNING_KEY`). The tenant binding is inherited from the
+saving agent — never a parameter the model types. Artifact content is LLM
+output and is served as untrusted. See [Artifacts](ARTIFACTS.md).
 
 ## See also
 
 - [Tools](TOOLS.md) — define, register, and troubleshoot tools.
+- [Artifacts](ARTIFACTS.md) — the report destination: the tool, the routes, the signed link.
 - [Skills](SKILLS.md) — progressive playbooks an agent loads on demand.
 - [Context](CONTEXT.md) — what fills a turn's prompt, and memory.
 - [Security](SECURITY.md) — guardrails, sandbox, approvals, edge limits.

data/docs/API.md

@@ -1,7 +1,7 @@
 ---
 title: The /v1 API
-parent: Build an agent
-nav_order: 9
+parent: Integrate
+nav_order: 1
 permalink: /api/
 ---
 
@@ -9,7 +9,7 @@ permalink: /api/
 
 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
+— 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
@@ -38,8 +38,8 @@ 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;
+2. a route branch that serves both vintages (a compatibility branch), 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.

data/docs/ARCHITECTURE.md

@@ -1,7 +1,7 @@
 ---
 title: Architecture
-parent: Understand the idea
-nav_order: 2
+parent: Start here
+nav_order: 3
 permalink: /architecture/
 ---
 
@@ -319,6 +319,7 @@ validator as the after-task hook, so both roots enforce content safety identical
 | Tools (data/manifest/MCP) | `lib/insika/tool_definition.rb`, `tool_manifest.rb`, `mcp_tool_ingestor.rb` |
 | Plugin loading (boot) | `lib/insika/plugin.rb`, `lib/insika/plugin/loader.rb` |
 | Refinement (traffic → report) | `lib/insika/refinement/*`, `lib/insika/refinement_store.rb` |
+| Post-turn learning (facts, skills, knowledge — extracted from finished conversations) | `lib/insika/distill.rb`, `lib/insika/harvest.rb`, `lib/insika/knowledge.rb`, `lib/insika/knowledge_store.rb`; the per-turn hook lives in `Executor#persist_turn`, next to `finalize_delegation` |
 | Evals (cases, judges, gate) | `lib/insika/evals/*`, `lib/insika/golden_store.rb`; `evals/run.rb` is the CLI |
 | HTTP/SSE surface | `lib/insika/server/*` |