studio-engine 0.66.1 → 0.67.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50dd61991cf5d6c07313f0f8b3cff808d8207e866052d3d138bf804414e6157e
-  data.tar.gz: f7e06ec09e8c833f4d0dc7334d5079ad82377763a81284c21c638f4cb8b02a9b
+  metadata.gz: 3ffd4e2260ecf5e4ed81cbe17b45001ac14b3bcbf576b4fd79b506bfa2fff6dc
+  data.tar.gz: d7f03282009eeb8f914637df864769fb5846808d4ccc270a1285c04564b18418
 SHA512:
-  metadata.gz: d50292a80537c03f7aa76c1dbfece07b2f21b6abb5d497bf412767463862b1030137b0ad13f9f7ac1cac412401d246dbdcc7a73045bcafca767c1375622252fd
-  data.tar.gz: 76983256a17c0cdcd0cb479a650a2f374a312b13b6d940117fd65783eb402e347eb8b6076daba41f535020f5e108e4b831d6743d1a0eb706da25d8f925e92209
+  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/Gemfile

@@ -30,3 +30,28 @@ group :development, :test do
   # test fixture. Not a runtime dependency — consuming apps bring their own server.
   gem "puma", ">= 6.0"
 end
+
+# solana-studio backs the style guide's THREE web3 specimens (Connect wallet and
+# the two Sign Wallet cards). Those partials used to live here, in
+# app/views/studio/modals; the two-template split moved them to the gem —
+# BASE is studio-engine + mcritchie-studio, WEB3 ADD is solana-studio +
+# turf-monster — because, as the call was made, "the real op sec vector is
+# managing sessions safely. Anything wallet based should be in the app."
+#
+# DEVELOPMENT AND TEST ONLY, and deliberately NOT a gemspec runtime dependency.
+# Declaring it there would push a Solana stack onto every BASE consumer
+# (acquisition-studio, mcritchie-industries, moms-app mount this engine and
+# bundle no solana-studio), which is precisely the coupling the split removed.
+# It is here so the DUMMY app can resolve the gem's partials and the style guide
+# renders the real shipped cards rather than a fork of them.
+#
+# There is no dependency cycle: solana-studio's GEMSPEC declares only ed25519.
+# It lists studio-engine in its own Gemfile, dev-only, which Bundler never reads
+# when solana-studio is consumed as a gem.
+#
+# 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.
+group :development, :test do
+  gem "solana-studio", ">= 0.5.3"
+end

data/README.md

@@ -238,30 +238,28 @@ the block:
 <% end %>
 ```
 
-**Connect Wallet — `studio/modals/wallet_connect`.** The reown-style wallet
-picker, engine-owned so the apps stop each keeping a copy. Register it like any
-other modal and configure it with locals:
-
-```erb
-<template x-if="$store.modals.current().id === 'wallet-connect'">
-  <%= render "studio/modals/wallet_connect" %>
-</template>
-```
-
-Locals: `store` (default `"modals"`), `connect_fn` (the window function that
-connects AND verifies, default `"solanaConnectAndVerify"`), `title`, `slot` /
-`slot_locals` (a partial rendered before the wallet rows — an app's legal-age
-attestation goes here), and `extra_data` (a JS fragment merged into the
-component's `x-data`).
-
-App behaviour arrives as optional **hook methods** defined in `extra_data`, each
-called only when present: `onInit`, `canPick` (falsy aborts a pick or a deep
-link), `verifyArgs` (merged into the connect options), `onConnected(result)`,
-`onDeepLink`, `onBack`. An app that needs none passes no `extra_data`.
-
-The slot is a **named local, not a block** — `block_given?` is always true inside
-a compiled Rails partial, so a block-shaped slot yields the captured page body
-into the card whenever no block is passed.
+**Wallet modals moved to `solana-studio`.** The Connect Wallet picker, the Web3
+step-up card and the Phantom deep link used to ship here as
+`studio/modals/wallet_connect`, `studio/modals/web3_step_up` and
+`studio/solana/phantom_deeplink`. They now live in the **solana-studio** gem as
+`solana_studio/modals/wallet_connect`, `solana_studio/modals/web3_step_up` and
+`solana_studio/phantom_deeplink`; render them from those paths and read that
+gem's README for their locals and hooks.
+
+This is the two-template split: **BASE** is studio-engine + mcritchie-studio,
+**WEB3 ADD** is solana-studio + turf-monster. The engine has no business
+shipping wallet UI — as the call was made, *"the real op sec vector is managing
+sessions safely. Anything wallet based should be in the app."*
+
+What the engine **keeps** is the SESSION half of Solana sign-in:
+`SolanaSessionsController`, `Solana::SessionAuth`, the `/auth/solana/nonce` and
+`/auth/solana/verify` routes, the `solana_sessions/phantom_callback` view, and
+`Studio.wallet_sign_in_statement` — the single source for the signed statement,
+which the gem's deep link reads so the two cannot drift.
+
+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.
 
 **Page-scoped hosts — `studio/modals/scoped_host`.** When a page must bring its
 own modals (because not every consuming app renders a shared host, and the ones

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/solana_sessions/phantom_callback.html.erb

@@ -313,11 +313,12 @@
       dbg('Verify result', JSON.stringify(result));
       if (result.success) {
         cleanup();
-        // Guarded, matching studio/modals/_wallet_connect two files over. An app
-        // that does not define this hook would otherwise throw HERE — after a
-        // successful verify, with the session already set — so the user is
-        // signed in and the page dies before redirecting. The engine cannot
-        // require a hook it does not ship.
+        // Guarded, matching solana-studio's wallet_connect picker (the partial
+        // that used to sit two files over, before the two-template split moved
+        // the wallet UI to the gem). An app that does not define this hook would
+        // otherwise throw HERE — after a successful verify, with the session
+        // already set — so the user is signed in and the page dies before
+        // redirecting. The engine cannot require a hook it does not ship.
         if (typeof window.handleSolanaVerifySuccess === 'function') window.handleSolanaVerifySuccess(result);
         dbg('OK', 'Login success! Redirecting...');
         window.location.href = result.redirect || '/';

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 %>