diff --git a/README.md b/README.md
index 1e7b993..7e85094 100644
--- a/README.md
+++ b/README.md
@@ -1,403 +1,96 @@
-# RelayTV – Home Assistant Integration
+# RelayTV Home Assistant Integration
 
-RelayTV transforms Home Assistant into a **programmable local media automation engine**.
+RelayTV integrates with Home Assistant as a local `media_player` plus RelayTV-specific services.
 
-It exposes your RelayTV server as a `media_player` (plus services), supports queue-based playback, and makes it easy to drive **local HDMI playback** from automations (doorbells, sensors, schedules, scenes, and AI).
+## Current Feature Set
 
-> Tip: The YAML below uses the `relaytv.*` service names as examples. If your integration exposes slightly different names/fields, keep the **automation patterns** and adjust the service calls accordingly.
+- Creates a `media_player` entity for each RelayTV config entry.
+- Polls RelayTV `GET /status` every 3 seconds.
+- Supports media controls from Home Assistant:
+  - Play, pause, stop
+  - Next and previous
+  - Seek
+  - Volume set
+  - Turn on / turn off
+- Registers a Home Assistant sidebar panel that embeds the RelayTV UI.
+- Supports multi-target synchronized start (`play_synced`) using RelayTV `POST /play_at`.
+- Supports snapshots (`snapshot`) and exposes `snapshot_url` on the entity.
+- Stores resume positions and provides `play_with_resume` behavior.
+- Supports optional sensor->stream mappings that trigger temporary playback when a mapped sensor turns `on`.
 
----
+## RelayTV Services
 
-# 🚀 What RelayTV Enables Today
+| Service | RelayTV endpoint | Notes |
+| --- | --- | --- |
+| `relaytv.smart_url` | `POST /smart` | One-button play/enqueue behavior from RelayTV |
+| `relaytv.play_now` | `POST /play` | Immediate playback; clears queue |
+| `relaytv.announce` | `POST /play` | Alias of `play_now` |
+| `relaytv.play_temporary` | `POST /play_temporary` | Temporary interrupt + resume flow |
+| `relaytv.overlay` | `POST /overlay` | Text/image overlay |
+| `relaytv.play_synced` | `POST /play_at` | Multi-entity time-aligned start |
+| `relaytv.snapshot` | `POST /snapshot` (fallback `GET /snapshot`) | Captures current frame |
+| `relaytv.play_with_resume` | `POST /play` + `POST /seek_abs` | Resume per-URL saved position |
 
-## 🎬 Media Player Control
-- `media_player` entity support
-- Play / pause / stop / seek / volume
-- Queue management
-- Resume playback support (where implemented)
-- Local HDMI playback
-- yt-dlp powered “smart URL” stream resolution
+## Installation (Manual)
 
----
+1. Copy this repository's `custom_components/relaytv` folder into your Home Assistant config:
 
-# ⭐ Key Mobile UX Feature: “Share to Home Assistant” → Play / Enqueue
+   `/config/custom_components/relaytv/`
 
-One of the best day-to-day workflows is using your phone like a “remote link picker”:
+2. Restart Home Assistant.
+3. Go to **Settings -> Devices & Services -> Add Integration**.
+4. Search for **RelayTV**.
+5. Enter:
+   - RelayTV base URL (example: `http://relaytv-host:8787`)
+   - Display name for this RelayTV instance
 
-1. On iOS/Android, **share a link** (YouTube, Twitch, a direct stream URL, etc.)
-2. Choose **Home Assistant** from the share sheet
-3. Home Assistant fires an event (`mobile_app.share`) containing the shared `url` or `text`
-4. An automation can then **play now** or **enqueue** on RelayTV
+## Options
 
-This feels *incredible* in practice: you browse normally on your phone, tap Share, and your TV starts playing.
+From the integration options flow, you can configure:
 
-> Pro tip: Use the HA UI automation editor to duplicate this automation into variants:
-> - “Share → Play Now (Living Room)"
-> - “Share → Enqueue (Bedroom)"
-> - “Share → Ask which TV” (roadmap: actionable notification picker)
+- `panel_enabled`: enable/disable sidebar panel registration
+- `panel_target_entry_id`: which RelayTV config entry is used by the shared sidebar panel
+- `sensor_stream_mappings`: list of sensor-to-URL mappings for temporary playback triggers
 
----
-
-# 🔵 Practical Automation Use Cases (Available Now)
-
-- 🚪 Doorbell / camera pop on the TV
-- ⏰ Morning video alarm clock
-- 🌙 Bedtime routines (relaxing queue + auto stop)
-- 🏠 Home/Away/Movie mode scenes that change what’s on screen
-- 📺 Queue-based “experiences” (workouts, parties, timers, intros)
-- 📲 **Mobile Share → Play/Enqueue** from iOS/Android browsing (see below)
-
----
-
-# 🟢 Creative & Fun Automation Ideas
-
-- 👻 Late-night motion jump scares
-- 🧟 Halloween mode (seasonal triggers + ambient loops)
-- 🐶 Dog cam on bark detection
-- 🎉 Birthday surprise mode
-- 🎮 Easter-egg triggers (sensor patterns launch hidden clips)
-
----
-
-# 🔴 Advanced Home Automation Scenarios
-
-- 🤖 AI-powered announcements (TTS + relevant clip)
-- 🌧 Weather-based media (radar, warnings, checklist videos)
-- 📈 Energy monitoring visualizations (play alert/graph clip)
-- 🛡 “Command center” camera rotation on alarm events
-- 📰 AI daily digest queue (headlines + summaries)
-
----
-
-# 🧠 Core Services (Examples)
-
-| Service | Description |
-|--------|-------------|
-| `relaytv.play_now` | Immediately plays a URL |
-| `relaytv.enqueue` | Adds URL to queue |
-| `relaytv.smart_url` | Resolves URL via yt-dlp (when applicable) |
-| `relaytv.clear_queue` | Clears current queue |
-| `relaytv.seek` | Seek to a time position |
-| `relaytv.volume_set` | Adjust volume |
-
----
-
-# ✅ Automation Examples (YAML)
-
-## 0) Drop-in: Share to Home Assistant → Play Now (Mobile)
-
-**What it does:** When you share a link to the Home Assistant app, this plays it immediately on RelayTV.
-
-- Trigger: `mobile_app.share`
-- Uses: `trigger.event.data.url` (preferred) or `trigger.event.data.text`
+## Example Service Calls
 
 ```yaml
-alias: RelayTV - Mobile Share -> Play Now
-mode: queued
-trigger:
-  - platform: event
-    event_type: mobile_app.share
-action:
-  - variables:
-      shared_url: >-
-        {{ trigger.event.data.url
-           if trigger.event.data.url is defined
-           else (trigger.event.data.text if trigger.event.data.text is defined else '') }}
-  - condition: template
-    value_template: "{{ shared_url | length > 0 }}"
-  - service: relaytv.play_now
-    target:
-      entity_id: media_player.relaytv_living_room
-    data:
-      url: "{{ shared_url }}"
-  - service: notify.notify
-    data:
-      title: "RelayTV"
-      message: "Playing: {{ shared_url }}"
+service: relaytv.play_now
+target:
+  entity_id: media_player.relaytv_living_room
+data:
+  url: https://www.youtube.com/watch?v=dQw4w9WgXcQ
+  use_ytdlp: true
+  cec: false
 ```
 
-### Variant: Mobile Share → Enqueue Instead of Play Now
-
 ```yaml
-alias: RelayTV - Mobile Share -> Enqueue
-mode: queued
-trigger:
-  - platform: event
-    event_type: mobile_app.share
-action:
-  - variables:
-      shared_url: >-
-        {{ trigger.event.data.url
-           if trigger.event.data.url is defined
-           else (trigger.event.data.text if trigger.event.data.text is defined else '') }}
-  - condition: template
-    value_template: "{{ shared_url | length > 0 }}"
-  - service: relaytv.enqueue
-    target:
-      entity_id: media_player.relaytv_living_room
-    data:
-      url: "{{ shared_url }}"
-  - service: notify.notify
-    data:
-      title: "RelayTV"
-      message: "Enqueued: {{ shared_url }}"
+service: relaytv.play_temporary
+target:
+  entity_id: media_player.relaytv_living_room
+data:
+  url: https://example.com/doorbell-chime.mp3
+  timeout: 10
+  volume: 0.6
 ```
 
----
-
-## 1) Doorbell → Show Front Door Camera (RTSP)
-
 ```yaml
-alias: RelayTV - Doorbell Camera Pop
-mode: single
-trigger:
-  - platform: state
-    entity_id: binary_sensor.front_door_ding
-    to: "on"
-action:
-  - service: relaytv.play_now
-    target:
-      entity_id: media_player.relaytv_living_room
-    data:
-      url: "rtsp://user:pass@10.0.55.10:554/stream1"
-  - service: relaytv.volume_set
-    target:
-      entity_id: media_player.relaytv_living_room
-    data:
-      volume_level: 0.55
+service: relaytv.overlay
+target:
+  entity_id: media_player.relaytv_living_room
+data:
+  text: Front door opened
+  duration: 8
+  position: top-right
 ```
 
-## 2) Morning Video Alarm Clock (Playlist + Lights)
+## Known Limitations
 
-```yaml
-alias: RelayTV - Morning Video Alarm
-mode: single
-trigger:
-  - platform: time
-    at: "06:45:00"
-condition:
-  - condition: state
-    entity_id: person.mark
-    state: "home"
-action:
-  - service: light.turn_on
-    target:
-      entity_id: light.bedroom
-    data:
-      brightness_pct: 10
-  - delay: "00:00:05"
-  - service: relaytv.play_now
-    target:
-      entity_id: media_player.relaytv_bedroom
-    data:
-      url: "https://www.youtube.com/playlist?list=YOUR_PLAYLIST_ID"
-  - service: relaytv.volume_set
-    target:
-      entity_id: media_player.relaytv_bedroom
-    data:
-      volume_level: 0.25
-  - delay: "00:05:00"
-  - service: light.turn_on
-    target:
-      entity_id: light.bedroom
-    data:
-      brightness_pct: 45
-```
+- `relaytv.play_now` currently maps to RelayTV `POST /play` (queue-clearing behavior).
+- No dedicated `enqueue` or `clear_queue` Home Assistant service is currently registered by this integration.
+- Overlay calls must include at least `text` or `image_url`.
+- Integration uses local polling; it does not currently use WebSocket push updates.
 
-## 3) Late-Night Motion → Jump Scare (Fun Mode)
+## Compatibility
 
-```yaml
-alias: RelayTV - Late Night Jump Scare
-mode: single
-trigger:
-  - platform: state
-    entity_id: binary_sensor.hall_motion
-    to: "on"
-condition:
-  - condition: time
-    after: "01:00:00"
-    before: "04:00:00"
-action:
-  - service: relaytv.volume_set
-    target:
-      entity_id: media_player.relaytv_living_room
-    data:
-      volume_level: 0.85
-  - service: light.turn_on
-    target:
-      entity_id: light.hallway
-    data:
-      brightness_pct: 100
-  - service: relaytv.play_now
-    target:
-      entity_id: media_player.relaytv_living_room
-    data:
-      url: "https://www.youtube.com/watch?v=YOUR_JUMPSCARE_CLIP"
-  - delay: "00:00:12"
-  - service: light.turn_off
-    target:
-      entity_id: light.hallway
-```
-
-## 4) Alarm Trigger → “Command Center” Camera Rotation (Queue)
-
-```yaml
-alias: RelayTV - Alarm Command Center
-mode: restart
-trigger:
-  - platform: state
-    entity_id: alarm_control_panel.house
-    to: "triggered"
-action:
-  - service: relaytv.clear_queue
-    target:
-      entity_id: media_player.relaytv_living_room
-  - service: relaytv.enqueue
-    target:
-      entity_id: media_player.relaytv_living_room
-    data:
-      url: "rtsp://user:pass@10.0.55.10:554/front"
-  - service: relaytv.enqueue
-    target:
-      entity_id: media_player.relaytv_living_room
-    data:
-      url: "rtsp://user:pass@10.0.55.10:554/driveway"
-  - service: relaytv.enqueue
-    target:
-      entity_id: media_player.relaytv_living_room
-    data:
-      url: "rtsp://user:pass@10.0.55.10:554/backyard"
-  - service: relaytv.play_now
-    target:
-      entity_id: media_player.relaytv_living_room
-    data:
-      url: "rtsp://user:pass@10.0.55.10:554/front"
-```
-
-## 5) Party Mode Script (Intro Clip + Playlist)
-
-Create this as a **Script** in HA (Settings → Automations & Scenes → Scripts).
-
-```yaml
-party_mode_relaytv:
-  alias: Party Mode (RelayTV)
-  mode: single
-  sequence:
-    - service: relaytv.clear_queue
-      target:
-        entity_id: media_player.relaytv_living_room
-    - service: relaytv.enqueue
-      target:
-        entity_id: media_player.relaytv_living_room
-      data:
-        url: "https://www.youtube.com/watch?v=YOUR_INTRO_CLIP"
-    - service: relaytv.enqueue
-      target:
-        entity_id: media_player.relaytv_living_room
-      data:
-        url: "https://www.youtube.com/playlist?list=YOUR_PARTY_PLAYLIST"
-    - service: relaytv.volume_set
-      target:
-        entity_id: media_player.relaytv_living_room
-      data:
-        volume_level: 0.65
-    - service: relaytv.play_now
-      target:
-        entity_id: media_player.relaytv_living_room
-      data:
-        url: "https://www.youtube.com/watch?v=YOUR_INTRO_CLIP"
-```
-
-## 6) “AI Announcement” Pattern (TTS + Video)
-
-```yaml
-alias: RelayTV - AI Announcement Pattern
-mode: single
-trigger:
-  - platform: state
-    entity_id: binary_sensor.garage_door_open_too_long
-    to: "on"
-action:
-  - service: tts.speak
-    data:
-      media_player_entity_id: media_player.kitchen_speaker
-      message: "Garage door has been open for a while."
-  - service: relaytv.play_now
-    target:
-      entity_id: media_player.relaytv_living_room
-    data:
-      url: "https://www.youtube.com/watch?v=YOUR_ALERT_CLIP"
-```
-
-## 7) Energy Spike → Alert Clip + Reduce Loads
-
-```yaml
-alias: RelayTV - Energy Spike Alert
-mode: single
-trigger:
-  - platform: numeric_state
-    entity_id: sensor.home_power_kw
-    above: 8.0
-    for: "00:02:00"
-action:
-  - service: relaytv.play_now
-    target:
-      entity_id: media_player.relaytv_living_room
-    data:
-      url: "https://www.youtube.com/watch?v=YOUR_POWER_ALERT_CLIP"
-  - service: switch.turn_off
-    target:
-      entity_id:
-        - switch.space_heater
-        - switch.shop_fan
-```
-
----
-
-# 🛣 Roadmap (Future Capabilities)
-
-## 🔔 Interrupt + Resume Service
-Temporarily interrupt playback for alerts, then auto-resume prior content.
-
-## 🪟 Overlay Mode
-Display notification banners without stopping playback.
-
-## 🔄 Multi-Screen Sync
-Synchronize playback across multiple RelayTV servers (perfect for whole-home announcements).
-
-## 🖼 Snapshot Previews
-Capture/preview before switching content (helps with camera pops).
-
-## 🎛 Sensor → Stream Mapping UI
-Map motion/doorbell sensors to streams directly in the integration options UI (no YAML required).
-
-## 🧠 AI Clip Generator
-Generate short clips (image + TTS + theme) for alerts, seasons, and events.
-
-## 📢 Smart Alert Replacement
-Insert custom “house announcements” during downtime or between queued items.
-
----
-
-# 📦 Installation
-
-## HACS
-1. Add as Custom Repository (Integration)
-2. Install
-3. Restart Home Assistant
-4. Add Integration
-5. Configure server address
-
-## Manual
-Copy `custom_components/relaytv` into:
-
-```text
-/ config / custom_components / relaytv
-```
-
-Restart Home Assistant.
-
----
-
-# 🔐 License
-TBD
+Validated against RelayTV app routes in `/opt/relaytv/app/relaytv_app/routes.py` and API docs in `/opt/relaytv/docs/API.md`.
diff --git a/custom_components/relaytv/README.md b/custom_components/relaytv/README.md
index ae6b15b..5f327b4 100644
--- a/custom_components/relaytv/README.md
+++ b/custom_components/relaytv/README.md
@@ -1,143 +1,42 @@
-# RelayTV -- Home Assistant Integration
+# RelayTV Home Assistant Integration
 
-The RelayTV Home Assistant integration adds a sidebar panel that embeds
-the RelayTV web UI directly inside Home Assistant.
+This integration provides a RelayTV `media_player` entity, RelayTV service actions, and an optional Home Assistant sidebar panel embedding RelayTV UI.
 
-This integration does **not** create media entities or mirror playback
-state into HA.\
-RelayTV remains the authoritative playback engine and UI.
+## Implemented Behavior
 
-------------------------------------------------------------------------
+- `media_player` platform is enabled (`custom_components/relaytv/media_player.py`).
+- Polling coordinator refreshes RelayTV `GET /status` every 3 seconds.
+- Sidebar panel is registered via Home Assistant frontend iframe panel APIs.
+- RelayTV services are registered from `services.yaml`:
+  - `smart_url`
+  - `play_now`
+  - `announce`
+  - `play_temporary`
+  - `overlay`
+  - `play_synced`
+  - `snapshot`
+  - `play_with_resume`
 
-## What This Integration Does
+## Setup
 
--   Adds a dedicated **RelayTV** sidebar panel
--   Embeds the RelayTV `/ui` interface via iframe
--   Allows control from desktop or mobile HA apps
--   Keeps RelayTV fully self-contained
+1. Place this folder at:
 
-------------------------------------------------------------------------
+   `/config/custom_components/relaytv/`
 
-## Requirements
+2. Restart Home Assistant.
+3. Add integration: **Settings -> Devices & Services -> Add Integration -> RelayTV**.
+4. Provide RelayTV base URL (example: `http://relaytv-host:8787`) and a server/display name.
 
--   A running RelayTV instance accessible from Home Assistant
--   RelayTV reachable via HTTP (e.g. `http://relaytv-host:8787`)
--   Home Assistant 2023.x or newer recommended
+## Options
 
-------------------------------------------------------------------------
+- `panel_enabled`
+- `panel_target_entry_id`
+- `sensor_stream_mappings`
 
-## Installation (Manual)
+## Notes
 
-1.  Copy the `relaytv_webui` folder into:
+- `play_now` and `announce` currently target RelayTV `POST /play`.
+- Overlay requires `text` or `image_url`.
+- Snapshot responses are normalized to absolute URLs for Home Assistant entity attributes.
 
-```{=html}
-<!-- -->
-```
-    /config/custom_components/
-
-So it becomes:
-
-    /config/custom_components/relaytv_webui/
-
-2.  Restart Home Assistant.
-
-3.  Go to:
-
-```{=html}
-<!-- -->
-```
-    Settings → Devices & Services → Add Integration
-
-4.  Search for **RelayTV Web UI Panel**.
-
-5.  Enter the base URL where RelayTV is reachable from Home Assistant.
-
-Example:
-
-    http://relaytv-host:8787
-
-------------------------------------------------------------------------
-
-## Configuration Options
-
-After installation, you can configure:
-
-  Option          Description
-  --------------- ----------------------------
-  Sidebar title   Display name in HA sidebar
-  Sidebar icon    Any valid MDI icon
-  Sidebar path    URL slug used in HA
-
-------------------------------------------------------------------------
-
-## Example Configuration
-
-Base URL:
-
-    http://192.168.1.50:8787
-
-Custom sidebar path:
-
-    relaytv
-
-Resulting HA path:
-
-    http://homeassistant.local:8123/relaytv
-
-------------------------------------------------------------------------
-
-## How It Works
-
-The integration registers a built-in Home Assistant **iframe panel**.
-
-No polling, no entities, no media_player integration.
-
-RelayTV's own API and state model remain independent and
-server-authoritative.
-
-------------------------------------------------------------------------
-
-## Security Notes
-
--   RelayTV should only be exposed on trusted networks.
--   If accessing via HTTPS reverse proxy, use the proxied URL as the
-    base URL.
--   Ensure CORS and authentication policies match your deployment
-    environment.
-
-------------------------------------------------------------------------
-
-## Recommended Deployment Pattern
-
-For maximum reliability:
-
--   Run RelayTV in Docker
--   Bind-mount `/data` for persistent queue/history
--   Use stable and beta containers during upgrades
--   Point HA at the stable instance
-
-------------------------------------------------------------------------
-
-## Roadmap
-
-Planned future enhancements:
-
--   Optional HA media_player entity bridge
--   Service calls for play/enqueue
--   WebSocket event push support
--   HACS compatibility
-
-------------------------------------------------------------------------
-
-## Support
-
-If the panel fails to load:
-
-1.  Verify RelayTV is reachable from the HA container
-2.  Confirm the base URL is correct
-3.  Check HA logs for integration load errors
-4.  Confirm no mixed HTTP/HTTPS blocking issues
-
-------------------------------------------------------------------------
-
-**RelayTV --- A local-first media runtime for your television.**
+For fuller documentation and examples, see the repository root README.