Rework reading order and small improvements

.gitignore

@@ -4,3 +4,4 @@ node_modules
 .DS_Store
 .omc/
 .playwright-cli/
+pnpm-lock.yaml

astro.config.mjs

@@ -8,8 +8,9 @@ export default defineConfig({
     '/beacons/apple': '/apple',
     '/beacons/other': '/other',
     '/base-stations': '/nodes',
-    '/hardware': '/nodes',
-    '/install': '/firmware',
+    '/nodes': '/hardware/nodes',
+    '/install': '/hardware/firmware',
+    '/firmware': '/hardware/firmware',
     '/data-flow': '/troubleshooting/data-flow',
     '/ids': '/troubleshooting/ids',
     '/terminal': '/troubleshooting/terminal',
@@ -41,30 +42,37 @@ export default defineConfig({
       ],
       sidebar: [
         { label: 'Home', link: '/' },
-        { slug: 'quick-start' },
-        { slug: 'nodes' },
-        { slug: 'firmware' },
         {
-          label: 'Devices',
+          label: 'Getting started',
           items: [
-            { slug: 'devices', label: 'Overview' },
-            { slug: 'android' },
-            { slug: 'apple' },
-            { slug: 'other' },
+            { slug: 'approach' },
+            { slug: 'quick-start' },
           ],
         },
         {
-          label: 'Configuration',
+          label: 'Hardware',
+          items: [
+            { slug: 'hardware/nodes' },
+            { slug: 'hardware/firmware' },
+            { slug: 'hardware/enclosures' },
+          ],
+        },
+	{
+          label: 'Node Configuration',
           items: [
             { slug: 'configuration/network' },
             { slug: 'configuration/settings' },
             { slug: 'configuration/hardware' },
+            { slug: 'configuration/mqtt' },
           ],
         },
         {
-          label: 'MQTT',
+          label: 'Trackable Devices',
           items: [
-            { slug: 'configuration/mqtt' },
+            { slug: 'devices', label: 'Overview' },
+            { slug: 'android' },
+            { slug: 'apple' },
+            { slug: 'other' },
           ],
         },
         {
@@ -103,7 +111,6 @@ export default defineConfig({
             { slug: 'troubleshooting/terminal' },
           ],
         },
-        { slug: 'enclosures' },
         { slug: 'credits' },
       ],
     }),

src/content/docs/approach.mdx

@@ -0,0 +1,62 @@
+---
+title: Approaches
+---
+
+:::note
+These are fundamentally different approaches. mqtt_room uses 1 node per room. Companion needs dense coverage (5-8 per floor) with strategic placement. More nodes doesn't make mqtt_room better - pick one approach and commit.
+:::
+
+## Approach 1: mqtt_room (Simple Room Presence)
+
+**Best for:** Room-based automations like "turn on kitchen lights when I enter"
+
+| | mqtt_room |
+|:---|:---|
+| **Question Answered** | "Which room is my device in?" |
+| **Output** | Room name (e.g., "kitchen") |
+| **Nodes Needed** | 1 per room |
+| **Setup** | Simple |
+
+Your device connects to the **single nearest ESPresense node**. The node's configured room name is reported to Home Assistant.
+
+```
+Phone → "I'm 2m from Living Room node" → HA sees "Phone is in Living Room"
+```
+
+**Requirements:**
+- Place **one node per room** where you want detection
+- Each node = one room in your automation
+- No floor plan required
+
+**When to use:** Turning lights on/off per room, playing announcements, basic presence detection. **Start here if you're new.**
+
+[Setup mqtt_room →](/integrations/home-assistant)
+
+## Approach 2: Companion (Precise Positioning)
+
+**Best for:** Precise location tracking like "find my phone on the floor plan"
+
+| | Companion |
+|:---|:---|
+| **Question Answered** | "Where exactly is my device on the floor?" |
+| **Output** | X,Y coordinates on floor plan |
+| **Nodes Needed** | 5-8 per floor |
+| **Setup** | More complex |
+
+Multiple nodes measure distance to your device simultaneously. Using **multilateration**, Companion calculates precise coordinates.
+
+```
+Phone → 3m from Node A, 5m from Node B, 4m from Node C → Companion: Phone is at (X,Y)
+```
+
+**Additional requirements:**
+- **5-8 nodes per floor** (depending on square footage)
+- **Perimeter nodes help most** - provide strongest positioning
+- **Avoid collinearity** - don't place nodes in straight lines
+- Requires accurate floor plan
+- Obstacles (walls, furniture) drastically affect accuracy
+
+**When to use:** Finding exact location on a floor plan, tracking movement paths, room-level presence isn't enough.
+
+[Setup Companion →](/companion)
+

src/content/docs/companion/configuration.md

@@ -314,4 +314,6 @@ The configuration file supports hot reloading, which means:
 - No need to restart the companion after changes
 - If there is unexpected behavior give the companion add-on a moment to implement the configuration, if unresolved or unresponsive a reboot (not restart of home assistant, a full reboot) of the host device can resolve the issue.
 
-### Help write this documentation! Click 'Edit this page on GitHub' below.
+:::tip
+Help improve this documentation! Click 'Edit page' below.
+:::

src/content/docs/companion/installation.md

@@ -4,32 +4,47 @@ sidebar:
   order: 1
 ---
 
+Installing the ESPresense Companion is a combination of the Companion App itself and a MQTT server.
 
-## Home Assistant OS (HAOS)
+Companion deployment:
 
-### Step 1: Add Repository
-<div style="display: flex; align-items: center; gap: 10px; margin-bottom: 20px;">
-    <a href="https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2FESPresense%2Fhassio-addons">
-        <img src="https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg" alt="Open your Home Assistant instance and show the add add-on repository dialog with a specific repository URL pre-filled." />
-    </a>
-    <span>Click <code>Add</code></span>
-</div>
+- Recommended: As an [App](#home-assistant-app) within Home Assistant
+- Optional: As a (composed) [container](#containerized-deployment) elsewhere (experienced users)
 
-### Step 2: Install
-<div style="display: flex; align-items: center; gap: 10px;">
-    <a href="https://my.home-assistant.io/redirect/supervisor_store/">
-        <img src="https://my.home-assistant.io/badges/supervisor_store.svg" alt="Open your Home Assistant instance and show the Supervisor add-on store." />
-    </a>
-    <span>Click <code>Install</code>, <code>Start</code>, then <code>Show in Sidebar</code></span>
-</div>
+MQTT setup:
 
-### Manual Add-on Installation (Alternative)
+- Recommended: Home Assistant [MQTT](#home-assistant-mqtt-app) App
+- Alternative: [External](#external-mqtt-broker) MQTT broker
 
-If the buttons above don't work for you, follow these steps to add the repository and install the add-on manually within Home Assistant:
+## Home Assistant App
 
-1.  **Navigate to Add-ons:** Go to `Settings` > `Add-ons` in your Home Assistant UI.
+### Two-step Install (Recommended!)
+
+#### Step 1: Add Repository
+
+<a href="https://my.home-assistant.io/redirect/supervisor_add_addon_repository/?repository_url=https%3A%2F%2Fgithub.com%2FESPresense%2Fhassio-addons">
+  <img src="https://my.home-assistant.io/badges/supervisor_add_addon_repository.svg"
+       alt="Add ESPresense App repository to Home Assistant" />
+</a>
+
+Click **Add** in the dialog.
+
+#### Step 2: Install
+
+<a href="https://my.home-assistant.io/redirect/supervisor_store/">
+  <img src="https://my.home-assistant.io/badges/supervisor_store.svg"
+       alt="Open Home Assistant Supervisor App store" />
+</a>
+
+Click **Install**, **Start**, then **Show in Sidebar**.
+
+### Manual App Installation
+
+If the buttons above don't work for you, follow these steps to add the repository and install the app manually within Home Assistant:
+
+1.  **Navigate to Apps:** Go to `Settings` > `Add-ons` in your Home Assistant UI.
 2.  **Add Repository:**
-    *   Click the `Add-on Store` button (usually bottom right).
+    *   Click the `Apps Store` button (usually bottom right).
     *   Click the three dots menu in the top right corner and select `Repositories`.
     *   Paste the following URL into the "Add repository" field:
         ```
@@ -38,18 +53,18 @@ If the buttons above don't work for you, follow these steps to add the repositor
     *   Click `Add`.
     *   Close the repository management dialog.
 3.  **Install ESPresense Companion:**
-    *   Refresh the Add-on Store page (you might need to wait a moment or refresh your browser).
+    *   Refresh the Apps Store page (you might need to wait a moment or refresh your browser).
     *   Search for `ESPresense Companion`.
-    *   Click on the `ESPresense Companion` add-on.
+    *   Click on the `ESPresense Companion` app.
     *   Click `Install`.
     *   Once installed, click `Start`.
     *   Optionally, enable `Show in sidebar` for easy access.
 
-## DIY Docker Container
+### Containerized Deployment
 
 Example docker-compose configuration:
-```yaml
-version: '3.7'
+
+```yaml title="compose.yaml"
 services:
   espresense:
     image: espresense/espresense-companion
@@ -59,18 +74,19 @@ services:
     volumes:
       - ./data/espresense:/config/espresense
 ```
+
 Port `8268` is required for firmware updates.
 
 ## MQTT Setup
 
-ESPresense and ESPresense Companion require MQTT to function. Here's how to set it up:
+ESPresense and ESPresense Companion require MQTT to function. Here's two ways to set it up:
 
-### Using Home Assistant's MQTT Addon
-1. Install the Mosquitto broker addon from the official add-on store
-2. Start the addon
+#### Home Assistant MQTT App
+1. Install the Mosquitto broker app from the official app store
+2. Start the app
 3. ESPresense Companion will automatically use these settings
 
-### Using External MQTT Broker
+### External MQTT Broker
 1. Install [Mosquitto](https://mosquitto.org/) or your preferred MQTT broker
 2. Note your configuration:
    - Host
@@ -101,10 +117,10 @@ Once installation is complete:
 ## Troubleshooting Installation
 
 ### Common Issues:
-1. **Can't see the add-on in Home Assistant:**
+1. **Can't see the app in Home Assistant:**
    - Refresh your browser
    - Verify the repository was added successfully
-   - Check the add-on store logs
+   - Check the app store logs
 
 2. **MQTT Connection Failed:**
    - Verify MQTT broker is running

src/content/docs/companion/optimization.md

@@ -115,4 +115,6 @@ If the default values aren't providing accurate distances:
 - Metal objects, walls, and furniture can affect readings
 - Note successful RSSI@1m values for your specific devices for future reference
 
-## Help write this documentation! Click the edit this page below.
+:::tip
+Help improve this documentation! Click 'Edit page' below.
+:::

src/content/docs/companion/troubleshooting.md

@@ -7,6 +7,10 @@ sidebar:
 
 ## Installation Issues
 
+:::note
+Also check the [Installation Troubleshooting](/companion/installation/#troubleshooting-installation) section.
+:::
+
 ### Add-on Not Appearing
 - Refresh your browser cache
 - Re-add the repository using the button on the [Installation page](/companion/installation)
@@ -123,4 +127,6 @@ If you're still having issues:
    - Steps to reproduce
    - Expected vs actual behavior
 
-## Help write this documentation! Click the edit this page below.
+:::tip
+Help improve this documentation! Click 'Edit page' below.
+:::

src/content/docs/configuration/mqtt.md

@@ -7,12 +7,17 @@ sidebar:
 
 If you end up deploying a fleet of ESP32s in your home, it can quickly become painful to go to each device to update settings.
 
-You can use tools like MQTT explorer or if you are using mosquitto (default for HA), the mosquitto_sub and mosquitto_pub tools to view and manage the settings.
+You can use tools like [MQTT explorer](https://mqtt-explorer.com) or if you are using mosquitto (default for HA), the `mosquitto_sub` and `mosquitto_pub` tools to view and manage the settings.
+
 
 ```bash
-mosquitto_sub -h homeassistant.local -u <username> -P <password> -i presensce-information -v -t "espresense/rooms/kitchen/#"
+mosquitto_sub -h homeassistant.local -u <username> -P <password> -i presense-information -v -t "espresense/rooms/kitchen/#"
 ```
 
+:::note
+For configuration of the Companion App also check the [Companion MQTT](/companion/installation/#mqtt-setup) section
+:::
+
 ## Reading Current Settings
 
 Example output when subscribing to a room:
@@ -32,7 +37,7 @@ espresense/rooms/study/arduino_ota OFF
 You can update the configuration for any of the above topics by publishing to the `/set` endpoint for each topic like so:
 
 ```bash
-mosquitto_pub -h homeassistant.local -u <username> -P <password> -i presensce-information -t "espresense/rooms/kitchen/auto_update/set" -m "ON" -d
+mosquitto_pub -h homeassistant.local -u <username> -P <password> -i presense-information -t "espresense/rooms/kitchen/auto_update/set" -m "ON" -d
 ```
 
 You can use a room of `*` to update all ESPresense nodes at the same time. If you retain that setting even NEW nodes will upon startup get that configuration set.

src/content/docs/devices.md

@@ -1,7 +1,7 @@
 ---
-title: Devices
+title: Trackable Devices
 sidebar:
-  order: 4
+  order: 3
 ---
 
 
@@ -63,3 +63,4 @@ If you have a different BLE-enabled piece of hardware that you have gotten to wo
 ## Footnotes
 
 [^beaconconfig]: These can do eddystone and iBeacon at the same time, just pick iBeacon
+

src/content/docs/enclosures.md → src/content/docs/hardware/enclosures.md

@@ -4,6 +4,7 @@ sidebar:
   order: 9
 ---
 
+Example enclosures for various ESPs.
 
 ## D1 Mini 32
 * [ESP32 D1 Mini Case - USB Plug w/ MMWave Sensor](https://www.printables.com/model/335469-usb-outlet-esp32-d1-mini-case-for-espresense-and-m)

src/content/docs/firmware.mdx → src/content/docs/hardware/firmware.mdx

@@ -1,21 +1,25 @@
 ---
 title: Install Firmware
 sidebar:
-  order: 2
+  order: 5
 ---
 
-import FirmwareInstaller from '../../components/FirmwareInstaller.astro';
+import FirmwareInstaller from '../../../components/FirmwareInstaller.astro';
 
 ## Browser-Based Installer
 
 Begin by connecting an ESP device to your computer using USB, then click the "Connect" button below:
 
 <FirmwareInstaller />
 
+:::tip
+You must use Edge or Chrome(-based) browser, the above web-based installer does not work on Firefox or Safari.
+:::
+
 ## Post-Flashing Steps
 
 Upon successful firmware flashing, search for an Access Point (AP) with an SSID beginning with "ESPresense-". Connect to this network to access the configuration portal. For setup instructions, visit [Configuration Settings](/configuration/settings).
 
 ## Alpha / Nightly Builds
 
-For those interested in experimental features, you can opt for a nightly/alpha build available [here](/alpha). Please note this is for adventurous users and may not be stable.
+For those interested in experimental features, you can opt for a nightly/alpha build available [here](/alpha). Please note this is for experienced and adventurous users and may not be stable.

src/content/docs/nodes.md → src/content/docs/hardware/nodes.md

@@ -1,7 +1,7 @@
 ---
 title: Nodes
 sidebar:
-  order: 3
+  order: 4
 ---