insika 0.3.0 → 0.7.0

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,7 +367,7 @@ 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 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
@@ -394,7 +394,7 @@ forgotten or aged out. Three operations enforce the right to be forgotten:
   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)
+### 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
@@ -402,7 +402,7 @@ 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
+(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.
@@ -412,7 +412,7 @@ deployment (in `single_tenant` the bare cell is the designed customer shape), an
 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)
+### 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,
@@ -428,6 +428,22 @@ 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
@@ -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

@@ -1,7 +1,7 @@
 ---
 title: Soak
-parent: Operate & prove it
-nav_order: 4
+parent: Operate
+nav_order: 5
 permalink: /soak/
 ---
 

data/docs/TEMPLATES.md

@@ -0,0 +1,134 @@
+---
+title: Templates
+parent: Integrate
+nav_order: 6
+permalink: /templates/
+---
+
+# Templates
+
+Example agents shipped **inside the gem** — `lib/insika/templates/<name>/`,
+one DSL file per template. `insika new <name>` copies it for you to run and
+edit; the same file is what the Studio gallery evaluates to create the
+agent from a click. One source of truth, two doors — never a parallel pack
+format to drift.
+
+## The gallery
+
+```bash
+insika new --list
+```
+
+```
+travel-planner     Starter    Weather + currency data-tools against keyless public APIs …
+research-analyst   Advanced   Insika.system fan-out — three specialist subagents research …
+daily-digest       Always-on  A recurring schedule plus save_artifact build and publish …
+review-panel       Teams      Two specialists reviewed in parallel by a synthesizing lead …
+repo-explorer      MCP        Live MCP tool-loop over http — answers questions about any …
+browser-agent      MCP        Live MCP tool-loop over stdio — navigates and summarizes …
+```
+
+```bash
+insika new travel-planner            # copies ./travel-planner/{agent.rb,README.md}
+insika new travel-planner my-trip    # ...into ./my-trip/ instead
+```
+
+The CLI prints the exact run line, including any env the template needs
+**set** (not just available as an override) — a stdio MCP template needs
+`INSIKA_MCP_STDIO=1`, for instance. The generated script *is* the editing
+surface: no Gemfile, no questionnaire, no placeholders to fill in.
+
+The same roster appears as a "+ from template" gallery on the Studio
+`/studio/agents` page — clicking **Create** dispatches the identical
+`:create_agent` (and, for a system template, one per agent) the CLI-run
+copy would produce. A template marked `studio: false` in its frontmatter
+(none in wave 1) shows a "CLI-only for now" note instead of a button —
+reserved for a template whose value is a durable workflow, until workflow
+import into a running store exists.
+
+## The MCP trail: point it at your own server
+
+`repo-explorer` (http) and `browser-agent` (stdio) are not showcases for
+one MCP vendor — they demonstrate exactly how to plug **any** MCP server
+into an agent. Each ships with a working, keyless default so
+`insika new` + the run line works with zero setup, but the server is a
+config value:
+
+```bash
+MCP_URL=https://your-mcp-server/mcp DEEPSEEK_API_KEY=sk-... ruby repo-explorer/agent.rb "..."
+MCP_COMMAND=your-mcp-server INSIKA_MCP_STDIO=1 DEEPSEEK_API_KEY=sk-... ruby browser-agent/agent.rb "..."
+```
+
+Swap the env var, rewrite the instructions for the new server's tools —
+nothing else in `agent.rb` changes.
+
+## Writing a template
+
+A template is `lib/insika/templates/<name>/agent.rb` + `README.md`.
+
+**The frontmatter contract** — a `# ---` … `# ---` comment block, YAML
+inside, right after the standard `# frozen_string_literal: true` (that
+magic comment is skipped automatically — a template doesn't have to break
+the convention every other file in the gem follows):
+
+```ruby
+# frozen_string_literal: true
+
+# ---
+# title: My Template
+# trail: Starter | Advanced | Always-on | Teams | MCP
+# description: one line, shown in the CLI list and the Studio card.
+# capabilities: comma, separated, tags
+# studio: true            # optional, default true
+# env: SOME_REQUIRED_VAR   # optional — env the run line must SET, not just may override
+# requires: Node.js and npm   # optional — a local dependency beyond the gem + a provider key
+# ---
+```
+
+**The two-doors mechanics**, in the file itself:
+
+1. `require "insika"` — gem-style, never `require_relative` (the file gets
+   copied out of the gem into an arbitrary directory).
+2. Build the agent/system as a normal top-level local: `travel = Insika.agent(...) { ... }`.
+3. Guard the CLI demo footer: `if __FILE__ == $PROGRAM_NAME ... end`. False
+   whenever `Insika::Templates.evaluate` loads the file (never true from
+   inside the gem/Studio process), so the Studio door never makes a network
+   call, prints anything, or parses `ARGV`.
+4. End the file with the **bare** built value (`travel`, `panel`, `team`,
+   …) as its last expression — `evaluate` runs the file in an isolated
+   `instance_eval` and returns whatever that last expression is. No
+   registration call, no second format.
+5. **No top-level constants.** `instance_eval`'s isolation keeps local
+   variables and `def`s from leaking into the NEXT template evaluated in
+   the same process, but Ruby scopes a `CONST = ...` assignment lexically,
+   not by `self` — it would leak. Use a local variable (closures see it
+   fine from inside a `do...end` block) — every wave-1 template does.
+
+**Engine-only rules** (enforced by the lint below):
+provider-agnostic (one provider key), zero tenant/store data, external
+calls only to keyless public APIs, every tool/mcp group covered by an
+explicit allowlist.
+
+**Declaring an `mcp` server** auto-adds `"mcp:<name>"` to that agent's
+`tools_allow_groups` (`Insika::DSL::Builder#mcp`) — without it the agent
+could never call the MCP tool it just declared, since `PackImporter`
+forces `tools_allow: []` for a pack with no `data_tool`. A **system**-level
+`mcp` (declared outside any member `agent { }` block) grants no agent
+access by itself — declare it inside the specific agent that needs it.
+
+## The E3 lint
+
+`spec/insika/templates_spec.rb` iterates `Insika::Templates.all` for real —
+one example per template name, so a broken new template fails by name, not
+a generic loop assertion. It checks, per template:
+
+- evaluates cleanly to schema-valid pack(s) (`id`/`model` present);
+- every `data_tool` it declares is in that SAME pack's `tools_allow`;
+- every `mcp` instance's group is granted by SOME agent in the pack(s);
+- every referenced host (`data_tool` URL, http/sse `mcp` URL) passes
+  `Insika::EgressGuard.violation` — public HTTPS only, same guard a live
+  turn would apply;
+- no hardcoded secret-shaped literal (`sk-...`, a long `Bearer ...` token)
+  in the source.
+
+Run it before adding a template: `bundle exec rspec spec/insika/templates_spec.rb`.

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,19 @@ 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.
+
 ## 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 }}