step 7: harden docs and prepare beta

README.md

@@ -2,11 +2,82 @@
 
 Dear PyGui gauge widgets for dashboards and telemetry displays.
 
-Current implementation status: Step 6 high-rate update support is implemented. Analog, digital, bar,
-level, status, segmented, compass, thermometer, battery, and multi-value gauges render Dear PyGui
-drawlist visuals. Bar/level gauges draw threshold bands and markers; analog gauges draw ticks,
-redline bands, markers, and needles.
+## Install
 
-Runtime value updates are intended for the Dear PyGui GUI thread. Attached gauges redraw immediately
-for simple value/configuration changes. Animation and smoothing are configurable per gauge; high-rate
-examples marshal latest producer-thread values to GUI-thread frame callbacks.
+```bash
+uv add dpg-gauges
+```
+
+For local development from another project:
+
+```bash
+uv add --editable ../dpg-gauges
+```
+
+## Minimal Example
+
+```python
+import dearpygui.dearpygui as dpg
+import dpg_gauges as dpgg
+
+dpg.create_context()
+with dpg.window(label="Dashboard"):
+    dpgg.analog_gauge(tag="rpm", label="RPM", value=3200, max_value=8000, width=220, height=220)
+    dpgg.digital_gauge(tag="speed", label="Speed", value=88, unit="km/h", width=220, height=90)
+
+dpg.create_viewport(title="gauges", width=520, height=340)
+dpg.setup_dearpygui()
+dpg.show_viewport()
+dpg.start_dearpygui()
+dpg.destroy_context()
+```
+
+## Dashboard Example
+
+```python
+with dpg.window(label="Engine"):
+    with dpgg.gauge_panel(label="Powertrain", width=-1, height=260):
+        with dpgg.gauge_grid(columns=3):
+            dpgg.analog_gauge(tag="rpm", label="RPM", max_value=8000, redline_start=6500)
+            dpgg.bar_gauge(tag="boost", label="Boost", max_value=30, unit="psi")
+            dpgg.status_light(tag="ecu", label="ECU", state=True)
+```
+
+## GUI-Thread Contract
+
+Dear PyGui item operations must happen on the GUI thread. Gauge creation and runtime updates such as
+`set_value`, `update_gauge`, `set_thresholds`, and `delete_gauge` are GUI-thread functions. Worker
+threads may produce data, but applications should marshal the latest values to a Dear PyGui frame
+callback before calling dpg-gauges APIs.
+
+## Animation And Smoothing
+
+Animation changes the displayed value over a short duration without changing the raw target value.
+Smoothing improves readability during high-rate updates.
+
+```python
+dpgg.digital_gauge(
+    tag="speed",
+    animation=dpgg.AnimationConfig(enabled=True, duration=0.15),
+    smoothing=dpgg.SmoothingConfig(enabled=True, alpha=0.25, max_step=5),
+)
+```
+
+Disable animation with `animation=False` for immediate response.
+
+## Thresholds And Markers
+
+Thresholds and markers are visual only; they do not trigger callbacks or alarms.
+
+```python
+dpgg.bar_gauge(
+    tag="coolant",
+    min_value=40,
+    max_value=120,
+    thresholds=[dpgg.ThresholdBand(100, 120, (255, 45, 45, 150))],
+    markers=[dpgg.GaugeMarker(110, (255, 255, 255, 255), thickness=3)],
+)
+```
+
+Implemented gauge types: analog, digital, bar, level, status light, segmented, compass,
+thermometer, battery, and multi-value.