From ffbb945a804bf681ad99503c53c40f8d7d29e6c5 Mon Sep 17 00:00:00 2001
From: Nortaq-PlayNexus <311333767+Nortaq-PlayNexus@users.noreply.github.com>
Date: Fri, 4 Sep 2026 23:11:57 +1000
Subject: [PATCH] docs: add Troubleshooting section to README

---
 README.rst | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/README.rst b/README.rst
index b9d19d5..06ba7ad 100644
--- a/README.rst
+++ b/README.rst
@@ -64,3 +64,12 @@ Tests use ``unittest`` (not pytest)::
 
 Contributions to any part of fusil are welcome, but active development and CI focus on the
 Python fuzzer.
+
+Troubleshooting
+===============
+
+If `python -m unittest discover -s tests` fails with `ModuleNotFoundError: No module named 'ptrace'`, install the hard dependency::
+
+    pip install python-ptrace
+
+For `--tsan` runs, ensure you use a free-threaded CPython built with `--with-thread-sanitizer` and set `PYTHON_GIL=0` as documented in `doc/tsan-mode-plan.md`.