diff --git a/scripts/yupana.py b/scripts/yupana.py
index 6261cfba..5804477e 100755
--- a/scripts/yupana.py
+++ b/scripts/yupana.py
@@ -42,9 +42,31 @@
 #   triaje            clasificar la frontera            → triaje.py
 #   drenar [--perfil] el orden de masticado, en ondas   → drenar.py
 #
-# Uso:  scripts/yupana.py radio <receta> [--json]
-#       scripts/yupana.py estado [--kde] | drenar [--todos] | triaje | frontera <perfil> | objetivo
-# Como módulo:  from yupana import cargar_colas, membresia, dependientes, resolver
+# La ayuda operativa vive en el DOCSTRING de abajo y no en estos comentarios, por una razón medida:
+# `main()` hace `print(__doc__)` para `--help` y para un verbo desconocido, y mientras todo el
+# encabezado fue `#` eso imprimía literalmente `None`. La puerta única de la metodología no sabía
+# explicarse, y el error de verbo desconocido tampoco decía cuáles son los verbos. El diseño y el
+# porqué se quedan arriba como comentario; lo que un humano necesita para USARLO va en el docstring.
+"""yupana — el ábaco del build: reckona sobre el khipu (docs/state/build-state.json).
+
+Verbos, en el orden del ciclo:
+
+  radio <receta> [--json]   ¿a QUIÉN rompo si toco esto? cruza TODAS las colas ← ANTES de cambiar nada
+  perfiles <receta>         ¿qué imágenes dependen de esto?
+  duplicados [--json]       el mismo paquete bajo dos nombres (por sha)
+  keystones [--json]        nudos en deuda que gatean el máximo trabajo bloqueado
+  preflight <receta>        ¿choca con un límite del entorno que el grafo no ve?
+  estado [--kde|--gnome|--cosmic|--wlr]   regenera el grafo firme
+  objetivo                  qué debe tener cada imagen
+  frontera <perfil>         qué pide upstream y no tenemos
+  triaje                    clasificar la frontera
+  sembrar <perfil>          sembrar las recetas que la frontera reveló
+  drenar [--todos|--perfil <p>]           el orden de masticado, en ondas
+
+Uso:  scripts/yupana.py radio <receta> [--json]
+      scripts/yupana.py estado [--kde] | drenar [--todos] | triaje | frontera <perfil> | objetivo
+Como módulo:  from yupana import cargar_colas, membresia, dependientes, resolver
+"""
 import glob, json, os, re, subprocess, sys, tomllib
 from pathlib import Path