update

docs/CONTRACT.md

@@ -22,7 +22,7 @@ type Phase =
   | "error";        // the last long operation failed; see `error`
 
 interface Status {
-  online: boolean;              // the site's update service answered /v1/health
+  online: boolean;              // the site's update service answered /v1/health (2 s, then 10 s if that timed out: a hotspot is slow, not absent)
   site: { url: string; name: string | null };
   operator: string | null;      // last signed-in ODIAN username (cached; valid offline)
   signed_in: boolean;           // this PC remembers the operator's site sign-in until Sign out: the
@@ -64,6 +64,7 @@ interface SyncConflict {
 interface Settings {
   site_url: string;             // e.g. "http://192.168.1.41:30097"
   mcp_url: string;              // site MCP, for Keycloak sign-in
+  ai_url: string;               // MCP serving /api/ai/... over the internet; "" = none
   install_dir: string;
 }
 
@@ -163,8 +164,35 @@ nothing else. Installing from a drive asks the same way: the marketplace opens o
 drive carries, `set_market` records the answer, and `start_install_from_drive` copies it. A PC installed before the marketplace counts what it has on disk as chosen,
 so nothing is removed or downloaded again behind the operator's back.
 
+## AI over the internet
+
+The client is started with `ODIAN_OFFLINE=1`, which blanks the MCP address whatever the
+environment holds: the AI features (destination prediction, chat, vision) answer "not
+available offline" rather than hanging on a call that cannot arrive. An `ai_url` in Settings
+says this PC has a line out: the flag is left off and that address is passed as
+`ODIAN_MCP_API_URL`. Nothing else moves - the data, the tiles and the map stay this PC's own
+local stack - and emptying the field puts the client back to wholly offline. The AI routes
+need no token of their own; `site.json` may carry an `ai_url` so a site ships with one.
+
+## Overlays out of this PC's database
+
+The tile server draws its overlays (aeroways, data centres, gas, hospitals, military bases,
+oil, places of worship, schools) from PostGIS. A site reads the extractor's SQLite files; a
+PC has none of those, so the launcher names each layer in  with the DSN of
+the local database, whose snapshot carries the same tables. One key per layer is required:
+the server looks for that key, then for a DSN under ITS OWN env name, and a layer it cannot
+resolve draws nothing at all rather than failing loudly.
+
 ## Live mode
 
+The DHP names where live mode forwards. `/v1/health` offers `engine_api_urls`, best first:
+the address its own network reaches, then the one that answers from outside. The PC tries
+the one it already uses, then that list in order, and keeps the first that answers - a
+laptop is at the office in the morning and at home in the evening, and neither address
+suits both. `engine_api_url` remains the single address a launcher that ignores the list
+will use, so a site must make that one the address that works from anywhere. None of them
+answering is not an error: the local API serves this PC's own data, as it does offline.
+
 When the DHP advertises an Engine API (`engine_api_url` in its `/v1/health`), the
 launcher starts the local API pointed at it and keeps a token file fresh for it. ODIAN
 always talks to the local API; while the DHP answers, that API forwards the shared-data