[dmccoystephenson]

Stage A documentation accuracy sweep. Each claim was checked against TraceClient.java, pom.xml and build.yml. Three cases of drift were found and are fixed here. All the changes are documentation; no code changed.

Summary

• Builder.serverWideConfig Javadoc: it said build() "makes sure plugins/trace/config.yml exists". The constructor never reads or creates the file once TRACE_USAGE_REPORTING / DO_NOT_TRACK has opted out (builder.pluginsDirectory == null || environmentDisables() ? ServerWideConfig.NONE : ...). This is already pinned by installId_aDisabledClientNeitherGeneratesNorWritesOne ("an environment opt-out touches nothing on disk"). The Javadoc now says so. "Both are read once" also became "All three", because the paragraph lists the switch, the tags: block and server-id:.
• readServerWideConfig Javadoc: it named the enabled: line and the tags: block but not the server-id: line, which parseServerWideConfig also reads. It also did not say that the method is skipped under an environment opt-out.
• README "What report promises", "Never throws" row: "Drops are logged at FINE" contradicted the "Bounded" row next to it, which says queue-full drops get no log line. It now reads "Such a failure is logged", which matches the class Javadoc ("Failures are logged at FINE").

The same inaccuracy appears in the README "Opting out" table (server-wide row). It is not fixed here, because that section is user-facing disclosure wording that needs maintainer approval. It is filed as #34.

No tracking issue for the fixes in this PR: the drift was found during the sweep.

Checked and found accurate

The version agrees in all four places (0.7.0). The REASON_* / ENV_* strings and the precedence match the class Javadoc and README. QUEUE_CAPACITY, MAX_COALESCED_EVENTS, COALESCE_WINDOW_MS and the 5 s close() bound match. So do the wire format (endpoint, Authorization: Bearer, 201, value omission), the server-id: / install-ID rules and the Building section against the build.yml matrix (8, 17, 21).

Deferred issues

• withVersion pushes an event already at MAX_TAGS over the server's tag limit #13, A quoted enabled: "false" in the server-wide config does not turn reporting off #15, A comment-only enabled: line in the server-wide config shadows a later enabled: false #27, A coalesced count at MAX_TAGS, or on an event with its own coalesced tag, is sent without its count tag #31: each one changes the wire format or the opt-out contract and is waiting on a maintainer decision, so none was picked up.
• README Opting out table says build() creates the server-wide file even when the environment has opted out #34: filed by this sweep. It touches the "Opting out" README section, which is do-not-auto-merge.

Test plan

• mvn -B verify run locally on Java 21: 97 tests, 0 failures.
• CI matrix (Java 8, 17, 21) green on the PR head.

This PR description was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

🤖 Generated with Claude Code

---

drafted by Claude on behalf of Daniel Stephenson

[dmccoystephenson]

Self-review rubric (scored against the diff and CI on head f7b4307):

• Scope: PASS. Two files, three comment/prose hunks, and each one fixes a piece of drift named in the PR body. No code or formatting churn.
• Tests-new: PASS (n/a). No public member was added.
• Tests-fix: PASS (n/a). This is a documentation-only change, so no bug fix needs a regression test. The documented behaviour is already pinned by installId_aDisabledClientNeitherGeneratesNorWritesOne.
• Sibling structure: PASS. No new files.
• Sibling renames: PASS. Nothing was renamed.
• Docs: PASS with one known exception. The README "Opting out" server-wide row has the same inaccuracy, but that section is do-not-auto-merge disclosure wording, so it is tracked in README Opting out table says build() creates the server-wide file even when the environment has opted out #34 rather than changed here.
• Issue resolution: PASS (n/a). No Closes. The PR body states that the drift was found during the sweep.
• CI: PASS. build (8), build (17) and build (21) are all green on the PR head.
• No dependencies: PASS. pom.xml is untouched, and TraceClient.java has only java.* imports.
• Single file: PASS. git ls-files src/main lists only TraceClient.java.
• Java 8: PASS. The Java 8 leg is green, and maven.compiler.release is unchanged.
• Never throws / non-blocking / environment seam: PASS. Only Javadoc changed in TraceClient.java.
• Version agreement: PASS (n/a). No version string changed.
• Opt-out contract: PASS. No REASON_*/ENV_*, precedence, SERVER_WIDE_CONFIG_CONTENT or README "Opting out" text was touched.

Do-not-auto-merge path check: none matched. The changed paths are README.md (the "What report promises" table only) and TraceClient.java (Javadoc only, no contract surface).

Observation, not blocking: src/main/java/software/stephenson/trace/TraceClient.java:1127, where "read once, here" means in build(), which the paragraph names just above. That wording is inherited from the original sentence.

Summary: an accurate, docs-only correction, and ready to merge.

This comment was drafted during a Gardener session (https://github.com/Stephenson-Software/gardener).

---

drafted by Claude on behalf of Daniel Stephenson