insika 0.3.0 → 0.8.0

data/docs/ROUTER.md

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

data/docs/RUNNING-LOCAL.md

@@ -1,7 +1,7 @@
 ---
 title: Running locally
-parent: Build an agent
-nav_order: 8
+parent: Start here
+nav_order: 2
 permalink: /running-local/
 ---
 
@@ -62,7 +62,7 @@ whole surface answers `503`, never open by omission.
 | `INSIKA_DB` | — (ephemeral memory) | SQLite path → config + execution survive a restart |
 | `BIND` | `http://localhost:9292` | host:port |
 | `ADMIN_TOKEN` | `local-demo` | token for `/studio` |
-| `OPENCLAW_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN` | Bearer for the whole `/v1` + `/a2a` surface |
+| `INSIKA_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN` | Bearer for the whole `/v1` + `/a2a` surface |
 | `DEEPSEEK_MODEL` | `deepseek-v4-flash` | model |
 
 With persistence:
@@ -122,13 +122,13 @@ prompt files, skills, and one data-tool per file:
 > **Data-tool URLs must be literal on the pack path.** The pack import does not
 > resolve `{{env.*}}` — bake the backend base URL into each `tools/*.json` at
 > generation time. (Only the *manifest* path resolves `{{env.*}}`.) See
-> [Tools](TOOLS.md#the-one-gotcha-env-templating-is-manifest-only).
+> [Tools](TOOLS.md#the-one-gotcha-envsecret-templating-is-manifest-only).
 
 Provision it (runs as a client against the live server; the internal token comes
 from the environment, never disk):
 
 ```bash
-INSIKA_URL=http://localhost:9292 OPENCLAW_GATEWAY_TOKEN=local-demo \
+INSIKA_URL=http://localhost:9292 INSIKA_GATEWAY_TOKEN=local-demo \
   bundle exec ruby scripts/import_pack.rb /path/to/pack
 ```
 

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

@@ -27,7 +27,7 @@ The layers, from the edge inward:
 ## The Bearer gate
 
 The `/v1` and `/a2a` surface answers only with
-`Authorization: Bearer <OPENCLAW_GATEWAY_TOKEN>` (which falls back to `ADMIN_TOKEN`).
+`Authorization: Bearer <INSIKA_GATEWAY_TOKEN>` (which falls back to `ADMIN_TOKEN`).
 The check runs in the router, **before** any dispatch, against an **allowlist** of
 public routes — so a route added later is closed until someone deliberately publishes
 it. Only these answer without a token:
@@ -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/
 ---
 
@@ -88,7 +88,7 @@ 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)
+# the run itself (INSIKA_URL + INSIKA_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)

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`.