promote: platformio profile baseline to main

.agents/context-index.md

@@ -0,0 +1,16 @@
+# Repository Context Index
+
+Repository structure:
+
+Source:
+* src
+* lib
+* scripts
+
+Tests:
+* tests
+
+Documentation:
+* docs
+
+ANR migration generated this file.

AGENTS.md

@@ -20,3 +20,25 @@ HiveTech is the beehive monitoring firmware line in the portfolio. Treat it as a
 ## Delivery Flow
 
 Use `feature -> develop -> main`. Keep public-facing docs and topics aligned with the actual firmware scope.
+
+<!-- ANR PROFILE START -->
+## Active Stack Profile
+
+This repository uses the `platformio-iot` stack profile.
+
+### Additional Focus
+
+- PlatformIO build and upload configuration
+- board, sensor, and pin assumptions
+- telemetry/topic contracts
+- hardware validation beyond compile success
+
+### Additional Working Rules
+
+- never commit device-specific secrets or local deployment values
+- keep hardware assumptions explicit in docs
+- treat topic and payload changes as interface changes
+- separate build success from real-device verification success
+- keep the local `platformio.ini` upload target as developer-local state unless a shared deployment path is intentionally introduced
+<!-- ANR PROFILE END -->
+

README.md

@@ -24,6 +24,14 @@ See [docs/STATUS.md](docs/STATUS.md) for the current project state.
 
 The firmware expects a local `src/config.h` file that is not committed. Start from [src/config_template.h](src/config_template.h) and adjust the values for your network and MQTT broker.
 
+Additional operating context now lives in:
+
+- [docs/hardware.md](docs/hardware.md)
+- [docs/operations.md](docs/operations.md)
+- [docs/topic-contracts.md](docs/topic-contracts.md)
+- [docs/verification.md](docs/verification.md)
+- [anr.profile.yaml](anr.profile.yaml)
+
 ## Topics Published
 
 - `HT_BME280_Temperature`
@@ -34,6 +42,6 @@ The firmware expects a local `src/config.h` file that is not committed. Start fr
 ## Immediate Next Steps
 
 1. Replace the legacy `config.h` flow with a clearer credentials/config separation.
-2. Document the intended hardware wiring for the hive node.
+2. Add a repeatable local build check that uses placeholder config for compile-only validation.
 3. Decide which parts should remain standalone versus moving into `SkySentinel`.
-4. Add a simple validation/build workflow once the local config path is standardized.
+4. Add hive-specific telemetry beyond the current BME280 baseline once the hardware scope is stable.

anr.profile.yaml

@@ -0,0 +1,20 @@
+profile_id: platformio-iot
+category: firmware
+focus:
+  - platformio
+  - hardware-validation
+  - device-config
+  - telemetry
+recommended_docs:
+  - docs/hardware.md
+  - docs/verification.md
+  - docs/operations.md
+  - docs/topic-contracts.md
+recommended_skills:
+  - embedded-debugging
+  - hardware-bringup
+  - telemetry-review
+recommended_guardrails:
+  - secret-handling
+  - hardware-assumption-boundaries
+  - deployment-safety

anr.yaml

@@ -0,0 +1,8 @@
+anr_version: "0.1"
+context_index: .agents/context-index.md
+detected_directories:
+  - src
+  - lib
+  - scripts
+  - tests
+  - docs

docs/STATUS.md

@@ -9,19 +9,20 @@ HiveTech is an ESP32 firmware prototype for live beehive monitoring. It reads BM
 - Revival candidate with real firmware code, not just a stub
 - Public again by explicit portfolio decision
 - Still uses a legacy `config.h` include path
+- PlatformIO/IoT profile context is now committed in `anr.profile.yaml` plus focused hardware and operations docs
 - No modern CI/build validation yet
 - Local developer deployment settings are still present outside committed templates
 
 ## Known Gaps
 
-- No committed configuration template existed before this cleanup pass
-- No README or public-facing operational context existed
-- Hardware wiring and deployment procedure are not yet documented
-- MQTT contract is still implicit in code
+- The repo still relies on a simple local `config.h` include model
+- Hardware wiring is documented only to the level visible in current firmware assumptions
+- Deployment is still local and OTA-target specific
+- MQTT contract is documented but still topic-only, without retained/availability semantics
 
 ## Next Milestone
 
-Stabilize the public repo baseline, then decide whether HiveTech becomes:
+Stabilize the revived public firmware baseline, then decide whether HiveTech becomes:
 
 1. a standalone beehive telemetry node, or
 2. a domain-specific branch of the broader SkySentinel ecosystem.

docs/hardware.md

@@ -0,0 +1,30 @@
+# Hardware
+
+## Target
+
+HiveTech currently targets a generic `esp32dev` board definition with a single BME280 environmental sensor.
+
+Current firmware assumptions from the code:
+
+- board: ESP32 dev board (`[env:esp32dev]` in `platformio.ini`)
+- primary sensor: BME280 via I2C
+- I2C address: `0x77`
+- sleep cycle: `TIME_TO_SLEEP = 60` seconds
+- deep sleep wake source: timer wakeup
+
+The code calls `Wire.begin()` without explicit pins, so the active SDA/SCL mapping depends on the actual ESP32 board defaults or local hardware wiring.
+
+## Pin Map
+
+- `GPIO25`: `redLEDpin`
+- `GPIO4`: `greenLEDpin`
+- `GPIO15`: `ONE_WIRE_BUS`
+- `GPIO5`: `SD_CS`
+
+Not every declared pin is currently exercised in the active telemetry flow. Treat this list as the current code-level hardware contract, not as proof that every peripheral is physically assembled on the node.
+
+## Notes
+
+- The firmware currently uses only BME280 telemetry in the active publish path.
+- OTA is enabled, so the deployed node must stay reachable on the local network during maintenance.
+- Before adding more hive-specific sensors, document their wiring and topic outputs here first.

docs/operations.md

@@ -0,0 +1,29 @@
+# Operations
+
+## Runtime
+
+HiveTech is a local-first firmware repo.
+
+Current runtime flow:
+
+1. local `src/config.h` provides Wi-Fi SSID, password, and MQTT broker
+2. firmware boots on ESP32
+3. node connects to Wi-Fi
+4. OTA is initialized
+5. BME280 values are read and published to MQTT
+6. node returns to timed deep sleep
+
+`platformio.ini` currently contains a developer-local `upload_port`. Treat that as local machine state, not as committed team-wide truth.
+
+## Safety Rules
+
+- separate local credentials from committed templates
+- keep `src/config.h` untracked
+- verify the target IP/device before OTA uploads
+- document any destructive or risky deployment step explicitly
+
+## Recovery Notes
+
+- If Wi-Fi or MQTT details change, update only local config files.
+- If OTA fails, fall back to a direct flash path rather than repeatedly retrying against the wrong node.
+- If BME280 detection fails, check wiring and I2C address assumptions before changing code.

docs/topic-contracts.md

@@ -0,0 +1,28 @@
+# Topic Contracts
+
+## Purpose
+
+Document the MQTT topics currently published by HiveTech.
+
+## Topics
+
+- `HT_BME280_Temperature`
+  Payload: numeric value as text
+  Meaning: ambient temperature from the BME280 in degrees Celsius
+- `HT_BME280_Humidity`
+  Payload: numeric value as text
+  Meaning: relative humidity from the BME280
+- `HT_BME280_Pressure`
+  Payload: numeric value as text
+  Meaning: barometric pressure from the BME280 divided by `100`
+- `HT_BME280_Altitude`
+  Payload: numeric value as text
+  Meaning: altitude reported by the BME280 library
+
+Current code publishes these topics once per wake cycle after sensor readout and MQTT reconnect.
+
+## Change Rules
+
+- Keep topic names stable unless downstream automations are migrated deliberately.
+- Treat unit changes or payload-format changes as interface changes.
+- If retained messages, availability topics, or structured payloads are introduced, document them here before rollout.

docs/verification.md

@@ -0,0 +1,26 @@
+# Verification
+
+## Goal
+
+Keep firmware changes reproducible and separate "compiles locally" from "works on the hive node".
+
+## Minimum Checks
+
+1. Copy `src/config_template.h` to local `src/config.h` or provide an equivalent local config file.
+2. Run `platformio run` for `env:esp32dev`.
+3. Flash or OTA-update the node using the local deployment path from `platformio.ini`.
+4. Confirm serial boot output reaches:
+   - Wi-Fi connect
+   - MQTT connect
+   - BME280 detection
+   - deep sleep entry
+5. Verify these MQTT topics receive fresh values:
+   - `HT_BME280_Temperature`
+   - `HT_BME280_Humidity`
+   - `HT_BME280_Pressure`
+   - `HT_BME280_Altitude`
+
+## Separation Of Checks
+
+- Compile-only validation is useful for refactors and dependency changes.
+- Real hardware validation is still mandatory after sensor, networking, OTA, or sleep-logic changes.