Add manual stop creation and override alerts with alternate stop codes (#74)

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: arielcostas <94913521+arielcostas@users.noreply.github.com>
Co-authored-by: Ariel Costas Guerrero <ariel@costas.dev>

1 files changed, 75 insertions, 8 deletions

diff --git a/data/README.md b/data/README.md
index 6aa2e10..2cf8151 100644
--- a/data/README.md
+++ b/data/README.md
@@ -1,8 +1,10 @@
-# Bus Stop Overrides
+# Bus Stop Overrides and Manual Stops
 
-This file defines custom overrides for specific bus stops in YAML format.
+This directory contains YAML files for overriding properties of existing bus stops and manually adding new stops.
 
-## Format
+## Overrides Format
+
+Overrides modify or extend properties of existing stops from the transit API.
 
 ```yaml
 stopId:            # Numeric ID of the stop to override
@@ -16,20 +18,56 @@ stopId:            # Numeric ID of the stop to override
     amenities:       # List of amenities available at this stop (list)
         - shelter
         - display
+    cancelled:       # Mark stop as cancelled/out of service (boolean)
+    title:           # Alert title shown to users (string)
+    message:         # Alert message shown to users (string)
+    alternateCodes:  # Alternative stop codes (list of strings)
+        - "ALT-123"
+```
+
+## Adding New Stops
+
+New stops that don't exist in the transit API can be added directly in override files using the `new: true` parameter. The `new` parameter is automatically removed after the stop is added to the list.
+
+```yaml
+stopId:            # Numeric ID for the new stop (must not conflict with existing stops)
+    new: true        # Mark this as a new stop (required, will be removed after processing)
+    name:            # Name of the stop (string)
+    location:        # Location coordinates (required for new stops)
+        latitude:      # Latitude coordinate (float)
+        longitude:     # Longitude coordinate (float)
+    lines:           # List of lines serving this stop (list of strings)
+        - "1"
+        - "2"
+    amenities:       # Optional: List of amenities (list)
+        - shelter
+    title:           # Optional: Alert title (string)
+    message:         # Optional: Alert message (string)
+    cancelled:       # Optional: Mark as cancelled (boolean)
+    alternateCodes:  # Optional: Alternative stop codes (list)
 ```
 
 ## Field Descriptions
 
 - **stopId** (integer): Unique identifier of the bus stop.  
+- **new** (boolean): Set to `true` to add a new stop that doesn't exist in the API. This parameter is removed after processing.
+- **name** (string): Override or set the stop name.
 - **alternateNames** (object): Other names used in different contexts.
     - **key** (string): Name used in a specific context, such as `metro`.
 - **location** (object):
-    - **latitude** (float): Override latitude coordinate.  
-    - **longitude** (float): Override longitude coordinate.  
+    - **latitude** (float): Override/set latitude coordinate.  
+    - **longitude** (float): Override/set longitude coordinate.  
+- **lines** (array of strings): List of line numbers serving this stop (required for new stops).
 - **hide** (boolean): Set to `true` to exclude the stop from maps and listings.  
-- **amenities** (array of strings): Amenities available at this stop, such as `shelter` or `display`. For now, only those two will be supported in the app.
+- **cancelled** (boolean): Set to `true` to mark the stop as cancelled or out of service.
+- **title** (string): Alert title displayed to users (e.g., "Stop Temporarily Closed").
+- **message** (string): Detailed message about the stop status or alert.
+- **alternateCodes** (array of strings): Alternative stop codes or identifiers.
+- **amenities** (array of strings): Amenities available at this stop, such as `shelter` or `display`.
+
+## Examples
 
-## Example
+### Override Example
 
 ```yaml
 12345:
@@ -42,5 +80,34 @@ stopId:            # Numeric ID of the stop to override
     hide: false
     amenities:
         - shelter
-        - real-time display
+        - display
+    title: "Stop Relocated"
+    message: "This stop has been temporarily moved 50 meters north."
+```
+
+### New Stop Example
+
+```yaml
+99999:
+    new: true
+    name: "New Development Stop"
+    location:
+        latitude: 42.229188
+        longitude: -8.722469
+    lines:
+        - "5"
+        - "12"
+    amenities:
+        - shelter
+```
+
+### Cancelled Stop Example
+
+```yaml
+54321:
+    cancelled: true
+    title: "Stop Out of Service"
+    message: "This stop is temporarily closed for construction. Use stop 54322 (100m south) instead."
+    alternateCodes:
+        - "54322"
 ```