Shorten Learn the Basics sidebar headings

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

@@ -8,7 +8,7 @@ ESPHome is the open-source firmware project that powers your Apollo ESPHome Star
 
 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
+## ESPHome vs Device Builder
 
 These two names get used interchangeably, but they are different pieces:
 
@@ -17,7 +17,7 @@ These two names get used interchangeably, but they are different pieces:
 
 For the Starter Kit, you will spend almost all your time in the Device Builder.
 
-## How you talk to your device
+## Controlling your device
 
 Once your device is flashed, there are two ways to interact with it.
 
@@ -27,7 +27,7 @@ ESPHome's built-in **Web Server** component (the Starter Kit's First Steps walks
 
 #### 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.
+Home Assistant discovers your device automatically through the **ESPHome integration**. Each of your device's sensors, switches, and lights then appears in Home Assistant as an entity you can use in dashboards and automations.
 
 A typical flow looks like this:
 
@@ -37,12 +37,12 @@ A typical flow looks like this:
 
 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
+## Why 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>
+<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>

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

@@ -37,4 +37,4 @@ Treat secrets.yaml like a password manager entry:
 
 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>
+<a href="../../tutorials/using-secrets/" class="md-button md-button--primary"><img src="/assets/esphome-logo.svg" /> Using Secrets tutorial</a>

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

@@ -23,7 +23,7 @@ platform: ESP32
 
 #### Indentation groups things together
 
-Indentation, always with spaces and never tabs, shows which settings belong to which item:
+Indentation shows which settings belong to which item:
 
 ```yaml
 wifi:
@@ -66,15 +66,41 @@ Most text values do not need quotes. You only need quotes if your value contains
 wifi_password: "my-password-with-spaces and symbols!"
 ```
 
-#### Common gotchas
+## Spacing matters
 
-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.
+YAML uses indentation to figure out which settings belong to which item. Get the spacing wrong and the Device Builder will refuse to save or compile. Three rules cover almost every mistake.
 
-- **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.
+**Use spaces, never tabs.** Tabs and spaces look the same on screen, but a YAML parser treats them differently. Most editors handle this for you, but if you paste YAML from somewhere else and get errors, tabs are the first thing to check for.
 
-## What this looks like in ESPHome
+**Two spaces per level, consistently.** Every level of nesting is two more spaces than the parent. The number doesn't strictly have to be two, but it has to stay the same across the whole file. Mixing two-space and four-space indents in one file will fail.
+
+**A space after every colon.** `name: esphome-starter-kit` works. `name:esphome-starter-kit` does not. The parser uses the colon-plus-space to separate keys from values.
+
+A correct example, with the indent levels visible:
+
+```yaml
+wifi:                    # top level
+  ssid: my-network       # two spaces in, belongs to wifi
+  password: my-pass      # two spaces in, belongs to wifi
+  ap:                    # two spaces in, belongs to wifi
+    ssid: Fallback       # four spaces in, belongs to ap
+```
+
+And the same content with broken indentation, which will fail to compile:
+
+```yaml
+wifi:
+ssid: my-network         # no indent, no longer part of wifi
+  password: my-pass
+   ap:                   # three spaces, doesn't match siblings
+    ssid: Fallback
+```
+
+!!! tip "Back up before you edit"
+
+    Before hand-editing YAML in the Device Builder, copy the current contents into a notepad or text file as a safety net. If a misplaced indent breaks the build, you can paste the original back and start over.
+
+## ESPHome example
 
 When you add the Onboard RGB LED component in the Device Builder, the YAML view shows something like this:
 
@@ -91,4 +117,4 @@ You did not type any of that. The Builder wrote it when you clicked **Add**. Onc
 
 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>
+<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>