@xmarts/genius-setup 1.13.1 → 1.14.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xmarts/genius-setup",
-  "version": "1.13.1",
+  "version": "1.14.0",
   "description": "One-command, self-updating onboarding for Xmarts Genius (Brain MCP + per-turn injection + automatic session/time capture + presence heartbeat for honest time-tracking 'amarre' + plan/committee→Brain enforcement + CLAUDE.md protocol + MCP fan-out: provisions the consultant's granted MCP servers into Claude Code & Claude Desktop). Secret-free onboarding via single-use setup-token exchange. Installs once; self-updates daily so new tools/skills/features arrive with zero action.",
   "bin": {
     "genius-setup": "bin/genius-setup.js"

package/plugin/skills/contentforge/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: contentforge
+description: ContentForge — Content Command Center de Xmarts. USAR cuando el usuario pida producir contenido/videos de contenido (guion con fórmulas probadas, pipeline artículo→video, News Animator, hooks A/B, fact-check con fuentes, teleprompter, voz TTS karaoke) o mencione ContentForge. Claude drives: el consultor NUNCA toca la terminal.
+---
+
+# ContentForge — Content Command Center (Xmarts)
+
+Herramienta propia de Xmarts (repo privado `Bananoman/ContentForge`). Genera
+guiones con 27 fórmulas probadas, renderiza B-roll con Remotion, anima artículos
+(News Animator), hace fact-check con fuentes reales y narra con ElevenLabs
+(captions karaoke con timings exactos del engine). **Todo en modo suscripción
+Claude CLI — sin API keys de LLM.**
+
+## Regla #1 — Claude drives
+El consultor pide en lenguaje natural; TÚ ejecutas los comandos. Nunca le pidas
+correr nada en terminal.
+
+## Setup en máquina nueva (una vez, ~10 min)
+Prerrequisitos que TÚ verificas/instalas: Node 20+, pnpm, Docker (para el
+Postgres local), Claude Code CLI logueado.
+```bash
+git clone https://github.com/Bananoman/ContentForge.git ~/Development/ContentForge
+cd ~/Development/ContentForge && pnpm install && pnpm bootstrap   # idempotente
+pnpm doctor    # DEBE dar GREEN 8/8 antes de usar — si no, arregla lo que marque
+```
+Si el clone falla por acceso: el consultor necesita el grant del repo — pedirlo
+a Rubén/Daniela (1 min). El acceso es por-persona, igual que las demás
+herramientas de Genius.
+
+## Recetas (todas verificadas E2E)
+| El consultor pide… | Tú corres… |
+|---|---|
+| "Video de este artículo" (pipeline completo, resumible) | `pnpm cf pipeline --name X --source <url> --out out/x.mp4` |
+| Proyecto + ingesta de fuente | `pnpm cf new --name X --source <url>` |
+| Guion 60s con fórmulas | `pnpm cf generate <projectId> --length 60` |
+| **News Animator** (scroll+highlight+closeup de artículo) | `pnpm cf capture --url <articulo> --highlight "texto exacto" --image 0 --render out/x.mp4` |
+| Variantes de hook A/B | `pnpm cf hooks generate <versionId>` → `hooks pick` |
+| **Fact-check con fuentes reales** | `pnpm cf factcheck <versionId>` |
+| Revisión con feedback | `pnpm cf revise <versionId> --feedback "..."` |
+| Voz narrada + captions karaoke | lane TTS ElevenLabs (usa el skill `elevenlabs-voiceover`; timings verbatim del engine — commit 50e3478, e2e 13/13) |
+| Teleprompter (solo texto hablado, 0 cues) | `pnpm cf teleprompter <versionId>` |
+| Guardián de voz de marca | `pnpm cf voice-check <versionId>` |
+| Render de composición | `pnpm cf render --comp KineticQuote --props f.json --out x.mp4` |
+| **Dashboard visual** | `pnpm cf ui` → http://localhost:4577 (library/detail/formulas/runs) |
+| Inteligencia competitiva (velocity + trend radar, zero-key) | `cf intel add-channel/poll/trends` |
+| Costos de corridas (reales o NULL, nunca fabricados) | `pnpm cf runs` |
+
+## Flujo recomendado (calidad máxima)
+1. `cf new` con la fuente → 2. `cf generate` (fórmula sugerida) → 3. `cf hooks
+generate` + `hooks pick` (el hook decide la retención) → 4. `cf factcheck`
+(NUNCA publicar claims sin fuente) → 5. `cf revise` con feedback del consultor →
+6. voz con `elevenlabs-voiceover` → 7. `cf render`/`pipeline` → 8. preview
+aprobado ANTES del render final.
+
+## Reglas duras
+- `pnpm doctor` GREEN antes de cualquier sesión de trabajo.
+- Fact-check obligatorio antes de publicar (claims con receipts o fuera).
+- Los costos que reporta `cf runs` son reales o NULL — jamás inventar números.
+- Guía ilustrada completa: `docs/guide/index.html` del repo (paso a paso con
+  screenshots + registro E2E).
+- Combina con: `video-storytelling` (narrativa), `elevenlabs-voiceover` (voz),
+  `higgsfield-video` (motion generativo), NanoBanana2 (imágenes).

package/plugin/skills/elevenlabs-voiceover/SKILL.md

@@ -0,0 +1,85 @@
+---
+name: elevenlabs-voiceover
+description: Voz profesional con ElevenLabs para consultores Xmarts (la API key llega provisionada por Genius — NUNCA pedirla ni pegarla en el chat). USAR SIEMPRE que el usuario pida narración, voiceover, text-to-speech, TTS, doblaje, diseñar una voz, o audio para un video/demo/curso.
+---
+
+# ElevenLabs Voiceover — receta Xmarts (tier Creator)
+
+Comité creative-stack 2026-07-06 — todo verificado en docs oficiales + pipeline
+real en producción. Fuentes: `docs/audit/2026-07-06-creative-stack-research/seats/B-elevenlabs.md`.
+La key llega por Genius (MCP `elevenlabs` o env `ELEVENLABS_API_KEY`). Si falta:
+la máquina no convergió → cualquier turno + reiniciar sesión. NUNCA pedir la key.
+
+## 1. Ruteo de modelo (decisión #1)
+| Modelo | Cuándo | Límite/request |
+|---|---|---|
+| `eleven_v3` | Expresivo con audio tags, diálogos | 5,000 chars |
+| `eleven_multilingual_v2` | **Default narración es-MX/LATAM larga** | 10,000 chars |
+| `eleven_flash_v2_5` | Barato+rápido (0.5 cr/char); escribir NÚMEROS COMO PALABRAS (no normaliza) | 40,000 chars |
+| ~~`eleven_turbo_v2_5`~~ | ⛔ **MUERTO 2026-07-09** — migrar a flash_v2_5 | — |
+
+## 2. Prompting v3 (audio tags)
+- Tags = dirección de actuación entre corchetes: emoción (`[excited]` `[sarcastic]`
+  `[warmly]` `[professional]`), reacciones (`[laughs]` `[sighs]` `[clears throat]`),
+  delivery (`[whispers]` `[SHOUTING]` `[pause]` `[rushed]` `[drawn out]`),
+  acentos (`[strong French accent]`).
+- **Puntuación = prosodia**: elipsis `…` pausa con peso; MAYÚSCULAS = énfasis;
+  `¿? ¡!` ayudan la entonación en español. Ej oficial:
+  `"Fue un día MUY largo [sigh] … nadie escucha."`
+- Prompts **>250 chars** (cortos = inconsistentes). **NO existe SSML `<break>` en v3**
+  (solo en v2) — pausas con tags + puntuación.
+- Stability en v3 es discreto: Creative/Natural responden a tags; **Robust los mata**.
+- No contradecir la voz (voz calma + `[SHOUTING]` no funciona).
+- Generar 2-3 tomas y elegir; `seed` para reproducibilidad.
+
+## 3. Voice Design — plantilla oficial (crear voces por prompt)
+```
+Native <idioma + variante>. <Género>, <edad>. <Calidad de audio>.
+Persona: <2-5 palabras>. Emotion: <2-3 adjetivos>.
+<1-2 frases de timbre, ritmo y entrega>
+```
+Receta Xmarts narrador demo: *"Native Spanish, español latinoamericano neutro.
+Male, 30-40. Studio quality. Persona: narrador tecnológico confiable. Emotion:
+confident, warm, clear. Smooth timbre, relaxed pace, clear emphasis on key data."*
+- **Guidance scale**: 20-25% naturalidad · 30-35% balance (default Xmarts) ·
+  40%+ fidelidad al acento/carácter. Preview text 100-1000 chars acorde a la voz.
+- NUNCA "foreign accent" (vago) ni términos FX ("reverb","phone") — degradan.
+- Flujo API: `POST /v1/text-to-voice/design` → previews → persistir. Registrar
+  voice_ids del equipo en Genius.
+
+## 4. Settings por caso de uso (voice_settings)
+| Caso | stability | style | speed |
+|---|---|---|---|
+| **VO corporativo/demo (probado en producción)** | **0.55** | **0.2** | 1.0 |
+| Ad/hook enérgico (v3+tags) | Creative/Natural | — | — |
+| E-learning largo | 0.6-0.7 | 0.1 | 0.95-1.05 |
+Si suena robótico: alargar la escena/copy, NO tocar speed primero.
+
+## 5. Integración con video (Remotion) — el núcleo
+1. **`scenes.json` como contrato**: `{id, text, duration, character, delay}` →
+   genera `scene1..N.mp3` + `info.json` con duraciones reales.
+2. **Config central de timing** (única fuente de verdad) — duraciones hardcodeadas
+   en varios archivos rompen silencioso.
+3. **`previous_text`/`next_text`** en cada request (o `previous_request_ids` ≤3,
+   mismo modelo) → prosodia continua entre escenas.
+4. **Captions frame-perfect SIN Whisper**: `POST /v1/text-to-speech/{voice}/with-timestamps`
+   → alignment POR CARÁCTER (start/end seconds) → karaoke en Remotion.
+5. Audio por escena: `<Sequence from={Math.round(FPS * audioDelay)}>` dentro de
+   TransitionSeries (sin esto los VO se pisan en transiciones).
+6. Regenerar UNA escena, no todo (ahorra créditos en iteración).
+7. Música/SFX: `textToSoundEffects` (cuota separada), `loop:true`, volumen ≤0.12.
+8. Formato: **`mp3_44100_192`** (se desbloquea en Creator — usarlo siempre).
+   WAV/PCM requiere Pro: no prometer WAV master.
+9. Guion: escribir COMO SE HABLA; números y abreviaturas en palabras.
+10. Pronunciación de marcas: dictionary PLS con reglas **alias** ("Odoo"→"Oh-doo",
+    "Xmarts"→"Ex-marts") — phoneme IPA solo flash_v2/v3.
+
+## 6. Presupuesto Creator (121,000 créditos/mes ≈ 1 cr/char en v2)
+≈2h de narración premium/mes. Lo que come cuota es la ITERACIÓN → regeneración
+por-escena + `seed`. Voice changer: 1,000 chars/min de audio. Dubbing 90+ idiomas
+(watermark solo en free). Concurrencia 2-15: serializar renders batch.
+
+## Referencia clonada
+`~/Development/creative-stack/elevenlabs-examples` (oficial, MIT) y
+`elevenlabs-remotion-skill` (patrón scenes.json). MCP oficial opcional:
+`uvx elevenlabs-mcp` con `ELEVENLABS_MCP_BASE_PATH` al `public/audio/` del proyecto.

package/plugin/skills/genius-media-gen/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: genius-media-gen
+description: Generación de imágenes y voz/TTS para consultores Xmarts. USAR SIEMPRE que el usuario pida crear/generar/editar una imagen, icono, ilustración, visual, logo, banner (→ NanoBanana2) o audio, voz, narración, text-to-speech, TTS (→ ElevenLabs). Nunca preguntar qué modelo usar ni pedir API keys.
+---
+
+# Genius Media Gen — imágenes (NanoBanana2) y voz (ElevenLabs)
+
+## Regla de oro (no negociable)
+1. **NUNCA preguntes al usuario qué modelo usar.** El estándar Xmarts está decidido:
+   - **Imágenes → NanoBanana2** (= `gemini-3.1-flash-image-preview`, fijo).
+   - **Voz/TTS → ElevenLabs** (`eleven_multilingual_v2` por defecto para español).
+2. **NUNCA pidas al usuario que pegue una API key en el chat.** Las keys las
+   entrega Genius automáticamente (cifradas, por-consultor). Si falta una key,
+   el remedio es converger la máquina (abajo), no pedirla.
+
+## Imágenes — cómo ejecutar
+1. **Preferido**: tool MCP `generate_image` del server `nanobanana2`
+   (prompt, `filename?`, `aspect_ratio?` — guarda PNG y devuelve la ruta).
+   Para editar una imagen existente: `edit_image(image_path, prompt)`.
+2. Si `nanobanana2` no está en la sesión pero sí `pencil_design`:
+   `generate_slide_image` usa el MISMO motor (sirve para imágenes sueltas).
+3. Fallback REST (solo si no hay ningún MCP y SÍ hay `GEMINI_API_KEY` en env o
+   `~/.genius/secrets/gemini_api_key`):
+   `POST https://generativelanguage.googleapis.com/v1beta/models/gemini-3.1-flash-image-preview:generateContent`
+   con header `x-goog-api-key` y body
+   `{"contents":[{"parts":[{"text":"<prompt>"}]}],"generationConfig":{"responseModalities":["IMAGE"]}}`
+   → la imagen viene en `candidates[0].content.parts[].inlineData.data` (base64).
+
+## Voz / TTS — cómo ejecutar
+1. **Preferido**: tools del server MCP `elevenlabs` (text-to-speech).
+2. Fallback REST (si hay `ELEVENLABS_API_KEY` en env):
+   `POST https://api.elevenlabs.io/v1/text-to-speech/{voice_id}` con header
+   `xi-api-key`, body `{"text":"...","model_id":"eleven_multilingual_v2"}` → MP3.
+
+## Si la herramienta o la key NO están en esta máquina
+Significa que el equipo aún no convergió con Genius. Dile al usuario EXACTAMENTE esto:
+> "Tu acceso ya está aprovisionado en Genius. Da un turno cualquiera en Claude
+> Code (el hook de Genius actualiza tu configuración solo) y **reinicia la
+> sesión de Claude Code**. Al volver, la herramienta aparece con su key."
+
+Si tras converger sigue sin aparecer, el consultor no tiene el grant: pedir a un
+admin (Rubén/Daniela) que lo active en su ficha de Genius → pestaña MCP
+(server `nanobanana2` o `elevenlabs` → Grant + credencial). Es 1 minuto.
+
+## Anti-patrones
+- ❌ Preguntar "¿qué modelo quieres usar?" — el modelo es fijo.
+- ❌ Pedir/aceptar API keys pegadas en el chat (aunque el usuario se ofrezca).
+- ❌ Sugerir `setx`/`export` manual de keys — Genius las entrega solo.
+- ❌ Usar otro motor de imágenes "mientras tanto" sin decirlo.

package/plugin/skills/genius-operator/references/provision-consultant-ui-access.md

@@ -26,6 +26,7 @@ name + xmarts.com email first (from `get_my_profile`, or the consultant record o
 
 ```python
 U = env['res.users'].sudo()
+GF = 'group_ids' if 'group_ids' in U.fields_get([]) else 'groups_id'   # v19 vs v17/18 field
 NAME, LOGIN = '<Full Name>', '<person@xmarts.com>'   # the consultant who needs access
 env.cr.execute("SELECT replace(gen_random_uuid()::text, '-', '')")
 raw = env.cr.fetchone()[0]
@@ -47,12 +48,12 @@ else:
         lg = p.login or ''
         if lg == 'admin' or lg.startswith('xma_'):
             continue                                   # skip the admin + service accounts
-        if sysg and sysg.id in p.group_ids.ids:
+        if sysg and sysg.id in p[GF].ids:
             continue                                   # never clone an admin's groups
-        n = len(p.group_ids)
+        n = len(p[GF])
         if n > best:
             best = n; peer = p
-    gids = peer.group_ids.ids if peer else []
+    gids = peer[GF].ids if peer else []
     if not gids:
         base = env.ref('base.group_user', raise_if_not_found=False)
         sales = env.ref('sales_team.group_sale_salesman', raise_if_not_found=False)
@@ -61,7 +62,7 @@ else:
     user = U.with_context(no_reset_password=True, mail_create_nosubscribe=True).create({
         'name': NAME, 'login': LOGIN, 'email': LOGIN, 'password': pw,
         'company_id': comp, 'company_ids': [Command.set([comp])],
-        'group_ids': [Command.set(gids)]})
+        GF: [Command.set(gids)]})
     status = 'created'
 result = {'status': status, 'uid': user.id, 'login': user.login, 'password': pw,
           'url': env['ir.config_parameter'].sudo().get_param('web.base.url') + '/web/login'}
@@ -80,6 +81,15 @@ Only assigned clients are reachable (`target_client` refuses unassigned). If the
 their assignments, tell them to ask an admin to assign it — that is the only gate. Nothing else
 about this should require a human hop.
 
+**If the `execute_orm` call itself errors** *before* your snippet runs — e.g. `"Client X has no
+API key configured"`, a not-reachable / timeout, or you can see `connectivity_mode: unknown` /
+`heartbeat_count: 0` on the `xma.client` record — the client is **registered but not gateway-
+connected** (the `xma_connect` agent was never activated on it). You cannot provision a UI user
+there. Tell the consultant plainly: *"\<client\> isn't connected to Genius yet — an admin needs to
+deploy xma_connect on it before UI access can be granted"* — do NOT surface the raw error or retry.
+(Confirmed 2026-07-01: PACKLIFE is `active` in the registry but has no gateway URL and 0 heartbeats,
+so `target_client="PACKLIFE"` is unreachable; Elevatrix and Edenred are connected and work.)
+
 ## The pattern (scalable, sustainable, auditable)
 
 **Per-consultant internal user in the client instance, provisioned on demand through the

package/plugin/skills/higgsfield-video/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: higgsfield-video
+description: Video generativo con Higgsfield (motion real, presets de cámara, avatares) para consultores Xmarts. USAR cuando el usuario pida video con IA generativa, motion cinematográfico, animar una imagen, avatar hablando, o mencione Higgsfield/Kling/Veo/Sora. Si es animación de datos/branding → remotion-video; si es solo imagen → NanoBanana2.
+---
+
+# Higgsfield Video — receta Xmarts
+
+Comité creative-stack 2026-07-06 (fuentes verificadas en
+`docs/audit/2026-07-06-creative-stack-research/seats/C-higgsfield.md`).
+Higgsfield = AGREGADOR multi-modelo (Sora 2, Veo 3.1, Kling 3.0, Seedance 2.0,
+Wan 2.6…) + su capa diferencial: **50+ presets de cámara**.
+
+## 1. Setup (Claude drives)
+```bash
+npm install -g @higgsfield/cli && higgsfield auth login   # browser, 5 seg
+```
+⛔ NUNCA `curl | sh` del CLI. MCP oficial (`https://mcp.higgsfield.ai/mcp`, OAuth)
+solo para exploración — a volumen, el manifest come tokens cada turno; el CLI es
+el camino de producción. Skills oficiales: `npx skills add higgsfield-ai/skills`
+(auditar antes de global — su setup trae scripts shell).
+```bash
+higgsfield generate create kling3_0 --prompt "..." --wait
+```
+
+## 2. Ruteo por COSTO (regla dura — los créditos expiran)
+| Necesidad | Modelo | Costo aprox |
+|---|---|---|
+| **Default: establecimiento, b-roll, iteración** | **Kling 3.0** | ~6 cr/clip |
+| Hero shot de campaña (solo el final) | Veo 3.1 | 40-70 cr |
+| Multi-shot con audio nativo | Seedance 2.0 (plan Plus) | ~90 cr/15s |
+| **Keyframes/imágenes** | ⛔ NUNCA en Higgsfield → **NanoBanana2 propio (gratis)** | 0 |
+| **Voz** | ⛔ NUNCA text2speech de Higgsfield → **ElevenLabs propio** | 0 |
+
+Iterar en Kling, finalizar en premium. Borradores NUNCA en 4K.
+
+## 3. Prompt frameworks (el oro)
+- **MCSLA** — Model · Camera · Subject · Look · Action:
+  `Kling 3.0 · FPV Drone weaving · [sujeto específico] · Cinematic cold blue · [acción]`.
+- **Seedance shot-structure-first**: declarar ARRIBA "`6 shots, 15 seconds, 16:9`" +
+  base cinematográfica ("35mm film quality", "film grain") + decir qué hace Y qué
+  NO hace la cámara ("no cuts, no zoom") + beats numerados + VFX inline `[VFX: ...]`.
+- **Soul tag** (personaje consistente): `"Soul: 28yo [complexión] [género]"` +
+  3-5 rasgos faciales + estilo + pose. **75-100 palabras.**
+- **Referencias**: `"Use Image 1 as reference for the character, Image 2 for the
+  location"`, `"continuing @video1"` (Cinema Studio).
+- **UN solo movimiento de cámara dominante por clip** — nunca 3 a la vez.
+- **Preset en vez de prosa**: usar el preset, no describir el movimiento.
+
+## 4. Presets de cámara → casos B2B
+| Preset | Uso Xmarts |
+|---|---|
+| **360 Orbit / Lazy Susan** | Héroe de producto |
+| **FPV Drone** | Recorridos de planta/bodega/oficina |
+| **Crash Zoom In** | Hooks de shorts (énfasis KPI/logo) |
+| **Dolly In / Super Dolly** | Reveal de producto, walkthrough |
+| **Crane Up/Down** | Apertura/cierre corporativo |
+| **Timelapse (Human/Landscape)** | "Antes/después" de implementación |
+| **Through Object / Flying Cam** | Transiciones entre secciones de explainer |
+| **Dolly Zoom (vértigo)** | Momento "problema descubierto" |
+
+## 5. Prompts verbatim (comunidad, verificados)
+- Producto: *"Premium product ad of [PRODUCT] floating and slowly rotating against
+  a seamless gradient backdrop"*
+- Hero: *"Smooth orbital camera circling 360 degrees around [SUBJECT] in a
+  low-angle hero pose"*
+- Hook vertical: *"Vertical 9:16 POV clip of [SUBJECT] speaking directly to camera
+  with an energetic crash-zoom-in on the first word"*
+- Animar imagen NB2: *"Animate [IMAGE] with subtle lifelike motion: gentle
+  breathing, slow blink, soft hair movement"*
+- Logo reveal: *"Create an elegant dynamic logo reveal animation for the logo in
+  Image 1... Liquid Glass aesthetic"*
+
+## 6. Pipeline E2E Xmarts (mapeo 1:1 con nuestro stack)
+```
+Guion + shot list   → skill video-storytelling (gate humano en storyboard JSON)
+Keyframes           → NanoBanana2 (propio, gratis) o Soul ID (personaje consistente)
+Video motion        → Higgsfield CLI + preset de cámara (Kling default)
+Avatar hablando     → Lipsync Studio (imagen + audio ElevenLabs es-MX propio)
+Voz off             → skill elevenlabs-voiceover
+Ensamblaje/branding → Remotion (intro/outro, KPIs animados, subtítulos, tema cliente)
+```
+
+## 7. Guardrails de créditos (letra chica verificada)
+- Créditos mensuales NO acumulables; packs de recarga **expiran a los 90 días**;
+  cancelar = perder todo. NO stockpilear.
+- "Unlimited" solo aplica a Soul V2 e imágenes — Sora/Veo NUNCA son gratis.
+- Colas de 4-12 min en horas pico (18:00-23:00 UTC) — planear renders.
+- Presupuestar por proyecto y registrar consumo por cliente.
+
+## Anti-patterns
+❌ Describir cámara en prosa teniendo presets · ❌ 3 movimientos por clip ·
+❌ TTS de Higgsfield teniendo ElevenLabs · ❌ keyframes en Higgsfield teniendo
+NanoBanana2 · ❌ borradores en 4K · ❌ confiar en "unlimited" · ❌ `curl | sh`.
+
+## Referencia clonada
+`~/Development/creative-stack/higgsfield-ai-prompt-skill` (MCSLA completo, 17
+templates) y `higgsfield-skills` (5 skills oficiales del vendor).

package/plugin/skills/video-storytelling/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: video-storytelling
+description: Guion, storyboard y storytelling para videos de consultores Xmarts (demos, explainers, recaps, social) con Remotion. USAR SIEMPRE que el usuario pida crear un video, guion de video, storyboard, script para demo/explainer/short, o mejorar la narrativa de un video. Complementa remotion-video (el motor) con la CAPA NARRATIVA.
+---
+
+# Video Storytelling — de idea a storyboard aprobado (Xmarts)
+
+Comité creative-stack 2026-07-06. Evidencia y fuentes: repo XmartsGenius
+`docs/audit/2026-07-06-creative-stack-research/`. Repos de referencia clonados
+en `~/Development/creative-stack/` (máquina del owner) o clonables al vuelo.
+
+## Flujo obligatorio (5 pasos, con gate humano)
+
+### 1. Brief — 5 preguntas antes de escribir nada
+Objetivo (demo/recap/explainer/social) · audiencia · duración target ·
+plataforma + aspect ratio · UNA sola CTA.
+
+### 2. Guion — plantilla Hook→Value→Proof→CTA
+- **Hook completo en ≤2.5s** (el viewer decide en <2s). 4 fórmulas probadas:
+  1. *Pattern Interrupt*: contradicción ("Gané más cuando dejé de publicar diario")
+  2. *Direct Promise* con número ("Domina X en 30 segundos")
+  3. *Question Hook* específico ("¿Por qué tus demos mueren al 40%?")
+  4. *Self-Identifying* ("¿Implementas Odoo y sientes que N?")
+- **Regla madre: diseñar para MUDO** — 60% del short-form se ve sin sonido; el
+  hook y cada beat deben funcionar solo con texto on-screen.
+- **Estructura de retención** (patrón MrBeast comprimido a 60-90s B2B):
+  0-3s promesa con dato → 3-15s progreso VISIBLE del demo → ~50% re-engagement
+  (cifra/giro) → payoff → CTA en los últimos 3-5s. La promesa del thumbnail/hook
+  se CUMPLE en el primer tramo, no al final.
+- Copy como UNA persona pensando en voz alta, no seis titulares sueltos —
+  conectores entre cortes ("Pero la mayoría…", "Con X…", "Así que…").
+
+### 3. Storyboard-as-JSON — GATE HUMANO obligatorio
+El video es DATA antes que código. Generar este schema y obtener aprobación
+del consultor ANTES de codear (patrón contact-sheet de OpenMontage — la
+versión video del "snapshot pre-cambio"):
+```json
+{
+  "meta": {"fps": 30, "width": 1920, "height": 1080, "durationInFrames": 2700},
+  "scenes": [{
+    "id": "s1", "beat": "hook", "durationInFrames": 90,
+    "visual": "pantalla Odoo con KPI subiendo",
+    "onScreenText": "3 días. No 3 meses.",
+    "voiceover": "¿Y si tu cierre contable tomara tres días?",
+    "dataBindings": [], "transition": {"type": "fade", "timing": "spring"}
+  }],
+  "audio": {"music": "mixkit-<id> (licencia registrada)", "sfx": [], "vo": "elevenlabs"}
+}
+```
+
+### 4. Voz — delegar al skill `elevenlabs-voiceover`
+Normalizar números/abreviaturas a palabras; guardar timestamps para captions.
+
+### 5. Build Remotion — reglas de motion premium
+- Instalar los skills oficiales del vendor: `npx skills add remotion-dev/skills`.
+- `spring({frame, fps, config:{damping: 200}})` para entradas SIN rebote
+  (el default damping:10 rebota = look juguetón, no B2B).
+- Escenas encadenadas SIEMPRE con `<TransitionSeries>` + springTiming/linearTiming.
+- Captions palabra-a-palabra estilo template-tiktok (word-level, para mudo).
+- Videos data-driven (recap por cliente desde Odoo): patrón github-unwrapped
+  (datos → props → composición).
+- Catálogo de 81 escenas listas: `reactvideoeditor/remotion-templates` (MIT).
+- Pipeline guion→imágenes→voz→timeline completo de referencia:
+  `remotion-dev/template-prompt-to-video` (swap imágenes a NanoBanana2).
+
+## Assets (licencia o no se usa)
+- Música/SFX: **Mixkit** (mixkit.co — Free License por categoría, verificar
+  "View License") o **Pixabay Audio** (descarga manual). Registrar licencia
+  POR ASSET en el proyecto.
+- 🪦 **FreePD murió en 2025** — NO recomendarlo jamás.
+- Fuentes: `@remotion/google-fonts` (licencias claras dentro del ecosistema).
+- Volumen de música de fondo ≤0.12 con fade-in/out — nunca pisar el VO.
+
+## Reglas duras
+1. Hook completo ≤2.5s. 2. Diseñar para mudo. 3. Gate humano en el storyboard
+JSON — nunca codear sin aprobación. 4. Nunca render final sin preview aprobado.
+5. Licencia registrada por asset. 6. Branding/tema del cliente (OKLCH, nunca
+hex hardcodeado — Brain #245). 7. Anti-AI-slop (#5668): si parece plantilla
+genérica de IA, rehacer.