yem-hjk6th/explainer-kit

Video explicativo

Creas videos explicativos que un espectador específico entiende y que son correctos. Dos cosas determinan el resultado: las reglas en references/STYLE.md (provienen de comentarios reales de revisores) y el hábito de calcular y verificar cada número que muestras. El renderizado es la parte fácil.

Mapa del repositorio: biblioteca animkit/ (referencia de API animkit/README.md), herramientas tools/, ejemplos examples/, dos episodios terminados episodes_example/ (copia sus formatos de storyboard y planos; el formato de AFIRMACIONES está en references/VERIFY.md), tu trabajo va en episodes/<ID>_<topic>/.

0. Antes de todo

1. ¿El entorno funciona? python -I -B -X utf8 tools/selftest.py debe imprimir all OK. Si falta config/animkit.json, ejecuta python -X utf8 tools/setup_config.py (la configuración es por checkout: un clon nuevo o git worktree la necesita de nuevo, o establece ANIMKIT_CONFIG). Problemas: SETUP.md.
2. Pregunta al usuario solo lo que no puedas predeterminar (un mensaje, breve):
   • tema y el material fuente (apuntes de clase, un artículo, una página); necesitas una fuente para cada afirmación;
   • audiencia y lo que ya saben (define la profundidad, references/STORYBOARD.md §Audiencia);
   • duración; ¿versión traducida / narración / locución deseada?
   • ¿puedes ejecutar modelos reales (GPU, descargas)? Valor predeterminado: no, usa una escena sintética con verdad fundamental conocida.
   • Valores predeterminados si no se responden: 1080×1440, 30 fps, solo subtítulos, sin voz, una ronda de revisión planificada.
3. Crea episodes/<ID>_<topic>/ con STATUS.md (etapa / siguiente paso / esperando / tiempo desde date).

1. El flujo de trabajo (detalles y comandos: references/PIPELINE.md)

Etapa	Tú produces	Puerta antes de la siguiente etapa
A. Estudio	resumen de la fuente; desglose opcional de video de referencia (references/REFERENCES.md)	puedes enunciar el mecanismo como entrada → fórmula → formas → pequeño ejemplo numérico → por qué
B. Storyboard	storyboard.md, AFIRMACIONES_a_verificar.md, episode.json (+ elements_needed.md si falta algo en la biblioteca)	usuario OK en el esquema para episodios largos; ronda de verificación independiente 1 realizada y correcciones aplicadas (references/VERIFY.md)
C. Planos	shots/sNN_*.py, cada uno con @shot.check	--check-only pasa; hoja de contactos inspeccionada; render completo; advertencias de check.json corregidas
D. Ensamblar	render/<ID>.mp4 (tools/concat.py), review/round1/review.html (tools/review_page.py)	has visto las hojas de cada plano; números en pantalla = AFIRMACIONES
E. Rondas de revisión	review/roundN/feedback.md (notas del usuario), review/roundN+1/changes.md, re-renders	cada elemento de feedback respondido; nuevas afirmaciones verificadas (máx. 2 rondas por elemento)
F. Opcional	versión traducida (references/I18N.md), narración (references/NARRATION.md), locución (references/TTS.md)	cada una tiene su propia verificación

Escribe los planos directamente en el idioma del video (inglés en los ejemplos): los subtítulos, títulos y etiquetas son cadenas de texto simples en el script. --lang es solo para una segunda versión traducida.

Micro ruta (≤ 60 s, 1–3 planos). Mismas etapas, más ligeras. Lista de archivos mínima en episodes/<ID>_<topic>/:

1. storyboard.md: una tabla, una fila por subtítulo (rango de tiempo, subtítulo, qué cambia en pantalla, computado o ilustrativo). Esqueleto: templates/storyboard_skeleton.md.
2. AFIRMACIONES_a_verificar.md: una fila por número / hecho en pantalla (afirmación, fuente, cómo verificar, medido / computado / inferido / artículo).
3. shots/s01_<name>.py a partir de templates/shot_template.py, con un @shot.check que afirma cada número computado como la cadena mostrada.
4. Verificación: un subagente nuevo con templates/verifier_prompt.md limitado a todas las filas de AFIRMACIONES; aplica sus correcciones (redacción antigua tachada).
5. Render: --check-only → --sheet-only (mira sheet.jpg) → render completo.
6. episode.json + tools/concat.py solo si hay 2+ planos; tools/review_page.py <EP> --round 1 para la página de revisión (una ronda). No omitas la tabla de afirmaciones, el @shot.check o la inspección de la hoja de contactos.

2. Reglas que nunca son opcionales

• Cada elemento visual computable se computa (proyecciones, pesos de atención, remodelaciones, retroproyecciones, líneas ajustadas) y se afirma en @shot.check, incluyendo la cadena mostrada: ck.eq("profundidad en pantalla", f"{z:.3f}", "1.976"). Formato desde precisión completa; nunca vuelvas a redondear un valor impreso. Los elementos visuales ilustrativos obtienen shot.tag("Illustration"); los dibujos con dimensiones reducidas lo indican.
• Cada número tiene una fuente (artículo § / tabla / ecuación, archivo de código oficial + línea, o nuestro propio script) en AFIRMACIONES_a_verificar.md, etiquetado como medido / computado / inferido / artículo. Las comparaciones indican métrica, unidad y si un valor más bajo o más alto es mejor; los porcentajes indican su denominador.
• Cada símbolo se define donde aparece, cada vez; los términos que el espectador podría no conocer reciben una ventana emergente lateral (animkit.Popup) que los explica brevemente y se cierra.
• Un subtítulo = un cambio visual, ≤ 12 palabras y no más ancho que el fotograma (el render advierte; a 42 px eso suele ser ~8 palabras largas por línea, máximo 2 líneas), 2–3 s cada uno, nada estático.
• Primero la imagen, luego la fórmula, iluminada término por término, cada término coloreado o vinculado a su parte de la imagen.
• Nuestras propias pruebas se etiquetan como nuestras (no el experimento del artículo) la primera vez y con la misma etiqueta después.
• Verificación independiente: quien escribe una afirmación no la verifica; una corrección es una nueva afirmación; como máximo dos rondas, luego aplica tal como está redactado y verifica puntualmente. La redacción antigua se tacha (~~antiguo~~ → nuevo), nunca se elimina en silencio.
• Sin hechos inventados en la traducción o narración: solo pueden decir lo que dicen los subtítulos / AFIRMACIONES verificados.
• Lista de verificación completa: references/STYLE.md (§A contenido, §B ritmo, §C gramática visual, §D pre-entrega, §E comentarios de revisores que se convirtieron en reglas). Léelo antes de escribir el storyboard y nuevamente antes de cada ronda de revisión.

3. Estilo de trabajo

• Lee la sección de API que necesites en animkit/README.md (es larga: busca con grep el elemento, luego lee esa parte). Copia patrones del plano más cercano en episodes_example/ en lugar de inventar diseños. templates/shot_template.py es un plano completo mínimo.
• Itera sobre un plano con --still t1 t2 (fotogramas PNG) y --sheet-only (hoja de contactos de 12 fotogramas); los renders completos al final. Mira la hoja tú mismo cada vez (superposiciones, texto fuera del lienzo, cuadros = glifos faltantes, subtítulos sobre la imagen). Los fotogramas fijos no se actualizan con renders posteriores: vuelve a ejecutar --still después de cada edición.
• Escenas 3D: animkit/README.md §Escenas 3D (PinholeCam, OrbitCam convención az / el: az=90, el=0 es una vista lateral). Diagramas 2D como una vista lateral de un agujero estenopeico: §Vista lateral 2D (Plot2D con escala uniforme).
• Ejecuta Python como python -I -B -X utf8; nunca edites archivos de la biblioteca mientras otra sesión renderiza (references/PITFALLS.md).
• Mantén STATUS.md breve y actualizado; registra el esfuerzo en effort_log.csv (elemento, tamaño, inicio, fin, s_render, iteraciones, nota).
• Episodios largos o muchos planos: divide el trabajo en sesiones / subagentes como en references/DISPATCH.md (presupuesto de contexto ≈ 300k por sesión principal, ≤ 150k por subagente de un solo uso, archivo de traspaso antes de cambiar).

4. Entrega

Informa al usuario: la ruta del video, la ruta de la página de revisión (review/roundN/review.html, ábrela en un navegador; tiene un cuadro de comentarios por plano y un botón "copiar todo"), qué es computado vs. ilustrativo, qué se verificó y por quién, preguntas abiertas. Cuando lleguen sus notas, guárdalas textualmente como review/roundN/feedback.md (una línea por id de plano, ej. E03-02: ...), responde a cada una y convierte cualquier preferencia general en una nueva línea en tus reglas locales del episodio (añade a un STYLE_local.md en episodes/), para que el próximo episodio comience con ella.

Índice de referencias

Archivo	Léelo cuando
references/PIPELINE.md	al comenzar; comandos de etapa, formatos de archivo, puertas
references/STYLE.md	al escribir el storyboard; antes de cada ronda de revisión
references/STORYBOARD.md	etapa B: profundidad de la audiencia, formatos de storyboard + AFIRMACIONES, patrones de historia
references/REFERENCES.md	al estudiar videos de referencia / artículos fuente
references/VERIFY.md + templates/verifier_prompt.md	después de AFIRMACIONES, después de ejecuciones de modelo, después de narración / traducción
references/REVIEW.md	etapa D–E: página de revisión, archivo de feedback, rondas
references/I18N.md	una versión traducida de un episodio en inglés (--lang)
references/NARRATION.md	guion hablado por segmento visual
references/TTS.md	locución TTS local, sincronización, mezcla
references/DISPATCH.md	trabajo multisensión / subagente, costo, etiqueta de máquina compartida
references/PITFALLS.md	algo se rompe; antes de cambiar la biblioteca
templates/	indicaciones para sesiones y subagentes, archivos esqueleto, una plantilla de plano