Sync dev to main: Homey region light flow guide, home page link fix

AGENTS.md

@@ -32,6 +32,10 @@ Read the full style guide, but these are the ones worth checking twice:
   all display text. Keep `rpro1`, `r-pro-1`, and `R_PRO-1` only in file
   names, URLs, hostnames, and literal device names.
 - **US English** spelling: color, center, meter, behavior.
+- Flag must-know info with admonitions (`note` for prerequisites,
+  `tip`, `warning`, `success` for a "Next step" box with a primary
+  button to the follow-on guide). See
+  [Admonitions and next steps](STYLE_GUIDE.md#admonitions-and-next-steps).
 - **Apollo addons** (hardware modules) and **Home Assistant apps**
   (formerly add-ons) are different things and not interchangeable.
 - **ESPHome** is the only correct casing.

STYLE_GUIDE.md

@@ -353,6 +353,39 @@ ffmpeg -ss 3 -to 26 -i recording.mp4 -an -vf "scale=540:-2,fps=30" -c:v libx264
 <video class="phone-media" src="/assets/homey-radar-regions-add-widget.mp4" autoplay loop muted playsinline></video>
 ```
 
+### Admonitions and next steps
+
+Readers skim. Put anything they must not miss in an admonition instead
+of burying it in a paragraph, and pick the type by what the box does:
+
+| Type | Use it for | Example title |
+| --- | --- | --- |
+| `note` | Prerequisites at the top of a guide | "Before you start" |
+| `tip` | A shortcut, or why something works the way it does | "Why taps instead of drags" |
+| `warning` | Something that breaks a setup or loses data if ignored | "Install both parts" |
+| `danger` | Risk of damaging hardware | "Unplug before opening" |
+| `success` | The next step once the reader has finished this one | "Next step: build your first region flow" |
+
+Keep each box to one idea and a few sentences. A page where every
+paragraph is a box has no emphasis left; if a section has more than two
+or three, fold the minor ones back into the text.
+
+**Link guides into a progression.** When one guide naturally leads to
+another (draw a zone, then build a flow with it), close the relevant
+section with a `success` box: one sentence on what the reader unlocks
+next, then a primary button to the follow-on guide. The follow-on guide
+links back from its "Before you start" note.
+
+```markdown
+!!! success "Next step: build your first region flow"
+
+    Your regions are drawn. Now make one do something: the step-by-step
+    guide walks you through a flow that turns a light on when someone
+    enters a region.
+
+    [Turn on a light when someone enters a region](../../../general/tutorials/region-light-flow-example/){ .md-button .md-button--primary }
+```
+
 ### Internal links
 
 Internal links use site-relative paths in wiki-URL form (trailing

docs/_snippets/homey-radar-regions.md

@@ -67,7 +67,7 @@ Drawing works by tapping, not dragging. Pick a shape, tap its points on the map,
 3. Adjust the new region. It appears with a name like Region 1 and its settings open. Use the arrows to move it and **Bigger** or **Smaller** to resize it.
 4. Press **Save**, or **Cancel** to throw the unsaved changes away.
 
-Your region now shows on the map, and a matching occupancy tile appears on the device.
+Your region now shows on the map, and a matching occupancy tile appears on the device. Once your regions are in place, [put one to work in a flow](#use-regions-in-flows).
 
 <video class="phone-media" src="/assets/homey-radar-regions-draw-rectangle.mp4" autoplay loop muted playsinline></video>
 
@@ -108,6 +108,12 @@ Here a polygon is drawn over a fan and set to **Ignore this area**:
 
 This is where regions pay off. Every saved detect region is an occupancy tile on the device, named after the region, and the device gets three region flow cards.
 
+!!! success "Next step: build your first region flow"
+
+    Your regions are drawn. Now make one do something: the step-by-step guide walks you through a flow that turns a light on when someone enters a region and off when they leave.
+
+    [Turn on a light when someone enters a region](../../../general/tutorials/region-light-flow-example/){ .md-button .md-button--primary }
+
 | Card | Type | Asks for | Tokens |
 | --- | --- | --- | --- |
 | **A region became occupied** | Trigger (When) | The device, then a region or **Any region** | Region name, Target count |

docs/homey.md

@@ -22,7 +22,7 @@ description: Guide to integrating Apollo Automation devices with the Homey smart
 * [Setting up zones on MTR-1 with the HLK app](https://wiki.apolloautomation.com/products/mtr1/setup/zones-hlk/)
 * [Beta test our new Zone Mapper tool!](https://github.com/ApolloAutomation/zone-mapper) - [Use this custom card along with Zone Mapper!](https://github.com/ApolloAutomation/zone-mapper-card)
 * [Tune your new R PRO-1 PoE mmWave sensor](https://wiki.apolloautomation.com/products/rpro1/setup/zones-hlk/)
-* [Draw occupancy regions in Homey with the Zone Mapper tool for MTR-1](homey/products/mtr1/setup/mtr-1-zone-mapper-tool/) or [R PRO-1](homey/products/rpro1/setup/r-pro-1-zone-mapper-tool/)
+* [Draw occupancy regions in Homey with the Zone Mapper tool for MTR-1](products/mtr1/setup/mtr-1-zone-mapper-tool/) or [R PRO-1](products/rpro1/setup/r-pro-1-zone-mapper-tool/)
 
 ### Quick References
 

docs/homey/products/general/tutorials/region-light-flow-example.md

@@ -0,0 +1,80 @@
+---
+title: Turn on a light when someone enters a region
+description: Build a Homey flow that turns a light on when someone enters a Radar regions area on your MTR-1 or R PRO-1, and off again when they leave.
+---
+
+# Turn on a light when someone enters a region
+
+<span class="difficulty lvl-1">Difficulty: Level 1</span>
+
+Regions turn one radar into several spots you can automate on their own: the desk, the sofa, the workbench. In this guide you build two flows in the Homey mobile app. The first turns a light on the moment someone steps into a region; the second turns it off once the region has been empty for a while. The example uses a region called **Server** on an Apollo R PRO-1, and works the same way on an MTR-1 with any region you have drawn.
+
+<!-- Video walkthrough goes here once recorded:
+<video class="phone-media" src="/assets/homey-region-light-flow-walkthrough.mp4" poster="/assets/homey-region-light-flow-walkthrough-poster.jpg" controls muted playsinline preload="metadata"></video>
+-->
+
+!!! note "Before you start"
+
+    - Draw at least one region with the Zone Mapper tool, set to **Detect people here**. See the guide for your [R PRO-1](../../../rpro1/setup/r-pro-1-zone-mapper-tool/) or [MTR-1](../../../mtr1/setup/mtr-1-zone-mapper-tool/).
+    - Add the light you want to control to Homey.
+
+## Why use the region trigger
+
+Every detect region gives your sensor three flow cards: **A region became occupied**, **A region became empty**, and **A region is occupied**. Start your flow with **A region became occupied** and pick your region. It fires every time someone walks into that spot, even when someone else is already elsewhere in the room.
+
+The sensor's whole-room card, **The occupancy alarm turned on**, only fires when the room goes from empty to occupied. Pairing it with a **Server is occupied** condition misses the moment someone who is already in the room walks over to the server, so the light stays off.
+
+## Flow 1: turn the light on
+
+This flow has one trigger and one action, so it needs no **And** card.
+
+1. In the Homey mobile app, tap **Flow** in the bottom bar, then tap **+** at the top right (or **Create a Flow** if you have none yet).
+2. Under **When...**, tap **Add Card**. Open **Apollo Automation** under **Apps**, and choose your sensor.
+3. Choose the card **A region became occupied**.
+4. Tap **Region** and pick **Server**, then tap the check mark at the top right.
+5. Under **Then...**, tap **Add Card**. Find your light under **Zones & Devices**, choose **Turn on**, and tap the check mark.
+6. Tap **Next**. Name the flow, for example **Server area light on**, and tap **Save Flow**.
+
+<!-- Clip goes here once recorded:
+<video class="phone-media" src="/assets/homey-region-light-flow-on.mp4" autoplay loop muted playsinline></video>
+-->
+
+The flow now shows in **My Flows**. Walk into the region and the light turns on.
+
+!!! tip "Only detect regions are listed"
+
+    The region picker lists your **Detect people here** regions. Areas set to **Ignore this area** never report occupied, so they don't appear.
+
+## Flow 2: turn the light off
+
+The second flow mirrors the first. Build it the same way, with two changes:
+
+1. Under **When...**, choose **A region became empty** and pick **Server**.
+2. Under **Then...**, choose **Turn off** for the same light.
+3. Name it **Server area light off** and tap **Save Flow**.
+
+Now the light follows the region: on when someone arrives, off when they leave.
+
+## Set the hold time
+
+A region stays occupied for its **Hold time** after the last person leaves, 5 seconds by default. That is what stops the light from flickering off when someone leans back or steps away for a moment.
+
+For a desk or a workbench, raise it. Open the dashboard with your **Radar regions** widget, tap the region with **Select** active, and set **Hold time** under **More** to 60 seconds or longer. Press **Save**. Flow 2 now waits that long before it turns the light off.
+
+## Test your flows
+
+Run the flows end to end by walking in and out of the region while you watch the light. To check a single flow without moving, tap the play button next to it in **My Flows**; it runs its **Then** cards once, and a green check mark confirms it ran.
+
+If a flow doesn't fire:
+
+- Open the **Radar regions** widget and watch the dots. If your dot doesn't land inside the region, make the region larger with **Bigger** or the arrows.
+- Check that the region is set to **Detect people here** and is **Enabled**.
+- Check that both flows are switched on in **My Flows**.
+
+## Take it further
+
+- **One flow for many regions**: pick **Any region** in the trigger instead of a single region. The **Region name** token tells the flow which one fired, for example in a notification.
+- **Count people**: **A region became occupied** also passes a **Target count** token, the number of people in the region.
+- **Keep other automations in check**: add **A region is occupied** as an **And** condition. For example, add **Sofa** is not occupied (with **Invert** on) to the flow that turns your living room lights off.
+
+See [Use regions in flows](../../../rpro1/setup/r-pro-1-zone-mapper-tool/#use-regions-in-flows) for the full list of region cards.

mkdocs.yml

@@ -643,6 +643,7 @@ nav:
           - Example Flows:
 #            - Air Quality Notification: homey/products/general/tutorials/air-quality-notification-example.md
             - High CO2 Notification: homey/products/general/tutorials/high-co2-notification-example.md
+            - Region Light: homey/products/general/tutorials/region-light-flow-example.md
           - Additional Info:
             - Calibrating:
               - CO<sub>2</sub>: homey/products/general/calibrating-and-updating/co2-calibration.md