janela 0.2.0 → 0.3.0

data/docs/decisions/012-frames-and-panes-are-data.md

@@ -0,0 +1,166 @@
+---
+Date: 2026-09-15
+Status: Accepted
+Related: ADR 001, ADR 002, ADR 005, ADR 009
+Supersedes: part of ADR 001
+Triggers:
+  - changing what a frame or a pane stores, or how either is rendered
+  - adding an editing surface for dashboards
+  - anything that would let a persisted row widen what can be queried
+  - deciding whether a dashboard belongs in git
+  - adding layout vocabulary, or a layer between a frame and its panes
+  - naming anything "frame"
+Topics: frames, panes, persistence, layout, css-grid, naming, authorisation, scope
+---
+
+# ADR 012: Frames and Panes Are Data
+
+## Context
+
+ADR 001 put a drag and drop report designer out of scope and made
+dashboards code. A dashboard was an ERB page in the host application
+calling `janela_pane` helpers, which kept it in git, reviewable and
+identical across environments. Everything since has been built on that
+assumption.
+
+Dogfooding found the assumption wrong, and the reason is ownership
+rather than convenience. **The author of a dashboard is the analyst.**
+In the commercial application this gem was extracted from, the people
+who decide which panes a dashboard has, in what order and at what
+size, are the people reading it, and they cannot deploy. A composition
+that lives in ERB is a file held by the wrong owner. One install
+measured a fourteen minute round trip, edit, test, lint, CI, deploy,
+poll, to add a single pane; the cost is real, but the ownership is the
+argument.
+
+The gem was already half of the way there, and the asymmetry was
+visible once pointed at. A pane is a real URL accepting `as`,
+`granularity`, `limit` and Ransack `q[...]`, so what a pane *shows*
+changes live for anyone with the link (ADR 005, ADR 007, ADR 008).
+Only *composition* was frozen in code.
+
+## Decision
+
+**A frame is a dashboard, and it is data.** Two records, created at
+runtime, with no requirement to be declared or seeded in code first:
+
+- `Janela::Frame`, one dashboard. A name, a slug, and its grid: how
+  many columns and what gap.
+- `Janela::Pane`, one visual in one frame. Its position, how many
+  columns it spans, and what it shows: model, measure, dimension,
+  renderer, granularity, limit, and an optional title of its own.
+
+**The data definition drives the HTML.** Janela renders a frame from
+its rows and the host composes nothing:
+
+```erb
+<%= janela_frame @frame %>
+```
+
+Grid, order, spans and each pane's Turbo Frame all derive from the
+data. This is the point of the change: the library is data driven and
+the markup fits the definition, rather than the definition being
+markup.
+
+**Layout uses CSS Grid's vocabulary, not a new one.** `columns` and
+`gap` on the frame, `span` on a pane. Every Rails developer knows
+these words, they map directly onto what renders with no translation
+layer, and ADR 001 argues against inventing a glossary when a shared
+one exists.
+
+**The names come from window anatomy, one level each.** Janela is
+Portuguese for window, so the gem name already carries the metaphor
+and a class called `Window` would stutter. In a window the frame is
+the fixed outer structure, the sash is the movable assembly inside it,
+and the panes are the glass. The frame holds the panes, so `Frame` is
+the container and `Pane` is the visual. `Sash`, a band of panes within
+a frame, is deliberately **not** built: `columns` on the frame plus
+`span` on a pane already express a row of single values, a full width
+time series and a row of breakdowns, which is the dashboard shape this
+project recommends. A sash would be a layer the layout does not need,
+and it stays available if nested bands ever earn one.
+
+**"Frame" now means two things, and the rule is written down rather
+than discovered.** `Janela::Frame` is a dashboard. A `<turbo-frame>`
+is the mechanism each pane is rendered inside. They sit one level
+apart, so the frame holds frames, and the ambiguity is real: a
+`Pane belongs_to :frame` gives `pane.frame_id` as a foreign key, which
+collided with the existing `frame_id` meaning the DOM id of a pane's
+turbo frame. That method is renamed `turbo_frame_id`, which is clearer
+regardless. The rule: **frame unqualified means the dashboard; the DOM
+element is always spelled turbo frame.**
+
+**The code keeps the vocabulary; the data arranges it.** Measures and
+dimensions stay declared in the `janela` block on the model, in git. A
+`Pane` row may only name a measure and a dimension that block
+declares, because `Janela.definition!` validates against the registry
+and dimensions are themselves the Ransack allowlist (ADR 002, ADR
+003). A row therefore cannot invent a query, reach a model nobody
+exposed, or widen what is filterable. This property is worth stating
+plainly, because it is precisely what is usually wrong with database
+backed dashboards, and here it falls out of what is already built.
+
+The division of labour is then: **developers define what can be asked;
+analysts arrange what is shown.**
+
+**The runtime object is `Janela::Query`.** Today's `Janela::Pane`
+conflates the thing displayed with the query it runs. With `Pane`
+taken by the persisted record, the runtime object, a definition plus a
+measure, a dimension, filters and a renderer that resolves to a
+result, becomes `Janela::Query`. A `Pane` row builds one to do its
+work.
+
+**Three editing surfaces, in this order.** All three are wanted; they
+are not alternatives.
+
+1. **Rows.** The models are the foundation, so a host, a script or an
+   agent composes a frame with ordinary ActiveRecord. This is the
+   whole of the first increment.
+2. **Forms in the engine.** Plain Rails CRUD, no canvas: add a pane by
+   choosing from the declared vocabulary, reorder, set a span, set a
+   granularity. This is the analyst's minimum and the point at which
+   the change delivers what it is for.
+3. **A visual editor.** Accepted as the direction and deferred to its
+   own ADR, because it is mostly a JavaScript design problem and
+   should not be settled in the same breath as a schema.
+
+**Authorisation is the host's, as always.** Reading and editing go
+through Pundit policies on `Janela::Frame` and `Janela::Pane` in the
+host application, the same hook every other part of the gem uses.
+Janela ships no roles.
+
+## What this supersedes in ADR 001
+
+ADR 001 listed a drag and drop report designer under what Janela would
+deliberately not build, reasoning that dashboards defined in code stay
+small, reviewable and forkable. That reasoning holds for the
+*vocabulary*, which is why measures and dimensions stay in code. It
+does not hold for *composition*, because it assumed the developer was
+the author. Everything else in ADR 001 stands: ship the load bearing
+core, prefer one obvious way, stay decoupled from any host, keep the
+codebase small enough to fork.
+
+## Consequences
+
+- A dashboard is no longer in git. It cannot be code reviewed,
+  diffed, or guaranteed identical between environments, and a
+  production frame will drift from anything staging has. This is the
+  price of the decision and it is paid knowingly: the owner of a
+  dashboard is not a person who works in git.
+- Export and import of a frame will be wanted, to move one between
+  environments and to put one under review when it matters. Not built
+  now; noted so it is not a surprise.
+- Rendering a frame is a new surface: a helper, a grid, and a
+  stylesheet, because a grid with no CSS means nothing. The missing
+  default stylesheet (#15) and inter pane layout (#29) become part of
+  this work rather than neighbours to it.
+- Snapshots (ADR 009) name their panes explicitly today. A frame gives
+  a snapshot an obvious subject: freeze a frame, not a list. A later
+  ADR, but the shape is now clear.
+- Renaming the runtime object touches the helper, both controllers,
+  the snapshot model, a view and the tests. Mechanical, pre 1.0, and
+  invisible to hosts: `janela_pane` keeps its name, so neither
+  existing installation changes.
+- Every dashboard built so far, including the demo and both hosts, is
+  ERB calling `janela_pane`. That helper keeps working. A frame is an
+  addition, not a replacement, and nothing has to move.

data/docs/decisions/013-naming-and-addressing-frames.md

@@ -0,0 +1,119 @@
+---
+Date: 2026-09-15
+Status: Accepted
+Related: ADR 005, ADR 011, ADR 012
+Triggers:
+  - changing how a frame is addressed, or what a frame is called in a host's interface
+  - adding a slug, a friendly URL or a lookup other than the primary key
+  - adding or replacing the index of frames
+  - a frame slug or path segment colliding with the pane grammar
+Topics: routes, urls, naming, i18n, frames, defaults
+---
+
+# ADR 013: Naming and Addressing Frames
+
+## Context
+
+ADR 012 made a frame a database record. Three questions follow from
+that and none were settled there: what a host calls a frame in its own
+interface, how a frame is addressed, and how a person finds one.
+
+The first is the same question ADR 005 answered for the mount path.
+"Frame" is the code's word, taken from window anatomy; it is not a
+word an analyst would use. One host calls these insights, another
+reports, another dashboards, and the difference is business language
+rather than preference.
+
+The second has a trap. ADR 005 published the pane grammar as
+`/<mount>/:model/:measure(/:dimension)`. A frame addressed directly
+under the mount, `/insights/vamos-review`, cannot be distinguished
+from the start of a pane URL: Rails cannot tell a frame slug from a
+model route key, and the frame route would shadow every pane.
+
+## Decision
+
+**What a frame is called comes from i18n, not from configuration.**
+The class stays `Janela::Frame`, and every label the engine renders
+uses `Frame.model_name.human`, so a host renames it in its own locale
+file:
+
+```yaml
+en:
+  activerecord:
+    models:
+      janela/frame:
+        one: "Dashboard"
+        other: "Dashboards"
+```
+
+This adds no setting, uses the mechanism Rails already has, and
+composes with real translation rather than only relabelling. Janela
+ships English defaults.
+
+**Frames live under their own path segment, and that segment is the
+host's.** A single configurable value, defaulting to `dashboards`
+because that is the word most hosts want and no one should have to
+read the gem to like the default:
+
+```
+/insights/dashboards            every frame
+/insights/dashboards/3          one frame
+/insights/orders/revenue/status a pane, grammar unchanged
+```
+
+The segment removes the collision entirely, so the pane grammar from
+ADR 005 needs no constraints or disambiguation and stays exactly as
+published.
+
+**A frame is addressed by its primary key, the Rails way.**
+`resources :frames` inside the engine, looked up with
+`find(params[:id])`. No slug column, therefore no uniqueness rules, no
+reserved word list, no regeneration on rename, and no second lookup
+path to keep working.
+
+If readable URLs are wanted later, the Rails answer is to override
+`to_param` to return `"3-quarterly-review"`. Rails resolves that back
+through `to_i`, so lookups do not change and nothing has to be
+unique. That is an option for a host or a later decision here, not a
+schema.
+
+**Using `resources` is also the editing surface.** ADR 012's second
+editing surface, plain forms in the engine, is `index`, `new`, `edit`,
+`update` and `destroy` on that resource. Choosing the conventional
+route shape means the forms are the framework's defaults rather than
+something invented.
+
+**Janela ships an index, and a host may ignore it.** The mount's frame
+segment renders a grid of cards, one per frame, with its name, how
+many panes it has and when it changed. That is enough for a host to
+install the gem and navigate on the same day, which is the point.
+
+A host that wants something else writes its own page over
+`Janela::Frame.all` and never routes to ours. This is the pattern from
+ADR 011: ship a default that works, let the host replace it, add no
+configuration for the choice.
+
+**A richer browse is not this decision.** Rows grouped by category,
+horizontal scrolling and hover previews are a different size of
+feature, and a preview in particular is expensive because a thumbnail
+means rendering panes. The card grid is the default; anything more
+earns its own ADR once a host has enough frames to justify browsing
+rather than listing.
+
+## Consequences
+
+- Nothing in a host's interface says "frame" unless the host wants it
+  to, and the word in the URL is the host's too. The code keeps one
+  vocabulary and the reader keeps theirs.
+- One configuration value is added, for the path segment. It is
+  justified on the same grounds as ADR 005's mount path: it appears in
+  a URL a person reads. The noun in labels deliberately is not
+  configuration, because i18n already does it.
+- Integer ids mean a frame URL is not self describing. `to_param` is
+  the escape hatch and costs nothing to adopt later.
+- The index is a new view in the engine, so it is more surface to
+  style, which reinforces that the default stylesheet (#15) is part of
+  this body of work and not adjacent to it.
+- Frames being a conventional Rails resource means the forms surface
+  arrives largely for free, which moves ADR 012's second editing stage
+  closer than it looked.

data/docs/decisions/014-corrections-before-frames-are-built.md

@@ -0,0 +1,222 @@
+---
+Date: 2026-09-15
+Status: Accepted
+Related: ADR 001, ADR 002, ADR 005, ADR 008, ADR 009, ADR 010, ADR 011, ADR 012, ADR 013
+Supersedes: part of ADR 012, part of ADR 013
+Triggers:
+  - building frames or panes as records
+  - naming anything in the gem's public vocabulary
+  - adding a route, a layout or an index to the engine
+  - scoping or authorising a frame
+  - rendering a pane from a row rather than from URL parameters
+Topics: frames, panes, naming, routes, layouts, authorisation, tenancy, sequencing
+---
+
+# ADR 014: Corrections Before Frames Are Built
+
+## Context
+
+ADR 012 made frames and panes data and ADR 013 decided how a frame is
+named and addressed. Both were accepted within an hour of each other
+at the end of a long session. An independent review before any code
+was written found three decisions that are wrong rather than
+incomplete, and several claims that are overstated. This ADR corrects
+them, records the naming rule that was implicit, and sequences the
+build. It is the document to read before writing any of it.
+
+## Decision
+
+### A frame page renders its panes, not empty frames
+
+ADR 013 has the engine serve an index and a show page for frames. ADR
+011 has anything the engine serves render in Janela's own minimal
+layout, which deliberately loads no assets. A frame page is a grid of
+lazily loaded `turbo-frame` elements, so with no Turbo on the page
+they never fetch and **the page renders blank**. The two ADRs conflict
+and neither noticed.
+
+A frame page therefore renders each pane's content inline, inside its
+`turbo-frame`, on the first response. Cross-filtering still replaces
+frames afterwards when Turbo is present, and without Turbo the page is
+a correct static dashboard.
+
+This is better than either ADR intended, for reasons beyond the
+conflict: it removes a fan out of one request per pane on every load,
+and it is what ADR 008 already required of a dashboard, that a shared
+link be correct before any JavaScript runs. The host composed
+dashboard should do the same, which makes `loading: :lazy` on a pane an
+option rather than the default.
+
+### A frame carries an opaque owner, and is always read through a scope
+
+ADR 012 said authorisation is the host's Pundit policy on
+`Janela::Frame`. A frame has no ownership column, so a multi tenant
+host cannot write a `Scope` over it at all, and the shipped index
+would list every tenant's frames with enumerable integer ids. One of
+the two real hosts is multi tenant.
+
+`Janela::Frame belongs_to :owner, polymorphic: true, optional: true`.
+Janela never interprets the owner: it sets nothing, reads nothing from
+it, and offers no roles. It exists so a host's policy `Scope` has
+something to filter on. A single user host leaves it null.
+
+Every controller lookup goes through the host's scope rather than
+`find` on the class, so a frame belonging to another tenant is a 404
+and ids stay unguessable in effect if not in form. The same correction
+applies to the existing snapshot pane controller, which looks a
+snapshot up unscoped today.
+
+### A pane row is addressed as a row
+
+ADR 012 assumed a persisted pane could be rendered through the
+existing pane URL. It cannot, for two reasons found in the code. The
+`turbo-frame` id is derived from the query, so two rows in one frame
+with the same measure, dimension and renderer produce duplicate DOM
+ids and Turbo replaces the wrong one. And a row's own title cannot
+reach the response, because the controller builds everything from URL
+parameters.
+
+A pane row gets its own nested route, `frames/:frame_id/panes/:id`,
+identified in the DOM as `janela_pane_<id>`, built from the row. The
+ADR 005 pane grammar stays exactly as published and keeps its purpose:
+an ad hoc pane, addressable and shareable without a row existing.
+
+This also resolves a collision ADR 012 missed. The controller that
+renders a query is already `PanesController`, and the forms surface
+needs that name for CRUD. The query renderer keeps the ADR 005 URL and
+is renamed with it.
+
+### Frames sit at the mount root, and the path configuration is dropped
+
+ADR 013 gave frames their own path segment, configurable, defaulting
+to `dashboards`, and claimed this removed the collision with the pane
+grammar entirely. That claim is false. `/dashboards/3` matches the
+pane route as model `dashboards` and measure `3`, and worse, a host
+model whose route key equals the chosen segment, `Report`, `Dashboard`
+or `Insight`, has its panes shadowed by it. Those are precisely the
+words the option exists to allow.
+
+Frames live at the mount root with a numeric id constraint:
+
+```
+/insights                  every frame
+/insights/3                one frame
+/insights/orders/revenue   an ad hoc pane, grammar unchanged
+```
+
+No model route key is all digits, so nothing collides, and the mount
+path is already the host's noun by ADR 005. The configuration value
+ADR 013 added is deleted before it ships. ADR 001 prefers this.
+
+### The security claim, stated accurately
+
+ADR 012 claimed a persisted pane adds no query surface because
+dimensions are the Ransack allowlist. The registry and the fetch or
+raise lookups do hold, and a row genuinely cannot invent a query,
+reach an unexposed model or widen what is filterable. Two corrections
+to how it was stated:
+
+- Dimensions are the allowlist **only when the model has not already
+  declared its own**. Janela skips generating the allowlist if the
+  host defined `ransackable_attributes`, so in that case the surface
+  is the host's list, not Janela's. Both real hosts define their own.
+- Filter parameters are still permitted wholesale, so any Ransack
+  predicate on an allowed attribute is reachable. That is issue #8 and
+  is unchanged by frames.
+
+Rows are validated against the registry on save, not only at render:
+model, measure, dimension, renderer, granularity and limit. Otherwise
+deleting a dimension from a `janela` block silently breaks every row
+naming it, and the failure appears to a reader as a missing pane. A
+pane's title is the first analyst authored text the gem renders, and
+is escaped like any other string, never marked safe.
+
+### A pane whose model has no policy fails as one pane
+
+A frame spanning several models may include one the viewer's host has
+no policy for, which raises inside a single pane request. That pane
+renders a refusal in its own frame with a 403 rather than taking out
+the response.
+
+### Naming: uncommon but conceivable, so a host is not pigeonholed
+
+The words in the gem's vocabulary, Janela, Frame, Pane, are chosen to
+be uncommon and still conceivable. A class called `Dashboard` would
+push every host into calling the thing a dashboard; `Frame` leaves
+them free to say insight, report or scorecard through i18n while the
+gem keeps one internal vocabulary. This is the same principle as the
+mount path belonging to the host (ADR 005) and the noun coming from a
+locale file (ADR 013), and it is a rule rather than a preference: **the
+gem's own words should not become a host's product language.**
+
+The review's argument for `Dashboard`, that it removes glue, is
+therefore declined, and the glue is realigned to `Frame` instead:
+
+- `janela_dashboard do ... end` becomes `janela_frame do ... end`, and
+  gains a record form, `janela_frame @frame`. One helper, two ways to
+  supply the panes.
+- The Stimulus controller `janela--dashboard` becomes `janela--frame`,
+  and its file follows. Hosts register it by name, so this is a
+  breaking change for the two installations and belongs in the
+  changelog.
+- The helper module becomes `Janela::FramesHelper`.
+- Today's runtime `Janela::Pane` becomes `Janela::Query`, freeing
+  `Pane` for the record, as ADR 012 decided.
+
+### Sequence: four builds, not one
+
+1. **Rename only.** `Pane` to `Query`, `janela_dashboard` to
+   `janela_frame`, the Stimulus controller, the helper module. No new
+   behaviour, no records, both hosts updated for the controller name.
+2. **Records and rendering.** Migrations, `Frame` and `Pane`, the
+   opaque owner, row validations, the nested pane route, inline first
+   render, the grid and the stylesheet. A host renders a frame in its
+   own page and owns the authorisation.
+3. **The engine's own pages.** Index and show at the mount root, only
+   once 1 and 2 are settled and scoping is proven in a real host.
+4. **Forms.** The analyst's editing surface, as conventional Rails
+   CRUD on the nested resources.
+
+The visual editor keeps its own future ADR, and ADR 012's commitment
+to it is softened here to undecided: the ownership argument justifies
+records and forms, and does not by itself justify a canvas.
+
+### Documentation that is now wrong
+
+The README still lists a report designer as out of scope and says
+there is no drag and drop designer. ADR 009 states there is no
+Dashboard model. ADR 010's skill instructs agents not to build a
+report designer, and requires the skill to describe only the README's
+API. All three must be corrected as part of build 2, not after it.
+
+## Consequences
+
+- Nothing in ADR 012's core is reversed: frames and panes are still
+  data, created at runtime, and the HTML still derives from the rows.
+  What changes is how they are addressed, scoped and first rendered.
+- One configuration value is removed before shipping and none is
+  added, so the gem still has exactly one, `parent_controller`.
+- Inline first render means a frame page does one query per pane on
+  the server. At the scale a dashboard renders that is cheaper than
+  the request per pane it replaces, but it makes the ordering and
+  limit decision of ADR 007 load bearing for page speed rather than
+  only for legibility.
+- The polymorphic owner is the first column Janela adds that it does
+  not itself use. It is a hook and is documented as one.
+- Build 1 is a breaking change for two known installations with no
+  user visible benefit, which is the right moment to take it: the only
+  installations are the author's.
+- Uncommon words are collision free by construction, which is the
+  point of the rule: no host names a model `Frame` or `Pane`, so the
+  class, the CSS hook, the DOM id and the sentence "the pane is not
+  loading" are unambiguous in any application with no coordination.
+  The application this gem was extracted from already has a
+  `Dashboard` model, a `DashboardPolicy` and a `dashboards` table, so
+  the declined name would have collided in conversation there
+  permanently. Active Storage's `Blob` and Action Text's `RichText`
+  are the same choice; Blazer's `Dashboard` is the counter example.
+- The cost is a permanent translation tax on documentation. Every
+  README example, error message and line of ADR 010's skill has to
+  decide whether to speak the gem's word or the reader's, and a gloss
+  like "a frame is a dashboard" never stops being necessary. That is
+  accepted as much smaller than a name that collides in every host.

data/docs/decisions/015-how-breaking-change-is-communicated.md

@@ -0,0 +1,114 @@
+---
+Date: 2026-09-16
+Status: Accepted
+Related: ADR 001, ADR 010, ADR 014
+Triggers:
+  - making any change a host must act on
+  - cutting a release whose version's middle number changes
+  - adding a deprecation, an alias or a compatibility shim
+  - adding or changing what janela:doctor checks
+  - writing anything an agent is expected to follow
+Topics: releases, upgrades, documentation, ai, dx, deprecation
+---
+
+# ADR 015: How Breaking Change Is Communicated
+
+## Context
+
+Build 1 of ADR 014 renamed a helper, a Stimulus controller, a helper
+module, two controllers and a class. Every host has to act on it, and
+the only record is `CHANGELOG.md`, which a reader has to know to look
+for. The failures a host meets first are uninformative:
+`undefined method 'janela_dashboard'` and `uninitialized constant
+Janela::Pane` say nothing about what replaced them.
+
+The people and agents upgrading this gem are the same ones ADR 010 was
+written for. That ADR decided guidance ships inside the gem so nobody
+has to rediscover what the gem already knows. An upgrade path is
+guidance, and none has shipped. This is the first case where the
+principle has something concrete to do.
+
+A changelog is also the wrong document for the job. It records what
+changed, for a reader deciding whether to upgrade. It does not tell
+someone mid-upgrade what to do, in order, with exact before and after.
+Those are different readers and mixing them serves neither.
+
+## Decision
+
+**`UPGRADING.md` ships inside the gem.** One section per version that
+requires action, newest first, written as imperative steps with the
+exact old and new text. Not prose: something a person or an agent can
+work through and tick off. It is listed in the gemspec's files, so it
+travels with an installed gem and is readable without network access.
+
+The division of labour: `CHANGELOG.md` says what changed and why,
+`UPGRADING.md` says what to do about it, `docs/decisions/` says why
+the change was decided at all.
+
+**A breaking release sets `post_install_message`.** One or two lines
+naming the version and pointing at `UPGRADING.md`. Bundler prints it
+when the gem is updated, which makes it the only mechanism that
+reaches whoever, or whatever, ran the command at the moment they
+needed it.
+
+Used only for releases that require host action, and removed in the
+release after. A post install message on every version is noise that
+teaches people to skip it.
+
+**`rails janela:doctor` reports what a host needs to fix.** One
+command, a list of findings, exit status zero when clean. It checks
+what experience says actually breaks a host:
+
+- Stale identifiers from any previous version, for example
+  `janela--dashboard` or `janela_dashboard` in the host's markup and
+  JavaScript, or `Janela::Pane` in its Ruby.
+- Whether Janela's Stimulus controllers are registered at all, which
+  is the failure that looks like nothing happening.
+- A `through:` dimension whose associated model does not allowlist the
+  attribute, which Ransack refuses per class.
+- Whether Janela's endpoints are reachable without authentication,
+  which depends entirely on what the host's `ApplicationController`
+  does.
+- Whether the engine is mounted, and where.
+
+This is the most agent shaped surface the gem can offer: one command
+whose output is a list of actions rather than a paragraph to
+interpret. It covers install as well as upgrade, so the traps ADR 010
+listed become something a machine finds rather than something a person
+remembers.
+
+**No deprecation aliases and no compatibility shims.** A renamed
+helper is not kept alive with a warning. The codebase's posture is
+that a thing has one name, and a shim is a second name that lives
+forever because nobody dares delete it. A loud failure plus a
+findable, executable guide is better than a quiet alias, particularly
+before 1.0 where the version number already says what to expect.
+
+The exception, if one is ever wanted, is a constant that raises with a
+message naming its replacement, because that is an error rather than a
+second way to write working code. Not adopted now.
+
+**ADR 010's skill will point at all three.** When the skill ships it
+tells an agent to read `UPGRADING.md` before changing a version
+constraint and to run `janela:doctor` after, which is the loop this
+ADR exists to make possible.
+
+## Consequences
+
+- Three documents now have to stay in step on a breaking release:
+  changelog entry, upgrade section, and the doctor check that catches
+  the thing being renamed. The doctor is what keeps the other two
+  honest, because a check either finds the stale identifier or it does
+  not.
+- `janela:doctor` reads the host's source, which is the first time the
+  gem inspects an application rather than serving it. It only reads,
+  reports, and changes nothing.
+- A doctor check for authentication has to guess, since whether an
+  endpoint is public depends on the host's controller. It reports what
+  it observes and says plainly that it cannot be certain, rather than
+  asserting a system is safe.
+- Refusing aliases means an upgrade cannot be gradual within one
+  version. That is the intended cost: the guide is short because there
+  is exactly one way the code can be.
+- This ADR is itself the thing that makes 0.3.0 shippable to anyone
+  other than the author.