trainbud 0.5.0 → 0.5.2

package/CHANGELOG.md

@@ -1,675 +1,757 @@
-# Changelog
-
-All notable changes to this project will be documented in this file.
-
-## [Unreleased] — server 0.5.0 · watch 2.0.0
-
-### Security — the key stopped living in the address bar
-
-- **The dashboard trades `?token=` for a session cookie and redirects to a clean
-  URL.** The API key opened the dashboard and then stayed in the address bar for
-  the whole session, which put it in browser history, in the tunnel provider's
-  access log, and in every screenshot of the page — and this page is about to be
-  screenshotted by people announcing it. The token still gets you in; what carries
-  you afterwards is an opaque 32-byte session id held in the server's memory, so it
-  grants nothing after a restart and cannot be replayed against another server.
-  `HttpOnly` keeps page script off it and `SameSite=Lax` is what stops cookie auth
-  from adding the CSRF that a Bearer header never had. `Secure` goes on only when
-  the request arrived over TLS, because a browser silently discards a Secure cookie
-  on `http://127.0.0.1` — which is how the local dashboard is reached.
-  A Bearer header still works untouched, and is what the watch and MCP clients use.
-- **The paired watch holds the API key itself, and the docs now say so.** Approving
-  a pairing hands the watch the same credential that opens the dashboard and `/mcp`,
-  not a narrower per-device token. The privacy policy implied a scoped token; it now
-  states what is actually handed over and how to revoke it. A per-device token is
-  still owed.
-- **`scripts/start-watch-stack.ps1` no longer defaults to the maintainer's own ngrok
-  domain.** Anyone who cloned the repo and ran the script published a tunnel pointed
-  at somebody else's address. It reads `TRAINBUD_NGROK_DOMAIN` and refuses to guess.
-
-### Changed — the README a launch link lands on
-
-- Quick start leads with `npx trainbud setup`; the clone-and-link path moves into a
-  "from source" fold. The old first instruction was four commands and a caveat.
-- A **"What TrainBud is not"** section: no hosted service, not an official Garmin
-  integration, not MFA-compatible, and the AI features bill to your own key.
-- The test count said 33. It is 551.
-
-TrainBud knew a great deal about your body and nothing about you. This release
-adds the half that was missing, and takes four decisions off the watch that it
-was never in a position to make.
-
-### Added — a profile, and a product that knows who it is talking to
-
-- **`src/profile.ts`** — name, units, primary sport, weekly goal, the bands at
-  which a number turns amber or red, the watch card order, and the AI's voice.
-  One row of `app.db`, read by every surface. Reads salvage field by field
-  (a settings row that is not JSON is wreckage, not configuration, and
-  `getProfile` sits on the path of every watch fetch); writes are strict and
-  name the field they refused.
-- **Personal thresholds decide colour everywhere.** Resting heart rate is graded
-  on the distance from *your own* median rather than on the rate — 58 bpm is
-  unremarkable for one person and a warning for another.
-- **Card order and visibility** are set in the dashboard and live on the watch's
-  next fetch. No Connect IQ settings sync, no store update.
-
-### Added — what the AI costs, which nothing had ever counted
-
-- Every AI call records its tokens and its price. Month-to-date spend is a
-  **calendar month**, not a rolling thirty days: a cap on a sliding window never
-  resets, and the number is compared against a bill that runs in months.
-- An optional monthly cap **refuses the request before the money is spent**, and
-  says so on the watch instead of after a round trip. No cap is set by default,
-  so nothing is ever blocked out of the box.
-- **An unknown price is null, never zero.** A model this build has no rate for
-  records its tokens and leaves the cost unknown, because a call priced at zero
-  is a cap that can never trip. Every total carries the count of calls it could
-  not price and says when it is a floor rather than a total.
-
-### Added — the Ask menu you write yourself
-
-Up to five questions, set in the dashboard, that lead the Ask menu on the wrist in
-the order you put them — ahead of the generated ones, in every state, including the
-first fortnight when the app has nothing of its own worth asking about. Whatever
-slots are left still fill from what actually fired, so "Why is my resting HR up?"
-keeps its place on the day it is up.
-
-**`ai.customPrompts` had existed since the profile landed and nothing read it.** It
-was in the schema, it validated, it saved — and no dashboard control wrote it and no
-code path consumed it, so a question typed against that API could never have appeared
-on a watch. The bounds it shipped with said as much: eight questions for a five-slot
-menu, 120 characters for a line the watch draws at 32. Both now come from
-`promptSuggestions.ts`, which owns the menu, and the profile refuses to store a
-question that could not be shown.
-
-### Added — a training dashboard
-
-- Phone first, because the pairing flow already was. Findings, the week against
-  last week, resting heart rate and sleep against your own median, spend, and
-  every setting above.
-- Drawn from local SQLite and nothing else — no Garmin round trip, so it paints
-  instantly and works with an expired session. Charts are inline SVG built by
-  pure functions; there is no CDN, because a script tag would tell a third party
-  every time you opened your own health dashboard.
-- **A missing day is a gap, not a zero.** Lines break at an absence, days are
-  placed by date rather than by array position, and a chart with nothing to draw
-  says so instead of rendering an empty axis that reads as "zero, every day".
-
-### Added — local feature counters
-
-Which of the nine cards anyone opens, and how often the Ask path runs. Counted
-on a request the watch was already making rather than per swipe. On by default
-because there is no endpoint to send them to; switchable off, with a delete
-button, in the dashboard under Privacy.
-
-### Changed — the watch draws state, it no longer decides it
-
-`recoveryColor`, `sleepColor`, `stressColor` and `heartRateColor` are gone from
-the Monkey C. The server grades; the watch colours. That removed three defects
-rather than moving code: the Overview grid graded two of its four cells and
-recovered the number by re-parsing its own formatted string (`parseNumber("6.3h")`
-returns 6); `heartRateColor` painted one line holding both the resting and the
-maximum heart rate while grading only the resting one; and a missing value fell
-through to white, which is also what "graded and unremarkable" looks like.
-
-### Fixed — on the wrist
-
-- A finding that does not fit is **counted, not dropped**. The same payload
-  showed two findings on a Fenix and one, silently, on a Forerunner 55.
-- The recovery ring no longer strikes through the heart-rate line beneath it.
-  A circle narrows as it descends; the label had been tested against that since
-  1.3.2 and the line under it never was.
-- Severity is a marker, not the text colour. A warning arrived as five lines of
-  red on black — the least legible combination there is on a transflective
-  screen in daylight.
-- A big **fall** in training load is marked. Only a rise was, so a 40% collapse
-  — the shape of an illness week — passed without a mark.
-- Colours are chosen against the worst screen in the manifest. The Forerunner 55
-  has an eight-colour palette and rounds everything to the nearest entry, which
-  is why "good" is `#4CD964`: the mint the dashboard shipped with rounds to CYAN
-  there.
-
-### Fixed — verification
-
-The Forerunner 55 could not finish the screen tour. It died partway through,
-twice, reported as "keypress did not register" — which reads exactly like the
-simulator being flaky, and was not: the tour allocated a second full payload
-while the first was still live, and on that device it is the difference between
-fitting and not. All 28 states now capture on fr55 and fenix847mm.
-
-### Fixed — store screenshots the app actually drew
-
-The Connect IQ listing still carried five 1.3.x captures: an Overview grid from
-before all four cells were graded, and findings as coloured body text rather
-than white text with a severity marker. Replacing them had already failed twice
-in one day — once because the screen tour paints its state counter over the app
-("9/28" above the title, in five images that reached the tree), once because the
-crop was measured inwards from the simulator window instead of from the device,
-so it sat off-centre and carried the watch case, and the vendor's wordmark
-printed on it, into a picture meant to be the screen.
-
-- **`build.ps1 -Screens -NoLabel`** compiles the counter out through a
-  `ScreenTour.labelVisible()` annotation pair, so no keypress can bring it back.
-- **`capture-sim.ps1 -Display -Device <id>`** locates the device artwork in the
-  window and adds `display.location` from the SDK's own `simulator.json`,
-  writing the display at native resolution — 390×390 on fr70 — with the corners
-  a round screen cannot physically show blacked out. If the artwork is not
-  there at 1:1 it refuses, rather than cropping something plausible.
-- **`capture-store-shots.ps1`** drives the tour, refuses any build but the
-  label-free one, re-checks every saved image for the counter's colour, and
-  stops the run when a keypress does not land instead of naming every remaining
-  file after the state before it.
-
-`ciq/store/screenshots/store/` is now Today, Week, Recovery, Overview and Ask as
-2.0.0 draws them. The five whole-watch 558x558 images that sat beside them are
-gone: nothing referenced them, they were 1.3.x too, and they were pictures of a
-watch rather than of a screen.
-
----
-
-## [0.4.1] — server 0.4.1 · watch 1.4.0
-
-"The AI says it has no access to my data" was reported once and fixed once, in
-`bb1fae8`. This release is what an audit found behind it: **four more distinct
-causes of that same sentence**, none of which the first fix touched, plus six
-defects the sweep turned up alongside them. Every one was verified against this
-machine's real install, whose Garmin session is genuinely gone and whose record
-genuinely stops on 2026-08-21 — which turned out to be the most valuable test
-fixture in the project.
-
-### Fixed — the AI could not see the user's data, four more ways
-
-- **The one tool that reads the store told the model the store was empty.**
-  `get_findings` and `trainbud findings`, on a store holding 74 days:
-  *"Still gathering data — 74 of the 14 days needed."* `coverage.ready` carries
-  two refusals that need opposite answers — not enough history yet, and plenty
-  of history that stops weeks ago — and `bb1fae8` taught exactly one of the four
-  surfaces to tell them apart. `FindingsPayload.coverage` was also typed
-  `{ days, ready }` while the value assigned to it carried four fields, so the
-  renderer could not have read `throughDate` had it wanted to. One
-  `describeFindingsCoverage`, read by all four surfaces.
-
-- **Nothing on the read path had ever opened the history store.** Every
-  per-metric tool read Garmin and nothing else, so an expired session meant
-  `get_sleep_data` threw, all six of the watch summary's payload calls returned
-  null, and an MCP client got a tool error — with 598 measurements and 2139
-  archived Connect responses on disk. Tools now fall back to `raw_payload`,
-  re-run through the *same* mapper the live path uses so a stored night keeps
-  its stage breakdown, and to `daily_metric` behind it for days older than the
-  180-day archive. **The window moves too**: with the record ending 08-21, "the
-  last 7 nights" selects seven days that were never recorded, so serving the
-  store changed nothing until the window could slide to where the data is — and
-  say so, in capitals, so no model reads a fortnight-old week as this week.
-
-- **A dependency printed English into the middle of the MCP protocol stream.**
-  `garmin-connect` calls `console.log('login page title:', …)` on every
-  re-login, and `console.log` writes to stdout, which is the JSON-RPC channel
-  for `trainbud start`. Claude Desktop and Cursor — the two clients `setup`
-  configures — lose the session on any re-login inside a tool call. Stdout is
-  now claimed for the life of the process rather than one more `console` method
-  being patched at one more call site.
-
-- **Any CLI command killed the answer the watch was waiting for.**
-  `reconcilePromptJobs` ran inside `getDb()`, so the first time *any* process
-  opened `app.db` it flipped every in-flight job to *"The server stopped before
-  this answer came back."* Running `trainbud doctor` while the watch waited did
-  exactly that. It now runs once, from `serve`, and never touches a job younger
-  than five minutes.
-
-### Fixed — numbers the app stated and had not measured
-
-- **"This week against last week" compared seven days against eight.**
-  `series(kind, n)` spans `n + 1` days inclusive, so `WEEK_DAYS * 2` split at
-  `today - 7` gave halves of 7 and 8. The TRIMP load line beside it summed two
-  correct seven-day windows, so a single card disagreed with itself.
-
-- **The sleep card called a fortnight-old night "last night".**
-  `hours.slice(-7)` is the last seven *rows*, which are seven nights only if the
-  watch was worn every night. Windowed by date now, like `detectors.ts` and
-  `week.ts` already were; a week with nothing in it reports no debt rather than
-  a debt of zero.
-
-- **`status` reported 1590 empty days for a store covering 366 dates.** The
-  count was over `ingest_day` rows, which are keyed (date, source) across six
-  sources. Now 292 empty days against 74 measured — figures that add up.
-
-### Fixed — security and data loss
-
-- **The crash handler wrote the API key to the log the request logger had
-  stopped writing.** The dashboard authenticates with `?token=`, and
-  `logger.error({ error, url: req.url })` was raw. The occurrence already
-  present in `.trainbud/mcp.log` has been scrubbed. **Rotate the key**: a
-  credential that has sat in a world-readable file is exposed whatever the file
-  says now.
-
-- **Only `app.db` was hardened to 0600.** `history.db` — a year of sleep, heart
-  rate and HRV — `cache.db` and the log file were all at the default 0644.
-
-- **`setup` rewrote the user's Claude Desktop config keeping only our own key.**
-  `readMcpConfig` returned `{ mcpServers }` and the write dropped everything
-  else; a config with no `mcpServers` key at all was replaced wholesale. The
-  file is now read whole and copied to `<name>.bak.json` before being touched.
-
-- **The retry path erased the rate-limit block it had just walked into.**
-  `withGarminClient` called `resetGarminClient`, which clears the persisted
-  cooldown, and then forced a login into the live block — on the single path
-  that block exists to guard. Splitting "forget the session" from "forget the
-  limit" also lets the backoff ladder escalate, which it never could.
-
-- **The cooldown test wrote a live five-minute Garmin block into the
-  developer's own database.** Found by attempting a backfill after the suite
-  passed. Tests no longer touch the real `app.db`.
-
-### Notes
-
-Two regression tests in this release passed against the deliberately broken
-build before being rebuilt. Reverting the fix remains the only thing that
-separates a regression test from a decoration.
-
-## [0.4.0] — server 0.4.0 · watch 1.4.0 - 2026-09-03
-
-Reported as "AI Unavailable, Error HTTP -400" on the Ask card. The AI was never
-asked: the tunnel was down, ngrok answered an HTML error page, and Connect IQ
-cannot parse HTML as JSON. Three surfaces had by now invented three vocabularies
-for the same class of failure, and this release collapses them into one — then
-adds the check that would have found it in a sentence.
-
-### Fixed
-
-- **A request that never reached the server was reported as a broken AI.**
-  `onPromptSubmitted` set the error to `"HTTP " + responseCode` under the heading
-  *AI unavailable*, so `-400` — which means the response body could not be parsed
-  — blamed the one component that had not been contacted. The pairing flow
-  already classified this exact code correctly and the prompt flow never called
-  it. `PairFail` is now `Fail` (`ciq/source/Fail.mc`) and pairing, the summary
-  fetch and the prompt all route through it.
-
-- **A rotated API key was reported as an unreachable server.** Any summary
-  failure drew "Could not reach TrainBud", including a 401 from a server that had
-  answered perfectly well. A new `UNAUTHORIZED` class says *Watch not authorised
-  — pair this watch again*.
-
-- **A prompt poll that failed every time looked like one still running.**
-  `onPromptStatusReceived` returned silently on any non-200, so the screen sat on
-  "Asking AI..." for thirty seconds and then said "Timed out", naming nothing.
-  One dropped Bluetooth response is now tolerated and a run of them is reported;
-  a 401 is reported at once.
-
-- **No AI answer this app ever produced was readable.** The result was cut into
-  80-character substrings and each was handed to a single `drawText`, which does
-  not wrap in Monkey C — so a page was laid out on one line, ran off both edges,
-  and the cut fell mid-word. It survived every build, type check and store review
-  because no Anthropic key had ever been configured on the machine it was written
-  on, so the success path had never once been drawn. Answers now wrap to the
-  chord width and page by line.
-
-- **`trainbud check` caused the failure it reported.** A rate-limited Garmin
-  login was retried once per tool call, so one expired session became nine logins
-  into a Cloudflare 429 in about five seconds. There is now a single cooldown,
-  taken from the upstream's own retry-after and honoured before any login is
-  attempted; a session already in hand keeps working.
-
-- **A test asserted against the developer's environment.** `checkAiStatus`
-  cleared `ANTHROPIC_API_KEY` in a `before` hook, but `src/config.ts` calls dotenv
-  at module load, so the dynamic import that followed put it straight back. Green
-  for the life of the project purely because no key had ever existed on the
-  machine it ran on; it failed the day one was added.
-
-### Fixed — found by an adversarial sweep
-
-A ten-lens audit produced 52 candidates; each went to two independent verifiers
-told to refute it, and 42 survived. The ones fixed here:
-
-- **Every daily metric was fetched for the wrong day, west of UTC.**
-  garmin-connect derives the calendar day from the Date it is given by
-  subtracting `getTimezoneOffset()` — a function that round-trips a
-  local-midnight Date and shifts a UTC-midnight one. Every Date this codebase
-  produced was UTC midnight, so at UTC-5 the library asked Garmin about the 18th
-  while the answer was stored under the 19th. Sleep, resting heart rate, stress
-  and weight were all off by one day, silently, and every baseline and finding
-  built on them described a day the user did not live. Invisible here because
-  this machine is UTC+4. The suite now passes under Los Angeles, UTC, Baku and
-  Auckland.
-
-- **Sleep debt was noise roughly half the time.** It summed one-sided shortfalls
-  against the user's own median, and half of anyone's nights fall below their
-  median by construction. Measured over 2000 synthetic steady sleepers with no
-  deficit at all it fired on 46.7% of weeks at an hour of night-to-night
-  variation. Now measured against a floor; false positives fall to 8.0% while a
-  genuine 1.5 h/night deficit is still caught 93% of the time.
-
-- **An unworn night scored as a bad night.** Recovery read
-  `sleep?.sleepTimeSeconds ?? 0`, scored zero hours as 35/100, and dragged an
-  otherwise excellent day under the "fatigued" line.
-
-- **A gap in the store read as a run of days.** The recent window was the last N
-  *points*, not N days.
-
-- **The request handler could not survive a throw.** One unguarded async
-  callback, so a malformed `Host` header — accepted by Node's parser, rejected by
-  `new URL` — exited the process, with no credential required.
-
-- **`trainbud setup` destroyed the Anthropic key**, and a Garmin password
-  containing `#` broke setup permanently, because values were written to `.env`
-  unquoted.
-
-- **Every goal and injury was saved twice**; the dashboard bound its form twice.
-
-- **`trainbud check` caused the rate limit it reported**, and a backfill answered
-  a 429 with ~1800 more requests.
-
-- **`app.db` held the Anthropic key at 0644**, and live pairing codes were
-  written to the log.
-
-- **The glance drew a tofu box** for the "h" in "6.3h"; **an expired pairing code
-  was polled forever**; **a rotated API key was hidden** behind ageing cached
-  numbers; and **the Ask card accepted presses with no AI key**.
-
-- **The only type check CI ran never looked at a test file**, which is why four
-  stale fixtures compiled.
-
-### Added
-
-- **`trainbud doctor`, `GET /api/selftest`, and a Connection panel on the
-  dashboard.** Fetches the configured public URL from outside this machine with
-  the watch's own headers and grades the answer with the watch's taxonomy. Status
-  alone is not the test — both of this project's expensive network bugs were a
-  200 or a 404 carrying HTML — so the body is graded and a 200 of HTML fails.
-
-- **A Week card, and `get_week_review`.** This week against last, per metric,
-  split by date rather than by position so a missing day cannot shift the
-  boundary. A metric absent on either side reads as unknown rather than as a
-  delta against zero.
-
-- **A load forecast.** Where the acute:chronic ratio lands if next week repeats
-  this one. The existing detector fires after the jump; this fires before it. The
-  projection slides the whole 28-day window forward rather than only advancing
-  the acute end.
-
-- **Sleep debt and consistency**, against the user's own median night rather than
-  eight hours, with consistency as median absolute deviation so one recovery
-  sleep cannot make a metronomic sleeper look erratic. Surfaced under last
-  night's hours as "Usually 7.2h · variable".
-
-- **A race countdown.** The context store has held races since the memory layer
-  landed and nothing ever read one for its date, though it changes what every
-  other number means — a falling load ratio is a warning in January and the plan
-  in a taper. `activeContext` excludes future dates by design, so
-  `upcomingContext` was added.
-
-- **`build.ps1 -Screens` and `scripts/capture-screens.ps1`.** Every screen the
-  app can draw, with no server, photographed on any device in one command. 1.3.0
-  shipped to the store having never been drawn once. Three faults it caught
-  immediately: the default jungle `sourcePath` was pulling the debug driver into
-  the store build; a jungle setting is assigned rather than appended, so listing
-  two jungles silently un-excluded the glance; and the Forerunner 55's recovery
-  card collided with its own ring.
-
-## [watch 1.3.1] - 2026-09-02
-
-Nobody who installed the watch app from the store could ever pair it. Reported
-from a Forerunner 55 on firmware 11.03; it affected every user on every device.
-
-### Fixed — watch
-
-- **The store build shipped a default Server URL pointing at a developer's
-  personal ngrok tunnel.** From 1.2.0 onward `properties.xml` carried
-  `https://backpedal-immorally-cathouse.ngrok-free.dev` as the default, so a
-  fresh install found a non-empty URL, skipped the setup screen entirely, POSTed
-  `/api/pair` at a host that was usually offline, and rendered "Pairing failed"
-  forever. The tunnel answers `ERR_NGROK_3200` when it is not running; the watch
-  read the HTML error page as `-400` and reported a pairing failure. The default
-  is now empty, which routes a fresh install to a **Setup required** screen
-  naming the setup guide. Sideloading keeps a baked URL through the new
-  `ciq/monkey-dev.jungle` overlay, which is gitignored and never in a store
-  build.
-
-  The same default was a privacy hazard in the other direction: while that
-  tunnel was up, a stranger's watch minted a pairing code against the
-  developer's own health server, one approval click away from handing out a
-  bearer token to somebody else's Garmin data.
-
-- **One "Pairing failed" screen became three, each naming what the user can
-  fix.** *Cannot reach server* (nothing answered), *Not a TrainBud server*
-  (something answered and it was not us — a dead tunnel, a captive portal, the
-  wrong address), *Server refused pairing*. The address in use is drawn on
-  screen whenever the address is the suspect, and `-104`, `-1001` and `429` get
-  their own one-line hints. `-1001` distinguishes a plain `http://` URL from an
-  `https://` one whose certificate was refused: the same code, two different
-  problems, and telling a self-hosted user to "use https" when they already do
-  is a dead end.
-
-- **Round screens were detected by measuring pixels rather than asking the
-  device.** `isRoundScreen()` was `width == height && width >= 240`, so the
-  Forerunner 55 — round, 208×208 — was treated as rectangular and drew the
-  recovery bar instead of the ring. Now `System.getDeviceSettings().screenShape`.
-
-- **Text wrapped to a fixed character count, which a circle does not honour.**
-  A line near the top of a round screen has far less room than one through the
-  middle; "Cannot reach server" rendered as "annot reach serve". Wrapping is now
-  measured in pixels against the chord width available at that height.
-
-- **The five button-only products could not navigate.** `BehaviorDelegate` maps
-  UP and DOWN to `onNextPage`/`onPreviousPage` and neither was implemented, so
-  on fr55, fr745 and the three Instinct 3 variants the carousel only moved
-  forwards one START press at a time and the Ask menu could not be scrolled at
-  all. Every on-screen hint also said "tap"; hints are now chosen from
-  `System.getDeviceSettings().isTouchScreen`.
-
-- **Grey was invisible on the Forerunner 55.** Its palette holds eight colours
-  and none of them is grey, so `COLOR_DK_GRAY` snapped to black on a black
-  background: inactive page dots, faded Ask items, card footnotes and the ring
-  track all vanished. Secondary elements use a colour that survives the palette,
-  and inactive dots are outlined rather than filled, so the hierarchy is carried
-  by shape.
-
-- **Pairing telemetry is debug-only.** The pairing screen drew `9/8 200` in the
-  corner of a store build — unexplainable to a user, and the difference between
-  a poll that never ran and one discarded on the device to anyone debugging.
-
-- **The AI disclaimer is now on screen.** The string existed from 1.2.0 and was
-  never drawn anywhere, so the app made training and recovery statements on a
-  health device with nothing to qualify them. It renders on the last page of an
-  answer.
-
-### Fixed — watch, found by drawing it
-
-Everything below was found by running 1.3.1 in the simulator on a Forerunner 55
-and a fenix 8 47mm and looking at every card. None of it was visible from the
-source, the type checker or a green build, and none of these screens had ever
-been drawn on any watch: 1.3.0 shipped its `.iq` without a single render.
-
-- **The Today card printed its first finding through its own title,** and cut a
-  character off each end of it: "Resting HR 4 bpm above" drew as "esting HR 4 bpm
-  above". It centred the text block on the screen rather than in the space below
-  the heading, and wrapped to a fixed 24 characters. This is card 0 — the first
-  thing a paired user sees.
-
-- **The Sleep card drew an empty yellow box next to "6.3".** The FONT_NUMBER_*
-  faces contain digits and separators and no letters, so the "h" rendered as a
-  missing-glyph box — and a box has a width, so the "does this fit" check passed
-  and the value never stepped down to a font that has letters. The Recovery
-  card's "No data" had the same fault waiting.
-
-- **The Ask AI card printed the selected prompt underneath its own hint:**
-  "Why is my re[STA]sting HR up?". The hint was right-justified against the
-  screen edge at the vertical centre, which on a circle is exactly where the
-  widest line already is.
-
-- **The carousel dead-ended on the Ask card.** Going back from the first prompt
-  left the card, but going forward from the last one wrapped around, so the six
-  metric cards after it could only be reached by paging *backwards* from Today.
-  It now leaves at both ends, on buttons and on swipe.
-
-- **The AI Insight card overlapped its own lines on large screens.** The line
-  step was a hardcoded 20 px, which is about right for the 208 px Forerunner 55
-  and much too small for a 454 px fenix. Every hardcoded line step is now
-  derived from the font.
-
-- **The Recovery card printed "Ready" through the bottom of the score,** for the
-  same reason: the label sat at a fixed offset from the centre while the score
-  is drawn in a font whose height nearly doubles between those two devices. The
-  label and the heart rate line are now stacked off the score's measured height.
-
-- **"Resting 48  Max 178" lost its last digits** at the bottom of a 208 px round
-  screen. It now shortens the *label* before the number: "Rest 48  Max 178".
-
-- Activity card: the workout name was cut to 14 characters before being drawn,
-  which threw away room a smaller font would have used. `drawFittedValue`
-  already measures and steps down; the character cut is gone. This was the last
-  item open on that card.
-
-### Fixed — "AI unavailable" meant four different things
-
-Reported as "it still shows AI Unavailable". The cause on this install was that
-**no Anthropic key had ever been configured**: the settings table was empty,
-`.env` had no `ANTHROPIC_API_KEY`, and the only two prompt jobs ever created, on
-2026-08-17 and 2026-08-19, both failed with
-`ANTHROPIC_API_KEY not configured`. AI is bring-your-own-key and genuinely could
-not run. The defect is that the watch could not say so.
-
-- **`/api/watch` now carries `ai_configured`.** `ai_insight: null` meant three
-  different things — no key, a failed call, or today's insight not generated
-  yet — and the watch drew one screen for all of them. The Ask card now shows
-  **"AI not set up / Add an API key in the dashboard"** instead of offering five
-  questions that cannot succeed, and the AI Insight card no longer tells a user
-  with no key that there is "No insight today", which is a claim about today. A
-  summary from an older server carries no such field; missing is read as
-  configured, so nothing is asserted on no evidence.
-
-- **The watch threw away the reason a prompt failed.** `GET /api/prompt/<id>`
-  returns the server's error string, and `onPromptStatusReceived` read only
-  `status` — so a missing API key and a provider outage rendered identically.
-  The reason is now drawn under the message, along with a timeout and the HTTP
-  code from a failed submit.
-
-- **`trainbud check` reported AI status from the environment only.** It read
-  `appConfig.anthropicApiKey` instead of `isAiConfigured()`, so a key saved
-  through the dashboard — the route the setup guide tells users to take — was
-  reported as absent forever. `resolveAnthropicKey()` exists for exactly this
-  and this call site never used it.
-
-### Fixed — dependencies
-
-- `qs` 6.15.3 → 6.16.0 and `fast-uri` 3.1.5 → 3.1.7, clearing one high and one
-  moderate advisory. `npm audit` is clean.
-
-### Removed
-
-- Dead resources and code: `drawHint()` and the `TapHint` string it drew
-  (replaced by page dots in 1.2.0), plus the unused `AskHint`, `PairingPolling`
-  and `CardHeartRate` strings.
-
-## [0.3.1] - 2026-08-19
-
-Watch pairing works. It never had, on any build, and the cause was the last one
-still open: a status poll that never reached the server.
-
-### Fixed — watch
-
-- **Pairing completes end to end.** ngrok's free tier answers any GET carrying a
-  browser-ish User-Agent with an HTML interstitial under a 200. Connect IQ sends
-  `Mozilla/5.0` and will not let an app override it, so every status poll was
-  answered by the tunnel, never reached the server, and failed on the watch as
-  `-400 INVALID_HTTP_BODY_IN_NETWORK_RESPONSE`. POSTs are not intercepted, which
-  is why `/api/pair` always worked and the poll never did. Verified in the
-  simulator against the live tunnel: code issued, approved in the dashboard,
-  credentials saved, summary fetched.
-- Recovery ring drew the inverse of the score: the end angle is measured
-  clockwise but the arc was drawn counter-clockwise, so 91 rendered as the
-  missing 9%.
-- Recovery ring overlapped the card title.
-- Fractional values drew with six decimal places (`6.300000h`), on both the
-  widget and the glance.
-- The four-cell overview grid used "No data" as its placeholder, which drew over
-  the neighbouring cells and their labels; it now uses a dash.
-- Activity card: subtitle and footnote collided, and a strength workout listed
-  "0 km" as though zero were a measurement.
-
-### Fixed — server
-
-- **Recovery score was NaN on every default call** and reached the watch as
-  `null`: normalizeWeights spread an object of explicit `undefined` weights over
-  its defaults, and `NaN <= 0` is false so the guard missed it.
-- **Stress and VO2 max were fetched from URLs Connect answers 404 for.** Both
-  take the date as a path segment; VO2 max is `maxmet/latest`, not
-  `maxmet/daily`. The stress mapper also read fields the response does not
-  contain (`overallStressLevel` rather than `avgStressLevel`), and Connect's
-  negative "not measured" sentinels were averaged in as real readings.
-- Pair codes came from `Math.random()`. `/api/pair` is unauthenticated by
-  design, so an attacker could mint codes, recover the PRNG state, predict the
-  code the watch was showing and collect the API key on approval. Now
-  `crypto.randomInt`.
-- Rate limiting only ever ran on `/mcp`, leaving the unauthenticated pair
-  endpoints open to a walk through the six-digit code space; and buckets were
-  keyed on the socket address, which behind a tunnel is one bucket for every
-  client. Limits now cover every route, with a tighter budget for pairing, keyed
-  on the forwarded address.
-- API key compared in constant time.
-- `.env`, `session.json` and the MCP client config were written world-readable
-  (0644) and are now 0600.
-- A single failed Garmin login was memoised and poisoned every later call until
-  the process restarted.
-- All four npm audit advisories cleared.
-
-### Added
-
-- Real Connect IQ Store screenshots, captured from a paired app in the
-  simulator (`ciq/store/screenshots/`). The previous set was drawn in PowerShell
-  and removed in 1.2.0.
-- Tests: pair code randomness, pair rate limiting, secret file permissions,
-  client auth lifecycle, the real Connect stress payload, recovery weights.
-  91 tests, up from 73.
-
-## [0.2.0] - 2026-06-26
-
-### Fixed
-
-- **Critical:** Logger no longer writes to stdout — pino-pretty uses stderr; file logging starts only when server starts
-- **Critical:** Credentials validated at server startup, not on first tool call
-- N+1 Garmin API calls batched with concurrency limit (`mapInBatches`, max 6 parallel)
-- Body composition fetches parallelized instead of sequential
-- Activities range queries use shared paginated pool cache (up to 500 activities) with truncation warning
-- Cache keys unified via `buildToolCacheKey()` with stable sorted-param hashing
-- Recovery tool uses yesterday's sleep data with fallback to prior nights
-- Activity date filtering uses consistent Luxon parsing
-- Session path resolved from single `getSessionPath()` in config
-- Version read from `package.json` instead of hardcoded strings
-- `GarminApiError` is now a proper class; auth retry uses `await`
-- Tool errors sanitized before returning to MCP clients
-- SQLite cache closed on SIGTERM/SIGINT/exit
-
-### Added
-
-- `src/version.ts`, `src/utils/batch.ts`, `src/garmin/garminApiTypes.ts`, `src/tools/types.ts`
-- `filterActivitiesByRange()`, `sanitizeErrorMessage()`, `getYesterday()` helpers
-- `configureLogger()` for lazy log file initialization
-- `.nvmrc` (Node 20)
-- `.github/workflows/publish.yml` for npm + GitHub Releases on version tags
-- Project knowledge base moved to Obsidian vault (`05-Projects/trainbud/`); see `docs/VAULT.md`
-- 11 new tests (32 total): cache key stability, date filtering, recovery scoring, error sanitization
-
-### Changed
-
-- **Rebranded** from garmin-mcp to **TrainBud** (package `trainbud`, CLI `trainbud`)
-- README rewritten as product page with disclaimer, badges, and security section
-- Added CONTRIBUTING.md; updated vault docs and examples
-- Removed imports from internal `garmin-connect/dist/` paths
-- Tool registry uses shared `ToolDefinition` interface without unsafe casts
-- `runCacheClear` is synchronous
-
-## [0.1.0] - 2026-06-26
-
-### Added
-
-- Initial MCP server exposing 6 Garmin Connect tools
-- Email/password authentication with session persistence (`.trainbud/session.json`)
-- SQLite caching layer with configurable TTL per resource type
-- CLI commands: `start`, `auth`, `cache clear`, `status`
-- Unit and integration tests using Node test runner
-- README, QUICKSTART, and example prompts
-
-### Notes
-
-- Uses unofficial `garmin-connect` npm package (Windows/macOS/Linux compatible)
-- MFA is not yet supported by the underlying library
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [0.5.2] — server 0.5.2 · watch 2.0.2 — 2026-09-06
+
+### Added — a paired watch no longer holds the master key
+
+- **Pairing mints a token scoped to that device.** `/api/pair/<code>/status` used
+  to hand the watch `TRAINBUD_API_KEY` itself: the credential that also opens the
+  dashboard and `/mcp`, sent to a device over a public tunnel, with no way to take
+  it back except rotating the key for everything at once. It now mints a
+  256-bit token per pairing and stores only its SHA-256, so a copy of `app.db` is
+  not a working watch credential.
+- **`trainbud devices`** lists paired watches with when they were paired and last
+  seen; **`trainbud devices revoke <id>`** (or `--all`) takes one away without
+  logging out the dashboard, the MCP endpoint, or the other watches. Revoking is
+  now the documented way to remove a watch — rotating `TRAINBUD_API_KEY` is not.
+- **Nothing on the watch changed and no re-pair is forced.** The field name in the
+  pairing response is unchanged, the master key is still accepted, and a watch
+  paired before this release keeps working. Re-pair it to swap its stored master
+  key for a scoped token.
+
+### Added — security headers, on every response including the 401s
+
+- The server shipped 0.5.1 with none, while being reachable from the internet for
+  as long as the watch's tunnel is up. Now sends `Content-Security-Policy`
+  (`frame-ancestors 'none'`, `form-action 'self'`, no external script or style),
+  `X-Content-Type-Options`, `X-Frame-Options`, `Referrer-Policy: no-referrer`, and
+  the two `Cross-Origin-*` policies. Applied before routing, so an error path
+  cannot miss them.
+- `script-src` keeps `'unsafe-inline'`: the dashboard is server-rendered HTML with
+  inline handlers, and a nonce policy is a rewrite of the page, not a header.
+- **HSTS only when the request actually arrived over TLS.** Pinning https on a
+  host the user reaches at `http://127.0.0.1:3847` would lock them out of their
+  own dashboard.
+
+### Changed
+
+- npm keywords: added `mcp-server`, `cursor`, `chatgpt`, `connect-iq`.
+- 569 tests (567 pass, 2 skipped), up from 551.
+
+## [0.5.1] — server 0.5.1 · watch 2.0.2 — 2026-09-06
+
+First release published to npm: `npx trainbud setup`. Trusted publishing over
+OIDC, no stored token — see `docs/RELEASING.md`.
+
+### Fixed — the published package was 42% dead weight
+
+- **134 of 274 files in the tarball were source maps that resolved to nothing.**
+  `.js.map` and `.d.ts.map` both point at `../src/*.ts`, and `files` does not
+  ship `src`, so every map in the published package referenced a file that was
+  not there. Excluded with `!dist/**/*.map`; maps are still generated locally.
+  **274 files → 140, 1.0 MB → 644 kB unpacked.**
+
+### Fixed — docs that told users the package did not exist
+
+- `QUICKSTART.md` led with `git clone` and stated TrainBud was not on the npm
+  registry. Both Claude Code setup skills said the same, one of them in the very
+  step that installs the CLI. All now lead with `npx trainbud setup`, with the
+  clone path kept for running an unreleased commit.
+- README gains an npm version badge.
+
+
+### Fixed — a rotated key left the watch with no way back
+
+- **A 401 cleared nothing, so the watch could never pair again.** The summary
+  fetch classified the failure correctly and drew "Watch not authorised / Pair
+  this watch again", then kept the dead key in `Application.Storage`. Pressing
+  the button called `fetchSummary()`, which only starts pairing when the key is
+  *empty*, so every press re-sent the same dead key and got the same 401. The
+  instruction on screen was not something the watch could actually do, and
+  reinstalling the app was the only cure — for a state the security docs
+  actively tell users to create, since rotating `TRAINBUD_API_KEY` is how you
+  revoke a paired watch. A 401 now drops the stored key, and the next press
+  requests a fresh pairing code. The server URL is kept: it is still right, and
+  nobody should retype an address on a watch.
+- Status deliberately stays `error` rather than `pairing_error`: that screen
+  reads the *pairing* fail class, which is unset on a summary 401, so it would
+  have drawn "Could not reach TrainBud" about a server that answered.
+
+### Note on versions
+
+**The store served 2.0.1 and this repository could not build it** — no tag, no
+manifest bump, no changelog entry. This release is **2.0.2**, built from `main`,
+so the shipped artifact and the source agree again.
+
+
+### Security — the key stopped living in the address bar
+
+- **The dashboard trades `?token=` for a session cookie and redirects to a clean
+  URL.** The API key opened the dashboard and then stayed in the address bar for
+  the whole session, which put it in browser history, in the tunnel provider's
+  access log, and in every screenshot of the page — and this page is about to be
+  screenshotted by people announcing it. The token still gets you in; what carries
+  you afterwards is an opaque 32-byte session id held in the server's memory, so it
+  grants nothing after a restart and cannot be replayed against another server.
+  `HttpOnly` keeps page script off it and `SameSite=Lax` is what stops cookie auth
+  from adding the CSRF that a Bearer header never had. `Secure` goes on only when
+  the request arrived over TLS, because a browser silently discards a Secure cookie
+  on `http://127.0.0.1` — which is how the local dashboard is reached.
+  A Bearer header still works untouched, and is what the watch and MCP clients use.
+- **The paired watch holds the API key itself, and the docs now say so.** Approving
+  a pairing hands the watch the same credential that opens the dashboard and `/mcp`,
+  not a narrower per-device token. The privacy policy implied a scoped token; it now
+  states what is actually handed over and how to revoke it. A per-device token is
+  still owed.
+- **`scripts/start-watch-stack.ps1` no longer defaults to the maintainer's own ngrok
+  domain.** Anyone who cloned the repo and ran the script published a tunnel pointed
+  at somebody else's address. It reads `TRAINBUD_NGROK_DOMAIN` and refuses to guess.
+
+### Changed — the README a launch link lands on
+
+- Quick start leads with `npx trainbud setup`; the clone-and-link path moves into a
+  "from source" fold. The old first instruction was four commands and a caveat.
+- A **"What TrainBud is not"** section: no hosted service, not an official Garmin
+  integration, not MFA-compatible, and the AI features bill to your own key.
+- The test count said 33. It is 551.
+
+TrainBud knew a great deal about your body and nothing about you. This release
+adds the half that was missing, and takes four decisions off the watch that it
+was never in a position to make.
+
+### Added — a profile, and a product that knows who it is talking to
+
+- **`src/profile.ts`** — name, units, primary sport, weekly goal, the bands at
+  which a number turns amber or red, the watch card order, and the AI's voice.
+  One row of `app.db`, read by every surface. Reads salvage field by field
+  (a settings row that is not JSON is wreckage, not configuration, and
+  `getProfile` sits on the path of every watch fetch); writes are strict and
+  name the field they refused.
+- **Personal thresholds decide colour everywhere.** Resting heart rate is graded
+  on the distance from *your own* median rather than on the rate — 58 bpm is
+  unremarkable for one person and a warning for another.
+- **Card order and visibility** are set in the dashboard and live on the watch's
+  next fetch. No Connect IQ settings sync, no store update.
+
+### Added — what the AI costs, which nothing had ever counted
+
+- Every AI call records its tokens and its price. Month-to-date spend is a
+  **calendar month**, not a rolling thirty days: a cap on a sliding window never
+  resets, and the number is compared against a bill that runs in months.
+- An optional monthly cap **refuses the request before the money is spent**, and
+  says so on the watch instead of after a round trip. No cap is set by default,
+  so nothing is ever blocked out of the box.
+- **An unknown price is null, never zero.** A model this build has no rate for
+  records its tokens and leaves the cost unknown, because a call priced at zero
+  is a cap that can never trip. Every total carries the count of calls it could
+  not price and says when it is a floor rather than a total.
+
+### Added — the Ask menu you write yourself
+
+Up to five questions, set in the dashboard, that lead the Ask menu on the wrist in
+the order you put them — ahead of the generated ones, in every state, including the
+first fortnight when the app has nothing of its own worth asking about. Whatever
+slots are left still fill from what actually fired, so "Why is my resting HR up?"
+keeps its place on the day it is up.
+
+**`ai.customPrompts` had existed since the profile landed and nothing read it.** It
+was in the schema, it validated, it saved — and no dashboard control wrote it and no
+code path consumed it, so a question typed against that API could never have appeared
+on a watch. The bounds it shipped with said as much: eight questions for a five-slot
+menu, 120 characters for a line the watch draws at 32. Both now come from
+`promptSuggestions.ts`, which owns the menu, and the profile refuses to store a
+question that could not be shown.
+
+### Added — a training dashboard
+
+- Phone first, because the pairing flow already was. Findings, the week against
+  last week, resting heart rate and sleep against your own median, spend, and
+  every setting above.
+- Drawn from local SQLite and nothing else — no Garmin round trip, so it paints
+  instantly and works with an expired session. Charts are inline SVG built by
+  pure functions; there is no CDN, because a script tag would tell a third party
+  every time you opened your own health dashboard.
+- **A missing day is a gap, not a zero.** Lines break at an absence, days are
+  placed by date rather than by array position, and a chart with nothing to draw
+  says so instead of rendering an empty axis that reads as "zero, every day".
+
+### Added — local feature counters
+
+Which of the nine cards anyone opens, and how often the Ask path runs. Counted
+on a request the watch was already making rather than per swipe. On by default
+because there is no endpoint to send them to; switchable off, with a delete
+button, in the dashboard under Privacy.
+
+### Changed — the watch draws state, it no longer decides it
+
+`recoveryColor`, `sleepColor`, `stressColor` and `heartRateColor` are gone from
+the Monkey C. The server grades; the watch colours. That removed three defects
+rather than moving code: the Overview grid graded two of its four cells and
+recovered the number by re-parsing its own formatted string (`parseNumber("6.3h")`
+returns 6); `heartRateColor` painted one line holding both the resting and the
+maximum heart rate while grading only the resting one; and a missing value fell
+through to white, which is also what "graded and unremarkable" looks like.
+
+### Fixed — on the wrist
+
+- A finding that does not fit is **counted, not dropped**. The same payload
+  showed two findings on a Fenix and one, silently, on a Forerunner 55.
+- The recovery ring no longer strikes through the heart-rate line beneath it.
+  A circle narrows as it descends; the label had been tested against that since
+  1.3.2 and the line under it never was.
+- Severity is a marker, not the text colour. A warning arrived as five lines of
+  red on black — the least legible combination there is on a transflective
+  screen in daylight.
+- A big **fall** in training load is marked. Only a rise was, so a 40% collapse
+  — the shape of an illness week — passed without a mark.
+- Colours are chosen against the worst screen in the manifest. The Forerunner 55
+  has an eight-colour palette and rounds everything to the nearest entry, which
+  is why "good" is `#4CD964`: the mint the dashboard shipped with rounds to CYAN
+  there.
+
+### Fixed — verification
+
+The Forerunner 55 could not finish the screen tour. It died partway through,
+twice, reported as "keypress did not register" — which reads exactly like the
+simulator being flaky, and was not: the tour allocated a second full payload
+while the first was still live, and on that device it is the difference between
+fitting and not. All 28 states now capture on fr55 and fenix847mm.
+
+### Fixed — store screenshots the app actually drew
+
+The Connect IQ listing still carried five 1.3.x captures: an Overview grid from
+before all four cells were graded, and findings as coloured body text rather
+than white text with a severity marker. Replacing them had already failed twice
+in one day — once because the screen tour paints its state counter over the app
+("9/28" above the title, in five images that reached the tree), once because the
+crop was measured inwards from the simulator window instead of from the device,
+so it sat off-centre and carried the watch case, and the vendor's wordmark
+printed on it, into a picture meant to be the screen.
+
+- **`build.ps1 -Screens -NoLabel`** compiles the counter out through a
+  `ScreenTour.labelVisible()` annotation pair, so no keypress can bring it back.
+- **`capture-sim.ps1 -Display -Device <id>`** locates the device artwork in the
+  window and adds `display.location` from the SDK's own `simulator.json`,
+  writing the display at native resolution — 390×390 on fr70 — with the corners
+  a round screen cannot physically show blacked out. If the artwork is not
+  there at 1:1 it refuses, rather than cropping something plausible.
+- **`capture-store-shots.ps1`** drives the tour, refuses any build but the
+  label-free one, re-checks every saved image for the counter's colour, and
+  stops the run when a keypress does not land instead of naming every remaining
+  file after the state before it.
+
+`ciq/store/screenshots/store/` is now Today, Week, Recovery, Overview and Ask as
+2.0.0 draws them. The five whole-watch 558x558 images that sat beside them are
+gone: nothing referenced them, they were 1.3.x too, and they were pictures of a
+watch rather than of a screen.
+
+---
+
+## [0.4.1] — server 0.4.1 · watch 1.4.0
+
+"The AI says it has no access to my data" was reported once and fixed once, in
+`bb1fae8`. This release is what an audit found behind it: **four more distinct
+causes of that same sentence**, none of which the first fix touched, plus six
+defects the sweep turned up alongside them. Every one was verified against this
+machine's real install, whose Garmin session is genuinely gone and whose record
+genuinely stops on 2026-08-21 — which turned out to be the most valuable test
+fixture in the project.
+
+### Fixed — the AI could not see the user's data, four more ways
+
+- **The one tool that reads the store told the model the store was empty.**
+  `get_findings` and `trainbud findings`, on a store holding 74 days:
+  *"Still gathering data — 74 of the 14 days needed."* `coverage.ready` carries
+  two refusals that need opposite answers — not enough history yet, and plenty
+  of history that stops weeks ago — and `bb1fae8` taught exactly one of the four
+  surfaces to tell them apart. `FindingsPayload.coverage` was also typed
+  `{ days, ready }` while the value assigned to it carried four fields, so the
+  renderer could not have read `throughDate` had it wanted to. One
+  `describeFindingsCoverage`, read by all four surfaces.
+
+- **Nothing on the read path had ever opened the history store.** Every
+  per-metric tool read Garmin and nothing else, so an expired session meant
+  `get_sleep_data` threw, all six of the watch summary's payload calls returned
+  null, and an MCP client got a tool error — with 598 measurements and 2139
+  archived Connect responses on disk. Tools now fall back to `raw_payload`,
+  re-run through the *same* mapper the live path uses so a stored night keeps
+  its stage breakdown, and to `daily_metric` behind it for days older than the
+  180-day archive. **The window moves too**: with the record ending 08-21, "the
+  last 7 nights" selects seven days that were never recorded, so serving the
+  store changed nothing until the window could slide to where the data is — and
+  say so, in capitals, so no model reads a fortnight-old week as this week.
+
+- **A dependency printed English into the middle of the MCP protocol stream.**
+  `garmin-connect` calls `console.log('login page title:', …)` on every
+  re-login, and `console.log` writes to stdout, which is the JSON-RPC channel
+  for `trainbud start`. Claude Desktop and Cursor — the two clients `setup`
+  configures — lose the session on any re-login inside a tool call. Stdout is
+  now claimed for the life of the process rather than one more `console` method
+  being patched at one more call site.
+
+- **Any CLI command killed the answer the watch was waiting for.**
+  `reconcilePromptJobs` ran inside `getDb()`, so the first time *any* process
+  opened `app.db` it flipped every in-flight job to *"The server stopped before
+  this answer came back."* Running `trainbud doctor` while the watch waited did
+  exactly that. It now runs once, from `serve`, and never touches a job younger
+  than five minutes.
+
+### Fixed — numbers the app stated and had not measured
+
+- **"This week against last week" compared seven days against eight.**
+  `series(kind, n)` spans `n + 1` days inclusive, so `WEEK_DAYS * 2` split at
+  `today - 7` gave halves of 7 and 8. The TRIMP load line beside it summed two
+  correct seven-day windows, so a single card disagreed with itself.
+
+- **The sleep card called a fortnight-old night "last night".**
+  `hours.slice(-7)` is the last seven *rows*, which are seven nights only if the
+  watch was worn every night. Windowed by date now, like `detectors.ts` and
+  `week.ts` already were; a week with nothing in it reports no debt rather than
+  a debt of zero.
+
+- **`status` reported 1590 empty days for a store covering 366 dates.** The
+  count was over `ingest_day` rows, which are keyed (date, source) across six
+  sources. Now 292 empty days against 74 measured — figures that add up.
+
+### Fixed — security and data loss
+
+- **The crash handler wrote the API key to the log the request logger had
+  stopped writing.** The dashboard authenticates with `?token=`, and
+  `logger.error({ error, url: req.url })` was raw. The occurrence already
+  present in `.trainbud/mcp.log` has been scrubbed. **Rotate the key**: a
+  credential that has sat in a world-readable file is exposed whatever the file
+  says now.
+
+- **Only `app.db` was hardened to 0600.** `history.db` — a year of sleep, heart
+  rate and HRV — `cache.db` and the log file were all at the default 0644.
+
+- **`setup` rewrote the user's Claude Desktop config keeping only our own key.**
+  `readMcpConfig` returned `{ mcpServers }` and the write dropped everything
+  else; a config with no `mcpServers` key at all was replaced wholesale. The
+  file is now read whole and copied to `<name>.bak.json` before being touched.
+
+- **The retry path erased the rate-limit block it had just walked into.**
+  `withGarminClient` called `resetGarminClient`, which clears the persisted
+  cooldown, and then forced a login into the live block — on the single path
+  that block exists to guard. Splitting "forget the session" from "forget the
+  limit" also lets the backoff ladder escalate, which it never could.
+
+- **The cooldown test wrote a live five-minute Garmin block into the
+  developer's own database.** Found by attempting a backfill after the suite
+  passed. Tests no longer touch the real `app.db`.
+
+### Notes
+
+Two regression tests in this release passed against the deliberately broken
+build before being rebuilt. Reverting the fix remains the only thing that
+separates a regression test from a decoration.
+
+## [0.4.0] — server 0.4.0 · watch 1.4.0 - 2026-09-03
+
+Reported as "AI Unavailable, Error HTTP -400" on the Ask card. The AI was never
+asked: the tunnel was down, ngrok answered an HTML error page, and Connect IQ
+cannot parse HTML as JSON. Three surfaces had by now invented three vocabularies
+for the same class of failure, and this release collapses them into one — then
+adds the check that would have found it in a sentence.
+
+### Fixed
+
+- **A request that never reached the server was reported as a broken AI.**
+  `onPromptSubmitted` set the error to `"HTTP " + responseCode` under the heading
+  *AI unavailable*, so `-400` — which means the response body could not be parsed
+  — blamed the one component that had not been contacted. The pairing flow
+  already classified this exact code correctly and the prompt flow never called
+  it. `PairFail` is now `Fail` (`ciq/source/Fail.mc`) and pairing, the summary
+  fetch and the prompt all route through it.
+
+- **A rotated API key was reported as an unreachable server.** Any summary
+  failure drew "Could not reach TrainBud", including a 401 from a server that had
+  answered perfectly well. A new `UNAUTHORIZED` class says *Watch not authorised
+  — pair this watch again*.
+
+- **A prompt poll that failed every time looked like one still running.**
+  `onPromptStatusReceived` returned silently on any non-200, so the screen sat on
+  "Asking AI..." for thirty seconds and then said "Timed out", naming nothing.
+  One dropped Bluetooth response is now tolerated and a run of them is reported;
+  a 401 is reported at once.
+
+- **No AI answer this app ever produced was readable.** The result was cut into
+  80-character substrings and each was handed to a single `drawText`, which does
+  not wrap in Monkey C — so a page was laid out on one line, ran off both edges,
+  and the cut fell mid-word. It survived every build, type check and store review
+  because no Anthropic key had ever been configured on the machine it was written
+  on, so the success path had never once been drawn. Answers now wrap to the
+  chord width and page by line.
+
+- **`trainbud check` caused the failure it reported.** A rate-limited Garmin
+  login was retried once per tool call, so one expired session became nine logins
+  into a Cloudflare 429 in about five seconds. There is now a single cooldown,
+  taken from the upstream's own retry-after and honoured before any login is
+  attempted; a session already in hand keeps working.
+
+- **A test asserted against the developer's environment.** `checkAiStatus`
+  cleared `ANTHROPIC_API_KEY` in a `before` hook, but `src/config.ts` calls dotenv
+  at module load, so the dynamic import that followed put it straight back. Green
+  for the life of the project purely because no key had ever existed on the
+  machine it ran on; it failed the day one was added.
+
+### Fixed — found by an adversarial sweep
+
+A ten-lens audit produced 52 candidates; each went to two independent verifiers
+told to refute it, and 42 survived. The ones fixed here:
+
+- **Every daily metric was fetched for the wrong day, west of UTC.**
+  garmin-connect derives the calendar day from the Date it is given by
+  subtracting `getTimezoneOffset()` — a function that round-trips a
+  local-midnight Date and shifts a UTC-midnight one. Every Date this codebase
+  produced was UTC midnight, so at UTC-5 the library asked Garmin about the 18th
+  while the answer was stored under the 19th. Sleep, resting heart rate, stress
+  and weight were all off by one day, silently, and every baseline and finding
+  built on them described a day the user did not live. Invisible here because
+  this machine is UTC+4. The suite now passes under Los Angeles, UTC, Baku and
+  Auckland.
+
+- **Sleep debt was noise roughly half the time.** It summed one-sided shortfalls
+  against the user's own median, and half of anyone's nights fall below their
+  median by construction. Measured over 2000 synthetic steady sleepers with no
+  deficit at all it fired on 46.7% of weeks at an hour of night-to-night
+  variation. Now measured against a floor; false positives fall to 8.0% while a
+  genuine 1.5 h/night deficit is still caught 93% of the time.
+
+- **An unworn night scored as a bad night.** Recovery read
+  `sleep?.sleepTimeSeconds ?? 0`, scored zero hours as 35/100, and dragged an
+  otherwise excellent day under the "fatigued" line.
+
+- **A gap in the store read as a run of days.** The recent window was the last N
+  *points*, not N days.
+
+- **The request handler could not survive a throw.** One unguarded async
+  callback, so a malformed `Host` header — accepted by Node's parser, rejected by
+  `new URL` — exited the process, with no credential required.
+
+- **`trainbud setup` destroyed the Anthropic key**, and a Garmin password
+  containing `#` broke setup permanently, because values were written to `.env`
+  unquoted.
+
+- **Every goal and injury was saved twice**; the dashboard bound its form twice.
+
+- **`trainbud check` caused the rate limit it reported**, and a backfill answered
+  a 429 with ~1800 more requests.
+
+- **`app.db` held the Anthropic key at 0644**, and live pairing codes were
+  written to the log.
+
+- **The glance drew a tofu box** for the "h" in "6.3h"; **an expired pairing code
+  was polled forever**; **a rotated API key was hidden** behind ageing cached
+  numbers; and **the Ask card accepted presses with no AI key**.
+
+- **The only type check CI ran never looked at a test file**, which is why four
+  stale fixtures compiled.
+
+### Added
+
+- **`trainbud doctor`, `GET /api/selftest`, and a Connection panel on the
+  dashboard.** Fetches the configured public URL from outside this machine with
+  the watch's own headers and grades the answer with the watch's taxonomy. Status
+  alone is not the test — both of this project's expensive network bugs were a
+  200 or a 404 carrying HTML — so the body is graded and a 200 of HTML fails.
+
+- **A Week card, and `get_week_review`.** This week against last, per metric,
+  split by date rather than by position so a missing day cannot shift the
+  boundary. A metric absent on either side reads as unknown rather than as a
+  delta against zero.
+
+- **A load forecast.** Where the acute:chronic ratio lands if next week repeats
+  this one. The existing detector fires after the jump; this fires before it. The
+  projection slides the whole 28-day window forward rather than only advancing
+  the acute end.
+
+- **Sleep debt and consistency**, against the user's own median night rather than
+  eight hours, with consistency as median absolute deviation so one recovery
+  sleep cannot make a metronomic sleeper look erratic. Surfaced under last
+  night's hours as "Usually 7.2h · variable".
+
+- **A race countdown.** The context store has held races since the memory layer
+  landed and nothing ever read one for its date, though it changes what every
+  other number means — a falling load ratio is a warning in January and the plan
+  in a taper. `activeContext` excludes future dates by design, so
+  `upcomingContext` was added.
+
+- **`build.ps1 -Screens` and `scripts/capture-screens.ps1`.** Every screen the
+  app can draw, with no server, photographed on any device in one command. 1.3.0
+  shipped to the store having never been drawn once. Three faults it caught
+  immediately: the default jungle `sourcePath` was pulling the debug driver into
+  the store build; a jungle setting is assigned rather than appended, so listing
+  two jungles silently un-excluded the glance; and the Forerunner 55's recovery
+  card collided with its own ring.
+
+## [watch 1.3.1] - 2026-09-02
+
+Nobody who installed the watch app from the store could ever pair it. Reported
+from a Forerunner 55 on firmware 11.03; it affected every user on every device.
+
+### Fixed — watch
+
+- **The store build shipped a default Server URL pointing at a developer's
+  personal ngrok tunnel.** From 1.2.0 onward `properties.xml` carried
+  `https://backpedal-immorally-cathouse.ngrok-free.dev` as the default, so a
+  fresh install found a non-empty URL, skipped the setup screen entirely, POSTed
+  `/api/pair` at a host that was usually offline, and rendered "Pairing failed"
+  forever. The tunnel answers `ERR_NGROK_3200` when it is not running; the watch
+  read the HTML error page as `-400` and reported a pairing failure. The default
+  is now empty, which routes a fresh install to a **Setup required** screen
+  naming the setup guide. Sideloading keeps a baked URL through the new
+  `ciq/monkey-dev.jungle` overlay, which is gitignored and never in a store
+  build.
+
+  The same default was a privacy hazard in the other direction: while that
+  tunnel was up, a stranger's watch minted a pairing code against the
+  developer's own health server, one approval click away from handing out a
+  bearer token to somebody else's Garmin data.
+
+- **One "Pairing failed" screen became three, each naming what the user can
+  fix.** *Cannot reach server* (nothing answered), *Not a TrainBud server*
+  (something answered and it was not us — a dead tunnel, a captive portal, the
+  wrong address), *Server refused pairing*. The address in use is drawn on
+  screen whenever the address is the suspect, and `-104`, `-1001` and `429` get
+  their own one-line hints. `-1001` distinguishes a plain `http://` URL from an
+  `https://` one whose certificate was refused: the same code, two different
+  problems, and telling a self-hosted user to "use https" when they already do
+  is a dead end.
+
+- **Round screens were detected by measuring pixels rather than asking the
+  device.** `isRoundScreen()` was `width == height && width >= 240`, so the
+  Forerunner 55 — round, 208×208 — was treated as rectangular and drew the
+  recovery bar instead of the ring. Now `System.getDeviceSettings().screenShape`.
+
+- **Text wrapped to a fixed character count, which a circle does not honour.**
+  A line near the top of a round screen has far less room than one through the
+  middle; "Cannot reach server" rendered as "annot reach serve". Wrapping is now
+  measured in pixels against the chord width available at that height.
+
+- **The five button-only products could not navigate.** `BehaviorDelegate` maps
+  UP and DOWN to `onNextPage`/`onPreviousPage` and neither was implemented, so
+  on fr55, fr745 and the three Instinct 3 variants the carousel only moved
+  forwards one START press at a time and the Ask menu could not be scrolled at
+  all. Every on-screen hint also said "tap"; hints are now chosen from
+  `System.getDeviceSettings().isTouchScreen`.
+
+- **Grey was invisible on the Forerunner 55.** Its palette holds eight colours
+  and none of them is grey, so `COLOR_DK_GRAY` snapped to black on a black
+  background: inactive page dots, faded Ask items, card footnotes and the ring
+  track all vanished. Secondary elements use a colour that survives the palette,
+  and inactive dots are outlined rather than filled, so the hierarchy is carried
+  by shape.
+
+- **Pairing telemetry is debug-only.** The pairing screen drew `9/8 200` in the
+  corner of a store build — unexplainable to a user, and the difference between
+  a poll that never ran and one discarded on the device to anyone debugging.
+
+- **The AI disclaimer is now on screen.** The string existed from 1.2.0 and was
+  never drawn anywhere, so the app made training and recovery statements on a
+  health device with nothing to qualify them. It renders on the last page of an
+  answer.
+
+### Fixed — watch, found by drawing it
+
+Everything below was found by running 1.3.1 in the simulator on a Forerunner 55
+and a fenix 8 47mm and looking at every card. None of it was visible from the
+source, the type checker or a green build, and none of these screens had ever
+been drawn on any watch: 1.3.0 shipped its `.iq` without a single render.
+
+- **The Today card printed its first finding through its own title,** and cut a
+  character off each end of it: "Resting HR 4 bpm above" drew as "esting HR 4 bpm
+  above". It centred the text block on the screen rather than in the space below
+  the heading, and wrapped to a fixed 24 characters. This is card 0 — the first
+  thing a paired user sees.
+
+- **The Sleep card drew an empty yellow box next to "6.3".** The FONT_NUMBER_*
+  faces contain digits and separators and no letters, so the "h" rendered as a
+  missing-glyph box — and a box has a width, so the "does this fit" check passed
+  and the value never stepped down to a font that has letters. The Recovery
+  card's "No data" had the same fault waiting.
+
+- **The Ask AI card printed the selected prompt underneath its own hint:**
+  "Why is my re[STA]sting HR up?". The hint was right-justified against the
+  screen edge at the vertical centre, which on a circle is exactly where the
+  widest line already is.
+
+- **The carousel dead-ended on the Ask card.** Going back from the first prompt
+  left the card, but going forward from the last one wrapped around, so the six
+  metric cards after it could only be reached by paging *backwards* from Today.
+  It now leaves at both ends, on buttons and on swipe.
+
+- **The AI Insight card overlapped its own lines on large screens.** The line
+  step was a hardcoded 20 px, which is about right for the 208 px Forerunner 55
+  and much too small for a 454 px fenix. Every hardcoded line step is now
+  derived from the font.
+
+- **The Recovery card printed "Ready" through the bottom of the score,** for the
+  same reason: the label sat at a fixed offset from the centre while the score
+  is drawn in a font whose height nearly doubles between those two devices. The
+  label and the heart rate line are now stacked off the score's measured height.
+
+- **"Resting 48  Max 178" lost its last digits** at the bottom of a 208 px round
+  screen. It now shortens the *label* before the number: "Rest 48  Max 178".
+
+- Activity card: the workout name was cut to 14 characters before being drawn,
+  which threw away room a smaller font would have used. `drawFittedValue`
+  already measures and steps down; the character cut is gone. This was the last
+  item open on that card.
+
+### Fixed — "AI unavailable" meant four different things
+
+Reported as "it still shows AI Unavailable". The cause on this install was that
+**no Anthropic key had ever been configured**: the settings table was empty,
+`.env` had no `ANTHROPIC_API_KEY`, and the only two prompt jobs ever created, on
+2026-08-17 and 2026-08-19, both failed with
+`ANTHROPIC_API_KEY not configured`. AI is bring-your-own-key and genuinely could
+not run. The defect is that the watch could not say so.
+
+- **`/api/watch` now carries `ai_configured`.** `ai_insight: null` meant three
+  different things — no key, a failed call, or today's insight not generated
+  yet — and the watch drew one screen for all of them. The Ask card now shows
+  **"AI not set up / Add an API key in the dashboard"** instead of offering five
+  questions that cannot succeed, and the AI Insight card no longer tells a user
+  with no key that there is "No insight today", which is a claim about today. A
+  summary from an older server carries no such field; missing is read as
+  configured, so nothing is asserted on no evidence.
+
+- **The watch threw away the reason a prompt failed.** `GET /api/prompt/<id>`
+  returns the server's error string, and `onPromptStatusReceived` read only
+  `status` — so a missing API key and a provider outage rendered identically.
+  The reason is now drawn under the message, along with a timeout and the HTTP
+  code from a failed submit.
+
+- **`trainbud check` reported AI status from the environment only.** It read
+  `appConfig.anthropicApiKey` instead of `isAiConfigured()`, so a key saved
+  through the dashboard — the route the setup guide tells users to take — was
+  reported as absent forever. `resolveAnthropicKey()` exists for exactly this
+  and this call site never used it.
+
+### Fixed — dependencies
+
+- `qs` 6.15.3 → 6.16.0 and `fast-uri` 3.1.5 → 3.1.7, clearing one high and one
+  moderate advisory. `npm audit` is clean.
+
+### Removed
+
+- Dead resources and code: `drawHint()` and the `TapHint` string it drew
+  (replaced by page dots in 1.2.0), plus the unused `AskHint`, `PairingPolling`
+  and `CardHeartRate` strings.
+
+## [0.3.1] - 2026-08-19
+
+Watch pairing works. It never had, on any build, and the cause was the last one
+still open: a status poll that never reached the server.
+
+### Fixed — watch
+
+- **Pairing completes end to end.** ngrok's free tier answers any GET carrying a
+  browser-ish User-Agent with an HTML interstitial under a 200. Connect IQ sends
+  `Mozilla/5.0` and will not let an app override it, so every status poll was
+  answered by the tunnel, never reached the server, and failed on the watch as
+  `-400 INVALID_HTTP_BODY_IN_NETWORK_RESPONSE`. POSTs are not intercepted, which
+  is why `/api/pair` always worked and the poll never did. Verified in the
+  simulator against the live tunnel: code issued, approved in the dashboard,
+  credentials saved, summary fetched.
+- Recovery ring drew the inverse of the score: the end angle is measured
+  clockwise but the arc was drawn counter-clockwise, so 91 rendered as the
+  missing 9%.
+- Recovery ring overlapped the card title.
+- Fractional values drew with six decimal places (`6.300000h`), on both the
+  widget and the glance.
+- The four-cell overview grid used "No data" as its placeholder, which drew over
+  the neighbouring cells and their labels; it now uses a dash.
+- Activity card: subtitle and footnote collided, and a strength workout listed
+  "0 km" as though zero were a measurement.
+
+### Fixed — server
+
+- **Recovery score was NaN on every default call** and reached the watch as
+  `null`: normalizeWeights spread an object of explicit `undefined` weights over
+  its defaults, and `NaN <= 0` is false so the guard missed it.
+- **Stress and VO2 max were fetched from URLs Connect answers 404 for.** Both
+  take the date as a path segment; VO2 max is `maxmet/latest`, not
+  `maxmet/daily`. The stress mapper also read fields the response does not
+  contain (`overallStressLevel` rather than `avgStressLevel`), and Connect's
+  negative "not measured" sentinels were averaged in as real readings.
+- Pair codes came from `Math.random()`. `/api/pair` is unauthenticated by
+  design, so an attacker could mint codes, recover the PRNG state, predict the
+  code the watch was showing and collect the API key on approval. Now
+  `crypto.randomInt`.
+- Rate limiting only ever ran on `/mcp`, leaving the unauthenticated pair
+  endpoints open to a walk through the six-digit code space; and buckets were
+  keyed on the socket address, which behind a tunnel is one bucket for every
+  client. Limits now cover every route, with a tighter budget for pairing, keyed
+  on the forwarded address.
+- API key compared in constant time.
+- `.env`, `session.json` and the MCP client config were written world-readable
+  (0644) and are now 0600.
+- A single failed Garmin login was memoised and poisoned every later call until
+  the process restarted.
+- All four npm audit advisories cleared.
+
+### Added
+
+- Real Connect IQ Store screenshots, captured from a paired app in the
+  simulator (`ciq/store/screenshots/`). The previous set was drawn in PowerShell
+  and removed in 1.2.0.
+- Tests: pair code randomness, pair rate limiting, secret file permissions,
+  client auth lifecycle, the real Connect stress payload, recovery weights.
+  91 tests, up from 73.
+
+## [0.2.0] - 2026-06-26
+
+### Fixed
+
+- **Critical:** Logger no longer writes to stdout — pino-pretty uses stderr; file logging starts only when server starts
+- **Critical:** Credentials validated at server startup, not on first tool call
+- N+1 Garmin API calls batched with concurrency limit (`mapInBatches`, max 6 parallel)
+- Body composition fetches parallelized instead of sequential
+- Activities range queries use shared paginated pool cache (up to 500 activities) with truncation warning
+- Cache keys unified via `buildToolCacheKey()` with stable sorted-param hashing
+- Recovery tool uses yesterday's sleep data with fallback to prior nights
+- Activity date filtering uses consistent Luxon parsing
+- Session path resolved from single `getSessionPath()` in config
+- Version read from `package.json` instead of hardcoded strings
+- `GarminApiError` is now a proper class; auth retry uses `await`
+- Tool errors sanitized before returning to MCP clients
+- SQLite cache closed on SIGTERM/SIGINT/exit
+
+### Added
+
+- `src/version.ts`, `src/utils/batch.ts`, `src/garmin/garminApiTypes.ts`, `src/tools/types.ts`
+- `filterActivitiesByRange()`, `sanitizeErrorMessage()`, `getYesterday()` helpers
+- `configureLogger()` for lazy log file initialization
+- `.nvmrc` (Node 20)
+- `.github/workflows/publish.yml` for npm + GitHub Releases on version tags
+- Project knowledge base moved to Obsidian vault (`05-Projects/trainbud/`); see `docs/VAULT.md`
+- 11 new tests (32 total): cache key stability, date filtering, recovery scoring, error sanitization
+
+### Changed
+
+- **Rebranded** from garmin-mcp to **TrainBud** (package `trainbud`, CLI `trainbud`)
+- README rewritten as product page with disclaimer, badges, and security section
+- Added CONTRIBUTING.md; updated vault docs and examples
+- Removed imports from internal `garmin-connect/dist/` paths
+- Tool registry uses shared `ToolDefinition` interface without unsafe casts
+- `runCacheClear` is synchronous
+
+## [0.1.0] - 2026-06-26
+
+### Added
+
+- Initial MCP server exposing 6 Garmin Connect tools
+- Email/password authentication with session persistence (`.trainbud/session.json`)
+- SQLite caching layer with configurable TTL per resource type
+- CLI commands: `start`, `auth`, `cache clear`, `status`
+- Unit and integration tests using Node test runner
+- README, QUICKSTART, and example prompts
+
+### Notes
+
+- Uses unofficial `garmin-connect` npm package (Windows/macOS/Linux compatible)
+- MFA is not yet supported by the underlying library