# Agent Guide

This project has dedicated specifications to keep implementation work aligned and to prevent agent drift.

Before changing code, read the documentation that matches the touched area:

- `Documentation/API Reference/README.md`
  Entry point for entity, operation, invariant, and test expectations.
- `Documentation/API Reference/UI_ALIGNMENT.md`
  UI-to-spec mapping and known alignment gaps.
- `Documentation/Project Structure and Naming.md`
  Folder, naming, and view-organization rules.
- `Documentation/Research Resources/README.md`
  Vendor manuals, protocol notes, and reverse-engineering material.

## Working Rules

- Treat `MUST` items in `Documentation/API Reference/` as required behavior.
- Treat `SHOULD` items as expected behavior; regressions need a reason and documentation update.
- If code and documentation disagree, do not silently choose one. Update the implementation, update the spec, or call out the conflict.
- Keep feature work scoped to the relevant model, view, or operation described in the docs.
- When adding behavior, update the matching API Reference page if the behavior changes an invariant, public API, storage shape, sync behavior, or user-visible workflow.
- Prefer existing project patterns over new abstractions unless the docs or surrounding code clearly support the change.

## Quick Routing

- Meter Bluetooth, connection, measurements: `Documentation/API Reference/Meter.md`, `BluetoothDiscovery.md`, `Operations.md`
- Charge sessions and charged devices: `ChargedDevice.md`, `ChargingMonitoring.md`, `ChargeCurveIsolation.md`, `ChargeCurveStorage.md`
- Capacity and consumption logic: `CapacityMeasurement.md`, `ConsumptionMeasurement.md`, `IdleConsumptionMeasurement.md`
- Powerbank behavior: `Powerbank.md`
- CloudKit and cross-device data integrity: `CloudKitSync.md`, `Charge Session Integrity and Conflict Healing.md`
- UI changes: `UI_ALIGNMENT.md` and the relevant operation/entity page