Move the build note into the version line, drop its standalone box

The "NEW VERSION NOTE" box that appeared above the Welcome heading
whenever no update was pending duplicated the version-line
information and stuck around persistently after every update. It's
gone now — the always-visible "Current version date" line carries
the note in parentheses instead, so it only ever needs one home.

Also documents the home page's status lines and update-check timing
in a new user-manual.md tour section (Part 3.A) and a fuller
technical writeup in README-numa-documentation.md.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

Author: tom-cloyd

README-numa-documentation.md

@@ -2,7 +2,7 @@
 
 A nutritional analysis web app written in Python (FastAPI). Analyzes individual food portions, recipes, and complete meals using data pooled from six nutrition databases — USDA FoodData Central, Open Food Facts, the Canadian Nutrient File, and the UK CoFID, Australian AFCD, and French CIQUAL static datasets. The program presents itself to users as **NutriMagnus ("nutrition wizard")**.
 
-UPDATED: 2026-08-30:1043
+UPDATED: 2026-08-31:2157
 
 Last monthly accuracy check: 2026-08-30.
 
@@ -1072,6 +1072,14 @@ The navbar marks the active section by comparing `request.url.path` to each nav
 
 Renders the content of `home.md` (project root) as HTML. The markdown file is rendered once at startup and cached in `web/home_body.cache`; the cache is invalidated if `home.md` is newer.
 
+**Status lines below the Welcome heading.** Three lines, `<br>`-separated inside one `<p class="muted mb-0"><small>` block: dietary preference, active profile, and `Current version date: {{ version_date }}` — `version_date` is `index()`'s full `VERSION` string (`web/backend.py`), i.e. the `yyyy-mm-dd:hhmm` stamp from `version.py`, not just its date portion. Whenever `NEW_VERSION_NOTE` (`version.py`) is non-empty it's appended in parentheses on that same line as `(Version note: {{ version_note }})`. This is the only place the build note shows when no update is available — there is no separate standalone box for it (there used to be; removed since it duplicated the same information already on this line).
+
+**Update-check flow.** `index()` calls `_update_check.check_for_update(VERSION)` (`numa_app/services/update_check.py`) on every load of `/` — launch, manual reload, or navigating back to Home from elsewhere — except immediately after a successful in-place update (`updated=1` query param), since the running process's in-memory `VERSION` is still stale until relaunch. `check_for_update()` compares the tag-ified current version against GitHub's latest-release tag via plain string comparison (safe because `VERSION` is a fixed-width, lexically-sortable stamp) and returns `{"tag": ..., "url": ...}` or `None`; it never raises, so a network failure or offline state is silently treated as "no update." Its own module-level cache (`_CACHE_TTL_SECONDS = 6 * 60 * 60`) means repeated home-page loads within a 6-hour window reuse the last GitHub response rather than making a fresh call each time; the cache key includes the version string, so it self-invalidates the moment `VERSION` changes (e.g. right after a self-update).
+
+**Notification-frequency gate.** Even when `check_for_update()` reports a real update, `index()` only lets the **UPDATE AVAILABLE** banner through if `_should_show_update_notice()` (`web/backend.py`) says so — otherwise it sets `update_available = None` before rendering, same as the post-update suppression case. That helper reads the saved `update_notify_frequency` pref (`"daily"` / `"weekly"` / `"monthly"`, default `"daily"`, validated against `_VALID_UPDATE_NOTIFY_FREQS`) and an `update_notice_last_shown_at` ISO date, both in `prefs.json`; if fewer days than the frequency's interval (`_UPDATE_NOTIFY_FREQ_DAYS`: 1/7/30) have elapsed since the last time the banner was shown, it returns `False` without touching `prefs.json`. Otherwise it stamps today's date into `update_notice_last_shown_at` and returns `True`. This is a display throttle only — it never affects the 6-hour network-cache TTL above, which keeps polling GitHub at its own fixed cadence regardless of the user's notification preference. The setting itself lives in Settings → "Update Notifications" (`settings.html`, `POST /settings/update-notify-frequency`), following the same radio-button/`prefs.json` pattern as the Dietary Preferences section (`diet_pref`).
+
+**When the banner does show**, its build-note line also names the current frequency setting in a muted aside with a link to `/settings#update-notifications`, so the note doubles as a reminder of how often you've asked to be told.
+
 #### `search.html`
 
 Food search results. Shows a results table with food name, data type, brand, and source badge (`pantry` / `cache` / `recipe` / `usda` / `off`). Each row links to `/food/{fdc_id}`. Used for both the Foods → Search page and as a reusable search partial.

tests/test_web.py

@@ -1871,25 +1871,24 @@ def test_home_page_shows_db_integrity_banner(client: TestClient, cached_food, db
 
 def test_home_page_shows_version_note_prominently(client: TestClient) -> None:
     """version_note (version.py's NEW_VERSION_NOTE) describes what changed
-    in the build you're actually running — it needs to be somewhere a user
-    will see it, not just in the fine print at the very bottom."""
+    in the build you're actually running — with no update pending, it shows
+    in parentheses next to the "Current version date" line below Welcome,
+    not just in the fine print at the very bottom, and not in a standalone
+    box of its own."""
     from version import NEW_VERSION_NOTE
 
     resp = client.get("/")
     assert NEW_VERSION_NOTE in resp.text
-    # The note appears in its own prominent box, ahead of the "Welcome to
-    # NutriMagnus" heading — not only in the small print at the page foot.
-    note_pos = resp.text.index(NEW_VERSION_NOTE)
-    welcome_pos = resp.text.index("Welcome to NutriMagnus")
-    assert note_pos < welcome_pos
-    assert f"NEW VERSION NOTE: {NEW_VERSION_NOTE}" in resp.text
+    assert f"(Version note: {NEW_VERSION_NOTE})" in resp.text
+    assert "alert-secondary" not in resp.text
+    assert "NEW VERSION NOTE:" not in resp.text
 
 
 def test_version_note_sits_inside_update_available_banner(client: TestClient, monkeypatch: pytest.MonkeyPatch) -> None:
     """When there's an update available, NEW_VERSION_NOTE appears inside
     that same alert box, directly below the first line — not as a separate
-    box, and not repeated in the always-visible "Current version date" line
-    below the Welcome heading (that line shows only the date, not the note)."""
+    box. It also appears a second time, in parentheses on the always-visible
+    "Current version date" line below the Welcome heading."""
     from numa_app.services import update_check as _update_check
     from version import NEW_VERSION_NOTE
 
@@ -1898,9 +1897,9 @@ def test_version_note_sits_inside_update_available_banner(client: TestClient, mo
         lambda *a, **kw: {"tag": "v2099-01-01-0000", "url": "https://github.com/tom-cloyd/NutriMagnus/releases/tag/v2099-01-01-0000"},
     )
     resp = client.get("/")
-    assert resp.text.count(NEW_VERSION_NOTE) == 1
+    assert resp.text.count(NEW_VERSION_NOTE) == 2
     assert f"NEW VERSION NOTE: {NEW_VERSION_NOTE}" in resp.text
-    assert f"Current version date:" in resp.text
+    assert f"(Version note: {NEW_VERSION_NOTE})" in resp.text
     update_banner_pos = resp.text.index("UPDATE AVAILABLE:")
     note_pos = resp.text.index(NEW_VERSION_NOTE)
     welcome_pos = resp.text.index("Welcome to NutriMagnus")

user-manual.md

@@ -1,6 +1,6 @@
 # NutriMagnus User Manual
 
-*Updated 2026-08-31:2135* / Reading time: 4 hours, 24 minutes
+*Updated 2026-08-31:2157* / Reading time: 4 hours, 25 minutes
 
 *Last full audit: 2026-08-30*
 
@@ -259,6 +259,18 @@ NuMa's web app runs in your ordinary browser. This makes program development, wh
 
 Launch NuMa the way it was set up on your computer — a desktop icon, an Applications-menu entry, or a shortcut someone set up for you. It opens automatically in your browser, normally at a browser address like `http://127.0.0.1:8000` — this just means "this computer, talking to itself," not an address on the internet, so don't worry if the exact numbers you see differ. If the page doesn't load right away, wait a few seconds and reload — the program is still starting up.
 
+#### What you see on the home page {: #home-page-tour}
+
+Right below the **Welcome to NutriMagnus** heading is a small block of status lines:
+
+- **Dietary preferences** — your current setting (e.g. "All animal foods"), with a link straight to Settings to change it.
+- **Active profile** — a one-line summary of your profile (age, sex, weight, height, activity level), or "not set" with a link to configure one if you haven't yet.
+- **Current version date** — the exact build you're running, as `yyyy-mm-dd:hhmm`. Whenever `version.py`'s build note is set, it follows in parentheses as "(Version note: ...)" — a short plain-language description of what changed in that build.
+
+Above all of that, a few one-time or conditional banners can appear when relevant: a database-integrity warning, an "update installed" confirmation right after using Update Now, an update-failed message, and an **UPDATE AVAILABLE** banner when a newer release exists on GitHub (with an **Update Now** button if you're running the packaged Linux install, otherwise a plain link to what's new). That banner repeats the build note as its own line, plus a note on how often you're being notified about new releases and a link to change that in **Settings → Update Notifications** (daily, weekly, or monthly — daily by default).
+
+**When does NuMa actually check for a new release?** Every time the home page loads — at launch, on a manual reload, or by navigating back to it from anywhere else in the program — it asks whether a newer version exists. That check itself is cached for a few hours, so bouncing back to the home page repeatedly doesn't re-contact GitHub every time; it just reuses the last answer until the cache expires. Separately, even when a newer version genuinely is available, whether the **UPDATE AVAILABLE** banner is actually shown to you on a given visit is throttled again by your daily/weekly/monthly notification-frequency setting — so you won't see it more often than you asked to.
+
 ### B. Finding your way around
 
 Every page has the same navigation bar across the top: **NuMa** (takes you home), **Foods**, **Recipes**, **Meals & Log**, **Analysis**, **Settings**, and **Manual** (this document). **Foods** and **Analysis** open as drop-down menus with several choices each; the others go straight to their page.
@@ -477,7 +489,7 @@ If you'd rather fix the underlying recipe yourself instead of using Retry, re-ed
 
 A one-time banner also appears on the home page whenever there's a System Issues entry you haven't seen yet, with a **Got it. Don't remind me again.** checkbox — checking it hides the banner (the entry still stays listed under Settings until it's actually resolved), and any *new* failure after that brings the banner back.
 
-**The home page also checks GitHub for a newer NuMa release**, showing an **UPDATE AVAILABLE** banner with a link to what's new if one exists. This check is quick (a couple of seconds at most) and fails silently if you're offline or GitHub is unreachable — it never blocks the home page from loading. A short plain-language note about what changed in your current build, labeled **NEW VERSION NOTE:** (e.g. "NEW VERSION NOTE: minor problem fixes"), always appears near the top of the home page in its own light box — directly below the UPDATE AVAILABLE banner when one is showing — whether or not an update is available. The bare version number also stays in the small print at the very bottom, for reference.
+**The home page also checks GitHub for a newer NuMa release**, showing an **UPDATE AVAILABLE** banner with a link to what's new if one exists. This check is quick (a couple of seconds at most) and fails silently if you're offline or GitHub is unreachable — it never blocks the home page from loading. See [What you see on the home page](#home-page-tour) for exactly where the current build's version stamp and build note appear, how often the check itself runs, and how the **Settings → Update Notifications** frequency setting controls how often the banner is shown.
 
 **If you installed NuMa via the Linux installer, the banner also has an Update Now button** that downloads and installs the new version for you — no terminal, no manual download. Click it, confirm, and NuMa fetches the latest release and swaps itself in place; your data is completely untouched (it lives in a separate location the update never touches). You'll see a message telling you to close the browser tab and relaunch NuMa once it's done — the version you're currently running keeps working right up until you do. If you're running NuMa from source instead (a developer checkout), the button doesn't appear — you'll see the plain "what's new on GitHub" link instead, since there's no packaged install for it to replace.
 
@@ -2595,16 +2607,18 @@ Each entry below has a bold title and a plain-language description — anywhere
 
 **CHOOSE HOW OFTEN YOU'RE TOLD ABOUT NEW VERSIONS, AND ALWAYS SEE YOUR CURRENT ONE**
 
-Settings now has an "Update Notifications" section where you can set how often the "new version available" banner shows up on the home page: daily (the default), weekly, or monthly. The banner's build note also names that setting directly, with a link to change it. Separately, the home page now always shows a line under the Welcome heading — "Current version date: yyyy-mm-dd:hhmm" — so you can check exactly what you're running, down to the minute, without scrolling to the page footer; that line shows only the version stamp, not the build note, which stays exclusive to the update-available banner.
+Settings now has an "Update Notifications" section where you can set how often the "new version available" banner shows up on the home page: daily (the default), weekly, or monthly. The banner's build note also names that setting directly, with a link to change it. Separately, the home page now always shows a line under the Welcome heading — "Current version date: yyyy-mm-dd:hhmm" — so you can check exactly what you're running, down to the minute, without scrolling to the page footer; whenever a build note is set it follows in parentheses as "(Version note: ...)" on that same line. The build note no longer gets its own standalone box further up the page. See [What you see on the home page](#home-page-tour) for the full rundown, including exactly when the update check itself runs.
 
 ```
 Scope: web/backend.py (_current_update_notify_frequency(), _should_show_update_notice()
 gating index()'s update_available via a saved prefs.json frequency + last-shown-date pair;
 new POST /settings/update-notify-frequency route; version_date passed as the full
-VERSION stamp, not just its date portion). web/templates/settings.html (new "Update
-Notifications" section). web/templates/home.html (frequency note added next to NEW
-VERSION NOTE in the banner; new always-visible "Current version date" line below
-Welcome showing the full date:time stamp). tests/test_web.py (updated accordingly).
+VERSION stamp). web/templates/settings.html (new "Update Notifications" section).
+web/templates/home.html (frequency note added next to NEW VERSION NOTE in the banner;
+the old standalone "NEW VERSION NOTE" box removed; the always-visible "Current version
+date" line below Welcome now carries the build note in parentheses). tests/test_web.py
+(updated accordingly). user-manual.md (new "What you see on the home page" tour, Part 3
+Section A). README-numa-documentation.md (matching, fuller technical writeup).
 ```
 
 **BUILD-NOTE LINE NOW LABELED "NEW VERSION NOTE:", AND ITS BROKEN RENAME FIXED**

version.py

@@ -1,4 +1,4 @@
-VERSION = "2026-08-31:2135"
+VERSION = "2026-08-31:2157"
 
 # A short, plain-language note shown next to VERSION on the home page and
 # used to describe this build in the update-available banner (see
@@ -9,4 +9,4 @@
 #   "minor problem fixes"
 #   "minor function added or improved"
 #   "significant improvements implemented — see top of User Manual for details"
-NEW_VERSION_NOTE = "minor function added or improved: version date now includes time."
+NEW_VERSION_NOTE = "minor function added or improved"

web/templates/home.html

@@ -43,11 +43,6 @@
   {% endif %}
 </div>
 {% endif %}
-{% if version_note and not update_available %}
-<div class="alert alert-secondary mt-4 mb-0 py-2">
-  <small>NEW VERSION NOTE: {{ version_note }}</small>
-</div>
-{% endif %}
 {% if unacked_errors %}
 <div class="alert alert-warning mt-4">
   <strong>{{ unacked_errors|length }} recalculation{{ 's' if unacked_errors|length != 1 }} failed</strong> and
@@ -72,7 +67,7 @@ <h1>Welcome to NutriMagnus</h1>
     {% else %}
     Active profile: not set — <a href="/settings">configure under Settings</a>
     {% endif %}
-    <br>Current version date: {{ version_date }}
+    <br>Current version date: {{ version_date }}{% if version_note %} (Version note: {{ version_note }}){% endif %}
   </small></p>
 </div>