studio-engine 0.68.0 → 0.69.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cc639657a629af209c7afe28ae5114aff1d6121a0c6e5fc456c0d7fec51a40b3
-  data.tar.gz: 4875b0355b16ea935f873f4dca59d1657a2e8b7e2b7b7ae17f79df80ea194e48
+  metadata.gz: ec5eb4134f973228cde9577b93d24e6f7e7380f613669f7ef95396ae8f20b048
+  data.tar.gz: d51dbff7d2d0b87bbc7f99da58ed31759c23dfbf3296fb12962ac939dbcd17ab
 SHA512:
-  metadata.gz: 867c4b70c5c76e7619c6b4ed1d087a79ccb1cd3c9d99770f109c4c039d56372ca7835a3281d00bcc1fc076cb1759c700156959db4f29010e4fa5239b3a344944
-  data.tar.gz: 31eec34f181c1caec640f1085d97b3437bd6e0416e90ff4f4d23af29039b88406093ed42adbd11c973ef4a7687eeea76e208f5b57df88d25e66f37a937933bae
+  metadata.gz: '05658af267cec61bc5c54e4e68283bbfbe4a92fa401fc2e6c79d117bb65dd1f66b88ed9d1c4e1962b9131f138ef9fcffdc2948ff8fee796bb216033c953cd5c8'
+  data.tar.gz: 59538dc6601a43794bc1b700d3dfdace130bd9ac72a3a9cd507d1626a16e2679c0c7c81ab6fc36800403be4c7cf1dfd26258725971c30546899a7a2fb729e03b

data/CHANGELOG.md

@@ -4,8 +4,29 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ## Unreleased
 
+### Added
+
+- **Knowledge coverage view** — `/admin/knowledge/coverage` +
+  `Studio::KnowledgeExpectation`: the "what SHOULD exist" half of the
+  knowledge layer. Expectations carry an entity, folder, provenance
+  (`source_note`, e.g. "diligence tracker item 14"), and a cadence — `once`
+  (an LOI) or `monthly` (aging inventory), where each calendar month from
+  `start_on` is a slot and the view names missing months outright
+  (`2026-09 MISSING`). Documents fulfill expectations by an EXPLICIT
+  `expectation_id` set at triage (the show page grows a "fulfills expectation"
+  select; a fuzzy name-match would silently merge lookalikes, an id never
+  does), and superseded documents never fill a slot. Ships two reference
+  migrations (`create_studio_knowledge_expectations`,
+  `add_expectation_to_studio_knowledge_docs`); routes ride the existing
+  `Studio.draw_knowledge_routes` opt-in. Built for the Commercial Welding
+  65-item diligence tracker; app-agnostic like the rest of the layer.
+
 ### Changed
 
+- **`Gemfile.lock` resolves solana-studio 0.5.7, and a gate now keeps it there.** The lock had sat on **0.5.3 for four patch releases** while BOTH consumers shipped 0.5.7 (turf-monster `~> 0.5.3`, mcritchie-studio `~> 0.5`). Nothing was red and nothing could have been: engine CI installs with `bundler-cache: true`, so it resolves from the lock and never fresh — the drift does not self-correct and never surfaces as flakiness. It matters because `test/views/style_web3_specimens_test.rb` exists to prove "the style guide renders the REAL gem cards" and reads them off whatever the LOCK resolved; four versions behind, that guard certifies a card no consumer receives. It still passes — only its MEANING changes. MEASURED on this span, the gem's whole `app/` tree was byte-identical 0.5.3 → 0.5.7 (only `CHANGELOG.md`, `README.md` and `version.rb` differ), so this instance cost nothing, which is exactly why it went four releases unnoticed.
+- **The constraint stays `>= 0.5.3`, deliberately.** 0.5.3 is a real FLOOR (0.5.2 shipped the credential partial without `solana_studio/modals/_wallet_connect`, which the web3 capability gate requires). Above it this engine claims no ceiling: it is the BASE half of the base/bolt-on split, and a pessimistic `~> 0.5.3` here would be NARROWER than mcritchie-studio's own `~> 0.5` — a dev-only dependency constraining a resolution it does not own. The defect was the LOCK, not the pin, so the fix is a gate rather than a tighter pin.
+- **`bin/gem-drift-check`** — fails when this engine's lock resolves a tracked gem OLDER than a consumer's, wired into `consumer-ci.yml` after the consumer bundle install. That lane is the only place two repos' lockfiles exist at once (engine at `studio/`, consumer beside it); `test/lib/consumer_ci_shard_contract_test.rb` records the same constraint for its own cross-repo contract. Direction is ONE-WAY on purpose: engine behind FAILS, engine level or ahead passes (the engine is the producer and may test an unreleased gem), and a consumer bundling no tracked gem is a SKIP, not a failure — `mcritchie_industries` is the base half working as designed. Stdlib-only, and it names its one-command remedy (`bundle update solana-studio`) in the failure.
+
 - **The auth modal's Solana button moved to solana-studio, behind a CREDENTIAL
   SLOT.** `style/modals/_auth` no longer draws the button; it renders whatever
   resolves at `solana_studio/auth/wallet_credential` and nothing when that path

data/Gemfile

@@ -52,6 +52,34 @@ end
 # The style guide self-gates on the partial RESOLVING (style/_modals.html.erb),
 # so an app without this gem renders /admin/style with the web3 cards badged
 # rather than raising a missing-template error.
+#
+# THE CONSTRAINT STAYS OPEN-ENDED, AND THAT IS A DECISION, NOT AN OVERSIGHT.
+# ">= 0.5.3" is a FLOOR: 0.5.2 shipped the credential partial without
+# solana_studio/modals/_wallet_connect, which the web3 capability gate requires,
+# so 0.5.3 is the first version that can draw the button at all. Above it this
+# engine deliberately claims no ceiling. It is the BASE half of the split; the
+# bolt-on is the consumer's choice, and an engine that pinned the bolt-on more
+# tightly than the app bolting it on would be dictating upward. Concretely: a
+# pessimistic "~> 0.5.3" here would be NARROWER than mcritchie-studio's own
+# "~> 0.5", so this dev-only dependency would start constraining a resolution it
+# does not own.
+#
+# WHAT ACTUALLY WENT WRONG, and it was the LOCK, not the constraint. The lock sat
+# on 0.5.3 while both consumers shipped 0.5.7 — four patch releases — and nothing
+# was red, because engine CI installs with `bundler-cache: true` and never
+# resolves fresh. Meanwhile test/views/style_web3_specimens_test.rb exists to
+# prove "the style guide renders the REAL gem cards" and reads them off whatever
+# the LOCK resolved. Behind, that guard certifies a card no consumer receives; it
+# still passes, and only its MEANING has changed. (Measured on this span: the
+# gem's whole app/ tree was byte-identical 0.5.3 -> 0.5.7, so this instance cost
+# nothing — which is precisely why it went four releases unnoticed.)
+#
+# SO THE FIX IS A GATE, NOT A PIN. bin/gem-drift-check fails when this engine's
+# lock TRAILS a consumer's, and consumer-ci.yml runs it — the only lane holding
+# two repos' lockfiles at once. Direction is one-way: engine behind fails, engine
+# ahead or level passes, a consumer bundling no solana-studio is a skip. Keeping
+# up is now enforced rather than remembered, which is what lets the floor stay a
+# floor. Guarded by test/lib/gem_drift_check_test.rb.
 group :development, :test do
   gem "solana-studio", ">= 0.5.3"
 end

data/app/controllers/studio/knowledge_docs_controller.rb

@@ -43,6 +43,47 @@ module Studio
     end
 
     def show
+      # Guarded like intake!'s MissingTable posture: a consumer that bumped the
+      # gem without installing the expectations migrations keeps its working
+      # doc pages — the link select simply doesn't render.
+      @linkable_expectations =
+        if Studio::KnowledgeExpectation.table_exists?
+          Studio::KnowledgeExpectation.active.for_entity(@doc.entity).order(:path, :title).to_a
+        else
+          []
+        end
+    end
+
+    # GET /admin/knowledge/coverage — expected vs uploaded, the gap named.
+    def coverage
+      unless Studio::KnowledgeExpectation.table_exists?
+        return redirect_to admin_knowledge_path,
+                           alert: "The coverage view needs the studio_knowledge_expectations table — " \
+                                  "run `bin/rails studio_engine:install:migrations && bin/rails db:migrate`."
+      end
+
+      @entity = params[:entity].presence
+      scope = Studio::KnowledgeExpectation.active.order(:path, :title)
+      scope = scope.for_entity(@entity) if @entity
+      @expectations = scope.to_a
+      @entities = Studio::KnowledgeExpectation.distinct.pluck(:entity).sort
+    end
+
+    def create_expectation
+      expectation = Studio::KnowledgeExpectation.create!(expectation_params)
+      redirect_to admin_knowledge_coverage_path(entity: expectation.entity),
+                  notice: "Expecting: #{expectation.title}."
+    rescue ActiveRecord::RecordInvalid => e
+      redirect_to admin_knowledge_coverage_path, alert: e.message
+    end
+
+    def update_expectation
+      expectation = Studio::KnowledgeExpectation.find(params[:id])
+      expectation.update!(expectation_params)
+      redirect_to admin_knowledge_coverage_path(entity: expectation.entity),
+                  notice: "#{expectation.title} updated."
+    rescue ActiveRecord::RecordInvalid => e
+      redirect_to admin_knowledge_coverage_path, alert: e.message
     end
 
     def create
@@ -73,6 +114,12 @@ module Studio
 
     private
 
+    def expectation_params
+      params.require(:knowledge_expectation)
+            .permit(:entity, :title, :path, :category, :cadence, :start_on,
+                    :source_note, :active)
+    end
+
     def set_doc
       @doc = Studio::KnowledgeDoc.find(params[:id])
     end
@@ -80,7 +127,8 @@ module Studio
     def doc_params
       permitted = params.require(:knowledge_doc)
                         .permit(:title, :entity, :path, :category, :summary,
-                                :document_date, :source_note, :status, access: {})
+                                :document_date, :source_note, :status,
+                                :expectation_id, access: {})
       # The access map arrives as {"samson" => "full", ...}; drop blanks so an
       # untouched select doesn't write a "none" the map means by absence anyway.
       if permitted[:access]

data/app/models/studio/knowledge_doc.rb

@@ -35,6 +35,12 @@ module Studio
     ACCESS_LEVELS = %w[full aware none].freeze
     STATUSES      = %w[inbox filed superseded].freeze
 
+    # The expectation this document fulfills (coverage view) — optional, set at
+    # triage. Guarded: consumers that installed the docs table before the
+    # expectations migration existed simply have no column yet.
+    belongs_to :expectation, class_name: "Studio::KnowledgeExpectation",
+                             optional: true, inverse_of: :docs
+
     validates :title,  presence: true
     validates :entity, presence: true
     validates :status, inclusion: { in: STATUSES }

data/app/models/studio/knowledge_expectation.rb

@@ -0,0 +1,91 @@
+module Studio
+  # One row per document the knowledge layer EXPECTS — the other half of the
+  # coverage question. Documents record what exists; expectations record what
+  # should, so the gap between them is computable instead of remembered.
+  #
+  # Two cadences:
+  #
+  #   once    — a single fulfilling document satisfies it forever (an LOI, a
+  #             lease, tracker item 14).
+  #   monthly — one document per calendar month from start_on onward (aging
+  #             inventory, bank statements). Each month is a SLOT; a slot is
+  #             filled when a linked doc's as-of date falls inside it, and the
+  #             coverage view names the missing months outright.
+  #
+  # Fulfillment is an EXPLICIT link — Studio::KnowledgeDoc#expectation_id, set
+  # at triage — never a name match: a fuzzy matcher silently merges lookalike
+  # documents, an id never does.
+  #
+  # Installed per consumer like the other studio_* tables.
+  class KnowledgeExpectation < ApplicationRecord
+    self.table_name = "studio_knowledge_expectations"
+
+    CADENCES = %w[once monthly].freeze
+
+    has_many :docs, class_name: "Studio::KnowledgeDoc",
+                    foreign_key: :expectation_id, inverse_of: :expectation,
+                    dependent: :nullify
+
+    validates :entity, presence: true
+    validates :title, presence: true
+    validates :cadence, inclusion: { in: CADENCES }
+
+    before_validation :normalize_fields
+
+    scope :for_entity, ->(entity) { where(entity: entity) }
+    scope :active,     -> { where(active: true) }
+
+    def monthly?
+      cadence == "monthly"
+    end
+
+    # The linked documents that can fill slots — superseded rows never count.
+    def fulfilling_docs
+      docs.active.to_a
+    end
+
+    # Monthly slot months, oldest first: start_on's month (or this row's
+    # creation month) through as_of's month. Nil for once-cadence.
+    def slot_months(as_of: Date.current)
+      return nil unless monthly?
+
+      first = (start_on || created_at&.to_date || as_of).beginning_of_month
+      last  = as_of.beginning_of_month
+      return [] if first > last
+
+      months = []
+      cursor = first
+      while cursor <= last
+        months << cursor
+        cursor = cursor.next_month
+      end
+      months
+    end
+
+    # Coverage for the view, one shape per cadence:
+    #   once:    { filled: bool, docs: [...] }
+    #   monthly: { slots: [{ month:, docs: [...] }], missing_months: [...] }
+    def coverage(as_of: Date.current)
+      linked = fulfilling_docs
+      return { filled: linked.any?, docs: linked } unless monthly?
+
+      slots = slot_months(as_of: as_of).map do |month|
+        { month: month,
+          docs: linked.select { |doc| doc.display_date&.beginning_of_month == month } }
+      end
+      { slots: slots, missing_months: slots.select { |slot| slot[:docs].empty? }.map { |slot| slot[:month] } }
+    end
+
+    def filled?(as_of: Date.current)
+      result = coverage(as_of: as_of)
+      monthly? ? result[:missing_months].empty? : result[:filled]
+    end
+
+    private
+
+    def normalize_fields
+      self.entity = entity.to_s.strip.downcase if entity
+      self.path   = Studio::KnowledgeDoc.normalize_path(path)
+    end
+  end
+end

data/app/views/studio/knowledge_docs/_browser.html.erb

@@ -43,6 +43,8 @@
     <span aria-hidden="true">·</span>
     <%= link_to "Show all", admin_knowledge_path(view: "flat", entity: entity, status: status),
                 class: view == "flat" ? "font-semibold underline" : "" %>
+    <span aria-hidden="true">·</span>
+    <%= link_to "Coverage", admin_knowledge_coverage_path(entity: entity), id: "knowledge-coverage-link" %>
   </div>
 </div>
 

data/app/views/studio/knowledge_docs/_coverage_table.html.erb

@@ -0,0 +1,109 @@
+<%# The coverage table — expected vs uploaded, gaps named. Locals:
+      expectations: active Studio::KnowledgeExpectation rows to render
+      entity:       entity filter or nil
+      entities:     all entity slugs (filter row) %>
+<style>
+  .coverage-mark { font-size: .8rem; padding: 0 .45rem; border-radius: .25rem; white-space: nowrap; }
+  .coverage-filled  { color: rgb(5 150 105); }
+  .coverage-missing { color: rgb(220 38 38); border: 1px solid rgb(220 38 38 / .5); font-weight: 600; }
+  .coverage-slot { display: inline-block; margin-right: .4rem; }
+</style>
+
+<div class="flex flex-wrap items-center justify-between gap-3 mb-4">
+  <h1 class="text-xl font-semibold">Coverage</h1>
+  <div class="text-sm"><%= link_to "← Knowledge", admin_knowledge_path(entity: entity) %></div>
+</div>
+
+<% if entities.length > 1 || entity %>
+  <div class="flex flex-wrap items-center gap-2 mb-3 text-sm">
+    <%= link_to "All entities", admin_knowledge_coverage_path, class: entity ? "" : "font-semibold underline" %>
+    <% entities.each do |candidate| %>
+      <%= link_to candidate, admin_knowledge_coverage_path(entity: candidate),
+                  class: candidate == entity ? "font-semibold underline" : "" %>
+    <% end %>
+  </div>
+<% end %>
+
+<% if expectations.any? %>
+  <div class="overflow-x-auto mb-6">
+    <table id="knowledge-coverage" class="w-full text-sm">
+      <thead>
+        <tr class="text-left border-b">
+          <th class="py-2 pr-3">Expected</th>
+          <th class="py-2 pr-3">Folder</th>
+          <th class="py-2 pr-3">Cadence</th>
+          <th class="py-2 pr-3">Coverage</th>
+        </tr>
+      </thead>
+      <tbody>
+        <% expectations.each do |expectation| %>
+          <% result = expectation.coverage %>
+          <tr id="coverage-exp-<%= expectation.id %>" class="border-b align-top">
+            <td class="py-2 pr-3">
+              <span class="font-medium"><%= expectation.title %></span>
+              <% if expectation.source_note.present? %>
+                <div class="text-xs opacity-60"><%= expectation.source_note %></div>
+              <% end %>
+            </td>
+            <td class="py-2 pr-3 text-xs opacity-80"><%= expectation.path.presence || "root" %></td>
+            <td class="py-2 pr-3"><%= expectation.cadence %></td>
+            <td class="py-2 pr-3">
+              <% if expectation.monthly? %>
+                <% result[:slots].each do |slot| %>
+                  <span class="coverage-slot coverage-mark <%= slot[:docs].any? ? "coverage-filled" : "coverage-missing" %>"
+                        id="coverage-slot-<%= expectation.id %>-<%= slot[:month].strftime("%Y-%m") %>">
+                    <%= slot[:month].strftime("%Y-%m") %> <%= slot[:docs].any? ? "✓" : "MISSING" %>
+                  </span>
+                <% end %>
+              <% elsif result[:filled] %>
+                <span class="coverage-mark coverage-filled">✓ filled —
+                  <% result[:docs].first(2).each do |doc| %>
+                    <%= link_to doc.title, admin_knowledge_doc_path(doc) %>
+                  <% end %>
+                </span>
+              <% else %>
+                <span class="coverage-mark coverage-missing">MISSING</span>
+              <% end %>
+            </td>
+          </tr>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+<% else %>
+  <p id="coverage-empty" class="text-sm opacity-70 mb-4">Nothing is expected yet — add the first expectation below.</p>
+<% end %>
+
+<div id="coverage-new" class="p-4 border rounded">
+  <h2 class="font-semibold mb-3">Expect a document</h2>
+  <%= form_with url: admin_knowledge_expectations_path, method: :post, local: true do |form| %>
+    <div class="grid gap-3 md:grid-cols-3">
+      <label class="block text-sm">
+        <span class="block mb-1">Title</span>
+        <%= form.text_field "knowledge_expectation[title]", required: true, class: "block w-full border rounded px-2 py-1" %>
+      </label>
+      <label class="block text-sm">
+        <span class="block mb-1">Entity</span>
+        <%= form.text_field "knowledge_expectation[entity]", value: entity, required: true, class: "block w-full border rounded px-2 py-1" %>
+      </label>
+      <label class="block text-sm">
+        <span class="block mb-1">Folder</span>
+        <%= form.text_field "knowledge_expectation[path]", class: "block w-full border rounded px-2 py-1" %>
+      </label>
+      <label class="block text-sm">
+        <span class="block mb-1">Cadence</span>
+        <%= form.select "knowledge_expectation[cadence]",
+                        [["once", "once"], ["monthly", "monthly"]], {}, class: "block w-full border rounded px-2 py-1" %>
+      </label>
+      <label class="block text-sm">
+        <span class="block mb-1">Starts <span class="opacity-60">(monthly only)</span></span>
+        <%= form.date_field "knowledge_expectation[start_on]", class: "block w-full border rounded px-2 py-1" %>
+      </label>
+      <label class="block text-sm">
+        <span class="block mb-1">Source <span class="opacity-60">("tracker item 14")</span></span>
+        <%= form.text_field "knowledge_expectation[source_note]", class: "block w-full border rounded px-2 py-1" %>
+      </label>
+    </div>
+    <div class="mt-3"><%= form.submit "Add expectation", class: "px-3 py-1.5 border rounded font-medium" %></div>
+  <% end %>
+</div>

data/app/views/studio/knowledge_docs/coverage.html.erb

@@ -0,0 +1,4 @@
+<%# /admin/knowledge/coverage — bare content wrapper; the table partial is the
+    primitive (renderable + testable on its own, like the browser). %>
+<%= render "studio/knowledge_docs/coverage_table",
+           expectations: @expectations, entity: @entity, entities: @entities %>

data/app/views/studio/knowledge_docs/show.html.erb

@@ -69,6 +69,15 @@
                           class: "block w-full border rounded px-2 py-1" %>
         </label>
       <% end %>
+      <% expectations = @linkable_expectations || [] %>
+      <% if expectations.any? %>
+        <label class="block text-sm" id="knowledge-expectation-select">
+          <span class="block mb-1">Fulfills expectation</span>
+          <%= form.select "knowledge_doc[expectation_id]",
+                          [["— none —", ""]] + expectations.map { |e| [ "#{e.title} (#{e.cadence})", e.id ] },
+                          { selected: @doc.expectation_id }, class: "block w-full border rounded px-2 py-1" %>
+        </label>
+      <% end %>
       <label class="block text-sm md:col-span-2">
         <span class="block mb-1">Summary (safe for "aware" agents)</span>
         <%= form.text_area "knowledge_doc[summary]", value: @doc.summary, rows: 3, class: "block w-full border rounded px-2 py-1" %>

data/app/views/studio/modals/blocks/_wallet_brand_sprite.html.erb

@@ -28,7 +28,8 @@
   whenever a brand is absent or unrecognised, instead of hiding the avatar and
   giving the surface two different shapes.
 
-  ONE CALLER DELIBERATELY DOES NOT: studio/modals/_wallet_connect paints a LETTER
+  ONE CALLER DELIBERATELY DOES NOT: solana-studio's
+  solana_studio/modals/_wallet_connect paints a LETTER
   TILE for a detected wallet whose brand it does not know, not se-wallet-default.
   A detected wallet always has a name (it registered through Wallet Standard to
   get there), and its initial identifies it where a generic mark would not. The

data/app/views/style/_modals.html.erb

@@ -182,8 +182,9 @@
         return { connecting: false, error: null, statusText: 'Connect Wallet',
                  walletAvailable: false, isMobile: false, connect: function () {} };
       };
-      // Connect stub for the promoted wallet picker (studio/modals/_wallet_connect,
-      // configured by style/modals/_wallet_connect). Performs NO connect: it
+      // Connect stub for the wallet picker (solana-studio
+      // solana_studio/modals/_wallet_connect, configured by
+      // style/modals/_wallet_connect). Performs NO connect: it
       // resolves success after a beat so the picker's connecting state is
       // visible and its onConnected hook can continue the demo walk.
       window.dsWalletConnectDemo = window.dsWalletConnectDemo || function () {
@@ -1169,9 +1170,9 @@
         (<code class="font-mono text-2xs">studio/modals/blocks/_wallet_brand_sprite</code>),
         so every app inherits them with no per-app icon files.
         The two <strong>Sign Wallet</strong> cards are a different kind of thing
-        from the rest of this section: they render
-        <code class="font-mono text-2xs">studio/modals/_web3_step_up</code> &mdash;
-        the <strong>REAL shared partial a host renders in production</strong>,
+        from the rest of this section: they render solana-studio's
+        <code class="font-mono text-2xs">solana_studio/modals/_web3_step_up</code>
+        &mdash; the <strong>REAL shared partial a host renders in production</strong>,
         not a style-guide copy of it &mdash; so what you review here is the
         shipped card, and it cannot drift from what users see. They also carry the
         <strong>standard web3 auth button</strong>: a wallet row (brand mark, the

data/app/views/style/modals/_wallet_connect_slot.html.erb

@@ -1,5 +1,6 @@
 <%#
-  The style guide's pre-connect slot for studio/modals/_wallet_connect — the
+  The style guide's pre-connect slot for solana-studio's
+  solana_studio/modals/_wallet_connect — the
   legal-age attestation, sitting exactly where turf-monster puts its own.
 
   A PARTIAL rather than a block because the picker takes its slot as a named

data/db/migrate/20260902000001_create_studio_knowledge_expectations.rb

@@ -0,0 +1,32 @@
+# Reference migration for Studio::KnowledgeExpectation — the "what SHOULD
+# exist" half of the knowledge layer's coverage view. Installed per consumer
+# like the other studio_* tables (`bin/rails studio_engine:install:migrations
+# && bin/rails db:migrate`); do not hand-copy.
+#
+# STYLE NOTE: reference migrations are written omakase-rubocop-compatible
+# (spaces inside array brackets) because the installed copy is linted by the
+# CONSUMER's rubocop, not this gem's.
+class CreateStudioKnowledgeExpectations < ActiveRecord::Migration[7.2]
+  def change
+    create_table :studio_knowledge_expectations do |t|
+      # Which business expects the document (same vocabulary as knowledge docs).
+      t.string :entity, null: false
+      t.string :title, null: false
+      # Folder the fulfilling documents live under; display + default, not a matcher.
+      t.string :path, null: false, default: ""
+      t.string :category
+      # once: a single document satisfies it forever.
+      # monthly: one document per calendar month from start_on onward.
+      t.string :cadence, null: false, default: "once"
+      # First month a monthly expectation owes a document (defaults to creation month).
+      t.date :start_on
+      # Provenance: "diligence tracker item 14", "lender checklist", …
+      t.string :source_note
+      t.boolean :active, null: false, default: true
+
+      t.timestamps
+    end
+
+    add_index :studio_knowledge_expectations, [ :entity, :active ]
+  end
+end

data/db/migrate/20260902000002_add_expectation_to_studio_knowledge_docs.rb

@@ -0,0 +1,9 @@
+# Links a knowledge doc to the expectation it fulfills — set at triage, an
+# EXPLICIT pointer rather than name-matching (a fuzzy match silently merges
+# lookalikes; an id never does). Installed per consumer; do not hand-copy.
+class AddExpectationToStudioKnowledgeDocs < ActiveRecord::Migration[7.2]
+  def change
+    add_column :studio_knowledge_docs, :expectation_id, :bigint
+    add_index :studio_knowledge_docs, :expectation_id
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.68.0"
+  VERSION = "0.69.1"
 end

data/lib/studio.rb

@@ -861,6 +861,14 @@ module Studio
       if Studio.draw_knowledge_routes
         get   "admin/knowledge",     to: "studio/knowledge_docs#index", as: :admin_knowledge
         post  "admin/knowledge",     to: "studio/knowledge_docs#create"
+        # Coverage (expected vs uploaded) — MUST precede the :id route below,
+        # or "coverage" is swallowed as a document id.
+        get   "admin/knowledge/coverage", to: "studio/knowledge_docs#coverage",
+              as: :admin_knowledge_coverage
+        post  "admin/knowledge/expectations", to: "studio/knowledge_docs#create_expectation",
+              as: :admin_knowledge_expectations
+        patch "admin/knowledge/expectations/:id", to: "studio/knowledge_docs#update_expectation",
+              as: :admin_knowledge_expectation
         get   "admin/knowledge/:id", to: "studio/knowledge_docs#show",  as: :admin_knowledge_doc
         patch "admin/knowledge/:id", to: "studio/knowledge_docs#update"
         get   "admin/knowledge/:id/download", to: "studio/knowledge_docs#download",

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.68.0
+  version: 0.69.1
 platform: ruby
 authors:
 - Alex McRitchie
@@ -363,6 +363,7 @@ files:
 - app/models/studio/enumeral.rb
 - app/models/studio/geo_setting.rb
 - app/models/studio/knowledge_doc.rb
+- app/models/studio/knowledge_expectation.rb
 - app/models/studio/link.rb
 - app/models/studio/model_page.rb
 - app/models/theme_setting.rb
@@ -441,8 +442,10 @@ files:
 - app/views/studio/knowledge_docs/_access_chips.html.erb
 - app/views/studio/knowledge_docs/_browser.html.erb
 - app/views/studio/knowledge_docs/_chip_styles.html.erb
+- app/views/studio/knowledge_docs/_coverage_table.html.erb
 - app/views/studio/knowledge_docs/_doc_row.html.erb
 - app/views/studio/knowledge_docs/_upload_form.html.erb
+- app/views/studio/knowledge_docs/coverage.html.erb
 - app/views/studio/knowledge_docs/index.html.erb
 - app/views/studio/knowledge_docs/show.html.erb
 - app/views/studio/links/confirm.html.erb
@@ -554,6 +557,8 @@ files:
 - db/migrate/20260813220000_add_standard_user_profile_columns.rb
 - db/migrate/20260818120000_create_studio_geo_settings.rb
 - db/migrate/20260901000001_create_studio_knowledge_docs.rb
+- db/migrate/20260902000001_create_studio_knowledge_expectations.rb
+- db/migrate/20260902000002_add_expectation_to_studio_knowledge_docs.rb
 - lib/studio-engine.rb
 - lib/studio.rb
 - lib/studio/cable.rb