docs(starlark): say what happens when the device location can't be used

A blank app Location only renders at the device's city when one is set and
the Open-Meteo lookup finds it. With no city, no match, or the geocoder
unreachable (retried after 30 minutes), the app gets no location and keeps
its author's default. The guide, the config page hint, CONFIG_REFERENCE and
the CHANGELOG entry now say so.

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

CHANGELOG.md

@@ -28,7 +28,9 @@ accepts both, but the store flags the old spelling as deprecated
 - `src.device_location` — a blank `Location` field on a Starlark (Tidbyt) app
   now renders at the device's City / State / Country (geocoded once via
   Open-Meteo and cached) instead of the app author's hard-coded default,
-  usually San Francisco. A location saved on the app still wins. Clearing an
+  usually San Francisco. A location saved on the app still wins. With no
+  device city set, or when the lookup fails or finds no match, the app keeps
+  its own default (a failed lookup is retried after 30 minutes). Clearing an
   app's location in the web UI now actually clears it; the save used to drop
   the blank field, so the old value stayed.
 

docs/CONFIG_REFERENCE.md

@@ -18,7 +18,7 @@ tooling against it.
 | `web_display_autostart` | bool, `true` | Whether the web interface service starts with the system | `scripts/utils/start_web_conditionally.py` |
 | `timezone` | string, `"America/New_York"` | IANA timezone for schedules and displays | `ConfigManager.get_timezone()` |
 | `target_fps` | int, `100` | Legacy "Scroll Frame Rate". Core scrolling no longer reads it: scroll frames are presented at `display.hardware.limit_refresh_rate_hz` divided by each scroll's frame hold, and speed comes from each plugin's scroll settings. Still exposed to plugins via `BasePlugin.global_config` | `src/plugin_system/base_plugin.py` |
-| `location` | object | `city` / `state` / `country`. Supplies the **default** for a plugin's own `location_city` / `location_state` / `location_country` setting, so weather, radar and friends follow this device without being configured twice. A value saved on the plugin itself still overrides it. Starlark (Tidbyt) apps get the same treatment: a `Location` field left blank on the app renders at this city (geocoded once via Open-Meteo, coordinates cached permanently) instead of the app author's default, which is usually San Francisco. | `SchemaManager.apply_device_location()`, then plugins via merged config; `src/device_location.py` for Starlark apps |
+| `location` | object | `city` / `state` / `country`. Supplies the **default** for a plugin's own `location_city` / `location_state` / `location_country` setting, so weather, radar and friends follow this device without being configured twice. A value saved on the plugin itself still overrides it. Starlark (Tidbyt) apps get the same treatment: a `Location` field left blank on the app renders at this city (geocoded once via Open-Meteo, coordinates cached permanently) instead of the app author's default, which is usually San Francisco. If the city can't be looked up (no match, or the geocoder is unreachable; retried after 30 minutes), the app keeps its own default. | `SchemaManager.apply_device_location()`, then plugins via merged config; `src/device_location.py` for Starlark apps |
 
 ## `schedule` — display on/off hours
 

docs/STARLARK_APPS_GUIDE.md

@@ -139,9 +139,10 @@ Each app may have different configuration options:
 
 - **Location** (lat/lng/timezone): For weather, clocks, transit. Left blank,
   the app renders at this device's location (City / State / Country under
-  General settings). Without that, most community apps fall back to their
+  General settings). If no city is set there, or the city can't be looked up
-  author's hard-coded default, usually San Francisco. Fill it in only to
+  (no match, or the geocoder is unreachable -- retried after 30 minutes), the
-  point one app somewhere else.
+  app gets no location and falls back to its author's hard-coded default,
+  usually San Francisco. Fill it in only to point one app somewhere else.
 - **API Keys**: For services like weather, stocks, sports scores
 - **Display Preferences**: Colors, units, layouts
 - **Dropdown Options**: Team selections, language, themes

web_interface/templates/v3/partials/starlark_config.html

@@ -221,7 +221,7 @@
                                    data-starlark-location-key="timezone">
                         </div>
                     </div>
-                    <p class="text-xs text-gray-500 mt-1">Leave latitude and longitude blank to use this device's location (City / State / Country in General settings).</p>
+                    <p class="text-xs text-gray-500 mt-1">Leave latitude and longitude blank to use this device's location (City / State / Country in General settings). If no city is set there, or it can't be looked up, the app uses its own default.</p>
                     {% if field_desc %}
                     <p class="text-xs text-gray-400 mt-1">{{ field_desc }}</p>
                     {% endif %}