insika 0.3.0 → 0.8.0

data/docs/index.md

@@ -8,7 +8,7 @@ permalink: /
 {: .fs-9 }
 
 Your agent is the idea. Insika is what holds it up in production.
-{: .fs-6 .fw-300 }
+{: .hero-tagline }
 
 [Build your first agent](RUNNING-LOCAL.md){: .btn .btn-primary .fs-5 .mb-4 .mb-md-0 .mr-2 }
 [View on GitHub](https://github.com/guizaols/insika){: .btn .fs-5 .mb-4 .mb-md-0 }
@@ -60,9 +60,12 @@ secrets), `GET /docs` and `GET /docs/<name>.md`. Public and on by default when y
 
 ## Where to go next
 
-- **[Understand the idea](understand.md)** — why a runtime rather than a DIY loop, and how a turn actually runs.
-- **[Build an agent](build.md)** — agents, tools, skills, context, and the local loop.
-- **[Ship it](ship.md)** — security, confined execution, deployment.
-- **[Operate & prove it](operate.md)** — observability, the benchmark, load testing, evals, refinement.
+- **[Start here](start-here.md)** — why a runtime, getting one running, and what a turn actually does.
+- **[Core concepts](core-concepts.md)** — agents, limits, tools, skills, context, workflows.
+- **[Integrate](integrate.md)** — the API, channels, media, embedding, plugins, templates.
+- **[Ship it](ship.md)** — security, confined execution, deployment, scaling past one worker.
+- **[Operate](operate.md)** — observability, schedules, artifacts, load and soak testing.
+- **[Improve](improve.md)** — evals, refinement, outcomes, and the three learning loops.
+{: .card-grid }
 
 Pre-release: APIs may still change and nothing is tagged yet. Licensed MIT.

data/docs/integrate.md

@@ -0,0 +1,20 @@
+---
+title: Integrate
+nav_order: 4
+has_children: true
+permalink: /integrate/
+---
+
+# Integrate
+
+How the agent connects to everything that is not the engine: the clients that
+call it, the places people talk to it from, the app it may live inside, and the
+code you write to extend it.
+
+- **[The /v1 API](API.md)** — the frozen, OpenAI-Responses-compatible contract.
+- **[Channels](CHANNELS.md)** — the web widget and the relay: how people actually reach the agent.
+- **[Media](MEDIA.md)** — photos, voice notes and documents in; generated images out.
+- **[Embedding](EMBEDDING.md)** — mounting the engine inside a Ruby app you already have.
+- **[Plugins](PLUGINS.md)** — the two extension tiers, and how to pick between them.
+- **[Templates](TEMPLATES.md)** — the example agents that ship in the gem, and the gallery that installs them.
+{: .card-grid }

data/docs/operate.md

@@ -1,12 +1,19 @@
 ---
-title: Operate & prove it
-nav_order: 5
+title: Operate
+nav_order: 6
 has_children: true
 permalink: /operate/
 ---
 
-# Operate & prove it
+# Operate
 
-Turns as traces and metrics, the engine's measured overhead, how to load-test it
-yourself, the cases that grade an agent, and reading a live agent's own traffic back as
-a report of what broke.
+Running it once it is live: seeing what happened, firing turns nobody sent,
+handing back a report, and knowing what the box will take before it takes it.
+
+- **[Observability](OBSERVABILITY.md)** — the event stream, and turns as OpenTelemetry traces and metrics.
+- **[Schedules](SCHEDULING.md)** — recurring turns the engine fires on its own tick.
+- **[Artifacts](ARTIFACTS.md)** — a report the agent can hand you a URL to.
+- **[Load test](LOADTEST.md)** — end-to-end load testing, and comparing topologies before you choose one.
+- **[Soak](SOAK.md)** — the long run that finds what a short one cannot.
+- **[Benchmark](BENCHMARK.md)** — the engine's measured overhead, reproducible without an API key.
+{: .card-grid }

data/docs/prompts/ADD-TOOL.md

@@ -0,0 +1,118 @@
+---
+title: Prompt — add a tool or skill
+parent: Reference
+nav_order: 3
+permalink: /add-tool/
+layout: default
+render_with_liquid: false
+---
+
+# Add a tool, MCP server, or skill to my agent
+
+> **You are a coding agent** (Claude Code, Codex, Cursor, …) reading this because a
+> developer pasted a prompt pointing here. Treat this file as a **skill**: follow the
+> steps in order and apply the RULES literally.
+
+Your job: extend **one existing agent** with **one new capability** and prove it works
+with one turn. Nothing more.
+
+## Step 0 — Gather context (silently)
+
+- **Which agent?** Find its `Insika.agent { … }` block (or its pack). If the developer
+  has no agent yet, stop and build the minimal first agent instead — this file assumes
+  one exists. Do not mix onboarding with capability.
+- **A provider key in the environment**; ask if none is set.
+- Read [`docs/TOOLS.md`](../TOOLS.md) (also served at `GET /docs/tools.md`) and, for
+  skills, [`docs/SKILLS.md`](../SKILLS.md) before writing anything.
+
+## Step 1 — Pick the kind (RULES, not taste)
+
+| The need | The kind | Where it lives |
+|---|---|---|
+| Call an external HTTP API | **data tool** (`data_tool` in the DSL block) | a row in SQLite, editable at runtime |
+| Logic must run in-process | **code tool** (a Ruby class `< RubyLLM::Tool`) | the deployment image |
+| Adopt a whole external MCP server | **`mcp` instance** | durable config; its tools appear tagged `mcp:<name>` |
+| Teach a procedure (no data fetching) | **skill** (`skill "name", description:, instructions:`) | loads on demand via `load_skill` |
+
+Exactly one kind. A skill is not a tool; an MCP server is not five data tools.
+
+## Step 2 — Build the smallest version
+
+Data tool, via DSL (shape from
+[`examples/data-tool/`](https://github.com/guizaols/insika/tree/main/examples/data-tool/)):
+
+```ruby
+data_tool(
+  "name"        => "convert_currency",
+  "description" => "Latest reference exchange rate between two currencies.",
+  "parameters"  => {
+    "type" => "object",
+    "properties" => {
+      "from" => { "type" => "string", "description" => "source currency code" },
+      "to"   => { "type" => "string", "description" => "target currency code" }
+    },
+    "required" => %w[from to]
+  },
+  "request"  => { "method" => "GET",
+                  "url"    => "https://api.example.com/latest?from={{from}}&to={{to}}" },
+  "response" => { "extract" => "body_raw" }
+)
+```
+
+Skill, via DSL (from
+[`examples/skills/`](https://github.com/guizaols/insika/tree/main/examples/skills/)):
+
+```ruby
+skill "refunds",
+      description: "How to handle a refund request",
+      instructions: <<~MD
+        When a customer asks for a refund:
+        1. If you don't have the order number, ask for it first.
+        …
+      MD
+```
+
+RULES:
+
+- `parameters` is JSON Schema (safe subset — no `oneOf`/`$ref`); it reaches the model
+  verbatim and arguments are checked against it at call time.
+- Author the FINAL url: the HTTP client does not follow redirects, and the egress guard
+  cleared that host only.
+- Do not add a second capability "while we're here".
+
+## Step 3 — Make sure it enters the tool-loop
+
+Registered is not enough — the agent's policy allowlist decides. The DSL auto-enables
+the allowlist policy, and the three-state rule applies (`nil` = all, `[]` = none,
+`[names]` = exactly those; deny wins):
+
+```ruby
+tools %w[convert_currency]   # or tools_allow: [...] on the pack
+```
+
+A code tool can never be shadowed by a data tool of the same name — pick another name
+instead of fighting it.
+
+## Step 4 — Prove it with ONE turn
+
+Run one `reply()` whose message forces the call ("how many BRL is 1 USD right now?").
+The reply must use what the tool returned — if the model answers from imagination, the
+tool did not run: re-check Step 3 before touching the prompt.
+
+## Step 5 — Self-check
+
+- [ ] One agent, one new capability, one proving turn with real output.
+- [ ] The tool/skill is named in the allowlist (or absence was a deliberate "all").
+- [ ] No secret in any file — keys live in the environment.
+- [ ] No new gem dependency was added without asking.
+
+## Hard constraints
+
+- **Secrets stay in the environment.** `{{secret.*}}` resolves ONLY on the manifest
+  write path (`POST /v1/tools/manifest`); written via DSL or Studio it fails
+  registration. Tools authored outside a manifest ship literal values (masked on read).
+- **The egress guard refusing a URL is a feature**, not a bug to disable globally.
+  Report it; open an allowlist exception deliberately.
+- **Config over code**: everything above is data the DSL generates (`to_pack`). If it
+  seems to require reaching past the DSL, the answer is a DSL method you have not used
+  yet — re-read the docs first.

data/docs/prompts/DIAGNOSE-TURN.md

@@ -0,0 +1,65 @@
+---
+title: Prompt — diagnose a failed turn
+parent: Reference
+nav_order: 4
+permalink: /diagnose-turn/
+layout: default
+render_with_liquid: false
+---
+
+# Diagnose a turn that failed or misbehaved
+
+> **You are a coding agent** (Claude Code, Codex, Cursor, …) reading this because a
+> developer pasted a prompt pointing here — something like *"the agent didn't answer /
+> answered wrong / errored"*. Treat this file as a **skill**: investigate BEFORE
+> proposing fixes, and report findings in plain language with evidence.
+
+The engine already recorded what happened: every turn emits structured events stamped
+with `task_id`/`session_id`. Your job is to read the record, not to guess.
+
+## Step 0 — Pin down the facts
+
+Ask for (or find) the minimum: **agent id**, **session id** (or the customer's message
+text), roughly **when**, and expected vs. actual. Reproduce once locally if cheap
+(`reply()` or one `curl` against a dev instance) — never hammer production.
+
+## Step 1 — Read the record, in this order
+
+1. **`GET /v1/tasks/:id`** (or the Studio) — the terminal state:
+   `completed` / `failed` / `cancelled`, outcome, usage, timing. No task id? Find it
+   via **`GET /v1/events?session_id=…`**.
+2. **That task's events**: `task_started` → `tool_call`/`tool_result`/`data_tool_call`
+   … → the terminal event. A failure's reason lives there.
+3. **`GET /v1/sessions/:id`** — the transcript: what the model actually saw and said.
+4. **`bin/insika doctor`** — configuration sanity; relay its findings verbatim.
+
+## Step 2 — Map symptom to mechanism
+
+| On the record | Usual suspect | Details |
+|---|---|---|
+| provider auth/model error | missing key or wrong model id | fails at the provider, not the engine |
+| `provider_failure` then `provider_fallback` | reliability chain rotated mid-turn | [Agents](../AGENTS.md) § reliability |
+| `breaker_open` + fail-fast turns | circuit open until cooldown | same |
+| turn completed, customer got nothing | delivery is separate from the turn: check `channel_delivered` / `delivery_failed` | [Channels](../CHANNELS.md) |
+| freshly created agent returns empty turns | persona overflows the default `context_budget` (8000) | [Context](../CONTEXT.md) |
+| tool never called (or "missing") | not registered OR not allowed (`tools_allow`) | [Tools](../TOOLS.md) § troubleshooting |
+| identical `tool_call` repeated, then abort | the `max_tool_repeat` loop guard | [Agents](../AGENTS.md) § limits |
+| model gave up after one empty result | `tool_persistence` off (it is ON by default) | same |
+| `turn_stuck` event | the agent declared it cannot proceed — escalation signal, not a bug | [Agents](../AGENTS.md) § stuck |
+
+## Step 3 — Report, then fix ONE thing
+
+- Plain-language summary: **what happened → evidence (event names + ids) → root cause
+  → the fix you propose.**
+- Apply the fix; re-run the Step 0 reproduction; show the new terminal event as proof.
+- If the evidence does not fit any row above, say so and bring the raw events back —
+  do not force a diagnosis.
+
+## Hard constraints
+
+- **Never invent event data.** If you did not read it, you cannot claim it.
+- **Do not change config just to silence the symptom** without explaining the
+  mechanism (raising `context_budget` because the prompt is big is a fix; deleting the
+  guardrail that fired is not).
+- **Quote ids, counts and states first; message content only when needed** for the
+  developer to recognize the case.

data/docs/prompts/GO-LIVE.md

@@ -0,0 +1,138 @@
+---
+title: Prompt — go live
+parent: Reference
+nav_order: 5
+permalink: /go-live/
+layout: default
+render_with_liquid: false
+---
+
+# Take this agent to production
+
+> **You are a coding agent** (Claude Code, Codex, Cursor, …) reading this because a
+> developer pasted a prompt pointing here — something like *"deploy this"* or *"take
+> it to production"*. Treat this file as a **skill**: follow the steps in order and
+> apply the RULES literally. Production is where shortcuts become incidents.
+
+Your job: get **one working local setup** running as **one production instance**,
+verified end to end. The authoritative reference is
+[`docs/DEPLOY.md`](../DEPLOY.md) (served at `GET /docs/deploy.md`); this file is the
+ordered path through it.
+
+## Step 0 — Gather context (silently)
+
+- **Repo or gem?** The reference deployment is a checkout of the insika repo
+  (`Dockerfile` + `config.ru` + `railway.json` already in it). An adopter's own app
+  consumes the gem instead — then the developer's repo needs its own image; the env
+  contract below is identical.
+- **Which platform?** Railway is the documented path. Any Docker host works; the
+  Kubernetes caveats are in [`docs/DEPLOY.md`](../DEPLOY.md) § Kubernetes.
+- **Does it work locally?** One green `reply()` or `serve` turn first. Do not debug an
+  agent and a deployment at the same time.
+- Read [`docs/DEPLOY.md`](../DEPLOY.md) and
+  [`docs/SECURITY.md`](../SECURITY.md) before writing anything.
+
+## Step 1 — Mint the two secrets (RULES, not taste)
+
+Two tokens, **two different values** — the fallback of one onto the other is a dev
+convenience only:
+
+| Token | Gates | Rotating it |
+|---|---|---|
+| `ADMIN_TOKEN` | `/studio` login (the operator — just you) | safe, independent |
+| `INSIKA_GATEWAY_TOKEN` | Bearer for `/v1/responses` + `/v1/agents` (your API consumers) | both sides together, same step |
+
+Generate each: `ruby -rsecurerandom -e 'puts SecureRandom.hex(24)'`. Set them as
+platform env vars. **Never** write either into a file, a commit, or your own output.
+
+## Step 2 — The non-negotiable env
+
+- **`INSIKA_DB` on a mounted volume** (the image defaults to `/data/insika.db` —
+  mount a volume at `/data`). No volume = SQLite is ephemeral and recovery resumes
+  nothing after a redeploy.
+- **`WEB_CONCURRENCY` stays `1`.** It is a contract input, not a throughput knob:
+  N>1 without session-sticky routing in front is a guaranteed cross-session reply
+  leak, and `insika doctor` errors on it on Railway. The fix, when throughput is
+  actually needed, is [`insika-router`](../ROUTER.md) in front — not a bigger number.
+- **Provider key** (`DEEPSEEK_API_KEY` for the demo provider) — without it the engine
+  still boots (`/up` green) but every turn fails until it is configured.
+- **`INSIKA_EGRESS_HOSTS`** = exactly the hosts your data-tools call. A backend on the
+  developer's machine gets a public **https tunnel** + its host in this list — never
+  `INSIKA_EGRESS_ALLOW_HTTP`/`_ALLOW_PRIVATE` in cloud.
+- On Railway also **`RAILWAY_DEPLOYMENT_DRAINING_SECONDS=30`**: the platform default
+  is 0 — SIGKILL right after SIGTERM — which cancels the graceful drain entirely.
+
+## Step 3 — Deploy
+
+Railway (repo path — `railway.json` already sets builder, start command, `/up`
+healthcheck, restart policy):
+
+1. Create the project/service from the repo (builder = Dockerfile).
+2. Mount the volume at `/data`.
+3. Set the vars from Steps 1–2.
+4. Deploy; the healthcheck must go green on `/up`.
+
+Any Docker host, same contract:
+
+```bash
+docker build -t insika .
+docker run -p 9292:9292 -v insika-data:/data \
+  -e DEEPSEEK_API_KEY=... -e ADMIN_TOKEN=... -e INSIKA_GATEWAY_TOKEN=... \
+  insika
+```
+
+## Step 4 — Prove it with ONE real turn
+
+In order, each with evidence:
+
+1. `curl https://<host>/up` → `{"status":"ok"}`.
+2. `bin/insika doctor` against the deployed volume (or via the platform's shell) —
+   relay its findings verbatim; fix errors before continuing.
+3. One authenticated turn:
+
+```bash
+curl -N https://<host>/v1/responses \
+  -H "Authorization: Bearer $INSIKA_GATEWAY_TOKEN" \
+  -H "Content-Type: application/json" \
+  -d '{"model":"<agent-id>","user":"go-live-check","input":"hello"}'
+```
+
+The reply must be real model output. 401 → token mismatch (Step 1); a provider error
+→ key/model id (Step 2); anything else → stop and diagnose with
+[`docs/prompts/DIAGNOSE-TURN.md`](DIAGNOSE-TURN.md) before touching config.
+
+4. Log in to `/studio` with the new `ADMIN_TOKEN` and find the go-live-check session.
+
+## Step 5 — Close the total-loss hole (Litestream)
+
+A single volume is the one point of total loss. Enable continuous replication by env
+(off by default, zero code): set `LITESTREAM_REPLICA_URL` + credentials per
+[`docs/DEPLOY.md`](../DEPLOY.md) § Backup / DR. Then **run the restore drill** — an
+untested backup does not count:
+
+```bash
+scripts/litestream-restore-drill.sh   # local proof of the mechanism, or the
+                                      # production drill in DEPLOY.md § Restore drill
+```
+
+If the developer declines Litestream, record that as an explicit accepted risk in
+your report — do not silently skip it.
+
+## Step 6 — Self-check
+
+- [ ] `/up` green, `doctor` clean, one real authenticated turn with model output.
+- [ ] Two distinct tokens, both only in platform env; nothing secret in git or logs.
+- [ ] Volume mounted; `WEB_CONCURRENCY=1`; drain buffer set (Railway).
+- [ ] Egress allowlist names only the hosts the tools actually call.
+- [ ] Litestream on **and** a restore exercised — or the risk explicitly accepted.
+
+## Hard constraints
+
+- **Never raise `WEB_CONCURRENCY` to "fix" throughput.** The failure it causes is a
+  reply delivered to the wrong customer — read
+  [`docs/DEPLOY.md`](../DEPLOY.md) § The process model before proposing any scaling.
+- **`_ALLOW_HTTP`/`_ALLOW_PRIVATE` never in cloud.** They exist for fully-local loops.
+- **The onboarding surface (`/start.md`, `/docs`) is opt-in in production**
+  (`INSIKA_ONBOARDING=1`) — leaving it off is the default posture, not a bug.
+- **Report every deviation.** A var you had to add, a check that failed and was
+  worked around, a step the platform made impossible — findings, not noise.

data/docs/prompts/RUN-EXAMPLES.md

@@ -0,0 +1,70 @@
+---
+title: Prompt — run every example
+parent: Reference
+nav_order: 2
+permalink: /run-examples/
+layout: default
+render_with_liquid: false
+---
+
+# Run every example
+
+> **You are a coding agent** (Claude Code, Codex, Cursor, …) reading this because a
+> developer pasted a prompt pointing here. Treat this file as a **skill**: follow the
+> steps in order and apply the RULES literally. Do not improvise beyond them.
+
+Your job: get every runnable example under `examples/` running — one at a time — and
+explain to the developer what each one demonstrates. The authoritative list (and the
+one-line capability per example) is
+[`examples/README.md`](https://github.com/guizaols/insika/tree/main/examples/README.md)
+(`examples/README.md` when the repo is checked out). Read it first.
+
+## Step 0 — Gather context (do this first, silently)
+
+RULES — verify, do not assume:
+
+- **Ruby ≥ 3.3.** Run `ruby -v`. If lower, stop and tell the developer; do not try to
+  upgrade Ruby for them.
+- **Insika must be loadable** — `require "insika"` (installed gem) or the checked-out
+  repo's bundle. Do not copy source files around to "fix" a missing install.
+- **A provider key comes from the environment** (`DEEPSEEK_API_KEY` for the demo).
+  None is set → **ask the developer**; never invent or hard-code one.
+- **Read each example's own `README.md` before running it.** Some need more than one
+  terminal or extra env vars; the README is the contract.
+
+## Step 1 — Run in this order, ONE at a time
+
+| # | Example | Command | Note |
+|---|---------|---------|------|
+| 1 | hello-agent | `ruby examples/hello-agent/hello.rb` | smallest agent; one turn |
+| 2 | data-tool | `ruby examples/data-tool/currency_agent.rb` | declarative HTTP tool + the egress guard |
+| 3 | skills | `ruby examples/skills/skill_agent.rb` | progressive skill loading |
+| 4 | memory | `ruby examples/memory/memory_agent.rb` | cross-session `remember` |
+| 5 | guardrails | `ruby examples/guardrails/guarded_agent.rb` | content-safety guardrails |
+| 6 | agentic-workflows | `ruby examples/agentic-workflows/sequential.rb` | then routing/parallel/delegation/evaluator |
+| 7 | scheduled-report | `ruby examples/scheduled-report/report_agent.rb` | runs one report turn inline; add `--serve` only if asked |
+| 8 | relay-channel | see its README | TWO processes + env vars; skip unless asked |
+
+For each one: read its README → run → quote what it printed → explain in ≤ 3 lines
+what capability it demonstrated.
+
+Skip unless the developer asks: `insika-code/` (a full deployment, not a one-file
+script), `quickstart.rb` (hello-agent already covers it), and anything in `examples/`
+the table above does not list.
+
+## Step 2 — When one fails
+
+- **Auth or model error** → stop that example, report the exact error, ask for a valid
+  key/model id. Never retry with a guessed id.
+- **A cause you can read from the output** (missing env var, port already bound…) →
+  say so and fix only with the developer's OK.
+- **Never edit an example to make it pass silently.** An example that needed a change
+  to run is a finding, not noise.
+
+## Step 3 — Self-check before you report done
+
+- [ ] Every example above either printed real model output or was reported blocked,
+      with the exact blocker.
+- [ ] No provider key written into any file; no invented model ids.
+- [ ] Each example got its ≤ 3-line "what this demonstrates".
+- [ ] Nothing was edited to make a failure disappear.

data/docs/reference.md

@@ -0,0 +1,19 @@
+---
+title: Reference
+nav_order: 8
+has_children: true
+permalink: /reference/
+---
+
+# Reference
+
+The removability map, plus the paste-prompts that hand a journey to a coding
+agent. A running instance serves each prompt at `GET /docs/<name>.md`, so you can
+point Claude Code, Codex or Cursor at the URL instead of pasting the text.
+
+- **[The domain-free core](domain.md)** — what ships in the gem, what a deployment declares, and how to clear it.
+- **[Prompt — run every example](prompts/RUN-EXAMPLES.md)** — run `examples/` one at a time and explain what each proves.
+- **[Prompt — add a tool or skill](prompts/ADD-TOOL.md)** — pick the right kind, wire the allowlist, prove it with one turn.
+- **[Prompt — diagnose a failed turn](prompts/DIAGNOSE-TURN.md)** — symptom to mechanism, then fix one thing.
+- **[Prompt — go live](prompts/GO-LIVE.md)** — tokens, volume, deploy, one authenticated turn, and the backup hole.
+{: .card-grid }

data/docs/ship.md

@@ -1,10 +1,18 @@
 ---
 title: Ship it
-nav_order: 4
+nav_order: 5
 has_children: true
 permalink: /ship/
 ---
 
 # Ship it
 
-What stands between your agent and the open internet, and how to put it on a server.
+What stands between your agent and the open internet, and how to put it on a
+server without losing a turn to a restart.
+
+- **[Security](SECURITY.md)** — guardrails, egress, approvals, secrets, and the privacy obligations that come with memory.
+- **[Sandbox](SANDBOX.md)** — confined execution for tool code you did not write.
+- **[Deploy](DEPLOY.md)** — the container, the durable volume, the process model, and the full environment table.
+- **[Router](ROUTER.md)** — the session-sticky proxy that lets you run more than one worker.
+- **[Releasing](RELEASING.md)** — how the gem is cut, and the install proof that runs before it is published.
+{: .card-grid }

data/docs/start-here.md

@@ -0,0 +1,18 @@
+---
+title: Start here
+nav_order: 2
+has_children: true
+permalink: /start-here/
+---
+
+# Start here
+
+Four pages, in order: what problem the runtime solves, how to get one running on
+your machine, what actually happens inside a turn, and how to fill an empty
+install with enough data to see every loop working.
+
+- **[Why Insika](WHY.md)** — a runtime instead of a hand-rolled loop, an assembled framework, or a hosted gateway.
+- **[Running locally](RUNNING-LOCAL.md)** — boot the engine, open the control UI, point a Responses client at it.
+- **[Architecture](ARCHITECTURE.md)** — the turn pipeline, the tool-loop, checkpoint recovery, the concurrency model.
+- **[Demo data](DEMO.md)** — seed a deployment so funnels, refinement and approvals have something to show.
+{: .card-grid }