fix: housekeeper API paths and entity hallucination prevention

- Update all client endpoints to use /housekeeping/ prefix
- Add critical rule requiring list_devices() before control actions
- Add housekeeping API spec documentation

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

src/agents/housekeeper/agent.py

@@ -74,21 +74,35 @@ Your role is to help users control and monitor their smart home through Home Ass
 ### History Tools
 - **get_history**: Check a device's state history
 
+## Critical Rules
+
+**NEVER GUESS ENTITY IDs.** You do not know what devices exist. Entity IDs vary between
+installations. You MUST call list_devices() FIRST to discover actual entity_ids before
+ANY control action (turn_on, turn_off, toggle).
+
+Wrong approach:
+  User: "Turn off the study lights"
+  You: turn_off("light.study")  ← WRONG! You guessed the entity_id
+
+Correct approach:
+  User: "Turn off the study lights"
+  You: list_devices(domain="light")  ← First discover what exists
+  You: [See results like light.study_main, light.study]
+  You: turn_off("light.study_main"), turn_off("light.study")  ← Use actual IDs
+
 ## Best Practices
 
-1. **Device Discovery First**: If the user asks about devices without being specific,
-   use list_devices to find what's available before acting.
+1. **ALWAYS list_devices first** before any control action. No exceptions.
+   Filter by domain and/or area to narrow results.
 
-2. **Confirm State After Actions**: After turning something on/off, you can verify
-   with get_device_state if needed.
+2. **Use exact entity_ids** from list_devices results. Never construct or guess them.
 
-3. **Use Entity IDs**: Devices are identified by entity_id (e.g., light.living_room).
-   Always use the exact entity_id from list_devices.
+3. **Area-aware filtering**: Use area parameter when users mention a room.
+   Note: Some devices may have area=None but contain the room name in entity_id.
 
-4. **Area-Aware**: When users say "living room lights", filter by area="living_room".
+4. **Verify after actions**: Use get_device_state to confirm state changes if needed.
 
-5. **Safety**: For actions affecting multiple devices or automations, summarize
-   what you're about to do.
+5. **Safety for bulk actions**: When affecting multiple devices, summarize first.
 
 ## Common Patterns
 

src/agents/housekeeper/client.py

@@ -182,7 +182,7 @@ class CoreAPIClient:
 
         logger.debug("core_api_list_devices", domain=domain, area=area)
 
-        response = await client.get("/devices", params=params or None)
+        response = await client.get("/housekeeping/devices", params=params or None)
         response.raise_for_status()
 
         data = response.json()
@@ -199,7 +199,7 @@ class CoreAPIClient:
 
         logger.debug("core_api_list_areas")
 
-        response = await client.get("/areas")
+        response = await client.get("/housekeeping/areas")
         response.raise_for_status()
 
         data = response.json()
@@ -219,7 +219,7 @@ class CoreAPIClient:
 
         logger.debug("core_api_get_state", entity_id=entity_id)
 
-        response = await client.get(f"/entities/{entity_id}")
+        response = await client.get(f"/housekeeping/devices/{entity_id}")
         response.raise_for_status()
 
         return DeviceState(**response.json())
@@ -260,7 +260,7 @@ class CoreAPIClient:
         logger.info("core_api_turn_on", entity_id=entity_id, payload=payload)
 
         response = await client.post(
-            f"/devices/{entity_id}/control",
+            f"/housekeeping/devices/{entity_id}/control",
             json=payload,
         )
         response.raise_for_status()
@@ -288,7 +288,7 @@ class CoreAPIClient:
         logger.info("core_api_turn_off", entity_id=entity_id)
 
         response = await client.post(
-            f"/devices/{entity_id}/control",
+            f"/housekeeping/devices/{entity_id}/control",
             json={"action": "turn_off"},
         )
         response.raise_for_status()
@@ -316,7 +316,7 @@ class CoreAPIClient:
         logger.info("core_api_toggle", entity_id=entity_id)
 
         response = await client.post(
-            f"/devices/{entity_id}/control",
+            f"/housekeeping/devices/{entity_id}/control",
             json={"action": "toggle"},
         )
         response.raise_for_status()
@@ -344,7 +344,7 @@ class CoreAPIClient:
 
         logger.debug("core_api_list_scenes")
 
-        response = await client.get("/scenes")
+        response = await client.get("/housekeeping/scenes")
         response.raise_for_status()
 
         data = response.json()
@@ -364,7 +364,7 @@ class CoreAPIClient:
 
         logger.info("core_api_activate_scene", scene_id=scene_id)
 
-        response = await client.post(f"/scenes/{scene_id}/activate")
+        response = await client.post(f"/housekeeping/scenes/{scene_id}/activate")
         response.raise_for_status()
 
         data = response.json()
@@ -390,7 +390,7 @@ class CoreAPIClient:
 
         logger.debug("core_api_list_scripts")
 
-        response = await client.get("/scripts")
+        response = await client.get("/housekeeping/scripts")
         response.raise_for_status()
 
         data = response.json()
@@ -420,7 +420,7 @@ class CoreAPIClient:
         logger.info("core_api_run_script", script_id=script_id)
 
         response = await client.post(
-            f"/scripts/{script_id}/run",
+            f"/housekeeping/scripts/{script_id}/run",
             json=payload or None,
         )
         response.raise_for_status()
@@ -448,7 +448,7 @@ class CoreAPIClient:
 
         logger.debug("core_api_list_automations")
 
-        response = await client.get("/automations")
+        response = await client.get("/housekeeping/automations")
         response.raise_for_status()
 
         data = response.json()
@@ -478,7 +478,7 @@ class CoreAPIClient:
         )
 
         response = await client.post(
-            f"/automations/{automation_id}/toggle",
+            f"/housekeeping/automations/{automation_id}/toggle",
             json={"enable": enable},
         )
         response.raise_for_status()
@@ -515,7 +515,7 @@ class CoreAPIClient:
         logger.debug("core_api_get_history", entity_id=entity_id, hours=hours)
 
         response = await client.get(
-            "/history",
+            "/housekeeping/history",
             params={"entity_id": entity_id, "hours": hours},
         )
         response.raise_for_status()
@@ -536,7 +536,7 @@ class CoreAPIClient:
         """
         try:
             client = self._ensure_client()
-            response = await client.get("/health")
+            response = await client.get("/housekeeping/health")
             return response.status_code == 200
         except Exception as e:
             logger.warning("core_api_health_check_failed", error=str(e))