studio-engine 0.66.2 → 0.67.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 575e62e3700969f869d9e6b079c13a142c164cd655bf95d22be6eea95817e2c8
-  data.tar.gz: c8ea9ca891cf76ebe2a1f4dbdf1e343546cca37917851feb7151fe59517b3a06
+  metadata.gz: 3ffd4e2260ecf5e4ed81cbe17b45001ac14b3bcbf576b4fd79b506bfa2fff6dc
+  data.tar.gz: d7f03282009eeb8f914637df864769fb5846808d4ccc270a1285c04564b18418
 SHA512:
-  metadata.gz: 7387284b53eb7df98f34204d84bff4e10525c6fc1ff81a9e4ef01ae2418d5a689f523984ee94c128746ac260cc3af9c258c5fd15f81486f506d77e182a8dfb7c
-  data.tar.gz: a1d93bcf649e7494cac13bab83cc76051e1e86c92f942558e2740f97ee98934ac77c2ebae989cee815c61d50f8e72c305f55f0cd714ebe9b8c4cfa8dd2bec7de
+  metadata.gz: 1ab14b588d1d5382cc1738205472ba01b3f7aeb4442b026a506a824e777060eeae59ab7873d3176bfb6fd5f1ca95633a052e02b69ebe8f7715a6c9a8cdc1d821
+  data.tar.gz: 9256f176a552cea09a38ec5e56b32749ce4e419f5231b90971e6c14f2099983e6b4be646cdac8cc5efdef2e6d476714875c00ff1beae980f66c31752446c7123

data/CHANGELOG.md

@@ -6,6 +6,30 @@ The format is [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). This pro
 
 ### Added
 
+- **Knowledge layer primitive** — `Studio::KnowledgeDoc` + `/admin/knowledge`:
+  an S3-backed document store for an entity's business knowledge, built for the
+  McRitchie Industries acquisition agents (Samson/Dawn) but app-agnostic.
+  One row per document: entity, implicit folder `path` (the S3 key mirrors it,
+  so the bucket stays human-browsable), category, `document_date` (the as-of
+  date, distinct from upload time), `inbox → filed → superseded` lifecycle, and
+  a per-agent access map with three levels — `full` (reads the facts), `aware`
+  (knows the document exists and gets the safe `summary` + boundary line, not
+  the contents), `none` (does not see the row). "Aware" exists because an agent
+  with a hole in its context confabulates or stonewalls; one with an awareness
+  entry has something true to say and a boundary to hold.
+  The browser renders folder and flat ("show all") views with breadcrumbs,
+  entity/status filters, an inbox badge, per-agent access chips, and an intake
+  form whose uploads land as `inbox` for triage; downloads are 15-minute
+  presigned GETs. Storage goes through `Studio::S3` and **fails loudly** on an
+  unconfigured app (`NotConfigured` raised, plus a red banner on the browser) —
+  never a silent drop. Routes are opt-in (`Studio.draw_knowledge_routes`,
+  default off); `Studio.knowledge_agents` names the agent roster the intake UI
+  offers selects for. Ships the reference migration
+  `create_studio_knowledge_docs` — consumers run
+  `bin/rails studio_engine:install:migrations && bin/rails db:migrate`.
+  Deferred to a later cut, recorded on the task: coverage view against a
+  diligence tracker, recurring-series tracking, per-folder access defaults.
+
 - **A green comment-leak scan used to mean "not looked at".**
   `test/views/erb_comment_leak_test.rb` guards the ERB comment form in
   `app/views/**/*.erb`. It never looked inside `<script>`, and that is where this

data/app/controllers/studio/knowledge_docs_controller.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Studio
+  # /admin/knowledge — the knowledge layer's browser + intake surface.
+  #
+  # A plain host-inherited controller whose views are bare content wrappers,
+  # like /admin/geo, so pages render inside each host's application layout and
+  # pick up that app's navbar and theme. Routes are opt-in
+  # (Studio.draw_knowledge_routes) — see Studio.routes.
+  #
+  # Uploads land as status "inbox"; an agent running the knowledge-intake SOP
+  # (or the operator, on the show page) files them — classification is a
+  # deliberate second step, not a side effect of upload.
+  class KnowledgeDocsController < ApplicationController
+    before_action :require_admin
+    before_action :set_doc, only: [:show, :update, :download]
+
+    VIEWS = %w[folders flat].freeze
+
+    def index
+      @view    = VIEWS.include?(params[:view]) ? params[:view] : "folders"
+      @folder  = Studio::KnowledgeDoc.normalize_path(params[:folder])
+      @entity  = params[:entity].presence
+      @status  = Studio::KnowledgeDoc::STATUSES.include?(params[:status]) ? params[:status] : nil
+
+      scope = Studio::KnowledgeDoc.order(created_at: :desc)
+      scope = scope.for_entity(@entity) if @entity
+      scope = scope.where(status: @status) if @status
+
+      @entities   = Studio::KnowledgeDoc.distinct.pluck(:entity).sort
+      @inbox_size = scope.inbox.count
+
+      if @view == "folders"
+        @folders = scope.folders_under(@folder)
+        @docs    = scope.in_folder(@folder)
+      else
+        @folders = []
+        @docs    = scope
+      end
+    end
+
+    def show
+    end
+
+    def create
+      file = params.dig(:knowledge_doc, :file)
+      doc  = Studio::KnowledgeDoc.intake!(
+        doc_params.merge(uploaded_by: current_user&.email, status: "inbox"),
+        file: file
+      )
+      redirect_to admin_knowledge_doc_path(doc), notice: "#{doc.title} landed in the inbox."
+    rescue Studio::S3::NotConfigured, Studio::KnowledgeDoc::MissingTable => e
+      redirect_to admin_knowledge_path, alert: e.message
+    rescue ActiveRecord::RecordInvalid => e
+      redirect_to admin_knowledge_path, alert: e.message
+    end
+
+    def update
+      @doc.update!(doc_params)
+      redirect_to admin_knowledge_doc_path(@doc), notice: "#{@doc.title} updated."
+    rescue ActiveRecord::RecordInvalid => e
+      redirect_to admin_knowledge_doc_path(@doc), alert: e.message
+    end
+
+    def download
+      return redirect_to admin_knowledge_doc_path(@doc), alert: "No file attached." unless @doc.file?
+
+      redirect_to @doc.signed_url, allow_other_host: true
+    end
+
+    private
+
+    def set_doc
+      @doc = Studio::KnowledgeDoc.find(params[:id])
+    end
+
+    def doc_params
+      permitted = params.require(:knowledge_doc)
+                        .permit(:title, :entity, :path, :category, :summary,
+                                :document_date, :source_note, :status, 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]
+        permitted[:access] = permitted[:access].to_h.reject { |_agent, level| level.blank? }
+      end
+      permitted
+    end
+  end
+end

data/app/models/studio/knowledge_doc.rb

@@ -0,0 +1,207 @@
+module Studio
+  # One row per document in an entity's knowledge layer: the S3 object pointer,
+  # the filing metadata (entity, folder path, category, as-of date), and the
+  # per-agent access map that says who may read it and at what depth.
+  #
+  # The access model has three levels, because "not allowed to read it" and
+  # "does not know it exists" are different states:
+  #
+  #   full  — the agent reads the document and its facts.
+  #   aware — the agent knows the document exists and gets `summary` (the safe
+  #           summary + boundary line), not the contents. An agent with a HOLE
+  #           in its context confabulates or stonewalls; one with an awareness
+  #           entry has something true to say and a boundary to hold.
+  #   none  — the agent does not see the row at all (the default).
+  #
+  # Folders are implicit: a document claims a `path` and the folder exists.
+  # The S3 key mirrors entity + path, so the bucket stays human-browsable.
+  # Uploads land as status "inbox" for agent triage (the knowledge-intake SOP);
+  # filing flips them "filed"; a replacement marks the old row "superseded".
+  #
+  # Storage goes through Studio::S3 and FAILS LOUDLY on an unconfigured app
+  # (Studio::S3::NotConfigured) — never wrap intake in a rescue that returns
+  # success; a QA lane once lost weeks of writes to exactly that.
+  #
+  # Like Studio::Link, the table is installed per consumer app by
+  # `bin/rails studio_engine:install:migrations && bin/rails db:migrate`.
+  class KnowledgeDoc < ApplicationRecord
+    self.table_name = "studio_knowledge_docs"
+
+    # The app drew knowledge routes but never installed the table. Raised in
+    # place of a bare PG::UndefinedTable so the first person to hit it reads
+    # the fix instead of an adapter error — see .intake!.
+    class MissingTable < StandardError; end
+
+    ACCESS_LEVELS = %w[full aware none].freeze
+    STATUSES      = %w[inbox filed superseded].freeze
+
+    validates :title,  presence: true
+    validates :entity, presence: true
+    validates :status, inclusion: { in: STATUSES }
+    validate  :access_levels_are_known
+
+    before_validation :normalize_fields
+
+    scope :for_entity, ->(entity) { where(entity: entity) }
+    scope :inbox,      -> { where(status: "inbox") }
+    scope :filed,      -> { where(status: "filed") }
+    scope :active,     -> { where.not(status: "superseded") }
+    scope :in_folder,  ->(path) { where(path: normalize_path(path)) }
+    scope :under, lambda { |base|
+      base = normalize_path(base)
+      base.empty? ? all : where("path = ? OR path LIKE ?", base, "#{base}/%")
+    }
+
+    class << self
+      # Create + upload in one call — the write path the intake UI and the
+      # knowledge-intake SOP use. `file` responds to #read (an uploaded file);
+      # metadata-only records (file: nil) are legal.
+      #
+      # Table-missing is checked up front so the failure names its fix before
+      # any bytes reach S3.
+      def intake!(attrs, file: nil)
+        unless table_exists?
+          raise MissingTable,
+                "The knowledge layer needs the studio_knowledge_docs table, and #{Studio.app_name} has " \
+                "no such table. Run `bin/rails studio_engine:install:migrations && bin/rails db:migrate` " \
+                "(install ALL of them). Do not hand-copy the migration — it collides with the installed " \
+                "copy on `class CreateStudioKnowledgeDocs`."
+        end
+
+        doc = new(attrs)
+        doc.title = default_title(file) if doc.title.blank? && file
+        doc.validate!
+        doc.attach!(file) if file
+        doc.save!
+        doc
+      end
+
+      # Immediate child folder names under `base` for this scope, derived from
+      # the paths documents actually claim — there is no folder table.
+      #
+      # unscope(:order) is load-bearing: callers hand in display-ordered scopes,
+      # and Postgres refuses SELECT DISTINCT with an ORDER BY column outside the
+      # select list (SQLite tolerates it, so only a real consumer sees the 500).
+      def folders_under(base = "")
+        base   = normalize_path(base)
+        prefix = base.empty? ? "" : "#{base}/"
+        unscope(:order).distinct.pluck(:path).filter_map { |path|
+          next if path == base || !path.start_with?(prefix)
+
+          path.delete_prefix(prefix).split("/").first
+        }.uniq.sort
+      end
+
+      # "/a//b/" -> "a/b". Nil-safe; the empty string is the root folder.
+      def normalize_path(value)
+        value.to_s.strip.squeeze("/").delete_prefix("/").delete_suffix("/")
+      end
+
+      def default_title(file)
+        name = file.respond_to?(:original_filename) ? file.original_filename : File.basename(file.to_s)
+        File.basename(name.to_s, ".*").tr("_-", "  ").squeeze(" ").strip.presence
+      end
+    end
+
+    # --- access ---------------------------------------------------------------
+
+    def access_for(agent)
+      level = access.is_a?(Hash) ? access[agent.to_s] : nil
+      ACCESS_LEVELS.include?(level) ? level : "none"
+    end
+
+    # full or aware — the agent may know this document exists.
+    def visible_to?(agent)
+      access_for(agent) != "none"
+    end
+
+    def full_for?(agent)
+      access_for(agent) == "full"
+    end
+
+    # --- storage --------------------------------------------------------------
+
+    def file?
+      s3_key.present?
+    end
+
+    # Upload the file's bytes and point this row at them. The key mirrors
+    # entity + path so the bucket reads like the folder tree. Raises
+    # Studio::S3::NotConfigured on an app with no bucket — deliberately.
+    def attach!(file)
+      filename = file.respond_to?(:original_filename) ? file.original_filename : File.basename(file.to_s)
+      content_type = file.respond_to?(:content_type) ? file.content_type : nil
+      body = file.respond_to?(:read) ? file.read : file.to_s
+
+      key = [
+        "knowledge", entity, path.presence,
+        "#{Time.current.strftime('%Y%m%d%H%M%S')}-#{self.class.sanitize_filename(filename)}"
+      ].compact.join("/")
+
+      Studio::S3.upload(key: key, body: body, content_type: content_type)
+      self.s3_key    = key
+      self.mime_type = content_type if content_type
+      self.byte_size = body.bytesize if body.respond_to?(:bytesize)
+      self
+    end
+
+    # 15-minute presigned GET — the only way a private object leaves the bucket.
+    def signed_url(expires_in: 900)
+      raise Studio::S3::Error, "no file attached to #{title.inspect}" unless file?
+
+      Studio::S3.signed_url(key: s3_key, expires_in: expires_in)
+    end
+
+    # --- lifecycle ------------------------------------------------------------
+
+    def supersede_with!(replacement)
+      update!(status: "superseded", superseded_by_id: replacement.id)
+    end
+
+    def superseded?
+      status == "superseded"
+    end
+
+    def folder_segments
+      path.blank? ? [] : path.split("/")
+    end
+
+    # The date the row sorts and displays by: the document's own as-of date,
+    # falling back to upload time for undated material.
+    def display_date
+      document_date || created_at&.to_date
+    end
+
+    def self.sanitize_filename(name)
+      base = name.to_s.strip
+      return "document" if base.empty?
+
+      base.gsub(/[^A-Za-z0-9._-]+/, "-").squeeze("-")
+          .gsub(/-(?=\.)|\A-|-\z/, "").downcase
+          .presence || "document"
+    end
+
+    private
+
+    def normalize_fields
+      self.path   = self.class.normalize_path(path)
+      self.entity = entity.to_s.strip.downcase if entity
+      if access.is_a?(Hash)
+        self.access = access.each_with_object({}) do |(agent, level), map|
+          map[agent.to_s.strip.downcase] = level.to_s.strip.downcase if agent.present?
+        end
+      end
+    end
+
+    def access_levels_are_known
+      return if access.blank?
+      return errors.add(:access, "must be a map of agent => level") unless access.is_a?(Hash)
+
+      access.each do |agent, level|
+        unless ACCESS_LEVELS.include?(level)
+          errors.add(:access, "level for #{agent.inspect} must be one of #{ACCESS_LEVELS.join(', ')}")
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,10 @@
+<%# Per-agent access chips — who may know this document, at which depth.
+    Renders the map the document actually carries (any agent slug), so a chip
+    never lies about roster membership. Locals: doc:. %>
+<% if doc.access.blank? %>
+  <span class="knowledge-chip knowledge-chip-none">no agents</span>
+<% else %>
+  <% doc.access.sort.each do |agent, level| %>
+    <span class="knowledge-chip knowledge-chip-<%= level %>"><%= agent %> · <%= level %></span>
+  <% end %>
+<% end %>

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

@@ -0,0 +1,115 @@
+<%# The knowledge-layer browser. Locals:
+      view:       "folders" | "flat"
+      folder:     current folder path ("" = root; folder view only)
+      entity:     entity filter or nil
+      status:     status filter or nil
+      entities:   all entity slugs (for the filter row)
+      folders:    immediate child folder names (folder view)
+      docs:       the documents to list
+      inbox_size: count of inbox docs in the current scope
+
+    Styling note: gem-specific looks live in the scoped <style> below because a
+    host's Tailwind build may not scan this gem's views (same reasoning as the
+    geo grid). Layout leans on utilities every host already ships. %>
+<style>
+  .knowledge-chip { display: inline-block; padding: 0 .5rem; border-radius: 9999px;
+    font-size: .7rem; line-height: 1.4rem; border: 1px solid transparent; white-space: nowrap; }
+  .knowledge-chip-full  { background: rgb(16 185 129 / .12); border-color: rgb(16 185 129 / .4); color: rgb(5 150 105); }
+  .knowledge-chip-aware { background: rgb(245 158 11 / .12); border-color: rgb(245 158 11 / .4); color: rgb(180 83 9); }
+  .knowledge-chip-none  { background: rgb(148 163 184 / .12); border-color: rgb(148 163 184 / .4); color: rgb(100 116 139); }
+  .knowledge-status { font-size: .7rem; padding: 0 .45rem; border-radius: .25rem; border: 1px solid rgb(148 163 184 / .5); }
+  .knowledge-status-inbox      { border-color: rgb(245 158 11 / .6); color: rgb(180 83 9); }
+  .knowledge-status-superseded { text-decoration: line-through; opacity: .6; }
+  .knowledge-folder { display: inline-flex; align-items: center; gap: .4rem; padding: .35rem .75rem;
+    border: 1px solid rgb(148 163 184 / .4); border-radius: .5rem; }
+</style>
+
+<% unless Studio::S3.configured? %>
+  <div id="knowledge-storage-warning" class="mb-4 p-3 border rounded" style="border-color: rgb(239 68 68 / .5); color: rgb(220 38 38);">
+    Object storage is not configured — set <code>Studio.s3_bucket_prefix</code> in
+    <code>config/initializers/studio.rb</code>. Uploads will refuse rather than
+    silently drop files.
+  </div>
+<% end %>
+
+<div class="flex flex-wrap items-center justify-between gap-3 mb-4">
+  <h1 class="text-xl font-semibold">
+    Knowledge
+    <% if inbox_size.to_i.positive? %>
+      <%= link_to "#{inbox_size} in inbox",
+                  admin_knowledge_path(view: "flat", entity: entity, status: "inbox"),
+                  id: "knowledge-inbox-badge", class: "knowledge-status knowledge-status-inbox ml-2 align-middle" %>
+    <% end %>
+  </h1>
+  <div id="knowledge-view-toggle" class="flex items-center gap-2 text-sm">
+    <%= link_to "Folders", admin_knowledge_path(view: "folders", entity: entity, status: status),
+                class: view == "folders" ? "font-semibold underline" : "" %>
+    <span aria-hidden="true">·</span>
+    <%= link_to "Show all", admin_knowledge_path(view: "flat", entity: entity, status: status),
+                class: view == "flat" ? "font-semibold underline" : "" %>
+  </div>
+</div>
+
+<% if entities.length > 1 || entity %>
+  <div id="knowledge-entity-filter" class="flex flex-wrap items-center gap-2 mb-3 text-sm">
+    <%= link_to "All entities", admin_knowledge_path(view: view),
+                class: entity ? "" : "font-semibold underline" %>
+    <% entities.each do |candidate| %>
+      <%= link_to candidate, admin_knowledge_path(view: view, entity: candidate),
+                  class: candidate == entity ? "font-semibold underline" : "" %>
+    <% end %>
+  </div>
+<% end %>
+
+<% if view == "folders" %>
+  <nav id="knowledge-breadcrumbs" class="text-sm mb-3">
+    <%= link_to "root", admin_knowledge_path(view: "folders", entity: entity, status: status) %>
+    <% segments = folder.blank? ? [] : folder.split("/") %>
+    <% segments.each_with_index do |segment, index| %>
+      <span aria-hidden="true">/</span>
+      <%= link_to segment,
+                  admin_knowledge_path(view: "folders", entity: entity, status: status,
+                                       folder: segments[0..index].join("/")) %>
+    <% end %>
+  </nav>
+
+  <% if folders.any? %>
+    <div class="flex flex-wrap gap-2 mb-4">
+      <% folders.each do |name| %>
+        <%= link_to admin_knowledge_path(view: "folders", entity: entity, status: status,
+                                         folder: [folder.presence, name].compact.join("/")),
+                    id: "knowledge-folder-#{name.parameterize}", class: "knowledge-folder" do %>
+          <span aria-hidden="true">📁</span> <%= name %>
+        <% end %>
+      <% end %>
+    </div>
+  <% end %>
+<% end %>
+
+<% if docs.any? %>
+  <div class="overflow-x-auto">
+    <table id="knowledge-docs" class="w-full text-sm">
+      <thead>
+        <tr class="text-left border-b">
+          <th class="py-2 pr-3">Document</th>
+          <% if view == "flat" %><th class="py-2 pr-3">Folder</th><% end %>
+          <th class="py-2 pr-3">Category</th>
+          <th class="py-2 pr-3">As of</th>
+          <th class="py-2 pr-3">Status</th>
+          <th class="py-2 pr-3">Access</th>
+        </tr>
+      </thead>
+      <tbody>
+        <% docs.each do |doc| %>
+          <%= render "studio/knowledge_docs/doc_row", doc: doc, view: view %>
+        <% end %>
+      </tbody>
+    </table>
+  </div>
+<% else %>
+  <p id="knowledge-empty" class="text-sm opacity-70 mb-4">
+    <%= view == "folders" && folder.present? ? "This folder holds no documents." : "No documents yet — upload the first one below." %>
+  </p>
+<% end %>
+
+<%= render "studio/knowledge_docs/upload_form", entity: entity, folder: folder %>

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

@@ -0,0 +1,18 @@
+<%# One document row. Locals: doc:, view: ("folders" | "flat"). %>
+<tr id="knowledge-doc-<%= doc.id %>" class="border-b align-top <%= "opacity-60" if doc.superseded? %>">
+  <td class="py-2 pr-3">
+    <%= link_to doc.title, admin_knowledge_doc_path(doc), class: "font-medium" %>
+    <% if doc.summary.present? %>
+      <div class="text-xs opacity-70 max-w-md truncate"><%= doc.summary %></div>
+    <% end %>
+  </td>
+  <% if view == "flat" %>
+    <td class="py-2 pr-3 text-xs opacity-80"><%= doc.path.presence || "root" %></td>
+  <% end %>
+  <td class="py-2 pr-3"><%= doc.category %></td>
+  <td class="py-2 pr-3 whitespace-nowrap"><%= doc.display_date&.iso8601 %></td>
+  <td class="py-2 pr-3">
+    <span class="knowledge-status knowledge-status-<%= doc.status %>"><%= doc.status %></span>
+  </td>
+  <td class="py-2 pr-3"><%= render "studio/knowledge_docs/access_chips", doc: doc %></td>
+</tr>

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

@@ -0,0 +1,48 @@
+<%# Intake form — uploads land as status "inbox" for triage; classification is
+    the second step (the show page / the knowledge-intake SOP), so this form
+    asks only for what the uploader knows at drop time. Locals: entity:, folder:
+    (both may be blank; they pre-fill from where the browser stands). %>
+<div id="knowledge-upload" class="mt-6 p-4 border rounded">
+  <h2 class="font-semibold mb-3">Add a document</h2>
+  <%= form_with url: admin_knowledge_path, method: :post, multipart: true, local: true do |form| %>
+    <div class="grid gap-3 md:grid-cols-2">
+      <label class="block text-sm">
+        <span class="block mb-1">File</span>
+        <%= form.file_field "knowledge_doc[file]", required: true, class: "block w-full text-sm" %>
+      </label>
+      <label class="block text-sm">
+        <span class="block mb-1">Title <span class="opacity-60">(blank = from filename)</span></span>
+        <%= form.text_field "knowledge_doc[title]", 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_doc[entity]", value: entity, required: true,
+                            placeholder: "commercial-welding-llc", 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_doc[path]", value: folder,
+                            placeholder: "financials/aging-inventory/2026-08", class: "block w-full border rounded px-2 py-1" %>
+      </label>
+      <label class="block text-sm">
+        <span class="block mb-1">Document date <span class="opacity-60">(the as-of date, not today)</span></span>
+        <%= form.date_field "knowledge_doc[document_date]", 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">(who/where it came from)</span></span>
+        <%= form.text_field "knowledge_doc[source_note]", class: "block w-full border rounded px-2 py-1" %>
+      </label>
+      <% Array(Studio.knowledge_agents).each do |agent| %>
+        <label class="block text-sm" id="knowledge-access-<%= agent %>">
+          <span class="block mb-1">Access — <%= agent %></span>
+          <%= form.select "knowledge_doc[access][#{agent}]",
+                          [["none (default)", ""], ["aware — knows it exists", "aware"], ["full — reads the facts", "full"]],
+                          {}, class: "block w-full border rounded px-2 py-1" %>
+        </label>
+      <% end %>
+    </div>
+    <div class="mt-3">
+      <%= form.submit "Upload to inbox", class: "px-3 py-1.5 border rounded font-medium" %>
+    </div>
+  <% end %>
+</div>

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

@@ -0,0 +1,6 @@
+<%# /admin/knowledge — bare content wrapper; the browser partial is the
+    primitive (renderable + testable on its own, like studio/board/_board). %>
+<%= render "studio/knowledge_docs/browser",
+           view: @view, folder: @folder, entity: @entity, status: @status,
+           entities: @entities, folders: @folders, docs: @docs,
+           inbox_size: @inbox_size %>

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

@@ -0,0 +1,87 @@
+<%# /admin/knowledge/:id — one document: metadata, access, download, and the
+    triage form that files it out of the inbox. %>
+<style>
+  .knowledge-chip { display: inline-block; padding: 0 .5rem; border-radius: 9999px;
+    font-size: .7rem; line-height: 1.4rem; border: 1px solid transparent; white-space: nowrap; }
+  .knowledge-chip-full  { background: rgb(16 185 129 / .12); border-color: rgb(16 185 129 / .4); color: rgb(5 150 105); }
+  .knowledge-chip-aware { background: rgb(245 158 11 / .12); border-color: rgb(245 158 11 / .4); color: rgb(180 83 9); }
+  .knowledge-chip-none  { background: rgb(148 163 184 / .12); border-color: rgb(148 163 184 / .4); color: rgb(100 116 139); }
+</style>
+
+<div class="mb-4 text-sm">
+  <%= link_to "← Knowledge", admin_knowledge_path(folder: @doc.path.presence) %>
+</div>
+
+<div class="flex flex-wrap items-start justify-between gap-3 mb-4">
+  <div>
+    <h1 class="text-xl font-semibold"><%= @doc.title %></h1>
+    <div class="text-sm opacity-70"><%= @doc.entity %> · <%= @doc.path.presence || "root" %></div>
+  </div>
+  <% if @doc.file? %>
+    <%= link_to "Download (15-min link)", admin_knowledge_doc_download_path(@doc),
+                id: "knowledge-download", class: "px-3 py-1.5 border rounded font-medium" %>
+  <% end %>
+</div>
+
+<dl id="knowledge-doc-meta" class="grid gap-x-8 gap-y-2 md:grid-cols-2 text-sm mb-6">
+  <div><dt class="opacity-60">Status</dt><dd><%= @doc.status %></dd></div>
+  <div><dt class="opacity-60">Category</dt><dd><%= @doc.category.presence || "—" %></dd></div>
+  <div><dt class="opacity-60">Document date</dt><dd><%= @doc.document_date&.iso8601 || "—" %></dd></div>
+  <div><dt class="opacity-60">Uploaded</dt><dd><%= @doc.created_at&.to_date&.iso8601 %> by <%= @doc.uploaded_by.presence || "—" %></dd></div>
+  <div><dt class="opacity-60">Source</dt><dd><%= @doc.source_note.presence || "—" %></dd></div>
+  <div><dt class="opacity-60">File</dt><dd><%= @doc.file? ? "#{@doc.mime_type.presence || 'file'} · #{number_to_human_size(@doc.byte_size) if @doc.byte_size}" : "metadata only" %></dd></div>
+  <div class="md:col-span-2"><dt class="opacity-60">Access</dt><dd><%= render "studio/knowledge_docs/access_chips", doc: @doc %></dd></div>
+</dl>
+
+<% if @doc.summary.present? %>
+  <div class="mb-6">
+    <h2 class="font-semibold mb-1">Summary <span class="text-xs opacity-60">(what an "aware" agent may read)</span></h2>
+    <p class="text-sm whitespace-pre-line"><%= @doc.summary %></p>
+  </div>
+<% end %>
+
+<div id="knowledge-triage" class="p-4 border rounded">
+  <h2 class="font-semibold mb-3">File it</h2>
+  <%= form_with url: admin_knowledge_doc_path(@doc), method: :patch, local: true do |form| %>
+    <div class="grid gap-3 md:grid-cols-2">
+      <label class="block text-sm">
+        <span class="block mb-1">Title</span>
+        <%= form.text_field "knowledge_doc[title]", value: @doc.title, 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_doc[path]", value: @doc.path, class: "block w-full border rounded px-2 py-1" %>
+      </label>
+      <label class="block text-sm">
+        <span class="block mb-1">Category</span>
+        <%= form.text_field "knowledge_doc[category]", value: @doc.category, class: "block w-full border rounded px-2 py-1" %>
+      </label>
+      <label class="block text-sm">
+        <span class="block mb-1">Document date</span>
+        <%= form.date_field "knowledge_doc[document_date]", value: @doc.document_date, class: "block w-full border rounded px-2 py-1" %>
+      </label>
+      <label class="block text-sm">
+        <span class="block mb-1">Status</span>
+        <%= form.select "knowledge_doc[status]",
+                        Studio::KnowledgeDoc::STATUSES.map { |s| [s, s] },
+                        { selected: @doc.status }, class: "block w-full border rounded px-2 py-1" %>
+      </label>
+      <% (Array(Studio.knowledge_agents) | @doc.access.keys).each do |agent| %>
+        <label class="block text-sm">
+          <span class="block mb-1">Access — <%= agent %></span>
+          <%= form.select "knowledge_doc[access][#{agent}]",
+                          [["none", ""], ["aware", "aware"], ["full", "full"]],
+                          { selected: @doc.access_for(agent) == "none" ? "" : @doc.access_for(agent) },
+                          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" %>
+      </label>
+    </div>
+    <div class="mt-3">
+      <%= form.submit "Save", class: "px-3 py-1.5 border rounded font-medium" %>
+    </div>
+  <% end %>
+</div>

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

@@ -21,7 +21,8 @@
      through studio/cropper_assets), Web3 (wallet-connect and web3-step-up now
      rendered from the solana-studio gem / on-chain-tx / deposit / the generic
      entry-confirmed celebration, gated by Studio.feature?(:web3) —
-     disabled-but-present-yet-openable when off),
+     disabled-but-present-yet-openable when off, except the two gem-backed ids,
+     which an app without solana-studio lists but cannot open),
      System and status (the reusable card blocks), Templates (the copy-from
      archetypes), and Rewards (level-up + the entry-confirmed seeds bar + the
      Free Entry Earned reward, gated by :leveling).
@@ -53,6 +54,25 @@
   # (studio/modals/_host.html.erb): name, prefixes, partial.
   web3_gem = lookup_context.exists?("wallet_connect", ["solana_studio/modals"], true)
 
+  # web3_gem gates the REGISTRATION below. It must also gate the TRIGGER on the
+  # three gem-backed cards (Connect wallet + the two Sign Wallet cards), or they
+  # stay role=button over a modal id nothing registered: a card that opens an
+  # EMPTY panel. The registration gate cannot prevent that on its own — it is
+  # what stops the missing-template 500, one layer down.
+  #
+  # Both terms are load-bearing, because the two gates answer different
+  # questions and a BASE app can fail either:
+  #   openable: web3_gem  -> with the capability OFF, the section's
+  #     disabled-but-openable preview contract would otherwise keep the card
+  #     clickable (clickable is !(disabled AND NOT openable)).
+  #   disabled: web3_card_off -> with the capability ON but no gem, `disabled`
+  #     alone is false, so the card renders as a NORMAL live card: no badge, no
+  #     aria-disabled, and clickable whatever `openable` says. That is the worse
+  #     of the two, and it is the exact scenario the BASE-app test runs in.
+  # The other six web3 specimens are engine-owned and registered
+  # unconditionally, so they keep the plain capability gate.
+  web3_card_off = !web3_on || !web3_gem
+
   # Auth method-toggle defaults — mirror the app's Studio.auth_method? config;
   # Solana Wallet also needs the web3 capability, so it defaults OFF on an app
   # (like McRitchie Studio) that ships web3 off.
@@ -1077,7 +1097,9 @@
 
   <%# ===================================================================== %>
   <%# 2. WEB3 — the wallet + on-chain modals, in the order a player meets them. %>
-  <%# Gated by :web3; off = disabled-but-present-yet-openable. %>
+  <%# Gated by :web3; off = disabled-but-present-yet-openable. The three
+      gem-backed cards carry a second gate, web3_card_off, because a preview
+      you can open needs something registered to open. %>
   <%# ===================================================================== %>
   <section id="modals-web3" class="space-y-5">
     <div class="space-y-1">
@@ -1094,6 +1116,12 @@
         <code class="font-mono text-2xs">Studio.feature?(:web3)</code>. Web3 is
         <strong><%= web3_on ? "on" : "off" %></strong> here, so these render
         <%= web3_on ? "live." : "greyed and badged — but STILL openable as a preview." %>
+        <% unless web3_gem %>
+          <strong>This app bundles no solana-studio</strong>, so the three cards it
+          backs &mdash; Connect wallet and the two Sign Wallet states &mdash; are
+          listed for reference but <strong>cannot be opened here</strong>. Nothing
+          registers them, so a trigger would open an empty panel.
+        <% end %>
         The cards run in the order a player meets them &mdash; <strong>get a wallet,
         prove it, spend from it</strong>: Connect wallet &rarr; Setup Wallet &rarr;
         the two Sign Wallet states &rarr; Processing &rarr; success or error &rarr;
@@ -1143,7 +1171,7 @@
             reference: %(the Web3 "Connect wallet" picker (solana-studio solana_studio/modals/_wallet_connect, configured by style/modals/_wallet_connect) — the walk's entry: picking a wallet runs a brief connecting state then swaps to the on-chain Processing modal. Open with $store.dsModals.open('wallet-connect')),
             open_expr: "$store.dsModals.open('wallet-connect')",
             glow_when: ds_glow.call("wallet-connect"),
-            disabled: !web3_on, openable: true } do %>
+            disabled: web3_card_off, openable: web3_gem } do %>
         <%# A PICKER: brand tiles with names beside them, which is what this modal
             actually is. Two empty outlines said "form with two inputs" and were
             the least informative sketch in the section — the one card whose
@@ -1209,7 +1237,7 @@
             reference: %(the Web3 "Sign Wallet" card (solana-studio solana_studio/modals/_web3_step_up — the REAL shared partial, not a specimen copy) — shown to an account that holds a self-custody wallet but authenticated this session with a web2 credential. One wallet row, glowing, because it is the only thing to press. Open with $store.dsModals.open('web3-step-up', { provider: 'phantom', providerLabel: 'Phantom', walletHint: '7xKp…JZ2Q' })),
             open_expr: "$store.dsModals.open('web3-step-up', { provider: 'phantom', providerLabel: 'Phantom', walletHint: '7xKp…JZ2Q' })",
             glow_when: ds_glow.call("web3-step-up", provider: true),
-            disabled: !web3_on, openable: true } do %>
+            disabled: web3_card_off, openable: web3_gem } do %>
         <%# A FILLED row: brand tile, the wallet's name, an Installed badge. The
             two step-up thumbnails used to differ by a single border-dashed class
             on a 20px row, which is not a difference anyone can see at thumbnail
@@ -1232,7 +1260,7 @@
             reference: %(the Web3 "Sign Wallet" card with NO remembered brand (solana-studio solana_studio/modals/_web3_step_up) — every wallet linked before a host recorded brands lands here, so it is a live population and not a defensive branch. The row falls back to the picker rather than dead-ending. Open with $store.dsModals.open('web3-step-up', {})),
             open_expr: "$store.dsModals.open('web3-step-up', {})",
             glow_when: ds_glow.call("web3-step-up", provider: false),
-            disabled: !web3_on, openable: true } do %>
+            disabled: web3_card_off, openable: web3_gem } do %>
         <%# An EMPTY slot: dashed outline, no brand tile, a "?" where the wallet's
             name would be. Reads at a glance as "we do not know which wallet",
             which is the whole difference between this card and the one before it. %>

data/db/migrate/20260901000001_create_studio_knowledge_docs.rb

@@ -0,0 +1,49 @@
+# Reference migration for the Studio::KnowledgeDoc model. Like studio_links,
+# each consumer app installs its own copy into db/migrate
+# (`bin/rails studio_engine:install:migrations && bin/rails db:migrate`) so the
+# table is created in the app's database. Do not hand-copy — a hand copy
+# collides with the installed copy on `class CreateStudioKnowledgeDocs`.
+class CreateStudioKnowledgeDocs < ActiveRecord::Migration[7.2]
+  def change
+    create_table :studio_knowledge_docs do |t|
+      t.string :title, null: false
+      # Which business the document belongs to (e.g. "commercial-welding-llc").
+      # One app can host several entities' knowledge; every read is entity-scoped.
+      t.string :entity, null: false
+      # Folder path with no leading/trailing slash ("financials/aging-inventory/2026-08").
+      # Folders are implicit — they exist because a document claims the path —
+      # and the S3 key mirrors it, so the bucket stays human-browsable.
+      t.string :path, null: false, default: ""
+      t.string :category
+      t.string :mime_type
+      # The document's own as-of date (an August aging report dated August),
+      # distinct from created_at (when it was uploaded).
+      t.date :document_date
+      # inbox -> filed -> superseded. Uploads land as inbox for agent triage.
+      t.string :status, null: false, default: "inbox"
+      # Per-agent access map: {"samson" => "full", "dawn" => "aware"}.
+      # "aware" = the agent knows the document exists and gets the safe summary,
+      # not the contents; absent agents default to "none".
+      t.jsonb :access, null: false, default: {}
+      t.jsonb :tags, null: false, default: []
+      # The safe summary — what an "aware" agent may read and repeat.
+      t.text :summary
+      # Provenance: who/where the document came from ("broker email 2026-08-30").
+      t.string :source_note
+      t.string :uploaded_by
+      # Object storage pointer (Studio::S3 logical key); nil for a metadata-only
+      # record. byte_size is captured at attach time for the index view.
+      t.string :s3_key
+      t.bigint :byte_size
+      # Set on the OLD row when a newer document replaces it.
+      t.bigint :superseded_by_id
+
+      t.timestamps
+    end
+
+    add_index :studio_knowledge_docs, [:entity, :status]
+    add_index :studio_knowledge_docs, [:entity, :path]
+    add_index :studio_knowledge_docs, :s3_key, unique: true
+    add_index :studio_knowledge_docs, :superseded_by_id
+  end
+end

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.66.2"
+  VERSION = "0.67.0"
 end

data/lib/studio.rb

@@ -554,6 +554,14 @@ module Studio
   # A trailing slash is added if you leave it off.
   mattr_accessor :s3_key_prefix, default: nil
 
+  # Knowledge layer — the S3-backed document store + /admin/knowledge browser
+  # (Studio::KnowledgeDoc). Routes are opt-in like every route surface.
+  # knowledge_agents is the roster of agent slugs the intake UI offers
+  # per-agent access selects for (e.g. %w[samson dawn] on Industries); the
+  # access map itself accepts any agent slug regardless.
+  mattr_accessor :draw_knowledge_routes, default: false
+  mattr_accessor :knowledge_agents,      default: []
+
   class S3ConfigError < StandardError; end
 
   # Whether to validate the host app's User model at boot. See docs/USER_CONTRACT.md.
@@ -846,6 +854,19 @@ module Studio
              constraints: { token: %r{[^/]+} }
       end
 
+      # Knowledge layer — /admin/knowledge (Studio::KnowledgeDoc): folder/flat
+      # document browser, upload-to-inbox intake, per-agent access map, and
+      # 15-minute presigned downloads. Opt-in (default off) like every route
+      # surface, so no app grows an admin page it never asked for.
+      if Studio.draw_knowledge_routes
+        get   "admin/knowledge",     to: "studio/knowledge_docs#index", as: :admin_knowledge
+        post  "admin/knowledge",     to: "studio/knowledge_docs#create"
+        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",
+              as: :admin_knowledge_doc_download
+      end
+
       # Solana / Phantom wallet sign-in (nonce challenge + signature verify),
       # plus the MOBILE deep-link callback Phantom redirects back to. The
       # callback used to be listed here as app-specific and is not any more —

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.66.2
+  version: 0.67.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -328,6 +328,7 @@ files:
 - app/controllers/studio/email_images_controller.rb
 - app/controllers/studio/emails_controller.rb
 - app/controllers/studio/geo_settings_controller.rb
+- app/controllers/studio/knowledge_docs_controller.rb
 - app/controllers/studio/links_controller.rb
 - app/controllers/studio/local_emails_controller.rb
 - app/controllers/studio/local_reviews_controller.rb
@@ -361,6 +362,7 @@ files:
 - app/models/studio/email_setting.rb
 - app/models/studio/enumeral.rb
 - app/models/studio/geo_setting.rb
+- app/models/studio/knowledge_doc.rb
 - app/models/studio/link.rb
 - app/models/studio/model_page.rb
 - app/models/theme_setting.rb
@@ -436,6 +438,12 @@ files:
 - app/views/studio/emails/show.html.erb
 - app/views/studio/fields/_date_of_birth.html.erb
 - app/views/studio/geo_settings/edit.html.erb
+- app/views/studio/knowledge_docs/_access_chips.html.erb
+- app/views/studio/knowledge_docs/_browser.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/index.html.erb
+- app/views/studio/knowledge_docs/show.html.erb
 - app/views/studio/links/confirm.html.erb
 - app/views/studio/local_emails/index.html.erb
 - app/views/studio/mailers/_layered_banner.html.erb
@@ -544,6 +552,7 @@ files:
 - db/migrate/20260813010000_add_body_cta_footer_to_studio_email_settings.rb
 - 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
 - lib/studio-engine.rb
 - lib/studio.rb
 - lib/studio/cable.rb