Skip to content

docs: sharpen README positioning and structure - #43

Merged
0x0bug merged 5 commits into
mainfrom
docs/readme-positioning
Aug 6, 2026
Merged

docs: sharpen README positioning and structure#43
0x0bug merged 5 commits into
mainfrom
docs/readme-positioning

Conversation

@0x0bug

@0x0bug 0x0bug commented Aug 4, 2026

Copy link
Copy Markdown
Owner

What changed

  • rewrote the README opening around the user problem, intended audience, and first-pass diagnostics use case;
  • added a concise Why WDT table, clearer quick start, screenshots, report lifecycle, requirements, limitations, and support paths;
  • corrected the documented output defaults: interactive TUI uses .\WindowsDiagnosticsReports, while command-line mode uses the current working directory;
  • tightened safety language so report-file and bootstrap temporary-directory writes are explicit;
  • documented the Network module's external DNS/TCP/ICMP probes and -NoExternalNetworkTests opt-out;
  • pinned release wording to v0.1.0-beta rather than using a temporal “latest” label;
  • removed duplicated low-level module material already covered by docs/usage.md;
  • added workflow and release badges;
  • extended tests/readme.tests.ps1 with dependency-free quality checks.

Quality contract

The README test now checks:

  • required launch, release, trust-boundary, compatibility, and troubleshooting copy;
  • correct interactive and command-line output semantics;
  • one H1, ordered heading levels, and no duplicate headings;
  • closed fenced code blocks with language identifiers;
  • meaningful image alt text and non-generic link text;
  • existence of every relative link target;
  • no tabs or trailing whitespace, a final newline, and size below GitHub's 500 KiB rendering limit.

Why

The previous README was technically thorough but presented low-level behavior before the product value was clear. The audit also found one factual mismatch in the default output directory and several claims that needed narrower wording around process isolation, filesystem writes, and external network probes.

Impact

Documentation and documentation tests only. No production scripts, bootstrap content, module behavior, report format, or release assets changed.

Validation

Latest head: 08e15b24c10df839a845e4c60dc37cf19fb33615.

The complete PowerShell Validation workflow passed:

  • repository validation on PowerShell 7 and Windows PowerShell 5.1;
  • README quality tests on both engines;
  • AST safety, Privacy Mode, TUI, network, registry, compatibility, parser, classification, process-runner, startup, bootstrap-sync, and release tests;
  • live report tests on both engines;
  • final System report smoke test.

Additional audit checks:

  • GitHub Community Profile reports 100% repository health;
  • the v0.1.0-beta prerelease and both release assets exist;
  • README relative files, issue forms, external screenshot source files, and the published bootstrap source copy exist;
  • the site bootstrap blob matches the canonical bootstrap blob.

Not verified from this environment

Live DNS/HTTP reachability of wdt.digital could not be tested because the current execution environment has no external DNS resolution. Repository/API-backed existence and bootstrap synchronization were verified instead.

@0x0bug
0x0bug marked this pull request as ready for review August 6, 2026 01:56
@0x0bug
0x0bug merged commit 7363d11 into main Aug 6, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant