Add sleep mode and documentation

- Sleep/wake endpoints for Home Assistant webhooks
- Sleep state: dim ( -_-)zzZ with slow breathing animation
- Updated CLAUDE.md with full technical reference
- Added README.md with user guide and HA integration examples

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

aggregator.py

@@ -53,11 +53,29 @@ last_emote_change = 0
 current_optimal_emote = OPTIMAL_EMOTES[0][0]
 current_optimal_animation = OPTIMAL_EMOTES[0][1]
 
+# Sleep mode
+is_sleeping = False
+SLEEP_EMOTE = "( -_-)zzZ"
+SLEEP_COLOR = "#333333"
+SLEEP_ANIMATION = "sleeping"
+
 
 def get_current_state():
     """Determine current state based on active events."""
     global previous_priority, celebrating_until, last_emote_change, current_optimal_emote, current_optimal_animation
 
+    # Sleep mode overrides everything
+    if is_sleeping:
+        return {
+            "current_state": "sleeping",
+            "active_emote": SLEEP_EMOTE,
+            "color": SLEEP_COLOR,
+            "animation": SLEEP_ANIMATION,
+            "message": "",
+            "active_events": [],
+            "last_updated": datetime.now().isoformat(timespec="seconds"),
+        }
+
     now = time.time()
 
     with events_lock:
@@ -196,6 +214,24 @@ def clear_event():
             return jsonify({"error": "Event not found"}), 404
 
 
+@app.route("/sleep", methods=["POST"])
+def sleep_mode():
+    """Enter sleep mode. For Home Assistant webhook."""
+    global is_sleeping
+    is_sleeping = True
+    state = write_status()
+    return jsonify({"status": "sleeping", "current_state": state}), 200
+
+
+@app.route("/wake", methods=["POST"])
+def wake_mode():
+    """Exit sleep mode. For Home Assistant webhook."""
+    global is_sleeping
+    is_sleeping = False
+    state = write_status()
+    return jsonify({"status": "awake", "current_state": state}), 200
+
+
 @app.route("/")
 def index():
     """Serve the frontend."""