aioli-cli 0.1.46__tar.gz → 0.2.0__tar.gz

aioli_cli-0.2.0/.gitignore

@@ -0,0 +1,22 @@
+__pycache__/
+*.pyc
+.venv/
+
+# caches de herramientas (I6): un `git add -A` no debe commitearlas
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+
+# cobertura (I4): artefactos del run, se regeneran
+.coverage
+coverage.xml
+
+# web
+web/node_modules/
+web/dist/
+web/.astro/
+# copia de ../install.sh que hace `pnpm build`/`pnpm dev`
+web/public/install.sh
+
+dist/
+.kaudit/

aioli_cli-0.2.0/PKG-INFO

@@ -0,0 +1,160 @@
+Metadata-Version: 2.5
+Name: aioli-cli
+Version: 0.2.0
+Summary: aioli — local-first AI media suite CLI (images, video, music, voice, podcast)
+Author: aioli contributors
+License: MIT
+License-File: LICENSE
+Keywords: ai,generative,image,local-first,music,tts,video
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.27
+Requires-Dist: huggingface-hub>=0.30
+Requires-Dist: inquirerpy>=0.3.4
+Requires-Dist: numpy>=1.26
+Requires-Dist: pillow>=13.0
+Requires-Dist: pydantic-settings>=2.3
+Requires-Dist: pydantic>=2.7
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: soundfile>=0.12
+Requires-Dist: typer>=0.12
+Provides-Extra: voice-kokoro
+Requires-Dist: kokoro-onnx>=0.4; extra == 'voice-kokoro'
+Provides-Extra: voice-piper
+Requires-Dist: piper-tts>=1.2; extra == 'voice-piper'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/logo-transparent.png" width="220" alt="logo de aioli — ajo robot" />
+</p>
+
+<h1 align="center">🧄 aioli</h1>
+
+<p align="center">
+  <em>Tu estudio de IA en casa: clona voces, compón canciones, dibuja imágenes,<br />genera vídeo y produce podcasts. Todo en tu máquina. Sin nube.</em>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/aioli-cli/"><img src="https://img.shields.io/pypi/v/aioli-cli" alt="versión en PyPI" /></a>
+  <img src="https://img.shields.io/badge/python-%3E%3D3.12-blue" alt="python >= 3.12" />
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT" />
+  <img src="https://img.shields.io/badge/GPU-NVIDIA%20recomendada-orange" alt="GPU NVIDIA recomendada" />
+</p>
+
+<p align="center">
+  🎙️ Voz &nbsp;•&nbsp; 🎵 Música &nbsp;•&nbsp; 🖼️ Imagen &nbsp;•&nbsp; 🎬 Vídeo &nbsp;•&nbsp; 🎧 Master &nbsp;•&nbsp; 📻 Podcast
+</p>
+
+---
+
+## Qué hace (con ejemplos reales)
+
+| Plugin | Produce | Ejemplo |
+| --- | --- | --- |
+| 🎙️ `voice` | Voz clonada o sintética en WAV (español nativo con chatterbox, borradores gratis en CPU con piper) | `aioli voice "Hola mundo" --profile vega -o hola.wav` |
+| 🎵 `music` | Canción completa (voz + instrumentos) a partir de un estilo y tu letra; canta en español | `aioli music --preset reggae-consciente -l mi-letra.txt -o tema.mp3` |
+| 🖼️ `image` | Imagen desde texto, edición, inpainting o referencia de personaje (~9 s con FLUX-klein-4b) | `aioli image "un ajo robot"` |
+| 🎬 `video` | Clip MP4 con audio sincronizado desde texto o imagen | `aioli video "un ajo robot bailando" --frames 81 -o ajo.mp4` |
+| 🎧 `master` | Acabado de audio con ffmpeg: mezcla, ducking, reducción de ruido, `-16 LUFS` | `aioli master loudnorm mezcla.wav -o final.wav` |
+| 📻 `podcast` | Episodio MP3 + notas del programa a partir de un guion (voces + cama musical + pausas) | `aioli podcast episode guion.md -o ./ep1` |
+
+19 canciones, sus carátulas y varios clips se hicieron así, en local,
+con estos comandos. Sin cuentas ni suscripciones.
+
+## Cómo funciona
+
+1. `aioli install` inspecciona tu máquina y te dice qué cabe en tu GPU.
+2. `aioli models download` descarga pesos verificados (sha256, reanudables)
+   en `~/.local/share/aioli/models` (o donde apunte `AIOLI_MODELS_DIR`).
+3. Generas en local: ni un byte sale de tu máquina. Sin cuentas ni
+   suscripciones (ningún modelo del catálogo pide cuenta de HuggingFace).
+
+## Instalación
+
+Tres pasos (Linux, Mac y Windows):
+
+```bash
+# 1. uv, el instalador de Python de Astral (si no lo tienes ya)
+curl -LsSf https://astral.sh/uv/install.sh | sh          # Linux y Mac
+# Windows (PowerShell): powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# 2. aioli
+uv tool install aioli-cli
+
+# 3. el asistente: mira tu equipo, te recomienda qué cabe y descarga solo lo que elijas
+aioli install
+```
+
+Necesitas también `ffmpeg` (Linux: `sudo apt install ffmpeg` · Mac:
+`brew install ffmpeg` · Windows: `winget install ffmpeg`). `aioli doctor`
+te dice si falta algo y cómo arreglarlo. Para actualizar: `aioli update`.
+
+> Próximamente: instalador de un solo comando que hace los tres pasos (y
+> ffmpeg, preguntando antes). Ya está en `install.sh` del repo.
+
+### ¿No eres técnico? Pídeselo a tu asistente de IA
+
+Si usas Claude Code (u otro asistente que ejecuta comandos):
+
+```bash
+aioli agent install     # le enseña a tu asistente a instalar y usar aioli
+```
+
+Y luego pídele, sin más: *«instálame aioli para hacer canciones con mi letra»*.
+El asistente mira tu equipo (`aioli status --json`), te propone qué instalar con
+su tamaño y licencia, **pregunta antes de descargar** y nunca usa `sudo`.
+Para otros asistentes, `aioli agent guide` imprime la misma guía.
+
+## Requisitos
+
+| Qué | Mínimo | Recomendado |
+| --- | --- | --- |
+| SO | Linux (Ubuntu 22.04+), Mac | Ubuntu 24.04 |
+| GPU | ninguna (voz en CPU con piper) | NVIDIA 12–16 GB de VRAM |
+| Disco | 15 GB (un plugin) | 100 GB (el conjunto completo ≈ 60 GB) |
+| Cuenta | — | — (sin cuentas: espejos públicos verificados) |
+
+`aioli install` detecta tu máquina (nivel `patata/modesta/capaz/bicha`,
+sí, de patata a bestia) y solo descarga lo que cabe. Los pesos se verifican
+con sha256 y se reanudan si se corta tu conexión.
+
+## Uso
+
+Camino feliz: `aioli install` → `aioli <plugin> "texto"` → `aioli doctor`
+(solo si algo falla). Las recetas por modelo están en `docs/USAGE.md`.
+
+```bash
+# imagen: texto → PNG (edición, inpainting y referencia disponibles)
+aioli image "un faro en la niebla"
+aioli image "un faro en la niebla" -m z-image-turbo -o faro.png
+
+# música: estilo + tu letra → canción completa
+aioli music "rumba alegre" -l mi-letra.txt -o tema.mp3
+aioli music generate --preset reggae-consciente -l mi-letra.txt -o tema.mp3
+
+# voz: crea un perfil, añade una muestra con su transcripción, genera
+aioli voice profiles create vega --language es
+aioli voice profiles add-sample vega ref.wav -t "transcripción exacta del audio"
+aioli voice "Hola mundo" --profile vega --engine chatterbox -o hola.wav
+
+# vídeo: texto o imagen → clip con audio
+aioli video "un ajo robot bailando" --frames 81 -o ajo.mp4
+
+# podcast: guion con [ROL], [MUSIC:] y [PAUSE:] → episodio + notas
+aioli podcast episode guion.md -o ./ep1
+
+# master: remata cualquier audio (mezcla, ducking, -16 LUFS…)
+aioli master loudnorm mezcla.wav -o final.wav
+```
+
+`aioli <plugin> --help` detalla cada comando; `aioli doctor` diagnostica
+los fallos.
+
+## Licencia
+
+MIT. Los pesos de terceros llevan su propia licencia (algunos no comerciales
+o con aceptación previa en HuggingFace); `aioli models` te avisa.

aioli_cli-0.2.0/README.md

@@ -0,0 +1,130 @@
+<p align="center">
+  <img src="assets/logo-transparent.png" width="220" alt="logo de aioli — ajo robot" />
+</p>
+
+<h1 align="center">🧄 aioli</h1>
+
+<p align="center">
+  <em>Tu estudio de IA en casa: clona voces, compón canciones, dibuja imágenes,<br />genera vídeo y produce podcasts. Todo en tu máquina. Sin nube.</em>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/aioli-cli/"><img src="https://img.shields.io/pypi/v/aioli-cli" alt="versión en PyPI" /></a>
+  <img src="https://img.shields.io/badge/python-%3E%3D3.12-blue" alt="python >= 3.12" />
+  <img src="https://img.shields.io/badge/license-MIT-green" alt="MIT" />
+  <img src="https://img.shields.io/badge/GPU-NVIDIA%20recomendada-orange" alt="GPU NVIDIA recomendada" />
+</p>
+
+<p align="center">
+  🎙️ Voz &nbsp;•&nbsp; 🎵 Música &nbsp;•&nbsp; 🖼️ Imagen &nbsp;•&nbsp; 🎬 Vídeo &nbsp;•&nbsp; 🎧 Master &nbsp;•&nbsp; 📻 Podcast
+</p>
+
+---
+
+## Qué hace (con ejemplos reales)
+
+| Plugin | Produce | Ejemplo |
+| --- | --- | --- |
+| 🎙️ `voice` | Voz clonada o sintética en WAV (español nativo con chatterbox, borradores gratis en CPU con piper) | `aioli voice "Hola mundo" --profile vega -o hola.wav` |
+| 🎵 `music` | Canción completa (voz + instrumentos) a partir de un estilo y tu letra; canta en español | `aioli music --preset reggae-consciente -l mi-letra.txt -o tema.mp3` |
+| 🖼️ `image` | Imagen desde texto, edición, inpainting o referencia de personaje (~9 s con FLUX-klein-4b) | `aioli image "un ajo robot"` |
+| 🎬 `video` | Clip MP4 con audio sincronizado desde texto o imagen | `aioli video "un ajo robot bailando" --frames 81 -o ajo.mp4` |
+| 🎧 `master` | Acabado de audio con ffmpeg: mezcla, ducking, reducción de ruido, `-16 LUFS` | `aioli master loudnorm mezcla.wav -o final.wav` |
+| 📻 `podcast` | Episodio MP3 + notas del programa a partir de un guion (voces + cama musical + pausas) | `aioli podcast episode guion.md -o ./ep1` |
+
+19 canciones, sus carátulas y varios clips se hicieron así, en local,
+con estos comandos. Sin cuentas ni suscripciones.
+
+## Cómo funciona
+
+1. `aioli install` inspecciona tu máquina y te dice qué cabe en tu GPU.
+2. `aioli models download` descarga pesos verificados (sha256, reanudables)
+   en `~/.local/share/aioli/models` (o donde apunte `AIOLI_MODELS_DIR`).
+3. Generas en local: ni un byte sale de tu máquina. Sin cuentas ni
+   suscripciones (ningún modelo del catálogo pide cuenta de HuggingFace).
+
+## Instalación
+
+Tres pasos (Linux, Mac y Windows):
+
+```bash
+# 1. uv, el instalador de Python de Astral (si no lo tienes ya)
+curl -LsSf https://astral.sh/uv/install.sh | sh          # Linux y Mac
+# Windows (PowerShell): powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
+
+# 2. aioli
+uv tool install aioli-cli
+
+# 3. el asistente: mira tu equipo, te recomienda qué cabe y descarga solo lo que elijas
+aioli install
+```
+
+Necesitas también `ffmpeg` (Linux: `sudo apt install ffmpeg` · Mac:
+`brew install ffmpeg` · Windows: `winget install ffmpeg`). `aioli doctor`
+te dice si falta algo y cómo arreglarlo. Para actualizar: `aioli update`.
+
+> Próximamente: instalador de un solo comando que hace los tres pasos (y
+> ffmpeg, preguntando antes). Ya está en `install.sh` del repo.
+
+### ¿No eres técnico? Pídeselo a tu asistente de IA
+
+Si usas Claude Code (u otro asistente que ejecuta comandos):
+
+```bash
+aioli agent install     # le enseña a tu asistente a instalar y usar aioli
+```
+
+Y luego pídele, sin más: *«instálame aioli para hacer canciones con mi letra»*.
+El asistente mira tu equipo (`aioli status --json`), te propone qué instalar con
+su tamaño y licencia, **pregunta antes de descargar** y nunca usa `sudo`.
+Para otros asistentes, `aioli agent guide` imprime la misma guía.
+
+## Requisitos
+
+| Qué | Mínimo | Recomendado |
+| --- | --- | --- |
+| SO | Linux (Ubuntu 22.04+), Mac | Ubuntu 24.04 |
+| GPU | ninguna (voz en CPU con piper) | NVIDIA 12–16 GB de VRAM |
+| Disco | 15 GB (un plugin) | 100 GB (el conjunto completo ≈ 60 GB) |
+| Cuenta | — | — (sin cuentas: espejos públicos verificados) |
+
+`aioli install` detecta tu máquina (nivel `patata/modesta/capaz/bicha`,
+sí, de patata a bestia) y solo descarga lo que cabe. Los pesos se verifican
+con sha256 y se reanudan si se corta tu conexión.
+
+## Uso
+
+Camino feliz: `aioli install` → `aioli <plugin> "texto"` → `aioli doctor`
+(solo si algo falla). Las recetas por modelo están en `docs/USAGE.md`.
+
+```bash
+# imagen: texto → PNG (edición, inpainting y referencia disponibles)
+aioli image "un faro en la niebla"
+aioli image "un faro en la niebla" -m z-image-turbo -o faro.png
+
+# música: estilo + tu letra → canción completa
+aioli music "rumba alegre" -l mi-letra.txt -o tema.mp3
+aioli music generate --preset reggae-consciente -l mi-letra.txt -o tema.mp3
+
+# voz: crea un perfil, añade una muestra con su transcripción, genera
+aioli voice profiles create vega --language es
+aioli voice profiles add-sample vega ref.wav -t "transcripción exacta del audio"
+aioli voice "Hola mundo" --profile vega --engine chatterbox -o hola.wav
+
+# vídeo: texto o imagen → clip con audio
+aioli video "un ajo robot bailando" --frames 81 -o ajo.mp4
+
+# podcast: guion con [ROL], [MUSIC:] y [PAUSE:] → episodio + notas
+aioli podcast episode guion.md -o ./ep1
+
+# master: remata cualquier audio (mezcla, ducking, -16 LUFS…)
+aioli master loudnorm mezcla.wav -o final.wav
+```
+
+`aioli <plugin> --help` detalla cada comando; `aioli doctor` diagnostica
+los fallos.
+
+## Licencia
+
+MIT. Los pesos de terceros llevan su propia licencia (algunos no comerciales
+o con aceptación previa en HuggingFace); `aioli models` te avisa.

{aioli_cli-0.1.46 → aioli_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "aioli-cli"
-version = "0.1.46"
+version = "0.2.0"
 description = "aioli — local-first AI media suite CLI (images, video, music, voice, podcast)"
 readme = "README.md"
 requires-python = ">=3.12"
@@ -26,7 +26,7 @@ dependencies = [
     "pyyaml>=6.0",
     "numpy>=1.26",
     "soundfile>=0.12",
-    "pillow>=10.0",  # stubs de imagen (contrato: stub funciona sin GPU ni extras)
+    "pillow>=13.0",  # 13.0: 35 CVE corregidos (pip-audit 2026-10-22). stubs de imagen (contrato: stub funciona sin GPU ni extras)
 ]
 
 
@@ -39,7 +39,6 @@ voice-piper = ["piper-tts>=1.2"]  # binario + onnxruntime via pip
 # D13: kokoro-onnx fuera de la base (el motor lo importa lazy y el spec
 # declara el extra; antes pesaba en cada fresh install sin usarse).
 voice-kokoro = ["kokoro-onnx>=0.4"]  # motor neural ES (CPU, sin clonar)
-music-storage = ["boto3>=1.34"]
 
 [project.scripts]
 aioli = "aioli_cli.main:main"
@@ -100,6 +99,12 @@ only-include = [
     "LICENSE",
 ]
 
+# Gate de tipos canónico del repo: `mypy src` (los 8 paquetes del wheel único,
+# 111 ficheros en verde). `libs/*` y `plugins/*` no aportan código (ver ADR-005),
+# así que un typecheck por miembro sería un falso scope. Lo consume wave-gate.
+[tool.wave-gate]
+typecheck = "mypy src"
+
 [tool.pytest.ini_options]
 pythonpath = ["src"]
 testpaths = [
@@ -111,7 +116,11 @@ testpaths = [
     "plugins/podcast/tests",
     "plugins/master/tests",
 ]
-addopts = "-q"
+# I4 (2026-10-05, wave-7/T28): cobertura MEDIDA en el run normal (pytest-cov,
+# dev dep). Sin `fail-under` ni exclusiones: medir no es un gate, y un umbral
+# inventado sin baseline sería ruido. Regresión de config:
+# `libs/contract/tests/test_bootstrap.py::TestCoverageConfig`.
+addopts = "-q -n auto --cov=src --cov-report=term-missing --cov-report=xml"
 # Markers: "network" sube a upstream real (gasta red y disco). Opt-in via
 # AIOLI_NET_TESTS=1, lo activa el job smoke-bundles de release.yml.
 markers = [
@@ -121,6 +130,7 @@ markers = [
 [dependency-groups]
 dev = [
     "pytest>=8.0",
+    "pytest-cov>=7.0",  # I4: cobertura del run normal (term-missing + xml)
     "pillow>=10.0",  # solo tests (stubs de imagen); nunca en dependencies
     # H0.4: tooling de CI pineado aqui (no en `uvx` run-steps) para que
     # dependabot lo renueve: no ve herramientas invocadas con `uvx` en los
@@ -128,6 +138,7 @@ dev = [
     "ruff==0.16.8",
     "mypy==2.3.1",
     "pip-audit==2.10.1",
+    "pytest-xdist>=3.6",
 ]
 
 [tool.mypy]
@@ -161,25 +172,20 @@ ignore_missing_imports = true
 module = ["soundfile", "soundfile.*", "tqdm"]
 ignore_missing_imports = true
 
-# Out-of-venv checkers (session lens) run mypy WITHOUT the project venv:
-# pytest (dev dep) and aioli_contract (workspace pkg in libs/contract, editable
-# in .venv) don't resolve there and mypy reports import-not-found — false
-# positive. In the real env they resolve (`.venv/bin/python -c "import pytest,
-# aioli_contract"` OK; ruff + pytest --collect-only green on libs/contract/tests).
-# ignore_missing_imports only fires when resolution fails, so the repo's own
-# venv runs keep full checking.
+# I3 (2026-10-05, wave-7/T27): los paquetes PROPIOS (`aioli_*`) salen de aquí.
+# Estaban por el falso positivo F-10 (mypy sin venv no resolvía `src/`), pero
+# `ignore_missing_imports` sobre un paquete propio silencia justo lo que debe
+# fallar: un import roto de `aioli_contract`/`aioli_cli`/... pasaba verde.
+# `mypy_path = "src"` + `explicit_package_bases` ya resuelven los paquetes
+# propios con la config leída desde la raíz, que es como lo ejecuta wave-gate y
+# el job `test` de release.yml. Regresión:
+# `libs/contract/tests/test_models_import.py::TestOwnImports`.
+# pytest (dev dep) sí sigue fuera del venv en algunos lenses: ese override se
+# queda.
 [[tool.mypy.overrides]]
-module = ["pytest", "pytest.*", "aioli_contract", "aioli_contract.*"]
+module = ["pytest", "pytest.*"]
 ignore_missing_imports = true
 
-# DEBT: aioli_music.core.jobs imports aioli_music.core.storage, which does not
-# exist (unimplemented object-storage feature); nothing imports jobs. Decide:
-# implement storage or delete the module. Until then its errors stay hidden
-# but listed here — not silently green.
-[[tool.mypy.overrides]]
-module = ["aioli_music.core.jobs"]
-ignore_errors = true
-
 [tool.ruff]
 line-length = 100
 target-version = "py312"

aioli_cli-0.2.0/src/aioli_cli/agent_guide.md

@@ -0,0 +1,111 @@
+---
+name: aioli
+description: Instala, diagnostica y usa aioli (estudio de IA local - voz, música, imagen, vídeo, podcast) en el ordenador del usuario. Úsala cuando el usuario quiera instalar aioli o sus modelos, saber qué puede usar en su equipo, arreglar un fallo de aioli o generar voz, canciones, imágenes o vídeo con aioli.
+---
+
+# aioli: guía para agentes
+
+aioli genera voz, música, imagen y vídeo en local. El usuario puede no ser
+técnico: tú ejecutas los comandos, él decide. Todo comando tiene salida
+`--json` estable donde importa; léela en vez de interpretar tablas.
+
+## Reglas (no negociables)
+
+1. **Pregunta antes de descargar.** Di cuántos GB y para qué; espera un sí.
+2. **Nunca uses `sudo`.** Si falta algo del sistema (ffmpeg), dile al usuario
+   el comando exacto y que lo ejecute él.
+3. **Nunca pidas tokens ni contraseñas por el chat.** Ningún modelo del
+   catálogo necesita cuenta de HuggingFace; si alguna vez hiciera falta, el
+   usuario ejecuta `hf auth login` él mismo.
+4. **Respeta las licencias.** Cada motor trae `license`/`license_note` en
+   `aioli status --json`. Si es `no comercial` o `condicional`, avísalo antes
+   de instalarlo o de usarlo para algo que el usuario quiera publicar o vender.
+5. **No borres modelos ni configuración** sin que el usuario lo pida.
+6. **No compartas la GPU a ciegas:** si hay otras apps usándola, usa `--gpu`
+   (`aioli status --json` → `machine.gpus[].free_gb`).
+
+## 1. ¿Está instalado?
+
+```bash
+aioli version            # si falla: no está instalado
+```
+
+Si no está: `uv tool install aioli-cli`. Si tampoco hay `uv`, instálalo
+primero con el instalador oficial de Astral (Linux/Mac:
+`curl -LsSf https://astral.sh/uv/install.sh | sh`; Windows PowerShell:
+`irm https://astral.sh/uv/install.ps1 | iex`) — pide permiso antes. Falta
+`ffmpeg`: dile al usuario el comando de su sistema (regla 2).
+
+## 2. Lee el equipo y lo que cabe
+
+```bash
+aioli status --json
+```
+
+- `machine`: sistema, nivel (`patata`/`modesta`/`capaz`/`bicha`), GPUs con
+  VRAM libre, RAM y disco libre.
+- `engines[]`: por cada `plugin`/`engine` → `state` (`listo` | `instalable` |
+  `no_cabe`), `suggested` (el recomendado para este equipo), `download_gb`,
+  `fix` (comando exacto para dejarlo listo), licencia, calidad y velocidad.
+
+Propón al usuario los `suggested` que le interesen, con su tamaño y licencia.
+
+## 3. Instala lo que el usuario apruebe
+
+```bash
+aioli install --plugins voice,image --yes     # usos completos (motor sugerido)
+aioli models download music -b heartmula --yes   # un motor concreto (el `fix`)
+aioli backend install video longcat --yes        # vídeo: instala WanGP y sus modelos
+```
+
+Códigos de salida de `aioli install`: `0` hecho, `3` no se eligió nada,
+cualquier otro = error (lee la salida y pasa al paso 5).
+
+Comprueba con `aioli status --json` que el motor quedó en `state: "listo"`.
+
+## 4. Usarlo
+
+```bash
+aioli voice "Hola, soy Aioli" -o hola.wav                    # voz (motor por defecto)
+aioli voice profiles create vega --language es              # clonar una voz:
+aioli voice profiles add-sample vega muestra.wav            #   5-30 s limpios
+aioli voice "Texto" --profile vega -m chatterbox-gguf -o v.wav
+aioli music "rumba alegre, guitarra española" -l letra.txt -o tema.mp3
+aioli music "…" -m heartmula -l letra.txt --gpu auto        # mejor dicción en español
+aioli image "un faro en la niebla" -o faro.png
+aioli image "el personaje en la playa" -m flux3-klein -r personaje.png -o p.png
+aioli video "un ajo robot bailando" -o ajo.mp4               # vídeo con voz (NVIDIA)
+aioli video generate "…" -m longcat -r cara.png --audio-guide voz.wav --frames 225 -o avatar.mp4
+                                                             # avatar que habla con esa voz
+```
+
+`aioli <plugin> --help` lista todas las opciones. Las letras de canciones van
+en un fichero de texto con `[verse]`, `[chorus]`, etc.
+
+## 5. Si algo falla
+
+```bash
+aioli doctor --json
+```
+
+`checks[]` trae `name`, `ok` y `detail`. Los `extra:*` de voz en rojo son
+motores opcionales sin instalar: no son un fallo si el usuario no los usa.
+Para un motor concreto, aplica el `fix` de `aioli status --json`. Errores
+típicos y qué hacer:
+
+- «No hay espacio en disco»: dile cuánto falta; puede liberar espacio o
+  guardar los modelos en otro disco con `AIOLI_MODELS_DIR=/ruta`.
+- «necesita unos N GB de RAM/memoria de vídeo»: ese motor no es para este
+  equipo; usa el `suggested`.
+- «checksum mismatch»: repite la descarga; si persiste, avisa al usuario
+  (puede ser un problema de red o del repositorio).
+
+## 6. Actualizar o desinstalar (solo si lo pide)
+
+```bash
+aioli update --yes                 # última versión, conserva motores y extras
+aioli uninstall --yes              # quita el programa; conserva modelos y creaciones
+aioli uninstall --delete-models --yes   # también los modelos (decenas de GB): pregunta antes
+```
+
+`uninstall` nunca borra lo que el usuario ha creado ni `~/ai/models`.