OneBusAway · bmander · Jul 21, 2026 · Jul 21, 2026 · Jul 21, 2026
diff --git a/README.md b/README.md
@@ -50,7 +50,7 @@ Did you just set up your own [OneBusAway](https://github.com/OneBusAway/onebusaw
 
 ## Permissions
 
-In order to support certain features in OneBusAway, we need to request various permissions to access information on your device.  See an explanation of why each permission is needed [here](PRIVACY.md).
+In order to support certain features in OneBusAway, we need to request various permissions to access information on your device.  See our [privacy explanation](PRIVACY.md) for why each permission is needed.
 
 ## Troubleshooting
 

diff --git a/docs/BETA_TESTING.md b/docs/BETA_TESTING.md
@@ -44,4 +44,4 @@ You can also reach us via:
 * Email - android-app (at) onebusaway.org
 * Posting a messsage to the [OneBusAway Google+ Community](https://plus.google.com/u/0/communities/105092615216731099521)
 * Posting a messsage on the [onebusaway-developers Google Group](https://groups.google.com/forum/#!forum/onebusaway-developers)
-* Filing a issue on the [OBA Android Github issue tracker](../.github/CONTRIBUTING.md#issue-tracker)
+* Filing an issue on the [OBA Android GitHub issue tracker](../.github/CONTRIBUTING.md#issue-tracker)
diff --git a/docs/DESTINATION_REMINDERS.md b/docs/DESTINATION_REMINDERS.md
@@ -49,7 +49,7 @@ Starting from the second line, here are the columns that contain the position da
 1. coordinateID - unique ID for each location fix in the file
 1. getReadyFlag - true if the "Get Ready" alert has been announced to the user, false if it has not
 1. pullTheCordNowFlag - true if the "Pull the Cord Now" alert has been announced to the user, false if it has not
-1. the time in nanoseconds since the application started
+1. the time in nanoseconds since system boot (`Location.elapsedRealtimeNanos`)
 1. the time in UTC
 1. latitude
 1. longitude

diff --git a/docs/ISSUE_REPORTING.md b/docs/ISSUE_REPORTING.md
@@ -14,20 +14,20 @@ For screenshots and more information, see [this presentation](http://www.slidesh
 
 ## Issue metadata
 
-We capture the below information directly from the OneBusAway server and include it in at the bottom of all issue reports to make it easier to quickly diagnose a problem.
+We capture the below information directly from the OneBusAway server and include it at the bottom of all issue reports to make it easier to quickly diagnose a problem.
 
 For bus stop and other non-arrival time issue categories, include the following info:
 
-~~~
+~~~text
 gtfs_stop_id=Hillsborough Area Regional Transit_420;    // The ID of the stop from OneBusaway - - consists of the GTFS agency_id (or agency_name if agency_id isn't provided), followed by an underscore (_), followed by the GTFS stop_id 
 stop_name=Nebraska Av @ Lake Av;                        // The name of the stop, from GTFS data
 ~~~
 
-You can see an example of this type of report [here](https://seeclickfix.com/issues/3165497-safety-concern).
+You can see an [example of a bus stop issue report](https://seeclickfix.com/issues/3165497-safety-concern).
 
 Arrival/departure time prediction problem reports include more information related to the vehicle and prediction:
 
-~~~
+~~~text
 service_date=01-29-2017;                                // The GTFS date of service when this issue was reported
 agency_name=Hillsborough Area Regional Transit;         // The name of the agency that this report is for
 gtfs_stop_id=Hillsborough Area Regional Transit_5542;   // The ID of the stop from OneBusaway - - consists of the GTFS agency_id (or agency_name if agency_id isn't provided), followed by an underscore (_), followed by the GTFS stop_id
@@ -40,12 +40,12 @@ trip_headsign=East to Yukon Transfer Center;            // The headsign shown to
 predicted=true;                                         // True if real-time information existed for this prediction, False if the schedule time was shown to the rider
 vehicle_id=Hillsborough Area Regional Transit_1305;     // The ID of this vehicle - consists of the GTFS agency_id (or agency_name if agency_id isn't provided), followed by an underscore (_), followed by the vehicle ID from the GTFS-realtime data
 vehicle_location=28.033536911010742 -82.48483276367188; // The location of this vehicle when the user reported the problem
-schedule_deviation=3.000 min early;                     // The real-time prediction from the AVL system, shown as the deviation from the schedule (assuming predicted=true).  This is how early/late a bus is running.  If it's "0", then the bus is runnign on time.
+schedule_deviation=3.000 min early;                     // The real-time prediction from the AVL system, shown as the deviation from the schedule (assuming predicted=true).  This is how early/late a bus is running.  If it's "0", then the bus is running on time.
 stop_arrival_time=03:54 PM;                             // The arrival time that was shown to the user when they reported the problem.  If predicted=true then this is the real-time predicted arrival time, if predicted=false then this is the scheduled time.
 stop_departure_time=03:54 PM;                           // The departure time that was shown to the user when they reported the problem.  If predicted=true then this is the real-time predicted departure time, if predicted=false then this is the scheduled time.
 ~~~
 
-You can see an example of this type of report [here](https://seeclickfix.com/issues/3177416-arrival-times-schedules).
+You can see an [example of an arrival time issue report](https://seeclickfix.com/issues/3177416-arrival-times-schedules).
 
 ### Arrival/departure time issue reports
 

diff --git a/docs/REBRANDING.md b/docs/REBRANDING.md
@@ -20,15 +20,15 @@ We have one Gradle "platform" flavor dimension:
 * **agencyY** = A sample rebranded version of OneBusAway for a fictitious "Agency Y"
 * **kiedybus** = KiedyBus, a Polish transit app
 
-Here's where you can download the apps for each of these brands on Google Play:
+Here's where you can download three of these brands on Google Play (KiedyBus is maintained by a third party and isn't listed here):
 
 * [OneBusAway](https://play.google.com/store/apps/details?id=com.joulespersecond.seattlebusbot)
 * [Agency X](https://play.google.com/store/apps/details?id=org.agencyx.android)
 * [Agency Y](https://play.google.com/store/apps/details?id=org.agencyy.android)
 
-And here are screenshots for these 3 brands:
+And here are screenshots of those same three brands:
 
-<img src="https://cloud.githubusercontent.com/assets/928045/23876835/a6ceb718-0815-11e7-866a-5daef01d0a08.png" width="496" height="281" align=center />
+<img src="https://cloud.githubusercontent.com/assets/928045/23876835/a6ceb718-0815-11e7-866a-5daef01d0a08.png" alt="Side-by-side screenshots of the OneBusAway, Agency X, and Agency Y brands, each showing the same stop and arrival times screen in its own brand colors" width="496" height="281" align=center />
 
 Each brand is deployed as an independent app on Google Play (using the **google** platform flavor).
 
@@ -74,13 +74,13 @@ android.productFlavors {
 }
 ```
 
-See `flavors/README.md` for the complete list of configuration options.
+See [`onebusaway-android/flavors/README.md`](../onebusaway-android/flavors/README.md) for the complete list of configuration options.
 
 ### Step 2: Create Resource Directory
 
 Create minimal resources in `src/newBrandName/res/`:
 
-```
+```text
 src/newBrandName/
 └── res/
     ├── values/
@@ -118,7 +118,8 @@ All other branded strings use `%1$s` placeholders that automatically substitute
     <color name="brand_color_dark">#YOUR_DARK_COLOR</color>
     <color name="theme_muted">#YOUR_MUTED_COLOR</color>
     <color name="theme_accent">#YOUR_ACCENT_COLOR</color>
-    <color name="tutorial_background">#dfYOUR_PRIMARY</color>
+    <!-- Primary color with a "df" alpha prefix (~87% opaque) -->
+    <color name="tutorial_background">#dfYOUR_PRIMARY_COLOR</color>
     <color name="ic_launcher_background">#YOUR_PRIMARY_COLOR</color>
     <!-- Keep on-time color green even if your theme isn't green -->
     <color name="stop_info_ontime">#4CAF50</color>
@@ -189,43 +190,37 @@ Firebase provides analytics and crash reporting. To set up Firebase for your bra
 
 #### Adding Your App to google-services.json
 
-Open `onebusaway-android/google-services.json` and add your app's client entry to the `client` array:
+Open `onebusaway-android/google-services.json` and append the following object to the existing `client` array, leaving `project_info` and the other entries in that array untouched:
 
 ```json
 {
-  "project_info": { ... },
-  "client": [
-    // ... existing entries ...
+  "client_info": {
+    "mobilesdk_app_id": "1:YOUR_PROJECT_NUMBER:android:YOUR_APP_ID",
+    "android_client_info": {
+      "package_name": "com.newbrandname.android"
+    }
+  },
+  "oauth_client": [
     {
-      "client_info": {
-        "mobilesdk_app_id": "1:YOUR_PROJECT_NUMBER:android:YOUR_APP_ID",
-        "android_client_info": {
-          "package_name": "com.newbrandname.android"
-        }
-      },
-      "oauth_client": [
+      "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
+      "client_type": 3
+    }
+  ],
+  "api_key": [
+    {
+      "current_key": "YOUR_FIREBASE_API_KEY"
+    }
+  ],
+  "services": {
+    "appinvite_service": {
+      "other_platform_oauth_client": [
         {
           "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
           "client_type": 3
         }
-      ],
-      "api_key": [
-        {
-          "current_key": "YOUR_FIREBASE_API_KEY"
-        }
-      ],
-      "services": {
-        "appinvite_service": {
-          "other_platform_oauth_client": [
-            {
-              "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
-              "client_type": 3
-            }
-          ]
-        }
-      }
+      ]
     }
-  ]
+  }
 }
 ```
 
@@ -304,7 +299,7 @@ Users can change the sorting style using the "Sort by" button regardless of the
 `USE_PELIAS_GEOCODING` - Controls which service is used for searching origins and destinations in trip planning:
 
 * `true` - Uses the [Pelias geocoder](https://github.com/pelias/pelias) (configured for [geocode.earth](https://geocode.earth/) by default). Requires a Pelias API key in `gradle.properties`:
-  ```
+  ```properties
   Pelias_newBrandName=YOUR_API_KEY
   ```
 * `false` - Uses the [Google Places SDK](https://developers.google.com/places/android-sdk/intro). Requires a Google Maps Platform billing account.
@@ -313,9 +308,9 @@ Users can change the sorting style using the "Sort by" button regardless of the
 
 See the following flavor files for complete examples:
 
-* `flavors/agencyX.gradle` - Multi-region brand with Style A arrivals
-* `flavors/agencyY.gradle` - Fixed-region brand with Style B arrivals
-* `flavors/kiedybus.gradle` - Multi-region brand with custom regions API
+* [`agencyX.gradle`](../onebusaway-android/flavors/agencyX.gradle) - Multi-region brand with Style A arrivals
+* [`agencyY.gradle`](../onebusaway-android/flavors/agencyY.gradle) - Fixed-region brand with Style B arrivals
+* [`kiedybus.gradle`](../onebusaway-android/flavors/kiedybus.gradle) - Multi-region brand with custom regions API
 
 ## Acknowledgements
 

diff --git a/docs/SYSTEM_ARCHITECTURE.md b/docs/SYSTEM_ARCHITECTURE.md
@@ -35,7 +35,7 @@ If you use an issue management system that supports the Open311 standard, you ca
 
 ## Configure your own servers
 
-#### OneBusAway and OpenTripPlanner
+### OneBusAway and OpenTripPlanner
 
 See the [Getting Started](https://github.com/OneBusAway/onebusaway-application-modules#getting-started) section of the [**onebusaway-application-modules**](https://github.com/OneBusAway/onebusaway-application-modules) project to set up your own OneBusAway server - this is a good place to start, and will give you arrival estimates and service alerts in the OneBusAway Android app.
 
@@ -45,6 +45,6 @@ After you've tested arrival information, if you want to add trip planning and/or
 
 When you have this set up, see the [Custom Servers](CUSTOM_SERVERS.md#opentripplanner-api-server) documentation again to point your OBA Android app to your new OTP server.
 
-#### Open311
+### Open311
 
 Currently we don't have a way to easily plug an Open311 server URL directly into the OBA Android app UI to test, but [let us know](https://github.com/OneBusAway/onebusaway/wiki/Contact-Us) if you'd like to test it out and we'll help out.
diff --git a/onebusaway-android/flavors/README.md b/onebusaway-android/flavors/README.md
@@ -103,7 +103,7 @@ Use [Android Asset Studio](http://romannurik.github.io/AndroidAssetStudio/icons-
 
 ### Step 4: Add Firebase Configuration (Optional)
 
-Add your app's Firebase client info to `google-services.json`. See `docs/REBRANDING.md` for detailed instructions.
+Add your app's Firebase client info to `google-services.json`. See [`REBRANDING.md`](../../docs/REBRANDING.md) for detailed instructions.
 
 **Note on API key security:** Firebase API keys in `google-services.json` are safe to commit to version control. Unlike server-side API keys, these client-side keys are designed to be embedded in apps and are protected by:
 - Package name restrictions (the key only works for your specific app ID)