supcoflow 0.7.0 → 0.8.1

package/dist/comandos/describir.js

@@ -1,19 +1,19 @@
-// `supcoflow describir --json`: el contrato entero en una línea (§13), para que un asistente sepa
+// `supcoflow describe --json`: el contrato entero en una línea (§13), para que un asistente sepa
 // qué comandos hay, con qué flags, qué puede la clave y qué quiere decir cada código, sin leer la
 // ayuda pensada para personas. La ayuda se arma desde acá: una sola fuente, así no se desfasan.
 import { SALIDA } from "../contrato.js";
 // A mano a propósito, como en api.ts: tiene que coincidir con package.json (lo pinza un test).
-const VERSION = "0.7.0";
+const VERSION = "0.8.1";
 export const DESCRIPCION = {
     version: VERSION,
     comandos: [
         {
             nombre: "login",
-            resumen: "Inicia sesión aprobando un código desde la consola. Sin terminal interactiva, en dos pasos: --start y después --wait.",
+            resumen: "Signs in by approving a code from the console. Without an interactive terminal, in two steps: --start and then --wait.",
             flags: [
-                "--start: pide el código y sale 5 con la URL para aprobarlo",
-                "--wait: espera la aprobación hasta 90 s; sale 5 si todavía no llegó (volvé a llamarlo)",
-                "--dry-run: dice qué haría sin pedir nada (no vale con --wait)",
+                "--start: asks for the code and exits 5 with the URL to approve it",
+                "--wait: waits for the approval up to 90 s; exits 5 if it hasn't arrived yet (call it again)",
+                "--dry-run: says what it would do without asking for anything (not valid with --wait)",
                 "--json",
             ],
             ejemplos: ["supcoflow login", "supcoflow login --start --json", "supcoflow login --wait --json"],
@@ -21,270 +21,280 @@ export const DESCRIPCION = {
         },
         {
             nombre: "logout",
-            resumen: "Revoca la clave en uso y la borra de esta máquina; reintenta las que quedaron por revocar.",
-            flags: ["--dry-run: dice qué revocaría sin revocar nada", "--json"],
+            resumen: "Revokes the key in use and deletes it from this machine; retries the ones left to revoke.",
+            flags: ["--dry-run: says what it would revoke without revoking anything", "--json"],
             ejemplos: ["supcoflow logout", "supcoflow logout --json"],
             codigos: [0, 1, 3],
         },
         {
-            nombre: "quien-soy",
-            resumen: "Muestra con qué clave anda la terminal, a nombre de quién y en qué equipo.",
+            nombre: "whoami",
+            resumen: "Shows which key the terminal runs with, on whose behalf and in which team.",
             flags: ["--json"],
-            ejemplos: ["supcoflow quien-soy", "supcoflow quien-soy --json"],
+            ejemplos: ["supcoflow whoami", "supcoflow whoami --json"],
             codigos: [0, 1, 2, 3],
         },
         {
-            nombre: "describir",
-            resumen: "Describe comandos, flags, facultades y códigos de salida, para un asistente.",
+            nombre: "describe",
+            resumen: "Describes commands, flags, capabilities and exit codes, for an assistant.",
             flags: ["--json"],
-            ejemplos: ["supcoflow describir --json"],
+            ejemplos: ["supcoflow describe --json"],
             codigos: [0],
         },
         {
-            nombre: "repo conectar",
-            resumen: "Conecta el repo de esta carpeta (o el de --repo) con la App de GitHub: una persona lo confirma en la consola. Sin terminal interactiva, en dos pasos: --start y después --wait.",
+            nombre: "repo connect",
+            resumen: "Connects this folder's repo (or --repo's) with the GitHub App: a person confirms it in the console. Without an interactive terminal, in two steps: --start and then --wait.",
             flags: [
-                "--start: pide la conexión y sale 5 con la URL para confirmarla",
-                "--wait: espera la confirmación hasta 90 s; sale 5 si todavía no llegó (volvé a llamarlo)",
-                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta",
-                "--dry-run: dice qué pediría sin pedir nada (--wait sólo lee)",
+                "--start: requests the connection and exits 5 with the URL to confirm it",
+                "--wait: waits for the confirmation up to 90 s; exits 5 if it hasn't arrived yet (call it again)",
+                "--repo owner/repo: the repo, if it isn't this folder's «origin»",
+                "--dry-run: says what it would request without requesting anything (--wait only reads)",
                 "--json",
             ],
-            ejemplos: ["supcoflow repo conectar", "supcoflow repo conectar --start --json", "supcoflow repo conectar --wait --json"],
+            ejemplos: ["supcoflow repo connect", "supcoflow repo connect --start --json", "supcoflow repo connect --wait --json"],
             codigos: [0, 1, 2, 3, 4, 5],
         },
         {
-            nombre: "proyecto crear",
-            resumen: "Crea (o reusa) el proyecto del repo ya conectado y lo anota en .supcoflow/proyecto.json; un archivo distinto nunca se pisa (sale 4).",
+            nombre: "project create",
+            resumen: "Creates (or reuses) the already connected repo's project and records it in .supcoflow/proyecto.json; a different existing file is never overwritten (exits 4). Before connecting or creating anything it checks what it can see and exits 4 contexto_incoherente (motivo proyecto_del_clon_distinto: the clone notes a project your account doesn't see for this repo; archivo_del_clon_ilegible: .supcoflow/proyecto.json can't be read; dueno_distinto_del_login: a possible mismatch, the repo's owner on GitHub isn't the GitHub login of your key; sin_github: the account isn't signed in with GitHub) without touching anything.",
             flags: [
-                "--install \"…\": el comando de instalación, cuando el motor no lo puede deducir",
-                "--test \"…\": el comando de pruebas, ídem",
-                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta (sin escribir el archivo)",
-                "--dry-run: dice qué crearía sin crear nada",
+                "--install \"…\": the install command, when the engine can't work it out",
+                "--test \"…\": the test command, same",
+                "--repo owner/repo: the repo, if it isn't this folder's «origin» (without reading or writing this clone's file)",
+                "--dry-run: says what it would create without creating anything",
                 "--json",
             ],
-            ejemplos: ["supcoflow proyecto crear --json", "supcoflow proyecto crear --install \"pnpm i\" --test \"pnpm test\""],
+            ejemplos: ["supcoflow project create --json", "supcoflow project create --install \"pnpm i\" --test \"pnpm test\""],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "proyecto ver",
-            resumen: "Muestra el proyecto del repo: rama, comandos y el estado de la App de GitHub; null si todavía no tiene.",
-            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--json"],
-            ejemplos: ["supcoflow proyecto ver --json"],
-            codigos: [0, 1, 2, 3],
+            nombre: "project show",
+            resumen: "Shows the repo's project: branch, commands and the GitHub App's state; null if it has none yet. It starts with who you are: `contexto` { equipo, identidad (the GitHub login, or «email», or «clave_de_consulta»), identidad_tipo, fuente, repo, proyecto (id or null), en_el_clon { estado: ausente|valido|ilegible, id } }, said as «You're @login in team T; repo O/R; project P (existing)». Exits 4 contexto_incoherente if this clone's .supcoflow/proyecto.json doesn't match what your key sees (proyecto_del_clon_distinto / archivo_del_clon_ilegible) or, when the repo has no project yet, if the account can't create one for it (dueno_distinto_del_login, a possible mismatch / sin_github): it stops BEFORE `repo connect`. The repo comes from the «origin» of this clone; if origin is an SSH alias or not GitHub, from a remote called `supcoflow` that points at https://github.com/owner/repo.git (the first time, `git remote add supcoflow https://github.com/owner/repo.git`: it is never fetched and ssh is never run).",
+            flags: ["--repo owner/repo: the repo, if it isn't this folder's «origin»", "--json"],
+            ejemplos: ["supcoflow project show --json"],
+            codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "catalogo",
-            resumen: "Lista lo que se puede configurar en el chat (claves y valores admitidos) y el estado del contrato de la App.",
+            nombre: "catalog",
+            resumen: "Lists what can be configured in the chat (keys and accepted values) and the state of the App's contract.",
             flags: ["--json"],
-            ejemplos: ["supcoflow catalogo --json"],
+            ejemplos: ["supcoflow catalog --json"],
             codigos: [0, 1, 2, 3],
         },
         {
-            nombre: "configuracion",
-            resumen: "Muestra la configuración del proyecto del repo: chat, sitios, marca, política de problemas y acuerdo de datos. El acuerdo frena lo que se guarda y lo que lee la IA que releva; no cubre lo que ve la IA del chat mientras conversa.",
-            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--json"],
-            ejemplos: ["supcoflow configuracion --json"],
+            nombre: "config",
+            resumen: "Shows the repo's project configuration: chat, sites, brand, problem policy and data agreement. The agreement limits what is saved and what the investigating AI reads; it doesn't cover what the chat's AI sees while it talks. Like every command that acts on the repo's project, it exits 4 contexto_incoherente without doing anything if this clone's .supcoflow/proyecto.json notes another project than the one your key sees (proyecto_del_clon_distinto) or can't be read (archivo_del_clon_ilegible).",
+            flags: ["--repo owner/repo: the repo, if it isn't this folder's «origin»", "--json"],
+            ejemplos: ["supcoflow config --json"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "chat prender",
-            resumen: "Prende el chat de soporte del proyecto. Hace falta una guía vigente (la publicada del repo o la aprobada de nuestro agente); si no, sale 4 (skill_no_aprobada).",
-            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
-            ejemplos: ["supcoflow chat prender --json"],
+            nombre: "chat on",
+            resumen: "Turns the project's support chat on. A current guide is needed (the repo's published one or our agent's approved one); otherwise it exits 4 (skill_no_aprobada).",
+            flags: ["--repo owner/repo: the repo, if it isn't this folder's «origin»", "--dry-run: says what it would do without doing it", "--json"],
+            ejemplos: ["supcoflow chat on --json"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "chat apagar",
-            resumen: "Apaga el chat de soporte del proyecto.",
-            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
-            ejemplos: ["supcoflow chat apagar --json"],
+            nombre: "chat off",
+            resumen: "Turns the project's support chat off.",
+            flags: ["--repo owner/repo: the repo, if it isn't this folder's «origin»", "--dry-run: says what it would do without doing it", "--json"],
+            ejemplos: ["supcoflow chat off --json"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "chat marca",
-            resumen: "Cambia título, saludo y colores del chat; lo que no nombrás queda como estaba.",
+            nombre: "chat brand",
+            resumen: "Changes the chat's title, greeting and colors; whatever you don't name stays as it was.",
             flags: [
-                "--titulo \"…\": el título del chat",
-                "--saludo \"…\": el saludo inicial",
-                "--tema clave=valor: un color o ajuste del tema (se repite, uno por clave)",
-                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta",
-                "--dry-run: dice qué haría sin hacerlo",
+                "--title \"…\": the chat's title",
+                "--greeting \"…\": the opening greeting",
+                "--theme key=value: a color or theme setting (repeatable, one per key); the keys are the API's: acento, fondo, texto, textoSuave, radio, fuente",
+                "--repo owner/repo: the repo, if it isn't this folder's «origin»",
+                "--dry-run: says what it would do without doing it",
                 "--json",
             ],
-            ejemplos: ["supcoflow chat marca --titulo \"Ayuda\" --tema acento=#0a7"],
+            ejemplos: ["supcoflow chat brand --title \"Help\" --theme acento=#0a7"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
             nombre: "chat logo",
-            resumen: "Sube el logo del chat (.png, .jpg o .webp, hasta 200 KB).",
-            flags: ["--archivo ruta: la imagen", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
-            ejemplos: ["supcoflow chat logo --archivo logo.png --json"],
+            resumen: "Uploads the chat's logo (.png, .jpg or .webp, up to 200 KB).",
+            flags: ["--file path: the image", "--repo owner/repo: the repo, if it isn't this folder's «origin»", "--dry-run: says what it would do without doing it", "--json"],
+            ejemplos: ["supcoflow chat logo --file logo.png --json"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "sitios agregar",
-            resumen: "Agrega un sitio desde el que el chat puede cargarse.",
-            flags: ["--sitio https://…: el sitio", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
-            ejemplos: ["supcoflow sitios agregar --sitio https://app.ejemplo.com"],
+            nombre: "sites add",
+            resumen: "Adds a site the chat can load from.",
+            flags: ["--site https://…: the site", "--repo owner/repo: the repo, if it isn't this folder's «origin»", "--dry-run: says what it would do without doing it", "--json"],
+            ejemplos: ["supcoflow sites add --site https://app.example.com"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "sitios quitar",
-            resumen: "Quita un sitio de los que pueden cargar el chat.",
-            flags: ["--sitio https://…: el sitio", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
-            ejemplos: ["supcoflow sitios quitar --sitio https://app.ejemplo.com"],
+            nombre: "sites remove",
+            resumen: "Removes a site from the ones that can load the chat.",
+            flags: ["--site https://…: the site", "--repo owner/repo: the repo, if it isn't this folder's «origin»", "--dry-run: says what it would do without doing it", "--json"],
+            ejemplos: ["supcoflow sites remove --site https://app.example.com"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "datos fijar",
-            resumen: "Fija el acuerdo de datos: qué datos pasan. Frena lo que se guarda y lo que lee la IA que releva el repo; no cubre lo que ve la IA del chat mientras conversa.",
+            nombre: "data set",
+            resumen: "Sets the data agreement: which data gets through. It limits what is saved and what the AI that investigates the repo reads; it doesn't cover what the chat's AI sees while it talks.",
             flags: [
-                "--permitir lista: datos que pasan, separados por coma (usuario_id, usuario_rol, pagina_y_navegador, capturas, elementos, email, atributo:nombre) o `nada`",
-                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta",
-                "--dry-run: dice qué haría sin hacerlo",
+                "--allow list: data that gets through, comma-separated (user_id, user_role, page_and_browser, screenshots, elements, email, attribute:name) or `nothing`",
+                "--repo owner/repo: the repo, if it isn't this folder's «origin»",
+                "--dry-run: says what it would do without doing it",
                 "--json",
             ],
-            ejemplos: ["supcoflow datos fijar --permitir usuario_id,atributo:plan"],
+            ejemplos: ["supcoflow data set --allow user_id,attribute:plan"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "politica fijar",
-            resumen: "Fija qué hace el motor con un problema que llega por el chat: relevarlo en el acto (gasta) o guardarlo. Guardar frena sólo lo automático del chat: desde la consola una persona puede pedir el relevamiento, y cuesta.",
-            flags: ["--modo relevar|guardar", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
-            ejemplos: ["supcoflow politica fijar --modo guardar"],
+            nombre: "policy set",
+            resumen: "Sets what the engine does with a problem that comes in through the chat: investigate it right away (spends) or save it. Saving only stops what the chat does automatically: from the console a person can still ask for the investigation, and it costs.",
+            flags: ["--mode investigate|save", "--repo owner/repo: the repo, if it isn't this folder's «origin»", "--dry-run: says what it would do without doing it", "--json"],
+            ejemplos: ["supcoflow policy set --mode save"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "claves crear",
-            resumen: "Crea una clave de consulta (sólo lee su proyecto) y la guarda en un archivo 0600 fuera de todo repo; el secreto nunca sale por la salida.",
+            nombre: "keys create",
+            resumen: "Creates a read-only key (it only reads its project) and saves it in a 0600 file outside any repo; the secret never goes out through the output.",
             flags: [
-                "--nombre ci: para qué es la clave",
-                "--guardar-en ruta: el archivo donde queda (fuera de un repo; si ya tiene otra cosa sale 4 y no lo toca)",
-                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta",
-                "--dry-run: dice qué haría sin hacerlo",
+                "--name ci: what the key is for",
+                "--save-to path: the file where it ends up (outside a repo; if it already has something else it exits 4 and doesn't touch it)",
+                "--repo owner/repo: the repo, if it isn't this folder's «origin»",
+                "--dry-run: says what it would do without doing it",
                 "--json",
             ],
-            ejemplos: ["supcoflow claves crear --nombre ci --guardar-en ~/ci.key --json"],
+            ejemplos: ["supcoflow keys create --name ci --save-to ~/ci.key --json"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "claves listar",
-            resumen: "Lista las claves de consulta activas del proyecto (id, nombre, fecha; nunca el secreto).",
-            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--json"],
-            ejemplos: ["supcoflow claves listar --json"],
+            nombre: "keys list",
+            resumen: "Lists the project's active read-only keys (id, name, date; never the secret).",
+            flags: ["--repo owner/repo: the repo, if it isn't this folder's «origin»", "--json"],
+            ejemplos: ["supcoflow keys list --json"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "claves revocar",
-            resumen: "Revoca una clave de consulta por su id; revocar dos veces deja lo mismo.",
-            flags: ["--id cla_…: la clave (la da `claves listar`)", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
-            ejemplos: ["supcoflow claves revocar --id cla_0123456789abcdef --json"],
+            nombre: "keys revoke",
+            resumen: "Revokes a read-only key by its id; revoking twice leaves the same result.",
+            flags: ["--id cla_…: the key (`keys list` gives it)", "--repo owner/repo: the repo, if it isn't this folder's «origin»", "--dry-run: says what it would do without doing it", "--json"],
+            ejemplos: ["supcoflow keys revoke --id cla_0123456789abcdef --json"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "guia revisar",
-            resumen: "Revisa .supcoflow/guia.md (la raíz de este clon) contra el motor, sin publicar nada: dice si está bien armada y cuántas secciones tiene. Es el paso antes del commit.",
-            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta (sin clon local sale 3 falta_guia: la guía se lee del archivo)", "--dry-run: dice qué mandaría sin mandarlo", "--json"],
-            ejemplos: ["supcoflow guia revisar --json"],
+            nombre: "guide check",
+            resumen: "Checks .supcoflow/guide.md (this clone's root) against the engine, without publishing anything: says whether it's well formed and how many sections it has. It's the step before the commit. If guide.md doesn't exist it reads the old name .supcoflow/guia.md and says so.",
+            flags: ["--repo owner/repo: the repo, if it isn't this folder's «origin» (the guide is read from this clone only if it is that repo: its origin, or a `supcoflow` remote at https://github.com/owner/repo.git; otherwise it exits 3 falta_guia saying what this clone is and the exact `git remote add supcoflow …`, without asking the engine)", "--dry-run: says what it would send without sending it", "--json"],
+            ejemplos: ["supcoflow guide check --json"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "guia publicar",
-            resumen: "Sube .supcoflow/guia.md directo: manda el contenido y el commit y la rama que declara este clon (si hay git y commits; si no, sin commit). El motor la revisa y la deja como guía activa; el commit queda como «declarado por la terminal, no verificado en GitHub». Con --desde-github conserva la vía anterior: manda la huella y el motor la compara con la de la rama principal; si todavía no está subida a esa rama (o es otra), sale 5.",
-            flags: ["--desde-github: no sube el archivo; verifica contra la rama principal de GitHub (sale 5 guia_no_subida / guia_distinta si no coincide)", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta (sin clon local sale 3 falta_guia: la guía se lee del archivo)", "--dry-run: dice qué mandaría (o la huella con --desde-github), sin pedir nada", "--json"],
-            ejemplos: ["supcoflow guia publicar --json"],
+            nombre: "guide publish",
+            resumen: "Uploads .supcoflow/guide.md directly (or the old name guia.md, only if guide.md doesn't exist): sends the content, the file it read and the commit and branch this clone declares (if there's git and commits; otherwise, no commit). The engine checks it and makes it the active guide; the commit is kept as «declared by the terminal, not verified in GitHub». With --from-github it keeps the earlier route: it sends the fingerprint and the engine compares it with the main branch's; if it isn't pushed to that branch yet (or it's another one), it exits 5.",
+            flags: ["--from-github: doesn't upload the file; verifies against GitHub's main branch (exits 5 guia_no_subida / guia_distinta if it doesn't match)", "--repo owner/repo: the repo, if it isn't this folder's «origin» (the guide is read from this clone only if it is that repo: its origin, or a `supcoflow` remote at https://github.com/owner/repo.git; otherwise it exits 3 falta_guia saying what this clone is and the exact `git remote add supcoflow …`, without asking the engine)", "--dry-run: says what it would send (or the fingerprint with --from-github), without requesting anything", "--json"],
+            ejemplos: ["supcoflow guide publish --json"],
             codigos: [0, 1, 2, 3, 4, 5],
         },
         {
-            nombre: "guia ver",
-            resumen: "Muestra la guía activa del proyecto, de dónde viene y si la rama principal sigue teniendo esa versión (`al_dia` en el JSON).",
-            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--json"],
-            ejemplos: ["supcoflow guia ver --json"],
+            nombre: "guide show",
+            resumen: "Shows the project's active guide, where it comes from, which file it was read from (and whether that name is declared) and whether the main branch still has that version (`al_dia` in the JSON).",
+            flags: ["--repo owner/repo: the repo, if it isn't this folder's «origin»", "--json"],
+            ejemplos: ["supcoflow guide show --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
+        {
+            nombre: "guide use",
+            resumen: "Chooses which guide is active when there are two: the repo's or our agent's.",
+            flags: ["--source repo|agent: which one becomes active (required)", "--repo owner/repo: the repo, if it isn't this folder's «origin»", "--dry-run: says what it would do without doing it", "--json"],
+            ejemplos: ["supcoflow guide use --source repo --json"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "guia usar",
-            resumen: "Elige cuál guía queda activa cuando hay dos: la del repo o la de nuestro agente.",
-            flags: ["--origen repo|agente: cuál queda activa (obligatorio)", "--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--dry-run: dice qué haría sin hacerlo", "--json"],
-            ejemplos: ["supcoflow guia usar --origen repo --json"],
+            nombre: "guide versions",
+            resumen: "Lists the guide that governs now (the one the chat reads: its origin and version) and the repo's publications, newest first, with where each one comes from (declared by the terminal or verified in GitHub), commit, file and who published it. At most one says «live»: the one that is the active guide. Read-only.",
+            flags: ["--repo owner/repo: the repo, if it isn't this folder's «origin»", "--json: { vigente, publicaciones }"],
+            ejemplos: ["supcoflow guide versions --json"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
             nombre: "widget",
-            resumen: "Muestra lo que hay que pegar en la app para tener el chat, armado por el motor con los ids del proyecto: el paquete y su versión exacta, el archivo envoltorio de Next.js (`nextjs.contenido`, tal cual, sin reescribir los ids), cómo usarlo, la línea de CSP y la de <script> (no para Next.js). No escribe archivos. Sale 4 sin_proyecto si el repo no tiene proyecto; 1 respuesta_inesperada si el motor manda algo a medias.",
-            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--json: el objeto del motor tal cual"],
+            resumen: "Shows what to paste into the app to get the chat, built by the engine with the project's ids: the package and its exact version, the Next.js wrapper file (`nextjs.contenido`, as is, without rewriting the ids), the file name to use (`nextjs.archivo_sugerido`) and the earlier names the chat may already be installed under (`nextjs.archivos_anteriores`), how to use it, the CSP line and the <script> one (not for Next.js). It writes no files. Exits 4 sin_proyecto if the repo has no project; 1 respuesta_inesperada if the engine sends something halfway.",
+            flags: ["--repo owner/repo: the repo, if it isn't this folder's «origin»", "--json: the engine's object as is"],
             ejemplos: ["supcoflow widget --json"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "instalacion anotar",
-            resumen: "Anota en .supcoflow/instalacion.json (la raíz de este clon) con qué versiones se instaló el chat: la skill, esta terminal, el paquete del chat (declarado en el package.json de la app e instalado en node_modules) y la configuración del proyecto; nunca un secreto ni una fecha. Repetir sin cambios no lo toca (sin_cambios: true). Lo reescribe sólo si git ya guarda el anterior: si tiene cambios sin commit (o está borrado sin commit) sale 4 cambios_sin_commit; si existe sin estar versionado (o ignorado), 4 archivo_no_versionado. Otros: 3 falta_skill / skill_invalida / app_fuera_del_repo / app_inexistente / sin_clon; 4 sin_proyecto / acuerdo_ilegible; 1 paquete_ilegible / configuracion_inesperada / archivo_no_escrito.",
+            nombre: "install record",
+            resumen: "Records in .supcoflow/instalacion.json (this clone's root, version 2) which versions the chat was installed with: the skill, this terminal, the chat package (declared in the app's package.json and installed in node_modules), the project configuration and, with --file, the file the chat lives in; never a secret or a date. Repeating without changes doesn't touch it (sin_cambios: true), and running again without --file keeps the file already recorded. It only rewrites it if git already keeps the previous one: with uncommitted changes (or deleted without a commit) it exits 4 cambios_sin_commit; if it exists without being tracked (or ignored), 4 archivo_no_versionado. Others: 3 falta_skill / skill_invalida / archivo_invalido / app_fuera_del_repo / app_inexistente / sin_clon; 4 sin_proyecto / acuerdo_ilegible; 1 paquete_ilegible / configuracion_inesperada / archivo_no_escrito.",
             flags: [
-                "--skill versión: la metadata.version de la skill que instala (semver, obligatorio; sin él sale 3 falta_skill sin pedir nada)",
-                "--app carpeta: la carpeta de la app, relativa a la raíz del repo (por defecto la raíz; fuera del repo sale 3 app_fuera_del_repo)",
-                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta (sin clon local sale 3 sin_clon: el archivo va en el clon)",
-                "--dry-run: muestra el archivo y la diferencia sin escribir nada",
+                "--skill version: the metadata.version of the skill that installs it (semver, required; without it exits 3 falta_skill without requesting anything)",
+                "--file path: the chat file, relative to the repo root (no `..`, not absolute, not a symlink or through one; otherwise exits 3 archivo_invalido and writes nothing)",
+                "--app folder: the app's folder, relative to the repo root (the root by default; outside the repo it exits 3 app_fuera_del_repo)",
+                "--repo owner/repo: the repo, if it isn't this folder's «origin» (the file goes in this clone only if it is that repo: its origin, or a `supcoflow` remote at https://github.com/owner/repo.git; otherwise it exits 3 sin_clon saying what this clone is and the exact `git remote add supcoflow …`, without asking the engine)",
+                "--dry-run: shows the file and the difference without writing anything",
                 "--json",
             ],
-            ejemplos: ["supcoflow instalacion anotar --skill 0.1.0 --app web --json"],
+            ejemplos: ["supcoflow install record --skill 0.3.1 --app web --file web/app/_supcoflow/support-chat.tsx --json"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "diagnosticar",
-            resumen: "Dice, gratis y sin escribir nada, si una prueba del proyecto entraría y hasta dónde llegaría: instalación de GitHub, sitios, chat, guía, política, saldo del mes contra el techo de la prueba, pruebas abiertas y lo que el motor sume. Sale 0 si está todo listo y 4 si algo hay que arreglar (no_listo), con cada punto.",
-            flags: ["--repo owner/repo: el repo, si no es el «origin» de esta carpeta", "--json"],
-            ejemplos: ["supcoflow diagnosticar --json"],
+            nombre: "diagnose",
+            resumen: "Says, free of charge and writing nothing, how far the installation is (sign-in, repo, GitHub App, allowed sites, chat and guide: N of 6) and, apart, whether a test of the project would go in and how far it would get: policy, monthly balance against the test's ceiling, open tests, whether THIS machine can save the test request (the local point `maquina`, checked without writing anything) and whatever else the engine adds. Exits 0 if everything is ready and 4 if something needs fixing (no_listo), with each point; if `maquina` isn't ok, `listo` and `prueba.listo` are false and the N of 6 doesn't change.",
+            flags: ["--repo owner/repo: the repo, if it isn't this folder's «origin»", "--json: { instalacion: { ok, total: 6, puntos }, prueba: { listo, puntos }, maquina: { ok, impedimentos: [{ codigo, detalle }] }, intento_pendiente: { techo_usd, politica } | null, … }"],
+            ejemplos: ["supcoflow diagnose --json"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
-            nombre: "probar",
-            resumen: "Prueba la instalación de punta a punta: un problema entra por la misma puerta que el chat y termina en un issue. Gasta un relevamiento (hasta el techo que dice el motor; con la política guardar llega hasta el caso guardado y no gasta). Sin --autorizo-gasto no manda nada: sale 4 falta_autorizacion con techo_usd, saldo_usd, tope_usd y comprometido_usd. Con --autorizo-gasto pide la prueba y sale 5 con prueba_id; después --wait la sigue. Otros: 4 prueba_en_curso (con su id), techo_distinto, chat_deshabilitado, requiere_api_key, intento_pendiente; 6 tope_mensual; 1 con intento_pendiente: true si la respuesta no llegó (repetir retoma la misma prueba).",
+            nombre: "test",
+            resumen: "Tests the installation end to end: a problem comes in through the same door as the chat and ends up as an issue. It spends one investigation (up to the ceiling you authorize; with the save policy it goes as far as the saved case and doesn't spend). Without --authorize-spend it sends nothing: it exits 4 falta_autorizacion with techo_usd, saldo_usd, tope_usd and comprometido_usd, and, checked before you say yes and without writing anything, `maquina` { ok, impedimentos: [{ codigo, detalle }] } (whether this machine can save the test request: if it isn't ok the message says why first) and `intento_pendiente` { techo_usd, politica } | null (a request waiting for confirmation: only its ceiling and policy, never its message or key). With --authorize-spend, --ceiling and --expect-policy it requests the test with exactly those values (it doesn't re-read anything to choose them) and exits 5 with prueba_id; then --wait follows it. If the ceiling or the policy changed in the meantime it exits 4 techo_distinto / politica_distinta with the new values and doesn't retry: ask again. Others: 4 prueba_en_curso (with its id), chat_deshabilitado, requiere_api_key, intento_pendiente; 6 tope_mensual; 1 with intento_pendiente: true if the answer didn't arrive (repeating resumes the same test).",
             flags: [
-                "--autorizo-gasto: autoriza el gasto de UNA prueba, hasta el techo que mostró el motor; sin él no se manda nada que escriba",
-                "--mensaje \"…\": el texto del problema de la prueba (por defecto, uno fijo del motor); con un pedido sin confirmar, otro --mensaje sale 4 intento_pendiente",
-                "--wait: sigue la última prueba hasta 90 s; sale 5 mientras corre, 0 con el issue (o guardado), 4 si hace falta mirarla (con el enlace a la bandeja); el cobro sale como esté (pendiente nunca es 0)",
-                "--prueba prb_…: con --wait, sigue esa prueba en vez de la última guardada",
-                "--repo owner/repo: el repo, si no es el «origin» de esta carpeta",
-                "--dry-run: dice qué haría (proyecto, techo, saldo, política) sin pedir nada que escriba",
+                "--authorize-spend: authorizes the spend of ONE test; without it nothing that writes is sent",
+                "--ceiling usd: the ceiling you authorize, the number you were shown (required with --authorize-spend)",
+                "--expect-policy investigate|save: the policy you were offered (required with --authorize-spend); if the project's is another one, nothing starts",
+                "--message \"…\": the problem text of the test (by default, a fixed one from the engine); with a request that was never confirmed, another --message exits 4 intento_pendiente",
+                "--wait: follows the last test up to 90 s; exits 5 while it runs, 0 with the issue (or saved), 4 if it needs a look (with the link to the inbox); the charge comes out as it is (pending is never 0)",
+                "--test-id prb_…: with --wait, follows that test instead of the last saved one",
+                "--repo owner/repo: the repo, if it isn't this folder's «origin»",
+                "--dry-run: says what it would do (project, ceiling, balance, policy) without requesting anything that writes",
                 "--json",
             ],
-            ejemplos: ["supcoflow probar --json", "supcoflow probar --autorizo-gasto --json", "supcoflow probar --wait --json", "supcoflow probar --dry-run --autorizo-gasto --json"],
+            ejemplos: ["supcoflow test --json", "supcoflow test --authorize-spend --ceiling 2 --expect-policy investigate --json", "supcoflow test --wait --json", "supcoflow test --dry-run --authorize-spend --ceiling 2 --expect-policy investigate --json"],
             codigos: [0, 1, 2, 3, 4, 5, 6],
         },
     ],
-    flags_globales: ["--json: el resultado en una línea de JSON por stdout; los avisos van por stderr", "--help, -h: la ayuda con ejemplos"],
+    flags_globales: ["--json: the result as a line of JSON on stdout; warnings go to stderr", "--help, -h: the help with examples"],
     facultades: [
         {
-            nombre: "consultar",
-            incluye: "Identidad y equipo, proyectos, configuración, casos, issues, runs, costos, estado de la instalación, leer y revisar la guía (guia revisar, guia ver)",
+            nombre: "read",
+            incluye: "Identity and team, projects, configuration, cases, issues, runs, costs, installation state, reading and checking the guide (guide check, guide show, guide versions)",
             con_api_key: true,
         },
         {
-            nombre: "configurar",
-            incluye: "Crear/reusar proyecto, conectar o desconectar el repo, configurar y prender el chat, sitios permitidos, acuerdo de datos, política de problemas, publicar la guía, elegir la guía activa (guia usar), crear y revocar claves de consulta, perfiles de los agentes",
+            nombre: "configure",
+            incluye: "Create/reuse a project, connect or disconnect the repo, configure and turn on the chat, allowed sites, data agreement, problem policy, publish the guide, choose the active guide (guide use), create and revoke read-only keys, agent profiles",
             con_api_key: true,
         },
-        { nombre: "probar", incluye: "La prueba hasta el issue (gasta, dentro de los topes)", con_api_key: true },
+        { nombre: "test", incluye: "The test up to the issue (spends, within the limits)", con_api_key: true },
         {
-            nombre: "solo_consola",
-            incluye: "Subir el tope de gasto, borrar el proyecto, encender la fábrica, dar o sacar acceso a personas: sólo con sesión en la consola",
+            nombre: "console_only",
+            incluye: "Raise the spend cap, delete the project, turn on the factory, give or remove people's access: only with a console session",
             con_api_key: false,
         },
         {
-            nombre: "operador",
-            incluye: "Solicitudes, /maquinaria, cerrar runs, la fábrica de operador: nunca por clave, aunque la persona sea operadora",
+            nombre: "operator",
+            incluye: "Requests, /maquinaria, closing runs, the operator factory: never by key, even if the person is an operator",
             con_api_key: false,
         },
     ],
     codigos: {
         [SALIDA.ok]: "ok",
-        [SALIDA.inesperado]: "inesperado",
-        [SALIDA.faltaLogin]: "falta login",
-        [SALIDA.entradaInvalida]: "entrada inválida",
-        [SALIDA.haceFaltaUnaPersona]: "hace falta una persona",
-        [SALIDA.esperandoAUnaPersona]: "esperando a una persona (volvé a llamar)",
-        [SALIDA.topeAlcanzado]: "tope alcanzado",
+        [SALIDA.inesperado]: "unexpected",
+        [SALIDA.faltaLogin]: "login needed",
+        [SALIDA.entradaInvalida]: "invalid input",
+        [SALIDA.haceFaltaUnaPersona]: "a person is needed",
+        [SALIDA.esperandoAUnaPersona]: "waiting for a person (call again)",
+        [SALIDA.topeAlcanzado]: "limit reached",
     },
 };
 export function comandoDescribir() {
@@ -298,21 +308,21 @@ function bloque(c) {
 }
 export function ayuda(comando) {
     const elegidos = comando === null ? DESCRIPCION.comandos : DESCRIPCION.comandos.filter((c) => c.nombre === comando);
-    const uso = comando === null ? "supcoflow <comando> [flags]" : `supcoflow ${comando} [flags]`;
+    const uso = comando === null ? "supcoflow <command> [flags]" : `supcoflow ${comando} [flags]`;
     const codigos = Object.entries(DESCRIPCION.codigos).map(([n, t]) => `  ${n}  ${t}`);
     return [
-        `Uso: ${uso}`,
+        `Usage: ${uso}`,
         "",
-        comando === null ? "Comandos:" : "Comando:",
+        comando === null ? "Commands:" : "Command:",
         ...elegidos.map(bloque),
         "",
-        "Flags de todos los comandos:",
+        "Flags for every command:",
         ...DESCRIPCION.flags_globales.map((f) => `  ${f}`),
         "",
-        "Ejemplos:",
+        "Examples:",
         ...elegidos.flatMap((c) => c.ejemplos.map((e) => `  ${e}`)),
         "",
-        "Códigos de salida:",
+        "Exit codes:",
         ...codigos,
     ].join("\n");
 }