Overture docs update

[MitchellShiell]

Documentation for the Overture docs site, plus factual corrections to two in-repo READMEs. No source code changes.

Three new pages, a restructure of docs/usage/ into docs/reference/, and three corrections to the graphql-router README's network-search section.

New pages

Page	Sidebar	Source of truth
docs/reference/graphql-api.md	GraphQL API (sidebar_position: 2.5)	the generated per-catalogue schema: the single POST /graphql endpoint, SQON and field selection, pagination, sorting, and a pointer to the Introspection API for runtime field discovery
docs/charts.md	Arranger Charts (sidebar_position: 4)	ported from modules/charts/README.md, covering ChartsProvider batching every registered chart into one GraphQL query, plus three screenshots
docs/federated-search.md	Arranger Federated search (sidebar_position: 6)	written from modules/graphql-router/src/network/, not from the README

The federated search page is new coverage, not a port. A sweep of all 74 remote branches found no dedicated page anywhere, only scattered mentions plus an unmerged 2024 design doc on origin/search-docs whose design has since diverged from what shipped. The page states up front that federation returns aggregate counts, not documents (there is no federated hits list), and records that the feature appears under three names: federated search, network search, and network aggregation, with network being what configuration and GraphQL field names use.

Restructure

• docs/usage/* becomes docs/reference/*, and usage.mdx becomes reference.mdx.
• docs/usage/06-ai-and-automation.md becomes docs/mcp-server.md, promoted out of the reference section to a top-level "Arranger MCP server" page.
• docs/migration/v3.1.md becomes docs/reference/08-Migration/v3.1.md.
• Renumbered as fallout: 07-defaults-and-limits to 06, 08-feature-flags to 07.
• Cross-links repointed across overview.md, setup.md, reference.mdx, 02-query-processing.md, 06-defaults-and-limits.md and graphql-api.md.

docs/overview.md also gains a Key Features bullet and a federation pathway; 01-arranger-configs.md notes the optional fifth config file (network.json); 05-introspection.md, 07-feature-flags.md and charts.md gain federation cross-links.

Corrections to modules/graphql-router/README.md, Network search

Three statements were wrong against the code in src/network/:

1. Field merging was described as an intersection. The code takes a union; nodes lacking a field contribute an ___aggregation_not_available___ sentinel bucket rather than dropping the field.
2. remoteRequests.headers and remoteNodes[].requests.headers were presented as arrangerRouter options. They are search-server config-file properties, normalized into a customizeRemoteRequest function, so passing them to the library directly is a silent no-op. Per-node headers also replace the global list rather than merging with it.
3. The example used documentType: 'FileAggs', which resolves to FileAggsAggregations and fails discovery.

apps/mcp-server/README.md is updated for the docs-site URL change.

Rebased onto main

Current with main, no conflicts. 11 commits absorbed, four resolved:

• MCP tool names. 🚚 Chore: Rename MCP Resources and Tools to Use snake_case Instead of kebab-case #1088 renamed them to snake_case on main while this branch still had kebab-case, so main wins on both the tool list and the fuller execute_query signature, verified against apps/mcp-server/src.
• docs/mcp-server.md was combined, keeping main's new query_arranger Prompts block from ✨ Add query-arranger System Prompt and MCP Server instructions (overture-stack/admin#184) #1087 alongside this branch's heading promotion out of reference/.
• Two .dev/ files follow this branch's own chore: drop .dev changes commit, so .dev/ matches main exactly. The exception is tech-debt.md, where both entries are kept because they are additive: this branch's OpenSearch entry records why its Makefile change removes the start-os target.

main also landed eight graphql-router changes around catalogue availability. docs/reference/05-introspection.md already documents the resulting healthy/degraded/unhealthy and available/failed values and all six error codes, each confirmed present in the code, so that page needed no update.

Before merging

• Docs site build was green against the pre-rebase branch tip and has not been re-run since.