theus-cli-linux-arm64 0.2.84

package/vendor/theus-arsenal/skills/decisiones-arquitectura/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: decisiones-arquitectura
+description: Captura las decisiones arquitectónicas tomadas durante las sesiones de Theus como ADR estructurados. Detecta los momentos de decisión, registra el contexto, las alternativas consideradas y la justificación. Mantiene el registro de ADR en el almacén de Ñaupa (tool manage_adr del MCP theus-naupa) para que los futuros desarrolladores entiendan por qué el código base tiene la forma que tiene.
+---
+
+# Registros de decisiones de arquitectura (ADR)
+
+Captura las decisiones arquitectónicas en el momento en que ocurren durante las sesiones de trabajo. En lugar de que las decisiones vivan solo en hilos de chat, comentarios de PR o en la memoria de alguien, esta skill produce documentos ADR estructurados que viven junto al proyecto.
+
+**En Theus, los ADR se gestionan a través de la tool `manage_adr` del MCP `theus-naupa`**, no como archivos sueltos en el repo. Ñaupa guarda el documento ADR del proyecto en su almacén SQLite (el mismo backend que usa la sección ADR del panel de Ñaupa, así que lo escrito por la tool es visible en la interfaz y viceversa). No crees estructuras paralelas tipo `docs/adr/` a menos que el usuario lo pida explícitamente.
+
+## Cuándo activarla
+
+- El usuario dice explícitamente "registra esta decisión" o "haz un ADR de esto"
+- El usuario elige entre alternativas significativas (framework, librería, patrón, base de datos, diseño de API)
+- El usuario dice "decidimos que..." o "la razón por la que hacemos X en vez de Y es..."
+- El usuario pregunta "¿por qué elegimos X?" (leer los ADR existentes)
+- Durante fases de planificación en las que se discuten compensaciones arquitectónicas
+
+## La tool manage_adr
+
+```
+manage_adr(project, mode?, content?)
+```
+
+| Parámetro | Descripción |
+|-----------|-------------|
+| `project` | Obligatorio. Nombre del proyecto tal como está indexado en Ñaupa (si dudas, consúltalo con `list_projects`). |
+| `mode` | `get` (por defecto) devuelve el documento ADR completo; `sections` lista los encabezados Markdown (líneas que empiezan con `#`) — sirve de índice; `update` guarda `content` como el documento ADR del proyecto. |
+| `content` | Solo con `mode='update'`: el documento ADR **completo** en Markdown. |
+
+**Regla crítica: `update` reemplaza el documento entero.** El flujo de escritura es siempre leer-modificar-escribir:
+
+1. `manage_adr(project, mode='get')` → obtén el documento actual
+2. Añade o modifica la sección del ADR en cuestión
+3. `manage_adr(project, mode='update', content=<documento completo actualizado>)`
+
+Nunca envíes solo el ADR nuevo como `content`: borrarías el histórico.
+
+## Formato de ADR
+
+Usa el formato de ADR ligero propuesto por Michael Nygard, adaptado al desarrollo asistido por IA. Cada decisión es una sección de nivel 1 dentro del documento ADR del proyecto, de modo que `mode='sections'` funcione como índice:
+
+```markdown
+# ADR-NNNN: [Título de la decisión]
+
+**Fecha**: AAAA-MM-DD
+**Estado**: propuesto | aceptado | obsoleto | reemplazado por ADR-NNNN
+**Decisores**: [quiénes participaron]
+
+## Contexto
+
+¿Qué problema estamos viendo que motiva esta decisión o este cambio?
+
+[2-5 frases describiendo la situación, las restricciones y las fuerzas en juego]
+
+## Decisión
+
+¿Qué cambio proponemos y/o estamos haciendo?
+
+[1-3 frases enunciando la decisión con claridad]
+
+## Alternativas consideradas
+
+### Alternativa 1: [Nombre]
+- **Pros**: [beneficios]
+- **Contras**: [inconvenientes]
+- **Por qué no**: [razón concreta por la que se descartó]
+
+### Alternativa 2: [Nombre]
+- **Pros**: [beneficios]
+- **Contras**: [inconvenientes]
+- **Por qué no**: [razón concreta por la que se descartó]
+
+## Consecuencias
+
+¿Qué se vuelve más fácil o más difícil a raíz de este cambio?
+
+### Positivas
+- [beneficio 1]
+- [beneficio 2]
+
+### Negativas
+- [compensación 1]
+- [compensación 2]
+
+### Riesgos
+- [riesgo y mitigación]
+```
+
+## Flujo de trabajo
+
+### Capturar un ADR nuevo
+
+Cuando se detecta un momento de decisión:
+
+1. **Inicializar (solo la primera vez)** — llama a `manage_adr(project, mode='get')`. Si responde `status: "no_adr"`, pide confirmación al usuario antes de crear el primer documento ADR del proyecto. No escribas nada sin consentimiento explícito. (Nota: si Ñaupa sugiere secciones genéricas como PURPOSE/STACK/ARCHITECTURE, esas corresponden a su resumen de proyecto guiado; para esta skill, el documento se estructura como secciones `# ADR-NNNN:` numeradas.)
+2. **Identificar la decisión** — extrae la elección arquitectónica central que se está tomando
+3. **Reunir el contexto** — ¿qué problema la motivó? ¿Qué restricciones existen?
+4. **Documentar las alternativas** — ¿qué otras opciones se consideraron? ¿Por qué se rechazaron?
+5. **Enunciar las consecuencias** — ¿cuáles son las compensaciones? ¿Qué se facilita o se dificulta?
+6. **Asignar un número** — lee el documento actual con `mode='get'` (o el índice con `mode='sections'`), localiza el mayor `ADR-NNNN` e incrementa
+7. **Confirmar y escribir** — presenta el borrador del ADR al usuario para revisión. Solo tras su aprobación explícita, guarda con el flujo leer-modificar-escribir: `get` → añadir la sección nueva → `update` con el documento completo. Si el usuario declina, descarta el borrador sin escribir nada.
+
+### Leer los ADR existentes
+
+Cuando el usuario pregunta "¿por qué elegimos X?":
+
+1. Llama a `manage_adr(project, mode='get')` — si responde `status: "no_adr"`, contesta: "No hay ADR registrados en este proyecto. ¿Quieres empezar a registrar las decisiones arquitectónicas?"
+2. Si existe, usa `mode='sections'` como índice para localizar las entradas relevantes
+3. Presenta las secciones Contexto y Decisión del ADR que corresponda
+4. Si no hay coincidencia, responde: "No encuentro un ADR para esa decisión. ¿Quieres registrarla ahora?"
+
+### Estructura del documento ADR
+
+Un único documento Markdown por proyecto, almacenado en Ñaupa:
+
+```markdown
+# ADR-0001: Usar Next.js como framework de frontend
+...
+
+# ADR-0002: PostgreSQL sobre MongoDB como almacén primario
+...
+
+# ADR-0003: API REST sobre GraphQL
+...
+```
+
+### Índice
+
+No hace falta mantener un índice manual: `manage_adr(project, mode='sections')` devuelve los encabezados del documento, que con el formato `# ADR-NNNN: Título` funcionan directamente como tabla de contenidos:
+
+```json
+{
+  "sections": [
+    "# ADR-0001: Usar Next.js como framework de frontend",
+    "# ADR-0002: PostgreSQL sobre MongoDB como almacén primario",
+    "# ADR-0003: API REST sobre GraphQL"
+  ]
+}
+```
+
+## Señales de detección de decisiones
+
+Vigila estos patrones en la conversación que indican una decisión arquitectónica:
+
+**Señales explícitas**
+- "Vamos con X"
+- "Deberíamos usar X en lugar de Y"
+- "La compensación vale la pena porque..."
+- "Registra esto como un ADR"
+
+**Señales implícitas** (sugiere registrar un ADR — no lo crees automáticamente sin confirmación del usuario)
+- Comparar dos frameworks o librerías y llegar a una conclusión
+- Tomar una decisión de diseño de esquema de base de datos con justificación explícita
+- Elegir entre patrones arquitectónicos (monolito vs microservicios, REST vs GraphQL)
+- Decidir la estrategia de autenticación/autorización
+- Seleccionar la infraestructura de despliegue tras evaluar alternativas
+
+## Qué hace bueno a un ADR
+
+### Haz
+- **Sé específico** — "Usar el ORM Prisma", no "usar un ORM"
+- **Registra el porqué** — la justificación importa más que el qué
+- **Incluye las alternativas rechazadas** — los futuros desarrolladores necesitan saber qué se consideró
+- **Enuncia las consecuencias con honestidad** — toda decisión tiene compensaciones
+- **Mantenlo corto** — un ADR debe poder leerse en 2 minutos
+- **Usa el presente** — "Usamos X", no "Usaremos X"
+
+### No hagas
+- Registrar decisiones triviales — los nombres de variables o el formato no necesitan ADR
+- Escribir ensayos — si la sección de contexto supera las 10 líneas, es demasiado larga
+- Omitir alternativas — "simplemente lo elegimos" no es una justificación válida
+- Retrodatar sin marcarlo — si registras una decisión pasada, anota la fecha original
+- Dejar que los ADR caduquen — las decisiones reemplazadas deben referenciar a su reemplazo
+
+## Ciclo de vida de un ADR
+
+```
+propuesto → aceptado → [obsoleto | reemplazado por ADR-NNNN]
+```
+
+- **propuesto**: la decisión está en discusión, aún no comprometida
+- **aceptado**: la decisión está en vigor y se sigue
+- **obsoleto**: la decisión ya no es relevante (p. ej., se eliminó la funcionalidad)
+- **reemplazado**: un ADR más nuevo sustituye a este (enlaza siempre el reemplazo)
+
+Los cambios de estado también siguen el flujo leer-modificar-escribir: `get` → editar la línea **Estado** de la sección afectada → `update` con el documento completo.
+
+## Categorías de decisiones que vale la pena registrar
+
+| Categoría | Ejemplos |
+|-----------|----------|
+| **Elecciones de tecnología** | Framework, lenguaje, base de datos, proveedor de nube |
+| **Patrones de arquitectura** | Monolito vs microservicios, orientado a eventos, CQRS |
+| **Diseño de API** | REST vs GraphQL, estrategia de versionado, mecanismo de auth |
+| **Modelado de datos** | Diseño de esquema, decisiones de normalización, estrategia de caché |
+| **Infraestructura** | Modelo de despliegue, pipeline de CI/CD, stack de monitorización |
+| **Seguridad** | Estrategia de auth, enfoque de cifrado, gestión de secretos |
+| **Testing** | Framework de tests, metas de cobertura, balance E2E vs integración |
+| **Proceso** | Estrategia de branches, proceso de revisión, cadencia de releases |
+
+## Integración con otras skills
+
+- **Agente `planificador`**: cuando el planificador proponga cambios de arquitectura, sugiere crear un ADR
+- **Agente `revisor-codigo`**: marca los PR que introducen cambios arquitectónicos sin su ADR correspondiente

package/vendor/theus-arsenal/skills/demos-ui/SKILL.md

@@ -0,0 +1,469 @@
+---
+name: demos-ui
+description: Graba videos de demo pulidos de aplicaciones web usando Playwright. Úsala cuando se pida un demo, walkthrough, grabación de pantalla o video tutorial de una app web. Produce videos WebM con cursor visible, ritmo natural y acabado profesional.
+---
+
+# Grabador de demos de UI
+
+Graba videos de demostración pulidos de aplicaciones web usando la grabación de video de Playwright con un cursor superpuesto inyectado, ritmo natural y flujo narrativo.
+
+## Cuándo usarla
+
+- Se pide un "video demo", "grabación de pantalla", "walkthrough" o "tutorial"
+- Se quiere mostrar visualmente una funcionalidad o un flujo de trabajo
+- Se necesita un video para documentación, onboarding o presentación a stakeholders
+
+## Proceso en tres fases
+
+Todo demo pasa por tres fases: **Descubrir -> Ensayar -> Grabar**. Nunca saltes directo a grabar.
+
+---
+
+## Fase 1: Descubrir
+
+Antes de escribir cualquier script, explora las páginas objetivo para entender qué hay realmente.
+
+### Por qué
+
+No puedes guionizar lo que no has visto. Los campos pueden ser `<input>` y no `<textarea>`, los desplegables pueden ser componentes personalizados y no `<select>`, y las cajas de comentarios pueden soportar `@menciones` o `#tags`. Las suposiciones rompen las grabaciones en silencio.
+
+### Cómo
+
+Navega a cada página del flujo y vuelca sus elementos interactivos:
+
+```javascript
+// Ejecuta esto en cada página del flujo ANTES de escribir el script del demo
+const fields = await page.evaluate(() => {
+  const els = [];
+  document.querySelectorAll('input, select, textarea, button, [contenteditable]').forEach(el => {
+    if (el.offsetParent !== null) {
+      els.push({
+        tag: el.tagName,
+        type: el.type || '',
+        name: el.name || '',
+        placeholder: el.placeholder || '',
+        text: el.textContent?.trim().substring(0, 40) || '',
+        contentEditable: el.contentEditable === 'true',
+        role: el.getAttribute('role') || '',
+      });
+    }
+  });
+  return els;
+});
+console.log(JSON.stringify(fields, null, 2));
+```
+
+### Qué buscar
+
+- **Campos de formulario**: ¿son `<select>`, `<input>`, desplegables personalizados o comboboxes?
+- **Opciones de select**: vuelca valores Y texto de las opciones. Los placeholders suelen tener `value="0"` o `value=""`, que parece no vacío. Usa `Array.from(el.options).map(o => ({ value: o.value, text: o.text }))`. Descarta opciones cuyo texto incluya "Seleccionar"/"Select" o cuyo valor sea `"0"`.
+- **Texto enriquecido**: ¿la caja de comentarios soporta `@menciones`, `#tags`, markdown o emoji? Revisa el texto del placeholder.
+- **Campos obligatorios**: ¿qué campos bloquean el envío del formulario? Revisa `required`, `*` en las etiquetas, e intenta enviar vacío para ver los errores de validación.
+- **Contenido dinámico**: ¿aparecen campos después de rellenar otros?
+- **Textos de botones**: el texto exacto, como `"Enviar"`, `"Submit Request"` o `"Send"`.
+- **Encabezados de columnas de tablas**: en modales basados en tablas, mapea cada `input[type="number"]` a su encabezado de columna en lugar de asumir que todos los inputs numéricos significan lo mismo.
+
+### Salida
+
+Un mapa de campos por página, usado para escribir selectores correctos en el script. Ejemplo:
+
+```text
+/purchase-requests/new:
+  - Código de presupuesto: <select> (primer select de la página, 4 opciones)
+  - Entrega deseada: <input type="date">
+  - Contexto: <textarea> (no input)
+  - Tabla BOM: celdas editables en línea con patrón span.cursor-pointer -> input
+  - Enviar: <button> texto="Submit"
+
+/purchase-requests/N (detalle):
+  - Comentario: <input placeholder="Type a message..."> soporta @usuario y tags #PR
+  - Enviar: <button> texto="Send" (deshabilitado hasta que el input tenga contenido)
+```
+
+---
+
+## Fase 2: Ensayar
+
+Recorre todos los pasos sin grabar. Verifica que cada selector resuelva.
+
+### Por qué
+
+Los fallos silenciosos de selectores son la razón principal por la que se rompen las grabaciones. El ensayo los atrapa antes de desperdiciar una grabación.
+
+### Cómo
+
+Usa `ensureVisible`, un wrapper que registra y falla ruidosamente:
+
+```javascript
+async function ensureVisible(page, locator, label) {
+  const el = typeof locator === 'string' ? page.locator(locator).first() : locator;
+  const visible = await el.isVisible().catch(() => false);
+  if (!visible) {
+    const msg = `ENSAYO FALLIDO: "${label}" no encontrado - selector: ${typeof locator === 'string' ? locator : '(objeto locator)'}`;
+    console.error(msg);
+    const found = await page.evaluate(() => {
+      return Array.from(document.querySelectorAll('button, input, select, textarea, a'))
+        .filter(el => el.offsetParent !== null)
+        .map(el => `${el.tagName}[${el.type || ''}] "${el.textContent?.trim().substring(0, 30)}"`)
+        .join('\n  ');
+    });
+    console.error('  Elementos visibles:\n  ' + found);
+    return false;
+  }
+  console.log(`ENSAYO OK: "${label}"`);
+  return true;
+}
+```
+
+### Estructura del script de ensayo
+
+```javascript
+const steps = [
+  { label: 'Campo de email del login', selector: '#email' },
+  { label: 'Botón de envío del login', selector: 'button[type="submit"]' },
+  { label: 'Botón Nueva solicitud', selector: 'button:has-text("New Request")' },
+  { label: 'Select de código de presupuesto', selector: 'select' },
+  { label: 'Fecha de entrega', selector: 'input[type="date"]:visible' },
+  { label: 'Campo de descripción', selector: 'textarea:visible' },
+  { label: 'Botón Agregar ítem', selector: 'button:has-text("Add Item")' },
+  { label: 'Botón Enviar', selector: 'button:has-text("Submit")' },
+];
+
+let allOk = true;
+for (const step of steps) {
+  if (!await ensureVisible(page, step.selector, step.label)) {
+    allOk = false;
+  }
+}
+if (!allOk) {
+  console.error('ENSAYO FALLIDO - corrige los selectores antes de grabar');
+  process.exit(1);
+}
+console.log('ENSAYO SUPERADO - todos los selectores verificados');
+```
+
+### Cuando el ensayo falla
+
+1. Lee el volcado de elementos visibles.
+2. Encuentra el selector correcto.
+3. Actualiza el script.
+4. Vuelve a ejecutar el ensayo.
+5. Continúa solo cuando todos los selectores pasen.
+
+---
+
+## Fase 3: Grabar
+
+Solo después de que el descubrimiento y el ensayo pasen debes crear la grabación.
+
+### Principios de grabación
+
+#### 1. Flujo narrativo
+
+Planifica el video como una historia. Sigue el orden que pida el usuario, o usa este por defecto:
+
+- **Entrada**: login o navegación al punto de partida
+- **Contexto**: recorre el entorno para que el espectador se oriente
+- **Acción**: ejecuta los pasos del flujo principal
+- **Variación**: muestra una funcionalidad secundaria como ajustes, tema o localización
+- **Resultado**: muestra el desenlace, la confirmación o el nuevo estado
+
+#### 2. Ritmo
+
+- Tras el login: `4s`
+- Tras navegar: `3s`
+- Tras hacer clic en un botón: `2s`
+- Entre pasos importantes: `1.5-2s`
+- Tras la acción final: `3s`
+- Retardo de tipeo: `25-40ms` por carácter
+
+#### 3. Cursor superpuesto
+
+Inyecta un cursor SVG de flecha que sigue los movimientos del mouse:
+
+```javascript
+async function injectCursor(page) {
+  await page.evaluate(() => {
+    if (document.getElementById('demo-cursor')) return;
+    const cursor = document.createElement('div');
+    cursor.id = 'demo-cursor';
+    cursor.innerHTML = `<svg width="24" height="24" viewBox="0 0 24 24" fill="none" xmlns="http://www.w3.org/2000/svg">
+      <path d="M5 3L19 12L12 13L9 20L5 3Z" fill="white" stroke="black" stroke-width="1.5" stroke-linejoin="round"/>
+    </svg>`;
+    cursor.style.cssText = `
+      position: fixed; z-index: 999999; pointer-events: none;
+      width: 24px; height: 24px;
+      transition: left 0.1s, top 0.1s;
+      filter: drop-shadow(1px 1px 2px rgba(0,0,0,0.3));
+    `;
+    cursor.style.left = '0px';
+    cursor.style.top = '0px';
+    document.body.appendChild(cursor);
+    document.addEventListener('mousemove', (e) => {
+      cursor.style.left = e.clientX + 'px';
+      cursor.style.top = e.clientY + 'px';
+    });
+  });
+}
+```
+
+Llama a `injectCursor(page)` después de cada navegación, porque el overlay se destruye al navegar.
+
+#### 4. Movimiento del mouse
+
+Nunca teletransportes el cursor. Muévelo hasta el objetivo antes de hacer clic:
+
+```javascript
+async function moveAndClick(page, locator, label, opts = {}) {
+  const { postClickDelay = 800, ...clickOpts } = opts;
+  const el = typeof locator === 'string' ? page.locator(locator).first() : locator;
+  const visible = await el.isVisible().catch(() => false);
+  if (!visible) {
+    console.error(`ADVERTENCIA: moveAndClick omitido - "${label}" no visible`);
+    return false;
+  }
+  try {
+    await el.scrollIntoViewIfNeeded();
+    await page.waitForTimeout(300);
+    const box = await el.boundingBox();
+    if (box) {
+      await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2, { steps: 10 });
+      await page.waitForTimeout(400);
+    }
+    await el.click(clickOpts);
+  } catch (e) {
+    console.error(`ADVERTENCIA: moveAndClick falló en "${label}": ${e.message}`);
+    return false;
+  }
+  await page.waitForTimeout(postClickDelay);
+  return true;
+}
+```
+
+Cada llamada debe incluir un `label` descriptivo para depuración.
+
+#### 5. Tipeo
+
+Escribe de forma visible, no con relleno instantáneo:
+
+```javascript
+async function typeSlowly(page, locator, text, label, charDelay = 35) {
+  const el = typeof locator === 'string' ? page.locator(locator).first() : locator;
+  const visible = await el.isVisible().catch(() => false);
+  if (!visible) {
+    console.error(`ADVERTENCIA: typeSlowly omitido - "${label}" no visible`);
+    return false;
+  }
+  await moveAndClick(page, el, label);
+  await el.fill('');
+  await el.pressSequentially(text, { delay: charDelay });
+  await page.waitForTimeout(500);
+  return true;
+}
+```
+
+#### 6. Desplazamiento
+
+Usa scroll suave en lugar de saltos:
+
+```javascript
+await page.evaluate(() => window.scrollTo({ top: 400, behavior: 'smooth' }));
+await page.waitForTimeout(1500);
+```
+
+#### 7. Paneo de dashboards
+
+Al mostrar un dashboard o una página de resumen, mueve el cursor sobre los elementos clave:
+
+```javascript
+async function panElements(page, selector, maxCount = 6) {
+  const elements = await page.locator(selector).all();
+  for (let i = 0; i < Math.min(elements.length, maxCount); i++) {
+    try {
+      const box = await elements[i].boundingBox();
+      if (box && box.y < 700) {
+        await page.mouse.move(box.x + box.width / 2, box.y + box.height / 2, { steps: 8 });
+        await page.waitForTimeout(600);
+      }
+    } catch (e) {
+      console.warn(`ADVERTENCIA: panElements omitió el elemento ${i} (selector: "${selector}"): ${e.message}`);
+    }
+  }
+}
+```
+
+#### 8. Subtítulos
+
+Inyecta una barra de subtítulos en la parte inferior del viewport:
+
+```javascript
+async function injectSubtitleBar(page) {
+  await page.evaluate(() => {
+    if (document.getElementById('demo-subtitle')) return;
+    const bar = document.createElement('div');
+    bar.id = 'demo-subtitle';
+    bar.style.cssText = `
+      position: fixed; bottom: 0; left: 0; right: 0; z-index: 999998;
+      text-align: center; padding: 12px 24px;
+      background: rgba(0, 0, 0, 0.75);
+      color: white; font-family: -apple-system, "Segoe UI", sans-serif;
+      font-size: 16px; font-weight: 500; letter-spacing: 0.3px;
+      transition: opacity 0.3s;
+      pointer-events: none;
+    `;
+    bar.textContent = '';
+    bar.style.opacity = '0';
+    document.body.appendChild(bar);
+  });
+}
+
+async function showSubtitle(page, text) {
+  await page.evaluate((t) => {
+    const bar = document.getElementById('demo-subtitle');
+    if (!bar) return;
+    if (t) {
+      bar.textContent = t;
+      bar.style.opacity = '1';
+    } else {
+      bar.style.opacity = '0';
+    }
+  }, text);
+  if (text) await page.waitForTimeout(800);
+}
+```
+
+Llama a `injectSubtitleBar(page)` junto con `injectCursor(page)` después de cada navegación.
+
+Patrón de uso:
+
+```javascript
+await showSubtitle(page, 'Paso 1 - Iniciando sesión');
+await showSubtitle(page, 'Paso 2 - Vista general del dashboard');
+await showSubtitle(page, '');
+```
+
+Pautas:
+
+- Mantén el texto del subtítulo corto, idealmente menos de 60 caracteres.
+- Usa el formato `Paso N - Acción` para mantener consistencia.
+- Borra el subtítulo durante pausas largas en las que la UI habla por sí sola.
+
+## Plantilla del script
+
+```javascript
+'use strict';
+const { chromium } = require('playwright');
+const path = require('path');
+const fs = require('fs');
+
+const BASE_URL = process.env.QA_BASE_URL || 'http://localhost:3000';
+const VIDEO_DIR = path.join(__dirname, 'screenshots');
+const OUTPUT_NAME = 'demo-FUNCIONALIDAD.webm';
+const REHEARSAL = process.argv.includes('--rehearse');
+
+// Pega aquí injectCursor, injectSubtitleBar, showSubtitle, moveAndClick,
+// typeSlowly, ensureVisible y panElements.
+
+(async () => {
+  const browser = await chromium.launch({ headless: true });
+
+  if (REHEARSAL) {
+    const context = await browser.newContext({ viewport: { width: 1280, height: 720 } });
+    const page = await context.newPage();
+    // Navega por el flujo y ejecuta ensureVisible para cada selector.
+    await browser.close();
+    return;
+  }
+
+  const context = await browser.newContext({
+    recordVideo: { dir: VIDEO_DIR, size: { width: 1280, height: 720 } },
+    viewport: { width: 1280, height: 720 }
+  });
+  const page = await context.newPage();
+
+  try {
+    await injectCursor(page);
+    await injectSubtitleBar(page);
+
+    await showSubtitle(page, 'Paso 1 - Iniciando sesión');
+    // acciones de login
+
+    await page.goto(`${BASE_URL}/dashboard`);
+    await injectCursor(page);
+    await injectSubtitleBar(page);
+    await showSubtitle(page, 'Paso 2 - Vista general del dashboard');
+    // paneo del dashboard
+
+    await showSubtitle(page, 'Paso 3 - Flujo principal');
+    // secuencia de acciones
+
+    await showSubtitle(page, 'Paso 4 - Resultado');
+    // revelación final
+    await showSubtitle(page, '');
+  } catch (err) {
+    console.error('ERROR DEL DEMO:', err.message);
+  } finally {
+    await context.close();
+    const video = page.video();
+    if (video) {
+      const src = await video.path();
+      const dest = path.join(VIDEO_DIR, OUTPUT_NAME);
+      try {
+        fs.copyFileSync(src, dest);
+        console.log('Video guardado:', dest);
+      } catch (e) {
+        console.error('ERROR: no se pudo copiar el video:', e.message);
+        console.error('  Origen:', src);
+        console.error('  Destino:', dest);
+      }
+    }
+    await browser.close();
+  }
+})();
+```
+
+Uso:
+
+```bash
+# Fase 2: ensayar
+node demo-script.cjs --rehearse
+
+# Fase 3: grabar
+node demo-script.cjs
+```
+
+## Lista de verificación antes de grabar
+
+- [ ] Fase de descubrimiento completada
+- [ ] El ensayo pasa con todos los selectores OK
+- [ ] Modo headless habilitado
+- [ ] Resolución fijada en `1280x720`
+- [ ] Overlays de cursor y subtítulos reinyectados tras cada navegación
+- [ ] `showSubtitle(page, 'Paso N - ...')` usado en las transiciones importantes
+- [ ] `moveAndClick` usado en todos los clics con labels descriptivos
+- [ ] `typeSlowly` usado para entrada visible
+- [ ] Sin catch silenciosos; los helpers registran advertencias
+- [ ] Scroll suave usado para revelar contenido
+- [ ] Las pausas clave son visibles para un espectador humano
+- [ ] El flujo coincide con el orden narrativo solicitado
+- [ ] El script refleja la UI real descubierta en la fase 1
+
+## Errores comunes
+
+1. El cursor desaparece tras navegar - reinyéctalo.
+2. El video va demasiado rápido - añade pausas.
+3. El cursor es un punto en vez de una flecha - usa el overlay SVG.
+4. El cursor se teletransporta - muévelo antes de hacer clic.
+5. Los desplegables se ven mal - muestra el movimiento y luego elige la opción.
+6. Los modales se sienten abruptos - añade una pausa de lectura antes de confirmar.
+7. La ruta del archivo de video es aleatoria - cópialo a un nombre de salida estable.
+8. Los fallos de selectores se tragan en silencio - nunca uses bloques catch silenciosos.
+9. Se asumieron tipos de campo - descúbrelos primero.
+10. Se asumieron funcionalidades - inspecciona la UI real antes de guionizar.
+11. Los valores placeholder de los select parecen reales - vigila `"0"` y `"Select..."`.
+12. Los popups crean videos separados - captura las páginas popup explícitamente y fusiona después si hace falta.
+
+## Skills relacionadas
+
+- `testing-e2e` — pruebas E2E web con Playwright
+- `qa-navegador` — verificación de UI en el navegador