insika 0.3.0 → 0.7.0

data/docs/PLUGINS.md

@@ -1,7 +1,7 @@
 ---
 title: Plugins
-parent: Build an agent
-nav_order: 7
+parent: Integrate
+nav_order: 5
 permalink: /plugins/
 ---
 
@@ -131,16 +131,34 @@ keyword is itself an error rather than being silently ignored.
 
 ### Discovery and enabling
 
+The loader runs **at boot, in every composition root** — the server wirings and
+a DSL-run agent alike — single-threaded, before the first request is accepted.
+A plugin therefore either exists for the whole life of the process or not at
+all; there is no half-loaded state a turn can observe.
+
 Plugins come from three kinds of root, and they differ in **who has to say yes**:
 
 | Root | How it is found | Enabled by default |
 |---|---|---|
 | **Gem** | the gem calls `Insika::Plugin.announce(__dir__)` when its `lib/` loads | **yes** — installing it is the consent |
-| **Workspace** | a directory in the deployment's plugin roots | no — must be listed in `enabled:` |
-| **Bundled** | `plugins/` in this repo | no — must be listed in `enabled:` |
+| **Workspace** | the directory named by `INSIKA_PLUGIN_DIR` | no — list the id in `INSIKA_PLUGINS` |
+| **Bundled** | `plugins/` in this repo | no — list the id in `INSIKA_PLUGINS` |
+
+```sh
+INSIKA_PLUGIN_DIR=/srv/insika/plugins   # workspace root to scan
+INSIKA_PLUGINS=weather,acme             # ids to enable from workspace/bundled roots
+INSIKA_PLUGINS_DISABLED=insika-code     # ids that never load, no matter what
+```
 
-`disabled:` is an absolute veto: an id listed there never loads, even if it is
-also in `enabled:` (deny wins, the same rule as every allowlist in the engine).
+`INSIKA_PLUGINS_DISABLED` is an absolute veto: an id listed there never loads,
+even if it is enabled or shipped by an installed gem (deny wins, the same rule
+as every allowlist in the engine).
+
+When two roots ship the same `id`, precedence is workspace → gems → bundled:
+the first root wins, so an operator's local copy always overrides an installed
+one. Skills and prompts a plugin ships join the catalogs at the **lowest**
+precedence for the same reason — a workspace or Studio-authored skill beats a
+plugin's same-named one.
 
 A gem announces itself explicitly — Insika never scans the load path or your
 installed gems:
@@ -173,6 +191,33 @@ config_schema:
 The manifest is committed; the secret is not. This mirrors how data tools handle
 `{{secret.*}}`.
 
+## Why it is built this way
+
+Five decisions carry the whole design; knowing them explains every behavior
+above.
+
+1. **Data before code.** Most agent runtimes make code the unit of extension
+   and a restart the price of every integration. Insika inverts that: tier 1
+   (data tools, MCP imports, skills) covers most integrations hot, with no
+   deploy, and tier 2 exists only for what genuinely needs to run in-process.
+   A smaller code-plugin surface is a feature — less to audit, less to break.
+2. **Manifest before code.** Discovery never executes anything: the manifest is
+   read, validated, and gated first, and only then is the entry `require`d.
+   You can inventory, enable, and veto plugins without running them.
+3. **Contracts are the public API.** Anything addressable by name — tools,
+   workflows, capabilities, channels — must be declared in `contracts`, and an
+   undeclared registration is ignored with a warning. A plugin cannot quietly
+   widen its surface between versions, and a channel cannot mount a route
+   nobody asked for.
+4. **Announce, never scan.** A gem opts in with one explicit
+   `Insika::Plugin.announce` call; Insika never walks the load path or your
+   installed gems looking for candidates. What loads is exactly what was
+   announced or configured — auditable from the boot log alone.
+5. **One bad plugin never takes the deployment down.** Registration is staged
+   and committed atomically; a raise inside `register(api)` rolls back
+   everything that plugin staged and boot continues. Enablement is explicit,
+   and deny wins.
+
 ## Publishing a plugin
 
 - **Name it `insika-plugin-<thing>`.** The convention *is* the registry for now:

data/docs/POLICY.md

@@ -0,0 +1,216 @@
+---
+title: Limits and policy
+parent: Core concepts
+nav_order: 2
+permalink: /policy/
+---
+
+# Limits and policy
+
+What an agent may do is layered. Each layer is independent, opt-in where it
+matters, and editable hot — the same profile keys covered in [Agents](AGENTS.md),
+grouped here because they answer one question: what is this agent allowed to do,
+and what stops it when it tries to do more.
+
+What an agent may do is layered. Each layer is independent, opt-in where it
+matters, and editable hot.
+
+## Layer 1: Tools (what it can call)
+
+`tools_allow` / `tools_deny` / `tools_allow_groups` decide which tools enter the
+turn's tool-loop, enforced by the tool-allowlist policy. See [Tools](TOOLS.md)
+for how tools are defined and registered, and [`examples/data-tool/`](https://github.com/guizaols/insika/tree/main/examples/data-tool/).
+
+## Layer 2: Policies and approvals
+
+Policies are named entries evaluated before the turn runs. Builtins cover
+tool-, skill-, and workflow-allowlisting, plus **`ApprovalRequired`** — which
+does not allow or deny but *tags* a tool as needing human approval. Set
+`approvals_required: [tool names]`; the gate then fires when the model tries to
+call that tool, suspending the turn until an operator approves it in the Studio.
+See [Security](SECURITY.md#human-approval).
+
+## Layer 3: Guardrails (content safety)
+
+`guardrails` configures input/output content safety per agent — **opt-in**, so an
+agent that says nothing gets a conservative default (deterministic detectors on,
+LLM moderator off). See [Security](SECURITY.md#guardrails) and
+[`examples/guardrails/`](https://github.com/guizaols/insika/tree/main/examples/guardrails/).
+
+## Layer 4: Edge limits (flood and spend control)
+
+Two independent, opt-in ceilings, enforced *before* the model is ever called —
+opt-in everywhere except on a public channel, where `chat_rate_limit` is
+[required](CHANNELS.md#a-rate-limit-is-required-not-suggested) and the
+[web widget](CHANNELS.md#the-web-widget) refuses to serve without one:
+
+- **`chat_rate_limit`** — turn attempts per session per `chat_rate_window`.
+- **`agent_token_ceiling`** — total tokens per agent per `agent_token_window`.
+
+On breach the turn halts gracefully with a configurable `limit_response` and
+**zero LLM calls**. Windows are set at the platform level; the ceilings can be set
+per agent (blank inherits the platform value, `0` explicitly disables it).
+
+> ⚠️ The token window default is **86400 (daily)**. To express "500k tokens per
+> **hour**", set `agent_token_window = 3600` explicitly. A per-agent key that is
+> *present but nil* reads as OFF for that agent — leave the key **absent** to
+> inherit. See [Security](SECURITY.md#edge-limits).
+
+### Calendar budgets — the daily/monthly cost wall
+
+A third, opt-in ceiling for the *billing* shape the windows above cannot express:
+a spend cap over a CALENDAR day or month, per `(tenant, agent)` when
+multi-tenant. Data on the profile (DSL `budget` or the pack's `budget` key):
+
+```ruby
+budget daily: 100_000, monthly: 2_000_000, soft: false   # or soft: true
+```
+
+- Tokens count the **billed** spend — `input + output + cached + cache_creation`
+  (the cached prefix is the bulk of the bill, not an afterthought).
+- **Hard** (the default, `soft` absent/false): a turn that arrives with the
+  window's spend already at/over the cap **fails** with the typed
+  `Insika::BudgetExceeded` — the envelope reads `budget_exceeded` +
+  `retry_after` (seconds until the window rolls). It is NOT a customer reply; it
+  is an operator signal.
+- **Soft** (`soft: true`): the same turn RUNS — crossing the cap emits one
+  `budget_warning` event per window and injects a note into the context (the
+  model sees it, the transcript does not).
+- Either way, crossing `alert_at` (default `0.8` of the cap) fires the same
+  warning **before** the wall, once per window.
+
+> ⚠️ Unlike the ceilings above, the cap that counts is per **calendar** window —
+> a `daily` budget rolls at UTC midnight, a `monthly` one on the 1st, whatever
+> the sun. `agent_token_window` is a fixed seconds window and cannot express
+> "the day resets at midnight".
+
+### Reliability — retries, fallback, circuit breaker
+
+The provider interaction is a single attempt by default (RubyLLM's own 2
+transport retries aside). For a store that cannot have a dead model take the
+chat down, the reliability policy is DATA on the profile:
+
+```ruby
+reliability retries: 2, backoff: "exponential",
+            fallback: ["openai/gpt-4o-mini"],
+            circuit_breaker: { after: 10, within: 60, cooldown: 300 }
+```
+
+- **Retries** — transient failures (`:retryable` / `:rate_limited_*` per the
+  error classification) retry with exponential backoff, up to `retries`.
+  A `:fatal` (auth, billing, bad request) is NEVER retried or rotated. Each
+  attempt runs on a fresh chat — the customer-visible answer comes only from
+  the attempt that returns.
+- **Fallback** — after a node's retries, the turn ROTATES to the next model in
+  the chain: the profile's `fallback` refs first, then the platform
+  `fallback_models`. The turn's usage is attributed to the model that actually
+  spoke (`model_source: "fallback"`).
+- **Circuit breaker** — per `(tenant, provider/model)`: `after` failures within
+  `within` seconds open the circuit; while open, the turn fail-fasts with the
+  typed `circuit_open` + `retry_after` (remaining cooldown) and the provider is
+  never touched. After `cooldown` a half-open trial closes the circuit on
+  success or reopens it on failure.
+- **`timeout`** — per-attempt ceiling (default 30s), counted as a retryable
+  failure.
+
+Absent `reliability` = the plain single attempt, byte-for-byte today's
+behavior.
+
+### Intent routing — classify before you answer
+
+For a store that must tell "shopping" from "order" from "human" up front,
+routing is data on the profile:
+
+```ruby
+routes "shopping" => "the customer wants to browse products",
+       "order"    => { "description" => "asks about an existing order",
+                       "delegate" => "order-agent" },
+       "human"    => { "description" => "the customer asks for a person",
+                       "stuck" => true, "message" => "A person will help you." },
+       "default"  => "shopping",
+       "model"    => "deepseek-v4-flash"   # the cheap classifier (absent = the agent's own)
+```
+
+- **Classification** — when `routes:` is present, the message is classified into
+  one route with the configured model BEFORE the agent chat is assembled, from
+  a prompt auto-generated out of the descriptions (no per-route prompt file).
+  The route rides the turn: `state.route`, the `:route_classified` event, and
+  the terminal event additively.
+- **Deterministic default** — the model's answer must be a route name; prose,
+  an unknown name, or an empty answer falls back to `default`, never invents.
+  A classifier call that FAILS leaves the turn unrouted (routing is additive —
+  it must not break the turn).
+- **Cost** — the classification is an extra provider call, counted in the
+  turn's usage (the trace, the token ceiling and the budget all see it).
+- **Actions** — a route value may be a description string, or a Hash:
+  `delegate: "<agent-id>"` hands the turn to that existing agent and its
+  answer becomes the parent's; `stuck: true` ends the turn with the [stuck
+  outcome](AGENTS.md#the-stuck-signal--i-cannot-proceed) and the route's `message`
+  (or description) as the lead-in — the consumer interprets it. A route with
+  neither is just a label. A delegation counts against the same delegation
+  depth cap as a subagent (`INSIKA_SUBAGENT_DEPTH_CAP`, default 5), so a pair
+  of agents routing to each other stops instead of looping.
+
+Absent `routes` = no classification, no extra call, byte-identical turn.
+
+### Operator alerts — the webhook
+
+Three operational events — `budget_warning`, `breaker_open`, `delivery_failed` —
+can be answered per agent with a webhook:
+
+```ruby
+alerts webhook: "https://ops.example.com/insika-alerts"
+```
+
+When present, each such event is POSTed to the URL as JSON (the event's
+type/data/meta, plus the agent). Delivery rides the same outbox + claim +
+bounded-retry pipeline as channel answers — at-most-once, crashed deliveries
+recovered at boot. The engine transports the event and does not interpret it: a
+Slack/CRM adapter is the consumer's. Absent `alerts` = nothing is sent.
+
+Separately, with `INSIKA_TURN_TIMING`, the provider's **live TTFB** is carried in
+the streaming envelope: the first content chunk emits an `insika.ttft` frame
+(`ttft_ms`) on `/v1/responses`, alongside the per-turn `timing` breakdown on the
+final `response.completed`. Additive and opt-in — absent by default.
+
+## Layer 5: Reasoning (thinking)
+
+Controls the model's thinking budget, resolved by precedence
+**Chat > Agent > Model > Global** (first non-blank wins):
+
+| Scope | Where |
+|-------|-------|
+| Chat | session var `__llm__.thinking` |
+| Agent | `profile.params["thinking"]` |
+| Model | platform `model_params[<ref>].thinking` |
+| Global | platform `thinking` |
+
+Values: `off | on | low | medium | high`. `off`/`on` toggle thinking; the effort
+levels map to the provider's thinking-effort parameter. This is a control
+primitive, not a latency lever — turning reasoning off does not necessarily speed
+up a turn, because most of a turn's latency is the provider itself, not thinking.
+
+Whether the reasoning ever reaches the **customer** is a separate switch, off by
+default:
+
+```ruby
+edge_stream thinking: true, intermediate: false
+```
+
+`thinking` is the provider's reasoning; `intermediate` is the model narrating its
+own tool loop ("let me look that up"). Both are always on the event stream for the
+Studio and the trace — this decides only whether `/v1/responses` translates them,
+and each opted-in channel gets its own frame type, never the answer's. See
+[Architecture](ARCHITECTURE.md#what-crosses-the-edge).
+
+> ⚠️ Turn it on knowing your consumer. One that concatenates every text delta into
+> a single message — a WhatsApp adapter — will only be affected once it learns to
+> read the new frames, and when it does, the deliberation is what the customer
+> reads. That is the operator's call, which is why it is neither a default nor a
+> global.
+
+## See also
+
+- [Agents](AGENTS.md) — the profile these keys live on.
+- [Tools](TOOLS.md) — how a tool gets defined, registered and allowed.
+- [Security](SECURITY.md) — the deployment-side counterpart: sandbox, egress, secrets.

data/docs/REFINEMENT.md

@@ -1,7 +1,7 @@
 ---
 title: Refinement
-parent: Operate & prove it
-nav_order: 5
+parent: Improve
+nav_order: 2
 permalink: /refinement/
 ---
 
@@ -51,11 +51,14 @@ Or from **Studio → Refinement**: pick the agent, press Run, and the same repor
 renders with each session id linking to its transcript. Every finding is a claim
 you can go and check.
 
-There is no scheduler in the engine, by design. A run is one command
-(`run_refinement`), and the CLI and the button are the two ways to fire it. If you
-want it on a timer, point your own cron at the authenticated route the button uses
-— that keeps the engine free of a background ticker and of the single-node
-assumption one would bring.
+A run is one command (`run_refinement`), and the CLI and the button are the
+two ways to fire it. There is still no built-in timer *for the report itself*,
+but there is one for the *agent*: fine-grained recurring turns live in
+[Schedules](SCHEDULING.md), and a refinement run scheduled like any other turn
+is just a message the agent's schedule sends it. If you prefer to stay outside
+the engine, pointing your own cron at the authenticated route the button uses
+works just the same — both paths are supported, the engine's trigger is the
+built-in one.
 
 ```
 insika refine ─┐
@@ -466,8 +469,10 @@ prompt edits have real leverage, and it is also where they do damage.
 
 ## What this is not
 
-It has no scheduler: a run happens because a person or a cron asked for one, never
-because a timer inside the engine went off. A proposal is written when you ask for
+A run happens because a person or a cron asked for one — the refinement
+pipeline has no timer of its own, and if you want one, a schedule
+([Schedules](SCHEDULING.md)) makes a run a turn any agent can be scheduled to
+send. A proposal is written when you ask for
 one, and — unless you turned on [`auto_apply`](#applying-without-a-human), which is
 off until you do and bounded when you do — applied when you approve it. And it cannot
 touch your guardrails, tools, policies, model pins or limits, and not because a prompt

data/docs/RELEASING.md

@@ -59,10 +59,10 @@ GEM_HOME="$T/gemhome" GEM_PATH="$T/gemhome" ruby -e '
   puts "clean"'
 ```
 
-### The 1.0 release gate — the RFC-0036 install proof (E1)
+### The 1.0 release gate — the clean-install proof
 
 For the 1.0 release the proof above is scripted and its **installed-bytes**
-half is asserted by the domain-boundary suite (C1) on the artifact, not the
+half is asserted by the domain-boundary suite on the artifact, not the
 repo. Run the runbook, with a key (the smoke turn is one `reply` through the
 installed gem):
 
@@ -77,12 +77,12 @@ only the public docs. Archive the PASS output with the release notes — it is
 the 1.0 exit criterion "install proof by the docs alone".
 
 The same gate writes the freeze date: a breaking `/v1` change needs a new
-`Insika-Version` entry (server/app.rb), a compatibility branch (RFC-0016 A5)
+`Insika-Version` entry (server/app.rb), a compatibility branch
 and a rewritten `**Frozen as of:**` line in `docs/API.md` — the version-gate
 spec pins the two together, and the 1.0 release writes the date at release
 time.
 
-Catalog submission checklist (RFC §6): verify the best-of-Agent-Harnesses
+Catalog submission checklist: verify the best-of-Agent-Harnesses
 catalog size at submission time (161 vs 154 — the counts diverge across the
 catalog's own pages) and cite the conformance suite as the `durable` evidence.
 

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/
 ---
 
@@ -122,7 +122,7 @@ 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):