docs: comment/doc accuracy sweep (audit group D)

Fourteen text-only fixes where a public contract lagged the code it
describes: the coverage doc's TLS claims predate the tls-e2e dind job
(mutual TLS IS CI-verified); run(client, request) described the reaper
as process-global (it is per-daemon, keyed by endpoint URL);
ExecOptions denied exec-with-stdin on the named pipe (message-mode
pipes half-close fine - every real daemon's pipe is one); the API-pin
rationale now cites the actual newest need (volume-prune all, 1.42);
compose_image() no longer calls the cli image "ambassador"; the one
stale test-index entry in 66 files (DockerAuthCredentialHelper suite
rename); the coverage doc's audit date; ContainerSpec's long-outgrown
"deliberately small"; the "stateless host config" comments x3 (the
client carries a lazy version pin); Kafka's to_generic() throw list
gains the topic validation; make_request's pre-Session "for now";
feature-notes' "modules remain planned"; the Http wait documents the
in-container HTTPS workaround; docs/conventions.md gains the
error-message style rule (lowercase clause, single-quoted values,
opportunistic alignment).

Pipeline: MSVC 563 units, WSL gcc 557 units, clang-tidy and
clang-format clean (text-only change). Opus review: SHIP; the one
recommendation applied (Container's mutable-client comment no longer
overclaims "an active Session" - no Container path opens one).

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_0141x8KrNdD9NfmCh1vSMbpg

Author: cppudge

docs/conventions.md

@@ -31,6 +31,14 @@ only when it is actually being followed.
   using testcontainers::docker::demux_all;
   ```
 
+## Error messages
+- A `throw` message is a lowercase clause (no leading capital, no trailing
+  period) that names what failed first and quotes interesting values in single
+  quotes: `throw Error("init script 'seed.sql' has an extension ...")`. Add
+  context the catcher cannot reconstruct (the resource, the actual value) —
+  not what the exception type already says. Existing messages are aligned
+  opportunistically when a throw site is touched anyway; no big-bang sweep.
+
 ## Backlog
 - Known limitations and deferred work are tracked in [`TODO.md`](TODO.md), not
   scattered through code comments. When you spot tech debt during review, add it there.

docs/feature-notes.md

@@ -52,8 +52,9 @@ stay independent.
 **API version pin** (2026-07-05) — every typed `DockerClient` method pins its path to
 `/v1.NN`, negotiated once per client instance the way the docker CLI does it: one unversioned
 `GET /_ping`, then `min(kClientApiVersion = 1.44, daemon's Api-Version header)`, compared
-numerically ("1.9" < "1.44"). 1.44 covers everything the library uses (newest need:
-`?platform=` on create, 1.41) and is the negotiation floor of daemons that dropped the old
+numerically ("1.9" < "1.44"). 1.44 covers everything the library uses (newest need: the
+`all` filter on volume prune, 1.42 — see the kClientApiVersion comment) and is the
+negotiation floor of daemons that dropped the old
 versions; an old daemon wins with its own version. Copies inherit the negotiated version (the
 drop-time DELETE of a `Container` handle re-uses it — no second ping); a daemon that reveals no
 parsable version falls back to unversioned paths (its default version, the old behavior). The
@@ -127,8 +128,8 @@ hooks → start → wait → handle) lives in `detail::Runner`; `GenericImage::s
 `run(to_request())`. Public `run(request)` / `run(client, request)` bootstrap the Reaper and
 delegate; the core skips reaper bootstrap so unit tests drive it against a canned responder.
 A hand-built request owns the consistency of the port trio (typed `exposed_ports` vs rendered
-`spec.exposed_ports` vs `publish_all_ports`). Modules (Postgres/Redis/…) remain planned as
-composition over `GenericImage`.
+`spec.exposed_ports` vs `publish_all_ports`). Modules (Postgres/Redis/…, landed 2026-07-12)
+are exactly that composition over `GenericImage` — see "Ecosystem modules" below.
 
 **Lifecycle hooks + startup retry** — `with_created/starting/started/stopping_hook`
 (`LifecycleHook = std::function<void(DockerClient&, const std::string& id)>`) and

docs/public-api-test-coverage.md

@@ -1,7 +1,7 @@
 # Public API integration-test coverage
 
-Audit date: 2026-07-05. Updated the same day after the gap-closing test batch
-(verified live: Linux engine and Windows engine CI runs green).
+Audit date: 2026-07-05; last updated 2026-07-12 (the module layer and the
+pre-0.2.0 audit fixes; verified live: Linux and Windows engine CI runs green).
 
 This file audits the integration-test coverage of every public interface under
 `include/testcontainers/` against a real Docker daemon, in each of the two engine
@@ -474,9 +474,10 @@ Notes:
 | TLS disabled build (`TC_TLS=OFF`) | ✅ | ✅ | ✅ TlsTransport.DisabledBuildThrowsClearError + unit TransportTimeout.TlsDisabledConnectThrowsNamedError (CI: linux-minimal job) | ✅ (same tests; daemon-independent) |
 | `TransportTimeouts` | ✅ | ✅ | ❌ (unit-tested) | ❌ |
 
-TLS is exercised against an in-process self-signed server, not a real remote
-daemon (see feature-notes: end-to-end TLS against a real daemon is not
-CI-verified). The npipe (Windows) and unix-socket (Linux) transports are
+TLS is exercised against an in-process self-signed server (the tests above)
+AND end to end in CI against a real `--tlsverify` daemon — the `tls-e2e`
+docker:dind job runs mutual TLS (see feature-notes). The npipe (Windows) and
+unix-socket (Linux) transports are
 exercised by every daemon-touching test in their respective modes; TCP is the
 default CI transport shape for the named-pipe/socket cases.
 
@@ -545,5 +546,6 @@ connect, build-context variants, typed 404s on Linux are all now covered).
 5. **Remaining builder options** — Network `Builder::with_name` /
    `with_enable_ipv6` / `with_option`; Volume `Builder::with_driver` /
    `with_driver_opt`; `with_platform`; `with_create_body_patch`.
-6. **`TransportTimeoutError` against a real wedged endpoint** and end-to-end TLS
-   to a real remote daemon (feature-notes.md records both as not CI-verified).
+6. **`TransportTimeoutError` against a real wedged endpoint** (feature-notes.md
+   records it as not CI-verified; end-to-end TLS to a real daemon is covered by
+   the `tls-e2e` dind job since 2026-07-11).

include/testcontainers/Container.hpp

@@ -287,10 +287,11 @@ class Container {
     /// is best-effort and must never propagate, especially from the destructor).
     void fire_stopping() noexcept;
 
-    // Mutable: the client is just a stateless host config that opens a fresh
-    // connection per call, so issuing requests through it is logically const
-    // from the handle's point of view (const accessors like get_host_port /
-    // is_running / logs need it).
+    // Mutable: requests through the client are logically const from the
+    // handle's point of view (const accessors like get_host_port / is_running
+    // / logs need it). The client is connection-per-request; its lazy state
+    // (the negotiated API-version pin) is instance-internal under the usual
+    // one-instance-one-thread rule.
     mutable DockerClient client_;
     std::string id_;
     bool dropped_ = false;

include/testcontainers/ContainerRequest.hpp

@@ -98,10 +98,10 @@ Container run(const ContainerRequest& request);
 
 /// As above, but on a caller-supplied client — for a custom daemon endpoint or
 /// tuned transport timeouts. The reaper is booted on `client`'s daemon (not the
-/// environment one); note it is process-global and binds to the FIRST daemon it
-/// starts against — later runs against a different daemon in the same process
-/// get labels but no crash-safe reaping. The client is copied into the
-/// returned handle.
+/// environment one); reapers are per-daemon, keyed by endpoint URL, so a
+/// second daemon used in the same process gets its own crash-safe reaper (two
+/// URL spellings of one daemon count as two endpoints — harmless, two
+/// reapers). The client is copied into the returned handle.
 Container run(DockerClient client, const ContainerRequest& request);
 
 } // namespace testcontainers

include/testcontainers/DockerComposeContainer.hpp

@@ -290,7 +290,8 @@ class DockerComposeContainer {
     /// The selected client kind (default Local).
     ComposeClientKind client_kind() const noexcept { return client_kind_; }
 
-    /// The containerised ambassador image.
+    /// The containerised client's cli image ("ambassador" is the socat relay
+    /// — see ambassador_image()).
     const std::string& compose_image() const noexcept { return compose_image_; }
 
     /// The environment variables set on the compose invocation.

include/testcontainers/ExecOptions.hpp

@@ -29,9 +29,10 @@ struct ExecOptions {
     /// interaction.
     bool detach = false;
     /// When set, attach stdin, feed these bytes, then half-close so the reader
-    /// sees EOF. Requires a half-closable transport (TCP / unix socket): on the
-    /// Windows named-pipe and TLS transports exec throws instead (no EOF signal
-    /// is possible there, so a reader like `cat` would hang forever).
+    /// sees EOF. Requires a half-closable transport — TCP, unix socket, or a
+    /// message-mode Windows named pipe (every real daemon's pipe is one): on
+    /// the TLS transport and byte-mode pipes exec throws instead (no EOF
+    /// signal is possible there, so a reader like `cat` would hang forever).
     std::optional<std::string> stdin_data;
     /// Initial console size of a `tty` exec, rows x columns. Commands that
     /// format to the terminal width see this size from their first output

include/testcontainers/Network.hpp

@@ -223,8 +223,9 @@ class Network {
     /// Best-effort remove, swallowing any error. Marks the handle dropped.
     void drop() noexcept;
 
-    // Mutable for the same reason as Container: the client is a stateless host
-    // config that opens a fresh connection per call.
+    // Mutable for the same reason as Container: requests through the client
+    // are logically const; its lazy state (the negotiated API-version pin) is
+    // instance-internal under the one-instance-one-thread rule.
     mutable DockerClient client_;
     std::string id_;
     std::string name_;

include/testcontainers/Volume.hpp

@@ -138,8 +138,9 @@ class Volume {
     /// Best-effort remove, swallowing any error. Marks the handle dropped.
     void drop() noexcept;
 
-    // Mutable for the same reason as Container/Network: the client is a stateless
-    // host config that opens a fresh connection per call.
+    // Mutable for the same reason as Container/Network: requests through the
+    // client are logically const; its lazy state (the negotiated API-version
+    // pin) is instance-internal under the one-instance-one-thread rule.
     mutable DockerClient client_;
     std::string name_;
     bool dropped_ = false;

include/testcontainers/WaitFor.hpp

@@ -43,6 +43,8 @@ struct Exit {
 struct Healthcheck {};
 
 /// Wait until an HTTP GET to the mapped host port returns `expected_status`.
+/// Plain HTTP only — probe an HTTPS-serving container in-container instead,
+/// e.g. `successful_shell_command("curl -fsk https://localhost:8443/health")`.
 struct Http {
     std::string path = "/";                       ///< request path
     ContainerPort port;                           ///< container port to probe