Update documentation to describe default route filtering behavior

- Add "Route filtering" subsection to prediction.md explaining trip-level
  vs block-level filtering, when each is used, and how to control it
- Update code examples in prediction.md to reflect new defaults (deadhead
  is now opt-in, not default)
- Add explanation in index.md quickstart about filtering modes with
  examples showing both trip-level and block-level usage

Agent-Logs-Url: https://github.com/NatLabRockies/routee-transit/sessions/2ff76f0b-42a6-4a2d-89df-ecd5324791de

Co-authored-by: dan-mccabe <25916826+dan-mccabe@users.noreply.github.com>

Author: Copilot

docs/index.md

@@ -34,6 +34,17 @@ predictor.run(
 )
 ```
 
+By default, route filtering works at the **trip level**, so individual trips on the requested routes are always included even if their block also serves other routes. If you enable deadhead trip estimation, filtering automatically switches to **block level** to ensure complete blocks (see [](prediction) for details):
+
+```python
+predictor.run(
+    date="2023/08/02",
+    routes=["806", "807"],
+    add_mid_block_deadhead=True,
+    add_depot_deadhead=True,
+)
+```
+
 For a full example, see [](examples/Utah_Transit_Agency_example).
 
 ## Available Models

docs/prediction.md

@@ -13,6 +13,25 @@ The full workflow proceeds in four stages:
 
 RouteE-Transit reads a standard GTFS feed directory and loads trips along with their shape traces, stop locations, and stop times. Users can optionally filter to a specific service date and/or a subset of routes. The shape traces and scheduled stop times are used downstream to estimate average speed and distance at the road link level.
 
+### Route filtering
+
+By default, route filtering is **trip-level**: only trips whose `route_short_name` appears in the `routes` list are included, regardless of what other routes share the same GTFS block. This gives the most intuitive results, especially for agencies where interlining is common (e.g., a bus block might serve both route 5 and route 21).
+
+When deadhead trips are requested (`add_mid_block_deadhead=True` or `add_depot_deadhead=True`), filtering automatically switches to **block-level** mode. In block-level mode, entire blocks are excluded if *any* trip in the block belongs to a route not in the requested set. This is necessary because deadhead estimation requires complete blocks. If block-level filtering removes all trips but trip-level filtering would have kept some, the error message will explain this and suggest alternatives (either disabling deadhead or adding the additional interlined routes to the `routes` list).
+
+When using `filter_trips()` directly, you can control this behavior with the `use_block_filter` parameter:
+
+```python
+predictor.load_gtfs_data()
+
+# Trip-level filtering (default) — individual trips on route "5" are
+# always kept, even if their block also serves route "21"
+predictor.filter_trips(routes=["5"])
+
+# Block-level filtering — only blocks that exclusively serve route "5"
+predictor.filter_trips(routes=["5"], use_block_filter=True)
+```
+
 See [](data:gtfs-reqs) for the full list of required GTFS files and fields.
 
 ## 2) Deadhead Trip Inference
@@ -77,6 +96,15 @@ predictor = GTFSEnergyPredictor(
 )
 
 # Option 1: Use the convenience method (recommended)
+# By default, only revenue trips are included (no deadhead).
+trip_results = predictor.run(
+    date="2023/08/02",
+    routes=["205"],
+)
+
+# Option 2: Include deadhead trips and HVAC impacts
+# When deadhead is enabled with route filtering, block-level filtering
+# is used automatically to ensure complete blocks.
 trip_results = predictor.run(
     date="2023/08/02",
     routes=["205"],
@@ -85,7 +113,7 @@ trip_results = predictor.run(
     add_hvac=True,
 )
 
-# Option 2: Step-by-step processing for more control
+# Option 3: Step-by-step processing for more control
 predictor.load_gtfs_data()
 predictor.filter_trips(date="2023/08/02", routes=["205"])
 predictor.add_mid_block_deadhead()  # Between-trip deadhead