first commit

docs/geospatial/logistics/ports/src/data/rail-terminals/rail-terminals.md

@@ -0,0 +1,57 @@
+# rail-terminals
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+Curated dataset of major rail freight terminals — primarily the
+inland container hubs on the New Silk Road and Trans-European rail
+freight corridors — exported as the readonly `railTerminals` array.
+Each record conforms to the `Port` interface (with `type: "rail"`) and
+carries a UIC railway code for cross-system identification.
+
+## Features
+
+- Coverage spans China's interior rail hubs, the Trans-Siberian and
+  Trans-Mongolian routes, the European TEN-T corridors, and select
+  North American intermodal centres.
+- Each record carries `uicCode` (where assigned) and `iataCode`
+  (intermodal interchange terminals).
+- Facility tags reflect rail-specific capabilities (`intermodal`,
+  `bonded_warehouse`, `container`, `bulk`, `roro`).
+- IANA timezones populated for every record so consumers can derive
+  local times for cross-border schedules.
+
+## Usage: Basic
+
+```ts
+import { railTerminals } from "@suaveplan/ports/data/rail-terminals";
+
+console.log("rail terminal count:", railTerminals.length);
+```
+
+## Usage: Advanced
+
+```ts
+import { railTerminals, findNearestPort } from "@suaveplan/ports";
+
+const nearest = findNearestPort(
+    { latitude: 50.1, longitude: 8.7 }, // Frankfurt
+    railTerminals
+);
+```
+
+## API Reference
+
+- `railTerminals: readonly Port[]` — curated rail-freight terminal set.
+
+## Implementation Notes
+
+Every entry uses a UN/LOCODE primary key. `uicCode` is populated only
+where the terminal has an assigned UIC code — pure intermodal yards
+without a UIC registration leave the field undefined. The dataset is
+curated rather than exhaustive: it captures the rail-freight hubs most
+likely to appear in cross-modal ETA calculations against this package's
+shipping-lane registry.