synthesisui 0.16.421 → 0.16.423

package/dist/commands/component.js

@@ -7,14 +7,12 @@ import { readProjectConfig, resolveRegistry } from "../config.js";
 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 { findCollision, reactMajorOf, readInstalledConvention, readInstalledScheme, theirThemeVars, } from "../project-facts.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, 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";
 /**
  * Writes the shared `cn.ts` next to the components, built from THIS project's
@@ -72,18 +70,6 @@ export function localName(blueprint, asked) {
  * The component's styles reference the DS tokens, so the system itself must be
  * installed (`synthesisui add <slug>`) for `tokens.css`/`theme.css` to resolve.
  */
-/**
- * O QUE NESTE ARQUIVO PRECISA DA FOLHA, dito uma vez.
- *
- * A frase aparece nos três desfechos do bloco de setup (está aí · está no repo · falta), e três
- * redações da mesma medição são três respostas no dia em que uma for editada.
- */
-function whatNeedsIt(need) {
-    const some = (list) => `${list.slice(0, 3).join(", ")}${list.length > 3 ? `, +${list.length - 3}` : ""}`;
-    return need.variables.length > 0
-        ? some(need.variables)
-        : `the ${some(need.classes)} ${need.classes.length === 1 ? "utility" : "utilities"}`;
-}
 export async function component(slug, name, opts) {
     const base = resolveRegistry(opts.registry);
     const root = opts.dir ?? process.cwd();
@@ -130,19 +116,12 @@ export async function component(slug, name, opts) {
      * 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.
+     * sempre. O `catch` mantem o comportamento antigo - sem traducao, e o relato abaixo DIZ que nada
+     * foi traduzido, em vez de deixar a pessoa descobrir pela cor que nao apareceu.
      */
     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)
@@ -157,13 +136,6 @@ export async function component(slug, name, opts) {
      * sai no fim - depois da linha que nomeia o que foi escrito.
      */
     let spoken = null;
-    /**
-     * OS BYTES QUE FORAM A DISCO - é sobre ELES que a pergunta "precisa da folha?" se responde.
-     *
-     * Pela mesma razão que `spoken` é preenchido em cada caminho de escrita: perguntar sobre o
-     * recipe, ou sobre o css antes da tradução, seria responder sobre um arquivo que ninguém abriu.
-     */
-    let writtenSource = "";
     /**
      * O VEREDITO DA RAIZ - ver `GeneratedRoot` em `component-codegen.ts`.
      *
@@ -181,7 +153,6 @@ export async function component(slug, name, opts) {
         const sheet = tongue ? inTheirTongue(res.css, tongue) : null;
         if (sheet)
             spoken = sheet;
-        writtenSource = sheet ? sheet.css : res.css;
         await writeFile(join(dir, `${res.name}.css`), `${sheet ? sheet.css : res.css}\n`, "utf8");
         console.log(`✓ ${res.name} → _synthesisui/ds/${slug}/components/${res.name}.{json,css}  (${slug} v${res.version})`);
     }
@@ -380,7 +351,6 @@ export async function component(slug, name, opts) {
             ];
             for (const f of written)
                 await writeFile(join(compDir, f.filename), f.content, "utf8");
-            writtenSource = written.map((f) => f.content).join("\n");
             /** O fingerprint do que escrevemos - é o que protege a edição dele no upgrade (T7). */
             await recordWritten(join(root, "_synthesisui", "ds", slug), local, written);
             filenames = written.map((f) => f.filename);
@@ -405,7 +375,17 @@ export async function component(slug, name, opts) {
              * O ARQUIVO e o EXPORT levam o nome dele; a CLASSE continua sendo a do blueprint. Um
              * `<CardPreview>` vestindo `.ds-card` está estilizado certo e não faz sombra em nada dele.
              */
-            local, await readInstalledScheme(root, slug), tongue, await installedThemeVars(root, slug));
+            local, await readInstalledScheme(root, slug), tongue, 
+            /**
+             * AS PASTAS DE APP, para a resposta ser a INTERSEÇÃO delas - ver `theirThemeVars`.
+             *
+             * Um componente materializado vai para uma pasta que num monorepo os dois apps importam, e
+             * ele não sabe em qual será usado. Varrer da raiz faria o `@theme` do app A responder por
+             * um componente escrito no app B: emitimos `bg-brand`, aquele app não gera a classe, e a
+             * propriedade renderiza NADA - pior que o valor arbitrário, porque nada falta na tela. É a
+             * mesma lição de `INV-VOLTA-12`, que saiu com a instrução de import e não com a topologia.
+             */
+            await theirThemeVars(root, await detectAppDirs(root, config.pagesDir)));
             spoken = said;
             root_ = generatedRoot;
             /**
@@ -430,7 +410,6 @@ export async function component(slug, name, opts) {
             }));
             for (const f of written)
                 await writeFile(join(compDir, f.filename), f.content, "utf8");
-            writtenSource = written.map((f) => f.content).join("\n");
             await recordWritten(join(root, "_synthesisui", "ds", slug), local, written);
             if (flavour === "tailwind")
                 await writeCn(root, compDir, slug);
@@ -449,11 +428,37 @@ export async function component(slug, name, opts) {
      * pergunta é uma: o que foi escrito ainda precisa da nossa folha? Enquanto isto era calculado
      * antes da materialização, a resposta descrevia outro arquivo.
      */
+    /**
+     * `left` É A FALHA, E ELE SAI PRIMEIRO - fora de qualquer condição sobre o que deu certo.
+     *
+     * O DEFEITO QUE ISTO CONSERTA, achado pela revisão de QA do fecho: este aviso estava ANINHADO em
+     * `named > 0 || inlined > 0`. O caso em que ele mais importa é justamente o que zera os dois - uma
+     * folha instalada de versão anterior, que não declara a variável que o componente novo usa. Ali
+     * `named=0`, `inlined=0`, `left=["--ds-…"]`, o byte com a nossa grafia ia para o repositório dele,
+     * e o terminal não dizia uma palavra: o ramo `else if (!tongue)` também não pega, porque o
+     * vocabulário EXISTE.
+     *
+     * É o skew de versão que `component-codegen.ts` já documenta como tendo acontecido, e a lei 8 na
+     * forma mais cara dela - a lacuna calada no único momento em que a lacuna é real.
+     */
+    if (spoken && spoken.left.length > 0)
+        console.log(`  ${spoken.left.length} value${spoken.left.length === 1 ? "" : "s"} the system declares no value for (${spoken.left.slice(0, 3).join(", ")}${spoken.left.length > 3 ? ", …" : ""}) - ${spoken.left.length === 1 ? "that declaration is" : "those declarations are"} dropped by the browser. Run \`npx synthesisui upgrade ${slug}\` to re-read the system; if it persists, please report it.`);
     if (spoken && (spoken.named > 0 || spoken.inlined > 0)) {
         console.log(`  ${spoken.named} reference${spoken.named === 1 ? "" : "s"} now speak${spoken.named === 1 ? "s" : ""} the name YOUR code gives the value${spoken.inlined > 0 ? `, and ${spoken.inlined} carr${spoken.inlined === 1 ? "ies" : "y"} the value because your code names no token for it` : ""}.`);
-        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"}.`);
+        if (spoken.left.length === 0)
+            console.log(`  Nothing in what was just written points at us - every value is a name YOUR code declares, or the value itself.`);
+        /**
+         * O QUE CONGELOU ENTRE OS ESQUEMAS - ver `Tongue.frozen`, e é lei 8 na forma mais barata dela.
+         *
+         * Um valor que muda com o tema e que o código dele não nomeia sai como o literal do esquema
+         * base: renderiza certo hoje, e não vira quando ele alterna. É o tipo de coisa que ele nota na
+         * tela e não tem como explicar - e nomear aquele valor no próprio vocabulário é o conserto, que
+         * é decisão dele.
+         *
+         * MEDIDO em 11/09 na folha do `codelevel`: 3 de 119.
+         */
+        if (spoken.froze > 0)
+            console.log(`  ${spoken.froze} of ${spoken.froze === 1 ? "those changes" : "those change"} with the colour scheme, and ${spoken.froze === 1 ? "it is" : "they are"} written here as the value of the resting one - so ${spoken.froze === 1 ? "it does" : "they do"} not flip when the scheme does. Name ${spoken.froze === 1 ? "it" : "them"} in your own code and the next run writes your name instead.`);
         /**
          * E DIZER DE ONDE VEIO O VOCABULARIO, quando o sistema NAO esta' instalado aqui.
          *
@@ -464,179 +469,56 @@ export async function component(slug, name, opts) {
          */
         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.
+         * E POR QUE NENHUM NOME DELE ENTROU, quando nenhum entrou - lei 8, e a causa tem conserto.
          *
-         * 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.
+         * `their-vars.ts` recusa todo par que o BUILD dele não emite, por desenho: um nome afirmado sem
+         * prova pinta a cor errada no dia em que ele o renomear. Num clone fresco isso é o caso normal,
+         * e o efeito é um arquivo inteiro de valores literais - que funciona, e que perde a ligação com
+         * as decisões dele.
          *
-         * 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.
+         * A frase que este ramo substituiu dizia *"nada foi traduzido"*, e ela era verdade quando a
+         * tradução dependia do mapa. Desde 11/09 a folha responde sozinha: sempre há tradução, e o que
+         * varia é se ela achou NOMES dele ou só valores.
          */
-        /**
-         * 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.`);
+        if (spoken.named === 0 && spoken.inlined > 0) {
+            const noBuild = (await resolvableVars(root)) === null;
+            console.log(noBuild
+                ? `  None of them is a name yet: 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 again - the file then speaks your own names.`
+                : `  None of them is a name yet: your code names none of the values this system declares. The values above work as they are; naming one is yours to decide.`);
+        }
     }
-    // ── DX: concrete paths + copy-pasteable snippets, with breathing room ──
-    const tailwind = flavour === "tailwind";
-    const imports = tailwind
-        ? [
-            `@import "tailwindcss";`,
-            `@import "../_synthesisui/ds/${slug}/tokens.css";`,
-            `@import "../_synthesisui/ds/${slug}/theme.css";`,
-        ]
-        : [`@import "../_synthesisui/ds/${slug}/tokens.css";`];
-    /**
-     * O SETUP SÓ É COBRADO QUANDO ESTE ARQUIVO PRECISA DELE - ver `sheet-needed.ts`.
-     *
-     * O DEFEITO, apontado pelo dono olhando a própria tela (07/09): o comando terminava dizendo
-     * *"No variable in what was just written points at our stylesheet"* e, três linhas abaixo,
-     * imprimia **One-time setup** mandando colar dois `@import`. As duas frases não podem ser
-     * verdadeiras ao mesmo tempo, e a segunda pedia uma dependência de runtime para um arquivo que
-     * não a usa.
-     *
-     * A VERSÃO ANTERIOR DESTE BLOCO já tinha visto metade do problema e parou na metade: manteve o
-     * setup e acrescentou *"o que estes imports ainda trazem são os utilitários do sistema e o
-     * movimento"*. A razão é real - `INV-VOLTA-13` deixa no `@theme` os nomes que só o sistema tem -
-     * mas ela era AFIRMADA, nunca medida. No `codelevel` aquele `@theme` declara 50 variáveis, todas
-     * `--animate-*` e `--max-width-*`, e o componente gerado não veste nenhuma delas: as duas
-     * animações que ele usa são declaradas pelo `globals.css` DELE.
-     *
-     * Então a pergunta passa a ser feita: sobrou variável nossa, ou classe que só o nosso `@theme`
-     * gera? Se nenhuma das duas, o arquivo está isolado e o bloco diz isso - com o que o import ainda
-     * daria, para a escolha continuar sendo dele.
-     */
-    const need = whatOnlyTheSheetResolves({
-        source: writtenSource,
+    else if (!tongue) {
         /**
-         * O `@theme` DO SISTEMA - do disco quando ele instalou, do registry quando nao.
+         * NEM A FOLHA VEIO - e desde 11/09 é a ÚNICA causa que resta para não haver tradução.
          *
-         * 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.
+         * A pasta não existe e a leitura do registry não chegou: rede fora, sessão ausente, sistema
+         * privado. O arquivo sai com a nossa grafia porque não há de onde tirar nem nome nem valor, e
+         * isso SE DIZ - a pessoa abre o arquivo, vê variáveis que o `globals.css` dela não declara, e a
+         * única forma de descobrir por que a cor não apareceu seria ler o nosso código.
          *
-         * 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.
+         * As outras duas causas que este ramo distinguia - o build ausente e o código que não nomeia
+         * nada - deixaram de impedir a tradução, e viraram a linha logo acima.
          */
-        sheetCss: "",
-    });
-    if (!need.needed) {
-        console.log(section("This file needs nothing else"));
-        console.log(body("Every variable and class in it is declared by your own code - no import, no scope"));
-        console.log(body("attribute, nothing at runtime. It is yours."));
-        console.log("");
-        console.log(body(`The system stays what it is here: the reference your agent reads to build ON it.`));
-        console.log(body(`If you later want the utilities only its own @theme generates, that is when`));
-        console.log(body(`importing earns its place - and \`doctor\` says so.`));
+        console.log(`  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`);
     }
     /**
-     * E O "USE IT" SAI NOS DOIS CAMINHOS - a primeira versão disto era um `return`, e ela levava
-     * junto a única linha que diz COMO importar o componente. Dizer "está isolado" e sonegar o
-     * `import { ButtonSample }` troca um defeito por outro.
-     */
-    /**
-     * A FIAÇÃO JÁ ESTÁ AQUI? - ver `wiring-read.ts`, a MESMA leitura que o `doctor` usa.
+     * E NÃO HÁ SETUP A PEDIR - `INV-GERAL-13`, e este bloco tinha 120 linhas até 11/09.
      *
-     * MEDIDO em 08/09, nos dois apps do ato 2B: com os dois `@import` colados e o
-     * `data-ds="<slug>"` no `<body>`, este comando ainda imprimia os passos 1 e 2 para colar de
-     * novo. Ele perguntava se o arquivo PRECISA da folha e nunca se a folha já estava lá.
+     * O QUE ELE FAZIA: media se o arquivo recém-escrito ainda apontava para a nossa folha e, quando
+     * sim, imprimia **One-time setup** com dois `@import` e um `data-ds` para colar. O dono leu isso
+     * na própria tela e a frase dele fecha o assunto: *"isso nunca deve acontecer, a gente havia
+     * combinado (...) garanta que nunca mais você irá falar desse import e nem solicitar e nem
+     * precisar nos projetos"*.
      *
-     * As duas perguntas continuam sendo feitas, e nesta ordem: `need` decide se o setup é
-     * necessário, `wiring` decide se ele ainda está pendente.
-     */
-    const wiring = need.needed ? await readWiring(root, slug) : null;
-    /**
-     * O ADAPTADOR CONTA quando o que precisa da folha são UTILITÁRIOS - eles só existem pelo
-     * `@theme` do `theme.css`. Dizer "está tudo aí" com o `tokens.css` sozinho declararia resolvido
-     * exatamente o que continua faltando.
-     */
-    const sheetsThere = wiring?.imported === true && (!tailwind || wiring?.themed === true);
-    /**
-     * E A RESPOSTA É DO PROJETO, NÃO DO APP - então num repositório com mais de um app ela não
-     * decide, e o comando diz isso em vez de afirmar (`INV-VOLTA-12`: monorepo é a forma comum).
+     * O QUE MATOU A PERGUNTA foi a causa, não o texto. Nenhuma variável nossa chega ao arquivo
+     * (`speak`), e nenhum utilitário nomeado depende do nosso `@theme` (`theirThemeVars`). Não sobra
+     * nada para uma folha nossa resolver - então não há o que perguntar, e a leitura da fiação
+     * (`readWiring`, `sheet-needed.ts`) saiu junto com a cobrança.
      *
-     * `readWiring` varre a partir da raiz e responde "existe, em algum lugar daqui". Com dois apps
-     * servidos, um fiado e o outro não, um responderia pelo outro - e o arquivo que este comando
-     * acabou de escrever vai para uma pasta só de componentes, que não desambigua qual app o usa.
+     * O relatório da tradução, logo acima, é o que substitui: ele diz o que aconteceu com os bytes
+     * que foram a disco, e o que sobrou quando algo sobrou.
      */
-    const appDirs = await detectAppDirs(root, config.pagesDir ?? "app");
-    const oneApp = appDirs.length <= 1;
-    const alreadyWired = sheetsThere && wiring?.scoped === true;
-    if (need.needed && alreadyWired && !oneApp) {
-        console.log(section(`This file needs the sheet - and this repo has it`));
-        console.log(body(`What needs it: ${whatNeedsIt(need)}.`));
-        console.log(body(`Measured across this repository, not per app: ${slug}'s sheet is imported and`));
-        console.log(body(`data-ds="${slug}" is set somewhere in it. There ${appDirs.length === 2 ? "are two apps" : `are ${appDirs.length} apps`} here (${appDirs.slice(0, 2).join(", ")}${appDirs.length > 2 ? ", …" : ""}),`));
-        console.log(body(`so if this file lands in one that does not carry them, run \`doctor\` inside it.`));
-    }
-    if (need.needed && alreadyWired && oneApp) {
-        console.log(section(`This file needs the sheet - and it is already there`));
-        console.log(body(`What needs it: ${whatNeedsIt(need)}.`));
-        console.log(body(`This project already imports ${slug}'s ${tailwind ? "tokens.css and theme.css" : "tokens.css"} and carries data-ds="${slug}",`));
-        console.log(body(wiring?.fontsMapped
-            ? `and its type is mapped onto the system's family tokens. Nothing to set up.`
-            : `so nothing to set up here. \`doctor\` says whether the type is mapped too.`));
-    }
-    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)`));
-        console.log("");
-        console.log(body(`1. Import the design system in your GLOBAL stylesheet, e.g. app/globals.css`));
-        console.log(body(`   (the path is relative to that file - hence the leading ../):`));
-        console.log("");
-        console.log(snippet(imports));
-        console.log("");
-        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>`]));
-        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).
      *
@@ -709,11 +591,24 @@ export async function component(slug, name, opts) {
         ]));
     }
     else {
-        console.log(snippet([
-            `@import "../_synthesisui/ds/${slug}/components/${res.name}.css";`,
-            "",
-            `<div class="ds-${res.name}">…</div>`,
-        ]));
+        /**
+         * O CAMINHO DOS ARTEFATOS NÃO MANDA IMPORTAR DA NOSSA PASTA - `INV-GERAL-13`, 11/09.
+         *
+         * A instrução era `@import "../_synthesisui/ds/<slug>/components/<name>.css"`, e ela criava
+         * exatamente a dependência que esta etapa fechou: a folha dele passava a apontar para dentro da
+         * nossa pasta, e o build dele quebrava no dia em que aquela pasta mudasse de nome ou saísse do
+         * versionamento (é o defeito medido em 24/08, com `Can't resolve` e exit code 1).
+         *
+         * O ARQUIVO JÁ É DELE, e é isso que torna a resposta simples: ele passou pela porta de tradução
+         * um pouco acima, então cada valor nele é um nome que o código dele declara ou o valor em si.
+         * Copiá-lo para onde as folhas dele vivem não perde nada, e o que fica em `_synthesisui/` segue
+         * sendo a nossa referência.
+         */
+        console.log(body("The stylesheet above already speaks your vocabulary -"));
+        console.log(body("copy it next to the markup that uses it, wherever your"));
+        console.log(body("stylesheets live. Nothing of ours has to be loaded:"));
+        console.log("");
+        console.log(snippet([`<div class="ds-${res.name}">…</div>`]));
     }
     console.log("");
 }

package/dist/commands/connect.js

@@ -39,6 +39,26 @@ import { installedSlugs } from "./sync.js";
  * um cliente que rodou `connect` há um mês não sabe que o nome mudou.
  */
 const LEGACY_SKILLS = ["import-design-system"];
+/**
+ * SKILLS QUE SAÍRAM DO PRODUTO - e a régua aqui é o OPOSTO da de cima.
+ *
+ * `LEGACY_SKILLS` é renomeação: o mesmo playbook mudou de nome, e apagar a pasta antiga é o conserto
+ * porque a nova ocupa o lugar dela. Aqui o playbook deixou de existir, e não há substituto - então a
+ * regra é a que ele fixou em 10/09 sobre os agentes: **desmarcar nunca apaga, mas NOMEIA o que
+ * ficou**. Uma pasta que some sozinha de `.claude/skills/` do repositório dele é a plataforma
+ * editando o repositório de alguém sem pedir.
+ *
+ * `sui-configure-ds` existia para uma coisa só: *"set up an installed design system in the app so
+ * its tokens actually reach the browser - the stylesheet import"*. Nada no app dele carrega nada
+ * nosso (`INV-GERAL-13`), então ela não tem mais objeto - e um agente que a invocar hoje vai
+ * executar um playbook que pede exatamente o que o produto promete nunca pedir.
+ */
+const RETIRED_SKILLS = [
+    {
+        dir: "sui-configure-ds",
+        why: "retired - nothing of ours loads in your app any more",
+    },
+];
 /**
  * OS ARQUIVOS DO INSTALL, PÔSTOS EM DIA COM ESTE CLI.
  *
@@ -566,6 +586,27 @@ export async function connect(opts) {
         await rm(dir, { recursive: true, force: true }).catch(() => { });
         row(true, `✕ /${legacy.padEnd(21)} ${say("removed - renamed to /sui-import-ds")}`);
     }
+    /**
+     * A SKILL APOSENTADA É NOMEADA, e o arquivo fica - ver `RETIRED_SKILLS`.
+     *
+     * Com o caminho literal, porque uma linha que diz *"uma skill saiu"* devolve a ele o trabalho de
+     * procurar qual (pedido dele, 09/09). Só aparece para quem TEM o arquivo: avisar sobre uma pasta
+     * que nunca existiu é ruído.
+     */
+    for (const retired of RETIRED_SKILLS) {
+        const path = join(".claude", "skills", retired.dir, "SKILL.md");
+        if (!(await exists(join(root, path))))
+            continue;
+        /**
+         * O CAMINHO VAI NO `under` DA MESMA LINHA, e não numa linha própria.
+         *
+         * `row(false, …)` não IMPRIME: ele entra na contagem de *"N outras peças já atuais"*, que é o
+         * mecanismo que mantém a tela curta. Uma segunda chamada para o caminho fazia a linha da skill
+         * sair sem ele - exatamente o *"uma linha que espera ele e não diz ONDE"* que o formato de
+         * resposta proíbe. Medido rodando o comando: a prova de A6 pegou.
+         */
+        row(true, `✕ /${retired.dir.padEnd(21)} ${say(retired.why)}`, `${say("it stays in your repo - yours to delete")}: ${path}`);
+    }
     /** Se ALGUMA skill mudou nesta rodada - é o que autoriza a frase da sessão nova a citá-las. */
     let skillsMoved = false;
     for (const skill of skills) {