Update documentation

Author: jfmlima

README.md

@@ -17,6 +17,9 @@ Manage Shelly devices on your local network without connecting them to the Shell
 - Device configuration changes
 - Bulk operations across multiple devices
 - Status monitoring
+- Component action discovery and execution
+- Dynamic device capability detection  
+- Component-specific controls (switches, covers, lights, etc.)
 
 Available as:
 
@@ -133,13 +136,17 @@ GET /api/health                    # Service health check
 GET /api/devices/scan              # Discover devices on network
 GET /api/devices/{ip}/status       # Get device status
 
-# Device operations
+# Device operations  
 POST /api/devices/{ip}/update      # Update device firmware
 POST /api/devices/{ip}/reboot      # Reboot device
 POST /api/devices/bulk/update      # Bulk firmware updates
 
+# Component Actions
+GET /api/devices/{ip}/components/actions           # Discover available actions
+POST /api/devices/{ip}/components/{id}/action      # Execute component action
+
 # Configuration management
-GET /api/devices/{ip}/config       # Get device configuration
+GET /api/devices/{ip}/config       # Get device configuration  
 POST /api/devices/{ip}/config      # Update device configuration
 ```
 

packages/api/README.md

@@ -63,13 +63,17 @@ GET /api/devices/scan              # Scan network for devices
 GET /api/devices/{ip}/status       # Get device status
   ?include_updates=true            # Include update information
 
-POST /api/devices/{ip}/update      # Update device firmware
+POST /api/devices/{ip}/update      # Update device firmware  
   ?channel=stable                  # Update channel (stable/beta)
 
 POST /api/devices/{ip}/reboot      # Reboot device
 
 POST /api/devices/bulk/update      # Bulk firmware updates
   # Body: {"device_ips": ["192.168.1.100", "192.168.1.101"], "channel": "stable"}
+
+# Component Actions
+GET /api/devices/{ip}/components/actions           # Discover available actions
+POST /api/devices/{ip}/components/{id}/action      # Execute component action
 ```
 
 ### Configuration Management
@@ -83,6 +87,21 @@ GET /api/config                    # Get global configuration
 PUT /api/config                    # Update global configuration
 ```
 
+### Component Actions
+
+The Component Actions system provides dynamic action discovery and execution for individual device components.
+
+#### Discovery
+```bash
+GET /api/devices/{ip}/components/actions    # Get all available actions for device
+```
+
+
+#### Execute Component Action
+```bash
+POST /api/devices/{ip}/components/{component_id}/action
+```
+
 ### Monitoring (Future)
 
 ```bash
@@ -131,6 +150,73 @@ curl -X POST "http://localhost:8000/api/devices/192.168.1.100/update?channel=sta
 }
 ```
 
+### Component Actions Examples
+
+#### Discover Device Actions
+```bash
+curl "http://localhost:8000/api/devices/192.168.1.100/components/actions"
+```
+
+**Response Example:**
+```json
+{
+  "device_ip": "192.168.1.100",
+  "components": [
+    {
+      "component_id": "switch:0",
+      "component_type": "switch", 
+      "available_actions": [
+        {
+          "action": "toggle",
+          "description": "Toggle switch state",
+          "parameters": {}
+        },
+        {
+          "action": "turn_on", 
+          "description": "Turn switch on",
+          "parameters": {}
+        }
+      ]
+    }
+  ]
+}
+```
+
+#### Toggle a Switch
+```bash
+curl -X POST "http://localhost:8000/api/devices/192.168.1.100/components/switch:0/action" \
+  -H "Content-Type: application/json" \
+  -d '{"action": "toggle", "params": {}}'
+```
+
+**Request Body:**
+```json
+{
+  "action": "toggle",
+  "params": {}
+}
+```
+
+**Response:**
+```json
+{
+  "ip": "192.168.1.100",
+  "component_id": "switch:0", 
+  "action": "toggle",
+  "success": true,
+  "result": {
+    "new_state": "on"
+  }
+}
+```
+
+#### Open a Cover
+```bash
+curl -X POST "http://localhost:8000/api/devices/192.168.1.100/components/cover:0/action" \
+  -H "Content-Type: application/json" \
+  -d '{"action": "open", "params": {}}'
+```
+
 ### Error Response
 
 ```json

packages/cli/README.md

@@ -376,7 +376,7 @@ uv run --package shelly-manager-cli pytest packages/cli/tests/unit/use_cases/ -v
 uv run --package shelly-manager-cli pytest packages/cli/tests/ --cov=cli --cov-report=html
 ```
 
-Detailed testing documentation: [tests/README.md](tests/README.md)
+**Testing Documentation**: Tests are located in `packages/cli/tests/` with unit tests for commands and use cases.
 
 ## Architecture
 

packages/core/README.md

@@ -11,6 +11,7 @@ Contains the core business logic that defines how Shelly Manager works. Framewor
 - Domain models for Shelly devices and operations
 - Business rules for device management
 - Use cases that orchestrate operations (scan, update, reboot)
+- Component action discovery and execution use cases
 - Gateway contracts for external dependencies
 - No dependencies on frameworks, databases, or UI
 
@@ -29,6 +30,8 @@ packages/core/src/core/
 │   ├── scan_devices.py      # Device discovery
 │   ├── update_device_firmware.py
 │   ├── reboot_device.py
+│   ├── execute_component_action.py    # Component action execution
+│   ├── get_component_actions.py       # Component action discovery
 │   └── ...
 ├── gateways/                 # External interfaces (abstract)
 │   ├── device/              # Device communication contracts