[dmccoystephenson]

Summary

Stage A documentation accuracy sweep. No production behaviour changes: the TraceClient.cs diff is XML doc comments only. Every open issue is a human-gated contract decision, so the sweep was taken up instead.

Each item below was checked against the code and the tests that pin it.

• EnvironmentDisables. The doc said "only the listed values count" but listed off and 1 alone, while false, 0, no, true and yes count as well. It now points at the two constants that list them, and also says that an environment that cannot be read leaves the program's setting in charge (EnvironmentDisables_IsFalseWhenTheEnvironmentCannotBeRead).
• A closed client. DisabledReason was described as why Report sends nothing, which does not hold after Close: nothing is sent and the reason stays null. The DisabledReason doc and a new README paragraph now cover this, and name IsEnabled as the way to ask. The gap was noted in the PR Test the request timeout, undeliverable base URLs and a non-ASCII application #30 self-review.
• Reports on a disabled or closed client. The Report doc named a blank name as the silent case and left these two out.
• A blank installId. It does not win over installIdFile, although the docs said installId wins and the README sample said "null or blank: none sent". The behaviour is pinned by BlankExplicitId_DoesNotWinOverTheFile, and both places now say so.
• The log parameter. It also receives installation ID file failures.
• baseUrl. Only a URL that does not parse is rejected. ftp://host and localhost:8080 make a client whose every report is a logged drop, as tested since PR Test the request timeout, undeliverable base URLs and a non-ASCII application #30.
• The README Bounded row. "A few kilobytes" understated the cost. A body like the README's sample is about 130 characters, or about 260 bytes in memory, so 256 of them are tens of kilobytes. This figure is an estimate from the sample, not a measurement.

One assertion is added to a test: Close_IsIdempotentAndReportAfterCloseIsANoOp now also checks that nothing is logged, which pins the new "logs nothing" wording. This goes slightly beyond a docs-only change and is stated here for that reason.

No tracking issue: the gaps were found during triage.

Test plan

• Build workflow green on ubuntu-latest (net8.0)
• Build workflow green on windows-latest (net8.0 + net48), which also proves the new crefs resolve under TreatWarningsAsErrors
• Test totals match main at 109 per target, with 0 skipped (run 42335610852 on head 8b8384a)

The local anchor is UNVERIFIED: dotnet is not available in the dispatch sandbox, so the CI matrix on the head SHA is the gate.

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.
• Repeated events are not coalesced, unlike trace-client-java 0.7.0 #28 (coalescing repeated events) was not picked for the same reason. The README sentence saying the clients "make the same promises" was left as it is, since its rewording depends on that decision.
• A repeated tag key is sent twice and counted twice #31 (a repeated tag key) was not picked. Any change alters what goes on the wire.

The README "Turning it off" and "Keys" sections were not touched.

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. gh pr diff 32 touches README.md, XML doc comments in TraceClient.cs, and one test. The test assertion goes slightly past a docs change; it pins the new "logs nothing" wording and is disclosed in the PR body.
• Tests-new: PASS. No public member was added.
• Tests-fix: not applicable. This is not a bug fix, and no production behaviour changed.
• Sibling structure: PASS. No file was added.
• Sibling renames: PASS. Nothing was renamed.
• Docs: PASS. Each changed statement was checked against the code path and, where one exists, the test that pins it. The Phase 7 table was read through on this head and nothing further was found to be wrong, apart from the items listed below.
• Issue resolution: not applicable. There is no Closes reference.
• CI: PASS. Run 42335610852 is green on head 8b8384a: 109 passed and 0 skipped on ubuntu net8.0, windows net8.0 and windows net48, the same total as main. The build also resolved the new crefs under TreatWarningsAsErrors.
• No dependencies: PASS. Neither csproj is touched.
• Single file: PASS. git ls-files src/TraceClient lists TraceClient.cs and TraceClient.csproj only.
• Vendoring floor: PASS. The csproj is untouched and the net48 leg is green.
• Never throws: PASS. No executable line in TraceClient.cs changed; every changed line is a /// comment.
• Non-blocking and bounded: PASS, for the same reason.
• Environment seam: PASS. System.Environment appears only in the EnvironmentSource initializer and the comment above it.
• Version agreement: not applicable. No version changed.
• Opt-out contract: PASS. No constant, accepted value or precedence changed. The EnvironmentDisables doc now defers to the constants' own lists, which match IsOff and IsYes.

One finding was fixed before this comment: "in any case" in the EnvironmentDisables doc could be read as "anyway", so it was changed to "case-insensitive" in 8b8384a.

Findings noted, not changed:

• Close_IsIdempotentAndReportAfterCloseIsANoOp: the new Assert.Empty(logged) was not checked by mutating the code, because no SDK is available locally. The claim comes from reading Report, whose first branch returns when IsEnabled is false.
• The new "logs nothing" wording covers a report made after Close has been called. A report racing Close can still reach the could not queue log line, which is the existing behaviour.
• README.md "Bounded" row: "typically tens of kilobytes" is an estimate from the README's sample body, not a measurement. A report at the size limits costs far more.
• README.md:13: "make the same promises" no longer holds for coalescing. The rewording depends on Repeated events are not coalesced, unlike trace-client-java 0.7.0 #28, so it was left as it is.
• The Unity (Mono/IL2CPP) runtime is not covered by CI, but nothing executable changed here.

Do-not-auto-merge check: .github/workflows/* and both csproj files are untouched. No wire-format, opt-out, limit or signature code changed, and no version changed. The README hunks fall in the installation ID and "What Report promises" sections, not in "Turning it off" or "Keys". No file has more than 50 lines deleted.

Local anchor: UNVERIFIED (dotnet is not available 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