chore: improve documentation and README

docs/INTEROP_COMPARISON.md

@@ -1,4 +1,38 @@
-# Interop Comparison
+# Interop comparison
+
+## Feature comparison
+
+This compares `irtt-rs` with the original [heistp/irtt](https://github.com/heistp/irtt)
+release [v0.9.2](https://github.com/heistp/irtt/releases/tag/v0.9.2) (2026-07-17).
+The aim is for the two implementations to interoperate, though the interop
+tests and verified protocol baseline still use upstream v0.9.1. Both
+upstream releases use wire protocol version 1, but v0.9.2 hasn't been run
+through this project's interop harness. See [`docs/protocol/`](protocol/)
+for the verified protocol baseline.
+
+| Capability | irtt-rs | Upstream IRTT (v0.9.2) |
+| --- | --- | --- |
+| Wire protocol | Version 1, verified against upstream v0.9.1 | Version 1, unchanged from v0.9.1 |
+| Finite probing | Default duration of 10s | Default duration of 1m |
+| Continuous probing | `--continuous` or `--duration 0`, with optional per-target reconnection | Streaming mode (`-s`, added in v0.9.2) |
+| Statistics in continuous mode | Optional count/min/max/mean/variance per session, with bounded IPDV tracking and no exact medians. Disable with `--no-stats` or omit the `stats` feature | No statistics; raw/event output only to avoid unbounded memory |
+| Multiple targets | Labels and staggered/burst pacing in one invocation | One remote address per invocation |
+| Terminal UI | Live graph and dashboard through `irtt-tui` | None |
+| Output formats | table, csv, tsv, jsonl, with selectable columns | Text summary, JSON (optionally gzip to file), and fixed-field raw output; no CSV/TSV or column selection |
+| Replay saved results | Not implemented | `report` subcommand for saved JSON results |
+| Benchmarking and clock diagnostics | Not implemented | Benchmarking and timer/clock-diagnostic subcommands |
+| Client payload and timing controls | No client-side payload fill or don't-fragment/wait-strategy/timer-algorithm controls | Client-side payload fill and controls for don't-fragment, wait strategy, and timer algorithm |
+| Kernel timestamps | Best-effort preference on Linux for its own send/receive endpoint | Not implemented |
+| Server listeners | Several listeners in one process, supervised by `ServerSet` | Multiple requested addresses through `ListenAndServe` |
+| Server wildcard reply-source selection | Default on Linux/macOS/FreeBSD; other platforms refuse wildcard binds | Opt-in through `--set-src-ip`, with a documented per-packet allocation cost |
+| Server default bind | Wildcard addresses for both families, subject to the platform restriction above | Wildcard addresses for both families; no documented platform restriction |
+| Server payload fill policy | Honors the session's negotiated request, with a fixed fallback pattern; no options to restrict or override it | Options to restrict or override client fill requests |
+| Syslog logging | Not implemented | Supported |
+| Bundled service files | None | systemd and OpenRC |
+| Client/server library API | Separate, independently versioned Rust crates (`irtt-client`, `irtt-server`) | One Go package exposing both roles |
+| Prebuilt release binaries | Published for six target triples | None published; install through `go install` or build manually |
+
+## Black-box testing
 
 `scripts/compare_irtt_clients.py` is a black-box comparison harness for running
 upstream `irtt` and `irtt-rs` clients concurrently against the same server. It
@@ -8,7 +42,7 @@ summaries, and comparison JSON under `target/interop-comparisons` by default.
 The harness does not inspect upstream source or tests. It only invokes the
 upstream executable.
 
-## Remote or Existing Local Server
+### Remote or Existing Local Server
 
 Build `irtt-rs` and ensure an upstream `irtt` executable is available:
 
@@ -36,7 +70,7 @@ python3 scripts/compare_irtt_clients.py \
 Remote comparisons are useful for smoke coverage, but Internet paths are noisy
 and can make RTT/loss differences hard to interpret.
 
-## Linux Netem Interop
+### Linux Netem Interop
 
 `scripts/run_netem_interop_ci.py` provides deterministic Linux CI coverage using
 network namespaces, a veth pair, and `tc netem`. It is intended for GitHub
@@ -69,7 +103,7 @@ Netem qdiscs are applied on veth egress:
 Cleanup deletes qdiscs, stops the server process, and removes both namespaces in
 a `finally` path.
 
-### Scenarios
+#### Scenarios
 
 The CI harness implements:
 
@@ -86,7 +120,7 @@ both clients run in the same client namespace against the same server namespace,
 relative one-way shape is still useful for diagnostics, but the CI pass/fail
 policy is based on RTT and packet behavior.
 
-### Pass/Fail Policy
+#### Pass/Fail Policy
 
 Deterministic scenarios fail when:
 
@@ -113,7 +147,7 @@ python3 scripts/run_netem_interop_ci.py \
   --loss-rate-warning-pct 12
 ```
 
-### Manual Linux Usage
+#### Manual Linux Usage
 
 On Linux: