stv 0.2.0__tar.gz

stv-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+*.db

stv-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yunsu Kim
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stv-0.2.0/PKG-INFO

@@ -0,0 +1,220 @@
+Metadata-Version: 2.4
+Name: stv
+Version: 0.2.0
+Summary: Talk to your TV. Control any smart TV with natural language.
+Project-URL: Homepage, https://github.com/Hybirdss/smartest-tv
+Project-URL: Repository, https://github.com/Hybirdss/smartest-tv
+Author: Yunsu Kim
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai-agent,android-tv,cli,deep-link,fire-tv,lg,mcp,netflix,roku,samsung,smart-tv,spotify,tv,youtube
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: End Users/Desktop
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.11
+Requires-Dist: click>=8.0.0
+Requires-Dist: tomli>=2.0.0; python_version < '3.11'
+Provides-Extra: all
+Requires-Dist: adb-shell>=0.4.0; extra == 'all'
+Requires-Dist: aiohttp>=3.9.0; extra == 'all'
+Requires-Dist: bscpylgtv>=0.5.0; extra == 'all'
+Requires-Dist: fastmcp>=2.0.0; extra == 'all'
+Requires-Dist: samsungtvws[encrypted]>=3.0.0; extra == 'all'
+Provides-Extra: android
+Requires-Dist: adb-shell>=0.4.0; extra == 'android'
+Provides-Extra: lg
+Requires-Dist: bscpylgtv>=0.5.0; extra == 'lg'
+Provides-Extra: mcp
+Requires-Dist: fastmcp>=2.0.0; extra == 'mcp'
+Provides-Extra: roku
+Requires-Dist: aiohttp>=3.9.0; extra == 'roku'
+Provides-Extra: samsung
+Requires-Dist: samsungtvws[encrypted]>=3.0.0; extra == 'samsung'
+Description-Content-Type: text/markdown
+
+# stv
+
+[English](README.md) | [한국어](docs/i18n/README.ko.md) | [中文](docs/i18n/README.zh.md) | [日本語](docs/i18n/README.ja.md) | [Español](docs/i18n/README.es.md) | [Deutsch](docs/i18n/README.de.md) | [Português](docs/i18n/README.pt-br.md) | [Français](docs/i18n/README.fr.md)
+
+**Talk to your TV. It listens.**
+
+A CLI and agent skills for controlling smart TVs with natural language. Deep links into Netflix, YouTube, Spotify — say what you want to watch and it plays. No developer mode. No API keys. No cursed env vars. Just `stv setup` and go.
+
+> "Play Frieren season 2 episode 8"
+>
+> *Netflix opens. Episode starts playing.*
+
+Works with **LG** (tested), **Samsung**, **Android TV / Fire TV**, and **Roku** (community testing).
+
+## Install
+
+```bash
+pip install stv
+```
+
+That's it. No extras needed for LG — the default install covers it.
+
+```bash
+pip install "stv[samsung]"  # Samsung Tizen
+pip install "stv[android]"  # Android TV / Fire TV
+pip install "stv[all]"      # Everything
+```
+
+## Zero-config Setup
+
+Run this once and you're done:
+
+```bash
+stv setup
+```
+
+It auto-discovers your TV on the network, detects the platform (LG? Samsung? Roku?), pairs automatically — no developer mode required, no IP hunting — and writes everything to `~/.config/smartest-tv/config.toml`. After that, every `stv` command just works.
+
+If something looks wrong, `stv doctor` will tell you exactly what's up.
+
+## CLI
+
+```bash
+stv status                          # What's on, volume, mute state
+stv launch netflix 82656797         # Deep link to specific content
+stv launch youtube dQw4w9WgXcQ     # Play a YouTube video
+stv launch spotify spotify:album:x  # Play on Spotify
+stv volume 25                       # Set volume
+stv mute                            # Toggle mute
+stv apps --format json              # List apps (structured output)
+stv notify "Dinner's ready"         # Toast notification on screen
+stv off                             # Goodnight
+```
+
+Every command supports `--format json` — designed for scripts and AI agents.
+
+## Agent Skills
+
+stv ships five skills that teach AI assistants how to control your TV intelligently. Install them into Claude Code:
+
+```bash
+# Auto-install all skills
+cd smartest-tv && ./install-skills.sh
+```
+
+Then just talk to Claude:
+
+```
+You: Play Frieren season 2 episode 8 on Netflix
+You: Put on Baby Shark for the kids
+You: Ye's new album on Spotify
+You: Screen off, play my jazz playlist
+You: Good night
+```
+
+The skills handle the hard part — finding Netflix episode IDs, searching YouTube via yt-dlp, resolving Spotify URIs — and call `stv` to control your TV.
+
+### Skills
+
+| Skill | What it does |
+|-------|-------------|
+| `tv-shared` | CLI reference, auth, config, common patterns |
+| `tv-netflix` | Episode ID lookup via Playwright scraping |
+| `tv-youtube` | Video search via yt-dlp, format resolution |
+| `tv-spotify` | Album/track/playlist URI resolution |
+| `tv-workflow` | Composite actions: movie night, kids mode, sleep timer |
+
+## Deep Linking
+
+This is what makes stv different from everything else. Other tools open Netflix. stv plays *Frieren episode 36*.
+
+The same content ID works across every TV platform:
+
+```bash
+stv launch netflix 82656797                           # LG, Samsung, Roku, Android TV
+stv launch youtube dQw4w9WgXcQ                        # Same
+stv launch spotify spotify:album:5poA9SAx0Xiz1cd17f   # Same
+```
+
+Each driver translates the ID into the platform's native deep link format under the hood:
+
+| TV | How it sends the deep link |
+|----|---------------------------|
+| LG webOS | SSAP WebSocket: contentId (Netflix DIAL) / params.contentTarget (YouTube) |
+| Samsung | WebSocket: `run_app(id, "DEEP_LINK", meta_tag)` |
+| Android / Fire TV | ADB: `am start -d 'netflix://title/{id}'` |
+| Roku | HTTP: `POST /launch/{ch}?contentId={id}` |
+
+You never think about any of this. The driver handles it.
+
+## Platforms
+
+| Platform | Driver | Connection | Status |
+|----------|--------|-----------|--------|
+| LG webOS | [bscpylgtv](https://github.com/chros73/bscpylgtv) | WebSocket :3001 | **Tested** |
+| Samsung Tizen | [samsungtvws](https://github.com/xchwarze/samsung-tv-ws-api) | WebSocket :8002 | Community testing |
+| Android / Fire TV | [adb-shell](https://github.com/JeffLIrion/adb-shell) | ADB TCP :5555 | Community testing |
+| Roku | HTTP ECP | REST :8060 | Community testing |
+
+LG is the primary tested platform. Samsung, Android TV, and Roku should work — no developer mode required on any of them — but real-world reports are welcome.
+
+## Configuration
+
+Config lives at `~/.config/smartest-tv/config.toml`. After `stv setup`, it looks something like:
+
+```toml
+[tv]
+platform = "lg"
+ip = "192.168.1.100"
+mac = "AA:BB:CC:DD:EE:FF"   # optional, for Wake-on-LAN
+```
+
+On first connection, the TV shows a pairing prompt. Accept once — the key is saved and never asked again.
+
+## Real World
+
+**It's 2am.** You're in bed. You tell Claude: "Play where I left off on Frieren." The living room TV turns on, Netflix opens, the episode starts. You never touched the remote. You barely opened your eyes.
+
+**Saturday morning.** "Put on Cocomelon for the baby." YouTube finds it, TV plays it. You keep making breakfast. Coffee's getting cold anyway.
+
+**Friends are over.** "Game mode, HDMI 2, volume down." One sentence, three changes, done before anyone noticed you did it.
+
+**Cooking dinner.** "Screen off, play my jazz playlist." Screen goes dark, music flows through the speakers. You didn't need to pause, navigate, or squint at a menu.
+
+**Falling asleep.** "Sleep timer 45 minutes." The TV turns itself off. You don't.
+
+## MCP Server
+
+For Claude Desktop, Cursor, or other MCP clients — this is optional, the CLI is the primary interface:
+
+```json
+{
+  "mcpServers": {
+    "tv": {
+      "command": "uvx",
+      "args": ["stv"]
+    }
+  }
+}
+```
+
+18 tools available: `tv_on`, `tv_off`, `tv_launch`, `tv_close`, `tv_volume`, `tv_set_volume`, `tv_mute`, `tv_play`, `tv_pause`, `tv_stop`, `tv_status`, `tv_info`, `tv_notify`, `tv_apps`, `tv_volume_up`, `tv_volume_down`, `tv_screen_on`, `tv_screen_off`.
+
+Config is read from `~/.config/smartest-tv/config.toml` automatically — no env vars needed.
+
+## Architecture
+
+```
+You (natural language)
+  → AI + Skills (finds content ID via yt-dlp / Playwright / web search)
+    → stv CLI (formats and dispatches)
+      → Driver (WebSocket / ADB / HTTP)
+        → TV
+```
+
+## Contributing
+
+**Drivers** for Samsung, Android TV, and Roku are the highest-leverage contribution. The [driver interface](src/smartest_tv/drivers/base.py) is defined — implement `TVDriver` for your platform and open a PR.
+
+**Skills** for new streaming services (Disney+, Hulu, Prime Video) are welcome too.
+
+## License
+
+MIT

stv-0.2.0/README.md

@@ -0,0 +1,184 @@
+# stv
+
+[English](README.md) | [한국어](docs/i18n/README.ko.md) | [中文](docs/i18n/README.zh.md) | [日本語](docs/i18n/README.ja.md) | [Español](docs/i18n/README.es.md) | [Deutsch](docs/i18n/README.de.md) | [Português](docs/i18n/README.pt-br.md) | [Français](docs/i18n/README.fr.md)
+
+**Talk to your TV. It listens.**
+
+A CLI and agent skills for controlling smart TVs with natural language. Deep links into Netflix, YouTube, Spotify — say what you want to watch and it plays. No developer mode. No API keys. No cursed env vars. Just `stv setup` and go.
+
+> "Play Frieren season 2 episode 8"
+>
+> *Netflix opens. Episode starts playing.*
+
+Works with **LG** (tested), **Samsung**, **Android TV / Fire TV**, and **Roku** (community testing).
+
+## Install
+
+```bash
+pip install stv
+```
+
+That's it. No extras needed for LG — the default install covers it.
+
+```bash
+pip install "stv[samsung]"  # Samsung Tizen
+pip install "stv[android]"  # Android TV / Fire TV
+pip install "stv[all]"      # Everything
+```
+
+## Zero-config Setup
+
+Run this once and you're done:
+
+```bash
+stv setup
+```
+
+It auto-discovers your TV on the network, detects the platform (LG? Samsung? Roku?), pairs automatically — no developer mode required, no IP hunting — and writes everything to `~/.config/smartest-tv/config.toml`. After that, every `stv` command just works.
+
+If something looks wrong, `stv doctor` will tell you exactly what's up.
+
+## CLI
+
+```bash
+stv status                          # What's on, volume, mute state
+stv launch netflix 82656797         # Deep link to specific content
+stv launch youtube dQw4w9WgXcQ     # Play a YouTube video
+stv launch spotify spotify:album:x  # Play on Spotify
+stv volume 25                       # Set volume
+stv mute                            # Toggle mute
+stv apps --format json              # List apps (structured output)
+stv notify "Dinner's ready"         # Toast notification on screen
+stv off                             # Goodnight
+```
+
+Every command supports `--format json` — designed for scripts and AI agents.
+
+## Agent Skills
+
+stv ships five skills that teach AI assistants how to control your TV intelligently. Install them into Claude Code:
+
+```bash
+# Auto-install all skills
+cd smartest-tv && ./install-skills.sh
+```
+
+Then just talk to Claude:
+
+```
+You: Play Frieren season 2 episode 8 on Netflix
+You: Put on Baby Shark for the kids
+You: Ye's new album on Spotify
+You: Screen off, play my jazz playlist
+You: Good night
+```
+
+The skills handle the hard part — finding Netflix episode IDs, searching YouTube via yt-dlp, resolving Spotify URIs — and call `stv` to control your TV.
+
+### Skills
+
+| Skill | What it does |
+|-------|-------------|
+| `tv-shared` | CLI reference, auth, config, common patterns |
+| `tv-netflix` | Episode ID lookup via Playwright scraping |
+| `tv-youtube` | Video search via yt-dlp, format resolution |
+| `tv-spotify` | Album/track/playlist URI resolution |
+| `tv-workflow` | Composite actions: movie night, kids mode, sleep timer |
+
+## Deep Linking
+
+This is what makes stv different from everything else. Other tools open Netflix. stv plays *Frieren episode 36*.
+
+The same content ID works across every TV platform:
+
+```bash
+stv launch netflix 82656797                           # LG, Samsung, Roku, Android TV
+stv launch youtube dQw4w9WgXcQ                        # Same
+stv launch spotify spotify:album:5poA9SAx0Xiz1cd17f   # Same
+```
+
+Each driver translates the ID into the platform's native deep link format under the hood:
+
+| TV | How it sends the deep link |
+|----|---------------------------|
+| LG webOS | SSAP WebSocket: contentId (Netflix DIAL) / params.contentTarget (YouTube) |
+| Samsung | WebSocket: `run_app(id, "DEEP_LINK", meta_tag)` |
+| Android / Fire TV | ADB: `am start -d 'netflix://title/{id}'` |
+| Roku | HTTP: `POST /launch/{ch}?contentId={id}` |
+
+You never think about any of this. The driver handles it.
+
+## Platforms
+
+| Platform | Driver | Connection | Status |
+|----------|--------|-----------|--------|
+| LG webOS | [bscpylgtv](https://github.com/chros73/bscpylgtv) | WebSocket :3001 | **Tested** |
+| Samsung Tizen | [samsungtvws](https://github.com/xchwarze/samsung-tv-ws-api) | WebSocket :8002 | Community testing |
+| Android / Fire TV | [adb-shell](https://github.com/JeffLIrion/adb-shell) | ADB TCP :5555 | Community testing |
+| Roku | HTTP ECP | REST :8060 | Community testing |
+
+LG is the primary tested platform. Samsung, Android TV, and Roku should work — no developer mode required on any of them — but real-world reports are welcome.
+
+## Configuration
+
+Config lives at `~/.config/smartest-tv/config.toml`. After `stv setup`, it looks something like:
+
+```toml
+[tv]
+platform = "lg"
+ip = "192.168.1.100"
+mac = "AA:BB:CC:DD:EE:FF"   # optional, for Wake-on-LAN
+```
+
+On first connection, the TV shows a pairing prompt. Accept once — the key is saved and never asked again.
+
+## Real World
+
+**It's 2am.** You're in bed. You tell Claude: "Play where I left off on Frieren." The living room TV turns on, Netflix opens, the episode starts. You never touched the remote. You barely opened your eyes.
+
+**Saturday morning.** "Put on Cocomelon for the baby." YouTube finds it, TV plays it. You keep making breakfast. Coffee's getting cold anyway.
+
+**Friends are over.** "Game mode, HDMI 2, volume down." One sentence, three changes, done before anyone noticed you did it.
+
+**Cooking dinner.** "Screen off, play my jazz playlist." Screen goes dark, music flows through the speakers. You didn't need to pause, navigate, or squint at a menu.
+
+**Falling asleep.** "Sleep timer 45 minutes." The TV turns itself off. You don't.
+
+## MCP Server
+
+For Claude Desktop, Cursor, or other MCP clients — this is optional, the CLI is the primary interface:
+
+```json
+{
+  "mcpServers": {
+    "tv": {
+      "command": "uvx",
+      "args": ["stv"]
+    }
+  }
+}
+```
+
+18 tools available: `tv_on`, `tv_off`, `tv_launch`, `tv_close`, `tv_volume`, `tv_set_volume`, `tv_mute`, `tv_play`, `tv_pause`, `tv_stop`, `tv_status`, `tv_info`, `tv_notify`, `tv_apps`, `tv_volume_up`, `tv_volume_down`, `tv_screen_on`, `tv_screen_off`.
+
+Config is read from `~/.config/smartest-tv/config.toml` automatically — no env vars needed.
+
+## Architecture
+
+```
+You (natural language)
+  → AI + Skills (finds content ID via yt-dlp / Playwright / web search)
+    → stv CLI (formats and dispatches)
+      → Driver (WebSocket / ADB / HTTP)
+        → TV
+```
+
+## Contributing
+
+**Drivers** for Samsung, Android TV, and Roku are the highest-leverage contribution. The [driver interface](src/smartest_tv/drivers/base.py) is defined — implement `TVDriver` for your platform and open a PR.
+
+**Skills** for new streaming services (Disney+, Hulu, Prime Video) are welcome too.
+
+## License
+
+MIT

stv-0.2.0/docs/i18n/README.de.md

@@ -0,0 +1,84 @@
+# smartest-tv
+
+[English](../../README.md) | [한국어](README.ko.md) | [中文](README.zh.md) | [日本語](README.ja.md) | [Español](README.es.md) | **Deutsch** | [Português](README.pt-br.md) | [Français](README.fr.md)
+
+Sprich mit deinem Fernseher. Er hört zu.
+
+CLI und KI-Agenten-Skill zur Steuerung deines Smart TVs per natürlicher Sprache. Deep Links für Netflix, YouTube und Spotify — sag, was du sehen willst, und es läuft.
+
+> „Spiel Folge 8 der zweiten Staffel Frieren ab"
+>
+> *Netflix öffnet sich und die Episode beginnt.*
+
+Unterstützt **LG**, **Samsung**, **Android TV**, **Fire TV** und **Roku**.
+
+## Installation
+
+```bash
+pip install "smartest-tv[lg]"      # LG webOS
+pip install "smartest-tv[samsung]" # Samsung Tizen
+pip install "smartest-tv[android]" # Android TV / Fire TV
+pip install "smartest-tv[all]"     # Alles
+```
+
+## CLI
+
+```bash
+export TV_IP=192.168.1.100
+
+tv status                          # Aktueller Status (App, Lautstärke, Stummschaltung)
+tv launch netflix 82656797         # Bestimmten Inhalt auf Netflix abspielen
+tv launch youtube dQw4w9WgXcQ     # YouTube-Video abspielen
+tv launch spotify spotify:album:x # Spotify abspielen
+tv volume 25                       # Lautstärke einstellen
+tv mute                            # Stummschaltung umschalten
+tv apps --format json              # Liste installierter Apps
+tv notify "Essen ist fertig!"      # Benachrichtigung auf dem TV anzeigen
+tv off                             # TV ausschalten
+```
+
+Alle Befehle unterstützen `--format json` — strukturierte Ausgabe für KI-Agenten.
+
+## KI-Agenten-Skill
+
+Skill in Claude Code installieren:
+
+```bash
+cd smartest-tv && ./install-skills.sh
+```
+
+Dann einfach in natürlicher Sprache mit Claude reden:
+
+```
+Du: Spiel Frieren Staffel 2, Folge 8 auf Netflix
+Du: Mach YouTube für die Kinder an
+Du: Spiel das neue Album von Ye auf Spotify
+Du: Bildschirm aus und Jazz an
+Du: Gute Nacht
+```
+
+Der Skill übernimmt die komplizierte Arbeit — Netflix-Episoden-IDs suchen, YouTube via yt-dlp durchsuchen, Spotify-URIs auflösen — und ruft dann die `tv` CLI auf, um den Fernseher zu steuern.
+
+## Deep Links
+
+Das ist das entscheidende Alleinstellungsmerkmal von smartest-tv. Andere Tools öffnen Netflix nur. Wir *spielen Folge 36 von Frieren ab*.
+
+Dieselbe Inhalts-ID funktioniert auf allen TV-Plattformen:
+
+```bash
+tv launch netflix 82656797       # Egal ob LG, Samsung oder Roku
+tv launch youtube dQw4w9WgXcQ    # Genauso
+tv launch spotify spotify:album:x  # Genauso
+```
+
+## Praxisbeispiele
+
+**Nachts um 2 Uhr.** Im Bett sagst du Claude: „Weiter mit Frieren." Der Fernseher im Wohnzimmer geht an, Netflix öffnet sich, die Episode beginnt. Keine Fernbedienung nötig.
+
+**Samstagmorgen.** „Mach Cocomelon für die Kleinen an." Es findet es auf YouTube und spielt es auf dem Fernseher ab. Mach einfach weiter mit dem Frühstück.
+
+**Wenn Freunde zu Besuch kommen.** „Gaming-Modus, HDMI 2, Lautstärke runter." Drei Änderungen mit einem Satz.
+
+## Lizenz
+
+MIT

stv-0.2.0/docs/i18n/README.es.md

@@ -0,0 +1,172 @@
+# stv
+
+[English](../../README.md) | [한국어](README.ko.md) | [中文](README.zh.md) | [日本語](README.ja.md) | **Español** | [Deutsch](README.de.md) | [Português](README.pt-br.md) | [Français](README.fr.md)
+
+**Habla con tu tele. Te escucha.**
+
+CLI y skills para agentes de IA que controlan tu smart TV en lenguaje natural. Deep links para Netflix, YouTube y Spotify — di lo que quieres ver y empieza a reproducirse. Sin modo desarrollador. Sin API keys. Un `stv setup` y listo.
+
+> "Pon el episodio 8 de la temporada 2 de Frieren"
+>
+> *Netflix se abre y el episodio empieza solo.*
+
+Compatible con **LG** (probado), **Samsung**, **Android TV / Fire TV** y **Roku** (pruebas de la comunidad).
+
+## Instalación
+
+```bash
+pip install stv
+```
+
+Eso es todo. Para LG no necesitas nada más.
+
+```bash
+pip install "stv[samsung]"  # Samsung Tizen
+pip install "stv[android]"  # Android TV / Fire TV
+pip install "stv[all]"      # Todo
+```
+
+## Configuración cero
+
+Ejecuta esto una sola vez:
+
+```bash
+stv setup
+```
+
+Detecta la tele en la red automáticamente, identifica la plataforma (¿LG? ¿Samsung? ¿Roku?), hace el emparejamiento solo — sin modo desarrollador, sin buscar la IP a mano — y guarda todo en `~/.config/smartest-tv/config.toml`. A partir de ahí, cada comando `stv` funciona sin más.
+
+¿Algo no va bien? `stv doctor` te dice exactamente qué está pasando.
+
+## CLI
+
+```bash
+stv status                          # Qué está sonando, volumen, silencio
+stv launch netflix 82656797         # Deep link a contenido específico
+stv launch youtube dQw4w9WgXcQ     # Reproduce un vídeo de YouTube
+stv launch spotify spotify:album:x  # Reproduce en Spotify
+stv volume 25                       # Ajustar volumen
+stv mute                            # Activar/desactivar silencio
+stv apps --format json              # Lista de apps instaladas
+stv notify "¡A comer!"              # Notificación en pantalla
+stv off                             # Apagar la tele
+```
+
+Todos los comandos admiten `--format json` — salida estructurada para scripts y agentes de IA.
+
+## Skills para agentes de IA
+
+stv incluye cinco skills que enseñan a los asistentes de IA a controlar tu tele de forma inteligente. Instálalos en Claude Code de una vez:
+
+```bash
+cd smartest-tv && ./install-skills.sh
+```
+
+Y ya puedes hablar con Claude con total naturalidad:
+
+```
+Tú: Pon el episodio 8 de la temporada 2 de Frieren en Netflix
+Tú: Pon Cocomelon para el niño
+Tú: Pon el nuevo álbum de Ye en Spotify
+Tú: Apaga la pantalla y pon jazz
+Tú: Buenas noches
+```
+
+Los skills se encargan de lo complicado — buscar el ID del episodio en Netflix, buscar en YouTube con yt-dlp, interpretar URIs de Spotify — y llaman al CLI `stv` para controlar la televisión.
+
+### Lista de skills
+
+| Skill | Qué hace |
+|-------|----------|
+| `tv-shared` | Referencia CLI, autenticación, configuración, patrones comunes |
+| `tv-netflix` | Búsqueda de IDs de episodios con Playwright |
+| `tv-youtube` | Búsqueda de vídeos con yt-dlp |
+| `tv-spotify` | Resolución de URIs de álbumes, canciones y playlists |
+| `tv-workflow` | Acciones combinadas: modo cine, modo niños, temporizador |
+
+## Por qué los deep links cambian todo
+
+Otras herramientas solo *abren* Netflix. stv *reproduce el episodio 36 de Frieren*. Esa es la diferencia real.
+
+El mismo ID de contenido funciona en todas las plataformas de TV:
+
+```bash
+stv launch netflix 82656797                          # Igual en LG, Samsung o Roku
+stv launch youtube dQw4w9WgXcQ                       # Igual
+stv launch spotify spotify:album:5poA9SAx0Xiz1cd17f  # Igual
+```
+
+Cada plataforma tiene su propio formato de deep link, pero el driver lo traduce por ti. Tú no tienes que pensar en eso.
+
+## Plataformas
+
+| Plataforma | Driver | Conexión | Estado |
+|------------|--------|---------|--------|
+| LG webOS | [bscpylgtv](https://github.com/chros73/bscpylgtv) | WebSocket :3001 | **Probado** |
+| Samsung Tizen | [samsungtvws](https://github.com/xchwarze/samsung-tv-ws-api) | WebSocket :8002 | Pruebas de la comunidad |
+| Android / Fire TV | [adb-shell](https://github.com/JeffLIrion/adb-shell) | ADB TCP :5555 | Pruebas de la comunidad |
+| Roku | HTTP ECP | REST :8060 | Pruebas de la comunidad |
+
+LG es la plataforma principal probada. Samsung, Android TV y Roku deberían funcionar — ninguna requiere modo desarrollador — y se agradecen las experiencias reales de la comunidad.
+
+## Configuración
+
+La configuración se guarda en `~/.config/smartest-tv/config.toml`. Después de `stv setup`, tiene esta pinta:
+
+```toml
+[tv]
+platform = "lg"
+ip = "192.168.1.100"
+mac = "AA:BB:CC:DD:EE:FF"   # opcional, para Wake-on-LAN
+```
+
+En la primera conexión la tele muestra un aviso de emparejamiento. Lo aceptas una vez y la clave se guarda para siempre.
+
+## Casos de uso reales
+
+**Las 2 de la mañana.** En la cama, le dices a Claude: "Sigue con Frieren donde lo dejé." El televisor del salón se enciende, Netflix se abre y el episodio empieza. Sin buscar el mando. Con los ojos medio cerrados.
+
+**Sábado por la mañana.** "Pon Cocomelon para el bebé." Lo encuentra en YouTube y lo pone en la tele. Tú sigues con el desayuno.
+
+**Cuando vienen amigos.** "Modo juego, HDMI 2, baja el volumen." Tres cambios en una frase, antes de que nadie note nada.
+
+**Cocinando.** "Apaga la pantalla y pon jazz." La pantalla se apaga, la música suena. Sin navegar por menús ni buscar la app.
+
+**Antes de dormir.** "Apaga en 45 minutos." La tele se apaga sola. Tú, no.
+
+## Servidor MCP
+
+Para Claude Desktop, Cursor u otros clientes MCP — esto es opcional, el CLI es la interfaz principal:
+
+```json
+{
+  "mcpServers": {
+    "tv": {
+      "command": "uvx",
+      "args": ["stv"]
+    }
+  }
+}
+```
+
+18 herramientas disponibles. La configuración se lee automáticamente de `~/.config/smartest-tv/config.toml`. Sin variables de entorno.
+
+## Arquitectura
+
+```
+Tú (lenguaje natural)
+  → IA + Skills (busca el ID del contenido con yt-dlp / Playwright / búsqueda web)
+    → stv CLI (formatea y envía)
+      → Driver (WebSocket / ADB / HTTP)
+        → TV
+```
+
+## Contribuir
+
+Los **drivers** de Samsung, Android TV y Roku son la contribución de mayor impacto. La [interfaz del driver](src/smartest_tv/drivers/base.py) ya está definida — implementa `TVDriver` para tu plataforma y abre una PR.
+
+Los **skills** para nuevos servicios de streaming (Disney+, Hulu, Prime Video) también son bienvenidos.
+
+## Licencia
+
+MIT