diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..2ea0b24
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,4 @@
+firmware/secrets.yaml
+.esphome/
+__pycache__/
+*.pyc
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..7bdfd18
--- /dev/null
+++ b/README.md
@@ -0,0 +1,20 @@
+# Firecrest
+
+ESPHome firmware for the Waveshare ESP32-S3-Touch-LCD-7B touch display board,
+configured as a smart thermostat panel with direct 24VAC HVAC control.
+
+Requires Home Assistant with the ESPHome integration.
+
+## Hardware
+
+See [docs/build-guide-phase1-notes.md](docs/build-guide-phase1-notes.md) for
+full pin assignments and Phase 1 hardware decisions.
+
+## Flashing
+
+1. Copy `firmware/secrets.example.yaml` to `firmware/secrets.yaml` and fill in your values.
+2. `esphome run firmware/waveshare-thermostat.yaml`
+
+## License
+
+MIT
diff --git a/firmware/components/climate.yaml b/firmware/components/climate.yaml
new file mode 100644
index 0000000..743aa57
--- /dev/null
+++ b/firmware/components/climate.yaml
@@ -0,0 +1 @@
+# placeholder — see task 3/4/5/6
diff --git a/firmware/components/display.yaml b/firmware/components/display.yaml
new file mode 100644
index 0000000..743aa57
--- /dev/null
+++ b/firmware/components/display.yaml
@@ -0,0 +1 @@
+# placeholder — see task 3/4/5/6
diff --git a/firmware/components/relays.yaml b/firmware/components/relays.yaml
new file mode 100644
index 0000000..743aa57
--- /dev/null
+++ b/firmware/components/relays.yaml
@@ -0,0 +1 @@
+# placeholder — see task 3/4/5/6
diff --git a/firmware/components/sensors.yaml b/firmware/components/sensors.yaml
new file mode 100644
index 0000000..743aa57
--- /dev/null
+++ b/firmware/components/sensors.yaml
@@ -0,0 +1 @@
+# placeholder — see task 3/4/5/6
diff --git a/firmware/secrets.example.yaml b/firmware/secrets.example.yaml
new file mode 100644
index 0000000..ff9fad3
--- /dev/null
+++ b/firmware/secrets.example.yaml
@@ -0,0 +1,4 @@
+wifi_ssid: "your_wifi_ssid"
+wifi_password: "your_wifi_password"
+ha_api_key: "your_home_assistant_api_encryption_key"
+ota_password: "your_ota_password"
diff --git a/firmware/waveshare-thermostat.yaml b/firmware/waveshare-thermostat.yaml
new file mode 100644
index 0000000..ee8d86b
--- /dev/null
+++ b/firmware/waveshare-thermostat.yaml
@@ -0,0 +1,47 @@
+substitutions:
+  name: firecrest
+  friendly_name: "Firecrest Thermostat"
+
+esphome:
+  name: ${name}
+  friendly_name: ${friendly_name}
+  platformio_options:
+    board_build.flash_mode: dio
+
+esp32:
+  board: esp32-s3-devkitc-1
+  variant: esp32s3
+  flash_size: 16MB
+  framework:
+    type: esp-idf
+    sdkconfig_options:
+      CONFIG_ESP32S3_DATA_CACHE_64KB: y
+      CONFIG_ESP32S3_INSTRUCTION_CACHE_32KB: y
+
+psram:
+  mode: octal
+  speed: 80MHz
+
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+  ap:
+    ssid: "${friendly_name} Fallback"
+    password: "thermostat1234"
+
+api:
+  encryption:
+    key: !secret ha_api_key
+
+ota:
+  - platform: esphome
+    password: !secret ota_password
+
+logger:
+  level: DEBUG
+
+packages:
+  display: !include components/display.yaml
+  sensors: !include components/sensors.yaml
+  relays: !include components/relays.yaml
+  climate: !include components/climate.yaml