docs: add Connect to Home Assistant tutorial + HA Integration Learn the Basics page

[bharvey88]

What does this implement/fix?

Two new Starter Kit pages covering how the device shows up in Home Assistant, plus a few touch-ups to existing pages:

New pages:

• tutorials/connect-to-home-assistant.md ("Connect to Home Assistant"): step-by-step for accepting the device into Home Assistant, confirming entities, and a short troubleshooting section.
• learning-the-basics/how-esphome-talks-to-home-assistant.md ("HA Integration" in the nav): conceptual companion covering auto-discovery, the encryption key, how components become entities, and how the on-device web page coexists with Home Assistant. Network edge cases collapsed into a single admonition that links to the UniFi mDNS troubleshooting guide.

Both pages use my.home-assistant.io My redirect links and badges for any "open X in Home Assistant" reference, so readers land at the right spot in their own instance without manual navigation.

Touch-ups:

• setup/first-steps.md footer: three buttons (Back - Start Here, Add More Modules, Connect to Home Assistant).
• learning-the-basics/explaining-esphome.md: cross-link to the new HA Integration page from the "From Home Assistant" subsection, and link the on-device web page hostname so readers can click straight to it. Same actionable-URL fix on the new HA Integration page.

Types of changes

• Typo / wording fix
• Content update (correcting outdated info, adding missing steps, clarifications)
• New page or new product section
• Page move / rename (redirect added in mkdocs.yml)
• Image / screenshot update
• Nav / structure change
• Site config or theme change
• CI / workflows / dependencies — Does not publish

Checklist:

• This PR targets the dev branch (not main)
• Changes previewed locally with mkdocs serve
• If pages were moved or renamed, redirects were added to mkdocs.yml
• If new pages were added, nav was updated in mkdocs.yml

Summary by CodeRabbit

• Documentation
  • Added comprehensive guide for connecting the ESPHome Starter Kit to Home Assistant, including device discovery and troubleshooting steps.
  • New documentation explaining how ESPHome integrates with Home Assistant, including auto-discovery, encryption setup, and entity mapping.
  • Enhanced navigation and cross-references throughout learning materials for improved user flow.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 706e076c-cec2-4125-8bbe-6ac2816b8001

📥 Commits

Reviewing files that changed from the base of the PR and between 0ead41d and 1878ecf.

📒 Files selected for processing (5)

• docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md
• docs/products/ESPHome-Starter-Kit/learning-the-basics/how-esphome-talks-to-home-assistant.md
• docs/products/ESPHome-Starter-Kit/setup/first-steps.md
• docs/products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md
• mkdocs.yml

---

Walkthrough

This PR extends the ESPHome Starter Kit documentation with new learning and tutorial content focused on Home Assistant integration. It adds two new pages explaining how the device connects to Home Assistant and walking users through the setup process, updates navigation across existing docs to surface these resources, and wires them into the site's documentation structure.

Changes

Home Assistant Integration Documentation

Layer / File(s)	Summary
HA Integration learning page docs/products/ESPHome-Starter-Kit/learning-the-basics/how-esphome-talks-to-home-assistant.md	New page explaining ESPHome-to-Home Assistant integration mechanics: auto-discovery via mDNS, encryption with api_encryption_key, component-to-entity mapping, dual control paths, mDNS troubleshooting, and navigation references.
Connect to Home Assistant tutorial docs/products/ESPHome-Starter-Kit/tutorials/connect-to-home-assistant.md	New step-by-step tutorial covering prerequisites, device discovery, encryption key entry, optional Area selection, entity verification, two-way control testing, troubleshooting for discovery and encryption issues, and back-navigation.
Navigation and cross-document updates docs/products/ESPHome-Starter-Kit/learning-the-basics/explaining-esphome.md, docs/products/ESPHome-Starter-Kit/setup/first-steps.md, mkdocs.yml	Updated Web Server instructions and HA integration links in explaining-esphome.md; expanded first-steps.md navigation from single "Next - Add Button Module" button to three buttons including "Connect to Home Assistant"; registered new tutorial and learning pages in mkdocs.yml nav structure.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• ApolloAutomation/docs#833: Updates the ESPHome Starter Kit "Learn the Basics/First Steps" documentation around the built-in Web Server setup narrative and core-components links.
• ApolloAutomation/docs#842: Modifies first-steps.md navigation and UI/link updates for Learn the Basics and Configure Components guidance.
• ApolloAutomation/docs#823: Updates the same "Controlling your device" section in explaining-esphome.md, adjusting Web Server instructions and heading organization.

Poem

🐰 A starter kit finds its way back home,
Through mDNS magic and secrets to roam.
With docs now as guides—both learning and how—
Users can connect and light up their brow! ✨

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/connect-to-home-assistant

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}