janela 0.14.0 → 0.16.0

data/docs/decisions/057-a-host-is-told-about-the-agent-tools-and-a-generator-sets-them-up.md

@@ -0,0 +1,197 @@
+---
+Date: 2026-10-14
+Status: Accepted
+Related: ADR 010, ADR 015, ADR 032, ADR 035, ADR 053, ADR 056
+Triggers:
+  - adding an install step, a generator or a rake task that writes into a host
+  - changing what janela:doctor prints when nothing is wrong
+  - deciding how a host learns that a feature exists
+  - registering Janela::Tools with an MCP library
+  - an agent needs to change a frame's columns or gap
+  - an agent needs to reach a dashboard on a deployed host
+Topics: ai, agents, mcp, install, dx, generators, doctor, host-integration, discoverability
+---
+
+# ADR 057: A Host Is Told About the Agent Tools, and a Generator Sets Them Up
+
+## Context
+
+ADR 053 gave Janela agent tools and deliberately stopped short of helping a
+host use them. It rejected a `janela:install:mcp` task because copied files
+drift, rejected detecting a host's MCP setup because the signal does not
+distinguish anything, and added no doctor check because construction already
+raises. A host that wants the tools reads `docs/agents.md` and writes about
+ten lines.
+
+That left one thing unconsidered: **how a host learns the tools exist.** The
+guide is a document the host has to go looking for, so a host that does not
+know to look never finds out. The demo showed it. Its `/visits` dashboard was
+arranged through `Janela::Tools` by an agent over stdio, using
+`test/dummy/bin/janela-mcp`, and the maintainer's reaction to being told how it
+was done was that he had assumed a setup tool already existed, and that anyone
+using the library should not have to ask for one. Nothing in the install path,
+the doctor's output or the README's install section mentions the tools at all.
+The feature is real and, to a new host, invisible.
+
+### Measured
+
+Against the demo, 2026-10-14.
+
+**A generator in the gem is found and ships.** A file at
+`lib/generators/janela/mcp/mcp_generator.rb` is listed by
+`bin/rails generate --help` under `Janela:` and runs as
+`bin/rails generate janela:mcp`. The gemspec's `lib/**/*` glob already packages
+it. Janela has no generators today, so this would be the first.
+
+**A server file cannot borrow the host's `policy_scope`.** It is a controller
+method, and a stdio server has no request. Called on a bare controller it does
+not raise, which would be a safe failure. It answers a different question:
+
+```
+policy_scope(Janela::Frame) from inside a request:  owner is the first customer
+policy_scope(Janela::Frame) with no request:        WHERE owner_id IS NULL
+```
+
+ADR 035 found the same shape for the doctor, where a real host's
+`policy_scope` reaches for the session, which is nil outside a request. So the
+scope has to be written into the server file by the host, who knows who an
+agent acts for. `Janela::Tools.new` with no scope still raises `Janela::Unscoped`
+(ADR 053), so a generated file that leaves the scope unwritten fails loudly
+and does not read the wrong rows.
+
+**The demo's server file is the first copy of the thing.** It is 25 lines, of
+which three are the host's: who is asking, what the scope is, and which
+environment it may run in. The rest is `docs/agents.md`'s adapter, unchanged.
+
+### What was considered
+
+**Keep ADR 053 as it is and improve the guide.** Rejected. The guide is not
+the problem, finding it is. A better page nobody opens is the same failure.
+
+**A doctor finding.** Rejected as a finding. ADR 035 says a check reads what
+Janela does or says what it saw, and the doctor's contract is "what to fix".
+The tools are optional, so their absence is not something to fix, and a
+warning would be wrong for the host that has deliberately chosen not to use
+them. It also could not be silenced without teaching hosts to silence the
+doctor. See the decision for what the doctor says instead.
+
+**A `post_install_message` for the tools.** Rejected as the main route. ADR 015
+sets it only on a release a host must act on and removes it in the next, so it
+reaches a host once, at the moment it is least interested. It is used for the
+release that ships the generator and no other.
+
+**Detect the host's MCP server and register into it.** Still rejected, for
+ADR 053's reason: it edits a host's tooling on a signal that distinguishes
+nothing.
+
+**A generator that borrows the host's scope by calling `policy_scope`.**
+Rejected on the measurement above. It would silently read the wrong rows.
+
+**`mcp` as a dependency, added to the host's Gemfile by the generator.**
+Rejected. The generator prints the line to add and never edits the Gemfile,
+which keeps ADR 053's "Janela depends on no MCP library" and ADR 010's rule that
+Janela edits nothing it did not create.
+
+## Decision
+
+**A host is told the agent tools exist in the places it already looks, and a
+generator writes the server file the host then owns.**
+
+```
+bin/rails generate janela:mcp
+```
+
+It writes two things and edits nothing else:
+
+- `bin/janela-mcp`, an executable stdio server built on the official Ruby
+  SDK. It is `docs/agents.md`'s adapter with the host's three decisions left
+  as plain code to fill in. The scope is a lambda that **raises
+  `Janela::Unscoped` until the host replaces it**, so an unedited file reads
+  nothing. It refuses to run outside development, with the guard in the file
+  where the host can see it, because removing it is a decision about who can
+  reach real data and should be made on purpose.
+- An entry in `.mcp.json`, created if it is absent and merged if it is not, so
+  Claude Code and any client that reads the same file find the server.
+
+If the `mcp` gem is not in the bundle the generator says which line to add to
+the Gemfile and does not add it. If `bin/janela-mcp` already exists it is left
+alone and the generator says so.
+
+**The file is the host's from the moment it is written.** This is the case
+ADR 053 rejected, and it is accepted now for a reason that did not apply then:
+the file is the adapter itself and nothing else. It calls `Janela::Tools.all`
+and `Janela::Tools#call`, which are the public contract from 1.0, so there is
+nothing for it to drift from except a change that would already be a major
+release. The doctor does not grow a check for it.
+
+**Discovery, in the order a new host meets it:**
+
+1. **The README's install steps** gain one line after the doctor step: that
+   agents can arrange dashboards, the command, and a link to `docs/agents.md`.
+   It stays in the README permanently, since a host installing next year needs
+   it as much as one installing today.
+2. **`janela:doctor` prints a closing line, not a finding**, when
+   `bin/janela-mcp` does not exist: `Optional: let an agent arrange
+   dashboards. bin/rails generate janela:mcp (docs/agents.md).` It states what
+   it saw, which is the absence of the file. It does not change the exit
+   status, is not counted in "things to fix" and needs no silencing. It is
+   printed on a clean run too, so the host that has nothing to fix still hears
+   it, and a host that has generated the file stops hearing it.
+3. **The gem's `post_install_message`** carries it once, on the release that
+   ships the generator, and goes in the release after (ADR 015).
+4. **The generator's own output** says what to fill in and how to start the
+   server, so the first run ends with a working next step.
+
+**An agent can change a frame's columns and gap.** ADR 053 gave agents no
+frame-level tool because "a frame is found or made by the host". Arranging
+`/visits` showed that a layout is not finished without them: the demo's frame
+went from three columns to four and could only be changed from a console. One
+tool is added, and only with `write: true`:
+
+| Tool | Does |
+| --- | --- |
+| `update_frame` | Change a frame's `columns` and `gap`. Found through the host's scope like every other frame, and refused with the frame's own reason (`Columns is not included in the list`) when the value is not one Janela draws |
+
+Its inputs are the frame's own attributes and nothing else, so a `name`, an
+`owner` or a `key` is refused and not dropped, as a pane's are. A frame is
+still found or made by the host: there is no `create_frame`, and a frame's
+owner is the host's to say (ADR 033). This is a new tool, so it is a minor
+release, and its name and schema join the contract at 1.0 with the rest.
+
+**A deployed host's dashboard stays out of an agent's reach, and that is
+named, not solved.** The generated server runs in development against a local
+database, so a change made through it is not a change to a live site. Reaching
+a deployed host needs an authenticated path that only the host can provide
+(ADR 053: Janela serves no endpoint and does not know who is calling). The
+guide says so, so it is a known limit and not a surprise.
+
+## Consequences
+
+- **A new host hears about the tools without asking**, in its install steps,
+  from the doctor it was told to run, and from the generator's output. A host
+  that does not want them has nothing to silence.
+- **This is the first generator Janela ships**, and ADR 010 lists generators
+  as something that needs a decision. This is that decision, scoped to one
+  generator that writes a file and a config entry.
+- **The doctor's contract widens by one printed line.** It says something on a
+  clean run for the first time. That is accepted because the line is not a
+  finding and cannot change the exit status or the count.
+- **ADR 053 is superseded in part**: its rejection of an install task and its
+  statement that no doctor output is added. Its tool surface, its required
+  scope and its rule that Janela registers nothing on a host's behalf stand.
+- **A host that already wrote its own adapter loses nothing.** The generator
+  leaves an existing `bin/janela-mcp` alone, and the doctor line stops once it
+  exists.
+- **A scope left as written raises.** The cost is that the first run needs one
+  edit, which is the point.
+- **The write tools are five, not four.** ADR 053's table gains `update_frame`,
+  and its rule that the write tools are off until asked for applies to it.
+- **Tests first:** the generator writes both files into a scratch host and
+  leaves an existing one alone; the unedited server file raises
+  `Janela::Unscoped` rather than reading; the doctor's closing line appears
+  without the file, is absent with it, and never changes `check` or the exit
+  status; and `docs/agents.md`'s adapter and the generated file are asserted to
+  match so they cannot drift (ADR 010).
+- **What would change this decision:** a second MCP library with enough hosts
+  to want its own generator option, or the doctor line turning out to be
+  noise, in which case it moves to the README alone.

data/docs/decisions/058-the-deployed-demo-is-reached-over-ssh-and-its-visits-frame-survives-a-reset.md

@@ -0,0 +1,94 @@
+---
+Date: 2026-10-14
+Status: Accepted
+Related: ADR 053, ADR 056, ADR 057
+Triggers:
+  - an agent needs to change a dashboard on the deployed demo
+  - adding an endpoint to the demo that writes
+  - changing demo:reset, or what the demo keeps through it
+  - changing which group the mcp gem is in
+Topics: demo, agents, mcp, deployment, security, dogfooding
+---
+
+# ADR 058: The Deployed Demo Is Reached Over SSH, and Its Visits Frame Survives a Reset
+
+## Context
+
+ADR 057 left one gap named and unsolved: a server run from `bin/janela-mcp`
+changes the database of the environment it starts in, so an agent could
+arrange `/visits` locally and not on the live demo. The maintainer's reading
+was that talking to an agent should change the dashboard people see.
+
+### Measured
+
+Against the deployed demo, 2026-10-14.
+
+**The production image has no `mcp` gem.** It is built with
+`BUNDLE_WITHOUT="development test"`, and `mcp` was in the development and
+test group, so `bundle list` on the running container shows Janela and not
+`mcp`. The server could not have started there.
+
+**Production logs to stdout.** `config.logger` writes to `$stdout`, which for
+this server is the protocol stream, so a single log line would corrupt it.
+Run in production mode at debug level against a scratch database, with
+`$stdout` pointed at stderr during boot, stdout carried only valid JSON-RPC
+and every log line went to stderr.
+
+**The hourly reset deletes every frame.** `demo:reset` runs `Frame.delete_all`
+and reseeds, so a change made to "Site visits" would be gone within the hour.
+Its owner is also a customer the reset deletes and recreates under a new id.
+
+**SSH reaches the box.** `docker exec -i` into the running container is a
+clean stdio pipe with no terminal allocated.
+
+### What was considered
+
+**An authenticated HTTP endpoint on the demo.** Rejected. It would put a write
+path to a public site behind a token, which is a new surface to secure and
+rotate, for a dashboard one maintainer arranges. ADR 053 says Janela serves
+nothing and a host that wants an endpoint owns its authentication. The demo is
+a host, and it does not need one.
+
+**Letting the reset run over the frame.** Rejected. It makes a live change
+impossible to keep.
+
+## Decision
+
+**The deployed demo is reached by running the same server on the box over SSH,
+and the authentication is the SSH key.** `bin/janela-mcp` runs in production
+only when `JANELA_MCP_PRODUCTION=1` is set, which the SSH command sets and
+nothing else does. There is no endpoint, no token and no new login.
+
+**`mcp` moves out of the development and test group** so it is in the
+production bundle. It stays out of the gemspec (ADR 053).
+
+**The server points `$stdout` at stderr while Rails boots**, and gives it back
+to the transport afterwards, so production's stdout logger cannot corrupt the
+stream.
+
+**`demo:reset` keeps the visits frame.** Every other frame is still put back.
+The frame is handed to the new first customer after the reseed, because its
+owner was deleted. Page views were already left alone (ADR 056).
+
+## Consequences
+
+- **A change made through the tools reaches the live dashboard** and stays
+  there. The seeds hold the first design and the live frame is the one that
+  evolves, so the seeds no longer describe it once it has been changed.
+- **Keeping one frame broke two assumptions the demo made, found on the live
+  site an hour after the deploy.** The seeds created the original frames only
+  when there were no frames at all, and the orders page linked to whichever
+  frame had the lowest id. With the visits frame kept, the first never ran and
+  the second picked the wrong one, so the live `/dashboards` lost two frames.
+  Each frame is now guarded by its own name and the page finds its frame by
+  name. The reset test now asserts every original frame comes back, since it
+  had only checked one that happened to have its own guard.
+- **The reach is exactly the people with SSH to the box**, which is the people
+  who can already change the demo.
+- **The connection is not committed.** The SSH entry goes in a developer's own
+  local MCP config, because a contributor without access would see a server
+  that fails.
+- **The demo image carries one more gem**, with no endpoint that uses it.
+- **What would change this decision:** a second person needing to arrange the
+  demo without SSH, which is the day an authenticated endpoint is worth its
+  cost.

data/docs/decisions/059-a-host-can-tell-janelas-own-pages-that-its-layout-draws-charts.md

@@ -0,0 +1,91 @@
+---
+Date: 2026-10-14
+Status: Proposed
+Related: ADR 011, ADR 018, ADR 023, ADR 046
+Triggers:
+  - a chart pane renders as a table on one of the engine's own pages
+  - changing what the engine's frame page passes to janela_frame
+  - adding a setting that says what a host's layout loads
+  - a host gives Janela's own pages its own layout
+Topics: rendering, charts, layouts, engines, host-integration, dogfooding, settings
+---
+
+# ADR 059: A Host Can Tell Janela's Own Pages That Its Layout Draws Charts
+
+## Context
+
+The demo's Site visits dashboard had bar charts, and the page people reach
+from the Dashboards list showed them as tables. That page is the engine's own
+frame page, which passes `charts: false` to `janela_frame` because its minimal
+layout loads no chart runtime (ADR 018). The maintainer looked at it three
+times and called it trash each time. The data was right and the page was
+doing exactly what ADR 018 says, which is the trouble: a decision written for
+a host with no layout of its own was applied to a host that has one.
+
+ADR 018 closed with its own condition: "If the engine ever gains a way to
+know a host's asset setup, this decision is worth revisiting, because the
+better answer is a chart that draws everywhere."
+
+### Measured
+
+Against the live demo, 2026-10-14.
+
+**The demo gives the engine's frame page its own layout, and that layout
+loads the runtime.** `Janela::FramesController.layout` is overridden (ADR 011,
+ADR 022), the page carries the `janela--frame` Stimulus controller and has no
+console errors, and `/visits`, which renders the same frame through the host's
+own page, draws both bar charts. The only difference between the two pages is
+the `charts: false` in the engine's view.
+
+**The engine cannot tell.** Whether a layout loads Chart.js is a fact about the
+host's bundler and importmap. A layout other than Janela's own may load
+nothing, and Janela cannot read it.
+
+### What was considered
+
+**Detect a host layout and assume it draws charts.** Rejected for ADR 018's
+reason: it would guess. A host layout that loads Turbo and no Chart.js would
+get empty holes where tables were, which is the failure ADR 018 was written
+to remove.
+
+**Detect JavaScript at runtime and swap.** Rejected. The page is meant to be
+correct before any JavaScript, and a swap would flash a table first.
+
+**Always draw charts on the engine's pages.** Rejected. The default install,
+with Janela's own minimal layout, has no runtime.
+
+## Decision
+
+**A host says so, once.**
+
+```ruby
+# config/initializers/janela.rb
+Janela.charts_on_own_pages = true
+```
+
+It defaults to `false`, so a host that sets nothing renders exactly what it
+does today. When it is `true` the engine's frame page passes `charts: true`,
+and a bar or line pane draws. It is a setting and not a convention because it
+is the one thing the engine cannot see and cannot guess, which is what ADR 021
+says a setting is for. A host turns it on when it has given Janela's own pages
+a layout that registers the Stimulus controllers and loads Chart.js, and not
+before.
+
+The demo sets it, because its layout is such a layout.
+
+## Consequences
+
+- **Nothing changes for an existing host.** The default is ADR 018's behaviour.
+- **A host that sets it without the runtime gets empty chart holes** on the
+  engine's pages. The README says what the setting promises, and the doctor
+  does not check it, because what a layout loads is not something it can read
+  (ADR 035).
+- **ADR 018 is superseded in part**: the engine's frame page is no longer
+  always table-only. Its rule for a page with no runtime stands.
+- **The pane page opened directly is unchanged.** It is not given a setting
+  here, and a host that wants a chart there still uses a layout and a frame of
+  its own, as README says. This covers the frame page, which is where the
+  Dashboards list leads.
+- **What would change this decision:** the engine gaining a reliable way to
+  read a host's asset setup, at which point the setting is removed and the
+  chart simply draws.

data/docs/decisions/060-the-demo-tells-search-engines-what-it-is-and-shows-its-own-adoption.md

@@ -0,0 +1,79 @@
+---
+Date: 2026-10-14
+Status: Proposed
+Related: ADR 010, ADR 052, ADR 056
+Triggers:
+  - changing what the demo tells a search engine or a link preview
+  - adding a call from the demo to a service outside it
+  - showing a number in the demo that the demo did not count itself
+  - adding a page to the demo that should or should not be indexed
+Topics: demo, seo, marketing, privacy, dependencies, dogfooding
+---
+
+# ADR 060: The Demo Tells Search Engines What It Is, and Shows Its Own Adoption
+
+## Context
+
+The demo is Janela's front door, and a search for it is how most hosts will meet
+the gem. The maintainer wants to measure how well it is found, and the first
+thing that measuring needs is that there is something to find.
+
+### Measured
+
+Against the live demo, 2026-10-14.
+
+| Thing | State |
+| --- | --- |
+| `/robots.txt`, `/sitemap.xml` | both 404 |
+| meta description, canonical link, Open Graph tags | none on any page |
+| `lang` on the `html` element | absent |
+| `<h1>` on `/name` | none |
+| titles | one per page, though `Gallery` and `Vitral` say nothing a search result could use |
+| RubyGems | the gem answers `api/v1/gems/janela.json`: 8,315 downloads, 147 on the current version |
+| GitHub | the repository answers `api.github.com/repos/...`: 1 star |
+
+The Dashboards, snapshot and frame pages are the engine's own, and they take any
+filter as a query string, so a crawler that follows their links meets an
+unbounded number of URLs that all show the same page.
+
+## Decision
+
+**The demo says what each page is, in the head of the page, and keeps crawlers
+off the pages that are only filters.**
+
+- Every page has a `lang`, a title, a meta description, a canonical link to its
+  own path with no query string, and Open Graph and Twitter tags. A page with
+  nothing of its own to say gets the site's description rather than none.
+- A documentation page's description is its first paragraph, read from the
+  document, so it cannot drift from what ships in the gem (ADR 010).
+- `robots.txt` names the sitemap and disallows `/dashboards`, `/snapshots` and
+  `/frames`, the pages that are one dashboard under unbounded filters.
+  `sitemap.xml` lists the pages worth finding: the home page, the guides, the
+  decisions, the gallery, the name, the example and the visits page. One
+  mechanism for keeping a page out, and it is the robots file.
+
+**The footer shows RubyGems downloads and GitHub stars, fetched by the server
+and cached for an hour.** They link to the gem's page and the repository. A
+failed fetch shows the plain links as before and is not retried for five
+minutes, so a service being down costs the page nothing and the demo does not
+hammer it. The numbers are fetched, not stored: Janela owns no data store, and a
+count that is only ever read from its source cannot disagree with it.
+
+**Nothing is fetched in the test suite.** The footer is on every page, so a call
+from it would put the network in every test. It is switched on in development
+and production, and a test that wants it says so.
+
+## Consequences
+
+- **The demo makes two outbound calls**, at most one pair an hour. They carry no
+  information about a visitor, because the server makes them and not the
+  browser, so no visitor's address reaches either service.
+- **A visitor's first view after the cache expires waits for the fetch**, up to
+  the timeout. That is accepted for a demo, and the stale-while-refresh answer
+  is for when it is not.
+- **This is the baseline, not the measuring.** Search Console and page speed
+  data, a referrer on the visits recorder and the adoption numbers as stored
+  history are separate decisions, and the first of them needs `PageView` to
+  change, which ADR 056 keeps cookie free.
+- **What would change this decision:** the counts being wanted as history, which
+  is the day they stop being fetched and become rows.

data/docs/decisions/061-the-demo-speaks-brazilian-portuguese-under-a-prefix-and-the-gem-stays-english.md

@@ -0,0 +1,118 @@
+---
+Date: 2026-10-14
+Status: Proposed
+Related: ADR 023, ADR 036, ADR 054, ADR 056, ADR 060
+Triggers:
+  - adding a language to the demo, or a page that is translated
+  - generating a route helper for a page under the /pt-BR prefix
+  - deciding whether the gem should ship a second language
+  - mounting the engine inside a scope with a dynamic segment
+  - writing a month, a number or a date label in a chart
+Topics: i18n, demo, routing, seo, engines, host-integration, dogfooding
+---
+
+# ADR 061: The Demo Speaks Brazilian Portuguese Under a Prefix, and the Gem Stays English
+
+## Context
+
+Janela is the Portuguese word for window, and the demo has never said so in
+Portuguese. The maintainer wants a language picker and Brazilian Portuguese
+(`pt-BR`) as a homage to the name. Two questions decide the shape: whether the
+gem or only the demo carries the language, and where the language lives in the
+address.
+
+The README already tells a host to override Janela's words in its own locale
+file, and every string the gem shows is one `en.yml` of 63 keys under `janela.*`.
+
+### Measured
+
+Against the demo, 2026-10-14.
+
+**The language can be a prefix, including for the mounted engine.** With the
+whole demo inside `scope "(:locale)", locale: /pt-BR/` and the engine mounted
+inside it, `/pt-BR/dashboards` serves the engine's index, its frame page and its
+editor. Every `href`, `action`, `data-` URL and Turbo Frame `src` on those pages
+carries `/pt-BR/`, so cross-filtering stays in the language. `/fr/orders` is a
+404, because the constraint admits only the language we have.
+
+**A positional route argument fills the locale slot.** With an optional leading
+segment, `doc_path("agents")` generated `locale: "agents"` and then failed for
+want of a slug, on every English page, until the controller's
+`default_url_options` always carried a `locale` key, nil for English. The same
+call in a test outside a request has no controller, so the route set carries
+`locale: nil`, which an integration test merges, and the system tests' base class
+says it for their own helper object.
+
+**The engine repeated the language as a query parameter.** Its own links came out
+as `/pt-BR/dashboards/684?locale=pt-BR`: the mount point already carries the
+language in its path, so a `locale` option has nowhere to go but the query
+string. `_routes` inside `url_options` says which route set is being generated
+for, so the host drops `locale` for the engine's routes and keeps it for its own.
+
+**A month label was English only.** `Dimension::LABELS["month"]` used
+`strftime("%b %Y")`, which does not read a locale. A clicked label maps back to
+its bucket through a lookup built from the labels (`Query`), not by parsing the
+text, so a translated label cannot break a time click.
+
+**Numbers already follow the locale.** The measure reads `number.format` for its
+delimiter and `number_to_rounded` for the separator, so with Rails' own Portuguese
+data `$375.00` reads `$375,00`.
+
+### What was considered
+
+**The gem ships `pt-BR`.** Rejected for now, by the maintainer. A second language
+in the gem is upkeep for every release, and the demo adding it in its own locale
+file is the worked example of how any host does.
+
+**A cookie or the `Accept-Language` header.** Rejected. Neither is in the
+address, so a link cannot carry the language, a search engine cannot see the
+second page, and the visits page promises no cookie.
+
+**A subdomain.** Rejected. It is a second site to certify and deploy for one
+language.
+
+**Translating every page.** Rejected as a first step. The guides and decisions are
+the gem's own markdown, rendered as they ship (ADR 010), and are English.
+
+## Decision
+
+**English is the root and Brazilian Portuguese is under `/pt-BR`, one address per
+language. The gem ships English only, and the demo adds Portuguese in its own
+locale files.**
+
+- The pages translated are the home page, the orders dashboard, the visits page,
+  the menu, the footer and every string Janela's own pages show. A page that is
+  not translated is still reachable under `/pt-BR`, says so at the top, and
+  names the English page as its canonical address, so there is never a second
+  copy of English text competing with the first.
+- A translated page carries `hreflang` alternates for both languages and
+  `x-default`. The sitemap lists the translated pages in both. `robots.txt`
+  keeps the Portuguese dashboards out as it does the English ones (ADR 060).
+- The picker is a link in the menu, named in its own language, that goes to the
+  same page in the other language and keeps its filter.
+- Brazilian Portuguese for Rails' own words (month names, number formats) is the
+  `rails-i18n` gem, in the demo's Gemfile and not the gem's.
+- **The gem's month label reads the locale** when the host has month names for it,
+  and falls back to English when it has not, so a host that never set a locale
+  sees exactly what it did. This is the one change to the gem.
+- A frame is `quadro` and a pane is `painel`, the words a Brazilian reader of a
+  dashboard already uses, and not the window words (`esquadria`, `vidraça`) that
+  are prettier and mean nothing to someone looking for a chart.
+
+## Consequences
+
+- **The Portuguese is written by an assistant and has not been read by a native
+  speaker.** It should be before this is shown to people. It is a draft to be
+  corrected, and the copy is in two files, so correcting it is an edit.
+- **Every `Rails.application.routes` helper in the demo is under an optional
+  segment.** A new helper called with a positional argument outside a controller
+  needs `locale: nil` or a named argument. The route set and the system test
+  base class carry the former.
+- **A missing key fails a test.** Test runs raise on a missing translation, and a
+  test compares the Portuguese files with the English ones, because fallbacks
+  would otherwise hide a gap behind English text.
+- **The visits dashboard records Portuguese pages at their own path**, so the
+  language a visitor read is visible in the data the demo already shows.
+- **What would change this decision:** a host asking for Portuguese from the
+  gem, which is the day `config/locales/pt-BR.yml` moves from the demo into the
+  gem and `janela.pt-BR.yml` here is deleted.