insika 0.3.0 → 0.8.0

data/bin/insika

@@ -16,6 +16,7 @@
 # DEEPSEEK, no seeding. So it is safe to run against a live deployment's volume.
 
 require "optparse"
+require "fileutils"
 require_relative "../lib/insika"
 
 module Insika
@@ -31,10 +32,17 @@ module Insika
       when "harvest" then harvest(argv)
       when "harvest:negative" then harvest_negative_import(argv)
       when "harvest:criterion" then harvest_criterion_check(argv)
+      when "tools:report" then tools_report(argv)
+      when "knowledge:backfill" then knowledge_backfill(argv)
+      when "knowledge:export" then knowledge_export(argv)
       when "soak"    then exit(Insika::Soak::Runner.main(argv, stdout: $stdout, stderr: $stderr))
       when "evals:import" then evals_import(argv)
       when "evals:export" then evals_export(argv)
       when "evals:baseline" then evals_baseline(argv)
+      when "evals:simulate" then evals_simulate(argv)
+      when "demo:seed" then demo_seed(argv)
+      when "mcp" then mcp(argv)
+      when "new" then new_from_template(argv)
       when "version", "--version", "-v" then puts "insika #{Insika::VERSION}"
       when "help", "--help", "-h" then puts usage
       else
@@ -58,16 +66,52 @@ module Insika
                                     seed the profile's negative list from a rules file
           harvest:criterion check --file F
                                     strict-load the frozen conversion criterion
+          tools:report [--agent ID] [--days N] [--json]
+                                    tool usage per agent over the stored traces:
+                                    allowlisted-but-never-called, error rate > 30%
+                                    in the window, and stale (not called in N days).
+                                    Read-only — the operator removes
+          knowledge:backfill --agent ID [--since ISO8601] [--json]
+                                    the recovery path for post-turn extraction: replays
+                                    the agent's stored sessions through the same
+                                    extractor a live turn uses
+          knowledge:export --agent ID [--out DIR] [--tenant T] [--format md|graphml]
+                                    writes one <name>.md per learned concept under DIR —
+                                    a dump, not a converter (the storage format IS the
+                                    export format), for okf-gem/graphify tooling; --format
+                                    graphml writes one knowledge.graphml graph file instead
           soak   --run | --verify FILE | --preflight   the 72h soak
           evals:import [--dir D]    load the golden corpus into the store (editable in Studio)
           evals:export [--dir D]    write the stored cases back out as YAML
           evals:baseline <sub>      the accepted state per agent: show | import | export
+          evals:simulate --persona F --target <agent|url>
+                                    generate a simulated conversation against an
+                                    agent: a persona model talks to the
+                                    target until max_turns or a stop marker; the
+                                    transcript is scored by the judge panel.
+                                    Requires --staging or --eval-profile (a simulated
+                                    run must not write for real); --eval-profile is
+                                    verified against the target's derived
+                                    side-effect tools (--eval-tools).
+          demo:seed [--force]       populate the "demo-store" agent with enough data to see
+                                    every Studio loop at once (funnel+baseline, follow-ups,
+                                    refinement runs, approvals, distillation, evals+baseline)
+          mcp list                  the configured MCP instances
+          mcp add --name N [...]    add/edit an instance (see mcp add --help)
+          mcp remove NAME           delete an instance
+          mcp import FILE.json      upsert every entry of a `mcpServers` JSON document
+          mcp test NAME             connect live, list its tools, print them (or the error)
+          mcp refresh NAME          same as test, plus caches the result for display
+          new --list                the template gallery: trail + one-line description
+          new <template> [dir]      copy a template (default dir: ./<template>) and print the run line
           version                   print the engine version
           help                      show this help
 
         Environment:
           INSIKA_DB                 SQLite path (durable). Unset -> ephemeral memory.
           INSIKA_CONFIG_STRICT      when truthy, the server refuses boot on any finding.
+          INSIKA_MCP_STDIO          set to 1 to allow stdio MCP instances to start
+                                    (arbitrary command execution by config — off by default)
       TXT
     end
 
@@ -273,8 +317,552 @@ def baseline_export(path)
   puts "exported #{merged.size} case(s) from #{store.agents.size} agent baseline(s) to #{path}"
 end
 
+# insika evals:simulate --persona F --target <agent|url> [--staging|--eval-profile]
+#
+# Generates a SIMULATED conversation: a persona model (the cheap
+# utility_model) plays a customer with the persona as its whole instruction — and
+# one hard rule: it may ONLY assert what the persona's `knows` contains. The
+# target agent answers over the same Transport the replay uses (HttpTransport
+# against a running deployment, or a thin A2A transport when --target is a URL).
+#
+# SAFETY (fixed in the spec): a simulated conversation must not write for real,
+# because `simulated: true` marks the transcript, it does not disarm the tools.
+# So this CLI REQUIRES one of:
+#   --staging       the operator declares the target is a staging deployment
+#   --eval-profile  the target runs an eval profile (side-effect tools swapped
+#                   for dry-runs) — a VERIFIED declaration, not a trust-me flag:
+#                   the CLI derives the target's side-effect tools from the
+#                   deployment's own registry (GET /v1/agents/:id) or the local
+#                   store (INSIKA_DB), and requires --eval-tools to cover every
+#                   one of them. An A2A target (no reachable registry) requires
+#                   the explicit --eval-tools list.
+# and refuses to run without one. Every run is marked `simulated: true`.
+def evals_simulate(argv)
+  require "yaml"
+  require "json"
+  require "fileutils"
+  require "time"
+  opts = { base_url: ENV["INSIKA_URL"] || "http://localhost:9292",
+           token: ENV["INSIKA_GATEWAY_TOKEN"] || ENV["ADMIN_TOKEN"] || "local-demo",
+           timeout: 120, persona_model: ENV["EVAL_PERSONA_MODEL"],
+           judge_model: ENV["EVAL_JUDGE_MODEL"], judge_provider: ENV["EVAL_JUDGE_PROVIDER"] }
+  OptionParser.new do |o|
+    o.banner = "Usage: insika evals:simulate --persona F --target <agent|url> [options]"
+    o.on("--persona FILE", "the persona YAML — a case with a `persona:` key (required)") { |v| opts[:persona] = v }
+    o.on("--target T", "agent id (over --base-url) or an A2A http(s) URL (required)") { |v| opts[:target] = v }
+    o.on("--base-url URL", "deployment base URL (default #{opts[:base_url]})") { |v| opts[:base_url] = v }
+    o.on("--token T", "gateway token (default INSIKA_GATEWAY_TOKEN/local-demo)") { |v| opts[:token] = v }
+    o.on("--timeout N", Integer, "per-turn read timeout, and the A2A poll budget in seconds (default 120)") { |v| opts[:timeout] = v }
+    o.on("--staging", "the target is a staging deployment (side effects acceptable)") { opts[:staging] = true }
+    o.on("--eval-profile", "the target runs an eval profile (side-effect tools swapped for fakes)") { opts[:eval_profile] = true }
+    o.on("--eval-tools LIST", "comma-separated side-effect tools the eval profile swaps (verified against the derived set; required for an A2A target)") { |v| opts[:eval_tools] = v }
+    o.on("--persona-model MODEL", "the model playing the customer (default settings utility_model)") { |v| opts[:persona_model] = v }
+    o.on("--judge-model MODEL", "score the transcript's rubric with this model") { |v| opts[:judge_model] = v }
+    o.on("--judge-provider PROVIDER", "provider for the judge model") { |v| opts[:judge_provider] = v }
+    o.on("--pairwise", "compare the simulated transcript against the case's `reference:`") { opts[:pairwise] = true }
+    o.on("--conv ID", "conversation id (default: sim-<case id>-<random>, unique per run)") { |v| opts[:conv] = v }
+    o.on("--out FILE", "write the JSON report here") { |v| opts[:out] = v }
+  end.parse!(argv)
+
+  abort "insika evals:simulate: --persona is required" if opts[:persona].to_s.empty?
+  abort "insika evals:simulate: --target is required (<agent> or an A2A <url>)" if opts[:target].to_s.empty?
+  unless opts[:staging] || opts[:eval_profile]
+    abort "insika evals:simulate: a simulated run must not write for real — pass --staging " \
+          "(the target is a staging deployment) or --eval-profile (side-effect tools are swapped)"
+  end
+
+  golden = load_sim_persona(opts[:persona])
+  # --target names the agent actually simulated. An agent id overrides the
+  # persona file's `agent:` (the file is a reusable script); a URL means an A2A
+  # endpoint, where the agent id is irrelevant (the transport ignores it).
+  a2a_target = opts[:target].to_s.match?(%r{\Ahttps?://})
+  target_agent = a2a_target ? golden.agent : opts[:target].to_s
+  safety = build_sim_safety(opts, golden, target_agent, a2a_target)
+
+  settings = eval_settings_from_env
+  ask = build_persona_ask(opts, settings)
+  judge = build_sim_judge(opts, settings)
+
+  transport = build_sim_transport(opts)
+  simulator = Insika::Evals::Simulator.new(transport: transport, ask: ask, safety: safety)
+  # Unique per run: two runs sharing a conv share the deployment SESSION, so the
+  # second inherits the first's history — including across the A/B arms of a
+  # paired comparison, which it silently invalidates.
+  require "securerandom"
+  conv = opts[:conv] || "sim-#{golden.id}-#{SecureRandom.hex(4)}"
+  run = simulator.run(persona: golden.persona, agent: target_agent, conv: conv)
+
+  verdict = judge && judge.score_conversation(
+    rubric: golden.rubric, transcript: run.transcript, policy: golden.policy,
+    min_score: golden.min_score || Insika::Evals::Judge::DEFAULT_MIN_SCORE
+  )
+
+  pairwise = if opts[:pairwise] && golden.reference?
+               p = build_sim_pairwise(opts, settings)
+               if p
+                 p.compare_texts(
+                   ours: Insika::Evals::Pairwise.transcript_text(run.transcript),
+                   theirs: Insika::Evals::Pairwise.reference_transcript(golden.reference_messages),
+                   vs: golden.human_assisted? ? "human-assisted" : "agent"
+                 )
+               end
+             end
+
+  at = Time.now.utc.iso8601
+  report = { "simulated" => true, "at" => at, "id" => golden.id, "agent" => golden.agent,
+             "conv" => conv, "stop" => run.stop.to_s, "turns" => run.turns, "error" => run.error,
+             "persona" => golden.persona.to_h, "transcript" => run.transcript }
+  if verdict
+    report["judge"] = { "score" => verdict.score, "pass" => verdict.pass, "reason" => verdict.reason }
+    # A split panel must be visible in the report (the whole point of a panel
+    # over a lone judge): one entry per judge model, in settings order.
+    report["judge"]["judges"] = verdict.judges if verdict.judges
+  end
+  report["pairwise"] = { "outcome" => pairwise.outcome, "vs" => pairwise.vs, "reason" => pairwise.reason } if pairwise
+  puts simulate_markdown(report, verdict, pairwise)
+  if opts[:out]
+    FileUtils.mkdir_p(File.dirname(File.expand_path(opts[:out])))
+    File.write(opts[:out], JSON.pretty_generate(report))
+    puts "report: #{opts[:out]}"
+  end
+  exit(run.stop == :error || (verdict && !verdict.pass) ? 1 : 0)
+rescue Insika::Evals::PersonaLoader::InvalidPersona, Insika::Evals::GoldenLoader::InvalidGolden,
+       Insika::Evals::Simulator::UnsafeTarget => e
+  warn "insika evals:simulate: #{e.message}"
+  exit 2
+end
+
+# --persona: a case YAML carrying a `persona:` key (the alternative
+# shape). A case without turns but with a persona is the only thing this CLI
+# drives — a scripted case has nothing to simulate.
+def load_sim_persona(path)
+  raw = YAML.safe_load(File.read(path), permitted_classes: [], aliases: false) || {}
+  golden = Insika::Evals::GoldenLoader.build(raw, source: path)
+  raise Insika::Evals::GoldenLoader::InvalidGolden, "#{path}: needs a `persona:` (a simulated case)" unless golden.simulated?
+
+  golden
+rescue Errno::ENOENT => e
+  raise Insika::Evals::GoldenLoader::InvalidGolden, e.message
+end
+
+# The safety gate for a run. --staging is a straight declaration. --eval-profile
+# is a VERIFIED one: the CLI derives the target's side-effect tools (see
+# derive_side_effect_tools) and refuses unless the operator's --eval-tools names
+# every one of them — an eval profile that leaves a side-effect tool unswapped is
+# a lie, and a bare `--eval-profile` on a write-capable agent is exactly the
+# trust-me flag the docs promise is not what happens.
+def build_sim_safety(opts, golden, target_agent, a2a_target)
+  return Insika::Evals::Simulator::Safety.staging if opts[:staging]
+
+  declared = opts[:eval_tools].to_s.split(",").map(&:strip).reject(&:empty?)
+  derived = if a2a_target
+              nil # a remote A2A agent has no reachable registry — the list must be declared
+            else
+              derive_side_effect_tools(opts, target_agent)
+            end
+
+  if derived
+    uncovered = derived - declared
+    unless uncovered.empty?
+      abort "insika evals:simulate: --eval-profile, but the target's derived side-effect " \
+            "tool(s) (#{uncovered.join(', ')}) are not declared in --eval-tools — an eval " \
+            "profile must swap EVERY side-effect tool (or use --staging)"
+    end
+  elsif declared.empty?
+    abort "insika evals:simulate: cannot derive the target's side-effect tools (no " \
+          "/v1/agents/:id answer and no local store) — declare the swap list explicitly " \
+          "with --eval-tools, or use --staging"
+  end
+
+  Insika::Evals::Simulator::Safety.new(eval_profile: true, side_effect_tools: derived || [],
+                                       swapped_tools: declared)
+end
+
+# The target's side-effect tools — DERIVED, never hand-typed into the safety
+# gate. -> [names] | nil when derivation is impossible. Local store first (the
+# definitive answer when INSIKA_DB points at the deployment); otherwise the
+# deployment's own registry over GET /v1/agents/:id (`side_effect_tools` — the
+# server computes it from the same allowlist − deny resolution the capability
+# view uses).
+def derive_side_effect_tools(opts, agent)
+  local = local_side_effect_tools(agent)
+  return local unless local.nil?
+
+  capabilities = Insika::Evals::HttpCapabilities.new(base_url: opts[:base_url], token: opts[:token])
+  answer = capabilities.for(agent)
+  answer && !answer["side_effect_tools"].nil? ? Array(answer["side_effect_tools"]).map(&:to_s) : nil
+end
+
+# Derivation from the local store (INSIKA_DB set): the profile's reachable set
+# intersected with the store-backed overlay registry's side-effect marks. nil
+# when there is no store or the agent is not in it.
+def local_side_effect_tools(agent)
+  db = Insika::EnvSchema.read("INSIKA_DB", ENV)
+  return nil if db.nil? || db.empty?
+
+  backend = Insika::Wiring::Graph.backend_from_env
+  config_store = Insika::ConfigStore.new(store: backend)
+  profile = Insika::StoredProfileSource.new(config_store: config_store).fetch(agent)
+  return nil if profile.nil?
+
+  registry = Insika::OverlayToolRegistry.new(
+    base: Insika::ToolRegistry.new, tool_store: Insika::ToolStore.new(config_store: config_store),
+    http: Insika::HttpClient.new
+  )
+  Insika::Evals::EvalProfile.side_effect_tools(profile, registry)
+end
+
+# One place for the CLI's provider keys. Every synchronous CLI command that
+# builds its own extractor/miner/judge ask (no full app boot, so LlmConfigurator
+# never ran) calls this first — a judge panel is only as multi-model as the keys
+# this block wires: a settings panel pointing at OpenRouter models silently
+# 401'd here while the engine (LlmConfigurator) knew the key all along.
+def configure_cli_llm!
+  require "ruby_llm"
+  RubyLLM.configure do |c|
+    c.deepseek_api_key = ENV["DEEPSEEK_API_KEY"] if ENV["DEEPSEEK_API_KEY"]
+    c.openai_api_key = ENV["OPENAI_API_KEY"] if ENV["OPENAI_API_KEY"]
+    c.openai_api_base = ENV["OPENAI_API_BASE"] if ENV["OPENAI_API_BASE"]
+    c.openrouter_api_key = ENV["OPENROUTER_API_KEY"] if ENV["OPENROUTER_API_KEY"]
+    c.gemini_api_key = ENV["GEMINI_API_KEY"] if ENV["GEMINI_API_KEY"]
+  end
+end
+
+# The persona MODEL — the cheap side that plays the customer. Defaults to the
+# platform `utility_model` (the same setting the judges and the moderator read);
+# --persona-model overrides. Refuses when neither is set: never guess a model to
+# spend money on (the proposer's rule, applied to the cheap side too).
+def build_persona_ask(opts, settings)
+  model = opts[:persona_model] || settings["utility_model"]
+  abort "insika evals:simulate: no persona model — set the platform utility_model or pass --persona-model" if model.to_s.empty?
+
+  configure_cli_llm!
+  # ruby_llm_ask runs with assume_model_exists, which requires an explicit
+  # provider — a bare model id (e.g. a platform utility_model outside the
+  # RubyLLM registry) aborted every simulated run before this fallback.
+  provider = ENV["EVAL_PERSONA_PROVIDER"] || settings["default_provider"]
+  Insika::Evals::JudgePanel.ruby_llm_ask(model, provider)
+end
+
+def build_sim_judge(opts, settings)
+  models = if opts[:judge_model]
+             [{ "model" => opts[:judge_model], "provider" => opts[:judge_provider] }]
+           else
+             Array(settings["evals"] && settings["evals"]["judges"])
+           end
+  return nil if models.reject { |m| (m["model"] || m[:model]).to_s.empty? }.empty?
+
+  configure_cli_llm!
+  Insika::Evals::JudgePanel.build(settings["evals"] || {}, overrides: {
+                                    "judge_model" => opts[:judge_model], "judge_provider" => opts[:judge_provider]
+                                  })&.first
+end
+
+# The pairwise judge — the SAME configured panel, asked which conversation served
+# the customer better. Same opt-in as a replay's --pairwise (2 calls per judge).
+def build_sim_pairwise(opts, settings)
+  models = if opts[:judge_model]
+             [{ "model" => opts[:judge_model], "provider" => opts[:judge_provider] }]
+           else
+             Array(settings["evals"] && settings["evals"]["judges"])
+           end
+  return nil if models.reject { |m| (m["model"] || m[:model]).to_s.empty? }.empty?
+
+  configure_cli_llm!
+  Insika::Evals::JudgePanel.pairwise(settings["evals"] || {}, overrides: {
+                                       "judge_model" => opts[:judge_model], "judge_provider" => opts[:judge_provider]
+                                     })&.first
+end
+
+# --target <agent|url>: an agent id rides HttpTransport over the deployment's
+# /v1/responses (the same surface the replay uses); a full http(s) URL is an A2A
+# endpoint (an agent that only speaks A2A) driven by the thin A2A transport. The
+# A2A client is built with a SYNCHRONOUS Net::HTTP adapter (the CLI has no
+# reactor) — `post_json(url, body) -> Hash` is the client's whole contract.
+#
+# POLLING: the A2A client's default cadence (0.02s, 30 polls = ~0.6s total) is
+# for in-process loopback. A remote agent takes SECONDS to finish a task, so the
+# CLI polls once per second, bounded by --timeout (the same flag the HTTP
+# transport's read timeout honors).
+def build_sim_transport(opts)
+  target = opts[:target]
+  if target.to_s.match?(%r{\Ahttps?://})
+    require_relative "../lib/insika/server/a2a/client"
+    require_relative "../lib/insika/server/a2a/message"
+    require "net/http"
+    require "uri"
+    cadence = 1.0
+    client = Insika::Server::A2A::Client.new(
+      http: SyncPostJson.new,
+      poll_max: [opts[:timeout].to_i, 1].max,
+      sleeper: ->(_delay) { sleep(cadence) }
+    )
+    Insika::Evals::A2ATransport.new(client: client, url: target)
+  else
+    Insika::Evals::HttpTransport.new(base_url: opts[:base_url], token: opts[:token], timeout: opts[:timeout])
+  end
+end
+
+# A synchronous A2A JSON-RPC HTTP adapter for the CLI (no async reactor). The A2A
+# client calls `post_json(url, body) -> Hash`; this answers it over Net::HTTP. An
+# unreachable host or a non-JSON body becomes a clean `{ "error" => ... }` envelope —
+# the A2A client turns that into a turn error, never a crash.
+class SyncPostJson
+  def post_json(url, body)
+    uri = URI.parse(url)
+    req = Net::HTTP::Post.new(uri)
+    req["Content-Type"] = "application/json"
+    req["Accept"] = "application/json"
+    req.body = body.is_a?(String) ? body : JSON.generate(body)
+    res = Net::HTTP.start(uri.host, uri.port, use_ssl: uri.scheme == "https",
+                                             open_timeout: 10, read_timeout: 120) { |http| http.request(req) }
+    JSON.parse(res.body.to_s)
+  rescue StandardError => e
+    { "error" => { "code" => -32_600, "message" => "A2A call failed: #{e.class}: #{e.message}" } }
+  end
+end
+
+def eval_settings_from_env
+  db = Insika::EnvSchema.read("INSIKA_DB", ENV)
+  return {} if db.nil? || db.empty?
+
+  Insika::SettingsStore.new(config_store: Insika::ConfigStore.new(store: Insika::Stores::SQLite.new(path: db))).get
+rescue StandardError
+  {}
+end
+
+def simulate_markdown(report, verdict, pairwise = nil)
+  lines = ["# Simulated run — #{report['id']} (#{report['agent']})", "",
+           "**simulated: true** · stop: #{report['stop']}#{" (turn #{report['turns']})" if report['turns']}" \
+           "#{" · error: #{report['error']}" if report['error']}", ""]
+  report["transcript"].each do |m|
+    role = m[:role].to_s == "user" ? "customer" : "assistant"
+    lines << "**#{role}**"
+    lines << m[:text].to_s.empty? ? "  _#{m[:error] || 'no reply'}_" : "  #{m[:text]}"
+    lines << "  _tools: #{m[:tools].join(', ')}_" if m[:tools] && !m[:tools].empty?
+  end
+  lines << ""
+  if verdict
+    lines << "**judge: #{verdict.pass ? '✅' : '❌'} #{verdict.score}** — #{verdict.reason}"
+  else
+    lines << "_(no judge configured — transcript only)_"
+  end
+  if pairwise
+    mark = { "better" => "🟢", "comparable" => "🟡", "worse" => "🔴" }.fetch(pairwise.outcome, "·")
+    lines << "**vs incumbent (#{pairwise.vs}): #{mark} #{pairwise.outcome}** — #{pairwise.reason}"
+  end
+  "#{lines.join("\n")}\n"
+end
+
+    # insika mcp list|add|remove|import|test|refresh
+    def mcp(argv)
+      sub = argv.shift
+      case sub
+      when "list"    then mcp_list
+      when "add"     then mcp_add(argv)
+      when "remove"  then mcp_remove(argv)
+      when "import"  then mcp_import(argv)
+      when "test"    then mcp_run(argv, verb: "test", persist_label: nil)
+      when "refresh" then mcp_run(argv, verb: "refresh", persist_label: "cached")
+      else
+        warn "insika mcp: unknown subcommand '#{sub}' (list|add|remove|import|test|refresh)"
+        exit 2
+      end
+    rescue Insika::Error => e
+      warn "insika mcp: #{e.message}"
+      exit 2
+    end
+
+    def mcp_list
+      store = mcp_store
+      names = store.names
+      return puts("no MCP instances configured (insika mcp add / insika mcp import FILE.json)") if names.empty?
+
+      names.each do |name|
+        r = store.get(name)
+        status = r["enabled"] ? "enabled" : "disabled"
+        target = r["transport"] == "stdio" ? r["command"].to_s : r["url"].to_s
+        puts format("%-20s %-8s %-8s %-40s %d tool(s)", name, r["transport"], status, target, Array(r["tools_cache"]).size)
+      end
+    end
+
+    def mcp_add(argv)
+      opts = { args: [], headers: {}, env: {}, enabled: true }
+      OptionParser.new do |o|
+        o.banner = "Usage: insika mcp add --name NAME [--transport stdio|http|sse] [options]"
+        o.on("--name NAME", "instance name (required)") { |v| opts[:name] = v }
+        o.on("--transport T", "stdio|http|sse (default: stdio with --command, else http)") { |v| opts[:transport] = v }
+        o.on("--command CMD", "stdio: the executable") { |v| opts[:command] = v }
+        o.on("--arg ARG", "stdio: one argv entry (repeatable)") { |v| opts[:args] << v }
+        o.on("--url URL", "http/sse: the server URL") { |v| opts[:url] = v }
+        o.on("--header 'Name: value'", "http/sse: one header (repeatable)") do |v|
+          k, val = v.split(":", 2)
+          opts[:headers][k.to_s.strip] = val.to_s.strip
+        end
+        o.on("--env 'KEY=value'", "stdio: one env var (repeatable)") do |v|
+          k, val = v.split("=", 2)
+          opts[:env][k.to_s.strip] = val.to_s.strip
+        end
+        o.on("--description DESC", "free text") { |v| opts[:description] = v }
+        o.on("--disabled", "create it disabled") { opts[:enabled] = false }
+      end.parse!(argv)
+      raise Insika::ValidationError, "--name is required" if opts[:name].nil?
+
+      opts[:transport] ||= Insika::Coercion.presence(opts[:command]) ? "stdio" : "http"
+      record = mcp_store.upsert(opts)
+      puts "MCP instance '#{record['name']}' saved (#{record['transport']}, #{record['enabled'] ? 'enabled' : 'disabled'})"
+    end
+
+    def mcp_remove(argv)
+      name = argv.shift
+      raise Insika::ValidationError, "usage: insika mcp remove NAME" if name.nil?
+
+      existed = mcp_store.delete(name)
+      puts existed ? "MCP instance '#{name}' removed" : "MCP instance '#{name}' did not exist"
+    end
+
+    def mcp_import(argv)
+      path = argv.shift
+      raise Insika::ValidationError, "usage: insika mcp import FILE.json" if path.nil?
+      raise Insika::ValidationError, "no such file: #{path}" unless File.exist?(path)
+
+      records = Insika::McpJson.import(File.read(path), mcp_store: mcp_store)
+      puts "imported #{records.size} MCP instance(s) from #{path}"
+      records.each { |r| puts "  #{r['name']} (#{r['transport']})" }
+    end
+
+    # Shared by `test`/`refresh` — both connect live and list tools
+    # (Insika::McpToolRegistry#refresh always writes tools_cache; `test` differs
+    # only in what it prints). Exits 1 (not 2) on a
+    # connection/transport failure — the instance is configured correctly, the
+    # SERVER is unreachable, which is a finding, not a usage error. Rescues
+    # StandardError, not just Insika::Error: the registry's docstring is
+    # explicit that a transport failure is the GEM's error class (e.g.
+    # ruby_llm-mcp's own AuthenticationRequiredError) and it is this caller's
+    # job to turn it into a clean one-liner instead of a raw backtrace.
+    def mcp_run(argv, verb:, persist_label:)
+      name = argv.shift
+      raise Insika::ValidationError, "usage: insika mcp #{verb} NAME" if name.nil?
+
+      tools = mcp_registry.refresh(name)
+      suffix = persist_label ? ", #{persist_label}" : ""
+      puts "MCP instance '#{name}': connected, #{tools.size} tool(s)#{suffix}"
+      tools.each { |t| puts "  #{t['name']} — #{t['description']}" }
+    rescue StandardError => e
+      warn "MCP instance '#{name}': #{e.message}"
+      exit 1
+    end
+
+    # insika new --list | insika new <template> [dir]
+    def new_from_template(argv)
+      if argv.first == "--list"
+        new_list
+      else
+        new_copy(argv)
+      end
+    rescue Insika::Error => e
+      warn "insika new: #{e.message}"
+      exit 2
+    end
+
+    def new_list
+      entries = Insika::Templates.all
+      return puts("no templates available") if entries.empty?
+
+      entries.each { |t| puts format("%-18s %-10s %s", t.name, t.trail, t.description) }
+    end
+
+    # Copies the template's directory verbatim (agent.rb + README.md) — no
+    # rewriting, the generated script IS the editing surface. Prints the
+    # exact run line, including any env the template needs SET (not just
+    # available as an override, like MCP_URL's keyless default) — the
+    # EgressGuard/stdio-gate failure is silent otherwise, same discipline as
+    # the `mcp add`/data-tool egress hints elsewhere in this CLI.
+    def new_copy(argv)
+      name = argv.shift
+      raise Insika::ValidationError, "usage: insika new <template> [dir] (see insika new --list)" if name.nil?
+
+      entry = Insika::Templates.read(name)
+      dest = argv.shift || "./#{name}"
+      raise Insika::ValidationError, "already exists: #{dest}" if File.exist?(dest)
+
+      FileUtils.mkdir_p(dest)
+      FileUtils.cp(Insika::Templates.agent_path(name), File.join(dest, "agent.rb"))
+      readme = Insika::Templates.readme_path(name)
+      FileUtils.cp(readme, File.join(dest, "README.md")) if File.file?(readme)
+
+      puts "Created #{dest}/ (#{entry.title})"
+      puts
+      puts "Run it:"
+      env_flags = entry.env.map { |e| "#{e}=1" }.join(" ")
+      env_flags = "#{env_flags} " unless env_flags.empty?
+      puts "  #{env_flags}DEEPSEEK_API_KEY=sk-... ruby #{dest}/agent.rb"
+      puts "\nRequires: #{entry.requires}" if entry.requires
+    end
+
+    # insika demo:seed [--force]
+    #
+    # Populates the "demo-store" agent with enough data to see every Studio
+    # loop working at once: a funnel with a frozen baseline, follow-ups in
+    # all four states, refinement runs across the lifecycle, pending +
+    # resolved approvals, distillation proposals/facts, and a golden set
+    # with a baseline (Insika::Demo::Seeder — the same object the Studio's
+    # "Seed demo data" button dispatches). Safe against a live volume: it
+    # only ever touches the demo agent's own records, and is a no-op on a
+    # second run unless --force asks for another batch.
+    def demo_seed(argv)
+      opts = { force: false }
+      OptionParser.new do |o|
+        o.banner = "Usage: insika demo:seed [--force]"
+        o.on("--force", "seed again even if the demo agent already exists") { opts[:force] = true }
+      end.parse!(argv)
+
+      backend = Insika::Wiring::Graph.backend_from_env
+      config_store = Insika::ConfigStore.new(store: backend)
+      profiles = Insika::StoredProfileSource.new(config_store: config_store)
+      seeder = Insika::Demo::Seeder.new(
+        profiles: profiles, store: backend,
+        session_store: Insika::SessionStore.new(store: backend),
+        task_store: Insika::TaskStore.new(store: backend),
+        outcome_store: Insika::OutcomeStore.new(store: backend),
+        funnel_store: Insika::FunnelStore.new(store: backend),
+        followup_store: Insika::FollowupStore.new(store: backend),
+        refinement_store: Insika::RefinementStore.new(store: backend),
+        pending_action_store: Insika::PendingActionStore.new(store: backend),
+        proposal_store: Insika::ProposalStore.new(store: backend),
+        memory_store: Insika::MemoryStore.new(store: backend),
+        golden_store: Insika::GoldenStore.new(config_store: config_store),
+        baseline_store: Insika::BaselineStore.new(config_store: config_store),
+        event_stream: Insika::EventStream.new
+      )
+      result = seeder.seed!(force: opts[:force])
+
+      unless result[:seeded]
+        warn "insika demo:seed: already seeded (#{result[:reason]}) — pass --force to seed again."
+        return
+      end
+
+      puts "seeded demo agent '#{result[:agent]}':"
+      result[:counts].each { |area, n| puts "  #{area}: #{n}" }
+      puts "\nOpen /studio/funnel?agent=#{result[:agent]} (also /studio/followups, " \
+           "/studio/refinement, /studio/approvals, /studio/harvest, /studio/evals) in " \
+           "whichever Studio instance points at this INSIKA_DB."
+    rescue Insika::Error => e
+      warn "insika demo:seed: #{e.message}"
+      exit 2
+    end
+
     # -- helpers -------------------------------------------------------
 
+    def mcp_store
+      backend = Insika::Wiring::Graph.backend_from_env
+      Insika::McpStore.new(config_store: Insika::ConfigStore.new(store: backend))
+    end
+
+    def mcp_registry
+      Insika::McpToolRegistry.new(mcp_store: mcp_store)
+    end
+
     def baseline_store
       backend = Insika::Wiring::Graph.backend_from_env
       Insika::BaselineStore.new(config_store: Insika::ConfigStore.new(store: backend))
@@ -405,6 +993,102 @@ end
       exit 1
     end
 
+    # insika knowledge:backfill --agent ID [--since ISO8601] [--json]
+    #
+    # the recovery path (RFC's "re-scan, not a queue"): replays the agent's
+    # stored sessions through the SAME extractor a live turn's terminal hook
+    # uses. Writes nothing but the concepts themselves.
+    def knowledge_backfill(argv)
+      opts = { json: false }
+      OptionParser.new do |o|
+        o.banner = "Usage: insika knowledge:backfill --agent ID [options]"
+        o.on("--agent ID", "agent whose sessions to replay (required)") { |v| opts[:agent] = v }
+        o.on("--since ISO8601", "replay only sessions with turns from this instant on") { |v| opts[:since] = v }
+        o.on("--json", "emit the summary as JSON") { opts[:json] = true }
+      end.parse!(argv)
+
+      abort "insika knowledge:backfill: --agent is required" if Insika::Coercion.blank?(opts[:agent])
+
+      result = begin
+        run_knowledge_backfill(opts)
+      rescue Insika::Error, ArgumentError => e
+        warn "insika knowledge:backfill: #{e.message}"
+        exit 2
+      end
+      if opts[:json]
+        require "json"
+        puts JSON.pretty_generate(result)
+      else
+        puts knowledge_backfill_report(result)
+      end
+    end
+
+    # Builds the handler over the real durable backend — same "no app boot"
+    # rule as `doctor`/`harvest`: no DEEPSEEK, no seeding, no reactor.
+    def run_knowledge_backfill(opts)
+      configure_cli_llm!
+      backend = Insika::Wiring::Graph.backend_from_env
+      config_store = Insika::ConfigStore.new(store: backend)
+      profiles = Insika::StoredProfileSource.new(config_store: config_store)
+      handler = Insika::Commands::BackfillKnowledge.new(
+        profiles: profiles,
+        knowledge_store: Insika::KnowledgeStore.new(store: backend),
+        session_store: Insika::SessionStore.new(store: backend),
+        task_store: Insika::TaskStore.new(store: backend),
+        settings_store: Insika::SettingsStore.new(config_store: config_store),
+        event_stream: Insika::EventStream.new
+      )
+      handler.call(Insika::Command.build(:backfill_knowledge,
+                                         { agent: opts[:agent], since: opts[:since] }.compact, transport: :cli))
+    end
+
+    def knowledge_backfill_report(result)
+      return "knowledge:backfill: skipped (#{result[:skipped]})" unless result[:backfilled]
+
+      head = "knowledge:backfill: #{result[:concepts]} concept(s) learned from #{result[:sessions]} session(s)"
+      head += " — #{result[:conflicts]} conflict(s), needs a human" if result[:conflicts].to_i.positive?
+      dropped = result[:dropped].reject { |_k, v| v.to_i.zero? }
+      dropped.empty? ? head : "#{head} — dropped: #{dropped.map { |k, v| "#{k}: #{v}" }.join(', ')}"
+    end
+
+    # insika knowledge:export --agent ID [--out DIR] [--tenant T]
+    #
+    # writes one <name>.md per concept — the storage format IS the export
+    # format, so this is a dump, not a converter, for okf-gem/graphify to
+    # read directly. Safe to re-run: unlike evals:export's YAML.dump, there
+    # is nothing lossy here to guard with --force.
+    KNOWLEDGE_EXPORT_FORMATS = %w[md graphml].freeze
+
+    def knowledge_export(argv)
+      opts = { out: ".", format: "md" }
+      OptionParser.new do |o|
+        o.banner = "Usage: insika knowledge:export --agent ID [options]"
+        o.on("--agent ID", "agent whose concepts to export (required)") { |v| opts[:agent] = v }
+        o.on("--out DIR", "destination directory (default: current directory)") { |v| opts[:out] = v }
+        o.on("--tenant T", "explicit tenant scope (default: none)") { |v| opts[:tenant] = v }
+        o.on("--format FORMAT", "md (default, one file per concept) | graphml (one graph file)") { |v| opts[:format] = v }
+      end.parse!(argv)
+
+      abort "insika knowledge:export: --agent is required" if Insika::Coercion.blank?(opts[:agent])
+      unless KNOWLEDGE_EXPORT_FORMATS.include?(opts[:format])
+        abort "insika knowledge:export: --format must be #{KNOWLEDGE_EXPORT_FORMATS.join(' or ')} (got #{opts[:format].inspect})"
+      end
+
+      backend = Insika::Wiring::Graph.backend_from_env
+      store = Insika::KnowledgeStore.new(store: backend)
+      tenant = Insika::Coercion.presence(opts[:tenant])
+
+      if opts[:format] == "graphml"
+        FileUtils.mkdir_p(opts[:out])
+        path = File.join(opts[:out], "knowledge.graphml")
+        File.write(path, store.export_graphml(opts[:agent], tenant: tenant))
+        puts "exported the concept graph to #{path}"
+      else
+        paths = store.export_dir(opts[:agent], opts[:out], tenant: tenant)
+        puts "exported #{paths.size} concept(s) to #{opts[:out]}"
+      end
+    end
+
     def run_failed?(result)
       backend = Insika::Wiring::Graph.backend_from_env
       run = Insika::HarvestStore.new(store: backend).find_run(result[:run_id])
@@ -414,6 +1098,7 @@ end
     # Builds the handler over the real durable backend — same "no app boot" rule as
     # `doctor`: no DEEPSEEK, no seeding, no reactor.
     def run_harvest(opts)
+      configure_cli_llm!
       backend = Insika::Wiring::Graph.backend_from_env
       config_store = Insika::ConfigStore.new(store: backend)
       profiles = Insika::StoredProfileSource.new(config_store: config_store)
@@ -483,6 +1168,41 @@ end
       "last #{n} session(s)"
     end
 
+    # insika tools:report [--agent ID] [--days N] [--json]
+    #
+    # The tool audit: reads the SAME durable backend as `doctor` (tasks →
+    # sessions → tool_traces), no app boot. Read-only — it names never-called
+    # allowlisted tools, high-error tools and stale tools; the operator removes.
+    def tools_report(argv)
+      opts = { json: false, days: Insika::ToolUsageReport::WINDOW_DAYS }
+      OptionParser.new do |o|
+        o.banner = "Usage: insika tools:report [--agent ID] [--days N] [--json]"
+        o.on("--agent ID", "narrow the report to one stored agent") { |v| opts[:agent] = v }
+        o.on("--days N", Integer, "window for error-rate and staleness (default #{opts[:days]})") { |v| opts[:days] = v }
+        o.on("--json", "emit the report as JSON") { opts[:json] = true }
+      end.parse!(argv)
+
+      backend = Insika::Wiring::Graph.backend_from_env
+      config_store = Insika::ConfigStore.new(store: backend)
+      report = Insika::ToolUsageReport.new(
+        task_store: Insika::TaskStore.new(store: backend),
+        tool_trace_store: Insika::ToolTraceStore.new(store: backend),
+        profile_source: Insika::StoredProfileSource.new(config_store: config_store)
+      ).generate(days: opts[:days], agent: opts[:agent])
+
+      if opts[:agent] && report.agents.empty?
+        warn "insika tools:report: no stored agent '#{opts[:agent]}'"
+        exit 2
+      end
+
+      if opts[:json]
+        require "json"
+        puts JSON.pretty_generate(report.to_h)
+      else
+        puts report.to_s
+      end
+    end
+
     # Config stores over the real durable backend — no app boot / no DEEPSEEK.
     def build_doctor
       backend = Insika::Wiring::Graph.backend_from_env
@@ -532,6 +1252,9 @@ end
         # CLI reports declarations only).
         followup_store: Insika::FollowupStore.new(store: backend),
         contact_store: Insika::ContactStore.new(store: backend),
+        # the schedules check reads the rows over the same runtime
+        # backend (nil = the CLI reports declarations only).
+        schedule_store: Insika::ScheduleStore.new(store: backend),
         # the distillation check reads the proposal store over
         # the same runtime backend (nil = the CLI reports declarations only).
         proposal_store: Insika::ProposalStore.new(store: backend),
@@ -544,6 +1267,8 @@ end
         rescue Insika::ConfigError, Insika::ValidationError
           nil
         end,
+        # the mcp check reads the instances over the same runtime backend.
+        mcp_store: Insika::McpStore.new(config_store: config_store),
         backend: backend
       )
     end