docs: complete 100% kdoc coverage and update app branding

shared/src/main/kotlin/com/example/retroha/i18n/StringKey.kt

@@ -1,50 +1,102 @@
 package com.example.retroha.i18n
+
+/**
+ * Universal identifiers for translatable strings used across the application.
+ * Each key maps to a localized string in the platform-specific implementation.
+ */
 enum class StringKey {
+    /** Label for 'ON' state. */
     STATE_ON,
+    /** Label for 'OFF' state. */
     STATE_OFF,
+    /** Label for 'UNAVAILABLE' state. */
     STATE_UNAVAILABLE,
+    /** Label for transitioning state. */
     STATE_TOGGLING,
+    /** Button text for Settings. */
     BTN_SETTINGS,
+    /** Placeholder toast for adding widgets. */
     TOAST_WIDGET_ADD,
+    /** Tab label: All. */
     TAB_ALL,
+    /** Tab label: Lighting. */
     TAB_LIGHTING,
+    /** Tab label: Sockets. */
     TAB_SOCKETS,
+    /** Tab label: Power. */
     TAB_POWER,
+    /** Tab label: Weather. */
     TAB_WEATHER,
+    /** Title for entity selection screen. */
     TITLE_SETTINGS,
+    /** Title for connection configuration screen. */
     TITLE_CONNECTION,
+    /** Title for user manual screen. */
     TITLE_INSTRUCTIONS,
+    /** Instruction line 1. */
     INSTRUCTION_1,
+    /** Instruction line 2. */
     INSTRUCTION_2,
+    /** Instruction line 3. */
     INSTRUCTION_3,
+    /** Instruction line 4. */
     INSTRUCTION_4,
+    /** Instruction line 5. */
     INSTRUCTION_5,
+    /** Input label for URL. */
     LABEL_URL,
+    /** Input label for Access Token. */
     LABEL_TOKEN,
+    /** Input label for refresh interval. */
     LABEL_REFRESH,
+    /** Button text for testing and saving connection. */
     BTN_TEST_SAVE,
+    /** Button text for deleting all widgets. */
     BTN_DELETE_ALL,
+    /** Button text for saving selected entities. */
     BTN_SAVE_SELECTED,
+    /** Button text for language change. */
     BTN_CHANGE_LANG,
+    /** Status: Connecting. */
     STATUS_CONNECTING,
+    /** Status: Successfully connected / Online. */
     STATUS_CONNECTED,
+    /** Status: Offline. */
     STATUS_OFFLINE,
+    /** Status error: Home Assistant reported an error. */
     STATUS_ERROR_HA,
+    /** Status error: Authentication token missing. */
     STATUS_NO_TOKEN,
+    /** Title for language selection screen. */
     TITLE_SELECT_LANGUAGE,
+    /** Toast: Refreshing data. */
     STATUS_REFRESHING,
+    /** Status: Success message. */
     STATUS_SUCCESS,
+    /** Toast: Configuration saved and widgets cleared. */
     TOAST_SAVED_CLEARED,
+    /** General error status. */
     STATUS_ERROR,
+    /** Network connection error status. */
     STATUS_ERROR_NETWORK,
+    /** Confirmation message for mass deletion. */
     CONFIRM_DELETE_ALL,
+    /** Warning message for connection change. */
     CONFIRM_CHANGE_CONN,
+    /** Label for brightness level. */
     DIALOG_BRIGHTNESS,
+    /** Dialog button: Set/Apply. */
     DIALOG_SET,
+    /** Dialog button: Cancel. */
     DIALOG_CANCEL,
+    /** Dialog title: Warning. */
     DIALOG_WARNING,
+    /** Dialog button: Confirm connection change. */
     DIALOG_YES_CHANGE,
+    /** Dialog button: Confirm deletion. */
     DIALOG_YES_DELETE,
+    /** Toast: Cache/Dashboard cleared. */
     TOAST_CLEARED,
+    /** Toast: Selected entities saved. */
     TOAST_ENTITIES_SAVED
 }

shared/src/main/kotlin/com/example/retroha/i18n/Strings.kt

@@ -1,4 +1,14 @@
 package com.example.retroha.i18n
+
+/**
+ * Interface defining the contract for retrieving localized strings.
+ * This allows the business logic to remain platform-independent.
+ */
 interface Strings {
+    /**
+     * Retrieves a localized string for the given key.
+     * @param key The universal string identifier.
+     * @return The localized text for the current application language.
+     */
     operator fun get(key: StringKey): String
 }

shared/src/main/kotlin/com/example/retroha/model/EntityState.kt

@@ -1,2 +1,16 @@
 package com.example.retroha.model
-enum class EntityState { ON, OFF, UNAVAILABLE, TOGGLING }
+
+/**
+ * Represents the fundamental visual and logical states of a Home Assistant entity.
+ * Used by the UI layer to determine colors and animations.
+ */
+enum class EntityState {
+    /** Entity is active (e.g., light is on, switch is closed). */
+    ON,
+    /** Entity is inactive (e.g., light is off, switch is open). */
+    OFF,
+    /** Entity is disconnected or its state cannot be determined. */
+    UNAVAILABLE,
+    /** Entity is currently transitioning between states (e.g., command sent but not confirmed). */
+    TOGGLING
+}

shared/src/main/kotlin/com/example/retroha/model/WidgetConfig.kt

@@ -1,4 +1,18 @@
 package com.example.retroha.model
+
+/**
+ * Data configuration class for a UI widget.
+ * Holds all necessary information to render a Home Assistant entity on the dashboard.
+ *
+ * @property id Unique local identifier for the widget instance.
+ * @property entityId The full Home Assistant entity ID (e.g., "light.living_room").
+ * @property label The display name shown on the card top section.
+ * @property value The primary state value or measurement (e.g., "ON", "21.5°C").
+ * @property secondary Subtitle or additional info (e.g., battery level, wattage).
+ * @property domain The HA domain (light, switch, sensor, etc.) used for icon selection.
+ * @property state Current logical state for UI coloring and animations.
+ * @property brightness Optional brightness value (0-255) for light-domain entities.
+ */
 data class WidgetConfig(
     val id: Long,
     val entityId: String,

shared/src/main/kotlin/com/example/retroha/model/WidgetInteraction.kt

@@ -1,5 +1,22 @@
 package com.example.retroha.model
-enum class WidgetInteraction { TOGGLE, EXECUTE, READ_ONLY }
+
+/**
+ * Defines the type of user interaction supported by a widget.
+ */
+enum class WidgetInteraction { 
+    /** Supports switching between ON and OFF states. */
+    TOGGLE, 
+    /** Supports one-shot execution (e.g., triggering a script). */
+    EXECUTE, 
+    /** Information only, no user interaction allowed. */
+    READ_ONLY 
+}
+
+/**
+ * Maps a Home Assistant domain string to its appropriate [WidgetInteraction] type.
+ * 
+ * @return The interaction type (TOGGLE, EXECUTE, or READ_ONLY) based on the domain logic.
+ */
 fun String.toWidgetInteraction(): WidgetInteraction = when (this) {
     "light",
     "switch",

shared/src/main/kotlin/com/example/retroha/theme/Colors.kt

@@ -1,28 +1,65 @@
 package com.example.retroha.theme
+
+/**
+ * Bauhaus-inspired color palette for the application.
+ * All colors are defined as ARGB integers.
+ */
 object Colors {
+    /** Pure black for borders, shadows, and text. */
     const val BLACK  = 0xFF000000.toInt()
+    /** Pure white for backgrounds and default states. */
     const val WHITE  = 0xFFFFFFFF.toInt()
+    /** Bauhaus red. Used for scripts and high-priority states. */
     const val RED    = 0xFFE23A24.toInt()
+    /** Bauhaus yellow. Used for active (ON) highlights. */
     const val YELLOW = 0xFFFAD02C.toInt()
+    /** Bauhaus blue. Used for switches and interactive elements. */
     const val BLUE   = 0xFF0056B3.toInt()
+    /** Bauhaus orange. Used for light-domain entities. */
     const val ORANGE = 0xFFF4801A.toInt()
+    /** Bauhaus green. Secondary status color. */
     const val GREEN  = 0xFF2D7D46.toInt()
+    /** Bauhaus violet. Used for sensors and measurements. */
     const val VIOLET = 0xFF6B3FA0.toInt()
+    
+    /** Light gray for background elements. */
     const val GRAY_LIGHT = 0xFFCCCCCC.toInt()
+    /** Mid gray for disabled borders. */
     const val GRAY_MID   = 0xFF888888.toInt()
+    /** Dark gray for default category stripes. */
     const val GRAY_DARK  = 0xFF444444.toInt()
+
+    // Semantic status colors
+    /** Card background color when entity is ON. */
     const val STATUS_ON          = YELLOW      
+    /** Card background color when entity is OFF. */
     const val STATUS_OFF         = WHITE       
+    /** Card background color when entity is unavailable. */
     const val STATUS_UNAVAILABLE = GRAY_LIGHT  
+    /** Card background color during state transition. */
     const val STATUS_TOGGLING    = WHITE       
+
+    // Semantic border colors
+    /** Default card border color. */
     const val BORDER_DEFAULT     = BLACK
+    /** Border color during state transition. */
     const val BORDER_TOGGLING    = BLUE
+    /** Border color when entity is unavailable. */
     const val BORDER_UNAVAILABLE = GRAY_MID
+
+    // Domain-specific side stripes
+    /** Accent stripe for light domain. */
     const val STRIPE_LIGHT         = ORANGE  
+    /** Accent stripe for switch domain. */
     const val STRIPE_SWITCH        = BLUE
+    /** Accent stripe for sensor domain. */
     const val STRIPE_SENSOR        = VIOLET
+    /** Accent stripe for binary_sensor domain. */
     const val STRIPE_BINARY_SENSOR = VIOLET
+    /** Accent stripe for script domain. */
     const val STRIPE_SCRIPT        = RED
+    /** Accent stripe for automation domain. */
     const val STRIPE_AUTOMATION    = RED
+    /** Default accent stripe for unknown domains. */
     const val STRIPE_DEFAULT       = GRAY_DARK  
 }