document output format and read/write detection

README.md

@@ -40,6 +40,28 @@ gwatch --var <symbol> --exec <path> [-- arg1 arg2 ... argN]
 ./build/gwatch --var global_counter --exec ./test_with_args -- hello world 123
 ```
 
+## Output Format
+
+When watchpoints trigger, gwatch outputs access events in the following format:
+
+**For writes:**
+```
+<symbol>\twrite\t<old_value>-><new_value>
+```
+
+**For reads:**
+```
+<symbol>\tread\t<value>
+```
+
+Example output:
+```
+global_counter	read	0
+global_counter	write	0->42
+global_counter	read	42
+global_counter	write	42->52
+```
+
 ## Implementation Details
 
 ### Variable Detection
@@ -60,6 +82,13 @@ For Position Independent Executables, the tool:
 2. Adds the load address to the DWARF-provided offset
 3. Sets the watchpoint at the runtime address
 
+### Read vs Write Detection
+When a watchpoint triggers:
+1. The current value is read from the traced process memory using `ptrace(PTRACE_PEEKDATA)`
+2. If the value has changed since the last access, it's reported as a write
+3. If the value is unchanged, it's reported as a read
+4. Values are formatted according to the variable size (1, 2, 4, or 8 bytes)
+
 ## Current Limitations
 
 **Hardware watchpoints are not currently triggering on the test system.** The implementation follows standard Linux ptrace documentation for setting x86 hardware breakpoints, but watchpoint events are not being generated. This may be due to: