completion-kit 0.5.6 → 0.5.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bc297d90963b3ef6543ef3b2f14a94808c9a5a945047bd9ebb4b820fed1c9c9d
-  data.tar.gz: dc730069a2f27764f384068d2fab146e3cb402e24f3dfdeea33d700d50118d3a
+  metadata.gz: ea1ba2dec01de2f2ae45703edf5c0ab0b6d92845ec524729d7b71d5f5127143d
+  data.tar.gz: 8f99494d4d4037d11a004ccc5cfce7c5485aecd435617ba5fa2b7a9fc2c00c4c
 SHA512:
-  metadata.gz: c0fe08870fd298ca0ba0e5b850dc9992dbe8fc7cfebb81abb352d1543220c2925f195abd66113204f28ebfa2e48433d9ad389fc94f100ab1f8c9689edfdc6785
-  data.tar.gz: 1fc05c857f889ea0e461196471eca63d630c82a84d5447f870db9cd6bdfec9f539125d6189de27e3ee6cfc6969089105212f73e8a48485fecb8282ca886305a5
+  metadata.gz: 7550c2197cc20827bbd93d4484c8ae1ae35106566f2494cf98d3fd7fecaab95a9b267fa36ef237c0593a0649c7fcbd8fb0efc27f052a0c93fd4120556296246d
+  data.tar.gz: 82d84167a4e64f8e0400e1af7a5b115b17db7d742d4a0cb64c667a6321ccad8f08b4004284c337a76d22377865cab6a0d3290fe1b2554044787c39702eeddfd9

data/app/assets/javascripts/completion_kit/application.js

@@ -36,33 +36,32 @@ function ckAutoFocusFirstError() {
 
 function ckRelativeTime(then) {
   var seconds = Math.round((Date.now() - then.getTime()) / 1000);
-  if (seconds < 5) return "just now";
-  if (seconds < 60) return "less than a minute";
+  if (seconds < 60) return "just now";
   var minutes = Math.round(seconds / 60);
-  if (minutes < 60) return minutes === 1 ? "1 minute" : minutes + " minutes";
+  if (minutes < 60) return (minutes === 1 ? "1 minute" : minutes + " minutes") + " ago";
   var hours = Math.round(minutes / 60);
-  if (hours < 24) return hours === 1 ? "about 1 hour" : "about " + hours + " hours";
+  if (hours < 24) return (hours === 1 ? "about 1 hour" : "about " + hours + " hours") + " ago";
   var days = Math.round(hours / 24);
-  if (days < 30) return days === 1 ? "1 day" : days + " days";
+  if (days < 30) return (days === 1 ? "1 day" : days + " days") + " ago";
   var months = Math.round(days / 30);
-  if (months < 12) return months === 1 ? "about 1 month" : "about " + months + " months";
+  if (months < 12) return (months === 1 ? "about 1 month" : "about " + months + " months") + " ago";
   var years = Math.round(days / 365);
-  return years === 1 ? "about 1 year" : "about " + years + " years";
+  return (years === 1 ? "about 1 year" : "about " + years + " years") + " ago";
 }
 
 function ckRelativeTimeCompact(then) {
   var seconds = Math.round((Date.now() - then.getTime()) / 1000);
-  if (seconds < 60) return "now";
+  if (seconds < 60) return "just now";
   var minutes = Math.round(seconds / 60);
-  if (minutes < 60) return minutes + "m";
+  if (minutes < 60) return minutes + "m ago";
   var hours = Math.round(minutes / 60);
-  if (hours < 24) return hours + "h";
+  if (hours < 24) return hours + "h ago";
   var days = Math.round(hours / 24);
-  if (days < 30) return days + "d";
+  if (days < 30) return days + "d ago";
   var months = Math.round(days / 30);
-  if (months < 12) return months + "mo";
+  if (months < 12) return months + "mo ago";
   var years = Math.round(days / 365);
-  return years + "y";
+  return years + "y ago";
 }
 
 function ckTickRelativeTimes() {

data/app/assets/stylesheets/completion_kit/application.css

@@ -2695,7 +2695,8 @@ select.ck-input {
 #ck-tab-responses:checked ~ .ck-api-tabs__nav label[for="ck-tab-responses"],
 #ck-tab-datasets:checked ~ .ck-api-tabs__nav label[for="ck-tab-datasets"],
 #ck-tab-metrics:checked ~ .ck-api-tabs__nav label[for="ck-tab-metrics"],
-#ck-tab-criteria:checked ~ .ck-api-tabs__nav label[for="ck-tab-criteria"],
+#ck-tab-metric-groups:checked ~ .ck-api-tabs__nav label[for="ck-tab-metric-groups"],
+#ck-tab-tags:checked ~ .ck-api-tabs__nav label[for="ck-tab-tags"],
 #ck-tab-providers:checked ~ .ck-api-tabs__nav label[for="ck-tab-providers"] {
   color: var(--ck-accent);
   background: var(--ck-surface-soft);
@@ -2708,8 +2709,9 @@ select.ck-input {
 #ck-tab-responses:checked ~ .ck-api-tabs__panels .ck-api-tabs__panel:nth-child(4),
 #ck-tab-datasets:checked ~ .ck-api-tabs__panels .ck-api-tabs__panel:nth-child(5),
 #ck-tab-metrics:checked ~ .ck-api-tabs__panels .ck-api-tabs__panel:nth-child(6),
-#ck-tab-criteria:checked ~ .ck-api-tabs__panels .ck-api-tabs__panel:nth-child(7),
-#ck-tab-providers:checked ~ .ck-api-tabs__panels .ck-api-tabs__panel:nth-child(8) {
+#ck-tab-metric-groups:checked ~ .ck-api-tabs__panels .ck-api-tabs__panel:nth-child(7),
+#ck-tab-tags:checked ~ .ck-api-tabs__panels .ck-api-tabs__panel:nth-child(8),
+#ck-tab-providers:checked ~ .ck-api-tabs__panels .ck-api-tabs__panel:nth-child(9) {
   display: block;
 }
 
@@ -2741,7 +2743,8 @@ select.ck-input {
   #ck-tab-responses:checked ~ .ck-api-tabs__nav label[for="ck-tab-responses"],
   #ck-tab-datasets:checked ~ .ck-api-tabs__nav label[for="ck-tab-datasets"],
   #ck-tab-metrics:checked ~ .ck-api-tabs__nav label[for="ck-tab-metrics"],
-  #ck-tab-criteria:checked ~ .ck-api-tabs__nav label[for="ck-tab-criteria"],
+  #ck-tab-metric-groups:checked ~ .ck-api-tabs__nav label[for="ck-tab-metric-groups"],
+  #ck-tab-tags:checked ~ .ck-api-tabs__nav label[for="ck-tab-tags"],
   #ck-tab-providers:checked ~ .ck-api-tabs__nav label[for="ck-tab-providers"] {
     border-left-color: transparent;
     border-bottom-color: var(--ck-accent);
@@ -2752,9 +2755,17 @@ select.ck-input {
   }
 }
 
+/* the metrics field stacks several sub-sections (hint, groups, divider, tag
+   filter, checkboxes) — give it more vertical breathing room than a plain field,
+   and extra separation from the run-tags field that follows it */
+#metrics-field {
+  gap: 0.85rem;
+  margin-bottom: 1.25rem;
+}
+
 .ck-metric-groups {
   display: grid;
-  gap: 0.4rem;
+  gap: 0.55rem;
   margin-bottom: 0.5rem;
 }
 
@@ -2770,7 +2781,7 @@ select.ck-input {
 .ck-metric-groups__row {
   display: flex;
   flex-wrap: wrap;
-  gap: 0.4rem;
+  gap: 0.5rem;
 }
 
 .ck-metric-group-pill {

data/app/controllers/completion_kit/runs_controller.rb

@@ -28,6 +28,11 @@ module CompletionKit
 
     def new
       @run = Run.new(prompt_id: params[:prompt_id])
+      prompt = Prompt.find_by(id: @run.prompt_id)
+      if prompt
+        last_run = Run.where(prompt_id: prompt.family_versions.ids).order(created_at: :desc).first
+        @run.tag_names = last_run.tag_names if last_run
+      end
     end
 
     def edit
@@ -45,7 +50,7 @@ module CompletionKit
     end
 
     def update
-      if @run.responses.any?
+      if @run.responses.any? && run_generation_changed?
         attrs = run_params.except(:metric_ids).to_h
         attrs.delete("name") if attrs["name"].to_s == @run.name.to_s
         new_run = Run.create!(attrs.merge(status: "pending"))
@@ -79,6 +84,7 @@ module CompletionKit
         dataset_id: @run.dataset_id,
         judge_model: @run.judge_model,
         temperature: @run.temperature,
+        tag_names: @run.tag_names,
         status: "pending"
       )
       new_run.replace_metrics!(@run.metric_ids)
@@ -156,5 +162,29 @@ module CompletionKit
       params.require(:run).permit(:name, :prompt_id, :dataset_id, :judge_model, :temperature, metric_ids: [], tag_names: [])
     end
 
+    # Editing a run that already has results forks a new run — but only when a
+    # field that affects generation or judging changed. Renaming or retagging is
+    # pure metadata and updates the run in place.
+    GENERATION_RUN_FIELDS = %i[prompt_id dataset_id judge_model temperature].freeze
+
+    def run_generation_changed?
+      GENERATION_RUN_FIELDS.each do |field|
+        next unless run_params.key?(field)
+        return true if normalize_run_field(field, run_params[field]) != normalize_run_field(field, @run.public_send(field))
+      end
+      return false unless params[:run].key?(:metric_ids)
+      Array(params[:run][:metric_ids]).map(&:to_i).reject(&:zero?).sort != @run.metric_ids.sort
+    end
+
+    def normalize_run_field(field, value)
+      s = value.to_s.strip
+      return nil if s.empty?
+      case field
+      when :temperature then s.to_f
+      when :prompt_id, :dataset_id then s.to_i
+      else s
+      end
+    end
+
   end
 end

data/app/helpers/completion_kit/application_helper.rb

@@ -72,6 +72,12 @@ module CompletionKit
       CompletionKit::ProviderCredential::PROVIDER_LABELS[provider.to_s] || provider.to_s.titleize
     end
 
+    def ck_masked_token(token)
+      return "YOUR_TOKEN" if token.blank?
+      return "••••••••" if token.length < 12
+      "#{token[0..3]}#{'•' * [token.length - 8, 4].max}#{token[-4..]}"
+    end
+
     OPENAI_MODEL_FAMILY_ORDER = ["GPT-5", "GPT-4", "o-series", "GPT-3.5", "GPT-OSS", "Other"].freeze
 
     def ck_openai_model_family(model_id)

data/app/services/completion_kit/worker_health.rb

@@ -1,6 +1,9 @@
 module CompletionKit
   class WorkerHealth
-    HEARTBEAT_THRESHOLD = 30.seconds
+    # SolidQueue workers heartbeat every SolidQueue.process_heartbeat_interval
+    # (60s by default), so a 30s window flagged healthy workers as down between
+    # beats. Allow two missed heartbeats before we say the worker is gone.
+    HEARTBEAT_THRESHOLD = 2.minutes
 
     def self.healthy?
       return true unless defined?(::SolidQueue::Process)

data/app/views/completion_kit/api_reference/_authentication.html.erb

@@ -0,0 +1,11 @@
+<% if token.present? %>
+  <% masked = ck_masked_token(token) %>
+  <div style="display: flex; align-items: center; gap: 0.4rem; margin: 0.5rem 0;">
+    <button type="button" class="ck-chip ck-token-toggle" onclick="ckToggleToken(this)" data-masked="<%= masked %>" data-real="<%= token %>" aria-label="Reveal API token" aria-pressed="false" style="cursor: pointer;"><%= masked %></button>
+    <button type="button" class="ck-icon-btn" title="Copy token" aria-label="Copy API token" onclick="var b=this;navigator.clipboard.writeText('<%= token %>').then(function(){b.classList.add('ck-api-copy--done');setTimeout(function(){b.classList.remove('ck-api-copy--done')},1500)})">
+      <%= heroicon_tag "clipboard-document", variant: :outline, size: 14, "aria-hidden": "true" %>
+    </button>
+  </div>
+<% else %>
+  <p class="ck-meta-copy">No API token configured. Set <code>COMPLETION_KIT_API_TOKEN</code> to enable API access.</p>
+<% end %>

data/app/views/completion_kit/api_reference/_body.html.erb

@@ -0,0 +1,310 @@
+<%
+  token = local_assigns.fetch(:token, "YOUR_TOKEN")
+  real_token = local_assigns.fetch(:real_token, nil)
+  published_prompts = local_assigns.fetch(:published_prompts, [])
+%>
+<div class="ck-api-tabs">
+  <input type="radio" name="ck-api-tab" id="ck-tab-mcp" class="ck-api-tabs__radio" checked>
+  <input type="radio" name="ck-api-tab" id="ck-tab-prompts" class="ck-api-tabs__radio">
+  <input type="radio" name="ck-api-tab" id="ck-tab-runs" class="ck-api-tabs__radio">
+  <input type="radio" name="ck-api-tab" id="ck-tab-responses" class="ck-api-tabs__radio">
+  <input type="radio" name="ck-api-tab" id="ck-tab-datasets" class="ck-api-tabs__radio">
+  <input type="radio" name="ck-api-tab" id="ck-tab-metrics" class="ck-api-tabs__radio">
+  <input type="radio" name="ck-api-tab" id="ck-tab-metric-groups" class="ck-api-tabs__radio">
+  <input type="radio" name="ck-api-tab" id="ck-tab-tags" class="ck-api-tabs__radio">
+  <input type="radio" name="ck-api-tab" id="ck-tab-providers" class="ck-api-tabs__radio">
+
+  <nav class="ck-api-tabs__nav">
+    <label for="ck-tab-mcp" class="ck-api-tabs__label">MCP <span class="ck-api-tabs__count">35</span></label>
+    <label for="ck-tab-prompts" class="ck-api-tabs__label">Prompts <span class="ck-api-tabs__count">6</span></label>
+    <label for="ck-tab-runs" class="ck-api-tabs__label">Runs <span class="ck-api-tabs__count">7</span></label>
+    <label for="ck-tab-responses" class="ck-api-tabs__label">Responses <span class="ck-api-tabs__count">2</span></label>
+    <label for="ck-tab-datasets" class="ck-api-tabs__label">Datasets <span class="ck-api-tabs__count">5</span></label>
+    <label for="ck-tab-metrics" class="ck-api-tabs__label">Metrics <span class="ck-api-tabs__count">5</span></label>
+    <label for="ck-tab-metric-groups" class="ck-api-tabs__label">Metric Groups <span class="ck-api-tabs__count">5</span></label>
+    <label for="ck-tab-tags" class="ck-api-tabs__label">Tags <span class="ck-api-tabs__count">5</span></label>
+    <label for="ck-tab-providers" class="ck-api-tabs__label">Providers <span class="ck-api-tabs__count">5</span></label>
+  </nav>
+
+  <div class="ck-api-tabs__panels">
+
+    <div class="ck-api-tabs__panel">
+      <h2 class="ck-section-title">MCP Server</h2>
+      <p class="ck-copy">Connect Claude Code, Cursor, or any <a href="https://modelcontextprotocol.io" class="ck-link">MCP</a> client to manage prompts, runs, datasets, and metrics conversationally. 35 tools over streamable HTTP.</p>
+
+      <div class="ck-mcp-install-grid">
+        <div class="ck-mcp-install-card">
+          <div class="ck-mcp-install-card__header">
+            <span class="ck-mcp-install-card__icon">&#9654;</span>
+            Claude Code
+          </div>
+          <%= render "completion_kit/api_reference/example", base_url: base_url, token: token, real_token: real_token, cmd: "claude mcp add completion-kit \\\n  --transport http \\\n  --url #{base_url}/mcp \\\n  --header \"Authorization: Bearer #{token}\"" %>
+        </div>
+        <div class="ck-mcp-install-card">
+          <div class="ck-mcp-install-card__header">
+            <span class="ck-mcp-install-card__icon">{}</span>
+            Cursor / Generic
+          </div>
+          <%= render "completion_kit/api_reference/example", base_url: base_url, token: token, real_token: real_token, cmd: "{\n  \"mcpServers\": {\n    \"completion-kit\": {\n      \"url\": \"#{base_url}/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer #{token}\"\n      }\n    }\n  }\n}" %>
+        </div>
+      </div>
+
+      <div class="ck-api-endpoint" style="padding-top: 1.5rem;">
+        <p class="ck-kicker" style="margin-bottom: 0.75rem;">Available tools</p>
+        <% grouped = CompletionKit::McpDispatcher.tool_definitions.group_by { |t| t[:name].split("_").first } %>
+        <% grouped.each do |group, tools| %>
+          <div class="ck-mcp-tool-group">
+            <p class="ck-mcp-tool-group__label"><%= group %> <span class="ck-api-tabs__count"><%= tools.size %></span></p>
+            <div class="ck-mcp-tools">
+              <% tools.each do |tool| %>
+                <div class="ck-mcp-tool">
+                  <code class="ck-mcp-tool__name"><%= tool[:name] %></code>
+                  <span class="ck-mcp-tool__desc"><%= tool[:description] %></span>
+                </div>
+              <% end %>
+            </div>
+          </div>
+        <% end %>
+      </div>
+    </div>
+
+    <div class="ck-api-tabs__panel">
+      <h2 class="ck-section-title">Prompts</h2>
+      <p class="ck-copy">Create, version, and manage LLM prompt templates.</p>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/prompts</p>
+        <p class="ck-meta-copy">List all prompts, ordered by most recent.</p>
+        <%= render "completion_kit/api_reference/example", base_url: base_url, token: token, real_token: real_token, cmd: "curl #{base_url}/api/v1/prompts \\\n  -H \"Authorization: Bearer #{token}\"" %>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/prompts</p>
+        <p class="ck-meta-copy">Create a new prompt.</p>
+        <p class="ck-api-params"><strong>Required:</strong>&ensp;<code>name</code>, <code>template</code>, <code>llm_model</code>&emsp;<strong>Optional:</strong>&ensp;<code>description</code></p>
+        <%= render "completion_kit/api_reference/example", base_url: base_url, token: token, real_token: real_token, cmd: "curl -X POST #{base_url}/api/v1/prompts \\\n  -H \"Authorization: Bearer #{token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"summarizer\", \"template\": \"Summarize: {{text}}\", \"llm_model\": \"gpt-4.1\"}'" %>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/prompts/:id</p>
+        <p class="ck-meta-copy">Get a single prompt by ID.</p>
+      </div>
+      <% if published_prompts.any? %>
+        <div class="ck-api-endpoint" style="padding-top: 1rem;">
+          <p class="ck-kicker" style="margin-bottom: 0.5rem;">Your published prompts</p>
+          <% published_prompts.each do |p| %>
+            <div class="ck-api-prompt-card">
+              <div class="ck-api-prompt-card__top">
+                <div>
+                  <strong class="ck-api-prompt-card__name"><%= p.name %></strong>
+                  <% if p.description.present? %>
+                    <p class="ck-api-prompt-card__desc"><%= p.description %></p>
+                  <% end %>
+                </div>
+                <span class="ck-chip" style="text-transform: none; flex-shrink: 0;"><%= p.llm_model %></span>
+              </div>
+              <div class="ck-api-prompt-card__url">
+                <code class="ck-endpoint__url" id="prompt_ep_<%= p.id %>"><%= base_url %>/api/v1/prompts/<%= p.slug %></code>
+                <button type="button" class="ck-icon-btn" title="Copy endpoint" aria-label="Copy endpoint URL" onclick="navigator.clipboard.writeText(document.getElementById('prompt_ep_<%= p.id %>').textContent)"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor" width="14" height="14" aria-hidden="true"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"/><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"/></svg></button>
+              </div>
+            </div>
+          <% end %>
+        </div>
+      <% end %>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">PATCH</span> /api/v1/prompts/:id</p>
+        <p class="ck-meta-copy">Update a prompt. Accepts same params as create.</p>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip" style="color: var(--ck-danger);">DELETE</span> /api/v1/prompts/:id</p>
+        <p class="ck-meta-copy">Delete a prompt. Returns 204 No Content.</p>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/prompts/:id/publish</p>
+        <p class="ck-meta-copy">Publish a prompt version, making it the current version in its family.</p>
+      </div>
+    </div>
+
+    <div class="ck-api-tabs__panel">
+      <h2 class="ck-section-title">Runs</h2>
+      <p class="ck-copy">Create runs, generate LLM responses, and judge them with metrics.</p>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/runs</p>
+        <p class="ck-meta-copy">List all runs with response counts and average scores.</p>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/runs</p>
+        <p class="ck-meta-copy">Create a new run.</p>
+        <p class="ck-api-params"><strong>Required:</strong>&ensp;<code>prompt_id</code>&emsp;<strong>Optional:</strong>&ensp;<code>name</code>, <code>dataset_id</code>, <code>metric_ids</code>, <code>judge_model</code></p>
+        <%= render "completion_kit/api_reference/example", base_url: base_url, token: token, real_token: real_token, cmd: "curl -X POST #{base_url}/api/v1/runs \\\n  -H \"Authorization: Bearer #{token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"prompt_id\": 1, \"dataset_id\": 1, \"metric_ids\": [1, 2]}'" %>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/runs/:id</p>
+        <p class="ck-meta-copy">Get a run with status, progress, response count, and average score.</p>
+        <%= render "completion_kit/api_reference/example", base_url: base_url, token: token, real_token: real_token, cmd: "curl #{base_url}/api/v1/runs/1 \\\n  -H \"Authorization: Bearer #{token}\"" %>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/runs/:id/generate</p>
+        <p class="ck-meta-copy">Start generating responses. Returns 202 Accepted. Poll the run to check progress.</p>
+        <%= render "completion_kit/api_reference/example", base_url: base_url, token: token, real_token: real_token, cmd: "curl -X POST #{base_url}/api/v1/runs/1/generate \\\n  -H \"Authorization: Bearer #{token}\"" %>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">PATCH</span> /api/v1/runs/:id</p>
+        <p class="ck-meta-copy">Update a run. Accepts same params as create.</p>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip" style="color: var(--ck-danger);">DELETE</span> /api/v1/runs/:id</p>
+        <p class="ck-meta-copy">Delete a run and all its responses. Returns 204 No Content.</p>
+      </div>
+    </div>
+
+    <div class="ck-api-tabs__panel">
+      <h2 class="ck-section-title">Responses</h2>
+      <p class="ck-copy">Read-only access to generated responses and their review scores. Nested under runs.</p>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/runs/:run_id/responses</p>
+        <p class="ck-meta-copy">List all responses for a run, including nested review scores.</p>
+        <%= render "completion_kit/api_reference/example", base_url: base_url, token: token, real_token: real_token, cmd: "curl #{base_url}/api/v1/runs/1/responses \\\n  -H \"Authorization: Bearer #{token}\"" %>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/runs/:run_id/responses/:id</p>
+        <p class="ck-meta-copy">Get a single response with its review scores and feedback.</p>
+      </div>
+    </div>
+
+    <div class="ck-api-tabs__panel">
+      <h2 class="ck-section-title">Datasets</h2>
+      <p class="ck-copy">Data used as input for runs.</p>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/datasets</p>
+        <p class="ck-meta-copy">List all datasets.</p>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/datasets</p>
+        <p class="ck-meta-copy">Create a dataset.</p>
+        <p class="ck-api-params"><strong>Required:</strong>&ensp;<code>name</code>, <code>csv_data</code></p>
+        <%= render "completion_kit/api_reference/example", base_url: base_url, token: token, real_token: real_token, cmd: "curl -X POST #{base_url}/api/v1/datasets \\\n  -H \"Authorization: Bearer #{token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"tickets\", \"csv_data\": \"text,expected_output\\\\nHello,Hi\"}'" %>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span>&ensp;<span class="ck-chip ck-chip--soft">PATCH</span>&ensp;<span class="ck-chip" style="color: var(--ck-danger);">DELETE</span> /api/v1/datasets/:id</p>
+        <p class="ck-meta-copy">Get, update, or delete a dataset.</p>
+      </div>
+    </div>
+
+    <div class="ck-api-tabs__panel">
+      <h2 class="ck-section-title">Metrics</h2>
+      <p class="ck-copy">Scoring dimensions used by the judge model.</p>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/metrics</p>
+        <p class="ck-meta-copy">List all metrics.</p>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/metrics</p>
+        <p class="ck-meta-copy">Create a metric.</p>
+        <p class="ck-api-params"><strong>Required:</strong>&ensp;<code>name</code>&emsp;<strong>Optional:</strong>&ensp;<code>instruction</code>, <code>rubric_bands</code> (array of {stars, description})</p>
+        <%= render "completion_kit/api_reference/example", base_url: base_url, token: token, real_token: real_token, cmd: "curl -X POST #{base_url}/api/v1/metrics \\\n  -H \"Authorization: Bearer #{token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"relevance\", \"instruction\": \"Is the response relevant?\"}'" %>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span>&ensp;<span class="ck-chip ck-chip--soft">PATCH</span>&ensp;<span class="ck-chip" style="color: var(--ck-danger);">DELETE</span> /api/v1/metrics/:id</p>
+        <p class="ck-meta-copy">Get, update, or delete a metric.</p>
+      </div>
+    </div>
+
+    <div class="ck-api-tabs__panel">
+      <h2 class="ck-section-title">Metric Groups</h2>
+      <p class="ck-copy">Named groups of metrics you can apply to a run as a set.</p>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/metric_groups</p>
+        <p class="ck-meta-copy">List all metric groups with their metric IDs.</p>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/metric_groups</p>
+        <p class="ck-meta-copy">Create a metric group.</p>
+        <p class="ck-api-params"><strong>Required:</strong>&ensp;<code>name</code>&emsp;<strong>Optional:</strong>&ensp;<code>description</code>, <code>metric_ids</code> (array)</p>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span>&ensp;<span class="ck-chip ck-chip--soft">PATCH</span>&ensp;<span class="ck-chip" style="color: var(--ck-danger);">DELETE</span> /api/v1/metric_groups/:id</p>
+        <p class="ck-meta-copy">Get, update, or delete a metric group. PATCH with <code>metric_ids</code> replaces all metric associations.</p>
+      </div>
+    </div>
+
+    <div class="ck-api-tabs__panel">
+      <h2 class="ck-section-title">Tags</h2>
+      <p class="ck-copy">Domain labels you can attach to metrics, prompts, runs, and datasets. Tags are auto-assigned a color from a 10-color palette. Each index page can be filtered by one or more tags using <code>?tag[]=name</code> query params (OR semantics).</p>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/tags</p>
+        <p class="ck-meta-copy">List all tags with name and color.</p>
+        <%= render "completion_kit/api_reference/example", base_url: base_url, token: token, real_token: real_token, cmd: "curl #{base_url}/api/v1/tags \\\n  -H \"Authorization: Bearer #{token}\"" %>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/tags</p>
+        <p class="ck-meta-copy">Create a tag.</p>
+        <p class="ck-api-params"><strong>Required:</strong>&ensp;<code>name</code></p>
+        <%= render "completion_kit/api_reference/example", base_url: base_url, token: token, real_token: real_token, cmd: "curl -X POST #{base_url}/api/v1/tags \\\n  -H \"Authorization: Bearer #{token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"real estate\"}'" %>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span>&ensp;<span class="ck-chip ck-chip--soft">PATCH</span>&ensp;<span class="ck-chip" style="color: var(--ck-danger);">DELETE</span> /api/v1/tags/:id</p>
+        <p class="ck-meta-copy">Get, update, or delete a tag. PATCH accepts <code>name</code>. DELETE returns 204 No Content and removes all taggings for this tag.</p>
+      </div>
+      <div class="ck-api-endpoint" style="padding-top: 1rem;">
+        <p class="ck-kicker" style="margin-bottom: 0.5rem;">Tagging resources</p>
+        <p class="ck-meta-copy">Metrics, prompts, runs, and datasets accept a <code>tag_names</code> array on their create and update endpoints. Passing a name that does not yet exist silently creates the tag. On PATCH, the list replaces all existing tags for that record (omit the field to leave tags unchanged).</p>
+        <%= render "completion_kit/api_reference/example", base_url: base_url, token: token, real_token: real_token, cmd: "curl -X POST #{base_url}/api/v1/metrics \\\n  -H \"Authorization: Bearer #{token}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"Accuracy\", \"tag_names\": [\"real estate\"]}'" %>
+      </div>
+      <div class="ck-api-endpoint" style="padding-top: 1rem;">
+        <p class="ck-kicker" style="margin-bottom: 0.5rem;">MCP tools</p>
+        <div class="ck-mcp-tools">
+          <div class="ck-mcp-tool"><code class="ck-mcp-tool__name">tags_list</code><span class="ck-mcp-tool__desc">List all tags</span></div>
+          <div class="ck-mcp-tool"><code class="ck-mcp-tool__name">tags_get</code><span class="ck-mcp-tool__desc">Get a tag by ID</span></div>
+          <div class="ck-mcp-tool"><code class="ck-mcp-tool__name">tags_create</code><span class="ck-mcp-tool__desc">Create a tag (name required)</span></div>
+          <div class="ck-mcp-tool"><code class="ck-mcp-tool__name">tags_update</code><span class="ck-mcp-tool__desc">Update a tag's name</span></div>
+          <div class="ck-mcp-tool"><code class="ck-mcp-tool__name">tags_delete</code><span class="ck-mcp-tool__desc">Delete a tag and remove all its taggings</span></div>
+        </div>
+        <p class="ck-meta-copy" style="margin-top: 0.75rem;">The existing <code>metrics_create</code>, <code>metrics_update</code>, <code>prompts_create</code>, <code>prompts_update</code>, <code>runs_create</code>, <code>runs_update</code>, <code>datasets_create</code>, and <code>datasets_update</code> tools all accept a <code>tag_names</code> parameter with the same auto-create and replace semantics as the REST API.</p>
+      </div>
+    </div>
+
+    <div class="ck-api-tabs__panel">
+      <h2 class="ck-section-title">Provider Credentials</h2>
+      <p class="ck-copy">LLM provider API keys. The <code>api_key</code> field is write-only and never returned in responses.</p>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/provider_credentials</p>
+        <p class="ck-meta-copy">List all provider credentials (api_key excluded).</p>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/provider_credentials</p>
+        <p class="ck-meta-copy">Create a provider credential.</p>
+        <p class="ck-api-params"><strong>Required:</strong>&ensp;<code>provider</code> (openai, anthropic, ollama, openrouter), <code>api_key</code>&emsp;<strong>Optional:</strong>&ensp;<code>api_endpoint</code></p>
+      </div>
+      <div class="ck-api-endpoint">
+        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span>&ensp;<span class="ck-chip ck-chip--soft">PATCH</span>&ensp;<span class="ck-chip" style="color: var(--ck-danger);">DELETE</span> /api/v1/provider_credentials/:id</p>
+        <p class="ck-meta-copy">Get, update, or delete a provider credential.</p>
+      </div>
+    </div>
+
+  </div>
+</div>
+
+<script>
+function ckToggleToken(el) {
+  var showing = el.textContent === el.dataset.masked;
+  el.textContent = showing ? el.dataset.real : el.dataset.masked;
+  el.setAttribute('aria-pressed', showing ? 'true' : 'false');
+  el.setAttribute('aria-label', showing ? 'Hide API token' : 'Reveal API token');
+  navigator.clipboard.writeText(el.dataset.real).then(function() {
+    el.classList.add('ck-api-copy--done');
+    setTimeout(function() { el.classList.remove('ck-api-copy--done'); }, 1500);
+  });
+}
+
+function ckCopyExample(btn) {
+  var pre = btn.closest('.ck-api-example').querySelector('pre');
+  var text = pre.textContent;
+  var realToken = btn.dataset.realToken;
+  var displayToken = btn.dataset.displayToken;
+  if (realToken && displayToken) {
+    text = text.split(displayToken).join(realToken);
+  }
+  navigator.clipboard.writeText(text).then(function() {
+    btn.classList.add('ck-api-copy--done');
+    setTimeout(function() { btn.classList.remove('ck-api-copy--done'); }, 1500);
+  });
+}
+</script>

data/app/views/completion_kit/api_reference/index.html.erb

@@ -1,11 +1,3 @@
-<% token_display = if @token.present? && @token.length >= 12
-  "#{@token[0..3]}#{'•' * [@token.length - 8, 4].max}#{@token[-4..]}"
-elsif @token.present?
-  "••••••••"
-else
-  "YOUR_TOKEN"
-end %>
-
 <section class="ck-page-header">
   <div>
     <h1 class="ck-title">API</h1>
@@ -18,324 +10,14 @@ end %>
     <div class="ck-split">
       <div>
         <p class="ck-kicker">Authentication</p>
-        <% if @token.present? %>
-          <div style="display: flex; align-items: center; gap: 0.4rem; margin: 0.5rem 0;">
-            <button type="button" class="ck-chip ck-token-toggle" onclick="ckToggleToken(this)" data-masked="<%= token_display %>" data-real="<%= @token %>" aria-label="Reveal API token" aria-pressed="false" style="cursor: pointer;"><%= token_display %></button>
-            <button type="button" class="ck-icon-btn" title="Copy token" aria-label="Copy API token" onclick="var b=this;navigator.clipboard.writeText('<%= @token %>').then(function(){b.classList.add('ck-api-copy--done');setTimeout(function(){b.classList.remove('ck-api-copy--done')},1500)})">
-              <%= heroicon_tag "clipboard-document", variant: :outline, size: 14, "aria-hidden": "true" %>
-            </button>
-          </div>
-        <% else %>
-          <p class="ck-meta-copy">No API token configured. Set <code>COMPLETION_KIT_API_TOKEN</code> to enable API access.</p>
-        <% end %>
-      </div>
-    </div>
-  </div>
-</div>
-
-<% if @published_prompts.any? %>
-  <div class="ck-api-prompts-section">
-    <p class="ck-kicker">Your prompts</p>
-    <% @published_prompts.each do |p| %>
-      <div class="ck-api-prompt-card">
-        <div class="ck-api-prompt-card__top">
-          <div>
-            <strong class="ck-api-prompt-card__name"><%= p.name %></strong>
-            <% if p.description.present? %>
-              <p class="ck-api-prompt-card__desc"><%= p.description %></p>
-            <% end %>
-          </div>
-          <span class="ck-chip" style="text-transform: none; flex-shrink: 0;"><%= p.llm_model %></span>
-        </div>
-        <div class="ck-api-prompt-card__url">
-          <code class="ck-endpoint__url" id="prompt_ep_<%= p.id %>"><%= @base_url %>/api/v1/prompts/<%= p.slug %></code>
-          <button type="button" class="ck-icon-btn" title="Copy endpoint" aria-label="Copy endpoint URL" onclick="navigator.clipboard.writeText(document.getElementById('prompt_ep_<%= p.id %>').textContent)"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor" width="14" height="14" aria-hidden="true"><path d="M0 6.75C0 5.784.784 5 1.75 5h1.5a.75.75 0 0 1 0 1.5h-1.5a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-1.5a.75.75 0 0 1 1.5 0v1.5A1.75 1.75 0 0 1 9.25 16h-7.5A1.75 1.75 0 0 1 0 14.25Z"/><path d="M5 1.75C5 .784 5.784 0 6.75 0h7.5C15.216 0 16 .784 16 1.75v7.5A1.75 1.75 0 0 1 14.25 11h-7.5A1.75 1.75 0 0 1 5 9.25Zm1.75-.25a.25.25 0 0 0-.25.25v7.5c0 .138.112.25.25.25h7.5a.25.25 0 0 0 .25-.25v-7.5a.25.25 0 0 0-.25-.25Z"/></svg></button>
-        </div>
-      </div>
-    <% end %>
-  </div>
-<% end %>
-
-<div class="ck-api-tabs">
-  <input type="radio" name="ck-api-tab" id="ck-tab-mcp" class="ck-api-tabs__radio" checked>
-  <input type="radio" name="ck-api-tab" id="ck-tab-prompts" class="ck-api-tabs__radio">
-  <input type="radio" name="ck-api-tab" id="ck-tab-runs" class="ck-api-tabs__radio">
-  <input type="radio" name="ck-api-tab" id="ck-tab-responses" class="ck-api-tabs__radio">
-  <input type="radio" name="ck-api-tab" id="ck-tab-datasets" class="ck-api-tabs__radio">
-  <input type="radio" name="ck-api-tab" id="ck-tab-metrics" class="ck-api-tabs__radio">
-  <input type="radio" name="ck-api-tab" id="ck-tab-metric-groups" class="ck-api-tabs__radio">
-  <input type="radio" name="ck-api-tab" id="ck-tab-tags" class="ck-api-tabs__radio">
-  <input type="radio" name="ck-api-tab" id="ck-tab-providers" class="ck-api-tabs__radio">
-
-  <nav class="ck-api-tabs__nav">
-    <label for="ck-tab-mcp" class="ck-api-tabs__label">MCP <span class="ck-api-tabs__count">35</span></label>
-    <label for="ck-tab-prompts" class="ck-api-tabs__label">Prompts <span class="ck-api-tabs__count">6</span></label>
-    <label for="ck-tab-runs" class="ck-api-tabs__label">Runs <span class="ck-api-tabs__count">7</span></label>
-    <label for="ck-tab-responses" class="ck-api-tabs__label">Responses <span class="ck-api-tabs__count">2</span></label>
-    <label for="ck-tab-datasets" class="ck-api-tabs__label">Datasets <span class="ck-api-tabs__count">5</span></label>
-    <label for="ck-tab-metrics" class="ck-api-tabs__label">Metrics <span class="ck-api-tabs__count">5</span></label>
-    <label for="ck-tab-metric-groups" class="ck-api-tabs__label">Metric Groups <span class="ck-api-tabs__count">5</span></label>
-    <label for="ck-tab-tags" class="ck-api-tabs__label">Tags <span class="ck-api-tabs__count">5</span></label>
-    <label for="ck-tab-providers" class="ck-api-tabs__label">Providers <span class="ck-api-tabs__count">5</span></label>
-  </nav>
-
-  <div class="ck-api-tabs__panels">
-
-    <div class="ck-api-tabs__panel">
-      <h2 class="ck-section-title">MCP Server</h2>
-      <p class="ck-copy">Connect Claude Code, Cursor, or any <a href="https://modelcontextprotocol.io" class="ck-link">MCP</a> client to manage prompts, runs, datasets, and metrics conversationally. 35 tools over streamable HTTP.</p>
-
-      <div class="ck-mcp-install-grid">
-        <div class="ck-mcp-install-card">
-          <div class="ck-mcp-install-card__header">
-            <span class="ck-mcp-install-card__icon">&#9654;</span>
-            Claude Code
-          </div>
-          <%= render "example", base_url: @base_url, token: token_display, real_token: @token, cmd: "claude mcp add completion-kit \\\n  --transport http \\\n  --url #{@base_url}/mcp \\\n  --header \"Authorization: Bearer #{token_display}\"" %>
-        </div>
-        <div class="ck-mcp-install-card">
-          <div class="ck-mcp-install-card__header">
-            <span class="ck-mcp-install-card__icon">{}</span>
-            Cursor / Generic
-          </div>
-          <%= render "example", base_url: @base_url, token: token_display, real_token: @token, cmd: "{\n  \"mcpServers\": {\n    \"completion-kit\": {\n      \"url\": \"#{@base_url}/mcp\",\n      \"headers\": {\n        \"Authorization\": \"Bearer #{token_display}\"\n      }\n    }\n  }\n}" %>
-        </div>
-      </div>
-
-      <div class="ck-api-endpoint" style="padding-top: 1.5rem;">
-        <p class="ck-kicker" style="margin-bottom: 0.75rem;">Available tools</p>
-        <% grouped = CompletionKit::McpDispatcher.tool_definitions.group_by { |t| t[:name].split("_").first } %>
-        <% grouped.each do |group, tools| %>
-          <div class="ck-mcp-tool-group">
-            <p class="ck-mcp-tool-group__label"><%= group %> <span class="ck-api-tabs__count"><%= tools.size %></span></p>
-            <div class="ck-mcp-tools">
-              <% tools.each do |tool| %>
-                <div class="ck-mcp-tool">
-                  <code class="ck-mcp-tool__name"><%= tool[:name] %></code>
-                  <span class="ck-mcp-tool__desc"><%= tool[:description] %></span>
-                </div>
-              <% end %>
-            </div>
-          </div>
-        <% end %>
-      </div>
-    </div>
-
-    <div class="ck-api-tabs__panel">
-      <h2 class="ck-section-title">Prompts</h2>
-      <p class="ck-copy">Create, version, and manage LLM prompt templates.</p>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/prompts</p>
-        <p class="ck-meta-copy">List all prompts, ordered by most recent.</p>
-        <%= render "example", base_url: @base_url, token: token_display, real_token: @token, cmd: "curl #{@base_url}/api/v1/prompts \\\n  -H \"Authorization: Bearer #{token_display}\"" %>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/prompts</p>
-        <p class="ck-meta-copy">Create a new prompt.</p>
-        <p class="ck-api-params"><strong>Required:</strong>&ensp;<code>name</code>, <code>template</code>, <code>llm_model</code>&emsp;<strong>Optional:</strong>&ensp;<code>description</code></p>
-        <%= render "example", base_url: @base_url, token: token_display, real_token: @token, cmd: "curl -X POST #{@base_url}/api/v1/prompts \\\n  -H \"Authorization: Bearer #{token_display}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"summarizer\", \"template\": \"Summarize: {{text}}\", \"llm_model\": \"gpt-4.1\"}'" %>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/prompts/:id</p>
-        <p class="ck-meta-copy">Get a single prompt by ID.</p>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">PATCH</span> /api/v1/prompts/:id</p>
-        <p class="ck-meta-copy">Update a prompt. Accepts same params as create.</p>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip" style="color: var(--ck-danger);">DELETE</span> /api/v1/prompts/:id</p>
-        <p class="ck-meta-copy">Delete a prompt. Returns 204 No Content.</p>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/prompts/:id/publish</p>
-        <p class="ck-meta-copy">Publish a prompt version, making it the current version in its family.</p>
-      </div>
-    </div>
-
-    <div class="ck-api-tabs__panel">
-      <h2 class="ck-section-title">Runs</h2>
-      <p class="ck-copy">Create runs, generate LLM responses, and judge them with metrics.</p>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/runs</p>
-        <p class="ck-meta-copy">List all runs with response counts and average scores.</p>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/runs</p>
-        <p class="ck-meta-copy">Create a new run.</p>
-        <p class="ck-api-params"><strong>Required:</strong>&ensp;<code>prompt_id</code>&emsp;<strong>Optional:</strong>&ensp;<code>name</code>, <code>dataset_id</code>, <code>metric_ids</code>, <code>judge_model</code></p>
-        <%= render "example", base_url: @base_url, token: token_display, real_token: @token, cmd: "curl -X POST #{@base_url}/api/v1/runs \\\n  -H \"Authorization: Bearer #{token_display}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"prompt_id\": 1, \"dataset_id\": 1, \"metric_ids\": [1, 2]}'" %>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/runs/:id</p>
-        <p class="ck-meta-copy">Get a run with status, progress, response count, and average score.</p>
-        <%= render "example", base_url: @base_url, token: token_display, real_token: @token, cmd: "curl #{@base_url}/api/v1/runs/1 \\\n  -H \"Authorization: Bearer #{token_display}\"" %>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/runs/:id/generate</p>
-        <p class="ck-meta-copy">Start generating responses. Returns 202 Accepted. Poll the run to check progress.</p>
-        <%= render "example", base_url: @base_url, token: token_display, real_token: @token, cmd: "curl -X POST #{@base_url}/api/v1/runs/1/generate \\\n  -H \"Authorization: Bearer #{token_display}\"" %>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">PATCH</span> /api/v1/runs/:id</p>
-        <p class="ck-meta-copy">Update a run. Accepts same params as create.</p>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip" style="color: var(--ck-danger);">DELETE</span> /api/v1/runs/:id</p>
-        <p class="ck-meta-copy">Delete a run and all its responses. Returns 204 No Content.</p>
-      </div>
-    </div>
-
-    <div class="ck-api-tabs__panel">
-      <h2 class="ck-section-title">Responses</h2>
-      <p class="ck-copy">Read-only access to generated responses and their review scores. Nested under runs.</p>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/runs/:run_id/responses</p>
-        <p class="ck-meta-copy">List all responses for a run, including nested review scores.</p>
-        <%= render "example", base_url: @base_url, token: token_display, real_token: @token, cmd: "curl #{@base_url}/api/v1/runs/1/responses \\\n  -H \"Authorization: Bearer #{token_display}\"" %>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/runs/:run_id/responses/:id</p>
-        <p class="ck-meta-copy">Get a single response with its review scores and feedback.</p>
-      </div>
-    </div>
-
-    <div class="ck-api-tabs__panel">
-      <h2 class="ck-section-title">Datasets</h2>
-      <p class="ck-copy">Data used as input for runs.</p>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/datasets</p>
-        <p class="ck-meta-copy">List all datasets.</p>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/datasets</p>
-        <p class="ck-meta-copy">Create a dataset.</p>
-        <p class="ck-api-params"><strong>Required:</strong>&ensp;<code>name</code>, <code>csv_data</code></p>
-        <%= render "example", base_url: @base_url, token: token_display, real_token: @token, cmd: "curl -X POST #{@base_url}/api/v1/datasets \\\n  -H \"Authorization: Bearer #{token_display}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"tickets\", \"csv_data\": \"text,expected_output\\\\nHello,Hi\"}'" %>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span>&ensp;<span class="ck-chip ck-chip--soft">PATCH</span>&ensp;<span class="ck-chip" style="color: var(--ck-danger);">DELETE</span> /api/v1/datasets/:id</p>
-        <p class="ck-meta-copy">Get, update, or delete a dataset.</p>
-      </div>
-    </div>
-
-    <div class="ck-api-tabs__panel">
-      <h2 class="ck-section-title">Metrics</h2>
-      <p class="ck-copy">Scoring dimensions used by the judge model.</p>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/metrics</p>
-        <p class="ck-meta-copy">List all metrics.</p>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/metrics</p>
-        <p class="ck-meta-copy">Create a metric.</p>
-        <p class="ck-api-params"><strong>Required:</strong>&ensp;<code>name</code>&emsp;<strong>Optional:</strong>&ensp;<code>instruction</code>, <code>rubric_bands</code> (array of {stars, description})</p>
-        <%= render "example", base_url: @base_url, token: token_display, real_token: @token, cmd: "curl -X POST #{@base_url}/api/v1/metrics \\\n  -H \"Authorization: Bearer #{token_display}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"relevance\", \"instruction\": \"Is the response relevant?\"}'" %>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span>&ensp;<span class="ck-chip ck-chip--soft">PATCH</span>&ensp;<span class="ck-chip" style="color: var(--ck-danger);">DELETE</span> /api/v1/metrics/:id</p>
-        <p class="ck-meta-copy">Get, update, or delete a metric.</p>
-      </div>
-    </div>
-
-    <div class="ck-api-tabs__panel">
-      <h2 class="ck-section-title">Metric Groups</h2>
-      <p class="ck-copy">Named groups of metrics you can apply to a run as a set.</p>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/metric_groups</p>
-        <p class="ck-meta-copy">List all metric groups with their metric IDs.</p>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/metric_groups</p>
-        <p class="ck-meta-copy">Create a metric group.</p>
-        <p class="ck-api-params"><strong>Required:</strong>&ensp;<code>name</code>&emsp;<strong>Optional:</strong>&ensp;<code>description</code>, <code>metric_ids</code> (array)</p>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span>&ensp;<span class="ck-chip ck-chip--soft">PATCH</span>&ensp;<span class="ck-chip" style="color: var(--ck-danger);">DELETE</span> /api/v1/metric_groups/:id</p>
-        <p class="ck-meta-copy">Get, update, or delete a metric group. PATCH with <code>metric_ids</code> replaces all metric associations.</p>
-      </div>
-    </div>
-
-    <div class="ck-api-tabs__panel">
-      <h2 class="ck-section-title">Tags</h2>
-      <p class="ck-copy">Domain labels you can attach to metrics, prompts, runs, and datasets. Tags are auto-assigned a color from a 10-color palette. Each index page can be filtered by one or more tags using <code>?tag[]=name</code> query params (OR semantics).</p>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/tags</p>
-        <p class="ck-meta-copy">List all tags with name and color.</p>
-        <%= render "example", base_url: @base_url, token: token_display, real_token: @token, cmd: "curl #{@base_url}/api/v1/tags \\\n  -H \"Authorization: Bearer #{token_display}\"" %>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/tags</p>
-        <p class="ck-meta-copy">Create a tag.</p>
-        <p class="ck-api-params"><strong>Required:</strong>&ensp;<code>name</code></p>
-        <%= render "example", base_url: @base_url, token: token_display, real_token: @token, cmd: "curl -X POST #{@base_url}/api/v1/tags \\\n  -H \"Authorization: Bearer #{token_display}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"real estate\"}'" %>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span>&ensp;<span class="ck-chip ck-chip--soft">PATCH</span>&ensp;<span class="ck-chip" style="color: var(--ck-danger);">DELETE</span> /api/v1/tags/:id</p>
-        <p class="ck-meta-copy">Get, update, or delete a tag. PATCH accepts <code>name</code>. DELETE returns 204 No Content and removes all taggings for this tag.</p>
-      </div>
-      <div class="ck-api-endpoint" style="padding-top: 1rem;">
-        <p class="ck-kicker" style="margin-bottom: 0.5rem;">Tagging resources</p>
-        <p class="ck-meta-copy">Metrics, prompts, runs, and datasets accept a <code>tag_names</code> array on their create and update endpoints. Passing a name that does not yet exist silently creates the tag. On PATCH, the list replaces all existing tags for that record (omit the field to leave tags unchanged).</p>
-        <%= render "example", base_url: @base_url, token: token_display, real_token: @token, cmd: "curl -X POST #{@base_url}/api/v1/metrics \\\n  -H \"Authorization: Bearer #{token_display}\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"name\": \"Accuracy\", \"tag_names\": [\"real estate\"]}'" %>
-      </div>
-      <div class="ck-api-endpoint" style="padding-top: 1rem;">
-        <p class="ck-kicker" style="margin-bottom: 0.5rem;">MCP tools</p>
-        <div class="ck-mcp-tools">
-          <div class="ck-mcp-tool"><code class="ck-mcp-tool__name">tags_list</code><span class="ck-mcp-tool__desc">List all tags</span></div>
-          <div class="ck-mcp-tool"><code class="ck-mcp-tool__name">tags_get</code><span class="ck-mcp-tool__desc">Get a tag by ID</span></div>
-          <div class="ck-mcp-tool"><code class="ck-mcp-tool__name">tags_create</code><span class="ck-mcp-tool__desc">Create a tag (name required)</span></div>
-          <div class="ck-mcp-tool"><code class="ck-mcp-tool__name">tags_update</code><span class="ck-mcp-tool__desc">Update a tag's name</span></div>
-          <div class="ck-mcp-tool"><code class="ck-mcp-tool__name">tags_delete</code><span class="ck-mcp-tool__desc">Delete a tag and remove all its taggings</span></div>
-        </div>
-        <p class="ck-meta-copy" style="margin-top: 0.75rem;">The existing <code>metrics_create</code>, <code>metrics_update</code>, <code>prompts_create</code>, <code>prompts_update</code>, <code>runs_create</code>, <code>runs_update</code>, <code>datasets_create</code>, and <code>datasets_update</code> tools all accept a <code>tag_names</code> parameter with the same auto-create and replace semantics as the REST API.</p>
-      </div>
-    </div>
-
-    <div class="ck-api-tabs__panel">
-      <h2 class="ck-section-title">Provider Credentials</h2>
-      <p class="ck-copy">LLM provider API keys. The <code>api_key</code> field is write-only and never returned in responses.</p>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span> /api/v1/provider_credentials</p>
-        <p class="ck-meta-copy">List all provider credentials (api_key excluded).</p>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">POST</span> /api/v1/provider_credentials</p>
-        <p class="ck-meta-copy">Create a provider credential.</p>
-        <p class="ck-api-params"><strong>Required:</strong>&ensp;<code>provider</code> (openai, anthropic, ollama, openrouter), <code>api_key</code>&emsp;<strong>Optional:</strong>&ensp;<code>api_endpoint</code></p>
-      </div>
-      <div class="ck-api-endpoint">
-        <p class="ck-api-method"><span class="ck-chip ck-chip--soft">GET</span>&ensp;<span class="ck-chip ck-chip--soft">PATCH</span>&ensp;<span class="ck-chip" style="color: var(--ck-danger);">DELETE</span> /api/v1/provider_credentials/:id</p>
-        <p class="ck-meta-copy">Get, update, or delete a provider credential.</p>
+        <%= render CompletionKit.config.api_reference_authentication_partial, token: @token %>
       </div>
     </div>
-
   </div>
 </div>
 
-<script>
-function ckToggleToken(el) {
-  var showing = el.textContent === el.dataset.masked;
-  el.textContent = showing ? el.dataset.real : el.dataset.masked;
-  el.setAttribute('aria-pressed', showing ? 'true' : 'false');
-  el.setAttribute('aria-label', showing ? 'Hide API token' : 'Reveal API token');
-  navigator.clipboard.writeText(el.dataset.real).then(function() {
-    el.classList.add('ck-api-copy--done');
-    setTimeout(function() { el.classList.remove('ck-api-copy--done'); }, 1500);
-  });
-}
-
-function ckCopyExample(btn) {
-  var pre = btn.closest('.ck-api-example').querySelector('pre');
-  var text = pre.textContent;
-  var realToken = btn.dataset.realToken;
-  var displayToken = btn.dataset.displayToken;
-  if (realToken && displayToken) {
-    text = text.split(displayToken).join(realToken);
-  }
-  navigator.clipboard.writeText(text).then(function() {
-    btn.classList.add('ck-api-copy--done');
-    setTimeout(function() { btn.classList.remove('ck-api-copy--done'); }, 1500);
-  });
-}
-</script>
+<%= render "completion_kit/api_reference/body",
+      base_url: @base_url,
+      token: ck_masked_token(@token),
+      real_token: @token,
+      published_prompts: @published_prompts %>

data/app/views/completion_kit/prompts/index.html.erb

@@ -66,7 +66,7 @@
               <span class="ck-prompts-table__runs-count"><%= family_runs.count %></span>
               <% last_run = family_runs.order(created_at: :desc).first %>
               <% if last_run %>
-                <span class="ck-prompts-table__runs-when">last <time data-relative-time datetime="<%= last_run.created_at.utc.iso8601 %>"><%= time_ago_in_words(last_run.created_at) %></time> ago</span>
+                <span class="ck-prompts-table__runs-when">last <time data-relative-time datetime="<%= last_run.created_at.utc.iso8601 %>"><%= time_ago_in_words(last_run.created_at) %> ago</time></span>
               <% else %>
                 <span class="ck-prompts-table__runs-when">never run</span>
               <% end %>

data/app/views/completion_kit/prompts/show.html.erb

@@ -181,7 +181,7 @@
             <td><strong><%= s.run.name %></strong></td>
             <td class="ck-meta-copy"><%= truncate(s.reasoning.to_s, length: 100) %></td>
             <td><%= s.applied_at? ? content_tag(:span, "Applied", class: "ck-chip", style: "background: var(--ck-success-soft); color: var(--ck-success);") : "&mdash;".html_safe %></td>
-            <td class="ck-meta-copy"><time data-relative-time datetime="<%= s.created_at.utc.iso8601 %>"><%= time_ago_in_words(s.created_at) %></time> ago</td>
+            <td class="ck-meta-copy"><time data-relative-time datetime="<%= s.created_at.utc.iso8601 %>"><%= time_ago_in_words(s.created_at) %> ago</time></td>
             <td class="ck-results-table__arrow">&rarr;</td>
           </tr>
         <% end %>

data/app/views/completion_kit/provider_credentials/_discovery_status.html.erb

@@ -26,7 +26,7 @@
     </div>
   <% elsif provider_credential.discovery_status == "completed" && local_assigns.fetch(:show_completed, true) %>
     <div class="ck-discovery-bar ck-discovery-bar--completed">
-      <div class="ck-discovery-bar__label">Available models list updated <time data-relative-time datetime="<%= provider_credential.updated_at.utc.iso8601 %>"><%= time_ago_in_words(provider_credential.updated_at) %></time> ago</div>
+      <div class="ck-discovery-bar__label">Available models list updated <time data-relative-time datetime="<%= provider_credential.updated_at.utc.iso8601 %>"><%= time_ago_in_words(provider_credential.updated_at) %> ago</time></div>
     </div>
   <% end %>
 </div>

data/app/views/completion_kit/provider_credentials/_models_card.html.erb

@@ -15,7 +15,7 @@
             <span class="ck-model-list__summary-label">Available models <span class="ck-model-list__summary-count"><%= models.count %></span></span>
             <span class="ck-model-list__summary-meta">
               <% if provider_credential.discovery_status == "completed" %>
-                <span class="ck-model-list__summary-stamp">updated <time data-relative-time datetime="<%= provider_credential.updated_at.utc.iso8601 %>"><%= time_ago_in_words(provider_credential.updated_at) %></time> ago</span>
+                <span class="ck-model-list__summary-stamp">updated <time data-relative-time datetime="<%= provider_credential.updated_at.utc.iso8601 %>"><%= time_ago_in_words(provider_credential.updated_at) %> ago</time></span>
               <% end %>
               <button type="button" class="ck-icon-btn ck-model-list__refresh<%= ' ck-icon-btn--spinning' if discovering %>" title="Refresh models" aria-label="Refresh available models" <%= 'disabled' if discovering %> onclick="event.preventDefault();event.stopPropagation();fetch('<%= refresh_provider_credential_path(provider_credential) %>', {method:'POST',headers:{'X-CSRF-Token':document.querySelector('meta[name=csrf-token]').content}})">
                 <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 16 16" fill="currentColor" width="13" height="13" aria-hidden="true"><path fill-rule="evenodd" d="M13.836 2.477a.75.75 0 0 1 .75.75v3.182a.75.75 0 0 1-.75.75h-3.182a.75.75 0 0 1 0-1.5h1.37l-.84-.841a4.5 4.5 0 0 0-7.08.681.75.75 0 0 1-1.264-.808 6 6 0 0 1 9.44-.908l.84.84V3.227a.75.75 0 0 1 .75-.75Zm-.911 7.5A.75.75 0 0 1 13.199 11a6 6 0 0 1-9.44.908l-.84-.84v1.68a.75.75 0 0 1-1.5 0V9.567a.75.75 0 0 1 .75-.75h3.182a.75.75 0 0 1 0 1.5h-1.37l.84.841a4.5 4.5 0 0 0 7.08-.681.75.75 0 0 1 1.024-.274Z" clip-rule="evenodd"/></svg>

data/app/views/completion_kit/provider_credentials/index.html.erb

@@ -30,7 +30,7 @@
           <span><%= provider_credential.model_count %> models</span>
           <span><%= provider_credential.prompt_count %> prompts</span>
           <span><%= provider_credential.judge_count %> judges</span>
-          <span><% if provider_credential.last_used_at %>Used <time data-relative-time datetime="<%= provider_credential.last_used_at.utc.iso8601 %>"><%= time_ago_in_words(provider_credential.last_used_at) %></time> ago<% else %>Never used<% end %></span>
+          <span><% if provider_credential.last_used_at %>Used <time data-relative-time datetime="<%= provider_credential.last_used_at.utc.iso8601 %>"><%= time_ago_in_words(provider_credential.last_used_at) %> ago</time><% else %>Never used<% end %></span>
         </div>
 
         <%= render "discovery_status", provider_credential: provider_credential %>

data/app/views/completion_kit/runs/_row.html.erb

@@ -49,7 +49,7 @@
     <% end %>
   </td>
   <td class="ck-runs-table__when">
-    <time data-relative-time datetime="<%= run.created_at.utc.iso8601 %>"><%= time_ago_in_words(run.created_at) %></time> ago
+    <time data-relative-time datetime="<%= run.created_at.utc.iso8601 %>"><%= time_ago_in_words(run.created_at) %> ago</time>
   </td>
   <td class="ck-results-table__arrow">&rarr;</td>
 </tr>

data/app/views/completion_kit/tags/_picker.html.erb

@@ -2,7 +2,7 @@
   <% label_text = local_assigns[:label].presence || "#{param_namespace.to_s.titleize} tags" %>
   <%= label_tag "#{param_namespace}_tags", label_text, class: "ck-label" %>
   <% all_tags = CompletionKit::Tag.order(:name) %>
-  <% selected_ids = record.persisted? ? record.tags.pluck(:id) : [] %>
+  <% selected_ids = (record.persisted? || record.tags.loaded?) ? record.tags.map(&:id) : [] %>
   <div class="ck-tag-picker">
     <% all_tags.each do |tag| %>
       <% checked = selected_ids.include?(tag.id) %>

data/lib/completion_kit/version.rb

@@ -1,3 +1,3 @@
 module CompletionKit
-  VERSION = "0.5.6"
+  VERSION = "0.5.8"
 end

data/lib/completion_kit.rb

@@ -9,6 +9,7 @@ module CompletionKit
     attr_accessor :judge_model, :high_quality_threshold, :medium_quality_threshold
     attr_accessor :username, :password, :auth_strategy, :api_token
     attr_accessor :tenant_scope, :tenant_scope_columns
+    attr_accessor :api_reference_authentication_partial
 
     def initialize
       @openai_api_key = ENV['OPENAI_API_KEY']
@@ -19,6 +20,8 @@ module CompletionKit
       @judge_model = "gpt-4.1"
       @high_quality_threshold = 4
       @medium_quality_threshold = 3
+
+      @api_reference_authentication_partial = "completion_kit/api_reference/authentication"
     end
 
     def tenant_scope_columns

data/lib/generators/completion_kit/templates/initializer.rb

@@ -37,6 +37,10 @@ CompletionKit.configure do |config|
   # API Authentication
   # config.api_token = ENV['COMPLETION_KIT_API_TOKEN']
 
+  # API reference page: swap in your own Authentication card (e.g. a multi-tenant
+  # token-management panel). The partial receives a `token:` local.
+  # config.api_reference_authentication_partial = "my_app/api_token_panel"
+
   # Web UI Authentication
   # config.username = "admin"
   # config.password = ENV['COMPLETION_KIT_PASSWORD']

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: completion-kit
 version: !ruby/object:Gem::Version
-  version: 0.5.6
+  version: 0.5.8
 platform: ruby
 authors:
 - Damien Bastin
@@ -300,6 +300,8 @@ files:
 - app/services/completion_kit/prompt_improvement_service.rb
 - app/services/completion_kit/worker_health.rb
 - app/validators/completion_kit/tenant_scoped_uniqueness_validator.rb
+- app/views/completion_kit/api_reference/_authentication.html.erb
+- app/views/completion_kit/api_reference/_body.html.erb
 - app/views/completion_kit/api_reference/_example.html.erb
 - app/views/completion_kit/api_reference/index.html.erb
 - app/views/completion_kit/datasets/_form.html.erb