Current Limitation
The AI Gateway documentation is organised around artifacts rather than around what a reader is trying to do. Level-2 nav names components (LLM Proxy, Resiliency, Observability), so a first-time reader can't find how to set the gateway up, authenticate a request, control cost, or troubleshoot a failure.
The structure also contradicts itself: LLM Provider and LLM Proxy are conflated in both the Overview table and the nav, guardrails are nested under LLM Proxy even though our own Overview says they apply at three levels, and two near-identical quick starts have already drifted apart on version strings and prerequisites.
On top of the structural problems, several advertised features are undocumented or unreachable. accessControl appears in 21 of 42 files and is explained in none, there is no inbound client authentication page, token-based rate limiting is advertised in the Overview but has no gateway-side page, spend and cost tracking is absent, 6 of 7 LLM providers have no usable configuration reference, the REST API authentication page is orphaned from the nav, the Overview is doing six jobs in 811 words, Guardrails has no landing page, the eight task guides under guides/ai-and-mcp/ aren't reachable from AI Gateway at all, and the Overview tells readers the real guardrail catalogue lives in a GitHub repository instead of in the docs.
Suggested Improvement
Restructure the AI Gateway section around user jobs at level 2 with a maximum depth of 3, and fill the content gaps that the restructure exposes.
The new shape keeps Overview, Quick Start and a new How It Works page at the top, then groups everything else by job: Run the Gateway, Connect LLM Providers, Expose LLMs to Applications, MCP Proxy, Control Access, Control Content, Control Cost and Traffic, AI Workspace, Monitor Traffic, Extend the Gateway, Guides and Reference. Artifacts stay artifact-shaped only where the artifact is something you create.
The work runs in seven phases: merge the two quick starts and apply OS tabs, apply the new nav with a redirect map, write the landing pages and split the Overview, add one page per supported provider, write the missing access and cost pages (accessControl, client authentication, rate limits, spend), add the AI Workspace bridge with "Requires AI Workspace" badges, and reorder guardrails behind a new catalogue page. Every policy page gains an "Applies to: LLM Provider / LLM Proxy / MCP Proxy" line, and Reference gains an A-Z Policy Index so readers who know a feature's name don't have to guess which job owns it. No existing page is orphaned — all 42 files have a destination.
Version
No response
Current Limitation
The AI Gateway documentation is organised around artifacts rather than around what a reader is trying to do. Level-2 nav names components (LLM Proxy, Resiliency, Observability), so a first-time reader can't find how to set the gateway up, authenticate a request, control cost, or troubleshoot a failure.
The structure also contradicts itself: LLM Provider and LLM Proxy are conflated in both the Overview table and the nav, guardrails are nested under LLM Proxy even though our own Overview says they apply at three levels, and two near-identical quick starts have already drifted apart on version strings and prerequisites.
On top of the structural problems, several advertised features are undocumented or unreachable. accessControl appears in 21 of 42 files and is explained in none, there is no inbound client authentication page, token-based rate limiting is advertised in the Overview but has no gateway-side page, spend and cost tracking is absent, 6 of 7 LLM providers have no usable configuration reference, the REST API authentication page is orphaned from the nav, the Overview is doing six jobs in 811 words, Guardrails has no landing page, the eight task guides under guides/ai-and-mcp/ aren't reachable from AI Gateway at all, and the Overview tells readers the real guardrail catalogue lives in a GitHub repository instead of in the docs.
Suggested Improvement
Restructure the AI Gateway section around user jobs at level 2 with a maximum depth of 3, and fill the content gaps that the restructure exposes.
The new shape keeps Overview, Quick Start and a new How It Works page at the top, then groups everything else by job: Run the Gateway, Connect LLM Providers, Expose LLMs to Applications, MCP Proxy, Control Access, Control Content, Control Cost and Traffic, AI Workspace, Monitor Traffic, Extend the Gateway, Guides and Reference. Artifacts stay artifact-shaped only where the artifact is something you create.
The work runs in seven phases: merge the two quick starts and apply OS tabs, apply the new nav with a redirect map, write the landing pages and split the Overview, add one page per supported provider, write the missing access and cost pages (accessControl, client authentication, rate limits, spend), add the AI Workspace bridge with "Requires AI Workspace" badges, and reorder guardrails behind a new catalogue page. Every policy page gains an "Applies to: LLM Provider / LLM Proxy / MCP Proxy" line, and Reference gains an A-Z Policy Index so readers who know a feature's name don't have to guess which job owns it. No existing page is orphaned — all 42 files have a destination.
Version
No response