Normalize internal doc links to relative .md paths

docs/20-quick-start.md

@@ -54,7 +54,7 @@ Try creating assets, agents, rules, users, realms, etc. using the Manager UI, so
 ## Where's the data stored?
 Persistent data is stored in a PostgreSQL DB which is stored in the `openremote_postgresql-data` Docker volume which is durably stored independently of the running containers (see all with `docker volume ls`).
 Note that historical attribute data is purged daily based on value of `OR_DATA_POINTS_MAX_AGE_DAYS`; this value can also be overridden for individual attributes by using the `dataPointsMaxAgeDays` configuration item.
-See the [Developer Guide](developer-guide/system-administration#backuprestore) for details on making backups of the database.
+See the [Developer Guide](developer-guide/100-system-administration.md#backuprestore) for details on making backups of the database.
 
 
 ## Contributing to OpenRemote

docs/developer-guide/160-frontend-testing.md

@@ -71,7 +71,7 @@ The component tests are used to test individual Lit web components.
 
 ### Prerequisites
 
-Assuming you have set up your [development tooling](preparing-the-environment#development-tooling).
+Assuming you have set up your [development tooling](010-preparing-the-environment.md#development-tooling).
 
 1. Create a playwright configuration file `playwright.config.ts` in your component / app directory.
 

docs/tutorials/010-white-label-multi-tenant-iot-platform.md

@@ -8,7 +8,7 @@ White-labeling and multi-tenancy are part of the open-source core of OpenRemote
 
 ## Prerequisites
 
-- A running OpenRemote instance - see the [Quick Start](../quick-start).
+- A running OpenRemote instance - see the [Quick Start](../20-quick-start.md).
 - Superuser (`admin`) access to the **master** realm.
 - Your brand assets: a `logo.png`, a `logo-mobile.png`, a `favicon.png`, and your brand colour hex codes.
 
@@ -55,7 +55,7 @@ By default, superusers (e.g. `admin`) will see styling changes from `manager_con
 
 To verify per-tenant branding reliably, log in as a normal realm user.
 
-See [Custom deployment](../user-guide/deploying/custom-deployment) and the [Appearance page](../user-guide/manager-ui/appearance) for the full set of options.
+See [Custom deployment](../user-guide/010-deploying/10-custom-deployment.md) and the [Appearance page](../user-guide/020-manager-ui/30-appearance.md) for the full set of options.
 :::
 
 ## Step 3 - Serving each tenant
@@ -70,6 +70,6 @@ Your customer's realm is now available at its own URL (e.g. `iot.acme.com/manage
 
 ## Next steps
 
-- Lock down who can see what with [enterprise identity, SSO and RBAC](enterprise-identity-sso-rbac).
-- Let your customers' devices register themselves with [auto-provisioning at scale](auto-provision-devices-at-scale).
+- Lock down who can see what with [enterprise identity, SSO and RBAC](./060-enterprise-identity-sso-rbac.md).
+- Let your customers' devices register themselves with [auto-provisioning at scale](./080-auto-provision-devices-at-scale.md).
 - Build a customer-facing dashboard with the Insights dashboard builder.

docs/tutorials/020-open-weather-api-using-http-agent.md

@@ -1,9 +1,9 @@
 # Using HTTP Agent for weather service
 
-This tutorial explains how to use the generic [HTTP Agent](../user-guide/agents-protocols/http) with an example to connect to the [OpenWeatherMap](https://openweathermap.org/) API.
+This tutorial explains how to use the generic [HTTP Agent](../user-guide/040-agents-protocols/050-http.md) with an example to connect to the [OpenWeatherMap](https://openweathermap.org/) API.
 
 :::note
-If you specifically want to connect to OpenWeatherMap, you can use the dedicated [OpenWeatherMap Agent](../user-guide/agents-protocols/openweathermap).
+If you specifically want to connect to OpenWeatherMap, you can use the dedicated [OpenWeatherMap Agent](../user-guide/040-agents-protocols/190-openweathermap.md).
 :::
 
 ## Prerequisites

docs/tutorials/040-receive-lorawan-sensor-data-from-chirpstack.md

@@ -1,6 +1,6 @@
 # ChirpStack LoRaWAN Integration
 
-[ChirpStack](https://www.chirpstack.io/) is an open source LoRaWAN network server stack. This tutorial explains how to receive LoRaWAN sensor data via ChirpStack using the [MQTT Agent](../user-guide/agents-protocols/mqtt). The tutorial is based on the [Dragino LHT65](https://www.dragino.com/products/temperature-humidity-sensor/item/151-lht65.html) LoRaWAN sensor device as an example.
+[ChirpStack](https://www.chirpstack.io/) is an open source LoRaWAN network server stack. This tutorial explains how to receive LoRaWAN sensor data via ChirpStack using the [MQTT Agent](../user-guide/040-agents-protocols/090-mqtt.md). The tutorial is based on the [Dragino LHT65](https://www.dragino.com/products/temperature-humidity-sensor/item/151-lht65.html) LoRaWAN sensor device as an example.
 
 :::note
 This tutorial focuses on the **manual configuration** of MQTT agent links to provide a deeper understanding of the integration process.

docs/tutorials/050-connect-modbus-devices.md

@@ -8,7 +8,7 @@ The Modbus agent runs **inside the OpenRemote Manager** - there is no separate g
 
 ## Prerequisites
 
-- A running OpenRemote instance - see the [Quick Start](../quick-start).
+- A running OpenRemote instance - see the [Quick Start](../20-quick-start.md).
 - A reachable Modbus device: a Modbus TCP slave on your network, or a Modbus RTU device on a serial line accessible to the Manager host.
 - The device's register map (function code, address, data type, scaling).
 
@@ -18,7 +18,7 @@ The Modbus agent runs **inside the OpenRemote Manager** - there is no separate g
 2. For TCP, set the host/IP, port and the unit/slave ID.
 3. For RTU, set the serial port, baud rate, parity and stop bits, and the unit ID.
 
-See the [Modbus agent reference](../user-guide/agents-protocols/modbus) for all parameters.
+See the [Modbus agent reference](../user-guide/040-agents-protocols/080-modbus.md) for all parameters.
 
 ## Step 2 - Create the asset that represents the device
 
@@ -46,9 +46,9 @@ Writing to a holding register or coil lets you actuate the device (e.g. toggle a
 
 ## Step 5 - Turn raw values into insight
 
-Use [Flow rules](../user-guide/rules-and-forecasting/flow-rules) to derive virtual attributes (e.g. compute energy from power), and [When-Then rules](../user-guide/rules-and-forecasting/when-then-rules) to alarm on thresholds.
+Use [Flow rules](../user-guide/060-rules-and-forecasting/30-flow-rules.md) to derive virtual attributes (e.g. compute energy from power), and [When-Then rules](../user-guide/060-rules-and-forecasting/20-when-then-rules.md) to alarm on thresholds.
 
 ## Next steps
 
-- Deploy a local [edge gateway with a secure tunnel](edge-gateway-secure-tunnel) for sites with intermittent connectivity.
+- Deploy a local [edge gateway with a secure tunnel](./070-edge-gateway-secure-tunnel.md) for sites with intermittent connectivity.
 

docs/tutorials/060-enterprise-identity-sso-rbac.md

@@ -8,15 +8,15 @@ Industry-standard identity is built into the open-source core: Keycloak-based au
 
 ## Prerequisites
 
-- A running OpenRemote instance - see the [Quick Start](../quick-start).
-- Superuser access; ideally a [tenant realm already created](white-label-multi-tenant-iot-platform).
+- A running OpenRemote instance - see the [Quick Start](../20-quick-start.md).
+- Superuser access; ideally a [tenant realm already created](./010-white-label-multi-tenant-iot-platform.md).
 - For SSO/AD: access to your identity provider (Microsoft Entra ID/AD, Google, Okta, or any OIDC/SAML IdP).
 
 ## Step 1 - Understand the access model
 
 OpenRemote separates concerns into:
 
-- **Realms** - isolated tenants (see the [white-label tutorial](white-label-multi-tenant-iot-platform)).
+- **Realms** - isolated tenants (see the [white-label tutorial](./010-white-label-multi-tenant-iot-platform.md)).
 - **Roles** - what a user can do (read, write, configure, manage users, etc.).
 - **Restricted users** - users who can only see the specific assets linked to them (device- or customer-level access control).
 
@@ -34,7 +34,7 @@ Because identity is managed by Keycloak, you can federate to an external Identit
 2. Add an **Identity Provider** (OIDC or SAML) for your IdP and map claims/roles.
 3. Users now sign in with corporate credentials; access maps to OpenRemote roles automatically.
 
-To synchronise users/groups from a directory, follow [Linking to Active Directory](../user-guide/identity-and-security/linking-to-active-directory).
+To synchronise users/groups from a directory, follow [Linking to Active Directory](../user-guide/070-identity-and-security/30-linking-to-active-directory.md).
 
 ## Step 4 - Create OAuth2 service users for devices and integrations
 
@@ -52,9 +52,9 @@ Give each device or integration its own service user with a narrow role, so you
 
 1. Sign in via your IdP and confirm the SSO flow and resulting roles.
 2. Log in as a restricted user and confirm they see only their linked assets.
-3. Obtain a token for the service user and call a [REST API](../category/rest-api) endpoint.
+3. Obtain a token for the service user and call a [REST API](/docs/category/rest-api) endpoint.
 
 ## Next steps
 
-- Use these service users in the [MQTT/auto-provisioning](auto-provision-devices-at-scale) flow.
-- Apply per-tenant branding in the [white-label, multi-tenant tutorial](white-label-multi-tenant-iot-platform).
+- Use these service users in the [MQTT/auto-provisioning](./080-auto-provision-devices-at-scale.md) flow.
+- Apply per-tenant branding in the [white-label, multi-tenant tutorial](./010-white-label-multi-tenant-iot-platform.md).

docs/tutorials/070-edge-gateway-secure-tunnel.md

@@ -8,13 +8,13 @@ The edge gateway is the **same OpenRemote codebase** running on-site, so an inst
 
 ## Prerequisites
 
-- Two OpenRemote instances: a **central** instance and an on-site **edge** instance (both from the [Quick Start](../quick-start) / Docker images; `amd64` and `arm64` are supported, so the edge can run on small hardware).
+- Two OpenRemote instances: a **central** instance and an on-site **edge** instance (both from the [Quick Start](../20-quick-start.md) / Docker images; `amd64` and `arm64` are supported, so the edge can run on small hardware).
 - Network access from the edge instance out to the central instance.
-- Read [OpenRemote as Edge Gateway](../user-guide/gateways-and-devices/edge-gateway).
+- Read [OpenRemote as Edge Gateway](../user-guide/080-gateways-and-devices/10-edge-gateway.md).
 
 ## Step 1 - Run OpenRemote on the edge
 
-Deploy a standard OpenRemote instance on the on-site hardware. Connect your local devices to it using whichever agents fit - [Modbus](connect-modbus-devices), [KNX](../user-guide/agents-protocols/knx), MQTT, Z-Wave, etc. The edge instance keeps working and storing data even if the uplink drops.
+Deploy a standard OpenRemote instance on the on-site hardware. Connect your local devices to it using whichever agents fit - [Modbus](./050-connect-modbus-devices.md), [KNX](../user-guide/040-agents-protocols/060-knx.md), MQTT, Z-Wave, etc. The edge instance keeps working and storing data even if the uplink drops.
 
 ## Step 2 - Register the gateway on the central instance
 
@@ -27,17 +27,17 @@ Configure the edge instance with the central instance's address and the gateway
 
 ## Step 4 - Remotely access the gateway UI via the secure tunnel
 
-Open the gateway's local UI from the central instance through the **secure tunnel**, so field engineers can configure and troubleshoot a site without a site visit or a public inbound port. Follow the tunnel setup in [OpenRemote as Edge Gateway](../user-guide/gateways-and-devices/edge-gateway).
+Open the gateway's local UI from the central instance through the **secure tunnel**, so field engineers can configure and troubleshoot a site without a site visit or a public inbound port. Follow the tunnel setup in [OpenRemote as Edge Gateway](../user-guide/080-gateways-and-devices/10-edge-gateway.md).
 
 :::caution
-Restrict who can open tunnels and access gateway UIs using [roles and restricted users](enterprise-identity-sso-rbac); remote access to field equipment should be tightly scoped.
+Restrict who can open tunnels and access gateway UIs using [roles and restricted users](./060-enterprise-identity-sso-rbac.md); remote access to field equipment should be tightly scoped.
 :::
 
 ## Step 5 - Decide what runs where
 
-Keep latency-sensitive control and local automation in [edge rules](../user-guide/rules-and-forecasting/create-rules), and use the central instance for cross-site dashboards, fleet-wide rules and long-term analytics.
+Keep latency-sensitive control and local automation in [edge rules](../user-guide/060-rules-and-forecasting/10-create-rules.md), and use the central instance for cross-site dashboards, fleet-wide rules and long-term analytics.
 
 ## Next steps
 
-- Push [OTA firmware updates](ota-firmware-updates-with-hawkbit) to devices behind the gateway.
-- Onboard edge devices automatically with [auto-provisioning](auto-provision-devices-at-scale).
+- Push [OTA firmware updates](./090-ota-firmware-updates-with-hawkbit.md) to devices behind the gateway.
+- Onboard edge devices automatically with [auto-provisioning](./080-auto-provision-devices-at-scale.md).

docs/tutorials/080-auto-provision-devices-at-scale.md

@@ -8,7 +8,7 @@ Provisioning in OpenRemote creates the client credentials **and** the digital as
 
 ## Prerequisites
 
-- A running OpenRemote instance - see the [Quick Start](../quick-start).
+- A running OpenRemote instance - see the [Quick Start](../20-quick-start.md).
 - Superuser access to a realm where your devices will live.
 - A device (or test client) that can do MQTT over TLS with an X.509 client certificate - for example an ESP32/ESP8266.
 
@@ -23,7 +23,7 @@ Decide what each device *is* in your model (e.g. a `Thing`, or a custom `Environ
 3. Select the **asset type** to create per device and set the realm.
 4. Choose whether to **auto-link attributes** to standard MQTT topics and whether newly provisioned assets are **disabled until approved** (useful for a manufacturing QA gate).
 
-See [Auto provisioning devices and users](../user-guide/gateways-and-devices/auto-provisioning) for the message format and the full configuration reference.
+See [Auto provisioning devices and users](../user-guide/080-gateways-and-devices/20-auto-provisioning.md) for the message format and the full configuration reference.
 
 ## Step 3 - Flash devices with a unique certificate
 
@@ -37,7 +37,7 @@ On first connection the device publishes a provisioning request to the provision
 2. Links its attributes to the device's publish/subscribe topics.
 3. Returns the asset ID so the device can start publishing telemetry immediately.
 
-For a concrete firmware example, follow [Connect ESP32 or ESP8266 using MQTT](../user-guide/gateways-and-devices/connect-esp32-or-esp8266-using-mqtt), then point it at your provisioning config instead of a manually created service user.
+For a concrete firmware example, follow [Connect ESP32 or ESP8266 using MQTT](../user-guide/080-gateways-and-devices/30-connect-esp32-or-esp8266-using-mqtt.md), then point it at your provisioning config instead of a manually created service user.
 
 ## Step 5 - Verify and scale
 
@@ -46,10 +46,10 @@ For a concrete firmware example, follow [Connect ESP32 or ESP8266 using MQTT](..
 3. Roll out the remaining fleet - no manual asset creation required.
 
 :::note
-Combine this with [multi-tenant realms](./white-label-multi-tenant-iot-platform) so each customer's devices provision straight into that customer's realm.
+Combine this with [multi-tenant realms](./010-white-label-multi-tenant-iot-platform.md) so each customer's devices provision straight into that customer's realm.
 :::
 
 ## Next steps
 
-- Keep field devices current with [OTA firmware updates using hawkBit](ota-firmware-updates-with-hawkbit).
-- Deploy a local [edge gateway with a secure tunnel](edge-gateway-secure-tunnel) for sites with intermittent connectivity.
+- Keep field devices current with [OTA firmware updates using hawkBit](./090-ota-firmware-updates-with-hawkbit.md).
+- Deploy a local [edge gateway with a secure tunnel](./070-edge-gateway-secure-tunnel.md) for sites with intermittent connectivity.

docs/tutorials/090-ota-firmware-updates-with-hawkbit.md

@@ -8,17 +8,17 @@ OpenRemote integrates a purpose-built rollout engine (hawkBit) for **device life
 
 ## Prerequisites
 
-- A running OpenRemote instance - see the [Quick Start](../quick-start).
+- A running OpenRemote instance - see the [Quick Start](../20-quick-start.md).
 - A hawkBit instance reachable from OpenRemote (can be co-located with your stack).
 - Devices whose firmware can poll a hawkBit DDI endpoint and apply an update image.
 
 ## Step 1 - Enable the hawkBit integration
 
-Configure OpenRemote to connect to your hawkBit server. Once linked, OpenRemote can represent firmware/device-update state on your assets and surface update actions. See [Firmware updating with Hawkbit](../user-guide/gateways-and-devices/firmware-updating-with-hawkbit) for the supported features and configuration.
+Configure OpenRemote to connect to your hawkBit server. Once linked, OpenRemote can represent firmware/device-update state on your assets and surface update actions. See [Firmware updating with Hawkbit](../user-guide/080-gateways-and-devices/40-firmware-updating-with-hawkbit.md) for the supported features and configuration.
 
 ## Step 2 - Register devices as hawkBit targets
 
-Each device becomes a **target** in hawkBit. Use a consistent target/controller ID (for example the same serial used during [auto-provisioning](auto-provision-devices-at-scale)) so a device's OpenRemote asset and its hawkBit target line up one-to-one.
+Each device becomes a **target** in hawkBit. Use a consistent target/controller ID (for example the same serial used during [auto-provisioning](./080-auto-provision-devices-at-scale.md)) so a device's OpenRemote asset and its hawkBit target line up one-to-one.
 
 ## Step 3 - Upload a software module and distribution set
 
@@ -38,9 +38,9 @@ Always start with a small canary group and verify devices come back online and r
 
 ## Step 5 - Track update status in OpenRemote
 
-Monitor update progress and firmware version on the device assets in the Manager. Combine this with [rules](../user-guide/rules-and-forecasting/create-rules) to alert an operator if a device fails to check in after an update.
+Monitor update progress and firmware version on the device assets in the Manager. Combine this with [rules](../user-guide/060-rules-and-forecasting/10-create-rules.md) to alert an operator if a device fails to check in after an update.
 
 ## Next steps
 
-- Trigger update alerts and escalation with [ML Forecasting Service](../user-guide/services/service-ml-forecast).
-- Manage on-site devices behind an [edge gateway with a secure tunnel](../user-guide/gateways-and-devices/edge-gateway).
+- Trigger update alerts and escalation with [ML Forecasting Service](../user-guide/100-services/20-service-ml-forecast.md).
+- Manage on-site devices behind an [edge gateway with a secure tunnel](../user-guide/080-gateways-and-devices/10-edge-gateway.md).

docs/tutorials/110-change-celsius-to-fahrenheit-with-flow.md

@@ -4,7 +4,7 @@ This tutorial offers an example for converting an attribute value, using the Flo
 
 ## Prerequisites
 
-- A running OpenRemote instance - see the [Quick Start](../quick-start).
+- A running OpenRemote instance - see the [Quick Start](../20-quick-start.md).
 
 ## Step 1 - Create a new attribute