### Markdown Documentation (`docs/AHK_SCRIPTS.md`)

# AutoHotkey Infrastructure for SL5-Aura-Service

Because Windows handles file locks and system hotkeys differently than Linux, this project uses a set of AutoHotkey (v2) scripts to bridge the gap between the Python STT engine and the Windows User Interface.

## Overview of Scripts

### 1. `trigger-hotkeys.ahk`
*   **Purpose:** The main user interface for controlling the service.
*   **Key Features:** 
    *   Intercepts **F10** and **F11** to start/stop dictation.
    *   Uses a `Keyboard Hook` to override default Windows system behavior (e.g., F10 activating the menu bar).
    *   **Deployment:** Designed to be registered via the Windows Task Scheduler with "Highest Privileges" so it can capture hotkeys even when the user is working in an Administrator-level application.

### 2. `type_watcher.ahk`
*   **Purpose:** Acts as the "Consumer" in the STT pipeline. 
*   **Key Features:**
    *   Watches a temporary directory for incoming `.txt` files generated by the Python engine.
    *   **State Machine (Zombie Map):** Implements a memory-based map to ensure each file is typed exactly once. This prevents "double-typing" caused by redundant Windows file-system events (Added/Modified).
    *   **Safe Typing:** Uses `SendText` to ensure special characters are handled correctly in any active editor.
    *   **Reliable Cleanup:** Manages file deletion with a retry-logic to handle Windows file-access locks.

### 3. `scripts/ahk/sync_editor.ahk`
*   **Purpose:** Ensures seamless synchronization between the disk and the text editor (e.g., Notepad++).
*   **Key Features:**
    *   **Save-on-Demand:** Can be triggered by Python to force a `Ctrl+S` in the editor before the engine reads the file.
    *   **Dialog Automator:** Automatically detects and confirms "File modified by another program" reload dialogs, creating a fluid real-time update experience.
    *   **Visual Feedback:** Provides short-lived notification boxes to inform the user that corrections are being applied.

### 4. `scripts/notification_watcher.ahk`
*   **Purpose:** Provides UI feedback for background processes.
*   **Key Features:**
    *   Monitors specific status files or events to display notifications to the user.
    *   Decouples the logic of "calculating" a message (Python) from "displaying" it (AHK), ensuring the main STT engine isn't blocked by UI interactions.


---

### Non-Admin Fallback
If the application is run without Administrator privileges:
 - **Functionality:** The service remains fully functional.
 - **Hotkey Limitations:** System-reserved keys like **F10** may still trigger the Windows menu. In this case, it is recommended to change the hotkeys to non-system keys (e.g., `F9` or `Insert`).
 - **Task Scheduler:** If the "AuraDictation_Hotkeys" task was created during an Admin-install, the script will run with high privileges even for a standard user. If not, the `start_dictation.bat` will launch a local user-level instance silently.

---

### 3. Warum "nervige Meldungen" erscheinen und wie man sie im AHK-Code stoppt
Um sicherzustellen, dass das Skript selbst niemals den Nutzer mit Popups stört, füge diese "Silent-Flags" oben in deine `.ahk` Dateien ein:

```autohotkey
#Requires AutoHotkey v2.0
#SingleInstance Force   ; Ersetzt alte Instanzen ohne zu fragen
#NoTrayIcon            ; (Optional) Wenn du kein Icon im Tray willst
ListLines(False)       ; Erhöht Performance und verbirgt Debug-Logs
```

### 4. Strategie für die Hotkeys (F10 Alternative)
Da F10 ohne Admin-Rechte unter Windows fast unmöglich sauber abzufangen ist, könntest du im `trigger-hotkeys.ahk` eine Weiche einbauen:

```autohotkey
if !A_IsAdmin {
    ; Wenn kein Admin, warne den Entwickler im Log
    ; Log("Running without Admin - F10 might be unreliable")
}

; Nutze Wildcards, um die Chance zu erhöhen, dass es auch ohne Admin klappt
*$f10::
{
    ; ... Logik
}
```

### Zusammenfassung der Verbesserungen:
1.  **Batch-Datei:** Nutzt `start "" /b`, um das schwarze Fenster zu vermeiden, und prüft vorher, ob der Admin-Task schon läuft.
2.  **Transparenz:** Die Doku erklärt nun offen: "Kein Admin? Kein Problem, nimm einfach eine andere Taste als F10".
3.  **AHK-Skript:** Nutzt `#SingleInstance Force`, um den "An older instance is running"-Dialog zu unterdrücken.

Damit wirkt die Software viel professioneller ("Smooth"), da sie im Hintergrund startet, ohne dass der Nutzer mit technischen Details oder Bestätigungsfenstern konfrontiert wird.
    
    
---

### Why this Documentation is important:
By documenting the **"Zombie Map"** and the **"Task Scheduler/Admin"** requirement, you explain to other developers (and your future self) why the code is more complex than a simple Linux script. It turns "weird workarounds" into "engineered solutions for Windows limitations."

(s,29.1.'26 11:02 Thu)