# SPEC.md: Project "Sentry-Emote"

## 1. Overview

**Purpose:** Repurpose an old Pixel phone (OLED screen) as an ambient, glanceable system status monitor for a home server.
**Design Philosophy:** Minimalist, binary-state, and high-signal. Use an "Emote" (ASCII/Emoji) to represent system health instead of complex graphs.
**Target Device:** Android Pixel (accessed via Fully Kiosk Browser).

## 2. System Architecture

The system follows a decoupled **Publisher/Subscriber** model to ensure extensibility.

- **Aggregator (The Broker):** A central Python service running on the server. It manages the event queue and generates the state.
- **Detectors (The Publishers):** Independent scripts (Python, Bash, etc.) that monitor specific system metrics and "hook" into the Aggregator.
- **Emote-UI (The Subscriber):** A mobile-optimized web frontend that displays the current highest-priority emote.

## 3. Data Specification

### 3.1 `status.json` (State Registry)

The Aggregator outputs this file every time the state changes.

```json
{
	"current_state": "optimal",
	"active_emote": "( ^_^)",
	"color": "#00FF00",
	"animation": "breathing",
	"message": "All systems nominal",
	"active_events": [
		{
			"id": "disk_check",
			"priority": 4,
			"message": "Disk 40% full"
		}
	],
	"last_updated": "2026-02-02T17:30:00"
}
```

### 3.2 Priority Hierarchy

| Level | Name         | Priority  | Emote    | Color  | Logic                                    |
| ----- | ------------ | --------- | -------- | ------ | ---------------------------------------- |
| **1** | **Critical** | Emergency | `( x_x)` | Red    | Overrules all. Manual clear required.    |
| **2** | **Warning**  | Caution   | `( o_o)` | Yellow | Overrules Optimal. Auto-clears if fixed. |
| **3** | **Notify**   | Event     | `( 'o')` | Blue   | Transient. TTL (Time To Live) of 10s.    |
| **4** | **Optimal**  | Default   | `( ^_^)` | Green  | Active when no other events exist.       |

## 4. Component Requirements

### 4.1 Aggregator (`aggregator.py`)

- **Event Bus:** Accept HTTP POST requests or watch a specific file/directory for new event signals.
- **State Management:** Maintain a list of "Active Events."
- **TTL Logic:** Automatically remove Priority 3 events after 10 seconds.
- **Deduplication:** If multiple events exist, always select the one with the lowest priority number for the `active_emote` field.

### 4.2 Emote-UI (`index.html`)

- **OLED Optimization:** Pure black background (`#000000`).
- **Glanceability:** Massive centered text for the emote.
- **Animations:** - `breathing`: Slow opacity/scale pulse.
- `shaking`: Rapid X-axis jitter for Critical.
- `popping`: Scale-up effect for Notifications.

- **Refresh:** Long-polling or `setInterval` every 2 seconds.

### 4.3 Extensibility (The Hook System)

- New detectors must be able to send an event to the Aggregator without modifying the core code.
- Example Detector Hook: `curl -X POST -d '{"id":"ssh","priority":1}' http://localhost:5000/event`

## 5. Implementation Roadmap

1. **Phase 1:** Build the `aggregator.py` with basic JSON output.
2. **Phase 2:** Build the OLED-friendly `index.html` frontend.
3. **Phase 3:** Create the first "Detector" (e.g., a simple disk space checker).
4. **Phase 4:** Implement TTL for transient notifications.