ApolloAutomation · bharvey88 · Jun 3, 2026 · Jun 3, 2026
diff --git a/AGENTS.md b/AGENTS.md
@@ -36,6 +36,12 @@ Read the full style guide, but these are the ones worth checking twice:
   with framing copy (what the reader unlocks, what success looks like).
 - Avoid corporate filler: **simply**, **just**, **easy**, **powerful**,
   **seamlessly**.
+- Automation pages must carry a difficulty pill under the H1
+  (`<span class="difficulty lvl-N">Difficulty: Level N · Word</span>`,
+  Level 1 Starter to Level 5 Pro). On Moderate-and-up pages, add a
+  same-product stepping-stone box linking easier automations. Pill and
+  box styles live in `docs/stylesheets/extra.css`; never inline colors.
+  See [Automation difficulty](STYLE_GUIDE.md#10-automation-difficulty).
 
 ## Keep the style guide current
 

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -78,6 +78,7 @@ The full writing and formatting rules live in [STYLE_GUIDE.md](STYLE_GUIDE.md).
 - **Terminology**: Apollo hardware **addons** and Home Assistant software **apps** are different things; use each in its own context.
 - **ESPHome** is the only correct casing.
 - **No em dashes** anywhere in user-facing copy.
+- **Automation pages** carry a difficulty pill (`Level 1 Starter` to `Level 5 Pro`) under the title; harder pages can link easier ones in a stepping-stone box. See [Automation difficulty](STYLE_GUIDE.md#10-automation-difficulty).
 
 Mechanical conventions:
 - MkDocs Material: see https://squidfunk.github.io/mkdocs-material/ for admonitions, tabs, and content tabs syntax

diff --git a/STYLE_GUIDE.md b/STYLE_GUIDE.md
@@ -401,7 +401,56 @@ how `docs/assets/` is organised), see
 
 ---
 
-## 10. When in doubt
+## 10. Automation difficulty
+
+Every automation page carries a difficulty pill directly under the H1 so
+readers can gauge how involved the setup is. The rating is about **setup
+difficulty and skill** (steps, helpers, templating, integrations), not
+runtime load.
+
+| Level | Word | Use it when the automation... |
+| --- | --- | --- |
+| 1 | Starter | is plug-and-play: toggle one entity, no helpers. |
+| 2 | Easy | needs a helper or two and a few guided steps. |
+| 3 | Moderate | combines several entities, conditions, or a template. |
+| 4 | Advanced | needs templating, blueprints, or multi-device logic. |
+| 5 | Pro | is complex multi-device or heavily custom. |
+
+Add the pill as the first line under the title. The `lvl-N` class sets the
+color (green at 1 to red at 5):
+
+```html
+# Build a Button-Controlled RGB Light
+
+<span class="difficulty lvl-2">Difficulty: Level 2 · Easy</span>
+```
+
+### Stepping-stone box
+
+On a harder page, point newcomers at one to three easier automations from
+the **same product**. Add it under the pill at your discretion (Moderate
+and up is a good rule of thumb). Use relative links so previews work:
+
+```html
+<p class="automation-steps-heading">🌱 New here? Try these first:</p>
+<div class="automation-steps">
+  <div class="step">
+    <a class="step-title" href="../motion-activated-light/">Turn On a Light with Motion</a>
+    <span class="difficulty lvl-1">Difficulty: Level 1 · Starter</span>
+  </div>
+  <div class="step">
+    <a class="step-title" href="../button-controlled-leds/">Build a Button-Controlled RGB Light</a>
+    <span class="difficulty lvl-2">Difficulty: Level 2 · Easy</span>
+  </div>
+</div>
+```
+
+The pill and box styles live in `docs/stylesheets/extra.css`; never inline
+colors on the page.
+
+---
+
+## 11. When in doubt
 
 If a rule above conflicts with clarity for the reader, clarity wins.
 Open an issue or PR proposing the rule change so the guide stays

diff --git a/docs/products/ESPHome-Starter-Kit/automations/button-controlled-leds.md b/docs/products/ESPHome-Starter-Kit/automations/button-controlled-leds.md
@@ -6,6 +6,8 @@ description: >-
 ---
 # Build a Button-Controlled RGB Light
 
+<span class="difficulty lvl-2">Difficulty: Level 2 · Easy</span>
+
 This tutorial uses the Button module and the RGB & Buzzer module connected to the ESP32-C6, all sitting in the starter kit case.
 
 !!! note "Before you start"

diff --git a/docs/products/ESPHome-Starter-Kit/automations/motion-activated-light.md b/docs/products/ESPHome-Starter-Kit/automations/motion-activated-light.md
@@ -6,6 +6,8 @@ description: >-
 ---
 # Turn On a Light with Motion
 
+<span class="difficulty lvl-1">Difficulty: Level 1 · Starter</span>
+
 This tutorial uses the Motion module and the LED & Buzzer module connected to the ESP32-C6. When the PIR sensor detects movement, the RGB light turns on. It's the same trigger-then-action pattern as the [Button Controlled LEDs](button-controlled-leds.md) automation, swapping the button trigger for a motion trigger.
 
 !!! note "Before you start"

diff --git a/docs/products/ESPHome-Starter-Kit/automations/play-a-tune.md b/docs/products/ESPHome-Starter-Kit/automations/play-a-tune.md
@@ -6,6 +6,8 @@ description: >-
 ---
 # Play a Tune with the Button
 
+<span class="difficulty lvl-2">Difficulty: Level 2 · Easy</span>
+
 This tutorial uses the Button module and the LED & Buzzer module connected to the ESP32-C6. When you click the button, the piezo buzzer plays a short tune. It's the same trigger-then-action pattern as the [Button Controlled LEDs](button-controlled-leds.md) automation, swapping the light action for a buzzer action.
 
 !!! note "Before you start"

diff --git a/docs/products/ESPHome-Starter-Kit/automations/press-to-check-climate.md b/docs/products/ESPHome-Starter-Kit/automations/press-to-check-climate.md
@@ -7,6 +7,20 @@ description: >-
 ---
 # Press to Check Climate
 
+<span class="difficulty lvl-3">Difficulty: Level 3 · Moderate</span>
+
+<p class="automation-steps-heading">🌱 New here? Try these first:</p>
+<div class="automation-steps">
+  <div class="step">
+    <a class="step-title" href="../motion-activated-light/">Turn On a Light with Motion</a>
+    <span class="difficulty lvl-1">Difficulty: Level 1 · Starter</span>
+  </div>
+  <div class="step">
+    <a class="step-title" href="../button-controlled-leds/">Build a Button-Controlled RGB Light</a>
+    <span class="difficulty lvl-2">Difficulty: Level 2 · Easy</span>
+  </div>
+</div>
+
 Want a quick read on how the room feels without opening Home Assistant? Press the button and the **Onboard RGB LED** gives you one color for the current temperature, then another for the current humidity.
 
 The Onboard RGB LED on the ESP32-C6 is all you need for this tutorial, so the LED & Buzzer module can sit this one out.

diff --git a/docs/products/ESPHome-Starter-Kit/automations/temp-reactive-leds.md b/docs/products/ESPHome-Starter-Kit/automations/temp-reactive-leds.md
@@ -6,6 +6,20 @@ description: >-
 ---
 # Temp-Reactive LEDs
 
+<span class="difficulty lvl-3">Difficulty: Level 3 · Moderate</span>
+
+<p class="automation-steps-heading">🌱 New here? Try these first:</p>
+<div class="automation-steps">
+  <div class="step">
+    <a class="step-title" href="../motion-activated-light/">Turn On a Light with Motion</a>
+    <span class="difficulty lvl-1">Difficulty: Level 1 · Starter</span>
+  </div>
+  <div class="step">
+    <a class="step-title" href="../button-controlled-leds/">Build a Button-Controlled RGB Light</a>
+    <span class="difficulty lvl-2">Difficulty: Level 2 · Easy</span>
+  </div>
+</div>
+
 This tutorial uses the Temperature and Humidity module and the LED & Buzzer module connected to the ESP32-C6. As the room temperature drifts across set thresholds, the RGB LEDs change color so you can see the comfort band at a glance. It's the same trigger-then-action pattern as [Button Controlled LEDs](button-controlled-leds.md), swapping the button trigger for a sensor-value trigger and adding one trigger per band.
 
 !!! note "Before you start"

diff --git a/docs/stylesheets/extra.css b/docs/stylesheets/extra.css
@@ -186,3 +186,53 @@ article.md-typeset .md-button img {
   border-color: #4752c4;
   color: #fff;
 }
+
+/* ===== Automation difficulty pills ===== */
+.md-typeset .difficulty {
+  display: inline-flex;
+  align-items: center;
+  gap: 7px;
+  border-radius: 999px;
+  padding: 5px 13px;
+  font-size: 0.78rem;
+  font-weight: 600;
+  line-height: 1;
+}
+.md-typeset .difficulty::before {
+  content: "";
+  width: 9px;
+  height: 9px;
+  border-radius: 50%;
+  background: var(--diff-dot);
+}
+.md-typeset .difficulty.lvl-1 { background:#e8f5e9; color:#2e7d32; border:1px solid #a5d6a7; --diff-dot:#2e7d32; }
+.md-typeset .difficulty.lvl-2 { background:#f1f8e9; color:#558b2f; border:1px solid #c5e1a5; --diff-dot:#7cb342; }
+.md-typeset .difficulty.lvl-3 { background:#fff8e1; color:#a16207; border:1px solid #fde68a; --diff-dot:#f9a825; }
+.md-typeset .difficulty.lvl-4 { background:#fff3e0; color:#e65100; border:1px solid #ffcc80; --diff-dot:#ef6c00; }
+.md-typeset .difficulty.lvl-5 { background:#ffebee; color:#c62828; border:1px solid #ef9a9a; --diff-dot:#d32f2f; }
+
+/* ===== "Start easier" stepping-stone box ===== */
+.md-typeset .automation-steps-heading {
+  font-size: 0.8rem;
+  font-weight: 600;
+  margin: 1em 0 0.25em;
+}
+.md-typeset .automation-steps {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 10px;
+  margin: 0.5em 0 1em;
+}
+.md-typeset .automation-steps > .step {
+  flex: 1;
+  min-width: 170px;
+  border: 1px solid var(--md-default-fg-color--lightest);
+  border-radius: 8px;
+  padding: 11px 13px;
+  background: var(--md-code-bg-color);
+}
+.md-typeset .automation-steps .step-title {
+  display: block;
+  font-weight: 600;
+  margin-bottom: 7px;
+}