update change file and docs

Assisted-By: devx/aad5d142-46d9-4330-a723-1b17588b7654

Author: brophdawg11

docs/upgrading/future.md

@@ -133,7 +133,7 @@ The flag is also available with `createHashRouter` and `createMemoryRouter`.
 
 **Update your Code**
 
-No route configuration changes are required, but you should review any routes with overlapping patterns to ensure the new ranking behavior selects the intended route.
+No route configuration changes are required, but you should review any routes with overlapping patterns to ensure the new ranking behavior selects the intended route. This is mostly expected to be an issue when you have deep dynamic param paths which could result in an aggregate score that outweighs a shallower static segment route.
 
 For example, both of these routes match `/products/one/two/three`:
 
@@ -142,14 +142,14 @@ const routes = [
   { path: "/products/*", id: "products" },
   {
     path: "/:first/:second/:third/:fourth",
-    id: "four-segments",
+    id: "segments",
   },
 ];
 ```
 
-The legacy matcher selects `four-segments` based on its aggregate segment score. The new matcher selects `products` because its static `products` segment is more specific than the dynamic `:first` segment in the same position.
+The legacy matcher selects `segments` based on its aggregate segment score. The new matcher selects `products` because its static `products` segment is more specific than the dynamic `:first` segment in the same position.
 
-Once you enable this flag, use `router.match()` when you need to match a location. Standalone matching APIs such as `matchRoutes`, `matchPath`, and `useMatch` continue to use the legacy matcher and may return different matches than the router.
+Once you enable this flag, use the `router.match()` when you need to match a location (this is currently marked private and will become stable at the same time this flag stabilizes). Standalone matching APIs such as `matchRoutes`, `matchPath`, and `useMatch` continue to use the legacy matcher and may return different matches than the router.
 
 Case-sensitive routes are not currently supported with this flag.
 

packages/react-router/.changes/unstable.route-pattern-matching.md

@@ -1,11 +1,10 @@
-Add a Data Mode-only POC for route-pattern based route matching
+Add a new Data Mode-only `future.unstable_routePatternMatching` flag to opt into more efficient `@remix-run/route-pattern` based route matching internally
 
-- Adds `future.unstable_routePatternMatching: true` for Data Router matching only
-- Uses `@remix-run/route-pattern` internally to match and rank route branches when the flag is enabled
-- Keeps route definitions and public route/match fields in React Router path syntax
-- Manual matching APIs such as `matchRoutes`, `matchPath`, and `useMatch` continue to use legacy path matching and should not be used once a Data Router opts into `future.unstable_routePatternMatching` because they may not return the same matches as the router
+- No code changes required - syntax remains the same for pubic route definitions and route match fields
+- Once opting into this flag, you should no longer user legacy matching APIs (`matchRoutes`/`matchPath`/`useMatch`) as they are hardcoded to the previous regex-based matcher
+  - A new `router.match()` API exists for those use cases but it's marked private and considered unstable along with the flag
 - Path generation APIs such as `generatePath` and `href` continue to accept React Router path syntax
-- Adds an `unstable_validateParams` POC using keyed regular expressions so a route can reject matched params and let matching continue. Params omitted from a match, such as optional params, are not validated.
+- This flag also comes with a new `unstable_validateParams` route field which uses keyed regular expressions so a route can reject matched params and let matching continue (non-matched optional params are not validated)
 
   ```ts
   let router = createBrowserRouter(