Sync dev to main

.github/workflows/docs-checks.yml

@@ -0,0 +1,50 @@
+name: docs-checks
+# Runs on every pull request into dev or main. Each step reports problems as
+# annotations on the PR's changed lines; later steps still run if an earlier
+# one fails, so one run shows everything. Scripts live in tools/docs-checks/.
+on:
+  pull_request:
+    branches:
+      - dev
+      - main
+  workflow_dispatch:
+permissions:
+  contents: read
+jobs:
+  checks:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v7
+        with:
+          python-version: 3.x
+      - run: pip install -r requirements.txt
+      - run: sudo apt-get update && sudo apt-get install -y libimage-exiftool-perl
+      - name: List changed files
+        id: changed
+        run: |
+          base="${{ github.event.pull_request.base.sha }}"
+          if [ -n "$base" ]; then
+            git diff --name-only --diff-filter=AM "$base"...HEAD > changed.txt
+          else
+            : > changed.txt
+          fi
+          echo "Changed files:"; cat changed.txt
+      - name: Markdown (front matter, headings, alt text, includes)
+        run: python tools/docs-checks/check_markdown.py docs
+      - name: No secrets in text
+        if: always()
+        run: python tools/docs-checks/check_secrets.py docs
+      - name: Images (GPS location data, file size)
+        if: always()
+        run: CHANGED_FILES="$(cat changed.txt)" python tools/docs-checks/check_images.py docs/assets
+      - name: Build the site
+        if: always()
+        env:
+          DISABLE_MKDOCS_2_WARNING: "true"
+        run: mkdocs build -d site
+      - name: Links, anchors, and image alt text in the built site
+        if: always()
+        run: python tools/docs-checks/check_links.py site docs

AGENTS.md

@@ -39,6 +39,10 @@ Read the full style guide, but these are the ones worth checking twice:
 - **Apollo addons** (hardware modules) and **Home Assistant apps**
   (formerly add-ons) are different things and not interchangeable.
 - **ESPHome** is the only correct casing.
+- Firmware install links go to the product's page on the Apollo
+  installer (`https://install.apolloautomation.com/#/air-1`), not the
+  old `apolloautomation.github.io/AIR-1/` installers. See
+  [Flashing firmware](STYLE_GUIDE.md#flashing-firmware).
 - **No em dashes** anywhere in user-facing copy.
 - Second person, imperative voice for action copy. Wrap numbered steps
   with framing copy (what the reader unlocks, what success looks like).
@@ -58,6 +62,14 @@ Read the full style guide, but these are the ones worth checking twice:
   buttons, edit the snippet file, never the include line on a page.
   See [Community CTA on starter-kit pages](STYLE_GUIDE.md#11-community-cta-on-starter-kit-pages).
 
+## Automated PR checks
+
+Every pull request runs `tools/docs-checks/` (see its README): front
+matter, heading levels, alt text, snippet includes, secrets, GPS data in
+photos, and links and anchors on the built site. Run them locally before
+opening a PR. They can't read text inside images, so check screenshots
+and recordings for passwords, API keys, and personal details by eye.
+
 ## Keep the style guide current
 
 If you notice a recurring pattern that should be standardized but isn't

CONTRIBUTING.md

@@ -43,6 +43,7 @@ mkdocs serve
 4. Verify the build is clean (no broken links or missing-plugin errors) via `mkdocs build`.
 5. Fill out the PR template and link any related issues.
 6. Use PR title format: `<type>: <description>` (types: `docs`, `fix`, `feat`, `chore`)
+7. Automated checks run on every PR: front matter, heading levels, image alt text, snippet includes, secrets in text, GPS location data in photos, and broken links or anchors on the built site. Problems appear as comments on the changed lines. See [tools/docs-checks/README.md](tools/docs-checks/README.md) for what each check looks for, how to fix it, and how to run them locally.
 
 ## Key files and folders
 

STYLE_GUIDE.md

@@ -158,6 +158,20 @@ When introducing the broader project, prefer **ESPHome ecosystem** over
 context (for example, when the audience may not recognize the term).
 Avoid **burn** and **load**.
 
+Link firmware installs to the product's own page on the Apollo
+installer, `https://install.apolloautomation.com/#/<product>` (for
+example `#/air-1` or `#/r-pro-1`), not the older
+`apolloautomation.github.io/<PRODUCT>/` installers. Name buttons the way
+the installer shows them: the variant (**USB Power**, **Battery Power**,
+**WiFi**, **Ethernet**, **Smart (Wi-Fi)**, **Basic (No Wi-Fi)**) and
+then **Connect & Install**, and the firmware option in the next dialog
+exactly as listed (for example **Install ApolloAutomation.AIR-1**). The
+B models use their parent's page with **Battery Power** (TEMP-1B on
+`#/temp-1`, PLT-1B on `#/plt-1`). Keep the older installer link only
+where the Apollo installer has no equivalent: the TEMP Pro-1, and TEMP-1
+Revision 1 firmware. The LED-1 uses the official WLED installer at
+`https://install.wled.me/`.
+
 ---
 
 ## 6. Voice and structure
@@ -415,8 +429,16 @@ shrinks PNGs, so compress video before committing it.
 - **Phone recordings** (portrait) take `class="phone-media"`, which
   caps them at phone width and centers them. The class lives in
   `docs/stylesheets/extra.css`; never size media inline.
-- **Trim personal details** (names, email addresses, home names,
-  notifications) out of every recording before it's published.
+- **Trim personal details and secrets** (names, email addresses, home
+  names, notifications, Wi-Fi passwords, API keys) out of every recording
+  and screenshot before it's published. Compile and install logs print
+  the device's full configuration, so end a recording before the log
+  scrolls through it, and check YAML editor shots for an `api:
+  encryption: key:` value.
+- **Strip location data from photos.** Phones save the GPS location in
+  every photo. Remove it before committing:
+  `exiftool -gps:all= -overwrite_original docs/assets/<file>`. The PR
+  checks fail on any photo that still has it.
 - **Compress** with H.264, no audio track, and fast start, scaled to
   540px wide for clips and 720px for a full phone walkthrough. Aim for
   under 1 MB per clip and a few MB for a walkthrough:

docs/homey/products/air1/additonal-info/air-quality-sensor-comparison.md

@@ -1,4 +1,5 @@
 ---
+title: Air quality sensor comparison
 description: "A technical comparison of air quality sensors used with the AIR-1, including performance, accuracy, and specifications."
 ---
 --8<-- "products/air1/additional-info/air-quality-sensor-comparison.md:5:"

docs/homey/products/air1/troubleshooting/air1-code.md

@@ -15,11 +15,11 @@ If your Apollo AIR-1 becomes unresponsive and you've exhausted the other trouble
 
 ![AIR-1 case with a tool pointing at the boot button left of the USB-C port](/assets/air-1-boot-button.jpg)
 
-2\. Go to the <a href="https://apolloautomation.github.io/AIR-1/" target="_blank" rel="noreferrer nofollow noopener">Apollo AIR-1 Installer</a> page.
+2\. Go to the <a href="https://install.apolloautomation.com/#/air-1" target="_blank" rel="noreferrer nofollow noopener">Apollo AIR-1 installer</a> page.
 
-3\. Click the big **Connect** button.
+3\. Click **Connect & Install**.
 
-![Apollo AIR-1 Installer web page with the Connect button highlighted](/assets/air-1-reflash-pic-1.png)
+![AIR-1 page of the Apollo installer with the Connect & Install button outlined in red](/assets/installer-air-1.png)
 
 4\. Select the open COM port, then click **Connect**.
 

docs/homey/products/general/calibrating-and-updating/zone-configuration/zones-ha.md

@@ -1,4 +1,5 @@
 ---
+title: MTR-1 Home Assistant zone configuration
 description: "Tutorial for MTR-1 Home Assistant Zone Configuration."
 ---
 --8<-- "products/mtr1/setup/zones-ha.md:5:"

docs/homey/products/general/calibrating-and-updating/zone-configuration/zones-hlk.md

@@ -1,4 +1,5 @@
 ---
+title: HLK Radar Tool app
 description: "Tutorial for MTR-1 HLKRadarTool app Zone Configuration."
 ---
 --8<-- "homey/products/mtr1/setup/zones-hlk.md:5:"

docs/homey/products/general/contact-us/Facebook.md

@@ -1,4 +1,5 @@
 ---
+title: Facebook
 description: "Join the Apollo Automation community group on Facebook."
 ---
 --8<-- "products/general/contact-us/Facebook.md:5:"

docs/homey/products/general/contact-us/GitHub.md

@@ -1,4 +1,5 @@
 ---
+title: GitHub
 description: "Apollo Automation on GitHub, where the firmware and hardware files live."
 ---
 --8<-- "products/general/contact-us/GitHub.md:5:"

docs/homey/products/general/contact-us/Instagram.md

@@ -1,4 +1,5 @@
 ---
+title: Instagram
 description: "Follow Apollo Automation on Instagram."
 ---
 --8<-- "products/general/contact-us/Instagram.md:5:"

docs/homey/products/general/contact-us/Reddit.md

@@ -1,4 +1,5 @@
 ---
+title: Reddit
 description: "The Apollo Automation subreddit."
 ---
 --8<-- "products/general/contact-us/Reddit.md:5:"

docs/homey/products/general/contact-us/YouTube.md

@@ -1,4 +1,5 @@
 ---
+title: YouTube
 description: "The Apollo Automation YouTube channel, with setup guides, reviews, and live streams."
 ---
 --8<-- "products/general/contact-us/YouTube.md:5:"

docs/homey/products/general/contact-us/apollo-automation-shop.md

@@ -1,4 +1,5 @@
 ---
+title: Apollo Automation shop
 description: "The Apollo Automation shop, where you can buy sensors, probes, and accessories."
 ---
 --8<-- "products/general/contact-us/apollo-automation-shop.md:6:"

docs/homey/products/general/contact-us/our-team.md

@@ -1,4 +1,5 @@
 ---
+title: Our team
 description: "Meet the people behind Apollo Automation."
 ---
 --8<-- "products/general/contact-us/our-team.md:5:"

docs/homey/products/general/setup/getting-started-msr1.md

@@ -1,4 +1,5 @@
 ---
+title: Getting started
 description: "Generic getting started article."
 ---
 --8<-- "homey/products/general/setup/getting-started.md:6:"

docs/homey/products/general/setup/getting-started-temp1.md

@@ -1,4 +1,5 @@
 ---
+title: Getting started
 description: "Generic getting started article."
 ---
 --8<-- "homey/products/general/setup/getting-started.md:6:"

docs/homey/products/general/temp-hum-calibration.md

@@ -1,4 +1,5 @@
 ---
+title: Temp and humidity calibration and offset examples
 description: "Temp and Humidity Calibration and Offset Examples."
 ---
 --8<-- "products/general/temp-hum-calibration.md:5:"

docs/homey/products/led1/examples/led-1-controlling-govee-lights.md

@@ -1,4 +1,5 @@
 ---
+title: LED-1 controlling Govee lights
 description: How to use the Apollo LED-1 to control your Govee/3rd Party permanent outdoor LED lights!
 ---
 --8<-- "products/led1/examples/led-1-controlling-govee-lights.md:7:"

docs/homey/products/led1/faq.md

@@ -1,4 +1,5 @@
 ---
+title: LED-1 FAQ
 description: "Frequently asked questions about the LED-1 controller."
 ---
 --8<-- "products/led1/faq.md:5:"

docs/homey/products/led1/introduction.md

@@ -1,4 +1,5 @@
 ---
+title: Introduction
 description: "Documentation for LED-1, including setup, usage, and best practices."
 ---
 --8<-- "products/led1/introduction.md:5:"

docs/homey/products/led1/setup/getting-started-led1.md

@@ -1,4 +1,5 @@
 ---
+title: Getting started
 description: "Getting started with your new LED-1!"
 ---
 --8<-- "products/led1/setup/getting-started-led1.md:5:"

docs/homey/products/led1/setup/led1-general-tips.md

@@ -1,4 +1,5 @@
 ---
+title: LED-1 general tips
 description: "Multiple helpful tips to use your LED-1 to the fullest!"
 ---
 --8<-- "products/led1/setup/led1-general-tips.md:5:"

docs/homey/products/led1/setup/led1-pinout-guide.md

@@ -1,4 +1,5 @@
 ---
+title: LED-1 pinout guide
 description: "LED-1 Pinout Guide"
 ---
 --8<-- "products/led1/setup/led1-pinout-guide.md:5:"

docs/homey/products/led1/setup/led1-replace-fuse.md

@@ -1,4 +1,5 @@
 ---
+title: How to replace the LED-1 10 A fuse
 description: "Tutorial showing how to replace the 10 A Fuse on the LED-1."
 ---
 --8<-- "products/led1/setup/led1-replace-fuse.md:5:"

docs/homey/products/led1/troubleshooting/led1-boot-mode.md

@@ -1,4 +1,5 @@
 ---
+title: Putting the LED-1 in boot mode
 description: "Step by step guide for putting The LED-1 In Boot Mode."
 ---
 --8<-- "products/led1/troubleshooting/led1-boot-mode.md:5:"

docs/homey/products/led1/troubleshooting/led1-find-ip-address-and-hostname.md

@@ -1,4 +1,5 @@
 ---
+title: How to find the IP address and hostname of your LED-1
 description: "Step by step guide for finding the IP address and the hostname of your LED-1 device."
 ---
 --8<-- "products/led1/troubleshooting/led1-find-ip-address-and-hostname.md:5:"

docs/homey/products/led1/troubleshooting/led1-reflash.md

@@ -1,4 +1,5 @@
 ---
-description: "Step by step guide for re-flashing the LED-1 back to factory firmware."
+title: Factory re-flash LED-1
+description: "Step by step guide for re-flashing the LED-1 with regular WLED from your browser."
 ---
 --8<-- "products/led1/troubleshooting/led1-reflash.md:5:"

docs/homey/products/msr2/setup/msr2-general-tips.md

@@ -34,4 +34,4 @@ The MSR-2 can also be mounted on the ceiling if you can provide power and mount
 
 **![Table of LD2410 gates 0 to 8 with distance ranges in meters and feet and default move and still thresholds](/assets/ld2410-gate-table.png)![Radar Distance Resolution set to 0.75m with Radar End Zone 1, 2, and 3 at 50, 100, and 200 cm](/assets/gate-zones-and-rr.png)**
 
-![Fan diagram of LD2410 gates G1 to G8, each 0.75 m deep, reaching 6 m (19.69 ft) from the sensor](/assets/ld2410-gate-map.png)![Radar gate diagram with Zones 1, 2, and 3 shaded red, blue, and green over gates G1 to G7](/assets/radar-gates-colored.png)
+![Fan diagram of LD2410 gates G1 to G8, each 0.75 m deep, reaching 6 m (19.69 ft) from the sensor](/assets/ld2410-gate-map.png)![Fan diagram of LD2410 gates G1 to G8 grouped into example zones: Zone 1 (G1 to G2) in red, Zone 2 (G3 to G5) in blue, and Zone 3 (G6 to G8) in green, reaching 6 m](/assets/radar-gates-colored.png)

docs/homey/products/msr2/troubleshooting/msr2-code.md

@@ -16,17 +16,17 @@ If your device has already been added to Homey, please <a href="https://wiki.apo
 
 2\. Push and hold the boot button. While still holding the button down, plug in a USB-C cable into the USB-C port of your MSR-2 then let go of the button.
 
-3\. Navigate to our installer page and click connect under <a href="https://apolloautomation.github.io/MSR-2/" target="_blank" rel="noreferrer nofollow noopener">Apollo MSR-2 Installer</a>.
+3\. Open the <a href="https://install.apolloautomation.com/#/msr-2" target="_blank" rel="noreferrer nofollow noopener">Apollo MSR-2 installer</a>.
 
-4\. Click the big "Connect" button.
+4\. Click **Connect & Install**.
 
-![Apollo MSR-2 Installer page with the CONNECT button highlighted](/assets/msr-2-reflash-pic-1.png)
+![MSR-2 page of the Apollo installer with the Connect & Install button outlined in red](/assets/installer-msr-2.png)
 
 5\. Select the open com port then click Connect.
 
 ![Browser serial port dialog listing the USB JTAG serial debug unit with the Connect button](/assets/msr-2-reflash-pic-2.png)
 
-6\. Click "Install MSR-2".
+6\. Click **Install ApolloAutomation.MSR-2**.
 
 ![Installer Device Dashboard menu with INSTALL MSR-2 highlighted](/assets/msr-2-reflash-pic-3.png)
 

docs/homey/products/mtr1/examples/how-to-use-the-apollo-gpio-header-to-control-an-led-strip.md

@@ -1,4 +1,5 @@
 ---
+title: Control an LED strip with the GPIO header
 description: "Wire a WS2812B LED strip to the Apollo GPIO Header and control it from Home Assistant."
 ---
 --8<-- "products/msr2/examples/gpio-header-control-an-led-strip.md:5:"

docs/homey/products/mtr1/troubleshooting/mtr1-code.md

@@ -16,17 +16,17 @@ If your device has already been added to Homey, please <a href="https://wiki.apo
 
 2\. Push and hold the boot button. While still holding the button down, plug in a USB-C cable into the USB-C port of your MTR-1 then let go of the button.
 
-3\. Navigate to our installer page and click connect under <a href="https://apolloautomation.github.io/MTR-1/" target="_blank" rel="noreferrer nofollow noopener">Apollo MTR-1 Installer</a>.
+3\. Open the <a href="https://install.apolloautomation.com/#/mtr-1" target="_blank" rel="noreferrer nofollow noopener">Apollo MTR-1 installer</a>.
 
-4\. Click the big "Connect" button.
+4\. Click **Connect & Install**.
 
-![Apollo MTR-1 Installer page with the Connect button highlighted](/assets/mtr-1-reflash-pic-1.png)
+![MTR-1 page of the Apollo installer with the Connect & Install button outlined in red](/assets/installer-mtr-1.png)
 
 5\. Select the open com port then click Connect.
 
 ![Browser serial port prompt with the USB JTAG/serial debug unit selected and Connect clicked](/assets/mtr-1-reflash-pic-2.png)
 
-6\. Click "Install MTR-1".
+6\. Click **Install ApolloAutomation.MTR-1**.
 
 ![Installer Device Dashboard with the Install MTR-1 option being clicked](/assets/mtr-1-reflash-pic-3.png)
 

docs/homey/products/plt1/troubleshooting/plt1-code.md

@@ -16,17 +16,17 @@ Follow these steps to put your device in boot mode and install the factory firmw
 
 ![Side of the PLT-1 with the boot button opening circled](/assets/screenshot-2024-10-23-at-12-32-55-pm.png)
 
-2\. Navigate to our installer page and click connect under Non Battery Firmware <a href="https://apolloautomation.github.io/PLT-1/" target="_blank" rel="noreferrer nofollow noopener">Apollo PLT-1 Installer</a>
+2\. Navigate to the <a href="https://install.apolloautomation.com/#/plt-1" target="_blank" rel="noreferrer nofollow noopener">Apollo PLT-1 installer</a> and choose **USB Power** since you are using a PLT-1.
 
-3\. Click the big "Connect" button.
+3\. Click **Connect & Install**.
 
-![Apollo PLT-1 Installer page with the Non Battery Firmware Connect button highlighted](/assets/plt-1-reflash-pic-1-1.png)
+![PLT-1 page of the Apollo installer with the USB Power variant and the Connect & Install button outlined in red](/assets/installer-plt-1-usb-power.png)
 
 4\. Select the open com port then click Connect.
 
 ![Browser serial port prompt with the USB JTAG/serial debug unit selected and Connect clicked](/assets/plt-1-reflash-pic-2-1.png)
 
-5\. Click "Install ApolloAutomation.PLT-1".
+5\. Click **Install ApolloAutomation.PLT-1**.
 
 ![Installer Device Dashboard with the Install ApolloAutomation.PLT-1 option highlighted](/assets/plt-1-reflash-pic-3.png)
 

docs/homey/products/plt1b/troubleshooting/plt1b-code.md

@@ -21,11 +21,11 @@ Follow these steps to put your PLT-1B in boot mode and install the factory firmw
 
 ![Tool inserted into the boot button opening on the side of the closed PLT-1B case](/assets/plt-boot-mode-pic-4.jpg)
 
-2\. Open the <a href="https://apolloautomation.github.io/PLT-1/" target="_blank" rel="noreferrer nofollow noopener">Apollo PLT-1B Installer</a>.
+2\. Open the <a href="https://install.apolloautomation.com/#/plt-1" target="_blank" rel="noreferrer nofollow noopener">Apollo PLT-1 installer</a>. The PLT-1B uses the same page as the PLT-1.
 
-3\. Under **Battery Firmware**, click the big **Connect** button.
+3\. Choose **Battery Power**, then click **Connect & Install**.
 
-![Apollo PLT-1 Installer page with the Battery Firmware Connect button being clicked](/assets/plt-1b-reflash-pic-1.png)
+![PLT-1 page of the Apollo installer with the Battery Power variant and the Connect & Install button outlined in red](/assets/installer-plt-1-battery-power.png)
 
 4\. Select the open COM port, then click **Connect**.
 

docs/homey/products/rpro1/calibrating-co2.md

@@ -1,4 +1,5 @@
 ---
+title: CO2 calibration tutorial (quick)
 description: "Step by step guide for re-calibrating your SCD40 CO2 sensor"
 ---
 --8<-- "products/rpro1/calibrating-co2.md:5:"

docs/homey/products/rpro1/faq.md

@@ -35,7 +35,7 @@ description: "Answers to common questions about the R PRO-1 PoE mmWave sensor wi
 7\. **How do I connect the R PRO-1 to Homey?**
 
 * The R PRO-1 ships with Wi-Fi firmware. Connect it to your Wi-Fi through its hotspot, then add it in Homey with the Apollo Automation app, which talks to it directly over your local network through the ESPHome native API. The app runs on Homey Pro; Homey Cloud isn't supported. See [Getting started](../../general/setup/getting-started/).
-* Once it's connected, you can switch to Ethernet firmware for PoE from the sensor's own web page: in a browser, open `http://apollo-r-pro-1-w-xxxxxx.local`, where `xxxxxx` is the last 6 characters of the device's name in Homey. Choose **Ethernet** under **Firmware Type**, then press **Firmware Update**. The sensor downloads the new firmware from GitHub, so it needs internet access. You can also reflash it to Ethernet firmware with the <a href="https://apolloautomation.github.io/R_PRO-1/" target="_blank" rel="noreferrer nofollow noopener">R PRO-1 installer</a>.
+* Once it's connected, you can switch to Ethernet firmware for PoE from the sensor's own web page: in a browser, open `http://apollo-r-pro-1-w-xxxxxx.local`, where `xxxxxx` is the last 6 characters of the device's name in Homey. Choose **Ethernet** under **Firmware Type**, then press **Firmware Update**. The sensor downloads the new firmware from GitHub, so it needs internet access. You can also reflash it to Ethernet firmware from the <a href="https://install.apolloautomation.com/#/r-pro-1" target="_blank" rel="noreferrer nofollow noopener">Apollo R PRO-1 installer</a> by choosing **Ethernet**.
 * Homey recognizes the R PRO-1 by its hardware address, so after the switch it stays the same device in Homey.
 
 8\. **What kind of flows can I create with the R PRO-1?**