Documentation: complete re-analysis and reorganisation, with five end-to-end paths (quick start, stdio, HTTP, HTTP with telemetry and a collector, reverse proxies for LAN and public)

[jmrplens]

Status 2026-09-12

What is left, the earlier body kept below for context:

Plan steps 4, 5, 7, 8, 9, 10, 12, 13, 14, 15 and 16 of docs/development/documentation-audit-2026-09.md: the collector worked example with a compose file for path 4; the single stdio page for path 2; retiring the per-token server prose; single-sourcing the env and flag tables; deciding and writing down the docs/site relationship; the six moves with redirects; icons out of capabilities/; banners on the 27 pages without one; README linking the section indexes; the Spanish reconcile; and the runnable-block harness for the five paths' pages. Also re-verify path 5 end to end on the rewritten proxy configurations now that PR 554 lifted the 403.

---

A complete re-analysis of the documentation for 2.8.0, after the benchmark work (#493) has landed: not a gap check but a review of what the documentation is, how it is organised, and whether a reader can go from nothing to every shape this server runs in without leaving it. External sources (the MCP specification, the SDK, GitLab's own documentation, the OpenTelemetry collector and the proxies' references) are consulted wherever a page needs a fact it does not carry today, and the fact is brought in rather than linked out.

Scope is deliberately open: whatever the review finds is done, including features or logic the server itself turns out to need, new end-to-end tests that prove a documented path, and splitting this issue when a front grows.

The paths a reader must be able to follow end to end

Each of these is a page or a section that a reader can execute top to bottom and end with a working setup, verified by actually doing it on a clean machine (or container) while writing:

1. Quick start. The shortest path to a first tool call, one channel, one client, no options.
2. stdio, configured. The full stdio setup: every relevant variable, the dotenv files and their precedence, tiers, read-only and safe mode, the allow-lists, the client configurations for the clients we document.
3. HTTP. The server in HTTP mode from scratch: instance policy (--gitlab-url, the allow-list, the header), legacy and OAuth authentication, sessions, rate limits, /health, drain, the unix socket, TLS on the listener.
4. HTTP with telemetry. The same, exporting traces, metrics and logs, with a worked example of bringing up the collector (an OpenTelemetry collector configuration and a compose file that starts it beside the server, with a backend that shows the data, and the identity policy choices explained), not only the OTEL_* variables.
5. Reverse proxies, LAN and public. Review and improve every proxy example in docs/guides/remote-deployment.md (nginx, Caddy, Traefik, Apache, Cloudflare Tunnel): one shape for a LAN deployment behind a proxy that terminates nothing, and one for public exposure with TLS, with the headers, timeouts, SSE and prefix rules each one has to get right, each configuration tested against the real binary (the HTTP end-to-end module already drives an nginx layer; extend it where a proxy claim has no test).

Organisation

• Review the structure of docs/ (Diátaxis: getting started, guides, reference, concepts, development) and of the site (EN and ES) against those paths: what is duplicated, what is in the wrong place, what a reader cannot find, which pages contradict each other. Reorganise where the review says so and keep the redirects and cross-links working (the docs domain is path-preserving).
• Every page carries the audience and prerequisites banner, and every generated block stays generated.
• The Spanish site follows the English one page for page.

Acceptance

• Each of the five paths above is executed from its own page on a clean environment and works as written.
• The organisation review is recorded (what moved, what merged, what was removed and why), and every gate over documentation is green: markdownlint, format_md_tables, check-doc-tool-names, check-llms, check-site-stats, the site lint in both languages.
• Anything the review finds in the server itself (a flag that does not do what its page says, a behaviour the documentation cannot describe honestly) is fixed, not documented around.

[jmrplens]

The re-analysis itself landed in PR 545 as docs/development/documentation-audit-2026-09.md with the five-path table and a sixteen-step plan, and steps 1, 2 and 3 in part, 6 and 11 and the enterprise deployment section are done (PRs 546, 547, 551, 554). The rest of the plan is not: there is still no collector worked example, no stdio page, the six moves have not happened, 27 pages carry no audience banner and there is no runnable-block harness. I have rewritten the body to the remaining steps and moved the issue to 3.1.0.