insika 0.2.0 → 0.7.0

data/docs/ROUTER.md

@@ -0,0 +1,213 @@
+---
+title: Router
+parent: Ship it
+nav_order: 4
+permalink: /router/
+---
+
+# Session-sticky router
+
+`insika-router` is a standalone proxy that lets you run **N engine backends**
+(`WEB_CONCURRENCY=1` each) and get the same per-session guarantees a single
+worker gives you today — FIFO ordering, `collect`/`steer`, the SSE watch (see
+[DEPLOY.md "The process model"](DEPLOY.md#the-process-model)) — at N>1
+capacity. It is **entirely opt-in**: if one worker is enough for you, ignore
+this file, run the engine exactly as DEPLOY.md already describes, and nothing
+changes. Reach for the router only when you outgrow one worker and want to
+scale up.
+
+It changes nothing about the engine itself — no code in `SessionActor` or
+`Executor` is aware the router exists. It solves routing, and routing only: a
+given session's requests always land on the same backend, so that backend's
+in-memory session state is always the one being read and written.
+
+## Why this exists
+
+`WEB_CONCURRENCY>1` without sticky routing in front is not "reduced
+guarantees" — it is a correctness bug (a reply from one session can leak into
+another's transcript; `insika doctor`'s `web-concurrency` check exists because
+this happened in staging). Sticky routing is the documented escape hatch, but
+neither deploy target the engine ships for has it built in:
+
+- **Railway** does not support sticky sessions at all — traffic is randomly
+  distributed across replicas, with no configuration that changes that.
+- **Kubernetes** `Service` load-balances with no session notion, and
+  ingress-nginx's `upstream-hash-by` (the usual sticky mechanism) hashes on
+  nginx *variables* — headers, cookies, the URL — never a field parsed out of
+  a POST body. The session id here is exactly that: the `user` field inside
+  `POST /v1/responses`'s JSON body.
+
+So this is a small piece of new infrastructure, not a config flag.
+
+## How it decides where a request goes
+
+Per request, in order:
+
+1. `GET /up` → answered directly by the router (its own liveness), never
+   proxied.
+2. `POST /v1/responses` or `POST /v1/messages` → the session key is the
+   `user` field of the JSON body.
+3. `POST /channels/:id/messages` or `POST /channels/:id/events` (the web
+   widget and the relay channel) → the session key is the `session_id` field
+   of the JSON body.
+4. Everything else (health checks, `/studio/*`, onboarding, minting a new
+   channel session) → no session key, plain round-robin. None of these depend
+   on a worker's in-memory `SessionActor` — a Studio read hits the durable
+   store, and minting a session has no existing state to be sticky about.
+
+A request with a session key is routed by a ketama-style **consistent hash
+ring** over the backend list: the same key always reaches the same backend,
+and adding or removing one backend remaps only ~1/N of the key space, not the
+whole ring — a rolling deploy does not bounce every live session to a new
+owner at once. A request whose key isn't found (a corner-case route) or whose
+key extraction is skipped (see body size cap below) round-robins across all
+backends.
+
+The whole request body is always read and forwarded byte-for-byte —
+`INSIKA_ROUTER_BODY_MAX_BYTES` (default 256 KiB) only bounds how much of it
+the router will attempt to parse as JSON while looking for a session key; a
+body over that cap round-robins instead of erroring, and the router logs it.
+
+**A request whose chosen backend is unreachable is never retried against a
+different backend** — that backend may already hold a durable, at-most-once
+claim on the task the request names, and retrying elsewhere could
+double-process it. It answers the same retry envelope a single overloaded
+backend would:
+
+```json
+{"error": {"class": "Insika::Router::BackendUnavailable", "message": "no backend reachable",
+           "retryable": true, "retry_after": 1}}
+```
+
+SSE responses stream through the router with no added buffering — a client
+watching a long turn sees the same chunks, in the same order, as if it had
+hit the backend directly.
+
+## Deploy shape 1 — Railway (N local workers, one replica)
+
+Railway's replica load balancer has no sticky option, full stop — this shape
+does not attempt to fix that. What it fixes is the *unsafe* alternative
+(`WEB_CONCURRENCY=N` Falcon workers behind Railway's own port, which is
+exactly the leak `insika doctor` errors on). Instead, run N engine processes
+on different local ports and put the router in front of them, all inside the
+one container Railway load-balances to:
+
+```bash
+# three engine workers, WEB_CONCURRENCY=1 each (the entrypoint's own
+# `falcon serve --count 1`), on different local ports — never `--count 3` on
+# one port, which is exactly the unsafe fan-out this replaces
+bundle exec falcon serve --bind http://127.0.0.1:9292 --count 1 config.ru &
+bundle exec falcon serve --bind http://127.0.0.1:9293 --count 1 config.ru &
+bundle exec falcon serve --bind http://127.0.0.1:9294 --count 1 config.ru &
+
+# the router, bound to the port Railway actually forwards
+INSIKA_ROUTER_PORT=$PORT \
+INSIKA_ROUTER_BACKENDS=http://127.0.0.1:9292,http://127.0.0.1:9293,http://127.0.0.1:9294 \
+  bundle exec insika-router
+```
+
+`insika doctor` treats `WEB_CONCURRENCY>1` as `ok` (not `error`/`warn`) once
+it sees `INSIKA_ROUTER_BACKENDS` or `INSIKA_ROUTER_BACKENDS_DNS` set — it
+cannot verify a router process is actually running at those addresses, only
+that one was configured, same as every other env-based capability check in
+`insika doctor`.
+
+## Deploy shape 2 — Kubernetes (a headless Service)
+
+Run N engine pods (`WEB_CONCURRENCY=1` each) behind a **headless** Service
+(`clusterIP: None` — this is what makes DNS resolve to one A/AAAA record per
+ready pod instead of a single virtual IP), and the router as its own
+Deployment in front:
+
+```yaml
+apiVersion: v1
+kind: Service
+metadata:
+  name: insika-headless
+spec:
+  clusterIP: None
+  selector: { app: insika }
+  ports: [{ port: 9292 }]
+---
+# insika-router Deployment env:
+env:
+  - name: INSIKA_ROUTER_BACKENDS_DNS
+    value: insika-headless.default.svc.cluster.local
+  - name: INSIKA_ROUTER_BACKEND_PORT
+    value: "9292"
+  - name: INSIKA_ROUTER_DNS_INTERVAL
+    value: "15"
+```
+
+The router holds no session state itself, so it needs no sticky routing in
+front of *itself* — it scales trivially (1-2 replicas behind an ordinary
+`Service`). It re-resolves the headless Service on `INSIKA_ROUTER_DNS_INTERVAL`
+(default 15s) and rebuilds its hash ring only when the resolved pod set
+actually changed. A pod that just became ready is invisible to the router
+until the next resolve — capacity added a few seconds late, never wrong.
+
+## Environment variables
+
+| Variable | Default | Meaning |
+|---|---|---|
+| `INSIKA_ROUTER_BACKENDS` | — | Comma-separated backend URLs (static mode). Exactly one of this or the DNS var below. |
+| `INSIKA_ROUTER_BACKENDS_DNS` | — | A headless-Service hostname to re-resolve (DNS mode). Requires `INSIKA_ROUTER_BACKEND_PORT`. |
+| `INSIKA_ROUTER_BACKEND_PORT` | — | The engine port on every DNS-resolved pod. |
+| `INSIKA_ROUTER_DNS_INTERVAL` | `15` | Seconds between DNS re-resolves. |
+| `INSIKA_ROUTER_BODY_MAX_BYTES` | `262144` | Size cap on the session-key JSON peek (never on what is forwarded). |
+| `INSIKA_ROUTER_BACKEND_TIMEOUT` | `10` | Connect/read timeout to a backend, in seconds. |
+| `INSIKA_ROUTER_HOST` | `0.0.0.0` | Bind address for the router itself. |
+| `INSIKA_ROUTER_PORT` | `9090` | Listen port for the router itself. |
+
+## A runnable smoke test
+
+The shape below is what the router's acceptance criteria were verified
+against: two fake backends and the router in front, run entirely in-process.
+
+```ruby
+require "async"; require "async/http/server"; require "async/http/client"
+require "async/http/endpoint"; require "protocol/rack"; require "insika/router"
+
+Async do |task|
+  echo = ->(name) { ->(env) { [200, {}, ["#{name} #{Rack::Request.new(env).path_info}"]] } }
+  %w[9292 9293].each_with_index do |port, i|
+    endpoint = Async::HTTP::Endpoint.parse("http://127.0.0.1:#{port}")
+    task.async { Async::HTTP::Server.new(Protocol::Rack::Adapter.new(echo["backend-#{i}"]), endpoint).run }
+  end
+  task.sleep(0.2)
+
+  pool = Insika::Router::BackendPool.new(static: %w[http://127.0.0.1:9292 http://127.0.0.1:9293])
+  app = Insika::Router::App.new(pool: pool)
+  endpoint = Async::HTTP::Endpoint.parse("http://127.0.0.1:9090")
+  task.async { Async::HTTP::Server.new(Protocol::Rack::Adapter.new(app), endpoint).run }
+  task.sleep(0.2)
+
+  client = Async::HTTP::Client.new(Async::HTTP::Endpoint.parse("http://127.0.0.1:9090"))
+  3.times { |i| puts client.post("/v1/responses", {}, [%({"user":"sess-1","i":#{i}})]).read }
+  # -> the same "backend-N" answers all three times, even though two backends are up.
+ensure
+  task.stop
+end
+```
+
+## What this deliberately does not attempt
+
+- **Railway cross-*replica* routing.** Railway's replica load balancer itself
+  has no sticky option and this router cannot sit in front of Railway's own
+  edge. Railway stays at one replica; this only raises the ceiling of that one
+  replica (N local workers instead of N=1).
+- **A distributed `SessionActor`.** The alternative design — making any
+  worker able to safely pick up any session, removing the need for sticky
+  routing entirely — is a much larger rewrite (debounce windows, steer
+  mailboxes, and SSE fan-out would all have to move into the shared store with
+  lease semantics) for the same outcome this router reaches with an unchanged
+  engine. Worth revisiting only if this approach turns out not to scale far
+  enough.
+- Native WhatsApp/Slack channel routing — those channels are shelved; the
+  relay channel rides the same `/v1/responses`-shaped call this router already
+  covers.
+
+## See also
+
+- [DEPLOY.md "The process model"](DEPLOY.md#the-process-model) — the contract
+  this router satisfies (FIFO/`collect`/`steer` guarantees, recovery, drain).

data/docs/RUNNING-LOCAL.md

@@ -1,14 +1,14 @@
 ---
 title: Running locally
-parent: Build an agent
-nav_order: 8
+parent: Start here
+nav_order: 2
 permalink: /running-local/
 ---
 
 # Running the Insika locally
 
 Boots the engine single-process, serving `/studio` and `/v1/*` against a demo
-agent (the `bia` persona on DeepSeek). Every message runs the **same**
+agent (the `demo` agent on DeepSeek). Every message runs the **same**
 `send_message` the API runs — real tools, skills, and memory.
 
 ## Boot
@@ -26,7 +26,7 @@ Open `http://localhost:9292`:
 | URL | What |
 |-----|------|
 | `/studio` | management UI (log in with the token; default `local-demo`) |
-| `/studio/chats` | chat with the demo agent (`agent: bia`, `session_id: web`, multi-turn ready) |
+| `/studio/chats` | chat with the demo agent (`agent: demo`, `session_id: web`, multi-turn ready) |
 | `/studio/tasks` | tasks / approvals console |
 | `/v1/responses` | OpenAI-Responses ingress (Bearer) — the drop-in API contract |
 | `/v1/agents` | provisioning by definition/pack (Bearer) — `POST` imports, `DELETE /:id` removes |
@@ -82,7 +82,7 @@ the `model`:
 curl -N http://localhost:9292/v1/responses \
   -H "Authorization: Bearer local-demo" \
   -H "Content-Type: application/json" \
-  -d '{ "model": "bia", "user": "web", "stream": true, "input": "hello" }'
+  -d '{ "model": "demo", "user": "web", "stream": true, "input": "hello" }'
 ```
 
 `user` is the session id (any stable id for a multi-turn conversation).
@@ -122,7 +122,7 @@ prompt files, skills, and one data-tool per file:
 > **Data-tool URLs must be literal on the pack path.** The pack import does not
 > resolve `{{env.*}}` — bake the backend base URL into each `tools/*.json` at
 > generation time. (Only the *manifest* path resolves `{{env.*}}`.) See
-> [Tools](TOOLS.md#the-one-gotcha-env-templating-is-manifest-only).
+> [Tools](TOOLS.md#the-one-gotcha-envsecret-templating-is-manifest-only).
 
 Provision it (runs as a client against the live server; the internal token comes
 from the environment, never disk):

data/docs/SCHEDULING.md

@@ -0,0 +1,121 @@
+---
+title: Schedules
+parent: Operate
+nav_order: 2
+permalink: /schedules/
+---
+
+# Schedules — recurring turns the engine fires
+
+A schedule is a turn nobody has to remember to send: a daily report at 22:00,
+an eval sweep every night, a heartbeat every hour. The engine fires it on its
+own periodic tick — no cron on some other box pointing at an authenticated
+route. (That route still works, if you want it; the built-in trigger just
+removes the homework.)
+
+A schedule is **declared on the agent** — pack data, like `followup:` or the
+budget — in one of the same three places every profile field is edited: the
+DSL at import, `POST /v1/agents` in the pack, or the Studio's config form
+(the **Schedules** group on the agent page). Edits are hot: the next pass
+sees them.
+
+## The declaration
+
+```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 }
+  schedule "heartbeat", every: 3600, message: "Say you are alive."
+end
+```
+
+| Key | Meaning |
+|---|---|
+| `id` | the schedule's name (the argument). Lowercase, `[a-z][a-z0-9_-]*` |
+| `cron` | a five-field expression (`minute hour day-of-month month day-of-week`), or |
+| `every` | a plain interval in seconds — the two are **exclusive** |
+| `tz` | IANA zone for **cron** materialization (default `Etc/UTC`). `every` never needs it — every comparison runs in UTC |
+| `message` | the synthetic inbound that kicks each run — what the agent "hears" |
+| `session_mode` | `"new"` (default) — a fresh session per run, the report shape; `"fixed"` — one standing session, the "standing assistant" shape |
+| `session_id` | for `fixed` sessions: the standing session (created on first run when missing) |
+| `overrides` | per-run ceilings: `turn_timeout`, `max_tool_calls`, `model` — a report needs a bigger ceiling than a chat turn; the base profile is untouched |
+| `enabled` | `false` pauses the schedule (the Studio toggle / the JSON field) |
+
+> **The cadence floor.** Firing rides one claim window per pass — a schedule
+> fires **at most once per window**. That is the true cadence ceiling: an
+> `every: 60` does not fire sixty times a minute, it fires once per window.
+> `doctor` warns when a declared `every` is shorter than the claim window.
+
+The Studio renders the schedules section as a JSON array of the same
+declarations plus a read-only card: each schedule's next fire, last run and —
+when a window was skipped — the skip reason. `doctor` parses every
+declaration with the engine's own parser: an invalid cron, an unknown
+runtime zone, a schedule with neither trigger, an unknown override key —
+each is named, per agent, as an error finding.
+
+## The engine's triggers: cron subset
+
+Five fields, whitespace-separated. Per field: `*` (or `?`), a single value, a
+range (`N-M`), a step (`*/N`, `N-M/N`, `N/N`), or a comma list of those.
+Day-of-week is `0-7` with `7` = Sunday; when **both** day fields are
+restricted the date matches on **either** (standard cron OR semantics).
+`L`, `W`, `#` and month/day names are refused loudly at creation — the engine
+will not silently ignore a cron that only some dates understand.
+
+```text
+ minute  hour  day-of-month  month  day-of-week
+   0      22        *          *         *
+```
+
+## Firing: one turn per window, no catch-up
+
+Firing rides the tick, gated by its own claim window (one scheduler per
+window across `N` workers — the same claim the outbox and recovery sweeps
+use). Each due schedule is claimed transactionally: the task and the
+schedule's state (last run, last task id, next fire) commit together, so two
+workers racing serialize on the backend's lock and **exactly one fires per
+window**.
+
+Three skip rules are part of the contract, all recorded on the schedule and
+shown in the Studio — never silent, never queued:
+
+- **late** — the no-catch-up policy. A window more than one claim window in
+  the past is **missed, not replayed**: a deploy that was down over 22:00 does
+  not fire a 22:00 report at 06:00 the next morning. The schedule's lattice
+  advances to the next window and the skip is recorded.
+- **overlap** — the previous run's task is still live (`queued`/`running`/
+  `waiting`/`paused`). The window is skipped, recorded, and the next one
+  fires. There is no queue buildup: one scheduled run at a time per schedule.
+- **budget** — a **hard** calendar budget (`budget daily: …` on the profile)
+  already at/over its cap. The edge would fail the turn anyway; the engine
+  refuses to even queue it. A `soft` budget crosses and runs — the ledger
+  warns as usual.
+
+A bounded run also costs what it costs: the run's usage lands on the same
+`BudgetLedger` the edge enforces, and `billed = total + cached +
+cache_creation` — a long report is cache-heavy, measure the caps against it.
+
+## What a schedule run is
+
+A first-class turn, stamped `origin: "scheduled"` so a refinement read can
+never mistake the engine's kick for a customer speaking. It enters through the
+pipeline directly (never through the message edge, so no rate-limit/token
+ceiling gate applies — same as a resume), is charged to the ledger like any
+turn, and its result is delivered wherever the agent's outputs go: a channel
+answer, or – for the report shape – nothing at all, when the run publishes an
+artifact instead. The Studio's schedule card links the last run's task.
+
+No customer ever receives anything from a schedule unless your agent sends a
+message in reply — the engine contacts no one.
+
+## The boundaries
+
+- **Not a job queue.** No priorities, no fan-out, no retries of a failed run
+  beyond what Recovery already does for any task.
+- **Not the follow-up feature.** `schedule_followup` is a one-shot,
+  customer-facing, consent-gated contact from inside a conversation — and it
+  keeps being that. These schedules are operator-declared recurring internal
+  triggers: no contact policy, no consent, no customer.
+- **Not a replacement for your cron.** The external route stays; this is the
+  built-in one.

data/docs/SECURITY.md

@@ -171,7 +171,7 @@ LLM calls**. A *resumed* turn is never re-counted.
 > `0` to explicitly disable. A malformed value in the Studio raises a validation
 > error rather than silently disabling a production limit.
 
-See [Agents §Layer 4](AGENTS.md#layer-4-edge-limits-flood-and-spend-control).
+See [Agents §Layer 4](POLICY.md#layer-4-edge-limits-flood-and-spend-control).
 
 ## Guardrails
 
@@ -203,7 +203,7 @@ Strictness selects the detector categories (`low` = injection only; `medium`
 (default) and `high` add sexual and abuse). Safe-reply lookup falls back per
 category: the agent's category reply → the agent's default → the builtin
 category → the builtin default. All of it is editable in the Studio Configuration
-form. See [Agents §Layer 3](AGENTS.md#layer-3-guardrails-content-safety).
+form. See [Agents §Layer 3](POLICY.md#layer-3-guardrails-content-safety).
 
 ## Human approval
 
@@ -367,6 +367,83 @@ rotated key or a typo never takes the whole service down. The `insika doctor`
 command runs the same checks on demand against a live database. See
 [Deploy](DEPLOY.md#strict-config-and-insika-doctor).
 
+## Memory and the right to be forgotten (LGPD)
+
+Memory is scoped per **`(tenant, customer)`** — the cell `"memory:<tenant>:<customer>"`
+is the isolation boundary. A query against one tenant never touches another's
+cells. A turn with no customer falls back to the session's own **marked** cell
+(`"memory:chat:<session id>"`) — the marker keeps the Studio drill and the doctor
+from ever reading a conversation as a customer (a bare `memory:<id>` cell is
+indistinguishable from a single-tenant customer ref). Cells written before the
+marker (bare session ids) may still appear as customers in the drill until
+forgotten or aged out. Three operations enforce the right to be forgotten:
+
+- **Retention** — the `memory_ttl_days` setting (platform default per cell, or an
+  ops-authored per-tenant map) sweeps facts older than the window. A per-fact
+  `expires_at` override wins over the cell TTL. Both run on the daily retention
+  tick, **not** gated by `retention_days` (the conversation-footprint window).
+  Note the interaction: an explicit `expires_at` also exempts the fact from the
+  `retention_days` age-based sweep — an explicit date owns that fact's life, so a
+  far-future date makes the fact immune to *both* age passes. Export and forget
+  still see it; the only way to remove it early is the Customers drill.
+- **Export** — `export_customer_memory` returns the full fact + note content to the
+  **operator** (the Studio turns it into a JSON download). The emitted event carries
+  counts only — the event stream, the audit store and every log stay content-free.
+- **Forget** — `forget_customer` purges the customer's memory cell AND their
+  sessions (and everything those sessions left behind: traces, tasks, checkpoints,
+  outbox deliveries). The operator-mutation audit store records a digest-free line
+  ("a purge happened, with N records") — content-free by construction.
+
+### Distilled facts are personal data
+
+The distillation loop ([Facts](FACTS.md)) writes **proposals** — a distilled
+fact's name and value are personal data, and they are treated like the rest of
+the memory footprint: `forget_customer` deletes the person's proposals (every
+status), `delete_tenant_data` deletes a tenant's, and the `retention_days`
+sweep ages them out with the transcripts they were distilled from. Provenance
+holds: an approved fact is written with `origin: "distilled:<session_ref>"`
+(the closed set gains one spelling, never an open string). Events and
+audit carry ids and counts only — a fact value never enters the stream, the
+ledger or a log; the evidence excerpt is a link read from the transcript at
+request time, never a copy.
+
+The doctor's `memory-scopes` check flags bare cells only in a `multi_tenant`
+deployment (in `single_tenant` the bare cell is the designed customer shape), and
+never the session-marked cells. See [Context](CONTEXT.md#memory) and
+[Deploy](DEPLOY.md#strict-config-and-insika-doctor).
+
+### Harvest candidates are derived data
+
+The harvest loop ([Harvest](HARVEST.md)) writes **candidates** — a mined skill
+proposal is behavior instructions, the same trust level as any skill content,
+and it is store-scoped, never customer-scoped: `forget_customer` does NOT reach
+it (a candidate's skill body is not customer content). Candidates reference
+sessions by id and their evidence excerpt is the transcript rendered at request
+time through the output filter — never a copy. `delete_tenant_data` purges a
+tenant's candidates, promotion rows and markers; the `retention_days` sweep
+ages them out with the transcripts they were derived from (they are
+re-derivable — pruning is never data loss). **No auto-application**: nothing
+reaches the catalog without a human click, and the grounding filter refuses any
+product claim the origin sessions' evidence ledger did not see. Events and the
+promotion log carry ids, refs and verdicts only — a skill body never enters
+the stream.
+
+### Learned knowledge is redacted before it is stored
+
+The [Knowledge](KNOWLEDGE.md) loop writes **concepts** extracted from finished
+conversations — store-scoped, not customer-scoped, but written from real
+transcript text, so the write path is deliberately conservative: a concept's
+body goes through the same PII/secret redactor the output guardrail uses
+before it is ever persisted, and `sources` holds session ids only — never
+message content, never a customer identifier. This is the one write path in
+the engine where a model-authored field is rejected outright rather than
+merely validated: `provenance`, `confidence`, `sources` and the timestamps are
+stamped by the engine, so a model cannot self-assign trust it did not earn or
+smuggle a scope into a store-wide record. A repeat sighting that contradicts
+what's on record is never silently merged — the conservative default when
+the engine cannot tell is to flag it for a human, not to guess. Events carry
+names and counts only — a concept's content never enters the stream.
+
 ## See also
 
 - [Agents](AGENTS.md) — the five access layers per agent.

data/docs/SKILLS.md

@@ -1,7 +1,7 @@
 ---
 title: Skills
-parent: Build an agent
-nav_order: 3
+parent: Core concepts
+nav_order: 4
 permalink: /skills/
 ---
 
@@ -16,6 +16,14 @@ while paying for the text of only the ones it opens.
 
 See [`examples/skills/`](https://github.com/guizaols/insika/tree/main/examples/skills/) for a runnable one.
 
+**Skills vs. Knowledge.** They share a format — YAML frontmatter over a
+Markdown body, progressive loading — which makes them easy to confuse. A
+skill is **curated**: a human writes it, and it is canonical until a human
+changes it. A [Knowledge](KNOWLEDGE.md) concept is **learned**: the engine
+extracts it from finished conversations, it is `provenance: observed`, and it
+sits below skills in the context priority ladder — earned trust, not
+authored trust.
+
 ## Format
 
 ```markdown
@@ -219,8 +227,8 @@ Write one with `agent:`, and remove it the same way (which un-specializes, leavi
 the shared skill in place):
 
 ```ruby
-dispatch(:write_skill,  { name: "escalation-to-human", agent: "store-cacau", content: md })
-dispatch(:delete_skill, { name: "escalation-to-human", agent: "store-cacau" })
+dispatch(:write_skill,  { name: "escalation-to-human", agent: "store-demo", content: md })
+dispatch(:delete_skill, { name: "escalation-to-human", agent: "store-demo" })
 ```
 
 In the Studio: **Skills → specialize for this agent**, which seeds the override from
@@ -281,4 +289,5 @@ reading the doctor:
 - [Agents](AGENTS.md) — the skills allowlist.
 - [Tools](TOOLS.md) — `load_skill` and deferred-tool progressive disclosure.
 - [Plugins](PLUGINS.md) — shipping skills inside a plugin, and the two extension tiers.
+- [Knowledge](KNOWLEDGE.md) — the learned counterpart: engine-extracted concepts, same format, earned trust.
 - [`examples/skills/`](https://github.com/guizaols/insika/tree/main/examples/skills/) — progressive loading, runnable.

data/docs/SOAK.md

@@ -0,0 +1,127 @@
+---
+title: Soak
+parent: Operate
+nav_order: 5
+permalink: /soak/
+---
+
+# SOAK — does it degrade over uptime?
+
+The soak is the third question the measurement toolbox answers, and it is the
+one the other two cannot:
+
+| Tool | Question | Drives |
+|------|----------|--------|
+| [`scripts/bench.rb`](BENCHMARK.md) | How much overhead does the engine itself add? | publishable claims |
+| [Load test](LOADTEST.md) | What does a burst look like, end to end? | topology + provider choice |
+| **`insika soak`** | **Does the deploy degrade over 72 hours of steady load?** | the cut argument: "it does not tax uptime" |
+
+A load test fires a wave, joins it, and reports. A soak **sustains a declared
+arrival rate for days** and asks whether the *process itself* — resident memory,
+per-turn local work, restarts — degrades with uptime. A leak that only shows at
+hour 40 is invisible to a 10-minute bench.
+
+## The protocol in one paragraph
+
+1. **Freeze the envelope first.** A deployment-side envelope file declares the
+   load shape, the gated ceilings and the isolation contract — *before* the
+   first turn is fired. Its SHA-256 is stamped into every hourly snapshot;
+   editing it mid-run turns the run `invalid` instead of producing a verdict.
+2. **Preflight.** `insika soak --preflight` refuses to start unless the target
+   answers `/v1/vitals` with a readable RSS, turns carry the `INSIKA_TURN_TIMING`
+   breakdown *and* a `usage` block, the pid is stable, and the target host
+   matches the envelope. Each check is a named refusal, not a runtime warning.
+3. **Run.** `insika soak --run` fires the arrival process (Poisson, seeded,
+   concurrency-capped), polls vitals hourly, and appends every observation to
+   `<out>/<run>.jsonl` as it happens — a runner that dies at hour 60 must
+   leave 60 usable hours behind. No retry, no self-healing: a failed turn is
+   evidence.
+4. **Read the verdict.** `insika soak --verify <file>.jsonl.gz` recomputes the
+   whole verdict offline from the raw records — no network, no target, no
+   clock. Two people running it get the same answer; so does CI.
+
+## What is gated, and what is only reported
+
+The gate is on the part **Insika owns**:
+
+| Gated (binding) | Reported (never gated) |
+|-----------------|------------------------|
+| `rss_growth_ratio` — upper 95% bound of the RSS fit, hour 6 → hour 72 | `rss_slope_mb_per_day`, `rss_peak_mb` |
+| `prep_p95_drift_ratio` — p95 of the local per-turn work (`prep_ms`: context build, policy, guardrails, chat assembly), last 6 h vs first measured 6 h | `ttft_p95_ms`, `total_p95` hourly series |
+| `restarts_max` — any `boot_id` **or** `pid` change is a fail; there is no "declared deploy" exception | `heap_growth_ratio`, `db_growth_mb` |
+| `error_rate_ceiling`, `no_usage_rate_ceiling` | `cost_usd`, `tokens_per_turn` |
+| calibrated absolute ceilings (written from the E1 dry run, ×2) | — |
+
+Time-to-first-token is **reported, never gated**: it was measured at ~720 ms and
+shown to be ~100% provider. Gating on a number the engine cannot move would mean
+failing a clean soak because the provider had a bad afternoon — and then
+loosening the envelope, which the protocol forbids.
+
+The **`no_usage_rate`** ceiling is the trap detector. The edge limiter answers a
+breach with a canned reply, zero LLM calls and HTTP 200 — so a soak that ran
+entirely into the limiter looks like thousands of successful turns with a
+gorgeous 2 ms p95 and flat memory. A turn with no `usage` block called no model;
+the ceiling keeps that from reading as a pass.
+
+## The isolation contract
+
+- **Staging or a dedicated tenant, never a production tenant.** The run writes
+  ~4,000 sessions and tasks into the store; against production that is
+  synthetic data mixed into real customer history. The envelope names the
+  tenant (`soak`), so `delete_tenant_data` cleans the entire run in one
+  command.
+- **Its own agent, with the edge limits off.** At a real ~48k tokens per turn,
+  the production token ceiling admits about 10 turns per hour — a 60 turns/h
+  soak against a production-configured agent measures its own limiter within
+  minutes. `chat_rate_limit: 0` and `agent_token_ceiling: 0` on the soak agent
+  are part of the frozen envelope, not an afternoon decision.
+- **Deploys are frozen for the window.** Any restart is a fail, including a
+  deployment — a marker the operator writes after the fact would turn every
+  crash into a deploy.
+
+## Running it
+
+```bash
+# the plan + one sample request, no traffic
+insika soak --dry-run --envelope soak-envelope.md
+
+# every precondition, and nothing else
+insika soak --preflight --envelope soak-envelope.md
+
+# the run itself (INSIKA_URL + OPENCLAW_GATEWAY_TOKEN, like loadtest.rb)
+INSIKA_URL=https://<target> insika soak --run --envelope soak-envelope.md --out soak-out/
+
+# resume after a short outage (the gap is recorded and counts against the window)
+insika soak --run --resume soak-out/staging-2026-08-20T09-00-00Z.jsonl
+
+# the verdict, recomputed offline — the only step that needs no target
+insika soak --verify soak-out/staging-2026-08-20T09-00-00Z.jsonl.gz
+```
+
+Duration, rate and ceilings all come from the envelope — there is no
+`--duration` override, so a short run cannot be passed off as a soak.
+
+## Reading the verdict
+
+`insika soak --verify` prints one of four, in this order of precedence:
+
+- **`invalid`** — the snapshots carry more than one envelope hash, more than
+  one process id appeared under one boot generation, or the file is materially
+  truncated. **No metric is reported at all**; the file cannot be argued with.
+- **`insufficient`** — coverage is short: a gap over 15 minutes, an hour under
+  the turn floor, or a runner that did not reach hour 72. Short coverage
+  restarts the window; it is never rounded up into a pass.
+- **`fail`** — a gated ceiling was breached. The report names each one and
+  prints the leak-hunt starting point: whether the Ruby heap grew with RSS
+  (Ruby-side retention) or stayed flat while RSS climbed (allocator or a
+  native buffer).
+- **`pass`** — none of the above.
+
+A fail means *find the leak* — never cut, and never loosen the envelope.
+
+## See also
+
+- [Observability](OBSERVABILITY.md) — `GET /v1/vitals`, the process readings
+  the soak samples hourly.
+- [Deploy](DEPLOY.md) — the process model; `WEB_CONCURRENCY=1` is a soak
+  precondition, not only a queue-semantics one.