synthesisui 0.16.360 → 0.16.362

package/dist/agent-wiring.js

@@ -1,5 +1,6 @@
 import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
+import { hasCodexBlock, pinnedInCodex, withCodexBlock } from "./codex-mcp.js";
 const HOOK_MATCHER = "Write|Edit|MultiEdit";
 /**
  * Exportado porque a REGRA é uma só: a pasta de uma ferramenta é a evidência de que ela é usada, e
@@ -222,8 +223,56 @@ async function wireMcp(root, version) {
             path: ".cursor/mcp.json",
             status: await wireMcpAt(root, version, ".cursor/mcp.json"),
         });
+    /**
+     * E O CODEX, quando `.codex/` já existe - a mesma regra de evidência que decide o Cursor e a casa
+     * do bloco (`bornWhen`): a pasta da ferramenta é a prova de que ela é usada.
+     *
+     * Formato diferente, escritor diferente: aquele lê e reescreve um objeto JSON; este é dono de uma
+     * região delimitada num TOML que a pessoa também edita. Ver `codex-mcp.ts` para o porquê de não
+     * haver parser.
+     */
+    if (await exists(join(root, ".codex")))
+        wrote.push({
+            path: ".codex/config.toml",
+            status: await wireCodexMcp(root, version),
+        });
     return wrote;
 }
+/**
+ * A REGIÃO DO SYNTHESISUI NO `.codex/config.toml` - escrita só quando muda.
+ *
+ * `already there` quando o arquivo já diz exatamente isto, e é o que faz um `connect` seguido dizer
+ * "nada a mudar" em vez de anunciar uma escrita que não aconteceu.
+ */
+/**
+ * A VERSÃO QUE ESTAVA PINADA NO `.codex/config.toml` ANTES desta rodada - `null` quando não havia.
+ *
+ * Variável de módulo e não retorno porque o tipo de `wireMcp` é compartilhado com os dois
+ * escritores de JSON, e alargá-lo para um campo que só o Codex preenche faria os outros dois
+ * carregarem um `undefined` para sempre.
+ */
+let codexWas = null;
+/** O que a rodada anterior havia pinado no Codex - para a tela poder dizer de onde veio. */
+export function codexPinBefore() {
+    return codexWas;
+}
+async function wireCodexMcp(root, version) {
+    const path = join(root, ".codex", "config.toml");
+    const current = await readFile(path, "utf8").catch(() => null);
+    const had = current != null && hasCodexBlock(current);
+    const next = withCodexBlock(current ?? "", version);
+    if (current === next)
+        return "already there";
+    /**
+     * A VERSÃO DE ONDE ELE SAIU, para a linha da tela dizer "veio da 0.16.361" em vez de só
+     * "atualizado" - a mesma correção que o hook recebeu em 06/08, quando "already had it" escondia
+     * um pin velho.
+     */
+    codexWas = pinnedInCodex(current ?? "");
+    await mkdir(dirname(path), { recursive: true }).catch(() => { });
+    await writeFile(path, next, "utf8");
+    return had ? "updated" : "added";
+}
 export async function wireAgent(root, version, want) {
     const proposed = await hookCommand(root, version);
     const hook = want.hook

package/dist/codex-mcp.js

@@ -0,0 +1,85 @@
+/**
+ * AS FERRAMENTAS DO SISTEMA DENTRO DO CODEX - a metade que faltava para o agente dele saber tanto
+ * quanto o do Claude Code.
+ *
+ * O QUE O CLIENTE GANHA: num repositório com `.codex/`, o agente dele passa a poder PERGUNTAR ao
+ * sistema - como um valor se chama, que componentes existem, o que a esteira não leu - em vez de
+ * adivinhar. Antes ele recebia as regras (`AGENTS.md`) e nenhuma ferramenta: sabia o que obedecer e
+ * não tinha como consultar.
+ *
+ * O DEFEITO, medido em 03/09 no repositório do dono: `.codex/config.toml` estava lá desde sempre, o
+ * `AGENTS.md` passou a nascer daquela pasta, e as 19 ferramentas continuavam existindo só para o
+ * Claude Code e o Cursor. A causa é de formato: aqueles dois compartilham o MESMO objeto JSON
+ * (`mcpServers`), então cobrir o segundo custou um `writeFile` a mais. O Codex declara em TOML, sob
+ * `[mcp_servers.<nome>]`, e nenhuma linha do nosso escritor de JSON serve.
+ *
+ * TRÊS NÍVEIS, E A GENTE ESCREVE NO DE PROJETO. O Codex lê `/etc/codex/config.toml`,
+ * `~/.codex/config.toml` e `.codex/config.toml`, cada um sobrepondo o de cima. O de projeto é o
+ * lugar certo para um servidor que vale para UM repositório - e é o único que não é território de
+ * fora: escrever no `~/.codex/config.toml` seria a mesma fronteira do `.zshrc`, que este produto
+ * atravessa só perguntando.
+ *
+ * SEM PARSER DE TOML, E ISSO É UMA DECISÃO. Escrever TOML genérico exigiria ler o arquivo inteiro,
+ * entender e reserializar - e uma reserialização perde comentário, ordem e formatação de quem
+ * escreveu aquilo à mão. O `.codex/config.toml` do dono tem um `[tui]` com a barra de status dele:
+ * um arquivo que volta reordenado é um arquivo que ele não reconhece.
+ *
+ * Então a gente é dona de uma REGIÃO DELIMITADA, exatamente como no `CLAUDE.md` e no hook de
+ * shell - o resto do arquivo passa por aqui sem ser tocado, byte por byte.
+ */
+const BEGIN = "# synthesisui:start";
+const END = "# synthesisui:end";
+/** Já existe região nossa neste arquivo? */
+export function hasCodexBlock(text) {
+    return text.includes(BEGIN);
+}
+/**
+ * A versão pinada dentro da nossa região - `null` quando não há região ou quando ela não pina.
+ *
+ * O `connect` usa isto para dizer de ONDE para onde a fiação andou, que é a diferença entre
+ * "atualizei" e uma linha que a pessoa fecha sem ler.
+ */
+export function pinnedInCodex(text) {
+    const start = text.indexOf(BEGIN);
+    if (start === -1)
+        return null;
+    const end = text.indexOf(END, start);
+    const region = text.slice(start, end === -1 ? undefined : end);
+    return region.match(/synthesisui@(\d+\.\d+\.\d+)/)?.[1] ?? null;
+}
+/**
+ * A REGIÃO, montada. `args` em duas partes porque é assim que o Codex quer a linha de comando:
+ * o executável em `command`, e o resto quebrado em array.
+ */
+export function codexBlock(version) {
+    return [
+        BEGIN,
+        "# Managed by synthesisui. Edit outside this block; this region is rewritten on connect.",
+        "[mcp_servers.synthesisui]",
+        'command = "npx"',
+        `args = ["synthesisui@${version}", "mcp"]`,
+        END,
+    ].join("\n");
+}
+/**
+ * O arquivo com a nossa região em dia, e TODO o resto intocado.
+ *
+ * Sem região: acrescenta no fim, com uma linha em branco antes - um `[mcp_servers.x]` colado no
+ * fim de outra tabela TOML entraria DENTRO dela.
+ *
+ * Com região: troca só o que está entre as marcas.
+ *
+ * MARCA DE ABERTURA SEM A DE FECHAMENTO significa que alguém editou à mão e o fechamento se
+ * perdeu. Aí a gente devolve o arquivo COMO ESTÁ: apagar até o fim seria destruir o que vem
+ * depois, e é a mesma decisão que o `withHook` toma no perfil de shell.
+ */
+export function withCodexBlock(text, version) {
+    const block = codexBlock(version);
+    if (!hasCodexBlock(text))
+        return `${text.replace(/\n*$/, "")}\n\n${block}\n`.replace(/^\n+/, "");
+    const start = text.indexOf(BEGIN);
+    const end = text.indexOf(END, start);
+    if (end === -1)
+        return text;
+    return text.slice(0, start) + block + text.slice(end + END.length);
+}

package/dist/commands/align.js

@@ -9,6 +9,7 @@ import { unsentEvents } from "../doctor/ledger.js";
 import { readRequests } from "../doctor/requests.js";
 import { declaredReference } from "../group-role.js";
 import { CHECKER_SINCE, installedBehind, MATERIALISER_SINCE, READER_SINCE, } from "../install-marks.js";
+import { fmt, say } from "../lang.js";
 import { measuredScope } from "../measured-scope.js";
 import { body, bodyWrapped, paint, section, snippet } from "../output.js";
 import { SKILLS } from "../skills.js";
@@ -648,7 +649,7 @@ export async function nextStepFor(root) {
  * traz as linhas em branco de graça, que é o "respiro" pedido.
  */
 export function renderNextStep(next, freshSession) {
-    const lines = [section("Do this next")];
+    const lines = [section(say("Do this next"))];
     /**
      * NUMERA SÓ QUANDO SÃO DOIS PASSOS. Abrir o agente e falar com ele são duas coisas, e sem o "1" e
      * o "2" a pessoa lê dois blocos azuis e não sabe se escolhe um ou faz os dois. Com um passo só, o
@@ -656,32 +657,48 @@ export function renderNextStep(next, freshSession) {
      */
     const numbered = Boolean(next.open?.length && next.say);
     if (next.open?.length) {
-        lines.push(body(numbered ? `1  ${next.headline}` : next.headline), "");
+        lines.push(body(numbered ? `1  ${say(next.headline)}` : say(next.headline)), "");
         lines.push(paint.blue(snippet(next.open)), "");
     }
     if (next.say) {
         if (next.open?.length)
-            lines.push(body(numbered ? "2  and say" : "and say"), "");
+            lines.push(body(numbered ? `2  ${say("and say")}` : say("and say")), "");
         else
-            lines.push(body(`${next.headline} and say:`), "");
+            lines.push(body(`${say(next.headline)} ${say("and say")}:`), "");
         lines.push(paint.blue(snippet([next.say])), "");
     }
     if (next.run?.length) {
-        lines.push(body(next.headline), "");
+        lines.push(body(say(next.headline)), "");
         lines.push(paint.blue(snippet(next.run)), "");
     }
-    lines.push(...bodyWrapped(next.why).map(paint.dim));
+    lines.push(...bodyWrapped(say(next.why)).map(paint.dim));
     /** O que a flag dispensa, dito - ver `OPENS` em `claude-md.ts`. E concordando: um repo com um
      *  agente só recebe uma linha no singular, porque "those flags" sobre um comando lê como se a
      *  pessoa tivesse perdido uma opção da tela. */
     if (next.open?.length)
         lines.push(...bodyWrapped(next.open.length === 1
-            ? "That flag lets it write without asking each time. Drop it to approve every change yourself."
-            : "Those flags let it write without asking each time. Drop them to approve every change yourself.").map(paint.dim));
-    if (freshSession)
-        lines.push(...bodyWrapped(freshSession.mcp
-            ? "A new session is what loads the skills and tools just installed, and the project's tools ask for approval once - say yes."
-            : "A new session is what loads the skills just installed.").map(paint.dim));
+            ? say("Drop the flag to approve each write yourself.")
+            : say("Drop the flags to approve each write yourself.")).map(paint.dim));
+    if (freshSession) {
+        const list = freshSession.loads;
+        const said = list.length === 0
+            ? "and"
+            : list.length === 1
+                ? list[0]
+                : /** O conector também é língua: "and" em inglês, "e" em português - e a vírgula do
+                   *  penúltimo é a mesma nas duas, então só o último elo entra na tabela. */
+                    fmt("{head} and {last}", {
+                        head: list.slice(0, -1).join(", "),
+                        last: String(list.at(-1)),
+                    });
+        lines.push(...bodyWrapped(list.length === 0
+            ? say("A new session reads the wiring this run changed.")
+            : fmt(list.length === 1
+                ? "This run moved {what}, and a new session is what reads it."
+                : "This run moved {what}, and a new session is what reads them.", { what: said })).map(paint.dim));
+        if (freshSession.mcp)
+            lines.push(...bodyWrapped(say("The project's tools ask for approval once - say yes.")).map(paint.dim));
+    }
     return lines.join("\n");
 }
 /**

package/dist/commands/connect.js

@@ -1,9 +1,10 @@
 import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
 import { dirname, join } from "node:path";
-import { wireAgent } from "../agent-wiring.js";
+import { codexPinBefore, wireAgent } from "../agent-wiring.js";
 import { blockHomes, syncClaudeMd } from "../claude-md.js";
 import { resolveRegistry } from "../config.js";
-import { body, paint, section, snippet } from "../output.js";
+import { fmt, say } from "../lang.js";
+import { body, bodyWrapped, paint, section, snippet } from "../output.js";
 import { readShellAnswer, rememberShellNo } from "../shell-answer.js";
 import { existingRc, hasHook, pinnedInHook, rcPathFor, shellFrom, shellSnippet, withHook, } from "../shell-hook.js";
 import { SKILLS } from "../skills.js";
@@ -173,8 +174,12 @@ version) {
         return;
     }
     console.log("");
-    console.log(body("Your editor tells you when this repo drifts, once a session. Your terminal does not, and that is where most people notice something is stale."));
-    console.log(body(paint.faint(`Adding it writes one block to ${rc}. It stays silent when nothing is wrong, never blocks your prompt, and checks at most once an hour.`)));
+    /**
+     * A OFERTA EM DUAS LINHAS - eram cinco, e ela ficava entre a lista do que foi instalado e a ação
+     * recomendada, empurrando para baixo a única coisa que a pessoa procurava. O que ela precisa dizer
+     * é o que ganha, o que a gente escreve e onde: nada disso saiu.
+     */
+    console.log(bodyWrapped(fmt("Your terminal can warn you when this repo drifts - one block in {rc}, silent unless something is wrong, at most once an hour.", { rc })).join("\n"));
     if (!process.stdin.isTTY || !process.stdout.isTTY) {
         console.log(body(paint.blue("  npx synthesisui@latest connect --shell")));
         return;
@@ -227,7 +232,40 @@ export async function connect(opts) {
     // The block reads the settings we just wrote, so it must be regenerated
     // after them, not before.
     const contract = await syncClaudeMd(root);
-    console.log(section("Connected"));
+    console.log(section(say("Connected")));
+    /**
+     * A LISTA DA TELA, JUNTADA ANTES DE IMPRIMIR - e é isto que faz a rodada silenciosa caber numa
+     * linha.
+     *
+     * O QUE O CLIENTE GANHA: ele lê o que MUDOU, e o que não mudou vira uma linha só. Medido em 03/09
+     * na segunda rodada deste comando: 41 linhas na tela, das quais 10 diziam `already had it` /
+     * `already current` - um quarto da tela informando ausência de novidade, exatamente entre a pessoa
+     * e a única instrução que ela procurava.
+     *
+     * A DISTINÇÃO NÃO SE PERDE: cada peça que mudou continua nomeada, com o seu detalhe embaixo. O que
+     * colapsa é o silêncio, que não tem detalhe para dar.
+     */
+    const rows = [];
+    const row = (moved, line, under) => {
+        rows.push({ moved, line, ...(under ? { under } : {}) });
+    };
+    const flush = () => {
+        for (const r of rows) {
+            if (!r.moved)
+                continue;
+            console.log(body(r.line));
+            if (r.under)
+                console.log(snippet([r.under]));
+        }
+        const quiet = rows.filter((r) => !r.moved).length;
+        if (quiet === 0)
+            return;
+        console.log(body(paint.dim(quiet === rows.length
+            ? say("· nothing to change - this environment is already current")
+            : fmt(quiet === 1
+                ? "· {n} other piece already current"
+                : "· {n} other pieces already current", { n: quiet }))));
+    };
     /**
      * E O QUE FALTA, DITO EM VOZ ALTA - porque este comando estava mentindo por omissão.
      *
@@ -240,45 +278,61 @@ export async function connect(opts) {
      * `CLAUDE.md`, achou o bloco vazio, e não havia nada dizendo que faltava um comando. Lacuna
      * silenciosa é o que faz um produto correto parecer quebrado.
      *
-     * E SÃO DOIS CAMINHOS, não um. A primeira versão desta mensagem mandava `add <slug>` e só - o que
-     * desorienta justamente quem acabou de rodar `connect` num projeto que AINDA NÃO TEM sistema, que é
-     * a primeira corrida e o caso mais comum. Para essa pessoa o passo seguinte é a skill que este mesmo
-     * comando acabou de instalar, e não um comando de terminal. Quem já tem sistema na plataforma é o
-     * outro caso, e ele também é dito.
+     * E ELE DIZ A LACUNA, NÃO O QUE FAZER - corrigido em 03/09, com o dono lendo a própria tela.
+     *
+     * Ele carregava os dois caminhos ("ask the agent for `/sui-init`" e "`synthesisui add <slug>`"), e
+     * o resultado era UMA TELA COM DUAS INSTRUÇÕES para o mesmo passo: esta linha mandava pedir uma
+     * slash command, e a ação recomendada, quinze linhas abaixo, mandava dizer uma frase. Quem lê não
+     * tem como saber qual das duas é a certa.
+     *
+     * E A FRASE É A CERTA, por decisão de produto (dono, 03/09): *"as skills são chamadas de acordo
+     * com a necessidade que o Claude vai encontrando, não por comando nosso diretamente"*. Nomear
+     * `/sui-init` ensina o cliente a dirigir o agente por comando, que é o oposto de como a esteira
+     * foi desenhada - e amarra a instrução ao nome de uma skill que pode ser dividida amanhã.
+     *
+     * `nextStepFor` JÁ COBRE OS DOIS CAMINHOS, e com a mesma distinção: medido sem sistema instalado
+     * leva a `list --mine` + `add <slug>`; nunca medido leva à frase. Então isto para de repeti-los e
+     * fica com o que só ele diz - a CONSEQUÊNCIA da lacuna, que é o que fez alguém perder tempo em
+     * 20/08 achando o bloco do `CLAUDE.md` vazio sem nada explicando por quê.
      */
     const anyInstalled = (await installedSlugs(root).catch(() => [])).length > 0;
     if (!anyInstalled)
-        console.log(body("· no design system installed here yet - the agent has no index, and memory has nothing to belong to.\n  This repo has none yet:  ask the agent for `/sui-init`, or `/sui-import-ds` to turn this project into one.\n  You already have one:     `synthesisui list` shows them, `synthesisui add <slug>` brings it in."));
+        console.log(bodyWrapped(say("· no design system installed here yet - the agent has no index, and memory has nothing to belong to.")).join("\n"));
     /**
      * O QUE ESTE CLI REESCREVEU NA PASTA DO SISTEMA - dito primeiro, porque é o que a pessoa não sabia
      * que estava devendo. Ela rodou `connect` para atualizar a fiação; os arquivos do install estarem
      * velhos era invisível, e o `upgrade` não alcançava (ver `refreshInstall`).
      */
     if (refreshed)
-        console.log(body(`✓ _synthesisui/ds/${refreshed.slug}/  rewritten by this CLI${refreshed.was
+        row(true, `✓ _synthesisui/ds/${refreshed.slug}/  rewritten by this CLI${refreshed.was
             ? ` - it was written by ${refreshed.was}`
-            : " - it carried no CLI version, so it predates this"}`));
+            : " - it carried no CLI version, so it predates this"}`);
     if (want.hook) {
-        console.log(body(wired.hook === "added"
-            ? "✓ .claude/settings.json  the check now runs after every write"
-            : wired.hook === "updated"
-                ? /**
-                   * A LINHA QUE FALTAVA, e a ausência dela fazia o comando mentir: rodando o 0.16.157, a
-                   * saída dizia "already had it" e imprimia `npx synthesisui@0.16.153 hook` embaixo
-                   * (dono, 06/08). Quem lê "already had it" fecha o terminal.
-                   */
-                    `✓ .claude/settings.json  the check moved from ${wired.was?.match(/synthesisui@(\d+\.\d+\.\d+)/)?.[1] ?? "an older version"} to this one`
-                : "· .claude/settings.json  already had it"));
-        console.log(snippet([wired.command]));
+        row(wired.hook !== "already there", (() => {
+            return wired.hook === "added"
+                ? say("✓ .claude/settings.json  the check now runs after every write")
+                : wired.hook === "updated"
+                    ? /**
+                       * A LINHA QUE FALTAVA, e a ausência dela fazia o comando mentir: rodando o 0.16.157, a
+                       * saída dizia "already had it" e imprimia `npx synthesisui@0.16.153 hook` embaixo
+                       * (dono, 06/08). Quem lê "already had it" fecha o terminal.
+                       */
+                        `✓ .claude/settings.json  the check moved from ${wired.was?.match(/synthesisui@(\d+\.\d+\.\d+)/)?.[1] ?? "an older version"} to this one`
+                    : say("· .claude/settings.json  already had it");
+        })(), wired.command);
         /**
          * A SEGUNDA COSTURA, dita por nome. As onze ferramentas MCP são PULL e o hook de escrita roda
          * DEPOIS de uma escrita - nenhum dos dois chega a tempo de dizer "você não está logado nesta
          * máquina" ou "este sistema não sabe de onde foi medido". O `SessionStart` é o único que chega.
          */
         if (wired.session !== "skipped")
-            console.log(body(wired.session === "already there"
-                ? "· .claude/settings.json  the session check was already there"
-                : `✓ .claude/settings.json  every session now opens with what this environment is missing${wired.session === "updated" ? ", pointed at this version" : ""}`));
+            row(wired.session !== "already there", wired.session === "already there"
+                ? say("· .claude/settings.json  the session check was already there")
+                : wired.session === "updated"
+                    ? /** A distinção `added` x `updated` vale desde 06/08: um estado que não se
+                       *  distingue de "nada a fazer" faz a instrução de atualizar mentir. */
+                        say("✓ .claude/settings.json  the session check moved to this one")
+                    : say("✓ .claude/settings.json  each session opens with what is missing"));
     }
     /**
      * OS CAMINHOS DE MCP, POR NOME - e o número vem da LISTA, não da minha memória.
@@ -289,13 +343,22 @@ export async function connect(opts) {
      */
     if (want.mcp && wired.mcp !== "skipped") {
         for (const one of wired.mcp)
-            console.log(body(one.status === "added"
-                ? `✓ ${one.path.padEnd(22)} ${MCP_TOOL_COUNT} tools, so the agent can ask instead of guess`
+            row(one.status !== "already there", one.status === "added"
+                ? `✓ ${one.path.padEnd(22)} ${fmt("{n} tools the agent can ask", { n: MCP_TOOL_COUNT })}`
                 : one.status === "updated"
-                    ? /** Uma entrada pinada antes de o MCP flutuar ficava pinada para sempre - nenhum
-                       *  `connect` a soltava, e o agente segurava um leitor velho sem saber. */
-                        `✓ ${one.path.padEnd(22)} unpinned - it now follows the published reader`
-                    : `· ${one.path.padEnd(22)} already had it`));
+                    ? /**
+                       * DUAS HISTÓRIAS DIFERENTES SOB O MESMO `updated`, e dizer a errada é pior que não
+                       * dizer: no Claude Code e no Cursor a entrada é SOLTA (`@latest`), então o que
+                       * mudou é ela parar de segurar um leitor velho. No Codex a entrada é PINADA numa
+                       * versão, e o que mudou é de qual para qual - a mesma correção que o hook recebeu
+                       * em 06/08, quando "already had it" escondia um pin antigo.
+                       */
+                        one.path.endsWith(".toml")
+                            ? `✓ ${one.path.padEnd(22)} ${fmt(codexPinBefore()
+                                ? "the tools moved from {was} to this one"
+                                : "{n} tools the agent can ask", { was: codexPinBefore() ?? "", n: MCP_TOOL_COUNT })}`
+                            : `✓ ${one.path.padEnd(22)} ${say("unpinned - it follows the published reader")}`
+                    : `· ${one.path.padEnd(22)} ${say("already had it")}`);
     }
     /**
      * ONDE O BLOCO CAIU, DITO POR NOME.
@@ -311,7 +374,7 @@ export async function connect(opts) {
      */
     for (const home of await blockHomes(root)) {
         const moved = contract.changed.includes(home);
-        console.log(body(`${moved ? "✓" : "·"} ${home.padEnd(22)} ${moved
+        row(moved, `${moved ? "✓" : "·"} ${home.padEnd(22)} ${moved
             ? home === "CLAUDE.md"
                 ? /**
                    * A FRASE DIZ O QUE O BLOCO CARREGA, e ela descrevia um conteúdo que não existia.
@@ -321,12 +384,12 @@ export async function connect(opts) {
                    * fazer, e a linha diz qual dos dois ele é (dono, 21/08).
                    */
                     contract.count === 0
-                        ? "how to turn this repo into your system"
-                        : "rewritten for what is installed"
-                : "the same rules, where this agent reads them"
+                        ? say("how to turn this repo into your system")
+                        : say("rewritten for what is installed")
+                : say("the same rules, where this agent reads")
             : contract.count === 0
-                ? "already says how to start"
-                : "already says what is installed"}`));
+                ? say("already says how to start")
+                : say("already says what is installed")}`);
     }
     /**
      * The fourth layer, and the one that had no installer at all: the import
@@ -369,21 +432,26 @@ export async function connect(opts) {
         if (had == null)
             continue;
         await rm(dir, { recursive: true, force: true }).catch(() => { });
-        console.log(body(`✕ /${legacy.padEnd(21)} removed - renamed to /sui-import-ds`));
+        row(true, `✕ /${legacy.padEnd(21)} ${say("removed - renamed to /sui-import-ds")}`);
     }
+    /** Se ALGUMA skill mudou nesta rodada - é o que autoriza a frase da sessão nova a citá-las. */
+    let skillsMoved = false;
     for (const skill of skills) {
         const skillPath = join(root, skill.path);
         const before = await readFile(skillPath, "utf8").catch(() => null);
         if (before !== skill.source) {
             await mkdir(dirname(skillPath), { recursive: true });
             await writeFile(skillPath, skill.source, "utf8");
+            skillsMoved = true;
         }
-        console.log(body(before === skill.source
-            ? `· ${skill.label.padEnd(22)} already current`
+        row(before !== skill.source, before === skill.source
+            ? `· ${skill.label.padEnd(22)} ${say("already current")}`
             : before == null
-                ? `✓ ${skill.label.padEnd(22)} ${skill.what}`
-                : `✓ ${skill.label.padEnd(22)} updated to this CLI's pipeline`));
+                ? `✓ ${skill.label.padEnd(22)} ${say(skill.what)}`
+                : `✓ ${skill.label.padEnd(22)} ${say("updated to this CLI's pipeline")}`);
     }
+    /** A tela sai agora, junta: o que mudou por nome, e o silêncio numa linha. */
+    flush();
     /**
      * O CI: escrito quando pedido, e NÃO MAIS OFERECIDO aqui.
      *
@@ -419,9 +487,29 @@ export async function connect(opts) {
     const mcpMoved = Boolean(want.mcp &&
         Array.isArray(wired.mcp) &&
         wired.mcp.some((m) => moved(m.status)));
+    /**
+     * O QUE ESTA RODADA MOVEU, PELO NOME - e são os nomes que a pessoa acabou de ler nas linhas com
+     * `✓`, não os nossos nomes internos. Uma razão que ela pode conferir contra a própria tela.
+     */
+    const bothChecks = moved(wired.hook) && moved(wired.session);
+    const loads = [
+        /** Os dois checks juntos viram "the checks": nomeá-los separados custava uma linha inteira da
+         *  tela para uma distinção que não muda nada do que a pessoa faz em seguida. */
+        ...(bothChecks
+            ? [say("the checks")]
+            : moved(wired.hook)
+                ? [say("the write check")]
+                : moved(wired.session)
+                    ? [say("the session check")]
+                    : []),
+        ...(mcpMoved ? [say("the tools")] : []),
+        ...(skillsMoved ? [say("the skills")] : []),
+    ];
     await reportWhatIsLeft(root, {
         cli: opts.version,
-        ...(needsRestart ? { freshSession: { mcp: mcpMoved } } : {}),
+        ...(needsRestart || skillsMoved
+            ? { freshSession: { loads, mcp: mcpMoved } }
+            : {}),
     });
     /**
      * O CUSTO DO HOOK, DITO SEM UM NÚMERO QUE NÃO É NOSSO.
@@ -437,11 +525,20 @@ export async function connect(opts) {
      * que se sustenta.
      */
     if (wired.command.startsWith("npx synthesisui@")) {
+        /**
+         * O CUSTO DO HOOK, EM UMA LINHA - eram cinco, e elas fechavam a tela.
+         *
+         * Medido em 03/09: a tela do `connect` tinha 41 linhas, e este parágrafo era 5 delas, na última
+         * posição, falando de resolução de pacote npm. Para quem acabou de instalar, é o assunto mais
+         * distante do design system dele possível, no momento em que ele deveria estar abrindo o agente.
+         *
+         * A METADE QUE FICA É A ACIONÁVEL. O diagnóstico completo - por que o npx custa, o que foi
+         * medido, quanto o caminho local ganhou - vive na documentação do comando, guardado por
+         * `apps/web/src/lib/cli/commands.spec.ts`.
+         */
         console.log("");
-        console.log(body(paint.dim("The hook runs through npx, which resolves this package against the")));
-        console.log(body(paint.dim("registry on every edit - that wait is the network, not the check itself")));
-        console.log(body(paint.dim("(the analysis is about 80ms). Adding synthesisui to your devDependencies")));
-        console.log(body(paint.dim("makes npx resolve it locally instead, which is several times faster;")));
-        console.log(body(paint.dim("run this again afterwards and it will switch by itself.")));
+        console.log(bodyWrapped(say("The hook resolves against the npm registry on each edit - that is the wait, not the check. Add synthesisui to your devDependencies and run this again; it switches by itself to local, several times faster."))
+            .map(paint.dim)
+            .join("\n"));
     }
 }

package/dist/commands/gaps.js

@@ -69,7 +69,19 @@ export async function gaps(opts) {
     const carried = await carriedByGlobals(root);
     if (carried) {
         console.log("");
-        console.log(body(`${carried.total} of those declarations are already in your system - ${carried.parts}. They are not component recipes, which is why they count as "not interpreted" above; they did arrive.`));
+        console.log(body(
+        /**
+         * AS DUAS UNIDADES, DITAS - e ler a frase antiga era fazer uma conta errada.
+         *
+         * Ela dizia "24 of those declarations are already in your system - 6 base rules, 1 of your
+         * utilities, 1 registered property", e 6+1+1 é 8. Os números são certos e contam coisas
+         * DIFERENTES: `total` soma DECLARAÇÕES, `parts` conta as REGRAS e os UTILITÁRIOS em que elas
+         * moram. Quem lê subtrai e não fecha - e um número que não fecha derruba a confiança nos
+         * outros da mesma tela, que estão certos. Visto pelo dono no primeiro import real, 03/09.
+         *
+         * `across` é a palavra que carrega a mudança de unidade.
+         */
+        `${carried.total} of those declarations are already in your system - across ${carried.parts}. They are not component recipes, which is why they count as "not interpreted" above; they did arrive.`));
     }
 }
 /**
@@ -109,10 +121,10 @@ async function carriedByGlobals(root) {
             continue;
         const parts = [
             (globals.base ?? []).length > 0
-                ? `${(globals.base ?? []).length} base rules`
+                ? `${(globals.base ?? []).length} base ${(globals.base ?? []).length === 1 ? "rule" : "rules"}`
                 : "",
             Object.keys(globals.utilities ?? {}).length > 0
-                ? `${Object.keys(globals.utilities ?? {}).length} of your utilities`
+                ? `${Object.keys(globals.utilities ?? {}).length} of your ${Object.keys(globals.utilities ?? {}).length === 1 ? "utilities entry" : "utilities"}`
                 : "",
             props > 0
                 ? `${props} registered ${props === 1 ? "property" : "properties"}`

package/dist/commands/import.js

@@ -1,5 +1,5 @@
 import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
-import { basename, dirname, join, relative, sep } from "node:path";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
 import { anatomyFromSketch } from "../anatomy-from-sketch.js";
 import { applyAnatomyPatch, hasEdits, } from "../anatomy-patch.js";
 import { resolveAnatomy, resolveFlatParts, safePartName, } from "../anatomy-read.js";
@@ -2771,6 +2771,11 @@ export async function takeCensus(root, opts) {
          * A primeira parece perfeita, e é isso que faz o defeito sobreviver. O `usage` estava dois campos
          * acima o tempo todo, gravado por este mesmo objeto - os dois chegam juntos e só um sobrevivia.
          */
+        /**
+         * A PROCEDÊNCIA, GRAVADA - ver `measured` no tipo. `basename` e não o caminho: o nome da pasta
+         * distingue dois monorepos parecidos sem mandar o diretório pessoal dele para o nosso servidor.
+         */
+        measured: { repo: basename(resolve(root)), at: new Date().toISOString() },
         ...(scopeLabel ? { scope: scopeLabel } : {}),
         /**
          * O DENOMINADOR DO FORA - ver `outside-scope.ts`.

package/dist/copy/connect.pt-BR.js

@@ -0,0 +1,104 @@
+import { register } from "../lang.js";
+/**
+ * A TELA DO `connect` EM PORTUGUÊS DO BRASIL - a primeira tela deste produto a falar outra língua.
+ *
+ * O QUE O CLIENTE GANHA: quem trabalha em português lê a nossa tela em português, sem uma pergunta
+ * a mais e sem misturar. O defeito que isto fecha foi medido no primeiro import real (03/09): o
+ * agente narra na língua da pessoa e os nossos blocos saíam em inglês, na mesma tela.
+ *
+ * ESTA TABELA É UMA PROMESSA COMPLETA, não um começo. `connect` está declarado em `COVERED` no
+ * `lang.ts`, e `connect-speaks.spec.ts` reprova se sobrar UMA frase da tela sem tradução aqui. É a
+ * diferença entre "traduzimos o connect" e "traduzimos parte do connect".
+ *
+ * AS TRÊS REGRAS QUE A TRADUÇÃO SEGUE, e nenhuma é estilística:
+ *
+ *   1. O NOME DA PEÇA NÃO TRADUZ. `hook`, `token`, `design system`, `commit` - são o vocabulário
+ *      de quem trabalha com isto, e "gancho" obrigaria a pessoa a traduzir de volta para entender.
+ *      O que traduz é a PROSA em volta deles.
+ *
+ *   2. CAMINHO, COMANDO E NÚMERO NÃO TRADUZEM. `.claude/settings.json` é o mesmo arquivo em toda
+ *      língua, e um caminho traduzido é um caminho que não existe.
+ *
+ *   3. A LARGURA CONTINUA VALENDO. A coluna da lista dá 39 colunas depois do prefixo (ver
+ *      `screen-fits.spec.ts`), e o português é tipicamente 15-20% mais longo que o inglês. Cada
+ *      linha desta tabela foi medida, não traduzida e esquecida.
+ */
+register("pt-BR", {
+    // ── as seções ──
+    Connected: "Conectado",
+    "Do this next": "Faça isto agora",
+    /** O último elo de uma lista - o resto da vírgula é igual nas duas línguas. */
+    "{head} and {last}": "{head} e {last}",
+    // ── o estado do repositório ──
+    "· no design system installed here yet - the agent has no index, and memory has nothing to belong to.": "· nenhum design system instalado aqui ainda - o agente não tem índice, e a memória não tem a que pertencer.",
+    // ── a fiação do agente ──
+    "✓ .claude/settings.json  the check now runs after every write": "✓ .claude/settings.json  a verificação roda após cada escrita",
+    "· .claude/settings.json  already had it": "· .claude/settings.json  já estava lá",
+    "✓ .claude/settings.json  each session opens with what is missing": "✓ .claude/settings.json  cada sessão abre com o que falta",
+    "✓ .claude/settings.json  the session check moved to this one": "✓ .claude/settings.json  a verificação de sessão veio para esta",
+    "· .claude/settings.json  the session check was already there": "· .claude/settings.json  a verificação de sessão já estava lá",
+    // ── o MCP e as skills ──
+    "{n} tools the agent can ask": "{n} ferramentas que o agente pode consultar",
+    "the tools moved from {was} to this one": "as ferramentas vieram da {was} para esta",
+    "unpinned - it follows the published reader": "solto - acompanha o leitor publicado",
+    "already had it": "já estava lá",
+    "already current": "já está em dia",
+    "updated to this CLI's pipeline": "atualizada para esta versão",
+    "removed - renamed to /sui-import-ds": "removida - virou /sui-import-ds",
+    // ── onde o bloco de regras caiu ──
+    "how to turn this repo into your system": "como transformar este repo no seu sistema",
+    "rewritten for what is installed": "reescrito para o que está instalado",
+    "the same rules, where this agent reads": "as mesmas regras, onde este agente lê",
+    "already says how to start": "já diz como começar",
+    "already says what is installed": "já diz o que está instalado",
+    /**
+     * O silêncio. "está em dia" é mais curto que "already current" e cabe com folga - a régua de
+     * largura vale igual aqui.
+     */
+    "· nothing to change - this environment is already current": "· nada a mudar - este ambiente já está em dia",
+    "· {n} other piece already current": "· mais {n} peça já em dia",
+    "· {n} other pieces already current": "· mais {n} peças já em dia",
+    // ── a oferta do terminal ──
+    "Your terminal can warn you when this repo drifts - one block in {rc}, silent unless something is wrong, at most once an hour.": "Seu terminal pode avisar quando este repo sair do sistema - um bloco em {rc}, calado a menos que algo esteja errado, no máximo uma vez por hora.",
+    // ── a ação recomendada ──
+    "and say": "e diga",
+    "Open a new agent session in this repo": "Abra uma sessão nova do agente neste repo",
+    /**
+     * A FRASE QUE ELE DIZ AO AGENTE **NÃO** TRADUZ, e é a decisão mais importante desta tabela.
+     *
+     * `import my design system` é o que ele digita, e as descrições das skills - que o agente lê para
+     * decidir qual usar - são em inglês. Traduzir a frase mandaria a pessoa dizer algo que o agente
+     * escolhe pior. É a mesma razão de `mcp.ts` nunca traduzir: onde a máquina lê, a precisão vence a
+     * gentileza. O dia em que as skills forem multilíngues, esta frase entra aqui.
+     */
+    "I read what is already in your code - the colours, the type, the shapes, the components. Nothing is invented.": "Eu leio o que já está no seu código - as cores, a tipografia, as formas, os componentes. Nada é inventado.",
+    "Drop the flag to approve each write yourself.": "Tire a flag para aprovar cada escrita você mesmo.",
+    "Drop the flags to approve each write yourself.": "Tire as flags para aprovar cada escrita você mesmo.",
+    /**
+     * `moveu` E NÃO `mexeu em` - e a razão é gramatical, não de gosto.
+     *
+     * Em português a preposição contrai com o artigo do que vem depois: "em" + "as verificações" é
+     * "NAS verificações", e "em" + "o hook" é "NO hook". O marcador `{what}` não sabe o gênero nem o
+     * número do que vai cair nele, então qualquer frase que ponha preposição antes dele sai errada em
+     * metade dos casos - saiu "mexeu em as verificações" na primeira medição. Um verbo transitivo
+     * direto resolve sem tabela de contração.
+     */
+    "This run moved {what}, and a new session is what reads it.": "Esta rodada moveu {what}, e é uma sessão nova que lê isso.",
+    "This run moved {what}, and a new session is what reads them.": "Esta rodada moveu {what}, e é uma sessão nova que lê isso.",
+    "A new session reads the wiring this run changed.": "Uma sessão nova lê a fiação que esta rodada mudou.",
+    "The project's tools ask for approval once - say yes.": "As ferramentas do projeto pedem aprovação uma vez - diga sim.",
+    // ── os nomes do que moveu, usados dentro da frase acima ──
+    "the checks": "as verificações",
+    "the write check": "a verificação de escrita",
+    "the session check": "a verificação de sessão",
+    "the tools": "as ferramentas",
+    "the skills": "as skills",
+    // ── o custo do hook ──
+    "The hook resolves against the npm registry on each edit - that is the wait, not the check. Add synthesisui to your devDependencies and run this again; it switches by itself to local, several times faster.": "O hook resolve no registro do npm a cada edição - a espera é isso, não a verificação. Adicione synthesisui às suas devDependencies e rode isto de novo; ele passa a resolver local sozinho, várias vezes mais rápido.",
+    // ── as descrições das skills ──
+    "the first run, start to finish": "o primeiro uso, do início ao fim",
+    "the import, orchestrated": "o import, orquestrado",
+    "one component against the system": "um componente contra o sistema",
+    "build what the system does not have": "construir o que o sistema não tem",
+    "the tokens, wired into your app": "os tokens, ligados no seu app",
+});

package/dist/doctor/gap-triage.js

@@ -77,7 +77,15 @@ function whereOf(shape, reason) {
                 }
                 : {
                     module: null,
-                    work: "no module owns this shape - a reader here is a new module, and it needs an app in the corpus before it exists",
+                    /**
+                     * DITO PELO EFEITO NO PROJETO DELE, não pela nossa condição interna.
+                     *
+                     * Dizia "it needs an app in the corpus before it exists" - `corpus` é o nosso conjunto
+                     * de medição, uma palavra que só existe dentro desta empresa, e ele não tem o que fazer
+                     * com essa informação. O que ELE precisa saber é que esta forma ainda não tem leitor e
+                     * que o pedido dele é o que a coloca na fila.
+                     */
+                    work: "nothing here reads this shape yet - ask for it and this file becomes the case that gets it built",
                 };
         }
         case "value-gap":
@@ -188,7 +196,18 @@ values) {
     const lines = values
         ? [
             ...describeValueRuler(values),
-            `The ${unread} style fragments not interpreted are sorted below by what to do about them.`,
+            /**
+             * A SEGUNDA FRASE CONTA OUTRA COISA, E PASSA A DIZER QUAL.
+             *
+             * A linha de cima fala em DECISÕES (1063, das quais 1005 interpretadas) e esta fala em
+             * FRAGMENTOS (32). Quem lê subtrai 1063-1005 = 58, vê 32 na linha seguinte, e as duas dizem
+             * "not interpreted". O comentário da régua única, logo acima, registra que esta tela já
+             * produziu uma segunda resposta uma vez - o percentual foi consertado, as CONTAGENS ficaram.
+             *
+             * Visto pelo dono no primeiro import real, 03/09. Um fragmento é um LUGAR onde a decisão
+             * mora, e é isso que a frase passa a dizer.
+             */
+            `They live in ${unread} ${unread === 1 ? "place" : "places"} in your code, sorted below by what to do about each.`,
         ]
         : [
             `${t.counted} style fragments accounted for, ${t.interpreted} interpreted (${t.percent}%). The ${unread} below are sorted by what to do about them.`,
@@ -197,7 +216,9 @@ values) {
         lines.push("", `MEASURED BY CLI ${t.measuredBy}, TRIAGED BY ${t.triagedBy}. Re-run \`import\` before concluding anything from the numbers below - a gap here may already be closed, and the work already done.`);
     }
     const label = {
-        "no-reader": "NO READER FOR THIS SHAPE - this is work",
+        /** `this is work` era o nosso bilhete de triagem na tela dele - trabalho de quem? A faixa já
+         *  diz o fato, e o que falta é dizer de quem é a vez: nossa. */
+        "no-reader": "NO READER FOR THIS SHAPE - ours to build",
         "value-gap": "THE SHAPE IS READ, THE VALUE IS NOT - a scale, not a reader",
         "by-design": "NOT A READING GAP - nothing a reader would change, and no work here",
     };

package/dist/doctor/style-ledger.js

@@ -399,7 +399,7 @@ values) {
          * valor está inteiramente no sistema, e o que falta é só saber qual elemento o veste.
          */
         const theirs = g.withTheirTokens && g.withTheirTokens > 0
-            ? ` — and ${g.withTheirTokens} of them already wear a token you declare, so their value is in the system`
+            ? ` - and ${g.withTheirTokens} of them already wear a token you declare, so their value is in the system`
             : "";
         lines.push(`  ${g.uses} ${g.shape}${g.uses === 1 ? "" : "s"} in ${g.files} file${g.files === 1 ? "" : "s"} - ${g.because}${theirs}`);
         /**
@@ -417,7 +417,13 @@ values) {
          * do cliente e ainda não foi tomada.
          */
         if (g.distinct !== undefined && g.distinct > g.unreadable.length)
-            lines.push(`      of ${g.distinct} distinct texts here, ${g.unreadable.length} travel with the census - a reader we publish later reaches those without you re-measuring, and the remaining ${g.distinct - g.unreadable.length} need this scan run again`);
+            lines.push(
+            /**
+             * `census` ERA O NOSSO NOME NA TELA DELE - trocado por "the measurement we already have",
+             * que é o que a palavra significa do lado dele. Pego pela régua de `INV-VOC-05` no dia em
+             * que `doctor/` entrou nela (03/09).
+             */
+            `      of ${g.distinct} distinct texts here, ${g.unreadable.length} travel with the measurement we already have - a reader we publish later reaches those without you running this again, and the remaining ${g.distinct - g.unreadable.length} need another scan`);
         for (const e of g.examples)
             lines.push(`      ${e.file}:${e.line}  ${e.text.slice(0, 80)}`);
     }

package/dist/index.js

@@ -2,6 +2,7 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 import { boolFlag, parseFlags } from "./cli-flags.js";
+import "./copy/connect.pt-BR.js";
 import { absorb } from "./commands/absorb.js";
 import { add } from "./commands/add.js";
 import { adopt } from "./commands/adopt.js";
@@ -31,6 +32,7 @@ import { upgrade } from "./commands/upgrade.js";
 import { use } from "./commands/use.js";
 import { appendEvent } from "./doctor/ledger.js";
 import { blueprintTarget, installedSlugs } from "./installed.js";
+import { useLang } from "./lang.js";
 import { RegistryError } from "./registry.js";
 /** Our own version, for pinning the hook and MCP commands we write into a
  *  project. Read from the package we are running out of, so a pinned command
@@ -158,6 +160,14 @@ async function main() {
     }
     const registry = typeof flags.registry === "string" ? flags.registry : undefined;
     const dir = typeof flags.dir === "string" ? flags.dir : undefined;
+    /**
+     * A LÍNGUA DESTA EXECUÇÃO, ligada UMA vez e antes de qualquer impressão.
+     *
+     * `useLang` só ativa outra língua se ESTE comando tem a tela coberta inteira (ver `COVERED` em
+     * `lang.ts`) - um comando de fora roda em inglês mesmo com o locale em português, porque meia
+     * tela traduzida é o defeito que aquele módulo existe para não cometer.
+     */
+    useLang(command, process.env);
     switch (command) {
         case "import":
             // The census is arithmetic over their files; --dry keeps it on disk.

package/dist/install-marks.js

@@ -162,7 +162,15 @@
  * O que o cliente ganha ao rodar `upgrade`: as regras do sistema passam a existir no arquivo que o
  * agente DELE lê, em vez de só no do Claude Code.
  */
-export const MATERIALISER_SINCE = "0.16.360";
+/**
+ * 0.16.360 -> 0.16.362 em 03/09: as ferramentas do sistema passam a ser fiadas no Codex. Num
+ * repositório com `.codex/`, `[mcp_servers.synthesisui]` nasce em `.codex/config.toml` - e é o
+ * `upgrade` que também chama `wireAgent`, então isto é ARQUIVO NOVO na pasta de quem já instalou.
+ *
+ * O que o cliente ganha ao rodar `upgrade`: o agente dele no Codex passa a poder PERGUNTAR ao
+ * sistema, em vez de só receber as regras e adivinhar o resto.
+ */
+export const MATERIALISER_SINCE = "0.16.362";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/lang.js

@@ -0,0 +1,145 @@
+/**
+ * A LÍNGUA EM QUE A GENTE FALA COM ELE - DERIVADA, nunca perguntada.
+ *
+ * O QUE O CLIENTE GANHA: um comando cuja tela chega na língua dele, sem uma pergunta a mais no
+ * primeiro uso e sem uma bandeirinha para clicar.
+ *
+ * O DEFEITO QUE ISTO FECHA, medido no primeiro import real (03/09): o agente narra na língua da
+ * pessoa - porque é a língua em que ela conversa - e os nossos blocos saíam em inglês, na MESMA
+ * tela. Uma tela com duas línguas é a mesma classe de defeito que uma tela com duas instruções.
+ *
+ * DERIVAR, E NÃO PERGUNTAR, é decisão desta casa desde 27/07, escrita em `claude-md.ts`: *"THE
+ * INTERFACE LANGUAGE, READ FROM THE PROJECT RATHER THAN ASKED FOR"*. Aqui a fonte é OUTRA, e a
+ * diferença importa: aquela decide a língua do CÓDIGO GERADO e vem do projeto (`<html lang>`),
+ * porque o app é que tem público. Esta decide a língua da NOSSA TELA e vem da PESSOA - um
+ * desenvolvedor brasileiro constrói produto em inglês todo dia, e ler o `<html lang>` dele para
+ * escolher a língua do terminal erraria exatamente esse caso.
+ *
+ * A ORDEM, e o porquê de cada degrau:
+ *
+ *     SUI_LANG        a escolha explícita dele, que vence tudo - é a saída para quem tem locale
+ *                     de sistema numa língua e prefere ler noutra
+ *     LC_ALL / LANG   o que o sistema operacional dele já sabe. Ninguém precisa nos contar
+ *     en              o piso. Nunca uma língua adivinhada por IP, fuso ou nome de pasta
+ *
+ * NENHUMA TELA MISTURADA - e é isto que decide a arquitetura em vez do tamanho da tradução. A
+ * cobertura é por COMANDO, nunca por frase: um comando ou fala a língua dele inteiro, ou fala
+ * inglês inteiro. Traduzir por frase produziria a tela meio-e-meio que motivou este módulo, com
+ * a nossa assinatura em vez da coincidência.
+ *
+ * O QUE NUNCA TRADUZ, e a razão é dura: o que um AGENTE lê. As 11 ferramentas do MCP e as
+ * descrições que elas carregam são contrato de máquina - um modelo escolhe ferramenta lendo aquele
+ * texto, e traduzi-lo troca a precisão de uma escolha por uma gentileza que ninguém vê.
+ */
+/**
+ * O que um locale de sistema quer dizer para nós - e só o que a gente sabe cumprir.
+ *
+ * `pt_BR.UTF-8`, `pt-BR`, `pt` e `pt_PT` todos caem em `pt-BR`, e isto é uma escolha declarada:
+ * a tradução foi escrita em português do Brasil. Um leitor de Portugal lê algo legível e não o
+ * seu próprio registro - e é melhor que inglês, mas o dia em que `pt-PT` for pedido ele entra
+ * como língua própria em vez de continuar escondido aqui.
+ */
+function fromLocale(raw) {
+    const tag = raw.trim().toLowerCase().replace("_", "-").split(".")[0];
+    if (!tag)
+        return null;
+    if (tag.startsWith("pt"))
+        return "pt-BR";
+    if (tag.startsWith("en"))
+        return "en";
+    return null;
+}
+/**
+ * A LÍNGUA DESTE AMBIENTE. Pura: recebe o ambiente, nunca o lê de `process` por dentro - é o que
+ * permite um spec provar os quatro degraus sem mexer em variável global.
+ */
+export function resolveLang(env) {
+    const explicit = env.SUI_LANG ? fromLocale(env.SUI_LANG) : null;
+    if (explicit)
+        return explicit;
+    for (const key of ["LC_ALL", "LC_MESSAGES", "LANG"]) {
+        const found = env[key] ? fromLocale(env[key]) : null;
+        if (found)
+            return found;
+    }
+    return "en";
+}
+/**
+ * OS COMANDOS COM TELA COMPLETA NA OUTRA LÍNGUA - e a lista é a promessa.
+ *
+ * Um comando fora dela roda em inglês mesmo com o locale em português, e isso é deliberado: meia
+ * tela traduzida é o defeito que este módulo existe para não cometer. A lista cresce por comando,
+ * com a tela inteira medida, e é ela que o `--help` pode citar no dia em que alguém perguntar
+ * "vocês falam português?".
+ */
+const COVERED = {
+    en: new Set(),
+    "pt-BR": new Set(["connect"]),
+};
+/** A língua ativa desta execução - `en` até alguém declarar outra. */
+let active = "en";
+/**
+ * Liga a língua para ESTE comando, se e somente se a tela dele está coberta inteira.
+ *
+ * Chamado uma vez, no despacho. Devolve a língua que ficou ativa, para o chamador poder dizer.
+ */
+export function useLang(command, env) {
+    /**
+     * NÃO EXISTE UM `reset` SEPARADO, e a ausência é deliberada: um comando fora da lista devolve o
+     * piso, então `useLang("", {})` já É o reset que um teste precisa. Um export que só o spec chama
+     * é o que o `reachable.spec` reprova, e com razão - ele vira código que ninguém mais mantém.
+     */
+    const wanted = resolveLang(env);
+    active = COVERED[wanted].has(command) ? wanted : "en";
+    return active;
+}
+/**
+ * A TRADUÇÃO, CHAVEADA PELA FRASE EM INGLÊS - e não por um identificador.
+ *
+ * O identificador (`connect.hook.added`) é a forma clássica e ela custa uma coisa que este
+ * repositório não pode pagar: a frase sai do lugar onde a decisão dela está escrita. Aqui cada
+ * frase mora ao lado do comentário que conta por que ela é aquela frase, e a chave é o próprio
+ * texto - então uma frase que muda de redação PERDE a tradução e cai no inglês, o que é o
+ * comportamento certo: melhor inglês correto que português de uma versão anterior da promessa.
+ */
+const PT_BR = {};
+/**
+ * A frase que sai na tela: a tradução quando existe, o original quando não.
+ *
+ * O fallback é o original, nunca uma chave crua nem um vazio - a pior tela possível é a que perde
+ * a informação por causa da nossa tabela.
+ */
+export function say(text) {
+    if (active === "en")
+        return text;
+    return PT_BR[text] ?? text;
+}
+/**
+ * A FRASE COM NÚMERO DENTRO - e o marcador existe para a ORDEM DAS PALAVRAS ser livre.
+ *
+ * `the check moved from {was} to this one` em português é *"a verificação saiu da {was} para esta"*:
+ * o número muda de lugar. Traduzir pedaço por pedaço prenderia toda língua à sintaxe do inglês,
+ * que é o erro clássico de i18n feito com concatenação.
+ *
+ * A CHAVE É O TEMPLATE, com os marcadores dentro - a tabela guarda a frase inteira e cada língua
+ * decide onde cada número entra.
+ */
+export function fmt(text, vars) {
+    return say(text).replace(/\{(\w+)\}/g, (whole, key) => key in vars ? String(vars[key]) : whole);
+}
+/** Registra as frases de uma tela. Chamado pelos módulos de tradução, um por comando. */
+export function register(lang, table) {
+    if (lang !== "pt-BR")
+        return;
+    for (const [k, v] of Object.entries(table))
+        PT_BR[k] = v;
+}
+/**
+ * O QUE A TABELA NÃO ALCANÇA NESTA TELA - a conta que impede a mistura silenciosa.
+ *
+ * Um spec pergunta isto por comando: se sobrar frase sem tradução num comando declarado como
+ * coberto, o spec reprova. É a diferença entre uma promessa medida e uma intenção.
+ */
+export function missing(texts) {
+    return texts.filter((t) => !(t in PT_BR));
+}

package/dist/skills.js

@@ -36,7 +36,7 @@ export const SKILLS = [
         path: ADAPT_SKILL_PATH,
         source: ADAPT_SKILL,
         label: "/sui-adapt",
-        what: "one component against the system, and what to do about it",
+        what: "one component against the system",
     },
     /**
      * A DE CONSTRUÇÃO, e ela é a que responde ao pedido mais comum de todos:
@@ -52,7 +52,7 @@ export const SKILLS = [
         path: COMPOSE_SKILL_PATH,
         source: COMPOSE_SKILL,
         label: "/sui-compose",
-        what: "build what the system does not have, layer by layer",
+        what: "build what the system does not have",
     },
     /**
      * A DE LIGAR O SISTEMA NO APP, e ela é a única aqui que fecha um passo que a esteira já sabia
@@ -67,6 +67,6 @@ export const SKILLS = [
         path: CONFIGURE_SKILL_PATH,
         source: CONFIGURE_SKILL,
         label: "/sui-configure-ds",
-        what: "the system wired into the app, so the tokens reach the browser",
+        what: "the tokens, wired into your app",
     },
 ];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "synthesisui",
-  "version": "0.16.360",
+  "version": "0.16.362",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {