[dmccoystephenson]

Summary

Stage A documentation accuracy sweep. Only docs change: the edits are to README.md and to XML doc comments in TraceClient.cs, and no executable line is touched. Everything added describes what the code already does.

• NaN and infinite values. The wire format section said value is omitted "when not given". Json also omits a NaN or infinite value and still sends the event. The README and the Report XML doc now say so.
• Null or blank names. Report returns before anything else for these, with no log line. The README says "Drops go to the optional log callback", so this case is now stated in the README and the Report XML doc.
• The log callback. Its thread was undocumented, which matters for Unity, where a callback can arrive off the main thread. The README and the constructor's log parameter doc now cover which thread each message arrives on, the need for a quick and thread-safe callback, and that a failed delivery's message includes the JSON body. A note says the client does not write the key into any message.

The first two match trace-client-python's Stephenson-Software/trace-client-python#24.

No tracking issue: the gaps were found during triage.

Test plan

• Build workflow green on ubuntu-latest (net8.0): 102 tests, run 41959743507
• Build workflow green on windows-latest (net8.0 + net48): 102 tests on each; doc comments are compiled, and warnings are errors

The local anchor is UNVERIFIED: no .NET SDK is installed in the dispatch sandbox, so the CI matrix on the head SHA is the gate. No new tests were needed. The behaviour described is covered by Json_EscapesControlCharactersAndSkipsNullOrBlankTags, Json_OmitsAnInfiniteValueLikeNaN and Report_IgnoresABlankName, although the last of these does not assert that nothing is logged.

Deferred

• Non-ASCII application name drops every report on .NET 5+ (User-Agent header) #12 (non-ASCII application name in User-Agent) was not picked. It changes the wire-format contract shared with the Java and Python clients, so a maintainer has to decide it. The new coalescing parity issue, Repeated events are not coalesced, unlike trace-client-java 0.7.0 #28, is deferred for the same reason.

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 (plain comment; not an independent review):

• Scope: PASS. Only README.md and TraceClient.cs changed, and every hunk serves the sweep. git diff shows no change to an executable line.
• Tests-new: PASS. No public member was added.
• Tests-fix: not applicable. This is not a bug fix, and no behaviour changed.
• Sibling structure: PASS. No file was added.
• Sibling renames: PASS. Nothing was renamed.
• Docs: PASS. Each new claim was read against the source. Json omits NaN and infinite values, and Report returns on a null or blank name before any Log call. Note runs on the caller's thread from Report and the constructor, and on the background thread from Send and Drain. _key is read only for the emptiness check and the Authorization header.
• Issue resolution: not applicable. There is no Closes reference; the gaps were found during triage.
• CI: PASS. Run 41959743507 is green on head 39f3653: 102 tests on ubuntu net8.0, windows net8.0 and windows net48, the same total as the last merged PR. The XML doc changes compiled with warnings as errors.
• No dependencies: PASS. The csproj is untouched and no using was added.
• Single file: PASS. No source file was added.
• Vendoring floor: PASS. The csproj is untouched and the net48 leg is green.
• Never throws: PASS. No executable code changed.
• Non-blocking and bounded: PASS. No executable code changed.
• Environment seam: PASS. No executable code changed.
• Version agreement: not applicable. No version changed.
• Opt-out contract: not applicable. Neither "Turning it off" nor "Keys" was touched.

Findings noted, not changed:

• README.md:124: the thread list leaves out could not close cleanly, which is logged on the caller's thread. That path needs CompleteAdding or Join to fail, so the sentence was kept short. The rule it states, that the callback runs on whichever thread hit the problem, still covers it.
• README.md:179: "nothing is logged" for a blank name follows from the early return in Report, but Report_IgnoresABlankName does not assert it. A one-line assertion would suit a later Stage B cycle.
• The note about the key covers messages the client composes. A failure.Message comes from the runtime, so the wording was limited to what the client writes.

Do-not-auto-merge check: neither path is listed, and the TraceClient.cs change is limited to comments, so no contract is changed.

Local anchor: UNVERIFIED (no .NET SDK in the dispatch sandbox), so CI on the exact head SHA was used as the gate.

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

---

drafted by Claude on behalf of Daniel Stephenson