insika 0.1.0 → 0.3.0

data/docs/SECURITY.md

@@ -47,16 +47,26 @@ dispatch **any** registered authoring Command (`write_agent_file`, `write_data_t
 `upsert_llm_provider`, `update_settings`, `delete_agent`). Treat that token as
 operator-grade — it is not a read key, and a leak is agent takeover, not just usage.
 
-> **The auth decision (RFC-0018, decided for 0.1.0): one deployment, one token;
-> multi-tenancy belongs to the host.** There is exactly one credential per
-> surface — `OPENCLAW_GATEWAY_TOKEN` for `/v1`, `ADMIN_TOKEN` for the Studio —
-> and no per-caller scoping inside the engine. That is what the code has always
-> done; this paragraph is the decision written down so nothing built on top
-> inherits an assumption nobody stated. Serving two tenants from one mount means
-> putting the app behind your own authentication (see
-> [Embedding](EMBEDDING.md#embedding-is-not-multi-tenancy)), and scoped auth —
-> one mount, several tokens with different powers — is a real RFC the day an
-> adopter needs it, not a someday.
+### Multi-tenant mode (`INSIKA_TENANCY=multi_tenant`)
+
+A single operator-grade token cannot host N stores. With `INSIKA_TENANCY=multi_tenant`
+the Bearer is resolved to a **principal** before the routes:
+
+- **Per-tenant tokens** (`POST /v1/commands/issue_tenant_token`) scope a caller to
+  one tenant; **operator** tokens (and the legacy gateway token — an existing
+  deployment switching modes keeps its credential) have the run of the deployment.
+- Tokens are stored **only as SHA-256 hashes**; the plaintext is shown exactly once,
+  at issue time. Rotation (`rotate_tenant_token`) and revocation (`revoke_token`)
+  are operator commands — revoking one tenant's token never touches another's.
+- A tenant principal reaches only its **own runtime surfaces** (`/v1/sessions`,
+  `/v1/messages`, `/v1/responses`, workflow runs, and its own session/task/event
+  reads). Every authoring/provisioning/config surface answers `403` to a tenant.
+- Isolation is the key, not a convention: a tenant's sessions live under
+  `<tenant>:<session-id>`, its commands carry `meta.tenant` (memory scoping,
+  event tagging), and reading another tenant's session/task reads as `404`.
+
+`single_tenant` (the default) is exactly the classic behavior above — one
+operator credential, no principal, no stamping.
 
 ## The `/v1` contract is versioned by date
 
@@ -172,7 +182,10 @@ moderator off. See [`examples/guardrails/`](https://github.com/guizaols/insika/t
 - **Input** — deterministic detectors (prompt-injection, abuse) run *before* the
   model. A flagged input gets a **safe refusal without burning a model turn** — an
   injection or a flood never reaches the provider. An LLM moderator can be layered
-  on top.
+  on top. The moderator is **fail-open**: an error or an unparseable reply never
+  blocks a legitimate customer — but silence is not a negative. That third state
+  surfaces as a `:guardrail_flagged` event with category `moderator_unavailable`,
+  so a degraded tier is distinguishable from a healthy one in the audit stream.
 - **Output** — moderation plus PII/secret redaction on the streamed response, and
   a post-turn validator.
 
@@ -354,6 +367,67 @@ 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, RFC-0031)
+
+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 (RFC-0034)
+
+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 RFC-0031 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 (RFC-0035)
+
+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.
+
 ## See also
 
 - [Agents](AGENTS.md) — the five access layers per agent.

data/docs/SKILLS.md

@@ -22,6 +22,8 @@ See [`examples/skills/`](https://github.com/guizaols/insika/tree/main/examples/s
 ---
 name: refunds                       # must equal the directory name
 description: When and how to process a refund   # the Level-1 trigger text
+triggers: [refund, money back]      # optional: deterministic activation (below)
+companions: [refund-policy]         # optional: skills this one cannot work without
 ---
 
 <the full playbook body — loaded only on demand>
@@ -33,17 +35,121 @@ which the `name:` field must match.
 ## Progressive loading: two levels
 
 - **Level 1 — metadata only.** A context provider injects an `<available_skills>`
-  list (the name + one-line description of every allowed skill) into the system
-  prompt, telling the model to load a skill before acting on it. Cheap, and always
-  present for allowed skills.
+  list into the system prompt — the name, the one-line description and the
+  `triggers:` of every allowed skill — telling the model to load a skill before
+  acting on it. Cheap, and always present for allowed skills. **This is the routing
+  table, and it is generated:** it cannot disagree with the allowlist, so do not
+  hand-write one in a prompt file (see [Drift guards](#drift-guards)).
 - **Level 2 — the full body.** A built-in `load_skill` tool returns the skill body
   on demand. It enforces the agent's skill allowlist and is wired **automatically**
   whenever the agent has any allowed skills — you do not add it to `tools_allow`.
+- **Deterministic activation — `triggers:`.** When the user message contains one
+  of the skill's `triggers`, the body is injected for that turn — no model
+  decision, no `load_skill` call. Only matched skills, only that turn. Use it for
+  skills that MUST fire on known phrases; model loading stays as the fallback for
+  everything else. Matching is on **whole words**, case-insensitive and
+  accent-folded: `presente` fires on *um presente* and *presénte*, never inside
+  *apresente*.
 
 The Level-1 list is budgeted like any other context fragment
 (see [Context](CONTEXT.md)); the Level-2 body only costs tokens on the turns that
 open it.
 
+### Only trigger a skill that can finish the turn alone
+
+A `triggers:` match is not a hint — the body lands in the prompt with the
+authority of an instruction. So put triggers only on a skill that is
+**self-sufficient** for the turn it fires on.
+
+The failure mode is counter-intuitive: injecting a skill that is only *part* of
+the answer is **worse than injecting nothing**. Give the model a reference table
+whose procedure lives in a companion skill, and it now holds a plausible
+half-recipe — so it never calls `load_skill` for the other half, and improvises
+the missing part. A precise trigger on the wrong kind of skill still breaks the
+turn.
+
+Reference tables, vocabularies and lookup maps are the skills to leave on
+level 1. Whole procedures ("run this journey", "recover from this error") are the
+ones worth triggering.
+
+## Always-on skills: `skills_eager`
+
+A skill that every turn needs — output format, the marker vocabulary, how to
+recover from a failed tool — should not depend on the model choosing to load it.
+Name it on the **agent** and its body is in the prompt on every turn:
+
+```ruby
+Insika.agent("consultant") do
+  skills_eager "recommendation-formatting", "tool-error-recovery"
+  # skills_eager        # or: every allowed skill (a corpus that fits the budget)
+  # skills_eager false  # or: none — the default
+end
+```
+
+An eager skill also **leaves level 1**: it is absent from `<available_skills>` and
+`load_skill` refuses to serve it. There is no level 2 left to fetch, and a catalog
+pointing at a body already in the prompt only invites a call that pays for a
+duplicate.
+
+### Why the agent decides, and not the skill
+
+Eagerness used to be an `eager: true` key in the `SKILL.md` frontmatter. That put
+the decision on the wrong object: **skills are shared.** `escalation-to-human`,
+`recommendation-formatting` and `tool-error-recovery` each sit in several agents'
+allowlists, and one flag on the skill forced one decision onto every agent holding
+it — with no way to be always-on for the agent that needs it and discretionary for
+the one that does not.
+
+`skills_eager` is a per-agent list, so the same shared skill can be both. The
+frontmatter key is **ignored** — `insika doctor` flags any skill still carrying it,
+and names the agent setting that replaced it.
+
+A name that is not in the agent's `skills` allowlist is a no-op (eagerness is
+intersected with what the agent is allowed to see); `doctor` flags that too.
+
+### Keep the discretionary skills on the load path
+
+Making everything eager is a trap, and the reason is not the tokens: **it costs you
+the signal**. When every body is present on every turn, "which skills were active"
+is always "all of them", and you can no longer tell which one the model reached for.
+The `load_skill` call is the only record of that choice — it is a persisted tool
+message, so it shows up in the transcript on its own.
+
+So the split is: **eager for what the turn always needs, `load_skill` for what the
+turn might need.** The second group is where you want the model's choice on the
+record, because that is the group where a wrong choice is worth seeing.
+
+The token trade is real but smaller than it looks: eager bodies sit at a fixed
+position ahead of the history, so they belong to the **cacheable prefix**, and they
+are still evictable under budget pressure, unlike the pinned identity. Conditional
+injection is what breaks that prefix, on exactly the turns it fires.
+
+## Seeing which skills were active, and why
+
+The load path is legible for free: `load_skill` is a tool, so the call is a
+persisted message and shows up in the transcript on its own. The deterministic paths
+are not a call, so the engine reports them itself — **with a reason per skill**:
+
+| reason | what it means |
+|---|---|
+| `eager` | the agent's `skills_eager` names it, so every turn gets it |
+| `trigger:<phrase>` | this message matched that `triggers:` entry — the phrase as **authored**, so you can find the line to edit |
+| `pack` | a plugin's own context provider supplied the body |
+
+Where it shows up, per turn, in the Studio session screen:
+
+- an **activation card in the transcript thread**, placed at the top of its turn and
+  in the same visual language as a tool result, so a context-injected skill and a
+  model-loaded one read the same way;
+- the **Context card**, next to that category's token count, for the after-the-fact
+  audit;
+- the `skill_activated` **event** (`skills: [{name, reason}]`, `source: "context"`),
+  with full task/session correlation.
+
+All three are computed from what actually reached the prompt **after the budget
+cut**: a body the budget evicted is reported as an eviction, never as an activation.
+A turn that mixes both paths is labelled `mixed`, and each line keeps its own reason.
+
 ## Where skills live: the store, over a disk seed
 
 - Skills live as **rows in SQLite** — one row per skill, holding the entire
@@ -58,6 +164,68 @@ open it.
 > runtime operation (Studio / API / DSL), not a commit. See
 > [Context](CONTEXT.md#the-volume).
 
+## Pairs that must not break: `companions:`
+
+Injecting *part* of an answer is worse than injecting nothing. Give the model a line
+map whose query-construction rules live in another skill and it holds a plausible
+half-recipe — so it never calls `load_skill` for the other half, and improvises the
+missing part. Measured on a real pack: the map arrived by trigger, the rules did not,
+and the searches came out malformed. Twice.
+
+Declare the dependency and it travels with whatever brought it — a trigger match, the
+agent's eager set, or a `load_skill` call (which returns both bodies in the one call):
+
+```yaml
+companions: [query-construction]
+```
+
+Two deliberate limits:
+
+- **One level, no transitive walk.** A cycle would be a hang and a chain a budget
+  blowout, and "cannot work without" is a direct relationship.
+- **Never widens an allowlist.** A companion the agent is not allowed to load is
+  simply absent; `insika doctor` flags the declaration instead.
+
+## Specializing a shared skill for one agent
+
+Skills are shared on purpose: `escalation-to-human` belongs in several agents'
+allowlists. But sometimes one agent needs a different version of the same skill —
+its own return policy, its own store name — and forking it under a second name
+throws the sharing away and leaves two things to keep in step.
+
+So the store has a second scope, and resolution is a **precedence chain** with one
+more dimension:
+
+```
+for agent A, skill <name>:   (A, <name>) in the agent scope,
+                             then <name> in the shared scope
+```
+
+Three cases fall out of that one rule:
+
+| case | what exists in the store |
+|---|---|
+| **shared** | only the shared record — every agent gets the same body |
+| **override** | both — the agent's wins, for that agent only |
+| **agent-private** | only the agent record — invisible elsewhere, and the name may collide freely |
+
+The **name never changes.** An override keeps saying `name: escalation-to-human`
+inside, because it *is* that skill, specialized; the allowlist, the `<available_skills>`
+list, `load_skill` and the activation card all keep showing the bare name. What
+decides which record you get is its **position in the store**, never the frontmatter —
+otherwise an override would clobber the shared skill for everybody.
+
+Write one with `agent:`, and remove it the same way (which un-specializes, leaving
+the shared skill in place):
+
+```ruby
+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
+the shared body.
+
 ## Making a new skill "show up"
 
 For an agent to actually use a skill, **both** conditions must hold:
@@ -89,6 +257,24 @@ Two ways to satisfy both:
   `load_skill` errors → the store row is missing or misnamed (condition 1); the
   `name:` frontmatter must equal the directory name.
 
+## Drift guards
+
+A skill catalog drifts against the prose that routes to it, and every way it happened
+on the pilot was silent — found by reading a customer conversation days later. So the
+routing table is **generated** (above), and `insika doctor` reports the residue the
+generator cannot remove. Every check takes mechanical inputs only — names, allowlists,
+agent identities — because one false positive is enough for an operator to stop
+reading the doctor:
+
+| finding | what it means |
+|---|---|
+| a prompt file names a skill outside that agent's allowlist | leftover hand-written routing: the model is told to use something it cannot load |
+| a shared skill's body names one of its own holders | specialized text in shared clothing — the other holders are served that store's policy as their own. Specialize it instead |
+| a body references another catalog skill without declaring it a companion | the pair can still arrive apart |
+| a declared companion is outside an agent's allowlist | the pair cannot travel for that agent, and the engine will not widen the allowlist |
+| a skill still declares `eager:` in its frontmatter | the key is ignored; the decision moved to the agent |
+| an agent marks a skill eager that it does not allow | the name is a no-op |
+
 ## See also
 
 - [Context](CONTEXT.md) — how the skills list is budgeted into a turn.

data/docs/SOAK.md

@@ -0,0 +1,127 @@
+---
+title: Soak
+parent: Operate & prove it
+nav_order: 4
+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.

data/docs/TOOLS.md

@@ -91,8 +91,10 @@ retries against. Structure is strict; a scalar may arrive in its lossless string
 
 - `{{param}}` — a declared top-level parameter, filled from the model's call.
 - `{{ctx.*}}` — turn context set **server-side, never by the model**: a closed set
-  of `chat_id`, `store_id`, `agent_id`, `tenant`. This is how a tool knows *which*
-  session/agent it is acting for without trusting the model.
+  of `chat_id`, `store_id`, `agent_id`, `tenant`, `image_url`. This is how a tool knows *which*
+  session/agent it is acting for without trusting the model. `image_url` is the
+  first image part on the message (a photo for analysis outside the prompt);
+  absent when the turn carried none.
 - `{{secret.*}}` — allowed **only** inside a header named in `secret_headers`.
   A secret placeholder anywhere else is rejected (it would leak unmasked). The
   real secret value is injected at provision time and never lives on disk.
@@ -181,6 +183,72 @@ backend, not of whoever calls it. Every agent sharing the tool gets the same val
 > there **preserves** it — the form carries the stored values through instead of
 > replacing the record with only what it shows.
 
+## Evidence: the lean envelope and grounding (RFC-0029)
+
+A catalog tool returns products; the model should only ever quote the ones the tool
+actually returned — the store dies of a SKU the model invented. `evidence` is the
+declaration that makes "no claim without a tool ID" an engine rule instead of a
+prompt convention. One declaration does **both** jobs: the engine strips the result
+down to what the model sees (the lean envelope) **and** records every returned id on
+the session's evidence ledger. There is no "lean but not evidence" mode.
+
+```jsonc
+{ "name": "search_products",
+  "response": { "extract": "evidence_envelope" },
+  "evidence": "products" }                        // bare kind
+
+{ "evidence": { "kind": "products",               // full form
+                "items": "results",               // non-default paths
+                "attachments": "cards" } }
+```
+
+- `evidence_envelope` is the canonical extract: the raw response body arrives under
+  an engine-only key, the envelope parses `items`/`attachments` out of it, and
+  **nothing re-fattens** — the transcript and the tool trace record only the lean
+  result. It **requires** the `evidence` declaration (refused at load otherwise).
+- **Wire contract** — the lean result the model sees is always
+  `{ "items": [ { "id": "…", "line": "…" } ] }` (≤ 16 items; `line` truncated to
+  200 chars). A tool whose result has no valid items yields `{ "items": [] }`,
+  never a null. A malformed evidence result becomes `{ "error": … }` back to the
+  model — a correctable tool answer, exactly like a malformed call.
+- **Attachments** are the optional second half: `[{ "type": "card"|"image",
+  "url": "…", "caption": "…" }]` (≤ 16, url ≤ 500 chars, malformed dropped). They
+  **never** reach the model context or the transcript — they ride the channel
+  delivery as an additive `attachments` key on the outbox payload, and the channel
+  (or its consumer) decides what a card looks like.
+- A **code tool** opts in the same way: it either returns `{ items, attachments }`
+  directly and declares `evidence` in its registry metadata, or exposes an
+  `evidence` reader. No declaration = today's tool behavior, byte for byte.
+
+### Grounding: policing claims against the ledger
+
+With the ledger fed, the pack declares how claims are policed — data on the agent,
+not a separate code path (see [Agents](AGENTS.md)):
+
+```ruby
+grounding mode: :flag, matcher: { sku: '\b[A-Z]{2,4}\d{4,8}\b' }
+```
+
+- `mode` is `flag` (the default — audit), `enforce` (cut), or `off`. Absent = off.
+- `matcher.sku` is a regex for the store's SKU shape, applied to the final answer;
+  every match that is **not** in the evidence ledger is an ungrounded claim.
+  Grounding is **SKU-only** by design: a name-based half cannot flag anything
+  without a "this is a product name" signal, so the ledger grounds ids, and the
+  model quoting a returned product by its *name* is simply outside the check
+  (the SKU path is the claim detector). A `sku` that does not compile is refused
+  at build; a matcher with no `sku` builds but matches nothing — `insika doctor`
+  warns about it.
+- **`flag`** appends an `:ungrounded` flag (category `ungrounded`, source
+  `evidence`) to the existing `:guardrail_flagged` event — audit after the fact,
+  like every other output flag.
+- **`enforce`** *cuts the sentence* containing an ungrounded claim from the content
+  the turn persists and delivers, and the flag carries `action: "cut"` so the audit
+  can tell a cut from a flag. It is honest about streaming: on a streaming surface
+  the already-streamed bytes are the channel's reality, which is exactly why the
+  default is `flag` — ship `enforce` only after a matcher audit proves precision.
+- Grounding is **independent of the guardrails opt-in**: an agent with guardrails
+  off and `grounding.mode: :flag` still gets the check.
+
 ## Registering a tool
 
 A tool appears in the Studio panel and enters an agent's tool-loop when it is

data/docs/WHY.md

@@ -32,7 +32,7 @@ the same speed-to-first-agent story Python teams tell, without leaving Ruby:
 require "insika"
 
 agent = Insika.agent("assistant") do
-  model "deepseek-chat"
+  model "deepseek-v4-flash"
   provider :deepseek
   instructions "You are a concise, friendly assistant."
 end

data/docs/WORKFLOWS.md

@@ -40,8 +40,8 @@ agents by id and those agents must resolve in the same runtime:
 newsroom = Insika.system do
   provider :deepseek
 
-  agent("writer") { model "deepseek-chat"; instructions "Write ONE paragraph." }
-  agent("editor") { model "deepseek-chat"; instructions "Rewrite as ONE sentence." }
+  agent("writer") { model "deepseek-v4-flash"; instructions "Write ONE paragraph." }
+  agent("editor") { model "deepseek-v4-flash"; instructions "Rewrite as ONE sentence." }
 
   workflow "publish",
            description: "Draft a paragraph, then tighten it.",