synthesisui 0.16.411 → 0.16.413

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,9 +525,28 @@ 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()] : [],
+        /**
+         * A TERCEIRA FONTE NÃO É MEDIDA AQUI, e o vazio é a resposta EXPLÍCITA disso.
+         *
+         * As classes de receita que a folha declara entrariam nesta conta se esta linha entregasse o
+         * `tokens.css` instalado - e o efeito está medido em `steps/11-fora-do-escopo.md`: este comando
+         * diz *"This file needs nothing else… It is yours."* sobre um componente cujo estilo inteiro vem
+         * de `.ds-button`. Ligar a medição aqui é mudar o que este comando promete, com o bloco de setup
+         * dele para redesenhar: é etapa própria. O que o argumento obrigatório garante é que a omissão
+         * está ESCRITA, e não escondida num parâmetro que ninguém passou.
+         */
+        sheetCss: "",
     });
     if (!need.needed) {
         console.log(section("This file needs nothing else"));
@@ -517,6 +607,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 +632,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/doctor.js

@@ -916,6 +916,13 @@ export async function doctor(opts) {
         source: scannedSource,
         themeCss,
         theirNames: installed.theirs.byName.keys(),
+        /**
+         * A TERCEIRA FONTE NÃO É MEDIDA AQUI - ver o mesmo comentário em `component.ts` e o número em
+         * `steps/11-fora-do-escopo.md`. Este comando decide `unwired` e `blocked` por `needed`, então
+         * ligar a medição muda o veredito do `doctor` num repositório real: é etapa própria, e o vazio
+         * deixa a omissão escrita em vez de escondida.
+         */
+        sheetCss: "",
     });
     /**
      * BLOQUEADO SÓ QUANDO A FOLHA É NECESSÁRIA - a mesma pergunta que decide `unwired`.

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/hook.js

@@ -57,6 +57,20 @@ async function report(root, filePath) {
     const rel = relative(root, filePath);
     const d = diagnose([scanSource(rel, src, table)]);
     const named = d.findings.filter((f) => nameToWrite(f));
+    /**
+     * O VALOR QUE NADA NOMEIA - dito, e nunca batizado (A1 da etapa 11, escolha dele em 10/09).
+     *
+     * ERA SILÊNCIO, e o silêncio era a única resposta errada disponível. O comentário que estava aqui
+     * dizia que a deriva sem nome "não vale interromper, porque o único conselho honesto é pergunte a
+     * uma pessoa" - e a conclusão não segue da premissa: quem lê um relatório que só fala de valores
+     * nomeáveis não tem como distinguir "não sobrou nada" de "sobrou, e nós engolimos".
+     *
+     * ENTÃO ELE DIZ O VALOR E A LINHA, E PARA AÍ. Nenhum nome nosso é proposto: `--ds-<algo>`
+     * inventado aqui entraria no código dele sem uma pessoa ter decidido, e este comando roda depois
+     * de CADA escrita do agente - é o pior lugar do produto para inventar vocabulário. A seção 0 da
+     * jornada é literal: sem nome no sistema DELE, o valor fica onde está.
+     */
+    const unnamed = d.findings.filter((f) => !nameToWrite(f));
     const phantoms = d.files.flatMap((f) => f.phantoms ?? []);
     // Every check leaves one line in the ledger - INCLUDING the clean ones,
     // because a fix is itself a write, so the clean re-check of a file that was
@@ -70,21 +84,60 @@ async function report(root, filePath) {
         named: named.length,
         phantoms: phantoms.length,
     });
-    // Unnamed drift alone is deliberately NOT worth interrupting for. There is
-    // no token to move to, so the only honest advice is "ask a person" - and
-    // saying that after every edit trains the reader to skip the block.
-    if (named.length === 0 && phantoms.length === 0)
+    if (named.length === 0 && phantoms.length === 0 && unnamed.length === 0)
         return greet(root, rel);
     // A report IS the evidence the greeting exists to provide, so it counts as the
     // introduction. Otherwise a project whose first file had drift would get the
     // "it is live" sentence afterwards, telling somebody who just watched it work.
     await markGreeted(root);
+    /**
+     * QUANDO NÃO HÁ NADA A FAZER NAQUELE ARQUIVO, O RELATÓRIO É DE DUAS LINHAS - e isto é o que
+     * mantém o comando instalado.
+     *
+     * MEDIDO pela revisão de DX no fecho da etapa 11, rodando o scanner deste binário sobre os 38
+     * arquivos de uma biblioteca real com o vocabulário mais generoso possível (as 94 custom
+     * properties que o próprio repositório declara): **20 arquivos (53%) disparam pelo menos um
+     * achado sem nome, e 18 desses 20 têm ZERO achado nomeado** - o relatório inteiro seria o bloco
+     * novo. O cabeçalho deste arquivo é explícito sobre o risco: *"a hook that speaks on every edit
+     * is noise, and noise is what gets a hook removed"*.
+     *
+     * Então a MESMA informação sai em duas formas. Sozinha, ela é uma frase - o valor, a linha, e a
+     * ação, que é não agir. Ao lado de algo acionável, ela é um bloco, porque aí o contraste com a
+     * seta do bloco de cima é o que ensina a diferença entre os dois conjuntos.
+     *
+     * O que NÃO está resolvido, e é decisão dele: a REPETIÇÃO no tempo. Um valor cuja resposta certa
+     * é "deixe como está" volta a ser dito na próxima escrita naquele arquivo, porque não existe
+     * memória por linha e criar uma é comportamento novo. Está medido em `steps/11-fora-do-escopo.md`.
+     */
+    const sample = unnamed
+        .slice(0, 3)
+        .map((f) => `line ${f.line} ${f.literal}`)
+        .join(", ");
+    if (named.length === 0 && phantoms.length === 0)
+        return [
+            `${rel} - ${unnamed.length} value${unnamed.length === 1 ? "" : "s"} here ${unnamed.length === 1 ? "has" : "have"} no name in this system, and nothing to replace ${unnamed.length === 1 ? "it" : "them"} with: ${sample}${unnamed.length > 3 ? `, +${unnamed.length - 3} more` : ""}.`,
+            "Do not invent a name - leave them, or ask the person what they would call it.",
+        ].join("\n");
     const lines = [`${rel} - checked against ${table.name ?? table.slug}.`];
     if (named.length > 0) {
         lines.push("", "Values written by hand that this system already has a name for:", ...named
             .slice(0, 20)
             .map((f) => `  line ${f.line}  ${f.literal} → ${nameToWrite(f)}`), "", "Replace them now, while you still have this file in mind.");
     }
+    if (unnamed.length > 0) {
+        /**
+         * O TÍTULO CARREGA A PROIBIÇÃO, e não a terceira frase de um parágrafo - achado da revisão de
+         * DX: a lista tinha a MESMA forma da lista acionável de cima (`Values written by hand that…`,
+         * uma linha por achado), e um agente que acabou de aprender *"lista de valores → proponha o
+         * token"* recebia aqui uma lista igual com a única frase que interrompe esse reflexo escondida
+         * no fim.
+         */
+        lines.push("", "Not yet named - do NOT invent a name for these:", ...unnamed.slice(0, 20).map((f) => `  line ${f.line}  ${f.literal}`), 
+        /** O QUE FOI CORTADO É DITO - medido num `.css` real: 20 de 252, e as 232 sumiam caladas. */
+        ...(unnamed.length > 20
+            ? [`  … and ${unnamed.length - 20} more in this file`]
+            : []), "", "This system declares no name for them, so there is nothing to replace them with.", "Leave them as they are, or tell the person the value and what THEY would call it.");
+    }
     if (phantoms.length > 0) {
         lines.push("", "Names this system does not declare. These look tokenized and apply nothing at all:", ...phantoms.slice(0, 20).map((p) => `  line ${p.line}  ${p.name}`), "", "Use a name the system has, or say which value you need and what you would call it. Do NOT invent a token.");
     }

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,37 @@
 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 { installedThemeCss, installedTokensCss, whatOnlyTheSheetResolves, } from "../sheet-needed.js";
 import { inTheirTongue, projectTongue } from "../their-tongue.js";
+import { keptLine, recordWritten, editedHere as theirEdits, } from "../written.js";
+/**
+ * O QUE O ARQUIVO DIZ TAMBÉM É COBRANÇA - e ela é a metade que FICA no repositório dele.
+ *
+ * O DEFEITO, achado pela revisão de DX no fecho da etapa 11: o fecho no terminal parou de mandar
+ * instalar a folha quando a tradução a tornou desnecessária, e o `.tsx` que acabou de ser escrito
+ * continuava abrindo com *"Ensure the DS tokens.css is imported"* e *"Keep the … ds-* classes
+ * (on-system…)"*. O terminal role uma vez; o comentário fica no arquivo que o time dele abre
+ * depois, sem o terminal por perto para desmentir. É a mesma contradição de duas frases que o
+ * critério conserta, um arquivo adiante.
+ *
+ * QUEM SABE A RESPOSTA É ESTE LADO, e é por isso que a linha sai aqui e não no servidor: a
+ * pergunta é *"o REPOSITÓRIO dele ainda precisa da folha?"*, e o codegen do servidor não conhece o
+ * repositório dele. Lá o header é escrito completo, que é a resposta certa para quem não traduziu
+ * nada.
+ *
+ * E O PAR NÃO É VIGIADO POR ACIDENTE: `apps/web/src/lib/ds/the-page-header-can-be-uncharged.spec.ts`
+ * assere que o header do servidor traz exatamente estas duas marcas. Se alguém reescrever a frase
+ * lá, aquele spec fica VERMELHO - em vez de este filtro passar a não casar em silêncio, que é
+ * exatamente como um `replace` por string falha aqui.
+ */
+const SHEET_INSTRUCTION = /tokens\.css is imported|\(on-system/;
+function withoutTheSheetInstruction(code) {
+    return code
+        .split("\n")
+        .filter((line) => !SHEET_INSTRUCTION.test(line))
+        .join("\n");
+}
 /**
  * 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 +57,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
@@ -39,28 +98,84 @@ export async function template(slug, name, opts) {
     let named = 0;
     let inlined = 0;
     const still = new Set();
-    await mkdir(pageDir, { recursive: true });
-    const spokenPage = speak(pageFile.code);
-    if (spokenPage) {
-        named += spokenPage.named;
-        inlined += spokenPage.inlined;
-        for (const l of spokenPage.left)
+    /**
+     * TRADUZ TUDO ANTES DE ESCREVER NADA, porque a pergunta *"esta pagina precisa da nossa folha?"*
+     * se responde sobre os bytes TRADUZIDOS - e a resposta decide o que vai a disco, nao so' o que o
+     * terminal diz.
+     *
+     * A ordem anterior escrevia e depois media. Funcionava enquanto a medicao servia so' ao fecho no
+     * terminal; no momento em que ela passou a decidir uma linha do ARQUIVO, escrever primeiro era
+     * gravar a decisao errada e corrigi-la na frase seguinte.
+     */
+    const pieces = [];
+    const translate = (code) => {
+        const spoken = speak(code);
+        if (!spoken)
+            return code;
+        named += spoken.named;
+        inlined += spoken.inlined;
+        for (const l of spoken.left)
             still.add(l);
+        return spoken.css;
+    };
+    pieces.push({
+        rel: pageRel,
+        filename: pageRel.split(/[\\/]/).pop() ?? pageFile.filename,
+        content: translate(pageFile.code),
+    });
+    for (const f of siblings)
+        pieces.push({
+            rel: join(dirname(pageRel), f.filename),
+            filename: f.filename,
+            content: translate(f.code),
+        });
+    /**
+     * A FOLHA SÓ É COBRADA QUANDO ESTA PÁGINA PRECISA DELA (A2 da etapa 11) - ver
+     * `sheet-needed.ts`, a mesma porta que o `component` usa.
+     *
+     * O DEFEITO, medido em 10/09: o comando já contava em `still` quantas referências sobraram
+     * apontando para a nossa folha depois da tradução, imprimia o número, e três linhas abaixo
+     * mandava instalar a folha e colar um `@import` - inclusive quando o número era ZERO. Uma página
+     * que renderiza igual sem os dois passava a pedi-los, e pedir cria exatamente a dependência que
+     * a plataforma promete não criar: a gente é referência, não dependência.
+     *
+     * E A PERGUNTA É MAIOR QUE `still`, que é por que ela não é feita com ele: a folha entrega as
+     * variáveis, as classes que só o `@theme` gera E as classes das receitas (`.ds-hero`). Uma
+     * página veste as três, e cortar o setup contando só as variáveis entregaria uma página pelada.
+     *
+     * SEM TRADUÇÃO, NADA MUDA: sem o mapa do `.lock` o `--ds-*` cru está no arquivo, a folha é o
+     * caminho, e a cobrança sai inteira como sempre saiu.
+     */
+    const need = tongue
+        ? whatOnlyTheSheetResolves({
+            source: pieces.map((f) => f.content).join("\n"),
+            themeCss: await installedThemeCss(root, slug),
+            sheetCss: await installedTokensCss(root, slug),
+            theirNames: [...tongue.names.values()],
+        })
+        : null;
+    const chargesTheSheet = !need || need.needed;
+    await mkdir(pageDir, { recursive: true });
+    /** OS BYTES QUE FORAM A DISCO, para o fingerprint lembrar EXATAMENTE o que escrevemos. */
+    const landed = [];
+    for (const piece of pieces) {
+        const content = chargesTheSheet
+            ? piece.content
+            : withoutTheSheetInstruction(piece.content);
+        await writeFile(join(root, piece.rel), content, "utf8");
+        landed.push({ filename: piece.filename, content });
+        console.log(piece.rel === pageRel
+            ? `✓ wrote ${piece.rel}  (${slug} v${generated.version})`
+            : `✓ wrote ${piece.rel}`);
     }
-    await writeFile(join(root, pageRel), spokenPage ? spokenPage.css : pageFile.code, "utf8");
-    console.log(`✓ wrote ${pageRel}  (${slug} v${generated.version})`);
-    for (const f of siblings) {
-        const rel = join(dirname(pageRel), f.filename);
-        const spoken = speak(f.code);
-        if (spoken) {
-            named += spoken.named;
-            inlined += spoken.inlined;
-            for (const l of spoken.left)
-                still.add(l);
-        }
-        await writeFile(join(root, rel), spoken ? spoken.css : f.code, "utf8");
-        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) {
@@ -72,8 +187,28 @@ export async function template(slug, name, opts) {
     console.log("Next steps:");
     console.log(`  • use it in a route, e.g. ${join(config.pagesDir, "page.tsx")}:`);
     console.log(`      import Page from "@/${defaultDir.replace(/\\/g, "/")}/${pageFile.filename.replace(/\.tsx$/, "")}";`);
-    console.log(`  • ensure the DS is installed: synthesisui add ${slug} (provides tokens.css)`);
-    console.log(`  • @import "_synthesisui/ds/${slug}/tokens.css" in your global CSS`);
+    if (chargesTheSheet) {
+        /** E ELE DIZ O QUE PEDE A FOLHA - um setup cobrado sem motivo dito ensina a ignorar o próximo. */
+        if (need)
+            console.log(`  • what still needs the sheet here: ${[...need.recipeClasses, ...need.classes, ...need.variables].slice(0, 3).join(", ")}`);
+        console.log(`  • ensure the DS is installed: synthesisui add ${slug} (provides tokens.css)`);
+        console.log(`  • @import "_synthesisui/ds/${slug}/tokens.css" in your global CSS`);
+    }
+    else {
+        console.log(`  • nothing to install: every value in this page is a name YOUR code declares, so it renders without our stylesheet`);
+    }
     console.log("  • refine the file: wire real data, split into components, swap placeholders");
-    console.log(`  • keep the data-ds="${slug}" wrapper and the ds-* / layout classes (stays on-system)`);
+    /**
+     * E A LINHA DO ESCOPO SÓ SAI ONDE ELA É VERDADE - medido rodando o comando em 10/09.
+     *
+     * Ela mandava *"keep the data-ds wrapper and the ds-* classes (stays on-system)"* sempre, e no
+     * caminho isolado a saída ficava contradizendo a linha logo acima: *"nothing to install… it
+     * renders without our stylesheet"* e, uma linha depois, uma instrução para manter um escopo que
+     * não resolve nada naquele arquivo. É o mesmo defeito que este bloco existe para consertar - duas
+     * frases que não podem ser verdadeiras ao mesmo tempo -, e a medição já responde qual das duas é:
+     * chegar aqui com `chargesTheSheet` falso significa zero variável nossa e zero classe nossa no
+     * que acabou de ser escrito.
+     */
+    if (chargesTheSheet)
+        console.log(`  • keep the data-ds="${slug}" wrapper and the ds-* / layout classes (stays on-system)`);
 }

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/doctor/ci-format.js

@@ -23,7 +23,7 @@
  * checagem que telefona para casa é uma checagem que alguém desinstala.
  */
 import { isOlderCli } from "../cli-version.js";
-import { CHECKER_SINCE } from "../install-marks.js";
+import { COUNTED_DIFFERENTLY, COUNTED_DIFFERENTLY_SINCE, } from "../install-marks.js";
 const byFileOf = (d) => {
     const out = {};
     for (const f of d.files)
@@ -75,10 +75,12 @@ export function compareToBaseline(d, base, now) {
      * prometia o contrário desde o primeiro dia (*"um número que sobe porque o leitor melhorou não é
      * regressão"*), e `incomparable` existia para exatamente isto.
      *
-     * A RÉGUA É A MARCA QUE JÁ EXISTE: `CHECKER_SINCE` é a última versão em que a leitura que o CI
-     * compara mudou de resposta, e ela sobe no mesmo PR que muda a leitura. Nada de limiar novo.
+     * A RÉGUA É `COUNTED_DIFFERENTLY_SINCE`, em `install-marks.ts`: a última versão em que a CONTAGEM
+     * que o CI compara mudou de resposta. Ela mora na casa das outras marcas porque é lá que está a
+     * disciplina de mantê-las - uma marca à mão sem portão é uma marca errada esperando a hora -, e
+     * não é a MESMA das outras: emprestar `CHECKER_SINCE` foi exatamente o defeito que a criou.
      */
-    const readerMoved = base.cli !== undefined && isOlderCli(base.cli, CHECKER_SINCE);
+    const readerMoved = base.cli !== undefined && isOlderCli(base.cli, COUNTED_DIFFERENTLY_SINCE);
     return {
         worse: !scopeChanged &&
             !readerMoved &&
@@ -95,7 +97,7 @@ export function compareToBaseline(d, base, now) {
             }
             : readerMoved
                 ? {
-                    incomparable: `the baseline was written by CLI ${base.cli}, and this run counts every length in a shorthand - that version counted only the first. The rise is in the reading, not in your code. Rewrite the line before comparing: npx synthesisui doctor --write-baseline`,
+                    incomparable: `the baseline was written by CLI ${base.cli}, and ${COUNTED_DIFFERENTLY}. The rise is in the reading, not in your code. Rewrite the line before comparing: npx synthesisui doctor --write-baseline`,
                 }
                 : {}),
     };

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.
  *
@@ -258,7 +275,37 @@ export const MATERIALISER_SINCE = "0.16.403";
  * não via, 14% e 16% das declarações de espaço/raio. Um hook pinado antes desta versão aconselha
  * MENOS, que é a régua desta marca.
  */
-export const CHECKER_SINCE = "0.16.408";
+/**
+ * A ÚLTIMA VERSÃO EM QUE A CONTAGEM QUE O CI COMPARA MUDOU DE RESPOSTA - a régua da catraca, e ela
+ * mora aqui porque é onde a disciplina mora.
+ *
+ * ELA ERA `CHECKER_SINCE`, e as duas perguntas não são a mesma. Aquela significa *"o que o hook
+ * ENTREGA mudou"*, e sobe também quando ele passa a DIZER algo novo sobre os mesmos achados - o que
+ * aconteceu em 10/09. Com a régua emprestada, aquela subida declararia INCOMPARÁVEL todo baseline
+ * gravado entre as duas versões: a catraca pararia de reprovar regressão de verdade até o time
+ * regravar a linha, e a frase abaixo diria a ele um motivo que não é o dele. Foi o caso negativo do
+ * `doctor/ci-format.spec.ts` que acendeu isso, sozinho.
+ *
+ * A PERGUNTA DO PASSO 1 GANHA UMA SEGUNDA METADE por causa dela, e as duas se fazem no mesmo
+ * vermelho do fingerprint do CHECKER (que já inclui `doctor/scan.ts`, quem conta):
+ *
+ *     o hook aconselha diferente?  -> `CHECKER_SINCE`
+ *     a CONTAGEM mudou de valor?   -> `COUNTED_DIFFERENTLY_SINCE`, e a FRASE junto
+ *
+ * A frase viaja ao lado da versão porque as duas são uma coisa só: quem move a marca troca a
+ * explicação no mesmo lugar, em vez de deixar o CI citando a causa da marca anterior.
+ */
+export const COUNTED_DIFFERENTLY_SINCE = "0.16.408";
+export const COUNTED_DIFFERENTLY = "this run counts every length in a shorthand - that version counted only the first";
+/**
+ * 0.16.408 -> 0.16.413 em 10/09: o hook passa a DIZER o valor que nada nomeia. Ele silenciava toda
+ * deriva sem token de destino - a decisão estava escrita como "não vale interromper, porque o único
+ * conselho honesto é pergunte a uma pessoa" -, e o silêncio é a única resposta errada disponível:
+ * quem lê um relatório que só fala de valores nomeáveis não distingue "não sobrou nada" de "sobrou,
+ * e nós engolimos". Agora sai `line 12  #ff00aa`, sem uma única proposta de nome nosso. Um hook
+ * pinado antes desta versão aconselha MENOS, que é a régua desta marca.
+ */
+export const CHECKER_SINCE = "0.16.413";
 /**
  * A ÚLTIMA VERSÃO EM QUE OS LEITORES PASSARAM A PRODUZIR UM CENSO DIFERENTE.
  *

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/sheet-needed.js

@@ -1,6 +1,74 @@
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { TAILWIND_THEME_VARS } from "./tailwind-theme-vars.js";
+/**
+ * AS CLASSES QUE A FOLHA COMPILADA DECLARA COMO RECEITA - o nome, não o prefixo.
+ *
+ * A convenção viaja com o sistema (`ds-`, `sui-`, o que o projeto dele usa), então perguntar pelo
+ * prefixo seria fixar a forma de um repositório. O que é estrutural é onde a regra MORA: o
+ * compilador emite uma regra por receita dentro de `@layer components`, e é só essa camada que a
+ * folha traz e o projeto dele não tem.
+ *
+ * A PRIMEIRA VERSÃO VARRIA O TEXTO INTEIRO, e a revisão do fecho mediu o preço na folha viva do
+ * `codelevel` (143.409 bytes, versão instalada): **147 nomes extraídos, 3 deles não são receita** -
+ * `dark`, que é a classe DELE em `@layer base`; `layer-3d`, um utilitário DELE espelhado em
+ * `@layer utilities`; e `background`, que aparecia como VALOR de uma declaração e nem seletor era.
+ * Rodada sobre o repositório dele, a função devolvia `["layer-3d", "dark"]` - duas classes DELE
+ * sustentando a cobrança da NOSSA folha. É o defeito de 07/09 voltando pela porta do balde novo, e
+ * o oposto exato do que esta medição existe para permitir.
+ *
+ * O ESCAPE CONTA como parte do nome, porque no CSS ele é como se escreve um caractere que o
+ * seletor não aceita cru: `.ds-w-\[10px\]` é a classe `ds-w-[10px]`, e `.sm\:ds-hero` é a variante
+ * `sm:` da classe `ds-hero` - que é como o código dele a escreve. Truncar no `\` produziria os
+ * nomes `ds-w-` e `sm`, que ninguém escreve: uma dependência real deixaria de ser contada, e esse é
+ * o único lado do erro que o cabeçalho deste módulo declara inaceitável.
+ */
+export function classesTheSheetDeclares(css) {
+    const out = new Set();
+    for (const body of layerBodies(css, "components"))
+        for (const prelude of selectorPreludes(body))
+            for (const m of prelude.matchAll(/\.((?:\\.|[\w-])+)/g)) {
+                const bare = m[1].replace(/\\(.)/g, "$1");
+                /** A MESMA normalização que `classesIn` aplica ao que ele ESCREVE - `sm:ds-hero` é `ds-hero`. */
+                out.add((bare.split(":").pop() ?? bare).replace(/^[!-]/, ""));
+            }
+    return [...out];
+}
+/** O corpo de cada `@layer <nome> { … }`, com as chaves de dentro contadas. */
+function layerBodies(css, name) {
+    const out = [];
+    for (const m of css.matchAll(new RegExp(`@layer\\s+${name}\\s*\\{`, "g"))) {
+        let depth = 1;
+        let i = (m.index ?? 0) + m[0].length;
+        const start = i;
+        for (; i < css.length && depth > 0; i += 1) {
+            const c = css[i];
+            if (c === "{")
+                depth += 1;
+            else if (c === "}")
+                depth -= 1;
+        }
+        out.push(css.slice(start, i - 1));
+    }
+    return out;
+}
+/**
+ * O PRELÚDIO DE CADA REGRA - o texto entre o fim da regra anterior e a `{` desta.
+ *
+ * É o que separa um SELETOR de um valor de declaração: `background: p.background` mora depois da
+ * `{`, e nunca chega aqui. Um prelúdio que começa com `@` é uma regra de agrupamento (`@media`,
+ * `@supports`) e não declara classe nenhuma - o corpo dela é varrido pela mesma volta do laço.
+ */
+function selectorPreludes(body) {
+    const out = [];
+    const parts = body.split("{");
+    for (const part of parts.slice(0, -1)) {
+        const tail = part.slice(part.lastIndexOf("}") + 1).trim();
+        if (tail && !tail.startsWith("@"))
+            out.push(tail);
+    }
+    return out;
+}
 /** `--animate-shimmer` no `@theme` -> o nome `shimmer`, que é o que uma classe carrega. */
 function themeNames(themeCss) {
     const out = new Set();
@@ -207,14 +275,33 @@ export function whatOnlyTheSheetResolves(input) {
     const classes = [
         ...new Set([...written].filter((c) => names.some((n) => c === n || c.endsWith(`-${n}`)))),
     ];
+    /** As classes que a folha declara e que ESTE texto veste - ver `recipeClasses`. */
+    const declared = new Set(classesTheSheetDeclares(input.sheetCss));
+    const recipeClasses = [
+        ...new Set([...written].filter((c) => declared.has(c))),
+    ];
     return {
         variables,
         classes,
-        needed: variables.length > 0 || classes.length > 0,
+        recipeClasses,
+        needed: variables.length > 0 || classes.length > 0 || recipeClasses.length > 0,
     };
 }
+/** A folha compilada da versão instalada - as receitas moram nela, não no `theme.css`. */
+export async function installedTokensCss(root, slug) {
+    return installedSheet(root, slug, "tokens.css");
+}
 /** O `theme.css` da versão instalada - a folha da raiz é um re-export de uma linha. */
 export async function installedThemeCss(root, slug) {
+    return installedSheet(root, slug, "theme.css");
+}
+/**
+ * UM ARQUIVO DA VERSÃO PINADA - o `.lock` diz qual é, e a folha da raiz é um re-export de uma linha.
+ *
+ * Uma leitura só para as duas folhas: duas cópias da mesma decisão de versão é a forma de uma delas
+ * ficar atrás no dia em que o formato do `.lock` mudar.
+ */
+async function installedSheet(root, slug, filename) {
     const dir = join(root, "_synthesisui", "ds", slug);
     const lock = await readFile(join(dir, ".lock"), "utf8").catch(() => null);
     let version = 0;
@@ -226,5 +313,5 @@ export async function installedThemeCss(root, slug) {
             version = 0;
         }
     }
-    return readFile(join(dir, `v${version}`, "theme.css"), "utf8").catch(() => "");
+    return readFile(join(dir, `v${version}`, filename), "utf8").catch(() => "");
 }

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.413",
   "description": "Bring SynthesisUI design systems into any project - tokens, typed components, whole pages and an agent-ready CLAUDE.md manifest.",
   "type": "module",
   "bin": {