refractored documentation

Author: Creamy-pie-96

README.md

@@ -0,0 +1,30 @@
+[⬅ Back to main readme file](../README.md)
+
+# Common Pitfalls
+
+- **C++20 required** - Won't compile with older standards
+- **No automatic conversions from strings** - Use `Int()`, `Float()`, etc. when converting from strings
+- **Dictionary keys** - Currently only support string keys
+- **Index checking** - Out of bounds returns None instead of throwing
+- **Comparison** - Different types compare as not equal (no implicit conversion)
+- **Operator ambiguity with slicing** - When using `slice()` with `None`, wrap numeric literals in `var()`: `slice(None, None, var(-1))`
+- **Index ambiguity** - Use `size_t` for list indices when 0 might be ambiguous: `lst[size_t(0)]`
+- **DynamicVar arithmetic** - Convert `let()` variables to `var` first for arithmetic: `var v = let(x); let(x) = v + 50;`
+- **Type Conversions** - The `var` type provides explicit conversion operators, so `static_cast<int>()`, `static_cast<double>()` work correctly. However, for clarity and best practice, prefer using the explicit conversion methods `.toInt()`, `.toDouble()`, `.toString()`:
+
+  ```cpp
+  var x = 42;
+  int i1 = static_cast<int>(x);    // Works ✓ (returns 42)
+  int i2 = x.toInt();              // Recommended ✓ (clearer intent)
+
+  // For list/path access, both work:
+  var path = list(0, 2, 4, 3);
+  size_t idx1 = static_cast<size_t>(static_cast<int>(path[1]));  // Works ✓
+  size_t idx2 = static_cast<size_t>(path[1].toInt());            // Clearer ✓
+  ```
+
+# Safety Features
+
+- **Overflow Detection** - Integer arithmetic operations (+, -, \*, /) are checked for overflow and throw `PythonicOverflowError`
+- **Zero Division** - Division/Modulo by zero throws `PythonicZeroDivisionError`
+- **Safe Iteration** - `as_span()` provides safe views of list data

docs/Pitfall_safety/pitfall_safety.md

@@ -6,6 +6,64 @@ This page documents all user-facing graph APIs for `var` when holding a graph, i
 
 ---
 
+---
+
+## Interactive Graph Viewer (GUI)
+
+Pythonic provides a powerful interactive viewer for your graphs, powered by OpenGL/ImGui. This lets you visualize, edit, and explore graphs in real time.
+
+### Enabling the Viewer
+
+To use the interactive viewer, build with the following CMake option:
+
+```bash
+cmake -DPYTHONIC_ENABLE_GRAPH_VIEWER=ON ..
+```
+
+### Usage
+
+Once enabled, simply call:
+
+```cpp
+g.show();
+```
+
+or
+
+```cpp
+g.show(false); // disables auto-layout, preserves current node positions
+```
+
+### Features
+
+- **View Mode**:
+  - Drag nodes (physics snaps them back to preserve topology)
+  - Hover over nodes/edges to see metadata/weights
+  - **Click nodes** to trigger animated signal waves
+- **Edit Mode** (toggle with 🔒 icon):
+  - **Double-click** empty space to add nodes
+  - **Drag** from node to node to add edges
+  - **Select + Delete** to remove nodes/edges
+  - All changes are saved back to your `var` graph
+
+### Controls & Tips
+
+| Action                    | Effect                              |
+| ------------------------- | ----------------------------------- |
+| Drag node                 | Move node (snaps back in View mode) |
+| Hover node/edge           | Show metadata/weight                |
+| Click node                | Trigger animated signal wave        |
+| Double-click empty space  | Add new node (Edit mode)            |
+| Drag from node to node    | Add edge (Edit mode)                |
+| Select node/edge + Delete | Remove element (Edit mode)          |
+| 🔒 icon (top bar)         | Toggle between View/Edit mode       |
+| Mouse wheel               | Zoom in/out                         |
+| Right-click background    | Pan view                            |
+
+**Note:** The viewer is only available if built with the appropriate CMake flag. If `g.show()` does nothing, check your build configuration.
+
+---
+
 ## Graph Properties & Queries
 
 | Method                                                          | Description                  | Example                   |