diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..13dd7c3
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,44 @@
+# Working on Amber Compare & Export
+
+A browser-only tool for Australian electricity bills (Amber Electric vs other plans, bill checks, a solar and battery planner). Read these first:
+
+- [README.md](README.md): what the app does, for users
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): modules, data model, each tab's flow, the planner engine, storage, releases
+- [docs/FRONTEND.md](docs/FRONTEND.md): the UI contract (IDs, data attributes, help keys, CSP) and known UI issues
+- [docs/REVIEW.md](docs/REVIEW.md): invariants, risk areas, technical debt, test map
+
+## Commands
+
+```bash
+npm install
+npm run build:css     # after changing any Tailwind class in index.html or js/; commit css/app.css
+npm run test:unit     # Node unit checks (fast)
+npm test              # unit checks + Playwright (starts scripts/static-server.js on :4173)
+npx playwright test tests/planner.spec.js --workers=2   # one spec
+npm run serve         # http://127.0.0.1:4173
+```
+
+If Playwright can't find its browser, point it at an installed Chromium with `launchOptions.executablePath` in a local config, not by editing `playwright.config.js`. Don't leave your own server running on port 4173 during a test run: Playwright reuses it.
+
+## Rules of the codebase
+
+- **No build step for JS, no framework, no ES modules.** Each `js/*.js` is an IIFE adding to `window.Amber`; the load order in `index.html` matters (`app.js` is last). New files need a `<script>` tag with `?v=<version>`, and the unit tests `require` them in order.
+- **CSP**: no inline scripts or styles, no `style="…"` in HTML or HTML strings, no third-party hosts. `element.style.x = …` from JS is fine.
+- **Tailwind classes must appear literally** in `index.html` or `js/`, or be safelisted in `tailwind.config.js`.
+- **IDs, `data-*` hooks and visible wording are used by the tests.** Change them together with `tests/*.spec.js`.
+- **Every `data-help="key"` needs an entry in `Amber.HELP`** (`js/help.js`), and new inputs and table headings should get one.
+- **Escape anything from data or the user** with `Amber.escapeHTML` before `innerHTML`.
+- **Keep pricing in one place.** Compare, month by month, Bill Check, Free? and the planner must agree on the same readings; `tests/unit-planner.js` checks the planner against Compare.
+- **Missing readings are never zero; NEM time is UTC+10 interval-end; templates are GST-inclusive** (see REVIEW.md invariants).
+- **Calculation modules stay DOM-free** so they run under Node.
+- **Writing style for the UI**: plain English for householders, Australian spelling, short sentences, units kWh, kW, c/kWh and $.
+
+## Releasing a change
+
+1. Bump the version everywhere it appears:
+   - `index.html`: the `<title>`, "Version X." in the header, and every `?v=X`;
+   - `js/constants.js`: `Amber.APP_VERSION`;
+   - `tests/unit-time.js`: the version assert.
+2. Update `README.md` and `docs/` if behaviour or structure changed.
+3. Run `npm run build:css` if classes changed, then `npm test`.
+4. Open a pull request. Merge only after the GitHub "Tests" check passes (GitHub Pages serves `main`).
diff --git a/README.md b/README.md
index 959cd54..d34d88c 100644
--- a/README.md
+++ b/README.md
@@ -1,77 +1,122 @@
 # Amber Compare & Export
 
-A browser-based tool for analysing [Amber Electric](https://www.amber.com.au/) usage, comparing costs with traditional suppliers, and exporting CSV data.
+A free, browser-only tool for Australian electricity customers. It shows what your power really costs on [Amber Electric](https://www.amber.com.au/) (wholesale prices), checks an Amber bill line by line, compares Amber with retailers' flat, time-of-use and free-power plans, and plans solar and battery purchases from a year of your own meter data. It also works for households that aren't on Amber, from their NEM12 meter file.
 
-Runs entirely in your browser. No installation required.
-
-## Quick start
+Everything runs in the browser: there is no server and no account, and nothing is uploaded.
 
 **[Launch the app](https://rickusinggithub.github.io/Amber/)**
 
-Open `index.html` on GitHub Pages, via `npm run serve`, or as a local file. Scripts are classic (not ES modules), so `file://` works in most desktop browsers.
-
-You need an Amber API key from [app.amber.com.au/developers](https://app.amber.com.au/developers), except to check a household that isn't on Amber (see below).
-
-## Features
-
-- Compare Amber vs a flat or time-of-use retailer plan, including controlled load and optional demand tariffs
-- Pre-built templates for each state, including 2026-27 Victorian Default Offer rates for all five networks
-- Time-varying feed-in (for example Synergy DEBS 10c peak / 2c off-peak), with optional daily kWh caps
-- Free-window plans: a free (or cheap) window with an optional daily kWh cap, a super off-peak / EV window, and seasonal peak windows. Templates for CovaU SolarMax, GloBird Four4Free, OVO The Free 4 Plan, and the Solar Sharer Offer for Ausgrid, Endeavour, Essential Energy, Energex and SA Power Networks
-- Written for everyday users: a welcome screen with two paths ("I'm with Amber" / "I'm thinking about Amber"), plain-English labels, a ? help bubble beside every input and table heading (hover, tap or keyboard; Escape closes), and a jargon buster on the Start tab
-- Six tabs: Start (welcome, Amber account, history import, non-Amber households, jargon buster), Compare (plan to compare with and its prices, the answer, every plan, month by month), Usage (one day, average day, calendar, more numbers), Bill? (an Amber bill checked line by line), Free? (what each free-power plan would cost if you moved some use into its free hours) and Solar+? (the solar and battery planner). Hovering a tab shows its full name. The dates bar appears once there's something to look at
-- Opens on This month and compares straight away when an API key is saved
-- Bill Check loads the bill period's meter data as soon as a bill is uploaded (and when you come back to the tab), then checks every line against your meter data: usage, peak demand and demand charges, daily supply, subscription, GST, charges total, solar exports and export credits
-- Import Amber's usage export (CSV) on Setup to go beyond the API's ~3 months: it fills the same cache as Compare (keeping days already fetched from the API and leaving the last week to the API), flags the network demand window (Ausgrid, Endeavour, Energex, Essential and Evoenergy demand tariffs; for other tariffs it is learned from the days Amber's API flagged), then compares the whole months imported. Last 12 months date preset
-- Re-scheduling estimate for free-window plans: re-times your real interval data into each plan's free window and best feed-in window, at the daily shift budgets you choose, over every whole month within the chosen dates. Battery size field (blank = auto from exports after dark, 0 = none): without a battery only load you move (EV, pool pump, hot water) shifts, and no battery exports are invented
-- Households not on Amber: import their meter data (NEM12, from their retailer or network; files with only the 200/300 data rows are fine, a meter that switches from 30- to 5-minute readings part way through is read correctly, and days with missing readings are left out rather than counted as zero, with the summary saying how many) on Setup and the app rebuilds what Amber would have charged for every interval: AEMO's 5-minute wholesale price for the region × a loss factor, plus Amber's 2026-27 network, market, environmental and hedging charges for the chosen network tariff (all 11 networks Amber serves), plus GST; feed-in at the wholesale price plus the export tariff. A second meter channel that is off most of the day is taken as controlled load (CL2 if it also runs in the daytime). Amber's daily, metering, subscription and demand charges come from the same tariff, and Amber's quarterly wholesale price cap is applied. No API key needed; the household appears as a site you can compare against any plan, including the free-window estimate. Checked against a year of real Amber prices on Ausgrid EA116/EA029: on average within 0.05 c/kWh per interval, and the year's usage and feed-in costs within 1% (the gap is last year's slightly lower network charges)
-- Demand charges worked out per calendar month, from each month's own peak
-- Ausgrid EA029 exports settled as on the bill: free midday allowance, with the export charge on usage
-- 24-hour average and daily charts, with competitor c/kWh in the hover tooltip
-- Daily calendar; click a day to open it on the graph
-- IndexedDB cache, GST toggle
-- CSV export of every meter reading, daily totals or the comparison table
-- Multi-site picker when your Amber account has more than one NMI
-- Editable Amber daily connection, subscription and demand rates for this financial year and last (days before 1 July 2026 use last year's); an uploaded bill fills the year it belongs to
-- More Stats: average import and feed-in prices, price-spike and negative-price exposure, evening import share, grid-free days
-- Solar & battery planner: from the last 12 months of meter readings (Amber's, an imported Amber CSV, or any household's NEM12), tries every mix of new solar size, battery size and plan for the network, half hour by half hour, and ranks them by 20-year value, payback or yearly bill. Every option is measured against one yardstick: nothing new on the plan to compare against, by default whichever of the plans you'd use is cheapest with nothing new (switching is free). Companies, or single plans, can be ticked or unticked: only ticked plans are searched and shown. Any of the three can be fixed ("a size I choose", "none", or one plan). Shows next year's bill month by month against today's, a payback chart at today's prices and ±20% (with the $0 line, where it's paid back, marked) (payback is when it's ahead for good, after any battery replacement), worth in today's money and IRR (a battery replaced within the years compared is credited with the life it has left at the end), a "How keen to be" rating (Not worth it, Marginal, Modest, Good or Strong, from the value per $1 up front, whether it still pays with prices 20% lower, and payback, plus whether waiting a year would cost anything), and a 'Where the saving comes from' breakdown for each option (power bought, power sent to the grid, export and demand charges, and where the new panels' power goes: used at home, stored or sent out, lost to the export limit or clipped by the inverter), a "wait a year" check, and what just switching plan would save. Each plan is priced exactly as on Compare (free windows and caps, capped and time-varying feed-in, demand, Amber's export charge); missing Amber feed-in prices are rebuilt from AEMO wholesale prices. The battery charges from spare solar and from free or cheap grid hours, covers the home when power is dear and sells into high feed-in prices, knowing each day's prices in the morning. The export limit applies to the whole home and is measured against what the meter already sent out; a battery stores spare solar before the limit throws the rest away. When a feed-in price is negative the panels switch off by default (a battery soaks up what it can first), so nothing is paid to export; a setting says if they can't, and then exporting at negative prices costs money. Where the feed-in price goes below zero (Amber), the recommendation and "what to ask installers for" say the panels need a "curtailable" inverter (one the retailer can switch off remotely), and on Amber a battery that SmartShift can run. A "Check the numbers" card for the option on show gives the average price paid per kWh bought and earned per kWh sent out (for the yardstick, the same plan with nothing new, and the option), daily and demand charges, the plan's average buy and feed-in prices through the day and how often feed-in is below zero, rules of thumb (kWh a day per kW of panels; what each kWh of new solar or battery output is worth against what it costs per kWh), and the settings it was worked out with. The "How keen to be" rating also checks the result if feed-in prices from 10am to 3pm halve. Solar comes from a PVGIS 5.3 typical year (ERA5) for 22 towns (`data/solar`, fetched by `scripts/update-solar.js`), with sun position, tilt, facing, shade, temperature and inverter clipping, scaled to PVGIS's own yield. Homes that already have panels or a battery: the app spots them in the readings (solar sent out; selling after dark or quiet nights) and pre-fills a guess. Existing panels stay in the readings and new ones are added on top. An existing battery is taken out of the readings (selling to the grid is seen directly; what it covered at home is estimated from its size, the days it filled up and ran flat, and the home's use on nights it was empty; its charging from spare solar first, then from the grid in the cheapest half hours that bought more than usual) and run again on every plan with any new battery, since it would behave differently on another plan. A check card compares the planner's run of that battery on today's plan with the real readings, and shows what the battery saves. Allows for the federal solar (STC) and battery rebates shrinking each year, hardware getting cheaper, panel and battery wear, battery and inverter replacement, the export limit, and planned changes: an electric car, heat-pump hot water, gas heating and cooking to electric (with the gas bill saved)
+## Contents
+
+- [Getting started](#getting-started)
+- [What each tab does](#what-each-tab-does)
+- [Where the numbers come from](#where-the-numbers-come-from)
+- [Data completeness and CSV backups](#data-completeness-and-csv-backups)
+- [Privacy](#privacy)
+- [For developers](#for-developers)
+- [Known limitations](#known-limitations)
+- [Disclaimer](#disclaimer)
+
+## Getting started
+
+Open the app (GitHub Pages, `npm run serve`, or `index.html` as a local file: the scripts are classic scripts, not ES modules, so `file://` works in most desktop browsers). The Start tab offers two paths:
+
+- **I'm with Amber**: paste an API key from [app.amber.com.au/developers](https://app.amber.com.au/developers). The app opens on This month and compares straight away whenever a key is saved. Amber's API reaches back about 3 months; import Amber's usage export (CSV) to go further.
+- **I'm thinking about Amber**: import the household's meter data (a NEM12 file from its retailer or network). No API key is needed.
+
+## What each tab does
+
+The tab bar is Start, Compare, Usage, Bill?, Free? and Solar+?. Hovering a tab shows its full name. The dates bar (dates, quick picks such as Last 12 months, and Compare costs) appears once there is something to look at. Every input and table heading has a **?** help bubble (hover, tap or keyboard; Escape closes), and the Start tab has a jargon buster.
+
+### Start
+
+- Connect an Amber account (API key, remembered on this device or for the session only), pick a site when the account has several NMIs, and edit Amber's daily connection, subscription and demand rates for this financial year and last (days before 1 July 2026 use last year's). An uploaded Amber bill fills the year it belongs to.
+- **Import Amber's usage export (CSV)** to go beyond the API's ~3 months. It fills the same cache as Compare, keeps days already fetched from the API, leaves the last week to the API, and flags the network demand window (Ausgrid, Endeavour, Energex, Essential and Evoenergy demand tariffs; for other tariffs it is learned from the days Amber's API flagged).
+- **Households not on Amber**: import a NEM12 file and the app rebuilds what Amber would have charged for every interval (see [Where the numbers come from](#where-the-numbers-come-from)). The household then appears as a site that works everywhere else in the app.
+
+### Compare
+
+- Pick a plan to compare with: pre-built templates for each state (including 2026-27 Default Market Offer and Victorian Default Offer rates, market offers, and the Solar Sharer Offer), or your own flat or time-of-use plan with controlled load, optional demand tariffs, time-varying feed-in (for example Synergy DEBS 10c peak / 2c off-peak) with optional daily kWh caps, and free-window plans (a free or cheap window with an optional daily cap, a super off-peak / EV window, and seasonal peak windows).
+- The answer for the chosen dates, every plan for your network ranked, and month by month. Demand charges are worked out per calendar month from each month's own peak, and Ausgrid EA029 exports are settled as on the bill (free midday allowance, export charge on usage). GST can be shown or hidden.
+- Download every meter reading, daily totals or the comparison table as CSV.
+
+### Usage
+
+- A 24-hour average and a daily chart (with the compared plan's c/kWh in the tooltip), a calendar (click a day to open it on the graph), and More Stats: average import and feed-in prices, price-spike and negative-price exposure, evening import share and grid-free days.
+
+### Bill?
+
+- Upload an Amber bill (PDF or text). The app loads the bill period's meter data and checks every line against it: usage, peak demand and demand charges, daily supply, subscription, GST, the charges total, solar exports and export credits.
+
+### Free?
+
+- For free-window plans (CovaU SolarMax, GloBird Four4Free, OVO The Free 4 Plan and the Solar Sharer Offer for Ausgrid, Endeavour, Essential Energy, Energex and SA Power Networks), a re-scheduling estimate re-times your real interval data into each plan's free window and best feed-in window, at the daily shift budgets you choose, over every whole month in the chosen dates. A battery size field (blank = worked out from exports after dark, 0 = none) controls whether a battery can shift exports; without one, only load you move (EV, pool pump, hot water) shifts.
+
+### Solar+?
+
+The solar and battery planner. From the last 12 months of meter readings (Amber's, an imported Amber CSV, or a NEM12 file) it tries every mix of new solar size, battery size and plan for the network, half hour by half hour, and ranks them by 20-year value, payback or yearly bill.
+
+- **What you can set**: panels, battery and plan can each be "find the best", "a size I choose", "none", or one plan. Companies, or single plans, can be ticked or unticked; only ticked plans are searched and shown. Roof size, facing, pitch, shade, town, export limit, whether panels switch off at negative feed-in prices, battery round trip and power, prices and rebates, wear and replacement, price rises, the interest rate and planned changes (an electric car, heat-pump hot water, gas heating and cooking to electric with the gas bill saved).
+- **The yardstick**: every option is measured against nothing new on the plan you compare against; by default that's whichever ticked plan is cheapest for you with nothing new, since switching is free.
+- **What it shows**:
+  - the best option, with what to ask installers for (panel, inverter and battery sizes; a "curtailable" inverter where the feed-in price goes below zero, and on Amber a battery SmartShift can run);
+  - a **How keen to be** rating (Not worth it, Marginal, Modest, Good or Strong). It comes from the value per $1 up front, whether it still pays with prices 20% lower or with 10am–3pm feed-in halved, and payback, plus whether waiting a year would cost anything;
+  - every option ranked, and next year month by month against today;
+  - **Where the saving comes from**: power bought, power sent out, export and demand charges, and where the new panels' power goes (used at home, stored or sent out, lost to the export limit, switched off at negative prices, or clipped by the inverter);
+  - **Check the numbers**: average c/kWh bought and earned, daily charges, the plan's prices through the day, rules of thumb (kWh a day per kW of panels; what each kWh of new solar or battery output is worth against what it costs) and the settings used;
+  - **Paying it back**: a chart at today's prices and ±20%, with the $0 line marked. Payback is when it's ahead for good, after any battery replacement. Worth is in today's money, with IRR, and a battery replaced within the years compared is credited with the life it has left.
+- **Homes that already have panels or a battery**: the app spots them in the readings and pre-fills a guess. Existing panels stay in the readings and new ones are added on top. An existing battery is taken out of the readings, then run again on every plan together with any new battery, and a check card compares the planner's version of it with the real readings.
+
+## Where the numbers come from
+
+- **Amber prices**: Amber's API (or its usage export) gives each interval's price. Fixed charges come from the rates on the Start tab.
+- **Other plans**: templates in `js/templates.js`, from published tariffs (AER and ESC default offers, Energy Made Easy, retailer fact sheets), each with an "as at" date.
+- **The NEM12 estimate** (households not on Amber): AEMO's 5-minute wholesale price for the region × a loss factor, plus Amber's 2026-27 network, market, environmental and hedging charges for the chosen network tariff (all 11 networks Amber serves), plus GST. Feed-in is the wholesale price plus the export tariff, and Amber's quarterly wholesale price cap is applied. A second meter channel that is off most of the day is taken as controlled load (CL2 if it also runs in the daytime). NEM12 files with only 200/300 rows are fine, a meter that switches from 30- to 5-minute readings part way through is read correctly, and days with missing readings are left out rather than counted as zero. Checked against a year of real Amber prices on Ausgrid EA116/EA029: within 0.05 c/kWh per interval on average, and the year's usage and feed-in costs within 1%.
+- **Wholesale prices**: `data/prices/<region>/<month>.json`, refreshed daily from AEMO by a GitHub Action (`scripts/update-prices.js`).
+- **Solar**: a PVGIS 5.3 typical year (ERA5) for 22 towns (`data/solar`, fetched once by `scripts/update-solar.js`), with sun position, tilt, facing, shade, temperature and inverter clipping, scaled to PVGIS's own yield.
 
 ## Data completeness and CSV backups
 
-- When selected dates contain days without readings, Compare labels the result **Incomplete comparison**. Usage costs omit missing readings, while fixed charges and export allowances cover the full selected period. Savings are provisional until the missing readings are available. The calendar labels missing days **No readings**, rather than treating them as zero usage. Daily CSV and calendar totals cover only dates with readings and may therefore differ from an incomplete full-period comparison.
-- Daily free-power and feed-in caps are shared across the household's meter channels. Ausgrid export settlement adjustments are allocated to days in proportion to midday exports, so daily totals reconcile with the selected period's settlement. These allocations are not separate daily export allowances.
-- **Download → Every meter reading** produces a versioned CSV that can be restored through the existing Amber usage CSV import on the Start tab, for the same Amber site. It preserves original NEM interval-end times, duration, quality, renewables and demand flags, including zero-use channels. Whole-day backups can restore recent and estimated readings; cached final API days are still kept, and estimated readings remain eligible for API refresh. Incomplete days are not restored. Earlier app exports without the version column are not supported as backups; Amber's own usage export remains supported. For a non-Amber household, retain its original NEM12 file for re-import.
+- When the selected dates contain days without readings, Compare labels the result **Incomplete comparison**. Usage costs leave out missing readings, while fixed charges and export allowances cover the full period, so savings are provisional until the missing readings arrive. The calendar labels missing days **No readings** rather than treating them as zero use. Daily CSV and calendar totals cover only dates with readings and may differ from an incomplete full-period comparison.
+- Daily free-power and feed-in caps are shared across the household's meter channels. Ausgrid export settlement adjustments are allocated to days in proportion to midday exports, so daily totals reconcile with the period's settlement; they aren't separate daily allowances.
+- **Download → Every meter reading** produces a versioned CSV that can be restored through the Amber usage CSV import on the Start tab, for the same Amber site. It keeps the original NEM interval-end times, duration, quality, renewables and demand flags, including zero-use channels. Whole-day backups can restore recent and estimated readings; cached final API days are kept, and estimated readings can still be refreshed from the API. Incomplete days aren't restored. App exports from before the version column aren't supported as backups (Amber's own usage export is). For a non-Amber household, keep its original NEM12 file to re-import.
 
 ## Privacy
 
-- The API key is stored only in this browser (localStorage or sessionStorage). It is obfuscated, not encrypted.
-- Usage data is requested directly from `https://api.amber.com.au` and never sent anywhere else. Imported files (Amber CSV, NEM12, bills) are read in the browser and stay there.
-- Wholesale prices for the NEM12 estimate are files in this repo (`data/prices`), refreshed daily from AEMO by a GitHub Action (`scripts/update-prices.js`).
-- Uncheck **Remember key on this device** to keep the key in the session only.
-- The last checked bill's line items stay in localStorage until you click **Clear**.
+- The API key is stored only in this browser (localStorage, or sessionStorage if **Remember key on this device** is unticked). It is obfuscated, not encrypted.
+- Usage data is requested directly from `https://api.amber.com.au` and never sent anywhere else; the page's Content Security Policy allows no other connections. Imported files (Amber CSV, NEM12, bills) are read in the browser and stay there.
+- Meter readings are cached in IndexedDB; settings, saved plans, imported households and the last checked bill (until **Clear**) are in localStorage. The settings menu (cog) can clear the cache and saved plans.
 
-## Local development
+## For developers
 
 ```bash
-npm install
-npm run build:css
-npm test
-npm run serve
+npm install          # Tailwind CLI and Playwright
+npm run build:css    # css/input.css -> css/app.css (commit the result)
+npm test             # unit checks, then Playwright against a local static server
+npm run test:unit    # unit checks only
+npm run serve        # http://127.0.0.1:4173
 ```
 
-`npm test` runs the unit checks (time and TOU, bill reading, More Stats, demand, Bill Check, re-scheduling, usage import, NEM12 estimate, solar & battery planner), then Playwright against a local static server. `npm run test:unit` runs only the unit checks.
+There is no bundler and no framework: plain JavaScript files share one `window.Amber` namespace and load in order from `index.html`. Tests run in GitHub Actions on every pull request.
+
+More detail for contributors and reviewers:
+
+- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md): how the code is organised, the data model, how each tab works, the planner engine, storage, external data, build, tests and releases.
+- [docs/FRONTEND.md](docs/FRONTEND.md): the UI as it stands, what a redesign must keep (IDs, data attributes, help keys, CSP), styling, accessibility and known UI issues.
+- [docs/REVIEW.md](docs/REVIEW.md): a guide for code review: invariants, where the risk is, known technical debt and open questions.
+- [CLAUDE.md](CLAUDE.md): short working rules for AI coding agents.
 
 ## Known limitations
 
 - Amber API rate limits still apply; fetches run a few chunks at a time and retry 429s.
 - Retailer templates are estimates from published tariffs. Check Energy Made Easy or the retailer's current fact sheet before switching.
 - Public holidays are not treated as off-peak.
-- Comparison accuracy depends on the Amber fixed charges you enter (they vary by network).
+- Comparison accuracy depends on the Amber fixed charges entered (they vary by network).
 - Imported usage has no renewables or price-spike details. Demand windows ignore public holidays, and Energex/Essential monthly demand charges are approximated as daily ones.
 - The re-scheduling estimate uses meter data only (no battery telemetry): it assumes each day's shift budget is available and leaves midday solar exports where they were.
 - Sites with several general meters (E1 + E2) have demand worked out on their combined use.
 - The NEM12 estimate assumes the household keeps using power exactly as it did. With a battery on Amber, SmartShift would usually do better. Loss factors other than Ausgrid's are typical values, not measured; seasonal and monthly demand charges are spread by month; Evoenergy's off-peak demand charge is not modelled.
-- The planner uses last year's usage and today's plan prices (Amber: last year's interval prices) for every future year, scaled by the price rise you set. Its battery knows each day's prices in advance, so a real one may do a little worse; network tariff changes after installing, VPP payments and blackout backup aren't counted. West-facing solar may read slightly low because the typical-year weather has cloudier afternoons. An existing battery's work at home can't be seen on the meter, so taking it out of the readings is an estimate; the check card shows how close it comes, but can't tell if the battery size entered is wrong (take off any backup reserve). Hardware and rebate defaults are rough late-2026 guides: use your quotes.
+- The planner uses last year's usage and today's plan prices (Amber: last year's interval prices) for every future year, scaled by the price rise you set. Its battery knows each day's prices in advance, so a real one may do a little worse. Network tariff changes after installing, VPP payments and blackout backup aren't counted. West-facing solar may read slightly low because the typical-year weather has cloudier afternoons. An existing battery's work at home can't be seen on the meter, so taking it out of the readings is an estimate; the check card shows how close it comes, but can't tell if the battery size entered is wrong (take off any backup reserve). Hardware and rebate defaults are rough late-2026 guides: use your quotes.
 - Bill Check reads the Amber bill layouts seen so far. If it can't read a bill, it shows the text it read so the reader can be fixed.
 
 ## Disclaimer
diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md
new file mode 100644
index 0000000..5c87d10
--- /dev/null
+++ b/docs/ARCHITECTURE.md
@@ -0,0 +1,228 @@
+# Architecture
+
+How Amber Compare & Export is put together, for contributors and reviewers. User-facing features are in the [README](../README.md); the UI contract for a redesign is in [FRONTEND.md](FRONTEND.md); review notes are in [REVIEW.md](REVIEW.md).
+
+## At a glance
+
+- **A static site** (GitHub Pages) with one page, `index.html`. There is no server, no backend and no account. Network traffic is limited to Amber's API (`https://api.amber.com.au/v1`) and the site's own files (`data/…`), enforced by a Content Security Policy in `index.html`.
+- **Plain JavaScript, no framework and no bundler.** Each file in `js/` is an IIFE that adds to a single global namespace, `window.Amber` (or `globalThis.Amber` under Node). The files are classic `<script>` tags loaded in a fixed order, so `file://` works.
+- **Logic and UI are mostly separate.** Calculation modules (`costs`, `monthly`, `estimate`, `redispatch`, `planner`, `solar`, `stats`, `bill`, `import`, `time`, `templates`, `networks`) don't touch the DOM and are unit-tested in Node. DOM code lives in `app.js` (everything except the planner), `planner-ui.js` (the Solar+? tab), `charts.js`, `calendar.js`, `help.js` and parts of `csv.js` and `storage.js`.
+- **Styling** is Tailwind CSS 3, prebuilt by the Tailwind CLI from `css/input.css` into `css/app.css` (committed). There's no runtime CSS-in-JS and no inline `<style>`.
+- **Vendored libraries** in the repository root: Chart.js 4.4.2 (`chart.umd.min.js`), chartjs-plugin-zoom (`chartjs-plugin-zoom.min.js`) and pdf.js (`pdf.min.js`, `pdf.worker.min.js`, loaded on demand for bill PDFs).
+- **Storage**: IndexedDB for meter readings (a per-site, per-day cache), localStorage for settings, saved plans, imported households and the last bill check.
+
+## Repository layout
+
+```
+index.html               The whole page: header, dates bar, tab bar, six tab panels, footer, script tags
+css/input.css            Tailwind source (base layer + a few component classes)
+css/app.css              Built CSS (npm run build:css), committed
+js/                      Application code (see the module map)
+data/prices/<REGION>/    AEMO 5-minute wholesale prices, one JSON per month (NSW1, QLD1, SA1, VIC1)
+data/solar/<town>.json   PVGIS typical-year hourly weather for 22 towns
+scripts/static-server.js Tiny static server for development and Playwright (port 4173)
+scripts/update-prices.js Downloads AEMO prices into data/prices (run daily by a GitHub Action)
+scripts/update-solar.js  Downloads PVGIS weather into data/solar (run by hand)
+tests/unit-*.js          Node unit checks (no framework: assert + console)
+tests/*.spec.js          Playwright end-to-end tests (Chromium)
+.github/workflows/       test.yml (tests on PRs and main), update-prices.yml (daily price refresh)
+chart.umd.min.js, chartjs-plugin-zoom.min.js, pdf.min.js, pdf.worker.min.js   Vendored libraries
+```
+
+## Script load order and the `Amber` namespace
+
+`index.html` loads, in order:
+
+```
+chart.umd.min.js, chartjs-plugin-zoom.min.js
+js/constants.js   js/help.js      js/time.js      js/templates.js   js/storage.js
+js/costs.js       js/api.js       js/bill.js      js/csv.js         js/charts.js
+js/calendar.js    js/stats.js     js/monthly.js   js/redispatch.js  js/import.js
+js/networks.js    js/estimate.js  js/solar.js     js/planner.js     js/planner-ui.js
+js/app.js
+```
+
+Every file starts with `const Amber = root.Amber = root.Amber || {};` and attaches functions and constants as `Amber.something`. Later files may use anything earlier files define. `app.js` is last and starts the page (`init()` on `DOMContentLoaded`). Every script URL carries `?v=<version>` to bust caches.
+
+Under Node (unit tests), files are `require`d in the same order and attach to `global.Amber`; DOM-free modules work unchanged.
+
+There are two cross-module UI hooks:
+
+- `Amber.appApi` (set in `app.js`) gives `planner-ui.js` what it needs from the main app: `selectedSite`, `currentStateCode`, `readAmberRates`, `templates()`, `selectedPlanName()` and `selectTab`. The planner reads the meter cache itself through `storage.js`.
+- `Amber.plannerUi = { show, run }` (set in `planner-ui.js`) is called by `app.js` when the Solar+? tab opens.
+
+`Amber._appState` exposes `app.js`'s internal state for tests and debugging.
+
+## Module map
+
+| File | Lines | Owns |
+|---|---|---|
+| `constants.js` | ~130 | API URL and fetch limits, app version, Amber's default fixed charges (this year and last), state time zones, network names and plan-to-network matching, plan company names (`planCompany`) |
+| `help.js` | ~310 | `Amber.HELP` (every help text, keyed) and the help-bubble behaviour for any `[data-help]` element |
+| `time.js` | ~250 | Dates and times: NEM time (UTC+10) vs local wall clock, interval end times, TOU window matching, day arithmetic |
+| `templates.js` | ~570 | Built-in retailer plans per state (`supplierTemplates`), with "as at" dates |
+| `storage.js` | ~220 | IndexedDB cache (`AmberDataCacheDB` → `dailyUsage`, key `<siteId>_<YYYY-MM-DD>`), cache freshness rules, API key storage (obfuscated), `escapeHTML` |
+| `costs.js` | ~910 | Pricing a period: per-channel totals from usage items, TOU periods, other plans' costs (flat/TOU, controlled load, feed-in windows and caps, free windows), demand tariffs (Amber and other plans), Amber fixed charges, Ausgrid export settlement, `computePlanTotals` |
+| `api.js` | ~230 | Amber API client: sites, usage in date chunks, timeouts, retries with backoff, a small promise pool |
+| `bill.js` | ~360 | Reading an Amber bill (PDF via pdf.js, or text): rates, period, line items; `compareBill` checks it against meter data |
+| `csv.js` | ~85 | CSV downloads: every reading (a versioned, restorable backup), daily totals, the results table |
+| `charts.js` | ~440 | Usage tab charts (24-hour average, daily) with Chart.js plugins |
+| `calendar.js` | ~360 | Usage tab calendar and its day tooltips |
+| `stats.js` | ~60 | More Stats figures (price spikes, negative prices, evening share, grid-free days) |
+| `monthly.js` | ~130 | `periodTotals` / `monthlyBreakdown`: Amber vs another plan per calendar month, worked out the same way as Compare |
+| `redispatch.js` | ~350 | Free? tab: re-timing real interval data into a plan's free and feed-in windows under daily shift budgets |
+| `import.js` | ~380 | Amber usage CSV import into the cache (API-shaped items, demand window flags) |
+| `networks.js` | ~280 | Network tariffs and Amber's charges for all 11 networks Amber serves (FY2026-27), for the NEM12 estimate |
+| `estimate.js` | ~400 | NEM12 parsing and the rebuild of Amber's interval prices from wholesale prices, as a local "site" |
+| `solar.js` | ~220 | Towns, PVGIS weather loading, sun position, panel output per half hour (tilt, facing, shade, temperature, inverter clipping) |
+| `planner.js` | ~1,480 | Solar+? engine: the half-hourly year, plan rate cards, exact costing, flows, existing-battery detection and unwinding, battery simulation, the search, finance and ratings |
+| `planner-ui.js` | ~1,180 | Solar+? tab UI: inputs and settings, running the search, every results card |
+| `app.js` | ~3,010 | Everything else in the UI: tabs, Start, Compare (plan form, results, all plans, month by month), Usage, Bill?, Free?, imports, settings menu, `init()` |
+
+## Data model
+
+### Sites and channels
+
+A site is either Amber's (from `GET /sites`) or local, an imported NEM12 household (`{ id, local: true, nmi, network, channels, … }`, kept in localStorage `localSites`). Channels have `identifier` and `type` (`general`, `controlledLoad`, `feedIn`) and a `tariff` code.
+
+### Usage items
+
+The unit of meter data is the Amber API's usage item, one per channel per interval:
+
+```
+{ channelIdentifier, channelType, nemTime (interval end, NEM time), startTime, endTime, duration (min),
+  date (NEM date), kwh, perKwh (c/kWh inc GST; feed-in negative = credit), cost, quality,
+  spikeStatus, renewables, tariffInformation: { demandWindow, … } }
+```
+
+Imports (Amber CSV, NEM12 estimate) produce the same shape, so every feature works on any source.
+
+### The cache
+
+IndexedDB `AmberDataCacheDB`, store `dailyUsage`, one record per site and NEM date (`id = "<siteId>_<date>"`). Compare reads the cache first and fetches only missing or stale days, in 7-day chunks, 3 at a time (`Amber.FETCH_CHUNK_DAYS`, `FETCH_CONCURRENCY`). Final whole days are cached. Old days with no data are remembered as empty (`emptyDayCutoff`). Estimated readings stay eligible for refetch (`cachedDayUsable`).
+
+### Channel totals
+
+`Amber.processUsageData(items, channelTotals)` turns items into per-channel totals plus the per-interval detail the cost functions need. `Amber.emptyChannel(c)` creates one entry per channel. Everything on Compare, Usage and Bill? is computed from these.
+
+### Plan configs
+
+A plan (built-in template or saved custom plan):
+
+```
+{ rateType: 'flat' | 'tou', flat, daily (c/day), feedIn, cl (controlled load c/kWh), clock: 'local' | 'nem',
+  tou: { free: { rate, capKwh, windows }, superOffpeak, peak: { rate, windows: [{ start, end, days }] },
+         shoulder, offpeak: { rate } },
+  feedInWindows: [{ rate, start, end, days, capKwh, overRate }],
+  demand: { e (enabled), … window and rate fields }, asAt }
+```
+
+TOU period names and labels are in `Amber.PERIOD_LABELS`. Days are 0 = Sunday. Rates in templates are GST-inclusive c/kWh and c/day; feed-in is the published rate. `templates.js` has the full set; `app.js` `createPlanObjectFromForm` builds one from the plan form.
+
+### The planner's year
+
+`Amber.planYear(byDate)` turns the cache into a 365-day, half-hourly year (`n = 365 × 48` slots, NEM time):
+
+```
+{ ok, dates[365], n, days, imp, exp, cl (kWh per slot), amberImp, amberCl, amberExp (c/kWh, negative = credit),
+  demandFlag, filled, first, last, meterExp (after an existing battery is unwound), … }
+```
+
+Missing days (up to 31) are filled from the nearest whole day on the same weekday. Every plan's rate windows start on the hour or half hour, so half-hourly pricing equals pricing the 5-minute readings: the planner's cost of the unchanged year matches Compare exactly. `tests/unit-planner.js` checks this.
+
+## How each tab works
+
+### Start (`app.js`: `setupStartTab`, imports, sites)
+
+- API key: `Amber.setApiKey` stores an obfuscated key in localStorage (or sessionStorage); `Amber.fetchSites` lists sites.
+- Amber's fixed charges: `loadAmberChargeFields` / `readAmberRates`. The two years' connection, subscription and demand rates are split at `Amber.AMBER_RATES_CHANGE_DATE` (1 July 2026). Uploading a bill (`handleAmberBillFile` → `bill.js`) fills the year it belongs to.
+- Amber CSV import: `handleUsageCsvFile` → `import.js` → `setUsageDataMany`.
+- NEM12: `handleNem12File` → `estimate.js` parses the file and rebuilds Amber's interval prices from `data/prices` and `networks.js`. The result becomes a local site whose days are written to the cache.
+
+### Compare (`app.js`: `fetchAndCompare`, `displayResults`, `renderAllPlansTable`, `renderMonthly`)
+
+1. Read the cache for the dates, fetch what's missing (`api.js`) and write final days back.
+2. `processUsageData` → channel totals; `applyAmberFeedInSettlement` (Ausgrid EA029 export settlement).
+3. `calculateOtherSupplierCosts` (the chosen plan), `calculateDemandTariff` / `calculateOtherDemandTariff` (monthly peaks), `precalculateDailySummaries` (daily rows and calendar).
+4. Render the answer, every plan for the network (`computePlanTotals` per template), then month by month (`monthly.js`, after the main results).
+
+### Usage (`charts.js`, `calendar.js`, `stats.js`)
+
+Uses the same channel totals and daily summaries. Charts use the interval's local time and real interval length.
+
+### Bill? (`bill.js`, `app.js` bill check section)
+
+Reads the bill (pdf.js is loaded on demand), loads that period's meter data (from the cache or API), and `compareBill` checks each line. The last result is kept in localStorage `amberBillCheck`.
+
+### Free? (`redispatch.js`, `app.js` battery re-scheduling section)
+
+For each free-window plan, re-times each day's real readings. Grid use moves into the free window (dearest first) within a daily shift budget, the window's cap and an import limit. Battery exports move into the best feed-in window when a battery is present. The result is priced with the same cost functions as Compare.
+
+### Solar+? (`planner.js`, `solar.js`, `planner-ui.js`)
+
+```
+cache ──planYear──▶ year ──(existing battery?)──plannerUnwindBattery──▶ year without it
+                                                       │
+solar.js: town weather → solarSlotsPerKw → clipToInverter (panels/1.33)
+plannerExtraLoads: EV, heat-pump hot water, gas to electric
+                                                       ▼
+plannerSearch(ctx) ── plannerPrepare (rate cards, prices, flows cache)
+   for each solar size × plan: plannerFlows (import/export after solar, export limit)
+   for battery sizes on the best few plans: simulateBattery
+   ▼ rows { solarKw, batteryKwh, plan, bill, … }
+planner-ui analyse(): yardstick, options, plannerFinance (NPV, IRR, payback), plannerKeenLevel
+```
+
+Key pieces:
+
+- **Rate cards** (`planRateCard`): each plan's buy, sell and controlled-load price per slot, plus free windows, feed-in windows and caps, and demand. `planCardCost` and `amberCardCost` price any import/export arrays for the year or a month; `plannerMonths` gives month ranges.
+- **Flows** (`plannerFlows`): adds new solar and extra loads to the readings, then applies the export limit. The limit is `max(limit, what the meter already sent)`, and `expRaw` keeps what would have gone out before the limit.
+- **Negative feed-in**: by default (`switchOffNegative`), exports at a negative sell price are dropped (`exportsFor`, or `curtailNegative` in the battery run). The UI says this needs a curtailable inverter.
+- **Battery** (`simulateBattery`): one day at a time with that day's prices known (perfect daily foresight). It searches a charge threshold and a discharge threshold per day. It charges from solar over the export cap first, then from cheap or free grid; it discharges into dear use and high feed-in. Charge and discharge share the power limit, and a small wear cost per kWh stops pointless cycling. `limited` counts what's thrown away at the export limit.
+- **Existing battery**: `plannerDetectExisting` guesses panels and battery from the readings. `plannerUnwindBattery` removes the battery's effect (grid sales are seen directly; what it covered at home is estimated), and the search re-runs it on every plan with any new battery. `plannerExistingCheck` compares the planner's version with the real readings.
+- **Search** (`plannerSearch`): every solar size on every plan without a battery. A probe battery ranks plans, then the full battery search runs on the best `keepPlans` (6) plus any that must be included. `allowPlans` limits the plans considered to those ticked.
+- **Money** (`plannerCapex`, `plannerFinance`): the up-front cost after rebates. Then year by year: savings grow with price rises and shrink with panel and battery wear, the battery and inverter are replaced, and a battery replaced inside the period is credited with its remaining life. The results are NPV, IRR, payback "ahead for good" (and the first time it reaches $0), and `plannerWaitAYear`.
+- **Ratings** (`plannerKeenLevel`): the value per $1 up front (≥1.75 Strong, ≥1.4 Good, ≥1.15 Modest). Strong and Good also need the result to hold with prices 20% lower and with 10am–3pm feed-in halved (`dayFeedInScale`), and payback within 8 years.
+- **UI** (`planner-ui.js`): `search()` gathers inputs, `analyse()` builds options against the yardstick, and the `render*` functions build each card as HTML strings (escaped with `esc`).
+
+## Storage keys
+
+| Where | Key | What |
+|---|---|---|
+| IndexedDB | `AmberDataCacheDB` / `dailyUsage` | Meter readings per site and day |
+| localStorage | `amberApiKey` (or sessionStorage) | Obfuscated API key |
+| localStorage | `selectedSiteId`, `startDate`, `endDate`, `activeTab` | Where the user was |
+| localStorage | `selectedState`, `selectedPlan`, `rateType`, `planName`, `flatRate`, `flatFeedInRate`, `flatControlledLoad`, `dailyConnectionRate`, `touConfig`, `feedInWindows`, `enableFeedInTou`, `demandSettings`, `ratesDetailsOpen` | The Compare plan form |
+| localStorage | `customSupplierPlans` | Saved custom plans |
+| localStorage | Amber charge field IDs | Amber's fixed charges (this year and last) |
+| localStorage | `localSites` | Imported NEM12 households |
+| localStorage | `batteryShiftSettings` | Free? tab settings |
+| localStorage | `amberBillCheck` | The last bill check |
+| localStorage | `plannerSettings` | Every Solar+? input and the company ticks |
+
+## External data
+
+- **AEMO prices**: `scripts/update-prices.js` downloads `PRICE_AND_DEMAND_<YYYYMM>_<REGION>.csv` from AEMO into `data/prices/<REGION>/<YYYY-MM>.json` as `{ region, month, interval: 5, rrp: [...] }` ($/MWh, interval ending `month-01 00:00 + (i+1)×5 min` NEM time). `.github/workflows/update-prices.yml` runs it daily at 1:17 am AEST and commits changes.
+- **PVGIS weather**: `scripts/update-solar.js` downloads a typical meteorological year (hourly GHI, DNI, DHI and temperature) and PVGIS's own 1 kW yield for each town in `Amber.SOLAR_LOCATIONS`. It's run by hand; the files don't change.
+- **Plan prices**: maintained by hand in `templates.js` (with `asAt` dates) and `networks.js` (Amber's FY2026-27 network tariffs). `Amber.TEMPLATES_AS_AT` is shown in the UI.
+
+## Security and privacy
+
+- The CSP (`index.html` `<meta http-equiv="Content-Security-Policy">`) is `default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self' https://api.amber.com.au; img-src 'self' data:; …`. This means no inline scripts, no inline `<style>` and no `style="…"` attributes (setting `element.style.x` from JS is fine), and no third-party hosts.
+- All data stays in the browser. The API key is obfuscated (XOR with a fixed key, then base64), not encrypted.
+- Dynamic HTML is built with template strings. Anything from data or user input goes through `Amber.escapeHTML` (aliased `esc` in `planner-ui.js`).
+
+## Build, test and CI
+
+- `npm run build:css` rebuilds `css/app.css`. Tailwind scans `index.html` and `js/**/*.js` for class names, and `tailwind.config.js` safelists classes that are only built dynamically. Commit `css/app.css` after changing classes.
+- **Unit checks**: `tests/unit-*.js`, run with plain `node` (`npm run test:unit`). Each prints `ok:` / `FAIL:` lines and exits non-zero on failure. `unit-planner.js` holds the parity checks: the planner's cost equals Compare's, battery energy balances, finance and ratings.
+- **End-to-end**: `tests/*.spec.js` with Playwright (Chromium) against `scripts/static-server.js` on port 4173 (`playwright.config.js`, `reuseExistingServer: true`). Tests mock Amber's API with `page.route('**/api.amber.com.au/**', …)` and build NEM12 files in code. About 54 tests take about 45 s with two workers.
+- **CI**: `.github/workflows/test.yml` runs `npm ci`, installs Chromium and runs `npm test -- --workers=2` on every pull request and on pushes to `main`. Failed runs upload `test-results/`.
+
+## Releases
+
+Each change ships as a version:
+
+1. Bump the version in three places: `index.html` (the `<title>`, the "Version X." line in the header, and every `?v=` query string), `js/constants.js` (`Amber.APP_VERSION`), and `tests/unit-time.js` (the version assert).
+2. `npm run build:css` if classes changed; update the README and these docs if behaviour changed.
+3. Run `npm test`, open a pull request, and merge once the Tests check passes. GitHub Pages serves `main`.
diff --git a/docs/FRONTEND.md b/docs/FRONTEND.md
new file mode 100644
index 0000000..a175fb8
--- /dev/null
+++ b/docs/FRONTEND.md
@@ -0,0 +1,134 @@
+# Frontend guide
+
+What the UI is today, what any redesign has to keep working, and where it could be better. Read with [ARCHITECTURE.md](ARCHITECTURE.md) (code structure) and [REVIEW.md](REVIEW.md) (review notes).
+
+## Constraints a redesign must respect
+
+1. **No build step for JavaScript.** Classic scripts loaded in order from `index.html`, sharing `window.Amber`. A framework or bundler would be a project-level decision, not part of a visual refresh. The page must keep working from `file://` and GitHub Pages.
+2. **Content Security Policy** (`index.html`): `script-src 'self'; style-src 'self'`. That rules out inline `<script>`, inline `<style>`, `style="…"` attributes in HTML or in HTML strings built by JS, and CDN fonts or scripts. Setting `element.style.width` etc. from JS is allowed, and is how progress bars are sized. Fonts must be self-hosted (today the system font stack is used).
+3. **Tailwind is prebuilt.** Classes must appear literally in `index.html` or `js/**/*.js` for `npm run build:css` to include them; classes assembled from pieces at runtime must be listed in `tailwind.config.js` `safelist`. Commit the rebuilt `css/app.css`.
+4. **IDs and data attributes are an API.** The JS looks elements up by ID (`$('id')` / `getElementById`) and the Playwright tests use about 135 distinct `#id` selectors and the `data-*` hooks listed below. Rename one only with its JS and tests.
+5. **Help keys.** Every `data-help="key"` must exist in `Amber.HELP` (`js/help.js`). A test fails on unknown keys, and another fails if a visible planner input has no help button nearby.
+6. **Independent tool.** This isn't Amber Electric's app. Don't adopt Amber's branding (logo, colours, typography) in a refresh. Consider saying "independent, not affiliated with Amber Electric" near the title; it isn't said explicitly today.
+7. **Everything stays in the browser.** No analytics, external fonts, maps or embeds; the CSP's `connect-src` allows only `'self'` and `https://api.amber.com.au`.
+
+## Page structure
+
+```
+header        title, one-line description, version, settings cog (#settingsBtn → #settingsMenu)
+#configSection  "Dates to look at": #startDate, #endDate, #fetchData (Compare costs), [data-preset] quick picks,
+                #messageContainer, #progressBar; hidden until there's something to look at
+#mainTabs     role="tablist": #tab-setup … #tab-plan (data-tab), scrolls sideways on a phone, never wraps
+#resultTools  GST switch (#gstToggle), Download menu (#downloadCsvButton → #csvDropdownMenu)
+main          six <section role="tabpanel" id="panel-…" data-panel="…">, one visible at a time
+footer        #disclaimerShort, <details id="disclaimer">, ko-fi link
+```
+
+The layout is a single centred column (`max-w-4xl`) of white cards (`bg-white rounded-lg shadow-md p-6`) on `bg-gray-100`. The accent colour is Tailwind indigo, with green/red for savings and costs, and amber/orange for warnings.
+
+### Tabs
+
+| Tab | Button / panel | What's on it |
+|---|---|---|
+| Start | `#tab-setup` / `#panel-setup` | `#welcomeCard` (two choice cards: with Amber / thinking about Amber), `#connectedCard`, `#setupSection` (API key `#apiKey`, `#rememberApiKey`, site picker `#siteSelectorRow`, `<details id="amberChargesDetails">` Amber's fixed charges and bill upload), `#usageImportSection` (Amber CSV), NEM12 import (`#nem12File`, `#nem12Build`, `#localSitesList`), `<details id="glossarySection">` jargon buster |
+| Compare | `#tab-compare` / `#panel-compare` | Jump links (`[data-jump]`), `#planChooser` (`#planSelector`, `#ratesDetails`: flat / TOU / feed-in windows / demand forms), `#resultsSection` (`#estimateBanner`, `#qualityBanner`, the answer `#results-table-container`), `#allPlansSection`, `#monthlySection`, `#freePowerPointer` |
+| Usage | `#tab-check` / `#panel-check` | `#dailyGraphSection` (`#dailyChart`, day selector), `#averageGraphContainer` (`#usagePriceChart`), `#calendarSection`, `#moreStatsSection` |
+| Bill? | `#tab-bill` / `#panel-bill` | `#billCheckSection` (upload, `#billCheckBody` line-by-line table) |
+| Free? | `#tab-free` / `#panel-free` | `#freePowerEmpty` (nothing to show yet), `#batteryShiftSection` (budgets, battery size, `#batteryShiftTable`, `#batteryShiftMonthly`) |
+| Solar+? | `#tab-plan` / `#panel-plan` | `#planDataStatus`, `#planInputs` (home, what you already have, what to work out, `<details id="planRetailers">` company ticks, Roof and panels, Prices and rebates `#planCostInputs`, Changes you're planning), `#planRun`, `#planProgress`, `#planResults`: `#planRecommendation`, `#planExistingCheck`, options `#planOptionsTable` (`#planRankBy`), `#planDetailBody`, `#planNumbersBody`, payback `#planPaybackChart` + `#planPaybackNotes`, `#planAssumptions` |
+
+Tab behaviour (`app.js` `selectTab`, `setupTabs`): `aria-selected`, roving `tabindex`, Left/Right/Home/End keys, and the last tab remembered in localStorage `activeTab`. The dates bar and the GST/Download tools are hidden until there's something to look at (`syncConnectedUi`) and on Solar+?, which always uses the last 12 months. Panels before results show a `[data-results-placeholder]` pointing to Start (`[data-go-start]`).
+
+### Data attributes used as hooks
+
+| Attribute | Used for |
+|---|---|
+| `data-tab`, `data-panel` | Tab buttons and panels |
+| `data-go-tab`, `data-go-start` | Links that switch tab |
+| `data-preset` | Date quick picks (`7d`, `thisMonth`, `lastMonth`, `3m`, `90d`, `12m`) |
+| `data-jump`, `data-jump-nav` | In-page jump links |
+| `data-results-placeholder` | "Nothing here yet" blocks |
+| `data-help`, `data-help-label` | Help bubbles (key into `Amber.HELP`, or plain text; label for screen readers) |
+| `data-tou-period`, `data-add-tou-window`, `data-remove-window` | TOU plan form |
+| `data-date`, `data-month-key` | Calendar days and months |
+| `data-local-use`, `data-local-remove`, `data-nem` | Imported households list, NEM12 options |
+| `data-bill-reload` | Bill check reload |
+| `data-plan-option` | Rows of the planner options table (`-1` = yardstick, `-2` = cheapest with nothing new) |
+| `data-plan`, `data-company`, `data-plan-all`, `data-plan-show`, `data-plan-go` | Planner company and plan ticks |
+| `data-keen`, `data-curtail`, `data-numbers` | Planner result blocks (the tests read these) |
+
+## Styling system
+
+- `css/input.css` = Tailwind base + a `@layer components` with the app's own classes:
+  - `.main-tab`: tabs, one line on a phone, bigger from `sm`;
+  - `.jump-link`;
+  - `.plan-input`: planner inputs;
+  - `.plan-multi`: the company ticks dropdown;
+  - `.calendar-day`, `.day-checkbox-label`;
+  - `.gst-switch`: a CSS-only toggle;
+  - `.help-btn`, `.help-row`, `.help-bubble`: help bubbles, with a bigger tap target on coarse pointers;
+  - `.choice-card`, `.step-num`: the Start tab.
+- Everything else is Tailwind utilities written straight into `index.html` and into HTML strings in `app.js` / `planner-ui.js`. Common patterns are repeated rather than shared: card, table (`min-w-full divide-y divide-gray-200 text-sm`, `thead bg-gray-50`, `px-2 py-2` cells), small grey notes (`text-xs text-gray-500`) and buttons (indigo primary, white bordered secondary).
+- There's no dark mode and no design tokens beyond Tailwind's default palette.
+
+## JS-built UI
+
+Most result content is built as HTML strings and set with `innerHTML`:
+
+- **`app.js`**:
+  - the answer table and banners (`displayResults`);
+  - every plan (`renderAllPlansTable`) and month by month (`renderMonthly`);
+  - Free? (`drawBatteryShift`), bill check (`renderBillCheck`) and More Stats (`renderMoreStats`);
+  - imported households (`renderLocalSites`);
+  - the settings menu (`buildSettingsMenu`) and the modal (`showModal`).
+- **`planner-ui.js`**: every Solar+? results card (`renderRecommendation`, `renderExistingCheck`, `renderOptions`, `renderDetail` + `breakdownHtml`, `renderNumbers`, `renderPayback`, `renderAssumptions`), and the company tick panel. Small helpers `th()` and `td()` keep its tables consistent.
+- **`calendar.js`**: the calendar grid and its tooltips (appended to `body`).
+- **`charts.js`** and `planner-ui.js` `renderPayback`: Chart.js charts (`#dailyChart` and `#usagePriceChart` with zoom and pan via chartjs-plugin-zoom, and `#planPaybackChart` with the $0 line drawn darker).
+
+Text from data or the user goes through `Amber.escapeHTML` (`esc`). Keep that when changing markup.
+
+## Responsive behaviour
+
+- The tab bar stays on one line from 320 px up and scrolls sideways (tested at 320, 360 and 390 px), and the page itself never scrolls sideways (tested).
+- Wide tables sit in cards with `overflow-x-auto` and scroll inside the card on a phone. The planner's options table (7 columns) and month table are the widest.
+- Planner inputs are grids that collapse to one column (`grid-cols-1 sm:grid-cols-2/3`).
+
+## Accessibility today
+
+- Skip link to the tabs; ARIA tabs with keyboard support; labelled inputs; the GST switch is a real checkbox; help buttons are buttons with `aria-expanded` and can be opened by keyboard and closed with Escape.
+- The planner options table rows are `role="button"` with `tabindex="0"`, and Enter/Space select them.
+- Charts have an `aria-label` on the canvas. The numbers are also in nearby tables (month table, payback notes), but there's no table alternative for the Usage charts.
+- The rating dots have `role="img"` and an `aria-label` ("3 of 4").
+- Colour carries meaning in places (green saves, red costs), usually alongside a sign or a word.
+
+## Writing style
+
+The app is written for everyday Australian householders:
+
+- Plain English with short sentences. Say what something means for the reader ("Pays back in 6.7 years"), not jargon ("ROI").
+- Australian spelling and units: kWh, kW, c/kWh, $ with commas.
+- Every input and table heading gets a help bubble. The jargon buster explains the terms that can't be avoided (feed-in, NEM12, controlled load, demand charge, TOU).
+- **Known inconsistency**: percentages are "20%" in most of the app but "20 %" (with a space) in the Solar+? tab. Pick one in a refresh.
+
+## Known UI issues and opportunities
+
+- **Solar+? is long and text-heavy.** Results stack as: recommendation, rating, battery check, options, month table, breakdown, check the numbers, payback, assumptions. Many paragraphs are full sentences of figures. Candidates: a summary strip of 3–4 key numbers, progressive disclosure (`<details>`) for the breakdown, numbers and assumptions, and a sticky "option on show" header.
+- **Inputs on Solar+?** are spread over several `<details>` groups. "Prices and rebates" has 18 numeric fields in one grid.
+- **Compare's plan form** (flat / TOU / feed-in windows / demand) is dense and shown under the results, and custom plans are edited in place.
+- **Tables** are styled inline in several places with small differences. A shared table component (CSS classes in `input.css`) would make them consistent.
+- **Charts**: the payback chart's x labels rotate on narrow screens. The Usage charts would benefit from a legend and colour review. Chart colours are hard-coded hex values in `charts.js` and `planner-ui.js`.
+- **Visual hierarchy**: every card has the same weight; the main answer on each tab could stand out more.
+- **Help bubbles** are everywhere, which helps beginners but adds visual noise. Consider showing them only on hover or focus on wider screens.
+- **The settings menu** mixes user actions (clear cache, clear saved plans) with maintainer tools ("Save custom plans", "Show stats"; IDs `saveCustomPlansForRick`, `showStatsForRick`).
+- **Loading and progress**: Compare and Solar+? each have their own progress bar and message area.
+- **No dark mode**; no print stylesheet, though a print or PDF view of the planner result could be useful to take to installers.
+
+## Checking a UI change
+
+```bash
+npm run build:css
+npm test                       # or: npx playwright test tests/planner.spec.js
+npm run serve                  # then open http://127.0.0.1:4173
+```
+
+To see results without an Amber key, import a NEM12 file on Start. The Playwright helpers `nem12Year()` and `nem12Battery()` in `tests/planner.spec.js` generate a year of readings for a household without and with solar and a battery. Check at 320, 375 and 1024 px wide, with the keyboard only, and with a long plan name.
diff --git a/docs/REVIEW.md b/docs/REVIEW.md
new file mode 100644
index 0000000..d301970
--- /dev/null
+++ b/docs/REVIEW.md
@@ -0,0 +1,83 @@
+# Code review guide
+
+Notes for anyone reviewing this codebase: what it must keep doing, where mistakes would cost users money, the technical debt we know about, and questions worth an opinion. Start with [ARCHITECTURE.md](ARCHITECTURE.md) for the layout, and [FRONTEND.md](FRONTEND.md) if the review covers the UI.
+
+## Running it
+
+```bash
+npm install
+npm run build:css
+npm test            # ~10 unit scripts, then ~54 Playwright tests (~45 s with --workers=2)
+npm run serve       # http://127.0.0.1:4173
+```
+
+Without an Amber API key, use the "Not with Amber?" path on Start with a NEM12 file. The tests build them in code (`nem12Year()`, `nem12Battery()` in `tests/planner.spec.js`). CI runs the same `npm test` on every pull request (`.github/workflows/test.yml`).
+
+## Invariants: what must stay true
+
+These are the properties the tests guard and that users rely on. A change that breaks one is a bug, even if the UI looks fine.
+
+1. **One way of pricing.** Compare, month by month (`monthly.js`), Bill Check, the Free? estimate and the Solar+? planner must price the same readings on the same plan to the same total. The planner's half-hourly costing (`planCardCost`, `amberCardCost`) is checked against `computePlanTotals` in `tests/unit-planner.js`, and `monthly.js` mirrors the Compare table.
+2. **Missing readings are never zero.** Days without readings are left out of usage costs and flagged ("Incomplete comparison", "No readings"). Fixed charges still cover the whole period. The planner fills at most 31 missing days from the same weekday and says so.
+3. **Time is explicit.** Amber's `nemTime` is an interval's end in NEM time (UTC+10, no daylight saving). Plan windows are local wall-clock time unless a plan says `clock: 'nem'`. Interval-end semantics matter at window edges (`Amber.intervalEndInWindow`, `timeInWindow`). The planner's slots are NEM half hours.
+4. **GST is consistent.** Templates are GST-inclusive; `networks.js` figures are ex GST and GST is added in `estimate.js`; household feed-in is GST-free. The GST toggle only changes the display (`adjustForGst`).
+5. **The cache is trustworthy.** Only final whole days are cached. Estimated readings stay refetchable, and empty old days are remembered as empty. The CSV backup round-trips (`tests/review.spec.js`).
+6. **Nothing leaves the browser** except requests to Amber's API with the user's key. The CSP enforces this; keep it.
+7. **User and data text is escaped** (`Amber.escapeHTML` / `esc`) before going into `innerHTML`.
+8. **The planner is fair between options.** Every option is measured against the same yardstick, and the same rules (export limit, negative feed-in switch-off, battery dispatch) apply on every plan.
+
+## Where the risk is
+
+| Area | Why it matters | Where |
+|---|---|---|
+| Plan prices | Stale or mistyped rates give wrong answers that look plausible. Templates are typed in by hand from fact sheets; each has `asAt`. | `templates.js`, `networks.js`, `constants.js` (Amber fixed charges) |
+| Feed-in caps and windows, free windows | Daily caps shared across channels, over-cap rates, Ausgrid's EA029 midday export allowance and charge. These are easy to get subtly wrong. | `costs.js` (`householdCappedSplits`, `settleAmberFeedIn`, `applyAmberFeedInSettlement`) |
+| Demand charges | Monthly peaks, demand windows, seasonal rates, days counted per month. | `costs.js` (`calculateMonthDemandTariff`, …), `planner.js` (card demand) |
+| The NEM12 estimate | Loss factors other than Ausgrid's are typical values; controlled load is guessed from channel shape. | `estimate.js`, `networks.js` |
+| Battery dispatch | A per-day heuristic with perfect daily foresight. It's optimistic for real batteries, especially on Amber price spikes. | `planner.js` `simulateBattery` |
+| Unwinding an existing battery | Estimates what the battery covered at home, which the meter can't see. The check card shows the gap against real readings. | `planner.js` `plannerUnwindBattery`, `plannerExistingCheck` |
+| Finance | Price rises, wear, replacements, residual value, payback "ahead for good", IRR. Small errors move recommendations. | `planner.js` `plannerFinance`, `plannerKeenLevel`, `plannerWaitAYear` |
+| Bill parsing | Depends on the layout of Amber's PDF text; new layouts break it. Unreadable bills show the text read. | `bill.js` |
+| Big UI files | `app.js` (~3,000 lines, module-level state) and `planner-ui.js` (~1,200) mix data handling and HTML building. | `app.js`, `planner-ui.js` |
+
+## Known technical debt
+
+- **`app.js` is a monolith.** Tabs, plan form, results, imports, bill check, Free? and settings live in one IIFE sharing a `state` object. Natural seams: the plan form (`createPlanObjectFromForm`, `applyPlanTemplate`, TOU windows), results rendering, imports (CSV, NEM12, local sites), the bill check, the Free? tab and settings.
+- **HTML as strings.** Most results are template strings set with `innerHTML`, with table markup repeated (`th`/`td` helpers exist only in `planner-ui.js`). It's safe while everything is escaped, but verbose and easy to make inconsistent.
+- **No linter, formatter or type checking.** There's no ESLint or Prettier config; the style is 4-space indentation, single quotes and semicolons. JSDoc comments exist on many engine functions but not throughout.
+- **Home-made unit test harness.** `tests/unit-*.js` use their own `assert` and print `ok:`/`FAIL:`. They work, but give no per-test isolation or coverage.
+- **End-to-end tests depend on IDs and wording.** Many assertions match visible text, so copy edits need test edits too.
+- **Yearly maintenance is manual.** Each 1 July: the default offers and VDO in `templates.js`, Amber's network tariffs in `networks.js` (FY2026-27 today), Amber's default fixed charges and `AMBER_RATES_CHANGE_DATE` in `constants.js`, rebate and hardware defaults in `PLANNER_FINANCE_DEFAULTS`, and `TEMPLATES_AS_AT`. Market offers drift during the year.
+- **Vendored libraries** are pinned copies: Chart.js 4.4.2, chartjs-plugin-zoom 2.0.1, pdf.js 3.11.174. Updating them is manual.
+- **The price-update workflow** uses Node 20 actions, which GitHub is deprecating (a warning only). `test.yml` already uses Node 22.
+- **Maintainer tools in the settings menu** ("Save custom plans", "Show stats"; IDs `saveCustomPlansForRick`, `showStatsForRick`) sit alongside user actions.
+- **The API key** is obfuscated, not encrypted. That's fine for a browser-only tool, but it shouldn't be described as secure.
+- **Number formatting** varies: percentages are "20%" in most places but "20 %" on Solar+?. Money uses `toLocaleString('en-AU')` in some places and `toFixed` in others.
+
+## Questions worth a reviewer's opinion
+
+1. Is it worth splitting `app.js` along the seams above before a frontend refresh, so the refresh doesn't have to touch pricing code?
+2. Should HTML building move to small render helpers (or `<template>` elements in `index.html`) to cut repetition, while staying build-free and within the CSP?
+3. Would a lint/format setup (ESLint + Prettier, run in CI) be welcome, given the no-build constraint?
+4. Is the planner's battery heuristic good enough, or should it be compared against a simple linear-programming optimum for a few test days to measure how optimistic it is?
+5. Should the Solar+? search move to a Web Worker (it runs on the main thread today, yielding with `setTimeout(0)`)? The CSP already allows `worker-src 'self'`.
+6. Should the app say explicitly that it's independent of Amber Electric (see FRONTEND.md)?
+7. Is there anything in the data handling that a privacy-minded user would object to?
+
+## Test map
+
+| Test | Covers |
+|---|---|
+| `unit-time.js` | Dates, NEM vs local time, TOU windows, app version |
+| `unit-bill.js`, `unit-billcheck.js` | Bill reading and line-by-line checks |
+| `unit-stats.js` | More Stats |
+| `unit-demand.js` | Demand charges |
+| `unit-redispatch.js` | Free? re-scheduling |
+| `unit-import.js` | Amber CSV import |
+| `unit-estimate.js` | NEM12 parsing and the Amber price rebuild |
+| `unit-planner.js` | Planner: parity with Compare, flows, export limit, battery energy balance, existing battery, negative feed-in, midday halving, finance and ratings |
+| `unit-review.js` | Regression checks from an earlier review: household caps across channels, export settlement, missing vs zero days, CSV backup timestamps |
+| `autoload`, `cache`, `import`, `review` specs | Opening state, the cache, CSV import and backup round trip |
+| `ui`, `tabs`, `graphs`, `stats`, `performance` specs | Tabs, help bubbles, disclaimer, phone layout, charts, More Stats, fetch behaviour |
+| `billcheck`, `shift`, `v140` specs | Bill?, Free?, financial-year rate switching |
+| `nem12`, `planner` specs | The NEM12 path and every Solar+? flow |
diff --git a/index.html b/index.html
index b8f0d41..dd3a2d3 100644
--- a/index.html
+++ b/index.html
@@ -4,9 +4,9 @@
     <meta charset="UTF-8">
     <meta name="viewport" content="width=device-width, initial-scale=1.0">
     <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'self' https://api.amber.com.au; img-src 'self' data:; font-src 'self'; worker-src 'self'; base-uri 'self'; form-action 'self'">
-    <title>Amber Compare &amp; Export v1.60</title>
+    <title>Amber Compare &amp; Export v1.61</title>
     <link rel="icon" href="favicon.ico" type="image/x-icon">
-    <link rel="stylesheet" href="css/app.css?v=1.60">
+    <link rel="stylesheet" href="css/app.css?v=1.61">
 </head>
 <body class="bg-gray-100 text-gray-800">
     <a href="#mainTabs" class="sr-only focus:not-sr-only focus:absolute focus:top-2 focus:left-2 focus:z-50 focus:bg-white focus:px-3 focus:py-2 focus:rounded">Skip to the tabs</a>
@@ -19,7 +19,7 @@ <h1 class="text-2xl sm:text-3xl font-bold text-gray-900 flex items-center">
                         <img src="favicon.ico" alt="" class="mr-3 h-12 w-12 sm:h-14 sm:w-14"> Amber Compare &amp; Export
                     </h1>
                     <p class="mt-2 text-gray-600">See what your electricity really costs on Amber, check an Amber bill, and find out whether another plan (or Amber) would be cheaper for you.</p>
-                    <p class="mt-1 text-xs text-gray-500">Free and private: everything runs in this browser and nothing is uploaded. Version 1.60.</p>
+                    <p class="mt-1 text-xs text-gray-500">Free and private: everything runs in this browser and nothing is uploaded. Version 1.61.</p>
                 </div>
                 <div class="relative flex items-center">
                     <button id="settingsBtn" type="button" aria-label="Settings" aria-haspopup="true" aria-expanded="false" class="p-2 rounded-full text-gray-500 hover:bg-gray-100 hover:text-gray-700 focus:outline-none focus:ring-2 focus:ring-offset-2 focus:ring-indigo-500">
@@ -798,26 +798,26 @@ <h3 class="text-xl font-bold text-gray-900 mb-1" data-help="planPayback">Paying
 
     <script src="chart.umd.min.js"></script>
     <script src="chartjs-plugin-zoom.min.js"></script>
-    <script src="js/constants.js?v=1.60"></script>
-    <script src="js/help.js?v=1.60"></script>
-    <script src="js/time.js?v=1.60"></script>
-    <script src="js/templates.js?v=1.60"></script>
-    <script src="js/storage.js?v=1.60"></script>
-    <script src="js/costs.js?v=1.60"></script>
-    <script src="js/api.js?v=1.60"></script>
-    <script src="js/bill.js?v=1.60"></script>
-    <script src="js/csv.js?v=1.60"></script>
-    <script src="js/charts.js?v=1.60"></script>
-    <script src="js/calendar.js?v=1.60"></script>
-    <script src="js/stats.js?v=1.60"></script>
-    <script src="js/monthly.js?v=1.60"></script>
-    <script src="js/redispatch.js?v=1.60"></script>
-    <script src="js/import.js?v=1.60"></script>
-    <script src="js/networks.js?v=1.60"></script>
-    <script src="js/estimate.js?v=1.60"></script>
-    <script src="js/solar.js?v=1.60"></script>
-    <script src="js/planner.js?v=1.60"></script>
-    <script src="js/planner-ui.js?v=1.60"></script>
-    <script src="js/app.js?v=1.60"></script>
+    <script src="js/constants.js?v=1.61"></script>
+    <script src="js/help.js?v=1.61"></script>
+    <script src="js/time.js?v=1.61"></script>
+    <script src="js/templates.js?v=1.61"></script>
+    <script src="js/storage.js?v=1.61"></script>
+    <script src="js/costs.js?v=1.61"></script>
+    <script src="js/api.js?v=1.61"></script>
+    <script src="js/bill.js?v=1.61"></script>
+    <script src="js/csv.js?v=1.61"></script>
+    <script src="js/charts.js?v=1.61"></script>
+    <script src="js/calendar.js?v=1.61"></script>
+    <script src="js/stats.js?v=1.61"></script>
+    <script src="js/monthly.js?v=1.61"></script>
+    <script src="js/redispatch.js?v=1.61"></script>
+    <script src="js/import.js?v=1.61"></script>
+    <script src="js/networks.js?v=1.61"></script>
+    <script src="js/estimate.js?v=1.61"></script>
+    <script src="js/solar.js?v=1.61"></script>
+    <script src="js/planner.js?v=1.61"></script>
+    <script src="js/planner-ui.js?v=1.61"></script>
+    <script src="js/app.js?v=1.61"></script>
 </body>
 </html>
diff --git a/js/api.js b/js/api.js
index a97087d..69ee7de 100644
--- a/js/api.js
+++ b/js/api.js
@@ -1,6 +1,13 @@
 (function (root) {
     const Amber = root.Amber = root.Amber || {};
 
+    /*
+     * Amber API client (https://api.amber.com.au/v1): the site list, and usage for a date range
+     * fetched in chunks of Amber.FETCH_CHUNK_DAYS, a few at a time (mapPool). Every request has a
+     * timeout; 429s, server errors and network failures are retried after Amber.RETRY_DELAYS_MS.
+     * The caller (app.js fetchAndCompare) caches what comes back (storage.js).
+     */
+
     Amber.sleep = function (ms) {
         return new Promise((resolve) => setTimeout(resolve, ms));
     };
diff --git a/js/app.js b/js/app.js
index 3148513..aa41b0c 100644
--- a/js/app.js
+++ b/js/app.js
@@ -1,6 +1,16 @@
 (function (root) {
     const Amber = root.Amber = root.Amber || {};
 
+    /*
+     * The page controller for everything except the Solar+? tab (planner-ui.js): start-up (init),
+     * tabs, the Start tab (API key, sites, Amber's fixed charges, Amber CSV and NEM12 imports), the
+     * dates bar, Compare (the plan form, fetchAndCompare, the answer, every plan, month by month),
+     * Usage (charts, calendar, More Stats), Bill?, Free? (the re-scheduling estimate), downloads and
+     * the settings menu. Pricing lives in costs.js / monthly.js; this file reads inputs, calls it
+     * and renders the results. Module state is in `state` (exposed as Amber._appState for tests);
+     * Amber.appApi is what planner-ui.js may use. See docs/ARCHITECTURE.md.
+     */
+
     const state = {
         templates: Amber.cloneTemplates(),
         originalTemplates: Amber.cloneTemplates(),
diff --git a/js/bill.js b/js/bill.js
index e8da3d1..b28bb93 100644
--- a/js/bill.js
+++ b/js/bill.js
@@ -1,6 +1,14 @@
 (function (root) {
     const Amber = root.Amber = root.Amber || {};
 
+    /*
+     * Amber bills: the text of a PDF (pdf.js, loaded on demand) or a text file is read into the bill
+     * period, Amber's fixed rates (connection, subscription, demand) and the line items
+     * (parseAmberBillText, parseBillCheck). compareBill then checks each line against the meter
+     * data for the same period. Used by the Bill? tab, and on Start to fill Amber's fixed charges.
+     * Layout-dependent: if a bill can't be read, the caller shows the text that was read.
+     */
+
     function roundCents(n) {
         if (!Number.isFinite(n)) return null;
         return Math.round(n * 1000) / 1000;
diff --git a/js/calendar.js b/js/calendar.js
index a5ab0fe..e7c74fc 100644
--- a/js/calendar.js
+++ b/js/calendar.js
@@ -1,6 +1,13 @@
 (function (root) {
     const Amber = root.Amber = root.Amber || {};
 
+    /*
+     * The Usage tab's calendar: a grid per month of the days in the selected period, with the
+     * day's cost on Amber and on the plan compared with in a tooltip (and Amber's demand peaks);
+     * clicking a day opens it on the daily graph. Days without readings say so rather than
+     * showing zero.
+     */
+
     Amber.hideTooltip = function () {
         const tooltip = document.getElementById('day-tooltip');
         if (tooltip) tooltip.remove();
diff --git a/js/charts.js b/js/charts.js
index a60321a..e07b2ce 100644
--- a/js/charts.js
+++ b/js/charts.js
@@ -1,6 +1,14 @@
 (function (root) {
     const Amber = root.Amber = root.Amber || {};
 
+    /*
+     * The Usage tab's Chart.js charts: the 24-hour average day (displayAverageGraph) and one day
+     * up close (displayDailyGraph), per channel (general, controlled load, feed-in) with Amber's
+     * price and the compared plan's c/kWh in the tooltip, on local time and the real interval
+     * length, with zoom and pan (chartjs-plugin-zoom). registerChartPlugins adds the cursor
+     * tooltip and the hover highlight once.
+     */
+
     Amber.registerChartPlugins = function () {
         if (!root.Chart || Amber._chartPluginsRegistered) return;
         root.Chart.Tooltip.positioners.cursor = function (items, eventPosition) {
diff --git a/js/constants.js b/js/constants.js
index ac244ae..bb1f1e0 100644
--- a/js/constants.js
+++ b/js/constants.js
@@ -1,6 +1,14 @@
 (function (root) {
     const Amber = root.Amber = root.Amber || {};
 
+    /*
+     * App-wide settings and reference data: Amber API limits, the app version (APP_VERSION, also
+     * in index.html and tests/unit-time.js), Amber's default fixed charges for this financial year
+     * and last (split at AMBER_RATES_CHANGE_DATE), state time zones, network names and matching
+     * plans to a site's network, and the company behind each plan (planCompany). Update each
+     * 1 July with templates.js and networks.js.
+     */
+
     Amber.API_URL = 'https://api.amber.com.au/v1';
     Amber.FETCH_CHUNK_DAYS = 7;
     Amber.FETCH_CONCURRENCY = 3;
@@ -12,7 +20,7 @@
     // Compare "This month" when the page opens with a saved API key (a test can preset
     // window.Amber.AUTO_COMPARE = false to start idle).
     Amber.AUTO_COMPARE = Amber.AUTO_COMPARE !== false;
-    Amber.APP_VERSION = '1.60';
+    Amber.APP_VERSION = '1.61';
     Amber.TEMPLATES_AS_AT = '2026-07-01';
     // All editable rates (plans, custom, Amber fixed charges) are GST-inclusive,
     // matching Energy Made Easy, DMO/VDO, retailer fact sheets and Amber perKwh.
diff --git a/js/costs.js b/js/costs.js
index f42d114..b4fbe2d 100644
--- a/js/costs.js
+++ b/js/costs.js
@@ -1,6 +1,20 @@
 (function (root) {
     const Amber = root.Amber = root.Amber || {};
 
+    /*
+     * Pricing a period of meter data. processUsageData turns API-shaped usage items into
+     * per-channel totals (with each interval kept for re-pricing); from those:
+     *   - Amber: interval prices, the Ausgrid EA029 export settlement (applyAmberFeedInSettlement),
+     *     demand per calendar month (calculateDemandTariff), daily connection and subscription
+     *     for the year each day falls in (amberRatesOn);
+     *   - another plan (calculateOtherSupplierCosts, computePlanTotals): flat or time-of-use rates,
+     *     free windows with daily caps, controlled load, flat, windowed and capped feed-in (caps
+     *     shared across channels: householdCappedSplits), demand (calculateOtherDemandTariff);
+     *   - daily rows for the calendar and CSV (precalculateDailySummaries).
+     * Compare, month by month (monthly.js), Bill Check and Free? all price through here; the
+     * planner's half-hourly costing is checked against computePlanTotals (tests/unit-planner.js).
+     */
+
     Amber.absKwh = function (value) {
         const n = parseFloat(value);
         if (!Number.isFinite(n)) return 0;
diff --git a/js/csv.js b/js/csv.js
index a119585..98e1d78 100644
--- a/js/csv.js
+++ b/js/csv.js
@@ -1,6 +1,11 @@
 (function (root) {
     const Amber = root.Amber = root.Amber || {};
 
+    /*
+     * CSV downloads: every meter reading (a versioned file that the Amber CSV import on Start can
+     * restore as a backup), one row per day, or the comparison table as shown.
+     */
+
     Amber.downloadCSV = function (csvContent, fileName) {
         const blob = new Blob([csvContent], { type: 'text/csv;charset=utf-8;' });
         const link = document.createElement('a');
diff --git a/js/monthly.js b/js/monthly.js
index b7c7f16..d7894b1 100644
--- a/js/monthly.js
+++ b/js/monthly.js
@@ -1,6 +1,12 @@
 (function (root) {
     const Amber = root.Amber = root.Amber || {};
 
+    /*
+     * Month by month on Compare: Amber and the compared plan for each calendar month (and any
+     * period), worked out the same way as the main comparison (feed-in settlement, monthly demand,
+     * daily charges for every day).
+     */
+
     function daysInMonth(monthKey) {
         const y = parseInt(monthKey.substring(0, 4), 10);
         const m = parseInt(monthKey.substring(5, 7), 10);
diff --git a/js/stats.js b/js/stats.js
index d18da7c..f8c6a71 100644
--- a/js/stats.js
+++ b/js/stats.js
@@ -1,6 +1,12 @@
 (function (root) {
     const Amber = root.Amber = root.Amber || {};
 
+    /*
+     * More Stats on the Usage tab: average import and feed-in prices, power bought and sent out
+     * during price spikes (above STATS_DEFAULTS.spikeCents) and at negative prices, the evening
+     * share of imports, and days with no grid use.
+     */
+
     Amber.STATS_DEFAULTS = {
         spikeCents: 50
     };
diff --git a/js/storage.js b/js/storage.js
index 02b2252..2af8a66 100644
--- a/js/storage.js
+++ b/js/storage.js
@@ -1,6 +1,14 @@
 (function (root) {
     const Amber = root.Amber = root.Amber || {};
 
+    /*
+     * Browser storage. IndexedDB AmberDataCacheDB / dailyUsage holds the meter readings, one record
+     * per site and NEM date (id "<siteId>_<YYYY-MM-DD>"). Only final whole days are cached (with
+     * old empty days remembered), and estimated readings stay eligible for a refetch
+     * (cachedDayUsable). Also the API key (obfuscated, not encrypted; localStorage, or
+     * sessionStorage when not remembered) and escapeHTML for everything put into innerHTML.
+     */
+
     const DB_NAME = 'AmberDataCacheDB';
     const STORE_NAME = 'dailyUsage';
     const DB_VERSION = 1;
diff --git a/js/templates.js b/js/templates.js
index 6a4ac00..7534962 100644
--- a/js/templates.js
+++ b/js/templates.js
@@ -1,6 +1,13 @@
 (function (root) {
     const Amber = root.Amber = root.Amber || {};
 
+    /*
+     * Built-in plans to compare with, by state: default offers (DMO, VDO), market offers, free-window
+     * plans and the Solar Sharer Offer, each with the date its prices are as at. The shape of a plan
+     * is in docs/ARCHITECTURE.md (Plan configs). Prices are typed in by hand from published fact
+     * sheets: update each 1 July (default offers) and when retailers change their offers.
+     */
+
     const ALL_DAYS = [1, 2, 3, 4, 5, 6, 0];
     const WEEKDAYS = [1, 2, 3, 4, 5];
     const AS_AT = '2026-07-01';
diff --git a/js/time.js b/js/time.js
index 2ce6403..86e6ec2 100644
--- a/js/time.js
+++ b/js/time.js
@@ -1,6 +1,13 @@
 (function (root) {
     const Amber = root.Amber = root.Amber || {};
 
+    /*
+     * Dates and times. Amber's nemTime is an interval's end in NEM time (UTC+10, no daylight
+     * saving); plans' windows are local wall-clock time (or NEM time with clock: 'nem'). Helpers
+     * here convert between them (getClockParts, localWallToNemIso), match intervals to time-of-use
+     * windows (timeInWindow, windowMatches), and do day arithmetic on YYYY-MM-DD strings.
+     */
+
     function pad(n) {
         return String(n).padStart(2, '0');
     }
diff --git a/tests/unit-time.js b/tests/unit-time.js
index f55b1f8..0fba87a 100644
--- a/tests/unit-time.js
+++ b/tests/unit-time.js
@@ -78,7 +78,7 @@ const clockA = Amber.clockPartsForItem(clockItem, vicLocal, 'VIC');
 const clockB = Amber.clockPartsForItem(clockItem, vicLocal, 'VIC');
 assert(clockA === clockB, 'clock parts are cached on the usage item');
 assert(clockA.hours === 17, 'cached Melbourne DST hour is 17');
-assert(Amber.APP_VERSION === '1.60', 'app version is 1.60');
+assert(Amber.APP_VERSION === '1.61', 'app version is 1.61');
 assert(Amber.DEFAULT_AMBER_CONNECTION_CENTS === 125.367 && Amber.PREVIOUS_AMBER_CONNECTION_CENTS === 116.787, 'Amber daily connection defaults (2026-27 and 2025-26)');
 assert(Amber.DEFAULT_AMBER_SUBSCRIPTION_CENTS === 82.181, 'Amber subscription default');
 assert(Amber.DEFAULT_AMBER_DEMAND_CENTS === 43.431 && Amber.PREVIOUS_AMBER_DEMAND_CENTS === 42.345, 'Amber demand defaults (2026-27 and 2025-26)');