docs: turn the root README into a project landing page

Reduce the root README to project discovery and navigation: what
irtt-rs is, its relationship to upstream IRTT (including a factual
capability comparison checked against upstream v0.9.2), installation,
a short quick start, and links out to detailed documentation. Detailed
CLI behavior, output/measurement semantics, continuous-mode memory
guidance, and server bind/session/negotiation semantics move into new
manpage-shaped docs under docs/ (irtt-rs, irtt-client, irtt-tui,
irtt-server), rewritten as operational guidance rather than copied
verbatim from the old README sections they replace.

docs/irtt-server.md

@@ -0,0 +1,261 @@
+# irtt-server
+
+## NAME
+
+irtt-server - IRTT-compatible UDP server
+
+## SYNOPSIS
+
+`irtt-server` [`--bind` *ADDR*]... [*OPTIONS*]
+
+`irtt-rs server` [`--bind` *ADDR*]... [*OPTIONS*]
+
+## DESCRIPTION
+
+`irtt-server` answers IRTT echo requests over UDP. It is thin orchestration
+over the reusable `irtt-server` library: one current-thread Tokio runtime,
+one or more listeners, and the library's own session/policy logic.
+
+Run with no arguments for the ordinary case:
+
+```sh
+irtt-server
+```
+
+With no `--bind`, the server listens on the standard IRTT port (2112) on the
+wildcard address for both address families, in this fixed order:
+
+1. `[::]:2112`
+2. `0.0.0.0:2112`
+
+This is available wherever the platform supports safe wildcard reply-source
+selection (see [Wildcard binds](#wildcard-binds) below). Any explicit
+`--bind` **replaces** this default pair entirely rather than adding to it —
+`irtt-server --bind 127.0.0.1:2112` binds only that one address.
+
+If one of the two default addresses cannot be bound because its address
+family itself has no local support at all — IPv6 disabled on an otherwise
+IPv4-capable host, for example — the server falls back to serving just the
+other one instead of failing outright, and says so on startup. Any other
+reason a default listener fails — the port already in use, permission
+denied, no safe wildcard reply-source path — is not a family-support
+problem and is not silently worked around; the invocation fails as it would
+for an explicit `--bind`. This fallback applies only to the implicit default
+pair: an explicit `--bind` list always keeps the ordinary all-or-nothing
+behavior described below.
+
+## OPTIONS
+
+### `--bind ADDR`
+
+Local UDP address to bind, as `ADDR:PORT`, for example `127.0.0.1:2112` or
+`[::1]:2112`. Host names are not resolved. Repeatable.
+
+Repeat the option to serve several addresses from one process, in the order
+given. Every listener applies the same policy options, but each keeps its
+own sessions and tokens, so a session belongs to the address it was opened
+on. Binding is all-or-nothing: if any address cannot be bound, none are
+served.
+
+A port of `0` selects an unused port per listener, so two such binds get two
+different ports.
+
+With no `--bind` at all, see [Default bind](#default-bind) above.
+
+### `--hmac KEY`
+
+HMAC key, taken as the UTF-8 bytes of this argument. With a key configured,
+every request must carry a valid MAC and every reply is authenticated;
+without one, authenticated requests are dropped. The key is visible in the
+process arguments.
+
+### `--max-sessions COUNT`
+
+Maximum number of simultaneously live sessions **per listener**, not per
+process. Once a listener's table is full, a session-creating open to it is
+dropped silently; nothing is evicted. Zero refuses every session-creating
+open.
+
+### `--max-packet-length BYTES`
+
+Maximum echo datagram size a session may negotiate, in bytes. A longer
+requested length is reduced during negotiation, an open whose mandatory
+field block would not fit is refused, and inbound echo requests are admitted
+against the same limit. This is a resource bound, not an MTU.
+
+### `--min-interval DURATION`
+
+Floor on the send interval a session may negotiate. The negotiated interval
+is still capped at a quarter of the idle timeout afterwards, so a
+`--min-interval` above that cap is not the value actually negotiated.
+
+A session's reply allowance refills at the shorter of this configured floor
+and the interval it actually negotiated. Ordinarily that is the configured
+floor itself, since the negotiated interval is normally at least as long —
+a 10ms `--min-interval` against a 1s negotiated interval refills every
+10ms. The two differ only when the idle-timeout cap above pulled the
+negotiated interval below the configured floor, in which case the shorter,
+negotiated value is what the allowance actually refills at: a server must
+not enforce a cadence it did not advertise to the client. Use `0` for no
+time-based throttling.
+
+### `--burst COUNT`
+
+Echo replies one session may have answered before its allowance has to
+refill. Use `0` for no allowance at all, which rate-limits every echo
+request whatever the interval is.
+
+### `--idle-timeout DURATION`
+
+Release a session after this long without a served or rate-limited echo
+request. The deadline runs from the open, and release is silent. Use `0` to
+expire a session at the next evaluation; it is not a way to disable expiry.
+
+### `--max-duration DURATION`
+
+Maximum test duration a session may negotiate. A longer request is reduced
+to it, and a continuous request is answered with it. Omit this flag for no
+maximum; a maximum of zero cannot be expressed, because a negotiated
+duration of zero means continuous.
+
+### `--timestamp-allowance MODE`
+
+How many timestamps this server will provide: `dual` (default, honors a
+request for send, receive, both, or midpoint timestamps), `single`
+(provides at most one timestamp instant; a request for both is negotiated to
+midpoint), or `none` (no timestamps at all). The requested clock source is
+never changed, only which instants are reported, so a single instant is
+still reported once per requested clock.
+
+### `--no-dscp`
+
+Refuse to provide requested traffic-class marking. Any requested DSCP is
+negotiated to zero, so the client is told its echo replies will be unmarked,
+and they are sent unmarked. The session is not refused.
+
+Durations everywhere in this command accept an integer followed by a unit:
+`ms`, `s`, or `m`.
+
+## OUTPUT
+
+Each bound endpoint is printed on startup, once every listener is up, which
+also resolves a port of `0`:
+
+```
+irtt-server: listening on [::]:2112
+irtt-server: listening on 0.0.0.0:2112
+```
+
+`Ctrl-C` stops the server gracefully.
+
+## MULTIPLE LISTENERS
+
+Every invocation runs through the same multi-listener path, so one address —
+whether from the default pair or a single explicit `--bind` — is an ordinary
+set of one rather than a separate mode. The policy options above apply to
+every listener, but listeners are otherwise independent: each has its own
+sessions and tokens, and `--max-sessions` bounds each listener rather than
+the process. If any listener fails while running, the others are shut down
+with it rather than leaving a service configured for two families answering
+on one.
+
+Wildcard IPv4 and IPv6 listeners may share one port, as the default pair
+does.
+
+## SERVER FILL
+
+Echo replies fill their payload according to the negotiated `ServerFill`
+mode, which a client requests with `irtt-client`'s `--sfill` (see
+`irtt-client(1)`):
+
+- `none`: zero-filled.
+- `rand`: random bytes.
+- `pattern:HEX`: the given repeating hexadecimal pattern.
+
+Every valid descriptor is honored. A descriptor the server cannot parse, and
+a client that expresses no fill preference at all, both get the default
+`pattern:69727474`, i.e. the repeating bytes `69 72 74 74` (`irtt`).
+
+## WILDCARD BINDS
+
+An explicit interface address works on every supported system. A wildcard
+bind such as `0.0.0.0:2112` or `[::]:2112` reads each request's local
+destination from packet metadata and sends that request's reply from the
+same address, so a client on a multi-homed host is answered from the
+endpoint it actually contacted.
+
+That reply-source selection is implemented on **Linux, macOS, and FreeBSD**.
+Elsewhere, a wildcard bind is refused at construction rather than served
+from a routing-table-selected source address a client would discard — this
+also applies to the zero-argument default, which will fail with a clear
+error asking for an explicit `--bind` on such a platform. This correctness
+rule is deliberate and is not weakened by the zero-argument default.
+
+## EXAMPLES
+
+Run with the default wildcard listeners on the standard port:
+
+```sh
+irtt-server
+```
+
+Bind a single explicit address:
+
+```sh
+irtt-server --bind 127.0.0.1:2112
+```
+
+Through the `irtt-rs` dispatcher:
+
+```sh
+irtt-rs server --bind 192.0.2.10:2112
+```
+
+Serve two explicit addresses from one process:
+
+```sh
+irtt-server \
+    --bind 0.0.0.0:2112 \
+    --bind [::]:2112
+```
+
+Apply session policy:
+
+```sh
+irtt-server \
+    --bind 192.0.2.10:2112 \
+    --max-sessions 512 \
+    --idle-timeout 30s
+```
+
+Restrict optional capabilities:
+
+```sh
+irtt-server \
+    --bind 192.0.2.10:2112 \
+    --timestamp-allowance single \
+    --no-dscp
+```
+
+Require authentication:
+
+```sh
+irtt-server --bind 192.0.2.10:2112 --hmac secret
+```
+
+## EXIT STATUS
+
+`0` on a clean shutdown (`Ctrl-C`), nonzero if binding fails or a listener
+fails while running.
+
+## LIMITATIONS
+
+- No hostname resolution, interface expansion, daemonization, or
+  configuration file — binds are explicit addresses only.
+- Wildcard reply-source selection is unavailable outside Linux, macOS, and
+  FreeBSD; such platforms must bind explicit addresses.
+
+## SEE ALSO
+
+`irtt-client(1)`, `irtt-tui(1)`, `irtt-rs(1)`, and `irtt-server --help` for
+the full option list.