# Agent Guide: Building with ESP Viewer

This guide is designed for **AI Agents** (like me!) to help you understand how to extend, configure, and use this framework effectively.

## 1. Core Abstractions

### 1.1 The Profile (The Brain)
The **Profile** is the single source of truth. It defines the entire UI and communication logic. 
- **Action**: To change the UI, modify the JSON Profile.
- **Pattern**: If you need to add a new sensor, add a new entry to `streams` and a corresponding entry to `plots`.

### 1.2 EspViewerEngine (The Broker) & DeviceService (The Worker)
The backend runs in a separate thread. `EspViewerEngine` holds the queues and manages `DeviceService`, which handles the serial port and parses data.
- **IPC**: Backend -> Engine -> Frontend events use `EventType`. Frontend -> Engine -> Backend commands use `CommandType`.

### 1.3 PySide Adapter & GenericWindow (The Face)
The UI doesn't know about specific hardware or background threads. It relies on a `BaseFrontendAdapter` (like `PySideAdapter`) to bridge thread events into native UI signals. It just renders whatever the Profile tells it to.
- **Dynamic Widgets**: Controls are generated based on the `widget` field in parameters.

### 1.4 Diagnostics Bridge
The framework supports low-level hardware diagnostics via `esptool`. This requires the `DeviceService` to handle "Iterative Re-Connects", where telemetry is paused to let the tool use the serial port.
- **Implementation**: See `esp_viewer/core/chip_info.py`.

## 2. Common Agent Recipes

### Recipe A: Adding a new Control Widget
1.  Identify the command the device expects (e.g., `SET_VOLT <val>`).
2.  Add a new parameter to `parameters`:
    ```json
    {
      "id": "voltage",
      "label": "Voltage Control",
      "widget": "slider",
      "set_template": "SET_VOLT {value}"
    }
    ```
3.  The UI will automatically render a slider and handle the communication.

### Recipe B: Parsing a new Data Curve
1.  Identify the device's output format (e.g., `DATA,123,456`).
2.  Add a stream parser:
    ```json
    {
      "id": "raw_sensor",
      "delimiter": ",", "header": "DATA",
      "fields": ["timestamp", "val1", "val2"]
    }
    ```
3.  Add a plot to show it:
    ```json
    {
      "title": "Raw Data",
      "y_items": ["val1", "val2"],
      "stream_id": "raw_sensor"
    }
    ```

## 3. Extension Points

If you need to add logic that can't be expressed in JSON:
- **Custom Drivers**: Inherit from `BaseDriver` in `core/drivers.py`.
- **Custom Widgets**: Add new classes to `ui/widgets/` and register them in `ui/dynamic_panel.py`.

---

## 4. Agent Code of Conduct

To maintain the quality and reliability of this framework, all Agents must adhere to the following standards:

### 4.1 Strict Versioning (SemVer)
We follow [Semantic Versioning 2.0.0](https://semver.org/). You MUST update the version in `pyproject.toml` and `esp_viewer/__init__.py` for **every release**.

| Change Type | Version to Bump | Example |
|---|---|---|
| Breaking API change | **Major** (`X.y.z → X+1.0.0`) | Removing a protocol field, renaming a core class |
| **New feature** | **Minor** (`x.Y.z → x.Y+1.0`) | New plot type, new widget, resizable layout |
| Bug fix / doc update | **Patch** (`x.y.Z → x.y.Z+1`) | Fixing a crash, correcting a comment |

> [!IMPORTANT]
> Adding a new feature (even a minor UI change) requires a **Minor** bump, not a Patch. Patch is reserved strictly for bug fixes and documentation corrections.

### 4.2 Mandatory Changelog Updates
Every single modification **MUST** be accompanied by an entry in `CHANGELOG.md`. 
- Use the standard headings: `Added`, `Changed`, `Fixed`, `Deprecated`, `Removed`, `Security`.
- Ensure the date and version number match the release.

### 4.3 Documentation Synchronization
New features are not "done" until they are documented. The documentation follows a clear hierarchy:

| Document | Purpose |
|---|---|
| `.agent/skills/` | High-level entry points and developer workflow overviews (links to `docs/`). |
| `docs/architecture.md` | Core framework architecture, module designs, and data flow. |
| `docs/development.md` | Environment setup, running app/tests, and build processes. |
| `docs/profile.md` | JSON Profile schema definitions and UI widget configuration. |
| `docs/protocol.md` | IPC sequence diagrams and serial communication contracts. |
| `docs/agent_guide.md` | This guide. Coding standards, recipes, and best practices. |

### 4.4 No Placeholders
Do not commit unfinished code or documentation with "TODO" or "Placeholder" markers. If a feature is partially implemented, mark it clearly as `[Experimental]` or `[WIP]` in the documentation.
