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.

[justincorrigible]

these tool names are stale: the MCP server registers them as snake_case, not kebab-case.

• list-catalogues should be list_catalogues
• get-sqon-schema should be get_sqon_schema
• get-catalogue-fields should be get_catalogue_fields
• execute-query should be execute_query

these were renamed to snake_case in #1088. The PR description says this branch already rebased past that change, so it looks like this new table just didn't pick up the rename when it was written

[MitchellShiell]

fixed!

[justincorrigible]

since this content already lives in the same repo, three of these links could point at it directly instead of the docs site:

• Arranger Overview (line 15) to ./docs/overview.md
• Setting up the Development Environment (line 16) to ./docs/setup.md
• Reference Docs (line 17) to ./docs/reference/reference.mdx.
  one tradeoff worth knowing: docs/reference/reference.mdx and the pages it links to use Docusaurus-specific syntax (the DocCardList component, ::: admonition blocks), which renders as plain text on GitHub rather than the docs site's styled callouts, still fully readable, just less polished

... your call on these.

[MitchellShiell]

updated, went with all three in-repo

[justincorrigible]

on the other hand, this Contributing Guide link (line 30) could similarly point at ./CONTRIBUTING.md, which already exists at the repo root with matching content, and would be directly relevant to Arranger's own specific contributions rather than a generic Overture.
I dare say that should be the priority for this specific link, across all repos, because each repo has nuances that are not "generic" as non-devs may imagine can be.

...but importantly: GitHub also gives root-level CONTRIBUTING.md special treatment (it's auto-surfaced on new issues and PRs), so linking to it directly is arguably more useful than the external link, not just an equivalent swap at all.

for contrast, the Support Guide and quickstart guides links are fine left as-is, since that content is org-wide or platform-wide and doesn't live in this repo

[MitchellShiell]

Keeping it to Arranger in this PR but will update across the board

[MitchellShiell]

fixed