supcoflow 0.3.0 → 0.6.0

package/README.md

@@ -4,7 +4,7 @@ La terminal de [Supcoflow](https://app.supcoflow.dev): iniciar sesión y manejar
 desde la consola, o desde un asistente de código que corre comandos por vos.
 
 Trae iniciar y cerrar sesión, ver con qué cuenta estás, conectar el repo con la App de GitHub,
-crear su proyecto y configurar el chat.
+crear su proyecto, configurar el chat y ponerlo en la app.
 
 ## Instalar
 
@@ -26,6 +26,12 @@ npx supcoflow login
 | `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
@@ -68,7 +74,7 @@ los que escriben aceptan `--dry-run`.
 |---|---|
 | `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 (sin skill aprobada, prender sale 4). |
+| `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. |
@@ -77,6 +83,77 @@ los que escriben aceptan `--dry-run`.
 | `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`:
+
+```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.
+```
+
+- 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.
+
+```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.
+
 ## El contrato
 
 Pensado para que lo lea un programa, no sólo una persona:
@@ -86,7 +163,7 @@ Pensado para que lo lea un programa, no sólo una persona:
 - **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`). `login --wait
+  `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.
 
 | Código | Quiere decir |

package/dist/api.js

@@ -21,9 +21,9 @@ export function urlDeLaApi(env) {
         return new URL(u.origin);
     throw invalida();
 }
-// A mano a propósito: tiene que coincidir con package.json (0.3.0); sólo identifica a la terminal
+// A mano a propósito: tiene que coincidir con package.json (0.6.0); sólo identifica a la terminal
 // en los logs del motor, no decide nada.
-const VERSION = "0.3.0";
+const VERSION = "0.6.0";
 const PLAZO_POR_DEFECTO_MS = 15_000;
 // Los dos POST que crean algo: detrás, el motor acuña con Vercel Connect y le pregunta a GitHub varias
 // veces (instalación, repos, comandos, rama). Con 15 s una respuesta lenta pero buena se cortaba y
@@ -293,3 +293,47 @@ export async function esClaveDeConsultaDelProyecto(api, clave, proyectoId, f) {
         throw inesperada(r.status);
     return r.cuerpo.via === "clave_de_consulta" && r.cuerpo.proyecto === proyectoId;
 }
+// ---- La guía (bloque 5) ----
+// Devuelven la respuesta entera: qué significa cada 409/422 lo decide el comando (`guia_no_subida` es
+// un código de salida propio; `guia_mal_armada` lleva la lista de errores por línea).
+const rutaDeLaGuia = (proyectoId) => `/api/proyectos/${encodeURIComponent(proyectoId)}/guia`;
+export function revisarGuia(api, clave, proyectoId, contenido, f) {
+    return conClave(api, clave, `${rutaDeLaGuia(proyectoId)}/revisar`, { method: "POST", headers: JSON_BODY, body: JSON.stringify({ contenido }) }, f);
+}
+export function publicarGuia(api, clave, proyectoId, cuerpo, f) {
+    // La vía de GitHub acuña con Connect y le pregunta a GitHub por la rama: el mismo plazo que las altas (la directa no
+    // llama a GitHub, pero comparte el plazo para no tener dos reglas).
+    return conClave(api, clave, `${rutaDeLaGuia(proyectoId)}/publicar`, { method: "POST", headers: JSON_BODY, body: JSON.stringify(cuerpo) }, f, PLAZO_DE_ALTA_MS);
+}
+// Siempre con `comprobar=1`: `guia ver` quiere el `al_dia` de la rama; el motor lo ignora si el origen no es el repo.
+export function leerGuia(api, clave, proyectoId, f) {
+    return conClave(api, clave, `${rutaDeLaGuia(proyectoId)}?comprobar=1`, { method: "GET" }, f, PLAZO_DE_ALTA_MS);
+}
+export function elegirOrigen(api, clave, proyectoId, origen, f) {
+    return conClave(api, clave, `${rutaDeLaGuia(proyectoId)}/origen`, { method: "POST", headers: JSON_BODY, body: JSON.stringify({ origen }) }, f);
+}
+// Se valida campo a campo: lo que se le pasa a la persona (y de ahí a un archivo de su app) no puede
+// ser algo a medias. `contenido` se guarda tal cual, sin tocarlo: los ids ya vienen puestos por el motor.
+function aWidget(v, status) {
+    const n = (typeof v.nextjs === "object" && v.nextjs !== null ? v.nextjs : {});
+    const s = (typeof v.script === "object" && v.script !== null ? v.script : {});
+    const [tenantId, projectId, backendUrl, version, instalar, csp] = [v.tenant_id, v.project_id, v.backend_url, v.version, v.instalar, v.csp].map(texto);
+    const [archivo, contenido, uso] = [n.archivo_sugerido, n.contenido, n.uso].map(texto);
+    const linea = texto(s.linea);
+    if (!tenantId || !projectId || !backendUrl || !version || !instalar || !csp || v.paquete !== "@supcoflow/chat"
+        || (n.estado !== "probando" && n.estado !== "soportado") || !archivo || !contenido || !uso
+        || s.estado !== "disponible_sin_soporte" || !linea)
+        throw inesperada(status);
+    return {
+        tenant_id: tenantId, project_id: projectId, backend_url: backendUrl, paquete: "@supcoflow/chat", version, instalar,
+        nextjs: { estado: n.estado, archivo_sugerido: archivo, contenido, uso },
+        script: { estado: "disponible_sin_soporte", linea },
+        csp,
+    };
+}
+export async function leerWidget(api, clave, proyectoId, f) {
+    const r = await conClave(api, clave, `/api/proyectos/${encodeURIComponent(proyectoId)}/widget`, { method: "GET" }, f);
+    if (r.status !== 200)
+        throw rechazada(r);
+    return aWidget(r.cuerpo, r.status);
+}

package/dist/argumentos.js

@@ -4,11 +4,13 @@ export const COMANDOS_COMPUESTOS = [
     "repo conectar", "proyecto crear", "proyecto ver",
     "chat prender", "chat apagar", "chat marca", "chat logo", "sitios agregar", "sitios quitar",
     "datos fijar", "politica fijar", "claves crear", "claves listar", "claves revocar",
+    "guia revisar", "guia publicar", "guia ver", "guia usar",
+    "instalacion anotar",
 ];
 // Sólo estas primeras palabras admiten una segunda: cualquier otro par sigue siendo «de más».
 const PRIMERAS_PALABRAS = new Set(COMANDOS_COMPUESTOS.map((c) => c.split(" ")[0]));
 const FLAGS_CON_VALOR = [
-    "repo", "install", "test", "sitio", "titulo", "saludo", "archivo", "permitir", "modo", "nombre", "guardar-en", "id",
+    "repo", "install", "test", "sitio", "titulo", "saludo", "archivo", "permitir", "modo", "nombre", "guardar-en", "id", "origen", "skill", "app",
 ];
 // strict: un flag mal escrito (`--estart`) no se ignora en silencio: un asistente creería que
 // pidió algo que no pidió.
@@ -37,6 +39,10 @@ export function leerArgumentos(argv) {
                 nombre: { type: "string" },
                 "guardar-en": { type: "string" },
                 id: { type: "string" },
+                origen: { type: "string" },
+                "desde-github": { type: "boolean" },
+                skill: { type: "string" },
+                app: { type: "string" },
                 tema: { type: "string", multiple: true },
             },
             tokens: true,
@@ -92,6 +98,10 @@ export function leerArgumentos(argv) {
             nombre: v.nombre ?? null,
             guardarEn: v["guardar-en"] ?? null,
             id: v.id ?? null,
+            origen: v.origen ?? null,
+            desdeGithub: v["desde-github"] === true,
+            skill: v.skill ?? null,
+            app: v.app ?? null,
             tema: v.tema ?? [],
         },
     };

package/dist/cli.js

@@ -6,6 +6,8 @@ import { revocarPropia } from "./api.js";
 import { leerArgumentos } from "./argumentos.js";
 import { clavesCrear, clavesListar, clavesRevocar } from "./comandos/claves.js";
 import { chatLogo, chatMarca, chatPrenderApagar, comandoConfiguracion, sitios } from "./comandos/configurar.js";
+import { guiaPublicar, guiaRevisar, guiaUsar, guiaVer } from "./comandos/guia.js";
+import { instalacionAnotar } from "./comandos/instalacion.js";
 import { comandoCatalogo, datosFijar, politicaFijar } from "./comandos/datos-y-politica.js";
 import { ayuda, comandoDescribir, DESCRIPCION } from "./comandos/describir.js";
 import { loginInteractivo, loginStart, loginWait } from "./comandos/login.js";
@@ -13,6 +15,7 @@ import { comandoLogout } from "./comandos/logout.js";
 import { proyectoCrear, proyectoVer } from "./comandos/proyecto.js";
 import { comandoQuienSoy } from "./comandos/quien-soy.js";
 import { repoConectarInteractivo, repoConectarStart, repoConectarWait } from "./comandos/repo-conectar.js";
+import { widget } from "./comandos/widget.js";
 import { emitir, FalloDeLaTerminal, resultadoDeFallo, SALIDA } from "./contrato.js";
 import { entornoReal } from "./entorno.js";
 import { flagQueNoAplica } from "./flags-por-comando.js";
@@ -36,7 +39,8 @@ async function correr(argv) {
             start: flags.start, wait: flags.wait, repo: flags.repo !== null, install: flags.install !== null, test: flags.test !== null,
             sitio: flags.sitio !== null, titulo: flags.titulo !== null, saludo: flags.saludo !== null, tema: flags.tema.length > 0,
             archivo: flags.archivo !== null, permitir: flags.permitir !== null, modo: flags.modo !== null,
-            nombre: flags.nombre !== null, guardarEn: flags.guardarEn !== null, id: flags.id !== null,
+            nombre: flags.nombre !== null, guardarEn: flags.guardarEn !== null, id: flags.id !== null, origen: flags.origen !== null, desdeGithub: flags.desdeGithub,
+            skill: flags.skill !== null, app: flags.app !== null,
         };
         const noAplica = flagQueNoAplica(comando, Object.keys(presentes).filter((k) => presentes[k]));
         if (noAplica !== null)
@@ -114,6 +118,18 @@ async function correr(argv) {
                 return { r: await clavesListar(e.claves, flags), json };
             case "claves revocar":
                 return { r: await clavesRevocar(e.claves, flags), json };
+            case "guia revisar":
+                return { r: await guiaRevisar(e.guia, flags), json };
+            case "guia publicar":
+                return { r: await guiaPublicar(e.guia, flags), json };
+            case "guia ver":
+                return { r: await guiaVer(e.guia, flags), json };
+            case "guia usar":
+                return { r: await guiaUsar(e.guia, flags), json };
+            case "widget":
+                return { r: await widget(e.widget, flags), json };
+            case "instalacion anotar":
+                return { r: await instalacionAnotar(e.instalacion, flags), json };
         }
         throw new Error(`comando sin despacho: ${comando}`);
     }

package/dist/comandos/describir.js

@@ -3,7 +3,7 @@
 // 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.3.0";
+const VERSION = "0.6.0";
 export const DESCRIPCION = {
     version: VERSION,
     comandos: [
@@ -89,7 +89,7 @@ export const DESCRIPCION = {
         },
         {
             nombre: "chat prender",
-            resumen: "Prende el chat de soporte del proyecto. Sin skill aprobada hace falta una persona (sale 4).",
+            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"],
             codigos: [0, 1, 2, 3, 4],
@@ -182,17 +182,65 @@ export const DESCRIPCION = {
             ejemplos: ["supcoflow claves revocar --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"],
+            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"],
+            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"],
+            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"],
+            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"],
+            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.",
+            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",
+                "--json",
+            ],
+            ejemplos: ["supcoflow instalacion anotar --skill 0.1.0 --app web --json"],
+            codigos: [0, 1, 2, 3, 4],
+        },
     ],
     flags_globales: ["--json: el resultado en una línea de JSON por stdout; los avisos van por stderr", "--help, -h: la ayuda con ejemplos"],
     facultades: [
         {
             nombre: "consultar",
-            incluye: "Identidad y equipo, proyectos, configuración, casos, issues, runs, costos, estado de la instalación",
+            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)",
             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, crear y revocar claves de consulta, perfiles de los agentes",
+            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",
             con_api_key: true,
         },
         { nombre: "probar", incluye: "La prueba hasta el issue (gasta, dentro de los topes)", con_api_key: true },

package/dist/comandos/guia.js

@@ -0,0 +1,244 @@
+// src/comandos/guia.ts
+// `guia revisar|publicar|ver|usar` (bloque 5): la guía del producto que vive en el repo del cliente
+// (`.supcoflow/guia.md`). La terminal NO decide qué es una guía buena —eso lo decide el parser del motor—;
+// lee el archivo, manda UN pedido y traduce la respuesta a los códigos de salida del contrato.
+import path from "node:path";
+import { resultadoDeFallo, SALIDA, taparSecretos } from "../contrato.js";
+import { huellaDeGuia, MAX_BYTES_DE_LA_GUIA, RUTA_DE_LA_GUIA } from "../guia.js";
+import { repoPedido } from "../repo-local.js";
+import { desenlace, fallo, rutaDe } from "./configurar.js";
+import { proyectoDelRepo } from "./proyecto-del-repo.js";
+// Texto que viene del motor (o del repo, vía el motor) y sale a la terminal de una persona: sin secretos y sin
+// caracteres de control (C0, DEL, C1), que un ESC movería el cursor. Texto y JSON salen del mismo texto ya limpio.
+// Primero se quita el control y recién después se tapan los secretos: al revés, una clave partida por un
+// control (U+0085, por ejemplo) quedaba entera al quitarlo y se imprimía sin tapar.
+const limpio = (t) => taparSecretos(t.replace(/[\u0000-\u001f\u007f-\u009f]/g, ""));
+const cadena = (v) => (typeof v === "string" ? limpio(v) : "");
+const corto = (commit) => cadena(commit).slice(0, 7);
+const secciones = (n) => (typeof n === "number" ? `${n} ${n === 1 ? "sección" : "secciones"}` : "secciones sin contar");
+const NOMBRE_DEL_ORIGEN = { repo: "la del repo", agente: "la de nuestro agente" };
+// ─── El archivo local ───
+// Se busca en la raíz de ESTE clon, nunca en el cwd: parado en una subcarpeta sigue siendo la guía del repo.
+// Con `--repo` y sin clon de ese repo no hay dónde leerla (publicar lee la rama, pero la huella sale del archivo).
+async function leerLaGuia(d, flags) {
+    let raiz;
+    try {
+        raiz = (await repoPedido({ flagRepo: flags.repo, git: d.git, cwd: d.cwd })).raiz;
+    }
+    catch (e) {
+        return { ok: false, resultado: resultadoDeFallo(e) };
+    }
+    if (raiz === null) {
+        return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "falta_guia", `No tengo el clon de ese repo acá, y la guía se lee de ${RUTA_DE_LA_GUIA}: parate en el clon del repo.`) };
+    }
+    const leido = d.leerArchivoChico(path.join(raiz, RUTA_DE_LA_GUIA), MAX_BYTES_DE_LA_GUIA);
+    if ("error" in leido) {
+        if (leido.error === "no existe")
+            return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "falta_guia", `Falta ${RUTA_DE_LA_GUIA} en el repo: escribila (una sección por pantalla) y volvé a correr.`) };
+        if (leido.error === "es demasiado grande")
+            return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "guia_muy_grande", `${RUTA_DE_LA_GUIA} pasa los ${MAX_BYTES_DE_LA_GUIA / 1024} KB: acortala.`) };
+        return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "guia_ilegible", `No leo ${RUTA_DE_LA_GUIA}: ${limpio(leido.error)}.`) };
+    }
+    try {
+        // ignoreBOM: el BOM se CONSERVA en el texto; quitarlo es regla de la huella (`huellaDeGuia`), no de la lectura.
+        // fatal: un byte inválido no se reemplaza en silencio, porque la huella de GitHub no coincidiría nunca.
+        return { ok: true, raiz, texto: new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(leido.bytes) };
+    }
+    catch {
+        return { ok: false, resultado: fallo(SALIDA.entradaInvalida, "guia_ilegible", `${RUTA_DE_LA_GUIA} no es UTF-8 válido.`) };
+    }
+}
+// ─── El desenlace propio de la guía, encima del de configurar ───
+function desenlaceDeGuia(r, ok) {
+    const c = r.cuerpo;
+    // 2xx, 401, 5xx y cuerpos raros los resuelve el de configurar. Ojo: la terminal no distingue 500
+    // connect_no_disponible de 502 github_no_disponible (ambos llegan como falla del servicio): los dos son 1.
+    if (r.status < 400 || r.status === 401 || r.status >= 500 || typeof c !== "object" || c === null)
+        return desenlace(r, ok);
+    const error = typeof c.error === "string" ? c.error : "rechazado";
+    const message = limpio(typeof c.message === "string" ? c.message : `El motor rechazó el pedido (${r.status}).`);
+    const con = (codigo, extra = {}, texto = message) => ({ codigo, json: { ok: false, error, message: taparSecretos(message), ...extra }, texto });
+    switch (error) {
+        case "guia_no_subida":
+        case "guia_distinta": {
+            const rama = cadena(c.rama), commit = cadena(c.commit);
+            const donde = rama !== "" ? ` (rama ${rama}${commit !== "" ? `, commit ${corto(commit)}` : ""})` : "";
+            const que = error === "guia_no_subida" ? "La guía no está en la rama principal del repo" : "La guía de la rama principal es otra, no la de tu archivo";
+            return con(SALIDA.esperandoAUnaPersona, { rama: c.rama ?? null, commit: c.commit ?? null }, `${que}${donde}: subí la guía a la rama principal y volvé a correr.`);
+        }
+        case "instalacion_ausente":
+        case "repo_fuera_de_alcance":
+        case "sin_guia_del_agente":
+            return con(SALIDA.haceFaltaUnaPersona);
+        case "guia_mal_armada": {
+            const errores = Array.isArray(c.errores) ? c.errores : [];
+            const lineas = errores.map((e) => {
+                const x = (e ?? {});
+                return `línea ${typeof x.linea === "number" ? x.linea : "?"}: ${cadena(x.motivo)}`;
+            });
+            return con(SALIDA.entradaInvalida, { errores: errores.map((e) => { const x = (e ?? {}); return { linea: x.linea ?? null, motivo: taparSecretos(typeof x.motivo === "string" ? x.motivo : "") }; }) }, [`${RUTA_DE_LA_GUIA} está mal armada:`, ...lineas].join("\n"));
+        }
+        default:
+            return desenlace(r, ok);
+    }
+}
+export async function guiaRevisar(d, flags) {
+    const g = await leerLaGuia(d, flags);
+    if (!g.ok)
+        return g.resultado;
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    if (flags.dryRun) {
+        const haria = `POST ${rutaDe(p.proyecto, "/guia/revisar")} (${new TextEncoder().encode(g.texto).length} bytes)`;
+        return { codigo: SALIDA.ok, json: { ok: true, dry_run: true, haria }, texto: `Con --dry-run no hago nada; sin él: ${haria}.` };
+    }
+    try {
+        return desenlaceDeGuia(await d.revisar(d.api, p.clave, p.proyecto.id, g.texto, d.fetch), (c) => ({
+            codigo: SALIDA.ok, json: { ok: true, secciones: c.secciones ?? null }, texto: `La guía está bien armada: ${secciones(c.secciones)}.`,
+        }));
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+}
+// Commit y rama que la terminal DECLARA: son del clon donde está el archivo, no verificados contra GitHub. Cualquier
+// falla (sin git, sin commits, HEAD suelto, plazo vencido) devuelve vacío: declarar es un extra que nunca bloquea la
+// subida ni pregunta nada, y lo que git imprima no sale a la terminal.
+async function declarado(d, raiz) {
+    const leer = async (args) => {
+        try {
+            const r = await d.gitDeclarado(args, raiz);
+            return r.codigo === 0 ? r.stdout.trim() : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const commit = await leer(["rev-parse", "HEAD"]);
+    // Sin un commit de 40 hex no se manda ni la rama: una rama sin commit no dice de dónde salió la guía.
+    if (commit === null || !/^[0-9a-f]{40}$/.test(commit))
+        return {};
+    const rama = await leer(["rev-parse", "--abbrev-ref", "HEAD"]);
+    // «HEAD» a secas es la cabeza suelta: no es una rama.
+    return rama !== null && rama !== "" && rama !== "HEAD" ? { commit, rama } : { commit };
+}
+export async function guiaPublicar(d, flags) {
+    const g = await leerLaGuia(d, flags);
+    if (!g.ok)
+        return g.resultado;
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    const github = flags.desdeGithub === true;
+    // La vía de GitHub manda la huella del archivo local TAL CUAL (con BOM y \r\n: normalizarla es regla de
+    // `huellaDeGuia`). La directa manda el contenido crudo y el motor calcula la huella: la terminal no la necesita.
+    const huella = github ? huellaDeGuia(g.texto) : null;
+    const decl = github ? {} : await declarado(d, g.raiz);
+    const cuerpo = huella !== null ? { huella } : { contenido: g.texto, ...decl };
+    const cuando = decl.commit ? `commit ${decl.commit.slice(0, 7)}${decl.rama ? ` de ${cadena(decl.rama)}` : ""} declarado` : "sin commit";
+    // El JSON del dry-run pasa por la misma limpieza que el texto (control primero, secretos después): la rama la
+    // decide quien escribió el clon, y un ESC en ella no debe llegar a la terminal por ninguna de las dos salidas.
+    if (flags.dryRun) {
+        const haria = huella !== null
+            ? `POST ${rutaDe(p.proyecto, "/guia/publicar")} con la huella ${huella.slice(0, 12)}…`
+            : `POST ${rutaDe(p.proyecto, "/guia/publicar")} con el contenido (${new TextEncoder().encode(g.texto).length} bytes), ${cuando}`;
+        const json = huella !== null ? { ok: true, dry_run: true, huella, haria } : { ok: true, dry_run: true, commit: decl.commit ? cadena(decl.commit) : null, rama: decl.rama ? cadena(decl.rama) : null, haria };
+        return { codigo: SALIDA.ok, json, texto: `Con --dry-run no hago nada; sin él: ${haria}.` };
+    }
+    try {
+        return desenlaceDeGuia(await d.publicar(d.api, p.clave, p.proyecto.id, cuerpo, d.fetch), (c) => {
+            const guia = (c.guia ?? {});
+            const ya = c.ya_publicada === true;
+            const rem = c.reemplaza;
+            const reemplaza = !ya && rem && rem.origen === "agente" && typeof rem.version === "number" ? ` (reemplaza a la de nuestro agente v${rem.version})` : "";
+            const json = { ok: true, guia: c.guia ?? null, ya_publicada: ya, reemplaza: c.reemplaza ?? null };
+            if (github) {
+                const base = `commit ${corto(guia.commit)} de ${cadena(guia.rama)}, ${secciones(guia.secciones)}`;
+                // Republicar re-activa la guía del repo aunque antes rigiera la de nuestro agente: «sigue siendo» mentiría en ese caso.
+                const texto = ya ? `Ya estaba publicada: ${base}. Quedó como guía activa.` : `Guía publicada: ${base}. Es la guía activa${reemplaza}.`;
+                return { codigo: SALIDA.ok, json, texto };
+            }
+            // El commit se muestra como lo que es: lo que la terminal dijo, no lo que GitHub confirmó.
+            const origen = decl.commit ? `commit ${decl.commit.slice(0, 7)} declarado por la terminal (no verificado en GitHub)` : "sin commit";
+            const texto = ya
+                ? `Ya estaba subida: ${secciones(guia.secciones)}. Quedó como guía activa; ${origen}.`
+                : `Guía subida: ${secciones(guia.secciones)}. Es la guía activa${reemplaza}; ${origen}.`;
+            return { codigo: SALIDA.ok, json: { ...json, commit_declarado: decl.commit ?? null }, texto };
+        });
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+}
+export async function guiaVer(d, flags) {
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    try {
+        return desenlaceDeGuia(await d.ver(d.api, p.clave, p.proyecto.id, d.fetch), (c) => {
+            const guia = c.guia;
+            const otra = c.otra;
+            const rama = c.rama;
+            const alDia = rama && typeof rama.al_dia === "boolean" ? rama.al_dia : null;
+            const json = { ok: true, guia: guia ?? null, otra: otra ?? null, al_dia: alDia, rama: rama ?? null };
+            if (!guia)
+                return { codigo: SALIDA.ok, json, texto: "Este proyecto no tiene guía activa: `supcoflow guia publicar` sube la del repo." };
+            const lineas = [];
+            if (guia.origen === "repo") {
+                lineas.push(`Guía activa: ${NOMBRE_DEL_ORIGEN.repo} (versión ${guia.version}, ${secciones(guia.secciones)}).`);
+                if (guia.procedencia === "terminal") {
+                    // Subida desde la terminal: el motor NO comparó nada contra GitHub a propósito (al_dia null), así que "no pude
+                    // comprobar la rama" sería falso. Commit y rama son lo que declaró quien subió; el id crudo de quien publicó
+                    // (usr_…) no le dice nada a una persona y la terminal no resuelve nombres: queda sólo en el JSON.
+                    const commit = cadena(guia.commit), rama = cadena(guia.rama);
+                    const partes = [cadena(guia.repo), rama !== "" ? `rama ${rama}` : "", commit !== "" ? `commit ${corto(commit)} (declarado)` : "sin commit declarado"].filter((x) => x !== "");
+                    lineas.push(`Procedencia: ${partes.join(", ")}.`);
+                    lineas.push("Subida desde la terminal; el commit es declarado, no verificado en GitHub.");
+                }
+                else {
+                    lineas.push(`Procedencia: ${cadena(guia.repo)}, rama ${cadena(guia.rama)}, commit ${corto(guia.commit)}, publicada por ${cadena(guia.publicada_por)}.`);
+                    if (alDia === true)
+                        lineas.push("Está al día con la rama.");
+                    else if (alDia === false)
+                        lineas.push("En la rama hay otra versión: corré `supcoflow guia publicar`.");
+                    else
+                        lineas.push("No pude comprobar la rama ahora.");
+                }
+            }
+            else {
+                lineas.push(`Guía activa: ${NOMBRE_DEL_ORIGEN.agente} (v${guia.version}, ${secciones(guia.secciones)}).`);
+                lineas.push("Procedencia: la escribió nuestro agente y la aprobó una persona.");
+            }
+            if (otra && (otra.origen === "repo" || otra.origen === "agente")) {
+                lineas.push(`También hay ${NOMBRE_DEL_ORIGEN[otra.origen]} (v${typeof otra.version === "number" ? otra.version : "?"}): \`supcoflow guia usar --origen ${otra.origen}\` la activa.`);
+            }
+            return { codigo: SALIDA.ok, json, texto: lineas.join("\n") };
+        });
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+}
+export async function guiaUsar(d, flags) {
+    const origen = flags.origen ?? null;
+    if (origen === null)
+        return fallo(SALIDA.entradaInvalida, "falta_origen", "Decí cuál: `supcoflow guia usar --origen repo` o `--origen agente`.");
+    if (origen !== "repo" && origen !== "agente")
+        return fallo(SALIDA.entradaInvalida, "origen_invalido", "--origen es `repo` o `agente`.");
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    if (flags.dryRun) {
+        const haria = `POST ${rutaDe(p.proyecto, "/guia/origen")} {origen: ${origen}}`;
+        return { codigo: SALIDA.ok, json: { ok: true, dry_run: true, haria }, texto: `Con --dry-run no hago nada; sin él: ${haria}.` };
+    }
+    try {
+        return desenlaceDeGuia(await d.elegir(d.api, p.clave, p.proyecto.id, origen, d.fetch), (c) => ({
+            codigo: SALIDA.ok, json: { ok: true, guia: c.guia ?? null }, texto: `Ahora la guía activa es ${NOMBRE_DEL_ORIGEN[origen]}.`,
+        }));
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+}

package/dist/comandos/instalacion.js

@@ -0,0 +1,207 @@
+// src/comandos/instalacion.ts
+// `instalacion anotar --skill <versión> [--app <carpeta>] [--dry-run]` (bloque 6): deja en
+// `.supcoflow/instalacion.json` con qué versiones se instaló el chat. Lee la configuración del motor y los
+// `package.json` de la app y del paquete instalado; nunca ejecuta nada del repo (ni `npm ls` ni `node`).
+//
+// La regla de §13 («no pisa archivos ni cambios sin commit») adaptada a un archivo que tiene que poder cambiar
+// (decisión 11): se reescribe sólo si git ya guarda el anterior. El control se hace ANTES de escribir; si la
+// persona edita el archivo entre el control y el `rename`, su cambio se pierde. Esa carrera se acepta: es una
+// persona instalando, y el archivo lo escribe sólo este comando.
+import { realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { resultadoDeFallo, SALIDA, taparSecretos } from "../contrato.js";
+import { armarInstalacion, esSemver, PAQUETE_DEL_CHAT, RUTA_DE_LA_INSTALACION, serializar } from "../instalacion.js";
+import { repoPedido } from "../repo-local.js";
+import { fallo } from "./configurar.js";
+import { proyectoDelRepo } from "./proyecto-del-repo.js";
+export function esCarpetaReal(p) {
+    try {
+        return statSync(p).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+export function rutaRealOEnNada(p) {
+    try {
+        return realpathSync(p);
+    }
+    catch {
+        return null;
+    }
+}
+// Los package.json son chicos; uno de más de 1 MB no es el de una app ni el de un paquete.
+const TOPE_DEL_PACKAGE_JSON = 1024 * 1024;
+const TOPE_DEL_ARCHIVO = 64 * 1024;
+const adentro = (raiz, p) => p === raiz || p.startsWith(raiz + path.sep);
+const limpio = (t) => taparSecretos(t.replace(/[\u0000-\u001f\u007f-\u009f]/g, ""));
+function leerJson(d, p, nombre) {
+    const leido = d.leerArchivoChico(p, TOPE_DEL_PACKAGE_JSON);
+    if ("error" in leido) {
+        if (leido.error === "no existe")
+            return { ok: false, noExiste: true };
+        return { ok: false, noExiste: false, resultado: fallo(SALIDA.inesperado, "paquete_ilegible", `No leo ${nombre}: ${limpio(leido.error)}.`) };
+    }
+    try {
+        return { ok: true, valor: JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(leido.bytes)) };
+    }
+    catch {
+        return { ok: false, noExiste: false, resultado: fallo(SALIDA.inesperado, "paquete_ilegible", `${nombre} no es JSON válido.`) };
+    }
+}
+// Como lo resuelve Node desde la app (revisión externa, hallazgo 4): el primer `node_modules/@supcoflow/chat`
+// subiendo desde <app> hasta la raíz del repo. En un monorepo npm lo deja en la raíz; pnpm enlaza a
+// `node_modules/.pnpm/…`, adentro del repo. Si la ruta real sale del repo, no se lee: lo que hay afuera no es
+// de esta instalación y la terminal no lee fuera del repo por un enlace que el repo eligió.
+function paqueteInstalado(d, raiz, app, avisos) {
+    for (let dir = app;; dir = path.dirname(dir)) {
+        const candidato = path.join(dir, "node_modules", ...PAQUETE_DEL_CHAT.split("/"), "package.json");
+        const real = d.rutaReal(candidato);
+        if (real !== null) {
+            if (!adentro(raiz, real)) {
+                const aviso = `${path.relative(raiz, candidato)} apunta fuera del repo; no lo leo y anoto el chat instalado como null.`;
+                avisos.push(aviso);
+                d.avisar(aviso);
+                return { ok: true, valor: null };
+            }
+            const j = leerJson(d, real, `el package.json de ${PAQUETE_DEL_CHAT} instalado`);
+            if (j.ok)
+                return j;
+            // Existía hace un instante: si ahora no está, tampoco se anota «no está».
+            return { ok: false, resultado: j.noExiste ? fallo(SALIDA.inesperado, "paquete_ilegible", `No leo el package.json de ${PAQUETE_DEL_CHAT} instalado.`) : j.resultado };
+        }
+        if (dir === raiz || path.dirname(dir) === dir)
+            return { ok: true, valor: null };
+    }
+}
+async function estadoDelArchivo(d, raizGit, existe) {
+    const git = async (args) => {
+        const r = await d.git(args, raizGit);
+        if (r.codigo !== 0)
+            throw new Error(`git ${args[0]} falló; no escribo ${RUTA_DE_LA_INSTALACION} sin saber si tiene cambios.`);
+        return r.stdout;
+    };
+    const lineas = (await git(["status", "--porcelain", "--ignored", "--", RUTA_DE_LA_INSTALACION])).split("\n").filter((l) => l.trim() !== "");
+    if (lineas.some((l) => !l.startsWith("??") && !l.startsWith("!!")))
+        return "cambios_sin_commit";
+    if (lineas.length > 0)
+        return "archivo_no_versionado";
+    const versionado = (await git(["ls-files", "--", RUTA_DE_LA_INSTALACION])).trim() !== "";
+    return versionado || !existe ? "escribir" : "archivo_no_versionado";
+}
+// Un diff de líneas (LCS) para el texto: los dos lados son chicos. El anterior lo escribió quien sea, así que
+// sale limpio de control y de secretos; el JSON nunca lo lleva.
+function diff(antes, despues) {
+    if (antes === null)
+        return ["--- (no había archivo)", "+++ " + RUTA_DE_LA_INSTALACION, ...despues.trimEnd().split("\n").map((l) => "+ " + l)].join("\n");
+    const a = antes.replace(/\r\n?/g, "\n").replace(/\n$/, "").split("\n").map(limpio);
+    const b = despues.trimEnd().split("\n");
+    const n = a.length, m = b.length;
+    const lcs = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
+    for (let i = n - 1; i >= 0; i--)
+        for (let j = m - 1; j >= 0; j--)
+            lcs[i][j] = a[i] === b[j] ? lcs[i + 1][j + 1] + 1 : Math.max(lcs[i + 1][j], lcs[i][j + 1]);
+    const lineas = ["--- " + RUTA_DE_LA_INSTALACION + " (antes)", "+++ " + RUTA_DE_LA_INSTALACION];
+    let i = 0, j = 0;
+    while (i < n || j < m) {
+        if (i < n && j < m && a[i] === b[j])
+            lineas.push("  " + a[i++]), j++;
+        else if (j < m && (i === n || lcs[i][j + 1] >= lcs[i + 1][j]))
+            lineas.push("+ " + b[j++]);
+        else
+            lineas.push("- " + a[i++]);
+    }
+    return lineas.join("\n");
+}
+const resumen = (x) => `skill ${x.skill}, terminal ${x.terminal}, chat declarado ${x.chat.declarado ?? "—"} / instalado ${x.chat.instalado ?? "—"}`;
+export async function instalacionAnotar(d, flags) {
+    if (flags.skill === null)
+        return fallo(SALIDA.entradaInvalida, "falta_skill", "Falta la versión de la skill: `supcoflow instalacion anotar --skill 0.1.0`.");
+    if (!esSemver(flags.skill))
+        return fallo(SALIDA.entradaInvalida, "skill_invalida", "--skill va con una versión semver (por ejemplo 0.1.0).");
+    // ─── La raíz y la app, antes de cualquier pedido ───
+    let raizGit;
+    try {
+        raizGit = (await repoPedido({ flagRepo: flags.repo, git: d.git, cwd: d.cwd })).raiz;
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    if (raizGit === null)
+        return fallo(SALIDA.entradaInvalida, "sin_clon", `No tengo el clon de ese repo acá, y ${RUTA_DE_LA_INSTALACION} va en el clon: parate en el clon del repo.`);
+    const raiz = d.rutaReal(raizGit);
+    if (raiz === null)
+        return fallo(SALIDA.inesperado, "inesperado", "No pude resolver la raíz del repo.");
+    // `realpath` DESPUÉS de resolver: un `--app` que es un enlace hacia afuera tiene que quedar afuera (Review Focus 4).
+    const app = d.rutaReal(path.resolve(raiz, flags.app ?? "."));
+    if (app === null)
+        return fallo(SALIDA.entradaInvalida, "app_inexistente", "La carpeta de --app no existe (va relativa a la raíz del repo).");
+    if (!adentro(raiz, app))
+        return fallo(SALIDA.entradaInvalida, "app_fuera_del_repo", "--app tiene que ser una carpeta dentro del repo (relativa a su raíz).");
+    // Un archivo no es una app: sin esto, leer `<archivo>/package.json` daba ENOTDIR y salía `paquete_ilegible`.
+    if (!d.esCarpeta(app))
+        return fallo(SALIDA.entradaInvalida, "app_inexistente", "--app tiene que ser una carpeta (la de la app), no un archivo.");
+    // ─── Proyecto → configuración → package.json de la app → paquete instalado → armar ───
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    let configuracion;
+    try {
+        configuracion = await d.leerConfiguracion(d.api, p.clave, p.proyecto.id);
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    const deLaApp = leerJson(d, path.join(app, "package.json"), "el package.json de la app");
+    if (!deLaApp.ok && !deLaApp.noExiste)
+        return deLaApp.resultado;
+    const avisos = [];
+    const instalado = paqueteInstalado(d, raiz, app, avisos);
+    if (!instalado.ok)
+        return instalado.resultado;
+    let x;
+    try {
+        x = armarInstalacion({ skill: flags.skill, terminal: d.terminal, paqueteDeLaApp: deLaApp.ok ? deLaApp.valor : null, paqueteInstalado: instalado.valor, configuracion });
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    const nuevo = serializar(x);
+    // ─── ¿Se puede escribir? ───
+    const archivo = path.join(raiz, RUTA_DE_LA_INSTALACION);
+    // Una `.supcoflow` que es un enlace hacia afuera: ni se lee (el diff mostraría un archivo de afuera) ni se escribe.
+    const carpeta = d.rutaReal(path.dirname(archivo));
+    if (carpeta !== null && !adentro(raiz, carpeta))
+        return fallo(SALIDA.inesperado, "inesperado", `${path.dirname(RUTA_DE_LA_INSTALACION)} no es una carpeta del repo (¿un enlace?); no escribo ahí.`);
+    const actual = d.leerArchivoChico(archivo, TOPE_DEL_ARCHIVO);
+    const existe = !("error" in actual) || actual.error !== "no existe";
+    const json = { ok: true, ruta: RUTA_DE_LA_INSTALACION, instalacion: x, ...(avisos.length > 0 ? { avisos } : {}) };
+    if ("bytes" in actual && Buffer.from(actual.bytes).equals(Buffer.from(nuevo, "utf8"))) {
+        return { codigo: SALIDA.ok, json: { ...json, ...(flags.dryRun ? { dry_run: true } : {}), sin_cambios: true }, texto: `${RUTA_DE_LA_INSTALACION} ya dice eso (${resumen(x)}); no lo toqué.` };
+    }
+    let estado;
+    try {
+        estado = await estadoDelArchivo(d, raizGit, existe);
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+    if (estado === "cambios_sin_commit") {
+        return fallo(SALIDA.haceFaltaUnaPersona, "cambios_sin_commit", `${RUTA_DE_LA_INSTALACION} tiene cambios sin commit (o se borró sin commit); no lo toqué. Commitealos o descartalos y volvé a correr.`);
+    }
+    if (estado === "archivo_no_versionado") {
+        return fallo(SALIDA.haceFaltaUnaPersona, "archivo_no_versionado", `Ya hay un ${RUTA_DE_LA_INSTALACION} que git no guarda (sin commit o ignorado); no lo pisé. Commitealo o borralo y volvé a correr.`);
+    }
+    const antes = "bytes" in actual ? Buffer.from(actual.bytes).toString("utf8") : null;
+    const cambios = existe && antes === null ? `(el archivo anterior no se lee)\n${diff(null, nuevo)}` : diff(antes, nuevo);
+    if (flags.dryRun) {
+        return { codigo: SALIDA.ok, json: { ...json, dry_run: true, sin_cambios: false }, texto: `Con --dry-run no escribo; sin él anotaría (${resumen(x)}):\n${cambios}` };
+    }
+    try {
+        d.escribir(archivo, nuevo);
+    }
+    catch {
+        return fallo(SALIDA.inesperado, "archivo_no_escrito", `No pude escribir ${RUTA_DE_LA_INSTALACION}. Volvé a correr \`supcoflow instalacion anotar\`.`);
+    }
+    return { codigo: SALIDA.ok, json: { ...json, sin_cambios: false }, texto: `Anoté ${RUTA_DE_LA_INSTALACION} (${resumen(x)}); commitealo cuando quieras.\n${cambios}` };
+}

package/dist/comandos/widget.js

@@ -0,0 +1,32 @@
+import { resultadoDeFallo, SALIDA } from "../contrato.js";
+import { proyectoDelRepo } from "./proyecto-del-repo.js";
+function textoDe(w) {
+    return [
+        "1. Instalá el paquete (con el gestor de la app, la versión exacta):",
+        `   ${w.instalar}`,
+        "",
+        `2. Creá el archivo ${w.nextjs.archivo_sugerido} con este contenido (Next.js, ${w.nextjs.estado}):`,
+        w.nextjs.contenido.trimEnd(),
+        "",
+        "3. Usalo en el layout que cubre las pantallas donde se traban los usuarios:",
+        `   ${w.nextjs.uso}`,
+        "",
+        "4. Política de contenido (CSP): si la app tiene `connect-src`, agregale este origen conservando lo que ya tiene:",
+        `   ${w.csp}`,
+        "",
+        "Alternativa con <script> (disponible, no probada en una app real):",
+        `   ${w.script.linea}`,
+    ].join("\n");
+}
+export async function widget(d, flags) {
+    const p = await proyectoDelRepo(d, flags);
+    if (!p.ok)
+        return p.resultado;
+    try {
+        const w = await d.leerWidget(d.api, p.clave, p.proyecto.id);
+        return { codigo: SALIDA.ok, json: { ok: true, ...w }, texto: textoDe(w) };
+    }
+    catch (e) {
+        return resultadoDeFallo(e);
+    }
+}

package/dist/entorno.js

@@ -5,8 +5,10 @@ import { randomUUID } from "node:crypto";
 import { chmodSync, closeSync, constants, fchmodSync, fstatSync, linkSync, lstatSync, mkdirSync, openSync, readFileSync, readSync, realpathSync, renameSync, rmSync, writeSync, } from "node:fs";
 import { homedir, hostname } from "node:os";
 import { basename, dirname, join } from "node:path";
-import { buscarProyecto, canjear, configurar, crearConexion, crearProyecto, esClaveDeConsultaDelProyecto, leerCatalogo, leerConfiguracion, leerProyecto, listarClaves, pedirCodigo, quienSoy, revocarPropia, subirLogo, ultimaConexion, urlDeLaApi, } from "./api.js";
+import { buscarProyecto, canjear, configurar, leerWidget, crearConexion, crearProyecto, elegirOrigen, esClaveDeConsultaDelProyecto, leerCatalogo, leerConfiguracion, leerGuia, leerProyecto, listarClaves, pedirCodigo, quienSoy, revocarPropia, subirLogo, ultimaConexion, urlDeLaApi, publicarGuia, revisarGuia, } from "./api.js";
 import { crearCandados } from "./candado.js";
+import { esCarpetaReal, rutaRealOEnNada } from "./comandos/instalacion.js";
+import { DESCRIPCION } from "./comandos/describir.js";
 import { almacenDeArchivo } from "./guardado/archivo.js";
 import { crearGuardado } from "./guardado/index.js";
 import { almacenDeLlavero } from "./guardado/llavero.js";
@@ -228,15 +230,20 @@ export const correrReal = (bin, args, stdin, techoMs) => new Promise((resolve) =
     hijo.stdin.end(stdin ?? undefined);
 });
 // `git` con entorno mínimo (sólo PATH): ni GIT_DIR ni GIT_CONFIG del shell desvían la lectura, y
-// SUPCOFLOW_TOKEN no le llega. Un git ausente (ENOENT) es «sin git», no un fallo.
-export const gitReal = (args, cwd) => new Promise((resolve) => {
-    execFile("git", args, { cwd, timeout: 5_000, env: { PATH: process.env.PATH ?? "" } }, (e, stdout) => {
+// SUPCOFLOW_TOKEN no le llega. Un git ausente (ENOENT) es «sin git», no un fallo. El plazo es parámetro para no
+// duplicar la función: lo que git imprima nunca sale a la terminal, sólo el código y el stdout.
+const gitConPlazo = (plazoMs) => (args, cwd) => new Promise((resolve) => {
+    execFile("git", args, { cwd, timeout: plazoMs, env: { PATH: process.env.PATH ?? "" } }, (e, stdout) => {
         if (!e)
             return resolve({ codigo: 0, stdout: String(stdout) });
         const codigo = e.code;
         resolve({ codigo: typeof codigo === "number" ? codigo : null, stdout: "" });
     });
 });
+export const gitReal = gitConPlazo(5_000);
+// El commit y la rama que la terminal DECLARA al subir la guía: 3 segundos (no 5) porque esto es un extra que nunca
+// debe hacer esperar a nadie.
+export const gitRapido = gitConPlazo(3_000);
 // `.supcoflow/proyecto.json` vive DENTRO del repo, y el repo puede ser un clon ajeno: su contenido lo
 // decide quien lo escribió. Por eso ni la carpeta ni el archivo se siguen si son enlaces (uno hacia
 // `~/.ssh/…` haría que la terminal leyera, o escribiera, lo que el repo quiera), y se lee con tope.
@@ -450,11 +457,29 @@ export function entornoReal(env = process.env) {
             leerArchivoChico,
             leerCatalogo: (a, clave) => leerCatalogo(a, clave, fetch),
         },
+        guia: {
+            ...configurarEnElMotor,
+            leerArchivoChico, fetch, gitDeclarado: gitRapido,
+            revisar: revisarGuia, publicar: publicarGuia, ver: leerGuia, elegir: elegirOrigen,
+        },
         claves: {
             ...configurarEnElMotor,
             listarClaves: (a, clave, id) => listarClaves(a, clave, id, fetch),
             esClaveDeConsultaDelProyecto: (a, clave, id) => esClaveDeConsultaDelProyecto(a, clave, id, fetch),
             idempotencia, candados, secretos,
         },
+        widget: {
+            api, guardado, git: gitReal, cwd,
+            buscarProyecto: configurarEnElMotor.buscarProyecto,
+            leerWidget: (a, clave, id) => leerWidget(a, clave, id, fetch),
+        },
+        // La versión que se anota es la de `describir` (pinzada contra package.json por test): una sola fuente
+        // para lo que la terminal dice de sí misma.
+        instalacion: {
+            ...configurarEnElMotor,
+            leerArchivoChico, rutaReal: rutaRealOEnNada, esCarpeta: esCarpetaReal,
+            escribir: archivosDelRepo(avisar).escribir,
+            terminal: DESCRIPCION.version,
+        },
     };
 }

package/dist/flags-por-comando.js

@@ -4,12 +4,13 @@
 const DE_CONFIGURAR_CON_REPO = [
     "configuracion", "chat prender", "chat apagar", "chat marca", "chat logo", "sitios agregar", "sitios quitar",
     "datos fijar", "politica fijar", "claves crear", "claves listar", "claves revocar",
+    "guia revisar", "guia publicar", "guia ver", "guia usar",
 ];
 export const FLAGS_POR_COMANDO = [
     { flags: ["start", "wait"], comandos: ["login", "repo conectar"], texto: "--start y --wait son de `supcoflow login` y `supcoflow repo conectar`." },
     {
-        flags: ["repo"], comandos: ["repo conectar", "proyecto crear", "proyecto ver", ...DE_CONFIGURAR_CON_REPO],
-        texto: "--repo es de `supcoflow repo conectar`, `proyecto crear|ver` y los comandos que configuran un proyecto (no de `catalogo`).",
+        flags: ["repo"], comandos: ["repo conectar", "proyecto crear", "proyecto ver", ...DE_CONFIGURAR_CON_REPO, "widget", "instalacion anotar"],
+        texto: "--repo es de `supcoflow repo conectar`, `proyecto crear|ver`, `widget`, `instalacion anotar` y los comandos que configuran un proyecto (no de `catalogo`).",
     },
     { flags: ["install", "test"], comandos: ["proyecto crear"], texto: "--install y --test son de `supcoflow proyecto crear`." },
     { flags: ["sitio"], comandos: ["sitios agregar", "sitios quitar"], texto: "--sitio es de `supcoflow sitios agregar|quitar`." },
@@ -18,7 +19,10 @@ export const FLAGS_POR_COMANDO = [
     { flags: ["permitir"], comandos: ["datos fijar"], texto: "--permitir es de `supcoflow datos fijar`." },
     { flags: ["modo"], comandos: ["politica fijar"], texto: "--modo es de `supcoflow politica fijar`." },
     { flags: ["nombre", "guardarEn"], comandos: ["claves crear"], texto: "--nombre y --guardar-en son de `supcoflow claves crear`." },
+    { flags: ["origen"], comandos: ["guia usar"], texto: "--origen es de `supcoflow guia usar`." },
+    { flags: ["desdeGithub"], comandos: ["guia publicar"], texto: "--desde-github es de `supcoflow guia publicar`." },
     { flags: ["id"], comandos: ["claves revocar"], texto: "--id es de `supcoflow claves revocar`." },
+    { flags: ["skill", "app"], comandos: ["instalacion anotar"], texto: "--skill y --app son de `supcoflow instalacion anotar`." },
 ];
 /** El mensaje del primer flag presente que el comando no acepta, o null si todo aplica. */
 export function flagQueNoAplica(comando, presentes) {

package/dist/guia.js

@@ -0,0 +1,11 @@
+// La guía del producto que vive en el repo del cliente. Sin dependencias: sólo `node:crypto`.
+import { createHash } from "node:crypto";
+export const RUTA_DE_LA_GUIA = ".supcoflow/guia.md";
+export const MAX_BYTES_DE_LA_GUIA = 64 * 1024;
+// La misma regla que el motor (`src/guia/formato.ts`), copiada a propósito y clavada con los vectores
+// de `test/vectores/huella.json` (idénticos en los dos repos). Se normaliza antes de hashear porque un
+// editor de Windows pone BOM o \r\n, y si las dos puntas hashearan distinto, `guia_distinta` sería eterno.
+export function huellaDeGuia(texto) {
+    const normalizado = texto.replace(/^/, "").replace(/\r\n?/g, "\n");
+    return createHash("sha256").update(normalizado, "utf8").digest("hex");
+}

package/dist/instalacion.js

@@ -0,0 +1,86 @@
+// `.supcoflow/instalacion.json` (bloque 6, decisión 3): con qué versiones se hizo la instalación, anotado en el
+// repo de quien instala. Supcoflow no lo guarda ni lo ve. Puro: recibe lo ya leído y arma el archivo.
+//
+// El archivo queda en el repo y se commitea: un secreto acá se publica con el primer `push`. Por eso se arma con
+// una LISTA CERRADA de campos, cada uno validado por separado; nunca un `...configuracion` (la configuración del
+// motor trae `fijado_por`, `publicada_por`, huellas y lo que el motor agregue mañana: nada de eso es de este archivo).
+import { FalloDeLaTerminal, SALIDA, taparSecretos } from "./contrato.js";
+export const RUTA_DE_LA_INSTALACION = ".supcoflow/instalacion.json";
+export const PAQUETE_DEL_CHAT = "@supcoflow/chat";
+// SemVer 2.0 tal cual, con tope de largo: la versión de la skill la escribe un asistente y queda en el repo.
+const SEMVER = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
+export const esSemver = (s) => s.length <= 64 && SEMVER.test(s);
+const objeto = (v) => (typeof v === "object" && v !== null && !Array.isArray(v) ? v : null);
+const entero = (v) => typeof v === "number" && Number.isInteger(v) && v >= 1;
+const ilegible = (message) => new FalloDeLaTerminal(SALIDA.inesperado, "paquete_ilegible", message);
+const inesperada = (que) => new FalloDeLaTerminal(SALIDA.inesperado, "configuracion_inesperada", `El motor contestó la configuración con ${que} que no entiendo; no anoto nada a medias. Probá de nuevo en un rato.`);
+// Lo declarado en el `package.json` de la app lo escribió quien escribió el repo: puede ser un rango, un alias o
+// cualquier cosa. Se copia tal cual sólo si es texto imprimible y corto; si no, no se adivina (`paquete_ilegible`).
+// `taparSecretos` igual, por si alguien pegó una clave ahí: el archivo nuevo no la repite.
+function declaradoEn(app) {
+    const a = objeto(app);
+    if (a === null)
+        return null;
+    const v = objeto(a.dependencies)?.[PAQUETE_DEL_CHAT] ?? objeto(a.devDependencies)?.[PAQUETE_DEL_CHAT];
+    if (v === undefined || v === null)
+        return null;
+    if (typeof v !== "string" || v.length === 0 || v.length > 200 || !/^[\x20-\x7e]+$/.test(v)) {
+        throw ilegible(`La versión de ${PAQUETE_DEL_CHAT} en el package.json de la app no se entiende; no la anoto.`);
+    }
+    return taparSecretos(v);
+}
+// `null` es «no está instalado». Un archivo que existe pero sin versión válida NO es null: diría que no está.
+function instaladoEn(paquete) {
+    if (paquete === null)
+        return null;
+    const v = objeto(paquete)?.version;
+    if (typeof v !== "string" || !esSemver(v))
+        throw ilegible(`El package.json de ${PAQUETE_DEL_CHAT} instalado no trae una versión que entienda.`);
+    return v;
+}
+function acuerdoDe(c) {
+    if (c.acuerdo === null)
+        return null;
+    const a = objeto(c.acuerdo);
+    // Ilegible es un estado conocido del motor (aplica cerrado), no «sin acuerdo»: anotarlo como null mentiría.
+    if (a?.ilegible === true) {
+        throw new FalloDeLaTerminal(SALIDA.haceFaltaUnaPersona, "acuerdo_ilegible", "El acuerdo de datos está fijado pero no se lee: revisalo en la consola y volvé a correr.");
+    }
+    if (a === null || !entero(a.version))
+        throw inesperada("un acuerdo");
+    return a.version;
+}
+function politicaDe(c) {
+    const modo = objeto(c.politica)?.modo;
+    if (modo !== "relevar" && modo !== "guardar")
+        throw inesperada("una política");
+    return modo;
+}
+function guiaDe(c) {
+    if (c.guia === null)
+        return null;
+    const g = objeto(c.guia);
+    if (g?.origen === "repo") {
+        if (g.procedencia !== "terminal" && g.procedencia !== "github")
+            throw inesperada("una guía");
+        if (g.commit !== null && (typeof g.commit !== "string" || !/^[0-9a-f]{40}$/.test(g.commit)))
+            throw inesperada("una guía");
+        return { origen: "repo", procedencia: g.procedencia, commit: g.commit };
+    }
+    if (g?.origen === "agente" && entero(g.version))
+        return { origen: "agente", version: g.version };
+    throw inesperada("una guía");
+}
+export function armarInstalacion(i) {
+    return {
+        version: 1,
+        skill: i.skill,
+        terminal: i.terminal,
+        chat: { declarado: declaradoEn(i.paqueteDeLaApp), instalado: instaladoEn(i.paqueteInstalado) },
+        configuracion: { acuerdo_version: acuerdoDe(i.configuracion), politica: politicaDe(i.configuracion), guia: guiaDe(i.configuracion) },
+    };
+}
+// El orden de las claves es el de `armarInstalacion`: el mismo estado da los mismos bytes, y eso es `sin_cambios`.
+export function serializar(x) {
+    return JSON.stringify(x, null, 2) + "\n";
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supcoflow",
-  "version": "0.3.0",
+  "version": "0.6.0",
   "description": "La terminal de Supcoflow: iniciar sesión y manejar el chat de soporte desde la consola o un asistente.",
   "type": "module",
   "bin": { "supcoflow": "dist/cli.js" },