insika 0.2.0 → 0.7.0

data/docs/_sass/custom/custom.scss

@@ -0,0 +1,199 @@
+// Insika's own styling on top of Just the Docs.
+//
+// Everything that is NOT one of the theme's `!default` variables lives here;
+// the palette itself is in _sass/color_schemes/insika.scss. Kept deliberately
+// small: the theme already handles layout, search and responsiveness, and every
+// rule below exists because a specific page needed it.
+//
+// IMPORTANT: these pages are read in three places — this site, GitHub, and the
+// raw-markdown API (`GET /docs/<name>.md`). Styling is therefore driven by
+// kramdown attribute lists (`{: .card-grid }`) on ORDINARY markdown, never by
+// raw HTML blocks: a list still reads as a list everywhere else.
+
+// ---------------------------------------------------------------------------
+// Typography
+// ---------------------------------------------------------------------------
+
+// The theme's 1.6 content line-height is tight for pages this long.
+.main-content {
+  line-height: 1.65;
+
+  h1,
+  h2,
+  h3 {
+    letter-spacing: -0.01em;
+  }
+
+  // A rule above every h2 turns a long page into visible sections. h2 is the
+  // level the search index already uses as a landmark, so it is the honest one
+  // to draw.
+  h2 {
+    padding-top: $sp-5;
+    margin-top: $sp-7;
+    border-top: $border $border-color;
+  }
+
+  h2:first-of-type {
+    margin-top: $sp-4;
+    padding-top: 0;
+    border-top: 0;
+  }
+
+  // Inline code appears in nearly every sentence here (env vars, method names).
+  // A tinted chip separates it from prose without shouting.
+  p > code,
+  li > code,
+  td > code,
+  h2 > code,
+  h3 > code,
+  h4 > code {
+    padding: 0.12em 0.32em;
+    background-color: $stone-100;
+    border: $border $stone-200;
+    border-radius: 3px;
+    font-size: 0.85em;
+  }
+
+  blockquote {
+    margin-left: 0;
+    padding: $sp-2 $sp-4;
+    border-left: 3px solid $terracotta-000;
+    background-color: $stone-050;
+    color: $ink-700;
+
+    > :first-child { margin-top: 0; }
+    > :last-child { margin-bottom: 0; }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Home hero
+// ---------------------------------------------------------------------------
+
+// `{: .hero-tagline }` on the one line under the h1.
+.hero-tagline {
+  max-width: 34rem;
+  margin-bottom: $sp-6;
+  color: $ink-700;
+  font-size: $font-size-6;
+  font-weight: 300;
+  line-height: 1.45;
+}
+
+// ---------------------------------------------------------------------------
+// Card grid
+// ---------------------------------------------------------------------------
+
+// `{: .card-grid }` on a markdown list whose items read
+// `**[Title](page.md)** — what the page answers.`
+//
+// The em dash is the split point: the bold link becomes the card title and the
+// remainder becomes the card's body. No HTML in the markdown, so GitHub and the
+// raw-markdown API still see a plain, readable list.
+.main-content ul.card-grid {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(15rem, 1fr));
+  gap: $sp-3;
+  margin: $sp-5 0;
+  padding: 0;
+  list-style: none;
+
+  > li {
+    margin: 0;
+    padding: $sp-4;
+    border: $border $border-color;
+    border-radius: 6px;
+    background-color: $body-background-color;
+    line-height: 1.5;
+    transition: border-color 150ms ease, background-color 150ms ease;
+
+    &::before { content: none; }
+
+    &:hover {
+      border-color: $terracotta-000;
+      background-color: $stone-050;
+    }
+
+    // The bold-wrapped link is the card's title.
+    > strong {
+      display: block;
+      margin-bottom: $sp-1;
+      font-size: $font-size-5;
+      font-weight: 600;
+
+      > a {
+        color: $body-heading-color;
+        text-decoration: none;
+        background-image: none;
+
+        &:hover { color: $terracotta-100; }
+      }
+    }
+
+    color: $ink-500;
+    font-size: $font-size-4;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Navigation
+// ---------------------------------------------------------------------------
+
+.site-title {
+  font-weight: 600;
+  letter-spacing: -0.02em;
+}
+
+// The sidebar is six sections deep; a hairline between top-level entries makes
+// the grouping legible at a glance instead of one 40-item column.
+.site-nav > .nav-list > .nav-list-item + .nav-list-item {
+  border-top: $border $border-color;
+}
+
+.nav-list .nav-list-item .nav-list-link.active {
+  font-weight: 600;
+  box-shadow: inset 2px 0 0 $terracotta-100;
+}
+
+// ---------------------------------------------------------------------------
+// Tables
+// ---------------------------------------------------------------------------
+
+// Reference tables here are wide (env var, default, meaning). Zebra striping
+// and a tinted header make a 20-row table scannable.
+.main-content table {
+  th {
+    background-color: $stone-100;
+    font-size: $font-size-3;
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+  }
+
+  tbody tr:nth-child(even) {
+    background-color: $stone-050;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Site title
+// ---------------------------------------------------------------------------
+
+// _includes/title.html puts the pillar mark inline before the wordmark.
+.site-title {
+  display: inline-flex;
+  align-items: center;
+  gap: $sp-2;
+}
+
+.site-title-mark {
+  display: inline-flex;
+  flex: 0 0 auto;
+
+  svg {
+    width: 1.05em;
+    height: 1.05em;
+    fill: $terracotta-100;
+
+    .shaft { fill: $terracotta-000; }
+  }
+}

data/docs/_sass/custom/setup.scss

@@ -0,0 +1,26 @@
+// Insika's palette tokens.
+//
+// This file is the ONE place the raw colours are written. It lives in
+// custom/setup rather than in the colour scheme because Just the Docs imports
+// it before every scheme it compiles — including its own stock light and dark
+// stylesheets, which also pull in _sass/custom/custom.scss and would otherwise
+// fail on an undefined variable.
+//
+// _sass/color_schemes/insika.scss maps these onto the theme's own variables.
+
+// Warm neutrals. The greys carry a little red so that text on the off-white
+// sidebar does not read as blue-grey next to the terracotta accent.
+$ink-900: #16191d !default; // headings
+$ink-700: #3d4148 !default; // body copy
+$ink-500: #6b6a68 !default; // muted
+$stone-050: #faf8f5 !default; // sidebar
+$stone-100: #f6f3ef !default; // code blocks, table stripes
+$stone-200: #e8e2d9 !default; // borders
+
+// The single accent. #a8431e clears 4.5:1 on both #fff and the sidebar, which
+// the lighter, prettier terracottas do not — links are the one thing here that
+// cannot trade contrast for warmth.
+$terracotta-000: #c2542a !default;
+$terracotta-100: #a8431e !default;
+$terracotta-200: #8a3617 !default;
+$terracotta-300: #6b2911 !default;

data/docs/assets/img/favicon.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" role="img" aria-label="Insika">
+  <!-- A pillar seen head-on: capital, shaft, base. It doubles as the "I" of
+       Insika, which is why the shaft is centred and the slabs overhang. -->
+  <rect x="3" y="3" width="18" height="3.6" rx="1" fill="#a8431e"/>
+  <rect x="8.7" y="7.6" width="6.6" height="8.8" fill="#c2542a"/>
+  <rect x="3" y="17.4" width="18" height="3.6" rx="1" fill="#a8431e"/>
+</svg>

data/docs/assets/img/insika-mark.svg

@@ -0,0 +1,7 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" role="img" aria-label="Insika">
+  <!-- A pillar seen head-on: capital, shaft, base. It doubles as the "I" of
+       Insika, which is why the shaft is centred and the slabs overhang. -->
+  <rect x="3" y="3" width="18" height="3.6" rx="1" fill="#a8431e"/>
+  <rect x="8.7" y="7.6" width="6.6" height="8.8" fill="#c2542a"/>
+  <rect x="3" y="17.4" width="18" height="3.6" rx="1" fill="#a8431e"/>
+</svg>

data/docs/core-concepts.md

@@ -0,0 +1,21 @@
+---
+title: Core concepts
+nav_order: 3
+has_children: true
+permalink: /core-concepts/
+---
+
+# Core concepts
+
+An agent is data: a profile, what it is allowed to do, its tools, its skills, and
+what fills its prompt. These six pages are the vocabulary everything else on this
+site assumes. Each one has a runnable counterpart under
+[`examples/`](https://github.com/guizaols/insika/tree/main/examples/).
+
+- **[Agents](AGENTS.md)** — the profile, the three ways to create one, and every key on it.
+- **[Limits and policy](POLICY.md)** — the five layers that decide what an agent may do and what stops it.
+- **[Tools](TOOLS.md)** — code tools, data-defined tools, MCP servers, and why a tool call goes missing.
+- **[Skills](SKILLS.md)** — playbooks the agent loads only when the conversation calls for them.
+- **[Context](CONTEXT.md)** — what fills a turn's prompt, the token budget, and cross-session memory.
+- **[Workflows](WORKFLOWS.md)** — when the order of work belongs in Ruby instead of a prompt.
+{: .card-grid }

data/docs/domain.md

@@ -0,0 +1,115 @@
+---
+title: The domain-free core
+parent: Reference
+nav_order: 1
+permalink: /domain/
+---
+
+# The domain-free core — what ships, what a deployment declares, and how to clear it
+
+The engine is domain-free by construction: the gem carries no store
+vocabulary, no persona, and no fixed conversation language. This page is the
+removability map — for every artifact that could make a deployment look like
+"the Brazilian store harness", here is what ships, what the doctor reports, and
+how to clear it.
+
+## What ships and what does not
+
+One selection function owns the gem payload: `Insika::Packaging.payload_files`
+— the gemspec and the audit spec (`spec/insika/domain_boundary_spec.rb`) call
+the same function, so the boundary is a fact the suite asserts on, never a
+prose promise. It ships:
+
+- `lib/` — the engine, the server, the Studio (the compiled JS only);
+- `docs/` — the public documentation;
+- `README.md`, `LICENSE`, `CHANGELOG.md`, `bin/insika`.
+
+It never ships: `deploy/`, `packs/`, `examples/`, `plugins/`, `evals/`,
+`scripts/`, `spec/` — even a tracked pack cannot ship. Packs, personas and
+deployment wiring are checkout material, and that is the point: the reference
+deployment is not the gem.
+
+The proof command is `insika doctor --domain`: a read-only inventory of what a
+deployment declares, plus the built-in corpora still in effect. A bare install
+with no agents names nothing; an install that boots an agent reports the
+built-in pt-BR guardrail corpus as `source: gem-default` — the removability
+surface, not a store. The section never fails the doctor's exit code: it is
+informational, the RFC's proof surface.
+
+## The guardrail corpus — clear the shipped pt-BR content
+
+The deterministic guardrail patterns ship as language-tagged data
+(`Safety::Corpus`). A deployment clears a language by config, per agent:
+
+```jsonc
+// pack: agent.config.json
+{ "guardrails": { "corpora": { "languages": ["en"] } } }
+```
+
+```ruby
+# DSL
+agent = Insika.agent("store-support") do
+  instructions "…"
+  guardrails corpora: { languages: ["en"] }
+end
+```
+
+- `languages` filters the shipped families: `nil` = all (the default),
+  `[]` = none, `["en"]` = the EN-only corpus. An EN-only deployment drops the
+  pt-BR input heuristics **and** the CPF/CNPJ output redaction — a documented
+  consequence: the tax-id formats are pt-BR data, and the universal "secret"
+  redaction is never cleared.
+- `extra` adds source-string patterns per family:
+
+```jsonc
+{ "guardrails": { "corpora": { "extra": { "abuse": ["/\\bdupa\\b/i"] } } } }
+```
+
+- `guardrails.responses` replaces the built-in pt-BR fallback replies (the
+  safe refusals). Set a `default` to clear every category at once.
+
+See [Security](SECURITY.md) for the guardrail layers; the doctor's domain
+section enumerates any agent still running the built-in pt-BR corpus or the
+built-in replies, with the clear path in each entry. An unknown language or
+family, or a malformed pattern, is refused at boot — `insika doctor` reports it
+as an error and the agent never turns with a broken corpus.
+
+## Marking a deployment — declare, never infer
+
+The engine never guesses a store. Domain markers are data a deployment
+declares, and the doctor reads only those declarations:
+
+- **Personas/packs** — `metadata.domain` on the agent profile:
+
+```jsonc
+{ "metadata": { "domain": "e-commerce-pt-BR" } }
+```
+
+```ruby
+metadata domain: "e-commerce-pt-BR"
+```
+
+- **Outcome funnel** — `funnel:` on the profile (see
+  [Outcomes](OUTCOMES.md#outcomes--business-results-over-real-traffic)).
+  Vocabulary note: in the gem and the doctor output it is an **outcome
+  funnel**, never "conversion" — the stage names are the deployment's, and a
+  bare install shows no funnel and no stage names at all.
+- **Evidence** — the `evidence:` declaration on a tool manifest (see
+  [Tools](TOOLS.md)); the kinds are the deployment's vocabulary, never gem
+  constants.
+
+`insika doctor --domain` enumerates all four with their source —
+`deployment` for declared data, `gem-default` for the built-in corpus still in
+effect — and a bare boot names none.
+
+## The conformance claim — model-visible means logged
+
+"Every byte that reaches the provider is reconstructable from checkpoints +
+traces" is a spec, not a promise. For each (task, turn) the engine records the
+model-visible payload at the provider boundary — the system text, the tool
+schemas, and the full message stream (`ModelVisibleTraceStore`) — next to the
+durable transcript (the checkpoint). The conformance suite
+(`spec/insika/conformance/model_visible_spec.rb`) drives real turns on a
+capturing chat and asserts a three-way byte identity: what the chat held ==
+the checkpoint transcript == the model trace. A path whose bytes are not
+logged is a fix in the engine, never a waiver in the suite.

data/docs/improve.md

@@ -0,0 +1,20 @@
+---
+title: Improve
+nav_order: 7
+has_children: true
+permalink: /improve/
+---
+
+# Improve
+
+The loops that make an agent better than it was last month — measure it, read
+its own traffic back, and turn finished conversations into something the next
+conversation can use. Every one of them ends at a human approval.
+
+- **[Evals](EVALS.md)** — the cases that grade an agent, and the gate that stops a regression.
+- **[Refinement](REFINEMENT.md)** — production traffic read back as a ranked report of what broke.
+- **[Outcomes and follow-ups](OUTCOMES.md)** — what the traffic was worth, and coming back on a promise.
+- **[Knowledge](KNOWLEDGE.md)** — durable concepts extracted from finished conversations.
+- **[Facts](FACTS.md)** — distilled customer memory, approved one fact at a time.
+- **[Harvest](HARVEST.md)** — skills mined from real traffic, promoted only if two gates hold.
+{: .card-grid }

data/docs/index.md

@@ -8,7 +8,7 @@ permalink: /
 {: .fs-9 }
 
 Your agent is the idea. Insika is what holds it up in production.
-{: .fs-6 .fw-300 }
+{: .hero-tagline }
 
 [Build your first agent](RUNNING-LOCAL.md){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
 [View on GitHub](https://github.com/guizaols/insika){: .btn .fs-5 .mb-4 .mb-md-0 }
@@ -36,7 +36,7 @@ require "insika"
 assistant = Insika.agent("assistant") do
   model "deepseek-v4-flash"
   provider :deepseek
-  instructions "You are Bia, a concise and friendly assistant. Answer briefly."
+  instructions "You are a concise and friendly assistant. Answer briefly."
 end
 
 puts assistant.reply("hi, what can you do?")   # one turn, in-process
@@ -60,9 +60,12 @@ secrets), `GET /docs` and `GET /docs/<name>.md`. Public and on by default when y
 
 ## Where to go next
 
-- **[Understand the idea](understand.md)** — why a runtime rather than a DIY loop, and how a turn actually runs.
-- **[Build an agent](build.md)** — agents, tools, skills, context, and the local loop.
-- **[Ship it](ship.md)** — security, confined execution, deployment.
-- **[Operate & prove it](operate.md)** — observability, the benchmark, load testing, evals, refinement.
+- **[Start here](start-here.md)** — why a runtime, getting one running, and what a turn actually does.
+- **[Core concepts](core-concepts.md)** — agents, limits, tools, skills, context, workflows.
+- **[Integrate](integrate.md)** — the API, channels, media, embedding, plugins, templates.
+- **[Ship it](ship.md)** — security, confined execution, deployment, scaling past one worker.
+- **[Operate](operate.md)** — observability, schedules, artifacts, load and soak testing.
+- **[Improve](improve.md)** — evals, refinement, outcomes, and the three learning loops.
+{: .card-grid }
 
 Pre-release: APIs may still change and nothing is tagged yet. Licensed MIT.

data/docs/integrate.md

@@ -0,0 +1,20 @@
+---
+title: Integrate
+nav_order: 4
+has_children: true
+permalink: /integrate/
+---
+
+# Integrate
+
+How the agent connects to everything that is not the engine: the clients that
+call it, the places people talk to it from, the app it may live inside, and the
+code you write to extend it.
+
+- **[The /v1 API](API.md)** — the frozen, OpenAI-Responses-compatible contract.
+- **[Channels](CHANNELS.md)** — the web widget and the relay: how people actually reach the agent.
+- **[Media](MEDIA.md)** — photos, voice notes and documents in; generated images out.
+- **[Embedding](EMBEDDING.md)** — mounting the engine inside a Ruby app you already have.
+- **[Plugins](PLUGINS.md)** — the two extension tiers, and how to pick between them.
+- **[Templates](TEMPLATES.md)** — the example agents that ship in the gem, and the gallery that installs them.
+{: .card-grid }

data/docs/operate.md

@@ -1,12 +1,19 @@
 ---
-title: Operate & prove it
-nav_order: 5
+title: Operate
+nav_order: 6
 has_children: true
 permalink: /operate/
 ---
 
-# Operate & prove it
+# Operate
 
-Turns as traces and metrics, the engine's measured overhead, how to load-test it
-yourself, the cases that grade an agent, and reading a live agent's own traffic back as
-a report of what broke.
+Running it once it is live: seeing what happened, firing turns nobody sent,
+handing back a report, and knowing what the box will take before it takes it.
+
+- **[Observability](OBSERVABILITY.md)** — the event stream, and turns as OpenTelemetry traces and metrics.
+- **[Schedules](SCHEDULING.md)** — recurring turns the engine fires on its own tick.
+- **[Artifacts](ARTIFACTS.md)** — a report the agent can hand you a URL to.
+- **[Load test](LOADTEST.md)** — end-to-end load testing, and comparing topologies before you choose one.
+- **[Soak](SOAK.md)** — the long run that finds what a short one cannot.
+- **[Benchmark](BENCHMARK.md)** — the engine's measured overhead, reproducible without an API key.
+{: .card-grid }

data/docs/prompts/ADD-TOOL.md

@@ -0,0 +1,118 @@
+---
+title: Prompt — add a tool or skill
+parent: Reference
+nav_order: 3
+permalink: /add-tool/
+layout: default
+render_with_liquid: false
+---
+
+# Add a tool, MCP server, or skill to my agent
+
+> **You are a coding agent** (Claude Code, Codex, Cursor, …) reading this because a
+> developer pasted a prompt pointing here. Treat this file as a **skill**: follow the
+> steps in order and apply the RULES literally.
+
+Your job: extend **one existing agent** with **one new capability** and prove it works
+with one turn. Nothing more.
+
+## Step 0 — Gather context (silently)
+
+- **Which agent?** Find its `Insika.agent { … }` block (or its pack). If the developer
+  has no agent yet, stop and build the minimal first agent instead — this file assumes
+  one exists. Do not mix onboarding with capability.
+- **A provider key in the environment**; ask if none is set.
+- Read [`docs/TOOLS.md`](../TOOLS.md) (also served at `GET /docs/tools.md`) and, for
+  skills, [`docs/SKILLS.md`](../SKILLS.md) before writing anything.
+
+## Step 1 — Pick the kind (RULES, not taste)
+
+| The need | The kind | Where it lives |
+|---|---|---|
+| Call an external HTTP API | **data tool** (`data_tool` in the DSL block) | a row in SQLite, editable at runtime |
+| Logic must run in-process | **code tool** (a Ruby class `< RubyLLM::Tool`) | the deployment image |
+| Adopt a whole external MCP server | **`mcp` instance** | durable config; its tools appear tagged `mcp:<name>` |
+| Teach a procedure (no data fetching) | **skill** (`skill "name", description:, instructions:`) | loads on demand via `load_skill` |
+
+Exactly one kind. A skill is not a tool; an MCP server is not five data tools.
+
+## Step 2 — Build the smallest version
+
+Data tool, via DSL (shape from
+[`examples/data-tool/`](https://github.com/guizaols/insika/tree/main/examples/data-tool/)):
+
+```ruby
+data_tool(
+  "name"        => "convert_currency",
+  "description" => "Latest reference exchange rate between two currencies.",
+  "parameters"  => {
+    "type" => "object",
+    "properties" => {
+      "from" => { "type" => "string", "description" => "source currency code" },
+      "to"   => { "type" => "string", "description" => "target currency code" }
+    },
+    "required" => %w[from to]
+  },
+  "request"  => { "method" => "GET",
+                  "url"    => "https://api.example.com/latest?from={{from}}&to={{to}}" },
+  "response" => { "extract" => "body_raw" }
+)
+```
+
+Skill, via DSL (from
+[`examples/skills/`](https://github.com/guizaols/insika/tree/main/examples/skills/)):
+
+```ruby
+skill "refunds",
+      description: "How to handle a refund request",
+      instructions: <<~MD
+        When a customer asks for a refund:
+        1. If you don't have the order number, ask for it first.
+        …
+      MD
+```
+
+RULES:
+
+- `parameters` is JSON Schema (safe subset — no `oneOf`/`$ref`); it reaches the model
+  verbatim and arguments are checked against it at call time.
+- Author the FINAL url: the HTTP client does not follow redirects, and the egress guard
+  cleared that host only.
+- Do not add a second capability "while we're here".
+
+## Step 3 — Make sure it enters the tool-loop
+
+Registered is not enough — the agent's policy allowlist decides. The DSL auto-enables
+the allowlist policy, and the three-state rule applies (`nil` = all, `[]` = none,
+`[names]` = exactly those; deny wins):
+
+```ruby
+tools %w[convert_currency]   # or tools_allow: [...] on the pack
+```
+
+A code tool can never be shadowed by a data tool of the same name — pick another name
+instead of fighting it.
+
+## Step 4 — Prove it with ONE turn
+
+Run one `reply()` whose message forces the call ("how many BRL is 1 USD right now?").
+The reply must use what the tool returned — if the model answers from imagination, the
+tool did not run: re-check Step 3 before touching the prompt.
+
+## Step 5 — Self-check
+
+- [ ] One agent, one new capability, one proving turn with real output.
+- [ ] The tool/skill is named in the allowlist (or absence was a deliberate "all").
+- [ ] No secret in any file — keys live in the environment.
+- [ ] No new gem dependency was added without asking.
+
+## Hard constraints
+
+- **Secrets stay in the environment.** `{{secret.*}}` resolves ONLY on the manifest
+  write path (`POST /v1/tools/manifest`); written via DSL or Studio it fails
+  registration. Tools authored outside a manifest ship literal values (masked on read).
+- **The egress guard refusing a URL is a feature**, not a bug to disable globally.
+  Report it; open an allowlist exception deliberately.
+- **Config over code**: everything above is data the DSL generates (`to_pack`). If it
+  seems to require reaching past the DSL, the answer is a DSL method you have not used
+  yet — re-read the docs first.

data/docs/prompts/DIAGNOSE-TURN.md

@@ -0,0 +1,65 @@
+---
+title: Prompt — diagnose a failed turn
+parent: Reference
+nav_order: 4
+permalink: /diagnose-turn/
+layout: default
+render_with_liquid: false
+---
+
+# Diagnose a turn that failed or misbehaved
+
+> **You are a coding agent** (Claude Code, Codex, Cursor, …) reading this because a
+> developer pasted a prompt pointing here — something like *"the agent didn't answer /
+> answered wrong / errored"*. Treat this file as a **skill**: investigate BEFORE
+> proposing fixes, and report findings in plain language with evidence.
+
+The engine already recorded what happened: every turn emits structured events stamped
+with `task_id`/`session_id`. Your job is to read the record, not to guess.
+
+## Step 0 — Pin down the facts
+
+Ask for (or find) the minimum: **agent id**, **session id** (or the customer's message
+text), roughly **when**, and expected vs. actual. Reproduce once locally if cheap
+(`reply()` or one `curl` against a dev instance) — never hammer production.
+
+## Step 1 — Read the record, in this order
+
+1. **`GET /v1/tasks/:id`** (or the Studio) — the terminal state:
+   `completed` / `failed` / `cancelled`, outcome, usage, timing. No task id? Find it
+   via **`GET /v1/events?session_id=…`**.
+2. **That task's events**: `task_started` → `tool_call`/`tool_result`/`data_tool_call`
+   … → the terminal event. A failure's reason lives there.
+3. **`GET /v1/sessions/:id`** — the transcript: what the model actually saw and said.
+4. **`bin/insika doctor`** — configuration sanity; relay its findings verbatim.
+
+## Step 2 — Map symptom to mechanism
+
+| On the record | Usual suspect | Details |
+|---|---|---|
+| provider auth/model error | missing key or wrong model id | fails at the provider, not the engine |
+| `provider_failure` then `provider_fallback` | reliability chain rotated mid-turn | [Agents](../AGENTS.md) § reliability |
+| `breaker_open` + fail-fast turns | circuit open until cooldown | same |
+| turn completed, customer got nothing | delivery is separate from the turn: check `channel_delivered` / `delivery_failed` | [Channels](../CHANNELS.md) |
+| freshly created agent returns empty turns | persona overflows the default `context_budget` (8000) | [Context](../CONTEXT.md) |
+| tool never called (or "missing") | not registered OR not allowed (`tools_allow`) | [Tools](../TOOLS.md) § troubleshooting |
+| identical `tool_call` repeated, then abort | the `max_tool_repeat` loop guard | [Agents](../AGENTS.md) § limits |
+| model gave up after one empty result | `tool_persistence` off (it is ON by default) | same |
+| `turn_stuck` event | the agent declared it cannot proceed — escalation signal, not a bug | [Agents](../AGENTS.md) § stuck |
+
+## Step 3 — Report, then fix ONE thing
+
+- Plain-language summary: **what happened → evidence (event names + ids) → root cause
+  → the fix you propose.**
+- Apply the fix; re-run the Step 0 reproduction; show the new terminal event as proof.
+- If the evidence does not fit any row above, say so and bring the raw events back —
+  do not force a diagnosis.
+
+## Hard constraints
+
+- **Never invent event data.** If you did not read it, you cannot claim it.
+- **Do not change config just to silence the symptom** without explaining the
+  mechanism (raising `context_budget` because the prompt is big is a fix; deleting the
+  guardrail that fired is not).
+- **Quote ids, counts and states first; message content only when needed** for the
+  developer to recognize the case.