step 7: harden docs and prepare beta

docs/API_REFERENCE.md

@@ -0,0 +1,41 @@
+# API Reference
+
+## Configuration
+
+- `configure(**config)`: set package-wide defaults for later gauges.
+
+## Gauge Creation
+
+Creation functions are context managers and accept common options such as `tag`, `label`, `value`,
+`min_value`, `max_value`, `unit`, `width`, `height`, `show`, `tooltip`, `callback`, `theme`,
+`style`, `animation`, `smoothing`, `thresholds`, and `markers`.
+
+- `analog_gauge(**config)`
+- `digital_gauge(**config)`
+- `bar_gauge(**config)`
+- `level_gauge(**config)`
+- `status_light(**config)`
+- `segmented_gauge(**config)`
+- `compass_gauge(**config)`
+- `thermometer_gauge(**config)`
+- `battery_gauge(**config)`
+- `multi_value_gauge(**config)`
+
+## Layout Helpers
+
+- `gauge_panel(**config)`: child-window panel for grouped gauges.
+- `gauge_grid(**config)`: lightweight horizontal gauge group.
+
+## Runtime API
+
+- `set_value(tag, value)`: set the latest target value.
+- `get_value(tag)`: return the latest raw target value.
+- `update_gauge(tag, **config)`: update value and/or configuration.
+- `configure_gauge(tag, **config)`: update configuration.
+- `set_thresholds(tag, thresholds)`: replace visual threshold bands.
+- `set_markers(tag, markers)`: replace visual markers.
+- `set_show(tag, show)`: show or hide a gauge.
+- `delete_gauge(tag)`: remove a gauge.
+- `get_gauge_debug_state(tag)`: return internal debug state.
+
+Runtime functions are GUI-thread functions unless explicitly documented otherwise.

docs/EXAMPLES.md

@@ -0,0 +1,23 @@
+# Examples
+
+Run examples with `uv run python examples/<name>.py`.
+
+- `basic_analog.py`
+- `basic_digital.py`
+- `basic_bar.py`
+- `basic_level.py`
+- `basic_status.py`
+- `basic_segmented.py`
+- `basic_compass.py`
+- `basic_thermometer.py`
+- `basic_battery.py`
+- `basic_multi_value.py`
+- `thresholds_markers.py`
+- `animations.py`
+- `dashboard.py`
+- `sizing.py`
+- `live_high_rate.py`
+- `live_worst_case.py`
+
+The live examples use a producer thread for data generation and a Dear PyGui frame callback for all
+gauge updates.

docs/GETTING_STARTED.md

@@ -0,0 +1,19 @@
+# Getting Started
+
+Install with `uv add dpg-gauges`, then import as `import dpg_gauges as dpgg`.
+
+Create gauges inside a Dear PyGui context:
+
+```python
+import dearpygui.dearpygui as dpg
+import dpg_gauges as dpgg
+
+dpg.create_context()
+with dpg.window(label="Dashboard"):
+    dpgg.digital_gauge(tag="speed", label="Speed", value=72, unit="km/h")
+
+dpgg.set_value("speed", 88)
+```
+
+All widget creation and runtime updates are Dear PyGui GUI-thread operations. If telemetry is
+produced in a worker thread, store the latest value and apply it from a GUI frame callback.