insika 0.3.0 → 0.7.0

data/lib/insika/templates/browser-agent/agent.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+# ---
+# title: Browser Agent
+# trail: MCP
+# description: Live MCP tool-loop over stdio — navigates and summarizes a real webpage via Playwright's MCP server. Requires Node.js/npm and INSIKA_MCP_STDIO=1.
+# capabilities: mcp, stdio
+# env: INSIKA_MCP_STDIO
+# requires: Node.js and npm (npx spawns the MCP server as a child process)
+# ---
+#
+# browser-agent — a live MCP tool-loop over STDIO: the agent
+# drives a real, sandboxed browser through Playwright's MCP server
+# (@playwright/mcp, no API key). stdio is arbitrary command execution by
+# config, so it needs the operator's explicit opt-in (INSIKA_MCP_STDIO=1)
+# and Node.js/npm on the machine — the two things this template needs
+# beyond the gem and a provider key. Swap MCP_COMMAND/MCP_ARGS for any other
+# MCP server and nothing else in this file changes.
+#
+#   INSIKA_MCP_STDIO=1 DEEPSEEK_API_KEY=sk-... ruby browser-agent/agent.rb "go to example.com and summarize the page"
+require "insika"
+require "shellwords"
+
+browser = Insika.agent("browser-agent") do
+  model "deepseek-v4-flash"
+  provider :deepseek
+
+  instructions <<~PROMPT
+    You browse the web using the browser MCP tools. Navigate to the
+    requested page, then extract or summarize what was asked. Never invent
+    page content — always navigate and read it first.
+  PROMPT
+
+  mcp "browser", transport: :stdio,
+      command: ENV.fetch("MCP_COMMAND", "npx"),
+      args: Shellwords.split(ENV.fetch("MCP_ARGS", "-y @playwright/mcp@latest"))
+end
+
+if __FILE__ == $PROGRAM_NAME
+  if ARGV.delete("--serve")
+    browser.serve
+  else
+    message = ARGV.join(" ")
+    message = "Go to https://example.com and summarize the page in two sentences." if message.empty?
+    puts browser.reply(message)
+  end
+end
+
+browser

data/lib/insika/templates/daily-digest/README.md

@@ -0,0 +1,38 @@
+# daily-digest
+
+**Always-on trail.** The report pipeline in one file: a recurring
+`schedule` (the engine's own tick fires it), a `save_artifact`
+tool (the report destination), and a store-free skill describing
+*how* to build the report. No database, no store content — the day's
+numbers are fake, inline text.
+
+```bash
+DEEPSEEK_API_KEY=sk-... ruby daily-digest/agent.rb
+```
+
+Expected output: a reply ending in `Report: /studio/artifacts/<id>`.
+
+```bash
+DEEPSEEK_API_KEY=sk-... ruby daily-digest/agent.rb --serve
+```
+
+Then open `/studio`, log in with the printed token, and either wait for the
+schedule (22:00 America/Sao_Paulo) or send a message to the "reporter" agent
+in the Playground — the artifact lands on the Artifacts tab either way.
+
+## What's real here
+
+- The **schedule** is a live engine feature: the tick actually fires this
+  turn at the cron time, in the same process, no external cron needed.
+- The **artifact** is a real signed/authenticated URL the report is saved
+  to — open it and the HTML renders with its own strict CSP (`default-src
+  'none'`), so the inline SVG chart has to be self-contained by
+  construction, not by convention.
+- The **numbers** are not. Swap the literal string in `agent.rb` for a
+  `data_tool` against your own sales API and nothing else changes.
+
+## Edit it
+
+The skill's instructions are the actual report spec — change the palette,
+add a second table, or add another chart. The schedule's `cron`/`tz` are
+plain arguments.

data/lib/insika/templates/daily-digest/agent.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+# ---
+# title: Daily Digest
+# trail: Always-on
+# description: A recurring schedule plus save_artifact build and publish a self-contained HTML report — no store, fake in-memory numbers only.
+# capabilities: schedule, save_artifact, skill
+# ---
+#
+# daily-digest — the report pipeline in one file: a recurring schedule (the
+# engine's own tick fires it), a daily-digest skill (the inline-SVG
+# pattern), the save_artifact tool (the report destination) and the
+# per-agent allowlist that gates it. No store content — fake, in-memory
+# "sales" numbers only.
+#
+#   DEEPSEEK_API_KEY=sk-... ruby daily-digest/agent.rb
+#   DEEPSEEK_API_KEY=sk-... ruby daily-digest/agent.rb --serve
+#       # --serve: open /studio, log in with the printed token, then send a
+#       # message to the "reporter" agent in the Playground — the artifact
+#       # lands on the Artifacts tab. The schedule fires the same run at
+#       # 22:00 America/Sao_Paulo on its own.
+require "insika"
+
+todays_sales = "Coffee 128 units ($512), Tea 64 units ($192), Pastries 40 units ($160)."
+
+reporter = Insika.agent("reporter") do
+  model "deepseek-v4-flash"
+  provider :deepseek
+
+  instructions <<~PROMPT
+    You produce the daily sales digest from the numbers given to you in the
+    message. Follow the daily-digest skill exactly, then save the finished
+    page with save_artifact (HTML with inline SVG). End your reply with the
+    artifact url, on its own line, prefixed with "Report: ".
+  PROMPT
+
+  # The per-agent allowlist IS the switch for save_artifact — without this
+  # line the model never even sees the tool.
+  tools %w[save_artifact]
+
+  # A recurring turn — the engine's tick fires it. session_mode:
+  # "new" = a fresh session per run (the report shape); the overrides raise
+  # the chat-time ceilings a real report needs.
+  schedule "daily_report", cron: "0 22 * * *", tz: "America/Sao_Paulo",
+           message: "Run the daily report now. Today's sales: #{todays_sales}",
+           session_mode: "new",
+           overrides: { turn_timeout: 600, max_tool_calls: 120 }
+
+  # The generic, store-free skill: how a report is BUILT — the inline-SVG
+  # pattern (palette, table, pure-SVG bars, light/dark). No store ids, no
+  # queries — that half belongs in a merchant's pack, not here.
+  skill "daily-digest",
+        description: "How to build the daily sales digest as a self-contained HTML report",
+        instructions: <<~MD
+          Build the digest as ONE self-contained HTML page:
+          - a <style> block with a light palette (e.g. #f8fafc bg, #0f172a text,
+            #6366f1 accent), plus a prefers-color-scheme: dark override;
+          - one <table> of the numbers (th/tbody, right-aligned amounts);
+          - one inline SVG bar chart (no <script>, no <img>, no <iframe>,
+            no external fonts or fetches — the report is served with
+            default-src 'none', so nothing external can load);
+          - a title and the run date.
+          Keep it readable on a phone. The report is the deliverable; the
+          channel message is just the link to it.
+        MD
+end
+
+if __FILE__ == $PROGRAM_NAME
+  if ARGV.delete("--serve")
+    reporter.serve
+  else
+    puts reporter.reply("Run the daily report now. Today's sales: #{todays_sales}")
+    puts "\nThen open the returned /studio/artifacts/<id> page (or --serve and look at the Artifacts tab)."
+  end
+end
+
+reporter

data/lib/insika/templates/repo-explorer/README.md

@@ -0,0 +1,36 @@
+# repo-explorer
+
+**MCP trail (http).** A live MCP tool-loop over Streamable HTTP:
+the agent calls a real, running MCP server's tools — not a snapshot, not a
+hand-rolled HTTP wrapper. The default target is
+[DeepWiki's public MCP server](https://mcp.deepwiki.com/mcp), which needs
+no API key for public repos.
+
+```bash
+DEEPSEEK_API_KEY=sk-... ruby repo-explorer/agent.rb "how does rails/rails route a request?"
+```
+
+This is not a DeepWiki showcase — it's exactly how you plug **any** MCP
+server into an agent:
+
+```bash
+MCP_URL=https://your-mcp-server/mcp DEEPSEEK_API_KEY=sk-... ruby repo-explorer/agent.rb "..."
+```
+
+Point `MCP_URL` at any Streamable HTTP or SSE MCP server and nothing else
+in `agent.rb` changes — swap the URL, rewrite the instructions for the new
+server's tools, done.
+
+## Under the hood
+
+`mcp "repo-docs", transport: :http, url: …` declares the instance; the
+engine connects live, discovers its tools (`read_wiki_structure`,
+`read_wiki_contents`, `ask_question`), and wires them straight into the
+agent's tool-loop with group `mcp:repo-docs`. Declaring an `mcp` inside an
+agent's block auto-grants that agent access to the group — see
+`lib/insika/dsl.rb`'s `mcp` method if you're curious why that matters.
+
+A public HTTPS target needs no extra configuration (same egress guard as
+any data-tool). A target on a private network needs the same
+`INSIKA_EGRESS_ALLOW_PRIVATE`/`INSIKA_EGRESS_HOSTS` env vars a data-tool
+would.

data/lib/insika/templates/repo-explorer/agent.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# ---
+# title: Repo Explorer
+# trail: MCP
+# description: Live MCP tool-loop over http — answers questions about any public GitHub repo via a keyless public MCP server. Point MCP_URL at any other MCP server instead.
+# capabilities: mcp, http
+# ---
+#
+# repo-explorer — a live MCP tool-loop over HTTP: the agent calls
+# a real MCP server's tools (read_wiki_structure, read_wiki_contents,
+# ask_question) to answer questions about a public GitHub repo. The default
+# target is DeepWiki's public, keyless MCP server — swap MCP_URL for any
+# other MCP server and nothing else in this file changes.
+#
+#   DEEPSEEK_API_KEY=sk-... ruby repo-explorer/agent.rb "how does rails/rails route a request?"
+#   MCP_URL=https://your-mcp-server/mcp DEEPSEEK_API_KEY=sk-... ruby repo-explorer/agent.rb "..."
+require "insika"
+
+repo = Insika.agent("repo-explorer") do
+  model "deepseek-v4-flash"
+  provider :deepseek
+
+  instructions <<~PROMPT
+    You answer questions about public GitHub repositories using the
+    repo-docs MCP tools (read_wiki_structure, read_wiki_contents,
+    ask_question). Repos are named "owner/repo" (e.g. "rails/rails"). Never
+    answer from your own training data when a tool can check — call
+    ask_question first.
+  PROMPT
+
+  mcp "repo-docs", transport: :http, url: ENV.fetch("MCP_URL", "https://mcp.deepwiki.com/mcp")
+end
+
+if __FILE__ == $PROGRAM_NAME
+  if ARGV.delete("--serve")
+    repo.serve
+  else
+    message = ARGV.join(" ")
+    message = "In the rails/rails repo, how does routing work? One paragraph." if message.empty?
+    puts repo.reply(message)
+  end
+end
+
+repo

data/lib/insika/templates/research-analyst/README.md

@@ -0,0 +1,26 @@
+# research-analyst
+
+**Advanced trail.** Four agents in one `Insika.system`: three specialists
+(market, technical, risk) and a lead ("analyst") that has no expertise of
+its own and must delegate. The MODEL decides to fan out — nothing in Ruby
+orchestrates the parallel calls.
+
+```bash
+DEEPSEEK_API_KEY=sk-... ruby research-analyst/agent.rb "a subscription box for specialty coffee"
+```
+
+Under the hood: the lead calls `spawn_subagents` once with all three
+specialist ids, they run **in parallel** (each in an isolated context — a
+child never sees the parent's conversation), and the lead synthesizes their
+three answers into one recommendation.
+
+Nothing forces the model to delegate — that's the trade of a model-driven
+pattern over a hand-coded workflow. If it answers alone instead, the fix is
+the lead's prompt, not the code: it needs to be told, plainly, that it has
+no expertise of its own.
+
+## Edit it
+
+Add a fourth specialist (`agent("competitors") { … }`, then add it to
+`subagents`), or turn any specialist into a `Insika.agent` with its own
+data-tools — a subagent is an ordinary agent, capability included.

data/lib/insika/templates/research-analyst/agent.rb

@@ -0,0 +1,58 @@
+# frozen_string_literal: true
+
+# ---
+# title: Research Analyst
+# trail: Advanced
+# description: Insika.system fan-out — three specialist subagents research different angles of a topic in parallel, the lead delegates and synthesizes.
+# capabilities: subagents, delegation, system
+# ---
+#
+# research-analyst — a lead agent with no expertise of its own: it must
+# delegate. spawn_subagents fans out to three specialists on separate angles
+# of a business idea, IN PARALLEL (each in its own isolated context), then
+# the lead synthesizes one recommendation.
+#
+#   DEEPSEEK_API_KEY=sk-... ruby research-analyst/agent.rb "a subscription box for specialty coffee"
+#   DEEPSEEK_API_KEY=sk-... ruby research-analyst/agent.rb --serve
+require "insika"
+
+team = Insika.system do
+  provider :deepseek
+
+  agent("market") do
+    model "deepseek-v4-flash"
+    instructions "Research the MARKET angle of a business idea: audience, demand, competitors. Three sentences."
+  end
+  agent("technical") do
+    model "deepseek-v4-flash"
+    instructions "Research the TECHNICAL/OPERATIONAL angle of a business idea: what it takes to build and run it. Three sentences."
+  end
+  agent("risk") do
+    model "deepseek-v4-flash"
+    instructions "Research the RISK angle of a business idea: what could make it fail. Three sentences."
+  end
+
+  agent "analyst" do
+    model "deepseek-v4-flash"
+    instructions <<~PROMPT
+      You are a research LEAD with no expertise of your own — never answer
+      from your own knowledge. Given a business idea, call spawn_subagents
+      once with all three specialists (market, technical, risk), then
+      synthesize their findings into one short recommendation: go, no-go, or
+      go-with-changes, and why.
+    PROMPT
+    subagents "market", "technical", "risk"
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  if ARGV.delete("--serve")
+    team.serve
+  else
+    topic = ARGV.join(" ")
+    topic = "a subscription box for specialty coffee" if topic.empty?
+    puts team.reply("analyst", "Research this idea: #{topic}")
+  end
+end
+
+team

data/lib/insika/templates/review-panel/README.md

@@ -0,0 +1,20 @@
+# review-panel
+
+**Teams trail.** The `Insika.system` snippet from the gem's main examples
+README, promoted to a runnable template: a "reviewer" lead with no
+expertise of its own delegates to two specialists — security and
+performance — IN PARALLEL, then synthesizes one prioritized fix.
+
+```bash
+DEEPSEEK_API_KEY=sk-... ruby review-panel/agent.rb
+```
+
+`panel.reply("reviewer", …)` — the target agent is always explicit; with
+several agents in one system, inferring which one should answer would be a
+guess, and a wrong guess is a silently wrong conversation.
+
+## Edit it
+
+Add a third specialist (a `style` reviewer, say), list it in `subagents`,
+and the lead's synthesis prompt already generalizes — it doesn't name the
+specialists, just says "both".

data/lib/insika/templates/review-panel/agent.rb

@@ -0,0 +1,50 @@
+# frozen_string_literal: true
+
+# ---
+# title: Review Panel
+# trail: Teams
+# description: Two specialists reviewed in parallel by a synthesizing lead, explicit target agent (Insika.system + subagents).
+# capabilities: subagents, delegation, system
+# ---
+#
+# review-panel — promotes the examples/README.md snippet to a runnable
+# template: a "reviewer" lead that has no expertise of its own delegates to
+# two specialists (security, performance) IN PARALLEL, then synthesizes.
+#
+#   DEEPSEEK_API_KEY=sk-... ruby review-panel/agent.rb
+#   DEEPSEEK_API_KEY=sk-... ruby review-panel/agent.rb --serve
+require "insika"
+
+panel = Insika.system do
+  provider :deepseek
+
+  agent("security")    { model "deepseek-v4-flash"; instructions "Review code for SECURITY issues. Two sentences." }
+  agent("performance") { model "deepseek-v4-flash"; instructions "Review code for PERFORMANCE issues. Two sentences." }
+
+  agent "reviewer" do
+    model "deepseek-v4-flash"
+    instructions <<~PROMPT
+      You are a review LEAD with no reviewing expertise of your own — never
+      review from your own knowledge. Call spawn_subagents once with both
+      specialists (security, performance), then synthesize their findings
+      into the single highest-priority fix.
+    PROMPT
+    subagents "security", "performance"
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  code = <<~RUBY
+    def find_user(name)
+      User.where("name = '\#{name}'").to_a.select { |u| u.active }
+    end
+  RUBY
+
+  if ARGV.delete("--serve")
+    panel.serve
+  else
+    puts panel.reply("reviewer", "Review this code:\n#{code}")
+  end
+end
+
+panel

data/lib/insika/templates/travel-planner/README.md

@@ -0,0 +1,35 @@
+# travel-planner
+
+**Starter trail.** A trip-planning assistant built entirely from **declarative
+data-tools** — no Ruby tool class, no rebuild. Three tools, three public
+HTTPS APIs, zero API keys beyond your LLM provider's:
+
+- `geocode_city` — Open-Meteo's geocoding API (city name → coordinates)
+- `get_weather` — Open-Meteo's forecast API (coordinates → today's conditions)
+- `convert_currency` — Frankfurter's reference exchange rates
+
+```bash
+DEEPSEEK_API_KEY=sk-... ruby travel-planner/agent.rb "3 days in Lisbon, budget 200 USD"
+```
+
+The model chains the first two tools itself (geocode, then weather) and
+calls the third when a budget is mentioned — nothing here tells it the
+order, the instructions just describe what each tool is for.
+
+## Egress guard (SSRF protection)
+
+Data-tools make **server-side** HTTP calls, so the engine ships an egress
+guard that is strict by default: public HTTPS only. This template works
+with zero configuration because all three endpoints are public HTTPS — a
+tool pointed at `http://…`, `localhost`, or a private IP would be blocked
+instead (`{ error: "destination blocked: …" }` back to the model, a clean
+tool error, never a crash). Opting a private/internal target in is a
+deployment env var (`INSIKA_EGRESS_ALLOW_HTTP`/`_PRIVATE`/`_HOSTS`), never a
+DSL setting — see `docs/TOOLS.md`'s "MCP servers" / egress sections in the
+installed gem's docs for the full contract.
+
+## Edit it
+
+Open `agent.rb` — it's the same file `insika new` copied and the same one
+this README describes. Add a fourth data-tool, change the model, or point
+an existing one at a different provider; nothing else needs to change.

data/lib/insika/templates/travel-planner/agent.rb

@@ -0,0 +1,87 @@
+# frozen_string_literal: true
+
+# ---
+# title: Travel Planner
+# trail: Starter
+# description: Weather + currency data-tools against keyless public APIs (Open-Meteo, Frankfurter) — the egress guard does its job with zero configuration.
+# capabilities: data-tool, egress-guard
+# ---
+#
+# travel-planner — plans a trip: geocodes the destination, checks today's
+# weather, and converts a budget to the local currency. Three declarative
+# data-tools, no Ruby tool class, no API key beyond the LLM provider's.
+#
+#   DEEPSEEK_API_KEY=sk-... ruby travel-planner/agent.rb "3 days in Lisbon, budget 200 USD"
+#   DEEPSEEK_API_KEY=sk-... ruby travel-planner/agent.rb --serve
+require "insika"
+
+travel = Insika.agent("travel-planner") do
+  model "deepseek-v4-flash"
+  provider :deepseek
+
+  instructions <<~PROMPT
+    You are a travel-planning assistant. Given a destination and, optionally,
+    a budget amount + currency:
+      1. geocode_city to find its coordinates — never guess them.
+      2. get_weather for those coordinates and summarize today's conditions.
+      3. If a budget was given, convert_currency to the destination's local
+         currency and report the converted amount.
+    Never invent coordinates, weather or exchange rates — always call the tools.
+  PROMPT
+
+  data_tool(
+    "name"        => "geocode_city",
+    "description" => "Latitude/longitude for a city name (Open-Meteo geocoding).",
+    "parameters"  => {
+      "type" => "object",
+      "properties" => { "city" => { "type" => "string", "description" => "city name, e.g. Lisbon" } },
+      "required" => ["city"]
+    },
+    "request"  => { "method" => "GET", "url" => "https://geocoding-api.open-meteo.com/v1/search?name={{city}}&count=1" },
+    "response" => { "extract" => "body_raw" }
+  )
+
+  data_tool(
+    "name"        => "get_weather",
+    "description" => "Current weather for a latitude/longitude (Open-Meteo).",
+    "parameters"  => {
+      "type" => "object",
+      "properties" => {
+        "latitude"  => { "type" => "number", "description" => "from geocode_city" },
+        "longitude" => { "type" => "number", "description" => "from geocode_city" }
+      },
+      "required" => %w[latitude longitude]
+    },
+    "request"  => { "method" => "GET", "url" => "https://api.open-meteo.com/v1/forecast?latitude={{latitude}}&longitude={{longitude}}&current_weather=true" },
+    "response" => { "extract" => "body_raw" }
+  )
+
+  # Author the FINAL url — the HTTP client does not follow redirects.
+  # api.frankfurter.app now redirects to api.frankfurter.dev.
+  data_tool(
+    "name"        => "convert_currency",
+    "description" => "Latest reference exchange rate between two currencies.",
+    "parameters"  => {
+      "type" => "object",
+      "properties" => {
+        "from" => { "type" => "string", "description" => "source currency code, e.g. USD" },
+        "to"   => { "type" => "string", "description" => "target currency code, e.g. BRL" }
+      },
+      "required" => %w[from to]
+    },
+    "request"  => { "method" => "GET", "url" => "https://api.frankfurter.dev/v1/latest?from={{from}}&to={{to}}" },
+    "response" => { "extract" => "body_raw" }
+  )
+end
+
+if __FILE__ == $PROGRAM_NAME
+  if ARGV.delete("--serve")
+    travel.serve
+  else
+    message = ARGV.join(" ")
+    message = "I'm spending 3 days in Lisbon with a budget of 200 USD. What should I pack, and how much is that in EUR?" if message.empty?
+    puts travel.reply(message)
+  end
+end
+
+travel

data/lib/insika/templates.rb

@@ -0,0 +1,112 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Insika
+  # Template gallery: example agents shipped INSIDE the gem
+  # (`lib/insika/templates/<name>/{agent.rb,README.md}`), one DSL file per
+  # template that is BOTH doors — `insika new <name>` copies it for the user
+  # to run and edit, and this module `evaluate`s the same file to hand its
+  # pack(s) to the Studio's "New from template" gallery. No parallel pack
+  # format to drift.
+  #
+  # A template's `agent.rb` guards its CLI demo footer with
+  # `if __FILE__ == $PROGRAM_NAME` (false when this module evaluates it) and
+  # ends with the bare `Insika.agent`/`Insika.system` result as its LAST
+  # expression, so `evaluate` gets it back as the string-eval's return value
+  # — no registration call, no second source of truth.
+  module Templates
+    ROOT = File.expand_path("templates", __dir__)
+
+    Entry = Data.define(:name, :title, :trail, :description, :capabilities, :studio, :env, :requires) do
+      def studio? = studio
+    end
+
+    module_function
+
+    # -> [String] template dirs that have an agent.rb, lexicographic.
+    def names
+      return [] unless Dir.exist?(ROOT)
+
+      Dir.children(ROOT).select { |n| File.file?(agent_path(n)) }.sort
+    end
+
+    # -> [Entry] every template, parsed metadata only (no evaluation — cheap,
+    # safe to call on every render of the Studio gallery).
+    def all = names.map { |n| read(n) }
+
+    # -> Entry for one template. Raises NotFoundError for an unknown name —
+    # same discipline as a missing agent/MCP instance.
+    def read(name)
+      path = agent_path(name)
+      raise Insika::NotFoundError, "template '#{name}' not found" unless File.file?(path)
+
+      meta = frontmatter(File.read(path))
+      Entry.new(
+        name: name.to_s, title: presence(meta["title"]) || name.to_s, trail: presence(meta["trail"]),
+        description: meta["description"].to_s,
+        capabilities: split_list(meta["capabilities"]),
+        studio: meta.fetch("studio", true) != false,
+        env: split_list(meta["env"]), requires: presence(meta["requires"])
+      )
+    end
+
+    # Evaluates the template's agent.rb in an ISOLATED scope (a fresh Object's
+    # instance_eval) and returns whatever its last expression is — the built
+    # `Insika::DSL::Definition` or `Insika::DSL::System`. $PROGRAM_NAME here is
+    # whatever process called this (rspec, the CLI, the Studio server), never
+    # this file's path, so the template's own `if __FILE__ == $PROGRAM_NAME`
+    # demo footer never runs: no network call, no ARGV parsing, no puts.
+    #
+    # The fresh-Object receiver keeps a template's local variables and `def`s
+    # from leaking into the next one evaluated in the same process; a
+    # top-level CONSTANT would still leak (Ruby scopes constant assignment
+    # lexically, not by `self`) — wave-1 templates simply don't declare any
+    # (the conformance spec, would catch a future one that did).
+    def evaluate(name)
+      path = agent_path(name)
+      raise Insika::NotFoundError, "template '#{name}' not found" unless File.file?(path)
+
+      Object.new.instance_eval(File.read(path), path)
+    end
+
+    # -> [Pack] one per agent, regardless of whether the template is a single
+    # `Insika.agent` (Definition#to_pack) or a system (System#to_packs).
+    def packs_for(name)
+      built = evaluate(name)
+      built.respond_to?(:to_packs) ? built.to_packs : [built.to_pack]
+    end
+
+    def agent_path(name) = File.join(ROOT, name.to_s, "agent.rb")
+    def readme_path(name) = File.join(ROOT, name.to_s, "README.md")
+
+    # A `# ---` … `# ---` comment block at the very top of the file, YAML
+    # inside (each line stripped of its leading `# `). Not real Ruby
+    # frontmatter (there's no such thing) — a convention this module alone
+    # parses, so the metadata lives in the one file without needing a
+    # side-channel manifest.
+    def frontmatter(source)
+      lines = source.lines
+      # Every template starts with the same magic comment every other .rb
+      # file in the gem does — skip it (and any blank line) before looking
+      # for the block, so templates don't have to break that convention.
+      lines = lines.drop(1) while lines.first && (lines.first.strip.empty? || lines.first.strip == "# frozen_string_literal: true")
+      return {} unless lines.first&.strip == "# ---"
+
+      body = lines.drop(1)
+                  .take_while { |l| l.strip != "# ---" }
+                  .map { |l| l.sub(/\A#\s?/, "") }
+                  .join
+      YAML.safe_load(body) || {}
+    end
+    private_class_method :frontmatter
+
+    def split_list(value)
+      value.to_s.split(",").map(&:strip).reject(&:empty?)
+    end
+    private_class_method :split_list
+
+    def presence(str) = Insika::Coercion.presence(str)
+    private_class_method :presence
+  end
+end