insika 0.0.1 → 0.2.0

data/docs/DEPLOY.md

@@ -0,0 +1,354 @@
+---
+title: Deploy
+parent: Ship it
+nav_order: 3
+permalink: /deploy/
+---
+
+# Deploy
+
+How to run the engine in a container (Railway today, Kubernetes later) and how to
+measure performance and load.
+
+> **This page deploys the repo, not the gem.** The reference deployment is a
+> checkout of this same repository — `config/` is its composition root, and the
+> `Gemfile` consumes the engine through the gemspec. An adopter deploys
+> `gem install insika` (or a `Gemfile` line) instead.
+
+## Image (Docker)
+
+The `Dockerfile` (multi-stage, YJIT on) serves `config.ru` under Falcon. The Studio
+ships with its `dist/` built and vendored — **no Node in the build**. The backend
+is durable SQLite (WAL) at `INSIKA_DB`; mount a volume and point it inside.
+
+```bash
+docker build -t insika .
+docker run -p 9292:9292 -v insika-data:/data \
+  -e DEEPSEEK_API_KEY=sk-... \
+  -e OPENCLAW_GATEWAY_TOKEN=change-me \
+  insika
+curl localhost:9292/up      # {"status":"ok"}
+```
+
+## The process model
+
+The image boots **N Falcon worker processes over one SQLite file**
+(`WEB_CONCURRENCY`, default 1). That number is a **contract input, not a tuning
+knob**: it decides which engine semantics hold cluster-wide and which are
+per-worker. The default is 1 because the per-worker semantics are the product
+— the queue modes (`collect`/`steer`) and FIFO ordering need one
+session actor; raise N only with sticky routing per session in front. The
+contract:
+
+> Everything here describes N workers of **one** deployment — one graph, replicated.
+> N *graphs* inside one process is a different contract, and it is
+> [Embedding](EMBEDDING.md): there each graph owns its own store and credentials,
+> and the host — not the engine — installs the drain.
+
+1. **N workers share one SQLite store.** Everything durable — sessions, tasks,
+   checkpoints, outbox, delegations — is cross-process state. Any status
+   transition that hands work to "whoever gets there first" goes through a
+   transactional claim (`Store#transaction`); a bare read-check-write on a
+   shared status field is a bug by definition.
+2. **A session's live semantics are per-worker.** Per-session FIFO ordering,
+   `steer`, `interrupt`, `pause`/`cancel` and the SSE watch operate on the
+   worker that holds the session's actor. The engine does **not** promise them
+   across workers. A deploy that needs those semantics for a session must route
+   that session's traffic to one worker (sticky routing) — or accept per-worker
+   best-effort.
+3. **Recovery is part of boot, in every wiring.** Every worker boots through
+   `Server::Boot`, which runs recovery **before the listen**. The per-record
+   sweeps (undelivered outbox records, undelivered delegation results) run in
+   every worker — each record carries its own transactional claim (item 1), so
+   at-most-once holds however many workers sweep. The **task sweep** runs
+   **once per boot generation**: the sweep's "orphaned `:running`" test cannot
+   see a fiber living in a *sibling* process, so the first worker to claim
+   `INSIKA_BOOT_ID` (one id per container start, exported by
+   `deploy/entrypoint.sh`) sweeps and the rest skip. A worker respawned
+   mid-generation skips too — sweeping then would steal its siblings' live
+   turns; its own orphans wait for the next generation (the next deploy).
+   Without `INSIKA_BOOT_ID` (single-process runs) every boot sweeps.
+4. **Shutdown is a drain, not a kill.** On SIGTERM (or SIGINT) a worker stops
+   accepting new turns — a turn that arrives mid-drain stays `:queued` and the
+   next boot's recovery replays it — and waits up to `INSIKA_DRAIN_TIMEOUT`
+   (default **20s**) for the in-flight ones. A second signal skips the wait.
+   Whatever the deadline abandons dies `:running`, and item 3 picks it up at the
+   next boot. The layers above must grant the time: `deploy/entrypoint.sh`
+   passes Falcon `--graceful-stop` = drain + 5 (Falcon's own default is 1s),
+   and the platform's SIGTERM→SIGKILL buffer must be ≥ drain + 10. **On Railway
+   that buffer defaults to 0** — SIGKILL right after SIGTERM, which cancels the
+   whole drain — so set `RAILWAY_DEPLOYMENT_DRAINING_SECONDS=30` on the
+   service.
+5. **A periodic tick closes the gap between boots.** Serving workers run a tick
+   every `INSIKA_TICK_INTERVAL` (default **60s**, `0` disables) as a child of
+   the turn supervisor: it re-drives any outbox record left `:pending` (each
+   carries its own claim — every worker may drain), and sweeps orphaned tasks
+   **without waiting for a deploy** — which is what recovers the orphans of a
+   worker respawned mid-generation (item 3's hole). One worker per window
+   sweeps (a single transactional claim), and only `:queued`/`:running` tasks
+   untouched for `INSIKA_TICK_STALE_AFTER` (default **900s**) are candidates:
+   a live turn is bounded by `turn_timeout`, so anything older cannot be alive.
+   **If you raise `turn_timeout` past it, raise `INSIKA_TICK_STALE_AFTER` too** —
+   the threshold must exceed the largest `turn_timeout` of the deployment.
+   `:waiting`/`:paused` tasks are idle by nature and stay boot recovery's.
+
+`deploy/entrypoint.sh` sets `WEB_CONCURRENCY` next to a pointer to this section;
+this section is the single source of truth for what changing it means.
+
+## Environment variables
+
+| Env | Default | Effect |
+|-----|---------|--------|
+| `INSIKA_DB` | `/data/insika.db` (in the image) | durable SQLite path (**mount a volume!**) |
+| `PORT` | `9292` | HTTP bind port |
+| `WEB_CONCURRENCY` | `1` | number of Falcon worker processes — a contract input, see [The process model](#the-process-model) |
+| `INSIKA_BOOT_ID` | set by `deploy/entrypoint.sh` | boot generation id; the recovery **task sweep** runs once per id (process model, item 3). Unset = every boot sweeps (single-process default) |
+| `INSIKA_DRAIN_TIMEOUT` | `20` | seconds a stopping worker waits for in-flight turns before abandoning them to the next boot's recovery (process model, item 4). The entrypoint sizes Falcon's `--graceful-stop` from it; on Railway also set `RAILWAY_DEPLOYMENT_DRAINING_SECONDS` ≥ drain + 10 |
+| `INSIKA_TICK_INTERVAL` | `60` | seconds between tick passes — outbox drain + stale recovery sweep (process model, item 5). `0` disables |
+| `INSIKA_TICK_STALE_AFTER` | `900` | seconds a `:queued`/`:running` task must sit untouched before the tick sweeps it. Must exceed the largest `turn_timeout` of the deployment |
+| `OPENCLAW_GATEWAY_TOKEN` | falls back to `ADMIN_TOKEN` | Bearer for `/v1/responses` and `/v1/agents` (the API contract) |
+| `ADMIN_TOKEN` | `local-demo` | login token for `/studio` (**change in production**) |
+| `DEEPSEEK_API_KEY` | — | provider key. **Without it the engine still boots** (`/up` green), but turns fail until it is configured (env or Studio → LLM providers) — cloud resilience |
+| `DEEPSEEK_MODEL` | `deepseek-v4-flash` | model |
+| `CONSUMER_INTERNAL_URL` | — | base URL for data-tools calling back a consumer's internal API (see below) |
+| `INSIKA_EGRESS_HOSTS` | — | outbound host allowlist (SSRF guard) |
+| `INSIKA_EGRESS_ALLOW_HTTP` / `_ALLOW_PRIVATE` | off | for `http`/loopback callbacks only (**never in cloud**) |
+| `INSIKA_RELAY_TOKEN` | — | **mounts the relay channel** at `POST /channels/relay/events`, and is the Bearer it requires. Empty = the route does not exist (`404`). See [Channels](CHANNELS.md) |
+| `INSIKA_RELAY_DELIVER_URL` | — | your callback; the engine POSTs each reply there. Goes through the egress guard |
+| `INSIKA_RELAY_DELIVER_TOKEN` | — | Bearer the engine sends **to** your callback (optional) |
+| `INSIKA_WIDGET_ORIGINS` | — | exact-match origins allowed to embed the [web widget](CHANNELS.md#the-web-widget), comma-separated. No wildcards. **Half the switch**: with `INSIKA_WIDGET_AGENTS` unset, nothing is mounted (`404`) |
+| `INSIKA_WIDGET_AGENTS` | — | agent ids a widget visitor may address, comma-separated. The other half of the switch. **A chat rate limit is also required** or the widget answers `503` |
+| `LITESTREAM_REPLICA_URL` | — | **enables Litestream** (backup/DR). Empty = disabled (default). See below |
+| `LITESTREAM_ENDPOINT` | — | S3-compatible endpoint (R2/MinIO). Empty = AWS S3 |
+| `LITESTREAM_REGION` | — | bucket region (AWS: `us-east-1`; R2: `auto`) |
+| `LITESTREAM_ACCESS_KEY_ID` / `LITESTREAM_SECRET_ACCESS_KEY` | — | bucket credentials (read natively by Litestream) |
+
+> **Renamed from `HARNESS_*` → `INSIKA_*`.** Every engine variable now uses the
+> `INSIKA_` prefix. The old `HARNESS_*` names are still honored as deprecated aliases
+> — set either one and the engine reads it, logging a one-line deprecation notice at
+> boot (`insika doctor` reports it too). Migrate at your convenience; the legacy names
+> will be dropped in a future release.
+
+> **The database filename changed too** — the image now defaults to
+> `INSIKA_DB=/data/insika.db` (it was `/data/harness.db`). **Existing volumes are
+> adopted automatically:** the container entrypoint renames the old file — with its
+> `-wal`/`-shm` siblings, before anything opens it — when the configured path does
+> not exist yet. Nothing to run by hand, no data lost, and a no-op from the second
+> boot on. To keep the old filename instead, point `INSIKA_DB` at it: the variable
+> is the knob, the image only picks a default. (The adoption lives in
+> `deploy/entrypoint.sh`, not in the engine — it is deploy baggage, not a runtime
+> behavior.)
+
+### Tokens & rotation (keep the two separate!)
+
+There are **two** secrets with distinct purposes — in production use **different**
+values (the API token falling back to `ADMIN_TOKEN` is a dev convenience only):
+
+- **`ADMIN_TOKEN`** — the `/studio` login (cookie auth). This is the **operator**
+  surface (just you). Rotating it is **safe and independent**: change it, redeploy,
+  log in with the new value. It does not affect any API consumer.
+- **`OPENCLAW_GATEWAY_TOKEN`** — the Bearer for `/v1/responses` and `/v1/agents`.
+  This is the **contract with your API consumers**. Rotating it means **changing
+  both sides together** (or the integration breaks): update the runtime var **and**
+  each consumer's token in the same step.
+
+Generate a strong token: `ruby -rsecurerandom -e 'puts SecureRandom.hex(24)'`.
+
+### Strict config and `insika doctor`
+
+Config discipline that **rejects unknown keys — no silent schema tolerance**. Two
+parts:
+
+**1. Boot gate.** On boot, the engine validates the environment against a schema of
+known keys (`Insika::EnvSchema`): a wrong type (`INSIKA_PORT=abc`) or an
+**unknown key in the `INSIKA_` namespace** (a typo like `INSIKA_EGRES_ALLOW_HTTP`
+the runtime would silently ignore). By **default it only warns** and boots anyway
+(*last-known-good* — a rotated key or a typo never takes the whole service down).
+To **refuse boot** on any finding, set `INSIKA_CONFIG_STRICT=1`. Unknown-key
+detection is scoped to the `INSIKA_` prefix; the shared `OPENCLAW_`, `LITESTREAM_`,
+and `OTEL_` namespaces are never flagged.
+
+**2. `bin/insika doctor` — on-demand diagnostics.** Reads the **same** durable
+backend the server uses (`INSIKA_DB`) without booting the whole app (no provider,
+no seed) — safe to run against a production volume:
+
+```bash
+insika doctor            # colored report; exits != 0 on any error
+insika doctor --json     # machine-readable (CI / monitoring)
+insika doctor --fix      # applies the safe autofixes and re-diagnoses
+insika env               # lists known keys + current values (secrets masked)
+```
+
+Checks: env (the schema above), settings schema version (a pending migration →
+`--fix` applies it), a missing platform `default_model` (`--fix` seeds it from
+`DEEPSEEK_MODEL`), durable vs ephemeral backend, LLM provider configured,
+`ADMIN_TOKEN` set, data-tool definitions still valid, **prompt files that hold
+text rather than a serialized object** (a file whose content is a stringified Hash
+serves a mangled prompt on every turn while looking perfectly healthy — present,
+non-empty, and the agent still answers), and **skill drift** — a shared skill whose
+body names one store, a prompt file routing to a skill the agent cannot load, a broken
+companion pair, a stale `eager:` key (see
+[Skills](SKILLS.md#drift-guards)). Settings-schema migrations are **explicit**
+— no Studio save silently reinterprets old-shape data.
+
+### Data-tool callbacks to a backend — via a tunnel
+
+Data-tools call back a consumer's internal HTTP API. With the engine **in the
+cloud** and your backend **on your machine** (`:3000`), expose it over a public
+`https` tunnel and point the engine at it:
+
+```bash
+# in the tool/manifest: base_url = {{env.CONSUMER_INTERNAL_URL}}
+CONSUMER_INTERNAL_URL=https://your-tunnel.example.dev
+INSIKA_EGRESS_HOSTS=your-tunnel.example.dev
+```
+
+Because the tunnel is **public `https`**, the strict egress guard (the default)
+**already allows it** — you do **not** need `ALLOW_HTTP`/`ALLOW_PRIVATE` (those are
+only for a fully-local loop). Restricting `INSIKA_EGRESS_HOSTS` to the tunnel host
+is the secure posture. See [Security](SECURITY.md#egress-the-ssrf-boundary).
+
+## Railway
+
+`railway.json` already configures the Dockerfile builder, `startCommand`, the `/up`
+healthcheck, and a restart policy.
+
+1. Create the project/service from this repo (builder = Dockerfile).
+2. **Volume**: mount it at `/data` (the default `INSIKA_DB` points there) —
+   without a volume, SQLite is ephemeral and recovery resumes nothing after a
+   redeploy.
+3. **Vars**: `DEEPSEEK_API_KEY`, `OPENCLAW_GATEWAY_TOKEN`, `CONSUMER_INTERNAL_URL`,
+   `INSIKA_EGRESS_HOSTS` (and `WEB_CONCURRENCY` to match your plan/CPU).
+4. The healthcheck hits `/up`.
+5. Point your consumer at the service's public URL, with a matching API token
+   (see [RUNNING-LOCAL.md](RUNNING-LOCAL.md)).
+
+## Backup / DR — Litestream (opt-in, configurable)
+
+A single volume is the **one point of total loss** between a pilot and production
+(disk corruption/loss = goodbye conversations + config). Litestream does
+**continuous replication** of `insika.db` (its WAL) to an S3/R2 bucket, without
+changing databases and **without a line of Ruby**.
+
+It is **off by default** and turns on by env — a single-box ephemeral deploy pays
+nothing; a durable deploy enables it by pointing at a bucket. The trigger is one
+variable, `LITESTREAM_REPLICA_URL`:
+
+- **empty (default):** the entrypoint `exec`s Falcon directly. The Litestream binary
+  is never invoked — behavior identical to not having it.
+- **set:** on a fresh box the entrypoint **restores** `insika.db` from the replica
+  *before* the app opens it (`litestream restore -if-replica-exists`; a no-op if the
+  bucket is still empty), then **supervises** the app (`litestream replicate -exec`),
+  replicating the WAL continuously and doing a final sync on shutdown (Railway's
+  SIGTERM).
+
+### Enable in production (Railway)
+
+Add the vars (keep the volume at `/data`):
+
+```bash
+# AWS S3
+LITESTREAM_REPLICA_URL=s3://my-bucket/insika
+LITESTREAM_REGION=us-east-1
+LITESTREAM_ACCESS_KEY_ID=AKIA...
+LITESTREAM_SECRET_ACCESS_KEY=...
+
+# Cloudflare R2 (S3-compatible): same, + endpoint and region=auto
+LITESTREAM_REPLICA_URL=s3://my-bucket/insika
+LITESTREAM_ENDPOINT=https://<accountid>.r2.cloudflarestorage.com
+LITESTREAM_REGION=auto
+LITESTREAM_ACCESS_KEY_ID=...
+LITESTREAM_SECRET_ACCESS_KEY=...
+```
+
+Credentials are read natively by Litestream (they are not in `deploy/litestream.yml`,
+which only references URL/endpoint/region via `${VAR}`).
+
+### Restore drill (the real "done" — an untested backup does not count)
+
+The pilot→production gap only closes once a restore has been **exercised**. Two ways:
+
+**1. Local, automated (proves the mechanism, zero credentials):** uses the real
+image + a `file://` replica; boots → replicates → deletes the volume → boots a new
+box → restores → confirms the marker row survived and `/up` is green.
+
+```bash
+scripts/litestream-restore-drill.sh      # needs docker, sqlite3, curl
+# → [drill] PASS — marker … restored from replica; /up green on the new box.
+```
+
+**2. Production (the drill that counts for go-live):** against the real bucket.
+
+```bash
+# a. with the service live and replicating, generate some config/conversation and
+#    confirm the replica has generations:
+litestream snapshots -config deploy/litestream.yml "$INSIKA_DB"
+
+# b. boot a NEW box (empty volume) with the same LITESTREAM_* vars → the entrypoint
+#    restores on boot. Verify manually in /studio that conversations and config came
+#    back. Manual restore alternative:
+litestream restore -config deploy/litestream.yml -o /tmp/restored.db "$INSIKA_DB"
+```
+
+## Kubernetes (evolution)
+
+SQLite does not share one file across nodes. Paths forward: a StatefulSet + a PVC
+per pod + **sticky-by-agent** routing (shard by tenant), or **LiteFS**, or an
+optional **Postgres** adapter. **Litestream** (above) for backup/DR from day one —
+orthogonal to topology.
+
+---
+
+## Measuring performance / load
+
+### 1. SQLite write ceiling (no provider) — `bench_store.rb`
+
+Isolates "can SQLite take multi-process writes?" from LLM noise: N processes
+hammering writes on the **same** file (WAL + busy_timeout — the real config).
+
+```bash
+bundle exec ruby scripts/bench_store.rb 1,2,4,8 3000
+```
+
+**Measured (mid-2026, laptop, ~481B payload):**
+
+| procs | writes/s (aggregate) | p50 | p95 | max | locked |
+|------:|--------------------:|----:|----:|----:|-------:|
+| 1 | ~29.6k | 0.02ms | 0.04ms | 2.4ms | **0** |
+| 2 | ~29.9k | 0.02ms | 0.04ms | 59ms | **0** |
+| 4 | ~23.7k | 0.02ms | 0.05ms | 336ms | **0** |
+| 8 | ~28.4k | 0.03ms | 0.05ms | 539ms | **0** |
+
+**Reading:** aggregate throughput stays ~25–30k writes/s regardless of process
+count (the WAL's one-writer-at-a-time ceiling), with **zero "database is locked"**
+(the `busy_timeout` absorbs contention into tail latency, not errors), and a
+microscopic p95. A real turn is **provider-bound (seconds)** and does a handful of
+writes → the workload sits ~100× under the ceiling. **Empirically, SQLite is not
+the bottleneck on a single box.**
+
+### 2. End-to-end load (with provider) — `loadtest.rb`
+
+Hits `POST /v1/responses` (SSE), the production path. Measures TTFB, total, tokens,
+cache hits, P50/P95, error rate. Runs against local or a remote deployment. See
+[LOADTEST.md](LOADTEST.md).
+
+```bash
+INSIKA_URL=http://localhost:9292 OPENCLAW_GATEWAY_TOKEN=xxx \
+  bundle exec ruby scripts/loadtest.rb --agents assistant --concurrency 16 --iterations 3
+```
+
+### 3. Baseline vs multi-worker on one box — `loadtest-local.sh`
+
+Boots Falcon with 1 worker, then N, over the **same** SQLite, and counts "database
+is locked" in the logs.
+
+```bash
+DEEPSEEK_API_KEY=sk-... ./scripts/loadtest-local.sh 4 24
+```
+
+## See also
+
+- [RUNNING-LOCAL.md](RUNNING-LOCAL.md) — run the engine locally, single-process.
+- [Security](SECURITY.md) — tokens, egress, strict config.
+- [BENCHMARK.md](BENCHMARK.md) — the neutral, key-free engine benchmark.
+- [OBSERVABILITY.md](OBSERVABILITY.md) — OpenTelemetry traces + metrics (opt-in).

data/docs/EMBEDDING.md

@@ -0,0 +1,198 @@
+---
+title: Embedding
+parent: Ship it
+nav_order: 4
+permalink: /embedding/
+---
+
+# Embedding
+
+Insika does not have to be a service you stand up next to your app. It can be an
+object inside the app you already have: a graph you build in an initializer and a
+Rack app you mount in your router. This page is the contract for doing that —
+what an embedded graph owns, what it still shares with the process, and what that
+makes your responsibility.
+
+---
+
+## The short version
+
+```ruby
+# config/initializers/insika.rb
+INSIKA = Insika.embed(backend: Insika::Stores::SQLite.new(path: Rails.root.join("storage/insika.sqlite3").to_s)) do
+  agent "support" do
+    model "deepseek-v4-flash"
+    provider :deepseek
+    api_key ENV.fetch("DEEPSEEK_API_KEY")
+    instructions "You answer questions about orders. Be brief."
+  end
+end
+
+# turns are born as children of a long-lived supervisor, not of the request
+INSIKA.runtime.graph.executor.supervised = true
+```
+
+```ruby
+# config/routes.rb — the transport is lazy: `require "insika"` never loads it
+require "insika/server/rack_app"
+
+mount Insika::Server.rack_app(INSIKA, token: ENV.fetch("INSIKA_TOKEN")), at: "/ai"
+```
+
+```ruby
+# anywhere in your app — no HTTP involved
+INSIKA.reply("support", "where is order 8123?", session: current_user.id)
+```
+
+`Insika.embed` takes the same block as [`Insika.system`](AGENTS.md) and adds one
+obligation: **you name the store**. That single argument is what turns "one
+program" into "one object" — see [why](#why-the-store-is-an-argument) below.
+
+`Insika::Server.rack_app` returns a plain Rack app. It routes on `PATH_INFO`, so
+Rails' `mount` (and `Rack::URLMap`, and anything else that moves the prefix into
+`SCRIPT_NAME`) leaves every route intact: mounted at `/ai`, the drop-in API is at
+`/ai/v1/responses`.
+
+---
+
+## Why the store is an argument
+
+The engine was not always one process — it was one *program*. Two graphs
+built in the same Ruby process shared things they never declared:
+
+| What | What actually happened |
+|---|---|
+| LLM credentials | one process-wide slot **per provider**: two graphs on `deepseek` with different keys, and the second one won **for both**. No error, no warning — agent A simply called the provider with tenant B's key. |
+| The store | `INSIKA_DB` unset → each graph got its own in-memory store and nothing persisted; `INSIKA_DB` set → every graph opened the **same file** and read the others' agents, sessions and tasks. |
+
+Neither failure raised. That is the whole reason the embed contract is written
+down rather than left to good sense.
+
+---
+
+## The contract
+
+### 1. A graph owns its store
+
+Every durable thing — sessions, tasks, checkpoints, the outbox, delegations,
+memory — belongs to the backend the graph was built with. Two graphs given the
+**same** backend share all of it, by your choice. Two graphs given **different**
+backends share nothing.
+
+```ruby
+support = Insika.embed(backend: Insika::Stores::SQLite.new(path: "storage/support.sqlite3")) { … }
+ops     = Insika.embed(backend: Insika::Stores::SQLite.new(path: "storage/ops.sqlite3"))     { … }
+# a session created in `support` does not exist in `ops`
+```
+
+### 2. A graph owns its LLM credentials
+
+Provider keys and bases resolve through the graph's own
+[`RubyLLM.context`](https://rubyllm.com) — an isolated dup of the configuration.
+An embedded graph never mutates the global `RubyLLM.config`, and never reads
+another graph's credentials. That holds for the turn itself *and* for everything
+else in the graph that asks a model: the content-safety moderator and the output
+validator ask on the same context the turn does.
+
+It also holds for runtime reconfiguration. Editing a provider key in the Studio
+(or dispatching `:upsert_llm_provider`) applies to **that graph only** — the
+change is real, takes effect without a restart, and stops at the graph boundary.
+
+### 3. The process still owns signals and the reactor
+
+Draining in-flight turns on SIGTERM ([the process model](DEPLOY.md)) is a process
+concern, not a graph concern: `Signal.trap` keeps only the last handler, so a
+shutdown installed once per graph would drain the last graph and let the others
+die mid-turn. An embedded graph therefore installs **nothing** behind your back.
+You install it once, naming every graph:
+
+```ruby
+Insika::Shutdown.install(executors: [SUPPORT, OPS].map { |g| g.runtime.graph.executor })
+```
+
+One signal closes every graph's intake first, then waits — up to
+`INSIKA_DRAIN_TIMEOUT` (default 20s) — for the in-flight turns of all of them.
+Whatever outlives the deadline stays `:running` and is replayed by the next
+boot's recovery sweep.
+
+The reactor is yours too, and this one has teeth:
+
+> **The mounted app needs an async server.** `rack_app` is a value — nothing in it
+> starts a server or a reactor. A turn is a fiber, so the routes that start one
+> (`POST /v1/responses`, `/v1/messages`, `/v1/commands`, `POST /channels/:id/events`)
+> must be called from inside a running reactor. Under **Falcon** you already are.
+> Under Puma or Unicorn they answer `500 {"error":{"message":"No async task
+> available!"}}` — the read-only routes (`GET /v1/agents/:id`, `/v1/tasks/:id`, `/up`)
+> are fine either way. Serve an embedded Insika from Falcon, or reach the graph
+> in-process with `INSIKA.reply(...)`, which builds its own reactor.
+
+And once you are inside one, set `supervised = true` (as in the quickstart): it
+makes a turn a child of a long-lived supervisor instead of a child of the
+request, so the turn survives a client disconnect. Without it the runtime cancels
+the turn when the connection drops.
+
+### 4. The Studio is not part of the embeddable surface
+
+`rack_app` returns the `/v1` transport and nothing else. `Studio::App.configure`
+freezes its collaborators on the **class**, which makes it one operator UI per
+process: a second graph configuring the Studio replaces the first's wiring, for
+both. So a host that wants the UI does a plain `require "insika/studio/app"`,
+calls `Studio::App.configure` with exactly one graph's collaborators, and mounts
+the class — accepting that the UI shows that graph and no other.
+
+This is a stated limitation, not an oversight. Making the Studio instantiable is
+its own change, and it needs its own reason.
+
+### 5. ENV is a default, never a requirement
+
+Anything an embedded graph reads from the environment has an injectable
+equivalent, and the injected value wins. `INSIKA_DB` still works — it is the
+default for the DSL quickstart and for `config.ru` — but an embedded graph that
+was given a backend never looks at it.
+
+---
+
+## What you are responsible for
+
+| Concern | Who |
+|---|---|
+| Which store each graph gets | You, via `backend:` |
+| Which credentials each graph gets | You, via the agent's `api_key`/`provider` |
+| Who may call the mounted app | You. `token:` is one shared Bearer for the whole mount — see below |
+| Signals and the drain | You, once per process (`Shutdown.install(executors:)`) |
+| The reactor / `supervised` | You, matching your server |
+| Recovery of orphaned turns at boot | You, if you want it — the sweep is `Insika::Recovery`, wired by `Insika::Server::Boot` for the standalone deployment, not by `embed` |
+
+### Embedding is not the multi-tenant server
+
+Two graphs stop corrupting each other. That is all this contract says. **Who is
+allowed to talk to which graph** is authorization, and it is not here: `token:` is
+a single Bearer gating the whole mounted app, exactly as it does for the
+standalone server in the default mode. Multi-tenancy is a property of the
+*standalone* server, not of an embed: with `INSIKA_TENANCY=multi_tenant` the
+Bearer resolves to a principal before the routes — per-tenant tokens scoped to
+their own sessions, tasks and events, operator tokens with the run of the
+deployment (see [Security](SECURITY.md#the-bearer-gate)). An embedded graph keeps
+no token store, so an embed's tenancy belongs to the host: put the mounted app
+behind your own authentication and pass `session:` yourself — do not hand the
+mount point to the browser.
+
+---
+
+## What this is not
+
+- **Not a Rails engine.** `insika-rails` would be a separate gem; this is the Rack
+  app such a gem would mount. The core has no Rails knowledge and takes no Rails
+  dependency.
+- **Not a second assembly path.** `Insika.embed` is a front door over the same
+  pipeline `Insika.agent`/`Insika.system` use — the profile it produces is
+  identical, and there is a spec that holds it to that.
+
+---
+
+## See also
+
+- [Architecture](ARCHITECTURE.md) — how a turn actually runs.
+- [Deploy](DEPLOY.md) — the standalone process model (N workers of *one*
+  deployment), which is a different question from N graphs in one process.
+- [Agents](AGENTS.md) — the DSL block `embed` takes.