insika 0.3.0 → 0.8.0

data/docs/TOOLS.md

@@ -1,7 +1,7 @@
 ---
 title: Tools
-parent: Build an agent
-nav_order: 2
+parent: Core concepts
+nav_order: 3
 permalink: /tools/
 ---
 
@@ -12,15 +12,16 @@ kinds, and the distinction that matters is **who can change one at runtime**:
 
 | | **Code tool** | **Data tool** | **MCP tool** |
 |---|---|---|---|
-| What | a Ruby class (`< RubyLLM::Tool`) | an HTTP call described by config, no Ruby | an MCP server's tool, ingested |
-| Lives | in the deployment image | as a row in SQLite | as data-tool rows in SQLite |
-| Editable at runtime | no (shipped in the image) | **yes** (DSL / API / manifest / Studio) | **yes** (re-ingest) |
-| Reach for it when | logic must run in-process (file edit, shell, subagent) | calling an external HTTP API | adopting a whole MCP toolset at once |
+| What | a Ruby class (`< RubyLLM::Tool`) | an HTTP call described by config, no Ruby | an MCP server's tool, called LIVE |
+| Lives | in the deployment image | as a row in SQLite | on the MCP server, behind a live client |
+| Editable at runtime | no (shipped in the image) | **yes** (DSL / API / manifest / Studio) | **yes** — enable/edit the *instance* (DSL / CLI / API / JSON import / Studio); the server owns its own tools |
+| Reach for it when | logic must run in-process (file edit, shell, subagent) | calling an external HTTP API | adopting a whole external MCP server's toolset |
 
-**MCP tools are not a separate runtime type.** An MCP ingestor discovers an MCP
-server's tools and turns each into an HTTP **data tool** that posts a JSON-RPC
-`tools/call`, tagged with a `group` naming the source instance. (Only
-HTTP-transport MCP servers are ingestible; stdio is rejected.)
+**MCP tools are not data tools.** Configuring an enabled MCP **instance** (any
+surface below) is enough — its tools appear automatically, tagged
+`mcp:<instance>`, and each CALL goes straight to the server through a live,
+held client (stdio process / Streamable HTTP / SSE, with the full protocol
+handshake) — never a frozen snapshot. See [MCP servers](#mcp-servers) below.
 
 Code tools **win name collisions** — you cannot register a data tool whose name
 shadows a code tool.
@@ -49,6 +50,11 @@ the one you create and change without a rebuild. See
 }
 ```
 
+`{{secret.api_token}}` above is only real coming through the **manifest**
+write path (`POST /v1/tools/manifest`) — writing this same shape via the DSL
+or Studio needs the literal header value instead; see
+"[The one gotcha](#the-one-gotcha-envsecret-templating-is-manifest-only)" below.
+
 ### Parameters: the schema is the contract
 
 `parameters` is **JSON Schema**, and it reaches the provider verbatim — it is the only
@@ -87,17 +93,25 @@ allow never becomes a request: it returns an `{ error: … }` naming the path
 retries against. Structure is strict; a scalar may arrive in its lossless string form
 (`"2"`, `"true"`) and is never coerced — what the model sent is what the request carries.
 
-**Placeholders** are resolved at turn time:
+**Placeholders**. Two of these resolve at turn time; `{{secret.*}}` resolves
+once, at ingestion — see the gotcha below before reaching for it:
 
-- `{{param}}` — a declared top-level parameter, filled from the model's call.
+- `{{param}}` — a declared top-level parameter, filled from the model's call,
+  every turn.
 - `{{ctx.*}}` — turn context set **server-side, never by the model**: a closed set
   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.
+  absent when the turn carried none. Resolved every turn, like `{{param}}`.
+- `{{secret.*}}` — **only resolved on the manifest ingestion path**
+  (`POST /v1/tools/manifest`; see "[The one gotcha](#the-one-gotcha-envsecret-templating-is-manifest-only)"
+  below), and only once — the resolved value is what gets stored, the token
+  itself never lives on disk and is never re-read per turn. Allowed **only**
+  inside a header named in `secret_headers`. Written any other way — DSL,
+  Studio, or anywhere outside a `secret_headers` header — a
+  `{{secret.*}}` is not a credential the engine knows how to fill; it is an
+  undeclared parameter, and tool registration refuses it exactly like it
+  refuses any other unknown placeholder.
 
 **Validation** happens on ingestion. Common rejections:
 
@@ -183,7 +197,7 @@ 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)
+## Evidence: the lean envelope and grounding
 
 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
@@ -261,16 +275,117 @@ reload, no restart):
 3. **Manifest** — `POST /v1/tools/manifest`. Partial failure is isolated: one
    malformed tool becomes an `errors[]` entry; only a structural manifest error
    fails the whole request. The response reports `{ version, created, updated, errors }`.
-4. **MCP ingestion** — import a server; each of its tools becomes a data tool.
-
-### The one gotcha: env templating is manifest-only
-
-`{{env.*}}` (and `{{secret.*}}`) are substituted **at ingestion, on the manifest
-path**. Other write paths do **not** resolve `{{env.*}}` — a literal
-`{{env.API_URL}}` there fails the `http`/`https` URL check and 422s. Rule:
-**manifest tools may template the URL with `{{env.*}}`; tools written any other
-way must ship a literal URL.** `{{ctx.*}}` and `{{param}}` work everywhere (they
-resolve at turn time, not ingestion).
+4. ~~MCP ingestion~~ — retired. An MCP server's tools are no
+   longer written into this store at all; see [MCP servers](#mcp-servers).
+
+### The one gotcha: env/secret templating is manifest-only
+
+`{{env.*}}` and `{{secret.*}}` are substituted **at ingestion, on the manifest
+path, once** — the resolved literal is what gets stored; the token itself
+never survives to a turn. Other write paths (DSL, Studio) do
+**not** resolve either: a literal `{{env.API_URL}}` in a URL fails the
+`http`/`https` check and 422s; a literal `{{secret.X}}` anywhere — including
+inside a header named in `secret_headers` — fails tool registration the same
+way an unknown parameter would (`ToolDefinition.build`'s placeholder check
+does not special-case it). Rule: **manifest tools may template a URL with
+`{{env.*}}` and a `secret_headers` header with `{{secret.*}}`; tools written
+any other way must ship literal values** — a real URL, and a real (masked on
+read) header value. `{{ctx.*}}` and `{{param}}` work everywhere (they resolve
+at turn time, not ingestion).
+
+## MCP servers
+
+An MCP **instance** is durable config — transport, target, credentials, an
+`enabled` flag — held in its own store, separate from data tools. Once an
+instance is enabled, its tools appear in the catalog automatically (group
+`mcp:<instance>`, `side_effect: true`), and every call goes straight to the
+server through a live, held client — the runtime never converts an MCP tool
+into a stored data tool.
+
+**Three transports**, picked by `transport:`:
+
+| Transport | Target | Notes |
+|---|---|---|
+| `stdio` | `command` + `args`, run as a child process, `env` is its process environment | requires `INSIKA_MCP_STDIO=1` — see below |
+| `http` | `url` + `headers` (Streamable HTTP, the modern default) | egress-guarded like any outbound URL |
+| `sse` | `url` + `headers` | same egress guard as `http` |
+
+**The stdio gate.** A stdio instance is arbitrary command execution by
+config — it saves, but refuses to start ("stdio disabled by env") until the
+operator sets `INSIKA_MCP_STDIO=1` (config-over-convention, the same pattern
+as the egress envs). `http`/`sse` need no such gate; their URL is checked by
+the normal egress allowlist instead.
+
+**Credentials are never visible in plaintext.** `env` (stdio) and `headers`
+(http/sse) mask every value as `__OCULTO__` on read, everywhere (CLI, API,
+Studio). On write, sending the sentinel back **preserves** the stored value; a
+new string **replaces** it; `""` (or omitting the key) **clears** it — the
+same per-key reconciliation `llm_providers` api keys use.
+
+**Discovery vs execution.** `insika mcp refresh <name>` (or `POST
+/v1/mcp/:name/import`, kept as that action's route since before the live
+registry) connects live, lists the server's tools, and caches the result
+(`tools_cache`) purely for display — the Studio panel and `insika doctor`.
+**Execution never reads that cache**: a live turn always goes through the
+held client, which does its own discovery on first use regardless of whether
+`refresh` ever ran.
+
+### Configuring an instance
+
+1. **DSL** — inside `Insika.system { … }` or a single `Insika.agent { … }`:
+
+   ```ruby
+   mcp "tavily", transport: :http, url: "https://mcp.tavily.com/mcp",
+       headers: { "Authorization" => "Bearer #{ENV['TAVILY_KEY']}" }
+   mcp "filesystem", transport: :stdio, command: "npx",
+       args: ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
+   ```
+
+   Code is the **template**: transport/command/args/url/description always
+   follow the declaration on every boot. But once the instance exists, its
+   `enabled` flag and its credentials are the **operator's** — a Studio/CLI/API
+   edit made after boot is never clobbered back by the next restart.
+
+2. **CLI** — `insika mcp list | add | remove | import <file.json> | test <name> |
+   refresh <name>`. `add` takes `--name`, `--transport`, `--command`/`--arg`
+   (repeatable) or `--url`/`--header "Name: value"` (repeatable)/`--env
+   "KEY=value"` (repeatable), `--description`, `--disabled`. `test` connects
+   live and prints the discovered tools (or the error) without any special
+   setup; `refresh` does the same and additionally updates `tools_cache`.
+
+3. **JSON import/export** — the same `mcpServers` shape every MCP client
+   (Claude Desktop, Cursor, …) already uses:
+
+   ```jsonc
+   {
+     "mcpServers": {
+       "tavily":     { "url": "https://mcp.tavily.com/mcp", "headers": { "Authorization": "Bearer …" } },
+       "filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"] }
+     }
+   }
+   ```
+
+   `insika mcp import FILE.json` upserts every entry (a bare `command` implies
+   `stdio`; a bare `url` implies `http`; add `"transport": "sse"` explicitly
+   for SSE — the bare format has no other way to spell it). The same parser
+   backs `PUT /v1/mcp` and Studio's "Import JSON" box; `export` produces the
+   document back with secrets masked as `__OCULTO__`, so round-tripping an
+   export never wipes a stored credential.
+
+4. **HTTP API** (operator-only, gateway Bearer):
+   - `GET /v1/mcp` — every instance, masked.
+   - `GET /v1/mcp/:name` — one instance, masked.
+   - `PUT /v1/mcp` — upsert (body = the instance attrs, `name` required).
+   - `DELETE /v1/mcp/:name` — remove (idempotent).
+   - `POST /v1/mcp/:name/import` — refresh (connect live, list tools, cache).
+
+5. **Studio** — the `/studio/mcp` panel (create/edit/delete). The form is
+   transport-aware (stdio shows command/args/env, http/sse shows
+   url/headers); each instance shows a status chip ("N tool(s)", "untested",
+   "stdio disabled", or "off") and its discovered tools from `tools_cache`; a
+   "Test connection" button dispatches the same `refresh_mcp_tools` seam as
+   `insika mcp test`; an "Import JSON" box takes a `mcpServers` document and
+   fans it out into one `upsert_mcp` per entry.
 
 ## Making it appear — and enter the tool-loop
 
@@ -361,9 +476,43 @@ Work down this checklist:
 4. **URL literal?** For non-manifest tools, an unresolved `{{env.*}}` would have
    422'd at import — re-check the definition.
 
+## The `save_artifact` built-in
+
+`save_artifact` is a **registry tool** — it obeys the same per-agent
+`tools_allow` as any data tool, and an agent that did not name it cannot call
+it (`tools_allow: %w[save_artifact]`). The agent hands in `title` + `content`
+and gets the URL back; the tenant is bound from the turn, never a parameter the
+model types. See [Artifacts](ARTIFACTS.md) for the tool contract, the serving
+routes, the signed link and the retention/LGPD reach.
+
+## The usage report — `insika tools:report`
+
+The per-session trace answers "what did this conversation call"; nothing used to
+answer "what does this agent carry and never use". The report aggregates the
+stored traces per agent (tasks → sessions → `tool_traces`, the same read the
+Studio does) and flags three shapes:
+
+- **`never_called`** — in `tools_allow`, zero calls in any stored trace. Dead
+  weight: its schema ships on every request and buys nothing.
+- **`error_rate`** — over 30% conventional errors (the trace's `ok` flag) inside
+  the window (default 14 days). Either the tool is broken or the model cannot
+  hold its contract.
+- **`stale`** — called at some point, but not once inside the window.
+
+```bash
+insika tools:report                        # every stored agent
+insika tools:report --agent store-support  # one agent
+insika tools:report --days 30 --json       # wider window, machine-readable
+```
+
+Read-only by design: the report names candidates, the **operator** removes — a
+flagged tool may still be the one a rare but critical flow needs. Counts are
+"at least", never exact: the trace keeps a capped tail per session.
+
 ## See also
 
 - [Agents](AGENTS.md) — allowlists, groups, and per-agent tool exposure.
+- [Artifacts](ARTIFACTS.md) — the report destination: the tool, the routes, the signed link.
 - [Plugins](PLUGINS.md) — where a code tool comes from, and how to package one.
 - [Security](SECURITY.md) — egress, sandbox, and approval gating together.
 - [Architecture](ARCHITECTURE.md) — the tool-loop and side-effect checkpointing.

data/docs/WHY.md

@@ -1,6 +1,6 @@
 ---
 title: Why Insika
-parent: Understand the idea
+parent: Start here
 nav_order: 1
 permalink: /why/
 ---

data/docs/WORKFLOWS.md

@@ -1,7 +1,7 @@
 ---
 title: Workflows
-parent: Build an agent
-nav_order: 5
+parent: Core concepts
+nav_order: 6
 permalink: /workflows/
 ---
 

data/docs/_includes/head_custom.html

@@ -0,0 +1,5 @@
+{%- comment -%}
+  Appended inside <head> on every page by the theme. The theme's own favicon
+  include only looks for a legacy /favicon.ico, so the SVG icon is declared here.
+{%- endcomment -%}
+<link rel="icon" href="{{ '/assets/img/favicon.svg' | relative_url }}" type="image/svg+xml">

data/docs/_includes/title.html

@@ -0,0 +1,13 @@
+{%- comment -%}
+  Overrides the theme's title.html so the sidebar shows the pillar mark next to
+  the wordmark. The theme's own `site.logo` path swaps the title for a single
+  background image, which would drop the text — and the text is what the
+  browser tab, the skip link and screen readers rely on.
+{%- endcomment -%}
+<span class="site-title-mark" aria-hidden="true">
+  <svg viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg" focusable="false">
+    <rect x="3" y="3" width="18" height="3.6" rx="1"/>
+    <rect x="8.7" y="7.6" width="6.6" height="8.8" class="shaft"/>
+    <rect x="3" y="17.4" width="18" height="3.6" rx="1"/>
+  </svg>
+</span>{{ site.title }}

data/docs/_sass/color_schemes/insika.scss

@@ -0,0 +1,32 @@
+// Insika's colour scheme for Just the Docs.
+//
+// Selected by `color_scheme: insika` in _config.yml; the theme picks the file up
+// by name and needs no other wiring. This file only maps the palette tokens from
+// _sass/custom/setup.scss onto the theme's own `!default` variables — anything
+// that is not a theme variable belongs in _sass/custom/custom.scss.
+//
+// The palette is warm stone with a terracotta accent: the name is Zulu for the
+// pillar that carries a structure, and the docs should read like one — quiet
+// neutrals, a single load-bearing colour. It is deliberately unlike the blue and
+// purple that every other Ruby docs site defaults to.
+
+$color-scheme: insika;
+
+$body-background-color: $white;
+$body-heading-color: $ink-900;
+$body-text-color: $ink-700;
+$link-color: $terracotta-100;
+$nav-child-link-color: $ink-700;
+$sidebar-color: $stone-050;
+$border-color: $stone-200;
+$base-button-color: $stone-100;
+$btn-primary-color: $terracotta-100;
+$code-background-color: $stone-100;
+$feedback-color: darken($sidebar-color, 3%);
+$table-background-color: $white;
+$search-background-color: $white;
+$search-result-preview-color: $ink-500;
+
+// The theme ships accessible-pygments; github-light is the one that sits calmly
+// on a warm background instead of fighting it.
+@import "./vendor/accessible-pygments/github-light";

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

@@ -1,13 +1,13 @@
 ---
 title: The domain-free core
-parent: Operate & prove it
-nav_order: 9
+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 (RFC-0036): the gem carries no store
+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
@@ -90,7 +90,7 @@ metadata domain: "e-commerce-pt-BR"
 ```
 
 - **Outcome funnel** — `funnel:` on the profile (see
-  [Outcomes](AGENTS.md#outcomes--business-results-over-real-traffic-ws7)).
+  [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.

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 }