# AGENTS.md

## Current status

Project instruction set initialized.

## Completed steps

None yet.

## Current step

Step 1 - Public API contract and pure core.

## Design decisions

- Package is managed with uv.
- Public import is `import dpg_gauges as dpgg`.
- Package target is Python 3.11+.
- The package is Dear PyGui-only, but pure configuration/state helpers should avoid Dear PyGui imports where practical.
- Widget creation and Dear PyGui item operations are GUI-thread-only.
- Runtime value/configuration updates are intended to be called from the GUI thread.
- High-frequency updates should be smoothed/coalesced so gauges remain readable and flicker-free.
- Out-of-range values clamp to min/max and display the clamped value.
- Gauges are display-only for the first release.
- Thresholds and redline zones are visual only; they do not trigger events.
- The public API should feel like normal Dear PyGui context-manager usage.

## Known issues

None yet.

## Commands used

- Read `codex-old/README.md`, `codex-old/FEATURES.md`, `codex-old/ARCHITECTURE.md`, `codex-old/STEPS.md`, and `codex-old/AGENTS.md`.
- Inspected `/home/hector/projects/dpg-map` package, examples, tests, docs, and pyproject structure.
- Created the initial `codex/` instruction documents for `dpg-gauges`.

## Next action

Implement Step 1.