docs: add a docs/ directory

[jacksontj]

Until now the only user-facing documentation was the README (overview + FAQ) and the ~300 lines of YAML comments in cmd/promxy/config.yaml. A number of things that exist in code had no prose documentation at all: the CLI flags, the query path, the metrics promxy exposes, the feature guides, and the remote_write_exporter binary.

This adds docs/ as plain markdown — no site generator, nothing new to maintain in CI.

Layout

Path	Contents
docs/README.md	Index
docs/getting-started.md	Install → minimal config → first query
docs/configuration/	Config file anatomy, every server_groups option, every CLI flag, alert templates
docs/concepts/	Query path and pushdown rules; the anti-affinity merge algorithm
docs/guides/	Multi-tenancy, rules and alerting, native histograms, label filtering, security
docs/operations/	Endpoints and shutdown, metrics, troubleshooting
docs/development.md	Build tags, vendoring, the prometheus fork, repo layout

configuration/README.md rather than index.md so GitHub auto-renders it when browsing the directory.

What is not changed

• The README keeps its overview, quickstart and FAQ, and gains a Documentation section linking into docs/.
• cmd/promxy/config.yaml stays as the annotated example and is linked from the docs.
• Nothing was moved or deleted, so existing links and anchors still resolve.

On accuracy

Content was written against the source rather than paraphrased from the config comments. The metrics reference in particular was checked against a running promxy, so the metric names, label sets (server_group_request_duration_seconds{host,call,status}, server_group_targets{ordinal,name}) and the note about which series only appear after their first observation reflect actual /metrics output. The error format quoted in the troubleshooting doc is copied from live output too.

All ~60 internal links and anchors were verified to resolve, using GitHub's slug rules.

Three things documented as-is that may be worth fixing separately

1. Config.WebConfig is dead config. pkg/config/config.go:103 parses a top-level tls_server_config key in the main config file, but nothing reads it — pkg/server/api.go is driven entirely by --web.config.file. A user setting it today gets silent plaintext. Documented as having no effect.
2. /-/quit is routed but inert. The vendored web handler registers it under --web.enable-lifecycle and closes quitCh, but main.go never selects on webHandler.Quit(). It answers "Goodbye!" and keeps running. Documented as "use SIGTERM".
3. label_filter's default on_sync_error: abort blocks startup silently when a downstream is unreachable — no log output at default level, so it looks like a hang. (Hit this accidentally while testing.) The retry loop is intentional and documented, but a periodic "blocked waiting on label_filter sync" warning would help.

Also worth noting: the README FAQ's version claims ("a fork based on prometheus 2.24", "as recent as 2.13") look stale against the current go.mod fork pin. I left the README prose alone and did not repeat those claims in docs/.

🤖 Generated with Claude Code

https://claude.ai/code/session_015SskNFpr2yDqGLR2NYA6yW