docs(config): require scope regions and surface MeshMapper integrations (#8)

app_config/config.yaml.example

@@ -1,6 +1,37 @@
 # Beacon configuration file
 # Copy to config.yaml and adjust as needed.
 
+# MeshMapper integrations (optional, no API key). Import transport scopes and
+# IATA border outlines from MeshMapper instead of maintaining scopes: and
+# iatas.*.borderFile by hand. Both need the IATAs to be in a configured region below.
+#
+# Scope-name discovery. Manual scopes remain authoritative.
+# Sources must belong to a configured region's IATAs.
+# Group endpoints are not supported: their names cannot be attributed to each IATA.
+# At most 16 sources, 64 names per source, 64 KiB per response; no page scraping.
+# Catalogues and ETags persist in PostgreSQL. Failed refreshes retain known names.
+# Refresh success/failure/freshness is logged under component=meshmapper.scopes.
+# Removing/turning off a source deactivates its imported matching keys on restart;
+# historical scope identities and recorded evidence are retained.
+# Region-filtered scope lists and scope stats show imported names only under the
+# IATAs whose catalogue lists them; regions without a source show manual scopes only.
+#meshmapper:
+#  scopes:
+#    enabled: false
+#    refresh_interval: 1h  # 5m-24h; one source checked per 15s tick
+#    sources:
+#      YOW: https://yow.meshmapper.net/get_scopes.php
+#
+# Region boundaries (Zones API). Every IATA in a configured
+# region is looked up in its country's zone list, then its get_geojson.php outline
+# is imported. An imported boundary overrides that IATA's borderFile on the border
+# map and for nodes.mark_foreign. A missing or failed boundary keeps the last good
+# import, or the borderFile when there is none. Disabling, or removing an IATA from
+# every region, drops its import on restart. Logged under component=meshmapper.zones.
+#  zones:
+#    enabled: false
+#    refresh_interval: 24h # 1h-168h; one request per 15s tick, ETag-conditional
+
 iatas:
   YVR:
     name: Vancouver International
@@ -61,9 +92,14 @@ channel_keys:
 
 # Regional transport scopes for matching TRANSPORT_FLOOD packets.
 # Plain names have # prepended automatically (e.g. "bc" → "#bc").
+# region (required) is a configured region slug; region-filtered scope lists
+# and scope stats show the scope under that region's IATAs. Matching stays global.
+# Optional when meshmapper.scopes covers your regions.
 scopes:
   - name: bc
+    region: western-canada
   - name: "#west"
+    region: western-canada
 
 telemetry:
   retention: 672h   # 4 weeks

docker-deployment-type1/data/app/config.yaml

@@ -1,6 +1,37 @@
 # Tower configuration file
 # Copy to config.yaml and adjust as needed.
 
+# MeshMapper integrations (optional, no API key). Import transport scopes and
+# IATA border outlines from MeshMapper instead of maintaining scopes: and
+# iatas.*.borderFile by hand. Both need the IATAs to be in a configured region below.
+#
+# Scope-name discovery. Manual scopes remain authoritative.
+# Sources must belong to a configured region's IATAs.
+# Group endpoints are not supported: their names cannot be attributed to each IATA.
+# At most 16 sources, 64 names per source, 64 KiB per response; no page scraping.
+# Catalogues and ETags persist in PostgreSQL. Failed refreshes retain known names.
+# Refresh success/failure/freshness is logged under component=meshmapper.scopes.
+# Removing/turning off a source deactivates its imported matching keys on restart;
+# historical scope identities and recorded evidence are retained.
+# Region-filtered scope lists and scope stats show imported names only under the
+# IATAs whose catalogue lists them; regions without a source show manual scopes only.
+#meshmapper:
+#  scopes:
+#    enabled: false
+#    refresh_interval: 1h  # 5m-24h; one source checked per 15s tick
+#    sources:
+#      YOW: https://yow.meshmapper.net/get_scopes.php
+#
+# Region boundaries (Zones API). Every IATA in a configured
+# region is looked up in its country's zone list, then its get_geojson.php outline
+# is imported. An imported boundary overrides that IATA's borderFile on the border
+# map and for nodes.mark_foreign. A missing or failed boundary keeps the last good
+# import, or the borderFile when there is none. Disabling, or removing an IATA from
+# every region, drops its import on restart. Logged under component=meshmapper.zones.
+#  zones:
+#    enabled: false
+#    refresh_interval: 24h # 1h-168h; one request per 15s tick, ETag-conditional
+
 iatas:
   YVR:
     name: Vancouver International
@@ -109,9 +140,14 @@ channel_keys:
 
 # Regional transport scopes for matching TRANSPORT_FLOOD packets.
 # Plain names have # prepended automatically (e.g. "bc" → "#bc").
+# region (required) is a configured region slug; region-filtered scope lists
+# and scope stats show the scope under that region's IATAs. Matching stays global.
+# Optional when meshmapper.scopes covers your regions.
 scopes:
   - name: bc
+    region: western-canada
   - name: "#west"
+    region: western-canada
 
 telemetry:
   retention: 672h   # 4 weeks