# Summary: hxprobe usage reference doc + standalone Makefile

Plan: [docs/plans/2026-07-02-10-22-hxprobe-usage-doc-and-makefile.md](../plans/2026-07-02-10-22-hxprobe-usage-doc-and-makefile.md)

## What was built

- **`hxprobe/USAGE.md`** (new): a "Runnable Usage Reference" matching the
  depth/format of `python/configs/usage-latprobe.md` (concrete `sh` command
  → real captured output, brief explanatory notes, `---` section
  separators). 16 cases: basic, verbose (HTTPS, plain HTTP, redirect
  followed, `--no-follow-redirects`, `--no-http2`, TLS failure, DNS
  failure), sampling, multi-URL, `--fail`, JSON, JSON+verbose, timeout,
  exit-codes table, Makefile shortcuts (both `hxprobe/Makefile`'s own and
  the parent repo's `hx-*` ones). Placed inside `hxprobe/` per the user's
  explicit choice, so the doc travels with the project if it's ever
  extracted to its own repo.
- **`docs/usage/hxprobe.md`** (edit): one-line pointer added at the top to
  `hxprobe/USAGE.md`. No other changes.
- **`hxprobe/Makefile`** (new): standalone, `help`/`deps`/`run`/`lint`/
  `fmt`/`test`/`test-integration`/`check`/`clean`, same auto-generated
  `## comment` help style as the root Makefile. Deliberately independent
  from the root Makefile's `hx-*` targets (neither calls into the other) —
  explicit user decision over the "delegate" alternative.

## Key design decisions

- **Every output in `USAGE.md` is real, freshly captured this session** —
  10 of 16 cases were run live during implementation specifically for this
  doc (TLS failure, sampling ×2, multi-URL, `--fail`, JSON ×2, timeout,
  basic, plain-HTTP), the rest reused real captures from earlier in the
  same session (redirect-follow, `--no-follow-redirects`, `--no-http2`, DNS
  failure) since the code hadn't changed since those were taken. No numbers
  were fabricated or extrapolated.
- **Timeout example uses `192.0.2.1`, not `10.255.255.1`.** Tested both:
  `10.255.255.1` resolves to an immediate `connect: Connection refused` in
  this dev sandbox (the sandbox's network layer actively rejects the
  packet rather than dropping it silently), which would misrepresent the
  timeout path. `192.0.2.1` (RFC 5737 TEST-NET-1, reserved/unreachable)
  reliably produces a genuine ~500ms timeout here, so that's what the doc
  uses and explains.
- **No delegation between the two Makefiles**, per explicit user
  instruction — both have complete, independent implementations of the
  same `uv sync`/`uv run pytest`/`ruff` commands. This is deliberate
  duplication: a change to one Makefile's command flags won't silently
  break the other, at the cost of needing to update both if the underlying
  `uv run ...` invocations ever change.
- **`hxprobe/Makefile` target names have no `hx-` prefix** (`run`, `test`,
  not `hx-run`, `hx-test`) since the prefix's whole purpose — disambiguating
  from `go-*`/`py-*` targets in the same file — doesn't apply once you're
  already inside `hxprobe/`'s own Makefile.

## Deviations from the plan

One, driven by what the live network in this sandbox actually does: the
plan didn't anticipate the timeout target needing to change from
`10.255.255.1` (used in `latprobe`'s own timeout example) to `192.0.2.1`.
Discovered and resolved by testing both live before writing the doc, rather
than assuming `latprobe`'s example target would work identically for
hxprobe.

## Verification

- `cd hxprobe && make help` — lists all 9 targets, no dependency on the
  root Makefile
- `cd hxprobe && make run ARGS="-v https://example.com"` — matches
  `make hx-run ARGS="-v https://example.com"` output shape from the repo
  root (both Makefiles agree independently)
- `cd hxprobe && make check` — 28 hermetic tests pass (lint + test)
- `cd hxprobe && make test-integration` — 9 live tests pass
- Every command block in `USAGE.md` was actually executed during
  authoring; output pasted directly from the terminal, not hand-edited
  beyond JSON float-precision rounding (documented as such in the doc)
- `git diff Makefile` — confirms the root Makefile's `hx-*` section is
  unchanged by this task