insika 0.1.0 → 0.2.0

data/lib/insika/server/responses.rb

@@ -4,9 +4,8 @@ require "json"
 
 module Insika
   module Server
-    # OpenAI Responses edge adapter (`/v1/responses`) — the contract that the
-    # OpenClaw gateway consumers already speak (see achei-b2b
-    # `CoreServices::OpenclawDispatcher`). Phase 6, Step A.
+    # OpenAI Responses edge adapter (`/v1/responses`) — the contract that
+    # OpenClaw gateway consumers already speak.
     #
     # PURE module (no state, no framework): (a) translates the OpenAI
     # Responses request → `:send_message` payload; (b) maps each turn Event →
@@ -26,7 +25,7 @@ module Insika
       # `origin` is the consumer declaring WHO wrote the input it is sending. It
       # matters here more than anywhere: this adapter's `input` is a STRING the
       # consumer already composed out of context blocks plus the customer's text
-      # (`<memoria> …`, `<cacau_cep_obrigatorio> …`), so a transcript reader cannot
+      # (`<memoria> …`, `<store_cep_required> …`), so a transcript reader cannot
       # tell the two apart — the first refinement run over real traffic reported 219
       # "the customer repeated themselves" that were the engine reading its own
       # fragment back. A consumer that sends `origin: "engine"` on a composed turn
@@ -84,8 +83,8 @@ module Insika
           # The provider's reasoning. Internal unless the AGENT opted in
           # (`edge_stream thinking: true`), which tags the event. Even then it does
           # NOT become answer text: it gets the Responses reasoning frame, so a
-          # consumer that only accumulates `output_text` deltas — achei-b2b's
-          # dispatcher, which turns them into one WhatsApp message — is unaffected,
+          # consumer that only accumulates `output_text` deltas — a dispatcher
+          # that turns them into one WhatsApp message — is unaffected,
           # and one that renders reasoning has something to render.
           if public_delta(event)
             sse("response.reasoning_summary_text.delta",
@@ -108,13 +107,19 @@ module Insika
                 { type: "insika.intermediate.delta", delta: event.data[:delta].to_s })
           end
         when :guardrail_blocked, :guardrail_flagged
-          # RFC-0009: audit events with no OpenAI Responses counterpart. On a BLOCK
+          # audit events with no OpenAI Responses counterpart. On a BLOCK
           # the safe reply still reaches the consumer through the normal :content
           # deltas + :task_completed path (the turn completes gracefully), so there
           # is nothing extra to translate here — the events live in /v1/events + the
           # Studio + the trace. Explicit (not a fall-through) to keep the closed
           # catalog honest.
           nil
+        when :ttft
+          # the live TTFB signal (WS6, INSIKA_TURN_TIMING opt-in): the provider's
+          # ms-to-first-token, emitted when the first content chunk arrives.
+          # Namespaced insika.* — no OpenAI Responses counterpart; unknown types
+          # are ignored, the safe failure.
+          sse("insika.ttft", { type: "insika.ttft", ttft_ms: event.data[:ttft_ms].to_i })
         end
       end
 
@@ -133,9 +138,14 @@ module Insika
           response[:usage] = usage.reject { |k, _| k.to_s == "model" }
           response[:model] = model if model
         end
-        # Opt-in per-turn latency breakdown (INSIKA_TURN_TIMING; item 34). Absent
+        # Opt-in per-turn latency breakdown (INSIKA_TURN_TIMING). Absent
         # by default — a non-standard sibling used only for TTFB diagnostics.
         (timing = event.data[:timing]) && (response[:timing] = timing)
+        # WS5 stuck signal: an additive sibling the terminal frame carries when the
+        # agent ended the turn declaring it cannot proceed. Consumers that only read
+        # the OpenAI-shaped response.use it to run their escalation ("stuck" means
+        # what they decide it means, never the engine's business).
+        (outcome = event.data[:outcome]) && (response[:outcome] = outcome.to_s)
         sse("response.completed", { type: "response.completed", response: response })
       end
 

data/lib/insika/server/tenant_auth.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+require "rack"
+require "rack/utils"
+
+module Insika
+  module Server
+    # Edge resolution for WS1 (multi-tenant): `Authorization: Bearer <token>` ->
+    # a principal `{ role:, tenant_id: }`, resolved BEFORE the routes. Two modes,
+    # one gate:
+    #
+    #   single_tenant (default) — no token store: the classic single operator
+    #     credential (config[:gateway_token]) is the only thing that resolves.
+    #   multi_tenant — tokens live in the TokenStore (per-tenant + operator).
+    #     A configured gateway_token STILL resolves as operator (an existing
+    #     deployment switching modes keeps its credential — additive, never
+    #     a second-class path).
+    #
+    # Fail-closed BY CONSTRUCTION: no store and no configured token -> :disabled
+    # (503, never open). A revoked or unknown token -> :unauthorized. Pure module,
+    # testable without a Rack env.
+    module TenantAuth
+      module_function
+
+      # gateway_token: config[:gateway_token] | nil. token_store: TokenStore |
+      # nil. header: raw Authorization value.
+      # -> :disabled | :unauthorized | { role: "operator"|"tenant", tenant_id: }
+      def check(gateway_token, token_store, header)
+        # Fail-closed FIRST (the construction rule): with no store AND no
+        # configured token the gateway is DISABLED (503) however the request
+        # looks — never "401: who are you facing a door that does not exist".
+        # A token_store present means the gateway IS configured (multi_tenant),
+        # with or without the legacy gateway token.
+        return :disabled if token_store.nil? && (gateway_token.nil? || gateway_token.empty?)
+
+        provided = header.to_s[/\ABearer (.+)\z/, 1]
+        return :unauthorized if provided.nil?
+
+        if token_store
+          record = token_store.resolve(provided)
+          unless record
+            # store miss -> the legacy gateway token still resolves as operator
+            # (an existing deployment switching modes keeps its credential).
+            return :unauthorized if gateway_token.nil? || gateway_token.empty?
+            return :unauthorized unless Rack::Utils.secure_compare(gateway_token, provided)
+
+            return { role: "operator", tenant_id: nil }
+          end
+
+          return { role: record.role.to_s, tenant_id: record.tenant_id }
+        end
+
+        # classic mode (no store): the gateway token is the only credential.
+        # Constant-time comparison: the operator token doesn't leak via timing.
+        return :unauthorized unless Rack::Utils.secure_compare(gateway_token, provided)
+
+        { role: "operator", tenant_id: nil }
+      end
+    end
+  end
+end

data/lib/insika/session_actor.rb

@@ -17,7 +17,7 @@ module Insika
   # Executor) is also born on the supervisor; the SessionActor only AWAITS it to
   # serialize.
   #
-  # RFC-0015: it is also where an inbound message for a BUSY session is routed.
+  # it is also where an inbound message for a BUSY session is routed.
   # That decision belongs here and nowhere else — this is already the object that
   # owns "one turn at a time for this session". Putting it in the HTTP handler
   # would duplicate the invariant; putting it in the Executor would mix turn
@@ -45,7 +45,7 @@ module Insika
       task.id
     end
 
-    # RFC-0015 §5.3 — merge a fragment into the turn waiting at the door.
+    # merge a fragment into the turn waiting at the door.
     # -> the task id it joined, or nil when there is nothing to merge into (no
     # pending turn, the window has closed, or the turn already started). nil is
     # the caller's signal to create a task of its own.
@@ -117,7 +117,7 @@ module Insika
       end
     end
 
-    # RFC-0015 §5.3 — the debounce window. Sleeps on the LOOP's fiber, never on the
+    # the debounce window. Sleeps on the LOOP's fiber, never on the
     # request's, so the POST is acked immediately and the platform does not retry.
     # Returns the task to run (re-read from the store when fragments merged into it,
     # since the in-memory Task is a frozen snapshot of an older message).

data/lib/insika/session_store.rb

@@ -61,7 +61,7 @@ module Insika
     # fiber, without a lock. Each message gets an "at" (ISO8601 UTC) if not
     # provided. NotFoundError if the session does not exist.
     #
-    # CONCURRENCY LIMITATION (§11 R2c): the RMW (read record -> += -> set) is
+    # CONCURRENCY LIMITATION (R2c): the RMW (read record -> += -> set) is
     # atomic ONLY because the SessionActor serializes turns of the same session
     # (one owner at a time). That serialization exists solely in SUPERVISED mode
     # (the actor loop lives on the supervisor). Two concurrent send_message on the

data/lib/insika/settings_store.rb

@@ -13,7 +13,7 @@ module Insika
     SCOPE = "settings"
     KEY   = "general"
 
-    # STRICT config, settings layer (item 23 / §8.1 — "no silent config compat: every
+    # STRICT config, settings layer (— "no silent config compat: every
     # schema migration explicit"). The settings record carries a `schema_version`;
     # every shape change is a numbered migration here, applied ONLY by the explicit
     # `migrate!` (Studio settings saves never silently reinterpret old-shaped data).
@@ -31,7 +31,7 @@ module Insika
       "turn_timeout" => 120,
       "tool_timeout" => 30,
       "compaction" => { "enabled" => false, "keep_last" => 20 },
-      # LLM config v2 (§10). Platform-wide model layer, resolved by the
+      # LLM config v2. Platform-wide model layer, resolved by the
       # ModelResolver under an agent that pins no model of its own:
       #   default_model/default_provider -> the platform default (Chat > Agent > HERE)
       #   fallback_models -> ordered chain ["provider/model" | "model", ...] tried
@@ -42,13 +42,13 @@ module Insika
       "default_provider" => nil,
       "fallback_models" => [],
       "utility_model" => nil,
-      # Reasoning control (§10, 4-layer: Chat > Agent > Model > Global). `thinking`
+      # Reasoning control (4-layer: Chat > Agent > Model > Global). `thinking`
       # is the GLOBAL default (off/on/low/medium/high; nil = provider default);
       # `model_params` is the PER-MODEL layer, a map "<provider/model>"|"<model>" ->
       # { "thinking" => ... }. Both resolved by the ModelResolver.
       "thinking" => nil,
       "model_params" => {},
-      # Evals (RFC-0008, panel by RFC-0013 §3.9). The GRADERS are platform config, so
+      # Evals (panel by). The GRADERS are platform config, so
       # the operator picks them in the Studio instead of remembering a CLI flag:
       #   judges        -> [{ "model" =>, "provider" => }, …]. [] = deterministic
       #                    asserts only (rubric'd cases read as judge_pending).
@@ -66,7 +66,7 @@ module Insika
         "quorum" => 1,
         "tolerance" => 0.05
       },
-      # Edge limits (item 33 / §12 G7) — the platform layer of the EdgeLimiter.
+      # Edge limits — the platform layer of the EdgeLimiter.
       # nil/0 = off (opt-in). chat_rate_limit = turn attempts per chat per
       # chat_rate_window (s); agent_token_ceiling = total tokens per agent per
       # agent_token_window (s). limit_response overrides the safe reply.

data/lib/insika/shutdown.rb

@@ -1,15 +1,15 @@
 # frozen_string_literal: true
 
 module Insika
-  # RFC-0016 A3 — shutdown is a drain, not a kill (docs/DEPLOY.md, process model
-  # item 4). The serving arms install this around the Executor. On the first
+  # shutdown is a drain, not a kill (docs/DEPLOY.md, process model
+  # The serving arms install this around the Executor. On the first
   # SIGTERM/SIGINT the process stops accepting new turns (`Executor#begin_drain!`
   # — a turn arriving mid-drain is left `:queued` for the next boot's recovery)
   # and waits up to `timeout` seconds for the in-flight ones; only then does the
   # ordinary stop proceed. A second signal skips the wait — the operator insisting
   # means now. Whatever the deadline abandons dies `:running` with the process and
   # the next boot generation's task sweep replays it from its checkpoint
-  # (side-effect skip on resume is what makes that replay safe, RFC-0006).
+  # (side-effect skip on resume is what makes that replay safe).
   #
   # Mechanics, because trap context is narrow: the handler writes ONE byte into a
   # self-pipe and returns. A plain watcher THREAD — not a fiber: at install time
@@ -27,7 +27,7 @@ module Insika
     # traps, parks the watcher. The CALLING thread is captured as the stop target
     # — install from the thread that runs the server.
     #
-    # `executors:` (RFC-0017 A4) drains N graphs on one signal. Signals are a
+    # `executors:` drains N graphs on one signal. Signals are a
     # PROCESS concern, and `Signal.trap` keeps only the last handler — so a second
     # `install` per graph would silently leave the earlier graphs dying mid-turn.
     # The host installs ONCE, naming every graph it embedded. `executor:` is the

data/lib/insika/skill_catalog.rb

@@ -11,7 +11,16 @@ module Insika
   # Consumed by the Executor (skill_catalog:) and by stage 3
   # (effective/format_for_prompt).
   class SkillCatalog
-    Skill = Data.define(:name, :description, :path, :body)
+    # Eagerness is NOT here. It used to be a frontmatter flag, i.e. a property of the
+    # SKILL — but skills are shared between agents, so one flag forced one decision
+    # onto every allowlist holding the skill. It is a property of the AGENT
+    # (`profile.skills_eager`, see #eager_for).
+    #
+    # companions: names of the skills this one cannot work without. Injecting or
+    # loading a skill brings them along, so the half-recipe state cannot be assembled —
+    # a reference table arriving without the procedure that reads it is worse than
+    # nothing, because the model then never asks for the other half.
+    Skill = Data.define(:name, :description, :path, :body, :triggers, :companions)
 
     # roots ordered by PRECEDENCE (highest first): workspace, managed,
     # bundled. Same name in more than one root: the first wins.
@@ -22,37 +31,93 @@ module Insika
     def initialize(roots, store: nil)
       @roots = Array(roots)
       @store = store
-      @skills = load_all
+      @skills, @agent_skills = load_all
     end
 
-    def all
-      @skills.values
+    # `agent` (an agent id) resolves the AGENT SCOPE first, then the shared one — the
+    # same precedence chain the catalog already runs for store-over-disk and
+    # workspace-over-managed-over-bundled, with one more dimension.
+    #
+    # Three cases fall out of that one rule: SHARED (only the shared record exists),
+    # OVERRIDE (both exist, the agent's wins) and AGENT-PRIVATE (only the agent record
+    # exists — invisible elsewhere, and its name may collide freely).
+    #
+    # Without `agent` the shared scope is all there is, which is what every caller
+    # that has no agent in hand (the Studio's shared editor, a bare catalog) means.
+    def all(agent: nil)
+      shared = @skills
+      overrides = agent_scope(agent)
+      return shared.values if overrides.empty?
+
+      shared.merge(overrides).values
     end
 
-    def find(name)
-      @skills[name.to_s]
+    def find(name, agent: nil)
+      agent_scope(agent)[name.to_s] || @skills[name.to_s]
     end
 
     # Reloads from disk + Store and SWAPS the index atomically: an
     # authored/edited skill takes effect without a restart. A turn in progress
     # captured @skills at dispatch, so it does not see the swap mid-flight.
     def reload
-      @skills = load_all
+      @skills, @agent_skills = load_all
       self
     end
 
-    # Per-agent allowlist: nil -> all | [] -> none | [names] -> subset.
-    def effective(skills_policy)
-      Allowlist.filter(all, skills_policy) { |s| s.name }
+    # Per-agent allowlist: nil -> all | [] -> none | [names] -> subset. `agent`
+    # selects WHICH body each allowed name resolves to (see #find); the allowlist is
+    # by NAME either way, so specializing a skill never touches the allowlist.
+    def effective(skills_policy, agent: nil)
+      Allowlist.filter(all(agent: agent), skills_policy) { |s| s.name }
     end
 
+    # THE single definition of "always in the prompt", consulted by all three
+    # surfaces that must agree: the body provider (injects these), the level-1
+    # catalog (hides them) and load_skill (refuses them). Split the rule across three
+    # files and they drift — which is the failure this whole feature came from.
+    #
+    # `profile.skills_eager` — a PER-AGENT decision, so a shared skill stays shared:
+    #   nil | false  -> none (progressive disclosure; the default)
+    #   true         -> every allowed skill (blanket; only for a corpus that fits the budget)
+    #   [names]      -> exactly these
+    #
+    # Deliberately NOT `Allowlist.filter`: there nil means ALL, which is the safe
+    # default for `skills`/`tools_allow` where nil is "no policy". Here nil must mean
+    # NONE — an unconfigured agent waking up with every skill body on every turn is
+    # the opposite of a safe default. A name that is not in the agent's `skills`
+    # allowlist is a silent no-op here (the intersection with `effective`); `doctor`
+    # flags it, because the operator who wrote the name meant it.
+    def eager_for(profile)
+      allowed = effective(profile.skills, agent: profile.id)
+      spec = profile.skills_eager
+      return allowed if blanket?(spec)
+      return [] if spec.nil? || spec == false
+
+      names = Array(spec).map { |n| n.to_s.strip }
+      allowed.select { |s| names.include?(s.name) }
+    end
+
+    # The complement: what the model still has to ASK for — and therefore what the
+    # level-1 list advertises and load_skill will serve.
+    def lazy_for(profile) = effective(profile.skills, agent: profile.id) - eager_for(profile)
+
     # Level 1: compact list injected into the system prompt. Metadata only.
     # Receives the set already filtered by the agent.
+    #
+    # `when=` carries the skill's `triggers:` — THE ROUTING TABLE, GENERATED. What
+    # actually made activation reliable on the pilot was a hand-written companion file
+    # listing each skill with its trigger phrases, and nothing checked it against the
+    # catalog: a skill created at 11:28 was invisible to a table written the day
+    # before, and the model obeyed the table. Rendering the same information from the
+    # catalog means it cannot disagree with the allowlist — a newly allowed skill
+    # appears the moment it is allowed. Detecting that drift would have been strictly
+    # worse than removing its source.
     def format_for_prompt(skills = all)
       return "" if skills.empty?
 
       entries = skills.map do |s|
-        %(  <skill name="#{s.name}">#{s.description}</skill>)
+        when_attr = Array(s.triggers).empty? ? "" : %( when="#{Array(s.triggers).join('; ')}")
+        %(  <skill name="#{s.name}"#{when_attr}>#{s.description}</skill>)
       end.join("\n")
 
       <<~PROMPT.strip
@@ -60,13 +125,24 @@ module Insika
         #{entries}
         </available_skills>
 
-        Before acting on a task that matches a skill above, call the
-        `load_skill` tool with its name to load the complete instructions.
+        Before ANY reply or tool call: scan the skills above. If one matches
+        or is even partially relevant to the task, you MUST call
+        `load_skill("name")` FIRST and follow what it returns. Err on the
+        side of loading. Only skip when genuinely none apply.
       PROMPT
     end
 
     private
 
+    # The blanket switch, tolerant of the strings a form / JSON round-trip produces
+    # ("1" from a checkbox, "true" from a pack) — same reading as
+    # AgentProfile#stream_public?. Anything else (a list, nil, false) is not blanket.
+    def blanket?(spec) = Coercion.truthy?(spec)
+
+    # An agent's override index; {} for a nil agent or one that specialized nothing.
+    def agent_scope(agent) = agent.nil? ? {} : (@agent_skills[agent.to_s] || {})
+
+    # -> [shared index, { agent_id => index }].
     def load_all
       found = {}
       @roots.each do |root|
@@ -78,7 +154,7 @@ module Insika
         end
       end
       overlay_store(found)
-      found
+      [found, load_agent_scopes]
     end
 
     # Store skills overlay the on-disk ones (authored > seed). Sentinel path
@@ -87,27 +163,58 @@ module Insika
       return unless @store
 
       @store.all.each do |name, content|
-        skill = parse_content(content.to_s, path: "store:#{name}")
-        found[skill.name] = skill if skill # Store wins
+        skill = parse_content(content.to_s, path: "store:#{name}", key: name)
+        found[name.to_s] = skill if skill # Store wins
+      end
+    end
+
+    # Per-agent overrides / private skills, one index per agent. A store that predates
+    # the agent dimension answers nothing here, so this is {} and every lookup falls
+    # straight through to the shared scope.
+    def load_agent_scopes
+      return {} unless @store.respond_to?(:agents)
+
+      @store.agents.each_with_object({}) do |agent, acc|
+        index = {}
+        @store.all(agent: agent).each do |name, content|
+          skill = parse_content(content.to_s, path: "store:#{agent}/#{name}", key: name)
+          index[name.to_s] = skill if skill
+        end
+        acc[agent.to_s] = index unless index.empty?
       end
     end
 
-    def parse_content(raw, path:)
+    # `key` = THE STORE POSITION, and it wins over the frontmatter `name:`. An override
+    # authored for one agent still says `name: escalation-to-human` inside — that is
+    # deliberate, it is the same skill specialized — and indexing by the parsed name
+    # would clobber the shared record globally, which is the exact bug the agent scope
+    # exists to fix. It also makes a pack whose directory name and frontmatter name
+    # disagree resolvable: the allowlist is written from the directory.
+    def parse_content(raw, path:, key: nil)
       match = raw.match(/\A---\s*\n(.*?)\n---\s*\n(.*)\z/m)
       return nil unless match
 
       # Tolerant frontmatter: real packs have `: ` in the description prose, which
       # strict YAML rejected (the pack would not load).
       meta = Insika::Frontmatter.parse(match[1])
-      name = meta["name"]
-      return nil unless name
+      name = key || meta["name"]
+      return nil unless name && Coercion.present?(meta["name"])
 
       Skill.new(
         name: name.to_s,
         description: meta["description"].to_s,
         path: path,
-        body: match[2].strip
+        body: match[2].strip,
+        triggers: parse_list(meta["triggers"]),
+        companions: parse_list(meta["companions"])
       )
     end
+
+    # `triggers:` / `companions:` frontmatter. YAML list, or comma-separated string
+    # under the lenient parse (which yields the whole value as one String).
+    def parse_list(raw)
+      list = raw.is_a?(String) ? raw.split(",") : Array(raw)
+      list.map { |t| t.to_s.strip }.reject(&:empty?)
+    end
   end
 end

data/lib/insika/skill_store.rb

@@ -3,20 +3,37 @@
 require "time"
 
 module Insika
-  # AUTHORED shared skills.
+  # AUTHORED skills, in two scopes.
   # Holds the complete SKILL.md (frontmatter + body) in the durable Store. The
   # SkillCatalog overlays these skills on top of the on-disk ones (seed), with the Store
   # winning — so editing/creating a skill in the Studio takes effect without a restart (via reload).
   #
-  # One record per skill in the ConfigStore (scope "skills"):
+  # SHARED scope (`agent:` omitted) — one record per skill in the ConfigStore
+  # (scope "skills"), keyed by the skill name:
   #   { "content" => "<entire SKILL.md>",
   #     "updated_at" => iso8601,
   #     "history" => [ { "content" =>, "at" => }, ... ] }
   #
-  # The key is the skill's canonical name (the same as in the frontmatter). Versions like
-  # the AgentFileStore.
+  # AGENT scope (`agent:` given) — one record per AGENT (scope "agent_skills"), the
+  # skills nested under it, exactly the AgentFileStore shape:
+  #   { "skills" => { "<name>" => { "content" =>, "updated_at" =>, "history" => [] } } }
+  #
+  # The agent dimension is a SECOND ARGUMENT, never part of the key. A composite
+  # `"agent/name"` key would put a `/` inside what the Studio serves as a single path
+  # segment (`GET /skills/:name`, the editor, the versions list) — the class of route
+  # bug that ships green and 404s in production. Two arguments become two route
+  # segments (`/agents/:id/skills/:name`) and nothing needs encoding.
+  #
+  # Two scopes and not one: the shared records are untouched by the arrival of the
+  # agent dimension, so there is no migration and a live deployment keeps serving
+  # exactly what it served.
+  #
+  # THE STORE POSITION IS THE IDENTITY. Which scope a record sits in — and under which
+  # key — is what decides which skill it is; the frontmatter `name:` inside an override
+  # stays the bare shared name. See SkillCatalog#find.
   class SkillStore
     SCOPE = "skills"
+    AGENT_SCOPE = "agent_skills"
     HISTORY_MAX = 20
 
     def initialize(config_store:)
@@ -24,48 +41,79 @@ module Insika
     end
 
     # -> String | nil (complete SKILL.md).
-    def get(name)
-      record(name)&.fetch("content", nil)
+    def get(name, agent: nil)
+      record(name, agent)&.fetch("content", nil)
     end
 
-    # -> [String] names, lexicographic order.
-    def names = @cs.keys(SCOPE)
+    # -> [String] names in the scope, lexicographic order.
+    def names(agent: nil)
+      agent.nil? ? @cs.keys(SCOPE) : agent_skills(agent).keys.sort
+    end
 
-    # -> { name => content } of all authored skills.
-    def all
-      @cs.keys(SCOPE).each_with_object({}) { |n, acc| acc[n] = get(n) }
+    # -> { name => content } of the scope's authored skills.
+    def all(agent: nil)
+      names(agent: agent).each_with_object({}) { |n, acc| acc[n] = get(n, agent: agent) }
     end
 
+    # -> [String] every agent that has specialized at least one skill. What the
+    # catalog overlays and `doctor` sweeps.
+    def agents = @cs.keys(AGENT_SCOPE).sort
+
     # Writes (upsert). create_only refuses to overwrite. -> Hash (the stored record).
-    def write(name, content, create_only: false)
+    def write(name, content, agent: nil, create_only: false)
       key = name.to_s
-      current = @cs.get(SCOPE, key)
-      raise Insika::ValidationError, "skill '#{key}' already exists" if create_only && current
+      current = record(key, agent)
+      raise Insika::ValidationError, "skill '#{key}' already exists#{" for agent '#{agent}'" if agent}" if create_only && current
 
       rec = build_record(content.to_s, current)
-      @cs.put(SCOPE, key, rec)
+      put(key, rec, agent)
       rec
     end
 
     # -> bool (did it exist?).
-    def delete(name) = @cs.delete(SCOPE, name.to_s)
+    def delete(name, agent: nil)
+      key = name.to_s
+      return @cs.delete(SCOPE, key) if agent.nil?
+
+      wrapper = @cs.get(AGENT_SCOPE, agent.to_s)
+      return false unless wrapper&.dig("skills", key)
+
+      wrapper["skills"].delete(key)
+      @cs.put(AGENT_SCOPE, agent.to_s, wrapper)
+      true
+    end
 
     # -> [ { "content" =>, "at" => } ] most recent first.
-    def versions(name) = record(name)&.fetch("history", []) || []
+    def versions(name, agent: nil) = record(name, agent)&.fetch("history", []) || []
 
     # Restores version `index` as the current content (a new write). -> Hash.
-    def restore(name, index)
-      hist = versions(name)
+    def restore(name, index, agent: nil)
+      hist = versions(name, agent: agent)
       i = Integer(index)
-      raise Insika::NotFoundError, "skill '#{name}' not found" unless record(name)
+      raise Insika::NotFoundError, "skill '#{name}' not found" unless record(name.to_s, agent)
       raise Insika::ValidationError, "version #{index} does not exist" if i.negative? || i >= hist.length
 
-      write(name, hist[i]["content"])
+      write(name, hist[i]["content"], agent: agent)
     end
 
     private
 
-    def record(name) = @cs.get(SCOPE, name.to_s)
+    def record(name, agent)
+      return @cs.get(SCOPE, name.to_s) if agent.nil?
+
+      agent_skills(agent)[name.to_s]
+    end
+
+    def put(key, rec, agent)
+      return @cs.put(SCOPE, key, rec) if agent.nil?
+
+      wrapper = @cs.get(AGENT_SCOPE, agent.to_s) || { "skills" => {} }
+      wrapper["skills"] ||= {}
+      wrapper["skills"][key] = rec
+      @cs.put(AGENT_SCOPE, agent.to_s, wrapper)
+    end
+
+    def agent_skills(agent) = (@cs.get(AGENT_SCOPE, agent.to_s) || {})["skills"] || {}
 
     def build_record(content, current)
       history = current ? current.fetch("history", []) : []

data/lib/insika/steer_injector.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Insika
-  # RFC-0015 §5.2 — WHERE a message that arrived mid-run is allowed to enter the
+  # WHERE a message that arrived mid-run is allowed to enter the
   # conversation.
   #
   # A customer who corrects themselves while the agent is calling tools ("1234567",

data/lib/insika/store.rb

@@ -5,7 +5,7 @@ module Insika
   # Namespace-scoped KV, transactional when the backend supports it.
   # Every implementation passes the SAME contract suite
   # (lib/insika/testing/store_contract.rb — requirable from outside the repo,
-  # RFC-0018 A4). Values must be JSON-serializable.
+  # Values must be JSON-serializable.
   #
   # scope: String — separates domains/tenants (e.g. "sessions", "tasks:tenant_x")
   # key:   Hierarchical String (e.g. "task:123", "checkpoint:123:turn:4")