diff --git a/docs/custom-usage-examples.md b/docs/custom-usage-examples.md
new file mode 100644
index 0000000..51f3857
--- /dev/null
+++ b/docs/custom-usage-examples.md
@@ -0,0 +1,295 @@
+# Custom Usage Examples
+
+All examples assume the binary has been built first:
+
+```sh
+make build
+# binary is now at go/latprobe
+```
+
+Estimated runtimes assume a typical home broadband connection.
+The timeout flag is shortened to `--timeout 3s` wherever non-routable IPs are
+used, so each timed-out sample fails in 3 s instead of the default 10 s.
+
+---
+
+## Example 1 — Clean global sweep, text output (single sample)
+
+10 sites distributed across continents, one request each.
+**All sites accessible. Exit code: 0.**
+
+```sh
+./go/latprobe \
+  https://www.google.com \
+  https://www.bbc.co.uk \
+  https://www.lemonde.fr \
+  https://www.spiegel.de \
+  https://www.yahoo.co.jp \
+  https://www.alibaba.com \
+  https://www.globo.com \
+  https://www.abc.net.au \
+  https://www.thehindu.com \
+  https://www.timeslive.co.za
+```
+
+*Estimated runtime: ~30 s — shows per-phase breakdown once per site.*
+
+---
+
+## Example 2 — Clean global sweep, 10 samples, text output
+
+Same 10 sites, 10 requests each — reveals real latency distribution (min/avg/max).
+**All sites accessible. Exit code: 0.**
+
+```sh
+./go/latprobe -n 10 \
+  https://www.google.com \
+  https://www.bbc.co.uk \
+  https://www.lemonde.fr \
+  https://www.spiegel.de \
+  https://www.yahoo.co.jp \
+  https://www.alibaba.com \
+  https://www.globo.com \
+  https://www.abc.net.au \
+  https://www.thehindu.com \
+  https://www.timeslive.co.za
+```
+
+*Estimated runtime: ~3–5 min — best for spotting jitter and TTFB variance.*
+
+---
+
+## Example 3 — Clean global sweep, 10 samples, JSON output
+
+Same as Example 2, machine-readable. Pipe into `jq` to extract specific phases.
+**All sites accessible. Exit code: 0.**
+
+```sh
+./go/latprobe -n 10 --json \
+  https://www.google.com \
+  https://www.bbc.co.uk \
+  https://www.lemonde.fr \
+  https://www.spiegel.de \
+  https://www.yahoo.co.jp \
+  https://www.alibaba.com \
+  https://www.globo.com \
+  https://www.abc.net.au \
+  https://www.thehindu.com \
+  https://www.timeslive.co.za
+
+# Extract average total latency per site:
+./go/latprobe -n 10 --json \
+  https://www.google.com https://www.bbc.co.uk https://www.lemonde.fr \
+  https://www.spiegel.de https://www.yahoo.co.jp https://www.alibaba.com \
+  https://www.globo.com https://www.abc.net.au https://www.thehindu.com \
+  https://www.timeslive.co.za \
+  | jq '.[] | {url, avg_total_ms: .phases.total.avg_ms}'
+```
+
+*Estimated runtime: ~3–5 min.*
+
+---
+
+## Example 4 — DNS failures mixed in (exit code 2)
+
+8 accessible sites + 2 non-existent domains.
+The `.invalid` TLD is guaranteed NXDOMAIN by RFC 6761.
+**Expected exit code: 2.**
+
+```sh
+./go/latprobe -n 10 \
+  https://www.google.com \
+  https://www.bbc.co.uk \
+  https://www.lemonde.fr \
+  https://www.spiegel.de \
+  https://www.yahoo.co.jp \
+  https://www.alibaba.com \
+  https://www.globo.com \
+  https://www.abc.net.au \
+  https://nonexistent-host-one.invalid \
+  https://nonexistent-host-two.invalid
+```
+
+*Estimated runtime: ~2–3 min — DNS failures resolve near-instantly.*
+
+---
+
+## Example 5 — Connection refused mixed in (exit code 3)
+
+8 accessible sites + 2 localhost ports with nothing listening.
+**Expected exit code: 3.**
+
+```sh
+./go/latprobe -n 10 \
+  https://www.google.com \
+  https://www.bbc.co.uk \
+  https://www.lemonde.fr \
+  https://www.spiegel.de \
+  https://www.yahoo.co.jp \
+  https://www.alibaba.com \
+  https://www.globo.com \
+  https://www.abc.net.au \
+  http://127.0.0.1:1 \
+  http://127.0.0.1:19999
+```
+
+*Estimated runtime: ~2–3 min — refused connections fail immediately.*
+
+---
+
+## Example 6 — Timeout failures mixed in (exit code 4)
+
+8 accessible sites + 2 non-routable IPs (RFC 5737 documentation range,
+packets are dropped by the network). `--timeout 3s` keeps each failed
+sample to 3 s instead of the default 10 s.
+**Expected exit code: 4.**
+
+```sh
+./go/latprobe -n 10 --timeout 3s \
+  https://www.google.com \
+  https://www.bbc.co.uk \
+  https://www.lemonde.fr \
+  https://www.spiegel.de \
+  https://www.yahoo.co.jp \
+  https://www.alibaba.com \
+  https://www.globo.com \
+  https://www.abc.net.au \
+  https://192.0.2.1 \
+  https://203.0.113.1
+```
+
+*Estimated runtime: ~3–4 min — timeout IPs add 3 s × 10 samples = 30 s each.*
+
+---
+
+## Example 7 — HTTP error status with `--fail` (exit code 6)
+
+8 accessible sites + 2 URLs that return 4xx/5xx. Without `--fail` these
+would exit 0; with it, exit code becomes 6.
+**Expected exit code: 6.**
+
+```sh
+./go/latprobe -n 10 --fail \
+  https://www.google.com \
+  https://www.bbc.co.uk \
+  https://www.lemonde.fr \
+  https://www.spiegel.de \
+  https://www.yahoo.co.jp \
+  https://www.alibaba.com \
+  https://www.globo.com \
+  https://www.abc.net.au \
+  https://httpbin.org/status/404 \
+  https://httpbin.org/status/503
+```
+
+*Estimated runtime: ~2–3 min — full timing captured even for error responses.*
+
+---
+
+## Example 8 — TLS failures mixed in (exit code 5)
+
+8 accessible sites + 2 HTTPS servers with bad certificates.
+`badssl.com` is a purpose-built TLS testing service.
+**Expected exit code: 5.**
+
+```sh
+./go/latprobe -n 10 \
+  https://www.google.com \
+  https://www.bbc.co.uk \
+  https://www.lemonde.fr \
+  https://www.spiegel.de \
+  https://www.yahoo.co.jp \
+  https://www.alibaba.com \
+  https://www.globo.com \
+  https://www.abc.net.au \
+  https://self-signed.badssl.com \
+  https://expired.badssl.com
+```
+
+*Estimated runtime: ~2–3 min — TLS failures surface DNS + connect timing.*
+
+---
+
+## Example 9 — All failure types, full matrix (exit code 5)
+
+10 accessible sites + one of each failure class. Exercises every code path:
+DNS (exit 2), connect (exit 3), timeout (exit 4), TLS (exit 5),
+HTTP error with `--fail` (exit 6). Highest code wins → **exit 5** (TLS is
+5, HTTP error is 6 — but exit 6 if httpbin is reachable).
+**Expected exit code: 6 (with --fail).**
+
+```sh
+./go/latprobe -n 10 --fail --timeout 3s \
+  https://www.google.com \
+  https://www.bbc.co.uk \
+  https://www.lemonde.fr \
+  https://www.spiegel.de \
+  https://www.yahoo.co.jp \
+  https://www.alibaba.com \
+  https://www.globo.com \
+  https://www.abc.net.au \
+  https://www.thehindu.com \
+  https://www.timeslive.co.za \
+  https://nonexistent-host.invalid \
+  http://127.0.0.1:1 \
+  https://192.0.2.1 \
+  https://httpbin.org/status/500 \
+  https://self-signed.badssl.com
+```
+
+*Estimated runtime: ~5–7 min — the comprehensive stress test.*
+
+---
+
+## Example 10 — Quick smoke test, single sample, JSON, all failure types
+
+Same 15 targets as Example 9 but `-n 1` for a fast sanity check.
+JSON output lets you pipe results to `jq` for filtering.
+**Expected exit code: 6 (with --fail).**
+
+```sh
+./go/latprobe -n 1 --fail --timeout 2s --json \
+  https://www.google.com \
+  https://www.bbc.co.uk \
+  https://www.lemonde.fr \
+  https://www.spiegel.de \
+  https://www.yahoo.co.jp \
+  https://www.alibaba.com \
+  https://www.globo.com \
+  https://www.abc.net.au \
+  https://www.thehindu.com \
+  https://www.timeslive.co.za \
+  https://nonexistent-host.invalid \
+  http://127.0.0.1:1 \
+  https://192.0.2.1 \
+  https://httpbin.org/status/500 \
+  https://self-signed.badssl.com
+
+# Show only failed entries:
+./go/latprobe -n 1 --fail --timeout 2s --json \
+  https://www.google.com \
+  https://nonexistent-host.invalid \
+  http://127.0.0.1:1 \
+  https://192.0.2.1 \
+  https://httpbin.org/status/500 \
+  https://self-signed.badssl.com \
+  | jq '.[] | select(.failed > 0 or .status >= 400)'
+```
+
+*Estimated runtime: ~30–60 s — fastest end-to-end check of all error paths.*
+
+---
+
+## Exit code reference
+
+| Code | Meaning |
+|------|---------|
+| 0 | All probes succeeded |
+| 1 | Usage error |
+| 2 | DNS resolution failure |
+| 3 | Connection failure |
+| 4 | Timeout |
+| 5 | TLS handshake failure |
+| 6 | HTTP status ≥ 400 (only with `--fail`) |
+
+When multiple failure types occur, the process exits with the **highest** code.