insika 0.2.0 → 0.7.0

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 |
+| `OPENCLAW_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 OPENCLAW_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 $OPENCLAW_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 }

data/lib/insika/agent_profile.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "coercion"
+require_relative "tool_definition"
 
 module Insika
   # Single point of per-agent policy.
@@ -63,6 +64,14 @@ module Insika
     #                                   a context provider injecting volatile content into
     #                                   :system turns every turn into a paid cache WRITE with
     #                                   no read hit. Enable only for stable-system agents.
+    :tool_persistence,                # the engine's "Tool discipline" block in the system
+    #                                   prompt (retry weak/empty tool results with a different
+    #                                   approach before giving up). THE ONE OPT-OUT FIELD:
+    #                                   nil/true = ON (the proven default — every reference
+    #                                   harness ships it), false = OFF. Deliberately inverted
+    #                                   from the opt-in fields above: the exception here is
+    #                                   turning the good behavior OFF, so that is what an
+    #                                   operator declares. Read by Context::Providers::Prompt.
     :tool_output_compression,          # MECHANICAL tool-result dedupe in the replayed
     #                                   history (A3/C3): nil/false = OFF (parity); true = ON.
     #                                   Same opt-in as `memory`. When ON, the history the
@@ -103,6 +112,14 @@ module Insika
     #                                   breaker_open / delivery_failed events are POSTed to
     #                                   the URL as JSON (outbox + claim, at-most-once).
     #                                   nil/absent = no webhook (parity).
+    :routes,                          # intent routing (WS4): { "route" => "description" or a
+    #                                   Hash with description/delegate/stuck/message,
+    #                                   "default" => route, "model" => cheap classifier }.
+    #                                   When present, the message is classified BEFORE the
+    #                                   ask with the cheap model; the route lands on the
+    #                                   turn (state.route + :route_classified) and may
+    #                                   delegate to an existing agent or end the turn :stuck
+    #                                   (WS5). nil/absent = no routing (parity).
     :stuck_signal,                    # the agent may signal it cannot proceed (WS5):
     #                                   nil/false = OFF (parity — the signal_stuck system
     #                                   tool is not wired); true = ON (the model may call
@@ -111,6 +128,25 @@ module Insika
     #                                   event the consumer acts on). Same opt-in as
     #                                   `memory`. What "stuck" MEANS is the consumer's call
     #                                   (escalation via CRM/operator), never the engine's.
+    :stt_prompt,                     # STT vocabulary hint (WS9): domain words
+    #                                   (product names, brand terms) the transcriber should
+    #                                   expect on this agent's voice notes — passed straight
+    #                                   through to the Whisper-family provider's `prompt:`.
+    #                                   nil/absent = the deployment default (INSIKA_STT_PROMPT
+    #                                   env) or nothing. OPERATOR config, never customer input.
+    :outputs,                         # generated-media output policy (WS9, saída):
+    #                                   { "image" => { "model" => …, "size" => "1024x1024" },
+    #                                   "tts" => { "model" => "tts-1", "voice" => "alloy",
+    #                                   "format" => "mp3" } }. THE AGENT'S HALF of the
+    #                                   media-output gate — nil/absent = the agent never
+    #                                   generates media (opt-in like `capabilities`, do NOT
+    #                                   "fix" to nil = all). The other half is the CHANNEL'S:
+    #                                   the request must declare it can receive the media
+    #                                   (`channel.capabilities` — "image_output" /
+    #                                   "audio_output"); only with BOTH does the model see
+    #                                   the generate_image/tts tools (the abstraction admits
+    #                                   only what leaks). Generated media rides the turn's
+    #                                   `output_parts` in the envelope, never the answer text.
     :model_policy,                    # governance of WHICH models the agent may use:
     #                                   { "allow" => [refs] }. nil = NO fence (all models —
     #                                   parity). Enforced on the RESOLVED model (ModelResolver).
@@ -162,10 +198,102 @@ module Insika
     #                                   (WhatsApp) puts the deliberation in front of a
     #                                   customer; that is the operator's call to make, not a
     #                                   default to inherit.
-    :metadata                         # free-form agent metadata, stable per agent
-    #                                   (from the pack `agent.config.json`). Home of the `store_id`
-    #                                   that becomes turn context (ctx.store_id).
-    #                                   It is NOT a policy — never decides security. {} = absent.
+    :grounding,                     # the pack's grounding policy —
+    #                                   { "mode" => "flag"|"enforce"|"off",
+    #                                   "matcher" => { "sku" => …,
+    #                                   "name_keys" => [...] } }. OPT-IN:
+    #                                   nil/absent = OFF (parity, zero allocations).
+    #                                   Deep-stringified like the other hashes.
+    :metadata,                      # free-form agent metadata, stable per agent
+                                   # (from the pack `agent.config.json`). Home of the `store_id`
+                                   # that becomes turn context (ctx.store_id).
+                                   # It is NOT a policy — never decides security. {} = absent.
+    :briefing_fields,                # the per-session working-state schema this agent
+                                   # keeps and asks for: a flat [String] of
+                                   # field names the pack declares. []/nil/absent = the
+                                   # feature is OFF (no provider output, no tools — visibly
+                                   # removable). Names are engine-owned store keys
+                                   # and tool text, so they are validated against NAME_RE at
+                                   # build time. Data, never a policy: the engine owns the
+                                   # briefing object, the pack owns the fields.
+    :funnel,                         # the outcome funnel declaration — pack
+                                   # data, exactly like budget/reliability:
+                                   # { "stages" => ["greeted", "qualified", "cart", "paid"],
+                                   #   "advance_on" => { "pix_paid" => "paid", … },
+                                   #   "primary" => "paid", "attribution_window" => "72h" }.
+                                   # The ENGINE never hard-codes a stage name: the fold,
+                                   # the doctor and the Studio read this declaration (D1).
+                                   # nil/absent = no funnel (parity — nothing folds).
+                                   # Deep-stringified like the other free-form hashes;
+                                   # shape-validated by FunnelDeclaration, never here (D8).
+    :followup,                       # the follow-up declaration — pack data,
+                                   # exactly like budget/funnel:
+                                   # { "arm" => "schedule",
+                                   #   "policy" => { "quiet_hours" => { "timezone" => "…",
+                                   #       "start" => "21:30", "end" => "09:00" },
+                                   #     "max_frequency" => "2/24h",
+                                   #     "cancel_keywords" => ["não quero mais contato"],
+                                   #     "silence_after_sends" => 3 } }.
+                                   # The engine OWNS the firing, never a policy value (D1);
+                                   # shape-validated by FollowupPolicy, never here (D9).
+                                   # nil/absent = the feature is off (parity).
+                                   # Deep-stringified like the other free-form hashes.
+    :distill,                        # the session-distillation declaration — pack
+                                   # data, exactly like refinement/followup:
+                                   # { "enabled" => bool, "prompt" => "<pack-authored markdown
+                                   #   — what counts as a fact for this store>",
+                                   #   "model" => "<ref — absent = the platform utility_model>",
+                                   #   "idle_hours" => 6, "min_messages" => 3,
+                                   #   "max_proposals" => 10 }.
+                                   # The ENGINE assembles the scope from the session; the
+                                   # model only names facts (D1). nil/absent = the feature is
+                                   # off (parity, byte-identical engine). Shape-validated by
+                                   # the command/engine, never here (the refinement precedent).
+                                   # Deep-stringified like the other free-form hashes.
+    :harvest,                        # the gated-harvest declaration — pack data,
+                                     # exactly like refinement/distill:
+                                     # { "enabled" => bool,
+                                     #   "negative_list" => [ { "rule" => "…", "pattern" => "…",
+                                     #                          "note" => "…" } ],
+                                     #   "miner" => { "model" => "<ref — absent = the platform
+                                     #       utility_model>", "window" => { "last_sessions" => N },
+                                     #       "max_proposals" => N, "budget" => { "tokens" => N } },
+                                     #   "idle_hours" => 24, "min_messages" => 3 }.
+                                     # The ENGINE mines (reads sessions, asks the miner, filters
+                                     # through the negative list + grounding), never authors a
+                                     # rule (D4). nil/absent = the loop is off (parity).
+                                     # Shape-validated by the command/engine/doctor, never here.
+                                     # Deep-stringified like the other free-form hashes.
+    :knowledge,                       # the post-turn learning declaration — pack
+                                   # data, exactly like distill/harvest:
+                                   # { "extract" => true, "retrieve" => true,
+                                   #   "model" => "<ref — absent = the platform
+                                   #       utility_model>", "top_k" => 5,
+                                   #   "index" => "scan", "types" => ["fact", …] }.
+                                   # The ENGINE extracts concepts after the turn and
+                                   # stamps their provenance/confidence/sources;
+                                   # the model only names concepts (same D1
+                                   # discipline as distill). nil/absent = the
+                                   # loop is off (parity). Shape-validated by
+                                   # the extractor/doctor, never here.
+                                   # Deep-stringified like the other free-form hashes.
+    :schedules                       # the recurring-schedule declarations — pack
+                                     # data, exactly like followup/distill:
+                                     # [ { "id" => "daily_report",
+                                     #     "cron" | "every" => …,
+                                     #     "tz" => "America/Sao_Paulo",
+                                     #     "message" => "<the synthetic inbound>",
+                                     #     "session_mode" => "new"|"fixed",
+                                     #     "overrides" => { "turn_timeout" => N,
+                                     #                        "max_tool_calls" => N,
+                                     #                        "model" => … },
+                                     #     "enabled" => bool }, … ].
+                                     # The ENGINE owns the firing (the
+                                     # ScheduleEngine, the tick's duty); the
+                                     # store rows are declared-derived.
+                                     # Shape-validated by Insika::Schedule,
+                                     # never here. nil/empty = the feature is
+                                     # off for that agent (parity).
   )
 
   # Reopened class (not a Data.define block): a constant assigned inside
@@ -193,10 +321,12 @@ module Insika
                    skills_eager: nil, context_providers: nil, workflows_allow: nil,
                    policies: [], prompt_refs: [], limits: {}, approvals_required: nil,
                    capabilities: nil, subagents: nil, tools_deferred: nil, memory: nil,
-                   prompt_caching: nil, tool_output_compression: nil,
-                   params: {}, model_policy: nil, guardrails: nil, sandbox: nil,
-                   refinement: nil, capabilities_declared: nil, edge_stream: nil, metadata: {},
-                   budget: nil, reliability: nil, alerts: nil, stuck_signal: nil)
+                   prompt_caching: nil, tool_persistence: nil, tool_output_compression: nil,
+                    params: {}, model_policy: nil, guardrails: nil, sandbox: nil,
+                    refinement: nil, capabilities_declared: nil, edge_stream: nil, metadata: {},
+                     budget: nil, reliability: nil, alerts: nil, routes: nil, stuck_signal: nil,
+outputs: nil, stt_prompt: nil, briefing_fields: nil, grounding: nil, funnel: nil,
+                      followup: nil, distill: nil, harvest: nil, knowledge: nil, schedules: nil)
       new(
         id: id, model: model, provider: provider, base_prompt: base_prompt,
         prompt_files: Array(prompt_files), tools_allow: tools_allow,
@@ -210,7 +340,8 @@ module Insika
         # readers get a clean [] and the ChatBuilder gate (present? => wire) is stable.
         subagents: subagents.nil? ? nil : Array(subagents).map(&:to_s),
         tools_deferred: tools_deferred, memory: memory,
-        prompt_caching: prompt_caching, tool_output_compression: tool_output_compression,
+        prompt_caching: prompt_caching, tool_persistence: tool_persistence,
+        tool_output_compression: tool_output_compression,
         # The free-form hashes arrive with symbol keys (internal build) OR string
         # keys (StoredProfileSource JSON round-trip). Normalize to string keys ONCE
         # here — the single front door every profile passes through — so no reader
@@ -228,10 +359,71 @@ module Insika
         budget: Coercion.deep_stringify(budget),
         reliability: Coercion.deep_stringify(reliability),
         alerts: Coercion.deep_stringify(alerts),
-        stuck_signal: stuck_signal
+        routes: Coercion.deep_stringify(routes),
+        stuck_signal: stuck_signal,
+        outputs: Coercion.deep_stringify(outputs),
+        # plain vocabulary string, like `base_prompt` — no deep_stringify (not
+        # a Hash/Array). "" round-trips as nil (Coercion.presence).
+        stt_prompt: Coercion.presence(stt_prompt),
+        # Flat [String] — same discipline as capabilities_declared: a
+        # symbol/string mix would be a silent miss in the provider's known-set.
+        briefing_fields: normalize_briefing_fields(briefing_fields),
+        # grounding is profile DATA, deep-stringified like the other
+        # free-form hashes; parsed into a Grounding per turn by the validator/
+        # enforcer. nil = off (parity).
+        grounding: Coercion.deep_stringify(grounding),
+        # funnel is profile DATA, deep-stringified like the other
+        # free-form hashes; parsed into a FunnelDeclaration by the fold/doctor/
+        # Studio (shape-validated THERE, never here — D8). nil = no funnel (parity).
+        funnel: Coercion.deep_stringify(funnel),
+        # followup is profile DATA, deep-stringified like the other
+        # free-form hashes; parsed into a FollowupPolicy by the tool/engine/
+        # doctor/Studio (shape-validated THERE, never here — D9). nil = off (parity).
+        followup: Coercion.deep_stringify(followup),
+        # distill is profile DATA, deep-stringified like the other
+        # free-form hashes; shape-validated by the command/engine/doctor
+        # (never here — the refinement precedent). nil = off (parity).
+        distill: Coercion.deep_stringify(distill),
+        # harvest is profile DATA, deep-stringified like the other
+        # free-form hashes; shape-validated by the command/engine/doctor
+        # (never here — the refinement precedent). nil = off (parity).
+        harvest: Coercion.deep_stringify(harvest),
+        # knowledge is profile DATA, deep-stringified like the other
+        # free-form hashes; shape-validated by the extractor/doctor
+        # (never here — the refinement precedent). nil = off (parity).
+        knowledge: Coercion.deep_stringify(knowledge),
+        # schedules is profile DATA, deep-stringified like the other
+        # free-form hashes (an ARRAY of declarations); parsed into
+        # Insika::Schedule entries by the engine/doctor/Studio (shape-validated
+        # THERE, never here). nil/[] = the feature is off (parity).
+        schedules: normalize_schedules(schedules)
       )
     end
 
+    # nil/absent -> nil; a single Hash -> [Hash]; else an Array of Hashes —
+    # deep-stringified so JSON round-trips stay stable.
+    def self.normalize_schedules(list)
+      return nil if list.nil?
+
+      entries = list.is_a?(Hash) ? [list] : Array(list)
+      entries.empty? ? nil : Coercion.deep_stringify(entries)
+    end
+
+    # nil -> []; strings; trim + drop empties + uniq (stable order); every name
+    # must match ToolDefinition::NAME_RE (\A[a-z][a-z0-9_]*\z) or it is a
+    # ValidationError at build time — the names become tool-description text,
+    # store keys and context-block lines, so "size ok" or "tamanho do cliente"
+    # is refused here, not corrupted later.
+    def self.normalize_briefing_fields(list)
+      names = Array(list).map { |f| f.to_s.strip }.reject(&:empty?).uniq
+      bad = names.reject { |n| ToolDefinition::NAME_RE.match?(n) }
+      unless bad.empty?
+        raise Insika::ValidationError,
+              "briefing_fields must match #{ToolDefinition::NAME_RE.inspect}: #{bad.join(', ')}"
+      end
+      names
+    end
+
     # opt-in for an optional tool = being in the agent's allow list.
     def tool_opted_in?(name)
       Array(tools_allow).include?(name)

data/lib/insika/artifact_signing.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require "openssl"
+require "time"
+
+module Insika
+  # The signed-link half of the artifact serving surface. The signing key
+  # lives in the environment (INSIKA_ARTIFACT_SIGNING_KEY), never in a store:
+  # HMAC-SHA256 over (id, expiry), verified in constant time on the serve
+  # path. Without the key, only the authenticated Studio URL exists.
+  #
+  # The token is deterministic for a (id, expiry) pair — no nonce, on purpose:
+  # a rotated key invalidates every outstanding link, which is the documented
+  # rotation behavior (an artifact link is short-lived by TTL, not by
+  # unguessability of a single-use nonce).
+  module ArtifactSigning
+    module_function
+
+    # The route's path shapes — the ONE place the URL grammar lives, shared
+    # by the tool (which hands URLs to the model) and the route (which serves
+    # them).
+    AUTHENTICATED_PATH = "/studio/artifacts/%{id}/content"
+    SIGNED_PATH = "/studio/artifacts/s/%{id}?exp=%{exp}&sig=%{sig}"
+
+    # -> hex token (64 chars) | nil when the key is blank (no signed surface).
+    def sign(id:, expires_at:, key:)
+      key = key.to_s
+      return nil if key.empty?
+
+      OpenSSL::HMAC.hexdigest("SHA256", key, payload(id, expires_at))
+    end
+
+    # -> bool. Re-signs the (id, exp) pair the route extracted from the URL
+    # and compares in constant time; an expired link or a blank key/token is
+    # false (the route 404s — no oracle). Expiry is inclusive: a link at its
+    # exact `expires_at` still verifies.
+    def valid?(id:, token:, key:, exp:, now: Time.now.utc)
+      token = token.to_s
+      key = key.to_s
+      return false if key.empty? || token.empty?
+
+      expected = sign(id: id.to_s, expires_at: exp, key: key)
+      return false unless expected && secure_compare(expected, token)
+
+      exp_time = exp.is_a?(Time) ? exp.to_time.utc : Time.iso8601(exp.to_s).utc
+      now.to_time <= exp_time
+    rescue ArgumentError, TypeError
+      false # a malformed exp (or a time that never parses) is an invalid link
+    end
+
+    # -> the artifact's shareable URL. With a key + ttl: the signed link
+    # (shares OUTSIDE the Studio, expires). Without: the authenticated Studio
+    # content URL. An empty base yields the relative path — still openable in
+    # the Studio, useless on a channel (the doc says exactly that).
+    def url_for(id:, base: nil, key: nil, ttl: nil, now: Time.now.utc)
+      base = base.to_s.sub(%r{/\z}, "")
+      if key && key.to_s.length.positive? && ttl && ttl.to_i.positive?
+        exp = (now.to_time + ttl.to_i).utc.iso8601
+        sig = sign(id: id.to_s, expires_at: exp, key: key)
+        "#{base}#{format(SIGNED_PATH, id: id, exp: exp, sig: sig)}"
+      else
+        "#{base}#{format(AUTHENTICATED_PATH, id: id)}"
+      end
+    end
+
+    # Constant-time comparison of two hex strings. Length-independent compare
+    # is fine here: the token length is public (fixed by the algorithm).
+    def secure_compare(a, b)
+      return false unless a.bytesize == b.bytesize
+
+      a.bytes.zip(b.bytes).reduce(0) { |acc, (x, y)| acc | (x ^ y) }.zero?
+    end
+
+    # The signed payload: id + expiry — both are what the route must not let
+    # an attacker change. The id is the store key; the expiry bounds the link.
+    # Accepts a Time or an ISO8601 String (the route passes the query param).
+    def payload(id, expires_at)
+      time = expires_at.is_a?(Time) ? expires_at.utc : Time.iso8601(expires_at.to_s).utc
+      "#{id}:#{time.iso8601}"
+    end
+  end
+end