janela 0.2.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f1be37d3c8dc019195214b51f66d263d13032c3f12e44861620fd2d4f1cbe88
-  data.tar.gz: be62c3edcf0f95b897c22a7b348b76168398ee6f3c801230236a3195bda9aae6
+  metadata.gz: 86e2bcbf47fdcf475b8e34b2b1897d308a6c9f478e7b3f0903979cd3fa6bb8e2
+  data.tar.gz: 9116c50f2f6e92a69489827acf9e9d580954c21bbe068887c3605b96d0531019
 SHA512:
-  metadata.gz: 63ef09cab8969ea61002ac8273304222ef40d3d11cc5d5470eecab7a26ef57d84186afb44b58b6bcbeb25a336ae16e91fbc45289199a2163ed3a203bef739ff8
-  data.tar.gz: 05462c455475cadb4dc633e76ea3181eeba0d169c9f82090a715a39afb375b92adebba3ca4de4db9e41c03d6a3dd53a641017ee5605e3c90280c18ab3c5dba1a
+  metadata.gz: a132498d5553317cd888139ba00559b5c7844c3878bdfe4c0c595783e14e3e4a082ec6fbe0a844d9f07a985a586daf4a4104164ff9dd452ed8ddf4390bdfe630
+  data.tar.gz: 5f35f6d28fe84c469e3502f97f8c0ec13b7e1c703f04c5aa21360ef7ad6e14b4cc9c8e8d174e5ac1af9207adcc221d3ed430e2851059ef41f08eb5833637712b

data/CHANGELOG.md

@@ -7,6 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.1] - 2026-09-15
+
+Fixes found by dogfooding 0.2.0 in a second application. 0.2.0 is unusable in any host whose layout contains a route helper, which is most of them.
+
+### Fixed
+
+- Panes rendered in the host's application layout, so any route helper in it raised `NameError` inside the isolated engine and every pane 500'd. A pane in a Turbo Frame now carries no layout; opened directly it uses Janela's own minimal layout (ADR 011, #19).
+- `average:` or `sum:` over a boolean column returned `true` instead of a ratio, because ActiveRecord casts an aggregate back through the column's type. Declaring one now raises and points at `dimension` instead (#20).
+- A group whose dimension is null rendered as a blank label and filtered on an empty string. It is now labelled `(none)` and toggles Ransack's null predicate (#21).
+- The README claimed time buckets follow `Time.zone`; on SQLite they are UTC, which silently shifts daily buckets by the host's offset (#22).
+
+### Changed
+
+- A request for a model, measure, dimension or stored pane that does not exist is a 404; a renderer, granularity, limit or filter the request may not use is a 400. The response is a plain sentence, inside the requesting Turbo Frame when there is one, and the detail goes to the log instead of the client. `Janela::NotFound` and `Janela::BadRequest` subclass `Janela::Error`.
+
 ## [0.2.0] - 2026-09-15
 
 Breaking. Renames and a new URL scheme while the only installation is the author's own (ADR 005).
@@ -47,5 +62,6 @@ First alpha, installed from GitHub for testing in a single host application.
 - Only models that declare a `janela` block are addressable over HTTP.
 - ADRs 001 to 004 in `docs/decisions/`, shipped inside the gem.
 
+[0.2.1]: https://github.com/retail-tasker/janela/releases/tag/v0.2.1
 [0.2.0]: https://github.com/retail-tasker/janela/releases/tag/v0.2.0
 [0.1.0]: https://github.com/retail-tasker/janela/releases/tag/v0.1.0

data/README.md

@@ -84,7 +84,7 @@ class Order < ApplicationRecord
 end
 ```
 
-A dimension with a `granularity` is a time dimension. Groupdate buckets it (`hour`, `day`, `week`, `month`, `quarter`, `year`), fills empty buckets with zero, and uses your app's `Time.zone` and week start.
+A dimension with a `granularity` is a time dimension. Groupdate buckets it (`hour`, `day`, `week`, `month`, `quarter`, `year`), fills empty buckets with zero, and uses your app's `Time.zone` and week start. **On SQLite, buckets are UTC**, because SQLite cannot convert time zones: with a non-UTC `Time.zone` a daily bucket is shifted by your offset, and an early-morning row lands in the previous day. Coarser granularities blunt the shift without removing it. If you need local-day buckets on SQLite, store a local date column and use it as a plain dimension.
 
 Then query them:
 
@@ -135,7 +135,7 @@ Compose panes on any page. Each pane is a Turbo Frame; clicking a value in one r
 
 A pane with no `by:` is the measure's single total, the KPI tile. `limit: 10` keeps the top ten rows or bars. `as:` is `:table` by default, `:bar` for a Chart.js bar chart, or `:line`, which suits a time dimension: `janela_pane Order, :revenue, by: :placed_on, as: :line, granularity: :week`. A chart fills its container's width at Chart.js's default aspect ratio, so wrap it in an element with the width you want. Clicking a bar does exactly what clicking a table value does.
 
-The dashboard's filters live in the page URL as the same `q[...]` parameters, so a reload keeps them and a filtered dashboard is a link you can send: `/reports/orders?q[status_eq]=paid` renders filtered before any JavaScript runs. A pane ignores filters on its own dimension, so clicking a value re-scopes the rest of the dashboard rather than collapsing the pane you clicked. Time panes re-scope with the others but are not click sources yet; drill-down is the next decision. The selected value is marked `aria-pressed="true"` on tables and drawn solid against faded siblings on charts, so it can be styled and read. A pane with no matching rows renders a `.janela-empty` paragraph. Only models that declare a `janela` block can be requested over HTTP.
+The dashboard's filters live in the page URL as the same `q[...]` parameters, so a reload keeps them and a filtered dashboard is a link you can send: `/reports/orders?q[status_eq]=paid` renders filtered before any JavaScript runs. A pane ignores filters on its own dimension, so clicking a value re-scopes the rest of the dashboard rather than collapsing the pane you clicked. Time panes re-scope with the others but are not click sources yet; drill-down is the next decision. The selected value is marked `aria-pressed="true"` on tables and drawn solid against faded siblings on charts, so it can be styled and read. A pane with no matching rows renders a `.janela-empty` paragraph. A group whose dimension is null is labelled `(none)` and filters with Ransack's null predicate rather than an empty string. Only models that declare a `janela` block can be requested over HTTP.
 
 ### Pane URLs
 
@@ -175,6 +175,8 @@ Render a stored pane the same way you render a live one:
 <%= janela_snapshot_pane @snapshot, Order, :revenue, by: :status, as: :bar %>
 ```
 
+Panes render in Janela's own minimal layout when opened directly, so a shared pane link shows its numbers but no host styling and no charts; set `Janela::ApplicationController.layout "application"` in an initializer to use your own layout, which must not call a bare host route helper (inside an engine those need a `main_app.` prefix). Inside a dashboard, panes are Turbo Frames and carry no layout at all.
+
 Stored panes are static by nature: no filter buttons, charts ignore clicks, and the URL says *as of*: `/dashboards/snapshots/42/orders/revenue/status`. Request filters are ignored because the snapshot's were fixed when it was taken.
 
 `Janela::SnapshotJob.perform_later(name:, panes: [{ "model" => "orders", "measure" => "revenue", "by" => "status" }])` takes one from serialisable arguments so you can schedule it with whatever runs your jobs. The job uses each model's default scope; if you scope by tenant, write your own job around `Snapshot.take` and pass `on:`.
@@ -212,7 +214,7 @@ Deliberately out of scope: report designer UI, natural-language query, a separat
 
 ## Status
 
-**v0.2.0 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering, bar and line charts, pane URLs, shareable dashboard URLs and snapshots work and are covered by unit and real-browser tests. Not yet built: drill-down on time panes, other chart types. Open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
+**v0.2.1 alpha.** The measures/dimensions DSL, time dimensions, cross-filtering, bar and line charts, pane URLs, shareable dashboard URLs and snapshots work and are covered by unit and real-browser tests. Not yet built: drill-down on time panes, other chart types. Open work is in [GitHub Issues](https://github.com/retail-tasker/janela/issues).
 
 ## Development
 

data/app/assets/javascripts/janela/chart_controller.js

@@ -8,7 +8,7 @@ Chart.register(...registerables)
 // the difference. Turbo replaces the frame on every cross-filter, so the chart
 // is destroyed on disconnect and rebuilt on connect.
 export default class extends Controller {
-  static values = { type: String, labels: Array, values: Array, key: String, title: String, selected: String }
+  static values = { type: String, labels: Array, values: Array, filters: Object, title: String, selected: String }
 
   connect() {
     this.chart = new Chart(this.element, {
@@ -27,9 +27,10 @@ export default class extends Controller {
         scales: { y: { beginAtZero: true } },
         plugins: { legend: { display: false } },
         onClick: (_event, elements) => {
-          if (!this.keyValue || elements.length === 0) return
-          const value = this.labelsValue[elements[0].index]
-          this.dispatch("toggle", { detail: { key: this.keyValue, value } })
+          if (elements.length === 0) return
+          const label = this.labelsValue[elements[0].index]
+          const [key, value] = this.filtersValue[String(label)] || []
+          if (key) this.dispatch("toggle", { detail: { key, value } })
         }
       }
     })

data/app/controllers/janela/application_controller.rb

@@ -1,5 +1,13 @@
 module Janela
   class ApplicationController < Janela.parent_controller.constantize
+    # A frame request needs no layout, since Turbo keeps only the matching
+    # frame. A direct request gets Janela's own minimal layout, because a host
+    # layout's route helpers cannot resolve inside an isolated engine (ADR 011).
+    layout -> { turbo_frame_request? ? false : "janela/application" }
+
+    rescue_from Janela::NotFound, with: :janela_not_found
+    rescue_from Janela::BadRequest, with: :janela_bad_request
+
     private
       # Pundit defines policy_scope on the host's ApplicationController, which
       # this inherits from, so authorisation applies without Janela depending
@@ -7,5 +15,24 @@ module Janela
       def janela_scope(model)
         respond_to?(:policy_scope, true) ? policy_scope(model) : model.all
       end
+
+      def janela_not_found(error)
+        janela_error(error, :not_found, "There is no such pane.")
+      end
+
+      def janela_bad_request(error)
+        janela_error(error, :bad_request, "That request is not allowed on this pane.")
+      end
+
+      # The detail names models and filter keys, so it goes to the log; the
+      # client sees a plain sentence. A Turbo Frame request gets its frame
+      # back so the dashboard shows the sentence where the pane would be.
+      def janela_error(error, status, message)
+        logger.warn("Janela: #{error.message}")
+        body = view_context.tag.p(message, class: "janela-pane janela-error")
+        frame = request.headers["Turbo-Frame"]
+        body = view_context.turbo_frame_tag(frame) { body } if frame.present?
+        render html: body, status: status, layout: frame.blank?
+      end
   end
 end

data/app/models/janela/pane.rb

@@ -25,7 +25,7 @@ module Janela
       @filters = filters
       @snapshot = snapshot
 
-      raise Error, "unknown pane renderer #{renderer.inspect}" unless RENDERERS.include?(@renderer)
+      raise BadRequest, "unknown pane renderer #{renderer.inspect}" unless RENDERERS.include?(@renderer)
       @granularity = Dimension.granularity!(granularity) if granularity.present?
       @limit = definition.limit!(limit) if limit.present?
     end
@@ -88,19 +88,38 @@ module Janela
       definition.query(measure, by: dimension, where: applicable_filters, on: on, granularity: granularity, limit: limit)
     end
 
-    def filter_key
-      "#{ransack_name}_eq" if clickable?
+    # The Ransack key and value a click on this label should toggle. A null
+    # group filters with the null predicate, not an empty string (ADR 009 has
+    # no say here; see issue #21).
+    def filter_params(label)
+      return [ nil, nil ] unless clickable?
+      return [ "#{ransack_name}_null", "1" ] if label.to_s == Dimension::NONE
+
+      [ "#{ransack_name}_eq", label.to_s ]
+    end
+
+    # Every label in this pane paired with the filter it toggles, for a chart
+    # to look up by label when a bar is clicked.
+    def filters_for(labels)
+      return {} unless clickable?
+
+      labels.to_h { |label| [ label.to_s, filter_params(label) ] }
     end
 
     # The filter on this pane's own dimension is not applied to its query, but
     # it is what the user clicked here, so the view highlights it.
     def selected_value
       return unless clickable?
+      return Dimension::NONE if filter("#{ransack_name}_null").present?
 
-      filters[filter_key] || filters[filter_key.to_sym]
+      filter("#{ransack_name}_eq")
     end
 
     private
+      def filter(key)
+        filters[key] || filters[key.to_sym]
+      end
+
       def dimension_definition
         definition.dimension!(dimension)
       end

data/app/models/janela/snapshot.rb

@@ -18,7 +18,7 @@ module Janela
     def stored_result(pane)
       key = pane.lookup_key
       entry = panes.find { |stored| stored.slice(*key.keys) == key }
-      raise Error, "snapshot #{id} has no pane #{key.compact.values.join(' ')}" unless entry
+      raise NotFound, "snapshot #{id} has no pane #{key.compact.values.join(' ')}" unless entry
 
       entry["result"]
     end

data/app/views/janela/panes/show.html.erb

@@ -1,3 +1,4 @@
+<% content_for :title, @pane.title %>
 <%= turbo_frame_tag @pane.frame_id do %>
   <% if @pane.single_value? %>
     <p class="janela-pane janela-value">
@@ -12,28 +13,29 @@
             data-action="janela--chart:toggle->janela--dashboard#toggle"
             data-janela--chart-type-value="<%= @pane.renderer %>"
             data-janela--chart-title-value="<%= @pane.title %>"
-            data-janela--chart-key-value="<%= @pane.filter_key %>"
             data-janela--chart-selected-value="<%= @pane.selected_value %>"
             data-janela--chart-labels-value="<%= @result.keys.to_json %>"
             data-janela--chart-values-value="<%= @result.values.map(&:to_f).to_json %>"
+            data-janela--chart-filters-value="<%= @pane.filters_for(@result.keys).to_json %>"
             role="img" aria-label="<%= @pane.title %>"></canvas>
   <% else %>
     <table class="janela-pane">
       <caption><%= @pane.title %></caption>
       <tbody>
-        <% @result.each do |value, measured| %>
+        <% @result.each do |label, measured| %>
+          <% key, value = @pane.filter_params(label) %>
           <tr>
             <td>
-              <% if @pane.clickable? %>
+              <% if key %>
                 <button type="button"
-                        aria-pressed="<%= value.to_s == @pane.selected_value.to_s && @pane.selected_value.present? %>"
+                        aria-pressed="<%= label.to_s == @pane.selected_value.to_s && @pane.selected_value.present? %>"
                         data-action="janela--dashboard#toggle"
-                        data-janela--dashboard-key-param="<%= @pane.filter_key %>"
+                        data-janela--dashboard-key-param="<%= key %>"
                         data-janela--dashboard-value-param="<%= value %>">
-                  <%= value %>
+                  <%= label %>
                 </button>
               <% else %>
-                <span><%= value %></span>
+                <span><%= label %></span>
               <% end %>
             </td>
             <td><%= number_with_delimiter(measured) %></td>

data/app/views/layouts/janela/application.html.erb

@@ -0,0 +1,18 @@
+<%# A pane opened directly, outside a Turbo Frame. Deliberately minimal: the
+    engine cannot know the host's asset names or bundler, and a host layout's
+    route helpers do not resolve inside an isolated engine (ADR 011). A host
+    can override this file, or point the controller at its own layout. %>
+<!DOCTYPE html>
+<html>
+  <head>
+    <title><%= yield(:title).presence || "Janela" %></title>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width,initial-scale=1">
+    <%= csrf_meta_tags %>
+    <%= csp_meta_tag %>
+    <%= yield :head %>
+  </head>
+  <body>
+    <%= yield %>
+  </body>
+</html>

data/docs/decisions/005-pane-urls-and-mount-path.md

@@ -1,7 +1,7 @@
 ---
 Date: 2026-09-15
 Status: Accepted
-Related: ADR 001, ADR 002, ADR 003, ADR 004
+Related: ADR 001, ADR 002, ADR 003, ADR 004, ADR 011
 Triggers:
   - changing the URL of a pane or how a dashboard frame addresses one
   - mounting the engine anywhere other than the default, or with as:
@@ -134,3 +134,6 @@ author reached for unprompted.
 - Looking up the mount in the host's route table means the helper
   finds the first mount of the engine. Mounting Janela twice is
   unsupported and not a goal.
+- The claim above that a directly opened pane renders "inside the
+  host's layout" was wrong and is superseded by ADR 011: a host
+  layout's route helpers cannot resolve inside an isolated engine.

data/docs/decisions/010-agent-guidance-ships-the-agent-waits.md

@@ -0,0 +1,130 @@
+---
+Date: 2026-09-15
+Status: Accepted
+Related: ADR 001, ADR 005, ADR 009
+Triggers:
+  - writing or changing guidance for AI agents about using Janela
+  - proposing that Janela ship an agent, a skill or an MCP surface to hosts
+  - adding generators or introspection tasks
+  - changing the public API in a way the guidance describes
+  - deciding what a host application receives on install beyond the code
+Topics: ai, agents, jan, skills, documentation, install, dx, scope
+---
+
+# ADR 010: Agent Guidance Ships, the Agent Waits
+
+## Context
+
+ADR 001 decided the reasoning behind Janela ships inside the gem, as
+ADRs, so a developer or their agent understands why a piece exists
+before changing it. That covers the *why*. Nothing covers the *how*,
+and the first real installation showed the gap has a price: three
+traps bit within an hour, each a one line fix found only by debugging.
+Ransack's allowlist is per class, so a `through:` dimension needs the
+associated model to allow the attribute. A host that bundles with
+esbuild has no importmap, so none of Janela's JavaScript loads and
+nothing cross filters while everything looks right. Janela's
+controllers are exactly as authenticated as the host's
+`ApplicationController`, which in a host that authenticates per
+controller means not at all.
+
+None of that is derivable from reading the code, which is precisely
+the test ADR 001 sets for what belongs in the repository as prose.
+
+A second, larger idea came up alongside it: that Janela ship an agent
+of its own, named Jan, so installing the gem gives a host a briefed
+colleague rather than a briefing. Open source has always shipped code
+and documentation; it could now ship the person who knows how to use
+them. It is a genuinely novel idea and nobody is doing it.
+
+The two are not the same commitment, and this ADR separates them.
+
+## Decision
+
+**A skill ships with the gem and installs into the host.**
+`docs/skills/janela/SKILL.md` lives in the gem's `docs/` tree beside
+the ADRs. `rails janela:install:skill` copies it to the host's
+`.claude/skills/janela/` and prints the one line to add to an
+`AGENTS.md` or `CLAUDE.md` for tools that read those instead. Janela
+never edits a host's instruction files itself.
+
+The skill is knowledge, not instructions to a particular agent, which
+is why it survives whatever agent formats come and go.
+
+**What the skill covers, in this order:**
+
+1. The dashboard shape that works, and why: a row of single value
+   panes, a time series, then categorical breakdowns.
+2. Choosing measures and dimensions. Name them for what they mean and
+   alias through dimensions. Keep categories low cardinality or pass
+   `limit`. Declare time dimensions with the granularity people
+   actually ask about. A dimension declaration is a promise that
+   filtering on it is allowed.
+3. The naming table from ADR 005, so an analyst's sentence becomes a
+   pane URL and back.
+4. When to take a snapshot, and that a snapshot holds results, not
+   HTML.
+5. The three traps above, each with its one line fix.
+6. What Janela deliberately does not do, so an agent does not build a
+   report designer, natural language query, row level security or a
+   scheduler into the host by accident.
+
+**The skill describes the README's API and nothing else.** One API,
+one set of names. If the skill needs to say something the README does
+not, the README is incomplete and gets fixed first. No agent only
+vocabulary.
+
+**The demo application is the worked example.** `test/dummy` shows
+every construct on realistic data, deployed and clickable. The skill
+points at specific files rather than duplicating them.
+
+**Every code sample is executable.** Each sample in the skill and in
+`docs/guides/` is lifted from a file the test suite exercises, or is
+run by a test. A sample that cannot be run is written as a sentence,
+not a code block. This is the mechanism that stops the guidance
+drifting from the code.
+
+**Jan is not shipped to hosts yet.** An agent definition is added to
+this repository only, as the project's own collaborator, and is not
+copied into host applications by any install task. Three reasons:
+
+- Its method, read the models, declare dimensions, compose in the
+  standard shape, wire the install, verify in a browser, is what a
+  capable agent with the skill loaded already does. The marginal value
+  over the skill is a name to invoke and a guarantee the skill is
+  loaded. That is convenience, not capability, and convenience is not
+  worth a public surface.
+- Agent definition formats are unsettled. The skill's content is prose
+  about dashboards and survives any format; an agent definition is the
+  part most likely to be stale in six months.
+- A gem that writes a named agent into a host arrives with opinions
+  about how that team works, not only about what its code does. That
+  cuts against the posture in ADR 001, where the invitation is to read
+  the code and fork it.
+
+**What would change this.** Ship Jan to hosts when either is true:
+
+- Jan, used on this repository, demonstrably does something a skill
+  loaded agent does not. Name the thing in the ADR that supersedes
+  this one.
+- An MCP surface exists. An agent that can query dashboards and take
+  snapshots through tools has a job no skill can do, and at that point
+  a named agent stops being a wrapper and becomes a user.
+
+## Consequences
+
+- A host that installs Janela and runs one task gets an opinionated,
+  current briefing, including the three traps that cost real debugging
+  time. That is the concrete value of this layer and it lands now.
+- `docs/guides/` becomes a real directory shipping in the gem, so a
+  forker receives reasoning, rules and how to together.
+- Jan exists but only here. The agent that helps build the gem is the
+  agent that would one day help hosts, so drift between what Jan says
+  and what the code does surfaces in this repository first. That is
+  the trial period, and it is free.
+- Saying no to shipping Jan is recorded rather than remembered, with
+  the conditions that would reverse it. A future proposal cites this
+  ADR instead of relitigating the idea.
+- Introspection (`rails janela:describe Model`), generators and MCP
+  are each one ADR away. Each must be a wrapper over the existing API,
+  for the same reason the skill must describe only one.

data/docs/decisions/011-panes-do-not-render-in-the-host-layout.md

@@ -0,0 +1,81 @@
+---
+Date: 2026-09-15
+Status: Accepted
+Related: ADR 003, ADR 005
+Triggers:
+  - changing which layout a pane renders in
+  - a host reporting NameError from its own layout when a pane loads
+  - adding anything to the engine's own layout
+  - making the dummy application unrepresentative of a real host
+Topics: layouts, engines, panes, urls, install
+---
+
+# ADR 011: Panes Do Not Render in the Host Layout
+
+## Context
+
+ADR 005 promised that a pane opened directly "gets that pane alone
+inside the host's layout". Dogfooding 0.2.0 in a second application
+showed that promise is a bug. `Janela::ApplicationController` inherits
+the host's `ApplicationController` and therefore the host's layout,
+but the engine is `isolate_namespace`d, so a route helper written in
+that layout resolves against Janela's routes and raises `NameError`.
+Almost every real application layout has a nav, so almost every host
+is broken on install, and a whole dashboard of frames goes blank.
+
+The gem's own dummy application has no route helper in its layout,
+which is exactly why the suite, the demo and the first host install
+never saw it. The first host squeaked through because its only layout
+helpers were an Active Storage URL and a PWA manifest path rather
+than nav links.
+
+## Decision
+
+**A pane requested inside a Turbo Frame renders with no layout.**
+Turbo extracts the matching frame from the response and discards
+everything around it, so a layout was never doing any work there. This
+alone fixes every dashboard, which is how panes are almost always
+requested.
+
+**A pane requested directly renders in Janela's own layout.** A
+minimal layout in the engine, carrying only a charset, a viewport, the
+CSRF and CSP tags and a `yield`. It keeps ADR 005's shareable pane
+alive and cannot depend on anything the host has not got.
+
+```ruby
+layout -> { turbo_frame_request? ? false : "janela/application" }
+```
+
+**A directly opened pane is therefore unstyled, and that is
+documented.** Janela ships no CSS (issue #15), and the engine layout
+deliberately loads none of the host's assets, because it cannot know
+their names or whether the host bundles or uses importmap. A host that
+wants its own styling on direct pane URLs sets
+`Janela::ApplicationController.layout "application"` in an
+initializer, and is told the condition: that layout must not call a
+bare host route helper, since inside an engine those need a
+`main_app.` prefix.
+
+**The dummy application's layout gains a route helper.** The dummy is
+the gem's stand in for a real host, and a stand in that omits the most
+common thing a layout contains is not doing its job. A `link_to` to
+the dashboard makes the suite fail if a pane ever renders in the host
+layout again.
+
+## Consequences
+
+- ADR 005's sentence about the host layout is superseded by this ADR.
+  The rest of ADR 005, the URL grammar and the naming table, stands.
+- Direct pane URLs render a table but not a chart, because no
+  JavaScript is loaded. Shareable pane links are therefore honest for
+  data and plain for visuals until a host opts its own layout in.
+  Acceptable: the pane URL's job is to show a number to someone, and
+  the dashboard is where charts live.
+- The engine now owns a view that a host might want to override.
+  `app/views/layouts/janela/application.html.erb` is overridable by
+  the usual Rails precedence, which is the Rails answer and needs no
+  configuration of Janela's own.
+- The lesson generalises beyond layouts: the dummy application should
+  resemble a real host in the ways hosts actually vary. Each time a
+  host finds something the dummy could not, the dummy gains that
+  characteristic rather than the fix being verified only by hand.

data/docs/decisions/INDEX.md

@@ -20,16 +20,18 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 
 | Topic | ADRs |
 |-------|------|
-| **Vision, scope, forkability** | 001 |
+| **Vision, scope, forkability** | 001, 010 |
 | **Open-source & host-decoupling** | 001 |
 | **DSL & query layer** | 002, 006, 007 |
 | **Dependencies** | 002, 003, 004, 006 |
 | **Authorisation** | 002, 003, 004, 009 |
 | **Cross-filtering & Hotwire** | 003, 004, 005, 008 |
+| **Layouts & views** | 011 |
 | **JavaScript delivery & charts** | 004, 006 |
 | **Time dimensions** | 006 |
-| **Routes, URLs & naming** | 005, 007, 008, 009 |
+| **Routes, URLs & naming** | 005, 007, 008, 009, 011 |
 | **Snapshots & publishing** | 009 |
+| **AI agents & guidance** | 010 |
 | **Security** | 003 |
 | **Testing** | 003 |
 
@@ -46,7 +48,9 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 007 | Ordering and Limits | 2026-09-15 | Accepted |
 | 008 | Dashboard Filters in the Page URL | 2026-09-15 | Accepted |
 | 009 | Snapshots | 2026-09-15 | Accepted |
+| 010 | Agent Guidance Ships, the Agent Waits | 2026-09-15 | Accepted |
+| 011 | Panes Do Not Render in the Host Layout | 2026-09-15 | Accepted |
 
 ## Next number
 
-Next ADR: 010
+Next ADR: 012

data/lib/janela/definition.rb

@@ -9,7 +9,7 @@ module Janela
     end
 
     def measure(name, **aggregate)
-      measures[name] = Measure.build(name, **aggregate)
+      measures[name] = Measure.build(name, **aggregate).tap { |measure| reject_boolean_column!(measure) }
     end
 
     def dimension(name, through: nil, column: nil, granularity: nil)
@@ -36,17 +36,31 @@ module Janela
       else
         grouped = relation.group(dimension.attribute).order(Arel.sql("#{measure.sql_alias} DESC"))
         grouped = grouped.limit(limit!(limit)) if limit
-        measure.apply(grouped)
+        measure.apply(grouped).transform_keys { |value| value.nil? ? Dimension::NONE : value }
       end
     end
 
     def dimension!(name)
-      dimensions.fetch(name) { raise Error, "#{model} has no janela dimension #{name.inspect}" }
+      dimensions.fetch(name) { raise NotFound, "#{model} has no janela dimension #{name.inspect}" }
+    end
+
+    # ActiveRecord casts an aggregate back through the column's own type, so
+    # AVG over a boolean returns true rather than a ratio. Say so at
+    # declaration rather than rendering a meaningless pane.
+    def reject_boolean_column!(measure)
+      return unless measure.column && Measure::NUMERIC.include?(measure.aggregate)
+      return unless model.type_for_attribute(measure.column).type == :boolean
+
+      raise Error, "measure #{measure.name.inspect} takes #{measure.aggregate} of the boolean " \
+                   "#{model}##{measure.column}, which ActiveRecord casts back to true or false. " \
+                   "Declare dimension #{measure.column.inspect} instead and read the split."
+    rescue ActiveRecord::ActiveRecordError
+      nil # no database to ask yet; a query will raise on its own if it cannot run
     end
 
     def limit!(value)
       limit = Integer(value, exception: false)
-      raise Error, "limit must be a whole number from 1 to 1000, got #{value.inspect}" unless limit&.between?(1, 1000)
+      raise BadRequest, "limit must be a whole number from 1 to 1000, got #{value.inspect}" unless limit&.between?(1, 1000)
       limit
     end
 
@@ -74,12 +88,12 @@ module Janela
         dropped = params.keys.reject { |key| applied.any? { |name| key.to_s.start_with?(name) } }
         return if dropped.empty?
 
-        raise Error, "#{model} does not allow filtering on #{dropped.join(', ')}. " \
+        raise BadRequest, "#{model} does not allow filtering on #{dropped.join(', ')}. " \
                      "Declare a janela dimension, or add it to ransackable_attributes."
       end
 
       def measure!(name)
-        measures.fetch(name) { raise Error, "#{model} has no janela measure #{name.inspect}" }
+        measures.fetch(name) { raise NotFound, "#{model} has no janela measure #{name.inspect}" }
       end
   end
 end

data/lib/janela/dimension.rb

@@ -2,6 +2,10 @@ module Janela
   class Dimension
     GRANULARITIES = %w[hour day week month quarter year].freeze
 
+    # A group of rows whose dimension is null. Labelled rather than blank, and
+    # filtered with Ransack's null predicate rather than an empty string.
+    NONE = "(none)".freeze
+
     LABELS = {
       "hour" => ->(t) { t.strftime("%Y-%m-%d %H:00") },
       "day" => ->(t) { t.strftime("%Y-%m-%d") },
@@ -29,7 +33,7 @@ module Janela
 
     def self.granularity!(value)
       value = value.to_s
-      raise Error, "unknown granularity #{value.inspect}, use one of #{GRANULARITIES.join(', ')}" unless GRANULARITIES.include?(value)
+      raise BadRequest, "unknown granularity #{value.inspect}, use one of #{GRANULARITIES.join(', ')}" unless GRANULARITIES.include?(value)
       value
     end
 

data/lib/janela/measure.rb

@@ -1,6 +1,9 @@
 module Janela
   class Measure
     AGGREGATES = %i[sum count average minimum maximum].freeze
+    # Aggregates whose answer is a number, so a boolean column would have its
+    # result cast back to true or false by ActiveRecord.
+    NUMERIC = %i[sum average].freeze
 
     attr_reader :name, :aggregate, :column
 

data/lib/janela/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Janela
-  VERSION = "0.2.0"
+  VERSION = "0.2.1"
 end

data/lib/janela.rb

@@ -12,6 +12,12 @@ require "janela/dimension"
 
 module Janela
   class Error < StandardError; end
+  # Something the request named does not exist: a model, measure, dimension
+  # or a pane a snapshot did not freeze. Rendered as 404.
+  class NotFound < Error; end
+  # Something the request asked for is not allowed here: a renderer, a
+  # granularity, a limit or a filter. Rendered as 400.
+  class BadRequest < Error; end
 
   # Janela's controllers inherit from the host's, so the host's authentication
   # and authorisation apply to dashboards with no configuration.
@@ -32,7 +38,7 @@ module Janela
     # In development a model is only registered once autoloaded, so a cold
     # lookup loads the app rather than constantizing an unvetted parameter.
     Rails.application.eager_load! unless registry.key?(route_key)
-    class_name = registry.fetch(route_key) { raise Error, "#{route_key.inspect} is not a janela model" }
+    class_name = registry.fetch(route_key) { raise NotFound, "#{route_key.inspect} is not a janela model" }
 
     class_name.constantize.janela
   end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: janela
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Jay Killeen
@@ -106,6 +106,7 @@ files:
 - app/models/janela/pane.rb
 - app/models/janela/snapshot.rb
 - app/views/janela/panes/show.html.erb
+- app/views/layouts/janela/application.html.erb
 - config/importmap.rb
 - config/routes.rb
 - db/migrate/20260915000001_create_janela_snapshots.rb
@@ -118,6 +119,8 @@ files:
 - docs/decisions/007-ordering-and-limits.md
 - docs/decisions/008-dashboard-filters-in-the-page-url.md
 - docs/decisions/009-snapshots.md
+- docs/decisions/010-agent-guidance-ships-the-agent-waits.md
+- docs/decisions/011-panes-do-not-render-in-the-host-layout.md
 - docs/decisions/INDEX.md
 - lib/janela.rb
 - lib/janela/definition.rb