diff --git a/examples/quickstart.py b/examples/quickstart.py
new file mode 100644
index 0000000..149a644
--- /dev/null
+++ b/examples/quickstart.py
@@ -0,0 +1,30 @@
+"""Minimal example: generate one trajectory + click event.
+
+Run:    uv run python examples/quickstart.py
+"""
+from __future__ import annotations
+
+from ai_mouse import generate
+
+start = (100, 200)
+end = (900, 400)
+points = generate(start, end, seed=0)
+
+print(f"Generated {len(points)} events:")
+print(f"  first move:  {points[0]}")
+print(f"  middle move: {points[len(points) // 2]}")
+print(f"  last move:   {points[-3]}")
+print(f"  click-down:  {points[-2]}")
+print(f"  click-up:    {points[-1]}")
+
+# Typical replay loop pattern. t_ms is cumulative from the start of the trace,
+# so block your sender thread until time-since-start reaches each event's t_ms.
+#
+# import time
+# t0 = time.monotonic()
+# for x, y, t_ms in points:
+#     target_wallclock = t0 + t_ms / 1000.0
+#     while time.monotonic() < target_wallclock:
+#         pass
+#     # replace this with pyautogui / pynput / win32 mouse_event:
+#     # send_mouse_move(x, y)