synthesisui 0.16.361 → 0.16.363

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,40 +657,47 @@ 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
-            ? "Drop the flag to approve each write yourself."
-            : "Drop the flags to approve each write yourself.").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]
-                : `${list.slice(0, -1).join(", ")} and ${list.at(-1)}`;
+                : /** 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
-            ? "A new session reads the wiring this run changed."
-            : `This run moved ${said}, and a new session is what reads ${list.length === 1 ? "it" : "them"}.`).map(paint.dim));
+            ? 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("The project's tools ask for approval once - say yes.").map(paint.dim));
+            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,8 +1,9 @@
 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 { 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";
@@ -178,7 +179,7 @@ version) {
      * 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(`Your terminal can warn you when this repo drifts - one block in ${rc}, silent unless something is wrong, at most once an hour.`).join("\n"));
+    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;
@@ -231,7 +232,7 @@ 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.
@@ -260,8 +261,10 @@ export async function connect(opts) {
         if (quiet === 0)
             return;
         console.log(body(paint.dim(quiet === rows.length
-            ? "· nothing to change - this environment is already current"
-            : `· ${quiet} other ${quiet === 1 ? "piece" : "pieces"} already current`)));
+            ? 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.
@@ -294,7 +297,7 @@ export async function connect(opts) {
      */
     const anyInstalled = (await installedSlugs(root).catch(() => [])).length > 0;
     if (!anyInstalled)
-        console.log(bodyWrapped("· no design system installed here yet - the agent has no index, and memory has nothing to belong to.").join("\n"));
+        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
@@ -307,7 +310,7 @@ export async function connect(opts) {
     if (want.hook) {
         row(wired.hook !== "already there", (() => {
             return wired.hook === "added"
-                ? "✓ .claude/settings.json  the check now runs after every write"
+                ? 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
@@ -315,7 +318,7 @@ export async function connect(opts) {
                        * (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";
+                    : 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
@@ -324,12 +327,12 @@ export async function connect(opts) {
          */
         if (wired.session !== "skipped")
             row(wired.session !== "already there", wired.session === "already there"
-                ? "· .claude/settings.json  the session check was 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. */
-                        "✓ .claude/settings.json  the session check moved to this one"
-                    : "✓ .claude/settings.json  each session opens with what is missing");
+                        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.
@@ -341,12 +344,21 @@ export async function connect(opts) {
     if (want.mcp && wired.mcp !== "skipped") {
         for (const one of wired.mcp)
             row(one.status !== "already there", one.status === "added"
-                ? `✓ ${one.path.padEnd(22)} ${MCP_TOOL_COUNT} tools the agent can ask`
+                ? `✓ ${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 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.
@@ -372,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"
+                        ? 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
@@ -420,7 +432,7 @@ export async function connect(opts) {
         if (had == null)
             continue;
         await rm(dir, { recursive: true, force: true }).catch(() => { });
-        row(true, `✕ /${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;
@@ -433,10 +445,10 @@ export async function connect(opts) {
             skillsMoved = true;
         }
         row(before !== skill.source, before === skill.source
-            ? `· ${skill.label.padEnd(22)} already current`
+            ? `· ${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();
@@ -484,14 +496,14 @@ export async function connect(opts) {
         /** 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
-            ? ["the checks"]
+            ? [say("the checks")]
             : moved(wired.hook)
-                ? ["the write check"]
+                ? [say("the write check")]
                 : moved(wired.session)
-                    ? ["the session check"]
+                    ? [say("the session check")]
                     : []),
-        ...(mcpMoved ? ["the tools"] : []),
-        ...(skillsMoved ? ["the skills"] : []),
+        ...(mcpMoved ? [say("the tools")] : []),
+        ...(skillsMoved ? [say("the skills")] : []),
     ];
     await reportWhatIsLeft(root, {
         cli: opts.version,
@@ -525,7 +537,7 @@ export async function connect(opts) {
          * `apps/web/src/lib/cli/commands.spec.ts`.
          */
         console.log("");
-        console.log(bodyWrapped("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.")
+        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

@@ -15,12 +15,12 @@
 import { readdir, readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { describeTriage, triageLedger } from "../doctor/gap-triage.js";
-import { body, section } from "../output.js";
+import { body, bodyWrapped, paint, section } from "../output.js";
 export async function gaps(opts) {
     const root = opts.dir ?? process.cwd();
     const path = opts.census ?? join(root, "_synthesisui", "census.json");
     const raw = await readFile(path, "utf8").catch(() => null);
-    console.log(section("What this pipeline did not read"));
+    console.log(section(opts.brief ? "What we read" : "What this pipeline did not read"));
     if (!raw) {
         console.log(body(`No measurement at ${path}. Run \`synthesisui import --dry\` first - that is what measures your files, and it writes the result there.`));
         return;
@@ -46,6 +46,8 @@ export async function gaps(opts) {
         console.log(body(`This measurement was written by a tool version that did not count style fragments yet, so the numbers do not exist rather than being zero. Run \`synthesisui import --dry\` again with ${opts.cli} to measure.`));
         return;
     }
+    if (opts.brief)
+        return brief(ledger, values);
     for (const line of describeTriage(triageLedger(ledger, opts.cli), values))
         console.log(body(line));
     /**
@@ -69,7 +71,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.`));
     }
 }
 /**
@@ -79,6 +93,47 @@ export async function gaps(opts) {
  * vazia. Em qualquer um dos três não há nada a dizer, e uma frase que aparece sempre é uma frase que
  * ninguém lê.
  */
+/**
+ * O RESULTADO E UMA AÇÃO - o fechamento de um import.
+ *
+ * TRÊS DECISÕES DE DESENHO, e cada uma responde a algo que o dono viu na tela em 03/09:
+ *
+ *   O PERCENTUAL EM AZUL. `paint.blue` é a cor que este produto reserva para o que está VIVO - a
+ *   barra de cobertura, os comandos, os links. A cobertura é o número que resume a entrega, e num
+ *   bloco de prosa cinza ela desaparecia ("deixe com um tom de outra cor").
+ *
+ *   A LACUNA EM UMA LINHA, COM ENDEREÇO. Ela continua dita - quantos fragmentos, em quantos
+ *   lugares - e a LISTA mora no comando sem `--brief`. Uma lacuna sem número seria silêncio; uma
+ *   lista no momento da entrega é pedir desculpa quando era hora de mostrar o resultado.
+ *
+ *   UMA CTA, COM O QUE ELA GANHA. O v2 já existe como rascunho; o que faltava era dizer o que
+ *   aprová-lo FAZ - agrupar cores quase iguais, nomear valor que carrega peso e não tem nome,
+ *   resolver o valor que carrega dois nomes dele. Um link sem consequência dita é um link que
+ *   espera para sempre.
+ */
+async function brief(ledger, values) {
+    const places = ledger.unread.length;
+    if (!values)
+        return;
+    const decisions = values.seen - values.structure;
+    const closed = values.interpreted + values.answered;
+    const pct = decisions > 0 ? Math.round((closed / decisions) * 100) : 0;
+    console.log(bodyWrapped(`${paint.blue(paint.strong(`${pct}%`))} of your design decisions are in the system - ${closed} of ${decisions}.`).join("\n"));
+    /**
+     * O QUE FALTA, NA MESMA UNIDADE DA LINHA DE CIMA - e a primeira versão desta função errou
+     * exatamente nisso.
+     *
+     * Ela dizia "222 fragments are not", ao lado de "920 de 1008": quem lê subtrai 88 e vê 222. É o
+     * mesmo defeito de duas unidades vizinhas que este PR conserta duas linhas acima, e eu o
+     * reintroduzi na frase nova. O resto vai em PONTOS PERCENTUAIS, que é a unidade que a pessoa
+     * acabou de ler, e o número de LUGARES é endereço e não contagem concorrente.
+     *
+     * E cala em 100%: "the other 0%" é uma linha que faz o leitor procurar o que não existe.
+     */
+    if (pct >= 100 || places === 0)
+        return;
+    console.log(bodyWrapped(paint.dim(`The other ${100 - pct}% sits in ${places} ${places === 1 ? "place" : "places"} - \`synthesisui gaps\` lists each one with the file and the line.`)).join("\n"));
+}
 async function carriedByGlobals(root) {
     const dir = join(root, "_synthesisui", "ds");
     const slugs = await readdir(dir).catch(() => []);
@@ -109,10 +164,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.
@@ -337,6 +347,8 @@ async function main() {
              */
             await gaps({
                 dir,
+                /** `--brief`: o fechamento de um import - o resultado e UMA ação. Ver `gaps.ts`. */
+                ...(boolFlag(flags, "brief") ? { brief: true } : {}),
                 census: typeof flags.census === "string" ? flags.census : undefined,
                 cli: CLI_VERSION,
             });

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/package.json

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