supcoflow 0.7.0 → 0.8.1

package/README.md

@@ -1,219 +1,296 @@
 # 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, ponerlo en la app y probar que un problema llega hasta un issue.
+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, starting with who you are: «You're @login in team T; repo O/R; project P (existing)». |
+| `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.1 --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 (including whether this machine can save the test request). |
+| `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.
+
+### When the `origin` isn't a GitHub address
+
+The terminal only recognizes `origin` when its host is exactly `github.com` (`https://github.com/o/r`,
+`git@github.com:o/r.git`, `ssh://git@github.com/o/r`). If yours is an SSH alias (`git@github-work:o/r.git`) or
+another server, it never runs `ssh` or reads your SSH configuration (it could run programs of yours). You tell it
+once, in your own clone, which GitHub repo this is:
 
 ```bash
-# Una persona frente a la 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
+git remote add supcoflow https://github.com/owner/repo.git   # it's never fetched
+```
 
-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
+A remote called `supcoflow` with those same strict forms ties the clone to that repo for every command. If `origin`
+is a GitHub address, `origin` wins. The error says the exact command to run. With `--repo owner/repo`, the commands
+that read or write a file of the clone (`guide check`, `guide publish`, `install record`) only use this clone if it is
+that repo; otherwise they exit 3 saying what the clone is, without asking the engine. (`project create --repo` keeps
+creating or reusing the project; when this clone is not that repo it does so without reading or writing this clone's
+`.supcoflow/proyecto.json`, and when it is that repo it reads and records the file as usual.)
 
-supcoflow quien-soy --json
-supcoflow logout --dry-run         # qué revocaría, sin revocar nada
-```
+### Is this repo the one for this account?
 
-## Configurar
+Every command that acts on the repo's project first checks what it can see, and exits 4 `contexto_incoherente` (with a
+`motivo`) without touching anything when it doesn't add up:
 
-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`.
+- `proyecto_del_clon_distinto`: `.supcoflow/proyecto.json` notes a project your key doesn't see for this repo. Check
+  which account you signed in with (`supcoflow whoami`), or review that old file.
+- `archivo_del_clon_ilegible`: that file exists but can't be read or understood (its content is never printed).
+- `dueno_distinto_del_login` (only when this repo has no project yet, in `project show` and `project create`; `show` stops the walk-through before `repo connect`): the repo's owner on GitHub isn't the GitHub login of your
+  key. It is a *possible* mismatch (the engine compares GitHub's number, and a login can be renamed): sign in to the
+  console with GitHub again, or as the owner. If your key comes from `SUPCOFLOW_TOKEN`, that variable wins over a new
+  login, and the terminal doesn't touch it.
+- `sin_github` (only when this repo has no project yet, in `project show` and `project create`): the account was signed in by email; connecting a repo needs GitHub.
 
-| Comando | Qué hace |
-|---|---|
-| `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`:
+A project that already exists is never blocked for belonging to another person of the team. This doesn't see a project
+of the same repo in another team when the clone doesn't note it.
 
-```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.
-```
+### From zero to a project
 
-- 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`.
+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.
 
-## Poner el chat en la app
+### Examples
 
-`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:
+```bash
+# A person at the terminal
+supcoflow login
 
-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).
+# 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
 
-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.
+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
 
-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.
+supcoflow whoami --json
+supcoflow logout --dry-run         # what it would revoke, without revoking anything
+```
 
-## Probar la instalación
+## Configure
 
-Con el chat puesto, dos comandos dicen si un problema que entra por el chat llega hasta un issue. Los dos
-toman el repo del `origin`, o `--repo owner/repo`.
+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 diagnosticar` | Gratis y sin escribir nada: revisa instalación de GitHub, sitios, chat, guía, política, saldo del mes y pruebas abiertas. Sale 0 si está todo listo, 4 si algo hay que arreglar (con cada punto). |
-| `supcoflow probar` | Sin `--autorizo-gasto` no manda nada: sale 4 con el techo de la prueba, el saldo, el tope y lo comprometido del mes. |
-| `supcoflow probar --autorizo-gasto` | Pide la prueba: el problema entra por la misma puerta que el chat y corre un relevamiento que **gasta** hasta el techo que mostró el motor (con la política `guardar` llega hasta el caso guardado y no gasta). Sale 5 con el id. `--mensaje "…"` usa un texto propio. |
-| `supcoflow probar --wait` | Sigue la última prueba hasta 90 s: 5 mientras corre (volvé a llamarlo), 0 con el issue, 4 si hay que mirarla en la consola (trae el enlace). El cobro se muestra como esté: `pendiente` justo al cerrar, nunca 0. `--prueba prb_…` sigue otra. |
-| `supcoflow probar --dry-run --autorizo-gasto` | Lo que haría (proyecto, techo, saldo, política), sin pedir nada. |
-
-Si la respuesta del motor no llega, el pedido queda guardado en esta máquina (fuera del repo, junto a las
-credenciales): repetir `supcoflow probar --autorizo-gasto` retoma **la misma** prueba en vez de pedir otra.
-Mientras haya un pedido sin confirmar, otro `--mensaje` sale 4 `intento_pendiente`. La prueba va con la clave
-personal de `supcoflow login`; una clave de consulta no puede pedirla. Una sola prueba abierta por proyecto: otra
-sale 4 `prueba_en_curso` con el id de la abierta. El issue de una prueba queda abierto y rotulado como prueba.
+| `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 a `supcoflow` remote, see above), or `--repo owner/repo`
+(with `check` and `publish`, if this clone isn't that repo it exits 3 `falta_guia` saying what the clone is: 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`:
 
-## Con un asistente
+```markdown
+# 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 /
+```
 
-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. It also says, before you authorize anything, whether this machine can save the test request (`maquina: { ok, impedimentos }`) and any request still waiting for confirmation (`intento_pendiente: { techo_usd, politica }`). |
+| `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.
+
+**If your home folder is a git repo.** The request is saved in `~/.config/supcoflow/pruebas.json` (it carries the
+ceiling, the policy and, if you passed one, your `--message`). That is allowed inside a repo only when git itself says
+it ignores the file and doesn't track it: the first time, the terminal creates a `.gitignore` containing `*` in that
+folder (only if there isn't one; it never edits yours), and then asks git (`git check-ignore`) about the file and its
+`.tmp`, for every repo that contains the written or the real path. A file that is already tracked or added to the index
+is refused with the exact `git rm --cached …` to run (the terminal never runs it or deletes anything of yours), and so
+is a missing or failing git. The same goes for every write or delete of `idempotencia.json`. `diagnose` and `test`
+check all this (and permissions, broken links and unreadable files) **before** you authorize, without writing
+anything: «no obstacle found» is a check, not a promise that the disk won't fill up later. The credentials don't use
+this exception: inside a repo they are still refused.
+
+## 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`. (The test request and the idempotency key are
+  the only things with an exception: see «Test the installation».)
+- **`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. Inside a repo it is saved only if git
+  ignores it and doesn't track it; otherwise the terminal says so and goes on without saving it.
+
+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:";