janela 0.12.0 → 0.13.0

data/docs/decisions/053-an-agent-reaches-janela-through-tools-the-host-scopes.md

@@ -0,0 +1,187 @@
+---
+Date: 2026-10-02
+Status: Accepted
+Related: ADR 001, ADR 010, ADR 012, ADR 014, ADR 017, ADR 019, ADR 025, ADR 032, ADR 033, ADR 034, ADR 037, ADR 041
+Triggers:
+  - proposing an MCP server, an agent tool or any machine facing surface for Janela
+  - an agent needs to read or arrange a frame without a browser
+  - adding a dependency on an MCP library
+  - deciding whether Janela should detect, register or install anything in a host's own tooling
+  - running a Janela query outside a controller, from a tool, a job or a console
+  - changing what an agent may do to a pane
+Topics: ai, agents, mcp, tools, authorisation, scope, host-integration, frames, dependencies, 1.0
+---
+
+# ADR 053: An Agent Reaches Janela Through Tools the Host Scopes, and Janela Registers None
+
+## Context
+
+Janela dashboards are meant to be composed by agents, and an agent in a
+host application has no way in. Frames and panes are rows (ADR 012), so
+the only route is `Janela::Frame` and `Janela::Pane` written from a
+console. A host that already runs an MCP server writes its own wrappers
+by hand, and a host without one gets nothing. #73 asks for an MCP
+surface, and ADR 010 named it as "one ADR away" and as one of the two
+conditions for shipping Jan.
+
+The issue proposed that Janela detect a host's MCP server and offer to
+install tools into it. Four facts, measured on the demo before this was
+written, change what that should mean.
+
+**Reading a pane outside a controller reads everything.** The refusal in
+ADR 032 lives in `Janela::ApplicationController`, where `policy_scope`
+is asked. `Query#result` underneath takes an optional `on:` relation,
+and without it reads the model's default scope. With two orders in the
+demo, `pane.query.result` returned both statuses, and
+`pane.query.result(on: Order.where(status: "paid"))` returned one. A tool
+that called the first form would show an agent, and so a person, rows
+the host never scoped, with no error. This is the same shape as ADR 034:
+a thing that runs outside a request and has to be told what may be read.
+
+**The host's scope is an answer given at the point of asking.** ADR 019
+found that a decision needing the current user and tenant belongs inside
+a request rather than in a setting, and ADR 032 rejected a global
+`Janela.scope = ->(model, controller)` for it. An MCP call is not a
+request to Janela's controllers. Who is asking arrives through whatever
+authentication the host's own MCP server has, which Janela does not own
+and cannot see.
+
+**A pane row already refuses what it should.** A pane naming a measure or
+model that is not declared is invalid, and says so in words an agent can
+act on: `Measure "nonsense" is not a measure of Order` and `Model
+"no_such_model" is not a janela model`. The tools do not need a
+validation layer of their own.
+
+**Tools can be built from data.** The official Ruby SDK, `mcp` 1.6.1,
+builds a tool from a name, a description, a JSON schema and a block
+(`MCP::Tool.define`), and hands the caller's context to the block as
+`server_context`. Other libraries take the same four things. A tool
+definition is therefore plain data plus a call, and none of it needs to
+live in an MCP library to be written once.
+
+One more fact corrects the issue. #73 describes the install task as "in
+the same spirit as `rails janela:install:skill`". That task does not
+exist. ADR 010 records the skill, the install task and the agent
+definition as not implemented, and `docs/skills/` is absent. This would
+be the first install task Janela has, not the second.
+
+### What was considered
+
+**Janela serves MCP itself**, as an engine endpoint. Rejected. A served
+endpoint needs authentication, a notion of who is calling and a way to
+answer ADR 032's question for them, and Janela has none of the three: its
+controllers are exactly as authenticated as the host's (ADR 010). Adding
+them is the subsystem ADR 001 refused, and getting scope wrong shows one
+tenant's numbers to another.
+
+**Detect the host's MCP server and install into it**, as #73 proposed.
+Rejected for the reason ADR 034 rejected detecting the kind of host: the
+signal does not distinguish anything. A host's MCP setup is a gem, an
+endpoint or a hand-written server, and the one thing Janela can reliably
+know is none of those. It would also be Janela editing a host's tooling,
+which ADR 010 says it never does.
+
+**A `janela:install:mcp` task that writes tool files into the host.**
+Rejected. Once copied the files are the host's, they drift from the
+gem's public API, and the doctor would have to grow a check for each
+release to say so. A host that wants the shape reads it in the guide and
+owns the ten lines.
+
+**A global scope setting**, so the tools need no argument. Rejected on
+ADR 019 and ADR 032, above.
+
+**`mcp` as a dependency of the gem.** Rejected. It is the right library
+today and is not the only one a host may use, so a hard dependency would
+make Janela's choice the host's. It stays out of the gemspec, the way the
+demo's markdown renderer does, and the adapter below is optional.
+
+**Writing and reading in one step.** Rejected as the shipped shape, not
+as an idea. The write tools change records a person arranged, so they are
+off until asked for.
+
+## Decision
+
+**Janela ships its agent tools as plain Ruby that the host builds with a
+scope and registers wherever it likes. Janela registers nothing,
+detects nothing and serves nothing.**
+
+```ruby
+tools = Janela::Tools.new(scope: ->(model) { policy_scope(model) }, write: true)
+
+tools.all                                   # name, description, input_schema, read_only
+tools.call("add_pane", frame_id: 3, model: "orders", measure: "revenue")
+```
+
+**`scope:` is required and has no default.** It is a callable that takes
+a model class and returns a relation: the same answer `policy_scope`
+gives. Leaving it out raises `Janela::Unscoped` when the tools are built,
+not when one is called, which is ADR 032's refusal moved to the place
+this surface begins. Every read the tools make passes the relation it
+returns as `on:`, and frames and panes are read through the same callable
+(`scope.call(Janela::Frame)`). It is an argument and not a setting,
+because it is built where the host knows who is asking, as ADR 034's
+`scope_for` is.
+
+**Read tools first, and writes only when asked for.** The 1.0 set:
+
+| Tool | Does |
+| --- | --- |
+| `describe_vocabulary` | The models, measures, dimensions, renderers and granularities `Janela.definitions` declares, so an agent offers only what can be asked |
+| `list_frames` | Id, name, owner and pane count of the frames the scope returns |
+| `get_frame` | One frame with its panes in position order |
+| `read_pane` | A pane's values, through the host's scope, with `q[...]` filters bounded as ADR 025 bounds them |
+| `add_pane`, `update_pane`, `remove_pane`, `move_pane` | Only with `write: true` |
+
+Inputs are the pane's own attributes and the README's own names. There is
+no agent only vocabulary (ADR 010). A rejected row returns the pane's
+validation messages unchanged. A frame is found or made by the host with
+`Frame.for` (ADR 041) or by an analyst on the engine's pages, so there is
+no `create_frame` in 1.0.
+
+**A tool definition is data, and an adapter is a few lines the host
+owns.** `Janela::Tools#all` carries what any library needs. The guide
+shows the mapping for the official `mcp` SDK, and a host using another
+writes the same few lines. Janela adds no MCP library to its gemspec.
+
+**Snapshots are not in 1.0.** A snapshot persists and publishes, so it
+needs an owner (ADR 033) and a scope the caller has named (ADR 034). That
+is two more decisions an agent should not be making by default, and it
+waits for a host that wants it.
+
+**Jan still does not ship.** ADR 010's second condition, that an MCP
+surface exists, is met by this. Its first reason, that a skill loaded
+agent already does the work, has not been tested, because the skill was
+never built. The skill ships first and teaches these tools. An agent
+definition is revisited after a host has used both, and ADR 010 is not
+superseded here.
+
+## Consequences
+
+- **It ships as 0.13.0, with its own short soak.** This adds public
+  surface, and ADR 037 says anything that changes the surface resets the
+  soak clock in #71. The earliest 1.0 tag moves by the length of that
+  soak. The rule for what 1.0 then contains is set now, before anyone has
+  seen the result: if a real host has exercised the write tools and found
+  nothing wrong, 1.0 ships with them. If no host has used them by the end
+  of the soak, 1.0 ships read only and the write tools wait for 1.1.
+  Freezing four schemas that nobody has tried is what a soak is for
+  avoiding.
+- **The tool names and input schemas join the contract at 1.0**, so the
+  set is small on purpose and every name is a verb and a README noun. A
+  tool added after 1.0 is a minor release. A tool changed is a major one.
+- **A host does the registering.** That is a few lines in the place its
+  MCP server already lives, and the guide says where. A host with no MCP
+  server gets nothing from this, which is the honest answer: Janela does
+  not run servers.
+- **The first test is the measured failure.** A tool built with a scope
+  that returns `Order.none` reads no values, and tools built without a
+  scope raise. Both belong in the suite before the code.
+- **No doctor check.** Construction raises, so there is nothing for the
+  doctor to see that the raise does not say (ADR 035).
+- **The pane `order` option (#75) reaches agents for free**, since the
+  write tools take a pane's attributes. It does not change this ADR.
+- **What would change this decision:** two hosts writing the same
+  adapter by hand, which would earn a shipped one for that library; or a
+  host with no MCP server that needs one, which would be the day Janela
+  is asked to run something and has to answer ADR 032's question for
+  itself.

data/docs/decisions/INDEX.md

@@ -23,26 +23,26 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | **Vision, scope, forkability** | 001, 010, 012, 037, 052 |
 | **Open-source & host-decoupling** | 001, 022, 036, 041, 052 |
 | **DSL & query layer** | 002, 006, 007, 020, 025, 038, 044, 049, 051 |
-| **Dependencies** | 002, 003, 004, 006, 017, 025 |
-| **Authorisation** | 002, 003, 004, 009, 017, 019, 022, 032, 033, 034, 035, 039, 040, 048 |
+| **Dependencies** | 002, 003, 004, 006, 017, 025, 053 |
+| **Authorisation** | 002, 003, 004, 009, 017, 019, 022, 032, 033, 034, 035, 039, 040, 048, 053 |
 | **Performance & storage** | 007, 017, 025, 048, 051 |
 | **Ordering & formatting** | 007, 020, 038 |
 | **Cross-filtering & Hotwire** | 003, 004, 005, 008, 024, 025, 040, 043, 044, 045, 048, 049 |
 | **Layouts & views** | 011, 012, 016, 018, 020, 027, 039, 047, 050 |
 | **CSS & styling** | 016, 018, 023, 026, 027, 036, 042, 046, 047, 050 |
-| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030, 033, 039, 040, 041, 043, 044, 047, 048, 050, 051 |
+| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030, 033, 039, 040, 041, 043, 044, 047, 048, 050, 051, 053 |
 | **Naming rule** | 014, 023, 036 |
 | **JavaScript delivery & charts** | 004, 006, 026, 042, 046, 047 |
 | **Time dimensions** | 006, 025, 045 |
 | **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025, 040, 041, 045, 047, 050, 051 |
 | **Snapshots & publishing** | 009, 020, 028, 033, 034, 051 |
-| **AI agents & guidance** | 010, 015, 021 |
+| **AI agents & guidance** | 010, 015, 021, 053 |
 | **The doctor & checks** | 021, 025, 032, 033, 035 |
 | **Releases & upgrades** | 015, 021, 032, 034, 035, 036, 037, 042, 052 |
 | **Accessibility & keyboard** | 024, 042, 045, 046, 049 |
 | **Security** | 003, 025, 028, 031, 032, 034, 035, 044, 052 |
 | **Testing** | 003 |
-| **Roadmap & planning** | 001, 037, 045, 046, 052 |
+| **Roadmap & planning** | 001, 037, 045, 046, 052, 053 |
 
 ## Chronological
 
@@ -100,7 +100,8 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 050 | A Single Value's Prominence Is One of Three Steps, and Unset Changes Nothing | 2026-09-30 | Accepted |
 | 051 | A Table Can Carry Companion Columns, and a Fact Is Shown Only When It Is Shared | 2026-09-30 | Accepted |
 | 052 | Two People Cut Releases, Reports Go Private, and Support Is Best Effort | 2026-09-30 | Accepted |
+| 053 | An Agent Reaches Janela Through Tools the Host Scopes, and Janela Registers None | 2026-10-02 | Accepted |
 
 ## Next number
 
-Next ADR: 053
+Next ADR: 054

data/docs/multi-tenancy.md

@@ -36,9 +36,10 @@ without asking first:
 - A snapshot, read through `policy_scope(Janela::Snapshot)`.
 
 A pane rendered inline in your own page runs in your request, so the
-same scope applies there as in the engine's controllers. Nothing is
-calculated in a background context where the current tenant would have
-gone missing.
+same scope applies there as in the engine's controllers, so a live pane
+is never calculated where the current tenant would have gone missing. A
+scheduled snapshot is the one thing that runs in the background, and it
+is told whose it is (see Snapshots below).
 
 ## With Pundit
 
@@ -69,6 +70,23 @@ class ApplicationController < ActionController::Base
 end
 ```
 
+A snapshot is read through its own scope as well. Without a policy for it
+Pundit raises, and a hand rolled `policy_scope` that does not name it
+would hand every tenant every snapshot, so write the second one too:
+
+```ruby
+# app/policies/janela/snapshot_policy.rb
+module Janela
+  class SnapshotPolicy < ApplicationPolicy
+    class Scope < ApplicationPolicy::Scope
+      def resolve
+        scope.where(owner: Current.account)
+      end
+    end
+  end
+end
+```
+
 Your own models keep the policies they already have. Janela calls
 `policy_scope(Order)` and gets whatever `OrderPolicy::Scope` returns.
 
@@ -85,7 +103,7 @@ class ApplicationController < ActionController::Base
   private
     def policy_scope(model)
       case model.name
-      when "Janela::Frame" then model.where(owner: ActsAsTenant.current_tenant)
+      when "Janela::Frame", "Janela::Snapshot" then model.where(owner: ActsAsTenant.current_tenant)
       else model.all # acts_as_tenant has already scoped your own models
       end
     end

data/docs/roadmap.md

@@ -8,7 +8,7 @@ Topics: roadmap, releases, scope, planning
 
 <svg viewBox="0 0 680 360" width="100%" role="img" aria-labelledby="vista-title vista-desc" class="vista-art" style="display: block; margin: 1.75rem 0; border-radius: 10px;">
   <title id="vista-title">Vista</title>
-  <desc id="vista-desc">Sea and sky with a horizon across them. The near water is dark, because every issue in 1.0 has shipped, and three lights sit far off at the horizon for the work still in sight past it. A low sun rises and sets on the horizon as the pointer moves up and down, and never climbs higher: the sky above is empty, because what is not coming is not in view.</desc>
+  <desc id="vista-desc">Sea and sky with a horizon across them. The near water is dark, because every issue in 1.0 has shipped, and five lights sit far off at the horizon for the work still in sight past it. A low sun rises and sets on the horizon as the pointer moves up and down, and never climbs higher: the sky above is empty, because what is not coming is not in view.</desc>
 
   <style>
     .vista-art .v-far { transform: translate3d(calc(var(--vitral-shift-x, 0) * 13px), calc(var(--vitral-shift-y, 0) * 7px), 0); transition: transform .45s cubic-bezier(.2,.7,.3,1); }
@@ -89,6 +89,10 @@ Topics: roadmap, releases, scope, planning
       <circle cx="322" cy="201" r="1.5" fill="#FFF3DC" opacity="0.55"/>
       <circle cx="540" cy="202.5" r="8" fill="url(#vLamp)" opacity="0.2"/>
       <circle cx="540" cy="202.5" r="1.6" fill="#FFF3DC" opacity="0.55"/>
+      <circle cx="112" cy="201.5" r="8" fill="url(#vLamp)" opacity="0.2"/>
+      <circle cx="112" cy="201.5" r="1.5" fill="#FFF3DC" opacity="0.55"/>
+      <circle cx="430" cy="202" r="8" fill="url(#vLamp)" opacity="0.2"/>
+      <circle cx="430" cy="202" r="1.6" fill="#FFF3DC" opacity="0.55"/>
     </g>
 
     <g class="v-glint" stroke="#FFE2A6" stroke-linecap="round">
@@ -109,7 +113,7 @@ Topics: roadmap, releases, scope, planning
 Janela is alpha. It works, it is tested against a real Rails application
 in a real browser, and its public surface has changed in three of the
 last four releases. This page says what has to be true before that stops,
-what is in the next release, and what is deliberately not coming. The
+what is left before 1.0, and what is deliberately not coming. The
 reasoning behind it is ADR 037.
 
 ## What 1.0 means
@@ -128,11 +132,10 @@ change in any release, and every change of that kind carries an entry in
 `UPGRADING.md`.
 
 **A pane can be read.** Janela draws tables, bars, lines, doughnuts and
-pies. A table row still cannot carry context beside its label, a single
-number has no way to say how prominent it is, and a chart takes whatever
-height its width gives it whether or not that suits the page. Those are
-not extra features. They are the 5% not finished, and most of them were
-found by people installing the gem rather than reading it.
+pies. A table row can carry context beside its label, a single number says
+how prominent it is, and a chart has a height that suits the page. Those
+were not extra features. They were the 5% not finished, and most of them
+were found by people installing the gem rather than reading it.
 
 **The doctor can be trusted.** `rails janela:doctor` checks an
 installation for the mistakes that produce a dashboard showing numbers
@@ -144,17 +147,20 @@ working is a check nobody should rely on.
 
 The near ground is clear. Every issue that was in 1.0 has shipped: chart
 height, a ratio measure, single value prominence, companion columns, Sprockets
-hosts, and how the project is run. What 1.0 waits on now is time with real
-installs, since much of that surface was added in the last days and has only
-met this repository. When nothing surprising comes back, the surface is
-frozen and 1.0 is tagged.
+hosts, and how the project is run. 0.13.0 is out, and adds tools an agent
+can use (ADR 053). What 1.0 waits on now is a week of real installs ([#71](https://github.com/retail-tasker/janela/issues/71)),
+since much of that surface was added in the last days and has only met this
+repository. When nothing surprising comes back, the surface is frozen and 1.0
+is tagged. The agent tools are the one new piece of surface: the read tools are
+frozen at 1.0, and the write tools are frozen with them only if a real host has
+used them by the end of that week. Otherwise they wait for 1.1.
 
 Progress is tracked on the
 [1.0 milestone](https://github.com/retail-tasker/janela/milestone/2).
 
 ## Horizonte
 
-The three lights far off at the horizon. Wanted, not blocking a stable
+The lights far off at the horizon. Wanted, not blocking a stable
 release, and being on this list is not a refusal.
 
 - **Drilling down on time panes** ([#65](https://github.com/retail-tasker/janela/issues/65)).
@@ -162,6 +168,12 @@ release, and being on this list is not a refusal.
   that pane itself to the weeks within it is a different gesture, with
   its own questions about getting back out and about the URL, and it
   needs a decision record before any code.
+- **Telling a frame to refresh** ([#68](https://github.com/retail-tasker/janela/issues/68)).
+  One action a host's own timer or push can call, and no timer or stream of
+  Janela's own (ADR 048). Additive, so it can land after 1.0.
+- **Vitral's own palette** ([#67](https://github.com/retail-tasker/janela/issues/67)).
+  The optional theme setting its own series colours instead of Janela's
+  neutral ones.
 - **A command palette for the demo** ([#41](https://github.com/retail-tasker/janela/issues/41)).
   The demo site, not the gem.
 - **A scroll drift on the gallery page** ([#45](https://github.com/retail-tasker/janela/issues/45)).
@@ -178,7 +190,9 @@ run does it better.
 Natural-language query. A separate data warehouse. A row-level-security
 subsystem, because your application already has Pundit or CanCanCan and
 Janela reads through it. A refresh-scheduling interface, because you
-already have a scheduler and snapshots are an ActiveJob. An embedding
+already have a scheduler and snapshots are an ActiveJob (a way to tell a
+frame to refresh, which your scheduler can call, is
+[#68](https://github.com/retail-tasker/janela/issues/68)). An embedding
 SDK. A mobile application. Print and paginated reports. A drag-and-drop
 visual dashboard designer, though frames and panes are database records,
 so an application can build its own editor on top of them.

data/docs/theming.md

@@ -82,6 +82,7 @@ the names a theme spends most of its time on.
 | `janela-legend` | `<table>` | its legend, one row of swatch, button and value per slice |
 | `janela-swatch` | `<span>` | the colour beside a legend label |
 | `janela-empty` | `<p>` | a pane whose query returned nothing |
+| `janela-muted` | `<p>` | the note under a ring that could not be drawn and became a table (ADR 046) |
 | `janela-error` | `<p>` | a pane that could not be read |
 | `janela-content` | `<div>` | a stored pane holding words or a host partial rather than a query (ADR 039) |
 | `janela-content-heading` | `<h2>` | a text pane's heading |
@@ -121,8 +122,9 @@ here rather than being left for each host to write.
 `janela.css` also styles Janela's own pages, the frame index and the
 editing forms: `janela-page`, `janela-card`, `janela-button`,
 `janela-form`, `janela-field`, `janela-list`, `janela-crumb`,
-`janela-flash` and the rest. They are scoped under `janela-page`, which
-only the engine's own layout sets, so they cannot touch your pages.
+`janela-flash` and the rest. They are plain class names that the engine's
+own pages use, not scoped to `janela-page`, so they affect your pages
+only if your own markup uses the same names. Avoid them.
 
 **Those names may change in any release.** They are the engine's own
 chrome rather than an interface. Restyle them if you want Janela's
@@ -140,8 +142,8 @@ Janela.theme = "midnight"
 
 The name is resolved against your own asset paths, so `midnight.css` in
 your application works exactly as the gem's own `vitral` does. A name
-that resolves to nothing raises rather than quietly rendering an
-unthemed page.
+that your asset pipeline cannot find raises when the page renders,
+rather than quietly rendering an unthemed one.
 
 That setting links the theme into **Janela's own pages**. Your pages load
 whatever your layout says, so if you want the same look around a pane you

data/lib/janela/doctor.rb

@@ -9,7 +9,7 @@ module Janela
 
     # Run in this order, and each one names the finding it produces: a host
     # silences a check by that name (ADR 021).
-    CHECKS = %i[stale_identifiers unmounted_engine unmigrated_tables unregistered_controllers
+    CHECKS = %i[stale_identifiers unmounted_engine unmigrated_tables unmigrated_columns unregistered_controllers
                 through_dimensions_without_an_allowlist unscoped_reads frames_nobody_will_own
                 snapshots_nobody_will_see unauthenticated_endpoints
                 hardcoded_disallowed_predicates].freeze
@@ -21,10 +21,22 @@ module Janela
       "janela/dashboard_controller" => "janela/frame_controller",
       "janela/dashboard_controller.js" => "janela/frame_controller.js",
       "Janela::DashboardHelper" => "Janela::FramesHelper",
-      "Janela::PanesController" => "Janela::QueriesController",
       "Janela::SnapshotPanesController" => "Janela::SnapshotQueriesController"
     }.freeze
 
+    # A name that was renamed away and later given back to something else, so
+    # finding it cannot say which one the host means. An error would send a
+    # host patching the stored-pane form to a controller without pane_params,
+    # and the extra param would silently stop saving (#74). A warning says what
+    # the name means now and leaves the judgement to the host.
+    REUSED = {
+      "Janela::PanesController" =>
+        "This name was the controller that renders a pane's query until 0.7, when it became " \
+        "Janela::QueriesController. Since 0.12 it is the stored-pane form's controller again, " \
+        "and it owns pane_params. A patch to the form belongs here; a patch to how a query " \
+        "renders belongs on Janela::QueriesController."
+    }.freeze
+
     SEARCHED = %w[app config lib].freeze
     READABLE = %w[.rb .erb .js .erb.html .html.erb .haml .slim .yml].freeze
 
@@ -79,14 +91,26 @@ module Janela
       end
 
       def stale_identifiers
-        RENAMED.filter_map do |old, new|
-          files = source_files.select { |file| file.read.include?(old) }
-          next if files.empty?
+        renamed = RENAMED.filter_map do |old, new|
+          next unless (files = files_naming(old)).any?
 
-          Finding.new(severity: :error,
-            summary: "#{old} is now #{new}",
-            detail: files.map { |file| "  #{file.relative_path_from(@root)}" }.join("\n"))
+          Finding.new(severity: :error, summary: "#{old} is now #{new}", detail: listed(files))
         end
+        reused = REUSED.filter_map do |name, meaning|
+          next unless (files = files_naming(name)).any?
+
+          Finding.new(severity: :warning, summary: "#{name} has meant two things",
+            detail: "  #{meaning}\n#{listed(files)}")
+        end
+        renamed + reused
+      end
+
+      def files_naming(identifier)
+        source_files.select { |file| file.read.include?(identifier) }
+      end
+
+      def listed(files)
+        files.map { |file| "  #{file.relative_path_from(@root)}" }.join("\n")
       end
 
       def unmounted_engine
@@ -116,6 +140,40 @@ module Janela
         nil # no database to ask yet
       end
 
+      # The columns a release added to a table that already existed. A host that
+      # upgraded and did not run the migration has the table, so the check above
+      # passes, and meets an error the first time a pane form or a stored pane
+      # reads the column. Only the tables that exist are asked: a missing table
+      # is that check's finding, and listing every column of it here would say
+      # the same thing twice.
+      ADDED_COLUMNS = {
+        "Janela::Frame" => %w[key default_model default_where],
+        "Janela::Pane" => %w[kind heading body link partial height prominence companions],
+        "Janela::Snapshot" => %w[owner_type owner_id]
+      }.freeze
+
+      def unmigrated_columns
+        return unless engine_mounted?
+
+        absent = ADDED_COLUMNS.filter_map do |model_name, columns|
+          model = model_name.constantize
+          next unless model.table_exists?
+
+          missing = columns - model.column_names
+          "#{model.table_name} (#{missing.join(', ')})" if missing.any?
+        end
+        return if absent.empty?
+
+        Finding.new(severity: :error,
+          summary: "#{absent.to_sentence} #{absent.one? ? 'is' : 'are'} missing columns a release added",
+          detail: "  The tables exist, so the migrations from an earlier release ran, but a later one has not.\n" \
+                  "  Run:\n" \
+                  "    bin/rails janela:install:migrations\n" \
+                  "    bin/rails db:migrate")
+      rescue StandardError
+        nil # no database to ask yet
+      end
+
       def engine_mounted?
         Rails.application.routes.routes.any? { |route| route.app.respond_to?(:app) && route.app.app == Janela::Engine }
       end