Persist an explicit timezone choice (timezone_configured)

The admin settings screen auto-set the browser zone whenever it loaded an
empty timezone, guarded only by a per-mount ref. After an admin cleared the
timezone (empty = API-host-local), the next open re-fetched "" and
auto-set the browser zone again, so the empty choice could not persist.

Add a twelfth settings field, timezone_configured (strict bool, default
false), carried by the core settings table, the stored JSON document and
the admin GET/PATCH. The screen now auto-sets only when the timezone is
empty AND timezone_configured is false, patching the flag with the
detected zone; saving the timezone field (including clearing it) also
sends timezone_configured: true. Detection returning nothing sets nothing.

Task: a0e7649c-58b0-4aa3-91b5-cf426e334a76 (release review TZ-001)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

custom_components/nestquest/core/const.py

@@ -119,6 +119,12 @@ DEFAULT_AUTOMATION_ENABLED = True
 # Home Assistant's configured ``time_zone`` and ignores this field.
 CONF_TIMEZONE = "timezone"
 DEFAULT_TIMEZONE = ""
+# Whether the admin has made an explicit ``timezone`` choice.  ``False``
+# (a fresh install) lets the admin UI auto-set the browser's zone once;
+# ``True`` pins the stored value — including an explicitly-chosen empty
+# ``timezone`` (the API host's local time) — so it is never auto-set again.
+CONF_TIMEZONE_CONFIGURED = "timezone_configured"
+DEFAULT_TIMEZONE_CONFIGURED = False
 
 # Panel-plane API client (Feature 18): the integration reaches the
 # NestQuest API service (Feature 16) over HTTP instead of the database.

custom_components/nestquest/core/settings.py

@@ -49,6 +49,7 @@ from .const import (
     CONF_MORNING_SUMMARY_TIME,
     CONF_NOTIFY_TARGET,
     CONF_TIMEZONE,
+    CONF_TIMEZONE_CONFIGURED,
     DEFAULT_AFTERNOON_REMINDER_TIME,
     DEFAULT_AUTOMATION_ENABLED,
     DEFAULT_DAY_ROLLOVER_TIME,
@@ -56,6 +57,7 @@ from .const import (
     DEFAULT_HORIZON_DAYS,
     DEFAULT_MORNING_SUMMARY_TIME,
     DEFAULT_TIMEZONE,
+    DEFAULT_TIMEZONE_CONFIGURED,
     LOGGER,
     TIME_PATTERN,
 )
@@ -241,6 +243,12 @@ _FIELDS: tuple[tuple[str, str, Any, Callable[[Any], Any]], ...] = (
         _resolve_bool,
     ),
     ("timezone", CONF_TIMEZONE, DEFAULT_TIMEZONE, _resolve_timezone),
+    (
+        "timezone_configured",
+        CONF_TIMEZONE_CONFIGURED,
+        DEFAULT_TIMEZONE_CONFIGURED,
+        _resolve_bool,
+    ),
 )
 
 
@@ -271,6 +279,10 @@ class NestQuestSettings:
     end_of_day_report_enabled: bool = DEFAULT_AUTOMATION_ENABLED
     celebration_enabled: bool = DEFAULT_AUTOMATION_ENABLED
     timezone: str = DEFAULT_TIMEZONE
+    #: ``True`` once the admin explicitly chose :attr:`timezone` (even
+    #: the empty host-local value); ``False`` on a fresh install, where
+    #: the admin UI may auto-set the browser's zone.
+    timezone_configured: bool = DEFAULT_TIMEZONE_CONFIGURED
 
     def __post_init__(self) -> None:
         # Validate STRICTLY at construction so a hand-built instance
@@ -303,6 +315,7 @@ class NestQuestSettings:
             "afternoon_reminder_enabled",
             "end_of_day_report_enabled",
             "celebration_enabled",
+            "timezone_configured",
         ):
             value = getattr(self, name)
             if not isinstance(value, bool):

custom_components/nestquest/core/settings_store.py

@@ -18,7 +18,7 @@ API client; the two are deliberately NOT unified here, and neither
 side reads the other's values.
 
 STORED SERIALIZATION — the document at ``SETTINGS_META_KEY`` is a JSON
-object holding exactly the ELEVEN settings fields, keyed by field name
+object holding exactly the TWELVE settings fields, keyed by field name
 (which equals the ``CONF_*`` option key for every field), complete
 after the first update:
 
@@ -33,7 +33,11 @@ after the first update:
   booleans,
 - ``timezone`` — ``""`` (the API host's local time) or an IANA time
   zone name such as ``America/New_York``.  A document stored before
-  this field existed simply lacks it and resolves to ``""``.
+  this field existed simply lacks it and resolves to ``""``,
+- ``timezone_configured`` — a real boolean: ``True`` once the admin
+  explicitly chose ``timezone`` (including the empty host-local value),
+  so the admin UI never auto-sets it again.  A document stored before
+  this field existed lacks it and resolves to ``False``.
 
 Only values whose core validators ACCEPTED are ever written, so a
 stored document always round-trips through the core's option builders.
@@ -175,7 +179,7 @@ async def update_settings(
     update can never leave a half-applied document behind.
 
     The validated changes are merged onto the current effective
-    settings and the merged (complete, eleven-field) document is persisted
+    settings and the merged (complete, twelve-field) document is persisted
     in one atomic upsert; the updated settings are returned.  The whole
     read → merge → write span runs inside the per-database settings
     lock, so concurrent updates queue instead of interleaving.