janela 0.11.0 → 0.13.0

data/docs/decisions/051-a-table-can-carry-companion-columns.md

@@ -0,0 +1,160 @@
+---
+Date: 2026-09-30
+Status: Accepted
+Related: ADR 002, ADR 005, ADR 007, ADR 009, ADR 020, ADR 025, ADR 029, ADR 032, ADR 037, ADR 038, ADR 047
+Triggers:
+  - a table pane that needs a second number or a second fact beside its label
+  - a rate whose sample size decides whether to trust it
+  - adding a column to janela_panes, or a parameter to the pane URL
+  - changing the shape of what a query returns
+  - reading a column that is not the pane's dimension or measure
+Topics: dsl, query layer, measures, tables, snapshots, public-api, performance
+---
+
+# ADR 051: A Table Can Carry Companion Columns, and a Fact Is Shown Only When It Is Shared
+
+## Context
+
+#34, raised from a real install: a table pane renders exactly two cells per
+row, the label and the value, and that runs out the moment the label needs
+context to be read. A top ten of words by times right, "quero 21", is really
+asking which words *and of what kind*. The other half is worth more: a
+"worst" list by error rate cannot say whether 75% came from four reviews or
+forty, which is exactly what decides whether to act on it. #27's ratio makes
+that case more common, not less.
+
+Investigated against the demo's fixtures, and the way the issue proposes to
+resolve "the attribute on the same row" does not survive contact with data.
+
+**Nothing in the code can carry a second number today.** A table is a
+`<caption>` and a `<tbody>` of two cells with no header row, and
+`Definition#query` returns a hash of label to value from which the table, a
+chart's arrays, a ring's slices and a stored snapshot are all built. This is
+not a view change.
+
+**A dimension attribute has three obvious implementations and two are wrong.**
+Measured, with customer names and their regions, and with statuses and regions
+(`paid` orders come from two regions):
+
+| Approach | by customer, region (one each) | by status, region (`paid` has two) |
+| --- | --- | --- |
+| group by both | correct | `paid` appears twice: the two dimension grouping the issue rejected |
+| `MAX(attr)` | correct | `paid` reads `EU`, silently: an arbitrary value shown as fact |
+| `CASE WHEN MIN(attr) = MAX(attr) THEN MIN(attr) END` | correct | `paid` is blank, the others right |
+
+A bare column is not an option on a strict database. The third form is one
+expression, works on SQLite, PostgreSQL and MySQL, and is the only one that
+cannot be silently wrong: a value that differs across the rows of a group is
+not shown as though it were one thing.
+
+**A second measure is cheap.** A second grouped calculation merged on the group
+key, or one `pluck`, gives `{"paid" => [1.0, 2], ...}` for a rate and the row
+count behind it. Ordering and the limit belong to the primary measure and are
+untouched: the extras are fetched for the keys already chosen.
+
+### What was considered
+
+**Group by both.** Rejected, above: it multiplies the rows whenever the
+attribute is not determined by the label, which is not a case a declaration can
+rule out ahead of the data.
+
+**`MAX` or `MIN`.** Rejected: an arbitrary value presented as fact is this
+library's worst failure, a wrong number that looks right.
+
+**A second dimension in `by:`.** Rejected: it answers a different question and
+multiplies the rows, which the issue itself said.
+
+**A concatenated generated column, or a SQL fragment option.** Rejected: it puts
+presentation in the schema, gives up filtering on either part, and a SQL string
+in a declaration is the second query language ADR 002 refused.
+
+**Calling it `attributes`.** Rejected as a name: `attributes` is an
+`ActiveRecord::Base` method on a `Pane` row, and a column of that name would
+shadow it.
+
+## Decision
+
+**A table pane may carry up to three companions: a measure or a dimension of the
+same model, drawn as a column beside its label. A measure is its own
+aggregate, formatted as it declares, and a dimension is shown only when every
+row of the group shares one value.**
+
+```erb
+<%= janela_pane Order, :expedited_rate, by: :customer, as: :table, companions: [:orders, :region] %>
+```
+
+```
+Customer    Expedited rate   Orders   Region
+Acme        75.0%            4        APAC
+Globex      50.0%            40       EU
+```
+
+**What may be named.** A companion is a declared measure or a declared
+dimension of the pane's model, by the name the model declared it under, and
+nothing else: no column, no expression, no string that becomes SQL (ADR 025,
+ADR 032). The pane's own measure and dimension cannot be repeated, and a time
+dimension cannot be a companion, since a bucket is not a fact about a label.
+A time pane may carry measures. An unknown name is a `BadRequest` that names
+the pane's declared measures and dimensions, as an unknown filter does.
+
+**A measure companion** is a second grouped calculation merged on the group key,
+one query each, formatted by its own declaration (ADR 020, ADR 038) so a
+ratio beside a count reads `75.0%` beside `4`.
+
+**A dimension companion** is `CASE WHEN MIN(col) = MAX(col) THEN MIN(col) END` in
+one query for all of a pane's dimension companions. A group whose rows disagree
+shows nothing, not a guess. A group whose rows are all null shows nothing too.
+
+**Nothing about the primary changes.** The pane's measure orders and limits it
+(ADR 007), the label is the click target, filters and cross-filtering read as
+they always did, and the returned hash is still label to value. The
+companions are a separate answer keyed by label, so a chart, a ring and a
+stored snapshot are built exactly as before.
+
+**Only a table draws them.** A chart, a ring and a single value ignore
+companions, so a pane switched between renderers keeps them (ADR 047, ADR 050).
+
+**A table with companions has a header row.** Three unlabelled columns are
+unreadable. The `<thead>` carries the label's dimension name and each
+companion's name, and a table with no companions is exactly what it is now: no
+header row, nothing added.
+
+**Bounded at three, because each is a query.** ADR 025 bounds what one query
+may ask for; this bounds how many a pane may run. Four is a refusal that says
+so.
+
+**One vocabulary in three places,** as height does:
+
+- `Janela::Pane#companions`, a JSON array of names, validated against the
+  model's declared measures and dimensions when the row is saved (ADR 043
+  validates a default filter the same way), and a multiple select on the pane
+  form.
+- `janela_pane` and `janela_snapshot_pane` take `companions:`.
+- The pane URL carries `companions[]=orders&companions[]=region`, because the
+  server draws the pane again from that URL on every cross-filter.
+
+It is not part of the pane's identity (ADR 029).
+
+## Consequences
+
+- A rate can sit beside the count behind it, which is the more valuable half of
+  the issue, and a label can sit beside the fact that gives it its meaning.
+- **A dimension companion can be blank where the data disagrees.** That is the
+  price of never being wrong, and it is visible: a blank cell in a column that
+  should be full is a prompt to look, where a guessed value is not.
+- **A stored snapshot shows the base table only.** ADR 009 freezes the result
+  a pane had; the companions are not part of what is stored, so a snapshot pane
+  with companions renders as if it had none. Storing them is a separate change
+  to the stored shape and is left until someone needs a frozen comparison.
+- **Up to three more queries per table pane.** The rate at which a page asks
+  is the host's (ADR 048); the count each pane makes is bounded here.
+- **A migration for stored frames:** `janela_panes` gains a nullable
+  `companions` JSON column, additive, taken with `height` and `prominence`
+  in one migration step for a host using stored frames.
+- **The pane URL grammar grows by an array parameter and the theming contract by
+  a header row and the classes on the extra cells,** named in the build and
+  documented in `docs/theming.md`. Both are surface ADR 037 freezes, which is why
+  this belongs before 1.0.
+- What would change this decision: a companion that needs to be a *filter*, not
+  only a column, which is a different feature; or a frozen comparison that
+  needs the companions stored, which changes ADR 009's shape.

data/docs/decisions/052-how-the-project-is-run.md

@@ -0,0 +1,93 @@
+---
+Date: 2026-09-30
+Status: Accepted
+Related: ADR 001, ADR 010, ADR 015, ADR 025, ADR 032, ADR 037
+Triggers:
+  - deciding who may cut a release, or how a release is approved
+  - a vulnerability report, or where one should go
+  - what a contributor may expect in reply to an issue or a pull request
+  - changing the release workflow, its environment, or how the gem is published
+  - adding a process file to the repository root
+Topics: vision, releases, security, open-source, planning
+---
+
+# ADR 052: Two People Cut Releases, Reports Go Private, and Support Is Best Effort
+
+## Context
+
+#6: the repository had a licence and a code of conduct and nothing else about how
+it is run. A project meant to be used and forked by other people needs four things
+written down before it is announced: how contributions are accepted, who can cut a
+release, where a vulnerability is reported privately, and what support to expect.
+It is also the last item on the 1.0 list that is a decision and not code
+(ADR 037).
+
+Three facts were established from the repository before deciding.
+
+**A tag push publishes.** `release.yml` runs on any `v*` tag and publishes to
+RubyGems through trusted publishing, and a published version can never be reused.
+Four accounts have admin on the repository, so any of the four could publish a
+release by pushing a tag. There was no branch or tag protection.
+
+**A vulnerability had nowhere private to go.** GitHub private vulnerability
+reporting was disabled, so the only route was a public issue. The doctor exists to
+catch a host showing numbers nobody should see (ADR 035), and a project that asks
+hosts to take that seriously has to take a report of its own seriously.
+
+**A tag ruleset cannot name a person.** GitHub rulesets accept a role, a team or an
+app as an exception, not a user. Restricting `v*` tags would have meant either
+giving up on naming Jay and Vanessa or creating a team for two people. An
+environment with required reviewers can name individuals, and a workflow job
+attached to it waits for one of them.
+
+## Decision
+
+**Jay Killeen and Vanessa Soares cut releases, and the workflow enforces it.**
+`release.yml` runs its publish job in a protected `release` environment whose
+required reviewers are those two and which accepts runs only from a `v*` tag.
+Anyone with repository access can push a tag, and nothing publishes until one of
+the two approves. Self approval is allowed, because a maintainer releasing alone is
+the ordinary case and two-person sign off is not the aim: the aim is that a
+publish is a deliberate act by a named person.
+
+**A vulnerability is reported through GitHub's private advisory form.** It is
+enabled, `SECURITY.md` points at it, and it says what counts: reads outside the
+host's scope, filters that widen or burden, markup or SQL from typed text, and a
+doctor that says safe when it is not. It says plainly that authentication belongs
+to the host (ADR 032). No email address is published, so there is no inbox to
+watch, and the maintainers are notified by GitHub.
+
+**Support is best effort, with no promised response time.** Issues and pull
+requests are read when the maintainers can. There is no support contract, and
+before 1.0 the surface may move with an upgrade note each time. This is written in
+`CONTRIBUTING.md` and the README rather than left to be inferred, because a promise
+that cannot be kept (a triage cadence) is worse than a limit that is stated.
+
+**Contributions follow what ADR 001 and ADR 015 already say,** written down in one
+place. A pull request is reviewed on the merits of the diff whoever wrote it; a
+change that touches the public surface starts as an issue and, if it is a design
+choice, an ADR; a change a host can see updates the changelog and, if they must act,
+the upgrade steps. The steps for a release are in `RELEASING.md`, and the same
+steps stay in the agent skill that carries them out.
+
+## Consequences
+
+- A report of a vulnerability is private by default, and a release cannot be
+  published by an accident or by a person who is not named.
+- **Every release now needs an approval click** in the Actions tab after the tag is
+  pushed. A workflow started by hand has to be started from the tag, since the
+  environment refuses a branch.
+- **The RubyGems trusted publisher is not restricted to the environment.** Its
+  configuration on rubygems.org names the repository and workflow, and can name an
+  environment as well. Doing so would make the gate binding on RubyGems' side and
+  not only on GitHub's. That is a setting only an owner of the gem can change, and
+  it is left as a follow-up for one of the two maintainers.
+- **Branch protection is not added.** The issue did not ask for it, `main` has one
+  author of nearly every commit, and requiring reviews would stop the maintainers
+  merging their own work. It can be added if the number of contributors grows.
+- The four admin accounts are not changed. Who has repository access is a matter
+  for the owners, and the release gate holds regardless.
+- What would change this decision: a third maintainer, which is a change to the
+  reviewers list and a line in `RELEASING.md`; or an incident that shows the gate
+  is friction without benefit, which is an argument to remove the environment and
+  keep the named-releasers convention.

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

@@ -20,29 +20,29 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 
 | Topic | ADRs |
 |-------|------|
-| **Vision, scope, forkability** | 001, 010, 012, 037 |
-| **Open-source & host-decoupling** | 001, 022, 036, 041 |
-| **DSL & query layer** | 002, 006, 007, 020, 025, 038, 044 |
-| **Dependencies** | 002, 003, 004, 006, 017, 025 |
-| **Authorisation** | 002, 003, 004, 009, 017, 019, 022, 032, 033, 034, 035, 039, 040 |
-| **Performance & storage** | 007, 017, 025 |
+| **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, 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 |
-| **Layouts & views** | 011, 012, 016, 018, 020, 027, 039 |
-| **CSS & styling** | 016, 018, 023, 026, 027, 036, 042, 046 |
-| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030, 033, 039, 040, 041, 043, 044 |
+| **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 |
 | **Naming rule** | 014, 023, 036 |
-| **JavaScript delivery & charts** | 004, 006, 026, 042, 046 |
+| **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 |
-| **Snapshots & publishing** | 009, 020, 028, 033, 034 |
-| **AI agents & guidance** | 010, 015, 021 |
+| **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, 053 |
 | **The doctor & checks** | 021, 025, 032, 033, 035 |
-| **Releases & upgrades** | 015, 021, 032, 034, 035, 036, 037, 042 |
-| **Accessibility & keyboard** | 024, 042, 045, 046 |
-| **Security** | 003, 025, 028, 031, 032, 034, 035, 044 |
+| **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 |
+| **Roadmap & planning** | 001, 037, 045, 046, 052, 053 |
 
 ## Chronological
 
@@ -85,7 +85,7 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 035 | A Check Does What Janela Does, or It Says What It Saw | 2026-09-22 | Accepted |
 | 036 | Janela Publishes What a Theme May Target, and Vitral Is Only One | 2026-09-22 | Accepted |
 | 037 | 1.0 Means the Surface Stops Moving, Not That Janela Is Finished | 2026-09-23 | Accepted |
-| 038 | A Ratio Is a Measure of Its Own, Stored as a Fraction and Read as a Percentage | 2026-09-24 | Proposed |
+| 038 | A Ratio Is a Measure of Its Own, Stored as a Fraction and Read as a Percentage | 2026-09-24 | Accepted |
 | 039 | A Pane Can Hold Words, and Only Code Writes Markup | 2026-09-24 | Accepted |
 | 040 | A Host Can Fix a Frame's Filter, and No Click Removes It | 2026-09-24 | Accepted |
 | 041 | A Host Finds Its Frame by Owner and Key | 2026-09-24 | Accepted |
@@ -94,7 +94,14 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 044 | A Categorical Dimension Can Say What It Excludes, Not Only What It Includes | 2026-09-29 | Accepted |
 | 045 | Clicking a Time Bucket Filters the Frame to Its Range | 2026-09-29 | Accepted |
 | 046 | A Ring Is Server Drawn SVG, and a Palette Is Eight Fixed Colours | 2026-09-29 | Accepted |
+| 047 | A Chart's Height Is One of Five Steps, and Unset Changes Nothing | 2026-09-30 | Accepted |
+| 048 | A Frame Can Be Told to Refresh, and Janela Never Decides When | 2026-09-30 | Proposed |
+| 049 | The Null Group Is One More Value in a Selection | 2026-09-30 | Accepted |
+| 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: 047
+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