From 21e85704b023662ce965c6ed98a92ed5f8cd8ad0 Mon Sep 17 00:00:00 2001
From: Stephanie Hobson <stephaniehobson@users.noreply.github.com>
Date: Thu, 8 Oct 2026 16:02:36 -0700
Subject: [PATCH 1/4] Revise execplan instructions

---
 .claude/skills/execplans/SKILL.md            |   8 +-
 .claude/skills/execplans/references/PLANS.md |  91 ++++++++-------
 AGENTS.md                                    | 110 ++++++++++---------
 CONTRIBUTING.md                              |   2 +-
 4 files changed, 115 insertions(+), 96 deletions(-)

diff --git a/.claude/skills/execplans/SKILL.md b/.claude/skills/execplans/SKILL.md
index 1b3dac0..53c2e44 100644
--- a/.claude/skills/execplans/SKILL.md
+++ b/.claude/skills/execplans/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: execplans
-description: Write and maintain an ExecPlan — a self-contained, committed Markdown design document in docs/execplans/ — for work that spans more than one session or touches several files or subsystems. Use for a refactor crossing the container/view split, a tooling or dependency migration, replacing the blocked Nightwatch e2e suite, unpicking the two ESLint configs, restoring CI, or any change whose decisions and progress must survive a context reset. Also use when resuming or revising a plan already in docs/execplans/. Invoke with /execplans.
+description: Write and maintain an ExecPlan — a self-contained, committed Markdown design document in docs/execplans/ — for work that spans more than one session or touches several files or subsystems. Use for a refactor crossing the container/view split, a tooling or dependency migration, adding CI or test coverage, #409's chart redraw path, or any change whose decisions and progress must survive a context reset. Also use when resuming or revising a plan already in docs/execplans/. Invoke with /execplans.
 ---
 
 # ExecPlans
@@ -9,8 +9,8 @@ An ExecPlan is a Markdown design document that lives on disk and carries a piece
 design through implementation. It is the durable record: someone holding only the working tree and
 the plan file can pick the work up and finish it. Write one instead of relying on the built-in
 plan/todo tools whenever the work meets the threshold below — those tools don't survive a context
-reset, and this repo's near-term work (restoring CI, unifying the two ESLint configs, replacing the
-blocked Nightwatch suite) is exactly the kind that needs to.
+reset, and this repo's near-term work (adding CI, broadening test coverage, fixing #409's chart
+redraw path) is exactly the kind that needs to.
 
 Plans in this repository go in `docs/execplans/` and are committed on the working branch. **Read
 `references/PLANS.md` in full before writing or revising one** — it is the specification, and its
@@ -44,6 +44,8 @@ Skip it for a single-file fix, a copy change, or anything a commit title already
    see the addendum's "Committing" section for the exact scope.
 6. Commit the plan on its own, before the first implementation commit. Then implement, updating
    `Progress`, `Surprises & Discoveries`, and `Decision Log` in the same commits as the work.
+   Record consequential decisions and surprises, not routine development operations — see the
+   addendum's "Record what matters, not what happened".
 7. Write `Outcomes & Retrospective` when the work lands, and commit that too.
 
 ## Resuming
diff --git a/.claude/skills/execplans/references/PLANS.md b/.claude/skills/execplans/references/PLANS.md
index d96cf8a..c196b01 100644
--- a/.claude/skills/execplans/references/PLANS.md
+++ b/.claude/skills/execplans/references/PLANS.md
@@ -1,6 +1,6 @@
 # Codex Execution Plans (ExecPlans):
 
-This document describes the requirements for an execution plan ("ExecPlan"), a design document that a coding agent can follow to deliver a working feature or system change. Treat the reader as a complete beginner to this repository: they have only the current working tree and the single ExecPlan file you provide. There is no memory of prior plans and no external context.
+This document describes the requirements for an execution plan ("ExecPlan"), a design document that a coding agent can follow to deliver a working feature or system change. Treat the reader as a beginner to this repository, but a moderately experienced developer: they have only the current working tree and the single ExecPlan file you provide.
 
 ## How to use ExecPlans and PLANS.md
 
@@ -8,7 +8,7 @@ When authoring an executable specification (ExecPlan), follow PLANS.md _to the l
 
 After you have created the executable specification (ExecPlan) the first time and have clear milestones, prompt the user to review it.
 
-When implementing an executable specification (ExecPlan), do not prompt the user for "next steps"; simply proceed to the next milestone. Keep all sections up to date, add or split entries in the list at every stopping point to affirmatively state the progress made and next steps. Resolve ambiguities autonomously, and commit frequently.
+When implementing an executable specification (ExecPlan), do not prompt the user for "next steps"; simply proceed to the next milestone. Keep all sections up to date, add or split entries in the list at every stopping point to affirmatively state the progress made and next steps. Resolve technical ambiguities autonomously, and commit frequently. Scope and policy choices are not yours to resolve: reducing what a test covers, weakening an assertion, or anything visible outside the repository goes to the user, and the answer goes in the Decision Log.
 
 When discussing an executable specification (ExecPlan), record decisions in a log in the spec for posterity; it should be unambiguously clear why any change to the specification was made. ExecPlans are living documents, and it should always be possible to restart from _only_ the ExecPlan and no other work.
 
@@ -18,12 +18,12 @@ When researching a design with challenging requirements or significant unknowns,
 
 NON-NEGOTIABLE REQUIREMENTS:
 
-* Every ExecPlan must be fully self-contained. Self-contained means that in its current form it contains all knowledge and instructions needed for a novice to succeed.
+* Every ExecPlan must be fully self-contained. Self-contained means that in its current form it contains all knowledge and instructions needed for a developer to succeed.
 * Every ExecPlan is a living document. Contributors are required to revise it as progress is made, as discoveries occur, and as design decisions are finalized. Each revision must remain fully self-contained.
-* Every ExecPlan must enable a complete novice to implement the feature end-to-end without prior knowledge of this repo.
+* Every ExecPlan must enable a developer to implement the feature end-to-end without prior knowledge of this repo.
 * Every milestone must assess whether its own changes leave any documentation or code comment stale, and update it as part of that milestone — never deferred to a separate final step. See "Milestones" below.
 * Every ExecPlan must produce a demonstrably working behavior, not merely code changes to "meet a definition".
-* Every ExecPlan must define every term of art in plain language or do not use it.
+* Every ExecPlan must define every term specific to this repository, or specialist enough that a competent web developer might not know it, in plain language — or not use it.
 
 Purpose and intent come first. Begin by explaining, in a few sentences, why the work matters from a user's perspective: what someone can do after this change that they could not do before, and how to see it working. Then guide the reader through the exact steps to achieve that outcome, including what to edit, what to run, and what they should observe.
 
@@ -35,27 +35,27 @@ Format and envelope are simple and strict. Each ExecPlan must be one single fenc
 
 When writing an ExecPlan to a Markdown (.md) file where the content of the file *is only* the single ExecPlan, you should omit the triple backticks.
 
-Write in plain prose. Prefer sentences over lists. Avoid checklists, tables, and long enumerations unless brevity would obscure meaning. Checklists are permitted only in the `Progress` section, where they are mandatory. Narrative sections must remain prose-first.
+Write in plain prose. Prefer sentences over lists. Avoid checklists, tables, and long enumerations unless brevity would obscure meaning. Checklists are permitted only in the `Progress` section, where they are mandatory. Steps the reader must follow in order, in `Plan of Work` and `Concrete Steps`, are numbered lists. Purpose, Context, and the Decision Log remain prose-first.
 
 ## Guidelines
 
-Self-containment and plain language are paramount. If you introduce a phrase that is not ordinary English ("daemon", "middleware", "RPC gateway", "filter graph"), define it immediately and remind the reader how it manifests in this repository (for example, by naming the files or commands where it appears). Do not say "as defined previously" or "according to the architecture doc." Include the needed explanation here, even if you repeat yourself.
+Self-containment and plain language are paramount. Assume the reader knows web development generally — npm scripts, React, CI, git — and define what is particular to this repository ("the container/view split", "react-refetch's `connect()`", "`flagForUpdate`", "the gitignored compiled CSS") the first time it appears, naming the files or commands where it shows up. Define each term once, in `Context and Orientation`, then use it. Do not say "according to the architecture doc"; put the needed explanation in the plan.
 
 Avoid common failure modes. Do not rely on undefined jargon. Do not describe "the letter of a feature" so narrowly that the resulting code compiles but does nothing meaningful. Do not outsource key decisions to the reader. When ambiguity exists, resolve it in the plan itself and explain why you chose that path. Err on the side of over-explaining user-visible effects and under-specifying incidental implementation details.
 
 Anchor the plan with observable outcomes. State what the user can do after implementation, the commands to run, and the outputs they should see. Acceptance should be phrased as behavior a human can verify ("after starting the server, navigating to [http://localhost:8080/health](http://localhost:8080/health) returns HTTP 200 with body OK") rather than internal attributes ("added a HealthCheck struct"). If a change is internal, explain how its impact can still be demonstrated (for example, by running tests that fail before and pass after, and by showing a scenario that uses the new behavior).
 
-Specify repository context explicitly. Name files with full repository-relative paths, name functions and modules precisely, and describe where new files should be created. If touching multiple areas, include a short orientation paragraph that explains how those parts fit together so a novice can navigate confidently. When running commands, show the working directory and exact command line. When outcomes depend on environment, state the assumptions and provide alternatives when reasonable.
+Specify repository context explicitly. Name files with full repository-relative paths, name functions and modules precisely, and describe where new files should be created. If touching multiple areas, include a short orientation paragraph that explains how those parts fit together so a newcomer can navigate confidently. When running commands, show the working directory and exact command line. When outcomes depend on environment, state the assumptions and provide alternatives when reasonable.
 
 Be idempotent and safe. Write the steps so they can be run multiple times without causing damage or drift. If a step can fail halfway, include how to retry or adapt. If a migration or destructive operation is necessary, spell out backups or safe fallbacks. Prefer additive, testable changes that can be validated as you go.
 
-Validation is not optional. Include instructions to run tests, to start the system if applicable, and to observe it doing something useful. Describe comprehensive testing for any new features or capabilities. Include expected outputs and error messages so a novice can tell success from failure. Where possible, show how to prove that the change is effective beyond compilation (for example, through a small end-to-end scenario, a CLI invocation, or an HTTP request/response transcript). State the exact test commands appropriate to the project’s toolchain and how to interpret their results.
+Validation is not optional. Include instructions to run tests, to start the system if applicable, and to observe it doing something useful. Describe comprehensive testing for any new features or capabilities. Include expected outputs and error messages so the reader can tell success from failure. Where possible, show how to prove that the change is effective beyond compilation (for example, through a small end-to-end scenario, a CLI invocation, or an HTTP request/response transcript). State the exact test commands appropriate to the project’s toolchain and how to interpret their results.
 
 Capture evidence. When your steps produce terminal output, short diffs, or logs, include them inside the single fenced block as indented examples. Keep them concise and focused on what proves success. If you need to include a patch, prefer file-scoped diffs or small excerpts that a reader can recreate by following your instructions rather than pasting large blobs.
 
 ## Milestones
 
-Milestones are narrative, not bureaucracy. If you break the work into milestones, introduce each with a brief paragraph that describes the scope, what will exist at the end of the milestone that did not exist before, the commands to run, the acceptance you expect to observe, and whether that milestone's own changes leave any documentation or code comment stale — update it within the same milestone, or state plainly that nothing needed updating. Keep it readable as a story: goal, work, result, proof. Progress and milestones are distinct: milestones tell the story, progress tracks granular work. Both must exist. Never abbreviate a milestone merely for the sake of brevity, do not leave out details that could be crucial to a future implementation.
+Milestones are narrative, not bureaucracy. If you break the work into milestones, introduce each with a brief paragraph that describes the scope, what will exist at the end of the milestone that did not exist before, the commands to run, the acceptance you expect to observe, and whether that milestone's own changes leave any documentation or code comment stale — update it within the same milestone, or state plainly that nothing needed updating. Keep it readable as a story: goal, work, result, proof. Progress and milestones are distinct: milestones tell the story, progress tracks granular work. Both must exist. Include what someone needs to carry out and check the milestone; leave out what they could work out from the code or `git log`.
 
 Each milestone must be independently verifiable and incrementally implement the overall goal of the execution plan.
 
@@ -116,7 +116,7 @@ Prefer additive code changes followed by subtractions that keep tests passing. P
 
     ## Context and Orientation
 
-    Describe the current state relevant to this task as if the reader knows nothing. Name the key files and modules by full path. Define any non-obvious term you will use. Do not refer to prior plans.
+    Describe the current state relevant to this task for someone new to this repository. Name the key files and modules by full path. Define any repository-specific term you will use. If this work builds on a checked-in ExecPlan, cite it by path and summarize only what this plan relies on.
 
     ## Plan of Work
 
@@ -148,18 +148,21 @@ Prefer additive code changes followed by subtractions that keep tests passing. P
             fn plan(&self, observed: &Observed) -> Vec<Action>;
         }
 
-If you follow the guidance above, a single, stateless agent -- or a human novice -- can read your ExecPlan from top to bottom and produce a working, observable result. That is the bar: SELF-CONTAINED, SELF-SUFFICIENT, NOVICE-GUIDING, OUTCOME-FOCUSED.
+If you follow the guidance above, a single, stateless agent -- or a developer new to this repository -- can read your ExecPlan from top to bottom and produce a working, observable result. That is the bar: SELF-CONTAINED, SELF-SUFFICIENT, NEWCOMER-GUIDING, OUTCOME-FOCUSED.
 
-When you revise a plan, you must ensure your changes are comprehensively reflected across all sections, including the living document sections, and you must write a note at the bottom of the plan describing the change and the reason why. ExecPlans must describe not just the what but the why for almost everything.
+When you revise a plan, you must ensure your changes are comprehensively reflected across all sections, including the living document sections. When a revision changes the approach or scope, write a note at the bottom of the plan describing the change and the reason why; bookkeeping fixes don't need one. ExecPlans must describe not just the what but the why for almost everything.
 
 ---
 
 # Ensemble addendum
 
 Everything above is the upstream ExecPlan specification, published by OpenAI at
-<https://cookbook.openai.com/articles/codex_exec_plans/>, reproduced verbatim. This section is
-local to `mozilla/ensemble` and **overrides the text above wherever the two disagree.** The
-repository's own conventions are in `AGENTS.md` at the repository root; read that too.
+<https://cookbook.openai.com/articles/codex_exec_plans/>, adapted for this repository: the reader
+is pitched at a competent developer who is new to this repository rather than a complete novice,
+and a plan may cite a checked-in ExecPlan instead of restating it. This section is local to
+`mozilla/ensemble` and **overrides the text above wherever the two disagree.** The repository's own
+conventions are in `AGENTS.md` at the repository root; read that too. Plans follow its "Writing for
+people" section.
 
 ## Where plans live
 
@@ -193,32 +196,36 @@ Do not paste a plan into a chat message. Summarize it and name the file.
 `Concrete Steps` and `Validation and Acceptance` must name commands that run in this repository
 today. These do:
 
-    npm install --ignore-scripts                              # plain `npm install` fails on Apple Silicon
-    npm run build:css                                         # required on a fresh clone; the CSS imports are gitignored
-    npm run lint                                               # currently broken here — see below; still the command to run and report on
-    npm run test:jest
-    NODE_OPTIONS=--openssl-legacy-provider npm run build:app  # CRA lints .jsx here
-
-A plan that changes application code validates with **both** `npm run lint` and `build:app` where
-lint is runnable — the two linters cover disjoint file sets, so a green run of either proves nothing
-about the other.
-
-**`npm run lint` currently fails outright** in a fresh install: the installed ESLint is v9.39.5, not
-the v6 that `AGENTS.md` describes, and `lint:js-extra`'s eslintrc-format config
-(`.eslintrc.extra.js`) is not valid under ESLint's flat-config system (`A config object is using the
-"env" key, which is not supported in flat config system`). Do not treat `AGENTS.md`'s "confirmed
-clean, no flags" as still true. A plan should run the command, report the actual result, and not
-claim a pass it did not observe. Fixing this is its own piece of work, not something to fold
-silently into an unrelated plan.
-
-**Never write `npm test`, `test:nightwatch:dev`, or any other Nightwatch command into a plan.**
-`npm test` includes the Nightwatch leg, and the e2e suite cannot run at all — `chromedriver@84` does
-not install on current hardware. A plan whose acceptance depends on Nightwatch is not executable. If
-e2e coverage is the point of the work, say so in `Interfaces and Dependencies` and make unblocking
-it an explicit milestone with its own acceptance.
-
-State the expected result, not just the command: "`npm run test:jest` — 2 suites, both passing"
-beats "run the tests".
+    npm ci
+    npm run build:css         # required before Vitest on a fresh clone; the compiled CSS is gitignored
+    npm run lint              # ESLint flat config (.js and .jsx) plus stylint
+    npm run test:jest         # Vitest
+    npm run test:playwright   # Playwright, against the Vite dev server and live data.firefox.com
+    npm run build             # Vite production build plus version.json
+    npm test                  # lint, then Vitest, then Playwright
+
+The Playwright dashboard specs assert against live production data, so a failure there can come
+from upstream data changing rather than from the commit. Re-run once before investigating, and say
+which it was.
+
+`AGENTS.md`'s toolchain description still predates the move to Vite; where it disagrees with the
+commands above, these win. Run each command and report the actual result; never claim a pass you
+did not observe. State the expected result, not just the command: "`npm run test:jest` — 2 files, 4
+tests passing" beats "run the tests".
+
+## Record what matters, not what happened
+
+The living sections are for the next person to make the next decision, not a log of the session.
+
+* `Progress` records milestone-level state: what is done, what is partly done, what is next.
+* `Decision Log` records choices someone might otherwise undo, and why they were made.
+* `Surprises & Discoveries` records facts that cost time to find and would cost the next person the
+  same.
+
+Leave out routine operations: pushes, rebases, force-pushes, resetting local branches, changed
+commit SHAs, CI re-runs, and the steps of reading the issue or the docs. `git log` and the pull
+request already hold those. When a later finding shows an earlier Surprise was wrong, replace the
+earlier entry rather than adding a correction beneath it.
 
 ## Committing
 
diff --git a/AGENTS.md b/AGENTS.md
index 47a9f47..8f2f33f 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,7 +2,7 @@
 
 ## Project Structure & Module Organization
 
-`ensemble` (v1.2.1, `private: true`, MPL-2.0, `git@github.com:mozilla/ensemble.git`) is the React app behind <https://data.firefox.com/> — the **Firefox Public Data Report**. It is a **pure client-side create-react-app SPA and it contains no data of its own.** Every metric is fetched at runtime from **[ensemble-transposer](https://github.com/mozilla/ensemble-transposer)** (separate repo), which reformats Mozilla's public telemetry and serves JSON from the same `data.firefox.com` domain. If a number on the site looks wrong, the bug is usually not here.
+`ensemble` (v1.2.1, `private: true`, MPL-2.0, `git@github.com:mozilla/ensemble.git`) is the React app behind <https://data.firefox.com/> — the **Firefox Public Data Report**. It is a **pure client-side React 16 SPA, built with Vite, and it contains no data of its own.** Every metric is fetched at runtime from **[ensemble-transposer](https://github.com/mozilla/ensemble-transposer)** (separate repo), which reformats Mozilla's public telemetry and serves JSON from the same `data.firefox.com` domain. If a number on the site looks wrong, the bug is usually not here.
 
 **`src/config.json` is the spine.** Two arrays, and almost every structural change starts by editing one of them:
 
@@ -29,8 +29,8 @@ Metric `description` strings are rendered as inline Markdown through `markdown-i
 src/
 ├── index.jsx                    entry: ReactDOM.render + BrowserRouter
 ├── config.json                  the route/dashboard table + next-button flow
-├── registerServiceWorker.js     CRA helper; only unregister() is called (SW deliberately off)
-├── setupTests.js                enzyme adapter; puts React and shallow on global
+├── registerServiceWorker.js     create-react-app leftover; only unregister() is called (SW deliberately off)
+├── setupTests.js                Vitest setup: enzyme adapter; puts React and shallow on global
 ├── components/
 │   ├── containers/              6 stateful/data-fetching .jsx
 │   ├── decorators/              withTracker.jsx (react-ga), withNextButton.jsx
@@ -40,61 +40,62 @@ src/
 │       ├── fonts/FiraSans/      8 weights/styles of webfonts
 │       └── img/                 3 assets
 ├── lib/
-│   ├── lazyLoad.jsx             react-loadable wrapper (spinner + error fallback)
+│   ├── lazyLoad.jsx             React.lazy wrapper
+│   ├── LazyBoundary.jsx         error boundary + spinner for lazy-loaded components
 │   └── utils.js                 bumpSort, isFloat, prettifyNumber, getPageTitle
 └── tests/
-    ├── jest/                    2 unit tests
-    └── nightwatch/              13 e2e specs (.js, CommonJS), incl. dashboards/
+    └── jest/                    2 unit test files, run by Vitest (the directory name predates Vitest)
+tests/playwright/
+├── specs/                       e2e specs (.spec.js, CommonJS), incl. dashboards/
+└── utils.js                     shared helpers: linkWorks, linksWork, flagForUpdate, metricTitleIsCorrect
 ```
 
-There is no `pages/`, `store/`, `hooks/`, `api/`, `locales/`, or `data/`. `public/` is CRA's checked-in static template (`index.html` with `%PUBLIC_URL%` placeholders and a hardcoded `og:image`, `manifest.json`, `contribute.json`, a Search Console verification file, favicons). `build/` is gitignored output. Routes are exactly `/`, `/contact`, `/dashboard/<key>`, and a catch-all `NotFound`.
+There is no `pages/`, `store/`, `hooks/`, `api/`, `locales/`, or `data/`. `index.html` at the repository root is Vite's entry point (with a hardcoded `og:image` and the `<noscript>` message). `public/` holds static files copied as-is: `manifest.json`, `contribute.json`, a Search Console verification file, and `img/`. `build/` is gitignored output. `docs/architecture/` describes the frontend and the data pipeline. Routes are exactly `/`, `/contact`, `/dashboard/<key>`, and a catch-all `NotFound`.
 
 ## Current state: read this before estimating anything
 
-MozMEAO is taking this repo over. 810 commits — 515 in 2018, 92 in 2020, **nothing in 2021–2024**, three in 2025. Last commit `f655559`, 2025-05-07. Assume nothing has been exercised recently.
+MozMEAO is taking this repo over. Before that work started there were 810 commits — 515 in 2018, 92 in 2020, **nothing in 2021–2024**, three in 2025, the last `f655559` on 2025-05-07. The toolchain has since been replaced (#441): create-react-app, Jest and Nightwatch gave way to Vite, Vitest and Playwright, and two ESLint configs became one. Code outside the toolchain has barely been exercised since 2020.
 
 - **No CI/CD of any kind exists.** No `.github/`, `.circleci/`, `Dockerfile`, `docker-compose`, `Jenkinsfile`. This is not a quirk of your clone — it was all deliberately removed: CircleCI disabled 2018-02-22 (`433a465`), Docker/Dockerflow removed 2018-08-23 (`d3bb561`), `.github/dependabot.yml` deleted 2020-07-29 (`7c7006f`, "Disable non-security updates from Dependabot"). Issue #79 ("enable CI") is still open.
-- **The deploy is a static build on Google Cloud Storage** (confirmed by `x-goog-*` headers on the live site). `https://data.firefox.com/version.json` reports `1.2.1` / commit `f655559`, so **the deployed site matches current `main`**. The mechanism that pushes `build/` to GCS is **not in this repo and is currently unknown** — finding and documenting it is takeover work, not something to guess at.
-- **`npm install` fails outright on an Apple Silicon (arm64) Mac.** Confirmed: `chromedriver@84.0.1`'s postinstall exits with `Only Mac 64 bits supported` and takes the whole install down with it. Use `npm install --ignore-scripts` to get a working `node_modules` (you lose the chromedriver binary, which you can't use anyway — see the Nightwatch bullet below). This is a harder failure than "chromedriver's download URL changed"; it doesn't even try to download on this architecture.
-- **Confirmed on Node v24.19.0:** `npm run build:app` (and therefore `npm run build`) fails with `ERR_OSSL_EVP_UNSUPPORTED` — webpack 4's chunk hashing uses MD4, which OpenSSL 3 (Node ≥17) rejects — and succeeds once prefixed with `NODE_OPTIONS=--openssl-legacy-provider`. `npm start` compiles through the same webpack pipeline, so expect to need the same prefix. **`npm run lint` and `npm run test:jest` both pass clean with no flag at all** — Jest never invokes webpack, so it never hits the MD4 path. The repo's only Node signal is `engines: node >=8`; there is **no `.nvmrc`**, and historical CI pinned Node 8.
-- **`npm install` on npm ≥7 rewrites `package-lock.json` from lockfileVersion 1 to 3.** Confirmed: a ~22,000-line diff. Revert it after installing; don't let it ride along in an unrelated commit.
-- **Nightwatch cannot run at all right now.** Its `chromedriver@84.0.1` dependency doesn't install (see above), so there is no chromedriver binary in `node_modules/.bin` to point Nightwatch at. Even setting that aside, Chrome 84 is mid-2020 and chromedriver must major-version-match the installed Chrome. Treat the whole e2e suite as blocked until this is deliberately fixed.
-- **A fresh clone will not render styles until you compile Stylus.** `src/components/views/css/*` is gitignored and every component does a side-effect `import './css/Foo.css';` — run `npm run build:css` (confirmed working, no flags needed) or the app fails to resolve those imports.
+- **The deploy is a static build on Google Cloud Storage** (confirmed by `x-goog-*` headers on the live site). `https://data.firefox.com/version.json` reports `1.2.1` / commit `f655559`, so **the deployed site predates the Vite toolchain on `main`**; nothing built by Vite has shipped yet. The mechanism that pushes `build/` to GCS is **not in this repo and is currently unknown** — finding and documenting it is takeover work, not something to guess at.
+- **Node 24.** `.nvmrc` holds `24` and `engines` requires `^24.15.0`. A plain `npm install` works with no flags.
+- **A fresh clone will not render styles until you compile Stylus.** `src/components/views/css/*` is gitignored and every component does a side-effect `import './css/Foo.css';` — run `npm run build:css` or the app, and Vitest, fail to resolve those imports. `npm start` compiles it for you.
 - **Headline known bug: issue #409** — the hardware dashboard takes >10 s to re-render on resize/zoom and can trigger Firefox's slow-script dialog. Most user-visible defect; lives in the d3/metrics-graphics redraw path (`views/SummaryMetric.jsx`, `containers/ChartContainer.jsx`, `views/Chart.jsx`).
-- ~40 open issues, oldest from 2018. Other notables: #313 (`MetricOverviewContainer` does not reject when metric data 404s — cited in an inline comment there), #395 (replace `request`), #333 (replace `@babel/polyfill`), #245 (React code-splitting), #46 (localize content). The remote also carries ~35 stale `dependabot/npm_and_yarn/*` branches and three `%archive-*` branches.
-- Upstream data is **live and current** — transposer `dates` arrays are sorted newest-first and currently run to 2026-08-31. The app is unmaintained; the data is not.
+- About 30 open issues, oldest from 2018. Other notables: #313 (`MetricOverviewContainer` does not reject when metric data 404s — cited in an inline comment there), #245 (React code-splitting), #46 (localize content). #333 (replace `@babel/polyfill`) is still open, but the polyfill was removed in #441. The remote also carries about 30 stale `dependabot/npm_and_yarn/*` branches and three `%archive-*` branches.
+- Upstream data is **live and current** — transposer `dates` arrays are sorted newest-first and are updated weekly. The app is unmaintained; the data is not.
 
 ## Build, Test, and Development Commands
 
+`CONTRIBUTING.md` is the fuller reference for these.
+
 ```bash
-npm install --ignore-scripts         # plain `npm install` fails on Apple Silicon; see Current State
-                                      # expect package-lock.json to be rewritten v1 -> v3; revert it after
+npm install
+npx playwright install chromium      # one-time browser download; needed before test:playwright
 
-NODE_OPTIONS=--openssl-legacy-provider npm start
-                                      # npm-run-all --parallel watch:css watch:app -> CRA dev server :3000
-                                      # .env sets BROWSER=firefox, so this opens Firefox
-npm run build:css                    # one-shot Stylus compile; confirmed working, no flags needed
+npm start                            # npm-run-all --parallel watch:css watch:app -> Vite dev server :3000
+npm run build:css                    # one-shot Stylus compile
 
-npm run lint                         # lint:js-extra (standalone ESLint) + lint:styl (stylint); confirmed clean, no flags
-npm run test:jest                    # CI=true react-scripts test (Jest + enzyme, 2 files); confirmed passing, no flags
-npm test                             # lint -> test:jest -> test:nightwatch:dev; the Nightwatch leg cannot run today
+npm run lint                         # lint:js (flat-config ESLint, .js and .jsx) + lint:styl (stylint)
+npm run test:jest                    # vitest run (Enzyme, 2 files)
+npm run test:playwright              # playwright test; starts the dev server itself if :3000 is free
+npm test                             # lint -> test:jest -> test:playwright
 
-NODE_OPTIONS=--openssl-legacy-provider npm run build:app     # confirmed required on Node >=17; fails with ERR_OSSL_EVP_UNSUPPORTED otherwise
+npm run build:app                    # vite build
 npm run build:version.json           # writes build/version.json; must run after build:app, needs git on PATH
-npm run size                         # source-map-explorer on build/static/js/main.* (needs a prior build)
+npm run size                         # source-map-explorer on build/assets/index-*.js (needs a prior build)
 ```
 
-Run one Jest file by passing a path through: `CI=true npx react-scripts test src/tests/jest/Dashboard.test.jsx` (confirmed working).
+Run one Vitest file: `npx vitest run src/tests/jest/Dashboard.test.jsx`. Run one Playwright spec: `npx playwright test contact.spec.js`.
 
-**Environment:** `.env` **is checked into git** and holds only public build-time config — `BROWSER=firefox`, `NODE_ENV=development`, `REACT_APP_GA_TRACKING_ID='UA-00000000-0'` (placeholder), `REACT_APP_SITE_TITLE='Firefox Public Data Report'`, `REACT_APP_VALUE_DECIMAL_PLACES=3`. Consumed by `decorators/withTracker.jsx` and `lib/utils.js`. Override inline: `REACT_APP_SITE_TITLE='…' npm start`.
+**Environment:** `.env` **is checked into git** and holds only public build-time config — `VITE_GA_TRACKING_ID='UA-00000000-0'` (placeholder), `VITE_SITE_TITLE='Firefox Public Data Report'`, `VITE_VALUE_DECIMAL_PLACES=3`. Consumed through `import.meta.env` by `decorators/withTracker.jsx` and `lib/utils.js`. Override inline: `VITE_SITE_TITLE='…' npm start`.
 
 ## Coding Style & Naming Conventions
 
-- **`.jsx` for any file containing JSX** — including `src/index.jsx` and `*.test.jsx`. Plain `.js` only for non-JSX modules (`lib/utils.js`, `setupTests.js`, `registerServiceWorker.js`, all Nightwatch specs).
-- **PascalCase filenames matching the default-exported component.** Decorators are camelCase with a `with` prefix; `lib/lazyLoad.jsx` is camelCase.
+- **`.jsx` for any file containing JSX** — including `src/index.jsx` and `*.test.jsx`. Plain `.js` only for non-JSX modules (`lib/utils.js`, `setupTests.js`, `registerServiceWorker.js`, the Playwright specs and helpers, and the config files at the repository root).
+- **PascalCase filenames matching the default-exported component.** Decorators are camelCase with a `with` prefix; `lib/lazyLoad.jsx` is camelCase because it is a helper, not a component.
 - **One component per file, always `export default`.** There are no named component exports anywhere in the repo; the only named exports at all are the four helpers in `lib/utils.js`.
 - **The container/view split is the organizing principle.** `containers/X.jsx` holds state and fetching and renders `views/X.jsx` with formatted props (`ChartContainer`→`Chart`, `DataTableContainer`→`DataTable`). Keep new state out of `views/`.
-- Function components are the default (17 of 19 views), written as anonymous default-exported arrows — `export default props => (...)` — with no `displayName` (hence `react/display-name: off`). Use a class only where state, refs, or lifecycle are genuinely needed: all 6 containers plus `SummaryMetric.jsx` (d3 + `React.createRef`), `Spinner.jsx`, `MetricOverview.jsx`, `Footer.jsx`.
+- Function components are the default (17 of 19 views), written as anonymous default-exported arrows — `export default props => (...)` — with no `displayName` (hence `react/display-name: off`). Use a class only where state, refs, or lifecycle are genuinely needed: all 6 containers plus `SummaryMetric.jsx` (d3 + `React.createRef`), `Spinner.jsx`, `MetricOverview.jsx`, `Footer.jsx`, and `lib/LazyBoundary.jsx` (error boundaries must be classes).
 - Leading underscore for private class-property handlers (`_onRegionChange`, `_drawChart`, `_setChartWidth`) — applied inconsistently (`setChartSize` in `ChartContainer.jsx`); prefer the underscore in new code.
 - Locals named `maybeX` hold a JSX fragment **or `null`** (`maybeDescription`, `maybeSummaryMetrics`, `maybeRegion`, `maybeGraphURL`). Keep the idiom.
 - Styles attach via a global CSS side-effect import of the **generated** file at the top of the component: `import './css/Dashboard.css';`. Some components import several (`Chart.jsx` pulls `metrics-graphics/dist/metricsgraphics.css`, `./css/Chart.css`, `./css/Metric.css`). `Metric.css` and `LabelledSelector.css` are shared partials with no component of their own.
@@ -102,17 +103,17 @@ Run one Jest file by passing a path through: `CI=true npx react-scripts test src
 - `.editorconfig`: LF, final newline, trim trailing whitespace, 4-space indent for `py,yml,html,css,styl,js,json,md`. `.jsx` is missing from that list but 4-space is the de facto convention. No max line length is configured anywhere.
 - Every dependency is **exact-pinned** — no `^` or `~` in `package.json`. Keep it that way.
 
-**ESLint — there are two of them, and neither sees everything.** `.eslintrc.extra.js` is a standalone config run only by `npm run lint:js-extra`, and that script is `npx eslint --config .eslintrc.extra.js --ext .js --ext .json .` — **`.jsx` is not in the `--ext` list, so the bulk of the application code is never linted by it.** Separately, `react-scripts` 3.4.1 lints during `start`/`build` using its own bundled `eslint-config-react-app`, which appears nowhere in this repo and has no `eslintConfig` key in `package.json`. **Consequence: a change can pass `npm run lint` and still fail `npm run build`, and vice versa.** Run both.
+**ESLint is one flat config, `eslint.config.js`, covering `.js` and `.jsx`.** `npm run lint:js` runs `eslint .`; the build does not lint. Warnings don't fail the run.
 
-`.eslintrc.extra.js` errors: `eqeqeq`, `no-var`, `prefer-const`, `no-console`, `no-global-assign`, `no-redeclare` and `no-shadow` — the latter two with `builtinGlobals: true`, so **do not name a variable `name`, `status`, `history`, `event`, etc.** Warnings: `semi: always`, `prefer-arrow-callback`, `comma-dangle` (trailing commas **required** for multiline arrays/objects/imports/exports, **never** for function args/params). Off: `react/prop-types`, `react/display-name`, `jsx-a11y/no-onchange`. `react/no-unescaped-entities` forbids only `>` and `}`. `jsx-a11y/recommended` is on, so a11y violations are errors. **Quote style is not enforced** (there is no `quotes` rule) — single quotes by convention. `.eslintignore` covers `build` and `package-lock.json`.
+Errors: `eqeqeq`, `no-var`, `prefer-const`, `no-console`, `no-global-assign`, `no-redeclare` and `no-shadow` — the latter two with `builtinGlobals: true`, so **do not name a variable `name`, `status`, `history`, `event`, etc.** Warnings: `semi: always`, `prefer-arrow-callback`, `comma-dangle` (trailing commas **required** for multiline arrays/objects/imports/exports, **never** for function args/params). Off: `react/prop-types`, `react/display-name`, `jsx-a11y/no-onchange`. `react/no-unescaped-entities` forbids only `>` and `}`. `jsx-a11y/recommended` is on, so a11y violations are errors; `jsx-a11y/label-has-associated-control` requires `htmlFor`. `settings.react.version` is `'detect'`. `src/tests/jest/**/*.test.jsx` also gets `@vitest/eslint-plugin`'s recommended rules and the `React`/`shallow` globals. **Quote style is not enforced** (there is no `quotes` rule) — single quotes by convention. The config's own `ignores` excludes `build`.
 
-## Styling: Stylus, outside webpack
+## Styling: Stylus, outside Vite
 
-`src/components/views/styl/*.styl` → `src/components/views/css/*.css` via the `stylus` CLI (`build:css` / `watch:css`). Webpack never sees the Stylus. One `.styl` per component (PascalCase, mirroring the component), plus `Application.styl` (global reset, Fira Sans `@font-face`, body type, ~217 lines), `BrowserHacks.styl`, and shared partials `Metric.styl` and `LabelledSelector.styl`.
+`src/components/views/styl/*.styl` → `src/components/views/css/*.css` via the `stylus` CLI (`build:css` / `watch:css`). Vite never sees the Stylus. One `.styl` per component (PascalCase, mirroring the component), plus `Application.styl` (global reset, Fira Sans `@font-face`, body type, ~217 lines) and shared partials `Metric.styl` and `LabelledSelector.styl`.
 
 Shared variables live in `src/components/views/styl/includes/lib.styl` and it is nearly empty — `$base-tablet`, `$base-desktop`, `$link-color-normal = #0070ff`, and a `// TODO: padding/margin spacing.`. Import it per-file with `@import 'includes/lib'`; it is not globally injected. **No mixins file; most colors are hardcoded hex inline** (stylint's `colors` check is off).
 
-**Not BEM.** ID selectors carry the page landmarks — `#application`, `#main-header`, `#main-navigation`, `#dashboard`, `#dashboard-sections`, `#summary-metrics`, `#region`, `#introduction` — with flat lowercase-dash classes for repeated pieces (`.metric-overview`, `.dashboard-section`, `.data-table-wrapper`, `.labelled-selector`, `.next-button`, `.striped`, `.highlighted`, `.bar-label`). Descendant nesting with `&` for states; responsive via `@media $base-tablet` / `@media $base-desktop` blocks at the bottom of each file. **Those element IDs are also the Nightwatch selectors — renaming one breaks the e2e tests.**
+**Not BEM.** ID selectors carry the page landmarks — `#application`, `#main-header`, `#main-navigation`, `#dashboard`, `#dashboard-sections`, `#summary-metrics`, `#region`, `#introduction` — with flat lowercase-dash classes for repeated pieces (`.metric-overview`, `.dashboard-section`, `.data-table-wrapper`, `.labelled-selector`, `.next-button`, `.striped`, `.highlighted`, `.bar-label`). Descendant nesting with `&` for states; responsive via `@media $base-tablet` / `@media $base-desktop` blocks at the bottom of each file. **Those element IDs are also the Playwright selectors — renaming one breaks the e2e tests.**
 
 stylint (`.stylintrc`) runs with `maxErrors: 0` and `maxWarnings: 0`, so any finding fails the lint. It enforces the **CSS-like** Stylus dialect, not the terse indented syntax: 4-space indent, single quotes, `brackets: always`, `colons: always`, `semicolons: always`. Also `noImportant: true`, `leadingZero: false` (`.5`, not `0.5`), `zeroUnits: never` (`0`, not `0px`), `universal: never` (no `*`), `prefixVarsWithDollar: always`, `namingConvention: lowercase-dash` with `namingConventionStrict: true`, `zIndexNormalize: 10`. Escape hatches are `// @stylint off` / `on` / `ignore` comments — see the `@font-face` block in `Application.styl`.
 
@@ -125,11 +126,22 @@ Code is read far more often than it is written, and in this repo the next reader
 - **Comments must stand on their own.** Never reference a spec, a plan document, a requirement label, or a ticket ID *as* the explanation — the comment must make sense to someone who has only the file in front of them. A cross-reference alongside a self-contained explanation is fine; that is how the `metrics-graphics` workaround notes in `views/Chart.jsx` read.
 - Never describe code that no longer exists. After a refactor, delete the comments it falsified — this repo already has several. Prefer deleting an obsolete comment, branch, or test over leaving it beside its replacement.
 
+## Writing for people
+
+This applies to everything written for a person to read: ExecPlans, PR descriptions, commit messages, documentation, issue comments, and chat replies.
+
+- Put the point first. Lead with the conclusion or the action, then give the reason.
+- Keep sentences short, one idea each. If a sentence needs a semicolon or a second "which", split it.
+- Use active voice and say who does what: "Vitest fails without the compiled CSS", not "a failure was observed".
+- Use the plain word: "use", "start", "before", "if", "about" — not "utilise", "commence", "prior to", "in the event that", "approximately".
+- Cut hedges and filler: "it should be noted that", "in order to", "verified directly, not assumed".
+- Number steps the reader has to follow in order.
+
 ## Testing Guidelines
 
-**Jest + enzyme**, through CRA's built-in Jest, with no `jest` config block. Only two files, both in `src/tests/jest/`, named `PascalCase.test.jsx` — **not colocated, no `__tests__` directories.** `src/setupTests.js` puts `React` and `shallow` on `global`, so **test files import neither**: they `import Dashboard from '../../components/views/Dashboard';` and call bare `shallow(<Dashboard … />)`. Existing style is top-level `it(...)` with long descriptive sentences, a `beforeAll` that builds a `requiredProps` object, and assertions via `.find(selector).exists()` and `.html()).toContain(...)`. Shallow rendering only; no snapshots; `react-refetch` is never mocked; there are no container tests.
+**Vitest + enzyme**, configured in the `test` block of `vite.config.mjs` (`jsdom`, `globals: true`, `include: ['src/tests/jest/**/*.test.jsx']`). Only two files, both in `src/tests/jest/`, named `PascalCase.test.jsx` — **not colocated, no `__tests__` directories.** `src/setupTests.js` puts `React` and `shallow` on `global`, so **test files import neither**: they `import Dashboard from '../../components/views/Dashboard';` and call bare `shallow(<Dashboard … />)`. Existing style is top-level `it(...)` with long descriptive sentences, a `beforeAll` that builds a `requiredProps` object, and assertions via `.find(selector).exists()` and `.html()).toContain(...)`. Shallow rendering only; no snapshots; `react-refetch` is never mocked; there are no container tests.
 
-**Nightwatch** specs in `src/tests/nightwatch/` are **lowercase `.js`, CommonJS**: `module.exports = { before: browser => …, 'Test name as a sentence': browser => … }`. `nightwatch.conf.js` reads `NIGHTWATCH_TARGET` (`dev` = localhost:3000, `stage` = data-ensemble.stage.mozaws.net, `prod` = data.firefox.com) and **throws if it is unset** — it destructures `undefined`. The `default` env is headless Chrome and excludes `utils.js` and `jsDisabled.js`; the `jsDisabled` env runs only `jsDisabled.js` and must be **non-headless** (JS cannot be disabled in headless Chrome), asserting on the `id="enable-javascript"` `<noscript>` block in `public/index.html`. `src/tests/nightwatch/utils.js` exports `linkWorks`, `linksWork`, `metricTitleIsCorrect`, and `flagForUpdate` — which **deliberately fails when an element count changes**, to force a human to look. The `dashboards/*.js` specs assert exact metric titles and section ordering **against live production data**, so upstream data changes break them by design. `test:nightwatch:dev` does **not** start the dev server; `npm start` must already be running in another shell. None of this can run today — see Current State.
+**Playwright** specs in `tests/playwright/specs/` are **`camelCase.spec.js` or `kebab-case.spec.js`, CommonJS**, using `@playwright/test`'s `test`/`expect`. `playwright.config.js` has two Chromium projects: `chromium` runs everything except `jsDisabled.spec.js`, and `chromium-no-js` runs only that spec with `javaScriptEnabled: false`, asserting on the `id="enable-javascript"` `<noscript>` block in `index.html`. Playwright starts `npm start` itself unless a server is already on `:3000`. Set `PLAYWRIGHT_BASE_URL` to test another environment (`PLAYWRIGHT_BASE_URL=https://data.firefox.com npx playwright test`). `tests/playwright/utils.js` exports `linkWorks`, `linksWork`, `metricTitleIsCorrect`, and `flagForUpdate` — which **deliberately fails when an element count changes**, to force a human to look. The `dashboards/*.spec.js` specs assert exact metric titles and section ordering **against live production data**, so upstream data changes break them by design.
 
 **Tests describe the code as it is now.** Assert what the code does; never add a test whose purpose is to prove that removed behaviour is absent — a negative assertion about history passes forever while documenting nothing. Each test builds only the data it needs; no shared mega-fixture. Keep assertions at the point where the thing is rendered rather than behind a `_getElement(wrapper)`-style indirection layer, so a failure points straight at the markup it cares about.
 
@@ -137,17 +149,15 @@ Code is read far more often than it is written, and in this repo the next reader
 
 | Trap | What happens |
 |---|---|
-| `npm install` on Apple Silicon | Fails outright — chromedriver@84 postinstall: `Only Mac 64 bits supported`. Use `--ignore-scripts`. |
-| Two linters, disjoint coverage | `npm run lint` only covers `.js`/`.json`; CRA lints `.jsx` during `build`. Green lint ≠ green build. Run both. |
+| Switching branches without reinstalling | `node_modules` can still hold another branch's packages. Run `npm install` after a branch switch before trusting any result. |
 | Gitignored `src/components/views/css/` | Fresh clone cannot resolve the CSS imports until `npm run build:css` runs. Never hand-edit `css/` — edit `styl/`. |
-| Renaming a landmark ID | Breaks Nightwatch selectors silently until the e2e suite runs — and it can't run at all right now. |
-| `NIGHTWATCH_TARGET` unset | `nightwatch.conf.js` throws on load, before any test runs. |
+| Renaming a landmark ID | Breaks Playwright selectors silently. |
+| First visit to a route on the Vite dev server | Can 504 or fail a dynamic import ("Outdated Optimize Dep") while Vite pre-bundles a new dependency. A reload fixes it; production builds don't do this. |
+| `path.mg-line1` in a Playwright locator | metrics-graphics puts the class on many invisible hover paths too. Use `.first()` or the locator throws a strict-mode error. |
 | `build:version.json` | Needs `build/` to already exist and `git` on PATH; must follow `build:app`. |
-| `.eslintrc.extra.js` override glob | Declares the `React`/`shallow` globals for `src/tests/jest/*.js`, but the files are `.jsx` — **the override never matches**. |
 | `no-shadow` / `no-redeclare` with `builtinGlobals` | Naming a local `name`, `status`, `history`, `event` is a hard error. |
-| `npm install` on npm ≥7 | Rewrites `package-lock.json` v1 → v3. |
 
-**Known rot, for recognition only — this file is not a roadmap:** `.eslintrc.extra.js` sets `parser: './node_modules/babel-eslint'` (a hard relative path into a *transitive* dependency) and `settings.react.version: "16.4.2"` while React 16.13.1 is installed; `eslint` is not a direct dependency, so `lint:js-extra` goes through `npx` and relies on a hoisted transitive `eslint@6.8.0`; `babel-polyfill` + `react-app-polyfill` and a `browserslist` of `>0.2%, not dead, not ie <= 10, not op_mini all` are IE11-era targeting; `request@2.88.2` is deprecated (#395); `registerServiceWorker.js` exists but only `unregister()` is called.
+**Known rot, for recognition only — this file is not a roadmap:** `registerServiceWorker.js` exists but only `unregister()` is called, and its registration path still reads create-react-app's `process.env.PUBLIC_URL`; `dateformat@3.0.3` is several majors behind, because newer majors change its export shape (see `docs/architecture/frontend.md`).
 
 ## Workflow guidelines
 
@@ -157,7 +167,7 @@ Code is read far more often than it is written, and in this repo the next reader
 
 ### ExecPlans
 
-Work that spans more than one session — the ESLint unification, replacing the blocked Nightwatch suite, #409's redraw path — gets an **ExecPlan**: a self-contained Markdown design document, written before the code, committed with it, and kept current as the work moves. The specification is `.claude/skills/execplans/references/PLANS.md`; the `execplans` skill loads it on demand, so read it there rather than guessing at the shape.
+Work that spans more than one session — #409's redraw path, broadening test coverage — gets an **ExecPlan**: a self-contained Markdown design document, written before the code, committed with it, and kept current as the work moves. The specification is `.claude/skills/execplans/references/PLANS.md`; the `execplans` skill loads it on demand, so read it there rather than guessing at the shape.
 
 Plans live in `docs/execplans/`, named `YYYY-MM-DD-kebab-case-summary.md` (`2026-09-14-eslint-unification.md`), and ship on the branch with the change so a reviewer reads the plan and the diff together. Update the plan in the same commit as the work it describes — a plan that lags the tree is worse than no plan.
 
@@ -205,7 +215,7 @@ Replacement, as it should read:
 
 **Testing.** What a reviewer does by hand to check this. The one section worth expanding.
 
-- Open with prerequisites where there are any: "Run `npm run build:css` first" or "Needs `tests/playwright/` installed separately — see its README."
+- Open with prerequisites where there are any: "Run `npm run build:css` first" or "Run `npx playwright install chromium` first."
 - Include setup commands a reviewer must run to see the change at all. Leave out test and lint commands — `npm test`, `npm run lint`, `npx playwright test` — those only re-check what CI (once it exists) already checks.
 - Give the URL to load — `http://localhost:3000/dashboard/hardware`, not just "the hardware dashboard" — and the expected result once there.
 - One step per thing to verify, phrased as a check — "Check the dashboard doesn't hang on resize", not "resize the window → dashboard redraws instantly". `- [ ]` checkboxes where the reviewer is working through a list.
@@ -242,8 +252,8 @@ Here's the shape to aim for — a description for the real ESLint-unification wo
 
 - Keep secrets out of version control.
 - Configuration follows the 12-Factor App pattern via `.env` — but note that **this repo's `.env` is deliberately checked in**, because it holds only public build-time values and a placeholder GA ID. A real credential does not go in that file.
-- This is a fully client-side bundle: anything in a `REACT_APP_*` variable ships to the browser in plain text.
-- If a changeset adds a GitHub Action or Workflow (there are none today), check it with [Zizmor](https://zizmor.sh/) before considering the work complete.
+- This is a fully client-side bundle: anything in a `VITE_*` variable ships to the browser in plain text.
+- If a changeset adds a GitHub Action or Workflow, check it with [Zizmor](https://zizmor.sh/) before considering the work complete.
 
 ## LLM assistance
 
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index e448ce2..aedbe39 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -27,7 +27,7 @@ Run one Vitest file directly: `npx vitest run src/tests/jest/Dashboard.test.jsx`
 working). Run one Playwright spec directly: `npx playwright test contact.spec.js`.
 
 **Environment:** `.env` is checked into git and holds only public build-time config —
-`NODE_ENV=development`, `VITE_GA_TRACKING_ID='UA-00000000-0'` (a placeholder),
+`VITE_GA_TRACKING_ID='UA-00000000-0'` (a placeholder),
 `VITE_SITE_TITLE='Firefox Public Data Report'`, `VITE_VALUE_DECIMAL_PLACES=3`. These are consumed by
 `src/components/decorators/withTracker.jsx` and `src/lib/utils.js` via `import.meta.env.VITE_*` —
 Vite's own convention, not Node's `process.env` (which is not populated in the browser bundle at

From 95f3925b98854ca59517a4cf3c15d3cad79f1abb Mon Sep 17 00:00:00 2001
From: Stephanie Hobson <stephaniehobson@users.noreply.github.com>
Date: Thu, 8 Oct 2026 20:33:37 -0700
Subject: [PATCH 2/4] Add GitHub Actions CI workflow for lint and tests (#79)

Runs lint, the Vitest unit tests, and the Playwright end-to-end tests on every push to main and every pull request. Stops checking external links in the Playwright suite, because third-party bot walls fail them on GitHub's runners.
---
 .github/workflows/ci.yml                      |  55 ++++
 AGENTS.md                                     |   4 +-
 CONTRIBUTING.md                               |   8 +-
 .../2026-10-08-github-actions-ci-shorter.md   | 235 ++++++++++++++++++
 tests/playwright/specs/contact.spec.js        |   6 -
 tests/playwright/specs/footer.spec.js         |  12 -
 tests/playwright/utils.js                     |  53 +---
 7 files changed, 303 insertions(+), 70 deletions(-)
 create mode 100644 .github/workflows/ci.yml
 create mode 100644 docs/execplans/2026-10-08-github-actions-ci-shorter.md
 delete mode 100644 tests/playwright/specs/footer.spec.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..e5f012e
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,55 @@
+name: CI
+
+on:
+    push:
+        branches:
+            - main
+    pull_request:
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+    cancel-in-progress: true
+
+permissions:
+    contents: read
+
+jobs:
+    lint-and-test:
+        name: Lint and test
+        runs-on: ubuntu-latest
+        if: github.repository == 'mozilla/ensemble'
+        steps:
+            - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+              with:
+                  persist-credentials: false
+            - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+              with:
+                  node-version-file: '.nvmrc'
+                  cache: npm
+            - name: Install dependencies
+              run: npm ci
+            - name: Compile Stylus
+              run: npm run build:css
+            - name: Run lint
+              run: npm run lint
+            - name: Run unit tests
+              run: npm run test:jest
+
+    e2e:
+        name: End-to-end tests
+        runs-on: ubuntu-latest
+        if: github.repository == 'mozilla/ensemble'
+        steps:
+            - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+              with:
+                  persist-credentials: false
+            - uses: actions/setup-node@949feb2413d6458794dcd2491c4babbbce0c15c1 # v7.1.0
+              with:
+                  node-version-file: '.nvmrc'
+                  cache: npm
+            - name: Install dependencies
+              run: npm ci
+            - name: Install Playwright browsers
+              run: npx playwright install --with-deps chromium
+            - name: Run end-to-end tests
+              run: npm run test:playwright
diff --git a/AGENTS.md b/AGENTS.md
index 8f2f33f..2546a02 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -56,7 +56,7 @@ There is no `pages/`, `store/`, `hooks/`, `api/`, `locales/`, or `data/`. `index
 
 MozMEAO is taking this repo over. Before that work started there were 810 commits — 515 in 2018, 92 in 2020, **nothing in 2021–2024**, three in 2025, the last `f655559` on 2025-05-07. The toolchain has since been replaced (#441): create-react-app, Jest and Nightwatch gave way to Vite, Vitest and Playwright, and two ESLint configs became one. Code outside the toolchain has barely been exercised since 2020.
 
-- **No CI/CD of any kind exists.** No `.github/`, `.circleci/`, `Dockerfile`, `docker-compose`, `Jenkinsfile`. This is not a quirk of your clone — it was all deliberately removed: CircleCI disabled 2018-02-22 (`433a465`), Docker/Dockerflow removed 2018-08-23 (`d3bb561`), `.github/dependabot.yml` deleted 2020-07-29 (`7c7006f`, "Disable non-security updates from Dependabot"). Issue #79 ("enable CI") is still open.
+- **CI runs on GitHub Actions; there is no CD.** `.github/workflows/ci.yml` runs lint, the Vitest unit tests, and the Playwright end-to-end tests on every push to `main` and every pull request. There is no `.circleci/`, `Dockerfile`, `docker-compose`, or `Jenkinsfile` — earlier automation was deliberately removed: CircleCI disabled 2018-02-22 (`433a465`), Docker/Dockerflow removed 2018-08-23 (`d3bb561`), `.github/dependabot.yml` deleted 2020-07-29 (`7c7006f`, "Disable non-security updates from Dependabot").
 - **The deploy is a static build on Google Cloud Storage** (confirmed by `x-goog-*` headers on the live site). `https://data.firefox.com/version.json` reports `1.2.1` / commit `f655559`, so **the deployed site predates the Vite toolchain on `main`**; nothing built by Vite has shipped yet. The mechanism that pushes `build/` to GCS is **not in this repo and is currently unknown** — finding and documenting it is takeover work, not something to guess at.
 - **Node 24.** `.nvmrc` holds `24` and `engines` requires `^24.15.0`. A plain `npm install` works with no flags.
 - **A fresh clone will not render styles until you compile Stylus.** `src/components/views/css/*` is gitignored and every component does a side-effect `import './css/Foo.css';` — run `npm run build:css` or the app, and Vitest, fail to resolve those imports. `npm start` compiles it for you.
@@ -216,7 +216,7 @@ Replacement, as it should read:
 **Testing.** What a reviewer does by hand to check this. The one section worth expanding.
 
 - Open with prerequisites where there are any: "Run `npm run build:css` first" or "Run `npx playwright install chromium` first."
-- Include setup commands a reviewer must run to see the change at all. Leave out test and lint commands — `npm test`, `npm run lint`, `npx playwright test` — those only re-check what CI (once it exists) already checks.
+- Include setup commands a reviewer must run to see the change at all. Leave out test and lint commands — `npm test`, `npm run lint`, `npx playwright test` — those only re-check what CI already checks.
 - Give the URL to load — `http://localhost:3000/dashboard/hardware`, not just "the hardware dashboard" — and the expected result once there.
 - One step per thing to verify, phrased as a check — "Check the dashboard doesn't hang on resize", not "resize the window → dashboard redraws instantly". `- [ ]` checkboxes where the reviewer is working through a list.
 - Ask plainly for a close look when you want one: "Look closely at the region-selector change, please — it touches sessionStorage across every dashboard."
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index aedbe39..0c35272 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -152,8 +152,9 @@ repository root. Specs are `camelCase.spec.js` or `kebab-case.spec.js` (matching
 page under test), CommonJS, using `@playwright/test`'s own `test`/`expect` — for example
 `test('Page loads', async ({ page }) => { await expect(page.locator('#contact')).toBeVisible(); })`.
 Shared helpers (`linkWorks`, `linksWork`, `flagForUpdate`, `metricTitleIsCorrect`) live in
-`tests/playwright/utils.js`. `flagForUpdate` deliberately fails when an element count changes, to
-force a human to look. The `dashboards/*.spec.js` specs assert exact metric titles and section
+`tests/playwright/utils.js`. `linkWorks` and `linksWork` check only links within the app and skip
+external URLs, which failed too often for reasons outside this repository. `flagForUpdate`
+deliberately fails when an element count changes, to force a human to look. The `dashboards/*.spec.js` specs assert exact metric titles and section
 ordering against live production data, so upstream data changes break them by design — this is not
 a bug in the tests, and updating their expectations to match reality is normal, expected
 maintenance. Two browser projects: `chromium` (everything except `jsDisabled.spec.js`) and
@@ -285,8 +286,7 @@ WebKit-specific slowness noted while porting the end-to-end suite."
 
 - Open with prerequisites where there are any: "Run `npm run build:css` first."
 - Include setup commands a reviewer must run to see the change at all. Leave out test and lint
-  commands (`npm test`, `npm run lint`) — those only re-check what CI, once it exists, already
-  checks.
+  commands (`npm test`, `npm run lint`) — those only re-check what CI already checks.
 - Give the URL to load — `http://localhost:3000/dashboard/hardware`, not just "the hardware
   dashboard" — and the expected result once there.
 - One step per thing to verify, phrased as a check — "Check the dashboard doesn't hang on resize,"
diff --git a/docs/execplans/2026-10-08-github-actions-ci-shorter.md b/docs/execplans/2026-10-08-github-actions-ci-shorter.md
new file mode 100644
index 0000000..b3bf8cc
--- /dev/null
+++ b/docs/execplans/2026-10-08-github-actions-ci-shorter.md
@@ -0,0 +1,235 @@
+# Run lint and tests on GitHub Actions for every push to main and every pull request
+
+This ExecPlan is a living document. The sections `Progress`, `Surprises & Discoveries`,
+`Decision Log`, and `Outcomes & Retrospective` must be kept up to date as work proceeds. It is
+maintained in accordance with `.claude/skills/execplans/references/PLANS.md`, including its
+"Ensemble addendum", which overrides the upstream text where the two disagree.
+
+## Purpose / Big Picture
+
+Nothing checks a commit in this repository today. Contributors run lint and the tests by hand, or
+don't. After this change, every push to `main` and every pull request runs a GitHub Actions
+workflow named "CI". It reports two checks on the commit and the pull request: "CI / Lint and test"
+and "CI / End-to-end tests". A contributor sees a red or green mark without running anything
+locally.
+
+To see it working, open a pull request from this branch on `mozilla/ensemble` and watch both checks
+go green in the pull request's Checks tab.
+
+Out of scope: a branch-protection rule that makes the checks required (a repository setting, not a
+file), Dependabot (deliberately turned off in 2020), and automated deploy.
+
+## Progress
+
+- [x] (2026-10-08) Drafted the plan.
+- [x] (2026-10-08) Milestone 1: `.github/workflows/ci.yml` with the `lint-and-test` job, Zizmor
+      clean (online mode), docs updated. Locally: lint clean, Vitest 2 files / 4 tests passed.
+- [x] (2026-10-08) Milestone 2: `e2e` job added, external link checks removed from the Playwright
+      suite, docs updated. Zizmor clean. Locally: Playwright 49 passed against a dev server on
+      :3001 (see Surprises).
+- [x] (2026-10-08) Milestone 3: both jobs green on pull request #447.
+
+## Surprises & Discoveries
+
+These come from an earlier attempt at this issue, first pushed to pull request #447. That attempt
+is kept on the local branches `79--github-actions-ci` and `79--github-actions-ci-rewrite`. They are
+restated here so this plan stands alone.
+
+- Observation: `npm run test:jest` fails outright without the compiled CSS.
+  Evidence: "Failed to resolve import './css/MetricOverview.css'". The unit-test job must run
+  `npm run build:css` first. The end-to-end job does not, because Playwright starts `npm start`,
+  which compiles the Stylus.
+- Observation: `playwright.config.js` already adapts to CI. GitHub Actions sets `CI=true`, and the
+  config then uses the `github` reporter (inline annotations on the pull request), 2 retries, 2
+  workers, and refuses to reuse an existing server. The workflow needs to configure none of this.
+- Observation: external link checks fail on GitHub's runners for reasons no commit can fix.
+  Evidence: `donate.mozilla.org` redirects to a page that returns 403 to non-browser clients,
+  `facebook.com` blocks GitHub's runner IP ranges, and `x.com` returns 403 to headless Chromium.
+
+- Observation: locally, Playwright silently tests whatever already listens on port 3000.
+  Evidence: outside CI, `reuseExistingServer` is true, so an unrelated server on :3000 (here, a
+  Fractal server from another project) made 45 of 49 specs fail with "#not-found ... element(s) not
+  found". Check with `lsof -i :3000`. To test without stopping that server, run
+  `npx vite --port 3001 --strictPort` and then
+  `PLAYWRIGHT_BASE_URL=http://localhost:3001 npx playwright test`. CI is unaffected.
+
+## Decision Log
+
+- Decision: model the workflow on `mozmeao/springfield`'s `unit_tests.yml`. Trigger on `push` to
+  `main` and on every `pull_request`. Cancel stale runs with a concurrency group keyed on the pull
+  request number. Grant only `permissions: contents: read`. Guard each job with
+  `if: github.repository == 'mozilla/ensemble'` so forks don't spend minutes on it.
+  Rationale: MozMEAO maintains this repository alongside springfield and bedrock, and matching them
+  keeps the three familiar. Bedrock's copy uses unpinned actions, which Zizmor rejects, so
+  springfield is the model.
+  Date/Author: 2026-09-18, the user's request on the earlier attempt; carried forward.
+- Decision: depart from springfield in three places. Set `persist-credentials: false` on
+  `actions/checkout`. Read the Node version from `.nvmrc` with `node-version-file`. Pin both actions
+  to the full commit SHA of their latest release, with the tag in a trailing comment.
+  Rationale: Zizmor flags persisted credentials and unpinned actions, and `AGENTS.md` requires a
+  Zizmor-clean workflow. A literal Node version in the workflow would drift from `.nvmrc`.
+  Date/Author: 2026-10-08.
+- Decision: one workflow file with two jobs. Use `npm ci`. Install only Chromium for Playwright.
+  Rationale: one "CI" entry in the Actions tab reads more easily than two workflows. `npm ci`
+  installs exactly what `package-lock.json` says. Both Playwright projects use Chromium.
+  Date/Author: 2026-10-08.
+- Decision: stop checking links that leave the app's own origin. Internal links stay checked.
+  Rationale: the user chose this on the earlier attempt, after a per-host exception for
+  `donate.mozilla.org` was followed by `facebook.com` and then `x.com` failing the same way.
+  Internal links are the ones this repository can break. The accepted cost is that external link
+  rot, the kind #448 fixed, is no longer caught automatically.
+  Date/Author: 2026-10-01, the user's decision on the earlier attempt; reconfirmed 2026-10-08.
+
+- Decision: reuse pull request #447 for this work rather than open a new one. Force-push this
+  branch to `mozilla/79--github-actions-ci` and track that remote branch from here.
+  Rationale: the user's choice. It keeps one pull request for issue #79 and its review history.
+  Date/Author: 2026-10-08, the user's decision.
+
+## Outcomes & Retrospective
+
+Shipped on pull request #447. Both jobs passed on the first run
+(<https://github.com/mozilla/ensemble/actions/runs/37879164574>): "Lint and test" in 17s and
+"End-to-end tests" in 1m32s. Playwright reported 47 passed and 2 flaky. The flaky specs were the
+title-and-order tests in `dashboards/usage-behavior.spec.js` and `dashboards/user-activity.spec.js`,
+which passed on retry. Both load live data from `data.firefox.com`, so expect this now and then.
+If a dashboard spec flakes on most runs, investigate it rather than raising the retry count.
+
+Still open, outside this plan: no branch protection, so a red check doesn't block a merge. External
+link rot is no longer caught by anything.
+
+## Context and Orientation
+
+Issue #79 (<https://github.com/mozilla/ensemble/issues/79>) was opened in 2018, when a pull request
+got no CI feedback. It asks for CI that lints and runs the tests on every commit. The repository
+once had CircleCI, but it was turned off in February 2018 (`433a465`), and nothing replaced it.
+There is no `.github/` directory today.
+
+The toolchain the workflow drives was replaced in #441 and is recorded in
+`docs/execplans/2026-09-15-update-toolchain.md`. What this plan relies on: Node 24, pinned in
+`.nvmrc`; and these npm scripts in `package.json`, all of which run with no flags on a clean
+checkout.
+
+    npm ci
+    npm run build:css         # compiles src/components/views/styl/*.styl into the gitignored css/
+    npm run lint              # ESLint (eslint.config.js) plus stylint (.stylintrc)
+    npm run test:jest         # Vitest; 2 files in src/tests/jest/
+    npm run test:playwright   # Playwright; starts `npm start` on :3000 itself
+
+"The compiled CSS" means `src/components/views/css/`. It is gitignored, and every component imports
+a file from it, so Vitest and the dev server fail until `npm run build:css` has run.
+
+The Playwright specs live in `tests/playwright/specs/`. Several of them call `linkWorks` or
+`linksWork` from `tests/playwright/utils.js`. Both helpers pass every link to `loadsSuccessfully` in
+the same file. For a link inside the app, it navigates there and checks that `#application` renders
+and `#not-found` does not. For an external link, it opens the URL in a new browser page and expects
+HTTP 200, with three attempts and backoff, plus a redirect-only special case for
+`donate.mozilla.org`. `footer.spec.js` and the "All links work" test in `contact.spec.js` check only
+external and `mailto:` links. The `dashboards/*.spec.js` specs assert exact metric titles against
+live production data on `data.firefox.com`, so a failure there can come from upstream data changing.
+
+Zizmor (<https://zizmor.sh/>) is a static checker for GitHub Actions workflows. It flags things like
+unpinned actions, persisted checkout credentials, and template injection. It is not installed
+globally on the author's machine; `uvx zizmor` runs it without installing.
+
+Docs that will go stale: `AGENTS.md` says "No CI/CD of any kind exists" (the "Current state"
+section) and "what CI (once it exists) already checks" (the PR-description "Testing" guidance).
+`CONTRIBUTING.md` says "what CI, once it exists, already checks" and describes `linkWorks` and
+`linksWork` without saying they skip external links.
+
+## Plan of Work
+
+### Milestone 1: lint and unit tests
+
+At the end of this milestone, `.github/workflows/ci.yml` exists with one job, `lint-and-test`,
+displayed as "Lint and test". Zizmor reports nothing.
+
+1. Look up the latest release tag of `actions/checkout` and `actions/setup-node`, and the full
+   commit SHA each tag points to. On 2026-10-08 those were checkout v7.0.1
+   (`3d3c42e5aac5ba805825da76410c181273ba90b1`) and setup-node v7.1.0
+   (`949feb2413d6458794dcd2491c4babbbce0c15c1`).
+2. Create `.github/workflows/ci.yml` with the triggers, concurrency group, and permissions from the
+   Decision Log. The `lint-and-test` job runs on `ubuntu-latest`, carries the repository guard, and
+   has these steps: checkout with `persist-credentials: false`; setup-node with
+   `node-version-file: '.nvmrc'` and `cache: npm`; then `npm ci`, `npm run build:css`,
+   `npm run lint`, and `npm run test:jest`, each as a named step. Use 4-space indentation, which
+   `.editorconfig` sets for `yml`.
+3. Run Zizmor and fix anything it reports.
+4. Update the docs this milestone makes stale. In `AGENTS.md`, rewrite the "No CI/CD of any kind
+   exists" bullet to say CI runs on GitHub Actions in `.github/workflows/ci.yml` and there is still
+   no CD; keep the history of what was removed and when. Drop "(once it exists)" from the
+   PR-description guidance. In `CONTRIBUTING.md`, drop ", once it exists,". Describe the jobs that
+   exist at this point; Milestone 2 adds the end-to-end job to the same sentence.
+
+### Milestone 2: end-to-end tests
+
+At the end of this milestone, `ci.yml` has a second job, `e2e`, displayed as "End-to-end tests",
+and the Playwright suite no longer reaches outside the app.
+
+1. In `tests/playwright/utils.js`, make `loadsSuccessfully` return early for any URL whose origin
+   differs from the current page's. This also covers `mailto:`, whose origin is `null`. Delete the
+   now-unused status-code constants, the `donate.mozilla.org` special case, the retry loop, and the
+   comment lines that described them. Replace them with one comment saying external links are not
+   checked and why.
+2. Delete `tests/playwright/specs/footer.spec.js`. Delete the "All links work" test and the
+   `linksWork` import from `tests/playwright/specs/contact.spec.js`. Both checked only external and
+   `mailto:` links, so they would now pass while checking nothing.
+3. Add the `e2e` job to `ci.yml`: same checkout, setup-node, guard, and `npm ci` as Milestone 1,
+   then `npx playwright install --with-deps chromium` and `npm run test:playwright`.
+4. Run Zizmor again.
+5. Update the docs. In `AGENTS.md`, add the end-to-end tests to the CI bullet. In
+   `CONTRIBUTING.md`, add the same, and say that `linkWorks` and `linksWork` check only links
+   within the app. Check the "Testing Guidelines" section of `AGENTS.md` for the same helper
+   description and update it if it implies external links are checked.
+
+### Milestone 3: prove it on GitHub
+
+The workflow only runs on GitHub, so local checks cannot prove it. This branch is pushed to the
+remote branch `79--github-actions-ci`, replacing the earlier attempt there, so it appears as pull
+request #447 against `main` on `mozilla/ensemble`. Wait for both checks to finish. If the
+end-to-end job fails, re-run it once before investigating, because the dashboard specs depend on
+live data. Record which it was. Then fill in `Outcomes & Retrospective`.
+
+## Concrete Steps
+
+From the repository root, `/Users/shobson/Sites/ensemble` on the author's machine:
+
+    npm ci
+    npm run build:css
+    npm run lint
+    npm run test:jest
+    npm run test:playwright
+    GH_TOKEN=$(gh auth token) uvx zizmor --pedantic .github/workflows/ci.yml
+
+Without `GH_TOKEN`, Zizmor runs offline and skips the audits that query GitHub, such as checking
+that a pinned SHA matches its tag comment.
+
+Expected: `npm run lint` exits 0 with no errors. `npm run test:jest` reports 2 test files passed.
+`npm run test:playwright` passes, possibly with retries on the dashboard specs. Zizmor prints:
+
+    No findings to report. Good job!
+
+## Validation and Acceptance
+
+Accept the work when all of these hold:
+
+1. Zizmor reports no findings for `.github/workflows/ci.yml`.
+2. `npm run lint`, `npm run test:jest`, and `npm run test:playwright` pass locally on the branch.
+3. On a pull request against `mozilla/ensemble`, "CI / Lint and test" and "CI / End-to-end tests"
+   both appear in the Checks tab and both pass.
+4. `grep -rn "once it exists\|No CI/CD" AGENTS.md CONTRIBUTING.md` prints nothing.
+
+## Idempotence and Recovery
+
+Every local command above is safe to repeat. Re-running a failed job on GitHub
+(`gh run rerun <run-id> --failed`) is safe and changes nothing in the repository. To back the work
+out, delete `.github/workflows/ci.yml`; nothing else depends on it.
+
+## Interfaces and Dependencies
+
+Future branch protection should require the check names "CI / Lint and test" and "CI / End-to-end
+tests". GitHub builds those names from the workflow's `name` and each job's `name`, so keep both
+stable. The job keys `lint-and-test` and `e2e` are what `needs:` and the API refer to; keep them
+stable too.
+
+The workflow depends on `actions/checkout` and `actions/setup-node`, both pinned by SHA, and on
+`ubuntu-latest` having network access to npm, the Playwright browser CDN, and `data.firefox.com`.
diff --git a/tests/playwright/specs/contact.spec.js b/tests/playwright/specs/contact.spec.js
index a0570a9..1043b14 100644
--- a/tests/playwright/specs/contact.spec.js
+++ b/tests/playwright/specs/contact.spec.js
@@ -1,5 +1,4 @@
 const { test, expect } = require('@playwright/test');
-const { linksWork } = require('../utils');
 
 
 test.beforeEach(async ({ page }) => {
@@ -14,8 +13,3 @@ test('Page <title> is correct', async ({ page }) => {
     await expect(page.locator('#contact')).toBeVisible();
     await expect(page).toHaveTitle('Contact | Firefox Public Data Report');
 });
-
-test('All links work', async ({ page }) => {
-    await expect(page.locator('#contact')).toBeVisible();
-    await linksWork(page, '#contact a');
-});
diff --git a/tests/playwright/specs/footer.spec.js b/tests/playwright/specs/footer.spec.js
deleted file mode 100644
index 931064a..0000000
--- a/tests/playwright/specs/footer.spec.js
+++ /dev/null
@@ -1,12 +0,0 @@
-const { test } = require('@playwright/test');
-const { linksWork } = require('../utils');
-
-
-test.beforeEach(async ({ page }) => {
-    await page.goto('/');
-});
-
-test('All footer links work', async ({ page }) => {
-    await page.locator('footer').waitFor({ state: 'visible' });
-    await linksWork(page, 'footer a');
-});
diff --git a/tests/playwright/utils.js b/tests/playwright/utils.js
index 4f2314c..c4831b6 100644
--- a/tests/playwright/utils.js
+++ b/tests/playwright/utils.js
@@ -1,58 +1,19 @@
 const { expect } = require('@playwright/test');
 
 
-const acceptedHTTPStatusCodes = [200];
-const acceptedRedirectStatusCodes = [301, 302];
-
-// donate.mozilla.org redirects (301) to a URL that blocks non-browser HTTP
-// clients (403), even though the redirect itself is completely valid.
-// Checking this one link's redirect status directly.
-const linksCheckedByRedirectOnly = ['https://donate.mozilla.org/'];
-
+// External links aren't checked: third-party bot walls, outages, and rate
+// limits made them fail for reasons unrelated to this repository's code.
 // Loading a URL the React app manages itself doesn't return a 404 - it
 // displays a "Not Found" message instead, so a booted app is confirmed via
 // #application before checking #not-found is absent (otherwise a page that
 // never booted at all would also lack #not-found and look like a pass).
-// External URLs are checked by navigating a throwaway page rather than
-// page.request.get(), since some hosts block non-browser HTTP clients;
-// retrying with backoff since external hosts occasionally hiccup.
 async function loadsSuccessfully(page, url) {
-    if (url.startsWith('mailto:')) return;
-
-    if (new URL(url).origin === new URL(page.url()).origin) {
-        await page.goto(url);
-        await expect(page.locator('#application'), `App booted for: ${url}`).toBeVisible();
-        await expect(page.locator('#not-found'), `Loaded successfully: ${url}`).not.toBeVisible();
-        await page.goBack();
-        return;
-    }
-
-    const checkRedirectOnly = linksCheckedByRedirectOnly.includes(url);
+    if (new URL(url).origin !== new URL(page.url()).origin) return;
 
-    const maxAttempts = 3;
-    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-        if (checkRedirectOnly) {
-            // A real navigation would follow the redirect straight into the
-            // bot-blocking wall, so this checks the redirect itself via a
-            // raw request instead of a browser navigation.
-            const response = await page.request.get(url, { maxRedirects: 0 }).catch(() => null);
-            if (response && acceptedRedirectStatusCodes.includes(response.status())) return;
-        } else {
-            const externalPage = await page.context().newPage();
-            try {
-                const response = await externalPage.goto(url).catch(() => null);
-                if (response && acceptedHTTPStatusCodes.includes(response.status())) return;
-            } finally {
-                await externalPage.close();
-            }
-        }
-
-        if (attempt === maxAttempts) {
-            throw new Error(`${url} did not load successfully after ${attempt} attempts`);
-        }
-
-        await new Promise(resolve => setTimeout(resolve, 5000 * attempt));
-    }
+    await page.goto(url);
+    await expect(page.locator('#application'), `App booted for: ${url}`).toBeVisible();
+    await expect(page.locator('#not-found'), `Loaded successfully: ${url}`).not.toBeVisible();
+    await page.goBack();
 }
 
 async function linkWorks(page, selector) {

From 14ea2d1122a287acd951b12208c786b112497e18 Mon Sep 17 00:00:00 2001
From: Stephanie Hobson <stephaniehobson@users.noreply.github.com>
Date: Thu, 15 Oct 2026 10:14:53 -0700
Subject: [PATCH 3/4] Remove a link test that can no longer fail, and a stale
 PLANS.md claim (#79)

---
 .claude/skills/execplans/references/PLANS.md       |  3 +--
 .../2026-10-08-github-actions-ci-shorter.md        | 14 ++++++++++----
 tests/playwright/specs/home.spec.js                |  7 +------
 3 files changed, 12 insertions(+), 12 deletions(-)

diff --git a/.claude/skills/execplans/references/PLANS.md b/.claude/skills/execplans/references/PLANS.md
index c196b01..4ab1c19 100644
--- a/.claude/skills/execplans/references/PLANS.md
+++ b/.claude/skills/execplans/references/PLANS.md
@@ -208,8 +208,7 @@ The Playwright dashboard specs assert against live production data, so a failure
 from upstream data changing rather than from the commit. Re-run once before investigating, and say
 which it was.
 
-`AGENTS.md`'s toolchain description still predates the move to Vite; where it disagrees with the
-commands above, these win. Run each command and report the actual result; never claim a pass you
+Run each command and report the actual result; never claim a pass you
 did not observe. State the expected result, not just the command: "`npm run test:jest` — 2 files, 4
 tests passing" beats "run the tests".
 
diff --git a/docs/execplans/2026-10-08-github-actions-ci-shorter.md b/docs/execplans/2026-10-08-github-actions-ci-shorter.md
index b3bf8cc..9613c86 100644
--- a/docs/execplans/2026-10-08-github-actions-ci-shorter.md
+++ b/docs/execplans/2026-10-08-github-actions-ci-shorter.md
@@ -28,6 +28,8 @@ file), Dependabot (deliberately turned off in 2020), and automated deploy.
       suite, docs updated. Zizmor clean. Locally: Playwright 49 passed against a dev server on
       :3001 (see Surprises).
 - [x] (2026-10-08) Milestone 3: both jobs green on pull request #447.
+- [x] (2026-10-15) Review fix: deleted the home page's "All introduction links work" test, which
+      checked only external links and so could no longer fail.
 
 ## Surprises & Discoveries
 
@@ -123,8 +125,8 @@ The Playwright specs live in `tests/playwright/specs/`. Several of them call `li
 the same file. For a link inside the app, it navigates there and checks that `#application` renders
 and `#not-found` does not. For an external link, it opens the URL in a new browser page and expects
 HTTP 200, with three attempts and backoff, plus a redirect-only special case for
-`donate.mozilla.org`. `footer.spec.js` and the "All links work" test in `contact.spec.js` check only
-external and `mailto:` links. The `dashboards/*.spec.js` specs assert exact metric titles against
+`donate.mozilla.org`. `footer.spec.js`, the "All links work" test in `contact.spec.js`, and the "All
+introduction links work" test in `home.spec.js` check only external and `mailto:` links. The `dashboards/*.spec.js` specs assert exact metric titles against
 live production data on `data.firefox.com`, so a failure there can come from upstream data changing.
 
 Zizmor (<https://zizmor.sh/>) is a static checker for GitHub Actions workflows. It flags things like
@@ -171,8 +173,12 @@ and the Playwright suite no longer reaches outside the app.
    comment lines that described them. Replace them with one comment saying external links are not
    checked and why.
 2. Delete `tests/playwright/specs/footer.spec.js`. Delete the "All links work" test and the
-   `linksWork` import from `tests/playwright/specs/contact.spec.js`. Both checked only external and
-   `mailto:` links, so they would now pass while checking nothing.
+   `linksWork` import from `tests/playwright/specs/contact.spec.js`. Delete the "All introduction
+   links work" test and the `linksWork` import from `tests/playwright/specs/home.spec.js`; every
+   link in `#introduction` (`src/components/views/Home.jsx`) is external. All three checked only
+   external and `mailto:` links, so they would now pass while checking nothing. To find any others,
+   look at every `linkWorks` and `linksWork` call in `tests/playwright/specs/` and check where its
+   selector's links point.
 3. Add the `e2e` job to `ci.yml`: same checkout, setup-node, guard, and `npm ci` as Milestone 1,
    then `npx playwright install --with-deps chromium` and `npm run test:playwright`.
 4. Run Zizmor again.
diff --git a/tests/playwright/specs/home.spec.js b/tests/playwright/specs/home.spec.js
index d879323..7f972ed 100644
--- a/tests/playwright/specs/home.spec.js
+++ b/tests/playwright/specs/home.spec.js
@@ -1,5 +1,5 @@
 const { test, expect } = require('@playwright/test');
-const { linkWorks, linksWork } = require('../utils');
+const { linkWorks } = require('../utils');
 
 
 test.beforeEach(async ({ page }) => {
@@ -17,11 +17,6 @@ test('Page <title> is correct', async ({ page }) => {
     await expect(page).toHaveTitle('Firefox Public Data Report');
 });
 
-test('All introduction links work', async ({ page }) => {
-    await expect(page.locator('#introduction')).toBeVisible();
-    await linksWork(page, '#introduction a');
-});
-
 test('The "proceed button" appears', async ({ page }) => {
     await expect(page.locator('.next-button')).toBeVisible();
 });

From 0e34913bb06052c1e5be15ecbd56713f8634ab4a Mon Sep 17 00:00:00 2001
From: Stephanie Hobson <stephaniehobson@users.noreply.github.com>
Date: Thu, 15 Oct 2026 10:21:16 -0700
Subject: [PATCH 4/4] Compile CSS and bound job time in CI, and tidy link tests
 (#79)

---
 .github/workflows/ci.yml                      |  4 +++
 .../2026-10-08-github-actions-ci-shorter.md   | 31 +++++++++++++++----
 .../specs/dashboards/usage-behavior.spec.js   |  9 +-----
 tests/playwright/specs/footer.spec.js         | 10 ++++++
 4 files changed, 40 insertions(+), 14 deletions(-)
 create mode 100644 tests/playwright/specs/footer.spec.js

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e5f012e..662100f 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -17,6 +17,7 @@ jobs:
     lint-and-test:
         name: Lint and test
         runs-on: ubuntu-latest
+        timeout-minutes: 10
         if: github.repository == 'mozilla/ensemble'
         steps:
             - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -38,6 +39,7 @@ jobs:
     e2e:
         name: End-to-end tests
         runs-on: ubuntu-latest
+        timeout-minutes: 20
         if: github.repository == 'mozilla/ensemble'
         steps:
             - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
@@ -51,5 +53,7 @@ jobs:
               run: npm ci
             - name: Install Playwright browsers
               run: npx playwright install --with-deps chromium
+            - name: Compile Stylus
+              run: npm run build:css
             - name: Run end-to-end tests
               run: npm run test:playwright
diff --git a/docs/execplans/2026-10-08-github-actions-ci-shorter.md b/docs/execplans/2026-10-08-github-actions-ci-shorter.md
index 9613c86..cc252db 100644
--- a/docs/execplans/2026-10-08-github-actions-ci-shorter.md
+++ b/docs/execplans/2026-10-08-github-actions-ci-shorter.md
@@ -30,6 +30,9 @@ file), Dependabot (deliberately turned off in 2020), and automated deploy.
 - [x] (2026-10-08) Milestone 3: both jobs green on pull request #447.
 - [x] (2026-10-15) Review fix: deleted the home page's "All introduction links work" test, which
       checked only external links and so could no longer fail.
+- [x] (2026-10-15) Second review: compiled the CSS before Playwright in the `e2e` job, added
+      `timeout-minutes` to both jobs, restored a footer visibility test, and deleted the
+      usage-behavior "All metric description links work" test.
 
 ## Surprises & Discoveries
 
@@ -38,9 +41,9 @@ is kept on the local branches `79--github-actions-ci` and `79--github-actions-ci
 restated here so this plan stands alone.
 
 - Observation: `npm run test:jest` fails outright without the compiled CSS.
-  Evidence: "Failed to resolve import './css/MetricOverview.css'". The unit-test job must run
-  `npm run build:css` first. The end-to-end job does not, because Playwright starts `npm start`,
-  which compiles the Stylus.
+  Evidence: "Failed to resolve import './css/MetricOverview.css'". Both jobs run
+  `npm run build:css` first. `npm start` also compiles the Stylus, but in parallel with Vite, so
+  the end-to-end job can't rely on it.
 - Observation: `playwright.config.js` already adapts to CI. GitHub Actions sets `CI=true`, and the
   config then uses the `github` reporter (inline annotations on the pull request), 2 retries, 2
   workers, and refuses to reuse an existing server. The workflow needs to configure none of this.
@@ -81,6 +84,19 @@ restated here so this plan stands alone.
   Internal links are the ones this repository can break. The accepted cost is that external link
   rot, the kind #448 fixed, is no longer caught automatically.
   Date/Author: 2026-10-01, the user's decision on the earlier attempt; reconfirmed 2026-10-08.
+- Decision: delete "All metric description links work" in `dashboards/usage-behavior.spec.js`.
+  Rationale: the user's decision. On 2026-10-15 none of the three live metric descriptions
+  (`locale`, `pct_addon`, `top10addons`) contained a link, and the test did not wait for
+  descriptions to render, so it checked nothing.
+  Date/Author: 2026-10-15, the user's decision.
+- Decision: keep `footer.spec.js` as a single "Footer appears" visibility test.
+  Rationale: its old link test was also the only check that the footer renders at all.
+  Date/Author: 2026-10-15.
+- Decision: run `npm run build:css` in the `e2e` job even though `npm start` compiles Stylus.
+  Rationale: `npm start` runs Stylus and Vite in parallel, and Playwright starts as soon as Vite
+  answers, which can be before the CSS exists. Set `timeout-minutes` (10 and 20) so a hung dev
+  server doesn't hold a runner for GitHub's 6-hour default.
+  Date/Author: 2026-10-15.
 
 - Decision: reuse pull request #447 for this work rather than open a new one. Force-push this
   branch to `mozilla/79--github-actions-ci` and track that remote branch from here.
@@ -172,15 +188,18 @@ and the Playwright suite no longer reaches outside the app.
    now-unused status-code constants, the `donate.mozilla.org` special case, the retry loop, and the
    comment lines that described them. Replace them with one comment saying external links are not
    checked and why.
-2. Delete `tests/playwright/specs/footer.spec.js`. Delete the "All links work" test and the
+2. Replace the link test in `tests/playwright/specs/footer.spec.js` with one that checks the
+   footer is visible. Delete the "All links work" test and the
    `linksWork` import from `tests/playwright/specs/contact.spec.js`. Delete the "All introduction
    links work" test and the `linksWork` import from `tests/playwright/specs/home.spec.js`; every
    link in `#introduction` (`src/components/views/Home.jsx`) is external. All three checked only
    external and `mailto:` links, so they would now pass while checking nothing. To find any others,
    look at every `linkWorks` and `linksWork` call in `tests/playwright/specs/` and check where its
-   selector's links point.
+   selector's links point. Also delete "All metric description links work" in
+   `tests/playwright/specs/dashboards/usage-behavior.spec.js` (see the Decision Log).
 3. Add the `e2e` job to `ci.yml`: same checkout, setup-node, guard, and `npm ci` as Milestone 1,
-   then `npx playwright install --with-deps chromium` and `npm run test:playwright`.
+   then `npx playwright install --with-deps chromium`, `npm run build:css`, and
+   `npm run test:playwright`. Give the jobs `timeout-minutes: 10` and `timeout-minutes: 20`.
 4. Run Zizmor again.
 5. Update the docs. In `AGENTS.md`, add the end-to-end tests to the CI bullet. In
    `CONTRIBUTING.md`, add the same, and say that `linkWorks` and `linksWork` check only links
diff --git a/tests/playwright/specs/dashboards/usage-behavior.spec.js b/tests/playwright/specs/dashboards/usage-behavior.spec.js
index 795dc14..899bb41 100644
--- a/tests/playwright/specs/dashboards/usage-behavior.spec.js
+++ b/tests/playwright/specs/dashboards/usage-behavior.spec.js
@@ -1,5 +1,5 @@
 const { test, expect } = require('@playwright/test');
-const { linkWorks, linksWork, flagForUpdate, metricTitleIsCorrect, changeRegionAndWaitForMetrics } = require('../../utils');
+const { linkWorks, flagForUpdate, metricTitleIsCorrect, changeRegionAndWaitForMetrics } = require('../../utils');
 
 
 test.beforeEach(async ({ page }) => {
@@ -47,13 +47,6 @@ test('Table renders', async ({ page }) => {
     await flagForUpdate(page, '.metric-overview table', 'table in the usage dashboard', 1);
 });
 
-test('All metric description links work', async ({ page }) => {
-    // Not every metric description contains a link, so this doesn't assert
-    // one is present first - linksWork is a no-op if the selector matches
-    // nothing.
-    await linksWork(page, '.metric-description a');
-});
-
 test('The "proceed button" appears', async ({ page }) => {
     await expect(page.locator('.next-button')).toBeVisible();
 });
diff --git a/tests/playwright/specs/footer.spec.js b/tests/playwright/specs/footer.spec.js
new file mode 100644
index 0000000..35460e1
--- /dev/null
+++ b/tests/playwright/specs/footer.spec.js
@@ -0,0 +1,10 @@
+const { test, expect } = require('@playwright/test');
+
+
+test.beforeEach(async ({ page }) => {
+    await page.goto('/');
+});
+
+test('Footer appears', async ({ page }) => {
+    await expect(page.locator('footer')).toBeVisible();
+});