diff --git a/docs/products/ESPHome-Starter-Kit/modules/button-module-sg.md b/docs/products/ESPHome-Starter-Kit/modules/button-module-sg.md
new file mode 100644
index 0000000000..c967153258
--- /dev/null
+++ b/docs/products/ESPHome-Starter-Kit/modules/button-module-sg.md
@@ -0,0 +1,116 @@
+---
+title: Adding the button module
+description: Wire up the ESPHome Starter Kit button module, add it through ESPHome Device Builder, and verify presses in the web server.
+---
+
+The button module is the first input your starter kit gets, and the fastest way to feel ESPHome respond to a physical action. By the end of this tutorial you'll have the button wired to your ESP32-C6, surfaced as a binary sensor in your YAML, and toggling live in the web server when you press it.
+
+!!! note "Before you start"
+
+ Work through the two prerequisites first.
+
+ - [Start here](../start-here.md) to snap the button module off the panel.
+ - [First steps](../setup/first-steps.md) to install ESPHome Device Builder and create your starter kit device.
+
+## Prerequisite, enable the Web Server
+
+The Web Server broadcasts a local website from your device. That lets you navigate to the device's IP address or hostname (for example esphome-starter-kit.local) to control it from any browser on your network.
+
+1. In the ESPHome Device Builder, navigate to the **Core configuration** section.
+2. Click **Add component**.
+3. Scroll to **Web Server** and click **Add**.
+4. Click **Add** once more to confirm.
+5. Toggle **Show advanced settings**.
+6. Scroll down to **Version** and select **3** from the dropdown.
+
+
+
+## Attach the button module
+
+Connect the button module to the ESP32-C6 using one of the FPC ribbon cables that came with the kit. Either FPC connector on the C6 works, top or bottom.
+
+1. Unplug the USB-C cable from the ESP32-C6 so the board is powered off.
+
+ 
+
+2. Flip up the latch on the FPC connector, then gently slide the ribbon cable into the connector. Gently press the latch down to lock it in place.
+
+ 
+
+3. Slide the ribbon cable into the button module with the blue side facing upwards, then press the latch down to lock it in place.
+
+ 
+
+4. Plug the C6 back into your computer.
+
+!!! warning "Handle the FPC connectors gently"
+
+ The latches are small and the ribbon cable is fragile. Lift the latch with a fingernail, slide the cable in, and press the latch down. Never pull on the cable itself.
+
+## Add the button in ESPHome Device Builder
+
+ESPHome Device Builder ships an **Add Component** flow that knows the pin layout for every Apollo Starter Kit module. Use it instead of writing the binary sensor by hand, and you'll get the right GPIO and inversion settings on the first try.
+
+1. Open your starter kit device in Device Builder and click **Edit**.
+2. In the ESPHome Device Builder, navigate to the **Components** section.
+3. Click **Add Component** in the editor toolbar.
+4. Search for **Button** and select the **Button Module**.
+5. Click **Add**. Device Builder inserts the button's binary sensor block into your YAML.
+
+
+
+??? note "What the button YAML does"
+
+ The block Add Component drops into your config looks like this.
+
+ ```yaml
+ binary_sensor:
+ - platform: gpio
+ pin:
+ number: GPIO6
+ inverted: true
+ mode:
+ input: true
+ pullup: true
+ id: my_button
+ name: "Button"
+ ```
+
+ Each option does something specific.
+
+ | Option | What it does |
+ | --- | --- |
+ | `platform: gpio` | Reads a digital input on a GPIO pin. |
+ | `number: GPIO6` | The pin the button module's FPC connector wires to on the ESP32-C6. |
+ | `inverted: true` | The pin reads LOW when the button is pressed, so this flips it to an intuitive on or off state. |
+ | `mode.input: true` | Configures the pin as an input. |
+ | `mode.pullup: true` | Enables the C6's internal pull-up so the pin doesn't float when the button isn't pressed. |
+ | `id: my_button` | Internal handle you can reference from automations and lambdas elsewhere in the config. |
+ | `name: "Button"` | The friendly name shown in Home Assistant and the web server. |
+
+## Flash the firmware
+
+Flash the device so the new web server and button entity go live.
+
+1. Click **Install** on your device card in ESPHome Device Builder.
+2. Choose **Plug into the computer running ESPHome Device Builder** for the first flash, or **On The Network** if the device is already on your Wi-Fi.
+3. Wait for the compile and flash to finish. First builds can take a few minutes.
+4. The device reboots and reconnects to your Wi-Fi on its own.
+
+
+
+## Test the button
+
+With the device back online, the button entity is live on the web server. Open it in a browser on the same network and watch it react in real time.
+
+
+
+1. In a browser, open `http://.local/`. If you used `esphome-starter-kit` as the device name in [First steps](../setup/first-steps.md), that's `http://esphome-starter-kit.local/`.
+2. Find the **Button** entity in the binary sensor list.
+3. Press the button on the module. The entity flips from **OFF** to **ON** while the button is held, then back to **OFF** when you release it.
+
+
+
+!!! success "Your button module is ready"
+
+ Your button module is now wired up and reporting state. From here it can toggle lights in your room, water your plants, or trigger any Home Assistant automation you can think of.
diff --git a/docs/products/ESPHome-Starter-Kit/modules/motion-module-sg.md b/docs/products/ESPHome-Starter-Kit/modules/motion-module-sg.md
new file mode 100644
index 0000000000..15da3bfa6a
--- /dev/null
+++ b/docs/products/ESPHome-Starter-Kit/modules/motion-module-sg.md
@@ -0,0 +1,121 @@
+---
+title: Adding the motion module
+description: Wire up the ESPHome Starter Kit motion module to turn your kit into an accurate motion sensor.
+---
+
+The motion module turns your starter kit into a motion sensor. By the end of this tutorial you'll have an MH-SR602 wired to your ESP32-C6, surfaced as a binary sensor in your YAML, and flipping live in the web server whenever something moves in front of it.
+
+!!! note "Before you start"
+
+ Work through the two prerequisites first.
+
+ - [Start here](../start-here.md) to snap the motion module off the panel.
+ - [First steps](../setup/first-steps.md) to install ESPHome Device Builder and create your starter kit device.
+
+## Prerequisite, enable the Web Server
+
+The Web Server broadcasts a local website from your device. That lets you navigate to the device's IP address or hostname (for example esphome-starter-kit.local) to control it from any browser on your network.
+
+1. In the ESPHome Device Builder, navigate to the **Core configuration** section.
+2. Click **Add component**.
+3. Scroll to **Web Server** and click **Add**.
+4. Click **Add** once more to confirm.
+5. Toggle **Show advanced settings**.
+6. Scroll down to **Version** and select **3** from the dropdown.
+
+
+
+## Attach the PIR
+
+The PIR sensor (the small white dome on a tiny PCB) ships separately from the motion module so it can be packed safely. Install it onto the module before plugging anything into the C6.
+
+1. Take the PIR sensor out of the box.
+2. Line up the **Out** label on each side as shown in the animation below.
+3. Press it down firmly until the pins are fully seated.
+
+
+
+## Attach the motion module
+
+Connect the motion module to the ESP32-C6 using one of the FPC ribbon cables that came with the kit. Either FPC connector on the C6 works, top or bottom.
+
+1. Unplug the USB-C cable from the ESP32-C6 so the board is powered off.
+
+ 
+
+2. Flip up the latch on the FPC connector, then gently slide the ribbon cable into the connector. Gently press the latch down to lock it in place.
+
+ 
+
+3. Slide the ribbon cable into the motion module with the blue side facing upwards, then press the latch down to lock it in place.
+
+ 
+
+4. Plug the C6 back into your computer.
+
+!!! warning "Handle the FPC connectors gently"
+
+ The latches are small and the ribbon cable is fragile. Lift the latch with a fingernail, slide the cable in, and press the latch down. Never pull on the cable itself.
+
+## Add the motion sensor in ESPHome Device Builder
+
+ESPHome Device Builder ships an **Add Component** flow that knows the pin layout for every Apollo Starter Kit module. Use it instead of writing the binary sensor by hand, and you'll get the right GPIO and pin mode on the first try.
+
+1. Open your starter kit device in Device Builder and click **Edit**.
+2. Click **Add Component** in the editor toolbar.
+3. Search for **Motion** and select the Apollo Starter Kit PIR motion component.
+4. Click **Add**. Device Builder inserts the PIR's binary sensor block into your YAML.
+
+
+
+??? note "What the motion YAML does"
+
+ The block Add Component drops into your config looks like this.
+
+ ```yaml
+ binary_sensor:
+ - platform: gpio
+ name: Motion Module
+ pin: 3
+ device_class: motion
+ id: motion_module
+ ```
+
+ Each option does something specific.
+
+ | Option | What it does |
+ | --- | --- |
+ | `platform: gpio` | Reads a digital input on a GPIO pin. |
+ | `pin: 3` | The pin the motion module's FPC connector wires to on the ESP32-C6. |
+ | `device_class: motion` | Tells Home Assistant this is a motion sensor, so it shows the right icon and works in motion-related templates and blueprints. |
+ | `id: motion_module` | Internal handle you can reference from automations and lambdas elsewhere in the config. |
+ | `name: "Motion Module"` | The friendly name shown in Home Assistant and the web server. |
+
+## Flash the firmware
+
+Flash the device so the new web server and motion entity go live.
+
+1. Click **Install** on your device card in ESPHome Device Builder.
+2. Choose **Plug into the computer running ESPHome Device Builder** for the first flash, or **On The Network** if the device is already on your Wi-Fi.
+3. Wait for the compile and flash to finish. First builds can take a few minutes.
+4. The device reboots and reconnects to your Wi-Fi on its own.
+
+
+
+## Test motion
+
+With the device back online, the motion entity is live on the web server. Open it in a browser on the same network and watch it react in real time.
+
+1. In a browser, open `http://.local/`. If you used `esphome-starter-kit` as the device name in [First steps](../setup/first-steps.md), that's `http://esphome-starter-kit.local/`.
+2. Find the **Motion** entity in the binary sensor list.
+3. Wave your hand in front of the sensor. The entity flips from OFF to ON while motion is detected, then back to OFF a few seconds after motion stops.
+
+!!! tip "Give the motion sensor a moment to settle"
+
+ PIR sensors need a brief warm-up after powering on, usually 5 to 10 seconds, before their readings stabilise. If the sensor reports motion right after boot even when nothing is moving, give it a moment.
+
+
+
+!!! success "Your motion module is ready"
+
+ You're now ready to build occupancy-based automations across your home.
diff --git a/docs/products/ESPHome-Starter-Kit/modules/rgb-buzzer-module-sg.md b/docs/products/ESPHome-Starter-Kit/modules/rgb-buzzer-module-sg.md
new file mode 100644
index 0000000000..5b89b78e71
--- /dev/null
+++ b/docs/products/ESPHome-Starter-Kit/modules/rgb-buzzer-module-sg.md
@@ -0,0 +1,143 @@
+---
+title: Adding the LED & Buzzer module
+description: Wire up the ESPHome Starter Kit LED & Buzzer module, add it through ESPHome Device Builder, then control the lights and play tones.
+---
+
+The LED & Buzzer is the starter kit's notification module, a strip of ten addressable RGB LEDs and a small piezo buzzer behind the ESPHome logo silkscreen. By the end of this tutorial you'll have the lights and buzzer wired to your ESP32-C6, surfaced in your YAML, and ready to flash, animate, or sing in response to anything else you build.
+
+!!! note "Before you start"
+
+ Work through the two prerequisites first.
+
+ - [Start here](../start-here.md) to snap the LED & Buzzer module off the panel.
+ - [First steps](../setup/first-steps.md) to install ESPHome Device Builder and create your starter kit device.
+
+## Prerequisite, enable the Web Server
+
+The Web Server broadcasts a local website from your device. That lets you navigate to the device's IP address or hostname (for example esphome-starter-kit.local) to control it from any browser on your network.
+
+1. In the ESPHome Device Builder, navigate to the **Core configuration** section.
+2. Click **Add component**.
+3. Scroll to **Web Server** and click **Add**.
+4. Click **Add** once more to confirm.
+5. Toggle **Show advanced settings**.
+6. Scroll down to **Version** and select **3** from the dropdown.
+
+
+
+## Attach the LED & Buzzer module
+
+Connect the LED & Buzzer module to the ESP32-C6 using one of the FPC ribbon cables that came with the kit. Either FPC connector on the C6 works, top or bottom.
+
+1. Unplug the USB-C cable from the ESP32-C6 so the board is powered off.
+
+ 
+
+2. Flip up the latch on the FPC connector, then gently slide the ribbon cable into the connector. Gently press the latch down to lock it in place.
+
+ 
+
+3. Slide the ribbon cable into the LED & Buzzer module with the blue side facing upwards, then press the latch down to lock it in place.
+
+ 
+
+4. Plug the C6 back into your computer.
+
+!!! warning "Handle the FPC connectors gently"
+
+ The latches are small and the ribbon cable is fragile. Lift the latch with a fingernail, slide the cable in, and press the latch down. Never pull on the cable itself.
+
+## Add the bundle in ESPHome Device Builder
+
+ESPHome Device Builder ships an **Add Component** flow that knows the pin layout for every Apollo Starter Kit module. Use it instead of writing the LED strip and buzzer config by hand, and you'll get the right GPIOs, chipset, and PWM setup on the first try.
+
+1. Open your starter kit device in Device Builder and click **Edit**.
+2. In the ESPHome Device Builder, navigate to the **Components** section.
+3. Click **Add Component** in the editor toolbar.
+4. Select the **RGB LED + Buzzer Module Bundle** at the top.
+5. Click **Add** → click **Add** → click **Add** → click **Add**. Each section lets you make changes, but you can leave them at defaults for now. Device Builder inserts the light, output, and rtttl blocks into your YAML.
+
+
+
+??? note "What the LED & Buzzer module YAML does"
+
+ The blocks Add Component drops into your config look like this.
+
+ ```yaml
+ light:
+ - platform: esp32_rmt_led_strip
+ id: rgb_module
+ name: "RGB Module Light"
+ pin: GPIO14
+ chipset: WS2812
+ num_leds: 10
+ rmt_symbols: 48
+ rgb_order: grb
+ default_transition_length: 0s
+ effects:
+ - addressable_rainbow:
+ name: "Rainbow"
+ - addressable_twinkle:
+ name: "Twinkle"
+
+ output:
+ - platform: ledc
+ pin: GPIO18
+ id: buzzer
+
+ rtttl:
+ id: rtttl_buzzer
+ output: buzzer
+ ```
+
+ **LED strip**
+
+ | Option | What it does |
+ | --- | --- |
+ | `light.platform: esp32_rmt_led_strip` | Uses the ESP32's RMT peripheral to drive addressable LEDs with precise timing. |
+ | `light.pin: GPIO14` | The data line going to the first LED on the PCB. |
+ | `light.chipset: WS2812` | Which addressable LED protocol to use. WS2812 is the most common, sometimes also called NeoPixel. |
+ | `light.num_leds: 10` | The number of LEDs on the LED & Buzzer module. |
+ | `light.rgb_order: grb` | Color channel order. WS2812 LEDs receive color data in green-red-blue order, so this makes sure red looks red and not green. |
+ | `light.rmt_symbols: 48` | Low-level RMT setting needed on the ESP32-C6. Leave it at 48. |
+ | `light.effects` | Pre-loaded animations you can select from the web server or trigger from Home Assistant. |
+
+ **Piezo buzzer**
+
+ | Option | What it does |
+ | --- | --- |
+ | `output.platform: ledc` | PWM output for driving the buzzer. PWM is how digital pins create audio tones on a piezo. |
+ | `output.pin: GPIO18` | The pin the buzzer is wired to. |
+ | `output.id: buzzer` | Internal handle the rtttl component uses to send tones to this output. |
+ | `rtttl.id: rtttl_buzzer` | Internal handle for triggering tunes from automations and lambdas. |
+ | `rtttl.output: buzzer` | Tells rtttl to use the buzzer output for playback. |
+
+## Flash the firmware
+
+Flash the device so the new web server and the LED and buzzer entities go live.
+
+1. Click **Install** on your device card in ESPHome Device Builder.
+2. Choose **Plug into the computer running ESPHome Device Builder** for the first flash, or **On The Network** if the device is already on your Wi-Fi.
+3. Wait for the compile and flash to finish. First builds can take a few minutes.
+4. The device reboots and reconnects to your Wi-Fi on its own.
+
+
+
+## Test the LEDs
+
+With the device back online, the RGB LED light entity is live on the web server. Open it in a browser on the same network and play with it.
+
+1. In a browser, open `http://.local/`. If you used `esphome-starter-kit` as the device name in [First steps](../setup/first-steps.md), that's `http://esphome-starter-kit.local/`.
+2. Toggle the **RGB LEDs** entity and play around with the colors and brightness.
+
+
+
+!!! tip "Go further with light effects"
+
+ There are a lot of advanced things you can do with a light entity. See the [advanced LED & Buzzer effects wiki](#TODO-link-to-advanced-light-component-wiki) for more.
+
+The buzzer doesn't have its own web server control, since it's an output rather than a switch. Once you've added the device to Home Assistant, you can trigger tunes with the `rtttl.play` action or by exposing your own service.
+
+!!! success "Your LED & Buzzer notification module is ready"
+
+ Your LED & Buzzer module is now wired up. From here, toggle the lights, animate the strip, or play tunes through the buzzer in response to anything else you build.
diff --git a/docs/products/ESPHome-Starter-Kit/modules/temperature-humidity-module-sg.md b/docs/products/ESPHome-Starter-Kit/modules/temperature-humidity-module-sg.md
new file mode 100644
index 0000000000..b171633bc1
--- /dev/null
+++ b/docs/products/ESPHome-Starter-Kit/modules/temperature-humidity-module-sg.md
@@ -0,0 +1,122 @@
+---
+title: Adding the temperature and humidity module
+description: Wire up the ESPHome Starter Kit Temperature and Humidity module for accurate AHT20F temperature and humidity readings in any room.
+---
+
+The temperature and humidity module is your starter kit's first environmental sensor, reading the air around it on whatever interval you choose. By the end of this tutorial you'll have an AHT20F wired to your ESP32-C6, surfaced as two sensors in your YAML, and updating live in the web server.
+
+!!! note "Before you start"
+
+ Work through the two prerequisites first.
+
+ - [Start here](../start-here.md) to snap the temperature and humidity module off the panel.
+ - [First steps](../setup/first-steps.md) to install ESPHome Device Builder and create your starter kit device.
+
+## Prerequisite, enable the Web Server
+
+The Web Server broadcasts a local website from your device. That lets you navigate to the device's IP address or hostname (for example esphome-starter-kit.local) to control it from any browser on your network.
+
+1. In the ESPHome Device Builder, navigate to the **Core configuration** section.
+2. Click **Add component**.
+3. Scroll to **Web Server** and click **Add**.
+4. Click **Add** once more to confirm.
+5. Toggle **Show advanced settings**.
+6. Scroll down to **Version** and select **3** from the dropdown.
+
+
+
+## Attach the temperature and humidity module
+
+Connect the Temperature and Humidity module to the ESP32-C6 using one of the FPC ribbon cables that came with the kit. Either FPC connector on the C6 works, top or bottom.
+
+1. Unplug the USB-C cable from the ESP32-C6 so the board is powered off.
+
+ 
+
+2. Flip up the latch on the FPC connector, then gently slide the ribbon cable into the connector. Gently press the latch down to lock it in place.
+
+ 
+
+3. Slide the ribbon cable into the temperature and humidity module with the blue side facing upwards, then press the latch down to lock it in place.
+
+ 
+
+4. Plug the C6 back into your computer.
+
+!!! warning "Handle the FPC connectors gently"
+
+ The latches are small and the ribbon cable is fragile. Lift the latch with a fingernail, slide the cable in, and press the latch down. Never pull on the cable itself.
+
+## Add the sensor in ESPHome Device Builder
+
+ESPHome Device Builder ships an **Add Component** flow that knows the pin layout for every Apollo Starter Kit module. Use it instead of writing the I2C bus and sensor block by hand, and you'll get the right pins, address, and variant on the first try.
+
+1. Open your starter kit device in Device Builder and click **Edit**.
+2. In the ESPHome Device Builder, navigate to the **Components** section.
+3. Click **Add Component** in the editor toolbar.
+4. Search for **Temperature and Humidity** and select the Apollo Starter Kit temperature and humidity component.
+5. Click **Add**. Device Builder inserts the I2C bus into your YAML.
+6. Search for **Temperature and Humidity** again and select the Apollo Starter Kit temperature and humidity component.
+7. Click **Add**. Device Builder inserts the AHT20F sensor block into your YAML.
+
+
+
+??? note "What the temperature and humidity YAML does"
+
+ The blocks Add Component drops into your config look like this.
+
+ ```yaml
+ i2c:
+ sda: GPIO1
+ scl: GPIO0
+ scan: true
+
+ sensor:
+ - platform: aht10
+ variant: AHT20
+ id: aht_20
+ temperature:
+ name: "Temperature"
+ id: aht_temperature
+ humidity:
+ name: "Humidity"
+ id: aht_humidity
+ update_interval: 60s
+ ```
+
+ Each option does something specific.
+
+ | Option | What it does |
+ | --- | --- |
+ | `i2c.sda` / `i2c.scl` | The data and clock pins for the I2C bus the AHT20F speaks on. The starter kit wires them to `GPIO1` and `GPIO0`. |
+ | `i2c.scan: true` | Lists every I2C device the board finds at boot, useful for confirming the sensor is connected. |
+ | `platform: aht10` | The ESPHome platform that drives AHT10, AHT20, and AHT30 sensors. |
+ | `variant: AHT20` | Tells the platform which variant of the chip is connected. |
+ | `id: aht_20` | Internal handle you can reference from automations and lambdas elsewhere in the config. |
+ | `temperature` / `humidity` | Two sub-sensors. Each has a `name` shown in Home Assistant and the web server, and an `id` you can reference from automations and lambdas. |
+ | `update_interval: 60s` | How often the sensor reports. 60 seconds is a reasonable default. Lower it for more responsive readings, raise it to cut down on network traffic. |
+
+## Flash the firmware
+
+Flash the device so the new web server and the temperature and humidity entities go live.
+
+1. Click **Install** on your device card in ESPHome Device Builder.
+2. Choose **Plug into the computer running ESPHome Device Builder** for the first flash, or **On The Network** if the device is already on your Wi-Fi.
+3. Wait for the compile and flash to finish. First builds can take a few minutes.
+4. The device reboots and reconnects to your Wi-Fi on its own.
+
+
+
+## Test temperature and humidity
+
+With the device back online, the temperature and humidity entities are live on the web server. Open it in a browser on the same network and watch them update in real time.
+
+1. In a browser, open `http://.local/`. If you used `esphome-starter-kit` as the device name in [First steps](../setup/first-steps.md), that's `http://esphome-starter-kit.local/`.
+2. Find the **Temperature** and **Humidity** entities in the sensor list.
+3. Watch the values update on the interval you set. Cup your hand over the sensor or breathe on it, and the humidity reading will respond within a few cycles.
+
+
+
+!!! success "Your temperature and humidity module is ready"
+
+ You now have a trustworthy temperature and humidity sensor you can place anywhere in your home.
diff --git a/docs/products/ESPHome-Starter-Kit/setup/first-steps-sg.md b/docs/products/ESPHome-Starter-Kit/setup/first-steps-sg.md
new file mode 100644
index 0000000000..b442ff7d30
--- /dev/null
+++ b/docs/products/ESPHome-Starter-Kit/setup/first-steps-sg.md
@@ -0,0 +1,223 @@
+---
+title: First steps with the ESPHome Starter Kit
+description: Install ESPHome Device Builder, write your first ESPHome config for the starter kit, and flash the ESP32-C6 over USB.
+---
+
+This guide walks you through installing the ESPHome Device Builder app and making your first ESPHome YAML configuration from scratch. By the end, your ESPHome Starter Kit will be flashed with a working configuration, showing up in Home Assistant, and serving a web UI at its IP address or at `esphome-starter-kit.local` in a browser.
+
+## Install ESPHome Device Builder
+
+ESPHome Device Builder is the software that gives you a user interface for writing, compiling, and flashing ESPHome YAML configurations. You'll use it to build the firmware for your kit. Think of it as how you tell the starter kit what is plugged in and what to do with it.
+
+Pick the platform you'll be running ESPHome Device Builder on.
+
+=== "Windows"
+
+ 1. Download the ESPHome Device Builder for Windows.
+ 2. Open the installer and click **Next** then click **Next** again to start the installation process. Once it shows completed, click **Next** again then **Finish** to complete the installation.
+ - If Windows shows a blue **Windows protected your PC** warning, click **More info → Run anyway** to continue.
+
+ 
+
+ 3. Once installed, a web browser should launch and navigate to http://localhost:6052/. When you see this page, your ESPHome Device Builder installation is complete.
+ - Use a Chromium-based browser such as Chrome or Edge. Firefox does not yet support WebSerial, which is required for the initial flashing of the device over USB. If Firefox is your default, copy the URL into Chrome or Edge instead.
+ 4. Navigate to the **system tray** (bottom right of your Windows taskbar). Hover over **Backend** and switch from Classic to the ESPHome Builder Beta with the new layout and features.
+
+ 
+
+ 5. Wait at least 30 seconds, then refresh your browser (F5). You should now see the new ESPHome Device Builder Preview.
+
+ 
+
+=== "Mac"
+
+ 1. Download the ESPHome Device Builder for Mac. Pick the build that matches your chip.
+
+ - Apple Silicon (M1, M2, M3, M4)
+ - Intel Mac
+
+ 2. Open the `.dmg` and drag **ESPHome Builder** into your Applications folder. Launch it from Applications or Spotlight.
+
+ - On first launch, macOS may block the app with a Gatekeeper warning. If that happens, right-click the app in Applications and choose **Open**, then click **Open** in the confirmation dialog. After the first launch, double-click will work normally.
+
+
+
+ 3. Once installed, a web browser should launch and navigate to http://localhost:6052/. When you see this page, your ESPHome Device Builder installation is complete.
+
+ - Use a Chromium-based browser such as Chrome or Edge. Safari and Firefox do not currently support WebSerial, which is required for the initial USB flash.
+
+ 4. Find the **ESPHome Builder** icon in the menu bar (top right of your Mac's screen). Click it, hover over **Backend**, and switch from Classic to the ESPHome Builder Beta.
+
+
+
+ 5. Wait at least 30 seconds, then refresh your browser. You should now see the new ESPHome Device Builder Preview.
+
+=== "Home Assistant App"
+
+ The ESPHome Device Builder runs as a Home Assistant app served right inside your existing HA dashboard. This is the most convenient option if you already run Home Assistant OS or a supervised install.
+
+ **Method 1**
+
+ To add the **ESPHome Device Builder** to your Home Assistant instance, use this My button.
+
+ [](https://my.home-assistant.io/redirect/config_flow_start/?domain=esphome)
+
+ **Method 2**
+
+ 1. In Home Assistant, open **Settings → Apps → App Store**.
+ 2. Search for **ESPHome Device Builder** and click **Install**.
+ 3. Once installed, click **Start**, then **Open Web UI**. The Device Builder will open inside your Home Assistant dashboard.
+
+ !!! info "Already on the new layout"
+
+ The HA app version of Device Builder is already on the new beta backend, so you can skip the backend toggle and browser refresh shown in the desktop tabs.
+
+=== "Linux"
+
+ 1. Download the ESPHome Device Builder for Linux. Pick the package that fits your distro.
+
+ - AppImage (works on any distro)
+ - .deb (Debian / Ubuntu)
+ - .rpm (Fedora / RHEL)
+
+ 2. Install or run the file you downloaded.
+
+ - **AppImage:** `chmod +x ESPHome.Builder_0.7.0_amd64.AppImage` then double-click the file, or run it from a terminal.
+ - **.deb:** `sudo apt install ./ESPHome.Builder_0.7.0_amd64.deb`
+ - **.rpm:** `sudo dnf install ./ESPHome.Builder-0.7.0-1.x86_64.rpm`
+
+
+
+ 3. Once installed, a web browser should launch and navigate to http://localhost:6052/. When you see this page, your ESPHome Device Builder installation is complete.
+
+ - Use a Chromium-based browser such as Chrome or Edge. Firefox does not currently support WebSerial, which is required for the initial USB flash.
+
+ 4. Look for the **ESPHome Builder** icon in your system tray or notification area. Its exact location depends on your desktop environment (top bar on GNOME, system tray on KDE, XFCE, or Cinnamon). Click it, hover over **Backend**, and switch from Classic to the ESPHome Builder Beta.
+
+
+
+ 5. Wait at least 30 seconds, then refresh your browser. You should now see the new ESPHome Device Builder Preview.
+
+## Set up your Wi-Fi credentials
+
+ESPHome stores your Wi-Fi name and password centrally so every device you build picks them up automatically. Fill them in once here.
+
+Enter your Wi-Fi network name (SSID) and Wi-Fi password, then click **Save credentials**. The password is case sensitive, so be careful when entering it.
+
+!!! tip "Secrets folder"
+
+ One popular option is to store your encryption keys here. That way, you can share your full YAML with other users without needing to edit and hide your encryption key. See the [using secrets](../tutorials/using-secrets.md) wiki for step by step directions.
+
+
+
+If you make a mistake or want to change this later, click the 3 dots menu in the top right then select **Secrets**. Click the Eye icon to unhide the Wi-Fi SSID and password, change them, then click **Save** in the bottom right.
+
+!!! success "You're set up"
+
+ You're done with the install guide and ready to build your first device.
+
+## Add a new device
+
+With ESPHome Device Builder installed and your Wi-Fi credentials saved, you can scaffold the starter kit as a new device.
+
+1. Navigate back to the ESPHome Device Builder and click **Add new device** then click **Create new project**.
+
+ 
+
+2. Select the **Apollo ESPHome Starter Kit** and give it a name such as `esphome-starter-kit`, then click **Finish Setup**.
+
+ 
+
+Your starter kit now appears as a device card in the Device Builder dashboard, ready for components.
+
+## Configure components
+
+When you create the device, ESPHome Device Builder seeds it with a list of components under **Core configuration**. You'll add three more for this tutorial.
+
+### Accessory power rail
+
+The accessory power rail is used behind the scenes to give power to your optional modules including the onboard RGB LED.
+
+1. In the ESPHome Device Builder, navigate to the **Components** section.
+2. Click **Add component**.
+3. Scroll to **Accessory Power Rail** and click **Add**.
+4. Click **Add** once more to confirm.
+
+
+
+### Web Server component
+
+The Web Server broadcasts a local website from your device. That lets you navigate to the device's IP address or hostname (for example esphome-starter-kit.local) to control it from any browser on your network.
+
+1. In the ESPHome Device Builder, navigate to the **Core configuration** section.
+2. Click **Add component**.
+3. Scroll to **Web Server** and click **Add**.
+4. Click **Add** once more to confirm.
+5. Toggle **Show advanced settings**.
+6. Scroll down to **Version** and select **3** from the dropdown.
+
+
+
+### Onboard RGB LED
+
+The onboard RGB LED is a small LED above the Reset button on your ESP32-C6 module. It is great for testing automations and doubles as a status light.
+
+1. In the ESPHome Device Builder, navigate to the **Components** section.
+2. Click **Add component**.
+3. Scroll to **Onboard RGB LED** and click **Add**.
+4. Click **Add** once more to confirm.
+
+
+
+## Boot mode
+
+The device must be flashed via USB using bootloader mode the very first time it is used. Once you flash it once, you do not have to repeat these steps.
+
+!!! tip "Use a quality USB-C cable and power source"
+
+ ESP32 boards are sensitive to power. If your device keeps restarting, will not be detected, or will not broadcast its hotspot, try a different USB-C cable or a different USB port. A 5V 1A supply is plenty.
+
+1. Hold the sides of the ESP32-C6 and gently push the USB-C cable firmly into the USB-C port. Plug the other end of the USB-C cable into your computer. Be careful not to snap or damage the FPC ribbon cable connectors located on the sides of the device.
+
+ 
+
+2. Hold down the boot button. While still holding the boot button, press and release the reset button, then release the boot button.
+
+ 
+
+3. Your device is now in boot mode. The board will stay in bootloader mode until you flash it.
+
+## Install firmware
+
+Before you continue, confirm that you have installed ESPHome Device Builder, configured your components, and put your device in boot mode.
+
+1. Click **Save** in the bottom right, which will then show an **Install** button.
+2. Click **Install** in the bottom right.
+3. Click **Plug into this computer**.
+4. Select the COM port, then click **Connect** to connect to the ESP32-C6 module.
+5. Wait for the firmware to compile and install. This usually takes two to five minutes.
+6. Once it completes, click **Stop**, then press the **Reset** button on your device. Your device will reboot and it is now ready to test.
+
+
+
+!!! tip "Click Show details during the install to watch the compile and flash process"
+
+ It is a great way to see what's happening under the hood.
+
+## Test your LED
+
+Above, you installed the `web_server` component, which lets you navigate to the IP address of your device or to the hostname, for example esphome-starter-kit.local.
+
+The page should load and show you the onboard RGB LED. Click the toggle button to make sure the RGB LED turns on and off on your device.
+
+
+
+Here is the light changing colors.
+
+
+
+!!! success "Your starter kit is alive"
+
+ Your ESP32-C6 is on Wi-Fi, in Home Assistant, and serving a web UI you can hit from any browser on your network. From here, every module you add becomes another entity on this same device.
+
+ Back - Start Here Next - Add Button Module
diff --git a/docs/products/ESPHome-Starter-Kit/setup/getting-started-advanced-sg.md b/docs/products/ESPHome-Starter-Kit/setup/getting-started-advanced-sg.md
new file mode 100644
index 0000000000..b5221c7487
--- /dev/null
+++ b/docs/products/ESPHome-Starter-Kit/setup/getting-started-advanced-sg.md
@@ -0,0 +1,280 @@
+---
+title: Getting started with the ESPHome Starter Kit (advanced)
+description: Hand-write your first ESPHome YAML for the starter kit, flash it via Home Assistant, and add it to Home Assistant.
+---
+
+This advanced guide walks through every block of the starter kit's YAML by hand instead of using ESPHome Device Builder's component picker. By the end you'll have your ESPHome Starter Kit flashed with a working configuration and showing up in Home Assistant, with a working web server reachable at its IP address or `hostname.local` in a browser.
+
+If you'd rather have ESPHome Device Builder write the YAML for you, see the [First steps](first-steps.md) guide instead.
+
+## Connect the hardware
+
+The ESP32-C6 is the main board in your kit. It is the small module with the USB-C port on one edge and a row of pin headers along the side. Every project you build with the kit starts here.
+
+### Plug a module into the C6
+
+For your first project, attach the LED & Buzzer module (ten RGB LEDs and a piezo buzzer) to the ESP32-C6 module using the FPC connector and ribbon cable. You can connect to the top or bottom FPC connector. This example uses the top.
+
+### Connect the C6 to your computer
+
+Plug the ESP32-C6 into your computer using a USB-C cable.
+
+!!! tip "First-time flashing"
+
+ The very first time you flash an ESP32-C6, you may need to put it into bootloader mode manually.
+
+ 1. Hold down the **BOOT** button on the C6.
+ 2. While still holding **BOOT**, press and release the **RESET** button.
+ 3. Release the **BOOT** button.
+
+ The board will stay in bootloader mode until you flash it. After the first flash you usually won't need to do this again.
+
+!!! success "Use a quality USB-C cable and power source"
+
+ ESP32 boards are sensitive to power. If your device keeps restarting, will not be detected, or will not broadcast its hotspot, try a different USB-C cable or a different USB port. A 5V 1A supply is plenty.
+
+## Set up ESPHome Device Builder
+
+ESPHome Device Builder is a Home Assistant app that gives you a web UI for writing, compiling, and flashing ESPHome configurations. You'll use it to build the firmware for your kit.
+
+### Install the app
+
+1. In Home Assistant, open **Settings → Apps → App Store**.
+2. Search for **ESPHome Device Builder** and install it.
+3. Once installed, click **Start**, then **Open Web UI**.
+
+If you don't have Home Assistant set up yet, follow the official Home Assistant installation guide first, then come back here.
+
+### Fill in your Wi-Fi secrets
+
+ESPHome keeps your Wi-Fi credentials in a separate `secrets.yaml` file so they aren't pasted into every device config.
+
+1. In the ESPHome Device Builder dashboard, click **Secrets** in the top right.
+2. Add your Wi-Fi name and password.
+
+ ```yaml title="secrets.yaml"
+ # Replace the values inside the quotes with your own Wi-Fi name and password.
+ wifi_ssid: "your-wifi-ssid-here"
+ wifi_password: "your-wifi-password-here"
+ ```
+
+3. Click **Save**.
+
+### Add a new device
+
+1. Click **\+ New Device** in the bottom right of the ESPHome Device Builder dashboard.
+2. Give your device a name (for example `apollo-esk-1`).
+3. When asked for the device type, choose **ESP32-C6**.
+4. ESPHome Device Builder will scaffold a starter YAML for you. Don't flash it yet, you're going to replace it in the next section.
+
+## Write your first ESPHome configuration
+
+ESPHome configs are YAML files. Each top-level block configures a different part of the device. Below is a complete starting config for the kit, broken down section by section. Paste each block into your device's YAML in ESPHome Device Builder as you go, or jump to the [complete configuration](#complete-configuration) at the bottom and paste the whole thing at once.
+
+!!! note "YAML basics"
+
+ YAML uses indentation (spaces, not tabs) to define structure. Two spaces per level is the convention used throughout these examples.
+
+### Substitutions
+
+Substitutions are reusable variables. Define them once at the top of the file and reference them anywhere with `${name}`.
+
+```yaml
+substitutions:
+ name: apollo-esk-1
+ version: "25.5.5.1"
+ device_description: ${name} made by Apollo Automation - version ${version}.
+```
+
+| Variable | Purpose |
+| --- | --- |
+| `name` | Device identifier used in ESPHome and Home Assistant. |
+| `version` | Track your firmware version. The convention used here is Year.Month.Day.Build. |
+| `device_description` | Human-readable description. Notice that it references other substitutions with `${}`. |
+
+### Core ESPHome configuration
+
+This block tells ESPHome how the device should appear in the dashboard and in Home Assistant.
+
+```yaml
+esphome:
+ name: "${name}"
+ friendly_name: Apollo ESPHome Starter Kit
+ comment: ${device_description}
+ name_add_mac_suffix: true
+ platformio_options:
+ board_build.flash_mode: dio
+ project:
+ name: "ApolloAutomation.ESK-1"
+ version: "${version}"
+ min_version: 2024.6.0
+```
+
+| Option | Description |
+| --- | --- |
+| `name` | Internal device name, pulled from substitutions. |
+| `friendly_name` | The name shown in Home Assistant's UI. |
+| `name_add_mac_suffix` | Appends part of the MAC address to the name, useful when you flash more than one device. |
+| `platformio_options` | Low-level build settings. `dio` flash mode is what the ESP32-C6 expects. |
+| `project` | Identifies this as an Apollo Automation project. |
+| `min_version` | Refuses to compile on ESPHome versions older than this. |
+
+### ESP32 board
+
+Tell ESPHome which chip you're targeting.
+
+```yaml
+esp32:
+ board: esp32-c6-devkitm-1
+ variant: esp32c6
+ flash_size: 8MB
+ framework:
+ type: esp-idf
+```
+
+!!! warning "ESP32-C6 needs the ESP-IDF framework"
+
+ The older Arduino framework does not fully support the C6. Stick with `esp-idf` here.
+
+### Home Assistant API
+
+One line enables the native Home Assistant API connection. ESPHome handles the encryption and discovery for you.
+
+```yaml
+api:
+```
+
+### Wi-Fi
+
+This block uses the secrets you saved earlier and sets up a fallback hotspot in case the device cannot reach your Wi-Fi.
+
+```yaml
+wifi:
+ ssid: !secret wifi_ssid
+ password: !secret wifi_password
+
+ ap:
+ ssid: "Apollo ESK-1 Hotspot"
+```
+
+If the device cannot connect to your Wi-Fi at boot, it will broadcast its own network called **Apollo ESK-1 Hotspot**. You can join that network from your phone or laptop to fix the credentials.
+
+### Captive portal
+
+Pairs with the fallback hotspot to give you a web page for entering Wi-Fi details when you connect to the hotspot.
+
+```yaml
+captive_portal:
+```
+
+### Logger
+
+Enables ESPHome's logging output. You'll see these logs in the ESPHome Device Builder dashboard when viewing the device, and they're invaluable for debugging.
+
+```yaml
+logger:
+```
+
+### Binary sensors
+
+Binary sensors report on or off state. The first one tracks whether the device is connected to Home Assistant. The second exposes a GPIO pin so you can wire up the button module or any other digital input.
+
+```yaml
+binary_sensor:
+ - platform: status
+ name: Online
+ id: ha_connected
+
+ - platform: gpio
+ pin:
+ number: GPIO9
+ inverted: true
+ mode:
+ input: true
+ pullup: true
+ id: my_button
+ name: "Button"
+```
+
+| Option | Description |
+| --- | --- |
+| `platform: status` | Reports the HA connection state. Useful for automations that check device availability. |
+| `platform: gpio` | A simple digital input. |
+| `number: GPIO9` | The physical pin you've wired the input to. |
+| `inverted: true` | The pin reads LOW when the button is pressed (active-low). |
+| `pullup: true` | Enables the C6's internal pull-up resistor so the pin doesn't float. |
+
+### Complete configuration
+
+```yaml title="apollo-esk-1.yaml"
+substitutions:
+ name: apollo-esk-1
+ version: "25.5.5.1"
+ device_description: ${name} made by Apollo Automation - version ${version}.
+
+esphome:
+ name: "${name}"
+ friendly_name: Apollo ESPHome Starter Kit
+ comment: ${device_description}
+ name_add_mac_suffix: true
+ platformio_options:
+ board_build.flash_mode: dio
+ project:
+ name: "ApolloAutomation.ESK-1"
+ version: "${version}"
+ min_version: 2024.6.0
+
+esp32:
+ board: esp32-c6-devkitm-1
+ variant: esp32c6
+ flash_size: 8MB
+ framework:
+ type: esp-idf
+
+api:
+
+wifi:
+ ssid: !secret wifi_ssid
+ password: !secret wifi_password
+ ap:
+ ssid: "Apollo ESK-1 Hotspot"
+
+captive_portal:
+
+logger:
+
+binary_sensor:
+ - platform: status
+ name: Online
+ id: ha_connected
+
+ - platform: gpio
+ pin:
+ number: GPIO9
+ inverted: true
+ mode:
+ input: true
+ pullup: true
+ id: my_button
+ name: "Button"
+```
+
+## Flash and add to Home Assistant
+
+With your YAML written, flash the device and finish the handoff to Home Assistant.
+
+1. In ESPHome Device Builder, click **Install** on your device.
+2. Choose **Plug into the computer running ESPHome Dashboard** (or **Wirelessly** if you're updating an already-flashed device).
+3. Wait for the compile and flash to finish. The first compile can take several minutes.
+4. Once it's done, the device will reboot and connect to your Wi-Fi.
+5. In Home Assistant, go to **Settings → Devices & Services**. Your new device should appear under **Discovered**. Click **Add**, pick an area, and finish.
+
+!!! success "You did it"
+
+ Your ESP32-C6 is now running ESPHome and showing up in Home Assistant. You've written your first ESPHome configuration from scratch.
+
+## Next steps
+
+- Add more sensors and modules to your YAML and re-flash to expand the device.
+- Browse [Apollo's other product wikis](https://wiki.apolloautomation.com) for more advanced ESPHome examples.
+- Join the [Apollo Discord](https://link.apolloautomation.com/discord) to share what you build.
diff --git a/docs/products/ESPHome-Starter-Kit/start-here-sg.md b/docs/products/ESPHome-Starter-Kit/start-here-sg.md
new file mode 100644
index 0000000000..b24d99efa7
--- /dev/null
+++ b/docs/products/ESPHome-Starter-Kit/start-here-sg.md
@@ -0,0 +1,78 @@
+---
+title: ESPHome Starter Kit, start here
+description: Unbox the ESPHome Starter Kit, snap the modules off the panel, and meet every part of your kit before you wire it up.
+---
+
+Welcome to the start of your ESPHome ecosystem journey with the **Apollo ESPHome Starter Kit**.
+
+
+
+By the end of this page you will know how to safely separate the modules from the panel, and recognise each part of the kit so the rest of the guides make sense.
+
+## What's in the kit
+
+Your kit arrives as a single snap-apart panel that includes the ESP32-C6 main board along with a selection of interchangeable modules. The kit also includes three ribbon cables used to connect the modules together, and a stand for the LED & Buzzer module.
+
+
+
+## Snapping the panel apart
+
+Each module is connected to the panel by small breakaway tabs. Follow the steps below to separate them, step by step.
+
+!!! success "Take it slow"
+
+ Bend the panel gradually, not all at once. The PCB is sturdy, but the components on the modules prefer a gentle snap.
+
+1. Hold the panel flat on a table with one hand on the module you want to remove.
+2. Gently flex the panel along the tab line until the tab snaps cleanly.
+
+
+
+Once every module is off the panel, lay them out so you can see what you have before plugging anything in.
+
+## Meet the modules
+
+### ESP32-C6 main board
+
+The brain of every project you'll build with the kit. It handles Wi-Fi and Bluetooth, runs your ESPHome config, and exposes the GPIO pins the modules plug into.
+
+
+
+### LED & Buzzer module
+
+The starter kit's notification module, a strip of ten addressable RGB LEDs and a small piezo buzzer behind the ESPHome logo silkscreen. Use the included stand to show it off on a shelf or desk.
+
+
+
+### Motion module
+
+Detects movement in a room, and a great way to get started automating your home. It ships in two parts so the PIR dome can be packed safely, then plugs into the PIR module board.
+
+
+
+### Button module
+
+Premium feel button perfect for triggering automations for lights, scenes, and more.
+
+
+
+### Temperature and humidity module
+
+Accurate temperature and humidity sensor, trustworthy enough to track room comfort levels with ease.
+
+
+
+### FPC cables
+
+Each module connects to the main board through an FPC connector using one of the three provided cables. Tear the brown paper bag open from one of the ends. Do not use scissors, you could accidentally cut the cables.
+
+
+
+## Next, bring it online
+
+Once you have identified your modules and snapped them off the panel, the next step is to connect the main board to your computer and walk through your first ESPHome configuration.
+
+ Next - First Steps
diff --git a/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets-sg.md b/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets-sg.md
new file mode 100644
index 0000000000..c6acd522ee
--- /dev/null
+++ b/docs/products/ESPHome-Starter-Kit/tutorials/using-secrets-sg.md
@@ -0,0 +1,183 @@
+---
+title: Using secrets.yaml
+description: Store API encryption keys, OTA passwords, MQTT credentials, and more in a single secrets.yaml file so they stay out of your device configs.
+---
+
+In [First steps](../setup/first-steps.md) you saved your Wi-Fi name and password in `secrets.yaml`. That same file can hold every other sensitive value your device needs, from your Home Assistant API key to your MQTT password. This tutorial walks through what to put in there and how to reference it from your device YAML.
+
+## What secrets.yaml is
+
+`secrets.yaml` is a single file in ESPHome Device Builder that stores values you don't want pasted into every device config. Two reasons to use it.
+
+- **Safety.** You can copy a device YAML to a friend, paste it in a forum, or commit it to a public repo without leaking your Wi-Fi password or API key.
+- **One place to change things.** Rotate a password once in `secrets.yaml` and every device that references it picks up the new value on the next flash.
+
+`secrets.yaml` lives inside ESPHome Device Builder, so the same secrets are available to every device you build there.
+
+## Open Secrets
+
+In the ESPHome Device Builder dashboard, click the 3 dots menu in the top right then **Secrets**.
+
+
+
+You'll see a YAML file with one key per line. If you followed First steps you should already see `wifi_ssid` and `wifi_password` here.
+
+
+
+## Syntax
+
+Each entry is a `key: "value"` pair.
+
+```yaml title="secrets.yaml"
+my_secret_name: "the value goes here"
+```
+
+In your device YAML, reference it with `!secret` followed by the key name.
+
+```yaml
+some_option: !secret my_secret_name
+```
+
+When the device compiles, ESPHome substitutes the value from `secrets.yaml` in place of the `!secret` tag.
+
+!!! warning "The key has to exist"
+
+ If you reference `!secret some_name` in a device config but `some_name` isn't defined in `secrets.yaml`, the build will fail. Spelling counts.
+
+## What to store
+
+Each section below shows the line you add to `secrets.yaml` and the line in your device YAML that references it.
+
+### Wi-Fi credentials
+
+You set these up in [First steps](../setup/first-steps.md). They're the baseline every device needs.
+
+```yaml title="secrets.yaml"
+wifi_ssid: "your-wifi-ssid-here"
+wifi_password: "your-wifi-password-here"
+```
+
+```yaml title="device.yaml"
+wifi:
+ ssid: !secret wifi_ssid
+ password: !secret wifi_password
+```
+
+### Fallback hotspot password
+
+If you want the device's fallback hotspot to require a password instead of being open, store that here too.
+
+```yaml title="secrets.yaml"
+ap_password: "fallback-hotspot-password"
+```
+
+```yaml title="device.yaml"
+wifi:
+ ssid: !secret wifi_ssid
+ password: !secret wifi_password
+ ap:
+ ssid: "Apollo ESK-1 Hotspot"
+ password: !secret ap_password
+```
+
+### Home Assistant API encryption key
+
+ESPHome encrypts the connection between your device and Home Assistant. The key is a 32-byte base64 string. The most convenient way to get one is to let ESPHome Device Builder generate it for you when you first add the `api:` block, then copy that value into `secrets.yaml`.
+
+```yaml title="secrets.yaml"
+api_encryption_key: "your-32-byte-base64-key-here"
+```
+
+```yaml title="device.yaml"
+api:
+ encryption:
+ key: !secret api_encryption_key
+```
+
+!!! tip "Reuse the same key across devices"
+
+ Using the same `api_encryption_key` for every Apollo device on your network is fine, and it keeps your secrets file short. Home Assistant prompts for the key the first time it discovers a device, then remembers it.
+
+### OTA password
+
+OTA (over-the-air) updates let you re-flash a device wirelessly after the first USB flash. The password protects that endpoint so a stranger on your network can't push firmware to your device.
+
+```yaml title="secrets.yaml"
+ota_password: "a-long-random-string"
+```
+
+```yaml title="device.yaml"
+ota:
+ - platform: esphome
+ password: !secret ota_password
+```
+
+### Web server username and password
+
+If you enable the optional `web_server:` component to access your device at `http://device-name.local/`, you can require a login.
+
+```yaml title="secrets.yaml"
+web_server_username: "admin"
+web_server_password: "a-strong-password"
+```
+
+```yaml title="device.yaml"
+web_server:
+ port: 80
+ auth:
+ username: !secret web_server_username
+ password: !secret web_server_password
+```
+
+### MQTT broker, username, and password
+
+If you publish to an MQTT broker instead of (or in addition to) the Home Assistant API, all three of these belong in `secrets.yaml`.
+
+```yaml title="secrets.yaml"
+mqtt_broker: "192.168.1.50"
+mqtt_username: "esphome"
+mqtt_password: "broker-password"
+```
+
+```yaml title="device.yaml"
+mqtt:
+ broker: !secret mqtt_broker
+ username: !secret mqtt_username
+ password: !secret mqtt_password
+```
+
+## Complete example
+
+Putting it all together, a fully loaded `secrets.yaml` looks like this.
+
+```yaml title="secrets.yaml"
+# Wi-Fi
+wifi_ssid: "your-wifi-ssid-here"
+wifi_password: "your-wifi-password-here"
+ap_password: "fallback-hotspot-password"
+
+# Home Assistant API
+api_encryption_key: "your-32-byte-base64-key-here"
+
+# OTA updates
+ota_password: "a-long-random-string"
+
+# Web server auth
+web_server_username: "admin"
+web_server_password: "a-strong-password"
+
+# MQTT
+mqtt_broker: "192.168.1.50"
+mqtt_username: "esphome"
+mqtt_password: "broker-password"
+```
+
+You don't have to include every entry. If a device doesn't use MQTT, leave those lines out (or leave them in for the next device, the unused ones are harmless).
+
+## Good practice
+
+!!! info "Treat secrets.yaml like a password manager"
+
+ - Don't share or post the file. Share device YAMLs instead, the `!secret` references are safe.
+ - Keep a backup somewhere safe (a password manager works well). If you reinstall ESPHome Device Builder you'll need to recreate it.
+ - Rotating a credential is a one-line edit here, then re-flash anything that uses it.
Back - Start Here