synthesisui 0.16.411 → 0.16.412

package/dist/commands/component.js

@@ -8,10 +8,11 @@ import { detectAppDirs } from "../global-sheet.js";
 import { hasInteractiveTemplate, interactiveTemplate, } from "../interactive-templates.js";
 import { body, section, snippet } from "../output.js";
 import { findCollision, installedThemeVars, reactMajorOf, readInstalledConvention, readInstalledScheme, } from "../project-facts.js";
-import { fetchComponent, RegistryError } from "../registry.js";
+import { fetchComponent, fetchDesignSystem, RegistryError, } from "../registry.js";
 import { installedThemeCss, whatOnlyTheSheetResolves, } from "../sheet-needed.js";
 import { flavourResolver } from "../styles-flavour.js";
-import { inTheirTongue, projectTongue, sumSpoken, } from "../their-tongue.js";
+import { inTheirTongue, projectTongue, sumSpoken, tongueFromArtifacts, } from "../their-tongue.js";
+import { resolvableVars } from "../their-vars.js";
 import { readCensus, unreadComment, unreadForComponent, } from "../unread-for-component.js";
 import { readWiring } from "../wiring-read.js";
 import { editedSinceWritten, readWritten, recordWritten } from "../written.js";
@@ -114,7 +115,38 @@ export async function component(slug, name, opts) {
      * apagaria a cor. Um projeto de destino chega sem mapa no `.lock`, nada é traduzido, e a folha
      * continua sendo o caminho - o comando DIZ qual dos dois aconteceu.
      */
-    const tongue = await projectTongue(root, slug);
+    const installedTongue = await projectTongue(root, slug);
+    /**
+     * E SEM O `add`, O SISTEMA VEM DO REGISTRY E O VOCABULARIO E' DERIVADO EM MEMORIA.
+     *
+     * O QUE ACONTECIA (medido em 10/09): sem `.lock`, `projectTongue` responde `null`, nada era
+     * traduzido, e o arquivo saia com `var(--ds-*)` cru - inutil ate' que a pessoa rodasse `add` e
+     * materializasse 1813 linhas, 111 variaveis e 628 referencias no repositorio dela. Pedir UM
+     * botao passava por instalar o sistema inteiro.
+     *
+     * A NOSSA FOLHA E' A REFERENCIA, NAO O PRE-REQUISITO (a definicao do produto, 07/09): ela existe
+     * para o agente dele ler e construir sobre ela. A medicao que ela carregava - quais das nossas
+     * variaveis tem nome no codigo dele - nao precisa de disco: e' a mesma varredura que o `add`
+     * faz, feita aqui e jogada fora depois de traduzir.
+     *
+     * UMA IDA A MAIS A' REDE, e so' neste caminho: quem ja' instalou o sistema le' do `.lock` como
+     * sempre. O `catch` mantem o comportamento antigo - sem tradução, e o bloco de setup abaixo diz
+     * que a folha e' o caminho.
+     */
+    const fromRegistry = installedTongue
+        ? null
+        : await fetchDesignSystem(base, slug, opts.version).catch(() => null);
+    /** A leitura do sistema NAO chegou - rede fora, ou sistema privado sem sessao. Ver o relato. */
+    const installedSheetMissing = !installedTongue && fromRegistry === null;
+    /**
+     * A NOSSA FOLHA ESTA' NA PASTA DELE? - o `.lock` responde, e e' o mesmo arquivo que o `add`
+     * escreve. Desde o A1 esta pergunta deixou de ser retorica: `component` roda sem ele.
+     */
+    const installedHere = await readFile(join(root, "_synthesisui", "ds", slug, ".lock"), "utf8").then(() => true, () => false);
+    const tongue = installedTongue ??
+        (fromRegistry
+            ? await tongueFromArtifacts(root, fromRegistry.artifacts)
+            : null);
     /**
      * O RELATÓRIO SÓ EXISTE DEPOIS DE OS BYTES EXISTIREM - e é essa ordem que corrige o defeito.
      *
@@ -422,6 +454,45 @@ export async function component(slug, name, opts) {
         console.log(spoken.left.length === 0
             ? `  No variable in what was just written points at our stylesheet - they are all names YOUR code declares.`
             : `  ${spoken.left.length} still point${spoken.left.length === 1 ? "s" : ""} at our stylesheet (${spoken.left.slice(0, 3).join(", ")}${spoken.left.length > 3 ? ", …" : ""}), so tokens.css carries ${spoken.left.length === 1 ? "it" : "those"}.`);
+        /**
+         * E DIZER DE ONDE VEIO O VOCABULARIO, quando o sistema NAO esta' instalado aqui.
+         *
+         * Sem esta linha o resultado seria magico: o arquivo fala a lingua dele e nada explica como.
+         * A frase importa porque a conclusao natural - *"entao o `add` ja' rodou"* - esta' errada, e a
+         * pessoa precisa saber que o que ela tem e' o componente, e que a folha continua sendo uma
+         * escolha e nao uma pendencia.
+         */
+        if (fromRegistry)
+            console.log(`  Nothing of ours was installed to do that - the system was read at v${fromRegistry.version}, and the names came from your own code.`);
+    }
+    else if (!tongue) {
+        /**
+         * A LACUNA DECLARADA (lei 8): nada foi traduzido, e ISSO SE DIZ.
+         *
+         * O QUE ACONTECIA SEM ESTA LINHA: o `.tsx` saia com `var(--ds-*)` cru e o terminal ficava
+         * mudo. A pessoa abre o arquivo, ve' variaveis que o `globals.css` dela nao declara, e a
+         * unica forma de descobrir por que a cor nao apareceu e' ir ler o nosso codigo.
+         *
+         * E OS DOIS MOTIVOS SAO DIFERENTES, entao a frase distingue: o repositorio dela nao nomeia
+         * nenhum destes valores (o caso comum, e nao ha' o que fazer), ou a leitura do sistema nao
+         * chegou - rede fora, sistema privado sem sessao. O segundo tem conserto e o primeiro nao.
+         */
+        /**
+         * E AS TRES CAUSAS SAO DIFERENTES, entao a frase distingue - so' uma delas tem conserto na
+         * mao dele, e ela e' a mais provavel das tres.
+         *
+         *     a leitura nao chegou     rede fora, sessao ausente, sistema privado
+         *     o build dele nao existe  `resolvableVars` recusa todo par que o build nao emite, por
+         *                              desenho: um nome afirmado sem prova pinta a cor errada no dia
+         *                              em que ele o renomear. Num clone fresco isso e' o caso normal
+         *     o codigo dele nao nomeia nada   a unica que o silencio de fato descrevia
+         */
+        const noBuild = !installedSheetMissing && (await resolvableVars(root)) === null;
+        console.log(installedSheetMissing
+            ? `  Nothing was translated: "${slug}" could not be read from the registry just now, so the variables stayed as ours. Check your connection, or run: npx synthesisui login`
+            : noBuild
+                ? `  Nothing was translated: this project has no build output to read, and a name we cannot see your build emit is a name we will not write. Run your build once and ask for it again - the file then speaks your own names.`
+                : `  Nothing was translated: your code names none of the values this system declares yet, so the variables stayed as ours and tokens.css is what resolves them.`);
     }
     // ── DX: concrete paths + copy-pasteable snippets, with breathing room ──
     const tailwind = flavour === "tailwind";
@@ -454,7 +525,15 @@ export async function component(slug, name, opts) {
      */
     const need = whatOnlyTheSheetResolves({
         source: writtenSource,
-        themeCss: await installedThemeCss(root, slug),
+        /**
+         * O `@theme` DO SISTEMA - do disco quando ele instalou, do registry quando nao.
+         *
+         * A pergunta que este bloco faz e' *"sobrou classe que so' o nosso @theme gera?"*. Sem o
+         * `add`, `installedThemeCss` responde vazio, e vazio leria como "nao sobrou nada" - uma
+         * resposta certa por acidente que ficaria errada no dia em que sobrasse.
+         */
+        themeCss: fromRegistry?.artifacts?.["theme.css"] ??
+            (await installedThemeCss(root, slug)),
         /** O vocabulário DELE sai da conta - ver `theirNames`. O mapa do `.lock` é a via mais barata. */
         theirNames: tongue?.names ? [...tongue.names.values()] : [],
     });
@@ -517,6 +596,19 @@ export async function component(slug, name, opts) {
     }
     if (need.needed && !alreadyWired) {
         console.log(section(`One-time setup (once per app, for "${slug}")`));
+        /**
+         * O PASSO ZERO VEM PRIMEIRO QUANDO A FOLHA NAO EXISTE - e desde o A1 este e' o caso comum.
+         *
+         * O QUE ACONTECIA: o passo 1 mandava colar `@import ".../tokens.css"` e o aviso de que o
+         * sistema nao esta' instalado saia na ULTIMA linha, entre parenteses. Quem nunca rodou `add`
+         * - agora um caminho normal, porque o `component` deixou de exigi-lo - lia a instrucao de
+         * cima para baixo e importava um caminho que nao existe. O erro do build nao fala de
+         * install: fala de um arquivo ausente.
+         *
+         * O motivo antes da instrucao, e nao depois dela.
+         */
+        if (!installedHere)
+            console.log(body(`First: "${slug}" is not installed in this project yet, so the file the import below points at does not exist. Run \`npx synthesisui add ${slug}\` before pasting it.`));
         console.log(body(need.variables.length > 0
             ? `(what still needs the sheet here: ${need.variables.slice(0, 3).join(", ")}${need.variables.length > 3 ? `, +${need.variables.length - 3}` : ""} - your code names no value for ${need.variables.length === 1 ? "it" : "them"})`
             : `(what still needs the sheet here: the ${need.classes.slice(0, 3).join(", ")}${need.classes.length > 3 ? `, +${need.classes.length - 3}` : ""} ${need.classes.length === 1 ? "utility" : "utilities"}, which only this system's @theme generates)`));
@@ -529,8 +621,10 @@ export async function component(slug, name, opts) {
         console.log(body(`2. Scope your app: add data-ds="${slug}" to a ROOT element, e.g. app/layout.tsx:`));
         console.log("");
         console.log(snippet([`<body data-ds="${slug}">{children}</body>`]));
-        console.log("");
-        console.log(body(`(If you haven't installed the system yet, run: synthesisui add ${slug})`));
+        if (installedHere) {
+            console.log("");
+            console.log(body(`(If you haven't installed the system yet, run: synthesisui add ${slug})`));
+        }
     }
     /**
      * O ELEMENTO QUE SAIU NÃO ATIVA O QUE A RECEITA PEDE - e isso se diz, em vez de sumir (lei 8).

package/dist/commands/connect.js

@@ -3,6 +3,7 @@ import { dirname, join } from "node:path";
 import { codexPinBefore, wireAgent } from "../agent-wiring.js";
 import { blockHomes, syncClaudeMd } from "../claude-md.js";
 import { resolveRegistry } from "../config.js";
+import { notAProject, projectRootFrom } from "../is-a-project.js";
 import { fmt, say } from "../lang.js";
 import { body, bodyWrapped, paint, section, snippet } from "../output.js";
 import { readShellAnswer, rememberShellNo } from "../shell-answer.js";
@@ -212,6 +213,25 @@ version) {
 }
 export async function connect(opts) {
     const root = opts.dir ?? process.cwd();
+    /**
+     * ANTES DA PRIMEIRA ESCRITA, SEMPRE - ver `is-a-project.ts`.
+     *
+     * MEDIDO EM 10/09: este comando tinha 6 escritas e 0 checagens de projeto. Rodado por engano
+     * na home ou numa pasta recem-criada, ele deixava `CLAUDE.md`, `.claude/settings.json`,
+     * `.mcp.json` e a casa da governanca ali - e um `CLAUDE.md` orfao instrui todo agente que
+     * abrir naquela pasta, semanas depois, sem ninguem lembrar de onde ele veio.
+     *
+     * AQUI E NAO DENTRO DE CADA ESCRITA: recusar na porta e' a unica forma de a promessa
+     * *"nada foi escrito"* ser verdade. Meia recusa deixaria dois arquivos e nenhuma mensagem.
+     */
+    const project = await projectRootFrom(root);
+    if (!project) {
+        console.log(section("Not a project"));
+        for (const line of notAProject("connect", root))
+            console.log(body(line));
+        process.exitCode = 1;
+        return;
+    }
     // Both unless one is explicitly turned off - somebody who says `--no-hook`
     // means it, and somebody who says nothing wants the thing to work.
     const want = { hook: opts.hook !== false, mcp: opts.mcp !== false };

package/dist/commands/generate.js

@@ -7,7 +7,7 @@ import { installedThemeVars, reactMajorOf, readInstalledConvention, readInstalle
 import { postGenerate, RegistryError } from "../registry.js";
 import { flavourResolver } from "../styles-flavour.js";
 import { projectTongue } from "../their-tongue.js";
-import { recordWritten } from "../written.js";
+import { keptLine, recordWritten, editedHere as theirEdits, } from "../written.js";
 /** PascalCase para o hint de import (course-card → CourseCard). */
 function pascalName(name) {
     return name.replace(/(^|[-_])([a-z0-9])/g, (_, __, c) => c.toUpperCase());
@@ -76,6 +76,23 @@ export async function generate(description, opts) {
         await readInstalledConvention(root, slug), res.name, await readInstalledScheme(root, slug), 
         /** O VOCABULÁRIO DELE - um componente gerado cai no mesmo projeto e fala a mesma língua. */
         await projectTongue(root, slug), await installedThemeVars(root, slug));
+        /**
+         * A EDICAO DELE VENCE A REESCRITA (T7) - a leitura que faltava.
+         *
+         * MEDIDO EM 10/09: este comando GRAVAVA o fingerprint e nunca o lia. A promessa existia pela
+         * metade - o `upgrade` respeitava o arquivo dele, e o comando que o escreveu na primeira vez
+         * passava por cima na segunda. Um pedido parecido devolve o mesmo nome, e o ajuste dele some.
+         *
+         * O QUE ELE NAO PERDE AO SER RECUSADO: a receita e o CSS ja' estao no disco - so' o `.tsx`
+         * nao foi escrito. E a saida e' a mesma que o `component` oferece.
+         */
+        const edited = await theirEdits(join(root, "_synthesisui", "ds", slug), res.name, compDir);
+        if (edited && edited.length > 0 && !opts.force) {
+            console.log("");
+            console.log(keptLine(res.name, edited, `npx synthesisui generate "${description}" --name ${res.name} --force`));
+            console.log(`  The recipe and the compiled CSS are on disk either way - only the .tsx was not written.`);
+            return;
+        }
         for (const file of files) {
             await writeFile(join(compDir, file.filename), file.code, "utf8");
         }

package/dist/commands/refit.js

@@ -8,7 +8,7 @@ import { installedThemeVars, reactMajorOf, readInstalledConvention, readInstalle
 import { fetchComponent, postRefit, postSaveComponent, RegistryError, } from "../registry.js";
 import { flavourResolver } from "../styles-flavour.js";
 import { projectTongue } from "../their-tongue.js";
-import { recordWritten } from "../written.js";
+import { keptLine, recordWritten, editedHere as theirEdits, } from "../written.js";
 /** Slugs INSTALLED under `_synthesisui/ds/` (a `.lock` marks a real install -
  *  a folder holding only refit artifacts doesn't count). */
 /** True when the system is actually installed (tokens.css present). */
@@ -122,6 +122,26 @@ export async function refit(file, opts) {
         const { files } = generateComponentFiles(slug, res.name, res.recipe, res.css, saved.version, flavourOf(res.name), await reactMajorOf(root), await readInstalledConvention(root, slug), res.name, await readInstalledScheme(root, slug), 
         /** O VOCABULÁRIO DELE - o `refit` reescreve o componente e não passava pela porta. */
         await projectTongue(root, slug), await installedThemeVars(root, slug));
+        /**
+         * A EDICAO DELE VENCE A REESCRITA (T7) - a leitura que faltava, a mesma do `generate`.
+         *
+         * Este comando REESCREVE um componente que a pessoa ja' tem, que e' exatamente a situacao em
+         * que o arquivo dela mais provavelmente foi tocado. Ele gravava o fingerprint e nunca o lia.
+         */
+        const edited = await theirEdits(join(root, "_synthesisui", "ds", slug), res.name, compDir);
+        if (edited && edited.length > 0 && !opts.force) {
+            console.log("");
+            console.log(
+            /**
+             * O COMANDO QUE RETOMA E' O QUE ELA ACABOU DE RODAR - `refit` recebe o CAMINHO do
+             * arquivo-fonte, nunca o nome do componente. Sugerir `refit ${res.name}` devolveria
+             * `Could not read "<nome>"`, e uma saida que nao funciona e' pior que nenhuma saida:
+             * a pessoa fez o que a tela mandou e levou uma segunda recusa.
+             */
+            keptLine(res.name, edited, `npx synthesisui refit ${file}${opts.name ? ` --name ${opts.name}` : ""} --force`));
+            console.log(`  The recipe is saved in your system's draft either way - only the .tsx was not written.`);
+            return;
+        }
         for (const f of files) {
             await writeFile(join(compDir, f.filename), f.code, "utf8");
         }

package/dist/commands/sync.js

@@ -582,6 +582,24 @@ export async function remeasure(args) {
     console.log(body(`${out.written ?? 0} of ${out.total ?? 0} components written.`));
     for (const note of out.notes ?? [])
         console.log(body(paint.faint(note)));
+    /**
+     * A RECUSA, DITA - e este era o unico numero da tela sem explicacao.
+     *
+     * O QUE O CLIENTE VIA (medido em 10/09): `60 of 62 components written.` e mais nada. Os dois
+     * que faltaram estavam nomeados na resposta, com o motivo, e o comando descartava o campo. Quem
+     * le "60 de 62" so' pode concluir uma coisa - que a esteira perdeu dois - e vai procurar um
+     * defeito que nao existe, ou pior, nao vai.
+     *
+     * A COPY JA' EXISTIA: `because` e' a frase do servidor, e reescreve-la aqui seria a segunda
+     * versao da mesma explicacao. A primeira coisa que a segunda faz e' discordar da primeira.
+     */
+    const refused = out.refused ?? [];
+    if (refused.length > 0) {
+        console.log("");
+        console.log(body(`${refused.length} ${refused.length === 1 ? "component was" : "components were"} refused - ${refused.length === 1 ? "it is" : "they are"} not lost, ${refused.length === 1 ? "it was" : "they were"} not written:`));
+        for (const r of refused)
+            console.log(body(paint.strong(`  ✕ ${r.name} - ${r.because}`)));
+    }
     /**
      * A RECUSA POR ESCOPO, DITA - e não como um número que some.
      *

package/dist/commands/template.js

@@ -1,8 +1,9 @@
 import { mkdir, writeFile } from "node:fs/promises";
-import { dirname, join } from "node:path";
+import { dirname, join, relative } from "node:path";
 import { readProjectConfig, resolveRegistry } from "../config.js";
 import { fetchTemplate } from "../registry.js";
 import { inTheirTongue, projectTongue } from "../their-tongue.js";
+import { keptLine, recordWritten, editedHere as theirEdits, } from "../written.js";
 /**
  * Materializes a whole page from a DS template into the project (hybrid
  * codegen-first): the server codegens deterministic files, we write them, and
@@ -28,6 +29,36 @@ export async function template(slug, name, opts) {
     const defaultDir = join("templates", asName ?? name);
     const pageRel = opts.out ?? join(defaultDir, pageFile.filename);
     const pageDir = dirname(join(root, pageRel));
+    /**
+     * A EDICAO DELE VENCE A REESCRITA (T7) - a MESMA guarda do `component`, no comando que a nao
+     * tinha.
+     *
+     * MEDIDO EM 10/09: `component.ts` consultava o registro do que nos escrevemos em seis pontos e
+     * `template.ts` em nenhum. E este comando escreve MAIS: uma pagina inteira, mais a folha
+     * co-locada. Alguem que traz um template, ajusta o texto, e roda de novo para pegar uma correcao
+     * perdia o ajuste - sem aviso, sem `--force`, sem uma frase.
+     *
+     * A MESMA CHAVE PARA OS DOIS LADOS: `templates/<nome>` e' o que a leitura procura e o que a
+     * escrita grava, entao o fingerprint de hoje e' lido pela rodada de amanha. Sem `.lock`
+     * (template trazido antes do install) nao ha' memoria, e o comportamento de sempre continua.
+     */
+    const slugDir = join(root, "_synthesisui", "ds", slug);
+    const entry = relative(root, pageDir).split(/[\\/]/).join("/");
+    const editedHere = await theirEdits(slugDir, entry, pageDir);
+    if (editedHere && editedHere.length > 0 && !opts.force) {
+        console.log("");
+        console.log(keptLine(entry, editedHere, 
+        /**
+         * O RETAKE CARREGA `--out`, senao ele escreve em OUTRO LUGAR.
+         *
+         * Sem esta parte, quem rodou `template landing --out app/page.tsx` e seguiu a instrucao
+         * da recusa escreveria em `templates/landing/page.tsx`: o arquivo que ele editou fica
+         * intocado, nasce um segundo, e nada diz que aconteceu. Uma saida que escreve no lugar
+         * errado e' pior que uma recusa sem saida.
+         */
+        `npx synthesisui template ${slug} ${name}${asName ? ` --as ${asName}` : ""}${opts.out ? ` --out ${opts.out}` : ""} --force`));
+        return;
+    }
     /**
      * NENHUMA MATERIALIZAÇÃO VAZA VOCABULÁRIO INTERNO (INV-VOLTA-02) - a mesma porta do
      * `component`. Uma página inteira saía com `var(--ds-*)` cru enquanto um componente avulso
@@ -40,6 +71,8 @@ export async function template(slug, name, opts) {
     let inlined = 0;
     const still = new Set();
     await mkdir(pageDir, { recursive: true });
+    /** OS BYTES QUE FORAM A DISCO, para o fingerprint lembrar EXATAMENTE o que escrevemos. */
+    const landed = [];
     const spokenPage = speak(pageFile.code);
     if (spokenPage) {
         named += spokenPage.named;
@@ -47,7 +80,12 @@ export async function template(slug, name, opts) {
         for (const l of spokenPage.left)
             still.add(l);
     }
-    await writeFile(join(root, pageRel), spokenPage ? spokenPage.css : pageFile.code, "utf8");
+    const pageContent = spokenPage ? spokenPage.css : pageFile.code;
+    await writeFile(join(root, pageRel), pageContent, "utf8");
+    landed.push({
+        filename: pageRel.split(/[\\/]/).pop() ?? pageFile.filename,
+        content: pageContent,
+    });
     console.log(`✓ wrote ${pageRel}  (${slug} v${generated.version})`);
     for (const f of siblings) {
         const rel = join(dirname(pageRel), f.filename);
@@ -58,9 +96,19 @@ export async function template(slug, name, opts) {
             for (const l of spoken.left)
                 still.add(l);
         }
-        await writeFile(join(root, rel), spoken ? spoken.css : f.code, "utf8");
+        const content = spoken ? spoken.css : f.code;
+        await writeFile(join(root, rel), content, "utf8");
+        landed.push({ filename: f.filename, content });
         console.log(`✓ wrote ${rel}`);
     }
+    /**
+     * E O REGISTRO E' GRAVADO - a outra metade da guarda, e sem ela a primeira nunca dispara.
+     *
+     * A leitura la' em cima procura o fingerprint desta escrita. Ler sem gravar seria uma guarda que
+     * passa em todo teste e nunca protege ninguem: a promessa so' existe quando as duas pontas
+     * fecham.
+     */
+    await recordWritten(slugDir, entry, landed);
     if (named > 0 || inlined > 0) {
         console.log(`  ${named} reference${named === 1 ? "" : "s"} now speak${named === 1 ? "s" : ""} the name YOUR code gives the value${inlined > 0 ? `, and ${inlined} carr${inlined === 1 ? "ies" : "y"} the value because your code names no token for it` : ""}.`);
         if (still.size > 0) {

package/dist/commands/upgrade.js

@@ -211,6 +211,56 @@ async function theOnlyInstalled(root) {
         throw new RegistryError("No design system is installed here - run `synthesisui add <slug>` first.");
     throw new RegistryError(`More than one system is installed here (${slugs.join(", ")}) - name the one to update: \`synthesisui upgrade <slug>\`.`);
 }
+/**
+ * O QUE ELE EDITOU DEPOIS DE NOS ESCREVERMOS - a mesma leitura, num lugar so'.
+ *
+ * A PROMESSA T7 e' *"kept YOUR file(s)"*, e ela vivia dentro do laco que regenera. Isso amarrou a
+ * promessa a UM caminho: o do upgrade que tem versao nova. Medido em 10/09 - com a versao igual,
+ * `upgrade` retornava antes de chegar ao laco, e a pessoa que editou tres componentes nao ouvia
+ * nada sobre eles no comando cuja funcao e' justamente dizer o que aconteceu com os arquivos dela.
+ *
+ * Extraida, a resposta e' a mesma nos tres caminhos - rematerializou, ja' estava na ultima, ou
+ * subiu de versao. Uma leitura, uma frase.
+ */
+async function editedByHand(root, slug, slugDir, componentsDir) {
+    const componentsRoot = join(root, componentsDir);
+    const marker = `from the "${slug}" design system`;
+    const writtenMap = await readWritten(slugDir);
+    const out = [];
+    for (const entry of await readdir(componentsRoot).catch(() => [])) {
+        let head = "";
+        try {
+            head = (await readFile(join(componentsRoot, entry, `${entry}.tsx`), "utf8")).slice(0, 300);
+        }
+        catch {
+            continue; // not a materialized component folder
+        }
+        if (!head.includes("Generated by SynthesisUI") || !head.includes(marker))
+            continue;
+        const edited = await editedSinceWritten(writtenMap[entry], join(componentsRoot, entry));
+        if (edited && edited.length > 0)
+            out.push({ entry, edited });
+    }
+    return out;
+}
+/**
+ * E A FRASE, DITA - nos caminhos que NAO regeneram nada.
+ *
+ * Aqui ela nao e' o relatorio de uma reescrita que respeitou o arquivo dele: e' a confirmacao de
+ * que este comando passou e nao tocou no que e' dele. E' a mesma informacao, e omiti-la nos
+ * caminhos silenciosos e' o que fazia a promessa valer so' as vezes.
+ */
+async function sayWhatWasKept(root, slug, slugDir) {
+    const config = await readProjectConfig(root).catch(() => null);
+    if (!config || config.target !== "next")
+        return;
+    const kept = await editedByHand(root, slug, slugDir, config.componentsDir);
+    if (kept.length === 0)
+        return;
+    console.log("");
+    for (const k of kept)
+        console.log(body(keptLine(k.entry, k.edited, `npx synthesisui component ${slug} ${k.entry}`)));
+}
 export async function upgrade(asked, opts) {
     const base = resolveRegistry(opts.registry);
     const root = opts.dir ?? process.cwd();
@@ -263,6 +313,8 @@ export async function upgrade(asked, opts) {
              * medido.
              */
             const measured = await checkAfterWriting(root, `v${installed}`);
+            /** ESTE CAMINHO REESCREVE OS ARTEFATOS - e o que e' dele fica onde esta'. Ver `sayWhatWasKept`. */
+            await sayWhatWasKept(root, slug, slugDir);
             await reportWhatIsLeft(root, {
                 ...(opts.cli ? { cli: opts.cli } : {}),
                 ...(measured > 0 ? { justMeasured: measured } : {}),
@@ -271,6 +323,12 @@ export async function upgrade(asked, opts) {
         }
         if (!opts.force) {
             console.log(`✓ ${slug} is already at the latest version (v${installed}).`);
+            /**
+             * E AQUI TAMBEM, que e' o caminho mais percorrido de todos: sem gap de versao, este comando
+             * dizia uma linha e sumia. Quem editou tres componentes ficava sem saber se eles seguem sendo
+             * dele - no comando que existe para responder isso.
+             */
+            await sayWhatWasKept(root, slug, slugDir);
             await reportWhatIsLeft(root, opts.cli ? { cli: opts.cli } : {});
             return;
         }
@@ -308,8 +366,9 @@ export async function upgrade(asked, opts) {
     const regenerated = [];
     const failed = [];
     /** Componentes que ELE editou desde que os escrevemos - mantidos intactos (T7). */
-    const kept = [];
-    const writtenMap = await readWritten(slugDir);
+    const kept = await editedByHand(root, slug, slugDir, config.componentsDir);
+    /** Os que ELE editou saem da regeneracao - a leitura acima ja' os separou. */
+    const keptEntries = new Set(kept.map((k) => k.entry));
     if (config.target === "next") {
         const componentsRoot = join(root, config.componentsDir);
         const marker = `from the "${slug}" design system`;
@@ -345,16 +404,13 @@ export async function upgrade(asked, opts) {
             if (!head.includes("Generated by SynthesisUI") || !head.includes(marker))
                 continue;
             /**
-             * A EDIÇÃO DELE VENCE A REGENERAÇÃO (T7) - ver `written.ts`. O fingerprint do que NÓS
+             * A EDIÇÃO DELE VENCE A REGENERAÇÃO (T7) - ver `editedByHand`. O fingerprint do que NÓS
              * escrevemos foi gravado no `.lock` na hora da escrita; se o disco divergiu, ele editou, e o
              * arquivo é DELE - fica intacto e o terminal diz qual. `null` é install de antes do
              * fingerprint: sem memória não há veredito, e o comportamento de sempre continua.
              */
-            const edited = await editedSinceWritten(writtenMap[entry], join(componentsRoot, entry));
-            if (edited && edited.length > 0) {
-                kept.push({ entry, edited });
+            if (keptEntries.has(entry))
                 continue;
-            }
             try {
                 const res = await fetchComponent(base, slug, entry);
                 const { files } = generateComponentFiles(slug, res.name, res.recipe, res.css, res.version, flavourOf(res.name), 
@@ -460,7 +516,7 @@ export async function upgrade(asked, opts) {
     if (kept.length > 0) {
         console.log("");
         for (const k of kept)
-            console.log(body(keptLine(slug, k.entry, k.edited)));
+            console.log(body(keptLine(k.entry, k.edited, `npx synthesisui component ${slug} ${k.entry}`)));
     }
     const measured = await checkAfterWriting(root, `v${latest.version}`);
     console.log(section("Migrate the app"));

package/dist/index.js

@@ -117,6 +117,7 @@ Options:
   --instruction <s>  refit: extra guidance for the adaptation
   --dry              refit: adapt and print, but save nothing
   --force            clean: apply the changes (without it, dry run)
+                     component/template/generate/refit: overwrite a file YOU edited
                      upgrade: rewrite UPGRADE.md even with no version gap left
   --from <n>         upgrade --force: which older snapshot to diff from
   --strict           doctor: exit 1 when drift is found in THIS repo (for CI)
@@ -155,6 +156,21 @@ Examples:
 async function main() {
     const { positionals, flags } = parseFlags(process.argv.slice(2));
     const [command, ...args] = positionals;
+    /**
+     * `synthesisui --version` RESPONDE A VERSAO - uma linha, exit 0.
+     *
+     * O QUE ACONTECIA (medido em 10/09): `node dist/index.js --version` imprimia as 117 linhas do
+     * help e saia 0. Quem pergunta a versao de uma ferramenta - uma pessoa num terminal, um script
+     * de CI, um relatorio de bug - recebia a lista de comandos, e a unica forma de descobrir a
+     * versao era abrir o `package.json` da instalacao.
+     *
+     * SEM COMANDO, sempre: `--version <n>` continua sendo flag do `add`, do `component` e do
+     * `template`, e la ela chega com um comando na frente. A distincao e' posicional, nao de nome.
+     */
+    if (!command && flags.version !== undefined) {
+        console.log(CLI_VERSION);
+        return;
+    }
     if (!command || flags.help || command === "help") {
         /**
          * A PRIMEIRA LINHA FALA DO PROJETO ONDE ELA FOI RODADA - ver `where-you-are.ts`.
@@ -484,6 +500,8 @@ async function main() {
                 target,
                 version,
                 as: as_,
+                /** A saida da guarda T7: escrever por cima do que ELE editou e' escolha dele. */
+                force: flags.force === true,
             });
             break;
         }
@@ -579,6 +597,8 @@ async function main() {
                 instruction: typeof flags.instruction === "string" ? flags.instruction : undefined,
                 support: typeof flags.support === "string" ? flags.support : undefined,
                 dry: flags.dry === true,
+                /** A saida da guarda T7: escrever por cima do que ELE editou e' escolha dele. */
+                force: flags.force === true,
             });
             break;
         }
@@ -681,7 +701,14 @@ async function main() {
             }
             const ds = typeof flags.ds === "string" ? flags.ds : undefined;
             const name = typeof flags.name === "string" ? flags.name : undefined;
-            await generate(description, { registry, dir, ds, name });
+            await generate(description, {
+                registry,
+                dir,
+                ds,
+                name,
+                /** A saida da guarda T7: escrever por cima do que ELE editou e' escolha dele. */
+                force: flags.force === true,
+            });
             break;
         }
         default:

package/dist/install-marks.js

@@ -170,7 +170,24 @@
  * 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.403";
+/**
+ * 0.16.403 -> 0.16.412 em 10/09, e o SIM é sobre TRÊS coisas que caem na pasta dele:
+ *
+ *   `component` sem `add`   sem `.lock`, o vocabulário do repositório dele passa a ser derivado
+ *                           em memória do sistema lido no registry. O `.tsx` que o CLI de ontem
+ *                           escrevia com `var(--ds-*)` cru sai com o nome que o código DELE dá
+ *                           àquele valor - e a nossa folha deixa de ser pré-requisito para
+ *                           trazer um componente.
+ *   `template` com T7       a página materializada grava o fingerprint no `.lock` e passa a
+ *                           recusar a reescrita do que ele editou à mão. Campo novo no arquivo
+ *                           que o time dele commita.
+ *   `generate` e `refit`    gravavam o fingerprint e nunca o liam; agora recusam por edição
+ *                           dele, então o conjunto de bytes que uma rodada deixa é outro.
+ *
+ * O que o cliente ganha ao rodar `upgrade`: os componentes que ele já tem voltam a ser reescritos
+ * pelo materializador que respeita a edição dele em TODO comando, e não só em dois.
+ */
+export const MATERIALISER_SINCE = "0.16.412";
 /**
  * A ÚLTIMA VERSÃO EM QUE O QUE O HOOK RODA MUDOU.
  *

package/dist/is-a-project.js

@@ -0,0 +1,78 @@
+import { stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+/**
+ * ESTA PASTA E' UM PROJETO? - a pergunta que todo comando que ESCREVE no repositorio dele
+ * deveria fazer antes da primeira escrita.
+ *
+ * O QUE O CLIENTE VIVIA: `connect` rodado por engano no `~` ou num diretorio recem-criado
+ * escrevia `.claude/settings.json`, `CLAUDE.md`, `.mcp.json` e a pasta de governanca ali mesmo -
+ * seis escritas, medidas em 10/09, nenhuma delas precedida de uma checagem. Ninguem percebe no
+ * dia; percebe semanas depois, quando um `CLAUDE.md` orfao na home passa a instruir todo agente
+ * que abre naquela pasta.
+ *
+ * O CRITERIO E' O DO ECOSSISTEMA, nao um nosso: um `package.json` nesta pasta ou acima dela. A
+ * subida para no diretorio que carrega o `.git`, porque a raiz do repositorio e' onde o projeto
+ * acaba - continuar subindo alcancaria a home de quem roda, que e' exatamente o acidente que isto
+ * existe para recusar.
+ *
+ * GENERALIDADE: nao pergunta por Next, por React nem pela nossa pasta. Um projeto que ainda nao
+ * instalou nada e' um projeto; uma pasta vazia dentro de um repositorio Node tambem e', porque o
+ * manifesto de cima responde por ela.
+ */
+export async function projectRootFrom(dir) {
+    /**
+     * DENTRO DE UMA DEPENDENCIA NAO E' O PROJETO DELE - e' o projeto de outra pessoa, baixado.
+     *
+     * Um `cd` de distancia do acidente: `node_modules/<lib>` tem `package.json`, entao a subida
+     * parava ali e o comando escrevia a fiacao do agente dentro de uma dependencia - que some no
+     * proximo `npm ci`, levando junto tudo que ele configurou.
+     */
+    if (dir.split(/[\\/]/).includes("node_modules"))
+        return null;
+    /**
+     * E A HOME E' O SEGUNDO TETO, ao lado da raiz do repositorio.
+     *
+     * O `.git` sozinho nao fechava o acidente que este modulo existe para recusar: numa maquina
+     * onde alguem rodou `npm init` na home - acontece -, uma pasta solta em `~/qualquer-coisa` sem
+     * git subia ate' `~`, encontrava aquele manifesto, e o comando escrevia `CLAUDE.md`,
+     * `.mcp.json` e a casa da governanca na HOME da pessoa.
+     *
+     * A home nunca e' "o projeto dele", tenha ela manifesto ou nao.
+     */
+    const home = homedir();
+    let at = dir;
+    for (;;) {
+        if (at === home)
+            return null;
+        if (await exists(join(at, "package.json")))
+            return at;
+        /** A raiz do repositorio e' o teto: acima dela nao existe "o projeto dele". */
+        if (await exists(join(at, ".git")))
+            return null;
+        const up = dirname(at);
+        if (up === at)
+            return null;
+        at = up;
+    }
+}
+async function exists(path) {
+    return stat(path).then(() => true, () => false);
+}
+/**
+ * A RECUSA, COM O MOTIVO E O QUE FAZER - nunca so' "nao posso".
+ *
+ * E ELA DIZ O QUE MEDIMOS, nao o que a pasta e'. A primeira redacao decretava
+ * *"<dir> is not a project"* e oferecia `npm init -y`: num repositorio Deno ou Rust a primeira
+ * frase e' falsa - aquilo E' um projeto - e a segunda manda sujar o repositorio dele com o
+ * manifesto de um ecossistema que ele nao usa. Representar o limite do leitor e' diferente de
+ * negar o que ele tem.
+ */
+export function notAProject(command, dir) {
+    return [
+        `No package.json in ${dir}, or in any folder above it up to the repository root - so this reader cannot tell which project it is looking at.`,
+        `\`${command}\` writes agent files into a project - a hook, an MCP entry, CLAUDE.md - so it stops before writing anything.`,
+        `Point it at the project:  npx synthesisui ${command} --dir <path/to/project>`,
+        `(it looks for a package.json - that is what this reader knows how to place files in)`,
+    ];
+}

package/dist/their-tongue.js

@@ -50,6 +50,33 @@ export function inTheirTongue(css, tongue, destination = "stylesheet") {
     });
     return { css: out, named, inlined, left: [...left].sort() };
 }
+/**
+ * O VOCABULARIO DESTE REPOSITORIO **SEM O `add` TER RODADO** - a folha deixa de ser pre-requisito.
+ *
+ * O QUE ISTO MUDA PARA O CLIENTE: ele pede UM componente e recebe um arquivo que ja' fala a
+ * lingua do codigo dele - `var(--color-ink-900)`, o nome que ELE deu - sem antes materializar as
+ * 1813 linhas, 111 variaveis e 628 referencias que o `add` escreve no repositorio (medido em
+ * 10/09). A nossa folha e' a REFERENCIA que o agente dele le'; exigi-la para trazer um botao
+ * invertia isso, e contrariava a definicao de produto: nada nosso no repositorio dele.
+ *
+ * A MEDICAO E' A MESMA DO `add`, so' que em memoria: `pointTokensAtTheirNames` varre as folhas
+ * DELE e o build dele, e responde quais das nossas variaveis tem nome dele. A diferenca e' que
+ * nada disso vai para o disco - nem o mapa, nem a folha.
+ *
+ * `null` quando o repositorio dele nao nomeia nada do que este sistema declara. Ai' a folha
+ * continua sendo o caminho, e quem chama DIZ isso - em vez de escrever `var(--ds-*)` cru e
+ * deixar a pessoa descobrir por que a cor nao apareceu.
+ */
+export async function tongueFromArtifacts(root, artifacts) {
+    const tokens = artifacts["tokens.css"] ?? "";
+    if (!tokens)
+        return null;
+    const { pointTokensAtTheirNames } = await import("./their-vars.js");
+    const { pairs } = await pointTokensAtTheirNames(root, { artifacts });
+    if (pairs.length === 0)
+        return null;
+    return tongueOf(pairs, tokens);
+}
 /**
  * O VOCABULÁRIO DESTE REPOSITÓRIO, montado do que o `add` já deixou na pasta.
  *

package/dist/wiring-read.js

@@ -36,6 +36,25 @@ import { detectAppDirs, sheetChainOf } from "./global-sheet.js";
  *
  * The system itself was always resolved from the root. So is this now.
  */
+/**
+ * O QUE NOS ESCREVEMOS NAO E' FIACAO DELE - e isto era um FALSO SILENCIO, o pior dos dois.
+ *
+ * MEDIDO EM 10/09: o cabecalho que `component-codegen.ts` poe em todo `.tsx` materializado diz,
+ * em comentario, *"Global setup (once per app): import _synthesisui/ds/<slug>/tokens.css"* e
+ * *"put data-ds=<slug> on a root element"*. A varredura abaixo procura exatamente essas duas
+ * strings em QUALQUER arquivo do repositorio - entao, a partir do primeiro componente que nos
+ * mesmos escrevemos, ela passava a responder `imported: true` e `scoped: true` sobre um projeto
+ * que nao importa nada e nao tem escopo nenhum.
+ *
+ * O QUE O CLIENTE VIVIA: ele traz um componente, a tela diz *"This project already imports
+ * <slug>'s tokens.css and carries data-ds - nothing to set up"*, ele cola o componente na pagina,
+ * e ve' um bloco sem cor, sem tipografia e sem sombra. O comando acabou de garantir que estava
+ * tudo certo. O `doctor` le' pela mesma porta, entao dizia o mesmo.
+ *
+ * A instrucao que ESTE arquivo carrega e' uma instrucao, nao um cumprimento dela. Um comentario
+ * nosso nunca prova nada sobre o projeto dele.
+ */
+const OURS = "Generated by SynthesisUI";
 export async function readWiring(root, slug) {
     const w = {
         imported: false,
@@ -84,6 +103,9 @@ export async function readWiring(root, slug) {
         const src = await readFile(file, "utf8").catch(() => "");
         if (!src)
             continue;
+        /** Ver `OURS`: o nosso proprio cabecalho respondia por ele. */
+        if (src.slice(0, 300).includes(OURS))
+            continue;
         if (src.includes(`_synthesisui/ds/${slug}/tokens.css`))
             w.imported = true;
         if (src.includes(`_synthesisui/ds/${slug}/theme.css`))

package/dist/written.js

@@ -60,11 +60,33 @@ export async function editedSinceWritten(recorded, dir) {
     return edited;
 }
 /**
- * A FRASE DO TERMINAL, uma por componente mantido - o critério do T7 é a prova VISÍVEL: o dono
- * fica sabendo na hora, com o arquivo nomeado e a saída dita, não num diff depois do fato. A
- * saída oferecida regenera por ESCOLHA (o `component` reescreve e regrava o fingerprint).
+ * A PERGUNTA, NUM LUGAR SO': *ele editou o que escrevemos aqui?*
+ *
+ * As duas linhas - ler o registro do `.lock`, comparar com o disco - estavam copiadas em cada
+ * comando que se lembrou de perguntar, e ausentes nos que nao se lembraram. Medido em 10/09:
+ * `component` 6 guardas, `upgrade` 4, `generate` e `refit` gravavam o fingerprint e nunca o liam,
+ * `template` nao fazia nem uma coisa nem outra.
+ *
+ * Uma porta so' torna a omissao visivel: um comando de materializacao que nao a chama aparece no
+ * portao de `every-writer-keeps-his-edits.spec.ts`, em vez de aparecer no repositorio de alguem.
+ *
+ * `null` e' install legado (sem fingerprint gravado) - sem memoria nao ha' veredito, e quem chama
+ * mantem o comportamento de sempre.
+ */
+export async function editedHere(slugDir, entry, dir) {
+    return editedSinceWritten((await readWritten(slugDir))[entry], dir);
+}
+/**
+ * A FRASE DO TERMINAL, uma por arquivo mantido - o critério do T7 é a prova VISÍVEL: o dono
+ * fica sabendo na hora, com o arquivo nomeado e a saída dita, não num diff depois do fato.
+ *
+ * `retake` E' OBRIGATORIO, e é o comando que RETOMA a versão nova. Ele era fixo em
+ * `component <slug> <entry>`, o que estava certo enquanto só um comando falava esta frase: no
+ * `template` aquela linha mandaria a pessoa rodar o comando errado, e uma saída que não funciona
+ * é pior que nenhuma. Obrigatório em vez de opcional porque um default aqui volta a ser o
+ * comando de outro comando, calado.
  */
-export function keptLine(slug, entry, edited) {
+export function keptLine(entry, edited, retake) {
     return (`! ${entry}: you edited ${edited.join(", ")} after we wrote it - kept YOUR file(s).\n` +
-        `  To take the new version anyway: npx synthesisui component ${slug} ${entry}`);
+        `  To take the new version anyway: ${retake}`);
 }

package/package.json

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