docs: Apollo mmWave switch-over from the original repository, zone map caveats

docs/products/general/setup/apollo-mmwave-dashboard-setup.md

@@ -37,6 +37,8 @@ If you built the [MSR-2 tuning dashboard](/products/msr2/setup/msr2-tuning-dashb
 
 Apollo mmWave installs from its GitHub repository, so you add that repository to HACS once as a custom repository. From then on HACS tracks updates for it like any other integration. The button under step 1 covers steps 1 to 5: it adds the repository, after HACS asks you to confirm, and opens Apollo mmWave so you can go on at step 6.
 
+If you installed Apollo mmWave from the original repository, bharvey88/apollo-mmwave, which is no longer on GitHub, follow [From the original Apollo mmWave repository](#from-the-original-apollo-mmwave-repository) instead. It switches HACS over without setting anything up again.
+
 1. Open **HACS** from your Home Assistant sidebar.
 
     [![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=ApolloAutomation&repository=apollo-mmwave-main&category=integration)
@@ -46,7 +48,7 @@ Apollo mmWave installs from its GitHub repository, so you add that repository to
 4. Set **Type** to **Integration** and click **Add**. The repository shows up in the list; close the dialog.
 5. Search HACS for **Apollo mmWave** and open it.
 6. Click **Download**, then confirm with **Download** in the dialog that opens.
-7. Restart Home Assistant: go to **Settings → System**, click the power icon in the upper right corner, and choose **Restart Home Assistant**. Wait for it to come back.
+7. Restart Home Assistant: go to **Settings → System**, click the power icon in the upper right corner, choose **Restart Home Assistant**, then click **Restart**. Wait for it to come back.
 
     [![Open your Home Assistant instance and show the system dashboard.](https://my.home-assistant.io/badges/system_dashboard.svg)](https://my.home-assistant.io/redirect/system_dashboard/)
 
@@ -126,6 +128,10 @@ Want to rearrange the cards? Click the pencil icon in the upper right corner of
 
 If this is your first Apollo dashboard, skip this section and [calibrate your radar](apollo-mmwave-dashboard.md#calibrate-with-an-empty-room). [Troubleshooting](#troubleshooting) is at the end of this page if something didn't load.
 
+Before any upgrade, make a full Home Assistant backup under **Settings → System → Backups**, so you can go back if something goes wrong. After you update Apollo mmWave in HACS, restart Home Assistant, then refresh the dashboard in your browser so it loads the new cards.
+
+[![Open your Home Assistant instance and show an overview of your backups.](https://my.home-assistant.io/badges/backup.svg)](https://my.home-assistant.io/redirect/backup/)
+
 ### From the MSR-2 tuning dashboard
 
 Your thresholds, detection range, and every other setting live on the sensor itself, and the new dashboard reads the same entities. There's nothing to migrate: once your MSR-2 tab works in the Apollo mmWave dashboard, you can delete the old view.
@@ -150,6 +156,40 @@ Your thresholds, detection range, and every other setting live on the sensor its
 
 If no other cards use them, you can also remove Streamline Card and Plotly Graph Card from HACS. Apollo mmWave doesn't need either.
 
+### From the original Apollo mmWave repository
+
+Apollo mmWave used to install from the original repository, bharvey88/apollo-mmwave, which is no longer on GitHub. If HACS installed your copy from there, point HACS at the new repository, ApolloAutomation/apollo-mmwave-main, so you keep getting updates. It's the same integration in the same folder, so nothing needs to be set up again: what you already have carries over, such as your Apollo mmWave entry, its dashboard, your zones, the saved calibration values that **Undo** uses, and your entity IDs. The switch takes one Home Assistant restart.
+
+If the old copy is version 1.x or 2.0, not everything carries over on its own. Read the [upgrade notes in the changelog](https://github.com/ApolloAutomation/apollo-mmwave-main/blob/main/CHANGELOG.md#upgrading-to-20) first. Some cards and automations need a change by hand, and [From Apollo mmWave 1.x zone mapping](#from-apollo-mmwave-1x-zone-mapping) below sums them up.
+
+!!! warning "Keep your Apollo mmWave entry in Home Assistant"
+
+    The switch happens in HACS only. If you choose **Delete** from the three-dot menu on the entry under **Settings → Devices & services → Apollo mmWave**, Home Assistant asks **Delete Apollo mmWave?** and warns that its devices and entities will be permanently deleted. Deleting it also deletes the Apollo mmWave dashboard, every zone, and the saved calibration values that **Undo** uses. Setting it up again starts from nothing.
+
+!!! warning "Leave Remove and Redownload alone in HACS"
+
+    Both Apollo mmWave entries in HACS use the same `custom_components/apollo_mmwave` folder. **Remove**, on either entry, first shows **Integration is configured** and tells you to delete the configuration. Don't: **Navigate** leads to the integrations page, where **Delete** wipes your zones. **Ignore**, or closing the box, opens a **Remove** box whose **Remove** button deletes the folder, new download included, so Apollo mmWave won't load after the next restart. **Redownload** on the old entry fails because its repository is gone, and the folder can end up missing. Step 3 takes the old entry off the list without touching any files.
+
+1. Check two versions first. Home Assistant needs to be 2026.8.1 or newer (**Settings → About**). In **HACS**, click the three-dot menu in the upper right corner, choose **About HACS**, and check that **Integration version** is 2.0.5 or newer. The new repository won't download on older versions. Then make a full Home Assistant backup under **Settings → System → Backups** (see [Upgrade from an older setup](#upgrade-from-an-older-setup)).
+2. In **HACS**, click the three-dot menu in the upper right corner and choose **Custom repositories**.
+3. Find the row whose second line reads **bharvey88/apollo-mmwave (integration)** and click the trash can icon on that row. There's no confirmation, so read the second line before you click: removing the wrong row deletes no files, but you have to add that repository again. This only takes the old entry off the HACS list. The files in `custom_components/apollo_mmwave` stay where they are, and Apollo mmWave keeps running.
+    - If you already added the new repository, there are two rows. Remove only the bharvey88/apollo-mmwave one.
+    - If there's no bharvey88/apollo-mmwave row, there's nothing to remove. Go on to step 4.
+4. If the dialog closed after step 3, open **Custom repositories** again. Paste `https://github.com/ApolloAutomation/apollo-mmwave-main` into the **Repository** field, set **Type** to **Integration**, click **Add**, and close the dialog. Or use the button below instead: it shows an **Add custom repository** box, and clicking **Add** there opens the repository page in HACS for you.
+
+    [![Open your Home Assistant instance and open a repository inside the Home Assistant Community Store.](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=ApolloAutomation&repository=apollo-mmwave-main&category=integration)
+
+5. Search HACS for **Apollo mmWave** and open it. Only one entry is left, and if you used the button in step 4, it's already open. Click **Download** in the lower right corner, then click **Download** again in the dialog. The dialog says the files go to `/config/custom_components/apollo_mmwave`, the same folder as before. Wait for it to finish.
+    - If it shows an error, don't restart. Fix the cause and click **Download** again until it finishes with no error. On a first download HACS saves no backup copy of the folder, so a download that stops partway can leave old and new files mixed together.
+6. Look at the HACS list. **Apollo mmWave** now shows **Pending restart**, and the old entry is gone.
+7. Restart Home Assistant: go to **Settings → System**, click the power icon in the upper right corner, choose **Restart Home Assistant**, then click **Restart**. The **Restart required** repair that HACS adds does the same when you click **Submit**.
+
+    [![Open your Home Assistant instance and show the system dashboard.](https://my.home-assistant.io/badges/system_dashboard.svg)](https://my.home-assistant.io/redirect/system_dashboard/)
+
+After the restart, HACS shows one **Apollo mmWave** entry with the status **Downloaded**. Everything else is where you left it: your same entry under **Settings → Devices & services → Apollo mmWave**, the Apollo mmWave dashboard in the sidebar, your zones on the zone map, your previous calibration values behind **Undo**, and the same entity IDs. If a card looks old or doesn't load, do a hard refresh with **Ctrl+Shift+R** (**Cmd+Shift+R** on a Mac). From here on, HACS tracks updates from the new repository.
+
+HACS may leave its own update entity for the old repository behind, showing as unavailable. It belongs to HACS, not Apollo mmWave, so deleting it is optional and doesn't touch your zones.
+
 ### From Apollo mmWave 1.x zone mapping
 
 Most of the move to 2.x happens on its own the first time the integration starts. If you wrote cards or automations by hand, change these yourself:

docs/products/general/setup/apollo-mmwave-dashboard.md

@@ -132,7 +132,7 @@ Open **Apollo mmWave** from your sidebar and, if you have more than one radar, p
 ### First column
 
 - **Auto-calibrate**: the calibration card, always at the top of the tab. It shows the chip and the device name under its title, a short checklist, and the **Calibrate with empty room** button. Everything about it is in [Calibrate with an empty room](#calibrate-with-an-empty-room) above.
-- A help card with your radar's name and a **Start here** checklist of four steps: calibrate, set how far the radar should look, set how long presence stays on, then walk the room and watch the Gate Energy chart. It ends with a **Full tuning guide →** link to the manual tuning guide on this wiki: the MSR-2 guide on an MSR-1 or MSR-2, and the LD2412 section of the R PRO-1 guide on an R PRO-1.
+- A help card with your radar's name and a **Start here** checklist of four steps: calibrate, set how far the radar should look, set how long presence stays on, then walk the room and watch the Gate Energy chart. It ends with a **Full tuning guide →** link to this guide on the wiki. On an MSR-1 or MSR-2 it opens the general version of this guide, the one that covers every Apollo radar. On an R PRO-1 it opens [the R PRO-1 version](/products/rpro1/setup/apollo-mmwave-dashboard.md#r-pro-1-and-its-ld2412-radar) at its LD2412 section.
 - **LD2410 Controls**: the **Radar Engineering Mode** switch, plus **Bluetooth**, **Restart Radar**, **Factory Reset Radar**, and **ESP Reboot**. On an R PRO-1 the card also has **Start Dynamic Background Correction** and **Background Correction Running** (see [R PRO-1 and its LD2412 radar](#r-pro-1-and-its-ld2412-radar)). **Restart Radar** restarts the radar chip and **ESP Reboot** restarts the whole sensor; neither changes your settings. Leave **Factory Reset Radar** alone unless Apollo support asks you to press it: it puts the radar chip's settings, every threshold included, back to factory values. If you press it by accident, run **Calibrate with empty room** again.
 - **LD2410 Zone Config** (MSR-1 and MSR-2): **Start Zone 1**, **End Zone 1**, **End Zone 2**, and **End Zone 3** split the radar's range into three distance bands, each with its own occupancy sensor (**Radar Zone 1 Occupancy** to **Radar Zone 3 Occupancy**). These are distances from the sensor, not areas you draw like on the R PRO-1 and MTR-1 zone map. They're optional: leave them as they are unless you want separate sensors for, say, the couch and the far end of the room.
 
@@ -212,7 +212,9 @@ The card shows your radar's name, a grid with the radar's view cone, and a dot f
 
 ### Lock and unlock
 
-The bottom-right corner has a lock toggle that reads **Unlocked** or **Locked**. The map starts locked once the radar has zones, and your browser remembers your choice for each radar. Drawing on a locked map shows **Unlock the grid before drawing.**
+The bottom-right corner has a lock toggle that reads **Unlocked** or **Locked**. The map starts locked once the radar has zones, and your browser remembers your choice for each radar. Drawing on a locked map shows **Unlock the grid before drawing.** The lock only stops drawing: **Clear All Zones**, double-clicking a zone's button, ↶ (**Undo last zone change**), and **Configure → Zones** still change your zones while the map is locked.
+
+On a phone or tablet, the grid takes every touch, so a swipe on it doesn't scroll the page, even while the map is locked. Scroll with your finger outside the grid, for example on the radar's name above it. Stay off the zone buttons while you scroll: a stray tap on **Clear All Zones** clears every zone's shape. Keep the map on **Locked** when you're not drawing: on an unlocked map, a swipe across the grid can draw a new shape for the selected zone and replace its old one.
 
 ### Add a zone
 
@@ -245,6 +247,8 @@ Under **Configure**, drag **Cone rotation:** (from -180° to 180°) until the vi
 
 Each zone gets an occupancy sensor named **Zone 1 presence** (and so on) on the radar's device page in Home Assistant. It turns on when a tracked person is inside the zone, ready to use in your automations. When you rename a zone on the card, its sensors follow, so a zone named Couch gets **Zone 1 presence - Couch**. A name you gave the sensor yourself in Home Assistant is kept.
 
+While the radar is offline, or still reconnecting after a restart, zone presence reads off, not unavailable. An automation that waits for a zone to be clear for some minutes can't tell that apart from an empty zone, so have it also check that the radar itself is online.
+
 ## Calibrate from an automation
 
 The **Calibrate with empty room** button runs the `apollo_mmwave.calibrate_gates` action, and your automations can run it too. When an automation already knows the room is empty, set `settle_s: 0` to skip the countdown, and `wait: true` to get the result back when the run ends. This example recalibrates an office radar at 3:00 AM if nobody has been detected for 30 minutes, and sends a notification when the outcome is anything other than applied:
@@ -339,9 +343,11 @@ If the button works but the card answers with a line starting **Calibration fail
 - **Home Assistant could not turn Radar Engineering Mode on within 10 s. Is the radar online?** The radar did not respond to the switch.
 - **No gate energy readings arrived within 20 s of turning Radar Engineering Mode on.** Check that the radar is online and that **Radar Engineering Mode** on the Controls card brings the Gate Energy chart to life.
 - **Radar Engineering Mode turned off during the listen. Nothing was changed.** Someone, or an automation, turned it off during the listen. Leave it on and try again.
-- **The radar has not reported 18 of its threshold values yet.** The radar has not sent its thresholds to Home Assistant since it started, which can happen after it has been running for a long time. Press **Read settings from the radar**: the card asks the radar for its settings, shows **Reading settings from the radar...**, and tries again a few seconds later. If the card can't find the radar's query params button, it says **Open the radar's device page, press its Query Params button in the Diagnostic section, wait a few seconds, then try again.** On an R PRO-1 without the [LD2412 addon](/products/rpro1/addons/add-the-ld2412-mmwave-sensor-to-r-pro-1.md), this message is expected: there's no radar to report thresholds, so reading the settings can't fix it. Skip the calibration and use the [zone map](#draw-zones-on-the-r-pro-1-and-mtr-1).
+- **The radar has not reported 18 of its threshold values yet.** The number is how many are missing: up to 18 on an MSR-1 or MSR-2, and up to 28 on an R PRO-1. The radar has not sent its thresholds to Home Assistant since it started, which can happen after it has been running for a long time. Press **Read settings from the radar**: the card asks the radar for its settings, shows **Reading settings from the radar...**, and tries again a few seconds later. If the card can't find the radar's query params button, it says **Open the radar's device page, press its Query Params button in the Diagnostic section, wait a few seconds, then try again.**
 - **Your Home Assistant user is not allowed to control this radar's entities.** Run the calibration from a Home Assistant user that can control the radar.
 
+On an R PRO-1 without the [LD2412 addon](/products/rpro1/addons/add-the-ld2412-mmwave-sensor-to-r-pro-1.md), there's no radar behind the LD2412 cards, so the Auto-calibrate card can't calibrate. Depending on what the sensor reports, the card either reads **Radar is offline. Calibration needs the radar online and its gate entities enabled.** with its buttons disabled, or answers **Calibrate with empty room** with **The radar has not reported 28 of its threshold values yet.** Reading the settings from the radar can't fix either one. Skip the calibration: the [zone map](#draw-zones-on-the-r-pro-1-and-mtr-1) is what that sensor uses.
+
 ### Radar Engineering Mode was left on
 
 The calibration only turns Radar Engineering Mode off if it was the one that turned it on. If you turned it on yourself, or with the button on the Gate Energy chart, it stays on until you turn it off with **Radar Engineering Mode** on the **Controls** card.