Review the documentation before the 2.3.00 release

[bertysentry]

A pre-release review of the whole site (src/site/markdown/*.md, site.xml) and README, to make the 2.3.00 docs accurate, complete, consistent and no longer than needed. The pages come out slightly shorter overall (+526 / −530).

How it was reviewed

Twelve reviewers each covered either a group of pages, checked against the source, or a cross-cutting angle: API coverage, links and structure, a newcomer reading in menu order, and compiling every code example. That produced 361 findings. A skeptical verifier per file then re-checked each finding in the code: 179 were confirmed, 30 refuted and 152 duplicates. 176 are applied here, and every edit was re-checked per file and read in full.

What changed

Wrong statements corrected

• WQL row values are always strings, and a WMI NULL comes back as an empty string (get() is not a typed value).
• WinRMFaultException.getFaultCode() returns a String that can be null.
• Only an HTTP 401 becomes WinRMAuthenticationException. A client-side Kerberos failure (KDC, SPN, clock skew) is a plain WinRMClientException (authentication, timeouts-and-errors, preparing-the-host).
• legacy.md said the output code page is detected before each call. That has not been true since 2.0.00.
• tls.md said --https-permissive sets the insecure system property. It calls trustAllCertificates().
• The PowerShell section assumed Windows PowerShell 5.x, but Windows Server 2008 R2 / Windows 7 run 2.0.
• The waitFor(Duration) comment suggested code that does not compile (it returns a boolean).
• On an empty result, WQL columns are lower case, and SELECT * columns are alphabetical.
• cli.md recommended pairing Basic with --https-permissive, which hands the password to any impostor host.

Missing coverage added

• index.md gets a Client options table: every builder option with its default. wql.md and commands.md already pointed readers to "the Overview for the builder options", which listed none. It also says a client may be shared between threads, with operations serialized.
• authentication.md: with Kerberos, the DOMAIN\ part of the user name is ignored (use user@REALM). With ticketCache(...), credentials(...) is still required and must name the cached principal.
• migrating-from-1x.md gets the breaking changes it left out: Kerberos over HTTP is rejected even as a fallback, output is UTF-8, legacy result collections are unmodifiable, and the transfer directory and share were renamed.
• A few short notes where users get stuck:
  • calling the same client while consuming a stream waits forever;
  • a UNC upload destination is a second hop;
  • JDKs refuse TLS 1.0/1.1;
  • Git Bash rewrites /switch arguments;
  • the CLI's wql always queries ROOT\CIMV2.

Structure and consistency

• File Transfers covers uploads and how downloads work. Remote Files no longer repeats the download section.
• CLI option tables on topic pages (authentication.md, tls.md) become pointers to cli.md, which stays the single source of truth.
• Duplicated exception tables and implementation-rationale passages are trimmed, e.g. the PowerShell script-size bullet, the BOM paragraph, read performance, and the non-admin WMI steps.
• Version notation is now 2.0.00 everywhere. The old Doxia-1 anchors (#Privileges and the like) are now lowercase-hyphen. "Platform trust store" becomes the JDK's cacerts.

CLI help and Javadoc

• --help printed DOMAIN\\user with two backslashes. Copied as-is, that user name fails to authenticate.
• "Connection options" also listed non-connection options; the header now reads "Options (before the subcommand)".
• The -i line implied stdin is only forwarded with -i. Forwarding is automatic when stdin is redirected; -i forces it.
• Stale Javadoc fixed:
  • CommandRequest.stdinCharset;
  • the WinRMCommandExecutor example, which named a class that does not exist and passed the wrong arguments;
  • WqlResult.columns();
  • WindowsRemoteCommandResult: execution time is in seconds, and the missing @return descriptions are added.

README
Only wrong or stale content is corrected: the feature list, the release instructions (Central Portal with auto-release, not OSSRH/Nexus staging), and two outdated option paragraphs, now replaced by a link to the site.

For the reviewer

• site.xml is unchanged: the menu was reviewed and found fine.
• The review also found three code bugs. They are deliberately left out of this docs PR:
  1. The streaming terminals (stream(), start(), openStream()) can leak a raw IllegalStateException for protocol failures (LightWinRMService.callStreaming). The docs keep promising WinRMClientException, so the code should be fixed.
  2. WQL array properties keep only their last element (WsmanClient.collectRows). wql.md does not mention arrays until this is fixed.
  3. A multi-line WHERE clause is rejected locally (WmiHelper pattern without DOTALL).
• mvn clean verify site passes: 322 tests, no checkstyle/PMD/SpotBugs findings. A script over the generated site found no broken internal link or anchor.

🤖 Generated with Claude Code

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-09-29T17:56:49.632810Z	9ce8e6d	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 0ad7cb2cb7

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[bertysentry]

@codex please review again

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1c3cbb32b4

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[bertysentry]

@codex please review again

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. 🎉

Reviewed commit: 9ce8e6d8e1

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".