docs: clarify how to generate and replay trace files

README.md

@@ -70,6 +70,38 @@ vardbg replay qsort.json -v sort_vis.mp4
 
 It is possible to generate videos live while running the debugged program, but this is discouraged because the overhead of video creation inflates execution times greatly and thus ruins profiler results. However, if profiling is not important to you, it is a valid use case.
 
+### Step-by-Step Example (Common Pitfalls Explained)
+
+This section provides a minimal working example and explains common errors reported by new users.
+
+#### 1. Example Python file
+
+Ensure the function you want to debug exists and matches the name provided in the command.
+
+Example: `qsort.py`
+
+```python
+def quick_sort(arr):
+    if len(arr) <= 1:
+        return arr
+    pivot = arr[0]
+    left = [x for x in arr[1:] if x <= pivot]
+    right = [x for x in arr[1:] if x > pivot]
+    return quick_sort(left) + [pivot] + quick_sort(right)
+
+
+### Generating and Replaying a Trace
+
+The `replay` command requires a JSON trace file.  
+This file must be generated first using `vardbg run`.
+
+```bash
+vardbg run qsort.py quick_sort -o qsort.json -a 9 -a 3 -a 5 -a 1
+
+To generate a visualization video from the trace:
+vardbg replay qsort.json -v qsort.mp4
+
+
 ## Configuration
 
 The video generator has many options: resolution, speed, fonts, and sizes. These options can be modified using a [TOML](https://learnxinyminutes.com/docs/toml/) config file. The [default config](https://github.com/CCExtractor/vardbg/blob/master/vardbg/output/video_writer/default_config.toml) documents the available options, which can be customized in an minimal overlay config without having to duplicate the entire config. The config can then be used by passing the `-c` argument on the command line.