From 90c4490a3db99f3738126892edb883aa6fa4ab2c Mon Sep 17 00:00:00 2001
From: nick <coachward0742@gmail.com>
Date: Tue, 9 Jun 2026 15:03:49 -0600
Subject: [PATCH] docs: add pre-lilygo baseline checklist

---
 docs/CHATGPT_HANDOFF.md               |  6 +++
 docs/README.md                        |  2 +
 docs/pre-lilygo-baseline-checklist.md | 54 +++++++++++++++++++++++++++
 docs/project-state.md                 |  4 ++
 4 files changed, 66 insertions(+)
 create mode 100644 docs/pre-lilygo-baseline-checklist.md

diff --git a/docs/CHATGPT_HANDOFF.md b/docs/CHATGPT_HANDOFF.md
index d7aea83..0359772 100644
--- a/docs/CHATGPT_HANDOFF.md
+++ b/docs/CHATGPT_HANDOFF.md
@@ -179,3 +179,9 @@ Do not suggest adding DS18B20 support as if it is missing. Future work should pr
 The Cargo ESP API contract is documented in `docs/cargo-api-contract.md`.
 
 Before making dashboard firmware changes, inspect the current API tests and this contract. Do not move relay, BMS, DS18B20, alarm, or configuration ownership from the Cargo ESP to the dashboard.
+
+## Pre-LilyGO Baseline Checklist
+
+Before suggesting a release/tag prior to Cargo ESP hardware migration, check `docs/pre-lilygo-baseline-checklist.md`.
+
+Do not suggest migrating active Cargo ESP firmware to LilyGO hardware until the user explicitly decides to buy/use that board.
diff --git a/docs/README.md b/docs/README.md
index 3ed282d..881086a 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -43,3 +43,5 @@ Archived documents are kept for history, but the primary documents above should
 - `API.md` - High-level API notes and telemetry ownership.
 
 - `cargo-api-contract.md` - Cargo ESP API ownership and expected API areas for WebUI/dashboard clients.
+
+- `pre-lilygo-baseline-checklist.md` - Checklist for creating a known-good Cargo ESP 2-channel baseline before future LilyGO migration.
diff --git a/docs/pre-lilygo-baseline-checklist.md b/docs/pre-lilygo-baseline-checklist.md
new file mode 100644
index 0000000..6c23a70
--- /dev/null
+++ b/docs/pre-lilygo-baseline-checklist.md
@@ -0,0 +1,54 @@
+# Pre-LilyGO Baseline Checklist
+
+Use this checklist before creating a release/tag for the current Cargo ESP 2-channel baseline.
+
+## Goal
+
+Capture a known-good project state before migrating Cargo ESP hardware to a LilyGO T-Relay-S3 board or other expanded-output controller.
+
+## Required Before Tagging
+
+- [ ] Tests pass with `source .venv/bin/activate && python run_tests.py`
+- [ ] Working Cargo ESP WebUI confirmed
+- [ ] Relay/output control confirmed on current 2-channel board
+- [ ] DS18B20 temperature display confirmed in WebUI
+- [ ] Cargo ESP API contract documented
+- [ ] Controller roles documented
+- [ ] Pico dashboard archived
+- [ ] Waveshare ESP32-S3 Touch LCD 5B dashboard target documented
+- [ ] Load-switching hardware boundaries documented
+- [ ] No stale active Pico/UART dashboard references remain
+- [ ] Repo is clean: `git status --short`
+
+## Suggested Tag Name
+
+    v0.1.0-cargo-esp32-2ch-baseline
+
+## Suggested Release Title
+
+    Cargo ESP32 2-Channel Relay Board Baseline
+
+## Suggested Release Notes
+
+Baseline working release before future Cargo ESP hardware migration.
+
+This release captures the current Cargo ESP32 controller architecture using the 2-channel relay board.
+
+Includes:
+
+- Cargo ESP WebUI/API architecture
+- DS18B20 temperature support
+- Relay/output control
+- HTTP API contract tests
+- Legacy Pico dashboard archived
+- ESP32-S3 Waveshare 5B dashboard direction documented
+- Controller roles clarified
+- Load-switching hardware boundaries documented
+
+Known future work:
+
+- LilyGO T-Relay-S3 hardware evaluation
+- Expanded relay/output mapping
+- OTA workflow
+- ESP32-S3 dashboard firmware
+- Dashboard screen mockups
diff --git a/docs/project-state.md b/docs/project-state.md
index 6030d77..b66d5a2 100644
--- a/docs/project-state.md
+++ b/docs/project-state.md
@@ -246,3 +246,7 @@ Future work should focus on:
 The current Cargo ESP API ownership and expected endpoint areas are documented in `docs/cargo-api-contract.md`.
 
 This contract should guide future ESP32-S3 dashboard work so dashboard firmware targets stable Cargo ESP data instead of duplicating sensor or relay ownership.
+
+## Pre-LilyGO Baseline
+
+Before migrating Cargo ESP hardware to a LilyGO T-Relay-S3 or other expanded-output controller, use `docs/pre-lilygo-baseline-checklist.md` to confirm the current 2-channel Cargo ESP baseline is stable enough to tag.