janela 0.12.0 → 0.14.0

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

@@ -66,6 +66,12 @@
     <%= form.select :prominence, Janela::Pane::PROMINENCES.map { |step| [ t("janela.prominences.#{step}"), step ] }, include_blank: t("janela.prominences.automatic") %>
   </div>
 
+  <div class="janela-field">
+    <%= form.check_box :value_labels %>
+    <%= form.label :value_labels %>
+    <span class="janela-hint"><%= t("janela.value_labels.hint") %></span>
+  </div>
+
   <div class="janela-field">
     <%= form.label :span %>
     <%= form.select :span, Janela::Pane::SPANS.to_a %>

data/app/views/janela/queries/_query.html.erb

@@ -15,21 +15,23 @@
     <figcaption class="janela-chart-title" id="<%= title_id %>"><%= query.title %></figcaption>
     <%# A height puts the canvas in a box of fixed size for the chart to fill;
         with none there is no box and the chart is what it always was (ADR 047). %>
-    <% canvas = capture do %>
-    <canvas class="janela-chart"
-            data-controller="janela--chart"
-            data-action="janela--chart:toggle->janela--frame#toggle"
-            data-janela--chart-type-value="<%= query.renderer %>"
-            data-janela--chart-title-value="<%= query.title %>"
-            data-janela--chart-selected-value="<%= query.selected_values.to_json %>"
-            data-janela--chart-labels-value="<%= result.keys.to_json %>"
-            data-janela--chart-values-value="<%= result.values.map(&:to_f).to_json %>"
-            data-janela--chart-formatted-value="<%= result.values.map { |measured| query.format(measured) }.to_json %>"
-            data-janela--chart-filters-value="<%= query.filters_for(result.keys).to_json %>"
-            <%= tag.attributes(aria: { description: (t("janela.time.click_hint") if query.time? && query.clickable?) }) %>
-            <%= "data-janela--chart-fixed-height-value=true".html_safe if query.boxed? %>
-            role="img" aria-labelledby="<%= title_id %>"></canvas>
-    <% end %>
+    <% canvas = tag.canvas(
+         class: "janela-chart", role: "img",
+         aria: { labelledby: title_id, description: (t("janela.time.click_hint") if query.time? && query.clickable?) },
+         data: {
+           controller: "janela--chart",
+           action: "janela--chart:toggle->janela--frame#toggle",
+           "janela--chart-type-value": query.renderer,
+           "janela--chart-title-value": query.title,
+           "janela--chart-selected-value": query.selected_values.to_json,
+           "janela--chart-labels-value": result.keys.to_json,
+           "janela--chart-values-value": result.values.map(&:to_f).to_json,
+           "janela--chart-formatted-value": result.values.map { |measured| query.format(measured) }.to_json,
+           "janela--chart-tick-format-value": query.tick_format.to_json,
+           "janela--chart-filters-value": query.filters_for(result.keys).to_json,
+           "janela--chart-fixed-height-value": (true if query.boxed?),
+           "janela--chart-value-labels-value": (true if query.labelled?)
+         }) %>
     <%= query.boxed? ? tag.div(canvas, class: "janela-chart-box janela-h-#{query.height}") : canvas %>
   </figure>
 <% else %>

data/config/locales/en.yml

@@ -22,9 +22,13 @@ en:
         span: Width
         height: Height
         prominence: Prominence
+        value_labels: Show each bar's value
         companions: Beside the label
         title: Title
   janela:
+    errors:
+      not_found: There is no such pane.
+      bad_request: That request is not allowed on this pane.
     actions:
       add_pane: "Add a %{name}"
       cancel: Cancel
@@ -71,6 +75,8 @@ en:
       measures: Measures
       dimensions: Dimensions
       hint: Up to three, drawn as columns in a table. A dimension shows a value only where every row of its group shares one.
+    value_labels:
+      hint: Draws the value at the end of each bar of a bar chart, if every one fits. Other charts ignore it.
     prominences:
       automatic: Automatic
       "1": Footnote

data/db/migrate/20261006000001_add_value_labels_to_janela_panes.rb

@@ -0,0 +1,7 @@
+class AddValueLabelsToJanelaPanes < ActiveRecord::Migration[8.0]
+  def change
+    # Whether a bar chart draws each bar's value on the bar (ADR 054). Null is
+    # what every existing pane is: unset, and drawn exactly as before.
+    add_column :janela_panes, :value_labels, :boolean
+  end
+end

data/docs/agents.md

@@ -0,0 +1,97 @@
+---
+Topics: agents, mcp, tools, authorisation, host-integration
+---
+
+# Giving an Agent Access to Janela
+
+Frames and panes are rows (ADR 012), so an agent could always arrange a
+dashboard by writing them from a console. This page is for giving it tools
+instead: read a frame, read a pane's values, and, if you choose, add, change,
+remove and move panes. The reasoning is in ADR 053.
+
+The short version: Janela gives you the tool definitions as plain Ruby. You
+build them with the answer to "what may this caller read", and you register
+them with whatever MCP library your application already runs. Janela
+registers nothing, detects nothing and serves nothing, because it cannot
+know who is asking and your application can.
+
+## Building the tools
+
+```ruby
+tools = Janela::Tools.new(scope: ->(model) { policy_scope(model) })
+```
+
+`scope:` is required. It takes a model class and returns a relation: the same
+answer your `policy_scope` gives a Janela controller (ADR 032). Leave it out
+and `Janela::Unscoped` is raised when the tools are built, because a tool with
+no scope would read every row of every model. Every read the tools make passes
+that relation, and frames and panes are found through it too, so a caller can
+change only what it can see.
+
+Build the tools where you know who is asking, which for an MCP server is when a
+tool is called. They are cheap to construct.
+
+## What they do
+
+| Tool | Does | Needs `write: true` |
+| --- | --- | --- |
+| `describe_vocabulary` | The models, measures, dimensions, renderers and granularities the `janela` blocks declare. An agent should offer nothing else. | no |
+| `list_frames` | The frames the scope returns: id, name, owner, pane count. | no |
+| `get_frame` | One frame with its panes in position order. | no |
+| `read_pane` | A pane's values, through the scope. Filters are Ransack predicates on declared dimensions, bounded as a reader's are (ADR 025). | no |
+| `add_pane` | Add a pane to the end of a frame. | yes |
+| `update_pane` | Change a pane. An invalid change leaves it as it was. | yes |
+| `remove_pane` | Remove a pane and close the gap. | yes |
+| `move_pane` | Move a pane one place up or down. | yes |
+
+The write tools are off unless you build the tools with `write: true`. Their
+inputs are the pane's own attributes, the ones the README
+names, and nothing else: an attribute that is not a pane's is refused rather
+than dropped. A pane Janela would refuse is refused with its own reason, for
+example `Measure "nonsense" is not a measure of Order`.
+
+There is no tool to create a frame or take a snapshot. Your code finds or makes
+a frame with `Janela::Frame.for` (ADR 041), and a snapshot needs an owner and a
+scope you have named (ADR 033, ADR 034).
+
+## Registering them
+
+`Janela::Tools.all` is the list of definitions, and needs no scope: each has a
+`name`, a `description`, an `input_schema` (JSON Schema) and `read_only`.
+`tools.call(name, arguments)` runs one and returns a Hash, or raises a
+`Janela::Error` (`NotFound`, `BadRequest` or `Unscoped`) that an adapter reports
+to the agent as the tool's own error.
+
+For the official Ruby SDK, the `mcp` gem, an adapter looks like this. It is run
+by Janela's own tests, so it cannot drift from the code. `server_context` is
+whatever your server was built with, and is where you keep the caller; the
+scope is built from it at the moment of the call.
+
+```ruby
+def janela_server(write: false)
+  tools = Janela::Tools.all(write: write).map do |tool|
+    MCP::Tool.define(name: tool.name, description: tool.description, input_schema: tool.input_schema,
+                     annotations: { read_only_hint: tool.read_only }) do |server_context:, **arguments|
+      # The scope is built per call, because who is asking is known only now.
+      scope = ->(model) { server_context[:scope].call(model) }
+      result = Janela::Tools.new(scope: scope, write: write).call(tool.name, arguments)
+      MCP::Tool::Response.new([ { type: "text", text: result.to_json } ])
+    rescue Janela::Error => error
+      MCP::Tool::Response.new([ { type: "text", text: error.message } ], error: true)
+    end
+  end
+
+  MCP::Server.new(name: "janela", tools: tools, server_context: { scope: yield })
+end
+```
+
+`mcp` is not a dependency of Janela, and a host using another library writes the
+same few lines against it.
+
+## What Janela does not do
+
+It does not serve MCP, detect a server, edit your configuration or install
+anything. It holds no credentials and has no idea who your agent is. Whether an
+agent may reach your MCP server at all is your server's authentication, which
+Janela never sees. Everything it adds is the question it already asks: what may
+this caller read?

data/docs/composing.md

@@ -23,12 +23,12 @@ with your own classes plus the hooks in [Theming Janela](theming).
 | `janela_frame do ... end` | anywhere inside the block | the page needs a heading, text, links or a layout of its own |
 | `janela_frame @frame` | none | the dashboard is data an analyst edits without a deploy |
 
-A stored frame renders panes and nothing else. That is deliberate (ADR
-012): a row names a measure the model declared, so an analyst arranges
-what is shown and cannot put arbitrary content on the page. If a
-dashboard needs a heading and an explanation, write them in the page
-around the frame, or use the block form. Whether a stored frame should
-hold content of its own, such as text or an image, has not been decided.
+A stored frame renders panes, and a pane is either a query, a few words
+the analyst writes (a heading, a sentence, a link), or a partial you
+wrote and they place by name (ADR 039). What an analyst writes is
+escaped, never markup, so a row cannot put arbitrary content on the page
+(ADR 012). Anything richer than that, an icon, an image, a layout of your
+own, goes in the page around the frame, or use the block form.
 
 ```erb
 <h2>Orders</h2>
@@ -58,9 +58,9 @@ same classes a stored frame gets from its integers:
 
 Every direct child is a grid item, your own elements included, so a
 heading can take a whole row and a text box can sit between two panes.
-`janela_pane` takes no class of its own yet
-([#29](https://github.com/retail-tasker/janela/issues/29)), so wrap a
-pane to span it:
+`janela_pane` takes no class of its own, and will not: arranging panes
+beyond the shipped grid is the host's (see the roadmap). So wrap a pane
+to span it:
 
 ```erb
 <div class="janela-span-2"><%= janela_pane Order, :revenue, by: :status, as: :bar %></div>
@@ -195,11 +195,11 @@ and number, so the figure needs a `<div>` rather than a `<p>` around it,
 and a line of CSS to put the numbers side by side. Without it they
 stack.
 
-A done out of total figure cannot be two panes yet. A measure has no
-condition of its own, so there is no pane for the done half. Compute it
-as the progress bar below does. A measure that is itself the ratio is
-proposed in ADR 038
-([#27](https://github.com/retail-tasker/janela/issues/27)).
+A done out of total figure over a yes or no column is one pane: a
+`ratio:` measure is the share of rows where a boolean is true (ADR 038).
+When the condition is not a column, a measure has no condition of its own,
+so there is no pane for the done half; compute it as the progress bar
+below does.
 
 ### A progress bar
 

data/docs/decisions/020-formatting-belongs-to-the-measure.md

@@ -2,6 +2,7 @@
 Date: 2026-09-16
 Status: Accepted
 Related: ADR 002, ADR 009, ADR 012, ADR 018
+Superseded in part by: ADR 054
 Triggers:
   - a number rendering with more precision than it means
   - adding an option to a pane, a frame or a pane URL
@@ -74,7 +75,9 @@ back under a format declared today.
 and a chart tooltip all show the string the measure produced, and the
 chart is handed those strings rather than formatting a second time in
 JavaScript. The chart still plots raw numbers, because an axis is a
-scale and not a label.
+scale and not a label. (Superseded in part by
+ADR 054: the axis is formatted by the measure too. The chart still plots
+raw numbers.)
 
 ## Consequences
 

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.