Add Learn the Basics section to ESPHome Starter Kit docs

docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md

@@ -0,0 +1,48 @@
+---
+title: Explaining ESPHome
+description: A short overview of what ESPHome is, how the Device Builder app fits in, and why the ESPHome Starter Kit is built on it.
+---
+# Explaining ESPHome
+
+ESPHome is the open-source firmware project that powers your Apollo ESPHome Starter Kit. You describe what is connected to your board (a button, a sensor, an LED) and ESPHome runs on the device, exposes those parts to Home Assistant, and accepts updates over the network.
+
+You do not need to write any code to use it. For the Starter Kit, the **ESPHome Device Builder** app does the work for you.
+
+## ESPHome vs ESPHome Device Builder
+
+These two names get used interchangeably, but they are different pieces:
+
+- **ESPHome** is the software that runs on your device after it has been flashed. It is what makes your board talk to Home Assistant, expose its sensors and controls, and accept wireless updates.
+- **ESPHome Device Builder** is the app you set everything up in. You pick the components you want (button, LED, sensor, etc.), click **Install**, and the Builder compiles the firmware and flashes it to your device for you. You can run it as a desktop app on Windows, Mac, or Linux, or install it as a Home Assistant app.
+
+For the Starter Kit, you will spend almost all your time in the Device Builder.
+
+## How you talk to your device
+
+Once your device is flashed, there are two ways to interact with it.
+
+#### From any web browser
+
+ESPHome's built-in **Web Server** component (the Starter Kit's First Steps walks you through adding it) makes your device serve its own local web page. Open `esphome-starter-kit.local` or its IP address in any browser on your network, on a phone or PC, and you can toggle the LED, view sensor readings, and control everything directly. No Home Assistant required.
+
+#### From Home Assistant
+
+Home Assistant discovers your device automatically through the **ESPHome integration**. This surfaces your device's sensors, switches, and lights as entities you can use in dashboards and automations.
+
+A typical flow looks like this:
+
+1. In **ESPHome Device Builder**, click **Add component** and pick what is connected to your device. No code or YAML required to get started.
+2. Click **Install** to flash the firmware to the device. USB the first time, then wirelessly after that.
+3. Home Assistant picks up the device through the **ESPHome integration** and shows its sensors, buttons, and lights as entities you can control or automate.
+
+If you ever want to fine-tune something the GUI does not expose, the YAML view is always available. It is an option, not a requirement.
+
+## Why the Starter Kit is built on ESPHome
+
+ESPHome is part of the **ESPHome ecosystem**, an open-source project with a large community of contributors and direct first-class support in Home Assistant. Apollo builds on **open standards**: public protocols like ESPHome and OpenThread, so your kit is never locked to one vendor. Everything you set up runs under **local control**: your home runs on your own network, and your devices keep working even if your internet goes down or Apollo goes away.
+
+You get wireless updates, a built-in web page for controlling your device, and direct Home Assistant integration without writing any code. The skills you build on the Starter Kit carry over to any ESPHome project you take on later.
+
+The official ESPHome documentation covers every component, configuration option, and advanced topic in detail.
+
+<a href="https://esphome.io/" target="_blank" rel="noreferrer nofollow noopener" class="md-button md-button--primary"><img src="/assets/esphome-logo.svg" /> Visit esphome.io</a> <a href="../../setup/first-steps/" class="md-button md-button--primary"><img src="/assets/esphome-logo.svg" /> Back to First Steps</a>

docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-secrets-yaml.md

@@ -0,0 +1,40 @@
+---
+title: What is secrets.yaml?
+description: A short overview of what secrets.yaml is, what it stores, and why ESPHome uses it.
+---
+# What is secrets.yaml?
+
+secrets.yaml is a single file inside **ESPHome Device Builder** that stores values you don't want pasted into every device config: your Wi-Fi password, your Home Assistant API key, OTA passwords, MQTT credentials, and so on.
+
+You define each value once in secrets.yaml, then reference it from your device YAML using `!secret`:
+
+```yaml
+wifi:
+  ssid: !secret wifi_ssid
+  password: !secret wifi_password
+```
+
+When the device compiles, ESPHome substitutes the real value in place of the `!secret` tag.
+
+## Why it exists
+
+There are two reasons to use secrets.yaml:
+
+- **Safety.** You can copy a device YAML to a friend, paste it on a forum, or commit it to a public repo without leaking your Wi-Fi password or API key. The `!secret` references are safe to share. The values they point to never leave your Device Builder.
+- **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.
+
+## How it fits in
+
+secrets.yaml lives inside **ESPHome Device Builder**, not on the device itself. The same secrets file is available to every device you build there. A device only ever sees the substituted values baked into its firmware, not the secrets.yaml file.
+
+## Good practice
+
+Treat secrets.yaml like a password manager entry:
+
+- Don't share or post the file. Share your device YAMLs instead, since the `!secret` references in them are safe.
+- Keep a backup somewhere safe (a password manager works well). If you reinstall ESPHome Device Builder, you will need to recreate it.
+- Rotating a credential is a one-line edit here, then re-flash anything that uses it.
+
+Ready to put this into practice? The Using Secrets tutorial walks through opening secrets.yaml in the Device Builder, the `!secret` syntax, and what to store for every common case (Wi-Fi, Home Assistant API, OTA, web server auth, MQTT).
+
+<a href="../../tutorials/using-secrets/" class="md-button md-button--primary"><img src="/assets/esphome-logo.svg" /> Using Secrets tutorial</a> <a href="../../setup/first-steps/" class="md-button md-button--primary"><img src="/assets/esphome-logo.svg" /> Back to First Steps</a>

docs/products/ESPHome-Starter-Kit/learning-the-basics/what-is-yaml.md

@@ -0,0 +1,94 @@
+---
+title: What is YAML?
+description: A short primer on YAML, the configuration format ESPHome uses, with examples drawn from the ESPHome Starter Kit.
+---
+# What is YAML?
+
+YAML is a plain-text format used to describe configuration in a way that is readable for both people and computers. ESPHome uses YAML to describe what your device is and what it should do.
+
+You do not have to write YAML yourself when using the **ESPHome Device Builder**. The Builder generates it for you as you click around. Recognising what you are looking at when you peek at the YAML view helps you understand what your device is doing, and a little YAML opens up advanced settings the GUI does not expose.
+
+## The basics
+
+YAML is built from three ideas: key-value pairs, indentation, and lists.
+
+#### Key and value
+
+Most lines are a name, a colon, then a value:
+
+```yaml
+name: esphome-starter-kit
+platform: ESP32
+```
+
+#### Indentation groups things together
+
+Indentation, always with spaces and never tabs, shows which settings belong to which item:
+
+```yaml
+wifi:
+  ssid: my-wifi-network
+  password: my-wifi-password
+```
+
+Here, `ssid` and `password` belong to `wifi`. The two spaces in front are what links them.
+
+#### Lists use dashes
+
+A dash at the start of a line means "this is one item in a list":
+
+```yaml
+sensor:
+  - platform: dht
+    pin: GPIO4
+  - platform: dht
+    pin: GPIO5
+```
+
+That is two sensors, each with its own settings.
+
+#### Comments
+
+A `#` starts a comment. Anything after it on that line is ignored, which makes it useful for leaving yourself notes:
+
+```yaml
+# Built-in LED on the ESP32-C6
+light:
+  - platform: esp32_rmt_led_strip
+    pin: GPIO8
+```
+
+#### Quoting strings
+
+Most text values do not need quotes. You only need quotes if your value contains special characters, starts with a number, or could be confused for something else (like the word `yes` or `no`). When in doubt, quotes are always safe:
+
+```yaml
+wifi_password: "my-password-with-spaces and symbols!"
+```
+
+#### Common gotchas
+
+A few small things trip people up when they start hand-editing YAML. Each of these will cause the Device Builder to refuse to save or compile, so spotting them early saves frustration.
+
+- **Indentation must be spaces, not tabs.** Most editors handle this, but if you paste from somewhere else and get errors, this is the first thing to check.
+- **Be consistent with your indent size.** Two spaces per level is the convention used throughout ESPHome examples.
+- **The colon after a key needs a space.** `name: esphome-starter-kit` works; `name:esphome-starter-kit` does not.
+
+## What this looks like in ESPHome
+
+When you add the Onboard RGB LED component in the Device Builder, the YAML view shows something like this:
+
+```yaml
+light:
+  - platform: esp32_rmt_led_strip
+    name: Onboard RGB LED
+    pin: GPIO8
+    num_leds: 1
+    chipset: WS2812
+```
+
+You did not type any of that. The Builder wrote it when you clicked **Add**. Once you can read it, you know exactly what your device is doing.
+
+The official YAML site has the full specification, and the ESPHome docs walk through YAML in the context of ESPHome specifically.
+
+<a href="https://yaml.org/" target="_blank" rel="noreferrer nofollow noopener" class="md-button md-button--primary">YAML official site</a> <a href="https://esphome.io/guides/configuration-types.html" target="_blank" rel="noreferrer nofollow noopener" class="md-button md-button--primary"><img src="/assets/esphome-logo.svg" /> ESPHome YAML guide</a> <a href="../../setup/first-steps/" class="md-button md-button--primary"><img src="/assets/esphome-logo.svg" /> Back to First Steps</a>

docs/products/ESPHome-Starter-Kit/setup/first-steps.md

@@ -16,6 +16,8 @@ ESPHome Device Builder is the software that gives you a user interface for writi
 
 Think of it like telling the starter kit about what devices it has connected and how to use them!
 
+<a href="../learning-the-basics/explaining-esphome/" class="md-button md-button--primary"><img src="/assets/esphome-logo.svg" /> Learn more about ESPHome</a>
+
 Pick the platform you'll be running ESPHome Device Builder on:
 
 === "Windows"

docs/products/ESPHome-Starter-Kit/tutorials/using-secrets.md

@@ -8,16 +8,9 @@ description: >-
 
 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.
+!!! info "New to secrets.yaml?"
 
-secrets.yaml lives inside ESPHome Device Builder, so the same secrets are available to every device you build there.
+    Read [What is secrets.yaml?](../learning-the-basics/what-is-secrets-yaml.md) first for a quick conceptual overview, then come back here when you're ready to set yours up.
 
 ---
 

mkdocs.yml

@@ -511,6 +511,10 @@ nav:
               - LED & Buzzer: products/ESPHome-Starter-Kit/modules/rgb-buzzer-module.md
           - Tutorials:
               - Using Secrets: products/ESPHome-Starter-Kit/tutorials/using-secrets.md
+          - Learn the Basics:
+              - Explaining ESPHome: products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md
+              - What is YAML?: products/ESPHome-Starter-Kit/learning-the-basics/what-is-yaml.md
+              - What is secrets.yaml?: products/ESPHome-Starter-Kit/learning-the-basics/what-is-secrets-yaml.md
       - Holiday Ornaments:
           - H-1:
               - Introduction: products/h1/introduction.md