insika 0.3.0 → 0.7.0

data/lib/insika/mcp_tool_registry.rb

@@ -0,0 +1,100 @@
+# frozen_string_literal: true
+
+module Insika
+  # LIVE MCP tools — kills the McpToolIngestor snapshot.
+  #
+  # `entries` is CHEAP: it reads only McpStore#tools_cache (no I/O), the same
+  # contract the ToolStore-backed dynamic entries already give
+  # OverlayToolRegistry — Policy recomputes `candidate_tools` every turn, so
+  # an unreachable MCP server must never add real latency there.
+  #
+  # `refresh` is the ONLY thing that talks to a server ahead of time: it
+  # connects, lists live, and writes the result back to tools_cache (display/
+  # doctor). Calling a tool never depends on that cache — Insika::McpLiveTool
+  # always goes through the live, memoized client (and RubyLLM::MCP::Client
+  # does its own real `tools/list` on ITS first use per instance, regardless
+  # of whether `refresh` ever ran).
+  class McpToolRegistry
+    def initialize(mcp_store:, client_factory: Insika::McpClient.method(:for))
+      @mcp_store = mcp_store
+      @client_factory = client_factory
+      @clients = {}
+      @mutex = Mutex.new
+    end
+
+    # -> [Registry::Entry] one per cached tool of every ENABLED instance.
+    def entries
+      @mcp_store.all_raw.select { |r| r["enabled"] }.flat_map { |r| entries_for(r) }
+    end
+
+    # Connects to `name` LIVE, lists its tools, and writes McpStore#tools_cache.
+    # ALWAYS drops any memoized client first and rebuilds from the current
+    # record: a stdio process can be `alive?` (still running) yet permanently
+    # broken (e.g. wrong transport args — see grafana-stg gotcha), and an
+    # edited command/url/env must take effect without a process restart —
+    # there's no SSH into a Railway dyno to do that by hand.
+    # -> the discovered [{"name","description","inputSchema"}]. Raises on a
+    # missing/disabled instance or a transport failure — the caller (a CLI
+    # verb/API route/UI button, PR3/PR4) decides how to surface it.
+    def refresh(name)
+      record = @mcp_store.get_raw(name.to_s)
+      raise Insika::NotFoundError, "MCP instance '#{name}' not found" if record.nil?
+      raise Insika::ValidationError, "MCP instance '#{name}' is disabled" unless record["enabled"]
+
+      evict(record["name"])
+      client = client_for(record)
+      discovered = client.tools.map { |t| { "name" => t.name, "description" => t.description, "inputSchema" => t.params_schema } }
+      @mcp_store.set_tools_cache(name, discovered)
+      discovered
+    end
+
+    # Stops and drops any memoized client for `name` (no-op if none), so the
+    # next `client_for` builds a fresh one off the current record. Public:
+    # called by `refresh` above AND by UpsertMcp/DeleteMcp right after they
+    # write the store — a Studio/CLI edit takes effect on that instance's
+    # NEXT tool call or refresh, no process restart required (there's no way
+    # to restart a process by hand on a Railway dyno).
+    def evict(name)
+      client = @mutex.synchronize { @clients.delete(name.to_s) }
+      client&.stop
+    rescue StandardError
+      nil # best-effort teardown of a possibly already-dead process
+    end
+
+    private
+
+    def entries_for(record)
+      Array(record["tools_cache"]).map { |tool| entry_for(record, tool) }
+    end
+
+    def entry_for(record, tool)
+      instance = record["name"]
+      Insika::Registry::Entry.new(
+        name: tool["name"], plugin: "mcp:#{instance}",
+        metadata: { optional: false, side_effect: true, group: "mcp:#{instance}", tags: [] },
+        factory: -> { build_tool(record, tool) }
+      )
+    end
+
+    # Lazy require (McpLiveTool < RubyLLM::Tool pulls in ruby_llm) — kept out
+    # of insika.rb load-time, loaded on the 1st instance (turn time), same
+    # discipline as OverlayToolRegistry#build_tool for data-tools.
+    def build_tool(record, tool)
+      require_relative "mcp_live_tool"
+      Insika::McpLiveTool.new(instance_name: record["name"], tool: tool, client_for: -> { client_for(record) })
+    end
+
+    # A started, MEMOIZED client for `record` — one real connection per
+    # instance name, reused across calls/turns. Raises on a gated/unreachable
+    # instance; only called from `refresh` and from a running McpLiveTool's
+    # `#execute` (which rescues) — never from `entries`/`build_tool`, so a
+    # downed server never breaks turn ASSEMBLY, only that tool's own call.
+    def client_for(record)
+      @mutex.synchronize do
+        client = (@clients[record["name"]] ||= @client_factory.call(record))
+        client.start unless client.alive?
+        client
+      end
+    end
+  end
+end

data/lib/insika/media.rb

@@ -3,28 +3,31 @@
 module Insika
   # WS9: the engine transports MEDIA, never meaning. Content parts ride the
   # message contract — `{ "type": "text", "text": … }`, `{ "type": "image",
-  # "url": … }`, `{ "type": "audio", "url": … }` — and the Executor turns them
-  # into a turn: audio is transcribed (text marked `source: :voice`), images
-  # attach to the model ask and the first URL is `{{ctx.image_url}}` for
-  # data/HTTP tools. This class owns the PURE parts (normalization) and
-  # the STT SEAM (injectable — specs stub it; the default fetches the audio and
-  # transcribes via RubyLLM behind a lazy require, so the core stays gem-free
-  # at load). `Media::Output` is the generated-media half (WS9, saída): the
-  # turn can PRODUCE an image or an audio clip when the agent opted in
-  # (`AgentProfile#outputs`) AND the channel declared it can receive it
-  # (`channel.capabilities`) — nothing leaks by default.
+  # "url": … }`, `{ "type": "audio", "url": … }`, `{ "type": "document",
+  # "url": … }` — and the Executor turns them into a turn: audio is
+  # transcribed (text marked `source: :voice`), images and documents attach
+  # to the model ask and the first URL of each kind is `{{ctx.image_url}}` /
+  # `{{ctx.document_url}}` for data tools. This class owns the PURE parts
+  # (normalization) and the STT SEAM (injectable — specs stub it; the default
+  # fetches the audio and transcribes via RubyLLM behind a lazy require, so
+  # the core stays gem-free at load). `Media::Output` is the generated-media
+  # half (WS9, saída): the turn can PRODUCE an image or an audio clip when the
+  # agent opted in (`AgentProfile#outputs`) AND the channel declared it can
+  # receive it (`channel.capabilities`) — nothing leaks by default.
   module Media
     # A single content part, normalized.
     Part = Data.define(:type, :text, :url) do
       def audio? = type == "audio"
       def image? = type == "image"
+      def document? = type == "document"
       def text? = type == "text"
     end
 
     # -> [Part]: normalize the raw parts (string|symbol keys), skipping anything
-    # that is not a well-formed text/image/audio part. Lenient on purpose — the
-    # SURFACE validates the contract with `well_formed?` (a malformed part is a
-    # 422 before dispatch); here a stray entry must not break the turn.
+    # that is not a well-formed text/image/audio/document part. Lenient on
+    # purpose — the SURFACE validates the contract with `well_formed?` (a
+    # malformed part is a 422 before dispatch); here a stray entry must not
+    # break the turn.
     def self.parts(raw)
       Array(raw).filter_map do |p|
         next unless p.is_a?(Hash)
@@ -34,24 +37,24 @@ module Insika
         text = (p[:text] || p["text"]).to_s
         case type
         when "text" then text.empty? ? nil : Part.new("text", text, nil)
-        when "image", "audio" then url.empty? ? nil : Part.new(type, nil, url)
+        when "image", "audio", "document" then url.empty? ? nil : Part.new(type, nil, url)
         else nil
         end
       end
     end
 
     # The SURFACE's contract check (server edge): true when EVERY entry is a
-    # well-formed content part — a Hash whose type is text (with text), image
-    # or audio (with url). The edge raises a 422 on the first offender; the
-    # engine itself stays lenient (`parts` skips strays so a non-HTTP transport
-    # that bypassed the edge cannot break a turn).
+    # well-formed content part — a Hash whose type is text (with text), image,
+    # audio or document (with url). The edge raises a 422 on the first
+    # offender; the engine itself stays lenient (`parts` skips strays so a
+    # non-HTTP transport that bypassed the edge cannot break a turn).
     def self.well_formed?(raw)
       Array(raw).all? do |p|
         next false unless p.is_a?(Hash)
 
         case (p[:type] || p["type"]).to_s
         when "text" then !(p[:text] || p["text"]).to_s.empty?
-        when "image", "audio" then !(p[:url] || p["url"]).to_s.empty?
+        when "image", "audio", "document" then !(p[:url] || p["url"]).to_s.empty?
         # a part WITHOUT a type is admitted only as a bare text part (the
         # shape the input joiner already tolerates) — anything else is refused.
         when "" then !(p[:text] || p["text"]).to_s.empty?
@@ -79,29 +82,75 @@ module Insika
     # so an uncapped one is a hostile URL away from growing it until it dies.
     MAX_AUDIO_BYTES = 1_000_000 # a voice note, not a warehouse
     MAX_IMAGE_BYTES = 5_000_000 # a photo, not a poster
+    MAX_DOCUMENT_BYTES = 10_000_000 # a prescription, not an archive
 
     def self.audio_parts(parts) = parts.select(&:audio?)
     def self.image_parts(parts) = parts.select(&:image?)
+    def self.document_parts(parts) = parts.select(&:document?)
 
     # The STT seam: ->(url) { text } (default: fetch + RubyLLM transcription).
     # Injected so a spec never touches the network; the default is built lazily
-    # when the turn first carries audio.
-    def self.default_transcriber(stt_model:, stt_language: nil)
+    # when the turn first carries audio. `stt_prompt` is the Whisper-family
+    # vocabulary hint (product names, brand terms) — OPERATOR config
+    # (agent profile / deployment env), never customer input.
+    def self.default_transcriber(stt_model:, stt_language: nil, stt_prompt: nil)
       lambda do |url|
-        fetch_and_transcribe(url, model: stt_model, language: stt_language)
+        fetch_and_transcribe(url, model: stt_model, language: stt_language, prompt: stt_prompt)
       end
     end
 
-    def self.fetch_and_transcribe(url, model:, language:)
+    # A file PATH, not bytes and not an Attachment: `RubyLLM::Transcription.
+    # transcribe` hands its argument to the PROVIDER's own `transcribe`, and the
+    # two shapes in this gem disagree — Gemini wraps it in `Attachment.new`
+    # itself (a raw byte String there is misread as a Pathname and blows up on
+    # any embedded null byte, which real audio has), while the DEFAULT
+    # `Provider#transcribe` (OpenAI, Mistral) calls `File.expand_path` on it
+    # directly and cannot take bytes/IO/Attachment at all. A tempfile is the
+    # one shape both accept. `assume_model_exists` is deliberately NOT passed:
+    # RubyLLM raises ArgumentError when it's true without an explicit
+    # `provider` (see ModelSelection#assume_model_exists?), and `stt_model` here
+    # is a bare ref like `utility_model` elsewhere — the registry resolves it.
+    def self.fetch_and_transcribe(url, model:, language:, prompt: nil)
       require "net/http"
       require "uri"
       require "ruby_llm" # lazy — the core loads without it (load-guard)
+      require "tempfile"
 
       bytes = fetch_binary(url)
-      audio = RubyLLM::Attachment.new(bytes)
-      options = { model: model, assume_model_exists: true }
+      options = { model: model }
       options[:language] = language if language
-      RubyLLM::Transcription.transcribe(audio, **options).text
+      options[:prompt] = prompt if prompt
+      Tempfile.create(["insika-media-", File.extname(filename_for(url).to_s)]) do |file|
+        file.binmode
+        file.write(bytes)
+        file.flush
+        RubyLLM::Transcription.transcribe(file.path, **options).text
+      end
+    end
+
+    # An inbound URL -> a RubyLLM::Attachment over bytes WE fetched (egress-
+    # guarded, size-capped — the `media_attachment` recipe). Shared by the
+    # Executor (inbound image/document parts) and `Output.generate_image`
+    # (edit sources / mask): an io-like source (StringIO) is the branch of
+    # Attachment that takes bytes already held, so the provider gets base64
+    # rather than the URL — handing the raw URL to RubyLLM instead would leave
+    # the (uncapped) fetch to the gem.
+    def self.url_attachment(url, max_bytes: MAX_IMAGE_BYTES)
+      require "ruby_llm"
+      require "stringio"
+
+      bytes = fetch_binary(url, max_bytes: max_bytes)
+      RubyLLM::Attachment.new(StringIO.new(bytes), filename: filename_for(url))
+    end
+
+    # The URL's basename, for the attachment's mime sniff (".png" -> image/png;
+    # a URL with no filename falls back to the content sniff RubyLLM does).
+    def self.filename_for(url)
+      require "uri"
+      name = File.basename(URI.parse(url).path.to_s)
+      name.empty? ? nil : name
+    rescue URI::InvalidURIError
+      nil
     end
 
     # Egress-guarded binary fetch of a media URL. Blocked like the webhook: the
@@ -166,6 +215,9 @@ module Insika
       # Base64 inlines into the envelope — a cap so a pathological generation
       # cannot blow up the SSE frame. A generated 1024x1024 PNG sits well under.
       MAX_EMBEDDED_BYTES = 8 * 1024 * 1024
+      # Edit sources on one `paint(with:)` call — a fitting room needs a
+      # handful of angles, not a gallery.
+      MAX_SOURCE_IMAGES = 4
 
       class << self
         # -> { image: seam, tts: seam } with the DEFAULTS bound to a context
@@ -179,17 +231,26 @@ module Insika
           }
         end
 
-        # -> [Part, usage]: paint via RubyLLM. usage is the provider's token
-        # counts ({ input_tokens:, output_tokens: } — merged into the turn's
-        # usage by the Executor); a provider without counts reports nothing.
+        # -> [Part, usage]: paint via RubyLLM — text-to-image when the config
+        # carries no sources (byte-identical to before this call), image
+        # EDITING when it does: `source_urls`/`source_attachments` ride
+        # `paint(with:)`, `mask_url` rides `paint(mask:)`. usage is the
+        # provider's token counts ({ input_tokens:, output_tokens: } — merged
+        # into the turn's usage by the Executor); a provider without counts
+        # reports nothing.
         def generate_image(prompt, config:, context:)
           require "ruby_llm" # lazy — the core loads without it (load-guard)
 
           cfg = Insika::Coercion.deep_stringify(config || {})
           model = Insika::Coercion.presence(cfg["model"]) || image_model(context)
+          # `assume_model_exists` is deliberately NOT passed: RubyLLM raises
+          # ArgumentError when it's true without an explicit `provider` (see
+          # ModelSelection#assume_model_exists?), and `model` here is a bare
+          # ref like `utility_model` elsewhere — the registry resolves it.
           api = context || RubyLLM
-          image = api.paint(prompt.to_s, model: model, assume_model_exists: true,
-                                          size: presence(cfg["size"]) || DEFAULT_IMAGE_SIZE)
+          image = api.paint(prompt.to_s, model: model,
+                                          size: presence(cfg["size"]) || DEFAULT_IMAGE_SIZE,
+                                          with: source_attachments(cfg), mask: mask_attachment(cfg))
           data = image.respond_to?(:data) ? image.data : nil
           raise Insika::MediaError, "image generation returned no embeddable data" if data.to_s.empty?
 
@@ -268,6 +329,29 @@ module Insika
           config.respond_to?(:default_image_model) ? config.default_image_model : nil
         end
 
+        # -> [Attachment] | nil: the edit sources for `paint(with:)`. Pre-built
+        # attachments win (the tool's DEFAULT source — the turn's own inbound
+        # images, already fetched bytes, no URL round-trip); otherwise explicit
+        # `source_urls` are fetched through the SAME capped, egress-guarded
+        # path images always used. nil (never []) when there are none — a
+        # provider without OpenAI's `editing?` leniency raises on a non-nil
+        # `with:`, and a text-to-image turn must stay byte-identical.
+        def source_attachments(cfg)
+          built = cfg["source_attachments"]
+          return built if built.is_a?(Array) && built.any?
+
+          urls = Array(cfg["source_urls"]).map(&:to_s).reject(&:empty?).first(MAX_SOURCE_IMAGES)
+          urls.empty? ? nil : urls.map { |u| Insika::Media.url_attachment(u, max_bytes: Insika::Media::MAX_IMAGE_BYTES) }
+        end
+
+        # -> Attachment | nil: the optional edit mask for `paint(mask:)`.
+        def mask_attachment(cfg)
+          url = presence(cfg["mask_url"])
+          return nil unless url
+
+          Insika::Media.url_attachment(url, max_bytes: Insika::Media::MAX_IMAGE_BYTES)
+        end
+
         def token_usage(raw)
           usage = raw.is_a?(Hash) ? raw : {}
           {

data/lib/insika/message_origin.rb

@@ -18,7 +18,7 @@ module Insika
   # Reading a transcript without that distinction is not a rounding error. The first
   # refinement run over real traffic reported `repetition ×219` on one agent: every
   # one of them the engine reading its own injected fragment back and calling it a
-  # customer repeating themselves (PR #133). That was filtered by a REGEX on the
+  # customer repeating themselves. That was filtered by a REGEX on the
   # leading tag, labelled in the code as a heuristic standing in for this field.
   #
   # ABSENT is the common case and stays valid forever: a message with no origin is

data/lib/insika/middleware.rb

@@ -26,6 +26,15 @@ module Insika
       @middlewares = middlewares
     end
 
+    # Appends a link at the END (innermost). This is the plugin Loader's
+    # registration seam ("collections that respond to <<") — it runs at boot,
+    # single-fiber, before the server accepts connections, so appending here
+    # never races a turn.
+    def <<(middleware)
+      @middlewares << middleware
+      self
+    end
+
     def call(state, &terminal)
       chain = @middlewares.reverse.reduce(terminal) do |nxt, mw|
         proc { |s| mw.call(s, &nxt) }

data/lib/insika/onboarding.rb

@@ -38,29 +38,45 @@ module Insika
       "readme" => "README.md",
       "why" => "docs/WHY.md",
       "agents" => "docs/AGENTS.md",
+      "policy" => "docs/POLICY.md",
       "tools" => "docs/TOOLS.md",
       "skills" => "docs/SKILLS.md",
       "context" => "docs/CONTEXT.md",
       "workflows" => "docs/WORKFLOWS.md",
       "channels" => "docs/CHANNELS.md",
       "plugins" => "docs/PLUGINS.md",
+      "templates" => "docs/TEMPLATES.md",
+      "media" => "docs/MEDIA.md",
       "security" => "docs/SECURITY.md",
       "architecture" => "docs/ARCHITECTURE.md",
       "running-local" => "docs/RUNNING-LOCAL.md",
       "deploy" => "docs/DEPLOY.md",
+      "router" => "docs/ROUTER.md",
       "embedding" => "docs/EMBEDDING.md",
       "sandbox" => "docs/SANDBOX.md",
       "benchmark" => "docs/BENCHMARK.md",
       "observability" => "docs/OBSERVABILITY.md",
+      "schedules" => "docs/SCHEDULING.md",
+      "artifacts" => "docs/ARTIFACTS.md",
+      "soak" => "docs/SOAK.md",
       "evals" => "docs/EVALS.md",
       "refinement" => "docs/REFINEMENT.md",
+      "outcomes" => "docs/OUTCOMES.md",
       "facts" => "docs/FACTS.md",
       "harvest" => "docs/HARVEST.md",
+      "knowledge" => "docs/KNOWLEDGE.md",
       "loadtest" => "docs/LOADTEST.md",
       "releasing" => "docs/RELEASING.md",
+      "demo" => "docs/DEMO.md",
       # the /v1 compatibility contract and the domain-free map.
       "api" => "docs/API.md",
-      "domain" => "docs/domain.md"
+      "domain" => "docs/domain.md",
+      # copy-paste journeys for the developer's coding agent (README "Or let your
+      # coding agent build it").
+      "run-examples" => "docs/prompts/RUN-EXAMPLES.md",
+      "add-tool" => "docs/prompts/ADD-TOOL.md",
+      "diagnose-turn" => "docs/prompts/DIAGNOSE-TURN.md",
+      "go-live" => "docs/prompts/GO-LIVE.md"
     }.freeze
 
     # Repo-relative path to the start.md template.

data/lib/insika/outcome_store.rb

@@ -14,7 +14,7 @@ module Insika
   #
   # The Studio's scorecard is the consumer: the LAST outcome per agent as a
   # pill on the grid, and the per-day series on the agent detail — both fed
-  # from the same store, no scheduler.
+  # from the same store, read on demand.
   class OutcomeStore
     SCOPE = "outcomes"
 

data/lib/insika/overlay_tool_registry.rb

@@ -2,47 +2,57 @@
 
 module Insika
   # DYNAMIC tool registry: composes the CODE registry (base, built at boot,
-  # immutable) with the DATA-DEFINED tools from the ToolStore. Drop-in for ToolRegistry —
-  # the Executor/ToolCatalog/ToolEnvelope only use entries/resolve/side_effect?.,
+  # immutable), the DATA-DEFINED tools from the ToolStore, and — optionally —
+  # the LIVE MCP tools from Insika::McpToolRegistry. Drop-in
+  # for ToolRegistry — the Executor/ToolCatalog/ToolEnvelope only use
+  # entries/resolve/side_effect?.
   #
   # Rules:
-  #   - COLLISION: the base (code) ALWAYS wins — a data-tool cannot hijack
-  #     the name of a code tool (security, R3). The authoring Command also
+  #   - COLLISION: the base (code) ALWAYS wins — a data-tool or an MCP tool
+  #     cannot hijack the name of a code tool (security, R3); a data-tool
+  #     also wins over an MCP tool of the same name (an operator-authored
+  #     definition over a server's own naming). The authoring Command also
   #     refuses to create with a colliding name (code_tool?), but the defense stays here.
   #   - HOT: `reload` re-reads the store and swaps the dynamic index atomically — a
   #     new/edited data-tool takes effect on the next turn without a restart, mirroring
-  #     SkillCatalog.reload. An in-flight turn has already captured the index.
-  # PARITY: empty ToolStore ⇒ entries/resolve/side_effect? identical to the
-  #     pure base. The base (config/wiring.rb) does not even use the overlay — zero regression.
+  #     SkillCatalog.reload. An in-flight turn has already captured the index. MCP
+  #     entries need no such reload — they read McpStore#tools_cache fresh every call
+  #     (no I/O, so there is nothing to memoize-then-invalidate).
+  # PARITY: empty ToolStore + no mcp_registry ⇒ entries/resolve/side_effect? identical
+  #     to the pure base. The base (config/wiring.rb) does not even use the overlay — zero regression.
   #
-  # The data-tools enter as NORMAL Registry::Entry (optional: false) — they obey
-  # the same per-agent allow/deny as code tools; exposure is the operator's
-  # (the /tools matrix), not automatic just because they are "data-defined".
+  # The data-tools and MCP tools enter as NORMAL Registry::Entry (optional:
+  # false) — they obey the same per-agent allow/deny as code tools; exposure
+  # is the operator's (the /tools matrix), not automatic just because they
+  # are "data-defined" or MCP-discovered.
   class OverlayToolRegistry
-    def initialize(base:, tool_store:, http:, egress: Insika::EgressGuard, egress_options: {}, event_stream: nil)
+    def initialize(base:, tool_store:, http:, egress: Insika::EgressGuard, egress_options: {}, event_stream: nil,
+                   mcp_registry: nil)
       @base = base
       @tool_store = tool_store
       @http = http
       @egress = egress
       @egress_options = egress_options
       @event_stream = event_stream
+      @mcp_registry = mcp_registry
     end
 
-    # Base + dynamic, except dynamic ones that collide with the base (base wins).
+    # Base + dynamic + mcp, except any that collide with something higher in
+    # the precedence (base > data-tools > mcp).
     def entries
-      @base.entries + dynamic.reject { |e| code_tool?(e.name) }
+      @base.entries + dynamic.reject { |e| code_tool?(e.name) } + mcp_entries
     end
 
     def names
-      (@base.names + dynamic.map(&:name)).uniq
+      (@base.names + dynamic.map(&:name) + mcp_entries.map(&:name)).uniq
     end
 
-    # -> instance (base wins) | raise NotFoundError.
+    # -> instance (base wins, then data-tools) | raise NotFoundError.
     def resolve(name)
       key = name.to_s
       return @base.resolve(key) if code_tool?(key)
 
-      entry = dynamic.find { |e| e.name == key }
+      entry = dynamic.find { |e| e.name == key } || mcp_entries.find { |e| e.name == key }
       raise Insika::NotFoundError, "'#{name}' not registered in #{self.class}" unless entry
 
       entry.factory.call
@@ -53,7 +63,7 @@ module Insika
       key = name.to_s
       return @base.side_effect?(key) if code_tool?(key)
 
-      entry = dynamic.find { |e| e.name == key }
+      entry = dynamic.find { |e| e.name == key } || mcp_entries.find { |e| e.name == key }
       entry ? !!entry.metadata[:side_effect] : false
     end
 
@@ -72,6 +82,16 @@ module Insika
       @dynamic ||= build_dynamic
     end
 
+    # No I/O (McpToolRegistry#entries only reads McpStore#tools_cache) ->
+    # recomputed fresh every call, unlike `dynamic` (nothing to reload).
+    # Drops anything already claimed by the base or a data-tool.
+    def mcp_entries
+      return [] unless @mcp_registry
+
+      claimed = @base.names + dynamic.map(&:name)
+      @mcp_registry.entries.reject { |e| claimed.include?(e.name) }
+    end
+
     def build_dynamic
       @tool_store.all_raw.filter_map { |raw| entry_for(raw) }
     end

data/lib/insika/packaging.rb

@@ -72,7 +72,7 @@ module Insika
         tracked = `git ls-files -z 2>/dev/null`.split("\x0")
         if tracked.empty?
           tracked = Dir.glob("{lib,docs}/**/*", File::FNM_DOTMATCH).reject { |f| File.directory?(f) } +
-                    %w[README.md LICENSE CHANGELOG.md bin/insika]
+                    %w[README.md LICENSE CHANGELOG.md bin/insika bin/insika-router]
         end
         tracked.select { |file| payload_path?(file) }.reject { |file| excluded?(file) }
       end
@@ -80,7 +80,7 @@ module Insika
 
     # -> bool: is this repo-relative path part of the payload selection?
     def payload_path?(file)
-      file.start_with?("lib/", "docs/") || %w[README.md LICENSE CHANGELOG.md bin/insika].include?(file)
+      file.start_with?("lib/", "docs/") || %w[README.md LICENSE CHANGELOG.md bin/insika bin/insika-router].include?(file)
     end
 
     # -> bool: is this file in the never-ship set?

data/lib/insika/profile_source.rb

@@ -119,6 +119,7 @@ module Insika
         routes: h[:routes],
         stuck_signal: h[:stuck_signal],
         outputs: h[:outputs],
+        stt_prompt: h[:stt_prompt],
         briefing_fields: h[:briefing_fields],
         # grounding profile data — a plain Hash read with string keys
         # by Insika::Grounding.parse per turn; nil round-trips as nil (= off).
@@ -148,7 +149,13 @@ module Insika
         distill: h[:distill],
         # harvest declaration — a plain Hash read with string keys
         # by the miner/engine/doctor; nil round-trips as nil (= loop off).
-        harvest: h[:harvest]
+        harvest: h[:harvest],
+        # knowledge declaration — a plain Hash read with string keys
+        # by the extractor/engine/doctor; nil round-trips as nil (= loop off).
+        knowledge: h[:knowledge],
+        # schedules declaration — an Array of Hashes read with string
+        # keys by the ScheduleEngine/doctor/Studio; nil round-trips as nil.
+        schedules: h[:schedules]
       )
     end
 

data/lib/insika/prompt_catalog.rb

@@ -30,6 +30,16 @@ module Insika
       self
     end
 
+    # Parity with SkillCatalog#add_roots: plugin prompt dirs join at the END
+    # (lowest precedence — a workspace prompt beats a plugin's same-named one).
+    def add_roots(dirs)
+      added = Array(dirs).map { |d| File.expand_path(d.to_s) } - @roots.map { |r| File.expand_path(r) }
+      return self if added.empty?
+
+      @roots.concat(added)
+      reload
+    end
+
     private
 
     def load_all