fix(docs): improve documentation clarity and formatting across multiple files

Author: sidey79

docs/01_user_guide/index.adoc

@@ -71,10 +71,10 @@ Die Hauptkomponenten sind:
 
 Für einen schnellen Einstieg folgen Sie diesen Schritten:
 
-1. **Installation**: Siehe link:installation.adoc[Installationsanleitung].
-2. **Konfiguration**: Setzen Sie die erforderlichen Umgebungsvariablen (z.B. `SIGNALDUINO_SERIAL_PORT`, `MQTT_HOST`).
-3. **Programm starten**: Führen Sie `python3 main.py` aus.
-4. **MQTT‑Nachrichten überwachen**: Abonnieren Sie das Topic `signalduino/messages`, um dekodierte Signale zu empfangen.
+. **Installation**: Siehe link:installation.adoc[Installationsanleitung].
+. **Konfiguration**: Setzen Sie die erforderlichen Umgebungsvariablen (z.B. `SIGNALDUINO_SERIAL_PORT`, `MQTT_HOST`).
+. **Programm starten**: Führen Sie `python3 main.py` aus.
+. **MQTT‑Nachrichten überwachen**: Abonnieren Sie das Topic `signalduino/messages`, um dekodierte Signale zu empfangen.
 
 Ausführliche Anleitungen finden Sie in den folgenden Kapiteln.
 

docs/01_user_guide/installation.adoc

@@ -4,6 +4,7 @@
 ====
 PySignalduino ist noch in Entwicklung.
 Es gibt bisher keine stabile Version – nutzen Sie die Software mit entsprechender Vorsicht.
+====
 
 == Voraussetzungen
 

docs/02_developer_guide/contribution.adoc

@@ -9,11 +9,11 @@ Beiträge zum Projekt sind willkommen!
 
 == Workflow
 
-1. **Fork & Clone:** Projekt forken und lokal klonen.
-2. **Branch:** Feature-Branch erstellen (`git checkout -b feature/mein-feature`).
-3. **Entwicklung:** Änderungen implementieren.
-4. **Tests:** Sicherstellen, dass alle Tests bestehen (`pytest`).
-5. **Pull Request:** PR auf GitHub öffnen.
+. **Fork & Clone:** Projekt forken und lokal klonen.
+. **Branch:** Feature-Branch erstellen (`git checkout -b feature/mein-feature`).
+. **Entwicklung:** Änderungen implementieren.
+. **Tests:** Sicherstellen, dass alle Tests bestehen (`pytest`).
+. **Pull Request:** PR auf GitHub öffnen.
 
 == Entwicklungsumgebung
 

docs/03_protocol_reference/protocol_details.adoc

@@ -22,6 +22,6 @@ Die Datei `sd_protocols/protocols.json` ist die definitive Quelle für alle Prot
 
 == Neues Protokoll hinzufügen
 
-1. Definition in `protocols.json` ergänzen.
-2. Dekodierungsmethode implementieren (z.B. in `sd_protocols/manchester.py`).
-3. Tests hinzufügen.
+. Definition in `protocols.json` ergänzen.
+. Dekodierungsmethode implementieren (z.B. in `sd_protocols/manchester.py`).
+. Tests hinzufügen.

docs/architecture/decisions/ADR-001-mqtt-get-frequency.adoc

@@ -24,9 +24,9 @@ $$f_{RF} = \frac{26}{65536} \times F_{REG} \, \text{MHz}$$
 
 Wir implementieren den `get/frequency` Befehl als Teil der `MqttHandler`- und `Commands`-Klassen.
 
-1.  *MQTT Topic*: Der Befehl wird über `cmd/get/frequency` empfangen (komplettes Topic: `<base_topic>/commands/get/frequency`).
-2.  *Antwort Topic*: Die Antwort wird über das etablierte Antwort-Topic (`<base_topic>/responses`) veröffentlicht, um Konsistenz mit dem bestehenden `get/system/version` Befehl zu gewährleisten. Der Payload muss das Feld `command` enthalten, um die Herkunft zu kennzeichnen.
-3.  *Berechnungslogik*: Die Berechnung wird exakt nach der CC1101-Formel unter Verwendung von $F_{XOSC} = 26 \, \text{MHz}$ durchgeführt.
+.  *MQTT Topic*: Der Befehl wird über `cmd/get/frequency` empfangen (komplettes Topic: `<base_topic>/commands/get/frequency`).
+.  *Antwort Topic*: Die Antwort wird über das etablierte Antwort-Topic (`<base_topic>/responses`) veröffentlicht, um Konsistenz mit dem bestehenden `get/system/version` Befehl zu gewährleisten. Der Payload muss das Feld `command` enthalten, um die Herkunft zu kennzeichnen.
+.  *Berechnungslogik*: Die Berechnung wird exakt nach der CC1101-Formel unter Verwendung von $F_{XOSC} = 26 \, \text{MHz}$ durchgeführt.
     *   Wir erstellen eine asynchrone Methode in `signalduino/hardware.py` (z.B. `get_frequency_registers()`) zum Auslesen von FREQ2, FREQ1, FREQ0.
     *   Wir implementieren die Berechnung in `signalduino/commands.py` (z.B. `get_frequency()`), um die Abhängigkeit der Hardware vom Command Layer zu kapseln.
     *   Das Ergebnis wird auf 4 Dezimalstellen gerundet (in MHz), um eine hohe Genauigkeit bei der Anzeige zu gewährleisten.

docs/architecture/decisions/ADR-002-mqtt-command-dispatcher.adoc

@@ -15,9 +15,9 @@ Die zentrale Verwaltung der Befehle und deren Validierung ist eine bewährte Met
 
 Die hartcodierte `if/elif`-Logik in `signalduino/mqtt.py` wird durch die Verwendung des `MqttCommandDispatcher` ersetzt.
 
-1. Der `MqttPublisher` in `signalduino/mqtt.py` wird eine Instanz des `MqttCommandDispatcher` erhalten.
-2. Die Methode `_handle_command` in `MqttPublisher` wird umgeschrieben, um den eingehenden Befehlspfad und Payload direkt an `MqttCommandDispatcher.dispatch()` zu übergeben.
-3. Die Fehler- und Erfolgsantworten werden vom `MqttCommandDispatcher` zurückgegeben und von `MqttPublisher` an die entsprechenden MQTT-Topics (`/responses` und `/errors`) publiziert.
+. Der `MqttPublisher` in `signalduino/mqtt.py` wird eine Instanz des `MqttCommandDispatcher` erhalten.
+. Die Methode `_handle_command` in `MqttPublisher` wird umgeschrieben, um den eingehenden Befehlspfad und Payload direkt an `MqttCommandDispatcher.dispatch()` zu übergeben.
+. Die Fehler- und Erfolgsantworten werden vom `MqttCommandDispatcher` zurückgegeben und von `MqttPublisher` an die entsprechenden MQTT-Topics (`/responses` und `/errors`) publiziert.
 
 [[konsequenzen]]
 == Konsequenzen

docs/architecture/proposals/mqtt_get_frequency.adoc

@@ -13,9 +13,9 @@ Dieses Proposal beschreibt die Implementierung des MQTT-Kommandos `get/cc1101/fr
 
 Der Befehl wird über das MQTT-Topic `[base_topic]/commands/get/cc1101/frequency` empfangen und löst eine Kette von Funktionsaufrufen aus:
 
-1.  *`signalduino/mqtt.py`*: Empfängt das Kommando und ruft die Kommando-Logik auf.
-2.  *`signalduino/commands.py`*: Implementiert die High-Level-Logik, welche die Registerwerte von der Hardware abruft und die Frequenz berechnet.
-3.  *`signalduino/hardware.py`*: Stellt eine neue Methode zum Lesen der FREQ2, FREQ1 und FREQ0 Register bereit.
+.  *`signalduino/mqtt.py`*: Empfängt das Kommando und ruft die Kommando-Logik auf.
+.  *`signalduino/commands.py`*: Implementiert die High-Level-Logik, welche die Registerwerte von der Hardware abruft und die Frequenz berechnet.
+.  *`signalduino/hardware.py`*: Stellt eine neue Methode zum Lesen der FREQ2, FREQ1 und FREQ0 Register bereit.
 
 Das Ergebnis wird als JSON-Objekt auf dem zentralen Antwort-Topic (`<base_topic>/responses`) veröffentlicht, um Konsistenz mit bestehenden Befehlen zu gewährleisten.
 

docs/architecture/proposals/mqtt_set_commands.adoc

@@ -5,6 +5,7 @@
 
 // Absicht und Zielsetzung
 == 1. Zielsetzung und Scope
+
 Dieses Architekturproposal beschreibt die Implementierung der CC1101-Parameter-Set-Befehle über MQTT.
 Die Funktionalität umfasst das Setzen von Frequenz, Bandbreite, Datenrate, Sensitivity und Ramping-Level (Rampl).
 Das Ziel ist es, eine konsistente, zuverlässige Kette vom MQTT-Topic bis zum seriellen Kommando an den Signalduino zu gewährleisten.
@@ -103,9 +104,9 @@ Das Feld `req_id` in allen MQTT-Command-Payloads (sowohl `set/...` als auch `get
 * **Antwort:** Bei Fehlen der `req_id` in der Anfrage wird das Feld `req_id` in der Antwort-Payload (Topics `responses` und `errors`) den Wert `null` (JSON null) annehmen.
 
 == 4. Fehlerbehandlung und Validierung
-1. **Validierung (Dispatcher):** Die MQTT-Payloads werden durch das in [`SignalduinoCommands.COMMAND_MAP`](signalduino/commands.py) definierte `schema` (z.B. `FREQ_SCHEMA`, `DATARATE_SCHEMA`) vor dem Aufruf der Controller-Methode validiert.
-2. **Serial-Kommunikation:** `SignalduinoCommands._send_command` wird bei Timeout eine `SignalduinoCommandTimeout` werfen. Diese wird im `SignalduinoController` gefangen und als NACK-Statusmeldung zurückgegeben.
-3. **`cc1101_write_init`:** Nach jedem Set-Vorgang muss `SignalduinoCommands.cc1101_write_init()` aufgerufen werden, um die CC1101-Konfiguration erneut in das Chip-Register zu schreiben und die Änderungen zu aktivieren.
+. **Validierung (Dispatcher):** Die MQTT-Payloads werden durch das in [`SignalduinoCommands.COMMAND_MAP`](signalduino/commands.py) definierte `schema` (z.B. `FREQ_SCHEMA`, `DATARATE_SCHEMA`) vor dem Aufruf der Controller-Methode validiert.
+. **Serial-Kommunikation:** `SignalduinoCommands._send_command` wird bei Timeout eine `SignalduinoCommandTimeout` werfen. Diese wird im `SignalduinoController` gefangen und als NACK-Statusmeldung zurückgegeben.
+. **`cc1101_write_init`:** Nach jedem Set-Vorgang muss `SignalduinoCommands.cc1101_write_init()` aufgerufen werden, um die CC1101-Konfiguration erneut in das Chip-Register zu schreiben und die Änderungen zu aktivieren.
 
 == 5. Teststrategie
 * **Unit Tests (`tests/test_mqtt_cc1101.py` oder neu: `tests/test_set_commands.py`):**

docs/index.adoc

@@ -1,8 +1,10 @@
 = SIGNALduino - Projektübersicht
 :doctype: book :homepage: index.html :description: Der SIGNALduino ist ein vielseitiges Funkmodul zum Empfangen und Senden von 433/868MHz Signalen in Smart-Home-Umgebungen wie FHEM.
-Er dient als Signal-Transceiver und Protokolldekoder. :keywords: SIGNALduino, FHEM, 433MHz, 868MHz, Smart Home, Funkprotokolle, DIY, Arduino, ESP32 :toc: left :toclevels: 2
+:keywords: SIGNALduino, FHEM, 433MHz, 868MHz, Smart Home, Funkprotokolle, DIY, Arduino, ESP32 :toc: left :toclevels: 2
 :experimental:
 
+Er dient als Signal-Transceiver und Protokolldekoder.
+
 [[section-uebersicht]]
 == Zweck und Funktion
 
@@ -13,9 +15,9 @@ Dadurch werden verschiedenste proprietäre Funkprotokolle für die Nutzung in Sm
 
 Die verfügbare Hardware-Basis reicht von einfachen Arduino/nanoCUL-Lösungen bis hin zu erweiterten Varianten wie dem Maple-SignalDuino und dem ESP32-SignalDuino, die erweiterte Funktionen (z.B. WLAN) bieten.
 
+.Übersicht: Hardware und Funktion
 [NOTE]
 ====
-== Übersicht: Hardware und Funktion
 
 [mermaid]
 ----