feat(client): atlas roads/settlements overlays + legend + server-API data delivery (T-960, T-949)

T-960: gen_l2_roads (MaintenanceAuthority-colored polylines, rail styling, junction markers) + gen_l3_settlements (size-scaled markers, capital shape, name labels) overlays — cities render on generated bodies for the first time; left-side generation legend panel (D-226 item 3, data-driven per-overlay spec, implant component library); protocol.gd decodes road_graph/settlements + the two new response types. T-949: system_index/atlas_app/overview_screen migrated off the direct star_map_data.json read to StarMapRequest over the bridge (loading state + replay-on-connect, no silent file fallback); atlas_viewer _load_markers requests CityNamesResponse for non-Sol bodies; Sol keeps the legacy authored markers.json geometry read (D-236/T-1073, load-bearing guard). Lead fix: _send_star_map_request now carries the same guard as request_star_map — the autoload's _star_map_wanted leaked across gdUnit suites and the unguarded replay-on-CONNECTED crashed 8 pre-existing flow tests on a Nil bridge; reset_test_state clears the flag. Fixtures regenerated via gen_fixtures (road/settlement samples). Full suite 2946/2946.

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

client/scripts/protocol/protocol.gd

@@ -771,6 +771,12 @@ static func decode_atlas_layer_response(bytes: PackedByteArray) -> Variant:
 
 ## Build an AtlasLayerResponse from an already-decoded raw value. Returns null
 ## if it is not an atlas response (no "status" key).
+## road_graph/settlements (T-960): passthrough fields for the L2 road/rail
+## graph and L3 settlement placements, mirroring the district_grid precedent
+## (T-1046) — raw decoded maps/arrays, no further client-side reshaping.
+## PLACEHOLDER key names ("road_graph"/"settlements") pending confirmation
+## against dudley-atlas-server's RoadGraphLayer/SettlementLayer field names —
+## this is the one spot to rename if the server picks different keys.
 static func atlas_response_from_raw(raw: Variant) -> Variant:
 	if not raw is Dictionary or not raw.has("status"):
 		return null
@@ -787,20 +793,118 @@ static func atlas_response_from_raw(raw: Variant) -> Variant:
 		"status": status,
 		"error": error,
 		"layer1": raw.get("layer1"),
-			"district_grid": raw.get("district_grid"),
+		"district_grid": raw.get("district_grid"),
+		"road_graph": raw.get("road_graph"),
+		"settlements": raw.get("settlements"),
 	}
 
 
-## Decode + classify one inbound frame (#960, D-225). Returns {kind, value} with
-## kind "snapshot" | "atlas" | "unknown" — both are msgpack maps, so they are
-## told apart by field (a response has "status"; a snapshot has "entities").
-## Lets receive_bytes decode the frame ONCE and branch, instead of double-decoding
-## the 20 Hz snapshot path.
+## Decode a status enum shared by StarMapStatus/CityNamesStatus/AtlasLayerStatus
+## shape: a unit variant is a bare string ("Ready", "SolExcluded", …); the one
+## data variant (Error(String)) is a single-key map {"Error": "message"}.
+## Returns {"status": String, "error": String} (error empty unless Error).
+static func _decode_status_field(status_raw: Variant) -> Dictionary:
+	if status_raw is String:
+		return {"status": status_raw, "error": ""}
+	if status_raw is Dictionary and status_raw.has("Error"):
+		return {"status": "Error", "error": str(status_raw["Error"])}
+	return {"status": "", "error": ""}
+
+
+## Encode a StarMapRequest (T-949, D-010) for the Reach-level star-map proxy.
+## `star_map: true` is the mandatory discriminator field the server's demux
+## matches on (dudley-atlas-server contract, 2026-07-14) — always send it,
+## never omit it, or the frame can't be routed.
+static func encode_star_map_request() -> PackedByteArray:
+	var msg := {"star_map": true}
+	var result = _mp().encode(msg)
+	if result.status != null:
+		push_error("Protocol: encode_star_map_request failed: %s" % result.status)
+		return PackedByteArray()
+	return result.value
+
+
+## Build a StarMapResponse from an already-decoded raw value. Returns null if
+## it is not a star-map response (no "status" key). `data` is a verbatim
+## MessagePack re-encoding of star_map_data.json's own top-level shape
+## (`_meta`/`nodes`/`edges`) — unwrapped here so callers (SystemIndex) see the
+## same {"nodes": [...]} shape they'd have gotten from the raw file, and never
+## need to know about the status/data envelope.
+static func star_map_response_from_raw(raw: Variant) -> Variant:
+	if not raw is Dictionary or not raw.has("status"):
+		return null
+	var decoded_status := _decode_status_field(raw.get("status"))
+	var nodes: Array = []
+	if decoded_status["status"] == "Ready":
+		var data: Variant = raw.get("data")
+		if data is Dictionary:
+			nodes = data.get("nodes", [])
+	return {"status": decoded_status["status"], "error": decoded_status["error"], "nodes": nodes}
+
+
+## Decode a StarMapResponse from MessagePack bytes. See star_map_response_from_raw.
+static func decode_star_map_response(bytes: PackedByteArray) -> Variant:
+	return star_map_response_from_raw(decode_raw(bytes))
+
+
+## Encode a CityNamesRequest (T-949, D-223/D-236) for one body's atlas
+## city-name pool. `city_names: true` is the mandatory discriminator field
+## (same contract as StarMapRequest) — without it the request is structurally
+## ambiguous with a malformed AtlasLayerRequest (missing `up_to`). Sent for
+## every body INCLUDING Sol — the server itself reports SolExcluded for those
+## (D-236) as a defensive backstop; atlas_viewer.gd's own guard is expected to
+## make that path rare, not load-bearing on its own.
+static func encode_city_names_request(body_id: String) -> PackedByteArray:
+	var msg := {"city_names": true, "body_id": body_id}
+	var result = _mp().encode(msg)
+	if result.status != null:
+		push_error("Protocol: encode_city_names_request failed: %s" % result.status)
+		return PackedByteArray()
+	return result.value
+
+
+## Build a CityNamesResponse from an already-decoded raw value. Returns null
+## unless it carries both "body_id" and "status". `cities` is a flat array of
+## {city_id, name, is_capital} — no position (that comes from SettlementLayer,
+## T-960's gen_l3_settlements). status is one of "Ready" | "SolExcluded" |
+## "Error" (see _decode_status_field) — SolExcluded means the caller must fall
+## back to the legacy markers.json read for that body (D-236).
+static func city_names_response_from_raw(raw: Variant) -> Variant:
+	if not raw is Dictionary or not raw.has("body_id") or not raw.has("status"):
+		return null
+	var decoded_status := _decode_status_field(raw.get("status"))
+	return {
+		"body_id": str(raw.get("body_id", "")),
+		"status": decoded_status["status"],
+		"error": decoded_status["error"],
+		"cities": raw.get("cities", []),
+	}
+
+
+## Decode a CityNamesResponse from MessagePack bytes. See city_names_response_from_raw.
+static func decode_city_names_response(bytes: PackedByteArray) -> Variant:
+	return city_names_response_from_raw(decode_raw(bytes))
+
+
+## Decode + classify one inbound frame (#960, D-225; T-949 adds starmap/
+## citynames). Returns {kind, value} with kind "snapshot" | "atlas" |
+## "starmap" | "citynames" | "unknown" — all four response kinds are msgpack
+## maps, so they are told apart by field. Checked most-specific-first:
+## StarMapResponse is the only kind with "data" and no "body_id";
+## CityNamesResponse is the only kind with "cities"; anything else carrying
+## "status" is AtlasLayerResponse. Lets receive_bytes decode the frame ONCE
+## and branch, instead of double-decoding the 20 Hz snapshot path.
 static func decode_inbound(bytes: PackedByteArray) -> Dictionary:
 	var raw = decode_raw(bytes)
 	if not raw is Dictionary:
 		return {"kind": "unknown", "value": null}
-	if raw.has("status") and not raw.has("entities"):
+	if raw.has("entities"):
+		return {"kind": "snapshot", "value": _decode_snapshot_from_raw(raw)}
+	if raw.has("data") and not raw.has("body_id"):
+		return {"kind": "starmap", "value": star_map_response_from_raw(raw)}
+	if raw.has("cities"):
+		return {"kind": "citynames", "value": city_names_response_from_raw(raw)}
+	if raw.has("status"):
 		return {"kind": "atlas", "value": atlas_response_from_raw(raw)}
 	return {"kind": "snapshot", "value": _decode_snapshot_from_raw(raw)}