docs(router): align dynamic subgraph routing docs with override_subgraph_urls all/subgraphs schema

[Copilot]

Documentation graphql-hive/router#987

Router docs were still describing the legacy flat override_subgraph_urls shape, while router now uses subgraphs plus optional global all. This update brings configuration and expression docs in sync with the new schema and runtime variables.

• Configuration reference: override_subgraph_urls

  • Reworked docs to describe:
    • override_subgraph_urls.subgraphs.<name>.url for per-subgraph overrides
    • override_subgraph_urls.all.expression for global fallback logic
  • Clarified precedence: explicit per-subgraph overrides win over all.
  • Added examples for both static and expression-based URL overrides in the new shape.

• Expression context updates

  • Documented .request.url_matches for path params captured from http.graphql_endpoint patterns.
  • Clarified .subgraph.name availability in dynamic routing expressions.
  • Updated dynamic URL expression examples to reflect the expanded context.

• Guide updates: dynamic subgraph routing

  • Migrated guide snippets from legacy flat config to subgraphs-nested YAML.
  • Kept examples focused on practical routing patterns (canary, regional) with the current schema.

override_subgraph_urls:
  all:
    expression: |
      if .subgraph.name == "products" && .request.headers."x-region" == "us-east" {
        "https://products-us-east.example.com/graphql"
      } else {
        .default
      }
  subgraphs:
    reviews:
      url:
        expression: |
          if .request.headers."x-user-region" == "eu-west" {
            "https://reviews-eu-west.example.com/graphql"
          } else {
            .default
          }

[Copilot]

Pull request overview

This PR updates the Hive Router documentation to reflect the current override_subgraph_urls schema (with subgraphs overrides plus an optional global all fallback), and refreshes expression-context documentation used for dynamic routing.

Changes:

• Updated the Dynamic Subgraph Routing guide examples from the legacy flat override_subgraph_urls shape to the subgraphs-nested structure.
• Reworked the override_subgraph_urls configuration reference to document subgraphs.<name>.url plus a global all.expression fallback and precedence.
• Expanded expression docs to include .request.url_matches and clarified .subgraph availability for dynamic routing expressions.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.

File	Description
packages/documentation/content/docs/router/guides/dynamic-subgraph-routing.mdx	Migrates guide YAML examples to override_subgraph_urls.subgraphs.* and documents .subgraph.name in routing context.
packages/documentation/content/docs/router/configuration/override_subgraph_urls.mdx	Documents the new all + subgraphs structure, precedence rules, and adds examples including url_matches.
packages/documentation/content/docs/router/configuration/expressions.mdx	Adds .request.url_matches and clarifies where .subgraph is available.

Comments suppressed due to low confidence (3)

packages/documentation/content/docs/router/configuration/override_subgraph_urls.mdx:106

• Same as above: this section says .request includes "query parameters", but the expressions docs don’t list any query-parameter field. Please align the documented .request shape across pages (either add the missing field to expressions.mdx or remove the mention here).

Within the `expression`, you have access to:

- `.request`: The incoming HTTP request object (headers, query parameters, parsed operation, and
  `url_matches`).
- `.default`: The original subgraph URL from the supergraph schema.
- `.subgraph.name`: The name of the subgraph currently being resolved.

packages/documentation/content/docs/router/configuration/override_subgraph_urls.mdx:77

• subgraphs.<name>.url is marked as Required: Yes, which could be misread as required for the overall feature even when using only override_subgraph_urls.all. Consider clarifying the requirement as "required when defining a subgraphs.<name> override" to avoid confusion.

### `subgraphs.<name>.url`

- **Type:** `string` or `object`
- **Required:** Yes

packages/documentation/content/docs/router/configuration/override_subgraph_urls.mdx:66

• The example uses http.graphql_endpoint: /{tenant}/graphql and refers to .request.url_matches.tenant, but the http configuration docs currently only document {wildcard} and {tail}* path captures. Either update the http docs to explicitly cover named parameters like {tenant}, or adjust this example to use the documented {wildcard}/{tail} patterns to avoid inconsistency.

If `http.graphql_endpoint` uses path parameters, they are available under `.request.url_matches`:

```yaml
http:
  graphql_endpoint: /{tenant}/graphql
override_subgraph_urls:

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[ardatan]

@copilot apply changes based on the comments in this thread

[github-actions]

Deployment	URL
🌐 Website	https://537a3a21-hive-platform-docs.theguild.workers.dev
📚 Storybook	https://pr-117.the-guild-docs-storybook.pages.dev

[Copilot]

@copilot apply changes based on the comments in this thread

Applied the requested thread changes in eddd506.

• Removed undocumented .request query-parameter claims from override_subgraph_urls docs.
• Aligned url_matches examples to documented endpoint capture syntax using /graphql/{wildcard} and .request.url_matches.wildcard in both relevant docs files.