janela 0.14.0 → 0.16.0

data/docs/decisions/062-a-time-pane-can-accumulate-and-carry-more-series-on-two-axes.md

@@ -0,0 +1,282 @@
+---
+Date: 2026-10-29
+Status: Proposed
+Related: ADR 002, ADR 005, ADR 006, ADR 007, ADR 009, ADR 018, ADR 020, ADR 029, ADR 037, ADR 045, ADR 046, ADR 047, ADR 051, ADR 054, ADR 055
+Triggers:
+  - a running total, a cumulative line, a to-date figure over time
+  - drawing two measures on one chart, or a bar beside a line
+  - a second value axis, a right axis, or two scales on one plot
+  - a series bucketed by a different date column than the pane's
+  - adding a column to janela_panes, or a parameter to the pane URL
+  - choosing the colour of a series rather than of a category
+  - a chart legend, or a title on an axis
+Topics: charts, time, dsl, query layer, panes, urls, public-api, frames, styling
+---
+
+# ADR 062: A Time Pane Can Accumulate, and Carry More Series on Two Axes
+
+## Context
+
+#90, raised from a real install building an adoption chart: sign-ups to
+date and activations to date as two lines on the left axis, new sign-ups
+per week as bars on a right axis, one chart, filtered by the panes around
+it. The host built it as a partial pane (ADR 039) holding its own Chart.js
+controller and its own query. It draws, and it is wrong in three ways that
+matter: it does not change when the reader clicks another pane, it is not a
+row an analyst can edit, and it is a second chart implementation the host
+has to keep in step with the gem's.
+
+Four gaps stand between a pane and that chart, measured against `main`
+before deciding.
+
+**Nothing accumulates.** `Definition#series` returns one value per bucket
+and `Query#result` hands it on. A chart of orders per month cannot be a
+chart of orders to date without a column on the model that stores the
+running count, which is presentation in the schema.
+
+**One measure, one dimension.** `Query` holds exactly one of each. The
+chart partial hands the controller one `labels` and one `values` array,
+and `chart_controller.js` builds one dataset over one `y` scale. Two
+measures over the same weeks are two panes, which cannot share an axis.
+
+**The renderer is the pane's.** A pane is bars or a line, never both.
+
+**A second value axis does not exist.** A count of five beside a total of
+five hundred is a line on the floor.
+
+Three facts shape the answer.
+
+**Groupdate's keys differ by column type.** A date column's week buckets
+come back as `Date` (`Mon, 31 Aug 2026`), a timestamp's as `Time` in the
+zone. Two series over two columns can only share an x axis if their keys
+are made the same kind first; `in_time_zone` gives the same instant for
+both, and `Dimension#span` already reads a bucket that way.
+
+**A list of hashes survives a URL if each starts with the same key.**
+Rack's nested query parser opens a new hash in `series[][...]` when a key
+repeats and otherwise adds to the last one, so `a[][x]=1&a[][y]=4&a[][x]=3`
+gives the first hash the `y` meant for the second. Rails' `to_query`
+leaves keys in their given order inside a `[]` namespace rather than
+sorting them, measured: `{ series: [{ measure: "m", by: "d" }, { measure:
+"n", as: "bar" }] }` writes `measure` first in each and parses back whole.
+A series led by its measure is unambiguous; one that is not may not be.
+
+**Chart.js draws a mixed chart from a type per dataset** and a second
+scale from a second entry in `scales`, so the canvas needs nothing new
+shipped (ADR 004).
+
+### What was considered
+
+**A stored column for the running total.** The host's workaround today.
+Rejected: ADR 051 refused presentation in the schema for companions, and
+a running total is the measure's own numbers added up, which is one line
+of Ruby after the read.
+
+**A `combo` renderer.** A fifth renderer whose dataset shape is its own.
+Rejected: it would be a renderer that means "several of the other two",
+and a table could not be its fallback without learning the same shape
+anyway (ADR 018). The series are what is new; which of two existing
+renderers each one uses is one word on it.
+
+**A second pane that is told to share an axis with the first.** Two
+panes, two queries, one canvas somehow. Rejected: a pane is one turbo
+frame with one URL (ADR 005, ADR 029), and two of them cannot be one
+`<figure>`.
+
+**Series on a categorical pane.** Revenue and orders by status as grouped
+bars. Not built, and not refused for ever: a categorical pane colours by
+position in the result (ADR 046), a series needs colour by series, and
+which rule wins is a decision of its own. The one host that needs this
+needs it over time.
+
+**A series with its own granularity.** Rejected: the point of a series is
+that it shares the pane's buckets, and a week beside a month is two x
+axes.
+
+**Colour by category on a multi-series bar.** ADR 046 draws a bar in the
+colour of its position. Rejected for a pane with series: a bar series over
+thirty weeks in eight colours and a grey, beside a legend that names one
+series, is a wrong picture. A pane with series colours by series.
+
+**Formatted labels on every point of a line.** ADR 054 refused this and
+the refusal stands. What a running total wants is its latest value, once,
+at the end of the line.
+
+**A per-series `title` left out, naming by measure alone.** Considered,
+because a measure is already named for what it means on the dashboard
+(ADR 002) and a host can declare `measure :sign_ups, count: true` beside
+`measure :activations, count: true` for the same aggregate. Not enough on
+its own: the same measure over the same dimension, once to date and once
+per week, is the first chart anyone draws with this, and two legend
+entries reading `Orders` is a wrong picture. A series may carry a title,
+and the one Janela writes says what it is.
+
+## Decision
+
+**A time pane may carry `cumulative`, a running total of its measure
+across its buckets, and `series`, up to three more measures of the same
+model over the same buckets, each drawn as a line or as bars, each on the
+left axis or a right one. Unset is exactly what a pane is today.**
+
+```erb
+<%= janela_pane Order, :orders, by: :placed_on, as: :line, granularity: :month,
+      cumulative: true,
+      series: [
+        { measure: :orders, by: :shipped_on, cumulative: true, title: "Orders shipped to date" },
+        { measure: :orders, as: :bar, axis: :right, title: "Orders per month" }
+      ] %>
+```
+
+**`cumulative` is a yes or a no, and a time pane's.** The running total
+is summed in Ruby after the read, so the SQL, the buckets, the filters and
+the click on a bucket are what they always were (ADR 045). A stored
+snapshot keeps per-bucket numbers and a cumulative view of it is summed
+the same way on read, so nothing about what is stored changes (ADR 009).
+Only a measure that adds up accumulates, a count or a sum: an average, a
+minimum, a maximum or a ratio is refused with its reason, as is a series
+with `cumulative` over one, because their sum is a number that means
+nothing. On a categorical pane or a single value it is refused with its reason,
+not ignored: a running total over categories sorted by their measure is a
+different chart that nobody has asked for, and a row whose dimension is
+changed to a category is told so on the form rather than quietly drawing
+something else.
+
+**A series is a hash of up to six words, and the first is `measure`.**
+
+| key | takes | unset means |
+| --- | --- | --- |
+| `measure` | a measure the model declares | required |
+| `by` | a time dimension the model declares | the pane's own dimension |
+| `cumulative` | `1` or `0` | `0` |
+| `as` | `line` or `bar` | the pane's renderer when it is one of those, else `line` |
+| `axis` | `left` or `right` | `left` |
+| `title` | words for the legend and the table header | Janela writes one |
+
+Only what the model declared, by the name it declared it under, as
+companions are bounded (ADR 025, ADR 051). A series by a different time
+dimension shares the pane's granularity: its buckets are read with the
+same `week_start`, every series' buckets are joined into one sorted set
+through `in_time_zone`, and a bucket a series has no row in is zero for a count or a sum, so
+`Orders shipped to date` is flat across a month nothing shipped rather
+than absent, and a gap for an average, minimum, maximum or ratio, which
+have no value in an empty bucket. Joined buckets beyond 10,000 are a
+refusal, so a stray year in a column cannot build a hundred thousand. Two series that name the same measure, dimension and
+`cumulative` are refused as one series drawn twice. Four series are a
+refusal that says three.
+
+**The title Janela writes** is the measure's name, then `by` and the
+dimension's name when the series is over a dimension other than the
+pane's, then `to date` when it is cumulative: `Orders`, `Orders by
+Shipped on to date`. The same rule names the pane's own series, so a
+cumulative pane's legend and table header read `Orders to date`. A
+`title` replaces all of it and is escaped like any other string.
+
+**The pane's own measure is the first series, and it is the left axis.**
+The pane's measure, dimension, renderer and `cumulative` are what they
+were. What a click writes is the pane's dimension's range (ADR 045), and
+the x axis is the pane's buckets. Filters are applied to every series the
+same way: the reader's selection on the pane's own dimension is set aside
+for all of them, because the pane shows the alternatives to it, and a
+selection on any other dimension, including a series' own, narrows that
+series as it narrows every pane.
+
+**A bar and a line draw the series as datasets. A table draws them as
+columns. A ring and a single value ignore them,** as a ring ignores a
+height (ADR 047) and every renderer but a table ignores companions (ADR
+051), so a pane switched between renderers keeps them. The table is the
+fallback on a surface with no chart runtime (ADR 018), with a header row
+as a table with companions has, the series' columns after the measure's
+and before any companions. A stored snapshot holds no series, as it holds
+no companions, so a snapshot pane with them shows the base table.
+
+**With series, the chart shows a legend and colours by series.** The
+pane's own series is `--janela-series-1`, the next `--janela-series-2`,
+and so on, in the order given (ADR 046's palette, by series rather than by
+category). Bars are drawn behind lines. A selected bucket is solid and the
+rest faded, in every dataset, as a single series is today. Without series
+nothing about a chart's colour, legend or interaction changes.
+
+**A right axis exists when a series asks for it, and then both axes are
+titled.** A right axis draws no grid lines across the plot, so the left
+axis's grid is the only one. Each axis's title is the titles of the
+series on it, in order, because an untitled second scale is the way two
+scales mislead. When every series on the right axis is bars, that axis is
+scaled so the tallest bar reaches about a third of the plot, so bars sit
+under the lines rather than fighting them. A line on the right axis is
+scaled to its own data like any line.
+
+**`value_labels` on a line writes its latest value at the end of the
+line, in text ink.** One label, not one per point, which is what ADR 054
+refused. It applies to every line series on a pane that asks for it. Bars
+on a pane with series draw no labels: their slots are shared and the all
+or none rule of ADR 054 would almost always say none. A single-series bar
+chart is unchanged. This supersedes the sentence in ADR 054 that a line
+ignores the flag, and nothing else in it.
+
+**One vocabulary in three places,** as height and companions are:
+
+- `Janela::Pane#cumulative`, a nullable boolean, and `Janela::Pane#series`,
+  a nullable JSON array of hashes, validated on save against the model's
+  declared measures and dimensions through the same `Query` that would
+  refuse the request. The pane form offers a checkbox and one blank
+  series slot beyond those filled, each a group of plain selects since
+  the engine's pages have no JavaScript (ADR 018), wherever it offers a
+  granularity: on a pane over a time dimension, or one with no dimension
+  chosen yet.
+- `janela_pane` and `janela_snapshot_pane` take `cumulative:` and
+  `series:`.
+- The pane URL carries `?cumulative=1` and `series[][measure]=orders&
+  series[][by]=shipped_on&series[][cumulative]=1`, each series led by its
+  measure, because the server draws the pane again from that URL on every
+  cross-filter.
+
+**`cumulative` and `series` are part of the pane's identity when set.**
+A measure to date and the same measure per period are two answers that
+may share a page, as top five and bottom five are (ADR 055), so a set
+`cumulative` joins `Query.turbo_frame_id` and an unset one leaves every
+existing id alone. Two panes that differ only in their series draw
+different charts, so a set `series` joins it as a short digest of the
+words given, however they were spelled; none leaves the id as it was.
+`cumulative` is read from the flag the way the server reads it, so `"0"`
+is no in the URL and in the id alike.
+
+## Consequences
+
+- The adoption chart is a row, or one `janela_pane`, and it cross-filters,
+  falls back to a table, and is edited on the pane form like any other.
+- **A migration for stored frames.** `janela_panes` gains a nullable
+  boolean `cumulative` and a nullable JSON `series`, additive, in one
+  migration. A host using stored frames runs `bin/rails
+  janela:install:migrations` and `db:migrate`, written in `UPGRADING.md`.
+  The doctor's `unmigrated-columns` check is taught both.
+- **`Janela::Tools` learns both attributes** in the same change, with the
+  series' keys in its schema (ADR 053).
+- **The pane URL grammar grows by one parameter and one array of hashes.**
+  ADR 037 counts that as public surface. The array of hashes is the first
+  structured parameter in the grammar, and it is readable because each
+  hash is a short sentence led by its measure.
+- **A chart with series carries three more data attributes** (`series`,
+  `label`, `axes`), and `labels`, `values` and `formatted` keep meaning
+  the pane's own series, so a host that subclasses the controller and
+  reads `datasets[0]` sees what it saw.
+- The running total is summed from the buckets Groupdate returned, so it
+  starts at the first bucket with a row, not at the beginning of time. A
+  host that fixes the frame's range with `where:` starts the count there.
+  That is the right answer for a filtered dashboard and the surprising one
+  for a chart meant to begin at zero on launch day; a `where:` from the
+  launch date is the way to say so.
+- A series by a different time dimension counts rows where that column
+  falls in the bucket, so a null is not counted anywhere. That is what
+  makes `Orders by Shipped on` the orders that shipped, with no filter.
+- Up to three more queries per pane, bounded as companions are (ADR 051).
+- Text labels on a canvas are not available to a screen reader, which is
+  as true of the lines themselves (ADR 042) and is why the table is
+  always there.
+- Not decided here: series on a categorical pane; a series with its own
+  granularity or its own filter; stacking; a legend a keyboard can
+  operate; a second axis for a single series. Each starts from the table
+  above.
+- What would change this decision: a host that needs a grouped bar over
+  categories, which reopens the colour rule and is the first thing to
+  revisit; or a dashboard whose series come from two models, which is an
+  argument about what a pane is and not about this.

data/docs/decisions/063-a-pane-can-ignore-a-filter-its-model-cannot-apply.md

@@ -0,0 +1,147 @@
+---
+Date: 2026-10-29
+Status: Proposed
+Related: ADR 003, ADR 005, ADR 008, ADR 012, ADR 025, ADR 035, ADR 037, ADR 040, ADR 043, ADR 053
+Triggers:
+  - a frame holding panes over more than one model
+  - a pane showing "That request is not allowed on this pane" after a click on another pane
+  - deciding what a pane does with a filter key its model does not declare
+  - adding a boolean to a pane, a column to janela_panes, or a parameter to the pane URL
+  - a setting that could live on the frame or on the pane
+Topics: cross-filtering, ransack, panes, frames, urls, public-api, security
+---
+
+# ADR 063: A Pane Can Ignore a Filter Its Model Cannot Apply
+
+## Context
+
+#92, found trialling a frame that holds panes over two models: the demo's
+orders, with a status, a region and a date, and the demo's page views,
+with a page and a date. Clicking `paid` on an orders pane writes
+`q[status_in][]=paid` to the frame (ADR 003, ADR 008), the frame hands
+it to every pane, and the page views pane answers with "That request is
+not allowed on this pane" where its number was.
+
+Measured against the demo before deciding. `Query#applicable_filters`
+drops only the pane's own dimension, which is the cross-filtering rule:
+the pane you clicked shows the alternatives to what you picked. Every
+other key goes to `Definition#filter`, where `reject_dropped_filters!`
+compares what Ransack applied with what was asked and raises
+`BadRequest` for the difference: `PageView does not allow filtering on
+status_in`. Ransack itself, asked for `status_in` and `viewed_on_gteq`
+on page views, applied `viewed_on` and dropped `status` without a word.
+
+That refusal is deliberate and right (ADR 025). Ransack discards a
+condition its allowlist does not permit, so a typo in a hand written
+`q[...]` would quietly show an unfiltered number, which is the worst
+thing this library can do. Nothing about that changes here. What is
+wrong is only its reach: a key another pane's model declares is not a
+mistake, it is a click the reader made on a pane beside this one, and
+the honest answer is for this pane to stay as it is.
+
+A key both models declare under the same name, such as a date, or one
+reached through an association, already works, because it matches a
+declared dimension on the second model too.
+
+### What was considered
+
+**Drop undeclared keys on every pane.** The smallest change and the
+wrong one: it removes the loud failure ADR 025 chose, for every host,
+to suit the one frame that mixes models.
+
+**A setting on the frame.** A frame is where the mixing happens, so a
+frame that says "my panes ignore what they cannot apply" reads well.
+Rejected, for how a pane is drawn. A pane is fetched on its own URL in
+its own request (ADR 005), lazily and again on every cross-filter, and
+a hand written `janela_frame do` block has no record at all, so the
+setting would have to travel on each pane's URL anyway to reach the
+request that draws it. A frame column would then be a fourth place to
+say a per-pane thing, beside the row, the helper and the URL that every
+other option already uses, and it could not reach a hand written frame.
+
+**Derive it: drop a key that another pane in the same frame declares.**
+The most precise rule, since a key no pane can apply is still a typo.
+Rejected, because only a stored pane fetched through its frame knows
+what the other panes are; a `janela_pane` on its own URL does not, and
+the two shapes would behave differently for the same click.
+
+**Have the frame controller send each pane only the keys its model
+declares.** The browser does not know the models' dimensions, and
+teaching it would put the allowlist in the page (ADR 025 keeps it on
+the server).
+
+## Decision
+
+**A pane may carry `ignore_unknown_filters`, a yes or a no. When set,
+the reader's filters whose keys Ransack would not apply to the pane's
+model are dropped before the query, and the pane draws as if they were
+never written. Unset is exactly what a pane is today: a key the model
+does not declare is refused with its reason.**
+
+```erb
+<%= janela_frame do %>
+  <%= janela_pane Order, :revenue, by: :status, as: :bar %>
+  <%= janela_pane PageView, :views, by: :page, ignore_unknown_filters: true %>
+<% end %>
+```
+
+**Only the reader's filters are dropped.** A host's fixed `where:`
+(ADR 040) and a frame's `default_where` (ADR 043) are the host's and the
+analyst's own words about this pane and stay refused when wrong, as they
+are validated today. A key the model does declare but with a predicate
+its dimension does not allow, such as `status_matches`, is still refused:
+that is a misuse of a real key, not another model's key.
+
+**What is dropped is what Ransack would drop,** read the same way
+`reject_dropped_filters!` reads it, so the two cannot disagree about
+which keys belong to the model. A key that survives is applied exactly
+as it would be on any pane.
+
+**It is opt in, per pane, because the pane is what knows.** A pane is
+the unit that is fetched, refused and drawn, and the analyst placing a
+page views pane on an orders frame is the one who knows it will be
+clicked past. A pane that never meets another model keeps the loud
+failure, and a typo on it is still a typo.
+
+**One vocabulary in three places,** as `value_labels` is (ADR 054):
+
+- `Janela::Pane#ignore_unknown_filters`, a nullable boolean offered on
+  the pane form as a checkbox.
+- `janela_pane` takes `ignore_unknown_filters:`.
+- The pane URL carries `?ignore_unknown_filters=1`, because the server
+  draws the pane again from that URL on every cross-filter.
+
+`janela_snapshot_pane` does not take it: a snapshot's filters were
+fixed when it was taken and the request's are ignored (ADR 009).
+
+**It is not part of the pane's identity** (ADR 029). What a pane does
+with a stray key does not say which query it is.
+
+## Consequences
+
+- A frame can hold panes over two models and a click on either side
+  leaves the other side standing. That is the first thing a host
+  building a page over events and the records they belong to tries.
+- **A migration for stored frames.** `janela_panes` gains a nullable
+  boolean, additive, so every existing pane is unset and refused as
+  before. A host using stored frames runs `bin/rails
+  janela:install:migrations` and `db:migrate`, in `UPGRADING.md`. The
+  doctor's `unmigrated-columns` check is taught the column.
+- **`Janela::Tools` learns the attribute** in the same change (ADR 053).
+- **The pane URL grammar grows by one optional parameter,** which ADR
+  037 counts as public surface.
+- A pane that ignores a key is silently unfiltered by it, which is the
+  very thing ADR 025 refuses by default. It is accepted here because the
+  analyst asked for it on that pane, and because the alternative is a
+  pane that cannot share a frame with another model at all. The log
+  says nothing when a key is dropped: a dropped key is the normal case
+  on such a pane, not a finding.
+- A dimension reached through an association is addressed by the host
+  as `<association>_<column>`, so two models can share a click only when
+  they spell the key the same. A way for a host to alias that name is a
+  separate question, not decided here.
+- What would change this decision: a frame that needs the derived rule,
+  a key dropped only when another pane in the frame declares it, which
+  would need the pane URL to carry the frame's vocabulary and is an
+  argument about what a pane URL says; or a host that wants the drop
+  logged, which is a setting that would have to earn itself.

data/docs/decisions/INDEX.md

@@ -21,28 +21,28 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | Topic | ADRs |
 |-------|------|
 | **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 |
+| **Open-source & host-decoupling** | 001, 022, 036, 041, 052, 060, 061 |
+| **DSL & query layer** | 002, 006, 007, 020, 025, 038, 044, 049, 051, 055, 062 |
 | **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, 054 |
-| **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, 053, 054 |
+| **Ordering & formatting** | 007, 020, 038, 054, 055, 061, 062 |
+| **Cross-filtering & Hotwire** | 003, 004, 005, 008, 024, 025, 040, 043, 044, 045, 048, 049, 063 |
+| **Layouts & views** | 011, 012, 016, 018, 020, 027, 039, 047, 050, 059 |
+| **CSS & styling** | 016, 018, 023, 026, 027, 036, 042, 046, 047, 050, 062 |
+| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030, 033, 039, 040, 041, 043, 044, 047, 048, 050, 051, 053, 054, 055, 062, 063 |
 | **Naming rule** | 014, 023, 036 |
-| **JavaScript delivery & charts** | 004, 006, 026, 042, 046, 047, 054 |
-| **Time dimensions** | 006, 025, 045 |
-| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025, 040, 041, 045, 047, 050, 051, 054 |
-| **Snapshots & publishing** | 009, 020, 028, 033, 034, 051 |
-| **AI agents & guidance** | 010, 015, 021, 053 |
-| **The doctor & checks** | 021, 025, 032, 033, 035 |
+| **JavaScript delivery & charts** | 004, 006, 026, 042, 046, 047, 054, 059, 062 |
+| **Time dimensions** | 006, 025, 045, 061, 062 |
+| **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025, 040, 041, 045, 047, 050, 051, 054, 055, 061, 062, 063 |
+| **Snapshots & publishing** | 009, 020, 028, 033, 034, 051, 055 |
+| **AI agents & guidance** | 010, 015, 021, 053, 056, 057, 058 |
+| **The doctor & checks** | 021, 025, 032, 033, 035, 057 |
 | **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 |
+| **Security** | 003, 025, 028, 031, 032, 034, 035, 044, 052, 063 |
 | **Testing** | 003 |
-| **Roadmap & planning** | 001, 037, 045, 046, 052, 053 |
+| **Roadmap & planning** | 001, 037, 045, 046, 052, 053, 060 |
 
 ## Chronological
 
@@ -102,7 +102,16 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 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 |
 | 054 | A Chart Reads Numbers the Way Its Measure Formats Them | 2026-10-06 | Accepted |
+| 055 | A Category Pane Can Be Sorted by Its Measure Either Way, or by Its Label | 2026-10-13 | Accepted |
+| 056 | The Demo Counts Its Own Visits, and an Agent Arranges the Dashboard | 2026-10-13 | Accepted |
+| 057 | A Host Is Told About the Agent Tools, and a Generator Sets Them Up | 2026-10-14 | Accepted |
+| 058 | The Deployed Demo Is Reached Over SSH, and Its Visits Frame Survives a Reset | 2026-10-14 | Accepted |
+| 059 | A Host Can Tell Janela's Own Pages That Its Layout Draws Charts | 2026-10-14 | Proposed |
+| 060 | The Demo Tells Search Engines What It Is, and Shows Its Own Adoption | 2026-10-14 | Proposed |
+| 061 | The Demo Speaks Brazilian Portuguese Under a Prefix, and the Gem Stays English | 2026-10-14 | Proposed |
+| 062 | A Time Pane Can Accumulate, and Carry More Series on Two Axes | 2026-10-29 | Proposed |
+| 063 | A Pane Can Ignore a Filter Its Model Cannot Apply | 2026-10-29 | Proposed |
 
 ## Next number
 
-Next ADR: 055
+Next ADR: 064

data/docs/roadmap.md

@@ -134,7 +134,8 @@ change in any release, and every change of that kind carries an entry in
 **A pane can be read.** Janela draws tables, bars, lines, doughnuts and
 pies. A table row can carry context beside its label, a single number says
 how prominent it is, a chart has a height that suits the page, its axis reads
-in the measure's own format, and a bar can show its value. Those
+in the measure's own format, a bar can show its value, and a category pane can
+be put in the order that reads. 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.
 
@@ -151,9 +152,14 @@ height, a ratio measure, single value prominence, companion columns, Sprockets
 hosts, and how the project is run. 0.13.0 added tools an agent can use
 (ADR 053). 0.14.0 followed: a chart's axis reads in the measure's own format,
 so a ratio is a percentage down the side as well as in the tooltip, and a bar
-chart can show each bar's value (ADR 054). Both came from a real install, and
-the second adds a pane option, so it starts its own short soak. What 1.0 waits
-on now is a week of real installs of 0.14.0 ([#71](https://github.com/retail-tasker/janela/issues/71)),
+chart can show each bar's value (ADR 054). 0.15.0 followed that: a category
+pane can be sorted by its measure either way or by its label, so a bottom five
+and a chart in date order can be drawn (ADR 055). 0.16.0 followed that: a time
+pane can be a running total and carry more series on two axes, and a pane can
+ignore a filter its model cannot apply (ADR 062, ADR 063). All four came from a
+real install, and the last three add a pane option and a URL parameter, so the
+soak starts again from 0.16.0. What 1.0 waits
+on now is a week of real installs of 0.16.0 ([#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

data/lib/generators/janela/mcp/mcp_generator.rb

@@ -0,0 +1,51 @@
+require "json"
+require "rails/generators"
+
+module Janela
+  module Generators
+    # Writes the server an agent reaches Janela::Tools through, and the entry
+    # MCP clients read to find it (ADR 057). Both belong to the host from then
+    # on. Janela edits nothing else: the Gemfile is told about, not changed.
+    class McpGenerator < Rails::Generators::Base
+      source_root File.expand_path("templates", __dir__)
+      desc "Writes bin/janela-mcp and a .mcp.json entry so an agent can arrange dashboards."
+
+      def write_server
+        if File.exist?(File.join(destination_root, SERVER))
+          say_status :exist, "#{SERVER} already there, left alone", :blue
+        else
+          template "janela-mcp.tt", SERVER
+          chmod SERVER, 0o755
+        end
+      end
+
+      def register_with_clients
+        path = File.join(destination_root, ".mcp.json")
+        config = File.exist?(path) ? JSON.parse(File.read(path)) : {}
+        servers = (config["mcpServers"] ||= {})
+
+        if servers.key?("janela")
+          say_status :exist, ".mcp.json already has a janela server, left alone", :blue
+        else
+          servers["janela"] = { "command" => "bundle", "args" => [ "exec", SERVER ] }
+          create_file ".mcp.json", JSON.pretty_generate(config) + "\n", force: true
+        end
+      end
+
+      def say_what_is_next
+        say
+        say %(Add gem "mcp" to your Gemfile and bundle: the server uses the official Ruby SDK, and Janela depends on no MCP library.) unless mcp_bundled?
+        say "Then open #{SERVER} and write the scope: who the agent acts for, and what that caller may read."
+        say "Until you do, every tool refuses to read. Start it with: bundle exec #{SERVER}"
+        say "Guide: docs/agents.md"
+      end
+
+      private
+        SERVER = "bin/janela-mcp".freeze
+
+        def mcp_bundled?
+          Gem.loaded_specs.key?("mcp")
+        end
+    end
+  end
+end

data/lib/generators/janela/mcp/templates/janela-mcp.tt

@@ -0,0 +1,50 @@
+#!/usr/bin/env ruby
+# The server an agent reaches Janela's tools through (ADR 053, ADR 057). Janela
+# wrote this file and it is yours now: change anything, and keep what you want.
+#
+# It speaks MCP over stdio. A client that reads .mcp.json starts it, so there
+# is nothing to run by hand. To try it: bundle exec bin/janela-mcp
+ENV["RAILS_ENV"] ||= "development"
+require_relative "../config/environment"
+
+# Removing this is a decision about who can reach real data through an agent.
+# Make it on purpose, and make it only after the scope below is written.
+abort "bin/janela-mcp runs in development only." unless Rails.env.development?
+
+require "mcp"
+
+# What may the agent read, and for whom? A request has a current user and this
+# does not, so your controller's policy_scope cannot be called from here: outside
+# a request it answers a different question and reads the wrong rows. Write the
+# answer with the caller you mean. It is given a model class and returns a
+# relation, as policy_scope does.
+#
+#   ->(model) { model.where(account: Account.find_by!(name: "Acme")) }
+#
+# Resolve who is asking inside the lambda, on every call. A value looked up once
+# when the server starts goes stale if that record is ever replaced, and the
+# agent then sees nothing without being told why.
+#
+# Until it is written, every tool refuses to read.
+SCOPE = lambda do |model|
+  raise Janela::Unscoped, "bin/janela-mcp has no scope yet. Open it and write what the agent may read for #{model.name}."
+end
+
+# Pass write: false for an agent that may look and never change anything.
+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::Server::Transports::StdioTransport.new(janela_server(write: true) { SCOPE }).open