insika 0.2.0 → 0.7.0

data/bin/insika-router

@@ -0,0 +1,87 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# `insika-router` — session-sticky router. A standalone Async/
+# Falcon process that sits in front of N engine backends and routes each
+# request to the SAME backend every time its session id resolves to (a
+# ketama-style consistent hash ring), so `WEB_CONCURRENCY=1`-per-worker's
+# session guarantees (FIFO/collect/steer, docs/DEPLOY.md "The process model")
+# hold at N>1 capacity without touching the engine itself.
+#
+# Entirely OPT-IN: an operator happy with one worker never runs this. Two
+# backend-discovery modes, picked by which env var is set (never both):
+#
+#   INSIKA_ROUTER_BACKENDS=http://host-a:9292,http://host-b:9292
+#     static list — the Railway shape (N local Falcon workers on known ports).
+#   INSIKA_ROUTER_BACKENDS_DNS=insika-headless.default.svc.cluster.local
+#     one hostname, re-resolved on INSIKA_ROUTER_DNS_INTERVAL (default 15s) —
+#     the Kubernetes shape (a headless Service, one record per ready pod).
+#     Requires INSIKA_ROUTER_BACKEND_PORT (the engine port on every pod).
+#
+# See docs/ROUTER.md for both deploy shapes end to end.
+
+require "async"
+require "async/http/server"
+require "async/http/endpoint"
+require "protocol/rack"
+
+require_relative "../lib/insika/env_schema"
+require_relative "../lib/insika/router"
+
+module Insika
+  module CLI
+    module Router
+      module_function
+
+      def main
+        Insika::EnvSchema.reconcile_legacy!
+        pool = build_pool
+        app = Insika::Router::App.new(
+          pool: pool,
+          body_max_bytes: (Insika::EnvSchema.read("INSIKA_ROUTER_BODY_MAX_BYTES") || Insika::Router::App::DEFAULT_BODY_MAX_BYTES).to_i,
+          backend_timeout: (Insika::EnvSchema.read("INSIKA_ROUTER_BACKEND_TIMEOUT") || 10).to_i
+        )
+
+        host = Insika::EnvSchema.read("INSIKA_ROUTER_HOST") || "0.0.0.0"
+        port = (Insika::EnvSchema.read("INSIKA_ROUTER_PORT") || 9090).to_i
+        endpoint = Async::HTTP::Endpoint.parse("http://#{host}:#{port}")
+
+        banner(pool, host, port)
+        Async do |task|
+          pool.start_polling(task)
+          Async::HTTP::Server.new(Protocol::Rack::Adapter.new(app), endpoint).run
+        end
+      end
+
+      def build_pool
+        static = Insika::EnvSchema.read("INSIKA_ROUTER_BACKENDS")
+        dns = Insika::EnvSchema.read("INSIKA_ROUTER_BACKENDS_DNS")
+        if static.nil? == dns.nil?
+          abort "insika-router: set exactly one of INSIKA_ROUTER_BACKENDS or INSIKA_ROUTER_BACKENDS_DNS"
+        end
+
+        if static
+          Insika::Router::BackendPool.new(static: static.split(",").map(&:strip))
+        else
+          port = Insika::EnvSchema.read("INSIKA_ROUTER_BACKEND_PORT")
+          abort "insika-router: INSIKA_ROUTER_BACKEND_PORT is required with INSIKA_ROUTER_BACKENDS_DNS" if port.nil?
+
+          Insika::Router::BackendPool.new(
+            dns: dns, dns_port: port.to_i,
+            dns_interval: (Insika::EnvSchema.read("INSIKA_ROUTER_DNS_INTERVAL") || 15).to_i
+          )
+        end
+      end
+
+      def banner(pool, host, port)
+        puts "\e[1mInsika Router\e[0m — session-sticky proxy"
+        puts "  http://#{host}:#{port}/up   → health (also this process's own liveness)"
+        mode = pool.dns? ? "dns" : "static"
+        puts "  backends (#{mode}): #{pool.backends.join(', ')}"
+        puts "  Ctrl-C to stop."
+      end
+    end
+  end
+end
+
+Insika::CLI::Router.main

data/docs/AGENTS.md

@@ -1,6 +1,6 @@
 ---
 title: Agents
-parent: Build an agent
+parent: Core concepts
 nav_order: 1
 permalink: /agents/
 ---
@@ -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**
@@ -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
@@ -97,6 +114,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 +261,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. 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 +387,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
 
@@ -351,167 +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.
-
-### 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.
-
-#### 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` |
+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).
 
-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
@@ -562,6 +454,81 @@ 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 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
@@ -608,9 +575,108 @@ 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
+
+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).
+
+## 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:
+
+```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), 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
+  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. 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 and follow-ups
+
+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).
+
+## Schedules — recurring turns the engine fires
+
+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("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 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

@@ -0,0 +1,56 @@
+---
+title: The /v1 API
+parent: Integrate
+nav_order: 1
+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
+— 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), 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/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/*` |