supcoflow 0.8.1 → 0.9.0

package/README.md

@@ -36,8 +36,8 @@ the English ones.
 | `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 install record --skill 0.3.1 --file app/_supcoflow/support-chat.tsx` | Records in `.supcoflow/instalacion.json` which versions the chat was installed with, what was installed (the widget or the app's own interface), which files it lives in and which presentation contract it follows. |
+| `supcoflow diagnose` | Free: how far the installation is (N of 7) 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. |
 
@@ -191,13 +191,61 @@ wrongly copied id leaves the chat invisible without any error). It writes no fil
 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
+### Your own interface (the app builds the chat)
+
+Supcoflow doesn't have to be the one that draws the chat. When the engine also describes the app's **own interface**
+(`interfaz_propia` in `widget --json`; `Own interface` in the text), the code assistant builds the chat with the
+app's own components, icons and styles, and Supcoflow only says what to install and which contract the interface
+must fulfil. **There is no code to paste** in this form:
+
+| Field (`interfaz_propia`) | What it is |
+|---|---|
+| `estado` | `disponible`, or `sin_publicar` when the package version isn't on npm yet. With `sin_publicar` the text doesn't offer the path (it would be an `npm i` that fails): it says «not published yet; use the widget». The JSON still carries everything. |
+| `paquete`, `version`, `instalar` | The package and its exact version, and the install command. |
+| `tenant_id`, `project_id`, `backend_url`, `opciones_del_nucleo` | The ids and the backend, as the engine has them: don't copy them by hand. |
+| `csp` | The Content Security Policy line to add to `connect-src`. |
+| `contrato` (`version`, `archivo`, `documento`) | The presentation contract the interface has to follow: its version, and where the installed package carries it (`contract.json` and `docs/presentation-contract.md`, paths relative to the folder where `npm i` was run), so it can be read offline. |
+| `entradas`, `documentos` | The package entry points (`@supcoflow/chat/core`, `/react`, `/testing`, `/testing/server`) and the docs inside the package. Names and paths, not code. |
+
+The field is additive: an engine that doesn't send it (production, until the engine's T8 ships) gives exactly the
+object it always gave, and the terminal adds nothing. If the engine sends `interfaz_propia` halfway (a field missing,
+an `estado` it doesn't know, a `contrato.version` that isn't a semver, a path outside the package), the terminal ignores
+that whole part, says so on stderr and shows the widget as always: it never shows half of it, and an optional block never
+takes the widget down. Anything else inside `interfaz_propia` that the terminal doesn't know is not passed on.
+
+Then, `supcoflow install record --skill <version> [--app <folder>] [--shape widget|own-interface] [--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.
+and installed, the project configuration and, from version 3 (0.9.0), what the installation is:
+
+- `forma`: `"widget"` or `"interfaz_propia"` (`--shape widget` / `--shape own-interface`), or `null` if not said.
+- `archivos`: the files the chat lives in, relative to the repo root (no `..`, not absolute, not a symlink, up to 20).
+  `--file` can be repeated, in order, and replaces the whole list; the wrapper of the widget is one file, an own
+  interface usually several.
+- `contrato`: the version of the presentation contract the **installed** package carries (its `contract.json`, found the
+  same way as its `package.json`: the closest `node_modules` going up to the repo root, never outside the repo), or `null`
+  if the package has none. A `contract.json` that is there but has no version is an error (`paquete_ilegible`).
+
+Running it again without `--shape` or `--file` keeps the form and the files already recorded; changing `--shape` without
+`--file` leaves `archivos` empty (the wrapper of the widget isn't the own interface, and the other way round). Versions 1 and
+2 are read without error and as a widget, the only form there was: a version 2 `archivo` is read as `archivos: [archivo]`
+(and rewritten as version 3). A file of version 4 or more (written by a newer supcoflow) is never rewritten: `install record`
+exits 4 `escrito_por_una_terminal_mas_nueva` and `diagnose` says to update supcoflow. The JSON of the command keeps `archivo` (the first file) for the skills before 0.9.0 and adds
+`archivos`, `forma` and `contrato`. 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.
+
+**Point 7 of `diagnose` (`interfaz`).** It is local and only reads. If `.supcoflow/instalacion.json` records an own
+interface, it checks that every recorded file is still there, that a contract is recorded and that it isn't older than the
+one the project declares today (`interfaz_propia.contrato.version`, asked from the engine; if that can't be asked, or the
+engine doesn't send it, nothing is compared). Only a new **major** version fails the point (a new requirement comes only with
+a major one): then it says to run the skill again and check that the interface still conforms. A newer minor or patch only
+adds optional points: the point stays ok and says so. To see that a recorded file is still there it doesn't read it. With no
+own interface recorded (no file, the widget, or nothing said) the point is ok («Not applicable»). It is advice: when it
+fails it lowers the «N of 7», it is marked `aviso: true` in the JSON, and it doesn't stop a test.
+
+**Before publishing 0.9.0.** `diagnose` now says «N of 7», and the skill of today (`SKILL.md`, `referencias/prueba.md`)
+asks literally for «6 of 6», but it pins the terminal to 0.8.1 (never `@latest`), so it won't see 0.9.0 until a skill pins it.
+The skill that pins 0.9.0 has to read `instalacion.ok` / `listo` (or `aviso`) instead of a fixed number, and 0.9.0 has to be on
+npm before or together with it.
 
 ## Test the installation
 
@@ -206,7 +254,7 @@ 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 diagnose` | Free and writes nothing. It prints «Checked sign-in, repo, GitHub App, allowed sites, chat, guide and interface: N of 7, 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: 7, puntos }` and `prueba: { listo, puntos }`. The seventh point, `interfaz`, is explained in «Put the chat in the app». |
 | `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. |

package/dist/api.js

@@ -1,5 +1,6 @@
 // Los pedidos de la terminal al motor. Sin dependencias: `fetch` viene de Node y se inyecta.
 import { FalloDeLaTerminal, SALIDA, taparSecretos } from "./contrato.js";
+import { esSemver } from "./instalacion.js";
 // La URL viene FIJA (§5.2): si un archivo del repo pudiera cambiarla, clonar un repo ajeno y correr
 // `supcoflow` mandaría el token a un servidor ajeno. Sólo el entorno del proceso la mueve, y `http`
 // únicamente contra la propia máquina: contra un host remoto la clave viajaría en claro.
@@ -23,7 +24,7 @@ export function urlDeLaApi(env) {
 }
 // A mano a propósito: tiene que coincidir con package.json (lo pinza test/describir.test.ts); sólo
 // identifica a la terminal en los logs del motor, no decide nada.
-const VERSION = "0.8.1";
+const VERSION = "0.9.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
@@ -318,7 +319,7 @@ export function elegirOrigen(api, clave, proyectoId, 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) {
+function aWidget(v, status, avisar) {
     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);
@@ -332,11 +333,58 @@ function aWidget(v, status) {
         || (n.estado !== "probando" && n.estado !== "soportado") || !archivo || !contenido || !uso
         || s.estado !== "disponible_sin_soporte" || !linea)
         throw inesperada(status);
+    // Un bloque ADITIVO a medias no tumba el widget de siempre (revisión 1, P2-1): se descarta entero, con un aviso, y no se muestra
+    // nada de él (nunca la mitad).
+    let propia = aInterfazPropia(v.interfaz_propia);
+    if (propia === null) {
+        avisar?.("The engine described the app's own interface halfway; I'm ignoring that part.");
+        propia = undefined;
+    }
     return {
         tenant_id: tenantId, project_id: projectId, backend_url: backendUrl, paquete: "@supcoflow/chat", version, instalar,
         nextjs: { estado: n.estado, archivo_sugerido: archivo, archivos_anteriores: anteriores, contenido, uso },
         script: { estado: "disponible_sin_soporte", linea },
         csp,
+        ...(propia === undefined ? {} : { interfaz_propia: propia }),
+    };
+}
+// `undefined` es «el motor no la manda» (producción de hoy; también `null`); `null` es «la mandó a medias»; y una lista cerrada de
+// campos, anidados incluidos: lo que el motor sume mañana dentro de `interfaz_propia` no se copia (como el resto del widget).
+// Sin `\\` tampoco: un `..` escrito con barras invertidas no se vería al partir por `/`.
+const SIN_ESPACIOS_RAROS = /^[\x21-\x5b\x5d-\x7e]+$/;
+const EN_EL_PAQUETE = "node_modules/@supcoflow/chat/";
+const ENTRADA_DEL_PAQUETE = "@supcoflow/chat/";
+// Una ruta o una entrada: un texto sin espacios ni control, que empiece donde tiene que empezar y no suba con `..`.
+const conPrefijo = (v, prefijo) => {
+    const t = texto(v);
+    return t !== null && SIN_ESPACIOS_RAROS.test(t) && t.startsWith(prefijo) && t.length > prefijo.length && !t.split("/").includes("..") ? t : null;
+};
+const objetoONull = (v) => (typeof v === "object" && v !== null && !Array.isArray(v) ? v : null);
+function aInterfazPropia(v) {
+    if (v === undefined || v === null)
+        return undefined;
+    const o = objetoONull(v);
+    const c = objetoONull(o?.contrato), e = objetoONull(o?.entradas), d = objetoONull(o?.documentos), n = objetoONull(o?.opciones_del_nucleo);
+    if (o === null || c === null || e === null || d === null || n === null)
+        return null;
+    const [version, instalar, tenantId, projectId, backendUrl, csp, nucleoTenant, nucleoProyecto] = [o.version, o.instalar, o.tenant_id, o.project_id, o.backend_url, o.csp, n.tenantId, n.projectId].map(texto);
+    const cVersion = texto(c.version);
+    const [cArchivo, cDocumento] = [c.archivo, c.documento].map((x) => conPrefijo(x, EN_EL_PAQUETE));
+    const entradas = [e.nucleo, e.react, e.pruebas, e.servidor_de_pruebas].map((x) => conPrefijo(x, ENTRADA_DEL_PAQUETE));
+    const docs = [d.nucleo, d.react, d.pruebas, d.conformidad, d.protocolo].map((x) => conPrefijo(x, EN_EL_PAQUETE));
+    if ((o.estado !== "sin_publicar" && o.estado !== "disponible") || o.paquete !== "@supcoflow/chat"
+        || !version || !instalar || !tenantId || !projectId || !backendUrl || !csp || !nucleoTenant || !nucleoProyecto
+        || !cVersion || !esSemver(cVersion) || cArchivo === null || cDocumento === null
+        || entradas.includes(null) || docs.includes(null))
+        return null;
+    const [eNucleo, eReact, ePruebas, eServidor] = entradas;
+    const [dNucleo, dReact, dPruebas, dConformidad, dProtocolo] = docs;
+    return {
+        estado: o.estado, paquete: "@supcoflow/chat", version, instalar, tenant_id: tenantId, project_id: projectId, backend_url: backendUrl, csp,
+        opciones_del_nucleo: { tenantId: nucleoTenant, projectId: nucleoProyecto },
+        contrato: { version: cVersion, archivo: cArchivo, documento: cDocumento },
+        entradas: { nucleo: eNucleo, react: eReact, pruebas: ePruebas, servidor_de_pruebas: eServidor },
+        documentos: { nucleo: dNucleo, react: dReact, pruebas: dPruebas, conformidad: dConformidad, protocolo: dProtocolo },
     };
 }
 // Una lista de textos no vacíos; ausente es lista vacía (un motor sin el campo), y cualquier otra forma es null.
@@ -348,11 +396,12 @@ function listaDeTextos(v) {
     const textos = v.map(texto);
     return textos.every((t) => t !== null && t !== "") ? textos : null;
 }
-export async function leerWidget(api, clave, proyectoId, f) {
+// `avisar` recibe lo que la terminal descarta sin tumbar el comando (hoy: una `interfaz_propia` a medias).
+export async function leerWidget(api, clave, proyectoId, f, avisar) {
     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);
+    return aWidget(r.cuerpo, r.status, avisar);
 }
 // ---- La prueba (bloque 7) ----
 const rutaDelProyecto = (proyectoId) => `/api/proyectos/${encodeURIComponent(proyectoId)}`;

package/dist/argumentos.js

@@ -13,8 +13,10 @@ export const COMANDOS_COMPUESTOS = [
 const PRIMERAS_PALABRAS = new Set([...COMANDOS_COMPUESTOS, ...Object.keys(COMANDOS_VIEJOS)].filter((c) => c.includes(" ")).map((c) => c.split(" ")[0]));
 const FLAGS_CON_VALOR = [
     "repo", "install", "test", "site", "title", "greeting", "file", "allow", "mode", "name", "save-to", "id", "source", "skill", "app",
-    "message", "test-id", "ceiling", "expect-policy",
+    "message", "test-id", "ceiling", "expect-policy", "shape",
 ];
+// Los que sí se repiten (cada comando decide cuántos acepta: `cli.ts`, `archivosDeMas`); ninguno va vacío.
+const FLAGS_REPETIBLES = new Set(["file"]);
 const FLAGS_BOOLEANOS = ["json", "dry-run", "help", "start", "wait", "from-github", "authorize-spend"];
 // El flag que el token nombró, ya llevado a su nombre canónico (el viejo y el nuevo cuentan como el mismo).
 const canonico = (nombre) => FLAGS_VIEJOS[nombre] ?? nombre;
@@ -55,7 +57,7 @@ export function leerArgumentos(argv) {
     // nombre viejo y el nuevo de un mismo flag) creería que se usó el primero. Se mira en los tokens y se rechaza.
     for (const nombre of FLAGS_CON_VALOR) {
         const toks = tokens.filter((t) => canonico(t.name) === nombre);
-        if (toks.length > 1 || toks.some((t) => t.value === "")) {
+        if ((toks.length > 1 && !FLAGS_REPETIBLES.has(nombre)) || toks.some((t) => t.value === "")) {
             throw invalida("argumentos_invalidos", `--${nombre} goes once, with a value. Try \`supcoflow --help\`.`);
         }
     }
@@ -86,6 +88,7 @@ export function leerArgumentos(argv) {
         return t === undefined ? null : (t.value ?? null);
     };
     const hay = (nombre) => tokens.some((x) => canonico(x.name) === nombre);
+    const archivos = tokens.filter((t) => canonico(t.name) === "file").map((t) => t.value ?? "");
     return {
         comando,
         viejos,
@@ -111,6 +114,8 @@ export function leerArgumentos(argv) {
             fromGithub: hay("from-github"),
             skill: un("skill"),
             app: un("app"),
+            files: archivos,
+            shape: un("shape"),
             authorizeSpend: hay("authorize-spend"),
             message: un("message"),
             testId: un("test-id"),

package/dist/cli.js

@@ -19,7 +19,7 @@ import { repoConectarInteractivo, repoConectarStart, repoConectarWait } from "./
 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";
+import { archivosDeMas, flagQueNoAplica } from "./flags-por-comando.js";
 const COMANDOS = new Set(DESCRIPCION.comandos.map((c) => c.nombre));
 const invalida = (error, message) => new FalloDeLaTerminal(SALIDA.entradaInvalida, error, message);
 // Los nombres que la terminal tenía antes de la 0.8.0 siguen valiendo (`src/alias.ts`), pero no salen en `describe`.
@@ -42,13 +42,16 @@ async function correr(argv) {
             site: flags.site !== null, title: flags.title !== null, greeting: flags.greeting !== null, theme: flags.theme.length > 0,
             file: flags.file !== null, allow: flags.allow !== null, mode: flags.mode !== null,
             name: flags.name !== null, saveTo: flags.saveTo !== null, id: flags.id !== null, source: flags.source !== null, fromGithub: flags.fromGithub,
-            skill: flags.skill !== null, app: flags.app !== null,
+            skill: flags.skill !== null, app: flags.app !== null, shape: flags.shape !== null,
             authorizeSpend: flags.authorizeSpend, message: flags.message !== null, testId: flags.testId !== null,
             ceiling: flags.ceiling !== null, expectPolicy: flags.expectPolicy !== null,
         };
         const noAplica = flagQueNoAplica(comando, Object.keys(presentes).filter((k) => presentes[k]));
         if (noAplica !== null)
             throw invalida("flag_no_aplica", noAplica);
+        const deMas = archivosDeMas(comando, flags.files.length);
+        if (deMas !== null)
+            throw invalida("argumentos_invalidos", deMas);
         if (flags.start && flags.wait) {
             throw invalida("flags_incompatibles", "--start and --wait go separately: first one and then the other.");
         }

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.8.1";
+const VERSION = "0.9.0";
 export const DESCRIPCION = {
     version: VERSION,
     comandos: [
@@ -219,17 +219,18 @@ export const DESCRIPCION = {
         },
         {
             nombre: "widget",
-            resumen: "Shows what to paste into the app to get the chat, built by the engine with the project's ids: the package and its exact version, the Next.js wrapper file (`nextjs.contenido`, as is, without rewriting the ids), the file name to use (`nextjs.archivo_sugerido`) and the earlier names the chat may already be installed under (`nextjs.archivos_anteriores`), how to use it, the CSP line and the <script> one (not for Next.js). It writes no files. Exits 4 sin_proyecto if the repo has no project; 1 respuesta_inesperada if the engine sends something halfway.",
-            flags: ["--repo owner/repo: the repo, if it isn't this folder's «origin»", "--json: the engine's object as is"],
+            resumen: "Shows what to paste into the app to get the chat, built by the engine with the project's ids: the package and its exact version, the Next.js wrapper file (`nextjs.contenido`, as is, without rewriting the ids), the file name to use (`nextjs.archivo_sugerido`) and the earlier names the chat may already be installed under (`nextjs.archivos_anteriores`), how to use it, the CSP line and the <script> one (not for Next.js). If the engine describes the app's own interface (`interfaz_propia`: the app builds the chat with its own components; there is no code to paste) it passes it on as the engine sent it: `estado` (`sin_publicar`: the version isn't on npm yet, so the text doesn't offer the path; `disponible`), the package with its exact version, the ids, the backend, the CSP line, the presentation contract (`contrato.version`, `contrato.archivo`, `contrato.documento`), the entry points (`entradas`) and the docs (`documentos`). A halfway `interfaz_propia` is ignored with a warning on stderr and the widget is shown as always. It writes no files. Exits 4 sin_proyecto if the repo has no project; 1 respuesta_inesperada if the engine sends the widget itself halfway.",
+            flags: ["--repo owner/repo: the repo, if it isn't this folder's «origin»", "--json: the engine's object as is (`interfaz_propia` only when the engine sends it)"],
             ejemplos: ["supcoflow widget --json"],
             codigos: [0, 1, 2, 3, 4],
         },
         {
             nombre: "install record",
-            resumen: "Records in .supcoflow/instalacion.json (this clone's root, version 2) which versions the chat was installed with: the skill, this terminal, the chat package (declared in the app's package.json and installed in node_modules), the project configuration and, with --file, the file the chat lives in; never a secret or a date. Repeating without changes doesn't touch it (sin_cambios: true), and running again without --file keeps the file already recorded. It only rewrites it if git already keeps the previous one: with uncommitted changes (or deleted without a commit) it exits 4 cambios_sin_commit; if it exists without being tracked (or ignored), 4 archivo_no_versionado. Others: 3 falta_skill / skill_invalida / archivo_invalido / app_fuera_del_repo / app_inexistente / sin_clon; 4 sin_proyecto / acuerdo_ilegible; 1 paquete_ilegible / configuracion_inesperada / archivo_no_escrito.",
+            resumen: "Records in .supcoflow/instalacion.json (this clone's root, version 3) which versions the chat was installed with: the skill, this terminal, the chat package (declared in the app's package.json and installed in node_modules), the project configuration and what was installed: `forma` (`widget` or `interfaz_propia`, with --shape), `archivos` (the files the chat lives in, with --file) and `contrato` (the version of the presentation contract the installed package carries in its contract.json, or null if it has none); never a secret or a date. A version 1 or 2 file is read without error as a widget (the `archivo` of a 2 is its file). Changing --shape without --file leaves `archivos` empty (the files of the other form aren't inherited). Repeating without changes doesn't touch it (sin_cambios: true), and running again without --shape or --file keeps the form and the files already recorded. The JSON adds `archivos`, `forma` and `contrato`; `archivo` (the first file) stays for the skills before 0.9.0. It only rewrites it if git already keeps the previous one: with uncommitted changes (or deleted without a commit) it exits 4 cambios_sin_commit; if it exists without being tracked (or ignored), 4 archivo_no_versionado. Others: 3 falta_skill / skill_invalida / archivo_invalido / forma_invalida / app_fuera_del_repo / app_inexistente / sin_clon; 4 sin_proyecto / acuerdo_ilegible / escrito_por_una_terminal_mas_nueva (the file is version 4 or more: it doesn't rewrite it); 1 paquete_ilegible / configuracion_inesperada / archivo_no_escrito.",
             flags: [
                 "--skill version: the metadata.version of the skill that installs it (semver, required; without it exits 3 falta_skill without requesting anything)",
-                "--file path: the chat file, relative to the repo root (no `..`, not absolute, not a symlink or through one; otherwise exits 3 archivo_invalido and writes nothing)",
+                "--file path: a file of the chat, relative to the repo root (no `..`, not absolute, not a symlink or through one; otherwise exits 3 archivo_invalido and writes nothing). It can be repeated (up to 20; an own interface lives in several files) and replaces the list already recorded",
+                "--shape widget|own-interface: what was installed: the packaged widget, or a chat the app builds with its own components (`forma: interfaz_propia`); anything else exits 3 forma_invalida. Without it the recorded form is kept",
                 "--app folder: the app's folder, relative to the repo root (the root by default; outside the repo it exits 3 app_fuera_del_repo)",
                 "--repo owner/repo: the repo, if it isn't this folder's «origin» (the file goes in this clone only if it is that repo: its origin, or a `supcoflow` remote at https://github.com/owner/repo.git; otherwise it exits 3 sin_clon saying what this clone is and the exact `git remote add supcoflow …`, without asking the engine)",
                 "--dry-run: shows the file and the difference without writing anything",
@@ -240,8 +241,8 @@ export const DESCRIPCION = {
         },
         {
             nombre: "diagnose",
-            resumen: "Says, free of charge and writing nothing, how far the installation is (sign-in, repo, GitHub App, allowed sites, chat and guide: N of 6) and, apart, whether a test of the project would go in and how far it would get: policy, monthly balance against the test's ceiling, open tests, whether THIS machine can save the test request (the local point `maquina`, checked without writing anything) and whatever else the engine adds. Exits 0 if everything is ready and 4 if something needs fixing (no_listo), with each point; if `maquina` isn't ok, `listo` and `prueba.listo` are false and the N of 6 doesn't change.",
-            flags: ["--repo owner/repo: the repo, if it isn't this folder's «origin»", "--json: { instalacion: { ok, total: 6, puntos }, prueba: { listo, puntos }, maquina: { ok, impedimentos: [{ codigo, detalle }] }, intento_pendiente: { techo_usd, politica } | null, … }"],
+            resumen: "Says, free of charge and writing nothing, how far the installation is (sign-in, repo, GitHub App, allowed sites, chat, guide and interface: N of 7) and, apart, whether a test of the project would go in and how far it would get: policy, monthly balance against the test's ceiling, open tests, whether THIS machine can save the test request (the local point `maquina`, checked without writing anything) and whatever else the engine adds. Exits 0 if everything is ready and 4 if something needs fixing (no_listo), with each point; if `maquina` isn't ok, `listo` and `prueba.listo` are false and the N of 7 doesn't change. The seventh point, `interfaz`, is local and only reads: if .supcoflow/instalacion.json records an own interface (`forma: interfaz_propia`) it checks that the recorded files are still there and that the recorded contract is not behind a new major version (the first number) of the one the project declares (`interfaz_propia.contrato.version` in `widget`; a newer minor or patch only adds optional points and stays ok, saying so); without an own interface it is ok («Not applicable»). It is advice, marked `aviso: true` in the JSON: it lowers the N of 7 but doesn't stop a test.",
+            flags: ["--repo owner/repo: the repo, if it isn't this folder's «origin»", "--json: { instalacion: { ok, total: 7, puntos }, prueba: { listo, puntos }, maquina: { ok, impedimentos: [{ codigo, detalle }] }, intento_pendiente: { techo_usd, politica } | null, … }"],
             ejemplos: ["supcoflow diagnose --json"],
             codigos: [0, 1, 2, 3, 4],
         },

package/dist/comandos/instalacion.js

@@ -1,8 +1,9 @@
 // src/comandos/instalacion.ts
-// `install record --skill <versión> [--app <carpeta>] [--file <ruta>] [--dry-run]` (bloque 6 y 0.8.0): deja en
-// `.supcoflow/instalacion.json` con qué versiones se instaló el chat y, desde la 0.8.0 (v2), en qué archivo quedó
-// (`--file`). 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`).
+// `install record --skill <versión> [--app <carpeta>] [--file <ruta>]... [--shape widget|own-interface] [--dry-run]`
+// (bloque 6, 0.8.0 y 0.9.0): deja en `.supcoflow/instalacion.json` con qué versiones se instaló el chat y, desde la 0.9.0
+// (v3, T8), qué se instaló (`--shape`: el widget o una interfaz propia de la app), en qué archivos quedó (`--file`, repetible)
+// y qué versión del contrato de presentación trae el paquete instalado (su `contract.json`). Lee la configuración del motor y
+// los `package.json` y `contract.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
@@ -11,11 +12,13 @@
 import { lstatSync, realpathSync, statSync } from "node:fs";
 import path from "node:path";
 import { resultadoDeFallo, SALIDA, taparSecretos } from "../contrato.js";
-import { archivoAnotado, armarInstalacion, esSemver, PAQUETE_DEL_CHAT, RUTA_DE_LA_INSTALACION, serializar, validarElArchivoDelChat } from "../instalacion.js";
+import { anotadoEn, armarInstalacion, leerInstalacionAnotada, esSemver, PAQUETE_DEL_CHAT, RUTA_DE_LA_INSTALACION, serializar, validarLosArchivos } from "../instalacion.js";
 import { NO_LEIDO } from "../lectura.js";
 import { repoPedido } from "../repo-local.js";
 import { fallo } from "./configurar.js";
 import { proyectoDelRepo } from "./proyecto-del-repo.js";
+// `--shape` en inglés; al archivo va el nombre de la API (como `--mode save` y `guardar`).
+const FORMA_DE_LA_FLAG = { widget: "widget", "own-interface": "interfaz_propia" };
 export function esEnlaceReal(p) {
     try {
         return lstatSync(p).isSymbolicLink();
@@ -59,10 +62,22 @@ function leerJson(d, p, nombre) {
         return { ok: false, noExiste: false, resultado: fallo(SALIDA.inesperado, "paquete_ilegible", `${nombre} isn't valid JSON.`) };
     }
 }
-// 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 contratoDelPaquete(d, raiz, carpetaReal, avisos) {
+    const candidato = path.join(carpetaReal, "contract.json");
+    const real = d.rutaReal(candidato);
+    if (real === null)
+        return { ok: true, valor: null };
+    if (!adentro(raiz, real)) {
+        const aviso = `${path.relative(raiz, candidato)} points outside the repo; I don't read it and I record the contract as null.`;
+        avisos.push(aviso);
+        d.avisar(aviso);
+        return { ok: true, valor: null };
+    }
+    const j = leerJson(d, real, `the contract.json of ${PAQUETE_DEL_CHAT}`);
+    if (j.ok)
+        return j;
+    return { ok: false, resultado: j.noExiste ? fallo(SALIDA.inesperado, "paquete_ilegible", `I can't read the contract.json of ${PAQUETE_DEL_CHAT}.`) : j.resultado };
+}
 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");
@@ -72,16 +87,18 @@ function paqueteInstalado(d, raiz, app, avisos) {
                 const aviso = `${path.relative(raiz, candidato)} points outside the repo; I don't read it and I record the installed chat as null.`;
                 avisos.push(aviso);
                 d.avisar(aviso);
-                return { ok: true, valor: null };
+                return { ok: true, valor: null, contrato: null };
             }
             const j = leerJson(d, real, `the installed package.json of ${PAQUETE_DEL_CHAT}`);
-            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", `I can't read the installed package.json of ${PAQUETE_DEL_CHAT}.`) : j.resultado };
+            if (!j.ok) {
+                // 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", `I can't read the installed package.json of ${PAQUETE_DEL_CHAT}.`) : j.resultado };
+            }
+            const c = contratoDelPaquete(d, raiz, path.dirname(real), avisos);
+            return c.ok ? { ok: true, valor: j.valor, contrato: c.valor } : c;
         }
         if (dir === raiz || path.dirname(dir) === dir)
-            return { ok: true, valor: null };
+            return { ok: true, valor: null, contrato: null };
     }
 }
 async function estadoDelArchivo(d, raizGit, existe) {
@@ -123,19 +140,29 @@ function diff(antes, despues) {
     }
     return lineas.join("\n");
 }
-const resumen = (x) => `skill ${x.skill}, terminal ${x.terminal}, chat declared ${x.chat.declarado ?? "—"} / installed ${x.chat.instalado ?? "—"}${x.archivo !== null ? `, file ${x.archivo}` : ""}`;
+const resumen = (x) => `skill ${x.skill}, terminal ${x.terminal}, chat declared ${x.chat.declarado ?? "—"} / installed ${x.chat.instalado ?? "—"}`
+    + `${x.forma === null ? "" : `, ${x.forma === "widget" ? "widget" : "own interface"}`}`
+    + `${x.archivos.length === 0 ? "" : `, ${x.archivos.length === 1 ? "file" : "files"} ${x.archivos.join(", ")}`}`
+    + `${x.contrato === null ? "" : `, contract ${x.contrato}`}`;
 export async function instalacionAnotar(d, flags) {
     if (flags.skill === null)
         return fallo(SALIDA.entradaInvalida, "falta_skill", "The skill version is missing: `supcoflow install record --skill 0.1.0`.");
     if (!esSemver(flags.skill))
         return fallo(SALIDA.entradaInvalida, "skill_invalida", "--skill goes with a semver version (for example 0.1.0).");
-    // El archivo del chat se mira antes de cualquier pedido: una ruta imposible no gasta una vuelta al motor.
-    let archivoPedido = null;
-    if (flags.file !== undefined && flags.file !== null) {
-        const v = validarElArchivoDelChat(flags.file);
+    // La forma y los archivos del chat se miran antes de cualquier pedido: algo imposible no gasta una vuelta al motor.
+    let formaPedida = null;
+    if (flags.shape !== undefined && flags.shape !== null) {
+        formaPedida = Object.hasOwn(FORMA_DE_LA_FLAG, flags.shape) ? FORMA_DE_LA_FLAG[flags.shape] : null;
+        if (formaPedida === null)
+            return fallo(SALIDA.entradaInvalida, "forma_invalida", "--shape goes with `widget` (the packaged widget) or `own-interface` (a chat the app builds with its own components).");
+    }
+    const crudos = flags.files !== undefined && flags.files.length > 0 ? flags.files : flags.file !== undefined && flags.file !== null ? [flags.file] : [];
+    let archivosPedidos = null;
+    if (crudos.length > 0) {
+        const v = validarLosArchivos(crudos);
         if (!v.ok)
             return fallo(SALIDA.entradaInvalida, "archivo_invalido", v.motivo);
-        archivoPedido = v.ruta;
+        archivosPedidos = v.rutas;
     }
     // ─── La raíz y la app, antes de cualquier pedido ───
     let raizGit;
@@ -162,7 +189,7 @@ export async function instalacionAnotar(d, flags) {
         return fallo(SALIDA.entradaInvalida, "app_inexistente", "--app has to be a folder (the app's), not a file.");
     // `--file`: ni un enlace simbólico ni un camino que pase por uno (saldría del repo sin que se vea). El archivo todavía
     // puede no existir (con `--dry-run` se anota antes de escribirlo), pero ninguna carpeta del camino puede ser un enlace.
-    if (archivoPedido !== null) {
+    for (const archivoPedido of archivosPedidos ?? []) {
         const partes = archivoPedido.split("/");
         for (let i = 1; i <= partes.length; i++) {
             if (d.esEnlace(path.join(raiz, ...partes.slice(0, i)))) {
@@ -197,18 +224,32 @@ export async function instalacionAnotar(d, flags) {
     const actual = d.leerArchivoChico(archivo, TOPE_DEL_ARCHIVO);
     const existe = !("error" in actual) || actual.error !== NO_LEIDO.noExiste;
     const antes = "bytes" in actual ? Buffer.from(actual.bytes).toString("utf8") : null;
-    // Re-correr sin `--file` no borra el archivo que ya se anotó; un v1 (sin `archivo`) da null, sin error.
-    const archivoDelChat = archivoPedido ?? archivoAnotado(antes);
+    // Re-correr sin `--shape` ni `--file` no borra lo que ya se anotó (v2: su `archivo` es el widget; v1: nada, sin error).
+    // `--file` reemplaza la lista entera y `--shape` la forma: lo que se pide manda, lo que no, se conserva.
+    // Un archivo de una terminal más nueva no se reescribe: se perdería lo que esa versión anotó.
+    if (leerInstalacionAnotada(antes).estado === "mas_nueva") {
+        return fallo(SALIDA.haceFaltaUnaPersona, "escrito_por_una_terminal_mas_nueva", `${RUTA_DE_LA_INSTALACION} was written by a newer supcoflow than this one; I didn't touch it. Update supcoflow (\`npx supcoflow@latest\`) and run again.`);
+    }
+    const anotado = anotadoEn(antes);
+    // Cambiar la forma sin decir los archivos no hereda los de la forma anterior (el envoltorio del widget no es la interfaz propia).
+    const cambiaLaForma = formaPedida !== null && anotado.forma !== null && formaPedida !== anotado.forma;
     let x;
     try {
-        x = armarInstalacion({ skill: flags.skill, terminal: d.terminal, paqueteDeLaApp: deLaApp.ok ? deLaApp.valor : null, paqueteInstalado: instalado.valor, configuracion, archivo: archivoDelChat });
+        x = armarInstalacion({
+            skill: flags.skill, terminal: d.terminal, paqueteDeLaApp: deLaApp.ok ? deLaApp.valor : null, paqueteInstalado: instalado.valor, configuracion,
+            forma: formaPedida ?? anotado.forma, archivos: archivosPedidos ?? (cambiaLaForma ? [] : anotado.archivos), contrato: instalado.contrato,
+        });
     }
     catch (e) {
         return resultadoDeFallo(e);
     }
     const nuevo = serializar(x);
     // ─── ¿Se puede escribir? ───
-    const json = { ok: true, ruta: RUTA_DE_LA_INSTALACION, instalacion: x, archivo: x.archivo, ...(avisos.length > 0 ? { avisos } : {}) };
+    // `archivo` (el primero) sigue en el JSON por las skills de antes de la 0.9.0; lo nuevo es `archivos`, `forma` y `contrato`.
+    const json = {
+        ok: true, ruta: RUTA_DE_LA_INSTALACION, instalacion: x, archivo: x.archivos[0] ?? null, archivos: x.archivos, forma: x.forma, contrato: x.contrato,
+        ...(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} already says that (${resumen(x)}); I didn't touch it.` };
     }

package/dist/comandos/probar.js

@@ -1,5 +1,30 @@
+// `supcoflow diagnose` y `supcoflow test` (bloque 7, la prueba): ¿un problema que entra por el
+// chat llega hasta un issue? El diagnóstico es gratis y sólo lee. La prueba gasta un relevamiento (techo
+// del motor, hoy US$ 2): sin `--authorize-spend` no se manda nada que escriba (R6).
+//
+// Lo que la persona vio es lo que viaja (R5, 0.8.0): `--authorize-spend` exige `--ceiling` (el número que se le
+// mostró) y `--expect-policy` (la política con la que se le ofreció) y manda esos dos valores; no relee el
+// diagnóstico para elegirlos. El motor los compara con los de ahora: `techo_distinto` / `politica_distinta` salen
+// 4 con los valores nuevos y sin reintentar, y la persona decide de nuevo. El alias viejo `probar --autorizo-gasto`
+// exige también `--ceiling` (un alias no puede ampliar lo autorizado) pero no `--expect-policy`.
+//
+// El ciclo de la clave (hallazgo 5), en el orden en que se lee abajo:
+//   1. Sin intento guardado: clave nueva, y el intento ENTERO guardado antes del POST (estricto).
+//   2. Con intento guardado: es un reintento; misma clave, mismo mensaje, mismo techo, misma política. Otro
+//      `--message`, otro `--ceiling` u otra `--expect-policy` sale 4 `intento_pendiente` sin mandar nada.
+//   3. 202: la última prueba = la del motor y el intento cerrado, en una escritura (src/pruebas-guardadas.ts).
+//      Si falla, sale 1 con el id y el intento sigue abierto: el próximo recibe la misma prueba.
+//   4. Ambigua (sin respuesta, 5xx, pausa, otro intento en curso): el intento se conserva. Rechazo
+//      definitivo: se cierra, el motor no creó nada con esa clave.
+//   5. Una prueba nueva es `test --authorize-spend` sin intento abierto: clave nueva aunque el mensaje
+//      sea el mismo.
+//
+// `--wait` sigue la prueba por tramos (≤ 90 s el comando entero, como `login --wait`): el estado lo deriva
+// el motor en cada llamada y acá sólo se traduce a un código de salida con la tabla de la prueba.
+import path from "node:path";
 import { resultadoDeFallo, SALIDA } from "../contrato.js";
-import { agruparPuntos, contarBuenos, lineaDeLoRevisado, nombreDelPunto, puntoDeSesion, puntoDelRepo, TOTAL_DE_INSTALACION } from "../diagnostico.js";
+import { agruparPuntos, contarBuenos, lineaDeLoRevisado, nombreDelPunto, puntoDeLaInterfaz, puntoDeSesion, puntoDelRepo, TOTAL_DE_INSTALACION } from "../diagnostico.js";
+import { leerInstalacionAnotada, RUTA_DE_LA_INSTALACION } from "../instalacion.js";
 import { leerRepoLocal } from "../repo-local.js";
 import { PLAZO_MINIMO_DE_SONDEO_MS, TRAMO_MAXIMO_MS } from "../sondeo.js";
 import { fallo, rutaDe } from "./configurar.js";
@@ -64,6 +89,41 @@ function puntoDeLaMaquina(r) {
         ? { punto: "maquina", ok: true, mensaje: "No obstacle found to saving the test request on this machine.", grupo: "prueba" }
         : { punto: "maquina", ok: false, mensaje: `This machine can't save the test request yet: ${detalles(r)}`, grupo: "prueba" };
 }
+// El punto 7 (T8): lee `.supcoflow/instalacion.json` del clon y, sólo si hay una interfaz propia anotada, mira que sus archivos
+// sigan y le pregunta al proyecto qué contrato declara hoy. Todo lo que no se pueda mirar queda «sin mirar», nunca en contra.
+async function puntoDeLaInterfazDeEsteClon(d, local, proyecto, clave) {
+    const esElClon = local.raiz !== null && local.repo !== null && local.repo.toLowerCase() === proyecto.repo.toLowerCase();
+    if (!esElClon || d.archivos === undefined)
+        return puntoDeLaInterfaz({ lectura: null, faltan: [], delProyecto: null });
+    let lectura;
+    try {
+        lectura = leerInstalacionAnotada(d.archivos.leer(path.join(local.raiz, RUTA_DE_LA_INSTALACION)));
+    }
+    catch {
+        lectura = { estado: "ilegible" };
+    }
+    if (lectura.estado !== "leida" || lectura.forma !== "interfaz_propia")
+        return puntoDeLaInterfaz({ lectura, faltan: [], delProyecto: null });
+    const faltan = lectura.archivos.filter((f) => {
+        try {
+            const completo = path.join(local.raiz, f);
+            return d.existe !== undefined ? !d.existe(completo) : d.archivos.leer(completo) === null;
+        }
+        catch {
+            return true;
+        }
+    });
+    let delProyecto = null;
+    if (d.leerWidget !== undefined) {
+        try {
+            delProyecto = (await d.leerWidget(d.api, clave, proyecto.id)).interfaz_propia?.contrato.version ?? null;
+        }
+        catch {
+            delProyecto = null; // no se pudo preguntar: no se compara
+        }
+    }
+    return puntoDeLaInterfaz({ lectura, faltan, delProyecto });
+}
 export async function diagnosticar(d, flags) {
     const p = await proyectoDelRepo(d, flags);
     if (!p.ok)
@@ -84,10 +144,10 @@ export async function diagnosticar(d, flags) {
     catch {
         local = { repo: null, raiz: null, motivo: "sin_git" };
     }
-    const agrupados = agruparPuntos(g, [puntoDeSesion(), puntoDelRepo(local, p.proyecto.repo)]);
+    const agrupados = agruparPuntos(g, [puntoDeSesion(), puntoDelRepo(local, p.proyecto.repo), await puntoDeLaInterfazDeEsteClon(d, local, p.proyecto, p.clave)]);
     const instalacion = agrupados.instalacion;
     // El punto local de la prueba (1A.1): ¿esta máquina puede guardar el pedido? Si no, la prueba no entra, y se dice acá y
-    // no después del OK de gasto. No cuenta en el «N of 6» de la instalación.
+    // no después del OK de gasto. No cuenta en el «N of 7» de la instalación.
     const revision = await revisarLaMaquina(d, p.proyecto.id);
     const prueba = [puntoDeLaMaquina(revision), ...agrupados.prueba];
     const buenos = contarBuenos(instalacion);

package/dist/comandos/widget.js

@@ -1,5 +1,30 @@
 import { resultadoDeFallo, SALIDA } from "../contrato.js";
 import { proyectoDelRepo } from "./proyecto-del-repo.js";
+// La forma «interfaz propia» (T8): sin código para pegar. La app arma el chat con sus propios componentes; esto es lo que
+// hay que instalar y el contrato que la interfaz tiene que cumplir. Todo sale del motor, tal cual (también las rutas). Con
+// `sin_publicar` la versión todavía no está en npm: no se ofrece el camino (ni un `npm i` que fallaría); el JSON sí lo dice.
+function textoDeLaInterfazPropia(p) {
+    if (p.estado !== "disponible") {
+        return ["", `Own interface: not published yet (${p.paquete}@${p.version} is not on npm); use the widget above.`];
+    }
+    return [
+        "",
+        "Own interface (build the chat with the app's own components, instead of steps 2 and 3; there is no code to paste):",
+        "   Install the package (the exact version):",
+        `   ${p.instalar}`,
+        `   tenantId: ${p.opciones_del_nucleo.tenantId}`,
+        `   projectId: ${p.opciones_del_nucleo.projectId}`,
+        `   backendUrl: ${p.backend_url}`,
+        "   Content Security Policy (CSP): if the app has `connect-src`, add this origin and keep what it already has:",
+        `   ${p.csp}`,
+        `   Presentation contract: ${p.contrato.version}. Once the package is installed, read it offline (paths relative to the folder where you ran npm i):`,
+        `   ${p.contrato.archivo}`,
+        `   ${p.contrato.documento}`,
+        "   What the interface must do is in the contract; how it looks is the app's.",
+        `   Entry points: ${p.entradas.nucleo} (core), ${p.entradas.react} (React), ${p.entradas.pruebas} and ${p.entradas.servidor_de_pruebas} (test bench).`,
+        `   Docs: ${p.documentos.nucleo}, ${p.documentos.react}, ${p.documentos.pruebas}, ${p.documentos.conformidad}, ${p.documentos.protocolo}.`,
+    ];
+}
 function textoDe(w) {
     const anteriores = w.nextjs.archivos_anteriores;
     return [
@@ -20,6 +45,7 @@ function textoDe(w) {
         "",
         "Alternative with <script> (available, not tested in a real app):",
         `   ${w.script.linea}`,
+        ...(w.interfaz_propia === undefined ? [] : textoDeLaInterfazPropia(w.interfaz_propia)),
     ].join("\n");
 }
 export async function widget(d, flags) {

package/dist/diagnostico.js

@@ -1,5 +1,5 @@
+import { compararSemver, RUTA_DE_LA_INSTALACION } from "./instalacion.js";
 import { frasePorQueNoAtaClon } from "./repo-local.js";
-export const TOTAL_DE_INSTALACION = 6;
 // El orden y los nombres con que se dicen: los ids de los puntos del motor son datos suyos y no cambian.
 const DE_LA_INSTALACION = [
     { punto: "sign-in", como: "sign-in" },
@@ -8,7 +8,9 @@ const DE_LA_INSTALACION = [
     { punto: "sitios", como: "allowed sites" },
     { punto: "chat", como: "chat" },
     { punto: "guia", como: "guide" },
+    { punto: "interfaz", como: "interface" },
 ];
+export const TOTAL_DE_INSTALACION = DE_LA_INSTALACION.length;
 const DEL_MOTOR = new Set(["instalacion", "sitios", "chat", "guia"]);
 export const lineaDeLoRevisado = (n) => `Checked ${DE_LA_INSTALACION.map((x) => x.como).slice(0, -1).join(", ")} and ${DE_LA_INSTALACION.at(-1).como}: ${n} of ${TOTAL_DE_INSTALACION}, at no cost.`;
 export const nombreDelPunto = (punto) => DE_LA_INSTALACION.find((x) => x.punto === punto)?.como ?? punto;
@@ -31,6 +33,46 @@ export function puntoDelRepo(local, repoDelProyecto) {
     }
     return { punto: "repo", ok: true, mensaje: `The origin of this folder is ${local.repo}, the project's repo.`, grupo: "instalacion" };
 }
+/**
+ * El punto 7 (T8): la interfaz propia de la app. Puro: recibe lo ya leído. Es un AVISO local: baja el «N of 7» pero no frena una
+ * prueba (la prueba mira que un problema llegue a un issue, no cómo se ve el chat). Sin interfaz propia anotada no aplica y
+ * cuenta como ok. El contenido de `instalacion.json` nunca se copia al mensaje.
+ *  · `lectura`: lo que dice el archivo (o `null` si no se miró: el clon no es el del repo del proyecto).
+ *  · `faltan`: los archivos anotados que ya no están.
+ *  · `delProyecto`: el contrato que declara el proyecto hoy (`interfaz_propia.contrato.version`), o null si no se supo.
+ */
+const mayor = (v) => Number(v.split(".")[0]);
+export function puntoDeLaInterfaz(i) {
+    const punto = (ok, mensaje) => ({ punto: "interfaz", ok, mensaje, grupo: "instalacion", aviso: true });
+    if (i.lectura === null)
+        return punto(true, "Not checked: this folder isn't a clone of the project's repo, so I don't read its installation record.");
+    const l = i.lectura;
+    if (l.estado === "ausente")
+        return punto(true, `Not applicable: there's no ${RUTA_DE_LA_INSTALACION}, so no own interface is recorded.`);
+    if (l.estado === "mas_nueva")
+        return punto(false, `${RUTA_DE_LA_INSTALACION} was written by a newer supcoflow than this one: update supcoflow (\`npm i -g supcoflow@latest\` or \`npx supcoflow@latest\`) to read it.`);
+    if (l.estado === "ilegible")
+        return punto(false, `I can't read ${RUTA_DE_LA_INSTALACION}: run \`supcoflow install record\` again.`);
+    if (l.forma !== "interfaz_propia") {
+        return punto(true, l.forma === "widget" ? "Not applicable: the chat is recorded as the packaged widget, which has no interface contract to check." : "Not applicable: no own interface is recorded.");
+    }
+    if (l.archivos.length === 0)
+        return punto(false, "The installation says the chat is an own interface but records none of its files: run `supcoflow install record --file …` again.");
+    if (i.faltan.length > 0)
+        return punto(false, `These files of the interface are recorded but gone: ${i.faltan.join(", ")}. Run the skill again to update the record.`);
+    if (l.contrato === null) {
+        return punto(false, "The interface doesn't record which presentation contract it follows (the installed @supcoflow/chat has no contract.json): update the package and run `supcoflow install record` again.");
+    }
+    const archivos = `${l.archivos.length} ${l.archivos.length === 1 ? "file" : "files"}`;
+    if (i.delProyecto !== null && compararSemver(i.delProyecto, l.contrato) > 0) {
+        // Un obligatorio nuevo sólo llega con una versión MAYOR del contrato (plan §2.5.8): una menor o de parche suma lo opcional.
+        if (mayor(i.delProyecto) > mayor(l.contrato)) {
+            return punto(false, `The interface (${archivos}) follows contract ${l.contrato}, and the project now declares ${i.delProyecto}, a new major version: run the skill again to see what changed and check that the interface still conforms.`);
+        }
+        return punto(true, `The interface (${archivos}) follows contract ${l.contrato}; the project declares ${i.delProyecto}, which only adds optional points: run the skill again to see them.`);
+    }
+    return punto(true, `The interface (${archivos}) follows contract ${l.contrato}${i.delProyecto === l.contrato ? ", the one the project declares" : ""}.`);
+}
 /** Reparte los puntos del motor en los dos grupos y suma los dos locales al de la instalación. */
 export function agruparPuntos(g, locales) {
     const delMotor = g.puntos.map((p) => ({ ...p, grupo: p.grupo ?? (DEL_MOTOR.has(p.punto) ? "instalacion" : "prueba") }));

package/dist/entorno.js

@@ -508,7 +508,7 @@ export function entornoReal(env = process.env) {
         widget: {
             api, guardado, git: gitReal, cwd, archivos: archivosDelRepo(avisar),
             buscarProyecto: configurarEnElMotor.buscarProyecto,
-            leerWidget: (a, clave, id) => leerWidget(a, clave, id, fetch),
+            leerWidget: (a, clave, id) => leerWidget(a, clave, id, fetch, avisar),
         },
         // 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.
@@ -522,6 +522,14 @@ export function entornoReal(env = process.env) {
             api, guardado, git: gitReal, cwd, avisar, archivos: archivosDelRepo(avisar), pruebas, generar: randomUUID, ahora: Date.now, dormir, tramoMs,
             buscarProyecto: configurarEnElMotor.buscarProyecto,
             leerDiagnostico: (a, clave, id) => leerDiagnostico(a, clave, id, fetch),
+            leerWidget: (a, clave, id) => leerWidget(a, clave, id, fetch, avisar),
+            existe: (p) => { try {
+                lstatSync(p);
+                return true;
+            }
+            catch {
+                return false;
+            } },
             pedirPrueba: (a, clave, id, intento) => pedirPrueba(a, clave, id, intento, fetch),
             leerPrueba: (a, clave, id, pruebaId, plazoMs) => leerPrueba(a, clave, id, pruebaId, fetch, plazoMs),
         },

package/dist/flags-por-comando.js

@@ -28,8 +28,12 @@ export const FLAGS_POR_COMANDO = [
         flags: ["authorizeSpend", "ceiling", "expectPolicy", "message", "testId"], comandos: ["test"],
         texto: "--authorize-spend, --ceiling, --expect-policy, --message and --test-id belong to `supcoflow test`.",
     },
-    { flags: ["skill", "app"], comandos: ["install record"], texto: "--skill and --app belong to `supcoflow install record`." },
+    { flags: ["skill", "app", "shape"], comandos: ["install record"], texto: "--skill, --app and --shape belong to `supcoflow install record`." },
 ];
+/** `--file` se repite sólo en `install record` (la interfaz propia vive en varios archivos); en los demás va una vez. */
+export function archivosDeMas(comando, cuantos) {
+    return cuantos > 1 && comando !== "install record" ? "--file goes once, with a value. Try `supcoflow --help`." : null;
+}
 /** El mensaje del primer flag presente que el comando no acepta, o null si todo aplica. */
 export function flagQueNoAplica(comando, presentes) {
     for (const regla of FLAGS_POR_COMANDO) {

package/dist/instalacion.js

@@ -1,4 +1,4 @@
-// `.supcoflow/instalacion.json` (bloque 6, decisión 3; v2 en la 0.8.0): con qué versiones se hizo la instalación, anotado en el
+// `.supcoflow/instalacion.json` (bloque 6, decisión 3; v2 en la 0.8.0; v3 en la 0.9.0): 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
@@ -7,9 +7,22 @@
 import { FalloDeLaTerminal, SALIDA, taparSecretos } from "./contrato.js";
 export const RUTA_DE_LA_INSTALACION = ".supcoflow/instalacion.json";
 export const PAQUETE_DEL_CHAT = "@supcoflow/chat";
+export const FORMAS = ["widget", "interfaz_propia"];
+export const MAX_ARCHIVOS_ANOTADOS = 20;
 // 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);
+/** Compara `major.minor.patch` número a número (1.10.0 > 1.9.0); lo que sigue al guion (prerelease) o al `+` no cuenta. */
+export function compararSemver(a, b) {
+    const partes = (v) => v.split(/[-+]/)[0].split(".").map(Number);
+    const [x, y] = [partes(a), partes(b)];
+    for (let i = 0; i < 3; i++) {
+        const d = (x[i] ?? 0) - (y[i] ?? 0);
+        if (d !== 0)
+            return d < 0 ? -1 : 1;
+    }
+    return 0;
+}
 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);
@@ -71,14 +84,26 @@ function guiaDe(c) {
         return { origen: "agente", version: g.version };
     throw inesperada("a guide");
 }
+// El `contract.json` del paquete instalado (T1 del sdk): sólo se copia su `version`, nunca el resto. Ausente es null (un
+// paquete anterior al contrato); presente sin una versión que se entienda NO es null: diría que no hay contrato.
+function contratoDe(contrato) {
+    if (contrato === null || contrato === undefined)
+        return null;
+    const v = objeto(contrato)?.version;
+    if (typeof v !== "string" || !esSemver(v))
+        throw ilegible(`The contract.json of ${PAQUETE_DEL_CHAT} has no version I understand.`);
+    return v;
+}
 export function armarInstalacion(i) {
     return {
-        version: 2,
+        version: 3,
         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) },
-        archivo: i.archivo ?? null,
+        forma: i.forma ?? null,
+        archivos: [...(i.archivos ?? [])],
+        contrato: contratoDe(i.contrato),
     };
 }
 // ─── El archivo del chat (`install record --file`) ───
@@ -99,25 +124,73 @@ export function validarElArchivoDelChat(crudo) {
         return { ok: false, motivo: "--file is the chat file, not a folder: say its path." };
     return { ok: true, ruta: partes.join("/") };
 }
-/** El `archivo` anotado en un `instalacion.json` ya existente: v1 y cualquier cosa ilegible o inválida dan null (nunca un error). */
-export function archivoAnotado(texto) {
+const SIN_NADA = { forma: null, archivos: [], contrato: null };
+// Una lista de rutas anotadas: cada una tiene que ser válida Y estar ya normalizada (es como la escribe esta terminal); lo
+// que no, se descarta de a una, sin error. Sin repetidas y con tope.
+function rutasAnotadas(v) {
+    if (!Array.isArray(v))
+        return [];
+    const rutas = [];
+    for (const a of v) {
+        if (typeof a !== "string")
+            continue;
+        const r = validarElArchivoDelChat(a);
+        if (r.ok && r.ruta === a && !rutas.includes(a) && rutas.length < MAX_ARCHIVOS_ANOTADOS)
+            rutas.push(a);
+    }
+    return rutas;
+}
+/**
+ * Lo que un `instalacion.json` ya existente dice de la forma, los archivos y el contrato. v1 y cualquier cosa ilegible o inválida
+ * dan «nada»; una versión que esta terminal no conoce (4 o más) tampoco se adivina. Nunca un error.
+ */
+export function leerInstalacionAnotada(texto) {
     if (texto === null)
-        return null;
+        return { estado: "ausente" };
     let v;
     try {
         v = JSON.parse(texto);
     }
     catch {
-        return null;
+        return { estado: "ilegible" };
     }
-    // AD9: un v1 se reconoce por `version: 1` (lo escribe la terminal 0.7.0) y no tiene archivo, aunque el campo aparezca.
-    if (objeto(v)?.version === 1)
-        return null;
-    const a = objeto(v)?.archivo;
-    if (typeof a !== "string")
-        return null;
-    const r = validarElArchivoDelChat(a);
-    return r.ok && r.ruta === a ? a : null;
+    const o = objeto(v);
+    if (o === null)
+        return { estado: "ilegible" };
+    // Antes de la 0.9.0 la única forma que existía era el widget: una v1 o una v2 son un widget, con el archivo que la v2 anotó (si lo
+    // anotó; la v1 no tiene archivo aunque el campo aparezca).
+    if (o.version === 1)
+        return { estado: "leida", forma: "widget", archivos: [], contrato: null };
+    if (o.version === 2) {
+        const a = typeof o.archivo === "string" ? validarElArchivoDelChat(o.archivo) : null;
+        return { estado: "leida", forma: "widget", archivos: a !== null && a.ok && a.ruta === o.archivo ? [a.ruta] : [], contrato: null };
+    }
+    if (o.version === 3) {
+        const forma = FORMAS.find((f) => f === o.forma) ?? null;
+        const contrato = typeof o.contrato === "string" && esSemver(o.contrato) ? o.contrato : null;
+        return { estado: "leida", forma, archivos: rutasAnotadas(o.archivos), contrato };
+    }
+    if (typeof o.version === "number" && Number.isInteger(o.version) && o.version > 3)
+        return { estado: "mas_nueva" };
+    return { estado: "leida", ...SIN_NADA };
+}
+export function anotadoEn(texto) {
+    const l = leerInstalacionAnotada(texto);
+    return l.estado === "leida" ? { forma: l.forma, archivos: l.archivos, contrato: l.contrato } : SIN_NADA;
+}
+/** Valida y normaliza la lista de `--file`: cada ruta con `validarElArchivoDelChat`, sin repetidas, con tope. */
+export function validarLosArchivos(crudos) {
+    const rutas = [];
+    for (const crudo of crudos) {
+        const r = validarElArchivoDelChat(crudo);
+        if (!r.ok)
+            return r;
+        if (!rutas.includes(r.ruta))
+            rutas.push(r.ruta);
+    }
+    if (rutas.length > MAX_ARCHIVOS_ANOTADOS)
+        return { ok: false, motivo: `--file goes up to ${MAX_ARCHIVOS_ANOTADOS} times: the files of the chat, not the whole app.` };
+    return { ok: true, rutas };
 }
 // 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) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supcoflow",
-  "version": "0.8.1",
+  "version": "0.9.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" },