studio-engine 0.67.2 → 0.69.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 79895e24dd5ade937ec8c0b4afacd84605ad495530a4c37f94e053a2c1040170
-  data.tar.gz: 0f1716ef07d10fc5388ea15853767f6c7e8911e076e280a096a8424a494eba9c
+  metadata.gz: 528dc35d5f8eb65f9c9be8b69d5541d9eaba24bb6e18ec1b2d144274c39f3b75
+  data.tar.gz: 92b56fbeda78e7404eaf3ea3832aaa4cc1faa43d88915be60bc4dc7cdc694a3e
 SHA512:
-  metadata.gz: 7c6e391302c996753b399019f2baeded267820a69d1f7451fe7ff68f82609fc625cc477cbdebb6127f74d0d5ed3a326ed4357d02c24b595e0fd1c213c3605895
-  data.tar.gz: 26bda400a871f3998a7baa64c72f43ed71a2d6d4ff177e02c4c6ae76d9bff65438e0bb33d48564802ea982bc2f628631906fc25e0a24167ec11d38796908310d
+  metadata.gz: 7d95ee9d3c5cf24d466feb69d52e90e763bc7985543740df1458d46dedca41def112f35ce2e3a6642b02ac37a195ac5efe2adec043ecad9516d3e03bd650c156
+  data.tar.gz: 4d2d7a231e57e84fb746d0b5db9c77f2780c03c1a7e817273a898bc4484be68d55765bcbc51ccd7e4fc784591bed4fadce17f6e28637ccdbbb713cb0ccf8070c

data/CHANGELOG.md

@@ -4,6 +4,51 @@ 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
+
+- **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
+  is empty, so bundling the gem IS the registration and a web2 app carries no
+  wallet markup at all. This completes the two-template split begun in 0.67.0,
+  which moved the four web3 MODALS to the gem and left the sign-in button as the
+  last web3 markup in the base engine. The gem half has shipped since
+  solana-studio **0.5.2** — until now this engine referenced that partial
+  nowhere, so the gem shipped a button no host rendered.
+  **Supersedes the stranded PR #245**, whose consumer lane was red only because
+  it opened before solana-studio 0.5.2 published.
+
+  **What did NOT change, deliberately:** `_methodDefaults.wallet` is still
+  `Studio.auth_method?(:wallet) && Studio.feature?(:web3)`. The Ruby gate
+  answers "is it implemented" (is the picker registered, does the credential
+  partial resolve) and gates the RENDER; Alpine's `methodOn('wallet')` still
+  answers "should it show" and gates VISIBILITY, which keeps the style guide's
+  method toggles working. Folding policy into the Ruby gate would delete the
+  button from the DOM on a web3-off app that bundles the gem, and the "or"
+  divider — which reads `methodOn('wallet')` too — would then float above a
+  button that is not there.
+
+  Hosts need no change: the engine's auth modal is a style-guide specimen
+  reached through `/admin/style`, and an app that bundles solana-studio 0.5.2 or
+  later sees the same button in the same place.
+
 ### Fixed
 
 - **Knowledge layer hardening** — the five findings from the 0.67.0 reviews:

data/README.md

@@ -257,6 +257,54 @@ What the engine **keeps** is the SESSION half of Solana sign-in:
 `Studio.wallet_sign_in_statement` — the single source for the signed statement,
 which the gem's deep link reads so the two cannot drift.
 
+#### The auth modal's credential slot
+
+The **sign-in modal itself stays here** and is never forked: every app in the
+ecosystem signs people in, and most of them are web2. What varies is *which
+credentials it offers*. Google and magic-link are implemented by this engine and
+render directly. The wallet button is implemented by the web3 layer, so it is
+**contributed** — `style/modals/_auth` looks for a partial at one fixed path and
+renders whatever it finds:
+
+    solana_studio/auth/_wallet_credential     (shipped by the solana-studio gem)
+
+Bundling the gem **is** the registration. There is no registry call and no
+config flag; an app without that layer renders nothing there, so a web2 app
+carries no wallet markup at all rather than markup hidden behind a flag. This is
+the same optional-partial convention as `modals/_host_extras` above, and it uses
+the same three-term `lookup_context.exists?`.
+
+Copying the auth modal into the gem was rejected deliberately: it would fork a
+surface both apps sign in through, and the two copies would drift — which is how
+the wallet picker reached three copies before it was promoted.
+
+**Two layers answer two different questions, and they are not merged:**
+
+| Question | Answered by | Where it is decided |
+|---|---|---|
+| Is it **implemented**? | the picker is registered, **and** the credential partial resolves | Ruby, in `style/modals/_auth` — gates the render |
+| Should it **show**? | `methodOn('wallet')`, falling back to `Studio.auth_method?(:wallet) && Studio.feature?(:web3)` | Alpine, inside the contributed partial — gates visibility |
+
+Both terms of the Ruby gate are load-bearing, and they fail differently. Without
+the **registration** term a layer that ships the credential but not the picker
+draws a button that opens an empty panel — not hypothetical, solana-studio 0.5.2
+shipped exactly that pair. Without the **existence** term an app whose picker
+resolves but whose credential does not raises `Missing partial` in front of
+someone signing in, instead of quietly rendering no button.
+
+Policy stays **out** of the Ruby gate on purpose. Folding
+`auth_method?(:wallet)` and `feature?(:web3)` into the render would delete the
+button from the DOM on a web3-off app that bundles the gem — and the "or"
+divider reads `methodOn('wallet')` too, so ticking Solana Wallet on the style
+guide's Sign in card would then float a divider above a button that is not
+there.
+
+A contributed partial renders inside the modal's own Alpine scope, so it may use
+`methodOn(...)`, `attested()` (the legal-age gate — call it, or wallet becomes
+the one credential that skips attestation) and `props.submitting`. It receives
+one local, `modal_store`: the engine's real host is `"modals"`, the living style
+guide's page-scoped host is `"dsModals"`.
+
 It also keeps two blocks the gem renders **by name** across the gem boundary:
 `studio/modals/blocks/wallet_brand_sprite` and `studio/modals/blocks/card_header`.
 Renaming either is a cross-repo change.

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/style/modals/_auth.html.erb

@@ -18,26 +18,69 @@
   No real auth happens — the demo shows the real UI.
 
   LOCALS:
-    web3_gem (Boolean, required) — does solana-studio resolve. style/_modals
-    owns the lookup and registers wallet-connect behind the same flag; the
-    Solana button below is rendered only when it is true, because a button that
-    swaps to an unregistered id opens an empty panel. Fetched without a default
-    on purpose: a caller that forgets it should fail loudly here rather than
+    web3_gem (Boolean, required) — does solana-studio resolve, meaning is the
+    wallet-connect picker on the view path. style/_modals owns the lookup and
+    registers wallet-connect behind the same flag. Fetched without a default on
+    purpose: a caller that forgets it should fail loudly here rather than
     silently drop Solana sign-in from an app that has the gem.
 
-  NOT gated on web3_gem, deliberately: _methodDefaults.wallet below. It is the
-  fallback methodOn uses when an opener passes no methods hash, and on a base
-  app nothing reaches it — the Sign in card always passes explicit booleans, and
-  the only opener that omits them is the wallet picker's back button, which
-  needs the gem to exist at all. Adding the term there would read like a third
-  gate while changing no rendered outcome and no behaviour, and a gate that
-  cannot be shown to bite is decoration. The trigger below is the real gate.
+  THE CREDENTIAL SLOT. Google and magic-link are implemented by this engine, so
+  they render below directly. Wallet is not: it belongs to the web3 bolt-on, and
+  a base-template app — a newsletter, a hub — must not carry markup it can never
+  render. So the wallet button is CONTRIBUTED by whichever layer implements it,
+  as a partial this file merely looks for:
+
+    solana_studio/auth/wallet_credential
+
+  Bundling the gem IS the registration. An app without that layer renders
+  nothing here and carries no wallet markup at all, rather than shipping a
+  button hidden behind a flag.
+
+  TWO LAYERS ANSWER TWO DIFFERENT QUESTIONS, and they are deliberately NOT
+  merged into one:
+
+    Ruby, below      IS IT IMPLEMENTED. Is the picker this button swaps to
+                     registered (web3_gem), and does a layer actually ship the
+                     credential partial. This gates the RENDER.
+    Alpine, in the   SHOULD IT SHOW. methodOn('wallet'), which reads
+    contributed      props.methods first so the Sign in card's toggle overrides
+    partial          the server default outright. This gates VISIBILITY.
+
+  KEEPING POLICY OUT OF THE RUBY GATE IS LOAD-BEARING, and it is why
+  auth_method?(:wallet) and feature?(:web3) are NOT terms in the render gate.
+  Fold them in and the button leaves the DOM on a web3-off app that bundles the
+  gem — and then ticking Solana Wallet on the Sign in card turns the divider
+  below on above a button that is not there, because the divider reads
+  methodOn('wallet') too. Measured: that is the exact failure this slot was
+  meant to remove, reintroduced one layer up.
+
+  NOT gated on the slot, deliberately: _methodDefaults.wallet below. It stays
+  the app's own policy answer and is unchanged by the move. It is the fallback
+  methodOn uses when an opener passes no methods hash, and on a base app nothing
+  reaches it — the Sign in card always passes explicit booleans, and the only
+  opener that omits them is the wallet picker's back button, which needs the gem
+  to exist at all.
 
   CRITICAL: rendered inside <template x-if="id==='auth'"> — Alpine requires a
   SINGLE root, so everything lives inside the outer <div>. The x-data is a
   double-quoted attribute: keep it free of double-quotes and backticks.
 %>
 <% web3_gem = local_assigns.fetch(:web3_gem) %>
+<%# BOTH terms are load-bearing, and they fail differently.
+
+    web3_gem  is the picker this button swaps to actually REGISTERED. A layer
+      that ships the credential partial without the picker draws a button that
+      opens an empty panel — not hypothetical: solana-studio 0.5.2 shipped
+      exactly that pair, the credential without wallet_connect.
+    exists?   does a layer ship the button AT ALL. Without it, an app whose
+      picker resolves but whose credential does not raises Missing partial in
+      front of someone signing in, instead of rendering no button.
+
+    Same three-term lookup_context.exists? the modal host uses for host_extras
+    (studio/modals/_host.html.erb): name, prefixes, partial. %>
+<% wallet_credential = "solana_studio/auth/wallet_credential" %>
+<% wallet_credential_available = web3_gem &&
+                                 lookup_context.exists?("wallet_credential", ["solana_studio/auth"], true) %>
 <div x-data="{
        email: '',
        ageAttested: false,
@@ -85,10 +128,6 @@
            if (pp) pp.submitting = null;
          }, 1200);
        },
-       openWalletHub() {
-         if (!this.attested()) return;
-         Alpine.store('dsModals').swap('wallet-connect', { backTo: 'auth', ageAttested: true });
-       },
        async submitMagicLink() {
          if (!this.attested()) return;
          var p = this.props;
@@ -184,35 +223,19 @@
         <p role="alert" class="text-red-400 text-xs -mt-2 mb-3" x-text="props.googleError"></p>
       </template>
 
-      <%# 2. Solana — progresses to the Connect Wallet picker modal. TWO gates,
-          asking two different questions, and only one of them is Alpine's:
-
-            x-show methodOn('wallet')  POLICY — does this app offer wallet as a
-              credential, and has the specimen card's toggle turned it on. Reads
-              props.methods.wallet first, so the card's checkbox overrides the
-              server default outright.
-            Ruby web3_gem             CAPABILITY — does solana-studio resolve, so
-              that something actually REGISTERED the wallet-connect id this button
-              swaps to. style/_modals wraps that registration in the same gate.
+      <%# 2. Wallet — CONTRIBUTED, not written here. See the credential-slot note
+          at the top of this file. The partial owns the button, its brand mark
+          and its click handler; this engine owns only the decision to look for
+          it. An app with no web3 layer on its view path renders nothing at all
+          here, which is the whole point: the base template ships no wallet
+          markup.
 
-          The policy gate cannot stand in for the capability one: a base app can
-          answer yes to the first and no to the second, and then the button opens
-          an empty panel. It has to be the RUBY gate because the toggle can flip
-          every Alpine term, and a control the operator can tick is not a gate. %>
-      <% if web3_gem %>
-        <button @click="openWalletHub()" x-show="methodOn('wallet')" :disabled="!!props.submitting"
-                class="btn btn-neutral btn-lg w-full gap-3 mb-3 disabled:cursor-wait">
-          <svg width="18" height="14" viewBox="0 0 397 311" fill="none" x-show="props.submitting !== 'wallet'" aria-hidden="true">
-            <defs><linearGradient id="auth-solana-grad" x1="361" y1="-9" x2="153" y2="389" gradientUnits="userSpaceOnUse">
-              <stop offset="0" stop-color="#00FFA3"/><stop offset="1" stop-color="#DC1FFF"/>
-            </linearGradient></defs>
-            <path d="M65 234c2-2 6-4 9-4h317c6 0 9 7 5 11l-63 63c-2 2-6 4-9 4H6c-6 0-9-7-5-11l64-63z" fill="url(#auth-solana-grad)"/>
-            <path d="M65 4c2-2 6-4 9-4h317c6 0 9 7 5 11l-63 63c-2 2-6 4-9 4H6c-6 0-9-7-5-11L65 4z" fill="url(#auth-solana-grad)"/>
-            <path d="M333 119c-2-2-6-4-9-4H7c-6 0-9 7-5 11l63 63c2 2 6 4 9 4h317c6 0 9-7 5-11l-63-63z" fill="url(#auth-solana-grad)"/>
-          </svg>
-          <span x-show="props.submitting === 'wallet'" class="spinner" aria-hidden="true"></span>
-          <span x-text="props.submitting === 'wallet' ? 'Connecting…' : 'Solana'"></span>
-        </button>
+          Visibility is still Alpine's. The contributed partial carries
+          x-show methodOn('wallet'), so the Sign in card's toggle drives it
+          exactly as it drove the button that used to live here, and the divider
+          below can never float above a button the DOM is missing. %>
+      <% if wallet_credential_available %>
+        <%= render wallet_credential, modal_store: "dsModals" %>
       <% end %>
 
       <%# "or" divider — only when magic-link AND a social method are both on. %>

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.67.2"
+  VERSION = "0.69.0"
 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.67.2
+  version: 0.69.0
 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