janela 0.6.0 → 0.8.0

data/docs/decisions/035-a-check-does-what-janela-does-or-says-what-it-saw.md

@@ -0,0 +1,262 @@
+---
+Date: 2026-09-22
+Status: Accepted
+Related: ADR 002, ADR 019, ADR 021, ADR 025, ADR 031, ADR 032, ADR 033
+Triggers:
+  - adding a check to janela:doctor, or changing what one reads
+  - a check that reports nothing for a host that has a real problem
+  - a check that reports something about code a host did not write
+  - rescuing an exception raised by a host's own code
+  - reading Janela.parent_controller anywhere
+  - assigning Janela.parent_controller outside an initializer
+Topics: tooling, configuration, authorisation, host-integration, security, releases
+---
+
+# ADR 035: A Check Does What Janela Does, or It Says What It Saw
+
+## Context
+
+Three reports arrived within a day of 0.7.0, two of them from a real host
+integration rather than from this repository (#51, #38). They read as
+three unrelated bugs in `janela:doctor` and they are one.
+
+Every failing check reads a **proxy** for the thing it reports on, and
+then words the finding as though it had checked the thing.
+
+| Check | Reads | Asserts |
+| --- | --- | --- |
+| every controller check | `Janela.parent_controller`, the setting | "Janela's controllers inherit X" |
+| `unscoped_reads` | whether a method is defined | "defines no policy_scope, so every pane will raise" |
+| `disallowed_uses` | a string anywhere under `app`, `config`, `lib` | "this file filters this model on this key" |
+| `scope_filters_by_owner?` | an exception, swallowed | "does not filter by owner" |
+
+### Measured
+
+All against the demo, plus Pundit 2.5.2 installed outside the bundle so
+it could be run rather than read. ADR 032 verified Pundit by reading, and
+that is the half of it that turned out wrong.
+
+**A Pundit host with no policy for Janela's own models.** This is the
+configuration the README treats as the common case, minus one file.
+
+```
+policy_scope defined on the host?  true
+a request (Janela.scope, the real path):
+  Pundit::NotDefinedError: unable to find scope `Janela::FramePolicy::Scope`
+the doctor's entire output:
+  WARNING (unauthenticated-endpoints): no authentication filter found
+```
+
+Every dashboard raises. The doctor says nothing about it.
+
+**A host that names its parent controller too late.** Measured at
+development boot, `config/initializers/*.rb` is safe because `to_prepare`
+runs after all of them, `config.after_initialize` is already too late,
+and within `to_prepare` it depends on registration order against anything
+else that touches the controller. The README's own layout recipe is such
+a block.
+
+```
+host named:            SecureHost (authenticated, policy_scope -> none)
+Janela actually uses:  ApplicationController
+doctor says:           WARNING ... no authentication filter found on SecureHost
+                       "Janela's controllers inherit SecureHost, so they are as public as it is"
+a pane served:         $375.00 (200)
+```
+
+That quoted sentence is false at the moment it is printed.
+
+**A predicate the host never wrote.** One planted file that does not
+mention `Order`:
+
+```
+ERROR (hardcoded-disallowed-predicates): Order does not allow status_cont
+  app/models/shipment.rb filters Order on status_cont
+ERROR (hardcoded-disallowed-predicates): WholesaleOrder does not allow status_cont
+```
+
+Twice, because #44 repeats a finding per STI class. What trips it, one
+case at a time:
+
+| Planted | Result |
+| --- | --- |
+| a ransack call on an unrelated model | 2 errors |
+| `def status_changed? = true` | nothing |
+| `def status_count = 0` | nothing |
+| `# never filter on status_cont, it is not allowed` | 2 errors |
+| `status_matches:` as a key in `config/locales/en.yml` | 2 errors |
+
+Ordinary identifiers are safe, so the predicate detection is doing real
+work and this is not a bare grep. A comment warning against the predicate
+still reports that you use it, at `error`, the loudest thing the doctor
+can say.
+
+**The worst of it, which nobody had reported.** The two owner checks call
+a host's `policy_scope` on `parent.allocate`, an instance with no
+request, and rescue everything:
+
+```
+RealisticOwnerHost     scope_filters_by_owner? -> false   raised: NameError
+SessionlessOwnerHost   scope_filters_by_owner? -> true    raised: no
+
+does frames-nobody-will-own fire?
+RealisticOwnerHost     no finding
+SessionlessOwnerHost   ... scopes frames by owner but defines no janela_frame_owner
+```
+
+`RealisticOwnerHost` differs from the other by one line: its
+`policy_scope` reaches for the signed in user through the session, which
+is what every authentication library does. On an allocated controller
+`session` is nil, the call raises `NameError`, the blanket rescue turns
+that into "does not filter by owner", and the check goes quiet.
+
+So `frames-nobody-will-own` and `snapshots-nobody-will-see` do not fire
+for any host with real authentication. The second of those shipped in
+0.7.0 yesterday, written because the case bit five times in one
+afternoon. It cannot fire for the hosts that need it.
+
+**Why this repository did not catch it.** The demo's `policy_scope` reads
+`Current.tenant`, a thread local, where a host reads the session. It is
+the #46 lesson a third time: a stand in wired differently to the
+documentation cannot catch a bug in the documentation's wiring. That is
+already a hard constraint in `/jan-orient`, and it did not extend to
+"wired differently to how hosts actually work".
+
+### The thing that makes this fixable
+
+An allocated controller can be given a request:
+
+```
+allocate, no request:                  NameError: undefined method 'session' for nil
+allocate + ActionDispatch::TestRequest, policy present:  ok, SELECT "janela_frames".*
+allocate + ActionDispatch::TestRequest, policy absent:   Pundit::NotDefinedError
+```
+
+A correctly wired host succeeds. A host missing a policy raises the same
+error its visitors get. The check can tell them apart without knowing
+that Pundit exists, which ADR 002 requires.
+
+### Options considered
+
+**Keep reading, and hedge in the prose.** Cheap, and leaves both owner
+checks dead and the Pundit gap unreported. A check that cannot fire is
+not improved by better wording.
+
+**Depend on Pundit so a check can name `Pundit::NotDefinedError`.**
+Rejected on ADR 002: authorisation here is a hook, not a dependency, and
+a doctor that knows one library's exception classes is a doctor that is
+wrong about every other library.
+
+**Build a real request through the integration stack.** Heavier than
+`ActionDispatch::TestRequest` and no more faithful. The controller never
+processes an action here; it is asked one question.
+
+**Statically resolve the receiver of a `ransack` call** so
+`disallowed_uses` can attribute a match honestly. That is a parser, for
+one advisory check, and it would still miss a call through a variable.
+
+**Remove `disallowed_uses`.** Seriously considered. It was written for
+the 0.5.0 upgrade (ADR 025) to help hosts find filters the predicate
+narrowing broke, two releases ago, and its noise is now measured. Kept,
+because a host upgrading from 0.4.x still exists and the check is
+salvageable as an observation.
+
+**Make `Janela.parent_controller=` raise when the assignment cannot take
+effect.** Chosen, below, after being weighed against a doctor check that
+names the disagreement instead.
+
+## Decision
+
+**A check does what Janela does, or it says what it saw.** Where Janela
+calls a method, the check calls the same method. Where Janela resolves a
+constant, the check resolves the same constant. Where a check cannot do
+what Janela does, it reports its observation and not a conclusion it did
+not earn.
+
+That is the rule the rest of this follows from.
+
+**A check that calls host code calls it the way a request does.** The
+controller is given an `ActionDispatch::TestRequest`, so a host's
+`policy_scope` can reach `session`, `params` and `current_user` and find
+them empty rather than absent. Empty is the honest condition: it is an
+unauthenticated visitor, which is exactly who a doctor should be asking
+about. Measured above to separate a wired host from an unwired one with
+no knowledge of the host's library.
+
+**An exception from host code is reported, never swallowed.**
+`scope_filters_by_owner?` collapses "raised" and "returned something
+unfiltered" into `false`, and both owner checks are silent as a result.
+The question becomes three-valued: filtered, not filtered, or raised. A
+raise is a finding in its own right, quoting the exception class and
+message, because Janela is about to do the same call on every request.
+
+**`unscoped_reads` calls `policy_scope` against `Janela::Frame` and
+`Janela::Snapshot`.** Those two are always present and are what the
+engine's own pages read first, so a host that cannot be asked about them
+has a broken dashboard whatever else is true. It stops testing for the
+method. **ADR 032's claim that this check is "exact: the method is
+defined or it is not, and that is the whole contract" is wrong and this
+supersedes it.** The contract is that calling it returns a relation.
+ADR 032's other claim, that a Pundit host missing a policy is not
+exposed, stands: Pundit raises rather than leaking, so no data is at
+risk and this is a diagnosis failure rather than a safety one.
+
+**Every check reads `Janela::ApplicationController.superclass`, not
+`Janela.parent_controller`.** The superclass is what Janela uses; the
+setting is what a host asked for, and the two can differ (#38). One line,
+four checks, and it removes the possibility of printing "Janela's
+controllers inherit X" about a class that is not in the chain.
+
+**`Janela.parent_controller=` raises when the assignment cannot take
+effect and names a different class.** Assigning before the controller
+loads is fine, and reassigning the value already resolved is fine, so the
+raise fires only for the case that is silently broken today. `Janela` can
+tell without forcing the autoload it is asking about, through
+`autoload?` and `const_defined?`. This is ADR 032's trade again, loud once
+at the exact wrong line rather than quiet forever, and it is why no new
+doctor check is added for #38: preventing the state is better than
+reporting it, and two mechanisms for one problem is what ADR 001 declines.
+It does not contradict ADR 032's refusal to raise at boot, which was
+about raising for a host that had done nothing wrong.
+
+**`disallowed_uses` says what it saw.** Janela never reads a host's
+source, so this check cannot do what Janela does and falls to the other
+half of the rule. It reports that a file *mentions* a key the model does
+not allow, rather than that the file *filters* that model, drops from
+error to warning, and reports once per declaration rather than once per
+inheriting class. It stays a hint to grep rather than a claim about the
+host's code.
+
+## Consequences
+
+- Two checks that could not fire for a host with real authentication
+  begin firing. Expect the first hosts to run this to see findings that
+  were always true and never printed.
+- A check now runs a host's own `policy_scope` during `janela:doctor`.
+  That is host code executing in a rake task, which it was already, but
+  deliberately rather than by accident. The contract for `policy_scope`
+  is that it returns a relation, so it reads; a host whose implementation
+  writes something has a larger problem than this check.
+- **A host assigning `Janela.parent_controller` too late goes from
+  silently ignored to an exception at boot.** Breaking, so it goes in
+  `UPGRADING.md` with the three places that are too late and the one that
+  is not (ADR 015). Most hosts assign in an initializer and see nothing.
+- `with_parent_controller` in this repository's own doctor tests works by
+  assigning after load, which is the very thing the setter now refuses.
+  Those tests have to set up their scenarios by another route, and they
+  were relying on the bug: they only worked because the checks read the
+  setting rather than the chain.
+- `disallowed_uses` dropping to warning means a host who genuinely broke
+  a filter is told less loudly. Accepted: it was error severity on
+  evidence it did not have, and a warning that is usually right beats an
+  error that is sometimes about a comment.
+- #44 is narrowed rather than closed. Reporting once per declaration
+  fixes the duplication in this one check; the rest of the model checks
+  still repeat per STI subclass.
+- The demo has to gain a host whose `policy_scope` reaches through the
+  session, because nothing else in this repository would have caught the
+  dead owner checks. That is the #46 lesson applied rather than restated.
+- What would change this decision: a host reporting that
+  `ActionDispatch::TestRequest` is not enough for their authorisation to
+  run, at which point the question is whether a check should be asking at
+  all rather than how hard it should try.

data/docs/decisions/036-janela-publishes-what-a-theme-may-target.md

@@ -0,0 +1,171 @@
+---
+Date: 2026-09-22
+Status: Accepted
+Related: ADR 011, ADR 015, ADR 016, ADR 021, ADR 023
+Triggers:
+  - adding a class, a custom property or a rule to either stylesheet
+  - deciding whether a piece of look belongs to the gem or to a theme
+  - writing a theme, or reading one somebody else wrote
+  - renaming anything a stylesheet targets
+  - adding a helper that renders markup a host will style
+Topics: styling, theming, host-integration, naming, public-api, releases
+---
+
+# ADR 036: Janela Publishes What a Theme May Target, and Vitral Is Only One
+
+## Context
+
+ADR 023 split the styling in two: `janela.css` is structure, frozen and
+boring, and `vitral.css` is taste, free to move. That was the right cut
+and it has held for the theme. It no longer describes the other file.
+
+### What `janela.css` actually contains
+
+Counted by where each name is used, in the engine's own views and in the
+demo standing in for a host:
+
+| Group | Names | Where they appear |
+| --- | --- | --- |
+| The grid scale | `janela-cols-1..12`, `janela-gap-0..8`, `janela-span-1..12` | chosen by a frame's own integers (ADR 016) |
+| Pane primitives | `janela-frame`, `janela-pane`, `janela-value`, `janela-value-label`, `janela-value-number`, `janela-chart`, `janela-empty`, `janela-error` | in a host's own pages, wherever a pane is rendered |
+| The engine's own chrome | `janela-card`, `janela-button`, `janela-crumb`, `janela-flash`, `janela-page`, `janela-form`, `janela-field`, `janela-heading`, `janela-subheading`, `janela-list`, `janela-list-row`, `janela-list-name`, `janela-actions`, `janela-exit`, `janela-hint`, `janela-muted`, `janela-danger`, `janela-errors` | only Janela's own pages: 2 to 6 engine views each, and none in the demo but `janela-form`, twice |
+
+The third group is a small UI kit for pages a host may never visit. ADR
+016 said "the class names are public API", meaning renaming one is
+breaking and belongs in `UPGRADING.md`. Applied to the third group that
+is a promise made to nobody, about markup only the engine renders, which
+makes the engine's own pages harder to change than the thing the gem is
+for.
+
+### A theme other than vitral already works
+
+`Janela.theme` is one line in the engine's layout,
+`stylesheet_link_tag Janela.theme if Janela.theme.present?`, so it
+resolves any stylesheet name against the host's own asset paths. Measured
+against Janela's own layout:
+
+```
+"vitral"         -> janela.css + vitral.css
+"application"    -> janela.css + the host's own application.css
+"no_such_theme"  -> raises, "The asset 'no_such_theme.css' was not found in the load path"
+nil              -> janela.css alone
+```
+
+So somebody else's skin needs nothing built. What it needs is to know
+what it may target, and today nothing says. A theme author reads
+`vitral.css` to find out, which makes every name vitral happens to use
+into an accidental interface, and makes the three groups above
+indistinguishable.
+
+### Four open issues are the same question
+
+`#26` a caption that cannot be hidden without losing it for screen
+readers, `#29` inter-pane layout being entirely the host's problem, `#30`
+a categorical palette, `#31` a single value pane with no typography and
+no way to say how prominent it is. Each one asks where a piece of look
+belongs, and each has been answered one at a time so far, which is how a
+split stops meaning anything: `janela.css` grew a UI kit that way,
+without anyone deciding it should.
+
+### Options considered
+
+**Leave it, and decide each issue as it comes.** What has been happening.
+It produced the drift above and gives a theme author nothing to read.
+
+**A third stylesheet**, splitting the engine's own chrome out of
+`janela.css`. Tempting and rejected on ADR 023's own consequence: a third
+file is a third thing every Sprockets host has to declare for
+precompilation, and #14 says the second one is already a rough edge. The
+problem is a missing promise, not a missing file.
+
+**Rename the chrome to mark it private**, `janela-internal-card` or
+similar. Rejected: the rename is itself the breaking change it is trying
+to make unnecessary, paid now for a benefit that is only cosmetic. Saying
+which names are the contract costs nothing and is just as clear.
+
+**Move the pane primitives into the theme**, so a host with no theme gets
+unstyled panes. Rejected: a pane has to be legible on install, which is
+ADR 016's founding reason, and #26 is the sharp case, since hiding a
+caption accessibly is correctness rather than taste and a host that never
+opts into a theme still needs it.
+
+## Decision
+
+**Janela publishes the hooks; a theme supplies the taste. What a theme
+may target is written down, and what is not written down is Janela's own
+chrome.**
+
+**Three layers, named, in two files.** No new stylesheet.
+
+- **The grid scale and the pane primitives are the contract.** These are
+  what a host's own pages contain and what a theme targets. Renaming one
+  is breaking and goes in `UPGRADING.md` with the doctor taught to find
+  the old name (ADR 015).
+- **The engine's own chrome is not the contract.** The classes only
+  Janela's own views render may change in any release. A host restyling
+  Janela's own pages is welcome to target them and should expect to
+  revisit it, which is the honest version of what was already true.
+- ADR 016's "the class names are public API" is **narrowed, not
+  superseded**: it is true of everything a host's markup contains, and
+  was never meant as a promise about the engine's breadcrumbs.
+
+**`docs/theming.md` carries the contract**, because a theme author is not
+going to read an ADR to find a class list. It names the two layers, every
+class in them, every custom property, and what a theme is expected to
+leave alone. Shipped in the gem beside the other docs.
+
+**A theme is any stylesheet the host names, and vitral is one of them.**
+Nothing more is built for this: `Janela.theme = "midnight"` already
+resolves against the host's asset paths, and a name that does not resolve
+already raises rather than failing quietly. What changes is that this is
+documented and supported rather than merely true, so a third party can
+publish a theme against a contract instead of against whatever vitral
+happens to do this month.
+
+**Where a new piece of look goes.** The rule that answers the four open
+issues without arguing each one separately:
+
+- Something a pane needs in order to be correct or legible on install is
+  a **hook**, and belongs in `janela.css` on the contract. A caption that
+  is announced but not seen is this (#26).
+- Something that is a choice about appearance is **taste**, and belongs
+  in a theme. A categorical palette is this (#30).
+- Something a host arranges is **layout**, and belongs in the grid scale
+  as an integer that selects a rule, never as a value interpolated into a
+  style attribute (ADR 016). Prominence for a single value pane is this
+  (#31), and so is inter-pane layout (#29).
+
+Where a feature has both halves, the hook ships in `janela.css` and the
+taste in the theme. A palette is the clean example: the class that marks
+which series a mark belongs to is a hook, and the colours it resolves to
+are a theme's.
+
+**Vitral stays in this repository**, and stays one theme among any
+others. It is the reference implementation of the contract, which is a
+reason to keep it here rather than to privilege it: if a rule cannot be
+written against the published names, the contract is wrong.
+
+## Consequences
+
+- A theme author has something to read, and a theme written against
+  `docs/theming.md` keeps working across releases in a way one written
+  against `vitral.css` never could.
+- The engine's own pages get easier to change, because their markup stops
+  being an interface. That is a real loosening: a host that today targets
+  `janela-card` will find it moves one day, and the doc says so rather
+  than leaving them to discover it.
+- Writing the contract down means reading every class in both files once
+  and deciding which side it is on. That is the work, and it is the point.
+- **Not decided here: whether Vitral grows to answer #29, #30 and #31.**
+  This says where each half of each of those belongs; it does not commit
+  to building them, and a component library large enough to lay out a
+  host's page is its own decision against ADR 001's preference for
+  staying small enough to fork.
+- A theme is still linked only into Janela's own layout. A host wanting
+  the look on its own pages links the stylesheet itself and uses the
+  theme's public classes, exactly as ADR 023 decided. The contract does
+  not change that asymmetry, it explains it.
+- What would change this decision: the engine's own chrome turning out to
+  be something hosts genuinely restyle, in reports rather than in
+  anticipation, at which point it has earned the promise this declines to
+  make and should be moved onto the contract deliberately.

data/docs/decisions/037-what-1-0-means.md

@@ -0,0 +1,172 @@
+---
+Date: 2026-09-23
+Status: Accepted
+Related: ADR 001, ADR 010, ADR 015, ADR 021
+Triggers:
+  - deciding whether an open issue belongs in the next release
+  - proposing a feature, or arguing that one is out of scope
+  - cutting a release and choosing the version number
+  - deciding whether a breaking change is still affordable
+  - wondering whether the project is drifting
+Topics: vision, scope, forkability, releases, roadmap, planning
+---
+
+# ADR 037: 1.0 Means the Surface Stops Moving, Not That Janela Is Finished
+
+## Context
+
+Janela has a vision and a backlog and nothing in between. ADR 001 says
+what the project is, the load-bearing 5% of a BI tool, and the README's
+Design section lists what it will never be: natural-language query, a
+warehouse, a row-level-security subsystem, a scheduling UI, an embedding
+SDK, a mobile app, paginated reports. That is a stronger statement of
+scope than most libraries manage. What neither says is what order things
+happen in, or what has to be true before a host can build on this
+without expecting the ground to move.
+
+The gap shows up in three measurements taken today.
+
+**The surface moves every release.** Counting entries marked breaking in
+`CHANGELOG.md`: 0.5.0 carried one, 0.7.0 carried two, and the unreleased
+section carries two more. Five breaking changes across four releases in
+five days, every one of them correct and every one of them announced the
+way ADR 015 requires. This is what alpha is for and there is nothing to
+apologise for in it. It also means nobody outside this repository can
+build anything on Janela yet, because the DSL, the helpers, the pane
+URLs and the class names a theme targets have all changed underneath a
+host at least once.
+
+**The declared horizon ran out.** The `Before public release` milestone
+stands at ten closed and one open. It worked, it is nearly spent, and
+nothing replaced it. Thirteen of the fourteen open issues carry no
+milestone at all.
+
+**The issue list cannot rank itself.** Eight of those issues are
+enhancements, four of them raised from a real install, and none has been
+picked up while the last four releases went to hardening. That looked
+like drift and is worth being precise about, because it was not. ADRs
+025, 032, 034 and 035 are one argument made four times: Janela refuses
+rather than guesses about scope. Bounded predicates, a refused unscoped
+read, a refused unnamed snapshot scope, and a doctor that reports what it
+actually saw. That is the most coherent stretch of work in the project.
+The problem is that the theme was never declared, so it was invisible
+while it was happening, and now that it is finished there is nothing
+declared to follow it. A flat list of fourteen issues is what a project
+looks like between themes when it has no way of saying so.
+
+Three options were considered.
+
+**A roadmap with dates or quarters** was rejected. This project's
+throughput is not predictable enough to commit to a calendar, and a
+published roadmap that slips teaches people to stop reading it. The cost
+is ongoing and lands every release; the benefit is mostly the appearance
+of planning.
+
+**Leaving it to the issue list** was rejected because that is the current
+state, and the current state is what prompted the question. Labels
+describe what an issue is. Nothing describes what it is for.
+
+**Declaring 1.0 feature-complete** against what a commercial BI tool ships
+was rejected for contradicting ADR 001 outright. Janela is not trying to
+reach parity with anything. A 1.0 defined as "the features are all there"
+has no end, because the list it is measured against is somebody else's.
+
+## Decision
+
+**1.0 means the public surface stops moving, the 5% can be read, and the
+doctor can be trusted. It does not mean Janela is finished, and it is not
+a feature count.**
+
+Three claims, each of which can be checked rather than argued about.
+
+**The public surface stops moving.** After 1.0, everything
+`docs/theming.md` lists as the contract, the measures and dimensions DSL,
+`janela_pane` and `janela_frame`, the pane URL shape and the dashboard
+filter parameters change only on a major version. Before 1.0 they may
+change in any release, with the upgrade note ADR 015 requires. This is
+the load-bearing claim and the other two exist to serve it: a surface is
+only worth freezing once it is the right shape, which is why the feature
+work below sits inside 1.0 rather than after it. Freezing an API that is
+missing a limb only guarantees the limb arrives as a breaking change
+later.
+
+**The 5% can be read.** Janela draws three renderers, `table`, `bar` and
+`line`. A part-to-whole split has to be drawn as two bars. A table pane
+carries exactly two cells per row, so a label that needs context to be
+understood cannot have any. A chart takes Chart.js's 2:1 default and a
+host cannot correct it from outside. None of these is a feature beyond
+the 5%; each is the 5% not finished, and the distinguishing test is that
+four of them were raised by someone trying to use the gem rather than by
+someone reading its source. The theme that follows "Janela refuses rather
+than guesses" is legibility: a pane a person can actually read.
+
+**The doctor can be trusted.** ADR 021 holds that a check people stop
+trusting has stopped working. Every check in `CHECKS` bar two now has a
+test that makes it fire and one that leaves it quiet.
+
+The open issues sort as follows, and this sort is the substance of the
+decision rather than an illustration of it.
+
+In 1.0: #14 (a Sprockets host serves the engine's JavaScript or is told
+it cannot), #53 (the last two untested checks), #27 (a ratio measure, so
+the refusal in #20 offers somewhere to go), #30 (doughnut and pie, and
+the categorical palette that makes them readable), #31 (a pane says how
+prominent it is), #34 (a table carries an attribute column beside its
+label), #24 (a chart's height is the host's to set), and #6 (how
+contributions are accepted, who cuts a release, where to report a
+vulnerability privately).
+
+After 1.0: #18 (drill-down on time panes, which ADR 006 excluded
+deliberately and which needs an ADR of its own before any code), #41 (a
+command palette, which the issue itself argues belongs to the demo and
+not the gem), and #45 (a cosmetic scroll drift on one demo page, where
+the issue already allows that deciding not to fix it is a legitimate
+answer).
+
+Neither, and tracked as itself: #5 is an upstream pin on ActiveSupport
+and is removed when ActiveSupport is fixed. #56 is a one-in-160 test
+flake deliberately recorded rather than chased, and is evidence, not
+work.
+
+Needing a decision rather than a place: #29 asks Janela to help arrange
+panes on a page. ADR 011 has panes not rendering in the host's layout and
+ADR 001 prefers a fork to a configuration surface, so the default answer
+is that arrangement belongs to the host and the issue closes into the
+README's out-of-scope list. That is a scope decision and gets argued on
+its own rather than settled here by omission.
+
+**The roadmap is published rather than kept in the issue tracker.**
+`docs/roadmap.md` ships in the gem and renders on the demo at
+`/docs/roadmap`, because the demo reads the gem's own markdown rather
+than restating it (ADR 010). One file is therefore the public statement,
+the page a visitor reads and the copy in the installed gem at once. The
+GitHub milestone remains the working tracker and the progress bar; it
+says which issues, while the document says what the release is for. A
+reader who has to open an issue tracker to find out where a library is
+going has been told to do the maintainer's filing.
+
+## Consequences
+
+- A breaking change is cheap now and expensive after 1.0. Anything that
+  wants to change the DSL, the helpers or the published class names
+  should be argued for before 1.0 rather than after, and the sort above
+  is deliberately biased that way.
+- An issue outside 1.0 is not rejected. It is not blocking a release,
+  which is a different and weaker statement, and the roadmap says so in
+  those words so that nobody reads the list as a refusal.
+- The eight issues in 1.0 are a commitment made in public. That is the
+  point of publishing it and also its only real cost: a roadmap on the
+  website can be held against the project in a way a milestone cannot.
+- The current release is 0.8.0 and not 1.0, which this ADR answers
+  without further argument, because it carries two breaking changes.
+- `docs/roadmap.md` has to be updated when a release lands, or it becomes
+  the stale artifact this ADR rejected dated roadmaps for being. It is
+  named in `/jan-release` for that reason.
+- The README's Design section currently says snapshots are "not built
+  yet" and they shipped in 0.7.0. Publishing a roadmap beside a stale
+  status line makes the staleness worse, so that sentence is corrected in
+  the same change.
+- What would change this decision: a real install blocked by something in
+  the after-1.0 list. The sort is a judgement about what a host needs to
+  read a dashboard, and a host saying otherwise is better evidence than
+  the judgement.

data/docs/decisions/INDEX.md

@@ -20,26 +20,28 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 
 | Topic | ADRs |
 |-------|------|
-| **Vision, scope, forkability** | 001, 010, 012 |
-| **Open-source & host-decoupling** | 001, 022 |
+| **Vision, scope, forkability** | 001, 010, 012, 037 |
+| **Open-source & host-decoupling** | 001, 022, 036 |
 | **DSL & query layer** | 002, 006, 007, 020, 025 |
 | **Dependencies** | 002, 003, 004, 006, 017, 025 |
-| **Authorisation** | 002, 003, 004, 009, 017, 019, 022 |
+| **Authorisation** | 002, 003, 004, 009, 017, 019, 022, 032, 033, 034, 035 |
 | **Performance & storage** | 007, 017, 025 |
 | **Cross-filtering & Hotwire** | 003, 004, 005, 008, 024, 025 |
 | **Layouts & views** | 011, 012, 016, 018, 020, 027 |
-| **CSS & styling** | 016, 018, 023, 026, 027 |
-| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030 |
-| **Naming rule** | 014, 023 |
+| **CSS & styling** | 016, 018, 023, 026, 027, 036 |
+| **Frames, panes & persistence** | 012, 013, 014, 019, 029, 030, 033 |
+| **Naming rule** | 014, 023, 036 |
 | **JavaScript delivery & charts** | 004, 006, 026 |
 | **Time dimensions** | 006, 025 |
 | **Routes, URLs & naming** | 005, 007, 008, 009, 011, 013, 022, 024, 025 |
-| **Snapshots & publishing** | 009, 020, 028 |
+| **Snapshots & publishing** | 009, 020, 028, 033, 034 |
 | **AI agents & guidance** | 010, 015, 021 |
-| **Releases & upgrades** | 015, 021 |
+| **The doctor & checks** | 021, 025, 032, 033, 035 |
+| **Releases & upgrades** | 015, 021, 032, 034, 035, 036, 037 |
 | **Accessibility & keyboard** | 024 |
-| **Security** | 003, 025, 028, 031 |
+| **Security** | 003, 025, 028, 031, 032, 034, 035 |
 | **Testing** | 003 |
+| **Roadmap & planning** | 001, 037 |
 
 ## Chronological
 
@@ -76,7 +78,13 @@ them when in doubt: `grep -l "Triggers:.*fork" docs/decisions/*.md`.
 | 029 | A Pane's Frame Is Identified by Who It Is, Not by What It Shows | 2026-09-18 | Accepted |
 | 030 | A Pane's src Belongs to Turbo, So a Host Talks to the Frame | 2026-09-18 | Accepted |
 | 031 | A Subclass Inherits the Dashboard Its Parent Declared | 2026-09-19 | Accepted |
+| 032 | Janela Will Not Read a Model It Cannot Scope | 2026-09-20 | Accepted |
+| 033 | A Snapshot Is Told Who Owns It | 2026-09-21 | Accepted |
+| 034 | Janela Will Not Freeze a Scope the Host Has Not Named | 2026-09-21 | Accepted |
+| 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 |
 
 ## Next number
 
-Next ADR: 032
+Next ADR: 038