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