docs: expand documentation with comprehensive tools and development guides

- Add detailed documentation for various tools and management interfaces
- Create development best practices and interface documentation
- Expand tools section with device management, automation, and event subscription guides
- Include configuration, usage examples, and error handling for each tool
- Update MkDocs navigation to reflect new documentation structure

docs/tools/history-state/scene.md

@@ -0,0 +1,215 @@
+# Scene Management Tool
+
+The Scene Management tool provides functionality to manage and control scenes in your Home Assistant instance.
+
+## Features
+
+- List available scenes
+- Activate scenes
+- Create new scenes
+- Update existing scenes
+- Delete scenes
+- Get scene state information
+
+## Usage
+
+### REST API
+
+```typescript
+GET /api/scenes
+GET /api/scenes/{scene_id}
+POST /api/scenes/{scene_id}/activate
+POST /api/scenes
+PUT /api/scenes/{scene_id}
+DELETE /api/scenes/{scene_id}
+```
+
+### WebSocket
+
+```typescript
+// List scenes
+{
+    "type": "get_scenes"
+}
+
+// Activate scene
+{
+    "type": "activate_scene",
+    "scene_id": "required_scene_id"
+}
+
+// Create/Update scene
+{
+    "type": "create_scene",
+    "scene": {
+        "name": "required_scene_name",
+        "entities": {
+            // Entity states
+        }
+    }
+}
+```
+
+## Scene Configuration
+
+### Scene Definition
+
+```json
+{
+    "name": "Movie Night",
+    "entities": {
+        "light.living_room": {
+            "state": "on",
+            "brightness": 50,
+            "color_temp": 2700
+        },
+        "cover.living_room": {
+            "state": "closed"
+        },
+        "media_player.tv": {
+            "state": "on",
+            "source": "HDMI 1"
+        }
+    }
+}
+```
+
+## Examples
+
+### List All Scenes
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/scenes', {
+    headers: {
+        'Authorization': 'Bearer your_access_token'
+    }
+});
+const scenes = await response.json();
+```
+
+### Activate a Scene
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/scenes/movie_night/activate', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token'
+    }
+});
+```
+
+### Create a New Scene
+
+```typescript
+const response = await fetch('http://your-ha-mcp/api/scenes', {
+    method: 'POST',
+    headers: {
+        'Authorization': 'Bearer your_access_token',
+        'Content-Type': 'application/json'
+    },
+    body: JSON.stringify({
+        "name": "Movie Night",
+        "entities": {
+            "light.living_room": {
+                "state": "on",
+                "brightness": 50
+            },
+            "cover.living_room": {
+                "state": "closed"
+            }
+        }
+    })
+});
+```
+
+## Response Format
+
+### Scene List Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "scenes": [
+            {
+                "id": "scene_id",
+                "name": "Scene Name",
+                "entities": {
+                    // Entity configurations
+                }
+            }
+        ]
+    }
+}
+```
+
+### Scene Activation Response
+
+```json
+{
+    "success": true,
+    "data": {
+        "scene_id": "activated_scene_id",
+        "status": "activated",
+        "timestamp": "2024-02-05T12:00:00Z"
+    }
+}
+```
+
+## Error Handling
+
+### Common Error Codes
+
+- `404`: Scene not found
+- `401`: Unauthorized
+- `400`: Invalid scene configuration
+- `409`: Scene activation failed
+
+### Error Response Format
+
+```json
+{
+    "success": false,
+    "message": "Error description",
+    "error_code": "ERROR_CODE"
+}
+```
+
+## Rate Limiting
+
+- Default limit: 50 requests per 15 minutes
+- Configurable through environment variables:
+  - `SCENE_RATE_LIMIT`
+  - `SCENE_RATE_WINDOW`
+
+## Best Practices
+
+1. Validate entity availability before creating scenes
+2. Use meaningful scene names
+3. Group related entities in scenes
+4. Implement proper error handling
+5. Cache scene configurations when possible
+6. Handle rate limiting gracefully
+
+## Scene Transitions
+
+Scenes can include transition settings for smooth state changes:
+
+```json
+{
+    "name": "Sunset Mode",
+    "entities": {
+        "light.living_room": {
+            "state": "on",
+            "brightness": 128,
+            "transition": 5  // 5 seconds
+        }
+    }
+}
+```
+
+## See Also
+
+- [Device Control](../device-management/control.md)
+- [Device History](history.md)
+- [Automation Management](../automation/automation.md)