supcoflow 0.6.0 → 0.8.0

package/README.md

@@ -1,200 +1,248 @@
 # supcoflow
 
-La terminal de [Supcoflow](https://app.supcoflow.dev): iniciar sesión y manejar el chat de soporte
-desde la consola, o desde un asistente de código que corre comandos por vos.
+The [Supcoflow](https://app.supcoflow.dev) terminal: sign in and manage the support chat from the console,
+or from a code assistant that runs the commands for you.
 
-Trae iniciar y cerrar sesión, ver con qué cuenta estás, conectar el repo con la App de GitHub,
-crear su proyecto, configurar el chat y ponerlo en la app.
+It signs you in and out, shows which account you are using, connects the repo with the GitHub App, creates
+its project, configures the chat, puts it in the app, and checks that a problem reaches an issue.
 
-## Instalar
+## Install
 
-Hace falta Node 24 o más nuevo.
+Node 24 or newer is required.
 
 ```bash
 npx supcoflow login
 ```
 
-## Los comandos
+## The commands
 
-| Comando | Qué hace |
+The command names are in English. The Spanish names of 0.7.0 (`quien-soy`, `guia publicar`,
+`--autorizo-gasto`, `--modo relevar|guardar`…) still work as hidden aliases; `describe` and `--help` only show
+the English ones.
+
+| Command | What it does |
 |---|---|
-| `supcoflow login` | Te muestra un enlace y un código; lo aprobás en la consola y la terminal queda con su clave. |
-| `supcoflow login --start` | El primer paso, solo: pide el código y sale 5 con el enlace para aprobarlo. |
-| `supcoflow login --wait` | El segundo paso: espera la aprobación hasta 90 s. Si todavía no llegó, sale 5: volvé a correrlo. |
-| `supcoflow logout` | Revoca la clave en uso y la borra de esta máquina. |
-| `supcoflow quien-soy` | Con qué clave anda la terminal, a nombre de quién y en qué equipo. |
-| `supcoflow repo conectar` | Conecta el repo de esta carpeta con la App de GitHub: te da un enlace, lo confirmás en la consola. Sin terminal, `--start` y después `--wait`, como `login`. |
-| `supcoflow proyecto crear` | Crea (o reusa) el proyecto del repo ya conectado y lo anota en `.supcoflow/proyecto.json`. Si el motor no deduce los comandos, `--install "…" --test "…"`. |
-| `supcoflow proyecto ver` | El proyecto del repo: rama, comandos y el estado de la App de GitHub. |
-| `supcoflow guia revisar` | Revisa `.supcoflow/guia.md` contra el motor sin publicar nada. |
-| `supcoflow guia publicar` | Sube `.supcoflow/guia.md` directo (con el commit y la rama que declara tu clon, no verificados en GitHub). `--desde-github` verifica contra la rama principal en vez de subir el archivo. |
-| `supcoflow guia ver` | Muestra la guía activa, de dónde viene y si la rama sigue al día. |
-| `supcoflow guia usar --origen repo\|agente` | Elige cuál guía queda activa. |
-| `supcoflow widget` | Lo que hay que pegar en la app para tener el chat (ver «Poner el chat en la app»). |
-| `supcoflow instalacion anotar --skill 0.1.0` | Anota en `.supcoflow/instalacion.json` con qué versiones se instaló el chat. |
-| `supcoflow describir --json` | Todo el contrato (comandos, flags, facultades de la clave, códigos) en una línea de JSON. |
-
-`supcoflow --help` (o `supcoflow <comando> --help`) muestra la ayuda con ejemplos. Los comandos de
-repo y proyecto toman el repo del `origin` de la carpeta; `--repo owner/repo` lo elige a mano.
-
-### De cero a un proyecto
-
-1. `supcoflow login`: aprobás el código en la consola.
-2. `supcoflow repo conectar`: instalás la App en GitHub si hace falta y tocás Confirmar.
-3. `supcoflow proyecto crear`: queda el proyecto y `.supcoflow/proyecto.json` para commitear.
-4. `supcoflow proyecto ver`: para revisar cómo quedó.
-
-### Ejemplos
+| `supcoflow login` | Shows a link and a code; you approve it in the console and the terminal keeps its key. |
+| `supcoflow login --start` | The first step alone: asks for the code and exits 5 with the link to approve it. |
+| `supcoflow login --wait` | The second step: waits for the approval up to 90 s. If it hasn't arrived, exits 5: run it again. |
+| `supcoflow logout` | Revokes the key in use and deletes it from this machine. |
+| `supcoflow whoami` | Which key the terminal runs with, on whose behalf and in which team. |
+| `supcoflow repo connect` | Connects this folder's repo with the GitHub App: it gives you a link and you confirm it in the console. Without a terminal, `--start` and then `--wait`, like `login`. |
+| `supcoflow project create` | Creates (or reuses) the project of the connected repo and records it in `.supcoflow/proyecto.json`. If the engine can't work out the commands, `--install "…" --test "…"`. |
+| `supcoflow project show` | The repo's project: branch, commands and the state of the GitHub App. |
+| `supcoflow guide check` | Checks `.supcoflow/guide.md` against the engine without publishing anything. |
+| `supcoflow guide publish` | Uploads `.supcoflow/guide.md` directly (with the commit and branch your clone declares, not verified in GitHub). `--from-github` verifies against the main branch instead of uploading the file. |
+| `supcoflow guide show` | Shows the active guide, where it comes from, which file it was read from and whether the branch is still up to date. |
+| `supcoflow guide use --source repo\|agent` | Chooses which guide is active. |
+| `supcoflow guide versions` | The guide that governs now and the repo's publications, newest first; at most one says «live». |
+| `supcoflow widget` | What to paste into the app to get the chat (see «Put the chat in the app»). |
+| `supcoflow install record --skill 0.3.0 --file app/_supcoflow/support-chat.tsx` | Records in `.supcoflow/instalacion.json` which versions the chat was installed with and which file it lives in. |
+| `supcoflow diagnose` | Free: how far the installation is (N of 6) and whether a test would go in. |
+| `supcoflow test` | The end-to-end test (see «Test the installation»). |
+| `supcoflow describe --json` | The whole contract (commands, flags, key capabilities, codes) in one line of JSON. |
+
+`supcoflow --help` (or `supcoflow <command> --help`) shows the help with examples. The repo and project commands
+take the repo from the folder's `origin`; `--repo owner/repo` picks it by hand.
+
+### From zero to a project
+
+1. `supcoflow login`: you approve the code in the console.
+2. `supcoflow repo connect`: you install the App on GitHub if needed and tap Confirm.
+3. `supcoflow project create`: the project is created and `.supcoflow/proyecto.json` is left to commit.
+4. `supcoflow project show`: to check how it ended up.
+
+### Examples
 
 ```bash
-# Una persona frente a la terminal
+# A person at the terminal
 supcoflow login
 
-# Un asistente, sin terminal interactiva: dos pasos
-supcoflow login --start --json     # sale 5 con verification_uri_complete y user_code
-supcoflow login --wait --json      # sale 5 mientras la persona no apruebe; 0 cuando aprueba
+# An assistant, without an interactive terminal: two steps
+supcoflow login --start --json     # exits 5 with verification_uri_complete and user_code
+supcoflow login --wait --json      # exits 5 until the person approves; 0 when they do
 
-supcoflow repo conectar --start --json   # sale 5 con la url para confirmar
-supcoflow repo conectar --wait --json    # sale 5 mientras nadie confirme; 0 conectado
-supcoflow proyecto crear --json          # 4 si hay un .supcoflow/proyecto.json distinto (no lo pisa)
-supcoflow proyecto crear --install "pnpm i" --test "pnpm test"
-supcoflow proyecto ver --json
+supcoflow repo connect --start --json   # exits 5 with the URL to confirm
+supcoflow repo connect --wait --json    # exits 5 until someone confirms; 0 connected
+supcoflow project create --json         # 4 if there is a different .supcoflow/proyecto.json (it doesn't overwrite)
+supcoflow project create --install "pnpm i" --test "pnpm test"
+supcoflow project show --json
 
-supcoflow quien-soy --json
-supcoflow logout --dry-run         # qué revocaría, sin revocar nada
+supcoflow whoami --json
+supcoflow logout --dry-run         # what it would revoke, without revoking anything
 ```
 
-## Configurar
+## Configure
 
-Con el repo ya conectado y su proyecto creado, se configura el chat sin entrar a la consola (la clave
-tiene que ser de sesión, no de consulta). Todos toman el repo del `origin`, o `--repo owner/repo`, y
-los que escriben aceptan `--dry-run`.
+With the repo connected and its project created, the chat is configured without entering the console (the key
+has to be a session key, not a read-only one). All of them take the repo from the `origin`, or `--repo
+owner/repo`, and the ones that write accept `--dry-run`.
 
-| Comando | Qué hace |
+| Command | What it does |
 |---|---|
-| `supcoflow catalogo` | Qué se puede configurar y con qué valores. |
-| `supcoflow configuracion` | Chat, sitios, marca y acuerdo de datos del proyecto. |
-| `supcoflow chat prender` / `chat apagar` | Prende o apaga el chat (hace falta una guía: publicá la del repo con `supcoflow guia publicar` o generá y aprobá la de nuestro agente en Brain). |
-| `supcoflow chat marca --titulo "Ayuda" --tema acento=#0a7` | Título, saludo y colores; lo no nombrado queda igual. |
-| `supcoflow chat logo --archivo logo.png` | Sube el logo (.png, .jpg o .webp, hasta 200 KB). |
-| `supcoflow sitios agregar\|quitar --sitio https://app.ejemplo.com` | Sitios desde los que carga el chat. |
-| `supcoflow datos fijar --permitir usuario_id,atributo:plan` | Acuerdo de datos: frena lo que se guarda y lo que lee la IA que releva; no cubre lo que ve la IA del chat mientras conversa. |
-| `supcoflow politica fijar --modo guardar` | Qué hace el motor con un problema que llega por el chat: `relevar` (gasta) o `guardar`. Guardar frena sólo lo automático del chat; una persona puede pedir el relevamiento desde la consola, y cuesta. |
-| `supcoflow claves crear --nombre ci --guardar-en ~/ci.key` | Clave de consulta para CI: el secreto queda sólo en ese archivo (0600, fuera de un repo), nunca en la salida. |
-| `supcoflow claves listar` / `claves revocar --id cla_…` | Ver y revocar claves de consulta. |
-
-## La guía
-
-La guía le cuenta al chat qué hace cada pantalla de tu producto. Vive en el repo, en
-`.supcoflow/guia.md` (en la raíz). El flujo, en este orden:
-
-1. `supcoflow guia revisar`: la revisa contra el motor sin publicar nada (si está mal armada, sale 3 con la línea de cada error).
-2. `supcoflow guia publicar`: sube el archivo directo y queda como guía activa. Manda también el commit y la rama de tu
-   clon (`git rev-parse HEAD`, si hay git y commits; si no, va sin commit): son declarados por la terminal, no
-   verificados en GitHub, y así se muestran. Repetir con el mismo archivo no duplica.
-3. Opcional, `supcoflow guia publicar --desde-github`: no sube el archivo; manda su huella y el motor la compara con la
-   de la rama principal de GitHub (commit verificado). Si todavía no está subida (o la rama tiene otra), sale 5:
-   subí la guía a la rama principal y volvé a correr.
-
-`supcoflow guia ver` muestra la guía activa y si la rama sigue al día (`al_dia` en el JSON);
-`supcoflow guia usar --origen repo|agente` elige cuál queda activa cuando hay una del repo y otra de nuestro agente.
-Todos toman el repo del `origin`, o `--repo owner/repo` (con `revisar` y `publicar`, sin clon local de ese repo sale 3 `falta_guia`: la guía se lee del archivo); `revisar`, `publicar` y `usar` aceptan `--dry-run`; `--desde-github` es sólo de `publicar`.
-
-El formato de `.supcoflow/guia.md`:
+| `supcoflow catalog` | What can be configured and with which values. |
+| `supcoflow config` | The project's chat, sites, brand and data agreement. |
+| `supcoflow chat on` / `chat off` | Turns the chat on or off (a guide is needed: publish the repo's with `supcoflow guide publish`, or generate and approve our agent's in Brain). |
+| `supcoflow chat brand --title "Help" --theme acento=#0a7` | Title, greeting and colors; whatever isn't named stays as it was. The `--theme` keys are the API's: `acento`, `fondo`, `texto`, `textoSuave`, `radio`, `fuente`. |
+| `supcoflow chat logo --file logo.png` | Uploads the logo (.png, .jpg or .webp, up to 200 KB). |
+| `supcoflow sites add\|remove --site https://app.example.com` | Sites the chat loads from. |
+| `supcoflow data set --allow user_id,attribute:plan` | Data agreement: it limits what is saved and what the AI that investigates reads; it doesn't cover what the chat's AI sees while it talks. The values are `user_id`, `user_role`, `page_and_browser`, `screenshots`, `elements`, `email`, `attribute:<name>` or `nothing`. |
+| `supcoflow policy set --mode save` | What the engine does with a problem that comes in through the chat: `investigate` (spends) or `save`. Saving only stops what the chat does automatically; a person can still ask for the investigation from the console, and it costs. |
+| `supcoflow keys create --name ci --save-to ~/ci.key` | Read-only key for CI: the secret stays only in that file (0600, outside a repo), never in the output. |
+| `supcoflow keys list` / `keys revoke --id cla_…` | List and revoke read-only keys. |
+
+## The guide
+
+The guide tells the chat what each screen of your product does. It lives in the repo, in
+`.supcoflow/guide.md` (at the root). The flow, in this order:
+
+1. `supcoflow guide check`: checks it against the engine without publishing anything (if it is badly formed it exits 3 with the line of each error).
+2. `supcoflow guide publish`: uploads the file directly and it becomes the active guide. It also sends your clone's
+   commit and branch (`git rev-parse HEAD`, if there is git and commits; otherwise it goes without a commit): they are
+   declared by the terminal, not verified in GitHub, and are shown that way. It also sends the file it actually read.
+   Repeating with the same file doesn't duplicate it.
+3. Optional, `supcoflow guide publish --from-github`: it doesn't upload the file; it sends its fingerprint and the
+   engine compares it with the main branch's on GitHub (verified commit). If it isn't pushed yet (or the branch has
+   another one), it exits 5: push the guide to the main branch and run again.
+
+**The old file name.** Until 0.7.0 the file was `.supcoflow/guia.md`. If `guide.md` doesn't exist and `guia.md` does,
+the terminal reads `guia.md` and says so («rename it to `guide.md`»); it never renames or deletes your files. If both
+exist, `guide.md` wins and the terminal says `guia.md` is ignored. If `guide.md` exists but can't be read, or is
+badly formed, that is an error: it never falls back to the old one.
+
+`supcoflow guide show` shows the active guide, the file it was read from and whether the branch is still up to date
+(`al_dia` in the JSON); `supcoflow guide versions` lists the guide that governs now and the repo's publications;
+`supcoflow guide use --source repo|agent` chooses which one is active when there is one from the repo and one from
+our agent. All of them take the repo from the `origin`, or `--repo owner/repo` (with `check` and `publish`, without a
+local clone of that repo it exits 3 `falta_guia`: the guide is read from the file); `check`, `publish` and `use`
+accept `--dry-run`; `--from-github` is only for `publish`.
+
+The format of `.supcoflow/guide.md`:
 
 ```markdown
-# Guía de Mi App            ← opcional; se ignora
-
-## Facturas                 ← una sección por pantalla o función (1 a 60). Nombre: 1–120 caracteres
-Para qué sirve: Ver y pagar las facturas del mes.             ← obligatorio, 1–600
-Qué puede hacer el usuario: Descargar el PDF, pagar con       ← obligatorio, 1–600; puede seguir
-tarjeta y ver el historial.                                       en las líneas de abajo
-Problemas comunes:                                            ← opcional; hasta 10, cada uno 1–300
-- El botón Pagar no responde con tarjetas de débito.
-- El PDF sale en blanco en Safari.
+# My App guide              ← optional; ignored
+
+## Invoices                 ← one section per screen or function (1 to 60). Name: 1–120 characters
+What it's for: See and pay the month's invoices.                 ← required, 1–600
+What users can do: Download the PDF, pay by card and see the    ← required, 1–600; it can continue
+history.                                                            on the lines below
+Common problems:                                                ← optional; up to 10, each 1–300
+- The Pay button does nothing with debit cards.
+- The PDF comes out blank in Safari.
+Where: /invoices                                                ← optional; the page's path, starts with /
 ```
 
-- Las etiquetas se reconocen al principio de la línea, sin distinguir mayúsculas y con o sin tildes
-  («Para que sirve:» vale). Una línea que no es etiqueta continúa el campo anterior (se une con un espacio).
-- Texto antes del primer `## ` que no sea el `# ` del título → error. Una etiqueta repetida en una sección →
-  error. Una línea con `<` o `>` → error. Más de 64 KB → `guia_muy_grande`.
-
-## Poner el chat en la app
-
-`supcoflow widget` muestra lo que hay que pegar, armado por el motor con los ids de tu proyecto (no los
-copies a mano: un id mal copiado deja el chat invisible sin ningún error). No escribe archivos de la app:
-
-1. El paquete con su versión exacta (`npm i @supcoflow/chat@… --save-exact`, o lo mismo con tu gestor).
-2. **Next.js (App Router):** un archivo envoltorio en la ruta que sugiere el motor
-   (`app/_supcoflow/chat-de-soporte.tsx`; si la app usa `src/app`, dentro de `src/app`), con el contenido
-   tal cual. Hace falta porque el componente del chat usa hooks de React y no trae `"use client"`, y un
-   `layout.tsx` es de servidor por defecto: importarlo directo ahí no anda. El envoltorio es esa directiva
-   más el componente con los ids.
-3. Usar el envoltorio en el layout que cubre las pantallas donde se traban tus usuarios.
-4. Si la app tiene una política de contenido (CSP) con `connect-src`, agregarle el origen del chat
-   conservando lo que ya tiene (una segunda `connect-src` se ignora).
-
-La línea de `<script>` que también muestra está disponible pero no probada en una app real, y no es
-para Next.js. `supcoflow widget --json` devuelve el objeto del motor tal cual.
-
-Después, `supcoflow instalacion anotar --skill <versión> [--app <carpeta>]` deja en
-`.supcoflow/instalacion.json` (para commitear) con qué versiones quedó: la skill, la terminal, el chat
-declarado e instalado, y la configuración del proyecto. Nunca lleva un secreto ni una fecha; repetirlo
-sin cambios no lo toca, y si el archivo tiene cambios sin commit sale 4 y no lo pisa.
-
-## Con un asistente
-
-Si usás un asistente de código como Claude Code, la skill de Supcoflow hace todo el camino
-por vos: sesión, proyecto, configuración, guía, el chat en la app y el resumen.
+- Labels are recognized at the start of the line, ignoring case. The Spanish labels of 0.7.0 (`Para qué sirve:`,
+  `Qué puede hacer el usuario:`, `Problemas comunes:`) are still accepted. A line that isn't a label continues the
+  previous field (joined with a space).
+- Text before the first `## ` that isn't the `# ` title → error. A repeated label in a section → error. A line with
+  `<` or `>` → error. More than 64 KB → `guia_muy_grande`.
+
+## Put the chat in the app
+
+`supcoflow widget` shows what to paste, built by the engine with your project's ids (don't copy them by hand: a
+wrongly copied id leaves the chat invisible without any error). It writes no files of the app:
+
+1. The package with its exact version (`npm i @supcoflow/chat@… --save-exact`, or the same with your package manager).
+2. **Next.js (App Router):** a wrapper file at the path the engine suggests (`nextjs.archivo_sugerido`, today
+   `app/_supcoflow/support-chat.tsx`; if the app uses `src/app`, inside `src/app`), with the content as is. If the
+   chat is already installed under an earlier name (`nextjs.archivos_anteriores`, for example
+   `app/_supcoflow/chat-de-soporte.tsx`), update that file in place instead of creating a second one. The wrapper is
+   needed because the chat component uses React hooks and doesn't ship `"use client"`, and a `layout.tsx` is a server
+   component by default: importing it directly there doesn't work.
+3. Use the wrapper in the layout that covers the screens where your users get stuck.
+4. If the app has a Content Security Policy (CSP) with `connect-src`, add the chat's origin to it, keeping what it
+   already has (a second `connect-src` is ignored).
+
+The `<script>` line it also shows is available but not tested in a real app, and is not for Next.js.
+`supcoflow widget --json` returns the engine's object as is.
+
+Then, `supcoflow install record --skill <version> [--app <folder>] [--file <path>]` leaves in
+`.supcoflow/instalacion.json` (to commit) which versions it ended up with: the skill, the terminal, the chat declared
+and installed, the project configuration and, with `--file`, the file the chat lives in (a path relative to the repo
+root, with no `..`, and not a symlink). The file is version 2; a version 1 file (from 0.7.0) is read without error as
+«no file recorded». Running it again without `--file` keeps the file already recorded. It never contains a secret or
+a date; repeating it without changes doesn't touch it, and if the file has uncommitted changes it exits 4 and doesn't
+overwrite it.
+
+## Test the installation
+
+With the chat in place, two commands say whether a problem that comes in through the chat reaches an issue. Both take
+the repo from the `origin`, or `--repo owner/repo`.
+
+| Command | What it does |
+|---|---|
+| `supcoflow diagnose` | Free and writes nothing. It prints «Checked sign-in, repo, GitHub App, allowed sites, chat and guide: N of 6, at no cost.» and, apart, «Ready for a test: yes / no, because …» with the policy, the month's balance and open tests. Exits 0 if everything is ready, 4 if something needs fixing (with each point). `--json` gives `instalacion: { ok, total: 6, puntos }` and `prueba: { listo, puntos }`. |
+| `supcoflow test` | Without `--authorize-spend` it sends nothing: it exits 4 with the test's ceiling, the balance, the cap and what is committed this month, and the exact command to launch it. |
+| `supcoflow test --authorize-spend --ceiling 2 --expect-policy investigate` | Requests the test: the problem comes in through the same door as the chat and runs an investigation that **spends** up to the ceiling you authorize (with the `save` policy it goes as far as the saved case and doesn't spend). Exits 5 with the id. `--message "…"` uses your own text. |
+| `supcoflow test --wait` | Follows the last test up to 90 s: 5 while it runs (call it again), 0 with the issue, 4 if it needs a look in the console (it brings the link). The charge is shown as it is: `pendiente` right at the close, never 0. `--test-id prb_…` follows another one. |
+| `supcoflow test --dry-run --authorize-spend --ceiling 2 --expect-policy investigate` | What it would do (project, ceiling, balance, policy), without requesting anything. |
+
+`--ceiling` is the number you were shown and `--expect-policy` the policy you were offered: both travel in the request
+and the terminal doesn't re-read anything to choose them. 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. The old
+`probar --autorizo-gasto` alias also needs `--ceiling` now (an alias can't widen what you authorized); if you need the
+old behavior, use supcoflow 0.7.0.
+
+If the engine's answer doesn't arrive, the request stays saved on this machine (outside the repo, next to the
+credentials): repeating the same `supcoflow test --authorize-spend …` picks up **the same** test instead of
+requesting another. While a request is unconfirmed, another `--message`, `--ceiling` or `--expect-policy` exits 4
+`intento_pendiente`. The test goes with the personal key of `supcoflow login`; a read-only key can't request it. One
+open test per project: another one exits 4 `prueba_en_curso` with the id of the open one. A test's issue stays open and
+is marked as a test.
+
+## With an assistant
+
+If you use a code assistant such as Claude Code, the Supcoflow skill does the whole path for you: session, project,
+configuration, guide, the chat in the app and the summary.
 
 ```bash
 npx skills add supcoflow/skills
 ```
 
-Y en el asistente: `/supcoflow go`. Las decisiones sobre los datos de tus usuarios y qué pasa con cada
-problema te las pregunta siempre; no sube nada a GitHub.
+And in the assistant: `/supcoflow go`. It always asks you about your users' data and what happens with each problem;
+it doesn't push anything to GitHub.
 
-## El contrato
+## The contract
 
-Pensado para que lo lea un programa, no sólo una persona:
+Made to be read by a program, not only by a person:
 
-- **`--json`**: el resultado sale por stdout en **una línea** de JSON; los avisos van por stderr.
-  Los errores también: `{"ok":false,"error":"…","message":"…"}`, con su código de salida.
-- **Sin preguntas sin terminal interactiva** (o con `--json`): si falta un dato, sale 3 diciendo qué
-  flag usar. `supcoflow login` sin terminal sale 3 y te indica el camino en dos pasos.
-- **`--dry-run`** donde se puede simular (`login`, `login --start`, `logout`, `repo conectar --start`,
-  `proyecto crear`, `guia revisar`, `guia publicar`, `guia usar`, `instalacion anotar`). `login --wait
-  --dry-run` sale 3: sondear consume el código y no hay cómo simularlo.
+- **`--json`**: the result goes out on stdout as **one line** of JSON; warnings go to stderr. Errors too:
+  `{"ok":false,"error":"…","message":"…"}`, with their exit code. The `error` codes are stable identifiers (some are in
+  Spanish, like `falta_guia`); the `message` of the engine's answers is printed as it arrives.
+- **No questions without an interactive terminal** (or with `--json`): if something is missing, it exits 3 saying which
+  flag to use. `supcoflow login` without a terminal exits 3 and points you to the two-step path.
+- **`--dry-run`** wherever it can be simulated (`login`, `login --start`, `logout`, `repo connect --start`,
+  `project create`, `guide check`, `guide publish`, `guide use`, `install record`, `test`). `login --wait --dry-run`
+  exits 3: polling consumes the code and there is no way to simulate it.
 
-| Código | Quiere decir |
+| Code | It means |
 |---|---|
 | 0 | ok |
-| 1 | inesperado |
-| 2 | falta login |
-| 3 | entrada inválida |
-| 4 | hace falta una persona |
-| 5 | esperando a una persona: volvé a llamar |
-| 6 | tope alcanzado |
-
-## Dónde queda la clave
-
-- En el **llavero del sistema** (Keychain en macOS, Secret Service con `secret-tool` en Linux).
-- Si no hay llavero, en `~/.config/supcoflow/credenciales.json` (o `$XDG_CONFIG_HOME/supcoflow/…`)
-  con permisos `0600`, y la terminal te avisa.
-- **Nunca dentro de un repo de git**: si ese archivo cayera dentro de uno (un `HOME` que es un repo
-  de dotfiles, por ejemplo), no guarda nada y te pide usar el llavero o `SUPCOFLOW_TOKEN`.
-- **`SUPCOFLOW_TOKEN`** tiene prioridad sobre lo guardado: sirve para CI y para la nube.
-- La clave nunca sale en un log ni en una salida `--json`.
-- `proyecto crear` guarda su clave de idempotencia (no es un secreto: sólo evita crear dos veces si se
-  pierde la respuesta) en `idempotencia.json`, al lado de las credenciales y con los mismos permisos.
-
-Cuando iniciás sesión de nuevo, la clave anterior se revoca recién cuando la nueva quedó guardada; si
-no se pudo revocar, queda anotada y se reintenta en el próximo `login` o `logout`.
-
-## La API es fija
-
-La terminal habla siempre con `https://app.supcoflow.dev`. Ningún archivo del repo puede cambiar
-eso, así que clonar un repo ajeno y correr `supcoflow` no manda tu clave a otro servidor. Para
-desarrollo, sólo la variable de entorno `SUPCOFLOW_API_URL` la mueve (`https`, o `http` contra
-`localhost`), y lo guardado queda atado a la API que lo emitió: una clave de un motor local nunca
-viaja a producción.
+| 1 | unexpected |
+| 2 | login needed |
+| 3 | invalid input |
+| 4 | a person is needed |
+| 5 | waiting for a person: call again |
+| 6 | limit reached |
+
+## Where the key is kept
+
+- In the **system keychain** (Keychain on macOS, Secret Service with `secret-tool` on Linux).
+- If there is no keychain, in `~/.config/supcoflow/credenciales.json` (or `$XDG_CONFIG_HOME/supcoflow/…`) with `0600`
+  permissions, and the terminal warns you.
+- **Never inside a git repo**: if that file would land inside one (a `HOME` that is a dotfiles repo, for example), it
+  saves nothing and asks you to use the keychain or `SUPCOFLOW_TOKEN`.
+- **`SUPCOFLOW_TOKEN`** takes priority over what is saved: it is for CI and the cloud.
+- The key never appears in a log or in a `--json` output.
+- `project create` keeps its idempotency key (it isn't a secret: it only avoids creating twice if the answer is lost)
+  in `idempotencia.json`, next to the credentials and with the same permissions.
+
+When you sign in again, the previous key is revoked only after the new one is saved; if it couldn't be revoked, it is
+noted down and retried on the next `login` or `logout`.
+
+## The API is fixed
+
+The terminal always talks to `https://app.supcoflow.dev`. No file in the repo can change that, so cloning someone
+else's repo and running `supcoflow` doesn't send your key to another server. For development, only the
+`SUPCOFLOW_API_URL` environment variable moves it (`https`, or `http` against `localhost`), and what is saved stays
+tied to the API that issued it: a key from a local engine never travels to production.

package/dist/alias.js

@@ -0,0 +1,60 @@
+// Los nombres que la terminal tenía hasta la 0.7.0 (castellano). Siguen funcionando como alias, pero no salen en
+// `describe` ni en la ayuda: el nombre canónico es el inglés. Todo el castellano de nombres vive acá, en un
+// solo archivo, para que la alarma de textos (`test/textos-en-ingles.test.ts`) pueda dejarlo afuera.
+// El comando viejo (completo, de una o dos palabras) → el canónico.
+export const COMANDOS_VIEJOS = {
+    "quien-soy": "whoami",
+    describir: "describe",
+    "repo conectar": "repo connect",
+    "proyecto crear": "project create",
+    "proyecto ver": "project show",
+    catalogo: "catalog",
+    configuracion: "config",
+    "chat prender": "chat on",
+    "chat apagar": "chat off",
+    "chat marca": "chat brand",
+    "sitios agregar": "sites add",
+    "sitios quitar": "sites remove",
+    "datos fijar": "data set",
+    "politica fijar": "policy set",
+    "claves crear": "keys create",
+    "claves listar": "keys list",
+    "claves revocar": "keys revoke",
+    "guia revisar": "guide check",
+    "guia publicar": "guide publish",
+    "guia ver": "guide show",
+    "guia usar": "guide use",
+    "instalacion anotar": "install record",
+    diagnosticar: "diagnose",
+    probar: "test",
+};
+// El flag viejo (sin los guiones) → el canónico.
+export const FLAGS_VIEJOS = {
+    "autorizo-gasto": "authorize-spend",
+    "desde-github": "from-github",
+    permitir: "allow",
+    modo: "mode",
+    mensaje: "message",
+    prueba: "test-id",
+    sitio: "site",
+    titulo: "title",
+    saludo: "greeting",
+    tema: "theme",
+    archivo: "file",
+    nombre: "name",
+    "guardar-en": "save-to",
+    origen: "source",
+};
+// Los valores viejos de los flags con valores fijos → el canónico. A la API siempre viaja el valor de la API
+// (`relevar`, `guardar`, `agente`, `nada`…): cada comando traduce el que recibe.
+export const POLITICA_VIEJA = { relevar: "investigate", guardar: "save" };
+export const ORIGEN_VIEJO = { repo: "repo", agente: "agent" };
+export const PERMITIDOS_VIEJOS = {
+    usuario_id: "user_id",
+    usuario_rol: "user_role",
+    pagina_y_navegador: "page_and_browser",
+    capturas: "screenshots",
+    elementos: "elements",
+    nada: "nothing",
+};
+export const PREFIJO_VIEJO_DE_ATRIBUTO = "atributo:";