lots more refactoring

DOCS.md

@@ -11,9 +11,8 @@ This document describes the current public API for `inire`.
 - `bounds`
 - `nets`
 - `static_obstacles`
-- `locked_routes`
+- `initial_paths`
 - `clearance`
-- `max_net_width`
 - `safety_zone_radius`
 
 ### `RoutingOptions`
@@ -34,21 +33,39 @@ run = route(problem, options=options)
 
 If you omit `options`, `route(problem)` uses `RoutingOptions()` defaults.
 
-### Incremental routing with `LockedRoute`
+The package root is the stable API surface. Deep imports under `inire.router.*` and `inire.geometry.*` remain accessible for advanced use, but they are unstable semi-private interfaces and may change without notice.
 
-For incremental workflows, route one problem, convert a result into a `LockedRoute`, and feed it into the next problem:
+Stable example:
+
+```python
+from inire import route, RoutingOptions, RoutingProblem
+```
+
+Unstable example:
+
+```python
+from inire.router._router import PathFinder
+```
+
+### Incremental routing with locked geometry
+
+For incremental workflows, route one problem, reuse the result's locked geometry, and feed it into the next problem:
 
 ```python
 run_a = route(problem_a)
 problem_b = RoutingProblem(
     bounds=problem_a.bounds,
     nets=(...),
-    locked_routes={"netA": run_a.results_by_net["netA"].as_locked_route()},
+    static_obstacles=run_a.results_by_net["netA"].locked_geometry,
 )
 run_b = route(problem_b)
 ```
 
-`LockedRoute` stores canonical physical geometry only. The next run applies its own clearance rules when treating it as a static obstacle.
+`RoutingResult.locked_geometry` stores canonical physical geometry only. The next run applies its own clearance rules when treating it as a static obstacle.
+
+### Initial paths with `PathSeed`
+
+Use `RoutingProblem.initial_paths` to provide semantic per-net seeds. Seeds are materialized with the current width, clearance, and bend collision settings for the run, and partial seeds are retried by normal routing in later iterations.
 
 ## 2. Search Options
 
@@ -65,7 +82,6 @@ run_b = route(problem_b)
 | `sbend_offsets` | `None` | Optional explicit lateral offsets for S-bends. |
 | `bend_collision_type` | `"arc"` | Bend collision model: `"arc"`, `"bbox"`, `"clipped_bbox"`, or a custom polygon. |
 | `visibility_guidance` | `"tangent_corner"` | Visibility-derived straight candidate strategy. |
-| `initial_paths` | `None` | Optional user-supplied initial paths for warm starts. |
 
 ## 3. Objective Weights
 
@@ -77,7 +93,6 @@ run_b = route(problem_b)
 | `bend_penalty` | `250.0` | Flat bend penalty before radius scaling. |
 | `sbend_penalty` | `500.0` | Flat S-bend penalty. |
 | `danger_weight` | `1.0` | Weight applied to danger-map proximity costs. |
-| `congestion_penalty` | `0.0` | Congestion weight used when explicitly scoring complete paths. |
 
 ## 4. Congestion Options
 
@@ -89,9 +104,9 @@ run_b = route(problem_b)
 | `base_penalty` | `100.0` | Starting overlap penalty for negotiated congestion. |
 | `multiplier` | `1.5` | Multiplier applied after an iteration still needs retries. |
 | `use_tiered_strategy` | `True` | Use cheaper collision proxies in the first pass when applicable. |
-| `warm_start` | `"shortest"` | Optional greedy warm-start ordering. |
+| `net_order` | `"user"` | Net ordering strategy for warm-start seeding and routed iterations. |
+| `warm_start_enabled` | `True` | Run the greedy warm-start seeding pass before negotiated congestion iterations. |
 | `shuffle_nets` | `False` | Shuffle routing order between iterations. |
-| `sort_nets` | `None` | Optional deterministic routing order. |
 | `seed` | `None` | RNG seed for shuffled routing order. |
 
 ## 5. Refinement Options
@@ -126,7 +141,7 @@ run_b = route(problem_b)
 
 ## 8. Internal Modules
 
-Lower-level search and collision modules are internal implementation details. The supported entrypoint is `route(problem, options=...)`.
+Lower-level search and collision modules are semi-private implementation details. They remain accessible through deep imports for advanced use, but they are unstable and may change without notice. The stable supported entrypoint is `route(problem, options=...)`.
 
 ## 9. Tuning Notes