Improve XML documentation coverage across src modules and sync generated analysis artifacts.

dottrace.md

@@ -196,6 +196,83 @@ Open `.dtp` / `.dtt` snapshot files in:
 open /Users/dohertj2/Applications/dotTrace.app --args ./snapshots/nats-sampling.dtp
 ```
 
+## Parsing Raw `.dtp` Snapshots To JSON
+
+The repository includes a Python-first parser for raw dotTrace sampling and tracing snapshots:
+
+- Python entrypoint: [tools/dtp_parse.py](/Users/dohertj2/Desktop/natsdotnet/tools/dtp_parse.py)
+- .NET helper: [tools/DtpSnapshotExtractor/Program.cs](/Users/dohertj2/Desktop/natsdotnet/tools/DtpSnapshotExtractor/Program.cs)
+
+The parser starts from the raw `.dtp` snapshot family and emits machine-readable JSON for call-tree and hotspot analysis. It uses the locally installed dotTrace assemblies to decode the snapshot format.
+
+### Prerequisites
+
+- `python3`
+- `.NET 10 SDK`
+- dotTrace installed at `/Users/dohertj2/Applications/dotTrace.app`
+
+If dotTrace is installed elsewhere, set `DOTTRACE_APP_DIR` to the `Contents/DotFiles` directory:
+
+```bash
+export DOTTRACE_APP_DIR="/path/to/dotTrace.app/Contents/DotFiles"
+```
+
+### Print JSON to stdout
+
+```bash
+python3 tools/dtp_parse.py snapshots/js-ordered-consume.dtp --stdout
+```
+
+### Write JSON to a file
+
+```bash
+python3 tools/dtp_parse.py snapshots/js-ordered-consume.dtp \
+  --out /tmp/js-ordered-consume-calltree.json
+```
+
+### Output shape
+
+The generated JSON contains:
+
+- `snapshot` — source path, payload type, thread count, node count
+- `threadRoots` — top-level thread roots with inclusive time
+- `callTree` — nested call tree rooted at a synthetic `<root>`
+- `hotspots` — flat `inclusive` and `exclusive` method lists
+
+Hotspot entries are method-first. Synthetic frames such as thread roots are excluded from the hotspot lists so the output is easier to feed into an LLM for slowdown analysis.
+
+### Typical analysis workflow
+
+1. Capture a snapshot with `dottrace`.
+2. Convert the raw `.dtp` snapshot to JSON:
+
+```bash
+python3 tools/dtp_parse.py snapshots/nats-sampling.dtp \
+  --out /tmp/nats-sampling-calltree.json
+```
+
+3. Inspect the top hotspots:
+
+```bash
+python3 - <<'PY'
+import json
+with open('/tmp/nats-sampling-calltree.json') as f:
+    data = json.load(f)
+print('Top inclusive:', data['hotspots']['inclusive'][0]['name'])
+print('Top exclusive:', data['hotspots']['exclusive'][0]['name'])
+PY
+```
+
+4. Feed the JSON into downstream tooling or an LLM to walk the call tree and identify expensive paths.
+
+### Verification
+
+Run the parser test with:
+
+```bash
+python3 -m unittest tools.tests.test_dtp_parser -v
+```
+
 ## Exit Codes
 
 | Code | Meaning |
@@ -212,3 +289,4 @@ open /Users/dohertj2/Applications/dotTrace.app --args ./snapshots/nats-sampling.
   ```bash
   mkdir -p snapshots
   ```
+- The parser currently targets raw `.dtp` snapshots. Timeline `.dtt` snapshots are still intended for the GUI viewer.