HANGTRACE (CLI) — Windows “Not Responding” / Hang Diagnostics
Version: 1.5.0  (update as needed)

============================================================
What is HangTrace?
------------------------------------------------------------
HangTrace is a lightweight Windows 10/11 troubleshooting CLI that helps explain
why an application becomes “Not Responding” (hung UI). It collects:

- Hung window detection + “ping” latency (WM_NULL round-trip time)
- UI thread context hints (GUI thread info)
- Wait Chain Traversal (WCT) analysis (best-effort) with enrichment
- Targeted stack samples for the UI thread and likely blockers
- Optional ETW “micro-trace mode” using WPR (WPA-friendly markers)
- Optional close-path probe (opt-in) to capture before/after state (WM_CLOSE)

Outputs:
- JSON report (machine-readable)
- HTML report (human-readable)
- Optional minidump (.dmp)
- Optional ETW trace (.etl)

============================================================
Best Practices / Safety
------------------------------------------------------------
- Run on systems you own or have explicit permission to troubleshoot.
- Prefer the fastest collection first (HTML/JSON) before deeper options.
- Minidumps and ETW traces may contain sensitive data (paths, memory fragments).
  Treat artifacts as confidential and store/share carefully.
- For protected/elevated targets, run HangTrace as Administrator to improve access.

============================================================
Quick Start
------------------------------------------------------------
1) Basic diagnosis by process name:
   HangTrace.exe --process notepad.exe --html hangtrace_report.html

2) Target a PID:
   HangTrace.exe --pid 1234 --html hangtrace_report.html --json hangtrace_report.json

3) Deeper capture + dump:
   HangTrace.exe --pid 1234 --deep --dump hangtrace_dump.dmp --html hangtrace_report.html

4) ETW micro-trace (requires WPR / Windows Performance Toolkit):
   HangTrace.exe --pid 1234 --etw hangtrace_trace.etl --html hangtrace_report.html

5) Close-path probe (opt-in) with before/after snapshot:
   HangTrace.exe --pid 1234 --probe-close --probe-delay 500 --html hangtrace_report.html

6) Self-test:
   HangTrace.exe --selftest
   HangTrace.exe --selftest --etw test.etl

============================================================
Common Options (may vary by build)
------------------------------------------------------------
--pid <n>                 Target by process id
--process <name.exe>      Target by image name (supports multiple matches)
--window-title <text>     Target by window title substring (optional if supported)
--pick first|newest|oldest    How to pick among multiple matches
--html <path>             Write HTML report
--json <path>             Write JSON report
--dump <path>             Write minidump (may require admin)
--deep                    Capture additional stacks and enrichment
--etw <path.etl>           Start/stop ETW micro-trace via WPR
--probe-close             Post WM_CLOSE to the main window (opt-in)
--probe-delay <ms>        Delay before the “after” capture (default ~300ms)
--verbose                 Print more details to console
--selftest                Verify basic capabilities (file write, WCT, etc.)

Exit Codes (recommended):
0  success
2  invalid arguments
3  target not found
4  access denied / insufficient rights
5  output write failed
6  selftest failed

============================================================
ETW Micro-Trace Notes
------------------------------------------------------------
- ETW mode is implemented via WPR so it works on most Windows 10/11 machines
  where Windows Performance Toolkit (WPT) is installed.
- The trace includes WPA-friendly markers to make the capture window obvious.
- If WPR is missing, HangTrace will report how to install/enable it.

============================================================
Build (Visual Studio 2015)
------------------------------------------------------------
- Create a new “Console Application” (x64 recommended).
- Add all .cpp/.h sources.
- Add the version resource files (HangTrace.rc, version.h, resource.h) if desired.
- Ensure Windows SDK (8.1 or newer) is installed.
- Linker inputs typically needed:
  - Dbghelp.lib
  - Advapi32.lib
  - Ole32.lib (for COM callback usage when enabled)
  - User32.lib, Kernel32.lib, Psapi.lib (as used)

============================================================
Support / Contributing
------------------------------------------------------------
This project is provided as-is. If you publish it publicly, consider adding:
- A website download page + privacy/disclaimer (already prepared in your site ZIP)
- A bug report template asking for:
  - HangTrace command used
  - Windows version/build
  - Whether run elevated
  - Report HTML/JSON (redacted if needed)
  - Optional ETL and/or DMP (only if safe to share)
