Add TODO.md and reframe CLAUDE.md around REST-push philosophy

Kao is a display, not a monitor — external systems push events via REST
rather than Kao polling things itself. Update CLAUDE.md to reflect this:
- New Design Philosophy section making the REST-first approach explicit
- Architecture diagram updated to show external systems as the push source
- Detectors section demoted to "Legacy Detectors" with a note to prefer push
- TODO.md added with planned REST API improvements (SSE, notify queue,
  sticky notifications, named presets, batch notify, /history endpoint)
  and display improvements (brightness curve, scrolling ticker)

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -8,23 +8,29 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Kao is a minimalist system status monitor designed for an old Pixel phone used as an ambient display. It uses ASCII "emotes" to represent system health instead of complex graphs.
+Kao is a minimalist ambient display for an old Pixel phone. It uses ASCII "emotes" to represent system health instead of graphs or dashboards. External systems (Home Assistant, Uptime Kuma, scripts, etc.) push events and notifications to Kao via REST — Kao itself does not poll or monitor anything.
+
+## Design Philosophy
+
+**Kao is a display, not a monitor.** It should not duplicate work that other tools already do. The right pattern is: your existing monitoring stack detects a problem, then POSTs to Kao to show it. This keeps Kao simple and lets each tool do what it's good at.
+
+The bundled `detectors/` scripts are legacy and exist for standalone use cases. New work should focus on making the REST API richer, not adding more detectors.
 
 ## Architecture
 
-**Publisher/Subscriber model:**
+**REST push model:**
 
 ```
-┌─────────────┐     POST /event      ┌─────────────┐     GET /status     ┌─────────────┐
-│  Detectors  │ ──────────────────▶  │  Aggregator │ ◀────────────────── │   Emote-UI  │
-│  (sensors)  │                      │   (broker)  │                     │  (display)  │
-└─────────────┘                      └─────────────┘                     └─────────────┘
+┌─────────────────────┐     POST /event      ┌─────────────┐     GET /status     ┌─────────────┐
+│  External systems   │ ──────────────────▶  │  Aggregator │ ◀────────────────── │   Emote-UI  │
+│  (HA, scripts, etc) │     POST /notify     │   (broker)  │                     │  (display)  │
+└─────────────────────┘                      └─────────────┘                     └─────────────┘
 ```
 
 - **Aggregator** (`aggregator.py`) — Flask service managing the event queue and priority logic
-- **Detectors** (`detectors/*.py`) — Independent scripts monitoring system metrics
 - **Emote-UI** (`index.html`) — OLED-optimized web frontend
 - **Sentry** (`kao.py`) — Unified entry point managing all processes
+- **Detectors** (`detectors/*.py`) — Legacy standalone sensors; prefer REST push from existing tools
 
 ## Quick Start
 
@@ -56,7 +62,9 @@ Edit `config.json` to configure detectors:
 }
 ```
 
-## Detectors
+## Legacy Detectors
+
+These bundled scripts exist for standalone use but are not the preferred approach. Prefer pushing from Home Assistant, Uptime Kuma, or any tool that already monitors what you care about.
 
 | Detector | Script | Required Env Vars |
 |----------|--------|-------------------|
@@ -188,5 +196,6 @@ Use in automations:
 │   ├── network.py
 │   └── docker.py
 ├── requirements.txt
+├── TODO.md             # Planned features and improvements
 └── SPEC.md             # Original project specification
 ```

TODO.md

@@ -0,0 +1,26 @@
+# Kao — TODO
+
+Feature ideas for future work, roughly in priority order.
+
+## REST API improvements
+
+- **`/status` SSE stream** — replace frontend polling with a Server-Sent Events
+  endpoint so the display reacts instantly and the 2s polling overhead disappears
+- **Notification queue** — buffer rapid `/notify` calls and auto-advance through
+  them instead of clobbering; important when HA fires several events at once
+- **Sticky notifications** — a `sticky: true` flag on `/notify` to keep a
+  notification visible until explicitly cleared via `/clear`, rather than TTL-expiring
+- **Named presets** — define reusable notification profiles in `config.json`
+  (e.g. `"doorbell"` → specific emote/sound/color/duration) so callers can
+  POST `{"preset": "doorbell"}` without repeating fields every time
+- **Batch `/notify`** — accept an array in a single POST so multiple
+  notifications can be queued atomically
+- **`/history` endpoint** — a ring buffer of the last N state changes/events
+  received, for auditing what fired overnight without tailing logs
+
+## Display / frontend
+
+- **Brightness curve** — dim gradually after dark rather than hard-sleeping;
+  reduces OLED burn-in without losing glanceability
+- **Scrolling ticker** — when multiple events are active, cycle through their
+  messages rather than only showing the top one