insika 0.1.0 → 0.2.0

data/lib/insika/studio/forms.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Studio
-  # Form → command-payload parsing for the Studio App (§11 B6). A mixin, NOT a
+  # Form → command-payload parsing for the Studio App. A mixin, NOT a
   # standalone object: `include`d into App so every method keeps `self` == the
   # App instance and reaches its request helpers (`presence`, `split_list`) and
   # per-request state (`@agent`) exactly as before. Pure extraction — the bodies
@@ -15,7 +15,7 @@ module Studio
         v = presence(r.params[field])
         limits[field.to_sym] = Integer(v) if v
       end
-      # Per-agent edge overrides (item 33). Unlike the timeouts (always present via
+      # Per-agent edge overrides. Unlike the timeouts (always present via
       # DEFAULT_LIMITS), these are OPT-IN keys: blank DELETES the override (inherit
       # the platform edge settings); 0 explicitly disables for this agent.
       %w[chat_rate_limit agent_token_ceiling].each do |field|
@@ -38,7 +38,7 @@ module Studio
       }
     end
 
-    # Guardrails config from the form (RFC-0009). The config form OWNS these fields,
+    # Guardrails config from the form. The config form OWNS these fields,
     # so the patch reflects the whole guardrails state. String values round-trip
     # cleanly through the JSON store; Safety::Config normalizes on read. A blank
     # moderator drops the key (deterministic only).
@@ -54,7 +54,7 @@ module Studio
       out
     end
 
-    # Per-category safe-reply overrides (RFC-0009 §7, config over convention). Only
+    # Per-category safe-reply overrides (config over convention). Only
     # the non-blank fields are persisted; Safety::Config normalizes on read.
     def guardrail_responses_patch(r)
       %w[default injection sexual abuse escalate].each_with_object({}) do |cat, acc|
@@ -62,7 +62,7 @@ module Studio
       end
     end
 
-    # Per-agent generation params (v2, §10). The config form OWNS these fields, so
+    # Per-agent generation params. The config form OWNS these fields, so
     # the patch reflects the whole form state: a blank field drops the key (and an
     # all-blank form clears params to {}). temperature/max_tokens MUST be Numeric —
     # ModelSelection#apply_params guards on `numeric?` and silently skips a String —
@@ -79,7 +79,7 @@ module Studio
       out
     end
 
-    # Per-agent model fence (v2, §10): { "allow" => [refs] } where a ref is
+    # Per-agent model fence: { "allow" => [refs] } where a ref is
     # "provider/model", "provider/*" or "model". Blank textarea -> nil (NO fence,
     # all models — parity). Enforced on the RESOLVED model by the ModelResolver,
     # so a per-chat pin can never escape it.
@@ -101,7 +101,7 @@ module Studio
 
     # Fields a tool CAN carry that this form does not render. The store REPLACES the
     # record on write, so anything missing here is erased — a save that only fixed a
-    # typo in the description would silently drop them (the class of bug §12 already
+    # typo in the description would silently drop them (the class of bug already
     # paid for once). `stored` carries them through untouched.
     UNEDITED_TOOL_FIELDS = %w[group tags halt_when].freeze
 
@@ -166,22 +166,17 @@ module Studio
 
     def settings_patch(r)
       patch = {
-        "streaming" => r.params["streaming"] == "1",
-        "compaction" => {
-          "enabled" => r.params["compaction_enabled"] == "1"
-        }
+        "streaming" => r.params["streaming"] == "1"
       }
       { "request_timeout" => "request_timeout", "max_retries" => "max_retries",
         "turn_timeout" => "turn_timeout", "tool_timeout" => "tool_timeout" }.each_key do |f|
         v = presence(r.params[f])
         patch[f] = Integer(v) if v
       end
-      kl = presence(r.params["keep_last"])
-      patch["compaction"]["keep_last"] = Integer(kl) if kl
       patch
     end
 
-    # Edge limits (item 33 / §12 G7) — the platform rate-limit/cost layer, saved
+    # Edge limits — the platform rate-limit/cost layer, saved
     # from its OWN form (a sub-resource, like models). The limit fields write nil
     # when blank (off — the EdgeLimiter reads nil/0 as off); the windows fall back
     # to the built-in defaults when cleared (the limiter guards non-positive).
@@ -209,7 +204,7 @@ module Studio
       { case: parsed }
     end
 
-    # Evals graders (RFC-0013 §3.9). `judges` is one `provider/model` per LINE — a
+    # Evals graders. `judges` is one `provider/model` per LINE — a
     # textarea, because the SIZE of the panel is the point and a fixed pair of fields
     # would cap it at two. A bare `model` (no slash) is valid: the provider is then
     # inferred by RubyLLM, same as everywhere else.
@@ -258,7 +253,7 @@ module Studio
       raise Insika::ValidationError, "#{field} must be an integer (got #{raw.inspect})"
     end
 
-    # LLM config v2 (§10) — the platform model layer, saved from its OWN form (a
+    # LLM config v2 — the platform model layer, saved from its OWN form (a
     # sub-resource, like providers) so the general-settings save never touches it and
     # vice-versa. The scalar refs are always present (blank -> nil, which the
     # deep-merge writes and the ModelResolver reads as "no platform default");
@@ -270,12 +265,12 @@ module Studio
         "default_provider" => presence(r.params["default_provider"]),
         "utility_model" => presence(r.params["utility_model"]),
         "fallback_models" => split_list(r.params["fallback_models"]),
-        # GLOBAL reasoning default (§10, 4-layer). Blank -> nil = provider default.
+        # GLOBAL reasoning default (4-layer). Blank -> nil = provider default.
         "thinking" => presence(r.params["thinking"])
       }
     end
 
-    # Per-model reasoning defaults (§10, the per-model layer). One line per model:
+    # Per-model reasoning defaults (the per-model layer). One line per model:
     #   <provider/model | model> | <off|on|low|medium|high>
     # CSP forbids JS for dynamic rows, so a textarea of lines is the honest path
     # (same idiom as the MCP env / tool params). A blank effort -> {} for that ref

data/lib/insika/studio/nav_icons.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 module Studio
-  # Nav SVG icons for the Studio App (§11 B6). A mixin included into App: the
+  # Nav SVG icons for the Studio App. A mixin included into App: the
   # `nav_icon` view helper and its icon table, moved verbatim out of app.rb.
   # Inline SVG is CSP-safe (an HTML element, not an external resource).
   module NavIcons

data/lib/insika/studio/views/_message.erb

@@ -1,4 +1,4 @@
-<%# Shared transcript bubble/tool-card (§11 A1/A2) — one visual language for the
+<%# Shared transcript bubble/tool-card — one visual language for the
     playground history, the optimistic echo and the read-only session viewer.
     Locals: m = stored message hash {"role","content","at"}; prev = the message before
     it in the thread, or nil (used only to spot a steered message). `content` may be a
@@ -22,7 +22,7 @@
           when it is NOT the natural producer for the role — otherwise every bubble
           would carry a label that says nothing. %>
       <% origin = Insika::MessageOrigin.origin_of(m) unless Insika::MessageOrigin.customer?(m) || Insika::MessageOrigin.agent?(m) %>
-      <%# STEERED (RFC-0015): a customer message sitting right after a tool result arrived
+      <%# STEERED: a customer message sitting right after a tool result arrived
           while the turn was running and was appended at a tool-batch boundary. Derived
           from position, not from a field — a steered message declares no origin, and it
           is right not to: a person typed it. Nothing else in the engine ever puts a user

data/lib/insika/studio/views/agent_detail.erb

@@ -69,7 +69,7 @@
     </label>
 
     <fieldset class="subgroup">
-      <legend>guardrails <span class="muted">— content safety (RFC-0009)</span></legend>
+      <legend>guardrails <span class="muted">— content safety</span></legend>
       <label class="check">
         <input type="checkbox" name="guardrail_input" value="1"<%== " checked" if guardrail_field(@guardrails, :input, true) %>>
         input guardrail <span class="muted">— block injection / abuse / inappropriate before the LLM</span>
@@ -88,7 +88,7 @@
           </select>
         </label>
         <label>LLM moderator <span class="muted">(model ref, or <code>on</code> for the platform utility_model; blank = deterministic only)</span>
-          <input type="text" name="guardrail_moderator" value="<%= guardrail_field(@guardrails, :moderator, "") %>" placeholder="deepseek/deepseek-chat">
+          <input type="text" name="guardrail_moderator" value="<%= guardrail_field(@guardrails, :moderator, "") %>" placeholder="deepseek/deepseek-v4-flash">
         </label>
       </div>
       <details class="newfile">

data/lib/insika/studio/views/agents.erb

@@ -48,7 +48,7 @@
         <input type="text" name="id" placeholder="bia" required>
       </label>
       <label>model
-        <input type="text" name="model" placeholder="deepseek-chat" required>
+        <input type="text" name="model" placeholder="deepseek-v4-flash" required>
       </label>
     </div>
     <label>provider <span class="muted">(optional)</span>

data/lib/insika/studio/views/refinement.erb

@@ -39,7 +39,7 @@
     </div>
   <% end %>
 
-  <%# RFC-0013 §3.6 — the review IS the product. A gated proposal shows the exact
+  <%# The review IS the product. A gated proposal shows the exact
       edit, what it claims to fix, and how it scored against the accepted baseline,
       because approving is a decision and a decision needs those three things. %>
   <% if @proposal %>
@@ -51,7 +51,7 @@
         <span class="mono"><%= @proposal.gate["passed_cases"] %>/<%= @proposal.gate["cases"] %> case(s)</span>
         <span class="muted">no regression against <%= @proposal.gate["baseline_cases"] %> baselined case(s)</span>
         <span class="muted">· proposed by <span class="mono"><%= cand["proposer"] %></span></span>
-        <%# RFC-0013 §3.9 — when a PANEL ran, the operator is looking at the winner of
+        <%# When a PANEL ran, the operator is looking at the winner of
             several, and which ones it beat is part of the decision. %>
         <% if @proposal.panel.size > 1 %>
           <span class="muted">· best of <%= @proposal.panel.size %> candidate(s)</span>
@@ -125,7 +125,7 @@
   <% else %>
     <h2>Findings<span class="sub"><%= @run.findings.size %> · <%= @run.status %><% if @run.excluded.to_i.positive? %> · <%= @run.excluded %> turn(s) excluded<% end %> · <%= @run.finished_at || @run.started_at %></span></h2>
 
-    <%# RFC-0013 §3.4 — the model writes the candidate, the gate scores it. Offered on
+    <%# The model writes the candidate, the gate scores it. Offered on
         a finished report and only when nothing is already awaiting an answer: a second
         proposal while one is pending would ask the operator to review two edits to the
         same file that were never scored together. %>
@@ -147,7 +147,7 @@
       </div>
     <% end %>
 
-    <%# RFC-0013 §3.6 — `mode: auto_apply` changed this agent's files with nobody in
+    <%# `mode: auto_apply` changed this agent's files with nobody in
         the loop, so the page owes the operator exactly three things: what changed, why,
         and where to undo it. The write versioned, so History IS the undo. %>
     <% if @run.status == :applied && (@run.decision || {})["by"] == "auto_apply" %>

data/lib/insika/studio/views/session.erb

@@ -12,6 +12,57 @@
   <a class="btn" href="/studio/playground?session_id=<%= Rack::Utils.escape(@session.id) %>">Continue in playground →</a>
 </header>
 
+<% ctx_traces = @context_traces || [] %>
+<% unless ctx_traces.empty? %>
+  <div class="card tooltrace">
+    <div class="trace-head">
+      <h2>Context</h2>
+      <span class="muted">tokens by category per turn (estimated) — no content stored</span>
+    </div>
+    <% ctx_traces.each do |c| %>
+      <div class="trace-turn">
+        <div class="turn-label">turn <%= c["turn"] %> · <%= c["at"] %></div>
+        <%# Skills injected by context (triggers/skills_eager) leave NO tool call in
+            the transcript, so this card is the only record that they were active.
+            The names live in the body, but the count belongs in the SUMMARY: the
+            card is collapsed, and "was the skill on?" is the question an operator
+            asks on every single turn. %>
+        <% skills = Array((c["categories"] || {}).dig("skilltrigger", "labels")).uniq %>
+        <details class="trace-item ok">
+          <summary>
+            <span class="badge"><%= c["used"] %> / <%= c["cap"] %></span>
+            <strong>context</strong>
+            <% unless skills.empty? %>
+              <span class="badge">skills <%= skills.length %></span>
+            <% end %>
+            <% unless Array(c["evicted"]).empty? %>
+              <span class="lat">evicted: <%= Array(c["evicted"]).join(", ") %></span>
+            <% end %>
+          </summary>
+          <% (c["categories"] || {}).sort_by { |_k, v| -(v["tokens"] || 0) }.each do |name, cat| %>
+            <div class="kv"><span><%= name %></span>
+              <div><%= cat["tokens"] %> tokens · <%= cat["fragments"] %> fragment(s)<%== " · pinned" if (cat["pinned"] || 0).positive? %>
+                <%# WHICH skills the turn injected AND WHY — the only after-the-fact %>
+                <%# record of activation once the bodies arrive by context instead of a %>
+                <%# tool call. The reason is the half the operator was missing: a name %>
+                <%# alone does not say whether they triggered it or the agent always has it. %>
+                <% labels = Array(cat["labels"]).uniq %>
+                <% unless labels.empty? %>
+                  <br><span class="lat"><%= labels.map { |l| skill_label(l) }.join(", ") %></span>
+                <% end %>
+              </div>
+            </div>
+          <% end %>
+          <% tools = c["tools"] || {} %>
+          <div class="kv"><span>tools</span>
+            <div><%= tools["tokens"] %> tokens · <%= tools["count"] %> tool schema(s)</div>
+          </div>
+        </details>
+      </div>
+    <% end %>
+  </div>
+<% end %>
+
 <% traces = @tool_traces || {} %>
 <% unless traces.empty? %>
   <div class="card tooltrace">
@@ -54,9 +105,33 @@
     <div class="empty">This session has no messages.</div>
   <% else %>
     <div class="thread">
-      <%# `prev` is what makes a STEERED message visible: a customer message that lands
-          right after a tool result arrived mid-run (RFC-0015). See _message.erb. %>
-      <% Array(@session.messages).each_with_index do |m, i| %><%== render("_message", locals: { m: m, prev: i.positive? ? @session.messages[i - 1] : nil }) %><% end %>
+      <%# A skill loaded by the model shows up here on its own: load_skill is a tool,
+          so its body is a persisted `role: tool` message. A skill injected by CONTEXT
+          (triggers/skills_eager) is part of the system prompt — never a message — so
+          the thread had no trace of it at all. Synthesized from the context trace so
+          both activation paths read the same way in the transcript.
+
+          Placed by TIME, not by counting turns: every message of a turn is persisted
+          together at the end of it, and the context stage always runs before that, so
+          each entry lands at the top of its own turn. Ordinal counting would drift on
+          a steered message (one that joins a turn already running). A message with no
+          `at` (older sessions) simply flushes nothing. %>
+      <% pending = (@context_traces || [])
+                   .select { |c| Array((c["categories"] || {}).dig("skilltrigger", "labels")).any? }
+                   .sort_by { |c| c["at"].to_s } %>
+      <% Array(@session.messages).each_with_index do |m, i| %>
+        <% while (entry = pending.first) && !m["at"].to_s.empty? && entry["at"].to_s <= m["at"].to_s %>
+          <% pending.shift %>
+          <% labels = Array(entry["categories"]["skilltrigger"]["labels"]).uniq %>
+          <details class="toolcard skill">
+            <summary><span class="arrow">↑</span><strong>skills · <%= skill_mode(labels) %> (<%= labels.length %>)</strong><span class="at"><%= entry["at"] %></span></summary>
+            <pre><%= labels.map { |l| skill_label(l) }.join("\n") %></pre>
+          </details>
+        <% end %>
+        <%# `prev` is what makes a STEERED message visible: a customer message that lands
+            right after a tool result arrived mid-run. See _message.erb. %>
+        <%== render("_message", locals: { m: m, prev: i.positive? ? @session.messages[i - 1] : nil }) %>
+      <% end %>
     </div>
   <% end %>
 </div>

data/lib/insika/studio/views/settings.erb

@@ -1,7 +1,7 @@
 <%# Settings — drill-down (T2): section list | selected section's form(s).
    @section (general|models|llm) comes from ?s= and drives the detail. %>
 <% sections = [
-     ["general", "General", "streaming, timeouts, compaction"],
+     ["general", "General", "streaming, timeouts"],
      ["models",  "Model defaults", "platform model layer (Chat › Agent › platform)"],
      ["edge",    "Edge limits", "rate-limit per chat, token ceiling per agent"],
      ["evals",   "Evals", "who grades a rubric, and how a panel agrees"],
@@ -27,7 +27,7 @@
         <button type="submit" form="set-general" class="btn primary" data-turbo-submits-with="Saving…">Save</button>
       </div>
       <div class="drill-pane-body">
-        <p class="muted">Streaming, timeouts and compaction — saved via <code>update_settings</code> (durable, applies next turn).</p>
+        <p class="muted">Streaming and timeouts — saved via <code>update_settings</code> (durable, applies next turn).</p>
         <form id="set-general" method="post" action="/studio/settings">
           <%== csrf_tag %>
           <label class="check">
@@ -40,11 +40,6 @@
             <label>turn_timeout (s)<input type="text" name="turn_timeout" value="<%= @settings["turn_timeout"] %>" inputmode="numeric"></label>
             <label>tool_timeout (s)<input type="text" name="tool_timeout" value="<%= @settings["tool_timeout"] %>" inputmode="numeric"></label>
           </div>
-          <label class="check">
-            <input type="checkbox" name="compaction_enabled" value="1"<%== " checked" if @settings.dig("compaction", "enabled") %>>
-            context compaction
-          </label>
-          <label>compaction.keep_last (messages)<input type="text" name="keep_last" value="<%= @settings.dig("compaction", "keep_last") %>" inputmode="numeric"></label>
         </form>
       </div>
 
@@ -58,11 +53,11 @@
         <form id="set-models" method="post" action="/studio/settings/models">
           <%== csrf_tag %>
           <div class="grid-2">
-            <label>default_model <span class="muted">(agents without their own model)</span><input type="text" name="default_model" value="<%= @settings["default_model"] %>" placeholder="deepseek-chat"></label>
+            <label>default_model <span class="muted">(agents without their own model)</span><input type="text" name="default_model" value="<%= @settings["default_model"] %>" placeholder="deepseek-v4-flash"></label>
             <label>default_provider <span class="muted">(optional)</span><input type="text" name="default_provider" value="<%= @settings["default_provider"] %>" placeholder="deepseek"></label>
           </div>
-          <label>fallback_models <span class="muted">(ordered chain; <code>provider/model</code> or <code>model</code>, comma or newline)</span><input type="text" name="fallback_models" value="<%= Array(@settings["fallback_models"]).join(", ") %>" placeholder="deepseek/deepseek-chat, openai/gpt-4o-mini"></label>
-          <label>utility_model <span class="muted">(cheap internal tasks — titles, distillation)</span><input type="text" name="utility_model" value="<%= @settings["utility_model"] %>" placeholder="deepseek-chat"></label>
+          <label>fallback_models <span class="muted">(ordered chain; <code>provider/model</code> or <code>model</code>, comma or newline)</span><input type="text" name="fallback_models" value="<%= Array(@settings["fallback_models"]).join(", ") %>" placeholder="deepseek/deepseek-v4-flash, openai/gpt-4o-mini"></label>
+          <label>utility_model <span class="muted">(cheap internal tasks — titles, distillation)</span><input type="text" name="utility_model" value="<%= @settings["utility_model"] %>" placeholder="deepseek-v4-flash"></label>
           <label>reasoning <span class="muted">(global default — off/on/effort; blank = provider default)</span>
             <%== thinking_select("thinking", @settings["thinking"], "provider default") %>
           </label>
@@ -107,7 +102,7 @@
     <p class="muted">Who grades a <a href="/studio/evals">case</a>'s rubric. <strong>One model per line</strong> as <code>provider/model</code> — several lines make a PANEL, and two different models disagreeing is the signal worth having (sampling one model N times mostly measures its own variance). Empty = deterministic assertions only, and rubric'd cases read as <code>judge_pending</code>.</p>
     <form id="set-evals" method="post" action="/studio/settings/evals">
       <%== csrf_tag %>
-      <label>judges<textarea name="judges" rows="4" spellcheck="false" placeholder="deepseek/deepseek-chat&#10;openai/gpt-5-mini"><%= Array(@settings.dig("evals", "judges")).map { |j| [j["provider"], j["model"]].compact.reject(&:empty?).join("/") }.join("\n") %></textarea></label>
+      <label>judges<textarea name="judges" rows="4" spellcheck="false" placeholder="deepseek/deepseek-v4-flash&#10;openai/gpt-5-mini"><%= Array(@settings.dig("evals", "judges")).map { |j| [j["provider"], j["model"]].compact.reject(&:empty?).join("/") }.join("\n") %></textarea></label>
       <div class="grid-2">
         <label>aggregate <span class="muted">(how the panel's scores combine)</span>
           <select name="aggregate">
@@ -147,7 +142,7 @@
                 <label>auth_header<input type="text" name="auth_header" value="<%= p["auth_header"] %>" placeholder="Authorization"></label>
               </div>
               <label>api_key<input type="password" name="api_key" value="<%= p["api_key"] %>" autocomplete="off"></label>
-              <label>models <span class="muted">(comma or newline)</span><input type="text" name="models" value="<%= Array(p["models"]).join(", ") %>" placeholder="deepseek-chat, deepseek-reasoner"></label>
+              <label>models <span class="muted">(comma or newline)</span><input type="text" name="models" value="<%= Array(p["models"]).join(", ") %>" placeholder="deepseek-v4-flash, deepseek-reasoner"></label>
               <div class="actions"><button type="submit" class="primary" data-turbo-submits-with="Saving…">Save provider</button></div>
             </form>
           </div>

data/lib/insika/studio/views/skills.erb

@@ -1,6 +1,9 @@
 <%# Skills — drill-down (T2): master list | detail editor + availability.
    Every skill route renders THIS view (index / new / :name); @selected drives
-   which skill is open (nil = none, "" = new). %>
+   which skill is open (nil = none, "" = new). @scope_agent set = editing THAT
+   agent's own version of the skill, not the shared one. %>
+<% scope = @scope_agent %>
+<% form_action = scope ? "/studio/agents/#{Rack::Utils.escape(scope)}/skills/#{Rack::Utils.escape(@selected.to_s)}" : "/studio/skills" %>
 <div class="drill" data-controller="list-filter">
   <aside class="drill-pane drill-master">
     <div class="drill-pane-head">
@@ -36,15 +39,30 @@
       <% new = @selected == "" %>
       <div class="drill-pane-head">
         <div class="title">
-          <nav class="crumbs"><a href="/studio/skills">skills</a> / <span><%= new ? "new" : @selected %></span></nav>
-          <strong class="mono"><%= new ? "New skill" : @selected %></strong>
+          <nav class="crumbs"><a href="/studio/skills">skills</a> / <span><%= new ? "new" : @selected %></span><% if scope %> / <span>for <%= scope %></span><% end %></nav>
+          <strong class="mono"><%= new ? "New skill" : @selected %><% if scope %> <span class="pill warn">specialized for <%= scope %></span><% end %></strong>
         </div>
         <button type="submit" form="skill-form" class="btn primary" data-turbo-submits-with="Saving…">Save skill</button>
       </div>
       <div class="drill-pane-body">
-        <form id="skill-form" method="post" action="/studio/skills" data-controller="dirty-guard">
+        <%# The specialization is one MORE record, not a fork: the name stays the bare
+            shared name everywhere the model and the operator see it, and deleting the
+            override falls back to the shared body. %>
+        <% if scope %>
+          <div class="drill-section">
+            <p class="muted">This is <strong><%= scope %></strong>'s own version of <code><%= @selected %></code>. Every
+              other agent keeps the <a href="/studio/skills/<%= Rack::Utils.escape(@selected.to_s) %>">shared skill</a>,
+              and the name does not change — the allowlist, <code>&lt;available_skills&gt;</code> and
+              <code>load_skill</code> all still say <code><%= @selected %></code>.</p>
+            <form method="post" action="/studio/agents/<%= Rack::Utils.escape(scope) %>/skills/<%= Rack::Utils.escape(@selected.to_s) %>/delete">
+              <%== csrf_tag %>
+              <div class="actions"><button type="submit" data-turbo-confirm="Remove this specialization? <%= scope %> falls back to the shared skill.">Stop specializing</button></div>
+            </form>
+          </div>
+        <% end %>
+        <form id="skill-form" method="post" action="<%= form_action %>" data-controller="dirty-guard">
           <%== csrf_tag %>
-          <% unless new %><input type="hidden" name="name" value="<%= @selected %>"><% end %>
+          <% if !new && !scope %><input type="hidden" name="name" value="<%= @selected %>"><% end %>
           <% if new %>
             <label>name <span class="muted">(canonical — same as <code>name:</code> in the frontmatter)</span>
               <input type="text" name="name" placeholder="my-skill" required>
@@ -56,29 +74,66 @@
           </div>
         </form>
 
-        <% unless new %>
+        <% if !new && !scope %>
           <div class="drill-section">
             <div class="drill-section-head">
               <h3>Availability</h3>
-              <span class="muted">which agents can <code>load_skill</code> this — an "all" allowlist is left untouched</span>
+              <span class="muted">per agent: <strong>allowed</strong> = can <code>load_skill</code> it; <strong>always on</strong> = the body
+                is in the prompt every turn. Both are the AGENT's decision, so one shared skill can be
+                always-on for one and discretionary for another. An "all" allowlist is left untouched.</span>
             </div>
             <form method="post" action="/studio/skills/<%= Rack::Utils.escape(@selected) %>/agents">
               <%== csrf_tag %>
               <% if @agents.empty? %>
                 <p class="muted">No agents configured.</p>
               <% else %>
-                <div class="check-grid">
+                <div class="check-grid agent-grid">
                   <% @agents.each do |a| %>
-                    <label class="check">
-                      <input type="checkbox" name="agent_ids[]" value="<%= a.id %>"<%== " checked" if skill_enabled_for?(a, @selected) %>>
-                      <span class="mono"><%= a.id %></span>
-                    </label>
+                    <% own = Array((@specialized || {})[@selected]).include?(a.id) %>
+                    <div class="agent-check">
+                      <div class="agent-check-name">
+                        <span class="mono"><%= a.id %></span>
+                        <% if own %>
+                          <a class="pill warn" href="/studio/agents/<%= Rack::Utils.escape(a.id) %>/skills/<%= Rack::Utils.escape(@selected) %>">own version</a>
+                        <% end %>
+                      </div>
+                      <label class="check tool-check">
+                        <input type="checkbox" name="agent_ids[]" value="<%= a.id %>"<%== " checked" if skill_enabled_for?(a, @selected) %>>
+                        <span class="mono">allowed</span>
+                      </label>
+                      <label class="check tool-check">
+                        <input type="checkbox" name="eager_ids[]" value="<%= a.id %>"<%== " checked" if skill_eager_for?(a, @selected) %>>
+                        <span class="mono">always on</span>
+                      </label>
+                    </div>
                   <% end %>
                 </div>
                 <div class="actions"><button type="submit" class="primary" data-turbo-submits-with="Applying…">Apply to agents</button></div>
               <% end %>
             </form>
           </div>
+
+          <%# Specializing is what keeps a shared skill shared: without it the only way
+              to give one agent a different version was to fork it under a new name and
+              edit the allowlist, which throws the sharing away. %>
+          <% others = @agents.reject { |a| Array((@specialized || {})[@selected]).include?(a.id) } %>
+          <% if others.any? %>
+            <div class="drill-section">
+              <div class="drill-section-head">
+                <h3>Specialize</h3>
+                <span class="muted">give ONE agent its own version of this skill, seeded from the body above — same name, no fork</span>
+              </div>
+              <form method="post" action="/studio/skills/<%= Rack::Utils.escape(@selected) %>/specialize">
+                <%== csrf_tag %>
+                <label>agent
+                  <select name="agent_id" required>
+                    <% others.each do |a| %><option value="<%= a.id %>"><%= a.id %></option><% end %>
+                  </select>
+                </label>
+                <div class="actions"><button type="submit" data-turbo-submits-with="Creating…">Specialize for this agent</button></div>
+              </form>
+            </div>
+          <% end %>
         <% end %>
       </div>
     <% end %>

data/lib/insika/subagent_graph.rb

@@ -1,8 +1,8 @@
 # frozen_string_literal: true
 
 module Insika
-  # Definition-time integrity of the subagent delegation graph (RFC-0010 §4.4,
-  # item 21). A pure function over `{id => [child_ids]}`: detects CYCLES and
+  # Definition-time integrity of the subagent delegation graph (
+  # A pure function over `{id => [child_ids]}`: detects CYCLES and
   # computes the max delegation DEPTH, raising a typed SubagentError so the
   # authoring Command (CreateAgent/UpdateAgent) fails cleanly and boot refuses a
   # bad static set. Cycle + bounded depth are exactly Flue's definition-time
@@ -21,7 +21,7 @@ module Insika
 
     # Max children a single `spawn_subagents` fan-out may run — also the concurrency
     # bound (N concurrent LLM calls hit the provider rate limit + the per-agent token
-    # ceiling of item 33). Override with INSIKA_SUBAGENT_FANOUT_CAP.
+    # ceiling of). Override with INSIKA_SUBAGENT_FANOUT_CAP.
     DEFAULT_FANOUT_CAP = 8
 
     module_function

data/lib/insika/task_actor.rb

@@ -9,7 +9,7 @@ module Insika
   # `await` as the cooperative SUSPENSION primitive. Cancellation/suspension only
   # at stage boundaries — never in the middle of an operation.
   class TaskActor
-    # `user_message` is posted by `Executor#steer_into_running` (RFC-0015 §5.1) and
+    # `user_message` is posted by `Executor#steer_into_running` and
     # consumed by `SteerInjector` at a tool-batch boundary. `pause`/`resume` (operator),
     # `approval` (human-in-the-loop), `timeout`/`heartbeat`
     # (watchdog/liveness, observation).
@@ -61,14 +61,14 @@ module Insika
     # the flag).
     def pause_requested? = @pause_requested
 
-    # RFC-0015 §5.2 — takes the steered messages and clears the buffer, WITHOUT
+    # takes the steered messages and clears the buffer, WITHOUT
     # observing anything else in the mailbox: whatever is not a `:user_message` is put
     # back, in the order it arrived.
     #
     # Why not `drain!`: this runs INSIDE RubyLLM's tool loop (a `after_message`
     # callback), and `drain!` raises on `:cancel`. Cancellation is only ever observed
     # at the Executor's own stage boundaries — that is what keeps a tool batch one
-    # unit of work (RFC-0015 §6.4, and D7 for the same rule under `turn_timeout`).
+    # unit of work (and for the same rule under `turn_timeout`).
     # Injecting a message must not quietly become a new place a turn can die.
     def take_user_messages!
       @mailbox.size.times do

data/lib/insika/task_store.rb

@@ -131,7 +131,7 @@ module Insika
       to_task(record)
     end
 
-    # RFC-0015 §5.3 (`collect`): appends a fragment to a task's message while it is
+    # (`collect`): appends a fragment to a task's message while it is
     # still waiting at the door. -> Task.
     #
     # ONLY on :queued, and that guard is the whole safety of the feature: once a

data/lib/insika/telemetry/pricing.rb

@@ -4,7 +4,7 @@ require "json"
 
 module Insika
   module Telemetry
-    # Estimated cost of a turn, from a rates table given as DATA (item 16 / P4).
+    # Estimated cost of a turn, from a rates table given as DATA.
     #
     # Insika never ships prices: they change weekly, differ per contract and per
     # region, and a stale table in the engine would be worse than no number at all.
@@ -13,11 +13,11 @@ module Insika
     #
     # Rates are **USD per million tokens** (the unit every provider publishes):
     #
-    #   { "deepseek-chat" => { "input" => 0.27, "output" => 1.10,
+    #   { "deepseek-v4-flash" => { "input" => 0.27, "output" => 1.10,
     #                          "cached_input" => 0.07, "cache_write" => 0.34 } }
     #
     # A key matches the model id the provider reports, with or without the
-    # `provider/` prefix (`deepseek/deepseek-chat` and `deepseek-chat` both hit the
+    # `provider/` prefix (`deepseek/deepseek-v4-flash` and `deepseek-v4-flash` both hit the
     # entry above). An UNKNOWN model -> nil: a missing price is not a zero cost, so
     # nothing is emitted and the dashboard shows a gap instead of a lie.
     #

data/lib/insika/telemetry/recorder.rb

@@ -12,7 +12,7 @@ module Insika
     # insika.data_tool), correlated by task_id. Latency is the span duration; the
     # agent/tenant/model/tokens/cost ride as ATTRIBUTES.
     #
-    # METRICS (item 16 / P4): the SAME events also feed counters and histograms, so
+    # METRICS: the SAME events also feed counters and histograms, so
     # volume/latency/tokens/cost are chartable WITHOUT span aggregation (which not
     # every backend does, and none does cheaply at retention). Metric attributes are
     # a deliberate LOW-CARDINALITY subset of the span attributes — never task_id or

data/lib/insika/telemetry.rb

@@ -5,7 +5,7 @@ require_relative "telemetry/pricing"
 require_relative "telemetry/recorder"
 
 module Insika
-  # OPT-IN observability (Phase 6): OTEL mounted at the edge, core untouched. Rides
+  # OPT-IN observability: OTEL mounted at the edge, core untouched. Rides
   # the Event Stream — the Recorder consumes the events and emits spans and metrics.
   # Off (the default) -> `setup` returns nil and nothing is loaded or instrumented
   # (parity, zero overhead). The OTEL gems are only REQUIRED lazily in `setup`
@@ -17,7 +17,7 @@ module Insika
   # OTEL_* keys are the OpenTelemetry SDK's own env and stay verbatim; only our opt-in
   # toggle is renamed (INSIKA_OTEL, with the HARNESS_OTEL alias still read).
   #
-  # Metrics (item 16 / P4) ride the same switch and the SAME standard env: the SDK
+  # Metrics ride the same switch and the SAME standard env: the SDK
   # registers a periodic metric reader when the OTLP metrics exporter is loadable,
   # and `OTEL_METRICS_EXPORTER=none` turns metrics off while traces stay on. No
   # Insika-specific toggle is invented for it.