# Deployed Sign Map

Map deployed transit signs and kiosks against verified GTFS stops and routes, with player health and phone navigation.

**CoWork project:** CW-033 — Deployed Sign Map  
**Version:** 0.1.0  
**Type / status:** Tool / Beta prototype  
**Owner:** Bryan Gilliom  
**Contributor:** Codex  
**Updated:** October 28, 2026  
**Git repository:** https://git2.mpm.to/mpm/deployed-sign-map

## Overview

This working prototype combines a read-only OnSign player snapshot, an official public GTFS feed, and a native CAD/AVL stop-ID crosswalk. It supports service technicians, salespeople, and implementation teams who need to see deployed devices alongside their stops and scheduled routes. It preserves the difference between a bus-stop coordinate and the surveyed location of a physical sign. It does not modify OnSign or the CAD/AVL system.

The captured RTC Washoe pilot is complete as a snapshot. Conversion into an installable skill or plugin, live refresh, and other-agency support remain future work. There is no SKILL.md, plugin manifest, or new MCP server in this package.

## Capabilities and planned skill entry points

| Capability | Current behavior | Potential trigger |
|---|---|---|
| Deployment map | Shows field signs and kiosks with online/offline icons and excluded test/showroom records | “Map the deployed signs for this agency” |
| Native stop crosswalk | Resolves each OnSign `-S` ID through native `SrcStopID` to GTFS `stop_id`; retains comma-separated kiosk IDs individually | “Crosswalk the player stop IDs to GTFS” |
| Route geometry | Joins resolved stops to active GTFS trips; renders ordered shapes using `route_color` | “Show the routes serving these signs” |
| Service navigation | Provides Apple Maps and Google Maps driving links using GTFS coordinates | “Navigate to this stop” |
| Quiet basemaps | CARTO Positron vector, labels or no labels; hidden POIs; Esri gray, original streets, and plain background | “Use a quieter basemap” |
| Predeployment planning | Not built; planned spreadsheet/list intake with the same reconciliation rules | “Map these planned stop installations” |

These are prototype capabilities and proposed skill triggers, not already installed tools.

## Contents

- `source/`: Python preparation, read-only native API fetch, renderer, integrity checks, HTML template, and pinned third-party map libraries.
- `sample-work/rtc-washoe/`: credential-free HTML map, source snapshots, public GTFS ZIP, resolved crosswalk, verification results, and PNG previews. Keep operational sample data in Coordination Drive, not in the public Git repository.
- `HANDOFF-BRIEF.md`: accepted decisions, evidence, open work, and exact continuation steps.
- `Wiki V2.md`: source for the native Google Docs wiki.
- `file-manifest.json`: file sizes and SHA-256 values for the archived package.

## Tools and interfaces used

| System | Read operations used in this work |
|---|---|
| Existing OnSign MCP (CW-032) | `find_players`, `account_summary`, `get_player`; investigation also used `get_data_feed` and `whats_playing` |
| Native Vontas traveler API | `GetStop`; `GetStopRouteTrip` was used to establish stop/trip identifier evidence; `?WSDL` exposed the read operation schema |
| Public GTFS | `feed_info`, `calendar`, `calendar_dates`, `stops`, `stop_times`, `trips`, `routes`, `shapes` |
| Browser map | Leaflet 1.9.4, MapLibre GL JS 5.6.2, MapLibre–Leaflet integration 0.1.3 |

## Reproduce the captured snapshot

Python 3 is sufficient for the data scripts. Third-party map libraries and their license notices are included under `source/vendor/`.

From the package root, with the source and sample-work archives extracted into sibling directories:

```bash
python3 source/scripts/prepare_data.py \
  --players sample-work/rtc-washoe/onsign-players.json \
  --native sample-work/rtc-washoe/native-stops.json \
  --gtfs sample-work/rtc-washoe/rtc-gtfs.zip \
  --service-date 2026-10-28 \
  --output-dir dist

python3 source/scripts/verify_snapshot.py \
  --data dist/rtc-map-data.json \
  --native sample-work/rtc-washoe/native-stops.json \
  --gtfs sample-work/rtc-washoe/rtc-gtfs.zip

python3 source/scripts/render_map.py \
  --data dist/rtc-map-data.json \
  --output dist/rtc-washoe-sign-map.html

python3 -m http.server 8765 --bind 127.0.0.1
```

Open `http://127.0.0.1:8765/dist/rtc-washoe-sign-map.html`. The archive contains no API key. It defaults to Esri Gray Canvas; selecting a CARTO style asks for a basemap key held in that tab only. Rendering with `--include-carto-key` explicitly embeds `RTC_CARTO_BASEMAP_KEY`; use that only for an approved browser-key distribution.

The snapshot feed covers September 5, 2026–January 1, 2027. Replaying the captured date is intentional. A live rebuild requires a newly downloaded official feed, a fresh OnSign snapshot, and fresh native responses; do not present this capture as current health.

### Read native stops for a new snapshot

Set `RTC_NATIVE_API_BASE` to the approved HTTPS ASMX service URL and `RTC_NATIVE_API_KEY` through a secure local environment. Do not put credentials in a command, Git file, report, or handoff.

```bash
python3 source/scripts/fetch_native_stops.py \
  --players input/onsign-players.json \
  --output input/native-stops.json
```

The script calls only `GetStop`, validates the returned `StopID`, stores credential-free responses, throttles requests, and exits with an error if any requested ID fails. It does not fetch player records itself; the host must supply the existing OnSign MCP export.

### Setup checklist

- [ ] Extract source and private sample-work packages into the expected directory structure.
- [ ] Use Python 3 and a browser with WebGL for vector basemaps.
- [ ] Run preparation and integrity verification before rendering.
- [ ] Choose an approved CARTO basemap key or a key-free alternative.
- [ ] Preserve attribution for CARTO/OpenStreetMap or Esri and the bundled library notices.
- [ ] For live work, refresh inputs and label the OnSign/native/feed timestamps separately.

## Connection and credential model

| Field | Behavior |
|---|---|
| OnSign | Existing account-scoped, read-only MCP; no new direct OnSign API key is required by this tool |
| Native stop API | HTTPS GET; key stays in the acquisition process; authenticated URLs are not printed |
| Basemaps | Online CARTO vector service uses a browser basemap key; Esri/OSM raster and plain alternatives are available |
| Map data | Stops, routes, shapes, crosswalk, and player health are embedded as a captured snapshot |
| Remote writes | None to OnSign or native CAD/AVL |

## Workflow rules

1. Verify the agency's current official feed and service-date coverage before matching stops.
2. Extract native `-S` IDs, including each comma-separated kiosk ID. Preserve excluded records without inventing positions.
3. Use the native API's explicit `SrcStopID` crosswalk. Never assume a numeric native stop ID equals GTFS `stop_id`.
4. Use GTFS latitude/longitude for all markers and navigation. OnSign GPS, manually placed positions, and IP geolocation are not coordinate authority.
5. Derive route associations from resolved stop IDs, `stop_times`, and active `trips`; derive line geometry from ordered `shapes`. Never infer a route from a nearby line or equate native and GTFS route IDs.
6. For kiosks, use a clearly labeled parent-station anchor; derive routes from the resolved bay list, not every bay at the station.
7. Report ID failures, name conflicts, and native-versus-GTFS coordinate differences separately. The current 25 m flag is a review threshold, not a measured GPS accuracy claim.
8. Preserve keys outside published maps by default. Maintain private customer snapshots separately from public code.

## Known limits and troubleshooting

| Symptom / limit | Action |
|---|---|
| Source-stop ID is missing from current GTFS | Stop the build and obtain an agency crosswalk; do not guess coordinates |
| Kiosk bays do not share one GTFS parent station | Require explicit review; the current prototype stops rather than selecting an arbitrary anchor |
| CARTO background is missing | Check basemap key, connectivity, WebGL, and attribution; choose Esri or plain background |
| Feed has expired | Download the official current feed for a live rebuild; use the captured service date only to replay this sample |
| Source template has RTC-specific dates and copy | Generalize these before using another agency; current data scripts expose a service-date argument but the UI is still a pilot template |
| Rapid basemap switching logs an abort | A removed vector map can cancel an outstanding request; verify the selected basemap finishes loading |
| Phone navigation | Links and destinations were verified in the browser; physical iPhone/Android launch was not tested |
| Live device health / detours / arrivals | Not implemented; captured health and static scheduled service only |

## Requirements and licenses

Python 3 standard library; Leaflet 1.9.4; MapLibre GL JS 5.6.2; MapLibre–Leaflet integration 0.1.3; optional CARTO basemap access; authorized existing OnSign MCP and native API access for acquisition. Bundled upstream licenses are in `source/vendor/`. No redistribution license has been selected for MPM-authored source; creating a public repository does not by itself grant an open-source license.